@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/api/components-datagrid-table.mdx

@@ -0,0 +1,316 @@
+---
+sidebar_position: 10
+title: DataGridTable
+---
+
+# DataGridTable
+
+The core data grid component that renders the table structure, headers, rows, cells, and inline editing UI. `DataGridTable` is typically used internally by `OGrid`, but can also be used standalone for custom layouts.
+
+## Import
+
+
+<Tabs groupId="framework">
+<TabItem value="react" label="React">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="angular" label="Angular">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="vue" label="Vue">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="js" label="Vanilla JS">
+
+```typescript
+// DataGridTable is an internal component of OGrid in vanilla JS
+```
+
+</TabItem>
+</Tabs>
+
+## Props (React)
+
+`DataGridTable` receives `IOGridDataGridProps<T>` which includes:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `T[]` | **Required** | Array of data items to render (paginated subset). |
+| `columns` | `(IColumnDef<T> \| IColumnGroupDef<T>)[]` | **Required** | Column definitions (flat or grouped). |
+| `getRowId` | `(item: T) => RowId` | **Required** | Function to extract a unique ID from each row item. |
+| `sortBy` | `string` | `undefined` | Currently sorted column ID. |
+| `sortDirection` | `'asc' \| 'desc'` | `undefined` | Sort direction. |
+| `onSortChange` | `(field: string, direction: 'asc' \| 'desc') => void` | `undefined` | Callback when user clicks a sortable column header. |
+| `filters` | `IFilters` | `{}` | Active filter values (column ID → FilterValue). |
+| `onFiltersChange` | `(filters: IFilters) => void` | `undefined` | Callback when filters are applied or cleared. |
+| `visibleColumns` | `Set<string>` | All columns | Set of visible column IDs. |
+| `onVisibilityChange` | `(columnId: string, visible: boolean) => void` | `undefined` | Callback when column visibility changes. |
+| `onSetVisibleColumns` | `(columns: Set<string>) => void` | `undefined` | Bulk-set all visible columns (used by Select All / Clear All). |
+| `editable` | `boolean` | `false` | Enable inline cell editing. |
+| `cellSelection` | `boolean` | `true` | Enable spreadsheet-like cell selection (active cell, range, fill handle, clipboard). |
+| `onCellValueChanged` | `(event: ICellValueChangedEvent<T>) => void` | `undefined` | Callback when a cell value is committed after edit. |
+| `rowSelection` | `RowSelectionMode` | `'none'` | Row selection mode: `'none'`, `'single'`, or `'multiple'`. |
+| `selectedRows` | `Set<RowId>` | `new Set()` | Set of selected row IDs. |
+| `onSelectionChange` | `(event: IRowSelectionChangeEvent<T>) => void` | `undefined` | Callback when row selection changes. |
+| `showRowNumbers` | `boolean` | `false` | Show Excel-style row numbers column at the start (1, 2, 3...). |
+| `statusBar` | `boolean \| IStatusBarProps` | `false` | Show status bar below the grid with row counts and aggregations. |
+| `emptyState` | `{ message?: ReactNode; render?: () => ReactNode }` | `undefined` | Custom empty state when no rows are available. |
+| `density` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Cell spacing/padding preset. |
+| `suppressHorizontalScroll` | `boolean` | `false` | Suppress horizontal scrolling (overflow-x hidden). |
+| `virtualScroll` | `IVirtualScrollConfig` | `undefined` | Enable virtual scrolling for large datasets. |
+| `columnReorder` | `boolean` | `false` | Enable drag-and-drop column reordering. |
+| `dataSource` | `IDataSource<T>` | `undefined` | Server-side data source (for filter options and people search). |
+| `onCellError` | `(error: Error, errorInfo: ErrorInfo) => void` | `undefined` | Error boundary callback for cell rendering errors. |
+| `aria-label` | `string` | `undefined` | Accessible label for the grid. |
+| `aria-labelledby` | `string` | `undefined` | ID of element that labels the grid. |
+
+## Usage
+
+### Basic Example (React)
+
+```tsx
+
+interface Product {
+  id: number;
+  name: string;
+  price: number;
+}
+
+const columns: IColumnDef<Product>[] = [
+  { columnId: 'name', name: 'Product Name', type: 'text' },
+  { columnId: 'price', name: 'Price', type: 'numeric' },
+];
+
+const data: Product[] = [
+  { id: 1, name: 'Widget', price: 29.99 },
+  { id: 2, name: 'Gadget', price: 49.99 },
+];
+
+function MyGrid() {
+  return (
+    <DataGridTable
+      items={data}
+      columns={columns}
+      getRowId={(item) => item.id}
+      aria-label="Product catalog"
+    />
+  );
+}
+```
+
+### With Sorting and Filtering (React)
+
+```tsx
+
+function MyGrid() {
+  const [sortBy, setSortBy] = useState<string>('name');
+  const [sortDirection, setSortDirection] = useState<'asc' | 'desc'>('asc');
+  const [filters, setFilters] = useState<IFilters>({});
+
+  const handleSortChange = (field: string, direction: 'asc' | 'desc') => {
+    setSortBy(field);
+    setSortDirection(direction);
+  };
+
+  return (
+    <DataGridTable
+      items={data}
+      columns={columns}
+      getRowId={(item) => item.id}
+      sortBy={sortBy}
+      sortDirection={sortDirection}
+      onSortChange={handleSortChange}
+      filters={filters}
+      onFiltersChange={setFilters}
+    />
+  );
+}
+```
+
+## Angular Usage
+
+In Angular Material/Radix packages, `DataGridTable` accepts a single `propsInput` property:
+
+```typescript
+
+@Component({
+  selector: 'app-my-grid',
+  standalone: true,
+  imports: [DataGridTableComponent],
+  template: `
+    <ogrid-datagrid-table [propsInput]="gridProps" />
+  `
+})
+export class MyGridComponent {
+  ogridService = new OGridService<Product>();
+  gridProps = this.ogridService.getDataGridProps();
+}
+```
+
+In Angular PrimeNG, `DataGridTable` uses individual `@Input()` properties matching the React prop names.
+
+## Vue Usage
+
+In Vue Vuetify/PrimeVue packages, `DataGridTable` accepts a single `:grid-props` prop:
+
+```vue
+<template>
+  <DataGridTable :grid-props="gridProps" />
+</template>
+
+<script setup lang="ts">
+
+const { dataGridProps: gridProps } = useOGrid({ /* ... */ });
+</script>
+```
+
+In Vue Radix, `DataGridTable` uses individual props via `defineProps<IOGridProps>()` (like React).
+
+## Accessibility
+
+`DataGridTable` implements WCAG 2.1 AA standards with comprehensive keyboard navigation and screen reader support.
+
+### ARIA Attributes
+
+The grid uses semantic HTML with proper ARIA roles:
+
+```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 for screen readers |
+| `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 (pass via `aria-label` prop) |
+| `aria-rowcount` | Grid wrapper | Total number of rows in dataset (server-side pagination) |
+| `aria-rowindex` | `<tr>` | Row's position in the full dataset (1-indexed) |
+| `aria-sort` | `<th>` | Current sort state: `"ascending"`, `"descending"`, or `"none"` |
+| `aria-colindex` | `<th>`, `<td>` | Column's position (1-indexed) |
+| `tabindex="-1"` | `<td>` | Enables programmatic focus for keyboard navigation |
+| `aria-readonly` | `<td>` | Indicates whether cell is editable (`"false"` when `editable: true`) |
+
+### Keyboard Navigation
+
+Complete Excel-style keyboard navigation:
+
+**Arrow Keys:**
+- `↑` `↓` `←` `→` — Move active cell one cell in the direction pressed
+- `Ctrl+↑` / `Ctrl+↓` — Jump to first/last row
+- `Ctrl+←` / `Ctrl+→` — Jump to first/last column
+- `Home` / `End` — Jump to start/end of row
+- `Ctrl+Home` / `Ctrl+End` — Jump to first/last cell in grid
+
+**Selection:**
+- `Shift+Arrows` — Extend cell selection range
+- `Ctrl+A` — Select all cells
+- `Space` (on checkbox column) — Toggle row selection
+
+**Editing:**
+- `Enter` or `F2` — Start editing active cell
+- `Escape` — Cancel editing and revert
+- `Enter` (while editing) — Commit and move down
+- `Tab` (while editing) — Commit and move right
+
+**Clipboard:**
+- `Ctrl+C` / `Cmd+C` — Copy selected cells
+- `Ctrl+X` / `Cmd+X` — Cut selected cells
+- `Ctrl+V` / `Cmd+V` — Paste
+- `Delete` — Clear selected cells
+
+**Undo/Redo:**
+- `Ctrl+Z` / `Cmd+Z` — Undo last edit
+- `Ctrl+Y` / `Cmd+Shift+Z` — Redo
+
+**Context Menu:**
+- `Shift+F10` — Open context menu for active cell
+
+See the [Accessibility Guide](/docs/guides/accessibility) for complete keyboard shortcuts.
+
+### Focus Management
+
+- **Focus visible:** `:focus-visible` styles show a 2px solid outline (`--ogrid-accent`) only when navigating via keyboard
+- **Focus restoration:** After closing dialogs or exiting edit mode, focus returns to the active cell
+- **Tab order:** Logical tab order through interactive elements (header buttons, editable cells)
+
+### Screen Reader Support
+
+Screen readers announce:
+- **Cell navigation:** "Product Name, cell, row 1, column 2"
+- **Sort changes:** "Sorted by Product Name, ascending"
+- **Edit mode:** "Editing Product Name, row 1, column 2"
+- **Value changes:** "Product Name changed from Widget to Gadget"
+
+Tested with NVDA, JAWS, VoiceOver, and Narrator.
+
+### High Contrast Mode
+
+All colors use CSS custom properties with system color fallbacks for Windows High Contrast Mode:
+- Focus indicators use system `Highlight` color
+- Borders use system `ButtonText` color
+- Text remains visible in all contrast themes
+
+### Usage Example
+
+```tsx
+
+function AccessibleGrid() {
+  return (
+    <OGrid
+      data={products}
+      columns={columns}
+      getRowId={(item) => item.id}
+      aria-label="Product catalog"
+      rowSelection="multiple"
+      editable={true}
+    />
+  );
+}
+```
+
+For complete accessibility documentation, see the [Accessibility Guide](/docs/guides/accessibility).
+
+## Related Components
+
+- [OGrid](./ogrid-props.mdx) — Top-level wrapper that includes toolbar and pagination
+- [ColumnHeaderFilter](./components-column-header-filter.mdx) — Column filtering UI
+- [StatusBar](./components-status-bar.mdx) — Status bar below the grid
+- [PaginationControls](./components-pagination-controls.mdx) — Pagination UI
+
+## See Also
+
+- [Column Definition](./column-def.mdx) — Complete column definition reference
+- [Grid API](./grid-api.mdx) — Imperative grid API reference
+- [Accessibility Guide](/docs/guides/accessibility) — Complete accessibility documentation

package/bundled-docs/api/components-pagination-controls.mdx

@@ -0,0 +1,344 @@
+---
+sidebar_position: 13
+title: PaginationControls
+---
+
+# PaginationControls
+
+A pagination UI component that displays page navigation buttons, current page info, and a page size dropdown. Supports first/last page buttons, previous/next buttons, and numbered page buttons with ellipsis for large page counts.
+
+## Import
+
+
+<Tabs groupId="framework">
+<TabItem value="react" label="React">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="angular" label="Angular">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="vue" label="Vue">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="js" label="Vanilla JS">
+
+```typescript
+// PaginationControls is an internal component in vanilla JS
+```
+
+</TabItem>
+</Tabs>
+
+## Props (React)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `currentPage` | `number` | **Required** | Current page number (1-indexed). |
+| `pageSize` | `number` | **Required** | Number of items per page. |
+| `totalCount` | `number` | **Required** | Total number of items across all pages. |
+| `onPageChange` | `(page: number) => void` | **Required** | Callback when user navigates to a different page. |
+| `onPageSizeChange` | `(pageSize: number) => void` | **Required** | Callback when user changes the page size. |
+| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | Available page size options in the dropdown. |
+| `entityLabelPlural` | `string` | `'rows'` | Plural label for items (e.g., `'products'`, `'users'`). |
+| `className` | `string` | `undefined` | Additional CSS class for the root element. |
+
+## Usage
+
+### Basic Example (React)
+
+```tsx
+
+function MyApp() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [pageSize, setPageSize] = useState(20);
+  const totalCount = 250; // Total items
+
+  return (
+    <PaginationControls
+      currentPage={currentPage}
+      pageSize={pageSize}
+      totalCount={totalCount}
+      onPageChange={setCurrentPage}
+      onPageSizeChange={setPageSize}
+    />
+  );
+}
+```
+
+**Output:**
+```
+Showing 21 to 40 of 250 rows
+« ‹ [1] [2] ... [13] › »
+Page size: [20 ▼]
+```
+
+### With Custom Entity Label (React)
+
+```tsx
+
+function ProductGrid() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [pageSize, setPageSize] = useState(50);
+  const totalCount = 1500;
+
+  return (
+    <PaginationControls
+      currentPage={currentPage}
+      pageSize={pageSize}
+      totalCount={totalCount}
+      onPageChange={setCurrentPage}
+      onPageSizeChange={setPageSize}
+      entityLabelPlural="products"
+    />
+  );
+}
+```
+
+**Output:**
+```
+Showing 1 to 50 of 1,500 products
+```
+
+### With Custom Page Size Options (React)
+
+```tsx
+
+function MyApp() {
+  return (
+    <PaginationControls
+      currentPage={1}
+      pageSize={25}
+      totalCount={500}
+      onPageChange={() => {}}
+      onPageSizeChange={() => {}}
+      pageSizeOptions={[25, 50, 100, 250]}
+    />
+  );
+}
+```
+
+## Angular Usage
+
+In Angular packages, the component uses `@Input()` and `@Output()` decorators:
+
+```typescript
+
+@Component({
+  selector: 'app-my-grid',
+  standalone: true,
+  imports: [PaginationControlsComponent],
+  template: `
+    <ogrid-pagination-controls
+      [currentPage]="currentPage"
+      [pageSize]="pageSize"
+      [totalCount]="totalCount"
+      (onPageChange)="handlePageChange($event)"
+      (onPageSizeChange)="handlePageSizeChange($event)"
+      [entityLabelPlural]="'users'"
+    />
+  `
+})
+export class MyGridComponent {
+  currentPage = 1;
+  pageSize = 20;
+  totalCount = 500;
+
+  handlePageChange(page: number) {
+    this.currentPage = page;
+  }
+
+  handlePageSizeChange(pageSize: number) {
+    this.pageSize = pageSize;
+    this.currentPage = 1; // Reset to first page
+  }
+}
+```
+
+## Vue Usage
+
+In Vue packages, the component accepts props via `v-bind` or shorthand `:`:
+
+```vue
+<template>
+  <PaginationControls
+    :current-page="currentPage"
+    :page-size="pageSize"
+    :total-count="totalCount"
+    @page-change="handlePageChange"
+    @page-size-change="handlePageSizeChange"
+    entity-label-plural="users"
+  />
+</template>
+
+<script setup lang="ts">
+
+const currentPage = ref(1);
+const pageSize = ref(20);
+const totalCount = ref(500);
+
+const handlePageChange = (page: number) => {
+  currentPage.value = page;
+};
+
+const handlePageSizeChange = (size: number) => {
+  pageSize.value = size;
+  currentPage.value = 1; // Reset to first page
+};
+</script>
+```
+
+## Behavior
+
+### Pagination Buttons
+
+- **« (First)** — Jump to page 1 (disabled when on page 1)
+- **‹ (Previous)** — Go to the previous page (disabled when on page 1)
+- **[1] [2] [3]** — Numbered page buttons (up to 7 buttons shown)
+- **...** — Ellipsis when there are more than 7 pages
+- **› (Next)** — Go to the next page (disabled when on last page)
+- **» (Last)** — Jump to the last page (disabled when on last page)
+
+### Page Number Display Logic
+
+The component uses a smart algorithm to show a maximum of 7 page numbers with ellipsis:
+
+- **1-7 pages:** Show all page numbers
+- **8+ pages:**
+  - Show first and last page always
+  - Show current page and 1-2 neighbors
+  - Use ellipsis (`...`) to indicate skipped pages
+
+**Examples:**
+
+| Current Page | Total Pages | Displayed |
+|--------------|-------------|-----------|
+| 1 | 10 | `[1] 2 3 ... 10` |
+| 5 | 10 | `1 ... 4 [5] 6 ... 10` |
+| 10 | 10 | `1 ... 8 9 [10]` |
+
+### Page Size Dropdown
+
+The dropdown shows all values from `pageSizeOptions` (default: `[10, 20, 50, 100]`). When the user changes the page size:
+1. `onPageSizeChange` is called with the new size
+2. The parent should reset `currentPage` to 1 (recommended best practice)
+
+### Info Text
+
+The info text shows the range of items currently displayed:
+
+```
+Showing {startItem} to {endItem} of {totalCount} {entityLabelPlural}
+```
+
+**Example:** `Showing 21 to 40 of 250 rows`
+
+## Accessibility
+
+`PaginationControls` implements WCAG 2.1 AA standards with full keyboard and screen reader support.
+
+### ARIA Attributes
+
+```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>
+  <label for="page-size">Page size:</label>
+  <select id="page-size" aria-label="Items per page">
+    <option>20</option>
+  </select>
+</nav>
+```
+
+| Attribute | Element | Purpose |
+|-----------|---------|---------|
+| `role="navigation"` | Nav wrapper | Identifies pagination controls as navigation |
+| `aria-label="Pagination"` | Nav wrapper | Provides context for screen readers |
+| `aria-label` (icon buttons) | `<button>` | Descriptive labels for icon-only buttons (« ‹ › ») |
+| `aria-label` (page buttons) | `<button>` | Announces page number: "Page 1", "Page 2", etc. |
+| `aria-current="page"` | Current page button | Identifies the active page |
+| `aria-disabled="true"` | Disabled buttons | Indicates buttons that cannot be activated (first/prev on page 1, next/last on last page) |
+| `id` / `for` | Select + label | Associates dropdown with its label |
+| `aria-label` | `<select>` | Additional context: "Items per page" |
+
+### Keyboard Navigation
+
+- `Tab` / `Shift+Tab` — Navigate between pagination buttons and page size dropdown
+- `Enter` / `Space` (on buttons) — Activate focused button (change page)
+- `←` `→` (on page buttons) — Navigate between page number buttons
+- `↑` `↓` (on dropdown) — Change page size
+- `Enter` (on dropdown) — Confirm page size selection
+
+### Focus Management
+
+- **Focus visible:** `:focus-visible` styles show 2px solid outline (`--ogrid-accent`) on keyboard navigation
+- **Focus restoration:** After page change, focus remains on pagination controls (does not jump to grid)
+- **Disabled state:** Disabled buttons show `aria-disabled="true"` and cannot receive focus
+
+### Screen Reader Support
+
+Screen readers announce:
+- **Page info:** "Showing 21 to 40 of 250 rows"
+- **Page button:** "Page 2 button"
+- **Current page:** "Page 1 button, current page"
+- **Disabled buttons:** "First page button, disabled"
+- **Page change:** "Navigated to page 3, showing 41 to 60 of 250 rows"
+- **Page size change:** "Page size changed to 50 rows per page"
+
+Tested with NVDA, JAWS, VoiceOver, and Narrator.
+
+### High Contrast Mode
+
+- Navigation buttons remain visible in high contrast mode
+- Focus indicators use system `Highlight` color
+- Borders use system `ButtonText` color
+- Current page button uses system `HighlightText` color
+
+See the [Accessibility Guide](/docs/guides/accessibility) for complete documentation.
+
+## Styling
+
+All UI packages provide default styles matching their design system. Styles are scoped to avoid conflicts.
+
+**CSS custom properties** (all packages):
+- `--ogrid-header-bg` — Background color
+- `--ogrid-border` — Border color
+- `--ogrid-fg` — Foreground text color
+- `--ogrid-primary` — Primary color (current page button)
+
+## Layout Integration
+
+`PaginationControls` is automatically rendered in the footer strip of `OGridLayout` when pagination is enabled. The footer strip has a border-top and matches the header background color.
+
+## No Border or Padding
+
+The component itself has **no outer border or padding** — the parent container (footer strip in `OGridLayout`) provides these styles.
+
+## Related Components
+
+- [OGrid](./ogrid-props.mdx) — Top-level wrapper that includes pagination
+- [DataGridTable](./components-datagrid-table.mdx) — Main grid component
+- [StatusBar](./components-status-bar.mdx) — Status bar below the grid
+
+## See Also
+
+- [Grid API](./grid-api.mdx) — Pagination-related API methods
+- [Pagination Feature Guide](/docs/features/pagination) — Complete pagination documentation