@multiplatform.one/backoffice 6.4.0 → 6.4.1

package/src/workspace/WorkspaceScreen.tsx

@@ -0,0 +1,322 @@
+// Contract: renders a frappe Workspace document (shortcuts, link cards,
+// charts, number cards, quick lists) by workspace name.
+/**
+ * Dashboard-first workspace page (MOD-11). The Workspace doc's `content`
+ * JSON declares the blocks; the composition is ours, not desk's authoring
+ * order (owner mandate: desk is a capability reference, not a design
+ * constraint): recents strip, then live data widgets (number cards →
+ * charts → quick lists), then narrative text, then a compact shortcut chip
+ * band, then the grouped link cards behind a searchable "Browse all"
+ * disclosure. Each widget resolves its definition from the doc's child
+ * tables (`shortcuts`, `links`, `charts`, `number_cards`, `quick_lists`)
+ * — shapes verified against a real bench (see types.ts).
+ *
+ * Skipped block types (rendered as nothing, by design): `onboarding`
+ * (module onboarding widget needs its own RPC surface), `custom_block`
+ * (arbitrary HTML — unsafe cross-platform), and `spacer` (the section
+ * composition owns vertical rhythm now).
+ */
+import {
+  AsyncBoundary,
+  H2,
+  H3,
+  H4,
+  H5,
+  H6,
+  PageHeader,
+  PageSection,
+  Paragraph,
+  Screen,
+  Skeleton,
+  XStack,
+  YStack,
+} from "@multiplatform.one/components";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { useMemo, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import { BACKOFFICE_I18N_NAMESPACE } from "../i18n";
+import {
+  composeWorkspaceBlocks,
+  findLinkGroup,
+  findShortcut,
+  groupLinks,
+  headerLevel,
+  parseWorkspaceContent,
+  stripHtml,
+} from "./parseContent";
+import type { WorkspaceBlock, WorkspaceDoc, WorkspaceShortcutRow } from "./types";
+import { useWorkspaceDoc } from "./useWorkspaceDoc";
+import { WorkspaceChartBlock } from "./WorkspaceChartBlock";
+import { WorkspaceGrid, type WorkspaceGridItem } from "./WorkspaceGrid";
+import { WorkspaceLinkDirectory, type WorkspaceLinkDirectoryItem } from "./WorkspaceLinkDirectory";
+import { WorkspaceNumberCard } from "./WorkspaceNumberCard";
+import { WorkspaceQuickList } from "./WorkspaceQuickList";
+import { WorkspaceRecents } from "./WorkspaceRecents";
+import { WorkspaceShortcut } from "./WorkspaceShortcut";
+
+/** Block classes a host can hide from the workspace composition. */
+export type WorkspaceBlockKind =
+  | "shortcuts"
+  | "links"
+  | "charts"
+  | "numbers"
+  | "quickLists"
+  | "recents";
+
+export interface WorkspaceScreenProps {
+  /** Workspace document name (proper case, e.g. "Home", "Users") */
+  workspace: string;
+  /** Hide whole block classes from the composition. */
+  hiddenBlocks?: readonly WorkspaceBlockKind[];
+  /** Override the default shortcut-chip navigation. */
+  onShortcutPress?: (row: WorkspaceShortcutRow) => void;
+  /**
+   * Replace the rendering of individual grid blocks (data widgets and
+   * narrative text). Shortcut chips and link cards have their own
+   * composition and are controlled via `hiddenBlocks`/`onShortcutPress`.
+   */
+  renderBlock?: (context: {
+    block: WorkspaceBlock;
+    doc: WorkspaceDoc;
+    defaultContent: ReactNode;
+  }) => ReactNode;
+}
+
+// Section headers step under the page H1; visual scale follows desk's
+// small workspace section headings.
+const HEADER_TAGS = { 1: H2, 2: H2, 3: H3, 4: H4, 5: H5, 6: H6 } as const;
+
+/**
+ * Map a text or data block to a grid item. Shortcut and card blocks never
+ * reach this — the composition renders them as the chip band and the
+ * "Browse all" directory instead.
+ */
+function blockToGridItem(block: WorkspaceBlock, doc: WorkspaceDoc): WorkspaceGridItem | undefined {
+  const key = block.id || JSON.stringify(block.data);
+  switch (block.type) {
+    case "header": {
+      const text = stripHtml(block.data.text);
+      if (!text) return undefined;
+      const Tag = HEADER_TAGS[headerLevel(block.data.text)];
+      return {
+        key,
+        col: 12,
+        node: (
+          <Tag margin={0} marginTop="$3">
+            {text}
+          </Tag>
+        ),
+      };
+    }
+    case "paragraph": {
+      const text = stripHtml(block.data.text);
+      if (!text) return undefined;
+      return {
+        key,
+        col: 12,
+        node: <Paragraph margin={0}>{text}</Paragraph>,
+      };
+    }
+    case "chart": {
+      const row = doc.charts?.find(
+        (chart) =>
+          chart.chart_name === block.data.chart_name || chart.label === block.data.chart_name,
+      );
+      if (!row) return undefined;
+      return { key, col: block.data.col ?? 12, node: <WorkspaceChartBlock row={row} /> };
+    }
+    case "number_card": {
+      const row = doc.number_cards?.find(
+        (card) =>
+          card.number_card_name === block.data.number_card_name ||
+          card.label === block.data.number_card_name,
+      );
+      if (!row) return undefined;
+      return { key, col: block.data.col ?? 3, node: <WorkspaceNumberCard row={row} /> };
+    }
+    case "quick_list": {
+      const row = doc.quick_lists?.find(
+        (list) =>
+          list.document_type === block.data.quick_list_name ||
+          list.label === block.data.quick_list_name,
+      );
+      if (!row) return undefined;
+      return { key, col: block.data.col ?? 4, node: <WorkspaceQuickList row={row} /> };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function WorkspaceSkeleton() {
+  const { knobProps } = useResolvedKnobs();
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  // Mirrors the dashboard-first anatomy (LC-20): title line, shortcut chip
+  // band (44px chips, deterministic widths), then the content card region.
+  return (
+    <YStack {...knobProps.gapLg} aria-busy aria-label={t("loading", "Loading")}>
+      <Skeleton width="30%" height={32} />
+      <XStack {...knobProps.gap}>
+        <Skeleton variant="rounded" width={128} height={44} />
+        <Skeleton variant="rounded" width={104} height={44} />
+        <Skeleton variant="rounded" width={144} height={44} />
+        <Skeleton variant="rounded" width={112} height={44} />
+      </XStack>
+      <XStack {...knobProps.gap}>
+        <Skeleton variant="rounded" width="32%" height={200} />
+        <Skeleton variant="rounded" width="32%" height={200} />
+        <Skeleton variant="rounded" width="32%" height={200} />
+      </XStack>
+    </YStack>
+  );
+}
+
+interface WorkspaceSections {
+  /** Data widgets first: number cards → charts → quick lists. */
+  data: WorkspaceGridItem[];
+  /** Narrative headers/paragraphs (e.g. the text-only Welcome Workspace). */
+  text: WorkspaceGridItem[];
+  /** Resolved shortcut rows for the chip band. */
+  shortcuts: WorkspaceShortcutRow[];
+  /** Resolved link groups (with authored spans) for the directory. */
+  links: WorkspaceLinkDirectoryItem[];
+}
+
+const DATA_KIND_BY_TYPE: Record<string, WorkspaceBlockKind> = {
+  chart: "charts",
+  number_card: "numbers",
+  quick_list: "quickLists",
+};
+
+function buildSections(
+  doc: WorkspaceDoc,
+  hidden: ReadonlySet<WorkspaceBlockKind>,
+  renderBlock?: WorkspaceScreenProps["renderBlock"],
+): WorkspaceSections {
+  const composition = composeWorkspaceBlocks(parseWorkspaceContent(doc.content));
+  const toGridItems = (blocks: WorkspaceBlock[]) =>
+    blocks
+      .map((block) => {
+        const item = blockToGridItem(block, doc);
+        if (!item || !renderBlock) return item;
+        return { ...item, node: renderBlock({ block, doc, defaultContent: item.node }) };
+      })
+      .filter((item): item is WorkspaceGridItem => item !== undefined);
+  const groups = groupLinks(doc.links);
+  const dataBlocks = composition.data.filter((block) => {
+    const kind = DATA_KIND_BY_TYPE[block.type];
+    return !kind || !hidden.has(kind);
+  });
+  return {
+    data: toGridItems(dataBlocks),
+    text: toGridItems(composition.text),
+    shortcuts: hidden.has("shortcuts")
+      ? []
+      : composition.shortcuts.flatMap((block) => {
+          const row = findShortcut(doc, block.data.shortcut_name);
+          return row ? [row] : [];
+        }),
+    links: hidden.has("links")
+      ? []
+      : composition.cards.flatMap((block) => {
+          const group = findLinkGroup(groups, block.data.card_name);
+          if (!group) return [];
+          return [{ key: block.id || group.label, col: block.data.col ?? 4, group }];
+        }),
+  };
+}
+
+export function WorkspaceScreen({
+  workspace,
+  hiddenBlocks,
+  onShortcutPress,
+  renderBlock,
+}: WorkspaceScreenProps) {
+  const { t } = useTranslation(BACKOFFICE_I18N_NAMESPACE);
+  const { knobProps } = useResolvedKnobs();
+  const { doc, isLoading, error, isPermissionError, refresh } = useWorkspaceDoc(workspace);
+
+  const hidden = useMemo(() => new Set(hiddenBlocks ?? []), [hiddenBlocks]);
+  const sections = useMemo(
+    () => (doc ? buildSections(doc, hidden, renderBlock) : undefined),
+    [doc, hidden, renderBlock],
+  );
+
+  if (isLoading) {
+    return (
+      <Screen>
+        <WorkspaceSkeleton />
+      </Screen>
+    );
+  }
+
+  if (error || !doc || !sections) {
+    return (
+      <Screen>
+        <AsyncBoundary
+          error={error ?? true}
+          onRetry={refresh}
+          errorTitle={
+            isPermissionError
+              ? t(
+                  "workspacePermissionError",
+                  "You do not have permission to view {{workspace}}",
+                  { workspace },
+                )
+              : t("workspaceError", "Couldn't load workspace {{workspace}}", {
+                  workspace,
+                })
+          }
+        />
+      </Screen>
+    );
+  }
+
+  const isEmpty =
+    sections.data.length === 0 &&
+    sections.text.length === 0 &&
+    sections.shortcuts.length === 0 &&
+    sections.links.length === 0;
+
+  return (
+    <Screen>
+      {/* D-11 page-title dial: moderate (32px) — a workspace title is
+          wayfinding, not display copy. No divider: the rule under the title
+          earned no role (Axiom 16 chrome-earns-role). */}
+      <PageHeader
+        title={doc.title || doc.label || workspace}
+        titleScale="moderate"
+        divider={false}
+      />
+      {hidden.has("recents") ? null : <WorkspaceRecents />}
+      {isEmpty ? (
+        <AsyncBoundary
+          empty
+          emptyTitle={t("workspaceEmpty", "This workspace is empty")}
+          emptyDescription={t(
+            "workspaceEmptyDescription",
+            "No blocks have been added to {{workspace}} yet",
+            { workspace },
+          )}
+        />
+      ) : (
+        <>
+          {sections.data.length > 0 ? <WorkspaceGrid items={sections.data} /> : null}
+          {sections.text.length > 0 ? <WorkspaceGrid items={sections.text} /> : null}
+          {sections.shortcuts.length > 0 ? (
+            // Section heading on the shared sectionHeading scale (LC-17) —
+            // PageSection owns it; no divider rule over a chip band.
+            <PageSection title={t("workspaceShortcuts", "Shortcuts")} divider={false}>
+              <XStack flexWrap="wrap" {...knobProps.gap}>
+                {sections.shortcuts.map((row) => (
+                  <WorkspaceShortcut key={row.name} row={row} onPress={onShortcutPress} />
+                ))}
+              </XStack>
+            </PageSection>
+          ) : null}
+          {sections.links.length > 0 ? <WorkspaceLinkDirectory items={sections.links} /> : null}
+        </>
+      )}
+    </Screen>
+  );
+}

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