@docx-editor.dev/core 2.31.0 → 2.33.0

package/dist/drawing-graphic-kind-CXYGYbB3.d.ts

@@ -0,0 +1,324 @@
+import { aG as OoxmlNodeId, ax as OoxmlGenericElementNode, a4 as OoxmlNode, a5 as OoxmlPackage, O as OoxmlPart, av as OoxmlElement, aA as OoxmlPackageRejection } from './tree-op-types-Df4oY2u4.js';
+import { e as HeaderFooterParts, f as HeaderFooterSectionResolution, T as TreePackageStore } from './tree-package-store-DXhX1PE-.js';
+
+/** Office Math Markup Language namespace. */
+declare const OFFICE_MATH_NAMESPACE_URI = "http://schemas.openxmlformats.org/officeDocument/2006/math";
+declare const DEFAULT_OMML_LIMITS: Readonly<{
+    maxDepth: 24;
+    maxNodes: 256;
+    maxTextLength: 512;
+}>;
+/** Shared work limits for untrusted OMML and linear-math input. */
+interface OmmlLimits {
+    readonly maxDepth?: number;
+    readonly maxNodes?: number;
+    readonly maxTextLength?: number;
+}
+/**
+ * Marks a structure whose property element carries `m:ctrlPr` operator run formatting that
+ * compact replacement cannot reproduce.
+ *
+ * The source keeps those properties verbatim. Layout draws the operator glyphs with the
+ * default math formatting. When every `m:ctrlPr` of the equation holds only default
+ * formatting, no structure carries this mark: compact replacement writes the same control
+ * properties back on each structure it emits.
+ */
+interface EquationControlSource {
+    /** The structure carries non-default `m:ctrlPr` properties, so compact replacement refuses it. */
+    readonly controlProperties?: true;
+}
+type EquationExpression = {
+    readonly kind: 'row';
+    readonly items: readonly EquationExpression[];
+} | {
+    readonly kind: 'text';
+    readonly value: string;
+    readonly format?: {
+        readonly fontFamily?: string;
+        readonly bold?: boolean;
+        readonly italic?: boolean;
+        readonly literal?: boolean;
+        readonly normalText?: boolean;
+        readonly mathStyle?: 'p' | 'b' | 'i' | 'bi';
+    };
+} | ({
+    readonly kind: 'bar';
+    readonly body: EquationExpression;
+    readonly position: 'top' | 'bottom';
+} & EquationControlSource) | ({
+    readonly kind: 'fraction';
+    readonly numerator: EquationExpression;
+    readonly denominator: EquationExpression;
+} & EquationControlSource) | ({
+    readonly kind: 'radical';
+    readonly radicand: EquationExpression;
+    readonly degree?: EquationExpression;
+} & EquationControlSource) | ({
+    readonly kind: 'script';
+    readonly base: EquationExpression;
+    readonly subscript?: EquationExpression;
+    readonly superscript?: EquationExpression;
+} & EquationControlSource) | ({
+    readonly kind: 'nary';
+    readonly operator: string;
+    readonly body: EquationExpression;
+    readonly lowerLimit?: EquationExpression;
+    readonly upperLimit?: EquationExpression;
+} & EquationControlSource) | {
+    readonly kind: 'fallback';
+    readonly text: string;
+};
+interface OmmlEquationProjection {
+    readonly sourceNodeId: OoxmlNodeId;
+    readonly expression: EquationExpression;
+    readonly fallbackText: string;
+    readonly truncated: boolean;
+    readonly visitedNodes: number;
+    /**
+     * The font size, in points, that every run of the equation shares through default run
+     * properties (`w:sz`). Absent, the equation takes the size of the surrounding text.
+     */
+    readonly fontSizePt?: number;
+}
+type LinearMathRejection = 'empty' | 'invalid-syntax' | 'invalid-xml-text' | 'depth-limit' | 'node-limit' | 'text-limit';
+type LinearMathParseResult = {
+    readonly ok: true;
+    readonly expression: EquationExpression;
+} | {
+    readonly ok: false;
+    readonly reason: LinearMathRejection;
+};
+type LinearMathOmmlResult = {
+    readonly ok: true;
+    readonly expression: EquationExpression;
+    readonly equation: OoxmlGenericElementNode;
+} | {
+    readonly ok: false;
+    readonly reason: LinearMathRejection;
+};
+/**
+ * Project one preserved `m:oMath` generic node without changing its canonical source.
+ */
+declare function projectOmmlEquation(node: OoxmlNode, limits?: OmmlLimits): OmmlEquationProjection | null;
+/** Parse the supported compact linear-math subset with fixed work limits. */
+declare function parseLinearMath(input: string, limits?: OmmlLimits): LinearMathParseResult;
+/**
+ * Convert a projected expression into reversible compact syntax.
+ *
+ * Returns an empty string when parsing the result would change the projected meaning.
+ */
+declare function equationExpressionToLinearMath(expression: EquationExpression): string;
+type NextNodeId = () => string;
+/** Parse compact linear math and generate fresh canonical OMML in one bounded operation. */
+declare function linearMathToOmml(input: string, nextId: NextNodeId, limits?: OmmlLimits): LinearMathOmmlResult;
+
+/** 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;
+    /** Complex-script heading and body theme faces. */
+    readonly majorBidi?: string | null;
+    readonly minorBidi?: string | null;
+    /** Language-specific theme faces, keyed by ISO 15924 script. */
+    readonly majorSupplemental?: Readonly<Record<string, string>>;
+    readonly minorSupplemental?: Readonly<Record<string, string>>;
+}
+/**
+ * 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;
+/** Internal live read view over the canonical store, preserving node identities for field pagination. */
+declare function headlessViewOfStore(store: TreePackageStore): HeadlessDocumentView;
+
+/**
+ * A drawing feature that the editor does not show as authored. Each code means:
+ *
+ * - `unsupported-effect`: the editor ignores an explicit effect, such as `a:blur`, `a:duotone`,
+ *   or `a14:imgProps`. The drawing renders without it.
+ * - `renderer-required`: an optional effect, such as `a:glow`, needs the drawing module:
+ *   `drawingModule()` or `installDrawing()` from `@docx-editor.dev/pro/drawing`. It appears
+ *   only while that module is not installed in the current process, for occurrences and
+ *   reports alike.
+ * - `unverified-3d`: the drawing has 3-D properties (`a:scene3d`, `a:sp3d`), which render flat.
+ * - `saved-fallback`: the editor shows the saved `mc:Fallback` content, not the main content.
+ * - `unplaced-drawing`: the drawing has no layout position, so the editor does not show it.
+ * - `inspection-limit`: a scan budget stopped the check, so the result is incomplete.
+ * - `projection-diagnostic`: the source is malformed or partly unusable. `detail` holds the
+ *   diagnostic code, such as `invalid-geometry` or `resource-refused`.
+ *
+ * The check reads the drawing's own XML. It does not read chart or diagram parts, inherited
+ * theme effects, or image bytes, so an empty list does not prove full fidelity.
+ *
+ * @public
+ */
+interface DrawingSupportIssue {
+    /** The kind of limitation. The list in this type's description explains each code. */
+    readonly code: 'unsupported-effect' | 'renderer-required' | 'unverified-3d' | 'saved-fallback' | 'unplaced-drawing' | 'inspection-limit' | 'projection-diagnostic';
+    /**
+     * The source node with the feature: in the inspected package for a report, or in the
+     * editor's current document for an occurrence's `drawingIssues`.
+     */
+    readonly nodeId: string;
+    /** The namespace of the node with the feature. */
+    readonly namespaceUri: string;
+    /** The local name of the node with the feature, such as `blur`. */
+    readonly localName: string;
+    /** The feature, such as `a:blur` or `mc:Fallback`, or the projection diagnostic code. */
+    readonly detail: string;
+}
+/**
+ * How completely the editor shows a drawing:
+ *
+ * - `native`: the editor renders the drawing and found no unsupported feature in its source.
+ * - `partial`: the editor renders the drawing, but without some features, or it shows a saved
+ *   fallback. The issue list names the features.
+ * - `unrendered`: the editor shows a placeholder, or the drawing has no layout position.
+ *
+ * A drawing that the document itself hides is `native` or `partial`: the editor shows it as
+ * authored, which is not at all.
+ *
+ * Charts and SmartArt diagrams that the editor draws report `native`, because the check does
+ * not read their chart or diagram parts. Inherited theme effects and image bytes are not
+ * checked either.
+ *
+ * @public
+ */
+type DrawingSupport = 'native' | 'partial' | 'unrendered';
+
+/**
+ * The kind of graphic a drawing holds. Note: `textbox` names every DrawingML shape, with or
+ * without text, and `shape` names only legacy VML drawings.
+ *
+ * Read from its source: `picture`, `chart` (a chart),
+ * `diagram` (SmartArt), `textbox` (a DrawingML shape, with or without text), `group` (a shape
+ * group), `canvas` (a drawing canvas), `shape` (a legacy VML drawing, such as WordArt), or
+ * `graphic` (any other graphic). It does not say whether the engine renders the graphic.
+ * The names match `placeholderGraphicKind`, which adds no `picture` and is set only for
+ * placeholders.
+ *
+ * @public
+ */
+type DrawingGraphicKind = 'picture' | 'chart' | 'diagram' | 'shape' | 'group' | 'textbox' | 'canvas' | 'graphic';
+
+export { DEFAULT_OMML_LIMITS as e, OFFICE_MATH_NAMESPACE_URI as k, authorableHyperlinkTarget as n, ensureHyperlinkRelationship as o, equationExpressionToLinearMath as p, headlessViewOfStore as q, linearMathToOmml as r, openHeadlessDocument as s, parseLinearMath as t, projectOmmlEquation as u, relationshipTargetIn as v };
+export type { DrawingGraphicKind as D, EnsuredHyperlinkRelationship as E, HeadlessDocumentView as H, LinearMathOmmlResult as L, OmmlEquationProjection as O, DrawingSupport as a, DrawingSupportIssue as b, DocumentProperties as c, HeadlessDocumentRejection as d, EquationControlSource as f, EquationExpression as g, HeadlessThemeFonts as h, LinearMathParseResult as i, LinearMathRejection as j, OmmlLimits as l, OpenHeadlessDocumentResult as m };

package/dist/drawing-preview-package-B9lSLRg4.d.ts

@@ -0,0 +1,115 @@
+import { a5 as OoxmlPackage } from './tree-op-types-Df4oY2u4.js';
+
+/** The longest name a bookmark is written with. */
+declare const MAX_AUTHORED_BOOKMARK_NAME_LENGTH = 40;
+/**
+ * Why a name cannot be written, or null when it can.
+ *
+ * - `empty`: no characters.
+ * - `tooLong`: more than {@link MAX_AUTHORED_BOOKMARK_NAME_LENGTH} characters.
+ * - `invalidStart`: the first character is not a letter or an underscore.
+ * - `invalidCharacter`: a later character is not a letter, a digit or an underscore.
+ *
+ * @public
+ */
+type BookmarkNameProblem = 'empty' | 'tooLong' | 'invalidStart' | 'invalidCharacter';
+/**
+ * Check a name before it is written. Measured in code points, so a letter outside the Basic
+ * Multilingual Plane counts once.
+ *
+ * @public
+ */
+declare function bookmarkNameProblem(name: string): BookmarkNameProblem | null;
+/**
+ * Whether a bookmark is hidden: its name starts with an underscore. Hidden bookmarks are the
+ * ones applications write for themselves, such as the targets of a table of contents.
+ *
+ * @public
+ */
+declare function isHiddenBookmarkName(name: string): boolean;
+/**
+ * The key two names are compared by. Names are case-insensitive, so `Intro` and `intro`
+ * share a key.
+ *
+ * @public
+ */
+declare function bookmarkNameKey(name: string): string;
+
+/**
+ * Where a drawing is. Pass an `inspectDrawingSupport` entry or an editor occurrence as is.
+ *
+ * @public
+ */
+interface DrawingPreviewTarget {
+    /** The part that holds the drawing, such as `/word/document.xml`. */
+    readonly ownerPartName: string;
+    /**
+     * The drawing, its compatibility wrapper, or any node inside them, in the package you pass.
+     * Every node of one drawing gives the same package.
+     */
+    readonly nodeId: string;
+}
+/** Caps for {@link createDrawingPreviewPackage}. @public */
+interface DrawingPreviewPackageLimits {
+    /** Maximum number of copied parts. Defaults to 64. */
+    readonly maxParts?: number;
+    /** Maximum number of copied bytes. Defaults to 64 MiB. */
+    readonly maxBytes?: number;
+}
+/**
+ * A preview package, or why it could not be built.
+ *
+ * - `drawing-not-found`: the target is not a drawing in the package.
+ * - `too-many-parts` or `too-large`: the drawing needs more than the limits allow.
+ *
+ * @public
+ */
+type DrawingPreviewPackageResult = {
+    readonly ok: true;
+    /**
+     * DOCX bytes with one paragraph that holds the drawing. The same drawing and document
+     * parts always give the same bytes, so a hash of them works as a cache key.
+     */
+    readonly docx: Uint8Array;
+    /**
+     * True when the page has the drawing's size, so the first page is the preview image.
+     * False when the size is unknown, such as a legacy VML drawing without a width and height
+     * in its style. Then the page has the document's page size and no margins, and the
+     * drawing starts at its top left corner. With the occurrence's `element.bounds`, crop
+     * from (0, 0) to `bounds.width * dpi / 72` by `bounds.height * dpi / 72` pixels;
+     * `bounds.x` and `bounds.y` are page positions, not crop offsets. Send this flag and the
+     * `bounds` size to your renderer with the bytes.
+     * Without `bounds`, such as for a report entry, trim the white space instead.
+     */
+    readonly pageFitsDrawing: boolean;
+    /** The package parts copied from the source document, for logging and caching. */
+    readonly copiedParts: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: 'drawing-not-found' | 'too-many-parts' | 'too-large';
+};
+/**
+ * Build a small DOCX that holds one drawing for an external renderer.
+ *
+ * Contents: one paragraph with the drawing, plus the chart and diagram parts, images, styles,
+ * theme, settings, and fonts it needs. Relationships to external targets, embedded objects,
+ * macros, and templates are dropped, so the package never points outside itself.
+ *
+ * Page: the first page is the preview. It has the drawing's size, including its effect
+ * extent, so it matches the occurrence's `bounds`, and it has no margins. A floating drawing
+ * is placed on the line, and a legacy VML drawing takes its size from its style. When the
+ * size is unknown, `pageFitsDrawing` is false; see that field for how to crop.
+ *
+ * Renderer: use one other than this library, whose own exporters show the same placeholder.
+ * The bytes come from the document, so run the renderer in a sandbox without network access,
+ * with time and memory limits.
+ *
+ * Pass the package that the target comes from: an `inspectDrawingSupport` entry with the
+ * parsed package it inspected, or an editor occurrence with the editor's current package.
+ *
+ * @public
+ */
+declare function createDrawingPreviewPackage(pkg: OoxmlPackage, target: DrawingPreviewTarget, limits?: DrawingPreviewPackageLimits): DrawingPreviewPackageResult;
+
+export { MAX_AUTHORED_BOOKMARK_NAME_LENGTH as M, bookmarkNameKey as c, bookmarkNameProblem as d, createDrawingPreviewPackage as e, isHiddenBookmarkName as i };
+export type { BookmarkNameProblem as B, DrawingPreviewPackageLimits as D, DrawingPreviewPackageResult as a, DrawingPreviewTarget as b };