@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/context-menu.mdx

@@ -0,0 +1,216 @@
+---
+sidebar_position: 13
+title: Context Menu
+description: Right-click cell menu with clipboard, undo/redo, and export actions
+---
+
+
+# Context Menu
+
+Right-click any cell to open a context menu with clipboard operations, undo/redo, and selection actions. Keyboard shortcut labels are displayed alongside each item.
+
+## Live Demo
+
+<ContextMenuDemo />
+
+:::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
+
+function App() {
+  const undoRedo = useUndoRedo();
+
+  return (
+    <OGrid
+      columns={columns}
+      data={data}
+      getRowId={(r) => r.id}
+      editable
+      onCellValueChanged={(e) => {
+        undoRedo.pushChange(e);
+        // persist change...
+      }}
+      onUndo={undoRedo.undo}
+      onRedo={undoRedo.redo}
+      canUndo={undoRedo.canUndo}
+      canRedo={undoRedo.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
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: [
+      { columnId: 'name', name: 'Name', editable: true },
+      { columnId: 'department', name: 'Department' },
+      {
+        columnId: 'salary', name: 'Salary', type: 'numeric', editable: true,
+        valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+      },
+    ] as IColumnDef<Person>[],
+    data: people,
+    getRowId: (item: Person) => item.id,
+    editable: true,
+    contextMenu: 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 columns: IColumnDef<Person>[] = [
+  { columnId: 'name', name: 'Name', editable: true },
+  { columnId: 'department', name: 'Department' },
+  {
+    columnId: 'salary', name: 'Salary', type: 'numeric', editable: true,
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+const gridProps = {
+  columns,
+  data: people,
+  getRowId: (item) => item.id,
+  editable: true,
+  contextMenu: 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 grid = new OGrid(document.getElementById('grid'), {
+  columns: columns,
+  data: data,
+  getRowId: (r) => r.id,
+  editable: true,
+});
+
+// Right-click any cell to see the context menu
+// Undo/redo is handled automatically by the JS package
+```
+
+  </TabItem>
+</Tabs>
+
+Right-click a cell to see the context menu with all available actions.
+
+## How It Works
+
+The context menu is built in and requires no additional configuration. It appears when the user right-clicks on a data cell. Right-clicking on headers, empty space, or outside the grid does not open the menu.
+
+### Built-in Menu Items
+
+| Item | Shortcut | Description |
+|---|---|---|
+| Undo | Ctrl+Z | Undo the last cell edit |
+| Redo | Ctrl+Y | Redo the last undone edit |
+| Copy | Ctrl+C | Copy selected cells to clipboard |
+| Cut | Ctrl+X | Cut selected cells to clipboard |
+| Paste | Ctrl+V | Paste clipboard contents into selected cells |
+| Select all | Ctrl+A | Select all **cells** in the grid (cell selection, not row selection) |
+
+On macOS, "Ctrl" is automatically displayed as the Command symbol.
+
+:::info Cell Selection vs Row Selection
+The "Select all" menu item selects all **cells** for copy/paste/fill operations. This is different from row selection, where the header checkbox selects all **rows** for bulk operations. See [Row Selection](./row-selection) for details on row-level selection.
+:::
+
+### Undo/Redo State
+
+The Undo and Redo items reflect their availability through the `canUndo` and `canRedo` props. When `canUndo` is `false`, the Undo item appears disabled (grayed out). Same for Redo.
+
+```tsx
+<OGrid
+  // ...
+  onUndo={undoRedo.undo}
+  onRedo={undoRedo.redo}
+  canUndo={undoRedo.canUndo}
+  canRedo={undoRedo.canRedo}
+/>
+```
+
+If `onUndo` and `onRedo` are not provided, the undo/redo items still appear but do nothing.
+
+### Cell-Only Activation
+
+The context menu only opens on cell right-clicks. This is intentional:
+
+- **Header right-click**: default browser context menu (no grid menu).
+- **Empty space right-click**: default browser context menu.
+- **Cell right-click**: grid context menu with actions scoped to the current selection.
+
+### Copy/Cut Disabled State
+
+The Copy and Cut items are disabled when no cells are selected. Once the user clicks a cell or selects a range, these items become active.
+
+## Props Reference
+
+| Type | Field | Description |
+|---|---|---|
+| `IOGridProps<T>` | `onUndo` | Callback invoked when Undo is clicked |
+| `IOGridProps<T>` | `onRedo` | Callback invoked when Redo is clicked |
+| `IOGridProps<T>` | `canUndo` | `boolean` -- disables Undo item when `false` |
+| `IOGridProps<T>` | `canRedo` | `boolean` -- disables Redo item when `false` |
+| `IOGridProps<T>` | `cellSelection` | `boolean` -- context menu requires cell selection (default `true`) |
+
+## Related
+
+- [Keyboard Navigation](./keyboard-navigation) -- same shortcuts work via keyboard
+- [CSV Export](./csv-export) -- export is also available via the `exportToCsv` utility
+- [Grid API](./grid-api) -- programmatic access to selection and data

package/bundled-docs/features/csv-export.mdx

@@ -0,0 +1,227 @@
+---
+sidebar_position: 15
+title: CSV Export
+description: Export grid data to a CSV file with one function call
+---
+
+
+# CSV Export
+
+Export grid data to a downloadable CSV file using the `exportToCsv` utility from core. It respects column visibility and applies `valueFormatter` so the exported values match what the user sees.
+
+## Live Demo
+
+<CsvExportDemo />
+
+:::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
+
+function ExportButton({ data, columns }: { data: Row[]; columns: IColumnDef<Row>[] }) {
+  const handleExport = () => {
+    exportToCsv(
+      data,
+      columns.map((col) => ({ columnId: col.columnId, name: col.name })),
+      (item, columnId) => {
+        const col = columns.find((c) => c.columnId === columnId);
+        if (!col) return '';
+        const value = col.valueGetter ? col.valueGetter(item) : (item as Record<string, unknown>)[columnId];
+        return col.valueFormatter ? col.valueFormatter(value, item) : String(value ?? '');
+      },
+      'my-data.csv'
+    );
+  };
+
+  return <button onClick={handleExport}>Export to CSV</button>;
+}
+```
+
+:::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,
+  template: `<button (click)="handleExport()">Export to CSV</button>`
+})
+export class ExportButtonComponent {
+  data: Row[] = [];
+  columns: IColumnDef<Row>[] = [];
+
+  handleExport() {
+    exportToCsv(
+      this.data,
+      this.columns.map((col) => ({ columnId: col.columnId, name: col.name })),
+      (item: Row, columnId: string) => {
+        const col = this.columns.find((c) => c.columnId === columnId);
+        if (!col) return '';
+        const value = col.valueGetter ? col.valueGetter(item) : (item as Record<string, unknown>)[columnId];
+        return col.valueFormatter ? col.valueFormatter(value as unknown, item) : String(value ?? '');
+      },
+      'my-data.csv'
+    );
+  }
+}
+```
+
+:::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 props = defineProps<{ data: Row[]; columns: IColumnDef<Row>[] }>();
+
+function handleExport() {
+  exportToCsv(
+    props.data,
+    props.columns.map((col) => ({ columnId: col.columnId, name: col.name })),
+    (item, columnId) => {
+      const col = props.columns.find((c) => c.columnId === columnId);
+      if (!col) return '';
+      const value = col.valueGetter ? col.valueGetter(item) : (item as Record<string, unknown>)[columnId];
+      return col.valueFormatter ? col.valueFormatter(value, item) : String(value ?? '');
+    },
+    'my-data.csv'
+  );
+}
+</script>
+
+<template>
+  <button @click="handleExport">Export to CSV</button>
+</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: columns,
+  data: data,
+  getRowId: (r) => r.id,
+});
+
+// Export to CSV
+document.getElementById('export-btn').addEventListener('click', () => {
+  exportToCsv(
+    data,
+    columns.map((col) => ({ columnId: col.columnId, name: col.name })),
+    (item, columnId) => {
+      const col = columns.find((c) => c.columnId === columnId);
+      if (!col) return '';
+      const value = item[columnId];
+      return col.valueFormatter ? col.valueFormatter(value, item) : String(value ?? '');
+    },
+    'my-data.csv'
+  );
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## How It Works
+
+### The `exportToCsv` Function
+
+```tsx
+exportToCsv<T>(
+  items: T[],
+  columns: CsvColumn[],
+  getValue: (item: T, columnId: string) => string,
+  filename?: string
+): void
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `items` | `T[]` | The row data to export |
+| `columns` | `CsvColumn[]` | Array of `{ columnId, name }` defining which columns to include and their header names |
+| `getValue` | `(item, columnId) => string` | Function to extract the display value for each cell |
+| `filename` | `string` (optional) | Download filename (default: `'export.csv'`) |
+
+The function:
+1. Builds a CSV header row from `columns[].name`.
+2. Iterates over each item and calls `getValue` for each column.
+3. Escapes values containing commas, quotes, or newlines.
+4. Triggers a browser download with the specified filename.
+
+### Context Menu Integration
+
+When `cellSelection` is enabled (the default), the context menu does not include a dedicated "Export to CSV" item. Use the `exportToCsv` utility directly from a toolbar button or custom UI element.
+
+### Exporting Visible Columns Only
+
+Filter the columns array to only include visible columns before passing to `exportToCsv`.
+
+```tsx
+const visibleCols = columns.filter((col) => visibleColumns.has(col.columnId));
+
+exportToCsv(
+  data,
+  visibleCols.map((col) => ({ columnId: col.columnId, name: col.name })),
+  getValue,
+  'filtered-export.csv'
+);
+```
+
+### Formatted Values
+
+Use `valueFormatter` in your `getValue` function so exported data matches the display. For example, a currency column that shows "$1,234.56" in the grid will export that same string.
+
+```tsx
+const getValue = (item: Row, columnId: string) => {
+  const col = columns.find((c) => c.columnId === columnId)!;
+  const raw = col.valueGetter ? col.valueGetter(item) : (item as any)[columnId];
+  return col.valueFormatter ? col.valueFormatter(raw, item) : String(raw ?? '');
+};
+```
+
+## Props Reference
+
+| Type | Field | Description |
+|---|---|---|
+| `CsvColumn` | `columnId` | Column identifier |
+| `CsvColumn` | `name` | Header label in the CSV |
+
+## Related
+
+- [Context Menu](./context-menu) -- clipboard operations for quick copy/paste
+- [Grid API](./grid-api) -- access current data and column state programmatically
+- [Column Chooser](./column-chooser) -- determines which columns are visible for export