@beyondwork/docx-react-component 1.0.38 → 1.0.40

package/src/io/ooxml/parse-styles.ts

@@ -10,6 +10,7 @@
 import type {
   CellShading,
   CharacterStyleDefinition,
+  DocumentDefaults,
   LatentStyleDefinition,
   ParagraphStyleDefinition,
   StylesCatalog,
@@ -37,6 +38,8 @@ import {
   readTableWidth,
 } from "./parse-tables.ts";
 import { toCanonicalNumberingInstanceId } from "./parse-numbering.ts";
+import { readRunProperties } from "./parse-run-formatting.ts";
+import { readParagraphProperties } from "./parse-paragraph-formatting.ts";
 
 // ---------------------------------------------------------------------------
 // Inline XML node types (same pattern as parse-numbering.ts)
@@ -116,11 +119,28 @@ export function parseStylesXml(xml: string): ParseStylesResult {
   const characters: Record<string, CharacterStyleDefinition> = {};
   const tables: Record<string, TableStyleDefinition> = {};
   const latentStyles: Record<string, LatentStyleDefinition> = {};
+  let docDefaults: DocumentDefaults | undefined;
 
   for (const child of stylesElement.children) {
     if (child.type !== "element") continue;
     const local = localName(child.name);
 
+    if (local === "docDefaults") {
+      const pPrDefault = findChildElementOptional(child, "pPrDefault");
+      const rPrDefault = findChildElementOptional(child, "rPrDefault");
+      const pPrNode = pPrDefault ? findChildElementOptional(pPrDefault, "pPr") : undefined;
+      const rPrNode = rPrDefault ? findChildElementOptional(rPrDefault, "rPr") : undefined;
+      const paragraph = readParagraphProperties(pPrNode);
+      const run = readRunProperties(rPrNode);
+      if (paragraph || run) {
+        docDefaults = {
+          ...(paragraph ? { paragraph } : {}),
+          ...(run ? { run } : {}),
+        };
+      }
+      continue;
+    }
+
     if (local === "style") {
       const styleType = child.attributes["w:type"] ?? child.attributes.type;
       const styleId = child.attributes["w:styleId"] ?? child.attributes.styleId;
@@ -135,6 +155,10 @@ export function parseStylesXml(xml: string): ParseStylesResult {
           const nextStyle = readLinkedStyleId(child, "next");
           const outlineLevel = readParagraphStyleOutlineLevel(child);
           const numbering = readParagraphStyleNumbering(child);
+          const pPrNode = findChildElementOptional(child, "pPr");
+          const rPrNode = findChildElementOptional(child, "rPr");
+          const paragraphProperties = readParagraphProperties(pPrNode);
+          const runProperties = readRunProperties(rPrNode);
           paragraphs[styleId] = {
             styleId,
             displayName,
@@ -144,16 +168,21 @@ export function parseStylesXml(xml: string): ParseStylesResult {
             ...(nextStyle ? { nextStyle } : {}),
             ...(outlineLevel !== undefined ? { outlineLevel } : {}),
             ...(numbering ? { numbering } : {}),
+            ...(paragraphProperties ? { paragraphProperties } : {}),
+            ...(runProperties ? { runProperties } : {}),
           };
           break;
         }
         case "character": {
+          const rPrNode = findChildElementOptional(child, "rPr");
+          const runProperties = readRunProperties(rPrNode);
           characters[styleId] = {
             styleId,
             displayName,
             kind: "character",
             isDefault,
             ...(basedOn ? { basedOn } : {}),
+            ...(runProperties ? { runProperties } : {}),
           };
           break;
         }
@@ -194,6 +223,8 @@ export function parseStylesXml(xml: string): ParseStylesResult {
       characters,
       tables,
       ...(hasLatent ? { latentStyles } : {}),
+      fromPackage: true,
+      ...(docDefaults ? { docDefaults } : {}),
     },
     fromPackage: true,
     diagnostics,

package/src/io/ooxml/xml-attr-helpers.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared XML helpers for OOXML parsers.
+ *
+ * These functions factor out the common pattern of reading namespaced-prefixed
+ * attributes (e.g., `w:val`) with fallback to the unprefixed form, handling
+ * the OOXML `ST_OnOff` toggle semantics (missing child = undefined, present
+ * with no val = true, `val="0"|"false"|"off"` = false), and reading integers.
+ *
+ * Used by parse-run-formatting.ts, parse-paragraph-formatting.ts, and (later)
+ * parse-styles.ts, parse-numbering.ts.
+ */
+
+import type { XmlElementNode } from "./xml-element.ts";
+
+export function localName(name: string): string {
+  const sep = name.indexOf(":");
+  return sep >= 0 ? name.slice(sep + 1) : name;
+}
+
+export function findChildOptional(
+  node: XmlElementNode,
+  local: string,
+): XmlElementNode | undefined {
+  return node.children.find(
+    (c): c is XmlElementNode => c.type === "element" && localName(c.name) === local,
+  );
+}
+
+/** ST_OnOff: missing child → undefined; present bare or w:val="1|true|on" → true; w:val="0|false|off" → false. */
+export function readOnOff(node: XmlElementNode | undefined): boolean | undefined {
+  if (!node) return undefined;
+  const raw = node.attributes["w:val"] ?? node.attributes.val;
+  if (raw === undefined) return true;
+  const n = raw.toLowerCase();
+  if (n === "0" || n === "false" || n === "off") return false;
+  if (n === "1" || n === "true" || n === "on") return true;
+  return true;
+}
+
+/** Read the child's `w:val` attribute as an int. Returns undefined if missing or not a finite integer. */
+export function readIntVal(node: XmlElementNode | undefined): number | undefined {
+  if (!node) return undefined;
+  const raw = node.attributes["w:val"] ?? node.attributes.val;
+  if (raw === undefined) return undefined;
+  const v = Number.parseInt(raw, 10);
+  return Number.isFinite(v) ? v : undefined;
+}
+
+/** Read an arbitrary attribute from a node as an int, with namespace fallback. */
+export function readIntAttr(node: XmlElementNode, attr: string): number | undefined {
+  const raw = node.attributes[attr] ?? node.attributes[attr.replace(/^w:/, "")];
+  if (raw === undefined) return undefined;
+  const v = Number.parseInt(raw, 10);
+  return Number.isFinite(v) ? v : undefined;
+}
+
+/** Read an arbitrary attribute from a node as a string, with namespace fallback. */
+export function readStringAttr(node: XmlElementNode, attr: string): string | undefined {
+  return node.attributes[attr] ?? node.attributes[attr.replace(/^w:/, "")];
+}

package/src/io/ooxml/xml-element.ts

@@ -0,0 +1,19 @@
+export interface XmlElementNode {
+  type: "element";
+  name: string;
+  attributes: Record<string, string>;
+  children: Array<XmlElementNode | XmlTextNode>;
+  /** Optional source offset (start) — parsers that track offsets may populate. */
+  start?: number;
+  /** Optional source offset (end) — parsers that track offsets may populate. */
+  end?: number;
+}
+
+export interface XmlTextNode {
+  type: "text";
+  text: string;
+  start?: number;
+  end?: number;
+}
+
+export type XmlNode = XmlElementNode | XmlTextNode;

package/src/model/canonical-document.ts

@@ -83,6 +83,7 @@ export interface StylesCatalog {
   tables: Record<string, TableStyleDefinition>;
   latentStyles?: Record<string, LatentStyleDefinition>;
   fromPackage?: boolean;
+  docDefaults?: DocumentDefaults;
 }
 
 export interface ParagraphStyleDefinition {
@@ -94,6 +95,8 @@ export interface ParagraphStyleDefinition {
   displayName: string;
   kind: "paragraph";
   isDefault: boolean;
+  paragraphProperties?: CanonicalParagraphFormatting;
+  runProperties?: CanonicalRunFormatting;
 }
 
 export interface ParagraphStyleNumberingReference {
@@ -107,6 +110,7 @@ export interface CharacterStyleDefinition {
   displayName: string;
   kind: "character";
   isDefault: boolean;
+  runProperties?: CanonicalRunFormatting;
 }
 
 export interface TableStyleDefinition {
@@ -136,6 +140,12 @@ export interface NumberingCatalog {
 export interface AbstractNumberingDefinition {
   abstractNumberingId: string;
   levels: NumberingLevelDefinition[];
+  nsid?: string;
+  multiLevelType?: "singleLevel" | "multilevel" | "hybridMultilevel";
+  /** ECMA-376 17.9.26 `<w:tmpl>` — template code identifying the abstractNum's origin template (ST_LongHexNumber). Preserved for round-trip. */
+  tplc?: string;
+  styleLink?: string;
+  numStyleLink?: string;
 }
 
 export interface NumberingLevelParagraphGeometry {
@@ -154,6 +164,8 @@ export interface NumberingLevelDefinition {
   isLegalNumbering?: boolean;
   suffix?: "tab" | "space" | "nothing";
   paragraphGeometry?: NumberingLevelParagraphGeometry;
+  runProperties?: CanonicalRunFormatting;
+  restartAfterLevel?: number;
 }
 
 export interface NumberingLevelOverrideDefinition {
@@ -165,6 +177,8 @@ export interface NumberingLevelOverrideDefinition {
   isLegalNumbering?: boolean;
   suffix?: "tab" | "space" | "nothing";
   paragraphGeometry?: NumberingLevelParagraphGeometry;
+  runProperties?: CanonicalRunFormatting;
+  restartAfterLevel?: number;
 }
 
 export interface NumberingInstance {
@@ -350,6 +364,68 @@ export interface ParagraphShading {
   val?: string;
 }
 
+/** Body of an OOXML `<w:rPr>` (run properties). All fields optional; absence = "not specified at this level". */
+export interface CanonicalRunFormatting {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: "single" | "double" | "thick" | "dotted" | "dash" | "wave" | "none";
+  strikethrough?: boolean;
+  doubleStrikethrough?: boolean;
+  vanish?: boolean;
+  allCaps?: boolean;
+  smallCaps?: boolean;
+  verticalAlign?: "baseline" | "superscript" | "subscript";
+  /**
+   * Convenience alias for the primary font family — the first non-empty of
+   * `fontFamilyAscii` → `fontFamilyHAnsi` → `fontFamilyEastAsia` → `fontFamilyCs`.
+   * Script-aware consumers should read the specific `fontFamily{Ascii,HAnsi,EastAsia,Cs}`
+   * fields directly.
+   */
+  fontFamily?: string;
+  fontFamilyAscii?: string;
+  fontFamilyHAnsi?: string;
+  fontFamilyEastAsia?: string;
+  fontFamilyCs?: string;
+  fontSizeHalfPoints?: number;
+  fontSizeCsHalfPoints?: number;
+  /**
+   * Color value from `<w:color w:val>`. Either an OOXML hex (e.g., `"2E74B5"`)
+   * or the sentinel `"auto"` (which serializers must round-trip verbatim).
+   */
+  colorHex?: string;
+  colorThemeSlot?: string;
+  highlight?: string;
+  characterSpacingTwips?: number;
+  characterStyleId?: string;
+  languageCode?: string;
+}
+
+/** Body of an OOXML `<w:pPr>` (paragraph properties). All fields optional; absence = "not specified at this level". */
+export interface CanonicalParagraphFormatting {
+  spacing?: ParagraphSpacing;
+  indentation?: ParagraphIndentation;
+  alignment?: "left" | "center" | "right" | "both" | "distribute" | "start" | "end";
+  borders?: ParagraphBorders;
+  shading?: ParagraphShading;
+  tabStops?: TabStop[];
+  contextualSpacing?: boolean;
+  keepNext?: boolean;
+  keepLines?: boolean;
+  widowControl?: boolean;
+  pageBreakBefore?: boolean;
+  outlineLevel?: number;
+  bidi?: boolean;
+  suppressLineNumbers?: boolean;
+  suppressAutoHyphens?: boolean;
+  paragraphMarkRunProperties?: CanonicalRunFormatting;
+}
+
+/** Body of an OOXML `<w:docDefaults>` — baseline formatting applied before style chain. */
+export interface DocumentDefaults {
+  paragraph?: CanonicalParagraphFormatting;
+  run?: CanonicalRunFormatting;
+}
+
 export interface ParagraphNode {
   type: "paragraph";
   styleId?: string;
@@ -594,15 +670,19 @@ export interface AltChunkNode {
  * These families have stable registry IDs, dependency metadata, and
  * runtime-owned refresh behavior.
  */
-export type SupportedFieldFamily = "REF" | "PAGEREF" | "NOTEREF" | "TOC";
+export type SupportedFieldFamily =
+  | "REF"
+  | "PAGEREF"
+  | "NOTEREF"
+  | "TOC"
+  | "PAGE"
+  | "NUMPAGES";
 
 /**
  * Unsupported field families that remain preserve-only.
  * They survive round-trip but do not participate in runtime refresh.
  */
 export type PreserveOnlyFieldFamily =
-  | "PAGE"
-  | "NUMPAGES"
   | "DATE"
   | "TIME"
   | "AUTHOR"

package/src/runtime/collab/event-types.ts

@@ -0,0 +1,165 @@
+import type { EditorCommand } from "../../core/commands/index.ts";
+import type { SelectionSnapshot } from "../../core/state/editor-state.ts";
+import type { EditorStoryTarget } from "../../api/public-types.ts";
+
+/**
+ * A single delta event recorded in the shared collaboration event log.
+ *
+ * The collaboration model for the runtime layer is:
+ *   `currentState = replay(baseDocxBytes, eventLog)`
+ *
+ * Every client loads the same base `.docx`, then the event log — stored as
+ * a `Y.Array<CommandEvent>` on the shared `Y.Doc` — is replayed through
+ * the runtime's `executeEditorCommand` pipeline to arrive at the current
+ * canonical document state. Because all mutations flow through the
+ * runtime, export/download and every other downstream read see the full,
+ * up-to-date state automatically.
+ *
+ * Events are meant to be small deltas (text insertions, comment adds,
+ * change accepts, etc.). They are NOT full-document snapshots.
+ *
+ * `document.replace` is a special case: some formatting/table/list
+ * operations currently produce `document.replace` commands that carry
+ * a full `CanonicalDocumentEnvelope`. These events are bandwidth-heavy
+ * but functionally correct. A follow-up will promote them to first-class
+ * delta commands.
+ */
+export interface CommandEvent {
+  /** UUID — dedup key for defensive idempotency. */
+  eventId: string;
+  /** `Y.Doc.clientID` of the originating client. */
+  originClientId: number;
+  /** User identity for attribution (e.g. `currentUser.userId`). */
+  authorId: string;
+  /** ISO-8601 UTC timestamp at origin. */
+  timestamp: string;
+  /** The exact `EditorCommand` that produced this delta. */
+  command: EditorCommand;
+  /** Context required for deterministic replay on remote clients. */
+  context: {
+    documentMode?: "editing" | "suggesting" | "viewing" | "commenting";
+    defaultAuthorId?: string;
+    /**
+     * Selection at the moment the command was dispatched on the origin
+     * client. Replay uses this to restore the caret before applying the
+     * command so text insertions, backspaces, etc. land at the position
+     * the author intended rather than the replaying client's current
+     * caret (which is arbitrary).
+     */
+    preSelection?: SelectionSnapshot;
+    /**
+     * Active story at the moment the command was dispatched. Replay
+     * must target the same story (main, header, footer, note, ...) so
+     * mutations apply to the intended region.
+     */
+    activeStory?: EditorStoryTarget;
+  };
+}
+
+/**
+ * Command types that are broadcast to all collaborators.
+ *
+ * Any command whose type is in this set represents a mutation to the
+ * shared document state (content, comments, tracked changes, review
+ * decisions). Local-only commands are intentionally excluded — see
+ * `LOCAL_ONLY_COMMAND_TYPES`.
+ */
+export const BROADCAST_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new Set<
+  EditorCommand["type"]
+>([
+  "text.insert",
+  "text.delete-backward",
+  "text.delete-forward",
+  "text.insert-tab",
+  "text.insert-hard-break",
+  "paragraph.split",
+  "document.replace",
+  "comment.add",
+  "comment.resolve",
+  "comment.reopen",
+  "comment.add-reply",
+  "comment.edit-body",
+  "change.accept",
+  "change.reject",
+  "change.accept-all",
+  "change.reject-all",
+]);
+
+/**
+ * Command types that are NEVER broadcast. These are intentionally
+ * per-client: cursor/selection state (handled by Awareness instead),
+ * UI focus, local warnings, and the local history stack.
+ */
+export const LOCAL_ONLY_COMMAND_TYPES: ReadonlySet<EditorCommand["type"]> = new Set<
+  EditorCommand["type"]
+>([
+  "selection.set",
+  "comment.open",
+  "warning.add",
+  "warning.clear",
+  "history.undo",
+  "history.redo",
+  "runtime.focus",
+  "runtime.set-read-only",
+]);
+
+/**
+ * Returns `true` when the command is local-only and must NOT be broadcast
+ * on the shared collaboration event log.
+ */
+export function isLocalOnlyCommand(command: EditorCommand): boolean {
+  return LOCAL_ONLY_COMMAND_TYPES.has(command.type);
+}
+
+/**
+ * Returns `true` when the command must be broadcast on the shared event
+ * log. Defensive helper — equivalent to `!isLocalOnlyCommand(command)`
+ * for every known command type, but raises visibility if a new command
+ * type is added without being classified (both predicates would be
+ * `false`, which is easier to spot in tests).
+ */
+export function isBroadcastCommand(command: EditorCommand): boolean {
+  return BROADCAST_COMMAND_TYPES.has(command.type);
+}
+
+export interface CreateCommandEventInput {
+  command: EditorCommand;
+  originClientId: number;
+  authorId: string;
+  timestamp: string;
+  context?: CommandEvent["context"];
+}
+
+/**
+ * Build a `CommandEvent` to append to the shared event log. Callers are
+ * responsible for ensuring `command` is a broadcast-eligible command.
+ */
+export function createCommandEvent(input: CreateCommandEventInput): CommandEvent {
+  return {
+    eventId: generateEventId(),
+    originClientId: input.originClientId,
+    authorId: input.authorId,
+    timestamp: input.timestamp,
+    command: input.command,
+    context: {
+      documentMode: input.context?.documentMode,
+      defaultAuthorId: input.context?.defaultAuthorId,
+      preSelection: input.context?.preSelection,
+      activeStory: input.context?.activeStory,
+    },
+  };
+}
+
+let eventIdCounter = 0;
+
+function generateEventId(): string {
+  // A short, collision-resistant-enough id for local dedup. Clients
+  // distinguish their own events by `originClientId` first; this id is
+  // a defensive fallback against replays of identical client-scoped
+  // sequences. No crypto requirements here.
+  eventIdCounter = (eventIdCounter + 1) >>> 0;
+  const random = Math.floor(Math.random() * 0xffffffff).toString(16).padStart(8, "0");
+  const counter = eventIdCounter.toString(16).padStart(8, "0");
+  const time = Date.now().toString(16);
+  return `evt-${time}-${counter}-${random}`;
+}

package/src/runtime/collab/index.ts

@@ -0,0 +1,22 @@
+export {
+  createRuntimeCollabSync,
+  createRuntimeCommandAppliedBridge,
+  type RuntimeCollabSyncHandle,
+  type RuntimeCollabSyncOptions,
+  type RuntimeCommandAppliedBridge,
+  type RuntimeCommandAppliedListener,
+} from "./runtime-collab-sync.ts";
+export {
+  createCommandEvent,
+  isBroadcastCommand,
+  isLocalOnlyCommand,
+  type CommandEvent,
+  type CreateCommandEventInput,
+} from "./event-types.ts";
+export {
+  clearLocalCursorState,
+  getCursorColorForUser,
+  getRemoteCursorStates,
+  setLocalCursorState,
+  type RemoteCursorState,
+} from "./remote-cursor-awareness.ts";

package/src/runtime/collab/remote-cursor-awareness.ts

@@ -0,0 +1,93 @@
+import type { Awareness } from "y-protocols/awareness";
+import type { EditorStoryTarget } from "../../api/public-types";
+
+export interface RemoteCursorState {
+  userId: string;
+  displayName: string;
+  color: string;
+  anchor: number;
+  head: number;
+  storyTarget: EditorStoryTarget;
+}
+
+const CURSOR_STATE_KEY = "cursor";
+
+const CURSOR_COLORS = [
+  "#e11d48",
+  "#ea580c",
+  "#ca8a04",
+  "#16a34a",
+  "#0891b2",
+  "#2563eb",
+  "#7c3aed",
+  "#c026d3",
+];
+
+function hashUserId(userId: string): number {
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) {
+    const char = userId.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash);
+}
+
+export function getCursorColorForUser(userId: string): string {
+  const index = hashUserId(userId) % CURSOR_COLORS.length;
+  return CURSOR_COLORS[index];
+}
+
+export function setLocalCursorState(
+  awareness: Awareness,
+  state: RemoteCursorState,
+): void {
+  awareness.setLocalStateField(CURSOR_STATE_KEY, state);
+}
+
+export function clearLocalCursorState(awareness: Awareness): void {
+  const localState = awareness.getLocalState();
+  if (localState && CURSOR_STATE_KEY in localState) {
+    awareness.setLocalStateField(CURSOR_STATE_KEY, null);
+  }
+}
+
+const SAFE_HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+
+export function isSafeCursorColor(value: unknown): value is string {
+  return typeof value === "string" && SAFE_HEX_COLOR_PATTERN.test(value);
+}
+
+export function getRemoteCursorStates(
+  awareness: Awareness,
+  localClientId: number,
+): RemoteCursorState[] {
+  const states = awareness.getStates();
+  const result: RemoteCursorState[] = [];
+
+  for (const [clientId, clientState] of states) {
+    if (clientId === localClientId) continue;
+
+    const cursorState = clientState[CURSOR_STATE_KEY];
+    if (!cursorState) continue;
+
+    if (
+      typeof cursorState.userId === "string" &&
+      typeof cursorState.displayName === "string" &&
+      typeof cursorState.anchor === "number" &&
+      typeof cursorState.head === "number" &&
+      cursorState.storyTarget &&
+      typeof cursorState.storyTarget.kind === "string"
+    ) {
+      const safeColor = isSafeCursorColor(cursorState.color)
+        ? cursorState.color
+        : getCursorColorForUser(cursorState.userId);
+      result.push({
+        ...(cursorState as RemoteCursorState),
+        color: safeColor,
+      });
+    }
+  }
+
+  return result;
+}