@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/office-js/errors.mjs

@@ -0,0 +1,39 @@
+// The errors the Word shim throws (CR-002 section 3.10). Office JS raises OfficeExtension.Error
+// with a `code` from Word.ErrorCodes; these carry the same codes so that add-in code which
+// branches on `error.code` behaves the same here.
+/**
+ * A member of the Word API that this package does not implement. The message names the class and
+ * the member, so an add-in's unsupported call fails at the call with something actionable:
+ * `Word.Paragraph.getNextOrNullObject is not supported by @docx4j/core-ts`.
+ */
+export class NotSupportedError extends Error {
+    constructor(
+    /** The Word class, as Office JS names it ('Paragraph', 'Body', 'RequestContext'). */
+    className, 
+    /** The member that was read, written or called. */
+    member, detail) {
+        super(`Word.${className}.${member} is not supported by @docx4j/core-ts${detail ? `: ${detail}` : ''}`);
+        this.className = className;
+        this.member = member;
+        /** Word.ErrorCodes.notImplemented. */
+        this.code = 'NotImplemented';
+        this.name = 'NotSupportedError';
+    }
+}
+/** Nothing matched: `getFirst()` on an empty collection, or a member of a null object. */
+export class ItemNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        /** Word.ErrorCodes.itemNotFound. */
+        this.code = 'ItemNotFound';
+        this.name = 'ItemNotFoundError';
+    }
+}
+/** A result read before `context.sync()` resolved it (Office JS: ValueNotLoaded). */
+export class ValueNotLoadedError extends Error {
+    constructor(message = 'The value is not loaded yet; await context.sync() first') {
+        super(message);
+        this.code = 'ValueNotLoaded';
+        this.name = 'ValueNotLoadedError';
+    }
+}

package/dist/office-js/extras.d.mts

@@ -0,0 +1,5 @@
+/** A member the shim adds: called with the view and the call's arguments. */
+export type ExtraMember = (target: never, ...args: never[]) => unknown;
+/** By Word class name, then member name. */
+export type ExtraMembers = Readonly<Record<string, Readonly<Record<string, ExtraMember>>>>;
+export declare const EXTRA_MEMBERS: ExtraMembers;

package/dist/office-js/extras.mjs

@@ -0,0 +1,29 @@
+// Members the shim adds over a view, per Word class (CR-002 section 3.10). The views keep to what
+// the content API promises (section 3.12), so `getOoxml()`, which needs the package, lives here
+// rather than on `Body`; the proxy offers these only when the view itself has no such member, so
+// a later phase that implements one on the view wins without a change here.
+import { xmlOfRange } from './fragment.mjs';
+/**
+ * `body.getOoxml()` is Office JS's whole-document flat OPC package, which is exactly
+ * `OpcPackage.saveFlatOpc()`; a body with no package (a fragment) gives its part's XML.
+ */
+function bodyOoxml(body) {
+    const pkg = body.package_;
+    if (pkg)
+        return pkg.saveFlatOpc();
+    return body.getXml();
+}
+export const EXTRA_MEMBERS = {
+    Body: {
+        getOoxml: (body) => bodyOoxml(body),
+    },
+    Paragraph: {
+        // Word wraps a paragraph in a pkg:package with the styles it needs; that is CR-002 phase C's
+        // insertOoxml work, so this is the bare `w:p` fragment (which `insertXml` takes back).
+        getOoxml: (paragraph) => paragraph.getXml(),
+    },
+    Range: {
+        getOoxml: (range) => xmlOfRange(range),
+        getXml: (range) => xmlOfRange(range),
+    },
+};

package/dist/office-js/fragment.d.mts

@@ -0,0 +1,10 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { Range } from '../model/content/Range.mjs';
+import type { Element } from '../model/content/tree.mjs';
+/**
+ * A detached `w:p` holding exactly the range's text, with the runs and their formatting. The
+ * paragraph is copied first, so the document is untouched.
+ */
+export declare function paragraphElementOfRange(range: Range): Element<wml.P>;
+/** The range as a `w:p` fragment (extension; Office JS wraps a range in a pkg:package). */
+export declare function xmlOfRange(range: Range): Promise<string>;

package/dist/office-js/fragment.mjs

@@ -0,0 +1,23 @@
+// Marshalling a view back to a fragment: what `getOoxml()` and `toApiScript`'s fallback need.
+// A `w:p` copy holding only a range's text is the one piece the views do not offer (Range has no
+// element of its own: it is a span of the paragraph's text).
+import { deepCopy, marshalString } from '@docx4j/generated-objects-ts';
+import { Paragraph } from '../model/content/Paragraph.mjs';
+/**
+ * A detached `w:p` holding exactly the range's text, with the runs and their formatting. The
+ * paragraph is copied first, so the document is untouched.
+ */
+export function paragraphElementOfRange(range) {
+    const copy = deepCopy(range.paragraph.element);
+    const view = new Paragraph(copy, [copy], range.paragraph.parentBody);
+    const length = view.text.length;
+    if (range.end < length)
+        view.splice(range.end, length, '');
+    if (range.start > 0)
+        view.splice(0, range.start, '');
+    return copy;
+}
+/** The range as a `w:p` fragment (extension; Office JS wraps a range in a pkg:package). */
+export function xmlOfRange(range) {
+    return marshalString(paragraphElementOfRange(range));
+}

package/dist/office-js/index.d.mts

@@ -0,0 +1,183 @@
+import { run, RequestContext, type RunOptions, type TrackedObjects } from './run.mjs';
+import { Document, DocumentProperties } from './document.mjs';
+import { supported, SUBSET_MEMBERS } from './supported.mjs';
+import { ClientResult, unwrap, nullObject, Wrapper, type Collection, type PendingSink } from './proxy.mjs';
+import { NotSupportedError, ItemNotFoundError, ValueNotLoadedError } from './errors.mjs';
+import { toApiScript, type ApiScriptOptions, type ApiScriptTarget } from './toApiScript.mjs';
+import { InsertLocation, Alignment, UnderlineType, ChangeTrackingMode, BreakType, ContentControlType, Style, ErrorCodes, SearchOptions, ListLevelType, ListNumbering, ListBullet, type InsertLocationValue, type ChangeTrackingModeValue, type BreakTypeValue, type ContentControlTypeValue, type StyleValue, type AlignmentValue, type UnderlineTypeValue, type ListLevelTypeValue, type ListNumberingValue, type ListBulletValue } from './enums.mjs';
+export { run, RequestContext, Document, DocumentProperties, ClientResult, unwrap, nullObject, Wrapper, toApiScript, supported, SUBSET_MEMBERS };
+export { NotSupportedError, ItemNotFoundError, ValueNotLoadedError };
+export { InsertLocation, Alignment, UnderlineType, ChangeTrackingMode, BreakType, ContentControlType, Style, ErrorCodes, SearchOptions };
+export { ListLevelType, ListNumbering, ListBullet };
+export type { RunOptions, TrackedObjects, Collection, PendingSink, ApiScriptOptions, ApiScriptTarget, InsertLocationValue, ChangeTrackingModeValue, BreakTypeValue, ContentControlTypeValue, StyleValue, AlignmentValue, UnderlineTypeValue, ListLevelTypeValue, ListNumberingValue, ListBulletValue, };
+/**
+ * The `Word` namespace an add-in script expects: `Word.run`, the enums, and `Word.supported`, the
+ * `Class.member` strings this package implements (so a tool can check a script before running it).
+ * `Word.run` takes the package first, since there is no host document.
+ */
+export declare const Word: Readonly<{
+    run: typeof run;
+    supported: ReadonlySet<string>;
+    InsertLocation: Readonly<{
+        readonly before: "Before";
+        readonly after: "After";
+        readonly start: "Start";
+        readonly end: "End";
+        readonly replace: "Replace";
+    }>;
+    Alignment: Readonly<{
+        readonly unknown: "Unknown";
+        readonly left: "Left";
+        readonly centered: "Centered";
+        readonly right: "Right";
+        readonly justified: "Justified";
+    }>;
+    UnderlineType: Readonly<{
+        readonly mixed: "Mixed";
+        readonly none: "None";
+        readonly single: "Single";
+        readonly word: "Word";
+        readonly double: "Double";
+        readonly thick: "Thick";
+        readonly dotted: "Dotted";
+        readonly dottedHeavy: "DottedHeavy";
+        readonly dashLine: "DashLine";
+        readonly dashLineHeavy: "DashLineHeavy";
+        readonly dashLineLong: "DashLineLong";
+        readonly dashLineLongHeavy: "DashLineLongHeavy";
+        readonly dotDashLine: "DotDashLine";
+        readonly dotDashLineHeavy: "DotDashLineHeavy";
+        readonly twoDotDashLine: "TwoDotDashLine";
+        readonly twoDotDashLineHeavy: "TwoDotDashLineHeavy";
+        readonly wave: "Wave";
+        readonly waveHeavy: "WaveHeavy";
+        readonly waveDouble: "WaveDouble";
+    }>;
+    ChangeTrackingMode: Readonly<{
+        readonly off: "Off";
+        readonly trackAll: "TrackAll";
+        readonly trackMineOnly: "TrackMineOnly";
+    }>;
+    BreakType: Readonly<{
+        readonly page: "Page";
+        readonly next: "Next";
+        readonly sectionNext: "SectionNext";
+        readonly sectionContinuous: "SectionContinuous";
+        readonly sectionEven: "SectionEven";
+        readonly sectionOdd: "SectionOdd";
+        readonly line: "Line";
+    }>;
+    ContentControlType: Readonly<{
+        readonly unknown: "Unknown";
+        readonly richText: "RichText";
+        readonly plainText: "PlainText";
+        readonly picture: "Picture";
+        readonly datePicker: "DatePicker";
+        readonly comboBox: "ComboBox";
+        readonly dropDownList: "DropDownList";
+        readonly checkBox: "CheckBox";
+        readonly repeatingSection: "RepeatingSection";
+        readonly repeatingSectionItem: "RepeatingSectionItem";
+        readonly group: "Group";
+        readonly buildingBlockGallery: "BuildingBlockGallery";
+        readonly citation: "Citation";
+        readonly bibliography: "Bibliography";
+        readonly equation: "Equation";
+    }>;
+    ListLevelType: Readonly<{
+        readonly bullet: "Bullet";
+        readonly number: "Number";
+        readonly picture: "Picture";
+    }>;
+    ListNumbering: Readonly<{
+        readonly none: "None";
+        readonly arabic: "Arabic";
+        readonly upperRoman: "UpperRoman";
+        readonly lowerRoman: "LowerRoman";
+        readonly upperLetter: "UpperLetter";
+        readonly lowerLetter: "LowerLetter";
+    }>;
+    ListBullet: Readonly<{
+        readonly custom: "Custom";
+        readonly solid: "Solid";
+        readonly hollow: "Hollow";
+        readonly square: "Square";
+        readonly diamonds: "Diamonds";
+        readonly arrow: "Arrow";
+        readonly checkmark: "Checkmark";
+    }>;
+    Style: Readonly<{
+        readonly other: "Other";
+        readonly normal: "Normal";
+        readonly heading1: "Heading1";
+        readonly heading2: "Heading2";
+        readonly heading3: "Heading3";
+        readonly heading4: "Heading4";
+        readonly heading5: "Heading5";
+        readonly heading6: "Heading6";
+        readonly heading7: "Heading7";
+        readonly heading8: "Heading8";
+        readonly heading9: "Heading9";
+        readonly toc1: "Toc1";
+        readonly toc2: "Toc2";
+        readonly toc3: "Toc3";
+        readonly toc4: "Toc4";
+        readonly toc5: "Toc5";
+        readonly toc6: "Toc6";
+        readonly toc7: "Toc7";
+        readonly toc8: "Toc8";
+        readonly toc9: "Toc9";
+        readonly footnoteText: "FootnoteText";
+        readonly header: "Header";
+        readonly footer: "Footer";
+        readonly caption: "Caption";
+        readonly footnoteReference: "FootnoteReference";
+        readonly endnoteReference: "EndnoteReference";
+        readonly endnoteText: "EndnoteText";
+        readonly title: "Title";
+        readonly subtitle: "Subtitle";
+        readonly hyperlink: "Hyperlink";
+        readonly strong: "Strong";
+        readonly emphasis: "Emphasis";
+        readonly noSpacing: "NoSpacing";
+        readonly listParagraph: "ListParagraph";
+        readonly quote: "Quote";
+        readonly intenseQuote: "IntenseQuote";
+        readonly subtleEmphasis: "SubtleEmphasis";
+        readonly intenseEmphasis: "IntenseEmphasis";
+        readonly subtleReference: "SubtleReference";
+        readonly intenseReference: "IntenseReference";
+        readonly bookTitle: "BookTitle";
+        readonly bibliography: "Bibliography";
+        readonly tocHeading: "TocHeading";
+        readonly tableGrid: "TableGrid";
+        readonly plainTable1: "PlainTable1";
+        readonly plainTable2: "PlainTable2";
+        readonly plainTable3: "PlainTable3";
+        readonly plainTable4: "PlainTable4";
+        readonly plainTable5: "PlainTable5";
+        readonly gridTable1Light: "GridTable1Light";
+        readonly listTable1Light: "ListTable1Light";
+    }>;
+    ErrorCodes: Readonly<{
+        readonly accessDenied: "AccessDenied";
+        readonly generalException: "GeneralException";
+        readonly invalidArgument: "InvalidArgument";
+        readonly itemNotFound: "ItemNotFound";
+        readonly notAllowed: "NotAllowed";
+        readonly notImplemented: "NotImplemented";
+        readonly searchDialogIsOpen: "SearchDialogIsOpen";
+        readonly searchStringInvalidOrTooLong: "SearchStringInvalidOrTooLong";
+    }>;
+    SearchOptions: Readonly<{
+        newObject(): SearchOptions;
+    }>;
+    ClientResult: typeof ClientResult;
+    RequestContext: typeof RequestContext;
+    Document: typeof Document;
+    DocumentProperties: typeof DocumentProperties;
+    NotSupportedError: typeof NotSupportedError;
+    ItemNotFoundError: typeof ItemNotFoundError;
+    ValueNotLoadedError: typeof ValueNotLoadedError;
+    unwrap: typeof unwrap;
+}>;

package/dist/office-js/index.mjs

@@ -0,0 +1,54 @@
+// `@docx4j/core-ts/office-js`: the `Word` shim of CR-002 section 3.10.
+//
+// The content API is a structural subset of Office JS's Word types (section 3.4); this makes that
+// executable, so an add-in's `Word.run` callback runs against a package here, in Node or in a
+// browser, with the saved docx as the assertion. It is deliberately not part of the root export:
+// an add-in bundle that wants only the content API never pulls the proxies in.
+//
+//   import { Word } from '@docx4j/core-ts/office-js';
+//   await Word.run(pkg, async (context) => {
+//     const paragraphs = context.document.body.paragraphs;
+//     paragraphs.load('text');
+//     await context.sync();
+//     paragraphs.items[0].font.bold = true;
+//   });
+import { run, RequestContext } from './run.mjs';
+import { Document, DocumentProperties } from './document.mjs';
+import { supported, SUBSET_MEMBERS } from './supported.mjs';
+import { ClientResult, unwrap, nullObject, Wrapper } from './proxy.mjs';
+import { NotSupportedError, ItemNotFoundError, ValueNotLoadedError } from './errors.mjs';
+import { toApiScript } from './toApiScript.mjs';
+import { InsertLocation, Alignment, UnderlineType, ChangeTrackingMode, BreakType, ContentControlType, Style, ErrorCodes, SearchOptions, ListLevelType, ListNumbering, ListBullet, } from './enums.mjs';
+export { run, RequestContext, Document, DocumentProperties, ClientResult, unwrap, nullObject, Wrapper, toApiScript, supported, SUBSET_MEMBERS };
+export { NotSupportedError, ItemNotFoundError, ValueNotLoadedError };
+export { InsertLocation, Alignment, UnderlineType, ChangeTrackingMode, BreakType, ContentControlType, Style, ErrorCodes, SearchOptions };
+export { ListLevelType, ListNumbering, ListBullet };
+/**
+ * The `Word` namespace an add-in script expects: `Word.run`, the enums, and `Word.supported`, the
+ * `Class.member` strings this package implements (so a tool can check a script before running it).
+ * `Word.run` takes the package first, since there is no host document.
+ */
+export const Word = Object.freeze({
+    run,
+    supported,
+    InsertLocation,
+    Alignment,
+    UnderlineType,
+    ChangeTrackingMode,
+    BreakType,
+    ContentControlType,
+    ListLevelType,
+    ListNumbering,
+    ListBullet,
+    Style,
+    ErrorCodes,
+    SearchOptions,
+    ClientResult,
+    RequestContext,
+    Document,
+    DocumentProperties,
+    NotSupportedError,
+    ItemNotFoundError,
+    ValueNotLoadedError,
+    unwrap,
+});

package/dist/office-js/proxy.d.mts

@@ -0,0 +1,72 @@
+import type { ExtraMembers } from './extras.mjs';
+/**
+ * The result of an asynchronous call, as Office JS hands one out: `value` after `context.sync()`.
+ * It is also awaitable (an extension), so that `await body.insertXml(...)`, which is how the
+ * content API and `toApiScript`'s output read, keeps its order through the shim.
+ */
+export declare class ClientResult<T = unknown> {
+    /** The call this is the result of ('getOoxml'), for the error message. */
+    readonly member: string;
+    private loaded;
+    private result;
+    private promise;
+    constructor(
+    /** The call this is the result of ('getOoxml'), for the error message. */
+    member?: string);
+    /** @internal the underlying call, which `context.sync()` awaits and `then` delegates to. */
+    attach(promise: Promise<T>): void;
+    /** Awaiting the result resolves to the value, without waiting for the next sync. */
+    then<R1 = T, R2 = never>(onFulfilled?: ((value: T) => R1 | PromiseLike<R1>) | null, onRejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    /** The value; throws until `context.sync()` has resolved it, as Office JS does. */
+    get value(): T;
+    /** @internal filled by the context when the underlying promise settles. */
+    resolveWith(value: T): void;
+    /** True once `context.sync()` has filled it. */
+    get isLoaded(): boolean;
+    toJSON(): {
+        value: T | undefined;
+    };
+}
+/** A collection, as the subset types describe one: an array that also answers Office JS's collection members. */
+export interface Collection<T> extends Array<T> {
+    /** Office JS's collection property; the same array. */
+    readonly items: T[];
+    getFirst(): T;
+    getFirstOrNullObject(): T;
+    getLast(): T;
+    getLastOrNullObject(): T;
+    getCount(): ClientResult<number>;
+}
+/** What a context must offer the wrapper: somewhere to park the promise of an asynchronous call. */
+export interface PendingSink {
+    /** @internal */
+    enqueue(promise: Promise<unknown>): void;
+}
+/** The target behind a proxy the shim handed out; anything else is returned as it is. */
+export declare function unwrap<T>(value: T): T;
+/**
+ * A null object: `isNullObject` is true and every other member throws, as Office JS's
+ * `*OrNullObject` results do.
+ */
+export declare function nullObject<T>(className: string): T;
+/**
+ * Wraps the views of one `Word.run` in proxies. One wrapper per context, so that the same view
+ * gives the same proxy and object identity holds within a batch, as it does in Office JS.
+ */
+export declare class Wrapper {
+    private readonly context;
+    /** Members the shim adds over a view (`getOoxml`), consulted only when the view has none. */
+    private readonly extras;
+    private readonly cache;
+    constructor(context: PendingSink, 
+    /** Members the shim adds over a view (`getOoxml`), consulted only when the view has none. */
+    extras?: ExtraMembers);
+    /** Wraps whatever a member returned: a view, an array of views, a promise, or a plain value. */
+    value(value: unknown, member?: string): unknown;
+    /** The proxy over one view. */
+    object<T extends object>(view: T, className?: string): T;
+    /** The result of a call: a promise becomes a ClientResult the next sync() fills. */
+    result(value: unknown, member: string): unknown;
+    /** An array of views as an Office JS collection: the array, plus `items` and the getters. */
+    collection<T>(items: T[], member?: string): T[];
+}