@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/editing.mdx

@@ -0,0 +1,377 @@
+---
+sidebar_position: 4
+title: Editing & Clipboard
+description: Inline editing, clipboard operations, fill handle, and undo/redo
+---
+
+
+# Editing & Clipboard
+
+OGrid supports inline cell editing, clipboard copy/paste, drag-to-fill, and undo/redo -- all working together through `onCellValueChanged` and `valueParser`.
+
+## Live Demo
+
+<CellEditingDemo />
+
+:::tip Try it in your framework
+The demo above uses Radix UI for styling. To see this feature with your framework's design system (Fluent UI, Material UI, Vuetify, PrimeNG, etc.), click **"Open in online demo"** below the demo.
+:::
+
+## Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+const DEPTS = ['Engineering', 'Marketing', 'Sales', 'Finance', 'Operations'];
+const STATUSES = ['Active', 'Draft', 'Archived'];
+
+const columns = [
+  { columnId: 'name', name: 'Name', editable: true },
+  {
+    columnId: 'department',
+    name: 'Department',
+    editable: true,
+    cellEditor: 'richSelect',
+    cellEditorParams: { values: DEPTS },
+  },
+  {
+    columnId: 'status',
+    name: 'Status',
+    editable: true,
+    cellEditor: 'select',
+    cellEditorParams: { values: STATUSES },
+  },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    editable: true,
+    type: 'numeric',
+    valueParser: ({ newValue }) => {
+      const num = Number(newValue);
+      return isNaN(num) || num < 0 ? undefined : num; // reject invalid
+    },
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+function App() {
+  const [data, setData] = useState(initialData);
+  const { handleCellValueChanged, undo, redo, canUndo, canRedo } = useUndoRedo({
+    data, setData, getRowId: (item) => item.id,
+  });
+
+  return (
+    <OGrid
+      columns={columns}
+      data={data}
+      getRowId={(item) => item.id}
+      editable
+      onCellValueChanged={handleCellValueChanged}
+      onUndo={undo}
+      onRedo={redo}
+      canUndo={canUndo}
+      canRedo={canRedo}
+    />
+  );
+}
+```
+
+:::tip Switching UI libraries
+The `OGrid` component has the same props across all React UI packages. To switch, just change the import:
+
+- **Radix** (lightweight, default): `from '@alaarab/ogrid-react-radix'`
+- **Fluent UI** (Microsoft 365 / SPFx): `from '@alaarab/ogrid-react-fluent'` — wrap in `<FluentProvider>`
+- **Material UI** (MUI v7): `from '@alaarab/ogrid-react-material'` — wrap in `<ThemeProvider>`
+:::
+
+  </TabItem>
+  <TabItem value="angular" label="Angular">
+
+```typescript
+
+const DEPTS = ['Engineering', 'Marketing', 'Sales', 'Finance', 'Operations'];
+const STATUSES = ['Active', 'Draft', 'Archived'];
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: [
+      { columnId: 'name', name: 'Name', editable: true },
+      {
+        columnId: 'department', name: 'Department', editable: true,
+        cellEditor: 'richSelect', cellEditorParams: { values: DEPTS },
+      },
+      {
+        columnId: 'status', name: 'Status', editable: true,
+        cellEditor: 'select', cellEditorParams: { values: STATUSES },
+      },
+      {
+        columnId: 'salary', name: 'Salary', editable: true, type: 'numeric',
+        valueParser: ({ newValue }: any) => {
+          const num = Number(newValue);
+          return isNaN(num) || num < 0 ? undefined : num;
+        },
+        valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+      },
+    ] as IColumnDef<Person>[],
+    data: initialData,
+    getRowId: (item: Person) => item.id,
+    editable: true,
+  };
+}
+```
+
+:::tip Switching UI libraries
+Same component API across Angular packages. To switch, just change the import:
+
+- **Radix (CDK)**: `from '@alaarab/ogrid-angular-radix'` *(default, lightweight)*
+- **Angular Material**: `from '@alaarab/ogrid-angular-material'`
+- **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
+
+All components are standalone — no NgModule required.
+:::
+
+  </TabItem>
+  <TabItem value="vue" label="Vue">
+
+```vue
+<script setup lang="ts">
+
+const DEPTS = ['Engineering', 'Marketing', 'Sales', 'Finance', 'Operations'];
+const STATUSES = ['Active', 'Draft', 'Archived'];
+
+const columns: IColumnDef<Person>[] = [
+  { columnId: 'name', name: 'Name', editable: true },
+  {
+    columnId: 'department', name: 'Department', editable: true,
+    cellEditor: 'richSelect', cellEditorParams: { values: DEPTS },
+  },
+  {
+    columnId: 'status', name: 'Status', editable: true,
+    cellEditor: 'select', cellEditorParams: { values: STATUSES },
+  },
+  {
+    columnId: 'salary', name: 'Salary', editable: true, type: 'numeric',
+    valueParser: ({ newValue }) => {
+      const num = Number(newValue);
+      return isNaN(num) || num < 0 ? undefined : num;
+    },
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+const gridProps = {
+  columns,
+  data: initialData,
+  getRowId: (item) => item.id,
+  editable: true,
+};
+</script>
+
+<template>
+  <OGrid :gridProps="gridProps" />
+</template>
+```
+
+:::tip Switching UI libraries
+Same component API across Vue packages. To switch, just change the import:
+
+- **Radix (Headless UI)**: `from '@alaarab/ogrid-vue-radix'` *(default, lightweight)*
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'` — wrap in `<v-app>` for theming
+- **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
+:::
+
+  </TabItem>
+  <TabItem value="js" label="Vanilla JS">
+
+```js
+
+const DEPTS = ['Engineering', 'Marketing', 'Sales', 'Finance', 'Operations'];
+const STATUSES = ['Active', 'Draft', 'Archived'];
+
+const grid = new OGrid(document.getElementById('grid'), {
+  columns: [
+    { columnId: 'name', name: 'Name', editable: true },
+    {
+      columnId: 'department',
+      name: 'Department',
+      editable: true,
+      cellEditor: 'richSelect',
+      cellEditorParams: { values: DEPTS },
+    },
+    {
+      columnId: 'status',
+      name: 'Status',
+      editable: true,
+      cellEditor: 'select',
+      cellEditorParams: { values: STATUSES },
+    },
+    {
+      columnId: 'salary',
+      name: 'Salary',
+      editable: true,
+      type: 'numeric',
+      valueParser: ({ newValue }) => {
+        const num = Number(newValue);
+        return isNaN(num) || num < 0 ? undefined : num;
+      },
+      valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+    },
+  ],
+  data: initialData,
+  getRowId: (item) => item.id,
+  editable: true,
+});
+
+// Listen for cell edits
+grid.on('cellValueChanged', (event) => {
+  console.log(`${event.columnId} changed to ${event.newValue}`);
+});
+```
+
+  </TabItem>
+</Tabs>
+
+This single setup gives you inline editing, clipboard paste, fill handle, and full undo/redo.
+
+## Inline Editing
+
+Double-click or press **F2** to edit. **Enter** commits and moves down, **Tab** commits and moves right, **Escape** cancels.
+
+### Built-in Editors
+
+| `cellEditor` | Description |
+|--------------|-------------|
+| `'text'` (default) | Standard text input |
+| `'select'` | Dropdown from `cellEditorParams.values` |
+| `'checkbox'` | Toggle boolean |
+| `'richSelect'` | Searchable dropdown with keyboard nav |
+
+### Rich Select
+
+```tsx
+{
+  columnId: 'category',
+  editable: true,
+  cellEditor: 'richSelect',
+  cellEditorParams: {
+    values: ['Engineering', 'Design', 'Marketing', 'Sales'],
+    formatValue: (v) => `Dept: ${v}`,
+  },
+}
+```
+
+### Per-Row Editability
+
+```tsx
+{ columnId: 'name', editable: (item) => item.status !== 'locked' }
+```
+
+### Custom Editor
+
+Pass a component to `cellEditor`. Use `cellEditorPopup: true` for a popover:
+
+```tsx
+function DateEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorProps<Task>) {
+  return (
+    <input
+      type="date"
+      value={value as string}
+      onChange={(e) => onValueChange(e.target.value)}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') onCommit();
+        if (e.key === 'Escape') onCancel();
+      }}
+      autoFocus
+    />
+  );
+}
+
+// In column def:
+{ columnId: 'dueDate', editable: true, cellEditor: DateEditor, cellEditorPopup: true }
+```
+
+### Value Parsing
+
+`valueParser` validates input for editing, paste, fill, and delete. Return `undefined` to reject:
+
+```tsx
+{ columnId: 'age', editable: true, type: 'numeric',
+  valueParser: ({ newValue }) => {
+    const num = Number(newValue);
+    return isNaN(num) || num < 0 || num > 150 ? undefined : num;
+  },
+}
+```
+
+## Clipboard
+
+<ClipboardDemo />
+
+Standard keyboard shortcuts on selected cells:
+
+| Key | Action | Requires `editable` |
+|-----|--------|-------------------|
+| Ctrl+C (Cmd+C) | Copy as tab-delimited text | No |
+| Ctrl+V (Cmd+V) | Paste into cells | Yes |
+| Ctrl+X (Cmd+X) | Cut (copy + clear) | Yes |
+| Delete / Backspace | Clear selected cells | Yes |
+
+- **Copy** uses `valueFormatter` so copied values match the display.
+- **Paste** calls `valueParser` on each value and fires `onCellValueChanged` per cell.
+
+## Fill Handle
+
+<FillHandleDemo />
+
+A small square at the bottom-right of the selection. Drag it down to fill cells with the source value (like Excel).
+
+- Requires `editable={true}` and `cellSelection={true}` (default).
+- Calls `valueParser` per cell -- return `undefined` to skip.
+- Each filled cell fires `onCellValueChanged`.
+- Uses `requestAnimationFrame` for smooth drag performance.
+
+## Undo / Redo
+
+The `useUndoRedo` hook tracks edit history (including paste, fill, and delete). See the quick example above.
+
+| Hook Input | Type | Description |
+|------------|------|-------------|
+| `data` | `T[]` | Current data array |
+| `setData` | `(data: T[]) => void` | State setter |
+| `getRowId` | `(item: T) => RowId` | Row identifier |
+
+| Hook Output | Type | Description |
+|-------------|------|-------------|
+| `handleCellValueChanged` | `(event) => void` | Wraps edits onto the undo stack |
+| `undo` / `redo` | `() => void` | Revert / re-apply |
+| `canUndo` / `canRedo` | `boolean` | Stack status |
+
+**Shortcuts:** Ctrl+Z (undo), Ctrl+Y (redo). Also available in the right-click [context menu](./context-menu).
+
+## Props Summary
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `editable` | `boolean` | Enable editing grid-wide (on `OGrid`) |
+| `editable` | `boolean \| (item: T) => boolean` | Per-column/row (on `IColumnDef`) |
+| `cellEditor` | `'text' \| 'select' \| 'checkbox' \| 'richSelect' \| ComponentType` | Editor type |
+| `cellEditorPopup` | `boolean` | Render custom editor in a popover |
+| `cellEditorParams` | `CellEditorParams` | Editor parameters (e.g., `{ values: [...] }`) |
+| `valueParser` | `(params) => unknown` | Validate on edit/paste/fill/delete. Return `undefined` to reject. |
+| `valueFormatter` | `(value, item) => string` | Format display & copy output |
+| `onCellValueChanged` | `(event) => void` | Fired after any cell value change |
+| `onUndo` / `onRedo` | `() => void` | Undo/redo callbacks |
+| `canUndo` / `canRedo` | `boolean` | Enable/disable undo/redo in context menu |
+
+## Related
+
+- [Spreadsheet Selection](./spreadsheet-selection) -- select cells for editing
+- [Context Menu](./context-menu) -- right-click menu with undo/redo
+- [Custom Cell Editors](../guides/custom-cell-editors) -- advanced editor guide

package/bundled-docs/features/filtering.mdx

@@ -0,0 +1,330 @@
+---
+sidebar_position: 2
+title: Filtering
+description: Column-level filtering with text, multi-select, and people filter types.
+---
+
+
+# Filtering
+
+OGrid supports four built-in filter types -- **text**, **multiSelect**, **people**, and **date** -- configured per column. Filters appear as popovers triggered from column headers.
+
+## Live Demo
+
+<FilteringDemo />
+
+:::tip Framework-Specific Styling
+The live demo above shows **React Radix UI** styling (lightweight default). To see how filter popovers look in your framework's design system, click the framework buttons above the demo to open online demo. Each framework renders filter UI with its native components (dropdowns, inputs, date pickers, etc.), so the styling matches your design system.
+:::
+
+## Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+const columns = [
+  {
+    columnId: 'name',
+    name: 'Name',
+    filterable: { type: 'text' },
+  },
+  {
+    columnId: 'department',
+    name: 'Department',
+    filterable: { type: 'multiSelect', filterField: 'department' },
+  },
+  {
+    columnId: 'status',
+    name: 'Status',
+    filterable: { type: 'multiSelect', filterField: 'status' },
+  },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    type: 'numeric' as const,
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(item) => item.id}
+      defaultPageSize={10}
+    />
+  );
+}
+```
+
+:::tip Switching UI libraries
+The `OGrid` component has the same props across all React UI packages. To switch, just change the import:
+
+- **Radix** (lightweight, default): `from '@alaarab/ogrid-react-radix'`
+- **Fluent UI** (Microsoft 365 / SPFx): `from '@alaarab/ogrid-react-fluent'` — wrap in `<FluentProvider>`
+- **Material UI** (MUI v7): `from '@alaarab/ogrid-react-material'` — wrap in `<ThemeProvider>`
+:::
+
+  </TabItem>
+  <TabItem value="angular" label="Angular">
+
+```typescript
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: [
+      { columnId: 'name', name: 'Name', filterable: { type: 'text' } },
+      {
+        columnId: 'department', name: 'Department',
+        filterable: { type: 'multiSelect', filterField: 'department' },
+      },
+      {
+        columnId: 'status', name: 'Status',
+        filterable: { type: 'multiSelect', filterField: 'status' },
+      },
+      {
+        columnId: 'salary', name: 'Salary', type: 'numeric',
+        valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+      },
+    ] as IColumnDef<Person>[],
+    data: people,
+    getRowId: (item: Person) => item.id,
+    defaultPageSize: 10,
+  };
+}
+```
+
+:::tip Switching UI libraries
+Same component API across Angular packages. To switch, just change the import:
+
+- **Radix (CDK)**: `from '@alaarab/ogrid-angular-radix'` *(default, lightweight)*
+- **Angular Material**: `from '@alaarab/ogrid-angular-material'`
+- **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
+
+All components are standalone — no NgModule required.
+:::
+
+  </TabItem>
+  <TabItem value="vue" label="Vue">
+
+```vue
+<script setup lang="ts">
+
+const columns: IColumnDef<Person>[] = [
+  { columnId: 'name', name: 'Name', filterable: { type: 'text' } },
+  {
+    columnId: 'department', name: 'Department',
+    filterable: { type: 'multiSelect', filterField: 'department' },
+  },
+  {
+    columnId: 'status', name: 'Status',
+    filterable: { type: 'multiSelect', filterField: 'status' },
+  },
+  {
+    columnId: 'salary', name: 'Salary', type: 'numeric',
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+const gridProps = {
+  columns,
+  data: people,
+  getRowId: (item) => item.id,
+  defaultPageSize: 10,
+};
+</script>
+
+<template>
+  <OGrid :gridProps="gridProps" />
+</template>
+```
+
+:::tip Switching UI libraries
+Same component API across Vue packages. To switch, just change the import:
+
+- **Radix (Headless UI)**: `from '@alaarab/ogrid-vue-radix'` *(default, lightweight)*
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'` — wrap in `<v-app>` for theming
+- **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
+:::
+
+  </TabItem>
+  <TabItem value="js" label="Vanilla JS">
+
+```js
+
+const grid = new OGrid(document.getElementById('grid'), {
+  columns: [
+    {
+      columnId: 'name',
+      name: 'Name',
+      filterable: { type: 'text' },
+    },
+    {
+      columnId: 'department',
+      name: 'Department',
+      filterable: { type: 'multiSelect', filterField: 'department' },
+    },
+    {
+      columnId: 'status',
+      name: 'Status',
+      filterable: { type: 'multiSelect', filterField: 'status' },
+    },
+    {
+      columnId: 'salary',
+      name: 'Salary',
+      type: 'numeric',
+      valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+    },
+  ],
+  data: people,
+  getRowId: (item) => item.id,
+  pageSize: 10,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## How It Works
+
+Set the `filterable` property on a column definition to an `IColumnFilterDef` object. The `type` field determines the filter UI:
+
+### Text Filter
+
+A simple text input. Filters rows where the column value contains the search string (case-insensitive).
+
+```tsx
+{ columnId: 'name', name: 'Name', filterable: { type: 'text' } }
+```
+
+### Multi-Select Filter
+
+A checkbox list with **Select All** and **Clear All** buttons. Users pick one or more values to include.
+
+```tsx
+{
+  columnId: 'status',
+  name: 'Status',
+  filterable: {
+    type: 'multiSelect',
+    filterField: 'status',       // field to filter on (defaults to columnId)
+    optionsSource: 'static',     // 'static' | 'api' | 'years'
+    options: ['Active', 'Draft', 'Archived'],
+  },
+}
+```
+
+**Options sources:**
+
+| `optionsSource` | Behavior |
+|-----------------|----------|
+| `'static'` | Uses the `options` array you provide. |
+| `'api'` | Calls `dataSource.fetchFilterOptions(field)` to load options dynamically. |
+| `'years'` | Auto-generates a year list (current year down, configurable via `yearsCount`). |
+| _(omitted)_ | Client-side: unique values extracted from the data array. Server-side: uses `'api'`. |
+
+### People Filter
+
+A search-as-you-type input that finds users via `dataSource.searchPeople(query)`. Displays `UserLike` objects with name, email, and photo.
+
+```tsx
+{
+  columnId: 'assignee',
+  name: 'Assignee',
+  filterable: { type: 'people' },
+}
+```
+
+:::info
+The people filter requires a `dataSource` with a `searchPeople` method. It is designed for directory lookups (e.g., Microsoft Graph, LDAP).
+:::
+
+### Date Filter
+
+A date range picker with **From** and **To** date inputs. Filters rows where the column value falls within the specified range.
+
+```tsx
+{
+  columnId: 'createdDate',
+  name: 'Created',
+  type: 'date',
+  filterable: { type: 'date' },
+}
+```
+
+:::tip
+Columns with `type: 'date'` automatically get date formatting, chronological sorting, and a native date input editor — no additional configuration needed.
+:::
+
+### Controlled vs. Uncontrolled
+
+- **Uncontrolled** -- the grid manages filter state internally. Filters reset when the component unmounts.
+- **Controlled** -- pass `filters` and `onFiltersChange` to own the filter state externally (e.g., for URL sync or persistence).
+
+```tsx
+function App() {
+  const [filters, setFilters] = useState<IFilters>({
+    status: { type: 'multiSelect', value: ['Active'] },
+    name: { type: 'text', value: 'John' },
+  });
+
+  return (
+    <OGrid
+      columns={columns}
+      data={tasks}
+      getRowId={(item) => item.id}
+      filters={filters}
+      onFiltersChange={setFilters}
+    />
+  );
+}
+```
+
+### Server-Side Filtering
+
+When using a `dataSource`, filter values are passed to `fetchPage()` in the `filters` param. The grid does not filter client-side.
+
+```tsx
+const dataSource: IDataSource<Task> = {
+  fetchPage: async ({ filters, page, pageSize, sort }) => {
+    const params = new URLSearchParams({ page: String(page), pageSize: String(pageSize) });
+    if (filters.status?.type === 'multiSelect') params.set('status', filters.status.value.join(','));
+    const res = await fetch(`/api/tasks?${params}`);
+    return res.json();
+  },
+  fetchFilterOptions: async (field) => {
+    const res = await fetch(`/api/tasks/filter-options/${field}`);
+    return res.json();
+  },
+  searchPeople: async (query) => {
+    const res = await fetch(`/api/users/search?q=${query}`);
+    return res.json();
+  },
+};
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `filterable` | `IColumnFilterDef` | -- | Set on `IColumnDef`. Defines filter type and options. |
+| `filterable.type` | `'text' \| 'multiSelect' \| 'people' \| 'date'` | -- | Filter UI type. |
+| `filterable.filterField` | `string` | `columnId` | Field name used in the filter model. |
+| `filterable.optionsSource` | `'api' \| 'static' \| 'years'` | auto | Where multi-select options come from. |
+| `filterable.options` | `string[]` | -- | Static options for multi-select. |
+| `filterable.yearsCount` | `number` | -- | Number of years to generate for `'years'` source. |
+| `filters` | `IFilters` | -- | Controlled filter state on `OGrid`. |
+| `onFiltersChange` | `(filters: IFilters) => void` | -- | Called when filters change (controlled mode). |
+
+## Related
+
+- [Sorting](./sorting) -- sort filtered results
+- [Pagination](./pagination) -- paginate filtered results