@alaarab/ogrid-mcp 2.9.0 → 2.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/bundled-docs/api/README.md +7 -32
  2. package/bundled-docs/api/column-def.mdx +1 -1
  3. package/bundled-docs/api/components-column-chooser.mdx +0 -96
  4. package/bundled-docs/api/components-column-header-filter.mdx +1 -83
  5. package/bundled-docs/api/components-datagrid-table.mdx +0 -63
  6. package/bundled-docs/api/components-pagination-controls.mdx +0 -94
  7. package/bundled-docs/api/components-sidebar.mdx +0 -76
  8. package/bundled-docs/api/components-status-bar.mdx +0 -66
  9. package/bundled-docs/api/headless-hooks.mdx +410 -0
  10. package/bundled-docs/api/ogrid-props.mdx +1 -1
  11. package/bundled-docs/api/types.mdx +1 -1
  12. package/bundled-docs/features/cell-references.mdx +2 -116
  13. package/bundled-docs/features/column-chooser.mdx +0 -131
  14. package/bundled-docs/features/column-groups.mdx +1 -136
  15. package/bundled-docs/features/column-pinning.mdx +1 -108
  16. package/bundled-docs/features/column-reordering.mdx +1 -168
  17. package/bundled-docs/features/column-types.mdx +0 -71
  18. package/bundled-docs/features/context-menu.mdx +1 -93
  19. package/bundled-docs/features/csv-export.mdx +1 -104
  20. package/bundled-docs/features/editing.mdx +0 -149
  21. package/bundled-docs/features/filtering.mdx +0 -119
  22. package/bundled-docs/features/formulas.mdx +2 -102
  23. package/bundled-docs/features/grid-api.mdx +1 -108
  24. package/bundled-docs/features/keyboard-navigation.mdx +1 -74
  25. package/bundled-docs/features/mobile-touch.mdx +0 -71
  26. package/bundled-docs/features/pagination.mdx +0 -105
  27. package/bundled-docs/features/performance.mdx +0 -191
  28. package/bundled-docs/features/premium-inputs.mdx +0 -311
  29. package/bundled-docs/features/responsive-columns.mdx +1 -76
  30. package/bundled-docs/features/row-selection.mdx +2 -106
  31. package/bundled-docs/features/server-side-data.mdx +1 -129
  32. package/bundled-docs/features/sidebar.mdx +1 -78
  33. package/bundled-docs/features/sorting.mdx +2 -108
  34. package/bundled-docs/features/spreadsheet-selection.mdx +2 -79
  35. package/bundled-docs/features/status-bar.mdx +1 -72
  36. package/bundled-docs/features/toolbar.mdx +1 -75
  37. package/bundled-docs/features/virtual-scrolling.mdx +1 -304
  38. package/bundled-docs/getting-started/headless-or-component.mdx +112 -0
  39. package/bundled-docs/getting-started/installation.mdx +11 -141
  40. package/bundled-docs/getting-started/overview.mdx +15 -55
  41. package/bundled-docs/getting-started/quick-start.mdx +4 -279
  42. package/bundled-docs/guides/browser-support-matrix.mdx +6 -17
  43. package/bundled-docs/guides/mcp-live-testing.mdx +0 -82
  44. package/bundled-docs/guides/mcp.mdx +4 -4
  45. package/bundled-docs/guides/migration-from-ag-grid.mdx +2 -3
  46. package/bundled-docs/guides/theming.mdx +50 -23
  47. package/dist/esm/index.js +9 -39
  48. package/package.json +5 -5
  49. package/bundled-docs/api/js-api.mdx +0 -198
  50. package/bundled-docs/getting-started/vanilla-js.mdx +0 -218
  51. package/bundled-docs/guides/framework-showcase.mdx +0 -246
package/bundled-docs/guides/theming.mdx CHANGED
@@ -61,29 +61,6 @@ function App() {
61
61
 
62
62
  Fluent also uses CSS Modules for grid-specific styles (cell selection, fill handle, etc.).
63
63
 
64
- ### Material UI (`@alaarab/ogrid-react-material`)
65
-
66
- The Material implementation renders with MUI v7 components, which inherit from `ThemeProvider`. Wrap your app in a `ThemeProvider` with your theme:
67
-
68
- ```tsx
69
-
70
- const theme = createTheme({
71
- palette: {
72
- primary: { main: '#1976d2' },
73
- },
74
- });
75
-
76
- function App() {
77
- return (
78
- <ThemeProvider theme={theme}>
79
- <OGrid columns={columns} data={data} getRowId={(item) => item.id} />
80
- </ThemeProvider>
81
- );
82
- }
83
- ```
84
-
85
- Material uses CSS-in-JS (inline styles) for grid-specific styling rather than CSS Modules.
86
-
87
64
  ## Layout Mode
88
65
 
89
66
  The `layoutMode` prop controls how the grid sizes itself:
@@ -209,3 +186,53 @@ Users can resize columns by dragging the column border. Listen for resize events
209
186
  }}
210
187
  />
211
188
  ```
189
+
190
+ ## Theme presets (new in 2.9)
191
+
192
+ Instead of mapping `--ogrid-*` variables to your design system one-by-one,
193
+ shadcn/Tailwind v4 preset ships with `@alaarab/ogrid-react-radix`:
194
+
195
+ ```ts
196
+ ```
197
+
198
+ The preset maps `--ogrid-bg → var(--card)`, `--ogrid-fg → var(--card-foreground)`,
199
+ `--ogrid-header-bg → var(--muted)`, `--ogrid-primary → var(--primary)`,
200
+ `--ogrid-accent → var(--ring)`, `--ogrid-border → var(--border)`,
201
+ `--ogrid-radius → var(--radius)`, `--ogrid-font → var(--font-sans)`, and
202
+ derived states (`--ogrid-selected-row-bg`, `--ogrid-range-bg`, etc.) via
203
+ `color-mix(in oklch, var(--ring) 12%, transparent)` so they auto-tint to
204
+ your primary/ring hue.
205
+
206
+ Both light and dark modes follow your shadcn theme automatically — no
207
+ hand-authored `[data-theme="dark"]` override blocks needed. The `.dark`
208
+ class on `<html>` (Tailwind v3+/shadcn convention) is fully supported.
209
+
210
+ ### New theming tokens (2.9)
211
+
212
+ In addition to the colors documented above, 2.8.0 added a radius/font/ring
213
+ scale that `preset-shadcn.css` bridges automatically:
214
+
215
+ | Variable | Default | Description |
216
+ |----------|---------|-------------|
217
+ | `--ogrid-radius` | `6px` | Base corner radius — buttons, inputs, popovers |
218
+ | `--ogrid-radius-sm` | `calc(--ogrid-radius * 0.6)` | Tighter — checkboxes, tags |
219
+ | `--ogrid-radius-lg` | `calc(--ogrid-radius * 1.4)` | Looser — cards, dialogs |
220
+ | `--ogrid-radius-xl` | `calc(--ogrid-radius * 1.8)` | Largest — hero surfaces |
221
+ | `--ogrid-radius-full` | `9999px` | Pills, dots |
222
+ | `--ogrid-font` | `inherit` | Font family for grid chrome |
223
+ | `--ogrid-font-size` | `13px` | Base body font-size |
224
+ | `--ogrid-ring` | `var(--ogrid-accent)` | Focus ring color |
225
+
226
+ Override `--ogrid-radius` once and every corner in OGrid scales (sm/lg/xl
227
+ are `calc()`'d from the base).
228
+
229
+ ### Dark mode signals
230
+
231
+ OGrid honors three dark-mode activation signals:
232
+
233
+ 1. `prefers-color-scheme: dark` — system preference (auto)
234
+ 2. `[data-theme="dark"]` on any ancestor (explicit)
235
+ 3. `.dark` on any ancestor — Tailwind v3+/shadcn convention (explicit)
236
+
237
+ Opt out of auto-dark on a deliberate-light-mode app by setting
238
+ `[data-theme="light"]` or `.light` on `<html>`.
package/dist/esm/index.js CHANGED
@@ -43,21 +43,11 @@ function parseFrontmatter(raw) {
43
43
  var CODE_BLOCK_RE = /```(\w*)\n([\s\S]*?)```/g;
44
44
  function detectFramework(language, code, surroundingContext) {
45
45
  if (language === "tsx" || language === "jsx") return "react";
46
- if (language === "vue") return "vue";
47
46
  const ctxLower = surroundingContext.toLowerCase();
48
47
  if (ctxLower.includes('value="react"') || ctxLower.includes('label="react"'))
49
48
  return "react";
50
- if (ctxLower.includes('value="angular"') || ctxLower.includes('label="angular"'))
51
- return "angular";
52
- if (ctxLower.includes('value="vue"') || ctxLower.includes('label="vue"'))
53
- return "vue";
54
- if (ctxLower.includes('value="js"') || ctxLower.includes('label="vanilla js"') || ctxLower.includes("vanilla js"))
55
- return "js";
56
- if (code.includes("@angular/") || code.includes("@Component")) return "angular";
57
- if (code.includes("ogrid-vue") || code.includes("<template>")) return "vue";
58
49
  if (code.includes("ogrid-react") || code.includes("from 'react'"))
59
50
  return "react";
60
- if (code.includes("ogrid-js") || code.includes("new OGrid(")) return "js";
61
51
  return void 0;
62
52
  }
63
53
  function extractCodeBlocks(raw) {
@@ -185,9 +175,9 @@ function loadDocsIndex(docsDir2) {
185
175
  }
186
176
  function detectFramework2(packageNames) {
187
177
  if (packageNames.some((n) => n.includes("-react"))) return "react";
188
- if (packageNames.some((n) => n.includes("-angular"))) return "angular";
189
- if (packageNames.some((n) => n.includes("-vue"))) return "vue";
190
- if (packageNames.some((n) => n.endsWith("-js"))) return "js";
178
+ if (packageNames.some((n) => n.endsWith("-js"))) return "js (frozen at v2.9.1)";
179
+ if (packageNames.some((n) => n.includes("-angular"))) return "angular (frozen at v2.9.0)";
180
+ if (packageNames.some((n) => n.includes("-vue"))) return "vue (frozen at v2.9.0)";
191
181
  return "unknown";
192
182
  }
193
183
  function detectOGridVersion(searchPath) {
@@ -228,7 +218,7 @@ function createOGridMcpServer(index2, bridge) {
228
218
  const server2 = new McpServer({
229
219
  name: "ogrid-docs",
230
220
  version: "2.3.0",
231
- instructions: `OGrid documentation server. OGrid is a lightweight multi-framework data grid for React, Angular, Vue, and vanilla JS.
221
+ instructions: `OGrid documentation server. OGrid is a lightweight, headless data grid for React (Radix and Fluent UI implementations).
232
222
 
233
223
  Tools: search_docs (keyword search), list_docs (browse by category), get_docs (full page), get_code_example (code snippets), detect_version (detect OGrid version in your project).
234
224
  Resources: ogrid://quick-reference (key API overview), ogrid://docs/{path} (any doc page by path).
@@ -240,7 +230,7 @@ Categories: features, getting-started, guides, api.`
240
230
  {
241
231
  query: z.string().describe("Search query string"),
242
232
  limit: z.number().int().min(1).max(20).optional().describe("Max results to return (default 5)"),
243
- framework: z.enum(["react", "angular", "vue", "js"]).optional().describe("Filter code examples to this framework")
233
+ framework: z.enum(["react"]).optional().describe("Filter code examples to this framework")
244
234
  },
245
235
  async ({ query, limit, framework }) => {
246
236
  const results = index2.search(query, limit ?? 5);
@@ -353,7 +343,7 @@ ${available}`
353
343
  "Find code examples from OGrid docs matching a query, optionally filtered by framework.",
354
344
  {
355
345
  query: z.string().describe("Search query for code examples"),
356
- framework: z.enum(["react", "angular", "vue", "js"]).optional().describe("Filter by framework: react, angular, vue, js")
346
+ framework: z.enum(["react"]).optional().describe("Filter by framework: react")
357
347
  },
358
348
  async ({ query, framework }) => {
359
349
  const examples = index2.getCodeExamples(query, framework);
@@ -410,15 +400,9 @@ ${formatted}`
410
400
  text: [
411
401
  `No OGrid packages found in package.json (searched from: ${searchPath}).`,
412
402
  "",
413
- "Install OGrid for your framework:",
414
- " React (Radix): npm install @alaarab/ogrid-react-radix",
415
- " React (Material): npm install @alaarab/ogrid-react-material",
416
- " React (Fluent): npm install @alaarab/ogrid-react-fluent",
417
- " Angular Material: npm install @alaarab/ogrid-angular-material",
418
- " Angular PrimeNG: npm install @alaarab/ogrid-angular-primeng",
419
- " Vue Vuetify: npm install @alaarab/ogrid-vue-vuetify",
420
- " Vue PrimeVue: npm install @alaarab/ogrid-vue-primevue",
421
- " Vanilla JS: npm install @alaarab/ogrid-js"
403
+ "Install OGrid:",
404
+ " React (Radix): npm install @alaarab/ogrid-react-radix",
405
+ " React (Fluent): npm install @alaarab/ogrid-react-fluent"
422
406
  ].join("\n")
423
407
  }
424
408
  ]
@@ -463,21 +447,7 @@ Tip: use \`get_code_example\` with framework="${result.framework}" or \`search_d
463
447
  "```bash",
464
448
  "# React (choose one)",
465
449
  "npm install @alaarab/ogrid-react-radix",
466
- "npm install @alaarab/ogrid-react-material",
467
450
  "npm install @alaarab/ogrid-react-fluent",
468
- "",
469
- "# Angular (choose one)",
470
- "npm install @alaarab/ogrid-angular-material",
471
- "npm install @alaarab/ogrid-angular-primeng",
472
- "npm install @alaarab/ogrid-angular-radix",
473
- "",
474
- "# Vue (choose one)",
475
- "npm install @alaarab/ogrid-vue-vuetify",
476
- "npm install @alaarab/ogrid-vue-primevue",
477
- "npm install @alaarab/ogrid-vue-radix",
478
- "",
479
- "# Vanilla JS",
480
- "npm install @alaarab/ogrid-js",
481
451
  "```",
482
452
  "",
483
453
  "## Core Props (IOGridProps)",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alaarab/ogrid-mcp",
3
- "version": "2.9.0",
3
+ "version": "2.11.0",
4
4
  "description": "MCP server for OGrid documentation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -25,15 +25,15 @@
25
25
  "prebuild": "node scripts/bundle-docs.mjs",
26
26
  "build": "tsup",
27
27
  "dev": "tsup --watch",
28
- "test": "jest"
28
+ "test": "bun test --preload ../../bun-test.setup.ts"
29
29
  },
30
30
  "dependencies": {
31
- "@modelcontextprotocol/sdk": "^1.28.0",
32
- "zod": "^4.0.0"
31
+ "@modelcontextprotocol/sdk": "^1.29.0",
32
+ "zod": "^4.4.2"
33
33
  },
34
34
  "devDependencies": {
35
35
  "tsup": "^8.5.1",
36
- "typescript": "^6.0.0"
36
+ "typescript": "^6.0.3"
37
37
  },
38
38
  "engines": {
39
39
  "node": ">=18"
package/bundled-docs/api/js-api.mdx DELETED
@@ -1,198 +0,0 @@
1
- ---
2
- sidebar_position: 5
3
- title: Vanilla JS API
4
- description: Full API reference for @alaarab/ogrid-js
5
- ---
6
-
7
- # Vanilla JS API
8
-
9
- Complete reference for `@alaarab/ogrid-js` - the framework-free data grid.
10
-
11
- ## OGrid Class
12
-
13
- ```js
14
-
15
- const grid = new OGrid(container, options);
16
- ```
17
-
18
- ### Constructor
19
-
20
- | Parameter | Type | Description |
21
- |-----------|------|-------------|
22
- | `container` | `HTMLElement` | DOM element to render into. OGrid fills this container. |
23
- | `options` | `OGridOptions<T>` | Configuration object (see below). |
24
-
25
- ### Instance Methods
26
-
27
- | Method | Description |
28
- |--------|-------------|
29
- | `grid.api` | The imperative API object (see [API Methods](#api-methods) below). |
30
- | `grid.on(event, handler)` | Subscribe to a grid event. Returns `void`. |
31
- | `grid.off(event, handler)` | Unsubscribe from a grid event. |
32
- | `grid.destroy()` | Tear down the grid - removes DOM, listeners, and ResizeObservers. |
33
-
34
- ---
35
-
36
- ## OGridOptions\<T\>
37
-
38
- All configuration is passed to the constructor.
39
-
40
- ### Data
41
-
42
- | Option | Type | Default | Description |
43
- |--------|------|---------|-------------|
44
- | `columns` | `(IColumnDef<T> \| IColumnGroupDef<T>)[]` | **required** | Column definitions. |
45
- | `getRowId` | `(item: T) => RowId` | **required** | Returns a unique `string \| number` per row. |
46
- | `data` | `T[]` | - | Client-side data. Mutually exclusive with `dataSource`. |
47
- | `dataSource` | `IDataSource<T>` | - | Server-side data source. Mutually exclusive with `data`. |
48
-
49
- ### Pagination & Sorting
50
-
51
- | Option | Type | Default | Description |
52
- |--------|------|---------|-------------|
53
- | `page` | `number` | `1` | Initial page (1-based). |
54
- | `pageSize` | `number` | `20` | Rows per page. |
55
- | `sort` | `{ field: string; direction: 'asc' \| 'desc' }` | - | Initial sort state. |
56
- | `filters` | `IFilters` | - | Initial filter state. |
57
-
58
- ### Interaction
59
-
60
- | Option | Type | Default | Description |
61
- |--------|------|---------|-------------|
62
- | `editable` | `boolean` | `false` | Enable inline cell editing. |
63
- | `cellSelection` | `boolean` | `false` | Enable spreadsheet-style cell/range selection. |
64
- | `rowSelection` | `'single' \| 'multiple'` | - | Row checkbox selection mode. |
65
- | `selectedRows` | `Set<RowId>` | - | Controlled selected row IDs. |
66
- | `pinnedColumns` | `Record<string, 'left' \| 'right'>` | - | Pin columns to left/right edges. |
67
- | `visibleColumns` | `Set<string>` | all | Initially visible column IDs. |
68
-
69
- ### Layout
70
-
71
- | Option | Type | Default | Description |
72
- |--------|------|---------|-------------|
73
- | `layoutMode` | `'fill' \| 'content'` | `'fill'` | `'fill'` stretches to container; `'content'` sizes to data. |
74
- | `suppressHorizontalScroll` | `boolean` | `false` | Prevent horizontal scrollbar. |
75
- | `sideBar` | `boolean \| ISideBarDef` | - | Show sidebar with columns/filters panels. |
76
- | `emptyMessage` | `string` | `'No data'` | Custom empty state text. |
77
- | `aria-label` | `string` | - | Accessible label for the grid. |
78
-
79
- ### Callbacks
80
-
81
- | Option | Type | Description |
82
- |--------|------|-------------|
83
- | `onCellValueChanged` | `(event: ICellValueChangedEvent<T>) => void` | Fired when a cell edit is committed. |
84
- | `onSelectionChange` | `(event: IRowSelectionChangeEvent<T>) => void` | Fired when row selection changes. |
85
- | `onError` | `(error: unknown) => void` | Fired on server-side data source failures. |
86
- | `onFirstDataRendered` | `() => void` | Fired once when the first data render completes. |
87
-
88
- ---
89
-
90
- ## API Methods
91
-
92
- Access via `grid.api`:
93
-
94
- ### Data
95
-
96
- | Method | Signature | Description |
97
- |--------|-----------|-------------|
98
- | `setRowData` | `(data: T[]) => void` | Replace the entire dataset (client-side only; no-op with `dataSource`). |
99
- | `setLoading` | `(loading: boolean) => void` | Show or hide the loading overlay. |
100
- | `getDisplayedRows` | `() => T[]` | Get the currently visible (filtered, sorted, paginated) rows. |
101
- | `refreshData` | `() => void` | Re-fetch from `dataSource` (server-side only). |
102
-
103
- ### Sorting & Filtering
104
-
105
- | Method | Signature | Description |
106
- |--------|-----------|-------------|
107
- | `setFilterModel` | `(filters: IFilters) => void` | Set the full filter model. Pass `{}` to clear all filters. |
108
- | `clearFilters` | `() => void` | Clear all active filters. Shorthand for `setFilterModel({})`. |
109
- | `clearSort` | `() => void` | Reset the sort to no active sort. |
110
- | `resetGridState` | `(options?: { keepSelection?: boolean }) => void` | Reset all grid state (filters, sort, and optionally selection). |
111
-
112
- ### Columns
113
-
114
- | Method | Signature | Description |
115
- |--------|-----------|-------------|
116
- | `getColumnState` | `() => IGridColumnState` | Get current column state (visibility, sort, order, widths, filters). |
117
- | `applyColumnState` | `(state: Partial<IGridColumnState>) => void` | Bulk-restore any combination of column state fields. |
118
- | `getColumnOrder` | `() => string[]` | Get the current column display order (array of column IDs). |
119
- | `setColumnOrder` | `(order: string[]) => void` | Set the column display order programmatically. |
120
-
121
- ### Selection
122
-
123
- | Method | Signature | Description |
124
- |--------|-----------|-------------|
125
- | `selectAll` | `() => void` | Select all rows (requires `rowSelection: 'multiple'`). |
126
- | `deselectAll` | `() => void` | Deselect all rows. |
127
- | `getSelectedRows` | `() => RowId[]` | Get the IDs of currently selected rows. |
128
- | `setSelectedRows` | `(rowIds: RowId[]) => void` | Set which rows are selected by their IDs. |
129
-
130
- ### Export
131
-
132
- | Method | Signature | Description |
133
- |--------|-----------|-------------|
134
- | `exportToCsv` | `(filename?: string) => void` | Export displayed rows to CSV and trigger a browser download. |
135
-
136
- ### Virtual Scrolling
137
-
138
- | Method | Signature | Description |
139
- |--------|-----------|-------------|
140
- | `scrollToRow` | `(index: number, options?: { align?: 'start' \| 'center' \| 'end' }) => void` | Scroll to a specific row by index. Only effective when virtual scrolling is enabled. |
141
-
142
- ---
143
-
144
- ## Events
145
-
146
- Subscribe with `grid.on(eventName, handler)`.
147
-
148
- | Event | Payload Type | Fired When |
149
- |-------|-------------|------------|
150
- | `cellValueChanged` | `ICellValueChangedEvent<T>` | A cell edit is committed |
151
- | `selectionChange` | `IRowSelectionChangeEvent<T>` | Row selection changes |
152
- | `sortChange` | `{ sort: { field: string; direction: 'asc' \| 'desc' } \| undefined }` | Sort state changes |
153
- | `filterChange` | `{ filters: IFilters }` | Filter state changes |
154
- | `pageChange` | `{ page: number }` | Current page changes |
155
-
156
- ### ICellValueChangedEvent\<T\>
157
-
158
- ```ts
159
- {
160
- item: T; // The row data object
161
- columnId: string; // Which column was edited
162
- oldValue: unknown; // Previous cell value
163
- newValue: unknown; // New cell value
164
- rowIndex: number; // Row index of the edited cell
165
- }
166
- ```
167
-
168
- ---
169
-
170
- ## IColumnDef\<T\> (JS-specific)
171
-
172
- The JS package extends the core `IColumnDef<T>` with DOM-aware fields:
173
-
174
- | Field | Type | Description |
175
- |-------|------|-------------|
176
- | `renderCell` | `(cell: HTMLTableCellElement, item: T, value: unknown) => void` | Custom cell renderer - mutate the `<td>` DOM directly. |
177
- | `cellStyle` | `Partial<CSSStyleDeclaration>` | Inline styles applied to each cell. |
178
- | `cellEditor` | `string \| (container: HTMLElement, params: object) => { getValue: () => unknown; destroy: () => void }` | Built-in editor name (`'text'`, `'select'`, `'richSelect'`, `'checkbox'`, `'date'`) or a factory function for custom editors. |
179
-
180
- All other `IColumnDef` fields (`columnId`, `name`, `sortable`, `filterable`, `type`, `editable`, `valueFormatter`, `valueGetter`, `valueParser`, `minWidth`, `defaultWidth`, `idealWidth`, `pinned`, `required`, `defaultVisible`) follow the shared column-definition contract used across the framework packages. See [Column Definitions](./column-def).
181
-
182
- ---
183
-
184
- ## CSS Classes
185
-
186
- The JS package renders semantic HTML with `ogrid-*` class names. Import the default theme or write your own CSS targeting these selectors:
187
-
188
- ### Layout
189
- `ogrid-container`, `ogrid-toolbar`, `ogrid-body-area`, `ogrid-table-container`, `ogrid-sidebar-container`, `ogrid-status-bar-container`, `ogrid-pagination-container`
190
-
191
- ### Table
192
- `ogrid-wrapper`, `ogrid-table`, `ogrid-header-cell`, `ogrid-group-header`, `ogrid-sortable`, `ogrid-sort-indicator`, `ogrid-resize-handle`, `ogrid-filter-icon`, `ogrid-row`, `ogrid-cell`, `ogrid-checkbox-header`, `ogrid-checkbox-cell`, `ogrid-fill-handle`, `ogrid-empty-state`
193
-
194
- ### Data Attributes
195
- `[data-active-cell]`, `[data-in-range]`, `[data-drag-range]`, `[data-row-selected]`, `[data-pinned="left|right"]`, `[data-column-id]`, `[data-row-index]`, `[data-col-index]`
196
-
197
- ### CSS Variables
198
- Override `--ogrid-bg`, `--ogrid-fg`, `--ogrid-border`, `--ogrid-primary`, `--ogrid-selection`, `--ogrid-bg-subtle`, `--ogrid-bg-hover`, `--ogrid-muted`, and more. See [Theming](../guides/theming).
package/bundled-docs/getting-started/vanilla-js.mdx DELETED
@@ -1,218 +0,0 @@
1
- ---
2
- sidebar_position: 4
3
- title: Vanilla JS
4
- description: OGrid without a framework — pure JavaScript, class-based API
5
- ---
6
-
7
-
8
- # Vanilla JS
9
-
10
- You don't need React, Angular, or Vue to use OGrid. The `@alaarab/ogrid-js` package gives you a sortable, filterable, editable data grid with the shared OGrid core through a simple class-based API — just a container element and an options object.
11
-
12
- 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.
13
-
14
- ## Install
15
-
16
- ```bash
17
- npm install @alaarab/ogrid-js
18
- ```
19
-
20
- Or drop it into an HTML file directly using a CDN (no build tools needed):
21
-
22
- ```html
23
- <script type="module">
24
- import { OGrid } from 'https://cdn.jsdelivr.net/npm/@alaarab/ogrid-js/dist/esm/index.js';
25
- </script>
26
- ```
27
-
28
- ## Build a real example
29
-
30
- Let's make an order management dashboard. It tracks orders by status, amount, and customer — sortable, filterable, and editable inline.
31
-
32
- ```html
33
- <div id="orders-grid" style="height: 500px;"></div>
34
-
35
- <script type="module">
36
- import { OGrid } from '@alaarab/ogrid-js';
37
- import '@alaarab/ogrid-js/styles';
38
-
39
- const grid = new OGrid(document.getElementById('orders-grid'), {
40
- columns: [
41
- { columnId: 'orderId', name: 'Order #', sortable: true },
42
- { columnId: 'customer', name: 'Customer', sortable: true },
43
- {
44
- columnId: 'status',
45
- name: 'Status',
46
- sortable: true,
47
- filterable: { type: 'multiSelect', options: ['Pending', 'Shipped', 'Delivered', 'Cancelled'] },
48
- },
49
- {
50
- columnId: 'amount',
51
- name: 'Amount',
52
- type: 'numeric',
53
- sortable: true,
54
- editable: true,
55
- valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
56
- },
57
- {
58
- columnId: 'date',
59
- name: 'Order Date',
60
- type: 'date',
61
- sortable: true,
62
- },
63
- ],
64
- data: [
65
- { orderId: 'ORD-1001', customer: 'Acme Corp', status: 'Shipped', amount: 4200, date: '2024-03-01' },
66
- { orderId: 'ORD-1002', customer: 'Globex Inc', status: 'Pending', amount: 1850, date: '2024-03-03' },
67
- { orderId: 'ORD-1003', customer: 'Initech', status: 'Delivered', amount: 9300, date: '2024-02-28' },
68
- { orderId: 'ORD-1004', customer: 'Umbrella LLC', status: 'Cancelled', amount: 620, date: '2024-03-05' },
69
- { orderId: 'ORD-1005', customer: 'Acme Corp', status: 'Delivered', amount: 7100, date: '2024-02-20' },
70
- ],
71
- getRowId: (row) => row.orderId,
72
- pageSize: 20,
73
- cellSelection: true,
74
- statusBar: true,
75
- });
76
-
77
- // React to edits in real time
78
- grid.on('cellValueChanged', ({ item, columnId, newValue }) => {
79
- console.log(`Order ${item.orderId}: ${columnId} updated to ${newValue}`);
80
- // sync to your backend here
81
- });
82
- </script>
83
- ```
84
-
85
- ## Live demo
86
-
87
- <VanillaJSDemo />
88
-
89
- ## What you get out of the box
90
-
91
- The JS package shares the same data model and most feature concepts as the framework packages, but browser-level interaction parity is still tracked package by package.
92
-
93
- - **Sorting** — click column headers
94
- - **Filtering** — multi-select dropdown on the Status column
95
- - **Inline editing** — double-click any Amount cell to edit
96
- - **Cell selection** — click and drag to select ranges
97
- - **Keyboard navigation** — arrow keys, Tab, Home/End, Ctrl+Arrow
98
- - **Clipboard** — Ctrl+C/V/X works like a spreadsheet
99
- - **Undo/redo** — Ctrl+Z/Y
100
- - **Status bar** — row count and selection aggregations
101
- - **Pagination** — page controls at the bottom
102
-
103
- ## Constructor
104
-
105
- ```js
106
- const grid = new OGrid(containerElement, options);
107
- ```
108
-
109
- The container element defines where the grid renders. OGrid fills it completely — give it an explicit height (CSS or inline).
110
-
111
- ## Key options
112
-
113
- | Option | Type | Default | Description |
114
- |--------|------|---------|-------------|
115
- | `columns` | `IColumnDef<T>[]` | **required** | Column definitions |
116
- | `data` | `T[]` | — | Client-side row data |
117
- | `dataSource` | `IDataSource<T>` | — | Server-side data source (use instead of `data`) |
118
- | `getRowId` | `(item: T) => RowId` | **required** | Returns a unique identifier per row |
119
- | `pageSize` | `number` | `20` | Rows per page |
120
- | `sort` | `{ field, direction }` | — | Initial sort state |
121
- | `filters` | `IFilters` | — | Initial filters |
122
- | `editable` | `boolean` | `false` | Enable cell editing |
123
- | `cellSelection` | `boolean` | `false` | Spreadsheet-style range selection |
124
- | `rowSelection` | `'single' \| 'multiple'` | — | Row selection mode |
125
- | `sideBar` | `boolean \| ISideBarDef` | — | Column visibility + filter panel |
126
- | `layoutMode` | `'fill' \| 'content'` | `'fill'` | `'fill'` fills the container; `'content'` sizes to data |
127
- | `pinnedColumns` | `Record<string, 'left' \| 'right'>` | — | Pin columns to left or right edge |
128
-
129
- ## Listening to events
130
-
131
- Use `.on()` to subscribe to grid events:
132
-
133
- ```js
134
- grid.on('cellValueChanged', ({ item, columnId, oldValue, newValue }) => {
135
- console.log(`${columnId} changed: ${oldValue} → ${newValue}`);
136
- // save to backend
137
- });
138
-
139
- grid.on('selectionChange', ({ selectedItems, selectedRowIds }) => {
140
- console.log(`${selectedItems.length} rows selected`);
141
- updateActionBar(selectedItems, selectedRowIds);
142
- });
143
-
144
- grid.on('sortChange', ({ sort }) => {
145
- if (!sort) return;
146
- console.log(`Sorted by ${sort.field} ${sort.direction}`);
147
- });
148
- ```
149
-
150
- | Event | Payload | When it fires |
151
- |-------|---------|---------------|
152
- | `cellValueChanged` | `{ item, columnId, oldValue, newValue }` | A cell edit is committed |
153
- | `sortChange` | `{ sort }` | User changes sort |
154
- | `filterChange` | `{ filters }` | User changes filters |
155
- | `pageChange` | `{ page }` | User navigates pages |
156
- | `selectionChange` | `{ selectedItems, selectedRowIds }` | Row selection changes |
157
-
158
- ## Programmatic control
159
-
160
- The grid API lives on `grid.api`:
161
-
162
- ```js
163
- // Swap in new data (re-renders efficiently)
164
- grid.api.setRowData(freshData);
165
-
166
- // Export what's currently displayed (respects active filters/sort)
167
- grid.api.exportToCsv('orders.csv');
168
-
169
- // Set sort programmatically
170
- grid.api.setSort('amount', 'desc');
171
-
172
- // Get current column state (widths, visibility, order)
173
- const state = grid.api.getColumnState();
174
- ```
175
-
176
- See the full [JS API Reference](../api/js-api) for all available methods.
177
-
178
- ## Theming
179
-
180
- The default theme uses CSS custom properties. Override any of them to match your design system:
181
-
182
- ```css
183
- :root {
184
- --ogrid-primary: #0066cc; /* buttons, active page */
185
- --ogrid-selection: #0078d4; /* active cell outline */
186
- --ogrid-bg: #ffffff; /* background */
187
- --ogrid-fg: #242424; /* text color */
188
- --ogrid-border: #e0e0e0; /* borders */
189
- --ogrid-bg-subtle: #f3f2f1; /* header background */
190
- --ogrid-bg-hover: #f5f5f5; /* row hover */
191
- }
192
- ```
193
-
194
- Dark mode works automatically if you rely on `prefers-color-scheme`, or you can opt into it explicitly:
195
-
196
- ```css
197
- [data-theme='dark'] {
198
- --ogrid-bg: #1a1a24;
199
- --ogrid-fg: #e0e0e0;
200
- --ogrid-border: #333340;
201
- }
202
- ```
203
-
204
- Or skip the built-in theme entirely and write your own CSS targeting `ogrid-*` class names.
205
-
206
- ## Cleanup
207
-
208
- When your grid is no longer needed (navigating away, SPA route change, etc.), call `destroy()` to remove all DOM elements and event listeners:
209
-
210
- ```js
211
- grid.destroy();
212
- ```
213
-
214
- ## What's next?
215
-
216
- - [JS API Reference](../api/js-api) — full method and options reference
217
- - [Features](../features/sorting) — feature guides, with JS notes where behavior differs from framework packages
218
- - [Theming Guide](../guides/theming) — deep dive into CSS customization