@beyondwork/docx-react-component 1.0.37 → 1.0.38

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.37",
+  "version": "1.0.38",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -20,8 +20,42 @@ export type {
   PublicResolvedParagraphFormatting,
   PublicResolvedRunFormatting,
   PublicSectionNode,
+  // R0.5: named page-format + margin-preset catalogs
+  PageFormatDefinition,
+  ActivePageFormat,
+  MarginPresetDefinition,
+  ActiveMarginPreset,
+  RenderZoomSummary,
 } from "../runtime/layout/public-facet.ts";
 
+// R1: render-kernel shapes (frame, decoration index, anchor index) — these
+// are exposed additively so consumers can read the future `getRenderFrame`
+// output without depending on the internal render kernel module.
+export type {
+  RenderFrame,
+  RenderPage,
+  RenderPageRegions,
+  RenderStoryRegion,
+  RenderBlock,
+  RenderLine,
+  RenderLineAnchor,
+  RenderBlockDecoration,
+  RenderFrameRect,
+  RenderZoom,
+  RenderAnchorIndex,
+  RenderAnchorQuery,
+  RenderFrameQueryOptions,
+  RenderHitResult,
+  RenderKernelEvent,
+  RenderPoint,
+  DecorationIndex,
+  PageChromeReservations,
+} from "../runtime/render/index.ts";
+
+// R0: scope-rail posture vocabulary and chrome pin state — exposed so
+// host apps can drive the editor role and render custom posture menus.
+export type { ScopeRailPosture } from "../runtime/workflow-rail-segments.ts";
+
 export type FieldFamily = import("../model/canonical-document.ts").FieldFamily;
 export type FieldRefreshStatus = import("../model/canonical-document.ts").FieldRefreshStatus;
 export type SupportedFieldFamily = import("../model/canonical-document.ts").SupportedFieldFamily;
@@ -1036,9 +1070,231 @@ export interface TableStructureContextSnapshot {
     mergeCells: TableOperationCapabilitySnapshot;
     splitCell: TableOperationCapabilitySnapshot;
     deleteTable: TableOperationCapabilitySnapshot;
+    // P2g — table-level authoring ops
+    setTableWidth: TableOperationCapabilitySnapshot;
+    setTableAlignment: TableOperationCapabilitySnapshot;
+    setTableIndent: TableOperationCapabilitySnapshot;
+    setTableLayoutMode: TableOperationCapabilitySnapshot;
+    setTableCellMargins: TableOperationCapabilitySnapshot;
+    setTableBorders: TableOperationCapabilitySnapshot;
+    setTableCaption: TableOperationCapabilitySnapshot;
+    setTableDescription: TableOperationCapabilitySnapshot;
+    // P2h — column / row sizing + row props
+    setColumnWidth: TableOperationCapabilitySnapshot;
+    distributeColumnsEvenly: TableOperationCapabilitySnapshot;
+    setRowHeight: TableOperationCapabilitySnapshot;
+    setRowCantSplit: TableOperationCapabilitySnapshot;
+    setRowIsHeader: TableOperationCapabilitySnapshot;
+    setRowAlignment: TableOperationCapabilitySnapshot;
+    insertRows: TableOperationCapabilitySnapshot;
+    insertColumns: TableOperationCapabilitySnapshot;
+    // P2i — cell-level ops (over a locator)
+    setCellBorders: TableOperationCapabilitySnapshot;
+    setCellShading: TableOperationCapabilitySnapshot;
+    clearCellShading: TableOperationCapabilitySnapshot;
+    setCellMargins: TableOperationCapabilitySnapshot;
+    setCellVerticalAlign: TableOperationCapabilitySnapshot;
+    setCellTextDirection: TableOperationCapabilitySnapshot;
+    setCellNoWrap: TableOperationCapabilitySnapshot;
+    setCellFitText: TableOperationCapabilitySnapshot;
   };
 }
 
+// ─── Table typed-op surface (P2.5) ───────────────────────────────────────────
+
+/**
+ * Width/height unit used by OOXML table properties.
+ */
+export interface PublicTableWidth {
+  value: number;
+  type: "dxa" | "auto" | "pct" | "nil";
+}
+
+/**
+ * Reusable border-spec shape for table-level and cell-level borders.
+ * Matches OOXML w:*Borders child attributes.
+ */
+export interface PublicBorderSpec {
+  value?: string;
+  size?: number;
+  space?: number;
+  color?: string;
+}
+
+export interface PublicTableBorders {
+  top?: PublicBorderSpec;
+  left?: PublicBorderSpec;
+  bottom?: PublicBorderSpec;
+  right?: PublicBorderSpec;
+  insideH?: PublicBorderSpec;
+  insideV?: PublicBorderSpec;
+}
+
+export interface PublicTableCellBorders {
+  top?: PublicBorderSpec;
+  left?: PublicBorderSpec;
+  bottom?: PublicBorderSpec;
+  right?: PublicBorderSpec;
+  insideH?: PublicBorderSpec;
+  insideV?: PublicBorderSpec;
+}
+
+export interface PublicTableCellMargins {
+  top?: number;
+  left?: number;
+  bottom?: number;
+  right?: number;
+}
+
+export interface PublicCellShading {
+  fill?: string;
+  color?: string;
+  val?: string;
+}
+
+/**
+ * Addresses a cell (or set of cells) for locator-driven cell-level ops.
+ *
+ *  - `anchor`: the currently anchored cell from the active selection
+ *  - `index`: explicit (rowIndex, columnIndex)
+ *  - `rect`:  rectangular range in logical grid coordinates
+ *  - `row` / `column`: all cells in a single row or column
+ *  - `selection`: whatever the active selection covers
+ */
+export type PublicCellLocator =
+  | { kind: "anchor" }
+  | { kind: "index"; rowIndex: number; columnIndex: number }
+  | {
+      kind: "rect";
+      rect: { top: number; left: number; bottom: number; right: number };
+    }
+  | { kind: "row"; rowIndex: number }
+  | { kind: "column"; columnIndex: number }
+  | { kind: "selection" };
+
+/**
+ * Discriminated union of every table operation the public API exposes.
+ * Mirrors the internal `TableStructureOperation` variants on a stable
+ * kebab-case `kind` discriminator.
+ *
+ * Stability: additive. New ops land as new `kind` values; existing
+ * variants keep the same shape across minor versions.
+ */
+export type TableOp =
+  | { kind: "insert"; rows: number; columns: number }
+  | { kind: "delete-table" }
+  | { kind: "add-row-before" }
+  | { kind: "add-row-after" }
+  | { kind: "add-column-before" }
+  | { kind: "add-column-after" }
+  | { kind: "delete-row" }
+  | { kind: "delete-column" }
+  | { kind: "merge-cells" }
+  | { kind: "split-cell" }
+  | { kind: "set-cell-background"; color: string }
+  // Table-level (P2g)
+  | { kind: "set-table-width"; width: PublicTableWidth }
+  | { kind: "set-table-alignment"; alignment: "left" | "center" | "right" }
+  | { kind: "set-table-indent"; indent: PublicTableWidth }
+  | { kind: "set-table-layout-mode"; mode: "fixed" | "autofit" }
+  | { kind: "set-table-cell-margins"; margins: Partial<PublicTableCellMargins> }
+  | { kind: "set-table-borders"; borders: Partial<PublicTableBorders> }
+  | { kind: "set-table-style"; styleId: string | null }
+  | { kind: "set-table-caption"; caption: string | null }
+  | { kind: "set-table-description"; description: string | null }
+  // Column / row sizing + row props (P2h)
+  | { kind: "set-column-width"; columnIndex: number; twips: number }
+  | {
+      kind: "distribute-columns-evenly";
+      columnRange?: { from: number; to: number };
+    }
+  | {
+      kind: "set-row-height";
+      rowIndex: number;
+      twips: number;
+      rule: "auto" | "atLeast" | "exact";
+    }
+  | { kind: "set-row-cant-split"; rowIndex: number; value: boolean }
+  | { kind: "set-row-is-header"; rowIndex: number; value: boolean }
+  | {
+      kind: "set-row-alignment";
+      rowIndex: number;
+      alignment: "left" | "center" | "right";
+    }
+  | {
+      kind: "insert-rows";
+      rowIndex: number;
+      at: "before" | "after";
+      count: number;
+    }
+  | {
+      kind: "insert-columns";
+      columnIndex: number;
+      at: "before" | "after";
+      count: number;
+      widths?: readonly number[];
+    }
+  // Cell-level (P2i)
+  | {
+      kind: "set-cell-borders";
+      locator: PublicCellLocator;
+      borders: Partial<PublicTableCellBorders>;
+    }
+  | {
+      kind: "set-cell-shading";
+      locator: PublicCellLocator;
+      shading: Partial<PublicCellShading> | null;
+    }
+  | { kind: "clear-cell-shading"; locator: PublicCellLocator }
+  | {
+      kind: "set-cell-margins";
+      locator: PublicCellLocator;
+      margins: Partial<PublicTableCellMargins>;
+    }
+  | {
+      kind: "set-cell-vertical-align";
+      locator: PublicCellLocator;
+      align: "top" | "center" | "bottom";
+    }
+  | {
+      kind: "set-cell-text-direction";
+      locator: PublicCellLocator;
+      direction: "lrTb" | "tbRl" | "btLr";
+    }
+  | { kind: "set-cell-no-wrap"; locator: PublicCellLocator; value: boolean }
+  | { kind: "set-cell-fit-text"; locator: PublicCellLocator; value: boolean };
+
+/**
+ * Outcome of `ref.tables.apply(op)`.
+ */
+export interface TableOpResult {
+  /** Whether the op mutated canonical document state. */
+  changed: boolean;
+  /**
+   * When the op was refused (e.g. no table selection, merge not clean),
+   * a short human-readable reason. `null` when the op committed.
+   */
+  coercedReason: string | null;
+  /**
+   * Fresh capability snapshot post-op. `null` when there is no table in
+   * the current selection.
+   */
+  capabilities: TableStructureContextSnapshot | null;
+}
+
+/**
+ * The `tables` property on `WordReviewEditorRef`. Minimal surface in this
+ * phase: a typed dispatch boundary for every table op plus a capability
+ * read. Read-only geometry queries (columns, rows, render plan, ...)
+ * land with the layout engine + render kernel integration.
+ */
+export interface WordReviewEditorTablesFacet {
+  /** Dispatch a typed table op through the runtime. */
+  apply(op: TableOp): TableOpResult;
+  /** Current capability snapshot for the active table selection. */
+  getCapabilities(): TableStructureContextSnapshot | null;
+}
+
 export interface PageRegionHitTest {
   region: "body" | "header" | "footer" | "margin" | "gutter";
   sectionIndex: number;
@@ -1067,8 +1323,50 @@ export interface EditorViewStateSnapshot {
   activeObjectFrame: LayoutMeasurement["objectFrame"] | null;
   measurement: LayoutMeasurement;
   isFocused: boolean;
+  /**
+   * Role-scoped chrome dimension (spec §6.4).  Drives which action set the
+   * top toolbar renders: `"editor"` exposes authoring (insert, format,
+   * Mark-section menu, tracked-changes toggle), `"review"` exposes review
+   * queue nav + accept/reject, `"workflow"` exposes work-item traversal.
+   * Independent of `viewMode` / `documentMode`.
+   */
+  editorRole: EditorRole;
+  /**
+   * Pin state for detachable chrome surfaces — topnav and the selection
+   * tier tool.  Absent key means "docked default"; `detached: true` means
+   * the surface renders as a floating, user-positioned panel.  State is
+   * runtime-owned, per-session, and survives snapshot rebuilds.
+   */
+  chromePins: ChromePinsState;
+}
+
+/**
+ * Role-scoped chrome dimension (spec §6.4 of runtime-rendering-and-chrome-phase.md).
+ *
+ * - `"editor"` — authoring posture.  Toolbar surfaces format, insert menu,
+ *   Mark-section posture menu, tracked-changes display toggle, comment.
+ * - `"review"` — reviewing posture.  Toolbar surfaces prev/next, accept,
+ *   reject, accept-all / reject-all in scope, markup mode, comment.
+ * - `"workflow"` — workflow-actor posture.  Toolbar surfaces prev/next
+ *   work item, claim, skip, mark complete, mark blocked, jump to scope.
+ */
+export type EditorRole = "editor" | "review" | "workflow";
+
+/**
+ * Chrome surfaces that can be detached into a floating, draggable panel.
+ * Extend this union as new surfaces adopt the `DraggableFloat` primitive.
+ */
+export type ChromePinSurface = "topnav" | "selectionTier";
+
+export interface PinState {
+  /** True when the surface is detached from its default dock. */
+  detached: boolean;
+  /** User-chosen offset in CSS px from the surface's dock origin. */
+  offset: { x: number; y: number };
 }
 
+export type ChromePinsState = Partial<Record<ChromePinSurface, PinState>>;
+
 export interface CommandStateSnapshot {
   canUndo: boolean;
   canRedo: boolean;
@@ -1952,13 +2250,33 @@ export interface WordReviewEditorRef {
    * event has fired, the facet is always available.
    */
   readonly layout: WordReviewEditorLayoutFacet;
+  /**
+   * Typed dispatch boundary for every table operation the runtime
+   * supports. Existing flat verbs (`addRowBefore`, `setCellBackground`,
+   * …) remain as compatibility wrappers; new ops land through
+   * `ref.tables.apply(op)` with a typed discriminated union.
+   */
+  readonly tables: WordReviewEditorTablesFacet;
 }
 
+/**
+ * Density + role-scoped chrome preset.
+ *
+ * Historically a pure density knob (`selection` → `simple` → `advanced` →
+ * `review` progressively exposed more chrome).  `"workflow"` was added in
+ * chrome-phase R1 to surface workflow-actor primary actions (prev/next
+ * work item, claim, skip, mark complete, jump to scope) inline in the
+ * top toolbar.  Host apps that already use `chromePreset` keep working
+ * unchanged; consumers that want the new workflow view set the preset
+ * to `"workflow"`.  For finer-grained role control independent of
+ * density, set `editorRole` on the view state directly.
+ */
 export type WordReviewEditorChromePreset =
   | "selection"
   | "simple"
   | "advanced"
-  | "review";
+  | "review"
+  | "workflow";
 
 export interface WordReviewEditorChromeOptions {
   showReviewQueueBar: boolean;

package/src/core/commands/section-layout-commands.ts

@@ -21,6 +21,10 @@ import type {
   SectionBreakNode,
   SectionProperties,
 } from "../../model/canonical-document.ts";
+import type {
+  MarginPresetDefinition,
+  PageFormatDefinition,
+} from "../../runtime/layout/index.ts";
 
 // ---- Public types ----
 
@@ -57,6 +61,60 @@ export interface SectionLinkPatch {
   relationshipId?: string | null;
 }
 
+// ---- Page-format / margin-preset patch builders (R0.5) ----
+
+/**
+ * Build a `SectionLayoutPatch` that swaps the page size to a named format
+ * at the requested orientation.  Width/height are swapped when orientation
+ * is `"landscape"` so the caller does not have to think about which twip
+ * goes on which axis.
+ *
+ * `custom` formats carry `portraitWidthTwips === 0`; callers should pass
+ * their desired twips through `SectionLayoutPatch.pageSize` directly in
+ * that case rather than going through this helper.
+ */
+export function buildPageFormatPatch(
+  format: PageFormatDefinition,
+  orientation: "portrait" | "landscape",
+): SectionLayoutPatch {
+  if (format.portraitWidthTwips <= 0 || format.portraitHeightTwips <= 0) {
+    return {};
+  }
+  const [width, height] =
+    orientation === "landscape"
+      ? [format.portraitHeightTwips, format.portraitWidthTwips]
+      : [format.portraitWidthTwips, format.portraitHeightTwips];
+  return {
+    pageSize: {
+      width,
+      height,
+      orientation,
+    },
+  };
+}
+
+/**
+ * Build a `SectionLayoutPatch` that applies a named margin preset to the
+ * section.  `custom` presets carry zero values and are a no-op here; the
+ * caller should pass explicit twips through `SectionLayoutPatch.pageMargins`.
+ */
+export function buildMarginPresetPatch(
+  preset: MarginPresetDefinition,
+): SectionLayoutPatch {
+  if (preset.id === "custom") {
+    return {};
+  }
+  return {
+    pageMargins: {
+      top: preset.topTwips,
+      bottom: preset.bottomTwips,
+      left: preset.leftTwips,
+      right: preset.rightTwips,
+      gutter: preset.gutterTwips,
+    },
+  };
+}
+
 // ---- Insert section break ----
 
 /**