@beyondwork/docx-react-component 1.0.0 → 1.0.1

package/src/component-inventory.md

@@ -1,99 +0,0 @@
-# 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

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

package/src/core/commands/README.md

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

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

@@ -1,161 +0,0 @@
-/**
- * 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

@@ -1,144 +0,0 @@
-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";
-  }
-}