@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/column-groups.mdx

@@ -0,0 +1,290 @@
+---
+sidebar_position: 10
+title: Column Groups
+description: Multi-row grouped column headers with arbitrary nesting
+---
+
+
+# Column Groups
+
+Group related columns under shared parent headers. OGrid supports arbitrarily nested column groups that render as multi-row `<thead>` headers.
+
+## Live Demo
+
+<ColumnGroupsDemo />
+
+:::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
+
+interface Person {
+  id: number;
+  name: string;
+  age: number;
+  email: string;
+  department: string;
+  salary: number;
+  status: string;
+}
+
+const columns: (IColumnDef<Person> | IColumnGroupDef<Person>)[] = [
+  {
+    headerName: 'Personal Info',
+    children: [
+      { columnId: 'name', name: 'Name' },
+      { columnId: 'age', name: 'Age', type: 'numeric' },
+      { columnId: 'email', name: 'Email' },
+    ],
+  },
+  {
+    headerName: 'Employment',
+    children: [
+      { columnId: 'department', name: 'Department' },
+      {
+        columnId: 'salary',
+        name: 'Salary',
+        type: 'numeric',
+        valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+      },
+      { columnId: 'status', name: 'Status' },
+    ],
+  },
+];
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(p) => p.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: [
+      {
+        headerName: 'Personal Info',
+        children: [
+          { columnId: 'name', name: 'Name' },
+          { columnId: 'age', name: 'Age', type: 'numeric' },
+          { columnId: 'email', name: 'Email' },
+        ],
+      },
+      {
+        headerName: 'Employment',
+        children: [
+          { columnId: 'department', name: 'Department' },
+          {
+            columnId: 'salary', name: 'Salary', type: 'numeric',
+            valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+          },
+          { columnId: 'status', name: 'Status' },
+        ],
+      },
+    ],
+    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 = [
+  {
+    headerName: 'Personal Info',
+    children: [
+      { columnId: 'name', name: 'Name' },
+      { columnId: 'age', name: 'Age', type: 'numeric' },
+      { columnId: 'email', name: 'Email' },
+    ],
+  },
+  {
+    headerName: 'Employment',
+    children: [
+      { columnId: 'department', name: 'Department' },
+      {
+        columnId: 'salary', name: 'Salary', type: 'numeric',
+        valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+      },
+      { columnId: 'status', name: 'Status' },
+    ],
+  },
+];
+
+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: [
+    {
+      headerName: 'Personal Info',
+      children: [
+        { columnId: 'name', name: 'Name' },
+        { columnId: 'age', name: 'Age', type: 'numeric' },
+        { columnId: 'email', name: 'Email' },
+      ],
+    },
+    {
+      headerName: 'Employment',
+      children: [
+        { columnId: 'department', name: 'Department' },
+        {
+          columnId: 'salary',
+          name: 'Salary',
+          type: 'numeric',
+          valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+        },
+        { columnId: 'status', name: 'Status' },
+      ],
+    },
+  ],
+  data: people,
+  getRowId: (p) => p.id,
+  pageSize: 10,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+This renders a two-row header: the first row shows "Personal Info" spanning three columns and "Employment" spanning three columns, with the individual column names in the second row.
+
+## How It Works
+
+Column groups use the `IColumnGroupDef<T>` type. A group has a `headerName` (the text displayed in the group header cell) and a `children` array that can contain either `IColumnDef` items or nested `IColumnGroupDef` items.
+
+```tsx
+// IColumnGroupDef<T>
+{
+  headerName: string;
+  children: (IColumnGroupDef<T> | IColumnDef<T>)[];
+}
+```
+
+When the `columns` prop contains groups, OGrid internally calls `buildHeaderRows()` to produce a multi-row header model. Each group header cell spans the correct number of leaf columns via `colSpan`.
+
+### Nested Groups
+
+Groups can be nested to any depth. Each level adds another header row.
+
+```tsx
+const columns: (IColumnDef<Row> | IColumnGroupDef<Row>)[] = [
+  {
+    headerName: 'Contact',
+    children: [
+      {
+        headerName: 'Name',
+        children: [
+          { columnId: 'firstName', name: 'First' },
+          { columnId: 'lastName', name: 'Last' },
+        ],
+      },
+      { columnId: 'email', name: 'Email' },
+    ],
+  },
+  { columnId: 'role', name: 'Role' },
+];
+```
+
+This produces three header rows:
+
+| Contact (span 3) | Role (span 1, rowSpan 3) |
+|---|---|
+| Name (span 2) | Email (rowSpan 2) | |
+| First | Last | | |
+
+### Mixing Groups and Standalone Columns
+
+Standalone `IColumnDef` items at the top level are valid alongside groups. They span all header rows vertically.
+
+## Group Header Behavior
+
+Group headers are display-only:
+
+- **Not sortable.** Clicking a group header does nothing.
+- **Not filterable.** No filter icon or popover appears on group headers.
+- **Not resizable.** Group headers cannot be dragged to resize.
+- **Centered text.** Group header labels are centered over their children by default.
+
+Sorting, filtering, and resizing remain available on the leaf column headers beneath the groups.
+
+## Props Reference
+
+| Type | Field | Description |
+|---|---|---|
+| `IColumnGroupDef<T>` | `headerName` | Display text for the group header |
+| `IColumnGroupDef<T>` | `children` | Array of child columns or nested groups |
+| `IOGridProps<T>` | `columns` | Accepts `(IColumnDef<T> \| IColumnGroupDef<T>)[]` |
+
+## Related
+
+- [Column Pinning](./column-pinning) -- pin grouped columns to the left edge
+- [Column Chooser](./column-chooser) -- show/hide columns within groups

package/bundled-docs/features/column-pinning.mdx

@@ -0,0 +1,282 @@
+---
+sidebar_position: 11
+title: Column Pinning
+description: Pin columns to the left edge so they stay visible during horizontal scroll
+---
+
+
+# Column Pinning
+
+Pin columns to the left edge of the grid so they remain visible while the user scrolls horizontally through the remaining columns.
+
+## Live Demo
+
+<ColumnPinningDemo />
+
+:::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
+
+interface Person {
+  id: number;
+  name: string;
+  email: string;
+  department: string;
+  salary: number;
+  status: string;
+  age: number;
+  startDate: string;
+}
+
+const columns: IColumnDef<Person>[] = [
+  { columnId: 'name', name: 'Name', pinned: 'left', defaultWidth: 160 },
+  { columnId: 'email', name: 'Email', defaultWidth: 220 },
+  { columnId: 'department', name: 'Department', defaultWidth: 160 },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    type: 'numeric',
+    defaultWidth: 120,
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+  { columnId: 'status', name: 'Status', defaultWidth: 120 },
+  { columnId: 'age', name: 'Age', type: 'numeric', defaultWidth: 80 },
+  { columnId: 'startDate', name: 'Start Date', defaultWidth: 130 },
+];
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(p) => p.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', pinned: 'left', defaultWidth: 160 },
+      { columnId: 'email', name: 'Email', defaultWidth: 220 },
+      { columnId: 'department', name: 'Department', defaultWidth: 160 },
+      {
+        columnId: 'salary', name: 'Salary', type: 'numeric', defaultWidth: 120,
+        valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+      },
+      { columnId: 'status', name: 'Status', defaultWidth: 120 },
+      { columnId: 'age', name: 'Age', type: 'numeric', defaultWidth: 80 },
+      { columnId: 'startDate', name: 'Start Date', defaultWidth: 130 },
+    ] as IColumnDef<Person>[],
+    data: people,
+    getRowId: (item: Person) => item.id,
+  };
+}
+```
+
+:::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', pinned: 'left', defaultWidth: 160 },
+  { columnId: 'email', name: 'Email', defaultWidth: 220 },
+  { columnId: 'department', name: 'Department', defaultWidth: 160 },
+  {
+    columnId: 'salary', name: 'Salary', type: 'numeric', defaultWidth: 120,
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+  { columnId: 'status', name: 'Status', defaultWidth: 120 },
+  { columnId: 'age', name: 'Age', type: 'numeric', defaultWidth: 80 },
+  { columnId: 'startDate', name: 'Start Date', defaultWidth: 130 },
+];
+
+const gridProps = {
+  columns,
+  data: people,
+  getRowId: (item) => item.id,
+};
+</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', pinned: 'left', defaultWidth: 160 },
+    { columnId: 'email', name: 'Email', defaultWidth: 220 },
+    { columnId: 'department', name: 'Department', defaultWidth: 160 },
+    {
+      columnId: 'salary',
+      name: 'Salary',
+      type: 'numeric',
+      defaultWidth: 120,
+      valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+    },
+    { columnId: 'status', name: 'Status', defaultWidth: 120 },
+    { columnId: 'age', name: 'Age', type: 'numeric', defaultWidth: 80 },
+    { columnId: 'startDate', name: 'Start Date', defaultWidth: 130 },
+  ],
+  data: people,
+  getRowId: (p) => p.id,
+  pageSize: 10,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+The "Name" column stays fixed on the left while all other columns scroll normally.
+
+## How It Works
+
+Set `pinned: 'left'` on any `IColumnDef` to pin it. The grid renders pinned columns with CSS `position: sticky` and a calculated `left` offset so multiple pinned columns stack correctly.
+
+```tsx
+{ columnId: 'name', name: 'Name', pinned: 'left' }
+```
+
+Pinned columns:
+
+- Use **sticky positioning** so they stay visible during horizontal scroll.
+- Stack left-to-right in the order they appear in the `columns` array.
+- Work with all grid features: sorting, filtering, editing, cell selection, and context menu.
+
+### With Row Selection
+
+When `rowSelection` is `'single'` or `'multiple'`, OGrid inserts a checkbox column at the far left. Pinned columns appear after the checkbox column, and both stay visible during scroll.
+
+```tsx
+<OGrid
+  columns={columns}
+  data={rows}
+  getRowId={(r) => r.id}
+  rowSelection="multiple"
+/>
+```
+
+### With Column Groups
+
+Pinning works inside column groups. Set `pinned: 'left'` on the leaf `IColumnDef` items within a group. The group header will span correctly over the pinned columns.
+
+```tsx
+const columns = [
+  {
+    headerName: 'Identity',
+    children: [
+      { columnId: 'id', name: 'ID', pinned: 'left' },
+      { columnId: 'name', name: 'Name', pinned: 'left' },
+    ],
+  },
+  { columnId: 'email', name: 'Email' },
+];
+```
+
+## Persisting Pin State
+
+Pin state can be saved and restored via the Grid API, just like column widths and sort order:
+
+```tsx
+const gridRef = useRef<IOGridApi<Row>>(null);
+
+// Save pin state (e.g. to localStorage)
+const state = gridRef.current.getColumnState();
+// state.pinnedColumns → { name: 'left' }
+localStorage.setItem('gridState', JSON.stringify(state));
+
+// Restore pin state on mount
+const saved = JSON.parse(localStorage.getItem('gridState'));
+gridRef.current.applyColumnState(saved);
+```
+
+### `onColumnPinned` Callback
+
+Listen for pin changes to persist state automatically:
+
+```tsx
+<OGrid
+  columns={columns}
+  data={rows}
+  getRowId={(r) => r.id}
+  ref={gridRef}
+  onColumnPinned={(columnId, pinned) => {
+    // pinned is 'left', 'right', or null (unpinned)
+    const state = gridRef.current.getColumnState();
+    localStorage.setItem('gridState', JSON.stringify(state));
+  }}
+/>
+```
+
+## Props Reference
+
+| Type | Field | Values | Description |
+|---|---|---|---|
+| `IColumnMeta` | `pinned` | `'left' \| 'right'` | Pin column to left or right edge |
+| `IOGridProps` | `onColumnPinned` | `(columnId, pinned) => void` | Called when a column is pinned or unpinned |
+| `IGridColumnState` | `pinnedColumns` | `Record<string, 'left' \| 'right'>` | Pinned columns in saved state |
+| `IColumnMeta` | `minWidth` | `number` | Minimum width in pixels (useful for pinned columns) |
+| `IColumnMeta` | `defaultWidth` | `number` | Initial width in pixels |
+
+:::tip
+Pin identifying columns like "Name" or "ID" so users always know which row they are looking at, even when scrolling through many columns.
+:::
+
+## Related
+
+- [Column Groups](./column-groups) -- group headers with pinned leaf columns
+- [Column Chooser](./column-chooser) -- show/hide columns (including pinned ones)
+- [Keyboard Navigation](./keyboard-navigation) -- arrow keys work across pinned and scrollable columns