@alaarab/ogrid-mcp 2.8.1 → 2.11.0

package/bundled-docs/features/virtual-scrolling.mdx

@@ -19,7 +19,7 @@ OGrid supports two independent virtualization axes that can be combined:
 <VirtualScrollingDemo />
 
 :::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.
+The demo above uses Radix UI for styling. To see this feature with the Fluent UI implementation, click **"Open in online demo"** below the demo.
 :::
 
 ## Quick Example
@@ -67,129 +67,8 @@ The `OGrid` component has the same props across all React UI packages. To switch
 
 - **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 Row {
-  id: number;
-  name: string;
-  value: number;
-}
-
-const data: Row[] = Array.from({ length: 10_000 }, (_, i) => ({
-  id: i + 1,
-  name: `Row ${i + 1}`,
-  value: Math.round(Math.random() * 10000),
-}));
-
-@Component({
-  standalone: true,
-  imports: [OGridComponent],
-  template: `<ogrid [props]="gridProps" />`
-})
-export class GridComponent {
-  gridProps = {
-    columns: [
-      { columnId: 'id', name: 'ID', type: 'numeric' },
-      { columnId: 'name', name: 'Name' },
-      { columnId: 'value', name: 'Value', type: 'numeric',
-        valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}` },
-    ] as IColumnDef<Row>[],
-    data,
-    getRowId: (item: Row) => item.id,
-    virtualScroll: { enabled: true, rowHeight: 36 },
-    statusBar: 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">
-
-interface Row {
-  id: number;
-  name: string;
-  value: number;
-}
-
-const data: Row[] = Array.from({ length: 10_000 }, (_, i) => ({
-  id: i + 1,
-  name: `Row ${i + 1}`,
-  value: Math.round(Math.random() * 10000),
-}));
-
-const columns: IColumnDef<Row>[] = [
-  { columnId: 'id', name: 'ID', type: 'numeric' },
-  { columnId: 'name', name: 'Name' },
-  { columnId: 'value', name: 'Value', type: 'numeric',
-    valueFormatter: (v) => `$${Number(v).toLocaleString()}` },
-];
-
-const gridProps = {
-  columns,
-  data,
-  getRowId: (item: Row) => item.id,
-  virtualScroll: { enabled: true, rowHeight: 36 },
-  statusBar: 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 data = Array.from({ length: 10_000 }, (_, i) => ({
-  id: i + 1,
-  name: `Row ${i + 1}`,
-  value: Math.round(Math.random() * 10000),
-}));
-
-const grid = new OGrid(document.getElementById('grid'), {
-  columns: [
-    { columnId: 'id', name: 'ID', type: 'numeric' },
-    { columnId: 'name', name: 'Name' },
-    { columnId: 'value', name: 'Value', type: 'numeric',
-      valueFormatter: (v) => `$${Number(v).toLocaleString()}` },
-  ],
-  data,
-  getRowId: (r) => r.id,
-  virtualScroll: { enabled: true, rowHeight: 36 },
-  statusBar: true,
-});
-```
-
   </TabItem>
 </Tabs>
 
@@ -276,82 +155,6 @@ function App() {
     </div>
   );
 }
-```
-
-  </TabItem>
-  <TabItem value="angular" label="Angular">
-
-```typescript
-
-@Component({
-  standalone: true,
-  imports: [OGridComponent],
-  template: `
-    <button (click)="scrollToTop()">Scroll to Top</button>
-    <button (click)="scrollToMiddle()">Scroll to Row 5000</button>
-    <button (click)="scrollToBottom()">Scroll to Bottom</button>
-    <ogrid [props]="gridProps" />
-  `,
-})
-export class GridComponent {
-  constructor(private gridService: OGridService) {}
-
-  scrollToTop() { this.gridService.scrollToRow(0); }
-  scrollToMiddle() { this.gridService.scrollToRow(4999, { align: 'center' }); }
-  scrollToBottom() { this.gridService.scrollToRow(9999, { align: 'end' }); }
-
-  gridProps = {
-    columns,
-    data,
-    getRowId: (item: Row) => item.id,
-    virtualScroll: { enabled: true, rowHeight: 36 },
-  };
-}
-```
-
-  </TabItem>
-  <TabItem value="vue" label="Vue">
-
-```vue
-<script setup lang="ts">
-
-const gridRef = ref<IOGridApi<Row> | null>(null);
-
-const scrollToTop = () => gridRef.value?.scrollToRow(0);
-const scrollToMiddle = () => gridRef.value?.scrollToRow(4999, { align: 'center' });
-const scrollToBottom = () => gridRef.value?.scrollToRow(9999, { align: 'end' });
-</script>
-
-<template>
-  <button @click="scrollToTop">Scroll to Top</button>
-  <button @click="scrollToMiddle">Scroll to Row 5000</button>
-  <button @click="scrollToBottom">Scroll to Bottom</button>
-  <OGrid :gridProps="gridProps" />
-</template>
-```
-
-  </TabItem>
-  <TabItem value="js" label="Vanilla JS">
-
-```js
-
-const grid = new OGrid(document.getElementById('grid'), {
-  columns,
-  data,
-  getRowId: (r) => r.id,
-  virtualScroll: { enabled: true, rowHeight: 36 },
-});
-
-const api = grid.getApi();
-
-// Scroll to the first row
-api.scrollToRow(0);
-
-// Scroll to row 5000, centered in the viewport
-api.scrollToRow(4999, { align: 'center' });
-
-// Scroll to the last row
-api.scrollToRow(9999, { align: 'end' });
 ```
 
   </TabItem>
@@ -447,114 +250,8 @@ The `OGrid` component has the same props across all React UI packages. To switch
 
 - **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 Row {
-  id: number;
-  [key: string]: number | string;
-}
-
-@Component({
-  standalone: true,
-  imports: [OGridComponent],
-  template: `<ogrid [props]="gridProps" />`
-})
-export class GridComponent {
-  gridProps = {
-    columns: [
-      { columnId: 'id', name: 'ID', type: 'numeric', pinned: 'left', defaultWidth: 80 },
-      ...Array.from({ length: 49 }, (_, i) => ({
-        columnId: `col${i}`,
-        name: `Column ${i + 1}`,
-        type: 'numeric' as const,
-      })),
-    ] as IColumnDef<Row>[],
-    data,
-    getRowId: (item: Row) => item.id,
-    virtualScroll: { enabled: true, rowHeight: 36, columns: true, columnOverscan: 2 },
-  };
-}
-```
-
-:::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 Row {
-  id: number;
-  [key: string]: number | string;
-}
-
-const columns: IColumnDef<Row>[] = [
-  { columnId: 'id', name: 'ID', type: 'numeric', pinned: 'left', defaultWidth: 80 },
-  ...Array.from({ length: 49 }, (_, i) => ({
-    columnId: `col${i}`,
-    name: `Column ${i + 1}`,
-    type: 'numeric' as const,
-  })),
-];
-
-const gridProps = {
-  columns,
-  data,
-  getRowId: (item: Row) => item.id,
-  virtualScroll: { enabled: true, rowHeight: 36, columns: true, columnOverscan: 2 },
-};
-</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 columns = [
-  { columnId: 'id', name: 'ID', type: 'numeric', pinned: 'left', defaultWidth: 80 },
-  ...Array.from({ length: 49 }, (_, i) => ({
-    columnId: `col${i}`,
-    name: `Column ${i + 1}`,
-    type: 'numeric',
-  })),
-];
-
-const grid = new OGrid(document.getElementById('grid'), {
-  columns,
-  data,
-  getRowId: (r) => r.id,
-  virtualScroll: { enabled: true, rowHeight: 36, columns: true, columnOverscan: 2 },
-});
-```
-
   </TabItem>
 </Tabs>
 

package/bundled-docs/getting-started/headless-or-component.mdx

@@ -0,0 +1,112 @@
+---
+sidebar_position: 5
+title: Headless or component?
+description: When to use the <OGrid> drop-in component vs the headless useHeadlessGrid hooks
+---
+
+# Headless or component?
+
+OGrid ships **two equally-supported entry points**. Both are first-class.
+Both are MIT. Both expose the same spreadsheet features. Pick the one that
+fits the page you're building — you can mix them in the same app.
+
+| | `<OGrid>` component | `useHeadlessGrid` + spreadsheet hooks |
+|---|---|---|
+| **What you write** | One JSX element | A handful of hook calls + your own `<table>` markup |
+| **Time to first working grid** | ~5 lines | ~50-100 lines |
+| **Customization ceiling** | High (theme tokens, slots) | Unlimited (you draw the chrome) |
+| **Design-system fit** | Inherits via theme presets (shadcn, Fluent, Material) | Native — uses your chrome primitives directly |
+| **Spreadsheet features** | Built-in | Composable from hooks |
+| **Best for** | Standard list pages, admin tables, dashboards | Pages where chrome integration matters more than save-time |
+
+## Use `<OGrid>` when…
+
+- You want a complete grid in one element. Sort, filter, paginate, edit,
+  range select, fill handle, copy/paste, undo, keyboard nav — all wired.
+- The default chrome (via your chosen UI variant — Radix / Fluent / Material)
+  is close enough to your design system that a theme preset (`preset-shadcn.css`)
+  can bridge the rest.
+- You're prototyping or building admin pages where shipping fast matters
+  more than every pixel.
+
+```tsx
+
+const columns = [
+  { columnId: "name", name: "Name", sortable: true, editable: true },
+  { columnId: "salary", name: "Salary", type: "numeric", sortable: true },
+];
+
+<OGrid columns={columns} data={employees} getRowId={(e) => e.id} />;
+```
+
+## Use `useHeadlessGrid` + the spreadsheet hooks when…
+
+- You want OGrid's logic but rendered with your own table chrome
+  (shadcn `<Table>`, Fluent `<DataGrid>`, Material `<TableRow>`, plain HTML —
+  anything).
+- The chrome integration is non-negotiable: a specific design system,
+  custom row layouts, embedded widgets in cells, or shared `<TableRow>`
+  components from the rest of the app.
+- You want to opt into spreadsheet features piece-by-piece. Add only
+  inline edit on this page; add range selection + clipboard on that one.
+
+```tsx
+  useHeadlessGrid,
+  useInlineEdit,
+  useRangeSelection,
+  useFillHandle,
+  useCellClipboard,
+  useUndoRedo,
+  useGridFocus,
+} from "@alaarab/ogrid-react-radix";
+
+const grid = useHeadlessGrid({ columns, data, getRowId: (r) => r.id });
+const range = useRangeSelection({ rowCount: grid.rows.length, colCount: grid.columns.length });
+const undo = useUndoRedo({ onCellValueChanged: applyEdit });
+const edit = useInlineEdit({ columns, getRowId: (r) => r.id, onCellEdit: undo.onCellValueChanged });
+const fill = useFillHandle({ rangeSelection: range, rows: grid.rows, columns, onFillCells });
+const clipboard = useCellClipboard({ rangeSelection: range, rows: grid.rows, columns, onCellEdit });
+const focus = useGridFocus({ rowCount: grid.rows.length, colCount: grid.columns.length, rangeSelection: range });
+
+return (
+  <Table>
+    <TableHeader>{/* render grid.columns + grid.toggleSort + grid.sortIndicator */}</TableHeader>
+    <TableBody>{/* render grid.rows + edit / range / fill / clipboard / focus glue */}</TableBody>
+  </Table>
+);
+```
+
+The full integration code is the
+[`SpreadsheetDemo` Storybook story in `react-radix`](https://github.com/alaarab/ogrid/blob/main/packages/react-radix/src/OGrid/SpreadsheetDemo.stories.tsx)
+— ~200 lines, copy-paste as your starter template.
+
+## Both at once — yes, in the same app
+
+Mix freely. A typical pattern:
+
+- 80% of admin / list pages → `<OGrid>` (fast to build, good enough chrome)
+- 20% of "the data table is the product" pages → headless hooks (custom chrome wins)
+
+Same package import. Same theme tokens. Same TypeScript types. The
+spreadsheet features (inline edit, fill handle, clipboard, undo) work
+identically across both paths because they share the same core utilities
+(`processClientSideData`, `applyFillValues`, `formatSelectionAsTsv`,
+`parseValue`, etc).
+
+## What this means architecturally
+
+`<OGrid>` is OGrid's **reference chrome** — a complete grid built on the
+same headless primitives any consumer would use. The two paths share
+underlying state machines (`useOGridSorting`, `useOGridFilters`,
+`useOGridPagination`, `useOGridDataFetching`); the only difference is who
+draws the table. That's why you can swap between them page-by-page
+without losing behavior parity, and why the bug fixes in one path
+automatically benefit the other.
+
+## Migrating between modes
+
+There's no migration boundary. `<OGrid>` accepts the same column defs
+your headless code uses. Move a page from `<OGrid>` to headless by
+replacing the JSX element with hook calls + your own table; the column
+defs, the row data, the sort/filter/paginate behavior all stay identical.
+Move back the same way.

package/bundled-docs/getting-started/installation.mdx

@@ -6,7 +6,7 @@ description: Install OGrid for your framework
 
 # Installation
 
-OGrid ships as separate packages for each UI framework. Pick the one that matches your project's design system.
+OGrid ships as separate packages for each design system. Pick the one that matches your project.
 
 ## React
 
@@ -32,115 +32,19 @@ npm install @alaarab/ogrid-react-fluent @fluentui/react-components
 
 **When to choose:** SharePoint Framework (SPFx) apps, Microsoft 365 integrations, or projects already using Fluent UI.
 
-### Material UI
-
-**Google's Material Design.** Requires MUI v7 and Emotion as peer dependencies.
-
-```bash
-npm install @alaarab/ogrid-react-material @mui/material @emotion/react @emotion/styled
-```
-
-**When to choose:** Projects using Material Design, or when you need MUI's extensive component ecosystem.
-
 ---
 
-## Angular
-
-Choose one Angular UI package based on your design system:
-
-### Radix (Angular CDK)
-
-**Lightest option.** Uses Angular CDK for overlays -- no heavy UI framework dependencies.
-
-```bash
-npm install @alaarab/ogrid-angular-radix @angular/cdk
-```
-
-**When to choose:** New Angular projects, or when you want minimal bundle size and no design system lock-in.
-
-### Angular Material
-
-**Official Material Design for Angular.** Requires Angular v21, Angular Material, and CDK as peer dependencies.
-
-```bash
-npm install @alaarab/ogrid-angular-material @angular/material @angular/cdk
-```
-
-**When to choose:** Projects already using Angular Material, or when you need Material Design components.
-
-### PrimeNG
-
-**PrimeNG component library.** Requires Angular v21 and PrimeNG as peer dependencies.
-
-```bash
-npm install @alaarab/ogrid-angular-primeng primeng
-```
-
-**When to choose:** Projects already using PrimeNG, or when you prefer PrimeNG's component set.
-
----
-
-## Vue
-
-Choose one Vue UI package based on your design system:
-
-### Radix (Headless UI)
-
-**Lightest option.** Headless UI Vue components are bundled as regular dependencies -- no peer deps beyond Vue.
-
-```bash
-npm install @alaarab/ogrid-vue-radix
-```
-
-**When to choose:** New Vue projects, or when you want minimal bundle size and no design system lock-in.
-
-### Vuetify
+## Frozen adapters
 
-**Material Design for Vue.** Requires Vue 3 and Vuetify as peer dependencies.
+The following adapters remain on npm at their last shipped version but no longer receive feature work or framework-major upgrades. Existing installs continue to work unchanged. Source for each lives on the `legacy/multiframework` branch of the repo.
 
-```bash
-npm install @alaarab/ogrid-vue-vuetify vuetify
-```
-
-**When to choose:** Projects already using Vuetify, or when you need Material Design components.
-
-### PrimeVue
-
-**PrimeVue component library.** Requires Vue 3 and PrimeVue as peer dependencies.
-
-```bash
-npm install @alaarab/ogrid-vue-primevue primevue
-```
-
-**When to choose:** Projects already using PrimeVue, or when you prefer PrimeVue's component set.
+- **`@alaarab/ogrid-react-material`** — frozen at v2.9.1. MUI v7 (skipped v8, broke in v9).
+- **`@alaarab/ogrid-js`** + **`@alaarab/ogrid-js-inputs`** — frozen at v2.9.1. The vanilla JS variant.
+- **`@alaarab/ogrid-angular*`** — frozen at v2.9.0.
+- **`@alaarab/ogrid-vue*`** — frozen at v2.9.0.
 
 ---
 
-## Vanilla JS (No Framework)
-
-**Framework-free data grid.** Class-based API with EventEmitter state management. Zero framework dependencies.
-
-```bash
-npm install @alaarab/ogrid-js
-```
-
-**When to choose:** Projects without React/Angular/Vue, legacy codebases, or when you want full control over rendering.
-
-:::tip Theme CSS
-The JS package ships a default theme with light and dark mode support:
-
-```js
-```
-
-Or link it directly in HTML:
-
-```html
-<link rel="stylesheet" href="node_modules/@alaarab/ogrid-js/dist/styles/ogrid.css" />
-```
-
-You can override any `--ogrid-*` CSS variable to customize colors, or skip the default theme entirely and write your own CSS targeting the `ogrid-*` class names.
-:::
-
 ## Core Only
 
 If you want to build your own framework adapter on top of OGrid's types and utilities, install the core package directly.
@@ -155,19 +59,16 @@ You typically do not need to install `@alaarab/ogrid-core` separately. All React
 
 ## Requirements
 
-| Framework | Version |
+| Dependency | Version |
 |---|---|
 | React | 17, 18, or 19 |
-| Angular | 21 |
-| Vue | 3.3+ |
-| TypeScript | 5.x recommended (not required) |
-| Node.js | >= 18 (for development/build tooling) |
+| TypeScript | 5.x or 6.x recommended (not required) |
+| Node.js | >= 18 (for your build tooling) |
 
 ## Verifying the Installation
 
 After installing, confirm everything is working by rendering a minimal grid.
 
-**React:**
 ```tsx
 
 type Row = { id: number; name: string };
@@ -178,39 +79,8 @@ function App() {
 }
 ```
 
-**Angular:**
-```typescript
-
-@Component({
-  standalone: true,
-  imports: [OGridComponent],
-  template: `<ogrid [props]="gridProps" />`
-})
-export class AppComponent {
-  gridProps = {
-    columns: [{ columnId: 'name', name: 'Name' }] as IColumnDef[],
-    data: [{ id: 1, name: 'Test' }],
-    getRowId: (row: any) => row.id,
-  };
-}
-```
-
-**Vue:**
-```vue
-<script setup lang="ts">
-
-const columns: IColumnDef[] = [{ columnId: 'name', name: 'Name' }];
-const data = [{ id: 1, name: 'Test' }];
-const getRowId = (row: any) => row.id;
-</script>
-
-<template>
-  <OGrid :gridProps="{ columns, data, getRowId }" />
-</template>
-```
-
 If the grid renders with a single row showing "Test", your installation is correct.
 
 ## Next Steps
 
-- [Quick Start](./quick-start) -- build a grid with your chosen framework
+- [Quick Start](./quick-start) -- build a working React grid