@alaarab/ogrid-mcp 2.5.8 → 2.6.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.
- package/bundled-docs/api/components-column-chooser.mdx +1 -1
- package/bundled-docs/api/components-column-header-filter.mdx +1 -1
- package/bundled-docs/api/components-datagrid-table.mdx +1 -1
- package/bundled-docs/api/components-pagination-controls.mdx +1 -1
- package/bundled-docs/api/components-sidebar.mdx +1 -1
- package/bundled-docs/api/components-status-bar.mdx +1 -1
- package/bundled-docs/features/cell-references.mdx +9 -9
- package/bundled-docs/features/column-chooser.mdx +1 -4
- package/bundled-docs/features/column-groups.mdx +3 -10
- package/bundled-docs/features/column-pinning.mdx +3 -7
- package/bundled-docs/features/column-reordering.mdx +4 -6
- package/bundled-docs/features/column-types.mdx +1 -1
- package/bundled-docs/features/context-menu.mdx +4 -8
- package/bundled-docs/features/csv-export.mdx +7 -7
- package/bundled-docs/features/editing.mdx +21 -21
- package/bundled-docs/features/filtering.mdx +15 -15
- package/bundled-docs/features/formulas.mdx +27 -27
- package/bundled-docs/features/grid-api.mdx +2 -2
- package/bundled-docs/features/keyboard-navigation.mdx +5 -5
- package/bundled-docs/features/pagination.mdx +1 -1
- package/bundled-docs/features/row-grouping.mdx +313 -0
- package/bundled-docs/getting-started/overview.mdx +3 -6
- package/bundled-docs/getting-started/quick-start.mdx +11 -11
- package/bundled-docs/getting-started/vanilla-js.mdx +16 -16
- package/bundled-docs/guides/accessibility.mdx +11 -11
- package/bundled-docs/guides/framework-showcase.mdx +16 -16
- package/bundled-docs/guides/mcp.mdx +9 -9
- package/package.json +1 -1
|
@@ -226,7 +226,7 @@ The trigger button shows the current visibility count: `"Column Visibility (3 of
|
|
|
226
226
|
|
|
227
227
|
## Accessibility
|
|
228
228
|
|
|
229
|
-
`ColumnChooser`
|
|
229
|
+
`ColumnChooser` meets WCAG 2.1 AA with full keyboard and screen reader support.
|
|
230
230
|
|
|
231
231
|
### ARIA Attributes
|
|
232
232
|
|
|
@@ -258,7 +258,7 @@ const handleFilterChange = (values: string[]) => {
|
|
|
258
258
|
|
|
259
259
|
## Accessibility
|
|
260
260
|
|
|
261
|
-
`ColumnHeaderFilter`
|
|
261
|
+
`ColumnHeaderFilter` meets WCAG 2.1 AA with full keyboard and screen reader support.
|
|
262
262
|
|
|
263
263
|
### ARIA Attributes
|
|
264
264
|
|
|
@@ -183,7 +183,7 @@ In Vue Radix, `DataGridTable` uses individual props via `defineProps<IOGridProps
|
|
|
183
183
|
|
|
184
184
|
## Accessibility
|
|
185
185
|
|
|
186
|
-
`DataGridTable`
|
|
186
|
+
`DataGridTable` meets WCAG 2.1 AA with full keyboard navigation and screen reader support.
|
|
187
187
|
|
|
188
188
|
### ARIA Attributes
|
|
189
189
|
|
|
@@ -249,7 +249,7 @@ Showing {startItem} to {endItem} of {totalCount} {entityLabelPlural}
|
|
|
249
249
|
|
|
250
250
|
## Accessibility
|
|
251
251
|
|
|
252
|
-
`PaginationControls`
|
|
252
|
+
`PaginationControls` meets WCAG 2.1 AA with full keyboard and screen reader support.
|
|
253
253
|
|
|
254
254
|
### ARIA Attributes
|
|
255
255
|
|
|
@@ -303,7 +303,7 @@ The panel content area has a fixed width (240px) and scrollable content. The pan
|
|
|
303
303
|
|
|
304
304
|
## Accessibility
|
|
305
305
|
|
|
306
|
-
`SideBar`
|
|
306
|
+
`SideBar` meets WCAG 2.1 AA with full keyboard and screen reader support.
|
|
307
307
|
|
|
308
308
|
### ARIA Attributes
|
|
309
309
|
|
|
@@ -237,7 +237,7 @@ When `statusBar` is `true`, the grid automatically computes the counts from the
|
|
|
237
237
|
|
|
238
238
|
## Accessibility
|
|
239
239
|
|
|
240
|
-
`StatusBar`
|
|
240
|
+
`StatusBar` meets WCAG 2.1 AA with screen reader support for dynamic content announcements.
|
|
241
241
|
|
|
242
242
|
### ARIA Attributes
|
|
243
243
|
|
|
@@ -171,13 +171,13 @@ const grid = new OGrid(document.getElementById('grid'), {
|
|
|
171
171
|
</TabItem>
|
|
172
172
|
</Tabs>
|
|
173
173
|
|
|
174
|
-
## How
|
|
174
|
+
## How it works
|
|
175
175
|
|
|
176
|
-
|
|
176
|
+
`cellReferences` turns on three things at once:
|
|
177
177
|
|
|
178
|
-
### 1. Column
|
|
178
|
+
### 1. Column letter headers
|
|
179
179
|
|
|
180
|
-
A row of Excel-style column letters (A, B, C, ..., Z, AA, AB, ...) appears above the normal header row.
|
|
180
|
+
A row of Excel-style column letters (A, B, C, ..., Z, AA, AB, ...) appears above the normal header row. They use base-26 encoding:
|
|
181
181
|
|
|
182
182
|
| Columns | Letters |
|
|
183
183
|
|---------|---------|
|
|
@@ -186,9 +186,9 @@ A row of Excel-style column letters (A, B, C, ..., Z, AA, AB, ...) appears above
|
|
|
186
186
|
| 53--78 | BA--BZ |
|
|
187
187
|
| 703+ | AAA, AAB, ... |
|
|
188
188
|
|
|
189
|
-
### 2. Row
|
|
189
|
+
### 2. Row numbers
|
|
190
190
|
|
|
191
|
-
A numbered gutter column
|
|
191
|
+
A numbered gutter column on the left shows the absolute row number (1, 2, 3, ...). Numbers are consistent across pages -- page 2 with a page size of 25 starts at row 26, not row 1.
|
|
192
192
|
|
|
193
193
|
:::info Row numbers without cell references
|
|
194
194
|
You can show row numbers independently without the full cell references feature by using the `showRowNumbers` prop:
|
|
@@ -205,11 +205,11 @@ You can show row numbers independently without the full cell references feature
|
|
|
205
205
|
This gives you the numbered gutter column without column letters or the name box.
|
|
206
206
|
:::
|
|
207
207
|
|
|
208
|
-
### 3. Name
|
|
208
|
+
### 3. Name box
|
|
209
209
|
|
|
210
|
-
A
|
|
210
|
+
A read-only field in the toolbar shows the active cell reference (e.g. "A1", "C15"). It updates on click or keyboard navigation.
|
|
211
211
|
|
|
212
|
-
The name box uses the
|
|
212
|
+
The name box uses the absolute row number, so clicking the third column on row 5 of page 2 (page size 10) shows "C15", not "C5".
|
|
213
213
|
|
|
214
214
|
## Props
|
|
215
215
|
|
|
@@ -201,10 +201,7 @@ const grid = new OGrid(document.getElementById('grid'), {
|
|
|
201
201
|
</TabItem>
|
|
202
202
|
</Tabs>
|
|
203
203
|
|
|
204
|
-
|
|
205
|
-
- **Name** is always visible (cannot be unchecked because `required: true`).
|
|
206
|
-
- **Age** and **Start Date** are hidden by default but the user can enable them.
|
|
207
|
-
- **Email**, **Department**, and **Salary** are visible by default and can be toggled.
|
|
204
|
+
Name is always visible (`required: true` locks its checkbox). Age and Start Date are hidden by default but users can show them. Email, Department, and Salary are visible by default and can be toggled.
|
|
208
205
|
|
|
209
206
|
## How It Works
|
|
210
207
|
|
|
@@ -217,9 +217,9 @@ const grid = new OGrid(document.getElementById('grid'), {
|
|
|
217
217
|
|
|
218
218
|
This renders a two-row header: the first row shows "Personal Info" spanning three columns and "Employment" spanning three columns, with the individual column names in the second row.
|
|
219
219
|
|
|
220
|
-
## How
|
|
220
|
+
## How it works
|
|
221
221
|
|
|
222
|
-
Column groups use the `IColumnGroupDef<T>` type. A group has a `headerName`
|
|
222
|
+
Column groups use the `IColumnGroupDef<T>` type. A group has a `headerName` and a `children` array that can contain `IColumnDef` items or nested `IColumnGroupDef` items.
|
|
223
223
|
|
|
224
224
|
```tsx
|
|
225
225
|
// IColumnGroupDef<T>
|
|
@@ -267,14 +267,7 @@ Standalone `IColumnDef` items at the top level are valid alongside groups. They
|
|
|
267
267
|
|
|
268
268
|
## Group Header Behavior
|
|
269
269
|
|
|
270
|
-
Group headers are display-only
|
|
271
|
-
|
|
272
|
-
- **Not sortable.** Clicking a group header does nothing.
|
|
273
|
-
- **Not filterable.** No filter icon or popover appears on group headers.
|
|
274
|
-
- **Not resizable.** Group headers cannot be dragged to resize.
|
|
275
|
-
- **Centered text.** Group header labels are centered over their children by default.
|
|
276
|
-
|
|
277
|
-
Sorting, filtering, and resizing remain available on the leaf column headers beneath the groups.
|
|
270
|
+
Group headers are display-only. Clicking them does nothing -- no sort, no filter icon, no resize handle. Labels are centered over their children by default. Sorting, filtering, and resizing all work normally on the leaf column headers below.
|
|
278
271
|
|
|
279
272
|
## Props Reference
|
|
280
273
|
|
|
@@ -182,19 +182,15 @@ const grid = new OGrid(document.getElementById('grid'), {
|
|
|
182
182
|
|
|
183
183
|
The "Name" column stays fixed on the left while all other columns scroll normally.
|
|
184
184
|
|
|
185
|
-
## How
|
|
185
|
+
## How it works
|
|
186
186
|
|
|
187
|
-
Set `pinned: 'left'` on any `IColumnDef
|
|
187
|
+
Set `pinned: 'left'` on any `IColumnDef`. The grid uses CSS `position: sticky` with a calculated `left` offset so multiple pinned columns stack correctly.
|
|
188
188
|
|
|
189
189
|
```tsx
|
|
190
190
|
{ columnId: 'name', name: 'Name', pinned: 'left' }
|
|
191
191
|
```
|
|
192
192
|
|
|
193
|
-
Pinned columns:
|
|
194
|
-
|
|
195
|
-
- Use **sticky positioning** so they stay visible during horizontal scroll.
|
|
196
|
-
- Stack left-to-right in the order they appear in the `columns` array.
|
|
197
|
-
- Work with all grid features: sorting, filtering, editing, cell selection, and context menu.
|
|
193
|
+
Pinned columns use sticky positioning, stack in the order they appear in the `columns` array, and work with all features: sorting, filtering, editing, cell selection, and context menu.
|
|
198
194
|
|
|
199
195
|
### With Row Selection
|
|
200
196
|
|
|
@@ -170,9 +170,9 @@ const grid = new OGrid(document.getElementById('grid'), {
|
|
|
170
170
|
|
|
171
171
|
Drag any column header to rearrange it. A vertical indicator line shows where the column will be placed.
|
|
172
172
|
|
|
173
|
-
## How
|
|
173
|
+
## How it works
|
|
174
174
|
|
|
175
|
-
Set `columnReorder` to `true
|
|
175
|
+
Set `columnReorder` to `true`. When a user drags a column header at least 5 pixels horizontally, the grid enters reorder mode:
|
|
176
176
|
|
|
177
177
|
1. A vertical drop indicator appears between columns as the user drags.
|
|
178
178
|
2. On mouse-up, the column is moved to the target position.
|
|
@@ -300,11 +300,9 @@ const columns = [
|
|
|
300
300
|
|
|
301
301
|
In this example, "ID" and "Name" can be swapped with each other but cannot be dragged into the unpinned section. The unpinned columns ("Email", "Department", "Salary") can be freely rearranged among themselves.
|
|
302
302
|
|
|
303
|
-
### Edge
|
|
303
|
+
### Edge cases
|
|
304
304
|
|
|
305
|
-
|
|
306
|
-
- **Resize handle zone:** The rightmost 8 pixels of each header cell are reserved for column resizing. Dragging in that zone starts a resize, not a reorder.
|
|
307
|
-
- **Minimum drag distance:** A 5-pixel horizontal threshold prevents accidental reorders from clicks.
|
|
305
|
+
Group headers are not draggable -- only leaf columns with a `columnId` can be reordered. The rightmost 8 pixels of each header cell are reserved for column resizing, so dragging there starts a resize instead. The 5-pixel horizontal threshold prevents accidental reorders from ordinary clicks.
|
|
308
306
|
|
|
309
307
|
## Grid API
|
|
310
308
|
|
|
@@ -150,9 +150,9 @@ const grid = new OGrid(document.getElementById('grid'), {
|
|
|
150
150
|
|
|
151
151
|
Right-click a cell to see the context menu with all available actions.
|
|
152
152
|
|
|
153
|
-
## How
|
|
153
|
+
## How it works
|
|
154
154
|
|
|
155
|
-
The context menu is built in
|
|
155
|
+
The context menu is built in. It appears on data cell right-clicks -- no configuration needed.
|
|
156
156
|
|
|
157
157
|
### Built-in Menu Items
|
|
158
158
|
|
|
@@ -187,13 +187,9 @@ The Undo and Redo items reflect their availability through the `canUndo` and `ca
|
|
|
187
187
|
|
|
188
188
|
If `onUndo` and `onRedo` are not provided, the undo/redo items still appear but do nothing.
|
|
189
189
|
|
|
190
|
-
### Cell-
|
|
190
|
+
### Cell-only activation
|
|
191
191
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
- **Header right-click**: default browser context menu (no grid menu).
|
|
195
|
-
- **Empty space right-click**: default browser context menu.
|
|
196
|
-
- **Cell right-click**: grid context menu with actions scoped to the current selection.
|
|
192
|
+
Right-clicking a header or empty space shows the browser's default context menu. The grid menu only appears on data cell right-clicks, with actions scoped to the current selection.
|
|
197
193
|
|
|
198
194
|
### Copy/Cut Disabled State
|
|
199
195
|
|
|
@@ -156,9 +156,9 @@ document.getElementById('export-btn').addEventListener('click', () => {
|
|
|
156
156
|
</TabItem>
|
|
157
157
|
</Tabs>
|
|
158
158
|
|
|
159
|
-
## How
|
|
159
|
+
## How it works
|
|
160
160
|
|
|
161
|
-
### The `exportToCsv`
|
|
161
|
+
### The `exportToCsv` function
|
|
162
162
|
|
|
163
163
|
```tsx
|
|
164
164
|
exportToCsv<T>(
|
|
@@ -182,11 +182,11 @@ The function:
|
|
|
182
182
|
3. Escapes values containing commas, quotes, or newlines.
|
|
183
183
|
4. Triggers a browser download with the specified filename.
|
|
184
184
|
|
|
185
|
-
### Context
|
|
185
|
+
### Context menu
|
|
186
186
|
|
|
187
|
-
|
|
187
|
+
The context menu doesn't include an "Export to CSV" item. Use `exportToCsv` from a toolbar button or any other UI you control.
|
|
188
188
|
|
|
189
|
-
### Exporting
|
|
189
|
+
### Exporting visible columns only
|
|
190
190
|
|
|
191
191
|
Filter the columns array to only include visible columns before passing to `exportToCsv`.
|
|
192
192
|
|
|
@@ -201,9 +201,9 @@ exportToCsv(
|
|
|
201
201
|
);
|
|
202
202
|
```
|
|
203
203
|
|
|
204
|
-
###
|
|
204
|
+
### Matching display formatting
|
|
205
205
|
|
|
206
|
-
|
|
206
|
+
Apply `valueFormatter` in your `getValue` so the export matches what users see -- a currency column showing "$1,234.56" will export that same string.
|
|
207
207
|
|
|
208
208
|
```tsx
|
|
209
209
|
const getValue = (item: Row, columnId: string) => {
|
|
@@ -7,17 +7,17 @@ description: Inline editing, clipboard operations, fill handle, and undo/redo
|
|
|
7
7
|
|
|
8
8
|
# Editing & Clipboard
|
|
9
9
|
|
|
10
|
-
Double-click a cell to edit it.
|
|
10
|
+
Double-click a cell to edit it. Enter saves, Escape cancels. Clipboard paste, drag-to-fill, and full undo/redo are all included.
|
|
11
11
|
|
|
12
12
|
<CellEditingDemo />
|
|
13
13
|
|
|
14
14
|
:::tip Try it in your framework
|
|
15
|
-
The demo above uses Radix UI for styling. Each framework renders editors with its native components
|
|
15
|
+
The demo above uses Radix UI for styling. Each framework renders editors with its native components: dropdowns, date pickers, and inputs that match your design system.
|
|
16
16
|
:::
|
|
17
17
|
|
|
18
18
|
## Get started in 5 minutes
|
|
19
19
|
|
|
20
|
-
Here's a realistic setup: an employee table with text, dropdown, and numeric columns
|
|
20
|
+
Here's a realistic setup: an employee table with text, dropdown, and numeric columns, including validation that rejects bad salary values before they're saved.
|
|
21
21
|
|
|
22
22
|
<Tabs groupId="framework">
|
|
23
23
|
<TabItem value="react" label="React" default>
|
|
@@ -79,7 +79,7 @@ function App() {
|
|
|
79
79
|
```
|
|
80
80
|
|
|
81
81
|
:::tip Switching UI libraries
|
|
82
|
-
Same props across all React packages
|
|
82
|
+
Same props across all React packages -- just change the import:
|
|
83
83
|
|
|
84
84
|
- **Radix** (lightweight, default): `from '@alaarab/ogrid-react-radix'`
|
|
85
85
|
- **Fluent UI** (Microsoft 365 / SPFx): `from '@alaarab/ogrid-react-fluent'` - wrap in `<FluentProvider>`
|
|
@@ -134,7 +134,7 @@ Same component API across Angular packages. Change the import:
|
|
|
134
134
|
- **Angular Material**: `from '@alaarab/ogrid-angular-material'`
|
|
135
135
|
- **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
|
|
136
136
|
|
|
137
|
-
All components are standalone
|
|
137
|
+
All components are standalone, no NgModule required.
|
|
138
138
|
:::
|
|
139
139
|
|
|
140
140
|
</TabItem>
|
|
@@ -243,18 +243,18 @@ That single setup gives you inline editing, clipboard paste, fill handle, and fu
|
|
|
243
243
|
|
|
244
244
|
Double-click or press **F2** to open the editor. When you're done:
|
|
245
245
|
|
|
246
|
-
- **Enter**
|
|
247
|
-
- **Tab**
|
|
248
|
-
- **Escape**
|
|
246
|
+
- **Enter** -- saves and moves focus down
|
|
247
|
+
- **Tab** -- saves and moves focus right
|
|
248
|
+
- **Escape** -- cancels, restores the original value
|
|
249
249
|
|
|
250
250
|
### Which editor should I use?
|
|
251
251
|
|
|
252
252
|
| `cellEditor` | When to use it |
|
|
253
253
|
|--------------|----------------|
|
|
254
|
-
| `'text'` (default) | Freeform text
|
|
254
|
+
| `'text'` (default) | Freeform text -- names, notes, anything open-ended |
|
|
255
255
|
| `'select'` | Small, fixed list where the user picks exactly one value |
|
|
256
|
-
| `'richSelect'` | Longer list with keyboard search
|
|
257
|
-
| `'checkbox'` | Boolean toggle
|
|
256
|
+
| `'richSelect'` | Longer list with keyboard search -- much nicer UX than a plain dropdown |
|
|
257
|
+
| `'checkbox'` | Boolean toggle -- renders as a checkbox, commits on click |
|
|
258
258
|
|
|
259
259
|
### Searchable dropdown (richSelect)
|
|
260
260
|
|
|
@@ -280,7 +280,7 @@ Use a function for `editable` to make it conditional:
|
|
|
280
280
|
{ columnId: 'name', editable: (item) => item.status !== 'locked' }
|
|
281
281
|
```
|
|
282
282
|
|
|
283
|
-
The cell still renders normally
|
|
283
|
+
The cell still renders normally. It just won't open an editor when you click it.
|
|
284
284
|
|
|
285
285
|
### Custom editor (popup)
|
|
286
286
|
|
|
@@ -308,7 +308,7 @@ function DateEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorPro
|
|
|
308
308
|
|
|
309
309
|
### Validating input with `valueParser`
|
|
310
310
|
|
|
311
|
-
`valueParser` runs on every edit, paste, fill, and delete. Return `undefined` to silently reject the value
|
|
311
|
+
`valueParser` runs on every edit, paste, fill, and delete. Return `undefined` to silently reject the value. The cell snaps back to its previous state:
|
|
312
312
|
|
|
313
313
|
```tsx
|
|
314
314
|
{
|
|
@@ -323,14 +323,14 @@ function DateEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorPro
|
|
|
323
323
|
```
|
|
324
324
|
|
|
325
325
|
:::tip Pro tip
|
|
326
|
-
`valueParser` is your single
|
|
326
|
+
`valueParser` is your single validation point -- it covers inline edits, clipboard paste, fill handle, and delete. You don't need separate logic for each.
|
|
327
327
|
:::
|
|
328
328
|
|
|
329
329
|
## Clipboard
|
|
330
330
|
|
|
331
331
|
<ClipboardDemo />
|
|
332
332
|
|
|
333
|
-
Standard shortcuts work on any selection
|
|
333
|
+
Standard shortcuts work on any selection with no configuration:
|
|
334
334
|
|
|
335
335
|
| Key | Action | Requires `editable` |
|
|
336
336
|
|-----|--------|-------------------|
|
|
@@ -339,13 +339,13 @@ Standard shortcuts work on any selection — no configuration needed:
|
|
|
339
339
|
| Ctrl+X / Cmd+X | Cut (copy then clear) | Yes |
|
|
340
340
|
| Delete / Backspace | Clear selected cells | Yes |
|
|
341
341
|
|
|
342
|
-
Copy respects `valueFormatter
|
|
342
|
+
Copy respects `valueFormatter`, so what you see is what ends up in the clipboard. Paste calls `valueParser` on each value, so bad data is rejected before it lands in your rows.
|
|
343
343
|
|
|
344
344
|
## Fill handle
|
|
345
345
|
|
|
346
346
|
<FillHandleDemo />
|
|
347
347
|
|
|
348
|
-
The small square in the bottom-right corner of a selection
|
|
348
|
+
The small square in the bottom-right corner of a selection. Drag it down to fill cells, just like Excel. Each filled cell goes through `valueParser`, so validation still applies.
|
|
349
349
|
|
|
350
350
|
:::tip Pro tip
|
|
351
351
|
Select a range of cells before dragging the fill handle to populate multiple columns at once. The fill handle uses `requestAnimationFrame` internally, so it stays smooth even on large selections.
|
|
@@ -363,7 +363,7 @@ const { handleCellValueChanged, undo, redo, canUndo, canRedo } = useUndoRedo({
|
|
|
363
363
|
});
|
|
364
364
|
```
|
|
365
365
|
|
|
366
|
-
Pass `handleCellValueChanged` as `onCellValueChanged
|
|
366
|
+
Pass `handleCellValueChanged` as `onCellValueChanged`. It intercepts changes and pushes them onto the undo stack before updating your state. Undo/redo are also available in the right-click [context menu](./context-menu).
|
|
367
367
|
|
|
368
368
|
## Props reference
|
|
369
369
|
|
|
@@ -382,6 +382,6 @@ Pass `handleCellValueChanged` as `onCellValueChanged` — it intercepts changes
|
|
|
382
382
|
|
|
383
383
|
## Next steps
|
|
384
384
|
|
|
385
|
-
- [Spreadsheet Selection](./spreadsheet-selection)
|
|
386
|
-
- [Context Menu](./context-menu)
|
|
387
|
-
- [Formulas](./formulas)
|
|
385
|
+
- [Spreadsheet Selection](./spreadsheet-selection) -- select ranges before editing or pasting
|
|
386
|
+
- [Context Menu](./context-menu) -- right-click to undo, copy, and more
|
|
387
|
+
- [Formulas](./formulas) -- formula-aware editing with `=SUM(A1:A5)` syntax
|
|
@@ -7,12 +7,12 @@ description: Column-level filtering with text, multi-select, date, and people fi
|
|
|
7
7
|
|
|
8
8
|
# Filtering
|
|
9
9
|
|
|
10
|
-
You have 3,000 support tickets and need to find the ones assigned to Alice that were opened last week. Click the filter icon on "Assignee", pick Alice. Click the filter on "Created Date", set the range.
|
|
10
|
+
You have 3,000 support tickets and need to find the ones assigned to Alice that were opened last week. Click the filter icon on "Assignee", pick Alice. Click the filter on "Created Date", set the range. Two clicks, no code.
|
|
11
11
|
|
|
12
12
|
<FilteringDemo />
|
|
13
13
|
|
|
14
14
|
:::tip Framework-Specific Styling
|
|
15
|
-
The demo uses React Radix styling. Each framework renders filter UI with its native components
|
|
15
|
+
The demo uses React Radix styling. Each framework renders filter UI with its native components: dropdowns, date pickers, and inputs that match your design system.
|
|
16
16
|
:::
|
|
17
17
|
|
|
18
18
|
## Add filters to any column
|
|
@@ -61,7 +61,7 @@ function App() {
|
|
|
61
61
|
```
|
|
62
62
|
|
|
63
63
|
:::tip Switching UI libraries
|
|
64
|
-
Same props across all React packages
|
|
64
|
+
Same props across all React packages -- just change the import:
|
|
65
65
|
|
|
66
66
|
- **Radix** (lightweight, default): `from '@alaarab/ogrid-react-radix'`
|
|
67
67
|
- **Fluent UI** (Microsoft 365 / SPFx): `from '@alaarab/ogrid-react-fluent'` - wrap in `<FluentProvider>`
|
|
@@ -109,7 +109,7 @@ Same API across Angular packages. Change the import:
|
|
|
109
109
|
- **Angular Material**: `from '@alaarab/ogrid-angular-material'`
|
|
110
110
|
- **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
|
|
111
111
|
|
|
112
|
-
All components are standalone
|
|
112
|
+
All components are standalone, no NgModule required.
|
|
113
113
|
:::
|
|
114
114
|
|
|
115
115
|
</TabItem>
|
|
@@ -203,7 +203,7 @@ Type "john" and it matches "John Smith", "Johnny", and "Johnathan".
|
|
|
203
203
|
|
|
204
204
|
### Multi-select filter
|
|
205
205
|
|
|
206
|
-
A checkbox list
|
|
206
|
+
A checkbox list. Users pick one or more values and the grid shows only matching rows. Has built-in "Select All" and "Clear All" buttons.
|
|
207
207
|
|
|
208
208
|
```tsx
|
|
209
209
|
{
|
|
@@ -223,8 +223,8 @@ A checkbox list — users pick one or more values, the grid shows only matching
|
|
|
223
223
|
| `optionsSource` | How it works |
|
|
224
224
|
|-----------------|----------|
|
|
225
225
|
| _(omitted)_ | Client-side: unique values extracted from your data. Server-side: calls your API. |
|
|
226
|
-
| `'static'` | Uses the `options` array you provide
|
|
227
|
-
| `'api'` | Calls `dataSource.fetchFilterOptions(field)`
|
|
226
|
+
| `'static'` | Uses the `options` array you provide -- great for known enums. |
|
|
227
|
+
| `'api'` | Calls `dataSource.fetchFilterOptions(field)` -- for dynamic option lists. |
|
|
228
228
|
| `'years'` | Auto-generates a year list from the current year down. |
|
|
229
229
|
|
|
230
230
|
### Date filter
|
|
@@ -241,7 +241,7 @@ A date range picker with "From" and "To" inputs. Shows only rows where the colum
|
|
|
241
241
|
```
|
|
242
242
|
|
|
243
243
|
:::tip
|
|
244
|
-
A column with `type: 'date'` automatically gets date formatting, chronological sorting, and a native date input editor
|
|
244
|
+
A column with `type: 'date'` automatically gets date formatting, chronological sorting, and a native date input editor. You don't need to configure those separately.
|
|
245
245
|
:::
|
|
246
246
|
|
|
247
247
|
### People filter
|
|
@@ -262,7 +262,7 @@ The people filter requires a `dataSource` with a `searchPeople` method that retu
|
|
|
262
262
|
|
|
263
263
|
## Keeping filter state outside the grid
|
|
264
264
|
|
|
265
|
-
By default the grid owns its filter state
|
|
265
|
+
By default the grid owns its filter state, and filters reset when the component unmounts. To persist them (URL sync, page reload survival), pass `filters` and `onFiltersChange`:
|
|
266
266
|
|
|
267
267
|
```tsx
|
|
268
268
|
function App() {
|
|
@@ -283,11 +283,11 @@ function App() {
|
|
|
283
283
|
}
|
|
284
284
|
```
|
|
285
285
|
|
|
286
|
-
Now you can serialize `filters` to the URL, localStorage, or a server
|
|
286
|
+
Now you can serialize `filters` to the URL, localStorage, or a server. The grid will restore the exact filter state when the user comes back.
|
|
287
287
|
|
|
288
288
|
## Server-side filtering
|
|
289
289
|
|
|
290
|
-
When you're using a `dataSource`, the grid
|
|
290
|
+
When you're using a `dataSource`, the grid passes filter values to your `fetchPage()` function. You decide what to do with them -- query params, request body, whatever your API expects:
|
|
291
291
|
|
|
292
292
|
```tsx
|
|
293
293
|
const dataSource: IDataSource<Task> = {
|
|
@@ -323,7 +323,7 @@ const dataSource: IDataSource<Task> = {
|
|
|
323
323
|
```
|
|
324
324
|
|
|
325
325
|
:::tip Pro tip
|
|
326
|
-
Server-side filtering pairs naturally with [pagination](./pagination). The `totalCount` in your `fetchPage` response tells the grid how many pages
|
|
326
|
+
Server-side filtering pairs naturally with [pagination](./pagination). The `totalCount` in your `fetchPage` response tells the grid how many pages exist, so pagination stays accurate even when filters narrow the result set.
|
|
327
327
|
:::
|
|
328
328
|
|
|
329
329
|
## Props reference
|
|
@@ -341,6 +341,6 @@ Server-side filtering pairs naturally with [pagination](./pagination). The `tota
|
|
|
341
341
|
|
|
342
342
|
## Next steps
|
|
343
343
|
|
|
344
|
-
- [Sorting](./sorting)
|
|
345
|
-
- [Pagination](./pagination)
|
|
346
|
-
- [Server-Side Data](./server-side-data)
|
|
344
|
+
- [Sorting](./sorting) -- sort filtered results by any column
|
|
345
|
+
- [Pagination](./pagination) -- paginate filtered results server-side or client-side
|
|
346
|
+
- [Server-Side Data](./server-side-data) -- move all filtering, sorting, and paging to the server
|