diff --git a/.changeset/filter-rail.md b/.changeset/filter-rail.md new file mode 100644 index 000000000..7821254a5 --- /dev/null +++ b/.changeset/filter-rail.md @@ -0,0 +1,19 @@ +--- +"@tailor-platform/app-shell": minor +--- + +Add `FilterRail`, an always-visible faceted filter rail that sits beside a `DataTable` and writes the same `CollectionControl`. + +Sections are config — any mix of `checkbox`, `radio`, `boolean`, `text`, `numberRange`, `date`, `dateRange` and `custom` — and every other feature is an optional part: `Header`, `ClearAll` and `Settings` (show / hide, reorder, sort). Below `lg` the rail turns itself into a left sheet behind a "Filters" button, like the Sidebar; wrap the page in `FilterRail.Provider` to place that button (`FilterRail.Trigger`) anywhere. + +```tsx + + + + + + + +``` + +Companion hooks: `useFilterRailCounts` (in-memory facet counts) and `useFilterRailLayout` (persisted section layout). diff --git a/.changeset/layout-fill-stacked-columns.md b/.changeset/layout-fill-stacked-columns.md new file mode 100644 index 000000000..d4062fc39 --- /dev/null +++ b/.changeset/layout-fill-stacked-columns.md @@ -0,0 +1,5 @@ +--- +"@tailor-platform/app-shell": patch +--- + +Fix `` with several columns on narrow screens. Below the breakpoint where the columns stack (`lg` for two columns, `xl` for three), the layout no longer bounds its rows, so no column is squashed to zero height and the content area scrolls as usual — as the `fill` docs already describe. Side-by-side behaviour is unchanged. diff --git a/decisions/filter-rail.md b/decisions/filter-rail.md new file mode 100644 index 000000000..ef4e6bcdb --- /dev/null +++ b/decisions/filter-rail.md @@ -0,0 +1,58 @@ +# Decision: `FilterRail` — an exposed faceted filter rail + +> Status: **Proposed — ships `FilterRail` as a new public component.** +> Scope: a second filter surface beside `DataTable`. `DataTable.Filters` is unchanged. + +## Context + +`DataTable.Filters` hides filterable fields behind an "Add filter" panel. That suits the long tail of ad-hoc filters, but ERP list screens usually have a handful of axes people use constantly (category, status, availability), and for those a dropdown costs a click to learn what is even filterable and gives no hint of how many rows a choice returns. + +A demo on `demo/filter-rail` proved out an always-visible rail with counts. This decision covers promoting it into the package. + +## Decision + +### Config sections + optional parts + +Sections are a config array (`sections`, like `DataTable` `columns` or `DescriptionCard` `fields`); assembly is a compound namespace (`FilterRail.Provider / Root / Header / ClearAll / Settings / Sections / Trigger`). + +- The rail must know every section to offer Clear all, reorder/hide settings and the "hiding clears its filter" rule. Pure JSX sections would need a registration protocol for that. +- A single component with a prop per feature cannot place pieces elsewhere (the narrow-screen button in a table toolbar) and grows a flag per feature. Parts are included or left out. +- A `custom` section type covers anything the built-in controls do not, and declares the `fields` it owns so it still takes part in Clear all. + +### Not `DataTable.FilterRail` + +The rail lives in a different `Layout.Column`, so it can never be a descendant of `DataTable.Root`. It therefore takes `control` as a prop rather than reading context. + +### Same filter model, no new operators + +Checkbox = `in`/`nin`, radio = `eq`/`ne`, boolean = `eq`, ranges = `between` (a field holds one filter, so `gte` + `lte` is not expressible). The operator is fixed per section; users pick values, not operators. + +### Counts and storage belong to the consumer + +The rail never sees rows. `counts` is a prop; `useFilterRailCounts` covers the in-memory case, a backend returns the same shape from an aggregation. Layout storage is a binding with a localStorage default (`useFilterRailLayout`) and a seam for a backend store — a team-shared layout is a product decision, not a component one. + +### Narrow screens: the Sidebar pattern + +Below `lg` the rail turns itself into a left sheet behind a "Filters" button, as the Sidebar does on mobile. The breakpoint check stays internal — AppShell exports no breakpoint hooks (`useIsMobile` / `useIsTablet` are private too), so apps write no breakpoint code. + +The app still owns where the button goes: `FilterRail.Trigger`, inside `FilterRail.Provider`, can sit anywhere (a table toolbar, a page header). If none is mounted, `Root` renders a fallback button in its own spot, so the filters are never unreachable on a screen whose author never tested narrow widths. + +`Root` takes the config directly in the common case; `Provider` is only needed when the Trigger lives outside the rail. Inside a Provider, `Root` takes no config (enforced by its prop types). + +### Saved views are a separate change + +Named views (filters plus sort, page size and column layout) were prototyped here and moved to a follow-up. A view is mostly `DataTable` state, its storage needs an async design for team-shared views, and keeping it out lets this review focus on the rail. + +### No hidden state + +Sections do not collapse; a selected option is never truncated, disabled or searched away; hiding a section clears its filter; zero-count options are disabled rather than hidden (there is no `"hide"` — removing rows reshuffles the list on every click and loses the "this has nothing" answer). + +### Radio stays private + +app-shell has no radio control. The rail uses a native radio in a `
` internally; a public `RadioGroup` can be promoted later without changing the rail's API. + +## Consequences + +- New public surface: `FilterRail`, `FilterRailRootProps`, `FilterRailSection`, `useFilterRailCounts`, `useFilterRailLayout`. +- A field should belong to one surface: do not render `DataTable.Filters` for fields the rail owns. +- Known limit: the URL serializer stringifies scalars, so a backend must coerce `"true"`/numeric strings as it would any input (the rail itself reads `"true"` back correctly). diff --git a/docs-manifest.json b/docs-manifest.json index 749f4e4b3..448580788 100644 --- a/docs-manifest.json +++ b/docs-manifest.json @@ -664,6 +664,29 @@ "examples": null } }, + "filter-rail": { + "slug": "filter-rail", + "kind": "code-backed", + "outline": "docs-src/components/filter-rail.docs.outline.md", + "output": "docs/components/filter-rail.md", + "examples": null, + "sources": ["packages/core/src/components/filter-rail/**"], + "claims": [], + "symbols": [ + "FilterRail", + "FilterRailRootProps", + "FilterRailSection", + "useFilterRailCounts", + "useFilterRailLayout" + ], + "hashes": { + "typeSurface": "f00196ddf9879362", + "outline": "15562a48f49aabae", + "snapshot": "5c1ae1fe48b89541", + "outputMd": "14b9a7a6c16fd50e", + "examples": null + } + }, "form": { "slug": "form", "kind": "code-backed", @@ -1700,6 +1723,7 @@ "packages/core/skills/app-shell-patterns/references/components/description-card.md": "a347fd1f4ccd433e", "packages/core/skills/app-shell-patterns/references/components/dialog.md": "ec6a0ac098d1d87a", "packages/core/skills/app-shell-patterns/references/components/document-progress-card.md": "d0fb940f685f8869", + "packages/core/skills/app-shell-patterns/references/components/filter-rail.md": "14b9a7a6c16fd50e", "packages/core/skills/app-shell-patterns/references/components/form.md": "91d901b17aed7781", "packages/core/skills/app-shell-patterns/references/components/global-header-layout.md": "dd2b0da3702cf8d9", "packages/core/skills/app-shell-patterns/references/components/grid.md": "9051eb53dde4179f", @@ -1757,6 +1781,6 @@ "packages/core/skills/app-shell-patterns/references/patterns/list-dense-scan.md": "916baa3cd2b9cbf1", "packages/core/skills/app-shell-patterns/references/pages/document-detail.md": "717ef4e7ae835aff", "packages/core/skills/app-shell-patterns/references/migrations.md": "013c3fef2303b096", - "packages/core/skills/app-shell-patterns/SKILL.md": "526decbfd2db6555" + "packages/core/skills/app-shell-patterns/SKILL.md": "5da601f440475b77" } } diff --git a/docs-src/components/filter-rail.docs.outline.md b/docs-src/components/filter-rail.docs.outline.md new file mode 100644 index 000000000..71c514b6b --- /dev/null +++ b/docs-src/components/filter-rail.docs.outline.md @@ -0,0 +1,140 @@ +--- +kind: code-backed +group: filter-rail +title: FilterRail +description: An always-visible faceted filter rail with counts and user layout settings, driven by the same CollectionControl as DataTable +sources: + - packages/core/src/components/filter-rail/** +--- + +# FilterRail + +`FilterRail` shows every filterable axis beside the results instead of hiding it behind a filter dropdown. Each section displays its options, and optionally how many rows each option would return, before the user clicks. + +It writes the same `CollectionControl` a `DataTable` reads, so there is no second filter engine: a checkbox section **is** the `in` operator, a radio section is `eq`, a range is `between`. + +```tsx +import { FilterRail, type FilterRailSection } from "@tailor-platform/app-shell"; + +const sections: FilterRailSection[] = [ + { + id: "category", + label: "Category", + control: "checkbox", + field: "category", + options: categories, + }, + { id: "status", label: "Status", control: "radio", field: "status", options: statuses }, +]; + + + +; +``` + +## Sections and parts + +What the rail shows is **config**: `sections`, one entry per axis, in screen order. How the rail is assembled is **parts**: leave a part out and that feature is not rendered. + +| Part | Renders | +| --------------------- | ----------------------------------------------------------------------------- | +| `FilterRail.Root` | The rail. Takes `control`, `sections`, `counts`, `layout`. | +| `FilterRail.Header` | A title row with a slot for actions. | +| `FilterRail.ClearAll` | Clears the rail's own filters only. Hidden while none are active. | +| `FilterRail.Settings` | Show / hide, reorder and sort sections. Needs `layout`. | +| `FilterRail.Sections` | The sections, in the user's layout. Scrolls while the header stays put. | +| `FilterRail.Provider` | Holds the config when a `Trigger` sits outside the rail (see Narrow screens). | +| `FilterRail.Trigger` | The narrow-screen "Filters" button, placed anywhere inside `Provider`. | + +```tsx + + + + + + + +``` + +### Section types + +Every section has an `id`, a `label` and an optional `hint`. The operator is fixed per section — the user picks values, never operators. + +| `control` | Commits | Notes | +| ------------- | ------------------------------------------ | ----------------------------------------------------------- | +| `checkbox` | `in` (or `nin`) with the ticked values | `sort`, `truncate` (default 8), `pinned`, `searchThreshold` | +| `radio` | `eq` (or `ne`) with one value | An "Any" row removes the filter; `anyLabel: null` hides it | +| `boolean` | `eq` with `true` / `false` | Three states: Any, `trueLabel`, `falseLabel` | +| `text` | `contains`, `hasPrefix` or `eq` | Debounced (`debounceMs`, default 250) | +| `numberRange` | `between` `{ min, max }`, or `gte` / `lte` | Commits on blur / Enter; one end alone is half-open | +| `date` | `eq`, `gte` or `lte` a `YYYY-MM-DD` | Uses `DatePicker` | +| `dateRange` | `between` `{ min, max }` | Uses `DateRangePicker`; optional `presets` | +| `custom` | Whatever `render` writes | Declares the `fields` it owns so Clear all includes them | + +A checkbox list long enough to be truncated also gets a search box, so a value can be found without scrolling (`searchThreshold` overrides when it appears). + +A field holds one filter, so two sections must not share a field; the rail warns in the console when they do. + +```tsx +const stockLevel: FilterRailSection = { + id: "stockLevel", + label: "Stock level", + control: "custom", + fields: ["stock"], + render: ({ getFilter, setFilter }) => ( + + ), +}; +``` + +The rail never hides state: a selected option is never truncated away, never disabled and never hidden by a section's search box, and sections do not collapse. + +## Counts + +Pass `counts` to show a number beside each option and disable options that would return nothing (`zeroBehavior="show"` keeps them enabled). The rail never sees rows, so counts come from you. For rows held in memory, `useFilterRailCounts` does standard faceting: each section's count excludes its own filter, so ticking one box never zeroes its neighbours. + +```tsx +const counts = useFilterRailCounts(rows, sections, control.filters, { baseline: true }); +``` + +For a server-side collection, return the same shape from an aggregation query: `{ live: { [sectionId]: { [value]: count } }, baseline?, total?, withoutSection? }`. With `total` and `withoutSection`, an empty result shows which section to clear to get rows back. Counts are optional: without them the rail still works, it just shows no numbers. + +## User layout + +`useFilterRailLayout(storageKey)` persists the user's section order, hidden sections and option sort to localStorage. Pass it as `layout` and add `FilterRail.Settings`. Hiding a section that carries a filter also clears that filter. To share a layout across a team, pass your own `{ value, onChange, onReset }` binding instead. + +## Beside a DataTable + +The rail sits in its own `Layout.Column`, outside `DataTable.Root`, which is why `control` is a prop. Do not also render `DataTable.Filters` for the same fields — one fact in two places can drift. + +## Narrow screens + +Below the `lg` breakpoint there is no room for a side column, so the rail turns itself into a left sheet behind a **Filters** button carrying the active count — the same way the Sidebar handles small screens. Apps write no breakpoint code. + +By default the button appears where the rail would have been. To put it somewhere else — a table toolbar, a page header — wrap the page in `FilterRail.Provider`, move the config there, and place `FilterRail.Trigger` wherever you want it. The Trigger renders nothing on wide screens, and while one is mounted the rail skips its own button. + +```tsx + + + + + + + + + + + + + + + + + +``` diff --git a/docs/components/filter-rail.md b/docs/components/filter-rail.md new file mode 100644 index 000000000..712b9abf5 --- /dev/null +++ b/docs/components/filter-rail.md @@ -0,0 +1,138 @@ +--- +title: FilterRail +description: An always-visible faceted filter rail with counts and user layout settings, driven by the same CollectionControl as DataTable +--- + + + +# FilterRail + +`FilterRail` shows every filterable axis beside the results instead of hiding it behind a filter dropdown. Each section displays its options, and optionally how many rows each option would return, before the user clicks. + +It writes the same `CollectionControl` a `DataTable` reads, so there is no second filter engine: a checkbox section **is** the `in` operator, a radio section is `eq`, a range is `between`. + +```tsx +import { FilterRail, type FilterRailSection } from "@tailor-platform/app-shell"; + +const sections: FilterRailSection[] = [ + { + id: "category", + label: "Category", + control: "checkbox", + field: "category", + options: categories, + }, + { id: "status", label: "Status", control: "radio", field: "status", options: statuses }, +]; + + + +; +``` + +## Sections and parts + +What the rail shows is **config**: `sections`, one entry per axis, in screen order. How the rail is assembled is **parts**: leave a part out and that feature is not rendered. + +| Part | Renders | +| --------------------- | ----------------------------------------------------------------------------- | +| `FilterRail.Root` | The rail. Takes `control`, `sections`, `counts`, `layout`. | +| `FilterRail.Header` | A title row with a slot for actions. | +| `FilterRail.ClearAll` | Clears the rail's own filters only. Hidden while none are active. | +| `FilterRail.Settings` | Show / hide, reorder and sort sections. Needs `layout`. | +| `FilterRail.Sections` | The sections, in the user's layout. Scrolls while the header stays put. | +| `FilterRail.Provider` | Holds the config when a `Trigger` sits outside the rail (see Narrow screens). | +| `FilterRail.Trigger` | The narrow-screen "Filters" button, placed anywhere inside `Provider`. | + +```tsx + + + + + + + +``` + +### Section types + +Every section has an `id`, a `label` and an optional `hint`. The operator is fixed per section — the user picks values, never operators. + +| `control` | Commits | Notes | +| ------------- | ------------------------------------------ | ----------------------------------------------------------- | +| `checkbox` | `in` (or `nin`) with the ticked values | `sort`, `truncate` (default 8), `pinned`, `searchThreshold` | +| `radio` | `eq` (or `ne`) with one value | An "Any" row removes the filter; `anyLabel: null` hides it | +| `boolean` | `eq` with `true` / `false` | Three states: Any, `trueLabel`, `falseLabel` | +| `text` | `contains`, `hasPrefix` or `eq` | Debounced (`debounceMs`, default 250) | +| `numberRange` | `between` `{ min, max }`, or `gte` / `lte` | Commits on blur / Enter; one end alone is half-open | +| `date` | `eq`, `gte` or `lte` a `YYYY-MM-DD` | Uses `DatePicker` | +| `dateRange` | `between` `{ min, max }` | Uses `DateRangePicker`; optional `presets` | +| `custom` | Whatever `render` writes | Declares the `fields` it owns so Clear all includes them | + +A checkbox list long enough to be truncated also gets a search box, so a value can be found without scrolling (`searchThreshold` overrides when it appears). + +A field holds one filter, so two sections must not share a field; the rail warns in the console when they do. + +```tsx +const stockLevel: FilterRailSection = { + id: "stockLevel", + label: "Stock level", + control: "custom", + fields: ["stock"], + render: ({ getFilter, setFilter }) => ( + + ), +}; +``` + +The rail never hides state: a selected option is never truncated away, never disabled and never hidden by a section's search box, and sections do not collapse. + +## Counts + +Pass `counts` to show a number beside each option and disable options that would return nothing (`zeroBehavior="show"` keeps them enabled). The rail never sees rows, so counts come from you. For rows held in memory, `useFilterRailCounts` does standard faceting: each section's count excludes its own filter, so ticking one box never zeroes its neighbours. + +```tsx +const counts = useFilterRailCounts(rows, sections, control.filters, { baseline: true }); +``` + +For a server-side collection, return the same shape from an aggregation query: `{ live: { [sectionId]: { [value]: count } }, baseline?, total?, withoutSection? }`. With `total` and `withoutSection`, an empty result shows which section to clear to get rows back. Counts are optional: without them the rail still works, it just shows no numbers. + +## User layout + +`useFilterRailLayout(storageKey)` persists the user's section order, hidden sections and option sort to localStorage. Pass it as `layout` and add `FilterRail.Settings`. Hiding a section that carries a filter also clears that filter. To share a layout across a team, pass your own `{ value, onChange, onReset }` binding instead. + +## Beside a DataTable + +The rail sits in its own `Layout.Column`, outside `DataTable.Root`, which is why `control` is a prop. Do not also render `DataTable.Filters` for the same fields — one fact in two places can drift. + +## Narrow screens + +Below the `lg` breakpoint there is no room for a side column, so the rail turns itself into a left sheet behind a **Filters** button carrying the active count — the same way the Sidebar handles small screens. Apps write no breakpoint code. + +By default the button appears where the rail would have been. To put it somewhere else — a table toolbar, a page header — wrap the page in `FilterRail.Provider`, move the config there, and place `FilterRail.Trigger` wherever you want it. The Trigger renders nothing on wide screens, and while one is mounted the rail skips its own button. + +```tsx + + + + + + + + + + + + + + + + + +``` diff --git a/examples/vite-app/src/App.tsx b/examples/vite-app/src/App.tsx index 60ebe0929..7ce850443 100644 --- a/examples/vite-app/src/App.tsx +++ b/examples/vite-app/src/App.tsx @@ -83,6 +83,7 @@ const AppInner = () => { + diff --git a/examples/vite-app/src/pages/showcase/filter-rail/page.tsx b/examples/vite-app/src/pages/showcase/filter-rail/page.tsx new file mode 100644 index 000000000..eabfcb73c --- /dev/null +++ b/examples/vite-app/src/pages/showcase/filter-rail/page.tsx @@ -0,0 +1,568 @@ +import { useMemo, useState, type ReactNode } from "react"; +import { + Badge, + DataTable, + FilterRail, + Layout, + Tabs, + createColumnHelper, + useCollectionVariables, + useDataTable, + useFilterRailCounts, + useFilterRailLayout, + useURLCollectionVariables, + type AppShellPageProps, + type CollectionControl, + type CollectionVariables, + type DataTableData, + type FilterRailSection, + type PageInfo, +} from "@tailor-platform/app-shell"; +import { PanelLeft } from "lucide-react"; + +import { allProducts, type Product } from "../../../mock-products"; + +// ─── FilterRail showcase ──────────────────────────────────────────────────────── +// +// An always-visible faceted filter rail beside a DataTable. The rail and the +// table share one `CollectionControl`, so there is no second filter engine. +// +// Three variants prove the parts are optional: +// Full — every section type, counts, settings; below lg the Filters +// button sits in the table toolbar (Provider + Trigger) +// Checkboxes — Root + Sections only, plus a long Tags list with value search; +// below lg the rail falls back to its own Filters button +// Radios — radio + boolean + a custom section, no counts + +// ─── Rows ─────────────────────────────────────────────────────────────────────── + +// 🧪 Dummy Data: Replace with real data later +type Row = Product & { + inStock: boolean; + /** `publishedAt` is an ISO datetime; date sections commit `YYYY-MM-DD`. */ + publishedOn: string; + priceBand: string; +}; + +const band = (price: number) => + price < 25 ? "Under $25" : price < 75 ? "$25 – $75" : price < 150 ? "$75 – $150" : "$150+"; + +const ROWS: Row[] = allProducts.map((product) => ({ + ...product, + inStock: product.stock > 0, + publishedOn: product.publishedAt.slice(0, 10), + priceBand: band(product.price), +})); + +const distinct = (pick: (row: Row) => string) => + [...new Set(ROWS.map(pick))].sort().map((value) => ({ value, label: value })); + +const range = (pick: (row: Row) => number) => { + const values = ROWS.map(pick); + return { min: Math.floor(Math.min(...values)), max: Math.ceil(Math.max(...values)) }; +}; + +const PRICE = range((row) => row.price); +const STOCK = range((row) => row.stock); +const PUBLISHED = { + min: ROWS.reduce((a, r) => (r.publishedOn < a ? r.publishedOn : a), ROWS[0].publishedOn), + max: ROWS.reduce((a, r) => (r.publishedOn > a ? r.publishedOn : a), ROWS[0].publishedOn), +}; + +// ─── Local data source (stands in for a GraphQL query) ───────────────────────── + +function compare(a: unknown, b: unknown) { + if (typeof a === "number" || typeof b === "number") return Number(a) - Number(b); + return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0; +} + +function matches(value: unknown, op: string, operand: unknown): boolean { + // The URL round-trip stringifies scalars, as a backend's input parsing would undo. + const scalar = + typeof value === "boolean" && typeof operand === "string" ? operand === "true" : operand; + switch (op) { + case "eq": + return value === scalar; + case "ne": + return value !== scalar; + case "gte": + return compare(value, operand) >= 0; + case "lte": + return compare(value, operand) <= 0; + case "between": { + const { min, max } = operand as { min: unknown; max: unknown }; + return compare(value, min) >= 0 && compare(value, max) <= 0; + } + case "in": + // A list-valued cell (tags) matches when any of its members does. + if (Array.isArray(value)) return value.some((member) => matches(member, "in", operand)); + return Array.isArray(operand) && operand.map(String).includes(String(value)); + case "nin": + return Array.isArray(operand) && !operand.map(String).includes(String(value)); + case "contains": + return String(value).toLowerCase().includes(String(operand).toLowerCase()); + default: + return true; + } +} + +function queryRows(variables: CollectionVariables): DataTableData { + const query = variables.query ?? {}; + let rows = ROWS.filter((row) => + Object.entries(query).every(([field, ops]) => + Object.entries(ops as Record).every(([op, operand]) => + matches(row[field as keyof Row], op, operand), + ), + ), + ); + + if (variables.order?.length) { + const [{ field, direction }] = variables.order; + const dir = direction === "Desc" ? -1 : 1; + rows = [...rows].sort((a, b) => compare(a[field as keyof Row], b[field as keyof Row]) * dir); + } + + const total = rows.length; + const { first, after, last, before } = variables.pagination; + let start: number; + let end: number; + if (last != null) { + end = before != null ? Number(before) : total; + start = Math.max(0, end - last); + } else { + start = after != null ? Number(after) + 1 : 0; + end = start + (first ?? 25); + } + const page = rows.slice(start, end); + const pageInfo: PageInfo = { + startCursor: page.length ? String(start) : null, + endCursor: page.length ? String(start + page.length - 1) : null, + hasPreviousPage: start > 0, + hasNextPage: start + page.length < total, + }; + return { rows: page, pageInfo, total }; +} + +// ─── Columns ──────────────────────────────────────────────────────────────────── + +const money = (value: number) => `$${value.toFixed(2)}`; +const showDate = (value: string) => + new Date(`${value}T00:00:00Z`).toLocaleDateString("en-GB", { + day: "numeric", + month: "short", + year: "numeric", + timeZone: "UTC", + }); + +const { column } = createColumnHelper(); + +const COLUMNS = [ + column({ + id: "name", + label: "Product", + accessor: (row) => row.name, + type: "text", + width: 220, + sort: { field: "name", type: "string" }, + pin: "left", + }), + column({ + id: "category", + label: "Category", + accessor: (row) => row.category, + type: "text", + width: 140, + sort: { field: "category", type: "string" }, + }), + column({ + id: "status", + label: "Status", + render: (row) => ( + {row.status} + ), + width: 110, + }), + column({ + id: "price", + label: "Price", + render: (row) => {money(row.price)}, + accessor: (row) => row.price, + type: "number", + align: "right", + width: 110, + sort: { field: "price", type: "number" }, + }), + column({ + id: "stock", + label: "Stock", + accessor: (row) => row.stock, + type: "number", + align: "right", + width: 90, + sort: { field: "stock", type: "number" }, + }), + column({ + id: "publishedOn", + label: "Published", + render: (row) => {showDate(row.publishedOn)}, + width: 130, + sort: { field: "publishedOn", type: "string" }, + }), + column({ + id: "availableOn", + label: "Available", + render: (row) => {showDate(row.availableOn)}, + width: 130, + sort: { field: "availableOn", type: "string" }, + }), +]; + +// ─── Sections ─────────────────────────────────────────────────────────────────── + +/** Full: one of every built-in section type. Array order is screen order. */ +const FULL_SECTIONS: FilterRailSection[] = [ + { + id: "name", + label: "Product name", + control: "text", + field: "name", + operator: "contains", + placeholder: "Search…", + }, + { + id: "status", + label: "Status", + control: "radio", + field: "status", + options: distinct((row) => row.status), + }, + { + id: "category", + label: "Category", + control: "checkbox", + field: "category", + options: distinct((row) => row.category), + // Biggest first, on the baseline count so the order never moves under the cursor. + sort: "baselineCount", + truncate: 6, + }, + { + id: "inStock", + label: "Availability", + control: "boolean", + field: "inStock", + trueLabel: "In stock", + falseLabel: "Out of stock", + }, + { + id: "price", + label: "Price", + control: "numberRange", + field: "price", + min: PRICE.min, + max: PRICE.max, + step: 1, + unit: "$", + }, + { + id: "stock", + label: "Stock on hand", + control: "numberRange", + field: "stock", + min: STOCK.min, + max: STOCK.max, + step: 1, + }, + { + id: "publishedOn", + label: "Published", + control: "dateRange", + field: "publishedOn", + min: PUBLISHED.min, + max: PUBLISHED.max, + }, + { + id: "availableOn", + label: "Available on or after", + control: "date", + field: "availableOn", + operator: "gte", + }, +]; + +/** Checkboxes only. */ +const CHECKBOX_SECTIONS: FilterRailSection[] = [ + { + id: "category", + label: "Category", + control: "checkbox", + field: "category", + options: distinct((row) => row.category), + truncate: false, + }, + { + // A long, list-valued field: more options than fit, so the section shows a + // search box to find a value without scrolling. + id: "tags", + label: "Tags", + control: "checkbox", + field: "tags", + options: [...new Set(ROWS.flatMap((row) => row.tags))] + .sort() + .map((value) => ({ value, label: value })), + sort: "baselineCount", + }, + { + id: "priceBand", + label: "Price band", + control: "checkbox", + field: "priceBand", + // A curated vocabulary — authored order, never re-sorted. + options: ["Under $25", "$25 – $75", "$75 – $150", "$150+"].map((value) => ({ + value, + label: value, + })), + }, + { + id: "status", + label: "Status", + control: "checkbox", + field: "status", + options: distinct((row) => row.status), + }, +]; + +/** Radios, boolean and a custom section. No counts. */ +const RADIO_SECTIONS: FilterRailSection[] = [ + { + id: "status", + label: "Status", + control: "radio", + field: "status", + options: distinct((row) => row.status), + }, + { + id: "inStock", + label: "Availability", + control: "boolean", + field: "inStock", + trueLabel: "In stock", + falseLabel: "Out of stock", + anyLabel: "All products", + }, + { + id: "stockLevel", + label: "Stock level", + hint: "A custom section writing its own filter.", + control: "custom", + fields: ["stock"], + render: ({ getFilter, setFilter }) => { + const current = getFilter("stock")?.value as { min: number; max: number } | undefined; + const levels = [ + { label: "Low (1–20)", min: 1, max: 20 }, + { label: "Healthy (21–100)", min: 21, max: 100 }, + { label: "Overstocked (100+)", min: 101, max: STOCK.max }, + ]; + return ( +
+ {levels.map((level) => { + const active = current?.min === level.min && current?.max === level.max; + return ( + + ); + })} +
+ ); + }, + }, +]; + +// ─── Shared table ─────────────────────────────────────────────────────────────── + +const ProductsTable = ({ + control, + variables, + tableId, +}: { + control: CollectionControl; + variables: CollectionVariables; + tableId: string; +}) => { + const data = useMemo(() => queryRows(variables), [variables]); + const table = useDataTable({ columns: COLUMNS, data, control, tableId }); + return ( + + {/* No DataTable.Filters: a field belongs to one surface, not both. */} + + + + + + + ); +}; + +// ─── Variant: Full ────────────────────────────────────────────────────────────── + +const FullVariant = ({ header }: { header: ReactNode }) => { + const { variables, control } = useURLCollectionVariables({ params: { pageSize: 25 } }); + const counts = useFilterRailCounts(ROWS, FULL_SECTIONS, control.filters, { baseline: true }); + const layout = useFilterRailLayout("showcase:products"); + const data = useMemo(() => queryRows(variables), [variables]); + const table = useDataTable({ + columns: COLUMNS, + data, + control, + tableId: "filter-rail:full", + }); + + // Provider, because the Trigger lives in the table toolbar rather than in the + // rail. Below lg the rail turns into a sheet and the Trigger opens it; on wide + // screens the Trigger renders nothing. + return ( + + + {header} + + + + + + + + + + + + + + + + + + + + + + + ); +}; + +// ─── Variant: Checkboxes only ─────────────────────────────────────────────────── + +const CheckboxVariant = ({ header }: { header: ReactNode }) => { + const { variables, control } = useCollectionVariables({ params: { pageSize: 25 } }); + const counts = useFilterRailCounts(ROWS, CHECKBOX_SECTIONS, control.filters, { + baseline: true, + }); + return ( + + {header} + + + + + + + + + + ); +}; + +// ─── Variant: Radios + custom ─────────────────────────────────────────────────── + +const RadioVariant = ({ header }: { header: ReactNode }) => { + const { variables, control } = useCollectionVariables({ params: { pageSize: 25 } }); + return ( + + {header} + + + + + + + + + + + + + ); +}; + +// ─── Page ─────────────────────────────────────────────────────────────────────── + +const VARIANTS = [ + { key: "full", label: "Full" }, + { key: "checkbox", label: "Checkboxes only" }, + { key: "radio", label: "Radios + custom" }, +] as const; + +type VariantKey = (typeof VARIANTS)[number]["key"]; + +const FilterRailPage = () => { + const [variant, setVariant] = useState("full"); + // Layout reads its Header / Column children directly, so each variant renders + // its own Layout and receives the shared header. + const header = ( + + setVariant(next as VariantKey)} + variant="capsule" + size="sm" + > + + {VARIANTS.map((item) => ( + + {item.label} + + ))} + + + + ); + if (variant === "checkbox") return ; + if (variant === "radio") return ; + return ; +}; + +FilterRailPage.appShellPageProps = { + meta: { + title: "Filter rail", + icon: , + }, +} satisfies AppShellPageProps; + +export default FilterRailPage; diff --git a/examples/vite-app/src/routes.generated.ts b/examples/vite-app/src/routes.generated.ts index e29ab4a89..91ac3be8e 100644 --- a/examples/vite-app/src/routes.generated.ts +++ b/examples/vite-app/src/routes.generated.ts @@ -36,6 +36,7 @@ export type GeneratedRouteParams = { "/showcase/date-picker": {}; "/showcase/document-progress": {}; "/showcase/dropdown": {}; + "/showcase/filter-rail": {}; "/showcase/forms": {}; "/showcase/forms/zod-rhf": {}; "/showcase/grid": {}; diff --git a/packages/core/__snapshots__/src__components__filter-rail__filter-rail.test.tsx.snap b/packages/core/__snapshots__/src__components__filter-rail__filter-rail.test.tsx.snap new file mode 100644 index 000000000..1a14b4e08 --- /dev/null +++ b/packages/core/__snapshots__/src__components__filter-rail__filter-rail.test.tsx.snap @@ -0,0 +1,15 @@ +// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html + +exports[`FilterRail > snapshots > checkbox section with counts 1`] = `"
[]
"`; + +exports[`FilterRail > snapshots > comfortable density 1`] = `"
[]
"`; + +exports[`FilterRail > snapshots > compact density 1`] = `"
[]
"`; + +exports[`FilterRail > snapshots > numberRange section 1`] = `"
[{"field":"price","operator":"between","value":{"min":10,"max":200}}]
"`; + +exports[`FilterRail > snapshots > radio and boolean sections 1`] = `"
[{"field":"status","operator":"eq","value":"active"}]
"`; + +exports[`FilterRail > snapshots > text section 1`] = `"
[]
"`; + +exports[`FilterRail > snapshots > with Header and ClearAll 1`] = `"
[{"field":"category","operator":"in","value":["apparel"]}]
"`; diff --git a/packages/core/src/components/filter-rail/apply-layout.test.ts b/packages/core/src/components/filter-rail/apply-layout.test.ts new file mode 100644 index 000000000..92fc56899 --- /dev/null +++ b/packages/core/src/components/filter-rail/apply-layout.test.ts @@ -0,0 +1,140 @@ +import { describe, expect, it } from "vitest"; +import { + applyRailLayout, + EMPTY_RAIL_LAYOUT, + findRailProblems, + orderSections, + railFields, +} from "./apply-layout"; +import type { FilterRailSection } from "./types"; + +// 🧪 Dummy Data: one section of each shape the layout logic cares about +const sections: FilterRailSection[] = [ + { + id: "category", + label: "Category", + control: "checkbox", + field: "category", + options: [], + }, + { id: "status", label: "Status", control: "radio", field: "status", options: [] }, + { id: "search", label: "Search", control: "text", field: "name", operator: "contains" }, + { + id: "supplier", + label: "Supplier", + control: "custom", + fields: ["supplierId", "supplierRegion"], + render: () => null, + }, +]; + +const ids = (list: readonly { id: string }[]) => list.map((section) => section.id); + +describe("applyRailLayout", () => { + it("returns a copy of the authored sections without a layout", () => { + const result = applyRailLayout(sections, undefined); + expect(result).toEqual(sections); + expect(result).not.toBe(sections); + }); + + it("returns authored order for an empty layout", () => { + expect(ids(applyRailLayout(sections, EMPTY_RAIL_LAYOUT))).toEqual([ + "category", + "status", + "search", + "supplier", + ]); + }); + + it("orders ranked sections first, unranked keep authored order after them", () => { + const result = applyRailLayout(sections, { order: ["search", "status"], hidden: [], sort: {} }); + expect(ids(result)).toEqual(["search", "status", "category", "supplier"]); + }); + + it("ignores unknown ids in order", () => { + const result = applyRailLayout(sections, { + order: ["gone", "supplier"], + hidden: [], + sort: {}, + }); + expect(ids(result)).toEqual(["supplier", "category", "status", "search"]); + }); + + it("removes hidden sections", () => { + const result = applyRailLayout(sections, { + order: ["status"], + hidden: ["category", "status"], + sort: {}, + }); + expect(ids(result)).toEqual(["search", "supplier"]); + }); + + it("applies a sort override only to checkbox sections", () => { + const result = applyRailLayout(sections, { + order: [], + hidden: [], + sort: { category: "label", status: "label", search: "baselineCount" }, + }); + const category = result.find((section) => section.id === "category"); + const status = result.find((section) => section.id === "status"); + const search = result.find((section) => section.id === "search"); + expect(category).toMatchObject({ sort: "label" }); + expect(status).not.toHaveProperty("sort"); + expect(search).not.toHaveProperty("sort"); + // The authored section object is not mutated. + expect(sections[0]).not.toHaveProperty("sort"); + }); +}); + +describe("orderSections", () => { + it("is stable for sections sharing the same (missing) rank", () => { + const list = [{ id: "a" }, { id: "b" }, { id: "c" }, { id: "d" }]; + expect(ids(orderSections(list, ["c"]))).toEqual(["c", "a", "b", "d"]); + }); +}); + +describe("railFields", () => { + it("collects every field, including a custom section's declared fields", () => { + expect(railFields(sections)).toEqual( + new Set(["category", "status", "name", "supplierId", "supplierRegion"]), + ); + }); +}); + +describe("findRailProblems", () => { + it("reports nothing for a clean rail", () => { + expect(findRailProblems(sections)).toEqual([]); + }); + + it("reports duplicate section ids", () => { + const problems = findRailProblems([ + sections[0]!, + { id: "category", label: "Again", control: "radio", field: "other", options: [] }, + ]); + expect(problems).toEqual(['FilterRail: duplicate section id "category".']); + }); + + it("reports two sections on one field", () => { + const problems = findRailProblems([ + sections[0]!, + { id: "category2", label: "Category 2", control: "radio", field: "category", options: [] }, + ]); + expect(problems).toHaveLength(1); + expect(problems[0]).toContain('sections "category" and "category2" both filter "category"'); + }); + + it("reports a custom section claiming another section's field", () => { + const problems = findRailProblems([ + sections[1]!, + { + id: "custom", + label: "Custom", + control: "custom", + fields: ["status"], + render: () => null, + }, + ]); + expect(problems).toHaveLength(1); + expect(problems[0]).toContain('both filter "status"'); + }); +}); diff --git a/packages/core/src/components/filter-rail/apply-layout.ts b/packages/core/src/components/filter-rail/apply-layout.ts new file mode 100644 index 000000000..c4d7bd5ab --- /dev/null +++ b/packages/core/src/components/filter-rail/apply-layout.ts @@ -0,0 +1,96 @@ +import type { CheckboxSection, FilterRailSection, RadioSection, RailLayout } from "./types"; + +export const EMPTY_RAIL_LAYOUT: RailLayout = { order: [], hidden: [], sort: {} }; + +/** The fields a section writes. A custom section may own several. */ +export const sectionFields = ( + section: FilterRailSection, +): readonly TField[] => (section.control === "custom" ? section.fields : [section.field]); + +/** + * Every field the rail owns, so Clear all never touches filters it does not + * own (a page search box, a scope set elsewhere). + * + * Always computed from the **authored** sections: a hidden section still owns + * its field. + */ +export const railFields = ( + sections: readonly FilterRailSection[], +): Set => new Set(sections.flatMap((section) => sectionFields(section))); + +/** + * An option's count, read safely. Counts may come from a backend as plain JSON, + * so an option value such as "constructor" must not resolve to an inherited + * property. `undefined` map ⇒ unknown; a known map without the key ⇒ 0. + */ +export const countOf = ( + map: Readonly> | undefined, + value: string, +): number | undefined => { + if (!map) return undefined; + return Object.hasOwn(map, value) ? map[value] : 0; +}; + +/** Sections whose options can be counted — checkbox and radio. */ +export const hasOptions = ( + section: FilterRailSection, +): section is CheckboxSection | RadioSection => + section.control === "checkbox" || section.control === "radio"; + +/** Sections in the user's order. Unranked ids keep authored order at the end. */ +export const orderSections = ( + sections: readonly TSection[], + order: readonly string[], +): TSection[] => { + const rank = new Map(order.map((id, index) => [id, index])); + return sections + .map((section, index) => ({ section, index })) + .toSorted((a, b) => { + const ra = rank.get(a.section.id) ?? Number.POSITIVE_INFINITY; + const rb = rank.get(b.section.id) ?? Number.POSITIVE_INFINITY; + // `Infinity - Infinity` is NaN, so compare for equality first. + return ra === rb ? a.index - b.index : ra - rb; + }) + .map(({ section }) => section); +}; + +/** The authored sections, reordered / filtered / re-sorted by the user's layout. */ +export const applyRailLayout = ( + sections: readonly FilterRailSection[], + layout: RailLayout | undefined, +): FilterRailSection[] => { + if (!layout) return [...sections]; + const hidden = new Set(layout.hidden); + return orderSections( + sections.filter((section) => !hidden.has(section.id)), + layout.order, + ).map((section) => { + const chosen = layout.sort[section.id]; + return chosen && section.control === "checkbox" ? { ...section, sort: chosen } : section; + }); +}; + +/** + * Two sections on one field overwrite each other, because a field holds one + * filter. Returns the problems so the caller can warn once. + */ +export const findRailProblems = (sections: readonly FilterRailSection[]): string[] => { + const problems: string[] = []; + const seenId = new Set(); + const fieldOwner = new Map(); + for (const section of sections) { + if (seenId.has(section.id)) problems.push(`FilterRail: duplicate section id "${section.id}".`); + seenId.add(section.id); + for (const field of sectionFields(section)) { + const owner = fieldOwner.get(field); + if (owner && owner !== section.id) { + problems.push( + `FilterRail: sections "${owner}" and "${section.id}" both filter "${field}". ` + + "A field holds one filter, so they will overwrite each other.", + ); + } + fieldOwner.set(field, section.id); + } + } + return problems; +}; diff --git a/packages/core/src/components/filter-rail/controls.tsx b/packages/core/src/components/filter-rail/controls.tsx new file mode 100644 index 000000000..5f3d20b8d --- /dev/null +++ b/packages/core/src/components/filter-rail/controls.tsx @@ -0,0 +1,209 @@ +// Date, date-range and number-range controls. +// +// A field holds exactly one filter, so `gte` AND `lte` on one field is not +// expressible — a two-ended range commits a single `between` with +// `{ min, max }`, which also survives the URL round-trip unchanged. + +import { useState, type KeyboardEvent } from "react"; +import { parseDate, type DateValue } from "@internationalized/date"; +import { cn } from "@/lib/utils"; +import type { Filter } from "@/types/collection"; +import { DatePicker, DateRangePicker } from "../date-field"; +import { useFilterRailContext, sectionName } from "./filter-rail-context"; +import { useFilterRailT } from "./i18n"; +import { inputClass } from "./internals"; +import { filterFor } from "./sections"; +import type { DateRangeSection, DateSection, NumberRangeSection } from "./types"; + +/** `YYYY-MM-DD` ⇄ `DateValue`. A malformed stored value renders empty rather than throwing. */ +const toDateValue = (iso: unknown): DateValue | null => { + if (typeof iso !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(iso)) return null; + try { + return parseDate(iso); + } catch { + return null; + } +}; + +const isoOf = (value: DateValue | null | undefined) => (value ? value.toString() : null); + +// ─── Date ──────────────────────────────────────────────────────────────────── + +export const DateControl = ({ section }: { section: DateSection }) => { + const { control, commit } = useFilterRailContext("Sections"); + const value = toDateValue(filterFor(control.filters, section.field)?.value); + + return ( + { + const iso = isoOf(next); + commit( + section.field, + iso ? { field: section.field, operator: section.operator, value: iso } : null, + ); + }} + /> + ); +}; + +// ─── Date range ────────────────────────────────────────────────────────────── + +export const DateRangeControl = ({ section }: { section: DateRangeSection }) => { + const { control, commit } = useFilterRailContext("Sections"); + const bounds = filterFor(control.filters, section.field)?.value as + | { min?: string; max?: string } + | undefined; + const start = toDateValue(bounds?.min); + const end = toDateValue(bounds?.max); + + const apply = (from: string | null, to: string | null) => + commit( + section.field, + from && to + ? { field: section.field, operator: "between", value: { min: from, max: to } } + : null, + ); + + return ( +
+ {section.presets && section.presets.length > 0 && ( +
+ {section.presets.map((preset) => { + const active = bounds?.min === preset.from && bounds?.max === preset.to; + return ( + + ); + })} +
+ )} + apply(isoOf(next?.start), isoOf(next?.end))} + /> +
+ ); +}; + +// ─── Number range ──────────────────────────────────────────────────────────── + +type Bounds = { min?: number; max?: number }; + +const num = (value: unknown) => { + if (value === undefined || value === null || value === "") return undefined; + const parsed = Number(value); + return Number.isNaN(parsed) ? undefined : parsed; +}; + +const show = (value: number | undefined) => (value === undefined ? "" : String(value)); + +/** `between` carries both ends; a half-open range is a single `gte` or `lte`. */ +const readBounds = (filter: Filter | undefined): Bounds => { + if (!filter) return {}; + if (filter.operator === "gte") return { min: num(filter.value) }; + if (filter.operator === "lte") return { max: num(filter.value) }; + const value = (filter.value ?? {}) as { min?: unknown; max?: unknown }; + return { min: num(value.min), max: num(value.max) }; +}; + +const rangeFilter = (field: string, min?: number, max?: number): Filter | null => { + if (min !== undefined && max !== undefined) { + return { field, operator: "between", value: { min, max } }; + } + if (min !== undefined) return { field, operator: "gte", value: min }; + if (max !== undefined) return { field, operator: "lte", value: max }; + return null; +}; + +export const NumberRangeControl = ({ section }: { section: NumberRangeSection }) => { + const t = useFilterRailT(); + const { control, commit } = useFilterRailContext("Sections"); + const bounds = readBounds(filterFor(control.filters, section.field)); + + // Local drafts: commit on blur / Enter, not per keystroke. Re-synced during + // render when the applied filter changes (Clear all, a shared URL). + const [from, setFrom] = useState(show(bounds.min)); + const [to, setTo] = useState(show(bounds.max)); + const boundsKey = `${bounds.min}|${bounds.max}`; + const [synced, setSynced] = useState(boundsKey); + if (synced !== boundsKey) { + setSynced(boundsKey); + setFrom(show(bounds.min)); + setTo(show(bounds.max)); + } + + const apply = () => { + let lo = num(from.trim()); + let hi = num(to.trim()); + // Ends typed the wrong way round mean the same range, not an empty one. + if (lo !== undefined && hi !== undefined && lo > hi) [lo, hi] = [hi, lo]; + if (lo === bounds.min && hi === bounds.max) { + // Nothing to commit, but show the normalised ends. + setFrom(show(lo)); + setTo(show(hi)); + return; + } + commit(section.field, rangeFilter(section.field, lo, hi)); + }; + + const name = sectionName(section); + const shared = { + type: "number", + inputMode: "decimal" as const, + min: section.min, + max: section.max, + step: section.step, + onBlur: apply, + onKeyDown: (event: KeyboardEvent) => { + if (event.key === "Enter") apply(); + }, + className: inputClass, + }; + + return ( +
+ setFrom(event.target.value)} + /> + + {t("rangeTo")} + + setTo(event.target.value)} + /> + {section.unit && ( + + {section.unit} + + )} +
+ ); +}; diff --git a/packages/core/src/components/filter-rail/filter-rail-context.ts b/packages/core/src/components/filter-rail/filter-rail-context.ts new file mode 100644 index 000000000..26f58b9cc --- /dev/null +++ b/packages/core/src/components/filter-rail/filter-rail-context.ts @@ -0,0 +1,59 @@ +import { createContext, useContext } from "react"; +import type { CollectionControl, Filter } from "@/types/collection"; +import type { FacetCounts, FilterRailSection, RailLayoutBinding } from "./types"; + +/** + * Everything the parts share. String-keyed on purpose: `TField` is narrowed at + * the `Root` boundary, and nothing inside varies on it. + */ +export type FilterRailContextValue = { + control: CollectionControl; + /** The authored sections, including ones the user has hidden. */ + sections: readonly FilterRailSection[]; + counts: FacetCounts | undefined; + layout: RailLayoutBinding | undefined; + zeroBehavior: "disable" | "show"; + density: "compact" | "comfortable"; + /** Fields the rail owns. */ + owned: ReadonlySet; + /** Active filters on owned fields. */ + activeCount: number; + /** Section ids that currently carry a filter. */ + filteredSections: ReadonlySet; + /** Replace (or remove) the filter on one field — the rail's single mutation path. */ + commit: (field: string, next: Filter | null) => void; + /** Remove the filters on these fields in one `setFilters`. */ + clearFields: (fields: readonly string[]) => void; + clearAll: () => void; + + // Narrow-screen form + /** Below `lg`: the rail lives in a sheet behind a button. */ + compact: boolean; + sheetOpen: boolean; + setSheetOpen: (open: boolean) => void; + /** Whether a `FilterRail.Trigger` is mounted, so Root skips its fallback button. */ + hasTrigger: boolean; + /** Called by `FilterRail.Trigger` on mount; returns the unregister function. */ + registerTrigger: () => () => void; +}; + +export const FilterRailContext = createContext(null); + +export function useFilterRailContext(part: string): FilterRailContextValue { + const context = useContext(FilterRailContext); + if (!context) { + throw new Error( + ` must be rendered inside or .`, + ); + } + return context; +} + +/** For Root, which provides the context itself when no Provider is above it. */ +export const useOptionalFilterRailContext = () => useContext(FilterRailContext); + +/** A plain-text name for a section, for aria-labels and messages. */ +export const sectionName = (section: FilterRailSection): string => + typeof section.label === "string" || typeof section.label === "number" + ? String(section.label) + : section.id; diff --git a/packages/core/src/components/filter-rail/filter-rail.test-d.tsx b/packages/core/src/components/filter-rail/filter-rail.test-d.tsx new file mode 100644 index 000000000..6217ddcbe --- /dev/null +++ b/packages/core/src/components/filter-rail/filter-rail.test-d.tsx @@ -0,0 +1,59 @@ +/** + * Vitest type tests for `FilterRail`'s field typing and Root/Provider config. + * + * To run: `pnpm test` + */ + +import { describe, expectTypeOf, it } from "vitest"; +import type { CollectionControl } from "@/types/collection"; +import { FilterRail, type FilterRailRootProps, type FilterRailSection } from "./index"; + +type Field = "category" | "status"; + +declare const control: CollectionControl; + +describe("FilterRail types", () => { + it("accepts sections whose field belongs to the control", () => { + const sections: FilterRailSection[] = [ + { id: "category", label: "Category", control: "checkbox", field: "category", options: [] }, + ]; + + + ; + }); + + it("rejects a misspelled field", () => { + const sections: FilterRailSection[] = [ + // @ts-expect-error — "categroy" is not a field of the control + { id: "category", label: "Category", control: "checkbox", field: "categroy", options: [] }, + ]; + expectTypeOf(sections).toBeArray(); + }); + + it("types a custom section's fields and setFilter", () => { + const section: FilterRailSection = { + id: "custom", + label: "Custom", + control: "custom", + fields: ["status"], + render: ({ setFilter }) => { + setFilter("status", { operator: "eq", value: "active" }); + // @ts-expect-error — unknown field + setFilter("warehouse", null); + return null; + }, + }; + expectTypeOf(section).not.toBeAny(); + }); + + it("requires both control and sections when Root is standalone", () => { + // @ts-expect-error — `sections` is missing + const missing: FilterRailRootProps = { control, children: null }; + expectTypeOf(missing).not.toBeAny(); + }); + + it("allows a Root with no config (inside a Provider)", () => { + const inside: FilterRailRootProps = { children: null }; + expectTypeOf(inside).not.toBeAny(); + }); +}); diff --git a/packages/core/src/components/filter-rail/filter-rail.test.tsx b/packages/core/src/components/filter-rail/filter-rail.test.tsx new file mode 100644 index 000000000..1e6273e62 --- /dev/null +++ b/packages/core/src/components/filter-rail/filter-rail.test.tsx @@ -0,0 +1,1002 @@ +import { useMemo, useState, type ReactNode } from "react"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import { act, cleanup, fireEvent, render, screen, within } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +import type { CollectionControl, Filter } from "@/types/collection"; +import { ClearAll, Header, Provider, Root, Sections } from "./filter-rail"; +import { Trigger } from "./responsive"; +import { Settings } from "./settings"; +import type { FacetCounts, FilterRailConfig, FilterRailSection, RailLayout } from "./types"; + +afterEach(() => { + cleanup(); + vi.useRealTimers(); + vi.restoreAllMocks(); +}); + +// ─── Harness ───────────────────────────────────────────────────────────────── + +const makeControl = ( + filters: Filter[], + setFilters: (next: Filter[]) => void, +): CollectionControl => ({ + filters, + setFilters, + addFilter: vi.fn(), + removeFilter: vi.fn(), + clearFilters: vi.fn(), + sortStates: [], + setSort: vi.fn(), + clearSort: vi.fn(), + pageSize: 20, + setPageSize: vi.fn(), + goToNextPage: vi.fn(), + goToPrevPage: vi.fn(), + resetPage: vi.fn(), + goToFirstPage: vi.fn(), + goToLastPage: vi.fn(), + getHasPrevPage: vi.fn(() => false), + getHasNextPage: vi.fn(() => false), + resetCount: 0, +}); + +type HarnessProps = Omit & { + "aria-label"?: string; + className?: string; + initial?: Filter[]; + initialLayout?: RailLayout; + onLayoutChange?: (next: RailLayout) => void; + children?: ReactNode; +}; + +function Harness({ + initial = [], + initialLayout, + onLayoutChange, + children, + ...rootProps +}: HarnessProps) { + const [filters, setFilters] = useState(initial); + const [layoutValue, setLayoutValue] = useState(initialLayout); + const control = useMemo(() => makeControl(filters, setFilters), [filters]); + const layout = layoutValue + ? { + value: layoutValue, + onChange: (next: RailLayout) => { + onLayoutChange?.(next); + setLayoutValue(next); + }, + } + : undefined; + return ( + <> + + {children ?? } + + 
{JSON.stringify(filters)}
+ + ); +} + +/** + * The option's checkbox. Queried by row rather than accessible name: Base UI + * adds `aria-labelledby` pointing at the wrapping