@beyondwork/docx-react-component 1.0.1 → 1.0.3

package/src/compare/snapshot.ts

@@ -0,0 +1,37 @@
+import {
+  createCanonicalDocumentSignature,
+  projectCanonicalDocument,
+  type CanonicalDocument,
+} from "../model/canonical-document.ts";
+
+export interface DocumentVersionSnapshot {
+  snapshotVersion: "document-version-snapshot/1";
+  versionId: string;
+  name: string;
+  createdAt: string;
+  documentId: string;
+  documentSignature: string;
+  canonicalDocument: CanonicalDocument;
+}
+
+export interface CreateDocumentVersionSnapshotOptions {
+  versionId?: string;
+  name: string;
+  createdAt?: string;
+}
+
+export function createDocumentVersionSnapshot(
+  document: CanonicalDocument,
+  options: CreateDocumentVersionSnapshotOptions,
+): DocumentVersionSnapshot {
+  const canonicalDocument = projectCanonicalDocument(document);
+  return {
+    snapshotVersion: "document-version-snapshot/1",
+    versionId: options.versionId ?? `${canonicalDocument.docId}:${options.name}`,
+    name: options.name,
+    createdAt: options.createdAt ?? canonicalDocument.updatedAt,
+    documentId: canonicalDocument.docId,
+    documentSignature: createCanonicalDocumentSignature(canonicalDocument),
+    canonicalDocument,
+  };
+}

package/src/component-inventory.md

@@ -0,0 +1,99 @@
+# Component Inventory
+
+This file is the source-owned inventory for the major subsystems in the active docx implementation.
+
+Wave 0 established the scaffold and ownership boundaries. Wave 1 froze the contract surface for the editor-side components listed below. That promotion does not claim implementation completeness; it means the subsystem boundaries, contract artifacts, and proof expectations are now explicit enough for later docx waves to build against without reopening the architecture.
+
+This inventory does not yet track:
+
+- shared OOXML platform extraction as a separate source area
+- a future xlsx runtime inventory
+- future pdf work
+
+## Inventory Table
+
+| Component | Current target | Primary paths | Scope in this repo phase | Contract and proof surfaces |
+| --- | --- | --- | --- | --- |
+| `canonical-document-model` | `contract-frozen` | `src/model/`, `src/api/` | Versioned canonical envelope, persisted snapshot shape, migration boundary, document metadata ownership | `docs/plans/waves/specs/wave-1-component-boundaries.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, schema docs, canonical JSON examples, model tests |
+| `command-and-transaction-runtime` | `contract-frozen` | `src/core/`, `src/runtime/` | Deterministic commands, transactions, mapping, selection semantics, runtime mutation boundary | `docs/plans/waves/specs/wave-1-component-boundaries.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, command tests, mapping tests, state-transition proofs |
+| `comments-and-anchor-mapping` | `contract-frozen` | `src/review/`, `src/core/selection/` | Comment threads, anchor remapping, review selectors, edit-safe anchor mapping policy | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, `docs/plans/waves/specs/wave-1-runtime-contracts.md`, anchor remap tests, threaded comment fixtures, review model docs |
+| `tracked-changes-and-review-actions` | `contract-frozen` | `src/review/`, `src/ui/review/` | Revision records, display modes, accept/reject boundaries, review-oriented commands | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, revision fixtures, accept/reject tests, review-state mapping tests |
+| `docx-import-and-normalization` | `contract-frozen` | `src/io/opc/`, `src/io/ooxml/`, `src/io/normalize/` | OPC opening, WordprocessingML parsing, normalization into canonical state, support classification inputs | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, `.docx` import fixtures, normalization tests, supported-feature mapping docs |
+| `docx-export-and-serialization` | `contract-frozen` | `src/io/export/`, `src/io/opc/` | Regenerated OOXML parts, package writing, relationship integrity, supported-feature serialization | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, round-trip fixtures, export validation tests, serializer docs |
+| `unsupported-ooxml-preservation` | `contract-frozen` | `src/preservation/`, `src/io/` | Opaque fragment capture, untouched package-part retention, reattachment policy, locked editing regions | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, preservation fixtures, fragment retention tests, export reattachment tests |
+| `compatibility-and-word-validation` | `contract-frozen` | `src/validation/`, `src/ui/compatibility/`, `services/openxml-validator/` | Editor-side compatibility reporting, support classification, export-risk reporting, validator-service integration boundary | `docs/plans/waves/specs/wave-1-ooxml-contracts.md`, `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, feature matrix, compatibility tests, Word reopen evidence |
+| `react-editor-ui` | `contract-frozen` | `src/ui-tailwind/`, `src/ui/headless/`, `src/runtime/`, `src/api/` | Tailwind-based React shell with Radix UI primitives. Headless logic in `src/ui/headless/`. Legacy inline-CSSProperties components removed. | `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`, component tests, selection behavior checks, review-surface checks, token and theme checks |
+
+## Boundary Notes
+
+### Canonical data stays outside React
+
+- `src/model/`, `src/core/`, `src/review/`, `src/io/`, `src/preservation/`, and `src/validation/` should remain framework-light and serializable.
+- The DOM is a rendering target, not canonical state.
+
+### Runtime is the mutation choke point
+
+- UI surfaces call into `src/runtime/`.
+- Commands and transactions are owned by `src/core/`.
+- Review actions remain explicit state transitions rather than implicit UI side effects.
+
+### DOCX handling is package-first
+
+- `src/io/opc/` owns ZIP/package and relationship handling.
+- `src/io/ooxml/` owns WordprocessingML parsing.
+- `src/preservation/` owns unsupported-content retention and untouched package parts.
+
+### Broader repo work is planned, not landed
+
+- The repo now documents a target source layout under `src/platform/` and `src/formats/*`, but this file still inventories the landed docx-first tree.
+- Shared platform and xlsx architecture are currently defined in docs, not in source ownership tables here.
+
+### Review semantics are first-class
+
+- Comments and tracked changes are not annotations layered loosely on top of text rendering.
+- Anchors and revisions must stay mappable through edits and export.
+
+## Service-Backed Wave 0 Components
+
+The following components have a higher Wave 0 target because they already have repo-landed scaffolds:
+
+| Component | Wave 0 target | Primary paths | Landed scaffold evidence |
+| --- | --- | --- | --- |
+| `railway-test-harness` | `repo-landed` | `services/react-word-editor/` | Next.js service package, layout shell, harness dashboard stub, Dockerfile, Railway-oriented README |
+| `openxml-sdk-validator-service` | `repo-landed` | `services/openxml-validator/` | .NET 8 minimal API, `GET /health`, `POST /validate`, Dockerfile, SDK-backed validation README |
+
+## Out Of Scope For Wave 0
+
+- No canonical schema implementation yet
+- No command engine implementation yet
+- No comment or revision persistence yet
+- No OOXML transformer or serializer yet
+- No production `WordReviewEditor` React runtime yet
+- No live Railway persistence or private networking integration yet
+
+Those surfaces move in later waves. This inventory only establishes where they belong and what proof each promotion will require.
+
+## Contract Freeze References
+
+Wave 1 froze the owned architecture in the following durable spec set:
+
+- `docs/plans/waves/design/wave-1-a1.md`
+- `docs/plans/waves/specs/wave-1-component-boundaries.md`
+- `docs/plans/waves/specs/wave-1-runtime-contracts.md`
+- `docs/plans/waves/specs/wave-1-ooxml-contracts.md`
+- `docs/plans/waves/specs/wave-1-review-and-ui-contracts.md`
+
+## Future Source Direction
+
+Target broader layout:
+
+```text
+src/
+  platform/
+  formats/
+    docx/
+    xlsx/
+    pdf/
+```
+
+That future layout is a planning direction only. Do not treat it as a landed source move until the actual implementation is reorganized.

package/src/core/README.md

@@ -0,0 +1,10 @@
+# Core
+
+Commands, transactions, selection, mapping, schema, and deterministic state transitions belong here.
+
+Key subdirectories:
+
+- `schema/`
+- `state/`
+- `commands/`
+- `selection/`

package/src/core/commands/README.md

@@ -0,0 +1,3 @@
+# Core Commands
+
+Command handlers, transaction builders, and editor mutation policies belong here.

package/src/core/commands/formatting-commands.ts

@@ -0,0 +1,161 @@
+/**
+ * ProseMirror formatting commands for the editor surface schema.
+ *
+ * Each command follows the standard ProseMirror command signature:
+ *   (state, dispatch?) => boolean
+ *
+ * Toggle commands use the ProseMirror toggleMark helper.
+ * Set commands for value-bearing marks (font, size, color) apply the mark
+ * over the current selection, or remove it when the value is null.
+ * The setAlignment command sets the `alignment` attr on paragraph nodes
+ * that intersect the current selection.
+ *
+ * These commands operate on the `editorSchema` live surface. In the
+ * current architecture the runtime is the canonical document authority;
+ * these commands are designed to be used with the PM view's `dispatch`
+ * so that mark changes are reflected on the live surface immediately.
+ */
+
+import { toggleMark } from "prosemirror-commands";
+import type { Command } from "prosemirror-state";
+import type { MarkType, Schema } from "prosemirror-model";
+
+// ---------------------------------------------------------------------------
+// Toggle commands (boolean marks – no attrs)
+// ---------------------------------------------------------------------------
+
+export function makeToggleBold(schema: Schema): Command {
+  return toggleMark(schema.marks.bold);
+}
+
+export function makeToggleItalic(schema: Schema): Command {
+  return toggleMark(schema.marks.italic);
+}
+
+export function makeToggleUnderline(schema: Schema): Command {
+  return toggleMark(schema.marks.underline);
+}
+
+export function makeToggleStrikethrough(schema: Schema): Command {
+  return toggleMark(schema.marks.strikethrough);
+}
+
+export function makeToggleSuperscript(schema: Schema): Command {
+  return toggleMark(schema.marks.superscript);
+}
+
+export function makeToggleSubscript(schema: Schema): Command {
+  return toggleMark(schema.marks.subscript);
+}
+
+export function makeToggleSmallCaps(schema: Schema): Command {
+  return toggleMark(schema.marks.small_caps);
+}
+
+export function makeToggleAllCaps(schema: Schema): Command {
+  return toggleMark(schema.marks.all_caps);
+}
+
+// ---------------------------------------------------------------------------
+// Set commands (value-bearing marks)
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply or remove a value-bearing mark over the current selection.
+ * When `value` is null the mark is removed; otherwise it is added with the
+ * given attribute key set to `value`.
+ */
+function makeSetValueMark(
+  markType: MarkType,
+  attrKey: string,
+  value: string | number | null,
+): Command {
+  return (state, dispatch) => {
+    const { from, to, empty } = state.selection;
+    if (empty) return false;
+    if (!dispatch) return true;
+
+    const tr = state.tr;
+    if (value === null) {
+      tr.removeMark(from, to, markType);
+    } else {
+      const mark = markType.create({ [attrKey]: value });
+      tr.addMark(from, to, mark);
+    }
+    dispatch(tr);
+    return true;
+  };
+}
+
+export function makeSetFontFamily(schema: Schema, family: string | null): Command {
+  return makeSetValueMark(schema.marks.font_family, "family", family);
+}
+
+export function makeSetFontSize(schema: Schema, size: number | null): Command {
+  return makeSetValueMark(schema.marks.font_size, "size", size);
+}
+
+export function makeSetTextColor(schema: Schema, color: string | null): Command {
+  return makeSetValueMark(schema.marks.text_color, "color", color);
+}
+
+export function makeSetHighlight(schema: Schema, color: string | null): Command {
+  return makeSetValueMark(schema.marks.highlight, "color", color);
+}
+
+// ---------------------------------------------------------------------------
+// Paragraph alignment
+// ---------------------------------------------------------------------------
+
+export type Alignment = "left" | "center" | "right" | "justify";
+
+/**
+ * Set the `alignment` attribute on every paragraph node that intersects
+ * the current selection. Pass `null` to clear the alignment.
+ */
+export function makeSetAlignment(schema: Schema, alignment: Alignment | null): Command {
+  return (state, dispatch) => {
+    const { from, to } = state.selection;
+    if (!dispatch) return true;
+
+    const tr = state.tr;
+    let applied = false;
+    state.doc.nodesBetween(from, to, (node, pos) => {
+      if (node.type === schema.nodes.paragraph) {
+        tr.setNodeMarkup(pos, undefined, { ...node.attrs, alignment });
+        applied = true;
+      }
+    });
+
+    if (!applied) return false;
+    dispatch(tr);
+    return true;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mark query helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if every character in the selection has the given mark active.
+ * When the selection is collapsed, checks the stored marks at the cursor.
+ */
+export function isMarkActive(schema: Schema, markName: keyof typeof schema.marks, state: import("prosemirror-state").EditorState): boolean {
+  const markType = schema.marks[markName];
+  if (!markType) return false;
+
+  const { from, to, empty } = state.selection;
+  if (empty) {
+    return Boolean(markType.isInSet(state.storedMarks ?? state.selection.$from.marks()));
+  }
+
+  let active = true;
+  state.doc.nodesBetween(from, to, (node) => {
+    if (node.isText && !markType.isInSet(node.marks)) {
+      active = false;
+      return false;
+    }
+  });
+  return active;
+}

package/src/core/commands/image-commands.ts

@@ -0,0 +1,144 @@
+import {
+  cloneParagraphProperties,
+  cloneStoryUnit,
+  parseTextStory,
+  serializeTextStory,
+  type TextStory,
+} from "../schema/text-schema.ts";
+import { createSelectionSnapshot, type CanonicalDocumentEnvelope, type SelectionSnapshot } from "../state/editor-state.ts";
+import { TextTransactionError } from "../state/text-transaction.ts";
+import type { TransactionMapping } from "../selection/mapping.ts";
+import type { MediaItem } from "../../model/canonical-document.ts";
+
+export interface ImageCommandContext {
+  timestamp: string;
+  altText?: string;
+}
+
+export interface InsertImageResult {
+  document: CanonicalDocumentEnvelope;
+  selection: SelectionSnapshot;
+  mapping: TransactionMapping;
+  mediaId: string;
+}
+
+/**
+ * Insert an image into the document at the current selection.
+ *
+ * Registers a MediaItem in the catalog with the supplied mimeType and
+ * optional dimensions, then inserts an image unit into the text story.
+ * Binary data is NOT stored in the canonical document — callers are
+ * responsible for persisting it to an external media store.
+ */
+export function insertImage(
+  document: CanonicalDocumentEnvelope,
+  selection: SelectionSnapshot,
+  data: Uint8Array | string,
+  mimeType: string,
+  width?: number,
+  height?: number,
+  context: ImageCommandContext = { timestamp: new Date().toISOString() },
+): InsertImageResult {
+  const story = parseTextStory(document.content);
+  const from = Math.min(selection.anchor, selection.head);
+  const to = Math.max(selection.anchor, selection.head);
+
+  if (from > story.size || to > story.size) {
+    throw new TextTransactionError(
+      "invalid_selection",
+      `Selection ${from}-${to} exceeds story size ${story.size}.`,
+    );
+  }
+
+  // Reject insertions whose replacement range crosses protected content.
+  const rangeUnits = story.units.slice(from, to);
+  const protectedUnit = rangeUnits.find(
+    (unit) =>
+      unit.kind === "opaque_inline" ||
+      unit.kind === "opaque_block" ||
+      unit.kind === "image",
+  );
+  if (protectedUnit) {
+    throw new TextTransactionError(
+      "unsupported_content",
+      `Image insertion range crosses protected ${protectedUnit.kind} content.`,
+    );
+  }
+
+  const ext = mimeTypeToExtension(mimeType);
+  const timestamp = context.timestamp.replace(/[^0-9]/g, "").slice(0, 14);
+  const mediaId = `media:img-${timestamp}`;
+  const packagePartName = `/word/media/${mediaId.replace("media:", "")}.${ext}`;
+
+  const mediaItem: MediaItem = {
+    mediaId,
+    contentType: mimeType,
+    filename: `${mediaId.replace("media:", "")}.${ext}`,
+    packagePartName,
+    ...(context.altText ? { altText: context.altText } : {}),
+  };
+
+  const existingItems =
+    document.media && "items" in document.media
+      ? (document.media as { items: Record<string, MediaItem> }).items
+      : {};
+
+  const updatedMedia = {
+    items: {
+      ...existingItems,
+      [mediaId]: mediaItem,
+    },
+  };
+
+  const nextUnits = [
+    ...story.units.slice(0, from).map(cloneStoryUnit),
+    {
+      kind: "image" as const,
+      mediaId,
+      ...(context.altText ? { altText: context.altText } : {}),
+    },
+    ...story.units.slice(to).map(cloneStoryUnit),
+  ];
+
+  const nextStory: TextStory = {
+    firstParagraph: cloneParagraphProperties(story.firstParagraph),
+    units: nextUnits,
+    size: nextUnits.length,
+  };
+
+  const caret = from + 1;
+
+  return {
+    document: {
+      ...document,
+      updatedAt: context.timestamp,
+      media: updatedMedia,
+      content: serializeTextStory(nextStory),
+    },
+    selection: createSelectionSnapshot(caret, caret),
+    mapping: {
+      steps: [{ from, to, insertSize: 1 }],
+    },
+    mediaId,
+  };
+}
+
+function mimeTypeToExtension(mimeType: string): string {
+  switch (mimeType.toLowerCase()) {
+    case "image/png":
+      return "png";
+    case "image/jpeg":
+    case "image/jpg":
+      return "jpg";
+    case "image/gif":
+      return "gif";
+    case "image/webp":
+      return "webp";
+    case "image/svg+xml":
+      return "svg";
+    case "image/bmp":
+      return "bmp";
+    default:
+      return "bin";
+  }
+}