@multiplatform.one/backoffice 6.4.3 → 6.7.0

package/src/list/listColumns.tsx

@@ -0,0 +1,297 @@
+// Meta-driven column builder for the doctype list view (desk parity):
+// liked heart, bolded title (title_field), in_list_view fields with
+// fieldtype-aware cells (status pills, dates, checks, numerics), subdued
+// ID, and a relative "Last Updated On" column.
+import { Text, XStack } from "@multiplatform.one/components";
+// House control for the like toggle — the icon rides the Button icon slot
+// (LC-53 GLYPH-SLOT) and the sub-44 circular size resolves the press floor
+// through the house channel (LC-54: 44px box + hitSlop).
+import { Button } from "@multiplatform.one/forms";
+import { HeartIcon } from "@phosphor-icons/react";
+import type { DataTableColumn } from "@multiplatform.one/table";
+import type { PermLevelMatrix } from "../form/fieldPermissions";
+import type { DocFieldMeta, DoctypeMeta } from "../shared/useDoctypeMeta";
+// Field selection + permlevel pruning live in the pure listFields module
+// (node-safe, unit-tested in listFields.spec.ts).
+import { listViewFields } from "./listFields";
+import { formatDateCell, formatTimeAgo, parseUserListField, stripHtmlPreview } from "./listFormat";
+import { statusPillColors } from "./statusColors";
+
+/** Minimal row shape for a doctype list (loose — server owns the schema). */
+export interface ListDoc {
+  name: string;
+  doctype: string;
+  [key: string]: unknown;
+}
+
+export type ListRow = Partial<ListDoc>;
+
+type Translate = (key: string, fallback: string) => string;
+
+export interface BuildListColumnsArgs {
+  meta?: DoctypeMeta;
+  t: Translate;
+  /** Session user — hearts fill when `_liked_by` contains them. */
+  sessionUser?: string;
+  /** Toggle like for a document (omit to render hearts read-only). */
+  onToggleLike?: (name: string, nextLiked: boolean) => void;
+  /** Optimistic like overrides keyed by document name. */
+  likeOverrides?: Record<string, boolean>;
+  /**
+   * Permlevel role matrix (session roles × meta.permissions, built with
+   * `buildPermLevelMatrix`). Columns for fields the roles cannot READ at
+   * their permlevel are pruned — desk parity with base_list.js
+   * `get_fields_in_list_view` (`frappe.perm.has_perm(doctype, df.permlevel,
+   * "read")`). Undefined (fixtures / roles unavailable) prunes nothing —
+   * the server strips no-read values either way.
+   */
+  permMatrix?: PermLevelMatrix;
+}
+
+const NUMERIC_FIELDTYPES = new Set(["Currency", "Float", "Int", "Percent", "Duration"]);
+
+// Fieldtypes whose stored value is markup — list cells render a stripped
+// one-line plain-text preview (desk strip_html parity), never raw HTML.
+const RICH_TEXT_FIELDTYPES = new Set([
+  "Text Editor",
+  "HTML Editor",
+  "HTML",
+  "Markdown Editor",
+  "Long Text",
+  "Text",
+  "Small Text",
+]);
+
+/** Cell-safe one-line preview: rich fieldtypes stripped, newlines collapsed. */
+function cellPreview(value: string, fieldtype?: string): string {
+  const text = fieldtype && RICH_TEXT_FIELDTYPES.has(fieldtype) ? stripHtmlPreview(value) : value;
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function isStatusField(field: DocFieldMeta, meta?: DoctypeMeta): boolean {
+  if (field.fieldname === "status") return true;
+  if (field.fieldtype !== "Select") return false;
+  const stateTitles = new Set(
+    (meta?.states ?? []).map((state) => (state.title ?? "").trim().toLowerCase()),
+  );
+  if (stateTitles.size === 0) return false;
+  const options = (field.options ?? "").split("\n").map((option) => option.trim().toLowerCase());
+  return options.some((option) => option && stateTitles.has(option));
+}
+
+function StatusPill({ value, meta }: { value: string; meta?: DoctypeMeta }) {
+  const colors = statusPillColors(value, meta);
+  return (
+    <XStack
+      alignSelf="flex-start"
+      backgroundColor={colors.background as "$color3"}
+      borderRadius={999}
+      paddingHorizontal="$2.5"
+      paddingVertical="$1"
+    >
+      <Text color={colors.text as "$color11"} fontSize="$2" fontWeight="600">
+        {value}
+      </Text>
+    </XStack>
+  );
+}
+
+function fieldCell(field: DocFieldMeta, meta: DoctypeMeta | undefined) {
+  return ({ getValue }: { getValue: () => unknown }) => {
+    const raw = getValue();
+    if (raw === null || raw === undefined || raw === "")
+      return (
+        <Text fontSize="$3" color="$color8">
+          —
+        </Text>
+      );
+    const value = String(raw);
+    if (isStatusField(field, meta)) return <StatusPill value={value} meta={meta} />;
+    switch (field.fieldtype) {
+      case "Check":
+        return (
+          <Text fontSize="$3" color={raw ? "$green11" : "$color8"}>
+            {raw ? "✓" : "—"}
+          </Text>
+        );
+      case "Date":
+      case "Datetime":
+        return (
+          <Text fontSize="$3" color="$color11">
+            {formatDateCell(value)}
+          </Text>
+        );
+      case "Currency":
+      case "Float":
+      case "Int":
+      case "Percent":
+        return (
+          <Text fontSize="$3" color="$color12" textAlign="right">
+            {value}
+          </Text>
+        );
+      case "Link":
+        return (
+          <Text fontSize="$3" color="$color11" numberOfLines={1} flexShrink={1} minWidth={0}>
+            {value}
+          </Text>
+        );
+      default:
+        // One-line plain-text preview (rich markup stripped) that SHRINKS
+        // inside the cell (flexShrink + minWidth 0) so numberOfLines can
+        // ellipsize instead of painting under the neighbor column
+        // (LC-06/LC-10; cell-containment rule candidate, audit pair 16).
+        return (
+          <Text fontSize="$3" color="$color11" numberOfLines={1} flexShrink={1} minWidth={0}>
+            {cellPreview(value, field.fieldtype)}
+          </Text>
+        );
+    }
+  };
+}
+
+/** Build the DataTable columns for a doctype list from its meta. */
+export function buildListColumns({
+  meta,
+  t,
+  sessionUser,
+  onToggleLike,
+  likeOverrides,
+  permMatrix,
+}: BuildListColumnsArgs): DataTableColumn<ListRow>[] {
+  const titleField = meta?.title_field || "name";
+  const columns: DataTableColumn<ListRow>[] = [];
+
+  // Liked hearts (desk `_liked_by` column). Press toggles; navigation is
+  // stopped so the row click underneath does not fire.
+  columns.push({
+    id: "_liked_by",
+    // Glyph header with a spoken name — a bare "♥" string gives the column
+    // an unpronounceable accessible name. Presentational glyph + aria-label.
+    header: () => (
+      <Text role="img" aria-label={t("list.likedColumn", "Liked")} color="$color9" fontSize="$4">
+        ♥
+      </Text>
+    ),
+    accessorKey: "_liked_by",
+    sortable: false,
+    filterable: false,
+    width: 56,
+    maxWidth: 64,
+    align: "center",
+    cell: ({ row }) => {
+      const doc = row.original;
+      const name = doc.name ?? "";
+      const likedBy = parseUserListField(doc._liked_by);
+      const liked = likeOverrides?.[name] ?? (sessionUser ? likedBy.includes(sessionUser) : false);
+      const likeLabel = liked
+        ? t("list.unlike", "Remove from liked")
+        : t("list.like", "Add to liked");
+      if (!onToggleLike || !name) {
+        // Read-only surface (fixtures / no session): presentational glyph.
+        return (
+          <Text
+            fontSize="$4"
+            color={liked ? "$red10" : "$color8"}
+            role="img"
+            aria-label={likeLabel}
+          >
+            {liked ? "♥" : "♡"}
+          </Text>
+        );
+      }
+      return (
+        <Button
+          circular
+          chromeless
+          size="$2"
+          // LC-53 GLYPH-SLOT: glyph rides the icon slot; the slot themes the
+          // clone from the control's color (`col` shorthand).
+          col={(liked ? "$red10" : "$color8") as never}
+          icon={<HeartIcon size={16} weight={liked ? "fill" : "regular"} />}
+          aria-label={likeLabel}
+          aria-pressed={liked}
+          onPress={(event) => {
+            event?.stopPropagation?.();
+            onToggleLike(name, !liked);
+          }}
+        />
+      );
+    },
+  });
+
+  // Title column: title_field bolded (desk subject).
+  const titleMeta = meta?.fields?.find((field) => field.fieldname === titleField);
+  columns.push({
+    id: titleField,
+    header:
+      titleField === "name"
+        ? t("list.idColumn", "ID")
+        : titleMeta?.label || t("list.titleColumn", "Title"),
+    accessorKey: titleField,
+    minWidth: 180,
+    cell: ({ row, getValue }) => {
+      const raw = getValue();
+      const value =
+        raw === null || raw === undefined || raw === "" ? (row.original.name ?? "") : String(raw);
+      // Same containment contract as fieldCell: stripped preview + a
+      // shrinkable text box so the one-line clamp ellipsizes in-column.
+      return (
+        <Text
+          fontSize="$3"
+          fontWeight="600"
+          color="$color12"
+          numberOfLines={1}
+          flexShrink={1}
+          minWidth={0}
+        >
+          {cellPreview(value, titleMeta?.fieldtype)}
+        </Text>
+      );
+    },
+  });
+
+  // in_list_view fields from meta (permlevel-pruned).
+  for (const field of listViewFields(meta, titleField, permMatrix)) {
+    columns.push({
+      id: field.fieldname,
+      header: field.label || field.fieldname,
+      accessorKey: field.fieldname,
+      ...(NUMERIC_FIELDTYPES.has(field.fieldtype) ? { align: "right" as const } : {}),
+      cell: fieldCell(field, meta),
+    });
+  }
+
+  // Subdued ID column when the title field is something else.
+  if (titleField !== "name") {
+    columns.push({
+      id: "name",
+      header: t("list.idColumn", "ID"),
+      accessorKey: "name",
+      maxWidth: 160,
+      cell: ({ getValue }) => (
+        <Text fontSize="$2" color="$color9" numberOfLines={1}>
+          {String(getValue() ?? "")}
+        </Text>
+      ),
+    });
+  }
+
+  // Desk "Last Updated On".
+  columns.push({
+    id: "modified",
+    header: t("list.lastUpdated", "Last Updated On"),
+    accessorKey: "modified",
+    maxWidth: 140,
+    cell: ({ getValue }) => {
+      const raw = getValue();
+      return (
+        <Text fontSize="$2" color="$color9">
+          {raw ? formatTimeAgo(String(raw)) : ""}
+        </Text>
+      );
+    },
+  });
+
+  return columns;
+}

package/src/list/listFields.spec.ts

@@ -0,0 +1,98 @@
+/**
+ * listFields — permlevel column pruning (desk parity with base_list.js
+ * `get_fields_in_list_view`: in_list_view fields above the session roles'
+ * READ permlevel never render as columns). The matrix itself is the form
+ * workstream's fieldPermissions module (perm.js parity) — reused, not forked.
+ * buildListColumns maps listViewFields 1:1 into column defs, so pruning is
+ * asserted here on the pure module (the features vitest node environment
+ * cannot import the JSX/components barrel — see vitest.config.mjs).
+ */
+import { describe, expect, it } from "vitest";
+import { buildPermLevelMatrix, type PermLevelMatrix } from "../form/fieldPermissions";
+import type { DoctypeMeta } from "../shared/useDoctypeMeta";
+import { listFieldsToFetch, listViewFields } from "./listFields";
+
+const meta: DoctypeMeta = {
+  name: "User",
+  title_field: "full_name",
+  fields: [
+    { fieldname: "full_name", fieldtype: "Data", label: "Full Name", in_list_view: 1 },
+    { fieldname: "enabled", fieldtype: "Check", label: "Enabled", in_list_view: 1 },
+    {
+      fieldname: "role_profile_name",
+      fieldtype: "Link",
+      label: "Role Profile",
+      in_list_view: 1,
+      permlevel: 1,
+    },
+    {
+      fieldname: "api_secret_hint",
+      fieldtype: "Data",
+      label: "API Secret Hint",
+      in_list_view: 1,
+      permlevel: 2,
+    },
+    { fieldname: "bio", fieldtype: "Small Text", label: "Bio" },
+  ],
+  permissions: [
+    { role: "System Manager", permlevel: 0, read: 1, write: 1 },
+    { role: "System Manager", permlevel: 1, read: 1, write: 1 },
+    // No rows at permlevel 2 — desk gap-fills {} and hides those fields.
+  ],
+};
+
+function viewFieldnames(matrix?: PermLevelMatrix): string[] {
+  return listViewFields(meta, meta.title_field ?? "name", matrix).map((field) => field.fieldname);
+}
+
+describe("listViewFields permlevel pruning", () => {
+  it("without a matrix (fixtures / roles unavailable) prunes nothing", () => {
+    const names = viewFieldnames(undefined);
+    expect(names).toContain("enabled");
+    expect(names).toContain("role_profile_name");
+    expect(names).toContain("api_secret_hint");
+  });
+
+  it("keeps fields whose permlevel the roles can read, prunes the rest", () => {
+    const matrix = buildPermLevelMatrix(meta.permissions, ["System Manager"]);
+    const names = viewFieldnames(matrix);
+    expect(names).toContain("enabled"); // level 0
+    expect(names).toContain("role_profile_name"); // level 1 granted
+    // Level 2 has no granting rows at all → hidden (desk gap-fill).
+    expect(names).not.toContain("api_secret_hint");
+  });
+
+  it("prunes every above-zero level for roles with no granting rows", () => {
+    const matrix = buildPermLevelMatrix(meta.permissions, ["Desk User"]);
+    const names = viewFieldnames(matrix);
+    expect(names).toContain("enabled");
+    expect(names).not.toContain("role_profile_name");
+    expect(names).not.toContain("api_secret_hint");
+  });
+
+  it("excludes the title field regardless of the matrix (title column owns it)", () => {
+    expect(viewFieldnames(undefined)).not.toContain("full_name");
+    const matrix = buildPermLevelMatrix(meta.permissions, ["Desk User"]);
+    expect(viewFieldnames(matrix)).not.toContain("full_name");
+  });
+
+  it("never includes fields that are not in_list_view", () => {
+    expect(viewFieldnames(undefined)).not.toContain("bio");
+  });
+});
+
+describe("listFieldsToFetch permlevel pruning", () => {
+  it("skips unreadable in_list_view fields but keeps bookkeeping fields", () => {
+    const matrix = buildPermLevelMatrix(meta.permissions, ["Desk User"]);
+    const fields = listFieldsToFetch(meta, matrix);
+    expect(fields).toEqual(expect.arrayContaining(["name", "modified", "full_name", "enabled"]));
+    expect(fields).not.toContain("role_profile_name");
+    expect(fields).not.toContain("api_secret_hint");
+  });
+
+  it("fetches everything in_list_view when no matrix is available", () => {
+    const fields = listFieldsToFetch(meta, undefined);
+    expect(fields).toContain("role_profile_name");
+    expect(fields).toContain("api_secret_hint");
+  });
+});

package/src/list/listFields.ts

@@ -0,0 +1,58 @@
+// Pure (node-safe, no UI imports) field selection for the doctype list:
+// which fields to fetch and which in_list_view fields render as columns.
+// Kept out of listColumns.tsx so the pruning logic is unit-testable under
+// the features vitest node environment (specs here never import the
+// components barrel — see vitest.config.mjs).
+//
+// Permlevel pruning reuses the form workstream's UI-free role-matrix module
+// (desk perm.js parity) rather than forking it (schema conformance §10
+// handoff).
+import { canReadLevel, type PermLevelMatrix } from "../form/fieldPermissions";
+import type { DocFieldMeta, DoctypeMeta } from "../shared/useDoctypeMeta";
+
+/** Read access for a field's permlevel (level 0 / no matrix always read). */
+function fieldLevelReadable(field: DocFieldMeta, permMatrix?: PermLevelMatrix): boolean {
+  return canReadLevel(permMatrix, Number(field.permlevel ?? 0) || 0);
+}
+
+/** Fields the list view fetches for a doctype (columns + niceties). */
+export function listFieldsToFetch(meta?: DoctypeMeta, permMatrix?: PermLevelMatrix): string[] {
+  const fields = new Set<string>([
+    "name",
+    "modified",
+    "owner",
+    "_liked_by",
+    "_assign",
+    "_user_tags",
+  ]);
+  if (meta?.title_field) fields.add(meta.title_field);
+  for (const field of meta?.fields ?? []) {
+    if (field.in_list_view && field.fieldname && fieldLevelReadable(field, permMatrix)) {
+      fields.add(field.fieldname);
+    }
+  }
+  return [...fields];
+}
+
+/**
+ * The in_list_view fields to render as columns (title field excluded).
+ * Desk parity: fields above the session's read permlevel never render as
+ * list columns (base_list.js `get_fields_in_list_view` →
+ * `frappe.perm.has_perm(doctype, df.permlevel, "read")`). An undefined
+ * matrix (fixtures / roles unavailable) prunes nothing — the server strips
+ * no-read values either way.
+ */
+export function listViewFields(
+  meta: DoctypeMeta | undefined,
+  titleField: string,
+  permMatrix?: PermLevelMatrix,
+): DocFieldMeta[] {
+  return (meta?.fields ?? []).filter(
+    (field) =>
+      Boolean(field.in_list_view) &&
+      field.fieldname !== titleField &&
+      field.fieldtype !== "Image" &&
+      field.fieldtype !== "Attach Image" &&
+      fieldLevelReadable(field, permMatrix),
+  );
+}

package/src/list/listFormat.spec.ts

@@ -0,0 +1,151 @@
+/**
+ * listFormat — frappe datetime parsing and desk-style list-cell display
+ * helpers. Time-ago fixtures anchor `now` to the parsed date itself so the
+ * assertions are timezone-independent.
+ */
+import { describe, expect, it } from "vitest";
+import {
+  formatDateCell,
+  formatTimeAgo,
+  parseFrappeDate,
+  parseTagsField,
+  parseUserListField,
+  stripHtmlPreview,
+} from "./listFormat";
+
+describe("parseFrappeDate", () => {
+  it("parses frappe datetime strings (space-separated, microseconds)", () => {
+    const date = parseFrappeDate("2026-08-12 08:50:24.691936");
+    expect(date).toBeInstanceOf(Date);
+    expect(date?.getFullYear()).toBe(2026);
+    expect(date?.getMonth()).toBe(7); // August
+    expect(date?.getDate()).toBe(12);
+    expect(date?.getHours()).toBe(8);
+    expect(date?.getMinutes()).toBe(50);
+    expect(date?.getSeconds()).toBe(24);
+  });
+
+  it("parses plain dates", () => {
+    const date = parseFrappeDate("2026-08-12");
+    expect(date).toBeInstanceOf(Date);
+    expect(Number.isNaN(date?.getTime())).toBe(false);
+  });
+
+  it("returns undefined for invalid input", () => {
+    expect(parseFrappeDate("not a date")).toBeUndefined();
+    expect(parseFrappeDate("")).toBeUndefined();
+  });
+});
+
+describe("formatDateCell (LC-12 compact-absolute display register)", () => {
+  // Anchor `now` inside the stamp's year so current-year elision is stable.
+  const now = parseFrappeDate("2026-01-01 00:00:00") as Date;
+
+  it("renders the house compact-absolute register, never raw ISO", () => {
+    expect(formatDateCell("2026-08-12 08:50:24", now)).toBe("Aug 12");
+    expect(formatDateCell("2026-08-12 08:50:24.691936", now)).toBe("Aug 12");
+    expect(formatDateCell("2026-08-12", now)).toBe("Aug 12");
+  });
+
+  it("keeps the year when not current (display register year:auto)", () => {
+    expect(formatDateCell("2025-07-01", now)).toBe("Jul 1, 2025");
+  });
+
+  it("passes unparseable input through unchanged (honest passthrough)", () => {
+    expect(formatDateCell("garbage", now)).toBe("garbage");
+  });
+});
+
+describe("formatTimeAgo (LC-12 relative register)", () => {
+  const stamp = "2026-08-12 08:00:00";
+  const base = parseFrappeDate(stamp) as Date;
+  const after = (ms: number) => new Date(base.getTime() + ms);
+  const MINUTE = 60_000;
+  const HOUR = 60 * MINUTE;
+  const DAY = 24 * HOUR;
+
+  it("speaks the house relative register — one voice, unambiguous units", () => {
+    expect(formatTimeAgo(stamp, after(0))).toBe("just now");
+    expect(formatTimeAgo(stamp, after(59_000))).toBe("just now");
+    expect(formatTimeAgo(stamp, after(MINUTE))).toBe("1m ago");
+    expect(formatTimeAgo(stamp, after(59 * MINUTE))).toBe("59m ago");
+    expect(formatTimeAgo(stamp, after(HOUR))).toBe("1h ago");
+    expect(formatTimeAgo(stamp, after(23 * HOUR + 59 * MINUTE))).toBe("23h ago");
+    expect(formatTimeAgo(stamp, after(DAY))).toBe("1 day ago");
+    expect(formatTimeAgo(stamp, after(29 * DAY))).toBe("29 days ago");
+  });
+
+  it("months use 'mo', never an ambiguous capital M", () => {
+    expect(formatTimeAgo(stamp, after(31 * DAY))).toBe("1mo ago");
+    expect(formatTimeAgo(stamp, after(330 * DAY))).toBe("11mo ago");
+  });
+
+  it("shows years beyond ~12 months", () => {
+    expect(formatTimeAgo(stamp, after(366 * DAY))).toBe("1y ago");
+    expect(formatTimeAgo(stamp, after(2 * 366 * DAY))).toBe("2y ago");
+  });
+
+  it("returns the raw value when unparseable", () => {
+    expect(formatTimeAgo("garbage", new Date())).toBe("garbage");
+  });
+
+  it("treats future timestamps as just now (clamped, never negative)", () => {
+    expect(formatTimeAgo(stamp, after(-5 * HOUR))).toBe("just now");
+  });
+});
+
+describe("parseUserListField (_assign / _liked_by JSON-array-string columns)", () => {
+  it("parses the bench shape: a JSON array string", () => {
+    expect(parseUserListField('["admin@example.com", "test@example.com"]')).toEqual([
+      "admin@example.com",
+      "test@example.com",
+    ]);
+  });
+
+  it("passes real arrays through, stringifying members", () => {
+    expect(parseUserListField(["a@b.c", 42])).toEqual(["a@b.c", "42"]);
+  });
+
+  it("returns [] for empty, malformed, or non-array JSON", () => {
+    expect(parseUserListField("")).toEqual([]);
+    expect(parseUserListField(null)).toEqual([]);
+    expect(parseUserListField(undefined)).toEqual([]);
+    expect(parseUserListField("not json")).toEqual([]);
+    expect(parseUserListField('{"a":1}')).toEqual([]);
+    expect(parseUserListField(42)).toEqual([]);
+  });
+});
+
+describe("stripHtmlPreview (rich-text cell previews, desk strip_html parity)", () => {
+  it("strips Text Editor markup down to its text", () => {
+    expect(stripHtmlPreview('<div class="ql-editor read-mode"><p>Call the vendor</p></div>')).toBe(
+      "Call the vendor",
+    );
+  });
+
+  it("collapses tags and entities into single spaces", () => {
+    expect(stripHtmlPreview("<p>a</p><p>b&nbsp;c</p>")).toBe("a b c");
+    expect(stripHtmlPreview("x &amp; y &lt;z&gt;")).toBe("x & y <z>");
+  });
+
+  it("passes plain text through untouched (fast path)", () => {
+    expect(stripHtmlPreview("plain description")).toBe("plain description");
+  });
+});
+
+describe("parseTagsField (_user_tags comma-joined column)", () => {
+  it("parses the bench shape: leading-comma joined tags", () => {
+    expect(parseTagsField(",Urgent,Follow Up")).toEqual(["Urgent", "Follow Up"]);
+  });
+
+  it("trims whitespace and drops empty segments", () => {
+    expect(parseTagsField(" ,  a , ,b, ")).toEqual(["a", "b"]);
+  });
+
+  it("returns [] for empty or non-string values", () => {
+    expect(parseTagsField("")).toEqual([]);
+    expect(parseTagsField(null)).toEqual([]);
+    expect(parseTagsField(undefined)).toEqual([]);
+    expect(parseTagsField(["a"])).toEqual([]);
+  });
+});

package/src/list/listFormat.ts

@@ -0,0 +1,80 @@
+// Cross-platform display helpers for list cells — frappe datetimes like
+// "2026-08-12 08:50:24.691936". Formatting routes through the house date
+// channel (LC-12 DATA-REGISTER-CHANNEL): one formatter owns each register,
+// this module only parses the frappe wire format and picks the register.
+import { formatAbsoluteDate, formatRelativeTimestamp } from "@multiplatform.one/theme";
+
+/** Parse a frappe date/datetime string into a Date (undefined when invalid). */
+export function parseFrappeDate(value: string): Date | undefined {
+  // "YYYY-MM-DD HH:mm:ss.SSSSSS" → ISO-ish so JSC/Hermes parse it too.
+  const isoish = value.includes(" ") ? value.replace(" ", "T") : value;
+  const date = new Date(isoish);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+/**
+ * Table date cell — the house compact-absolute display register
+ * ("Aug 12" / "Jul 1, 2025", current year elided). Raw ISO wire format
+ * never reaches the cell (LC-12); unparseable input passes through.
+ * The STRING (not a parsed Date) rides into the channel so its date-only
+ * UTC branch engages — a parsed "YYYY-MM-DD" would shift a day in
+ * negative-offset timezones.
+ */
+export function formatDateCell(value: string, now?: Date): string {
+  if (!parseFrappeDate(value)) return value;
+  const isoish = value.includes(" ") ? value.replace(" ", "T") : value;
+  return formatAbsoluteDate(isoish, now ? { now } : undefined);
+}
+
+/**
+ * Recency column ("Last Updated On") — the house relative register
+ * ("just now", "5m ago", "2h ago", "2mo ago"). One voice, unambiguous
+ * units (LC-12); unparseable input passes through.
+ */
+export function formatTimeAgo(value: string, now: Date = new Date()): string {
+  const date = parseFrappeDate(value);
+  if (!date) return value;
+  return formatRelativeTimestamp(date, now.getTime());
+}
+
+/**
+ * Plain-text preview of rich/HTML field content for list cells (desk
+ * `strip_html` parity): tags dropped, entities collapsed, whitespace
+ * normalized. A Text Editor value like `<div class="ql-editor"><p>Call the
+ * vendor</p></div>` renders as "Call the vendor" — markup never paints in
+ * a one-line cell (LC-06/LC-10 containment; cell-containment rule candidate).
+ */
+export function stripHtmlPreview(value: string): string {
+  if (!value.includes("<") && !value.includes("&")) return value;
+  return value
+    .replace(/<[^>]*>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&#39;|&apos;/gi, "'")
+    .replace(/&quot;/gi, '"')
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Parse frappe's `_assign` / `_liked_by` JSON-array-string columns. */
+export function parseUserListField(value: unknown): string[] {
+  if (Array.isArray(value)) return value.map(String);
+  if (typeof value !== "string" || !value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Parse frappe's `_user_tags` comma-joined column (",a,b" → ["a","b"]). */
+export function parseTagsField(value: unknown): string[] {
+  if (typeof value !== "string") return [];
+  return value
+    .split(",")
+    .map((tag) => tag.trim())
+    .filter(Boolean);
+}