@ai-matrx/records-ui 0.107.5 → 0.108.0

package/dist/views-VPwb3QQk.d.ts

@@ -0,0 +1,505 @@
+import { TableStyle, GroupAggregateSpec, GroupOrder, ChoiceColorLookup } from '@ai-matrx/design-system/data-table';
+import { FieldFormatConfig } from '@ai-matrx/design-system/field-formats';
+import { Field, TableDecorations, Uuid, RecordFilter, RuleExpression, RecordsResult, SavedViewRow } from '@ai-matrx/records';
+import { RecordsClient } from '@ai-matrx/records/core';
+
+/**
+ * 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";
+/** What a view that says nothing gets — the older grid's pinned footer. */
+declare const DEFAULT_FOOTER: FooterPlacement;
+/** Where THIS view's footer sits, said or defaulted. */
+declare function footerOf(p: GridPresentation | null | undefined): FooterPlacement;
+declare const EMPTY_PRESENTATION: GridPresentation;
+/** A frozen column needs a known width, or the table declines to freeze at all. */
+declare const FROZEN_COLUMN_WIDTH = 200;
+/**
+ * WHAT A ROW HEIGHT IS ALLOWED TO BE. Below the floor the text is clipped and
+ * no editor fits; above the ceiling one record fills the screen. A view asking
+ * for anything outside it is DROPPED rather than obeyed, because a saved look
+ * must not be able to make a table unreadable — and the Fields' own heights
+ * still draw, which is the tolerant half.
+ */
+declare const MIN_ROW_HEIGHT = 24;
+declare const MAX_ROW_HEIGHT = 96;
+/**
+ * Read a presentation out of whatever the view record holds — an object, or the
+ * JSON string a text field stores.
+ *
+ * Tolerant in exactly the way `parseTableStyle` is: an unreadable half is
+ * dropped and the rest still applies, because a table must keep drawing when
+ * one piece of its styling goes out of date.
+ */
+declare function parseGridPresentation(raw: unknown): GridPresentation;
+/** True when nothing here would change how anything looks. */
+declare function presentationIsEmpty(p: GridPresentation): boolean;
+/** The string a view record stores. Empty string for "this view styles nothing". */
+declare function presentationDocument(p: GridPresentation): string;
+/**
+ * The format a Field's OWN declaration implies, before any view says anything.
+ *
+ * Returns `undefined` for a Field whose value the record renderer already draws
+ * better than a formatter could — a relation chip, a person, an attachment, a
+ * choice — because handing those to a text formatter would REPLACE a working
+ * control with a string.
+ */
+declare function formatForField(field: Field): FieldFormatConfig | undefined;
+declare function currencyCodeFor(unit: string | null | undefined): string;
+/**
+ * The color a value paints with when a view colors BY a column.
+ *
+ * NOTHING FAILS SILENTLY, so this never returns "no color" for a value that
+ * exists. The store keeps a list column's choices as records of another Table,
+ * and this grid has not read that Table's option colors, so the color is
+ * derived from the value's own text: the same word always gets the same color,
+ * different words get different ones, and `true` is green the way every
+ * checklist reads. When those option colors do land, this is the ONE function
+ * that changes and every screen follows.
+ */
+declare const colorFromTheValue: ChoiceColorLookup;
+/**
+ * G1's TABLE-LEVEL COLORS (`custom.table_decorations` / `client.tableDecorations`),
+ * TRANSLATED INTO A `TableStyle` — the same document a saved view's own `presentation.style`
+ * is, so one resolver (`resolveTableStyle`, below) can treat "the table's colors" and "this
+ * view's colors" as two layers of the SAME thing instead of two unrelated systems.
+ *
+ * THE TRANSLATION IS NECESSARY AND IT IS THE ONLY ONE. G1 addresses a Field by its ID
+ * (REC-17 — a column renamed keeps its color), because it is the STORE's own door; a
+ * `TableStyle` addresses a Field by its KEY, because it reads straight off `row.document`,
+ * which is keyed by Field key. A rule or a color-by whose Field has been deleted (its id no
+ * longer resolves to a key) is dropped rather than crashing the whole style — a defect in
+ * one rule costs that rule, never the read.
+ */
+declare function styleFromDecorations(decorations: TableDecorations | null | undefined, fields: readonly Field[]): TableStyle;
+/**
+ * THE ONE PRESENTATION RESOLVER every colored surface in this package reads —
+ * `Grid`, and (via `Card`) the kanban board, the calendar and the gallery.
+ *
+ * THE CLASS THIS CLOSES (lane UI-QUICK-1, TABLE-PARITY review, 2026-09-24). Threading
+ * `view.presentation.style` into `Card` closed the instance the CALENDAR-GALLERY bench
+ * found — a VIEW that had its own color-by looked right everywhere — but it left the
+ * class open: a table whose colors are the ORGANIZATION's decorations (G1's
+ * `custom.table_decorations` — "color rows by Account Type", "MAXED and NEAR rules" on
+ * Arman's own Coding Accounts table) and whose views never set a `presentation.style` of
+ * their own drew NOTHING, on the grid exactly as much as on every other layout, because
+ * nothing in this package had ever read G1's door at all.
+ *
+ * TWO LAYERS, ONE DOCUMENT. The table's decorations are the base coat — what every view
+ * of this table shows until a view says otherwise. A view's OWN `presentation.style` is
+ * an override, piece by piece: a view that only ever set manual row highlights still
+ * inherits the table's color-by and rules for everything it never touched, and a view
+ * that fully redecorated (its own `colorBy` AND its own `rules`) is not haunted by a
+ * table rule it meant to replace. Per-piece, never all-or-nothing, because a view is a
+ * LOOK on top of the table, not a wholesale substitute for it.
+ */
+declare function resolveTableStyle(decorations: TableDecorations | null | undefined, fields: readonly Field[], viewStyle: TableStyle | undefined): TableStyle;
+
+/** 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];
+declare const LAYOUT_LABEL: Record<ViewLayout, string>;
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHAT EACH LAYOUT NEEDS FROM THE TABLE, AND HOW THE SCREEN SUPPLIES IT
+ * (lane DATA-V2-VIEWS-1, Arman 2026-09-28).
+ *
+ * THE DEFECT. A plain table opened as a Kanban said "A kanban board needs a Field to make its
+ * columns from … Add column, then Select — and it appears here." It told the person what to do
+ * instead of doing it, and on an AI platform it offered no AI. The ruling: ONE primitive, used by
+ * every view (`ViewNeeds`) — the empty state says in one plain sentence what is missing and what
+ * pressing will do, offers "Make it work" (the column is declared through the store's
+ * `custom.field_declare`, its key minted by the store, its name and choices editable before the
+ * press) and "Ask AI" (the agent does it through the same door, held for the person's approval by
+ * the organization's "Agent changes to this organization's data" setting).
+ *
+ * THE CENSUS — every layout this package draws, and what it reads:
+ *   · grid      nothing.
+ *   · kanban    a CHOICE column (its options become the board's columns). Blocking.
+ *   · calendar  a DATE column (it places each record on a day). Blocking.
+ *   · gallery   a FILE column for the card's picture. NOT blocking: the cards draw without one,
+ *               so the offer sits above them instead of in place of them.
+ *   · timeline  a DATE column each bar starts on (the calendar's `dateField`). Blocking.
+ * `PAGE_VIEWS`' two extra values (dashboards, archived) read
+ * nothing a table can lack. This package ships no map layout; the day it does,
+ * `Record<ViewLayout, …>` below refuses to compile until the new layout names what it needs.
+ */
+type ViewNeedKind = "choice" | "date" | "file";
+interface ViewNeed {
+    /** What the layout reads, as a kind a column declares (`offerableFields`). */
+    kind: ViewNeedKind;
+    /** The view key the made column is written onto, so the layout opens drawn by it. */
+    viewKey: "groupField" | "dateField" | "imageField";
+    /** True when the layout cannot draw at all without it (kanban, calendar). */
+    blocking: boolean;
+    /** The column the press makes, before the person edits it: its name, the store's word, its choices. */
+    starter: {
+        label: string;
+        type: "select" | "datetime" | "attachment";
+        options?: readonly string[];
+    };
+    /** The table HAS columns this layout can use and none is chosen: the sentence over the picker. */
+    pick: string;
+    /** One plain sentence: what the table is missing (all a person who may not change it is told). */
+    missing: string;
+    /** One plain sentence: what pressing Make it work will do, with the column's name. */
+    does: (label: string) => string;
+    /** The sentence an agent is asked with — the same act, said in words. */
+    ask: (label: string, options: readonly string[]) => string;
+}
+/** A list of words as a person says it: "To do, In progress and Done". */
+declare function wordsList(words: readonly string[]): string;
+declare const VIEW_NEEDS: Record<ViewLayout, ViewNeed | null>;
+/**
+ * A NAME NO COLUMN OF THIS TABLE ALREADY HAS: the starter's own, else "Status 2", "Status 3"…
+ * A table that already holds a text column called Status must not be refused the board.
+ */
+declare function freeColumnName(wanted: string, taken: readonly string[]): string;
+/** 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'S DEFAULT VIEW: the first view that says it is. */
+declare function defaultViewOf<V extends Pick<SavedView, "isDefault">>(views: readonly V[]): V | undefined;
+/**
+ * WHICH FIELD EACH LAYOUT CAN BE DRAWN FROM, decided from the FIELD'S OWN
+ * DECLARATION and never from the values it happens to hold.
+ *
+ * A kanban makes columns from a choice: the Field whose value is one of a
+ * closed set (FLD-5 / FLD-6 — a pick-list is a Table, and a select stores the
+ * id of one of its records). Grouping by a free-text Field produces one column
+ * per record, which is not a board. A calendar places a record in time, so it
+ * needs a Field that holds a date.
+ *
+ * These two answers are here, beside the layouts, because the picker on the
+ * screen and any agent writing a view spec must agree about what is offerable.
+ */
+declare const LAYOUT_FIELD_KIND: Record<ViewLayout, ViewNeedKind | null>;
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHICH VIEW A LINK NAMES — the address bar as a first-class control.
+ *
+ * 🚨 THE DEFECT THIS CLOSES (lane FRONT-DOOR, 2026-09-21; VERIFIER-8 HIGH-2).
+ * `/data/<table>?view=kanban` returned 200 and rendered THE GRID. The
+ * switcher was there, the four buttons worked, and the parameter was read by
+ * nobody — so a person who bookmarked a board, or sent one to a colleague, got
+ * a grid, and nothing on the screen said the view had been dropped. A link that
+ * does not land is the inbox-link defect (`activeRecordId`) and the dashboard
+ * defect (`activeDashboardId`) for the third time, so this is the same shape of
+ * fix: the URL names it, the page opens on it, and the URL FOLLOWS the person
+ * when they pick another.
+ *
+ * The dashboards are a fifth value and not a special case: to the person, "the
+ * dashboard" is one of the ways to look at this table, and a link to it has to
+ * work like a link to the board.
+ */
+/**
+ * 🚨 `archived` IS THE SIXTH VALUE, AND IT IS NOT A SPECIAL CASE EITHER (lane
+ * FIX-10A-ARCHIVE, 2026-09-22; VERIFIER-10 F4).
+ *
+ * Archiving a record used to be a ONE-WAY DOOR: the grid's row action soft-
+ * deletes correctly — `deleted_at` set, version bumped, nothing removed — and
+ * then no screen anywhere in the platform could bring it back. The store's
+ * `custom.record_restore` was there the whole time and did exactly the right
+ * thing; nothing reached it, because every read door answers live rows only.
+ *
+ * So the archive is a WAY OF LOOKING AT THIS TABLE, like the board and the
+ * dashboards, reached by the same row of buttons and named by the same
+ * `?view=` parameter — never a Trash area of the app somebody has to know
+ * exists, and never a per-table screen. Every Table inherits it the moment it
+ * is in this list.
+ */
+declare const PAGE_VIEWS: readonly ["grid", "kanban", "calendar", "gallery", "timeline", "list", "dashboards", "archived"];
+type PageView = (typeof PAGE_VIEWS)[number];
+declare const PAGE_VIEW_LABEL: Record<PageView, string>;
+/**
+ * What a `?view=` value means, or `null` when it means nothing here.
+ *
+ * `null` is NOT "show the grid": the caller is expected to say that the link
+ * named something this table has no view for, because silently substituting a
+ * different view is exactly the defect above wearing a parser.
+ */
+declare function pageViewFromParam(raw: string | null | undefined): PageView | null;
+/** The sentence a link that named a view nobody has says. Never silent. */
+declare function unknownViewLine(raw: string): string;
+/**
+ * THE SPEC AS THE ONE DEFINITION `platform.saved_view` HOLDS — the keys
+ * `custom.view_declare` documents, by Field KEY. `subject` is not in it: the door
+ * takes the Table as its own argument and writes `table_id` itself.
+ */
+declare function viewDocument(spec: SavedViewSpec): Record<string, unknown>;
+/**
+ * One row of `custom.views` back into the spec a screen and an agent both read — THROUGH THE ONE
+ * ACCESSOR (`viewSettings`, viewKeys.ts), so every layout sees every declared key the same way.
+ */
+declare function viewFromRow(row: SavedViewRow): SavedView;
+/**
+ * SAVE ONE NEW VIEW of a Table — the bar's "New view" and an agent's seed spec.
+ * One `view_declare` with no `view_id`; the answer is the new view's id.
+ */
+declare function declareView(client: Pick<RecordsClient, "viewDeclare">, spec: SavedViewSpec): Promise<RecordsResult<Uuid>>;
+/**
+ * WRITE A CHANGE ONTO A SAVED VIEW, AND KEEP IT.
+ *
+ * `custom.view_declare` with the view's id MERGES: only the keys in `patch` are
+ * written, a key cleared to null is removed, and everything the patch did not
+ * name — the grid's own choices, a hand-set order, where the view was moved from,
+ * a colour set in another tab — stays exactly as it was (S0, 2026-09-23: the door
+ * used to rebuild the whole definition from what one press sent).
+ *
+ * There is no version to be stale against (VERIFIER-15 M4 is closed by the shape,
+ * not by a retry): a saved view is a person's own arrangement of a table, and
+ * their latest press on a control is the one that stands. A refusal — the view
+ * was removed, or belongs to a table this person cannot open — is handed back for
+ * the page to say through the one notice.
+ */
+declare function saveViewPatch(client: Pick<RecordsClient, "viewDeclare">, tableId: Uuid, viewId: Uuid, patch: Partial<SavedViewSpec>): Promise<RecordsResult<Uuid>>;
+/**
+ * A PARTIAL change to a saved view, as the definition keys the door merges. Only
+ * the keys the caller actually changed are sent; a Field cleared (a board with no
+ * "Group by") is sent as `null`, which the door removes.
+ */
+declare function viewPatchDocument(patch: Partial<SavedViewSpec>): Record<string, unknown>;
+
+export { styleFromDecorations as A, unknownViewLine as B, viewDocument as C, DEFAULT_FOOTER as D, EMPTY_PRESENTATION as E, type FooterPlacement as F, type GridPresentation as G, viewFromRow as H, viewPatchDocument as I, wordsList as J, LAYOUT_FIELD_KIND as L, MAX_ROW_HEIGHT as M, type PageView as P, type SavedView as S, type ViewOrder as V, type ViewSort as a, type SavedViewSpec as b, type ViewLayout as c, type ViewNeed as d, FROZEN_COLUMN_WIDTH as e, type GridGrouping as f, LAYOUT_LABEL as g, MIN_ROW_HEIGHT as h, PAGE_VIEWS as i, PAGE_VIEW_LABEL as j, VIEW_LAYOUTS as k, VIEW_NEEDS as l, type ViewNeedKind as m, colorFromTheValue as n, currencyCodeFor as o, declareView as p, defaultViewOf as q, footerOf as r, formatForField as s, freeColumnName as t, pageViewFromParam as u, parseGridPresentation as v, presentationDocument as w, presentationIsEmpty as x, resolveTableStyle as y, saveViewPatch as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/records-ui",
-  "version": "0.107.5",
+  "version": "0.108.0",
   "description": "The thirty-one canonical screens of the AI Matrx record store: grid, generated record form, field editor, table settings, relation picker, peek, views, import/export, custom fields, action inbox, history, comments, forms, charts, documents, record chat, AI field fill, checklists, bookings, offline capture, portals, public pages and embeds. Built on @ai-matrx/design-system's data table, carrying @ai-matrx/alchemy's menu, and reading and writing ONLY through @ai-matrx/records.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -71,7 +71,17 @@
         "default": "./dist/pickers.cjs"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./first-page": {
+      "import": {
+        "types": "./dist/first-page.d.ts",
+        "default": "./dist/first-page.js"
+      },
+      "require": {
+        "types": "./dist/first-page.d.cts",
+        "default": "./dist/first-page.cjs"
+      }
+    }
   },
   "peerDependencies": {
     "@dnd-kit/core": ">=6.3.1",
@@ -83,13 +93,13 @@
     "@tanstack/react-query": ">=5.100.0"
   },
   "dependencies": {
+    "@ai-matrx/alchemy": "latest",
     "@ai-matrx/content-ir": "latest",
     "@ai-matrx/design-system": "latest",
-    "@ai-matrx/print": "latest",
     "@ai-matrx/kit": "latest",
-    "@ai-matrx/records": "latest",
+    "@ai-matrx/print": "latest",
     "@ai-matrx/realtime": "latest",
-    "@ai-matrx/alchemy": "latest"
+    "@ai-matrx/records": "latest"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",