@ai-matrx/design-system 0.21.13 → 0.22.0

package/dist/{types-D9b_LfTB.d.ts → types-D-flTpK0.d.ts}

@@ -1,6 +1,7 @@
 import { ContentTransferReference } from './content-transfer.js';
 import { ReactNode } from 'react';
 import { AiVariant, AiCustomSource, CopyExportConfig } from './data-table/copy-types.js';
+import { b as FieldFormatConfig } from './types-BdbvlF9-.js';
 
 type TableSearchRole = "id" | "name" | "description" | "other";
 interface TableSearchScope {
@@ -14,6 +15,9 @@ interface TableRankedSearchOptions {
     scopes?: readonly TableSearchScope[];
     matchMode?: TableSearchMatchMode;
 }
+/** Column metadata overrides inference; identity substrings always outrank prose. */
+declare function inferTableSearchRole(field: string): TableSearchRole;
+declare function resolveTableSearchScopes<T>(rows: readonly T[], columns: readonly MatrxColumnDef<T>[], options?: TableRankedSearchOptions): TableSearchScope[];
 /** Apply to the complete authorized result BEFORE slicing pages. Remote owners
  * must implement the same contract at their source, never on a partial page. */
 declare function rankTableSearchRows<T>(rows: readonly T[], columns: readonly MatrxColumnDef<T>[], query: string, options?: TableRankedSearchOptions, extraText?: (row: T) => string): T[];
@@ -77,6 +81,151 @@ declare function columnFiltersToLayeredRules(filters: ColumnFiltersState, fieldI
 declare function layeredFilterMatchesValue(value: unknown, rule: LayeredFilterRule): boolean;
 declare function layeredFilterRuleSummary(rule: LayeredFilterRule, fields: readonly LayeredFilterField[]): string;
 
+/**
+ * Table style — colors on a user data table, the Airtable way.
+ *
+ * WHAT IS ALLOWED, AND WHY ONLY THIS. A typed dataset is not a canvas; the
+ * platform already has Workbooks (Univer) for arbitrary per-cell formatting.
+ * Here, color carries MEANING and stays out of the data:
+ *
+ *   1. COLOR BY A COLUMN — a choice column's option colors (or a boolean's
+ *      true/false) tint the row or that column's cells. Zero configuration:
+ *      the Status column already knows "Blocked" is red.
+ *   2. RULES — "when Amount > 1000, tint the row amber". Evaluated live, so a
+ *      tint is never stale.
+ *   3. MANUAL HIGHLIGHTS — a small palette on a cell, a row, or a column, for
+ *      the "look at this one" gesture. The same palette the choice chips use,
+ *      so the table never has two vocabularies of color.
+ *
+ * WHERE IT LIVES. This module is the MODEL only — pure, no React, no DOM, no
+ * network. Each consumer names its own home for the same document and writes it
+ * surgically BY PATH (`stylePath.*`), so two editors highlighting different
+ * cells never overwrite each other:
+ *
+ *   - user data tables (`/data`): `udt_datasets.metadata.style`, written by
+ *     `public.udt_set_table_style(p_table_id, p_path, p_value)`.
+ *   - the record store: the table's saved view / Table settings document,
+ *     written by `custom.table_style_set(p_table, p_path, p_value)`.
+ *
+ * Copy, export, agents and the data itself never see the style.
+ *
+ * PRECEDENCE (most deliberate wins): a manual cell highlight > a cell rule >
+ * color-by targeting cells > a manual column highlight, for the CELL; a manual
+ * row highlight > a row rule > color-by targeting rows, for the ROW. A cell
+ * tint always paints over the row tint underneath it.
+ *
+ * Pure module: no React, no DOM, no Supabase.
+ */
+declare const TABLE_STYLE_VERSION: 1;
+/**
+ * The highlight palette.
+ *
+ * These are the SAME seven names the choice-chip palette uses minus "neutral"
+ * (which means "no color"), spelled out here so the model carries no import at
+ * all. Names, never raw hex: a name is legible on both grounds because each one
+ * ships its own `dark:` class below, and a retired name degrades to "no color"
+ * instead of to an unreadable swatch. A consumer that also draws choice chips
+ * must keep its chip palette on these names, or the table grows two vocabularies
+ * of color.
+ */
+declare const STYLE_COLORS: readonly ["slate", "green", "amber", "red", "blue", "violet", "teal"];
+type StyleColor = (typeof STYLE_COLORS)[number];
+declare function isStyleColor(v: unknown): v is StyleColor;
+declare const COLOR_RULE_OPS: readonly ["is", "is_not", "contains", "is_empty", "not_empty", "is_true", "is_false", "gt", "gte", "lt", "lte"];
+type ColorRuleOp = (typeof COLOR_RULE_OPS)[number];
+/** Which ops take a value to compare against. */
+declare const OPS_WITH_VALUE: readonly ColorRuleOp[];
+declare const COLOR_RULE_OP_LABELS: Record<ColorRuleOp, string>;
+type StyleTarget = "row" | "cell";
+type ColorRule = {
+    id: string;
+    /** Machine field name the condition reads. */
+    field: string;
+    op: ColorRuleOp;
+    /** Compared as text for `is` / `is_not` / `contains`, as a number for gt/lt. */
+    value?: string;
+    color: StyleColor;
+    /** Tint the whole row, or only this column's cell. */
+    target: StyleTarget;
+};
+type ColorBy = {
+    field: string;
+    target: StyleTarget;
+};
+type TableStyle = {
+    version: typeof TABLE_STYLE_VERSION;
+    colorBy?: ColorBy | null;
+    rules?: ColorRule[];
+    /** Manual row highlights, by row id. */
+    rows?: Record<string, StyleColor>;
+    /** Manual cell highlights, by row id then field name. */
+    cells?: Record<string, Record<string, StyleColor>>;
+    /** Manual column highlights, by field name. */
+    columns?: Record<string, StyleColor>;
+};
+declare const EMPTY_TABLE_STYLE: TableStyle;
+/** The conventional key the style document lives under on a table's own metadata. */
+declare const TABLE_STYLE_METADATA_KEY = "style";
+/** True when nothing in the style would paint anything. */
+declare function tableStyleIsEmpty(style: TableStyle): boolean;
+/**
+ * Read a style off table metadata. Tolerant by design: an unknown key, a
+ * retired color name or a malformed rule is dropped, never thrown, because a
+ * table must still render when its style is stale.
+ */
+declare function parseTableStyle(raw: unknown): TableStyle;
+/** Style out of a table-metadata blob (or null / undefined). */
+declare function tableStyleFromMetadata(metadata: unknown): TableStyle;
+/** Does `value` satisfy `rule`? Text ops compare case-insensitively; number ops parse both sides. */
+declare function evaluateRule(rule: ColorRule, value: unknown): boolean;
+/**
+ * The color a choice / boolean column gives a value, for color-by. The caller
+ * supplies the lookup because option colors live on the resolved choice list
+ * (which may come from a structured list), not on the style.
+ */
+type ChoiceColorLookup = (fieldName: string, value: unknown) => StyleColor | undefined;
+/**
+ * The color an option paints with. An option that DECLARED a color uses it; an
+ * option without one gets a stable color from its position in the list, so
+ * "color rows by Status" always paints something — Airtable assigns every
+ * option a color for the same reason. A column whose options were never
+ * colored would otherwise look like color-by did nothing at all.
+ */
+declare function colorForChoice(choices: readonly {
+    value: string;
+    color?: string;
+}[] | undefined, value: unknown): StyleColor | undefined;
+/**
+ * Boolean columns have no option list; color-by paints true green and leaves
+ * false untinted, which is the "done / not done" reading every checklist has.
+ */
+declare const BOOLEAN_TRUE_COLOR: StyleColor;
+/** The tint for a whole row, or null for none. */
+declare function resolveRowColor(style: TableStyle, row: {
+    id: string;
+    data: Record<string, unknown>;
+}, choiceColorFor: ChoiceColorLookup): StyleColor | null;
+/** The tint for one cell (painted over the row tint), or null for none. */
+declare function resolveCellColor(style: TableStyle, row: {
+    id: string;
+    data: Record<string, unknown>;
+}, fieldName: string, choiceColorFor: ChoiceColorLookup): StyleColor | null;
+declare const ROW_TINT_CLASS: Record<StyleColor, string>;
+declare const CELL_TINT_CLASS: Record<StyleColor, string>;
+/** A solid swatch for palette menus. */
+declare const SWATCH_CLASS: Record<StyleColor, string>;
+declare const STYLE_COLOR_LABELS: Record<StyleColor, string>;
+type StylePath = readonly string[];
+declare const stylePath: {
+    colorBy: () => StylePath;
+    rules: () => StylePath;
+    row: (rowId: string) => StylePath;
+    cell: (rowId: string, fieldName: string) => StylePath;
+    column: (fieldName: string) => StylePath;
+};
+/** Apply a path write locally, so the grid repaints before the round trip returns. */
+declare function applyStylePath(style: TableStyle, path: StylePath, value: unknown): TableStyle;
+
 /** How a column's filter UI behaves. `auto` infers from sample values. */
 type ColumnFilterKind = "auto" | "text" | "select" | "boolean" | "number" | false;
 type SortDirection = "asc" | "desc";
@@ -256,6 +405,36 @@ interface MatrxColumnDef<T> {
         /** Force non-navigable for this column. */
         forbidden?: boolean | ((id: string, row: T) => boolean);
     };
+    /**
+     * How this column's value READS — money, percent, a date style, decimal
+     * places. The vocabulary is the platform's one field-format registry
+     * (`@ai-matrx/design-system/field-formats`), the same `{id, options}` a user
+     * data table stores on its column and the record store stores on its Field,
+     * so `$1,234.56` is the same `$1,234.56` on every table in the product.
+     *
+     * A declarative format, not another render function, because a `cell`
+     * callback is invisible to everything else: with `format` the column also
+     * right-aligns itself, and a consumer's own `cell` asks the primitive for the
+     * same text through `formatColumnValue(col, value)` rather than growing a
+     * second money formatter beside this one.
+     *
+     * THE FALLBACK LAW travels with it: a value that does not fit the declared
+     * format is never blanked and never throws — it renders its base-type text in
+     * amber with the reason on hover, so the person SEES the mismatch.
+     *
+     * `cell` still wins when both are set.
+     */
+    format?: FieldFormatConfig;
+    /**
+     * Keep this column in place while the rest of the table scrolls sideways.
+     *
+     * Only the LEADING RUN freezes, only from `sm:` up, and only when the widths
+     * the offsets need are known — `./frozen-columns.ts` says why each of those
+     * three is a rule and not a default. Give a frozen column an explicit
+     * `width`; without one the table declines to freeze anything rather than pin
+     * a column at a guessed offset.
+     */
+    frozen?: boolean;
     className?: string;
     headerClassName?: string;
     width?: string | number;
@@ -397,6 +576,14 @@ interface MatrxTablePagination<T> {
     };
     retrySource?: () => void;
     sourceUntil?: string;
+    /** Source records differ from rendered rows when the host groups occurrences. */
+    sourceRecords?: {
+        loaded: number;
+        total?: number | undefined;
+        label: string;
+        rowLabel: string;
+        matchedRecords?: number;
+    };
     sourcePageSize?: {
         value: number;
         options: readonly number[];
@@ -568,6 +755,17 @@ interface TableViewSnapshot {
         hidden: string[];
         widths?: Record<string, number>;
     };
+    /**
+     * The view's COLORS — color-by-a-column, rules, and manual highlights
+     * (`./table-style.ts`). Optional so every view saved before colors existed
+     * still parses; absent means "this view paints nothing".
+     *
+     * Colors belong to the VIEW and not to the data, for the same reason the
+     * filters do: two people can read one table two ways, and neither reading is
+     * a fact about the records. That is also why this snapshot is the only place
+     * a style is carried — copy, export and agents read the rows, never this.
+     */
+    style?: TableStyle;
 }
 /** Host port for durable named views. The host owns actor, tenancy and CRUD. */
 interface TableSavedViewsProps {
@@ -844,6 +1042,28 @@ interface MatrxDataTableMobileCardControls {
     expandedDetail: ReactNode;
 }
 type MatrxDataTableDensity = "condensed" | "normal" | "spacious";
+/**
+ * What the table needs in order to paint a `TableStyle` itself.
+ *
+ * `fieldOf` exists because a style names DATA fields ("tint the row when
+ * `status` is Blocked") while the table addresses COLUMNS. In the common case
+ * the column id IS the field name and the default is right; a table whose
+ * column ids are decorated (`records-grid-notes`) maps them here.
+ */
+interface MatrxDataTableStyleConfig<T> {
+    /** The style document. */
+    style: TableStyle;
+    /** The row's data as the rules read it. Defaults to the row itself. */
+    documentOf?: (row: T) => Record<string, unknown>;
+    /** Column id to the field name a rule would name. Defaults to identity. */
+    fieldOf?: (columnId: string) => string;
+    /**
+     * The color a choice column's option paints with, for color-by. The consumer
+     * supplies it because option colors live on the resolved option list, which
+     * may come from a shared pick list this package cannot reach.
+     */
+    choiceColorFor?: ChoiceColorLookup;
+}
 interface MatrxDataTableProps<T> {
     data: T[];
     columns: MatrxColumnDef<T>[];
@@ -953,6 +1173,26 @@ interface MatrxDataTableProps<T> {
     footerRows?: T[];
     /** Per-row presentation class, after canonical selection/highlight state. */
     rowClassName?: (row: T, index: number) => string | undefined;
+    /**
+     * Per-CELL presentation class, after the column's own static `className`.
+     *
+     * The primitive had `rowClassName` and a static per-column `className`, and
+     * nothing in between — so every table that needed to say something about ONE
+     * cell had to grow a `cell` render function and paint inside it, where the
+     * table can no longer see it. This is the missing rung, and `tableStyle`
+     * below is the declarative thing built on top of it.
+     */
+    cellClassName?: (row: T, columnId: string, index: number) => string | undefined;
+    /**
+     * COLORS, declaratively — color by a column, rules, manual highlights.
+     *
+     * The model is `./table-style.ts`: one document, evaluated live on every
+     * render so a tint is never stale, with a documented precedence between the
+     * three ways a cell can earn a color. Pass the document and the table paints
+     * itself; the consumer owns only where that document is STORED and how a
+     * person edits it.
+     */
+    tableStyle?: MatrxDataTableStyleConfig<T>;
     /** Highlight an index in the currently rendered page without selecting it. */
     highlightedIndex?: number | undefined;
     /** Receives the complete visible local view after local processing, before paging. Attaching after absence receives one snapshot; callback identity changes alone do not notify. */
@@ -1018,4 +1258,4 @@ interface MatrxDataTableProps<T> {
     onRowOpen?: (row: T) => void;
 }
 
-export { type AnyOfColumnSearch as A, type MatrxDataTableWindowConfig as B, type ColumnFiltersState as C, type MatrxTablePagination as D, type SortDirection as E, type TableViewQuery as F, type TextFilterMode as G, type ToolbarFacet as H, rankTableSearchRows as I, LAYERED_FILTER_OPERATORS as J, LAYERED_FILTER_OPERATOR_LABELS as K, type LayeredFilterRule as L, type MatrxColumnDef as M, type LayeredFilterField as N, type LayeredFilterOperator as O, columnFiltersToLayeredRules as P, completeLayeredFilterRules as Q, decodeLayeredFilterRules as R, type SortState as S, type TableSearchMatchMode as T, encodeLayeredFilterRules as U, isCompleteLayeredFilterRule as V, isLayeredFilterOperator as W, layeredFilterMatchesValue as X, layeredFilterNeedsValue as Y, layeredFilterRuleSummary as Z, operatorsForLayeredField as _, type ColumnFilterValue as a, type TableSavedViewsProps as b, type MatrxDataTableRecordControls as c, type MatrxDataTableDensity as d, type MatrxDataTableQueryState as e, type ColumnFilterKind as f, type MatrxDataTableCopyConfig as g, type MatrxDataTableProps as h, type TableViewSnapshot as i, type ColumnMarker as j, type CellEditType as k, type CellEditsMap as l, type MatrxDataTableContextMenuConfig as m, type MatrxDataTableDetailConfig as n, type MatrxDataTableEditConfig as o, type MatrxDataTableEmptyState as p, type MatrxDataTableExpandedDetailConfig as q, type MatrxDataTableFilterUi as r, type MatrxDataTableHierarchyConfig as s, type MatrxDataTableHierarchyMove as t, type MatrxDataTableMobileCardControls as u, type MatrxDataTableQueryControl as v, type MatrxDataTableSelectionConfig as w, type MatrxDataTableSourceProcessing as x, type MatrxDataTableToolbar as y, type MatrxDataTableUrlStateConfig as z };
+export { TABLE_STYLE_METADATA_KEY as $, type AnyOfColumnSearch as A, BOOLEAN_TRUE_COLOR as B, type ColumnFiltersState as C, type MatrxDataTableHierarchyMove as D, EMPTY_TABLE_STYLE as E, type MatrxDataTableMobileCardControls as F, type MatrxDataTableQueryControl as G, type MatrxDataTableSelectionConfig as H, type MatrxDataTableSourceProcessing as I, type MatrxDataTableStyleConfig as J, type MatrxDataTableToolbar as K, type LayeredFilterRule as L, type MatrxColumnDef as M, type MatrxDataTableUrlStateConfig as N, type MatrxDataTableWindowConfig as O, type MatrxTablePagination as P, OPS_WITH_VALUE as Q, ROW_TINT_CLASS as R, type SortState as S, type TableSearchMatchMode as T, STYLE_COLORS as U, STYLE_COLOR_LABELS as V, SWATCH_CLASS as W, type SortDirection as X, type StyleColor as Y, type StylePath as Z, type StyleTarget as _, type ColumnFilterValue as a, TABLE_STYLE_VERSION as a0, type TableRankedSearchOptions as a1, type TableSearchRole as a2, type TableSearchScope as a3, type TableStyle as a4, type TableViewQuery as a5, type TextFilterMode as a6, type ToolbarFacet as a7, applyStylePath as a8, colorForChoice as a9, evaluateRule as aa, inferTableSearchRole as ab, isStyleColor as ac, parseTableStyle as ad, rankTableSearchRows as ae, resolveCellColor as af, resolveRowColor as ag, resolveTableSearchScopes as ah, stylePath as ai, tableStyleFromMetadata as aj, tableStyleIsEmpty as ak, LAYERED_FILTER_OPERATORS as al, LAYERED_FILTER_OPERATOR_LABELS as am, type LayeredFilterField as an, type LayeredFilterOperator as ao, columnFiltersToLayeredRules as ap, completeLayeredFilterRules as aq, decodeLayeredFilterRules as ar, encodeLayeredFilterRules as as, isCompleteLayeredFilterRule as at, isLayeredFilterOperator as au, layeredFilterMatchesValue as av, layeredFilterNeedsValue as aw, layeredFilterRuleSummary as ax, operatorsForLayeredField as ay, type TableSavedViewsProps as b, type MatrxDataTableRecordControls as c, type MatrxDataTableDensity as d, type MatrxDataTableQueryState as e, type ColumnFilterKind as f, type MatrxDataTableCopyConfig as g, type MatrxDataTableProps as h, type TableViewSnapshot as i, type ColumnMarker as j, CELL_TINT_CLASS as k, COLOR_RULE_OPS as l, COLOR_RULE_OP_LABELS as m, type CellEditType as n, type CellEditsMap as o, type ChoiceColorLookup as p, type ColorBy as q, type ColorRule as r, type ColorRuleOp as s, type MatrxDataTableContextMenuConfig as t, type MatrxDataTableDetailConfig as u, type MatrxDataTableEditConfig as v, type MatrxDataTableEmptyState as w, type MatrxDataTableExpandedDetailConfig as x, type MatrxDataTableFilterUi as y, type MatrxDataTableHierarchyConfig as z };

package/dist/{types-DaKPLM6T.d.cts → types-Sn249eoy.d.cts}

@@ -1,6 +1,7 @@
 import { ContentTransferReference } from './content-transfer.cjs';
 import { ReactNode } from 'react';
 import { AiVariant, AiCustomSource, CopyExportConfig } from './data-table/copy-types.cjs';
+import { b as FieldFormatConfig } from './types-BdbvlF9-.cjs';
 
 type TableSearchRole = "id" | "name" | "description" | "other";
 interface TableSearchScope {
@@ -14,6 +15,9 @@ interface TableRankedSearchOptions {
     scopes?: readonly TableSearchScope[];
     matchMode?: TableSearchMatchMode;
 }
+/** Column metadata overrides inference; identity substrings always outrank prose. */
+declare function inferTableSearchRole(field: string): TableSearchRole;
+declare function resolveTableSearchScopes<T>(rows: readonly T[], columns: readonly MatrxColumnDef<T>[], options?: TableRankedSearchOptions): TableSearchScope[];
 /** Apply to the complete authorized result BEFORE slicing pages. Remote owners
  * must implement the same contract at their source, never on a partial page. */
 declare function rankTableSearchRows<T>(rows: readonly T[], columns: readonly MatrxColumnDef<T>[], query: string, options?: TableRankedSearchOptions, extraText?: (row: T) => string): T[];
@@ -77,6 +81,151 @@ declare function columnFiltersToLayeredRules(filters: ColumnFiltersState, fieldI
 declare function layeredFilterMatchesValue(value: unknown, rule: LayeredFilterRule): boolean;
 declare function layeredFilterRuleSummary(rule: LayeredFilterRule, fields: readonly LayeredFilterField[]): string;
 
+/**
+ * Table style — colors on a user data table, the Airtable way.
+ *
+ * WHAT IS ALLOWED, AND WHY ONLY THIS. A typed dataset is not a canvas; the
+ * platform already has Workbooks (Univer) for arbitrary per-cell formatting.
+ * Here, color carries MEANING and stays out of the data:
+ *
+ *   1. COLOR BY A COLUMN — a choice column's option colors (or a boolean's
+ *      true/false) tint the row or that column's cells. Zero configuration:
+ *      the Status column already knows "Blocked" is red.
+ *   2. RULES — "when Amount > 1000, tint the row amber". Evaluated live, so a
+ *      tint is never stale.
+ *   3. MANUAL HIGHLIGHTS — a small palette on a cell, a row, or a column, for
+ *      the "look at this one" gesture. The same palette the choice chips use,
+ *      so the table never has two vocabularies of color.
+ *
+ * WHERE IT LIVES. This module is the MODEL only — pure, no React, no DOM, no
+ * network. Each consumer names its own home for the same document and writes it
+ * surgically BY PATH (`stylePath.*`), so two editors highlighting different
+ * cells never overwrite each other:
+ *
+ *   - user data tables (`/data`): `udt_datasets.metadata.style`, written by
+ *     `public.udt_set_table_style(p_table_id, p_path, p_value)`.
+ *   - the record store: the table's saved view / Table settings document,
+ *     written by `custom.table_style_set(p_table, p_path, p_value)`.
+ *
+ * Copy, export, agents and the data itself never see the style.
+ *
+ * PRECEDENCE (most deliberate wins): a manual cell highlight > a cell rule >
+ * color-by targeting cells > a manual column highlight, for the CELL; a manual
+ * row highlight > a row rule > color-by targeting rows, for the ROW. A cell
+ * tint always paints over the row tint underneath it.
+ *
+ * Pure module: no React, no DOM, no Supabase.
+ */
+declare const TABLE_STYLE_VERSION: 1;
+/**
+ * The highlight palette.
+ *
+ * These are the SAME seven names the choice-chip palette uses minus "neutral"
+ * (which means "no color"), spelled out here so the model carries no import at
+ * all. Names, never raw hex: a name is legible on both grounds because each one
+ * ships its own `dark:` class below, and a retired name degrades to "no color"
+ * instead of to an unreadable swatch. A consumer that also draws choice chips
+ * must keep its chip palette on these names, or the table grows two vocabularies
+ * of color.
+ */
+declare const STYLE_COLORS: readonly ["slate", "green", "amber", "red", "blue", "violet", "teal"];
+type StyleColor = (typeof STYLE_COLORS)[number];
+declare function isStyleColor(v: unknown): v is StyleColor;
+declare const COLOR_RULE_OPS: readonly ["is", "is_not", "contains", "is_empty", "not_empty", "is_true", "is_false", "gt", "gte", "lt", "lte"];
+type ColorRuleOp = (typeof COLOR_RULE_OPS)[number];
+/** Which ops take a value to compare against. */
+declare const OPS_WITH_VALUE: readonly ColorRuleOp[];
+declare const COLOR_RULE_OP_LABELS: Record<ColorRuleOp, string>;
+type StyleTarget = "row" | "cell";
+type ColorRule = {
+    id: string;
+    /** Machine field name the condition reads. */
+    field: string;
+    op: ColorRuleOp;
+    /** Compared as text for `is` / `is_not` / `contains`, as a number for gt/lt. */
+    value?: string;
+    color: StyleColor;
+    /** Tint the whole row, or only this column's cell. */
+    target: StyleTarget;
+};
+type ColorBy = {
+    field: string;
+    target: StyleTarget;
+};
+type TableStyle = {
+    version: typeof TABLE_STYLE_VERSION;
+    colorBy?: ColorBy | null;
+    rules?: ColorRule[];
+    /** Manual row highlights, by row id. */
+    rows?: Record<string, StyleColor>;
+    /** Manual cell highlights, by row id then field name. */
+    cells?: Record<string, Record<string, StyleColor>>;
+    /** Manual column highlights, by field name. */
+    columns?: Record<string, StyleColor>;
+};
+declare const EMPTY_TABLE_STYLE: TableStyle;
+/** The conventional key the style document lives under on a table's own metadata. */
+declare const TABLE_STYLE_METADATA_KEY = "style";
+/** True when nothing in the style would paint anything. */
+declare function tableStyleIsEmpty(style: TableStyle): boolean;
+/**
+ * Read a style off table metadata. Tolerant by design: an unknown key, a
+ * retired color name or a malformed rule is dropped, never thrown, because a
+ * table must still render when its style is stale.
+ */
+declare function parseTableStyle(raw: unknown): TableStyle;
+/** Style out of a table-metadata blob (or null / undefined). */
+declare function tableStyleFromMetadata(metadata: unknown): TableStyle;
+/** Does `value` satisfy `rule`? Text ops compare case-insensitively; number ops parse both sides. */
+declare function evaluateRule(rule: ColorRule, value: unknown): boolean;
+/**
+ * The color a choice / boolean column gives a value, for color-by. The caller
+ * supplies the lookup because option colors live on the resolved choice list
+ * (which may come from a structured list), not on the style.
+ */
+type ChoiceColorLookup = (fieldName: string, value: unknown) => StyleColor | undefined;
+/**
+ * The color an option paints with. An option that DECLARED a color uses it; an
+ * option without one gets a stable color from its position in the list, so
+ * "color rows by Status" always paints something — Airtable assigns every
+ * option a color for the same reason. A column whose options were never
+ * colored would otherwise look like color-by did nothing at all.
+ */
+declare function colorForChoice(choices: readonly {
+    value: string;
+    color?: string;
+}[] | undefined, value: unknown): StyleColor | undefined;
+/**
+ * Boolean columns have no option list; color-by paints true green and leaves
+ * false untinted, which is the "done / not done" reading every checklist has.
+ */
+declare const BOOLEAN_TRUE_COLOR: StyleColor;
+/** The tint for a whole row, or null for none. */
+declare function resolveRowColor(style: TableStyle, row: {
+    id: string;
+    data: Record<string, unknown>;
+}, choiceColorFor: ChoiceColorLookup): StyleColor | null;
+/** The tint for one cell (painted over the row tint), or null for none. */
+declare function resolveCellColor(style: TableStyle, row: {
+    id: string;
+    data: Record<string, unknown>;
+}, fieldName: string, choiceColorFor: ChoiceColorLookup): StyleColor | null;
+declare const ROW_TINT_CLASS: Record<StyleColor, string>;
+declare const CELL_TINT_CLASS: Record<StyleColor, string>;
+/** A solid swatch for palette menus. */
+declare const SWATCH_CLASS: Record<StyleColor, string>;
+declare const STYLE_COLOR_LABELS: Record<StyleColor, string>;
+type StylePath = readonly string[];
+declare const stylePath: {
+    colorBy: () => StylePath;
+    rules: () => StylePath;
+    row: (rowId: string) => StylePath;
+    cell: (rowId: string, fieldName: string) => StylePath;
+    column: (fieldName: string) => StylePath;
+};
+/** Apply a path write locally, so the grid repaints before the round trip returns. */
+declare function applyStylePath(style: TableStyle, path: StylePath, value: unknown): TableStyle;
+
 /** How a column's filter UI behaves. `auto` infers from sample values. */
 type ColumnFilterKind = "auto" | "text" | "select" | "boolean" | "number" | false;
 type SortDirection = "asc" | "desc";
@@ -256,6 +405,36 @@ interface MatrxColumnDef<T> {
         /** Force non-navigable for this column. */
         forbidden?: boolean | ((id: string, row: T) => boolean);
     };
+    /**
+     * How this column's value READS — money, percent, a date style, decimal
+     * places. The vocabulary is the platform's one field-format registry
+     * (`@ai-matrx/design-system/field-formats`), the same `{id, options}` a user
+     * data table stores on its column and the record store stores on its Field,
+     * so `$1,234.56` is the same `$1,234.56` on every table in the product.
+     *
+     * A declarative format, not another render function, because a `cell`
+     * callback is invisible to everything else: with `format` the column also
+     * right-aligns itself, and a consumer's own `cell` asks the primitive for the
+     * same text through `formatColumnValue(col, value)` rather than growing a
+     * second money formatter beside this one.
+     *
+     * THE FALLBACK LAW travels with it: a value that does not fit the declared
+     * format is never blanked and never throws — it renders its base-type text in
+     * amber with the reason on hover, so the person SEES the mismatch.
+     *
+     * `cell` still wins when both are set.
+     */
+    format?: FieldFormatConfig;
+    /**
+     * Keep this column in place while the rest of the table scrolls sideways.
+     *
+     * Only the LEADING RUN freezes, only from `sm:` up, and only when the widths
+     * the offsets need are known — `./frozen-columns.ts` says why each of those
+     * three is a rule and not a default. Give a frozen column an explicit
+     * `width`; without one the table declines to freeze anything rather than pin
+     * a column at a guessed offset.
+     */
+    frozen?: boolean;
     className?: string;
     headerClassName?: string;
     width?: string | number;
@@ -397,6 +576,14 @@ interface MatrxTablePagination<T> {
     };
     retrySource?: () => void;
     sourceUntil?: string;
+    /** Source records differ from rendered rows when the host groups occurrences. */
+    sourceRecords?: {
+        loaded: number;
+        total?: number | undefined;
+        label: string;
+        rowLabel: string;
+        matchedRecords?: number;
+    };
     sourcePageSize?: {
         value: number;
         options: readonly number[];
@@ -568,6 +755,17 @@ interface TableViewSnapshot {
         hidden: string[];
         widths?: Record<string, number>;
     };
+    /**
+     * The view's COLORS — color-by-a-column, rules, and manual highlights
+     * (`./table-style.ts`). Optional so every view saved before colors existed
+     * still parses; absent means "this view paints nothing".
+     *
+     * Colors belong to the VIEW and not to the data, for the same reason the
+     * filters do: two people can read one table two ways, and neither reading is
+     * a fact about the records. That is also why this snapshot is the only place
+     * a style is carried — copy, export and agents read the rows, never this.
+     */
+    style?: TableStyle;
 }
 /** Host port for durable named views. The host owns actor, tenancy and CRUD. */
 interface TableSavedViewsProps {
@@ -844,6 +1042,28 @@ interface MatrxDataTableMobileCardControls {
     expandedDetail: ReactNode;
 }
 type MatrxDataTableDensity = "condensed" | "normal" | "spacious";
+/**
+ * What the table needs in order to paint a `TableStyle` itself.
+ *
+ * `fieldOf` exists because a style names DATA fields ("tint the row when
+ * `status` is Blocked") while the table addresses COLUMNS. In the common case
+ * the column id IS the field name and the default is right; a table whose
+ * column ids are decorated (`records-grid-notes`) maps them here.
+ */
+interface MatrxDataTableStyleConfig<T> {
+    /** The style document. */
+    style: TableStyle;
+    /** The row's data as the rules read it. Defaults to the row itself. */
+    documentOf?: (row: T) => Record<string, unknown>;
+    /** Column id to the field name a rule would name. Defaults to identity. */
+    fieldOf?: (columnId: string) => string;
+    /**
+     * The color a choice column's option paints with, for color-by. The consumer
+     * supplies it because option colors live on the resolved option list, which
+     * may come from a shared pick list this package cannot reach.
+     */
+    choiceColorFor?: ChoiceColorLookup;
+}
 interface MatrxDataTableProps<T> {
     data: T[];
     columns: MatrxColumnDef<T>[];
@@ -953,6 +1173,26 @@ interface MatrxDataTableProps<T> {
     footerRows?: T[];
     /** Per-row presentation class, after canonical selection/highlight state. */
     rowClassName?: (row: T, index: number) => string | undefined;
+    /**
+     * Per-CELL presentation class, after the column's own static `className`.
+     *
+     * The primitive had `rowClassName` and a static per-column `className`, and
+     * nothing in between — so every table that needed to say something about ONE
+     * cell had to grow a `cell` render function and paint inside it, where the
+     * table can no longer see it. This is the missing rung, and `tableStyle`
+     * below is the declarative thing built on top of it.
+     */
+    cellClassName?: (row: T, columnId: string, index: number) => string | undefined;
+    /**
+     * COLORS, declaratively — color by a column, rules, manual highlights.
+     *
+     * The model is `./table-style.ts`: one document, evaluated live on every
+     * render so a tint is never stale, with a documented precedence between the
+     * three ways a cell can earn a color. Pass the document and the table paints
+     * itself; the consumer owns only where that document is STORED and how a
+     * person edits it.
+     */
+    tableStyle?: MatrxDataTableStyleConfig<T>;
     /** Highlight an index in the currently rendered page without selecting it. */
     highlightedIndex?: number | undefined;
     /** Receives the complete visible local view after local processing, before paging. Attaching after absence receives one snapshot; callback identity changes alone do not notify. */
@@ -1018,4 +1258,4 @@ interface MatrxDataTableProps<T> {
     onRowOpen?: (row: T) => void;
 }
 
-export { type AnyOfColumnSearch as A, type MatrxDataTableWindowConfig as B, type ColumnFiltersState as C, type MatrxTablePagination as D, type SortDirection as E, type TableViewQuery as F, type TextFilterMode as G, type ToolbarFacet as H, rankTableSearchRows as I, LAYERED_FILTER_OPERATORS as J, LAYERED_FILTER_OPERATOR_LABELS as K, type LayeredFilterRule as L, type MatrxColumnDef as M, type LayeredFilterField as N, type LayeredFilterOperator as O, columnFiltersToLayeredRules as P, completeLayeredFilterRules as Q, decodeLayeredFilterRules as R, type SortState as S, type TableSearchMatchMode as T, encodeLayeredFilterRules as U, isCompleteLayeredFilterRule as V, isLayeredFilterOperator as W, layeredFilterMatchesValue as X, layeredFilterNeedsValue as Y, layeredFilterRuleSummary as Z, operatorsForLayeredField as _, type ColumnFilterValue as a, type TableSavedViewsProps as b, type MatrxDataTableRecordControls as c, type MatrxDataTableDensity as d, type MatrxDataTableQueryState as e, type ColumnFilterKind as f, type MatrxDataTableCopyConfig as g, type MatrxDataTableProps as h, type TableViewSnapshot as i, type ColumnMarker as j, type CellEditType as k, type CellEditsMap as l, type MatrxDataTableContextMenuConfig as m, type MatrxDataTableDetailConfig as n, type MatrxDataTableEditConfig as o, type MatrxDataTableEmptyState as p, type MatrxDataTableExpandedDetailConfig as q, type MatrxDataTableFilterUi as r, type MatrxDataTableHierarchyConfig as s, type MatrxDataTableHierarchyMove as t, type MatrxDataTableMobileCardControls as u, type MatrxDataTableQueryControl as v, type MatrxDataTableSelectionConfig as w, type MatrxDataTableSourceProcessing as x, type MatrxDataTableToolbar as y, type MatrxDataTableUrlStateConfig as z };
+export { TABLE_STYLE_METADATA_KEY as $, type AnyOfColumnSearch as A, BOOLEAN_TRUE_COLOR as B, type ColumnFiltersState as C, type MatrxDataTableHierarchyMove as D, EMPTY_TABLE_STYLE as E, type MatrxDataTableMobileCardControls as F, type MatrxDataTableQueryControl as G, type MatrxDataTableSelectionConfig as H, type MatrxDataTableSourceProcessing as I, type MatrxDataTableStyleConfig as J, type MatrxDataTableToolbar as K, type LayeredFilterRule as L, type MatrxColumnDef as M, type MatrxDataTableUrlStateConfig as N, type MatrxDataTableWindowConfig as O, type MatrxTablePagination as P, OPS_WITH_VALUE as Q, ROW_TINT_CLASS as R, type SortState as S, type TableSearchMatchMode as T, STYLE_COLORS as U, STYLE_COLOR_LABELS as V, SWATCH_CLASS as W, type SortDirection as X, type StyleColor as Y, type StylePath as Z, type StyleTarget as _, type ColumnFilterValue as a, TABLE_STYLE_VERSION as a0, type TableRankedSearchOptions as a1, type TableSearchRole as a2, type TableSearchScope as a3, type TableStyle as a4, type TableViewQuery as a5, type TextFilterMode as a6, type ToolbarFacet as a7, applyStylePath as a8, colorForChoice as a9, evaluateRule as aa, inferTableSearchRole as ab, isStyleColor as ac, parseTableStyle as ad, rankTableSearchRows as ae, resolveCellColor as af, resolveRowColor as ag, resolveTableSearchScopes as ah, stylePath as ai, tableStyleFromMetadata as aj, tableStyleIsEmpty as ak, LAYERED_FILTER_OPERATORS as al, LAYERED_FILTER_OPERATOR_LABELS as am, type LayeredFilterField as an, type LayeredFilterOperator as ao, columnFiltersToLayeredRules as ap, completeLayeredFilterRules as aq, decodeLayeredFilterRules as ar, encodeLayeredFilterRules as as, isCompleteLayeredFilterRule as at, isLayeredFilterOperator as au, layeredFilterMatchesValue as av, layeredFilterNeedsValue as aw, layeredFilterRuleSummary as ax, operatorsForLayeredField as ay, type TableSavedViewsProps as b, type MatrxDataTableRecordControls as c, type MatrxDataTableDensity as d, type MatrxDataTableQueryState as e, type ColumnFilterKind as f, type MatrxDataTableCopyConfig as g, type MatrxDataTableProps as h, type TableViewSnapshot as i, type ColumnMarker as j, CELL_TINT_CLASS as k, COLOR_RULE_OPS as l, COLOR_RULE_OP_LABELS as m, type CellEditType as n, type CellEditsMap as o, type ChoiceColorLookup as p, type ColorBy as q, type ColorRule as r, type ColorRuleOp as s, type MatrxDataTableContextMenuConfig as t, type MatrxDataTableDetailConfig as u, type MatrxDataTableEditConfig as v, type MatrxDataTableEmptyState as w, type MatrxDataTableExpandedDetailConfig as x, type MatrxDataTableFilterUi as y, type MatrxDataTableHierarchyConfig as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/design-system",
-  "version": "0.21.13",
+  "version": "0.22.0",
   "description": "AI Matrx semantic React primitives shared across Vite, Next.js, desktop, and customer-built applications.",
   "type": "module",
   "license": "MIT",
@@ -78,6 +78,16 @@
         "default": "./dist/data-table/index.cjs"
       }
     },
+    "./field-formats": {
+      "import": {
+        "types": "./dist/field-formats/index.d.ts",
+        "default": "./dist/field-formats/index.js"
+      },
+      "require": {
+        "types": "./dist/field-formats/index.d.cts",
+        "default": "./dist/field-formats/index.cjs"
+      }
+    },
     "./data-table/host": {
       "import": {
         "types": "./dist/data-table/host.d.ts",