@ai-matrx/records-ui 0.16.1 → 0.30.0

package/dist/index.d.cts

@@ -1,9 +1,11 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
-import { PermissionLevel, Table, Uuid as Uuid$1, RecordsError, Field, RecordDocument, ReadRow, WriteConflict, ParityFieldType, NewFieldDeclaration, ValueEnvelope, WorkInboxKind, RuleExpression, AggregateBucket, AggregateMeasure, DocTemplateRow, DocRenderRow, AnonTokenBinding, RecordsConfig, RecordsActor, RecordsDataSource } from '@ai-matrx/records';
+import { ReactNode, ComponentType, RefObject } from 'react';
+import { PermissionLevel, Table, Uuid as Uuid$1, AggregateFilter, RecordsError, Field, RecordDocument, ReadRow, WriteConflict, ParityFieldType, NewFieldDeclaration, ValueEnvelope, WorkInboxKind, RuleExpression, FormSummary, PortalCard, PortalPrincipal, PortalPreviewRow, DashboardBlockKind, AggregateBucket, AggregateMeasure, DashboardBlock, DashboardSummary, DocTemplateRow, DocRenderRow, DashboardBlockResult, AnonTokenBinding, RecordsConfig, RecordsActor, RecordsDataSource, FieldTypeWord } from '@ai-matrx/records';
 import { Uuid, 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';
+import { TableStyle, GroupAggregateSpec, GroupOrder, ChoiceColorLookup } from '@ai-matrx/design-system/data-table';
 
 /** The six things a person does to a record or a table, as the screens offer them. */
 type Capability = "read" | "comment" | "write" | "remove" | "share" | "structure";
@@ -269,6 +271,54 @@ interface RecordsUiHost {
      * Never a Share button that opens nothing.
      */
     share?: (subject: ShareSubject) => ReactNode;
+    /**
+     * OPTIONAL. OPEN THE RECORDS BEHIND A NUMBER (SCR-16).
+     *
+     * Every number on a dashboard is a count of real records, and the whole
+     * product row is that a person can get from the number to them: click the
+     * "Awaiting parts" column and the grid opens on the twenty-eight jobs it
+     * counted, with the block's own filter still on. That is one navigation, and
+     * WHERE the grid lives is the host's routing — so it is a port, like
+     * `hrefForRecord`, rather than a route string this package invents.
+     *
+     * Unbound, the marks are NOT clickable and the canvas says so in one
+     * sentence naming this port. A chart whose bars looked pressable and did
+     * nothing is the dead control this package does not ship.
+     */
+    openRecords?: (ask: OpenRecordsAsk) => void;
+    /**
+     * OPTIONAL. ASK THE AGENT TO CHANGE THIS DASHBOARD (SCR-16).
+     *
+     * "break it down by owner" is how a dashboard is actually built — the agent
+     * calls `dashboard_propose` on the server's `records` tool with this
+     * dashboard's id and re-states it. Only the server can do that honestly (a
+     * browser stamping itself `agent` is a browser claiming to be one), which is
+     * the same reason `enrich` is a port, so this is one too.
+     *
+     * Unbound, the box is drawn DISABLED with one sentence naming this port —
+     * never a composer that goes nowhere and never silence.
+     */
+    onReask?: (question: string, context: ReaskContext) => Promise<void>;
+}
+/**
+ * WHAT A CLICK ON A NUMBER ASKS FOR. The filter is already merged: the block's
+ * own filter (which `custom.dashboard_run` echoes back with the canvas bar
+ * folded under it) with the clicked group's key and value over the top. A host
+ * that dropped a key would open the grid on more records than the number
+ * counted, which is the one way this control can lie.
+ */
+interface OpenRecordsAsk {
+    tableId: Uuid$1;
+    filter: Record<string, AggregateFilter>;
+    /** What the person clicked, in words: "Jobs by stage this month · Awaiting parts". */
+    label: string;
+}
+/** Which dashboard a re-ask is about, so the agent re-states it rather than making a second one. */
+interface ReaskContext {
+    tableId: Uuid$1;
+    /** Null while the canvas has no dashboard yet — the answer is the first one. */
+    dashboardId: Uuid$1 | null;
+    dashboardName: string | null;
 }
 /**
  * What a host's share dialog is being opened ON. A Table is a record in this
@@ -322,6 +372,10 @@ declare const NO_SAVED_VIEWS_REASON: string;
 declare const NO_MEMBERS_REASON: string;
 /** The sentence shown when no share dialog is bound. */
 declare const NO_SHARE_REASON: string;
+/** The sentence a canvas shows when nothing is bound to open the records behind a number. */
+declare const NO_OPEN_RECORDS_REASON: string;
+/** The sentence the re-ask box shows when no agent is bound. */
+declare const NO_REASK_REASON: string;
 /** The sentence an attachment question shows when no file store is bound. */
 declare const NO_UPLOAD_REASON: string;
 declare function RecordsUiProvider({ value, children }: {
@@ -538,7 +592,7 @@ declare function useGridEditing({ tableId, fields, rows, reload, canWrite, mayWr
  * `data-matrx-cell-control` is the data table's own opt-out from whole-row
  * click, so opening a cell never also opens the record panel behind it.
  */
-declare function GridCell({ field, row, editing, canWrite, whyNot, }: {
+declare function GridCell({ field, row, editing, canWrite, whyNot, format, }: {
     field: Field;
     row: ReadRow;
     editing: GridEditing;
@@ -550,6 +604,8 @@ declare function GridCell({ field, row, editing, canWrite, whyNot, }: {
      * is the silent half of the same defect this file closes.
      */
     whyNot?: string | undefined;
+    /** The column's declared format, so the read view reads like its header. */
+    format?: FieldFormatConfig | undefined;
 }): react.JSX.Element;
 
 /**
@@ -570,6 +626,134 @@ declare function RefusalLine({ error, className }: {
     className?: string | undefined;
 }): react.JSX.Element;
 
+/**
+ * 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[];
+};
+/** 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;
+};
+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;
+
+/**
+ * WHAT A TABLE WITH NO COLUMNS SAYS. Named here because the gate asserts on it:
+ * the state it describes is what a first-time person met for two days.
+ */
+declare const NO_COLUMNS_YET = "This table has no columns yet";
+declare const NO_COLUMNS_WHY: string;
 interface GridProps {
     tableId: Uuid;
     /** Rows per page. The table's own pagination handles the rest. */
@@ -588,15 +772,46 @@ interface GridProps {
     toolbarActions?: ReactNode | undefined;
     /** Editing in place is on by default; a read-only surface (a portal) turns it off. */
     editable?: boolean | undefined;
+    /**
+     * HOW THIS TABLE LOOKS — the active saved view's colors, per-column formats
+     * and frozen columns (`presentation.ts`).
+     *
+     * It is a prop and not a read of its own because the VIEW owns it and the
+     * host already knows which view is open; a second read here would draw one
+     * view's colors over another's. Omitted, the table still formats every money
+     * and date column correctly from the Fields' own declarations — a look is an
+     * override, never the only thing that makes a column readable.
+     */
+    presentation?: GridPresentation | undefined;
+    /**
+     * THE LOOK, WRITTEN BACK. Called with the WHOLE next look when the person
+     * changes one on the table itself — picks a column to group by, shuts a
+     * section, drags a column wider.
+     *
+     * It is the same door every other view change already uses: `ViewSwitcher`
+     * folds it into its `onViewChange` patch and `TablePage` writes that patch
+     * onto the view record with `client.recordUpdate`, carrying the version it
+     * read. The Grid has no view id and must not grow one — a component that
+     * wrote to a record it was never told about would be a second, parallel way
+     * to save a view.
+     *
+     * UNBOUND, NOTHING IS DEAD. A host that binds no door still gets grouping,
+     * collapsing and resizing for this visit — they are held in the grid's own
+     * state — they are simply not remembered.
+     */
+    onPresentationChange?: ((next: GridPresentation) => void) | undefined;
     className?: string | undefined;
 }
-declare function Grid({ tableId, pageSize, onOpenRecord, onAddField, onNewRecordForm, toolbarActions, editable, className, }: GridProps): react.JSX.Element;
+declare function Grid({ tableId, pageSize, onOpenRecord, onAddField, onNewRecordForm, toolbarActions, editable, presentation, onPresentationChange, className, }: 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
  * editable in place when an editing session is passed.
  */
-declare function columnForField(field: Field$1, editing?: GridEditing | null, mayWriteRow?: (rowId: Uuid) => boolean, whyNotRow?: (rowId: Uuid) => string): MatrxColumnDef<ReadRow$1>;
+declare function columnForField(field: Field$1, editing?: GridEditing | null, mayWriteRow?: (rowId: Uuid) => boolean, whyNotRow?: (rowId: Uuid) => string, look?: {
+    format?: FieldFormatConfig;
+    frozen?: boolean;
+}): MatrxColumnDef<ReadRow$1>;
 
 interface ExportMenuProps {
     tableId: Uuid;
@@ -820,10 +1035,23 @@ declare function ProvenanceBadge({ document, fieldKey }: {
  * export, a chat line) keeps calling `renderValue` with no resolver and says
  * "Loading…" rather than printing an id.
  */
-declare function RecordValue({ field, value, document, }: {
+declare function RecordValue({ field, value, document, format, }: {
     field: Field;
     value: unknown;
     document?: RecordDocument | undefined;
+    /**
+     * The column's DECLARED format (`presentation.ts`), when it has one.
+     *
+     * A cell renderer beats `MatrxColumnDef.format` — the table hands the cell to
+     * the consumer and steps back — so a store column that declared `currency`
+     * and then drew itself here would have shown a raw `1250.5` while its own
+     * header was right-aligned for money. The primitive's formatter is asked for
+     * the text instead of a second one being written beside it, so the read view
+     * and the table can never disagree about what a number means. THE FALLBACK
+     * LAW rides along: a value that does not fit is amber with the reason, never
+     * blank.
+     */
+    format?: FieldFormatConfig | undefined;
 }): react.JSX.Element;
 
 declare const PARITY_LABEL: Record<ParityFieldType, string>;
@@ -855,6 +1083,16 @@ interface SystemFieldSpec {
     required?: boolean;
     multi?: boolean;
     config?: Record<string, unknown>;
+    /**
+     * WHAT THE BEHAVIOUR ALONE CANNOT SAY, and what the declaring door refuses a
+     * column without. A `list` has to name its choices (FLD-5/FLD-6) and a
+     * `relation` has to name the Table it points at (FLD-11) — a package table
+     * that grew one of those without saying so here would be refused by name on
+     * every organization's first load, which is the class this file just cost us.
+     */
+    options?: string[];
+    relationTarget?: Uuid$1;
+    expr?: Record<string, unknown>;
 }
 interface SystemTableSpec {
     /** The token this Table is addressed by. Every package table starts `records_ui_`. */
@@ -943,6 +1181,16 @@ interface SavedViewSpec {
      */
     ruleId?: Uuid$1 | 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 record's own id. */
 interface SavedView extends SavedViewSpec {
@@ -1169,23 +1417,52 @@ interface FormSpec {
      */
     isPublic?: boolean;
 }
-/** A form as it comes back out of the store, with its record's own id and version. */
+/**
+ * A form as `custom.forms` reports it — the spec a screen renders, plus the
+ * things only the STORE knows about it.
+ *
+ * The four store-side ids are carried on purpose. `custom.form_declare` is a
+ * RE-STATEMENT of the whole form, so a save that left `notifyRuleId` out would
+ * set it to null and the owner would quietly stop being told when somebody
+ * answers — the exact silent failure the notify Rule exists to prevent. They are
+ * read here and handed straight back by `formDeclareArgs`.
+ */
 interface SavedForm extends FormSpec {
     id: Uuid$1;
-    /**
-     * The record's version AT LOAD, read from `custom.io_revisions` for the one
-     * record being edited. The read door answers documents and not versions, so
-     * this is null until it has been read — and a save with a null version is an
-     * ordinary last-writer-wins write, exactly as the store defines it.
-     */
-    version: number | null;
+    /** draft · open · closed · full — the store's own word, never derived on a screen. */
+    state: FormSummary["state"];
+    /** The form's readable name in the store. `form_declare` keeps it across saves. */
+    slug: string;
+    /** Stops taking answers at this many. Null is no ceiling. */
+    submissionCap: number | null;
+    /** The accept Rule: what counts as a complete answer. Null holds every answer for a person. */
+    quarantineRuleId: Uuid$1 | null;
+    /** The subscription Rule that tells somebody an answer arrived. */
+    notifyRuleId: Uuid$1 | null;
 }
-/** The package-owned Table every form is a record of. */
-declare const FORM_TABLE: SystemTableSpec;
-/** The spec as the one document the store holds. */
-declare function formDocument(spec: FormSpec): Record<string, unknown>;
-/** One stored record back into the spec a screen and an agent both read. */
-declare function formFromRecord(row: ReadRow): SavedForm;
+/**
+ * The spec as `custom.anon_form.presentation` holds it.
+ *
+ * `questions` is deliberately NOT here: the door writes it itself from the
+ * argument it validated (`presentation || {"questions": p_questions}`), so the
+ * words a form is asked in and the keys it is allowed to accept can never be two
+ * different lists.
+ */
+declare function formPresentation(spec: FormSpec): Record<string, unknown>;
+/** The exact arguments `custom.form_declare` is called with, for a new form or a re-statement. */
+declare function formDeclareArgs(form: FormSpec | SavedForm): {
+    table_id: Uuid$1;
+    title: string;
+    questions: FormQuestionSpec[];
+    presentation: Record<string, unknown>;
+    submission_cap: number | null;
+    quarantine_rule_id: Uuid$1 | null;
+    notify_rule_id: Uuid$1 | null;
+    form_id: Uuid$1 | null;
+    slug: string | null;
+};
+/** One row of `custom.forms` back into the spec a screen and an agent both read. */
+declare function formFromSummary(summary: FormSummary): SavedForm;
 /**
  * THE SOURCE STAMP every submission carries. A record that arrived through a
  * form is not indistinguishable from one somebody typed into the grid: it says
@@ -1200,6 +1477,65 @@ declare function submissionStamp(args: {
     onBehalfOf?: string | null;
 }): Record<string, unknown>;
 
+interface PortalsPanelProps {
+    /**
+     * OPTIONAL. The Table whose page this rail is on. It is used for ONE thing:
+     * saying, on an opened portal, whether this table is among the ones that
+     * portal shows. It never filters the list — a portal belongs to the
+     * organization, and hiding the others would answer a question nobody asked.
+     */
+    tableId?: Uuid | undefined;
+    className?: string | undefined;
+}
+/** What a door answered, for a view that never holds a client of its own. */
+type PortalAnswer<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: RecordsError;
+};
+/**
+ * THE SENTENCE SAID BEFORE A REVOKE, and it is deliberately not generic.
+ *
+ * "Are you sure?" tells somebody nothing they did not already know. What they
+ * need is the two things that actually change: this person stops being able to
+ * sign in at all, and the records that named their client stop reaching them.
+ * The store says the same thing back in the past tense once it is done
+ * (`custom.portal_revoke`'s own `say`), and that sentence is shown too.
+ */
+declare function revokeConsequence(person: PortalPrincipal, portalTitle: string): string;
+/**
+ * THE LINE ABOVE A PREVIEW, and why it is not decoration.
+ *
+ * A preview a screen assembled for itself would be a second implementation of
+ * visibility, and the first time the two disagreed nobody would know which one
+ * was lying. This one is the store's own answer to the store's own question, so
+ * the screen can say whose eyes these are and be right.
+ */
+declare function previewLine(person: PortalPrincipal): string;
+declare function PortalsPanel({ tableId, className }: PortalsPanelProps): react.JSX.Element;
+interface PortalCardViewProps {
+    /** Exactly what `custom.portal_card` answered. */
+    card: PortalCard;
+    /** The Table whose page this is on, if any — marked among the ones shown. */
+    tableId?: Uuid | undefined;
+    /** Take one person's way in away. Answers the door's own past-tense sentence. */
+    onRevoke: (person: PortalPrincipal) => Promise<PortalAnswer<string>>;
+    /** What this person sees on one Table — `custom.portal_preview`'s answer. */
+    onPreview: (person: PortalPrincipal, tableId: Uuid) => Promise<PortalAnswer<PortalPreviewRow[]>>;
+    /** The invite control, which needs a client of its own. Absent means none is offered. */
+    invite?: ReactNode;
+    className?: string | undefined;
+}
+declare function PortalCardView({ card, tableId, onRevoke, onPreview, invite, className, }: PortalCardViewProps): react.JSX.Element;
+
+interface SubscriptionsPanelProps {
+    tableId: Uuid;
+    className?: string | undefined;
+}
+declare function SubscriptionsPanel({ tableId, className }: SubscriptionsPanelProps): react.JSX.Element;
+
 interface FormBuilderProps {
     /** The Table this form collects into. A form is a view on a real Table. */
     tableId: Uuid;
@@ -1216,13 +1552,23 @@ interface FormBuilderProps {
 }
 declare function FormBuilder({ tableId, seed, activeFormId, onActiveForm, className }: FormBuilderProps): react.JSX.Element;
 
-/** The shapes a block can take. Closed: a shape nobody drew is not offered. */
-declare const CHART_KINDS: readonly ["bar", "column", "line", "donut", "number", "table"];
-type ChartKind = (typeof CHART_KINDS)[number];
+/**
+ * The shapes a block can take. There is exactly ONE closed set and it is the
+ * store's — `custom.dashboard_kinds()` answers it and `@ai-matrx/records`
+ * carries it. A second copy here would be a list that can disagree with the
+ * door, which is how a screen comes to offer a shape the store refuses.
+ */
+type ChartKind = DashboardBlockKind;
 declare const CHART_KIND_LABEL: Record<ChartKind, string>;
+/**
+ * The shapes in the order a person reads them, derived from the labels above —
+ * which TypeScript keys exhaustively by the store's own type, so this list can
+ * never drift from the closed set.
+ */
+declare const CHART_KINDS: ChartKind[];
 /** What each shape needs before it can draw, in one sentence a block prints. */
 declare const CHART_NEEDS: Record<ChartKind, string | null>;
-/** ONE BLOCK: the question and the shape, in one declarative object. */
+/** ONE BLOCK, in the words a screen edits. */
 interface ChartSpec {
     title: string;
     /** The Table this block asks about. */
@@ -1237,33 +1583,50 @@ interface ChartSpec {
     } | null;
     /** `count` needs no key; every other measure reads one Field. */
     measures?: AggregateMeasure[];
-    /** Equality only, and the store puts it in the SAME WHERE as visibility. */
-    filter?: Record<string, string>;
+    /** A scalar is an equality; an object is a half-open moment window. */
+    filter?: Record<string, AggregateFilter>;
     limit?: number;
     /** How wide this block sits on the canvas, in twelfths. */
     span?: number;
+    /** `stuck` only: the Field whose value is watched for a change. */
+    stateKey?: string;
+    /** `stuck` only: how long a record may sit on the same value. */
+    days?: number;
 }
-/** THE WHOLE DASHBOARD, as one object an agent writes in one call. */
-interface DashboardSpec {
+/** A dashboard as `custom.dashboards` reports it, in the screen's own words. */
+interface SavedDashboard {
+    id: Uuid$1;
     name: string;
-    /** The Table most of its blocks are about. A block may name another. */
-    subject: Uuid$1;
+    /** The subject Table: the one a block that names no table of its own reads. */
+    subject: Uuid$1 | null;
     blocks: ChartSpec[];
+    presentation: Record<string, unknown>;
+    /** The store's own version. A save re-states the whole dashboard. */
+    version: number;
 }
-interface SavedDashboard extends DashboardSpec {
-    id: Uuid$1;
-    /**
-     * The record's version AT LOAD, read from `custom.io_revisions` for the one
-     * record being edited. The read door answers documents and not versions, so
-     * this is null until it has been read — and a save with a null version is an
-     * ordinary last-writer-wins write, exactly as the store defines it.
-     */
-    version: number | null;
-}
-/** The package-owned Table every dashboard is a record of. */
-declare const DASHBOARD_TABLE: SystemTableSpec;
-declare function dashboardDocument(spec: DashboardSpec): Record<string, unknown>;
-declare function dashboardFromRecord(row: ReadRow): SavedDashboard;
+/** One saved block back into the shape a screen edits. */
+declare function specFromBlock(block: DashboardBlock, subject: Uuid$1): ChartSpec;
+/**
+ * One block back into the door's own argument. `custom.dashboard_declare` judges
+ * every block on the way IN — a block naming a Field this Table does not have is
+ * refused BY NAME — so a canvas cannot be saved broken.
+ */
+declare function blockFromSpec(spec: ChartSpec, subject: Uuid$1): DashboardBlock;
+/** One row of `custom.dashboards` into the shape a screen and an agent both read. */
+declare function dashboardFromSummary(summary: DashboardSummary): SavedDashboard;
+/**
+ * The exact arguments `custom.dashboard_declare` is called with. A save is a
+ * RE-STATEMENT of the whole dashboard, so the presentation goes straight back:
+ * a save that dropped it would quietly lose the question the person asked the
+ * agent, which is what the canvas is FOR.
+ */
+declare function dashboardDeclareArgs(board: SavedDashboard, subject: Uuid$1): {
+    table_id: Uuid$1;
+    name: string;
+    blocks: DashboardBlock[];
+    presentation: Record<string, unknown>;
+    dashboard_id: Uuid$1 | null;
+};
 /**
  * The series palette. Six SEMANTIC tokens the design system already flips for
  * dark mode, so a chart is correct in both themes without a second palette and
@@ -1273,6 +1636,60 @@ declare const SERIES_COLORS: readonly ["hsl(var(--primary))", "hsl(var(--info))"
 /** The label one aggregate row carries — its groups, joined the way a person reads them. */
 declare function groupLabel(groups: Record<string, string | null>): string;
 
+/** The same shape `components/ui/chart.tsx` takes: one entry per series key. */
+type ChartConfig = Record<string, {
+    label?: ReactNode;
+    icon?: ComponentType;
+    color?: string;
+}>;
+/**
+ * MEASURE THE BOX, DO NOT ASK RECHARTS TO. Returns the ref to put on the
+ * wrapper and the width to hand the chart. `ResizeObserver` being absent is not
+ * an error: the fallback stands and the chart still draws.
+ */
+declare function useMeasuredWidth(fallback?: number): [RefObject<HTMLDivElement | null>, number];
+/**
+ * The box a chart lives in. It carries the app's own Recharts class overrides —
+ * axis ticks in `muted-foreground`, the grid and the cursor in `border`, no
+ * focus outline on a layer — so the chart sits in the page's own palette.
+ */
+declare function ChartFrame({ config, height, className, children, }: {
+    config: ChartConfig;
+    height: number;
+    className?: string | undefined;
+    children: (width: number) => ReactNode;
+}): react.JSX.Element;
+/** One payload entry as Recharts injects it into a tooltip's `content` element. */
+interface TooltipEntry {
+    name?: string | number;
+    dataKey?: string | number;
+    value?: number | string;
+    color?: string;
+    payload?: Record<string, unknown>;
+}
+/**
+ * The app's tooltip, with its markup and its classes. Recharts 3 injects
+ * `active` / `payload` / `label` into the element it clones, so they are
+ * declared optional here exactly as the app declares them.
+ */
+declare function ChartTooltipContent({ active, payload, label, config, className, }: {
+    active?: boolean;
+    payload?: ReadonlyArray<TooltipEntry>;
+    label?: ReactNode;
+    config: ChartConfig;
+    className?: string | undefined;
+}): react.JSX.Element | null;
+/** The app's legend, with its markup and its classes. */
+declare function ChartLegendContent({ payload, config, className, }: {
+    payload?: ReadonlyArray<{
+        value?: string | number;
+        color?: string;
+        dataKey?: string | number;
+    }>;
+    config: ChartConfig;
+    className?: string | undefined;
+}): react.JSX.Element | null;
+
 /** The one token form, written the way the store's own pattern reads it. */
 declare function fieldToken(fieldId: Uuid$1): string;
 /** THE DECLARATIVE SPEC an agent writes. One template, whole, in one object. */
@@ -1350,20 +1767,23 @@ interface NotifyRuleEditorProps {
 declare function NotifyRuleEditor({ tableId, seed, className }: NotifyRuleEditorProps): react.JSX.Element;
 
 interface ChartBlockProps {
-    spec: ChartSpec;
+    /** One block out of the canvas's single run — answered, or refused. */
+    block: DashboardBlockResult;
+    /** The dashboard's subject Table, for a block that names none of its own. */
+    subject: Uuid$1;
     className?: string | undefined;
 }
-declare function ChartBlock({ spec, className }: ChartBlockProps): react.JSX.Element;
+declare function ChartBlock({ block, subject, className }: ChartBlockProps): react.JSX.Element;
 
 interface DashboardCanvasProps {
     /** The Table these blocks are about. */
     tableId: Uuid;
-    /** COMPLETE declarative dashboards an agent wrote. Saved once, never overwritten. */
-    seed?: DashboardSpec[] | undefined;
     activeDashboardId?: Uuid | null | undefined;
+    /** The one filter bar across the canvas. Merged UNDER each block's own filter. */
+    filter?: Record<string, AggregateFilter> | undefined;
     className?: string | undefined;
 }
-declare function DashboardCanvas({ tableId, seed, activeDashboardId, className }: DashboardCanvasProps): react.JSX.Element;
+declare function DashboardCanvas({ tableId, activeDashboardId, filter, className }: DashboardCanvasProps): react.JSX.Element;
 
 interface FormsPanelProps {
     tableId: Uuid;
@@ -1610,7 +2030,13 @@ declare const LANE_EMPTY: Record<TableLane, string>;
 declare function laneFor(table: Table): TableLane;
 interface TablesHomeProps {
     /** Where a table opens. Absent and the card is a plain row with no pretend link. */
-    onOpenTable?: ((tableId: Uuid$1) => void) | undefined;
+    /**
+     * Opening a Table, and — with a second argument — opening it ON one of its
+     * dashboards. The second argument is optional so every existing caller is
+     * unchanged; a host that ignores it lands on the records, which is what it
+     * did before, rather than on a screen it does not know how to address.
+     */
+    onOpenTable?: ((tableId: Uuid$1, dashboardId?: Uuid$1) => void) | undefined;
     className?: string | undefined;
 }
 declare function TablesHome({ onOpenTable, className }: TablesHomeProps): react.JSX.Element;
@@ -1635,6 +2061,17 @@ interface TablePageProps {
     onLeave?: (() => void) | undefined;
     /** The word on that button. Defaults to "Back to your tables". */
     leaveLabel?: string | undefined;
+    /**
+     * OPEN ON ONE DASHBOARD, because an agent's answer ends in a LINK.
+     *
+     * `dashboard_propose` makes the whole canvas in one call and hands back an
+     * address. A link that landed on the records and left the person to find the
+     * Dashboards button, and then the right dashboard among several, is a link
+     * that did not finish the sentence the agent started. Present, this opens the
+     * canvas on that dashboard; absent, the page opens on the records exactly as
+     * it always has.
+     */
+    activeDashboardId?: Uuid$1 | null | undefined;
     className?: string | undefined;
 }
 /**
@@ -1670,18 +2107,36 @@ declare const TABLE_NOT_REACHABLE: string;
  * second kind of view that every feature after it has to know about.
  */
 declare const DEFAULT_VIEW_NAME = "All records";
-declare function TablePage({ tableId, pageSize, seedViews, onLeave, leaveLabel, className, }: TablePageProps): react.JSX.Element;
+/**
+ * What the page says while it is running on the unsaved default. It is a
+ * STAND-IN and it announces itself, with the one thing a person can do about
+ * it: the bar above saves a view, and from then on the layout is remembered.
+ */
+declare const VIEW_NOT_SAVED_YET: string;
+declare function TablePage({ tableId, pageSize, seedViews, onLeave, leaveLabel, activeDashboardId, className, }: TablePageProps): react.JSX.Element;
 
-/** One Field a person asked for, in the store's own behaviour words (FLD-1). */
+/** One Field a person asked for, in the words a person uses (FLD-1 / FLD-11). */
 interface NewFieldSpec {
     key: string;
     label: string;
-    /** A parity type — the thirteen come from the store, see `PARITY_FIELD_TYPES`. */
-    type: string;
+    /**
+     * The word for what this column holds. One of the thirteen parity types, one
+     * of the five behaviours, or a plain synonym (`text`, `long_text`, `number`)
+     * — `custom._field_document_for` resolves all three and refuses a word that
+     * means nothing, by name, with the list.
+     */
+    type: FieldTypeWord;
     sort?: number;
     required?: boolean;
     multi?: boolean;
     config?: Record<string, unknown>;
+    /** A choice list's choices, as words. The store keeps them as a Table (FLD-5). */
+    options?: string[];
+    /** A column that points at another Table of this organization (FLD-11 / REL-8). */
+    relationTarget?: Uuid$1;
+    /** A currency column's symbol; a date column's day-or-day-and-time. */
+    unit?: string;
+    kind?: "date" | "datetime";
 }
 interface NewTableSpec {
     name: string;
@@ -1693,9 +2148,16 @@ interface NewTableSpec {
     titleField?: string;
     fields?: NewFieldSpec[];
 }
-type DeclareResult = {
+type DeclareResult = 
+/**
+ * The Table's id — and its HOME's, because REC-14 gives the Table exactly one
+ * and the caller that made it is the only one that can tidy it up again. A
+ * caller reading `data` alone is unaffected.
+ */
+{
     ok: true;
     data: Uuid$1;
+    homeId: Uuid$1;
 } | {
     ok: false;
     error: RecordsError;
@@ -1716,8 +2178,24 @@ declare function tokenFor(name: string): string;
  * store then enforces it for everyone.
  */
 declare const DEFAULT_FIELDS: NewFieldSpec[];
+/**
+ * One column, in the shape `custom.field_declare` takes — and EVERYTHING a
+ * person said about it. The keys after the type are not decoration: without
+ * `options` the door refuses a choice list outright ("A list of choices needs
+ * its choices"), without `unit` a money column is dollars whatever the person
+ * picked, and without `relation_target` a column that points at another of this
+ * organization's own tables cannot be declared at all.
+ */
+declare function fieldDeclarationFor(field: NewFieldSpec): NewFieldDeclaration;
 declare function declareTable(client: RecordsClient, spec: NewTableSpec): Promise<DeclareResult>;
-/** Write Field records for an existing Table. Used by the create path and by import. */
+/**
+ * Columns for an existing Table, through the door that declares one. Used by
+ * the create path and by import.
+ *
+ * A column the store refused STOPS the sequence and hands back the store's own
+ * sentence: a Table that quietly lost a column is the silent failure this
+ * package exists to prevent.
+ */
 declare function addFields(client: RecordsClient, tableId: Uuid$1, fields: NewFieldSpec[]): Promise<{
     ok: true;
     data: Uuid$1;
@@ -1750,4 +2228,4 @@ declare function useCanShare(): boolean;
 declare function shareUnavailableReason(): string;
 declare function ShareControl({ kind, organizationId, subjectId, name, may, size, variant, className, }: ShareControlProps): ReactNode;
 
-export { ACTION_KINDS, ActionInbox, type ActionInboxProps, type ActionKind, BookingSlots, type BookingSlotsProps, CAPTURE_MODES, CHART_KINDS, CHART_KIND_LABEL, CHART_NEEDS, CHECKLIST_TABLE, COMMENT_TABLE, type Capability, type CaptureMode, type CaptureQueuePort, CaptureSheet, type CaptureSheetProps, type CellAddress, type CellRefusal, type CellState, ChartBlock, type ChartBlockProps, type ChartKind, type ChartSpec, ChecklistRunner, type ChecklistRunnerProps, type ChecklistSpec, type ChecklistStepSpec, CommentThread, type CommentThreadProps, CustomFieldsSection, type CustomFieldsSectionProps, DASHBOARD_TABLE, DEFAULT_FIELDS, DEFAULT_VIEW_NAME, DashboardCanvas, type DashboardCanvasProps, type DashboardSpec, type DeclareResult, DocRender, type DocRenderProps, DocTemplate, type DocTemplateProps, type DocTemplateSpec, type EditorKind, EmbedFrame, type EmbedFrameProps, type EnrichAsk, type EnrichOutcome, EnrichPanel, type EnrichPanelProps, ExportMenu, type ExportMenuProps, FIELD_TYPE_CHOICES, FIELD_TYPE_GROUPS, FORM_FLOWS, FORM_TABLE, FieldControl, FieldEditor, type FieldEditorControlProps, type FieldEditorProps, FieldLabel, type FieldProposalRow, type FieldTypeChoice, FormBuilder, type FormBuilderProps, type FormFlow, type FormQuestionSpec, FormRunner, type FormRunnerProps, type FormSpec, type FormSubmitOutcome, type FormTheme, FormsPanel, type FormsPanelProps, Grid, GridCell, type GridEditing, type GridProps, HistoryPanel, type HistoryPanelProps, IN_MEMORY_QUEUE_REASON, ImportWizard, type ImportWizardProps, KERNEL_REASON, LANE_EMPTY, LANE_TITLE, LAYOUT_FIELD_KIND, LAYOUT_LABEL, LAYOUT_NEEDS, LAYOUT_NO_FIELD, LEVEL_WORD, type LabelLookup, MACHINE_IDENTITY, NOT_ANSWERED_YET, NO_CHAT_REASON, NO_ENRICH_REASON, NO_MEMBERS_REASON, NO_RIGHTS, NO_SAVED_VIEWS_REASON, NO_SHARE_REASON, NO_UPLOAD_REASON, type NewFieldSpec, type NewTableSpec, NotifyRuleEditor, type NotifyRuleEditorProps, type NotifyRuleSpec, type OrganizationMember, PARITY_LABEL, PARITY_MADE_OF, Peek, type PeekProps, type PendingCapture, PersonPicker, type PersonPickerProps, type PickableFieldType, type PlainFieldType, type PlainRefusal, PortalShell, type PortalShellProps, type ProposalOutcome, ProposalRow, type ProposalRowProps, type ProposedChange, ProvenanceBadge, PublicViewPage, type PublicViewPageProps, RecordChat, type RecordChatContext, type RecordChatEntry, type RecordChatProps, type RecordChatWithheld, RecordChip, RecordForm, type RecordFormProps, RecordLabelProvider, RecordValue, RecordsMount, type RecordsMountProps, type RecordsUiHost, RecordsUiProvider, RefusalLine, RefusalNotice, RelationPicker, type RelationPickerProps, SERIES_COLORS, STORE_DECIDES_REASON, type SavedDashboard, type SavedForm, type SavedView, type SavedViewSpec, ShareControl, type ShareControlProps, type ShareSubject, SignBlock, type SignBlockProps, type SystemFieldSpec, type SystemTableSpec, TABLE_LANES, TABLE_NOT_REACHABLE, type TableLane, TablePage, type TablePageProps, type TableRights, TableSettings, type TableSettingsProps, TablesHome, type TablesHomeProps, type TrackedVersion, type UseSystemTableState, VIEW_LAYOUTS, VIEW_TABLE, ViewBar, type ViewBarProps, type ViewLayout, type ViewSort, ViewSwitcher, type ViewSwitcherProps, type WhatYouMayDo, addFields, bodyForReading, bodyFromKeys, columnForField, dashboardDocument, dashboardFromRecord, declareTable, editorKindFor, ensureSystemTable, envelopeFor, fieldIsEditable, fieldName, fieldToken, fieldTypeChoice, fieldTypeLabel, formDocument, formFromRecord, groupLabel, hintForAPerson, hintIsMachineIdentity, humanize, idsOf, isId, isMachineIdentity, isPlainFieldType, isSignatureField, keyFor, laneFor, machineIdentityIn, memberName, parityTypesWithNoExplanation, personActor, personRecordForMember, pointsAtRecords, recordName, recordsDataSource, refusalForAPerson, refusalLineForAPerson, renderValue, rowName, scalarText, shareUnavailableReason, storeDecidesRights, submissionStamp, tableName, tableRightsAt, tokenFor, useCanShare, useEmbedHandshake, useGridEditing, useRecordLabels, useRecordRights, useRecordsUi, useRowRights, useSystemTable, useTableRights, useViewRecords, viewDocument, viewFromRecord, viewPatchDocument, whatIsMissing, whatYouMayDo, whatYouMayDoWithTable };
+export { ACTION_KINDS, ActionInbox, type ActionInboxProps, type ActionKind, BookingSlots, type BookingSlotsProps, CAPTURE_MODES, CHART_KINDS, CHART_KIND_LABEL, CHART_NEEDS, CHECKLIST_TABLE, COMMENT_TABLE, type Capability, type CaptureMode, type CaptureQueuePort, CaptureSheet, type CaptureSheetProps, type CellAddress, type CellRefusal, type CellState, ChartBlock, type ChartBlockProps, type ChartConfig, ChartFrame, type ChartKind, ChartLegendContent, type ChartSpec, ChartTooltipContent, ChecklistRunner, type ChecklistRunnerProps, type ChecklistSpec, type ChecklistStepSpec, CommentThread, type CommentThreadProps, CustomFieldsSection, type CustomFieldsSectionProps, DEFAULT_FIELDS, DEFAULT_VIEW_NAME, DashboardCanvas, type DashboardCanvasProps, type DeclareResult, DocRender, type DocRenderProps, DocTemplate, type DocTemplateProps, type DocTemplateSpec, EMPTY_PRESENTATION, type EditorKind, EmbedFrame, type EmbedFrameProps, type EnrichAsk, type EnrichOutcome, EnrichPanel, type EnrichPanelProps, ExportMenu, type ExportMenuProps, FIELD_TYPE_CHOICES, FIELD_TYPE_GROUPS, FORM_FLOWS, FROZEN_COLUMN_WIDTH, FieldControl, FieldEditor, type FieldEditorControlProps, type FieldEditorProps, FieldLabel, type FieldProposalRow, type FieldTypeChoice, FormBuilder, type FormBuilderProps, type FormFlow, type FormQuestionSpec, FormRunner, type FormRunnerProps, type FormSpec, type FormSubmitOutcome, type FormTheme, FormsPanel, type FormsPanelProps, Grid, GridCell, type GridEditing, type GridGrouping, type GridPresentation, type GridProps, HistoryPanel, type HistoryPanelProps, IN_MEMORY_QUEUE_REASON, ImportWizard, type ImportWizardProps, KERNEL_REASON, LANE_EMPTY, LANE_TITLE, LAYOUT_FIELD_KIND, LAYOUT_LABEL, LAYOUT_NEEDS, LAYOUT_NO_FIELD, LEVEL_WORD, type LabelLookup, MACHINE_IDENTITY, MAX_ROW_HEIGHT, MIN_ROW_HEIGHT, NOT_ANSWERED_YET, NO_CHAT_REASON, NO_COLUMNS_WHY, NO_COLUMNS_YET, NO_ENRICH_REASON, NO_MEMBERS_REASON, NO_OPEN_RECORDS_REASON, NO_REASK_REASON, NO_RIGHTS, NO_SAVED_VIEWS_REASON, NO_SHARE_REASON, NO_UPLOAD_REASON, type NewFieldSpec, type NewTableSpec, NotifyRuleEditor, type NotifyRuleEditorProps, type NotifyRuleSpec, type OpenRecordsAsk, type OrganizationMember, PARITY_LABEL, PARITY_MADE_OF, Peek, type PeekProps, type PendingCapture, PersonPicker, type PersonPickerProps, type PickableFieldType, type PlainFieldType, type PlainRefusal, type PortalAnswer, PortalCardView, type PortalCardViewProps, PortalShell, type PortalShellProps, PortalsPanel, type PortalsPanelProps, type ProposalOutcome, ProposalRow, type ProposalRowProps, type ProposedChange, ProvenanceBadge, PublicViewPage, type PublicViewPageProps, type ReaskContext, RecordChat, type RecordChatContext, type RecordChatEntry, type RecordChatProps, type RecordChatWithheld, RecordChip, RecordForm, type RecordFormProps, RecordLabelProvider, RecordValue, RecordsMount, type RecordsMountProps, type RecordsUiHost, RecordsUiProvider, RefusalLine, RefusalNotice, RelationPicker, type RelationPickerProps, SERIES_COLORS, STORE_DECIDES_REASON, type SavedDashboard, type SavedForm, type SavedView, type SavedViewSpec, ShareControl, type ShareControlProps, type ShareSubject, SignBlock, type SignBlockProps, SubscriptionsPanel, type SubscriptionsPanelProps, type SystemFieldSpec, type SystemTableSpec, TABLE_LANES, TABLE_NOT_REACHABLE, type TableLane, TablePage, type TablePageProps, type TableRights, TableSettings, type TableSettingsProps, TablesHome, type TablesHomeProps, type TrackedVersion, type UseSystemTableState, VIEW_LAYOUTS, VIEW_NOT_SAVED_YET, VIEW_TABLE, ViewBar, type ViewBarProps, type ViewLayout, type ViewSort, ViewSwitcher, type ViewSwitcherProps, type WhatYouMayDo, addFields, blockFromSpec, bodyForReading, bodyFromKeys, colorFromTheValue, columnForField, currencyCodeFor, dashboardDeclareArgs, dashboardFromSummary, declareTable, editorKindFor, ensureSystemTable, envelopeFor, fieldDeclarationFor, fieldIsEditable, fieldName, fieldToken, fieldTypeChoice, fieldTypeLabel, formDeclareArgs, formFromSummary, formPresentation, formatForField, groupLabel, hintForAPerson, hintIsMachineIdentity, humanize, idsOf, isId, isMachineIdentity, isPlainFieldType, isSignatureField, keyFor, laneFor, machineIdentityIn, memberName, parityTypesWithNoExplanation, parseGridPresentation, personActor, personRecordForMember, pointsAtRecords, presentationDocument, presentationIsEmpty, previewLine, recordName, recordsDataSource, refusalForAPerson, refusalLineForAPerson, renderValue, revokeConsequence, rowName, scalarText, shareUnavailableReason, specFromBlock, storeDecidesRights, submissionStamp, tableName, tableRightsAt, tokenFor, useCanShare, useEmbedHandshake, useGridEditing, useMeasuredWidth, useRecordLabels, useRecordRights, useRecordsUi, useRowRights, useSystemTable, useTableRights, useViewRecords, viewDocument, viewFromRecord, viewPatchDocument, whatIsMissing, whatYouMayDo, whatYouMayDoWithTable };