@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/api/v3/runtime/chart.ts

@@ -0,0 +1,310 @@
+/**
+ * @endStateApi v3 — `runtime.chart` family.
+ *
+ * Ships coord-07 §2.1 / coord-11 §4.1 — the chart-family substrate
+ * seam. Before this family, the 7 chart renderers under
+ * `src/ui-tailwind/chart/render/**` + `chart-node-view.tsx` reached
+ * into `src/io/ooxml/chart/**` and `src/runtime/chart/**` directly,
+ * keeping the Layer-11 boundary register at +11 imports that the
+ * refactor/11 guard must track. This family re-exposes the pure
+ * helpers through the v3 seam so L11 consumers can flip their
+ * imports from `src/io/ooxml/chart/**` → `src/api/v3/runtime/chart.ts`
+ * (a v3 import is outside the L11 substrate-boundary rule).
+ *
+ * Every function is `live` — direct delegation, no adapter debt.
+ * Pure read-only computations over typed inputs (theme, styleXml,
+ * seriesIdx, chartId). No runtime state mutated; no UxResponse
+ * emission. `stateClass: "C-local"` + `persistsTo: "none"`.
+ *
+ * Type re-exports (`ChartStyle`, `SeriesColorMode`) move the non-
+ * public chart-style-table types onto the v3 surface so presentation
+ * consumers don't have to peek into `src/io/ooxml/chart/**` for
+ * types either. This mirrors the pattern `public-types.ts` uses for
+ * chart-model types (`export type * from "../model/chart-types"`).
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type { ChartModel, ColorRef, ResolvedTheme } from "../../public-types.ts";
+import {
+  composeSeriesColor as composeSeriesColorImpl,
+  deriveResolvedColors as deriveResolvedColorsImpl,
+} from "../../../io/ooxml/chart/compose-series-color.ts";
+import { resolveColor as resolveColorImpl } from "../../../io/ooxml/chart/resolve-color.ts";
+import { paletteColorRef as paletteColorRefImpl } from "../../../io/ooxml/chart/color-palette.ts";
+import {
+  getChartStyle as getChartStyleImpl,
+  resolveChartStyleId as resolveChartStyleIdImpl,
+  type ChartStyle,
+  type SeriesColorMode,
+} from "../../../io/ooxml/chart/chart-style-table.ts";
+import {
+  chartModelStore,
+  type ChartStoreEntry,
+} from "../../../runtime/chart/chart-model-store.ts";
+
+// Re-exports — presentation consumers migrating off `src/io/**` reach
+// for these types through the v3 namespace.
+export type { ChartStyle, SeriesColorMode, ChartStoreEntry };
+
+// ---------------------------------------------------------------------
+// L11-facing named re-exports (coord-11 §4.1 migration seam)
+// ---------------------------------------------------------------------
+//
+// The chart renderers at `src/ui-tailwind/chart/render/**` +
+// `src/ui-tailwind/editor-surface/chart-node-view.tsx` are pure React
+// consumers of these helpers — no runtime handle in scope. Exposing
+// the helpers as top-level named exports (identity re-exports of the
+// same impls the factory binds) lets those consumers migrate their
+// imports from `src/io/ooxml/chart/**` + `src/runtime/chart/**` onto
+// the v3 seam without threading the factory instance through props /
+// context. Matches the pattern `table.ts` established for
+// `TableSelectionDescriptor` (type re-export), extended to values
+// because these are structurally pure + read-only.
+//
+// Agents still use `api.runtime.chart.*` via `createChartFamily(...)`;
+// both paths delegate to identical implementations, and the live-parity
+// tests cover the factory path.
+export {
+  composeSeriesColorImpl as composeSeriesColor,
+  deriveResolvedColorsImpl as deriveResolvedColors,
+};
+export { resolveColorImpl as resolveColor };
+export { paletteColorRefImpl as paletteColorRef };
+export {
+  getChartStyleImpl as getChartStyle,
+  resolveChartStyleIdImpl as resolveChartStyleId,
+};
+
+/**
+ * L11-facing read of the runtime chart-model store. Thin wrapper over
+ * `chartModelStore.get(chartId)` — mirrors what
+ * `api.runtime.chart.getModel(chartId)` does on a bound factory, but
+ * surface-callable without a runtime handle because the store itself
+ * is a module-level singleton populated by the surface-projection
+ * pass. Presentation callers (ChartNodeView) use this form so they
+ * don't reach into `src/runtime/chart/**` directly.
+ */
+export function getChartModel(chartId: string): ChartStoreEntry | null {
+  return chartModelStore.get(chartId) ?? null;
+}
+
+/* ================================================================== */
+/*  composeSeriesColor                                                */
+/* ================================================================== */
+
+export const composeSeriesColorMetadata: ApiV3FnMetadata = {
+  name: "runtime.chart.composeSeriesColor",
+  status: "live",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-chart-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "chart-color",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.chart.composeSeriesColor. Direct delegation to composeSeriesColor (src/io/ooxml/chart/compose-series-color.ts). Stitches the 3-layer OOXML chart-color cascade: explicit per-series override → palette (chart-style seriesColorMode) → resolveColor(ref, theme). Always returns #RRGGBB.",
+};
+
+/* ================================================================== */
+/*  deriveResolvedColors                                              */
+/* ================================================================== */
+
+export const deriveResolvedColorsMetadata: ApiV3FnMetadata = {
+  name: "runtime.chart.deriveResolvedColors",
+  status: "live",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-chart-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "chart-color",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.chart.deriveResolvedColors. Pre-composes the full series (or slice) color list so renderers don't touch the chart-style table in hot paths. Delegates to deriveResolvedColors (src/io/ooxml/chart/compose-series-color.ts).",
+};
+
+/* ================================================================== */
+/*  resolveColor                                                      */
+/* ================================================================== */
+
+export const resolveColorMetadata: ApiV3FnMetadata = {
+  name: "runtime.chart.resolveColor",
+  status: "live",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-chart-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "chart-color",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.chart.resolveColor. Direct delegation to resolveColor (src/io/ooxml/chart/resolve-color.ts). Resolves a ColorRef against the workbook theme + applies OOXML modifiers (lumMod/lumOff/shade/tint/satMod/hueMod). Always returns #RRGGBB; falls through to #808080 on bad inputs.",
+};
+
+/* ================================================================== */
+/*  paletteColorRef                                                   */
+/* ================================================================== */
+
+export const paletteColorRefMetadata: ApiV3FnMetadata = {
+  name: "runtime.chart.paletteColorRef",
+  status: "live",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-chart-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "chart-color",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.chart.paletteColorRef. Returns the ColorRef for a given series index under a SeriesColorMode (accent1-6 round-robin or monochromatic accent with tint/shade variations). Direct delegation to paletteColorRef (src/io/ooxml/chart/color-palette.ts).",
+};
+
+/* ================================================================== */
+/*  getChartStyle                                                     */
+/* ================================================================== */
+
+export const getChartStyleMetadata: ApiV3FnMetadata = {
+  name: "runtime.chart.getChartStyle",
+  status: "live",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-chart-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "chart-style",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.chart.getChartStyle. Returns the ChartStyle descriptor (seriesColorMode + fill/stroke/text defaults) for a given style id. Unknown ids fall through to the default ChartStyle (id=2). Direct delegation to getChartStyle (src/io/ooxml/chart/chart-style-table.ts).",
+};
+
+/* ================================================================== */
+/*  resolveChartStyleId                                               */
+/* ================================================================== */
+
+export const resolveChartStyleIdMetadata: ApiV3FnMetadata = {
+  name: "runtime.chart.resolveChartStyleId",
+  status: "live",
+  sourceLayer: "package-session",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-chart-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "chart-style",
+  },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.chart.resolveChartStyleId. Normalizes a raw (possibly undefined / out-of-range) chart-style id to one of the known CHART_STYLES keys. Returns DEFAULT_CHART_STYLE_ID (2) on miss. Direct delegation to resolveChartStyleId (src/io/ooxml/chart/chart-style-table.ts).",
+};
+
+/* ================================================================== */
+/*  getModel — chartModelStore read                                   */
+/* ================================================================== */
+
+export const getModelMetadata: ApiV3FnMetadata = {
+  name: "runtime.chart.getModel",
+  status: "live",
+  sourceLayer: "runtime-core",
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-chart-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: {
+    readOrMutate: "read",
+    boundedScope: "document",
+    auditCategory: "chart-model-read",
+  },
+  stateClass: "A-canonical",
+  persistsTo: "canonical",
+  rwdReference:
+    "§Runtime API § runtime.chart.getModel. Read-side lookup over the runtime-owned chartModelStore (src/runtime/chart/chart-model-store.ts) keyed by stable chartId. Returns the parsed ChartModel + px dimensions + resolved theme the surface-projection pass populated, or null when the id does not enumerate. Write-side (set/beginBuildPass/endBuildPass) stays internal to the runtime.",
+};
+
+/* ================================================================== */
+/*  family factory                                                    */
+/* ================================================================== */
+
+export function createChartFamily(_runtime: RuntimeApiHandle) {
+  // Runtime handle is accepted for factory-signature symmetry with the
+  // sibling families; every helper below is either a pure function over
+  // its inputs or a direct store read — no DocumentRuntime reads here.
+  return {
+    composeSeriesColor(
+      model: ChartModel,
+      theme: ResolvedTheme,
+      seriesIdx: number,
+    ): string {
+      // @endStateApi — live.
+      return composeSeriesColorImpl(model, theme, seriesIdx);
+    },
+
+    deriveResolvedColors(model: ChartModel, theme: ResolvedTheme): string[] {
+      // @endStateApi — live.
+      return deriveResolvedColorsImpl(model, theme);
+    },
+
+    resolveColor(ref: ColorRef, theme: ResolvedTheme): string {
+      // @endStateApi — live.
+      return resolveColorImpl(ref, theme);
+    },
+
+    paletteColorRef(mode: SeriesColorMode, seriesIdx: number): ColorRef {
+      // @endStateApi — live.
+      return paletteColorRefImpl(mode, seriesIdx);
+    },
+
+    getChartStyle(id: number | undefined): ChartStyle {
+      // @endStateApi — live.
+      return getChartStyleImpl(id);
+    },
+
+    resolveChartStyleId(raw: number | undefined): number {
+      // @endStateApi — live.
+      return resolveChartStyleIdImpl(raw);
+    },
+
+    getModel(chartId: string): ChartStoreEntry | null {
+      // @endStateApi — live. Read-only lookup against the runtime's
+      // chartModelStore. Returns null instead of undefined so agents
+      // branch cleanly on `result === null`.
+      return chartModelStore.get(chartId) ?? null;
+    },
+  };
+}

package/src/api/v3/runtime/clipboard.ts

@@ -0,0 +1,81 @@
+/**
+ * @endStateApi v3 — `runtime.clipboard` family.
+ *
+ * Single function: `parse({payload, hint})`. Live delegation to the
+ * shipped paste-parser pipeline in `src/io/paste/**`
+ * (`parseCanonicalFragmentFromWordML` + `parseCanonicalFragmentFromHtml`),
+ * which in turn routes through the authoritative
+ * `parseMainDocumentXml` → `normalizeParsedTextDocument` chain.
+ *
+ * Ships coord-07 §2.1 first family — coord-11 §4.2 asked for a
+ * Runtime API seam so agents + headless services can parse WordML /
+ * HTML clipboard payloads into `CanonicalDocumentFragment` without
+ * reaching into `src/io/paste/**` directly. The existing
+ * `PasteFragmentParserAdapter` (refactor/11 Slice 5) remains the PM
+ * command bridge's native seam; `runtime.clipboard.parse` is the
+ * agent-facing surface and can back the shell adapter when hosts
+ * migrate off `shellPasteFragmentParser`.
+ *
+ * Pure-function read: no runtime state touched, no UxResponse emitted,
+ * no broadcast. `stateClass: "C-local"` + `persistsTo: "none"` +
+ * `readOrMutate: "read"`. See `docs/architecture/07-runtime-api.md` §R9
+ * for the state-class taxonomy.
+ */
+
+import type { RuntimeApiHandle } from "../_runtime-handle.ts";
+import type { ApiV3FnMetadata } from "../_layer-metadata.ts";
+import type { CanonicalDocumentFragment } from "../../public-types.ts";
+import { parseCanonicalFragmentFromWordML } from "../../../io/paste/word-clipboard.ts";
+import { parseCanonicalFragmentFromHtml } from "../../../io/paste/html-clipboard.ts";
+
+/**
+ * Discriminator — the two rich formats the shipped pipeline supports.
+ * Plain-text paste is handled by the PM bridge's Tier A path directly;
+ * exposing it here would be a no-op wrapper around `String(payload)`.
+ */
+export type ClipboardHint = "wordml" | "html";
+
+export interface ClipboardParseInput {
+  readonly payload: string;
+  readonly hint: ClipboardHint;
+}
+
+export type ClipboardParseResult =
+  | { readonly ok: true; readonly fragment: CanonicalDocumentFragment }
+  | { readonly ok: false; readonly reason: string };
+
+export const parseMetadata: ApiV3FnMetadata = {
+  name: "runtime.clipboard.parse",
+  status: "live",
+  sourceLayer: "package-session",
+  // Direct delegation to the shipped Tier B paste parsers — no
+  // adapter debt. Validator log is the same corpus the parsers
+  // themselves ship under; runnerTest covers the v3 shape.
+  liveEvidence: {
+    runnerTest: "test/api/v3/live-parity.test.ts",
+    commit: "refactor-07-clipboard-family-2026-04-23",
+  },
+  uxIntent: { uiVisible: false, expectsUxResponse: "none" },
+  agentMetadata: { readOrMutate: "read", boundedScope: "document", auditCategory: "clipboard-parse" },
+  stateClass: "C-local",
+  persistsTo: "none",
+  rwdReference:
+    "§Runtime API § runtime.clipboard.parse. Delegates to parseCanonicalFragmentFromWordML / parseCanonicalFragmentFromHtml (src/io/paste/**). Pure-function read — parse a string payload into a `CanonicalDocumentFragment`. Failure returns `{ok:false, reason}` instead of throwing so callers can fall back to plain-text paste (matches the pm-command-bridge `PasteFragmentParserAdapter` contract shipped by refactor/11 Slice 5).",
+};
+
+export function createClipboardFamily(_runtime: RuntimeApiHandle) {
+  // Runtime handle is accepted for factory-signature symmetry with the
+  // sibling families; no state is read. Parser is pure over its string
+  // input.
+  return {
+    parse(input: ClipboardParseInput): ClipboardParseResult {
+      // @endStateApi — live. Dispatches on the hint; returns structured
+      // failure on empty / malformed payloads so callers can gracefully
+      // fall through (matches the native adapter's shape).
+      if (input.hint === "wordml") {
+        return parseCanonicalFragmentFromWordML(input.payload);
+      }
+      return parseCanonicalFragmentFromHtml(input.payload);
+    },
+  };
+}