import { BodyElement, FloatAnchor, ImageCrop, InlineImage, PictureOutline, RelativeSize, ShapeFill, ShapeGeometry, ShapeGroupChild, ShapeLine, ShapeShadow, ShapeTextBody, ShapeTransform } from '../core/document-model/index.js'; import { ColorResolver } from '../core/drawingml/colors.js'; import { PoNode } from '../core/po-helpers.js'; import { Pt, ResourceId } from '../core/ir/index.js'; /** * A parsed DrawingML shape without the owning paragraph's properties (attached by * the caller, mirroring how the image branch returns size + id and the caller * adds the `pPr`). */ export interface ShapeData { readonly width: Pt; readonly height: Pt; /** §20.5.2.17 — the shapes a `wpg:wgp` group holds, placed in its own box. */ readonly children?: ReadonlyArray; readonly geometry: ShapeGeometry; readonly fill: ShapeFill; readonly line?: ShapeLine; readonly transform?: ShapeTransform; /** `wp14:sizeRelH/V` — a size stated as a share of the page or margins. */ readonly relativeSize?: RelativeSize; /** The shape's text body (a `wps:txbx`), when it carries one. */ readonly text?: ShapeTextBody; } /** * Parses the body elements of a `w:txbxContent`. Injected by the caller to avoid * a module cycle with `document-parser` (which imports this module). */ export type ParseBody = (children: ReadonlyArray) => Array; /** * §21.1.2 `a:txBody` — the DrawingML text body a shape may carry instead of a * `wps:txbx`. Supplied by the caller (the reader owns the PresentationML text * reader that knows how to walk it), so this module stays free of it. */ export type ParseDrawingText = (txBody: PoNode, resolveColor: ColorResolver) => ShapeTextBody | undefined; /** * §20.1.4.1.14/§20.1.4.1.15 — the theme's format scheme, as the raw nodes a * `` reference indexes: the fill styles (`a:fillStyleLst`), the * BACKGROUND fill styles (`a:bgFillStyleLst`, which an `a:fillRef` reaches with * an index past 1000) and the effect styles (`a:effectStyleLst`). */ export interface ThemeStyles { readonly fills?: ReadonlyArray; readonly bgFills?: ReadonlyArray; readonly effects?: ReadonlyArray; } /** * The result of parsing a `` (or legacy VML picture): an embedded * picture, a DrawingML shape, a chart reference, or a SmartArt diagram. Each * variant carries optional alternate text and a float anchor. */ export type DrawingContent = { readonly kind: 'image'; readonly imageId: string; readonly width: Pt; readonly height: Pt; /** §20.1.2.2.24 `a:ln` on `pic:spPr` / VML `@stroked` — the picture's frame. */ readonly outline?: PictureOutline; /** §20.1.8.40 `a:outerShdw` on the same `pic:spPr` — the picture's shadow. */ readonly shadow?: ShapeShadow; /** §14.1.2.10 `@gain`/`@blacklevel` — the wash the picture is drawn through. */ readonly wash?: { readonly gain: number; readonly black: number; }; /** §20.1.8.55 `a:srcRect` — the part of the source the frame shows. */ readonly crop?: ImageCrop; /** §20.1.7.6 `a:xfrm @rot` — the picture's rotation (1/60000°, clockwise). */ readonly rotation60k?: number; /** §20.1.7.6 `a:xfrm @flipH/@flipV` — the picture drawn mirrored. */ readonly flipH?: boolean; readonly flipV?: boolean; /** `wp14:sizeRelH/V` — a size stated as a share of the page or margins. */ readonly relativeSize?: RelativeSize; /** §20.4.2.6 `wp:effectExtent` on an INLINE drawing: space reserved around it. */ readonly effectExtent?: InlineImage['effectExtent']; /** `wp:docPr` `@descr`/`@title` — alternate text for the tagged-PDF Figure. */ readonly altText?: string; readonly float?: FloatAnchor; } | { readonly kind: 'shape'; readonly data: ShapeData; readonly altText?: string; readonly float?: FloatAnchor; } | { readonly kind: 'chart'; /** The `c:chart` `@r:id` relationship id to the chart part. */ readonly chartRelId: string; readonly width: Pt; readonly height: Pt; readonly altText?: string; readonly float?: FloatAnchor; } | { readonly kind: 'diagram'; /** SmartArt data-part relationship id (`dgm:relIds` `@r:dm`); the reader resolves the drawing override. */ readonly dmRelId: string; /** Frame width in EMU. */ readonly widthEmu: number; /** Frame height in EMU. */ readonly heightEmu: number; readonly altText?: string; readonly float?: FloatAnchor; }; /** * ECMA-376 Part 3 (Markup Compatibility) — resolve an `` to * the children of the first `` whose `Requires` lists only namespaces * we understand, else the `` children, else nothing. (`Requires` * holds space-separated namespace prefixes as declared in the document.) * * @param altContent The `mc:AlternateContent` node. * @returns The chosen branch's children. */ export declare function resolveMc(altContent: PoNode): ReadonlyArray; /** * Flatten a children list, expanding any `` to its chosen * branch (via {@link resolveMc}) so downstream scanning sees plain elements (a * ``, or the VML we ignore). Used both at run level and inside * `a:graphicData`. * * @param children The raw child list. * @returns The flattened children. */ export declare function expandMcChildren(children: ReadonlyArray): Array; /** * Parse a `` (ECMA-376 Part 1 §20) into a {@link DrawingContent}. The * `a:graphicData` `@uri` selects the branch: a `wps:wsp` shape, a chart, a * SmartArt diagram, or — falling through — an embedded picture from * `a:blip @r:embed`. * * @param drawing The `w:drawing` node. * @param resolveColor Resolver for theme/scheme colours used by shape fills/lines. * @param parseBody Optional body parser for a shape's text box (omitted ⇒ no text). * @returns The parsed content, or `null` when no anchor / recognizable graphic is found. */ export declare function parseDrawing(drawing: PoNode, resolveColor: ColorResolver, parseBody?: ParseBody, resolveImage?: (relId: string) => ResourceId | undefined, resolveChartPart?: (relId: string) => string | undefined, themeLineWidths?: ReadonlyArray, themeStyles?: ThemeStyles, parseDrawingText?: ParseDrawingText): DrawingContent | null; /** * Parse a legacy ``/`` VML picture (ISO/IEC 29500-1 §14, VML * transitional) into an `image` {@link DrawingContent}. Modern files use * `` ({@link parseDrawing}); VML still shows up in headers, OLE-object * previews (`@o:ole`) and documents last saved by older Word. A VML shape carries * an `` pointing at the media part and a CSS-like `@style` * (`"width:75.6pt;height:49.2pt"`) giving its box; just enough is read to recover * the relationship id, the size and the `@alt` text. * * @param node The `w:pict` / `w:object` node. * @returns The picture, or `null` when there is no embedded `v:imagedata` or no usable size. */ export declare function parseVmlPicture(node: PoNode, parseBody?: ParseBody): DrawingContent | null; /** * §14.1.2.5 — `@filled="f"` or a `` says the shape is not * filled; otherwise `@fillcolor`, defaulting to VML's own white. Exported * because §17.2.1's page background is a `v:background` with exactly this fill * on it — the same gradients and the same pictures. * * @param shape The VML element carrying the fill. * @param shapeType Its `v:shapetype`, for the attributes it does not state. * @param resolveImage Resolver for a `v:fill` that paints a PICTURE (`@r:id`). * @returns The fill. */ export declare function vmlFill(shape: PoNode, shapeType?: PoNode, resolveImage?: (id: string) => ResourceId | undefined): ShapeFill; /** * §20.1.8.55 `a:srcRect` — the picture's own edges, cut away before it is * fitted to its frame. Each is a percentage in thousandths (ST_Percentage), so * `l="14711"` drops the left 14.711%. * * @param node The `a:srcRect` element, or `undefined` when the fill declares none. * @returns The crop, or `undefined` when nothing is cut away. */ export declare function parseSrcRect(node: PoNode | undefined): ImageCrop | undefined; /** * The fill with the direction the SHAPE states, where it states one and no * colours: §20.1.8.33's `a:gradFill` holding only an `a:lin` says "sweep the * gallery style's run of colours this way". 63200.pptx's ellipse asks for the * diagonal where the theme's slot sweeps straight down. * * @param fill The fill resolved from the style (or anywhere else). * @param spPr The shape's own properties. * @returns The fill, turned; unchanged when the shape states no bare direction. */ export declare function withStatedDirection(fill: ShapeFill, spPr: PoNode | undefined): ShapeFill; /** * Whether an `spPr` states a fill AT ALL — including `a:noFill`, which is a * shape saying it has none rather than saying nothing. A placeholder that says * nothing inherits its prototype's. * * @param spPr The shape properties, or undefined. * @returns Whether a fill element is present. */ export declare function statesFill(spPr: PoNode | undefined): boolean; export declare function styleRefFill(style: PoNode, resolveColor: ColorResolver, themeStyles?: ThemeStyles): ShapeFill; export declare function styleRefLine(style: PoNode, resolveColor: ColorResolver, themeLineWidths?: ReadonlyArray): ShapeLine | undefined; /** * §20.1.4.2.14 `a:fontRef` — the colour a gallery style writes its text in. * * @param style The shape's `p:style`/`wps:style` node. * @param resolveColor The document's colour resolver. * @returns The 6-hex colour, or `undefined` when the style names none. */ export declare function styleRefFontColor(style: PoNode, resolveColor: ColorResolver): string | undefined; export declare function withStyleFontColor(text: ShapeTextBody, style: PoNode, resolveColor: ColorResolver): ShapeTextBody; /** * §20.1.7.6 `a:xfrm` — how a shape sits in its box: rotated about its centre by * `@rot` (sixtieth-thousandths of a degree) and mirrored by `@flipH`/`@flipV`. * The box itself comes from elsewhere — the anchor on a sheet, the extent in a * document — and holds the shape UNROTATED, which is what makes this a separate * transform rather than a different rectangle. * * @param xfrm The `a:xfrm` element. * @returns The transform; empty when it states neither rotation nor a flip. */ export declare function parseXfrm(xfrm: PoNode): ShapeTransform; /** * Parse an `a:prstGeom` (§20.1.9.18) into a preset {@link ShapeGeometry}: the * `@prst` preset name plus the `a:avLst` adjust values (each `a:gd`'s `val …` * formula). Defaults to the `rect` preset when `@prst` is absent. */ export declare function parsePrstGeom(prst: PoNode): ShapeGeometry; /** * Parse an `a:custGeom` (ECMA-376 §20.1.9.11) → its first `` * (§20.1.9.15) into a custom {@link ShapeGeometry}. Coordinates stay in * path-space (the geometry layer scales + y-flips them). Multiple subpaths with * differing `w`/`h` are a follow-up; falls back to a `rect` preset when the path * is empty or has no usable size. */ export declare function parseCustGeom(cust: PoNode): ShapeGeometry; /** * Parse a shape's fill from its `a:spPr`: the first of `a:noFill`, `a:solidFill` * or `a:gradFill` wins. An unresolvable colour degrades to `{ kind: 'none' }`. * * @param spPr The `wps:spPr` node. * @param resolveColor Resolver for theme/scheme colours. */ export declare function parseFill(spPr: PoNode, resolveColor: ColorResolver, resolveImage?: (relId: string) => ResourceId | undefined): ShapeFill; /** * §20.1.8.16 `a:clrChange` — the colour a picture declares away, and what it * becomes. `useA` (default true) says the destination's alpha counts, so a * destination at zero alpha knocks the colour OUT rather than replacing it. * * @param blip The `a:blip` node. * @param resolveColor The colour resolver. * @returns The change, or `undefined` when the blip declares none. */ export declare function colorChangeOf(blip: PoNode, resolveColor: ColorResolver): { readonly fromHex: string; readonly toHex: string; readonly transparent: boolean; } | undefined; /** * Parse a shape's drop shadow from its `a:spPr` (§20.1.8.40 `a:effectLst` → * `a:outerShdw`). * * The spec states the displacement in polar form: `dist` in EMU and `dir` in * 60 000ths of a degree, measured clockwise from due east in a frame whose y * grows DOWNWARD — so the standard 2 700 000 (45°) puts the shadow down and to * the right, which is where every reader draws it. * * @param spPr The shape's `spPr` node. * @param resolveColor Resolver for theme/scheme colours. * @returns The shadow, or undefined when the shape declares none. */ export declare function parseShadow(spPr: PoNode, resolveColor: ColorResolver): ShapeShadow | undefined; /** * Build a {@link ShapeShadow} from an `a:outerShdw` node. * * @param shdw The `a:outerShdw` node. * @param resolveColor Resolver for theme/scheme colours. * @returns The shadow, or undefined when its colour will not resolve. */ export declare function shadowFromOuterShdw(shdw: PoNode, resolveColor: ColorResolver): ShapeShadow | undefined; /** * Parse a shape's outline (`a:ln`) from its `a:spPr` into a {@link ShapeLine}: * width, cap, solid colour, dash pattern, and an explicit `a:noFill` (an unstroked * outline). Returns `undefined` when the shape has no `a:ln`. * * @param spPr The `wps:spPr` node. * @param resolveColor Resolver for theme/scheme colours. */ export declare function parseLine(spPr: PoNode, resolveColor: ColorResolver): ShapeLine | undefined;