docxml/types/src/Docx.d.ts

TypeScript (component) library for building and parsing a DOCX file

import { GenericRenderer } from '../deps/deno.land/x/xml_renderer@5.0.7/mod.js';
import { Archive } from './classes/Archive.js';
import { Bookmarks } from './classes/Bookmarks.js';
import { type AnyComponent } from './classes/Component.js';
import { ContentTypesXml } from './files/ContentTypesXml.js';
import { CustomPropertiesXml } from './files/CustomPropertiesXml.js';
import { type DocumentChild, DocumentXml } from './files/DocumentXml.js';
import { RelationshipsXml } from './files/RelationshipsXml.js';
import { type SettingsI } from './files/SettingsXml.js';
import { jsx } from './utilities/jsx.js';
declare type SyncRuleResult = AnyComponent | string | null;
declare type AsyncRuleResult = Promise<SyncRuleResult>;
declare type RuleResult = SyncRuleResult | AsyncRuleResult | Array<RuleResult>;
/**
 * Represents the DOCX file as a whole, and collates other responsibilities together. Provides
 * access to DOCX content types ({@link ContentTypesXml}), relationships ({@link RelationshipsXml}),
 * the document itself ({@link DocumentXml}).
 *
 * An instance of this class can access other classes that represent the various XML files in a
 * DOCX archive, such as `ContentTypes.xml`, `word/document.xml`, and `_rels/.rels`.
 */
export declare class Docx<PropsGeneric extends {
    [key: string]: unknown;
} = {
    [key: string]: never;
}> {
    #private;
    /**
     * The JSX pragma.
     */
    readonly jsx: typeof jsx;
    /**
     * The JSX pragma.
     *
     * @deprecated This static property may be removed in the future since it does not have the context of
     * a DOCX. If you can, use the instance JSX property. If you cannot, submit an issue.
     */
    static readonly jsx: typeof jsx;
    /**
     * The utility function dealing with the XML for recording content types. Every DOCX file has
     * exactly one of these.
     */
    readonly contentTypes: ContentTypesXml;
    /**
     * The utility function dealing with the top-level XML file for recording relationships. Other
     * relationships may have their own relationship XMLs.
     */
    readonly relationships: RelationshipsXml;
    readonly bookmarks: Bookmarks;
    protected constructor(contentTypes?: ContentTypesXml, relationships?: RelationshipsXml, rules?: GenericRenderer<RuleResult, {
        document: DocumentXml;
    } & PropsGeneric> | null);
    /**
     * A short-cut to the relationship that represents visible document content.
     */
    get document(): DocumentXml;
    /**
     * The API representing "docProps/custom.xml"
     */
    get customProperties(): CustomPropertiesXml;
    /**
     * Create a ZIP archive, which is the handler for `.docx` files as a ZIP archive.
     */
    toArchive(): Promise<Archive>;
    /**
     * Convenience method to create a DOCX archive from the current document and write it to your disk.
     */
    toFile(location: string): Promise<void>;
    /**
     * Instantiate this class by giving it a `.docx` file if it is already loaded as a {@link Archive} instance.
     */
    static fromArchive<PropsGeneric extends {
        [key: string]: unknown;
    } = {
        [key: string]: never;
    }>(archive: Archive): Promise<Docx<PropsGeneric>>;
    /**
     * Instantiate this class by giving it a `.docx` file loaded as a byte array.
     */
    static fromArchive<PropsGeneric extends {
        [key: string]: unknown;
    } = {
        [key: string]: never;
    }>(data: Uint8Array): Promise<Docx<PropsGeneric>>;
    /**
     * Instantiate this class by pointing at a `.docx` file location.
     */
    static fromArchive<PropsGeneric extends {
        [key: string]: unknown;
    } = {
        [key: string]: never;
    }>(location: string): Promise<Docx<PropsGeneric>>;
    /**
     * Create an empty DOCX, and populate it with the minimum viable contents to appease MS Word.
     */
    static fromNothing<PropsGeneric extends {
        [key: string]: unknown;
    } = {
        [key: string]: never;
    }>(): Docx<PropsGeneric>;
    /**
     * Create a new DOCX with contents composed by this library's components. Needs a single JSX component
     * as root, for example `<Section>` or `<Paragragh>`.
     */
    static fromJsx(roots: DocumentChild[] | Promise<DocumentChild[]>): Docx<{
        [key: string]: never;
    }>;
    /**
     * Add an XML translation rule, applied to an element that matches the given XPath test.
     *
     * If an element matches multiple rules, the rule with the most specific XPath test wins.
     */
    withXmlRule(xPathTest: string, transformer: Parameters<GenericRenderer<RuleResult, {
        document: DocumentXml;
    } & PropsGeneric>['add']>[1]): this;
    /**
     * Add _all_ the XML translatiom rules from another set of translation rules. Useful for
     * cloning.
     */
    private withXmlRules;
    /**
     * A convenience method to set a few settings for the document.
     */
    withSettings(settingOverrides: Partial<SettingsI>): this;
    /**
     * Set the document contents to the provided XML, transformed using the rules previously
     * registered through {@link Docx.withXmlRule}.
     */
    withXml(dom: string | Document, props: PropsGeneric): this;
    /**
     * Clone some reusable configuration to a new instance of {@link Docx}:
     *
     * - XML rendering rules
     * - Settings
     * - Default content types
     * - Custom styles
     *
     * Does _not_ clone other things, like:
     * - Not content
     * - Not content type overrides
     * - Not relationships (unless required for settings)
     * - Not anything else either
     */
    cloneAsEmptyTemplate(): Docx<PropsGeneric>;
}
export {};