@ai-matrx/design-system 0.21.14 → 0.22.0

package/dist/data-table/index.d.cts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { ReactNode } from 'react';
-import { h as MatrxDataTableProps, i as TableViewSnapshot, c as MatrxDataTableRecordControls, j as ColumnMarker, M as MatrxColumnDef } from '../types-BgqIKbhq.cjs';
-export { A as AnyOfColumnSearch, k as CellEditType, l as CellEditsMap, f as ColumnFilterKind, a as ColumnFilterValue, C as ColumnFiltersState, m as MatrxDataTableContextMenuConfig, g as MatrxDataTableCopyConfig, d as MatrxDataTableDensity, n as MatrxDataTableDetailConfig, o as MatrxDataTableEditConfig, p as MatrxDataTableEmptyState, q as MatrxDataTableExpandedDetailConfig, r as MatrxDataTableFilterUi, s as MatrxDataTableHierarchyConfig, t as MatrxDataTableHierarchyMove, u as MatrxDataTableMobileCardControls, v as MatrxDataTableQueryControl, e as MatrxDataTableQueryState, w as MatrxDataTableSelectionConfig, x as MatrxDataTableSourceProcessing, y as MatrxDataTableToolbar, z as MatrxDataTableUrlStateConfig, B as MatrxDataTableWindowConfig, D as MatrxTablePagination, E as SortDirection, S as SortState, F as TableRankedSearchOptions, b as TableSavedViewsProps, T as TableSearchMatchMode, G as TableSearchRole, H as TableSearchScope, I as TableViewQuery, J as TextFilterMode, K as ToolbarFacet, N as inferTableSearchRole, O as rankTableSearchRows, P as resolveTableSearchScopes } from '../types-BgqIKbhq.cjs';
+import { h as MatrxDataTableProps, i as TableViewSnapshot, c as MatrxDataTableRecordControls, j as ColumnMarker, M as MatrxColumnDef } from '../types-Sn249eoy.cjs';
+export { A as AnyOfColumnSearch, B as BOOLEAN_TRUE_COLOR, k as CELL_TINT_CLASS, l as COLOR_RULE_OPS, m as COLOR_RULE_OP_LABELS, n as CellEditType, o as CellEditsMap, p as ChoiceColorLookup, q as ColorBy, r as ColorRule, s as ColorRuleOp, f as ColumnFilterKind, a as ColumnFilterValue, C as ColumnFiltersState, E as EMPTY_TABLE_STYLE, t as MatrxDataTableContextMenuConfig, g as MatrxDataTableCopyConfig, d as MatrxDataTableDensity, u as MatrxDataTableDetailConfig, v as MatrxDataTableEditConfig, w as MatrxDataTableEmptyState, x as MatrxDataTableExpandedDetailConfig, y as MatrxDataTableFilterUi, z as MatrxDataTableHierarchyConfig, D as MatrxDataTableHierarchyMove, F as MatrxDataTableMobileCardControls, G as MatrxDataTableQueryControl, e as MatrxDataTableQueryState, H as MatrxDataTableSelectionConfig, I as MatrxDataTableSourceProcessing, J as MatrxDataTableStyleConfig, K as MatrxDataTableToolbar, N as MatrxDataTableUrlStateConfig, O as MatrxDataTableWindowConfig, P as MatrxTablePagination, Q as OPS_WITH_VALUE, R as ROW_TINT_CLASS, U as STYLE_COLORS, V as STYLE_COLOR_LABELS, W as SWATCH_CLASS, X as SortDirection, S as SortState, Y as StyleColor, Z as StylePath, _ as StyleTarget, $ as TABLE_STYLE_METADATA_KEY, a0 as TABLE_STYLE_VERSION, a1 as TableRankedSearchOptions, b as TableSavedViewsProps, T as TableSearchMatchMode, a2 as TableSearchRole, a3 as TableSearchScope, a4 as TableStyle, a5 as TableViewQuery, a6 as TextFilterMode, a7 as ToolbarFacet, a8 as applyStylePath, a9 as colorForChoice, aa as evaluateRule, ab as inferTableSearchRole, ac as isStyleColor, ad as parseTableStyle, ae as rankTableSearchRows, af as resolveCellColor, ag as resolveRowColor, ah as resolveTableSearchScopes, ai as stylePath, aj as tableStyleFromMetadata, ak as tableStyleIsEmpty } from '../types-Sn249eoy.cjs';
 export { MatrxDataTableHost, MatrxDataTableProvider, MatrxTableRowAlchemy, TableDoors, TableEntityRefProps, TableLinkProps, TablePeekProps, TableSidePanelProps, TableToolbarActionProps, TableWindowPanelProps, useMatrxDataTableHost, useMatrxTableRowAlchemy } from './host.cjs';
 import { CopyControlProps } from './copy-types.cjs';
 export { AgentPayloadInput } from './copy-types.cjs';
@@ -14,6 +14,7 @@ export { downloadTableAsXlsx } from './xlsx.cjs';
 export { ResolvedFilterKind, collectSelectOptions, filterKindLabel, resolveFilterKind } from './infer-filter.cjs';
 export { ScrollPaginationContainer, UseScrollPaginationOptions, UseScrollPaginationResult, useScrollPagination } from './scroll-pagination.cjs';
 export { tableUrlParamPrefix, useTableUrlState } from './url-state.cjs';
+import { c as FormatResult } from '../types-BdbvlF9-.cjs';
 import '../content-transfer.cjs';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.cjs';
@@ -103,4 +104,91 @@ interface TableViewTabsProps {
 /** One shared tab strip; hosts may own URL state without copying its UI. */
 declare function TableViewTabs({ tabs, activeId, onSelect, onAdd, onClose, onRename, related }: TableViewTabsProps): React.JSX.Element;
 
-export { ColumnMarker, MatrxColumnDef, MatrxDataTable, MatrxDataTableProps, MatrxDataTableRecordControls, MatrxTableRowAlchemyProvider, type ResolvedColumnMarker, SavedViewsControl, type SavedViewsControlProps, TableTitleRow, type TableTitleRowProps, TableViewSnapshot, type TableViewTab, TableViewTabs, type TableViewTabsProps, parseTableViewSnapshot, resolveColumnMarker };
+/**
+ * `MatrxColumnDef.format` — the column's declared reading, rendered.
+ *
+ * ONE FORMATTER, NOT A SECOND ONE. The vocabulary is the platform registry in
+ * `../field-formats`; this file only decides what a TABLE CELL does with the
+ * registry's answer. A consumer with its own `cell` renderer calls
+ * `formatColumnValue(col, value)` and gets exactly the same text the table
+ * would have drawn, so an editable grid and a read-only grid never disagree
+ * about what `1234.5` means.
+ *
+ * THE FALLBACK LAW, on screen. `formatFieldValue` never throws and never
+ * blanks: when the stored value does not fit the declared format it returns
+ * `ok: false` with the BASE-TYPE rendering and a reason. The cell then prints
+ * that base rendering in amber with the reason on hover — the person SEES that
+ * something does not fit, instead of an empty cell that says nothing, and the
+ * value they typed is still legible and still theirs.
+ */
+
+/**
+ * The text a declared format gives this value, plus whether it fit.
+ * Returns `null` when the column declares no format — the caller keeps its own
+ * default rendering rather than being handed an empty string that looks real.
+ */
+declare function formatColumnValue<T>(col: Pick<MatrxColumnDef<T>, "format">, value: unknown): FormatResult | null;
+/**
+ * Which way a formatted column reads. Numbers and dates are right-aligned
+ * because a column of money a person has to compare is unreadable ragged-right
+ * — the alignment is part of the format, not a second decision the caller has
+ * to remember to make. An explicit `align` on the column always wins.
+ */
+declare function alignForFormat<T>(col: Pick<MatrxColumnDef<T>, "format" | "align">): "left" | "center" | "right" | undefined;
+/** The amber a value that does not fit its declared format wears. ONE amber. */
+declare const FORMAT_MISMATCH_CLASS = "text-amber-600 underline decoration-dotted underline-offset-2 dark:text-amber-400";
+declare function FormattedCell({ result }: {
+    result: FormatResult;
+}): ReactNode;
+
+/**
+ * Frozen (pinned) columns — the identity column that stays while the rest of a
+ * wide table scrolls sideways.
+ *
+ * 🚨 DESKTOP ONLY, AND THAT IS A RULE, NOT A DEFAULT. A phone table is already a
+ * horizontal scroller and pinning over it buries the data behind the pin; the
+ * package regression-tests that no `max-sm:sticky` is ever emitted
+ * (`MatrxDataTable.controlled.test.tsx`, "never freezes a column over mobile
+ * table data"). Freezing is therefore expressed as `sm:sticky` and the phone
+ * answer stays `MatrxColumnDef.mobileHidden`.
+ *
+ * ONLY THE LEADING RUN. `frozen` on a column in the middle of the table would
+ * have to slide over its own left neighbour, which is a lie about where the row
+ * is. So the frozen set is the run of `frozen: true` columns starting at the
+ * first visible column; a `frozen` column with a non-frozen column before it is
+ * ignored, deliberately and silently — the person asked for something the shape
+ * of a table cannot honour.
+ *
+ * A HALF-STUCK COLUMN IS A LYING SCREEN. Each frozen column sits at a left
+ * offset that is the sum of everything frozen to its left, so those widths must
+ * be KNOWN numbers. The last frozen column's own width is never needed (nothing
+ * is offset past it). If any width this arithmetic needs is missing, freezing is
+ * OFF for the whole table and every column renders in its ordinary place —
+ * never a column pinned at a guessed offset, drifting over its neighbour.
+ */
+type FrozenColumns = {
+    /** Left offset in px for each column id that is actually frozen. */
+    readonly offsets: Readonly<Record<string, number>>;
+    /** True when at least one column is frozen. */
+    readonly active: boolean;
+    /**
+     * Left offset for the leading selection column, present only when freezing is
+     * active AND the table draws that column — it has to stick too, or the first
+     * frozen data column slides over the checkboxes.
+     */
+    readonly selectionOffset: number | null;
+};
+declare const NO_FROZEN_COLUMNS: FrozenColumns;
+/**
+ * @param ids           visible column ids, in render order
+ * @param isFrozen      did this column ask to be frozen
+ * @param widthOf       resolved pixel width, or undefined when unknown
+ * @param leadingWidth  width of the selection column when the table draws one,
+ *                      `null` when it draws none. `undefined` means "it draws
+ *                      one and nobody has measured it yet" — freezing waits.
+ */
+declare function resolveFrozenColumns(ids: readonly string[], isFrozen: (id: string) => boolean, widthOf: (id: string) => number | undefined, leadingWidth: number | null | undefined): FrozenColumns;
+/** The numeric pixel width of a declared column width, when there is one. */
+declare function pixelWidth(width: string | number | undefined): number | undefined;
+
+export { ColumnMarker, FORMAT_MISMATCH_CLASS, FormattedCell, type FrozenColumns, MatrxColumnDef, MatrxDataTable, MatrxDataTableProps, MatrxDataTableRecordControls, MatrxTableRowAlchemyProvider, NO_FROZEN_COLUMNS, type ResolvedColumnMarker, SavedViewsControl, type SavedViewsControlProps, TableTitleRow, type TableTitleRowProps, TableViewSnapshot, type TableViewTab, TableViewTabs, type TableViewTabsProps, alignForFormat, formatColumnValue, parseTableViewSnapshot, pixelWidth, resolveColumnMarker, resolveFrozenColumns };

package/dist/data-table/index.d.ts

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { ReactNode } from 'react';
-import { h as MatrxDataTableProps, i as TableViewSnapshot, c as MatrxDataTableRecordControls, j as ColumnMarker, M as MatrxColumnDef } from '../types-emLxze_m.js';
-export { A as AnyOfColumnSearch, k as CellEditType, l as CellEditsMap, f as ColumnFilterKind, a as ColumnFilterValue, C as ColumnFiltersState, m as MatrxDataTableContextMenuConfig, g as MatrxDataTableCopyConfig, d as MatrxDataTableDensity, n as MatrxDataTableDetailConfig, o as MatrxDataTableEditConfig, p as MatrxDataTableEmptyState, q as MatrxDataTableExpandedDetailConfig, r as MatrxDataTableFilterUi, s as MatrxDataTableHierarchyConfig, t as MatrxDataTableHierarchyMove, u as MatrxDataTableMobileCardControls, v as MatrxDataTableQueryControl, e as MatrxDataTableQueryState, w as MatrxDataTableSelectionConfig, x as MatrxDataTableSourceProcessing, y as MatrxDataTableToolbar, z as MatrxDataTableUrlStateConfig, B as MatrxDataTableWindowConfig, D as MatrxTablePagination, E as SortDirection, S as SortState, F as TableRankedSearchOptions, b as TableSavedViewsProps, T as TableSearchMatchMode, G as TableSearchRole, H as TableSearchScope, I as TableViewQuery, J as TextFilterMode, K as ToolbarFacet, N as inferTableSearchRole, O as rankTableSearchRows, P as resolveTableSearchScopes } from '../types-emLxze_m.js';
+import { h as MatrxDataTableProps, i as TableViewSnapshot, c as MatrxDataTableRecordControls, j as ColumnMarker, M as MatrxColumnDef } from '../types-D-flTpK0.js';
+export { A as AnyOfColumnSearch, B as BOOLEAN_TRUE_COLOR, k as CELL_TINT_CLASS, l as COLOR_RULE_OPS, m as COLOR_RULE_OP_LABELS, n as CellEditType, o as CellEditsMap, p as ChoiceColorLookup, q as ColorBy, r as ColorRule, s as ColorRuleOp, f as ColumnFilterKind, a as ColumnFilterValue, C as ColumnFiltersState, E as EMPTY_TABLE_STYLE, t as MatrxDataTableContextMenuConfig, g as MatrxDataTableCopyConfig, d as MatrxDataTableDensity, u as MatrxDataTableDetailConfig, v as MatrxDataTableEditConfig, w as MatrxDataTableEmptyState, x as MatrxDataTableExpandedDetailConfig, y as MatrxDataTableFilterUi, z as MatrxDataTableHierarchyConfig, D as MatrxDataTableHierarchyMove, F as MatrxDataTableMobileCardControls, G as MatrxDataTableQueryControl, e as MatrxDataTableQueryState, H as MatrxDataTableSelectionConfig, I as MatrxDataTableSourceProcessing, J as MatrxDataTableStyleConfig, K as MatrxDataTableToolbar, N as MatrxDataTableUrlStateConfig, O as MatrxDataTableWindowConfig, P as MatrxTablePagination, Q as OPS_WITH_VALUE, R as ROW_TINT_CLASS, U as STYLE_COLORS, V as STYLE_COLOR_LABELS, W as SWATCH_CLASS, X as SortDirection, S as SortState, Y as StyleColor, Z as StylePath, _ as StyleTarget, $ as TABLE_STYLE_METADATA_KEY, a0 as TABLE_STYLE_VERSION, a1 as TableRankedSearchOptions, b as TableSavedViewsProps, T as TableSearchMatchMode, a2 as TableSearchRole, a3 as TableSearchScope, a4 as TableStyle, a5 as TableViewQuery, a6 as TextFilterMode, a7 as ToolbarFacet, a8 as applyStylePath, a9 as colorForChoice, aa as evaluateRule, ab as inferTableSearchRole, ac as isStyleColor, ad as parseTableStyle, ae as rankTableSearchRows, af as resolveCellColor, ag as resolveRowColor, ah as resolveTableSearchScopes, ai as stylePath, aj as tableStyleFromMetadata, ak as tableStyleIsEmpty } from '../types-D-flTpK0.js';
 export { MatrxDataTableHost, MatrxDataTableProvider, MatrxTableRowAlchemy, TableDoors, TableEntityRefProps, TableLinkProps, TablePeekProps, TableSidePanelProps, TableToolbarActionProps, TableWindowPanelProps, useMatrxDataTableHost, useMatrxTableRowAlchemy } from './host.js';
 import { CopyControlProps } from './copy-types.js';
 export { AgentPayloadInput } from './copy-types.js';
@@ -14,6 +14,7 @@ export { downloadTableAsXlsx } from './xlsx.js';
 export { ResolvedFilterKind, collectSelectOptions, filterKindLabel, resolveFilterKind } from './infer-filter.js';
 export { ScrollPaginationContainer, UseScrollPaginationOptions, UseScrollPaginationResult, useScrollPagination } from './scroll-pagination.js';
 export { tableUrlParamPrefix, useTableUrlState } from './url-state.js';
+import { c as FormatResult } from '../types-BdbvlF9-.js';
 import '../content-transfer.js';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.js';
@@ -103,4 +104,91 @@ interface TableViewTabsProps {
 /** One shared tab strip; hosts may own URL state without copying its UI. */
 declare function TableViewTabs({ tabs, activeId, onSelect, onAdd, onClose, onRename, related }: TableViewTabsProps): React.JSX.Element;
 
-export { ColumnMarker, MatrxColumnDef, MatrxDataTable, MatrxDataTableProps, MatrxDataTableRecordControls, MatrxTableRowAlchemyProvider, type ResolvedColumnMarker, SavedViewsControl, type SavedViewsControlProps, TableTitleRow, type TableTitleRowProps, TableViewSnapshot, type TableViewTab, TableViewTabs, type TableViewTabsProps, parseTableViewSnapshot, resolveColumnMarker };
+/**
+ * `MatrxColumnDef.format` — the column's declared reading, rendered.
+ *
+ * ONE FORMATTER, NOT A SECOND ONE. The vocabulary is the platform registry in
+ * `../field-formats`; this file only decides what a TABLE CELL does with the
+ * registry's answer. A consumer with its own `cell` renderer calls
+ * `formatColumnValue(col, value)` and gets exactly the same text the table
+ * would have drawn, so an editable grid and a read-only grid never disagree
+ * about what `1234.5` means.
+ *
+ * THE FALLBACK LAW, on screen. `formatFieldValue` never throws and never
+ * blanks: when the stored value does not fit the declared format it returns
+ * `ok: false` with the BASE-TYPE rendering and a reason. The cell then prints
+ * that base rendering in amber with the reason on hover — the person SEES that
+ * something does not fit, instead of an empty cell that says nothing, and the
+ * value they typed is still legible and still theirs.
+ */
+
+/**
+ * The text a declared format gives this value, plus whether it fit.
+ * Returns `null` when the column declares no format — the caller keeps its own
+ * default rendering rather than being handed an empty string that looks real.
+ */
+declare function formatColumnValue<T>(col: Pick<MatrxColumnDef<T>, "format">, value: unknown): FormatResult | null;
+/**
+ * Which way a formatted column reads. Numbers and dates are right-aligned
+ * because a column of money a person has to compare is unreadable ragged-right
+ * — the alignment is part of the format, not a second decision the caller has
+ * to remember to make. An explicit `align` on the column always wins.
+ */
+declare function alignForFormat<T>(col: Pick<MatrxColumnDef<T>, "format" | "align">): "left" | "center" | "right" | undefined;
+/** The amber a value that does not fit its declared format wears. ONE amber. */
+declare const FORMAT_MISMATCH_CLASS = "text-amber-600 underline decoration-dotted underline-offset-2 dark:text-amber-400";
+declare function FormattedCell({ result }: {
+    result: FormatResult;
+}): ReactNode;
+
+/**
+ * Frozen (pinned) columns — the identity column that stays while the rest of a
+ * wide table scrolls sideways.
+ *
+ * 🚨 DESKTOP ONLY, AND THAT IS A RULE, NOT A DEFAULT. A phone table is already a
+ * horizontal scroller and pinning over it buries the data behind the pin; the
+ * package regression-tests that no `max-sm:sticky` is ever emitted
+ * (`MatrxDataTable.controlled.test.tsx`, "never freezes a column over mobile
+ * table data"). Freezing is therefore expressed as `sm:sticky` and the phone
+ * answer stays `MatrxColumnDef.mobileHidden`.
+ *
+ * ONLY THE LEADING RUN. `frozen` on a column in the middle of the table would
+ * have to slide over its own left neighbour, which is a lie about where the row
+ * is. So the frozen set is the run of `frozen: true` columns starting at the
+ * first visible column; a `frozen` column with a non-frozen column before it is
+ * ignored, deliberately and silently — the person asked for something the shape
+ * of a table cannot honour.
+ *
+ * A HALF-STUCK COLUMN IS A LYING SCREEN. Each frozen column sits at a left
+ * offset that is the sum of everything frozen to its left, so those widths must
+ * be KNOWN numbers. The last frozen column's own width is never needed (nothing
+ * is offset past it). If any width this arithmetic needs is missing, freezing is
+ * OFF for the whole table and every column renders in its ordinary place —
+ * never a column pinned at a guessed offset, drifting over its neighbour.
+ */
+type FrozenColumns = {
+    /** Left offset in px for each column id that is actually frozen. */
+    readonly offsets: Readonly<Record<string, number>>;
+    /** True when at least one column is frozen. */
+    readonly active: boolean;
+    /**
+     * Left offset for the leading selection column, present only when freezing is
+     * active AND the table draws that column — it has to stick too, or the first
+     * frozen data column slides over the checkboxes.
+     */
+    readonly selectionOffset: number | null;
+};
+declare const NO_FROZEN_COLUMNS: FrozenColumns;
+/**
+ * @param ids           visible column ids, in render order
+ * @param isFrozen      did this column ask to be frozen
+ * @param widthOf       resolved pixel width, or undefined when unknown
+ * @param leadingWidth  width of the selection column when the table draws one,
+ *                      `null` when it draws none. `undefined` means "it draws
+ *                      one and nobody has measured it yet" — freezing waits.
+ */
+declare function resolveFrozenColumns(ids: readonly string[], isFrozen: (id: string) => boolean, widthOf: (id: string) => number | undefined, leadingWidth: number | null | undefined): FrozenColumns;
+/** The numeric pixel width of a declared column width, when there is one. */
+declare function pixelWidth(width: string | number | undefined): number | undefined;
+
+export { ColumnMarker, FORMAT_MISMATCH_CLASS, FormattedCell, type FrozenColumns, MatrxColumnDef, MatrxDataTable, MatrxDataTableProps, MatrxDataTableRecordControls, MatrxTableRowAlchemyProvider, NO_FROZEN_COLUMNS, type ResolvedColumnMarker, SavedViewsControl, type SavedViewsControlProps, TableTitleRow, type TableTitleRowProps, TableViewSnapshot, type TableViewTab, TableViewTabs, type TableViewTabsProps, alignForFormat, formatColumnValue, parseTableViewSnapshot, pixelWidth, resolveColumnMarker, resolveFrozenColumns };