@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.0

package/skills/editing/references/editing-api.md

@@ -9,7 +9,7 @@ kind.
 | --- | --- | --- | --- |
 | `editing` | `TMDataGridEditingOptions` | off | The editing namespace. Setting it turns editing on. |
 | `editing.mode` | `"cell" \| "cellConfirm" \| "row"` | – | What counts as a commit, and which controls trigger it. |
-| `editing.draft` | `boolean` | `false` | Where a commit goes. On, it parks in the grid's draft store until `edit.saveDrafts()`. |
+| `editing.draft` | `boolean` | `false` | Where a commit goes. On, it is held in the grid's draft store until `edit.saveDrafts()`. |
 | `getRowId` | `(row) => string` | – | A TanStack table option, required once `editing` is set. Drafts are keyed by it. |
 | `editing.columns` | `ReadonlyArray<string>` | every column mapping to a data path | The column ids that take edits. Gates before `meta.edit`, never past it: a column left out takes no edits whatever its meta says, and a listed column still answers to its `meta.edit.enabled`. Also decides which cells an entry row opens. |
 | `editing.isRowEditable` | `(row) => boolean` | – | Closes a whole row to editing, in every mode. |
@@ -28,8 +28,7 @@ the type.
 | Name | Argument | What it does |
 | --- | --- | --- |
 | `editing.onCommit` | `{ rowId, value, original, changes, source }` | Applies one row's change. Reject to keep the draft and show the error. |
-| `editing.onSaveDrafts` | `{ updated, created, deleted }` | `draft: true` only. One call for the whole draft store. Without it, `saveDrafts` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
-| `editing.onCommitDrafts` | `{ updated, created, deleted }` | **Deprecated** - renamed to `onSaveDrafts`. Still honoured; the new name wins if both are set. |
+| `editing.onSaveDrafts` | `{ updated, created, deleted }` | `draft: true` only. One call for the whole draft store. May return a `TMDataGridSaveDraftsResponse` naming the ids that failed; they stay in the draft store. Without it, `saveDrafts` loops `editing.onCommit`, `editing.onRowAdd` and `editing.onRowDelete`. |
 | `editing.onRowAdd` | `{ tempId, value }` | Commits an entry row. Mint the real id here. |
 | `editing.onRowDelete` | `{ rowId, row }` | Deletes a row. Shows the trash; under `draft: true`, `onSaveDrafts` shows it too. |
 
@@ -54,24 +53,25 @@ path, which may be dotted.
 | Member | Signature | Notes |
 | --- | --- | --- |
 | `begin` | `({ rowId, columnId }) => void` | Row mode opens the entire row either way. `columnId` selects which cell takes the caret; `null` (the pencil) uses its first editable one. On a committed row it reopens it, taking it back out of the draft store. |
-| `commit` | `(rowId) => Promise<boolean>` | The OK gesture: submits the row's form. `false` keeps it open with its errors, and the message outlives the editor that found it. Under `draft: true` a pass parks the row - no consumer callback runs until `saveDrafts`. Column rules run whether or not an editor is mounted. |
-| `commitAll` | `() => Promise<boolean>` | Submits every open row. Rows that fail stay open. `false` when one did. |
-| `saveDrafts` | `() => Promise<boolean>` | Sends the draft store. Open rows are left alone and stay open. |
+| `commit` | `(rowId) => Promise<boolean>` | The OK gesture: submits the row's form. `false` keeps it open with its errors, and the message outlives the editor that found it. Under `draft: true` a pass commits the row into the draft store - no consumer callback runs until `saveDrafts`. Column rules run whether or not an editor is mounted. |
+| `commitAll` | `() => Promise<TMDataGridCommitAllResult>` | Submits every open row. Rows that fail stay open. Resolves `{ ok, committed, open }`: every row open at the call is in exactly one list, and `ok` is `false` when one stayed open. |
+| `saveDrafts` | `() => Promise<TMDataGridSaveDraftsResult>` | Sends the draft store, re-running `editing.tableValidators` only; a committed row that fails is reopened with its errors. Open rows are left alone and stay open. Resolves `{ ok, saved, kept, reopened }` over row ids and temp ids, all kinds mixed: `saved` left the draft store, `kept` is still in it for the next save (reported failed by `onSaveDrafts`, sent when it threw, or a deletion whose per-row `onRowDelete` threw), `reopened` is open again with an error (a table rule, or a throwing per-row `onCommit` / `onRowAdd`). `ok` is `false` when anything was kept or reopened. A call during a save joins it and resolves the same result. |
 | `cancel` | `(rowId) => void` | Drops one draft. |
 | `cancelAll` | `() => void` | Drops every draft. |
 | `deactivate` | `() => void` | Closes the editor without touching the draft, as blur does under `"cellConfirm"`. |
-| `submitAll` | `() => Promise<boolean>` | **Deprecated** - `commitAll()` then `saveDrafts()`. |
 | `clearCell` | `(rowId, columnId) => Promise<boolean>` | What Delete does: writes the type's empty value and commits. |
-| `setCellValue` | `(rowId, columnId, value) => Promise<boolean>` | Writes one cell and commits the row, with no editor - toolbar actions and bulk fills. The row need not be mounted; a row inside a collapsed group takes the write. `value` is the stored value, so `meta.edit.mapValue` does not run and `meta.edit.validate` does. Under `draft: true` the row parks like any hand-made edit. `false` when the cell takes no edit, or when validation refused the value and left the row open with its errors. |
+| `setCellValue` | `(rowId, columnId, value) => Promise<boolean>` | Writes one cell and commits the row, with no editor - toolbar actions and bulk fills. The row need not be mounted; a row inside a collapsed group takes the write. `value` is the stored value, so `meta.edit.mapValue` does not run and `meta.edit.validate` does. Under `draft: true` the row is committed into the draft store like any hand-made edit. `false` when the cell takes no edit, or when validation refused the value and left the row open with its errors. |
 | `setRowValues` | `(rowId, values) => Promise<boolean>` | `setCellValue` for several cells of one row in a single commit - one consumer call and one draft entry. Keys are column ids. All or nothing: if any named cell takes no edit, nothing is written and it resolves `false`. |
 | `addRow` | `(values?) => string` | Opens an entry row, returns its `tempId`. `values` overrides `editing.newRowDefaults` key by key for that row; with no argument the row is `newRowDefaults` alone. |
-| `addRows` | `(rows, options?) => Promise<{ committed, open }>` | Opens a batch in one write, each row seeded as `addRow` seeds. `{ commit: true }` submits each as it lands - valid rows commit, invalid ones stay open with their errors. |
-| `deleteRow` | `(rowId) => void` | `editing.onRowDelete`, or a deletion mark under `draft: true`. Toggles: a second call restores the row. |
+| `addRows` | `(rows, options?) => Promise<TMDataGridAddRowsResult>` | Opens a batch in one write, each row seeded as `addRow` seeds. `{ commit: true }` submits each as it lands - valid rows commit, invalid ones stay open with their errors. Resolves `{ ok, committed, open }`; `ok` is `false` when a row stayed open. |
+| `deleteRow` | `(rowId) => void` | `editing.onRowDelete`, or a deletion mark under `draft: true`. Idempotent: a second call leaves the row marked; `restoreRow` is the undo. |
 | `canEditCell` | `(row, column) => boolean` | The check the built-in controls use. Both halves: the column's and the row's. |
 | `canEditRow` | `(row) => boolean` | The pencil's gate. |
 | `isColumnEditable` | `(column) => boolean` | The column's half alone, with no row in hand: it maps to a field, `editing.columns` lists it when that is set, and `meta.edit.enabled` is not `false`. |
 | `canDeleteRows` | `() => boolean` | Whether the delete control should be shown. |
-| `getForm` | `(rowId) => TMDataGridRowEditForm \| undefined` | The row's live `FormApi`. |
+| `getForm` | `(rowId) => TMDataGridRowEditForm \| undefined` | The open row's live `FormApi`; `undefined` for a committed row. |
+| `getRowValues` | `(rowId) => TData \| undefined` | The row as shown: the open form's values, else the committed draft, else the `data` value. `undefined` for an unknown row. |
+| `getRows` | `() => ReadonlyArray<TMDataGridEditRowSnapshot>` | Every row as shown, from the core row model: drafts overlaid, entry rows appended, deletion-marked rows included and flagged `deleted`. |
 | `state` | `TMDataGridEditState` | Snapshot, for reads outside React. |
 | `store` | `Store<TMDataGridEditState>` | For `useSelector`. |
 
@@ -81,10 +81,10 @@ path, which may be dotted.
 type TMDataGridEditState = {
   // The cell the last open gesture named - where the caret goes.
   active: { rowId: string; columnId: string | null } | null;
-  // Rows with a live form, committed or not. A row is *open* when it is in
-  // here and not in `committedRowIds`.
+  // Every row the grid holds work for: open rows and committed rows. A row
+  // is *open* when it is in here and not in `committedRowIds`.
   openRowIds: ReadonlyArray<string>;
-  // One `TMDataGridEditRowProjection` per open row.
+  // One `TMDataGridEditRowProjection` per row in `openRowIds`.
   rows: Record<
     string,
     {
@@ -96,8 +96,8 @@ type TMDataGridEditState = {
       values: TMDataGridRowData;
     }
   >;
-  // The draft store's edit slice: existing rows whose form passed its submit,
-  // parked for `saveDrafts`. Empty without `editing.draft`.
+  // The draft store's edit slice: existing rows that passed their commit,
+  // held as values for `saveDrafts`. Empty without `editing.draft`.
   committedRowIds: ReadonlyArray<string>;
   // What a committed row *is* to the table: the draft store's values per row,
   // snapshotted at each commit and kept across a reopen, so the row holds its
@@ -108,6 +108,8 @@ type TMDataGridEditState = {
   // a commit adds through `onRowAdd`, so it stays `false`.
   newRows: ReadonlyArray<{ tempId: string; committed: boolean }>;
   deletedRowIds: ReadonlyArray<string>;
+  // `true` while `saveDrafts` is in flight.
+  isSaving: boolean;
 };
 ```
 
@@ -119,12 +121,13 @@ type TMDataGridEditState = {
 | `TMDataGridDraftActions` | Export | The same component, for use outside the namespace. |
 | `EDIT_COLUMN_ID` | Export | `"__edit__"`, the generated edit lane's id. |
 | `clearedValueForType` | Export | `(type) => unknown` - what Delete writes per column type. |
+| `hasPendingEdits` | Export | `(state) => boolean` - unsaved work: an open row with a changed value, any entry row, the draft store, or a save in flight. `useSelector(grid.edit.store, hasPendingEdits)` for a navigation blocker; do not use `openRowIds.length`, which also counts committed rows and rows that are only open. |
 | `getEditFieldName` | Export | `(column) => string` - the data path a column's edits write to. |
 | `normalizeFieldValidate` | Export | `(validate) => validators` - a bare schema into Form's shape. |
 | `TMDataGridStringEditor` … `TMDataGridMultiSelectEditor` | Exports | The six built-in editors, for wrapping. |
 
 Types: `TMDataGridEditMode`, `TMDataGridEditApi`, `TMDataGridEditState`,
-`TMDataGridEditCommitArgs`, `TMDataGridEditCommitDraftsArgs`,
+`TMDataGridEditCommitArgs`, `TMDataGridSaveDraftsArgs`,
 `TMDataGridEditChange`, `TMDataGridEditorArgs`, `TMDataGridEditorComponent`,
 `TMDataGridEditField`, `TMDataGridEditRowProjection`, `TMDataGridFieldValidate`,
 `TMDataGridRowValidators`, `TMDataGridRowEditForm`, `TMDataGridRowAddArgs`,
@@ -148,11 +151,11 @@ The trash itself shows when the deletion has somewhere to report to:
 mark is part of the save.
 
 What the lane holds follows the row's state, one axis each. An open row shows
-the mode's own controls, `save-row` and `cancel-row`. A parked row shows
+the mode's own controls, `save-row` and `cancel-row`. A committed row shows
 `row-state` instead, whose `data-state` is `new`, `edited` or `deleted`,
 together with `revert-row` on an edited row, `restore-row` on one marked for
 deletion, and `edit-row` plus `discard-new-row` on an entered new row - never a
-save, which the engine would only park again. A parked row hides `delete-row`.
+save, which the engine would only commit again. A committed row hides `delete-row`.
 Every control carries a tooltip from the labels, `revertRow`, `rowStateNew`,
 `rowStateEdited` and `rowStateDeleted` among them.
 

package/skills/editing/references/editors-and-validation.md

@@ -63,11 +63,11 @@ Bind any control to `field` exactly as inside any TanStack Form:
 `field.state.value`, `field.state.meta.errors`, `field.handleChange`,
 `field.handleBlur`.
 
-Binding `field.state.meta.errors` is what shows a refused commit: the built-in
-editors pass the first error to the input's `error` prop, and an editor that
-binds nothing leaves a blocked save as `data-invalid` on the cell with no
-message on screen. An entry is a string from a function validator, or an issue
-carrying a `message` from a schema.
+The message itself is the host's: it shows in a tooltip on the editor, opened
+by focus and by hover, for a custom editor as much as a built-in one. What an
+editor binds is the invalid state - the built-ins pass a boolean to the input's
+`error` prop for the border alone, and an editor that binds nothing looks
+unchanged while the commit is refused.
 
 ```tsx
 import { Slider } from "@mantine/core";
@@ -193,8 +193,13 @@ meta: { edit: { validate: z.string().min(2, "At least two characters") } }
 // Object form: pick the trigger.
 meta: { edit: { validate: { onBlur: z.string().email("Not an email address") } } }
 
-// A plain function works too.
-meta: { edit: { validate: ({ value }) => (value > 0 ? undefined : "Must be positive") } }
+// A plain function works too. `value` is typed `never`, so annotate the parameter.
+meta: {
+  edit: {
+    validate: ({ value }: { value: unknown }) =>
+      typeof value === "number" && value > 0 ? undefined : "Must be positive",
+  },
+}
 ```
 
 `normalizeFieldValidate(validate)` is exported for consumers building their own
@@ -224,8 +229,8 @@ const grid = useTMDataGrid({
 ```
 
 Issues with a path land on the matching column's cell; pathless issues land on
-the row, where the message shows in the edit lane's tooltip - on the open
-row's ✓, and on the parked row's marker. A nested schema's issues follow the
+the row, where the message shows in the edit lane's tooltip on the open
+row's ✓. A nested schema's issues follow the
 same rule, so a `address.city` issue lands on the column whose `editField` is
 `"address.city"`.
 
@@ -261,9 +266,9 @@ row's cells. `onSubmit` runs first, and its failure stands without
 `onSubmitAsync` running. Errors land on the committing row only.
 
 The rules run at every commit - typed, ✓, `edit.setCellValue`, an entry
-row's - after the row's own validators, and again for every parked row during
-`saveDrafts`: a draft that a later edit invalidated fails there, keeps its
-markers, and the save resolves `false`.
+row's - after the row's own validators, and again for every committed row during
+`saveDrafts`, the only rules that run there: a committed row that a later edit
+invalidated is reopened with its errors, and the save reports it in `reopened`.
 
 ## Server-side errors
 
@@ -283,9 +288,9 @@ rowValidators: {
 },
 ```
 
-A commit blocked by validation keeps the editor open with the message on the
-input. A rejected `editing.onCommit` keeps the draft too, with the error on the
-row.
+A commit blocked by validation keeps the editor open, invalid, with the message
+in its tooltip. A rejected `editing.onCommit` keeps the draft too, with the
+error on the row.
 
 ## Where the state shows
 
@@ -294,11 +299,13 @@ row.
 | The cell's own value | A held draft is displayed: the cell renders the draft value through the column's `cell` renderer, in every mode |
 | Blue cell corner | The field is dirty against its original value |
 | Red cell corner | The field carries a validation error |
-| Row error text | A pathless rule failed, or a commit was rejected. In the lane's tooltip: the open row's ✓, or the parked row's marker |
+| Field error message | In a tooltip on the open editor, shown while the input has focus and on hover |
+| Row error text | A pathless rule failed, or a commit was rejected. In the lane's tooltip, on the open row's ✓ |
 | `data-dirty` on the row | The row holds a dirty draft |
 
 The same information is readable from `edit.store`: `rows[rowId].dirtyFields`,
 `rows[rowId].errorFields`, `rows[rowId].errorMessages` (`{ field, message }`
 pairs), `rows[rowId].hasRowError`, `rows[rowId].isSubmitting`, and
 `rows[rowId].values` for the draft itself. The pathless message's text is not
-in the store; read it from `edit.getForm(rowId)?.state.errors`.
+in the store; read it from `edit.getForm(rowId)?.state.errors` on the open
+row that carries it.

package/skills/filtering/SKILL.md

@@ -3,24 +3,27 @@ name: filtering
 description: >
   Narrow the rows a TMDataGrid shows. Covers the shared tmDataGrid filter
   function and its {operator, value} model, the eighteen operators and which
-  meta.type offers each, meta.filter.defaultOperator, isFilterActive and the
-  half-typed filter, the filter panel, TMDataGrid.FilterButton,
-  TMDataGrid.FilterPills with its api prop, openColumnFilter, replacing a value
-  control with DgRangeSliderFilter / DgDateRangeFilter / DgAutocompleteFilter /
-  DgTriStateFilter or a meta.filter.control component, per-column filterFn, and
-  the quick search: TMDataGrid.Search, quickSearchMode fuzzy or contains,
-  fuzzyGlobalFilterFn, enableMatchHighlighting and enableGlobalFilter. Load when
-  adding filters, choosing operators, building a filter control, showing active
-  filters outside the grid, or wiring a search box.
+  meta.type offers each, meta.filter.operators to offer a column only a subset
+  of them, meta.filter.defaultOperator, isFilterActive and the half-typed
+  filter, the filters option and its surfaces (popup, sidebar, none, plus
+  inHeader for header filters), TMDataGrid.FilterPanel and its layout prop,
+  TMDataGrid.FilterButton, TMDataGrid.FilterPills with its api prop,
+  openColumnFilter, replacing a value control with DgRangeSliderFilter /
+  DgDateRangeFilter / DgAutocompleteFilter / DgTriStateFilter or a
+  meta.filter.control component, per-column filterFn, and the quick search:
+  TMDataGrid.Search, quickSearchMode fuzzy or contains, fuzzyGlobalFilterFn,
+  enableMatchHighlighting and enableGlobalFilter. Load when adding filters,
+  choosing operators, building a filter control, showing active filters outside
+  the grid, or wiring a search box.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.0'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/filtering.md'
-  - 'Jielga/TMDataGrid:src/docs/quick-search.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/filterOperators.ts'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/quickSearch.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/filtering.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/quick-search.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/filterOperators.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/quickSearch.ts'
 ---
 
 # TMDataGrid - Filtering
@@ -48,7 +51,9 @@ leaving that end open).
 
 A filter with an empty value **stays in state** so the panel keeps its row while
 the user types. It matches every row, does not set the header indicator and
-produces no pill. `isFilterActive(value)` tests for that state; presence in
+produces no pill. `isFilterActive(value)` tests for that state, and
+`activeColumnFilters(columnFilters | table)` applies it across the slice and
+types what it hands back (entries in any other value shape are dropped); presence in
 `columnFilters` does not.
 
 ## Operators
@@ -80,16 +85,105 @@ columnHelper.accessor("salary", {
 });
 ```
 
-## The panel and the pills
+`meta.filter.operators` narrows the list a column offers to a subset of its
+type's - for a column whose backend answers only some operators, so the user is
+never offered one the query cannot express. The panel dropdown and the header
+funnel show only those, in the type's order. An operator the type does not
+offer is ignored; a list that leaves nothing falls back to the type's full set.
+Without `defaultOperator`, a fresh filter opens on the type's default when it is
+offered, else on the first offered operator.
 
-`TMDataGrid.FilterPanel` is column, operator and value rows under a "Filters"
-header, above "Add filter" and "Clear all". It is rendered by
-`TMDataGrid.Table`; Escape and a click outside close it, with `FilterButton`
-exempt from the click-away so it stays a toggle. Closing only hides it; the
-filters stay. **Clear all** drops every filter, half-typed ones included.
+```tsx
+columnHelper.accessor("customer", {
+  header: "Customer",
+  meta: { filter: { operators: ["contains", "equals", "isEmpty", "isNotEmpty"] } },
+});
+```
+
+`getColumnOperators(column)` returns the resolved list and
+`getColumnDefaultOperator(column)` the operator a fresh filter opens on. The
+`server-side` skill shows the list typed together with the API mapping table.
+
+## The filters option
+
+`filters` on `useTMDataGrid` picks the surface. It is read field by field, so a
+literal is fine.
+
+| Option | Type | Default | What it does |
+| --- | --- | --- | --- |
+| `surface` | `"popup" \| "sidebar" \| "none"` | `"popup"` | What `TMDataGrid.Table` renders and `FilterButton` toggles. |
+| `sidebarSide` | `"left" \| "right"` | `"right"` | Which side the sidebar sits on. Ignored by the other surfaces. |
+| `sidebarWidth` | `string` | `"280px"` | Sidebar width, any CSS length. Ignored by the other surfaces. |
+| `defaultOpen` | `boolean` | `true` under `"sidebar"`, else `false` | Whether the surface starts open. Read once, at mount. Under `"none"`, the starting value of `ui.state.filterPanelOpen`. |
+| `inHeader` | `boolean` | `false` | A second header row of per-column controls. Independent of `surface`. |
+
+`surface` and `inHeader` are separate choices: `{ surface: "none", inHeader: true }`
+is header filters alone, `{ inHeader: true }` keeps the popup as well.
+
+```tsx
+useTMDataGrid({ data, columns, filters: { surface: "sidebar", inHeader: true } });
+```
+
+**Popup** - the default. Floats over the first body rows. A pointerdown
+outside, Escape, and emptying it (the last row removed, or **Clear all**) all
+close it; `FilterButton` is exempt from the click-away so it stays a toggle.
+
+**Sidebar** - the same panel beside the rows, inside the grid frame and under
+the toolbar. The rows give up the width rather than being covered, a click in
+the table does not dismiss it, and clearing the filters leaves it standing.
+Escape closes it. It starts open, being a layout choice; its rows are
+`layout="stacked"`, since 280px has no room for the triple.
+
+**Header filters** - `inHeader: true` adds a header row of value controls, one
+per filterable column, on the same column tracks as everything else. The
+column and operator dropdowns are not there: the column is the one the cell
+sits over, and the operator is a funnel button beside the input, tinted off its
+default. The column menu's Filter item and the funnel indicator both come off,
+having nothing left to reveal; the filtered column's tinted title stays. A
+narrow column clips its control - give it a `minSize`.
 
-`TMDataGrid.FilterPills` takes the grid as an `api` prop instead of reading
-context, so active filters can live in a page header or anywhere else:
+Clearing a header control removes the column's `columnFilters` entry rather
+than leaving an empty one, unless the user also picked a non-default operator,
+which is kept. Panel rows still keep their empty filters.
+
+`FilterButton` still toggles whatever `surface` names. `openColumnFilter` does
+not: under `inHeader` it always focuses the header control and leaves the
+surface closed.
+
+**None** - `surface: "none"` renders no panel and no `FilterButton`, so a
+hand-placed `TMDataGrid.FilterPanel` is the only one. Read
+`ui.state.filterPanelOpen` if it belongs behind a control of your own.
+
+## TMDataGrid.FilterPanel
+
+The panel of filter rows - one column / operator / value triple per filter, over "Add filter" and "Clear all".
+A plain block with no title, no close button and no open state: it renders wherever it is mounted, and the popup and sidebar surfaces are wrappers around it.
+It must be inside `<TMDataGrid>` (it reads the grid from context) and it only reads and writes `columnFilters`, so a `manualFiltering` grid gets it for free.
+Closing a surface only hides it; the filters stay.
+**Clear all** drops every filter, half-typed ones included.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `layout` | `"row" \| "stacked"` | `"row"` | `"row"` is side by side and wants about 550px; `"stacked"` fills a narrow host. Passed to every value control as its `layout`. |
+
+```tsx
+<Drawer opened={open} onClose={close}>
+  <TMDataGrid.FilterPanel layout="stacked" />
+</Drawer>
+```
+
+## TMDataGrid.FilterButton
+
+The toolbar button that toggles the filter surface, tinted with the count of active filters.
+Opening an empty panel seeds a filter row on the first filterable column; with filters already in state it opens on those.
+Renders nothing when no column can be filtered, and nothing under `surface: "none"`.
+No props.
+
+## TMDataGrid.FilterPills
+
+One pill per **active** filter, `First name: Sofia ✕`, where the ✕ clears it and a click on the label calls `openColumnFilter`.
+The label spells the operator out unless it is the type's default: `Age is greater than 30`, but `First name: Sofia`.
+It takes the grid as an `api` prop instead of reading context, so it renders anywhere on the page.
 
 ```tsx
 import { TMDataGridFilterPills } from "@jielga/tmdatagrid";
@@ -97,11 +191,18 @@ import { TMDataGridFilterPills } from "@jielga/tmdatagrid";
 <TMDataGridFilterPills api={grid} onPillClick={(columnId) => focus(columnId)} />;
 ```
 
-One pill per **active** filter, `First name: Sofia ✕`, where ✕ clears it and a
-click on the label reopens the panel on its column. The label spells the
-operator out unless it is the type's default: `Age is greater than 30`, but
-`First name: Sofia`. `openColumnFilter(api, columnId)` does the same reopening
-from anywhere, seeding an empty row if the column has none.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `api` | `TMDataGridApi<TData>` | - | The object returned by `useTMDataGrid`. |
+| `size` | `MantineSize` | `"sm"` | Pill size. |
+| `showClearAll` | `boolean` | `true` | "Clear all", shown once two filters are active. |
+| `onPillClick` | `(columnId: string) => void` | - | Replaces the default click behaviour. |
+| `className` | `string` | - | Added to the wrapper class. |
+
+## openColumnFilter
+
+`openColumnFilter(api, columnId)` seeds an empty filter if the column has none, then opens the surface on that column's panel row - or, under `inHeader`, scrolls the column's header control into view and focuses it, leaving the surface closed.
+It is what a pill's label and the column menu's Filter item both call.
 
 ## Replacing the value control
 
@@ -220,12 +321,13 @@ const activeCount = columnFilters.length;
 Correct:
 
 ```tsx
-import { isFilterActive } from "@jielga/tmdatagrid";
+import { activeColumnFilters } from "@jielga/tmdatagrid";
 
-const active = columnFilters.filter((filter) => isFilterActive(filter.value));
+// The entries that narrow anything, with `value` typed rather than `unknown`.
+const active = activeColumnFilters(columnFilters);
 ```
 
-Source: `src/docs/filtering.md` (How a filter is stored).
+Source: `packages/tmdatagrid/docs/filtering.md` (How a filter is stored).
 
 ### HIGH Assuming `value` is always a string
 
@@ -246,7 +348,7 @@ if (operatorTakesRangeValue(operator)) {
 }
 ```
 
-Source: `src/tmdatagrid/core/filterOperators.ts`.
+Source: `packages/tmdatagrid/src/core/filterOperators.ts`.
 
 ### HIGH A numeric column with no `meta.type`
 
@@ -255,7 +357,7 @@ Source: `src/tmdatagrid/core/filterOperators.ts`.
 `between` never appear in the panel, and comparisons run as text, where `"9"`
 sorts above `"10"`.
 
-Source: `src/docs/filtering.md` (Operators).
+Source: `packages/tmdatagrid/docs/filtering.md` (Operators).
 
 ### HIGH A filter control defined inside the component
 
@@ -272,7 +374,7 @@ const StatusFilter: TMDataGridFilterControlComponent = (args) => { /* … */ };
 meta: { filter: { control: StatusFilter } }
 ```
 
-Source: `src/docs/filtering.md` (Writing your own).
+Source: `packages/tmdatagrid/docs/filtering.md` (Writing your own).
 
 ### MEDIUM Writing the whole filter from a custom control
 
@@ -292,7 +394,7 @@ Correct:
 onChange(picked);
 ```
 
-Source: `src/docs/filtering.md` (Writing your own).
+Source: `packages/tmdatagrid/docs/filtering.md` (Writing your own).
 
 ### MEDIUM Expecting match highlighting in a custom cell
 
@@ -301,7 +403,7 @@ does not modify a custom renderer's output. A column with a `cell` renderer
 shows no marks whatever `enableMatchHighlighting` is set to. Equality operators
 highlight nothing either.
 
-Source: `src/docs/quick-search.md` (Match highlighting).
+Source: `packages/tmdatagrid/docs/quick-search.md` (Match highlighting).
 
 ### MEDIUM Expecting fuzzy ranking to survive a sort
 
@@ -309,7 +411,7 @@ The rank ordering applies only while the search is the sole narrowing. Any sort
 or grouping replaces it. The ordering is derived and never written into
 `sorting`, so there is nothing to clear afterwards.
 
-Source: `src/docs/quick-search.md` (Fuzzy by default).
+Source: `packages/tmdatagrid/docs/quick-search.md` (Fuzzy by default).
 
 ## Reference
 
@@ -318,20 +420,26 @@ Source: `src/docs/quick-search.md` (Fuzzy by default).
 | `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the panel, the button and the menu item. |
 | `enableColumnFilter` | Column option | `boolean` | `true` | `false` takes one column out of filtering. |
 | `meta.type` | Column meta | `TMDataGridColumnType` | `"string"` | Selects the operators and the value control. |
-| `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default | The operator a fresh filter opens on. |
+| `meta.filter.operators` | Column meta | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. |
+| `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter opens on. |
 | `meta.filter.control` | Column meta | `TMDataGridFilterControlComponent` | By type and operator | Replaces the value control. Module scope. |
 | `filterFn` | Column option | name or fn | `"tmDataGrid"` | Custom matching for one column. |
 | `quickSearchMode` | Option | `"fuzzy" \| "contains"` | `"fuzzy"` | How the quick search matches. |
 | `enableMatchHighlighting` | Option | `boolean` | `false` | Mark matched text in default-rendered cells. |
 | `enableGlobalFilter` | Table option | `boolean` | `true` | Also a column option. Removes the input, or one column's participation. |
 | `globalFilterFn` | Table option | filter fn | fuzzy | Overrides the matching, and the ranking with it. |
-| `TMDataGrid.FilterPanel` | Component | – | – | The panel of filter rows. |
+| `TMDataGrid.FilterPanel` | Component | `layout: "row" \| "stacked"`, Mantine `BoxProps` | `"row"` | The panel of filter rows, as a plain block. Style props set on it. |
+| `filters` | Table option | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Which surface holds the filter controls. |
+| `TMDataGridFilterControlArgs.layout` | Type | `"row" \| "stacked" \| "header"` | – | How much room a value control has, and whether it names itself. |
+| `filterValueShape` | Export | `(operator) => "scalar" \| "set" \| "range"` | – | Which shape an operator's value takes. |
 | `TMDataGrid.FilterButton` | Component | – | – | Toolbar button opening the panel, with an active count. |
-| `TMDataGrid.FilterPills` | Component | `api`, `size`, `showClearAll`, `onPillClick`, `className` | – | Active filters as removable pills, renderable anywhere. |
+| `TMDataGrid.FilterPills` | Component | `api`, `size`, `showClearAll`, `onPillClick`, Mantine `BoxProps` | – | Active filters as removable pills, renderable anywhere. Style props set on the wrapper. |
 | `TMDataGrid.Search` | Component | `placeholder`, `debounce` (`250`), `w` (`220`) | – | The debounced quick-search input. |
 | `openColumnFilter` | Export | `(api, columnId) => void` | – | Opens the panel on a column. |
 | `isFilterActive` | Export | `(value) => boolean` | – | Whether a filter value narrows anything. |
+| `activeColumnFilters` | Export | `(columnFilters \| table) => Array<{ id, value }>` | – | The filters in the grid's own value shape that narrow anything, typed. |
 | `getOperatorsForType` | Export | `(type) => operators` | – | The operator list a type offers. |
+| `getColumnOperators` · `getColumnDefaultOperator` | Exports | `(column) => operators` · `(column) => operator` | – | One column's list after `meta.filter.operators`, and the operator a fresh filter on it opens on. |
 | `FILTER_OPERATOR_LABELS` | Export | record | – | The label shown for each operator. |
 | `formatFilterLabel` | Export | `({ label, type, filter }) => string` | – | The one-line description used on the pills. |
 | `emptyValueForOperator` · `operatorNeedsValue` · `operatorTakesArrayValue` · `operatorTakesRangeValue` | Exports | – | – | What shape of value an operator expects. |

package/skills/getting-started/SKILL.md

@@ -4,19 +4,19 @@ description: >
   Set up TMDataGrid, a compound React data grid built on TanStack Table v9 and
   Mantine. Covers useTMDataGrid, the TMDataGrid root, context, the component
   catalog (Table, Footer, Toolbar, Spacer, SummaryCount, Search,
-  LoadingIndicator, DraftActions, FilterButton, ColumnsButton, FilterPanel,
-  FilterPills, ColumnsPanel), the size scale and the bounded-height layout
-  requirement. Load when adding a grid, choosing which parts to render, or when
-  rows do not appear.
+  LoadingIndicator, DraftActions, FilterButton, Menu, FilterPanel, FilterPills,
+  ColumnsPanel), the size scale and the bounded-height layout requirement. Load
+  when adding a grid, choosing which parts to render, or when rows do not
+  appear.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.0'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/getting-started.md'
-  - 'Jielga/TMDataGrid:src/docs/anatomy.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGrid.tsx'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/core/sizes.ts'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/getting-started.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/anatomy.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/sizes.ts'
 ---
 
 # TMDataGrid - Getting started
@@ -80,7 +80,9 @@ export function Employees({ data }: { data: Employee[] }) {
         <TMDataGrid.SummaryCount />
         <TMDataGrid.Spacer />
         <TMDataGrid.FilterButton />
-        <TMDataGrid.ColumnsButton />
+        <TMDataGrid.Menu>
+          <TMDataGrid.Menu.Columns />
+        </TMDataGrid.Menu>
       </TMDataGrid.Toolbar>
 
       <TMDataGrid.Table<Employee> />
@@ -149,7 +151,7 @@ flex column.
 | Component | Props | Notes |
 | --- | --- | --- |
 | `TMDataGrid` | `table`, `ui`, `features`, `size`, `className`, `style` | Root. Provides context. `style` also takes CSS variables: `--dg-row-selected-bg`, `--dg-row-height`, `--dg-header-height`, `--dg-font-size`, `--dg-padding`. |
-| `TMDataGrid.Table` | `onRowClick(row)`, `renderRowContextMenu`, `renderColumnMenuItems`, `rowContextMenuProps` | Header, virtualized body, filter panel. `onRowClick` runs in addition to selection under `selectionMode: "row"`. |
+| `TMDataGrid.Table` | `onRowClick(row)`, `renderRowContextMenu`, `renderColumnMenuItems`, `rowContextMenuProps` | Header, virtualized body, and whichever filter surface the `filters` option asks for. `onRowClick` runs in addition to selection under `selectionMode: "row"`. |
 | `TMDataGrid.Footer` | `pageSizeOptions` (default `[10, 25, 50, 100]`), `pagination` render prop | Pagination controls. Renders nothing unless pagination is enabled. |
 | `TMDataGrid.Toolbar` | `children` | Flex row above the grid. |
 | `TMDataGrid.Spacer` | - | Pushes later toolbar items right. |
@@ -157,10 +159,10 @@ flex column.
 | `TMDataGrid.Search` | `placeholder`, `debounce` (default `250`), `w` (default `220`) | Quick search over every column, debounced into `globalFilter`. Renders nothing under `enableGlobalFilter: false`. |
 | `TMDataGrid.LoadingIndicator` | - | Small spinner while `meta.loading` is `true` and rows stay on screen. |
 | `TMDataGrid.DraftActions` | `renderActions` | Save with the pending count, and Discard. Renders nothing while editing is off - see the `editing` skill. |
-| `TMDataGrid.FilterButton` | - | Toggles filter panel. Renders nothing if no column is filterable. |
-| `TMDataGrid.ColumnsButton` | - | Opens column manager. Renders nothing if no column is hideable. |
-| `TMDataGrid.FilterPanel` | - | Rendered by `.Table`; exported for custom layouts. Header close button, Escape, click-away, "Add filter" and "Clear all". |
-| `TMDataGrid.ColumnsPanel` | - | Rendered by `.ColumnsButton`; exported for custom layouts. |
+| `TMDataGrid.FilterButton` | - | Toggles the filter surface, seeding a filter row on the first filterable column. Renders nothing if no column is filterable, or under `filters.surface: "none"`. |
+| `TMDataGrid.Menu` | `children`, `icon`, `label`, Mantine `MenuProps` | The burger and its dropdown: your own `Menu.Item`s, and `TMDataGrid.Menu.Columns`, the column chooser as menu items (renders nothing if no column is hideable). See the `appearance` skill. |
+| `TMDataGrid.FilterPanel` | `layout` (`"row"` \| `"stacked"`, default `"row"`) | Filter rows over "Add filter" / "Clear all", as a plain block. Rendered by `.Table` inside the popup and the sidebar; place it yourself under `filters.surface: "none"`. See the `filtering` skill. |
+| `TMDataGrid.ColumnsPanel` | - | The column chooser as plain controls, for a Popover or a Drawer. |
 | `TMDataGrid.FilterPills` | `api`, `size` (default `"sm"`), `showClearAll` (default `true`), `onPillClick(columnId)`, `className` | One pill per active filter, ✕ to clear it. Takes the api as a prop, so it can be rendered outside the grid. Also exported as `TMDataGridFilterPills`. |
 
 Pass the row type so `onRowClick` stays typed: