@connextar/house 0.5.1 → 0.6.0

package/README.md

@@ -491,6 +491,75 @@ module to React and its icons — no router, no toast library, no design system
 because the moment it reaches for one of those, the claim that six apps can host
 it stops being true.
 
+### `@connextar/house/grid`
+
+Search, sorting, per-column filters, column visibility, saved views and paging
+for a list screen — the arithmetic, with no markup in it.
+
+This is the rule's second clause again, and the clearest case since `ux`: three
+apps had written the same list behaviour three times. FB's grids sit on TanStack
+Table with sticky columns and a context menu; AltEd hand-rolled the same
+behaviour over its own `Column<T>`; PharmaLine had four hand-written `<table>`s
+with one search box between them. What actually differed was entirely the
+rendering. What was identical — and repeatedly wrong in small ways — was the
+arithmetic underneath: which rows match, in what order, on which page.
+
+Two of those small ways are worth naming, because both are in here now and
+neither is obvious. A plain string sort files every "Year 1x" before "Year 2",
+which reads as a broken table rather than a subtle one, so ordering goes through
+an `Intl.Collator` with `numeric` and `sensitivity: "base"`. And filtering a list
+while on page 4 strands the reader on a page that no longer exists — clamped
+when the page is derived, not corrected afterwards by an effect, which rendered
+the empty page once before putting it right.
+
+There is deliberately no table here. Each app already has its own table
+primitives and its own look, and bringing a second design system into an app
+that has one is the cost this package exists to avoid. So a host declares
+columns that extend `GridColumnSpec` with whatever its own table needs, and gets
+the same objects back:
+
+```tsx
+interface Column<T> extends GridColumnSpec<T> {
+  header: ReactNode;
+  cell: (row: T) => ReactNode;
+  numeric?: boolean;
+}
+
+const columns: Column<Patient>[] = [
+  { key: "name", header: "Name", label: "Name", cell: (p) => p.name, sortValue: (p) => p.name },
+  // `filterValue` is what offers the column a filter — and only when the rows
+  // hold more than one distinct value, since a filter with one option is clutter.
+  {
+    key: "status",
+    header: "Status",
+    label: "Status",
+    cell: (p) => <Badge>{p.status}</Badge>,
+    sortValue: (p) => p.status,
+    filterValue: (p) => p.status,
+  },
+];
+
+const grid = useGrid({ rows, columns, storageKey: "patients", initialSort: { key: "name", direction: "asc" } });
+```
+
+`grid.rows` is the page to render and `grid.visibleColumns` the columns to draw;
+`grid.matched` is everything the search and filters kept, for a total or a bulk
+action. `storageKey` is what lets column choices be remembered — in the browser,
+through `useHiddenColumns`, which is exported separately so a grid paging on the
+server keeps the same behaviour and the same stored choice.
+
+`GridController` is the contract a toolbar needs, and `useGrid` is only one thing
+that satisfies it: an app whose list is too long to send in one response drives
+the same search box, filter menus, column picker and saved-views menu from its
+own server-backed hook, and the UI cannot tell.
+
+`GridViewState` is what a saved view holds. It is written somewhere and read back
+later, possibly by a newer build, so `parseGridView` repairs rather than trusts:
+a view saved before `pageSize` existed is still a valid view, and one stale
+filter is dropped rather than throwing when the menu entry is picked. Where views
+are stored — a table keyed by account, or the browser — is the app's decision,
+because only the app knows whether a view should follow someone to their phone.
+
 ### Styles — `@connextar/house/house.css`
 
 What the components need that utility classes cannot say: rich text, the editor's

package/dist/grid/columns.d.ts

@@ -0,0 +1,47 @@
+import type { GridValue } from "./compare.js";
+/**
+ * What the engine needs to know about a column — and nothing more.
+ *
+ * Deliberately free of `header`, `cell` and every other presentational field:
+ * the engine never renders anything, and each app's table already has its own
+ * column type with its own look. Hosts extend this interface and hand their own
+ * columns in; `useGrid` is generic over that type and gives the same objects
+ * back in `visibleColumns`, so nothing has to be mapped on the way through.
+ */
+export interface GridColumnSpec<T> {
+    /** Stable identity, used by sorting, filters, saved views and column choices. */
+    key: string;
+    /**
+     * Plain-text name for the column menu and the filter label. Falls back to
+     * `key` — which is a poor label, so hosts with a string header should pass it.
+     */
+    label?: string;
+    /**
+     * The underlying value, for sorting and for matching a search term.
+     *
+     * A cell renders arbitrary markup, which cannot be sorted or searched, so a
+     * column that wants either has to say what it actually holds. Declaring this
+     * is also what makes a column sortable at all — better than sorting by
+     * something meaningless.
+     */
+    sortValue?: (row: T) => GridValue;
+    /**
+     * A short, repeating label — a status, a type, a person — offered as a filter
+     * on the column. Only offered when the rows hold more than one distinct
+     * value: a filter with a single option is clutter.
+     */
+    filterValue?: (row: T) => string | null | undefined;
+    /**
+     * Keep this column out of the global search. Use it for a column whose value
+     * is an opaque id or a duplicate of another column's — matches against it
+     * confuse more than they help.
+     */
+    unsearchable?: boolean;
+}
+/** A column's distinct values, offered as a filter. */
+export interface GridFacet {
+    key: string;
+    label: string;
+    values: string[];
+}
+//# sourceMappingURL=columns.d.ts.map

package/dist/grid/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../../src/grid/columns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,SAAS,CAAC;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACpD;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,uDAAuD;AACvD,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB"}

package/dist/grid/columns.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=columns.js.map

package/dist/grid/columns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.js","sourceRoot":"","sources":["../../src/grid/columns.ts"],"names":[],"mappings":""}

package/dist/grid/compare.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Ordering two cell values the way a reader expects them.
+ *
+ * Extracted from AltEd, where the rule was learnt the hard way: a plain string
+ * comparison reads digits one character at a time and files every "Year 1x"
+ * before "Year 2", which looks exactly like a broken sort rather than a subtle
+ * one. `numeric` fixes that; `sensitivity: "base"` folds case and accents so
+ * "bertie" does not sort after "Cai".
+ */
+/** What a column contributes to sorting. Anything else is the host's business. */
+export type GridValue = string | number | Date | null | undefined;
+/** Order two labels the way a reader expects. Nullish sorts as an empty string. */
+export declare function compareValues(a: GridValue, b: GridValue): number;
+/** Compare two plain labels — for the value lists inside a column's filter. */
+export declare function compareLabels(a: string, b: string): number;
+//# sourceMappingURL=compare.d.ts.map

package/dist/grid/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../src/grid/compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;AAIlE,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAOhE;AAED,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/grid/compare.js

@@ -0,0 +1,31 @@
+/**
+ * Ordering two cell values the way a reader expects them.
+ *
+ * Extracted from AltEd, where the rule was learnt the hard way: a plain string
+ * comparison reads digits one character at a time and files every "Year 1x"
+ * before "Year 2", which looks exactly like a broken sort rather than a subtle
+ * one. `numeric` fixes that; `sensitivity: "base"` folds case and accents so
+ * "bertie" does not sort after "Cai".
+ */
+const collator = new Intl.Collator("en-GB", { numeric: true, sensitivity: "base" });
+/** Order two labels the way a reader expects. Nullish sorts as an empty string. */
+export function compareValues(a, b) {
+    const left = normalise(a);
+    const right = normalise(b);
+    if (typeof left === "number" && typeof right === "number") {
+        return left === right ? 0 : left < right ? -1 : 1;
+    }
+    return collator.compare(String(left), String(right));
+}
+/** Compare two plain labels — for the value lists inside a column's filter. */
+export function compareLabels(a, b) {
+    return collator.compare(a, b);
+}
+function normalise(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (value instanceof Date)
+        return value.getTime();
+    return value;
+}
+//# sourceMappingURL=compare.js.map

package/dist/grid/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/grid/compare.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAC;AAEpF,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,CAAY,EAAE,CAAY;IACtD,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC1B,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC1D,OAAO,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,OAAO,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,SAAS,CAAC,KAAgB;IACjC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,IAAI,KAAK,YAAY,IAAI;QAAE,OAAO,KAAK,CAAC,OAAO,EAAE,CAAC;IAClD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/grid/hidden-columns.d.ts

@@ -0,0 +1,8 @@
+export interface HiddenColumns {
+    hiddenColumns: string[];
+    setHidden: (next: string[]) => void;
+    toggleColumn: (key: string) => void;
+    showAllColumns: () => void;
+}
+export declare function useHiddenColumns(grid: string | undefined): HiddenColumns;
+//# sourceMappingURL=hidden-columns.d.ts.map

package/dist/grid/hidden-columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-columns.d.ts","sourceRoot":"","sources":["../../src/grid/hidden-columns.ts"],"names":[],"mappings":"AAoDA,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACpC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAmCxE"}

package/dist/grid/hidden-columns.js

@@ -0,0 +1,81 @@
+"use client";
+import { useState, useSyncExternalStore } from "react";
+/**
+ * Which columns the reader has switched off, remembered per grid.
+ *
+ * Kept separate from the engine so a grid driven by the server — paging and
+ * filtering in the database rather than in the browser — keeps the same
+ * behaviour and the same stored choice. The store belongs to the browser, not
+ * to whichever hook happens to be driving the table.
+ */
+/** Shared empty array: `useSyncExternalStore` compares snapshots by identity. */
+const NONE = [];
+const storeKey = (grid) => `cx-grid:${grid}:hidden`;
+// Parsing yields a fresh array each call, which would look like a new snapshot
+// on every render, so the parse is cached against the text it came from.
+const cache = new Map();
+function read(grid) {
+    if (!grid)
+        return NONE;
+    let raw = null;
+    try {
+        raw = window.localStorage.getItem(storeKey(grid));
+    }
+    catch {
+        // A blocked store is not worth breaking the grid over.
+    }
+    const cached = cache.get(grid);
+    if (cached && cached.raw === raw)
+        return cached.value;
+    let value = NONE;
+    try {
+        if (raw) {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                value = parsed.filter((key) => typeof key === "string");
+        }
+    }
+    catch {
+        // A corrupt entry reads as "nothing hidden".
+    }
+    cache.set(grid, { raw, value });
+    return value;
+}
+/** Another tab changing the saved columns should move this one too. */
+function subscribe(onChange) {
+    window.addEventListener("storage", onChange);
+    return () => window.removeEventListener("storage", onChange);
+}
+export function useHiddenColumns(grid) {
+    /**
+     * Read through `useSyncExternalStore` rather than copied into state by an
+     * effect — an effect meant one render with every column showing and a second
+     * with the reader's choice. `chosen` wins once they pick, which is also what
+     * keeps the control working where the store is blocked.
+     */
+    const stored = useSyncExternalStore(subscribe, () => read(grid), () => NONE);
+    const [chosen, setChosen] = useState(null);
+    const hiddenColumns = chosen ?? stored;
+    function setHidden(next) {
+        setChosen(next);
+        if (!grid)
+            return;
+        try {
+            window.localStorage.setItem(storeKey(grid), JSON.stringify(next));
+        }
+        catch {
+            // Ignore — the choice just will not survive a reload.
+        }
+    }
+    return {
+        hiddenColumns,
+        setHidden,
+        toggleColumn(key) {
+            setHidden(hiddenColumns.includes(key) ? hiddenColumns.filter((k) => k !== key) : [...hiddenColumns, key]);
+        },
+        showAllColumns() {
+            setHidden([]);
+        },
+    };
+}
+//# sourceMappingURL=hidden-columns.js.map

package/dist/grid/hidden-columns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-columns.js","sourceRoot":"","sources":["../../src/grid/hidden-columns.ts"],"names":[],"mappings":"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"}

package/dist/grid/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@connextar/house/grid` — the arithmetic behind a list screen.
+ *
+ * Search, sorting, per-column filters, column visibility, saved views and
+ * paging, with no markup and no design system in them: React, and nothing else.
+ * Every app already has its own table primitives and its own look, so what it
+ * gets from here is the behaviour, not the appearance — the same bargain the
+ * error shell and the wizard offer.
+ *
+ * A host declares columns that extend `GridColumnSpec` with whatever its own
+ * table needs (`header`, `cell`, alignment, an inline editor) and hands them
+ * straight in; `useGrid` is generic over that type and returns the same objects
+ * in `visibleColumns`, so nothing is mapped on the way through.
+ */
+export type { GridColumnSpec, GridFacet } from "./columns.js";
+export { compareLabels, compareValues, type GridValue } from "./compare.js";
+export { useHiddenColumns, type HiddenColumns } from "./hidden-columns.js";
+export { DEFAULT_PAGE_SIZE, useGrid, type Grid, type GridController, type GridSort, type SortDirection, type UseGridOptions, } from "./use-grid.js";
+export { EMPTY_VIEW, parseGridView, type GridViewState } from "./views.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/grid/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/grid/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,OAAO,EACP,KAAK,IAAI,EACT,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/grid/index.js

@@ -0,0 +1,5 @@
+export { compareLabels, compareValues } from "./compare.js";
+export { useHiddenColumns } from "./hidden-columns.js";
+export { DEFAULT_PAGE_SIZE, useGrid, } from "./use-grid.js";
+export { EMPTY_VIEW, parseGridView } from "./views.js";
+//# sourceMappingURL=index.js.map

package/dist/grid/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/grid/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,aAAa,EAAE,aAAa,EAAkB,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAsB,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,OAAO,GAMR,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAsB,MAAM,YAAY,CAAC"}

package/dist/grid/use-grid.d.ts

@@ -0,0 +1,86 @@
+import type { GridColumnSpec, GridFacet } from "./columns.js";
+import type { GridViewState } from "./views.js";
+/**
+ * Search, sort, filter, hide columns and paginate one list — the behaviour
+ * every list screen in the portfolio should have and, before this, three apps
+ * had written three times.
+ *
+ * It is a hook over the host's own column type rather than a table library,
+ * because the thing that differs between those three apps is entirely the
+ * rendering: the cells hold arbitrary markup, each has its own table
+ * primitives, and adopting a library would mean rewriting every call site's
+ * column API to arrive at the same arithmetic. So the arithmetic is here and
+ * the markup stays where it belongs.
+ *
+ * Everything is client-side. These lists arrive already scoped to the signed-in
+ * account, so there is nothing to gain from another round trip and a great deal
+ * to gain from a filter that answers as it is typed. A list long enough to need
+ * server-side paging should drive `GridController` from its own hook instead —
+ * the toolbar contract below is what makes that swap invisible to the UI.
+ */
+export type SortDirection = "asc" | "desc";
+export interface GridSort {
+    key: string;
+    direction: SortDirection;
+}
+export declare const DEFAULT_PAGE_SIZE = 25;
+/**
+ * What a toolbar needs from whichever hook is driving a table.
+ *
+ * `useGrid` satisfies it, and so can an app's own server-driven hook, which is
+ * what lets the search box, filter menus, column picker and saved views be
+ * written once and behave identically either way.
+ */
+export interface GridController {
+    query: string;
+    setQuery: (next: string) => void;
+    sort: GridSort | null;
+    toggleSort: (key: string) => void;
+    facetOptions: GridFacet[];
+    facets: Record<string, string[]>;
+    toggleFacet: (key: string, value: string) => void;
+    clearFacet: (key: string) => void;
+    activeFacetCount: number;
+    isFiltered: boolean;
+    reset: () => void;
+    total: number;
+    hiddenColumns: string[];
+    toggleColumn: (key: string) => void;
+    showAllColumns: () => void;
+    viewState: GridViewState;
+    applyView: (view: GridViewState) => void;
+}
+export interface UseGridOptions<T, C extends GridColumnSpec<T>> {
+    rows: T[];
+    columns: C[];
+    /** How the list is ordered before anyone touches a header. */
+    initialSort?: GridSort;
+    /** A pre-filled search term — how a deep link lands on one row. */
+    initialQuery?: string;
+    pageSize?: number;
+    /** Extra text per row to match on, for values no column displays. */
+    searchExtra?: (row: T) => string | null | undefined;
+    /**
+     * Identifies this grid so column choices can be remembered and saved views
+     * can be filed against it. Without one the grid still works; it just forgets.
+     */
+    storageKey?: string;
+}
+export interface Grid<T, C extends GridColumnSpec<T>> extends GridController {
+    /** The rows to render: this page of the searched, filtered, sorted list. */
+    rows: T[];
+    /** Everything matching the search and filters, before paging. */
+    matched: T[];
+    /** Render these, not the full set — respects what the reader switched off. */
+    visibleColumns: C[];
+    page: number;
+    setPage: (page: number) => void;
+    pageCount: number;
+    pageSize: number;
+    setPageSize: (size: number) => void;
+    /** 1-based index of the first row on this page; 0 when there are none. */
+    from: number;
+    to: number;
+}
+export declare function useGrid<T, C extends GridColumnSpec<T> = GridColumnSpec<T>>({ rows, columns, initialSort, initialQuery, pageSize: initialPageSize, searchExtra, storageKey, }: UseGridOptions<T, C>): Grid<T, C>;
+//# sourceMappingURL=use-grid.d.ts.map

package/dist/grid/use-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-grid.d.ts","sourceRoot":"","sources":["../../src/grid/use-grid.ts"],"names":[],"mappings":"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"}

package/dist/grid/use-grid.js

@@ -0,0 +1,157 @@
+"use client";
+import { useMemo, useState } from "react";
+import { compareLabels, compareValues } from "./compare.js";
+import { useHiddenColumns } from "./hidden-columns.js";
+export const DEFAULT_PAGE_SIZE = 25;
+export function useGrid({ rows, columns, initialSort, initialQuery, pageSize: initialPageSize = DEFAULT_PAGE_SIZE, searchExtra, storageKey, }) {
+    const [query, setQuery] = useState(initialQuery ?? "");
+    const [sort, setSort] = useState(initialSort ?? null);
+    const [facets, setFacets] = useState({});
+    const [pageSize, setPageSizeState] = useState(initialPageSize);
+    const [requestedPage, setPage] = useState(1);
+    const { hiddenColumns, setHidden, toggleColumn, showAllColumns } = useHiddenColumns(storageKey);
+    /** The columns actually rendered, in declared order. */
+    const visibleColumns = useMemo(() => columns.filter((column) => !hiddenColumns.includes(column.key)), [columns, hiddenColumns]);
+    /** Columns that opted into a filter, with the distinct values they hold. */
+    const facetOptions = useMemo(() => columns
+        .filter((column) => column.filterValue)
+        .map((column) => ({
+        key: column.key,
+        label: column.label ?? column.key,
+        values: [
+            ...new Set(rows.map((row) => column.filterValue?.(row)).filter((v) => Boolean(v))),
+        ].sort(compareLabels),
+    }))
+        .filter((facet) => facet.values.length > 1), [columns, rows]);
+    const matched = useMemo(() => {
+        const term = query.trim().toLowerCase();
+        const filtered = rows.filter((row) => {
+            // Every active filter must match — narrowing, not widening.
+            for (const [key, kept] of Object.entries(facets)) {
+                if (kept.length === 0)
+                    continue;
+                const column = columns.find((c) => c.key === key);
+                const value = column?.filterValue?.(row);
+                if (!value || !kept.includes(value))
+                    return false;
+            }
+            if (!term)
+                return true;
+            const haystack = [...columns.filter((c) => !c.unsearchable).map((c) => valueOf(c, row)), searchExtra?.(row)]
+                .filter((value) => value !== null && value !== undefined)
+                .map((value) => (value instanceof Date ? value.toISOString() : String(value)))
+                .join(" ")
+                .toLowerCase();
+            return haystack.includes(term);
+        });
+        if (!sort)
+            return filtered;
+        const column = columns.find((c) => c.key === sort.key);
+        const sortValue = column?.sortValue;
+        if (!sortValue)
+            return filtered;
+        // Copy before sorting: the caller's array is not ours to reorder.
+        return [...filtered].sort((a, b) => {
+            const result = compareValues(sortValue(a), sortValue(b));
+            return sort.direction === "asc" ? result : -result;
+        });
+    }, [rows, columns, query, facets, searchExtra, sort]);
+    const total = matched.length;
+    const pageCount = Math.max(1, Math.ceil(total / pageSize));
+    // Never strand someone on a page that no longer exists after a filter.
+    // Clamped here rather than corrected from an effect, which rendered the
+    // empty page once before putting it right.
+    const page = Math.min(requestedPage, pageCount);
+    const pageRows = useMemo(() => matched.slice((page - 1) * pageSize, page * pageSize), [matched, page, pageSize]);
+    /** Cycle a column: ascending → descending → unsorted. */
+    function toggleSort(key) {
+        setSort((current) => {
+            if (current?.key !== key)
+                return { key, direction: "asc" };
+            if (current.direction === "asc")
+                return { key, direction: "desc" };
+            return null;
+        });
+    }
+    /** A new search starts at the beginning of the results, not on page 4. */
+    function search(next) {
+        setQuery(next);
+        setPage(1);
+    }
+    function toggleFacet(key, value) {
+        setPage(1);
+        setFacets((current) => {
+            const kept = current[key] ?? [];
+            const next = kept.includes(value) ? kept.filter((v) => v !== value) : [...kept, value];
+            if (next.length === 0)
+                return withoutKey(current, key);
+            return { ...current, [key]: next };
+        });
+    }
+    function clearFacet(key) {
+        setPage(1);
+        setFacets((current) => withoutKey(current, key));
+    }
+    function setPageSize(size) {
+        setPageSizeState(size);
+        setPage(1);
+    }
+    const activeFacetCount = Object.values(facets).reduce((sum, values) => sum + values.length, 0);
+    const isFiltered = query.trim().length > 0 || activeFacetCount > 0;
+    function reset() {
+        setQuery("");
+        setFacets({});
+        setPage(1);
+    }
+    /** Restore a saved view: search, sort, filters and columns together. */
+    function applyView(view) {
+        setQuery(view.query);
+        setSort(view.sort);
+        setFacets(view.facets);
+        setHidden(view.hiddenColumns);
+        if (view.pageSize)
+            setPageSizeState(view.pageSize);
+        setPage(1);
+    }
+    return {
+        rows: pageRows,
+        matched,
+        total,
+        query,
+        setQuery: search,
+        sort,
+        toggleSort,
+        facetOptions,
+        facets,
+        toggleFacet,
+        clearFacet,
+        activeFacetCount,
+        isFiltered,
+        reset,
+        visibleColumns,
+        hiddenColumns,
+        toggleColumn,
+        showAllColumns,
+        viewState: { query, sort, facets, hiddenColumns, pageSize },
+        applyView,
+        page,
+        setPage,
+        pageCount,
+        pageSize,
+        setPageSize,
+        from: total === 0 ? 0 : (page - 1) * pageSize + 1,
+        to: Math.min(page * pageSize, total),
+    };
+}
+/** The value a column contributes to the search haystack. */
+function valueOf(column, row) {
+    if (column.sortValue)
+        return column.sortValue(row);
+    if (column.filterValue)
+        return column.filterValue(row);
+    return undefined;
+}
+function withoutKey(facets, key) {
+    return Object.fromEntries(Object.entries(facets).filter(([candidate]) => candidate !== key));
+}
+//# sourceMappingURL=use-grid.js.map

package/dist/grid/use-grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-grid.js","sourceRoot":"","sources":["../../src/grid/use-grid.ts"],"names":[],"mappings":"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"}

package/dist/grid/views.d.ts

@@ -0,0 +1,30 @@
+import type { GridSort } from "./use-grid.js";
+/**
+ * Everything a saved view captures: how the list was searched, ordered,
+ * filtered and which columns were showing.
+ *
+ * This shape is written to a database or a browser store and read back later,
+ * possibly by a newer version of the app, so it is validated on the way in
+ * rather than trusted. A view saved before `pageSize` existed is still a valid
+ * view — every field is checked independently and a bad one is dropped, which
+ * is why this returns a repaired state rather than a boolean.
+ */
+export interface GridViewState {
+    query: string;
+    sort: GridSort | null;
+    /** Column key → the values kept. An absent key means "all values". */
+    facets: Record<string, string[]>;
+    hiddenColumns: string[];
+    /** Rows per page, when the view was saved with one. */
+    pageSize?: number;
+}
+export declare const EMPTY_VIEW: GridViewState;
+/**
+ * Read a stored view, keeping what is intelligible and discarding what is not.
+ *
+ * Returns `null` only when the input is not an object at all. A partly corrupt
+ * view is worth more than no view: losing one stale filter is a smaller failure
+ * than a menu entry that throws when picked.
+ */
+export declare function parseGridView(input: unknown): GridViewState | null;
+//# sourceMappingURL=views.d.ts.map

package/dist/grid/views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.d.ts","sourceRoot":"","sources":["../../src/grid/views.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACjC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,UAAU,EAAE,aAAwE,CAAC;AAElG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAalE"}

package/dist/grid/views.js

@@ -0,0 +1,51 @@
+export const EMPTY_VIEW = { query: "", sort: null, facets: {}, hiddenColumns: [] };
+/**
+ * Read a stored view, keeping what is intelligible and discarding what is not.
+ *
+ * Returns `null` only when the input is not an object at all. A partly corrupt
+ * view is worth more than no view: losing one stale filter is a smaller failure
+ * than a menu entry that throws when picked.
+ */
+export function parseGridView(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return null;
+    const raw = input;
+    return {
+        query: typeof raw.query === "string" ? raw.query : "",
+        sort: parseSort(raw.sort),
+        facets: parseFacets(raw.facets),
+        hiddenColumns: parseStrings(raw.hiddenColumns),
+        ...(typeof raw.pageSize === "number" && Number.isInteger(raw.pageSize) && raw.pageSize > 0
+            ? { pageSize: raw.pageSize }
+            : {}),
+    };
+}
+function parseSort(input) {
+    if (typeof input !== "object" || input === null)
+        return null;
+    const raw = input;
+    if (typeof raw.key !== "string" || raw.key.length === 0)
+        return null;
+    if (raw.direction !== "asc" && raw.direction !== "desc")
+        return null;
+    return { key: raw.key, direction: raw.direction };
+}
+function parseFacets(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        const values = parseStrings(value);
+        // An empty list means "all values" — the same as the key being absent, so
+        // it is dropped rather than stored as a filter that filters nothing.
+        if (values.length > 0)
+            out[key] = values;
+    }
+    return out;
+}
+function parseStrings(input) {
+    if (!Array.isArray(input))
+        return [];
+    return input.filter((value) => typeof value === "string");
+}
+//# sourceMappingURL=views.js.map

package/dist/grid/views.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"views.js","sourceRoot":"","sources":["../../src/grid/views.ts"],"names":[],"mappings":"AAsBA,MAAM,CAAC,MAAM,UAAU,GAAkB,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;AAElG;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrF,MAAM,GAAG,GAAG,KAAgC,CAAC;IAE7C,OAAO;QACL,KAAK,EAAE,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QACrD,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC;QACzB,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC;QAC/B,aAAa,EAAE,YAAY,CAAC,GAAG,CAAC,aAAa,CAAC;QAC9C,GAAG,CAAC,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,GAAG,CAAC;YACxF,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE;YAC5B,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7D,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,IAAI,GAAG,CAAC,SAAS,KAAK,KAAK,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM;QAAE,OAAO,IAAI,CAAC;IACrE,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;AACpD,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnF,MAAM,GAAG,GAA6B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC5E,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QACnC,0EAA0E;QAC1E,qEAAqE;QACrE,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;AAC7E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connextar/house",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "The pieces every app we build needs and none of them should own a copy of.",
   "license": "MIT",
   "repository": {
@@ -50,6 +50,10 @@
       "types": "./dist/ux/navigation-index.d.ts",
       "default": "./dist/ux/navigation-index.js"
     },
+    "./grid": {
+      "types": "./dist/grid/index.d.ts",
+      "default": "./dist/grid/index.js"
+    },
     "./wizard": {
       "types": "./dist/wizard/index.d.ts",
       "default": "./dist/wizard/index.js"