@beyondwork/docx-react-component 1.0.29 → 1.0.31

package/src/io/ooxml/workflow-payload.ts

@@ -0,0 +1,544 @@
+import type { OpcPackage } from "../opc/package-reader.ts";
+import type {
+  OpcCompressionMethod,
+  OpcRelationship,
+} from "./part-manifest.ts";
+import type {
+  WorkflowMetadataDefinition,
+  WorkflowMetadataEntry,
+  WorkflowMetadataSnapshot,
+} from "../../api/public-types.ts";
+
+export const WORKFLOW_PAYLOAD_PART_PATH = "/customXml/item1.xml";
+export const WORKFLOW_PAYLOAD_ITEM_PROPS_PART_PATH = "/customXml/itemProps1.xml";
+export const WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH = "/docProps/custom.xml";
+export const WORKFLOW_PAYLOAD_CONTENT_TYPE = "application/xml";
+export const WORKFLOW_PAYLOAD_ITEM_PROPS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.customXmlProperties+xml";
+export const WORKFLOW_PAYLOAD_CUSTOM_PROPS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.custom-properties+xml";
+export const WORKFLOW_PAYLOAD_ITEM_PROPS_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/customXmlProps";
+export const WORKFLOW_PAYLOAD_CUSTOM_PROPS_RELATIONSHIP_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties";
+
+type EmbeddedWorkflowPayloadDescriptor = {
+  payloadId: string;
+  itemId: string;
+  documentId: string;
+  payloadPartPath: string;
+  itemPropsPartPath: string;
+};
+
+export function getDocumentBackedWorkflowMetadata(
+  snapshot: WorkflowMetadataSnapshot | undefined,
+): WorkflowMetadataSnapshot {
+  if (!snapshot) {
+    return { definitions: [], entries: [] };
+  }
+
+  const definitions = snapshot.definitions.filter(
+    (definition) => definition.persistence === "document-metadata",
+  );
+  const allowedIds = new Set(definitions.map((definition) => definition.metadataId));
+  const entries = snapshot.entries.filter((entry) => allowedIds.has(entry.metadataId));
+  return {
+    definitions,
+    entries,
+  };
+}
+
+export function buildWorkflowPayloadParts(input: {
+  sourcePackage: OpcPackage;
+  workflowMetadata: WorkflowMetadataSnapshot | undefined;
+  documentId: string;
+  createdAt: string;
+  updatedAt: string;
+  producerVersion: string;
+}): {
+  payloadPartPath: string;
+  itemPropsPartPath: string;
+  payloadPartXml: string;
+  itemPropsXml: string;
+  customPropertiesXml: string;
+  payloadRelationships: OpcRelationship[];
+  descriptor: EmbeddedWorkflowPayloadDescriptor;
+} | null {
+  const workflowMetadata = getDocumentBackedWorkflowMetadata(input.workflowMetadata);
+  if (workflowMetadata.definitions.length === 0 && workflowMetadata.entries.length === 0) {
+    return null;
+  }
+
+  const descriptor = resolveDescriptor(input.sourcePackage, input.documentId);
+  const payloadPartXml = buildPayloadXml({
+    descriptor,
+    createdAt: input.createdAt,
+    updatedAt: input.updatedAt,
+    producerVersion: input.producerVersion,
+    workflowMetadata,
+  });
+  const itemPropsXml = buildItemPropsXml(descriptor.itemId);
+  const customPropertiesXml = buildCustomPropertiesXml(descriptor, workflowMetadata, input.sourcePackage);
+
+  return {
+    payloadPartPath: descriptor.payloadPartPath,
+    itemPropsPartPath: descriptor.itemPropsPartPath,
+    payloadPartXml,
+    itemPropsXml,
+    customPropertiesXml: buildCustomPropertiesXml(descriptor, workflowMetadata, input.sourcePackage),
+    payloadRelationships: [
+      {
+        id: "rId1",
+        type: WORKFLOW_PAYLOAD_ITEM_PROPS_RELATIONSHIP_TYPE,
+        target: descriptor.itemPropsPartPath.split("/").pop() ?? "itemProps1.xml",
+        targetMode: "internal",
+      },
+    ],
+    descriptor,
+  };
+}
+
+export function parseWorkflowPayloadFromPackage(
+  sourcePackage: OpcPackage,
+): WorkflowMetadataSnapshot | undefined {
+  const payloadPartPath = resolvePayloadPartPath(sourcePackage);
+  if (!payloadPartPath) {
+    return undefined;
+  }
+  const payloadPart = sourcePackage.parts.get(payloadPartPath);
+  if (!payloadPart) {
+    return undefined;
+  }
+
+  const xml = decodeUtf8(payloadPart.bytes);
+  const entryMatches = [...xml.matchAll(/<bw:entry\b([^>]*)>([\s\S]*?)<\/bw:entry>/g)];
+  const definitions: WorkflowMetadataDefinition[] = [];
+  const entries: WorkflowMetadataEntry[] = [];
+
+  for (const match of entryMatches) {
+    const attributes = parseAttributes(match[1] ?? "");
+    if (!attributes.key) {
+      continue;
+    }
+    if (attributes.key.startsWith("definition.")) {
+      const metadataId = attributes.key.replace(/^definition\./, "");
+      const kind = attributes.ns ?? "tag-category";
+      const label = decodeText(match[2] ?? "");
+      if (!metadataId || !kind || !label) {
+        continue;
+      }
+      definitions.push({
+        metadataId,
+        kind,
+        label,
+        ...(attributes.source ? { color: attributes.source } : {}),
+        ...(attributes.status ? { icon: attributes.status } : {}),
+        persistence: "document-metadata",
+      });
+      continue;
+    }
+
+    const payloadText = decodeText(match[2] ?? "");
+    const targetKey = attributes.scope === "document"
+      ? undefined
+      : attributes.scope?.startsWith("scope:")
+        ? attributes.scope.slice("scope:".length)
+        : undefined;
+    const entryId = attributes.key;
+    const metadataId = attributes.metadataId ?? attributes.key;
+    if (!entryId || !metadataId) {
+      continue;
+    }
+    entries.push({
+      entryId,
+      metadataId,
+      anchor: {
+        kind: "range",
+        from: 0,
+        to: 0,
+        assoc: { start: -1, end: 1 },
+      },
+      storyTarget: parseWorkflowStoryTarget(attributes),
+      value: parseWorkflowMetadataValue(payloadText, attributes.valueType),
+      ...(targetKey ? { scopeId: targetKey } : {}),
+      ...(attributes.scope?.startsWith("workItem:")
+        ? { workItemId: attributes.scope.slice("workItem:".length) }
+        : {}),
+    });
+  }
+
+  return {
+    definitions,
+    entries,
+  };
+}
+
+function buildPayloadXml(input: {
+  descriptor: EmbeddedWorkflowPayloadDescriptor;
+  createdAt: string;
+  updatedAt: string;
+  producerVersion: string;
+  workflowMetadata: WorkflowMetadataSnapshot;
+}): string {
+  const definitionEntriesXml = input.workflowMetadata.definitions
+    .map((definition) => [
+      `<bw:entry`,
+      ` key="definition.${escapeXml(definition.metadataId)}"`,
+      ` type="string"`,
+      ` scope="document"`,
+      definition.kind ? ` ns="${escapeXml(definition.kind)}"` : "",
+      definition.color ? ` source="${escapeXml(definition.color)}"` : "",
+      definition.icon ? ` status="${escapeXml(definition.icon)}"` : "",
+      `>${escapeXml(definition.label)}</bw:entry>`,
+    ].join(""))
+    .join("\n");
+
+  const metadataEntriesXml = input.workflowMetadata.entries
+    .map((entry) => {
+      const serializedValue = serializeWorkflowMetadataValue(entry.value);
+      const storyTargetAttributes = serializeWorkflowStoryTarget(entry.storyTarget);
+
+      return [
+        `<bw:entry`,
+        ` key="${escapeXml(entry.entryId)}"`,
+        ` metadataId="${escapeXml(entry.metadataId)}"`,
+        ` type="string"`,
+        ` valueType="${escapeXml(serializedValue.type)}"`,
+        ` scope="${escapeXml(entry.scopeId ? `scope:${entry.scopeId}` : entry.workItemId ? `workItem:${entry.workItemId}` : "document")}"`,
+        storyTargetAttributes,
+        `>${escapeXml(serializedValue.text)}</bw:entry>`,
+      ].join("");
+    })
+    .filter((value) => value.length > 0)
+    .join("\n");
+
+  return [
+    `<?xml version="1.0" encoding="UTF-8"?>`,
+    `<bw:workflowPayload xmlns:bw="urn:beyondwork:workflow-payload:1" version="1.0" payloadId="${escapeXml(input.descriptor.payloadId)}" itemId="${escapeXml(input.descriptor.itemId)}" documentId="${escapeXml(input.descriptor.documentId)}" createdAt="${escapeXml(input.createdAt)}" updatedAt="${escapeXml(input.updatedAt)}">`,
+    `  <bw:manifest>`,
+    `    <bw:producer name="@beyondwork/docx-react-component" version="${escapeXml(input.producerVersion)}" />`,
+    `    <bw:compatibility rebindMode="best-effort" preserveUnknownExtensions="true" />`,
+    `  </bw:manifest>`,
+    `  <bw:metadata>`,
+    definitionEntriesXml ? indentLines(definitionEntriesXml, 4) : "",
+    metadataEntriesXml ? indentLines(metadataEntriesXml, 4) : "",
+    `  </bw:metadata>`,
+    `  <bw:extensions />`,
+    `</bw:workflowPayload>`,
+  ].filter((line) => line.length > 0).join("\n");
+}
+
+function buildItemPropsXml(itemId: string): string {
+  return [
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+    `<ds:datastoreItem ds:itemID="${escapeXml(itemId)}" xmlns:ds="http://schemas.openxmlformats.org/officeDocument/2006/customXmlDataProps">`,
+    `  <ds:schemaRefs />`,
+    `</ds:datastoreItem>`,
+  ].join("\n");
+}
+
+function buildCustomPropertiesXml(
+  descriptor: EmbeddedWorkflowPayloadDescriptor,
+  workflowMetadata: WorkflowMetadataSnapshot,
+  sourcePackage: OpcPackage,
+): string {
+  const existing = parseCustomPropertiesXml(
+    sourcePackage.parts.get(WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH)?.bytes,
+  );
+  const ownedNames = new Set([
+    "BwWorkflowSchemaVersion",
+    "BwWorkflowPayloadId",
+    "BwWorkflowPayloadItemId",
+    "BwWorkflowDocumentId",
+    "BwWorkflowMetadataSummary",
+  ]);
+  const preserved = existing.filter((entry) => !ownedNames.has(entry.name));
+  const maxPid = existing.reduce((max, entry) => Math.max(max, entry.pid), 1);
+  let nextPid = maxPid + 1;
+  const owned = [
+    { name: "BwWorkflowSchemaVersion", value: "1.0" },
+    { name: "BwWorkflowPayloadId", value: descriptor.payloadId },
+    { name: "BwWorkflowPayloadItemId", value: descriptor.itemId },
+    { name: "BwWorkflowDocumentId", value: descriptor.documentId },
+    {
+      name: "BwWorkflowMetadataSummary",
+      value: workflowMetadata.definitions.map((definition) => definition.metadataId).join(","),
+    },
+  ].map((entry) => {
+    const existingEntry = existing.find((candidate) => candidate.name === entry.name);
+    return buildCustomProperty(existingEntry?.pid ?? nextPid++, entry.name, entry.value);
+  });
+  const preservedXml = preserved.map((entry) => buildCustomProperty(entry.pid, entry.name, entry.value));
+  const properties = [...preservedXml, ...owned].join("\n");
+
+  return [
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
+    `<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/custom-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes">`,
+    properties,
+    `</Properties>`,
+  ].join("\n");
+}
+
+function buildCustomProperty(pid: number, name: string, value: string): string {
+  return `  <property fmtid="{D5CDD505-2E9C-101B-9397-08002B2CF9AE}" pid="${pid}" name="${escapeXml(name)}"><vt:lpwstr>${escapeXml(value)}</vt:lpwstr></property>`;
+}
+
+function serializeWorkflowMetadataValue(
+  value: WorkflowMetadataEntry["value"],
+): { type: "json"; text: string } {
+  return {
+    type: "json",
+    text: JSON.stringify(value ?? {}),
+  };
+}
+
+function parseWorkflowMetadataValue(
+  payloadText: string,
+  valueType: string | undefined,
+): WorkflowMetadataEntry["value"] {
+  const decodedText = decodeXmlEntities(payloadText);
+  if (!decodedText) {
+    return undefined;
+  }
+  if (!payloadText) {
+    return undefined;
+  }
+  if (valueType === "json") {
+    try {
+      const parsed = JSON.parse(decodedText) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed as WorkflowMetadataEntry["value"];
+      }
+      return { value: parsed };
+    } catch {
+      return { value: decodedText };
+    }
+  }
+  if (decodedText.includes("=")) {
+    const pairs = decodedText
+      .split(";")
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0)
+      .map((entry) => {
+        const separatorIndex = entry.indexOf("=");
+        if (separatorIndex <= 0) {
+          return null;
+        }
+        return [
+          entry.slice(0, separatorIndex),
+          entry.slice(separatorIndex + 1),
+        ] as const;
+      })
+      .filter((entry): entry is readonly [string, string] => entry !== null);
+    if (pairs.length > 0) {
+      return Object.fromEntries(pairs);
+    }
+  }
+  return { value: decodedText };
+}
+
+function serializeWorkflowStoryTarget(target: WorkflowMetadataEntry["storyTarget"]): string {
+  const storyTarget = target ?? { kind: "main" as const };
+  switch (storyTarget.kind) {
+    case "main":
+      return ` storyKind="main"`;
+    case "header":
+    case "footer":
+      return [
+        ` storyKind="${escapeXml(storyTarget.kind)}"`,
+        ` storyRelationshipId="${escapeXml(storyTarget.relationshipId)}"`,
+        ` storyVariant="${escapeXml(storyTarget.variant)}"`,
+        typeof storyTarget.sectionIndex === "number"
+          ? ` storySectionIndex="${String(storyTarget.sectionIndex)}"`
+          : "",
+      ].join("");
+    case "footnote":
+    case "endnote":
+      return [
+        ` storyKind="${escapeXml(storyTarget.kind)}"`,
+        ` storyNoteId="${escapeXml(storyTarget.noteId)}"`,
+      ].join("");
+  }
+}
+
+function parseWorkflowStoryTarget(
+  attributes: Record<string, string>,
+): WorkflowMetadataEntry["storyTarget"] {
+  const kind = attributes.storyKind;
+  switch (kind) {
+    case "header":
+    case "footer":
+      if (!attributes.storyRelationshipId || !attributes.storyVariant) {
+        return { kind: "main" };
+      }
+      return {
+        kind,
+        relationshipId: attributes.storyRelationshipId,
+        variant: attributes.storyVariant as "default" | "first" | "even",
+        sectionIndex: attributes.storySectionIndex !== undefined
+          ? Number(attributes.storySectionIndex)
+          : undefined,
+      };
+    case "footnote":
+    case "endnote":
+      if (!attributes.storyNoteId) {
+        return { kind: "main" };
+      }
+      return {
+        kind,
+        noteId: attributes.storyNoteId,
+      };
+    case "main":
+    default:
+      return { kind: "main" };
+  }
+}
+
+function resolveDescriptor(sourcePackage: OpcPackage, documentId: string): EmbeddedWorkflowPayloadDescriptor {
+  const existingPayloadPartPath = resolvePayloadPartPath(sourcePackage);
+  if (existingPayloadPartPath) {
+    const payloadPart = sourcePackage.parts.get(existingPayloadPartPath);
+    const xml = payloadPart ? decodeUtf8(payloadPart.bytes) : "";
+    const attributes = parseAttributes(xml.match(/<bw:workflowPayload\b([^>]*)>/)?.[1] ?? "");
+    const payloadId = attributes.payloadId ?? `bw-${simpleHash(documentId)}`;
+    const itemId = attributes.itemId ?? createDefaultItemId(documentId);
+    const itemNumber = extractItemNumber(existingPayloadPartPath) ?? 1;
+    return {
+      payloadId,
+      itemId,
+      documentId,
+      payloadPartPath: existingPayloadPartPath,
+      itemPropsPartPath: `/customXml/itemProps${itemNumber}.xml`,
+    };
+  }
+
+  const itemNumber = findNextAvailableItemNumber(sourcePackage);
+  const seed = simpleHash(documentId);
+  return {
+    payloadId: `bw-${seed}`,
+    itemId: createDefaultItemId(documentId),
+    documentId,
+    payloadPartPath: `/customXml/item${itemNumber}.xml`,
+    itemPropsPartPath: `/customXml/itemProps${itemNumber}.xml`,
+  };
+}
+
+function resolvePayloadPartPath(sourcePackage: OpcPackage): string | null {
+  const mirroredItemId = readCustomPropertyValue(
+    sourcePackage,
+    "BwWorkflowPayloadItemId",
+  );
+  const payloadCandidates = [...sourcePackage.parts.keys()]
+    .filter((path) => /^\/customXml\/item\d+\.xml$/u.test(path));
+
+  if (mirroredItemId) {
+    const mirroredMatch = payloadCandidates.find((path) => {
+      const payloadPart = sourcePackage.parts.get(path);
+      const xml = payloadPart ? decodeUtf8(payloadPart.bytes) : "";
+      const attributes = parseAttributes(xml.match(/<bw:workflowPayload\b([^>]*)>/)?.[1] ?? "");
+      return attributes.itemId === mirroredItemId;
+    });
+    if (mirroredMatch) {
+      return mirroredMatch;
+    }
+  }
+
+  const direct = payloadCandidates.find((path) => {
+    const payloadPart = sourcePackage.parts.get(path);
+    const xml = payloadPart ? decodeUtf8(payloadPart.bytes) : "";
+    return /<bw:workflowPayload\b/u.test(xml);
+  });
+  return direct ?? null;
+}
+
+function findNextAvailableItemNumber(sourcePackage: OpcPackage): number {
+  const numbers = [...sourcePackage.parts.keys()]
+    .map((path) => extractItemNumber(path))
+    .filter((value): value is number => typeof value === "number");
+  return (numbers.length > 0 ? Math.max(...numbers) : 0) + 1;
+}
+
+function extractItemNumber(path: string): number | null {
+  const match = path.match(/^\/customXml\/item(?:Props)?(\d+)\.xml$/u);
+  return match ? Number(match[1]) : null;
+}
+
+function createDefaultItemId(documentId: string): string {
+  const seed = simpleHash(documentId);
+  return `{${seed.slice(0, 8)}-${seed.slice(8, 12)}-${seed.slice(12, 16)}-${seed.slice(16, 20)}-${seed.slice(20, 32)}}`;
+}
+
+function parseCustomPropertiesXml(
+  bytes: Uint8Array | undefined,
+): Array<{ pid: number; name: string; value: string }> {
+  if (!bytes) {
+    return [];
+  }
+  const xml = decodeUtf8(bytes);
+  return [...xml.matchAll(/<property\b([^>]*)>([\s\S]*?)<\/property>/g)].map((match) => {
+    const attributes = parseAttributes(match[1] ?? "");
+    return {
+      pid: Number(attributes.pid ?? "0"),
+      name: attributes.name ?? "",
+      value: decodeText(match[2] ?? ""),
+    };
+  }).filter((entry) => entry.pid > 0 && entry.name.length > 0);
+}
+
+function readCustomPropertyValue(sourcePackage: OpcPackage, name: string): string | null {
+  return parseCustomPropertiesXml(
+    sourcePackage.parts.get(WORKFLOW_PAYLOAD_CUSTOM_PROPS_PART_PATH)?.bytes,
+  ).find((entry) => entry.name === name)?.value ?? null;
+}
+
+function simpleHash(input: string): string {
+  let hash = 2166136261;
+  for (const char of input) {
+    hash ^= char.charCodeAt(0);
+    hash = Math.imul(hash, 16777619);
+  }
+  const base = Math.abs(hash >>> 0).toString(16).padStart(8, "0");
+  return `${base}${base}${base}${base}`;
+}
+
+function parseAttributes(source: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  for (const match of source.matchAll(/([A-Za-z0-9:_-]+)="([^"]*)"/g)) {
+    attributes[match[1] ?? ""] = decodeXmlEntities(match[2] ?? "");
+  }
+  return attributes;
+}
+
+function indentLines(value: string, spaces: number): string {
+  const prefix = " ".repeat(spaces);
+  return value.split("\n").map((line) => `${prefix}${line}`).join("\n");
+}
+
+function decodeUtf8(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8").decode(bytes);
+}
+
+function decodeText(value: string): string {
+  return decodeXmlEntities(value)
+    .replace(/<[^>]+>/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function decodeXmlEntities(value: string): string {
+  return value
+    .replace(/&quot;/g, "\"")
+    .replace(/&apos;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/'/g, "&apos;");
+}

package/src/io/opc/README.md

@@ -0,0 +1,3 @@
+# IO OPC
+
+Open Packaging Conventions package reading, part enumeration, and relationship handling belong here.