@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/guides/accessibility.mdx

@@ -0,0 +1,550 @@
+---
+sidebar_position: 8
+title: Accessibility
+---
+
+# Accessibility
+
+OGrid is built with accessibility as a core principle, meeting WCAG 2.1 AA standards. All components support keyboard navigation, screen readers, and high contrast modes.
+
+## WCAG 2.1 AA Compliance
+
+OGrid implements the following WCAG 2.1 AA guidelines:
+
+### Perceivable
+
+- **1.3.1 Info and Relationships** — Semantic HTML (`<table>`, `<thead>`, `<tbody>`, `<th>`, `<td>`) with proper ARIA roles
+- **1.4.1 Use of Color** — Focus indicators use both color and visible outlines (2px solid)
+- **1.4.3 Contrast (Minimum)** — All text and interactive elements meet 4.5:1 contrast ratio
+- **1.4.11 Non-text Contrast** — Focus indicators and UI components meet 3:1 contrast
+
+### Operable
+
+- **2.1.1 Keyboard** — All functionality available via keyboard
+- **2.1.2 No Keyboard Trap** — Focus can always escape modal dialogs and popovers
+- **2.4.3 Focus Order** — Logical tab order through interactive elements
+- **2.4.7 Focus Visible** — `:focus-visible` styles on all interactive elements
+
+### Understandable
+
+- **3.2.1 On Focus** — No unexpected context changes when elements receive focus
+- **3.2.2 On Input** — No automatic context changes during user input
+- **3.3.2 Labels or Instructions** — All form controls have associated `<label>` elements
+
+### Robust
+
+- **4.1.2 Name, Role, Value** — All UI components use proper ARIA attributes
+- **4.1.3 Status Messages** — ARIA live regions announce dynamic content changes
+
+## Keyboard Navigation
+
+OGrid provides Excel-style keyboard navigation for all grid interactions.
+
+### Arrow Key Navigation
+
+| Key | Action |
+|-----|--------|
+| `↑` `↓` `←` `→` | Move active cell one cell in the direction pressed |
+| `Ctrl+↑` / `Ctrl+↓` | Jump to first/last row in current column |
+| `Ctrl+←` / `Ctrl+→` | Jump to first/last column in current row |
+| `Home` | Jump to first column in current row |
+| `End` | Jump to last column in current row |
+| `Ctrl+Home` | Jump to first cell (top-left) |
+| `Ctrl+End` | Jump to last cell (bottom-right) |
+
+### Selection
+
+| Key | Action |
+|-----|--------|
+| `Shift+↑` `↓` `←` `→` | Extend cell selection range |
+| `Shift+Home` | Extend selection to first column |
+| `Shift+End` | Extend selection to last column |
+| `Shift+Ctrl+Home` | Extend selection to top-left corner |
+| `Shift+Ctrl+End` | Extend selection to bottom-right corner |
+| `Ctrl+A` | Select all cells |
+| `Space` (on checkbox column) | Toggle row selection |
+
+### Editing
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Start editing active cell (if editable) |
+| `F2` | Start editing active cell (if editable) |
+| `Escape` | Cancel editing and revert changes |
+| `Enter` (while editing) | Commit changes and move down |
+| `Tab` (while editing) | Commit changes and move right |
+| `Shift+Tab` (while editing) | Commit changes and move left |
+
+### Clipboard
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+C` / `Cmd+C` | Copy selected cells |
+| `Ctrl+X` / `Cmd+X` | Cut selected cells |
+| `Ctrl+V` / `Cmd+V` | Paste clipboard content |
+| `Delete` | Clear selected cells |
+
+### Undo/Redo
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+Z` / `Cmd+Z` | Undo last edit |
+| `Ctrl+Y` / `Cmd+Shift+Z` | Redo last undone edit |
+
+### Context Menu
+
+| Key | Action |
+|-----|--------|
+| `Shift+F10` | Open context menu for active cell |
+| `Escape` | Close context menu |
+| `↑` `↓` | Navigate menu items |
+| `Enter` | Execute selected menu item |
+
+### Column Headers
+
+| Key | Action |
+|-----|--------|
+| `Enter` / `Space` | Toggle sort on focused column header |
+| `Tab` | Move focus to next interactive element (sort/filter buttons) |
+| `Shift+Tab` | Move focus to previous interactive element |
+
+### Pagination
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Navigate between pagination buttons and page size dropdown |
+| `Enter` / `Space` | Activate focused button |
+| `←` `→` | Navigate page number buttons |
+
+### Column Chooser
+
+| Key | Action |
+|-----|--------|
+| `Enter` / `Space` | Open/close column chooser dropdown |
+| `↑` `↓` | Navigate column list |
+| `Space` | Toggle column visibility |
+| `Escape` | Close dropdown |
+
+### Filters
+
+| Key | Action |
+|-----|--------|
+| `Enter` / `Space` | Open filter popover |
+| `Tab` | Navigate filter inputs |
+| `Enter` | Apply filter |
+| `Escape` | Close filter popover |
+
+## ARIA Attributes
+
+OGrid uses comprehensive ARIA attributes for screen reader support.
+
+### DataGridTable
+
+```html
+<div role="grid" aria-label="Product catalog" aria-rowcount="1000">
+  <table>
+    <thead>
+      <tr role="row">
+        <th role="columnheader" aria-sort="ascending" scope="col">
+          Product Name
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr role="row" aria-rowindex="1">
+        <td role="gridcell" tabindex="-1">Widget</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+| Attribute | Element | Purpose |
+|-----------|---------|---------|
+| `role="grid"` | Grid wrapper | Identifies the grid container |
+| `role="row"` | `<tr>` | Identifies table rows |
+| `role="columnheader"` | `<th>` | Identifies column headers |
+| `role="gridcell"` | `<td>` | Identifies data cells |
+| `aria-label` | Grid wrapper | Provides accessible name for the grid |
+| `aria-rowcount` | Grid wrapper | Total number of rows (server-side pagination) |
+| `aria-rowindex` | `<tr>` | Row's position in the full dataset (1-indexed) |
+| `aria-sort` | `<th>` | Current sort state (`"ascending"`, `"descending"`, `"none"`) |
+| `aria-colindex` | `<th>`, `<td>` | Column's position (1-indexed) |
+| `tabindex="-1"` | `<td>` | Enables programmatic focus for keyboard navigation |
+
+### StatusBar
+
+```html
+<div role="status" aria-live="polite">
+  <span>Rows: 1,000</span>
+  <span>Selected: 5</span>
+</div>
+```
+
+| Attribute | Purpose |
+|-----------|---------|
+| `role="status"` | Identifies status information |
+| `aria-live="polite"` | Announces changes when user is idle (non-intrusive) |
+
+### PaginationControls
+
+```html
+<nav role="navigation" aria-label="Pagination">
+  <button aria-label="First page" aria-disabled="true">«</button>
+  <button aria-label="Previous page" aria-disabled="true">‹</button>
+  <button aria-label="Page 1" aria-current="page">1</button>
+  <button aria-label="Page 2">2</button>
+  <button aria-label="Next page">›</button>
+  <button aria-label="Last page">»</button>
+</nav>
+```
+
+| Attribute | Purpose |
+|-----------|---------|
+| `role="navigation"` | Identifies pagination controls |
+| `aria-label="Pagination"` | Provides context for screen readers |
+| `aria-label` (buttons) | Descriptive labels for icon-only buttons |
+| `aria-current="page"` | Identifies the current page |
+| `aria-disabled` | Indicates disabled state |
+
+### ColumnChooser
+
+```html
+<button aria-expanded="false" aria-haspopup="listbox">
+  Column Visibility (3 of 5)
+</button>
+<div role="dialog" aria-label="Column visibility">
+  <input type="checkbox" id="col-name" />
+  <label for="col-name">Product Name</label>
+</div>
+```
+
+| Attribute | Purpose |
+|-----------|---------|
+| `aria-expanded` | Indicates dropdown open/closed state |
+| `aria-haspopup="listbox"` | Indicates the button triggers a listbox |
+| `role="dialog"` | Identifies the dropdown as a dialog |
+| `aria-label="Column visibility"` | Provides context for the dialog |
+
+### ColumnHeaderFilter
+
+```html
+<th scope="col">
+  <button aria-label="Sort by Product Name, currently unsorted">
+    Product Name
+  </button>
+  <button aria-label="Filter Product Name" aria-expanded="false">
+    ▼
+  </button>
+</th>
+```
+
+| Attribute | Purpose |
+|-----------|---------|
+| `scope="col"` | Associates header with its column |
+| `aria-label` (sort button) | Describes current sort state |
+| `aria-label` (filter button) | Describes filter action |
+| `aria-expanded` | Indicates filter popover open/closed state |
+
+### Editable Cells
+
+```html
+<td role="gridcell" aria-readonly="false" tabindex="-1">
+  <input aria-label="Edit Product Name" />
+</td>
+```
+
+| Attribute | Purpose |
+|-----------|---------|
+| `aria-readonly="false"` | Indicates cell is editable |
+| `aria-label` (input) | Provides context for screen readers |
+
+## Screen Reader Support
+
+OGrid is tested with the following screen readers:
+
+- **NVDA** (Windows) — Latest version
+- **JAWS** (Windows) — Latest version
+- **VoiceOver** (macOS) — Built-in
+- **Narrator** (Windows) — Built-in
+- **TalkBack** (Android) — Built-in
+
+### Announcements
+
+Screen readers announce the following information:
+
+#### Grid Navigation
+
+- **Cell activation:** "Product Name, cell, row 1, column 2"
+- **Sort change:** "Sorted by Product Name, ascending"
+- **Filter applied:** "Filtered by Status, 3 results"
+- **Selection:** "5 rows selected"
+
+#### Editing
+
+- **Edit mode:** "Editing Product Name, row 1, column 2"
+- **Value changed:** "Product Name changed from Widget to Gadget"
+- **Validation error:** "Invalid value: Price must be a positive number"
+
+#### Pagination
+
+- **Page change:** "Showing 21 to 40 of 250 rows, page 2 of 13"
+- **Page size change:** "Page size changed to 50 rows per page"
+
+#### Column Visibility
+
+- **Column hidden:** "Product Name column hidden"
+- **Column shown:** "Product Name column shown"
+
+## Focus Management
+
+OGrid implements advanced focus management for optimal keyboard experience.
+
+### Focus Visible
+
+All interactive elements use `:focus-visible` (not `:focus`) to show focus indicators only when navigating via keyboard, not when clicking with a mouse.
+
+```scss
+.dataTable tbody tr {
+  outline: none;
+
+  &:focus-visible {
+    outline: 2px solid var(--ogrid-accent, #0078d4);
+    outline-offset: -2px;
+  }
+}
+```
+
+### Focus Trap
+
+Modal dialogs and popovers trap focus within their boundaries:
+- `Tab` cycles through interactive elements inside the dialog
+- `Shift+Tab` cycles backwards
+- `Escape` closes the dialog and returns focus to the trigger element
+
+### Focus Restoration
+
+When closing dialogs, popovers, or exiting edit mode:
+- Focus returns to the element that triggered the action
+- Active cell focus is restored after pagination or sorting
+
+## High Contrast Mode
+
+OGrid supports Windows High Contrast Mode and other forced color schemes.
+
+### Custom Properties
+
+All colors use CSS custom properties with fallbacks:
+
+```css
+--ogrid-bg: #ffffff;              /* Background */
+--ogrid-fg: #242424;              /* Foreground text */
+--ogrid-border: #e0e0e0;          /* Borders */
+--ogrid-accent: #0078d4;          /* Focus indicators, primary actions */
+--ogrid-bg-subtle: #f3f2f1;       /* Header background */
+```
+
+### High Contrast Support
+
+In high contrast mode:
+- Focus indicators use system colors (`Highlight`, `HighlightText`)
+- Borders use system colors (`ButtonText`, `GrayText`)
+- Icons and text remain visible
+
+## Accessible Usage Examples
+
+### Basic Accessible Grid
+
+```tsx
+
+function AccessibleGrid() {
+  return (
+    <OGrid
+      data={products}
+      columns={columns}
+      getRowId={(item) => item.id}
+      aria-label="Product catalog"
+      rowSelection="multiple"
+      editable={true}
+    />
+  );
+}
+```
+
+### With Descriptive Labels
+
+```tsx
+
+function GridWithLabels() {
+  return (
+    <div>
+      <h2 id="product-grid-heading">Product Catalog</h2>
+      <p id="product-grid-description">
+        Browse and manage your product inventory. Use arrow keys to navigate,
+        Enter to edit, and Space to select rows.
+      </p>
+      <OGrid
+        data={products}
+        columns={columns}
+        getRowId={(item) => item.id}
+        aria-labelledby="product-grid-heading"
+        aria-describedby="product-grid-description"
+      />
+    </div>
+  );
+}
+```
+
+### Announcing Status Changes
+
+```tsx
+
+function GridWithAnnouncements() {
+  const [announcement, setAnnouncement] = useState('');
+
+  const handleSelectionChange = (event) => {
+    const count = event.selectedRowIds.length;
+    setAnnouncement(`${count} ${count === 1 ? 'row' : 'rows'} selected`);
+  };
+
+  return (
+    <>
+      <div role="status" aria-live="polite" className="sr-only">
+        {announcement}
+      </div>
+      <OGrid
+        data={products}
+        columns={columns}
+        getRowId={(item) => item.id}
+        rowSelection="multiple"
+        onSelectionChange={handleSelectionChange}
+      />
+    </>
+  );
+}
+```
+
+### Screen Reader Only Text
+
+Use a `.sr-only` class for screen reader only content:
+
+```css
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border-width: 0;
+}
+```
+
+## Testing Accessibility
+
+### Automated Testing
+
+Use automated accessibility testing tools:
+
+```bash
+# Install axe-core for automated testing
+npm install --save-dev @axe-core/react
+
+# Install jest-axe for Jest integration
+npm install --save-dev jest-axe
+```
+
+```tsx
+
+expect.extend(toHaveNoViolations);
+
+test('OGrid has no accessibility violations', async () => {
+  const { container } = render(
+    <OGrid
+      data={products}
+      columns={columns}
+      getRowId={(item) => item.id}
+      aria-label="Product catalog"
+    />
+  );
+
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+### Manual Testing
+
+1. **Keyboard Navigation**
+   - Disconnect your mouse
+   - Navigate the entire grid using only keyboard
+   - Verify all features are accessible
+
+2. **Screen Reader Testing**
+   - Enable VoiceOver (macOS: `Cmd+F5`) or NVDA (Windows)
+   - Navigate the grid and verify announcements
+   - Test editing, filtering, and selection
+
+3. **High Contrast Mode**
+   - Windows: `Alt+Left Shift+Print Screen`
+   - Verify all content is visible
+   - Check focus indicators are clear
+
+4. **Zoom Testing**
+   - Zoom to 200% (`Ctrl++` or `Cmd++`)
+   - Verify layout remains usable
+   - No horizontal scrolling on text content
+
+### Checklist
+
+Use this checklist when building accessible grids:
+
+- [ ] Grid has `aria-label` or `aria-labelledby`
+- [ ] All interactive elements are keyboard accessible
+- [ ] Focus indicators are visible (`:focus-visible`)
+- [ ] Column headers have `scope="col"`
+- [ ] Sorted columns have `aria-sort` attribute
+- [ ] Edit mode inputs have descriptive `aria-label`
+- [ ] Status changes are announced (ARIA live regions)
+- [ ] High contrast mode is supported
+- [ ] Tested with screen reader
+- [ ] Automated accessibility tests pass
+
+## Known Limitations
+
+### Virtual Scrolling
+
+When virtual scrolling is enabled (`virtualScroll.enabled: true`), screen readers may not announce the total row count accurately because only visible rows are rendered in the DOM. Use `aria-rowcount` on the grid wrapper to communicate the full dataset size.
+
+### Large Datasets
+
+For grids with 10,000+ rows, consider server-side pagination instead of client-side filtering to improve screen reader performance.
+
+### Custom Cell Renderers
+
+When using custom `renderCell` functions, ensure your custom markup:
+- Includes appropriate ARIA attributes
+- Maintains keyboard navigability
+- Announces changes to screen readers
+
+## Resources
+
+- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+- [ARIA Authoring Practices Guide - Grid Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/)
+- [WebAIM Screen Reader Testing](https://webaim.org/articles/screenreader_testing/)
+- [axe DevTools Browser Extension](https://www.deque.com/axe/devtools/)
+
+## Support
+
+If you encounter accessibility issues or have suggestions for improvements:
+
+1. Check the [GitHub Issues](https://github.com/alaarab/ogrid/issues) for known issues
+2. Report new issues with:
+   - Browser and screen reader versions
+   - Steps to reproduce
+   - Expected vs. actual behavior
+3. Tag issues with `accessibility` label
+
+We're committed to maintaining WCAG 2.1 AA compliance and improving accessibility based on user feedback.

package/bundled-docs/guides/controlled-vs-uncontrolled.mdx

@@ -0,0 +1,153 @@
+---
+sidebar_position: 1
+title: Controlled vs Uncontrolled
+description: Choose between letting OGrid manage state internally or owning it yourself.
+---
+
+# Controlled vs Uncontrolled
+
+OGrid supports both **uncontrolled** and **controlled** state patterns for every stateful feature -- sorting, filtering, pagination, column visibility, row selection, and column order. You can also mix and match, controlling some features while leaving others to the grid.
+
+## Uncontrolled (Zero Config)
+
+In uncontrolled mode, OGrid manages all state internally. Just pass your columns and data:
+
+```tsx
+
+const columns = [
+  { columnId: 'name', name: 'Name', sortable: true },
+  { columnId: 'email', name: 'Email', filterable: { type: 'text' as const } },
+  { columnId: 'role', name: 'Role' },
+];
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(item) => item.id}
+      defaultPageSize={25}
+      defaultSortBy="name"
+      defaultSortDirection="asc"
+    />
+  );
+}
+```
+
+The grid handles sorting, filtering, pagination, and everything else on its own. Use the `default*` props to set initial values.
+
+## Controlled (You Own the State)
+
+In controlled mode, you pass the current value and an `onChange` callback for each feature you want to control. This is useful when you need to sync grid state with a URL, persist it to storage, or coordinate with other components.
+
+```tsx
+
+function App() {
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(25);
+  const [sort, setSort] = useState({ field: 'name', direction: 'asc' as const });
+  const [filters, setFilters] = useState<IFilters>({});
+
+  // Sync to URL, localStorage, or server on every change
+  const handleFiltersChange = (newFilters: IFilters) => {
+    setFilters(newFilters);
+    saveToUrl(newFilters);
+  };
+
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(item) => item.id}
+      page={page}
+      onPageChange={setPage}
+      pageSize={pageSize}
+      onPageSizeChange={setPageSize}
+      sort={sort}
+      onSortChange={setSort}
+      filters={filters}
+      onFiltersChange={handleFiltersChange}
+    />
+  );
+}
+```
+
+## Partial Control
+
+You do not have to control everything. Control only the features you need -- the rest stays uncontrolled:
+
+```tsx
+function App() {
+  // Only control sort; filters, pagination, etc. are managed by the grid
+  const [sort, setSort] = useState({ field: 'name', direction: 'asc' as const });
+
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(item) => item.id}
+      sort={sort}
+      onSortChange={setSort}
+      defaultPageSize={50}
+    />
+  );
+}
+```
+
+## Controllable Prop Pairs
+
+Every stateful feature follows the same pattern: a value prop and an `onChange` callback. When both are provided, the grid operates in controlled mode for that feature. When neither is provided, the grid manages it internally.
+
+| Feature | Value Prop | Callback Prop | Default Prop |
+|---------|-----------|---------------|-------------|
+| Sort | `sort` | `onSortChange` | `defaultSortBy`, `defaultSortDirection` |
+| Filters | `filters` | `onFiltersChange` | -- |
+| Page | `page` | `onPageChange` | -- |
+| Page size | `pageSize` | `onPageSizeChange` | `defaultPageSize` |
+| Visible columns | `visibleColumns` | `onVisibleColumnsChange` | -- |
+| Selected rows | `selectedRows` | `onSelectionChange` | -- |
+| Column order | `columnOrder` | `onColumnOrderChange` | -- |
+
+:::tip
+When using controlled mode, always pass **both** the value and the callback. Passing only the value without a callback will lock the feature in its initial state, since OGrid will not be able to update it.
+:::
+
+## Imperative API
+
+For cases where you need to read or set state programmatically (e.g., a "Reset Filters" button), use the grid API ref:
+
+```tsx
+
+function App() {
+  const gridRef = useRef<IOGridApi<Person>>(null);
+
+  const handleReset = () => {
+    gridRef.current?.setFilterModel({});
+    gridRef.current?.deselectAll();
+  };
+
+  return (
+    <>
+      <button onClick={handleReset}>Reset</button>
+      <OGrid
+        ref={gridRef}
+        columns={columns}
+        data={people}
+        getRowId={(item) => item.id}
+      />
+    </>
+  );
+}
+```
+
+The API ref works in both controlled and uncontrolled mode. See the [Grid API reference](../api/grid-api) for the full list of methods.
+
+## When to Use Which
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Simple table, no external state needed | Uncontrolled |
+| URL-driven filters or sort | Controlled (filters, sort) |
+| Persist column layout to localStorage | Controlled (visibleColumns, columnOrder) + `getColumnState()` |
+| Server-side data with `dataSource` | Controlled or uncontrolled -- both work with `dataSource` |
+| Coordinate multiple grids | Controlled (shared state between grids) |