superdoc 2.2.0 → 2.3.0

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

@@ -0,0 +1,61 @@
+import { BlockNodeAddress } from '../types/base.js';
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+export interface CaptionAddress {
+    kind: 'block';
+    nodeType: 'paragraph';
+    nodeId: string;
+}
+export interface CaptionListInput {
+    label?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface CaptionGetInput {
+    target: CaptionAddress;
+}
+export interface CaptionInsertInput {
+    adjacentTo: BlockNodeAddress;
+    position: 'above' | 'below';
+    label: string;
+    text?: string;
+}
+export interface CaptionUpdateInput {
+    target: CaptionAddress;
+    patch: {
+        text?: string;
+    };
+}
+export interface CaptionRemoveInput {
+    target: CaptionAddress;
+}
+export interface CaptionConfigureInput {
+    label: string;
+    format?: 'decimal' | 'lowerRoman' | 'upperRoman' | 'lowerLetter' | 'upperLetter';
+    includeChapter?: boolean;
+    chapterStyle?: string;
+}
+export interface CaptionInfo {
+    address: CaptionAddress;
+    label: string;
+    number: number;
+    text: string;
+    instruction: string;
+}
+export interface CaptionDomain {
+    address: CaptionAddress;
+    label: string;
+    number: number;
+    text: string;
+    instruction: string;
+}
+export interface CaptionMutationSuccess {
+    success: true;
+    caption: CaptionAddress;
+}
+export type CaptionMutationResult = CaptionMutationSuccess | AdapterMutationFailure;
+export interface CaptionConfigSuccess {
+    success: true;
+}
+export type CaptionConfigResult = CaptionConfigSuccess | AdapterMutationFailure;
+export type CaptionsListResult = DiscoveryOutput<CaptionDomain>;

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

@@ -0,0 +1,39 @@
+import { MutationOptions } from '../write/write.js';
+import { CitationListInput, CitationGetInput, CitationInsertInput, CitationUpdateInput, CitationRemoveInput, CitationInfo, CitationMutationResult, CitationsListResult, CitationSourceListInput, CitationSourceGetInput, CitationSourceInsertInput, CitationSourceUpdateInput, CitationSourceRemoveInput, CitationSourceInfo, CitationSourceMutationResult, CitationSourcesListResult, BibliographyInsertInput, BibliographyRebuildInput, BibliographyConfigureInput, BibliographyRemoveInput, BibliographyGetInput, BibliographyInfo, BibliographyMutationResult } from './citations.types.js';
+export interface CitationsApi {
+    list(query?: CitationListInput): CitationsListResult;
+    get(input: CitationGetInput): CitationInfo;
+    insert(input: CitationInsertInput, options?: MutationOptions): CitationMutationResult;
+    update(input: CitationUpdateInput, options?: MutationOptions): CitationMutationResult;
+    remove(input: CitationRemoveInput, options?: MutationOptions): CitationMutationResult;
+    sources: {
+        list(query?: CitationSourceListInput): CitationSourcesListResult;
+        get(input: CitationSourceGetInput): CitationSourceInfo;
+        insert(input: CitationSourceInsertInput, options?: MutationOptions): CitationSourceMutationResult;
+        update(input: CitationSourceUpdateInput, options?: MutationOptions): CitationSourceMutationResult;
+        remove(input: CitationSourceRemoveInput, options?: MutationOptions): CitationSourceMutationResult;
+    };
+    bibliography: {
+        get(input: BibliographyGetInput): BibliographyInfo;
+        insert(input: BibliographyInsertInput, options?: MutationOptions): BibliographyMutationResult;
+        rebuild(input: BibliographyRebuildInput, options?: MutationOptions): BibliographyMutationResult;
+        configure(input: BibliographyConfigureInput, options?: MutationOptions): BibliographyMutationResult;
+        remove(input: BibliographyRemoveInput, options?: MutationOptions): BibliographyMutationResult;
+    };
+}
+export type CitationsAdapter = CitationsApi;
+export declare function executeCitationsList(adapter: CitationsAdapter, query?: CitationListInput): CitationsListResult;
+export declare function executeCitationsGet(adapter: CitationsAdapter, input: CitationGetInput): CitationInfo;
+export declare function executeCitationsInsert(adapter: CitationsAdapter, input: CitationInsertInput, options?: MutationOptions): CitationMutationResult;
+export declare function executeCitationsUpdate(adapter: CitationsAdapter, input: CitationUpdateInput, options?: MutationOptions): CitationMutationResult;
+export declare function executeCitationsRemove(adapter: CitationsAdapter, input: CitationRemoveInput, options?: MutationOptions): CitationMutationResult;
+export declare function executeCitationSourcesList(adapter: CitationsAdapter, query?: CitationSourceListInput): CitationSourcesListResult;
+export declare function executeCitationSourcesGet(adapter: CitationsAdapter, input: CitationSourceGetInput): CitationSourceInfo;
+export declare function executeCitationSourcesInsert(adapter: CitationsAdapter, input: CitationSourceInsertInput, options?: MutationOptions): CitationSourceMutationResult;
+export declare function executeCitationSourcesUpdate(adapter: CitationsAdapter, input: CitationSourceUpdateInput, options?: MutationOptions): CitationSourceMutationResult;
+export declare function executeCitationSourcesRemove(adapter: CitationsAdapter, input: CitationSourceRemoveInput, options?: MutationOptions): CitationSourceMutationResult;
+export declare function executeBibliographyGet(adapter: CitationsAdapter, input: BibliographyGetInput): BibliographyInfo;
+export declare function executeBibliographyInsert(adapter: CitationsAdapter, input: BibliographyInsertInput, options?: MutationOptions): BibliographyMutationResult;
+export declare function executeBibliographyRebuild(adapter: CitationsAdapter, input: BibliographyRebuildInput, options?: MutationOptions): BibliographyMutationResult;
+export declare function executeBibliographyConfigure(adapter: CitationsAdapter, input: BibliographyConfigureInput, options?: MutationOptions): BibliographyMutationResult;
+export declare function executeBibliographyRemove(adapter: CitationsAdapter, input: BibliographyRemoveInput, options?: MutationOptions): BibliographyMutationResult;

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

@@ -0,0 +1,151 @@
+import { InlineAnchor } from '../types/base.js';
+import { TextTarget } from '../types/address.js';
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+import { TocCreateLocation } from '../toc/toc.types.js';
+export interface CitationAddress {
+    kind: 'inline';
+    nodeType: 'citation';
+    anchor: InlineAnchor;
+}
+export interface CitationSourceAddress {
+    kind: 'entity';
+    entityType: 'citationSource';
+    sourceId: string;
+}
+export interface BibliographyAddress {
+    kind: 'block';
+    nodeType: 'bibliography';
+    nodeId: string;
+}
+export type CitationSourceType = 'book' | 'journalArticle' | 'conferenceProceedings' | 'report' | 'website' | 'patent' | 'case' | 'statute' | 'thesis' | 'film' | 'interview' | 'misc';
+export interface CitationPerson {
+    first?: string;
+    middle?: string;
+    last: string;
+}
+/** Fields follow the OOXML bibliography schema (Sources.xsd). */
+export interface CitationSourceFields {
+    title?: string;
+    authors?: CitationPerson[];
+    year?: string;
+    publisher?: string;
+    city?: string;
+    journalName?: string;
+    volume?: string;
+    issue?: string;
+    pages?: string;
+    url?: string;
+    doi?: string;
+    edition?: string;
+    editor?: CitationPerson[];
+    translator?: CitationPerson[];
+    medium?: string;
+    shortTitle?: string;
+    standardNumber?: string;
+}
+export interface CitationListInput {
+    limit?: number;
+    offset?: number;
+}
+export interface CitationGetInput {
+    target: CitationAddress;
+}
+export interface CitationRemoveInput {
+    target: CitationAddress;
+}
+export interface CitationInsertInput {
+    at: TextTarget;
+    sourceIds: string[];
+}
+export interface CitationUpdateInput {
+    target: CitationAddress;
+    patch: {
+        sourceIds?: string[];
+    };
+}
+export interface CitationInfo {
+    address: CitationAddress;
+    sourceIds: string[];
+    displayText: string;
+    instruction: string;
+}
+export interface CitationDomain {
+    address: CitationAddress;
+    sourceIds: string[];
+    displayText: string;
+    instruction: string;
+}
+export interface CitationSourceListInput {
+    type?: CitationSourceType;
+    limit?: number;
+    offset?: number;
+}
+export interface CitationSourceGetInput {
+    target: CitationSourceAddress;
+}
+export interface CitationSourceRemoveInput {
+    target: CitationSourceAddress;
+}
+export interface CitationSourceInsertInput {
+    type: CitationSourceType;
+    fields: CitationSourceFields;
+}
+export interface CitationSourceUpdateInput {
+    target: CitationSourceAddress;
+    patch: Partial<CitationSourceFields>;
+}
+export interface CitationSourceInfo {
+    address: CitationSourceAddress;
+    sourceId: string;
+    tag: string;
+    type: CitationSourceType;
+    fields: CitationSourceFields;
+}
+export interface CitationSourceDomain {
+    address: CitationSourceAddress;
+    sourceId: string;
+    tag: string;
+    type: CitationSourceType;
+    fields: CitationSourceFields;
+}
+export interface BibliographyInsertInput {
+    at: TocCreateLocation;
+    style?: string;
+}
+export interface BibliographyRebuildInput {
+    target: BibliographyAddress;
+}
+export interface BibliographyConfigureInput {
+    target: BibliographyAddress;
+    style: string;
+}
+export interface BibliographyRemoveInput {
+    target: BibliographyAddress;
+}
+export interface BibliographyGetInput {
+    target: BibliographyAddress;
+}
+export interface BibliographyInfo {
+    address: BibliographyAddress;
+    style: string;
+    sourceCount: number;
+    instruction: string;
+}
+export interface CitationMutationSuccess {
+    success: true;
+    citation: CitationAddress;
+}
+export type CitationMutationResult = CitationMutationSuccess | AdapterMutationFailure;
+export interface CitationSourceMutationSuccess {
+    success: true;
+    source: CitationSourceAddress;
+}
+export type CitationSourceMutationResult = CitationSourceMutationSuccess | AdapterMutationFailure;
+export interface BibliographyMutationSuccess {
+    success: true;
+    bibliography: BibliographyAddress;
+}
+export type BibliographyMutationResult = BibliographyMutationSuccess | AdapterMutationFailure;
+export type CitationsListResult = DiscoveryOutput<CitationDomain>;
+export type CitationSourcesListResult = DiscoveryOutput<CitationSourceDomain>;

package/dist/document-api/src/clear-content/clear-content.d.ts

@@ -0,0 +1,25 @@
+import { Receipt } from '../types/receipt.js';
+import { RevisionGuardOptions } from '../write/write.js';
+export type ClearContentInput = Record<string, never>;
+/**
+ * Engine-specific adapter that clears all document body content.
+ */
+export interface ClearContentAdapter {
+    /**
+     * Clear the document body, replacing all content with a single empty paragraph.
+     */
+    clearContent(input: ClearContentInput, options?: RevisionGuardOptions): Receipt;
+}
+/**
+ * Execute a clearContent operation through the provided adapter.
+ *
+ * clearContent is a destructive reset: tracked mode and dry run are not
+ * meaningful, so this accepts {@link RevisionGuardOptions} rather than
+ * `MutationOptions`.
+ *
+ * @param adapter - Engine-specific clear-content adapter.
+ * @param input - Canonical clear-content input (empty object).
+ * @param options - Optional revision guard options.
+ * @returns A Receipt indicating success or NO_OP if already empty.
+ */
+export declare function executeClearContent(adapter: ClearContentAdapter, input: ClearContentInput, options?: RevisionGuardOptions): Receipt;

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

@@ -0,0 +1,11 @@
+import { MutationOptions } from '../write/write.js';
+import { ClipboardInsertInput, ClipboardInsertResult, ClipboardParseOptions, ClipboardParseResult, ClipboardPayload, ClipboardSerializeInput, ClipboardSerializeResult } from '../types/clipboard.js';
+export interface ClipboardApi {
+    parse(payload: ClipboardPayload, options?: ClipboardParseOptions): ClipboardParseResult;
+    insert(input: ClipboardInsertInput, options?: MutationOptions): ClipboardInsertResult;
+    serializeSelection(input?: ClipboardSerializeInput): ClipboardSerializeResult;
+}
+export type ClipboardAdapter = ClipboardApi;
+export declare function executeClipboardParse(adapter: ClipboardAdapter, payload: ClipboardPayload, options?: ClipboardParseOptions): ClipboardParseResult;
+export declare function executeClipboardInsert(adapter: ClipboardAdapter, input: ClipboardInsertInput, options?: MutationOptions): ClipboardInsertResult;
+export declare function executeClipboardSerializeSelection(adapter: ClipboardAdapter, input?: ClipboardSerializeInput): ClipboardSerializeResult;

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

@@ -0,0 +1,222 @@
+import { Receipt, ReceiptFailureResult, ReceiptSuccess, StoryLocator } from '../types/index.js';
+import { CommentInfo, CommentTarget, CommentsListQuery, CommentsListResult, TextSearchCommentTarget, TrackedChangeCommentTarget, TrackedChangeCommentTargetSide } from './comments.types.js';
+import { RevisionGuardOptions } from '../write/write.js';
+export type { TextSearchCommentTarget, TrackedChangeCommentTarget, TrackedChangeCommentTargetSide };
+/**
+ * Input for adding a comment to a text range.
+ *
+ * `target` accepts either a single-block {@link TextAddress} or a multi-
+ * segment {@link TextTarget}. A multi-segment target anchors the comment
+ * across contiguous blocks: use it directly from `editor.doc.selection.current().target`
+ * without picking a single segment.
+ */
+export interface AddCommentInput {
+    /**
+     * The text range to attach the comment to.
+     *
+     * Pass a {@link TextAddress} for single-block ranges (e.g. from `find`'s
+     * `textRanges[0]`), a {@link TextTarget} with multi-segment for
+     * selections that span multiple blocks, or a
+     * {@link TrackedChangeCommentTarget} that names a logical tracked-change
+     * id as a convenience anchor (the adapter normalizes it to the actual
+     * content range on the relevant revision side).
+     */
+    target?: CommentTarget;
+    /** The comment body text. */
+    text: string;
+}
+export interface EditCommentInput {
+    commentId: string;
+    text: string;
+}
+export interface ReplyToCommentInput {
+    parentCommentId: string;
+    text: string;
+}
+export interface MoveCommentInput {
+    commentId: string;
+    /**
+     * New anchor target. Accepts a plain {@link TextAddress}, a
+     * {@link SelectionTarget}, or a {@link TrackedChangeCommentTarget} that
+     * names a logical tracked-change id as a convenience re-anchor target.
+     */
+    target: CommentTarget;
+}
+export interface ResolveCommentInput {
+    commentId: string;
+}
+/**
+ * Input for reopening a previously-resolved comment. Accepted as the
+ * `status: 'active'` branch of `comments.patch`.
+ */
+export interface ReopenCommentInput {
+    commentId: string;
+}
+export interface RemoveCommentInput {
+    commentId: string;
+}
+export interface SetCommentInternalInput {
+    commentId: string;
+    isInternal: boolean;
+}
+export interface SetCommentActiveInput {
+    commentId: string | null;
+}
+export interface GoToCommentInput {
+    commentId: string;
+}
+export interface GetCommentInput {
+    commentId: string;
+}
+/**
+ * Input for `comments.create`: creates a new comment thread or a reply.
+ *
+ * When `parentCommentId` is provided, creates a reply on an existing thread.
+ * Otherwise, creates a new root comment anchored to the given text range.
+ */
+export interface CommentsCreateInput {
+    /** The comment body text. */
+    text: string;
+    /**
+     * The text range to attach the comment to (root comments only).
+     *
+     * Accepts either a single-block {@link TextAddress}, a multi-segment
+     * {@link TextTarget}, or a {@link TrackedChangeCommentTarget} that
+     * names a logical tracked-change id as a convenience anchor. Prefer
+     * passing `editor.doc.selection.current().target` directly for
+     * selections that may span multiple blocks.
+     */
+    target?: CommentTarget;
+    /**
+     * Compatibility shorthand for {@link TrackedChangeCommentTarget}. When
+     * `target` is omitted, execute normalizes this to
+     * `target: { trackedChangeId, side, story }` before validation.
+     */
+    trackedChangeId?: string;
+    /** Optional side for the `trackedChangeId` shorthand. */
+    side?: TrackedChangeCommentTargetSide;
+    /** Optional story for the `trackedChangeId` shorthand. */
+    story?: StoryLocator;
+    /** Parent comment ID: when provided, creates a reply instead of a root comment. */
+    parentCommentId?: string;
+    /**
+     * Public contract alias for {@link parentCommentId}. Pass either key, or
+     * both when they contain the same value.
+     */
+    parentId?: string;
+}
+/**
+ * Input for `comments.patch`: field-level patch on an existing comment.
+ *
+ * Exactly one mutation field (`text`, `target`, `status`, `isInternal`)
+ * must be provided per call. Providing zero or multiple fields throws
+ * `INVALID_INPUT`.
+ */
+export interface CommentsPatchInput {
+    /** The ID of the comment to patch. */
+    commentId: string;
+    /** New body text (routes to edit). */
+    text?: string;
+    /**
+     * New anchor range (routes to move). Accepts a plain
+     * {@link TextAddress} or {@link SelectionTarget} for direct anchor replacement, or a
+     * {@link TrackedChangeCommentTarget} that names a logical
+     * tracked-change id as a convenience re-anchor target.
+     */
+    target?: CommentTarget;
+    /**
+     * Lifecycle transition. `'resolved'` routes to resolve, `'active'`
+     * routes to reopen: symmetric inverse that removes the resolve
+     * anchors and restores the live comment mark.
+     */
+    status?: 'resolved' | 'active';
+    /** Set the internal/private flag (routes to setInternal). */
+    isInternal?: boolean;
+}
+/**
+ * Input for `comments.delete`: removes a comment by ID.
+ */
+export interface CommentsDeleteInput {
+    /** The ID of the comment to delete. */
+    commentId: string;
+}
+export type CommentsCreateReceiptSuccess = ReceiptSuccess & {
+    /** Convenience alias for the created comment id. */
+    id: string;
+};
+export type CommentsCreateReceipt = CommentsCreateReceiptSuccess | ReceiptFailureResult;
+/**
+ * Engine-specific adapter that the comments API delegates to.
+ */
+export interface CommentsAdapter {
+    /** Add a comment at the specified text range. */
+    add(input: AddCommentInput, options?: RevisionGuardOptions): CommentsCreateReceipt;
+    /** Edit the body text of an existing comment. */
+    edit(input: EditCommentInput, options?: RevisionGuardOptions): Receipt;
+    /** Reply to an existing comment thread. */
+    reply(input: ReplyToCommentInput, options?: RevisionGuardOptions): CommentsCreateReceipt;
+    /** Move a comment to a different text range. */
+    move(input: MoveCommentInput, options?: RevisionGuardOptions): Receipt;
+    /** Resolve an open comment. */
+    resolve(input: ResolveCommentInput, options?: RevisionGuardOptions): Receipt;
+    /**
+     * Reopen a previously-resolved comment. Symmetric inverse of
+     * {@link CommentsAdapter.resolve}: removes the
+     * `commentRangeStart` / `commentRangeEnd` anchor nodes inserted at
+     * resolve time and restores the live `comment` mark across the
+     * original range so subsequent operations see the comment as active.
+     */
+    reopen(input: ReopenCommentInput, options?: RevisionGuardOptions): Receipt;
+    /** Remove a comment from the document. */
+    remove(input: RemoveCommentInput, options?: RevisionGuardOptions): Receipt;
+    /** Set the internal/private flag on a comment. */
+    setInternal(input: SetCommentInternalInput, options?: RevisionGuardOptions): Receipt;
+    /** Set which comment is currently active/focused. Pass `null` to clear. */
+    setActive(input: SetCommentActiveInput, options?: RevisionGuardOptions): Receipt;
+    /** Scroll to and focus a comment in the document. */
+    goTo(input: GoToCommentInput): Receipt;
+    /** Retrieve full information for a single comment. */
+    get(input: GetCommentInput): CommentInfo;
+    /** List comments matching the given query. */
+    list(query?: CommentsListQuery): CommentsListResult;
+}
+/**
+ * Public comments API surface exposed on `editor.doc.comments`.
+ *
+ * Canonical operations: `create`, `patch`, `delete`, `get`, `list`.
+ *
+ * Excludes UI-state operations (`setActive`, `goTo`) that live on
+ * {@link CommentsAdapter} for internal editor use but are not part
+ * of the document-api contract.
+ */
+export interface CommentsApi {
+    create(input: CommentsCreateInput, options?: RevisionGuardOptions): CommentsCreateReceipt;
+    patch(input: CommentsPatchInput, options?: RevisionGuardOptions): Receipt;
+    delete(input: CommentsDeleteInput, options?: RevisionGuardOptions): Receipt;
+    get(input: GetCommentInput): CommentInfo;
+    list(query?: CommentsListQuery): CommentsListResult;
+}
+/**
+ * Execute `comments.create`: routes to `adapter.add` or `adapter.reply`
+ * depending on whether `parentCommentId` is provided.
+ *
+ * Accepts {@link RevisionGuardOptions} instead of `MutationOptions` because
+ * comments route to specialized adapter methods (add/edit/reply/move/resolve/remove)
+ * outside the plan engine, so changeMode and dryRun are not applicable.
+ */
+export declare function executeCommentsCreate(adapter: CommentsAdapter, input: CommentsCreateInput, options?: RevisionGuardOptions): CommentsCreateReceipt;
+/**
+ * Execute `comments.patch`: routes to exactly one adapter method based on
+ * the single mutation field provided. Validation enforces one-field-per-call.
+ *
+ * Accepts {@link RevisionGuardOptions} instead of `MutationOptions` because
+ * comments route to specialized adapter methods (add/edit/reply/move/resolve/remove)
+ * outside the plan engine, so changeMode and dryRun are not applicable.
+ */
+export declare function executeCommentsPatch(adapter: CommentsAdapter, input: CommentsPatchInput, options?: RevisionGuardOptions): Receipt;
+/**
+ * Execute `comments.delete`: routes to `adapter.remove`.
+ */
+export declare function executeCommentsDelete(adapter: CommentsAdapter, input: CommentsDeleteInput, options?: RevisionGuardOptions): Receipt;
+export declare function executeGetComment(adapter: CommentsAdapter, input: GetCommentInput): CommentInfo;
+export declare function executeListComments(adapter: CommentsAdapter, query?: CommentsListQuery): CommentsListResult;