@arbidocs/blocks 0.4.108 → 0.4.110

package/node_modules/@arbidocs/coedit/dist/commands.d.cts

@@ -0,0 +1,235 @@
+/**
+ * The read side of the Word-editor commands: a document's paragraphs as the commands see them
+ * (text in the engine's offset vocabulary, bookmarks, internal links, fields, note references),
+ * read from the engine's OOXML tree. The same tree comes from a live editor
+ * (`surface.session.part().root`) or from document bytes (`openHeadlessDocument`), so the toolbar
+ * and ARBI's headless tools read a document the same way.
+ */
+/** Character style of an inserted term: a dotted underline, so a defined term reads as one. */
+declare const DEFINED_TERM_STYLE = "DefinedTerm";
+/** Character style of a cross-reference: a muted blue with a dotted underline (Word's name). */
+declare const CROSS_REFERENCE_STYLE = "CrossReference";
+/** Character style of a cross-reference whose target is gone: its last text, flagged. */
+declare const BROKEN_CROSS_REFERENCE_STYLE = "CrossReferenceBroken";
+/** A position: a paragraph (the engine's node id) and a UTF-16 offset into its text. */
+interface DocPoint {
+    paragraphId: string;
+    offset: number;
+}
+/** An internal link in a paragraph. */
+interface DocLink {
+    anchor: string;
+    text: string;
+    /** Where its text starts in the paragraph's text. */
+    offset?: number;
+}
+/** A footnote or endnote reference: one character of the paragraph, as the engine counts it. */
+interface DocNote {
+    offset: number;
+    kind: 'footnote' | 'endnote';
+    /** `w:id` of the note. */
+    id: string;
+}
+/** One paragraph, in document order. */
+interface DocParagraph {
+    id: string;
+    /** `w14:paraId`, the id that is the same in every replica of a collaboration room. */
+    paraId?: string;
+    text: string;
+    /** Styled as a heading (a `Heading n` style or an outline level). */
+    heading: boolean;
+    styleId?: string;
+    /** A paragraph of the body itself, not inside a table. */
+    topLevel: boolean;
+    /** Names of the bookmarks that start in it. */
+    bookmarks: string[];
+    /** Its internal links (`w:hyperlink w:anchor`). */
+    links: DocLink[];
+    /** Its complex fields: where each sits (its one-character offset), its instruction and result. */
+    fields?: DocField[];
+    /** Its runs in a watched character style (a broken cross-reference's mark), with their text. */
+    marks?: DocMark[];
+    /** Its footnote and endnote references. */
+    notes?: DocNote[];
+}
+/** A stretch of a paragraph's text in a watched character style. */
+interface DocMark {
+    styleId: string;
+    offset: number;
+    text: string;
+}
+/** Character styles whose runs a paragraph read reports as marks. */
+declare const WATCHED_STYLES: Set<string>;
+/** A complex field of a paragraph. */
+interface DocField {
+    offset: number;
+    instruction: string;
+    result: string;
+}
+type OoxmlNodeLike = {
+    id: string;
+    kind: string;
+    localName?: string;
+    value?: string;
+    attributes?: readonly {
+        localName: string;
+        value: string;
+    }[];
+    children?: readonly OoxmlNodeLike[];
+};
+/** How a field (or a note reference) counts in a paragraph's text (the engine's model vocabulary). */
+declare const FIELD_ATOM = "\uFFFC";
+/** The paragraphs of a part's body, read from the engine's OOXML tree. */
+declare function readParagraphs(root: OoxmlNodeLike): DocParagraph[];
+/** Style id to style name (`Heading1` → `heading 1`), from a styles part's tree. */
+declare function styleNames(root: OoxmlNodeLike | null | undefined): Map<string, string>;
+
+/**
+ * Cross-reference targets: the document's numbered paragraphs (clauses, sub-clauses, numbered
+ * captions) and its headings, with the number Word's `REF \r` shows for each.
+ *
+ * The number is what the editor computes for a `REF … \r` field — and it has to be exactly that,
+ * because the engine shows a field's live value only while the field's cached result matches what
+ * it computes (otherwise it keeps the cached text for good). So this mirrors the engine: the
+ * paragraph's own list level, preceded by each higher level whose number its level text does not
+ * already show (`%1.%2` already shows level 1; `(%3)` does not show `2.1`), and one trailing
+ * period dropped (`2.` reads `2`).
+ */
+
+/** A paragraph's resolved list numbering (the engine's list item). */
+interface ListItemInfo {
+    numId: string;
+    ilvl: number;
+    markerText: string;
+    numFmt: string;
+}
+/** A list level's definition: its level text (`%1.%2`) and number format. */
+interface LevelInfo {
+    lvlText: string;
+    numFmt: string;
+}
+type LevelOf = (numId: string, ilvl: number) => LevelInfo | null;
+/**
+ * The number `REF \r` shows for a paragraph, or null when it is not numbered. `order` is every
+ * paragraph id in document order (for the markers of the levels above it).
+ */
+declare function paragraphNumber(order: readonly string[], items: ReadonlyMap<string, ListItemInfo>, levelOf: LevelOf, paragraphId: string): string | null;
+/** One place a cross-reference can point at. */
+interface CrossReferenceTarget {
+    paragraphId: string;
+    /** A numbered paragraph (clause, sub-clause, caption) or an unnumbered heading. */
+    kind: 'numbered' | 'heading';
+    /** What `REF \r` shows (`8.2`), or null for an unnumbered heading. */
+    number: string | null;
+    /** The paragraph's list marker as painted (`8.2`, `(a)`), or empty. */
+    marker: string;
+    /** The paragraph's text (without its marker). */
+    text: string;
+    heading: boolean;
+    /** Its list level (0 for a top-level clause), or 0 for a heading. */
+    level: number;
+}
+/** Every numbered paragraph and every heading, in document order. */
+declare function listTargets(paragraphs: readonly DocParagraph[], items: ReadonlyMap<string, ListItemInfo>, levelOf: LevelOf): CrossReferenceTarget[];
+/** Targets whose number or text contains the query (case-insensitive). */
+declare function filterTargets(targets: readonly CrossReferenceTarget[], query: string): CrossReferenceTarget[];
+/** What the engine's numbering needs of a document: its parts' trees. */
+interface NumberingSource {
+    /** The main document part's root. */
+    root(): OoxmlNodeLike;
+    stylesRoot(): unknown;
+    numberingRoot(): unknown;
+    settingsRoot(): unknown;
+}
+/** A document's list numbering as the engine resolves it. */
+interface DocumentNumbering {
+    /** Each numbered paragraph's list item, by paragraph (node) id. */
+    listItems(): ReadonlyMap<string, ListItemInfo>;
+    levelOf: LevelOf;
+}
+/**
+ * The numbering of a document, as the editor paints it: from a live editor's session or from a
+ * headless document view alike.
+ */
+declare function documentNumbering(source: NumberingSource): DocumentNumbering;
+
+/**
+ * The cross-references of a document (`REF` fields to `_Ref` bookmarks), each with what it shows
+ * and what its target now is: current, stale (a clause renumbered, a heading reworded) or broken
+ * (the target is gone).
+ */
+
+/** Prefix of Word's hidden cross-reference bookmarks. */
+declare const REF_BOOKMARK_PREFIX = "_Ref";
+type CrossReferenceMode = 'number' | 'text';
+/** What reading cross-references needs of a document. */
+interface ReferencesReader {
+    paragraphs(): DocParagraph[];
+    /** Each numbered paragraph's list item, by paragraph id. */
+    listItems(): ReadonlyMap<string, ListItemInfo>;
+    levelOf: LevelOf;
+}
+/** One `REF` field to a `_Ref` bookmark. */
+interface CrossReference {
+    paragraphId: string;
+    offset: number;
+    instruction: string;
+    bookmark: string;
+    mode: CrossReferenceMode;
+    /** The field's cached result (what it shows). */
+    cached: string;
+    /** The paragraph the bookmark is in, or null when it is gone (the reference is broken). */
+    target: string | null;
+    /** What the reference should show now, or null when that cannot be computed. */
+    value: string | null;
+}
+/** A `REF` field whose cached result no longer says what its target now is. */
+interface StaleReference {
+    paragraphId: string;
+    offset: number;
+    instruction: string;
+    /** The current value, or null when the target is gone (the reference is broken). */
+    value: string | null;
+    /** The field's cached result (what it last showed). */
+    cached: string;
+    bookmark: string;
+    mode: CrossReferenceMode;
+}
+/** A cross-reference whose target was deleted: its last text, marked in the Broken style. */
+interface BrokenReference {
+    paragraphId: string;
+    offset: number;
+    text: string;
+}
+/** Every cross-reference of the document, in document order. */
+declare function crossReferences(port: ReferencesReader): CrossReference[];
+/**
+ * The cross-references whose cached result is out of date: a clause renumbered, a heading
+ * reworded, or the target gone. The editor paints a field's live value only while its cached
+ * result matches what it computes, so a stale cache shows the OLD number after the document is
+ * reopened (and Word shows the cached result until its fields are updated).
+ */
+declare function staleCrossReferences(port: ReferencesReader): StaleReference[];
+/** The broken cross-references marked in the document, in document order. */
+declare function brokenCrossReferences(port: Pick<ReferencesReader, 'paragraphs'>): BrokenReference[];
+
+/** A document's parts as trees: a live editor's session or a headless view (`openHeadlessDocument`). */
+interface DocumentTrees {
+    part(): {
+        root: unknown;
+    };
+    stylesRoot(): unknown;
+    numberingRoot(): unknown;
+    settingsRoot(): unknown;
+}
+/** A read-only snapshot of a document: its paragraphs, numbering and style names. */
+interface DocumentReader extends ReferencesReader, DocumentNumbering {
+    /** A style's name (`heading 1`) by its id, or the id when the document does not name it. */
+    styleName(styleId: string): string;
+}
+/** Read a document whose trees do not change while the reader is used (a headless view). */
+declare function documentReader(view: DocumentTrees): DocumentReader;
+/** Read a document from its bytes (a collaboration room's `readRoom`). Throws on a bad package. */
+declare function readDocument(bytes: Uint8Array): DocumentReader;
+
+export { BROKEN_CROSS_REFERENCE_STYLE, type BrokenReference, CROSS_REFERENCE_STYLE, type CrossReference, type CrossReferenceMode, type CrossReferenceTarget, DEFINED_TERM_STYLE, type DocField, type DocLink, type DocMark, type DocNote, type DocParagraph, type DocPoint, type DocumentNumbering, type DocumentReader, type DocumentTrees, FIELD_ATOM, type LevelInfo, type LevelOf, type ListItemInfo, type NumberingSource, type OoxmlNodeLike, REF_BOOKMARK_PREFIX, type ReferencesReader, type StaleReference, WATCHED_STYLES, brokenCrossReferences, crossReferences, documentNumbering, documentReader, filterTargets, listTargets, paragraphNumber, readDocument, readParagraphs, staleCrossReferences, styleNames };

package/node_modules/@arbidocs/coedit/dist/commands.d.ts

@@ -0,0 +1,235 @@
+/**
+ * The read side of the Word-editor commands: a document's paragraphs as the commands see them
+ * (text in the engine's offset vocabulary, bookmarks, internal links, fields, note references),
+ * read from the engine's OOXML tree. The same tree comes from a live editor
+ * (`surface.session.part().root`) or from document bytes (`openHeadlessDocument`), so the toolbar
+ * and ARBI's headless tools read a document the same way.
+ */
+/** Character style of an inserted term: a dotted underline, so a defined term reads as one. */
+declare const DEFINED_TERM_STYLE = "DefinedTerm";
+/** Character style of a cross-reference: a muted blue with a dotted underline (Word's name). */
+declare const CROSS_REFERENCE_STYLE = "CrossReference";
+/** Character style of a cross-reference whose target is gone: its last text, flagged. */
+declare const BROKEN_CROSS_REFERENCE_STYLE = "CrossReferenceBroken";
+/** A position: a paragraph (the engine's node id) and a UTF-16 offset into its text. */
+interface DocPoint {
+    paragraphId: string;
+    offset: number;
+}
+/** An internal link in a paragraph. */
+interface DocLink {
+    anchor: string;
+    text: string;
+    /** Where its text starts in the paragraph's text. */
+    offset?: number;
+}
+/** A footnote or endnote reference: one character of the paragraph, as the engine counts it. */
+interface DocNote {
+    offset: number;
+    kind: 'footnote' | 'endnote';
+    /** `w:id` of the note. */
+    id: string;
+}
+/** One paragraph, in document order. */
+interface DocParagraph {
+    id: string;
+    /** `w14:paraId`, the id that is the same in every replica of a collaboration room. */
+    paraId?: string;
+    text: string;
+    /** Styled as a heading (a `Heading n` style or an outline level). */
+    heading: boolean;
+    styleId?: string;
+    /** A paragraph of the body itself, not inside a table. */
+    topLevel: boolean;
+    /** Names of the bookmarks that start in it. */
+    bookmarks: string[];
+    /** Its internal links (`w:hyperlink w:anchor`). */
+    links: DocLink[];
+    /** Its complex fields: where each sits (its one-character offset), its instruction and result. */
+    fields?: DocField[];
+    /** Its runs in a watched character style (a broken cross-reference's mark), with their text. */
+    marks?: DocMark[];
+    /** Its footnote and endnote references. */
+    notes?: DocNote[];
+}
+/** A stretch of a paragraph's text in a watched character style. */
+interface DocMark {
+    styleId: string;
+    offset: number;
+    text: string;
+}
+/** Character styles whose runs a paragraph read reports as marks. */
+declare const WATCHED_STYLES: Set<string>;
+/** A complex field of a paragraph. */
+interface DocField {
+    offset: number;
+    instruction: string;
+    result: string;
+}
+type OoxmlNodeLike = {
+    id: string;
+    kind: string;
+    localName?: string;
+    value?: string;
+    attributes?: readonly {
+        localName: string;
+        value: string;
+    }[];
+    children?: readonly OoxmlNodeLike[];
+};
+/** How a field (or a note reference) counts in a paragraph's text (the engine's model vocabulary). */
+declare const FIELD_ATOM = "\uFFFC";
+/** The paragraphs of a part's body, read from the engine's OOXML tree. */
+declare function readParagraphs(root: OoxmlNodeLike): DocParagraph[];
+/** Style id to style name (`Heading1` → `heading 1`), from a styles part's tree. */
+declare function styleNames(root: OoxmlNodeLike | null | undefined): Map<string, string>;
+
+/**
+ * Cross-reference targets: the document's numbered paragraphs (clauses, sub-clauses, numbered
+ * captions) and its headings, with the number Word's `REF \r` shows for each.
+ *
+ * The number is what the editor computes for a `REF … \r` field — and it has to be exactly that,
+ * because the engine shows a field's live value only while the field's cached result matches what
+ * it computes (otherwise it keeps the cached text for good). So this mirrors the engine: the
+ * paragraph's own list level, preceded by each higher level whose number its level text does not
+ * already show (`%1.%2` already shows level 1; `(%3)` does not show `2.1`), and one trailing
+ * period dropped (`2.` reads `2`).
+ */
+
+/** A paragraph's resolved list numbering (the engine's list item). */
+interface ListItemInfo {
+    numId: string;
+    ilvl: number;
+    markerText: string;
+    numFmt: string;
+}
+/** A list level's definition: its level text (`%1.%2`) and number format. */
+interface LevelInfo {
+    lvlText: string;
+    numFmt: string;
+}
+type LevelOf = (numId: string, ilvl: number) => LevelInfo | null;
+/**
+ * The number `REF \r` shows for a paragraph, or null when it is not numbered. `order` is every
+ * paragraph id in document order (for the markers of the levels above it).
+ */
+declare function paragraphNumber(order: readonly string[], items: ReadonlyMap<string, ListItemInfo>, levelOf: LevelOf, paragraphId: string): string | null;
+/** One place a cross-reference can point at. */
+interface CrossReferenceTarget {
+    paragraphId: string;
+    /** A numbered paragraph (clause, sub-clause, caption) or an unnumbered heading. */
+    kind: 'numbered' | 'heading';
+    /** What `REF \r` shows (`8.2`), or null for an unnumbered heading. */
+    number: string | null;
+    /** The paragraph's list marker as painted (`8.2`, `(a)`), or empty. */
+    marker: string;
+    /** The paragraph's text (without its marker). */
+    text: string;
+    heading: boolean;
+    /** Its list level (0 for a top-level clause), or 0 for a heading. */
+    level: number;
+}
+/** Every numbered paragraph and every heading, in document order. */
+declare function listTargets(paragraphs: readonly DocParagraph[], items: ReadonlyMap<string, ListItemInfo>, levelOf: LevelOf): CrossReferenceTarget[];
+/** Targets whose number or text contains the query (case-insensitive). */
+declare function filterTargets(targets: readonly CrossReferenceTarget[], query: string): CrossReferenceTarget[];
+/** What the engine's numbering needs of a document: its parts' trees. */
+interface NumberingSource {
+    /** The main document part's root. */
+    root(): OoxmlNodeLike;
+    stylesRoot(): unknown;
+    numberingRoot(): unknown;
+    settingsRoot(): unknown;
+}
+/** A document's list numbering as the engine resolves it. */
+interface DocumentNumbering {
+    /** Each numbered paragraph's list item, by paragraph (node) id. */
+    listItems(): ReadonlyMap<string, ListItemInfo>;
+    levelOf: LevelOf;
+}
+/**
+ * The numbering of a document, as the editor paints it: from a live editor's session or from a
+ * headless document view alike.
+ */
+declare function documentNumbering(source: NumberingSource): DocumentNumbering;
+
+/**
+ * The cross-references of a document (`REF` fields to `_Ref` bookmarks), each with what it shows
+ * and what its target now is: current, stale (a clause renumbered, a heading reworded) or broken
+ * (the target is gone).
+ */
+
+/** Prefix of Word's hidden cross-reference bookmarks. */
+declare const REF_BOOKMARK_PREFIX = "_Ref";
+type CrossReferenceMode = 'number' | 'text';
+/** What reading cross-references needs of a document. */
+interface ReferencesReader {
+    paragraphs(): DocParagraph[];
+    /** Each numbered paragraph's list item, by paragraph id. */
+    listItems(): ReadonlyMap<string, ListItemInfo>;
+    levelOf: LevelOf;
+}
+/** One `REF` field to a `_Ref` bookmark. */
+interface CrossReference {
+    paragraphId: string;
+    offset: number;
+    instruction: string;
+    bookmark: string;
+    mode: CrossReferenceMode;
+    /** The field's cached result (what it shows). */
+    cached: string;
+    /** The paragraph the bookmark is in, or null when it is gone (the reference is broken). */
+    target: string | null;
+    /** What the reference should show now, or null when that cannot be computed. */
+    value: string | null;
+}
+/** A `REF` field whose cached result no longer says what its target now is. */
+interface StaleReference {
+    paragraphId: string;
+    offset: number;
+    instruction: string;
+    /** The current value, or null when the target is gone (the reference is broken). */
+    value: string | null;
+    /** The field's cached result (what it last showed). */
+    cached: string;
+    bookmark: string;
+    mode: CrossReferenceMode;
+}
+/** A cross-reference whose target was deleted: its last text, marked in the Broken style. */
+interface BrokenReference {
+    paragraphId: string;
+    offset: number;
+    text: string;
+}
+/** Every cross-reference of the document, in document order. */
+declare function crossReferences(port: ReferencesReader): CrossReference[];
+/**
+ * The cross-references whose cached result is out of date: a clause renumbered, a heading
+ * reworded, or the target gone. The editor paints a field's live value only while its cached
+ * result matches what it computes, so a stale cache shows the OLD number after the document is
+ * reopened (and Word shows the cached result until its fields are updated).
+ */
+declare function staleCrossReferences(port: ReferencesReader): StaleReference[];
+/** The broken cross-references marked in the document, in document order. */
+declare function brokenCrossReferences(port: Pick<ReferencesReader, 'paragraphs'>): BrokenReference[];
+
+/** A document's parts as trees: a live editor's session or a headless view (`openHeadlessDocument`). */
+interface DocumentTrees {
+    part(): {
+        root: unknown;
+    };
+    stylesRoot(): unknown;
+    numberingRoot(): unknown;
+    settingsRoot(): unknown;
+}
+/** A read-only snapshot of a document: its paragraphs, numbering and style names. */
+interface DocumentReader extends ReferencesReader, DocumentNumbering {
+    /** A style's name (`heading 1`) by its id, or the id when the document does not name it. */
+    styleName(styleId: string): string;
+}
+/** Read a document whose trees do not change while the reader is used (a headless view). */
+declare function documentReader(view: DocumentTrees): DocumentReader;
+/** Read a document from its bytes (a collaboration room's `readRoom`). Throws on a bad package. */
+declare function readDocument(bytes: Uint8Array): DocumentReader;
+
+export { BROKEN_CROSS_REFERENCE_STYLE, type BrokenReference, CROSS_REFERENCE_STYLE, type CrossReference, type CrossReferenceMode, type CrossReferenceTarget, DEFINED_TERM_STYLE, type DocField, type DocLink, type DocMark, type DocNote, type DocParagraph, type DocPoint, type DocumentNumbering, type DocumentReader, type DocumentTrees, FIELD_ATOM, type LevelInfo, type LevelOf, type ListItemInfo, type NumberingSource, type OoxmlNodeLike, REF_BOOKMARK_PREFIX, type ReferencesReader, type StaleReference, WATCHED_STYLES, brokenCrossReferences, crossReferences, documentNumbering, documentReader, filterTargets, listTargets, paragraphNumber, readDocument, readParagraphs, staleCrossReferences, styleNames };