@alaarab/ogrid-mcp 2.5.4 → 2.5.8

package/bundled-docs/getting-started/quick-start.mdx

@@ -1,16 +1,18 @@
 ---
 sidebar_position: 3
 title: Quick Start
-description: Build a fully functional data grid in minutes
+description: A sortable, filterable, editable data grid in under 50 lines
 ---
 
 
 # Quick Start
 
-Build a sortable, filterable, editable data grid in under 50 lines.
+Here's a grid in 60 seconds — sorting, filtering, editing, pagination, and keyboard navigation, all working out of the box.
 
 ## Install
 
+Pick your framework and UI library:
+
 <Tabs groupId="framework">
   <TabItem value="react" label="React" default>
 
@@ -88,7 +90,9 @@ npm install @alaarab/ogrid-js
   </TabItem>
 </Tabs>
 
-## Full Example
+## Your first grid
+
+This example renders an employee directory with sortable columns, a department filter, and an editable salary column. Copy it and it'll just work.
 
 <Tabs groupId="framework">
   <TabItem value="react" label="React" default>
@@ -145,11 +149,11 @@ export default function App() {
 ```
 
 :::tip Switching UI libraries
-The `OGrid` component has the same props across all React UI packages. To switch, just change the import:
+The `OGrid` component has identical props across all React UI packages. To switch, change one 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>`
+- **Radix** (lightweight, no peer deps): `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>
@@ -203,7 +207,7 @@ export class EmployeeGridComponent {
 ```
 
 :::tip Switching UI libraries
-Same component API across Angular packages. To switch, just change the import:
+All Angular packages share the same component API. Change one import:
 
 - **Radix (CDK)** (lightweight): `from '@alaarab/ogrid-angular-radix'`
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
@@ -262,10 +266,10 @@ const gridProps = {
 ```
 
 :::tip Switching UI libraries
-Same component API across Vue packages. To switch, just change the import:
+All Vue packages share the same API. Change one import:
 
 - **Radix (Headless UI)** (lightweight): `from '@alaarab/ogrid-vue-radix'`
-- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'` — wrap in `<v-app>` for theming
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 
@@ -307,31 +311,33 @@ const grid = new OGrid(document.getElementById('grid'), {
 ```
 
 :::tip
-The JS package uses a class-based imperative API. See the [Vanilla JS guide](./vanilla-js) for the full API including events, grid methods, and theming.
+The JS package has a class-based imperative API. See the [Vanilla JS guide](./vanilla-js) for events, grid methods, and theming.
 :::
 
   </TabItem>
 </Tabs>
 
-## What You Get
+## What you get for free
+
+Paste those ~40 lines and you have:
 
-With just this code:
+- **Sorting** — click any column header, ascending/descending, shift-click for multi-sort
+- **Filtering** — the Department column gets a multi-select dropdown filter
+- **Inline editing** — double-click any salary cell to edit in place
+- **Currency formatting** — `valueFormatter` formats numbers on display without affecting stored values
+- **Pagination, keyboard nav, cell selection, status bar** — all there, no extra config
 
-- **Sorting** -- click column headers to sort ascending/descending
-- **Filtering** -- click the filter icon on Department to filter by value
-- **Inline editing** -- double-click any salary cell to edit
-- **Numeric formatting** -- `type: 'numeric'` right-aligns; `valueFormatter` displays currency
-- **Pagination, keyboard nav, cell selection, status bar** -- all built in
+## Three concepts worth knowing
 
-## Key Concepts
+| | Description |
+|--|--|
+| `IColumnDef<T>` | Describes a column. `columnId` must match a key on your row type (or use `valueGetter` for computed values). |
+| `getRowId` | Returns a stable unique identifier per row. Used for selection, editing, and efficient re-renders. |
+| `layoutMode` | `'fill'` (default) stretches the grid to fill its container. `'content'` sizes to the data. |
 
-| Concept | Description |
-|---------|-------------|
-| `IColumnDef<T>` | Column config. `columnId` matches a key on `T` (or use `valueGetter`). |
-| `getRowId` | Returns a unique `string \| number` per row for selection, editing, and re-rendering. |
-| `layoutMode` | `'fill'` (default) fills container; `'content'` sizes to content. |
+## Programmatic control
 
-## Using the Grid API
+Need to interact with the grid from outside? Use the API:
 
 <Tabs groupId="framework">
   <TabItem value="react" label="React" default>
@@ -343,8 +349,8 @@ function App() {
 
   return (
     <>
-      <button onClick={() => console.log(gridRef.current?.getColumnState())}>
-        Log State
+      <button onClick={() => gridRef.current?.exportToCsv('employees.csv')}>
+        Export CSV
       </button>
       <OGrid<Employee> ref={gridRef} columns={columns} data={data} getRowId={(row) => row.id} />
     </>
@@ -361,15 +367,15 @@ function App() {
   standalone: true,
   imports: [OGridComponent],
   template: `
-    <button (click)="logState()">Log State</button>
+    <button (click)="exportCsv()">Export CSV</button>
     <ogrid [props]="gridProps" />
   `
 })
 export class AppComponent {
   constructor(private gridService: OGridService) {}
 
-  logState() {
-    console.log(this.gridService.getColumnState());
+  exportCsv() {
+    this.gridService.exportToCsv('employees.csv');
   }
 
   gridProps = { columns, data, getRowId: (row: any) => row.id };
@@ -382,15 +388,11 @@ export class AppComponent {
 ```vue
 <script setup lang="ts">
 
-const { getColumnState } = useOGrid({ columns, data, getRowId: (row) => row.id });
-
-function logState() {
-  console.log(getColumnState());
-}
+const { exportToCsv } = useOGrid({ columns, data, getRowId: (row) => row.id });
 </script>
 
 <template>
-  <button @click="logState">Log State</button>
+  <button @click="exportToCsv('employees.csv')">Export CSV</button>
   <OGrid :gridProps="{ columns, data, getRowId: (row) => row.id }" />
 </template>
 ```
@@ -404,22 +406,20 @@ const grid = new OGrid(document.getElementById('grid'), {
   columns, data, getRowId: (row) => row.id,
 });
 
-// Programmatic control
-const api = grid.getApi();
-console.log(api.getColumnState());
-api.setRowData(newData);
+document.getElementById('export-btn').addEventListener('click', () => {
+  grid.api.exportToCsv('employees.csv');
+});
 
-// Cleanup
+// Cleanup when done
 grid.destroy();
 ```
 
   </TabItem>
 </Tabs>
 
-## Next Steps
+## What's next?
 
-- [Sorting](../features/sorting), [Filtering](../features/filtering), [Editing](../features/editing) -- core features
-- [Grid API](../api/grid-api) -- imperative methods
-- [Column Definitions](../api/column-def) -- all column options
-- [Controlled vs Uncontrolled](../guides/controlled-vs-uncontrolled) -- managing state externally
-- [Server-Side Data](../features/server-side-data) -- connect to REST APIs or GraphQL
+- [Sorting](../features/sorting), [Filtering](../features/filtering), [Editing](../features/editing) — dig into individual features
+- [Server-Side Data](../features/server-side-data) — connect to a REST API or GraphQL endpoint
+- [Grid API](../api/js-api) — full reference for programmatic control
+- [Column Definitions](../api/types) — every column option explained

package/bundled-docs/getting-started/vanilla-js.mdx

@@ -1,13 +1,15 @@
 ---
 sidebar_position: 4
 title: Vanilla JS
-description: Use OGrid without React — pure JavaScript, class-based API
+description: OGrid without a framework — pure JavaScript, class-based API
 ---
 
 
-# Vanilla JS Quick Start
+# Vanilla JS
 
-OGrid's vanilla JS package provides the same features as the React packages with a class-based, imperative API. No React, no virtual DOM — just a container element and an options object.
+You don't need React, Angular, or Vue to use OGrid. The `@alaarab/ogrid-js` package gives you a full-featured, sortable, filterable, editable data grid using a simple class-based API — just a container element and an options object.
+
+It's a good fit if you're working on an internal tool, a dashboard that can't take on a framework, or you're embedding a grid inside an existing non-framework app.
 
 ## Install
 
@@ -15,57 +17,83 @@ OGrid's vanilla JS package provides the same features as the React packages with
 npm install @alaarab/ogrid-js
 ```
 
-## Basic Example
+Or drop it into an HTML file directly using a CDN (no build tools needed):
+
+```html
+<script type="module">
+  import { OGrid } from 'https://cdn.jsdelivr.net/npm/@alaarab/ogrid-js/dist/esm/index.js';
+</script>
+```
+
+## Build a real example
+
+Let's make an order management dashboard. It tracks orders by status, amount, and customer — sortable, filterable, and editable inline.
 
 ```html
-<div id="grid" style="height: 400px;"></div>
+<div id="orders-grid" style="height: 500px;"></div>
 
 <script type="module">
   import { OGrid } from '@alaarab/ogrid-js';
-  import '@alaarab/ogrid-js/styles'; // default theme (light + dark mode)
+  import '@alaarab/ogrid-js/styles';
 
-  const grid = new OGrid(document.getElementById('grid'), {
+  const grid = new OGrid(document.getElementById('orders-grid'), {
     columns: [
-      { columnId: 'name', name: 'Name', sortable: true },
-      { columnId: 'department', name: 'Department', sortable: true },
+      { columnId: 'orderId', name: 'Order #', sortable: true },
+      { columnId: 'customer', name: 'Customer', sortable: true },
+      {
+        columnId: 'status',
+        name: 'Status',
+        sortable: true,
+        filterable: { type: 'multiSelect', options: ['Pending', 'Shipped', 'Delivered', 'Cancelled'] },
+      },
       {
-        columnId: 'salary',
-        name: 'Salary',
+        columnId: 'amount',
+        name: 'Amount',
         type: 'numeric',
         sortable: true,
         editable: true,
         valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
       },
+      {
+        columnId: 'date',
+        name: 'Order Date',
+        type: 'date',
+        sortable: true,
+      },
     ],
     data: [
-      { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000 },
-      { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000 },
-      { id: 3, name: 'Carol Williams', department: 'Sales', salary: 110000 },
-      { id: 4, name: 'David Brown', department: 'Engineering', salary: 68000 },
-      { id: 5, name: 'Eva Martinez', department: 'Marketing', salary: 78000 },
+      { orderId: 'ORD-1001', customer: 'Acme Corp', status: 'Shipped', amount: 4200, date: '2024-03-01' },
+      { orderId: 'ORD-1002', customer: 'Globex Inc', status: 'Pending', amount: 1850, date: '2024-03-03' },
+      { orderId: 'ORD-1003', customer: 'Initech', status: 'Delivered', amount: 9300, date: '2024-02-28' },
+      { orderId: 'ORD-1004', customer: 'Umbrella LLC', status: 'Cancelled', amount: 620, date: '2024-03-05' },
+      { orderId: 'ORD-1005', customer: 'Acme Corp', status: 'Delivered', amount: 7100, date: '2024-02-20' },
     ],
-    getRowId: (row) => row.id,
-    pageSize: 10,
-    editable: true,
+    getRowId: (row) => row.orderId,
+    pageSize: 20,
     cellSelection: true,
     statusBar: true,
   });
+
+  // React to edits in real time
+  grid.on('cellValueChanged', ({ item, columnId, newValue }) => {
+    console.log(`Order ${item.orderId}: ${columnId} updated to ${newValue}`);
+    // sync to your backend here
+  });
 </script>
 ```
 
-## Live Demo
+## Live demo
 
 <VanillaJSDemo />
 
-## What You Get
-
-With this code you have:
+## What you get out of the box
 
 - **Sorting** — click column headers
-- **Inline editing** — double-click any salary cell
+- **Filtering** — multi-select dropdown on the Status column
+- **Inline editing** — double-click any Amount cell to edit
 - **Cell selection** — click and drag to select ranges
 - **Keyboard navigation** — arrow keys, Tab, Home/End, Ctrl+Arrow
-- **Clipboard** — Ctrl+C/V/X
+- **Clipboard** — Ctrl+C/V/X works like a spreadsheet
 - **Undo/redo** — Ctrl+Z/Y
 - **Status bar** — row count and selection aggregations
 - **Pagination** — page controls at the bottom
@@ -76,78 +104,77 @@ With this code you have:
 const grid = new OGrid(containerElement, options);
 ```
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `container` | `HTMLElement` | The DOM element to render into. OGrid fills this element. |
-| `options` | `OGridOptions<T>` | Grid configuration (see below). |
+The container element defines where the grid renders. OGrid fills it completely — give it an explicit height (CSS or inline).
 
-## Key Options
+## Key options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `columns` | `IColumnDef<T>[]` | **required** | Column definitions |
-| `data` | `T[]` | — | Client-side data array |
-| `dataSource` | `IDataSource<T>` | — | Server-side data source (mutually exclusive with `data`) |
-| `getRowId` | `(item: T) => RowId` | **required** | Unique row identifier |
+| `data` | `T[]` | — | Client-side row data |
+| `dataSource` | `IDataSource<T>` | — | Server-side data source (use instead of `data`) |
+| `getRowId` | `(item: T) => RowId` | **required** | Returns a unique identifier per row |
 | `pageSize` | `number` | `20` | Rows per page |
-| `sort` | `{ field, direction }` | — | Initial sort |
+| `sort` | `{ field, direction }` | — | Initial sort state |
 | `filters` | `IFilters` | — | Initial filters |
 | `editable` | `boolean` | `false` | Enable cell editing |
-| `cellSelection` | `boolean` | `false` | Enable spreadsheet-style selection |
+| `cellSelection` | `boolean` | `false` | Spreadsheet-style range selection |
 | `rowSelection` | `'single' \| 'multiple'` | — | Row selection mode |
-| `sideBar` | `boolean \| ISideBarDef` | — | Show sidebar (columns + filters panels) |
-| `layoutMode` | `'fill' \| 'content'` | `'fill'` | `'fill'` stretches to container; `'content'` sizes to data |
-| `pinnedColumns` | `Record<string, 'left' \| 'right'>` | — | Pin columns to edges |
+| `sideBar` | `boolean \| ISideBarDef` | — | Column visibility + filter panel |
+| `layoutMode` | `'fill' \| 'content'` | `'fill'` | `'fill'` fills the container; `'content'` sizes to data |
+| `pinnedColumns` | `Record<string, 'left' \| 'right'>` | — | Pin columns to left or right edge |
 
-## Events
+## Listening to events
 
-Listen for events with `.on()`:
+Use `.on()` to subscribe to grid events:
 
 ```js
-grid.on('cellValueChanged', (event) => {
-  console.log(`Cell ${event.columnId} changed from ${event.oldValue} to ${event.newValue}`);
-});
-
-grid.on('sortChange', ({ field, direction }) => {
-  console.log(`Sorted by ${field} ${direction}`);
+grid.on('cellValueChanged', ({ item, columnId, oldValue, newValue }) => {
+  console.log(`${columnId} changed: ${oldValue} → ${newValue}`);
+  // save to backend
 });
 
 grid.on('selectionChange', ({ selectedRows }) => {
   console.log(`${selectedRows.length} rows selected`);
+  updateActionBar(selectedRows);
+});
+
+grid.on('sortChange', ({ field, direction }) => {
+  console.log(`Sorted by ${field} ${direction}`);
 });
 ```
 
-| Event | Payload | Fired when |
-|-------|---------|------------|
+| Event | Payload | When it fires |
+|-------|---------|---------------|
 | `cellValueChanged` | `{ item, columnId, oldValue, newValue }` | A cell edit is committed |
-| `sortChange` | `{ field, direction }` | Sort changes |
-| `filterChange` | `{ filters }` | Filters change |
-| `pageChange` | `{ page }` | Page changes |
+| `sortChange` | `{ field, direction }` | User changes sort |
+| `filterChange` | `{ filters }` | User changes filters |
+| `pageChange` | `{ page }` | User navigates pages |
 | `selectionChange` | `{ selectedRows, selectedRowIds }` | Row selection changes |
 
-## Grid API
+## Programmatic control
 
-Access the imperative API via `grid.api`:
+The grid API lives on `grid.api`:
 
 ```js
-// Update data
-grid.api.setRowData(newData);
+// Swap in new data (re-renders efficiently)
+grid.api.setRowData(freshData);
 
-// Get current state
-const state = grid.api.getColumnState();
+// Export what's currently displayed (respects active filters/sort)
+grid.api.exportToCsv('orders.csv');
 
-// Export to CSV
-grid.api.exportToCsv('my-data.csv');
+// Set sort programmatically
+grid.api.setSort('amount', 'desc');
 
-// Programmatic sort
-grid.api.setSort('salary', 'desc');
+// Get current column state (widths, visibility, order)
+const state = grid.api.getColumnState();
 ```
 
-See the full [JS API Reference](../api/js-api) for all methods.
+See the full [JS API Reference](../api/js-api) for all available methods.
 
 ## Theming
 
-The default theme uses CSS custom properties. Override them to match your design:
+The default theme uses CSS custom properties. Override any of them to match your design system:
 
 ```css
 :root {
@@ -155,37 +182,34 @@ The default theme uses CSS custom properties. Override them to match your design
   --ogrid-selection: #0078d4;     /* active cell outline */
   --ogrid-bg: #ffffff;            /* background */
   --ogrid-fg: #242424;            /* text color */
-  --ogrid-border: #e0e0e0;       /* borders */
-  --ogrid-bg-subtle: #f3f2f1;    /* header background */
-  --ogrid-bg-hover: #f5f5f5;     /* row hover */
+  --ogrid-border: #e0e0e0;        /* borders */
+  --ogrid-bg-subtle: #f3f2f1;     /* header background */
+  --ogrid-bg-hover: #f5f5f5;      /* row hover */
 }
 ```
 
-For dark mode, set `data-theme="dark"` on a parent element or rely on `prefers-color-scheme`:
+Dark mode works automatically if you rely on `prefers-color-scheme`, or you can opt into it explicitly:
 
 ```css
 [data-theme='dark'] {
   --ogrid-bg: #1a1a24;
   --ogrid-fg: #e0e0e0;
   --ogrid-border: #333340;
-  /* ... */
 }
 ```
 
-Or skip the default theme entirely and write your own CSS targeting the `ogrid-*` class names.
+Or skip the built-in theme entirely and write your own CSS targeting `ogrid-*` class names.
 
 ## Cleanup
 
-Always destroy the grid when you're done:
+When your grid is no longer needed (navigating away, SPA route change, etc.), call `destroy()` to remove all DOM elements and event listeners:
 
 ```js
 grid.destroy();
 ```
 
-This removes all DOM elements, event listeners, and ResizeObservers.
-
-## Next Steps
+## What's next?
 
 - [JS API Reference](../api/js-api) — full method and options reference
-- [Features](../features/sorting) — all grid features work identically in JS
+- [Features](../features/sorting) — all features work identically in the JS package
 - [Theming Guide](../guides/theming) — deep dive into CSS customization