@ai-matrx/design-system 0.21.14 → 0.25.0

package/dist/field-formats/index.js

@@ -0,0 +1,723 @@
+"use client";
+
+// src/field-formats/registry.ts
+import {
+  formatDurationSeconds,
+  formatFileSize,
+  formatRelativeTime
+} from "@ai-matrx/kit/format";
+function formatSignedDuration(totalSeconds) {
+  return formatDurationSeconds(totalSeconds, { signed: true });
+}
+function toNumber(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string") {
+    const cleaned = value.replace(/[,\s$€£¥%]/g, "");
+    if (cleaned === "") return null;
+    const n = Number(cleaned);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+function toText(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean")
+    return String(value);
+  return null;
+}
+function toDate(value) {
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
+  if (typeof value === "number") {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? null : d;
+  }
+  return null;
+}
+function toList(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.startsWith("[")) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed)) return parsed;
+      } catch {
+      }
+    }
+    if (trimmed === "") return [];
+    return trimmed.split(",").map((s) => s.trim());
+  }
+  return null;
+}
+function groupedNumber(n, options) {
+  return new Intl.NumberFormat(void 0, {
+    useGrouping: options.useGrouping !== false,
+    ...options.precision != null ? {
+      minimumFractionDigits: options.precision,
+      maximumFractionDigits: options.precision
+    } : { maximumFractionDigits: 10 }
+  }).format(n);
+}
+function affix(text, options) {
+  return `${options.prefix ?? ""}${text}${options.suffix ?? ""}`;
+}
+var DURATION_TO_SECONDS = { milliseconds: 1e-3, seconds: 1, minutes: 60, hours: 3600 };
+function findChoice(choices, value) {
+  if (!choices || choices.length === 0) return void 0;
+  const exact = choices.find((c) => c.value === value);
+  if (exact) return exact;
+  const lowered = value.toLowerCase();
+  return choices.find((c) => c.value.toLowerCase() === lowered);
+}
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var URL_RE = /^(?:[a-z][a-z0-9+.-]*:\/\/\S+|(?:[a-z0-9-]+\.)+[a-z]{2,}(?:[:/?#]\S*)?)$/i;
+var HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+var DEFS = [
+  // ── Text ──────────────────────────────────────────────────────────────────
+  {
+    id: "text",
+    label: "Text",
+    description: "Plain single-line text",
+    group: "Text",
+    base: "string",
+    editor: "text",
+    // Deliberately no optionKeys — plain text is the default for every string
+    // column, and giving it prefix/suffix controls puts an options row under
+    // every column in the settings dialog for a setting almost nobody wants.
+    format: (v, o) => {
+      const t = toText(v);
+      return t === null ? null : affix(t, o);
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw)
+  },
+  {
+    id: "long_text",
+    label: "Long text",
+    description: "Multi-line text, edited in a larger box",
+    group: "Text",
+    base: "string",
+    editor: "textarea",
+    format: (v) => toText(v),
+    parse: (raw) => raw === "" || raw == null ? null : String(raw)
+  },
+  {
+    id: "markdown",
+    label: "Markdown",
+    description: "Rich text written as Markdown",
+    group: "Text",
+    base: "string",
+    editor: "textarea",
+    rich: true,
+    format: (v) => toText(v),
+    parse: (raw) => raw === "" || raw == null ? null : String(raw)
+  },
+  {
+    id: "email",
+    label: "Email",
+    description: "Email address \u2014 click to compose",
+    group: "Text",
+    base: "string",
+    editor: "email",
+    rich: true,
+    format: (v) => {
+      const t = toText(v)?.trim();
+      if (!t) return null;
+      return EMAIL_RE.test(t) ? t : null;
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw).trim()
+  },
+  {
+    id: "url",
+    label: "Link",
+    description: "Web address \u2014 click to open",
+    group: "Text",
+    base: "string",
+    editor: "url",
+    rich: true,
+    format: (v) => {
+      const t = toText(v)?.trim();
+      if (!t) return null;
+      if (/\s/.test(t)) return null;
+      if (!URL_RE.test(t)) return null;
+      try {
+        new URL(t.includes("://") ? t : `https://${t}`);
+        return t;
+      } catch {
+        return null;
+      }
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw).trim()
+  },
+  {
+    id: "phone",
+    label: "Phone",
+    description: "Phone number \u2014 click to call",
+    group: "Text",
+    base: "string",
+    editor: "tel",
+    rich: true,
+    format: (v) => {
+      const t = toText(v)?.trim();
+      if (!t) return null;
+      return (t.match(/\d/g) ?? []).length >= 7 ? t : null;
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw).trim()
+  },
+  {
+    id: "color",
+    label: "Color",
+    description: "Hex color with a swatch",
+    group: "Text",
+    base: "string",
+    editor: "color",
+    rich: true,
+    format: (v) => {
+      const t = toText(v)?.trim();
+      if (!t) return null;
+      return HEX_RE.test(t) ? t.toLowerCase() : null;
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw).trim()
+  },
+  // ── Numbers ───────────────────────────────────────────────────────────────
+  {
+    id: "number",
+    label: "Number",
+    description: "Plain number",
+    group: "Numbers",
+    base: "number",
+    alsoAccepts: ["integer"],
+    editor: "number",
+    numericAlign: true,
+    optionKeys: ["useGrouping", "precision", "prefix", "suffix"],
+    format: (v, o) => {
+      const n = toNumber(v);
+      return n === null ? null : affix(groupedNumber(n, o), o);
+    },
+    parse: (raw) => toNumber(raw)
+  },
+  {
+    id: "decimal",
+    label: "Decimal",
+    description: "Number with fixed decimal places",
+    group: "Numbers",
+    base: "number",
+    alsoAccepts: ["integer"],
+    editor: "number",
+    numericAlign: true,
+    optionKeys: ["precision", "useGrouping", "prefix", "suffix"],
+    format: (v, o) => {
+      const n = toNumber(v);
+      if (n === null) return null;
+      return affix(groupedNumber(n, { ...o, precision: o.precision ?? 2 }), o);
+    },
+    parse: (raw) => toNumber(raw)
+  },
+  {
+    id: "currency",
+    label: "Currency",
+    description: "Money \u2014 stored as a plain number, shown with a symbol",
+    group: "Numbers",
+    base: "number",
+    alsoAccepts: ["integer"],
+    editor: "number",
+    numericAlign: true,
+    optionKeys: ["currency", "precision"],
+    format: (v, o) => {
+      const n = toNumber(v);
+      if (n === null) return null;
+      const currency = (o.currency || "USD").toUpperCase();
+      try {
+        return new Intl.NumberFormat(void 0, {
+          style: "currency",
+          currency,
+          ...o.precision != null ? {
+            minimumFractionDigits: o.precision,
+            maximumFractionDigits: o.precision
+          } : {}
+        }).format(n);
+      } catch {
+        return `${groupedNumber(n, { precision: o.precision ?? 2 })} ${currency}`;
+      }
+    },
+    parse: (raw) => toNumber(raw)
+  },
+  {
+    id: "percent",
+    label: "Percent",
+    description: "Percentage \u2014 stored as a plain number",
+    group: "Numbers",
+    base: "number",
+    alsoAccepts: ["integer"],
+    editor: "number",
+    numericAlign: true,
+    optionKeys: ["percentScale", "precision"],
+    format: (v, o) => {
+      const n = toNumber(v);
+      if (n === null) return null;
+      const shown = o.percentScale === "fraction" ? n * 100 : n;
+      return `${groupedNumber(shown, o.precision === void 0 ? {} : { precision: o.precision })}%`;
+    },
+    parse: (raw) => toNumber(raw)
+  },
+  {
+    id: "duration",
+    label: "Duration",
+    description: "Length of time, shown as h:mm:ss",
+    group: "Numbers",
+    base: "number",
+    alsoAccepts: ["integer"],
+    editor: "number",
+    numericAlign: true,
+    optionKeys: ["durationUnit"],
+    format: (v, o) => {
+      const n = toNumber(v);
+      if (n === null) return null;
+      return formatSignedDuration(n * DURATION_TO_SECONDS[o.durationUnit ?? "seconds"]);
+    },
+    parse: (raw) => toNumber(raw)
+  },
+  {
+    id: "integer",
+    label: "Whole number",
+    description: "Integer with no decimal part",
+    group: "Numbers",
+    base: "integer",
+    alsoAccepts: ["number"],
+    editor: "number",
+    numericAlign: true,
+    optionKeys: ["useGrouping", "prefix", "suffix"],
+    format: (v, o) => {
+      const n = toNumber(v);
+      if (n === null) return null;
+      return affix(groupedNumber(Math.trunc(n), { ...o, precision: 0 }), o);
+    },
+    parse: (raw) => {
+      const n = toNumber(raw);
+      return n === null ? null : Math.trunc(n);
+    }
+  },
+  {
+    id: "rating",
+    label: "Rating",
+    description: "Score out of a maximum, shown as stars",
+    group: "Numbers",
+    base: "integer",
+    alsoAccepts: ["number"],
+    editor: "rating",
+    rich: true,
+    optionKeys: ["ratingMax"],
+    format: (v, o) => {
+      const n = toNumber(v);
+      if (n === null) return null;
+      const max = o.ratingMax ?? 5;
+      if (n < 0 || n > max) return null;
+      return `${n} / ${max}`;
+    },
+    parse: (raw) => {
+      const n = toNumber(raw);
+      return n === null ? null : Math.round(n);
+    }
+  },
+  {
+    id: "file_size",
+    label: "File size",
+    description: "Byte count shown as KB / MB / GB",
+    group: "Numbers",
+    base: "integer",
+    alsoAccepts: ["number"],
+    editor: "number",
+    numericAlign: true,
+    format: (v) => {
+      const n = toNumber(v);
+      return n === null ? null : formatFileSize(n);
+    },
+    parse: (raw) => {
+      const n = toNumber(raw);
+      return n === null ? null : Math.trunc(n);
+    }
+  },
+  // ── Choice ────────────────────────────────────────────────────────────────
+  {
+    id: "boolean",
+    label: "Yes / No",
+    description: "True or false",
+    group: "Choice",
+    base: "boolean",
+    editor: "checkbox",
+    format: (v) => {
+      if (typeof v === "boolean") return v ? "Yes" : "No";
+      if (v === "true" || v === 1) return "Yes";
+      if (v === "false" || v === 0) return "No";
+      return null;
+    },
+    parse: (raw) => {
+      if (typeof raw === "boolean") return raw;
+      if (raw == null || raw === "") return null;
+      return String(raw).toLowerCase() === "true" || raw === 1;
+    }
+  },
+  // ── Dates ─────────────────────────────────────────────────────────────────
+  {
+    id: "date",
+    label: "Date",
+    description: "Calendar date",
+    group: "Dates",
+    base: "date",
+    alsoAccepts: ["datetime", "string"],
+    editor: "date",
+    optionKeys: ["dateStyle"],
+    format: (v, o) => {
+      const d = toDate(v);
+      if (!d) return null;
+      return d.toLocaleDateString(void 0, {
+        dateStyle: o.dateStyle ?? "medium"
+      });
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw)
+  },
+  {
+    id: "datetime",
+    label: "Date & time",
+    description: "Calendar date with a time of day",
+    group: "Dates",
+    base: "datetime",
+    alsoAccepts: ["date", "string"],
+    editor: "datetime",
+    optionKeys: ["dateStyle"],
+    format: (v, o) => {
+      const d = toDate(v);
+      if (!d) return null;
+      return d.toLocaleString(void 0, {
+        dateStyle: o.dateStyle ?? "medium",
+        timeStyle: "short"
+      });
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw)
+  },
+  {
+    id: "relative_time",
+    label: "Relative time",
+    description: 'Shown as "3 days ago"',
+    group: "Dates",
+    base: "datetime",
+    alsoAccepts: ["date", "string"],
+    editor: "datetime",
+    format: (v) => {
+      const d = toDate(v);
+      return d ? formatRelativeTime(d, { style: "intl" }) : null;
+    },
+    parse: (raw) => raw === "" || raw == null ? null : String(raw)
+  },
+  // ── Structured ────────────────────────────────────────────────────────────
+  {
+    id: "json",
+    label: "JSON",
+    description: "Structured object",
+    group: "Structured",
+    base: "json",
+    alsoAccepts: ["array"],
+    editor: "json",
+    format: (v) => {
+      if (v === null || v === void 0) return null;
+      if (typeof v === "object") return JSON.stringify(v);
+      return toText(v);
+    },
+    parse: (raw) => {
+      if (raw == null || raw === "") return null;
+      if (typeof raw !== "string") return raw;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return raw;
+      }
+    }
+  },
+  {
+    id: "array",
+    label: "List",
+    description: "List of values",
+    group: "Structured",
+    base: "array",
+    alsoAccepts: ["json"],
+    editor: "json",
+    format: (v) => {
+      const list = toList(v);
+      return list === null ? null : list.map((i) => String(i)).join(", ");
+    },
+    parse: (raw) => {
+      if (raw == null || raw === "") return null;
+      if (Array.isArray(raw)) return raw;
+      return toList(raw) ?? raw;
+    }
+  },
+  {
+    id: "tags",
+    label: "Tags",
+    description: "List of values shown as chips",
+    group: "Structured",
+    base: "array",
+    alsoAccepts: ["json", "string"],
+    editor: "json",
+    rich: true,
+    format: (v) => {
+      const list = toList(v);
+      return list === null ? null : list.map((i) => String(i)).join(", ");
+    },
+    parse: (raw) => {
+      if (raw == null || raw === "") return null;
+      if (Array.isArray(raw)) return raw;
+      return toList(raw) ?? raw;
+    }
+  },
+  // ─── Choice ────────────────────────────────────────────────────────────────
+  //
+  // An enum WITHOUT a database enum. The column stays `string` (or `array` for
+  // multi), the database enforces nothing, and stripping the format leaves
+  // every stored value exactly as it was. Options are a UI layer — the same
+  // trick `percent` plays on a number.
+  //
+  // The fallback law is the whole reason this is safe to switch on over live
+  // data: a value not in the option list is NOT an error and is NEVER blanked.
+  // `format()` returns null for it, `<FormattedFieldValue>` renders it in amber
+  // with the reason, and the user can fix it or adopt it. Declaring the options
+  // is therefore how you FIND your stray values, not how you lose them.
+  //
+  // Options resolve through `choices.ts` — inline `options.choices`, or a
+  // structured list via `options.structuredList`. This def only ever sees
+  // whatever the caller resolved into `options.choices`, so it stays pure and
+  // synchronous like every other format.
+  {
+    id: "choice",
+    label: "Choice",
+    description: "One value from a list of options",
+    group: "Choice",
+    base: "string",
+    alsoAccepts: ["number", "integer", "boolean"],
+    editor: "select",
+    rich: true,
+    optionKeys: ["choices", "structuredList", "allowOther"],
+    format: (v, options) => {
+      const text = toText(v);
+      if (text === null) return null;
+      const trimmed = text.trim();
+      if (trimmed === "") return "";
+      const match = findChoice(options.choices, trimmed);
+      if (!options.choices || options.choices.length === 0) return trimmed;
+      return match ? match.label ?? match.value : null;
+    },
+    parse: (raw) => {
+      if (raw == null) return null;
+      const text = toText(raw);
+      if (text === null) return raw;
+      const trimmed = text.trim();
+      return trimmed === "" ? null : trimmed;
+    }
+  },
+  {
+    id: "multi_choice",
+    label: "Multi-choice",
+    description: "Any number of values from a list of options",
+    group: "Choice",
+    base: "array",
+    alsoAccepts: ["string", "json"],
+    editor: "multiselect",
+    rich: true,
+    optionKeys: ["choices", "structuredList", "allowOther"],
+    format: (v, options) => {
+      const list = toList(v);
+      if (list === null) return null;
+      if (list.length === 0) return "";
+      const labels = [];
+      let anyOffList = false;
+      for (const entry of list) {
+        const text = toText(entry);
+        if (text === null) {
+          anyOffList = true;
+          continue;
+        }
+        const match = findChoice(options.choices, text.trim());
+        if (match) labels.push(match.label ?? match.value);
+        else {
+          labels.push(text.trim());
+          anyOffList = true;
+        }
+      }
+      const haveOptions = !!options.choices && options.choices.length > 0;
+      if (haveOptions && anyOffList) return null;
+      return labels.join(", ");
+    },
+    parse: (raw) => {
+      if (raw == null || raw === "") return null;
+      if (Array.isArray(raw)) return raw;
+      return toList(raw) ?? raw;
+    }
+  },
+  // ─── Computed ──────────────────────────────────────────────────────────────
+  //
+  // 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
+  // — the picker's groups are a fixed vocabulary, and a formula is structure
+  // over a plain string column, not a sixth family.
+  //
+  // `format()` here is handed the COMPUTED value, never a stored one, and its
+  // only job is to render it: through `resultFormat`'s own `format()` when the
+  // column declares one (a computed total shown as Currency, a computed date
+  // shown as a Date), and plainly otherwise. It never returns null for an
+  // empty value, because a formula legitimately produces BLANK.
+  //
+  // No `optionKeys`: the expression is authored in its own editor, not in the
+  // generic option rail, and listing a key the picker has no control for would
+  // open an empty options section under every formula column.
+  {
+    id: "formula",
+    label: "Formula",
+    description: "Computed from the other columns in the row \u2014 never typed in",
+    group: "Structured",
+    base: "string",
+    editor: "computed",
+    format: (v, o) => {
+      const target = o.formula?.resultFormat;
+      if (target && target !== "formula") {
+        const delegate = FIELD_FORMATS[target];
+        if (delegate) {
+          const rendered = delegate.format(v, o);
+          if (rendered !== null) return rendered;
+        }
+      }
+      if (v === null || v === void 0) return "";
+      if (typeof v === "boolean") return v ? "Yes" : "No";
+      if (typeof v === "number") return groupedNumber(v, o);
+      return toText(v);
+    },
+    // Nothing is ever stored in a formula column. Returning the raw input here
+    // would be the one way a computed cell could acquire a value of its own.
+    parse: () => null
+  }
+];
+var FIELD_FORMATS = Object.freeze(
+  Object.fromEntries(DEFS.map((d) => [d.id, d]))
+);
+var FIELD_FORMAT_LIST = Object.freeze(DEFS);
+var FIELD_FORMAT_IDS = DEFS.map((d) => d.id);
+function getFieldFormat(id) {
+  if (!id) return null;
+  return FIELD_FORMATS[id] ?? null;
+}
+function defaultFormatForBase(base) {
+  switch (base) {
+    case "number":
+      return "number";
+    case "integer":
+      return "integer";
+    case "boolean":
+      return "boolean";
+    case "date":
+      return "date";
+    case "datetime":
+      return "datetime";
+    case "json":
+      return "json";
+    case "array":
+      return "array";
+    default:
+      return "text";
+  }
+}
+function formatsForBase(base) {
+  return DEFS.filter(
+    (d) => d.base === base || (d.alsoAccepts ?? []).includes(base)
+  );
+}
+function groupedFormatsForBase(base) {
+  const out = [];
+  for (const def of formatsForBase(base)) {
+    const bucket = out.find((g) => g.group === def.group);
+    if (bucket) bucket.formats.push(def);
+    else out.push({ group: def.group, formats: [def] });
+  }
+  return out;
+}
+
+// src/field-formats/format.ts
+function isEmpty(value) {
+  return value === null || value === void 0 || value === "";
+}
+function baseText(value) {
+  if (isEmpty(value)) return "";
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+function readFieldFormatConfig(metadata) {
+  if (!metadata || typeof metadata !== "object") return null;
+  const raw = metadata.format;
+  if (!raw || typeof raw !== "object") return null;
+  const id = raw.id;
+  if (typeof id !== "string" || !getFieldFormat(id)) return null;
+  const options = raw.options;
+  return {
+    id,
+    ...options && typeof options === "object" ? { options } : {}
+  };
+}
+function resolveFieldFormat(dataType, metadata) {
+  const declared = readFieldFormatConfig(metadata);
+  if (declared) return declared;
+  return { id: defaultFormatForBase(dataType) };
+}
+function formatFieldValue(value, config, dataType) {
+  if (isEmpty(value)) return { ok: true, text: "", empty: true };
+  const def = config ? getFieldFormat(config.id) : null;
+  const effective = def ?? FIELD_FORMATS[defaultFormatForBase(dataType ?? "string")];
+  let formatted;
+  try {
+    formatted = effective.format(value, config?.options ?? {});
+  } catch {
+    formatted = null;
+  }
+  if (formatted !== null) return { ok: true, text: formatted, empty: false };
+  return {
+    ok: false,
+    text: baseText(value),
+    empty: false,
+    reason: `This value is not a valid ${effective.label.toLowerCase()} \u2014 showing the stored value instead.`
+  };
+}
+function parseFieldInput(raw, config, dataType) {
+  const def = config ? getFieldFormat(config.id) : null;
+  const effective = def ?? FIELD_FORMATS[defaultFormatForBase(dataType ?? "string")];
+  try {
+    return effective.parse(raw, config?.options ?? {});
+  } catch {
+    return raw;
+  }
+}
+function valueFitsFormat(value, config, dataType) {
+  return formatFieldValue(value, config, dataType).ok;
+}
+export {
+  FIELD_FORMATS,
+  FIELD_FORMAT_IDS,
+  FIELD_FORMAT_LIST,
+  defaultFormatForBase,
+  formatFieldValue,
+  formatsForBase,
+  getFieldFormat,
+  groupedFormatsForBase,
+  parseFieldInput,
+  readFieldFormatConfig,
+  resolveFieldFormat,
+  valueFitsFormat
+};
+//# sourceMappingURL=index.js.map