@aglyn/shared-ui-jsx 1.0.0-beta.186 → 1.0.0-beta.188

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/shared-ui-jsx",
-  "version": "1.0.0-beta.186",
+  "version": "1.0.0-beta.188",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,10 +25,10 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-mdi": "1.0.0-beta.186",
-    "@aglyn/shared-ui-theme": "1.0.0-beta.186",
-    "@aglyn/shared-util-tools": "1.0.0-beta.186",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.186",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.188",
+    "@aglyn/shared-ui-theme": "1.0.0-beta.188",
+    "@aglyn/shared-util-tools": "1.0.0-beta.188",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.188",
     "@mdi/js": "^7.4.47",
     "@swc/helpers": "0.5.23",
     "change-case": "^5.4.4",

package/src/lib/components/list-filter-chips.component.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ListFilterField } from '../const/list-filter';
+import type { ListFilterClause, ListFilterOption } from '../const/list-grid-filter';
+export interface ListFilterChipsProps {
+    /** The list's grammar — every field a clause may name. */
+    fields: readonly ListFilterField[];
+    /** How a field reads on a chip; a field without one reads as its column. */
+    headers: Readonly<Record<string, string>>;
+    clauses: readonly ListFilterClause[];
+    onChange: (clauses: ListFilterClause[]) => void;
+    /** Choices per field, so a chip names a picked value by its label. */
+    options?: Readonly<Record<string, readonly ListFilterOption[]>>;
+    /**
+     * The field the query is serving, marked so the reader knows which reached
+     * everything. Omitted on a list whose every clause narrows the same rows.
+     */
+    servedField?: string | null;
+    /**
+     * Whether chips carry the served / loaded-window distinction at all.
+     * Defaults to whether `servedField` was passed: a list that answers every
+     * clause over the same rows has nothing to distinguish.
+     */
+    marksServed?: boolean;
+    disabled?: boolean;
+}
+/**
+ * Every clause a list is narrowed by, as chips over the grid (AGL-2617,
+ * AGL-3313; shared since AGL-3317).
+ *
+ * The clauses are ADDED through the grid's own Filters panel; this bar is
+ * what shows the SET. The free DataGrid's panel holds one item at a time
+ * and a saved view holds several, so without it a list narrowed by two
+ * fields would show one of the two and hide the other. Each
+ * chip reads as a sentence — "Owner is Dana", "Created on or after 1 Jan"
+ * — and removes its clause; where some clauses reach the query and others
+ * narrow the loaded rows, the served one is marked.
+ */
+export declare function ListFilterChips(props: ListFilterChipsProps): import("react").JSX.Element;
+export declare namespace ListFilterChips {
+    var displayName: string;
+}
+export default ListFilterChips;

package/src/lib/components/list-filter-chips.component.js

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Chip, Stack, Tooltip } from "@mui/material";
+import { listFilterOperatorLabel } from "../const/list-filter.js";
+/** Operators that carry no value. */ const VALUELESS = new Set([
+    'isEmpty',
+    'isNotEmpty'
+]);
+/** Operators that take several values, comma-joined the way the grammar splits them. */ const MULTI = new Set([
+    'isAnyOf'
+]);
+const dayLabel = (raw)=>{
+    const at = new Date(raw);
+    return Number.isNaN(at.getTime()) ? raw : at.toLocaleDateString();
+};
+/**
+ * Every clause a list is narrowed by, as chips over the grid (AGL-2617,
+ * AGL-3313; shared since AGL-3317).
+ *
+ * The clauses are ADDED through the grid's own Filters panel; this bar is
+ * what shows the SET. The free DataGrid's panel holds one item at a time
+ * and a saved view holds several, so without it a list narrowed by two
+ * fields would show one of the two and hide the other. Each
+ * chip reads as a sentence — "Owner is Dana", "Created on or after 1 Jan"
+ * — and removes its clause; where some clauses reach the query and others
+ * narrow the loaded rows, the served one is marked.
+ */ export function ListFilterChips(props) {
+    const { fields, headers, clauses, onChange, options = {}, servedField = null, marksServed = props.servedField !== undefined, disabled = false } = props;
+    const header = (column)=>{
+        var _headers_column;
+        return (_headers_column = headers[column]) != null ? _headers_column : column;
+    };
+    /** How a clause reads: its header, its operator, and its value by label. */ const sentence = (clause)=>{
+        var _clause_label;
+        const field = fields.find((entry)=>entry.column === clause.field);
+        const choices = options[clause.field];
+        const named = (value)=>{
+            var _ref;
+            var _choices_find;
+            return (_ref = choices == null ? void 0 : (_choices_find = choices.find((option)=>option.value === value)) == null ? void 0 : _choices_find.label) != null ? _ref : value;
+        };
+        const value = VALUELESS.has(clause.op) ? '' : MULTI.has(clause.op) ? clause.value.split(',').map((entry)=>entry.trim()).filter(Boolean).map(named).join(', ') : (_clause_label = clause.label) != null ? _clause_label : (field == null ? void 0 : field.kind) === 'date' ? dayLabel(clause.value) : named(clause.value);
+        return `${header(clause.field)} ${listFilterOperatorLabel(clause.op)}${value ? ` ${value}` : ''}`;
+    };
+    if (!clauses.length) return null;
+    return /*#__PURE__*/ _jsx(Stack, {
+        direction: "row",
+        spacing: 1,
+        useFlexGap: true,
+        sx: {
+            alignItems: 'center',
+            flexWrap: 'wrap'
+        },
+        role: "list",
+        "aria-label": "Filters",
+        children: clauses.map((clause, index)=>{
+            const served = marksServed && servedField !== null && clause.field === servedField;
+            const key = `${clause.field}-${clause.op}-${index}`;
+            const chip = /*#__PURE__*/ _jsx(Chip, {
+                role: "listitem",
+                size: "small",
+                variant: served ? 'filled' : 'outlined',
+                color: served ? 'primary' : 'default',
+                label: sentence(clause),
+                disabled: disabled,
+                onDelete: ()=>onChange(clauses.filter((_entry, at)=>at !== index))
+            }, key);
+            return marksServed ? /*#__PURE__*/ _jsx(Tooltip, {
+                title: served ? 'Searched across every record' : 'Narrows the records already loaded',
+                children: chip
+            }, key) : chip;
+        })
+    });
+}
+ListFilterChips.displayName = 'ListFilterChips';
+export default ListFilterChips;
+
+//# sourceMappingURL=list-filter-chips.component.js.map

package/src/lib/components/list-filter-chips.component.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/components/list-filter-chips.component.tsx"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n'use client'\n\nimport { Chip, Stack, Tooltip } from '@mui/material'\nimport { type ListFilterField, listFilterOperatorLabel } from '../const/list-filter'\nimport type { ListFilterClause, ListFilterOption } from '../const/list-grid-filter'\n\nexport interface ListFilterChipsProps {\n  /** The list's grammar — every field a clause may name. */\n  fields: readonly ListFilterField[]\n  /** How a field reads on a chip; a field without one reads as its column. */\n  headers: Readonly<Record<string, string>>\n  clauses: readonly ListFilterClause[]\n  onChange: (clauses: ListFilterClause[]) => void\n  /** Choices per field, so a chip names a picked value by its label. */\n  options?: Readonly<Record<string, readonly ListFilterOption[]>>\n  /**\n   * The field the query is serving, marked so the reader knows which reached\n   * everything. Omitted on a list whose every clause narrows the same rows.\n   */\n  servedField?: string | null\n  /**\n   * Whether chips carry the served / loaded-window distinction at all.\n   * Defaults to whether `servedField` was passed: a list that answers every\n   * clause over the same rows has nothing to distinguish.\n   */\n  marksServed?: boolean\n  disabled?: boolean\n}\n\n/** Operators that carry no value. */\nconst VALUELESS = new Set(['isEmpty', 'isNotEmpty'])\n/** Operators that take several values, comma-joined the way the grammar splits them. */\nconst MULTI = new Set(['isAnyOf'])\n\nconst dayLabel = (raw: string): string => {\n  const at = new Date(raw)\n  return Number.isNaN(at.getTime()) ? raw : at.toLocaleDateString()\n}\n\n/**\n * Every clause a list is narrowed by, as chips over the grid (AGL-2617,\n * AGL-3313; shared since AGL-3317).\n *\n * The clauses are ADDED through the grid's own Filters panel; this bar is\n * what shows the SET. The free DataGrid's panel holds one item at a time\n * and a saved view holds several, so without it a list narrowed by two\n * fields would show one of the two and hide the other. Each\n * chip reads as a sentence — \"Owner is Dana\", \"Created on or after 1 Jan\"\n * — and removes its clause; where some clauses reach the query and others\n * narrow the loaded rows, the served one is marked.\n */\nexport function ListFilterChips(props: ListFilterChipsProps) {\n  const {\n    fields,\n    headers,\n    clauses,\n    onChange,\n    options = {},\n    servedField = null,\n    marksServed = props.servedField !== undefined,\n    disabled = false,\n  } = props\n  const header = (column: string) => headers[column] ?? column\n\n  /** How a clause reads: its header, its operator, and its value by label. */\n  const sentence = (clause: ListFilterClause): string => {\n    const field = fields.find((entry) => entry.column === clause.field)\n    const choices = options[clause.field]\n    const named = (value: string) =>\n      choices?.find((option) => option.value === value)?.label ?? value\n    const value = VALUELESS.has(clause.op)\n      ? ''\n      : MULTI.has(clause.op)\n        ? clause.value\n            .split(',')\n            .map((entry) => entry.trim())\n            .filter(Boolean)\n            .map(named)\n            .join(', ')\n        : clause.label ?? (field?.kind === 'date' ? dayLabel(clause.value) : named(clause.value))\n    return `${header(clause.field)} ${listFilterOperatorLabel(clause.op)}${value ? ` ${value}` : ''}`\n  }\n\n  if (!clauses.length) return null\n  return (\n    <Stack\n      direction=\"row\"\n      spacing={1}\n      useFlexGap\n      sx={{ alignItems: 'center', flexWrap: 'wrap' }}\n      role=\"list\"\n      aria-label=\"Filters\"\n    >\n      {clauses.map((clause, index) => {\n        const served = marksServed && servedField !== null && clause.field === servedField\n        const key = `${clause.field}-${clause.op}-${index}`\n        const chip = (\n          <Chip\n            key={key}\n            role=\"listitem\"\n            size=\"small\"\n            variant={served ? 'filled' : 'outlined'}\n            color={served ? 'primary' : 'default'}\n            label={sentence(clause)}\n            disabled={disabled}\n            onDelete={() => onChange(clauses.filter((_entry, at) => at !== index))}\n          />\n        )\n        return marksServed ? (\n          <Tooltip\n            key={key}\n            title={served ? 'Searched across every record' : 'Narrows the records already loaded'}\n          >\n            {chip}\n          </Tooltip>\n        ) : (\n          chip\n        )\n      })}\n    </Stack>\n  )\n}\nListFilterChips.displayName = 'ListFilterChips'\n\nexport default ListFilterChips\n"],"names":["Chip","Stack","Tooltip","listFilterOperatorLabel","VALUELESS","Set","MULTI","dayLabel","raw","at","Date","Number","isNaN","getTime","toLocaleDateString","ListFilterChips","props","fields","headers","clauses","onChange","options","servedField","marksServed","undefined","disabled","header","column","sentence","clause","field","find","entry","choices","named","value","option","label","has","op","split","map","trim","filter","Boolean","join","kind","length","direction","spacing","useFlexGap","sx","alignItems","flexWrap","role","aria-label","index","served","key","chip","size","variant","color","onDelete","_entry","title","displayName"],"mappings":"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"}

package/src/lib/const/list-grid-filter.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type GridColDef, type GridFilterItem } from '@mui/x-data-grid';
+import { type ListFilterField, type ListFilterRequest } from './list-filter';
+/** One clause a list is narrowed by; `label` names a picked value on a chip. */
+export interface ListFilterClause extends ListFilterRequest {
+    label?: string;
+}
+/** A choice for a field whose value is picked rather than typed. */
+export interface ListFilterOption {
+    value: string;
+    label: string;
+}
+/**
+ * A field of a list that holds its rows and answers the panel in memory.
+ *
+ * The grammar's derived operators describe what a FIRESTORE query can
+ * serve, so a text field with no lower-case twin offers nothing. A list
+ * that matches over rows it already has is not held to that: plain
+ * JavaScript answers a mid-string `contains` and both empty operators, so
+ * the field names them (`operators`), and `matchListFilter` answers them.
+ * `select` is a field picked from choices — the list passes them as the
+ * field's options, and the panel shows a select over them.
+ */
+export declare function inMemoryListField(column: string, kind: 'text' | 'select' | 'number' | 'date' | 'boolean', path?: string): ListFilterField;
+/**
+ * How one field's stored clause and the panel's item translate. A field
+ * with choices uses {@link listSelectCodec}; a typed one,
+ * {@link listPlainCodec}. A list whose clauses predate the panel supplies
+ * its own.
+ */
+export interface ListGridFilterCodec {
+    toItem: (clause: ListFilterClause) => Pick<GridFilterItem, 'operator' | 'value'> | null;
+    toClause: (item: GridFilterItem) => ListFilterClause | null;
+}
+/** A typed field: the stored operator IS the grid's. */
+export declare const listPlainCodec: ListGridFilterCodec;
+/** A picked field: `equals` shows as `is`, and `isAnyOf` holds a comma list. */
+export declare const listSelectCodec: ListGridFilterCodec;
+/** The select operators a field's allowed clause operators map to. */
+export declare function listSelectOperators(allowed: readonly string[]): import("@mui/x-data-grid").GridFilterOperator<any, any, any, import("@mui/x-data-grid").GridFilterInputValueProps>[];
+/**
+ * The list's columns, each made filterable exactly as far as its field is
+ * declared, and every declared field that is not a column added as a
+ * permanently hidden one — the panel lists columns, so a field with none
+ * could not be reached (`hiddenFilterColumns`).
+ *
+ * A field with choices becomes a `singleSelect` over them, whatever the
+ * column rendered before; one without keeps the grammar's operators; a
+ * column no field declares offers no filter, because the list, not the
+ * grid, answers every filter and would have nothing to answer it with.
+ */
+export declare function listFilterGridColumns(columns: readonly GridColDef[], fields: readonly ListFilterField[], options?: Readonly<Record<string, readonly ListFilterOption[]>>, headers?: Readonly<Record<string, string>>): GridColDef[];
+/**
+ * Whether a row answers a quick search: every whitespace-separated word
+ * appears, case-insensitively, in SOME of the row's searched values. A
+ * blank search matches every row, so an emptied box is the list unfiltered.
+ * An array value (tags) is searched member by member.
+ */
+export declare function listRowMatchesSearch(row: object, paths: readonly string[], words: readonly string[]): boolean;
+/**
+ * The rows that answer every clause and the quick search — for a list that
+ * holds its whole data set (or the window its query already narrowed) and
+ * so answers the panel itself. A clause `skip` names is one the query
+ * already served, and is not matched again.
+ */
+export declare function filterListRows<Row extends object>(rows: readonly Row[], fields: readonly ListFilterField[], clauses: readonly ListFilterClause[], search: {
+    paths: readonly string[];
+    words: readonly string[];
+}, skip?: (clause: ListFilterClause) => boolean): Row[];
+/**
+ * The clauses with one field's clause set: replaced in place where the field
+ * already had one, appended where it did not, removed when `next` is null.
+ * A field holds ONE clause, which is what the panel edits.
+ */
+export declare function upsertListFilterClause<Clause extends ListFilterClause>(clauses: readonly Clause[], field: string, next: Clause | null): Clause[];

package/src/lib/const/list-grid-filter.js

@@ -0,0 +1,213 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { getGridSingleSelectOperators } from "@mui/x-data-grid";
+import { gridFilterRequests, hiddenFilterColumns, listFilterColumn, listFilterOperators, matchListFilter } from "./list-filter.js";
+/**
+ * A field of a list that holds its rows and answers the panel in memory.
+ *
+ * The grammar's derived operators describe what a FIRESTORE query can
+ * serve, so a text field with no lower-case twin offers nothing. A list
+ * that matches over rows it already has is not held to that: plain
+ * JavaScript answers a mid-string `contains` and both empty operators, so
+ * the field names them (`operators`), and `matchListFilter` answers them.
+ * `select` is a field picked from choices — the list passes them as the
+ * field's options, and the panel shows a select over them.
+ */ export function inMemoryListField(column, kind, path = column) {
+    switch(kind){
+        case 'text':
+            return {
+                column,
+                path,
+                kind: 'text',
+                operators: [
+                    'contains',
+                    'doesNotContain',
+                    'equals',
+                    'startsWith',
+                    'endsWith',
+                    'isEmpty',
+                    'isNotEmpty'
+                ]
+            };
+        case 'select':
+            return {
+                column,
+                path,
+                kind: 'exact',
+                operators: [
+                    'equals',
+                    'doesNotEqual',
+                    'isAnyOf'
+                ]
+            };
+        case 'number':
+            return {
+                column,
+                path,
+                kind: 'number',
+                presence: 'nullable'
+            };
+        case 'date':
+            return {
+                column,
+                path,
+                kind: 'date',
+                presence: 'nullable'
+            };
+        default:
+            return {
+                column,
+                path,
+                kind: 'boolean'
+            };
+    }
+}
+/** The grid operator each stored select operator shows as. */ const SELECT_TO_GRID = {
+    equals: 'is',
+    doesNotEqual: 'not',
+    isAnyOf: 'isAnyOf'
+};
+const SELECT_FROM_GRID = {
+    is: 'equals',
+    not: 'doesNotEqual',
+    isAnyOf: 'isAnyOf'
+};
+/** The panel's item as a clause, through the grammar's one notion of "usable". */ const plainClause = (item)=>{
+    var _gridFilterRequests_;
+    return (_gridFilterRequests_ = gridFilterRequests({
+        items: [
+            item
+        ]
+    })[0]) != null ? _gridFilterRequests_ : null;
+};
+/** A typed field: the stored operator IS the grid's. */ export const listPlainCodec = {
+    toItem: (clause)=>({
+            operator: clause.op,
+            value: clause.value === '' ? undefined : clause.value
+        }),
+    toClause: plainClause
+};
+/** A picked field: `equals` shows as `is`, and `isAnyOf` holds a comma list. */ export const listSelectCodec = {
+    toItem: (clause)=>{
+        const operator = SELECT_TO_GRID[clause.op];
+        if (!operator) return null;
+        return {
+            operator,
+            value: operator === 'isAnyOf' ? clause.value.split(',').map((entry)=>entry.trim()).filter(Boolean) : clause.value
+        };
+    },
+    toClause: (item)=>{
+        const op = SELECT_FROM_GRID[String(item.operator)];
+        const request = op ? plainClause(item) : null;
+        return request && op ? _extends({}, request, {
+            op
+        }) : null;
+    }
+};
+/** The select operators a field's allowed clause operators map to. */ export function listSelectOperators(allowed) {
+    const shown = allowed.map((op)=>SELECT_TO_GRID[op]).filter(Boolean);
+    return getGridSingleSelectOperators().filter((operator)=>shown.includes(operator.value));
+}
+/**
+ * The list's columns, each made filterable exactly as far as its field is
+ * declared, and every declared field that is not a column added as a
+ * permanently hidden one — the panel lists columns, so a field with none
+ * could not be reached (`hiddenFilterColumns`).
+ *
+ * A field with choices becomes a `singleSelect` over them, whatever the
+ * column rendered before; one without keeps the grammar's operators; a
+ * column no field declares offers no filter, because the list, not the
+ * grid, answers every filter and would have nothing to answer it with.
+ */ export function listFilterGridColumns(columns, fields, options = {}, headers = {}) {
+    const selectProps = (field)=>{
+        var _options_field_column;
+        const choices = (_options_field_column = options[field.column]) != null ? _options_field_column : [];
+        const operators = listSelectOperators(listFilterOperators(field));
+        return {
+            type: 'singleSelect',
+            valueOptions: choices.map((choice)=>({
+                    value: choice.value,
+                    label: choice.label
+                })),
+            filterable: choices.length > 0 && operators.length > 0,
+            filterOperators: operators
+        };
+    };
+    const shown = columns.map((column)=>{
+        if (column.filterable === false && column.hideable === false) return column;
+        const field = fields.find((entry)=>entry.column === column.field);
+        if (!field) return _extends({}, column, {
+            filterable: false
+        });
+        if (options[field.column]) return _extends({}, column, selectProps(field));
+        return _extends({}, column, listFilterColumn(fields, field.column));
+    });
+    const present = columns.map((column)=>column.field);
+    const hidden = hiddenFilterColumns(fields, present, headers).map((column)=>{
+        const field = fields.find((entry)=>entry.column === column.field);
+        return field && options[field.column] ? _extends({}, column, selectProps(field)) : column;
+    });
+    return [
+        ...shown,
+        ...hidden
+    ];
+}
+/**
+ * Whether a row answers a quick search: every whitespace-separated word
+ * appears, case-insensitively, in SOME of the row's searched values. A
+ * blank search matches every row, so an emptied box is the list unfiltered.
+ * An array value (tags) is searched member by member.
+ */ export function listRowMatchesSearch(row, paths, words) {
+    const asked = words.map((word)=>word.trim().toLowerCase()).filter(Boolean);
+    if (!asked.length) return true;
+    const values = paths.flatMap((path)=>{
+        const value = path.split('.').reduce((at, key)=>at == null ? undefined : at[key], row);
+        return Array.isArray(value) ? value : [
+            value
+        ];
+    }).filter((value)=>typeof value === 'string' || typeof value === 'number').map((value)=>String(value).toLowerCase()).filter(Boolean);
+    return asked.every((word)=>values.some((value)=>value.includes(word)));
+}
+/**
+ * The rows that answer every clause and the quick search — for a list that
+ * holds its whole data set (or the window its query already narrowed) and
+ * so answers the panel itself. A clause `skip` names is one the query
+ * already served, and is not matched again.
+ */ export function filterListRows(rows, fields, clauses, search, skip) {
+    const applied = skip ? clauses.filter((clause)=>!skip(clause)) : clauses;
+    return rows.filter((row)=>applied.every((clause)=>matchListFilter(row, fields, clause)) && listRowMatchesSearch(row, search.paths, search.words));
+}
+/**
+ * The clauses with one field's clause set: replaced in place where the field
+ * already had one, appended where it did not, removed when `next` is null.
+ * A field holds ONE clause, which is what the panel edits.
+ */ export function upsertListFilterClause(clauses, field, next) {
+    const at = clauses.findIndex((clause)=>clause.field === field);
+    const rest = clauses.filter((clause)=>clause.field !== field);
+    if (!next) return rest;
+    if (at === -1) return [
+        ...rest,
+        next
+    ];
+    return [
+        ...rest.slice(0, at),
+        next,
+        ...rest.slice(at)
+    ];
+}
+
+//# sourceMappingURL=list-grid-filter.js.map

package/src/lib/const/list-grid-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/const/list-grid-filter.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  getGridSingleSelectOperators,\n  type GridColDef,\n  type GridFilterItem,\n} from '@mui/x-data-grid'\nimport {\n  gridFilterRequests,\n  hiddenFilterColumns,\n  type ListFilterField,\n  type ListFilterRequest,\n  listFilterColumn,\n  listFilterOperators,\n  matchListFilter,\n} from './list-filter'\n\n/*\n * ONE path from a list's filter clauses to the data grid's own Filters panel\n * and quick search, and back (AGL-3313, shared by every list since AGL-3317).\n *\n * A list stores what it is narrowed by as clauses — `{ field, op, value }`,\n * the shape saved views hold — and edits them through the grid's toolbar\n * rather than controls of its own. What a list declares is its fields, as\n * the `ListFilterField` grammar (`./list-filter`), plus the choices of the\n * fields whose values are picked rather than typed. The grid then offers\n * each as a typed column: a `singleSelect` with its choices where there are\n * choices, the operators the grammar allows otherwise.\n *\n * The clauses keep their stored shape, so a view saved before the panel\n * reads unchanged: the panel shows `equals` as the select's `is` and writes\n * `is` back as `equals`, and a list whose clauses were stored in some other\n * shape says so with a codec.\n */\n\n/** One clause a list is narrowed by; `label` names a picked value on a chip. */\nexport interface ListFilterClause extends ListFilterRequest {\n  label?: string\n}\n\n/** A choice for a field whose value is picked rather than typed. */\nexport interface ListFilterOption {\n  value: string\n  label: string\n}\n\n/**\n * A field of a list that holds its rows and answers the panel in memory.\n *\n * The grammar's derived operators describe what a FIRESTORE query can\n * serve, so a text field with no lower-case twin offers nothing. A list\n * that matches over rows it already has is not held to that: plain\n * JavaScript answers a mid-string `contains` and both empty operators, so\n * the field names them (`operators`), and `matchListFilter` answers them.\n * `select` is a field picked from choices — the list passes them as the\n * field's options, and the panel shows a select over them.\n */\nexport function inMemoryListField(\n  column: string,\n  kind: 'text' | 'select' | 'number' | 'date' | 'boolean',\n  path: string = column,\n): ListFilterField {\n  switch (kind) {\n    case 'text':\n      return {\n        column,\n        path,\n        kind: 'text',\n        operators: ['contains', 'doesNotContain', 'equals', 'startsWith', 'endsWith', 'isEmpty', 'isNotEmpty'],\n      }\n    case 'select':\n      return { column, path, kind: 'exact', operators: ['equals', 'doesNotEqual', 'isAnyOf'] }\n    case 'number':\n      return { column, path, kind: 'number', presence: 'nullable' }\n    case 'date':\n      return { column, path, kind: 'date', presence: 'nullable' }\n    default:\n      return { column, path, kind: 'boolean' }\n  }\n}\n\n/** The grid operator each stored select operator shows as. */\nconst SELECT_TO_GRID: Readonly<Record<string, string>> = {\n  equals: 'is',\n  doesNotEqual: 'not',\n  isAnyOf: 'isAnyOf',\n}\nconst SELECT_FROM_GRID: Readonly<Record<string, string>> = {\n  is: 'equals',\n  not: 'doesNotEqual',\n  isAnyOf: 'isAnyOf',\n}\n\n/**\n * How one field's stored clause and the panel's item translate. A field\n * with choices uses {@link listSelectCodec}; a typed one,\n * {@link listPlainCodec}. A list whose clauses predate the panel supplies\n * its own.\n */\nexport interface ListGridFilterCodec {\n  toItem: (clause: ListFilterClause) => Pick<GridFilterItem, 'operator' | 'value'> | null\n  toClause: (item: GridFilterItem) => ListFilterClause | null\n}\n\n/** The panel's item as a clause, through the grammar's one notion of \"usable\". */\nconst plainClause = (item: GridFilterItem): ListFilterClause | null =>\n  gridFilterRequests({ items: [item] })[0] ?? null\n\n/** A typed field: the stored operator IS the grid's. */\nexport const listPlainCodec: ListGridFilterCodec = {\n  toItem: (clause) => ({\n    operator: clause.op,\n    value: clause.value === '' ? undefined : clause.value,\n  }),\n  toClause: plainClause,\n}\n\n/** A picked field: `equals` shows as `is`, and `isAnyOf` holds a comma list. */\nexport const listSelectCodec: ListGridFilterCodec = {\n  toItem: (clause) => {\n    const operator = SELECT_TO_GRID[clause.op]\n    if (!operator) return null\n    return {\n      operator,\n      value:\n        operator === 'isAnyOf'\n          ? clause.value.split(',').map((entry) => entry.trim()).filter(Boolean)\n          : clause.value,\n    }\n  },\n  toClause: (item) => {\n    const op = SELECT_FROM_GRID[String(item.operator)]\n    const request = op ? plainClause(item) : null\n    return request && op ? { ...request, op } : null\n  },\n}\n\n/** The select operators a field's allowed clause operators map to. */\nexport function listSelectOperators(allowed: readonly string[]) {\n  const shown = allowed.map((op) => SELECT_TO_GRID[op]).filter(Boolean)\n  return getGridSingleSelectOperators().filter((operator) =>\n    shown.includes(operator.value),\n  )\n}\n\n/**\n * The list's columns, each made filterable exactly as far as its field is\n * declared, and every declared field that is not a column added as a\n * permanently hidden one — the panel lists columns, so a field with none\n * could not be reached (`hiddenFilterColumns`).\n *\n * A field with choices becomes a `singleSelect` over them, whatever the\n * column rendered before; one without keeps the grammar's operators; a\n * column no field declares offers no filter, because the list, not the\n * grid, answers every filter and would have nothing to answer it with.\n */\nexport function listFilterGridColumns(\n  columns: readonly GridColDef[],\n  fields: readonly ListFilterField[],\n  options: Readonly<Record<string, readonly ListFilterOption[]>> = {},\n  headers: Readonly<Record<string, string>> = {},\n): GridColDef[] {\n  const selectProps = (field: ListFilterField) => {\n    const choices = options[field.column] ?? []\n    const operators = listSelectOperators(listFilterOperators(field))\n    return {\n      type: 'singleSelect' as const,\n      valueOptions: choices.map((choice) => ({ value: choice.value, label: choice.label })),\n      filterable: choices.length > 0 && operators.length > 0,\n      filterOperators: operators,\n    }\n  }\n  const shown = columns.map((column): GridColDef => {\n    if (column.filterable === false && column.hideable === false) return column\n    const field = fields.find((entry) => entry.column === column.field)\n    if (!field) return { ...column, filterable: false }\n    if (options[field.column]) return { ...column, ...selectProps(field) } as GridColDef\n    return { ...column, ...listFilterColumn(fields, field.column) }\n  })\n  const present = columns.map((column) => column.field)\n  const hidden = hiddenFilterColumns(fields, present, headers).map(\n    (column): GridColDef => {\n      const field = fields.find((entry) => entry.column === column.field)\n      return field && options[field.column]\n        ? ({ ...column, ...selectProps(field) } as GridColDef)\n        : column\n    },\n  )\n  return [...shown, ...hidden]\n}\n\n/**\n * Whether a row answers a quick search: every whitespace-separated word\n * appears, case-insensitively, in SOME of the row's searched values. A\n * blank search matches every row, so an emptied box is the list unfiltered.\n * An array value (tags) is searched member by member.\n */\nexport function listRowMatchesSearch(\n  row: object,\n  paths: readonly string[],\n  words: readonly string[],\n): boolean {\n  const asked = words.map((word) => word.trim().toLowerCase()).filter(Boolean)\n  if (!asked.length) return true\n  const values = paths\n    .flatMap((path) => {\n      const value = path\n        .split('.')\n        .reduce<unknown>(\n          (at, key) => (at == null ? undefined : (at as Record<string, unknown>)[key]),\n          row,\n        )\n      return Array.isArray(value) ? value : [value]\n    })\n    .filter((value): value is string | number => typeof value === 'string' || typeof value === 'number')\n    .map((value) => String(value).toLowerCase())\n    .filter(Boolean)\n  return asked.every((word) => values.some((value) => value.includes(word)))\n}\n\n/**\n * The rows that answer every clause and the quick search — for a list that\n * holds its whole data set (or the window its query already narrowed) and\n * so answers the panel itself. A clause `skip` names is one the query\n * already served, and is not matched again.\n */\nexport function filterListRows<Row extends object>(\n  rows: readonly Row[],\n  fields: readonly ListFilterField[],\n  clauses: readonly ListFilterClause[],\n  search: { paths: readonly string[]; words: readonly string[] },\n  skip?: (clause: ListFilterClause) => boolean,\n): Row[] {\n  const applied = skip ? clauses.filter((clause) => !skip(clause)) : clauses\n  return rows.filter(\n    (row) =>\n      applied.every((clause) => matchListFilter(row, fields, clause)) &&\n      listRowMatchesSearch(row, search.paths, search.words),\n  )\n}\n\n/**\n * The clauses with one field's clause set: replaced in place where the field\n * already had one, appended where it did not, removed when `next` is null.\n * A field holds ONE clause, which is what the panel edits.\n */\nexport function upsertListFilterClause<Clause extends ListFilterClause>(\n  clauses: readonly Clause[],\n  field: string,\n  next: Clause | null,\n): Clause[] {\n  const at = clauses.findIndex((clause) => clause.field === field)\n  const rest = clauses.filter((clause) => clause.field !== field)\n  if (!next) return rest\n  if (at === -1) return [...rest, next]\n  return [...rest.slice(0, at), next, ...rest.slice(at)]\n}\n"],"names":["getGridSingleSelectOperators","gridFilterRequests","hiddenFilterColumns","listFilterColumn","listFilterOperators","matchListFilter","inMemoryListField","column","kind","path","operators","presence","SELECT_TO_GRID","equals","doesNotEqual","isAnyOf","SELECT_FROM_GRID","is","not","plainClause","item","items","listPlainCodec","toItem","clause","operator","op","value","undefined","toClause","listSelectCodec","split","map","entry","trim","filter","Boolean","String","request","listSelectOperators","allowed","shown","includes","listFilterGridColumns","columns","fields","options","headers","selectProps","field","choices","type","valueOptions","choice","label","filterable","length","filterOperators","hideable","find","present","hidden","listRowMatchesSearch","row","paths","words","asked","word","toLowerCase","values","flatMap","reduce","at","key","Array","isArray","every","some","filterListRows","rows","clauses","search","skip","applied","upsertListFilterClause","next","findIndex","rest","slice"],"mappings":"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"}

package/src/lib/hooks/use-list-grid-filter.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { GridFilterModel } from '@mui/x-data-grid';
+import { type ListFilterClause, type ListGridFilterCodec } from '../const/list-grid-filter';
+export interface ListGridFilterOptions {
+    /**
+     * The clauses the list is narrowed by — a saved view's working filters.
+     * Omitted, the hook holds them itself, for a list with no saved views.
+     */
+    clauses?: readonly ListFilterClause[];
+    onChange?: (clauses: ListFilterClause[]) => void;
+    /** Fields whose values are picked, which the panel shows as a select. */
+    selectFields?: readonly string[];
+    /** A field whose stored clauses predate the panel, translated its own way. */
+    codecs?: Readonly<Record<string, ListGridFilterCodec>>;
+    /**
+     * The query serves ONE clause, so the panel's replaces every other — a
+     * server-paged list, which has no loaded window to narrow further.
+     * `keepAlongside` names the clauses that do narrow the loaded page and so
+     * may stand beside it.
+     */
+    single?: boolean;
+    keepAlongside?: (clause: ListFilterClause) => boolean;
+    /**
+     * The quick search's words, held by the list when it needs them before
+     * the grid's columns exist; the hook holds them itself otherwise.
+     */
+    search?: {
+        words: string[];
+        onChange: (words: string[]) => void;
+    };
+}
+/** What the grid is handed, and what the list filters its rows by. */
+export interface ListGridFilter {
+    /** Controlled: the panel's one item, and the quick search's words. */
+    filterModel: GridFilterModel;
+    onFilterModelChange: (model: GridFilterModel) => void;
+    /** The quick search's words, for the list to match its rows against. */
+    searchWords: string[];
+    /** Every clause in force — the ones given, or the ones the hook holds. */
+    clauses: readonly ListFilterClause[];
+    /** Replaces every clause; what the chips call to remove one. */
+    setClauses: (clauses: ListFilterClause[]) => void;
+}
+/**
+ * The grid's Filters panel and quick search, bound to a list's clauses
+ * (AGL-3313; shared since AGL-3317). See `const/list-grid-filter.ts` for the
+ * shape both sides keep.
+ *
+ * ## One field, one clause; the panel edits one at a time
+ *
+ * The free DataGrid's panel holds a single item, while a list may be
+ * narrowed by several clauses. So each FIELD holds one clause, and the panel
+ * is a window onto whichever field was last filtered: setting a value writes
+ * that field's clause, clearing it or deleting the row removes it, and
+ * choosing another column in the panel moves the window without touching
+ * the clause the reader just set. Filtering one field and then another is
+ * therefore both, which is what a reader who does it means; the chips over
+ * the grid (`ListFilterChips`) show every clause and remove any of them.
+ *
+ * ## The list answers, never the grid
+ *
+ * Every list passes `filterMode="server"`: the grid holds one page, or a
+ * window the query already narrowed, so a filter the grid ran itself would
+ * answer "no match" for a row on the next page. The list reads the clauses
+ * — onto its query where it can, over its loaded rows where it cannot
+ * (`filterListRows`) — and the quick search's words, and hands the grid the
+ * rows that answer.
+ */
+export declare function useListGridFilter(options?: ListGridFilterOptions): ListGridFilter;
+export default useListGridFilter;

package/src/lib/hooks/use-list-grid-filter.js

@@ -0,0 +1,158 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { useCallback, useMemo, useState } from "react";
+import { listPlainCodec, listSelectCodec, upsertListFilterClause } from "../const/list-grid-filter.js";
+const NO_CLAUSES = [];
+/**
+ * The grid's Filters panel and quick search, bound to a list's clauses
+ * (AGL-3313; shared since AGL-3317). See `const/list-grid-filter.ts` for the
+ * shape both sides keep.
+ *
+ * ## One field, one clause; the panel edits one at a time
+ *
+ * The free DataGrid's panel holds a single item, while a list may be
+ * narrowed by several clauses. So each FIELD holds one clause, and the panel
+ * is a window onto whichever field was last filtered: setting a value writes
+ * that field's clause, clearing it or deleting the row removes it, and
+ * choosing another column in the panel moves the window without touching
+ * the clause the reader just set. Filtering one field and then another is
+ * therefore both, which is what a reader who does it means; the chips over
+ * the grid (`ListFilterChips`) show every clause and remove any of them.
+ *
+ * ## The list answers, never the grid
+ *
+ * Every list passes `filterMode="server"`: the grid holds one page, or a
+ * window the query already narrowed, so a filter the grid ran itself would
+ * answer "no match" for a row on the next page. The list reads the clauses
+ * — onto its query where it can, over its loaded rows where it cannot
+ * (`filterListRows`) — and the quick search's words, and hands the grid the
+ * rows that answer.
+ */ export function useListGridFilter(options = {}) {
+    var _options_clauses, _ref, _ref1;
+    var _options_search, _options_search1;
+    const { selectFields = [], codecs = {}, single = false, keepAlongside } = options;
+    const [ownClauses, setOwnClauses] = useState([]);
+    const controlled = options.clauses !== undefined;
+    const clauses = (_options_clauses = options.clauses) != null ? _options_clauses : controlled ? NO_CLAUSES : ownClauses;
+    const onChange = useMemo(()=>{
+        var _options_onChange;
+        return controlled ? (_options_onChange = options.onChange) != null ? _options_onChange : ()=>undefined : setOwnClauses;
+    }, [
+        controlled,
+        options.onChange
+    ]);
+    const codecFor = useCallback((field)=>{
+        var _codecs_field;
+        return (_codecs_field = codecs[field]) != null ? _codecs_field : selectFields.includes(field) ? listSelectCodec : listPlainCodec;
+    }, [
+        codecs,
+        selectFields
+    ]);
+    /** The field the panel shows, once the reader has pointed it anywhere. */ const [focus, setFocus] = useState(null);
+    /** The panel's row while it holds no value yet — a column chosen, a value not. */ const [pending, setPending] = useState(null);
+    const [ownWords, setOwnWords] = useState([]);
+    const searchWords = (_ref = (_options_search = options.search) == null ? void 0 : _options_search.words) != null ? _ref : ownWords;
+    const setSearchWords = (_ref1 = (_options_search1 = options.search) == null ? void 0 : _options_search1.onChange) != null ? _ref1 : setOwnWords;
+    /** Whatever the panel last pointed at, else the newest clause it can show. */ const shownField = useMemo(()=>{
+        if (focus) return focus;
+        for(let at = clauses.length - 1; at >= 0; at -= 1){
+            if (codecFor(clauses[at].field).toItem(clauses[at])) return clauses[at].field;
+        }
+        return null;
+    }, [
+        focus,
+        clauses,
+        codecFor
+    ]);
+    const filterModel = useMemo(()=>{
+        const clause = shownField ? clauses.find((entry)=>entry.field === shownField) : undefined;
+        const shown = clause ? codecFor(clause.field).toItem(clause) : null;
+        const item = pending && pending.field === shownField ? pending : clause && shown ? _extends({
+            id: 'list',
+            field: clause.field
+        }, shown) : null;
+        return {
+            items: item ? [
+                item
+            ] : [],
+            quickFilterValues: searchWords
+        };
+    }, [
+        shownField,
+        clauses,
+        codecFor,
+        pending,
+        searchWords
+    ]);
+    const onFilterModelChange = useCallback((model)=>{
+        var _model_quickFilterValues;
+        const words = ((_model_quickFilterValues = model.quickFilterValues) != null ? _model_quickFilterValues : []).map((word)=>String(word));
+        if (words.join(' ') !== searchWords.join(' ')) setSearchWords(words);
+        const item = model.items[0];
+        // The row deleted: the field it showed is no longer filtered.
+        if (!item) {
+            if (shownField && clauses.some((clause)=>clause.field === shownField)) {
+                onChange(upsertListFilterClause(clauses, shownField, null));
+            }
+            setPending(null);
+            setFocus(null);
+            return;
+        }
+        const field = String(item.field);
+        const moved = field !== shownField;
+        setFocus(field);
+        const clause = codecFor(field).toClause(item);
+        if (!clause) {
+            // No value yet. A value cleared on the field already shown removes
+            // its clause; a column just chosen leaves the last one standing.
+            setPending(_extends({}, item, {
+                id: 'list'
+            }));
+            if (!moved && clauses.some((entry)=>entry.field === field)) {
+                onChange(upsertListFilterClause(clauses, field, null));
+            }
+            return;
+        }
+        setPending(null);
+        // A clause that stands alongside the served one is added beside it;
+        // any other replaces whatever the query was serving.
+        const base = single && !(keepAlongside == null ? void 0 : keepAlongside(clause)) ? clauses.filter((entry)=>entry.field === field || (keepAlongside == null ? void 0 : keepAlongside(entry))) : clauses;
+        const next = upsertListFilterClause(base, field, clause);
+        const same = next.length === clauses.length && next.every((entry, at)=>entry.field === clauses[at].field && entry.op === clauses[at].op && entry.value === clauses[at].value);
+        if (!same) onChange(next);
+    }, [
+        searchWords,
+        setSearchWords,
+        shownField,
+        clauses,
+        onChange,
+        codecFor,
+        single,
+        keepAlongside
+    ]);
+    return {
+        filterModel,
+        onFilterModelChange,
+        searchWords,
+        clauses,
+        setClauses: onChange
+    };
+}
+export default useListGridFilter;
+
+//# sourceMappingURL=use-list-grid-filter.js.map

package/src/lib/hooks/use-list-grid-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/hooks/use-list-grid-filter.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n'use client'\n\nimport type { GridFilterItem, GridFilterModel } from '@mui/x-data-grid'\nimport { useCallback, useMemo, useState } from 'react'\nimport {\n  type ListFilterClause,\n  type ListGridFilterCodec,\n  listPlainCodec,\n  listSelectCodec,\n  upsertListFilterClause,\n} from '../const/list-grid-filter'\n\nexport interface ListGridFilterOptions {\n  /**\n   * The clauses the list is narrowed by — a saved view's working filters.\n   * Omitted, the hook holds them itself, for a list with no saved views.\n   */\n  clauses?: readonly ListFilterClause[]\n  onChange?: (clauses: ListFilterClause[]) => void\n  /** Fields whose values are picked, which the panel shows as a select. */\n  selectFields?: readonly string[]\n  /** A field whose stored clauses predate the panel, translated its own way. */\n  codecs?: Readonly<Record<string, ListGridFilterCodec>>\n  /**\n   * The query serves ONE clause, so the panel's replaces every other — a\n   * server-paged list, which has no loaded window to narrow further.\n   * `keepAlongside` names the clauses that do narrow the loaded page and so\n   * may stand beside it.\n   */\n  single?: boolean\n  keepAlongside?: (clause: ListFilterClause) => boolean\n  /**\n   * The quick search's words, held by the list when it needs them before\n   * the grid's columns exist; the hook holds them itself otherwise.\n   */\n  search?: { words: string[]; onChange: (words: string[]) => void }\n}\n\n/** What the grid is handed, and what the list filters its rows by. */\nexport interface ListGridFilter {\n  /** Controlled: the panel's one item, and the quick search's words. */\n  filterModel: GridFilterModel\n  onFilterModelChange: (model: GridFilterModel) => void\n  /** The quick search's words, for the list to match its rows against. */\n  searchWords: string[]\n  /** Every clause in force — the ones given, or the ones the hook holds. */\n  clauses: readonly ListFilterClause[]\n  /** Replaces every clause; what the chips call to remove one. */\n  setClauses: (clauses: ListFilterClause[]) => void\n}\n\nconst NO_CLAUSES: readonly ListFilterClause[] = []\n\n/**\n * The grid's Filters panel and quick search, bound to a list's clauses\n * (AGL-3313; shared since AGL-3317). See `const/list-grid-filter.ts` for the\n * shape both sides keep.\n *\n * ## One field, one clause; the panel edits one at a time\n *\n * The free DataGrid's panel holds a single item, while a list may be\n * narrowed by several clauses. So each FIELD holds one clause, and the panel\n * is a window onto whichever field was last filtered: setting a value writes\n * that field's clause, clearing it or deleting the row removes it, and\n * choosing another column in the panel moves the window without touching\n * the clause the reader just set. Filtering one field and then another is\n * therefore both, which is what a reader who does it means; the chips over\n * the grid (`ListFilterChips`) show every clause and remove any of them.\n *\n * ## The list answers, never the grid\n *\n * Every list passes `filterMode=\"server\"`: the grid holds one page, or a\n * window the query already narrowed, so a filter the grid ran itself would\n * answer \"no match\" for a row on the next page. The list reads the clauses\n * — onto its query where it can, over its loaded rows where it cannot\n * (`filterListRows`) — and the quick search's words, and hands the grid the\n * rows that answer.\n */\nexport function useListGridFilter(options: ListGridFilterOptions = {}): ListGridFilter {\n  const { selectFields = [], codecs = {}, single = false, keepAlongside } = options\n\n  const [ownClauses, setOwnClauses] = useState<ListFilterClause[]>([])\n  const controlled = options.clauses !== undefined\n  const clauses = options.clauses ?? (controlled ? NO_CLAUSES : ownClauses)\n  const onChange = useMemo(\n    () => (controlled ? (options.onChange ?? (() => undefined)) : setOwnClauses),\n    [controlled, options.onChange],\n  )\n\n  const codecFor = useCallback(\n    (field: string): ListGridFilterCodec =>\n      codecs[field] ?? (selectFields.includes(field) ? listSelectCodec : listPlainCodec),\n    [codecs, selectFields],\n  )\n\n  /** The field the panel shows, once the reader has pointed it anywhere. */\n  const [focus, setFocus] = useState<string | null>(null)\n  /** The panel's row while it holds no value yet — a column chosen, a value not. */\n  const [pending, setPending] = useState<GridFilterItem | null>(null)\n  const [ownWords, setOwnWords] = useState<string[]>([])\n  const searchWords = options.search?.words ?? ownWords\n  const setSearchWords = options.search?.onChange ?? setOwnWords\n\n  /** Whatever the panel last pointed at, else the newest clause it can show. */\n  const shownField = useMemo(() => {\n    if (focus) return focus\n    for (let at = clauses.length - 1; at >= 0; at -= 1) {\n      if (codecFor(clauses[at].field).toItem(clauses[at])) return clauses[at].field\n    }\n    return null\n  }, [focus, clauses, codecFor])\n\n  const filterModel = useMemo<GridFilterModel>(() => {\n    const clause = shownField\n      ? clauses.find((entry) => entry.field === shownField)\n      : undefined\n    const shown = clause ? codecFor(clause.field).toItem(clause) : null\n    const item: GridFilterItem | null =\n      pending && pending.field === shownField\n        ? pending\n        : clause && shown\n          ? { id: 'list', field: clause.field, ...shown }\n          : null\n    return { items: item ? [item] : [], quickFilterValues: searchWords }\n  }, [shownField, clauses, codecFor, pending, searchWords])\n\n  const onFilterModelChange = useCallback(\n    (model: GridFilterModel) => {\n      const words = (model.quickFilterValues ?? []).map((word) => String(word))\n      if (words.join(' ') !== searchWords.join(' ')) setSearchWords(words)\n\n      const item = model.items[0]\n      // The row deleted: the field it showed is no longer filtered.\n      if (!item) {\n        if (shownField && clauses.some((clause) => clause.field === shownField)) {\n          onChange(upsertListFilterClause(clauses, shownField, null))\n        }\n        setPending(null)\n        setFocus(null)\n        return\n      }\n      const field = String(item.field)\n      const moved = field !== shownField\n      setFocus(field)\n      const clause = codecFor(field).toClause(item)\n      if (!clause) {\n        // No value yet. A value cleared on the field already shown removes\n        // its clause; a column just chosen leaves the last one standing.\n        setPending({ ...item, id: 'list' })\n        if (!moved && clauses.some((entry) => entry.field === field)) {\n          onChange(upsertListFilterClause(clauses, field, null))\n        }\n        return\n      }\n      setPending(null)\n      // A clause that stands alongside the served one is added beside it;\n      // any other replaces whatever the query was serving.\n      const base =\n        single && !keepAlongside?.(clause)\n          ? clauses.filter((entry) => entry.field === field || keepAlongside?.(entry))\n          : clauses\n      const next = upsertListFilterClause(base, field, clause)\n      const same =\n        next.length === clauses.length &&\n        next.every(\n          (entry, at) =>\n            entry.field === clauses[at].field &&\n            entry.op === clauses[at].op &&\n            entry.value === clauses[at].value,\n        )\n      if (!same) onChange(next)\n    },\n    [searchWords, setSearchWords, shownField, clauses, onChange, codecFor, single, keepAlongside],\n  )\n\n  return { filterModel, onFilterModelChange, searchWords, clauses, setClauses: onChange }\n}\n\nexport default useListGridFilter\n"],"names":["useCallback","useMemo","useState","listPlainCodec","listSelectCodec","upsertListFilterClause","NO_CLAUSES","useListGridFilter","options","selectFields","codecs","single","keepAlongside","ownClauses","setOwnClauses","controlled","clauses","undefined","onChange","codecFor","field","includes","focus","setFocus","pending","setPending","ownWords","setOwnWords","searchWords","search","words","setSearchWords","shownField","at","length","toItem","filterModel","clause","find","entry","shown","item","id","items","quickFilterValues","onFilterModelChange","model","map","word","String","join","some","moved","toClause","base","filter","next","same","every","op","value","setClauses"],"mappings":"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"}

package/src/lib/hooks/use-list-rows-filter.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { GridColDef, GridFilterModel } from '@mui/x-data-grid';
+import type { ListFilterField } from '../const/list-filter';
+import { type ListFilterClause, type ListFilterOption } from '../const/list-grid-filter';
+import { type ListGridFilter } from './use-list-grid-filter';
+export interface ListRowsFilterOptions<Row extends object> {
+    /** Every row the list read — the whole set, or the window its query capped. */
+    rows: readonly Row[];
+    /** What the panel offers, in the `ListFilterField` grammar. */
+    fields: readonly ListFilterField[];
+    /** Choices per picked field; each field named here is shown as a select. */
+    options?: Readonly<Record<string, readonly ListFilterOption[]>>;
+    /** How a field reads on a chip and as a hidden column's header. */
+    headers?: Readonly<Record<string, string>>;
+    /** The row paths the quick search reads. */
+    search: readonly string[];
+    /** A clause the list's query already served, not matched again. */
+    served?: (clause: ListFilterClause) => boolean;
+    /** A saved view's clauses, when the list keeps them; held here otherwise. */
+    clauses?: readonly ListFilterClause[];
+    onChange?: (clauses: ListFilterClause[]) => void;
+}
+/** What a list that holds its rows hands its grid and its chips. */
+export interface ListRowsFilter<Row> {
+    /** The rows that answer every clause and the search. */
+    rows: Row[];
+    /** Whether anything narrows the list — a clause or a search word. */
+    filtering: boolean;
+    gridFilter: ListGridFilter;
+    /** Spread onto `ListTable`: the controlled panel, answered by the list. */
+    gridProps: {
+        filterMode: 'server';
+        filterModel: GridFilterModel;
+        onFilterModelChange: (model: GridFilterModel) => void;
+        quickFilter: true;
+    };
+    /** Spread onto `ListFilterChips`. */
+    chipsProps: {
+        fields: readonly ListFilterField[];
+        headers: Readonly<Record<string, string>>;
+        clauses: readonly ListFilterClause[];
+        onChange: (clauses: ListFilterClause[]) => void;
+        options: Readonly<Record<string, readonly ListFilterOption[]>>;
+    };
+    /** The list's columns, typed for the panel (`listFilterGridColumns`). */
+    filterColumns: (columns: readonly GridColDef[]) => GridColDef[];
+}
+/**
+ * The grid's Filters panel and quick search for a list that HOLDS its rows
+ * (AGL-3317) — every row it read, or the window its query capped — and so
+ * answers both over that whole set rather than the page on screen.
+ *
+ * It is `useListGridFilter` with the rest of the recipe every such list
+ * repeated: the rows matched through `filterListRows`, the columns typed
+ * through `listFilterGridColumns`, and the props the grid and the chips
+ * take. A list whose query can serve a clause names it in `served`, puts it
+ * on the query, and the rows here are not matched against it again.
+ */
+export declare function useListRowsFilter<Row extends object>(options: ListRowsFilterOptions<Row>): ListRowsFilter<Row>;
+export default useListRowsFilter;

package/src/lib/hooks/use-list-rows-filter.js

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { useCallback, useMemo } from "react";
+import { filterListRows, listFilterGridColumns } from "../const/list-grid-filter.js";
+import { useListGridFilter } from "./use-list-grid-filter.js";
+const NO_OPTIONS = {};
+const NO_HEADERS = {};
+/**
+ * The grid's Filters panel and quick search for a list that HOLDS its rows
+ * (AGL-3317) — every row it read, or the window its query capped — and so
+ * answers both over that whole set rather than the page on screen.
+ *
+ * It is `useListGridFilter` with the rest of the recipe every such list
+ * repeated: the rows matched through `filterListRows`, the columns typed
+ * through `listFilterGridColumns`, and the props the grid and the chips
+ * take. A list whose query can serve a clause names it in `served`, puts it
+ * on the query, and the rows here are not matched against it again.
+ */ export function useListRowsFilter(options) {
+    const { rows, fields, options: choices = NO_OPTIONS, headers = NO_HEADERS, search, served } = options;
+    const selectFields = useMemo(()=>Object.keys(choices), [
+        choices
+    ]);
+    const gridFilter = useListGridFilter({
+        clauses: options.clauses,
+        onChange: options.onChange,
+        selectFields
+    });
+    const searchKey = gridFilter.searchWords.join(' ');
+    const matched = useMemo(()=>filterListRows(rows, fields, gridFilter.clauses, {
+            paths: search,
+            words: gridFilter.searchWords
+        }, served), // `searchKey` stands for the words, which are a new array each render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+        rows,
+        fields,
+        gridFilter.clauses,
+        searchKey,
+        search,
+        served
+    ]);
+    const filterColumns = useCallback((columns)=>listFilterGridColumns(columns, fields, choices, headers), [
+        fields,
+        choices,
+        headers
+    ]);
+    return {
+        rows: matched,
+        filtering: gridFilter.clauses.length > 0 || gridFilter.searchWords.length > 0,
+        gridFilter,
+        gridProps: {
+            filterMode: 'server',
+            filterModel: gridFilter.filterModel,
+            onFilterModelChange: gridFilter.onFilterModelChange,
+            quickFilter: true
+        },
+        chipsProps: {
+            fields,
+            headers,
+            clauses: gridFilter.clauses,
+            onChange: gridFilter.setClauses,
+            options: choices
+        },
+        filterColumns
+    };
+}
+export default useListRowsFilter;
+
+//# sourceMappingURL=use-list-rows-filter.js.map

package/src/lib/hooks/use-list-rows-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/hooks/use-list-rows-filter.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n'use client'\n\nimport type { GridColDef, GridFilterModel } from '@mui/x-data-grid'\nimport { useCallback, useMemo } from 'react'\nimport type { ListFilterField } from '../const/list-filter'\nimport {\n  filterListRows,\n  type ListFilterClause,\n  type ListFilterOption,\n  listFilterGridColumns,\n} from '../const/list-grid-filter'\nimport { type ListGridFilter, useListGridFilter } from './use-list-grid-filter'\n\nexport interface ListRowsFilterOptions<Row extends object> {\n  /** Every row the list read — the whole set, or the window its query capped. */\n  rows: readonly Row[]\n  /** What the panel offers, in the `ListFilterField` grammar. */\n  fields: readonly ListFilterField[]\n  /** Choices per picked field; each field named here is shown as a select. */\n  options?: Readonly<Record<string, readonly ListFilterOption[]>>\n  /** How a field reads on a chip and as a hidden column's header. */\n  headers?: Readonly<Record<string, string>>\n  /** The row paths the quick search reads. */\n  search: readonly string[]\n  /** A clause the list's query already served, not matched again. */\n  served?: (clause: ListFilterClause) => boolean\n  /** A saved view's clauses, when the list keeps them; held here otherwise. */\n  clauses?: readonly ListFilterClause[]\n  onChange?: (clauses: ListFilterClause[]) => void\n}\n\n/** What a list that holds its rows hands its grid and its chips. */\nexport interface ListRowsFilter<Row> {\n  /** The rows that answer every clause and the search. */\n  rows: Row[]\n  /** Whether anything narrows the list — a clause or a search word. */\n  filtering: boolean\n  gridFilter: ListGridFilter\n  /** Spread onto `ListTable`: the controlled panel, answered by the list. */\n  gridProps: {\n    filterMode: 'server'\n    filterModel: GridFilterModel\n    onFilterModelChange: (model: GridFilterModel) => void\n    quickFilter: true\n  }\n  /** Spread onto `ListFilterChips`. */\n  chipsProps: {\n    fields: readonly ListFilterField[]\n    headers: Readonly<Record<string, string>>\n    clauses: readonly ListFilterClause[]\n    onChange: (clauses: ListFilterClause[]) => void\n    options: Readonly<Record<string, readonly ListFilterOption[]>>\n  }\n  /** The list's columns, typed for the panel (`listFilterGridColumns`). */\n  filterColumns: (columns: readonly GridColDef[]) => GridColDef[]\n}\n\nconst NO_OPTIONS: Readonly<Record<string, readonly ListFilterOption[]>> = {}\nconst NO_HEADERS: Readonly<Record<string, string>> = {}\n\n/**\n * The grid's Filters panel and quick search for a list that HOLDS its rows\n * (AGL-3317) — every row it read, or the window its query capped — and so\n * answers both over that whole set rather than the page on screen.\n *\n * It is `useListGridFilter` with the rest of the recipe every such list\n * repeated: the rows matched through `filterListRows`, the columns typed\n * through `listFilterGridColumns`, and the props the grid and the chips\n * take. A list whose query can serve a clause names it in `served`, puts it\n * on the query, and the rows here are not matched against it again.\n */\nexport function useListRowsFilter<Row extends object>(\n  options: ListRowsFilterOptions<Row>,\n): ListRowsFilter<Row> {\n  const {\n    rows,\n    fields,\n    options: choices = NO_OPTIONS,\n    headers = NO_HEADERS,\n    search,\n    served,\n  } = options\n  const selectFields = useMemo(() => Object.keys(choices), [choices])\n  const gridFilter = useListGridFilter({\n    clauses: options.clauses,\n    onChange: options.onChange,\n    selectFields,\n  })\n  const searchKey = gridFilter.searchWords.join(' ')\n  const matched = useMemo(\n    () =>\n      filterListRows(\n        rows,\n        fields,\n        gridFilter.clauses,\n        { paths: search, words: gridFilter.searchWords },\n        served,\n      ),\n    // `searchKey` stands for the words, which are a new array each render.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n    [rows, fields, gridFilter.clauses, searchKey, search, served],\n  )\n  const filterColumns = useCallback(\n    (columns: readonly GridColDef[]) =>\n      listFilterGridColumns(columns, fields, choices, headers),\n    [fields, choices, headers],\n  )\n  return {\n    rows: matched,\n    filtering: gridFilter.clauses.length > 0 || gridFilter.searchWords.length > 0,\n    gridFilter,\n    gridProps: {\n      filterMode: 'server',\n      filterModel: gridFilter.filterModel,\n      onFilterModelChange: gridFilter.onFilterModelChange,\n      quickFilter: true,\n    },\n    chipsProps: {\n      fields,\n      headers,\n      clauses: gridFilter.clauses,\n      onChange: gridFilter.setClauses,\n      options: choices,\n    },\n    filterColumns,\n  }\n}\n\nexport default useListRowsFilter\n"],"names":["useCallback","useMemo","filterListRows","listFilterGridColumns","useListGridFilter","NO_OPTIONS","NO_HEADERS","useListRowsFilter","options","rows","fields","choices","headers","search","served","selectFields","Object","keys","gridFilter","clauses","onChange","searchKey","searchWords","join","matched","paths","words","filterColumns","columns","filtering","length","gridProps","filterMode","filterModel","onFilterModelChange","quickFilter","chipsProps","setClauses"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;AAGA,SAASA,WAAW,EAAEC,OAAO,QAAQ,QAAO;AAE5C,SACEC,cAAc,EAGdC,qBAAqB,QAChB,+BAA2B;AAClC,SAA8BC,iBAAiB,QAAQ,4BAAwB;AA8C/E,MAAMC,aAAoE,CAAC;AAC3E,MAAMC,aAA+C,CAAC;AAEtD;;;;;;;;;;CAUC,GACD,OAAO,SAASC,kBACdC,OAAmC;IAEnC,MAAM,EACJC,IAAI,EACJC,MAAM,EACNF,SAASG,UAAUN,UAAU,EAC7BO,UAAUN,UAAU,EACpBO,MAAM,EACNC,MAAM,EACP,GAAGN;IACJ,MAAMO,eAAed,QAAQ,IAAMe,OAAOC,IAAI,CAACN,UAAU;QAACA;KAAQ;IAClE,MAAMO,aAAad,kBAAkB;QACnCe,SAASX,QAAQW,OAAO;QACxBC,UAAUZ,QAAQY,QAAQ;QAC1BL;IACF;IACA,MAAMM,YAAYH,WAAWI,WAAW,CAACC,IAAI,CAAC;IAC9C,MAAMC,UAAUvB,QACd,IACEC,eACEO,MACAC,QACAQ,WAAWC,OAAO,EAClB;YAAEM,OAAOZ;YAAQa,OAAOR,WAAWI,WAAW;QAAC,GAC/CR,SAEJ,uEAAuE;IACvE,uDAAuD;IACvD;QAACL;QAAMC;QAAQQ,WAAWC,OAAO;QAAEE;QAAWR;QAAQC;KAAO;IAE/D,MAAMa,gBAAgB3B,YACpB,CAAC4B,UACCzB,sBAAsByB,SAASlB,QAAQC,SAASC,UAClD;QAACF;QAAQC;QAASC;KAAQ;IAE5B,OAAO;QACLH,MAAMe;QACNK,WAAWX,WAAWC,OAAO,CAACW,MAAM,GAAG,KAAKZ,WAAWI,WAAW,CAACQ,MAAM,GAAG;QAC5EZ;QACAa,WAAW;YACTC,YAAY;YACZC,aAAaf,WAAWe,WAAW;YACnCC,qBAAqBhB,WAAWgB,mBAAmB;YACnDC,aAAa;QACf;QACAC,YAAY;YACV1B;YACAE;YACAO,SAASD,WAAWC,OAAO;YAC3BC,UAAUF,WAAWmB,UAAU;YAC/B7B,SAASG;QACX;QACAgB;IACF;AACF;AAEA,eAAepB,kBAAiB"}

package/src/lib/hooks/use-paged-rows-filter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type ListRowsFilter, type ListRowsFilterOptions } from './use-list-rows-filter';
+/** How many rows a paged list reads while it is filtered — see below. */
+export declare const PAGED_FILTER_WINDOW = 100;
+/**
+ * A paged window over a live list — the shape `usePagedCollection` returns:
+ * every row from the first page to the one being read (plus, possibly, one
+ * probe row past it), the page, and whether more exist.
+ */
+export interface PagedRowsWindow<Row> {
+    /** Every row read so far, page 0 to the current page; may hold a probe row. */
+    data?: readonly Row[] | null;
+    /** The current page's rows, when nothing narrows the list. */
+    rows: readonly Row[];
+    hasMore: boolean;
+    page: number;
+    setPage: (page: number) => void;
+    pageSize: number;
+    setPageSize: (pageSize: number) => void;
+}
+/** What the list's grid, chips and footer take while it is paged. */
+export interface PagedRowsFilter<Row> extends Omit<ListRowsFilter<Row>, 'rows'> {
+    /** The rows the grid shows: the page, or the page of the matches. */
+    rows: Row[];
+    /** How many rows the window read — what a filter has looked through. */
+    read: number;
+    /** Spread onto `ListPagination`. */
+    pagination: {
+        page: number;
+        pageSize: number;
+        rowCount: number;
+        hasMore: boolean;
+        onPageChange: (page: number) => void;
+        onPageSizeChange: (pageSize: number) => void;
+    };
+}
+/**
+ * The grid's Filters panel and quick search over a PAGED live list
+ * (AGL-3317), one that reads a window growing a page at a time rather than
+ * every row.
+ *
+ * Unfiltered it is the pager it wraps: the grid shows the page, and the
+ * footer turns it. While a clause or a search word is in force the list
+ * matches over EVERYTHING the window has read — every page up to the
+ * current one, not the page on screen — and pages the matches instead;
+ * turning past the last match widens the window by one more page, so a
+ * filter reaches further the further the reader goes. `read` says how far
+ * it has looked, for the list to say so while more exist.
+ *
+ * ## The first filter widens the window once
+ *
+ * A window of one ten-row page is too little to filter: a search would look
+ * through ten rows and call the rest "no match". So the first clause or word
+ * widens the window to `filterWindow` rows (default
+ * {@link PAGED_FILTER_WINDOW}) — one listener that much wider, for as long as
+ * the list is narrowed — and clearing the last one puts the reader back on
+ * the page they left.
+ */
+export declare function usePagedRowsFilter<Row extends object>(paged: PagedRowsWindow<Row>, options: Omit<ListRowsFilterOptions<Row>, 'rows'> & {
+    filterWindow?: number;
+}): PagedRowsFilter<Row>;
+export default usePagedRowsFilter;

package/src/lib/hooks/use-paged-rows-filter.js

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ 'use client';
+import { _ as _extends } from "@swc/helpers/_/_extends";
+import { _ as _object_without_properties_loose } from "@swc/helpers/_/_object_without_properties_loose";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useListRowsFilter } from "./use-list-rows-filter.js";
+/** How many rows a paged list reads while it is filtered — see below. */ export const PAGED_FILTER_WINDOW = 100;
+/**
+ * The grid's Filters panel and quick search over a PAGED live list
+ * (AGL-3317), one that reads a window growing a page at a time rather than
+ * every row.
+ *
+ * Unfiltered it is the pager it wraps: the grid shows the page, and the
+ * footer turns it. While a clause or a search word is in force the list
+ * matches over EVERYTHING the window has read — every page up to the
+ * current one, not the page on screen — and pages the matches instead;
+ * turning past the last match widens the window by one more page, so a
+ * filter reaches further the further the reader goes. `read` says how far
+ * it has looked, for the list to say so while more exist.
+ *
+ * ## The first filter widens the window once
+ *
+ * A window of one ten-row page is too little to filter: a search would look
+ * through ten rows and call the rest "no match". So the first clause or word
+ * widens the window to `filterWindow` rows (default
+ * {@link PAGED_FILTER_WINDOW}) — one listener that much wider, for as long as
+ * the list is narrowed — and clearing the last one puts the reader back on
+ * the page they left.
+ */ export function usePagedRowsFilter(paged, options) {
+    const { pageSize } = paged;
+    const { filterWindow = PAGED_FILTER_WINDOW } = options, filterOptions = _object_without_properties_loose(options, [
+        "filterWindow"
+    ]);
+    const windowRows = useMemo(()=>{
+        var _paged_data;
+        return ((_paged_data = paged.data) != null ? _paged_data : paged.rows).slice(0, pageSize * (paged.page + 1));
+    }, [
+        paged.data,
+        paged.rows,
+        pageSize,
+        paged.page
+    ]);
+    const filter = useListRowsFilter(_extends({}, filterOptions, {
+        rows: windowRows
+    }));
+    const [matchPage, setMatchPage] = useState(0);
+    const searchKey = filter.gridFilter.searchWords.join(' ');
+    // A narrowed list starts again at its first page.
+    useEffect(()=>setMatchPage(0), [
+        filter.gridFilter.clauses,
+        searchKey
+    ]);
+    /** The page the reader was on before the list was narrowed. */ const before = useRef(null);
+    const { filtering } = filter;
+    useEffect(()=>{
+        if (filtering && before.current === null) {
+            before.current = paged.page;
+            const widened = Math.max(0, Math.ceil(filterWindow / pageSize) - 1);
+            if (widened > paged.page) paged.setPage(widened);
+        } else if (!filtering && before.current !== null) {
+            paged.setPage(before.current);
+            before.current = null;
+        }
+    // Only the transition into and out of a filter moves the window.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        filtering
+    ]);
+    if (!filter.filtering) {
+        return _extends({}, filter, {
+            rows: [
+                ...paged.rows
+            ],
+            read: windowRows.length,
+            pagination: {
+                page: paged.page,
+                pageSize,
+                rowCount: paged.rows.length,
+                hasMore: paged.hasMore,
+                onPageChange: paged.setPage,
+                onPageSizeChange: paged.setPageSize
+            }
+        });
+    }
+    const matches = filter.rows;
+    const shown = matches.slice(matchPage * pageSize, (matchPage + 1) * pageSize);
+    const lastMatchPage = Math.max(0, Math.ceil(matches.length / pageSize) - 1);
+    return _extends({}, filter, {
+        rows: shown,
+        read: windowRows.length,
+        pagination: {
+            page: matchPage,
+            pageSize,
+            rowCount: shown.length,
+            hasMore: paged.hasMore || matchPage < lastMatchPage,
+            onPageChange: (next)=>{
+                // Past the matches read so far, the window reads another page first.
+                if ((next + 1) * pageSize > matches.length && paged.hasMore) {
+                    paged.setPage(paged.page + 1);
+                }
+                setMatchPage(next);
+            },
+            onPageSizeChange: (next)=>{
+                paged.setPageSize(next);
+                setMatchPage(0);
+            }
+        }
+    });
+}
+export default usePagedRowsFilter;
+
+//# sourceMappingURL=use-paged-rows-filter.js.map

package/src/lib/hooks/use-paged-rows-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/hooks/use-paged-rows-filter.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n'use client'\n\nimport { useEffect, useMemo, useRef, useState } from 'react'\nimport {\n  type ListRowsFilter,\n  type ListRowsFilterOptions,\n  useListRowsFilter,\n} from './use-list-rows-filter'\n\n/** How many rows a paged list reads while it is filtered — see below. */\nexport const PAGED_FILTER_WINDOW = 100\n\n/**\n * A paged window over a live list — the shape `usePagedCollection` returns:\n * every row from the first page to the one being read (plus, possibly, one\n * probe row past it), the page, and whether more exist.\n */\nexport interface PagedRowsWindow<Row> {\n  /** Every row read so far, page 0 to the current page; may hold a probe row. */\n  data?: readonly Row[] | null\n  /** The current page's rows, when nothing narrows the list. */\n  rows: readonly Row[]\n  hasMore: boolean\n  page: number\n  setPage: (page: number) => void\n  pageSize: number\n  setPageSize: (pageSize: number) => void\n}\n\n/** What the list's grid, chips and footer take while it is paged. */\nexport interface PagedRowsFilter<Row> extends Omit<ListRowsFilter<Row>, 'rows'> {\n  /** The rows the grid shows: the page, or the page of the matches. */\n  rows: Row[]\n  /** How many rows the window read — what a filter has looked through. */\n  read: number\n  /** Spread onto `ListPagination`. */\n  pagination: {\n    page: number\n    pageSize: number\n    rowCount: number\n    hasMore: boolean\n    onPageChange: (page: number) => void\n    onPageSizeChange: (pageSize: number) => void\n  }\n}\n\n/**\n * The grid's Filters panel and quick search over a PAGED live list\n * (AGL-3317), one that reads a window growing a page at a time rather than\n * every row.\n *\n * Unfiltered it is the pager it wraps: the grid shows the page, and the\n * footer turns it. While a clause or a search word is in force the list\n * matches over EVERYTHING the window has read — every page up to the\n * current one, not the page on screen — and pages the matches instead;\n * turning past the last match widens the window by one more page, so a\n * filter reaches further the further the reader goes. `read` says how far\n * it has looked, for the list to say so while more exist.\n *\n * ## The first filter widens the window once\n *\n * A window of one ten-row page is too little to filter: a search would look\n * through ten rows and call the rest \"no match\". So the first clause or word\n * widens the window to `filterWindow` rows (default\n * {@link PAGED_FILTER_WINDOW}) — one listener that much wider, for as long as\n * the list is narrowed — and clearing the last one puts the reader back on\n * the page they left.\n */\nexport function usePagedRowsFilter<Row extends object>(\n  paged: PagedRowsWindow<Row>,\n  options: Omit<ListRowsFilterOptions<Row>, 'rows'> & { filterWindow?: number },\n): PagedRowsFilter<Row> {\n  const { pageSize } = paged\n  const { filterWindow = PAGED_FILTER_WINDOW, ...filterOptions } = options\n  const windowRows = useMemo(\n    () => (paged.data ?? paged.rows).slice(0, pageSize * (paged.page + 1)),\n    [paged.data, paged.rows, pageSize, paged.page],\n  )\n  const filter = useListRowsFilter({ ...filterOptions, rows: windowRows })\n  const [matchPage, setMatchPage] = useState(0)\n  const searchKey = filter.gridFilter.searchWords.join(' ')\n  // A narrowed list starts again at its first page.\n  useEffect(() => setMatchPage(0), [filter.gridFilter.clauses, searchKey])\n\n  /** The page the reader was on before the list was narrowed. */\n  const before = useRef<number | null>(null)\n  const { filtering } = filter\n  useEffect(() => {\n    if (filtering && before.current === null) {\n      before.current = paged.page\n      const widened = Math.max(0, Math.ceil(filterWindow / pageSize) - 1)\n      if (widened > paged.page) paged.setPage(widened)\n    } else if (!filtering && before.current !== null) {\n      paged.setPage(before.current)\n      before.current = null\n    }\n    // Only the transition into and out of a filter moves the window.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [filtering])\n\n  if (!filter.filtering) {\n    return {\n      ...filter,\n      rows: [...paged.rows],\n      read: windowRows.length,\n      pagination: {\n        page: paged.page,\n        pageSize,\n        rowCount: paged.rows.length,\n        hasMore: paged.hasMore,\n        onPageChange: paged.setPage,\n        onPageSizeChange: paged.setPageSize,\n      },\n    }\n  }\n  const matches = filter.rows\n  const shown = matches.slice(matchPage * pageSize, (matchPage + 1) * pageSize)\n  const lastMatchPage = Math.max(0, Math.ceil(matches.length / pageSize) - 1)\n  return {\n    ...filter,\n    rows: shown,\n    read: windowRows.length,\n    pagination: {\n      page: matchPage,\n      pageSize,\n      rowCount: shown.length,\n      hasMore: paged.hasMore || matchPage < lastMatchPage,\n      onPageChange: (next) => {\n        // Past the matches read so far, the window reads another page first.\n        if ((next + 1) * pageSize > matches.length && paged.hasMore) {\n          paged.setPage(paged.page + 1)\n        }\n        setMatchPage(next)\n      },\n      onPageSizeChange: (next) => {\n        paged.setPageSize(next)\n        setMatchPage(0)\n      },\n    },\n  }\n}\n\nexport default usePagedRowsFilter\n"],"names":["useEffect","useMemo","useRef","useState","useListRowsFilter","PAGED_FILTER_WINDOW","usePagedRowsFilter","paged","options","pageSize","filterWindow","filterOptions","windowRows","data","rows","slice","page","filter","matchPage","setMatchPage","searchKey","gridFilter","searchWords","join","clauses","before","filtering","current","widened","Math","max","ceil","setPage","read","length","pagination","rowCount","hasMore","onPageChange","onPageSizeChange","setPageSize","matches","shown","lastMatchPage","next"],"mappings":"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"}