@beyondwork/docx-react-component 1.0.42 → 1.0.45

package/src/io/chart-preview-resolver.ts

@@ -0,0 +1,281 @@
+/**
+ * Stage 0B.1 — chart preview resolver.
+ *
+ * Given a freshly imported `CanonicalDocument` and the source
+ * `OpcPackage`, iterate every `chart_preview` inline node whose
+ * `previewMediaId` is unset, extract the chart part XML + theme, and
+ * ask the host adapter's `renderChartPreview` callback for preview
+ * bytes. Successful returns become synthesized `MediaItem` entries on
+ * the document; unresolved charts keep their existing shape so
+ * downstream rendering falls back to the Stage 0 typed badge.
+ *
+ * Pure Node-side. No React imports. Not reachable from the edit path
+ * (runs at import time only) so §Performance Invariants in CLAUDE.md
+ * about synchronous layout reads do not apply.
+ *
+ * See docs/plans/lane-5-charts.md §2 Task 2.
+ */
+
+import type {
+  BlockNode,
+  CanonicalDocument,
+  ChartPreviewNode,
+  DocumentRootNode,
+  InlineNode,
+  MediaItem,
+  ParagraphNode,
+} from "../model/canonical-document.ts";
+import type {
+  ChartPreviewResolveParams,
+  EditorHostAdapter,
+} from "../api/public-types.ts";
+import type { OpcPackage } from "./opc/package-reader.ts";
+import { normalizePartPath, resolveRelationshipTarget } from "./ooxml/part-manifest.ts";
+
+interface ResolveContext {
+  readonly package: OpcPackage;
+  readonly adapter: EditorHostAdapter;
+  readonly themeXml: string | undefined;
+  /** Monotonic counter so we can generate unique media ids across one run. */
+  seq: number;
+}
+
+interface PendingResolution {
+  /** Path from the document root to the chart_preview node, used to surgically replace the node on resolution. */
+  readonly pointer: Pointer;
+  readonly node: ChartPreviewNode;
+  readonly chartPartPath: string;
+  readonly chartXml: string;
+  readonly widthEmu: number;
+  readonly heightEmu: number;
+}
+
+type Pointer = Array<number>;
+
+export async function resolveChartPreviewsForDocument(
+  doc: CanonicalDocument,
+  pkg: OpcPackage,
+  adapter: EditorHostAdapter | undefined,
+): Promise<CanonicalDocument> {
+  if (!adapter?.renderChartPreview) return doc;
+
+  const pending = collectUnresolvedChartPreviews(doc, pkg);
+  if (pending.length === 0) return doc;
+
+  const themeXml = extractPartTextFromPackage(pkg, "/word/theme/theme1.xml");
+  const renderer = adapter.renderChartPreview;
+  const ctx: ResolveContext = { package: pkg, adapter, themeXml, seq: 0 };
+
+  const resolutions = await Promise.all(
+    pending.map(async (entry) => {
+      const params: ChartPreviewResolveParams = {
+        chartXml: entry.chartXml,
+        chartPartPath: entry.chartPartPath,
+        themeXml,
+        widthEmu: entry.widthEmu,
+        heightEmu: entry.heightEmu,
+      };
+      try {
+        const bytes = await renderer(params);
+        if (!bytes || bytes.length === 0) return null;
+        return { entry, bytes };
+      } catch (err) {
+        try {
+          adapter.logEvent?.({
+            type: "chart_preview_render_failed",
+            documentId: doc.docId,
+            detail: {
+              chartPartPath: entry.chartPartPath,
+              message: err instanceof Error ? err.message : String(err),
+            },
+          });
+        } catch {
+          // Host's logEvent can throw too; swallow silently — one chart failing
+          // must never surface as an unhandled rejection during import.
+        }
+        return null;
+      }
+    }),
+  );
+
+  const successful = resolutions.filter(
+    (r): r is { entry: PendingResolution; bytes: Uint8Array } => r !== null,
+  );
+  if (successful.length === 0) return doc;
+
+  void ctx; // resolveContext is reserved for future use (caching, progress events)
+  return applyResolutions(doc, successful);
+}
+
+/**
+ * Walk the whole content tree and yield one PendingResolution per
+ * chart_preview node that (a) has no previewMediaId yet and (b) can
+ * resolve its chart part from the package. The pointer path lets
+ * `applyResolutions` rewrite those exact nodes without touching the
+ * surrounding structure.
+ */
+function collectUnresolvedChartPreviews(doc: CanonicalDocument, pkg: OpcPackage): PendingResolution[] {
+  const out: PendingResolution[] = [];
+  const documentRels = collectDocumentPartRelationships(pkg);
+
+  const paragraphs = doc.content.children;
+  for (let i = 0; i < paragraphs.length; i++) {
+    const block = paragraphs[i]!;
+    if (block.type !== "paragraph") continue;
+    const paragraph = block as ParagraphNode;
+    for (let j = 0; j < paragraph.children.length; j++) {
+      const child = paragraph.children[j];
+      if (!child || child.type !== "chart_preview") continue;
+      const chartNode = child as ChartPreviewNode;
+      if (chartNode.previewMediaId) continue;
+      const resolved = resolveChartPart(chartNode, documentRels, pkg);
+      if (!resolved) continue;
+      out.push({
+        pointer: [i, j],
+        node: chartNode,
+        chartPartPath: resolved.chartPartPath,
+        chartXml: resolved.chartXml,
+        widthEmu: resolved.widthEmu,
+        heightEmu: resolved.heightEmu,
+      });
+    }
+  }
+  return out;
+}
+
+function collectDocumentPartRelationships(pkg: OpcPackage): Map<string, string> {
+  // Only walk /word/document.xml for Stage 0B.1; headers/footers/endnotes
+  // carry charts rarely and will be a later iteration.
+  const docPart = pkg.parts.get("/word/document.xml");
+  if (!docPart?.relationships) return new Map();
+  const map = new Map<string, string>();
+  for (const rel of docPart.relationships) {
+    if (rel.targetMode !== "internal") continue;
+    if (!rel.type.endsWith("/chart")) continue;
+    const target = resolveRelationshipTarget("/word/document.xml", rel);
+    map.set(rel.id, normalizePartPath(target));
+  }
+  return map;
+}
+
+interface ResolvedChartLocation {
+  chartPartPath: string;
+  chartXml: string;
+  widthEmu: number;
+  heightEmu: number;
+}
+
+function resolveChartPart(
+  node: ChartPreviewNode,
+  documentRels: Map<string, string>,
+  pkg: OpcPackage,
+): ResolvedChartLocation | null {
+  const relId = extractChartRelId(node.rawXml);
+  if (!relId) return null;
+  const chartPartPath = documentRels.get(relId);
+  if (!chartPartPath) return null;
+  const chartXml = extractPartTextFromPackage(pkg, chartPartPath);
+  if (!chartXml) return null;
+  const extent = extractDrawingExtent(node.rawXml);
+  return {
+    chartPartPath,
+    chartXml,
+    widthEmu: extent.widthEmu,
+    heightEmu: extent.heightEmu,
+  };
+}
+
+/** Find `<c:chart ... r:id="rIdN"/>` and return the relationship id. */
+function extractChartRelId(rawXml: string): string | null {
+  const match = /<c:chart\b[^>]*?r:id="([^"]+)"/.exec(rawXml);
+  return match ? match[1]! : null;
+}
+
+/** Read `<wp:extent cx="..." cy="..."/>` out of the drawing XML. */
+function extractDrawingExtent(rawXml: string): { widthEmu: number; heightEmu: number } {
+  const match = /<wp:extent\b([^/>]*)\/>/.exec(rawXml);
+  if (!match) return { widthEmu: 5486400, heightEmu: 3200400 };
+  const attrs = match[1] ?? "";
+  const cx = /\bcx="(\d+)"/.exec(attrs)?.[1];
+  const cy = /\bcy="(\d+)"/.exec(attrs)?.[1];
+  return {
+    widthEmu: cx ? parseInt(cx, 10) : 5486400,
+    heightEmu: cy ? parseInt(cy, 10) : 3200400,
+  };
+}
+
+function extractPartTextFromPackage(pkg: OpcPackage, path: string): string | undefined {
+  const part = pkg.parts.get(path);
+  if (!part?.bytes) return undefined;
+  try {
+    return new TextDecoder("utf-8").decode(part.bytes);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Produce a new CanonicalDocument with the resolved chart_preview
+ * nodes carrying previewMediaId + corresponding MediaCatalog entries.
+ * Never mutates the input doc.
+ */
+function applyResolutions(
+  doc: CanonicalDocument,
+  resolutions: Array<{ entry: PendingResolution; bytes: Uint8Array }>,
+): CanonicalDocument {
+  const newMediaItems: Record<string, MediaItem> = { ...doc.media.items };
+  const updates = new Map<string, { previewMediaId: string }>();
+
+  let seq = 0;
+  for (const { entry, bytes } of resolutions) {
+    seq += 1;
+    const contentType = inferPreviewContentType(bytes);
+    const extension = contentType === "image/png" ? "png" : "svg";
+    const packagePartName = `/word/media/chart-preview-synth-${seq}.${extension}`;
+    const mediaId = `media:word/media/chart-preview-synth-${seq}.${extension}`;
+    newMediaItems[mediaId] = {
+      mediaId,
+      contentType,
+      filename: packagePartName.slice(packagePartName.lastIndexOf("/") + 1),
+      packagePartName,
+      widthEmu: entry.widthEmu,
+      heightEmu: entry.heightEmu,
+    };
+    const pointerKey = entry.pointer.join(",");
+    updates.set(pointerKey, { previewMediaId: mediaId });
+  }
+
+  if (updates.size === 0) return doc;
+
+  // Clone the content tree along pointer paths only — everything else
+  // keeps object identity so downstream React memoization stays stable.
+  const newParagraphs: BlockNode[] = doc.content.children.slice();
+  for (const [pointerKey, update] of updates) {
+    const [pi, ci] = pointerKey.split(",").map((s) => parseInt(s, 10)) as [number, number];
+    const paragraph = newParagraphs[pi];
+    if (!paragraph || paragraph.type !== "paragraph") continue;
+    const newChildren: InlineNode[] = (paragraph as ParagraphNode).children.slice();
+    const existing = newChildren[ci];
+    if (!existing || existing.type !== "chart_preview") continue;
+    newChildren[ci] = { ...(existing as ChartPreviewNode), previewMediaId: update.previewMediaId };
+    newParagraphs[pi] = { ...(paragraph as ParagraphNode), children: newChildren };
+  }
+
+  const newContent: DocumentRootNode = { ...doc.content, children: newParagraphs };
+  const newMedia = { items: newMediaItems };
+  return { ...doc, content: newContent, media: newMedia };
+}
+
+/**
+ * Content-type sniff from the first bytes of the rendered preview.
+ * PNG magic is 0x89 0x50 0x4E 0x47; everything else is assumed to be
+ * SVG text. Hosts that need a different content type should extend
+ * this in a follow-up.
+ */
+function inferPreviewContentType(bytes: Uint8Array): string {
+  if (bytes.length >= 4 &&
+      bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) {
+    return "image/png";
+  }
+  return "image/svg+xml";
+}