@ai-matrx/records-ui 0.69.0 → 0.70.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode, ComponentType, RefObject } from 'react';
 import * as _ai_matrx_records from '@ai-matrx/records';
-import { PermissionLevel, Table, RecordScopeContext, EnrichCell, RecordsError, Uuid as Uuid$1, AggregateFilter, Field, RecordDocument, ReadRow, RelationDisplay, WriteConflict, ParityFieldType, NewFieldDeclaration, RuleExpression, ValueEnvelope, ChecklistRequirementKind, ContextPolicy, WorkDueState, FieldSensitivity, StageRuleOnFail, SubscriptionCadence, WorkInboxKind, FieldKind, FormSummary, PortalCard, PortalPrincipal, PortalPreviewRow, DashboardBlockKind, AggregateBucket, AggregateMeasure, DashboardBlock, DashboardSummary, DocTemplateRow, DocRenderRow, QuietHours, DashboardBlockResult, ChecklistRunStep, BookingSummary, CaptureSheetFace, CaptureField, AnonTokenBinding, RecordsConfig, RecordsActor, RecordsDataSource, HistoryActor, FieldHistoryEntry, FieldTypeWord } from '@ai-matrx/records';
-import { Uuid, Field as Field$1, ReadRow as ReadRow$1 } from '@ai-matrx/records/react';
+import { PermissionLevel, Table, RecordScopeContext, EnrichCell, RecordsError, Uuid as Uuid$1, AggregateFilter, Field, RecordDocument, ReadRow, RelationDisplay, WriteConflict, ParityFieldType, NewFieldDeclaration, RuleExpression, ValueEnvelope, ChecklistRequirementKind, ContextPolicy, WorkDueState, FieldSensitivity, StageRuleOnFail, SubscriptionCadence, WorkInboxKind, FieldKind, RecordFilter as RecordFilter$1, FormSummary, PortalCard, PortalPrincipal, PortalPreviewRow, DashboardBlockKind, AggregateBucket, AggregateMeasure, DashboardBlock, DashboardSummary, DocTemplateRow, DocRenderRow, QuietHours, DashboardBlockResult, ChecklistRunStep, BookingSummary, CaptureSheetFace, CaptureField, AnonTokenBinding, RecordsConfig, RecordsActor, RecordsDataSource, HistoryActor, FieldHistoryEntry, FieldTypeWord } from '@ai-matrx/records';
+import { Uuid, RecordFilter, Field as Field$1, ReadRow as ReadRow$1 } from '@ai-matrx/records/react';
 import { RecordsClient } from '@ai-matrx/records/core';
 import { FieldFormatConfig } from '@ai-matrx/design-system/field-formats';
 import { MatrxColumnDef } from '@ai-matrx/design-system/data-table/types';
@@ -1040,6 +1040,16 @@ interface GridProps {
     tableId: Uuid;
     /** Rows per page. The table's own pagination handles the rest. */
     pageSize?: number | undefined;
+    /**
+     * THE QUESTION THIS GRID IS ANSWERING, in the store's one filter shape.
+     *
+     * Left out, it is the whole table. Supplied — a dashboard number was clicked,
+     * or a saved view carries `filters` — the STORE narrows the page inside its
+     * own query. Never filter `rows` here: this grid only ever holds one page,
+     * so filtering in the browser would drop every matching record on page two
+     * and call the result the answer.
+     */
+    filter?: RecordFilter | undefined;
     /** Opened when a row is clicked. A host that has a record page passes its own. */
     onOpenRecord?: ((recordId: Uuid) => void) | undefined;
     /** SCR-2. Called when an admin clicks the "+" at the end of the headers. */
@@ -1093,7 +1103,7 @@ interface GridProps {
     onPresentationChange?: ((next: GridPresentation) => void) | undefined;
     className?: string | undefined;
 }
-declare function Grid({ tableId, pageSize, onOpenRecord, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, className, onAskWhoChanged, }: GridProps): react.JSX.Element;
+declare function Grid({ tableId, pageSize, filter, onOpenRecord, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, className, onAskWhoChanged, }: GridProps): react.JSX.Element;
 /**
  * One Field becomes one column. The header is the Field's own NAME — never its
  * key (`names.ts`) — and the cell is the value, rendered by its parity type and
@@ -1817,17 +1827,24 @@ interface ViewSwitcherProps {
     /** "Who changed this?" from a grid cell — the host opens that column's timeline. */
     onAskWhoChanged?: ((fieldKey: string, recordId: Uuid) => void) | undefined;
     pageSize?: number | undefined;
+    /**
+     * THE QUESTION THE ADDRESS ASKED, in the store's one filter shape — the same
+     * object the chart counted with. It narrows the grid AND the board through
+     * the store, so switching layout after a drill-through keeps the same rows
+     * instead of quietly widening back to the whole table.
+     */
+    filter?: RecordFilter$1 | undefined;
     className?: string | undefined;
 }
 /** The records this view holds: its Rule's members when it names one, the table otherwise. */
-declare function useViewRecords(view: SavedViewSpec, pageSize?: number): {
+declare function useViewRecords(view: SavedViewSpec, pageSize?: number, filter?: RecordFilter$1): {
     rows: ReadRow$1[];
     loading: boolean;
     error: RecordsError | null;
     /** Where membership came from, in a sentence. A screen that hides this is hiding the view's meaning. */
     membership: string;
 };
-declare function ViewSwitcher({ view, onLayoutChange, onViewChange, onOpenRecord, onMoved, onNewRecordForm, onAskWhoChanged, pageSize, className, }: ViewSwitcherProps): react.JSX.Element;
+declare function ViewSwitcher({ view, onLayoutChange, onViewChange, onOpenRecord, onMoved, onNewRecordForm, onAskWhoChanged, pageSize, filter, className, }: ViewSwitcherProps): react.JSX.Element;
 
 interface ViewBarProps {
     /** The Table whose views these are. */
@@ -2169,8 +2186,16 @@ interface DigestSchedulerProps {
      * view's name, so nothing in the list is called "Saved view".
      */
     subjectName?: string | null | undefined;
-    /** The filters of the thing being scheduled, written straight into the saved view. */
-    filters?: Record<string, unknown> | null | undefined;
+    /**
+     * The filters of the thing being scheduled, written straight into the saved
+     * view — in the store's ONE filter shape (`RecordFilter`), which is what
+     * `custom.view_declare` stores, what `custom.agg_view_admits` reads to decide
+     * whether a change belongs to this view, and what the read and aggregate
+     * doors both take. It was `Record<string, unknown>` until DRILL named the
+     * shape: an unknown here is a subscription that silently notifies about the
+     * wrong records.
+     */
+    filters?: RecordFilter$1 | null | undefined;
     onScheduled?: (() => void) | undefined;
     onClose?: (() => void) | undefined;
     className?: string | undefined;
@@ -2892,14 +2917,12 @@ interface TablePageProps {
     /**
      * WHICH FIELD THE ADDRESS WANTS THE BOARD'S COLUMNS TO BE, for this visit.
      *
-     * 🚨 THIS IS HOW A DASHBOARD NUMBER CLICKS THROUGH (lane TAILS-6, 2026-09-22).
-     * Until today the canvas told the owner of the business to "bind `openRecords`
-     * on <RecordsUiProvider>" — a developer's sentence on a customer's screen —
-     * because nothing in this app routed a bar or a slice anywhere. The store has
-     * no door that returns the ROWS behind an aggregate filter, so a click cannot
-     * honestly promise a narrowed list; what it CAN do is open this table's board
-     * with its columns set to the very field the chart grouped by, where the
-     * column the person clicked is right there and every card in it is real.
+     * 🚨 THIS IS HALF OF HOW A DASHBOARD NUMBER CLICKS THROUGH (lane TAILS-6,
+     * 2026-09-22): the board opens with its columns set to the very field the
+     * chart grouped by, so the column the person clicked is right there. The
+     * other half is `filter`, which lane DRILL added hours later once the store
+     * grew `custom.read_records_matching` — until then a click could only widen,
+     * and the sentence under the board said so out loud.
      *
      * It overrides the saved view's own `groupField` for this visit only, exactly
      * as `activeView` overrides its layout, and it is never written back.
@@ -2908,40 +2931,48 @@ interface TablePageProps {
     /**
      * WHAT THE PERSON CLICKED TO GET HERE — "Jobs by stage · Awaiting parts".
      *
-     * Present, the board says where they came from AND says plainly that it is
-     * showing every record grouped by that field rather than only the ones the
-     * number counted. A screen that quietly showed more rows than the number
-     * promised would be the number lying twice.
+     * Present, the board says where they came from AND, when `filter` came with
+     * it, which question is holding the rest of the table back. A screen showing
+     * a subset without saying so is a table lying about how much of itself it is
+     * — and one showing MORE rows than the number promised is the number lying
+     * twice.
      */
     cameFrom?: string | null | undefined;
+    /**
+     * WHICH RECORDS THE ADDRESS ASKED FOR, in the store's one filter shape.
+     *
+     * 🚨 THIS IS WHAT MAKES A DASHBOARD NUMBER WALKABLE (lane DRILL, 2026-09-22).
+     * TAILS-6 could route a bar click here but could not narrow anything: the
+     * store had no door that took a filter, so the click opened the WHOLE table
+     * and a sentence underneath said so. `custom.read_records_matching` takes the
+     * same object the chart counted with, and this prop is how the address hands
+     * it to the grid and the board — both of them, so switching layout does not
+     * quietly widen back to every record.
+     *
+     * It is a QUESTION for this visit, exactly like `activeView` and
+     * `activeGroupField`, and is never written onto the saved view.
+     */
+    filter?: RecordFilter$1 | null | undefined;
     className?: string | undefined;
 }
-/**
- * THE SENTENCE A TABLE YOU CANNOT SEE SAYS.
- *
- * Measured on the real screen (independent verdict, 19 September): opening a
- * table's page while another organization was active left the main area's text
- * "literally the empty string" after eighteen seconds — no sentence, no
- * spinner, no console error. A made-up id did the same. The cause is exactly
- * one line of this file: `custom.table_list` correctly answers the tables this
- * person can see in THIS organization, the table is not among them, so
- * `useTable` answers `{ data: null, error: null }` — not a refusal, just
- * absence — and the page rendered a skeleton for ever.
- *
- * Absence is an ANSWER and it gets a sentence. It deliberately does not say
- * whether the table exists: this person cannot see it, and which of the two it
- * is is not theirs to learn.
- */
 /**
  * WHAT THE BOARD SAYS TO SOMEBODY A DASHBOARD NUMBER SENT HERE.
  *
- * It says two things and neither is optional: which number they clicked, and
- * that this is every record grouped by that field rather than only the ones the
- * number counted. The store has no door that returns the rows behind an
- * aggregate filter, so claiming a narrowed list would be a lie — and showing a
- * wider one silently would be the same lie with nobody told.
- */
-declare function cameFromLine(label: string, groupField: string | null): string;
+ * 🚨 IT USED TO SAY THE OPPOSITE, AND IT WAS TELLING THE TRUTH WHEN IT DID.
+ * Until 2026-09-22 this sentence read "This is every record grouped into the
+ * same columns the chart used — not only the ones that number counted",
+ * because `custom.read_records` took no filter and `custom.record_aggregate`
+ * answers groups and counts, never ids: the store had no door that could open
+ * the rows behind a number, so claiming a narrowed list would have been a lie.
+ * `custom.read_records_matching` is that door, and it evaluates the question
+ * through the very same `custom.record_filter_sql` the number was counted
+ * with — so this now says the narrow thing, and means it.
+ *
+ * It still says both halves out loud: which number they clicked, and WHICH
+ * QUESTION is holding rows back. A screen showing a subset without saying so
+ * is a table lying about how much of itself it is.
+ */
+declare function cameFromLine(label: string, groupField: string | null, question?: string | null): string;
 declare const TABLE_NOT_REACHABLE: string;
 /**
  * THE VIEW EVERY TABLE HAS, AND WHY IT IS NOT OPTIONAL.
@@ -3050,7 +3081,7 @@ declare function openingView(activeView: string | null | undefined, activeDashbo
     layout: ViewLayout | null;
     unknown: string | null;
 };
-declare function TablePage({ tableId, pageSize, seedViews, onLeave, leaveLabel, activeDashboardId, activeRecordId, activeView, onViewChanged, activeGroupField, cameFrom, className, }: TablePageProps): react.JSX.Element;
+declare function TablePage({ tableId, pageSize, seedViews, onLeave, leaveLabel, activeDashboardId, activeRecordId, activeView, onViewChanged, activeGroupField, cameFrom, filter, className, }: TablePageProps): react.JSX.Element;
 
 /** What the roster can tell us about a user id. `null` when it cannot. */
 type ResolveName = (userId: Uuid$1) => string | null;

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode, ComponentType, RefObject } from 'react';
 import * as _ai_matrx_records from '@ai-matrx/records';
-import { PermissionLevel, Table, RecordScopeContext, EnrichCell, RecordsError, Uuid as Uuid$1, AggregateFilter, Field, RecordDocument, ReadRow, RelationDisplay, WriteConflict, ParityFieldType, NewFieldDeclaration, RuleExpression, ValueEnvelope, ChecklistRequirementKind, ContextPolicy, WorkDueState, FieldSensitivity, StageRuleOnFail, SubscriptionCadence, WorkInboxKind, FieldKind, FormSummary, PortalCard, PortalPrincipal, PortalPreviewRow, DashboardBlockKind, AggregateBucket, AggregateMeasure, DashboardBlock, DashboardSummary, DocTemplateRow, DocRenderRow, QuietHours, DashboardBlockResult, ChecklistRunStep, BookingSummary, CaptureSheetFace, CaptureField, AnonTokenBinding, RecordsConfig, RecordsActor, RecordsDataSource, HistoryActor, FieldHistoryEntry, FieldTypeWord } from '@ai-matrx/records';
-import { Uuid, Field as Field$1, ReadRow as ReadRow$1 } from '@ai-matrx/records/react';
+import { PermissionLevel, Table, RecordScopeContext, EnrichCell, RecordsError, Uuid as Uuid$1, AggregateFilter, Field, RecordDocument, ReadRow, RelationDisplay, WriteConflict, ParityFieldType, NewFieldDeclaration, RuleExpression, ValueEnvelope, ChecklistRequirementKind, ContextPolicy, WorkDueState, FieldSensitivity, StageRuleOnFail, SubscriptionCadence, WorkInboxKind, FieldKind, RecordFilter as RecordFilter$1, FormSummary, PortalCard, PortalPrincipal, PortalPreviewRow, DashboardBlockKind, AggregateBucket, AggregateMeasure, DashboardBlock, DashboardSummary, DocTemplateRow, DocRenderRow, QuietHours, DashboardBlockResult, ChecklistRunStep, BookingSummary, CaptureSheetFace, CaptureField, AnonTokenBinding, RecordsConfig, RecordsActor, RecordsDataSource, HistoryActor, FieldHistoryEntry, FieldTypeWord } from '@ai-matrx/records';
+import { Uuid, RecordFilter, Field as Field$1, ReadRow as ReadRow$1 } from '@ai-matrx/records/react';
 import { RecordsClient } from '@ai-matrx/records/core';
 import { FieldFormatConfig } from '@ai-matrx/design-system/field-formats';
 import { MatrxColumnDef } from '@ai-matrx/design-system/data-table/types';
@@ -1040,6 +1040,16 @@ interface GridProps {
     tableId: Uuid;
     /** Rows per page. The table's own pagination handles the rest. */
     pageSize?: number | undefined;
+    /**
+     * THE QUESTION THIS GRID IS ANSWERING, in the store's one filter shape.
+     *
+     * Left out, it is the whole table. Supplied — a dashboard number was clicked,
+     * or a saved view carries `filters` — the STORE narrows the page inside its
+     * own query. Never filter `rows` here: this grid only ever holds one page,
+     * so filtering in the browser would drop every matching record on page two
+     * and call the result the answer.
+     */
+    filter?: RecordFilter | undefined;
     /** Opened when a row is clicked. A host that has a record page passes its own. */
     onOpenRecord?: ((recordId: Uuid) => void) | undefined;
     /** SCR-2. Called when an admin clicks the "+" at the end of the headers. */
@@ -1093,7 +1103,7 @@ interface GridProps {
     onPresentationChange?: ((next: GridPresentation) => void) | undefined;
     className?: string | undefined;
 }
-declare function Grid({ tableId, pageSize, onOpenRecord, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, className, onAskWhoChanged, }: GridProps): react.JSX.Element;
+declare function Grid({ tableId, pageSize, filter, onOpenRecord, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, className, onAskWhoChanged, }: GridProps): react.JSX.Element;
 /**
  * One Field becomes one column. The header is the Field's own NAME — never its
  * key (`names.ts`) — and the cell is the value, rendered by its parity type and
@@ -1817,17 +1827,24 @@ interface ViewSwitcherProps {
     /** "Who changed this?" from a grid cell — the host opens that column's timeline. */
     onAskWhoChanged?: ((fieldKey: string, recordId: Uuid) => void) | undefined;
     pageSize?: number | undefined;
+    /**
+     * THE QUESTION THE ADDRESS ASKED, in the store's one filter shape — the same
+     * object the chart counted with. It narrows the grid AND the board through
+     * the store, so switching layout after a drill-through keeps the same rows
+     * instead of quietly widening back to the whole table.
+     */
+    filter?: RecordFilter$1 | undefined;
     className?: string | undefined;
 }
 /** The records this view holds: its Rule's members when it names one, the table otherwise. */
-declare function useViewRecords(view: SavedViewSpec, pageSize?: number): {
+declare function useViewRecords(view: SavedViewSpec, pageSize?: number, filter?: RecordFilter$1): {
     rows: ReadRow$1[];
     loading: boolean;
     error: RecordsError | null;
     /** Where membership came from, in a sentence. A screen that hides this is hiding the view's meaning. */
     membership: string;
 };
-declare function ViewSwitcher({ view, onLayoutChange, onViewChange, onOpenRecord, onMoved, onNewRecordForm, onAskWhoChanged, pageSize, className, }: ViewSwitcherProps): react.JSX.Element;
+declare function ViewSwitcher({ view, onLayoutChange, onViewChange, onOpenRecord, onMoved, onNewRecordForm, onAskWhoChanged, pageSize, filter, className, }: ViewSwitcherProps): react.JSX.Element;
 
 interface ViewBarProps {
     /** The Table whose views these are. */
@@ -2169,8 +2186,16 @@ interface DigestSchedulerProps {
      * view's name, so nothing in the list is called "Saved view".
      */
     subjectName?: string | null | undefined;
-    /** The filters of the thing being scheduled, written straight into the saved view. */
-    filters?: Record<string, unknown> | null | undefined;
+    /**
+     * The filters of the thing being scheduled, written straight into the saved
+     * view — in the store's ONE filter shape (`RecordFilter`), which is what
+     * `custom.view_declare` stores, what `custom.agg_view_admits` reads to decide
+     * whether a change belongs to this view, and what the read and aggregate
+     * doors both take. It was `Record<string, unknown>` until DRILL named the
+     * shape: an unknown here is a subscription that silently notifies about the
+     * wrong records.
+     */
+    filters?: RecordFilter$1 | null | undefined;
     onScheduled?: (() => void) | undefined;
     onClose?: (() => void) | undefined;
     className?: string | undefined;
@@ -2892,14 +2917,12 @@ interface TablePageProps {
     /**
      * WHICH FIELD THE ADDRESS WANTS THE BOARD'S COLUMNS TO BE, for this visit.
      *
-     * 🚨 THIS IS HOW A DASHBOARD NUMBER CLICKS THROUGH (lane TAILS-6, 2026-09-22).
-     * Until today the canvas told the owner of the business to "bind `openRecords`
-     * on <RecordsUiProvider>" — a developer's sentence on a customer's screen —
-     * because nothing in this app routed a bar or a slice anywhere. The store has
-     * no door that returns the ROWS behind an aggregate filter, so a click cannot
-     * honestly promise a narrowed list; what it CAN do is open this table's board
-     * with its columns set to the very field the chart grouped by, where the
-     * column the person clicked is right there and every card in it is real.
+     * 🚨 THIS IS HALF OF HOW A DASHBOARD NUMBER CLICKS THROUGH (lane TAILS-6,
+     * 2026-09-22): the board opens with its columns set to the very field the
+     * chart grouped by, so the column the person clicked is right there. The
+     * other half is `filter`, which lane DRILL added hours later once the store
+     * grew `custom.read_records_matching` — until then a click could only widen,
+     * and the sentence under the board said so out loud.
      *
      * It overrides the saved view's own `groupField` for this visit only, exactly
      * as `activeView` overrides its layout, and it is never written back.
@@ -2908,40 +2931,48 @@ interface TablePageProps {
     /**
      * WHAT THE PERSON CLICKED TO GET HERE — "Jobs by stage · Awaiting parts".
      *
-     * Present, the board says where they came from AND says plainly that it is
-     * showing every record grouped by that field rather than only the ones the
-     * number counted. A screen that quietly showed more rows than the number
-     * promised would be the number lying twice.
+     * Present, the board says where they came from AND, when `filter` came with
+     * it, which question is holding the rest of the table back. A screen showing
+     * a subset without saying so is a table lying about how much of itself it is
+     * — and one showing MORE rows than the number promised is the number lying
+     * twice.
      */
     cameFrom?: string | null | undefined;
+    /**
+     * WHICH RECORDS THE ADDRESS ASKED FOR, in the store's one filter shape.
+     *
+     * 🚨 THIS IS WHAT MAKES A DASHBOARD NUMBER WALKABLE (lane DRILL, 2026-09-22).
+     * TAILS-6 could route a bar click here but could not narrow anything: the
+     * store had no door that took a filter, so the click opened the WHOLE table
+     * and a sentence underneath said so. `custom.read_records_matching` takes the
+     * same object the chart counted with, and this prop is how the address hands
+     * it to the grid and the board — both of them, so switching layout does not
+     * quietly widen back to every record.
+     *
+     * It is a QUESTION for this visit, exactly like `activeView` and
+     * `activeGroupField`, and is never written onto the saved view.
+     */
+    filter?: RecordFilter$1 | null | undefined;
     className?: string | undefined;
 }
-/**
- * THE SENTENCE A TABLE YOU CANNOT SEE SAYS.
- *
- * Measured on the real screen (independent verdict, 19 September): opening a
- * table's page while another organization was active left the main area's text
- * "literally the empty string" after eighteen seconds — no sentence, no
- * spinner, no console error. A made-up id did the same. The cause is exactly
- * one line of this file: `custom.table_list` correctly answers the tables this
- * person can see in THIS organization, the table is not among them, so
- * `useTable` answers `{ data: null, error: null }` — not a refusal, just
- * absence — and the page rendered a skeleton for ever.
- *
- * Absence is an ANSWER and it gets a sentence. It deliberately does not say
- * whether the table exists: this person cannot see it, and which of the two it
- * is is not theirs to learn.
- */
 /**
  * WHAT THE BOARD SAYS TO SOMEBODY A DASHBOARD NUMBER SENT HERE.
  *
- * It says two things and neither is optional: which number they clicked, and
- * that this is every record grouped by that field rather than only the ones the
- * number counted. The store has no door that returns the rows behind an
- * aggregate filter, so claiming a narrowed list would be a lie — and showing a
- * wider one silently would be the same lie with nobody told.
- */
-declare function cameFromLine(label: string, groupField: string | null): string;
+ * 🚨 IT USED TO SAY THE OPPOSITE, AND IT WAS TELLING THE TRUTH WHEN IT DID.
+ * Until 2026-09-22 this sentence read "This is every record grouped into the
+ * same columns the chart used — not only the ones that number counted",
+ * because `custom.read_records` took no filter and `custom.record_aggregate`
+ * answers groups and counts, never ids: the store had no door that could open
+ * the rows behind a number, so claiming a narrowed list would have been a lie.
+ * `custom.read_records_matching` is that door, and it evaluates the question
+ * through the very same `custom.record_filter_sql` the number was counted
+ * with — so this now says the narrow thing, and means it.
+ *
+ * It still says both halves out loud: which number they clicked, and WHICH
+ * QUESTION is holding rows back. A screen showing a subset without saying so
+ * is a table lying about how much of itself it is.
+ */
+declare function cameFromLine(label: string, groupField: string | null, question?: string | null): string;
 declare const TABLE_NOT_REACHABLE: string;
 /**
  * THE VIEW EVERY TABLE HAS, AND WHY IT IS NOT OPTIONAL.
@@ -3050,7 +3081,7 @@ declare function openingView(activeView: string | null | undefined, activeDashbo
     layout: ViewLayout | null;
     unknown: string | null;
 };
-declare function TablePage({ tableId, pageSize, seedViews, onLeave, leaveLabel, activeDashboardId, activeRecordId, activeView, onViewChanged, activeGroupField, cameFrom, className, }: TablePageProps): react.JSX.Element;
+declare function TablePage({ tableId, pageSize, seedViews, onLeave, leaveLabel, activeDashboardId, activeRecordId, activeView, onViewChanged, activeGroupField, cameFrom, filter, className, }: TablePageProps): react.JSX.Element;
 
 /** What the roster can tell us about a user id. `null` when it cannot. */
 type ResolveName = (userId: Uuid$1) => string | null;

package/dist/index.js

@@ -3332,6 +3332,7 @@ var NO_COLUMNS_WHY = "A column is what a record holds \u2014 a name, a date, an
 function Grid({
   tableId,
   pageSize = 50,
+  filter,
   onOpenRecord,
   onAddField,
   onNewRecordForm,
@@ -3347,7 +3348,7 @@ function Grid({
   const table = useTable2(tableId);
   const fields = useFields3(tableId);
   const [page, setPage] = useState10(0);
-  const records = useRecords2(tableId, { pageSize, page });
+  const records = useRecords2(tableId, { pageSize, page, ...filter ? { filter } : {} });
   const rights = useTableRights(table.data);
   const rows = useMemo9(() => records.data?.rows ?? [], [records.data]);
   const rowIds = useMemo9(() => rows.map((row) => row.id), [rows]);
@@ -7131,9 +7132,12 @@ function unplacedName(record, field, labels) {
 // src/ViewSwitcher.tsx
 import { jsx as jsx26, jsxs as jsxs22 } from "react/jsx-runtime";
 var NO_FIELDS = [];
-function useViewRecords(view, pageSize = 200) {
+function useViewRecords(view, pageSize = 200, filter) {
   const client = useRecordsClient16();
-  const table = useRecords5(view.ruleId ? null : view.subject, { pageSize });
+  const table = useRecords5(view.ruleId ? null : view.subject, {
+    pageSize,
+    ...filter ? { filter } : {}
+  });
   const [ruled, setRuled] = useState24({
     rows: [],
     loading: Boolean(view.ruleId),
@@ -7188,6 +7192,7 @@ function ViewSwitcher({
   onNewRecordForm,
   onAskWhoChanged,
   pageSize = 200,
+  filter,
   className
 }) {
   const [layout, setLayout] = useState24(view.layout);
@@ -7225,6 +7230,7 @@ function ViewSwitcher({
       {
         tableId: view.subject,
         pageSize,
+        ...filter ? { filter } : {},
         ...local.presentation ?? view.presentation ? { presentation: local.presentation ?? view.presentation } : {},
         ...onViewChange ? { onPresentationChange: (next) => change({ presentation: next }) } : {},
         ...onOpenRecord ? { onOpenRecord } : {},
@@ -7236,6 +7242,7 @@ function ViewSwitcher({
       {
         view: { ...view, ...local, layout },
         pageSize,
+        ...filter ? { filter } : {},
         onChange: change,
         remembered: Boolean(onViewChange),
         ...onOpenRecord ? { onOpenRecord } : {},
@@ -7283,13 +7290,14 @@ function boardColumnChoice(fields, chosenKey, stage) {
 function Board({
   view,
   pageSize,
+  filter,
   onChange,
   remembered,
   onOpenRecord,
   onMoved
 }) {
   const fields = useFields12(view.subject);
-  const records = useViewRecords(view, pageSize);
+  const records = useViewRecords(view, pageSize, filter);
   const stage = useStageField(view.subject);
   if (fields.error) return /* @__PURE__ */ jsx26(RefusalNotice, { error: fields.error });
   if (records.error) return /* @__PURE__ */ jsx26(RefusalNotice, { error: records.error });
@@ -12852,14 +12860,20 @@ function DashboardCanvas({ tableId, activeDashboardId, filter, className }) {
         rights.admin ? /* @__PURE__ */ jsx47(Button39, { size: "sm", variant: "ghost", onClick: () => void remove(board), children: "Delete" }) : null
       ] }) : null
     ] }),
-    board && scheduling ? /* @__PURE__ */ jsx47(
-      DigestScheduler,
-      {
-        tableId,
-        subjectName: board.name,
-        ...filter ? { filters: filter } : {},
-        onClose: () => setScheduling(false)
-      }
+    board && scheduling ? (
+      // ONE SHAPE, SO NO CAST. The dashboard's own filter, the saved view it
+      // schedules over and the drill-through it opens are all the same
+      // `RecordFilter`; the `as Record<string, unknown>` that used to be here
+      // was the seam where they could have drifted.
+      /* @__PURE__ */ jsx47(
+        DigestScheduler,
+        {
+          tableId,
+          subjectName: board.name,
+          ...filter ? { filters: filter } : {},
+          onClose: () => setScheduling(false)
+        }
+      )
     ) : null,
     board ? /* @__PURE__ */ jsxs43("div", { className: "flex flex-col gap-1", children: [
       /* @__PURE__ */ jsxs43("div", { className: "flex items-center gap-1", children: [
@@ -14862,12 +14876,38 @@ function TablesHome({ onOpenTable, className }) {
 
 // src/TablePage.tsx
 import { useCallback as useCallback37, useEffect as useEffect41, useState as useState53 } from "react";
-import { useRecordsClient as useRecordsClient43, useTable as useTable22 } from "@ai-matrx/records/react";
+import { useFields as useFields23, useRecordsClient as useRecordsClient43, useTable as useTable22 } from "@ai-matrx/records/react";
 import { Button as Button48, Separator as Separator12, Skeleton as Skeleton34, cn as cn51 } from "@ai-matrx/design-system";
 import { Fragment as Fragment28, jsx as jsx58, jsxs as jsxs53 } from "react/jsx-runtime";
-function cameFromLine(label, groupField) {
-  const grouped = groupField ? `grouped into the same columns the chart used` : `for this table`;
-  return `You came here from \u201C${label}\u201D. This is every record ${grouped} \u2014 not only the ones that number counted \u2014 so the column you clicked is here with the rest beside it.`;
+function filterInWords(filter, fields) {
+  const nameOf = (key) => {
+    const field = fields.find((f) => f.key === key);
+    return field ? fieldName(field) : humanize(key);
+  };
+  const parts = Object.keys(filter).map((key) => {
+    const value = filter[key];
+    if (value === null || value === void 0) return `${nameOf(key)} is not filled in`;
+    if (typeof value === "object") {
+      const from = (value.from ?? "").toString().trim();
+      const to = (value.to ?? "").toString().trim();
+      if (from !== "" && to !== "") return `${nameOf(key)} from ${from} up to ${to}`;
+      if (from !== "") return `${nameOf(key)} from ${from} onwards`;
+      if (to !== "") return `${nameOf(key)} up to ${to}`;
+      return `${nameOf(key)} in a period nobody named`;
+    }
+    return `${nameOf(key)} is ${String(value)}`;
+  });
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0];
+  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+function cameFromLine(label, groupField, question) {
+  const asked = (question ?? "").trim();
+  if (asked === "") {
+    const grouped = groupField ? " grouped into the same columns the chart used" : "";
+    return `You came here from \u201C${label}\u201D. This is every record in this table${grouped} \u2014 that number was counted over all of them.`;
+  }
+  return `You came here from \u201C${label}\u201D. These are only the records that number counted: ${asked}. Everything else in this table is being held back \u2014 clear the filter to see all of it.`;
 }
 var TABLE_NOT_REACHABLE = "This table is not in the organization you are working in, so there is nothing here to show. Switch to the organization that owns it and open it again \u2014 or it may have been deleted.";
 var DEFAULT_VIEW_NAME = "All records";
@@ -14914,11 +14954,14 @@ function TablePage({
   onViewChanged,
   activeGroupField,
   cameFrom,
+  filter,
   className
 }) {
   const client = useRecordsClient43();
   const table = useTable22(tableId);
   const rights = useTableRights(table.data);
+  const pageFields = useFields23(filter ? tableId : null);
+  const askedInWords = filter ? filterInWords(filter, pageFields.data ?? []) : null;
   const organizationId = useRecordsClient43().config.organizationId;
   const [view, setView] = useState53(null);
   const opening = openingRail(activeRecordId);
@@ -15112,7 +15155,7 @@ function TablePage({
           {
             "data-testid": "came-from-a-number",
             className: "rounded-md border px-3 py-2 text-xs leading-relaxed text-muted-foreground",
-            children: cameFromLine(cameFrom, activeGroupField ?? null)
+            children: cameFromLine(cameFrom, activeGroupField ?? null, askedInWords)
           }
         ) : null,
         /* @__PURE__ */ jsx58(
@@ -15126,6 +15169,7 @@ function TablePage({
               ...activeGroupField ? { groupField: activeGroupField } : {}
             },
             pageSize,
+            ...filter ? { filter } : {},
             onLayoutChange: (layout) => {
               setLayoutFromLink(layout);
               onViewChanged?.(layout);