@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/model/content/List.d.mts

@@ -0,0 +1,253 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { ListDefinition, LevelDefinition } from '../listnumbering/definitions.mjs';
+import type { Emulator } from '../listnumbering/Emulator.mjs';
+import { Font } from './Font.mjs';
+import type { Body } from './Body.mjs';
+import type { Paragraph } from './Paragraph.mjs';
+import type { AlignmentOrUnknown } from './Paragraph.mjs';
+/** Office JS `Word.ListLevelType`: what a level paints in front of its paragraphs. */
+export type ListLevelType = 'Bullet' | 'Number' | 'Picture';
+/** Office JS `Word.ListNumbering`: the number formats `setLevelNumbering` takes. */
+export type ListNumbering = 'None' | 'Arabic' | 'UpperRoman' | 'LowerRoman' | 'UpperLetter' | 'LowerLetter';
+/** Office JS `Word.ListBullet`: the bullets `setLevelBullet` takes. */
+export type ListBullet = 'Custom' | 'Solid' | 'Hollow' | 'Square' | 'Diamonds' | 'Arrow' | 'Checkmark';
+/** What `Paragraph.startNewList()` builds (extension: Office JS's takes no options). */
+export interface StartListOptions {
+    /** docx4j's default **bullet** set rather than its decimal set (`w:abstractNum` 0, not 1). */
+    bullet?: boolean;
+    /** The level to put this paragraph at; 0 by default. */
+    level?: number;
+}
+/** One paragraph's place in its list, as one walk of the story answers it (`Body.listLabels`). */
+export interface ListLabel {
+    /** The label Word paints: the level's `w:lvlText` with the counters filled in, or the bullet. */
+    listString: string;
+    /** The `w:ilvl` the paragraph counts at, style-contributed levels included. */
+    level: number;
+    /** The `w:numId` it counts in. */
+    numId: string;
+    /** Its 0-based index among the items of this list and level since the level last restarted. */
+    siblingIndex: number;
+    /** Whether the level's `w:numFmt` is `bullet`. */
+    isBullet: boolean;
+}
+/**
+ * The package's numbering emulator, or undefined where the document has no lists (or nothing
+ * has read the numbering part: `await pkg.getBody()` builds the resolver, which reads it).
+ */
+export declare function numberingEmulatorOf(body: Body): Emulator | undefined;
+/**
+ * Every numbered paragraph of this body's **story**, with the label and the counters, in one
+ * walk. A header or footer that has not been unmarshalled contributes nothing to the count,
+ * since it cannot be read synchronously: `await part.getBody()` on each first where a footer's
+ * numbers must continue the headers' (the story rule).
+ */
+export declare function listLabelsOf(body: Body): Map<wml.P, ListLabel>;
+/**
+ * Nothing matched, as Office JS's `ItemNotFound` says it: the same `code` as the shim's
+ * `ItemNotFoundError`, so add-in code branching on `error.code` behaves the same.
+ */
+declare class ItemNotFound extends Error {
+    readonly code = "ItemNotFound";
+    constructor(message: string);
+}
+export { ItemNotFound as ListItemNotFoundError };
+/**
+ * A subset of Office JS `Word.List` over one `w:num` and the `w:abstractNum` it names. A light
+ * view: it holds the `w:numId` and the body it was found through, and resolves both elements
+ * through the numbering part's definitions on every call.
+ *
+ * Every `setLevel*` method writes on the **abstract** definition, copying it first where
+ * another `w:num` shares it ({@link separate}), so that the change stays local to this list;
+ * each then refreshes the package's resolver, which rebuilds the numbering definitions.
+ */
+export declare class List {
+    /** `w:numId`, as a string (docx4j's key; {@link id} is Office JS's number). */
+    readonly numId: string;
+    /** The body this list was found through: where {@link paragraphs} looks. */
+    readonly body: Body;
+    constructor(
+    /** `w:numId`, as a string (docx4j's key; {@link id} is Office JS's number). */
+    numId: string, 
+    /** The body this list was found through: where {@link paragraphs} looks. */
+    body: Body);
+    /** Office JS `list.id`: the `w:numId`. */
+    get id(): number;
+    /** The definitions this list is read from; throws where the numbering part has not been read. */
+    private get definitions();
+    /** The `w:num`'s definition (docx4j `ListNumberingDefinition`). */
+    get definition(): ListDefinition;
+    /** The `w:num` (extension: the tree). */
+    get element(): wml.Numbering.Num;
+    /** The `w:abstractNum` this list resolves to (extension: the tree). */
+    get abstractElement(): wml.Numbering.AbstractNum | undefined;
+    /** The level definition (the abstract level with this `w:num`'s override over it), or undefined. */
+    level(level: number): LevelDefinition | undefined;
+    /** Office JS `list.levelExistences`: whether each of the nine levels is defined. */
+    get levelExistences(): boolean[];
+    /** Whether the level is defined (extension; Office JS has {@link levelExistences}). */
+    levelExists(level: number): boolean;
+    /**
+     * Office JS `list.levelTypes`: `Bullet`, `Number` or `Picture` for each of the nine levels,
+     * from the level's `w:numFmt` and its `w:lvlPicBulletId`. A level that is not defined reads
+     * `Number`, as Office JS reports for a level with no format of its own.
+     */
+    get levelTypes(): ListLevelType[];
+    /** Office JS `list.getLevelString(level)`: the level's `w:lvlText` ('%1.', '(%2)', a bullet). */
+    getLevelString(level: number): string;
+    /**
+     * Office JS `list.getLevelFont(level)`: the `Font` the level's label is drawn with, over the
+     * level's `w:rPr`.
+     *
+     * **It is a writable view**, and Office JS pairs it with `resetLevelFont`, so it
+     * {@link separate}s first: the numbering part becomes live and a shared abstract definition
+     * is copied, exactly as the `setLevel*` methods do. A read that must not cost the part its
+     * byte-for-byte round trip is `list.level(n).labelRPr` (CR-002 section 17).
+     */
+    getLevelFont(level: number): Font;
+    /** Office JS `list.getLevelParagraphs(level)`: this body's paragraphs at that level of this list. */
+    getLevelParagraphs(level: number): Paragraph[];
+    /**
+     * Office JS `list.paragraphs`: every paragraph of this body whose effective `w:numPr` names
+     * this list, in document order (a style-contributed `w:numPr` counts).
+     */
+    get paragraphs(): Paragraph[];
+    /**
+     * Office JS `list.insertParagraph(text, location)`: a new paragraph of this list before its
+     * first item or after its last, at that item's level.
+     */
+    insertParagraph(text: string, location: 'Start' | 'End'): Paragraph;
+    /**
+     * Office JS `list.setLevelNumbering(level, listNumbering, formatString)`: the level's
+     * `w:numFmt` and, from `formatString`, its `w:lvlText` - each number in the array is a
+     * 0-based level whose counter goes there (`[0, '.', 1]` is `'%1.%2'`), each string a literal.
+     * Without one the level numbers itself and takes a trailing full stop (`'%<n>.'`).
+     */
+    setLevelNumbering(level: number, listNumbering: ListNumbering, formatString?: (string | number)[]): void;
+    /**
+     * Office JS `list.setLevelBullet(level, listBullet, charCode, fontName)`: the level's
+     * `w:numFmt` becomes `bullet` and its `w:lvlText` the bullet character, with the font in the
+     * level's `w:rPr/w:rFonts`. `Custom` takes `charCode` and `fontName`; the other six are the
+     * characters and faces Word's bullet library uses.
+     */
+    setLevelBullet(level: number, listBullet: ListBullet, charCode?: number, fontName?: string): void;
+    /**
+     * Office JS `list.setLevelIndents(level, textIndent, bulletNumberPictureIndent)`, both in
+     * points: the level's `w:ind/@w:left` is where the text sits and the label's position is the
+     * hanging indent from it (or `w:firstLine` where the label sits to the right of the text).
+     */
+    setLevelIndents(level: number, textIndent: number, bulletNumberPictureIndent: number): void;
+    /** Office JS `list.setLevelAlignment(level, alignment)`: the level's `w:lvlJc`. */
+    setLevelAlignment(level: number, alignment: AlignmentOrUnknown): void;
+    /**
+     * Office JS `list.setLevelStartingNumber(level, startingNumber)`: the level's `w:start`. A
+     * `w:startOverride` this `w:num` carries for the level would still win the first use, so it
+     * is removed with it.
+     */
+    setLevelStartingNumber(level: number, startingNumber: number): void;
+    /**
+     * A new `w:num` over this list's `w:abstractNum` with a `w:startOverride` on level 0, which
+     * is how Word restarts a list: the counters are shared by abstract definition, and the
+     * override is spent on the new `w:num`'s first use in a story (CR-001 section 15.2). Attach
+     * the paragraphs that are to start again to the list it returns.
+     *
+     * Extension name (Office JS has no restart verb); `Paragraph.restartList()` is the sugar.
+     */
+    restart(): List;
+    /**
+     * Gives this list a `w:abstractNum` of its own where another `w:num` shares the one it names
+     * (CR-002 section 3.9), so that a change to its levels stays local to it. The numbering part
+     * becomes live either way; the `setLevel*` methods call it for you.
+     */
+    separate(): void;
+    /** The numbering part's live tree; the first write promotes the tree the definitions hold. */
+    private live;
+    /**
+     * The `w:lvl` a write goes to: this list's own abstract definition's, created where the
+     * definition has no level for it. A `w:lvlOverride/w:lvl` this `w:num` carries for the level
+     * would mask the abstract one, so it goes (the `w:startOverride` beside it stays).
+     */
+    private writableLvl;
+    /** The numbering tree changed: the resolver (and with it the definitions) is rebuilt. */
+    private written;
+}
+/**
+ * A subset of Office JS `Word.ListItem` over one paragraph's place in its list. A view: the
+ * paragraph is the state.
+ */
+export declare class ListItem {
+    /** The paragraph this is the list item of (Office JS: `paragraph.listItem`). */
+    readonly paragraph: Paragraph;
+    constructor(
+    /** The paragraph this is the list item of (Office JS: `paragraph.listItem`). */
+    paragraph: Paragraph);
+    /** Where this paragraph's numbering resolves to; throws when it is not a list item any more. */
+    private get ref();
+    /** The list this item is in. */
+    get list(): List;
+    /**
+     * Office JS `listItem.level`: the `w:ilvl` the paragraph counts at, a style-contributed level
+     * included. Setting it writes the paragraph's own `w:numPr/w:ilvl` (with the `w:numId` beside
+     * it where the list came from the style), through the accessor that records `w:pPrChange`
+     * while the package tracks changes.
+     */
+    get level(): number;
+    set level(value: number);
+    /**
+     * Office JS `listItem.listString`: the label Word paints in front of the paragraph.
+     *
+     * It is counted by walking the paragraph's **story** from its start in document order
+     * (CR-001 section 15.2), so it costs one walk of the story per read; `Body.listLabels()`
+     * answers for every paragraph of the story in one walk.
+     */
+    get listString(): string;
+    /**
+     * Office JS `listItem.siblingIndex`: the 0-based index of this item among the items of the
+     * same list and level, counted from where the level last restarted. The same walk as
+     * {@link listString}.
+     */
+    get siblingIndex(): number;
+    /**
+     * Office JS `listItem.getAncestor(parentOnly)`: the nearest preceding paragraph of this list
+     * at a shallower level - the parent when `parentOnly` is true, which throws when the nearest
+     * one is not exactly one level up. Throws `ItemNotFound` when there is no ancestor.
+     */
+    getAncestor(parentOnly?: boolean): Paragraph;
+    /**
+     * Office JS `listItem.getDescendants(directChildrenOnly)`: the paragraphs of this list which
+     * follow this one at a deeper level, up to the next one at this level or shallower; only the
+     * ones one level down when `directChildrenOnly` is true.
+     */
+    getDescendants(directChildrenOnly?: boolean): Paragraph[];
+}
+/** The effective `w:ilvl` of a paragraph, or undefined when it is not a list item. */
+export declare function levelOf(paragraph: Paragraph): number | undefined;
+/** Office JS `paragraph.isListItem`: docx4j's `Emulator.numRefFor` answers it. */
+export declare function isListItem(paragraph: Paragraph): boolean;
+/** Office JS `paragraph.listItem`; throws `ItemNotFound` when the paragraph is not one. */
+export declare function listItemOf(paragraph: Paragraph): ListItem;
+/** Office JS `paragraph.listItemOrNullObject`. */
+export declare function listItemOrNullObjectOf(paragraph: Paragraph): ListItem;
+/** Office JS `paragraph.list`; throws `ItemNotFound` when the paragraph is not a list item. */
+export declare function listOf(paragraph: Paragraph): List;
+/** Office JS `paragraph.listOrNullObject`. */
+export declare function listOrNullObjectOf(paragraph: Paragraph): List;
+/** Office JS `body.lists`: every `w:num` a paragraph of this body names, in order of first use. */
+export declare function listsOf(body: Body): List[];
+/** Office JS `paragraph.attachToList(listId, level)`: the paragraph's own `w:numPr`. */
+export declare function attachToList(paragraph: Paragraph, listId: number | string, level?: number): List;
+/**
+ * Office JS `paragraph.detachFromList()`: the paragraph's own `w:numPr` goes. Where its style
+ * still numbers it, a `w:numPr` with `w:numId` 0 takes its place, which is how Word switches an
+ * inherited list off (ECMA-376 17.9.18, and what `Emulator.resolve` reads).
+ */
+export declare function detachFromList(paragraph: Paragraph): void;
+/**
+ * Office JS `paragraph.startNewList()`: a `w:abstractNum` copied from docx4j's default
+ * definitions (its `numbering.xml` resource: `w:abstractNum` 1 is Word's decimal set and 0 its
+ * bullet set), a `w:num` for it, and the paragraph attached to that list.
+ *
+ * Asynchronous where Office JS's is synchronous: the default definitions are XML which has to
+ * be unmarshalled, and a document with no numbering part gets one here (CR-002 section 17).
+ */
+export declare function startNewList(paragraph: Paragraph, options?: StartListOptions): Promise<List>;