@multiplatform.one/backoffice 6.4.0 → 6.4.2

package/src/workspace/parseContent.spec.ts

@@ -0,0 +1,327 @@
+/**
+ * parseContent — workspace content-block JSON parsing, HTML stripping,
+ * link grouping, and frappe filter-string normalization. Filter fixtures
+ * are the bench-verified shapes documented in the module header and
+ * p-results/backoffice/integration-notes.md (dicts for stats_filter /
+ * quick_list_filter, doctype-prefixed quads for Number Card filters_json).
+ */
+import { describe, expect, it } from "vitest";
+import {
+  composeWorkspaceBlocks,
+  findLinkGroup,
+  findShortcut,
+  groupLinks,
+  headerLevel,
+  parseFrappeFilters,
+  parseWorkspaceContent,
+  stripHtml,
+} from "./parseContent";
+import type { WorkspaceBlock, WorkspaceDoc, WorkspaceLinkRow } from "./types";
+
+describe("parseWorkspaceContent", () => {
+  it("parses a desk-shaped block array", () => {
+    const content = JSON.stringify([
+      {
+        id: "abc123",
+        type: "header",
+        data: { text: '<span class="h4"><b>Your Shortcuts</b></span>', col: 12 },
+      },
+      { id: "def456", type: "shortcut", data: { shortcut_name: "User", col: 3 } },
+      { id: "ghi789", type: "card", data: { card_name: "Masters", col: 4 } },
+    ]);
+    const blocks = parseWorkspaceContent(content);
+    expect(blocks).toHaveLength(3);
+    expect(blocks[0].type).toBe("header");
+    expect(blocks[1].data.shortcut_name).toBe("User");
+    expect(blocks[2].data.card_name).toBe("Masters");
+  });
+
+  it("drops entries that are not blocks (null, scalars, missing type)", () => {
+    const content = JSON.stringify([
+      null,
+      "string",
+      42,
+      { id: "x", data: {} },
+      { id: "y", type: 5, data: {} },
+      { id: "z", type: "spacer", data: {} },
+    ]);
+    const blocks = parseWorkspaceContent(content);
+    expect(blocks).toHaveLength(1);
+    expect(blocks[0].id).toBe("z");
+  });
+
+  it("returns [] for empty, malformed, or non-array content", () => {
+    expect(parseWorkspaceContent(undefined)).toEqual([]);
+    expect(parseWorkspaceContent(null)).toEqual([]);
+    expect(parseWorkspaceContent("")).toEqual([]);
+    expect(parseWorkspaceContent("{not json")).toEqual([]);
+    expect(parseWorkspaceContent('{"type":"header"}')).toEqual([]);
+  });
+});
+
+describe("stripHtml", () => {
+  it("strips desk rich-text wrappers (documented example)", () => {
+    expect(stripHtml('<span class="h4"><b>Reports &amp; Masters</b></span>')).toBe(
+      "Reports & Masters",
+    );
+  });
+
+  it("decodes named entities", () => {
+    expect(stripHtml("&lt;tag&gt;")).toBe("<tag>");
+    expect(stripHtml("&quot;quoted&quot; &apos;s&apos;")).toBe("\"quoted\" 's'");
+    expect(stripHtml("a&nbsp;b")).toBe("a b");
+  });
+
+  it("decodes decimal and hex numeric entities", () => {
+    expect(stripHtml("&#65;&#66;")).toBe("AB");
+    expect(stripHtml("&#x41;&#x42;")).toBe("AB");
+  });
+
+  it("leaves unknown entities untouched", () => {
+    expect(stripHtml("&unknown;")).toBe("&unknown;");
+  });
+
+  it("converts <br> variants to newlines", () => {
+    expect(stripHtml("a<br>b")).toBe("a\nb");
+    expect(stripHtml("a<br/>b")).toBe("a\nb");
+    expect(stripHtml("a<br />b")).toBe("a\nb");
+  });
+
+  it("trims and handles empty input", () => {
+    expect(stripHtml("  <b> x </b>  ")).toBe("x");
+    expect(stripHtml("")).toBe("");
+    expect(stripHtml(null)).toBe("");
+    expect(stripHtml(undefined)).toBe("");
+  });
+});
+
+describe("headerLevel", () => {
+  it("reads the hN class from the wrapper", () => {
+    expect(headerLevel('<span class="h1">t</span>')).toBe(1);
+    expect(headerLevel('<span class="h2">t</span>')).toBe(2);
+    expect(headerLevel('<span class="h6">t</span>')).toBe(6);
+  });
+
+  it("finds hN among multiple classes (word boundary)", () => {
+    expect(headerLevel('<span class="ce-header h3 muted">t</span>')).toBe(3);
+  });
+
+  it("falls back to 4 for unclassed, styled, or missing input", () => {
+    expect(headerLevel("<b>plain</b>")).toBe(4);
+    expect(headerLevel('<span style="font-size: 18px">t</span>')).toBe(4);
+    expect(headerLevel('<span class="h7">t</span>')).toBe(4);
+    expect(headerLevel(null)).toBe(4);
+    expect(headerLevel(undefined)).toBe(4);
+  });
+});
+
+describe("groupLinks", () => {
+  const row = (partial: Partial<WorkspaceLinkRow> & { type: string; label: string }) =>
+    ({ name: partial.label, ...partial }) as WorkspaceLinkRow;
+
+  it("groups Link rows under the preceding Card Break", () => {
+    const groups = groupLinks([
+      row({ type: "Card Break", label: "Masters", link_count: 2 }),
+      row({ type: "Link", label: "User", link_type: "DocType", link_to: "User" }),
+      row({ type: "Link", label: "Role", link_type: "DocType", link_to: "Role" }),
+      row({ type: "Card Break", label: "Settings" }),
+      row({ type: "Link", label: "System Settings", link_to: "System Settings" }),
+    ]);
+    expect(groups).toHaveLength(2);
+    expect(groups[0].label).toBe("Masters");
+    expect(groups[0].breakRow.link_count).toBe(2);
+    expect(groups[0].links.map((l) => l.label)).toEqual(["User", "Role"]);
+    expect(groups[1].label).toBe("Settings");
+    expect(groups[1].links.map((l) => l.label)).toEqual(["System Settings"]);
+  });
+
+  it("drops hidden rows", () => {
+    const groups = groupLinks([
+      row({ type: "Card Break", label: "Masters" }),
+      row({ type: "Link", label: "Visible" }),
+      row({ type: "Link", label: "Hidden", hidden: 1 }),
+    ]);
+    expect(groups[0].links.map((l) => l.label)).toEqual(["Visible"]);
+  });
+
+  it("ignores Link rows before any Card Break (desk parity)", () => {
+    const groups = groupLinks([
+      row({ type: "Link", label: "Orphan" }),
+      row({ type: "Card Break", label: "Masters" }),
+      row({ type: "Link", label: "User" }),
+    ]);
+    expect(groups).toHaveLength(1);
+    expect(groups[0].links.map((l) => l.label)).toEqual(["User"]);
+  });
+
+  it("returns [] for undefined or empty links", () => {
+    expect(groupLinks(undefined)).toEqual([]);
+    expect(groupLinks([])).toEqual([]);
+  });
+});
+
+describe("parseFrappeFilters (bench-verified shapes)", () => {
+  it("normalizes a plain dict to = triples", () => {
+    expect(parseFrappeFilters('{"status":"Open"}')).toEqual([["status", "=", "Open"]]);
+    expect(parseFrappeFilters('{"enabled":1}')).toEqual([["enabled", "=", 1]]);
+  });
+
+  it("normalizes a dict of [op, value] tuples", () => {
+    expect(parseFrappeFilters('{"status":["=","Open"]}')).toEqual([["status", "=", "Open"]]);
+    expect(parseFrappeFilters('{"status":["in",["Open","Overdue"]]}')).toEqual([
+      ["status", "in", ["Open", "Overdue"]],
+    ]);
+  });
+
+  it("treats non-operator array values as = values", () => {
+    // 3-element array value is not an [op, value] tuple.
+    expect(parseFrappeFilters('{"role":["a","b","c"]}')).toEqual([["role", "=", ["a", "b", "c"]]]);
+  });
+
+  it("passes triples through as-is", () => {
+    expect(parseFrappeFilters('[["enabled","=",1]]')).toEqual([["enabled", "=", 1]]);
+  });
+
+  it("strips the doctype element from quads (Number Card filters_json)", () => {
+    expect(parseFrappeFilters('[["User","enabled","=",1]]')).toEqual([["enabled", "=", 1]]);
+    expect(
+      parseFrappeFilters('[["ToDo","status","=","Open"],["ToDo","priority","!=","Low"]]'),
+    ).toEqual([
+      ["status", "=", "Open"],
+      ["priority", "!=", "Low"],
+    ]);
+  });
+
+  it("handles mixed triples and quads, skipping malformed entries", () => {
+    expect(
+      parseFrappeFilters('[["status","=","Open"],["User","enabled","=",1],"junk",["short","="]]'),
+    ).toEqual([
+      ["status", "=", "Open"],
+      ["enabled", "=", 1],
+    ]);
+  });
+
+  it("returns undefined for empty, malformed, or valueless input", () => {
+    expect(parseFrappeFilters(undefined)).toBeUndefined();
+    expect(parseFrappeFilters(null)).toBeUndefined();
+    expect(parseFrappeFilters("")).toBeUndefined();
+    expect(parseFrappeFilters("{not json")).toBeUndefined();
+    expect(parseFrappeFilters("[]")).toBeUndefined();
+    expect(parseFrappeFilters("{}")).toBeUndefined();
+    expect(parseFrappeFilters('"scalar"')).toBeUndefined();
+    expect(parseFrappeFilters("[1,2]")).toBeUndefined();
+  });
+});
+
+describe("composeWorkspaceBlocks (dashboard-first, MOD-11)", () => {
+  const block = (type: string, data: Record<string, unknown>, id: string) =>
+    ({ id, type, data }) as WorkspaceBlock;
+
+  it("reorders by class: data (cards → charts → quick lists), shortcuts, cards", () => {
+    const composed = composeWorkspaceBlocks([
+      block("header", { text: '<span class="h4"><b>Your Shortcuts</b></span>' }, "h1"),
+      block("shortcut", { shortcut_name: "User" }, "s1"),
+      block("spacer", {}, "sp1"),
+      block("header", { text: '<span class="h4"><b>Reports &amp; Masters</b></span>' }, "h2"),
+      block("card", { card_name: "Users" }, "c1"),
+      block("quick_list", { quick_list_name: "ToDo" }, "q1"),
+      block("chart", { chart_name: "Signups" }, "ch1"),
+      block("number_card", { number_card_name: "Enabled Users" }, "n1"),
+    ]);
+    expect(composed.data.map((b) => b.id)).toEqual(["n1", "ch1", "q1"]);
+    expect(composed.shortcuts.map((b) => b.id)).toEqual(["s1"]);
+    expect(composed.cards.map((b) => b.id)).toEqual(["c1"]);
+    expect(composed.text).toEqual([]);
+  });
+
+  it("keeps authored order within each data class", () => {
+    const composed = composeWorkspaceBlocks([
+      block("chart", { chart_name: "B" }, "ch2"),
+      block("number_card", { number_card_name: "N1" }, "n1"),
+      block("chart", { chart_name: "A" }, "ch1"),
+      block("number_card", { number_card_name: "N2" }, "n2"),
+    ]);
+    expect(composed.data.map((b) => b.id)).toEqual(["n1", "n2", "ch2", "ch1"]);
+  });
+
+  it("drops headers that label widget runs, keeps text-only headers", () => {
+    const composed = composeWorkspaceBlocks([
+      // Welcome-Workspace shape: header + paragraph only → both kept.
+      block("header", { text: '<span class="h2">Hi,</span>' }, "keep"),
+      block("paragraph", { text: "You can create a workspace." }, "p1"),
+      // Section label directly over shortcuts → dropped.
+      block("header", { text: "<b>Your Shortcuts</b>" }, "drop1"),
+      block("shortcut", { shortcut_name: "User" }, "s1"),
+      // Label separated from its cards by a spacer → still dropped.
+      block("header", { text: "<b>Masters</b>" }, "drop2"),
+      block("spacer", {}, "sp"),
+      block("card", { card_name: "Users" }, "c1"),
+    ]);
+    expect(composed.text.map((b) => b.id)).toEqual(["keep", "p1"]);
+  });
+
+  it("keeps a trailing header with no following blocks", () => {
+    const composed = composeWorkspaceBlocks([
+      block("shortcut", { shortcut_name: "User" }, "s1"),
+      block("header", { text: "<b>Notes</b>" }, "h1"),
+    ]);
+    expect(composed.text.map((b) => b.id)).toEqual(["h1"]);
+  });
+
+  it("drops headers labeling onboarding/custom blocks (which never render)", () => {
+    const composed = composeWorkspaceBlocks([
+      block("header", { text: "<b>Getting Started</b>" }, "h1"),
+      block("onboarding", { onboarding_name: "Setup" }, "o1"),
+    ]);
+    expect(composed.text).toEqual([]);
+    expect(composed.data).toEqual([]);
+  });
+
+  it("drops spacers and unknown block types", () => {
+    const composed = composeWorkspaceBlocks([
+      block("spacer", {}, "sp1"),
+      block("custom_block", {}, "cb1"),
+      block("paragraph", { text: "kept" }, "p1"),
+    ]);
+    expect(composed.text.map((b) => b.id)).toEqual(["p1"]);
+    expect(composed.data).toEqual([]);
+    expect(composed.shortcuts).toEqual([]);
+    expect(composed.cards).toEqual([]);
+  });
+
+  it("returns all-empty sections for empty input", () => {
+    expect(composeWorkspaceBlocks([])).toEqual({
+      data: [],
+      shortcuts: [],
+      cards: [],
+      text: [],
+    });
+  });
+});
+
+describe("findShortcut / findLinkGroup", () => {
+  const doc: WorkspaceDoc = {
+    name: "Users",
+    doctype: "Workspace",
+    shortcuts: [
+      { name: "s1", type: "DocType", label: "User", link_to: "User" },
+      { name: "s2", type: "DocType", label: "Role", link_to: "Role" },
+    ],
+  };
+
+  it("finds shortcut rows by the block's shortcut_name (label match)", () => {
+    expect(findShortcut(doc, "Role")?.link_to).toBe("Role");
+    expect(findShortcut(doc, "Missing")).toBeUndefined();
+    expect(findShortcut(doc, undefined)).toBeUndefined();
+  });
+
+  it("finds link groups by the card block's card_name", () => {
+    const groups = groupLinks([
+      { name: "b1", type: "Card Break", label: "Masters" },
+      { name: "l1", type: "Link", label: "User" },
+    ]);
+    expect(findLinkGroup(groups, "Masters")?.links).toHaveLength(1);
+    expect(findLinkGroup(groups, "Nope")).toBeUndefined();
+    expect(findLinkGroup(groups, undefined)).toBeUndefined();
+  });
+});

package/src/workspace/parseContent.ts

@@ -0,0 +1,240 @@
+/**
+ * Pure parsing helpers for the Workspace `content` block JSON and the
+ * JSON filter strings carried by shortcuts / quick lists / number cards.
+ * No DOM: HTML in header/paragraph blocks is stripped with a regex-based
+ * text extractor so this runs on native and gjs too.
+ */
+import type {
+  FrappeFilterTuple,
+  WorkspaceBlock,
+  WorkspaceDoc,
+  WorkspaceLinkGroup,
+  WorkspaceLinkRow,
+} from "./types";
+
+/** Parse the workspace `content` JSON string into blocks (bad JSON → []). */
+export function parseWorkspaceContent(content: string | undefined | null): WorkspaceBlock[] {
+  if (!content) return [];
+  try {
+    const parsed = JSON.parse(content);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (block): block is WorkspaceBlock =>
+        !!block && typeof block === "object" && typeof block.type === "string",
+    );
+  } catch {
+    return [];
+  }
+}
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+};
+
+/**
+ * Extract plain text from desk's rich-text wrappers, e.g.
+ * `<span class="h4"><b>Reports &amp; Masters</b></span>` → "Reports & Masters".
+ */
+export function stripHtml(html: string | undefined | null): string {
+  if (!html) return "";
+  const withoutTags = html.replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]*>/g, "");
+  return withoutTags
+    .replace(/&(#[xX]?[0-9a-fA-F]+|[a-zA-Z]+);/g, (match, entity: string) => {
+      if (entity.startsWith("#x") || entity.startsWith("#X")) {
+        const code = Number.parseInt(entity.slice(2), 16);
+        return Number.isNaN(code) ? match : String.fromCodePoint(code);
+      }
+      if (entity.startsWith("#")) {
+        const code = Number.parseInt(entity.slice(1), 10);
+        return Number.isNaN(code) ? match : String.fromCodePoint(code);
+      }
+      return NAMED_ENTITIES[entity.toLowerCase()] ?? match;
+    })
+    .trim();
+}
+
+/**
+ * Heading level from a desk header block's HTML wrapper: `class="h4"` →
+ * 4. Desk also emits raw font-size styles (Build workspace uses
+ * `font-size: 18px`); those and unclassed headers fall back to 4 — the
+ * visual scale desk uses for workspace section headings.
+ */
+export function headerLevel(html: string | undefined | null): 1 | 2 | 3 | 4 | 5 | 6 {
+  const match = (html ?? "").match(/class="[^"]*\bh([1-6])\b[^"]*"/);
+  if (match) return Number(match[1]) as 1 | 2 | 3 | 4 | 5 | 6;
+  return 4;
+}
+
+/**
+ * Group the flat `links` child table into cards: each "Card Break" row
+ * opens a group that collects the following "Link" rows (hidden rows are
+ * dropped). Link rows before any Card Break are ignored — desk does the
+ * same (they are unreachable from card blocks).
+ */
+export function groupLinks(links: WorkspaceLinkRow[] | undefined): WorkspaceLinkGroup[] {
+  const groups: WorkspaceLinkGroup[] = [];
+  let current: WorkspaceLinkGroup | undefined;
+  for (const row of links ?? []) {
+    if (row.type === "Card Break") {
+      // A hidden Card Break hides its whole card: close the current group so
+      // its following Link rows are dropped, not leaked into the prior card.
+      if (row.hidden) {
+        current = undefined;
+        continue;
+      }
+      current = { label: row.label, breakRow: row, links: [] };
+      groups.push(current);
+    } else if (row.type === "Link" && current && !row.hidden) {
+      current.links.push(row);
+    }
+  }
+  return groups;
+}
+
+/**
+ * Normalize a frappe JSON filter string to `[field, op, value]` triples.
+ * Real-world shapes (all seen on the control bench):
+ * - dict: `{"status":"Open"}` → `[["status","=","Open"]]`
+ * - dict of tuples: `{"status":["=","Open"]}` → `[["status","=","Open"]]`
+ * - list of triples: `[["enabled","=",1]]` → as-is
+ * - list of quads (doctype-prefixed, Number Card `filters_json`):
+ *   `[["User","enabled","=",1]]` → doctype element stripped.
+ */
+export function parseFrappeFilters(
+  raw: string | undefined | null,
+): FrappeFilterTuple[] | undefined {
+  if (!raw) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (Array.isArray(parsed)) {
+    const tuples: FrappeFilterTuple[] = [];
+    for (const entry of parsed) {
+      if (!Array.isArray(entry)) continue;
+      if (entry.length >= 4) {
+        // [doctype, field, op, value] — drop the doctype element.
+        tuples.push([String(entry[1]), String(entry[2]), entry[3]]);
+      } else if (entry.length === 3) {
+        tuples.push([String(entry[0]), String(entry[1]), entry[2]]);
+      }
+    }
+    return tuples.length > 0 ? tuples : undefined;
+  }
+  if (parsed && typeof parsed === "object") {
+    const tuples: FrappeFilterTuple[] = [];
+    for (const [field, value] of Object.entries(parsed as Record<string, unknown>)) {
+      if (Array.isArray(value) && value.length === 2 && typeof value[0] === "string") {
+        tuples.push([field, value[0], value[1]]);
+      } else {
+        tuples.push([field, "=", value]);
+      }
+    }
+    return tuples.length > 0 ? tuples : undefined;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Dashboard-first composition (MOD-11)
+// ---------------------------------------------------------------------------
+
+/**
+ * Workspace blocks partitioned by class for the dashboard-first layout:
+ * data widgets render first, then shortcuts, then the link-card directory.
+ */
+export interface WorkspaceComposition {
+  /**
+   * Live data widgets, ordered number cards → charts → quick lists
+   * (authored order within each class).
+   */
+  data: WorkspaceBlock[];
+  /** Shortcut blocks in authored order. */
+  shortcuts: WorkspaceBlock[];
+  /** Link-card blocks in authored order. */
+  cards: WorkspaceBlock[];
+  /**
+   * Narrative content in authored order: paragraphs, plus headers that do
+   * NOT label a widget run (see keep rule below). Section-label headers
+   * ("Your Shortcuts", "Reports & Masters") are dropped — the recomposed
+   * sections carry their own canonical headings.
+   */
+  text: WorkspaceBlock[];
+}
+
+const DATA_BLOCK_RANK: Record<string, number> = { number_card: 0, chart: 1, quick_list: 2 };
+
+function isDataBlock(block: WorkspaceBlock): boolean {
+  return block.type in DATA_BLOCK_RANK;
+}
+
+/**
+ * Partition parsed content blocks for the dashboard-first workspace layout
+ * (data → shortcuts → link cards), instead of desk's authoring order.
+ *
+ * Header keep rule: a header labels the blocks that follow it up to the next
+ * header. If that run contains any widget block (shortcut, card, chart,
+ * number card, quick list, onboarding, custom block), the header is a section
+ * label and is dropped; if the run holds only paragraphs (or nothing — e.g.
+ * the text-only "Welcome Workspace"), the header is real content and is kept.
+ * Spacers are dropped — section spacing owns the rhythm.
+ */
+export function composeWorkspaceBlocks(blocks: WorkspaceBlock[]): WorkspaceComposition {
+  const shortcuts: WorkspaceBlock[] = [];
+  const cards: WorkspaceBlock[] = [];
+  const text: WorkspaceBlock[] = [];
+  const dataBlocks: WorkspaceBlock[] = [];
+
+  for (const [index, block] of blocks.entries()) {
+    if (isDataBlock(block)) {
+      dataBlocks.push(block);
+    } else if (block.type === "shortcut") {
+      shortcuts.push(block);
+    } else if (block.type === "card") {
+      cards.push(block);
+    } else if (block.type === "paragraph") {
+      text.push(block);
+    } else if (block.type === "header") {
+      let labelsWidgets = false;
+      for (const following of blocks.slice(index + 1)) {
+        if (following.type === "header") break;
+        if (following.type === "paragraph" || following.type === "spacer") continue;
+        labelsWidgets = true;
+        break;
+      }
+      if (!labelsWidgets) text.push(block);
+    }
+    // spacer / onboarding / custom_block / unknown — dropped (see module doc).
+  }
+
+  // Stable class ordering: number cards → charts → quick lists.
+  const data = dataBlocks
+    .map((block, index) => ({ block, index }))
+    .sort(
+      (a, b) =>
+        (DATA_BLOCK_RANK[a.block.type] ?? 0) - (DATA_BLOCK_RANK[b.block.type] ?? 0) ||
+        a.index - b.index,
+    )
+    .map(({ block }) => block);
+
+  return { data, shortcuts, cards, text };
+}
+
+/** Find a workspace shortcut row by a shortcut block's `shortcut_name`. */
+export function findShortcut(doc: WorkspaceDoc, shortcutName: string | undefined) {
+  if (!shortcutName) return undefined;
+  return doc.shortcuts?.find((row) => row.label === shortcutName);
+}
+
+/** Find a link group by a card block's `card_name`. */
+export function findLinkGroup(groups: WorkspaceLinkGroup[], cardName: string | undefined) {
+  if (!cardName) return undefined;
+  return groups.find((group) => group.label === cardName);
+}