@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/ui-tailwind/chrome/editor-action-registry.ts

@@ -0,0 +1,553 @@
+/**
+ * editor-action-registry — the single source of truth for what
+ * contextual actions exist, keyed by `TargetKind`.
+ *
+ * Consumed by three access routes so DESIGN-EDITOR.md §6.4 holds by
+ * construction ("right-click cannot be richer than the floating surface;
+ * cannot duplicate command trees"):
+ *
+ *   1. Right-click context menu (via `build-context-menu-entries.ts`)
+ *   2. Inline "More…" affordance on reduced floating toolbars (Phase D)
+ *   3. Command palette groups (Phase C.δ)
+ *
+ * All three routes produce the same actions from this registry — they
+ * cannot diverge.  This is the load-bearing decision that makes the
+ * floating-menu demotion legal.
+ *
+ * Perf discipline: pure data + pure filter helpers.  No DOM reads, no
+ * runtime calls, no observers.  Actions are dispatched through host-
+ * supplied callbacks so the registry never references the PM view or
+ * the document runtime directly.
+ */
+
+import type { EditorChromeMode } from "../../api/v3/ui/chrome-composition";
+import type { ContextMenuGroupId } from "./tw-context-menu";
+import type { ShortcutKey } from "./tw-shortcut-hint";
+
+/**
+ * Target kinds roughly mirror DESIGN-EDITOR.md §4 "Local context" cells.
+ * A contextmenu event resolves its target to one (or more) of these
+ * kinds; the builder then asks the registry for every action whose
+ * `targetKinds` set includes at least one of the resolved kinds.
+ */
+export type TargetKind =
+  | "plain-text"          // caret or selection in flowing body text
+  | "table-cell"          // caret / selection inside a table cell (T1/T2)
+  | "table-row"           // whole row selected (T3) — Chrome Closure Pass · Task 3
+  | "table-column"        // whole column selected (T4b) — Chrome Closure Pass · Task 3
+  | "table-whole"         // whole table selected (T5) — Chrome Closure Pass · Task 3
+  | "image"               // an anchored image (inline or floating)
+  | "object"              // preserved shape / textbox / OLE / SmartArt
+  | "hyperlink"           // caret inside or selection over a hyperlink
+  | "comment-anchor"      // caret at a comment-anchored range
+  | "suggestion"          // caret at a tracked-change suggestion
+  | "opaque-block"        // preserved-for-export placeholder
+  | "scope-anchor";       // caret inside a workflow scope
+
+/**
+ * Dispatch context passed to each action's `run()` function.
+ * Host callbacks + composition posture + selection state come through
+ * here so the registry's actions never reach into React / PM internals.
+ */
+export interface EditorActionDispatchContext {
+  readonly composition: { readonly mode: EditorChromeMode };
+  readonly host: EditorActionHostCallbacks;
+  /** Close the menu / palette after dispatching, if applicable. */
+  readonly dismiss: () => void;
+}
+
+/**
+ * Host callbacks the editor shell passes down to the registry.  All
+ * fields are optional — the registry's `when()` predicates filter out
+ * actions the host hasn't wired yet so the menu never shows a row that
+ * can't fire.
+ *
+ * Phases C/D/E will wire these from the existing ref methods on
+ * `WordReviewEditorRef`; the surface is intentionally minimal now.
+ */
+export interface EditorActionHostCallbacks {
+  // Clipboard (always available — browser-native fallback acceptable)
+  readonly onCut?: () => void;
+  readonly onCopy?: () => void;
+  readonly onPaste?: () => void;
+
+  // Tracked-change operations (suggestion target)
+  readonly onAcceptSuggestion?: () => void;
+  readonly onRejectSuggestion?: () => void;
+
+  // Comment operations (comment-anchor target)
+  readonly onResolveComment?: () => void;
+  readonly onReplyToComment?: () => void;
+  readonly onJumpToCommentInRail?: () => void;
+
+  // Table operations (table-cell target)
+  readonly onInsertRowAbove?: () => void;
+  readonly onInsertRowBelow?: () => void;
+  readonly onInsertColumnBefore?: () => void;
+  readonly onInsertColumnAfter?: () => void;
+  readonly onDeleteRow?: () => void;
+  readonly onDeleteColumn?: () => void;
+  readonly onMergeCells?: () => void;
+  readonly onSplitCell?: () => void;
+  readonly onOpenTableProperties?: () => void;
+  readonly onOpenBorderPicker?: () => void;
+
+  // Image operations (image target)
+  readonly onReplaceImage?: () => void;
+  readonly onEditImageAltText?: () => void;
+  readonly onSetImageSize?: (preset: "small" | "medium" | "large") => void;
+
+  // Object operations (object target — read-only info by DESIGN-EDITOR.md §6.10)
+  readonly onOpenObjectInfo?: () => void;
+
+  // Hyperlink operations (hyperlink target)
+  readonly onEditHyperlink?: () => void;
+  readonly onRemoveHyperlink?: () => void;
+  readonly onOpenHyperlink?: () => void;
+
+  // Workflow (scope-anchor target)
+  readonly onJumpToScopeInRail?: () => void;
+  readonly onOpenScopeCard?: () => void;
+  readonly onMarkScopeResolved?: () => void;
+}
+
+export interface EditorAction {
+  readonly id: string;
+  readonly label: string;
+  readonly shortcut?: readonly ShortcutKey[];
+  readonly group: ContextMenuGroupId;
+  /** Targets for which this action is relevant. */
+  readonly targetKinds: ReadonlySet<TargetKind>;
+  /**
+   * Optional mode filter — some actions only surface in specific modes.
+   * Empty / undefined means "always in scope of its target".
+   */
+  readonly modes?: ReadonlySet<EditorChromeMode>;
+  /**
+   * Optional availability predicate.  Return `false` to hide the row;
+   * `true` to show; `"disabled"` to show as a non-interactive disabled
+   * row (DESIGN-EDITOR.md §6.4 "disabled items remain visible when
+   * explanation matters").
+   */
+  readonly when?: (
+    ctx: EditorActionDispatchContext,
+  ) => boolean | "disabled";
+  readonly run: (ctx: EditorActionDispatchContext) => void;
+}
+
+// ---------------------------------------------------------------------
+// The registry itself — terse, data-driven.
+// ---------------------------------------------------------------------
+
+/**
+ * Build a zero-argument action.  The callback referenced by `opts.callback`
+ * is invoked with no arguments at dispatch.  Use `mkArg()` below for
+ * callbacks that take a payload.
+ */
+function mk<K extends keyof EditorActionHostCallbacks>(opts: {
+  id: string;
+  label: string;
+  shortcut?: readonly ShortcutKey[];
+  group: ContextMenuGroupId;
+  targetKinds: readonly TargetKind[];
+  modes?: readonly EditorChromeMode[];
+  callback: K;
+  /** Optional extra predicate run after the callback-presence check. */
+  when?: (ctx: EditorActionDispatchContext) => boolean | "disabled";
+}): EditorAction {
+  return {
+    id: opts.id,
+    label: opts.label,
+    ...(opts.shortcut ? { shortcut: opts.shortcut } : {}),
+    group: opts.group,
+    targetKinds: new Set(opts.targetKinds),
+    ...(opts.modes ? { modes: new Set(opts.modes) } : {}),
+    when: (ctx) => {
+      if (typeof ctx.host[opts.callback] !== "function") return false;
+      if (opts.when) return opts.when(ctx);
+      return true;
+    },
+    run: (ctx) => {
+      const fn = ctx.host[opts.callback] as (() => void) | undefined;
+      fn?.();
+      ctx.dismiss();
+    },
+  };
+}
+
+/**
+ * Build a one-argument action.  `payload` is the value passed to the
+ * callback at dispatch.  This preserves argument-type discipline for
+ * parameterized host callbacks like
+ * `onSetImageSize(preset: "small" | "medium" | "large")`.
+ *
+ * Fixes the pre-fix bug where `mk()` cast every callback to `(() => void)`
+ * and invoked with zero arguments, leaving image-size / similar actions
+ * firing with `undefined` payloads at runtime.  The `A` generic parameter
+ * MUST match the callback's argument type — callers supply it explicitly
+ * at the call site (TypeScript cannot infer from the narrow payload
+ * literal in a way that catches mismatch against the host signature).
+ */
+function mkArg<A, K extends keyof EditorActionHostCallbacks>(opts: {
+  id: string;
+  label: string;
+  shortcut?: readonly ShortcutKey[];
+  group: ContextMenuGroupId;
+  targetKinds: readonly TargetKind[];
+  modes?: readonly EditorChromeMode[];
+  callback: K;
+  payload: A;
+  when?: (ctx: EditorActionDispatchContext) => boolean | "disabled";
+}): EditorAction {
+  return {
+    id: opts.id,
+    label: opts.label,
+    ...(opts.shortcut ? { shortcut: opts.shortcut } : {}),
+    group: opts.group,
+    targetKinds: new Set(opts.targetKinds),
+    ...(opts.modes ? { modes: new Set(opts.modes) } : {}),
+    when: (ctx) => {
+      if (typeof ctx.host[opts.callback] !== "function") return false;
+      if (opts.when) return opts.when(ctx);
+      return true;
+    },
+    run: (ctx) => {
+      const fn = ctx.host[opts.callback] as ((arg: A) => void) | undefined;
+      fn?.(opts.payload);
+      ctx.dismiss();
+    },
+  };
+}
+
+export const EDITOR_ACTION_REGISTRY: readonly EditorAction[] = [
+  // -------- Clipboard (always available across every target kind) --------
+  mk({
+    id: "cut",
+    label: "Cut",
+    shortcut: ["Mod", "X"],
+    group: "clipboard",
+    targetKinds: [
+      "plain-text",
+      "table-cell",
+      "image",
+      "hyperlink",
+      "suggestion",
+      "comment-anchor",
+      "opaque-block",
+      "scope-anchor",
+    ],
+    callback: "onCut",
+  }),
+  mk({
+    id: "copy",
+    label: "Copy",
+    shortcut: ["Mod", "C"],
+    group: "clipboard",
+    targetKinds: [
+      "plain-text",
+      "table-cell",
+      "image",
+      "hyperlink",
+      "suggestion",
+      "comment-anchor",
+      "opaque-block",
+      "scope-anchor",
+    ],
+    callback: "onCopy",
+  }),
+  mk({
+    id: "paste",
+    label: "Paste",
+    shortcut: ["Mod", "V"],
+    group: "clipboard",
+    targetKinds: [
+      "plain-text",
+      "table-cell",
+      "hyperlink",
+      "suggestion",
+      "comment-anchor",
+      "scope-anchor",
+    ],
+    callback: "onPaste",
+  }),
+
+  // -------- Suggestion / tracked change --------
+  mk({
+    id: "accept-suggestion",
+    label: "Accept suggestion",
+    group: "suggestion",
+    targetKinds: ["suggestion"],
+    callback: "onAcceptSuggestion",
+  }),
+  mk({
+    id: "reject-suggestion",
+    label: "Reject suggestion",
+    group: "suggestion",
+    targetKinds: ["suggestion"],
+    callback: "onRejectSuggestion",
+  }),
+
+  // -------- Comment --------
+  mk({
+    id: "resolve-comment",
+    label: "Resolve comment",
+    group: "comment",
+    targetKinds: ["comment-anchor"],
+    callback: "onResolveComment",
+  }),
+  mk({
+    id: "reply-to-comment",
+    label: "Reply to comment",
+    group: "comment",
+    targetKinds: ["comment-anchor"],
+    callback: "onReplyToComment",
+  }),
+  mk({
+    id: "jump-to-comment-in-rail",
+    label: "Open in rail",
+    group: "comment",
+    targetKinds: ["comment-anchor"],
+    callback: "onJumpToCommentInRail",
+  }),
+
+  // -------- Table --------
+  // Chrome Closure Pass · Task 3 — table actions are split across the
+  // tier ladder per designsystem.md §6.9. The menu builder asks the
+  // registry for actions whose `targetKinds` overlap any of the
+  // resolved kinds (table-cell ⊂ table-row ⊂ table-column ⊂
+  // table-whole — each higher tier inherits the cell-level ops). The
+  // cell-level ops carry every table-* kind so they remain visible at
+  // every tier; the row-only / column-only / whole-table ops carry
+  // only the kinds that should expose them.
+
+  // ── Cell-level ops — visible at every tier ──
+  mk({
+    id: "table-insert-row-above",
+    label: "Insert row above",
+    group: "table",
+    targetKinds: ["table-cell", "table-row", "table-column", "table-whole"],
+    callback: "onInsertRowAbove",
+  }),
+  mk({
+    id: "table-insert-row-below",
+    label: "Insert row below",
+    group: "table",
+    targetKinds: ["table-cell", "table-row", "table-column", "table-whole"],
+    callback: "onInsertRowBelow",
+  }),
+  mk({
+    id: "table-insert-column-before",
+    label: "Insert column before",
+    group: "table",
+    targetKinds: ["table-cell", "table-row", "table-column", "table-whole"],
+    callback: "onInsertColumnBefore",
+  }),
+  mk({
+    id: "table-insert-column-after",
+    label: "Insert column after",
+    group: "table",
+    targetKinds: ["table-cell", "table-row", "table-column", "table-whole"],
+    callback: "onInsertColumnAfter",
+  }),
+  mk({
+    id: "table-merge-cells",
+    label: "Merge cells",
+    group: "table",
+    targetKinds: ["table-cell", "table-row", "table-column", "table-whole"],
+    callback: "onMergeCells",
+  }),
+  mk({
+    id: "table-split-cell",
+    label: "Split cell",
+    group: "table",
+    targetKinds: ["table-cell", "table-row", "table-column", "table-whole"],
+    callback: "onSplitCell",
+  }),
+  // ── Row-only — Delete row only when a row is selected (T3) ──
+  mk({
+    id: "table-delete-row",
+    label: "Delete row",
+    group: "table",
+    targetKinds: ["table-row", "table-whole"],
+    callback: "onDeleteRow",
+  }),
+  // ── Column-only — Delete column only when a column is selected (T4b) ──
+  mk({
+    id: "table-delete-column",
+    label: "Delete column",
+    group: "table",
+    targetKinds: ["table-column", "table-whole"],
+    callback: "onDeleteColumn",
+  }),
+  // ── Whole-table — properties / borders surface at any tier so
+  //    they are reachable from a single right-click in a cell ──
+  mk({
+    id: "table-properties",
+    label: "Table properties…",
+    group: "table",
+    targetKinds: ["table-cell", "table-row", "table-column", "table-whole"],
+    callback: "onOpenTableProperties",
+  }),
+  mk({
+    id: "table-borders",
+    label: "Borders…",
+    group: "table",
+    targetKinds: ["table-cell", "table-row", "table-column", "table-whole"],
+    callback: "onOpenBorderPicker",
+  }),
+
+  // -------- Image --------
+  mk({
+    id: "image-replace",
+    label: "Replace image…",
+    group: "misc",
+    targetKinds: ["image"],
+    callback: "onReplaceImage",
+  }),
+  mk({
+    id: "image-alt-text",
+    label: "Edit alt text…",
+    group: "misc",
+    targetKinds: ["image"],
+    callback: "onEditImageAltText",
+  }),
+  mkArg<"small" | "medium" | "large", "onSetImageSize">({
+    id: "image-size-small",
+    label: "Small",
+    group: "misc",
+    targetKinds: ["image"],
+    callback: "onSetImageSize",
+    payload: "small",
+  }),
+  mkArg<"small" | "medium" | "large", "onSetImageSize">({
+    id: "image-size-medium",
+    label: "Medium",
+    group: "misc",
+    targetKinds: ["image"],
+    callback: "onSetImageSize",
+    payload: "medium",
+  }),
+  mkArg<"small" | "medium" | "large", "onSetImageSize">({
+    id: "image-size-large",
+    label: "Large",
+    group: "misc",
+    targetKinds: ["image"],
+    callback: "onSetImageSize",
+    payload: "large",
+  }),
+
+  // -------- Object (read-only info per DESIGN-EDITOR.md §6.10) --------
+  mk({
+    id: "object-info",
+    label: "Object info…",
+    group: "misc",
+    targetKinds: ["object"],
+    callback: "onOpenObjectInfo",
+  }),
+
+  // -------- Hyperlink --------
+  mk({
+    id: "hyperlink-edit",
+    label: "Edit link…",
+    group: "misc",
+    targetKinds: ["hyperlink"],
+    callback: "onEditHyperlink",
+  }),
+  mk({
+    id: "hyperlink-remove",
+    label: "Remove link",
+    group: "misc",
+    targetKinds: ["hyperlink"],
+    callback: "onRemoveHyperlink",
+  }),
+  mk({
+    id: "hyperlink-open",
+    label: "Open link",
+    group: "misc",
+    targetKinds: ["hyperlink"],
+    callback: "onOpenHyperlink",
+  }),
+
+  // -------- Workflow scope --------
+  mk({
+    id: "scope-open-card",
+    label: "Open scope card",
+    group: "misc",
+    targetKinds: ["scope-anchor"],
+    callback: "onOpenScopeCard",
+    modes: ["workflow", "review"],
+  }),
+  mk({
+    id: "scope-jump-in-rail",
+    label: "Open scope in rail",
+    group: "misc",
+    targetKinds: ["scope-anchor"],
+    callback: "onJumpToScopeInRail",
+    modes: ["workflow", "review"],
+  }),
+  mk({
+    id: "scope-mark-resolved",
+    label: "Mark scope resolved",
+    group: "misc",
+    targetKinds: ["scope-anchor"],
+    callback: "onMarkScopeResolved",
+    // Workflow-only — review posture inspects, doesn't mutate scope state.
+    modes: ["workflow"],
+  }),
+];
+
+/**
+ * Result row from `resolveActionsForTarget`.  Carries the evaluated
+ * `when()` verdict alongside the action so callers (e.g. the context-
+ * menu builder) don't re-evaluate the predicate a second time just to
+ * detect the `"disabled"` state.
+ */
+export interface ResolvedEditorAction {
+  readonly action: EditorAction;
+  readonly disabled: boolean;
+}
+
+/**
+ * Query the registry for every action whose target set includes `kind`
+ * and whose mode filter (if any) matches the current composition mode.
+ * Each `when()` predicate runs once per resolution; the result includes
+ * a `disabled` flag so callers render disabled rows without a second
+ * evaluation.
+ *
+ * Pure — no side effects.  The overload below preserves the legacy
+ * `readonly EditorAction[]` return shape for tests that don't need the
+ * disabled flag.
+ */
+export function resolveActionsForTarget(
+  kind: TargetKind,
+  mode: EditorChromeMode,
+  host: EditorActionHostCallbacks,
+): readonly EditorAction[];
+export function resolveActionsForTarget(
+  kind: TargetKind,
+  mode: EditorChromeMode,
+  host: EditorActionHostCallbacks,
+  options: { includeDisabled: true },
+): readonly ResolvedEditorAction[];
+export function resolveActionsForTarget(
+  kind: TargetKind,
+  mode: EditorChromeMode,
+  host: EditorActionHostCallbacks,
+  options?: { includeDisabled?: boolean },
+): readonly EditorAction[] | readonly ResolvedEditorAction[] {
+  const ctx: EditorActionDispatchContext = {
+    composition: { mode },
+    host,
+    dismiss: () => {},
+  };
+  const resolved: ResolvedEditorAction[] = [];
+  for (const action of EDITOR_ACTION_REGISTRY) {
+    if (!action.targetKinds.has(kind)) continue;
+    if (action.modes && !action.modes.has(mode)) continue;
+    const verdict = action.when ? action.when(ctx) : true;
+    if (verdict === false) continue;
+    resolved.push({ action, disabled: verdict === "disabled" });
+  }
+  if (options?.includeDisabled) return resolved;
+  return resolved.map((r) => r.action);
+}