@alaarab/ogrid-mcp 2.4.0

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

@@ -0,0 +1,425 @@
+---
+sidebar_position: 3
+title: Quick Start
+description: Build a fully functional data grid in minutes
+---
+
+
+# Quick Start
+
+Build a sortable, filterable, editable data grid in under 50 lines.
+
+## Install
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+<Tabs groupId="react-ui">
+  <TabItem value="radix" label="Radix (Default)" default>
+
+```bash
+npm install @alaarab/ogrid-react-radix
+```
+
+  </TabItem>
+  <TabItem value="fluent" label="Fluent UI">
+
+```bash
+npm install @alaarab/ogrid-react-fluent @fluentui/react-components
+```
+
+  </TabItem>
+  <TabItem value="material" label="Material UI">
+
+```bash
+npm install @alaarab/ogrid-react-material @mui/material @emotion/react @emotion/styled
+```
+
+  </TabItem>
+</Tabs>
+
+  </TabItem>
+  <TabItem value="angular" label="Angular">
+
+<Tabs groupId="angular-ui">
+  <TabItem value="angular-material" label="Angular Material" default>
+
+```bash
+npm install @alaarab/ogrid-angular-material @angular/material @angular/cdk
+```
+
+  </TabItem>
+  <TabItem value="angular-primeng" label="PrimeNG">
+
+```bash
+npm install @alaarab/ogrid-angular-primeng primeng
+```
+
+  </TabItem>
+</Tabs>
+
+  </TabItem>
+  <TabItem value="vue" label="Vue">
+
+<Tabs groupId="vue-ui">
+  <TabItem value="vue-vuetify" label="Vuetify" default>
+
+```bash
+npm install @alaarab/ogrid-vue-vuetify vuetify
+```
+
+  </TabItem>
+  <TabItem value="vue-primevue" label="PrimeVue">
+
+```bash
+npm install @alaarab/ogrid-vue-primevue primevue
+```
+
+  </TabItem>
+</Tabs>
+
+  </TabItem>
+  <TabItem value="js" label="Vanilla JS">
+
+```bash
+npm install @alaarab/ogrid-js
+```
+
+  </TabItem>
+</Tabs>
+
+## Full Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+interface Employee {
+  id: number;
+  name: string;
+  department: string;
+  salary: number;
+}
+
+const data: Employee[] = [
+  { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000 },
+  { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000 },
+  { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 110000 },
+  { id: 4, name: 'David Brown', department: 'Sales', salary: 68000 },
+  { id: 5, name: 'Eva Martinez', department: 'Marketing', salary: 78000 },
+];
+
+const columns: IColumnDef<Employee>[] = [
+  { columnId: 'name', name: 'Name', sortable: true },
+  {
+    columnId: 'department',
+    name: 'Department',
+    sortable: true,
+    filterable: { type: 'multiSelect', options: ['Engineering', 'Marketing', 'Sales'] },
+  },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    type: 'numeric',
+    sortable: true,
+    editable: true,
+    valueFormatter: (value) =>
+      new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value as number),
+  },
+];
+
+export default function App() {
+  return (
+    <OGrid<Employee>
+      columns={columns}
+      data={data}
+      getRowId={(row) => row.id}
+      defaultPageSize={10}
+      defaultSortBy="name"
+      statusBar
+      aria-label="Employee directory"
+    />
+  );
+}
+```
+
+:::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 Employee {
+  id: number;
+  name: string;
+  department: string;
+  salary: number;
+}
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class EmployeeGridComponent {
+  private readonly data: Employee[] = [
+    { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000 },
+    { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000 },
+    { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 110000 },
+    { id: 4, name: 'David Brown', department: 'Sales', salary: 68000 },
+    { id: 5, name: 'Eva Martinez', department: 'Marketing', salary: 78000 },
+  ];
+
+  private readonly columns: IColumnDef<Employee>[] = [
+    { columnId: 'name', name: 'Name', sortable: true },
+    {
+      columnId: 'department', name: 'Department', sortable: true,
+      filterable: { type: 'multiSelect', options: ['Engineering', 'Marketing', 'Sales'] },
+    },
+    {
+      columnId: 'salary', name: 'Salary', type: 'numeric', sortable: true, editable: true,
+      valueFormatter: (value) =>
+        new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value as number),
+    },
+  ];
+
+  gridProps = {
+    columns: this.columns,
+    data: this.data,
+    getRowId: (row: Employee) => row.id,
+    defaultPageSize: 10,
+    defaultSortBy: 'name',
+    statusBar: true,
+  };
+}
+```
+
+:::tip Switching UI libraries
+Same component API across Angular packages. To switch, just change the import:
+
+- **Radix (CDK)** (lightweight): `from '@alaarab/ogrid-angular-radix'`
+- **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 Employee {
+  id: number;
+  name: string;
+  department: string;
+  salary: number;
+}
+
+const data: Employee[] = [
+  { id: 1, name: 'Alice Johnson', department: 'Engineering', salary: 95000 },
+  { id: 2, name: 'Bob Smith', department: 'Marketing', salary: 72000 },
+  { id: 3, name: 'Carol Williams', department: 'Engineering', salary: 110000 },
+  { id: 4, name: 'David Brown', department: 'Sales', salary: 68000 },
+  { id: 5, name: 'Eva Martinez', department: 'Marketing', salary: 78000 },
+];
+
+const columns: IColumnDef<Employee>[] = [
+  { columnId: 'name', name: 'Name', sortable: true },
+  {
+    columnId: 'department', name: 'Department', sortable: true,
+    filterable: { type: 'multiSelect', options: ['Engineering', 'Marketing', 'Sales'] },
+  },
+  {
+    columnId: 'salary', name: 'Salary', type: 'numeric', sortable: true, editable: true,
+    valueFormatter: (value) =>
+      new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value as number),
+  },
+];
+
+const gridProps = {
+  columns,
+  data,
+  getRowId: (row: Employee) => row.id,
+  defaultPageSize: 10,
+  defaultSortBy: 'name',
+  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)** (lightweight): `from '@alaarab/ogrid-vue-radix'`
+- **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', sortable: true },
+    {
+      columnId: 'department',
+      name: 'Department',
+      sortable: true,
+      filterable: { type: 'multiSelect', options: ['Engineering', 'Marketing', 'Sales'] },
+    },
+    {
+      columnId: 'salary',
+      name: 'Salary',
+      type: 'numeric',
+      sortable: true,
+      editable: true,
+      valueFormatter: (value) =>
+        new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value),
+    },
+  ],
+  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: 'Engineering', salary: 110000 },
+    { id: 4, name: 'David Brown', department: 'Sales', salary: 68000 },
+    { id: 5, name: 'Eva Martinez', department: 'Marketing', salary: 78000 },
+  ],
+  getRowId: (row) => row.id,
+  pageSize: 10,
+  editable: true,
+});
+```
+
+:::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.
+:::
+
+  </TabItem>
+</Tabs>
+
+## What You Get
+
+With just this code:
+
+- **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
+
+## Key Concepts
+
+| 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. |
+
+## Using the Grid API
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+function App() {
+  const gridRef = useRef<IOGridApi<Employee>>(null);
+
+  return (
+    <>
+      <button onClick={() => console.log(gridRef.current?.getColumnState())}>
+        Log State
+      </button>
+      <OGrid<Employee> ref={gridRef} columns={columns} data={data} getRowId={(row) => row.id} />
+    </>
+  );
+}
+```
+
+  </TabItem>
+  <TabItem value="angular" label="Angular">
+
+```typescript
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `
+    <button (click)="logState()">Log State</button>
+    <ogrid [props]="gridProps" />
+  `
+})
+export class AppComponent {
+  constructor(private gridService: OGridService) {}
+
+  logState() {
+    console.log(this.gridService.getColumnState());
+  }
+
+  gridProps = { columns, data, getRowId: (row: any) => row.id };
+}
+```
+
+  </TabItem>
+  <TabItem value="vue" label="Vue">
+
+```vue
+<script setup lang="ts">
+
+const { getColumnState } = useOGrid({ columns, data, getRowId: (row) => row.id });
+
+function logState() {
+  console.log(getColumnState());
+}
+</script>
+
+<template>
+  <button @click="logState">Log State</button>
+  <OGrid :gridProps="{ columns, data, getRowId: (row) => row.id }" />
+</template>
+```
+
+  </TabItem>
+  <TabItem value="js" label="Vanilla JS">
+
+```js
+
+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);
+
+// Cleanup
+grid.destroy();
+```
+
+  </TabItem>
+</Tabs>
+
+## Next Steps
+
+- [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

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

@@ -0,0 +1,191 @@
+---
+sidebar_position: 4
+title: Vanilla JS
+description: Use OGrid without React — pure JavaScript, class-based API
+---
+
+
+# Vanilla JS Quick Start
+
+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.
+
+## Install
+
+```bash
+npm install @alaarab/ogrid-js
+```
+
+## Basic Example
+
+```html
+<div id="grid" style="height: 400px;"></div>
+
+<script type="module">
+  import { OGrid } from '@alaarab/ogrid-js';
+  import '@alaarab/ogrid-js/styles'; // default theme (light + dark mode)
+
+  const grid = new OGrid(document.getElementById('grid'), {
+    columns: [
+      { columnId: 'name', name: 'Name', sortable: true },
+      { columnId: 'department', name: 'Department', sortable: true },
+      {
+        columnId: 'salary',
+        name: 'Salary',
+        type: 'numeric',
+        sortable: true,
+        editable: true,
+        valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+      },
+    ],
+    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 },
+    ],
+    getRowId: (row) => row.id,
+    pageSize: 10,
+    editable: true,
+    cellSelection: true,
+    statusBar: true,
+  });
+</script>
+```
+
+## Live Demo
+
+<VanillaJSDemo />
+
+## What You Get
+
+With this code you have:
+
+- **Sorting** — click column headers
+- **Inline editing** — double-click any salary cell
+- **Cell selection** — click and drag to select ranges
+- **Keyboard navigation** — arrow keys, Tab, Home/End, Ctrl+Arrow
+- **Clipboard** — Ctrl+C/V/X
+- **Undo/redo** — Ctrl+Z/Y
+- **Status bar** — row count and selection aggregations
+- **Pagination** — page controls at the bottom
+
+## Constructor
+
+```js
+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). |
+
+## 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 |
+| `pageSize` | `number` | `20` | Rows per page |
+| `sort` | `{ field, direction }` | — | Initial sort |
+| `filters` | `IFilters` | — | Initial filters |
+| `editable` | `boolean` | `false` | Enable cell editing |
+| `cellSelection` | `boolean` | `false` | Enable spreadsheet-style 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 |
+
+## Events
+
+Listen for events with `.on()`:
+
+```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('selectionChange', ({ selectedRows }) => {
+  console.log(`${selectedRows.length} rows selected`);
+});
+```
+
+| Event | Payload | Fired when |
+|-------|---------|------------|
+| `cellValueChanged` | `{ item, columnId, oldValue, newValue }` | A cell edit is committed |
+| `sortChange` | `{ field, direction }` | Sort changes |
+| `filterChange` | `{ filters }` | Filters change |
+| `pageChange` | `{ page }` | Page changes |
+| `selectionChange` | `{ selectedRows, selectedRowIds }` | Row selection changes |
+
+## Grid API
+
+Access the imperative API via `grid.api`:
+
+```js
+// Update data
+grid.api.setRowData(newData);
+
+// Get current state
+const state = grid.api.getColumnState();
+
+// Export to CSV
+grid.api.exportToCsv('my-data.csv');
+
+// Programmatic sort
+grid.api.setSort('salary', 'desc');
+```
+
+See the full [JS API Reference](../api/js-api) for all methods.
+
+## Theming
+
+The default theme uses CSS custom properties. Override them to match your design:
+
+```css
+:root {
+  --ogrid-primary: #0066cc;       /* buttons, active page */
+  --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 */
+}
+```
+
+For dark mode, set `data-theme="dark"` on a parent element or rely on `prefers-color-scheme`:
+
+```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.
+
+## Cleanup
+
+Always destroy the grid when you're done:
+
+```js
+grid.destroy();
+```
+
+This removes all DOM elements, event listeners, and ResizeObservers.
+
+## Next Steps
+
+- [JS API Reference](../api/js-api) — full method and options reference
+- [Features](../features/sorting) — all grid features work identically in JS
+- [Theming Guide](../guides/theming) — deep dive into CSS customization