@aglyn/shared-ui-jsx 1.0.0-beta.198 → 1.0.0-beta.200

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

@@ -1 +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  /*\n   * A column made a select keeps what it DREW. The grid formats a\n   * `singleSelect` cell as the label of the option its value matches, and as\n   * nothing when none does — so a column whose `valueGetter` hands back a\n   * label (an address for an actor id, a site name for a scope id) went\n   * blank the moment it gained a filter (AGL-3321). A column with its own\n   * `renderCell` is left alone; any other draws the matching option's label\n   * when there is one, and its own value when there is not.\n   */\n  const keepsItsCell = (column: GridColDef, field: ListFilterField) => {\n    if (column.renderCell) return {}\n    const labels = new Map(\n      (options[field.column] ?? []).map((choice) => [choice.value, choice.label]),\n    )\n    return {\n      renderCell: (params: { value?: unknown }) => {\n        const value = params.value\n        if (value === undefined || value === null) return ''\n        return labels.get(String(value)) ?? String(value)\n      },\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]) {\n      return { ...column, ...selectProps(field), ...keepsItsCell(column, field) } as GridColDef\n    }\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","keepsItsCell","renderCell","labels","Map","params","get","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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"}
+{"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  getGridBooleanOperators,\n  getGridDateOperators,\n  getGridNumericOperators,\n  getGridSingleSelectOperators,\n  getGridStringOperators,\n  type GridColDef,\n  type GridFilterItem,\n  type GridFilterOperator,\n} from '@mui/x-data-grid'\nimport {\n  gridFilterRequests,\n  type ListFilterField,\n  type ListFilterKind,\n  type ListFilterRequest,\n  listFilterOperators,\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\nconst operatorPool = (kind: ListFilterKind): GridFilterOperator[] => {\n  switch (kind) {\n    case 'boolean':\n      return getGridBooleanOperators()\n    case 'number':\n      return getGridNumericOperators()\n    case 'date':\n      return getGridDateOperators()\n    default:\n      return getGridStringOperators()\n  }\n}\n\n/**\n * The MUI operators for a field — the same list `listFilterOperators` names,\n * resolved to the grid's own operator objects so the panel keeps its native\n * inputs (a date picker for a date, a number field for a number).\n */\nexport function gridFilterOperators(\n  field: ListFilterField,\n): GridFilterOperator[] {\n  const allowed = listFilterOperators(field)\n  return operatorPool(field.kind).filter((operator) =>\n    allowed.includes(operator.value),\n  )\n}\n\n/**\n * Spread onto a `GridColDef` to make a column filterable exactly as far as the\n * query can serve it. A column with NO declared field is turned off entirely —\n * deliberately, because the alternative is a funnel icon that opens a panel\n * nothing honours.\n */\nexport function listFilterColumn(\n  fields: readonly ListFilterField[],\n  column: string,\n): { filterable: boolean; filterOperators?: GridFilterOperator[] } {\n  const field = fields.find((entry) => entry.column === column)\n  if (!field) return { filterable: false }\n  const operators = gridFilterOperators(field)\n  return operators.length\n    ? { filterable: true, filterOperators: operators }\n    : { filterable: false }\n}\n\n/**\n * Fields a reader can filter by that are NOT columns on the table.\n *\n * MUI's filter panel lists COLUMNS — `gridFilterableColumnDefinitionsSelector`\n * reads every column definition, hidden ones included — so a filterable field\n * with no column is a field nobody can reach however well the route answers it.\n * Declaring it as a permanently hidden column keeps one source of truth, the\n * field list, instead of a second list of \"extra filters\" that drifts from it.\n *\n * `hideable: false` keeps them out of Manage columns as well: a column with no\n * `renderCell` and no width has nothing to show, and a reader who unhid one\n * would get a strip of blank cells for their trouble.\n *\n * Pair with {@link hiddenFilterVisibility}, which is what actually hides them.\n */\nexport function hiddenFilterColumns(\n  fields: readonly ListFilterField[],\n  visible: readonly string[],\n  headers: Readonly<Record<string, string>> = {},\n): Array<{\n  field: string\n  headerName: string\n  hideable: boolean\n  filterable: boolean\n  filterOperators?: GridFilterOperator[]\n}> {\n  return fields\n    .filter((field) => !visible.includes(field.column))\n    .map((field) => ({\n      field: field.column,\n      headerName: headers[field.column] ?? field.column,\n      hideable: false,\n      ...listFilterColumn(fields, field.column),\n    }))\n    .filter((column) => column.filterable)\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  /*\n   * A column made a select keeps what it DREW. The grid formats a\n   * `singleSelect` cell as the label of the option its value matches, and as\n   * nothing when none does — so a column whose `valueGetter` hands back a\n   * label (an address for an actor id, a site name for a scope id) went\n   * blank the moment it gained a filter (AGL-3321). A column with its own\n   * `renderCell` is left alone; any other draws the matching option's label\n   * when there is one, and its own value when there is not.\n   */\n  const keepsItsCell = (column: GridColDef, field: ListFilterField) => {\n    if (column.renderCell) return {}\n    const labels = new Map(\n      (options[field.column] ?? []).map((choice) => [choice.value, choice.label]),\n    )\n    return {\n      renderCell: (params: { value?: unknown }) => {\n        const value = params.value\n        if (value === undefined || value === null) return ''\n        return labels.get(String(value)) ?? String(value)\n      },\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]) {\n      return { ...column, ...selectProps(field), ...keepsItsCell(column, field) } as GridColDef\n    }\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 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\nexport { listFilterClauseSentence } from './list-filter-sentence'\n"],"names":["getGridBooleanOperators","getGridDateOperators","getGridNumericOperators","getGridSingleSelectOperators","getGridStringOperators","gridFilterRequests","listFilterOperators","operatorPool","kind","gridFilterOperators","field","allowed","filter","operator","includes","value","listFilterColumn","fields","column","find","entry","filterable","operators","length","filterOperators","hiddenFilterColumns","visible","headers","map","headerName","hideable","SELECT_TO_GRID","equals","doesNotEqual","isAnyOf","SELECT_FROM_GRID","is","not","plainClause","item","items","listPlainCodec","toItem","clause","op","undefined","toClause","listSelectCodec","split","trim","Boolean","String","request","listSelectOperators","shown","listFilterGridColumns","columns","options","selectProps","choices","type","valueOptions","choice","label","keepsItsCell","renderCell","labels","Map","params","get","present","hidden","listRowMatchesSearch","row","paths","words","asked","word","toLowerCase","values","flatMap","path","reduce","at","key","Array","isArray","every","some","upsertListFilterClause","clauses","next","findIndex","rest","slice","listFilterClauseSentence"],"mappings":"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"}

package/src/lib/const/list-query-plan.d.ts

@@ -0,0 +1,170 @@
+/**
+ * @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, type ListFilterRequest } from './list-filter';
+/**
+ * How the written search fields were normalized, so a typed value becomes the
+ * key the query can match: the lower-cased key (`equals`, `startsWith`), the
+ * one word-prefix token (`contains`, search), and the reversed key
+ * (`endsWith`). `maxPrefix` is the longest token a writer stores.
+ */
+export interface ListQueryNormalizers {
+    key(value: string): string;
+    token(value: string): string;
+    reversed(value: string): string;
+    maxPrefix: number;
+}
+/** A predicate on the query, SDK-free. `path` `__name__` is the document id. */
+export type ListQueryOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'array-contains' | 'array-contains-any';
+export type ListQueryValue = string | number | boolean | null | Date | readonly (string | number)[];
+export interface ListQueryFilter {
+    path: string;
+    op: ListQueryOp;
+    value: ListQueryValue;
+}
+export interface ListQuerySort {
+    path: string;
+    direction: 'asc' | 'desc';
+    /** The grid column this order sorts, when the list lets the grid sort by it. */
+    column?: string;
+}
+/** The document id, as a path. */
+export declare const LIST_QUERY_ID_PATH = "__name__";
+/** Firestore's cap on disjunctions — `in` values times `array-contains-any` values. */
+export declare const LIST_QUERY_DISJUNCTIONS = 30;
+export interface ListQueryDeclaration {
+    /** Every field the Filters panel may name. */
+    fields: readonly ListFilterField[];
+    /**
+     * The orders the list offers, its default FIRST. The query takes no other:
+     * each is a composite the index file carries for every filterable field.
+     */
+    sorts: readonly ListQuerySort[];
+    /**
+     * The quick search: the token array every write stamps (see
+     * `nameSearchTokens`), queried with `array-contains` on one typed word.
+     * Absent, the list offers no search box.
+     */
+    search?: {
+        tokensPath: string;
+        /**
+         * Under a scope clause the search cannot be a SECOND array clause, so a
+         * scoped list writes `<scopeToken><join><prefix>` tokens and the query
+         * asks `array-contains-any` over the scope's tokens joined to the word —
+         * one array clause that answers both.
+         *
+         * ⛔ Rules that grant a list from `visibleTo.hasAny(...)` DENY this
+         * query, because it no longer constrains `visibleTo`. Declare it only for
+         * readers whose rule needs no `visibleTo` term, or for an Admin-SDK read;
+         * see `SCOPED_SEARCH_JOIN` in `@aglyn/aglyn/app-utils/name-search`.
+         */
+        scoped?: {
+            tokensPath: string;
+            join: string;
+        };
+    };
+    /**
+     * Keys a presence-map field (`keysOf`) is filtered by, for the index
+     * enumeration: `sources.form`, `sources.order`, …
+     */
+    keys?: Readonly<Record<string, readonly string[]>>;
+}
+/** What the list asks this time. */
+export interface ListQueryRequest {
+    clauses: readonly ListFilterRequest[];
+    /** The quick search's words. */
+    search?: readonly string[];
+    /** The order asked for; a sort the declaration does not offer is ignored. */
+    sort?: ListQuerySort | null;
+    /**
+     * Predicates the list always applies — its scope — which count against
+     * the same limits. An `array-contains-any` scope is what a scoped search
+     * folds into (`declaration.search.scoped`).
+     */
+    base?: readonly ListQueryFilter[];
+}
+export interface ListQueryRefusal {
+    /** The clause refused, or `search`. */
+    clause: ListFilterRequest | 'search';
+    reason: string;
+}
+export interface ListQueryPlan {
+    /** Every predicate, base included, in the order the SDK should add them. */
+    filters: ListQueryFilter[];
+    /** The one order: the range field's when there is one, else the sort. */
+    orderBy: ListQuerySort;
+    /** The clauses on the query. */
+    served: ListFilterRequest[];
+    /** The search word on the query, or null. */
+    searched: string | null;
+    /** What was asked and could not be put on the query, with why. */
+    refused: ListQueryRefusal[];
+    /** Said to the reader about what WAS served — e.g. one search word of two. */
+    notices: string[];
+}
+/**
+ * Every clause and the search, as ONE query — or as much of it as one query
+ * can hold, with the rest refused by name.
+ *
+ * Order of claim: the base (the list's scope) first, then the search, then
+ * the clauses in the order they were added. A clause that would be a second
+ * array clause, a second inequality field or push the disjunctions past
+ * thirty is refused, and the list shows the refusal beside its chip; the
+ * clauses before it stand. The search is claimed before the clauses because
+ * it is the thing a reader typed last and looks at.
+ */
+export declare function planListQuery(declaration: ListQueryDeclaration, request: ListQueryRequest, names: ListQueryNormalizers): ListQueryPlan;
+/** A composite the plan's shapes need, in the index file's own terms. */
+export interface ListQueryIndex {
+    fields: Array<{
+        fieldPath: string;
+        order?: 'ASCENDING' | 'DESCENDING';
+        arrayConfig?: 'CONTAINS';
+    }>;
+}
+/**
+ * Every composite a declaration's queries can need, under index merging:
+ * one `(predicate field, order)` index per equality or array field and per
+ * order the list can take — its sorts, and the order each range imposes.
+ *
+ * `base` names the scope predicates the list always applies (their paths
+ * and whether they are array clauses), which need their own index per order
+ * like any other equality. Pinned by each list's spec against
+ * `cloud/firebase-firestore.indexes.json`.
+ */
+export declare function listQueryIndexes(declaration: ListQueryDeclaration, base?: readonly {
+    path: string;
+    array?: boolean;
+}[]): ListQueryIndex[];
+/** An index entry as `cloud/firebase-firestore.indexes.json` stores it. */
+interface IndexFileEntry {
+    collectionGroup: string;
+    queryScope: string;
+    fields: Array<{
+        fieldPath: string;
+        order?: string;
+        arrayConfig?: string;
+    }>;
+}
+/**
+ * The composites a declaration needs that an index file does not hold — what
+ * a list's spec asserts is empty, so a declared filter cannot ship without
+ * the index that serves it.
+ */
+export declare function missingListQueryIndexes(file: {
+    indexes: readonly IndexFileEntry[];
+}, collectionGroup: string, needed: readonly ListQueryIndex[], queryScope?: 'COLLECTION' | 'COLLECTION_GROUP'): ListQueryIndex[];
+export {};