@multiplatform.one/backoffice 6.3.0 → 6.4.1

package/src/workspace/WorkspaceShortcut.tsx

@@ -0,0 +1,223 @@
+/**
+ * Workspace shortcut chip — compact chip rendering for the `shortcut`
+ * content block (MOD-11): type icon + label + live count pill in a ~44px
+ * self-sized chip, laid out as a wrapping band by WorkspaceScreen (not
+ * grid-stretched cards).
+ *
+ * DocType shortcuts show a live count (respecting `stats_filter`) via the
+ * shared realtime aggregate and navigate to the doctype list. Report and
+ * Page shortcuts navigate into the backoffice slug router (best-effort —
+ * see the navigation notes on `resolveShortcutTarget`). URL shortcuts open
+ * via the platform-split openUrl (web new tab / native Linking / GNOME Gio).
+ *
+ * Rendering gates: chips targeting doctypes outside the provider's
+ * `doctypes` scope render nothing, and DocType/Report chips (list-surface
+ * navigations) render nothing when the `views` capability is off.
+ */
+import {
+  ArrowSquareOutIcon,
+  BrowserIcon,
+  ChartBarIcon,
+  GaugeIcon,
+  ListBulletsIcon,
+  SquaresFourIcon,
+  type Icon,
+} from "@phosphor-icons/react";
+import {
+  Card,
+  SizableText,
+  Skeleton,
+  XStack,
+  YStack,
+  useTheme,
+} from "@multiplatform.one/components";
+import { useFrappeAggregate, useFrappeConfig } from "@multiplatform.one/frappe-ui";
+import { openUrl } from "@multiplatform.one/platform";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  useBackofficeCapabilities,
+  useBackofficeNavigator,
+  useBackofficePaths,
+  useIsDoctypeAllowed,
+} from "../config/BackofficeProvider";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import { createBackofficePaths, type BackofficePaths } from "../navigation/paths";
+import { parseFrappeFilters } from "./parseContent";
+import type { WorkspaceShortcutRow } from "./types";
+
+const defaultPaths = createBackofficePaths();
+
+/**
+ * Resolve a shortcut press to a router path (or an external URL) —
+ * basePath-aware when the provider's `paths` are passed; defaults to the
+ * canonical "/backoffice".
+ *
+ * - DocType → paths.list(link_to)
+ * - Report → paths.list(link_to): there is no query-report route yet, so the
+ *   report slug goes through the runtime slug resolver (documented gap).
+ * - Page → `{base}/<link_to>` (frappe page names are already slugs,
+ *   e.g. "permission-manager"); resolution is up to the slug router.
+ * - Dashboard → no dashboard-view route yet → disabled (documented gap).
+ * - URL → external, opened through the platform openUrl.
+ */
+export function resolveShortcutTarget(
+  row: WorkspaceShortcutRow,
+  paths: BackofficePaths = defaultPaths,
+): {
+  path?: string;
+  externalUrl?: string;
+  disabled?: boolean;
+} {
+  const target = row.link_to || row.url || "";
+  const prefix = paths.base === "/" ? "" : paths.base;
+  switch (row.type) {
+    case "DocType":
+      return { path: paths.list(target) };
+    case "Report":
+      return { path: paths.list(target) };
+    case "Page":
+      return { path: `${prefix}/${target}` };
+    case "URL":
+      return { externalUrl: row.url || row.link_to };
+    default:
+      // "Dashboard" and unknown types have no backoffice route yet.
+      return { disabled: true };
+  }
+}
+
+export interface WorkspaceShortcutProps {
+  row: WorkspaceShortcutRow;
+  /** Override the default navigation/open behavior for this chip. */
+  onPress?: (row: WorkspaceShortcutRow) => void;
+}
+
+/** Leading chip glyph per shortcut target type. */
+const TYPE_ICONS: Record<string, Icon> = {
+  DocType: ListBulletsIcon,
+  Report: ChartBarIcon,
+  Page: BrowserIcon,
+  Dashboard: GaugeIcon,
+  URL: ArrowSquareOutIcon,
+};
+
+export function WorkspaceShortcut({ row, onPress }: WorkspaceShortcutProps) {
+  const navigator = useBackofficeNavigator();
+  const paths = useBackofficePaths();
+  const config = useFrappeConfig();
+  const { knobProps } = useResolvedKnobs();
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const theme = useTheme();
+  const { views } = useBackofficeCapabilities();
+  const isDoctypeAllowed = useIsDoctypeAllowed();
+  // Phosphor icons take a resolved color string, not a tamagui token —
+  // read the theme value so native/GTK get a real color (not a CSS var).
+  const iconColor = typeof theme.color11?.val === "string" ? theme.color11.val : undefined;
+
+  const isDoctype = row.type === "DocType" && !!row.link_to;
+  const filters = useMemo(() => parseFrappeFilters(row.stats_filter), [row.stats_filter]);
+
+  const connection = useMemo(
+    () =>
+      config?.baseURL || config?.fixtures
+        ? {
+            baseURL: config.baseURL,
+            socketPort: config.socketPort,
+            auth: config.auth,
+            syncOptions: config.syncOptions,
+            fixtures: config.fixtures,
+          }
+        : undefined,
+    [config],
+  );
+
+  // Visibility gates (before any early return — hooks above stay stable).
+  const hiddenByScope = isDoctype && row.link_to ? !isDoctypeAllowed(row.link_to) : false;
+  const hiddenByViews = (row.type === "DocType" || row.type === "Report") && !views.enabled;
+
+  const {
+    value: count,
+    isLoading: countLoading,
+    error: countError,
+  } = useFrappeAggregate(connection, {
+    doctype: row.link_to ?? "",
+    filters,
+    enabled: isDoctype && !!connection && !hiddenByScope && !hiddenByViews,
+  });
+
+  if (hiddenByScope || hiddenByViews) return null;
+
+  const target = resolveShortcutTarget(row, paths);
+
+  const handlePress = () => {
+    if (onPress) {
+      onPress(row);
+      return;
+    }
+    if (target.path) {
+      navigator.navigate(target.path);
+      return;
+    }
+    if (target.externalUrl) {
+      // Platform-split: new tab on web, Linking on native, Gio on GNOME.
+      openUrl(target.externalUrl);
+    }
+  };
+
+  // Desk shows "{} Open"-style templates when `format` is set.
+  const countLabel =
+    count === undefined
+      ? undefined
+      : row.format
+        ? row.format.replace("{}", String(count))
+        : String(count);
+
+  const TypeIcon = TYPE_ICONS[row.type] ?? SquaresFourIcon;
+
+  return (
+    <Card
+      // Chip-scale surface: eject the Card's default panelPadding — the
+      // inner row owns the compact inset (LC-18 eject-last contract).
+      padding={0}
+      onPress={target.disabled && !onPress ? undefined : handlePress}
+      disabled={target.disabled && !onPress}
+      opacity={target.disabled && !onPress ? 0.5 : 1}
+      cursor={target.disabled && !onPress ? "default" : "pointer"}
+      hoverStyle={target.disabled && !onPress ? undefined : { borderColor: "$accentBackground" }}
+      pressStyle={target.disabled && !onPress ? undefined : { scale: 0.98 }}
+      role="button"
+      aria-label={row.label}
+    >
+      {/* Compact chip anatomy: icon + label + count, ≥44px press target
+          (DG-LAY-04), self-sized so the band wraps instead of stretching. */}
+      <XStack paddingHorizontal="$3" minHeight={44} alignItems="center" {...knobProps.gap}>
+        <TypeIcon size={16} color={iconColor} aria-hidden />
+        <SizableText size="$3" fontWeight="600" numberOfLines={1} flexShrink={1}>
+          {row.label}
+        </SizableText>
+        {isDoctype ? (
+          countLoading ? (
+            // Pill-shaped like the real count pill (LC-20 radius class).
+            <Skeleton width={28} height={16} borderRadius={1000} />
+          ) : countError ? null : countLabel !== undefined ? (
+            <YStack
+              backgroundColor="$color4"
+              borderRadius={1000}
+              paddingHorizontal="$2.5"
+              paddingVertical="$1"
+            >
+              <SizableText size="$1" color="$color11" fontWeight="600">
+                {countLabel}
+              </SizableText>
+            </YStack>
+          ) : null
+        ) : target.disabled && !onPress ? (
+          <SizableText size="$1" color="$color10">
+            {t("workspaceShortcutUnavailable", "Not available")}
+          </SizableText>
+        ) : null}
+      </XStack>
+    </Card>
+  );
+}

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();
+  });
+});