@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/api/js-api.mdx

@@ -0,0 +1,198 @@
+---
+sidebar_position: 5
+title: Vanilla JS API
+description: Full API reference for @alaarab/ogrid-js
+---
+
+# Vanilla JS API
+
+Complete reference for `@alaarab/ogrid-js` — the framework-free data grid.
+
+## OGrid Class
+
+```js
+
+const grid = new OGrid(container, options);
+```
+
+### Constructor
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `container` | `HTMLElement` | DOM element to render into. OGrid fills this container. |
+| `options` | `OGridOptions<T>` | Configuration object (see below). |
+
+### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `grid.api` | The imperative API object (see [API Methods](#api-methods) below). |
+| `grid.on(event, handler)` | Subscribe to a grid event. Returns `void`. |
+| `grid.off(event, handler)` | Unsubscribe from a grid event. |
+| `grid.destroy()` | Tear down the grid — removes DOM, listeners, and ResizeObservers. |
+
+---
+
+## OGridOptions\<T\>
+
+All configuration is passed to the constructor.
+
+### Data
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `columns` | `(IColumnDef<T> \| IColumnGroupDef<T>)[]` | **required** | Column definitions. |
+| `getRowId` | `(item: T) => RowId` | **required** | Returns a unique `string \| number` per row. |
+| `data` | `T[]` | — | Client-side data. Mutually exclusive with `dataSource`. |
+| `dataSource` | `IDataSource<T>` | — | Server-side data source. Mutually exclusive with `data`. |
+
+### Pagination & Sorting
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `page` | `number` | `1` | Initial page (1-based). |
+| `pageSize` | `number` | `20` | Rows per page. |
+| `sort` | `{ field: string; direction: 'asc' \| 'desc' }` | — | Initial sort state. |
+| `filters` | `IFilters` | — | Initial filter state. |
+
+### Interaction
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `editable` | `boolean` | `false` | Enable inline cell editing. |
+| `cellSelection` | `boolean` | `false` | Enable spreadsheet-style cell/range selection. |
+| `rowSelection` | `'single' \| 'multiple'` | — | Row checkbox selection mode. |
+| `selectedRows` | `Set<RowId>` | — | Controlled selected row IDs. |
+| `pinnedColumns` | `Record<string, 'left' \| 'right'>` | — | Pin columns to left/right edges. |
+| `visibleColumns` | `Set<string>` | all | Initially visible column IDs. |
+
+### Layout
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `layoutMode` | `'fill' \| 'content'` | `'fill'` | `'fill'` stretches to container; `'content'` sizes to data. |
+| `suppressHorizontalScroll` | `boolean` | `false` | Prevent horizontal scrollbar. |
+| `sideBar` | `boolean \| ISideBarDef` | — | Show sidebar with columns/filters panels. |
+| `emptyMessage` | `string` | `'No data'` | Custom empty state text. |
+| `aria-label` | `string` | — | Accessible label for the grid. |
+
+### Callbacks
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `onCellValueChanged` | `(event: ICellValueChangedEvent<T>) => void` | Fired when a cell edit is committed. |
+| `onSelectionChange` | `(event: IRowSelectionChangeEvent<T>) => void` | Fired when row selection changes. |
+| `onError` | `(error: unknown) => void` | Fired on server-side data source failures. |
+| `onFirstDataRendered` | `() => void` | Fired once when the first data render completes. |
+
+---
+
+## API Methods
+
+Access via `grid.api`:
+
+### Data
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `setRowData` | `(data: T[]) => void` | Replace the entire dataset (client-side only; no-op with `dataSource`). |
+| `setLoading` | `(loading: boolean) => void` | Show or hide the loading overlay. |
+| `getDisplayedRows` | `() => T[]` | Get the currently visible (filtered, sorted, paginated) rows. |
+| `refreshData` | `() => void` | Re-fetch from `dataSource` (server-side only). |
+
+### Sorting & Filtering
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `setFilterModel` | `(filters: IFilters) => void` | Set the full filter model. Pass `{}` to clear all filters. |
+| `clearFilters` | `() => void` | Clear all active filters. Shorthand for `setFilterModel({})`. |
+| `clearSort` | `() => void` | Reset the sort to no active sort. |
+| `resetGridState` | `(options?: { keepSelection?: boolean }) => void` | Reset all grid state (filters, sort, and optionally selection). |
+
+### Columns
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getColumnState` | `() => IGridColumnState` | Get current column state (visibility, sort, order, widths, filters). |
+| `applyColumnState` | `(state: Partial<IGridColumnState>) => void` | Bulk-restore any combination of column state fields. |
+| `getColumnOrder` | `() => string[]` | Get the current column display order (array of column IDs). |
+| `setColumnOrder` | `(order: string[]) => void` | Set the column display order programmatically. |
+
+### Selection
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `selectAll` | `() => void` | Select all rows (requires `rowSelection: 'multiple'`). |
+| `deselectAll` | `() => void` | Deselect all rows. |
+| `getSelectedRows` | `() => RowId[]` | Get the IDs of currently selected rows. |
+| `setSelectedRows` | `(rowIds: RowId[]) => void` | Set which rows are selected by their IDs. |
+
+### Export
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `exportToCsv` | `(filename?: string) => void` | Export displayed rows to CSV and trigger a browser download. |
+
+### Virtual Scrolling
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `scrollToRow` | `(index: number, options?: { align?: 'start' \| 'center' \| 'end' }) => void` | Scroll to a specific row by index. Only effective when virtual scrolling is enabled. |
+
+---
+
+## Events
+
+Subscribe with `grid.on(eventName, handler)`.
+
+| Event | Payload Type | Fired When |
+|-------|-------------|------------|
+| `cellValueChanged` | `ICellValueChangedEvent<T>` | A cell edit is committed |
+| `selectionChange` | `IRowSelectionChangeEvent<T>` | Row selection changes |
+| `sortChange` | `{ field: string; direction: 'asc' \| 'desc' }` | Sort state changes |
+| `filterChange` | `{ filters: IFilters }` | Filter state changes |
+| `pageChange` | `{ page: number }` | Current page changes |
+
+### ICellValueChangedEvent\<T\>
+
+```ts
+{
+  item: T;           // The row data object
+  columnId: string;  // Which column was edited
+  oldValue: unknown; // Previous cell value
+  newValue: unknown; // New cell value
+  rowIndex: number;  // Row index of the edited cell
+}
+```
+
+---
+
+## IColumnDef\<T\> (JS-specific)
+
+The JS package extends the core `IColumnDef<T>` with DOM-aware fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `renderCell` | `(cell: HTMLTableCellElement, item: T, value: unknown) => void` | Custom cell renderer — mutate the `<td>` DOM directly. |
+| `cellStyle` | `Partial<CSSStyleDeclaration>` | Inline styles applied to each cell. |
+| `cellEditor` | `string \| (container: HTMLElement, params: object) => { getValue: () => unknown; destroy: () => void }` | Built-in editor name (`'text'`, `'select'`, `'richSelect'`, `'checkbox'`, `'date'`) or a factory function for custom editors. |
+
+All other `IColumnDef` fields (`columnId`, `name`, `sortable`, `filterable`, `type`, `editable`, `valueFormatter`, `valueGetter`, `valueParser`, `minWidth`, `defaultWidth`, `idealWidth`, `pinned`, `required`, `defaultVisible`) are identical to the React version — see [Column Definitions](./column-def).
+
+---
+
+## CSS Classes
+
+The JS package renders semantic HTML with `ogrid-*` class names. Import the default theme or write your own CSS targeting these selectors:
+
+### Layout
+`ogrid-container`, `ogrid-toolbar`, `ogrid-body-area`, `ogrid-table-container`, `ogrid-sidebar-container`, `ogrid-status-bar-container`, `ogrid-pagination-container`
+
+### Table
+`ogrid-wrapper`, `ogrid-table`, `ogrid-header-cell`, `ogrid-group-header`, `ogrid-sortable`, `ogrid-sort-indicator`, `ogrid-resize-handle`, `ogrid-filter-icon`, `ogrid-row`, `ogrid-cell`, `ogrid-checkbox-header`, `ogrid-checkbox-cell`, `ogrid-fill-handle`, `ogrid-empty-state`
+
+### Data Attributes
+`[data-active-cell]`, `[data-in-range]`, `[data-drag-range]`, `[data-row-selected]`, `[data-pinned="left|right"]`, `[data-column-id]`, `[data-row-index]`, `[data-col-index]`
+
+### CSS Variables
+Override `--ogrid-bg`, `--ogrid-fg`, `--ogrid-border`, `--ogrid-primary`, `--ogrid-selection`, `--ogrid-bg-subtle`, `--ogrid-bg-hover`, `--ogrid-muted`, and more. See [Theming](../guides/theming).

package/bundled-docs/api/ogrid-props.mdx

@@ -0,0 +1,244 @@
+---
+sidebar_position: 1
+title: OGrid Props
+---
+
+# OGrid Props
+
+Complete reference for `IOGridProps<T>`, the props accepted by the `OGrid` component in all UI packages (`@alaarab/ogrid-react-radix`, `@alaarab/ogrid-react-fluent`, `@alaarab/ogrid-react-material`).
+
+```typescript
+```
+
+:::caution v1.6.0 Breaking Changes
+- The `title` prop has been removed. Render your own heading outside `<OGrid>`.
+- `IFilters` values are now discriminated unions: `{ type: 'text', value: string }` instead of raw strings. See [Filtering](../features/filtering) for the new format.
+:::
+
+## Data
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `(IColumnDef<T> \| IColumnGroupDef<T>)[]` | **Required** | Array of column definitions and optional column groups. See [Column Definition](./column-def). |
+| `getRowId` | `(item: T) => RowId` | **Required** | Function that returns a unique identifier for each row. Must be stable across re-renders. |
+| `data` | `T[]` | `undefined` | Array of row data for client-side mode. Mutually exclusive with `dataSource`. When provided, sorting, filtering, and pagination are handled in-memory. |
+| `dataSource` | `IDataSource<T>` | `undefined` | Server-side data source. Mutually exclusive with `data`. See [Server-Side Data](../features/server-side-data). |
+| `isLoading` | `boolean` | `false` | Whether the grid is in a loading state. When `true`, the grid displays a loading indicator. |
+
+## Sorting
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `sort` | `{ field: string; direction: 'asc' \| 'desc' }` | `undefined` | Controlled sort state. When provided, the grid uses this value and calls `onSortChange` when the user clicks a sortable column header. |
+| `onSortChange` | `(sort: { field: string; direction: 'asc' \| 'desc' }) => void` | `undefined` | Callback fired when the user changes the sort. Required for controlled sort mode. |
+| `defaultSortBy` | `string` | `undefined` | Column ID to sort by initially in uncontrolled mode. |
+| `defaultSortDirection` | `'asc' \| 'desc'` | `undefined` | Initial sort direction in uncontrolled mode. Used together with `defaultSortBy`. |
+
+## Filtering
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `filters` | `IFilters` | `undefined` | Controlled filter state. A record mapping field names to filter values. See [Types](./types) for `IFilters`. |
+| `onFiltersChange` | `(filters: IFilters) => void` | `undefined` | Callback fired when the user applies or clears a filter. Required for controlled filter mode. |
+
+## Pagination
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `page` | `number` | `undefined` | Controlled current page (1-based). |
+| `pageSize` | `number` | `undefined` | Controlled page size. |
+| `onPageChange` | `(page: number) => void` | `undefined` | Callback fired when the user navigates to a different page. |
+| `onPageSizeChange` | `(size: number) => void` | `undefined` | Callback fired when the user changes the page size. |
+| `defaultPageSize` | `number` | `25` | Initial page size in uncontrolled mode. |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Options shown in the page size dropdown. The active page size is auto-inserted if missing. |
+
+## Column Visibility and Order
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `visibleColumns` | `Set<string>` | `undefined` | Controlled set of visible column IDs. When provided, only these columns are displayed. |
+| `onVisibleColumnsChange` | `(cols: Set<string>) => void` | `undefined` | Callback fired when column visibility changes (e.g., via the column chooser). |
+| `columnOrder` | `string[]` | `undefined` | Controlled column order as an array of column IDs. |
+| `onColumnOrderChange` | `(order: string[]) => void` | `undefined` | Callback fired when the user reorders columns. |
+| `onColumnResized` | `(columnId: string, width: number) => void` | `undefined` | Callback fired when the user finishes resizing a column. |
+
+## Editing
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `editable` | `boolean` | `false` | Whether inline cell editing is enabled globally. Individual columns can override this via `IColumnDef.editable`. |
+| `onCellValueChanged` | `(event: ICellValueChangedEvent<T>) => void` | `undefined` | Callback fired after a cell value is committed. The event contains `item`, `columnId`, `oldValue`, `newValue`, and `rowIndex`. |
+| `onUndo` | `() => void` | `undefined` | Callback fired when the user triggers undo (Ctrl+Z or context menu). |
+| `onRedo` | `() => void` | `undefined` | Callback fired when the user triggers redo (Ctrl+Y or context menu). |
+| `canUndo` | `boolean` | `false` | Whether undo is available. Controls the enabled state of the undo context menu item. |
+| `canRedo` | `boolean` | `false` | Whether redo is available. Controls the enabled state of the redo context menu item. |
+
+## Cell Selection
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `cellSelection` | `boolean` | `true` | Whether cell selection (active cell, range selection, drag selection) is enabled. When `false`, clicking cells does not highlight them. |
+
+## Row Selection
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `rowSelection` | `RowSelectionMode` | `'none'` | Row selection mode: `'none'`, `'single'`, or `'multiple'`. When enabled, a checkbox column is added. |
+| `selectedRows` | `Set<RowId>` | `undefined` | Controlled set of selected row IDs. |
+| `onSelectionChange` | `(event: IRowSelectionChangeEvent<T>) => void` | `undefined` | Callback fired when row selection changes. The event contains `selectedRowIds` and `selectedItems`. |
+
+## Status Bar
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `statusBar` | `boolean \| IStatusBarProps` | `false` | Controls the status bar at the bottom of the grid. Pass `true` to show a default status bar with item counts, or pass an `IStatusBarProps` object for full control. See [Types](./types) for `IStatusBarProps`. |
+
+## Side Bar
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `sideBar` | `boolean \| ISideBarDef` | `undefined` | Controls the side bar panel. Pass `true` for default side bar, or an `ISideBarDef` object to configure panels and position. See [Types](./types) for `ISideBarDef`. |
+
+## Column Chooser
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `columnChooser` | `boolean \| 'toolbar' \| 'sidebar'` | `true` | Where to render the column chooser. `true`/`'toolbar'` shows it in the toolbar. `'sidebar'` moves it to the sidebar columns panel. `false` hides it entirely. |
+
+## Column Reordering
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `columnReorder` | `boolean` | `false` | Enable drag-and-drop column reordering via header cells. See [Column Reordering](../features/column-reordering). |
+
+## Virtual Scrolling
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `virtualScroll` | `IVirtualScrollConfig` | `undefined` | Virtual scrolling configuration. See [Virtual Scrolling](../features/virtual-scrolling) and [Types](./types) for `IVirtualScrollConfig`. |
+
+## Layout
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `layoutMode` | `'content' \| 'fill'` | `'fill'` | How the grid sizes itself. `'content'` sizes to fit content. `'fill'` expands to fill its container. |
+| `suppressHorizontalScroll` | `boolean` | `false` | When `true`, disables horizontal scrolling by setting `overflow-x: hidden` on the grid wrapper. |
+| `stickyHeader` | `boolean` | `true` | When `true`, column headers stick to the top of the scroll container during vertical scrolling. Set to `false` to let headers scroll with data. |
+| `fullScreen` | `boolean` | `false` | When `true`, renders a fullscreen toggle button in the toolbar. Clicking it expands the grid to fill the entire viewport. Press **Escape** or click the button again to exit. |
+| `rowHeight` | `number` | `36` | Fixed row height in pixels. Affects layout and virtual scrolling row height calculation. |
+| `density` | `'compact' \| 'normal' \| 'comfortable'` | `'normal'` | Cell spacing preset. Controls cell padding throughout the grid. |
+| `showRowNumbers` | `boolean` | `false` | Show Excel-style row number column (1, 2, 3...) at the start of the grid. |
+| `className` | `string` | `undefined` | Additional CSS class name applied to the root grid element. |
+| `toolbar` | `ReactNode` | `undefined` | Custom toolbar content rendered in the left side of the primary toolbar strip. |
+| `toolbarBelow` | `ReactNode` | `undefined` | Secondary toolbar row rendered below the primary toolbar. Use for active filter chips, breadcrumbs, or other contextual controls. |
+| `entityLabelPlural` | `string` | `undefined` | Plural label for the entity type (e.g., `"projects"`, `"users"`). Used in status bar text and empty state messages. |
+| `emptyState` | `{ message?: ReactNode; render?: () => ReactNode }` | `undefined` | Custom empty state configuration. Provide `message` for a simple text override, or `render` for a fully custom empty state component. |
+
+## Callbacks
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `onFirstDataRendered` | `() => void` | `undefined` | Fired once when the grid first renders with data. Useful for restoring column state. |
+| `onColumnPinned` | `(columnId: string, pinned: 'left' \| 'right' \| null) => void` | `undefined` | Fired when a column is pinned or unpinned. |
+
+## Error Handling
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `onError` | `(error: unknown) => void` | `undefined` | Callback fired when the grid encounters an error (e.g., a failed server-side fetch). |
+| `onCellError` | `(error: Error, errorInfo: React.ErrorInfo) => void` | `undefined` | Callback fired when a cell renderer or custom editor throws an error. |
+
+## Accessibility
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `aria-label` | `string` | `undefined` | Accessible label for the grid. Use this or `aria-labelledby`, not both. |
+| `aria-labelledby` | `string` | `undefined` | ID of an element that labels the grid. Use this or `aria-label`, not both. |
+
+## Ref
+
+The `OGrid` component accepts a `ref` prop that exposes the `IOGridApi<T>` imperative API. See [Grid API](./grid-api) for full details.
+
+```typescript
+
+function MyGrid() {
+  const apiRef = useRef<IOGridApi<MyRow>>(null);
+
+  return (
+    <OGrid
+      ref={apiRef}
+      columns={columns}
+      data={data}
+      getRowId={(row) => row.id}
+    />
+  );
+}
+```
+
+## Minimal Example
+
+```typescript
+
+interface Person {
+  id: number;
+  name: string;
+  age: number;
+}
+
+const columns = [
+  { columnId: 'name', name: 'Name' },
+  { columnId: 'age', name: 'Age', type: 'numeric' as const },
+];
+
+const data: Person[] = [
+  { id: 1, name: 'Alice', age: 30 },
+  { id: 2, name: 'Bob', age: 25 },
+];
+
+function App() {
+  return (
+    <OGrid<Person>
+      columns={columns}
+      data={data}
+      getRowId={(row) => row.id}
+    />
+  );
+}
+```
+
+## Controlled vs Uncontrolled
+
+OGrid supports both controlled and uncontrolled modes for pagination, sorting, filtering, column visibility, column order, and row selection.
+
+**Uncontrolled** (default): The grid manages state internally. Use `default*` props to set initial values.
+
+```typescript
+<OGrid
+  columns={columns}
+  data={data}
+  getRowId={(row) => row.id}
+  defaultPageSize={25}
+  defaultSortBy="name"
+  defaultSortDirection="asc"
+/>
+```
+
+**Controlled**: You own the state and pass values + callbacks. The grid never updates these values on its own.
+
+```typescript
+const [page, setPage] = useState(1);
+const [pageSize, setPageSize] = useState(25);
+const [sort, setSort] = useState({ field: 'name', direction: 'asc' as const });
+
+<OGrid
+  columns={columns}
+  data={data}
+  getRowId={(row) => row.id}
+  page={page}
+  pageSize={pageSize}
+  sort={sort}
+  onPageChange={setPage}
+  onPageSizeChange={setPageSize}
+  onSortChange={setSort}
+/>
+```