@beyondwork/docx-react-component 1.0.67 → 1.0.70

package/src/session/shared/protection.ts

@@ -0,0 +1,228 @@
+/**
+ * Protection-range extraction helpers shared by the import (load) and
+ * export paths inside the session layer. These walk parsed OOXML to
+ * discover `w:permStart` / `w:permEnd` markers, measure canonical
+ * positions along the way, and compose a `ProtectionSnapshot` that
+ * encodes whether the runtime will enforce or only preserve each
+ * range.
+ *
+ * Slice 5e-7.a — relocated from `src/io/docx-session.ts` (was the 5e-6f.2
+ * deferral: these helpers are load-and-export shared, so they couldn't
+ * live under `src/session/export/` with the other stateful-export helpers
+ * from 5e-6f.1). `src/session/shared/` is the co-scope home — load path
+ * and export path both reach here without crossing each other's boundary.
+ */
+
+import type {
+  ProtectionRange,
+  ProtectionSnapshot,
+} from "../../api/public-types.ts";
+import {
+  parseMainDocumentXml,
+  type ParsedBlockNode,
+  type ParsedInlineNode,
+} from "../../io/ooxml/parse-main-document.ts";
+
+export interface DocumentProtectionMeta {
+  editType?: string;
+  enforcement: boolean;
+}
+
+export const EMPTY_PROTECTION_SNAPSHOT: ProtectionSnapshot = {
+  hasDocumentProtection: false,
+  enforcementActive: false,
+  ranges: [],
+  enforcedRangeCount: 0,
+  preservedRangeCount: 0,
+};
+
+export function extractDocumentProtection(
+  settingsXml: string,
+): DocumentProtectionMeta {
+  if (!settingsXml) return { enforcement: false };
+  const match = settingsXml.match(/<w:documentProtection\b([^/>]*)\/?>/);
+  if (!match) return { enforcement: false };
+  const attrs = match[1];
+  const editTypeMatch = attrs.match(/w:edit="([^"]*)"/);
+  const enforcementMatch = attrs.match(/w:enforcement="([^"]*)"/);
+  const editType = editTypeMatch?.[1];
+  const enforcement =
+    enforcementMatch?.[1] === "1" || enforcementMatch?.[1] === "true";
+  return { editType, enforcement };
+}
+
+export function extractProtectionRanges(
+  blocks: readonly ParsedBlockNode[],
+): ProtectionRange[] {
+  const ranges: ProtectionRange[] = [];
+  const openRanges = new Map<string, Omit<ProtectionRange, "end">>();
+  collectProtectionRangesFromBlocks(blocks, ranges, openRanges, 0);
+  return ranges;
+}
+
+export function collectProtectionRangesFromBlocks(
+  blocks: readonly ParsedBlockNode[],
+  ranges: ProtectionRange[],
+  openRanges: Map<string, Omit<ProtectionRange, "end">>,
+  cursor: number,
+): number {
+  let nextCursor = cursor;
+  let previousParagraph = false;
+
+  for (const block of blocks) {
+    if (block.type === "paragraph") {
+      if (previousParagraph) {
+        nextCursor += 1;
+      }
+      nextCursor = collectProtectionRangesFromInlines(
+        block.children,
+        ranges,
+        openRanges,
+        nextCursor,
+      );
+      previousParagraph = true;
+      continue;
+    }
+
+    if (block.type === "table") {
+      nextCursor += 1;
+      previousParagraph = false;
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          nextCursor = collectProtectionRangesFromBlocks(
+            cell.children,
+            ranges,
+            openRanges,
+            nextCursor,
+          );
+        }
+      }
+      continue;
+    }
+
+    if (block.type === "sdt" || block.type === "custom_xml") {
+      nextCursor = collectProtectionRangesFromBlocks(
+        block.children,
+        ranges,
+        openRanges,
+        nextCursor,
+      );
+      previousParagraph = false;
+      continue;
+    }
+
+    nextCursor += 1;
+    previousParagraph = false;
+  }
+
+  return nextCursor;
+}
+
+export function collectProtectionRangesFromInlines(
+  nodes: readonly ParsedInlineNode[],
+  ranges: ProtectionRange[],
+  openRanges: Map<string, Omit<ProtectionRange, "end">>,
+  cursor: number,
+): number {
+  let nextCursor = cursor;
+
+  for (const node of nodes) {
+    if (node.type === "perm_start") {
+      openRanges.set(node.rangeId, {
+        rangeId: node.rangeId,
+        start: nextCursor,
+        ...(node.editorGroup ? { editorGroup: node.editorGroup } : {}),
+        ...(node.editor ? { editor: node.editor } : {}),
+        enforced: false,
+        enforcementReason:
+          "preserve-only: runtime does not yet enforce permission range boundaries",
+      });
+      continue;
+    }
+
+    if (node.type === "perm_end") {
+      const openRange = openRanges.get(node.rangeId);
+      if (openRange) {
+        ranges.push({
+          ...openRange,
+          end: nextCursor,
+        });
+        openRanges.delete(node.rangeId);
+      }
+      continue;
+    }
+
+    nextCursor += measureParsedInlineNode(node);
+  }
+
+  return nextCursor;
+}
+
+export function measureParsedInlineNode(node: ParsedInlineNode): number {
+  switch (node.type) {
+    case "text":
+      return Array.from(node.text).length;
+    case "tab":
+    case "hard_break":
+    case "column_break":
+    case "footnote_ref":
+    case "image":
+    case "bookmark_start":
+    case "bookmark_end":
+      return 1;
+    case "hyperlink":
+      return node.children.reduce(
+        (size, child) => size + measureParsedInlineNode(child),
+        0,
+      );
+    case "field": {
+      const content = parseMainDocumentXml(
+        `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body><w:p>${node.contentXml}</w:p></w:body></w:document>`,
+      );
+      if (content.blocks[0]?.type === "paragraph") {
+        return content.blocks[0].children.reduce(
+          (size, child) => size + measureParsedInlineNode(child),
+          0,
+        );
+      }
+      return 1;
+    }
+    default:
+      return 1;
+  }
+}
+
+export function buildProtectionSnapshot(
+  documentProtection: DocumentProtectionMeta,
+  ranges: ProtectionRange[],
+): ProtectionSnapshot {
+  const hasDocumentProtection =
+    documentProtection.editType !== undefined || documentProtection.enforcement;
+  const enforceRanges =
+    documentProtection.editType === "readOnly" ||
+    documentProtection.editType === "comments";
+  const normalizedRanges = ranges.map((range) => {
+    const canEnforce =
+      hasDocumentProtection &&
+      documentProtection.enforcement &&
+      enforceRanges &&
+      typeof range.start === "number" &&
+      typeof range.end === "number" &&
+      range.end >= range.start;
+    return {
+      ...range,
+      enforced: canEnforce,
+      enforcementReason: canEnforce
+        ? "runtime-enforced: permission range is mapped to canonical positions"
+        : "preserve-only: runtime does not yet enforce permission range boundaries",
+    };
+  });
+  return {
+    hasDocumentProtection,
+    editType: documentProtection.editType,
+    enforcementActive: documentProtection.enforcement,
+    ranges: normalizedRanges,
+    enforcedRangeCount: normalizedRanges.filter((r) => r.enforced).length,
+    preservedRangeCount: normalizedRanges.filter((r) => !r.enforced).length,
+  };
+}

package/src/session/shared/session-utils.ts

@@ -0,0 +1,82 @@
+/**
+ * Tiny pure helpers shared by the session load and export paths.
+ *
+ * Slice 5e-7.d-prep — relocated from `src/io/docx-session.ts` so the
+ * loader-body extraction in 5e-7.d doesn't also need to carry the
+ * utilities with it. Each helper has a small, well-defined scope:
+ *
+ *   - `toUint8Array` / `decodeUtf8` — byte conversions used by every
+ *     parse-dispatch stage that reads OPC part bytes.
+ *   - `createEmptyNumberingCatalog` — sentinel used on the error path
+ *     when a canonical document has no numbering.
+ *   - `extractDocumentRootAttributes` — one-off regex scan for the
+ *     `<w:document>` element's attribute bag (preserved at export time
+ *     for opaque-attribute fidelity).
+ *   - `serializeCanonicalDocumentForExport` — canonical-document
+ *     signature wrapper that zeroes out `docId` / `createdAt` /
+ *     `updatedAt` so structural comparison doesn't falsely register
+ *     semantic drift.
+ *
+ * P6-clean: imports only from `src/model/**` + `src/api/**`.
+ */
+
+import {
+  createCanonicalDocumentSignature,
+  type CanonicalDocument,
+  type NumberingCatalog,
+} from "../../model/canonical-document.ts";
+
+const UTF8_DECODER = new TextDecoder("utf-8");
+
+export function decodeUtf8(bytes: Uint8Array | undefined): string {
+  if (!bytes) {
+    return "";
+  }
+  return UTF8_DECODER.decode(bytes);
+}
+
+export function toUint8Array(bytes: Uint8Array | ArrayBuffer): Uint8Array {
+  return bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+}
+
+export function createEmptyNumberingCatalog(): NumberingCatalog {
+  return {
+    abstractDefinitions: {},
+    instances: {},
+  };
+}
+
+export function extractDocumentRootAttributes(
+  documentXml: string,
+): Record<string, string> {
+  const match = documentXml.match(
+    /<(?:[A-Za-z_][A-Za-z0-9:._-]*:)?document\b([^>]*)>/u,
+  );
+  if (!match) {
+    return {};
+  }
+
+  const attributes: Record<string, string> = {};
+  const pattern = /([A-Za-z_][A-Za-z0-9:._-]*)\s*=\s*("([^"]*)"|'([^']*)')/gu;
+  for (const attributeMatch of (match[1] ?? "").matchAll(pattern)) {
+    const name = attributeMatch[1];
+    const value = attributeMatch[3] ?? attributeMatch[4] ?? "";
+    if (!name) {
+      continue;
+    }
+    attributes[name] = value;
+  }
+
+  return attributes;
+}
+
+export function serializeCanonicalDocumentForExport(
+  document: CanonicalDocument,
+): string {
+  return createCanonicalDocumentSignature({
+    ...document,
+    docId: "__export__",
+    createdAt: "__export__",
+    updatedAt: "__export__",
+  });
+}