docs(grid): enhance README with detailed usage, options, and accessib…

[blunteshwar]

Overview

This PR reorganizes the grid README.md to follow the established documentation standards structure, improving accessibility and consistency with other components.

Changes Made

Structure Reorganization

• Overview: Replaced "Description" with "Overview" section and expanded component description to better explain its role as a virtualized grid component
• Usage: Updated import code blocks with proper language syntax highlighting (bash, javascript)
• Anatomy: Added new section describing the component's key parts:
  • Virtualized container
  • Grid items rendered via renderItem
  • Roving tabindex system
  • Configurable layout properties
• Options: Created comprehensive properties documentation including:
  • items property with array examples
  • renderItem method with detailed explanation
  • itemSize property with object configuration
  • gap property for spacing control
  • focusableSelector property for keyboard navigation
• Behaviors: Added new section documenting:
  • Virtualization behavior and performance benefits
  • Focus management with roving tabindex pattern
  • Selection management with code examples
• Accessibility: Enhanced accessibility section with:
  • Keyboard navigation details with <kbd> tags
  • ARIA attributes documentation and examples
  • Focusable elements guidance
• Example: Retained existing comprehensive example at the end

Content Improvements

• Enhanced component description to clarify its relationship with lit-virtualizer
• Added documentation for all key properties (items, renderItem, itemSize, gap, focusableSelector)
• Provided JavaScript code examples for programmatic interaction
• Included detailed explanation of virtualization benefits
• Added selection management examples showing state handling
• Documented roving tabindex pattern with keyboard interaction details

Accessibility Enhancements

• Clarified keyboard navigation using the roving tabindex pattern
• Documented all necessary ARIA attributes for grid implementation
• Explained focus management for keyboard users
• Added proper semantic markup guidance with <kbd> tags for keyboard actions
• Included comprehensive ARIA attributes examples for both grid and items

Testing

• Verified all existing content is preserved
• Confirmed proper markdown syntax and formatting
• Checked consistency with documentation standards
• Reviewed accessibility improvements
• Ensured code blocks use proper language highlighting

Related Documentation

• Follows structure outlined in Adding a Component Documentation Standards
• Maintains consistency with accordion, button, meter, progress bar, progress circle, tooltip, and color-area README files
• References documentation structure from the adding-a-component guide

Documentation Standards Compliance

This reorganization ensures the grid documentation:

• Uses proper heading structure for organization and navigation
• Maintains consistent main headings (level 2 and 3) across components
• Uses <kbd> tags to semantically indicate keyboard input
• Provides accessible code examples
• Includes comprehensive accessibility section with ARIA guidance
• Uses sentence case for all headings
• Follows plain language principles for better understanding

This reorganization makes the grid documentation more accessible, easier to navigate, and consistent with the established documentation standards across the Spectrum Web Components library.

[changeset-bot]

⚠️ No Changeset found

Latest commit: a627684

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

📚 Branch Preview

• Documentation Site
• Storybook

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-5810

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

[github-actions]

Tachometer results

Currently, no packages are changed by this PR...

[coveralls]

Pull Request Test Coverage Report for Build 18681605860

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 97.966%

---

Totals
Change from base Build 18666105226:	0.0%
Covered Lines:	34247
Relevant Lines:	34776

---

💛 - Coveralls

[nikkimk]

LGTM.

[rubencarvalho]

Thanks! Left just 1 non-blocking comment

[rubencarvalho]

Unrelated to your changes, but do you know if this @todo is still relevant?

[blunteshwar]

I think after merging this PR we can get rid of this Todo