@alaarab/ogrid-mcp 2.4.0

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

@@ -0,0 +1,216 @@
+---
+sidebar_position: 2
+title: Installation
+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.
+
+## React
+
+Choose one React UI package based on your design system:
+
+### Radix UI (Recommended)
+
+**Lightest option.** Radix UI primitives are bundled as regular dependencies -- no peer deps beyond React.
+
+```bash
+npm install @alaarab/ogrid-react-radix
+```
+
+**When to choose:** New projects, or when you want minimal bundle size and no design system lock-in.
+
+### Fluent UI
+
+**Microsoft's design system.** Requires Fluent UI v9 as a peer dependency.
+
+```bash
+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
+
+**Material Design for Vue.** Requires Vue 3 and Vuetify as peer dependencies.
+
+```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.
+
+---
+
+## 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.
+
+```bash
+npm install @alaarab/ogrid-core
+```
+
+:::info
+You typically do not need to install `@alaarab/ogrid-core` separately. All React UI packages re-export everything from `@alaarab/ogrid-react` (which re-exports from core), so types like `IColumnDef`, `IOGridApi`, and hooks like `useUndoRedo` are available directly from your chosen UI package.
+:::
+
+## Requirements
+
+| Framework | Version |
+|---|---|
+| React | 17, 18, or 19 |
+| Angular | 21 |
+| Vue | 3.3+ |
+| TypeScript | 5.x recommended (not required) |
+| Node.js | >= 18 (for development/build tooling) |
+
+## Verifying the Installation
+
+After installing, confirm everything is working by rendering a minimal grid.
+
+**React:**
+```tsx
+
+type Row = { id: number; name: string };
+const columns: IColumnDef<Row>[] = [{ columnId: 'name', name: 'Name' }];
+
+function App() {
+  return <OGrid<Row> columns={columns} data={[{ id: 1, name: 'Test' }]} getRowId={(row) => row.id} />;
+}
+```
+
+**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

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

@@ -0,0 +1,151 @@
+---
+sidebar_position: 1
+title: Overview
+description: What is OGrid and why use it
+---
+
+# Overview
+
+OGrid is a lightweight, open-source data grid library that delivers spreadsheet-grade features without the enterprise paywall. It ships with React, Angular, and Vue adapters -- each with multiple UI library implementations -- plus a vanilla JS package, all powered by a shared TypeScript core.
+
+## Why OGrid?
+
+Most production-grade React data grids fall into one of two camps: free but limited, or feature-rich but locked behind expensive licenses. OGrid bridges that gap.
+
+- **Free and MIT-licensed.** Every feature is included. No enterprise tier, no feature gating.
+- **25+ built-in features.** Sorting, filtering, pagination, cell editing, clipboard, undo/redo, fill handle, row selection, cell range selection, column pinning, column groups, CSV export, context menu, keyboard navigation, cell references, virtual scrolling, status bar, sidebar, and more.
+- **Multiple frameworks.** React, Angular, and Vue adapters with UI library choices for each -- switch later with zero logic changes.
+- **TypeScript-first.** Full strict-mode TypeScript with exported types for every prop, event, and API method.
+- **Lightweight.** The Radix package has no heavy framework dependency. Fluent and Material packages use their respective component libraries as peer dependencies.
+
+## Architecture
+
+OGrid is built on a **3-layer architecture**: a pure TypeScript core, framework adapter layers (React hooks, Angular services, Vue composables), and thin UI shells. No duplicated logic, no drift.
+
+
+<ArchitectureDiagram />
+
+### Core Layer — `@alaarab/ogrid-core`
+
+Pure TypeScript with zero dependencies. Provides the type system (`IOGridProps`, `IColumnDef`, `IOGridApi`, `FilterValue`, etc.) and shared algorithms (`getCellValue`, `buildHeaderRows`, `parseValue`, `normalizeSelectionRange`, etc.) used by both the React and JS packages.
+
+### Framework Adapter Layers
+
+Each framework adapter translates Core's algorithms into idiomatic framework patterns — React hooks, Angular services with signals, or Vue composables with refs.
+
+**React** — `@alaarab/ogrid-react`
+
+| Domain | Hooks |
+|---|---|
+| **Orchestration** | `useOGrid` · `useDataGridState` |
+| **Cell Editing** | `useCellEditing` · `useInlineCellEditorState` · `useRichSelectState` |
+| **Selection** | `useCellSelection` · `useRowSelection` · `useActiveCell` |
+| **Navigation** | `useKeyboardNavigation` (arrow keys, Tab, Enter, Ctrl+Arrow) |
+| **Clipboard** | `useClipboard` · `useFillHandle` · `useUndoRedo` |
+| **Layout** | `useColumnResize` · `useSideBarState` · `useColumnChooserState` |
+| **Filtering** | `useColumnHeaderFilterState` · `useFilterOptions` |
+
+**Angular** — `@alaarab/ogrid-angular`
+
+Angular v21 services using signals (`signal()`, `computed()`, `effect()`). Standalone components with inline templates. Zone-less by default.
+
+| Service | Equivalent |
+|---|---|
+| `OGridService` | `useOGrid` — pagination, sorting, filtering, visibility, editing |
+| `DataGridStateService` | `useDataGridState` — layout, selection, editing, interaction |
+
+**Vue** — `@alaarab/ogrid-vue`
+
+Vue 3 Composition API composables using `ref()`, `computed()`, `watch()`.
+
+| Composable | Equivalent |
+|---|---|
+| `useOGrid` | Pagination, sorting, filtering, column visibility |
+| `useDataGridState` | Layout, cell selection, editing, clipboard, keyboard nav |
+| 20+ feature composables | `useCellEditing`, `useCellSelection`, `useClipboard`, etc. |
+
+### UI Layer — Pick Your Framework
+
+Each UI package is a thin shell (~1,500 lines) that calls the same core logic and renders into native components:
+
+| Package | Built on | Best for |
+|---|---|---|
+| `@alaarab/ogrid-react-radix` | Radix primitives | Lightweight apps, custom design systems |
+| `@alaarab/ogrid-react-fluent` | Fluent UI v9 | Microsoft 365, SharePoint, Teams apps |
+| `@alaarab/ogrid-react-material` | MUI v7 | Material Design apps, dashboards |
+| `@alaarab/ogrid-angular-radix` | Angular CDK | Lightweight Angular apps, custom design systems |
+| `@alaarab/ogrid-angular-material` | Angular Material v21 | Angular + Material Design |
+| `@alaarab/ogrid-angular-primeng` | PrimeNG v21 | Angular + PrimeNG ecosystem |
+| `@alaarab/ogrid-vue-radix` | Radix primitives (Vue) | Lightweight Vue apps, custom design systems |
+| `@alaarab/ogrid-vue-vuetify` | Vuetify 3 | Vue + Material Design |
+| `@alaarab/ogrid-vue-primevue` | PrimeVue 4 | Vue + PrimeVue ecosystem |
+
+All packages within a framework export the same `OGrid` component with the same props. Switching UI libraries is a one-line import change — your column definitions, event handlers, data sources, and API calls stay identical.
+
+### Why This Matters
+
+- **Write once, render anywhere.** A bug fix or feature in core lands across all frameworks instantly.
+- **Zero lock-in.** Migrate between React, Angular, and Vue without rewriting business logic.
+- **Guaranteed parity.** Shared core ensures all packages behave identically.
+- **Small surface area.** No duplicated state logic to drift out of sync.
+
+## Packages
+
+| Package | npm | Description |
+|---|---|---|
+| `@alaarab/ogrid-core` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-core)](https://npmjs.com/package/@alaarab/ogrid-core) | Pure TS types, algorithms, utilities (zero deps) |
+| **React** | | |
+| `@alaarab/ogrid-react` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-react)](https://npmjs.com/package/@alaarab/ogrid-react) | React hooks, headless components, utilities |
+| `@alaarab/ogrid-react-radix` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-react-radix)](https://npmjs.com/package/@alaarab/ogrid-react-radix) | Radix UI implementation (default, lightweight) |
+| `@alaarab/ogrid-react-fluent` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-react-fluent)](https://npmjs.com/package/@alaarab/ogrid-react-fluent) | Fluent UI v9 implementation |
+| `@alaarab/ogrid-react-material` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-react-material)](https://npmjs.com/package/@alaarab/ogrid-react-material) | Material UI v7 implementation |
+| **Angular** | | |
+| `@alaarab/ogrid-angular` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-angular)](https://npmjs.com/package/@alaarab/ogrid-angular) | Angular v21 services with signals |
+| `@alaarab/ogrid-angular-radix` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-angular-radix)](https://npmjs.com/package/@alaarab/ogrid-angular-radix) | Angular CDK implementation (lightweight) |
+| `@alaarab/ogrid-angular-material` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-angular-material)](https://npmjs.com/package/@alaarab/ogrid-angular-material) | Angular Material v21 implementation |
+| `@alaarab/ogrid-angular-primeng` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-angular-primeng)](https://npmjs.com/package/@alaarab/ogrid-angular-primeng) | PrimeNG v21 implementation |
+| **Vue** | | |
+| `@alaarab/ogrid-vue` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-vue)](https://npmjs.com/package/@alaarab/ogrid-vue) | Vue 3 composables with Composition API |
+| `@alaarab/ogrid-vue-radix` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-vue-radix)](https://npmjs.com/package/@alaarab/ogrid-vue-radix) | Radix Vue implementation (lightweight) |
+| `@alaarab/ogrid-vue-vuetify` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-vue-vuetify)](https://npmjs.com/package/@alaarab/ogrid-vue-vuetify) | Vuetify 3 implementation |
+| `@alaarab/ogrid-vue-primevue` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-vue-primevue)](https://npmjs.com/package/@alaarab/ogrid-vue-primevue) | PrimeVue 4 implementation |
+| **Other** | | |
+| `@alaarab/ogrid-js` | [![npm](https://img.shields.io/npm/v/@alaarab/ogrid-js)](https://npmjs.com/package/@alaarab/ogrid-js) | Vanilla JS data grid (no framework) |
+
+## Feature Highlights
+
+| Feature | Description |
+|---|---|
+| Sorting | Single-column sort with ascending/descending toggle |
+| Filtering | Text, multi-select, and people filters per column |
+| Pagination | Client-side or server-side with configurable page sizes |
+| Cell Editing | Inline text, select, checkbox, and rich select editors |
+| Cell Selection | Spreadsheet-style range selection with drag support |
+| Clipboard | Copy/paste with multi-cell support (Ctrl+C / Ctrl+V) |
+| Fill Handle | Drag to fill cells (like Excel) |
+| Undo/Redo | Full undo/redo stack for cell edits |
+| Row Selection | Single or multiple row selection with checkbox column |
+| Column Pinning | Pin columns to left or right edge |
+| Column Groups | Multi-row grouped column headers |
+| Column Chooser | Show/hide columns with a dropdown |
+| Context Menu | Right-click menu with copy, paste, undo, and export |
+| CSV Export | One-click export to CSV |
+| Keyboard Navigation | Arrow keys, Tab, Enter, Page Down/Up, Ctrl+Home/End |
+| Cell References | Excel-style column letters (A, B, C...), row numbers, name box |
+| Status Bar | Row count, filtered count, selected count, and aggregations |
+| Sidebar | Column visibility and filter panels in a collapsible sidebar |
+| Server-Side Data | `IDataSource` interface for server-side pagination and filtering |
+| Grid API | Imperative `IOGridApi` ref for programmatic control |
+| Column Resize | Drag column borders to resize |
+| Virtual Scrolling | Row and column virtualization for 10K+ row datasets |
+| Web Worker Sort | Background-thread sorting for 50K+ rows |
+| Theming | Inherits your framework's theme automatically |
+
+## Coming from AG Grid?
+
+OGrid is designed as a drop-in replacement for AG Grid with a simpler, more React-idiomatic API. If you are migrating from AG Grid, see the [Migration Guide](../guides/migration-from-ag-grid).
+
+## Next Steps
+
+- [Installation](./installation) -- install OGrid for your framework
+- [Quick Start](./quick-start) -- build a grid with React, Angular, or Vue