@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/cell-references.mdx

@@ -0,0 +1,225 @@
+---
+sidebar_position: 22
+title: Cell References
+description: Excel-style column letters (A, B, C...), row numbers, and a name box showing the active cell reference.
+---
+
+
+# Cell References
+
+Enable Excel-style cell references with a single prop. Column letter headers (A, B, C...) appear above the header row, row numbers show in the left gutter, and a name box in the toolbar displays the active cell reference (e.g. "A1", "C15").
+
+## Live Demo
+
+<CellReferencesDemo />
+
+:::tip Framework-Specific Styling
+The live demo above shows **React Radix UI** styling (lightweight default). To see how cell references look in your framework's design system, click the framework buttons above the demo to open online demo:
+- **React** -- Radix UI default theme
+- **Angular** -- Angular Material theme
+- **Vue** -- Vuetify theme
+- **JS** -- Vanilla JS default theme
+
+Each framework renders with its native components, 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' },
+  { columnId: 'age', name: 'Age', type: 'numeric' as const },
+  { columnId: 'email', name: 'Email' },
+  { columnId: 'department', name: 'Department' },
+  { 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}
+      cellReferences
+      defaultPageSize={25}
+      entityLabelPlural="people"
+    />
+  );
+}
+```
+
+:::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' },
+      { columnId: 'age', name: 'Age', type: 'numeric' },
+      { columnId: 'email', name: 'Email' },
+      { columnId: 'department', name: 'Department' },
+      {
+        columnId: 'salary', name: 'Salary', type: 'numeric',
+        valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+      },
+    ] as IColumnDef<Person>[],
+    data: people,
+    getRowId: (item: Person) => item.id,
+    cellReferences: true,
+    defaultPageSize: 25,
+    entityLabelPlural: 'people',
+  };
+}
+```
+
+:::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' },
+  { columnId: 'age', name: 'Age', type: 'numeric' },
+  { columnId: 'email', name: 'Email' },
+  { columnId: 'department', name: 'Department' },
+  {
+    columnId: 'salary', name: 'Salary', type: 'numeric',
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+const gridProps = {
+  columns,
+  data: people,
+  getRowId: (item) => item.id,
+  cellReferences: true,
+  defaultPageSize: 25,
+  entityLabelPlural: 'people',
+};
+</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' },
+    { columnId: 'age', name: 'Age', type: 'numeric' },
+    { columnId: 'email', name: 'Email' },
+    { columnId: 'department', name: 'Department' },
+    {
+      columnId: 'salary',
+      name: 'Salary',
+      type: 'numeric',
+      valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+    },
+  ],
+  data: people,
+  getRowId: (item) => item.id,
+  cellReferences: true,
+  pageSize: 25,
+  entityLabelPlural: 'people',
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## How It Works
+
+Setting `cellReferences` on the `OGrid` component enables three visual features together:
+
+### 1. Column Letter Headers
+
+A row of Excel-style column letters (A, B, C, ..., Z, AA, AB, ...) appears above the normal header row. These letters use base-26 encoding, matching the Excel convention:
+
+| Columns | Letters |
+|---------|---------|
+| 1--26 | A--Z |
+| 27--52 | AA--AZ |
+| 53--78 | BA--BZ |
+| 703+ | AAA, AAB, ... |
+
+### 2. Row Numbers
+
+A numbered gutter column appears on the left side of the grid showing the absolute row number (1, 2, 3, ...). Row numbers are consistent across pages -- page 2 with a page size of 25 starts at row 26, not row 1.
+
+:::info Row numbers without cell references
+You can show row numbers independently without the full cell references feature by using the `showRowNumbers` prop:
+
+```tsx
+<OGrid
+  columns={columns}
+  data={people}
+  getRowId={(item) => item.id}
+  showRowNumbers
+/>
+```
+
+This gives you the numbered gutter column without column letters or the name box.
+:::
+
+### 3. Name Box
+
+A small read-only text field appears in the toolbar showing the currently active cell reference (e.g. "A1", "C15", "G3"). It updates automatically when you click a cell or navigate with the keyboard.
+
+The name box uses the column letter and absolute row number, so clicking the third column on row 5 of page 2 (with a page size of 10) shows "C15", not "C5".
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cellReferences` | `boolean` | `false` | Enable Excel-style cell references: column letter headers, row number gutter, and name box. Implies `showRowNumbers`. |
+| `showRowNumbers` | `boolean` | `false` | Show only the row number gutter column (no column letters or name box). Automatically enabled when `cellReferences` is `true`. |
+
+## Related
+
+- [Spreadsheet Selection](./spreadsheet-selection) -- cell-level selection with drag and shift-click
+- [Keyboard Navigation](./keyboard-navigation) -- arrow key navigation updates the name box
+- [Toolbar](./toolbar) -- the name box renders inside the toolbar strip

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

@@ -0,0 +1,279 @@
+---
+sidebar_position: 12
+title: Column Chooser
+description: Let users show and hide columns with a dropdown control
+---
+
+
+# Column Chooser
+
+The Column Chooser gives users a dropdown with checkboxes to show or hide columns at runtime. Columns marked `required` cannot be hidden.
+
+## Live Demo
+
+<ColumnChooserDemo />
+
+:::tip Framework-Specific Styling
+The live demo above shows **React Radix UI** styling (lightweight default). To see how the column chooser dropdown looks in your framework's design system, click the framework buttons above the demo to open online demo. Each framework renders with its native dropdown and checkbox components, so the styling matches your design system.
+:::
+
+## Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+interface Person {
+  id: number;
+  name: string;
+  email: string;
+  age: number;
+  department: string;
+  salary: number;
+  startDate: string;
+}
+
+const columns: IColumnDef<Person>[] = [
+  { columnId: 'name', name: 'Name', required: true },
+  { columnId: 'email', name: 'Email' },
+  { columnId: 'age', name: 'Age', type: 'numeric', defaultVisible: false },
+  { columnId: 'department', name: 'Department' },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    type: 'numeric',
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+  { columnId: 'startDate', name: 'Start Date', defaultVisible: false },
+];
+
+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
+
+interface Person {
+  id: number;
+  name: string;
+  email: string;
+  age: number;
+  department: string;
+  salary: number;
+  startDate: string;
+}
+
+const columns: IColumnDef<Person>[] = [
+  { columnId: 'name', name: 'Name', required: true },
+  { columnId: 'email', name: 'Email' },
+  { columnId: 'age', name: 'Age', type: 'numeric', defaultVisible: false },
+  { columnId: 'department', name: 'Department' },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    type: 'numeric',
+    valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+  },
+  { columnId: 'startDate', name: 'Start Date', defaultVisible: false },
+];
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns,
+    data: people,
+    getRowId: (p: Person) => p.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">
+
+interface Person {
+  id: number;
+  name: string;
+  email: string;
+  age: number;
+  department: string;
+  salary: number;
+  startDate: string;
+}
+
+const columns: IColumnDef<Person>[] = [
+  { columnId: 'name', name: 'Name', required: true },
+  { columnId: 'email', name: 'Email' },
+  { columnId: 'age', name: 'Age', type: 'numeric', defaultVisible: false },
+  { columnId: 'department', name: 'Department' },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    type: 'numeric',
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+  { columnId: 'startDate', name: 'Start Date', defaultVisible: false },
+];
+
+const gridProps = {
+  columns,
+  data: people,
+  getRowId: (p: Person) => p.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', required: true },
+    { columnId: 'email', name: 'Email' },
+    { columnId: 'age', name: 'Age', type: 'numeric', defaultVisible: false },
+    { columnId: 'department', name: 'Department' },
+    {
+      columnId: 'salary',
+      name: 'Salary',
+      type: 'numeric',
+      valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+    },
+    { columnId: 'startDate', name: 'Start Date', defaultVisible: false },
+  ],
+  data: people,
+  getRowId: (p) => p.id,
+  pageSize: 10,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+In this example:
+- **Name** is always visible (cannot be unchecked because `required: true`).
+- **Age** and **Start Date** are hidden by default but the user can enable them.
+- **Email**, **Department**, and **Salary** are visible by default and can be toggled.
+
+## How It Works
+
+OGrid includes a built-in Column Chooser that appears in the grid toolbar. Users click it to open a dropdown listing all columns with checkboxes.
+
+### Hiding Columns by Default
+
+Set `defaultVisible: false` on a column definition to hide it when the grid first renders. Users can still show it via the Column Chooser.
+
+```tsx
+{ columnId: 'phone', name: 'Phone', defaultVisible: false }
+```
+
+### Preventing Users from Hiding a Column
+
+Set `required: true` to lock a column as always visible. Its checkbox in the Column Chooser will be disabled.
+
+```tsx
+{ columnId: 'name', name: 'Name', required: true }
+```
+
+### Controlled Visibility
+
+For full control over which columns are visible, pass `visibleColumns` and `onVisibleColumnsChange`.
+
+```tsx
+function App() {
+  const [visible, setVisible] = useState<Set<string>>(
+    new Set(['name', 'email', 'department'])
+  );
+
+  return (
+    <OGrid
+      columns={columns}
+      data={rows}
+      getRowId={(r) => r.id}
+      visibleColumns={visible}
+      onVisibleColumnsChange={setVisible}
+    />
+  );
+}
+```
+
+When these props are provided, OGrid uses them instead of its internal visibility state.
+
+### Standalone ColumnChooser Component
+
+Each UI package also exports a standalone `ColumnChooser` component that you can render anywhere in your UI.
+
+```tsx
+
+<ColumnChooser
+  columns={columns}
+  visibleColumns={visibleColumns}
+  onVisibleColumnsChange={setVisibleColumns}
+/>
+```
+
+## Props Reference
+
+| Type | Field | Description |
+|---|---|---|
+| `IColumnMeta` | `defaultVisible` | `false` to hide on initial render (default: `true`) |
+| `IColumnMeta` | `required` | `true` to prevent the user from hiding this column |
+| `IOGridProps<T>` | `visibleColumns` | Controlled `Set<string>` of visible column IDs |
+| `IOGridProps<T>` | `onVisibleColumnsChange` | Callback when visibility changes: `(cols: Set<string>) => void` |
+
+## Related
+
+- [Column Groups](./column-groups) -- visibility applies to leaf columns within groups
+- [Column Pinning](./column-pinning) -- pinned columns can also be toggled
+- [Grid API](./grid-api) -- `getColumnState()` / `applyColumnState()` to save and restore visibility