@multiplatform.one/backoffice 6.4.2 → 6.6.0

package/src/form/timeline-entries.tsx

@@ -0,0 +1,377 @@
+// Maps a docinfo payload into the flat, newest-first feed FormTimeline
+// renders: comments, versions (edits), communications, automated messages,
+// and assignment/attachment/like/info logs. Row shapes verified against the
+// live bench (get_docinfo):
+//   comments  → { name, creation, content, owner, comment_type }
+//   versions  → { name, owner, creation, data } with data a JSON string
+//               { changed: [[field, old, new]], added, removed, row_changed }
+//   user_info → { [user]: { fullname, image, name, email } }
+// The input types are deliberately structural ("docinfo-like") so both the
+// shared useDocinfo payload and form-core's typed docinfo satisfy them.
+import type { TimelineEntry } from "@multiplatform.one/components";
+import { htmlToText, humanizeFieldname, parseFrappeDate, truncateText } from "./timeline-utils";
+
+/** Any docinfo row — fields are unknown and validated at map time. */
+export interface TimelineRowLike {
+  name?: unknown;
+  creation?: unknown;
+  owner?: unknown;
+  content?: unknown;
+  /** Version rows: JSON diff string */
+  data?: unknown;
+  /** Communication rows */
+  sender?: unknown;
+  sender_full_name?: unknown;
+  subject?: unknown;
+  communication_date?: unknown;
+}
+
+export interface TimelineUserInfoLike {
+  fullname?: unknown;
+  image?: unknown;
+  name?: unknown;
+  email?: unknown;
+}
+
+/** Structural docinfo shape the timeline can render. */
+export interface TimelineDocinfoLike {
+  user_info?: Record<string, TimelineUserInfoLike | undefined>;
+  comments?: readonly TimelineRowLike[];
+  versions?: readonly TimelineRowLike[];
+  communications?: readonly TimelineRowLike[];
+  automated_messages?: readonly TimelineRowLike[];
+  assignment_logs?: readonly TimelineRowLike[];
+  attachment_logs?: readonly TimelineRowLike[];
+  like_logs?: readonly TimelineRowLike[];
+  info_logs?: readonly TimelineRowLike[];
+}
+
+export type TimelineFeedKind =
+  | "comment"
+  | "version"
+  | "communication"
+  | "automated"
+  | "assignment"
+  | "attachment"
+  | "like"
+  | "info";
+
+/** Desk-parity filter tabs: All / Comments / Edits. */
+export type TimelineFilterValue = "all" | "comments" | "edits";
+
+export interface VersionFieldChange {
+  field: string;
+  from?: string;
+  to?: string;
+}
+
+export interface ParsedVersionData {
+  changed: VersionFieldChange[];
+  /** Child-table fieldnames with added rows */
+  added: string[];
+  /** Child-table fieldnames with removed rows */
+  removed: string[];
+  /** Child-table fieldnames with edited rows */
+  rowChanged: string[];
+}
+
+export interface TimelineFeedEntry extends TimelineEntry {
+  kind: TimelineFeedKind;
+  /** Source document name (Comment name for update/delete RPCs) */
+  docname: string;
+  /** Owning user id — own-comment check for edit/delete */
+  ownerId?: string;
+  /** Resolved avatar image URL */
+  image?: string;
+  /** Original comment HTML (edit prefill) */
+  html?: string;
+  /** Communication subject line */
+  subject?: string;
+  /** Parsed version diff (undefined when data was malformed) */
+  version?: ParsedVersionData;
+  /** Epoch millis used for the newest-first sort */
+  epoch: number;
+}
+
+interface BuildOptions {
+  /** docinfo.user_info — resolves fullname/avatar for owners and senders */
+  userInfo?: Record<string, TimelineUserInfoLike | undefined>;
+  /** Frappe base URL for resolving relative avatar paths ("/files/…") */
+  baseURL?: string;
+}
+
+// ── small helpers ──────────────────────────────────────────────────────────
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined;
+}
+
+function resolveImage(image: string | undefined, baseURL?: string): string | undefined {
+  if (!image) return undefined;
+  if (/^(https?:)?\/\//.test(image) || image.startsWith("data:")) return image;
+  if (!baseURL) return image;
+  return `${baseURL.replace(/\/+$/, "")}${image.startsWith("/") ? "" : "/"}${image}`;
+}
+
+interface AuthorFields {
+  author: string;
+  authorName?: string;
+  authorEmail?: string;
+  image?: string;
+}
+
+function authorFields(userId: string | undefined, options: BuildOptions): AuthorFields {
+  const info = userId ? options.userInfo?.[userId] : undefined;
+  return {
+    author: userId ?? "unknown",
+    authorName: str(info?.fullname),
+    authorEmail: str(info?.email),
+    image: resolveImage(str(info?.image), options.baseURL),
+  };
+}
+
+interface TimestampFields {
+  timestamp: string;
+  epoch: number;
+}
+
+function timestampFields(raw: unknown): TimestampFields {
+  const date = parseFrappeDate(raw);
+  return {
+    // ISO keeps downstream Date() parsing safe on every JS engine
+    timestamp: date ? date.toISOString() : (str(raw) ?? ""),
+    epoch: date?.getTime() ?? 0,
+  };
+}
+
+function displayValue(value: unknown): string | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value === "object") {
+    try {
+      return truncateText(JSON.stringify(value));
+    } catch {
+      return undefined;
+    }
+  }
+  const text = String(value).trim();
+  return text ? truncateText(text) : undefined;
+}
+
+// ── version data parsing ───────────────────────────────────────────────────
+
+/**
+ * Parse a Version doc's `data` JSON string defensively — malformed or empty
+ * payloads yield undefined and render as a plain "made changes" row.
+ */
+export function parseVersionData(data: unknown): ParsedVersionData | undefined {
+  if (typeof data !== "string" || !data) return undefined;
+  let parsed: Record<string, unknown>;
+  try {
+    const raw: unknown = JSON.parse(data);
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+    parsed = raw as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+  const changed: VersionFieldChange[] = [];
+  if (Array.isArray(parsed.changed)) {
+    for (const row of parsed.changed) {
+      if (!Array.isArray(row) || row.length === 0) continue;
+      const field = str(row[0]);
+      if (!field) continue;
+      changed.push({ field, from: displayValue(row[1]), to: displayValue(row[2]) });
+    }
+  }
+  const tableFields = (value: unknown): string[] => {
+    if (!Array.isArray(value)) return [];
+    const fields = value
+      .filter((row): row is unknown[] => Array.isArray(row) && row.length > 0)
+      .map((row) => str(row[0]))
+      .filter((field): field is string => Boolean(field));
+    return [...new Set(fields)];
+  };
+  const added = tableFields(parsed.added);
+  const removed = tableFields(parsed.removed);
+  const rowChanged = tableFields(parsed.row_changed);
+  if (!changed.length && !added.length && !removed.length && !rowChanged.length) {
+    return undefined;
+  }
+  return { changed, added, removed, rowChanged };
+}
+
+export type TimelineTranslate = (
+  key: string,
+  options: { defaultValue: string } & Record<string, unknown>,
+) => string;
+
+/**
+ * Desk-parity version sentence: single field change reads
+ * "changed value of X from a to b"; multi-field and child-table changes
+ * collapse to field lists ("changed values for X, Y" / "added rows for Z").
+ */
+export function versionSummary(version: ParsedVersionData, translate: TimelineTranslate): string {
+  const parts: string[] = [];
+  const fieldList = (fields: string[]) => fields.map(humanizeFieldname).join(", ");
+  if (version.changed.length === 1) {
+    const change = version.changed[0];
+    const empty = translate("timeline.emptyValue", {
+      defaultValue: "(empty)",
+    });
+    parts.push(
+      translate("timeline.changedValue", {
+        defaultValue: "changed value of {{field}} from {{from}} to {{to}}",
+        field: humanizeFieldname(change.field),
+        from: change.from ?? empty,
+        to: change.to ?? empty,
+      }),
+    );
+  } else if (version.changed.length > 1) {
+    parts.push(
+      translate("timeline.changedValues", {
+        defaultValue: "changed values for {{fields}}",
+        fields: fieldList(version.changed.map((change) => change.field)),
+      }),
+    );
+  }
+  if (version.added.length) {
+    parts.push(
+      translate("timeline.addedRows", {
+        defaultValue: "added rows for {{fields}}",
+        fields: fieldList(version.added),
+      }),
+    );
+  }
+  if (version.removed.length) {
+    parts.push(
+      translate("timeline.removedRows", {
+        defaultValue: "removed rows for {{fields}}",
+        fields: fieldList(version.removed),
+      }),
+    );
+  }
+  if (version.rowChanged.length) {
+    parts.push(
+      translate("timeline.changedRows", {
+        defaultValue: "changed rows for {{fields}}",
+        fields: fieldList(version.rowChanged),
+      }),
+    );
+  }
+  return parts.join(", ");
+}
+
+// ── entry builders ─────────────────────────────────────────────────────────
+
+function commentEntry(row: TimelineRowLike, options: BuildOptions): TimelineFeedEntry | undefined {
+  const docname = str(row.name);
+  if (!docname) return undefined;
+  const html = str(row.content);
+  return {
+    id: `comment:${docname}`,
+    type: "comment",
+    kind: "comment",
+    docname,
+    ownerId: str(row.owner),
+    ...authorFields(str(row.owner), options),
+    ...timestampFields(row.creation),
+    content: htmlToText(html),
+    html,
+  };
+}
+
+function versionEntry(row: TimelineRowLike, options: BuildOptions): TimelineFeedEntry | undefined {
+  const docname = str(row.name);
+  if (!docname) return undefined;
+  return {
+    id: `version:${docname}`,
+    type: "version",
+    kind: "version",
+    docname,
+    ownerId: str(row.owner),
+    ...authorFields(str(row.owner), options),
+    ...timestampFields(row.creation),
+    version: parseVersionData(row.data),
+  };
+}
+
+function communicationEntry(
+  row: TimelineRowLike,
+  kind: "communication" | "automated",
+  options: BuildOptions,
+): TimelineFeedEntry | undefined {
+  const docname = str(row.name);
+  if (!docname) return undefined;
+  const sender = str(row.sender) ?? str(row.owner);
+  const fields = authorFields(sender, options);
+  return {
+    id: `${kind}:${docname}`,
+    type: "info",
+    kind,
+    docname,
+    ownerId: sender,
+    ...fields,
+    // Communication rows carry their own display name; prefer it
+    authorName: str(row.sender_full_name) ?? fields.authorName,
+    ...timestampFields(row.communication_date ?? row.creation),
+    subject: htmlToText(str(row.subject)),
+    content: htmlToText(str(row.content)),
+  };
+}
+
+function logEntry(
+  row: TimelineRowLike,
+  kind: "assignment" | "attachment" | "like" | "info",
+  options: BuildOptions,
+): TimelineFeedEntry | undefined {
+  const docname = str(row.name);
+  if (!docname) return undefined;
+  const type: TimelineEntry["type"] =
+    kind === "assignment" ? "assignment" : kind === "attachment" ? "attachment" : "info";
+  return {
+    id: `${kind}:${docname}`,
+    type,
+    kind,
+    docname,
+    ownerId: str(row.owner),
+    ...authorFields(str(row.owner), options),
+    ...timestampFields(row.creation),
+    content: htmlToText(str(row.content)),
+  };
+}
+
+// ── public API ─────────────────────────────────────────────────────────────
+
+/** Merge every docinfo activity stream into one newest-first feed. */
+export function buildTimelineFeed(
+  docinfo: TimelineDocinfoLike | undefined,
+  options: BuildOptions = {},
+): TimelineFeedEntry[] {
+  if (!docinfo) return [];
+  const entries: TimelineFeedEntry[] = [];
+  const push = (entry: TimelineFeedEntry | undefined) => {
+    if (entry) entries.push(entry);
+  };
+  for (const row of docinfo.comments ?? []) push(commentEntry(row, options));
+  for (const row of docinfo.versions ?? []) push(versionEntry(row, options));
+  for (const row of docinfo.communications ?? []) {
+    push(communicationEntry(row, "communication", options));
+  }
+  for (const row of docinfo.automated_messages ?? []) {
+    push(communicationEntry(row, "automated", options));
+  }
+  for (const row of docinfo.assignment_logs ?? []) push(logEntry(row, "assignment", options));
+  for (const row of docinfo.attachment_logs ?? []) push(logEntry(row, "attachment", options));
+  for (const row of docinfo.like_logs ?? []) push(logEntry(row, "like", options));
+  for (const row of docinfo.info_logs ?? []) push(logEntry(row, "info", options));
+  return entries.sort((a, b) => b.epoch - a.epoch);
+}
+
+/** Apply the All / Comments / Edits filter tabs. */
+export function filterTimelineFeed(
+  entries: TimelineFeedEntry[],
+  filter: TimelineFilterValue,
+): TimelineFeedEntry[] {
+  if (filter === "comments") return entries.filter((entry) => entry.kind === "comment");
+  if (filter === "edits") return entries.filter((entry) => entry.kind === "version");
+  return entries;
+}

package/src/form/timeline-utils.tsx

@@ -0,0 +1,235 @@
+// Cross-platform helpers for the form activity timeline: frappe datetime
+// parsing (bench sends naive "YYYY-MM-DD HH:mm:ss.ffffff" strings that
+// JSC/Hermes will not parse natively), a relative-time register, safe
+// HTML → plain-text conversion (no DOM APIs and no raw-HTML rendering on
+// any platform), plain text → comment HTML for the desk RPCs, and the
+// cached session-user lookup shared by every timeline instance.
+import type { FrappeApp } from "@multiplatform.one/frappe";
+import { useEffect, useState } from "react";
+import { useFrappeApp } from "../shared/useFrappeApp";
+
+// ── frappe datetime parsing ────────────────────────────────────────────────
+
+const FRAPPE_DATETIME =
+  /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?(?:\.(\d+))?(Z)?)?$/;
+
+/**
+ * Parse a frappe datetime ("2026-08-12 09:35:11.836712", date-only, or ISO)
+ * into a Date. Bench datetimes are naive site-local time, so date parts are
+ * constructed in local time; a trailing `Z` is honored as UTC. Returns
+ * undefined for unparseable input (honest passthrough happens at render).
+ */
+export function parseFrappeDate(value: unknown): Date | undefined {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? undefined : value;
+  }
+  if (typeof value === "number") {
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : date;
+  }
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  const match = value.trim().match(FRAPPE_DATETIME);
+  if (match) {
+    const [, year, month, day, hour, minute, second, fraction, utc] = match;
+    const ms = fraction ? Math.round(Number(`0.${fraction}`) * 1000) : 0;
+    if (utc) {
+      return new Date(
+        Date.UTC(
+          Number(year),
+          Number(month) - 1,
+          Number(day),
+          Number(hour ?? 0),
+          Number(minute ?? 0),
+          Number(second ?? 0),
+          ms,
+        ),
+      );
+    }
+    return new Date(
+      Number(year),
+      Number(month) - 1,
+      Number(day),
+      Number(hour ?? 0),
+      Number(minute ?? 0),
+      Number(second ?? 0),
+      ms,
+    );
+  }
+  const native = new Date(value);
+  return Number.isNaN(native.getTime()) ? undefined : native;
+}
+
+/** Epoch millis for sorting; unparseable input sorts last (0). */
+export function frappeDateEpoch(value: unknown): number {
+  return parseFrappeDate(value)?.getTime() ?? 0;
+}
+
+/**
+ * Relative timestamp in the house feed register ("just now", "5m ago",
+ * "2h ago", "3 days ago", "2mo ago", "1y ago") on top of frappe-safe
+ * parsing. Unparseable strings pass through unchanged.
+ */
+export function formatRelativeTime(value: unknown, now: number = Date.now()): string {
+  const date = parseFrappeDate(value);
+  if (!date) return typeof value === "string" ? value : "";
+  const sec = Math.floor(Math.max(0, now - date.getTime()) / 1000);
+  if (sec < 60) return "just now";
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day = Math.floor(hr / 24);
+  if (day < 30) return `${day} day${day === 1 ? "" : "s"} ago`;
+  const mo = Math.floor(day / 30);
+  if (mo < 12) return `${mo}mo ago`;
+  const yr = Math.floor(day / 365);
+  return `${Math.max(1, yr)}y ago`;
+}
+
+// ── HTML ↔ text ────────────────────────────────────────────────────────────
+
+function codePointToChar(code: number): string {
+  if (!Number.isFinite(code) || code < 0 || code > 0x10ffff) return "";
+  try {
+    return String.fromCodePoint(code);
+  } catch {
+    return "";
+  }
+}
+
+function decodeEntities(text: string): string {
+  return text
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex: string) => codePointToChar(Number.parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, dec: string) => codePointToChar(Number.parseInt(dec, 10)))
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/gi, "'")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&amp;/gi, "&");
+}
+
+/**
+ * Strip HTML down to display text without touching a DOM (works on web,
+ * iOS/Android, and GTK alike). Block ends and <br> become newlines, list
+ * items get a bullet, script/style/comment bodies are dropped, and common
+ * entities are decoded. The result renders only as plain <Text> content —
+ * markup from the server is never re-emitted as markup.
+ */
+export function htmlToText(html: string | null | undefined): string {
+  if (!html) return "";
+  let text = String(html).replace(/\r\n?/g, "\n");
+  text = text.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, "");
+  text = text.replace(/<!--[\s\S]*?-->/g, "");
+  text = text.replace(/<br\s*\/?>/gi, "\n");
+  text = text.replace(/<li\b[^>]*>/gi, "\n• ");
+  text = text.replace(/<\/(p|div|li|tr|h[1-6]|blockquote|pre|table|ul|ol)\s*>/gi, "\n");
+  text = text.replace(/<[^>]+>/g, "");
+  text = decodeEntities(text);
+  text = text.replace(/\u00a0/g, " ");
+  text = text
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+  return text;
+}
+
+/** Escape text for embedding inside HTML (comment payloads). */
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * Desk sends comment content as HTML; encode the plain composer text the
+ * same way (escaped, newlines as <br>, wrapped in one div) so the payload
+ * matches what `frappe.desk.form.utils.add_comment` expects.
+ */
+export function textToCommentHtml(text: string): string {
+  return `<div>${escapeHtml(text.trim()).replace(/\n/g, "<br>")}</div>`;
+}
+
+/** Truncate display text with an ellipsis (version values, error copy). */
+export function truncateText(text: string, max = 50): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** "sales_order_item" → "Sales Order Item" (no meta available here). */
+export function humanizeFieldname(fieldname: string): string {
+  return (
+    fieldname
+      .split(/[_\s]+/)
+      .filter(Boolean)
+      .map((word) => word[0].toUpperCase() + word.slice(1))
+      .join(" ") || fieldname
+  );
+}
+
+// ── session user ───────────────────────────────────────────────────────────
+
+interface SessionUserEntry {
+  promise: Promise<string>;
+  value?: string;
+}
+
+// Keyed by FrappeApp instance (useFrappeApp memoizes per connection config),
+// so every timeline on a page shares one get_logged_user round trip.
+const sessionUserCache = new WeakMap<FrappeApp, SessionUserEntry>();
+
+/**
+ * Session user via `frappe.auth.get_logged_user`, cached per FrappeApp.
+ * Drives the own-comment edit/delete affordances and the add_comment
+ * payload (`comment_email` / `comment_by`).
+ */
+export function useSessionUser(enabled = true): string | undefined {
+  const app = useFrappeApp();
+  const [user, setUser] = useState<string | undefined>(() =>
+    enabled && app ? sessionUserCache.get(app)?.value : undefined,
+  );
+
+  useEffect(() => {
+    if (!app || !enabled) return;
+    let entry = sessionUserCache.get(app);
+    if (!entry) {
+      const promise = app
+        .call()
+        .get<{ message?: string }>("frappe.auth.get_logged_user")
+        .then((res) => {
+          const value = res.payload?.message;
+          if (typeof value !== "string" || !value) {
+            throw new Error("No logged user returned");
+          }
+          return value;
+        });
+      const created: SessionUserEntry = { promise };
+      entry = created;
+      sessionUserCache.set(app, created);
+      promise
+        .then((value) => {
+          if (sessionUserCache.get(app) === created) created.value = value;
+        })
+        .catch(() => {
+          // allow a retry on the next mount instead of caching the failure
+          if (sessionUserCache.get(app) === created) sessionUserCache.delete(app);
+        });
+    }
+    let cancelled = false;
+    entry.promise
+      .then((value) => {
+        if (!cancelled) setUser(value);
+      })
+      .catch(() => {
+        // stay undefined; composer simply hides until a session is known
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [app, enabled]);
+
+  return user;
+}