@ai-matrx/design-system 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.41.0 (2026-09-25)
+
+### Lane MERGE-STEP-2 (data-tables-grid-overhaul, 2026-09-25)
+
+The app's `/data` grid kept forks of `field-formats` and `formulas` after they moved here, and
+the forks grew. Their newer behaviour moves into the package so the app can delete its copies.
+
+* **`@ai-matrx/design-system/field-formats` gains nine formats** the app had added since the move:
+  `address` (opens in maps), `progress` (a percentage drawn as a bar), `time` (time of day, with
+  `options.timeSeconds`), `autonumber` (database-assigned, `prefix`), the system columns
+  `created_time` / `modified_time`, `attachment` (file ids from Files; `base: "array"`, also
+  accepts `json` but NOT `string`, so on a text column it is offered under "Other kinds" and
+  retypes the column instead of storing JSON in a text cell), `person` (an organization member,
+  choice-shaped) and `relation` (a record of another table: `relation_target`, `relation_max`,
+  `on_delete`, `display`; a value that did not resolve to words is a mismatch, never a bare id).
+  `FieldEditorKind` gains `"time"` and `"attachment"`; `FieldFormatId` and `FieldFormatOptions`
+  grow to match. Additive.
+* **`@ai-matrx/design-system/formulas` gains the computed-column helpers:** `systemColumnKindOf`,
+  `SystemColumnKind`, `isAutonumberColumn`, `isComputedColumn` (THE check every write path uses to
+  refuse a computed cell). `withComputedColumns` fills `created_time` / `modified_time` columns from
+  the row's own `created_at` / `updated_at`, counts system and autonumber columns in
+  `formulaFieldNames`, and takes an optional third argument `displayValueOf(fieldName, raw)` so a
+  formula sees a relation cell's words rather than its id. Omitted, behaviour is unchanged.
+* Tests moved with the behaviour: `field-formats/{format,address-progress-format,attachment-format,
+  time-format,identifier-formats}.test.ts`, `formulas/computed-columns.test.ts`.
+
+**Consumer action:** matrx-frontend deletes its `lib/field-formats/{registry,types,format}.ts` and
+`features/data-tables/{formulas,grid-selection,grid-clipboard}.ts` forks and imports these subpaths.
+Other consumers: none.
+
 ## 0.40.0 (2026-09-25 — version and notes set by PUBLISHER-5)
 
 ### Lane TABLE-PAGE-CHROME (2026-09-25)

package/dist/data-table/copy-helpers.d.cts

@@ -1,11 +1,11 @@
 import { AgentPayloadInput } from './copy-types.cjs';
-import { g as MatrxDataTableCopyConfig, M as MatrxColumnDef } from '../types-oVyZbfwn.cjs';
+import { g as MatrxDataTableCopyConfig, M as MatrxColumnDef } from '../types-DNkbHRVK.cjs';
 import '../content-transfer.cjs';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.cjs';
 import './table-style.cjs';
-import '../types-CJWU1Gae.cjs';
+import '../types-JnZD8wM0.cjs';
 import './grouping.cjs';
 import './fill.cjs';
 import './facets.cjs';

package/dist/data-table/copy-helpers.d.ts

@@ -1,11 +1,11 @@
 import { AgentPayloadInput } from './copy-types.js';
-import { g as MatrxDataTableCopyConfig, M as MatrxColumnDef } from '../types-Z32pxexx.js';
+import { g as MatrxDataTableCopyConfig, M as MatrxColumnDef } from '../types-Dx5hJgCi.js';
 import '../content-transfer.js';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.js';
 import './table-style.js';
-import '../types-CJWU1Gae.js';
+import '../types-JnZD8wM0.js';
 import './grouping.js';
 import './fill.js';
 import './facets.js';

package/dist/data-table/filter-engine.d.cts

@@ -1,11 +1,11 @@
-import { M as MatrxColumnDef, C as ColumnFiltersState, S as SortState, L as LayeredFilterRule, T as TableSearchMatchMode, a as ColumnFilterValue } from '../types-oVyZbfwn.cjs';
+import { M as MatrxColumnDef, C as ColumnFiltersState, S as SortState, L as LayeredFilterRule, T as TableSearchMatchMode, a as ColumnFilterValue } from '../types-DNkbHRVK.cjs';
 import '../content-transfer.cjs';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.cjs';
 import './copy-types.cjs';
 import './table-style.cjs';
-import '../types-CJWU1Gae.cjs';
+import '../types-JnZD8wM0.cjs';
 import './grouping.cjs';
 import './fill.cjs';
 import './facets.cjs';

package/dist/data-table/filter-engine.d.ts

@@ -1,11 +1,11 @@
-import { M as MatrxColumnDef, C as ColumnFiltersState, S as SortState, L as LayeredFilterRule, T as TableSearchMatchMode, a as ColumnFilterValue } from '../types-Z32pxexx.js';
+import { M as MatrxColumnDef, C as ColumnFiltersState, S as SortState, L as LayeredFilterRule, T as TableSearchMatchMode, a as ColumnFilterValue } from '../types-Dx5hJgCi.js';
 import '../content-transfer.js';
 import 'react';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.js';
 import './copy-types.js';
 import './table-style.js';
-import '../types-CJWU1Gae.js';
+import '../types-JnZD8wM0.js';
 import './grouping.js';
 import './fill.js';
 import './facets.js';

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

@@ -2,13 +2,13 @@ import * as React from 'react';
 import { ComponentType, ReactNode, MouseEventHandler } from 'react';
 import { CopyControlProps } from './copy-types.cjs';
 export { AgentPayloadInput, AiCustomSource, AiVariant, CopyExportConfig } from './copy-types.cjs';
-import { b as TableSavedViewsProps, c as MatrxDataTableDensity, d as MatrxDataTableRecordControls } from '../types-oVyZbfwn.cjs';
+import { b as TableSavedViewsProps, c as MatrxDataTableDensity, d as MatrxDataTableRecordControls } from '../types-DNkbHRVK.cjs';
 import { MatrxTableMenuTarget, MatrxTableMenuPayload } from './menu-targets.cjs';
 import '../content-transfer.cjs';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.cjs';
 import './table-style.cjs';
-import '../types-CJWU1Gae.cjs';
+import '../types-JnZD8wM0.cjs';
 import './grouping.cjs';
 import './fill.cjs';
 import './facets.cjs';

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

@@ -2,13 +2,13 @@ import * as React from 'react';
 import { ComponentType, ReactNode, MouseEventHandler } from 'react';
 import { CopyControlProps } from './copy-types.js';
 export { AgentPayloadInput, AiCustomSource, AiVariant, CopyExportConfig } from './copy-types.js';
-import { b as TableSavedViewsProps, c as MatrxDataTableDensity, d as MatrxDataTableRecordControls } from '../types-Z32pxexx.js';
+import { b as TableSavedViewsProps, c as MatrxDataTableDensity, d as MatrxDataTableRecordControls } from '../types-Dx5hJgCi.js';
 import { MatrxTableMenuTarget, MatrxTableMenuPayload } from './menu-targets.js';
 import '../content-transfer.js';
 import '@ai-matrx/kit/content-transfer';
 import '../content-transfer/icon.js';
 import './table-style.js';
-import '../types-CJWU1Gae.js';
+import '../types-JnZD8wM0.js';
 import './grouping.js';
 import './fill.js';
 import './facets.js';

package/dist/data-table/index.cjs

@@ -10253,6 +10253,35 @@ function toText(value) {
     return String(value);
   return null;
 }
+function parseTimeOfDay(value) {
+  if (value instanceof Date) {
+    return { h: value.getHours(), m: value.getMinutes(), s: value.getSeconds() };
+  }
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  if (!text) return null;
+  const m = /^(\d{1,2})(?::(\d{2}))?(?::(\d{2}))?\s*([aApP]\.?[mM]\.?)?$/.exec(text);
+  if (m) {
+    let h = Number(m[1]);
+    const min = m[2] ? Number(m[2]) : 0;
+    const sec = m[3] ? Number(m[3]) : 0;
+    const ampm = m[4]?.toLowerCase().replace(/\./g, "");
+    if (ampm) {
+      if (h < 1 || h > 12) return null;
+      if (ampm === "pm" && h !== 12) h += 12;
+      if (ampm === "am" && h === 12) h = 0;
+    }
+    if (h > 23 || min > 59 || sec > 59) return null;
+    return { h, m: min, s: sec };
+  }
+  if (/\d{4}-\d{2}-\d{2}T/.test(text)) {
+    const d = new Date(text);
+    if (!Number.isNaN(d.getTime())) {
+      return { h: d.getHours(), m: d.getMinutes(), s: d.getSeconds() };
+    }
+  }
+  return null;
+}
 var BARE_CALENDAR_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ]00:00(?::00(?:\.0+)?)?)?$/;
 function toDate(value) {
   if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
@@ -10373,6 +10402,23 @@ var DEFS = [
     },
     parse: (raw) => raw === "" || raw == null ? null : String(raw).trim()
   },
+  {
+    // A postal address. Free text by design (addresses have no one shape
+    // worldwide); the cell opens it in maps, which is the thing people do
+    // with an address in a table.
+    id: "address",
+    label: "Address",
+    description: "Street address \u2014 click to open in maps",
+    group: "Text",
+    base: "string",
+    editor: "text",
+    rich: true,
+    format: (v) => {
+      const t = toText(v)?.trim();
+      return t ? t : null;
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw)
+  },
   {
     id: "url",
     label: "Link",
@@ -10506,6 +10552,26 @@ var DEFS = [
     },
     parse: (raw) => toNumber(raw)
   },
+  {
+    // A percentage DRAWN as a bar — task completion, quota used, a score out of
+    // 100. Same storage and scale rule as `percent`; only the rendering differs.
+    id: "progress",
+    label: "Progress bar",
+    description: "A percentage shown as a bar",
+    group: "Numbers",
+    base: "number",
+    alsoAccepts: ["integer"],
+    editor: "number",
+    rich: true,
+    optionKeys: ["percentScale"],
+    format: (v, o) => {
+      const n2 = toNumber(v);
+      if (n2 === null) return null;
+      const shown = o.percentScale === "fraction" ? n2 * 100 : n2;
+      return `${groupedNumber(shown, { precision: 0 })}%`;
+    },
+    parse: (raw) => toNumber(raw)
+  },
   {
     id: "duration",
     label: "Duration",
@@ -10574,13 +10640,16 @@ var DEFS = [
     alsoAccepts: ["number"],
     editor: "number",
     numericAlign: true,
+    // The name says BYTES on purpose: this cell holds a genuine byte length,
+    // never a character or item count, and `formatFileSize` is only honest
+    // about a quantity that is actually bytes.
     format: (v) => {
-      const n2 = toNumber(v);
-      return n2 === null ? null : (0, import_format3.formatFileSize)(n2);
+      const byteLength = toNumber(v);
+      return byteLength === null ? null : (0, import_format3.formatFileSize)(byteLength);
     },
     parse: (raw) => {
-      const n2 = toNumber(raw);
-      return n2 === null ? null : Math.trunc(n2);
+      const byteLength = toNumber(raw);
+      return byteLength === null ? null : Math.trunc(byteLength);
     }
   },
   // ── Choice ────────────────────────────────────────────────────────────────
@@ -10641,6 +10710,87 @@ var DEFS = [
     },
     parse: (raw) => raw === "" || raw == null ? null : String(raw)
   },
+  {
+    // A TIME OF DAY with no date: opening hours, a shift start, a meeting slot.
+    // Stored as the string the <input type="time"> gives ("HH:MM" or
+    // "HH:MM:SS"), shown in the viewer's locale ("2:30 PM" / "14:30"). The
+    // storage type stays `string`; sorting is lexical on the 24-hour form,
+    // which is chronological — the one reason the stored form is 24-hour.
+    id: "time",
+    label: "Time",
+    description: "Time of day, without a date",
+    group: "Dates",
+    base: "string",
+    editor: "time",
+    optionKeys: ["timeSeconds"],
+    format: (v, o) => {
+      const parts = parseTimeOfDay(v);
+      if (!parts) return null;
+      const d = new Date(2e3, 0, 1, parts.h, parts.m, parts.s);
+      return d.toLocaleTimeString(void 0, {
+        hour: "numeric",
+        minute: "2-digit",
+        ...o.timeSeconds ? { second: "2-digit" } : {}
+      });
+    },
+    // Normalise to the 24-hour "HH:MM[:SS]" form; a value that is not a time
+    // is handed back unchanged so the validation layer can refuse it by name.
+    parse: (raw) => {
+      if (raw == null || raw === "") return null;
+      const parts = parseTimeOfDay(raw);
+      if (!parts) return raw;
+      const two = (n2) => String(n2).padStart(2, "0");
+      const fields = parts.s > 0 ? [parts.h, parts.m, parts.s] : [parts.h, parts.m];
+      return fields.map(two).join(":");
+    }
+  },
+  {
+    // Assigned BY THE DATABASE when the row is inserted (trigger
+    // `_udt_autonumber`), so it is the same number whichever door made the row
+    // and never shifts when another row is deleted. Stored in the cell as an
+    // integer; every editor refuses it. `prefix` turns 42 into "INV-42".
+    id: "autonumber",
+    label: "Autonumber",
+    description: "A number the table assigns to each new row \u2014 never typed",
+    group: "Numbers",
+    base: "integer",
+    alsoAccepts: ["number"],
+    editor: "computed",
+    numericAlign: true,
+    optionKeys: ["prefix"],
+    format: (v, o) => {
+      const n2 = toNumber(v);
+      if (n2 === null) return null;
+      return `${o.prefix ?? ""}${Math.trunc(n2)}`;
+    },
+    parse: () => null
+  },
+  // ── System columns ────────────────────────────────────────────────────────
+  // Filled from the ROW'S OWN RECORD on read (`withComputedColumns` in
+  // `@ai-matrx/design-system/formulas`), never typed and never stored in the
+  // cell. `editor: "computed"` makes every editor refuse them.
+  {
+    id: "created_time",
+    label: "Created time",
+    description: "When the row was added \u2014 filled in automatically",
+    group: "Dates",
+    base: "string",
+    editor: "computed",
+    optionKeys: ["dateStyle"],
+    format: (v, o) => FIELD_FORMATS.datetime.format(v, o),
+    parse: () => null
+  },
+  {
+    id: "modified_time",
+    label: "Last modified time",
+    description: "When the row last changed \u2014 filled in automatically",
+    group: "Dates",
+    base: "string",
+    editor: "computed",
+    optionKeys: ["dateStyle"],
+    format: (v, o) => FIELD_FORMATS.datetime.format(v, o),
+    parse: () => null
+  },
   {
     id: "relative_time",
     label: "Relative time",
@@ -10697,6 +10847,44 @@ var DEFS = [
       return toList(raw) ?? raw;
     }
   },
+  {
+    // FILES ATTACHED TO THE ROW. The cell stores the files feature's file ids
+    // (`files.files.id`), never a URL or a name: a rename or a move in Files
+    // changes nothing here, and access is the file's own (RLS) — a reader who
+    // may see the row but not the file gets the chip's honest "no access", not
+    // a broken link. Drawn by `AttachmentChips`, edited by `AttachmentInput`
+    // through the ONE file picker.
+    id: "attachment",
+    label: "Attachments",
+    description: "Files from your Files, shown as chips",
+    group: "Structured",
+    base: "array",
+    // Not `string`: on a text column it must appear under "Other kinds" so
+    // picking it retypes the column to a list, rather than storing a JSON
+    // string of ids in a text cell.
+    alsoAccepts: ["json"],
+    editor: "attachment",
+    rich: true,
+    format: (v) => {
+      const list = toList(v);
+      if (list === null) return null;
+      const n2 = list.filter((i) => String(i).trim()).length;
+      return n2 === 0 ? "" : n2 === 1 ? "1 file" : `${n2} files`;
+    },
+    parse: (raw) => {
+      if (raw == null || raw === "") return null;
+      if (Array.isArray(raw)) return raw.map((i) => String(i).trim()).filter(Boolean);
+      const text = String(raw).trim();
+      if (text.startsWith("[")) {
+        try {
+          const parsed = JSON.parse(text);
+          if (Array.isArray(parsed)) return parsed.map((i) => String(i).trim()).filter(Boolean);
+        } catch {
+        }
+      }
+      return text.split(",").map((s) => s.trim()).filter(Boolean);
+    }
+  },
   {
     id: "tags",
     label: "Tags",
@@ -10760,6 +10948,82 @@ var DEFS = [
       return trimmed === "" ? null : trimmed;
     }
   },
+  {
+    // A PERSON: one member of the organization the table belongs to, stored as
+    // the user id. It is a choice column whose options are the members —
+    // supplied at runtime by whoever renders it (features/data-tables/
+    // person-choices.tsx), the same door a structured-list-bound column uses —
+    // so the cell picker, the chip, filters, color-by and the agent scope are
+    // all the choice system's, with no second implementation.
+    id: "person",
+    label: "Person",
+    description: "Someone in your organization \u2014 pick from its members",
+    group: "Choice",
+    base: "string",
+    editor: "select",
+    rich: true,
+    format: (v, o) => FIELD_FORMATS.choice.format(v, o),
+    parse: (raw) => FIELD_FORMATS.choice.parse(raw, {})
+  },
+  {
+    // A RECORD OF ANOTHER TABLE. The cell stores that record's ID; the screen
+    // shows its WORDS. `person` is the precedent and the template — it has
+    // stored a user id and displayed a name through `choiceMap` since
+    // 2026-09-21 — so `relation` is a member of CHOICE_FORMAT_IDS and every
+    // one of the ten readers that print a cell resolves it through the path
+    // they already use for `person`. There is no eleventh place to remember.
+    //
+    // THREE STATES, THREE RENDERINGS, NO FOURTH (OLD-TABLES-CUTOVER §3.3):
+    //   resolved      the target's words
+    //   unresolvable  the amber fallback WITH the id, as an identifier — never
+    //                 a blank, and never the bare uuid as if it were text, so a
+    //                 person can act on it and support can trace it
+    //   withheld      platform.relation_withheld_label(), with NO id — a cell
+    //                 the reader may not see never leaks the identifier through
+    //                 the gap between the two stores' refusals
+    //
+    // `format` therefore returns null (the fallback law's "cannot interpret")
+    // for anything the resolver did not turn into words, and the renderer is
+    // what distinguishes unresolvable from withheld. It never prints a bare id.
+    id: "relation",
+    label: "Relation",
+    description: "A record of another table \u2014 pick it, and its name is shown",
+    group: "Choice",
+    base: "string",
+    alsoAccepts: ["array", "json"],
+    editor: "select",
+    rich: true,
+    optionKeys: ["relation_target", "relation_max", "on_delete", "display"],
+    // IT DOES NOT DELEGATE TO `choice`, AND THAT IS THE WHOLE POINT.
+    // `choice.format` deliberately returns the RAW VALUE when no options have
+    // resolved yet — a structured list still loading should not make every cell
+    // look off-list. For a label column that is right: the raw value IS the
+    // label. For an identifier column it is the defect §3.3 names, and it is
+    // how the first cut of this wave put four raw uuids on a real grid: the
+    // fallback arm never ran, because returning the uuid counted as SUCCESS.
+    //
+    // Here, a value that did not resolve to words is a MISMATCH — `null` — so
+    // the renderer's three-state arm owns it and shows the amber fallback with
+    // the id marked as an identifier, or the withheld sentence. The id never
+    // reaches the eye as if it were the cell's contents.
+    format: (v, options) => {
+      const list = toList(v);
+      const values = list !== null ? list : v == null ? [] : [v];
+      if (values.length === 0) return "";
+      const words2 = [];
+      for (const entry of values) {
+        const text = toText(entry);
+        if (text === null) return null;
+        const trimmed = text.trim();
+        if (trimmed === "") continue;
+        const match = findChoice(options.choices, trimmed);
+        if (!match) return null;
+        words2.push(match.label ?? match.value);
+      }
+      return words2.length === 0 ? "" : words2.join(", ");
+    },
+    parse: (raw) => FIELD_FORMATS.choice.parse(raw, {})
+  },
   {
     id: "multi_choice",
     label: "Multi-choice",
@@ -10804,7 +11068,7 @@ var DEFS = [
   // A formula column stores NOTHING. `metadata.format.options.formula` holds
   // the expression; the stored cell is always null; the value is computed on
   // read from the other columns of the same row
-  // (`features/data-tables/formulas.ts`). Grouped under Structured on purpose
+  // (`@ai-matrx/design-system/formulas`). Grouped under Structured on purpose
   // — the picker's groups are a fixed vocabulary, and a formula is structure
   // over a plain string column, not a sixth family.
   //