@beyondwork/docx-react-component 1.0.66 → 1.0.69

package/src/shell/overlay-anchor-bridge.ts

@@ -0,0 +1,53 @@
+/**
+ * Shell-owned overlay-anchor bridge — the seam that lets
+ * `ui.overlays.getAnchor({ kind: "selection" })` return a real rect on
+ * the mounted React path without re-creating the API on every
+ * selection change (Performance Invariant 8 — stable bridge, stable
+ * `useMemo` deps).
+ *
+ * Why this exists
+ *
+ * `ui.overlays.getAnchor` resolves most `OverlayAnchorQuery` kinds
+ * directly through `handle.geometry.getAnchor` (id-keyed). The
+ * `kind: "selection"` branch is the exception: the geometry facet's
+ * `AnchorQuery` keys off stable ids, not the current selection range,
+ * so selection anchors fall through to `UiController.getOverlayAnchor`
+ * (see `src/api/v3/ui/overlays.ts` §Slice 11). The controller hook
+ * therefore needs access to mounted React state (current selection,
+ * active selection tool, geometry facet) while the factory that
+ * produces it runs once at API-creation time.
+ *
+ * The bridge is a stable mutable holder created by `WordReviewEditor`
+ * via `useRef`, handed to `createShellUiControllerFactory(bridge)`, and
+ * re-populated on each render by whichever hook in the shell tree
+ * already has the inputs in hand (today `tw-review-workspace.tsx` via
+ * `useShellSelectionAnchorBridge`). The factory's `getOverlayAnchor`
+ * delegates to the bridge; the bridge identity never changes so the
+ * controller identity never changes either.
+ *
+ * The bridge is explicitly *not* a React context — it is read from a
+ * non-React context (the `UiController` is constructed outside the
+ * tree) and must stay callable synchronously from the API layer. The
+ * shell writes into it with simple assignment; the factory reads with
+ * simple property access. No subscription machinery.
+ */
+
+import type { GeometryRect } from "../api/v3/ui/_types.ts";
+
+export interface ShellOverlayAnchorBridge {
+  /**
+   * Resolver for `ui.overlays.getAnchor({ kind: "selection" })`.
+   *
+   * Set by `useShellSelectionAnchorBridge` (mounted path) to a closure
+   * that returns the current selection rect from the geometry facet +
+   * active selection tool. Left `null` on the headless path where the
+   * bridge is never populated — the UI API then returns `null` per U4,
+   * MUST NOT fall back to DOM measurement.
+   */
+  getSelectionAnchor: (() => GeometryRect | null) | null;
+}
+
+/** Fresh bridge with no resolvers wired. Call once at shell mount. */
+export function createShellOverlayAnchorBridge(): ShellOverlayAnchorBridge {
+  return { getSelectionAnchor: null };
+}

package/src/shell/paste-adapter.ts

@@ -0,0 +1,23 @@
+/**
+ * Shell helper — rich-paste adapter for the PM command bridge.
+ *
+ * `pm-command-bridge.ts` exposes a narrow `PasteFragmentParserAdapter`
+ * interface (refactor/11 Slice 5) so the PM surface no longer imports
+ * `src/io/paste/**` directly. The default shell supplies this adapter
+ * so rich paste (WordML + HTML) continues to work; headless consumers
+ * (stateless services, test harnesses) omit it for plain-text-only
+ * paste, or plug their own wrapping.
+ *
+ * This lives in `src/shell/` rather than `src/ui/` so the `src/io/paste/**`
+ * value imports stay outside the Layer-11 boundary register. The
+ * adapter is a thin passthrough — one parse call per format.
+ */
+
+import { parseCanonicalFragmentFromWordML } from "../io/paste/word-clipboard";
+import { parseCanonicalFragmentFromHtml } from "../io/paste/html-clipboard";
+import type { PasteFragmentParserAdapter } from "../ui-tailwind/editor-surface/pm-command-bridge.ts";
+
+export const shellPasteFragmentParser: PasteFragmentParserAdapter = {
+  parseWordML: (wordml) => parseCanonicalFragmentFromWordML(wordml),
+  parseHtml: (html) => parseCanonicalFragmentFromHtml(html),
+};