@ai-matrx/records-ui 0.107.5 → 0.109.1

package/dist/first-page.d.cts

@@ -0,0 +1,320 @@
+import { Uuid, RecordFilter, RuleExpression, RecordPageSort, RecordsConfig, Table, Field } from '@ai-matrx/records';
+import { RecordsSeed, RecordsClient } from '@ai-matrx/records/core';
+import { TableStyle, GroupAggregateSpec, GroupOrder } from '@ai-matrx/design-system/data-table';
+import { FieldFormatConfig } from '@ai-matrx/design-system/field-formats';
+
+/**
+ * HOW A TABLE LOOKS — colors, formats and the frozen column.
+ *
+ * THE SPLIT, AND WHY IT IS THIS ONE. A Field declares WHAT it holds: a
+ * currency, a percent, a date, a person. A VIEW declares HOW that reads and
+ * what it is worth looking at: two decimal places or none, tint the row when
+ * Status is Blocked, keep Name in place while the rest scrolls. Airtable draws
+ * the line in exactly this place, and it has to be here: two people read one
+ * table two different ways, and neither reading is a fact about the records.
+ *
+ * So nothing in this module is a new column on a Field and nothing here needed
+ * a migration. A presentation lives on the saved-view record (`views.ts`), which
+ * is an ordinary record of an ordinary Table — which means an agent sets it
+ * through the same `records` tool it uses for everything else, and it travels
+ * with the table the way every other record does.
+ *
+ * A FIELD STILL GETS ITS MONEY RIGHT WITH NO CONFIGURATION. `formatForField`
+ * reads the Field's OWN declaration — a `currency` parity type with unit `$`, a
+ * `percent`, a `datetime` with `config.kind` — and returns the format that
+ * follows from it. The view's `formats` map only OVERRIDES that. A table nobody
+ * has ever styled still shows `$1,250.50` and `45%`.
+ */
+
+/**
+ * SECTIONS BY A FIELD — the view's own grouping.
+ *
+ * `field` is a Field KEY, exactly like `frozen` and the keys of `formats`,
+ * because a view is written against the Table's declaration and never against
+ * whatever id a screen happened to build its columns with.
+ *
+ * `aggregates` is keyed by Field key too, and `collapsed` holds the data
+ * table's own group keys (`s:Blocked`, `n:3`, `empty`), which is what the
+ * primitive emits and the only thing that survives a value rendering the same
+ * text as another.
+ *
+ * NOTHING HERE IS EVER CALLED `valueOf`, `toString` or `hasOwnProperty`: every
+ * object in JavaScript already has all three, so an optional field by one of
+ * those names is NEVER absent and a `config.valueOf ? … : …` check silently
+ * reads `Object.prototype`. It cost the primitive a whole grouping once.
+ */
+type GridGrouping = {
+    /** The Field key whose value makes the sections. */
+    field: string;
+    /** Per-Field-key subtotal on every section header. */
+    aggregates?: Record<string, GroupAggregateSpec>;
+    /** Section order. The primitive's default is `value-asc`; blanks sort last. */
+    order?: GroupOrder;
+    /** The sections this view keeps shut, by the primitive's own group key. */
+    collapsed?: string[];
+    /** The grouped column drawn as a column too. Absent = it steps aside (the headers name its value). */
+    showColumn?: boolean;
+    /**
+     * SUB-GROUPS (lane S1-PRIME VIEW-KEYS; ui-bench LISTS "sub-grouping"): up to two more levels
+     * inside each section, by Field key. At most three levels in all — the store refuses a fourth
+     * (`custom.view_declare`). A layout that draws one level ignores the rest; it never drops them,
+     * because this list is parsed and written back whole with the rest of the look.
+     */
+    then?: GridSubGroup[];
+    /**
+     * DRILL (lane DRILL-TABLE-PRIMITIVE): the Dimension pivoted across the top — a Field key, or
+     * `<key>:<grain>` for a date cut into periods.
+     */
+    across?: string;
+    /** DRILL: the period `field` is cut into when it is a date (`month`); the store keeps `field` a Field key. */
+    grain?: string;
+    /** The Measures shown ("what to display"), by the store's own keys (`count`, `sum_quantity`). */
+    show?: string[];
+    /** The drill trail, in order: each crumb a Dimension reference and the value it narrowed to. */
+    trail?: GridDrillStep[];
+};
+/** One crumb of a saved drill trail. `value: null` is "no value". */
+type GridDrillStep = {
+    dim: string;
+    value: string | null;
+};
+/** One sub-group level: a Field key and its section order. */
+type GridSubGroup = {
+    field: string;
+    order?: GroupOrder;
+    grain?: string;
+};
+/** Everything a view says about how its table LOOKS. */
+type GridPresentation = {
+    /** Color-by-a-column, rules and manual highlights. */
+    style?: TableStyle;
+    /** Per-column format overrides, by the Field's key. */
+    formats?: Record<string, FieldFormatConfig>;
+    /**
+     * The columns that stay in place while the table scrolls sideways, by Field
+     * key. Only the LEADING run of the view's column order can actually freeze —
+     * the data table decides that, and declines rather than pinning a column at a
+     * guessed offset.
+     */
+    frozen?: string[];
+    /** Collapsible sections by one Field, with subtotals on each header. */
+    grouping?: GridGrouping;
+    /**
+     * The width a person dragged a column to, by Field key. SPARSE on purpose —
+     * a view saved before widths existed carries none and still parses, and a
+     * column nobody resized is left to the table's own measurement.
+     */
+    widths?: Record<string, number>;
+    /** The body row height this view remembers, in px. */
+    rowHeight?: number;
+    /**
+     * Field keys hidden from this view — the SAME hidden-column list the grid's
+     * own column picker holds, now given a place on the view so it survives a
+     * reload and a layout switch reads the identical set gallery and grid agree
+     * on, rather than a second "fields shown" list nobody kept in sync.
+     */
+    hiddenFields?: string[];
+    /**
+     * THE FIELDS A CARD LEAVES OFF (board, list, gallery, calendar, timeline), by Field key — the
+     * card's own choice, kept apart from `hiddenFields` so a board's "Card fields" never hides the
+     * grid's columns when the view switches layout (v7 TABLE-EXPERIENCE, walk 2026-10-05). An empty
+     * list is a choice (every field shown); absent means the card never chose.
+     */
+    cardHidden?: string[];
+    /**
+     * THE ORDER A PERSON DRAGGED THE COLUMNS INTO, by Field key (merge tranche 6a). Sparse like
+     * `widths`: a key it does not name keeps its Field's own place after the named ones, and a key
+     * whose Field is gone is skipped — a column order can never hide or invent a column.
+     */
+    columnOrder?: string[];
+    /**
+     * The gallery's card size, remembered the same way the grid remembers its
+     * row height — a per-view look, not a global default.
+     */
+    gallerySize?: "small" | "medium" | "large";
+    /**
+     * THIS VIEW'S OWN LAYOUT CHOICES, over the organization's `custom/grid_layout` knob (lane
+     * DEFAULT-GRID-PARITY, TABLE-PARITY D1 D5 D6). Absent means "whatever the organization
+     * says"; present is the view's word. `freezeFirst: false` is an explicit NO over an
+     * organization that freezes the first column — an empty `frozen` cannot say that.
+     */
+    wrap?: boolean;
+    /** NOTION'S "WRAP COLUMN" (N5): the columns that wrap their text when the view as a whole does not. */
+    wrapColumns?: string[];
+    fit?: "auto" | "fit" | "scroll";
+    freezeFirst?: boolean;
+    /**
+     * THE SUMMARY BAR (TABLE-PARITY F1): Field key → the store measure shown under that column
+     * (`count`, `sum`, `avg`, `min`, `max`, `median`, `filled`, `empty`, `unique`), worked out
+     * by `custom.record_aggregate` over the whole table.
+     */
+    summaries?: Record<string, string>;
+    /**
+     * WHERE THE FOOTER SITS (lane TABLE-PAGE-CHROME, owner 2026-09-25) — the row count and the
+     * pages: `sticky`, pinned to the bottom of the screen while the rows scroll (the older grid's
+     * way, and the default when a view says nothing), or `inline`, right after the last row with
+     * the page scrolling. Read by the Grid and a host's Sheet.
+     */
+    footer?: FooterPlacement;
+};
+/** Where a grid's footer sits. */
+type FooterPlacement = "sticky" | "inline";
+
+/** The ways one saved view can be looked at (SCR-6; the timeline, lane VIEWS-AND-FIELDS TL). */
+declare const VIEW_LAYOUTS: readonly ["grid", "kanban", "calendar", "gallery", "timeline", "list"];
+type ViewLayout = (typeof VIEW_LAYOUTS)[number];
+/** One sort clause. The Field's key and a direction; nothing else is a sort. */
+interface ViewSort {
+    field: string;
+    direction: "asc" | "desc";
+}
+/** How a saved view is ordered: by hand, by its sort, or it never said (the same as sorted). */
+type ViewOrder = "manual" | "sorted" | null;
+/**
+ * THE DECLARATIVE SPEC. An agent writes this whole object; a person tweaks it.
+ * Every builder component in this package takes one of these as a prop.
+ */
+interface SavedViewSpec {
+    name: string;
+    /** The Table this view looks at. */
+    subject: Uuid;
+    layout: ViewLayout;
+    /** Kanban: the Field whose value becomes a column. */
+    groupField?: string | null;
+    /**
+     * Kanban: a number Field to TOTAL under each column heading. It lives on the VIEW for
+     * the same reason the colours do — two people read one board two ways and neither
+     * reading is a fact about the records.
+     */
+    measure?: string | null;
+    /**
+     * Kanban: the Field whose values cut the board into SWIMLANES across the columns — a
+     * dispatcher's board by Status, one lane per Technician (S1-PRIME VIEW-KEYS). Never the
+     * column Field itself; the store refuses that.
+     */
+    swimlaneField?: string | null;
+    /** Kanban: the columns this view keeps shut to a strip, by the column's stored value. */
+    collapsedColumns?: string[];
+    /** Calendar: the Field that places a record in the month. */
+    dateField?: string | null;
+    /** Timeline: the Field a record's bar starts on (`start_field`). */
+    startField?: string | null;
+    /** Calendar and timeline: the Field a record ends on (`end_field`). */
+    endField?: string | null;
+    /** Gallery: the Field shown large on the card. */
+    imageField?: string | null;
+    sorts?: ViewSort[];
+    /**
+     * HOW THE VIEW IS ORDERED (ORDER-FIX): `"manual"` — the positions a person set by hand ARE the
+     * view's sort, and it carries no `sorts`; `"sorted"` or null — by `sorts`. READ ONLY: the store
+     * writes "manual" only when the rows are placed (`custom.view_record_order_set`) and turns it
+     * off itself when a sort is saved, so no patch ever sends it (`viewSettingsPatch` does not).
+     */
+    order?: ViewOrder;
+    /**
+     * The membership Rule. The STORE decides who is in this view; this is a
+     * reference to its Rule record, never a predicate this package evaluates.
+     */
+    ruleId?: Uuid | null;
+    /**
+     * THE FLAT FILTER a digest or a notify rule wrote the view with — the one shape
+     * `custom.record_filter_sql` compiles, by Field KEY. A view saved in the bar has
+     * none; a view saved by `DigestScheduler` ("where Status is Open") does, and the
+     * grid and the board show exactly the records it names.
+     */
+    filters?: RecordFilter;
+    /**
+     * S2-PRIME — THE VIEW'S OWN QUESTION, as the condition builder writes it: the store's Rule
+     * shape `{op, args}`, ALL / ANY / NOT groups nested to any depth, Fields by id. Kept in the
+     * definition as `where` and asked of the store unchanged — the grid's list door, the board's
+     * headings and the dashboard's numbers compile it into the one WHERE clause
+     * (`custom.record_filter_sql`). Never stored under `filters`: that key is the flat map the
+     * digests and the notifier read, and they would refuse it by name.
+     */
+    where?: RuleExpression | null;
+    isDefault?: boolean;
+    /**
+     * HOW THIS VIEW LOOKS — its colors, its per-column formats and its frozen
+     * column (`presentation.ts`).
+     *
+     * It lives on the VIEW and not on the Fields because two people read one
+     * table two ways and neither reading is a fact about the records; it lives on
+     * a RECORD, not a new column, because that is what makes it something an
+     * agent writes with the same `records` tool as everything else.
+     */
+    presentation?: GridPresentation;
+}
+/**
+ * A saved view as it comes back out of the store, with its row's own id.
+ *
+ * It carries no version: `custom.view_declare` MERGES one key at a time, so two
+ * tabs pressing two different controls on one view both stand, and one control
+ * pressed in both keeps the latest — how Airtable and Notion keep a view change.
+ */
+interface SavedView extends SavedViewSpec {
+    id: Uuid;
+    /** Where the view came from when it was moved in (the mover, the S0 repair), else null. */
+    movedFrom: Record<string, unknown> | null;
+}
+
+/** The table page's own page size (`TablePage`: 100 unless embedded). */
+declare const TABLE_PAGE_SIZE = 100;
+/**
+ * HOW MANY ROWS AN EMBEDDED TABLE READS AT A TIME (CHAIR-EMBEDDED-FIDELITY 16): its first page, and
+ * each "Show more" press brings about this many more. `embeddedLook.tsx` re-exports it.
+ */
+declare const EMBEDDED_PAGE_SIZE = 50;
+interface FirstGridPageArgs {
+    p_table_id: Uuid;
+    p_filter: Record<string, never>;
+    p_search: null;
+    p_sort: RecordPageSort[];
+    p_view_id: null;
+    p_limit: number;
+    p_offset: 0;
+}
+/** The request for the plain opening, from what the screen itself reads — or null. Pure. */
+declare function firstGridPageArgs(input: {
+    tableId: Uuid;
+    table: Pick<Table, "default_sort"> | null;
+    fields: readonly Field[];
+    /** The view as THIS person sees it (the saved view with her look over it), or null for none. */
+    shown: SavedView | null;
+    pageSize?: number;
+}): FirstGridPageArgs | null;
+/**
+ * Read what the screen reads (through `client`, e.g. one served from `custom.table_page_bundle`)
+ * and build the first page's request. Null when anything it needs is not answered.
+ */
+declare function firstGridPageRequest(client: Pick<RecordsClient, "tableRead" | "fields" | "views" | "viewLookRead">, tableId: Uuid, options?: {
+    pageSize?: number;
+}): Promise<FirstGridPageArgs | null>;
+/**
+ * A TABLE PAGE'S SEED, ASKED BY THE SERVER AS THE PERSON (lane SSR-ROWS).
+ *
+ * Asks what the table page opens on — the table's bundle (`custom.table_page_bundle`, through the
+ * records client exactly as the browser would), the grid's first page when `firstGridPageRequest`
+ * can predict it, and on a record page the record's bundle — through a recording data source, and
+ * answers every door answer it got as a `RecordsSeed`. The host hands that to
+ * `<RecordsSeedProvider>` (`@ai-matrx/records/react`) above the table page: the page is drawn with
+ * its rows in the server's HTML and hydrates onto them without asking again.
+ *
+ * `dataSource` is the person's own (a server supabase client carrying her session): every door
+ * decides exactly as it does from the browser. Never throws; a door that refuses is simply not in
+ * the seed, and the page asks it for itself.
+ */
+declare function askTablePageSeed(input: {
+    dataSource: unknown;
+    organizationId: Uuid;
+    tableId: Uuid;
+    actor: RecordsConfig["actor"];
+    /** A record page: its record's bundle (`custom.record_page_bundle`) is asked beside the table's. */
+    recordId?: Uuid | null;
+    /** Ask the grid's first page (default true). Off when the address opens something else. */
+    rows?: boolean;
+    /** The table is drawn EMBEDDED (`TablePage presentation="embedded"`, a Space's inline table): its page size. */
+    embedded?: boolean;
+    pageSize?: number;
+}): Promise<RecordsSeed>;
+
+export { EMBEDDED_PAGE_SIZE, type FirstGridPageArgs, TABLE_PAGE_SIZE, askTablePageSeed, firstGridPageArgs, firstGridPageRequest };

package/dist/first-page.d.ts

@@ -0,0 +1,320 @@
+import { Uuid, RecordFilter, RuleExpression, RecordPageSort, RecordsConfig, Table, Field } from '@ai-matrx/records';
+import { RecordsSeed, RecordsClient } from '@ai-matrx/records/core';
+import { TableStyle, GroupAggregateSpec, GroupOrder } from '@ai-matrx/design-system/data-table';
+import { FieldFormatConfig } from '@ai-matrx/design-system/field-formats';
+
+/**
+ * HOW A TABLE LOOKS — colors, formats and the frozen column.
+ *
+ * THE SPLIT, AND WHY IT IS THIS ONE. A Field declares WHAT it holds: a
+ * currency, a percent, a date, a person. A VIEW declares HOW that reads and
+ * what it is worth looking at: two decimal places or none, tint the row when
+ * Status is Blocked, keep Name in place while the rest scrolls. Airtable draws
+ * the line in exactly this place, and it has to be here: two people read one
+ * table two different ways, and neither reading is a fact about the records.
+ *
+ * So nothing in this module is a new column on a Field and nothing here needed
+ * a migration. A presentation lives on the saved-view record (`views.ts`), which
+ * is an ordinary record of an ordinary Table — which means an agent sets it
+ * through the same `records` tool it uses for everything else, and it travels
+ * with the table the way every other record does.
+ *
+ * A FIELD STILL GETS ITS MONEY RIGHT WITH NO CONFIGURATION. `formatForField`
+ * reads the Field's OWN declaration — a `currency` parity type with unit `$`, a
+ * `percent`, a `datetime` with `config.kind` — and returns the format that
+ * follows from it. The view's `formats` map only OVERRIDES that. A table nobody
+ * has ever styled still shows `$1,250.50` and `45%`.
+ */
+
+/**
+ * SECTIONS BY A FIELD — the view's own grouping.
+ *
+ * `field` is a Field KEY, exactly like `frozen` and the keys of `formats`,
+ * because a view is written against the Table's declaration and never against
+ * whatever id a screen happened to build its columns with.
+ *
+ * `aggregates` is keyed by Field key too, and `collapsed` holds the data
+ * table's own group keys (`s:Blocked`, `n:3`, `empty`), which is what the
+ * primitive emits and the only thing that survives a value rendering the same
+ * text as another.
+ *
+ * NOTHING HERE IS EVER CALLED `valueOf`, `toString` or `hasOwnProperty`: every
+ * object in JavaScript already has all three, so an optional field by one of
+ * those names is NEVER absent and a `config.valueOf ? … : …` check silently
+ * reads `Object.prototype`. It cost the primitive a whole grouping once.
+ */
+type GridGrouping = {
+    /** The Field key whose value makes the sections. */
+    field: string;
+    /** Per-Field-key subtotal on every section header. */
+    aggregates?: Record<string, GroupAggregateSpec>;
+    /** Section order. The primitive's default is `value-asc`; blanks sort last. */
+    order?: GroupOrder;
+    /** The sections this view keeps shut, by the primitive's own group key. */
+    collapsed?: string[];
+    /** The grouped column drawn as a column too. Absent = it steps aside (the headers name its value). */
+    showColumn?: boolean;
+    /**
+     * SUB-GROUPS (lane S1-PRIME VIEW-KEYS; ui-bench LISTS "sub-grouping"): up to two more levels
+     * inside each section, by Field key. At most three levels in all — the store refuses a fourth
+     * (`custom.view_declare`). A layout that draws one level ignores the rest; it never drops them,
+     * because this list is parsed and written back whole with the rest of the look.
+     */
+    then?: GridSubGroup[];
+    /**
+     * DRILL (lane DRILL-TABLE-PRIMITIVE): the Dimension pivoted across the top — a Field key, or
+     * `<key>:<grain>` for a date cut into periods.
+     */
+    across?: string;
+    /** DRILL: the period `field` is cut into when it is a date (`month`); the store keeps `field` a Field key. */
+    grain?: string;
+    /** The Measures shown ("what to display"), by the store's own keys (`count`, `sum_quantity`). */
+    show?: string[];
+    /** The drill trail, in order: each crumb a Dimension reference and the value it narrowed to. */
+    trail?: GridDrillStep[];
+};
+/** One crumb of a saved drill trail. `value: null` is "no value". */
+type GridDrillStep = {
+    dim: string;
+    value: string | null;
+};
+/** One sub-group level: a Field key and its section order. */
+type GridSubGroup = {
+    field: string;
+    order?: GroupOrder;
+    grain?: string;
+};
+/** Everything a view says about how its table LOOKS. */
+type GridPresentation = {
+    /** Color-by-a-column, rules and manual highlights. */
+    style?: TableStyle;
+    /** Per-column format overrides, by the Field's key. */
+    formats?: Record<string, FieldFormatConfig>;
+    /**
+     * The columns that stay in place while the table scrolls sideways, by Field
+     * key. Only the LEADING run of the view's column order can actually freeze —
+     * the data table decides that, and declines rather than pinning a column at a
+     * guessed offset.
+     */
+    frozen?: string[];
+    /** Collapsible sections by one Field, with subtotals on each header. */
+    grouping?: GridGrouping;
+    /**
+     * The width a person dragged a column to, by Field key. SPARSE on purpose —
+     * a view saved before widths existed carries none and still parses, and a
+     * column nobody resized is left to the table's own measurement.
+     */
+    widths?: Record<string, number>;
+    /** The body row height this view remembers, in px. */
+    rowHeight?: number;
+    /**
+     * Field keys hidden from this view — the SAME hidden-column list the grid's
+     * own column picker holds, now given a place on the view so it survives a
+     * reload and a layout switch reads the identical set gallery and grid agree
+     * on, rather than a second "fields shown" list nobody kept in sync.
+     */
+    hiddenFields?: string[];
+    /**
+     * THE FIELDS A CARD LEAVES OFF (board, list, gallery, calendar, timeline), by Field key — the
+     * card's own choice, kept apart from `hiddenFields` so a board's "Card fields" never hides the
+     * grid's columns when the view switches layout (v7 TABLE-EXPERIENCE, walk 2026-10-05). An empty
+     * list is a choice (every field shown); absent means the card never chose.
+     */
+    cardHidden?: string[];
+    /**
+     * THE ORDER A PERSON DRAGGED THE COLUMNS INTO, by Field key (merge tranche 6a). Sparse like
+     * `widths`: a key it does not name keeps its Field's own place after the named ones, and a key
+     * whose Field is gone is skipped — a column order can never hide or invent a column.
+     */
+    columnOrder?: string[];
+    /**
+     * The gallery's card size, remembered the same way the grid remembers its
+     * row height — a per-view look, not a global default.
+     */
+    gallerySize?: "small" | "medium" | "large";
+    /**
+     * THIS VIEW'S OWN LAYOUT CHOICES, over the organization's `custom/grid_layout` knob (lane
+     * DEFAULT-GRID-PARITY, TABLE-PARITY D1 D5 D6). Absent means "whatever the organization
+     * says"; present is the view's word. `freezeFirst: false` is an explicit NO over an
+     * organization that freezes the first column — an empty `frozen` cannot say that.
+     */
+    wrap?: boolean;
+    /** NOTION'S "WRAP COLUMN" (N5): the columns that wrap their text when the view as a whole does not. */
+    wrapColumns?: string[];
+    fit?: "auto" | "fit" | "scroll";
+    freezeFirst?: boolean;
+    /**
+     * THE SUMMARY BAR (TABLE-PARITY F1): Field key → the store measure shown under that column
+     * (`count`, `sum`, `avg`, `min`, `max`, `median`, `filled`, `empty`, `unique`), worked out
+     * by `custom.record_aggregate` over the whole table.
+     */
+    summaries?: Record<string, string>;
+    /**
+     * WHERE THE FOOTER SITS (lane TABLE-PAGE-CHROME, owner 2026-09-25) — the row count and the
+     * pages: `sticky`, pinned to the bottom of the screen while the rows scroll (the older grid's
+     * way, and the default when a view says nothing), or `inline`, right after the last row with
+     * the page scrolling. Read by the Grid and a host's Sheet.
+     */
+    footer?: FooterPlacement;
+};
+/** Where a grid's footer sits. */
+type FooterPlacement = "sticky" | "inline";
+
+/** The ways one saved view can be looked at (SCR-6; the timeline, lane VIEWS-AND-FIELDS TL). */
+declare const VIEW_LAYOUTS: readonly ["grid", "kanban", "calendar", "gallery", "timeline", "list"];
+type ViewLayout = (typeof VIEW_LAYOUTS)[number];
+/** One sort clause. The Field's key and a direction; nothing else is a sort. */
+interface ViewSort {
+    field: string;
+    direction: "asc" | "desc";
+}
+/** How a saved view is ordered: by hand, by its sort, or it never said (the same as sorted). */
+type ViewOrder = "manual" | "sorted" | null;
+/**
+ * THE DECLARATIVE SPEC. An agent writes this whole object; a person tweaks it.
+ * Every builder component in this package takes one of these as a prop.
+ */
+interface SavedViewSpec {
+    name: string;
+    /** The Table this view looks at. */
+    subject: Uuid;
+    layout: ViewLayout;
+    /** Kanban: the Field whose value becomes a column. */
+    groupField?: string | null;
+    /**
+     * Kanban: a number Field to TOTAL under each column heading. It lives on the VIEW for
+     * the same reason the colours do — two people read one board two ways and neither
+     * reading is a fact about the records.
+     */
+    measure?: string | null;
+    /**
+     * Kanban: the Field whose values cut the board into SWIMLANES across the columns — a
+     * dispatcher's board by Status, one lane per Technician (S1-PRIME VIEW-KEYS). Never the
+     * column Field itself; the store refuses that.
+     */
+    swimlaneField?: string | null;
+    /** Kanban: the columns this view keeps shut to a strip, by the column's stored value. */
+    collapsedColumns?: string[];
+    /** Calendar: the Field that places a record in the month. */
+    dateField?: string | null;
+    /** Timeline: the Field a record's bar starts on (`start_field`). */
+    startField?: string | null;
+    /** Calendar and timeline: the Field a record ends on (`end_field`). */
+    endField?: string | null;
+    /** Gallery: the Field shown large on the card. */
+    imageField?: string | null;
+    sorts?: ViewSort[];
+    /**
+     * HOW THE VIEW IS ORDERED (ORDER-FIX): `"manual"` — the positions a person set by hand ARE the
+     * view's sort, and it carries no `sorts`; `"sorted"` or null — by `sorts`. READ ONLY: the store
+     * writes "manual" only when the rows are placed (`custom.view_record_order_set`) and turns it
+     * off itself when a sort is saved, so no patch ever sends it (`viewSettingsPatch` does not).
+     */
+    order?: ViewOrder;
+    /**
+     * The membership Rule. The STORE decides who is in this view; this is a
+     * reference to its Rule record, never a predicate this package evaluates.
+     */
+    ruleId?: Uuid | null;
+    /**
+     * THE FLAT FILTER a digest or a notify rule wrote the view with — the one shape
+     * `custom.record_filter_sql` compiles, by Field KEY. A view saved in the bar has
+     * none; a view saved by `DigestScheduler` ("where Status is Open") does, and the
+     * grid and the board show exactly the records it names.
+     */
+    filters?: RecordFilter;
+    /**
+     * S2-PRIME — THE VIEW'S OWN QUESTION, as the condition builder writes it: the store's Rule
+     * shape `{op, args}`, ALL / ANY / NOT groups nested to any depth, Fields by id. Kept in the
+     * definition as `where` and asked of the store unchanged — the grid's list door, the board's
+     * headings and the dashboard's numbers compile it into the one WHERE clause
+     * (`custom.record_filter_sql`). Never stored under `filters`: that key is the flat map the
+     * digests and the notifier read, and they would refuse it by name.
+     */
+    where?: RuleExpression | null;
+    isDefault?: boolean;
+    /**
+     * HOW THIS VIEW LOOKS — its colors, its per-column formats and its frozen
+     * column (`presentation.ts`).
+     *
+     * It lives on the VIEW and not on the Fields because two people read one
+     * table two ways and neither reading is a fact about the records; it lives on
+     * a RECORD, not a new column, because that is what makes it something an
+     * agent writes with the same `records` tool as everything else.
+     */
+    presentation?: GridPresentation;
+}
+/**
+ * A saved view as it comes back out of the store, with its row's own id.
+ *
+ * It carries no version: `custom.view_declare` MERGES one key at a time, so two
+ * tabs pressing two different controls on one view both stand, and one control
+ * pressed in both keeps the latest — how Airtable and Notion keep a view change.
+ */
+interface SavedView extends SavedViewSpec {
+    id: Uuid;
+    /** Where the view came from when it was moved in (the mover, the S0 repair), else null. */
+    movedFrom: Record<string, unknown> | null;
+}
+
+/** The table page's own page size (`TablePage`: 100 unless embedded). */
+declare const TABLE_PAGE_SIZE = 100;
+/**
+ * HOW MANY ROWS AN EMBEDDED TABLE READS AT A TIME (CHAIR-EMBEDDED-FIDELITY 16): its first page, and
+ * each "Show more" press brings about this many more. `embeddedLook.tsx` re-exports it.
+ */
+declare const EMBEDDED_PAGE_SIZE = 50;
+interface FirstGridPageArgs {
+    p_table_id: Uuid;
+    p_filter: Record<string, never>;
+    p_search: null;
+    p_sort: RecordPageSort[];
+    p_view_id: null;
+    p_limit: number;
+    p_offset: 0;
+}
+/** The request for the plain opening, from what the screen itself reads — or null. Pure. */
+declare function firstGridPageArgs(input: {
+    tableId: Uuid;
+    table: Pick<Table, "default_sort"> | null;
+    fields: readonly Field[];
+    /** The view as THIS person sees it (the saved view with her look over it), or null for none. */
+    shown: SavedView | null;
+    pageSize?: number;
+}): FirstGridPageArgs | null;
+/**
+ * Read what the screen reads (through `client`, e.g. one served from `custom.table_page_bundle`)
+ * and build the first page's request. Null when anything it needs is not answered.
+ */
+declare function firstGridPageRequest(client: Pick<RecordsClient, "tableRead" | "fields" | "views" | "viewLookRead">, tableId: Uuid, options?: {
+    pageSize?: number;
+}): Promise<FirstGridPageArgs | null>;
+/**
+ * A TABLE PAGE'S SEED, ASKED BY THE SERVER AS THE PERSON (lane SSR-ROWS).
+ *
+ * Asks what the table page opens on — the table's bundle (`custom.table_page_bundle`, through the
+ * records client exactly as the browser would), the grid's first page when `firstGridPageRequest`
+ * can predict it, and on a record page the record's bundle — through a recording data source, and
+ * answers every door answer it got as a `RecordsSeed`. The host hands that to
+ * `<RecordsSeedProvider>` (`@ai-matrx/records/react`) above the table page: the page is drawn with
+ * its rows in the server's HTML and hydrates onto them without asking again.
+ *
+ * `dataSource` is the person's own (a server supabase client carrying her session): every door
+ * decides exactly as it does from the browser. Never throws; a door that refuses is simply not in
+ * the seed, and the page asks it for itself.
+ */
+declare function askTablePageSeed(input: {
+    dataSource: unknown;
+    organizationId: Uuid;
+    tableId: Uuid;
+    actor: RecordsConfig["actor"];
+    /** A record page: its record's bundle (`custom.record_page_bundle`) is asked beside the table's. */
+    recordId?: Uuid | null;
+    /** Ask the grid's first page (default true). Off when the address opens something else. */
+    rows?: boolean;
+    /** The table is drawn EMBEDDED (`TablePage presentation="embedded"`, a Space's inline table): its page size. */
+    embedded?: boolean;
+    pageSize?: number;
+}): Promise<RecordsSeed>;
+
+export { EMBEDDED_PAGE_SIZE, type FirstGridPageArgs, TABLE_PAGE_SIZE, askTablePageSeed, firstGridPageArgs, firstGridPageRequest };