@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/ui-tailwind/chrome/editor-actions-to-palette.ts

@@ -0,0 +1,182 @@
+/**
+ * editor-actions-to-palette — adapter that turns the shared
+ * `EDITOR_ACTION_REGISTRY` into `CommandPaletteGroup[]` for mounting
+ * `TwCommandPalette`.
+ *
+ * Per DESIGN-EDITOR.md §6.4, the palette, right-click menu, and
+ * inline "More…" buttons all read the SAME registry — this file is
+ * the palette's read path.  It does NOT filter by target kind (the
+ * palette is global, not target-scoped); instead it surfaces every
+ * action whose callback is wired on the host, grouped by the
+ * registry's `ContextMenuGroupId`.
+ *
+ * Progressive-disclosure discipline (designsystem.md §2.1 principle 4):
+ *   - Actions without a wired callback are hidden, not rendered
+ *     disabled.  The palette is the escape valve for low-frequency
+ *     actions; an empty surface is better than a wall of disabled
+ *     rows.
+ *   - Mode-filtered actions (e.g. `scope-open-card` is
+ *     workflow/review-only) only appear when the composition mode
+ *     allows them.
+ */
+
+import type {
+  EditorChromeMode,
+} from "../../api/v3/ui/chrome-composition";
+import {
+  EDITOR_ACTION_REGISTRY,
+  type EditorAction,
+  type EditorActionDispatchContext,
+  type EditorActionHostCallbacks,
+} from "./editor-action-registry";
+import type {
+  CommandPaletteGroup,
+  CommandPaletteItem,
+} from "./tw-command-palette";
+import type { ContextMenuGroupId } from "./tw-context-menu";
+import type { ShortcutKey } from "./tw-shortcut-hint";
+
+/**
+ * Format a registry `ShortcutKey[]` for display in a palette row.
+ * Mac shows the canonical glyph cluster (`⌘⇧B`); other platforms show
+ * `Ctrl+Shift+B`. Used by Chrome Closure Pass · Task 4 to preserve
+ * shortcut metadata from the registry into the palette projection
+ * (designsystem.md §6.25 — every shipped action with a shortcut must
+ * surface that shortcut in the palette row).
+ *
+ * Pure / synchronous so the projection works in tests without a DOM.
+ * Platform detection is performed once per call from `navigator`; the
+ * fallback is `"win"` so SSR / headless paths produce stable output.
+ */
+const MAC_SHORTCUT_GLYPH: Record<string, string> = {
+  Cmd: "⌘",
+  // "Mod" is the cross-platform key the registry uses — Cmd on Mac,
+  // Ctrl elsewhere. Mirror both the Mac glyph and the Win/Linux
+  // translation so rows like `["Mod", "X"]` render "⌘X" on Mac and
+  // "Ctrl+X" on Win, not the raw literal "ModX".
+  Mod: "⌘",
+  Shift: "⇧",
+  Alt: "⌥",
+  Ctrl: "⌃",
+  Enter: "↵",
+  Esc: "Esc",
+  Tab: "⇥",
+  Backspace: "⌫",
+};
+
+function detectPlatform(): "mac" | "win" {
+  if (typeof navigator === "undefined") return "win";
+  const uaData = (navigator as Navigator & { userAgentData?: { platform?: string } })
+    .userAgentData;
+  if (uaData?.platform) {
+    return /mac|iPhone|iPad/i.test(uaData.platform) ? "mac" : "win";
+  }
+  return /Mac|iPhone|iPad/.test(navigator.platform) ? "mac" : "win";
+}
+
+export function formatShortcutForPalette(
+  keys: readonly ShortcutKey[],
+  platform: "mac" | "win" = detectPlatform(),
+): string {
+  if (keys.length === 0) return "";
+  if (platform === "mac") {
+    // Mac convention: glyphs concatenated, no separator.
+    return keys.map((k) => MAC_SHORTCUT_GLYPH[k] ?? k).join("");
+  }
+  // Win/Linux: Cmd → Ctrl, Mod → Ctrl, "+" separator.
+  return keys
+    .map((k) => (k === "Cmd" || k === "Mod" ? "Ctrl" : k))
+    .join("+");
+}
+
+/**
+ * Human-friendly group labels.  Kept here because the palette renders
+ * section headings and the registry's group ids are terse internal
+ * identifiers.
+ */
+const GROUP_LABELS: Record<ContextMenuGroupId, string> = {
+  clipboard: "Clipboard",
+  suggestion: "Review",
+  comment: "Comments",
+  table: "Table",
+  formatting: "Formatting",
+  misc: "More",
+};
+
+/**
+ * Stable group order — matches the progressive-disclosure priority in
+ * designsystem.md §2.1 (clipboard first because it's always available,
+ * review + comment next because they're the primary legal-review
+ * actions, table + formatting after, misc last).
+ */
+const GROUP_ORDER: readonly ContextMenuGroupId[] = [
+  "clipboard",
+  "suggestion",
+  "comment",
+  "table",
+  "formatting",
+  "misc",
+];
+
+function isActionAvailable(
+  action: EditorAction,
+  ctx: EditorActionDispatchContext,
+): boolean {
+  const verdict = action.when ? action.when(ctx) : true;
+  // "disabled" actions are hidden from the palette.  The palette is a
+  // search-first surface; surfacing disabled rows dilutes the query
+  // space and clutters the empty state.
+  return verdict === true;
+}
+
+export interface BuildPaletteGroupsInput {
+  readonly mode: EditorChromeMode;
+  readonly host: EditorActionHostCallbacks;
+  /** Called by every command's onInvoke — typically closes the palette. */
+  readonly dismiss: () => void;
+}
+
+export function buildPaletteGroupsFromRegistry(
+  input: BuildPaletteGroupsInput,
+): readonly CommandPaletteGroup[] {
+  const ctx: EditorActionDispatchContext = {
+    composition: { mode: input.mode },
+    host: input.host,
+    dismiss: input.dismiss,
+  };
+
+  const byGroup = new Map<ContextMenuGroupId, CommandPaletteItem[]>();
+
+  for (const action of EDITOR_ACTION_REGISTRY) {
+    if (action.modes && !action.modes.has(input.mode)) continue;
+    if (!isActionAvailable(action, ctx)) continue;
+
+    const item: CommandPaletteItem = {
+      id: action.id,
+      label: action.label,
+      // Chrome Closure Pass · Task 4 (designsystem.md §6.25) —
+      // preserve the registry shortcut so the palette row shows
+      // the same hint as the matching context-menu / tooltip.
+      ...(action.shortcut && action.shortcut.length > 0
+        ? { shortcut: formatShortcutForPalette(action.shortcut) }
+        : {}),
+      onInvoke: () => action.run(ctx),
+    };
+
+    const bucket = byGroup.get(action.group) ?? [];
+    bucket.push(item);
+    byGroup.set(action.group, bucket);
+  }
+
+  const groups: CommandPaletteGroup[] = [];
+  for (const groupId of GROUP_ORDER) {
+    const commands = byGroup.get(groupId);
+    if (!commands || commands.length === 0) continue;
+    groups.push({
+      id: groupId,
+      label: GROUP_LABELS[groupId],
+      commands,
+    });
+  }
+  return groups;
+}