superdoc 2.24.0-next.1 → 2.24.0-next.11

package/dist/document-api/src/types/query-match.types.d.ts

@@ -4,6 +4,7 @@ import { TextSelector, NodeSelector } from './query.js';
 import { DiscoveryItem, DiscoveryResult } from './discovery.js';
 import { InlineToggleDirective } from './style-policy.types.js';
 import { StoryLocator } from './story.types.js';
+import { StyleCatalogPreviewSources } from '../styles/catalog.js';
 export type CardinalityRequirement = 'any' | 'first' | 'exactlyOne' | 'all';
 /** Maximum total length for a match snippet (D11). */
 export declare const SNIPPET_MAX_LENGTH = 500;
@@ -27,12 +28,32 @@ export interface MatchDirectStyles {
     underline: InlineToggleDirective;
     strike: InlineToggleDirective;
 }
-/** Effective visual states: what the user sees after style cascade resolution. */
+/**
+ * Where an effective font or color came from: set as a literal value, or a
+ * theme reference (with tint/shade). Same vocabulary as catalog preview sources.
+ */
+export type MatchEffectiveSources = StyleCatalogPreviewSources;
+/**
+ * Effective visual states: what the user sees after style cascade resolution
+ * (direct run formatting, character style, paragraph style chain, table style,
+ * document defaults, theme). The optional values are present when the cascade
+ * resolved them; `meta.effectiveResolved` says whether it ran.
+ */
 export interface MatchEffectiveStyles {
     bold: boolean;
     italic: boolean;
     underline: boolean;
     strike: boolean;
+    /** 6-digit lowercase hex with `#` prefix. Theme colors are resolved, tint/shade applied. */
+    color?: string;
+    /** 6-digit lowercase hex with `#` prefix. */
+    highlight?: string;
+    /** Latin-track font family. Theme fonts are resolved to the theme's typeface. */
+    fontFamily?: string;
+    /** Font size in points, rounded to 1 decimal place. */
+    fontSizePt?: number;
+    /** Origin of `fontFamily` and `color`. A value without a source is absent. */
+    sources?: MatchEffectiveSources;
 }
 /**
  * Two-layer inline style state for a single run.
@@ -171,16 +192,33 @@ export type QueryMatchItem = DiscoveryItem<QueryMatchDomain>;
 export type TextMatchItem = DiscoveryItem<TextMatchDomain>;
 /** Node match item (blocks.length === 0). */
 export type NodeMatchItem = DiscoveryItem<NodeMatchDomain>;
+/**
+ * Why `styles.effective` could not be fully resolved for a match result.
+ *
+ * - `tracked-view-unresolved`: tracked-view matches (`includeDeletedText`) are not cascade-resolved.
+ * - `theme-fallback`: a theme font or color came from the default Office theme because the
+ *   document's theme part or color scheme is missing or unreadable.
+ * - `style-parts-unavailable`: the document's style parts were not loaded, so styles were not applied.
+ * - `run-projection-unavailable`: the matched text could not be split into runs.
+ */
+export type QueryMatchDiagnosticCode = 'tracked-view-unresolved' | 'theme-fallback' | 'style-parts-unavailable' | 'run-projection-unavailable';
+export interface QueryMatchDiagnostic {
+    code: QueryMatchDiagnosticCode;
+    message: string;
+}
 /**
  * Metadata for `query.match`: always present on the output envelope.
  *
- * - `effectiveResolved: true`: converter context was available; `styles.effective`
- *   on every run reflects full cascade resolution.
- * - `effectiveResolved: false`: converter context was unavailable (headless/non-DOCX);
- *   `styles.effective` is derived from `direct` only.
+ * - `effectiveResolved: true`: `styles.effective` on every run reflects full
+ *   style cascade and theme resolution.
+ * - `effectiveResolved: false`: at least one run was not fully resolved, or the
+ *   engine derives `styles.effective` from `direct` only. `diagnostics`, when
+ *   present, says why.
  */
 export interface QueryMatchMeta {
     effectiveResolved: boolean;
+    /** Reasons the result is not fully resolved. Absent when there are none. */
+    diagnostics?: QueryMatchDiagnostic[];
 }
 export interface QueryMatchInput {
     /** Selector for query.match. Text selectors may opt into deleted tracked text via `includeDeletedText`. */

package/dist/document-api/src/types/receipt.d.ts

@@ -2,6 +2,7 @@ import { BlockNavigationAddress, EntityAddress, SelectionTarget, TextAddress, Tr
 import { BlockNodeAddress } from './base.js';
 import { BookmarkAddress } from '../bookmarks/bookmarks.types.js';
 import { StoryLocator } from './story.types.js';
+import { ChangeMode } from '../write/write.js';
 export type ReceiptInsert = TrackedChangeAddress;
 export type ReceiptEntity = EntityAddress;
 export type AffectedRef = TextAddress | BookmarkAddress | EntityAddress | BlockNavigationAddress;
@@ -109,6 +110,13 @@ export interface ReceiptEffects {
 }
 export type ReceiptSuccess = {
     success: true;
+    /**
+     * Mode in which this call's document content was committed. An edit folded
+     * into the author's existing insertion is tracked; auxiliary style and
+     * numbering definition writes do not change the content mode. Omitted for
+     * dry runs, no-ops, and operations that do not author reviewable content.
+     */
+    appliedChangeMode?: ChangeMode;
     /**
      * Convenience id for operations that create exactly one primary durable entity.
      * Generic consumers should prefer `inserted`; this field exists for simple

package/dist/document-api/src/types/sd-contract.d.ts

@@ -23,6 +23,8 @@ export interface SDError {
 export type MutationResolutionTarget = TextAddress | BlockNodeAddress | BodyStoryLocator;
 export interface SDMutationReceipt {
     success: boolean;
+    /** Effective content mode on a committed success; absent for no-op and dry-run calls. */
+    appliedChangeMode?: ReceiptSuccess['appliedChangeMode'];
     /** Rich HTML/Markdown fidelity outcome, when this receipt came from a rich write. */
     outcome?: SDHtmlMarkdownOutcome;
     failure?: SDError;

package/dist/document-api/src/types/sd-props.d.ts

@@ -1,10 +1,4 @@
-/**
- * SDM/1 property models: run, paragraph, table, list, image, drawing props.
- *
- * These define the direct formatting ("authored") property bags carried by
- * style-bearing nodes. Resolved/provenance fields are separate concerns
- * populated at read time by the style-engine.
- */
+import { ST_HIGHLIGHT_VALUES } from '../inline-semantics/token-sets.js';
 export type SDThemeFontRef = 'majorAscii' | 'majorHAnsi' | 'majorEastAsia' | 'majorBidi' | 'minorAscii' | 'minorHAnsi' | 'minorEastAsia' | 'minorBidi';
 export interface SDRunFonts {
     ascii?: string;
@@ -34,7 +28,7 @@ export type SDColorRef = {
 } | {
     model: 'auto';
 };
-export type SDHighlightColor = 'black' | 'blue' | 'cyan' | 'green' | 'magenta' | 'red' | 'yellow' | 'white' | 'darkBlue' | 'darkCyan' | 'darkGreen' | 'darkMagenta' | 'darkRed' | 'darkYellow' | 'darkGray' | 'lightGray' | 'none';
+export type SDHighlightColor = (typeof ST_HIGHLIGHT_VALUES)[number];
 export type SDUnderlineStyle = 'none' | 'single' | 'words' | 'double' | 'thick' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashedHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dashDotHeavy' | 'dotDotDash' | 'dashDotDotHeavy' | 'wave' | 'wavyHeavy' | 'wavyDouble';
 export interface SDUnderline {
     style?: SDUnderlineStyle;
@@ -47,7 +41,9 @@ export interface SDShading {
 }
 export interface SDRunBorder {
     style?: string;
+    /** Line width in points. */
     width?: number;
+    /** Spacing from the content in points. */
     space?: number;
     color?: SDColorRef;
     frame?: boolean;
@@ -186,10 +182,31 @@ export type SDTableWidth = {
 } | {
     kind: 'none';
 };
+/** Table border lines; `width` and `space` in points. */
+export interface SDTableBorders {
+    top?: SDRunBorder;
+    right?: SDRunBorder;
+    bottom?: SDRunBorder;
+    left?: SDRunBorder;
+    start?: SDRunBorder;
+    end?: SDRunBorder;
+    insideH?: SDRunBorder;
+    insideV?: SDRunBorder;
+}
+/** Cell padding in points. */
+export interface SDCellPadding {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    start?: number;
+    end?: number;
+}
 export interface SDTableProps {
     width?: SDTableWidth;
     layout?: 'fixed' | 'autofit';
     alignment?: 'left' | 'center' | 'right' | 'inside' | 'outside';
+    /** Normalized CSS-like edge borders retained for document and fragment compatibility. */
     borders?: {
         top?: string;
         right?: string;
@@ -198,28 +215,51 @@ export interface SDTableProps {
         insideH?: string;
         insideV?: string;
     };
+    /** Leading-edge indent in points. */
+    indent?: number;
+    /** Spacing between cells in points. */
+    cellSpacing?: number;
+    /** Default cell padding in points. */
+    cellPadding?: SDCellPadding;
+    shading?: SDShading;
+    /** Right-to-left visual column order (`w:bidiVisual`). */
+    bidiVisual?: boolean;
+}
+/** Table formatting authored on a table style. Borders are structured lines, not strings. */
+export interface SDTableStyleProps extends Omit<SDTableProps, 'borders'> {
+    borders?: SDTableBorders;
 }
 export interface SDRowProps {
     /** Minimum row height in points. */
     minHeight?: number;
     cantSplit?: boolean;
+    /** Repeat this row as a header row on each page (`w:tblHeader`). */
+    repeatHeader?: boolean;
+}
+/** Cell border lines; `width` and `space` in points. */
+export interface SDCellBorders extends SDTableBorders {
+    /** Diagonal from top-left to bottom-right. */
+    tl2br?: SDRunBorder;
+    /** Diagonal from top-right to bottom-left. */
+    tr2bl?: SDRunBorder;
 }
 export interface SDCellProps {
     verticalAlign?: 'top' | 'center' | 'bottom';
     shading?: SDColorRef;
     /** Cell padding in points. */
-    padding?: {
-        top?: number;
-        right?: number;
-        bottom?: number;
-        left?: number;
-    };
+    padding?: SDCellPadding;
+    /** Normalized CSS-like edge borders, such as `'single 1pt #000000'` or `'none'`. */
     borders?: {
         top?: string;
         right?: string;
         bottom?: string;
         left?: string;
     };
+    noWrap?: boolean;
+}
+/** Cell formatting authored on a table style. Borders are structured lines, not strings. */
+export interface SDTableStyleCellProps extends Omit<SDCellProps, 'borders'> {
+    borders?: SDCellBorders;
 }
 export interface SDImageProps {
     alignment?: 'left' | 'center' | 'right';

package/dist/document-api/src/types/sd-styles.d.ts

@@ -1,20 +1,69 @@
-import { SDRunProps, SDParagraphProps, SDTableProps, SDThemeColorName } from './sd-props.js';
+import { SDParagraphProps, SDRowProps, SDRunProps, SDTableProps, SDTableStyleProps, SDTableStyleCellProps, SDThemeColorName } from './sd-props.js';
+import { SDResolvedProvenance } from './sd-objects.js';
 export interface SDStyleBase<TProps> {
     name?: string;
     basedOn?: string;
     next?: string;
     linked?: string;
+    /** Properties authored on this style, with theme references left raw. */
     props?: TProps;
+    /** Cascaded values (basedOn chain, docDefaults, theme). Present with `includeResolved`. */
+    resolved?: Partial<TProps>;
+    /** Where each resolved value came from. Present with `includeProvenance`. */
+    provenance?: SDResolvedProvenance<TProps>;
+}
+export interface SDParagraphStyleDef extends SDStyleBase<SDParagraphProps> {
+    /** Run properties authored on this paragraph style (`w:rPr`). */
+    runProps?: SDRunProps;
+    /** Cascaded run values for text in this paragraph style. Present with `includeResolved`. */
+    resolvedRun?: Partial<SDRunProps>;
+    /** Where each resolved run value came from. Present with `includeProvenance`. */
+    runProvenance?: SDResolvedProvenance<SDRunProps>;
 }
-export type SDParagraphStyleDef = SDStyleBase<SDParagraphProps>;
 export type SDCharacterStyleDef = SDStyleBase<SDRunProps>;
-export type SDTableStyleDef = SDStyleBase<SDTableProps>;
+/** Table regions that a table style can format conditionally (`w:tblStylePr/@w:type`). */
+export type SDTableStyleRegion = 'wholeTable' | 'firstRow' | 'lastRow' | 'firstCol' | 'lastCol' | 'band1Vert' | 'band2Vert' | 'band1Horz' | 'band2Horz' | 'neCell' | 'nwCell' | 'seCell' | 'swCell';
+/** Formatting a table style applies to one region, as authored. */
+export interface SDTableStyleFormatting {
+    table?: SDTableStyleProps;
+    row?: SDRowProps;
+    cell?: SDTableStyleCellProps;
+    paragraph?: SDParagraphProps;
+    run?: SDRunProps;
+}
+export interface SDTableStyleDef extends SDStyleBase<SDTableStyleProps> {
+    /** Row defaults (`w:trPr`). */
+    rowProps?: SDRowProps;
+    /** Cell defaults (`w:tcPr`). */
+    cellProps?: SDTableStyleCellProps;
+    /** Paragraph formatting for text in the table (`w:pPr`). */
+    paragraphProps?: SDParagraphProps;
+    /** Run formatting for text in the table (`w:rPr`). */
+    runProps?: SDRunProps;
+    /**
+     * Conditional formatting per table region (`w:tblStylePr`), as authored.
+     * `resolved` / `provenance` cover table-level props only; regions are not cascaded.
+     */
+    conditional?: Partial<Record<SDTableStyleRegion, SDTableStyleFormatting>>;
+    /** Rows per horizontal band (`w:tblStyleRowBandSize`). */
+    rowBandSize?: number;
+    /** Columns per vertical band (`w:tblStyleColBandSize`). */
+    columnBandSize?: number;
+}
 export interface SDStyles {
     paragraph?: Record<string, SDParagraphStyleDef>;
     character?: Record<string, SDCharacterStyleDef>;
     table?: Record<string, SDTableStyleDef>;
 }
+/** Theme color roles that `w:clrSchemeMapping` maps onto theme color slots. */
+export type SDThemeColorRole = 'bg1' | 't1' | 'bg2' | 't2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hyperlink' | 'followedHyperlink';
 export interface SDTheme {
+    /**
+     * `document` when read from the package theme part; `fallback` when the part is
+     * missing or unreadable and the default Office theme stands in (see diagnostics).
+     */
+    source?: 'document' | 'fallback';
+    /** Six-digit hex colors without `#`, matching `SDColorRef` rgb values. */
     colorScheme: Record<SDThemeColorName, string>;
     fontScheme?: {
         major?: {
@@ -28,9 +77,15 @@ export interface SDTheme {
             complexScript?: string;
         };
     };
+    /** From `w:settings/w:clrSchemeMapping`; absent when the document declares none. */
+    colorSchemeMapping?: Partial<Record<SDThemeColorRole, SDThemeColorName>>;
 }
 export interface SDDocDefaults {
     run?: SDRunProps;
     paragraph?: SDParagraphProps;
     table?: SDTableProps;
+    /** `run` with theme references resolved. Present with `includeResolved`. */
+    resolvedRun?: Partial<SDRunProps>;
+    /** `paragraph` with theme references resolved. Present with `includeResolved`. */
+    resolvedParagraph?: Partial<SDParagraphProps>;
 }

package/dist/document-api/src/types/table-operations.types.d.ts

@@ -133,6 +133,7 @@ export type TableCreateLocation = TableAnchorLocation
  */
 export interface TableMutationSuccess {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     table?: TableAddress;
     trackedChangeRefs?: ReceiptInsert[];
 }
@@ -154,6 +155,7 @@ export interface CreateTableInput {
 }
 export interface CreateTableSuccessResult {
     success: true;
+    appliedChangeMode?: 'direct' | 'tracked';
     table: TableAddress;
     trackedChangeRefs?: ReceiptInsert[];
 }

package/dist/document-api/src/write/write.d.ts

@@ -1,6 +1,6 @@
 import { TextMutationReceipt, SDMutationReceipt } from '../types/index.js';
 import { InsertInput } from '../insert/insert.js';
-import { ReplaceInput } from '../replace/replace.js';
+import { ReplaceMutationOptions, ReplaceInput } from '../replace/replace.js';
 import { StoryLocator } from '../types/story.types.js';
 import { SDHtmlMarkdownCheckGuard } from '../capabilities/html-markdown-support.js';
 export type ChangeMode = 'direct' | 'tracked';
@@ -77,11 +77,13 @@ export type WriteRequest = InsertWriteRequest;
  * `SelectionMutationAdapter` instead.
  */
 export interface WriteAdapter {
+    readonly supportsParagraphContents?: boolean;
+    readonly supportsNativeOoxml?: boolean;
     write(request: InsertWriteRequest, options?: TextMutationOptions): TextMutationReceipt;
     /** Structured insert for SDFragment or markdown/html content. Returns SDMutationReceipt. */
     insertStructured(input: InsertInput, options?: RichContentMutationOptions): SDMutationReceipt;
     /** Structured replace for SDFragment or markdown/html content. Returns SDMutationReceipt. */
-    replaceStructured(input: ReplaceInput, options?: RichContentMutationOptions): SDMutationReceipt;
+    replaceStructured(input: ReplaceInput, options?: ReplaceMutationOptions): SDMutationReceipt;
 }
 export declare function normalizeMutationOptions(options?: MutationOptions | RichContentMutationOptions, supportCheckOperation?: 'insert' | 'replace'): RichContentMutationOptions;
 export declare function executeWrite(adapter: WriteAdapter, request: InsertWriteRequest, options?: TextMutationOptions): TextMutationReceipt;

package/dist/public/ui-react.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-D_FbXpOQ.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-bTFGKVRb.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let react = require("react");
 //#region src/public/ui/react.ts

package/dist/public/ui-react.es.js

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-DFNXiKvQ.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-8UTu16Lw.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { createContext, createElement, useCallback, useContext, useEffect, useRef, useState } from "react";
 //#region src/public/ui/react.ts

package/dist/public/ui-vue.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-D_FbXpOQ.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-bTFGKVRb.cjs");
 const require_slice_source = require("../chunks/slice-source-CFaqq0Vo.cjs");
 let superdoc_entry_vue = require("vue");
 //#region src/public/ui/vue.ts

package/dist/public/ui-vue.es.js

@@ -1,4 +1,4 @@
-import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-DFNXiKvQ.es.js";
+import { t as createSuperDocUI } from "../chunks/create-super-doc-ui-8UTu16Lw.es.js";
 import { t as toSliceSource } from "../chunks/slice-source-gfOhG2MW.es.js";
 import { computed, inject, onScopeDispose, provide, shallowRef, toRaw, toValue, watch } from "vue";
 //#region src/public/ui/vue.ts

package/dist/public/ui.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-D_FbXpOQ.cjs");
+const require_create_super_doc_ui = require("../chunks/create-super-doc-ui-bTFGKVRb.cjs");
 exports.BUILT_IN_COMMAND_IDS = require_create_super_doc_ui.BUILT_IN_COMMAND_IDS;
 exports.createSuperDocUI = require_create_super_doc_ui.createSuperDocUI;
 exports.shallowEqual = require_create_super_doc_ui.shallowEqual;

package/dist/public/ui.es.js

@@ -1,2 +1,2 @@
-import { a as BUILT_IN_COMMAND_IDS, t as createSuperDocUI, u as shallowEqual } from "../chunks/create-super-doc-ui-DFNXiKvQ.es.js";
+import { a as BUILT_IN_COMMAND_IDS, t as createSuperDocUI, u as shallowEqual } from "../chunks/create-super-doc-ui-8UTu16Lw.es.js";
 export { BUILT_IN_COMMAND_IDS, createSuperDocUI, shallowEqual };