superdoc 2.2.1 → 2.3.0

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

@@ -0,0 +1,54 @@
+import { BlockNodeAddress } from './base.js';
+import { SelectionTarget, TextAddress } from './address.js';
+import { ReceiptEffects, TextMutationRange } from './receipt.js';
+export type SDErrorCode = 'INVALID_PAYLOAD' | 'INVALID_TARGET' | 'TARGET_NOT_FOUND' | 'ADDRESS_STALE' | 'PRECONDITION_FAILED' | 'REVISION_MISMATCH' | 'INVALID_CONTEXT' | 'INVALID_NESTING' | 'INVALID_PLACEMENT' | 'DUPLICATE_ID' | 'CAPABILITY_UNSUPPORTED' | 'RAW_MODE_REQUIRED' | 'PRESERVE_ONLY_VIOLATION' | 'NO_OP' | 'UNSUPPORTED_ENVIRONMENT' | 'INTERNAL_ERROR';
+export interface SDError {
+    code: SDErrorCode;
+    message: string;
+    path?: Array<string | number>;
+    /** The target that caused the error, when available. */
+    target?: BlockNodeAddress | TextAddress | SelectionTarget;
+    details?: Record<string, unknown>;
+}
+/**
+ * Discriminated target in a mutation resolution.
+ *
+ * - `TextAddress` (`kind: 'text'`): text-level insert/replace with block-relative offsets.
+ * - `BlockNodeAddress` (`kind: 'block'`): structural insert/replace targeting a whole block.
+ */
+export type MutationResolutionTarget = TextAddress | BlockNodeAddress;
+export interface SDMutationReceipt {
+    success: boolean;
+    failure?: SDError;
+    evaluatedRevision?: {
+        before: string;
+        after: string;
+    };
+    resolution?: {
+        target: MutationResolutionTarget;
+        /** Engine-resolved absolute document range for the effective target. */
+        range: TextMutationRange;
+        /** Full selection target for cross-block mutations. */
+        selectionTarget?: SelectionTarget;
+    };
+    /**
+     * Post-mutation created-content spans (inserted visible text / blocks).
+     *
+     * `resolution.target` is the resolved mutation target / insertion point; for
+     * a collapsed insert it stays a collapsed point. Callers that need to anchor
+     * to the content a mutation CREATED (citations, comments on inserted text)
+     * read it here instead. See {@link ReceiptEffects}.
+     */
+    effects?: ReceiptEffects;
+}
+export interface SDDiagnostic {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    path?: Array<string | number>;
+}
+export interface SDMarkdownToFragmentResult {
+    fragment: import('./fragment.js').SDFragment;
+    lossy: boolean;
+    diagnostics: SDDiagnostic[];
+}

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

@@ -0,0 +1,59 @@
+import { BlockNodeAddress, NodeAddress } from './base.js';
+import { TextSelector, NodeSelector } from './query.js';
+import { SDContentNode, SDInlineNode } from './sd-nodes.js';
+import { StoryLocator } from './story.types.js';
+export interface SDPoint {
+    blockId: string;
+    /** UTF-16 code units. */
+    offset: number;
+}
+export interface SDNodeContext {
+    ancestors?: Array<{
+        id: string;
+        kind: string;
+    }>;
+    sectionId?: string;
+    tablePosition?: {
+        tableId: string;
+        rowIndex: number;
+        cellIndex: number;
+    };
+    listPosition?: {
+        listId: string;
+        itemPath: number[];
+        level: number;
+    };
+}
+export interface SDReadOptions {
+    /** Include resolved (cascaded) property values. Default false. */
+    includeResolved?: boolean;
+    /** Include per-property provenance. Requires includeResolved=true. Default false. */
+    includeProvenance?: boolean;
+    /** Include SDNodeContext on SDNodeResult. Default false. */
+    includeContext?: boolean;
+}
+export interface SDGetInput {
+    /** Restrict the read to a specific story. Omit for body (backward compatible). */
+    in?: StoryLocator;
+    options?: SDReadOptions;
+}
+export interface SDFindInput {
+    select: TextSelector | NodeSelector;
+    within?: BlockNodeAddress;
+    /** Restrict the search to a specific story. Omit for body (backward compatible). */
+    in?: StoryLocator;
+    limit?: number;
+    offset?: number;
+    options?: SDReadOptions;
+}
+export interface SDNodeResult {
+    node: SDContentNode | SDInlineNode;
+    address: NodeAddress;
+    context?: SDNodeContext;
+}
+export interface SDFindResult {
+    total: number;
+    limit: number;
+    offset: number;
+    items: SDNodeResult[];
+}

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

@@ -0,0 +1,375 @@
+import { SDRunProps, SDParagraphProps, SDListProps, SDTableProps, SDRowProps, SDCellProps, SDImageProps, SDDrawingProps } from './sd-props.js';
+import { SDObjectLayout, SDObjectGeometry, SDObjectMediaRef, SDObjectCompat, SDAccessibilityInfo, SDDrawingSource, SDResolvedProvenance, SDResolvedTableLayout } from './sd-objects.js';
+import { SDSection } from './sd-sections.js';
+export interface SDNodeBase {
+    id?: string;
+    ext?: Record<string, unknown>;
+}
+export interface SDParagraphLikeIds {
+    /** OOXML paragraph identity (w14:paraId), when available. */
+    paraId?: string;
+    /** OOXML text identity (w14:textId), when available. */
+    textId?: string;
+}
+/** Base for paragraph-derived semantic nodes. */
+export interface SDParagraphLikeBase extends SDNodeBase {
+    paragraphIds?: SDParagraphLikeIds;
+}
+export interface SDParagraph extends SDParagraphLikeBase {
+    kind: 'paragraph';
+    paragraph: {
+        inlines: SDInlineNode[];
+        styleRef?: string;
+        props?: SDParagraphProps;
+        resolved?: Partial<SDParagraphProps>;
+        provenance?: SDResolvedProvenance<SDParagraphProps>;
+    };
+}
+export interface SDHeading extends SDParagraphLikeBase {
+    kind: 'heading';
+    heading: {
+        level: 1 | 2 | 3 | 4 | 5 | 6;
+        inlines: SDInlineNode[];
+        styleRef?: string;
+        props?: SDParagraphProps;
+        resolved?: Partial<SDParagraphProps>;
+        provenance?: SDResolvedProvenance<SDParagraphProps>;
+    };
+}
+export interface SDListLevelDef {
+    /** Level 0..8. */
+    level: number;
+    kind: 'ordered' | 'bullet';
+    format?: string;
+    text?: string;
+    start?: number;
+    restartAfterLevel?: number | null;
+}
+export interface SDListItem extends SDParagraphLikeBase {
+    level: number;
+    path?: number[];
+    marker?: string;
+    content: SDContentNode[];
+}
+export interface SDList extends SDParagraphLikeBase {
+    kind: 'list';
+    list: {
+        styleRef?: string;
+        props?: SDListProps;
+        resolved?: Partial<SDListProps>;
+        provenance?: SDResolvedProvenance<SDListProps>;
+        levels?: SDListLevelDef[];
+        items: SDListItem[];
+    };
+}
+export interface SDTableColumn {
+    /** Preferred/authored grid width in points; omit for auto/unspecified. */
+    width?: number;
+}
+export interface SDTableRow {
+    props?: SDRowProps;
+    cells: SDTableCell[];
+}
+export interface SDTableCell {
+    props?: SDCellProps;
+    colSpan?: number;
+    rowSpan?: number;
+    content: SDContentNode[];
+}
+export interface SDTable extends SDNodeBase {
+    kind: 'table';
+    table: {
+        styleRef?: string;
+        props?: SDTableProps;
+        resolved?: Partial<SDTableProps>;
+        provenance?: SDResolvedProvenance<SDTableProps>;
+        resolvedLayout?: SDResolvedTableLayout;
+        columns?: SDTableColumn[];
+        rows: SDTableRow[];
+    };
+}
+export interface SDToc extends SDNodeBase {
+    kind: 'toc';
+    toc: {
+        /** Raw TOC field instruction for lossless round-trip. */
+        instruction?: string;
+        sourceConfig?: {
+            outlineLevels?: {
+                from: number;
+                to: number;
+            };
+            useAppliedOutlineLevel?: boolean;
+            tcFieldIdentifier?: string;
+            tcFieldLevels?: {
+                from: number;
+                to: number;
+            };
+        };
+        displayConfig?: {
+            hyperlinks?: boolean;
+            hideInWebView?: boolean;
+            includePageNumbers?: boolean;
+            omitPageNumberLevels?: {
+                from: number;
+                to: number;
+            };
+            rightAlignPageNumbers?: boolean;
+            tabLeader?: 'none' | 'dot' | 'hyphen' | 'underscore' | 'middleDot';
+            separator?: string;
+        };
+        preservedSwitches?: {
+            customStyles?: Array<{
+                styleName: string;
+                level: number;
+            }>;
+            bookmarkName?: string;
+            captionType?: string;
+            seqFieldIdentifier?: string;
+            chapterSeparator?: string;
+            chapterNumberSource?: string;
+            preserveTabEntries?: boolean;
+            rawExtensions?: string[];
+        };
+        fieldState?: {
+            locked?: boolean;
+            dirty?: boolean;
+        };
+        entryCount?: number;
+    };
+}
+export interface SDDocumentIndex extends SDNodeBase {
+    kind: 'index';
+    index: {
+        instruction?: string;
+        config?: Record<string, unknown>;
+    };
+}
+export interface SDBibliography extends SDNodeBase {
+    kind: 'bibliography';
+    bibliography: {
+        style?: string;
+        instruction?: string;
+    };
+}
+export interface SDTableOfAuthorities extends SDNodeBase {
+    kind: 'tableOfAuthorities';
+    tableOfAuthorities: {
+        instruction?: string;
+        config?: Record<string, unknown>;
+    };
+}
+export interface SDBreak extends SDNodeBase {
+    kind: 'break';
+    break: {
+        type: 'page' | 'column';
+    };
+}
+export interface SDSectionBreak extends SDNodeBase {
+    kind: 'sectionBreak';
+    sectionBreak: {
+        targetSectionId: string;
+    };
+}
+export interface SDSectPr extends SDNodeBase {
+    kind: 'sectPr';
+    sectPr: {
+        section: SDSection;
+    };
+}
+export interface SDImage extends SDNodeBase {
+    kind: 'image';
+    image: {
+        src: string;
+        styleRef?: string;
+        accessibility?: SDAccessibilityInfo;
+        /** Convenience alias for accessibility.alt in simple workflows. */
+        alt?: string;
+        layout?: SDObjectLayout;
+        geometry?: SDObjectGeometry;
+        media?: SDObjectMediaRef;
+        compat?: SDObjectCompat;
+        props?: SDImageProps;
+        resolved?: Partial<SDImageProps>;
+        provenance?: SDResolvedProvenance<SDImageProps>;
+    };
+}
+export interface SDDrawing extends SDNodeBase {
+    kind: 'drawing';
+    drawing: {
+        source: SDDrawingSource;
+        accessibility?: SDAccessibilityInfo;
+        layout?: SDObjectLayout;
+        geometry?: SDObjectGeometry;
+        compat?: SDObjectCompat;
+        props?: SDDrawingProps;
+        resolved?: Partial<SDDrawingProps>;
+        provenance?: SDResolvedProvenance<SDDrawingProps>;
+    };
+}
+export interface SDSdt extends SDNodeBase {
+    kind: 'sdt';
+    sdt: {
+        tag?: string;
+        alias?: string;
+        type?: string;
+        appearance?: string;
+        placeholder?: string;
+        lock?: 'none' | 'content' | 'sdt' | 'both';
+        scope?: 'inline' | 'block' | 'row' | 'cell';
+        inlines?: SDInlineNode[];
+        content?: SDContentNode[];
+    };
+}
+export interface SDCustomXml extends SDNodeBase {
+    kind: 'customXml';
+    customXml: {
+        element?: string;
+        uri?: string;
+        itemId?: string;
+        scope?: 'inline' | 'block' | 'row' | 'cell';
+        attributes?: Record<string, string>;
+        inlines?: SDInlineNode[];
+        content?: SDContentNode[];
+    };
+}
+export interface SDAltChunk extends SDNodeBase {
+    kind: 'altChunk';
+    altChunk: {
+        relationshipId?: string;
+        format?: 'docx' | 'html' | 'rtf' | 'text' | string;
+        sourceUri?: string;
+        sourceBase64?: string;
+    };
+}
+export interface SDMath extends SDNodeBase {
+    kind: 'math';
+    math: {
+        placement?: 'inline' | 'block';
+        omml?: string;
+        latex?: string;
+        mathml?: string;
+    };
+}
+export interface SDField extends SDNodeBase {
+    kind: 'field';
+    field: {
+        fieldType?: string;
+        instruction?: string;
+        instructionTokens?: string[];
+        resultText?: string;
+        placement?: 'inline' | 'block';
+        locked?: boolean;
+        dirty?: boolean;
+    };
+}
+export interface SDRun extends SDNodeBase {
+    kind: 'run';
+    run: {
+        text: string;
+        styleRef?: string;
+        props?: SDRunProps;
+        resolved?: Partial<SDRunProps>;
+        provenance?: SDResolvedProvenance<SDRunProps>;
+    };
+}
+export interface SDHyperlink extends SDNodeBase {
+    kind: 'hyperlink';
+    hyperlink: {
+        href?: string;
+        anchor?: string;
+        docLocation?: string;
+        tooltip?: string;
+        targetFrame?: '_self' | '_blank' | '_parent' | '_top' | string;
+        history?: boolean;
+        inlines: Exclude<SDInlineNode, SDHyperlink>[];
+    };
+}
+export interface SDCrossRef extends SDNodeBase {
+    kind: 'crossRef';
+    crossRef: {
+        instruction?: string;
+        fieldType?: 'REF' | 'PAGEREF' | 'NOTEREF' | 'STYLEREF';
+        target?: string;
+        display?: string;
+        resolvedText?: string;
+    };
+}
+export interface SDIndexEntry extends SDNodeBase {
+    kind: 'indexEntry';
+    indexEntry: {
+        instruction?: string;
+        mainEntry?: string;
+        subEntry?: string;
+        bold?: boolean;
+        italic?: boolean;
+        crossReference?: string;
+    };
+}
+export interface SDSequenceField extends SDNodeBase {
+    kind: 'sequenceField';
+    sequenceField: {
+        instruction?: string;
+        identifier?: string;
+        format?: string;
+        restartLevel?: number;
+    };
+}
+export interface SDCitation extends SDNodeBase {
+    kind: 'citation';
+    citation: {
+        instruction?: string;
+        sourceIds?: string[];
+        displayText?: string;
+    };
+}
+export interface SDAuthorityEntry extends SDNodeBase {
+    kind: 'authorityEntry';
+    authorityEntry: {
+        instruction?: string;
+        longCitation?: string;
+        shortCitation?: string;
+        category?: string;
+        bold?: boolean;
+        italic?: boolean;
+    };
+}
+export interface SDTocEntry extends SDNodeBase {
+    kind: 'tocEntry';
+    tocEntry: {
+        instruction?: string;
+        text?: string;
+        level?: number;
+        tableIdentifier?: string;
+        omitPageNumber?: boolean;
+    };
+}
+export interface SDTab extends SDNodeBase {
+    kind: 'tab';
+    tab: Record<string, never>;
+}
+export interface SDLineBreak extends SDNodeBase {
+    kind: 'lineBreak';
+    lineBreak: Record<string, never>;
+}
+export interface SDFootnoteRef extends SDNodeBase {
+    kind: 'footnoteRef';
+    footnoteRef: {
+        noteId?: string;
+    };
+}
+export interface SDEndnoteRef extends SDNodeBase {
+    kind: 'endnoteRef';
+    endnoteRef: {
+        noteId?: string;
+    };
+}
+export interface SDExtContentNode extends SDNodeBase {
+    kind: `ext.${string}`;
+    [key: string]: unknown;
+}
+export interface SDExtInlineNode extends SDNodeBase {
+    kind: `ext.${string}`;
+    [key: string]: unknown;
+}
+export type SDContentNode = SDParagraph | SDHeading | SDList | SDTable | SDToc | SDDocumentIndex | SDBibliography | SDTableOfAuthorities | SDBreak | SDSectionBreak | SDSectPr | SDImage | SDDrawing | SDSdt | SDCustomXml | SDAltChunk | SDMath | SDField | SDExtContentNode;
+export type SDInlineNode = SDRun | SDHyperlink | SDCrossRef | SDIndexEntry | SDSequenceField | SDCitation | SDAuthorityEntry | SDTocEntry | SDImage | SDDrawing | SDSdt | SDCustomXml | SDMath | SDField | SDTab | SDLineBreak | SDFootnoteRef | SDEndnoteRef | SDExtInlineNode;

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

@@ -0,0 +1,144 @@
+/**
+ * SDM/1 object layout, geometry, media, and compatibility types.
+ *
+ * These types describe the positioning, sizing, and source data for
+ * visual objects (images, drawings) in the document model.
+ */
+export type SDObjectPlacement = 'inline' | 'block' | 'floating';
+export interface SDObjectHyperlinkTarget {
+    href?: string;
+    anchor?: string;
+    tooltip?: string;
+}
+export interface SDAccessibilityInfo {
+    /** Short alt text. */
+    alt?: string;
+    /** Object title (tooltip/name in some UIs). */
+    title?: string;
+    /** Long-form description. */
+    description?: string;
+    /** Object/UI name when present in source format. */
+    name?: string;
+    /** Mark decorative content with no semantic alt text. */
+    decorative?: boolean;
+    /** Source hidden flag for non-visual content. */
+    hidden?: boolean;
+    /** Optional click action hyperlink metadata. */
+    clickHyperlink?: SDObjectHyperlinkTarget;
+    /** Optional hover action hyperlink metadata. */
+    hoverHyperlink?: SDObjectHyperlinkTarget;
+}
+export interface SDObjectAnchor {
+    relativeX?: 'column' | 'page' | 'margin';
+    relativeY?: 'paragraph' | 'page' | 'margin';
+    alignX?: 'left' | 'center' | 'right' | 'inside' | 'outside';
+    alignY?: 'top' | 'center' | 'bottom' | 'inside' | 'outside' | 'inline';
+    /** Horizontal offset in points. */
+    offsetX?: number;
+    /** Vertical offset in points. */
+    offsetY?: number;
+    behindText?: boolean;
+    allowOverlap?: boolean;
+    layoutInCell?: boolean;
+    locked?: boolean;
+    anchorId?: string;
+    editId?: string;
+}
+export interface SDObjectWrap {
+    type: 'inline' | 'none' | 'square' | 'tight' | 'through' | 'topBottom';
+    side?: 'bothSides' | 'left' | 'right' | 'largest';
+    /** Wrap distances in points. */
+    distances?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    polygon?: Array<[number, number]>;
+}
+export interface SDObjectLayout {
+    placement?: SDObjectPlacement;
+    anchor?: SDObjectAnchor;
+    wrap?: SDObjectWrap;
+    zIndex?: number;
+}
+export interface SDObjectGeometry {
+    /** Width in points. */
+    width?: number;
+    /** Height in points. */
+    height?: number;
+    relativeSize?: {
+        widthPct?: number;
+        heightPct?: number;
+    };
+    transform?: {
+        rotation?: number;
+        flipH?: boolean;
+        flipV?: boolean;
+    };
+    /** Effect extent in points. */
+    effectExtent?: {
+        left?: number;
+        top?: number;
+        right?: number;
+        bottom?: number;
+    };
+    /** Crop percentages. */
+    crop?: {
+        leftPct?: number;
+        topPct?: number;
+        rightPct?: number;
+        bottomPct?: number;
+    };
+    fit?: 'contain' | 'cover' | 'fill' | 'scaleDown';
+}
+export interface SDObjectMediaRef {
+    relationshipId?: string;
+    embedId?: string;
+    link?: string;
+    src?: string;
+    mimeType?: string;
+    extension?: string;
+}
+export interface SDObjectCompat {
+    /** Optional mc:AlternateContent payload preserved for round-trip fidelity. */
+    alternateContent?: Record<string, unknown>;
+    /** Optional VML/w:pict fallback payload preserved for round-trip fidelity. */
+    legacyVml?: Record<string, unknown>;
+    /** Unmodeled source payload preserved for lossless round-trip. */
+    passthrough?: Record<string, unknown>;
+}
+export type SDDrawingSource = {
+    kind: 'image';
+    media?: SDObjectMediaRef;
+} | {
+    kind: 'vectorShape';
+    shapeKind?: string;
+    geometryData?: Record<string, unknown>;
+    styleData?: Record<string, unknown>;
+} | {
+    kind: 'shapeGroup';
+    children?: Array<{
+        kind: 'vectorShape' | 'image' | 'unknown';
+        data?: Record<string, unknown>;
+    }>;
+} | {
+    kind: 'externalObject';
+    objectType: 'chart' | 'smartArt' | 'diagram' | 'ole' | 'table' | 'unknown';
+    graphicDataUri?: string;
+    relations?: Record<string, string>;
+    data?: Record<string, unknown>;
+};
+export interface SDResolvedProperty<T> {
+    value: T;
+    source: 'docDefaults' | 'style' | 'linkedStyle' | 'tableConditional' | 'direct';
+    sourceRef?: string;
+    chain?: string[];
+}
+export type SDResolvedProvenance<TProps> = Partial<Record<keyof TProps, SDResolvedProperty<unknown>>>;
+export interface SDResolvedTableLayout {
+    /** Table width in points. */
+    tableWidth?: number;
+    /** Column widths in points. */
+    columnWidths?: number[];
+}