@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.1

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";
@@ -157,6 +157,10 @@ meta: {
 }
 ```
 
+The map receives `TMDataGridEditValueMapArgs`: `{ value, previous, row, column, table }`.
+Unlike `meta.edit.enabled`, its `row` is `Row<TMDataGridFeatures, TMDataGridRowData>`
+with or without the column helper.
+
 The grid applies it in the editor host, around the field every editor writes
 through, so it covers the six built-ins, a custom `meta.edit.editor`, and the
 type-to-edit seed character.
@@ -193,8 +197,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 +233,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"`.
 
@@ -236,7 +245,8 @@ unedited value and cannot pass. Use `"row"`.
 ## Cross-row rules
 
 `editing.tableValidators` holds the rules that need the other rows. Its
-`onSubmit` / `onSubmitAsync` receive `{ value, rowId, isNew, rows }`:
+`onSubmit` / `onSubmitAsync` receive `TMDataGridTableValidateArgs`,
+`{ value, rowId, isNew, rows }`:
 `value` is the committing row as drafted, and `rows` is
 `Array<{ rowId, value }>` - the collection as it would stand if the commit
 landed, with every draft overlaid, entry rows appended and deletion-marked
@@ -261,9 +271,59 @@ 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`.
+
+## Derived columns and a table-wide rule
+
+A column whose value depends on the other rows - a weight as a share of the
+total - cannot be an `accessorFn`, which is handed one row. Derive the whole
+collection with `useMemo` and pass the finished rows as `data`;
+`editing.onCommit` writes back to the source array, and the derived rows arrive
+on the next render. Under `mode: "cell"` with no draft store, every dependent
+column follows the commit.
+
+```tsx
+const positions = useMemo(() => {
+  const valued = holdings.map((h) => ({ ...h, marketValue: h.price * h.shares }));
+  const total = valued.reduce((sum, h) => sum + h.marketValue, 0);
+  return valued.map((h) => ({
+    ...h,
+    currentPct: (h.marketValue / total) * 100,
+    drift: h.targetPct - (h.marketValue / total) * 100,
+  }));
+}, [holdings]);
+```
+
+A rule over the whole collection, such as targets that may not total more than
+100%, is a `tableValidators` rule, while a bound on one cell (between 0 and 100)
+stays on `meta.edit.validate`. `editing.columns` keeps every other column
+read-only:
+
+```tsx
+editing: {
+  mode: "cell",
+  // Only the target weight takes edits; everything else is market data.
+  columns: ["targetPct"],
+  onCommit: ({ rowId, value }) =>
+    setHoldings((previous) =>
+      previous.map((h) => (h.id === rowId ? { ...h, targetPct: value.targetPct } : h)),
+    ),
+  tableValidators: {
+    // `rows` already holds the committing row's drafted value.
+    onSubmit: ({ rows }) => {
+      const total = rows.reduce((sum, r) => sum + Number(r.value.targetPct ?? 0), 0);
+      return total > 100.005
+        ? { fields: { targetPct: `Targets would total ${pct(total)}` } }
+        : undefined;
+    },
+  },
+}
+```
+
+Source: `packages/tmdatagrid/docs/portfolio-rebalancer.md`, and the demo
+`apps/docs/src/examples/demos/recipes/PortfolioRebalancer.tsx`.
 
 ## Server-side errors
 
@@ -283,9 +343,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 +354,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.1'
 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,32 @@ 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. |
+| `quickSearchMode` | Option | `TMDataGridQuickSearchMode`: `"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. |
+| `TMDataGridFilterPanelProps` · `TMDataGridFilterPanelLayout` | Types | – · `"row" \| "stacked"` | – | The props of `TMDataGrid.FilterPanel`, and the type of its `layout`. For wrapping the panel in a component of your own. |
+| `filters` | Table option | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Which surface holds the filter controls. |
+| `TMDataGridFiltersSettings` | Type | `Required<TMDataGridFiltersOptions>` | – | The `filters` option with its defaults filled in, as `api.filters`. |
+| `TMDataGridFilterSurface` · `TMDataGridFilterSidebarSide` | Types | `"popup" \| "sidebar" \| "none"` · `"left" \| "right"` | – | The types of `filters.surface` and `filters.sidebarSide`. |
+| `TMDataGridFilterControlArgs.layout` | Type | `TMDataGridFilterControlLayout` | – | How much room a value control has, and whether it names itself. |
+| `TMDataGridFilterControlLayout` | Type | `"row" \| "stacked" \| "header"` | – | The type of `layout` on `TMDataGridFilterControlArgs`. `"header"` is the cell of the `inHeader` row. |
+| `filterValueShape` | Export | `(operator) => TMDataGridFilterValueShape` | – | Which shape an operator's value takes. |
+| `TMDataGridFilterValueShape` | Type | `"scalar" \| "set" \| "range"` | – | What `filterValueShape` returns. |
 | `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<TMDataGridColumnFilter>` | – | The filters in the grid's own value shape that narrow anything, typed. |
+| `TMDataGridColumnFilter` | Type | `{ id, value }` | – | One entry of `columnFilters`, with `value` typed as `TMDataGridFilterValue`. |
 | `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,23 @@ 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) with their props types, the size scale, the bounded-height
+  layout requirement, and rendering rows without TMDataGrid.Table through
+  getDisplayedRows (a card view). Load when adding a grid, choosing which parts
+  to render, replacing the Table with a renderer of your own, or when rows do
+  not appear.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.9'
+  library_version: '2.0.1'
 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/docs/components.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/card-view.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/sizes.ts'
 ---
 
 # TMDataGrid - Getting started
@@ -80,7 +84,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> />
@@ -129,6 +135,7 @@ TanStack ships state and APIs for both but no `enable` option.
 | Configure the hook, or persist state | `options` |
 | Theme, size, compose the toolbar, translate | `appearance` |
 | Write tests against a grid | `testing` |
+| Upgrade code written against a 2.0 beta | `migrating-to-2` |
 
 ## Layout
 
@@ -149,20 +156,43 @@ 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. |
 | `TMDataGrid.SummaryCount` | `children` | Visible rows out of total. |
-| `TMDataGrid.Search` | `placeholder`, `debounce` (default `250`), `w` (default `220`) | Quick search over every column, debounced into `globalFilter`. Renders nothing under `enableGlobalFilter: false`. |
+| `TMDataGrid.Search` | `placeholder`, `debounce` (default `250`), `w` (default `220`) | Quick search over every column, debounced into `globalFilter`. Renders nothing under `enableGlobalFilter: false`. Also exported as `TMDataGridSearch`. |
 | `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`. |
 
+Each component's props type is exported, for wrapping a part in a component of
+your own:
+
+| Component | Props type |
+| --- | --- |
+| `TMDataGrid` | `TMDataGridProps<TData>`: the fields of `TMDataGridApi<TData>`, plus `children`, `size`, `className`, `style`, `id` and `data-testid` |
+| `TMDataGrid.Table` | `TMDataGridTableProps<TData>` |
+| `TMDataGrid.Toolbar` | `TMDataGridToolbarProps`: `children`, `withBottomBorder` (default `false`), Mantine `BoxProps` |
+| `TMDataGrid.Search` · `TMDataGridSearch` | `TMDataGridSearchProps` |
+| `TMDataGrid.Footer` | `TMDataGridFooterProps` |
+| `TMDataGrid.Menu` | `TMDataGridMenuProps`: `children`, `icon`, `label`, Mantine `MenuProps` |
+| `TMDataGrid.Menu.Columns` | `TMDataGridMenuColumnsProps`: `searchable` |
+| `TMDataGrid.Menu.Export` · `.ExportSelected` | `TMDataGridMenuExportProps`: per-item `exportOptions` overrides, `columns` (which also takes `"custom"`), `label` |
+| `TMDataGrid.ColumnsPanel` | `TMDataGridColumnsPanelProps`: `searchable`, Mantine `BoxProps` |
+| `TMDataGrid.FilterPanel` | `TMDataGridFilterPanelProps`: `layout`, Mantine `BoxProps` |
+| `TMDataGrid.FilterPills` · `TMDataGridFilterPills` | `TMDataGridFilterPillsProps<TData>` |
+| `TMDataGrid.DraftActions` · `TMDataGridDraftActions` | `TMDataGridDraftActionsProps`: `renderActions` |
+
+`renderActions` on `TMDataGrid.DraftActions` receives
+`TMDataGridDraftActionsSlotArgs`, `{ state, actions, Controls }`, typed
+`TMDataGridDraftActionsState`, `TMDataGridDraftActionsActions` and
+`TMDataGridDraftActionsControls`. The fields are in the `editing` skill.
+
 Pass the row type so `onRowClick` stays typed:
 
 ```tsx
@@ -247,6 +277,76 @@ The virtualizer needs row height as a number, so it cannot come from CSS alone.
 `SIZE_ROW_HEIGHT` is the exported source of these values and the stylesheet
 mirrors them. Set `meta.rowHeight` for a height outside the scale.
 
+## Render rows without TMDataGrid.Table
+
+To show the rows as something other than a table - cards, a list - keep
+`useTMDataGrid` and `<TMDataGrid>`, and replace `TMDataGrid.Table` with a
+renderer of your own. `TMDataGrid` renders no rows itself, and every other part
+works without the Table, so the toolbar stays. Search, filters, sorting, column
+visibility and row selection write the same table state the grid would.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  getRowId: (row) => String(row.id),
+  // The popup and the sidebar belong to TMDataGrid.Table.
+  filters: { surface: "none" },
+});
+
+<TMDataGrid {...grid} style={{ flex: 1, minHeight: 0 }}>
+  <TMDataGrid.Toolbar>
+    <TMDataGrid.Search />
+    <TMDataGrid.SummaryCount />
+    <TMDataGrid.Menu>
+      <TMDataGrid.Menu.Columns />
+    </TMDataGrid.Menu>
+  </TMDataGrid.Toolbar>
+  <TMDataGrid.FilterPanel layout="stacked" />
+  <CardList table={grid.table} features={grid.features} />
+</TMDataGrid>;
+```
+
+Read the rows with `getDisplayedRows(table, features)`: the rows the Table
+would render, in render order - filtered, sorted, the current page when paging
+is active, pinned rows left out. Call it inside a selector with a shallow
+compare:
+
+```tsx
+import { useSelector } from "@tanstack/react-store";
+import { shallow } from "@tanstack/store";
+import { getDisplayedRows } from "@jielga/tmdatagrid";
+
+const rows = useSelector(table.store, () => getDisplayedRows(table, features), {
+  compare: shallow,
+});
+```
+
+The table identity never changes, so the React Compiler caches a bare
+`getDisplayedRows(table, features)` call and the list stops following filters
+and sorting. The shallow compare re-renders the list only when the rows change.
+Read `row.getVisibleCells()` the same way, inside
+`useSelector(table.store, () => row.getVisibleCells())`, and skip the generated
+columns with `isGeneratedColumn(cell.column.id)` - the checkbox column is among
+the visible cells while row selection is on. Render each value through the
+column's own renderer: `flexRender(cell.column.columnDef.cell, cell.getContext())`.
+
+The following belong to `TMDataGrid.Table` and are not available without it:
+
+- the header, with click-to-sort, resizing, dragging and the column menus -
+  sort from a control of your own with `table.setSorting`
+- the filter popup and sidebar - set `filters: { surface: "none" }` and place
+  `TMDataGrid.FilterPanel` yourself
+- row details, row pinning, cell selection and editing in cells
+- `scrollToRow`, which returns `false` while no Table is mounted
+
+Virtualize the list yourself, for example with `useVirtualizer` from
+`@tanstack/react-virtual`.
+
+Source: `packages/tmdatagrid/docs/card-view.md`,
+`packages/tmdatagrid/docs/anatomy.md` (Which rows it renders), and the demo
+`apps/docs/src/examples/demos/recipes/CardView.tsx`.
+
 ## Helpers
 
 | Export | Description |