@docx-editor.dev/core 2.14.1 → 2.15.0

package/dist/font-resolver-BYEHQGTw.d.ts

@@ -0,0 +1,251 @@
+import { F as FontSource, a as FontSourceSubstitution, b as FontFaceRequest, c as FontConfiguration } from './editor-sRxrFJd8.js';
+
+/**
+ * A partial font configuration one origin contributes: sources, substitutions, or both.
+ * `loadDefaultFonts()` (the substitute package) and `loadFonts()` (the fetch helper) both
+ * return this shape, so every origin composes through `composeFontConfiguration` the
+ * same way.
+ */
+interface FontConfigurationFragment {
+    readonly sources?: readonly FontSource[];
+    readonly substitutions?: readonly FontSourceSubstitution[];
+}
+/**
+ * The base of a composition: everything a `FontConfiguration` carries, all optional.
+ * Omitted fields take the documented defaults (`epoch` 0, `maxFontBytes` at the engine
+ * hard maximum, `defaultFont` Calibri at 11pt — Word's own default face and size).
+ */
+interface FontConfigurationBase extends FontConfigurationFragment {
+    /**
+     * Identity of this configuration's byte set. The engine uses it to tell one resolved
+     * font set from another; leave it unset and the editor supplies the load sequence.
+     */
+    readonly epoch?: number;
+    /** Per-face byte ceiling. Defaults to the engine hard maximum; lower it to tighten intake. */
+    readonly maxFontBytes?: number;
+    /** The face used when a run names no font. Defaults to Word's own: Calibri at 11pt. */
+    readonly defaultFont?: FontConfiguration['defaultFont'];
+    /** BCP-47 tag passed to the shaper for language-sensitive shaping. */
+    readonly language?: string;
+}
+/**
+ * What the document turned out to need, handed to an on-demand resolver.
+ *
+ * The families are the ones the file actually names — already name-validated and capped,
+ * so a resolver may treat them as a list to look up, never as URLs or paths to build.
+ */
+interface FontResolutionRequest {
+    /**
+     * Families needed by the document, deduped and capped at {@link MAX_RESOLVER_FAMILIES}.
+     * Order is deterministic but may express host priority; do not sort it before resolving.
+     */
+    readonly families: readonly string[];
+    /** The face a run naming no font resolves to, so a resolver can cover it too. */
+    readonly defaultFamily: string;
+    /** Cancels document-scoped resolution; network-backed resolvers should pass it to fetch. */
+    readonly signal?: AbortSignal;
+    /**
+     * Faces an EARLIER origin in the same composition can already PAINT — either because it
+     * supplied the bytes, or because it mapped that face onto one it did supply.
+     *
+     * Absent, not empty, when there is nothing to report: the engine calling a resolver
+     * directly, and the first origin of a composition.
+     *
+     * FACES, not families, and only faces backed by bytes. Both narrowings are load-bearing.
+     * A family-grained list would let an origin holding only regular Arial suppress the bold
+     * and italic a later origin would have supplied, and a list built from substitutions
+     * alone would let an origin whose fetches all failed suppress the failover behind it,
+     * because both shipped resolvers emit their substitution map before fetching. Together
+     * they are what makes honouring this an OPTIMIZATION rather than a correctness
+     * requirement: skipping a reported face cannot lose one, so a resolver that ignores this
+     * list only spends bytes on a face first-wins composition would drop anyway.
+     *
+     * Match it case-insensitively. Word matches font names that way and both shipped
+     * resolvers do.
+     */
+    readonly resolvedFaces?: readonly FontFaceRequest[];
+}
+/**
+ * Resolve fonts once the document's needs are known, instead of ahead of them.
+ *
+ * Called once per load, AFTER the file is parsed and mounted, with the families it
+ * declares; whatever it returns composes exactly like a statically supplied fragment.
+ * Returning nothing is a valid answer — it means "I cover none of this", and the
+ * document stays on the fixed measurer.
+ *
+ * A resolver that fetches makes opening a document perform network requests. That is a
+ * real change in posture and it must stay the APP's decision: the engine never supplies
+ * one, and the families here are file-derived, so a resolver must look them up in a set
+ * it shipped rather than interpolate them into a URL.
+ */
+type FontResolver = (request: FontResolutionRequest) => FontConfiguration | FontConfigurationFragment | undefined | Promise<FontConfiguration | FontConfigurationFragment | undefined>;
+/**
+ * Ceiling on the families one document can put in front of a resolver.
+ *
+ * A resolver typically turns each family into up to four faces, and the resource snapshot
+ * refuses more than `HARD_MAX_FONT_SOURCES` (256) sources — so 64 families is the point
+ * past which a document could no longer be served anyway. Capping here means a file
+ * declaring thousands of distinct `w:rFonts` cannot fan a resolver out across thousands
+ * of lookups (or fetches) before that limit is ever reached.
+ */
+declare const MAX_RESOLVER_FAMILIES = 64;
+/** Word's document default when nothing else says otherwise: Calibri at 11pt. */
+declare const WORD_DEFAULT_FONT: FontConfiguration['defaultFont'];
+/**
+ * Merge a base and any number of fragments into one frozen `FontConfiguration`.
+ *
+ * A bare fragment IS a valid base, so the single-origin case is one argument:
+ * `composeFontConfiguration(await loadDefaultFonts())`. Pass extra fragments to layer
+ * origins, and set `epoch`/`maxFontBytes`/`defaultFont` on the base only when you need
+ * something other than the documented defaults.
+ *
+ * - Sources dedupe first-wins by (family, weight, style), in argument order — base
+ *   before fragments, earlier fragments before later ones.
+ * - Substitutions dedupe first-wins by their `from` face, in the same order, and every
+ *   substitution whose `from` face has a direct source anywhere in the composition is
+ *   dropped: a real face always beats a stand-in.
+ * - The result is frozen (arrays included); the byte arrays themselves are the callers'
+ *   and are not copied here — the resource snapshot takes its own defensive copy.
+ */
+declare function composeFontConfiguration(base: FontConfigurationBase, ...fragments: readonly FontConfigurationFragment[]): FontConfiguration;
+
+/**
+ * The namespaced key carrying the type-level half of the mark, and the runtime property
+ * name that backs it.
+ *
+ * A plain string rather than a symbol on purpose: `@docx-editor.dev/fonts` has no runtime
+ * or type dependency on the engine, so it declares the same mark itself, and two
+ * `unique symbol`s in two packages would not unify. Two identical string keys do.
+ *
+ * @public
+ */
+declare const FONT_RESOLVER_MARK_KEY = "docx-editor.dev/font-resolver";
+/**
+ * The runtime marker `defineFontResolver` sets and {@link isFontResolver} reads.
+ *
+ * Exported because a package mirroring the font contract structurally still has to mark
+ * the resolvers it builds. A package in that position sets
+ * `Symbol.for('docx-editor.dev/font-resolver')` itself; this constant is the same symbol,
+ * named, for everyone who can import it.
+ *
+ * @public
+ */
+declare const FONT_RESOLVER_BRAND: unique symbol;
+/**
+ * The type-level half of the mark: what {@link defineFontResolver} adds to a function's
+ * type so a `FontOrigin` list can REQUIRE it.
+ *
+ * Declared with a string key so `@docx-editor.dev/fonts` can declare an identical
+ * interface and have the two unify without importing anything from the engine. Set at
+ * runtime as well as in the type — non-enumerable, so it stays out of `Object.keys` and
+ * out of a host's own spread.
+ *
+ * @public
+ */
+interface FontResolverMark {
+    /** Always `true`. Set non-enumerably by {@link defineFontResolver}. */
+    readonly 'docx-editor.dev/font-resolver': true;
+}
+/**
+ * A {@link FontResolver} that has been through {@link defineFontResolver}.
+ *
+ * This, not bare `FontResolver`, is what a `FontOrigin` list accepts. The mark is the only
+ * thing separating a resolver from a zero-argument loader, and getting that wrong loses
+ * every font silently, so the type asks for it up front.
+ *
+ * @public
+ */
+type MarkedFontResolver<T extends FontResolver = FontResolver> = T & FontResolverMark;
+/**
+ * Mark a function as an on-demand {@link FontResolver}.
+ *
+ * Wrap every resolver you put in a `fonts` list — `useFonts(...)`, `useDocxSource`'s
+ * `fonts` option, `composeFontOrigins`. The `fonts` PROP needs no marking, because a
+ * function there is always a resolver; a list also accepts the older zero-argument loader
+ * form (`{ fonts: defaultFonts }`), and this is what keeps the two apart.
+ *
+ * Returns the same function object, mutated, so the mark survives being passed around and
+ * a marked resolver stays `===` to itself. It does NOT survive `.bind()` or being wrapped:
+ * both make a new function object. Re-mark the result.
+ *
+ * ```ts
+ * const brandFonts = defineFontResolver(async ({ families }) => ({
+ *   sources: await loadMine(families),
+ * }));
+ * ```
+ *
+ * Throws a `TypeError` on a frozen or sealed function, which cannot take the mark. That is
+ * deliberate: returning it unmarked would compile — the return TYPE says marked — and then
+ * lose every font at runtime.
+ *
+ * @public
+ */
+declare function defineFontResolver<T extends FontResolver>(resolve: T): MarkedFontResolver<T>;
+/**
+ * Whether a value is a function marked by {@link defineFontResolver}.
+ *
+ * False for an unmarked function, which callers read as a zero-argument loader. Calling a
+ * resolver that way reads `request.defaultFamily` off `undefined` and throws, so the
+ * callers that make this choice say so rather than swallowing it — and the type-level mark
+ * on {@link MarkedFontResolver} is there to stop it reaching runtime at all.
+ *
+ * @public
+ */
+declare function isFontResolver(value: unknown): value is MarkedFontResolver;
+/**
+ * ONE font origin, in the one shape every origin takes: a finished configuration, a
+ * fragment, a promise for either, or a marked resolver that answers per document.
+ *
+ * The point of the union is that `packagedFonts()`, `googleFonts()`, `await defaultFonts()`
+ * and a hand-built `{ sources }` are all the same kind of thing, so a list of them needs no
+ * ordering rule beyond "first wins".
+ *
+ * The resolver arm is {@link MarkedFontResolver}, not bare `FontResolver`: a list may also
+ * hold a zero-argument loader, and only the mark separates the two.
+ *
+ * @public
+ */
+type FontOrigin = FontConfiguration | FontConfigurationFragment | MarkedFontResolver | Promise<FontConfiguration | FontConfigurationFragment | undefined> | undefined;
+/** One font origin that could not contribute a valid fragment. @public */
+interface FontOriginFailure {
+    /** Zero-based position in the first-wins origin list. */
+    readonly originIndex: number;
+    /** Resolver function name when one is safely available. */
+    readonly originName?: string;
+    readonly cause: unknown;
+}
+/** Diagnostics hook for ordered font-origin composition. @public */
+interface ComposeFontOriginsOptions {
+    /** Fire-and-forget diagnostics; returned promises are observed but do not delay resolution. */
+    readonly onOriginFailure?: (failure: FontOriginFailure) => void;
+}
+/**
+ * Resolve a list of {@link FontOrigin}s against one document's needs and merge them,
+ * first-wins in list order.
+ *
+ * Origins resolve IN ORDER, one after another, and each is told which faces the ones
+ * before it can already paint ({@link FontResolutionRequest.resolvedFaces}). Sequential
+ * rather than a `Promise.all`, and that is a real cost — one extra origin's latency on the
+ * critical path — bought deliberately: composition is first-wins, so a later origin's copy
+ * of a face an earlier one supplied can never be used, and fetching it anyway spends the
+ * bytes twice and tells a font host which families the document uses for a result that
+ * gets thrown away. Order origins cheapest-first.
+ *
+ * A resolver that ignores `resolvedFaces` still composes correctly; it just spends more.
+ *
+ * ONE ORIGIN CANNOT SINK THE REST. An origin that throws, answers `null`, or answers
+ * something malformed is reported and skipped whole, and the origins around it still
+ * compose — an app that listed a flaky network origin behind a bundled one keeps the
+ * bundled faces. Skipped WHOLE: an answer is read completely before any of it is
+ * committed, so a half-ingested origin can never reach composition.
+ *
+ * The result carries NO `epoch`: it is a fragment for the engine to stamp with the load
+ * sequence. A fixed epoch from here would label every document's byte set as the same one.
+ * `undefined` means no origin contributed anything, which is a normal answer — the document
+ * stays on the fixed measurer.
+ *
+ * @public
+ */
+declare function composeFontOrigins(origins: readonly FontOrigin[], request: FontResolutionRequest, options?: ComposeFontOriginsOptions): Promise<FontConfigurationFragment | undefined>;
+
+export { type ComposeFontOriginsOptions as C, type FontOriginFailure as F, MAX_RESOLVER_FAMILIES as M, WORD_DEFAULT_FONT as W, type FontOrigin as a, FONT_RESOLVER_BRAND as b, FONT_RESOLVER_MARK_KEY as c, type FontConfigurationBase as d, type FontConfigurationFragment as e, type FontResolutionRequest as f, type FontResolver as g, type FontResolverMark as h, type MarkedFontResolver as i, composeFontConfiguration as j, composeFontOrigins as k, defineFontResolver as l, isFontResolver as m };

package/dist/headless-document-view-DELC4E5v.d.ts

@@ -0,0 +1,134 @@
+import { a as HeaderFooterParts, b as HeaderFooterSectionResolution } from './hf-references-DTrHkktY.js';
+import { b as OoxmlPackage, O as OoxmlPart, c as OoxmlElement, g as OoxmlPackageRejection } from './tree-op-types-egdarvH_.js';
+
+/** The package with a hyperlink relationship guaranteed present, and that relationship's id. */
+interface EnsuredHyperlinkRelationship {
+    readonly pkg: OoxmlPackage;
+    readonly relationshipId: string;
+}
+/**
+ * The target this engine would write for `url`, or null when it would write none.
+ *
+ * The VALIDATION half of {@link ensureHyperlinkRelationship}, exported so a caller that must decide
+ * "would this be authored?" before it is allowed to change the package can ask without changing it.
+ * A relationship outlives a refusal — it lives beside the trees, outside the undo stack — so a
+ * caller planning a batch that may yet be refused has to ask this and mint later.
+ *
+ * Same rules, one implementation: `sanitizeHref`'s allowlist, a bound on the length, XML-writable
+ * text, and the absolute-URI gate the READ side applies. There is no legitimate reason for this
+ * engine to author a scheme it would refuse to open.
+ */
+declare function authorableHyperlinkTarget(url: string): string | null;
+/**
+ * The external hyperlink relationship for `url` on `ownerPart` (default: main document),
+ * reusing an existing one with the same target, or `null` when the URL is not something to
+ * write.
+ *
+ * REUSE IS BY EXACT TARGET, matching Word: linking twice to the same address produces one
+ * relationship. It is safe because a hyperlink relationship carries nothing but its target —
+ * two links sharing one are indistinguishable from two links with identical targets, and
+ * retargeting one always mints rather than rewriting (see the edit op).
+ *
+ * Ownership follows the story that holds the `w:hyperlink`: a header/footer or notes part
+ * mints into that part's `.rels`, never into `document.xml.rels`. Passing an owner the
+ * package does not declare fails closed (`null`) so a scoped insert cannot leave a stray
+ * body relationship behind.
+ *
+ * The URL is refused unless `sanitizeHref` admits it. Storing a `javascript:` target that a
+ * FILE authored is required — round-tripping never rewrites a document — but AUTHORING one
+ * here is not: there is no legitimate reason for this engine to write a scheme it would then
+ * refuse to open, and writing it would hand the next reader a live target this reader made.
+ */
+declare function ensureHyperlinkRelationship(pkg: OoxmlPackage, url: string, ownerPart?: string): EnsuredHyperlinkRelationship | null;
+/**
+ * What a part's relationships answer for one `r:id`, over both maps.
+ *
+ * `relationships` holds the internal records and `externalTargets` the external ones, so a
+ * resolver reading only the first sees every hyperlink as dangling.
+ */
+declare function relationshipTargetIn(pkg: OoxmlPackage, ownerPart: string, relationshipId: string): {
+    readonly target: string;
+    readonly external: boolean;
+    readonly sinkSafe?: boolean;
+} | null;
+
+/**
+ * The document metadata Word's document-property fields render.
+ *
+ * Every member is optional: an absent part, an absent element, or an empty value all read as
+ * `undefined`, and a field over a missing property paints nothing. Keys are engine-internal
+ * names; the field → property mapping (`TITLE` → `title`, `AUTHOR` → `creator`, …) lives in
+ * `layout/field-doc-property.ts`.
+ */
+interface DocumentProperties {
+    /** `dc:title` — TITLE. */
+    readonly title?: string;
+    /** `dc:creator` — AUTHOR. */
+    readonly creator?: string;
+    /** `dc:subject` — SUBJECT. */
+    readonly subject?: string;
+    /** `cp:keywords` — KEYWORDS. */
+    readonly keywords?: string;
+    /** `cp:lastModifiedBy` — LASTSAVEDBY. */
+    readonly lastModifiedBy?: string;
+    /** `dc:description` — COMMENTS. */
+    readonly description?: string;
+    /** `Company` from `docProps/app.xml`. No field maps to it yet; carried for completeness. */
+    readonly company?: string;
+    /** `Manager` from `docProps/app.xml`. No field maps to it yet; carried for completeness. */
+    readonly manager?: string;
+}
+
+/** Theme typefaces already validated for use by layout. @public */
+interface HeadlessThemeFonts {
+    readonly major: string | null;
+    readonly minor: string | null;
+    /** East Asian heading face; optional for backwards-compatible custom views. */
+    readonly majorEastAsia?: string | null;
+    /** East Asian body face; optional for backwards-compatible custom views. */
+    readonly minorEastAsia?: string | null;
+}
+/**
+ * The read capabilities shared by browser layout, server export, and future renderers.
+ *
+ * It deliberately exposes resolved package facts rather than a binding or editor session.
+ * An exporter can therefore consume the live document without importing ProseMirror or a DOM.
+ * @public
+ */
+interface HeadlessDocumentView {
+    part(): OoxmlPart;
+    currentPackage(): OoxmlPackage;
+    packageRevision(): number;
+    stylesRoot(): OoxmlElement | null;
+    numberingRoot(): OoxmlElement | null;
+    settingsRoot(): OoxmlElement | null;
+    documentThemeFonts(): HeadlessThemeFonts;
+    documentProperties(): DocumentProperties;
+    headerFooterPartsBySection(): readonly HeaderFooterParts[];
+    /**
+     * Occurrence-specific relationship metadata for header/footer stories.
+     *
+     * Optional for backwards-compatible host views; core derives it from `currentPackage()` when
+     * absent. Hosts with a working-tree overlay should expose their canonical resolution directly.
+     */
+    headerFooterResolutionBySection?(): readonly HeaderFooterSectionResolution[];
+    relationshipTarget(relationshipId: string): ReturnType<typeof relationshipTargetIn>;
+}
+/** A bad package is data, not an exceptional control path. @public */
+type HeadlessDocumentRejection = OoxmlPackageRejection | 'no-main-document-tree';
+/** Result of opening untrusted DOCX bytes for neutral layout. @public */
+type OpenHeadlessDocumentResult = {
+    readonly ok: true;
+    readonly view: HeadlessDocumentView;
+} | {
+    readonly ok: false;
+    readonly reason: HeadlessDocumentRejection;
+    readonly detail?: string;
+};
+/**
+ * Open DOCX bytes through the bounded store reader and expose only neutral layout reads.
+ * @public
+ */
+declare function openHeadlessDocument(bytes: Uint8Array): OpenHeadlessDocumentResult;
+
+export { type DocumentProperties as D, type EnsuredHyperlinkRelationship as E, type HeadlessDocumentView as H, type OpenHeadlessDocumentResult as O, type HeadlessDocumentRejection as a, type HeadlessThemeFonts as b, authorableHyperlinkTarget as c, ensureHyperlinkRelationship as e, openHeadlessDocument as o, relationshipTargetIn as r };

package/dist/hf-references-DTrHkktY.d.ts

@@ -0,0 +1,70 @@
+import { O as OoxmlPart, a as OoxmlNode, c as OoxmlElement, b as OoxmlPackage } from './tree-op-types-egdarvH_.js';
+
+/** `w:headerReference w:type` vocabulary (ECMA-376 §17.10.5): default, first page, even pages. */
+type HeaderFooterVariant = 'default' | 'first' | 'even';
+/** Header vs footer region kind for chrome and lifecycle ops. */
+type HeaderFooterKind = 'header' | 'footer';
+/**
+ * A section's resolved header and footer parts, by variant.
+ *
+ * The `even` variant is only honoured when `w:evenAndOddHeaders` is set in settings.xml —
+ * without it Word ignores an authored even header, and so does this.
+ */
+interface HeaderFooterParts {
+    readonly headers: ReadonlyMap<HeaderFooterVariant, OoxmlPart>;
+    readonly footers: ReadonlyMap<HeaderFooterVariant, OoxmlPart>;
+    /** `w:evenAndOddHeaders` in settings.xml — without it the `even` variant is ignored. */
+    readonly evenAndOddHeaders: boolean;
+    /** Whether this section enables first-page header/footer furniture (`w:titlePg`). */
+    readonly titlePage: boolean;
+}
+/**
+ * One resolved furniture slot with enough metadata for "Same as previous" chrome.
+ *
+ * `inherited: true` means this section has no declared reference for the slot and the
+ * part comes from a predecessor. The first section never reports inherited — omitting a
+ * ref there is blank furniture, not inheritance from a later section.
+ */
+interface HeaderFooterSlotMeta {
+    readonly part: OoxmlPart;
+    readonly partName: string;
+    readonly rId: string;
+    readonly inherited: boolean;
+}
+/** Per-section resolution including declared-vs-inherited metadata. */
+interface HeaderFooterSectionResolution {
+    readonly headers: ReadonlyMap<HeaderFooterVariant, HeaderFooterSlotMeta>;
+    readonly footers: ReadonlyMap<HeaderFooterVariant, HeaderFooterSlotMeta>;
+    readonly evenAndOddHeaders: boolean;
+    readonly titlePage: boolean;
+}
+/**
+ * `w:sectPr` nodes in section order, aligned with layout's `enumerateDocumentSections`.
+ *
+ * `null` means a section with no `w:sectPr` node (Word defaults, inherits HF from previous).
+ * Paragraph-level breaks first; the final entry covers remaining blocks (body-level or null).
+ */
+declare function collectSectionPropertyNodes(root: OoxmlNode): Array<OoxmlElement | null>;
+/**
+ * Resolve header/footer parts for every section with declared-vs-inherited metadata.
+ *
+ * Index aligns with `enumerateDocumentSections` in the layout package. Existing merged
+ * maps stay available via {@link resolveHeaderFooterPartsBySection}.
+ */
+declare function resolveHeaderFooterResolutionBySection(pkg: OoxmlPackage): readonly HeaderFooterSectionResolution[];
+/**
+ * Resolve header/footer parts for every section, applying OOXML inheritance.
+ *
+ * Index aligns with `enumerateDocumentSections` in the layout package.
+ */
+declare function resolveHeaderFooterPartsBySection(pkg: OoxmlPackage): readonly HeaderFooterParts[];
+/**
+ * Resolve the main-document header/footer references to their parts, gated by the
+ * settings the section actually declares.
+ *
+ * Returns the FINAL section's effective parts (after inheritance). Multi-section hosts
+ * should prefer `resolveHeaderFooterPartsBySection`.
+ */
+declare function resolveHeaderFooterParts(pkg: OoxmlPackage): HeaderFooterParts;
+
+export { type HeaderFooterVariant as H, type HeaderFooterParts as a, type HeaderFooterSectionResolution as b, type HeaderFooterKind as c, type HeaderFooterSlotMeta as d, collectSectionPropertyNodes as e, resolveHeaderFooterPartsBySection as f, resolveHeaderFooterResolutionBySection as g, resolveHeaderFooterParts as r };