@arbidocs/coedit 0.4.111 → 0.4.113

package/dist/port-ip7WByvH.d.cts

@@ -0,0 +1,188 @@
+/**
+ * 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 few things the defined-term and cross-reference commands need from a document, behind an
+ * interface: a live editor (arbi-blocks' `editorPort`), a collaboration room (`roomCommandsPort` in
+ * `@arbidocs/coedit/server`), or the in-memory model the tests use.
+ */
+
+interface DefinitionsPort {
+    /** Every body paragraph, in document order (table cells included, `topLevel: false`). */
+    paragraphs(): DocParagraph[];
+    /** The caret, or `null` when the selection is a range or there is none. */
+    caret(): DocPoint | null;
+    setCaret(point: DocPoint): void;
+    /** Delete everything between two points (across paragraphs: the marks between them go too). */
+    deleteRange(from: DocPoint, to: DocPoint): void;
+    /**
+     * Paste paragraph XML at the caret. `covered`: the fragment ends with a whole paragraph, so at
+     * the start of a paragraph it lands as paragraphs before it. Otherwise it runs inline.
+     */
+    paste(body: string, text: string, covered: boolean, relationships?: string): boolean;
+    /** Split the caret's paragraph (Enter), the caret moving into the new one. */
+    splitParagraph(): void;
+    /** Type plain text at the caret. */
+    typeText(text: string): void;
+}
+interface ReferencesPort extends DefinitionsPort {
+    /** Each numbered paragraph's list item, by paragraph id. */
+    listItems(): ReadonlyMap<string, ListItemInfo>;
+    levelOf: LevelOf;
+    /** The paragraph's runs as WordprocessingML, or null when it holds more than plain runs. */
+    runsXml(paragraphId: string): string | null;
+}
+
+export { BROKEN_CROSS_REFERENCE_STYLE as B, CROSS_REFERENCE_STYLE as C, DEFINED_TERM_STYLE as D, FIELD_ATOM as F, type LevelInfo as L, type NumberingSource as N, type OoxmlNodeLike as O, type ReferencesPort as R, WATCHED_STYLES as W, type CrossReferenceTarget as a, type DefinitionsPort as b, type DocField as c, type DocLink as d, type DocMark as e, type DocNote as f, type DocParagraph as g, type DocPoint as h, type DocumentNumbering as i, type LevelOf as j, type ListItemInfo as k, documentNumbering as l, filterTargets as m, listTargets as n, paragraphNumber as p, readParagraphs as r, styleNames as s };

package/dist/port-ip7WByvH.d.ts

@@ -0,0 +1,188 @@
+/**
+ * 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 few things the defined-term and cross-reference commands need from a document, behind an
+ * interface: a live editor (arbi-blocks' `editorPort`), a collaboration room (`roomCommandsPort` in
+ * `@arbidocs/coedit/server`), or the in-memory model the tests use.
+ */
+
+interface DefinitionsPort {
+    /** Every body paragraph, in document order (table cells included, `topLevel: false`). */
+    paragraphs(): DocParagraph[];
+    /** The caret, or `null` when the selection is a range or there is none. */
+    caret(): DocPoint | null;
+    setCaret(point: DocPoint): void;
+    /** Delete everything between two points (across paragraphs: the marks between them go too). */
+    deleteRange(from: DocPoint, to: DocPoint): void;
+    /**
+     * Paste paragraph XML at the caret. `covered`: the fragment ends with a whole paragraph, so at
+     * the start of a paragraph it lands as paragraphs before it. Otherwise it runs inline.
+     */
+    paste(body: string, text: string, covered: boolean, relationships?: string): boolean;
+    /** Split the caret's paragraph (Enter), the caret moving into the new one. */
+    splitParagraph(): void;
+    /** Type plain text at the caret. */
+    typeText(text: string): void;
+}
+interface ReferencesPort extends DefinitionsPort {
+    /** Each numbered paragraph's list item, by paragraph id. */
+    listItems(): ReadonlyMap<string, ListItemInfo>;
+    levelOf: LevelOf;
+    /** The paragraph's runs as WordprocessingML, or null when it holds more than plain runs. */
+    runsXml(paragraphId: string): string | null;
+}
+
+export { BROKEN_CROSS_REFERENCE_STYLE as B, CROSS_REFERENCE_STYLE as C, DEFINED_TERM_STYLE as D, FIELD_ATOM as F, type LevelInfo as L, type NumberingSource as N, type OoxmlNodeLike as O, type ReferencesPort as R, WATCHED_STYLES as W, type CrossReferenceTarget as a, type DefinitionsPort as b, type DocField as c, type DocLink as d, type DocMark as e, type DocNote as f, type DocParagraph as g, type DocPoint as h, type DocumentNumbering as i, type LevelOf as j, type ListItemInfo as k, documentNumbering as l, filterTargets as m, listTargets as n, paragraphNumber as p, readParagraphs as r, styleNames as s };