@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/api/components-status-bar.mdx

@@ -0,0 +1,309 @@
+---
+sidebar_position: 14
+title: StatusBar
+---
+
+# StatusBar
+
+A status bar component that displays row counts, filtered counts, selected counts, and aggregations for selected numeric cells. Rendered below the grid table, above the pagination controls.
+
+## Import
+
+
+<Tabs groupId="framework">
+<TabItem value="react" label="React">
+
+```typescript
+// or
+// or
+```
+
+</TabItem>
+<TabItem value="angular" label="Angular">
+
+```typescript
+// StatusBar is rendered internally by DataGridTable in Angular packages
+```
+
+</TabItem>
+<TabItem value="vue" label="Vue">
+
+```typescript
+// StatusBar is rendered internally by DataGridTable in Vue packages
+```
+
+</TabItem>
+<TabItem value="js" label="Vanilla JS">
+
+```typescript
+// StatusBar is an internal component in vanilla JS
+```
+
+</TabItem>
+</Tabs>
+
+## Props (React)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `totalCount` | `number` | **Required** | Total row count (unfiltered). |
+| `filteredCount` | `number` | `undefined` | Filtered row count (after filters applied). Omit to hide. |
+| `selectedCount` | `number` | `undefined` | Number of selected rows. Omit or 0 to hide. |
+| `selectedCellCount` | `number` | `undefined` | Number of selected cells in a cell range. Omit or 0 to hide. |
+| `aggregation` | `{ sum, avg, min, max, count }` | `null` | Aggregation values for selected numeric cells. See [Aggregation](#aggregation) below. |
+| `suppressRowCount` | `boolean` | `false` | When true, hides the "Rows: X" label (useful when pagination already shows it). |
+
+## Aggregation
+
+When the user selects a range of numeric cells, the status bar can display aggregations:
+
+```typescript
+interface Aggregation {
+  sum: number;
+  avg: number;
+  min: number;
+  max: number;
+  count: number;
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `sum` | Sum of all numeric cells in the selection. |
+| `avg` | Average of all numeric cells in the selection. |
+| `min` | Minimum value in the selection. |
+| `max` | Maximum value in the selection. |
+| `count` | Number of numeric cells in the selection. |
+
+**Example:** If the user selects a 3×3 range of cells with values `[10, 20, 30, 40, 50, 60, 70, 80, 90]`:
+- `sum: 450`
+- `avg: 50`
+- `min: 10`
+- `max: 90`
+- `count: 9`
+
+## Usage
+
+### Basic Example (React)
+
+```tsx
+
+function MyGrid() {
+  return (
+    <StatusBar
+      totalCount={1000}
+      filteredCount={250}
+      selectedCount={5}
+    />
+  );
+}
+```
+
+**Output:**
+```
+Rows: 1,000  |  Filtered: 250  |  Selected: 5
+```
+
+### With Cell Selection Aggregation (React)
+
+```tsx
+
+function MyGrid() {
+  const aggregation = {
+    sum: 450,
+    avg: 50,
+    min: 10,
+    max: 90,
+    count: 9,
+  };
+
+  return (
+    <StatusBar
+      totalCount={1000}
+      selectedCellCount={9}
+      aggregation={aggregation}
+    />
+  );
+}
+```
+
+**Output:**
+```
+Rows: 1,000  |  Selected Cells: 9  |  Sum: 450  |  Avg: 50  |  Min: 10  |  Max: 90
+```
+
+### Suppress Row Count (React)
+
+When pagination controls already show "Showing X to Y of Z rows", you can hide the redundant "Rows: Z" label:
+
+```tsx
+
+function MyGrid() {
+  return (
+    <StatusBar
+      totalCount={1000}
+      filteredCount={250}
+      suppressRowCount={true}
+    />
+  );
+}
+```
+
+**Output:**
+```
+Filtered: 250
+```
+
+## Display Logic
+
+The status bar intelligently shows/hides sections based on available data:
+
+| Condition | Displayed |
+|-----------|-----------|
+| Always | `Rows: {totalCount}` (unless `suppressRowCount` is true) |
+| `filteredCount` provided and differs from `totalCount` | `Filtered: {filteredCount}` |
+| `selectedCount` > 0 | `Selected: {selectedCount}` |
+| `selectedCellCount` > 0 | `Selected Cells: {selectedCellCount}` |
+| `aggregation` provided | `Sum: X`, `Avg: X`, `Min: X`, `Max: X` |
+
+Sections are separated by `|` (pipe) characters.
+
+## Angular Usage
+
+In Angular packages, the status bar is rendered internally by `DataGridTable` when `statusBar` is enabled. You don't need to import or use the component directly.
+
+```typescript
+
+@Component({
+  selector: 'app-my-grid',
+  template: `
+    <ogrid-datagrid-table [propsInput]="gridProps" />
+  `
+})
+export class MyGridComponent {
+  ogridService = new OGridService<Product>();
+
+  constructor() {
+    // Enable status bar via props
+    this.ogridService.setProps({ statusBar: true });
+  }
+
+  gridProps = this.ogridService.getDataGridProps();
+}
+```
+
+## Vue Usage
+
+In Vue packages, the status bar is rendered internally by `DataGridTable` when `statusBar` is enabled.
+
+```vue
+<template>
+  <DataGridTable :grid-props="gridProps" />
+</template>
+
+<script setup lang="ts">
+
+const { dataGridProps: gridProps } = useOGrid({
+  data: products,
+  columns: columns,
+  getRowId: (item) => item.id,
+  statusBar: true, // Enable status bar
+});
+</script>
+```
+
+## Enabling in OGrid
+
+The top-level `OGrid` component accepts a `statusBar` prop:
+
+```tsx
+
+// Boolean mode: show with default configuration
+<OGrid statusBar={true} {...props} />
+
+// Custom configuration
+<OGrid
+  statusBar={{
+    totalCount: 1000,
+    filteredCount: 250,
+    selectedCount: 5,
+    suppressRowCount: false,
+  }}
+  {...props}
+/>
+```
+
+When `statusBar` is `true`, the grid automatically computes the counts from the current state.
+
+## Accessibility
+
+`StatusBar` implements WCAG 2.1 AA standards with screen reader support for dynamic content announcements.
+
+### ARIA Attributes
+
+```html
+<div role="status" aria-live="polite">
+  <span>Rows: 1,000</span>
+  <span>Filtered: 250</span>
+  <span>Selected: 5</span>
+  <span>Sum: 450</span>
+  <span>Avg: 90</span>
+</div>
+```
+
+| Attribute | Element | Purpose |
+|-----------|---------|---------|
+| `role="status"` | Status bar container | Identifies region containing status information |
+| `aria-live="polite"` | Status bar container | Announces changes when user is idle (non-intrusive) |
+
+### Screen Reader Support
+
+Screen readers announce changes to the status bar:
+- **Initial render:** "Status: Rows 1000, Filtered 250, Selected 5"
+- **Selection change:** "Selected 10"
+- **Filter change:** "Filtered 150"
+- **Aggregation update:** "Sum 450, Average 90, Minimum 10, Maximum 90"
+
+The `aria-live="polite"` setting ensures announcements don't interrupt the user's current task. Screen readers wait for a natural pause before announcing status changes.
+
+### Semantic HTML
+
+The status bar uses semantic `<span>` elements with clear text labels:
+- "Rows: 1,000" — Total row count
+- "Filtered: 250" — Filtered row count
+- "Selected: 5" — Selected row count
+- "Sum: 450" — Aggregation values
+
+No additional ARIA labels are needed because the text content is already descriptive.
+
+### High Contrast Mode
+
+- Text remains visible in all high contrast themes
+- Background uses system colors
+- Border uses system `ButtonText` color
+
+See the [Accessibility Guide](/docs/guides/accessibility) for complete documentation.
+
+## Styling
+
+All UI packages provide default styles matching their design system. The status bar is styled with a subtle background and border-top.
+
+**CSS custom properties** (all packages):
+- `--ogrid-header-bg` — Background color (matches header)
+- `--ogrid-border` — Border color
+- `--ogrid-fg` — Foreground text color
+
+## Layout Integration
+
+The status bar is rendered inside `DataGridTable` at the bottom, just above the pagination controls (when pagination is enabled).
+
+## Related Components
+
+- [DataGridTable](./components-datagrid-table.mdx) — Main grid component that renders the status bar
+- [PaginationControls](./components-pagination-controls.mdx) — Pagination UI below the status bar
+- [OGrid](./ogrid-props.mdx) — Top-level wrapper with `statusBar` prop
+
+## See Also
+
+- [Types: IStatusBarProps](./types.mdx#istatusbarprops) — Status bar props reference
+- [Spreadsheet Selection Feature Guide](/docs/features/spreadsheet-selection) — How aggregations are computed

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

@@ -0,0 +1,299 @@
+---
+sidebar_position: 4
+title: Grid API
+---
+
+# Grid API
+
+The `IOGridApi<T>` interface provides imperative methods for controlling the grid programmatically. Access it via a React ref on the `OGrid` component.
+
+## Accessing the API
+
+```typescript
+
+interface Employee {
+  id: number;
+  name: string;
+  department: string;
+}
+
+function EmployeeGrid() {
+  const apiRef = useRef<IOGridApi<Employee>>(null);
+
+  const handleClearFilters = () => {
+    apiRef.current?.setFilterModel({});
+  };
+
+  return (
+    <>
+      <button onClick={handleClearFilters}>Clear Filters</button>
+      <OGrid<Employee>
+        ref={apiRef}
+        columns={columns}
+        data={data}
+        getRowId={(e) => e.id}
+      />
+    </>
+  );
+}
+```
+
+## IOGridApi&lt;T&gt;
+
+```typescript
+interface IOGridApi<T> {
+  setRowData: (data: T[]) => void;
+  setLoading: (loading: boolean) => void;
+  getColumnState: () => IGridColumnState;
+  applyColumnState: (state: Partial<IGridColumnState>) => void;
+  setFilterModel: (filters: IFilters) => void;
+  clearFilters: () => void;
+  clearSort: () => void;
+  resetGridState: (options?: { keepSelection?: boolean }) => void;
+  getSelectedRows: () => RowId[];
+  setSelectedRows: (rowIds: RowId[]) => void;
+  selectAll: () => void;
+  deselectAll: () => void;
+  getDisplayedRows: () => T[];
+  refreshData: () => void;
+  scrollToRow: (index: number, options?: { align?: 'start' | 'center' | 'end' }) => void;
+  getColumnOrder: () => string[];
+  setColumnOrder: (order: string[]) => void;
+}
+```
+
+### Data Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `setRowData` | `(data: T[]) => void` | Replaces the grid's data with a new array. Useful for client-side mode when you want to update data imperatively rather than through the `data` prop. |
+| `setLoading` | `(loading: boolean) => void` | Sets the loading state of the grid. When `true`, the grid displays a loading indicator. |
+| `getDisplayedRows` | `() => T[]` | Returns the currently displayed (filtered, sorted, paginated) rows. |
+| `refreshData` | `() => void` | Re-triggers a data fetch. Server-side only; no-op for client-side grids. |
+
+### Column State Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getColumnState` | `() => IGridColumnState` | Returns the current column state including visibility, sort, order, widths, and filters. See [IGridColumnState](#igridcolumnstate) below. |
+| `applyColumnState` | `(state: Partial<IGridColumnState>) => void` | Applies a partial column state. Any fields not included in the object are left unchanged. Useful for restoring saved state. |
+| `getColumnOrder` | `() => string[]` | Returns the current column display order as an array of column IDs. |
+| `setColumnOrder` | `(order: string[]) => void` | Programmatically sets the column display order. |
+
+### Filter Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `setFilterModel` | `(filters: IFilters) => void` | Sets the filter state. Pass an empty object `{}` to clear all filters. See [Types](./types) for `IFilters`. |
+| `clearFilters` | `() => void` | Clears all active filters. Shorthand for `setFilterModel({})`. |
+| `clearSort` | `() => void` | Resets the sort to the default (no active sort). |
+| `resetGridState` | `(options?: { keepSelection?: boolean }) => void` | Resets all grid state (filters, sort, and optionally selection). |
+
+### Row Selection Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getSelectedRows` | `() => RowId[]` | Returns an array of selected row IDs. |
+| `setSelectedRows` | `(rowIds: RowId[]) => void` | Sets the selected rows to the given IDs. Any previously selected rows not in the array are deselected. |
+| `selectAll` | `() => void` | Selects all rows in the current data set. |
+| `deselectAll` | `() => void` | Deselects all rows. |
+
+### Virtual Scrolling Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `scrollToRow` | `(index: number, options?: { align?: 'start' \| 'center' \| 'end' }) => void` | Scrolls to a specific row by index. Only effective when virtual scrolling is enabled. |
+
+## IGridColumnState
+
+Represents the complete column state of the grid. Returned by `getColumnState()` and accepted by `applyColumnState()`.
+
+```typescript
+interface IGridColumnState {
+  visibleColumns: string[];
+  sort?: { field: string; direction: 'asc' | 'desc' };
+  columnOrder?: string[];
+  columnWidths?: Record<string, number>;
+  filters?: IFilters;
+  pinnedColumns?: Record<string, 'left' | 'right'>;
+}
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `visibleColumns` | `string[]` | Array of visible column IDs. |
+| `sort` | `{ field: string; direction: 'asc' \| 'desc' }` | Current sort configuration, or `undefined` if no sort is active. |
+| `columnOrder` | `string[]` | Current column display order as an array of column IDs. |
+| `columnWidths` | `Record<string, number>` | Map of column IDs to their current pixel widths. Only includes columns that have been explicitly sized. |
+| `filters` | `IFilters` | Current filter state. |
+| `pinnedColumns` | `Record<string, 'left' \| 'right'>` | Map of column IDs to their pinned position. Only includes columns that are pinned. |
+
+## Save and Restore State
+
+A common use case is persisting the grid's column state to `localStorage` so it survives page reloads.
+
+```typescript
+
+const STORAGE_KEY = 'employee-grid-state';
+
+function EmployeeGrid() {
+  const apiRef = useRef<IOGridApi<Employee>>(null);
+
+  // Restore state on mount
+  useEffect(() => {
+    const saved = localStorage.getItem(STORAGE_KEY);
+    if (saved) {
+      try {
+        const state: Partial<IGridColumnState> = JSON.parse(saved);
+        apiRef.current?.applyColumnState(state);
+      } catch {
+        // Ignore corrupted state
+      }
+    }
+  }, []);
+
+  // Save state on any column change
+  const handleSaveState = useCallback(() => {
+    const state = apiRef.current?.getColumnState();
+    if (state) {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+    }
+  }, []);
+
+  return (
+    <OGrid<Employee>
+      ref={apiRef}
+      columns={columns}
+      data={data}
+      getRowId={(e) => e.id}
+      onSortChange={handleSaveState}
+      onFiltersChange={handleSaveState}
+      onVisibleColumnsChange={handleSaveState}
+      onColumnOrderChange={handleSaveState}
+      onColumnResized={handleSaveState}
+    />
+  );
+}
+```
+
+## Dynamic Data Updates
+
+Use `setRowData` and `setLoading` for imperative data updates, such as polling or WebSocket-driven refresh.
+
+```typescript
+function LiveGrid() {
+  const apiRef = useRef<IOGridApi<StockQuote>>(null);
+
+  useEffect(() => {
+    const ws = new WebSocket('wss://quotes.example.com');
+
+    ws.onmessage = (event) => {
+      const quotes: StockQuote[] = JSON.parse(event.data);
+      apiRef.current?.setRowData(quotes);
+    };
+
+    ws.onopen = () => {
+      apiRef.current?.setLoading(false);
+    };
+
+    return () => ws.close();
+  }, []);
+
+  return (
+    <OGrid<StockQuote>
+      ref={apiRef}
+      columns={columns}
+      data={[]}
+      isLoading={true}
+      getRowId={(q) => q.symbol}
+    />
+  );
+}
+```
+
+## Programmatic Row Selection
+
+```typescript
+function SelectableGrid() {
+  const apiRef = useRef<IOGridApi<Employee>>(null);
+
+  return (
+    <>
+      <div>
+        <button onClick={() => apiRef.current?.selectAll()}>
+          Select All
+        </button>
+        <button onClick={() => apiRef.current?.deselectAll()}>
+          Deselect All
+        </button>
+        <button
+          onClick={() => {
+            const selected = apiRef.current?.getSelectedRows() ?? [];
+            console.log('Selected IDs:', selected);
+          }}
+        >
+          Log Selection
+        </button>
+        <button
+          onClick={() => {
+            // Select specific rows by their IDs
+            apiRef.current?.setSelectedRows([1, 3, 5]);
+          }}
+        >
+          Select Rows 1, 3, 5
+        </button>
+      </div>
+      <OGrid<Employee>
+        ref={apiRef}
+        columns={columns}
+        data={data}
+        getRowId={(e) => e.id}
+        rowSelection="multiple"
+      />
+    </>
+  );
+}
+```
+
+## Programmatic Filter Control
+
+```typescript
+function FilteredGrid() {
+  const apiRef = useRef<IOGridApi<Employee>>(null);
+
+  const showOnlyEngineering = () => {
+    apiRef.current?.setFilterModel({
+      department: { type: 'multiSelect', value: ['Engineering'] },
+    });
+  };
+
+  const clearFilters = () => {
+    apiRef.current?.setFilterModel({});
+  };
+
+  const applyMultipleFilters = () => {
+    // Apply column state which includes filters along with other state
+    apiRef.current?.applyColumnState({
+      filters: {
+        department: { type: 'multiSelect', value: ['Engineering', 'Product'] },
+        name: { type: 'text', value: 'John' },
+      },
+      sort: { field: 'name', direction: 'asc' },
+    });
+  };
+
+  return (
+    <>
+      <button onClick={showOnlyEngineering}>Engineering Only</button>
+      <button onClick={clearFilters}>Clear Filters</button>
+      <button onClick={applyMultipleFilters}>Apply Preset</button>
+      <OGrid<Employee>
+        ref={apiRef}
+        columns={columns}
+        data={data}
+        getRowId={(e) => e.id}
+      />
+    </>
+  );
+}
+```