import { ChatTransport } from 'ai'; import { ComponentOptionsMixin } from 'vue'; import { ComponentProvideOptions } from 'vue'; import { ComputedRef } from 'vue'; import { CSSProperties } from 'vue'; import { DefineComponent } from 'vue'; import { Doc } from 'yjs'; import { LanguageModel } from 'ai'; import { MaybeRefOrGetter } from 'vue'; import { PublicProps } from 'vue'; import { Ref } from 'vue'; import { ShallowRef } from 'vue'; import { ToolSet } from 'ai'; import { UIMessage } from 'ai'; declare const __VLS_base: DefineComponent<__VLS_Props, { /** The scaled slide origin, for host pointer-to-slide coordinate conversion. */ getStageElement: () => HTMLElement | null; }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, { createGuide: (axis: "h" | "v", position: number) => any; "update:fitScale": (args_0: number) => any; }, string, PublicProps, Readonly<__VLS_Props> & Readonly<{ onCreateGuide?: ((axis: "h" | "v", position: number) => any) | undefined; "onUpdate:fitScale"?: ((args_0: number) => any) | undefined; }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_base_2: DefineComponent<__VLS_Props_2, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_2> & Readonly<{}>, { scale: number; }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export: DefineComponent any; "content-change": (content: Uint8Array) => any; autosave: (content: Uint8Array) => any; "active-slide-change": (value: number) => any; "zoom-change": (value: number) => any; "slide-count-change": (value: number) => any; "mode-change": (mode: string) => any; "selection-change": (elementIds: string[]) => any; "start-collaboration": (config: CollaborationConfig) => any; "stop-collaboration": () => any; }, string, PublicProps, Readonly & Readonly<{ "onDirty-change"?: ((isDirty: boolean) => any) | undefined; "onContent-change"?: ((content: Uint8Array) => any) | undefined; onAutosave?: ((content: Uint8Array) => any) | undefined; "onActive-slide-change"?: ((value: number) => any) | undefined; "onZoom-change"?: ((value: number) => any) | undefined; "onSlide-count-change"?: ((value: number) => any) | undefined; "onMode-change"?: ((mode: string) => any) | undefined; "onSelection-change"?: ((elementIds: string[]) => any) | undefined; "onStart-collaboration"?: ((config: CollaborationConfig) => any) | undefined; "onStop-collaboration"?: (() => any) | undefined; }>, { barChart3D: boolean; lineChart3D: boolean; areaChart3D: boolean; pieChart3D: boolean; surfaceChart3D: boolean; smartArt3D: boolean; canEdit: boolean; }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_10: DefineComponent<__VLS_Props_9, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_9> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_11: DefineComponent<__VLS_Props_10, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_10> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_12: DefineComponent<__VLS_Props_11, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_11> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_13: DefineComponent<__VLS_Props_12, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_12> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_14: DefineComponent<__VLS_Props_13, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_13> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_15: DefineComponent<{ /** Remote collaborators to render, in unscaled slide coordinates. */ cursors: RemoteCursor[]; /** * @deprecated Unused. The scaled slide-stage host already applies the zoom * via its CSS transform, so cursor coordinates are rendered as-is. */ zoom?: number; }, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{ /** Remote collaborators to render, in unscaled slide coordinates. */ cursors: RemoteCursor[]; /** * @deprecated Unused. The scaled slide-stage host already applies the zoom * via its CSS transform, so cursor coordinates are rendered as-is. */ zoom?: number; }> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_16: DefineComponent<__VLS_Props_14, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, { format: (updates: Partial) => any; cancel: () => any; change: (text: string, snapshot?: InlineTextEditSnapshot | undefined) => any; commit: () => any; listSession: (event: { controller: InlineListController; active: boolean; }) => any; }, string, PublicProps, Readonly<__VLS_Props_14> & Readonly<{ onFormat?: ((updates: Partial) => any) | undefined; onCancel?: (() => any) | undefined; onChange?: ((text: string, snapshot?: InlineTextEditSnapshot | undefined) => any) | undefined; onCommit?: (() => any) | undefined; onListSession?: ((event: { controller: InlineListController; active: boolean; }) => any) | undefined; }>, { spellCheck: boolean; }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_17: DefineComponent<__VLS_Props_15, { hasActivePointerInteraction: () => boolean; }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, { transform: (payload: TransformPayload_2) => any; transformStart: (payload: { id: string; }) => any; transformEnd: (payload: TransformPayload_2) => any; adjustStart: (payload: { id: string; }) => any; adjust: (payload: AdjustPayload) => any; adjustEnd: (payload: AdjustPayload) => any; requestEdit: (payload: { id: string; }) => any; }, string, PublicProps, Readonly<__VLS_Props_15> & Readonly<{ onTransform?: ((payload: TransformPayload_2) => any) | undefined; onTransformStart?: ((payload: { id: string; }) => any) | undefined; onTransformEnd?: ((payload: TransformPayload_2) => any) | undefined; onAdjustStart?: ((payload: { id: string; }) => any) | undefined; onAdjust?: ((payload: AdjustPayload) => any) | undefined; onAdjustEnd?: ((payload: AdjustPayload) => any) | undefined; onRequestEdit?: ((payload: { id: string; }) => any) | undefined; }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_18: DefineComponent<__VLS_Props_16, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & { retry: () => any; }, string, PublicProps, Readonly<__VLS_Props_16> & Readonly<{ onRetry?: (() => any) | undefined; }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_19: DefineComponent<{ /** Remote collaborators' presence (cursor + selection + active slide). */ presences: RemotePresence[]; /** Elements on the active slide (used to resolve selected ids → geometry). */ elements: PptxElement[]; /** The current slide index: only peers on this slide are drawn. */ activeSlideIndex: number; /** * @deprecated Unused. The scaled slide-stage host already applies the zoom * via its CSS transform, so selection geometry is rendered as-is. */ zoom?: number; }, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{ /** Remote collaborators' presence (cursor + selection + active slide). */ presences: RemotePresence[]; /** Elements on the active slide (used to resolve selected ids → geometry). */ elements: PptxElement[]; /** The current slide index: only peers on this slide are drawn. */ activeSlideIndex: number; /** * @deprecated Unused. The scaled slide-stage host already applies the zoom * via its CSS transform, so selection geometry is rendered as-is. */ zoom?: number; }> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_2: __VLS_WithSlots; declare const __VLS_export_20: DefineComponent<__VLS_Props_17, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {} & { follow: (clientId: number | null) => any; }, string, PublicProps, Readonly<__VLS_Props_17> & Readonly<{ onFollow?: ((clientId: number | null) => any) | undefined; }>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_21: DefineComponent & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_3: __VLS_WithSlots_2; declare const __VLS_export_4: DefineComponent<__VLS_Props_3, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_3> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_5: DefineComponent<__VLS_Props_4, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_4> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_6: DefineComponent<__VLS_Props_5, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_5> & Readonly<{}>, { interactive: boolean; }, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_7: DefineComponent<__VLS_Props_6, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_6> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_8: DefineComponent<__VLS_Props_7, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_7> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; declare const __VLS_export_9: DefineComponent<__VLS_Props_8, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props_8> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>; /** * SlideCanvas - Vue port of the React `SlideCanvas.tsx`. * * Centres a {@link SlideStage} in a scrollable viewport with a drop shadow. * The rulers, grid, guides, marquee/selection, connector-creation, drawing, * and collaboration overlays are layered in by the surrounding viewer * components. * * Responsive sizing: the slide has a fixed authored pixel size (e.g. 1280×720), * which overflows small/mobile viewports. We measure the scroll viewport and * emit a `fitScale` (capped at 1 unless the host opts into enlargement) * so the parent can fold it into the effective zoom, mirroring the * React viewer's `fitScale * scale` model where "100%" means "fit to viewport". */ declare type __VLS_Props = { slide: PptxSlide | undefined; canvasSize: CanvasSize; mediaDataUrls: Map; /** Effective scale (fitScale × user zoom) supplied by the parent. */ zoom?: number; /** Unscaled decorative padding per side; omission preserves existing fit. */ fitPadding?: ViewportFitPadding; /** Fit-factor ceiling, separate from user zoom; null permits enlargement. */ maxFitScale?: number | null; /** Show the horizontal/vertical rulers along the slide edges (View ▸ Rulers). */ showRulers?: boolean; /** Unit system for the ruler labels; defaults to inches, as PowerPoint does. */ rulerUnit?: RulerUnit; /** Selected element extent (unscaled slide px) highlighted on the rulers. */ rulerSelectedBounds?: { x: number; y: number; width: number; height: number; } | null; /** Allow dragging a guide off a ruler strip (editing only). */ canDragGuides?: boolean; /** * Master/layout (template) elements for the active slide, rendered by * {@link SlideStage} in a dedicated layer behind the slide content. */ templateElements?: PptxElement[]; /** * When on, master/layout (template) elements become interactive on the canvas * and gain a visual affordance. Threaded down to {@link SlideStage}. */ editTemplateMode?: boolean; /** * The element currently open in the element-level inline text editor; * threaded down to {@link SlideStage} so it can suppress that element's own * static text render while the editor overlay draws it instead. */ inlineEditingElementId?: string | null; }; /** * Model3DRenderer - Vue port of the React `Model3DRenderer` / `PosterFallback` * (in `Model3DRenderer.tsx`). * * When the element carries a 3D model (`modelData`) and the optional `three` * peer dependency is installed, this mounts the shared, framework-agnostic * vanilla-three controller (`mountModel3D` from `pptx-viewer-shared`) into a * container div for interactive rotate/zoom. The blob-URL lifecycle and * three.js availability are handled by {@link useModel3dScene}; this SFC stays * thin presentation. * * It falls back to the poster/preview image (`posterImage`, then `imageData`) * when there is no model data or three.js is unavailable, drawing a labelled * "3D model" placeholder when no poster exists - exactly like React. */ declare type __VLS_Props_10 = { element: PptxElement; mediaDataUrls?: Map; zIndex: number; /** True only on the main editable canvas; see `hitTargetStyle`. */ interactive?: boolean; /** True only on the live presentation stage; see `hitTargetStyle`. */ presenting?: boolean; }; /** * ZoomRenderer - Vue port of the React `ZoomElementRenderer`. * * Renders a Slide-Zoom / Section-Zoom tile (`ZoomPptxElement`): the element's * own preview thumbnail (`imageData`) when available, otherwise a fallback tile * showing the target slide number. A small "Slide Zoom" / "Section Zoom" badge * is drawn in the corner. * * In presentation mode the controller provides a zoom-navigation context, so * clicking (or Enter/Space) jumps to the target slide. Outside presentation mode * no context is injected and the tile stays a static link, exactly as before. * When the viewer provides a zoom-target lookup, the fallback tile mirrors * React's `ZoomSlideThumbnail`: the target slide's real background colour, its * own slide number and friendly section name (no live mini-rendering). Without a * provider it falls back to the target index and section GUID. */ declare type __VLS_Props_11 = { element: PptxElement; mediaDataUrls?: Map; zIndex: number; /** True only on the main editable canvas; see `hitTargetStyle`. */ interactive?: boolean; /** True only on the live presentation stage; see `hitTargetStyle`. */ presenting?: boolean; }; /** * EquationRenderer: renders an element's math equation(s) as inline MathML. * * Vue port of the React equation rendering path * (`text-segment-helpers.tsx#renderEquationSegment`). Equations live on text * elements as {@link TextSegment} entries whose `equationXml` field holds the * parsed OMML (`m:oMathPara` / `m:oMath`) tree. Each such segment is converted * to MathML via {@link convertOmmlToMathMl}, sanitised, and injected with * `v-html`: MathML is namespaced HTML, so browsers render `` natively. * * The wrapper uses {@link getContainerStyle} for absolute positioning, matching * every other element renderer. */ declare type __VLS_Props_12 = { element: PptxElement; mediaDataUrls?: Map; zIndex: number; /** True only on the main editable canvas; see `hitTargetStyle`. */ interactive?: boolean; /** True only on the live presentation stage; see `hitTargetStyle`. */ presenting?: boolean; }; /** * WordArtText - Vue port of the React `WarpedText` SVG renderer. * * Renders warped (WordArt) text. Every classified preset (`textNoShape` / * `textPlain` / unknown excluded) renders along an SVG `` baseline * built by {@link shouldUseSvgWarp} + `buildWarpPath`: arch/wave/circle/ * triangle/chevron/ring/curve, and (as of the WordArt envelope fidelity fix) * inflate/deflate/can/slant/fade/cascade too, matching React and Vanilla. * * This used to branch on `classifyTextWarp(preset)` and fall back to a flat * `
` + CSS `transform` approximation for the `envelope`/`simple` * categories; that branch was dead code once `shouldUseSvgWarp` is used * directly (it already returns `true` for every classified preset), and * because React/Vanilla never had that branch, Vue rendered inflate/deflate/ * can/slant/fade/cascade as a flat CSS-transform approximation while React * and Vanilla already rendered them as true SVG textPath - a cross-binding * parity bug this component no longer has. * * Presets that are not classified (`textNoShape`, `textPlain`, unknown values) * cause the component to render nothing; callers fall back to flat text. The * overlay is absolutely positioned to fill the host box and is * `pointer-events: none` so it overlays without intercepting interaction. */ declare type __VLS_Props_13 = { element: PptxElement; zIndex: number; }; declare type __VLS_Props_14 = { element: PptxElement; livePatcher?: CollaborationLivePatcher; slideId?: string; /** Draw the browser's native red spell-check squiggles while editing (View ▸ Spell). */ spellCheck?: boolean; }; declare type __VLS_Props_15 = { elements: PptxElement[]; selectedIds: string[]; zoom: number; /** Keep handles above the active editor without changing connector layering. */ inlineEditing?: boolean; }; declare type __VLS_Props_16 = { /** Current WebSocket connection status. */ status: ConnectionStatus; /** Number of connected participants (including the local user). */ connectedCount: number; }; declare type __VLS_Props_17 = { /** Active remote collaborators (excludes self). */ presences: RemotePresence[]; /** The clientId currently being followed, or null. */ followedClientId: number | null; }; /** * SlideStage - the fixed-size slide surface (background + absolutely-positioned * elements) rendered at a given `scale`. * * Extracted so it can be reused at full size by `SlideCanvas` and at tiny scale * by the thumbnail rail. It owns no chrome (no centering, margins, or shadow); * the host decides layout. * * Template (master/layout) elements are rendered in a DEDICATED layer behind the * slide content (lower z), supplied separately via `templateElements`. They are * interactive (and gain the editable affordance) only while `editTemplateMode` * is on; otherwise they render but are locked. * * Accessibility contract: exactly ONE `aria-roledescription="slide"` region * exists per surface. On the editable canvas that region is the `SlideCanvas` * wrapper (which also paints the resolved background), mirroring React's * `SlideCanvas.tsx`, so the interactive stage itself stays unlabelled. Only the * standalone live presentation stage (`presenting`, no wrapper) self-labels. * Static stages (thumbnails, sorter, previews, export) are `aria-hidden` and * additionally have their `data-element-id` markers stripped post-render (see * `stripElementIdMarkers`) so element queries always hit the real canvas copy. */ declare type __VLS_Props_2 = { slide: PptxSlide | undefined; canvasSize: CanvasSize; mediaDataUrls: Map; scale?: number; /** Mark elements with the `data-pptx-element` interaction hook (main canvas only). */ interactive?: boolean; /** * Master/layout elements pulled out of the slide at load time, rendered in a * dedicated layer behind the slide content. */ templateElements?: PptxElement[]; /** * When on, the template-layer elements become interactive and gain a visual * affordance; when off they render but are locked. Only the main editable * canvas threads this through. */ editTemplateMode?: boolean; /** * True only for the live presentation stage: slide-content media autoplays * (as in a real slideshow). Left false for thumbnails, the sorter, presenter * previews and transition snapshots so their media stays quiet. */ presenting?: boolean; /** * Keep the `data-element-id` markers on an otherwise-static stage. * * Only the Morph transition layers set this: their per-element CSS is * keyed on those markers. It does not create a duplicate marked copy, * because the host hides its own stage while the overlay is mounted. */ preserveElementIds?: boolean; /** * Render the elements with NO slide background at all. * * `getSlideBackgroundStyle` always resolves to an opaque paint (it falls * back to `DEFAULT_SLIDE_BACKGROUND` when the slide declares none), which is * right for a real surface and fatal for a stage stacked over another one. * The morph transition's departing-shape layer is exactly that: it sits on * top of the incoming slide, so its background would hide the whole morph * behind a flat slab for the entire transition. */ transparentBackground?: boolean; /** * The element currently open in the element-level inline text editor * (mounted as a slotted overlay by the host), threaded down so * `ElementRenderer` can suppress its own text render for that one element * instead of duplicating it underneath the editor (issue #182). */ inlineEditingElementId?: string | null; }; /** * ElementRenderer: Vue port of the React `ElementRenderer.tsx`. * * A thin dispatcher: renders a slide element by its `type` discriminant, * delegating each non-trivial type to a dedicated renderer component. The text * paragraph/bullet model is built by the shared, framework-agnostic * `buildParagraphs`; image/media branches live in their own box components. */ declare type __VLS_Props_3 = { element: PptxElement; mediaDataUrls: Map; zIndex: number; /** * When true, emit the `data-pptx-element` test/interaction hook. Only the * primary editable canvas sets this; thumbnails, the sorter, the export * stage and presentation mode render without it. */ interactive?: boolean; /** * When true, emit the `data-pptx-element` marker even though `interactive` is * off. The main canvas sets this for template (master/layout) elements, which * are interaction-locked outside edit-template mode but are still rendered * slide elements as far as the contract is concerned (mirrors React, which * always tags canvas elements and gates interactivity separately). */ marked?: boolean; /** * When true, this element belongs to the slide layout/master and the viewer is * in edit-template mode: draw a visual affordance so the user can tell apart * the (now editable) shared template shapes from normal slide content. */ templateEditing?: boolean; /** True only on the live presentation stage; enables media autoplay. */ presenting?: boolean; /** * The enclosing group's fill (`GroupPptxElement.groupFill`), passed down by a * group's render branch so a child painted with `a:grpFill` inherits it. */ parentGroupFill?: ShapeStyle; /** * The element currently open in the element-level inline text editor * (`InlineTextEditor.vue`, mounted separately in `ViewerCanvasOverlays.vue`), * or `null`/`undefined` when nothing is being edited. * * Mirrors React's `ElementBody.renderBody`, which swaps its static text * render out for `InlineTextEditor` while `isEditing` is true rather than * layering the two: without this, this renderer kept painting the element's * normal text UNDERNEATH the editor overlay, and the editor's own * translucent background let it show through as a duplicate, offset "text * shadow" (issue #182). */ inlineEditingElementId?: string | null; }; /** * ConnectorRenderer: Vue port of the React `ConnectorElementRenderer`. * * Renders straight, bent, and curved connectors as an inline SVG spanning the * element's bounding box, with stroke colour/width/dash, start/end arrowheads, * and compound (double/triple) line support. * * Supported connector types: * - straightConnector1 / line → simple element * - bentConnector2/3/4/5 → orthogonal elbow path (L commands) * - curvedConnector2/3/4/5 → Bézier curve path (Q / C commands) * - compound lines (dbl/thickThin/thinThick/tri) → parallel offset strokes * * Flip is baked into the path geometry (not a CSS transform) so arrowheads * point the right way for both straight and multi-segment connectors. * * Connector labels (a non-empty `` on the connector) render via the * {@link ConnectorTextOverlay} child, centred over the bounding box. * * Line-level shadow (`a:ln/a:outerShdw`) renders as an SVG `feDropShadow` on the * primary stroke; line glow (`a:ln/a:glow`) as a CSS `drop-shadow` filter on the * wrapper. Both reuse the shared visual-effects helpers. */ declare type __VLS_Props_4 = { element: PptxElement; zIndex: number; /** * Native-animation playback state. When an active `p:animClr` colour animation * targets the stroke (`animatesStroke`), the SVG stroke is painted `inherit` so * the wrapper's animated `stroke` keyframes cascade into the line + arrowheads. */ animationState?: ElementAnimationState; /** * Scoped `!important` CSS override for an active font-style emphasis effect * (Bold Flash, Bold Reveal, Underline, Change Font Style/Size), built by the * parent `ElementRenderer` (`buildTextStyleOverrideCss`) so the connector's * own caption animates the same way a shape's text does. */ textStyleOverrideCss?: string; }; /** * TableRenderer - Vue port of the React table renderer * (`viewer/utils/table-render.tsx` + `table-render-data.tsx`). * * Read-only, viewer-first. Renders a PPTX `table` element as a real HTML * `` from the structured {@link PptxTableData} model that * `pptx-viewer-core` produces: * - `` column widths (proportional) * - per-row heights * - per-cell fill / border / alignment / text effects * - rowspan / colspan, skipping cells covered by a merge * - banded-row / header-row / first-last emphasis (theme-aware when * `colorScheme` + `tableStyleMap` props are supplied) * - pattern fills rendered as tiled inline SVG (not a flat colour) * - rich per-run cell text via optional `CellTextRun[]` on cells * - diagonal cell borders via an SVG overlay * * Editing affordances (inline cell text edit, cell selection + Shift+range * highlight, and column/row drag-resize handles) are layered on when an edit * context is provided. */ declare type __VLS_Props_5 = { element: PptxElement; /** Accepted for parity with `ElementRenderer`; unused (no image fills yet). */ mediaDataUrls?: Map; zIndex: number; /** * Whether this table is in an interactive context (main editable canvas). * When false (e.g. in a slide thumbnail), resize handles and cell editing * are disabled regardless of the injected editing context. */ interactive?: boolean; /** Emit the data-pptx-element marker even when not interactive (template layer). */ marked?: boolean; /** True only on the live presentation stage; see `hitTargetStyle`. */ presenting?: boolean; /** * PPTX theme colour scheme from the active presentation theme. * When supplied, band / header emphasis colours are resolved against * the real scheme instead of using hardcoded fallback colours. */ colorScheme?: PptxThemeColorScheme; /** * Parsed table style map (from `ppt/tableStyles.xml`). * Enables accurate banding / header style lookups by table style GUID. */ tableStyleMap?: ParsedTableStyleMap; /** * Scoped `!important` CSS override for an active font-style emphasis * effect (Bold Flash, Bold Reveal, Underline, Change Font Style/Size), * built by the parent `ElementRenderer` (`buildTextStyleOverrideCss`) so * a table cell animates the same way a shape's text does. */ textStyleOverrideCss?: string; }; /** * ChartRenderer: a chart element as inline SVG. * * EVERY chart kind is projected from the framework-agnostic `buildChartViewModel` * engine in `pptx-viewer-shared` through `ChartViewModelSvg`. This component * decides nothing about geometry; it resolves the palette (via * `buildVueChartViewModel`), applies any staged animation reveal, and asks * shared which aspect-ratio policy the kind wants. All kinds render through * this single shared engine (no bespoke per-kind Vue components), so * `data-chart-part` mark selection and the value maths stay identical across * every chart kind and every binding. */ declare type __VLS_Props_6 = { element: PptxElement; zIndex: number; mediaDataUrls?: Map; /** True only on the primary editable canvas: enables direct chart editing. */ interactive?: boolean; /** Emit the data-pptx-element marker even when not interactive (template layer). */ marked?: boolean; /** True only on the live presentation stage; see `hitTargetStyle`. */ presenting?: boolean; /** * Native-animation playback state. When it carries a staged chart build * (`build.kind === 'chart'`, or the authored-index `chartReveal`) the chart * reveals its series / categories / cells progressively via the shared * `resolveRevealedChartData`. */ animationState?: ElementAnimationState; /** * Scoped `!important` CSS override for an active font-style emphasis effect * (Bold Flash, Bold Reveal, Underline, Change Font Style/Size), built by the * parent `ElementRenderer` (`buildTextStyleOverrideCss`) so a chart * title/label/legend animates the same way a shape's text does. */ textStyleOverrideCss?: string; }; /** * SmartArtRenderer - Vue port of the React SmartArt renderer * (`viewer/utils/smartart*.tsx`). * * Data path: this component renders from the **pre-computed drawing shapes** * (`smartArtData.drawingShapes`) extracted by the core engine from * `ppt/diagrams/drawing*.xml`, mirroring React's `smartart-drawing.tsx`. * That is the path React prefers when drawing shapes are present, and it * avoids reimplementing the ~2800 LOC of layout math in the * `smartart-cycle/process/hierarchy/...` family. * * Fallbacks (mirroring `renderSmartArtElement`'s early returns): * - No `smartArtData` or zero nodes → a small "SmartArt" placeholder. * - Nodes present but no drawing shapes → a simple stacked block list of the * node text (the common-case fallback; the full per-family layout renderers * are out of scope per the porting brief). * * The whole graphic is wrapped in chrome (background / outline) when present. */ declare type __VLS_Props_7 = { element: PptxElement; mediaDataUrls?: Map; zIndex: number; /** * True only for the main editable canvas instance. The `data-testid` layout * hooks are emitted solely when interactive so the identical mini-renders in * the thumbnail rail / slide sorter / presenter don't duplicate the id and * break single-element test locators. */ interactive?: boolean; /** Emit the data-pptx-element marker even when not interactive (template layer). */ marked?: boolean; /** True only on the live presentation stage; see `hitTargetStyle`. */ presenting?: boolean; /** * Native-animation playback state. A staged diagram build * (`build.kind === 'diagram'`) reveals the leading nodes / drawing shapes for * the current progress; absent or non-diagram state renders every node. */ animationState?: ElementAnimationState; /** * Scoped `!important` CSS override for an active font-style emphasis effect * (Bold Flash, Bold Reveal, Underline, Change Font Style/Size), built by the * parent `ElementRenderer` (`buildTextStyleOverrideCss`) so a SmartArt node * caption animates the same way a shape's text does. */ textStyleOverrideCss?: string; }; /** * InkRenderer: Vue port of the React `renderInk` (in `InkGroupRenderers.tsx`), * viewer-first subset. * * Renders freehand ink strokes (`InkPptxElement.inkPaths`) as inline SVG * `` elements inside the element's bounding box, with per-stroke colour, * width, and opacity resolved from the parallel `inkColors`/`inkWidths`/ * `inkOpacities` arrays. * * The per-stroke view model (path vs pressure circles vs tilt-driven nib * marks) is the shared `buildInkGroupStrokes` decision function, the same one * `ContentPartRenderer.vue` uses for a loaded `p:contentPart`: pressure comes * from `inkPointPressures` (or a legacy per-point `inkWidths` array), tilt * from `inkPointTiltX`/`inkPointTiltY`. Strokes without either degrade to a * plain constant-width ``. * * Presentation mode progressively replays constant-width paths using the * shared dash-offset timing model. Pressure circles and nib marks remain * static because SVG dash replay only applies to paths. */ declare type __VLS_Props_8 = { element: PptxElement; mediaDataUrls?: Map; zIndex: number; replay?: boolean; /** True only on the main editable canvas; see `hitTargetStyle`. */ interactive?: boolean; /** True only on the live presentation stage; see `hitTargetStyle`. */ presenting?: boolean; }; /** * OleRenderer - Vue port of the React `renderOleElement` * (in `InkGroupRenderers.tsx`), viewer-first subset. * * Renders an embedded OLE object (`OlePptxElement`). When a decoded preview * image is present (`previewImageData`) it is shown with a small type badge * overlay; otherwise a type-specific icon + label placeholder box is drawn, * mirroring the React fallback. * * The OLE-type resolution (icon / colour / label) uses the shared * `resolveOleType` / `getOleIconShapes` helpers so the branding matches the * React renderer and cannot drift from it. Editing the embedded object in place * is not possible (a browser cannot run the native app that owns it); the * action bar below still offers Download and, for browser-openable types, * Open in a new tab, when core extracted an embedded payload. The object's * Object Name (`oleName`) IS editable, via `OlePropertiesPanel` in the * inspector; `displayName` / `ariaLabel` below already read it through the * shared `getOleDisplayName` / `getOleAriaLabel` helpers. */ declare type __VLS_Props_9 = { element: PptxElement; mediaDataUrls?: Map; zIndex: number; /** True only on the main editable canvas; see `hitTargetStyle`. */ interactive?: boolean; /** True only on the live presentation stage; see `hitTargetStyle`. */ presenting?: boolean; }; declare type __VLS_Slots = {} & { default?: (props: typeof __VLS_16) => any; }; declare type __VLS_Slots_2 = {} & { default?: (props: typeof __VLS_11) => any; }; declare type __VLS_WithSlots = T & { new (): { $slots: S; }; }; declare type __VLS_WithSlots_2 = T & { new (): { $slots: S; }; }; /** * Optional hook point for hosts that want to wire a real sign-in flow into * File > Account. Disabled by default: the Account page renders nothing * extra unless a host explicitly opts in by passing `enabled: true`. * See docs/guide for wiring instructions. */ declare interface AccountAuthConfig { enabled: boolean; onSignIn: () => void; signedInUser?: { name: string; email?: string; avatarUrl?: string; }; } /** * Polar-style adjustment handle (`a:ahPolar`) on a custom geometry. * * Drives a guide via radial distance and angle rather than XY coordinates. * * @example * ```ts * const handle: AdjustHandlePolar = { * gdRefR: "adj1", * gdRefAng: "adj2", * posX: "wd2", * posY: "hd2", * }; * // => satisfies AdjustHandlePolar * ``` */ declare interface AdjustHandlePolar { /** Guide reference for the radial distance (`@_gdRefR`). */ gdRefR?: string; /** Guide reference for the angle (`@_gdRefAng`). */ gdRefAng?: string; /** Minimum radial value (`@_minR`). */ minR?: string; /** Maximum radial value (`@_maxR`). */ maxR?: string; /** Minimum angle (`@_minAng`). */ minAng?: string; /** Maximum angle (`@_maxAng`). */ maxAng?: string; /** Handle position X from `a:pos/@_x`. */ posX?: string; /** Handle position Y from `a:pos/@_y`. */ posY?: string; } /** * XY-style adjustment handle (`a:ahXY`) on a custom geometry. * * Allows interactive editing of one or two guide values constrained to a * rectangular range. Coordinates are formula references (e.g. `"adj1"`, * `"w/2"`, `"0"`) preserved verbatim so they can re-emit unchanged. * * @example * ```ts * const handle: AdjustHandleXY = { * gdRefX: "adj1", * minX: "0", * maxX: "w", * posX: "adj1", * posY: "h/2", * }; * // => satisfies AdjustHandleXY * ``` */ declare interface AdjustHandleXY { /** Guide reference for the X axis (`@_gdRefX`). */ gdRefX?: string; /** Guide reference for the Y axis (`@_gdRefY`). */ gdRefY?: string; /** Minimum X value, as a formula reference (`@_minX`). */ minX?: string; /** Maximum X value (`@_maxX`). */ maxX?: string; /** Minimum Y value (`@_minY`). */ minY?: string; /** Maximum Y value (`@_maxY`). */ maxY?: string; /** Handle position X (formula or literal) from `a:pos/@_x`. */ posX?: string; /** Handle position Y from `a:pos/@_y`. */ posY?: string; } /** * Live values emitted while (and after) a shape-adjustment gesture. * * A MAP, not one number: a preset has one handle per `a:avLst` guide and a * callout's single diamond drives two of them at once, so a payload carrying * only `value` could describe neither. It also carries the element's other * adjustments forward, because the store writes `shapeAdjustments` whole. */ declare interface AdjustPayload { id: string; adjustments: Record; } /** Host-tunable options for how AI edits are animated on the canvas. */ declare interface AiChangeAnimationConfig { /** Master switch. Default true. */ enabled?: boolean; /** How long the motion + glow plays, in ms. Default 900. */ durationMs?: number; /** Draw the pulsing glow highlight on changed elements. Default true. */ glow?: boolean; /** Glide old->new bounds and cross-fade colours. Default true. */ tween?: boolean; /** Accent colour (any CSS colour) for the glow/ghosts. Default a blue. */ color?: string; } /** * The bucket a ribbon gallery click targets. Widens the three preset buckets * with `motionPath` so a binding's single "apply animation" callback can carry * a motion-path preset id too, instead of every binding growing a second * callback threaded through the same six components. */ declare type AnimationApplyGroup = 'entrance' | 'emphasis' | 'exit' | 'motionPath'; /** * Structured representation of a single OOXML animation condition * from `p:cond` elements inside `p:stCondLst` or `p:endCondLst`. * * Conditions control when an animation starts or ends, and can reference * events, time delays, and target time node IDs. * * @example * ```ts * const cond: AnimationCondition = { * event: "onClick", * delay: 0, * targetShapeId: "shape_5", * }; * ``` */ declare interface AnimationCondition { /** Event that triggers the condition. */ event?: AnimationConditionEvent; /** * The media element/bookmark this condition fires for, when * {@link event} is `onMediaBookmark`. See {@link PptxMediaBookmarkTarget}. */ bookmarkTarget?: PptxMediaBookmarkTarget; /** Delay in milliseconds (from `@_delay`). "indefinite" is represented as -1. */ delay?: number; /** Target time node ID reference (from `@_tn`). */ targetTimeNodeId?: number; /** Target shape ID from `p:tgtEl/p:spTgt/@spid`. */ targetShapeId?: string; /** Whether the condition targets a slide (from `p:tgtEl/p:sldTgt`). */ targetSlide?: boolean; /** Full target choice, including `p:sndTgt` and `p:inkTgt`. */ target?: PptxAnimationTarget; } /** * Event types for animation conditions from `p:cond/@evt`. * * These map directly to OOXML condition event attribute values * (ISO/IEC 29500-1 S19.5.28 CT_TLTimeCondition). */ declare type AnimationConditionEvent = 'onBegin' | 'onEnd' | 'begin' | 'end' | 'onClick' | 'onMouseOver' | 'onMouseOut' | 'onNext' | 'onPrev' | 'onStopAudio' | 'onDblClick' | 'onMediaBookmark'; declare interface AnimationInput { preset: PptxAnimationPreset; trigger?: PptxAnimationTrigger; duration?: number; delay?: number; } /** URL hash that marks the current tab as the audience display. */ export declare const AUDIENCE_HASH = "#pptx-audience"; /** * Structural interface for the lazily-imported Yjs awareness surface. Every * binding's live `y-protocols/awareness` `Awareness` instance satisfies this. */ declare interface AwarenessLike { clientID?: number; setLocalStateField: (field: string, value: unknown) => void; getStates: () => Map>; on: (event: string, cb: () => void) => void; off?: (event: string, cb: () => void) => void; } declare type BackgroundInput = { type: 'solid'; color: string; } | { type: 'gradient'; /** * Slide backgrounds are stored as a ready-made CSS gradient string * (`PptxSlide.backgroundGradient`), so this is a CSS * `linear-gradient()` angle: degrees clockwise from "to top" * (`90` = left to right, `180` = top to bottom). Defaults to `180`. */ angle?: number; stops: Array<{ color: string; position: number; }>; } | { type: 'image'; source: string; }; /** * Every action card the File-tab backstage can show, keyed by the operation it * triggers rather than by its wording. * * The five bindings used to hardcode a title and a body string each, which made * the whole backstage untranslatable and let the copy drift: the same card * carried four different descriptions depending on which binding you opened it * in. Both halves now live here as a dictionary key plus an English fallback, * so a wording change lands everywhere at once and a translator only has to * translate it once. */ declare type BackstageCardId = 'protect' | 'inspect' | 'embedFonts' | 'signatures' | 'versionHistory' | 'saveAsPptx' | 'saveAsPpsx' | 'saveAsPptm' | 'saveAsPpt' | 'pdf' | 'png' | 'video' | 'gif' | 'json' | 'copyImage' | 'print' | 'share'; /** File tab (backstage) customisation. */ declare interface BackstageCustomization { /** Navigation entries (pages) to remove from the File tab. */ hiddenPages?: readonly BackstagePage[]; /** Action cards to remove from the pages that show them. */ hiddenCards?: readonly BackstageCardId[]; } declare type BackstagePage = 'home' | 'new' | 'open' | 'info' | 'save' | 'saveAs' | 'print' | 'share' | 'export' | 'close' | 'account' | 'options'; declare interface BehaviorBase { /** Lower-cased `p:attrNameLst` entries, in document order. */ attrNames: string[]; /** `p:cBhvr/@additive` (`base`, `sum`, `repl`, `mult`, `none`). */ additive?: string; timing: PptxAnimationBehaviorTiming; } /** * 3-D effect properties, text warp (WordArt) presets, and scene/shape bevel * definitions parsed from OOXML `a:sp3d`, `a:scene3d`, and `a:bodyPr/a:prstTxWarp`. * * @module pptx-types/three-d */ /** * Bevel preset type tokens from OOXML `a:bevelT/@prst` / `a:bevelB/@prst`. * * @example * ```ts * const bevel: BevelPresetType = "circle"; * // => "circle" — one of: "circle" | "relaxedInset" | "cross" | "coolSlant" | "angle" | … * ``` */ declare type BevelPresetType = 'circle' | 'relaxedInset' | 'cross' | 'coolSlant' | 'angle' | 'softRound' | 'convex' | 'slope' | 'divot' | 'riblet' | 'hardEdge' | 'artDeco' | 'none'; /** * Converts raw EMU-based drawing guides from the parsed presentation * and the first slide into pixel-based `GuideEntry` objects. */ export declare function buildInitialGuides(presentationGuides: PptxDrawingGuide[] | undefined, firstSlideGuides: PptxDrawingGuide[] | undefined): GuideEntry[]; /** * Structured bullet metadata attached to the first {@link TextSegment} * of each paragraph. * * Describes how the paragraph bullet should render: character bullets * (`char`), auto-numbered lists (`autoNumType`), or picture bullets * (`imageRelId` / `imageDataUrl`). Set `none: true` when `a:buNone` * explicitly suppresses the bullet. * * @example * ```ts * // Simple character bullet: * const bullet: BulletInfo = { char: "•", color: "#333333" }; * * // Auto-numbered list starting at 1: * const numbered: BulletInfo = { * autoNumType: "arabicPeriod", * autoNumStartAt: 1, * }; * // => { char: "•", color: "#333333" } and { autoNumType: "arabicPeriod", autoNumStartAt: 1 } * ``` */ declare interface BulletInfo { /** Bullet character (e.g. "•", "-", "»") from `a:buChar`. */ char?: string; /** Auto-numbering type (e.g. "arabicPeriod", "romanUcPeriod") from `a:buAutoNum`. */ autoNumType?: string; /** Auto-numbering start value. */ autoNumStartAt?: number; /** * Auto-numbering ORDINAL OFFSET: the zero-based distance of this paragraph * within its own numbered list, such that * `autoNumStartAt + paragraphIndex` is the ordinal to render. Despite the * name it is NOT the paragraph's position in the text body; the two agree * only for a list that starts at the first paragraph and is never * interrupted. * * It has to be the offset rather than the raw position because every * consumer that re-derives a marker from `BulletInfo` alone (the renderer's * `resolveParagraphBullet`, the Markdown converter's `resolveListMarker`) * computes `autoNumStartAt + paragraphIndex`. The load path resolves the * real sequence itself, restarting the count after any paragraph that * interrupts the list, and publishes the offset here so those consumers * land on the same number. With the raw position they did not, and BOTH * markers were painted ("3.1. Item"), because the paragraph builder drops * the parsed marker segment only when the two strings agree. * * Runtime-only: derived at parse time and never serialized. OOXML has no * counterpart (`a:buAutoNum` carries only `@type` and `@startAt`), so the * writer neither reads nor emits it. */ paragraphIndex?: number; /** Bullet font family from `a:buFont`. */ fontFamily?: string; /** * PANOSE font-matching hint from `a:buFont/@panose`. `a:buFont` is a * CT_TextFont, the same complex type as `a:latin`/`a:ea`/`a:cs`/`a:sym` * (which carry the equivalent `TextStyle.latinFontPanose` etc.), so a * bullet's own PANOSE/pitch-family/charset decide the fallback glyph * PowerPoint substitutes when the named typeface is missing. */ fontPanose?: string; /** Font pitch-and-family byte from `a:buFont/@pitchFamily`. */ fontPitchFamily?: number; /** Font character-set byte from `a:buFont/@charset`. */ fontCharset?: number; /** Bullet size as percentage of text font size from `a:buSzPct`. */ sizePercent?: number; /** Bullet size in points from `a:buSzPts`. */ sizePts?: number; /** Bullet color as hex string from `a:buClr`. */ color?: string; /** * Raw colour-choice XML captured from `` so that themed bullets * (`a:schemeClr`, `a:sysClr`, `a:prstClr`) round-trip with their original * identity rather than being flattened to `` on save. */ colorXml?: XmlObject; /** * Typed theme colour reference for the bullet colour, set when * {@link colorXml} is a plain `a:schemeClr`. Wins on save, same as * {@link TextStyle.colorRef}. */ colorRef?: PptxThemeColorRef; /** True when `a:buNone` explicitly suppresses bullets. */ none?: boolean; /** Picture bullet: relationship ID from `a:buBlip` → `a:blip[@r:embed]`. */ imageRelId?: string; /** Picture bullet: data URL of the embedded image. */ imageDataUrl?: string; /** * Raw `` XML captured at parse time. Carries the full blipFill * subtree (`a:tile`, `a:stretch`, `a:srcRect`, `a:blip > a:extLst`) so the * writer can emit the complete original definition rather than the bare * `a:blip[@r:embed]` mapping. When set, the writer prefers it over * {@link imageRelId} for emission. */ imageBlipFillXml?: XmlObject; /** When true, `` was specified — inherit the bullet font from * the run text, not from a buFont declaration. */ fontInherit?: boolean; /** When true, `` was specified — inherit the bullet colour from * the run text. */ colorInherit?: boolean; /** When true, `` was specified — inherit the bullet size from * the run text font size. */ sizeInherit?: boolean; /** * True when this bullet resolution came from the paragraph's OWN `a:pPr` * rather than the shape's `a:lstStyle`, an inherited placeholder, or the * master's `a:defPPr` / `p:txStyles`. `resolveParagraphBulletInfo` walks * that cascade and returns the first match, so without this flag a * writer that re-emits every resolved `BulletInfo` in full pins an * inherited bullet (e.g. a master `buFont="Arial"` / `buChar="•"`) onto * every paragraph's own `a:pPr` the moment the slide is rewritten. The * save path only writes the bullet group when this is `true`, mirroring * how `paragraphProperties` gates every other per-paragraph field. */ ownedByParagraph?: boolean; } /** * The right-click menu for the empty slide canvas (no element under the * cursor), as distinct from {@link ./context-menu-commands}'s per-element menu. * * Right-clicking empty canvas used to do nothing at all in every binding: React * and Vue both bailed out early (`getElementIdFromEvent` returns `null`, so the * handler just returns) rather than opening a menu, and the other three never * wired a handler for it either. PowerPoint offers Paste, Layout, Reset, * Format Background and view toggles (Grid and Guides, Ruler) from this menu; * this module is the one list every binding renders instead of five omissions. * * @module render/canvas-context-menu-commands */ /** Every command the empty-canvas context menu can offer, in no particular order. */ declare type CanvasContextMenuCommandId = 'paste' | 'layout' | 'reset-slide' | 'format-background' | 'grid-and-guides' | 'ruler'; /** Canvas dimensions in pixels. */ export declare interface CanvasSize { width: number; height: number; } declare type Catalog = typeof RIBBON_CONTROL_CATALOG; declare type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle'; /** * `animation-timeline-build-descriptors` - staged-build (`p:bldChart` / * `p:bldDgm`) reveal descriptor types, split out of `animation-timeline-types` * to keep that module under the file-size limit. Re-exported from * `animation-timeline-types` so existing imports are unaffected. * * @module render/animation-timeline-build-descriptors */ /** * Normalized staged-reveal mode for a chart graphic frame, derived from the * OOXML `a:bldChart/@bld` (or `p:bldOleChart/@bld`) token: * - `asOne` the whole chart appears at once (`allAtOnce`). * - `bySeries` one data series is revealed per stage (`series`). * - `byCategory` one category is revealed per stage (`category`). * - `byElement` one series/category ELEMENT is revealed per stage * (`seriesElement` / `categoryElement`). */ declare type ChartBuildMode = 'asOne' | 'bySeries' | 'byCategory' | 'byElement'; declare interface ChartInput { series: ChartSeriesInput[]; categories: string[]; /** ChartEx hierarchy levels in leaf-to-root XML order. */ categoryLevels?: string[][]; title?: string; hasLegend?: boolean; legendPosition?: 't' | 'b' | 'l' | 'r' | 'tr'; grouping?: 'clustered' | 'stacked' | 'percentStacked'; /** Bar series direction (`c:barDir`): vertical columns (default) or horizontal bars. */ barDirection?: 'col' | 'bar'; } declare interface ChartOptions extends Partial {} /** * A chart embedded via a ``. * * Chart data is parsed from the related `chartN.xml` / `chartExN.xml` * parts inside the PPTX archive. */ declare interface ChartPptxElement extends PptxElementBase { type: 'chart'; chartData?: PptxChartData; /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */ altText?: string; /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */ title?: string; /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */ extensionXml?: PptxGraphicFrameExtension[]; } export declare const ChartRenderer: typeof __VLS_export_7; /** * Playback-time chart reveal state derived from AUTHORED `p:graphicEl` * indices (see `chart-reveal-descriptor`'s `resolveChartRevealDescriptor`), * rather than from click-count/time progress. Present on * {@link import('./animation-timeline-group').ElementAnimationState.chartReveal} * only when every fired chart-build step for the element carried index data; * a renderer prefers this over the progress-based `build`/`ElementBuildState` * path when present, since it reflects the real authored reveal set (correct * even for a reversed-order or gapped chart build), and falls back to `build` * when absent. */ declare interface ChartRevealDescriptor { /** * Whether the chart's background/axes/gridlines/legend should currently be * visible: always `true` when the chart's `animateBackground` is `false` * ("shown throughout"), otherwise `true` from the first revealed stage * onward. */ background: boolean; /** Whole series revealed by a `bldStep="series"` effect. */ series: ReadonlySet; /** Whole categories revealed by a `bldStep="category"` effect. */ categories: ReadonlySet; /** Individual cells revealed by a `bldStep="seriesEl"`/`"categoryEl"` effect. */ points: readonly ChartRevealPoint[]; } /** * One authored `p:graphicEl` reveal unit resolved onto a chart, per * `TimelineStepGraphicElement`'s "both indices set" case: a single (series, * category) cell revealed by a `bldStep="seriesEl"`/`"categoryEl"` effect. */ declare interface ChartRevealPoint { seriesIdx: number; categoryIdx: number; } declare interface ChartSeriesInput { name: string; values: number[]; color?: string; boxWhiskerOptions?: PptxChartBoxWhiskerOptions; histogramOptions?: PptxChartHistogramOptions; waterfallOptions?: PptxChartWaterfallOptions; regionMapOptions?: PptxChartRegionMapOptions; treemapOptions?: PptxChartTreemapOptions; } /** * Remove stored audience content (cleanup). */ export declare function clearAudienceContent(sessionId?: string): Promise; /** * Who asked for the deck that just finished loading, and what that means for a * room that already holds slides. * * Every binding brackets its content-load with an adoption check: when a load * lands while a collaboration session is up and the shared doc already has * slides, the ROOM wins and the freshly parsed deck is thrown away. That rule * exists for one case only - a late joiner whose bootstrap deck (the blank or * sample deck the host mounted the viewer with) finishes parsing after the * room's real slides arrived, which would otherwise clobber them with nothing * left to repair it, since the doc itself never changed. * * Applied to EVERY load it also swallows the deck a user deliberately opens * during a session. Joining a room and then opening a file left the viewer on * the room's blank starter deck: the file parsed, was committed, and was * immediately overwritten (reproduced in the vanilla demo - a 7-slide deck * opened in a room settled back to the room's 1 slide, and the bigger the file * the longer the window). Opening a file is an act of authorship, so it is * published to the room instead. * * @module render/collaboration-load-origin */ /** * Why a content load ran. * * - `bootstrap`: the deck the host handed the viewer at mount (`source`), or a * session restore. Nobody chose it during the session. * - `user`: opened during the session - File > Open, a recent file, a dropped * file, or a host calling the load API. */ declare type CollabLoadOrigin = 'bootstrap' | 'user'; /** * Real-time collaboration configuration. * * The same shape is accepted by every framework binding. */ export declare interface CollaborationConfig { /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */ roomId: string; /** * WebSocket server URL for the Yjs provider (e.g. "wss://collab.example.com"). * Ignored (may be empty) for `externalSession` or when `transport` is `'webrtc'`. */ serverUrl: string; /** Transport to use. Defaults to `'websocket'`. */ transport?: CollaborationTransport; /** * Use the host's document, awareness and transport instead of creating a * provider. Transport, serverUrl, signaling and authToken are ignored. The * viewer only detaches its listeners and presence on stop; it never destroys * these resources. Keep this object stable and report readiness via subscribe. */ externalSession?: ExternalCollaborationSession; /** * WebRTC signaling server URLs (only used when `transport` is `'webrtc'`). * Defaults to y-webrtc's built-in public signaling list. Same-browser tabs * sync via BroadcastChannel regardless of signaling availability. */ signaling?: string[]; /** Display name for the local user. */ userName: string; /** Avatar URL for the local user (optional). */ userAvatar?: string; /** Hex colour for the local user's cursor/presence indicator. */ userColor?: string; /** Optional authentication token sent with the WebSocket handshake. */ authToken?: string; /** Role in the session; defaults to `'collaborator'`. */ role?: CollaborationRole; /** * Whether this client created the room or joined an existing room. Providers * do not use this value, but hosts can use it to avoid publishing local file * bytes when handling a join request. Omitted values retain the legacy * create-session behaviour. */ sessionIntent?: CollaborationSessionIntent; /** * Elected-writer write-back callback (Area 3 of the C3 hardening plan). * * When the local user has `role: 'owner'`, the binding debounces changes and * serializes the current Y.Doc state to a PPTX byte array, then calls this * callback so the host can persist the snapshot. Only one writer (the owner) * does this; other collaborators never trigger write-back, eliminating the * last-save-wins problem. */ onWriteBack?: (bytes: Uint8Array) => void; /** * Debounce delay (ms) between the last Y.Doc change and the write-back * invocation. Defaults to 5000 ms. Set to 0 to write back on every change * (not recommended for large documents). */ writeBackDebounceMs?: number; } export declare const CollaborationCursors: typeof __VLS_export_15; declare interface CollaborationInlineSnapshot extends CollaborationTextSnapshot { readonly inline: InlineTextEditSnapshot; } declare interface CollaborationLivePatcher { /** Bind a mounted native editor; its handle must be disposed on unmount. */ beginTextEdit?: (slideId: string | undefined, elementId: string, onChange?: () => void, ownsModel?: (element: PptxElement) => boolean) => CollaborationTextTarget | undefined; /** Attach a live doc (or `null` to go dormant). Pending patches are dropped. */ configure: (doc: YDocLike | null, factories: YjsFactories | null, /** Publish synchronously when the host may revoke write readiness at any time. */ immediate?: boolean) => void; /** True when a doc + factories are attached, i.e. patches will be written. */ isActive: () => boolean; /** Queue interim geometry for an element. */ patchGeometry: (slideId: string | undefined, elementId: string, geometry: LiveGeometryPatch) => void; /** Queue interim text for an element (remapped over `source`'s segments). */ patchText: (slideId: string | undefined, elementId: string, text: string, source?: LiveTextSource) => void; /** Write everything queued right now (call on gesture end / edit commit). */ flush: () => void; /** Drop pending work, cancel timers and detach the doc. */ dispose: () => void; } /** Collaboration role within a session. */ export declare type CollaborationRole = 'owner' | 'collaborator' | 'viewer'; /** How the local user entered a collaboration session. */ declare type CollaborationSessionIntent = 'create' | 'join'; export declare interface CollaborationShellState { canEdit: boolean; status: ConnectionStatus; remoteUsers: readonly SanitizedPresence[]; connectedCount: number; } export declare const CollaborationStatusIndicator: typeof __VLS_export_18; declare interface CollaborationTextSession { applyLocalDelta: (delta: readonly DeltaOp[], edit?: LocalTextEdit) => boolean; readMerged: () => CollaborationTextSnapshot | undefined; adoptMerged: (snapshot: CollaborationTextSnapshot) => boolean; /** Capture an offset in the last painted/local draft, not the newer remote string. */ bookmark: (index: number, association: number) => () => number | null; dispose: () => void; } /** Opaque acknowledgement identity for an exact remote snapshot painted by an adapter. */ declare interface CollaborationTextSnapshot { readonly delta: readonly DeltaOp[]; } /** A mounted editor owns this handle, never the document or its provider. */ declare interface CollaborationTextTarget extends CollaborationTextSession { readMerged: () => CollaborationInlineSnapshot | undefined; /** A bookmark follows character identity rather than a mutable numeric offset. */ bookmark: (index: number, association: number) => () => number | null; } /** * Collaboration transport. * * - `'websocket'` (default): y-websocket against `serverUrl`. * - `'webrtc'`: y-webrtc peer-to-peer; needs no document server. Peers meet * through the `signaling` servers (WebRTC signaling only, no document data) * and same-browser tabs additionally sync via BroadcastChannel even without * any signaling server, which makes this mode usable from static hosting. */ declare type CollaborationTransport = 'websocket' | 'webrtc'; /** * Collect all unique image archive paths across all slides that need * to be resolved to displayable URLs (Blob URLs). * * This covers: * - Picture elements (`imageData`, `svgData`) * - Media poster frames (`posterFrameData`) * * Returns the set of unique archive paths, plus a list of element/field * references that need to be updated once each path resolves. */ export declare function collectImagePaths(slides: PptxSlide[]): { paths: Set; refs: ImagePathElement[]; }; /** * Recursively walks an element tree and pushes every media element * into the supplied collector array. */ export declare function collectMediaElements(elements: PptxElement[], collector: MediaPptxElement[]): void; /** * Connection site (`a:cxn`) on a custom geometry. * * Defines a point on a custom shape that connectors may snap to. * * @example * ```ts * const cxn: ConnectionSite = { ang: "0", posX: "0", posY: "hd2" }; * // => satisfies ConnectionSite * ``` */ declare interface ConnectionSite { /** Approach angle (`@_ang`) — formula or literal degree-1/60000 value. */ ang?: string; /** Site position X from `a:pos/@_x`. */ posX?: string; /** Site position Y from `a:pos/@_y`. */ posY?: string; } /** Connection lifecycle states for the Yjs WebSocket provider. */ export declare type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error'; /** * Arrow head types for connector start/end. * * Maps to `a:headEnd/@type` and `a:tailEnd/@type` in OOXML. * * @example * ```ts * const arrow: ConnectorArrowType = "triangle"; * // => "triangle" — one of: none | triangle | stealth | diamond | oval | arrow * ``` */ declare type ConnectorArrowType = 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow'; /** * Connector connection point reference — links a connector endpoint to a * specific shape on the slide. * * When both `shapeId` and `connectionSiteIndex` are set, the connector * end snaps to that shapes’s connection site and “follows” the shape when * it is moved. * * @example * ```ts * const start: ConnectorConnectionPoint = { * shapeId: "shape_1", * connectionSiteIndex: 2, * }; * // => { shapeId: "shape_1", connectionSiteIndex: 2 } satisfies ConnectorConnectionPoint * ``` */ declare interface ConnectorConnectionPoint { /** ID of the shape this connector endpoint is attached to. */ shapeId?: string; /** Connection site index on the target shape (0-based). */ connectionSiteIndex?: number; } declare interface ConnectorOptions extends Partial { type?: 'straight' | 'bent' | 'curved'; stroke?: StrokeInput; startArrow?: ConnectorArrowType; endArrow?: ConnectorArrowType; from?: { elementId: string; site: number; }; to?: { elementId: string; site: number; }; } /** * A connector (straight, bent, or curved line between shapes). * * Connector endpoints can snap to specific shapes via * `shapeStyle.connectorStartConnection` / `connectorEndConnection`. * * @example * ```ts * const line: ConnectorPptxElement = { * type: "connector", * id: "cxn_1", x: 100, y: 100, width: 200, height: 0, * shapeStyle: { * strokeColor: "#333", * connectorEndArrow: "triangle", * }, * }; * // => satisfies ConnectorPptxElement * ``` */ declare interface ConnectorPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxNonVisualDescription { type: 'connector'; } export declare const ConnectorRenderer: typeof __VLS_export_5; /** * A single ink stroke within a {@link ContentPartPptxElement}. */ declare interface ContentPartInkStroke { path: string; color: string; width: number; opacity: number; /** * Per-point pressure values (0-1) for this stroke. * * When present, the renderer uses these values to produce * variable-width strokes that reflect stylus/pen pressure. */ pressures?: number[]; /** * Per-point pen-tilt lean direction (radians), decoded from the source * InkML's `OTx`/`OTy` tilt-offset channels or its `AZIMUTH` channel. * * When present (paired with {@link tiltMagnitudes}), the renderer widens * each point perpendicular to the lean direction, approximating a * calligraphic (chisel-tip) nib. Absent when the source declared no tilt * channel, in which case rendering is unaffected. */ tiltAngles?: number[]; /** * Per-point pen-tilt strength (0 upright, 1 maximally leaned), paired with * {@link tiltAngles}. */ tiltMagnitudes?: number[]; /** * Which InkML channel pair {@link tiltAngles}/{@link tiltMagnitudes} were * decoded from: `'azimuthAltitude'` when the source declared `AZIMUTH` * (optionally paired with `ALTITUDE`); omitted (implying `OTx`/`OTy`, i.e. * `'vector'`) otherwise, including for tilt this library itself captured * from the Draw tool's `PointerEvent.tiltX`/`tiltY`. * * A save that has to rewrite this content part's InkML (see * `inkml-content-part-writer.ts`) uses this to re-declare the SAME channel * pair the file already used, rather than always converting to `OTx`/`OTy`; * the rendered lean is identical either way; only the written channel * NAMES differ. */ tiltEncoding?: 'vector' | 'azimuthAltitude'; /** * Per-point timestamps (milliseconds), decoded from the source InkML * trace's `T` channel when it declared one. * * Absent for the overwhelming majority of real decks: PowerPoint's own * SaveAs output declares only `X`/`Y` and has no per-point time channel at * all (see `contentpart-real-ink-roundtrip.test.ts`'s fixture), so this is * populated only for InkML sources that genuinely author one (a captured * digitizer session, OneNote, a Surface Hub export). When present, ink * replay ("watch the ink get drawn") uses each stroke's own first/last * timestamp to time its reveal instead of the fixed per-stroke cascade; see * `pptx-viewer-shared`'s `render/ink-replay-timeline.ts`. */ pointTimestamps?: number[]; } /** * A content-part element wrapped in `mc:AlternateContent`. * * Typically contains ink strokes from modern PowerPoint pen/highlighter. */ declare interface ContentPartPptxElement extends PptxElementBase { type: 'contentPart'; /** Ink strokes contained in this content part. */ inkStrokes?: ContentPartInkStroke[]; /** Package path of the related InkML part. */ inkPartPath?: string; /** Parsed InkML root retained for unknown-node preservation on dirty save. */ inkPartRawXml?: XmlObject; } /** Every command a canvas context menu can offer, in no particular order. */ declare type ContextMenuCommandId = 'copy' | 'cut' | 'paste' | 'duplicate' | 'edit-text' | 'edit-points' | 'bring-forward' | 'send-backward' | 'bring-front' | 'send-back' | 'ai-ask' | 'ai-fix' | 'comment' | 'hyperlink' | 'table-insert-row-above' | 'table-insert-row-below' | 'table-delete-row' | 'table-insert-col-left' | 'table-insert-col-right' | 'table-delete-col' | 'table-merge-selected' | 'table-merge-right' | 'table-merge-down' | 'table-split' | 'group' | 'ungroup' | 'crop' | MergeShapesCommandId | 'save-as-picture' | 'edit-alt-text' | 'size-and-position' | 'format-shape' | 'delete'; /** Right-click menu customisation. */ declare interface ContextMenuCustomization { /** Entries to remove from the element (right-click on a shape) menu. */ hiddenElementCommands?: readonly ContextMenuCommandId[]; /** Entries to remove from the empty-canvas menu. */ hiddenCanvasCommands?: readonly CanvasContextMenuCommandId[]; /** * Entries to remove from the Edit Points menu (right-click a vertex or a * segment while editing a shape's points). */ hiddenEditPointsCommands?: readonly EditPointsCommandId[]; /** Remove the element context menu entirely. */ disableElementMenu?: boolean; /** Remove the empty-canvas context menu entirely. */ disableCanvasMenu?: boolean; } /** * A single sub-path in a custom geometry definition (maps to one `a:path`). * * @example * ```ts * const path: CustomGeometryPath = { * width: 100, * height: 100, * segments: [ * { type: "moveTo", pt: { x: 0, y: 0 } }, * { type: "lineTo", pt: { x: 100, y: 100 } }, * ], * }; * // => satisfies CustomGeometryPath * ``` */ declare interface CustomGeometryPath { /** Coordinate-space width for this sub-path. */ width: number; /** Coordinate-space height for this sub-path. */ height: number; /** Ordered list of drawing segments. */ segments: CustomGeometrySegment[]; /** Path fill mode (`a:path/@fill`): norm, lighten, lightenLess, darken, darkenLess, none. */ fillMode?: 'norm' | 'lighten' | 'lightenLess' | 'darken' | 'darkenLess' | 'none'; /** Whether the path is stroked (`a:path/@stroke`). */ stroke?: boolean; /** 3D extrusion compatibility (`a:path/@extrusionOk`). */ extrusionOk?: boolean; } /** * A single point in a custom geometry path. * * @example * ```ts * const pt: CustomGeometryPoint = { x: 100, y: 200 }; * // => satisfies CustomGeometryPoint * ``` */ declare interface CustomGeometryPoint { x: number; y: number; } /** * Auxiliary raw XML preserved from `a:custGeom` for round-trip serialization. * These are stored opaquely so adjustment guides, handles, connection sites, * and the text rectangle are not lost when a custGeom is edited and saved. */ declare interface CustomGeometryRawData { /** Raw `a:avLst` XML content (adjustment value list). */ avLstXml?: unknown; /** Raw `a:gdLst` XML content (guide list). */ gdLstXml?: unknown; /** Raw `a:ahLst` XML content (adjustment handles). */ ahLstXml?: unknown; /** Raw `a:cxnLst` XML content (connection sites). */ cxnLstXml?: unknown; /** Raw `a:rect` XML content (text rectangle). */ rectXml?: unknown; /** * Raw `a:pathLst` XML content: every `a:path`'s formula-bearing `a:pt` * x/y attributes, `a:arcTo` params, `a:close`, and per-path `@w`/`@h`/ * `@fill`/`@stroke`/`@extrusionOk`, preserved verbatim (not the * parse-time-resolved numbers in `customGeometryPaths`). Lets a live * `shapeAdjustments` drag re-evaluate the outline against the CURRENT * guide values instead of the ones baked in at parse time; see * `geometry/custom-geometry-live-eval.ts`. */ pathLstXml?: unknown; } /** * A segment within a custom geometry path. * * Discriminated union over `type` — can be a moveTo, lineTo, * cubic Bézier, quadratic Bézier, or close command. * * @example * ```ts * const segments: CustomGeometrySegment[] = [ * { type: "moveTo", pt: { x: 0, y: 0 } }, * { type: "lineTo", pt: { x: 100, y: 0 } }, * { type: "lineTo", pt: { x: 100, y: 100 } }, * { type: "close" }, * ]; * // => satisfies CustomGeometrySegment[] * ``` */ declare type CustomGeometrySegment = { type: 'moveTo'; pt: CustomGeometryPoint; } | { type: 'lineTo'; pt: CustomGeometryPoint; } | { type: 'cubicBezTo'; pts: [CustomGeometryPoint, CustomGeometryPoint, CustomGeometryPoint]; } | { type: 'quadBezTo'; pts: [CustomGeometryPoint, CustomGeometryPoint]; } | { type: 'arcTo'; /** Horizontal radius of the ellipse. */ wR: number; /** Vertical radius of the ellipse. */ hR: number; /** Start angle in 60000ths of a degree. */ stAng: number; /** Sweep angle in 60000ths of a degree. */ swAng: number; } | { type: 'close'; }; /** * Typed text rectangle (`a:rect`) on a custom geometry. * * Each edge is the formula or literal string preserved from the source XML * (`"l"`, `"t"`, `"r"`, `"b"`, or any guide name / formula). */ declare interface CustomGeometryTextRect { /** Left edge formula reference (`@_l`). */ l?: string; /** Top edge (`@_t`). */ t?: string; /** Right edge (`@_r`). */ r?: string; /** Bottom edge (`@_b`). */ b?: string; } /** * What the Protect-Presentation UI knows at save time. `password` is the secret * the dialog captured; `passwordProtected` is the separate "is protected" flag * some bindings track for the badge. When the flag is explicitly `false` the * deck saves in the clear even if a stale secret is still around, so removing * a password can never leave the next save encrypted. * * `purpose` defaults to `'user-file'`; see {@link DeckSavePurpose} for why * `'recovery-snapshot'` overrides the password. */ declare interface DeckSaveIntent { password?: string | null; passwordProtected?: boolean; purpose?: DeckSavePurpose; } /** * Why the deck is being serialised, which is a separate question from whether * the user protected it. * * - `user-file` (the default): the bytes leave the viewer as a file. Save, * Save As, Export, the host-facing `getContent()`. Protection applies. * - `recovery-snapshot`: the bytes exist only so the viewer can read them back. * The autosave crash-recovery snapshot in IndexedDB, and the internal * re-serialise-then-reload cycle behind "apply theme". Protection does NOT * apply: these are always written in the clear. * * ## Why a recovery snapshot must stay plaintext * * Nothing that reads a snapshot back has a password to give it. * `readBackstageRecentFile`, `restoreSessionDeck` and the Version History * panel's Restore all hand `record.data` straight to `PptxHandler.load()` with * no `password` option, and an encrypted package refuses to open without one * (`EncryptedFileError`). So an encrypted snapshot is not an inconvenience, it * is unreadable: the moment the user turns on protection their crash-recovery * data is silently destroyed, which is the exact opposite of what autosave is * for. * * Encrypting it "properly" is not available either. Decrypting on recovery * means the key has to outlive the crash the snapshot exists for, so it would * have to sit in the same IndexedDB / localStorage as the snapshot itself, * next to the ciphertext it unlocks. That is not a security boundary, it is * theatre. Prompting the user instead only works if they remember the password * of a deck they lost, which is precisely the moment they will not. * * ## The tradeoff this accepts (deliberately, not by omission) * * A password-protected deck DOES leave its content in cleartext at rest in the * origin's IndexedDB. Anyone with the browser profile, or any script running on * the origin, can read it. What limits the exposure: snapshots are scoped to * the origin and profile, aged out by the store, and clearable from * File > Account > Storage & Privacy (`clearLocalStorageData`). A user who * cannot accept plaintext at rest should switch AutoSave off, which stops the * snapshot being written at all. * * The rejected alternative was "skip autosave entirely while a password is * set". It removes the plaintext, but it also removes crash recovery without * telling anyone, so a crash loses the whole editing session. Losing data * quietly is the failure mode we are fixing, not a fix for it. */ declare type DeckSavePurpose = 'user-file' | 'recovery-snapshot'; export declare const DEFAULT_CANVAS_HEIGHT = 720; export declare const DEFAULT_CANVAS_WIDTH = 1280; export declare const DEFAULT_FILL_COLOR = "#3b82f6"; export declare const DEFAULT_STROKE_COLOR = "#1f2937"; export declare const DEFAULT_TEXT_COLOR = "#111827"; declare type DefaultExportFormat = 'pptx' | 'pdf' | 'png'; /** * collaboration-text-codec.ts: TextSegment[] <-> Y.Text delta codec used by the * collaboration sync layer. Split out of collaboration-sync.ts to keep both * modules focused. * * Exports: * - DeltaOp / YTextLike: structural Yjs text interfaces (no yjs import) * - encodeTextBody: write TextSegment[] into a live YTextLike * - encodeSegmentsToDelta: pure simulation of the delta Y.Text would produce * - decodeDelta / decodeTextBody: delta -> TextSegment[] * - isYTextLike: runtime guard */ declare interface DeltaOp { insert?: unknown; attributes?: Record; } /** * Normalized staged-reveal mode for a SmartArt diagram, derived from the OOXML * `a:bldDgm/@bld` or `p:bldDgm/@bld` token: * - `asOne` the whole diagram appears at once (`whole` / `allAtOnce`). * - `byOne` one node is revealed per stage (`one`, and the assorted * `depthBy*` / `breadthBy*` / directional traversals). * - `byLvl` levels are revealed one element at a time (`lvlOne`). * - `byLvlAtOnce` a whole level is revealed per stage (`lvlAtOnce`). */ declare type DiagramBuildMode = 'asOne' | 'byOne' | 'byLvl' | 'byLvlAtOnce'; /** * Playback-time SmartArt diagram reveal state derived from AUTHORED * `p:graphicEl/p:dgm/@id` indices (see `diagram-reveal-descriptor`'s * `resolveDiagramRevealDescriptor`), rather than from click-count/time * progress. Present on * {@link import('./animation-timeline-group').ElementAnimationState.diagramReveal} * only when every fired diagram-build step for the element carried * `p:graphicEl` data. A SmartArt renderer prefers this over the * progress-based `build` / {@link ElementBuildState} path when present, since * it reflects the real authored reveal set (correct even for a * reversed-order or by-branch build), and falls back to `build` when absent. */ declare interface DiagramRevealDescriptor { /** * Whether the diagram's background/connector chrome should currently be * visible: `true` once any node-revealing or background-revealing * (`bldStep="bg"`) step has fired. */ background: boolean; /** Data-model point ids (`PptxSmartArtNode.id`) revealed so far. */ nodeIds: ReadonlySet; } declare type DisplayOptimization = 'appearance' | 'compatibility'; /** Active drawing/inking tool. Mirrors React `DrawingTool`. */ export declare type DrawingTool = 'select' | 'pen' | 'highlighter' | 'eraser' | 'freeform'; /** Which of the two behaviours a paragraph asks for. */ declare interface EastAsianBreakOptions { /** `a:pPr/@hangingPunct="1"`. */ hangingPunctuation: boolean; /** `a:pPr/@eaLnBrk="0"`: break between any two East Asian characters. */ breakAnywhere: boolean; } declare interface EditorHistoryResult { /** True when there is at least one snapshot to undo to. */ canUndo: ComputedRef; /** True when there is at least one snapshot to redo to. */ canRedo: ComputedRef; /** * Snapshot the current `slides.value` onto the undo stack and clear the redo * stack. Call this immediately **before** committing a mutating change. */ pushHistory: (label?: string) => void; /** Revert to the previous snapshot, pushing the current state onto redo. */ undo: () => void; /** Re-apply the next snapshot, pushing the current state back onto undo. */ redo: () => void; /** Drop all undo/redo history (e.g. when new content is loaded). */ clearHistory: () => void; /** * Apply a new File > Options > Advanced > "Maximum number of undos" value * at runtime (`resolveHistoryDepth`). Trims the past stack immediately if * the new limit is smaller. */ setMaxDepth: (depth: number) => void; } /** A logical editor command produced by one key press. */ declare type EditorKeyActionName = 'undo' | 'redo' | 'copy' | 'cut' | 'paste' | 'duplicate' | 'delete' | 'selectAll' | 'group' | 'ungroup' | 'nudge' | 'prevSlide' | 'nextSlide' | 'escape' | 'find' | 'findReplace' | 'toggleShortcuts' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'alignJustify' | 'increaseFontSize' | 'decreaseFontSize' | 'copyFormat' | 'pasteFormat' | 'newSlide' | 'hyperlink' | 'clearFormatting' | 'cycleSelectionNext' | 'cycleSelectionPrev' | 'pasteSpecial'; export declare interface EditorOperations { /** Resolved active slide (or `undefined` when the index is out of range). */ activeSlide: ComputedRef; /** Currently-selected element ids (owned internally if not supplied as input). */ selectedElementIds: Ref; /** Append an element to the active slide and select it. */ addElement: (element: PptxElement) => void; /** Shallow-merge `updates` into the element with `elementId` on the active slide. */ updateElement: (elementId: string, updates: Partial) => void; /** Remove an element from the active slide and drop it from the selection. */ removeElement: (elementId: string) => void; /** Patch an element's geometry (x/y/width/height/rotation). */ transformElement: (elementId: string, transform: ElementTransform) => void; /** Alias of {@link transformElement}: mirrors the React "move" semantics. */ moveElement: (elementId: string, transform: ElementTransform) => void; /** * Deep-clone an element (new ids via core `duplicateElement`), offset it * slightly, append it, and select the copy. Returns the new element's id. */ duplicateElement: (elementId: string) => string | undefined; /** Swap an element one step later in z-order (towards the front). */ bringForward: (elementId: string) => void; /** Swap an element one step earlier in z-order (towards the back). */ sendBackward: (elementId: string) => void; /** Move an element in front of every sibling on its layer. */ bringToFront: (elementId: string) => void; /** Move an element behind every sibling on its layer. */ sendToBack: (elementId: string) => void; /** Move an element to an explicit index within the active slide's z-order. */ reorder: (elementId: string, toIndex: number) => void; /** * Update an element's text. For `smartArt` elements a `nodeId` targets a * specific node via core `updateSmartArtNodeText`; for text/shape elements the * `text` field (and every text segment's text) is replaced. */ updateElementText: (elementId: string, text: string, nodeId?: string) => void; } /** Every command the Edit Points right-click menu can offer. */ declare type EditPointsCommandId = 'add-point' | 'delete-point' | 'delete-segment' | 'open-path' | 'close-path' | 'smooth-point' | 'straight-point' | 'corner-point' | 'straight-segment' | 'curved-segment' | 'exit'; /** Typed CT_AlphaOutsetEffect with original XML retained for lossless edits. */ declare interface EffectDagAlphaOutset { kind: 'alphaOutset'; radiusEmu?: number; xml: XmlObject; } declare interface EffectDagBlend { kind: 'blend'; mode: EffectDagBlendMode; container: EffectDagContainer; } declare type EffectDagBlendMode = 'darken' | 'lighten' | 'mult' | 'over' | 'screen'; /** Typed CT_BlurEffect with its original payload retained for lossless edits. */ declare interface EffectDagBlur { kind: 'blur'; radiusEmu?: number; grow?: boolean; xml: XmlObject; } declare interface EffectDagContainer { kind: 'cont'; type: EffectDagContainerType; name?: string; children: EffectDagNode[]; } declare type EffectDagContainerType = 'sib' | 'tree'; declare type EffectDagNode = EffectDagContainer | EffectDagBlend | EffectDagXfrm | EffectDagRelOff | EffectDagBlur | EffectDagAlphaOutset | EffectDagPresetShadow | EffectDagRawLeaf; /** Typed CT_PresetShadowEffect with colour and extension XML retained verbatim. */ declare interface EffectDagPresetShadow { kind: 'prstShdw'; preset?: `shdw${number}`; distanceEmu?: number; direction?: number; xml: XmlObject; } declare interface EffectDagRawLeaf { kind: 'raw'; tag: string; xml: Record; } declare interface EffectDagRelOff { kind: 'relOff'; tx?: number; ty?: number; } declare interface EffectDagXfrm { kind: 'xfrmEffect'; sx?: number; sy?: number; kx?: number; ky?: number; tx?: number; ty?: number; } /** Snapshot of a single element's animation state at a point in the timeline. */ declare interface ElementAnimationState { /** Whether the element should be visible. */ visible: boolean; /** CSS animation shorthand to apply (undefined = no active animation). */ cssAnimation: string | undefined; /** * Staged-build reveal state, present only when the active animation builds a * chart or SmartArt diagram in stages (`p:bldChart` / `p:bldDgm`) rather than * revealing the whole element at once. A staged renderer multiplies * `build.progress` (0..1) by its own series / category / level COUNT to * decide how many stages are revealed at the current playback time; see * {@link import('./animation-build').revealedStageCount}. Absent for ordinary * whole-element entrances, so existing renderers are unaffected. */ build?: ElementBuildState; /** * Authored-index chart reveal state (see {@link ChartRevealDescriptor}), * present only when every fired chart-build step for this element carried * `p:graphicEl` index data. A chart renderer prefers this over `build` when * present; `chart-build`'s `resolveRevealedChartData` picks between the two. */ chartReveal?: { mode: ChartBuildMode; descriptor: ChartRevealDescriptor; }; /** * Authored-index SmartArt diagram reveal state (see * {@link DiagramRevealDescriptor}), present only when every fired * diagram-build step for this element carried `p:graphicEl` node-id data. * `diagram-build`'s `resolveRevealedSmartArtNodes` prefers this over `build` * when present. */ diagramReveal?: { mode: DiagramBuildMode; descriptor: DiagramRevealDescriptor; }; /** * True when an active `p:animClr` color animation targets this shape's fill. * A vector renderer should then paint the fill with `fill: inherit` so the * wrapper-level colour keyframes cascade to the SVG path. Absent/false means * no active fill-colour animation. */ animatesFill?: boolean; /** * True when an active `p:animClr` color animation targets this shape's * stroke. A vector renderer should then paint the stroke with * `stroke: inherit`. Absent/false means no active stroke-colour animation. */ animatesStroke?: boolean; /** * Active discrete font-style / colour / size override (see * {@link import('./animation-timeline-step').TimelineStep.textStyle}) a * font-style emphasis effect currently applies to this element's text, * OVERRIDING the runs' own inline bold/italic/underline/size/colour. * `animation-playback-engine.ts` writes this on step start and again on * cleanup (held in full when the effect's `p:cTn/@fill` holds its end * state, otherwise reverted); a text renderer maps it onto its run markup * via `buildTextStyleOverrideCss` (`animation-text-style-css.ts`). Absent * means no font-style emphasis effect is currently active on this element. */ textStyle?: TextStyleAnimationDescriptor; } /** * Playback-time staged-build state surfaced on * {@link import('./animation-timeline-group').ElementAnimationState}. * `progress` is the 0..1 fraction of the build revealed at the current * playback time; a consumer maps it to its own item COUNT (see * `revealedStageCount`). */ declare type ElementBuildState = { kind: 'chart'; mode: ChartBuildMode; progress: number; } | { kind: 'diagram'; mode: DiagramBuildMode; progress: number; }; /** Opaque clipboard payload: only its presence gates the Paste button. */ export declare type ElementClipboardPayload = Record; /** Position and size in pixels. Converted to EMU internally when needed. */ declare interface ElementPosition { x: number; y: number; width: number; height: number; rotation?: number; } export declare const ElementRenderer: typeof __VLS_export_4; /** * useEditorOperations: element CRUD + transform operations over the active * slide of a reactive `PptxSlide[]`. * * This is the Vue port of the editing foundation that lives across the React * `useElementOperations` / `useClipboardHandlers` / `useGroupAlignLayerHandlers` * hooks. It is deliberately PURE of DOM and component concerns: it operates only * on the reactive slide model plus a current-slide-index ref, and threads every * mutation through a `pushHistory` callback (typically `useEditorHistory`'s * `pushHistory`) so the change is undoable. * * Mutation strategy (immutable, snapshot-first): * 1. call `pushHistory()` to snapshot the pre-mutation state, * 2. build a brand-new `PptxSlide[]` (active slide rebuilt with new elements), * 3. assign it to `slides.value`. * * Element cloning / creation always defers to the core helpers (`cloneSlide`, * `cloneElement`, `duplicateElement`, `updateSmartArtNodeText`) rather than * re-implementing them. */ /** Geometry/transform fields that {@link EditorOperations.transformElement} can patch. */ declare interface ElementTransform { x?: number; y?: number; width?: number; height?: number; rotation?: number; } /** A shallow property patch for a top-level element on an ordinary slide. */ declare interface ElementUpdate { slideId: string; elementId: string; patch: Partial; } declare interface ElementUpdateOptions { /** Optional description for the undo entry. */ label?: string; } /** * Type definitions for OOXML encryption and decryption. * * Contains all interfaces and type aliases used by the OOXML crypto modules. * * @module ooxml-crypto-types */ /** Supported encryption algorithms. */ declare type EncryptionAlgorithm = 'AES128' | 'AES256'; /** Encryption options for creating encrypted files. */ declare interface EncryptionOptions { /** The encryption algorithm to use (defaults to AES256). */ algorithm?: EncryptionAlgorithm; /** Number of hash iterations for key derivation (defaults to 100000). Lower values speed up tests. */ spinCount?: number; /** * Which encryption scheme to write (defaults to 'agile'). 'standard' * writes the ECMA-376 Standard scheme (Office 2007-compatible: a single * password-derived AES-CBC key with a zero IV over the whole package), * mirroring the scheme this library already knows how to decrypt. */ encryptionScheme?: EncryptionScheme; } /** * Which OOXML encryption scheme to write when creating a password-protected * file. Real PowerPoint can write and open either scheme; this library * defaults to 'agile' (Office 2010+), matching PowerPoint's own default. */ declare type EncryptionScheme = 'agile' | 'standard'; export declare const EquationRenderer: typeof __VLS_export_13; /** Export the selected presentation slides as SVG strings. */ export declare function exportAllSlidesToSvg(data: PptxData, options?: SvgExportAllOptions): string[]; /** Export the selected presentation slides as SVG Blobs. */ export declare function exportAllSlidesToSvgBlobs(data: PptxData, options?: SvgExportAllOptions): Blob[]; /** Export one parsed slide as self-contained SVG markup. */ export declare function exportSlideToSvg(slide: PptxSlide, width: number, height: number, options?: SvgExportSingleSlideOptions): string; /** Export one parsed slide as an SVG Blob. */ export declare function exportSlideToSvgBlob(slide: PptxSlide, width: number, height: number, options?: SvgExportSingleSlideOptions): Blob; /** The public y-protocols Awareness surface needed by a borrowed session. */ export declare interface ExternalCollaborationAwareness extends AwarenessLike { clientID: number; getLocalState: () => Record | null; setLocalState: (state: Record | null) => void; off: (event: string, callback: () => void) => void; } /** * Host-owned Yjs resources. The host creates, connects and destroys them. * Keep this object and its resources stable for a session; report connection * changes through subscribe instead of replacing the collaboration config. */ export declare interface ExternalCollaborationSession { readonly doc: Doc; /** Awareness must belong to doc. One viewer publishes slide presence at a time. */ readonly awareness: ExternalCollaborationAwareness; getSnapshot: () => ExternalCollaborationSnapshot; /** Subscribe to status or synced changes; return an unsubscribe function. */ subscribe: (listener: () => void) => () => void; } /** Connection state reported by the host, independent of the viewer lifetime. */ export declare interface ExternalCollaborationSnapshot { status: ConnectionStatus; /** * The host has loaded the authoritative document and permits local edits. * Keep true while offline to allow ordinary Yjs offline edits, or set false * to suspend writes until a fresh sync. The viewer never infers this from * `status` and never opens it after a timeout. */ synced: boolean; } declare type FeedbackSoundScheme = 'modern' | 'classic'; declare type FillInput = { type: 'solid'; color: string; opacity?: number; /** * A theme colour to use instead of a plain hex. When set, the shape * saves as `` (e.g. `{ scheme: 'accent1', lumMod: 0.8 }` * for "Accent 1, Lighter 80%") so it keeps following the theme after a * later theme change; `color` still supplies the immediate resolved * hex for renderers that read it directly. */ themeColorRef?: PptxThemeColorRef; } | { type: 'gradient'; /** * Gradient direction in the OOXML `a:lin/@ang` convention: degrees * clockwise from the positive x-axis, pointing from the first stop * towards the last (`0` = left to right, `90` = top to bottom). This is * what lands in `ShapeStyle.fillGradientAngle` and what is written back * to the file, NOT a CSS `linear-gradient()` angle. */ angle?: number; gradientType?: 'linear' | 'radial'; stops: Array<{ color: string; position: number; opacity?: number; }>; } | { type: 'pattern'; preset: string; foreground?: string; background?: string; } | { type: 'image'; url: string; mode?: 'stretch' | 'tile'; } | { type: 'none'; }; export declare const FollowModeBar: typeof __VLS_export_20; /** The two click-to-place drawing tools. */ declare type FreeformToolKind = 'freeformShape' | 'curve'; /** * Geometry types: adjustment handles, custom geometry points, segments, * paths, and custom path properties. * * @module pptx-types/geometry */ /** * Defines an adjustment handle position for a shape geometry. * * Adjustment handles allow users to interactively reshape preset shapes * (e.g. rounding a rectangle corner or adjusting arrow head width). * * @example * ```ts * const handle: GeometryAdjustmentHandle = { * guideName: "adj", * xFraction: 0.25, * minValue: 0, * maxValue: 50000, * }; * // => satisfies GeometryAdjustmentHandle * ``` */ declare interface GeometryAdjustmentHandle { /** Name of the adjustment guide this handle controls (e.g. "adj", "adj1"). */ guideName: string; /** X position as a fraction of shape width (0..1), or undefined if the handle only moves vertically. */ xFraction?: number; /** Y position as a fraction of shape height (0..1), or undefined if the handle only moves horizontally. */ yFraction?: number; /** Minimum allowed value for the adjustment guide. */ minValue?: number; /** Maximum allowed value for the adjustment guide. */ maxValue?: number; } /** * Basic, framework-agnostic style computation for slide elements. * * This is a deliberately small subset of the React package's sprawling * `viewer/utils/*` style layer (getShapeVisualStyle, getTextStyleForElement, * renderVectorShape, buildCssGradientFromShapeStyle, image-effects, …). It is * enough to faithfully position and paint text boxes, basic preset shapes, and * images. Advanced visuals (gradients, custom geometry clip-paths, shadows, * 3D, image effects, text warp) are handled by the shared render modules * (`pptx-viewer-shared`) consumed from the renderer components. */ /** * Absolute container style: position, size, rotation, flip, opacity, z-index. * Mirrors the essentials of the React `getContainerStyle`. */ export declare function getContainerStyle(el: PptxElement, zIndex: number): CSSProperties; /** Resolve a displayable image source for picture/image/media poster frames. */ export declare function getImageSrc(el: PptxElement, mediaDataUrls: Map): string | undefined; /** * Element-level convenience wrapper. Pulls `shapeType`, `width`, `height`, and * `shapeAdjustments` off a {@link PptxElement} and delegates to * {@link getResolvedShapeClipPathFor}. * * Custom-geometry freeforms (which carry `pathData`/`pathWidth`/`pathHeight` * rather than a preset `shapeType`) take priority: their outline is rescaled * into the element box via {@link buildCustomGeometryClipPath} so the fill clips * to the real shape instead of its bounding rectangle. * * @param element The PPTX element to resolve a clip-path for. * @param width Optional width override (pixels). Defaults to `element.width`. * @param height Optional height override (pixels). Defaults to `element.height`. */ export declare function getResolvedShapeClipPath(element: PptxElement, width?: number, height?: number): string | undefined; /** * Resolve the best available CSS `clip-path` value for a shape type at a given * pixel size. Implements the priority cascade described in the module * docstring. Returns `undefined` when the shape needs no clipping. * * @param shapeType The OOXML preset geometry name (case-insensitive). * @param width Element width in pixels (must be > 0 for path output). * @param height Element height in pixels (must be > 0 for path output). * @param adjustments Optional `shapeAdjustments` record from the element. */ export declare function getResolvedShapeClipPathFor(shapeType: string | undefined, width: number, height: number, adjustments?: Record): string | undefined; /** * Fill / stroke / corner-radius for shape-like elements. Returns an empty * object when the element carries no shape styling. * * `parentGroupFill` is the enclosing group's fill (`GroupPptxElement.groupFill`), * threaded down by the group renderer so a child painted with `a:grpFill` * (`fillMode === 'group'`) inherits the group's resolved fill. */ export declare function getShapeFillStrokeStyle(el: PptxElement, parentGroupFill?: ShapeStyle, animatesFill?: boolean, animatesStroke?: boolean): CSSProperties; /** * Text block style for elements that carry text. * * A thin adapter over the shared {@link buildTextBlockStyle}, which React * renders from too. It used to be a hand-ported copy of React's builder, and * the copy had silently lost `a:normAutofit` (a shrink-to-fit title painted 43% * too large), `a:bodyPr/@wrap="none"` (a no-wrap line wrapped to three), the * default font declaration, the italic padding nudge and the body margin/indent * pair. `bodyLayout` adds the flex-column body + `anchor` justification this * binding folds into the same element; `pxLengths` is required because Vue's * style binding does not unit-suffix bare numbers. */ export declare function getTextBlockStyle(el: PptxElement): CSSProperties; declare interface GroupOptions extends Partial {} /** * A group container that holds child elements. * * Children inherit the group’s transform, so moving/resizing the group * affects all children proportionally. * * @example * ```ts * const group: GroupPptxElement = { * type: "group", * id: "grp_1", x: 0, y: 0, width: 960, height: 540, * children: [textEl, shapeEl], * }; * // => satisfies GroupPptxElement * ``` */ declare interface GroupPptxElement extends PptxElementBase { type: 'group'; /** Child elements contained within this group. */ children: PptxElement[]; /** Fill style extracted from the group's `p:grpSpPr`, used for `a:grpFill` inheritance. */ groupFill?: ShapeStyle; /** * The SAME `p:grpSpPr` extraction as {@link groupFill}, kept whenever the * group carries a `p:grpSpPr` at all, regardless of whether it resolved to * a paintable fill. * * `groupFill` is `undefined` unless the group has a real fill, because * `getGroupChildParentFill`/`groupChildInheritedFill` (the `a:grpFill` * inheritance chain) must keep chaining through an ancestor's fill when * THIS group has none of its own. A group whose `p:grpSpPr` authors only * `a:effectLst` (shadow/glow/soft-edge/reflection, no fill) needs those * effects to still reach the renderer, so they are kept here under a name * that carries no fill-inheritance meaning. Currently only reflection is * read from it (`getComputedEffectStyle`); the rest of `a:effectLst` on a * group remains unsupported. */ groupEffectStyle?: ShapeStyle; /** * Exact EMU the group's own `a:chOff`/`a:chExt` (the coordinate space its * CHILDREN are authored in) were parsed from, alongside {@link * PptxElementBase.xEmu} etc for the group's own placement in its PARENT's * space. `undefined` when the source carried no usable `a:chOff`/`a:chExt` * (an SDK-created group, or one whose `a:xfrm` had no child-space data). * * Used by `group-xfrm-preservation.ts`'s `hasCapturedChildSpace` to decide * whether this group's original `a:chOff`/`a:chExt` can be re-emitted * verbatim (always true once captured, regardless of whether anything in * the subtree has moved or resized - only its DIRECT children's * `a:off`/`a:ext` are recomputed, via `invertChildIntoGroupSpace`, when * something changed), instead of the normalized `chOff 0,0` / `chExt == * ext` space the writer falls back to when this is `undefined` (or * degenerate). See `group-shape-geometry.ts`'s module doc for why a group * needs two coordinate systems at all. */ chOffXEmu?: number; /** See {@link chOffXEmu}. */ chOffYEmu?: number; /** See {@link chOffXEmu}. */ chExtWidthEmu?: number; /** See {@link chOffXEmu}. */ chExtHeightEmu?: number; } /** A single alignment guide, positioned in authored slide pixels. */ declare interface Guide { id: string; axis: 'h' | 'v'; position: number; } export declare interface GuideEntry { id: string; axis: 'h' | 'v'; position: number; } declare interface ImageOptions extends Partial { altText?: string; cropLeft?: number; cropTop?: number; cropRight?: number; cropBottom?: number; opacity?: number; } /** An element that may carry an image path needing Blob URL resolution. */ export declare interface ImagePathElement { element: PptxElement; field: 'imageData' | 'svgData' | 'posterFrameData' | 'modelData' | 'posterImage'; path: string; } /** * An image element from an OOXML `` node with `type: "image"`. * * @example * ```ts * const img: ImagePptxElement = { * type: "image", * id: "img_1", x: 0, y: 0, width: 960, height: 540, * imagePath: "ppt/media/image1.png", * altText: "Background scenery", * }; * // => satisfies ImagePptxElement * ``` */ declare interface ImagePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties, PptxAccessibilityProperties, PptxPictureNonVisualProperties { type: 'image'; } declare type ImageResolutionPreset = 'highFidelity' | 'ppi330' | 'ppi220' | 'ppi150' | 'ppi96'; /** * A freehand ink / drawing stroke captured with a stylus or mouse. * * Ink strokes are stored as SVG path data strings. Each path may * have independent colour, width, and opacity. */ declare interface InkPptxElement extends PptxElementBase { type: 'ink'; /** SVG path data for ink strokes. */ inkPaths: string[]; /** Per-path stroke colours. */ inkColors?: string[]; /** Per-path stroke widths. */ inkWidths?: number[]; /** Per-path opacities (0-1). */ inkOpacities?: number[]; /** Drawing tool used: pen, highlighter, or eraser. */ inkTool?: 'pen' | 'highlighter' | 'eraser'; /** * Per-path arrays of per-point pressure values (0-1). * * Each entry corresponds to the path at the same index in `inkPaths`. * Each inner array contains one pressure value per sampled point along * the stroke. When present, the renderer uses these values to produce * variable-width strokes that reflect stylus/pen pressure. */ inkPointPressures?: number[][]; /** * Per-path arrays of per-point pen-tilt lean direction (degrees, straight * from `PointerEvent.tiltX` on supporting hardware). * * Each entry corresponds to the path at the same index in `inkPaths`, and * is paired positionally with {@link inkPointTiltY}. Present only when at * least one point in the stroke reported a genuinely non-zero tilt: a * device that never reports tilt (a mouse, or a stylus with no tilt * sensor) leaves both arrays absent, the same way `inkPointPressures` is * omitted when pressure never varies. When present, the renderer converts * the raw `(tiltX, tiltY)` vector into a lean angle + magnitude (see * `pptx-viewer-shared`'s `tiltChannelsFromVectors`) and widens the stroke * perpendicular to the lean direction, approximating a chisel-tip * calligraphy nib. */ inkPointTiltX?: number[][]; /** Per-path, per-point pen-tilt lean direction (degrees), paired with {@link inkPointTiltX}. */ inkPointTiltY?: number[][]; /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */ extensionXml?: PptxGraphicFrameExtension[]; } export declare const InkRenderer: typeof __VLS_export_9; export declare interface InlineListController { read(): InlineListReadResult; format(snapshot: InlineTextEditSnapshot): InlineListReadResult; readSelection(selection?: Selection | null): InlineListSelectionResult; refresh(): InlineListReadResult; dispose(): void; } export declare type InlineListReadResult = { kind: 'supported'; snapshot: InlineTextEditSnapshot; paragraphs: RenderParagraph[]; } | { kind: 'unsupported'; reason: string; text: string; }; declare type InlineListSelectionResult = { kind: 'supported'; snapshot: InlineTextEditSnapshot; selection: InlineTextSelection | null; bodyRange?: { start: number; end: number; }; } | { kind: 'unsupported'; reason: string; }; export declare const InlineTextEditor: typeof __VLS_export_16; /** Current editor payload. Missing segments explicitly denotes plain-text fallback. */ export declare interface InlineTextEditSnapshot { elementId: string; text: string; textSegments?: TextSegment[]; } /** Describes which segments (and offsets within them) are selected. */ declare interface InlineTextSelection { startSegIdx: number; startOffset: number; endSegIdx: number; endOffset: number; } /** * Dropdown ids for the insert-chart menu. Distinct from `PptxChartType` * because PowerPoint offers Column (vertical) and Bar (horizontal) as two * entries over the same underlying `'bar'` chart type, and because `'pareto'` * has no `PptxChartType` of its own: it is a dropdown entry that resolves to * `type: 'histogram'` (see docs/guide/limitations.md's ChartEx row) with a * frequency-plus-cumulative-percentage default shape. The other six ChartEx * ids (`histogram` through `regionMap`) map one-to-one onto their chart type. */ declare type InsertChartKind = 'column' | 'bar' | 'line' | 'pie' | 'doughnut' | 'area' | 'scatter' | 'histogram' | 'pareto' | 'funnel' | 'treemap' | 'sunburst' | 'boxWhisker' | 'regionMap'; declare interface IPptxHandlerRuntime { /** * Release all resources held by this runtime (Blob URLs, caches, ZIP). * After calling, the runtime cannot be used further. */ dispose(): void; /** * Revoke all Blob URLs created during image loading. */ revokeBlobUrls(): void; getCompatibilityWarnings(): PptxCompatibilityWarning[]; getLayoutOptions(): PptxLayoutOption[]; getLayoutPreview(layoutPath: string): Promise; getLayoutPreviews(layoutPaths?: readonly string[]): Promise; createXmlBuilder(data: PptxData): PptxXmlBuilder; Builder(data: PptxData): PptxXmlBuilder; setTemplateBackground(path: string, backgroundColor: string | undefined): void; setPresentationTheme(themePath: string, applyToAllMasters?: boolean): Promise; getTemplateBackgroundColor(path: string): string | undefined; updateThemeColorScheme(colorScheme: PptxThemeColorScheme): Promise; updateThemeFontScheme(fontScheme: PptxThemeFontScheme): Promise; updateThemeName(name: string): Promise; /** Resolve a `` node against the loaded theme (see PptxHandlerRuntimeStyleMatrixResolve). */ resolveStyleMatrixReferences(styleXml: XmlObject): ResolvedStyleMatrix; applyTheme(colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme, themeName?: string): Promise; load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise; getChartDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise; getSmartArtDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise; getImageData(imagePath: string): Promise; /** * Extract a media file from the PPTX archive as an ArrayBuffer. * Returns undefined if the file is not found. */ getMediaArrayBuffer(mediaPath: string): Promise; save(slides: PptxSlide[], options?: PptxHandlerSaveOptions): Promise; exportSlides(slides: PptxSlide[], options: PptxExportOptions): Promise>; /** * Get the available slide layouts for a specific slide, based on the * slide's master. Scans the slide master's relationships to find all * layouts that belong to it. * * @param slideIndex - Zero-based slide index. * @param slides - Current slides array. * @returns Array of layout options belonging to the same slide master. */ getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise; /** * Resolve the editable template (master + layout) elements a slide * inherits, each carrying a `master-` / `layout-` prefixed id. Excludes * placeholders; returns only decorative shapes/pictures/graphic frames. * * @param slideId - The slide's archive path (`PptxSlide.id`). */ getTemplateElementsForSlide(slideId: string): Promise; /** * Scan the loaded PPTX archive for all theme parts. */ getAvailableThemes(): Promise>; /** * Apply a different layout to an existing slide by updating the slide's * relationship to point to the new layout and re-parsing layout * placeholders / background. * * @param slideIndex - Zero-based slide index. * @param layoutPath - Archive path of the target layout * (e.g. `ppt/slideLayouts/slideLayout2.xml`). * @param slides - Current slides array. * @returns The updated slide with new layout path, name, and background. */ applyLayoutToSlide(slideIndex: number, layoutPath: string, slides: PptxSlide[]): Promise; } /** * Abstract factory contract for creating {@link IPptxHandlerRuntime} * instances. * * Implement this interface to supply a custom runtime (e.g. a * WASM-backed or test-double runtime) to {@link PptxHandlerCore}. */ declare interface IPptxHandlerRuntimeFactory { /** Instantiate and return a new runtime implementation. */ createRuntime(): IPptxHandlerRuntime; } /** * Fluent interface for navigating and mutating a {@link PptxData} structure. * Provides method-chaining access to slides, elements, and notes. */ declare interface IPptxXmlBuilder { /** Navigate to a slide by zero-based index (Pascal-case alias). */ Slides(index: number): PptxSlideBuilder; /** Navigate to a slide by zero-based index. */ slide(index: number): PptxSlideBuilder; /** Navigate to a slide by zero-based index (plural alias). */ slides(index: number): PptxSlideBuilder; /** Return the underlying presentation data. */ project(): PptxData; } /** Returns true if the current page was opened as an audience tab. */ export declare function isAudienceTab(): boolean; /** Editor keyboard-shortcut customisation. */ declare interface KeyboardCustomization { /** Turn every editor shortcut off (the host owns the keyboard). */ disableAll?: boolean; /** Editor commands whose shortcut is turned off. */ disabled?: readonly EditorKeyActionName[]; /** * Replacement chords per command. A remapped command no longer answers to * its built-in chord; it answers to the chord(s) given here instead. */ remap?: Partial>; } /** A `{ path, name }` layout option for the New-Slide dropdown. */ export declare interface LayoutOption { path: string; name: string; } /** Interim geometry for an element mid-gesture. All fields optional. */ declare interface LiveGeometryPatch { x?: number; y?: number; width?: number; height?: number; rotation?: number; } /** The element's pre-edit rich text, used to remap the interim plain text. */ declare interface LiveTextSource { textSegments?: TextSegment[]; textStyle?: TextStyle; } /** * Load PPTX content bytes stored by the presenter tab. * Returns `null` if nothing is stored. */ export declare function loadAudienceContent(sessionId?: string): Promise; /** One selectable entry in the viewer chrome's built-in language picker (File > Options > Language). */ declare interface LocaleCatalogEntry { /** BCP-47-ish locale code, e.g. `'en'`, `'fr'`. Matches `pptx-viewer-locales`' exports. */ code: string; /** English display name, used before a translation dictionary for the target locale is loaded. */ label: string; /** The locale's own name for itself, e.g. `'Français'` for `fr`. */ nativeLabel: string; } declare type LocalTextEdit = LocalTextReplacement | TextSessionCorrespondence; /** Browser edit range mapped to the editor's pre-input encoded coordinates. */ declare interface LocalTextReplacement { from: number; to: number; } /** * Active tab within the master view sidebar. * * @example * ```ts * const tab: MasterViewTab = "slides"; * // => "slides" — one of: "slides" | "notes" | "handout" * ``` */ declare type MasterViewTab = 'slides' | 'notes' | 'handout'; /** Which part the master view is currently pointed at. */ declare interface MasterViewTarget { tab: MasterViewTab; masterIndex: number; /** `null` selects the master itself rather than one of its layouts. */ layoutIndex: number | null; } /** * Material preset type tokens from OOXML `a:sp3d/@prstMaterial`. * * @example * ```ts * const mat: MaterialPresetType = "plastic"; * // => "plastic" — one of: "matte" | "warmMatte" | "plastic" | "metal" | "dkEdge" | … * ``` */ declare type MaterialPresetType = 'matte' | 'warmMatte' | 'plastic' | 'metal' | 'dkEdge' | 'softEdge' | 'flat' | 'softmetal' | 'clear' | 'powder' | 'translucentPowder' | 'legacyMatte' | 'legacyPlastic' | 'legacyMetal' | 'legacyWireframe'; /** * A named bookmark within a media clip timeline. * * @example * ```ts * const bm: MediaBookmark = { * id: "bm1", * time: 12.5, * label: "Intro ends", * }; * // => satisfies MediaBookmark * ``` */ declare interface MediaBookmark { id: string; /** Position in seconds from the start of the clip. */ time: number; /** User-visible label for this bookmark. */ label: string; } /** * A closed-caption / subtitle track associated with a media element. * * @example * ```ts * const track: MediaCaptionTrack = { * id: "t1", * label: "English", * language: "en", * kind: "subtitles", * isDefault: true, * }; * // => satisfies MediaCaptionTrack * ``` */ declare interface MediaCaptionTrack { /** Unique ID for this track. */ id: string; /** Human-readable label (e.g. "English", "Spanish"). */ label: string; /** BCP-47 language code (e.g. "en", "es"). */ language: string; /** Track kind: subtitles, captions, or descriptions. */ kind: 'subtitles' | 'captions' | 'descriptions'; /** Data URL or path to the VTT/SRT content within the PPTX archive. */ src?: string; /** Inline VTT content (for embedded captions). */ content?: string; /** Whether this track is the default/active one. */ isDefault?: boolean; } /** * Runtime-extracted metadata about a media clip (populated from HTMLMediaElement). * * @example * ```ts * const meta: MediaMetadata = { * duration: 120.5, * videoWidth: 1920, * videoHeight: 1080, * codecInfo: "video/mp4; codecs=\"avc1.640028\"", * }; * // => satisfies MediaMetadata * ``` */ declare interface MediaMetadata_2 { /** Duration in seconds. */ duration?: number; /** Video width in pixels (video only). */ videoWidth?: number; /** Video height in pixels (video only). */ videoHeight?: number; /** MIME type / codec string reported by the browser. */ codecInfo?: string; } declare interface MediaOptions extends Partial { autoPlay?: boolean; loop?: boolean; volume?: number; trimStartMs?: number; trimEndMs?: number; posterFrame?: string; } /** * An audio or video media element. * * Media elements reference files inside the PPTX archive * (`mediaPath`) and may include trim points, poster frames, and * playback settings for presentation mode. * * @example * ```ts * const video: MediaPptxElement = { * type: "media", * id: "vid_1", x: 50, y: 100, width: 640, height: 360, * mediaType: "video", * mediaPath: "ppt/media/media1.mp4", * autoPlay: true, * volume: 0.8, * }; * // => satisfies MediaPptxElement * ``` */ declare interface MediaPptxElement extends PptxElementBase { type: 'media'; mediaType?: PptxMediaType; mediaPath?: string; mediaData?: string; mediaMimeType?: string; mediaReferenceKind?: PptxMediaReferenceKind; mediaReferenceName?: string; /** Explicit DrawingML `audioFile/@contentType` value when present. */ mediaReferenceContentType?: string; audioCdStart?: PptxAudioCdPosition; audioCdEnd?: PptxAudioCdPosition; rawMediaReferenceXml?: XmlObject; /** Trim start in milliseconds (from p:cMediaNode p:cTn @st). */ trimStartMs?: number; /** Trim end in milliseconds (from p:cMediaNode p:cTn @end). */ trimEndMs?: number; /** Path to the poster/preview image inside the ZIP. */ posterFramePath?: string; /** Base64 data-URL for the poster frame image. */ posterFrameData?: string; /** Poster source crop from the left edge as a 0..1 fraction. */ cropLeft?: number; /** Poster source crop from the top edge as a 0..1 fraction. */ cropTop?: number; /** Poster source crop from the right edge as a 0..1 fraction. */ cropRight?: number; /** Poster source crop from the bottom edge as a 0..1 fraction. */ cropBottom?: number; /** Poster stretch-target inset from the left frame edge. */ fillRectLeft?: number; /** Poster stretch-target inset from the top frame edge. */ fillRectTop?: number; /** Poster stretch-target inset from the right frame edge. */ fillRectRight?: number; /** Poster stretch-target inset from the bottom frame edge. */ fillRectBottom?: number; /** Whether media should play full-screen during presentation. */ fullScreen?: boolean; /** Whether media should loop continuously. */ loop?: boolean; /** Fade-in duration in seconds. */ fadeInDuration?: number; /** Fade-out duration in seconds. */ fadeOutDuration?: number; /** Playback volume (0 to 1). */ volume?: number; /** Whether media auto-plays on slide entry. */ autoPlay?: boolean; /** Whether audio continues playing across slide transitions (presentation mode). */ playAcrossSlides?: boolean; /** Hide the element when media is not actively playing. */ hideWhenNotPlaying?: boolean; /** Named time bookmarks within the clip. */ bookmarks?: MediaBookmark[]; /** Playback speed multiplier (1 = normal, 2 = double, 0.5 = half). */ playbackSpeed?: number; /** Runtime-extracted metadata (duration, resolution, codec). */ metadata?: MediaMetadata_2; /** Closed caption / subtitle tracks. */ captionTracks?: MediaCaptionTrack[]; /** Whether the media source is missing/broken (file not found in archive). */ mediaMissing?: boolean; /** * Whether the media is linked (external `r:link`) rather than embedded * (`r:embed`). Defaults to embedded when undefined. */ isLinked?: boolean; /** * Accessibility description. Read from `p:nvGraphicFramePr/p:cNvPr/@descr` * for the `p:graphicFrame`-shaped (SDK-created) media form, or from * `p:nvPicPr/p:cNvPr/@descr` for the `p:pic`-shaped media form (real * PowerPoint's usual authoring shape for a video/audio placeholder); see * `PptxHandlerRuntimePictureParsing.ts`. */ altText?: string; /** Accessibility title, from the same `@title` attribute on whichever `p:cNvPr` the media form uses. Same scope note as {@link altText}. */ title?: string; /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */ extensionXml?: PptxGraphicFrameExtension[]; } /** The right-click command id for each operation. */ declare type MergeShapesCommandId = 'merge-union' | 'merge-combine' | 'merge-fragment' | 'merge-intersect' | 'merge-subtract'; /** * A 3D model object embedded via `p16:model3D` inside an * `mc:AlternateContent` block (PowerPoint 365+). * * The element carries the path to the `.glb`/`.gltf` binary inside * the ZIP and a poster/fallback image for rendering in viewers that * do not support interactive 3D. */ declare interface Model3DPptxElement extends PptxElementBase, PptxImageProperties { type: 'model3d'; /** Path to the 3D model file inside the ZIP. */ modelPath?: string; /** Base64 data URL of the 3D model binary. */ modelData?: string; /** MIME type of the model (e.g. "model/gltf-binary"). */ modelMimeType?: string; /** Poster/preview image shown when 3D rendering is unavailable. */ posterImage?: string; /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */ extensionXml?: PptxGraphicFrameExtension[]; } export declare const Model3DRenderer: typeof __VLS_export_11; /** * Recognised OLE object application types derived from `progId` / `clsId`. * * Used to show type-specific icons and previews in the editor. */ declare type OleObjectType = 'excel' | 'word' | 'powerpoint' | 'pdf' | 'visio' | 'mathtype' | 'package' | 'unknown'; /** * An OLE (Object Linking and Embedding) object. * * OLE objects can be embedded Excel sheets, Word documents, PDFs, Visio * diagrams, MathType equations, or generic "packages". They carry a * preview image for display and optional binary data for extraction. * * @example * ```ts * const ole: OlePptxElement = { * type: "ole", * id: "ole_1", x: 100, y: 200, width: 400, height: 300, * oleObjectType: "excel", * oleProgId: "Excel.Sheet.12", * fileName: "budget.xlsx", * }; * // => satisfies OlePptxElement * ``` */ declare interface OlePptxElement extends PptxElementBase { type: 'ole'; oleTarget?: string; oleProgId?: string; oleName?: string; /** CLSID of the OLE object (from `@_classid`). */ oleClsId?: string; /** Detected application type (excel, word, pdf, etc.). */ oleObjectType?: OleObjectType; /** File extension for the embedded binary (e.g. "xlsx", "docx"). */ oleFileExtension?: string; /** Original file name when available. */ fileName?: string; /** Whether this is a linked (vs. embedded) object. */ isLinked?: boolean; /** External file path for linked OLE objects (TargetMode="External"). */ externalPath?: string; /** Data-URL or path for the OLE preview image. */ previewImage?: string; /** Decoded preview image as a data-URL. */ previewImageData?: string; /** Whether the OLE object is shown as an icon (`p:oleObj/@showAsIcon`). */ oleShowAsIcon?: boolean; /** Authored display width of the OLE object preview, in EMU (`@imgW`). */ oleImgW?: number; /** Authored display height of the OLE object preview, in EMU (`@imgH`). */ oleImgH?: number; /** * The recovered embedded payload as a data-URL (e.g. * `data:application/vnd...;base64,...`), suitable for download or * open-in-new-tab. For a generic "Package" OLE object this is the unwrapped * inner file; for a plain embedded file (e.g. `.xlsx`) it is that file * directly. Undefined when the embedding is missing or unreadable. * * Stored as a data-URL string to mirror how images store decoded bytes * ({@link ImagePptxElement.imageData}) and to stay serialization-safe. */ oleEmbeddedData?: string; /** Original file name of the embedded payload when recoverable. */ oleEmbeddedFileName?: string; /** MIME type of the embedded payload, derived from its extension/ProgID. */ oleEmbeddedMimeType?: string; /** Size of the embedded payload in bytes. */ oleEmbeddedByteSize?: number; /** * `p:link/@followColorScheme` (`ST_OleObjectFollowColorScheme`): whether a * LINKED OLE object's icon recolours to match the presentation theme. * Only meaningful when {@link isLinked} is `true`. ECMA-376 §19.3.1.28. */ oleFollowColorScheme?: 'none' | 'full' | 'textAndBackground'; /** * `p:link/@updateAutomatic` (`CT_OleObjectLink`, ECMA-376 §19.3.2.4): * whether a LINKED OLE object refreshes automatically from its source * (PowerPoint's Edit Links dialog "Automatic" vs. "Manual" radio buttons). * Only meaningful when {@link isLinked} is `true`. The schema default is * `false`; `undefined` means the source authored no explicit value. */ oleUpdateAutomatic?: boolean; /** * Set by the in-viewer OLE content editors (`ole-edit-api.ts`) whenever * `oleEmbeddedData` and/or `previewImageData` have been changed in memory * and still need to be written back into the saved package. Never * authored from a parsed file; purely an in-memory save signal, mirroring * `PptxSlide.isDirty`. The save writer clears it once the pending write * has been queued. */ oleContentDirty?: boolean; /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */ altText?: string; /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */ title?: string; /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */ extensionXml?: PptxGraphicFrameExtension[]; } export declare const OleRenderer: typeof __VLS_export_10; declare type OpenDocumentsView = 'savedView' | 'normal' | 'outline' | 'slideSorter' | 'notes'; /** File > Options (the Settings dialog) customisation. */ declare interface OptionsCustomization { /** Whole pages to remove from the dialog's category rail. */ hiddenPages?: readonly OptionsPageId[]; /** Sections (`.
`) to remove from their page. */ hiddenSections?: readonly OptionsSectionId[]; /** Individual settings (`.`) to remove wherever they appear. */ hiddenSettings?: readonly OptionsSettingId[]; /** * Settings pinned to a fixed value. The value is forced into the options * store, user edits to it are ignored, and the control renders read-only. * Add the id to `hiddenSettings` too to lock it invisibly. */ locked?: OptionsSettingValues; /** * Host defaults: the value a setting starts at when the user has not saved * a choice of their own. "Reset" returns to these, not to the built-ins. */ defaults?: OptionsSettingValues; } /** * A File > Options page: the ten PowerPoint categories plus `ai`, the AI * assistant page a binding adds when the host configured an assistant. */ declare type OptionsPageId = ViewerOptionsTabId | 'ai'; declare type OptionsPrintColorMode = 'color' | 'grayscale' | 'blackAndWhite'; declare type OptionsPrintWhat = 'slides' | 'handouts' | 'notes' | 'outline'; /** * One section of an Options page, addressed as `.
`, for * example `general.personalize` or `advanced.print`. The full list is * `OPTIONS_SECTION_IDS` (derived from the schema at runtime). */ declare type OptionsSectionId = `${ViewerOptionsTabId}.${string}`; /** * One File > Options setting, addressed as `.`, for example * `general.userName` or `advanced.showGrid`. The union is derived from the * `ViewerOptions` model itself, so a typo is a compile error. */ declare type OptionsSettingId = { [G in ViewerOptionsGroupId]: `${G}.${PrimitiveKeys}`; }[ViewerOptionsGroupId]; /** Values a host forces onto settings. */ declare type OptionsSettingValues = Partial>; /** Overlay a current rich list draft for serialization, without committing editor state. */ export declare function overlayInlineTextSnapshot(elements: readonly PptxElement[], snapshot?: InlineTextEditSnapshot, text?: string | undefined): readonly PptxElement[]; /** A single rendered run within a paragraph. */ declare interface ParagraphRun { text: string; style: RunStyle; /** * The run's hyperlink (`a:hlinkClick` / `a:hlinkMouseOver`), when it has one. * A binding renders the run inside an `` when {@link RunHyperlink.href} * is set, and routes {@link RunHyperlink.url} to its click handler otherwise * (internal `ppaction://` slide jumps). */ hyperlink?: RunHyperlink; /** * An inline equation (`m:oMath`) this run renders INSTEAD of `text`, which is * empty for it. Emitted in the run sequence so the maths lands at its * authored position between the runs around it. */ equation?: RunEquation; /** * The run's phonetic guide (`a:ruby`: furigana, pinyin, bopomofo), when it * has one. A binding renders `{text}{ruby.text}`; * a run carrying one is never split per word, so the annotation appears once * over the whole base run. * * Core parsed and saved ruby from the start, but `buildParagraphs` never read * it, so the annotation rendered in React alone. */ ruby?: RunRuby; /** * Index of the `textSegments` entry (of the override list when one was * supplied) this run was built from. * * Shared splits one authored run into several per-word runs for PowerPoint's * metric tracking, so this is many-to-one. It is the seam a binding uses to * reach the facts the neutral model does not carry - React's find-match * highlights, per-script font spans, tab stops and ruby all key off the * originating segment - without regrouping the segments itself and drifting * from the grouping here. */ segmentIndex?: number; /** * Offset of this run's `text` within its segment's RENDERED text (after field * substitution), so a caller holding per-segment character offsets can map * them onto the split runs. */ charStart?: number; /** * Per-script (`a:ea`/`a:cs`/`a:sym`) font-fallback pieces for this run's * text, when a script it contains needs a font distinct from its own. A * binding renders these as nested spans in place of `text` (see * `text-script-fonts.ts`); absent for the common single-font case. */ scriptRuns?: ScriptFontPiece[]; /** * Measured tab-stop layout for this run's text, present when it contains an * authored `\t` and the paragraph declares explicit tab stops. A binding * renders these lines/pieces in place of `text`, honouring per-stop * alignment and leader glyphs a plain CSS `tab-size` cannot express (see * `text-tab-run-build.ts`). Absent for the common no-tab case. */ tabLines?: TabbedLineRun[]; /** * `a:rPr/@u="words"` word/gap pieces of a RUBY run's base text, present only * when such a run's underline is `words` (the ordinary per-word split emits * sibling runs instead; a tab piece carries its own `words`). Same shape as * `scriptRuns` and rendered the same way, in place of `text`: a word entry * carries the decoration for its own span, a gap entry is bare text. The * run's own `style` has the underline stripped when this is set (see * `paragraph-run-build.ts`). */ underlineWordPieces?: ScriptFontPiece[]; /** The advance-carrying space after a hanging `、`/`。` (`text-east-asian-breaks`). */ hangingSpace?: true; /** * `a:reflection` mirrored-sibling wrapper style for this run (the text-run * counterpart of a shape/picture's `ComputedEffectStyle.reflection`), or * `undefined` for the common no-reflection case. A binding renders a sibling * node just below the run's own, painted with the same text, positioned and * masked by this style - see `render/reflection.ts`'s * `getTextReflectionWrapperStyle`. */ reflection?: ReflectionWrapperStyle; } /** * Parse the session nonce from the current page URL hash. Returns `null` if the * hash is not in the expected `#pptx-audience&nonce=` form. */ export declare function parseAudienceNonce(): string | null; /** Parsed digital signature with certificate info and validation status. */ declare interface ParsedSignature { /** Path to the signature XML in the ZIP. */ signaturePath: string; /** The canonicalized signing method algorithm URI. */ signatureMethod?: string; /** The digest method algorithm URI from the first reference. */ digestMethod?: string; /** Base64-encoded signature value. */ signatureValue?: string; /** Certificate information, if X.509 data was found. */ certificate?: SignatureCertificateInfo; /** Signature validation status. */ status: SignatureStatus; /** Reference URIs and their digest values. */ references: SignatureReference[]; } /** * Table background style (CT_TableBackgroundStyle, ECMA-376 §21.1.3.7). * * Corresponds to the `` child of ``. Captures the * resolved scheme-fill colour, an unresolved style-matrix `a:fillRef`, and a * presence flag for effects (verbatim XML for the effect list is preserved * separately by the save path). */ declare interface ParsedTableBackground { /** Solid fill (resolved from `a:fill > a:solidFill > a:schemeClr`). */ fill?: ParsedTableStyleFill; /** * Style-matrix fill reference (`...`), * mutually exclusive with {@link fill} (`a:fill` is the choice sibling of * `a:fillRef` in `CT_TableBackgroundStyle`). */ fillRef?: ParsedTableFillRef; /** Has an `a:effectLst` child that should be round-tripped. */ hasEffectLst?: boolean; } /** * A `a:fillRef`/`a:lnRef`/`a:effectRef`-style style-matrix reference: an * index into the theme's format scheme (`a:fmtScheme/a:fillStyleLst`, 1-based * per ECMA-376 §20.1.4.1.12) plus an optional colour transform child. * * Distinct from an already-resolved {@link ParsedTableStyleFill}: a fill ref * points AT a theme style-matrix entry rather than carrying a colour choice * directly, though the two commonly appear together (` * `). * * @example * ```ts * const ref: ParsedTableFillRef = { idx: 2, color: { schemeColor: 'accent1' } }; * // => satisfies ParsedTableFillRef * ``` */ declare interface ParsedTableFillRef { /** 1-based index into the theme format scheme's fill style list. */ idx: number; /** Colour transform child (`a:schemeClr`/`a:srgbClr`) applied to the referenced style. */ color?: ParsedTableStyleFill; } /** * A single border side within a table style's `a:tcStyle/a:tcBdr`. * * Corresponds to one of `a:left`, `a:right`, `a:top`, `a:bottom`, * `a:insideH`, `a:insideV`, `a:tl2br`, `a:tr2bl` (each a * `CT_ThemeableLineStyle` wrapping an `a:ln`). * * @example * ```ts * const side: ParsedTableStyleBorder = { * width: 1, * dash: 'solid', * fill: { schemeColor: 'lt1' }, * }; * // => satisfies ParsedTableStyleBorder * ``` */ declare interface ParsedTableStyleBorder { /** Line width in px (converted from the `a:ln@w` EMU value). */ width?: number; /** OOXML `a:prstDash@val` (e.g. `solid`, `dash`, `sysDot`). */ dash?: string; /** Border colour as a theme scheme fill (from `a:ln/a:solidFill/a:schemeClr`). */ fill?: ParsedTableStyleFill; /** Explicit hex colour when the line used `a:srgbClr` (e.g. `#808080`). */ color?: string; /** The line was `a:noFill` - an explicit "no border" that clears lower layers. */ noFill?: boolean; } /** * The set of border sides parsed from a table style section's * `a:tcStyle/a:tcBdr` element. */ declare interface ParsedTableStyleBorders { left?: ParsedTableStyleBorder; right?: ParsedTableStyleBorder; top?: ParsedTableStyleBorder; bottom?: ParsedTableStyleBorder; /** Interior horizontal borders between rows in the region. */ insideH?: ParsedTableStyleBorder; /** Interior vertical borders between columns in the region. */ insideV?: ParsedTableStyleBorder; /** Top-left to bottom-right diagonal. */ tl2br?: ParsedTableStyleBorder; /** * Top-right to bottom-left diagonal (`a:tr2bl`, ECMA-376's * `CT_TableCellBorderStyle` sequence: left/right/top/bottom/insideH/ * insideV/tl2br/tr2bl). The field keeps its historical `bl2tr` spelling * only in the sense that it names the same geometric anti-diagonal line * (top-right-to-bottom-left and bottom-left-to-top-right describe one * undirected diagonal); the parser accepts the real `a:tr2bl` element and, * leniently, a legacy `a:bl2tr` this app previously wrote (issue G4). */ tr2bl?: ParsedTableStyleBorder; } /** * One leaf (or `effectDag`-wrapped) node of an `a:effectLst`/`a:effectDag` * effect chain, kept mostly opaque: {@link kind} names the OOXML element so a * consumer can recognise common effects (`outerShdw`, `glow`, `softEdge`, * `reflection`, `blur`, `innerShdw`, `prstShdw`, `fillOverlay`, `alphaModFix`, * `alphaInv`, `grayscl`, `biLevel`, `duotone`, `hsl`, `lum`, `tint`) without * this module re-deriving the full shape-effect taxonomy already modelled on * `ShapeStyle`; {@link xml} preserves the node verbatim for lossless re-emit. * * @example * ```ts * const effect: ParsedTableStyleEffect = { * kind: 'outerShdw', * xml: { '@_blurRad': '40000', '@_dist': '20000', '@_dir': '5400000' }, * }; * // => satisfies ParsedTableStyleEffect * ``` */ declare interface ParsedTableStyleEffect { /** The OOXML element's local name, e.g. `outerShdw`, `glow`, `softEdge`. */ kind: string; /** Verbatim XML node (attributes + children) for lossless round-trip. */ xml: XmlObject; } declare interface ParsedTableStyleEntry { styleId: string; styleName?: string; /** Dominant accent key derived from fills (e.g. `accent1`). */ accentKey?: string; /** Table-level background (``). */ tableBackground?: ParsedTableBackground; wholeTblFill?: ParsedTableStyleFill; band1HFill?: ParsedTableStyleFill; band2HFill?: ParsedTableStyleFill; band1VFill?: ParsedTableStyleFill; band2VFill?: ParsedTableStyleFill; firstRowFill?: ParsedTableStyleFill; lastRowFill?: ParsedTableStyleFill; firstColFill?: ParsedTableStyleFill; lastColFill?: ParsedTableStyleFill; /** Corner cell fills (``, ``, ``, ``). */ seCellFill?: ParsedTableStyleFill; swCellFill?: ParsedTableStyleFill; neCellFill?: ParsedTableStyleFill; nwCellFill?: ParsedTableStyleFill; /** * Per-role border styling from `a:tcStyle/a:tcBdr`. These supply the * gridlines/edges a styled table inherits from its table style when the * cells carry no explicit per-cell `a:lnX` overrides. */ wholeTblBorders?: ParsedTableStyleBorders; firstRowBorders?: ParsedTableStyleBorders; lastRowBorders?: ParsedTableStyleBorders; firstColBorders?: ParsedTableStyleBorders; lastColBorders?: ParsedTableStyleBorders; band1HBorders?: ParsedTableStyleBorders; band2HBorders?: ParsedTableStyleBorders; band1VBorders?: ParsedTableStyleBorders; band2VBorders?: ParsedTableStyleBorders; seCellBorders?: ParsedTableStyleBorders; swCellBorders?: ParsedTableStyleBorders; neCellBorders?: ParsedTableStyleBorders; nwCellBorders?: ParsedTableStyleBorders; /** Per-role text styling from a:tcTxStyle. */ wholeTblText?: ParsedTableStyleText; firstRowText?: ParsedTableStyleText; lastRowText?: ParsedTableStyleText; firstColText?: ParsedTableStyleText; lastColText?: ParsedTableStyleText; band1HText?: ParsedTableStyleText; band2HText?: ParsedTableStyleText; band1VText?: ParsedTableStyleText; band2VText?: ParsedTableStyleText; seCellText?: ParsedTableStyleText; swCellText?: ParsedTableStyleText; neCellText?: ParsedTableStyleText; nwCellText?: ParsedTableStyleText; /** * Per-role 3D bevel + lighting from `a:tcStyle/a:cell3D` (CT_Cell3D), * distinct from the per-cell `a:tcPr/a:cell3D` {@link PptxTableCellStyle} * already supports. None of PowerPoint's 74 built-in gallery styles use * this (0 hits in the built-in catalogue), so it only matters for a * hand-authored or third-party table style. */ wholeTblCell3D?: PptxTableCell3D; firstRowCell3D?: PptxTableCell3D; lastRowCell3D?: PptxTableCell3D; firstColCell3D?: PptxTableCell3D; lastColCell3D?: PptxTableCell3D; band1HCell3D?: PptxTableCell3D; band2HCell3D?: PptxTableCell3D; band1VCell3D?: PptxTableCell3D; band2VCell3D?: PptxTableCell3D; seCellCell3D?: PptxTableCell3D; swCellCell3D?: PptxTableCell3D; neCellCell3D?: PptxTableCell3D; nwCellCell3D?: PptxTableCell3D; } /** * A single fill reference within a table style section. * * @example * ```ts * const fill: ParsedTableStyleFill = { * schemeColor: "accent1", * tint: 40000, // 40% tint * }; * // => satisfies ParsedTableStyleFill * ``` */ declare interface ParsedTableStyleFill { /** * Theme colour key (e.g. `accent1`, `dk1`). Empty string when the fill is a * non-scheme fill (explicit sRGB, gradient, pattern, or none) that carries * no theme colour reference; the renderer then resolves {@link color}, * {@link gradient}, {@link pattern}, or {@link noFill} instead. */ schemeColor: string; /** Tint value (0-100 000). */ tint?: number; /** Shade value (0-100 000). */ shade?: number; /** * Alpha (opacity) value (0-100 000, where 100 000 is fully opaque) from an * `a:alpha` child of `a:schemeClr`/`a:srgbClr`. Several built-in table * styles (e.g. "Light Style 1/3", "Themed Style 1/2") band their rows with * a partially transparent tint of the theme colour rather than a tint/shade * blend. */ alpha?: number; /** Explicit sRGB hex colour (e.g. `#FF8800`) from `a:srgbClr`. */ color?: string; /** The fill was `a:noFill`: renders transparent and clears lower layers. */ noFill?: boolean; /** Gradient fill parsed from `a:gradFill`. */ gradient?: ParsedTableStyleGradient; /** Preset pattern fill parsed from `a:pattFill`. */ pattern?: ParsedTableStylePattern; /** Image texture fill parsed from `a:blipFill`. */ image?: ParsedTableStyleImage; } /** A gradient fill parsed from a table style section's `a:gradFill`. */ declare interface ParsedTableStyleGradient { /** Ordered colour stops. */ stops: ParsedTableStyleGradientStop[]; /** Linear gradient angle in degrees (from `a:lin@ang`, 60000ths -> deg). */ angle?: number; /** Gradient family: linear (`a:lin`) or radial (`a:path`). */ type: 'linear' | 'radial'; } /** A single colour stop within a {@link ParsedTableStyleGradient}. */ declare interface ParsedTableStyleGradientStop { /** Stop position as a percentage (0-100). */ position: number; /** Stop colour (scheme or explicit sRGB). */ fill: ParsedTableStyleFill; } /** * An image texture fill parsed from a table style section's `a:blipFill`. * * `ppt/tableStyles.xml` is a presentation-level part parsed once (not * per-slide), so this mirrors the per-CELL `a:tcPr/a:blipFill` two-field lazy * pattern (`PptxTableCellStyle.backgroundImageFillPath` / * `backgroundImageFillData`): `path` starts out as a raw archive-relative * path (or an already-external `http(s):`/`data:` URL), and a load pipeline * patches it to a displayable URL in `data` once resolved. */ declare interface ParsedTableStyleImage { /** Archive-relative path, or an already-displayable external/data URL. */ path?: string; /** Displayable URL once a load pipeline has resolved `path`. */ data?: string; } /** * Map of GUID → table style entry. * * Parsed from `ppt/tableStyles.xml` and indexed by the style GUID * referenced in `a:tblPr@tblStyle`. * * @example * ```ts * const styles: ParsedTableStyleMap = { * "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}": { * styleId: "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}", * styleName: "Medium Style 2 - Accent 1", * accentKey: "accent1", * }, * }; * // => satisfies ParsedTableStyleMap * ``` */ declare type ParsedTableStyleMap = Record; /** A preset pattern fill parsed from a table style section's `a:pattFill`. */ declare interface ParsedTableStylePattern { /** OOXML preset name (e.g. `ltDnDiag`) from `a:pattFill@prst`. */ preset: string; /** Foreground colour (`a:fgClr`). */ foreground?: ParsedTableStyleFill; /** Background colour (`a:bgClr`). */ background?: ParsedTableStyleFill; } /** * A single entry in the parsed table style map. * * Contains fill colours for whole-table, banded rows/columns, first/last * row, and first/last column sections. * * @example * ```ts * const entry: ParsedTableStyleEntry = { * styleId: "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}", * styleName: "Medium Style 2 - Accent 1", * accentKey: "accent1", * wholeTblFill: { schemeColor: "accent1", tint: 20000 }, * band1HFill: { schemeColor: "accent1", tint: 40000 }, * firstRowFill: { schemeColor: "accent1" }, * }; * // => satisfies ParsedTableStyleEntry * ``` */ /** Text properties from a:tcTxStyle in a table style section. */ declare interface ParsedTableStyleText { /** Font bold. */ bold?: boolean; /** Font italic. */ italic?: boolean; /** Font underline (from `a:tcTxStyle@u`, any value other than `none`). */ underline?: boolean; /** Font colour as theme scheme key. */ fontSchemeColor?: string; /** Font colour tint (0-100 000). */ fontTint?: number; /** Font colour shade (0-100 000). */ fontShade?: number; /** Explicit sRGB hex font colour (e.g. `#FF0000`) from `a:srgbClr`. */ fontColor?: string; /** Typeface from `a:font@typeface` (latin font). */ fontFace?: string; /** Font-collection index from `a:fontRef@idx` (`minor`, `major`, `none`). */ fontRefIdx?: string; } /** The viewer-owned edit session identifies the part to overlay, never just a global element ID. */ export declare interface PendingInlineTextEdit { snapshot: InlineTextEditSnapshot; text?: string; target: { slideId: string; } | { masterView: MasterViewTarget; }; } /** Framework-neutral picture-bullet source, sizing, and accessible fallback. */ declare interface PictureBulletMarker { src?: string; sizePx: number; fallbackMarker: string; accessibleLabel: string; imageRelId?: string; } /** * A picture element from an OOXML `` node with `type: "picture"`. * * Functionally identical to {@link ImagePptxElement} but distinguished by * the `type` discriminant for semantic clarity. */ declare interface PicturePptxElement extends PptxElementBase, PptxShapeProperties, PptxCustomPathProperties, PptxImageProperties, PptxAccessibilityProperties, PptxPictureNonVisualProperties { type: 'picture'; } /** * Text styling for a single indent level (0–8) inside a placeholder’s * `a:lstStyle`. * * Used during placeholder inheritance to fill in defaults for font, * bullet, and spacing properties the slide element does not override. * * @example * ```ts * const level0: PlaceholderTextLevelStyle = { * fontSize: 32, * bold: true, * bulletChar: "•", * }; * // => satisfies PlaceholderTextLevelStyle * ``` */ declare interface PlaceholderTextLevelStyle { fontFamily?: string; /** * The RAW `a:defRPr/a:latin/@typeface` string (verbatim: a theme alias * such as `+mj-lt`/`+mn-lt`, or a literal face name) {@link fontFamily} * was resolved from. Master/layout text styles are parsed once and * cached, so `fontFamily` is a resolved-for-display snapshot; re-emitting * it as the literal name on every save (the master-level analogue of * `colorChoiceXml` below) flattens the theme alias the moment ANYTHING * about the deck is rewritten, even when this level was never touched. * Absent when the level declares no `a:latin`. */ fontTypefaceXml?: string; /** * Snapshot of {@link fontFamily} exactly as parsed, before any edit. The * save path diffs the live value against this: unchanged means re-emit * {@link fontTypefaceXml} verbatim (preserve the alias); different means * a genuine edit, so the new literal name is written instead. */ resolvedFontFamily?: string; fontSize?: number; bold?: boolean; italic?: boolean; color?: string; /** * The `a:defRPr/a:solidFill` node this level's {@link color} came from. * * Master and layout text styles are parsed and cached before any slide is, * so a scheme alias such as `tx1` was resolved through the map that was * active then. A slide carrying `p:clrMapOvr` routes the same alias * somewhere else, so the alias has to be resolved again against the slide * that is inheriting it; {@link color} is only the reading taken at parse * time. Absent when the level declares no colour, or declares a literal one. */ colorChoiceXml?: XmlObject; bulletChar?: string; bulletAutoNumType?: string; bulletFontFamily?: string; bulletSizePercent?: number; /** Bullet colour from `a:buClr` as hex string. */ bulletColor?: string; /** * The colour-choice node inside `a:buClr` this level's {@link bulletColor} * resolved from (`a:schemeClr` / `a:sysClr` / `a:prstClr` / `a:srgbClr`, * transforms included), mirroring `BulletInfo.colorXml`. Re-emitted * verbatim on save so a themed bullet is not downgraded to a literal * `a:srgbClr`. Absent when the level declares no bullet colour. */ bulletColorXml?: XmlObject; /** Bullet size in points from `a:buSzPts`. */ bulletSizePts?: number; /** True when `a:buNone` is present at this level. */ bulletNone?: boolean; marginLeft?: number; /** Paragraph right margin in px (from `@_marR` EMU). */ marginRight?: number; indent?: number; /** * Paragraph alignment as a `TextStyle['align']` token (`left`, `center`, * `right`, `justify`, `justLow`, `dist`, `thaiDist`), never the raw OOXML * `@algn` value. */ alignment?: string; /** Right-to-left paragraph direction (`@rtl`). */ rtl?: boolean; /** Tab stops from `a:tabLst/a:tab` (positions in px). */ tabStops?: TextStyle['tabStops']; lineSpacing?: number; lineSpacingExactPt?: number; /** * Space before the paragraph in px, resolved from EITHER `a:spcPts` * (absolute) or `a:spcPct` (a percentage of this level's own `a:defRPr` * font size) - the OOXML source is not distinguishable from this field * alone. See {@link spaceBeforePercent} / {@link resolvedSpaceBefore}. */ spaceBefore?: number; spaceAfter?: number; /** * Snapshot of {@link spaceBefore} / {@link spaceAfter} exactly as parsed. * Diffed the same way as {@link resolvedFontFamily}: unchanged means the * writer re-emits the ORIGINAL form (`a:spcPct` when * {@link spaceBeforePercent} / {@link spaceAfterPercent} is set); a value * that has since moved away from the snapshot is a genuine edit and is * always written as `a:spcPts`, since an editor works in absolute units. */ resolvedSpaceBefore?: number; resolvedSpaceAfter?: number; /** * The raw `a:spcPct` fraction (e.g. `0.2` for 20%) {@link spaceBefore} / * {@link spaceAfter} was resolved from, when the source used percentage * spacing rather than `a:spcPts`. Absent when the source used `a:spcPts` * (or authored no spacing at all). */ spaceBeforePercent?: number; spaceAfterPercent?: number; /** Default tab interval in CSS pixels (`a:lvlXpPr/@defTabSz`). */ defaultTabSize?: number; /** Whether East Asian line-breaking rules are enabled. */ eaLineBreak?: boolean; /** Whether Latin line-breaking rules are enabled. */ latinLineBreak?: boolean; /** Font vertical alignment within the text line. */ fontAlignment?: string; /** Whether end punctuation may hang outside the text frame. */ hangingPunctuation?: boolean; } export declare const PowerPointViewer: typeof __VLS_export; /** * Framework-agnostic imperative API contract for the PowerPoint viewer. * * Each binding (React `forwardRef` handle, Vue `defineExpose`, Angular public * methods) implements this interface so consumers get a consistent progressive * API regardless of framework. */ declare interface PowerPointViewerAPI { /** Serialise the current presentation to `.pptx` bytes. */ getContent: () => Promise; /** Navigate to a specific slide by zero-based index. */ goTo: (slideIndex: number) => void; /** Navigate to the previous slide. */ goPrev: () => void; /** Navigate to the next slide. */ goNext: () => void; /** Undo the last editing action. No-op when nothing to undo. */ undo: () => void; /** Redo the last undone action. No-op when nothing to redo. */ redo: () => void; /** Whether an undo action is available. */ canUndo: () => boolean; /** Whether a redo action is available. */ canRedo: () => boolean; /** Get the current zoom level (1 = 100%). */ getZoom: () => number; /** Set the zoom level (clamped to min/max bounds). */ setZoom: (level: number) => void; /** Zoom in by one step. */ zoomIn: () => void; /** Zoom out by one step. */ zoomOut: () => void; /** Reset zoom to 100%. */ zoomReset: () => void; /** Get the current viewer mode. */ getMode: () => ViewerMode; /** Switch the viewer mode (e.g. 'edit', 'preview', 'present'). */ setMode: (mode: ViewerMode) => void; /** Get the zero-based active slide index. */ getActiveSlideIndex: () => number; /** Set the active slide by zero-based index (alias of goTo). */ setActiveSlideIndex: (index: number) => void; /** Get the total number of slides. */ getSlideCount: () => number; /** Whether the document has unsaved changes. */ isDirty: () => boolean; /** * Get the full slide array. Returns the actual `PptxSlide[]` from the * internal model with full type information (elements, notes, transitions, * animations, etc.). The returned reference is a snapshot; mutations are * not reflected back unless done via the manipulation methods. */ getSlides: () => readonly PptxSlide[]; /** Get a single slide by zero-based index, or undefined if out of range. */ getSlide: (index: number) => PptxSlide | undefined; /** Get the currently active slide. */ getActiveSlide: () => PptxSlide | undefined; /** Add a blank slide after the given index (or at end if omitted). */ addSlide: (afterIndex?: number) => void; /** Delete slides at the given zero-based indexes. At least one slide is kept. */ deleteSlides: (indexes: number[]) => void; /** Duplicate slides at the given zero-based indexes. */ duplicateSlides: (indexes: number[]) => void; /** Move a slide from one position to another. */ moveSlide: (fromIndex: number, toIndex: number) => void; /** Toggle the hidden flag on slides at the given indexes. */ toggleHideSlides: (indexes: number[]) => void; /** * Get the elements on a slide. Defaults to the active slide when * `slideIndex` is omitted. Returns the full `PptxElement[]` with * all type-specific properties intact. */ getElements: (slideIndex?: number) => readonly PptxElement[]; /** Get a single element by ID from the active slide (or a specified slide). */ getElementById: (elementId: string, slideIndex?: number) => PptxElement | undefined; /** * Append and select a deep copy on the active ordinary editable slide. * Assigns fresh element IDs without offsetting the supplied geometry. * Returns the new root ID, or undefined when insertion is unavailable. * Uses normal Undo/Redo grouping. Models must be self-contained or refer to * assets in this document; this does not import foreign PPTX relationships. */ addElement: (element: PptxElement) => string | undefined; /** * Update one or more properties of an element by ID on the active slide. * Accepts a `Partial` patch (e.g. `{ x: 100, width: 300 }`). */ updateElement: (elementId: string, updates: Partial) => void; /** Atomically patch ordinary slide elements as one independent undo step. Rejects invalid batches. */ updateElements: (updates: readonly ElementUpdate[], options?: ElementUpdateOptions) => Promise; /** Delete elements by their IDs from the active slide. */ deleteElements: (elementIds: string[]) => void; /** * Duplicate an element on the active slide. * Returns the new element's ID, or undefined if the source was not found. */ duplicateElement: (elementId: string) => string | undefined; /** Get the IDs of currently selected elements. */ getSelectedElementIds: () => string[]; /** Programmatically select elements by their IDs. */ selectElements: (ids: string[]) => void; /** Clear the current selection. */ clearSelection: () => void; } /** * Events emitted by ``. * * These replace the React function-prop callbacks: * - `onDirtyChange` → `@dirty-change` * - `onContentChange` → `@content-change` * - `onActiveSlideChange` → `@active-slide-change` * - `onModeChange` → `@mode-change` * - `onZoomChange` → `@zoom-change` * - `onSelectionChange` → `@selection-change` * - `onSlideCountChange` → `@slide-count-change` */ export declare interface PowerPointViewerEmits { /** Fired when the unsaved-changes flag toggles. */ (e: 'dirty-change', isDirty: boolean): void; /** * Fired with serialised bytes on each in-memory content change (after * edits) and when autosave persists the presentation. */ (e: 'content-change' | 'autosave', content: Uint8Array): void; /** Fired when the active slide, zoom level, or slide count changes. */ (e: 'active-slide-change' | 'zoom-change' | 'slide-count-change', value: number): void; /** Fired when the viewer mode changes. */ (e: 'mode-change', mode: string): void; /** Fired when element selection changes. */ (e: 'selection-change', elementIds: string[]): void; /** Fired when the user starts a collaboration session from the Share dialog. */ (e: 'start-collaboration', config: CollaborationConfig): void; /** Fired when the user stops a collaboration session from the Share dialog. */ (e: 'stop-collaboration'): void; } /** * Imperative surface exposed via `defineExpose`, retrievable through a * template ref. Implements the shared {@link PowerPointViewerAPI} contract. * * @example * ```vue * * ``` */ export declare interface PowerPointViewerExpose extends PowerPointViewerAPI, ViewerCustomizationApi { /** Serialise the current presentation to `.pptx` bytes. */ getContent: () => Promise; } /** Public viewer props: React callbacks become Vue emits. */ export declare interface PowerPointViewerProps { /** Per-side fit allowance in CSS pixels; omission retains the existing default. */ fitPadding?: ViewportFitPadding; /** Positive fit-factor ceiling; null allows enlargement without a ceiling. */ maxFitScale?: number | null; /** PowerPoint content as Uint8Array (or ArrayBuffer). */ content: Uint8Array | ArrayBuffer; /** Licensed font sources supplied by the host application. */ fonts?: ViewerFontSource[]; /** Original file path, used for autosave recovery. */ filePath?: string; /** Display name of the open document, shown in the title bar. */ fileName?: string; /** Whether editing actions are enabled. */ canEdit?: boolean; /** * Recovery autosave: after an edit the deck is re-serialised (always as a * plain, unencrypted package, because recovery has no password), stashed in * the shared IndexedDB store keyed by {@link filePath}, and emitted as * `@autosave`. It is a crash-safety net and never replaces the user's real * Save: the document stays dirty. On load, a newer snapshot is offered back * through a recovery prompt. * * **The prop is a policy ceiling; the title-bar AutoSave toggle is the user's * preference inside it.** `false` turns autosave off and makes the toggle * inert (a user cannot switch on what the application forbade). `true` or * omitted permits it, and the toggle decides, defaulting to on. Identical in * all five bindings; see `resolveAutosaveActivation` in `pptx-viewer-shared`. * * @default true */ autosave?: boolean; /** * Autosave debounce window in milliseconds. An explicit value is a host * policy and is honoured as given; omit it to follow the user's File > * Options > Save > "Save AutoRecover information every N minutes" (two * minutes by default). Was a private 2000ms default before the five bindings * were brought onto one rule. */ autosaveIntervalMs?: number; /** Optional class name applied to the root element. */ class?: string; /** * Display name used as the author for comments and annotations. * Falls back to `collaboration.userName` when collaborating, or `'You'`. */ authorName?: string; /** * Theme configuration for customising the viewer's appearance. * * Accepts partial color overrides, a custom border-radius, and arbitrary * CSS custom properties. Unset values fall back to the built-in dark theme. * * @see {@link ViewerTheme} */ theme?: ViewerTheme; /** * Optional real-time collaboration configuration. When provided, the viewer * joins a Yjs session (y-websocket or serverless y-webrtc) with live cursors, * remote selections, follow mode and elected-writer write-back. */ collaboration?: CollaborationConfig; /** Default values for the Share dialog fields. */ shareDefaults?: { roomId?: string; userName?: string; serverUrl?: string; }; /** * Host override for the File ▸ Open action. When provided, the built-in * native file picker is bypassed and this is invoked instead; the host is * then responsible for supplying a new `content` value. When omitted, the * viewer opens its own picker and loads the chosen presentation in place. */ onOpenFile?: () => void; /** * Opt in to the Three.js SmartArt renderer. When `true`, SmartArt diagrams * render as extruded 3D blocks on a WebGL canvas instead of flat SVG. * Requires the optional `three` peer dependency; when it is not installed * (or the diagram has no geometry), the viewer transparently falls back to * the SVG SmartArt renderer. Default `false`. */ smartArt3D?: boolean; /** * Opt in to the interactive Three.js surface-chart renderer. When `true`, * `surface`/`surface3D` charts render as a WebGL mesh * instead of the static SVG isometric * projection. Chart marks are not selectable/draggable in this mode. * Requires the optional `three` peer dependency; when it is not installed * (or the chart has no plottable grid), the viewer transparently falls back * to the SVG surface renderer. Default `false`. */ surfaceChart3D?: boolean; /** * Opt in to the interactive Three.js bar3D-chart renderer. When `true`, * `bar3D` charts render as real box meshes instead of the flat SVG oblique-projection * illusion. Chart marks are not selectable/draggable in this mode. * Requires the optional `three` peer dependency; when it is not installed * (or the chart has no plottable grid, or it is a horizontal 3-D Bar), the * viewer transparently falls back to the flat SVG bar3D renderer. Default * `false`. */ barChart3D?: boolean; /** * Opt in to the interactive Three.js line3D-chart renderer. When `true`, * `line3D` charts render as a real tube-path mesh per * series, one per depth ("series") plane, * instead of the flat SVG oblique-projection illusion. Chart marks are not * selectable/draggable in this mode. Requires the optional `three` peer * dependency; when it is not installed (or the chart has no plottable * grid), the viewer transparently falls back to the flat SVG line3D * renderer. Default `false`. */ lineChart3D?: boolean; /** * Opt in to the interactive Three.js area3D-chart renderer. When `true`, * `area3D` charts render as a real tube path + filled * ribbon mesh per series, one per depth ("series") plane, instead of the flat SVG oblique-projection illusion. * Chart marks are not selectable/draggable in this mode. Requires the * optional `three` peer dependency; when it is not installed (or the chart * has no plottable grid), the viewer transparently falls back to the flat * SVG area3D renderer. Default `false`. */ areaChart3D?: boolean; /** * Opt in to the interactive Three.js pie3D-chart renderer. When `true`, * `pie3D` charts render as real wedge meshes instead of the flat SVG oblique-projection * illusion. Chart marks are not selectable/draggable in this mode. * Requires the optional `three` peer dependency; when it is not installed * (or the chart has no plottable series), the viewer transparently falls * back to the flat SVG pie3D renderer. Default `false`. */ pieChart3D?: boolean; /** * Individual toolbar buttons and/or ribbon tabs to hide, letting a host * curate the chrome instead of only the all-or-nothing `canEdit` toggle. * Omit (default) to show everything, matching prior behaviour. * * @see {@link ToolbarActionId} */ hiddenActions?: ToolbarActionId[]; /** * Framework-neutral UI customisation. See docs/guide/customization.md. * * Hides ribbon tabs/buttons, Options pages/sections/settings, File tab * pages/cards, context-menu commands, panels, features and dialogs; locks * settings or sets host defaults; disables or remaps editor shortcuts. * Unioned with `hiddenActions`. The imperative helpers on the component * handle (`hideRibbonTab`, `lockSetting`, ...) edit the same state, and a * NEW object passed here replaces those imperative edits wholesale. */ customization?: ViewerCustomization; /** * Initial theme-catalog selection key (e.g. `'vermilionDark'`), used only * when no persisted preference exists. Has no effect when the `theme` prop * is set: an explicit `theme` always wins over the catalog selection. */ defaultThemeKey?: string; /** * Theme choices offered by File > Options > Appearance. Defaults to the * shared `THEME_CATALOG` (default / light / vermilion light / vermilion * dark). */ availableThemes?: ThemeCatalogEntry[]; /** * Host hook for the File > Options > Appearance theme picker. When * provided, the host owns persisting the choice (only this callback is * invoked); when omitted, the viewer persists the choice to `localStorage` * itself via the shared `writeStoredViewerPrefs`. */ onThemeChange?: (key: string) => void; /** * Initial locale code (e.g. `'fr'`), used only when no persisted * preference exists. */ defaultLocale?: string; /** * Locale choices offered by File > Options > Language. Defaults to every * locale registered with the host's `vue-i18n` instance (via * `useI18n().availableLocales`), mapped through the shared * `LOCALE_CATALOG` for display labels. */ availableLocales?: LocaleCatalogEntry[]; /** * Host hook for the File > Options > Language picker. When provided, the * host owns applying and persisting the locale switch (the viewer leaves * its own `vue-i18n` `locale` ref untouched); when omitted, the viewer * sets `locale.value` itself and persists the choice to `localStorage`. */ onLocaleChange?: (code: string) => void; /** * Optional sign-in hook point for File > Account. Disabled by default: the * Account page renders nothing extra unless `enabled: true` is passed. */ accountAuth?: AccountAuthConfig; /** * Optional AI assistant configuration. When provided, a Sparkles toggle * appears in the ribbon's quick-action strip and opens a right-hand chat * panel that can read and edit the open deck through the framework-agnostic * AI core. The panel (and its optional `@ai-sdk/vue` + `ai` peers) is * lazily loaded only when first opened; omit this prop to disable the * assistant entirely. * * @see {@link PptxAiConfig} */ ai?: PptxAiConfig; } /** * 3D scene/camera properties from `a:scene3d`. * * @example * ```ts * const scene: Pptx3DScene = { * cameraPreset: "perspectiveFront", * lightRigType: "threePt", * lightRigDirection: "t", * }; * // => satisfies Pptx3DScene * ``` */ declare interface Pptx3DScene { /** Camera preset type, e.g. "orthographicFront", "perspectiveFront". */ cameraPreset?: string; /** Camera field of view in 1/60000 degrees (`a:camera/@fov`). */ cameraFieldOfView?: number; /** Camera zoom as an OOXML percentage fraction (`a:camera/@zoom`, 1 = 100%). */ cameraZoom?: number; /** Camera rotation around X axis in 1/60000 degrees. */ cameraRotX?: number; /** Camera rotation around Y axis in 1/60000 degrees. */ cameraRotY?: number; /** Camera rotation around Z axis in 1/60000 degrees. */ cameraRotZ?: number; /** Light rig type, e.g. "threePt", "balanced", "harsh". */ lightRigType?: string; /** Light rig direction, e.g. "t", "b", "l", "r", "tl". */ lightRigDirection?: string; /** Light-rig rotation latitude in 1/60000 degrees. */ lightRigRotX?: number; /** Light-rig rotation longitude in 1/60000 degrees. */ lightRigRotY?: number; /** Light-rig rotation revolution in 1/60000 degrees. */ lightRigRotZ?: number; /** Whether a 3D backdrop plane is present (`a:backdrop`). */ hasBackdrop?: boolean; /** Backdrop plane anchor X in EMU. */ backdropAnchorX?: number; /** Backdrop plane anchor Y in EMU. */ backdropAnchorY?: number; /** Backdrop plane anchor Z in EMU. */ backdropAnchorZ?: number; /** Backdrop normal vector X component. */ backdropNormalX?: number; /** Backdrop normal vector Y component. */ backdropNormalY?: number; /** Backdrop normal vector Z component. */ backdropNormalZ?: number; /** Backdrop up vector X component. */ backdropUpX?: number; /** Backdrop up vector Y component. */ backdropUpY?: number; /** Backdrop up vector Z component. */ backdropUpZ?: number; } /** * 3D shape extrusion/bevel from `a:sp3d`. * * @example * ```ts * const shape3d: Pptx3DShape = { * extrusionHeight: 76200, * extrusionColor: "#4F81BD", * presetMaterial: "metal", * bevelTopType: "circle", * bevelTopWidth: 12700, * bevelTopHeight: 12700, * }; * // => satisfies Pptx3DShape * ``` */ declare interface Pptx3DShape { /** * Position of the shape along the Z axis, in EMU (`a:sp3d/@z`, default 0). * Independent of {@link extrusionHeight}: it moves the whole shape forward * or back in 3D space rather than adding depth to it, most commonly used to * stack several shapes at different depths under one `a:scene3d` camera. */ positionZ?: number; /** Extrusion height in EMU. */ extrusionHeight?: number; /** Extrusion colour. */ extrusionColor?: string; /** Contour width in EMU. */ contourWidth?: number; /** Contour colour. */ contourColor?: string; /** Preset material, e.g. "matte", "warmMatte", "metal". */ presetMaterial?: string; /** Top bevel type, e.g. "circle", "relaxedInset". */ bevelTopType?: string; /** Top bevel width in EMU. */ bevelTopWidth?: number; /** Top bevel height in EMU. */ bevelTopHeight?: number; /** Bottom bevel type, e.g. "circle", "relaxedInset". */ bevelBottomType?: string; /** Bottom bevel width in EMU. */ bevelBottomWidth?: number; /** Bottom bevel height in EMU. */ bevelBottomHeight?: number; } /** * Accessibility metadata from `p:cNvPr/a:extLst`'s "Mark as decorative" * vendor extension (issue G16). PowerPoint's Alt Text pane writes * `a:ext[@uri='{C183D7F6-B498-43B3-948B-1728B52AA6E4}']/adec:decorative * val="1"` when a shape or image is marked decorative; mixed into the * element variants whose `p:cNvPr` that pane covers. */ declare interface PptxAccessibilityProperties { /** * Whether the element is marked decorative. When true, alt text / * aria-label / Markdown export should skip describing the element even * when {@link PptxImageProperties.altText} (or similar) is present. */ isDecorative?: boolean; } /** * Action types: hyperlinks, slide jumps, macros, and action buttons. * * @module pptx-types/actions */ /** * A parsed shape-level action from `a:hlinkClick` or `a:hlinkHover`. * * @example * ```ts * const link: PptxAction = { * url: "https://example.com", * tooltip: "Visit Example", * highlightClick: true, * }; * * const slideJump: PptxAction = { * action: "ppaction://hlinksldjump", * targetSlideIndex: 3, * }; * // => satisfies PptxAction * ``` */ declare interface PptxAction { /** Relationship ID referencing the action target. */ rId?: string; /** OOXML action string (e.g. `ppaction://hlinksldjump`). */ action?: string; /** Tooltip text shown on hover. */ tooltip?: string; /** Whether the shape should highlight on click. */ highlightClick?: boolean; /** Resolved URL or file path from the slide relationship map. */ url?: string; /** Zero-based index into the slides array for internal slide jumps. */ targetSlideIndex?: number; /** Relationship ID of an optional click sound (`a:snd/@r:embed`). */ soundRId?: string; /** Resolved media target path for the optional click sound. */ soundPath?: string; /** * `CT_Hyperlink/@endSnd` (ECMA-376 20.1.2.2.23): PowerPoint's Action * Settings "Stop previous sound" checkbox. Round-tripped for now (issue * G14); not yet wired into playback. */ endSnd?: boolean; } /** * An ActiveX control reference from `p:controls / p:control`. * * ActiveX form controls (buttons, text boxes, check boxes, combo boxes, etc.) * are embedded via OLE parts and referenced by relationship ID in the slide XML. * * @see ECMA-376 Part 1, §19.3.1.3 (controls), §19.3.1.2 (control) */ declare interface PptxActiveXControl { /** Relationship ID referencing the ActiveX binary part. */ relId: string; /** Control name from @name attribute. */ name?: string; /** Shape ID this control is linked to (from @spid). */ shapeId?: string; /** * `p:control/@showAsIcon` (CT_Control, ECMA-376 S19.3.1.2): whether the * control renders as its static icon rather than its live appearance. * `undefined` when the source authored no explicit value (schema default * `false`). */ showAsIcon?: boolean; /** * `p:control/@imgW` in EMU (ST_PositiveCoordinate32): the width the host * reserves for the control's icon/preview image. Distinct from * {@link width}, which is the fallback `p:pic`'s own `a:ext/@cx` in px; * `imgW`/`imgH` are direct attributes on `p:control` itself. */ imgWidthEmu?: number; /** `p:control/@imgH` in EMU (ST_PositiveCoordinate32). @see imgWidthEmu */ imgHeightEmu?: number; /** X position (px) of the control's fallback picture, if present. */ x?: number; /** Y position (px) of the control's fallback picture, if present. */ y?: number; /** Width (px) of the control's fallback picture, if present. */ width?: number; /** Height (px) of the control's fallback picture, if present. */ height?: number; /** * Relationship ID of the control's static fallback picture * (`mc:AlternateContent > mc:Fallback > p:pic > p:blipFill > a:blip@r:embed`). * Renderers resolve this to an image so a control shows its last static * frame instead of a blank area (the live ActiveX cannot run in a viewer). */ fallbackImageRelId?: string; /** Raw XML for round-trip preservation. */ rawXml?: XmlObject; } /** Behavior after animation finishes. */ declare type PptxAfterAnimationAction = 'none' | 'hideOnNextClick' | 'hideAfterAnimation' | 'dimToColor'; /** * Implemented by each binding to expose its live editor to the AI core. * * Read methods must be cheap and synchronous. Write methods must route through * the binding's editor-history layer so AI edits are undoable like manual ones. */ export declare interface PptxAiBridge { /** Return a summary of the whole deck. */ getDeckMeta(): PptxAiDeckMeta; /** Return the deck's slides. Callers must not mutate the returned array. */ getSlides(): PptxSlide[]; /** Return the zero-based index of the active slide. */ getActiveSlideIndex(): number; /** Return the resolved presentation theme, when available. */ getTheme(): PptxTheme | undefined; /** Return the underlying core handler, when the binding exposes one. */ getHandler(): PptxHandler | undefined; /** Navigate the viewer to a slide by zero-based index. */ goToSlide(index: number): void; /** Select the given elements on a slide (empty array clears selection). */ selectElements(slideIndex: number, elementIds: string[]): void; /** * Apply a slides updater as a single, atomic, undoable history entry. The * binding is responsible for cloning current slides before calling * `updater` and for installing the result. */ applySlidesUpdate(updater: PptxAiSlidesUpdater, label: string): void; /** Apply field updates to one element as a single history entry. */ updateElement(slideIndex: number, elementId: string, updates: PptxAiElementUpdate): void; /** Apply partial theme updates as a single history entry. */ applyTheme(updates: Partial): void; /** * Return the full parsed {@link PptxData} for the open deck, with the live * (edited) slides and theme overlaid. Enables `pptx-viewer-mcp` tools that * read presentation-level state (metadata, sections, layouts, presentation * properties). Optional: when absent, the AI core synthesises a minimal * PptxData from slides + dimensions, which is enough for every slide/theme * tool but not for presentation-level reads. */ getDeckData?(): PptxData | undefined; /** * Commit a whole-deck {@link PptxData} mutation as one undoable history entry. * Used to apply presentation-level MCP tool results (metadata, sections, * canvas size, presentation properties, layouts). Optional: when absent, * those tools report they are not supported in this viewer; slide/theme tools * are unaffected (they route through {@link PptxAiBridge.applySlidesUpdate} * and {@link PptxAiBridge.applyTheme}). */ applyDeckData?(updater: PptxAiDataUpdater, label: string): void; /** * Return the slides / elements the user has scoped the assistant to, if any. * When present and non-empty, the context builder tells the model to focus on * exactly these targets. Optional so existing bridges satisfy the contract * without change; a bridge that does not implement it behaves as before (no * focus scoping). */ getFocusedTargets?(): PptxAiFocusedTarget[]; /** Surface a transient message in the host UI (toast / status line). */ notify?(message: string, level?: PptxAiNotifyLevel): void; } /** Complete host configuration for an AI chat session. */ export declare interface PptxAiConfig { connection: PptxAiConnection; /** Extra host instructions appended to the base system prompt. */ systemPromptExtras?: string; tools?: { /** Allowlist. When set, only these tools are exposed. */ enabled?: PptxAiToolName[]; /** Denylist, applied after `enabled`. */ disabled?: PptxAiToolName[]; /** Additional host-defined tools merged into the tool set. */ extra?: ToolSet; }; /** Default `'stage'`. */ writePolicy?: PptxAiWritePolicy; /** Default `'outline'`. */ contextStrategy?: PptxAiContextStrategy; history?: PptxAiHistoryHooks; /** * How AI edits are animated on the canvas so the user can watch them land * (glide old->new, fade/scale in-out, glow-pulse). Omit for the defaults; * set `{ enabled: false }` to turn it off. */ changeAnimation?: AiChangeAnimationConfig; onError?(error: Error): void; } /** How the assistant reaches a language model. */ export declare type PptxAiConnection = /** * Post messages to a host backend route (recommended for production so the * provider API key stays server-side). Maps to `DefaultChatTransport`. */ { kind: 'endpoint'; api: string; headers?: Resolvable>; body?: Resolvable>; credentials?: RequestCredentials; fetch?: typeof globalThis.fetch; } | /** * Run a language model in-process in the browser (bring-your-own key / * local model). Maps to a `ToolLoopAgent` behind a `DirectChatTransport`. */ { kind: 'model'; model: LanguageModel; system?: string; maxSteps?: number; } | /** Provide a fully-constructed transport (advanced / testing escape hatch). */ { kind: 'transport'; transport: ChatTransport; }; /** Which deck context is fed to the model with each turn. */ export declare type PptxAiContextStrategy = 'outline' | 'current-slide' | 'none'; /** * A pure updater over the whole parsed deck ({@link PptxData}). Mirrors the * `pptx-viewer-mcp` tool model (data in, mutated data out) so presentation-level * MCP tools (metadata, sections, canvas size, presentation properties, layouts) * can be committed as ONE undoable history entry through {@link * PptxAiBridge.applyDeckData}. Optional: bindings that only track slide/theme * state can omit it, in which case those presentation-level tools report that * they are unavailable in this viewer while every slide/theme tool still works. */ declare type PptxAiDataUpdater = (data: PptxData) => PptxData; /** Lightweight, model-friendly summary of the whole deck. */ declare interface PptxAiDeckMeta { /** Total number of slides. */ slideCount: number; /** Zero-based index of the currently active slide. */ activeSlideIndex: number; /** Deck title, when known (first slide title / core properties). */ title?: string; /** Slide canvas width in CSS pixels. */ width: number; /** Slide canvas height in CSS pixels. */ height: number; } /** Field-level updates for a single element, mirroring the MCP update vocab. */ declare interface PptxAiElementUpdate { x?: number; y?: number; width?: number; height?: number; rotation?: number; opacity?: number; hidden?: boolean; flipHorizontal?: boolean; flipVertical?: boolean; text?: string; fontSize?: number; fontFamily?: string; fontColor?: string; bold?: boolean; italic?: boolean; underline?: boolean; align?: 'left' | 'center' | 'right' | 'justify'; fillColor?: string; strokeColor?: string; strokeWidth?: number; } /** * A target the user has scoped the assistant to: either a whole slide or a * single element on a slide. Returned by {@link PptxAiBridge.getFocusedTargets} * so the context builder can tell the model exactly what to focus on. */ declare type PptxAiFocusedTarget = { kind: 'slide'; slideIndex: number; } | { kind: 'element'; slideIndex: number; elementId: string; }; /** Optional per-session history persistence hooks. */ declare interface PptxAiHistoryHooks { load?(id: string): Promise; save?(id: string, messages: PptxAiUIMessage[]): Promise; } /** Severity hint for {@link PptxAiBridge.notify}. */ declare type PptxAiNotifyLevel = 'info' | 'success' | 'warning' | 'error'; /** * A pure updater over the deck's slides. It receives a deep clone of the * current slides (mutation-safe) and returns the next slides array. The bridge * commits the returned array as ONE history entry. */ declare type PptxAiSlidesUpdater = (slides: PptxSlide[]) => PptxSlide[]; /** * Canonical name of every tool the assistant can call. Document tools mirror the * `pptx-viewer-mcp` server exactly (they ARE the same functions, run against the * live deck); the viewer-only tools (navigation, deck outline, element/notes * readers, table merge) have no MCP counterpart. */ export declare type PptxAiToolName = 'get_deck_overview' | 'get_slide' | 'get_element' | 'get_speaker_notes' | 'find_text' | 'get_theme' | 'go_to_slide' | 'select_elements' | 'merge_tables' | 'get_metadata' | 'get_layouts' | 'find_placeholders' | 'get_presentation_properties' | 'run_accessibility_check' | 'convert_to_markdown' | 'export_to_json' | 'add_element' | 'update_element' | 'delete_elements' | 'arrange_elements' | 'clone_element' | 'set_element_animation' | 'group_elements' | 'ungroup_elements' | 'batch_update_elements' | 'update_element_style' | 'replace_geometry' | 'set_element_lock' | 'manage_hyperlinks' | 'replace_text' | 'manage_comments' | 'update_table_cells' | 'manage_table_structure' | 'create_chart' | 'update_chart' | 'add_chart_series' | 'remove_chart_series' | 'update_chart_series_data' | 'manage_smart_art' | 'apply_template' | 'add_slide' | 'duplicate_slide' | 'delete_slides' | 'reorder_slides' | 'update_slide_properties' | 'set_slide_transition' | 'apply_theme_preset' | 'update_theme_colors' | 'update_theme_fonts' | 'set_canvas_size' | 'update_metadata' | 'manage_sections' | 'update_presentation_properties' | 'import_from_json' | 'apply_layout'; /** The UI message shape exchanged with the assistant. Alias of the SDK type. */ export declare type PptxAiUIMessage = UIMessage; /** How writes proposed by the assistant reach the document. */ export declare type PptxAiWritePolicy = 'stage' | 'approve' | 'auto'; /** One behaviour child of an effect, tagged by its OOXML element. */ declare type PptxAnimationBehavior = PptxSetBehavior | PptxAnimBehavior | PptxAnimEffectBehavior | PptxAnimScaleBehavior | PptxAnimRotBehavior | PptxAnimMotionBehavior; /** Timing of one behaviour, from its own `p:cBhvr/p:cTn`. */ declare interface PptxAnimationBehaviorTiming { /** `p:cTn/@dur` in ms; absent when `indefinite` or unset. */ durationMs?: number; /** Start offset in ms from `p:stCondLst/p:cond/@delay`, relative to the effect start. */ delayMs?: number; /** `p:cTn/@accel` as a 0..1 fraction of the behaviour's duration. */ accel?: number; /** `p:cTn/@decel` as a 0..1 fraction of the behaviour's duration. */ decel?: number; /** `p:cTn/@autoRev`: play forward, then backward, doubling the active time. */ autoReverse?: boolean; /** `p:cTn/@repeatCount` in plain iterations (OOXML stores thousandths). */ repeatCount?: number; /** `p:cTn/@tmFilter`: the raw `"t,v; t,v; ..."` time remapping list. */ tmFilter?: string; } /** Direction for fly-in / fly-out / wipe effects. */ declare type PptxAnimationDirection = 'fromLeft' | 'fromRight' | 'fromTop' | 'fromBottom' | 'fromTopLeft' | 'fromTopRight' | 'fromBottomLeft' | 'fromBottomRight'; /** * Parsed `p:animEffect/@filter` (+ `@transition`) descriptor. ECMA-376 * describes `@filter` as a free-form string of the form `family(subtype)`, * optionally followed by `;`-separated fallback candidates (only the first * is honoured, per ECMA-376 S19.5.3's "first supported filter wins" rule). * * @example * ```ts * const f: PptxAnimationEffectFilter = { family: 'wipe', subtype: 'up', transition: 'in', raw: 'wipe(up)' }; * ``` */ declare interface PptxAnimationEffectFilter { /** Filter family name (e.g. `"wipe"`, `"barn"`, `"checkerboard"`), lowercased. */ family: string; /** * Parenthesised subtype/direction token verbatim (e.g. `"up"`, * `"inVertical"`, `"across"`, `"4"`). Absent when the filter has no * subtype (e.g. bare `"dissolve"`). */ subtype?: string; /** * `p:animEffect/@transition`: `"in"` reveals the target (the OOXML * default when the attribute is omitted), `"out"` conceals it, `"none"` * applies the filter without a visibility change (a static filter pass). */ transition?: 'in' | 'out' | 'none'; /** Raw filter string exactly as authored, for round-trip/debugging. */ raw: string; } /** * `p:spTgt/p:graphicEl` (CT_TLGraphicalObjectBuildElement, ECMA-376 S19.5.34): * identifies exactly which series/category/element of a chart or diagram * build a per-stage effect reveals, when a deck authors one effect per stage * instead of a single staged `p:bldGraphic` reveal. */ declare interface PptxAnimationGraphicElementTarget { /** Which graphic kind: `p:dgm` (diagram) or `p:chart`. */ kind: 'dgm' | 'chart'; /** `@_seriesIdx`, 0-based series index, when the target is series-scoped. */ seriesIdx?: number; /** `@_categoryIdx`, 0-based category index, when the target is category-scoped. */ categoryIdx?: number; /** * `p:dgm/@_id` (CT_TLBuildDiagram, ECMA-376 S19.5.10): the diagram DATA MODEL * point id (`dgm:pt/@modelId`) this per-stage effect reveals, when a * `p:bldDgm` build authors one effect per node instead of a single staged * reveal. `dgm`-kind targets only; a `chart`-kind target never carries this. * Matches `PptxSmartArtNode.id` (parsed from the same `@modelId`), so a * diagram renderer can reveal the exact authored node. */ id?: string; /** * `@_bldStep`: `ST_TLChartBuildStep` (`category` / `categoryEl` / `series` / * `seriesEl`) for a `chart`-kind target, or `ST_TLDiagramBuildStep` * (`sp` / `bg`) for a `dgm`-kind target. */ bldStep?: string; } /** Iteration configuration from `p:iterate`. */ declare interface PptxAnimationIterate { /** Iteration type: el (element), lt (letter), wd (word). */ type: 'el' | 'lt' | 'wd'; /** Whether to iterate backwards. */ backwards?: boolean; /** Timing interval (percentage of total duration, in 1000ths). */ tmPct?: number; /** Absolute timing interval in ms. */ tmAbs?: number; } /** * Single keyframe parsed from a `p:tav` element (CT_TLTimeAnimateValue). * * Each entry in a `p:tavLst` has a time fraction (`@_tm`, in 1000ths of the * total duration; or the literal "indefinite" / "large") and a typed value * child under `p:val/p:strVal|p:boolVal|p:intVal|p:fltVal|p:clrVal`. * * @see ECMA-376 §19.5.30 CT_TLAnimVariantList / §19.5.92 CT_TLTimeAnimateValue */ declare interface PptxAnimationKeyframe { /** * Time fraction. A finite number is the OOXML `@_tm` integer (0–100000 * for percentage, where 100000 = 100% of duration). A string preserves * special tokens ("indefinite", "large"). */ tm: number | string; /** Decoded keyframe value. */ value: string | boolean | number; /** Discriminant indicating which `p:val` child carried the value. */ valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr'; /** * Optional formula carried on `p:tav/@_fmla`. Preserved for round-trip * fidelity; consumers may use it to drive computed animation values. */ fmla?: string; /** * The typed theme reference when a `p:val/p:clrVal` stop is an * `a:schemeClr` (e.g. `accent1`), including any `tint`/`shade`/`lumMod`/ * `lumOff`/`alpha` children. {@link value} keeps the bare scheme name for * round-trip; a playback consumer needs this ref (resolved against the * deck's theme colour map) to turn the stop into a real CSS colour, which * the bare name alone cannot do. Absent for an `a:srgbClr` stop, whose * {@link value} is already a resolved `#rrggbb` hex string. */ colorRef?: PptxThemeColorRef; } /** * `p:spTgt/p:oleChartEl` (CT_TLOleChartTargetElement, ECMA-376 S19.5.44): * legacy pre-DrawingML OLE Graph chart sub-element targeting. */ declare interface PptxAnimationOleChartElementTarget { /** `@_type` (ST_TLOleChartSubelementType): entireChart / series / category / ... */ subelementType: string; /** `@_lvl`, optional sub-element level. */ level?: number; } /** * Built-in animation preset names used for entrance, exit, and emphasis effects. * * @example * ```ts * const preset: PptxAnimationPreset = "fadeIn"; * // => "fadeIn" — one of: none | fadeIn | flyIn | zoomIn | fadeOut | flyOut | zoomOut | spin | pulse | ... * ``` */ declare type PptxAnimationPreset = 'none' | 'appear' | 'fadeIn' | 'flyIn' | 'zoomIn' | 'bounceIn' | 'wipeIn' | 'splitIn' | 'dissolveIn' | 'wheelIn' | 'blindsIn' | 'boxIn' | 'floatIn' | 'riseUp' | 'swivel' | 'expandIn' | 'checkerboardIn' | 'flashIn' | 'peekIn' | 'randomBarsIn' | 'spinnerIn' | 'growTurnIn' | 'fadeOut' | 'flyOut' | 'zoomOut' | 'bounceOut' | 'wipeOut' | 'shrinkOut' | 'dissolveOut' | 'disappear' | 'spin' | 'pulse' | 'colorWave' | 'bounce' | 'flash' | 'growShrink' | 'teeter' | 'transparency' | 'boldFlash' | 'wave'; /** Repeat mode for animations. */ declare type PptxAnimationRepeatMode = 'untilNextClick' | 'untilEndOfSlide'; /** Sequence mode for paragraph-level animations. */ declare type PptxAnimationSequence = 'asOne' | 'byParagraph' | 'byWord' | 'byLetter'; /** A target selected by `p:tgtEl` in the PresentationML timing model. */ declare type PptxAnimationTarget = { type: 'shape'; shapeId: string; /** Whether `p:spTgt/p:bg` limits the effect to the shape background. */ backgroundOnly?: boolean; /** * `p:spTgt/p:subSp/@_spid`: the id of a shape NESTED inside the group * named by {@link shapeId} (CT_TLSubShapeId, ECMA-376 S19.5.71). * PowerPoint authors this when a user animates one member of a group * without ungrouping it: `shapeId` stays the outer group's id for * round-trip, but this sub-shape is the real playback target. */ subShapeId?: string; /** `p:spTgt/p:graphicEl`: chart/diagram series/category/element target. */ graphicElement?: PptxAnimationGraphicElementTarget; /** `p:spTgt/p:oleChartEl`: legacy OLE chart sub-element target. */ oleChartElement?: PptxAnimationOleChartElementTarget; rawXml?: XmlObject; } | { type: 'slide'; rawXml?: XmlObject; } | { type: 'sound'; relationshipId: string; name?: string; rawXml?: XmlObject; } | { type: 'ink'; shapeId: string; rawXml?: XmlObject; } | { type: 'unknown'; rawXml: XmlObject; }; /** * A read-only anchor representing one of the deck's own effect groups: a * top-level click group (`p:par` under `p:timing`'s main sequence) that this * app did not author, so it is never exposed as an editable * {@link PptxElementAnimation}. * * The authoring UI merges these anchors alongside `PptxSlide.animations` to * render the FULL animation sequence (editor-authored and deck-native * effects together) and lets an editor-authored entry be dragged to any * position relative to them. `order` is the anchor's position among ALL * top-level click groups (editor-owned and native) at load time, in the same * numbering space as {@link PptxElementAnimation.order}, so the two * populations sort into one coherent timeline. * * Anchors are never written back: on save, an untouched anchor's own click * group is repositioned (if an editor-authored effect was dragged past it) * but never mutated, so the deck's own effect stays byte-identical apart * from its position in the sequence. */ declare interface PptxAnimationTimelineAnchor { /** * Position of this group among all top-level click groups in the main * animation sequence at load time (dense, shared with editor entries' * `order`). */ order: number; /** Shape id(s) this group's effects target, for a readable UI label. */ targetIds: string[]; /** Effect preset classes present in the group (entr/exit/emph/path). */ presetClasses: Array<'entr' | 'exit' | 'emph' | 'path'>; } /** Animation timing curve. */ declare type PptxAnimationTimingCurve = 'ease' | 'ease-in' | 'ease-out' | 'linear'; /** Animation trigger type from OOXML `p:cTn`. */ declare type PptxAnimationTrigger = 'onClick' | 'onShapeClick' | 'onHover' | 'afterPrevious' | 'withPrevious' | 'afterDelay' | /** * Starts when a media element's playback reaches a named bookmark * (PowerPoint's "Trigger > On Bookmark"). The media element is * {@link PptxElementAnimation.triggerShapeId} and the bookmark * {@link PptxElementAnimation.triggerBookmark}; saved as an interactive * sequence gated on `p:cond evt="onMediaBookmark"` with a `p14:bmkTgt`. */ 'onMediaBookmark'; /** `p:anim`: a `p:tavLst` ramp or a `from`/`to`/`by` formula ramp. */ declare interface PptxAnimBehavior extends BehaviorBase { kind: 'anim'; calcMode?: 'discrete' | 'lin' | 'fmla'; valueType?: string; from?: string; to?: string; by?: string; keyframes: PptxAnimationKeyframe[]; } /** `p:animEffect`: a filter transition (`fade`, `wipe(down)`...). */ declare interface PptxAnimEffectBehavior extends BehaviorBase { kind: 'animEffect'; filter?: string; transition?: 'in' | 'out' | 'none'; } /** `p:animMotion`: a path (slide fractions) or a `from`/`to`/`by` offset. */ declare interface PptxAnimMotionBehavior extends BehaviorBase { kind: 'animMotion'; path?: string; origin?: string; from?: PptxBehaviorPoint; to?: PptxBehaviorPoint; by?: PptxBehaviorPoint; } /** `p:animRot`: rotation in degrees (OOXML stores 60000ths). */ declare interface PptxAnimRotBehavior extends BehaviorBase { kind: 'animRot'; from?: number; to?: number; by?: number; } /** `p:animScale`: scale factors as fractions (OOXML stores percent*1000, so `100000` = 1). */ declare interface PptxAnimScaleBehavior extends BehaviorBase { kind: 'animScale'; from?: PptxBehaviorPoint; to?: PptxBehaviorPoint; by?: PptxBehaviorPoint; zoomContents?: boolean; } /** * Extended (application) properties from `docProps/app.xml`. * * @example * ```ts * const app: PptxAppProperties = { * application: "Microsoft Office PowerPoint", * appVersion: "16.0000", * slides: 24, * words: 1500, * company: "Acme Corp", * }; * // => satisfies PptxAppProperties * ``` */ declare interface PptxAppProperties { /** Application name (e.g. "Microsoft Office PowerPoint"). */ application?: string; /** Application version string. */ appVersion?: string; /** Presentation format (e.g. "On-screen Show (16:9)"). */ presentationFormat?: string; /** Total number of slides. */ slides?: number; /** Number of hidden slides. */ hiddenSlides?: number; /** Number of notes slides. */ notes?: number; /** Total editing time in minutes. */ totalTime?: number; /** Number of words. */ words?: number; /** Number of paragraphs. */ paragraphs?: number; /** Company name. */ company?: string; /** Manager name. */ manager?: string; /** Template name. */ template?: string; /** Hyperlink base URL. */ hyperlinkBase?: string; /** Document security bitmask (``). */ docSecurity?: number; /** Number of multimedia clips (``). */ mmClips?: number; /** Whether thumbnail images were scaled to fit (``). */ scaleCrop?: boolean; /** Whether hyperlinks are current (``). */ linksUpToDate?: boolean; /** Whether the document is shared (``). */ sharedDoc?: boolean; /** Whether hyperlinks changed since last save (``). */ hyperlinksChanged?: boolean; } /** One generic `p:anim` behaviour inside a composed PowerPoint effect. */ declare interface PptxAttributeAnimation { /** Lowercased target attribute from `p:attrNameLst`. */ attrName: string; /** * Authored value stops from this behaviour's `p:tavLst`. Empty when the * behaviour instead uses the simpler `from`/`to`/`by` attribute form (see * below); at least one of `keyframes`, `from`/`to`, or `by` is present. */ keyframes: PptxAnimationKeyframe[]; /** * `p:anim/@_from` (a formula string, ECMA-376 S19.5.4 CT_TLAnimateBehavior): * the absolute starting value, used instead of `p:tavLst` when the * behaviour only has two endpoints. PowerPoint writes this form for some * built-in presets (e.g. "Grow And Turn"'s `ppt_x` fly-in): a bare * `p:anim from="..." to="..."` with no `p:tavLst` child at all. See * `animation-ppt-formula-ground-truth.md` in `pptx-viewer-shared` for the * real-PowerPoint sample this was found in. */ from?: string; /** `p:anim/@_to`: the absolute ending value. See {@link from}. */ to?: string; /** * `p:anim/@_by`: a DELTA formula added to wherever the attribute already * stands (as opposed to `from`/`to`'s absolute values), typically paired * with `p:cBhvr/@_additive="sum"` so it composites with a sibling * behaviour driving the same attribute instead of replacing it. */ by?: string; /** Duration from this behaviour's nested `p:cTn/@dur`. */ durationMs?: number; /** Start offset from this behaviour's nested `p:stCondLst`. */ delayMs?: number; /** * Interpolation mode from this behaviour's own `@_calcmode` * (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2): `discrete` snaps to * each `p:tav` stop with no interpolation, `lin` (the OOXML default) * interpolates linearly. `fmla` as the WHOLE behaviour's calc mode has * never been observed in a real PowerPoint file and is not consulted at * playback; what PowerPoint actually writes is `calcmode="lin"` with a * per-stop `p:tav/@fmla` (see {@link PptxAnimationKeyframe.fmla}), which * IS consulted regardless of this field's value. Absent means `lin`. */ calcMode?: 'discrete' | 'lin' | 'fmla'; /** * `p:anim/@_p14:bounceEnd` (Office 2010 `p14` extension attribute, * MS-OI29500), normalized to a 0-1 fraction of this behaviour's own * duration. PowerPoint's "Bounce End" effect option (COM: * `Effect.Timing.BounceEnd` + `BounceEndIntensity`) writes this on the * position-ramp `p:anim` node(s): the share of the duration spent * BOUNCING at the end. Measured from PowerPoint's own CreateVideo frames, * the travel completes at `1 - bounceEnd` and the rest is a damped * oscillation about the final value (see shared's `animation-bounce-end`). * Mirrored verbatim by PowerPoint onto the enclosing * `p:cTn/@_p14:presetBounceEnd`. Absent for every animation that doesn't * use this effect option (the overwhelming majority). */ bounceEnd?: number; } declare interface PptxAudioCdPosition { track: number; time?: number; /** Original `st` or `end` node, retained for lossless edits. */ rawXml?: XmlObject; } declare interface PptxBackgroundRemoval { /** Top edge of the retained rectangle (0..1 fraction of the image height). */ top: number; /** Bottom edge of the retained rectangle (0..1 fraction of the image height). */ bottom: number; /** Left edge of the retained rectangle (0..1 fraction of the image width). */ left: number; /** Right edge of the retained rectangle (0..1 fraction of the image width). */ right: number; /** Strokes marking regions the user forced to be foreground. */ foregroundMarks?: PptxBackgroundRemovalMark[]; /** Strokes marking regions the user forced to be background. */ backgroundMarks?: PptxBackgroundRemovalMark[]; /** Original effect XML, retained for lossless re-emission. */ rawXml?: XmlObject; } /** * Image recolour/adjustment properties parsed from blip extensions. * * These effects are stored in the OpenXML `` extension list * and applied non-destructively to the original image data. * * @example * ```ts * const fx: PptxImageEffects = { * brightness: 20, * contrast: -10, * grayscale: true, * }; * // => { brightness: 20, contrast: -10, grayscale: true } satisfies PptxImageEffects * ``` */ /** * One `a14:foregroundMark` / `a14:backgroundMark` polyline hint recorded while * the user painted over the picture in PowerPoint's "Remove Background" mode. * Coordinates are 0..1 fractions of the image. */ declare interface PptxBackgroundRemovalMark { x1: number; y1: number; x2: number; y2: number; } /** * 3-D bar/column shape (OOXML `ST_Shape`, `c:bar3DChart/c:shape/@val` or a * per-series `c:ser/c:shape` override). `coneToMax` / `pyramidToMax` scale * the cone/pyramid so it reaches full height at the value axis maximum, * appearing truncated below it; the plain `cone`/`pyramid` always come to a * full point at the bar's own value. * * @example * ```ts * const shape: PptxBar3DShape = "cylinder"; * // => "cylinder", one of: "box" | "cone" | "coneToMax" | "cylinder" | "pyramid" | "pyramidToMax" * ``` */ declare type PptxBar3DShape = 'box' | 'cone' | 'coneToMax' | 'cylinder' | 'pyramid' | 'pyramidToMax'; /** A `p:animScale` factor pair (1 = unscaled) or a `p:animMotion` offset (slide fractions). */ declare interface PptxBehaviorPoint { x: number; y: number; } /** Classic `c:bubbleChart` options from CT_BubbleChart. */ declare interface PptxBubbleChartOptions { bubble3D?: boolean; /** Bubble diameter scale in percent, constrained to 0 through 300. */ bubbleScale?: number; showNegativeBubbles?: boolean; sizeRepresents?: 'area' | 'w'; } /** 3D wall or floor element formatting. */ declare interface PptxChart3DSurface { thickness?: number; spPr?: PptxChartShapeProps; } /** Axis formatting for category, value, or date axes. */ declare interface PptxChartAxisFormatting extends PptxChartAxisLabelFormatting { axisType: 'catAx' | 'valAx' | 'dateAx' | 'serAx'; /** Axis position: "b" (bottom), "l" (left), "r" (right), "t" (top). */ axPos?: 'b' | 'l' | 'r' | 't'; /** Unique axis identifier (c:axId/@val) used to link series to axes. */ axisId?: number; /** Cross-axis identifier: the axis this axis crosses. */ crossAxisId?: number; /** Automatic crossing mode (`c:crosses`). Mutually exclusive with `crossesAt`. */ crosses?: 'autoZero' | 'min' | 'max'; /** Explicit crossing value (`c:crossesAt`). Units depend on the axis type. */ crossesAt?: number; /** Whether a value axis crosses between or at category tick marks. */ crossBetween?: 'between' | 'midCat'; numFmt?: PptxChartAxisNumFmt; titleText?: string; spPr?: PptxChartShapeProps; fontFamily?: string; fontSize?: number; fontBold?: boolean; fontColor?: string; /** Whether major gridlines are present (`c:majorGridlines`). */ majorGridlines?: boolean; /** Whether minor gridlines are present (`c:minorGridlines`). */ minorGridlines?: boolean; majorGridlinesSpPr?: PptxChartShapeProps; minorGridlinesSpPr?: PptxChartShapeProps; /** Minimum axis value override (c:min/@val). */ min?: number; /** Maximum axis value override (c:max/@val). */ max?: number; /** Axis value direction (`c:scaling/c:orientation/@val`). */ orientation?: 'minMax' | 'maxMin'; /** Whether the axis is deleted/hidden (c:delete/@val). */ deleted?: boolean; /** * Display units for value axis (c:dispUnits/c:builtInUnit/@val). * When set to 'custom', the actual divisor is in {@link displayUnitsValue}. */ displayUnits?: 'hundreds' | 'thousands' | 'tenThousands' | 'hundredThousands' | 'millions' | 'tenMillions' | 'hundredMillions' | 'billions' | 'trillions' | 'custom'; /** Custom display unit divisor value (c:dispUnits/c:custUnit/@val). Only used when displayUnits is 'custom'. */ displayUnitsValue?: number; /** * Display-unit label contents (`c:dispUnits/c:dispUnitsLbl`). A string is * retained as a compatibility shorthand for `{ text: string }`; `null` * explicitly removes the label. */ displayUnitsLabel?: string | PptxChartDisplayUnitsLabel | null; /** Whether logarithmic scaling is enabled (presence of c:scaling/c:logBase). */ logScale?: boolean; /** Logarithmic base value (c:scaling/c:logBase/@val), typically 10 or e. */ logBase?: number; /** Major-unit interval between primary tick marks (c:majorUnit/@val). */ majorUnit?: number; /** Minor-unit interval between secondary tick marks (c:minorUnit/@val). */ minorUnit?: number; /** Calendar unit used to interpret date-axis serial values. */ baseTimeUnit?: 'days' | 'months' | 'years'; majorTimeUnit?: 'days' | 'months' | 'years'; minorTimeUnit?: 'days' | 'months' | 'years'; } /** Typed axis tick and category/date label controls. */ declare interface PptxChartAxisLabelFormatting { /** Primary and secondary tick-mark placement. */ majorTickMark?: PptxChartTickMark; minorTickMark?: PptxChartTickMark; /** Tick-label position from ChartML `ST_TickLblPos`. */ tickLblPos?: 'high' | 'low' | 'nextTo' | 'none'; /** Automatic category/date axis behavior (`c:auto`). */ auto?: boolean; /** Category-axis label alignment (`c:lblAlgn`). */ labelAlignment?: 'ctr' | 'l' | 'r'; /** Category/date label distance, from 0 through 1000 percent. */ labelOffset?: number; /** Number of category/date labels between rendered labels. */ tickLabelSkip?: number; /** Number of category/date tick positions between major tick marks. */ tickMarkSkip?: number; /** Suppress multi-level category labels (`c:noMultiLvlLbl`). */ noMultiLevelLabels?: boolean; } /** Axis number format. */ declare interface PptxChartAxisNumFmt { formatCode: string; sourceLinked?: boolean; } /** * One colour band for a surface chart (`c:bandFmts/c:bandFmt`, * ECMA-376 §21.2.2.19 / CT_BandFmt). `index` is the band's position * (`c:idx/@val`) among the value axis's major-unit bands, in authored order. */ declare interface PptxChartBandFmt { index: number; spPr?: PptxChartShapeProps; } /** * Bar series direction (OOXML `ST_BarDir`): `"col"` is a vertical column * chart, `"bar"` a horizontal bar chart. * * @example * ```ts * const dir: PptxChartBarDirection = "col"; * // => "col" - one of: "col" | "bar" * ``` */ declare type PptxChartBarDirection = 'col' | 'bar'; /** Office 2016 ChartEx box-and-whisker series layout options. */ declare interface PptxChartBoxWhiskerOptions { quartileMethod?: 'inclusive' | 'exclusive'; showMeanLine?: boolean; showMeanMarker?: boolean; /** Show non-outlier (inner) data points. */ showInnerPoints?: boolean; showOutlierPoints?: boolean; } /** * Chart "chrome" flags from `c:chart` that round-trip cleanly even when * rendering ignores them. * * - {@link autoTitleDeleted}: `c:autoTitleDeleted/@val`. Suppresses the * auto-generated title for single-series charts. * - {@link dispBlanksAs}: `c:dispBlanksAs/@val`. How blank cells * render: `"gap"`, `"zero"`, or `"span"`. * - {@link showDLblsOverMax}: `c:showDLblsOverMax/@val`. Keeps data * labels visible for points exceeding the value-axis maximum. * - {@link dispNaAsBlank}: the Office 2017+ chart extension * `c:extLst/c:ext/c16r3:dataDisplayOptions16/c16r3:dispNaAsBlank/@val` * (uri `{56B9EC1D-385E-4148-901F-78D8002777C0}`), PowerPoint's "Show #N/A * as an empty cell" chart option. Confirmed against real corpus markup * (`e2e/fixtures/chart-data-fidelity.pptx`). * * `c:plotVisOnly` lives on {@link PptxChartData.plotVisibleOnly} and is * intentionally not duplicated here. */ declare interface PptxChartChrome { autoTitleDeleted?: boolean; dispBlanksAs?: 'gap' | 'zero' | 'span'; showDLblsOverMax?: boolean; dispNaAsBlank?: boolean; } /** * Complete parsed chart data for a {@link ChartPptxElement}. * * @example * ```ts * const chart: PptxChartData = { * title: "Q4 Sales", * chartType: "bar", * categories: ["Jan", "Feb", "Mar"], * series: [ * { name: "Revenue", values: [100, 120, 140] }, * ], * grouping: "clustered", * style: { hasLegend: true, legendPosition: "b" }, * }; * // => satisfies PptxChartData * ``` */ declare interface PptxChartData { title?: string; /** * Rich-text runs of the title, parsed from `c:title/c:tx/c:rich` (issue: * chart title rich text). Lossless multi-run alternative to the flat * {@link title}: when present, the writer serialises every run's own * bold/italic/size/color; when absent, save falls back to the flat * `title` path as before. Only populated for a classic (`c:`) chart's * rich (typed) title, not a ChartEx (`cx:`) title or one authored as a * linked-cell reference. */ titleRuns?: PptxChartTitleRun[]; chartType: PptxChartType; categories: string[]; /** * Hierarchical category levels in source XML order, for both ChartEx * hierarchy charts (`cx:multiLvlStrRef`) and classic multi-level category * axes (`c:cat/c:multiLvlStrRef`, e.g. a PowerPoint Quarter > Month * grouping). Level 0 contains the leaf labels and remains mirrored by * {@link categories} for consumers that only understand a flat category * axis. Parent (grouping) levels are forward-filled: a blank cache slot * continues the previous group's label, matching how the source stores a * merged category header sparsely. */ categoryLevels?: string[][]; dateCategories?: PptxChartDateCategories; series: PptxChartSeries[]; /** * Series hidden from the plot by PowerPoint's "Chart Filters" feature * (Series tab) but still present in the workbook, aggregated across every * chart-type container (combo charts can carry more than one). Absent * when the chart has no such extension. See {@link PptxChartFilteredSeries}. */ filteredSeries?: PptxChartFilteredSeries[]; /** * `c15:filteredSeriesTitle`: the auto-generated series title text (e.g. * "Series 3") PowerPoint preserved when the chart filter hid the series * whose data would otherwise have supplied it. See * `utils/chart-ext-titles.ts`. Read-mostly like {@link filteredSeries}. */ filteredSeriesTitle?: string; /** * `c15:filteredCategoryTitle`: the auto-numbered category labels ("1", * "2", "3", ...) PowerPoint preserved when the chart filter hid the * category axis source entirely. See `utils/chart-ext-titles.ts`. */ filteredCategoryTitle?: string[]; /** Chart style/formatting metadata. */ style?: PptxChartStyle; /** Grouping mode for bar/area/line charts: 'clustered' | 'stacked' | 'percentStacked' */ grouping?: 'clustered' | 'stacked' | 'percentStacked'; /** * The source `c:grouping` was `standard`, which {@link grouping} folds into * `'clustered'` (a 2D bar chart draws the two the same). A 3D chart draws * `standard` differently: each series on its own depth row. The writer * emits `standard` again while `grouping` is still `'clustered'`, so the * chart round-trips unchanged. */ groupingStandard?: boolean; /** * Whether the first (or only) series varies its point colours * (`c:varyColors/@val`). Pie/doughnut default this on; single-series * bar/column honour it by giving each point a distinct palette colour. * Absent when the source XML omits `c:varyColors`. */ varyColors?: boolean; /** * Pie/doughnut start angle in degrees clockwise from 12 o'clock * (`c:firstSliceAng/@val`, 0 through 360). Absent uses the default 0. */ firstSliceAngle?: number; /** * Doughnut hole diameter as a percentage of the outer diameter * (`c:holeSize/@val`, 10 through 90). Absent uses the renderer default. */ doughnutHoleSize?: number; /** * Bar series direction (`c:barDir/@val`): `"col"` draws vertical columns, * `"bar"` draws horizontal bars. Absent means `"col"` (PowerPoint's own * default), so only horizontal bar charts need to carry the field. */ barDirection?: PptxChartBarDirection; /** * 3-D bar/column shape (`c:bar3DChart/c:shape/@val`). Bar3D only; a plain * bar chart has no `c:shape` element. A per-series `c:ser/c:shape` * ({@link PptxChartSeries.shape}) overrides this for that series. */ barShape?: PptxBar3DShape; /** * Radar chart drawing style (`c:radarChart/c:radarStyle/@val`). `standard` * draws an outline only, `marker` adds markers at each vertex (PowerPoint's * own default for every radar chart it authors), and `filled` paints the * enclosed polygon with the series fill and omits markers. Radar only. */ radarStyle?: 'standard' | 'marker' | 'filled'; /** * Whether a surface chart renders as a wireframe grid rather than a solid * coloured surface (`c:surfaceChart/c:wireframe/@val` or * `c:surface3DChart/c:wireframe/@val`, both modeled as chart type * `"surface"`). A `CT_Boolean` element: absent from the source XML * defaults to `true` per schema, so `undefined` here means "not present in * the source" and callers should treat it as `true`. Surface only. */ wireframe?: boolean; /** * Whether the surface chart is the 2-D "top view" projection * (`c:surfaceChart`, PowerPoint's "Contour" / "Wireframe Contour" types) * rather than the 3-D isometric one (`c:surface3DChart`, "3-D Surface" / * "3-D Surface (Wireframe)"). Both element names map to chart type * `"surface"`; this bit is the only thing that tells the renderer which * of the two projections PowerPoint actually drew, since a top-view * surface has no Z-axis at all (only category and series axes) while the * 3-D one draws all three. Surface only; `undefined` for every other * chart type. */ surfaceTopView?: boolean; /** * Scatter presentation mode (`c:scatterChart/c:scatterStyle/@val`). * * `lineMarker` (PowerPoint's own default for every scatter it writes) and * `smoothMarker` draw a connecting line; `marker` and `none` do not. Whether * the MARKERS appear is decided separately by `c:marker/c:symbol`, and * whether the LINE appears is further gated by * {@link PptxChartSeries.lineNoFill} - PowerPoint expresses "markers only" as * `lineMarker` plus an `a:ln/a:noFill`, not as `marker`. */ scatterStyle?: PptxChartScatterStyle; /** * Bar/column gap between category clusters as a percentage of bar width * (`c:gapWidth/@val`, 0 through 500). Absent uses the renderer default. */ barGapWidth?: number; /** * Clustered bar/column overlap between series within a category as a * percentage (`c:overlap/@val`, -100 through 100). Absent uses 0. */ barOverlap?: number; /** Internal: path to the chart XML part in the PPTX archive (for round-trip save). */ chartPartPath?: string; /** Internal: relationship ID linking the graphic frame to the chart part. */ chartRelationshipId?: string; /** `null` explicitly removes an existing ChartML data table. */ dataTable?: PptxChartDataTable | null; /** `null` explicitly removes an existing `c:dropLines` element. */ dropLines?: PptxChartLineStyle | null; /** `null` explicitly removes an existing `c:hiLowLines` element. */ hiLowLines?: PptxChartLineStyle | null; /** `null` explicitly removes an existing up/down-bars container. */ upDownBars?: PptxChartUpDownBars | null; axes?: PptxChartAxisFormatting[]; floor?: PptxChart3DSurface; sideWall?: PptxChart3DSurface; backWall?: PptxChart3DSurface; /** Per-band surface-chart colour overrides (`c:surfaceChart/c:bandFmts`). */ bandFmts?: PptxChartBandFmt[]; /** External data source reference (c:externalData) linking to an external workbook. */ externalData?: PptxExternalData; /** * Parsed data from the embedded xlsx workbook (from ppt/embeddings/). * * When a chart references an embedded Excel workbook via `c:externalData`, * the xlsx is parsed to extract categories and series. This data serves as * a fallback when the chart XML's cached series data is empty or incomplete. */ embeddedWorkbookData?: PptxEmbeddedWorkbookData; /** * Pivot table data source reference (c:pivotSource). * * When present, the chart's data originates from a PivotTable. * The chart still renders using its cached series data; this field * is metadata about the data origin, preserved for round-trip fidelity. */ pivotSource?: PptxChartPivotSource | null; /** * Whether only visible cells are plotted (c:plotVisOnly). * When `true` (the default), hidden cells are excluded from the chart. * When `false`, hidden data IS plotted. */ plotVisibleOnly?: boolean; /** * Color palette extracted from the chart's Office 2013+ color style part * (`chartColorStyle*.xml`). When present, this palette takes priority over * the `c:style/@val`-derived palette in `getChartStylePalette`. * * Each entry is a resolved hex colour string (e.g. `"#4472C4"`). */ colorPalette?: string[]; /** * Color cycling method from the chart color style part's `meth` attribute. * * - `"cycle"`: repeat the palette colours in order (default) * - `"withinLinear"`: gradient within each series * - `"acrossLinear"`: gradient across series */ colorMethod?: 'cycle' | 'withinLinear' | 'acrossLinear'; /** Internal source color-style part path used for lossless dirty saves. */ colorStylePartPath?: string; /** Internal parsed palette snapshot used to detect actual edits. */ colorStyleOriginalPalette?: string[]; /** Internal parsed method snapshot used to detect actual edits. */ colorStyleOriginalMethod?: 'cycle' | 'withinLinear' | 'acrossLinear'; /** * Pie-of-pie / Bar-of-pie options (`c:ofPieChart`, CT_OfPieChart). * * Present only when {@link chartType} is `"ofPie"`. Carries the split * configuration, secondary plot size, and serLines flag so that an * `ofPieChart` element can be re-emitted on save with full fidelity. */ ofPieOptions?: PptxChartOfPieOptions; /** Classic bubble-chart display options (`c:bubbleChart`). */ bubbleOptions?: PptxBubbleChartOptions; /** * 3D viewing parameters (`c:view3D`, CT_View3D). * * Parsed from and emitted to `c:chart/c:view3D`. Absent when the * chart XML has no `c:view3D` element. */ view3D?: PptxChartView3D; /** * Top-level chart chrome flags (`c:autoTitleDeleted`, * `c:dispBlanksAs`, `c:showDLblsOverMax`). * * Each flag is omitted from the emitted XML when absent on the * source data, so absence does not produce empty `` placeholders. */ chartChrome?: PptxChartChrome; /** `c:chartSpace/c:printSettings`; `null` removes the container on save. */ printSettings?: PptxChartPrintSettings | null; /** `c:chartSpace/c:protection`; `null` removes the container on save. */ protection?: PptxChartProtection | null; /** Editable manual placement for the title, plot area, and legend. */ layouts?: PptxChartLayouts; /** * Raw `c:userShapes` XML subtree (a drawing tree) preserved verbatim. * * `c:userShapes` references a separate drawing part containing * shapes drawn over the chart. The reference is preserved as-is so * that round-trip save re-emits the original element without * attempting to parse the nested drawing tree. */ userShapesXml?: unknown; /** * Parsed, renderable drawing-overlay shapes resolved from the separate * drawing part referenced by `c:userShapes/@r:id` * (`ppt/drawings/drawingN.xml`). Each entry carries chart-relative anchor * geometry plus light shape/text formatting so the viewer can render an * overlay on top of the chart plot. Render-only: {@link userShapesXml} * remains the source of truth for round-trip save. */ userShapes?: PptxChartUserShape[]; /** * Raw `c:pivotFmts` XML subtree preserved verbatim. * * `c:pivotFmts` carries a list of `c:pivotFmt` formatting overrides * for charts whose data originates from a PivotTable. Preserved * verbatim for round-trip fidelity. */ /** Typed pivot-chart format persistence; `null` removes `c:pivotFmts`. */ pivotFormats?: PptxChartPivotFormats | null; /** * Color-map override (`c:clrMapOvr`) carrying 12 attributes that * remap theme colour roles for this chart only. Modeled as a flat * `attribute -> value` map (e.g. `{ bg1: 'lt1', accent1: 'accent2' }`) * so unknown/future attributes round-trip without code changes. * `null` explicitly removes an existing `c:clrMapOvr`; an empty object * is treated the same as `null` on save. */ clrMapOvr?: Record | null; /** * Whether the chart's own cached numeric values use the 1904 date epoch * (`c:chartSpace/c:date1904/@val`). Independent of, and authoritative over, * any embedded workbook's `workbookPr/@date1904` (a chart can lack an * embedded workbook entirely, or its cache can legitimately differ from the * workbook's current setting). Absent when the source XML omits the * element, in which case the 1900 system applies (the schema default). */ date1904?: boolean; /** * PowerPoint's "Rounded corners" chart-area option * (`c:chartSpace/c:roundedCorners/@val`, default `false`). Absent when the * source XML omits the element. */ roundedCorners?: boolean; /** * 3-D chart depth/spacing along the series axis, as a percentage * (`c:gapDepth/@val`, `ST_GapAmount`, 0 through 500). Legal on * `bar3D`/`area3D`/`line3D`/`surface` chart-type containers only. Read-only * for rendering, matching {@link barGapWidth}/{@link barOverlap}: save * round-trips it via the preserved chart XML rather than a typed edit path. */ gapDepth?: number; /** * Parsed Office 2013+ chart-style part (`ppt/charts/style#.xml`, * `cs:chartStyle`), providing per-element font/line/fill defaults for * whichever built-in "Chart Styles" gallery entry ({@link PptxChartStyle.styleId}) * is active. Absent when the chart has no such part (common for * automation-authored charts, where PowerPoint still implies style 2's * look via its own bundled defaults). */ chartStyleDefinition?: PptxChartStyleDefinition; } /** Individual data label override (c:dLbl). */ declare interface PptxChartDataLabel { idx: number; /** Suppress this data point's automatically generated label. */ deleted?: boolean; showVal?: boolean; showCatName?: boolean; showSerName?: boolean; showPercent?: boolean; showLegendKey?: boolean; showBubbleSize?: boolean; position?: PptxChartDataLabelPosition; text?: string; separator?: string; showLeaderLines?: boolean; /** * Per-label number-format override (`c:dLbl/c:numFmt/@formatCode`), taking * precedence over the chart-level {@link PptxChartDataLabelOptions.numberFormat} * and the series' own {@link PptxChartSeries.numberFormat} when set. */ numberFormat?: string; /** * Manually dragged label position (`c:dLbl/c:layout/c:manualLayout`), the * same CT_ManualLayout shape used for title/legend/plotArea. `null` * explicitly clears a drag back to the automatic position. */ layout?: PptxChartManualLayout | null; /** * This label's own font (`c:dLbl/c:txPr/a:p/a:pPr/a:defRPr`, or ChartEx * `cx:dataLabel/cx:txPr`), taking precedence over the chart/series-level * {@link PptxChartDataLabelOptions.txPr} when set. Reuses the legend * entry's flat text-style shape since both are the same * `.../a:p/a:pPr/a:defRPr` default-run-property style. */ txPr?: PptxChartLegendTextStyle; /** * This label's own shape formatting (`c:dLbl/c:spPr`): fill/line colour, * width, and dash style for the label's callout box, taking precedence * over any chart/series-level default when set. */ spPr?: PptxChartShapeProps; /** * `c15:xForSave`: this override exists only so its properties survive a * save/reload round trip; PowerPoint merges it back onto the series' * default label on load. Round-tripped as-is (an edited chart keeps an * existing point's whole `extLst`, this flag included); introspection * only otherwise. See `utils/chart-data-labels-range.ts`. */ savedForCompatibilityOnly?: boolean; } /** * Chart-level data-label options (`c:dLbls` directly under a chart-type * container, applying to every series). Mirrors the OOXML `c:show*` flags * and `c:dLblPos`. */ declare interface PptxChartDataLabelOptions { /** Label box fill/outline (`c:dLbls/c:spPr`), see `chart-data-label-box.ts`. */ labelShape?: PptxChartShapeProps; /** Callout geometry of the label box (`c15:spPr/a:prstGeom/@prst`, e.g. `wedgeRectCallout`). */ calloutShape?: string; /** The chart15 extension's `c15:showLeaderLines`, which wins for a moved label's leader line. */ extLeaderLines?: boolean; /** Show the numeric value (`c:showVal`). */ showValue?: boolean; /** Show the category name (`c:showCatName`). */ showCategory?: boolean; /** Show the series name (`c:showSerName`). */ showSeriesName?: boolean; /** Show the percentage (`c:showPercent`, pie/doughnut). */ showPercent?: boolean; /** Show the legend key swatch (`c:showLegendKey`). */ showLegendKey?: boolean; /** Show bubble size (`c:showBubbleSize`). */ showBubbleSize?: boolean; /** Text placed between combined label components (`c:separator`). */ separator?: string; /** Show leader lines where supported (`c:showLeaderLines`). */ showLeaderLines?: boolean; /** * Leader-line stroke styling for offset (pie/doughnut `outEnd`/`bestFit`) * labels. Resolved from the base `c:leaderLines/c:spPr` when present, else * falling back to the Office 2013+ chart15 extension's mirror * (`c:extLst/c:ext/c15:leaderLines/c:spPr`, uri * `{CE6537A1-D6FC-4f65-9D91-7224C49458BB}`), which is the one PowerPoint * itself treats as authoritative when both are present. Confirmed against * `e2e/fixtures/issue-132-gradient-fill.pptx` and * `e2e/fixtures/issue-132-hr-deck.pptx`, both of which write only the * extension form. `undefined` leaves the renderer's own default leader-line * stroke. */ leaderLineStyle?: PptxChartShapeProps; /** * Label position (`c:dLblPos`). Valid values depend on the chart type * (`ctr`, `inEnd`, `inBase`, `outEnd`, `bestFit`, `l`, `r`, `t`, `b`). * Omit to let PowerPoint use the type default. */ position?: PptxChartDataLabelPosition; /** * Chart-level number-format override (`c:dLbls/c:numFmt/@formatCode`), * applied to every label of the series/chart-type unless a per-point * {@link PptxChartDataLabel.numberFormat} overrides it. */ numberFormat?: string; /** * Default font for every label at this level (`c:dLbls/c:txPr`, or * ChartEx `cx:dataLabels/cx:txPr`), overridden by a per-point * {@link PptxChartDataLabel.txPr} when set. `c:dLbls` at the chart-type * level and the series level cascade the same way the show flags do * (point > series > chart-type). */ txPr?: PptxChartLegendTextStyle; /** * PowerPoint 2013+ "Value From Cells", series-wide form * (`c15:datalabelsRange`, chart15 uri `{CE6537A1-...}`): one cell range * supplies every label in this group, aligned by point index. A * SERIES-WIDE alternative to the per-point `c15:dlblFieldTable` mechanism * (already resolved into {@link PptxChartDataLabel.text} at parse time). * See `utils/chart-data-labels-range.ts`. */ dataLabelsRange?: PptxChartDataLabelsRange; /** * `c15:showDataLabelsRange` at the SAME level as {@link dataLabelsRange}: * whether every label in this group resolves through the range's cache. * Distinct from the per-point {@link PptxChartDataLabel} flag of the same * XML name. Only meaningful when {@link dataLabelsRange} is set. */ showDataLabelsRange?: boolean; } /** Schema values accepted by `c:dLblPos`. */ declare type PptxChartDataLabelPosition = 'bestFit' | 'b' | 'ctr' | 'inBase' | 'inEnd' | 'l' | 'outEnd' | 'r' | 't'; /** * `c15:dlblRangeCache`/`c15:datalabelsRange` (CT_SeriesDataLabelsRange): * PowerPoint 2013+'s "Value From Cells" custom label source, one cell range * supplying every label in a group (chart-type or series `c:dLbls`), with a * cache aligned to point order. See `utils/chart-data-labels-range.ts`. */ declare interface PptxChartDataLabelsRange { /** `c15:f`: the cell range formula (e.g. `Sheet1!$D$2:$D$5`). */ formula: string; /** `c15:dlblRangeCache`: cached label text, index-aligned with data points. */ cache: string[]; } /** Per-data-point formatting override (c:dPt). */ declare interface PptxChartDataPoint { idx: number; spPr?: PptxChartShapeProps; explosion?: number; invertIfNegative?: boolean; marker?: PptxChartMarker; /** Render a bubble-chart point with a 3-D appearance. */ bubble3D?: boolean; /** Per-point picture-fill flags (`c:dPt/c:pictureOptions`). */ picture?: PptxChartDataPointPicture; /** * A picture fill implied by a bare `c:dPt/c:spPr/a:blipFill` with NO * sibling `c:pictureOptions` at all: still a fully legal "stretch, no * stack" picture fill, just one PowerPoint's format pane never touched the * stack settings for. Render-derived only: unlike {@link picture}, this is * never written back on save (the original, untouched `c:spPr` already * round-trips verbatim), so populating it can never desync the saved file * from what was authored. See `chart-datapoint-picture.ts`'s * `parseImplicitBlipPictureFill`. */ impliedPicture?: PptxChartDataPointPicture; /** * This point's identity GUID (`c:dPt/c:extLst/c:ext/c16:uniqueId/@val`, * the Office 2014+ `{C3380CC4-5D6E-409C-BE32-E72D297353CC}` chart * extension), read-only here: an edited point keeps its existing * `c:extLst` as passthrough (see `chart-datapoint-serializer.ts`), so this * field exists for introspection rather than round-trip. */ uniqueId?: string; } /** * Per-data-point picture-fill flags (`c:dPt/c:pictureOptions`): PowerPoint's * "Picture or texture fill" with "Stack"/"Stretch" semantics on a bar/column * data point, distinct from the point's plain `c:spPr` solid/gradient fill. * * `c:pictureOptions` is optional: a point/series whose `c:spPr` carries a bare * `a:blipFill` with NO `c:pictureOptions` sibling at all is still a fully * legal, common picture fill (PowerPoint's own default "stretch, no stack" * when the format pane never touched the stack settings); `parseChartDataPointPicture` * synthesizes this descriptor (`pictureFormat: 'stretch'`) in that case so the * SAME render pipeline resolves it, rather than silently dropping the fill. * * The flags parse purely (`parseChartDataPointPicture` in * `utils/chart-datapoint-serializer.ts`); {@link imageUrl} is a separate, * later addition populated by the runtime (`PptxHandlerRuntimeChartParsing.ts`) * once the sibling `c:spPr/a:blipFill/a:blip`'s `r:embed`/`r:link` is resolved * against the chart part's relationships, since that resolution needs zip/file * access the pure parser does not have. */ declare interface PptxChartDataPointPicture { /** Apply the picture to the front face of a 3-D bar/column (`c:applyToFront`). */ applyToFront?: boolean; /** Apply the picture to the side faces of a 3-D bar/column (`c:applyToSides`). */ applyToSides?: boolean; /** Apply the picture to the end face of a 3-D bar/column (`c:applyToEnd`). */ applyToEnd?: boolean; /** Stretch, or stack repeated tiles at their natural size (or scaled). */ pictureFormat?: PptxChartPictureFormat; /** Height, in points, of one repeated picture tile for "stack"/"stackScale" (`c:pictureStackUnit/@val`). */ pictureStackUnit?: number; /** * Resolved picture source (a `data:`/`blob:` URL) for the point's sibling * `c:spPr/a:blipFill/a:blip`. Populated by the runtime after relationship * resolution (C2-G9 render half); absent until then, and absent entirely * when the point has no picture fill or the image could not be resolved. */ imageUrl?: string; /** * Effective opacity (0-1) from the blip's `a:alphaModFix/@amt` (a * thousandths-of-a-percent value, so `amt="60000"` is `0.6`). `undefined` * when the blip carries no `alphaModFix`, meaning fully opaque. */ opacity?: number; } /** * Visibility flags for the chart data table (axes + legend keys). * * @example * ```ts * const dt: PptxChartDataTable = { * showHorzBorder: true, * showVertBorder: true, * showOutline: true, * showKeys: true, * }; * // => satisfies PptxChartDataTable * ``` */ declare interface PptxChartDataTable { showHorzBorder?: boolean; showVertBorder?: boolean; showOutline?: boolean; showKeys?: boolean; /** Table border/fill formatting (`c:dTable/c:spPr`). */ spPr?: PptxChartShapeProps; /** * Cell text defaults (`c:dTable/c:txPr/a:p/a:pPr/a:defRPr`). Reuses the same * shape as a legend entry's text override since both are a flat paragraph * default-run-property style (size/bold/italic/font/colour). */ txPr?: PptxChartLegendTextStyle; } /** Raw numeric category cache used by a classic ChartML date axis. */ declare interface PptxChartDateCategories { values: number[]; /** False/default uses Excel's 1900 date system; true uses the 1904 system. */ date1904?: boolean; /** Number format copied from the numeric category cache. */ formatCode?: string; } /** Typed contents of a value-axis display-unit label (`c:dispUnitsLbl`). */ declare interface PptxChartDisplayUnitsLabel { /** Literal label text. Omit to preserve the source text subtree. */ text?: string; /** Manual label placement. `null` removes only the manual layout. */ layout?: PptxChartManualLayout | null; /** Label shape formatting. `null` removes `c:spPr`. */ spPr?: PptxChartShapeProps | null; /** * The label's own run font, when it carries a distinct `txPr` from the * axis's own (ChartEx `cx:unitsLabel/cx:txPr`; classic `c:dispUnitsLbl` * has no equivalent child, so this is only ever populated from a ChartEx * axis). */ fontFamily?: string; fontSize?: number; fontBold?: boolean; fontColor?: string; } /** Error-bar direction axis. */ declare type PptxChartErrBarDir = 'x' | 'y'; /** * Error bars for a chart series. * * @example * ```ts * const bars: PptxChartErrBars = { * direction: "y", * barType: "both", * valType: "percentage", * val: 5, * }; * // => satisfies PptxChartErrBars * ``` */ declare interface PptxChartErrBars { direction: PptxChartErrBarDir; barType: PptxChartErrBarType; valType: PptxChartErrValType; val?: number; customPlus?: number[]; customMinus?: number[]; noEndCap?: boolean; color?: string; /** Error-bar line width in points (`c:errBars/c:spPr/a:ln/@w`, EMU / 12700). */ width?: number; /** Error-bar line dash style (`c:errBars/c:spPr/a:ln/a:prstDash/@val`). */ dashStyle?: string; } /** Error-bar display type (both sides, negative only, or positive only). */ declare type PptxChartErrBarType = 'both' | 'minus' | 'plus'; /** * How the error-bar value is calculated. * * @example * ```ts * const valType: PptxChartErrValType = "percentage"; * // => "percentage": one of: "cust" | "fixedVal" | "percentage" | "stdDev" | "stdErr" * ``` */ declare type PptxChartErrValType = 'cust' | 'fixedVal' | 'percentage' | 'stdDev' | 'stdErr'; /** * A series PowerPoint's "Chart Filters" feature hid from the plot while * keeping it in the workbook (`c:Chart/c:extLst/c:ext * [@uri={02D57815-91ED-43cb-92C2-25804820EDAC}]/c15:filteredSeries * /c15:ser`). Read-mostly: {@link PptxChartData.filteredSeries} exists for * introspection (AI tools, "unhide filtered series" UI) and round-trips as * passthrough through the preserved chart XML when untouched. See * `utils/chart-filtered-series.ts` for the parse rules and the idx-collision * fix this modelling enables on save. */ declare interface PptxChartFilteredSeries { /** `c15:ser/c:idx/@val`, the workbook column position this series still occupies. */ idx: number; /** `c15:ser/c:order/@val`, defaulting to {@link idx} when absent. */ order: number; /** Series name, from the hidden series' own `c:tx` cache. */ name?: string; /** Category labels, from the hidden series' own `c:cat` cache. */ categories?: string[]; /** Data values, from the hidden series' own `c:val` cache. */ values?: number[]; /** This hidden series' own identity GUID (`c16:uniqueId`), when present. */ uniqueId?: string; /** * A full snapshot of the series as it looked the moment it was hidden * (`render/chart-ext-editor-actions.ts`'s `hideChartSeries`), so * `restoreFilteredSeries` can bring it back exactly as it was: full fill/ * line formatting, marker, data-label options, everything, not just the * bare name/values/idx the other fields above capture. * * NOT derived from XML and NEVER written to disk (the save writer, * `chart-filtered-series-writer.ts`, only reads the named fields above): * this exists purely for the live "Chart Filters" hide/show round-trip * within one editing session. A filtered series read from an actually * parsed file (one that was already hidden when opened) has no snapshot * to draw on, since real PowerPoint's `c15:ser` node is parsed only for * the fields above (`chart-filtered-series.ts`'s `parseOneFilteredSeries`); * `restoreFilteredSeries` falls back to reconstructing a bare series from * those for that case, same as before this field existed. */ originalSeries?: PptxChartSeries; } /** Shape properties extracted from c:spPr for chart formatting. */ /** * A render-ready gradient fill from a chart `c:spPr/a:gradFill` (chart area, * plot area or series). Positions are 0..100; a linear gradient's `angle` is * in degrees clockwise from left-to-right (`a:lin/@ang`); a radial (`a:path`) * gradient centres on `focalPoint` (0..1 fractions of the box), the middle * when absent. */ declare interface PptxChartGradientFill { type: 'linear' | 'radial'; stops: Array<{ color: string; position: number; opacity?: number; }>; angle?: number; focalPoint?: { x: number; y: number; }; } /** Office 2016 ChartEx histogram and Pareto series layout options. */ declare interface PptxChartHistogramOptions { /** Maps to `clusteredColumn` for histogram columns or `paretoLine`. */ layout?: 'histogram' | 'pareto'; /** Exactly one of binSize and binCount is emitted by the ChartEx writer. */ binSize?: number; binCount?: number; intervalClosed?: 'l' | 'r'; underflow?: number | 'auto'; overflow?: number | 'auto'; /** * `c:layoutPr/cx:aggregation` was authored instead of `cx:binning`: the * raw rows are CATEGORICAL (a Pareto chart's `clusteredColumn` series * counting occurrences of each authored category, COM-verified against * charts-com.pptx slide 31 / chartEx6.xml), not a numeric range to bin. * Mutually exclusive with `binSize`/`binCount`/`intervalClosed`, which * only apply to a true numeric-value histogram. */ aggregateByCategory?: boolean; } /** * Typed manual layouts for chart regions that accept `c:layout`. * A `null` region removes its manual layout without removing extensions. */ declare interface PptxChartLayouts { title?: PptxChartManualLayout | null; plotArea?: PptxChartManualLayout | null; legend?: PptxChartManualLayout | null; } /** Per-series legend entry override (`c:legendEntry`). */ declare interface PptxChartLegendEntry { index: number; deleted?: boolean; textStyle?: PptxChartLegendTextStyle; } /** Typed text defaults for a single chart legend entry. */ declare interface PptxChartLegendTextStyle { fontFamily?: string; fontSize?: number; bold?: boolean; italic?: boolean; color?: string; } /** * Line appearance for chart helper lines (drop lines, hi-low lines). * * @example * ```ts * const style: PptxChartLineStyle = { * color: "#AAAAAA", * width: 1, * dashStyle: "dash", * }; * // => satisfies PptxChartLineStyle * ``` */ declare interface PptxChartLineStyle { color?: string; width?: number; dashStyle?: string; } /** Manual chart placement from `c:layout/c:manualLayout` (CT_ManualLayout). */ declare interface PptxChartManualLayout { layoutTarget?: 'inner' | 'outer'; xMode?: 'edge' | 'factor'; yMode?: 'edge' | 'factor'; widthMode?: 'edge' | 'factor'; heightMode?: 'edge' | 'factor'; x?: number; y?: number; width?: number; height?: number; /** * Raw `c:extLst` (CT_ExtensionList) of the `c:manualLayout`, captured * verbatim so it round-trips through the typed model. Without this, a dirty * write of an edited layout would drop the extension list (the manual node * is rebuilt from the typed fields). Emitted as the trailing child, matching * the CT_ManualLayout schema order. */ ext?: XmlObject; } /** Marker appearance on a chart series or data point. */ declare interface PptxChartMarker { symbol: PptxChartMarkerSymbol; /** Marker size in points, constrained by ST_MarkerSize to 2 through 72. */ size?: number; spPr?: PptxChartShapeProps; } /** Marker symbol types for line/scatter chart data points. */ declare type PptxChartMarkerSymbol = 'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'picture' | 'plus' | 'square' | 'star' | 'triangle' | 'x' | 'auto'; /** * Options specific to the OOXML "Pie of Pie" / "Bar of Pie" chart * (`c:ofPieChart`, ECMA-376 §21.2.2.126 / CT_OfPieChart). * * The primary discriminator is {@link ofPieType}: `"pie"` produces a * pie-of-pie chart whose secondary plot is itself a pie, while `"bar"` * produces a bar-of-pie chart whose secondary plot is a horizontal bar. * * - {@link splitType} chooses the split rule. * - {@link splitPos} is the threshold value used by `pos`/`val`/`percent`. * - {@link secondPieSize} controls the secondary plot's size (5–200%). * - {@link serLines} toggles the leader lines connecting the plots. * - {@link gapWidth} is the gap between the plots in percent (0–500). */ declare interface PptxChartOfPieOptions { ofPieType: 'pie' | 'bar'; splitType?: 'auto' | 'cust' | 'percent' | 'pos' | 'val'; splitPos?: number; custSplit?: number[]; secondPieSize?: number; serLines?: boolean; gapWidth?: number; } /** Required page margins from ChartML `c:pageMargins`, measured in inches. */ declare interface PptxChartPageMargins { left: number; right: number; top: number; bottom: number; header: number; footer: number; /** Original leaf retained for foreign attributes. */ rawXml?: unknown; } /** Printer page configuration from ChartML `c:pageSetup`. */ declare interface PptxChartPageSetup { paperSize?: number; firstPageNumber?: number; orientation?: 'default' | 'portrait' | 'landscape'; blackAndWhite?: boolean; draft?: boolean; useFirstPageNumber?: boolean; horizontalDpi?: number; verticalDpi?: number; copies?: number; /** * Custom paper height, used when {@link paperSize} is `0` * (`c:pageSetup/@paperHeight`, ST_PositiveUniversalMeasure, e.g. `"297mm"`). * Kept as the raw measure string rather than converted, matching how the * schema stores it. */ paperHeight?: string; /** Custom paper width, used when {@link paperSize} is `0` (`@paperWidth`). */ paperWidth?: string; /** Original leaf retained for foreign attributes. */ rawXml?: unknown; } /** Layout for parent category labels in a hierarchical ChartEx treemap. */ declare type PptxChartParentLabelLayout = 'none' | 'banner' | 'overlapping'; /** * Chart-formatting types that don't fit an existing, owned type module for * this wave (`types/chart.ts` is owned elsewhere; see its own module doc). * Despite the file name, `PptxChartDataPointPicture` is a CLASSIC (`c:`) * construct, not ChartEx (`cx:`) - it landed here only because it needs a * home outside `chart.ts`. * * @module pptx-types/chart-ex */ /** `c:dPt/c:pictureOptions/c:pictureFormat/@val` (ST_PictureFormat). */ declare type PptxChartPictureFormat = 'stretch' | 'stack' | 'stackScale'; declare interface PptxChartPivotFormat { index: number; /** * Typed projection of `spPr` (fill/stroke colour, stroke width, dash * style). When the parser is given a colour resolver (the normal case: the * runtime always supplies one), both a literal `a:srgbClr` and an * `a:schemeClr` theme reference (with its `lumMod`/`lumOff`/`tint`/`shade` * modifiers) resolve to a hex colour here, the same theme + * `c:clrMapOvr` chain the rest of chart parsing uses. Without a resolver * (e.g. a hand-built `PptxChartPivotFormat` with no theme to resolve * against), only the literal case resolves. Either way the authored node * is byte-preserved through {@link shapePropertiesXml} until this field is * set to something that no longer matches what re-parses off the current * XML; setting it then re-derives `shapePropertiesXml` on save (merged * onto whatever was already authored, keeping an unrelated schemeClr * reference alive when the colour itself is unchanged) unless * `shapePropertiesXml` is set explicitly, which wins. */ shapeProperties?: PptxChartShapeProps; /** * Typed projection of `txPr`'s `a:p/a:pPr/a:defRPr` (size/bold/italic/ * colour/family), the same shape a legend entry or data-table's text * override models. Colour resolution mirrors {@link shapeProperties} * (theme-resolved `schemeClr` when a colour resolver is supplied, literal * `srgbClr` otherwise). See {@link txPrXml} for the raw fallback. */ textStyle?: PptxChartLegendTextStyle; /** * Typed projection of `marker` (symbol/size/spPr). See {@link markerXml} * for the raw fallback. */ marker?: PptxChartMarker; shapePropertiesXml?: XmlObject | null; txPrXml?: XmlObject | null; markerXml?: XmlObject | null; dataLabelXml?: XmlObject | null; extensionListXml?: XmlObject | null; rawXml?: XmlObject; } /** Editable classic ChartML `c:pivotFmts` collection. */ declare interface PptxChartPivotFormats { formats: PptxChartPivotFormat[]; rawXml?: XmlObject; } /** Editable classic ChartML `c:pivotSource` metadata. */ declare interface PptxChartPivotSource { /** Pivot table reference stored as `c:name` text. */ name: string; /** Required unsigned format identifier stored in `c:fmtId/@val`. */ formatId: number; /** Internal source subtree used to preserve extensions and foreign markup. */ rawXml?: XmlObject; } /** Headers and footers used when a classic ChartML chart is printed. */ declare interface PptxChartPrintHeaderFooter { oddHeader?: string; oddFooter?: string; evenHeader?: string; evenFooter?: string; firstHeader?: string; firstFooter?: string; alignWithMargins?: boolean; differentOddEven?: boolean; differentFirst?: boolean; /** Original subtree retained for foreign attributes and extension children. */ rawXml?: unknown; } /** Editable `c:printSettings` content from a classic ChartML chart space. */ declare interface PptxChartPrintSettings { headerFooter?: PptxChartPrintHeaderFooter | null; pageMargins?: PptxChartPageMargins | null; pageSetup?: PptxChartPageSetup | null; /** `null` removes the legacy header/footer drawing relationship element. */ legacyDrawingHeaderFooterRelationshipId?: string | null; /** Original subtree retained for unknown and extension content. */ rawXml?: unknown; } /** Editable classic ChartML `c:protection` settings. */ declare interface PptxChartProtection { /** Prevent editing the chart object. */ chartObject?: boolean | null; /** Prevent editing the chart data. */ data?: boolean | null; /** Prevent editing chart formatting. */ formatting?: boolean | null; /** Prevent selecting chart elements. */ selection?: boolean | null; /** Prevent chart user-interface operations. */ userInterface?: boolean | null; /** Internal source subtree used to preserve foreign markup during edits. */ rawXml?: XmlObject; } /** Office 2016 ChartEx geographic series dimensions and layout options. */ declare interface PptxChartRegionMapOptions { /** * Colour-by-value gradient stops (`cx:valueColors/cx:colors/cx:color`), * resolved to hex, 2 or 3 entries (matching PowerPoint's two- and * three-colour scale UI). Paired index-for-index with * {@link valueColorPositions} when both are present. */ valueColors?: string[]; /** Gradient breakpoints for {@link valueColors} (`cx:valueColorPositions`). */ valueColorPositions?: PptxCxValueColorPosition[]; /** Optional provider entity identifiers aligned with categories and values. */ entityIds?: string[]; /** Original `cx:pt/@idx` values for category points. */ categorySourceIndices?: number[]; /** Original `cx:pt/@idx` values for colour-value points. */ valueSourceIndices?: number[]; /** Original `cx:pt/@idx` values for entity-ID points. */ entityIdSourceIndices?: number[]; regionLabelLayout?: 'none' | 'bestFitOnly' | 'showAll'; projectionType?: 'mercator' | 'miller' | 'robinson' | 'albers'; viewedRegionType?: 'dataOnly' | 'postalCode' | 'county' | 'state' | 'countryRegion' | 'countryRegionList' | 'world'; cultureLanguage?: string; /** ISO-3166-1 alpha-2 region code. */ cultureRegion?: string; attribution?: string; /** Opaque authored provider cache under `cx:geography/cx:geoCache`. */ geographyCache?: XmlObject; } /** * `ST_ScatterStyle` (ECMA-376 §21.2.3.40): how a scatter chart joins its points. * `line`/`lineMarker` connect them with straight segments, `smooth`/ * `smoothMarker` with a bezier, `marker`/`none` not at all. */ declare type PptxChartScatterStyle = 'none' | 'line' | 'lineMarker' | 'marker' | 'smooth' | 'smoothMarker'; /** * A single data series within a chart. * * @example * ```ts * const series: PptxChartSeries = { * name: "Revenue", * values: [100, 120, 140], * color: "#4F81BD", * trendlines: [{ trendlineType: "linear" }], * }; * // => satisfies PptxChartSeries * ``` */ declare interface PptxChartSeries { name: string; /** * This series' own `c:ser/c:idx/@val`. PowerPoint keys per-series identity * (data-point picking, and the automatic marker-symbol cycle when no * `c:marker/c:symbol` is authored) off this value, NOT off the series' * position in this array: a series can be reordered (`c:order`) without its * `idx` changing, and a chart with a deleted/filtered series leaves a gap * (e.g. idx 1, 2 with no idx 0). Absent only for chart kinds this parser * does not tag (rare); render code that needs it should fall back to the * array position. */ idx?: number; values: number[]; /** * Series gradient fill (`c:ser/c:spPr/a:gradFill`), painted on every mark * of the series that has no per-point override. Render-only: the series' * own `c:spPr` round-trips untouched. */ gradientFill?: PptxChartGradientFill; /** * Per-series x values from `c:ser/c:xVal` (scatter and bubble series only). * * Every `CT_ScatterSer` / `CT_BubbleSer` carries its OWN `c:xVal`, so two * series in one scatter chart routinely plot against different x ranges (the * normal case for measurement data). Reading the x values off the first * series and reusing them everywhere plotted every series against series 1's * x axis. Absent for category-axis chart kinds, where * {@link PptxChartData.categories} is the x axis. */ xValues?: number[]; /** * Per-series bubble sizes from `c:ser/c:bubbleSize` (bubble series only), * aligned index-for-index with {@link values}. * * `CT_BubbleSer` carries x, y AND size, so a one-series bubble chart is fully * specified. Absent when the source omits `c:bubbleSize`. */ bubbleSizes?: number[]; /** * Series-level data-label content flags from `c:ser/c:dLbls`. * * PowerPoint writes the flags a user picks in "Format Data Labels" onto the * SERIES, and leaves the chart-type-level `c:dLbls` all-zero, so reading only * the chart-level group reports "show nothing" for a chart that visibly shows * percentages. These override {@link PptxChartStyle.dataLabels}. */ dataLabelOptions?: PptxChartDataLabelOptions; /** * Whether the series line is explicitly suppressed * (`c:ser/c:spPr/a:ln/a:noFill`). Line-drawn kinds (line, scatter, radar) * use this to decide whether to draw a connecting line at all; a marker-only * scatter is authored as `scatterStyle="lineMarker"` PLUS this flag, never by * changing the scatter style. */ lineNoFill?: boolean; /** * Blank-value mask aligned index-for-index with {@link values}: `true` marks * a category whose numeric cache point (`c:numCache/c:pt`) was absent or * empty, i.e. a genuine blank rather than a real `0`. Present only when the * source series actually contains blanks; when set, blank slots in * {@link values} carry `0` as a placeholder. Renderers honour * `c:dispBlanksAs` (gap / zero / span) using this mask. */ blanks?: boolean[]; /** * ECMA-376 number-format code for this series' values, resolved from * `c:ser/c:dLbls/c:numFmt/@formatCode` and falling back to the value cache's * own `c:numCache/c:formatCode` (which is what `@sourceLinked="1"` means). * Data labels render through it: a percentage series caches fractions, so * without the code `0.52` reaches the label where PowerPoint shows `52%`. */ numberFormat?: string; color?: string; trendlines?: PptxChartTrendline[]; errBars?: PptxChartErrBars[]; dataPoints?: PptxChartDataPoint[]; marker?: PptxChartMarker; dataLabels?: PptxChartDataLabel[]; explosion?: number; /** * Series-level `c:invertIfNegative`: when true, bar/column data points with a * negative value are drawn with an inverted (lightened) fill. A per-point * `c:dPt/c:invertIfNegative` overrides this for that point. Absent when the * source XML omits the flag. */ invertIfNegative?: boolean; /** * Whether this line/scatter series is drawn with bezier smoothing * (`c:ser/c:smooth/@val`). Absent when the source XML omits `c:smooth`. */ smooth?: boolean; /** Axis ID this series is plotted against (links to PptxChartAxisFormatting.axisId). */ axisId?: number; /** * Per-series chart type, used for combo charts where individual series are * plotted with different chart types (e.g. a bar series and a line series in * the same chart). Maps to the OOXML chart-type container that holds the * series (`c:barChart`, `c:lineChart`, etc.). Omitted for single-type charts, * where the chart-level {@link PptxChartData.chartType} applies to every * series. */ seriesChartType?: PptxChartType; /** * Per-series 3-D bar/column shape override (`c:ser/c:shape`), legal only * inside a bar3D chart-type container. Overrides {@link PptxChartData.barShape} * for this series alone. */ shape?: PptxBar3DShape; boxWhiskerOptions?: PptxChartBoxWhiskerOptions; histogramOptions?: PptxChartHistogramOptions; waterfallOptions?: PptxChartWaterfallOptions; regionMapOptions?: PptxChartRegionMapOptions; treemapOptions?: PptxChartTreemapOptions; /** * Series-level picture-fill flags (`c:ser/c:pictureOptions`), legal * wherever a per-point `c:dPt/c:pictureOptions` is (CT_BarSer): paints * EVERY point in the series with one picture unless a `c:dPt` overrides it * for that point alone. A point's own {@link PptxChartDataPoint.picture} * takes precedence entirely (not merged field-by-field) when it resolves * its own image; renderers fall back to this series-level picture only * when the point has none of its own. */ picture?: PptxChartDataPointPicture; /** * A picture fill implied by a bare `c:ser/c:spPr/a:blipFill` with NO * sibling `c:pictureOptions` at all. See * {@link PptxChartDataPoint.impliedPicture}'s doc comment: same * render-only, never-serialized-back convention, at the series level. */ impliedPicture?: PptxChartDataPointPicture; /** * This series' identity GUID (`c:ser/c:extLst/c:ext/c16:uniqueId/@val`, * the Office 2014+ `{C3380CC4-5D6E-409C-BE32-E72D297353CC}` chart * extension). PowerPoint uses it to track a series across edits and * collaborators independent of its `c:idx`/`c:order` position (the same * role animation targeting and CRDT reconciliation need). An edited * existing series keeps its own `c:extLst` as passthrough; a NEW series * added by cloning an existing one as a template is given a freshly * generated id rather than duplicating the template's (see * `regenerateClonedUniqueId` in `chart-series-identity.ts`), since two * series sharing one identity is exactly what this extension exists to * prevent. */ uniqueId?: string; } declare interface PptxChartShapeProps { fillColor?: string; strokeColor?: string; strokeWidth?: number; /** Line dash style (a:prstDash/@val), e.g. 'solid', 'dash', 'dot', 'lgDash'. */ strokeDashStyle?: string; } /** * Style / formatting metadata for a chart. * * @example * ```ts * const style: PptxChartStyle = { * styleId: 2, * hasLegend: true, * legendPosition: "b", * hasDataLabels: true, * }; * // => satisfies PptxChartStyle * ``` */ declare interface PptxChartStyle { /** Chart style index from `c:style/@val`. */ styleId?: number; /** Whether the chart has a visible legend. */ hasLegend?: boolean; /** Legend position (t, b, l, r, tr). */ legendPosition?: string; /** Per-series visibility and text-style overrides. */ legendEntries?: PptxChartLegendEntry[]; /** * The legend's own default text style (`c:legend/c:txPr`), falling back to * the chart-wide default (`c:chartSpace/c:txPr`) when the legend has none * of its own. Applies to every legend entry that has no per-entry * `c:legendEntry/c:txPr` override (see {@link PptxChartLegendEntry.textStyle}), * which always wins over this chart-level default. */ legendTextStyle?: PptxChartLegendTextStyle; /** Whether the chart has a title. */ hasTitle?: boolean; /** Whether gridlines are visible. */ hasGridlines?: boolean; /** * Chart-area fill from `c:chartSpace/c:spPr`: a resolved colour, or the * literal `'none'` when the source declares ``. Absent when the * chart says nothing, in which case the renderer picks its own default. * PowerPoint decks routinely set `a:noFill` so the chart floats on the slide * background; painting a panel behind it boxes the chart in. */ chartAreaFill?: string; /** Plot-area fill from `c:plotArea/c:spPr`. See {@link chartAreaFill}. */ plotAreaFill?: string; /** Chart-area gradient (`c:chartSpace/c:spPr/a:gradFill`); wins over {@link chartAreaFill}. */ chartAreaGradient?: PptxChartGradientFill; /** Plot-area gradient (`c:plotArea/c:spPr/a:gradFill`); wins over {@link plotAreaFill}. */ plotAreaGradient?: PptxChartGradientFill; /** Whether data labels are shown. */ hasDataLabels?: boolean; /** Chart-level data-label content/position options (when `hasDataLabels`). */ dataLabels?: PptxChartDataLabelOptions; /** * Font styling for the chart's own title (`c:title/c:txPr`), edited via * `applyChartTitleStyleToXml` (chart-title-style-serializer.ts). Distinct * from an axis title's styling (`PptxChartAxisFormatting.fontFamily` etc.). */ titleFontFamily?: string; titleFontSize?: number; titleFontBold?: boolean; titleFontColor?: string; /** Title text-box fill/border (`c:title/c:spPr`). `null` removes it. */ titleSpPr?: PptxChartShapeProps | null; } /** * Parsed per-element style defaults from a chart-style part. Only the * elements this viewer actually renders distinct defaults for are modeled; * elements PowerPoint's style gallery also styles (data table, trendlines, * up/down bars, ...) are out of scope until a renderer needs them. */ declare interface PptxChartStyleDefinition { title?: PptxChartStylePartEntry; axisTitle?: PptxChartStylePartEntry; categoryAxis?: PptxChartStylePartEntry; valueAxis?: PptxChartStylePartEntry; legend?: PptxChartStylePartEntry; dataLabel?: PptxChartStylePartEntry; dataPoint?: PptxChartStylePartEntry; dataPointLine?: PptxChartStylePartEntry; gridlineMajor?: PptxChartStylePartEntry; gridlineMinor?: PptxChartStylePartEntry; chartArea?: PptxChartStylePartEntry; plotArea?: PptxChartStylePartEntry; } /** * Typed subset of an Office 2013+ chart-style part (`ppt/charts/style#.xml`, * root element `cs:chartStyle`, relationship type * `.../2012/relationships/chartStyle`). * * PowerPoint's Design-tab "Chart Styles" gallery (1-48) writes `c:style/@val` * on the chart part itself (already modeled as `PptxChartStyle.styleId`) and, * for most styles, this SEPARATE part spelling out the per-element * `cs:lnRef`/`cs:fillRef`/`cs:effectRef`/`cs:fontRef`/`cs:defRPr` defaults a * chart element falls back to when its own XML leaves it unstyled. Without * parsing this part, styles beyond the one PowerPoint happens to have baked * inline are visually inert. * * @module pptx-types/chart-style-definition */ /** * One styled chart-element entry (`cs:title`, `cs:axisTitle`, * `cs:categoryAxis`, ...). Colours are resolved to hex at parse time (scheme * colour references via `cs:fontRef`/`cs:lnRef`/`cs:fillRef` are already * flattened against the theme, matching how classic chart colours resolve * elsewhere in this codebase). Fields are present only when the source XML * carried a value for them. */ declare interface PptxChartStylePartEntry { /** Text size in points, from `cs:defRPr/@sz` (hundredths of a point). */ fontSize?: number; bold?: boolean; italic?: boolean; /** Resolved text colour: `cs:defRPr/a:solidFill`, or `cs:fontRef`'s scheme colour. */ color?: string; /** Resolved line colour from `cs:lnRef`'s scheme colour reference. */ lineColor?: string; /** Line width in points, when directly authored (rare; most styles reference a theme line style by index only). */ lineWidth?: number; /** Resolved fill colour from `cs:fillRef`'s scheme colour reference. */ fillColor?: string; } /** Tick-mark placement from ChartML `ST_TickMark`. */ declare type PptxChartTickMark = 'cross' | 'in' | 'none' | 'out'; /** * Chart title rich-text run type, split out of `types/chart.ts` (already at * the repo's file-size limit) to keep that module from growing further. * * @module pptx-types/chart-title */ /** * One run of a chart title's rich text (`c:title/c:tx/c:rich/a:p/a:r`). * * The flat `PptxChartData.title` field only ever captured the FIRST run's * text with no per-run formatting; `titleRuns` (when present) is the * lossless, multi-run replacement parsed from the same `c:rich` body. Absent * when the title has no rich text at all (an empty/auto title, or one * authored as a linked-cell reference). */ declare interface PptxChartTitleRun { /** This run's text (`a:t`). */ text: string; /** `a:rPr/@_b`. */ bold?: boolean; /** `a:rPr/@_i`. */ italic?: boolean; /** * Font size in POINTS (`a:rPr/@_sz`, hundredths of a point / 100), matching * `PptxChartLegendTextStyle.fontSize`'s convention rather than the pixel * convention `TextStyle.fontSize` uses for slide text. */ fontSize?: number; /** Resolved hex colour (e.g. `"#FF0000"`) from `a:rPr/a:solidFill`. */ color?: string; } /** Per-series layout options for an Office 2016+ ChartEx treemap. */ declare interface PptxChartTreemapOptions { parentLabelLayout?: PptxChartParentLabelLayout; } /** * Configuration for a chart trendline (regression line). * * @example * ```ts * const trendline: PptxChartTrendline = { * trendlineType: "linear", * displayEq: true, * displayRSq: true, * color: "#FF0000", * }; * // => satisfies PptxChartTrendline * ``` */ declare interface PptxChartTrendline { trendlineType: PptxChartTrendlineType; name?: string; order?: number; period?: number; forward?: number; backward?: number; intercept?: number; displayRSq?: boolean; displayEq?: boolean; color?: string; /** Trendline width in points (`c:trendline/c:spPr/a:ln/@w`, EMU / 12700). */ lineWidth?: number; /** Trendline dash style (`c:trendline/c:spPr/a:ln/a:prstDash/@val`). */ lineDashStyle?: string; label?: PptxChartTrendlineLabel | null; } /** Typed, commonly edited properties of `c:trendlineLbl`. */ declare interface PptxChartTrendlineLabel { layout?: PptxChartManualLayout; numberFormatCode?: string; sourceLinked?: boolean; } /** * Supported trendline regression types. * * @example * ```ts * const type: PptxChartTrendlineType = "linear"; * // => "linear": one of: "linear" | "exponential" | "logarithmic" | "polynomial" | "power" | "movingAvg" * ``` */ declare type PptxChartTrendlineType = 'linear' | 'exponential' | 'logarithmic' | 'polynomial' | 'power' | 'movingAvg'; /** * Supported chart type discriminators. * * @example * ```ts * const type: PptxChartType = "bar"; * // => "bar": one of: "bar" | "line" | "pie" | "doughnut" | "area" | "scatter" | … * ``` */ declare type PptxChartType = 'bar' | 'line' | 'pie' | 'ofPie' | 'doughnut' | 'area' | 'scatter' | 'bubble' | 'radar' | 'stock' | 'bar3D' | 'line3D' | 'pie3D' | 'area3D' | 'surface' | 'histogram' | 'waterfall' | 'funnel' | 'treemap' | 'sunburst' | 'boxWhisker' | 'regionMap' | 'combo' | 'unknown'; /** Up/down bar formatting on line and stock charts (`c:upDownBars`). */ declare interface PptxChartUpDownBars { /** Gap between bars as a percentage, constrained to 0 through 500. */ gapWidth?: number; upBars?: PptxChartShapeProps; downBars?: PptxChartShapeProps; } /** * A parsed chart-overlay shape positioned by a drawing anchor. * * Position is expressed as chart-relative fractions in {@link from}. For a * `relSizeAnchor` the opposite corner is {@link to} (also fractional); for an * `absSizeAnchor` the extent is {@link ext} in EMU. */ declare interface PptxChartUserShape { /** * Shape kind: text/preset shape, connector, picture, a group of the * above (`grpSp`, with its own {@link transform} and {@link children}, * nested arbitrarily; use `flattenChartUserShapes` from * `chart-user-shapes-parser.ts` to get a flat, render-ready leaf list * with the group transform already applied), or a bare placeholder for * a `graphicFrame` anchor child (deep content such as a nested chart or * table is out of scope; it only keeps the anchor's space accounted for * instead of the whole overlay disappearing). */ kind: 'sp' | 'cxnSp' | 'pic' | 'grpSp' | 'graphicFrame'; /** Anchor kind that positioned the shape. */ anchor: 'rel' | 'abs'; /** Top-left corner as chart-relative fractions (0-1). */ from: { x: number; y: number; }; /** Bottom-right corner as chart-relative fractions (0-1); relSizeAnchor only. */ to?: { x: number; y: number; }; /** Extent in EMU (cx, cy); absSizeAnchor only. */ ext?: { cx: number; cy: number; }; /** Preset geometry name (`a:prstGeom/@prst`), defaulting to `"rect"`. */ prst?: string; /** Resolved solid-fill hex colour, when present. */ fill?: string; /** Resolved line/stroke hex colour, when present. */ stroke?: string; /** Line width in points (`a:ln/@w` divided by 12700), when present. */ strokeWidth?: number; /** Text paragraphs of the shape's `txBody`, when present. */ paragraphs?: PptxChartUserShapeParagraph[]; /** * A `pic` anchor's alt text (`cdr:nvPicPr/cdr:cNvPr/@descr`), when * present. Editable independently of {@link rawXml}'s otherwise-verbatim * content: the serializer patches only this attribute onto the cloned * raw node, so a picture's blip and other markup are untouched. */ altText?: string; /** * This shape's OWN rotation in degrees (`a:xfrm/@rot`, on `spPr/a:xfrm` * for `sp`/`cxnSp`/`pic`, or directly on a top-level `graphicFrame`'s own * `a:xfrm`), when present. A top-level anchor's position/size is governed * by {@link from}/{@link to}/{@link ext}, never by this `a:xfrm`'s own * `off`/`ext` (see {@link rawXml}'s doc), but `rot`/`flipH`/`flipV` on that * same `a:xfrm` DO apply visually: verified against real PowerPoint (COM), * which writes e.g. `` * on a rotated overlay shape's `spPr`, with the `off`/`ext` values * unrelated to the anchor's own `cdr:from`/`cdr:to`. */ rotation?: number; /** This shape's OWN horizontal flip (`a:xfrm/@flipH`); see {@link rotation}'s doc. */ flipH?: boolean; /** This shape's OWN vertical flip (`a:xfrm/@flipV`); see {@link rotation}'s doc. */ flipV?: boolean; /** * Verbatim source XML of a `pic` or `graphicFrame` anchor child (the * `cdr:pic` / `cdr:graphicFrame` node itself, not the enclosing anchor), * or of the `cdr:grpSp` node itself when `kind === 'grpSp'` and the * group is untouched since parse (byte-identical passthrough). None of * these three kinds have a reconstructable typed representation that is * guaranteed lossless (a picture's blip reference, a nested chart/table's * graphic content, or a group's exact child ordering/ids), so the * serializer re-emits this verbatim when present instead of a lossy * rebuild. Editing a shape inside a group (via the SDK's path-based * overlay operations) clears the group's `rawXml` so the serializer * regenerates it from {@link transform}/{@link children} instead. Absent * for `sp`/`cxnSp`, which round-trip losslessly through their typed * fields above. */ rawXml?: XmlObject; /** Present when `kind === 'grpSp'`: the group's own transform. */ transform?: PptxChartUserShapeGroupTransform; /** Present when `kind === 'grpSp'`: the grouped children, nested arbitrarily. */ children?: PptxChartUserShapeGroupChild[]; } /** * One shape grouped inside a `cdr:grpSp` (or a nested `cdr:grpSp` itself). * Unlike a top-level {@link PptxChartUserShape}, a group child has no * drawing anchor of its own: its position is expressed in its parent * group's child coordinate space via {@link off}/{@link ext} (EMU, read * from the child's own `a:xfrm`), not as a chart-relative fraction. */ declare interface PptxChartUserShapeGroupChild { /** Shape kind, same vocabulary as {@link PptxChartUserShape.kind}. */ kind: 'sp' | 'cxnSp' | 'pic' | 'grpSp' | 'graphicFrame'; /** Position within the parent group's child coordinate space, in EMU. */ off: { x: number; y: number; }; /** Size within the parent group's child coordinate space, in EMU. */ ext: { cx: number; cy: number; }; /** Preset geometry name (`a:prstGeom/@prst`), defaulting to `"rect"`. */ prst?: string; /** Resolved solid-fill hex colour, when present. */ fill?: string; /** Resolved line/stroke hex colour, when present. */ stroke?: string; /** Line width in points (`a:ln/@w` divided by 12700), when present. */ strokeWidth?: number; /** Text paragraphs of the shape's `txBody`, when present. */ paragraphs?: PptxChartUserShapeParagraph[]; /** * A `pic` child's alt text (`cdr:nvPicPr/cdr:cNvPr/@descr`), when present. * Editable independently of {@link rawXml}'s otherwise-verbatim content: * the serializer patches only this attribute onto the cloned raw node. */ altText?: string; /** * This child's OWN rotation in degrees (`a:xfrm/@rot`), when present. * Composes with every enclosing group's own * {@link PptxChartUserShapeGroupTransform.rotation} (added) to produce the * leaf's final on-screen rotation; see `flattenChartUserShapes`. */ rotation?: number; /** This child's OWN horizontal flip (`a:xfrm/@flipH`); composes with an ancestor group's flip by XOR. */ flipH?: boolean; /** This child's OWN vertical flip (`a:xfrm/@flipV`); composes with an ancestor group's flip by XOR. */ flipV?: boolean; /** * Verbatim source XML of a `pic`/`graphicFrame` child, or of this node * itself when `kind === 'grpSp'` and the nested group is untouched since * parse. See {@link PptxChartUserShape.rawXml}'s doc for the same * contract one level up. */ rawXml?: XmlObject; /** Present when `kind === 'grpSp'`: this nested group's own transform. */ transform?: PptxChartUserShapeGroupTransform; /** Present when `kind === 'grpSp'`: this nested group's own children. */ children?: PptxChartUserShapeGroupChild[]; } /** * The DrawingML 2D group transform (`a:xfrm` inside `cdr:grpSpPr`) that * anchors a `grpSp`'s own box ({@link off}/{@link ext}) and establishes the * coordinate space its children are expressed in ({@link chOff}/{@link * chExt}), all in EMU. A child's position within the group is mapped into * the group's own box via * `frac = (child.off - chOff) / chExt`, then applied to the enclosing * anchor's box; see `flattenChartUserShapes` in * `chart-user-shapes-parser.ts`. */ declare interface PptxChartUserShapeGroupTransform { /** The group's own position in its parent's coordinate space, in EMU. */ off: { x: number; y: number; }; /** The group's own size in its parent's coordinate space, in EMU. */ ext: { cx: number; cy: number; }; /** Origin of the child coordinate space (`a:chOff`), in EMU. */ chOff: { x: number; y: number; }; /** Size of the child coordinate space (`a:chExt`), in EMU. */ chExt: { cx: number; cy: number; }; /** * The group's own rotation in degrees (`a:xfrm/@rot`, stored in 60,000ths * of a degree), when present. Rotates the whole group, and everything * grouped inside it, as a rigid body about the CENTRE of the group's own * box ({@link off}/{@link ext}); see `flattenChartUserShapes` in * `chart-user-shapes-parser.ts` for how this composes onto each contained * leaf's own {@link PptxChartUserShapeGroupChild.rotation}. Verified * against real PowerPoint (COM): a `cdr:grpSp`'s `cdr:grpSpPr/a:xfrm` does * carry `rot` the same way an ordinary shape's does. */ rotation?: number; /** The group's own horizontal flip (`a:xfrm/@flipH`), when present; composes onto children by XOR, see {@link rotation}'s doc. */ flipH?: boolean; /** The group's own vertical flip (`a:xfrm/@flipV`), when present; composes onto children by XOR, see {@link rotation}'s doc. */ flipV?: boolean; } /** A single paragraph of overlay-shape text with light formatting. */ declare interface PptxChartUserShapeParagraph { /** Joined run text of the paragraph. */ text: string; /** Font size in points (`a:rPr/@sz` divided by 100), when present. */ fontSize?: number; /** Whether the first run is bold (`a:rPr/@b`). */ bold?: boolean; /** Whether the first run is italic (`a:rPr/@i`). */ italic?: boolean; /** Resolved run colour hex (e.g. `"#FF0000"`), when present. */ color?: string; /** Paragraph alignment (`a:pPr/@algn`): left / centre / right. */ align?: 'l' | 'ctr' | 'r'; } /** * 3D viewing parameters for a chart (`c:view3D`, ECMA-376 §21.2.2.228 / * CT_View3D). * * All fields are optional and round-trip verbatim. * * - {@link rotX}: X-axis rotation in degrees (-90…90). * - {@link rotY}: Y-axis rotation in degrees (0…360). * - {@link depthPercent}: chart depth as a percentage of base width. * - {@link rAngAx}: `true` if axes meet at right angles. * - {@link perspective}: perspective angle in degrees (0…240). * - {@link hPercent}: height as a percentage of chart width. */ declare interface PptxChartView3D { rotX?: number; rotY?: number; depthPercent?: number; rAngAx?: boolean; perspective?: number; hPercent?: number; } /** Office 2016 ChartEx waterfall series layout options. */ declare interface PptxChartWaterfallOptions { /** Zero-based data point indexes rendered as absolute subtotal or total bars. */ subtotalIndices?: number[]; /** Whether connector lines are visible between adjacent bars. */ connectorLines?: boolean; } /** Color animation data parsed from `p:animClr`. */ declare interface PptxColorAnimation { /** Color interpolation space: "hsl" or "rgb". */ colorSpace: 'hsl' | 'rgb'; /** Direction for HSL interpolation: "cw" (clockwise) or "ccw". */ direction?: 'cw' | 'ccw'; /** * Optional `p:animClr/@path` value preserved for round-trip. When set, * the colour sweep follows a path-based interpolation rather than the * straight cw/ccw arc. ECMA-376 §19.5.13 documents this attribute as a * companion to `@dir` for HSL colour-space animations. */ path?: string; /** Starting color as hex string, or the bare scheme name (e.g. `accent1`) for a theme colour; see {@link fromColorRef}. */ fromColor?: string; /** Ending color as hex string, or the bare scheme name; see {@link toColorRef}. */ toColor?: string; /** * Color delta (for "by" animations) as hex string, or the bare scheme name; * see {@link byColorRef}. For HSL colour-space animations this retains the * historical byte-packed compatibility value; consumers should prefer * {@link hslDelta}, which preserves signed values. */ byColor?: string; /** * The typed theme reference when {@link fromColor} is an `a:schemeClr` * (including `tint`/`shade`/`lumMod`/`lumOff`/`alpha`), so playback can * resolve it against the deck's theme colour map. Absent when `fromColor` * is already a resolved `#rrggbb` hex (an `a:srgbClr` stop). */ fromColorRef?: PptxThemeColorRef; /** The typed theme reference for {@link toColor}; see {@link fromColorRef}. */ toColorRef?: PptxThemeColorRef; /** * The typed theme reference for {@link byColor} (RGB colour space only; an * HSL `by` is a signed delta, never a theme colour). See {@link fromColorRef}. */ byColorRef?: PptxThemeColorRef; /** * Typed HSL delta from `p:by/p:hsl`. This preserves signed values and their * OOXML units without forcing them through the legacy byte-packed `byColor` * representation. */ hslDelta?: PptxHslColorDelta; /** * Target attribute from `p:attrNameLst` (e.g. "fillcolor", "style.color", * "stroke.color"). Used to determine which CSS property to animate. */ targetAttribute?: string; /** * All sibling `p:animClr` behaviours authored for the same timing node. * The top-level fields continue to mirror the first behaviour for backwards * compatibility; this list is present only when there is more than one. */ components?: readonly PptxColorAnimation[]; } /** * A slide comment — may be a legacy positional comment or a modern * threaded comment with replies. * * @example * ```ts * const comment: PptxComment = { * id: "c1", * text: "Please update this chart.", * author: "Alice", * createdAt: "2024-06-01T10:00:00Z", * resolved: false, * }; * // => satisfies PptxComment * ``` */ declare interface PptxComment { id: string; text: string; /** Storage vocabulary used by this comment. Omitted means legacy PresentationML. */ format?: 'legacy' | 'modern'; /** Stable GUID author identifier used by Office 2021 modern comments. */ authorId?: string; /** Optional parent comment id for reply threading metadata. */ parentId?: string; author?: string; createdAt?: string; x?: number; y?: number; /** Whether this comment has been resolved/marked done. */ resolved?: boolean; /** Native p188 status token. */ status?: 'active' | 'resolved' | 'closed'; /** Modern comment classification tags and author IDs that liked the comment. */ tags?: string[]; likes?: string[]; startDate?: string; dueDate?: string; assignedTo?: string[]; /** Task completion in thousandths of a percent, from 0 through 100000. */ complete?: number; priority?: number; title?: string; /** Modern threaded comment support (p15:threadingInfo). */ threadId?: string; /** `@`-mentions, indexed into `text` (see {@link PptxCommentMention}). */ mentions?: PptxCommentMention[]; /** Replies to this comment (for modern threaded comments). */ replies?: PptxComment[]; /** ID of the element this comment is associated with (if any). */ elementId?: string; /** Original `p:cm` subtree, retained for unknown child and extension preservation. */ rawXml?: XmlObject; } /** * A comment author from `ppt/commentAuthors.xml`. * * Stores all attributes needed for lossless round-trip serialization * of the `p:cmAuthor` element (id, name, initials, lastIdx, clrIdx). * * @see ECMA-376 Part 1, §19.4.2 (cmAuthor) * * @example * ```ts * const author: PptxCommentAuthor = { * id: "0", * name: "John Doe", * initials: "JD", * lastIdx: 3, * clrIdx: 0, * }; * // => satisfies PptxCommentAuthor * ``` */ declare interface PptxCommentAuthor { /** Unique numeric author identifier (`@_id`). */ id: string; /** Author display name (`@_name`). */ name: string; /** Author initials (`@_initials`). */ initials: string; /** Last comment index used by this author (`@_lastIdx`). */ lastIdx: number; /** Colour index assigned to this author (`@_clrIdx`). */ clrIdx: number; /** Original `p:cmAuthor` subtree, retained for unknown attribute preservation. */ rawXml?: XmlObject; } /** * A single `@`-mention inside a modern comment body. * * Offsets index into the comment's FLATTENED plain text: every `a:t` value * below `p188:txBody` concatenated, with paragraphs joined by `\n`. That is the * same string `PptxComment.text` carries, so an edit to `text` invalidates * every offset after the edit point and the serializer re-bases them. * * The markup Office uses for a mention is `CT_Mention` (documented for the * SpreadsheetML `2018/threadedcomments` part): `mentionpersonId`, `mentionId`, * `startIndex` and `length`. The PowerPoint `2018/8/main` schema does not * publish a mention element at all, so `rawXml` is retained and re-emitted * attribute-for-attribute: a producer that spells the attributes differently * still round-trips. * * @example * ```ts * const mention: PptxCommentMention = { * personId: "{2CB2E9D0-D392-EB21-5D46-FBA34C1295E6}", * authorName: "Bob Example", * startIndex: 3, * length: 11, * }; * // => "Hi Bob Example can you check this".slice(3, 14) === "Bob Example" * ``` */ declare interface PptxCommentMention { /** `mentionId`: GUID identifying this mention instance. */ id?: string; /** `mentionpersonId`: the `p188:author` id of the mentioned person. */ personId: string; /** Display name resolved from the author list at parse time, when known. */ authorName?: string; /** Character offset of the mentioned span in the flattened plain text. */ startIndex: number; /** Character length of the mentioned span. */ length: number; /** * `uri` of the `p188:ext` this mention list was read from. Undefined means * the list is a direct child of `p188:cm`, which is where it is written for * newly authored mentions. */ containerUri?: string; /** Original `p188:mention` node, retained for unknown-attribute preservation. */ rawXml?: XmlObject; } /** * Common slide view properties shared by slideViewPr, outlineViewPr, * notesTextViewPr, and notesViewPr. */ declare interface PptxCommonSlideViewProperties { /** Whether snap-to-grid is enabled. */ snapToGrid?: boolean; /** Whether snap-to-objects is enabled. */ snapToObjects?: boolean; /** Whether drawing guides are shown. */ showGuides?: boolean; /** Whether the application may vary the scale automatically. */ variableScale?: boolean; /** Drawing guides shown in this slide view. */ guides?: PptxViewGuide[]; /** View origin (scroll position). */ origin?: PptxViewOrigin; /** View scale. */ scale?: PptxViewScale; } /** * A compatibility warning generated during parse or save when the * file uses features not fully supported by the editor. * * @example * ```ts * const warning: PptxCompatibilityWarning = { * code: "UNSUPPORTED_3D", * message: "3D rotation effects may not render accurately.", * severity: "warning", * scope: "element", * slideId: "slide-1", * elementId: "elem-42", * }; * // => satisfies PptxCompatibilityWarning * ``` */ declare interface PptxCompatibilityWarning { code: string; message: string; severity: 'info' | 'warning'; scope: 'presentation' | 'slide' | 'element' | 'save'; slideId?: string; elementId?: string; xmlPath?: string; } /** * Core document properties from `docProps/core.xml` (Dublin Core + OOXML). * * @example * ```ts * const core: PptxCoreProperties = { * title: "Q4 Business Review", * creator: "Alice", * created: "2024-01-15T08:00:00Z", * modified: "2024-06-01T12:30:00Z", * lastModifiedBy: "Bob", * }; * // => satisfies PptxCoreProperties * ``` */ declare interface PptxCoreProperties { /** dc:title */ title?: string; /** dc:subject */ subject?: string; /** dc:creator */ creator?: string; /** cp:keywords */ keywords?: string; /** dc:description */ description?: string; /** cp:lastModifiedBy */ lastModifiedBy?: string; /** cp:revision */ revision?: string; /** dcterms:created (ISO 8601) */ created?: string; /** dcterms:modified (ISO 8601) */ modified?: string; /** cp:category */ category?: string; /** cp:contentStatus */ contentStatus?: string; } /** * Shape names used for crop-to-shape (CSS `clip-path` equivalent). * * @example * ```ts * const shape: PptxCropShape = "ellipse"; * // => "ellipse": one of: none | ellipse | roundedRect | triangle | diamond | pentagon | hexagon | star * ``` */ declare type PptxCropShape = 'none' | 'ellipse' | 'roundedRect' | 'triangle' | 'diamond' | 'pentagon' | 'hexagon' | 'star'; declare interface PptxCustomDashSegment { /** Dash length as a non-negative percentage in thousandths of one percent. */ dash: number; /** Space length as a non-negative percentage in thousandths of one percent. */ space: number; } /** * A customer data reference from `p:custDataLst / p:custData`. * * Enterprise add-ins and integrations store custom data parts in the * package and reference them via relationship IDs in the slide or * presentation XML. * * @see ECMA-376 Part 1, §19.2.1.3 (custDataLst), §19.3.1.6 (custData) */ declare interface PptxCustomerData { /** Resolved part path inside the package (e.g. `customXml/item1.xml`). */ id?: string; /** Relationship ID referencing the custom data part. */ relId?: string; /** Raw string content of the custom data part (if resolvable). */ data?: string; /** OPC content type for the custom data part. */ contentType?: string; /** Raw `p:custData` XML retained for unknown-node preservation. */ rawXml?: XmlObject; } /** * Custom (non-preset) geometry path — only on shapes and pictures. * * Contains SVG path data and/or structured custom geometry paths * parsed from `a:custGeom/a:pathLst`. * * @example * ```ts * const custom: PptxCustomPathProperties = { * pathData: "M 0 0 L 100 0 L 100 100 Z", * pathWidth: 100, * pathHeight: 100, * }; * // => satisfies PptxCustomPathProperties * ``` */ declare interface PptxCustomPathProperties { /** SVG path data for custom shapes. */ pathData?: string; /** Coordinate-space width for the custom path. */ pathWidth?: number; /** Coordinate-space height for the custom path. */ pathHeight?: number; /** Structured custom geometry paths for editing (maps to a:custGeom/a:pathLst). */ customGeometryPaths?: CustomGeometryPath[]; /** Raw adjustment/guide/handle/connection/text-rectangle XML preserved for serialization. */ customGeometryRawData?: CustomGeometryRawData; /** * Typed XY adjustment handles parsed from `a:custGeom/a:ahLst/a:ahXY`. * SDK-built shapes can populate this and the writer will emit `` entries * even when no raw XML was preserved. */ customGeometryAdjustHandlesXY?: AdjustHandleXY[]; /** * Typed polar adjustment handles parsed from `a:custGeom/a:ahLst/a:ahPolar`. */ customGeometryAdjustHandlesPolar?: AdjustHandlePolar[]; /** * Typed connection sites parsed from `a:custGeom/a:cxnLst/a:cxn`. */ customGeometryConnectionSites?: ConnectionSite[]; /** * Typed text rectangle parsed from `a:custGeom/a:rect`. When present this is * preferred over {@link customGeometryRawData}'s `rectXml` on save. */ customGeometryTextRect?: CustomGeometryTextRect; } /** * A custom document property from `docProps/custom.xml`. * * @example * ```ts * const prop: PptxCustomProperty = { * name: "Project", * value: "pptx", * type: "lpwstr", * }; * // => satisfies PptxCustomProperty * ``` */ declare interface PptxCustomProperty { /** Property name. */ name: string; /** Property value (always stringified). */ value: string; /** Original VT type (e.g. "lpwstr", "i4", "bool", "filetime"). */ type: string; } /** * A named custom slide show (`p:custShowLst / p:custShow`). * * Custom shows define ordered subsets of slides that can be presented * independently of the full deck. * * @example * ```ts * const show: PptxCustomShow = { * name: "Executive Summary", * id: "0", * slideRIds: ["rId2", "rId5", "rId8"], * }; * // => satisfies PptxCustomShow * ``` */ declare interface PptxCustomShow { /** Custom show name. */ name: string; /** Custom show id. */ id: string; /** Ordered list of slide relationship IDs included in this custom show. */ slideRIds: string[]; /** Original `p:custShow` subtree used to preserve unmodelled attributes and extensions. */ rawXml?: XmlObject; } /** * Embedded font data extracted from a PPTX file. * * Used to register `@font-face` rules so the renderer can display * the correct typeface even when the system font is missing. * * @example * ```ts * const font: PptxEmbeddedFont = { * name: "CustomSans", * dataUrl: "data:font/truetype;base64,AAEAK...", * format: "truetype", * }; * // => satisfies PptxEmbeddedFont * ``` */ /** * A single Custom XML Data Part stored in `customXml/` within the OPC package. * * These parts are used by add-ins, data-binding, and enterprise templates * to store structured data alongside the presentation. * * @see ECMA-376 Part 1, §15.2.5 */ declare interface PptxCustomXmlPart { /** Item number (e.g. "1" for `customXml/item1.xml`). */ id: string; /** Raw XML string content of the custom XML item. */ data: string; /** Schema target namespace URI from `itemProps` (ds:schemaRef/@ds:uri). */ schemaUri?: string; /** Raw XML string content of the associated `itemProps` file. */ properties?: string; /** Raw XML string content of the OPC relationship file (`customXml/_rels/item{id}.xml.rels`). */ rels?: string; } /** * A single breakpoint in a ChartEx colour-by-value scale * (`cx:valueColorPositions/cx:colorPosition`). `kind` selects which of * CT_ColorPosition's union members was authored; `value` is absent for * `min`/`max` (they are implicit endpoints) and required otherwise. */ declare interface PptxCxValueColorPosition { kind: 'min' | 'max' | 'number' | 'percent'; value?: number; } /** * Root data structure returned by {@link PptxHandlerCore.load}. * * Contains every slide, canvas dimensions, theme data, layout options, * metadata, and optional features (custom shows, sections, macros, * digital signatures, embedded fonts). * * @example * ```ts * const data: PptxData = await handler.load(buffer); * console.log(`${data.slides.length} slides, ${data.width}×${data.height}`); * // => e.g. "24 slides, 960×540" * ``` */ declare interface PptxData { slides: PptxSlide[]; width: number; height: number; /** Slide width in EMU (for save round-trip). */ widthEmu?: number; /** Slide height in EMU (for save round-trip). */ heightEmu?: number; /** Slide size type from `p:sldSz/@type` (e.g. "screen4x3", "screen16x9", "custom"). */ slideSizeType?: string; /** Notes page width in EMU (from `p:notesSz`). */ notesWidthEmu?: number; /** Notes page height in EMU (from `p:notesSz`). */ notesHeightEmu?: number; layoutOptions?: PptxLayoutOption[]; headerFooter?: PptxHeaderFooter; /** Presentation-level properties parsed from `presentationPr.xml`. */ presentationProperties?: PptxPresentationProperties; /** Named custom slide shows from `p:custShowLst`. */ customShows?: PptxCustomShow[]; /** Ordered presentation sections from `p:sectionLst` / `p14:sectionLst`. */ sections?: PptxSection[]; warnings?: PptxCompatibilityWarning[]; /** Map of theme colour scheme keys to resolved hex values. */ themeColorMap?: Record; /** Full parsed theme object with colours, fonts, and name. */ theme?: PptxTheme; /** Available theme parts discovered in `ppt/theme/`. */ themeOptions?: PptxThemeOption[]; /** Parsed table style definitions from `ppt/tableStyles.xml`. */ tableStyleMap?: ParsedTableStyleMap; /** * The current default table style GUID (`ppt/tableStyles.xml`'s * `a:tblStyleLst/@def`): the style PowerPoint applies to a newly inserted * table. Matches `PptxSaveOptions.tableStylesDefaultId` so a save call * that omits it can fall back to what was loaded. */ tableStylesDefaultId?: string; /** Whether the presentation is password-protected. */ isPasswordProtected?: boolean; /** Embedded font data (name + binary data URL) extracted from the presentation. */ embeddedFonts?: PptxEmbeddedFont[]; /** Typed `p:embeddedFontLst` package metadata, including unresolved variants. */ embeddedFontList?: PptxEmbeddedFontList; /** * `p:presentation/@embedTrueTypeFonts` (ECMA-376 §19.2.1.26): the author's * saved preference that TrueType fonts referenced by the deck be embedded. * `undefined` when the attribute is absent (spec default `false`). * * This is purely declarative in this library: fonts are only ever embedded * when the caller explicitly supplies `embeddedFontList`/`embeddedFonts` * (there is no automatic embed-on-save), so toggling this flag does not * gate any embedding behaviour of its own here - it only round-trips the * author's stated preference, the same way real PowerPoint reads it back * as a checkbox state rather than a trigger. See `@saveSubsetFonts`, * which is a separate, deliberately unimplemented flag (no glyph * subsetting) that does not interact with this one. */ embedTrueTypeFonts?: boolean; /** * Presentation-level default text style (`p:defaultTextStyle`): the * last-resort paragraph/run-property fallback for every shape (placeholder * or not) whose local and inherited cascade leaves a field undefined. * Keyed the same way as {@link PptxMasterTextStyles} categories: `-1` is * `a:defPPr`, `0`-`8` are `a:lvl1pPr`-`a:lvl9pPr`. */ defaultTextStyle?: PptxTextStyleLevels; /** Most-recently-used colour list from presentation properties. */ mruColors?: string[]; /** Parsed notes master data if present in the PPTX. */ notesMaster?: PptxNotesMaster; /** Parsed handout master data if present in the PPTX. */ handoutMaster?: PptxHandoutMaster; /** Structured slide master data for each master in the presentation. */ slideMasters?: PptxSlideMaster[]; /** Parsed tag collections attached to the presentation or slides. */ tags?: PptxTagCollection[]; /** Custom document properties from `docProps/custom.xml`. */ customProperties?: PptxCustomProperty[]; /** Core document properties from `docProps/core.xml`. */ coreProperties?: PptxCoreProperties; /** Extended (application) properties from `docProps/app.xml`. */ appProperties?: PptxAppProperties; /** Whether the presentation contains VBA macros (is a .pptm file). */ hasMacros?: boolean; /** Whether the presentation contains digital signatures (`_xmlsignatures/` parts). */ hasDigitalSignatures?: boolean; /** Number of digital signatures found. */ digitalSignatureCount?: number; /** Presentation-level drawing guides from `p:extLst`. */ presentationGuides?: PptxDrawingGuide[]; /** View properties from `ppt/viewProps.xml`. */ viewProperties?: PptxViewProperties; /** Write-protection verifier from `p:modifyVerifier` in `presentation.xml`. */ modifyVerifier?: PptxModifyVerifier; /** Photo album metadata from `p:photoAlbum` in `presentation.xml`. */ photoAlbum?: PptxPhotoAlbum; /** * Legacy Smart Tags recognizer reference from `p:smartTags` in * `presentation.xml`. Read-only: there is no data model for the * recognizer part's own content, so this exists to make the reference * inspectable and to prove it survives a save (the owning part and its * relationship are preserved passively, like any other unmodelled part). */ smartTags?: PptxSmartTagsReference; /** East Asian line-break settings from `p:kinsoku` in `presentation.xml`. */ kinsoku?: PptxKinsoku; /** Custom XML data parts from `customXml/` in the OPC package. */ customXmlParts?: PptxCustomXmlPart[]; /** Customer data references from `p:custDataLst` in `presentation.xml`. */ customerData?: PptxCustomerData[]; /** Thumbnail image binary data from `docProps/thumbnail.{jpeg,png}`. */ thumbnailData?: Uint8Array; /** Comment authors parsed from `ppt/commentAuthors.xml` for round-trip preservation. */ commentAuthors?: PptxCommentAuthor[]; /** Office 2021 p188 authors from the modern Author part. */ modernCommentAuthors?: PptxModernCommentAuthor[]; /** * OOXML conformance class of the loaded file. * - `'strict'` -- ISO/IEC 29500 Strict (uses `purl.oclc.org` namespace URIs) * - `'transitional'` -- ECMA-376 Transitional (uses `schemas.openxmlformats.org` URIs) * * When saving, if the save option `conformance` is `'preserve'` (default), * the file will be saved using the same conformance class as the original. */ conformance?: 'strict' | 'transitional'; } /** * A drawing guide parsed from OOXML extension lists. * * Slide-level and presentation-level guides are shown as thin coloured * lines that help users align elements. * * @example * ```ts * const guide: PptxDrawingGuide = { * id: "g1", * orientation: "horz", * positionEmu: 457200, * color: "#FF0000", * }; * // => { id: "g1", orientation: "horz", positionEmu: 457200, color: "#FF0000" } satisfies PptxDrawingGuide * ``` */ declare interface PptxDrawingGuide { /** Unique identifier (from `@_id` attribute or generated). */ id: string; /** Orientation: horizontal or vertical. */ orientation: 'horz' | 'vert'; /** Position in EMU (converted from pos attribute). */ positionEmu: number; /** Optional guide colour as hex string (e.g. "#FF0000"). */ color?: string; } /** * A single element on a PPTX slide. * * This is a **discriminated union**: narrow on `element.type` to access * variant-specific properties like `imageData` (image/picture), `pathData` * (shape), or `textSegments` (text/shape). */ declare type PptxElement = TextPptxElement | ShapePptxElement | ConnectorPptxElement | ImagePptxElement | PicturePptxElement | TablePptxElement | ChartPptxElement | SmartArtPptxElement | OlePptxElement | MediaPptxElement | GroupPptxElement | InkPptxElement | ContentPartPptxElement | ZoomPptxElement | Model3DPptxElement | UnknownPptxElement; /** * High-level animation data associated with a slide element. * * Combines entrance, exit, and emphasis presets with timing and * trigger configuration. Used by the editor’s animation panel * and the `setPptxElementAnimation` tool. * * @example * ```ts * const anim: PptxElementAnimation = { * elementId: "title_1", * entrance: "fadeIn", * durationMs: 600, * order: 1, * trigger: "afterPrevious", * }; * // => { elementId: "title_1", entrance: "fadeIn", durationMs: 600, order: 1, trigger: "afterPrevious" } * ``` */ declare interface PptxElementAnimation { elementId: string; entrance?: PptxAnimationPreset; exit?: PptxAnimationPreset; emphasis?: PptxAnimationPreset; durationMs?: number; delayMs?: number; order?: number; /** * The {@link order} the loader derived from the slide's `p:timing` tree for * an entry whose `pptx:editorMeta` record authored no `@order`. The tree * already expresses that position (and every load re-derives it), so the * writer omits `@order` while `order` still equals this value; a reorder * changes `order` and the attribute is written again. Load-time bookkeeping * only; never set it by hand. */ orderFromTimeline?: number; trigger?: PptxAnimationTrigger; /** * Shape ID that triggers this animation: the shape clicked for * `onShapeClick`, or the media element whose bookmark fires it for * `onMediaBookmark`. */ triggerShapeId?: string; /** Bookmark name (`p14:bmk/@name`) an `onMediaBookmark` trigger waits for. */ triggerBookmark?: string; timingCurve?: PptxAnimationTimingCurve; repeatCount?: number; repeatMode?: PptxAnimationRepeatMode; /** Direction for directional effects (fly in/out, wipe, etc.). */ direction?: PptxAnimationDirection; /** Sequence mode — animate as one object or by paragraph/word/letter. */ sequence?: PptxAnimationSequence; /** What happens after the animation finishes playing. */ afterAnimation?: PptxAfterAnimationAction; /** Dim-to color hex (used when afterAnimation is "dimToColor"). */ afterAnimationColor?: string; /** SVG motion path string for custom motion path animations. */ motionPath?: string; /** * Path edit mode for `p:animMotion/@pathEditMode`. Defaults to "relative" * when emitted without an explicit value. */ motionPathEditMode?: string; /** Comma-separated point-types string for `p:animMotion/@ptsTypes`. */ motionPtsTypes?: string; /** Authored path rotation in degrees from `p:animMotion/@rAng`. */ motionPathRotationAngle?: number; /** Motion-path rotation centre X in slide percentage units (`p:rCtr/@x`). */ motionPathRotationCenterX?: number; /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */ motionPathRotationCenterY?: number; /** * Sound relationship ID to play when animation triggers. Written on save * as a `p:audio/p:cMediaNode` sibling of the effect's own `p:childTnLst` * (see `PptxNativeAnimation.soundRId` for the COM-verified detail). */ soundRId?: string; /** Resolved sound file path from relationship. */ soundPath?: string; /** * The `@_name` to write on the embedded sound (`p:sndTgt`). For a stock * gallery pick this is the exact PowerPoint file name (e.g. * `"CHIMES.WAV"`), which is what makes PowerPoint itself recognise the * sound as that built-in entry when it reopens the saved deck (there is no * separate "built-in" flag anywhere in the schema). Set by * `pptx-viewer-shared`'s `setEffectSound` when the pick carries a * `soundName`; absent for a custom file with no meaningful name. */ soundName?: string; /** Whether to stop any currently playing sound (`p:endSnd`). */ stopSound?: boolean; /** * Pending, not-yet-embedded sound chosen in the authoring UI, as a * `data:audio/...;base64,...` URL. Mirrors the `imageData` / * `mediaData` pending-embed convention used elsewhere in the typed model: * on save, the writer converts this to real bytes under `ppt/media/`, * mints a relationship, and replaces this field with the resolved * {@link soundRId} / {@link soundPath}. Cleared once embedded. */ soundData?: string; /** * Display name for the chosen sound (e.g. the uploaded file's name), * shown by the authoring UI's sound picker. Purely cosmetic; has no * OOXML equivalent and is not required for playback. For a stock gallery * pick, the UI derives its label from {@link soundName} via the catalogue * instead of this field. */ soundFileName?: string; /** * Per-build-level timing template(s) from the {@link sequence}'s own * `p:bldP/p:tmplLst` (ECMA-376 §19.5.84), carried over from the loaded * `PptxNativeAnimation.buildTemplates` this element animation was derived * from so a full timing-tree rebuild (`PptxAnimationWriteService`'s * `buildTimingXml`, when the slide had no prior `p:timing`) can re-emit * them instead of silently dropping the deck's authored per-level * defaults. Absent when {@link sequence} carries no such template. */ buildTemplates?: PptxTimingTemplate[]; } /** * Properties shared by **every** element on a slide. * * Position and size are in pixels (converted from EMU at parse time). * Optional properties apply to subsets of elements or may be absent in * the original OOXML. * * @example * ```ts * const base: PptxElementBase = { * id: "el_001", * x: 100, y: 50, * width: 400, height: 200, * rotation: 15, * opacity: 0.9, * }; * // => satisfies PptxElementBase * ``` */ declare interface PptxElementBase { id: string; /** * The shape's native OOXML id from `p:cNvPr/@id` (an unsigned integer, as a * string), captured on load. Distinct from {@link id}, which is a synthetic * positional identity (`${slidePath}-shape-${index}`) the loader assigns for * selection / undo / template tracking. Animations target shapes by this * native id (`p:spTgt/@spid`), so it is the stable key used to reconcile an * animation to the element it animates across a save/reload round trip. * Absent on SDK-created elements until one is minted at save time. */ shapeId?: string; /** Element name from `cNvPr/@name`. Used for morph transition matching via the `!!` naming convention. */ name?: string; /** * `p:nvSpPr/p:nvPr/p:ph/@type` (lower-cased) when the shape is a placeholder: * `title`, `ctrtitle`, `body`, `subtitle`, `ftr`, `dt`, `sldnum`, ... * * Captured on load so consumers can tell a footer placeholder from a text box * without re-walking `rawXml`. Absent on non-placeholder shapes and on * SDK-created elements. */ placeholderType?: string; /** * `p:nvSpPr/p:nvPr/p:ph/@sz` (lower-cased): `"full"`, `"half"`, or * `"quarter"`. Captured on load for round-trip completeness. Per * ECMA-376 §19.3.1.36 (CT_Placeholder) this size hint is only meaningful * when NO `a:xfrm` exists anywhere in the placeholder's inheritance * chain (slide -> layout -> master); every real-world corpus placeholder * that carries `@sz` already has an explicit `a:xfrm` at the master * level, so no renderer currently derives a size from this field. */ placeholderSz?: string; /** * `p:nvSpPr/p:nvPr/p:ph/@orient` (only `"vert"` is meaningful per * `ST_Direction`). Captured on load for round-trip completeness. In * practice every placeholder observed with `orient="vert"` also carries * an explicit `a:bodyPr/@vert`, which already drives vertical-text * rendering, so this field is not currently read by any renderer. */ placeholderOrient?: 'vert'; x: number; y: number; width: number; height: number; /** * The exact EMU integer `x` was parsed from (the `a:off/@_x` this * element's own `a:xfrm` carried on load), when the parser could resolve * one. `x` itself is always `Math.round(xEmu / EMU_PER_PX)` at parse * time, but that rounding is lossy: re-deriving EMU from `x` on save * (`Math.round(x * EMU_PER_PX)`) can drift from the original value by up * to half a pixel's worth of EMU on every load/save cycle even when * nothing touched this element. Kept alongside `x` (not instead of it) so * every consumer that only cares about on-screen position is unaffected; * only the save-side xfrm writer (`resolveXfrmEmu` in * `xfrm-emu-resolution.ts`) reads this, and only when `x` still equals * `Math.round(xEmu / EMU_PER_PX)` (i.e. nothing moved this element since * load) does it re-emit `xEmu` verbatim instead of re-quantizing `x`. * `undefined` for an SDK-created element or one whose transform could not * be resolved to a usable `a:off` on load. */ xEmu?: number; /** The exact EMU integer `y` was parsed from (`a:off/@_y`). See {@link xEmu}. */ yEmu?: number; /** The exact EMU integer `width` was parsed from (`a:ext/@_cx`). See {@link xEmu}. */ widthEmu?: number; /** The exact EMU integer `height` was parsed from (`a:ext/@_cy`). See {@link xEmu}. */ heightEmu?: number; /** Resolved load-time transform for a shape with no own a:xfrm. Used only to detect edits. */ inheritedTransform?: Pick; rotation?: number; /** Skew along the X axis in degrees (parsed from `@_skewX` in 1/60000ths of a degree). */ skewX?: number; /** Skew along the Y axis in degrees (parsed from `@_skewY` in 1/60000ths of a degree). */ skewY?: number; flipHorizontal?: boolean; flipVertical?: boolean; /** Whether this element is hidden (used by the Elements Panel visibility toggle). */ hidden?: boolean; /** Element-level opacity (0-1). */ opacity?: number; rawXml?: XmlObject; /** Shape-level click action (from `a:hlinkClick` on `p:cNvPr`). */ actionClick?: PptxAction; /** Shape-level hover action (from `a:hlinkHover` on `p:cNvPr`). */ actionHover?: PptxAction; /** Shape lock attributes parsed from `p:cNvSpPr/a:spLocks`. */ locks?: PptxShapeLocks; /** * Opaque `` children captured from the shape's `` whose * URI is not recognised by a typed extractor (hidden fill/line, image * effects, …). Preserved verbatim and re-emitted on save so unknown * vendor extensions survive a round-trip. * * Mirrors the existing `effectDagXml` / `endParaRunProperties` raw-XML * preservation pattern. */ extLstXml?: XmlObject[]; } declare interface PptxEmbeddedFont { name: string; dataUrl: string; bold?: boolean; italic?: boolean; /** CSS font format hint (e.g. "truetype", "opentype"). */ format?: 'truetype' | 'opentype' | 'woff' | 'woff2'; /** * Deobfuscated (clear-text) font binary data preserved from load * for round-trip re-embedding on save. When present, the save * pipeline will re-obfuscate and write this data back into the ZIP. */ rawFontData?: Uint8Array; /** * Original ZIP path of the font part (e.g. `ppt/fonts/{GUID}.fntdata`). * Preserved from load for round-trip. */ partPath?: string; /** * The GUID used for obfuscation, either from the `fontKey` attribute * or extracted from the part path. Preserved from load for round-trip. */ fontGuid?: string; /** * Relationship ID (e.g. `rId21`) of the font part in * `ppt/_rels/presentation.xml.rels`. Preserved from load so the save * pipeline can reuse the original part/rel instead of minting a new * GUID-named copy alongside the stale original. */ originalRId?: string; /** * Raw bytes of the original obfuscated font part exactly as they were * stored in the source ZIP. When the loader could not determine a * usable GUID (e.g. EOT extraction path), the save pipeline preserves * these bytes verbatim under the original path/rel. */ originalPartBytes?: Uint8Array; } declare interface PptxEmbeddedFontDataId { /** Required relationship identifier from `r:id`. */ relationshipId?: string | null; /** Original leaf retained for unknown attribute preservation. */ rawXml?: XmlObject; } declare interface PptxEmbeddedFontDescriptor { typeface?: string | null; panose?: string | null; pitchFamily?: string | null; charset?: string | null; rawXml?: XmlObject; } declare interface PptxEmbeddedFontList { fonts: PptxEmbeddedFontListEntry[]; /** Original list retained for unknown attribute and child preservation. */ rawXml?: XmlObject; } declare interface PptxEmbeddedFontListEntry { font: PptxEmbeddedFontDescriptor; regular?: PptxEmbeddedFontDataId | null; bold?: PptxEmbeddedFontDataId | null; italic?: PptxEmbeddedFontDataId | null; boldItalic?: PptxEmbeddedFontDataId | null; rawXml?: XmlObject; } /** Parsed data extracted from an embedded xlsx workbook. */ declare interface PptxEmbeddedWorkbookData { /** Category labels from the first column/row. */ categories: string[]; /** Data series extracted from worksheet cells. */ series: Array<{ name: string; values: number[]; }>; /** Whether the workbook uses the 1904 date system. */ date1904?: boolean; } /** * Target format for slide export. * * @see {@link PptxExportOptions} */ declare type PptxExportFormat = 'pdf' | 'png' | 'svg'; /** * Options controlling slide export to raster or vector formats. * * @example * ```ts * const opts: PptxExportOptions = { * format: "png", * slideIndices: [0, 2, 4], * dpi: 300, * }; * // => satisfies PptxExportOptions * ``` */ declare interface PptxExportOptions { /** Target format. */ format: PptxExportFormat; /** Slide indices to export (0-based). If omitted, all slides are exported. */ slideIndices?: number[]; /** Output width in pixels (for PNG). Height is derived from aspect ratio. */ width?: number; /** DPI for raster export (default 150). */ dpi?: number; /** Whether to include hidden slides. */ includeHidden?: boolean; } /** * External data source reference for a chart (c:externalData). * * Charts can reference an external Excel workbook via a relationship ID * that points to an external file (TargetMode="External"). The * `autoUpdate` flag indicates whether the chart should refresh its * cached data from the external source on open. * * @example * ```ts * const ext: PptxExternalData = { * relId: "rId2", * targetPath: "file:///C:/Data/budget.xlsx", * autoUpdate: true, * }; * // => satisfies PptxExternalData * ``` */ declare interface PptxExternalData { /** Relationship ID referencing the external data source in the chart .rels. */ relId: string; /** Resolved external file path or URL from the relationship target. */ targetPath?: string; /** Whether to auto-update data from the external source on open. */ autoUpdate?: boolean; /** Raw binary data of the embedded xlsx workbook (from ppt/embeddings/). */ embeddedWorkbookData?: Uint8Array; } /** Nested build choice carried by `p:bldGraphic`. */ declare type PptxGraphicBuild = { mode: 'asOne'; rawXml?: XmlObject; } | { mode: 'sub'; kind: 'diagram'; build: string; reverse: boolean; rawXml?: XmlObject; } | { mode: 'sub'; kind: 'chart'; build: string; animateBackground: boolean; rawXml?: XmlObject; }; /** * A single unrecognised `//` extension on a * graphicFrame, captured verbatim so the round-trip can preserve future or * vendor-specific markup that the parser doesn't yet understand. * * The XML is preserved as a fast-xml-parser object tree (the same shape as * `rawXml` on other elements) so the save layer can re-emit it through the * existing builder without lossy string manipulation. */ declare interface PptxGraphicFrameExtension { /** The `@_uri` attribute identifying the extension (e.g. `{C3CD43...}`). */ uri: string; /** Parsed XML payload of the extension, suitable for re-serialization. */ xml: XmlObject; } /** Positive grid spacing from `p:gridSpacing`. */ declare interface PptxGridSpacing { cx: number; cy: number; } /** * Public facade for the PPTX editor handler. * * The implementation lives in `PptxHandlerCore` so this surface can stay small, * stable, and easy to replace with alternate implementations in the future. */ declare class PptxHandler extends PptxHandlerCore { /** * Create a new blank PPTX presentation from scratch. * * This is a convenience static method that delegates to * {@link PresentationBuilder.create}. The returned handler is fully * initialized and ready for editing, adding slides, and saving. * * @param options - Optional slide dimensions, theme, and metadata. * @returns Handler, parsed data, and a slide builder factory. * * @example * ```ts * const { handler, data, createSlide } = await PptxHandler.createBlank({ * title: "My Deck", * theme: { colors: { accent1: "#FF6B6B" } }, * }); * * data.slides.push( * createSlide("Blank") * .addText("Hello", { fontSize: 36 }) * .build() * ); * * const bytes = await handler.save(data.slides); * ``` */ static createBlank(options?: PresentationOptions): Promise; /** * Create a new PPTX presentation from scratch. * * Alias for {@link createBlank}. Generates a valid minimal OpenXML * package and returns a fully initialized handler ready for editing, * adding slides, and saving. * * @param options - Optional slide dimensions, theme, metadata, * and initial slide count. * @returns Handler, parsed data, and a slide builder factory. * * @example * ```ts * const { handler, data, createSlide } = await PptxHandler.create({ * title: "Q4 Report", * initialSlideCount: 3, * theme: { colors: { accent1: "#FF6B6B" } }, * }); * * // The presentation already has 3 blank slides * console.log(data.slides.length); // => 3 * * // Add more slides with content * data.slides.push( * createSlide("Blank") * .addText("Hello", { fontSize: 36 }) * .build() * ); * * const bytes = await handler.save(data.slides); * ``` */ static create(options?: PresentationOptions): Promise; /** * Parse a presentation from an `ArrayBuffer`, accepting both `.pptx` * archives and portable `pptx-viewer-json` documents. * * The buffer is sniffed first: JSON documents (leading `{` plus the * `"pptx-viewer-json"` format marker) are routed to {@link loadFromJson}; * everything else goes through the regular ZIP/OLE2 pipeline. */ load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise; /** * Load a presentation from `pptx-viewer-json` text. * * A minimal blank package is generated and loaded first so that the * handler keeps a valid in-memory archive (editing and {@link save} keep * working), then the imported model is overlaid on top: imported * presentation fields win, and the slide array is replaced wholesale. */ loadFromJson(text: string, options?: PptxHandlerLoadOptions): Promise; } /** * Thin facade over the PPTX runtime implementation. * * All heavy parsing, serialisation, and XML manipulation is delegated to an * {@link IPptxHandlerRuntime}. This surface stays stable and small so that * callers remain decoupled from the runtime internals and host-specific * runtime swaps (e.g. WASM vs Node) can be done transparently. * * @remarks * - Constructed once per open document. * - Errors from encrypted files are caught at `load()` time via * {@link EncryptedFileError}. * - `PptxXmlBuilder` instances returned by `createXmlBuilder()` / `Builder()` * operate directly on the runtime’s in-memory ZIP. * * @example * ```ts * const handler = new PptxHandlerCore(); * const data = await handler.load(arrayBuffer); * // ... mutate slides ... * const out = await handler.save(data.slides); * // => Uint8Array of the modified .pptx file * ``` */ declare class PptxHandlerCore { private readonly runtime; /** * Create a new handler, optionally injecting a custom runtime. * * Resolution order: * 1. `dependencies.runtime` — use as-is. * 2. `dependencies.runtimeFactory` — call `createRuntime()` once. * 3. Fall back to {@link createDefaultPptxHandlerRuntime}. * * @param dependencies - Optional runtime or factory override. * * @example * ```ts * const core = new PptxHandlerCore(); * // => PptxHandlerCore instance with default runtime * ``` */ constructor(dependencies?: PptxHandlerCoreDependencies); /** * Release all resources held by this handler instance. * * Revokes every Blob URL created for images/media, clears all * in-memory caches, and releases the in-memory ZIP archive. * * Call this when the handler is no longer needed (e.g. component * unmount) to free memory immediately rather than waiting for GC. * * After calling `dispose()`, do not call any other methods — create * a new `PptxHandler` instance instead. */ dispose(): void; /** * Return any compatibility warnings detected during the most recent load. * * Warnings indicate features the editor cannot fully represent (e.g. * SmartArt, 3-D effects, embedded OLE objects). * * @returns Array of {@link PptxCompatibilityWarning} objects. */ getCompatibilityWarnings(): PptxCompatibilityWarning[]; /** * Get the slide layout options available in the loaded presentation. * * Each option maps to a `` inside the PPTX archive. * * @returns Array of {@link PptxLayoutOption} entries. */ getLayoutOptions(): PptxLayoutOption[]; /** * Build the artwork thumbnails backing the New Slide / Layout galleries. * * Parsing happens on first request and is memoised afterwards, so opening * the gallery costs one pass over the layout parts and reopening it costs * nothing. Callers that only need one entry should prefer * {@link getLayoutPreview}. * * @param layoutPaths - Restrict the result to these layouts; defaults to * every layout in the presentation. * @returns One {@link PptxLayoutPreview} per resolvable layout. */ getLayoutPreviews(layoutPaths?: readonly string[]): Promise; /** * Build the artwork thumbnail for a single layout. * * @param layoutPath - Archive path of the `p:sldLayout` part. * @returns The preview, or `null` when the presentation has no such layout. */ getLayoutPreview(layoutPath: string): Promise; /** * Create a fluent XML builder scoped to the given presentation data. * * The builder provides a chainable API for constructing and inserting * OpenXML nodes directly into the runtime’s in-memory ZIP. * * @param data - The parsed {@link PptxData} to bind the builder to. * @returns A new {@link PptxXmlBuilder} instance. */ createXmlBuilder(data: PptxData): PptxXmlBuilder; /** * Shorthand alias for {@link createXmlBuilder}. * * @param data - Parsed presentation data. * @returns A {@link PptxXmlBuilder} instance. */ Builder(data: PptxData): PptxXmlBuilder; /** * Register a background image for a specific template layout path. * * @param path - The internal PPTX path (e.g. `ppt/slideLayouts/slideLayout1.xml`). * @param backgroundColor - Optional hex colour to render behind the image. */ setTemplateBackground(path: string, backgroundColor: string | undefined): void; /** * Retrieve the background colour previously set for a template layout. * * @param path - The internal PPTX layout path. * @returns Hex colour string, or `undefined` if none was set. */ getTemplateBackgroundColor(path: string): string | undefined; /** * Replace the presentation’s theme by loading an external `.thmx` file. * * @param themePath - Absolute or relative path to the `.thmx` file. * @param applyToAllMasters - Apply to every slide master (default `true`). * * @example * ```ts * await handler.setPresentationTheme("./themes/corporate.thmx"); * // => void — theme XML replaced in the in-memory ZIP * ``` */ setPresentationTheme(themePath: string, applyToAllMasters?: boolean): Promise; /** * Modify the theme’s colour scheme (accent colours, background, text, etc.). * * @param colorScheme - A {@link PptxThemeColorScheme} with hex colour values. * * @example * ```ts * await handler.updateThemeColorScheme({ * dk1: "#1A1A2E", dk2: "#16213E", * lt1: "#FFFFFF", lt2: "#E8E8E8", * accent1: "#0F3460", accent2: "#533483", * accent3: "#E94560", accent4: "#F0A500", * }); * // => void — colour scheme updated in the in-memory theme XML * ``` */ updateThemeColorScheme(colorScheme: PptxThemeColorScheme): Promise; /** * Update the theme’s font scheme (heading + body typefaces). * * @param fontScheme - A {@link PptxThemeFontScheme} with font family names. * * @example * ```ts * await handler.updateThemeFontScheme({ * majorFont: "Montserrat", * minorFont: "Open Sans", * }); * // => void — font scheme updated in the in-memory theme XML * ``` */ updateThemeFontScheme(fontScheme: PptxThemeFontScheme): Promise; /** * Rename the presentation theme. * * @param name - New display name for the theme. */ updateThemeName(name: string): Promise; /** * Resolve a `` block (`a:lnRef` / `a:fillRef` / `a:effectRef` / * `a:fontRef`) against the loaded theme, exactly as the load path would for * a shape whose `spPr` authors nothing. Apply the returned `shapeStyle` to a * shape and it renders like PowerPoint's Shape Styles entry and saves as a * bare `` with an empty `spPr`, which is what PowerPoint writes. */ resolveStyleMatrixReferences(styleXml: XmlObject): ResolvedStyleMatrix; /** * Apply a complete theme in one call (colour scheme + font scheme + optional name). * * This is a convenience wrapper over {@link updateThemeColorScheme}, * {@link updateThemeFontScheme}, and {@link updateThemeName}. * * @param colorScheme - Colour definitions. * @param fontScheme - Font definitions. * @param themeName - Optional theme display name. * * @example * ```ts * await handler.applyTheme( * { dk1: "#000", lt1: "#FFF", accent1: "#0066CC", /* … *\/ }, * { majorFont: "Helvetica", minorFont: "Arial" }, * "Corporate 2025", * ); * // => void — colour scheme, font scheme, and name applied atomically * ``` */ applyTheme(colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme, themeName?: string): Promise; /** * Switch the presentation's theme, updating both the underlying XML and * re-resolving all element colours in-place. * * This is the high-level API for theme switching: it updates the theme * data in the ZIP, then patches all resolved colours in the provided * `PptxData` so that elements immediately reflect the new colour scheme * without requiring a re-parse. * * @param data - The current parsed presentation data (mutated in-place for * convenience, but a new `PptxData` object is also returned). * @param colorScheme - New colour scheme (12 colours). * @param fontScheme - Optional new font scheme. * @param themeName - Optional theme display name. * @returns The updated PptxData with re-resolved colours. * * @example * ```ts * import { THEME_PRESETS } from "pptx-viewer-core"; * * const ion = THEME_PRESETS.find(p => p.id === "ion")!; * const newData = await handler.switchTheme( * data, * ion.colorScheme, * ion.fontScheme, * ion.name, * ); * // => PptxData with all colours updated to the Ion theme * ``` */ switchTheme(data: PptxData, colorScheme: PptxThemeColorScheme, fontScheme?: PptxThemeFontScheme, themeName?: string): Promise; /** * Apply a built-in theme preset to the presentation. * * Convenience wrapper around {@link switchTheme} that accepts a * {@link PptxThemePreset} directly. * * @param data - The current parsed presentation data. * @param preset - One of the built-in presets from {@link THEME_PRESETS}. * @returns The updated PptxData. * * @example * ```ts * import { THEME_PRESETS } from "pptx-viewer-core"; * * const preset = THEME_PRESETS.find(p => p.id === "facet")!; * const newData = await handler.switchThemePreset(data, preset); * ``` */ switchThemePreset(data: PptxData, preset: PptxThemePreset): Promise; /** * Parse a PPTX file from an `ArrayBuffer` and return structured data. * * If the file is encrypted and a `password` is provided in `options`, * the file will be decrypted before parsing. If no password is provided * for an encrypted file, throws {@link EncryptedFileError}. * * @param data - Raw bytes of the `.pptx` file (may be encrypted OLE2). * @param options - Optional load-time settings, including `password`. * @returns Parsed {@link PptxData} containing slides, theme, layouts, etc. * * @example * ```ts * // Load an unencrypted file: * const pptx = await handler.load(buf.buffer); * * // Load a password-protected file: * const pptx = await handler.load(buf.buffer, { password: "secret" }); * console.log(`${pptx.slides.length} slides loaded`); * ``` */ load(data: ArrayBuffer, options?: PptxHandlerLoadOptions): Promise; /** * Extract chart data from a graphic-frame XML node. * * @param slidePath - Internal archive path of the slide (e.g. `ppt/slides/slide1.xml`). * @param graphicFrame - Parsed XML object for the `` node. * @returns Chart data, or `undefined` if the frame is not a chart. */ getChartDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise; /** * Extract SmartArt data from a graphic-frame XML node. * * @param slidePath - Internal archive path of the slide. * @param graphicFrame - Parsed XML object for the `` node. * @returns SmartArt data, or `undefined` if the frame is not SmartArt. */ getSmartArtDataForGraphicFrame(slidePath: string, graphicFrame: XmlObject | undefined): Promise; /** * Get the base64-encoded data URL for an embedded image. * * @param imagePath - Archive-relative path (e.g. `ppt/media/image1.png`). * @returns A `data:image/...;base64,...` string, or `undefined` if not found. */ getImageData(imagePath: string): Promise; /** * Extract a media file from the PPTX archive as an ArrayBuffer. * Avoids the 33% base64 overhead of getImageData — prefer this for * audio/video media that will be played via Blob URLs. */ getMediaArrayBuffer(mediaPath: string): Promise; /** * Serialise current slides back into a PPTX byte array. * * @param slides - The (possibly mutated) slide array. * @param options - Optional save-time settings (e.g. thumbnail generation). * @returns `Uint8Array` of the complete `.pptx` file. * * @example * ```ts * const bytes = await handler.save(data.slides); * await fs.writeFile("output.pptx", Buffer.from(bytes)); * // => Uint8Array written to disk as a valid .pptx file * ``` */ save(slides: PptxSlide[], options?: PptxHandlerSaveOptions): Promise; /** * Serialise slides and then encrypt the output with a password. * * This is a convenience method that calls {@link save} followed by * {@link encryptPptx}. The result is an OLE2 container suitable for * opening in Microsoft PowerPoint with a password prompt. * * @param slides - The (possibly mutated) slide array. * @param password - The password to encrypt with. * @param options - Optional save-time and encryption settings. * @returns `Uint8Array` of the encrypted OLE2 file. * * @example * ```ts * const bytes = await handler.saveEncrypted(data.slides, "secret"); * await fs.writeFile("protected.pptx", Buffer.from(bytes)); * // => Encrypted OLE2 file requiring password to open * ``` */ saveEncrypted(slides: PptxSlide[], password: string, options?: PptxHandlerSaveOptions & { encryption?: EncryptionOptions; }): Promise; /** * Get the slide layouts available for a specific slide. * * Returns layouts belonging to the same slide master as the given slide. * This is useful for building a layout picker UI scoped to the current * slide's master. * * @param slideIndex - Zero-based slide index. * @param slides - Current slides array. * @returns Array of {@link PptxLayoutOption} entries for the slide's master. * * @example * ```ts * const layouts = await handler.getAvailableLayoutsForSlide(0, data.slides); * console.log(layouts.map(l => l.name)); * // => ["Title Slide", "Title and Content", "Blank", ...] * ``` */ getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise; /** * Resolve the editable template (master + layout) elements a slide * inherits, each carrying a `master-` / `layout-` prefixed id. * * This is the foundation for an "edit template/master" feature. The * returned elements are the decorative master/layout shapes the loader * already merges behind slide-authored content (master shapes behind, * layout shapes on top); placeholders are excluded. The same elements are * shared by every slide inheriting the layout/master, so editing one and * saving updates the shared part. * * To persist an edit, keep the mutated template element inside the * `slide.elements` array passed to {@link save}; the save writer reads * template elements from there and writes their shape XML back into the * owning layout/master `p:spTree`. * * @param slideId - The slide's archive path (the `PptxSlide.id`). * @returns Master + layout elements with prefixed ids (may be empty). * * @example * ```ts * const templateEls = await handler.getTemplateElementsForSlide(slide.id); * const logo = templateEls.find((e) => e.id.startsWith("master-")); * if (logo) { * logo.x += 10; * slide.elements = [...slide.elements, logo]; * await handler.save(data.slides); * } * ``` */ getTemplateElementsForSlide(slideId: string): Promise; /** * Apply a different layout to an existing slide. * * Updates the slide's relationship to point to the new layout and * refreshes layout-derived properties (background, layout name). * The slide's own content elements are preserved. * * @param slideIndex - Zero-based slide index. * @param layoutPath - Archive path of the target layout * (e.g. `ppt/slideLayouts/slideLayout2.xml`). * @param slides - Current slides array (the slide at `slideIndex` * is replaced in-place). * @returns The updated {@link PptxSlide} with new layout metadata. * * @example * ```ts * const updated = await handler.applyLayoutToSlide( * 0, * "ppt/slideLayouts/slideLayout3.xml", * data.slides, * ); * console.log(updated.layoutName); * // => "Two Content" * ``` */ applyLayoutToSlide(slideIndex: number, layoutPath: string, slides: PptxSlide[]): Promise; /** * Scan the loaded PPTX archive for all theme parts (`ppt/theme/theme*.xml`) * and return their paths and display names. */ getAvailableThemes(): Promise>; /** * Export selected slides to a vector or raster format, keyed by slide index. * * **This does not produce PPTX files.** The previous version of this comment * said each entry was "a standalone PPTX with only that slide", named the * option `slideIndexes` (the real field is `slideIndices`), and wrote the * bytes to `slide_N.pptx`. None of that was ever true: the runtime has * always taken a `format` of `svg` / `png` / `pdf`. Per-slide PPTX * extraction is a different operation and is not implemented here. * * Only `svg` works without a host-supplied backend, and it works fully: * the headless {@link SvgExporter} renders it with no DOM. `png` and `pdf` * THROW, because this package carries no rasteriser; use a viewer binding's * browser export pipeline, or override `exportSlides` on the runtime with * your own backend. * * @param slides - Full slide array. * @param options - Export options (`format`, `slideIndices`, `width`, ...). * @returns A `Map` of exported files. Hidden slides * are omitted unless `options.includeHidden` is set, so the map can be * smaller than `options.slideIndices`. * @throws {Error} when `options.format` is `png` or `pdf`. * * @example * ```ts * const exports = await handler.exportSlides(data.slides, { * format: 'svg', * slideIndices: [0, 2], * }); * for (const [idx, bytes] of exports) { * await fs.writeFile(`slide_${idx}.svg`, Buffer.from(bytes)); * } * // => Map: one SVG document per exported slide * ``` */ exportSlides(slides: PptxSlide[], options: PptxExportOptions): Promise>; } /** * Dependency injection options for {@link PptxHandlerCore}. * * Provide either `runtime` (an already-constructed runtime) or * `runtimeFactory` (a factory that will be called once). When neither * is supplied the default runtime is created automatically. * * @example * ```ts * // Use the default runtime: * const core = new PptxHandlerCore(); * * // Inject a custom runtime: * const core = new PptxHandlerCore({ runtime: myRuntime }); * * // Supply a factory for lazy creation: * const core = new PptxHandlerCore({ runtimeFactory: myFactory }); * // => PptxHandlerCore instance with injected runtime * ``` */ declare interface PptxHandlerCoreDependencies { runtime?: IPptxHandlerRuntime; runtimeFactory?: IPptxHandlerRuntimeFactory; } declare interface PptxHandlerLoadOptions { eagerDecodeImages?: boolean; password?: string; /** * Maximum total uncompressed bytes accepted from the input ZIP archive. * Defaults to 500 MiB. When the sum of `_data.uncompressedSize` across * all archive entries exceeds this cap, `load()` rejects with a * {@link ZipBombError}. A hard cap of 65 536 archive entries also * applies. */ maxUncompressedBytes?: number; /** * When `false` (default), relationship targets that resolve to * `http://` or `https://` URLs are dropped from rendered slides * (image, picture, background). Set to `true` to allow external image * URLs to flow through to ``. * * Disabled by default to mitigate SSRF / privacy-leak vectors in * server-side rendering and headless export pipelines. */ allowExternalImages?: boolean; } declare interface PptxHandlerSaveOptions { headerFooter?: PptxHeaderFooter; presentationProperties?: PptxPresentationProperties; customShows?: PptxCustomShow[]; sections?: PptxSection[]; coreProperties?: PptxCoreProperties; appProperties?: PptxAppProperties; customProperties?: PptxCustomProperty[]; /** Updated notes master data to save back to notesMaster1.xml. */ notesMaster?: PptxNotesMaster; /** Updated handout master data to save back to handoutMaster1.xml. */ handoutMaster?: PptxHandoutMaster; /** * Updated slide masters to save back to ppt/slideMasters/slideMaster*.xml. * Each entry in the array applies typed mutations (clrMap, hf flags, * background) to the master at its `path`. Masters not listed here pass * through verbatim from the original load. */ slideMasters?: PptxSlideMaster[]; /** * Updated slide layouts to save back to ppt/slideLayouts/slideLayout*.xml. * Each entry applies typed mutations (clrMapOverride, attrs, hf flags, * background) to the layout at its `path`. Layouts not listed here pass * through verbatim from the original load. */ slideLayouts?: PptxSlideLayout[]; /** Updated tag collections to save back to ppt/tags/tag*.xml. */ tags?: PptxTagCollection[]; /** Presentation-level customer data references to author or update. */ customerData?: PptxCustomerData[]; /** Photo album metadata to save back to `p:photoAlbum`. */ photoAlbum?: PptxPhotoAlbum; /** * Slide dimensions to write back to `p:sldSz`. * * Omitting the option preserves the load-time dimensions verbatim, which * is why an edit made through a viewer's Slide Size control has to reach * the save call: nothing else in the pipeline can observe it. * * PowerPoint derives `Presentation.PageSetup.SlideSize` from `@cx`/`@cy` * alone (verified by COM: an A4-typed `p:sldSz` carrying 4:3 dimensions * still reports `ppSlideSizeCustom`), so `type` is written for fidelity * but the dimensions are what actually decide the reported preset. */ slideSize?: PptxSlideSize; /** East Asian line-break settings to save back to `p:kinsoku`. */ kinsoku?: PptxKinsoku | null; /** Write-protection verifier. Set to `null` to remove, `undefined` to preserve existing. */ modifyVerifier?: PptxModifyVerifier | null; /** * `p:presentation/@embedTrueTypeFonts` to write. `undefined` preserves * whatever was loaded (or omits the attribute for a brand-new deck); * purely declarative here, see {@link PptxData.embedTrueTypeFonts}. */ embedTrueTypeFonts?: boolean; /** * Presentation-level default text style edits to save back to * `p:defaultTextStyle`. Only the levels present in the map are touched; * omitted levels and any unmodelled XML on an edited level survive * untouched. See {@link PptxData.defaultTextStyle}. */ defaultTextStyle?: PptxTextStyleLevels; /** View properties to save back to ppt/viewProps.xml. */ viewProperties?: PptxViewProperties; /** * Table style edits to save back to `ppt/tableStyles.xml`. Pass the * `tableStyleMap` from `PptxData` (optionally with edited entries) * to persist user edits. The `def` GUID and any unmodelled XML are * preserved verbatim. Omitting the option round-trips the original * part untouched. */ tableStyles?: ParsedTableStyleMap; /** * Set `ppt/tableStyles.xml`'s `` to this style GUID * (normalised to uppercase-with-braces). `undefined` preserves the * existing default; there is no removal form (`@def` is required by the * schema and PowerPoint always points it at a real style). No-op when the * archive has no `ppt/tableStyles.xml`, same as {@link tableStyles}. */ tableStylesDefaultId?: string; /** * Style GUIDs to remove from `ppt/tableStyles.xml` entirely, kept as a * separate opt-in list rather than inferred from omission on * {@link tableStyles}: that map is documented as safe to pass a PARTIAL * edit (only the entries a caller actually touched), so treating every * GUID missing from it as "delete this" would silently destroy untouched * styles on an ordinary targeted edit. A GUID here that is also the * current (or newly requested) default is left in place and skipped. */ tableStylesToDelete?: string[]; /** * Target output format. * - `'pptx'` (default): Standard presentation. * - `'ppsx'`: Slide-show file (opens in presentation mode). * - `'pptm'`: Macro-enabled presentation (requires VBA data). * - `'ppt'`: Legacy binary PowerPoint 97-2003 presentation. Bypasses the * OOXML ZIP pipeline entirely; see `PptxHandlerRuntimeSaveLegacyPpt`. * Elements with no binary equivalent (charts, SmartArt, media, OLE, ink, * 3D models) are degraded to a rasterised preview picture or a labelled * placeholder, each reported via a `scope: 'save'`-adjacent * `PptxCompatibilityWarning`. */ outputFormat?: PptxSaveFormat; /** * Password for RC4 CryptoAPI encryption of a `'ppt'`-format save. Ignored * for every other {@link outputFormat}; encrypting a `.pptx`/`.ppsx`/`.pptm` * save uses {@link IPptxHandlerRuntime.saveEncrypted}'s separate AES/Agile * OLE2 wrapping instead, since the legacy binary format's own encryption * scheme is embedded directly in the `.ppt` stream rather than wrapping an * already-produced package. */ pptPassword?: string; /** * Embedded fonts to write back (or add) to the saved PPTX. * * Pass the `embeddedFonts` array from `PptxData` to preserve existing * embedded fonts during save. You can also add new fonts by including * entries with `rawFontData` populated. * * When omitted, the save pipeline will automatically re-embed any * fonts that were loaded from the original PPTX and have `rawFontData` * preserved (i.e. the default is lossless round-trip). */ embeddedFonts?: PptxEmbeddedFont[]; /** Typed embedded-font list metadata. Set to null to remove fonts and relationships. */ embeddedFontList?: PptxEmbeddedFontList | null; /** * OOXML conformance class for the saved output. * - `'preserve'` (default): use the same conformance as the loaded file. * - `'strict'`: force Strict Open XML (ISO/IEC 29500) namespace URIs. * - `'transitional'`: force Transitional (ECMA-376) namespace URIs. */ conformance?: 'strict' | 'transitional' | 'preserve'; } /** * Parsed handout master from `ppt/handoutMasters/handoutMaster1.xml`. * * @example * ```ts * const handout: PptxHandoutMaster = { * path: "ppt/handoutMasters/handoutMaster1.xml", * slidesPerPage: 6, * }; * // => satisfies PptxHandoutMaster * ``` */ declare interface PptxHandoutMaster { /** File path within the PPTX archive. */ path: string; /** Background colour of the handout master. */ backgroundColor?: string; /** Background image data URL. */ backgroundImage?: string; /** Crop, tiling and image effects authored on the background blip fill. */ backgroundImageProperties?: PptxImageProperties; /** Placeholder shapes found on the handout master. */ placeholders?: PptxPlaceholderFrame[]; /** Editable elements on the handout master (header, footer, date, page number, slide placeholders). */ elements?: PptxElement[]; /** Number of slides per page for handout print layout (1, 2, 3, 4, 6, or 9). */ slidesPerPage?: number; /** Header/footer flags from `` on the handout master (P-H3). */ headerFooter?: PptxHeaderFooterFlags; /** Colour map from `` (12 alias attributes). Applied at save time. */ clrMap?: Record; } /** * Header, footer, date-time, and slide-number placeholders. * * Parsed from `ppt/presProps.xml` and individual slide layouts. * * @example * ```ts * const hf: PptxHeaderFooter = { * hasFooter: true, * footerText: "Confidential", * hasSlideNumber: true, * }; * // => satisfies PptxHeaderFooter * ``` */ declare interface PptxHeaderFooter { hasHeader?: boolean; headerText?: string; hasFooter?: boolean; footerText?: string; hasDateTime?: boolean; dateTimeText?: string; dateTimeAuto?: boolean; /** * The master date placeholder's own `a:fld/@type` (e.g. "datetime2"), NOT a * format pattern. It is one of the predefined OOXML datetime field types * (`datetime1`-`datetime13`); the display pattern for each is resolved by * `resolveFieldDateText` in `packages/shared/src/render/text-field-substitution.ts`. */ dateFormat?: string; hasSlideNumber?: boolean; } /** * Per-part header/footer flags from `` (CT_HeaderFooter, ECMA-376 * §19.3.1.21). Defaults are "all true" — fields are only set on the typed * model when they were explicitly read, so callers can distinguish "unset" * (preserve original XML) from "false" (override). */ declare interface PptxHeaderFooterFlags { /** `@hdr` — show header placeholder. Spec default: `true`. */ hasHeader?: boolean; /** `@ftr` — show footer placeholder. Spec default: `true`. */ hasFooter?: boolean; /** `@dt` — show date/time placeholder. Spec default: `true`. */ hasDateTime?: boolean; /** `@sldNum` — show slide-number placeholder. Spec default: `true`. */ hasSlideNumber?: boolean; } /** Signed HSL channel deltas parsed from `p:animClr/p:by/p:hsl`. */ declare interface PptxHslColorDelta { /** Hue offset in degrees. OOXML stores this in 60000ths of a degree. */ hue: number; /** Saturation offset in percentage points. */ saturation: number; /** Lightness offset in percentage points. */ lightness: number; } declare interface PptxImageEffects { /** Brightness adjustment (-100 to 100). */ brightness?: number; /** Contrast adjustment (-100 to 100). */ contrast?: number; /** Duotone colour pair. */ duotone?: { color1: string; color2: string; /** Original effect XML, retained while the resolved colours are unchanged. */ rawXml?: XmlObject; }; /** Grayscale flag. */ grayscale?: boolean; /** Saturation adjustment (-100 to 100). */ saturation?: number; /** Color wash overlay. */ colorWash?: { color: string; opacity: number; }; /** Artistic effect name (blur, pencilGrayscale, paintStrokes, etc.). */ artisticEffect?: string; /** Artistic effect radius/amount, normalised to 0..100. */ artisticRadius?: number; /** * Every numeric attribute of the source `a14:artistic*` element, raw and * un-normalised (`trans`, `pencilSize`, `crackSpacing`, …). The attribute set * differs per effect, so this is the lossless companion to the single * {@link PptxImageEffects.artisticRadius} number. */ artisticParams?: Record; /** * Name of the artistic effect ALREADY baked into the image data, which a * renderer must not apply a second time. Set from the `a14` blip extension, * which PowerPoint writes alongside a pre-rendered bitmap (see * {@link PptxBackgroundRemoval}), and normally equal to * {@link PptxImageEffects.artisticEffect}. * * It records the NAME rather than a boolean so that picking a different * effect in this library's inspector (which patches `artisticEffect` alone) * still renders: the two names then differ. */ artisticPrerenderedEffect?: string; /** * PowerPoint "Remove Background" state (`a14:backgroundRemoval`). Edit-time * metadata: the removal is already baked into the image data. */ backgroundRemoval?: PptxBackgroundRemoval; /** * `a14:imgLayer/@r:embed`: relationship id of the PRISTINE original image * the baked effects were derived from (PowerPoint stores it as an HD Photo * `.wdp` part, which browsers cannot decode). */ originalImageRelId?: string; /** * PowerPoint 2010+ Corrections panel "Sharpen/Soften" * (`a14:sharpenSoften/@amount`). Raw as the XML carries it: 1/1000ths of a * percent, `-100000` (fully softened) .. `100000` (fully sharpened). * Edit-time metadata like the artistic effects: PowerPoint bakes the result * into the stored bitmap. */ sharpenSoften?: { amount: number; }; /** * PowerPoint 2010+ Corrections panel "Brightness/Contrast" * (`a14:brightnessContrast/@bright`, `@contrast`). Raw 1/1000ths of a * percent, `-100000` .. `100000`. Distinct from the legacy `a:blip/@bright` * + `@contrast` pair in {@link PptxImageEffects.brightness} / * {@link PptxImageEffects.contrast}, which PowerPoint 2007 wrote and which * a renderer still applies. */ brightnessContrast?: { bright?: number; contrast?: number; }; /** * PowerPoint 2010+ Color panel "Color Tone" * (`a14:colorTemperature/@colorTemp`). Raw Kelvin value, `1500` .. `11500`; * `6500` is neutral. */ colorTemperature?: { colorTemp: number; }; /** * PowerPoint 2010+ Color panel "Color Saturation" (`a14:saturation/@sat`). * Raw 1/1000ths of a percent: `100000` is unchanged, `0` is grayscale, * `400000` the maximum. Named `colorSaturation` because * {@link PptxImageEffects.saturation} is the viewer-side -100..100 knob * that has no OOXML counterpart. */ colorSaturation?: { sat: number; }; /** * The Corrections / Color panel values ALREADY baked into the image data, * which a renderer must not apply a second time. The a14 counterpart of * {@link PptxImageEffects.artisticPrerenderedEffect}: PowerPoint writes the * corrected bitmap to the main `a:blip` and keeps the pristine original in * `a14:imgLayer` (measured on a real deck: the stored PNG is a monotone tonal * transform of the `.wdp` original, slope 0.7 for `contrast="-40000"`). * * Holds the VALUES rather than a boolean so that changing one of the four * fields in this library's inspector still renders: a field that differs * from its snapshot is applied, one that matches is skipped. */ prerenderedCorrections?: PptxImagePrerenderedCorrections; /** Alpha modulation fixed: non-negative percentage (100 means unchanged opacity). */ alphaModFix?: number; /** Original alpha modulation fixed node, including foreign attributes. */ alphaModFixRawXml?: XmlObject; /** Bi-level threshold: converts to 1-bit black/white (0-100). */ biLevel?: number; /** Colour change: swap one colour range for another (used for transparency keying). */ clrChange?: { clrFrom: string; clrTo: string; /** Whether the target colour is fully transparent (alpha = 0). */ clrToTransparent?: boolean; /** Original effect XML, including colour transforms and extensions. */ rawXml?: XmlObject; }; /** Original grayscale node, including extension or foreign attributes. */ grayscaleRawXml?: XmlObject; /** Original bi-level node, including extension or foreign attributes. */ biLevelRawXml?: XmlObject; /** * Alpha inverse effect (`a:alphaInv`). Inverts the alpha channel; an optional * colour child shifts the inversion baseline. */ alphaInv?: { /** Optional baseline colour (hex). */ color?: string; /** Original effect XML, including colour transforms and foreign attributes. */ rawXml?: XmlObject; }; /** Alpha ceiling (`a:alphaCeiling`): clamps any non-zero alpha to fully opaque. Boolean flag. */ alphaCeiling?: boolean; /** Original alpha ceiling node, including foreign attributes. */ alphaCeilingRawXml?: XmlObject; /** Alpha floor (`a:alphaFloor`): clamps any non-fully-opaque alpha to fully transparent. Boolean flag. */ alphaFloor?: boolean; /** Original alpha floor node, including foreign attributes. */ alphaFloorRawXml?: XmlObject; /** * Alpha modulate (`a:alphaMod`). The schema requires a single `cont` (effect * container) child; we preserve the inner XML opaquely for round-trip. */ alphaMod?: { /** Raw opaque XML for the `a:cont` child to preserve on save. */ contRawXml?: Record; /** Original effect XML, including foreign attributes. */ rawXml?: XmlObject; /** * Multiplicative alpha percentage (0..100+), read from a nested * `` inside `contRawXml` when present - the common * real-world shape of `a:alphaMod` (` * `). Derived/read-only: a renderer multiplies the source alpha * by this, distinct from the top-level {@link alphaModFix} sibling * effect. Not written back independently on save; `contRawXml` is what * round-trips. */ amt?: number; }; /** Alpha replace (`a:alphaRepl`): replaces alpha with the given fixed-percent value (0..100). */ alphaRepl?: number; /** Original alpha replace node, including foreign attributes. */ alphaReplRawXml?: XmlObject; /** Alpha bi-level (`a:alphaBiLevel`): threshold (0..100) above which alpha becomes fully opaque. */ alphaBiLevel?: number; /** Original alpha bi-level node, including foreign attributes. */ alphaBiLevelRawXml?: XmlObject; /** * Colour replace (`a:clrRepl`): replaces all colour information in an image * with the given solid colour. Stores the raw colour child to preserve scheme * colour references and modifiers. */ clrRepl?: { /** Resolved hex colour. */ color: string; /** Raw opaque colour XML for round-trip. */ rawXml?: Record; }; /** Luminance modulation (`a:lum`): bright/contrast as fixed percentages (0..100). */ lum?: { bright?: number; contrast?: number; }; /** HSL modulation (`a:hsl`): hue (0..360 degrees), saturation/luminance (-100..100). */ hsl?: { hue?: number; sat?: number; lum?: number; }; /** Image-effect tint (`a:tint` inside blip): hue (0..360), amount (-100..100). */ tint?: { hue?: number; amt?: number; }; /** * Fill overlay (`a:fillOverlay`): overlays a fill on top of the blip. * Stores blend mode and the raw inner fill XML for round-trip. */ fillOverlay?: { blend: 'over' | 'mult' | 'screen' | 'darken' | 'lighten'; /** Raw opaque fill XML preserved for round-trip. */ fillRawXml?: Record; /** * Resolved hex colour, when the overlay fill is a plain `a:solidFill` * (the common case for a picture-style colour overlay). `undefined` for * a gradient/pattern/picture overlay fill - see {@link resolvedGradient} / * {@link resolvedPattern} instead. `fillRawXml` still round-trips * losslessly regardless of which of the three resolved. */ resolvedColor?: string; /** Resolved opacity (0-1) of the `a:solidFill` overlay colour, when resolved. */ resolvedOpacity?: number; /** * Resolved gradient, when the overlay fill is `a:gradFill`. A renderer * composites this as an SVG paint server (`` / * ``) rather than a flat flood colour. */ resolvedGradient?: { type: 'linear' | 'radial'; /** Gradient angle in degrees (`a:lin/@ang`), for a linear gradient. */ angle?: number; stops: Array<{ color: string; position: number; opacity?: number; }>; }; /** * Resolved preset pattern, when the overlay fill is `a:pattFill`. A * renderer composites this as a tiled SVG paint server. */ resolvedPattern?: { preset: string; foreground?: string; background?: string; }; }; /** Blur (`a:blur`): radius in EMU and grow flag. */ blur?: { rad?: number; grow?: boolean; }; } /** * PowerPoint "Remove Background" state (`a14:backgroundRemoval`). * * The four edges are the RETAINED rectangle as 0..1 fractions of the image * (OOXML stores them as per-100000 relative units), and the mark lists are the * segmentation hints the user painted. * * **This is edit-time metadata, not a render instruction.** PowerPoint bakes the * removal into the bitmap referenced by the main `a:blip/@r:embed` and keeps the * pristine original in `a14:imgLayer/@r:embed`. Verified against PowerPoint COM: * a slide exported with and without this element is byte-identical. A renderer * that clips to the retained rectangle would clip an image whose background has * already been removed. * * @example * ```ts * const removal: PptxBackgroundRemoval = { top: 0.12, bottom: 0.88, left: 0.07, right: 0.93 }; * // => retains the middle of the image; the marks list stays empty * ``` */ /** * Snapshot of the a14 Corrections / Color panel values as they were read from * the file, kept on {@link PptxImageEffects.prerenderedCorrections} so a * renderer can tell a baked-in value from one changed in this library. */ declare interface PptxImagePrerenderedCorrections { sharpenSoften?: { amount: number; }; brightnessContrast?: { bright?: number; contrast?: number; }; colorTemperature?: { colorTemp: number; }; colorSaturation?: { sat: number; }; } /** * Image content mixin: present on image and picture elements. * * Contains the decoded image data (base64 data URL or archive path), * alt text, crop insets, tiling settings, and image effects. * * @example * ```ts * const props: PptxImageProperties = { * imagePath: "ppt/media/image1.png", * altText: "Company logo", * cropLeft: 0.05, * cropRight: 0.05, * }; * // => { imagePath: "ppt/media/image1.png", altText: "Company logo", cropLeft: 0.05, cropRight: 0.05 } * ``` */ declare interface PptxImageProperties { /** Base64 data-URL for the decoded image. */ imageData?: string; /** Path within the PPTX ZIP archive. */ imagePath?: string; /** Base64 data-URL for an SVG variant (from blip extension asvg:svgBlip). Preferred over raster when available. */ svgData?: string; /** Path to the SVG file within the PPTX ZIP archive. */ svgPath?: string; /** Alt text / description from `p:cNvPr/@descr`. */ altText?: string; /** Crop from left edge as 0..1 fraction (OOXML `a:srcRect/@l`). */ cropLeft?: number; /** Crop from top edge as 0..1 fraction (OOXML `a:srcRect/@t`). */ cropTop?: number; /** Crop from right edge as 0..1 fraction (OOXML `a:srcRect/@r`). */ cropRight?: number; /** Crop from bottom edge as 0..1 fraction (OOXML `a:srcRect/@b`). */ cropBottom?: number; /** * Stretch target inset from the left frame edge as a signed fraction * (OOXML `a:stretch/a:fillRect/@l`). Unlike `cropLeft` (which selects a * region of the SOURCE bitmap), a fill-rect selects the region of the * FRAME the whole image is stretched into; negative values push the * image beyond the frame edge, and the overflow is clipped. */ fillRectLeft?: number; /** Stretch target inset from the top frame edge (`a:fillRect/@t`). */ fillRectTop?: number; /** Stretch target inset from the right frame edge (`a:fillRect/@r`). */ fillRectRight?: number; /** Stretch target inset from the bottom frame edge (`a:fillRect/@b`). */ fillRectBottom?: number; /** Image tiling offset X in px. */ tileOffsetX?: number; /** Image tiling offset Y in px. */ tileOffsetY?: number; /** Image tiling scale X as percentage (100 = 100%). */ tileScaleX?: number; /** Image tiling scale Y as percentage (100 = 100%). */ tileScaleY?: number; /** Image tiling flip mode. */ tileFlip?: 'none' | 'x' | 'y' | 'xy'; /** Image tiling alignment. */ tileAlignment?: string; /** * Print-resolution hint in DPI (`a:blipFill/@dpi`). PowerPoint records this * when it downsamples an embedded image for a target print quality; it has * no on-screen rendering effect (a `0`/absent value means "use the source * image's native resolution"). Parsed for round-trip / API fidelity only. */ dpi?: number; /** Image recolour/artistic effect properties. */ imageEffects?: PptxImageEffects; /** * Crop-to-shape (CSS clip-path shape name). * * PowerPoint implements "Crop to Shape" by writing the picture's own * `a:prstGeom`, so this is a typed view over `shapeType`: on load it is * derived from the preset (`ellipse` -> `'ellipse'`, `roundRect` -> * `'roundedRect'`, `star5` -> `'star'`, ...; see * `utils/crop-shape-geometry`), and on save a changed value rewrites the * preset. `'none'` / `undefined` leaves the geometry alone. */ cropShape?: PptxCropShape; } /** * East Asian line-break (kinsoku) settings from `p:kinsoku` in `presentation.xml`. * * Defines forbidden start/end characters for a given language so that * line-breaking follows East Asian typographic rules. * * @see ECMA-376 Part 1, §19.2.1.17 */ declare interface PptxKinsoku { /** Language code (e.g. "ja-JP", "zh-CN"). */ lang?: string | null; /** Characters that cannot begin a line. */ invalStChars?: string; /** Characters that cannot end a line. */ invalEndChars?: string; /** Original leaf retained for unknown attribute preservation. */ rawXml?: XmlObject; } /** * A slide layout available in the loaded presentation. * * Each entry maps to a `` inside `ppt/slideLayouts/`. * * @example * ```ts * const layout: PptxLayoutOption = { * path: "ppt/slideLayouts/slideLayout2.xml", * name: "Title and Content", * }; * // => satisfies PptxLayoutOption * ``` */ declare interface PptxLayoutOption { path: string; name: string; /** Standard layout type from `p:sldLayout/@type` (e.g. "obj", "twoColTx", "blank"). */ type?: string; /** ZIP path of the slide master this layout belongs to. */ masterPath?: string; } /** * Rendered content of a single layout, used to draw gallery thumbnails. * * Produced on demand rather than during load: materialising every layout's * artwork (and decoding its images) up front costs a noticeable amount of time * on decks with many masters, and most sessions never open the layout gallery * at all. * * @example * ```ts * const preview: PptxLayoutPreview = { * path: "ppt/slideLayouts/slideLayout2.xml", * width: 960, * height: 540, * elements: [], * placeholders: [{ type: "title" }], * }; * // => satisfies PptxLayoutPreview * ``` */ declare interface PptxLayoutPreview { /** ZIP path of the layout this preview belongs to. */ path: string; /** Slide width in CSS pixels, so a thumbnail can compute its own scale. */ width: number; /** Slide height in CSS pixels. */ height: number; /** Background resolved from the layout, falling back to its master's. */ backgroundColor?: string; /** Background image data URL, when the layout or master declares one. */ backgroundImage?: string; /** Crop, tiling and image effects authored on the resolved background image. */ backgroundImageProperties?: PptxImageProperties; /** The layout's own artwork (pictures, shapes and static text). */ elements: PptxElement[]; /** Placeholder slots, drawn as outlined frames in the gallery. */ placeholders: PptxPlaceholderFrame[]; } /** * Text styles parsed from `p:txStyles` on a slide master. * Provides cascading defaults for title, body, and other text. */ declare interface PptxMasterTextStyles { /** Title text style (`p:titleStyle`). */ titleStyle?: PptxTextStyleLevels; /** Body text style (`p:bodyStyle`). */ bodyStyle?: PptxTextStyleLevels; /** Other text style (`p:otherStyle`). */ otherStyle?: PptxTextStyleLevels; } /** * `p14:bmkTgt` (Office 2010 `p14` extension, MS-OI29500): names the specific * media element and bookmark an `evt="onMediaBookmark"` condition fires for. * `bookmarkName` matches a `p14:bmk/@_name` on that media element's own * `p14:bmkLst` (see `MediaBookmark.label` in `core/types/elements.ts`). */ declare interface PptxMediaBookmarkTarget { /** `p14:bmkTgt/@_spid`: the media element's shape id. */ shapeId: string; /** `p14:bmkTgt/@_bmkName`: the bookmark's name. */ bookmarkName: string; } declare type PptxMediaReferenceKind = 'audioCd' | 'wavAudioFile' | 'audioFile' | 'videoFile' | 'quickTimeFile'; /** * Discriminator for embedded media element types. * * @example * ```ts * const kind: PptxMediaType = "video"; * // => "video" — one of: "video" | "audio" | "unknown" * ``` */ declare type PptxMediaType = 'video' | 'audio' | 'unknown'; /** Office 2021 comment author from the p188 Author part. */ declare interface PptxModernCommentAuthor { id: string; name: string; initials?: string; userId: string; providerId: string; rawXml?: XmlObject; } declare interface PptxModernCommentPart { path: string; relationshipId: string; /** Original p188:cmLst root, including unknown attributes and extensions. */ rawXml?: XmlObject; } /** * Write-protection hash data parsed from `p:modifyVerifier` in `presentation.xml`. * * When present, the presentation is marked as "read-only recommended" or * write-protected with a password hash. The hash parameters follow the * ECMA-376 Part 1, section 19.2.1.22 specification. * * @example * ```ts * const verifier: PptxModifyVerifier = { * algorithmName: "SHA-512", * hashData: "base64EncodedHash==", * saltData: "base64EncodedSalt==", * spinValue: 100000, * }; * // => satisfies PptxModifyVerifier * ``` */ declare interface PptxModifyVerifier { /** Hash algorithm name (e.g. "SHA-512", "SHA-1"). */ algorithmName?: string; /** Base64-encoded hash value. */ hashData?: string; /** Base64-encoded salt value. */ saltData?: string; /** Number of hash iterations (spin count). */ spinValue?: number; /** Legacy algorithm ID extension. */ algIdExt?: string; /** Legacy algorithm ID. */ cryptAlgorithmSid?: number; /** Cryptographic algorithm type (e.g. "typeAny"). */ cryptAlgorithmType?: string; /** Cryptographic provider name. */ cryptProvider?: string; /** Cryptographic provider type (e.g. "providerTypeRsaFull"). */ cryptProviderType?: string; /** Cryptographic algorithm class (e.g. "hash"). */ cryptAlgorithmClass?: string; } /** * Slide transition configuration. * * @example * ```ts * const transition: PptxSlideTransition = { * type: "fade", * durationMs: 700, * advanceOnClick: true, * advanceAfterMs: 5000, * }; * // => { type: "fade", durationMs: 700, advanceOnClick: true, advanceAfterMs: 5000 } * ``` */ /** * Morph granularity (``). * * - `byObject` - match whole shapes (PowerPoint's default) * - `byWord` - additionally morph text word by word * - `byChar` - additionally morph text character by character */ declare type PptxMorphOption = 'byObject' | 'byWord' | 'byChar'; /** * Parsed native animation record from `p:timing / p:tnLst`. * * Represents a single animation node in the OOXML timing tree, * including motion paths, scale transforms, and text build settings. * * @example * ```ts * const anim: PptxNativeAnimation = { * targetId: "shape_1", * presetClass: "entr", * presetId: 10, * trigger: "afterPrevious", * durationMs: 500, * }; * // => { targetId: "shape_1", presetClass: "entr", presetId: 10, trigger: "afterPrevious", durationMs: 500 } * ``` */ declare interface PptxNativeAnimation { /** Target element/shape ID. */ targetId?: string; /** Full timing target, including sound and ink target variants. */ target?: PptxAnimationTarget; /** Trigger type. */ trigger?: PptxAnimationTrigger; /** * Shape ID that triggers this animation: the clicked shape of an * interactive sequence, or the media element of an `onMediaBookmark` one. */ triggerShapeId?: string; /** Bookmark name an `onMediaBookmark` interactive sequence waits for. */ triggerBookmark?: string; /** Whether this effect belongs to an OOXML `interactiveSeq`. */ interactiveSequence?: boolean; /** Whether `p:endSync/p:rtn[@val="all"]` makes that sequence replayable. */ interactiveRestart?: boolean; /** Effect preset class (entr, exit, emph, path). */ presetClass?: 'entr' | 'exit' | 'emph' | 'path'; /** Effect preset sub-type identifier. */ presetId?: number; /** * Effect preset direction/variant code from `p:cTn/@presetSubtype` * (ECMA-376 CT_TLCommonTimeNodeData). For Fly In/Out this encodes the * edge/corner the object travels from as a bitmask (1=top, 2=right, * 4=bottom, 8=left; corners combine bits). Absent means the preset default. */ presetSubtype?: number; /** Duration in milliseconds. */ durationMs?: number; /** Delay in milliseconds. */ delayMs?: number; /** * Acceleration fraction in the range 0..1, parsed from `p:cTn/@accel` * (ST_PositiveFixedPercentage, stored as 1000ths of a percent). A non-zero * value means the effect eases in (starts slow). Absent means no easing-in. */ accel?: number; /** * Deceleration fraction in the range 0..1, parsed from `p:cTn/@decel`. * A non-zero value means the effect eases out (ends slow). Absent means no * easing-out. When both {@link accel} and {@link decel} are set, the effect * eases in and out. */ decel?: number; /** Trigger delay in milliseconds (for afterDelay). */ triggerDelayMs?: number; /** SVG path string for motion path animations (`p:animMotion/@path`). */ motionPath?: string; /** Motion origin: "layout" or "parent". */ motionOrigin?: string; /** * Whether the element auto-rotates to follow the motion path tangent. * Viewer-authoring-only hint: OOXML has no such flag (`p:animMotion/@rAng` * is a plain rotation angle that PowerPoint writes as "0" on every path), * so the parser never sets this. */ motionPathRotateAuto?: boolean; /** Path edit mode from `p:animMotion/@pathEditMode` (e.g. "relative", "fixed"). */ motionPathEditMode?: string; /** Comma-separated point-types string from `p:animMotion/@ptsTypes`. */ motionPtsTypes?: string; /** Authored path rotation in degrees from `p:animMotion/@rAng`. */ motionPathRotationAngle?: number; /** Motion-path rotation centre X in slide percentage units (`p:rCtr/@x`). */ motionPathRotationCenterX?: number; /** Motion-path rotation centre Y in slide percentage units (`p:rCtr/@y`). */ motionPathRotationCenterY?: number; /** Rotation angle in degrees for `p:animRot/@by` (converted from 60000ths). */ rotationBy?: number; /** Starting rotation angle in degrees for `p:animRot/@from` (converted from 60000ths). */ rotationFrom?: number; /** Ending rotation angle in degrees for `p:animRot/@to` (converted from 60000ths). */ rotationTo?: number; /** X scale factor (percentage / 100) for `p:animScale/p:by/@x`. */ scaleByX?: number; /** Y scale factor (percentage / 100) for `p:animScale/p:by/@y`. */ scaleByY?: number; /** Starting X scale factor for `p:animScale/p:from/@x`. */ scaleFromX?: number; /** Starting Y scale factor for `p:animScale/p:from/@y`. */ scaleFromY?: number; /** Ending X scale factor for `p:animScale/p:to/@x`. */ scaleToX?: number; /** Ending Y scale factor for `p:animScale/p:to/@y`. */ scaleToY?: number; /** Whether `p:animScale/@zoomContents` was set ("1"/"true"). */ scaleZoomContents?: boolean; /** Parsed `p:tav` keyframes from `p:tavLst` (CT_TLAnimVariantList). */ keyframes?: PptxAnimationKeyframe[]; /** * The attribute {@link keyframes} drives, from the SAME node's * `p:cBhvr/p:attrNameLst/p:attrName` (ECMA-376 S19.5.4). `p:tavLst` is * schema-generic: without this, playback could see a numeric ramp but not * know whether it targeted opacity, position, colour, or something with * no CSS mapping. Lowercased and trimmed; common values seen in the wild * (and written by this codebase's own animation writer) include * `"style.opacity"`, `"style.color"`, `"style.visibility"`, `"fillcolor"`, * `"stroke.color"`, `"r"` (rotation, only meaningful on `p:animRot`), and * `"ppt_x"` / `"ppt_y"` (position, normally driven via `p:animMotion` * instead). Absent when the behaviour carries no `p:attrNameLst`. */ attrName?: string; /** Every generic `p:anim` sibling composed by the authored effect. */ attributeAnimations?: PptxAttributeAnimation[]; /** Repeat count (e.g. `2`, `Infinity` for indefinite). */ repeatCount?: number; /** Whether the animation plays in reverse after completion. */ autoReverse?: boolean; /** Text build type from `p:bldP/@build` in `p:bldLst`. */ buildType?: PptxTextBuildType; /** Build level for multi-level lists from `p:bldP/@bldLvl`. */ buildLevel?: number; /** Group ID linking a `p:bldP` entry to its timing animation node. */ groupId?: string; /** * Sound relationship ID to play when animation triggers. Modern PowerPoint * (COM-verified against 2016) writes this as a `p:audio/p:cMediaNode` * sibling of the effect's own `p:childTnLst`, targeting `p:sndTgt` rather * than a shape; the legacy `p:stSnd` form (directly on `p:cTn`) is still * accepted on load for round-trip of older-authored decks, but PowerPoint * itself no longer writes it and does not recognise it back * (`Effect.EffectInformation.SoundEffect` reads empty against it). */ soundRId?: string; /** Resolved sound file path from relationship. */ soundPath?: string; /** * The embedded sound's `@_name` (from `p:snd`/`p:sndTgt`). For one of * PowerPoint's 19 built-in stock sounds this is the exact upper-case file * name PowerPoint itself writes (e.g. `"CHIMES.WAV"`); see * `pptx-viewer-shared`'s `effect-sound-catalogue.ts`, which matches this * value back to a gallery entry. Absent for a custom sound with no name, * or when unresolved. */ soundName?: string; /** Whether to stop any currently playing sound (`p:endSnd`). */ stopSound?: boolean; /** * End-state behaviour from `p:cTn/@fill` (ST_TLTimeNodeFillType, ECMA-376 * §19.5.27). `hold`/`freeze` mean the effect's final frame persists after * it finishes; `remove` (the default when absent) means the target reverts * to its pre-effect appearance. `transition` behaves like `hold` until the * next time node starts. Absent means the OOXML default (`remove`). */ fill?: 'remove' | 'freeze' | 'hold' | 'transition'; /** * Restart behaviour from `p:cTn/@restart` (ST_TLTimeNodeRestartType). * Absent means the OOXML default (`always`). */ restart?: 'always' | 'whenNotActive' | 'never'; /** * Repeat duration in milliseconds from `p:cTn/@repeatDur`. `Infinity` * represents the literal `"indefinite"` token. */ repeatDurMs?: number; /** * Playback speed multiplier from `p:cTn/@spd` (ST_Percentage, normalized * from OOXML's 1000ths-of-a-percent storage to a plain percentage, e.g. * `150` for 150% / double speed). Absent means normal (100%) speed. */ speedPct?: number; /** * Reverse the paragraph build order from `p:bldP/@rev` (TEXT build only). * Not to be confused with {@link PptxGraphicBuild}'s `reverse` field, which * carries the unrelated `p:bldDgm`/`@rev` DIAGRAM-build reverse flag. */ buildReverse?: boolean; /** * Auto-advance time in milliseconds from `p:bldP/@advAuto`. `Infinity` * represents the literal `"indefinite"` token. Absent means the build * step waits for a click. */ buildAdvAutoMs?: number; /** * Per-build-level timing templates from a TEXT `p:bldP/p:tmplLst` * (ECMA-376 §19.5.84 CT_TLTemplateList). Parsed for round-trip only; see * {@link PptxTimingTemplate} for why they are not consulted at playback. */ buildTemplates?: PptxTimingTemplate[]; /** * Whether the enclosing `p:seq` allows concurrent play with its siblings, * from `p:seq/@concurrent`. Parsed for round-trip; not yet honoured by * playback (see `docs/guide/limitations.md`). */ seqConcurrent?: boolean; /** Next-action behaviour from `p:seq/@nextAc` (ST_TLNextActionType). */ seqNextAction?: 'none' | 'seek'; /** Previous-action behaviour from `p:seq/@prevAc` (ST_TLPreviousActionType). */ seqPrevAction?: 'none' | 'skipTimeNode'; /** * Whether the enclosing click-level group (a direct `p:par` child of the * `mainSeq`) begins automatically when the slide appears, rather than waiting * for a click. * * PowerPoint gates a click step with a lone ``; * a group that also carries a time-node condition (`onBegin`/`onEnd` with a * `@tn`) or a finite delay starts on slide entry ("With/After Previous" as the * first effect on the slide). The flat animation list cannot express that on * its own, so the parse layer stamps it here. */ groupAutoStart?: boolean; /** * Index of the enclosing effect-wrapper `p:par` inside the click-level group. * * Effects that share a wrapper are OOXML siblings: they all start when that * wrapper starts, and each `p:cond/@delay` is measured from the wrapper's * start, NOT chained off the effect before it. Playback uses this to place * simultaneous effects at their true offsets instead of accumulating delays. */ parGroupIndex?: number; /** * Absolute start offset of the enclosing effect-wrapper from its click group. * * Structural `p:par` wrappers can carry their own start conditions. Keeping * this offset separate from the effect's delay prevents playback from * replacing an authored absolute start with a duration-based approximation. */ parGroupDelayMs?: number; /** Structured start conditions parsed from `p:stCondLst`. */ startConditions?: AnimationCondition[]; /** Structured end conditions parsed from `p:endCondLst`. */ endConditions?: AnimationCondition[]; /** Preserved raw `p:endCondLst` XML node for lossless round-trip. */ rawEndCondLst?: XmlObject; /** Color animation data from `p:animClr`. */ colorAnimation?: PptxColorAnimation; /** Text-level target: character range or paragraph range from `p:txEl`. */ textTarget?: PptxTextAnimationTarget; /** Whether this animation is inside an exclusive container (`p:excl`). */ exclusive?: boolean; /** * Identifies which `p:excl` container this animation belongs to, when * {@link exclusive} is set. ECMA-376 S19.5.24 CT_TLExclusiveTimeNode: at * most one direct child of an exclusive container may be active at a * time, so starting one child stops any other currently-playing child of * the SAME container. Two different `p:excl` containers on the same slide * are independent groups; this id (assigned per container encountered * during parsing, stable only within one parse's animation list) lets * playback tell them apart. Absent when {@link exclusive} is unset. */ exclGroupId?: number; /** Command type from `p:cmd` (@_type: call/evt/verb). */ commandType?: string; /** Command string from `p:cmd` (@_cmd). */ commandString?: string; /** Iteration configuration from `p:iterate`. */ iterate?: PptxAnimationIterate; /** * Discriminator for non-preset animation kinds. When `undefined`, the * entry represents the default shape-effect animation. The `'media'` * kind represents a `p:audio` / `p:video` timing node, captured here so * playback order in the timeline is preserved alongside other animations. */ kind?: PptxNativeAnimationKind; /** * For `kind === 'media'`, identifies whether this is an audio or video * media node so writers know which OOXML element to re-emit. */ mediaType?: 'audio' | 'video'; /** * SmartArt build attribute (`p:bldDgm/@bld`) when this animation is * associated with a SmartArt diagram build. Common values include * `whole`, `one`, `lvlOne`, `lvlAtOnce`. */ smartArtBuild?: string; /** * Graphic-frame build attribute (`p:bldGraphic/@bld`) when this animation * is associated with a generic graphic frame build (charts, tables, etc. * that aren't OLE charts). */ graphicBuild?: string; /** * OLE-embedded chart build attribute (`p:bldOleChart/@bld`) when this * animation stages an OLE chart graphic frame. Values follow * ST_TLOleChartBuildType: `allAtOnce`, `series`, `category`, `seriesEl`, * `categoryEl`. Lets a staged-reveal renderer build the chart by series / * category / element to match PowerPoint, rather than as one whole element. */ oleChartBuild?: string; /** Schema-accurate `p:bldGraphic/p:bldAsOne|p:bldSub` representation. */ graphicBuildProperties?: PptxGraphicBuild; /** * Opaque map of `p:cTn` attributes that don't have a typed home on this * interface but must round-trip through parse → save. Keys are stored * verbatim including the `@_` prefix used by the underlying XML parser * (e.g. `@_evtFilter`, `@_display`, `@_masterRel`, `@_nodePh`, * `@_endSync`, `@_progress`). The `subTnLst` child element is also * preserved here under the literal key `p:subTnLst`. The `afterEffect` * attribute is surfaced separately as a typed boolean ({@link afterEffect}) * because it changes write semantics for subsequent timing nodes. */ cTnAttributes?: Record; /** * Whether the OOXML `p:cTn/@afterEffect` flag is set. Indicates this node * runs after the parent effect's main body has completed; affects how * subsequent peer nodes are sequenced when serialised back to OOXML. */ afterEffect?: boolean; /** * "After animation" end-state behaviour: dim-to-colour, hide-after- * animation, or hide-on-next-click. Populated directly by the * native-timing parser (`native-animation-after-effect.ts`) when the * effect's `p:cTn/p:subTnLst` carries PowerPoint's genuine after-effect * shape, so a real-world deck's build shows up here even with no * `pptx:editorMeta`. `applyAfterAnimationFromEditorList` in * `pptx-viewer-shared` overrides this from the matching * {@link PptxElementAnimation.afterAnimation} entry when the editor's * per-element animation list has one (the model the animation panel * writes `afterAnimation` into), so an edit through our own UI always wins. */ afterAnimationAction?: PptxAfterAnimationAction; /** Dim-to color hex, present when {@link afterAnimationAction} is `dimToColor` AND the dim target is an already-resolved `a:srgbClr`. */ afterAnimationColor?: string; /** * The typed theme reference when a `dimToColor` target is an `a:schemeClr` * (e.g. `accent2`) instead of `a:srgbClr`: this parse layer has no theme to * resolve it to sRGB with (see {@link afterAnimationColor}'s doc), so a * playback consumer resolves this against the deck's theme colour map. * Mutually exclusive with {@link afterAnimationColor} being set. */ afterAnimationColorRef?: PptxThemeColorRef; /** * Parsed `p:animEffect` filter descriptor. `presetId`/`presetClass` remain * the primary effect selector (see `resolveEffect` in `pptx-viewer-shared`); * this is the fallback used when a preset table lookup misses (unmapped or * absent `presetId`), which happens for decks authored by tools other than * PowerPoint that only emit the SMIL-style filter string. */ effectFilter?: PptxAnimationEffectFilter; /** * This effect's own `p:cTn/@_id` (a raw OOXML time-node id, not a shape * id). Lets playback resolve a `p:cond/@tn` dependency (see * {@link AnimationCondition.targetTimeNodeId}) against the SPECIFIC node * it names rather than assuming it is always the positionally-previous * effect. Absent when the node carried no `@_id`. */ nodeId?: number; /** * Interpolation mode for this effect's PRIMARY `p:anim`-family behaviour * (the same node {@link keyframes}/{@link attrName} were read from), from * `@_calcmode` (ST_TLAnimateBehaviorCalcMode, ECMA-376 S19.5.2). See * {@link PptxAttributeAnimation.calcMode} for the per-component version. */ calcMode?: 'discrete' | 'lin' | 'fmla'; /** * `p:cBhvr/@_additive` (ST_TLBehaviorAdditiveType, ECMA-376 S19.5.4): * controls how this behaviour's value composites with sibling behaviours * driving the same attribute on the same target. `sum` accumulates * (e.g. a combined scale+rotate), `repl`/`base`/`none`/`mult` replace or * otherwise combine. Absent means the OOXML default (`base`). */ cBhvrAdditive?: 'base' | 'sum' | 'repl' | 'mult' | 'none'; /** * `p:cBhvr/@_accumulate` (ST_TLBehaviorAccumulateType): `always` means * each `p:cTn/@repeatCount` repeat starts from the PREVIOUS repeat's end * value (e.g. a 3x Spin totals 1080deg instead of replaying 0-360 three * times); `none` (the OOXML default) resets every repeat. */ cBhvrAccumulate?: 'none' | 'always'; /** * `p:cBhvr/@_xfrmType` (only meaningful on `p:animMotion`): `point` * (default) or `img`, a legacy compatibility hint. Round-tripped only. */ cBhvrXfrmType?: 'point' | 'img'; /** * `p:cBhvr/@_override` (ST_TLBehaviorOverrideType): `normal` (default) or * `childStyle`, a legacy compatibility hint. Round-tripped only. */ cBhvrOverride?: 'normal' | 'childStyle'; /** * `p:set` discrete attribute assignments composed alongside this effect * (ECMA-376 S19.5.79 CT_TLSetBehavior): an instantaneous (non-interpolated) * value change, as opposed to {@link attributeAnimations}'s `p:anim` * keyframe ramps. PowerPoint authors several font-style emphasis effects * this way (Bold Reveal, Underline, Bold Flash, Change Font Size), since * "on/off" or "size N" has nothing to interpolate. Not yet consulted by * shared playback (round-trip/typed-model only so far). */ setAnimations?: PptxSetAnimation[]; /** * Every behaviour child of this effect (`p:set`, `p:anim`, `p:animEffect`, * `p:animScale`, `p:animRot`, `p:animMotion`) with its own timing, as * authored. The single-valued fields above flatten a composed preset; * this keeps the whole tree so playback can follow what PowerPoint wrote * (see `animation-behavior-player` in `pptx-viewer-shared`). */ behaviors?: PptxAnimationBehavior[]; } /** * Native animation kind. The historic shape-targeted preset animations are * implicitly the default kind (`undefined`). Media animations (`p:audio`, * `p:video`) emit dedicated entries so playback order on the slide timeline * is preserved alongside other animations. */ declare type PptxNativeAnimationKind = 'media'; /** * Accessibility description/title from `p:cNvPr/@descr` / `@title` on a * plain shape, text box or connector (`p:sp` / `p:cxnSp`). The same pair of * attributes already round-trips for a graphic frame (see * {@link TablePptxElement.altText}) and, `descr` only, for a picture * ({@link PptxImageProperties.altText}); this mixin extends it to the three * element kinds whose PowerPoint Alt Text pane data was previously dropped * on load because neither field existed on the model. */ declare interface PptxNonVisualDescription { /** `p:cNvPr/@descr`. */ altText?: string; /** `p:cNvPr/@title`. */ title?: string; } /** * Normal view properties (`p:normalViewPr`). * Controls the splitter positions in normal (editing) view. */ declare interface PptxNormalViewProperties { /** Whether to show outline icons in the slide panel. */ showOutlineIcons?: boolean; /** Whether the outline/slide panel is snapped closed. */ snapVertSplitter?: boolean; /** Vertical splitter bar state: 'minimized' | 'maximized' | 'restored'. */ vertBarState?: string; /** Horizontal splitter bar state. */ horzBarState?: string; /** Whether to prefer single-slide view in the panel. */ preferSingleView?: boolean; /** Restored left region (slide panel width). */ restoredLeft?: PptxRestoredRegion; /** Restored top region (notes panel height). */ restoredTop?: PptxRestoredRegion; } /** * Parsed notes master from `ppt/notesMasters/notesMaster1.xml`. * * @example * ```ts * const notes: PptxNotesMaster = { * path: "ppt/notesMasters/notesMaster1.xml", * backgroundColor: "#FFFFFF", * placeholders: [{ type: "body" }, { type: "sldImg" }], * }; * // => satisfies PptxNotesMaster * ``` */ declare interface PptxNotesMaster { /** File path within the PPTX archive. */ path: string; /** Background colour of the notes master. */ backgroundColor?: string; /** Background image data URL. */ backgroundImage?: string; /** Crop, tiling and image effects authored on the background blip fill. */ backgroundImageProperties?: PptxImageProperties; /** Placeholder shapes found on the notes master. */ placeholders?: PptxPlaceholderFrame[]; /** Editable elements on the notes master (header, footer, date, page number, slide image, notes body). */ elements?: PptxElement[]; /** Header/footer flags from `` on the notes master (P-H3). */ headerFooter?: PptxHeaderFooterFlags; /** Colour map from `` (12 alias attributes). Applied at save time. */ clrMap?: Record; /** * Notes text defaults from `` (`CT_TextListStyle`, ECMA-376 * §19.3.1.34): the same `a:defPPr` + `a:lvl1pPr`..`a:lvl9pPr` shape as * {@link PptxMasterTextStyles}'s per-category styles, keyed 0-8 with the * default at `-1`. Governs the notes body placeholder's font size, indent * levels, and bullet style wherever a notes slide does not override them. * Parsed read-only for the render cascade; the save side preserves the * original `` XML verbatim rather than re-serialising this. */ notesStyle?: PptxTextStyleLevels; } /** * Photo album metadata from `p:photoAlbum` in `presentation.xml`. * * Stores settings for presentations created via Insert > Photo Album. * * @see ECMA-376 Part 1, §19.2.1.27 */ declare interface PptxPhotoAlbum { /** Whether photos are displayed in black-and-white. */ bw?: boolean; /** Whether captions are shown below each photo. */ showCaptions?: boolean; /** Photo album layout (e.g. "1pic", "2pic", "4pic", "fitToSlide"). */ layout?: string; /** Frame style applied to each photo (e.g. "frameStyle1"). */ frame?: string; /** * `p:photoAlbum/@isPhoto` (ECMA-376 S19.2.1.27, CT_PhotoAlbum): whether * the pictures placed by the album wizard are real photographs, as * opposed to clip art or other embedded images. `undefined` when the * source authored no explicit value (schema default `false`); this is a * purely declarative wizard-provenance flag, not something this library * gates any layout/frame behaviour on. */ isPhoto?: boolean; } /** * `a:cNvPicPr/@preferRelativeResize` (issue G13), a picture-only non-visual * property distinct from `a:picLocks`. */ declare interface PptxPictureNonVisualProperties { /** * `a:cNvPicPr/@preferRelativeResize` (ST_Boolean, defaults to `true` when * absent). Controls whether a picture's crop rectangle is reinterpreted * relative to the picture's ORIGINAL dimensions or its CURRENT * (already-resized) dimensions when it is resized again after being * cropped. Parsed and round-tripped for now; not yet wired into * resize-after-crop arithmetic (this app always uses current-size * semantics, which only diverges from `preferRelativeResize="0"` on a * second resize after a crop). */ preferRelativeResize?: boolean; } /** * A placeholder slot declared on a master or layout. * * The geometry fields are in CSS pixels (EMU / {@link EMU_PER_PX}) and are only * present when the shape carried an explicit `a:xfrm`. Placeholders that * inherit their frame from the master leave them undefined, so consumers that * draw placeholder outlines (the layout gallery) must skip those entries * rather than assume a zero-sized box at the origin. * * @example * ```ts * const frame: PptxPlaceholderFrame = { type: "body", idx: "1", x: 63, y: 130 }; * // => satisfies PptxPlaceholderFrame * ``` */ declare interface PptxPlaceholderFrame { /** `p:ph/@type`, lower-cased by the parser; defaults to `body` when omitted. */ type: string; /** `p:ph/@idx`, when present. */ idx?: string; /** Left offset in CSS pixels, when the shape declares `a:off`. */ x?: number; /** Top offset in CSS pixels, when the shape declares `a:off`. */ y?: number; /** Width in CSS pixels, when the shape declares `a:ext`. */ width?: number; /** Height in CSS pixels, when the shape declares `a:ext`. */ height?: number; } /** PresentationML `CT_PrintProperties` (`p:prnPr`). */ declare interface PptxPresentationPrintProperties { printWhat?: PptxPrintOutput | null; colorMode?: PptxPrintColorMode | null; hiddenSlides?: boolean | null; scaleToFitPaper?: boolean | null; frameSlides?: boolean | null; /** Original subtree retained for unknown attributes and `p:extLst`. */ rawXml?: XmlObject; } /** * Presentation-level properties parsed from `presentationPr.xml`. * * Controls slideshow behaviour, print settings, custom colours, and grid. * * @example * ```ts * const props: PptxPresentationProperties = { * showType: "presented", * loopContinuously: false, * advanceMode: "useTimings", * }; * // => satisfies PptxPresentationProperties * ``` */ declare interface PptxPresentationProperties { /** Show type: presented, browsed, kiosk. */ showType?: 'presented' | 'browsed' | 'kiosk'; /** Whether to loop the slideshow continuously. */ loopContinuously?: boolean; /** Whether to show without narration. */ showWithNarration?: boolean; /** Whether to show without animation. */ showWithAnimation?: boolean; /** Advance slides mode: manual click or use stored timings. */ advanceMode?: 'manual' | 'useTimings'; /** Show slides: 'all', a custom show id, or a from-to range. */ showSlidesMode?: 'all' | 'customShow' | 'range'; /** Custom show id to use when showSlidesMode is 'customShow'. */ showSlidesCustomShowId?: string; /** Slide range start (1-based) when showSlidesMode is 'range'. */ showSlidesFrom?: number; /** Slide range end (1-based) when showSlidesMode is 'range'. */ showSlidesTo?: number; /** Whether to show subtitles/captions during presentation mode. */ showSubtitles?: boolean; /** Typed `p:prnPr` settings. Set to null during save to remove the element. */ printProperties?: PptxPresentationPrintProperties | null; /** Most-recently-used colours from the presentation palette. */ mruColors?: string[]; /** * Pen colour for presentation mode annotations (from `p:showPr/p:penClr`). * `p:penClr` is a full `EG_ColorChoice` (P1-G2): a scheme/preset/system * swatch resolves to a hex string here just like a direct `a:srgbClr`. */ penColor?: string; /** * The resolved hex value {@link penColor} had at parse time, and the * original `p:penClr` colour-choice XML node, preserved so a save that * never touches the pen colour re-emits the original scheme/preset * reference verbatim instead of flattening it to a baked `a:srgbClr`. * Internal round-trip bookkeeping; not meant to be set by API callers. */ penColorOriginal?: string; /** @see penColorOriginal */ penColorXml?: XmlObject; /** Kiosk auto-restart interval in milliseconds (from `p:kiosk/@restart`). Only meaningful when showType is "kiosk". */ kioskRestartTime?: number; /** * `p:showPr/p:browse/@showScrollbar` (CT_ShowInfoBrowse §19.2.1.10 / * §19.3.1.43), the "Show scrollbar" checkbox in PowerPoint's Set Up Show * dialog. Only meaningful when `showType` is `"browsed"`; the schema * default is `true`. `undefined` means the source authored no explicit * value (or `showType` is not `"browsed"`). */ showScrollbar?: boolean; } declare type PptxPrintColorMode = 'bw' | 'gray' | 'clr'; declare type PptxPrintOutput = 'slides' | 'handouts1' | 'handouts2' | 'handouts3' | 'handouts4' | 'handouts6' | 'handouts9' | 'notes' | 'outline'; /** * Restored region dimensions for normal view splitter. * Represents `p:restoredLeft` or `p:restoredTop`. */ declare interface PptxRestoredRegion { /** Size as a percentage of the available space (thousandths of a percent). */ sz: number; /** Whether auto-adjust is enabled. */ autoAdjust?: boolean; } /** Output format for the save pipeline. */ declare type PptxSaveFormat = 'pptx' | 'ppsx' | 'pptm' | 'ppt'; /** * An ordered section in the presentation (from `p:sectionLst` / `p14:sectionLst`). * * Sections group consecutive slides under a named heading (visible * in the PowerPoint slide sorter). * * @example * ```ts * const section: PptxSection = { * id: "sec_1", * name: "Introduction", * slideIds: ["256", "257"], * }; * // => satisfies PptxSection * ``` */ declare interface PptxSection { /** Section unique identifier (GUID or synthetic). */ id: string; /** Human-readable section name. */ name: string; /** Ordered list of numeric slide IDs that belong to this section. */ slideIds: string[]; /** Whether the section is collapsed in the slide sorter (from p15:sectionPr). */ collapsed?: boolean; /** Section highlight color hex (from p15:sectionPr/@clr). */ color?: string; /** Original section subtree used to preserve unmodelled attributes and extensions. */ rawXml?: XmlObject; } /** * One `p:set` discrete (non-interpolated) attribute assignment composed * alongside an authored effect. See {@link PptxNativeAnimation.setAnimations}. * * @see ECMA-376 S19.5.79 CT_TLSetBehavior */ declare interface PptxSetAnimation { /** Lowercased target attribute from `p:cBhvr/p:attrNameLst/p:attrName`. */ attrName: string; /** Decoded value from `p:to` (same variant shape as a `p:tav/p:val`). */ value: string | boolean | number; /** Discriminant indicating which `p:to` child carried the value. */ valueType: 'str' | 'bool' | 'int' | 'flt' | 'clr'; /** Duration from this behaviour's nested `p:cTn/@dur`. */ durationMs?: number; /** Start offset from this behaviour's nested `p:stCondLst`. */ delayMs?: number; } /** `p:set`: a discrete value held from the behaviour's start. */ declare interface PptxSetBehavior extends BehaviorBase { kind: 'set'; value: string | number | boolean; } /** * Lock attributes from an element's non-visual properties node. * * When a flag is `true` the corresponding user interaction is disabled * in the editor (e.g. `noRotation` prevents free rotation of the shape). * * One bag covers every family, but the families are NOT interchangeable in * the file: `a:spLocks` (`CT_ShapeLocking`), `a:picLocks`, `a:cxnSpLocks`, * `a:grpSpLocks` (`CT_GroupLocking`) and `a:graphicFrameLocks` * (`CT_GraphicalObjectFrameLocking`) each declare their own attribute subset. * `runtime/shape-lock-containers` holds that table and is what decides which * of these fields may be written for a given element. * * @example * ```ts * const locks: PptxShapeLocks = { noMove: true, noResize: true }; * // => { noMove: true, noResize: true } satisfies PptxShapeLocks * ``` */ declare interface PptxShapeLocks { noGrouping?: boolean; noRotation?: boolean; noMove?: boolean; noResize?: boolean; noTextEdit?: boolean; noSelect?: boolean; noChangeAspect?: boolean; noEditPoints?: boolean; noAdjustHandles?: boolean; noChangeArrowheads?: boolean; noChangeShapeType?: boolean; /** * `a:graphicFrameLocks/@noDrilldown`: forbids selecting the individual * parts inside a graphic frame (a chart series, a SmartArt node). Declared * ONLY by `CT_GraphicalObjectFrameLocking`, so it is written for tables, * charts, SmartArt, OLE objects and graphic-frame media, and never onto * `a:spLocks` / `a:picLocks` / `a:cxnSpLocks` / `a:grpSpLocks`. */ noDrilldown?: boolean; /** * `a:picLocks/@noCrop`: forbids cropping the picture. Declared ONLY by * `CT_PictureLocking`, so it is written for pictures (and media authored as * a `p:pic`) and never onto the other lock elements. */ noCrop?: boolean; /** * Text-box flag from `p:cNvSpPr/@txBox`. Not a lock in the strict sense, * but it lives on the same non-visual-properties node as `a:spLocks`, so * it is captured here to round-trip through the model. When `true` the * shape is a plain text box (no fill/line by default). */ txBox?: boolean; } /** * Shape styling & geometry mixin — present on shapes, connectors, and images. * * @example * ```ts * const props: PptxShapeProperties = { * shapeType: "roundRect", * shapeStyle: { fillColor: "#0055AA", strokeWidth: 2 }, * shapeAdjustments: { adj: 16667 }, * }; * // => satisfies PptxShapeProperties * ``` */ declare interface PptxShapeProperties { shapeStyle?: ShapeStyle; /** Preset geometry name, e.g. "rect", "ellipse", "roundRect". */ shapeType?: string; /** Geometry adjustment values, e.g. `{ adj: 16667 }`. */ shapeAdjustments?: Record; /** Adjustment handles for interactive shape modification (yellow diamond handles). */ adjustmentHandles?: GeometryAdjustmentHandle[]; } /** * A single slide in a parsed PPTX presentation. * * Contains the element tree, background settings, notes, comments, * transition / animation data, and metadata like layout path and section. * * @example * ```ts * const slide: PptxSlide = { * id: "slide1", * rId: "rId2", * slideNumber: 1, * elements: [titleTextBox, subtitleTextBox], * backgroundColor: "#FFFFFF", * notes: "Remember to mention quarterly goals.", * }; * // => satisfies PptxSlide * ``` */ declare interface PptxSlide { id: string; rId: string; /** * `p:sldIdLst/p:sldId/@id` (ST_SlideId, 256..2147483647): the numeric key * that sections (`p14:sldIdLst/p14:sldId/@id`) and section/summary zooms * name slides by. * * It lives in `presentation.xml`, NOT in the slide part, so it cannot be * recovered from `rawXml`. Without it on the model, code that writes a * section's membership has nothing correct to write and falls back to the * slide NUMBER, which is 1-based and therefore never matches a real deck's * ids: the section reloads with no slides in it. */ slideId?: string; sourceSlideId?: string; /** * The slide name, `p:cSld/@name`: loaded from the part, written back on * save (an empty string clears the attribute), and settable via * `SlideBuilder.setName`. */ name?: string; layoutPath?: string; layoutName?: string; slideNumber: number; hidden?: boolean; sectionName?: string; sectionId?: string; elements: PptxElement[]; backgroundColor?: string; backgroundImage?: string; /** Crop, tiling and image effects authored on the background blip fill. */ backgroundImageProperties?: PptxImageProperties; backgroundGradient?: string; /** * Pattern fill on the slide background (`` inside ``). * * When present, renderers should draw a real two-colour pattern using * the named DrawingML preset (e.g. `"ltDnDiag"`, `"pct50"`). The flat * `backgroundColor` field is left set to the foreground colour for * fallback rendering paths that don't understand patterns. * * ECMA-376 §20.1.8.47. */ backgroundPattern?: PptxSlideBackgroundPattern; /** * ``: boolean flag instructing the renderer to * anchor the background gradient on the title placeholder as a * rectangular path gradient (COM-measured against real PowerPoint; * it does NOT recolour toward the title's text colour, despite the * attribute's name). Parsed and round-tripped here on the core model; * the actual visual effect is applied by `pptx-viewer-shared`'s * `getSlideBackgroundStyle` (see `render/background-shade-to-title.ts`), * consumed by all five bindings, not by core itself. Legacy PowerPoint * 97-2003 hint, not observed in any real-world corpus file this project * has collected and not settable from any modern PowerPoint UI; see * `docs/guide/limitations.md`. * * ECMA-376 §19.3.1.2 (CT_BackgroundProperties). */ backgroundShadeToTitle?: boolean; transition?: PptxSlideTransition; animations?: PptxElementAnimation[]; /** * Read-only anchors for the deck's own (non-editor-authored) effect * groups, merged with `animations` by the authoring UI so drag-to-reorder * can target any position in the full sequence. See * {@link PptxAnimationTimelineAnchor}. */ animationTimelineAnchors?: PptxAnimationTimelineAnchor[]; /** Native OOXML animation data parsed from `p:timing`. */ nativeAnimations?: PptxNativeAnimation[]; /** Preserved raw `p:timing` XML for lossless round-trip of native animations. */ rawTiming?: XmlObject; notes?: string; /** Rich text segments for the slide notes (preserves formatting). */ notesSegments?: TextSegment[]; /** * Parsed shapes from the notes slide's `/` so the full * notes-page shape tree can be inspected and mutated, not just the body * placeholder text. When undefined, the existing notes XML is left * untouched on save and only `notes` / `notesSegments` are written. */ notesShapes?: PptxElement[]; /** * Per-notes-slide colour map override parsed from `/`. * Captured for lossless round-trip of the notes-slide's colour scheme. */ notesClrMapOverride?: Record; /** Optional `` value of the notes slide, for round-trip. */ notesCSldName?: string; comments?: PptxComment[]; /** Source package metadata for an Office 2021 p188 comment part. */ modernCommentPart?: PptxModernCommentPart; warnings?: PptxCompatibilityWarning[]; rawXml?: XmlObject; /** Per-slide colour map override parsed from `p:clrMapOvr`. */ clrMapOverride?: Record; /** Whether background animations should play (`p:bg/@showAnimation`). */ backgroundShowAnimation?: boolean; /** Whether master slide shapes should be shown on this slide (`p:sld/@showMasterSp`). */ showMasterShapes?: boolean; /** * Whether inherited master placeholder animations should replay on this * slide (`p:sld/@showMasterPhAnim`). Distinct from {@link showMasterShapes}: * this governs animation timing, not shape visibility. Mirrors * `p:sldLayout/@showMasterPhAnim`, ECMA-376 §19.3.1.38. */ showMasterPhAnim?: boolean; /** Drawing guides parsed from slide extension list. */ guides?: PptxDrawingGuide[]; /** When explicitly `false`, the slide is unmodified and save can skip re-serialization. */ isDirty?: boolean; /** Customer data references from `p:custDataLst` on this slide. */ customerData?: PptxCustomerData[]; /** ActiveX control references from `p:controls` on this slide. */ activeXControls?: PptxActiveXControl[]; /** * Shapes parsed from a referenced legacy VML drawing part * (`ppt/drawings/vmlDrawing*.vml`, linked via a `legacyDrawing` * relationship). These are read-only render hints: the VML part itself is * preserved verbatim on save, so this field is not re-serialized. */ legacyVmlElements?: PptxElement[]; /** Per-slide header/footer flags from `` (P-H3). */ headerFooterFlags?: PptxHeaderFooterFlags; /** Server-backed slide synchronization metadata stored in a related OPC part. */ slideSynchronization?: PptxSlideSyncProperties; } /** * Pattern fill on a slide background. * * Mirrors the `` choice inside ``. Renderers should * draw a 2-colour preset pattern (e.g. `dkDnDiag`, `pct50`). * * ECMA-376 §20.1.8.47. * * @example * ```ts * const pattern: PptxSlideBackgroundPattern = { * preset: "ltDnDiag", * fgColor: "#4472C4", * bgColor: "#FFFFFF", * }; * // => satisfies PptxSlideBackgroundPattern * ``` */ declare interface PptxSlideBackgroundPattern { /** DrawingML preset pattern token (`@_prst`). */ preset: string; /** Foreground colour resolved to `#RRGGBB`. */ fgColor?: string; /** Background colour resolved to `#RRGGBB`. */ bgColor?: string; } /** * Fluent builder scoped to a single slide. * Provides navigation to the slide's elements and notes. */ declare class PptxSlideBuilder { /** The slide being operated on. */ private readonly slideValue; /** Reference back to the root builder for chaining. */ private readonly rootBuilder; /** * @param slideValue - The slide data. * @param rootBuilder - The parent builder. */ constructor(slideValue: PptxSlide, rootBuilder: PptxXmlBuilder); /** Navigate to the slide's notes builder (getter). */ get Notes(): PptxSlideNotesBuilder; /** Navigate to the slide's notes builder. */ notes(): PptxSlideNotesBuilder; /** Navigate to the slide's elements builder. */ elements(): PptxSlideElementsBuilder; /** Return the underlying slide data. */ project(): PptxSlide; /** Pascal-case alias for {@link project}. */ Project(): PptxSlide; /** Navigate back to the root builder. */ done(): PptxXmlBuilder; /** Pascal-case alias for {@link done}. */ Done(): PptxXmlBuilder; } /** * Fluent builder for manipulating the elements array of a single slide. * Supports adding, removing, and updating elements by ID. */ declare class PptxSlideElementsBuilder { private readonly slideValue; private readonly slideBuilder; /** * @param slideValue - The slide whose elements are being modified. * @param slideBuilder - The parent slide builder for chaining. */ constructor(slideValue: PptxSlide, slideBuilder: PptxSlideBuilder); /** * Append an element to the slide's element list. * @param element - The element to add. * @returns This builder for chaining. */ add(element: PptxElement): this; /** * Remove an element from the slide by its ID. * @param elementId - The ID of the element to remove. * @returns This builder for chaining. */ removeById(elementId: string): this; /** * Update an element in-place by ID using a transform function. * @param elementId - The ID of the element to update. * @param updater - A function that receives the current element and returns the replacement. * @returns This builder for chaining. */ updateById(elementId: string, updater: (current: PptxElement) => PptxElement): this; /** Return the current elements array. */ project(): PptxElement[]; /** Navigate back to the slide builder. */ done(): PptxSlideBuilder; } /** * A slide layout associated with a slide master. * * @example * ```ts * const layout: PptxSlideLayout = { * path: "ppt/slideLayouts/slideLayout2.xml", * name: "Title and Content", * }; * // => satisfies PptxSlideLayout * ``` */ declare interface PptxSlideLayout { /** File path within the PPTX archive. */ path: string; /** Human-readable layout name. */ name?: string; /** Background colour of the layout. */ backgroundColor?: string; /** Background image data URL for the layout. */ backgroundImage?: string; /** Crop, tiling and image effects authored on the background blip fill. */ backgroundImageProperties?: PptxImageProperties; /** Parsed element shapes on the layout. */ elements?: PptxElement[]; /** Placeholder shapes on the layout. */ placeholders?: PptxPlaceholderFrame[]; /** Matching name attribute for layout identification (`@matchingName`). */ matchingName?: string; /** Whether the layout is marked as preserved (prevent deletion, `@preserve`). */ preserve?: boolean; /** Whether master placeholder animations should play (`@showMasterPhAnim`). */ showMasterPhAnim?: boolean; /** Whether this layout is user-drawn (`@userDrawn`). */ userDrawn?: boolean; /** Colour map override from `p:clrMapOvr`. */ clrMapOverride?: Record; /** Header/footer flags from `` on this layout (P-H3). */ headerFooter?: PptxHeaderFooterFlags; } /** * Structured slide master data. * * @example * ```ts * const master: PptxSlideMaster = { * path: "ppt/slideMasters/slideMaster1.xml", * name: "Office Theme", * backgroundColor: "#FFFFFF", * themePath: "ppt/theme/theme1.xml", * }; * // => satisfies PptxSlideMaster * ``` */ declare interface PptxSlideMaster { /** File path within the PPTX archive. */ path: string; /** Human-readable name if available. */ name?: string; /** Background colour of the slide master. */ backgroundColor?: string; /** Background image data URL for the slide master. */ backgroundImage?: string; /** Crop, tiling and image effects authored on the background blip fill. */ backgroundImageProperties?: PptxImageProperties; /** Theme file path this master references. */ themePath?: string; /** Layout paths associated with this master. */ layoutPaths?: string[]; /** Placeholder shapes on the master. */ placeholders?: PptxPlaceholderFrame[]; /** Parsed element shapes on the master slide (for master view rendering). */ elements?: PptxElement[]; /** Parsed slide layout objects associated with this master. */ layouts?: PptxSlideLayout[]; /** Text styles from `p:txStyles` — title, body, and other text defaults. */ txStyles?: PptxMasterTextStyles; /** Header/footer flags from `` on this master (P-H3). */ headerFooter?: PptxHeaderFooterFlags; /** * Colour map from `` (12 alias attributes: bg1/tx1/bg2/tx2, * accent1-6, hlink, folHlink). Applied at save time when present. */ clrMap?: Record; /** * Whether the master is marked as preserved (prevent auto-deletion, * `@preserve`). Mirrors {@link PptxSlideLayout.preserve}: PowerPoint * silently drops an unused master unless this is set. * * ECMA-376 §19.3.1.38 (CT_SlideMaster). */ preserve?: boolean; } /** * Fluent builder for manipulating speaker notes on a single slide. * Supports adding, setting, clearing, and retrieving notes text. */ declare class PptxSlideNotesBuilder { private readonly slideValue; private readonly slideBuilder; /** * @param slideValue - The slide whose notes are being modified. * @param slideBuilder - The parent slide builder for chaining. */ constructor(slideValue: PptxSlide, slideBuilder: PptxSlideBuilder); /** * Append text to existing notes (separated by newline). * @param text - The text to append. * @returns This builder for chaining. */ add(text: string): this; /** Pascal-case alias for {@link add}. */ Add(text: string): this; /** * Replace all notes with the given text. * @param text - The replacement notes text. Empty string clears notes. * @returns This builder for chaining. */ set(text: string): this; /** Pascal-case alias for {@link set}. */ Set(text: string): this; /** Remove all notes from the slide. */ clear(): this; /** Pascal-case alias for {@link clear}. */ Clear(): this; /** Return the current notes text, or `undefined` if none. */ get(): string | undefined; /** Pascal-case alias for {@link get}. */ Get(): string | undefined; /** Navigate back to the slide builder. */ done(): PptxSlideBuilder; /** Pascal-case alias for {@link done}. */ Done(): PptxSlideBuilder; /** * Synchronize the `notesSegments` array from the plain-text notes string. * Splits text on newlines and creates corresponding {@link TextSegment} entries * with paragraph break markers between lines. */ private syncSegmentsFromNotes; } /** * Slide dimensions from `p:sldSz` (CT_SlideSize, ECMA-376 §19.2.1.39). * * @example * ```ts * const size: PptxSlideSize = { widthEmu: 9144000, heightEmu: 6858000, type: 'screen4x3' }; * // => satisfies PptxSlideSize * ``` */ declare interface PptxSlideSize { /** `@cx` in EMU. Omitted or non-positive values leave the loaded width alone. */ widthEmu?: number; /** `@cy` in EMU. Omitted or non-positive values leave the loaded height alone. */ heightEmu?: number; /** * `@type` (ST_SlideSizeType). The schema default is `custom`, which is * why PowerPoint omits the attribute for a non-preset size. */ type?: string; } /** Metadata from a `p:sldSyncPr` slide synchronization data part. */ declare interface PptxSlideSyncProperties { serverSlideId: string; serverSlideModifiedTime: string; clientInsertedTime: string; extensionList?: XmlObject; rawXml?: XmlObject; partPath?: string; relationshipId?: string; } declare interface PptxSlideTransition { type: PptxTransitionType; /** Schema-defined transition speed. Defaults to `fast` when omitted. */ speed?: PptxTransitionSpeed; durationMs?: number; direction?: string; advanceOnClick?: boolean; advanceAfterMs?: number; /** Number of spokes for wheel transition (1-8). */ spokes?: number; /** Pattern type for shred transition. */ pattern?: string; /** * Through-black flag (OOXML `@_thruBlk`). COM-verified to actually apply to * `cut` and `fade` (see {@link TRANSITION_THRUBLK_TYPES}); parsed generically * off any standard transition child so an unexpected authored value still * round-trips. */ thruBlk?: boolean; /** Split orientation (horz/vert) parsed from `@_orient`. */ orient?: PptxSplitOrientation; /** * Morph granularity from ``: how finely PowerPoint * matches content between the two slides. Only meaningful when * {@link type} is `morph`; defaults to `byObject` when the attribute is * absent, matching PowerPoint's own default. */ morphOption?: PptxMorphOption; /** Relationship ID of transition sound from `p:sndAc/p:stSnd/@r:embed` when present. */ soundRId?: string; /** Embedded WAV display name from `p:stSnd/p:snd/@name`. */ soundName?: string; /** Whether the transition sound repeats until another sound starts. */ soundLoop?: boolean; /** Resolved transition sound media path within the package. */ soundPath?: string; /** Human-readable sound file name (extracted from soundPath, or set by the * UI when a new file is picked, before it has a soundPath at all). */ soundFileName?: string; /** * A newly-picked local sound file awaiting embedding, as a `data:` URL. * Set by the transitions ribbon's Sound picker (`applyTransitionSoundFile` * in `pptx-viewer-shared`) when the user chooses a file that is not yet * part of the package; mirrors `imageData`/`mediaData` on picture and media * elements. The save pipeline (`embedTransitionSound`) writes the bytes to * `ppt/media/`, mints a relationship, sets `soundRId`/`soundPath`, and * clears this field so a later save does not re-embed the same bytes. */ soundData?: string; /** * When true, the transition stops the currently-playing sound (OOXML `p:sndAc/p:endSnd`). * Mutually exclusive with `soundRId`/`soundPath` (which use `p:stSnd`). */ stopSound?: boolean; /** Preserved sound-action XML node from `p:sndAc` for lossless round-trip. */ rawSoundAction?: XmlObject; /** Preserved extension-list XML node from `p:extLst` within the transition for lossless round-trip. */ rawExtLst?: XmlObject; /** Original transition node, retained to preserve unknown attributes and children. */ rawTransition?: XmlObject; } declare interface PptxSmartArtAlgorithmParameter { type: string; value?: string; } declare interface PptxSmartArtChoose { name?: string; when: PptxSmartArtWhen[]; otherwise?: { name?: string; rawXml?: XmlObject; } | null; rawXml?: XmlObject; } /** * Background / outline extracted from `dgm:bg` and `dgm:whole`. * * @example * ```ts * const chrome: PptxSmartArtChrome = { * backgroundColor: "#F0F0F0", * outlineColor: "#333333", * outlineWidth: 1, * }; * // => satisfies PptxSmartArtChrome * ``` */ declare interface PptxSmartArtChrome { /** * Background fill colour (hex). When the real `dgm:bg` fill is a gradient * or pattern (see {@link PptxSmartArtChrome.backgroundFillXml}), this is an * APPROXIMATION (the gradient's first stop, or the pattern's foreground * colour) for a consumer that only wants one display colour, not the full fill. */ backgroundColor?: string; /** * Raw `dgm:bg` fill XML, present only when the background is a gradient or * pattern fill (a solid fill is fully captured by {@link PptxSmartArtChrome.backgroundColor} * alone). Round-trip only: `smartart-save-chrome.ts` re-emits this verbatim * instead of flattening the fill to a solid colour on save. */ backgroundFillXml?: PptxSmartArtRawBackgroundFill; /** Outline stroke colour (hex). */ outlineColor?: string; /** Outline stroke width in points. */ outlineWidth?: number; } declare type PptxSmartArtColorApplicationMethod = 'span' | 'cycle' | 'repeat'; /** CT_Colors application metadata. Color-choice children remain preserved XML. */ declare interface PptxSmartArtColorListMetadata { method?: PptxSmartArtColorApplicationMethod; hueDirection?: PptxSmartArtHueDirection; } /** CT_CTStyleLabel metadata from a color-transform definition. */ declare interface PptxSmartArtColorStyleLabel { name: string; fill?: PptxSmartArtColorListMetadata; line?: PptxSmartArtColorListMetadata; effect?: PptxSmartArtColorListMetadata; textLine?: PptxSmartArtColorListMetadata; textFill?: PptxSmartArtColorListMetadata; textEffect?: PptxSmartArtColorListMetadata; } /** Typed CT_ColorTransform metadata and the resolved legacy color palette. */ declare interface PptxSmartArtColorTransform extends PptxSmartArtDefinitionMetadata { /** Legacy resolved display name. */ name?: string; /** Ordered resolved fill colors for rendering. */ fillColors: string[]; /** Ordered resolved line colors for rendering. */ lineColors: string[]; /** Ordered resolved text-fill colors (primary styleLbl `txFillClrLst`). */ textFillColors?: string[]; /** Ordered resolved text-line colors (primary styleLbl `txLinClrLst`). */ textLineColors?: string[]; /** Ordered resolved effect colors (primary styleLbl `effectClrLst`). */ effectColors?: string[]; /** Ordered resolved text-effect colors (primary styleLbl `txEffectClrLst`). */ textEffectColors?: string[]; /** Fill-list span/cycle + hue-direction interpolation of the primary styleLbl. */ fillInterpolation?: PptxSmartArtColorListMetadata; /** Line-list span/cycle + hue-direction interpolation of the primary styleLbl. */ lineInterpolation?: PptxSmartArtColorListMetadata; /** Ordered CT_CTStyleLabel metadata. */ labels?: PptxSmartArtColorStyleLabel[]; /** * Every `styleLbl`'s own resolved fill/line colour list, keyed by name * (e.g. `node1`, `asst0`, `bgShp`, `revTx`). Unlike {@link fillColors} / * {@link lineColors} (which collapse to ONE "primary" node-role list), * this keeps every role so a node can be coloured from its OWN role's * palette (see `PptxSmartArtNode.styleRole` and `applySmartArtRoleColors`) * instead of a generic cycled colour. */ roleColors?: Record; } /** * A connection between two SmartArt data-model nodes. * * @example * ```ts * const conn: PptxSmartArtConnection = { * sourceId: "1", * destId: "2", * type: "parOf", * }; * // => satisfies PptxSmartArtConnection * ``` */ declare interface PptxSmartArtConnection { /** Stable CT_Cxn model identifier. Required when serialized. */ modelId?: string | null; /** Model ID of the source node. */ sourceId: string; /** Model ID of the destination node. */ destId: string; /** Connection type (e.g. "parOf", "presOf", "sibTrans"). */ type?: string; /** Source index for ordering sibling connections. */ srcOrd?: number; /** Destination index for ordering. */ destOrd?: number; /** Model ID of the parent transition point associated with this edge. */ parentTransitionId?: string | null; /** Model ID of the sibling transition point associated with this edge. */ siblingTransitionId?: string | null; /** Layout presentation identifier used by presentation connections. */ presentationId?: string | null; /** * Connector text, read from the linked `parTrans`/`sibTrans` transition * point's `dgm:t` (via {@link parentTransitionId} / {@link siblingTransitionId}). * PowerPoint's own diagram editor lets a user type text directly onto an * org-chart relationship connector; `undefined` when the transition point * carries no text. Written back to that point on save. */ label?: string; } /** Editable DiagramML CT_Constraint. */ declare interface PptxSmartArtConstraint extends PptxSmartArtConstraintTarget { type: string; referenceType?: string; referenceFor?: PptxSmartArtConstraintRelationship; referenceForName?: string; referencePointType?: PptxSmartArtConstraintPointType; operator?: PptxSmartArtConstraintOperator; value?: number; factor?: number; /** Original constraint retained for foreign attributes and extension content. */ rawXml?: XmlObject; } declare type PptxSmartArtConstraintOperator = 'none' | 'equ' | 'gte' | 'lte'; declare type PptxSmartArtConstraintPointType = 'all' | 'doc' | 'node' | 'norm' | 'nonNorm' | 'asst' | 'nonAsst' | 'parTrans' | 'pres' | 'sibTrans'; declare type PptxSmartArtConstraintRelationship = 'self' | 'ch' | 'des'; declare interface PptxSmartArtConstraintTarget { for?: PptxSmartArtConstraintRelationship; forName?: string; pointType?: PptxSmartArtConstraintPointType; } /** * Complete parsed SmartArt data for a {@link SmartArtPptxElement}. * * @example * ```ts * const data: PptxSmartArtData = { * resolvedLayoutType: "hierarchy", * layout: "hierarchy", * colorScheme: "colorful1", * style: "moderate", * nodes: [ * { id: "1", text: "CEO", children: [ * { id: "2", text: "VP Marketing", parentId: "1" }, * ]}, * ], * }; * // => satisfies PptxSmartArtData * ``` */ declare interface PptxSmartArtData { layoutType?: string; resolvedLayoutType?: SmartArtLayoutType; /** Named layout preset (used when creating new SmartArt). */ layout?: SmartArtLayout; /** Colour scheme for the SmartArt graphic. */ colorScheme?: SmartArtColorScheme; /** Visual style intensity. */ style?: SmartArtStyle; nodes: PptxSmartArtNode[]; /** Connections between data-model nodes. */ connections?: PptxSmartArtConnection[]; /** Pre-computed shapes from `ppt/diagrams/drawing*.xml`. */ drawingShapes?: PptxSmartArtDrawingShape[]; /** Background and outline chrome from `dgm:bg` / `dgm:whole`. */ chrome?: PptxSmartArtChrome; /** Colour transform from `ppt/diagrams/colors*.xml`. */ colorTransform?: PptxSmartArtColorTransform; /** Quick style from `ppt/diagrams/quickStyles*.xml`. */ quickStyle?: PptxSmartArtQuickStyle; /** Editable metadata from the related DiagramML layout definition. */ layoutDefinition?: PptxSmartArtLayoutDefinition; /** * Presentation layout variables (direction, hierarchy branch, org-chart, * child limits, bullets) from `dgm:presLayoutVars` / layout `dgm:varLst`. * Consulted by the fallback layout engine for direction/org-chart hints. */ presLayoutVars?: PptxSmartArtPresLayoutVars; /** * The deck's own theme minor-Latin font (`a:fontScheme/a:minorFont/a:latin/ * @typeface`): what SmartArt text actually renders in when no per-run * `a:latin` override is present (the common case - see * `smartart-layout-item-font-size.ts`'s font-fit, the one consumer). * Undefined when the theme carries no font scheme at all. */ themeMinorFont?: string; /** Relationship ID for the diagram data part (for round-trip save). */ dataRelId?: string; /** Relationship ID for the diagram layout part. */ layoutRelId?: string; /** Relationship ID for the drawing part. */ drawingRelId?: string; /** Relationship ID for the colours part. */ colorsRelId?: string; /** Relationship ID for the quick-styles part. */ styleRelId?: string; /** Internal save hint: the layout definition changed in the editor. */ layoutDirty?: boolean; /** Internal save hint: typed layout-definition metadata changed. */ layoutDefinitionDirty?: boolean; /** Internal save hint: quick-style definition metadata changed. */ quickStyleDirty?: boolean; /** Internal save hint: color-transform definition metadata changed. */ colorTransformDirty?: boolean; /** Internal save hint: cached drawing geometry or text changed in the editor. */ drawingDirty?: boolean; } declare interface PptxSmartArtDefinitionCategory { type: string; priority: number; } declare interface PptxSmartArtDefinitionMetadata { uniqueId?: string; minimumVersion?: string; titles?: PptxSmartArtDefinitionText[]; descriptions?: PptxSmartArtDefinitionText[]; categories?: PptxSmartArtDefinitionCategory[]; } declare interface PptxSmartArtDefinitionText { value: string; language?: string; } /** * A pre-computed shape from `ppt/diagrams/drawing*.xml`. * * @example * ```ts * const shape: PptxSmartArtDrawingShape = { * id: "s1", * shapeType: "roundRect", * x: 100, y: 50, width: 200, height: 80, * fillColor: "#4F81BD", * text: "CEO", * }; * // => satisfies PptxSmartArtDrawingShape * ``` */ declare interface PptxSmartArtDrawingShape extends PptxCustomPathProperties { /** Shape ID within the drawing. */ id: string; /** Preset geometry type (e.g. "roundRect", "ellipse"). */ shapeType?: string; /** Position and size in EMU-based pixels. */ x: number; y: number; width: number; height: number; /** Rotation in degrees. */ rotation?: number; /** Horizontal/vertical mirrors declared on the cached drawing transform. */ flipHorizontal?: boolean; flipVertical?: boolean; /** Skew along the X axis in degrees. */ skewX?: number; /** Skew along the Y axis in degrees. */ skewY?: number; /** Preset-geometry adjustment values from `a:prstGeom/a:avLst`. */ shapeAdjustments?: Record; /** * The cached shape declares `a:noFill`. Renderers must leave it unpainted * rather than substituting a palette colour, because these shapes usually sit * on top of a painted shape whose fill has to stay visible. */ fillNone?: boolean; /** Solid fill colour (hex). */ fillColor?: string; /** * Opacity (0..1) of the solid fill, from the colour's `a:alpha` (Basic Venn * paints its circles at 50% so overlaps blend). Absent when opaque. */ fillOpacity?: number; /** * Gradient fill stops when the cached shape uses `a:gradFill`. Positions are * 0..100 (percent). Renderers emit an SVG/CSS gradient instead of a flat box. */ fillGradientStops?: Array<{ color: string; position: number; opacity?: number; }>; /** Gradient geometry type (`linear` for `a:lin`, `radial` for `a:path`). */ fillGradientType?: 'linear' | 'radial'; /** Linear gradient angle in degrees (0..360). */ fillGradientAngle?: number; /** Pattern fill preset name from `a:pattFill/@prst` (e.g. "pct50", "cross"). */ fillPatternPreset?: string; /** Pattern fill foreground colour (hex) from `a:pattFill/a:fgClr`. */ fillPatternForegroundColor?: string; /** Pattern fill background colour (hex) from `a:pattFill/a:bgClr`. */ fillPatternBackgroundColor?: string; /** * Relationship id of a picture (blip) fill's embedded image, from * `a:blipFill/a:blip/@r:embed`. The image bytes are resolved separately; see * {@link fillImageUrl}. */ fillBlipEmbedId?: string; /** * Resolved data-URI/URL for a picture (blip) fill, when the embedded image * part could be resolved. Absent when only {@link fillBlipEmbedId} is known. */ fillImageUrl?: string; /** Whether the cached shape carries an outer-shadow effect (`a:effectLst`). */ hasShadow?: boolean; /** Resolved outer-shadow colour (hex), when present. */ shadowColor?: string; /** Stroke colour (hex). */ strokeColor?: string; /** Stroke width in points. */ strokeWidth?: number; /** Text content of the shape. */ text?: string; /** Standard rich-text segments projected from the associated SmartArt node. */ textSegments?: TextSegment[]; /** Font size in CSS pixels. */ fontSize?: number; /** Font colour (hex). */ fontColor?: string; /** Authored font family from the first styled run. */ fontFamily?: string; /** Authored font weight (400 or 700). */ fontWeight?: number; /** Authored font style. */ fontStyle?: 'normal' | 'italic'; /** Absolute line height in CSS pixels from `a:spcPts`. */ lineHeight?: number; /** Relative line height from `a:spcPct`. */ lineHeightRatio?: number; /** Absolute spacing after a paragraph in CSS pixels. */ lineSpacingAfter?: number; /** Relative spacing after a paragraph. */ lineSpacingAfterRatio?: number; /** Text-body insets in CSS pixels. */ textInsetLeft?: number; textInsetTop?: number; textInsetRight?: number; textInsetBottom?: number; /** DiagramML text vertical anchor (`t`, `ctr`, or `b`). */ textVerticalAnchor?: string; /** Independent DiagramML text-frame geometry from `dsp:txXfrm`. */ textFrameX?: number; textFrameY?: number; textFrameWidth?: number; textFrameHeight?: number; /** * 3D scene (camera/light rig/backdrop) from `dsp:spPr/a:scene3d`, when this * cached shape carries its own per-shape camera. Bevel quick styles * (Polished, Inset, Cartoon, Powder) cache one per shape (always * `orthographicFront`, so the 2D layout stays undistorted). Scene quick * styles (Brick, Flat, Metallic, Sunset, Bird's Eye) instead put ONE camera * on the whole diagram (see `PptxSmartArtQuickStyle.scene3d`) and leave this * undefined on every shape. */ scene3d?: Pptx3DScene; /** * 3D extrusion/bevel/contour/material from `dsp:spPr/a:sp3d`. PowerPoint * caches this fully resolved (from the quick style's per-label `dgm:sp3d`) * on every shape for every non-flat quick style, bevel or scene alike. */ shape3d?: Pptx3DShape; /** * Text-body 3D extrusion/bevel from `dsp:txBody/a:bodyPr/a:sp3d`. Rare: * present when a quick style extrudes the label text itself off the shape * face (e.g. Bird's Eye Scene: `extrusionH="28000"`), rather than only the * shape body. */ text3d?: Text3DStyle; /** * The presentation style label (`presStyleLbl`: `node1`, `revTx`, * `sibTrans2D1`, ...) of the layout node a REGENERATED shape was laid out * from, when the layout engine reports it. Picks the quick-style label * whose 3D the shape takes; `undefined` on cached (parsed) shapes. */ styleLabel?: string; } declare interface PptxSmartArtForEach extends PptxSmartArtIteratorAttributes { rawXml?: XmlObject; } declare type PptxSmartArtHueDirection = 'cw' | 'ccw'; declare interface PptxSmartArtIteratorAttributes { name?: string; reference?: string; axis?: string[]; pointTypes?: string[]; hideLastTransition?: boolean[]; start?: number[]; count?: number[]; step?: number[]; } /** Typed DiagramML CT_Algorithm data attached to a layout node. */ declare interface PptxSmartArtLayoutAlgorithm { type: string; revision?: number; parameters?: PptxSmartArtAlgorithmParameter[]; } declare interface PptxSmartArtLayoutCategory { type: string; priority: number; } /** Metadata and root node from DiagramML CT_DiagramDefinition. */ declare interface PptxSmartArtLayoutDefinition { uniqueId?: string; minimumVersion?: string; defaultStyle?: string; titles?: PptxSmartArtLocalizedText[]; descriptions?: PptxSmartArtLocalizedText[]; categories?: PptxSmartArtLayoutCategory[]; rootNode: PptxSmartArtLayoutNode; /** Original definition retained for constraint evaluation and foreign rules. */ rawXml?: XmlObject; /** * The un-parsed layout-definition part text (starting at ``, * XML declaration included). `rawXml` above loses the document order of * differently-named siblings (the package-wide `fast-xml-parser` * configuration groups children into one array per tag), which the * per-point DiagramML engine (`core/utils/smartart-engine/`) needs to * execute a `layoutNode` body's `forEach`/`choose`/`constrLst` statements * in their real declared sequence - see that package's `ordered-xml.ts`. * `undefined` when the part could not be read (matches `rawXml`'s own * optionality); the engine falls back to the legacy interpreter then. */ rawXmlText?: string; } /** Identity and ordering metadata from DiagramML CT_LayoutNode. */ declare interface PptxSmartArtLayoutNode { name?: string; styleLabel?: string; childOrder?: 'b' | 't'; moveWith?: string; algorithm?: PptxSmartArtLayoutAlgorithm; forEach?: PptxSmartArtForEach[]; choose?: PptxSmartArtChoose[]; constraints?: PptxSmartArtConstraint[]; rules?: PptxSmartArtNumericRule[]; /** `dgm:shape`: this node's own preset geometry override, when present. */ shape?: PptxSmartArtLayoutNodeShape; /** * `dgm:presOf` (CT_PresentationOf, same iterator shape as `dgm:forEach`): * which data-model point(s) this node's OWN text/geometry binds to - * `axis: ['self']` the point currently being iterated, `['des']` all of * its descendants, `['ch']` its direct children, and so on. Absent or * empty `axis` (including a bare ``) means the node carries * no text of its own (a pure positioning/decoration wrapper - `composite`, * `sp` spacer, connector cap). See `smartart-layout-interpreter-item- * roles.ts`, the one consumer: it is what lets the interpreter tell a * text-bearing per-item role (a list layout's `childText`, a card * layout's `roleText`/`bodyText`) apart from a same-generation sibling * that positions or decorates instead. */ presentationOf?: PptxSmartArtIteratorAttributes; /** * EVERY `dgm:constr` reachable from this node, including ones declared * inside a `dgm:choose`/`dgm:if`/`dgm:else` that wraps THIS layoutNode's * `constrLst` (a genuinely conditional constraint set, e.g. one branch * per data-point count - `gear`'s composite positions its `gear1`/ * `gear2`/`gear3` slots this way, so its plain, direct-child-only * `constraints` above is empty for it). Stops at a nested `dgm:layoutNode` * boundary: that child's own conditional constrLst becomes ITS * `allConstraints`, not folded into the parent's. Read-only / * interpretation-only - `constraints` above (this node's own DIRECT * constrLst) remains the one `applySmartArtLayoutDefinition` round-trips, * so editing an unrelated property can never collapse a genuinely * conditional constrLst into a single branch. `undefined` when this node * declares no constrLst at all, in or out of a choose (the common case); * otherwise a superset of `constraints` (every branch, blindly unioned - * this interpreter does not evaluate `dgm:choose` conditions when * indexing constraints, matching the same "flatten both branches" * convention `nestedLayoutNodes` already uses for `children`). See * `smartart-constraint-solver.ts`'s `buildConstraintIndex`, the only * consumer. */ allConstraints?: PptxSmartArtConstraint[]; children?: PptxSmartArtLayoutNode[]; /** * The iterator attributes of the ENCLOSING `dgm:forEach` this node was * found through, when `nestedLayoutNodes` (`smartart-layout-definition * .ts`) reached it by walking one - as opposed to being a direct child of * its parent layoutNode, or reached only through a `dgm:choose` wrapper * (a condition, not an iteration, leaves this `undefined`). * * `forEach` above records a node's OWN direct `dgm:forEach` children * (which wrap ITS descendants); this is the opposite direction - the * forEach that wraps the node ITSELF, one level up. A layoutNode can sit * inside more than one enclosing forEach only via nesting, so this is * always the SINGLE nearest one, not a list. * * This is what tells a genuinely repeated per-child template * (`axis="ch"`, `ptType` absent or `"node"`) apart from a once-only or * transition-only sibling that merely happens to sit inside SOME * `dgm:forEach` (a `ptType="parTrans"`/`"sibTrans"` connector, or * `axis="followSib" cnt="1"`) - both can be direct siblings under the * SAME parent layoutNode (`lProcess1`'s `vertFlow` has one forEach for * its `parTrans` connector and a SEPARATE one, `axis="ch"`, for its * repeated `child` items; `vertFlow.forEach` bundles both, but only * `child.forEachOrigin` says which ONE produced it). See * `smartart-layout-interpreter-item-roles-recursive.ts`, the one * consumer. Read-only / interpretation-only, like `allConstraints`: * never round-tripped by `applySmartArtLayoutDefinition`. */ forEachOrigin?: PptxSmartArtIteratorAttributes; /** * The conditions of EVERY enclosing `dgm:if` this node was found through, * outermost first, when `nestedLayoutNodes` (`smartart-layout- * definition.ts`) reached it via one or more `dgm:choose`'s `if` branches * (as opposed to a direct child, a `dgm:else` branch contributing no * condition of its own - see below - or a `dgm:forEach`, which sets * {@link forEachOrigin} instead). ALL must hold (evaluate `!== false`, * per {@link chooseGuard}'s own AND semantics - see `evaluateWhen`) for * this node's branch to be genuinely live. A caller that already has the * data-model node list can use this instead of treating every * choose-flattened branch as unconditionally present * (`nestedLayoutNodes`' pre-existing "flatten every branch" convention, * still the default when this is absent or a caller does not evaluate * it) - e.g. `cycle-matrix--fallback-n2.pptx`'s `child1group`.. * `child4group`, each gated on a DIFFERENT top-level point existing and * having its own child (`axis="ch ch" st="N 1" cnt="1 0" func="cnt" * op="gte" val="1"`). * * A CHAIN, not a single condition, because a node can sit inside NESTED * `dgm:choose`s whose OWN conditions are each individually necessary - * `sub-step-process--hier5.pptx`'s `chLin1`..`chLin7` each sit inside * BOTH an outer `dgm:if func="pos" op="equ" val="N"` (which one of the * 7 hand-duplicated per-position templates this is) AND an inner, * nearly-vacuous `dgm:if func="cnt" op="gte" val="1"` (has >= 1 point at * all) - keeping only the NEAREST (inner) one, as an earlier single- * condition design did, loses the ONE piece of information (the outer * `pos` guard) that actually discriminates `chLin1` from `chLin2`. * * A `dgm:else` branch contributes NO condition of its own (ECMA-376 * defines it as "none of the sibling ifs matched", which would need the * FULL sibling list's conditions negated and ANDed together, not a * single condition - no gallery fixture measured needs an else branch's * own guard yet, so it is left unconditional, matching the pre-existing * flatten-everything behaviour) but does NOT clear any OUTER ancestor * guard already accumulated before it. Evaluate with `smartart-layout- * interpreter-when.ts`'s `evaluateWhen`, once per entry, ANDed. */ chooseGuard?: PptxSmartArtWhen[]; /** * ROUND 42: the forEach iterator active WHEN EACH ENTRY of {@link * chooseGuard} was declared (index-parallel with it, `undefined` per * entry when no forEach was active at that point) - NOT the same as * {@link forEachOrigin}, which is always this NODE's own single nearest * enclosing forEach, however deep. A `dgm:if` declared ABOVE a `dgm:forEach` * that this node's own branch happens to descend through afterwards needs * ITS OWN, SHALLOWER anchor for a `func="cnt"`/`"maxDepth"`-family * `@axis` condition, not this node's deeper one - `funnel--flat3.pptx`'s * `item1`/`item2`/`item3` (`chooseGuard: [Name5's axis="ch" func="cnt" * op="gte" val="1"]`, declared directly under the composite root, BEFORE * each item's own per-item `dgm:forEach axis="ch" st="2"/"3"/"4" cnt="1"`) * is exactly this shape: evaluating Name5's condition anchored to item1's * OWN forEach binding (one specific data point, with no children of its * own in a flat dataset) wrongly resolves its `axis="ch"` child count to * 0 instead of the diagram's real top-level count, dropping the item * entirely - `chooseGuardOrigins[i]` for that entry is `undefined` * (Name5 sits above ANY forEach), so the guard correctly stays * root-relative. See `smartart-layout-interpreter-composite- * candidates.ts`'s `guardAllows`, the one production consumer. * `undefined` whenever {@link chooseGuard} itself is (no enclosing * choose at all). */ chooseGuardOrigins?: (PptxSmartArtIteratorAttributes | undefined)[]; /** * The chain of every enclosing `dgm:choose`'s own GROUP identity + this * node's ordinal position within it + THAT branch's own condition, * outermost first - identifies WHICH `dgm:choose` instance and WHERE * within its own `dgm:if`/`dgm:else` list this node's branch sits, unlike * {@link chooseGuard} (a flat AND-chain of every condition with no group/ * position identity, and no entry at all for a `dgm:else` branch, which * has no condition of its own - see that field's doc comment). `id` is a * synthetic, process-unique identifier assigned per `dgm:choose` instance * during flattening (`smartart-layout-definition-nesting.ts`'s * `nestedLayoutNodes`, a monotonic counter - NOT round-tripped, NOT the * choose's own `@_name`, which is not guaranteed unique across a whole * layoutDef); `ordinal` is 0-based document order within that ONE choose * (every `dgm:if` in order, then `dgm:else` last, if present); `guard` is * that branch's OWN condition (`undefined` for a `dgm:else` entry, which * has none - deliberately kept PER-ENTRY rather than cross-referenced by * index against {@link chooseGuard}, whose own length can diverge from * this chain's whenever an ancestor `dgm:else` contributed a group * position but no guard). * * Lets a consumer recover ECMA-376's real `dgm:choose` semantics - "the * FIRST branch whose condition holds wins, siblings never coexist" - * from the flattened `.children` array, where that grouping would * otherwise be lost: `balance--hier5.pptx`'s `balance_NN`/`left_NN_M`/ * `right_NN_M` family (127 members across ~30 NESTED `dgm:choose` * instances, not one flat 127-branch choose) needs first-match-wins * WITHIN each individual choose to resolve to the single genuinely-live * arrangement, not the "every guard-true node is an independent * candidate" reading `smartart-layout-interpreter-composite-choose.ts`'s * `collectRawCandidates` used before this field existed - see that * module's own consumer of this field for the actual selection rule. * `undefined` (or an empty array) for a node reached without any * enclosing choose (a direct child, or a `dgm:forEach`-only path) - * every PRE-EXISTING caller that does not consult this field is * unaffected by its mere presence. * * ROUND 42: `origin` is the forEach iterator active when THIS branch's * own `dgm:if`/`dgm:else` was declared (the SAME "declaration time, not * whatever descendant ends up carrying it" concept {@link * chooseGuardOrigins} exists for) - the anchor a `func="cnt"`/`"maxDepth"` * -family condition in `guard` needs, NOT a representative member's own * (possibly deeper) `forEachOrigin`. See `smartart-layout-interpreter- * composite-choose-groups.ts`'s `winningOrdinalFor`, the one consumer. */ chooseGroups?: { id: string; ordinal: number; guard?: PptxSmartArtWhen; origin?: PptxSmartArtIteratorAttributes; }[]; /** * Every `dgm:presOf` candidate reachable through a `dgm:choose`/`dgm:if`/ * `dgm:else` wrapping THIS node's OWN presOf (as opposed to * {@link chooseGuard}, which gates the layoutNode's own EXISTENCE), each * tagged with the FULL chain of enclosing `dgm:if` conditions that select * it (`guard`, empty for an unconditional or `dgm:else`-reached * candidate), in document order (every `dgm:if` then `dgm:else` last). * `undefined` when this node's presOf is not choose-guarded at all (the * overwhelmingly common case) - {@link presentationOf} already carries * the one-and-only value then. Exists for a genuinely conditional presOf * where TWO OR MORE branches each declare a real, DIFFERENT axis * (`funnel--flat3.pptx`'s `item1`/`item2`/`item3`, one literal axis per * data-point count): `smartart-layout-definition-constraints.ts`'s * `choosePresentationOf` (feeding {@link presentationOf}) can only ever * guess ONE branch statically, at parse time, with no diagram to * evaluate against; this field lets an interpret-time caller with the * actual diagram (`smartart-layout-interpreter-when.ts`'s * `resolvePresentationOf`, the one consumer) pick the branch PowerPoint's * own runtime would, first-match-wins. */ presentationOfCandidates?: { guard: PptxSmartArtWhen[]; presentationOf: PptxSmartArtIteratorAttributes; }[]; /** * SESSION 17: every `dgm:rule` reachable through a `dgm:choose`/`dgm:if`/ * `dgm:else` wrapping THIS node's `ruleLst` (a genuinely count-gated rule * set, e.g. `diverging-radial`'s own `w for="ch" forName="node"` ceiling: * 6 `dgm:if cnt<=N` branches, each its own `fact`), tagged with its guard * chain - the SAME shape {@link presentationOfCandidates} uses for * choose-guarded `presOf`, applied to `dgm:rule`. `undefined` when not * choose-guarded (`rules` above then carries the one set, the common * case). See `smartart-layout-interpreter-cycle-hub-ratio.ts`'s * `resolveHubToNodeRatio` (COM-verified live mechanism, not a guess) for * how the guard is evaluated against the real satellite count. */ ruleCandidates?: { guard: PptxSmartArtWhen[]; rule: PptxSmartArtNumericRule; }[]; /** * ROUND 39: every `dgm:constr` reachable through a `dgm:choose`/`dgm:if`/ * `dgm:else` wrapping THIS node's `constrLst` (a genuinely count/position * -branched constraint set, e.g. `basic-venn--flat3.pptx`'s composite * `Name9` choose, one `ctrX`/`ctrY`/`w`/`h` per data-point-count branch * for `circ1`/`circ1Tx`/...), each tagged with its guard chain - the SAME * shape {@link presentationOfCandidates}/{@link ruleCandidates} use, * applied to `dgm:constr`. `undefined` when not choose-guarded * (`allConstraints`/`constraints` above then carry the one set, the * common case). See `smartart-constraint-branch-index.ts`'s * `selectConstraints` for how the guard is evaluated against the real * diagram, and that module's own doc comment for why `allConstraints`'s * pre-existing blind union of every branch is not enough on its own. */ constraintCandidates?: { guard: PptxSmartArtWhen[]; constraint: PptxSmartArtConstraint; }[]; } /** * Typed DiagramML CT_Shape data (`dgm:shape`) attached to a layout node: the * per-node preset geometry override real (and third-party/custom) layout * definitions use so a layoutNode can be e.g. an ellipse or a chevron instead * of the arranger family's hardcoded default shape. */ declare interface PptxSmartArtLayoutNodeShape { /** `dgm:shape/@type`: a preset geometry name (`roundRect`, `ellipse`, `chevron`, `conn`, ...). */ presetGeometry?: string; /** `dgm:adjLst/dgm:adj` entries (adjustment index -> value, as authored). */ adjustments?: PptxSmartArtShapeAdjustment[]; /** `dgm:shape/@hideGeom`: the shape is present only to size text, never painted. */ hideGeometry?: boolean; /** * `dgm:shape/@lkTxEntry` (CT_Shape, boolean, default false): this node is a * decorative shape that should mirror its paired content node's text * rather than always rendering blank. See `smartart-layout-interpreter- * pyramid.ts`'s `arrangePyramid`, the interpreter's one existing * synthesized-decorative-shape call site. */ lkTxEntry?: boolean; } declare interface PptxSmartArtLocalizedText { value: string; language?: string; } /** * A single node in the SmartArt data model. * * @example * ```ts * const node: PptxSmartArtNode = { * id: "1", * text: "CEO", * children: [ * { id: "2", text: "VP Marketing", parentId: "1" }, * { id: "3", text: "VP Engineering", parentId: "1" }, * ], * }; * // => satisfies PptxSmartArtNode * ``` */ declare interface PptxSmartArtNode { id: string; text: string; /** CT_Pt connection identifier, when the point references a connection. */ connectionId?: string | null; parentId?: string; children?: PptxSmartArtNode[]; /** Node type from `@_type` attribute (e.g. "doc", "node", "asst", "pres"). */ nodeType?: string; /** * The node's own quick-style role (`dgm:prSet/@presStyleLbl` from its * paired `type="pres"` presentation point, resolved via a `presOf` * connection back to this content point). Structural names like `node1`, * `asst2`, `bgShp`, `revTx`; distinct from {@link nodeType}, which is the * data-model `@_type` ("node"/"asst"/...). Used to pick this node's own * colour list from a colour transform's per-role palettes instead of the * generic cycled palette (see `applySmartArtRoleColors`). */ styleRole?: string; /** * `dgm:prSet/@coherent3DOff` (`CT_ElemPropSet`) resolved from the node's * paired presentation point: when true, this node opts out of the * diagram's overall coherent-3D scene rotation (a `dgm:scene3d`/`dgm:sp3d` * quick-style variation) applied to every other node. */ coherent3DOff?: boolean; /** * The layout variables PowerPoint recorded for each presentation node * this point drives (`dgm:prSet/@presName` -> `dgm:presLayoutVars` * variable -> `@val`), e.g. `{ hierRoot1: { hierBranch: 'l' } }` for an * org-chart manager set to "Left Hanging". Read-only: the presentation * points themselves round-trip verbatim. */ presLayoutVarsByName?: Record>; /** * Per-run text + run-properties for the node's first paragraph, captured at * parse time. When the joined run text still equals {@link text} (the node * was not edited, or was edited only in ways that preserve the run split), * the save path rebuilds the paragraph from these runs so per-run rich text * is not flattened. When {@link text} diverges, the runs are ignored. */ runs?: PptxSmartArtTextRun[]; /** * Complete typed paragraph model. Unlike {@link runs}, this retains every * paragraph and the ordered run, field, break, and tab children within it. */ paragraphs?: PptxSmartArtTextParagraph[]; /** * Optional per-node visual override (fill / line / font colour, bold / * italic). Read at parse time from the point's `spPr` / first-run `rPr`, set * by the editing op, honoured by the render path, and written back on save so * it round-trips. */ style?: PptxSmartArtNodeStyle; /** * Manual layout override read from the node's `dgm:prSet` `cust*` * attributes (drag/resize/rotate/flip performed in PowerPoint's own diagram * editor). Applied as a final transform after algorithmic layout by * {@link module:smartart-layout-interpreter-custom} so it survives even * when there is no cached `dsp:` drawing to fall back on. */ customLayout?: SmartArtNodeCustomLayout; } /** * Per-node visual override for a SmartArt node. * * Captures the individual fill / line / font colour and the bold / italic * emphasis a user has set on one specific node, independent of the diagram's * colour scheme and quick style. All colours are hex strings (e.g. "#FF0000"). * Every field is optional: only the overridden aspects are carried, so an * empty object means "no per-node override". * * The parser reads these from the data point's `spPr` solid fill / line colour * and the first run's `rPr` (b / i / solidFill) when present, and the save path * writes them back so the override survives a load -> edit -> save round-trip. * * @example * ```ts * const style: PptxSmartArtNodeStyle = { * fillColor: "#FF0000", * fontColor: "#FFFFFF", * bold: true, * }; * // => satisfies PptxSmartArtNodeStyle * ``` */ declare interface PptxSmartArtNodeStyle { /** Solid fill colour override (hex, e.g. "#4F81BD"). */ fillColor?: string; /** Outline / line colour override (hex). */ lineColor?: string; /** Text (font) colour override (hex). */ fontColor?: string; /** Bold emphasis override for the node's runs. */ bold?: boolean; /** Italic emphasis override for the node's runs. */ italic?: boolean; } /** Editable DiagramML CT_NumericRule. */ declare interface PptxSmartArtNumericRule extends PptxSmartArtConstraintTarget { type: string; value?: number; factor?: number; max?: number; /** Original rule retained for foreign attributes and extension content. */ rawXml?: XmlObject; } /** * Presentation layout variables from `dgm:prSet/dgm:presLayoutVars` (data model) * or `dgm:varLst` (layout definition defaults). * * These drive how the DiagramML layout interpreter arranges points: flow * direction, hierarchy branch style, org-chart mode, and child count limits. * The fallback layout engine can consult them for direction/org-chart hints. * * @example * ```ts * const vars: PptxSmartArtPresLayoutVars = { direction: "rev", orgChart: true }; * // => satisfies PptxSmartArtPresLayoutVars * ``` */ declare interface PptxSmartArtPresLayoutVars { /** Flow direction (`dgm:dir`): "norm" (default) or "rev" (reversed/RTL). */ direction?: 'norm' | 'rev'; /** Hierarchy branch style (`dgm:hierBranch`): std/init/l/r/hang. */ hierarchyBranch?: 'std' | 'init' | 'l' | 'r' | 'hang'; /** Org-chart mode enabled (`dgm:orgChart`). */ orgChart?: boolean; /** Maximum children per node (`dgm:chMax`, -1 = unbounded). */ childMax?: number; /** Preferred children per node (`dgm:chPref`, -1 = unbounded). */ childPreferred?: number; /** Whether bullets are enabled (`dgm:bulletEnabled`). */ bulletEnabled?: boolean; /** Animation-by-level setting (`dgm:animLvl`). */ animationLevel?: string; /** Animate-one setting (`dgm:animOne`). */ animateOne?: string; /** Allowed resize handles (`dgm:resizeHandles`). */ resizeHandles?: string; } /** Typed CT_StyleDefinition metadata and legacy rendering hint. */ declare interface PptxSmartArtQuickStyle extends PptxSmartArtDefinitionMetadata { /** Legacy resolved display name. */ name?: string; /** Legacy effect-intensity rendering hint. */ effectIntensity?: string; /** Ordered CT_StyleLabel metadata. Complex style payload remains preserved XML. */ labels?: PptxSmartArtQuickStyleLabel[]; /** * Whole-diagram 3D scene (camera preset/rotation/zoom/fov, light rig, * backdrop) from the quick style's own `dgm:styleDef/dgm:scene3d`, present * for the "Scene" quick styles (Brick, Flat, Metallic, Sunset, Bird's Eye * Scene). One camera renders the whole diagram; per-shape `a:scene3d` is * absent for those styles (see `PptxSmartArtDrawingShape.scene3d`). Each * `dgm:styleLbl` also carries its own per-label `dgm:scene3d`/`dgm:sp3d` * ({@link PptxSmartArtQuickStyleLabel.scene3d} / `shape3d` / `text3d`), * which PowerPoint bakes onto each cached shape; they are re-applied when a * structural edit regenerates the shapes. */ scene3d?: Pptx3DScene; } /** CT_StyleLabel metadata from a quick-style definition. */ declare interface PptxSmartArtQuickStyleLabel { name: string; /** Theme-resolved `dgm:style` refs for this label's role, when available. */ resolvedStyle?: PptxSmartArtResolvedStyleRef; /** * The label's own `dgm:scene3d` (per-shape camera + light rig). PowerPoint * copies it onto a shape's cached `a:scene3d` unless it is the default * front camera with a `threePt` light (see `applySmartArtQuickStyle3d`). */ scene3d?: Pptx3DScene; /** The label's own `dgm:sp3d` (bevel / extrusion / contour / material); absent when empty. */ shape3d?: Pptx3DShape; /** The label's `dgm:txPr/a:sp3d` label-text extrusion (Bird's Eye Scene). */ text3d?: Text3DStyle; } /** * A `dgm:bg` fill this viewer doesn't fully model as first-class chrome * (gradient or pattern), preserved verbatim for round-trip. See * {@link PptxSmartArtChrome.backgroundFillXml}. */ declare interface PptxSmartArtRawBackgroundFill { /** Local element name of the fill under `dgm:bg` (`gradFill` or `pattFill`). */ localName: 'gradFill' | 'pattFill'; /** The fill element's own attributes/children, as parsed. */ xml: XmlObject; } /** * A quick-style label's `a:lnRef`/`a:fillRef`/`a:effectRef`/`a:fontRef` * (`CT_ShapeStyle`, the same complex type an ordinary shape's `p:style` * uses), resolved against the theme's `fmtScheme` at parse time instead of * the coarse subtle/moderate/intense enum ({@link PptxSmartArtQuickStyle.effectIntensity}). * Only populated when a theme format scheme was available when the quick * style was parsed. See G13 in the 2026-09 diagram audit. */ declare interface PptxSmartArtResolvedStyleRef { fillColor?: string; fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'theme'; strokeColor?: string; strokeWidth?: number; /** `a:effectRef`'s theme-resolved outer shadow colour, when the style has one. */ shadowColor?: string; /** `a:fontRef`'s theme-resolved typeface (`+mn-lt`/`+mj-lt` -> the theme's actual font). */ fontTypeface?: string; } /** A single `dgm:adj/@val` adjustment, keyed by its `@idx` (1-based, like `a:gd`). */ declare interface PptxSmartArtShapeAdjustment { index: number; value: number; } /** A complete `a:p` paragraph in a SmartArt data-model text body. */ declare interface PptxSmartArtTextParagraph { /** Paragraph properties (`a:pPr`) preserved verbatim. */ pPr?: Record; /** Text children in source order. */ items: PptxSmartArtTextParagraphItem[]; /** End-paragraph run properties (`a:endParaRPr`) preserved verbatim. */ endParaRPr?: Record; /** Resolved style for the paragraph terminator. */ endParaStyle?: TextStyle; /** Raw paragraph XML used to retain unmodelled extension children on save. */ rawXml?: Record; } /** An ordered item within a SmartArt text paragraph. */ declare type PptxSmartArtTextParagraphItem = { kind: 'run'; run: PptxSmartArtTextRun; } | { kind: 'break'; rPr?: Record; style?: TextStyle; rawXml?: Record; childOrder?: string[]; } | { kind: 'field'; id?: string; fieldType?: string; text: string; rPr?: Record; style?: TextStyle; pPr?: Record; rawXml?: Record; childOrder?: string[]; } | { kind: 'tab'; rawXml?: Record; childOrder?: string[]; } | { kind: 'raw'; name: string; value: unknown; }; /** * A single run of text inside a SmartArt node, capturing the run text and the * raw `a:rPr` run-properties object verbatim so per-run formatting (bold, * colour, size, etc.) survives a load -> edit -> save round-trip instead of * collapsing to a single unstyled run. * * @example * ```ts * const run: PptxSmartArtTextRun = { * text: "Bold", * rPr: { "@_b": "1", "@_lang": "en-US" }, * }; * // => satisfies PptxSmartArtTextRun * ``` */ declare interface PptxSmartArtTextRun { /** Run text content. */ text: string; /** * Raw parsed `a:rPr` run-properties object, preserved verbatim for * round-trip. Untyped XML, hence the loose record shape. */ rPr?: Record; /** Resolved standard shape-text style derived from {@link rPr}. */ style?: TextStyle; /** Raw run XML used to retain unmodelled extension children on save. */ rawXml?: Record; /** Original direct-child order, including unmodelled extension children. */ childOrder?: string[]; } declare interface PptxSmartArtWhen extends PptxSmartArtIteratorAttributes { function: string; argument?: string; operator: string; value: string; rawXml?: XmlObject; } /** * A recognizer-owned `p:smartTags` reference from `presentation.xml` * (CT_SmartTags, ECMA-376 S19.2.1.42): a bare relationship id pointing at a * legacy Office "Smart Tags" recognizer part, distinct from the * user-authored `p:tags` construct (see {@link PptxTagCollection}). * * This library has no data model for recognizer part CONTENT (there is no * way to create, inspect, or edit one through the public API), so this type * only captures enough to preserve an authored reference losslessly: the * relationship id and, when resolvable, the target part path. */ declare interface PptxSmartTagsReference { /** Relationship id from `p:smartTags/@r:id`. */ relId: string; /** Resolved ZIP path of the referenced recognizer part, when resolvable. */ targetPath?: string; /** Raw `p:smartTags` XML retained for lossless round-trip. */ rawXml?: XmlObject; } /** Split orientation from OOXML `@_orient`. */ declare type PptxSplitOrientation = 'horz' | 'vert'; /** * A single table cell with text content, optional style, and merge info. * * @example * ```ts * const cell: PptxTableCell = { * text: "$1.5M", * style: { bold: true, align: "right" }, * gridSpan: 1, * }; * // => satisfies PptxTableCell * ``` */ declare interface PptxTableCell { text: string; style?: PptxTableCellStyle; /** * Per-run formatting for the cell's text, when it has any beyond what * {@link style} can express. Present only for cells whose `a:txBody` * actually carries runs; renderers fall back to {@link text} when absent. * * Editing a cell's text invalidates these (the editor produces a plain * string), so an edit path must clear them alongside setting `text`. */ textRuns?: PptxTableCellTextRun[]; /** Column span (defaults to 1). */ gridSpan?: number; /** Row span (defaults to 1). */ rowSpan?: number; /** Whether this cell is merged vertically with the cell above. */ vMerge?: boolean; /** Whether this cell is horizontally merged with the cell to the left (gridSpan continuation). */ hMerge?: boolean; /** * Opaque round-trip storage for `a:tcPr` attributes that don't yet have * typed equivalents on {@link PptxTableCellStyle} (e.g. `horzOverflow`, * `anchorCtr`, `headers`, `hideSlicers`, `slicerCacheId`). Keys are the * raw XML attribute names without the `@_` prefix used by * fast-xml-parser. Re-emitted verbatim by the save writer when present. */ extraAttributes?: Record; } /** * Cell 3D bevel + lighting parsed from `a:tcPr/a:cell3D` (CT_Cell3D). * * Only the fields needed to render a plausible bevel treatment are captured; * verbatim round-trip of the full node is handled separately by the save path. * * @example * ```ts * const c3d: PptxTableCell3D = { * bevelWidth: 8, * bevelHeight: 8, * bevelPreset: 'circle', * material: 'plastic', * }; * // => satisfies PptxTableCell3D * ``` */ declare interface PptxTableCell3D { /** Bevel width in px (from `a:bevel@w`, EMU converted). */ bevelWidth?: number; /** Bevel height in px (from `a:bevel@h`, EMU converted). */ bevelHeight?: number; /** Bevel preset name (`a:bevel@prst`, e.g. `circle`, `relaxedInset`). */ bevelPreset?: string; /** Preset material (`a:cell3D@prstMaterial`, e.g. `plastic`, `metal`). */ material?: string; /** Light rig type (`a:lightRig@rig`, e.g. `threePt`, `soft`). */ lightRig?: string; /** Light rig direction (`a:lightRig@dir`, e.g. `tl`, `t`, `tr`). */ lightRigDirection?: string; } /** * Per-cell visual style for a table cell. * * All fields are optional - unset values inherit from the table style. * * @example * ```ts * const header: PptxTableCellStyle = { * bold: true, * fontSize: 14, * color: "#FFFFFF", * backgroundColor: "#0055AA", * align: "center", * }; * // => satisfies PptxTableCellStyle * ``` */ declare interface PptxTableCellStyle { /** Font size in points (`a:rPr@sz / 100`). */ fontSize?: number; bold?: boolean; italic?: boolean; underline?: boolean; color?: string; /** * Font family from the first run's `a:rPr/a:latin@typeface` (falling back to * `a:ea` / `a:cs`). Per-run families live on {@link PptxTableCellTextRun}. */ fontFamily?: string; /** * Raw XML colour-choice node preserved from `a:tc/a:txBody/.../a:rPr/a:solidFill` * for round-trip serialisation. Currently unused by the cell-level writer * (cell text colour falls through `writeCellTextFormatting`), reserved for * future expansion alongside the run-properties round-trip path. */ colorXml?: XmlObject; /** * Typed theme colour reference for the cell text colour, set when * {@link colorXml} is a plain `a:schemeClr`. Wins on save, mirroring * `TextStyle.colorRef`. Distinct from {@link ParsedTableStyleFill.schemeColor}, * which describes a `ppt/tableStyles.xml` section fill rather than an * individual cell override. */ colorRef?: PptxThemeColorRef; backgroundColor?: string; /** * Raw XML colour-choice node preserved from cell `a:tcPr/a:solidFill` for * round-trip serialisation. Re-emitted verbatim when the resolved * {@link backgroundColor} still matches the original colour. */ backgroundColorXml?: XmlObject; /** * Typed theme colour reference for the cell fill, set when * {@link backgroundColorXml} is a plain `a:schemeClr`. Wins on save, * mirroring `ShapeStyle.fillColorRef`. */ backgroundColorRef?: PptxThemeColorRef; borderColor?: string; /** Top border width in px. */ borderTopWidth?: number; /** Bottom border width in px. */ borderBottomWidth?: number; /** Left border width in px. */ borderLeftWidth?: number; /** Right border width in px. */ borderRightWidth?: number; /** Top border color as hex. */ borderTopColor?: string; /** Bottom border color as hex. */ borderBottomColor?: string; /** Left border color as hex. */ borderLeftColor?: string; /** Right border color as hex. */ borderRightColor?: string; align?: 'left' | 'center' | 'right' | 'justify'; vAlign?: 'top' | 'middle' | 'bottom'; /** Text direction from `a:tcPr/@vert` (spec values from CT_TextVerticalType). */ textDirection?: 'vert' | 'vert270' | 'eaVert' | 'wordArtVert' | 'wordArtVertRtl' | 'mongolianVert'; /** Cell left margin in px (from a:tcPr > a:tcMar > a:marL). */ marginLeft?: number; /** Cell right margin in px. */ marginRight?: number; /** Cell top margin in px. */ marginTop?: number; /** Cell bottom margin in px. */ marginBottom?: number; /** Diagonal border top-left to bottom-right color. */ borderDiagDownColor?: string; /** Diagonal border top-left to bottom-right width in px. */ borderDiagDownWidth?: number; /** Diagonal border bottom-left to top-right color. */ borderDiagUpColor?: string; /** Diagonal border bottom-left to top-right width in px. */ borderDiagUpWidth?: number; /** Table cell border dash style (legacy single value). */ borderDash?: string; /** Per-edge border dash styles. */ borderTopDash?: string; borderBottomDash?: string; borderLeftDash?: string; borderRightDash?: string; /** Cell text shadow colour. */ textShadowColor?: string; /** Cell text shadow blur radius in px. */ textShadowBlur?: number; /** Cell text shadow horizontal offset in px. */ textShadowOffsetX?: number; /** Cell text shadow vertical offset in px. */ textShadowOffsetY?: number; /** Cell text shadow opacity (0-1). */ textShadowOpacity?: number; /** Cell text glow colour. */ textGlowColor?: string; /** Cell text glow radius in px. */ textGlowRadius?: number; /** Cell text glow opacity (0-1). */ textGlowOpacity?: number; /** Cell fill mode: solid, gradient, pattern, image, or none. */ fillMode?: 'solid' | 'gradient' | 'pattern' | 'image' | 'none'; /** Gradient fill stops (colours with positions). */ gradientFillStops?: Array<{ color: string; position: number; opacity?: number; }>; /** Gradient angle in degrees. */ gradientFillAngle?: number; /** Gradient type: linear or radial. */ gradientFillType?: 'linear' | 'radial'; /** Path gradient sub-type. */ gradientFillPathType?: 'circle' | 'rect' | 'shape'; /** Focal point for radial gradients (0–1 fractions). */ gradientFillFocalPoint?: { x: number; y: number; }; /** Raw fillToRect LTRB values (0–1 fractions) for gradient sizing. */ gradientFillFillToRect?: { l: number; t: number; r: number; b: number; }; /** Pre-computed CSS gradient string for rendering. */ gradientFillCss?: string; /** Pattern fill preset name (e.g. "ltDnDiag"). */ patternFillPreset?: string; /** Pattern fill foreground colour. */ patternFillForeground?: string; /** Pattern fill background colour. */ patternFillBackground?: string; /** * Image fill (`a:tcPr/a:blipFill`, CT_TableCellProperties). Resolved * archive-relative path (or external `http(s):`/`data:` URL) for the * cell's background image, from `a:blipFill/a:blip/@r:embed` (or * `@r:link`). Present when `fillMode` is `'image'`. * * The parser resolves this synchronously (path only, no binary read); * a viewer's load pipeline resolves it further to a displayable * `data:`/`blob:` URL, written back to {@link backgroundImageFillData}. */ backgroundImageFillPath?: string; /** * Displayable image data (`data:` or `blob:` URL) for an image cell * fill, once resolved by the load pipeline. Renderers should prefer * this over {@link backgroundImageFillPath} when both are present. */ backgroundImageFillData?: string; /** * Cell 3D bevel + lighting from `a:tcPr/a:cell3D` (CT_Cell3D, * ECMA-376 §21.1.3.1). Rendered as a CSS bevel treatment. */ cell3D?: PptxTableCell3D; /** * `a:tcPr/@anchorCtr` - centre the text block in the direction * perpendicular to the text flow (horizontal centring for horizontal text). */ anchorCtr?: boolean; /** * `a:tcPr/@horzOverflow` (ST_TextHorzOverflowType): `clip` clips text at * the cell edge, `overflow` (the default) lets it spill. */ horzOverflow?: 'clip' | 'overflow'; } /** * One styled text run inside a table cell's `a:txBody`. * * `PptxTableCell.text` is a flat string and `PptxTableCell.style` describes * only the FIRST run, so a cell mixing formats ("Revenue **grew 42%** last * year") cannot be represented by those two alone. {@link PptxTableCell.runs} * carries the full sequence, with paragraph and line breaks as marker entries * so a renderer can walk it linearly. * * Structurally identical to `pptx-viewer-shared`'s `CellTextRun`, which every * binding's table renderer already consumes. * * @example * ```ts * const runs: PptxTableCellTextRun[] = [ * { text: "Revenue " }, * { text: "grew 42%", bold: true, color: "#C00000" }, * ]; * // => satisfies PptxTableCellTextRun[] * ``` */ declare interface PptxTableCellTextRun { /** Run text. Empty for the break markers below. */ text: string; /** This entry starts a new paragraph (`a:p` boundary) rather than carrying text. */ isParagraphBreak?: boolean; /** This entry is a soft line break (`a:br`) rather than carrying text. */ isLineBreak?: boolean; /** This entry carries an `a:fld` value rather than a literal `a:r`. */ isField?: true; bold?: boolean; italic?: boolean; underline?: boolean; strikethrough?: boolean; /** Resolved run colour as a CSS colour string. */ color?: string; /** Run font size in points (`a:rPr@sz` / 100). */ fontSize?: number; /** Run font family from `a:rPr/a:latin@typeface` (or `a:ea` / `a:cs`). */ fontFamily?: string; } /** * Complete parsed table data for a {@link TablePptxElement}. * * Includes row/cell data, column widths, banding flags, and the applied * table style ID. * * @example * ```ts * const data: PptxTableData = { * rows: [ * { cells: [{ text: "Product" }, { text: "Revenue" }] }, * { cells: [{ text: "Widget A" }, { text: "$3.4M" }] }, * ], * columnWidths: [0.6, 0.4], * firstRowHeader: true, * bandedRows: true, * }; * // => satisfies PptxTableData * ``` */ declare interface PptxTableData { rows: PptxTableRow[]; /** Column widths as proportion of total (summing to 1). */ columnWidths: number[]; /** Whether the table has banded rows. */ bandedRows?: boolean; /** Whether the first row is a header. */ firstRowHeader?: boolean; /** Whether banded columns are enabled. */ bandedColumns?: boolean; /** Whether the last row is styled as a total row. */ lastRow?: boolean; /** Whether the first column is styled as a header column. */ firstCol?: boolean; /** Whether the last column is styled specially. */ lastCol?: boolean; /** Table style ID from `a:tblPr/a:tblStyle@val` or `a:tblPr@tblStyle`. */ tableStyleId?: string; /** Number of rows per banding group (default 1). */ bandRowCycle?: number; /** Number of columns per banding group (default 1). */ bandColCycle?: number; /** Right-to-left table layout from `a:tblPr/@rtl`. */ rtl?: boolean; /** * `a:tblPr`'s OWN fill (`CT_TableProperties` §21.1.3.15's * `EG_FillProperties`), independent of any `a:tblStyleLst`-referenced style * or that style's `a:tblBg`. Applied as the lowest-priority fill layer, * beneath the table style's `wholeTbl` fill. Real PowerPoint decks route * table appearance through `tableStyleId` instead, so this mainly matters * for non-PowerPoint authoring tools (issue G6). */ tableFill?: ParsedTableStyleFill; /** * `a:tblPr`'s own `a:effectLst` (or `a:effectDag`) effect chain, * independent of the referenced table style, decomposed into a typed * sequence of {@link ParsedTableStyleEffect} nodes (issue G6). Each node * keeps its own XML verbatim for lossless round-trip; empty array is * normalised to `undefined` by the parser so `tableEffects` is only ever * present when there is at least one effect. */ tableEffects?: ParsedTableStyleEffect[]; /** * Table-cell-context default text size in points, resolved from the * slide's master `p:otherStyle` (ECMA-376 §19.3.1.42 CT_TextListStyle, * §19.3.1.52 for `p:txStyles`). PowerPoint sizes a table cell's text off * this master default (commonly 18pt) whenever neither the run nor the * (size-less) table style provides one; without it, cell text without an * explicit `a:rPr@sz` fell back to the browser's own default font size * (16px / 12pt) instead. A render-only hint: it is not part of any * individual cell's parsed style and is never written back on save, so * resaving an unstyled cell does not bake in an explicit size that was * never authored. `undefined` when no master/otherStyle size resolves * (renderers should leave the browser default in place in that case). */ defaultCellFontSize?: number; } /** * A single table row with an optional height and an array of cells. * * @example * ```ts * const row: PptxTableRow = { * height: 40, * cells: [ * { text: "Name" }, * { text: "Score" }, * ], * }; * // => satisfies PptxTableRow * ``` */ declare interface PptxTableRow { /** Row height in px. */ height?: number; cells: PptxTableCell[]; } /** * A single name–value tag from `ppt/tags/*.xml`. * * @example * ```ts * const tag: PptxTag = { name: "CUSTOM_ID", value: "12345" }; * // => satisfies PptxTag * ``` */ declare interface PptxTag { name: string; value: string; } /** * A collection of tags from a single tags XML part. * * @example * ```ts * const coll: PptxTagCollection = { * path: "ppt/tags/tag1.xml", * tags: [{ name: "CUSTOM_ID", value: "12345" }], * }; * // => satisfies PptxTagCollection * ``` */ declare interface PptxTagCollection { /** File path within the PPTX archive. */ path?: string; /** Package owner of the tags relationship. New collections default to presentation. */ owner?: 'presentation' | 'slide' | 'part'; /** Source OPC part that owns the relationship, e.g. ppt/slides/slide1.xml. */ sourcePartPath?: string; /** Durable relationship identifier from the owning part. */ relationshipId?: string; /** Tags in this collection. */ tags: PptxTag[]; /** Parsed tag-list XML retained for unknown-node preservation. */ rawXml?: XmlObject; } /** Text-level animation target from `p:txEl`. */ declare interface PptxTextAnimationTarget { /** Target type: character range or paragraph range. */ type: 'charRg' | 'pRg'; /** Start index (0-based). */ start: number; /** End index (exclusive). */ end: number; } /** Build type for text build (paragraph/word/letter) animations from `p:bldP/@build`. */ declare type PptxTextBuildType = 'allAtOnce' | 'byParagraph' | 'byWord' | 'byChar'; /** * Text content mixin — present on text boxes and shapes. * * Shapes can contain text overlaid on the shape geometry, so both * `TextPptxElement` and `ShapePptxElement` extend this interface. * * @example * ```ts * const props: PptxTextProperties = { * text: "Hello World", * textStyle: { fontSize: 24, bold: true, color: "#333333" }, * }; * // => satisfies PptxTextProperties * ``` */ declare interface PptxTextProperties { text?: string; textStyle?: TextStyle; /** Rich text segments with individual styling. */ textSegments?: TextSegment[]; /** Per-paragraph indentation (marginLeft, indent) for multi-level bullet support. */ paragraphIndents?: Array<{ marginLeft?: number; indent?: number; }>; /** Placeholder prompt text inherited from layout/master (e.g. "Click to add title"). Shown as a greyed-out hint when the shape has no user-entered text. */ promptText?: string; /** * The string {@link text} was INHERITED from, when this is a header / footer / * date / slide-number placeholder whose own body the file leaves empty. * * PowerPoint keeps the footer string on the slide master and writes each * slide's copy of the `ftr` placeholder empty, so the empty body means * "render the master's footer here". Rendering needs the resolved string, but * SAVING it into the slide would pin that slide to today's master text and * silently detach it from the Header & Footer dialog. The save writer * therefore leaves the authored empty body alone while `text` still equals * this value, and writes a genuine per-slide override once it does not. */ inheritedPlaceholderText?: string; /** Linked text box chain ID from `a:bodyPr > a:linkedTxbx/@id` or `a:txbx > a:linkedTxbx/@id`. Text overflows from one linked frame to the next. */ linkedTxbxId?: number; /** Sequence number within a linked text box chain (0-based). */ linkedTxbxSeq?: number; } /** * Per-level paragraph properties for a text style category. * Each entry maps a 0-based level index to its style defaults. */ declare type PptxTextStyleLevels = Record; /** * Known OOXML preset text warp types (WordArt transforms). * * Falls back to `string` for unknown presets not yet catalogued. * * @example * ```ts * const warp: PptxTextWarpPreset = "textArchUp"; * // => "textArchUp" — one of: "textNoShape" | "textPlain" | "textStop" | "textArchUp" | … * ``` */ declare type PptxTextWarpPreset = 'textNoShape' | 'textPlain' | 'textStop' | 'textTriangle' | 'textTriangleInverted' | 'textChevron' | 'textChevronInverted' | 'textRingInside' | 'textRingOutside' | 'textArchUp' | 'textArchDown' | 'textCircle' | 'textButton' | 'textArchUpPour' | 'textArchDownPour' | 'textCirclePour' | 'textButtonPour' | 'textCurveUp' | 'textCurveDown' | 'textCanUp' | 'textCanDown' | 'textWave1' | 'textWave2' | 'textWave4' | 'textDoubleWave1' | 'textInflate' | 'textDeflate' | 'textInflateBottom' | 'textDeflateBottom' | 'textInflateTop' | 'textDeflateTop' | 'textFadeRight' | 'textFadeLeft' | 'textFadeUp' | 'textFadeDown' | 'textSlantUp' | 'textSlantDown' | 'textCascadeUp' | 'textCascadeDown' | 'textDeflateInflate' | 'textDeflateInflateDeflate' | string; /** * Full parsed theme object available to renderers. * * @example * ```ts * const theme: PptxTheme = { * name: "Office Theme", * colorScheme: { dk1: "#000", lt1: "#FFF", /* … *\/ }, * fontScheme: { * majorFont: { latin: "Calibri Light" }, * minorFont: { latin: "Calibri" }, * }, * }; * // => satisfies PptxTheme * ``` */ declare interface PptxTheme { /** Theme name from `a:theme @name`. */ name?: string; /** Resolved colour scheme. */ colorScheme?: PptxThemeColorScheme; /** Resolved font scheme. */ fontScheme?: PptxThemeFontScheme; /** Format scheme — fill, line, effect and background fill style matrices. */ formatScheme?: PptxThemeFormatScheme; } /** * A theme colour choice. Every transform is a 0..1 fraction of the OOXML * percentage (`lumMod val="20000"` is `lumMod: 0.2`), matching how the parser * reads them, and is applied in the order `a:schemeClr` children are written: * `tint`, `shade`, `lumMod`, `lumOff`, `alpha`. */ declare interface PptxThemeColorRef { scheme: PptxThemeColorSchemeName; /** `a:lumMod`: multiply HSL luminance (PowerPoint's "Lighter/Darker" rows). */ lumMod?: number; /** `a:lumOff`: add to HSL luminance after `lumMod` ("Lighter N%" rows). */ lumOff?: number; /** `a:tint`: blend towards white. */ tint?: number; /** `a:shade`: blend towards black. */ shade?: number; /** `a:alpha`: opacity fraction (1 = opaque). */ alpha?: number; } /** * Resolved hex values for the 12 theme colour slots. * * @example * ```ts * const scheme: PptxThemeColorScheme = { * dk1: "#000000", lt1: "#FFFFFF", * dk2: "#1F497D", lt2: "#EEECE1", * accent1: "#4F81BD", accent2: "#C0504D", * accent3: "#9BBB59", accent4: "#8064A2", * accent5: "#4BACC6", accent6: "#F79646", * hlink: "#0000FF", folHlink: "#800080", * }; * // => satisfies PptxThemeColorScheme * ``` */ declare interface PptxThemeColorScheme { dk1: string; lt1: string; dk2: string; lt2: string; accent1: string; accent2: string; accent3: string; accent4: string; accent5: string; accent6: string; hlink: string; folHlink: string; } /** * Theme colour references: the typed counterpart of ``. * * A colour picked from the theme palette is remembered as a scheme slot plus * PowerPoint's luminance variants rather than as the sRGB it currently * resolves to, so a later theme change re-colours the shape (and a saved file * keeps `` instead of a canonical ``). * * @module types/color-ref */ /** * The scheme slot names `a:schemeClr/@val` accepts (ECMA-376 `ST_SchemeColorIndex`). * `bg1`/`tx1`/`bg2`/`tx2` are the colour-map aliases a slide resolves through * `p:clrMap`; `phClr` is the placeholder colour used inside a theme's style * matrix and is never chosen from a picker. */ declare type PptxThemeColorSchemeName = 'dk1' | 'lt1' | 'dk2' | 'lt2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'bg1' | 'tx1' | 'bg2' | 'tx2' | 'phClr'; /** * A single effect style entry from `a:effectStyleLst`. * Each entry may define shadow, glow, soft-edge, reflection, blur, * and optionally a 3-D scene/shape. * * @example * ```ts * const dropShadow: PptxThemeEffectStyle = { * shadowColor: "#000000", * shadowBlur: 4, * shadowOffsetX: 2, * shadowOffsetY: 3, * shadowOpacity: 0.4, * }; * // => satisfies PptxThemeEffectStyle * ``` */ declare interface PptxThemeEffectStyle { shadowColor?: string; shadowBlur?: number; shadowOffsetX?: number; shadowOffsetY?: number; shadowOpacity?: number; glowColor?: string; glowRadius?: number; glowOpacity?: number; softEdgeRadius?: number; innerShadowColor?: string; innerShadowOpacity?: number; innerShadowBlur?: number; innerShadowOffsetX?: number; innerShadowOffsetY?: number; reflectionBlurRadius?: number; reflectionStartOpacity?: number; reflectionEndOpacity?: number; reflectionEndPosition?: number; reflectionDirection?: number; reflectionRotation?: number; reflectionDistance?: number; /** 3D scene/camera from `a:scene3d` on the effect style (idx 3 typically). */ scene3d?: Pptx3DScene; /** 3D shape extrusion/bevel from `a:sp3d` on the effect style (idx 3 typically). */ shape3d?: Pptx3DShape; /** Raw XML node preserved for `phClr` re-resolution. */ rawNode?: unknown; } /** * A single fill style entry from the theme format scheme. * Each entry is one of: solid, gradient, pattern, or no fill. * The raw XML node is also stored so that `phClr` substitution can happen * at resolution time. * * @example * ```ts * const solidFill: PptxThemeFillStyle = { * kind: "solid", * color: "#4F81BD", * opacity: 1, * }; * * const gradientFill: PptxThemeFillStyle = { * kind: "gradient", * gradientAngle: 90, * gradientType: "linear", * gradientStops: [ * { color: "#4F81BD", position: 0 }, * { color: "#1F497D", position: 1 }, * ], * }; * // => satisfies PptxThemeFillStyle * ``` */ declare interface PptxThemeFillStyle { /** * Discriminator for the fill type. * * `'group'` corresponds to `` — a fill that inherits the * containing group shape's fill at render time. Captured for round-trip * preservation in `fmtScheme/fillStyleLst`. */ kind: 'solid' | 'gradient' | 'pattern' | 'none' | 'group'; /** Pre-resolved colour (may be `undefined` when `phClr`-dependent). */ color?: string; opacity?: number; /** Gradient-specific fields (only present when `kind === "gradient"`). */ gradientStops?: Array<{ color: string; position: number; opacity?: number; }>; gradientAngle?: number; gradientType?: 'linear' | 'radial'; gradientCss?: string; /** Pattern-specific fields (only present when `kind === "pattern"`). */ patternPreset?: string; patternBackgroundColor?: string; /** Raw XML node preserved for `phClr` re-resolution. */ rawNode?: unknown; } /** * A font-family triplet for major or minor theme fonts. * * Supports Latin, East Asian, and Complex Script font families. * * @example * ```ts * const fonts: PptxThemeFontGroup = { * latin: "Calibri Light", * eastAsia: "MS PGothic", * complexScript: "Arial", * }; * // => satisfies PptxThemeFontGroup * ``` */ declare interface PptxThemeFontGroup { latin?: string; eastAsia?: string; complexScript?: string; /** * Per-script typeface overrides (`` per ECMA-376 §20.1.4.1.16). Keyed by * the four-letter ISO 15924 script tag from the `script` attribute. * * Phase 4 Stream A / M4. */ byScript?: Record; } /** * Theme font scheme — major (headings) and minor (body) font families. * * @example * ```ts * const scheme: PptxThemeFontScheme = { * majorFont: { latin: "Calibri Light" }, * minorFont: { latin: "Calibri", eastAsia: "MS PGothic" }, * }; * // => satisfies PptxThemeFontScheme * ``` */ declare interface PptxThemeFontScheme { majorFont?: PptxThemeFontGroup; minorFont?: PptxThemeFontGroup; } /** * The full parsed format scheme from `a:fmtScheme` inside `a:themeElements`. * Contains three fill style lists and one line/effect style list each, * at three intensity levels: subtle (idx 1), moderate (idx 2), intense (idx 3). * * OOXML reference indices: * - fillStyleLst: idx 1-3 (used by `a:fillRef @idx` 1-3) * - lnStyleLst: idx 1-3 (used by `a:lnRef @idx` 1-3) * - effectStyleLst: idx 1-3 (used by `a:effectRef @idx` 1-3) * - bgFillStyleLst: idx 1-3 (used by `a:fillRef @idx` 1001-1003) * * @example * ```ts * const fmt: PptxThemeFormatScheme = { * name: "Office", * fillStyles: [solidFill, gradientFill, intenseFill], * lineStyles: [thinLine, mediumLine, thickLine], * effectStyles: [subtle, moderate, intense], * backgroundFillStyles: [solidBg, gradientBg, intenseBg], * }; * // => satisfies PptxThemeFormatScheme * ``` */ declare interface PptxThemeFormatScheme { /** The `@name` attribute of the format scheme. */ name?: string; /** Fill styles at indices 1-3 (subtle, moderate, intense). */ fillStyles: PptxThemeFillStyle[]; /** Line styles at indices 1-3. */ lineStyles: PptxThemeLineStyle[]; /** Effect styles at indices 1-3. */ effectStyles: PptxThemeEffectStyle[]; /** Background fill styles at indices 1-3 (referenced via idx 1001-1003). */ backgroundFillStyles: PptxThemeFillStyle[]; } /** * A single line style entry from `a:lnStyleLst`. * Provides width, dash, join, cap, and optional fill colour. * * @example * ```ts * const line: PptxThemeLineStyle = { * width: 1.5, * color: "#4F81BD", * dash: "solid", * lineJoin: "round", * lineCap: "flat", * }; * // => satisfies PptxThemeLineStyle * ``` */ declare interface PptxThemeLineStyle { /** Line width in pixels (converted from EMU). */ width?: number; color?: string; opacity?: number; dash?: string; lineJoin?: 'round' | 'bevel' | 'miter'; lineCap?: 'flat' | 'rnd' | 'sq'; compoundLine?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri'; /** Raw XML node preserved for `phClr` re-resolution. */ rawNode?: unknown; } /** * A theme part available in the presentation package. * * @example * ```ts * const opt: PptxThemeOption = { * path: "ppt/theme/theme1.xml", * name: "Office Theme", * }; * // => satisfies PptxThemeOption * ``` */ declare interface PptxThemeOption { /** File path within the PPTX archive (e.g. `ppt/theme/theme2.xml`). */ path: string; /** Human-readable theme name from `a:theme/@name`, when present. */ name?: string; } /** * A complete theme preset that can be applied to a presentation. * * @example * ```ts * import { THEME_PRESETS } from "pptx-viewer-core"; * * const office = THEME_PRESETS.find(p => p.id === "office"); * await handler.switchTheme(office.colorScheme, office.fontScheme, office.name); * ``` */ declare interface PptxThemePreset { /** Unique identifier for the preset. */ id: string; /** Human-readable display name. */ name: string; /** The 12-colour scheme. */ colorScheme: PptxThemeColorScheme; /** Heading and body font families. */ fontScheme: PptxThemeFontScheme; } /** * A single `p:tmpl` timing template parsed from a TEXT `p:bldP/p:tmplLst` * (CT_TLTemplate, ECMA-376 §19.5.85; the list itself is CT_TLTemplateList, * §19.5.84). * * PowerPoint writes these as the timing PowerPoint would apply to a build * level that does not yet have an instantiated effect, so that promoting or * demoting an outline paragraph, or adding a new bullet at a level with no * prior animation, has a default to clone. They are not consulted at * playback: the animation actually shown for every paragraph level already * visible on the slide is the real, instantiated `p:tnLst` under * `p:timing/p:tnLst`, which the rest of this parser already models in full. * * The nested time-node tree under each template's own `p:tnLst` is kept as * a preserved `XmlObject` rather than deep-parsed into * {@link PptxNativeAnimation} records: it is schema-identical to the * top-level timing tree but scoped to a template that is never itself * executed, so structurally modelling it would stand up a second, unused * parallel animation model. Parsing stops at typed round-trip; see * `docs/guide/limitations.md`. */ declare interface PptxTimingTemplate { /** Build level this template targets, from `p:tmpl/@lvl` (ST_TLLevel, default 0). */ level: number; /** Preserved `p:tnLst` (CT_TimeNodeList) subtree, verbatim. */ timeNodeList: XmlObject; /** Preserved `p:tmpl` XML node (its attributes plus any unmodelled children). */ rawXml?: XmlObject; } /** Schema-defined `ST_TransitionSpeed` values. */ declare type PptxTransitionSpeed = 'slow' | 'med' | 'fast'; /** * Available slide transition effects. * * Maps to the OOXML child element names under `` / ``. * * @example * ```ts * const t: PptxTransitionType = "morph"; * // => "morph" — one of 40+ transition effects * ``` */ declare type PptxTransitionType = 'none' | 'cut' | 'fade' | 'push' | 'wipe' | 'split' | 'randomBar' | 'blinds' | 'checker' | 'circle' | 'comb' | 'cover' | 'diamond' | 'dissolve' | 'plus' | 'pull' | 'random' | 'strips' | 'uncover' | 'wedge' | 'wheel' | 'zoom' | 'newsflash' | 'morph' | 'conveyor' | 'doors' | 'ferris' | 'flash' | 'flythrough' | 'gallery' | 'glitter' | 'honeycomb' | 'pan' | 'prism' | 'reveal' | 'ripple' | 'shred' | 'switch' | 'vortex' | 'warp' | 'wheelReverse' | 'window' | 'cube' | 'flip' | 'rotate' | 'box' | 'orbit' | 'fallOver' | 'drape' | 'curtains' | 'wind' | 'prestige' | 'fracture' | 'crush' | 'peelOff' | 'pageCurlDouble' | 'pageCurlSingle' | 'airplane' | 'origami'; /** A horizontal or vertical drawing guide in slide coordinates. */ declare interface PptxViewGuide { orientation?: 'horz' | 'vert'; position?: number; } /** * Origin point for a view (x, y in twips or EMU). */ declare interface PptxViewOrigin { x: number; y: number; } /** * Full view properties from `ppt/viewProps.xml`. */ declare interface PptxViewProperties { /** Last used view type (`p:viewPr/@lastView`). */ lastView?: string; /** Whether comments are shown (`p:viewPr/@showComments`). */ showComments?: boolean; /** Normal view properties (splitter positions). */ normalViewPr?: PptxNormalViewProperties; /** Slide view properties. */ slideViewPr?: PptxCommonSlideViewProperties; /** Outline view properties. */ outlineViewPr?: PptxCommonSlideViewProperties; /** Notes text view properties. */ notesTextViewPr?: PptxCommonSlideViewProperties; /** Sorter view scale. */ sorterViewPr?: { scale?: PptxViewScale; }; /** Notes view properties. */ notesViewPr?: PptxCommonSlideViewProperties; /** Grid spacing in positive DrawingML coordinates. */ gridSpacing?: PptxGridSpacing; /** Raw XML preserved for lossless round-trip of unparsed attributes. */ rawXml?: Record; } /** * View properties types parsed from `ppt/viewProps.xml`. * * Models the `p:viewPr` element and its child views: * normalViewPr, slideViewPr, outlineViewPr, notesTextViewPr, * sorterViewPr, notesViewPr. * * @module pptx-types/view-properties */ /** * Scale factor for a view (numerator / denominator percentage). */ declare interface PptxViewScale { /** Numerator of the scale percentage (e.g. 100 for 100%). */ n: number; /** Denominator of the scale percentage (e.g. 100 for 100%). */ d: number; /** Optional independent vertical scale. When absent, the X scale is used. */ sy?: { n: number; d: number; }; } /** * Root builder of the fluent PPTX editing API. * * Wraps a {@link PptxData} object and provides chainable accessors * to navigate into slides, elements, and notes for in-place mutation. */ declare class PptxXmlBuilder implements IPptxXmlBuilder { /** The presentation data being mutated. */ private readonly data; /** @param data - The presentation data to wrap. */ constructor(data: PptxData); /** * Factory method to create a builder from presentation data. * @param data - The presentation data to wrap. * @returns A new {@link PptxXmlBuilder} instance. */ static from(data: PptxData): PptxXmlBuilder; /** @inheritdoc */ Slides(index: number): PptxSlideBuilder; /** * Navigate to a slide by zero-based index. * @param index - Zero-based slide index. * @returns A {@link PptxSlideBuilder} for the requested slide. * @throws Error if index is not an integer or is out of range. */ slide(index: number): PptxSlideBuilder; /** @inheritdoc */ slides(index: number): PptxSlideBuilder; /** Return the underlying {@link PptxData}. */ project(): PptxData; /** Pascal-case alias for {@link project}. */ Project(): PptxData; } /** Result returned by {@link PresentationBuilder.create}. */ declare interface PresentationBuilderResult { /** Initialized handler ready for editing and saving. */ handler: PptxHandler; /** Parsed presentation data. */ data: PptxData; /** Convenience slide builder factory. */ createSlide: (layoutName?: string) => SlideBuilder; } declare interface PresentationOptions { /** Slide width in EMU. Default: 12192000 (16:9 widescreen). */ width?: number; /** Slide height in EMU. Default: 6858000 (16:9 widescreen). */ height?: number; /** Theme configuration. */ theme?: PresentationThemeInput; /** Presentation title (stored in docProps/core.xml). */ title?: string; /** Presentation author. */ creator?: string; /** * Number of blank slides to include in the initial presentation. * Default: 0 (no slides). Slides use the "Blank" layout. */ initialSlideCount?: number; } declare interface PresentationThemeInput { name?: string; colors?: { dk1?: string; lt1?: string; dk2?: string; lt2?: string; accent1?: string; accent2?: string; accent3?: string; accent4?: string; accent5?: string; accent6?: string; hlink?: string; folHlink?: string; }; fonts?: { majorFont?: string; minorFont?: string; }; } /** Keys of an options group whose value is a primitive (not an array). */ declare type PrimitiveKeys = { [K in keyof T]: T[K] extends ViewerOptionPrimitive ? K : never; }[keyof T] & string; declare interface Props extends RibbonProps { } declare type QuickAccessPosition = 'above' | 'below'; /** * CSS `mask-image`/`-webkit-mask-image` value plus the raw `transform` for a * mirrored reflection sibling. Every value is a ready-to-apply CSS string (or * `'none'` sentinel avoided - fields are omitted when the browser default * already matches), so a binding can spread this directly onto its own style * object with no further per-framework logic. */ declare interface ReflectionWrapperStyle { position: 'absolute'; left: string; /** `calc(100% + px)`: sits `@dist` px below the source element's box. */ top: string; width: string; height: string; /** `scale(@sx, @sy)` (the sign of `@sy` IS the mirror) composed with `@kx`/`@ky`/`@rot`. */ transform: string; /** Anchor point for the transform above, from `@algn` (default `center top`). */ transformOrigin: string; maskImage: string; WebkitMaskImage: string; pointerEvents: 'none'; } /** * CollaborationCursors: presentational overlay that renders remote * collaborators' cursors above the slide canvas. * * This component is purely visual: it owns no network/Yjs logic. The * integrator supplies a reactive list of {@link RemoteCursor} entries (via the * collaboration composable). Each entry is drawn as an absolutely-positioned * pointer SVG plus a name-label chip in the user's colour, placed at `(x, y)`. * * `x`/`y` are *unscaled* slide coordinates (px) and are used as-is: the * overlay is mounted inside the scaled slide-stage host (like the local * selection overlay), so the stage's CSS `transform: scale()` applies the zoom * exactly once. Multiplying by zoom here as well would double-apply the scale * and misplace cursors at any zoom other than 100%. * * The overlay sets `pointer-events: none` so it never intercepts canvas input. */ /** A single remote collaborator's cursor, in unscaled slide coordinates. */ export declare interface RemoteCursor { /** Stable id for the remote client (awareness clientId or peer id). */ clientId: number | string; /** Display name shown in the label chip. */ userName: string; /** Cursor + chip colour (any CSS colour string). */ color: string; /** Unscaled slide-space X coordinate (px). */ x: number; /** Unscaled slide-space Y coordinate (px). */ y: number; /** Optional ids of elements this user has selected. */ selectionIds?: string[]; } /** * A remote peer's full presence: identity plus the live cursor, selection and * active slide they have published over awareness. */ export declare interface RemotePresence { clientId: number; userName: string; color: string; cursor?: { x: number; y: number; }; selectionIds: string[]; activeSlide: number; role?: CollaborationRole; } /** A single resolved remote selection box, in unscaled slide coordinates. */ export declare interface RemoteSelectionBox { /** Stable key (peer clientId + element id). */ key: string; /** Id of the outlined element (framework-neutral e2e contract). */ elementId: string; /** Peer display name shown in the label chip. */ userName: string; /** Outline + chip colour. */ color: string; /** Unscaled slide-space geometry of the selected element. */ x: number; y: number; width: number; height: number; } export declare const RemoteSelectionOverlay: typeof __VLS_export_19; /** A rendered paragraph: runs plus resolved bullet + hanging-indent metadata. */ declare interface RenderParagraph { runs: ParagraphRun[]; /** Bullet glyph / number to render before the runs (or `undefined`). */ bulletMarker?: string; /** Picture marker rendered before runs, or fallback metadata when unresolved. */ bulletPicture?: PictureBulletMarker; /** Inline style for the bullet marker (font / size / colour). */ bulletStyle: RunStyle; /** `margin-left` in px for the whole paragraph (hanging-indent layout). */ marginLeftPx?: number; /** `text-indent` in px (first-line / hanging indent). */ textIndentPx?: number; /** * Per-paragraph `line-height` from this paragraph's own `a:pPr > a:lnSpc`. * A unitless multiplier for proportional spacing (`a:spcPct`) or a `"pt"` * string for exact spacing (`a:spcPts`). Undefined when the paragraph does * not override spacing (binding keeps the body-level line-height). */ lineHeight?: number | string; /** `margin-top` in px from this paragraph's `a:pPr > a:spcBef` (space before). */ spaceBeforePx?: number; /** `margin-bottom` in px from this paragraph's `a:pPr > a:spcAft` (space after). */ spaceAfterPx?: number; /** * `font-size` in px to set on the paragraph element so its CSS line boxes * are built from its OWN runs rather than the text body's default size. * Undefined when the paragraph already matches the body default. * * See `resolveParagraphStrutFontSize` for why this is needed: without it a * paragraph of small runs inside a larger-defaulting body is laid out on * too-tall lines and overflows its shape. */ strutFontSizePx?: number; /** * True when the paragraph has no runs and no bullet: an authored blank line * (``). * * PowerPoint gives such a paragraph a full line box, which is how decks * space a heading away from the bullet list under it. A binding must render * something with height for it (a `
`), or the gap disappears and the * block reads as one dense run of text (issue #131, slides 13-14). */ isEmpty?: boolean; /** * Indices of this paragraph's segments in the rendered segment list (the * override list when one was supplied), in authored order and INCLUDING the * bullet-marker segment the runs drop. * * The seam a binding uses to reach paragraph facts the neutral model does not * carry, without regrouping the segments itself and drifting from the * grouping here - which is exactly how React ended up splitting on every * `"\n"` and treating a soft `a:br` as a paragraph break. */ segmentIndices: number[]; /** * True when this paragraph resolves right-to-left (`a:pPr/@rtl`, or the text * body's default). A binding that mirrors its hanging indent for RTL reads * this; the direction itself is already in {@link paragraphStyle}. */ rtl?: boolean; /** * Extra CSS for the paragraph box, beyond the margin / indent / spacing * fields above: this paragraph's own `text-align` (`a:pPr/@algn`), its BiDi * `direction`, and the kinsoku line-breaking rules (`@eaLnBrk`, * `@latinLnBrk`, `@hangingPunct`). Absent when the paragraph overrides none * of them, which is the common case. * * All three used to be resolved in React's private paragraph renderer only, * so a deck that centred one paragraph of a left-aligned body, or set CJK * break rules, rendered differently in the other four bindings. */ paragraphStyle?: RunStyle; /** * `@hangingPunct` / `@eaLnBrk="0"` as resolved for this paragraph. The runs * above already carry their pieces; React, which rebuilds each segment's * pieces inside one span, re-applies `splitEastAsianBreaks` from this. */ eastAsianBreaks?: EastAsianBreakOptions; } declare type Resolvable = T | (() => T | Promise); /** * The result of resolving a `` block against the loaded theme. * * `shapeStyle` is exactly what the load pipeline would have produced for a * shape whose `spPr` authors nothing and whose `` is `styleXml`: * the flat fill/outline/effect values a renderer needs, the reference indices * and colours the writer re-emits, and the inheritance baselines that tell the * writer to leave `spPr` empty while the flat values still agree with them. */ declare interface ResolvedStyleMatrix { shapeStyle: ShapeStyle; /** The text colour `` names, resolved to hex. */ fontColor?: string; } declare const RIBBON_CONTROL_CATALOG: { readonly home: { readonly clipboard: { readonly label: 'Clipboard'; readonly controls: { readonly paste: 'Paste'; readonly cut: 'Cut'; readonly copy: 'Copy'; readonly formatPainter: 'Format Painter'; }; }; readonly slides: { readonly label: 'Slides'; readonly controls: { readonly newSlide: 'New Slide'; readonly layout: 'Layout'; readonly reset: 'Reset'; readonly section: 'Section'; readonly slideTemplates: 'Slide templates'; }; }; readonly font: { readonly label: 'Font'; readonly controls: { readonly fontFamily: 'Font'; readonly fontSize: 'Font Size'; readonly increaseFontSize: 'Increase Font Size'; readonly decreaseFontSize: 'Decrease Font Size'; readonly clearFormatting: 'Clear All Formatting'; readonly bold: 'Bold'; readonly italic: 'Italic'; readonly underline: 'Underline'; readonly strikethrough: 'Strikethrough'; readonly shadow: 'Text Shadow'; readonly characterSpacing: 'Character Spacing'; readonly changeCase: 'Change Case'; readonly fontColor: 'Font Color'; readonly highlightColor: 'Text Highlight Color'; readonly superscript: 'Superscript'; readonly subscript: 'Subscript'; }; }; readonly paragraph: { readonly label: 'Paragraph'; readonly controls: { readonly bullets: 'Bullets (toggle and gallery)'; readonly numbering: 'Numbering (toggle and gallery)'; readonly decreaseIndent: 'Decrease List Level'; readonly increaseIndent: 'Increase List Level'; readonly lineSpacing: 'Line Spacing'; readonly alignLeft: 'Align Left'; readonly alignCenter: 'Center'; readonly alignRight: 'Align Right'; readonly justify: 'Justify'; readonly columns: 'Columns'; readonly textDirection: 'Text Direction'; readonly alignText: 'Align Text'; }; }; readonly drawing: { readonly label: 'Drawing'; readonly controls: { readonly shapes: 'Shapes'; readonly arrange: 'Arrange'; readonly quickStyles: 'Quick Styles (Shape Styles gallery)'; readonly shapeFill: 'Shape Fill'; readonly shapeOutline: 'Shape Outline'; readonly shapeEffects: 'Shape Effects gallery'; }; }; readonly arrange: { readonly label: 'Arrange'; readonly controls: { readonly bringForward: 'Bring Forward'; readonly sendBackward: 'Send Backward'; readonly bringToFront: 'Bring to Front'; readonly sendToBack: 'Send to Back'; readonly flipHorizontal: 'Flip Horizontal'; readonly flipVertical: 'Flip Vertical'; readonly duplicate: 'Duplicate'; readonly delete: 'Delete'; readonly group: 'Group'; readonly ungroup: 'Ungroup'; readonly align: 'Align'; readonly mergeShapes: 'Merge Shapes'; readonly crop: 'Crop'; readonly outlineWidth: 'Outline width'; }; }; readonly editing: { readonly label: 'Editing'; readonly controls: { readonly find: 'Find'; readonly replace: 'Replace'; readonly select: 'Select'; }; }; }; readonly insert: { readonly slides: { readonly label: 'Slides'; readonly controls: { readonly newSlide: 'New Slide'; }; }; readonly tables: { readonly label: 'Tables'; readonly controls: { readonly table: 'Table'; }; }; readonly images: { readonly label: 'Images'; readonly controls: { readonly pictures: 'Pictures'; }; }; readonly illustrations: { readonly label: 'Illustrations'; readonly controls: { readonly shapes: 'Shapes'; readonly smartArt: 'SmartArt'; readonly chart: 'Chart'; }; }; readonly links: { readonly label: 'Links'; readonly controls: { readonly link: 'Link'; readonly action: 'Action button'; }; }; readonly comments: { readonly label: 'Comments'; readonly controls: { readonly comment: 'Comment'; }; }; readonly text: { readonly label: 'Text'; readonly controls: { readonly textBox: 'Text Box'; readonly field: 'Header, date, slide number field'; }; }; readonly symbols: { readonly label: 'Symbols'; readonly controls: { readonly equation: 'Equation'; readonly symbol: 'Symbol'; }; }; readonly media: { readonly label: 'Media'; readonly controls: { readonly media: 'Video / Audio'; }; }; }; readonly draw: { readonly tools: { readonly label: 'Drawing Tools'; readonly controls: { readonly select: 'Select'; readonly pen: 'Pen'; readonly highlighter: 'Highlighter'; readonly eraser: 'Eraser'; readonly penColor: 'Pen colour'; readonly penWidth: 'Pen width'; }; }; readonly convert: { readonly label: 'Convert'; readonly controls: { readonly inkToShape: 'Ink to Shape'; }; }; }; readonly design: { readonly themes: { readonly label: 'Themes'; readonly controls: { readonly browseThemes: 'Themes gallery'; readonly editTheme: 'Edit theme'; }; }; readonly variants: { readonly label: 'Variants'; readonly controls: { readonly colors: 'Variants: Colors gallery'; readonly fonts: 'Variants: Fonts gallery'; }; }; readonly customize: { readonly label: 'Customize'; readonly controls: { readonly slideSize: 'Slide Size'; readonly formatBackground: 'Format Background'; }; }; }; readonly transitions: { readonly preview: { readonly label: 'Preview'; readonly controls: { readonly preview: 'Preview'; }; }; readonly transitionToThisSlide: { readonly label: 'Transition to This Slide'; readonly controls: { readonly gallery: 'Transition gallery'; readonly effectOptions: 'Effect Options'; }; }; readonly timing: { readonly label: 'Timing'; readonly controls: { readonly sound: 'Sound'; readonly duration: 'Duration'; readonly applyToAll: 'Apply To All'; readonly advanceOnClick: 'On Mouse Click'; readonly advanceAfter: 'After'; }; }; }; readonly animations: { readonly preview: { readonly label: 'Preview'; readonly controls: { readonly preview: 'Preview'; }; }; readonly animation: { readonly label: 'Animation'; readonly controls: { readonly gallery: 'Animation gallery'; readonly effectOptions: 'Effect Options'; }; }; readonly motionPath: { readonly label: 'Motion Paths'; readonly controls: { readonly gallery: 'Motion path gallery'; }; }; readonly advancedAnimation: { readonly label: 'Advanced Animation'; readonly controls: { readonly addAnimation: 'Add Animation'; readonly animationPane: 'Animation Pane'; readonly trigger: 'Trigger'; readonly animationPainter: 'Animation Painter'; readonly remove: 'Remove animation'; }; }; readonly timing: { readonly label: 'Timing'; readonly controls: { readonly start: 'Start'; readonly duration: 'Duration'; readonly delay: 'Delay'; readonly reorder: 'Reorder'; }; }; }; readonly slideShow: { readonly startSlideShow: { readonly label: 'Start Slide Show'; readonly controls: { readonly fromBeginning: 'From Beginning'; readonly fromCurrent: 'From Current Slide'; readonly customShow: 'Custom Slide Show'; }; }; readonly present: { readonly label: 'Present'; readonly controls: { readonly presenterView: 'Presenter View'; readonly broadcast: 'Present Online'; }; }; readonly setUp: { readonly label: 'Set Up'; readonly controls: { readonly setUpSlideShow: 'Set Up Slide Show'; readonly hideSlide: 'Hide Slide'; readonly rehearseTimings: 'Rehearse Timings'; readonly record: 'Record'; readonly rehearseWithCoach: 'Rehearse with Coach'; }; }; readonly captions: { readonly label: 'Captions & Subtitles'; readonly controls: { readonly subtitles: 'Always Use Subtitles'; readonly subtitleSettings: 'Subtitle Settings'; }; }; }; readonly record: { readonly camera: { readonly label: 'Camera'; readonly controls: { readonly cameo: 'Cameo'; }; }; readonly record: { readonly label: 'Record'; readonly controls: { readonly fromBeginning: 'From Beginning'; readonly fromCurrent: 'From Current Slide'; }; }; readonly manage: { readonly label: 'Manage'; readonly controls: { readonly clear: 'Clear'; readonly reset: 'Reset to Cameo'; }; }; readonly help: { readonly label: 'Help'; readonly controls: { readonly learnMore: 'Learn more'; }; }; }; readonly review: { readonly proofing: { readonly label: 'Proofing'; readonly controls: { readonly spelling: 'Spelling'; readonly thesaurus: 'Thesaurus'; }; }; readonly accessibility: { readonly label: 'Accessibility'; readonly controls: { readonly check: 'Check Accessibility'; }; }; readonly language: { readonly label: 'Language'; readonly controls: { readonly translate: 'Translate'; }; }; readonly comments: { readonly label: 'Comments'; readonly controls: { readonly newComment: 'New Comment'; readonly delete: 'Delete'; readonly previous: 'Previous'; readonly next: 'Next'; readonly showComments: 'Show Comments'; }; }; readonly compare: { readonly label: 'Compare'; readonly controls: { readonly compare: 'Compare'; readonly markAllRead: 'Mark all read'; }; }; readonly protect: { readonly label: 'Protect'; readonly controls: { readonly readOnly: 'Read-only'; readonly restrictPermission: 'Restrict Permission'; }; }; readonly ink: { readonly label: 'Ink'; readonly controls: { readonly hideInk: 'Hide Ink'; }; }; }; readonly view: { readonly presentationViews: { readonly label: 'Presentation Views'; readonly controls: { readonly normal: 'Normal'; readonly outline: 'Outline View'; readonly slideSorter: 'Slide Sorter'; readonly notesPage: 'Notes Page'; readonly readingView: 'Reading View'; }; }; readonly masterViews: { readonly label: 'Master Views'; readonly controls: { readonly slideMaster: 'Slide Master'; readonly handoutMaster: 'Handout Master'; readonly notesMaster: 'Notes Master'; }; }; readonly show: { readonly label: 'Show'; readonly controls: { readonly ruler: 'Ruler'; readonly gridlines: 'Gridlines'; readonly guides: 'Guides'; readonly snapToGrid: 'Snap to Grid'; readonly snapToShape: 'Snap to Shape'; readonly addGuide: 'Add horizontal / vertical guide'; readonly selectionPane: 'Selection Pane'; readonly eyedropper: 'Eyedropper'; readonly notes: 'Notes'; }; }; readonly zoom: { readonly label: 'Zoom'; readonly controls: { readonly zoom: 'Zoom'; readonly fitToWindow: 'Fit to Window'; }; }; readonly window: { readonly label: 'Window'; readonly controls: { readonly templateEditing: 'Edit template elements'; readonly macros: 'Macros'; }; }; }; readonly help: { readonly help: { readonly label: 'Help'; readonly controls: { readonly options: 'Options'; readonly keyboardShortcuts: 'Keyboard shortcuts'; readonly accessibility: 'Accessibility checker'; }; }; }; readonly shapeFormat: { readonly shapeStyles: { readonly label: 'Shape Styles'; readonly controls: { readonly gallery: 'Shape Styles gallery'; readonly shapeEffects: 'Shape Effects gallery'; }; }; readonly wordArtStyles: { readonly label: 'WordArt Styles'; readonly controls: { readonly gallery: 'WordArt Styles gallery'; }; }; }; readonly pictureFormat: { readonly pictureStyles: { readonly label: 'Picture Styles'; readonly controls: { readonly gallery: 'Picture Styles gallery'; readonly pictureEffects: 'Picture Effects gallery'; }; }; }; readonly tableDesign: { readonly tableStyles: { readonly label: 'Table Styles'; readonly controls: { readonly gallery: 'Table Styles gallery'; }; }; }; readonly chartDesign: { readonly chartLayouts: { readonly label: 'Chart Layouts'; readonly controls: { readonly quickLayout: 'Quick Layout gallery'; }; }; readonly chartStyles: { readonly label: 'Chart Styles'; readonly controls: { readonly changeColors: 'Change Colors gallery'; readonly gallery: 'Chart Styles gallery'; }; }; }; readonly smartArtDesign: { readonly smartArtStyles: { readonly label: 'SmartArt Styles'; readonly controls: { readonly changeColors: 'Change Colors gallery'; readonly gallery: 'SmartArt Styles gallery'; }; }; }; }; /** * PowerPoint's contextual tabs: they join the tab row only while the * selection is of their kind (see `contextualTabsForElement` in * `ribbon-galleries/`). Kept apart from `ToolbarTabId` because they are not * part of the fixed tab order every binding renders. */ declare type RibbonContextualTabId = 'shapeFormat' | 'pictureFormat' | 'tableDesign' | 'chartDesign' | 'smartArtDesign'; /** `..`, for example `home.font.bold`. */ declare type RibbonControlId = { [T in keyof Catalog]: { [G in keyof Catalog[T]]: Catalog[T][G] extends { controls: infer C; } ? `${T & string}.${G & string}.${keyof C & string}` : never; }[keyof Catalog[T]]; }[keyof Catalog]; /** Ribbon and toolbar customisation. */ declare interface RibbonCustomization { /** * Ribbon tabs to remove (the File tab included, unlike Customize Ribbon), * and contextual tabs (`shapeFormat`, `pictureFormat`, ...) that should * never appear. */ hiddenTabs?: readonly (ToolbarTabId | RibbonContextualTabId)[]; /** Groups inside a tab to remove, as `.` (`home.font`). */ hiddenGroups?: readonly RibbonGroupId[]; /** * Controls to remove: a top-level toolbar button / control cluster * (`share`, `zoom`, ...) or any ribbon control as * `..` (`home.font.bold`). */ hiddenButtons?: readonly (ToolbarButtonId | RibbonControlId)[]; } /** `.`, for example `home.font`. */ declare type RibbonGroupId = { [T in keyof Catalog]: { [G in keyof Catalog[T]]: `${T & string}.${G & string}`; }[keyof Catalog[T]]; }[keyof Catalog]; /** * Aggregate ribbon contract (state + callbacks). Mirrors React `ToolbarProps`. * The shell (`RibbonToolbar.vue`) passes the relevant subset to each section. */ export declare interface RibbonProps { fileName?: string; mode: ViewerMode_2; canEdit: boolean; isNarrowViewport: boolean; isSidebarCollapsed: boolean; isInspectorPaneOpen: boolean; isCompactToolbarOpen: boolean; toolbarSection: ToolbarSection; scale: number; canUndo: boolean; canRedo: boolean; undoLabel?: string; redoLabel?: string; findReplaceOpen: boolean; selectedElement: PptxElement | null; /** How many elements the multi-select holds; Group needs two. */ selectedCount: number; /** Whether every selected element allows `a:spLocks/@noGrp` grouping. */ selectionGroupable: boolean; tableEditorState?: TableCellEditorState | null; editTemplateMode: boolean; newShapeType: SupportedShapeType; activeTool: DrawingTool; drawingColor: string; drawingWidth: number; clipboardPayload: ElementClipboardPayload | null; spellCheckEnabled: boolean; showGrid: boolean; showRulers: boolean; /** * Guide-overlay visibility. Separate from `snapToShape`: hiding the guides * must not stop the editor snapping, and the guides stay in the model either * way so snapping and save still see the full list. */ showGuides: boolean; snapToGrid: boolean; snapToShape: boolean; isOverflowMenuOpen: boolean; layoutOptions: LayoutOption[]; /** `layoutPath` of the active slide, marking the current gallery tile. */ currentLayoutPath?: string; /** Builds the New Slide / Layout gallery artwork on first menu open. */ loadLayoutPreviews?: () => Promise; /** Theme major/minor latin faces, leading the font dropdown. */ themeFonts?: { heading?: string; body?: string; }; /** Families the deck embeds, offered as their own dropdown group. */ embeddedFontFamilies?: readonly string[]; /** Families registered this session via File > Options > Fonts. */ customFontFamilies?: readonly string[]; customShows: PptxCustomShow[]; activeCustomShowId: string | null; isCurrentSlideInActiveShow: boolean; hasMacros: boolean; isThemeEditorOpen: boolean; isThemeGalleryOpen: boolean; isCommentsPanelOpen?: boolean; slideCommentCount?: number; formatPainterActive?: boolean; canActivateFormatPainter?: boolean; isSelectionPaneOpen?: boolean; eyedropperActive?: boolean; showSubtitles?: boolean; activeSlide?: PptxSlide; /** True when a collaboration session is connected (Share button turns green). */ isCollaborating?: boolean; /** Connected collaborator count, shown on the Share button while collaborating. */ collaboratorCount?: number; /** Toolbar buttons / ribbon tabs the host has asked to hide. Undefined/empty hides nothing. */ hiddenActions?: ToolbarActionId[]; /** File > Options > Advanced > "Quickly access this number of Recent Documents". */ recentPresentationsCount?: number; /** True when the host opted into the AI assistant (the `ai` prop is set). */ aiEnabled?: boolean; /** Whether the AI chat panel is currently open (drives the toggle's active state). */ isAiPanelOpen?: boolean; /** Toggle the AI chat panel open/closed. */ onToggleAiPanel?: () => void; onSetMode: (mode: ViewerMode_2) => void; /** Slide Show > Start > From Beginning: the show's first slide, unconditionally. */ onPresentFromBeginning: () => void; onToggleSidebar: () => void; onToggleInspector: () => void; onOpenAnimationPanel: () => void; /** `motionPath` carries a motion-path catalogue id in `preset`, not a preset name. */ onAddAnimation?: (preset: string, group: AnimationApplyGroup) => void; onRemoveAnimation?: () => void; onToggleCompactToolbar: () => void; onSetToolbarSection: (section: ToolbarSection) => void; onZoomIn: () => void; onZoomOut: () => void; onZoomToFit: () => void; onUndo: () => void; onRedo: () => void; onToggleFindReplace: () => void; onSelectAll?: () => void; onSetNewShapeType: (type: SupportedShapeType) => void; onAddTextBox: () => void; onAddShape: () => void; onAddTable: () => void; onAddChart?: (chartKind: InsertChartKind) => void; onAddSmartArt: () => void; onAddEquation: () => void; onAddActionButton: (shapeType: string) => void; onInsertField?: (fieldType: string, value?: string) => void; onOpenHeaderFooter?: () => void; onOpenImagePicker: () => void; onOpenMediaPicker: () => void; onSetActiveTool: (tool: DrawingTool) => void; onSetDrawingColor: (color: string) => void; onSetDrawingWidth: (width: number) => void; onSetEditTemplateMode: (mode: boolean) => void; onSetSpellCheckEnabled: (enabled: boolean) => void; onSetShowGrid: (enabled: boolean) => void; onSetShowRulers: (enabled: boolean) => void; onSetShowGuides: (enabled: boolean) => void; onSetSnapToGrid: (enabled: boolean) => void; onSetSnapToShape: (enabled: boolean) => void; onAddGuide: (axis: 'h' | 'v') => void; onAlignElements: (align: string) => void; onDistributeElements: (axis: string) => void; canDistribute: boolean; onCopy: () => void; onCut: () => void; onPaste: () => void; onFlip: (direction: 'horizontal' | 'vertical') => void; onMoveLayer: (direction: string) => void; onMoveLayerToEdge: (direction: string) => void; onGroupElements: () => void; onUngroupElement: () => void; /** Patch the selection's `shapeStyle` (the Arrange group's outline width). */ onUpdateElementStyle: (updates: Partial) => void; /** Open the hyperlink editor for the selection (Insert > Link). */ onOpenHyperlinkDialog: () => void; onDuplicate: () => void; onDelete: () => void; /** Open another presentation (File ▸ Open). Hidden when not provided. */ onOpenFile?: () => void; onOpenRecentFile?: (key: string) => void; onCreatePresentation: (templateId: string) => void; onExportPng: () => void; onExportPdf: () => void; onExportVideo: () => void; onExportGif: () => void; /** Serialise the deck to pptx-viewer-json and download it (Export page card). */ onExportJson: () => void; onOpenShareDialog?: () => void; onSaveAsPptx: () => void; onSaveAsPpsx: () => void; onSaveAsPptm: () => void; onSaveAsPpt: () => void; onCopySlideAsImage: () => void; onPrint: () => void; onToggleShortcuts: () => void; onOpenSettings?: () => void; onRunAccessibilityCheck: () => void; onToggleSlideSorter: () => void; /** * View > Normal: leave whichever alternate view (slide sorter, reading, * outline, master) is open and return to the ordinary editing canvas. */ onGoToNormalView?: () => void; /** Open the windowed Reading View (NOT the fullscreen slide show). */ onOpenReadingView: () => void; /** Enter PowerPoint's Outline view: the deck as editable indented text. */ onOpenOutlineView: () => void; onUpdateTextStyle: (updates: Partial) => void; /** Rewrite the selected text's characters (PowerPoint's Aa "Change Case" dropdown). */ onTransformTextCase: (mode: ChangeCaseMode) => void; onSetOverflowMenuOpen: (open: boolean) => void; onInsertSlideFromLayout: (path: string, name?: string) => void; /** Insert a pre-designed slide template after the active slide (Home ▸ Slide Templates). */ onInsertSlideFromTemplate?: (templateId: SlideTemplateId) => void; /** Deck scheme map so template gallery previews show the deck's theme colours. */ templateScheme?: Record; onApplyLayout?: (path: string) => void; onResetSlide?: () => void; onAddSection?: () => void; onSetActiveCustomShowId: (id: string | null) => void; onCreateCustomShow: () => void; onRenameActiveCustomShow: () => void; onDeleteActiveCustomShow: () => void; onToggleCurrentSlideInActiveShow: () => void; onToggleVersionHistory?: () => void; onOpenPasswordProtection?: () => void; onOpenDocumentProperties?: () => void; /** Design > Slide Size: reveal the inspector card that owns the size. */ onOpenSlideSize?: () => void; onOpenFontEmbedding?: () => void; onOpenDigitalSignatures?: () => void; onEnterMasterView: () => void; onCloseMasterView: () => void; onEnterPresenterView?: () => void; onEnterRehearsalMode?: () => void; onToggleThemeEditor: () => void; onToggleThemeGallery: () => void; onCompare?: () => void; onToggleComments?: () => void; onToggleFormatPainter?: () => void; onToggleSelectionPane?: () => void; onToggleEyedropper?: () => void; onOpenSetUpSlideShow?: () => void; /** PowerPoint's Hide Slide toggle for the active slide (Slide Show tab). */ onToggleHideSlide?: () => void; /** Whether the active slide is hidden, for Hide Slide's pressed state. */ activeSlideHidden?: boolean; onOpenBroadcastDialog?: () => void; onToggleSubtitles?: () => void; onTransitionChange: (updates: Partial) => void; onApplyTransitionToAll: () => void; /** Deck presentation properties backing the Slide Show tab's Options checkboxes. */ presentationProperties?: PptxPresentationProperties; /** Commit an Options checkbox onto the deck's presentation properties. */ onPresentationPropertiesChange?: (updates: Partial) => void; } export declare const RibbonToolbar: typeof __VLS_export_21; /** The unit system used for ruler display. */ declare type RulerUnit = 'inches' | 'centimetres'; /** An inline equation run (`m:oMath`), rendered as MathML rather than text. */ declare interface RunEquation { /** The raw OMML node, for `convertOmmlToMathMl`. */ xml: Record; /** Display number for a numbered equation, without its parentheses. */ number?: string; } /** A run's resolved hyperlink target. */ declare interface RunHyperlink { /** * The URL to hand a click handler. For an internal `ppaction://hlinksldjump` * the resolved slide index is appended as a `slideIndex` query parameter, so * the target survives a callback whose only argument is the URL (see * `parsePpactionUrl`, which reads it back off). */ url: string; /** * A safe, renderable `href` for a plain ``, or `undefined` when the target * is an internal `ppaction://` action or fails the URL safety check. A * binding with no click handler renders the run as text in that case, which * is what every binding did for every link before this field existed. */ href?: string; /** `a:hlinkClick/@tooltip`, for the anchor's `title`. */ tooltip?: string; /** * `` for a real (non-`ppaction://`) hyperlink, from * `a:hlinkClick/@tgtFrame` when authored, else `_blank` (every binding's * pre-existing hardcoded default). Only meaningful alongside {@link href}. */ target?: string; /** `` paired with {@link target} (see `resolveHyperlinkTargetAttrs`). */ rel?: string; /** Resolved target slide for an internal slide jump. */ targetSlideIndex?: number; /** * True when the target came from `a:hlinkMouseOver` rather than * `a:hlinkClick`: PowerPoint follows it on hover, not on click, so a binding * that renders a plain anchor should not make it look clickable. */ onHover?: boolean; } /** A run's phonetic guide, ready to render as `` above the base text. */ declare interface RunRuby { /** The annotation itself (`a:ruby/a:rt`), e.g. the furigana reading. */ text: string; /** Inline style for the `` element (size, family, alignment, colour). */ style: RunStyle; } /** A plain CSS style map (keys are CSS properties; binding-agnostic). */ declare type RunStyle = Record; /** * Presence data for a remote collaborator, sanitised from the awareness * protocol. Returned by {@link sanitizePresence}; coordinates are in unscaled * slide pixels, clamped to the supplied canvas bounds. */ export declare interface SanitizedPresence { clientId: number; userName: string; userAvatar?: string; userColor: string; activeSlideIndex: number; cursorX: number; cursorY: number; lastUpdated: string; selectedElementId?: string; role?: CollaborationRole; } /** * Full PowerPoint "File > Options" parity model. * * Groups mirror the ten categories of PowerPoint's Options dialog. Values are * flat primitives per group so the dialog panes can be rendered generically * from `VIEWER_OPTIONS_SCHEMA` in every binding. The legacy six-toggle * `ViewerPreferences` surface stays supported via the mapping helpers below. */ declare type ScreenTipStyle = 'descriptions' | 'plain' | 'off'; /** One script-tagged piece of a run's text, ready for a binding's nested span. */ declare interface ScriptFontPiece { text: string; /** * CSS for a nested span wrapping `text`, or `undefined` when this piece * needs no span at all (its script's font equals the run's own, so plain * text renders identically). When present it carries the `fontFamily` * override plus the run's own decoration subset, repeated because * `text-decoration-*` does not inherit into a nested span (see * `nestedTextDecorationStyle`). */ style?: RunStyle; } export declare const SelectionOverlay: typeof __VLS_export_17; /** * Shadow effect properties for a single shadow layer. * * Represents parsed values from an `` node. Multiple instances * can be stored in {@link ShapeStyle.shadows} for compound shadow effects. * * @example * ```ts * const shadow: ShadowEffect = { * color: "#000000", * opacity: 0.4, * blur: 6, * angle: 315, * distance: 4, * }; * // => { color: "#000000", opacity: 0.4, blur: 6, angle: 315, distance: 4 } satisfies ShadowEffect * ``` */ declare interface ShadowEffect { /** Shadow color as hex string. */ color: string; /** Shadow opacity (0-1). */ opacity: number; /** Blur radius in pixels. */ blur: number; /** Shadow angle in degrees (0-360). */ angle: number; /** Shadow distance in pixels. */ distance: number; /** Whether shadow rotates with shape. */ rotateWithShape?: boolean; } declare interface ShadowInput { color?: string; blur?: number; offsetX?: number; offsetY?: number; opacity?: number; } declare interface ShapeOptions extends Partial { fill?: FillInput; stroke?: StrokeInput; text?: string; textStyle?: Partial; adjustments?: Record; shadow?: ShadowInput; opacity?: number; } /** * A shape — may contain text and custom geometry (preset or freeform). * * @example * ```ts * const rect: ShapePptxElement = { * type: "shape", * id: "shp_1", x: 100, y: 200, width: 300, height: 150, * shapeType: "roundRect", * shapeStyle: { fillColor: "#00AA55" }, * text: "OK", * }; * // => satisfies ShapePptxElement * ``` */ declare interface ShapePptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxCustomPathProperties, PptxAccessibilityProperties, PptxNonVisualDescription { type: 'shape'; } /** * Comprehensive visual style for a shape, connector, or image element. * * All fields are optional. When absent, the element inherits from theme * or layout defaults. The interface models both simple styling (solid fill + * basic stroke) and advanced effects (multiple shadow layers, gradient * fills, 3-D extrusion). * * @example * ```ts * // Simple blue filled shape with a thin black outline: * const simple: ShapeStyle = { * fillColor: "#0055AA", * fillMode: "solid", * strokeColor: "#000000", * strokeWidth: 1, * }; * * // Gradient fill with a soft shadow: * const fancy: ShapeStyle = { * fillMode: "gradient", * fillGradientType: "linear", * fillGradientAngle: 135, * fillGradientStops: [ * { color: "#FF6B6B", position: 0 }, * { color: "#556270", position: 1 }, * ], * shadowColor: "#000000", * shadowBlur: 10, * shadowOffsetX: 4, * shadowOffsetY: 4, * shadowOpacity: 0.3, * }; * // => both satisfy the ShapeStyle interface * ``` */ declare interface ShapeStyle { fillColor?: string; /** * Raw XML colour-choice node preserved from `a:solidFill` for round-trip * serialisation. Captures `a:schemeClr` / `a:sysClr` / `a:prstClr` / * `a:srgbClr` plus colour transforms (`lumMod`, `lumOff`, `tint`, * `shade`, `satMod`, `alpha`, …). On save we re-emit verbatim when the * resolved {@link fillColor} still matches this node, otherwise we fall * back to canonical ``. */ fillColorXml?: XmlObject; /** * Typed theme colour reference for the fill, set when {@link fillColorXml} * is a plain `a:schemeClr` (see `themeColorRefFromColorChoice`). When * present it WINS on save: the writer emits `` from this ref * instead of the resolved {@link fillColor}, so the fill keeps following * the theme palette after a later theme change. `undefined` means the fill * is a plain hex (or a colour kind a ref cannot express). */ fillColorRef?: PptxThemeColorRef; fillGradient?: string; /** Original `gradFill` XML retained for unknown-child and extension round-tripping. */ fillGradientXml?: XmlObject; fillMode?: 'solid' | 'gradient' | 'pattern' | 'none' | 'image' | 'theme' | 'group'; /** * ``: the shape paints with the SLIDE BACKGROUND's fill * rather than its own or its theme style's. * * PowerPoint's designer emits full-bleed rectangles this way, and they also * carry an `a:fillRef` pointing at `accent1`. Ignoring the attribute painted * those panels in the accent colour, so a black-and-white title slide came out * black-and-blue. The load pipeline copies the resolved slide background onto * the fill fields; the flag stays for round-trip and for renderers that want * to re-resolve against a changed background. */ useBackgroundFill?: boolean; fillPatternPreset?: string; fillPatternBackgroundColor?: string; /** Original `pattFill` XML retained for unknown-child round-tripping. */ fillPatternXml?: XmlObject; /** Raw XML node for pattern fill foreground colour (preserves color transforms). */ fillPatternFgClrXml?: XmlObject; /** Raw XML node for pattern fill background colour (preserves color transforms). */ fillPatternBgClrXml?: XmlObject; /** Data-URI or URL for image fill (when fillMode === "image"). */ fillImageUrl?: string; /** How the image is sized within the shape: stretch to fill, or tile/repeat. */ fillImageMode?: 'stretch' | 'tile'; /** Whether the image fill rotates/flips with the shape (`a:blipFill/@rotWithShape`). * Defaults to true per the schema; preserved for round-trip when the source * authored the attribute explicitly. When false, the shape's own geometry * (clip-path/outline) still carries the shape's rotation/flip, but the * picture content inside stays fixed to the page frame (upright), matching * PowerPoint. See `pptx-viewer-shared`'s `getImageFillCounterTransform`. */ fillImageRotWithShape?: boolean; fillGradientStops?: Array<{ color: string; position: number; opacity?: number; /** Raw XML colour node preserved for round-trip (e.g. a:schemeClr with transforms). */ originalColorXml?: XmlObject; /** * Typed theme colour reference for this stop, set when * {@link originalColorXml} is a plain `a:schemeClr`. Wins on save, same * as {@link ShapeStyle.fillColorRef}. */ colorRef?: PptxThemeColorRef; }>; fillGradientAngle?: number; fillGradientType?: 'linear' | 'radial'; /** Path gradient sub-type from `a:path/@path` (e.g. "circle", "rect", "shape"). */ fillGradientPathType?: 'circle' | 'rect' | 'shape'; /** Focal point for path (radial) gradients, derived from `a:fillToRect`. * Values are 0..1 fractions relative to shape bounds. */ fillGradientFocalPoint?: { x: number; y: number; }; /** Raw fillToRect LTRB values (0..1 fractions) from `a:fillToRect`. * Defines the inner rectangle where the gradient reaches its final stop. * l/t are insets from left/top edges; r/b are insets from right/bottom edges. */ fillGradientFillToRect?: { l: number; t: number; r: number; b: number; }; /** Raw tileRect LTRB values (0..1 fractions, may be negative) from * `a:gradFill/a:tileRect`. Defines the rectangle the gradient tile occupies * before any flip/tiling is applied. */ fillGradientTileRect?: { l: number; t: number; r: number; b: number; }; /** Gradient tile flip mode (`a:gradFill/@flip`). * `none` = no tiling flip (default), `x|y|xy` = mirror in the named axis. */ fillGradientFlip?: 'none' | 'x' | 'y' | 'xy'; /** Whether the gradient rotates with the shape (`a:gradFill/@rotWithShape`). * Defaults to true per the schema; preserved for round-trip when the source * authored the attribute explicitly. */ fillGradientRotWithShape?: boolean; /** Whether the linear gradient is scaled to the shape (`a:lin/@scaled`). * Defaults to true per the schema; preserved for round-trip. */ fillGradientScaled?: boolean; fillOpacity?: number; strokeColor?: string; /** * Raw XML colour-choice node preserved from `a:ln/a:solidFill` for * round-trip serialisation. See {@link fillColorXml} for the rationale. */ strokeColorXml?: XmlObject; /** * Typed theme colour reference for the outline, mirroring * {@link fillColorRef}: set when {@link strokeColorXml} is a plain * `a:schemeClr`, and wins on save. */ strokeColorRef?: PptxThemeColorRef; /** * Kind of fill painted on the outline (`a:ln` child). Distinguishes a solid * outline from a gradient/pattern/none outline so save can emit the correct * single line fill instead of collapsing every outline to `a:solidFill` * (which, alongside a preserved `a:gradFill`/`a:pattFill`, produces an * invalid dual-fill ``). */ strokeFillMode?: 'solid' | 'gradient' | 'pattern' | 'none'; /** Raw `a:ln/a:gradFill` XML preserved for round-trip when the outline is * gradient-filled. Re-emitted verbatim as the line's single fill on save. */ strokeGradientXml?: XmlObject; /** Raw `a:ln/a:pattFill` XML preserved for round-trip when the outline is * pattern-filled. Re-emitted verbatim as the line's single fill on save. */ strokePatternXml?: XmlObject; /** * Structured stops of a gradient outline (`a:ln/a:gradFill/a:gsLst`), in the * same shape as {@link fillGradientStops}. * * The raw XML above round-trips a gradient outline on save, but a renderer * cannot paint from it: it needs resolved colours and positions. Without * these, every binding fell back to {@link strokeColor} - a single averaged * colour - so a two-tone outline painted flat and a fade-to-transparent * outline painted fully opaque. */ strokeGradientStops?: ShapeStyle['fillGradientStops']; /** Gradient outline angle in OOXML degrees (`a:lin/@ang`), 0 = left to right. */ strokeGradientAngle?: number; /** Gradient outline kind: `linear` (`a:lin`) or `radial` (`a:path`). */ strokeGradientType?: ShapeStyle['fillGradientType']; /** Path-gradient shape for a radial outline (`a:path/@path`). */ strokeGradientPathType?: ShapeStyle['fillGradientPathType']; /** Preset name of a pattern outline (`a:ln/a:pattFill/@prst`). */ strokePatternPreset?: string; /** Background colour of a pattern outline (`a:ln/a:pattFill/a:bgClr`). */ strokePatternBackgroundColor?: string; strokeWidth?: number; strokeOpacity?: number; strokeDash?: StrokeDashType; /** Line join style (`a:ln/@join`): round, bevel, or miter. */ lineJoin?: 'round' | 'bevel' | 'miter'; /** Miter limit (`a:miter/@lim`) in EMU-percent units (default 800000 = 8.0). Only meaningful when lineJoin is 'miter'. */ miterLimit?: number; /** Line cap style (`a:ln/@cap`): flat, rnd, or sq. */ lineCap?: 'flat' | 'rnd' | 'sq'; /** Compound line type (`a:ln/@cmpd`). */ compoundLine?: 'sng' | 'dbl' | 'thickThin' | 'thinThick' | 'tri'; /** Pen line alignment (`a:ln/@algn`): `ctr` (centre, default) or `in` (inside). */ lineAlignment?: 'ctr' | 'in'; shadowColor?: string; /** Preserved source `a:effectLst`, including unknown effects and extensions. */ effectListXml?: XmlObject; /** Original outer-shadow node used for lossless surgical updates. */ outerShadowXml?: XmlObject; /** Resolved source shadow colour used to detect colour edits. */ outerShadowOriginalColor?: string; /** Source shadow opacity used to detect alpha edits. */ outerShadowOriginalOpacity?: number; shadowBlur?: number; shadowOffsetX?: number; shadowOffsetY?: number; shadowOpacity?: number; /** Preset shadow name from `a:prstShdw/@prst` (e.g. "shdw1"..."shdw20"). */ presetShadowName?: string; /** Shadow angle in degrees (0-360). Parsed from `@_dir` (60000ths of a degree). */ shadowAngle?: number; /** Shadow distance in pixels. Parsed from `@_dist` (EMUs). */ shadowDistance?: number; /** Whether shadow rotates with shape. Parsed from `@_rotWithShape`. */ shadowRotateWithShape?: boolean; /** Outer-shadow horizontal scaling (`a:outerShdw/@sx`) in 1000ths of a percent (default 100000 = 100%). */ shadowScaleX?: number; /** Outer-shadow vertical scaling (`a:outerShdw/@sy`). */ shadowScaleY?: number; /** Outer-shadow horizontal skew (`a:outerShdw/@kx`) in 60000ths of a degree. */ shadowSkewX?: number; /** Outer-shadow vertical skew (`a:outerShdw/@ky`). */ shadowSkewY?: number; /** Outer-shadow alignment (`a:outerShdw/@algn`). */ shadowAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br'; /** Inner-shadow rotateWithShape (`a:innerShdw/@rotWithShape`). */ innerShadowRotateWithShape?: boolean; /** Reflection fade direction (`a:reflection/@fadeDir`) in 60000ths of a degree. */ reflectionFadeDirection?: number; /** Reflection horizontal scaling (`a:reflection/@sx`). */ reflectionScaleX?: number; /** Reflection vertical scaling (`a:reflection/@sy`). */ reflectionScaleY?: number; /** Reflection horizontal skew (`a:reflection/@kx`). */ reflectionSkewX?: number; /** Reflection vertical skew (`a:reflection/@ky`). */ reflectionSkewY?: number; /** Reflection alignment (`a:reflection/@algn`). */ reflectionAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br'; /** Reflection rotateWithShape (`a:reflection/@rotWithShape`). */ reflectionRotateWithShape?: boolean; /** Reflection start position (`a:reflection/@stPos`) as 0-1 fraction. */ reflectionStartPosition?: number; /** Multiple shadow layers (for advanced effects). */ shadows?: ShadowEffect[]; glowColor?: string; /** Original glow node used for lossless surgical updates. */ glowXml?: XmlObject; /** Resolved source glow colour used to detect colour edits. */ glowOriginalColor?: string; /** Source glow opacity used to detect alpha edits. */ glowOriginalOpacity?: number; glowRadius?: number; glowOpacity?: number; softEdgeRadius?: number; /** Inner shadow colour (`a:innerShdw`). */ innerShadowColor?: string; /** Original inner-shadow node used for lossless surgical updates. */ innerShadowXml?: XmlObject; /** Resolved source inner-shadow colour used to detect colour edits. */ innerShadowOriginalColor?: string; /** Source inner-shadow opacity used to detect alpha edits. */ innerShadowOriginalOpacity?: number; /** Inner shadow opacity (0-1). */ innerShadowOpacity?: number; /** Inner shadow blur radius in px. */ innerShadowBlur?: number; /** Inner shadow horizontal offset in px. */ innerShadowOffsetX?: number; /** Inner shadow vertical offset in px. */ innerShadowOffsetY?: number; /** Original soft-edge node, including vendor attributes and extensions. */ softEdgeXml?: XmlObject; /** Reflection effect — distance from shape bottom in px. */ reflectionBlurRadius?: number; /** Original reflection node, including vendor attributes and extensions. */ reflectionXml?: XmlObject; /** Reflection start opacity (0-1). */ reflectionStartOpacity?: number; /** Reflection end opacity (0-1). */ reflectionEndOpacity?: number; /** Reflection end position (0-1 fraction of shape height). */ reflectionEndPosition?: number; /** Reflection direction in degrees. */ reflectionDirection?: number; /** Reflection rotation in degrees (`a:reflection/@rot` in 60000ths). */ reflectionRotation?: number; /** Reflection distance in px. */ reflectionDistance?: number; /** Standalone blur effect radius in px (`a:effectLst > a:blur`). */ blurRadius?: number; /** Whether the blur effect grows the bounds of the shape (`a:blur/@grow`). */ blurGrow?: boolean; connectorStartArrow?: ConnectorArrowType; /** Start arrow width size ('sm' | 'med' | 'lg'). */ connectorStartArrowWidth?: 'sm' | 'med' | 'lg'; /** Start arrow length size ('sm' | 'med' | 'lg'). */ connectorStartArrowLength?: 'sm' | 'med' | 'lg'; connectorEndArrow?: ConnectorArrowType; /** End arrow width size ('sm' | 'med' | 'lg'). */ connectorEndArrowWidth?: 'sm' | 'med' | 'lg'; /** End arrow length size ('sm' | 'med' | 'lg'). */ connectorEndArrowLength?: 'sm' | 'med' | 'lg'; /** Connection point for the start of a connector. */ connectorStartConnection?: ConnectorConnectionPoint; /** Connection point for the end of a connector. */ connectorEndConnection?: ConnectorConnectionPoint; /** Custom dash pattern, measured relative to line width in thousandths of one percent. */ customDashSegments?: PptxCustomDashSegment[]; /** Original `a:ds` payloads retained by index for lossless edits. */ customDashSegmentXml?: XmlObject[]; /** Original `a:custDash` payload retained for lossless edits. */ customDashXml?: XmlObject; /** 3D scene/camera settings from `a:scene3d`. */ scene3d?: Pptx3DScene; /** 3D shape extrusion/bevel from `a:sp3d`. */ shape3d?: Pptx3DShape; /** Line-level shadow colour from `a:ln/a:effectLst/a:outerShdw`. */ lineShadowColor?: string; /** Line-level shadow opacity (0-1). */ lineShadowOpacity?: number; /** Line-level shadow blur radius in px. */ lineShadowBlur?: number; /** Line-level shadow horizontal offset in px. */ lineShadowOffsetX?: number; /** Line-level shadow vertical offset in px. */ lineShadowOffsetY?: number; /** Line-level glow colour from `a:ln/a:effectLst/a:glow`. */ lineGlowColor?: string; /** Line-level glow radius in px. */ lineGlowRadius?: number; /** Line-level glow opacity (0-1). */ lineGlowOpacity?: number; /** Raw `a:effectDag` XML node preserved for round-trip serialisation. */ effectDagXml?: XmlObject; /** * Typed effect graph parsed from {@link ShapeStyle.effectDagXml}. The four * structural container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`, * `a:relOff`) are fully typed; any other leaf effect (e.g. `a:outerShdw`, * `a:glow`, `a:alphaInv`) is captured as * {@link import('./effect-dag').EffectDagRawLeaf} so we never have to * recurse into the full effect taxonomy. */ effectDagTree?: EffectDagContainer; /** Grayscale flag from effectDag `a:grayscl`. */ dagGrayscale?: boolean; /** Bi-level threshold (0-100) from effectDag `a:biLevel`. */ dagBiLevel?: number; /** Brightness adjustment (-100 to 100) from effectDag `a:lum/@bright`. */ dagLumBrightness?: number; /** Contrast adjustment (-100 to 100) from effectDag `a:lum/@contrast`. */ dagLumContrast?: number; /** Hue rotation in degrees (0-360) from effectDag `a:hsl/@hue`. */ dagHslHue?: number; /** Saturation adjustment from effectDag `a:hsl/@sat`. */ dagHslSaturation?: number; /** Luminance adjustment from effectDag `a:hsl/@lum`. */ dagHslLuminance?: number; /** Alpha modulation fixed (0-100) from effectDag `a:alphaModFix`. */ dagAlphaModFix?: number; /** Tint hue in degrees from effectDag `a:tint/@hue`. */ dagTintHue?: number; /** Tint amount (0-100) from effectDag `a:tint/@amt`. */ dagTintAmount?: number; /** Duotone colour pair from effectDag `a:duotone`. */ dagDuotone?: { color1: string; color2: string; }; /** Fill overlay blend mode from effectDag `a:fillOverlay/@blend`. */ dagFillOverlayBlend?: 'over' | 'mult' | 'screen' | 'darken' | 'lighten'; /** * Fill overlay tint colour (hex `#RRGGBB`) from effectDag `a:fillOverlay`'s * `a:solidFill`/`a:gradFill`. Painted as a blended overlay layer over the * element; the blend mode comes from {@link dagFillOverlayBlend}. */ dagFillOverlayColor?: string; /** Fill overlay tint opacity (0-1), from the overlay fill colour's alpha. */ dagFillOverlayOpacity?: number; /** Fill overlay blend mode from a direct `a:effectLst/a:fillOverlay/@blend`. */ shapeFillOverlayBlend?: 'over' | 'mult' | 'screen' | 'darken' | 'lighten'; /** * Fill overlay tint colour (hex `#RRGGBB`) from a direct * `a:effectLst/a:fillOverlay`'s `a:solidFill`/`a:gradFill`. */ shapeFillOverlayColor?: string; /** Fill overlay tint opacity (0-1), from the overlay fill colour's alpha. */ shapeFillOverlayOpacity?: number; /** Original source `a:fillOverlay` node, preserved for lossless surgical updates. */ fillOverlayXml?: XmlObject; /** Resolved source fill-overlay colour used to detect colour edits. */ shapeFillOverlayOriginalColor?: string; /** Source fill-overlay opacity used to detect alpha edits. */ shapeFillOverlayOriginalOpacity?: number; /** `` — 1-based index into the theme's lnStyleLst. */ lnRefIdx?: number; /** Raw XML colour child of `` (e.g. `` with transforms). */ lnRefColorXml?: XmlObject; /** `` — 1-based index into fillStyleLst (1-3) or bgFillStyleLst (1001-1003). */ fillRefIdx?: number; /** Raw XML colour child of ``. */ fillRefColorXml?: XmlObject; /** `` — 1-based index into the theme's effectStyleLst. */ effectRefIdx?: number; /** Raw XML colour child of ``. */ effectRefColorXml?: XmlObject; /** `` — typically `major`, `minor`, or `none`. */ fontRefIdx?: string; /** Raw XML colour child of ``. */ fontRefColorXml?: XmlObject; /** * The fill `` resolved to, recorded ONLY when the shape's own * `spPr` authored no fill at all, so the reference is what paints it. * * Its absence therefore means "the fill is the shape's own", and its * presence plus an unchanged flat fill means "still purely inherited": see * `authored-shape-style.ts`, the shape-scope twin of `TextStyle`'s * `inheritedRunStyle`. */ inheritedFillStyle?: ShapeStyle; /** * The outline `` resolved to, recorded before `spPr/a:ln` was * layered on top. A property that still equals this baseline was never * authored on the shape and must not be written back as if it were. */ inheritedLineStyle?: ShapeStyle; /** * The shadow/glow/reflection/soft-edge/3D properties `` * resolved from the theme's `effectStyleLst`, recorded ONLY for the * properties the shape had not already authored itself. A shape whose * effects still match this baseline was never given its own effects and * must not have them written back as a literal `spPr/a:effectLst`; see * `authored-shape-style.ts`'s `effectIsPurelyStyleMatrix`. */ inheritedEffectStyle?: ShapeStyle; /** * Set by a style-matrix pick (the Shape Styles gallery): the shape's own * `spPr` fill, outline and effects were replaced by ``, so the * writer clears whatever the retained `spPr` still authored before it * writes the (now reference-owned) style. Never parsed; editor state only. */ styleMatrixReset?: boolean; } /** * A shortcut chord in the form `Mod+Shift+D`: modifiers `Mod` (Ctrl on * Windows/Linux, Cmd on macOS), `Ctrl`, `Meta`, `Alt`, `Shift`, joined by `+`, * followed by a `KeyboardEvent.key` value (`D`, `Delete`, `ArrowLeft`, `F2`). */ declare type ShortcutChord = string; /** X.509 certificate information extracted from a signature. */ declare interface SignatureCertificateInfo { /** Base64-encoded DER certificate data. */ certificateBase64: string; /** Issuer distinguished name (CN, O, etc.) if parseable. */ issuer?: string; /** Subject distinguished name (CN, O, etc.) if parseable. */ subject?: string; /** Certificate serial number as hex string. */ serialNumber?: string; /** Not-before validity date (ISO string). */ validFrom?: string; /** Not-after validity date (ISO string). */ validTo?: string; } /** A single ds:Reference in the SignedInfo. */ declare interface SignatureReference { /** The URI identifying the signed part. */ uri: string; /** The digest method algorithm. */ digestMethod?: string; /** Base64-encoded digest value. */ digestValue?: string; } /** Status of a digital signature. */ declare type SignatureStatus = 'valid' | 'invalid' | 'expired' | 'unknownCA' | 'unverified'; /** * Fluent builder for a single slide. * * @example * ```ts * const slide = new SlideBuilder(1) * .addText("Hello World", { fontSize: 36, bold: true, x: 100, y: 50 }) * .addShape("roundRect", { fill: { type: "solid", color: "#4472C4" } }) * .setNotes("Remember to mention key points") * .setBackground({ type: "solid", color: "#F5F5F5" }) * .build(); * ``` */ declare class SlideBuilder { private readonly slide; /** * @param slideNumber - 1-based slide number. * @param layoutPath - Optional layout archive path. * @param layoutName - Optional layout display name. */ constructor(slideNumber: number, layoutPath?: string, layoutName?: string); /** Add a text box to the slide. */ addText(text: string | TextSegmentInput[], options?: TextOptions): this; /** Add a shape to the slide. */ addShape(shapeType: string, options?: ShapeOptions): this; /** Add a connector (line) to the slide. */ addConnector(options?: ConnectorOptions): this; /** Add an image to the slide. */ addImage(source: string, options?: ImageOptions): this; /** Add a table to the slide. */ addTable(input: TableInput, options?: TableOptions): this; /** Add a chart to the slide. */ addChart(chartType: PptxChartType, input: ChartInput, options?: ChartOptions): this; /** Add a media element (video or audio) to the slide. */ addMedia(mediaType: 'video' | 'audio', source: string, options?: MediaOptions): this; /** Add a group of elements to the slide. */ addGroup(children: PptxElement[], options?: GroupOptions): this; /** Add a pre-built element directly. */ addElement(element: PptxElement): this; /** Set slide background. */ setBackground(bg: BackgroundInput): this; /** Set slide transition. */ setTransition(input: TransitionInput): this; /** Add an animation to an element on this slide. */ addAnimation(elementId: string, input: AnimationInput): this; /** Set speaker notes. */ setNotes(text: string): this; /** Mark the slide as hidden. */ setHidden(hidden: boolean): this; /** Assign the slide to a section. */ setSection(name: string, id?: string): this; /** * Add a freeform shape from SVG path data. * * Creates a custom-geometry shape element using the provided SVG path * string and appends it to the slide's element list. * * @param pathData - An SVG path data string (e.g. `"M 0 0 L 100 50 L 50 100 Z"`). * @param options - Optional position, styling, and size overrides. * @returns The builder instance for chaining. * * @example * ```ts * new SlideBuilder(1) * .addFreeform("M 0 0 C 33 0 66 100 100 100", { * stroke: { color: "#FF0000", width: 2 }, * }) * .build(); * ``` */ addFreeform(pathData: string, options?: ShapeOptions): this; /** * Add a pre-built element from any element builder (calls `.build()` for you). * * Accepts any object with a `build()` method that returns a {@link PptxElement}, * such as {@link TextBuilder}, {@link ShapeBuilder}, {@link ImageBuilder}, etc. * * @param builder - An element builder with a `.build()` method. * @returns The builder instance for chaining. * * @example * ```ts * const title = TextBuilder.create("Hello").fontSize(36).bold(); * new SlideBuilder(1).addBuilderElement(title).build(); * ``` */ addBuilderElement(builder: { build(): PptxElement; }): this; /** * Remove an element by its ID. * * Filters out the element with the given ID from the slide's element list. * If no element matches, the slide is left unchanged. * * @param elementId - The unique ID of the element to remove. * @returns The builder instance for chaining. * * @example * ```ts * const slide = new SlideBuilder(1) * .addText("temp", { x: 0, y: 0 }) * .removeElement("txt_abc123_1") * .build(); * ``` */ removeElement(elementId: string): this; /** * Get the current list of elements on this slide. * * Returns a readonly view of the elements array. Useful for inspecting * what has been added so far during the build process. * * @returns A readonly array of the slide's current elements. * * @example * ```ts * const builder = new SlideBuilder(1).addText("Hi"); * console.log(builder.getElements().length); // 1 * ``` */ getElements(): readonly PptxElement[]; /** * Get the number of elements on this slide. * * @returns The count of elements currently added to the slide. * * @example * ```ts * const builder = new SlideBuilder(1) * .addText("A").addText("B"); * console.log(builder.elementCount); // 2 * ``` */ get elementCount(): number; /** * Get the last added element (useful for getting its ID for animations). * * Returns `undefined` if the slide has no elements yet. * * @returns The most recently added element, or `undefined`. * * @example * ```ts * const builder = new SlideBuilder(1).addShape("rect"); * const shape = builder.getLastElement(); * if (shape) { * builder.addAnimation(shape.id, { preset: "fadeIn" }); * } * ``` */ getLastElement(): PptxElement | undefined; /** * Set the slide name/title for organizational purposes. * * Stores an arbitrary name string on the slide object. This is useful * for labeling slides in tooling or custom workflows. * * @param name - The display name to assign to the slide. * @returns The builder instance for chaining. * * @example * ```ts * new SlideBuilder(1) * .setName("Introduction") * .addText("Welcome!") * .build(); * ``` */ setName(name: string): this; /** Return the built {@link PptxSlide}. */ build(): PptxSlide; } export declare const SlideCanvas: typeof __VLS_export_2; declare interface SlideSizeEmu { widthEmu: number; heightEmu: number; /** ST_SlideSizeType token, or `''` for a size with no preset. */ type: string; } export declare const SlideStage: typeof __VLS_export_3; /** Discriminated id for every built-in slide template. */ declare type SlideTemplateId = 'title' | 'titleAndContent' | 'sectionHeader' | 'agenda' | 'twoContent' | 'comparison' | 'quote' | 'timeline' | 'keyMetrics' | 'titleOnly' | 'blank' | 'closing'; /** * SmartArt colour scheme presets. * * @example * ```ts * const scheme: SmartArtColorScheme = "colorful1"; * // => "colorful1" — one of: "colorful1" | "colorful2" | "colorful3" | "monochromatic1" | "monochromatic2" * ``` */ declare type SmartArtColorScheme = 'colorful1' | 'colorful2' | 'colorful3' | 'monochromatic1' | 'monochromatic2'; /** * Named SmartArt layout presets for creation (subset of PowerPoint layouts). * * @example * ```ts * const layout: SmartArtLayout = "hierarchy"; * // => "hierarchy" — one of: "basicBlockList" | "alternatingHexagons" | "hierarchy" | … * ``` */ declare type SmartArtLayout = 'basicBlockList' | 'alternatingHexagons' | 'basicChevronProcess' | 'basicCycle' | 'basicPie' | 'basicRadial' | 'basicVenn' | 'continuousBlockProcess' | 'convergingRadial' | 'hierarchy' | 'horizontalBulletList' | 'linearVenn' | 'segmentedProcess' | 'stackedList' | 'tableList' | 'trapezoidList' | 'upwardArrow' | 'basicFunnel' | 'basicTarget' | 'interlockingGears' | 'basicTimeline' | 'basicMatrix' | 'basicPyramid' | 'invertedPyramid' | 'bendingProcess' | 'stepDownProcess' | 'alternatingFlow' | 'descendingProcess' | 'pictureAccentList' | 'verticalBlockList' | 'groupedList' | 'pyramidList' | 'horizontalPictureList' | 'accentProcess' | 'verticalChevronList'; /** * Resolved SmartArt layout category. * * @example * ```ts * const cat: SmartArtLayoutType = "hierarchy"; * // => "hierarchy" — one of: "list" | "process" | "cycle" | "hierarchy" | "relationship" | … * ``` */ declare type SmartArtLayoutType = 'list' | 'process' | 'cycle' | 'hierarchy' | 'relationship' | 'matrix' | 'pyramid' | 'funnel' | 'gear' | 'target' | 'timeline' | 'venn' | 'chevron' | 'bending' | 'unknown'; /** * Manual layout override for a `type="pres"` presentation point, read from its * `dgm:prSet` attributes. PowerPoint writes these when the user drags, resizes, * rotates, or flips a SmartArt node by hand in its own diagram editor; without * them the node silently reverts to its algorithmic position whenever there is * no cached `dsp:` drawing part to fall back on. * * Every field is optional: only the attributes actually present on `prSet` are * populated. Angle and scale/factor units are already normalised to degrees and * plain ratios (a `custScaleX="150000"` becomes `scaleX: 1.5`), so a consumer * never has to know the raw `60000ths-of-a-degree` / `100000ths-of-a-percent` * XML encodings. * * @example * ```ts * const custom: SmartArtNodeCustomLayout = { angle: 15, scaleX: 1.2 }; * // => a node manually rotated 15 degrees and widened 20% in PowerPoint * ``` */ declare interface SmartArtNodeCustomLayout { /** `custAng`: additional rotation in degrees. */ angle?: number; /** `custScaleX`: horizontal scale ratio (1 = no change). */ scaleX?: number; /** `custScaleY`: vertical scale ratio (1 = no change). */ scaleY?: number; /** `custSzX`: horizontal size ratio, layered on top of {@link scaleX}. */ sizeX?: number; /** `custSzY`: vertical size ratio, layered on top of {@link scaleY}. */ sizeY?: number; /** `custFlipHor`: the node was manually mirrored horizontally. */ flipHorizontal?: boolean; /** `custFlipVert`: the node was manually mirrored vertically. */ flipVertical?: boolean; /** `custLinFactX`: manual position nudge along X, as a fraction of the container width. */ linearFactorX?: number; /** `custLinFactY`: manual position nudge along Y, as a fraction of the container height. */ linearFactorY?: number; /** * `custLinFactNeighborX`: spacing compensation applied to a NEIGHBOURING * node when this one is resized. Parsed for round-trip completeness; not * applied by the per-node final transform (it has no effect on this node's * own geometry; folding it into a neighbour's geometry would require * whole-layout awareness the final transform pass does not have). */ linearFactorNeighborX?: number; /** `custLinFactNeighborY`: see {@link linearFactorNeighborX} (Y axis). */ linearFactorNeighborY?: number; /** `custRadScaleRad`: manual radius scale ratio for a radial/cycle node. */ radialScaleRadius?: number; /** `custRadScaleInc`: manual angular-position nudge for a radial/cycle node. */ radialScaleIncrement?: number; /** `custT`: whether `prSet` declares a custom transform is present at all. */ hasCustomTransform?: boolean; } /** * A SmartArt diagram embedded via a ``. * * SmartArt data is extracted from `dgm:dataModel` parts. The editor * supports real structural editing (adding, removing and reordering nodes, * editing node text, and switching layout presets) with a lossless * `ptLst` round-trip. When the file carries PowerPoint's own pre-computed * drawing part, that exact layout is used; otherwise an algorithmic layout * engine approximates it, so complex custom layouts may not match * PowerPoint pixel-for-pixel. */ declare interface SmartArtPptxElement extends PptxElementBase { type: 'smartArt'; smartArtData?: PptxSmartArtData; /** Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`. */ altText?: string; /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */ title?: string; /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */ extensionXml?: PptxGraphicFrameExtension[]; } export declare const SmartArtRenderer: typeof __VLS_export_8; /** One colour-transform `styleLbl`'s resolved colour lists. */ declare interface SmartArtRoleColorList { fill: string[]; line: string[]; /** * `txFillClrLst`, when the label declares one (`revTx` -> `tx1`). A text * node's colour comes from here; see `smartart-merged-text-label`. */ textFill?: string[]; } /** * SmartArt visual style intensity. * * @example * ```ts * const style: SmartArtStyle = "moderate"; * // => "moderate" — one of: "flat" | "moderate" | "intense" * ``` */ declare type SmartArtStyle = 'flat' | 'moderate' | 'intense'; /** One transient red alignment line drawn while a snap is active. */ declare interface SnapLine { axis: 'x' | 'y'; position: number; } /** * Store PPTX content bytes so the audience tab can retrieve them. * Called by the presenter before opening the audience window. */ export declare function storeAudienceContent(content: ArrayBuffer | Uint8Array, sessionId?: string): Promise; /** * Stroke dash pattern types for lines and shape outlines. * * Maps to `a:ln/a:prstDash/@val` in OOXML. Use `"custom"` for * user-defined dash/space arrays. * * @example * ```ts * const dash: StrokeDashType = "dashDot"; * // => "dashDot" — one of: solid | dot | dash | lgDash | dashDot | custom | ... * ``` */ declare type StrokeDashType = 'solid' | 'dot' | 'dash' | 'lgDash' | 'dashDot' | 'lgDashDot' | 'lgDashDotDot' | 'sysDot' | 'sysDash' | 'sysDashDot' | 'sysDashDotDot' | 'custom'; declare interface StrokeInput { color?: string; width?: number; dash?: StrokeDashType; opacity?: number; join?: 'round' | 'bevel' | 'miter'; cap?: 'flat' | 'rnd' | 'sq'; /** A theme colour for the outline; see {@link FillInput}'s `themeColorRef`. */ themeColorRef?: PptxThemeColorRef; } /** A single section tile within a PowerPoint Summary Zoom container. */ declare interface SummaryZoomTarget extends PptxImageProperties { sectionId: string; targetSlideIndex: number; x: number; y: number; width: number; height: number; title?: string; description?: string; offsetFactorX?: number; offsetFactorY?: number; scaleFactorX?: number; scaleFactorY?: number; /** This tile's own `zmPr/@returnToParent`; see {@link ZoomPptxElement.returnToParent}. */ returnToParent?: boolean; /** This tile's own `zmPr/@transitionDur` in milliseconds; see {@link ZoomPptxElement.transitionDurationMs}. */ transitionDurationMs?: number; rawXml?: XmlObject; } /** Shape preset the Insert tab inserts. Mirrors React `SupportedShapeType`. */ export declare type SupportedShapeType = 'rect' | 'roundRect' | 'ellipse' | 'triangle' | 'rtTriangle' | 'diamond' | 'cylinder' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'hexagon' | 'octagon' | 'chevron' | 'star5' | 'star6' | 'star8' | 'plus' | 'heart' | 'cloud' | 'sun' | 'moon' | 'pie' | 'plaque' | 'teardrop' | 'line' | 'rtArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'connector' | 'freeform'; export declare type SvgExportAllOptions = SvgExportOptions; /** * Options controlling SVG export behaviour. */ declare interface SvgExportOptions { /** Include hidden slides when exporting all. Default `false`. */ includeHidden?: boolean; /** Slide indices to export (0-based). If omitted, all slides are exported. */ slideIndices?: number[]; /** Default font family when the element does not specify one. */ defaultFontFamily?: string; /** Default font size in points when the element does not specify one. */ defaultFontSize?: number; } export declare type SvgExportSingleSlideOptions = SvgExportOptions; /** One `\n`-split line of a run's tabbed text. */ declare interface TabbedLineRun { pieces: TabbedRunPiece[]; } /** One tabbed-line piece, ready to spread onto a binding's own span element. */ declare interface TabbedRunPiece { text: string; /** * CSS for the span that wraps `text`: inline-block layout, this run's own * decoration repeated, and this piece's own PowerPoint advance-width * correction as `letter-spacing` (see `buildTabbedLine`). The piece is * nested inside the run's own span, and neither property inherits the way a * caller would want: `text-decoration-*` does not inherit into a nested * element at all (an ancestor's underline is drawn *through* its * descendants, but each descendant still computes `none` of its own), so a * caller passes the run's decoration subset (`nestedTextDecorationStyle`) to * have it repeated here; `letter-spacing` DOES inherit, which is exactly why * this piece sets it explicitly rather than only when non-zero - the run's * container span carries its own (wrong, whole-text) correction that would * otherwise leak in. */ style: RunStyle; /** CSS for the leader-fill span preceding this piece, or `undefined` when there is no gap to fill. */ leaderStyle?: RunStyle; /** Leader glyphs sized to fill `leaderStyle`'s width. Present only alongside `leaderStyle`. */ leaderText?: string; /** * `a:rPr/@u="words"` per-word/gap sub-pieces of THIS tab piece's own text * (see `splitWordsForUnderline`), present only when the run's underline is * `words`. A tab-separated piece is otherwise rendered as a single span * (`text` + `style`), which underlines it continuously - correct for a * one-word piece, but wrong for a piece like `"Hello World"` between two tab * stops, which needs a gap under the space. A binding renders one SIBLING * span per entry IN PLACE OF the piece's single `text` span: each entry's * `style` is the piece's own `style` (the same inline-block layout and * advance-width correction, so the line measures exactly as before), with * the underline stripped on a gap entry. They must be siblings, not spans * nested inside the piece span: an ancestor's underline is drawn through * every inline descendant, so a nested gap could not lose it. `text`/`style` * stay the continuous-underline fallback for a binding that does not * render this field. */ words?: Array<{ text: string; style: RunStyle; }>; } /** Table inline-edit state: present while a table cell is being edited. */ export declare interface TableCellEditorState { elementId: string; rowIndex: number; columnIndex: number; } declare interface TableCellInput { text: string; style?: Partial; fill?: FillInput; gridSpan?: number; rowSpan?: number; } declare interface TableInput { rows: TableRowInput[]; columnWidths?: number[]; style?: string; bandRows?: boolean; bandColumns?: boolean; firstRow?: boolean; lastRow?: boolean; firstCol?: boolean; lastCol?: boolean; } declare interface TableOptions extends Partial {} /** * A table embedded via a ``. * * @example * ```ts * const tbl: TablePptxElement = { * type: "table", * id: "tbl_1", x: 50, y: 200, width: 860, height: 300, * tableData: { * rows: [ * { cells: [{ text: "Name" }, { text: "Score" }] }, * { cells: [{ text: "Alice" }, { text: "95" }] }, * ], * }, * }; * // => satisfies TablePptxElement * ``` */ declare interface TablePptxElement extends PptxElementBase { type: 'table'; /** Parsed table cell data for editing. */ tableData?: PptxTableData; /** * Accessibility description from `p:nvGraphicFramePr/p:cNvPr/@descr`, the * same non-visual-properties attribute a picture's alt text comes from. */ altText?: string; /** Accessibility title from `p:nvGraphicFramePr/p:cNvPr/@title`. */ title?: string; /** * Unrecognised extensions captured from `a:graphicData/a:extLst` so they * round-trip losslessly. See {@link PptxGraphicFrameExtension}. */ extensionXml?: PptxGraphicFrameExtension[]; } export declare const TableRenderer: typeof __VLS_export_6; declare interface TableRowInput { cells: TableCellInput[]; height?: number; } export declare type TemplateElementMap = Record; /** * 3D text body extrusion/bevel from `a:bodyPr/a:sp3d`. * * @example * ```ts * const text3d: Text3DStyle = { * extrusionHeight: 57150, * presetMaterial: "plastic", * bevelTopType: "circle", * bevelTopWidth: 25400, * bevelTopHeight: 25400, * }; * // => satisfies Text3DStyle * ``` */ declare interface Text3DStyle { /** Extrusion height (depth) in EMU. */ extrusionHeight?: number; /** Extrusion colour as hex string. */ extrusionColor?: string; /** Preset material, e.g. "matte", "plastic", "metal". */ presetMaterial?: MaterialPresetType; /** Top bevel preset type. */ bevelTopType?: BevelPresetType; /** Top bevel width in EMU. */ bevelTopWidth?: number; /** Top bevel height in EMU. */ bevelTopHeight?: number; /** Bottom bevel preset type. */ bevelBottomType?: BevelPresetType; /** Bottom bevel width in EMU. */ bevelBottomWidth?: number; /** Bottom bevel height in EMU. */ bevelBottomHeight?: number; } declare interface TextOptions extends Partial { fontSize?: number; fontFamily?: string; bold?: boolean; italic?: boolean; underline?: boolean; strikethrough?: boolean; color?: string; alignment?: 'left' | 'center' | 'right' | 'justify'; verticalAlignment?: 'top' | 'middle' | 'bottom'; lineSpacing?: number; fill?: FillInput; stroke?: StrokeInput; shadow?: ShadowInput; opacity?: number; } /** * Rich text style properties for a text run or paragraph. * * Combines character-level formatting (font, bold, colour …), * paragraph-level controls (alignment, spacing, indentation), and * body-level properties (autofit, insets, text direction). All * fields are optional — unset properties inherit from layout/master * placeholders or theme defaults. * * @remarks * Font sizes are stored in **points**. Spatial measurements (insets, * margins) are in **pixels** (pre-converted from EMU during parsing). * * @example * ```ts * const heading: TextStyle = { * fontFamily: "Montserrat", * fontSize: 36, * bold: true, * color: "#1A1A2E", * align: "center", * lineSpacing: 1.15, * }; * * const body: TextStyle = { * fontFamily: "Open Sans", * fontSize: 14, * color: "#444444", * align: "left", * paragraphSpacingAfter: 8, * }; * // => both satisfy the TextStyle interface * ``` */ /** 2D linear transform matrix `[a, b, c, d]` for inherited group orientation. */ declare type TextOrientationMatrix = [number, number, number, number]; declare interface TextPositionCell { index: number; left?: TextPositionCell; right?: TextPositionCell; } /** * A text box — a plain rectangle containing text, typically with no * visible fill or stroke. * * @example * ```ts * const title: TextPptxElement = { * type: "text", * id: "txt_1", x: 50, y: 30, width: 800, height: 60, * text: "Welcome", * textStyle: { fontSize: 36, bold: true }, * }; * // => satisfies TextPptxElement * ``` */ declare interface TextPptxElement extends PptxElementBase, PptxTextProperties, PptxShapeProperties, PptxNonVisualDescription { type: 'text'; } /** * A single text run within a paragraph. * * A text body is decomposed into an array of `TextSegment` objects, * each with its own style. Paragraph breaks are represented as * segments with `isParagraphBreak: true`. * * @example * ```ts * const segments: TextSegment[] = [ * { text: "Bold intro ", style: { bold: true, fontSize: 16 } }, * { text: "and normal text.", style: { fontSize: 16 } }, * { text: "", style: {}, isParagraphBreak: true }, * { text: "Second paragraph.", style: { fontSize: 14 } }, * ]; * // => 4 segments: 2 styled runs, 1 paragraph break, 1 normal run * ``` */ declare interface TextSegment { text: string; style: TextStyle; /** When this segment originated from an `a:fld` element, stores the field type (e.g. "slidenum", "datetime"). */ fieldType?: string; /** When this segment originated from an `a:fld` element, stores the field GUID. */ fieldGuid?: string; /** * Original attribute name used to author the field GUID — `'uuid'` for the * `a:fld/@uuid` form authored by some legacy producers, `'id'` for the * canonical `a:fld/@id` form. Preserved so the writer round-trips whichever * spelling the source used (PowerPoint accepts both). Defaults to `'id'` * on save when undefined. */ fieldGuidAttr?: 'uuid' | 'id'; /** * Raw per-field paragraph properties (`a:fld > a:pPr`). The schema permits * `pPr` inside an `a:fld` so the field can carry its own paragraph-level * formatting; preserved verbatim on save when present. */ fieldParagraphPropertiesXml?: XmlObject; /** Raw OMML XML node for equation segments (from `a14:m` / `m:oMathPara`). */ equationXml?: Record; /** * The ORIGINAL top-level paragraph child that carried this equation, * captured verbatim at parse time and keyed by its own tag: `{ 'a14:m': * ... }`, `{ 'm:oMathPara': ... }`, `{ 'm:oMath': ... }`, or `{ * 'mc:AlternateContent': ... }` for an equation authored behind a * Choice/Fallback switch. `equationXml` above is the resolved math content * used for rendering (unwrapped one level for `a14:m`/`mc:AlternateContent` * sources); this field exists solely so the writer can re-emit an UNTOUCHED * equation byte-for-byte, Choice and Fallback both, instead of collapsing * it to a bare math element PowerPoint's own writer never produces. * `undefined` for a freshly inserted or edited equation, which the writer * instead reconstructs from `equationXml` (always `{ 'm:oMathPara': ... }` * or `{ 'm:oMath': ... }` for those cases). Any code that replaces * `equationXml` on an existing segment must drop this field, or the writer * would keep re-emitting the equation's OLD XML instead of the edit. */ equationSourceXml?: Record; /** * Optional equation number for numbered equations (e.g. "(1)", "(2.3)"). * When present, the equation is rendered centered with the number right-aligned. */ equationNumber?: string; /** Whether this segment represents a paragraph break rather than renderable text. */ isParagraphBreak?: boolean; /** * Whether this segment represents a soft line break (`a:br`) rather than * a paragraph terminator. Soft line breaks remain inside the same paragraph * but force a line wrap and may carry their own run properties. * * The renderer should treat the segment text as `"\n"` when present. */ isLineBreak?: true; /** * Raw `a:rPr` XML for an `a:br` (soft line break) segment, captured verbatim * during parse so the writer can re-emit attributes/colours/fonts that the * typed model doesn't represent. Only meaningful when {@link isLineBreak} * is `true`. */ breakRunProperties?: Record; /** Structured bullet info for the first segment of a paragraph. */ bulletInfo?: BulletInfo; /** * Outline level for the paragraph this segment starts (`a:p/@lvl`). * * Only meaningful on the first segment of a paragraph (matching the * convention used for {@link bulletInfo}). Stored as the raw OOXML * value (0 = top level, 1-8 = nested) and serialised back when non-zero. */ paragraphLevel?: number; /** * Raw `a:endParaRPr` XML node for the paragraph this segment starts. * * Captured verbatim on parse so attributes and child colours/fonts that * the typed model doesn't represent survive a round-trip. Only meaningful * on the first segment of a paragraph. */ endParaRunProperties?: Record; /** * Resolved body defaults and optional `a:endParaRPr` of a runless paragraph. * Carried on its first segment (or terminator), separately from marker * styling. Absent when the source contains an authored run or field. */ paragraphInsertionStyle?: TextStyle; /** * Per-paragraph properties (alignment, spacing, margins, indent, tab stops, * rtl) authored on this paragraph's own `a:pPr` (#69). Only meaningful on * the first segment of a paragraph. When present, the writer emits these * per paragraph instead of collapsing one shape-level pPr onto every * paragraph. Only the paragraph-geometry keys of {@link TextStyle} are * populated; unrelated fields fall back to the shape-level style. */ paragraphProperties?: TextStyle; /** * The paragraph this segment starts authored an EMPTY ``. Only * meaningful on the first segment of a paragraph. The writer re-emits the * empty element when it has no paragraph property of its own to write, so * a rewritten slide keeps the markup PowerPoint wrote. */ emptyParagraphPropertiesAuthored?: boolean; /** * The paragraph this segment starts has no run content and authored no * `a:endParaRPr` (a bare ``, possibly with an `a:pPr`). Only * meaningful on the first segment of a paragraph. It stops the writer * inventing an empty run or an `` stub for a * paragraph that still has no content when saved. */ bareParagraph?: boolean; /** * Phonetic annotation text from `a:ruby > a:rt` (e.g. furigana, pinyin). * When present, the renderer should wrap the base text with an HTML `` tag. */ rubyText?: string; /** * Ruby text alignment from `a:rubyPr > @val` attribute. * Values: "ctr" (center), "l" (left), "r" (right), "dist" (distribute), "distCat", "distLetter". * @default "ctr" */ rubyAlignment?: string; /** * Ruby text font size as a percentage of the base text font size * from `a:rubyPr/@hps` (half-point size) or inferred from rt run font size. * Stored in **points** for consistency with `TextStyle.fontSize`. */ rubyFontSize?: number; /** * Style for the ruby (phonetic) text run, parsed from `a:rt > a:r > a:rPr`. * Used by the renderer to apply font family, colour, etc. to the `` element. */ rubyStyle?: TextStyle; /** * The parsed `a:rubyPr` node, kept verbatim so its attributes (`hps`, * `hpsRaise`, `hpsBaseText`, `lid`, ...) round-trip exactly; only an * edited {@link rubyAlignment} is written over it on save. */ rubyPropertiesXml?: XmlObject; /** * What each of a ruby run's two base-side `a:rPr`s authored on its own: * `outer` is the containing `a:r`'s, `base` the `a:rubyBase` run's. The * flat {@link style} merges both for rendering; these let the writer give * each `a:rPr` back only its own properties (plus any later edit). */ rubyRunAuthoredStyles?: { outer?: TextStyle; base?: TextStyle; }; } declare interface TextSegmentInput { text: string; style?: Partial; } /** Desired UTF-16 units mapped to the editor's previously observed identities. */ declare interface TextSessionCorrespondence { readonly retainedIndices: readonly (number | null)[]; /** Old carriers for known paragraph attributes, independently of character identity. */ readonly paragraphSources?: readonly (number | null)[]; } /** Supplied by the binding's existing Yjs runtime, bound to this exact Y.Text. */ declare interface TextSessionPositions { capture: (index: number, association: number) => Position; resolve: (position: Position) => number | null; /** Synchronize tracked positions once per batch, including in-transaction writes. */ refresh?: () => boolean | void; /** Release only resources created for this session. */ dispose?: () => void; } declare interface TextStyle { /** * Combined rotation/flip matrix inherited from ancestor groups. * Used only to keep descendant text readable after nested group mirrors. */ ancestorGroupTransform?: TextOrientationMatrix; /** Original `a:rPr` XML retained by projections that share the shape-text model. */ runPropertiesXml?: XmlObject; /** * The properties this run's OWN `a:rPr` authored, and nothing else. * * A run style is assembled as * `{...inheritedRunStyle, ...authoredRunStyle}`, so the flat style is a * fully RESOLVED view: it cannot say whether `fontSize: 60` came from the * run, from the shape's `a:lstStyle`, from the layout placeholder, from the * master `p:txStyles` or from the theme. Omission is meaningful in OOXML * (§21.1.2.3), so a writer that re-emits the resolved view converts every * inherited value into an authored one and the deck stops being * theme-driven after one save. * * This is the run-scope twin of {@link TextSegment.paragraphProperties}, * which is parsed strictly from the paragraph's own `a:pPr` for the same * reason. Present only for runs that came from a parsed deck; absent for * SDK-built text, where the flat style IS the only description and must be * written out in full. */ authoredRunStyle?: TextStyle; /** * The resolved inheritance baseline {@link authoredRunStyle} was layered * on top of (shape `a:lstStyle` -> placeholder -> layout -> master * `p:txStyles` -> theme -> `p:defaultTextStyle`). * * Kept alongside the authored half because the two answer different * questions. The authored half says "the source pinned this"; the baseline * says "this value is what inheritance already produces", which is how an * EDIT is told apart from an inherited value: an editor mutates the flat * style without knowing about either field, so a property that now differs * from the baseline was either authored or edited and must be written, * while one that still matches can be left to inherit. * * Holds a reference to the per-paragraph baseline object rather than a * copy, so carrying it costs one pointer per run. */ inheritedRunStyle?: TextStyle; /** * Snapshot of the ELEMENT-scope paragraph geometry (alignment, margins, * indent, line and paragraph spacing, tab stops, rtl, line-break flags) as * the load pipeline resolved it. * * Present only on an `element.textStyle` that came from a parsed deck, and * populated only with the geometry keys. It exists so the save path can * answer one question it otherwise cannot: has the user CHANGED the body's * alignment or indent, or is the value simply what the shape's * `a:lstStyle`, its layout placeholder and the master already produce? * Element-level text panels (`textAdvancedPatch`, `alignPatch` and friends * in `pptx-viewer-shared`) write `element.textStyle` and never touch * `segment.paragraphProperties`, so a diff against this snapshot is the * only way to tell an edit from an inheritance artefact. * * @see element-paragraph-geometry.ts */ resolvedParagraphGeometry?: TextStyle; /** * Snapshot of the ELEMENT-scope `a:bodyPr` properties (vertical anchor, * text direction, columns, overflow, autofit, body insets, text wrap, and * the boolean/rotation attributes) as the load pipeline resolved them. * * A shape's own `a:bodyPr` is parsed first, then whatever it left * `undefined` is back-filled from the placeholder / layout / master * defaults (`applyPlaceholderBodyDefaults`), and a placeholder shape with * no `a:bodyPr` of its own has the INHERITED one parsed as if it were its * own. None of those three sources is distinguishable at * `element.textStyle` once the cascade finishes, so a writer that * re-emits every defined field turns an inherited anchor, inset, autofit * mode or `rtlCol` into a value pinned on the slide forever (and an * inherited `a:normAutofit` with no scale gets written back as * `a:spAutoFit`, flipping AutoSize from "shrink text" to "resize shape"). * * Present only on an `element.textStyle` that came from a parsed deck. * The save path diffs the live style against this snapshot: a field that * still matches is an inheritance artefact and the writer leaves the * underlying `a:bodyPr` attribute untouched (whatever it already is, * present or absent); a field that differs was authored or has since * been edited and is written out. * * @see element-body-properties.ts */ resolvedBodyProperties?: TextStyle; fontFamily?: string; fontSize?: number; /** When true, some form of autofit is in effect; see {@link autoFitMode} for which. */ autoFit?: boolean; /** Explicit autofit mode from OOXML body properties. * - 'shrink': `a:spAutoFit` - resize the SHAPE to fit the text (never the font) * - 'normal': `a:normAutofit` - shrink the TEXT to fit the shape (via `fontScale`/`lnSpcReduction`) * - 'none': `a:noAutofit` - explicitly no auto-fit (text overflows) * - undefined: no autofit element present (inherit from layout/master) */ autoFitMode?: 'shrink' | 'normal' | 'none'; /** Font scale percentage for normAutofit (e.g. 0.9 = 90%). Only meaningful when autoFit is true. */ autoFitFontScale?: number; /** Line spacing reduction for normAutofit (e.g. 0.2 = reduce by 20%). Only meaningful when autoFit is true. */ autoFitLineSpacingReduction?: number; bold?: boolean; italic?: boolean; underline?: boolean; /** Specific underline style (e.g. "sng", "dbl", "wavy"). Falls back to "sng" when `underline` is true. */ underlineStyle?: UnderlineStyle; /** Underline colour as hex string (`a:uFill` / `a:uLn`). When absent, inherits text colour. */ underlineColor?: string; /** * When true, the source authored `` to explicitly suppress * underline (rather than omitting the attribute entirely). Preserved so the * writer can re-emit the explicit `none` token instead of dropping it. */ underlineExplicitNone?: boolean; /** * Underline line properties parsed from `` — width, dash * preset, and end caps. Captured as a typed object so the writer can * round-trip the line styling that previously was dropped (only the * solidFill colour was carried before). */ underlineLine?: { /** Line width in EMU (raw OOXML) for `a:uLn/@w`. */ widthEmu?: number; /** Compound line type (`a:uLn/@cmpd`). */ compound?: string; /** Cap style (`a:uLn/@cap`). */ cap?: string; /** Pen alignment (`a:uLn/@algn`). */ algn?: string; /** Preset dash value (`a:uLn/a:prstDash/@val`). */ prstDash?: string; /** Raw `a:uLn/a:headEnd` XML preserved verbatim. */ headEndXml?: XmlObject; /** Raw `a:uLn/a:tailEnd` XML preserved verbatim. */ tailEndXml?: XmlObject; }; /** When `` is present — underline line follows the text run line. */ underlineLineFollowsText?: boolean; /** When `` is present — underline fill follows the text run fill. */ underlineFillFollowsText?: boolean; strikethrough?: boolean; /** Specific strike type: single or double from `a:rPr/@strike`. */ strikeType?: 'sngStrike' | 'dblStrike'; /** Text outline width in px (`a:rPr > a:ln/@w` in EMU). */ textOutlineWidth?: number; /** Text outline colour as hex string (`a:rPr > a:ln > a:solidFill`). */ textOutlineColor?: string; /** Text outline dash preset (`a:rPr > a:ln > a:prstDash/@val`), e.g. `dash`; absent for solid. */ textOutlineDash?: string; /** When true, the text body has no fill (`a:rPr > a:noFill`), producing hollow/outline-only text. */ textFillNone?: boolean; /** * When true, the run authored an EMPTY ``: an explicit "no * effects" override that blocks an inherited shadow or glow. Kept so a * rewrite re-emits it instead of letting the inherited effect return. */ textEffectsExplicitNone?: boolean; /** Superscript/subscript baseline shift as percentage (`a:rPr/@baseline`). Positive = super, negative = sub. */ baseline?: number; /** Character spacing in hundredths of a point (`a:rPr/@spc`). */ characterSpacing?: number; /** Kerning threshold in hundredths of a point (`a:rPr/@kern`). 0 = none. */ kerning?: number; /** Text highlight colour as hex string (`a:highlight`). */ highlightColor?: string; /** * Raw colour-choice XML preserved from `a:highlight` so a themed highlight * (`a:schemeClr` / `a:sysClr` / `a:prstClr`) re-emits with its original * identity rather than being flattened to `` on save. On save we * re-emit verbatim when the resolved {@link highlightColor} still matches. */ highlightColorXml?: XmlObject; /** Text-level gradient fill CSS string (from `a:rPr > a:gradFill`). */ textFillGradient?: string; /** Structured gradient stops for text fill round-trip serialization. */ textFillGradientStops?: Array<{ color: string; position: number; opacity?: number; }>; /** Gradient angle in degrees for text fill round-trip. */ textFillGradientAngle?: number; /** Gradient type for text fill round-trip ('linear' | 'radial'). */ textFillGradientType?: 'linear' | 'radial'; /** Text-level pattern fill preset (from `a:rPr > a:pattFill`). */ textFillPattern?: string; /** Text-level pattern foreground colour. */ textFillPatternForeground?: string; /** Text-level pattern background colour. */ textFillPatternBackground?: string; /** * Raw `a:rPr > a:blipFill` XML, preserved verbatim for round-trip * serialization AND as the input to the image resolution pass that fills * in {@link textFillBlipUrl} (parsing a run's fill happens synchronously, * with no zip/relationship access at that point; resolving the blip to a * displayable URL needs both, so it happens in a later async pass over * the slide's parsed elements, mirroring how a shape's OWN image fill is * resolved). A picture-filled text run (`a:rPr > a:blipFill`) was * documented as handled ("Handles gradient fills, pattern fills, and * image fills on text runs") but never actually parsed, so it silently * fell through to the run's plain `color` and rendered solid black * (COM-verified: `audit-text` slide 13's "PICTURE FILL" run shows the * fill image through the glyphs in PowerPoint). */ textFillBlipXml?: XmlObject; /** Resolved displayable URL for {@link textFillBlipXml}, or the archive-relative path when unresolved (lazy decode). */ textFillBlipUrl?: string; /** Tiling mode for {@link textFillBlipUrl} (`a:blipFill/a:tile` present -> 'tile', else 'stretch'). */ textFillBlipMode?: 'stretch' | 'tile'; hyperlink?: string; /** Relationship ID for the hyperlink (`a:hlinkClick/@r:id`) — preserved for round-trip serialization. */ hyperlinkRId?: string; /** Hyperlink tooltip text (`a:hlinkClick/@tooltip`). */ hyperlinkTooltip?: string; /** Hyperlink action type (`a:hlinkClick/@action`). */ hyperlinkAction?: string; /** Whether the hyperlink target is an internal slide jump (targetSlideIndex style). */ hyperlinkTargetSlideIndex?: number; color?: string; /** * Raw XML colour-choice node preserved from `a:rPr/a:solidFill` for * round-trip serialisation. Captures `a:schemeClr` / `a:sysClr` / * `a:prstClr` / `a:srgbClr` plus colour transforms. On save we re-emit * verbatim when the resolved {@link color} still matches this node. */ colorXml?: XmlObject; /** * Typed theme colour reference for the run's text colour, set when * {@link colorXml} is a plain `a:schemeClr` (see * `themeColorRefFromColorChoice`). When present it WINS on save: the * writer emits `` from this ref instead of the resolved * {@link color}, so the text keeps following the theme palette after a * later theme change. */ colorRef?: PptxThemeColorRef; align?: 'left' | 'center' | 'right' | 'justify' | 'justLow' | 'dist' | 'thaiDist'; /** * Vertical text-box anchor (`a:bodyPr/@anchor`, `ST_TextAnchoringType`). * `distributed`/`justified` (`dist`/`just`) stretch line spacing so the * paragraph block fills the box's full vertical extent, distinct from true * centering (`middle`/`ctr`); both approximate to a middle-anchored render * (see `text-body-layout.ts`) since CSS has no native vertical-justify * primitive, but round-trip losslessly through parse/save. */ vAlign?: 'top' | 'middle' | 'bottom' | 'distributed' | 'justified'; /** Right-to-left paragraph/run direction (`a:pPr/@rtl`, `a:rPr/@rtl`). */ rtl?: boolean; /** Body text direction (`a:bodyPr/@vert`). * * Values map to OOXML `a:bodyPr/@vert` attribute values: * - `"horizontal"` — default horizontal text (`horz`) * - `"vertical"` — standard vertical text, right-to-left columns (`vert`) * - `"vertical270"` — text rotated 270 degrees (`vert270`) * - `"eaVert"` — East Asian vertical text with CJK glyphs upright (`eaVert`) * - `"wordArtVert"` — WordArt vertical, each character upright stacked (`wordArtVert`) * - `"wordArtVertRtl"` — WordArt vertical, right-to-left direction (`wordArtVertRtl`) * - `"mongolianVert"` — Mongolian vertical text, left-to-right columns (`mongolianVert`) */ textDirection?: 'horizontal' | 'vertical' | 'vertical270' | 'eaVert' | 'wordArtVert' | 'wordArtVertRtl' | 'mongolianVert'; /** Body column count (`a:bodyPr/@numCol`). */ columnCount?: number; /** Column spacing in px (`a:bodyPr/@spcCol` in EMU). */ columnSpacing?: number; /** Horizontal overflow mode from `a:bodyPr/@hOverflow`. */ hOverflow?: 'overflow' | 'clip'; /** Vertical overflow mode from `a:bodyPr/@vertOverflow`. */ vertOverflow?: 'overflow' | 'clip' | 'ellipsis'; /** Body text left inset in px (`a:bodyPr/@lIns` in EMU). */ bodyInsetLeft?: number; /** Body text top inset in px (`a:bodyPr/@tIns` in EMU). */ bodyInsetTop?: number; /** Body text right inset in px (`a:bodyPr/@rIns` in EMU). */ bodyInsetRight?: number; /** Body text bottom inset in px (`a:bodyPr/@bIns` in EMU). */ bodyInsetBottom?: number; /** Paragraph spacing before in px. */ paragraphSpacingBefore?: number; /** Paragraph spacing after in px. */ paragraphSpacingAfter?: number; /** Line spacing multiplier (e.g. 1.2 = 120%). Used when mode is proportional (spcPct). */ lineSpacing?: number; /** Exact line spacing in points (from `a:lnSpc > a:spcPts`). Takes priority over `lineSpacing` when set. */ lineSpacingExactPt?: number; /** Paragraph left margin in px (`a:pPr/@marL` in EMU). */ paragraphMarginLeft?: number; /** Paragraph right margin in px (`a:pPr/@marR` in EMU). */ paragraphMarginRight?: number; /** Paragraph first-line indent in px (`a:pPr/@indent` in EMU). */ paragraphIndent?: number; /** Tab stop positions and alignments (`a:pPr/a:tabLst/a:tab`). */ tabStops?: Array<{ position: number; align: 'l' | 'ctr' | 'r' | 'dec'; leader?: 'none' | 'dot' | 'hyphen' | 'underscore'; /** * True when the source spelled out the schema-default `@algn="l"`, so the * writer re-emits it instead of treating it as an omitted default. */ alignAuthored?: boolean; /** True when the source spelled out the schema-default `@leader="none"`. */ leaderAuthored?: boolean; }>; /** * True when the paragraph's own `a:pPr` authored an EMPTY `` * (explicitly "no tab stops", overriding whatever the cascade would * otherwise supply) rather than omitting the element entirely (inherit). * fast-xml-parser gives a childless element as the empty string, so * `tabLst` and no-`tabLst` are otherwise indistinguishable once `tabStops` * comes back empty either way. Paragraph-scope only; not part of the * element-level geometry cascade. */ tabStopsExplicitEmpty?: boolean; /** Body text wrapping mode from `a:bodyPr/@wrap`. */ textWrap?: 'square' | 'none'; /** Preset text warp type from `a:bodyPr/a:prstTxWarp`. */ textWarpPreset?: PptxTextWarpPreset; /** Primary adjustment value for text warp (from `a:prstTxWarp/a:avLst/a:gd` with name "adj"). * Stored as raw OOXML 1/60000th units (e.g. 50000 = default for many presets). */ textWarpAdj?: number; /** Secondary adjustment value for text warp (from `a:prstTxWarp/a:avLst/a:gd` with name "adj2"). * Stored as raw OOXML 1/60000th units. */ textWarpAdj2?: number; /** Text capitalization style from `a:rPr/@cap`. */ textCaps?: 'all' | 'small' | 'none'; /** * When true, the source authored `` explicitly. This * differs from {@link textCaps} = `"none"` only because the writer must * preserve the explicit token rather than collapse it to omission. */ textCapsExplicitNone?: boolean; /** Symbol font family from `a:sym`. */ symbolFont?: string; /** East Asian font family from `a:ea`. */ eastAsiaFont?: string; /** Complex Script font family from `a:cs`. */ complexScriptFont?: string; /** * Theme-font token (`+mj-lt` / `+mn-lt` / ...) authored on `a:latin`, when * present. {@link fontFamily} holds the resolved concrete face for * rendering; this preserves the token linkage so the writer re-emits the * token rather than the flattened face (see #84). */ latinFontThemeToken?: string; /** Theme-font token authored on `a:ea` (e.g. `+mn-ea`), when present. */ eastAsiaFontThemeToken?: string; /** Theme-font token authored on `a:cs` (e.g. `+mn-cs`), when present. */ complexScriptFontThemeToken?: string; /** * Automatic per-script fallback face resolved from the theme's * `` overrides for a run whose text is dominantly * CJK / Arabic / Hebrew / Thai (see #83). A rendering hint only: it is not * serialised back on save, so it never disturbs the round-trip typefaces. */ scriptFallbackFont?: string; /** * Set alongside {@link scriptFallbackFont} when the resolved {@link fontFamily} * came only from the paragraph/list-style/theme CASCADE (the run's own * `a:rPr` authored no `a:latin`/`a:ea`/`a:cs` of its own). A run always * inherits SOME font this way (typically the theme's `+mn-lt`), so without * this flag `fontFamily` was indistinguishable from a run that genuinely * chose that font itself, and the renderer never applied the theme's * per-script override (see #83): `+mn-lt` names only the LATIN member of * the font scheme and was never meant to cover text in a different * dominant script. An explicit `a:latin`/`a:ea`/`a:cs` authored on the run * itself still always wins; only the cascade default yields to the * script-specific override. */ fontFamilyIsCascadeDefault?: boolean; /** Text language from `a:rPr/@lang`. */ language?: string; /** Hyperlink mouse-over target from `a:hlinkMouseOver`. */ hyperlinkMouseOver?: string; /** * Raw `a:snd` (embedded WAV audio) child of `a:hlinkClick`, preserved * verbatim (carries `@r:embed` + `@name`). Round-tripped on save so the * click sound survives instead of being dropped. */ hyperlinkSoundXml?: XmlObject; /** Raw `a:snd` child of `a:hlinkMouseOver`, preserved verbatim for round-trip. */ hyperlinkMouseOverSoundXml?: XmlObject; /** Hyperlink invalidUrl attribute (`a:hlinkClick/@invalidUrl`). */ hyperlinkInvalidUrl?: string; /** Hyperlink target frame (`a:hlinkClick/@tgtFrame`). */ hyperlinkTargetFrame?: string; /** Whether hyperlink history is tracked (`a:hlinkClick/@history`). */ hyperlinkHistory?: boolean; /** Whether hyperlink uses highlight-click effect (`a:hlinkClick/@highlightClick`). */ hyperlinkHighlightClick?: boolean; /** Whether hyperlink ends a sound (`a:hlinkClick/@endSnd`). */ hyperlinkEndSound?: boolean; /** * Raw `a:hlinkClick/a:extLst` child, preserved verbatim for round-trip. * Carries vendor extensions this engine does not interpret, most commonly * `ahyp:hlinkClr` (Microsoft's "hyperlink color" extension, * `{A12FA001-AC4F-418D-AE19-62706E023703}`), which records whether a * hyperlink run should paint with the theme's text colour instead of the * hyperlink colour. Dropping the whole `a:extLst` silently reverted such a * run to the default (themed) hyperlink colour on save. */ hyperlinkExtensionXml?: XmlObject; /** Kumimoji (ideographic text combining) flag for vertical CJK text (`a:rPr/@kumimoji`). */ kumimoji?: boolean; /** Normalize height flag (`a:rPr/@normalizeH`). */ normalizeHeight?: boolean; /** No proofing flag (`a:rPr/@noProof`). */ noProof?: boolean; /** Dirty flag indicating run has been edited (`a:rPr/@dirty`). */ dirty?: boolean; /** Error flag indicating spelling error (`a:rPr/@err`). */ spellingError?: boolean; /** Smart tag clean flag (`a:rPr/@smtClean`). */ smartTagClean?: boolean; /** Bookmark link target (`a:rPr/@bmk`). */ bookmark?: string; /** Alternative language for the run (`a:rPr/@altLang`). Populated for runs * authored in mixed-script documents (e.g. Asian/Latin combined). */ altLanguage?: string; /** SmartTag (Office grammar tag) GUID id (`a:rPr/@smtId`). Round-tripped * verbatim — the engine doesn't interpret it. */ smartTagId?: number; /** Latin font PANOSE classification string from `a:rPr > a:latin/@panose`. */ latinFontPanose?: string; /** Latin font pitch + family flag from `a:rPr > a:latin/@pitchFamily`. */ latinFontPitchFamily?: number; /** Latin font character set id from `a:rPr > a:latin/@charset`. */ latinFontCharset?: number; /** East-Asian font PANOSE from `a:rPr > a:ea/@panose`. */ eastAsiaFontPanose?: string; /** East-Asian font pitch + family flag from `a:rPr > a:ea/@pitchFamily`. */ eastAsiaFontPitchFamily?: number; /** East-Asian font character set id from `a:rPr > a:ea/@charset`. */ eastAsiaFontCharset?: number; /** Complex-script font PANOSE from `a:rPr > a:cs/@panose`. */ complexScriptFontPanose?: string; /** Complex-script font pitch + family flag from `a:rPr > a:cs/@pitchFamily`. */ complexScriptFontPitchFamily?: number; /** Complex-script font character set id from `a:rPr > a:cs/@charset`. */ complexScriptFontCharset?: number; /** Symbol-font PANOSE from `a:rPr > a:sym/@panose`. */ symbolFontPanose?: string; /** Symbol-font pitch + family flag from `a:rPr > a:sym/@pitchFamily`. */ symbolFontPitchFamily?: number; /** Symbol-font character set id from `a:rPr > a:sym/@charset`. */ symbolFontCharset?: number; /** Paragraph list type for toggling bullet / numbered lists via the toolbar. * - `'bullet'` — character bullet (default "•") * - `'numbered'` — auto-numbered list (arabicPeriod) * - `'none'` — explicitly no list */ listType?: 'bullet' | 'numbered' | 'none'; /** Default tab size in px (`a:pPr/@defTabSz` in EMU). */ defaultTabSize?: number; /** East Asian line break flag (`a:pPr/@eaLnBrk`). */ eaLineBreak?: boolean; /** Latin line break flag (`a:pPr/@latinLnBrk`). */ latinLineBreak?: boolean; /** Font alignment (`a:pPr/@fontAlgn`): 'auto' | 'base' | 'ctr' | 't' | 'b'. */ fontAlignment?: string; /** Hanging punctuation flag (`a:pPr/@hangingPunct`). */ hangingPunctuation?: boolean; /** Whether to space first and last paragraph from body edges (`a:bodyPr/@spcFirstLastPara`). */ spaceFirstLastParagraph?: boolean; /** Right-to-left column flow (`a:bodyPr/@rtlCol`). */ rtlColumns?: boolean; /** Whether text originates from WordArt (`a:bodyPr/@fromWordArt`). */ fromWordArt?: boolean; /** Whether text anchoring is centered (`a:bodyPr/@anchorCtr`). */ anchorCenter?: boolean; /** Force anti-aliasing (`a:bodyPr/@forceAA`). */ forceAntiAlias?: boolean; /** Upright text in 3D views (`a:bodyPr/@upright`). */ upright?: boolean; /** Compatible line spacing flag (`a:bodyPr/@compatLnSpc`). */ compatibleLineSpacing?: boolean; /** * Text body rotation in **degrees** (`a:bodyPr/@rot`). * * OOXML stores the value as 60000ths of a degree. Positive values rotate * the body clockwise. When undefined, the attribute is omitted on save * (PowerPoint treats absent `rot` as inherit/none). */ textBodyRotation?: number; /** Text shadow colour as hex string (`a:outerShdw`). */ textShadowColor?: string; /** Text shadow blur radius in px. */ textShadowBlur?: number; /** Text shadow horizontal offset in px. */ textShadowOffsetX?: number; /** Text shadow vertical offset in px. */ textShadowOffsetY?: number; /** Text shadow opacity (0-1). */ textShadowOpacity?: number; /** Text inner shadow colour (`a:innerShdw`). */ textInnerShadowColor?: string; /** Text inner shadow opacity (0-1). */ textInnerShadowOpacity?: number; /** Text inner shadow blur radius in px. */ textInnerShadowBlur?: number; /** Text inner shadow horizontal offset in px. */ textInnerShadowOffsetX?: number; /** Text inner shadow vertical offset in px. */ textInnerShadowOffsetY?: number; /** * Original inner-shadow colour-choice XML (`a:innerShdw`'s * `a:prstClr`/`a:schemeClr`/`a:srgbClr`/… child), preserved verbatim so an * authored preset or theme colour round-trips instead of always being * re-serialized as a resolved `a:srgbClr`. Mirrors {@link textGlowColorXml}. */ textInnerShadowColorXml?: XmlObject; /** Theme colour slot the inner shadow colour resolved from, when it is `a:schemeClr`. */ textInnerShadowColorRef?: PptxThemeColorRef; /** Preset shadow type from `a:prstShdw/@prst` (e.g. "shdw1"..."shdw20"). */ textPresetShadowName?: string; /** Preset shadow colour as hex string. */ textPresetShadowColor?: string; /** Preset shadow opacity (0-1). */ textPresetShadowOpacity?: number; /** Preset shadow distance in px. */ textPresetShadowDistance?: number; /** Preset shadow direction in degrees. */ textPresetShadowDirection?: number; /** Text blur effect radius in px (`a:blur`). */ textBlurRadius?: number; /** * Text soft-edge radius in px (`a:softEdge/@rad`). * * Feathers the glyph's own edges (a uniform blur of the alpha silhouette, * the same effect a shape's `a:softEdge` gives its fill), unrelated to * `a:blur` (which blurs the whole run, colour included) or a shadow. Never * parsed before this field existed, so `a:softEdge` on a run was silently * dropped: PowerPoint fades the glyphs to near-transparent at their * outline (COM-verified, `audit-text` slide 14's "SOFTEDGE" run), while * the viewer painted them fully crisp. */ textSoftEdgeRadius?: number; /** * Raw `a:effectDag` XML node from `a:rPr`, preserved verbatim for * round-trip serialisation. Mirrors the shape-level * {@link import('./shape-style').ShapeStyle.effectDagXml} field. */ textEffectDagXml?: XmlObject; /** * Typed effect graph parsed from `textEffectDagXml`. The four structural * container nodes (`a:cont`, `a:blend`, `a:xfrmEffect`, `a:relOff`) are * fully typed; any other leaf effect is captured as * {@link import('./effect-dag').EffectDagRawLeaf} so we never have to * recurse into the full effect taxonomy. */ textEffectDagTree?: EffectDagContainer; /** Text alpha modulation fixed (0-100) from `a:alphaModFix`. */ textAlphaModFix?: number; /** Text alpha modulation from `a:alphaMod` (0-100 percentage). */ textAlphaMod?: number; /** Text hue shift in degrees from `a:hsl/@hue`. */ textHslHue?: number; /** Text saturation adjustment from `a:hsl/@sat`. */ textHslSaturation?: number; /** Text luminance adjustment from `a:hsl/@lum`. */ textHslLuminance?: number; /** Text colour change from colour as hex string (`a:clrChange`). */ textClrChangeFrom?: string; /** Text colour change to colour as hex string. */ textClrChangeTo?: string; /** Text duotone colour pair (`a:duotone`). */ textDuotone?: { color1: string; color2: string; }; /** Text glow colour as hex string (`a:glow`). */ textGlowColor?: string; /** Text glow radius in px. */ textGlowRadius?: number; /** Text glow opacity (0-1). */ textGlowOpacity?: number; /** * Original glow colour-choice XML (`a:glow`'s `a:schemeClr`/`a:srgbClr`/… * child), preserved verbatim so a theme colour reference round-trips * instead of always being re-serialized as a resolved `a:srgbClr` (which * cuts the glow off from theme/Recolor changes). */ textGlowColorXml?: XmlObject; /** Theme colour slot the glow colour resolved from, when it is `a:schemeClr`. */ textGlowColorRef?: PptxThemeColorRef; /** Text reflection enabled flag. */ textReflection?: boolean; /** Text reflection blur radius in px. */ textReflectionBlur?: number; /** Text reflection start opacity (0-1). */ textReflectionStartOpacity?: number; /** Text reflection end opacity (0-1). */ textReflectionEndOpacity?: number; /** Text reflection offset distance in px. */ textReflectionOffset?: number; /** * Text reflection end position (`@endPos`) as a 0-1 fraction of the text * height the fade reaches. Mirrors `ShapeStyle.reflectionEndPosition`. */ textReflectionEndPosition?: number; /** * Text reflection offset direction (`@dir`) in degrees. Mirrors * `ShapeStyle.reflectionDirection`. */ textReflectionDirection?: number; /** * Text reflection fade direction (`a:rPr/a:effectLst/a:reflection/@fadeDir`) * in degrees. Mirrors `ShapeStyle.reflectionFadeDirection`. */ textReflectionFadeDirection?: number; /** * Text reflection horizontal scaling (`@sx`), same units as * `ShapeStyle.reflectionScaleX` (1000ths of a percent, e.g. 100000 = 100%). */ textReflectionScaleX?: number; /** Text reflection vertical scaling (`@sy`). See `ShapeStyle.reflectionScaleY`. */ textReflectionScaleY?: number; /** * Text reflection horizontal skew (`@kx`) in 60000ths of a degree. See * `ShapeStyle.reflectionSkewX`. */ textReflectionSkewX?: number; /** Text reflection vertical skew (`@ky`). See `ShapeStyle.reflectionSkewY`. */ textReflectionSkewY?: number; /** * Text reflection independent rotation (`@rot`) in degrees. See * `ShapeStyle.reflectionRotation`. */ textReflectionRotation?: number; /** Text reflection anchor (`@algn`). See `ShapeStyle.reflectionAlignment`. */ textReflectionAlignment?: 'tl' | 't' | 'tr' | 'l' | 'ctr' | 'r' | 'bl' | 'b' | 'br'; /** 3D extrusion/bevel settings on the text body. */ text3d?: Text3DStyle; /** 3D scene (camera + light rig) settings on the text body (`a:bodyPr/a:scene3d`). */ textBodyScene3d?: Pptx3DScene; /** Raw `a:scene3d` subtree used to preserve extensions and unmodelled children. */ textBodyScene3dXml?: XmlObject; /** * `a:bodyPr/a:flatTx` - an explicit "render this text flat" marker. `sp3d` * and `flatTx` are a mutually exclusive OOXML choice (`EG_Text3D`), so a * shape/run that overrides an inherited 3D text body with `` * carries no `text3d` of its own; without this explicit flag a later * inheritance merge has no signal to stop `text3d`/`textBodyScene3d` from * an ancestor (layout/master) leaking back in, the way `noFill` stops an * inherited fill. A renderer must short-circuit 3D-text application * whenever this is `true`, regardless of what `text3d`/`textBodyScene3d` * otherwise hold. */ flatText?: boolean; /** * Raw `` subtree captured from ``. Preserved verbatim so * authored extensions (e.g. content placeholders, custom application data) * survive a round-trip even though the engine doesn't interpret them. */ bodyPropertiesExtLstXml?: XmlObject; /** * Raw `` subtree captured from ``. Only meaningful on the * paragraph-level style (paragraphs propagate this via the first segment). */ paragraphPropertiesExtLstXml?: XmlObject; /** * Raw `` subtree captured from ``. Persisted verbatim on * save when present — covers run-level extensions the typed model doesn't * model (e.g. `a14:hiddenFill` and similar). */ runPropertiesExtLstXml?: XmlObject; /** * Raw `` XML node captured from ``. The schema permits * `defRPr` directly inside `pPr` so that paragraph defaults can specify the * end-paragraph run formatting; previously this was dropped on save. We * persist the parsed XML object so it round-trips verbatim. * * Only meaningful on the *first* segment of each paragraph (matches the * convention used for {@link bulletInfo} / {@link endParaRunProperties}). */ paragraphDefaultRunPropertiesXml?: XmlObject; /** * The bullet colour / size / typeface children (`a:buClrTx`, `a:buClr`, * `a:buSzTx`, `a:buSzPct`, `a:buSzPts`, `a:buFontTx`, `a:buFont`) a * paragraph authored in its own `` WITHOUT a bullet type * (`a:buNone` / `a:buChar` / `a:buAutoNum` / `a:buBlip`), captured * verbatim in source order. Such a paragraph restyles an inherited bullet * rather than declaring one, so its {@link BulletInfo} resolves from the * cascade and is (correctly) not written back; without this capture the * paragraph's own override vanished on every rewrite. * * Only meaningful on a paragraph's own authored properties. */ paragraphBulletPropertiesXml?: XmlObject; } /** * Framework-neutral text-style override a font-style emphasis effect applies * on top of its target's own authored per-run bold/italic/underline/size/ * colour. Every binding maps this onto its own text container so it OVERRIDES * the runs' inline styles (the runs carry explicit inline styles of their * own, so plain CSS inheritance cannot reach them). */ declare interface TextStyleAnimationDescriptor { bold?: boolean; italic?: boolean; underline?: boolean; /** Relative multiplier against each run's own authored font size. */ fontScale?: number; color?: string; } declare interface TextStyleInput { fontSize?: number; fontFamily?: string; bold?: boolean; italic?: boolean; underline?: boolean; strikethrough?: boolean; color?: string; /** A theme colour for the run; see {@link FillInput}'s `themeColorRef`. */ themeColorRef?: PptxThemeColorRef; alignment?: 'left' | 'center' | 'right' | 'justify'; verticalAlignment?: 'top' | 'middle' | 'bottom'; lineSpacing?: number; spaceBefore?: number; spaceAfter?: number; } /** One selectable entry in the viewer chrome's built-in theme picker (File > Options > Appearance). */ declare interface ThemeCatalogEntry { /** Stable identifier persisted to storage and passed to `onThemeChange`. */ key: string; /** `pptx.*` translation key for the entry's display label. */ labelKey: string; /** The theme to apply, or `undefined` to reset to the built-in default. */ theme: ViewerTheme | undefined; } declare type ToolbarActionId = ToolbarButtonId | ToolbarTabId; /** * Toolbar action / ribbon-tab visibility: a single, framework-agnostic * catalogue of every top-level toolbar button and ribbon tab a host app can * independently hide. Each binding exposes a `hiddenActions?: ToolbarActionId[]` * prop, threads it down to the relevant render sites, and gates them with * `isActionHidden`. Default (`undefined` / `[]`) hides nothing, matching * today's always-visible behaviour. * * `TOOLBAR_TABS` is also the canonical ribbon-tab list/order, replacing the * copy hand-duplicated in each binding (React's `TOOLBAR_SECTIONS`, Vue's * `ribbon-constants.ts`, Angular's `RIBBON_TABS`, etc.) so the tab set can't * drift between bindings. Per-tab icons stay in each binding (icon libraries * differ per framework); only id + i18n key + order are shared here. */ /** * A single toolbar button/control that can be hidden independently of the * ribbon tab it may also appear inside. `zoom` and `navigation` each cover a * whole control cluster (zoom in/out/fit, prev/next) rather than each button * in it, matching how hosts actually want to hide/keep them as a unit. */ declare type ToolbarButtonId = 'share' | 'broadcast' | 'export' | 'undo' | 'redo' | 'record' | 'notes' | 'fullscreen' | 'zoom' | 'navigation' | 'mergeShapes' | 'crop'; /** * Ribbon tab id. Mirrors React `ToolbarSection`, plus the contextual tabs * (Shape Format, Picture Format, ...) a selection brings up. */ export declare type ToolbarSection = 'file' | 'home' | 'insert' | 'text' | 'arrange' | 'draw' | 'design' | 'transitions' | 'animations' | 'slideShow' | 'record' | 'review' | 'view' | 'help' | RibbonContextualTabId; /** A top-level ribbon tab. `record` intentionally shares its id with the quick-access Record button above: both surface the same recording feature, so hiding one hides the other. */ declare type ToolbarTabId = 'file' | 'home' | 'insert' | 'draw' | 'design' | 'transitions' | 'animations' | 'slideShow' | 'record' | 'review' | 'view' | 'help'; declare interface TrackedTextPosition { /** Internal identity, shared by snapshots that observed the same character. */ readonly cell: TextPositionCell; readonly association: number; } /** Geometry patch emitted by the selection overlay during a drag/resize/rotate. */ export declare interface TransformPayload { id: string; x: number; y: number; width: number; height: number; rotation: number; } /** Live geometry emitted while (and after) a transform gesture. */ declare interface TransformPayload_2 { id: string; x: number; y: number; width: number; height: number; rotation: number; } declare interface TransitionInput { type: PptxTransitionType; duration?: number; direction?: string; advanceAfterMs?: number; } /** * Shared value types used across the entire PPTX editor type system. * * Contains primitive enums, small interfaces, and the XML object alias * that almost every other type file imports. * * @module pptx-types/common */ /** * Underline style tokens from OOXML `a:rPr/@u`. * * These map directly to the OpenXML `ST_TextUnderlineType` simple type. * * @example * ```ts * const style: UnderlineStyle = "wavy"; * // => "wavy" — one of: sng | dbl | heavy | dotted | dash | wavy | none | ... * ``` */ declare type UnderlineStyle = 'sng' | 'dbl' | 'heavy' | 'dotted' | 'dottedHeavy' | 'dash' | 'dashHeavy' | 'dashLong' | 'dashLongHeavy' | 'dotDash' | 'dotDashHeavy' | 'dotDotDash' | 'dotDotDashHeavy' | 'wavy' | 'wavyHeavy' | 'wavyDbl' | 'words' | 'none'; /** An element whose type is not recognised by the parser. */ declare interface UnknownPptxElement extends PptxElementBase { type: 'unknown'; /** Unrecognised graphicFrame extLst extensions, captured verbatim for round-trip. */ extensionXml?: PptxGraphicFrameExtension[]; } export declare function useCollaboration(options: UseCollaborationOptions): UseCollaborationResult; export declare interface UseCollaborationOptions { /** Optional reactive configuration; replacing or clearing it starts or stops the session. */ collaboration?: MaybeRefOrGetter; /** Host authorization, combined with the session's canonical read-only state. */ canEdit?: MaybeRefOrGetter; /** Whether an actual source file is still loading or failed to load. */ sourcePending?: MaybeRefOrGetter; sourceError?: MaybeRefOrGetter; /** Optional retained serializer for elected-owner write-back; the scheduler guards stale results. */ serialize?: (isCurrent: () => boolean) => Promise | Uint8Array | null; /** The editor's reactive slides ref (broadcast on local change). */ slides: Ref< PptxSlide[]>; /** Called when a remote peer broadcasts a newer slide set. */ onRemoteSlides: (slides: PptxSlide[]) => void; /** This user's cursor/label colour. */ userColor?: string; /** * Slide canvas width/height (unscaled px) used to clamp incoming cursor * coordinates. Defaults to a generous bound when omitted. */ canvasWidth?: Ref | number; canvasHeight?: Ref | number; /** * Return the source PPTX bytes for elected-writer write-back. Only called * when role === 'owner' and config.onWriteBack is provided. */ getSourceBytes?: () => Uint8Array | null; /** * Return the separate per-slide master/layout (template) element store so the * elected-writer write-back can merge template edits back into the saved file. */ getTemplateElements?: () => Record; /** * Session-level save options (view properties, table styles, tags, deck * properties, ...), built the same way as the Save/Export path * (`buildDeckSaveOptions`). Without this the elected-writer write-back * called `handler.save(slides)` with NO options, so an owner's write-back * file dropped every session-level edit outside `slides`. */ getSaveOptions?: () => PptxHandlerSaveOptions; /** * Monotonic counter bumped each time the content-load pipeline finishes * applying a parsed deck to viewer state. A local load that lands while the * shared doc already holds slides (a late joiner's bootstrap deck parsing * after the room state arrived) would silently clobber the synced slides; * each bump re-adopts the doc's slides when the room has content. */ loadVersion?: Ref; /** Why the last content load ran; see `shouldRoomSlidesReplaceLoad`. */ getLoadOrigin?: () => CollabLoadOrigin; } export declare interface UseCollaborationResult { /** Shared custom-shell permissions, connection status and sanitized presence. */ shellState: ComputedRef; /** The configuration attached by start() or the reactive collaboration option. */ activeCollaboration: Ref; status: Ref< ConnectionStatus>; connected: Ref; cursors: Ref; remotePresences: Ref; connectedCount: ComputedRef; active: Ref; /** Blocks edits only while a session is read-only or awaiting host sync. */ readOnly: Ref; /** The local user's role in the active session (undefined when stopped). */ activeRole: Ref; followedClientId: Ref; followedSlideIndex: ComputedRef; broadcasterSlideIndex: ComputedRef; start: (config: CollaborationConfig) => Promise; stop: () => void; retry: () => Promise; setCursor: (x: number, y: number) => void; setSelection: (ids: string[]) => void; setActiveSlide: (index: number) => void; followUser: (clientId: number | null) => void; /** * Interim ("live preview") Y.Doc write channel: publishes in-flight inline * editor text (and any other mid-gesture state) that has not yet reached * `slides`, so peers see typing as it happens instead of on commit. Dormant * until a session starts. */ livePatcher: CollaborationLivePatcher; } /** * Collaboration-aware wrapper over the editor history. Mirrors React's * `useCollaborativeHistory`: the undo/redo stack is still owned by the editor; * this guards each call on availability and tracks the local change count for * future multi-user undo scoping. */ export declare function useCollaborativeHistory(input: UseCollaborativeHistoryInput): UseCollaborativeHistoryResult; export declare interface UseCollaborativeHistoryInput { /** Standard history undo function. */ handleUndo: () => void; /** Standard history redo function. */ handleRedo: () => void; /** Whether undo is available. */ canUndo: Ref | ComputedRef | boolean; /** Whether redo is available. */ canRedo: Ref | ComputedRef | boolean; } export declare interface UseCollaborativeHistoryResult { /** Undo the last local change (no-op when unavailable). */ handleUndo: () => void; /** Redo the last undone local change (no-op when unavailable). */ handleRedo: () => void; /** Whether undo is available. */ canUndo: ComputedRef; /** Whether redo is available. */ canRedo: ComputedRef; } /** * Shared-document/state view over an existing session: the slide-sync lifecycle * controls (start/stop/retry) and connection status. */ export declare function useCollaborativeState(session: UseCollaborationResult): UseCollaborativeStateResult; export declare interface UseCollaborativeStateResult { /** Current connection status. */ status: UseCollaborationResult['status']; /** Whether the session is connected. */ connected: Ref; /** Whether a session is currently active. */ active: Ref; /** Start a session with the given config. */ start: (config: Parameters[0]) => Promise; /** Stop the active session. */ stop: () => void; /** Retry the last session after a timeout or error. */ retry: () => Promise; } /** * @param slides Reactive reference to the live slide array the editor mutates. * A `shallowRef` is recommended for large decks. * @param templateElementsBySlideId Optional reactive store of the per-slide * master/layout (template) elements, snapshotted alongside slides * so edits in `editTemplateMode` are undoable. * @param options Optional tuning knobs (undo depth). */ export declare function useEditorHistory(slides: Ref, templateElementsBySlideId?: Ref, options?: UseEditorHistoryOptions): EditorHistoryResult; /** Optional tuning knobs for the history stack. */ declare interface UseEditorHistoryOptions { /** * Maximum undo depth. Defaults to `MAX_HISTORY_ENTRIES`; File > Options > * Advanced > "Maximum number of undos" threads `resolveHistoryDepth` here. */ maxDepth?: number; } export declare function useEditorOperations(input: UseEditorOperationsInput): EditorOperations; declare interface UseEditorOperationsInput { /** Live slide array. A `shallowRef` is recommended for large decks. */ slides: Ref; /** Index of the slide CRUD/transform operations act upon. */ activeSlideIndex: Ref; /** * Snapshot-before-mutate hook. Called immediately before each committed * change. Pass `useEditorHistory(slides).pushHistory`. */ pushHistory: () => void; /** * Optional selection state (element ids). When provided, operations keep it * in sync: newly added/duplicated elements become selected, removed ones are * deselected. When omitted, an internally-owned selection ref is used. */ selectedElementIds?: Ref; /** * Optional separate store of the per-slide master/layout (template) elements. * When provided, id-routed operations (update / remove / transform / text / * z-order) targeting a template id (`master-` / `layout-` prefix) mutate this * store for the active slide instead of `slides`. */ templateElementsBySlideId?: Ref; } export declare function useElementDrag(input: UseElementDragInput): { hasActivePointerInteraction: () => boolean; startElementDrag: (id: string, event: PointerEvent, wasSelected: boolean) => void; /** Stop window listeners when a custom shell detaches or becomes read-only. */ cancelElementDrag: () => void; onTransformStart: (payload?: { id: string; }) => void; onTransform: (payload: TransformPayload) => void; onTransformEnd: (payload: TransformPayload) => void; onAdjustStart: () => void; onAdjust: (payload: { id: string; adjustments: Record; }) => void; onAdjustEnd: (payload: { id: string; adjustments: Record; }) => void; onConnectorEndpoint: (payload: { id: string; element: PptxElement; }) => void; snapToShape: Ref; snapToGrid: Ref; snapLines: Ref< SnapLine[]>; guides: Ref< Guide[]>; addGuide: (axis: "h" | "v", position?: number) => void; onMoveGuide: (payload: { id: string; position: number; }) => void; onRemoveGuide: (id: string) => void; }; export declare interface UseElementDragInput { findActiveElement: (id: string) => PptxElement | undefined; pushHistory: () => void; effectiveZoom: ComputedRef; activeTemplateElements: ComputedRef; activeSlide: ComputedRef; activeSlideIndex: Ref; slides: Ref; templateElementsBySlideId: Ref; canvasSize: Ref<{ width: number; height: number; }>; enterInlineEdit: (id: string) => void; /** * Grid spacing in CSS px, derived from the deck's authored * `viewProperties.gridSpacing` via the shared `computeGridSpacingPx` * (falls back to `DEFAULT_GRID_SIZE` when the deck has none or hasn't * loaded yet). A `ComputedRef` like `effectiveZoom`, so a later deck load * is picked up without re-creating this composable. */ gridSpacingPx?: ComputedRef; } /** * useElementDrag: canvas pointer-drag-to-move, resize/rotate transform, shape * adjustment, plus the View-tab snap + alignment-guide state that those gestures * consume. One history entry is snapshotted at gesture start; live patches during * the gesture bypass history. Extracted verbatim from `PowerPointViewer.vue`. */ /** The drag/transform/adjust surface, inferred so it cannot drift from the impl. */ export declare type UseElementDragResult = ReturnType; /** * useInlineEditing: element-level inline text editing (entered by tapping an * already-selected element) plus the inline table-cell commit path. Both * commit through `ops.updateElement` so undo/redo works. Extracted verbatim * from `PowerPointViewer.vue`. */ export declare function useInlineEditing(input: UseInlineEditingInput): UseInlineEditingResult; export declare interface UseInlineEditingInput { canEdit: () => boolean; findActiveElement: (id: string) => PptxElement | undefined; ops: EditorOperations; /** * File > Options > Proofing values. When supplied, AutoCorrect runs over the * typed text on commit (inline element edits and table-cell edits only, so * loaded content is never rewritten). */ proofing?: () => ViewerProofingOptions | undefined; /** * Collaboration live-preview channel. Typed text only reaches `slides` (and * therefore the Y.Doc reconcile) on commit, so peers saw nothing while a * peer typed; `updateInlineText` publishes each keystroke through this. */ livePatcher?: () => CollaborationLivePatcher | undefined; /** The slide the edited element belongs to (needed by the live channel). */ activeSlide?: () => PptxSlide | undefined; /** Adopt already-published connected text locally before a host disables editing. */ onConnectedSuspend?: (snapshot: InlineTextEditSnapshot) => void; } export declare interface UseInlineEditingResult { inlineEditingElementId: Ref; inlineEditingText: Ref; inlineEditingElement: ComputedRef; /** Set the in-progress text and mirror it to collaborators. */ updateInlineText: (text: string, snapshot?: InlineTextEditSnapshot) => void; readInlineSnapshot: () => InlineTextEditSnapshot | undefined; isInlineInputPending: () => boolean; onListSession: (event: { controller: InlineListController; active: boolean; }) => void; formatInlineSnapshot: (snapshot: InlineTextEditSnapshot) => boolean; endInlineListSession: () => void; enterInlineEdit: (id: string) => void; commitInlineEdit: () => void; cancelInlineEdit: () => void; commitTableCell: (elementId: string, rowIndex: number, colIndex: number, text: string) => void; } export declare function useLoadContent(content: MaybeRefOrGetter, options?: UseLoadContentOptions): UseLoadContentResult; export declare interface UseLoadContentOptions { /** Current list edit only; serialization does not blur or commit the editor. */ getPendingInlineEdit?: () => PendingInlineTextEdit | undefined; /** * Called after a parse fully applies to viewer state (slides & co.). * Collaboration uses this to re-adopt the shared doc's slides when a local * load lands mid-session and would otherwise clobber remotely-synced state. */ onContentApplied?: () => void; /** * The File > Info > Protect Presentation state, read at save time. When it * yields a password the deck is serialised through `saveEncrypted` (an OLE2 * container), not `save` (a plain ZIP). A getter rather than a value so the * secret is always the current one, no matter when the dialog set it. */ getSaveIntent?: () => DeckSaveIntent; /** * The File > Fonts "Embed fonts in the file" toggle, read at save time. * `false` strips `p:embeddedFontLst`, the `/font` relationships and the * `.fntdata` parts; the default (omitted, or `true`) keeps whatever the deck * arrived with. A getter, not a value, for the same reason as * {@link getSaveIntent}: the composable is created before the panel that * owns the flag, and the answer must be the current one. */ getEmbedFonts?: () => boolean; /** * Trust Center > "Allow external content (remote images and media)", read * at load time. `false` (core's own default) makes `getImageData` drop any * `http://`/`https://` image URL instead of fetching it; omitted defaults to * `true` (fetch them), matching this option's own default. A getter, not a * value, so a later options-store change is picked up on the next load * without re-wiring this composable, the same convention as * {@link getSaveIntent} and {@link getEmbedFonts}. */ getAllowExternalImages?: () => boolean; } /** * `useLoadContent`: Vue port of the React hook of the same name. * * Watches a reactive `content` source and parses it into reactive viewer * state via the framework-agnostic `PptxHandler` from `pptx-viewer-core`. * The heavy lifting (ZIP, XML parse, theme/master/layout resolution, media * extraction) all lives in core; this composable only wires the async load * into Vue reactivity and manages Blob-URL / handler lifecycle. * * Differences vs. React: * - The `useEffect(..., [content])` cleanup pattern becomes a `watch` with a * cancellation token plus `onScopeDispose` for unmount cleanup. * - State setters become returned `ref`s mutated in place. * * Originally the viewer-first subset of the React hook; the extra pieces of * presentation metadata (sections, custom shows, embedded fonts, digital * signatures, etc.) were added alongside the corresponding features. */ export declare interface UseLoadContentResult { /** Parsed slides (with image Blob URLs patched in), template elements removed. */ slides: ShallowRef; /** * Master/layout (template) elements pulled out of each slide at load time, * keyed by `slide.id`. Edited in `editTemplateMode` and merged back (behind the * slide content) by every save path via {@link buildSaveSlides}. */ templateElementsBySlideId: ShallowRef; /** Slide canvas size in pixels. */ canvasSize: Ref; /** * The slide size in EMU (`p:sldSz`), seeded from the loaded deck and updated * by the inspector's preset / orientation controls. * * Held ALONGSIDE {@link canvasSize} rather than derived from it because the * pixel round-trip is lossy: Ledger is 12179300 EMU = 1278.5px, and rounding * that to an integer pixel and back moves it far enough to lose the deck's * `ppSlideSizeLedgerPaper` identity. `resolveSlideSizeSelection` decides * which of the two wins whenever they disagree. */ slideSize: Ref; /** Resolved presentation theme. */ theme: ShallowRef; /** Theme colour map (`accent1`→hex, …) used to re-resolve colours on theme switch. */ themeColorMap: ShallowRef | undefined>; /** Slide masters (for placeholder/background resolution). */ slideMasters: ShallowRef; /** Slide-layout choices for the New-Slide gallery (`{ path, name }`). */ layoutOptions: ShallowRef; /** Archive-path → displayable URL map for media + poster frames. */ mediaDataUrls: ShallowRef>; /** True while a load is in flight. */ loading: Ref; /** Error message from the last failed load, or null. */ error: Ref; /** True when the file is password-protected and could not be opened. */ isEncrypted: Ref; /** The live `PptxHandler` for the loaded file (or null). */ handler: ShallowRef; /** Parsed document core properties (title/author/subject/…). */ coreProperties: ShallowRef; /** Parsed custom document properties (name/type/value), empty when none. */ customProperties: ShallowRef; /** Parsed application properties (manager/company/…), or undefined. */ appProperties: ShallowRef; /** Parsed `ppt/tags/tag*.xml` collections (name/value pairs), empty when none. */ tagCollections: ShallowRef; /** Embedded fonts (for `@font-face` injection). */ embeddedFonts: ShallowRef; /** Parsed digital signatures (empty when unsigned). */ signatures: ShallowRef; /** * Parsed `ppt/tableStyles.xml` map (GUID → style entry), or `undefined` * when the presentation has no table styles part. Feeds table banding / * header colour resolution by table-style GUID. */ tableStyleMap: ShallowRef; /** `ppt/tableStyles.xml`'s `` default style GUID. */ tableStylesDefaultId: ShallowRef; /** * Style GUIDs deleted from `tableStyleMap` via the table style editor, * pending removal from `ppt/tableStyles.xml` on the next save. See * `tableStyleSaveOptions` / `applyTableStyleDelete` in `pptx-viewer-shared`. */ tableStylesToDelete: ShallowRef; /** Ordered presentation sections (`p:sectionLst`), empty when none. */ sections: ShallowRef; /** Named custom slide shows (`p:custShowLst`), empty when none. */ customShows: ShallowRef; /** * Modern comment authors (`ppt/commentAuthors.xml`'s `p188:` schema), used * to seed the `@`-mention typeahead (`matchCommentMentionAuthors`, * `pptx-viewer-shared`). Empty when the deck has no modern comments. */ modernCommentAuthors: ShallowRef; /** Legacy comment authors (`p:cm`'s original `ppt/commentAuthors.xml` schema), empty when none. */ commentAuthors: ShallowRef; /** Presentation-level slide-show properties (`presentationPr.xml`); reactive so Set Up Slide Show persists. */ presentationProperties: ShallowRef; /** * View properties (`ppt/viewProps.xml`, `p:viewPr`): grid spacing, snap / * guide toggles, last view, splitter state, etc. `gridSpacing` lives here, * NOT on `presentationProperties` -- `p:gridSpacing` is a child of * `p:viewPr`, and a real PowerPoint file never populates it under * `p:presentationPr`. */ viewProperties: ShallowRef; /** Presentation-level header/footer settings, or `undefined`. */ headerFooter: ShallowRef; /** Parsed notes master, or `undefined` when absent. */ notesMaster: ShallowRef; /** Parsed handout master, or `undefined` when absent. */ handoutMaster: ShallowRef; /** Theme parts discovered in the package (`{ path, name }`), empty when none. */ themeOptions: ShallowRef; /** Notes page size in pixels (`p:notesSz`), or `undefined` when absent. */ notesCanvasSize: Ref; /** * Write-protection verifier from `p:modifyVerifier` (`presentationPr.xml`), * or `undefined` when the deck carries none. Feeds * `readOnlyRecommendation` (`pptx-viewer-shared`), which the read-only * banner uses to default a password-protected deck open read-only. */ modifyVerifier: ShallowRef; /** * `handler.getCompatibilityWarnings()` right after this load: every * warning the parse reported, deck-scoped and slide-scoped alike (the * same list `attachSlideWarnings` partitions per slide, read back whole). * Feeds `compatibilityWarningToasts` (`pptx-viewer-shared`) for the * compat-warning toast stack. */ compatibilityWarnings: ShallowRef; /** Serialise the current presentation back to `.pptx` bytes. */ getContent: () => Promise; /** * Serialise for bytes this viewer will read back itself: the autosave * crash-recovery snapshot, and the re-serialise-then-reload cycle behind * "apply theme". Always a plain ZIP even when the deck is password * protected, because neither reader can supply the password (see * `deck-save-encryption` in `pptx-viewer-shared` for the rationale and the * privacy tradeoff it accepts). */ getRecoverySnapshot: () => Promise; /** Serialise to a specific OpenXML format (pptx / ppsx / pptm). */ saveAs: (format: PptxSaveFormat) => Promise; } /** * Presence/awareness view over an existing session: which peers are connected, * their cursors, and the outgoing presence broadcasters. */ export declare function usePresenceTracking(session: UseCollaborationResult): UsePresenceTrackingResult; export declare interface UsePresenceTrackingResult { /** Remote peers' full published presence (identity, cursor, selection). */ remotePresences: Ref; /** Remote cursor overlays projected onto the local canvas. */ cursors: Ref; /** Total connected participants (remote peers plus self when active). */ connectedCount: ComputedRef; /** The peer currently being followed, if any. */ followedClientId: Ref; /** Broadcast the local cursor position. */ setCursor: (x: number, y: number) => void; /** Broadcast the local selection. */ setSelection: (ids: string[]) => void; /** Broadcast the local active slide index. */ setActiveSlide: (index: number) => void; /** Follow (or unfollow with `null`) a remote peer. */ followUser: (clientId: number | null) => void; } /** * Transport/session owner. Creates (and tears down) the Yjs document and * provider lifecycle and exposes the connection controls. The React counterpart * of the same name owns the transport layer too; the presence and slide-state * projections below take the returned session so they all share one connection. */ export declare function useYjsProvider(options: UseCollaborationOptions): UseCollaborationResult; declare interface ViewerAccessibilityOptions { showAccessibilityStatus: boolean; feedbackWithSound: boolean; soundScheme: FeedbackSoundScheme; showShortcutKeysInScreenTips: boolean; reducedMotion: boolean; } declare interface ViewerAdvancedOptions { autoSelectEntireWord: boolean; allowTextDragAndDrop: boolean; maximumUndoSteps: number; useSmartCutAndPaste: boolean; showPasteOptionsButton: boolean; imageDefaultResolution: ImageResolutionPreset; doNotCompressImages: boolean; chartPropertiesFollowDataPoint: boolean; recentPresentationsCount: number; showVerticalRuler: boolean; showGrid: boolean; snapToGrid: boolean; disableHardwareAcceleration: boolean; /** * Force every opt-in interactive 3D scene (SmartArt, bar/line/area/pie/ * surface charts) to fall back to its flat 2D rendering, even when the * host has enabled that scene via its own `smartArt3D`/`*Chart3D` prop. * A host opting in says "this deck may want 3D"; this is the viewer * user's own override for when the WebGL scenes it renders are too much * for their machine. See `resolve3DRenderingFlags`. */ disable3DRendering: boolean; /** * `p:animEffect/@filter="pixelate"` defaults to snapping the element to * its end state (`cutIn`/`cutOut`), matching PowerPoint's own behaviour * (COM `CreateVideo` frame-diffing shows PowerPoint performs no animation * at all for this filter value). This turns on the blocky mosaic reveal * this renderer can build instead, for a viewer that would rather show * something animating than PowerPoint's own instant swap. See * `resolveFilterEffect` in `animation-filter-effects.ts` and * `docs/guide/visual-effects.md`. */ pixelateMosaicAnimation: boolean; openDocumentsView: OpenDocumentsView; slideShowShowMenuOnRightClick: boolean; slideShowShowPopupToolbar: boolean; slideShowPromptKeepInkAnnotations: boolean; slideShowEndWithBlackSlide: boolean; printInBackground: boolean; printHighQuality: boolean; printUseMostRecentSettings: boolean; printWhat: OptionsPrintWhat; printColorMode: OptionsPrintColorMode; printHiddenSlides: boolean; printScaleToFit: boolean; printFrameSlides: boolean; } /** * The whole customisation object. Every field is optional; omitted fields hide * nothing and lock nothing. */ declare interface ViewerCustomization { ribbon?: RibbonCustomization; options?: OptionsCustomization; backstage?: BackstageCustomization; contextMenu?: ContextMenuCustomization; keyboard?: KeyboardCustomization; /** Chrome regions to remove (`true` hides). */ hiddenPanels?: readonly ViewerPanelId[]; /** Feature areas to switch off (their buttons, menus, pages and panels). */ disabledFeatures?: readonly ViewerFeatureId[]; /** Dialogs to remove, along with every entry point that opens them. */ hiddenDialogs?: readonly ViewerDialogId[]; /** Export formats to remove from File > Export. */ hiddenExportFormats?: readonly ViewerExportFormatId[]; /** Drawing tools to remove from the Insert > Shapes gallery. */ hiddenDrawingTools?: readonly ViewerDrawingToolId[]; } /** The imperative methods every binding's component handle exposes. */ declare interface ViewerCustomizationApi { /** The current customisation object (a snapshot; do not mutate). */ getCustomization(): ViewerCustomization; /** Replace the whole customisation. */ setCustomization(next: ViewerCustomization): void; /** Merge a partial customisation (see `mergeCustomization`). */ updateCustomization(patch: ViewerCustomization): void; /** Drop every customisation, back to the stock UI. */ resetCustomization(): void; /** Hide a fixed tab, or stop a contextual tab (`shapeFormat`, ...) from appearing. */ hideRibbonTab(tab: ToolbarTabId | RibbonContextualTabId): void; showRibbonTab(tab: ToolbarTabId | RibbonContextualTabId): void; /** Hide a group inside a tab (`home.font`). */ hideRibbonGroup(group: RibbonGroupId): void; showRibbonGroup(group: RibbonGroupId): void; /** Hide a top-level toolbar button or any ribbon control (`home.font.bold`). */ hideToolbarButton(button: ToolbarButtonId | RibbonControlId): void; showToolbarButton(button: ToolbarButtonId | RibbonControlId): void; /** Alias of `hideToolbarButton` for a ribbon control id. */ hideRibbonControl(control: RibbonControlId): void; showRibbonControl(control: RibbonControlId): void; hideOptionsPage(page: OptionsPageId): void; showOptionsPage(page: OptionsPageId): void; hideOptionsSection(section: OptionsSectionId): void; showOptionsSection(section: OptionsSectionId): void; hideSetting(setting: OptionsSettingId): void; showSetting(setting: OptionsSettingId): void; /** Pin a setting to `value`; `hidden` also removes it from the dialog. */ lockSetting(setting: OptionsSettingId, value: ViewerOptionPrimitive, hidden?: boolean): void; unlockSetting(setting: OptionsSettingId): void; /** Set (or with `undefined`, clear) the host default for a setting. */ setSettingDefault(setting: OptionsSettingId, value: ViewerOptionPrimitive | undefined): void; hideBackstagePage(page: BackstagePage): void; showBackstagePage(page: BackstagePage): void; hideBackstageCard(card: BackstageCardId): void; showBackstageCard(card: BackstageCardId): void; hideContextMenuCommand(command: ContextMenuCommandId): void; showContextMenuCommand(command: ContextMenuCommandId): void; hideCanvasContextMenuCommand(command: CanvasContextMenuCommandId): void; showCanvasContextMenuCommand(command: CanvasContextMenuCommandId): void; disableShortcut(action: EditorKeyActionName): void; enableShortcut(action: EditorKeyActionName): void; /** Move a command onto new chord(s); `undefined` restores the built-in chord. */ remapShortcut(action: EditorKeyActionName, chords: ShortcutChord | readonly ShortcutChord[] | undefined): void; setPanelVisible(panel: ViewerPanelId, visible: boolean): void; setFeatureEnabled(feature: ViewerFeatureId, enabled: boolean): void; setDialogAvailable(dialog: ViewerDialogId, available: boolean): void; } /** Dialogs (and the entry points that open them) a host can remove. */ declare type ViewerDialogId = 'options' | 'share' | 'broadcast' | 'print' | 'export'; /** * The click-to-place drawing tools of Insert > Shapes > Lines: Freeform: * Shape and Curve. */ declare type ViewerDrawingToolId = FreeformToolKind; /** Export formats offered by the File > Export page. */ declare type ViewerExportFormatId = 'pdf' | 'png' | 'video' | 'gif' | 'json' | 'copyImage'; /** Feature areas that can be switched off as a whole. */ declare type ViewerFeatureId = 'ai' | 'collaboration' | 'comments' | 'presentMode' | 'editPoints'; /** * A font supplied by the host application. The package never ships fonts: * applications provide a licensed URL, data URL, or blob URL for their users. */ declare interface ViewerFontSource { family: string; src: string; format?: 'truetype' | 'opentype' | 'woff' | 'woff2'; weight?: string | number; style?: 'normal' | 'italic'; } declare interface ViewerGeneralOptions { displayOptimization: DisplayOptimization; showMiniToolbar: boolean; enableLivePreview: boolean; collapseRibbonAutomatically: boolean; collapseSearchByDefault: boolean; screenTipStyle: ScreenTipStyle; userName: string; userInitials: string; showStartScreen: boolean; /** * Lets the user hand a local font file to the viewer so decks authored * with a font the browser lacks render with the real face. * * Off by default. The registration reads a file the user picks and adds it * to the page's font set for the session, which is a capability a host * embedding the viewer should opt into rather than inherit. */ enableCustomFontUpload: boolean; } /** Viewer interaction mode: read-only, edit, presentation, or master-view. */ declare type ViewerMode = 'preview' | 'edit' | 'present' | 'master'; /** Viewer interaction mode. Mirrors React `ViewerMode`. */ declare type ViewerMode_2 = 'preview' | 'edit' | 'present' | 'master'; declare type ViewerOptionPrimitive = boolean | number | string; declare interface ViewerOptions { general: ViewerGeneralOptions; proofing: ViewerProofingOptions; save: ViewerSaveOptions; accessibility: ViewerAccessibilityOptions; advanced: ViewerAdvancedOptions; ribbon: ViewerRibbonOptions; quickAccess: ViewerQuickAccessOptions; trust: ViewerTrustOptions; } declare type ViewerOptionsGroupId = keyof ViewerOptions; /** * Control/section/tab descriptor types for the File > Options schema, plus * the terse constructors the tab-definition modules build panes with. */ declare type ViewerOptionsTabId = 'general' | 'proofing' | 'save' | 'language' | 'accessibility' | 'advanced' | 'ribbon' | 'quickAccess' | 'addIns' | 'trust'; /** * Chrome regions a host can remove. Each id maps onto one region in every * binding; see `VIEWER_PANEL_IDS` for the catalogue. */ declare type ViewerPanelId = 'statusBar' | 'slidesPane' | 'inspector' | 'notes' | 'quickAccessToolbar' | 'titleBar'; declare interface ViewerProofingOptions { autoCorrectTwoInitialCapitals: boolean; autoCorrectCapitalizeFirstLetter: boolean; autoCorrectCapitalizeDayNames: boolean; autoCorrectSmartQuotes: boolean; autoCorrectHyphensToDash: boolean; autoCorrectFractions: boolean; autoCorrectOrdinals: boolean; ignoreUppercase: boolean; ignoreWordsWithNumbers: boolean; ignoreInternetAddresses: boolean; flagRepeatedWords: boolean; checkSpellingAsYouType: boolean; hideSpellingErrors: boolean; } declare interface ViewerQuickAccessOptions { visible: boolean; position: QuickAccessPosition; showCommandLabels: boolean; /** Ordered ids from `QUICK_ACCESS_COMMAND_CATALOG`. */ commandIds: string[]; } declare interface ViewerRibbonOptions { /** Ribbon tabs unticked in Customize Ribbon. The File tab can never be hidden. */ hiddenTabIds: ToolbarTabId[]; } /** * File > Options > Save. * * Font embedding deliberately has NO entry here. It is owned by the File > * Fonts panel, whose toggle is the one the save path reads (see * `render/font-embedding`: `describeFontEmbedding` decides the toggle's start * position and whether it can do anything at all, `embeddedFontSaveOptions` * turns it into the `PptxHandler.save()` slice). This group used to carry a * second `embedFonts` boolean, plus an `embedAllFontCharacters` companion, and * neither was read by anything: the pane moved a switch that changed no saved * byte, while the panel next door moved the real one. Two switches for one * setting, one of them lying, is worse than one switch in a less * PowerPoint-shaped place. */ declare interface ViewerSaveOptions { autoSave: boolean; autoRecoverIntervalMinutes: number; keepLastAutoRecoveredVersion: boolean; defaultExportFormat: DefaultExportFormat; cacheRetentionDays: number; clearCacheOnClose: boolean; } /** * Full viewer theme configuration. * * Every property is optional — unset values fall back to the built-in * dark theme defaults. */ declare interface ViewerTheme { /** Semantic UI colors. Each key maps to a `--pptx-` CSS custom property. */ colors?: Partial; /** Base border-radius value (e.g. `"0.5rem"`, `"8px"`). */ radius?: string; /** * Escape hatch: arbitrary CSS custom properties to set on the viewer * root element. Keys should include the `--` prefix. * * @example * ```ts * { "--my-custom-shadow": "0 4px 12px rgba(0,0,0,0.5)" } * ``` */ cssVars?: Record; } /** * Theme configuration types for the PowerPoint viewer. * * All color values accept any valid CSS color string: * hex (`#6366f1`), rgb (`rgb(99 102 241)`), hsl (`hsl(239 84% 67%)`), * oklch (`oklch(0.585 0.233 277)`), named colors, etc. * * Framework-agnostic — shared by the React, Vue, and Angular bindings. */ /** * Semantic color tokens for the viewer UI. * * These map to CSS custom properties (`--pptx-`) and drive all * UI component colors. The naming follows the shadcn/ui convention so * that Tailwind + shadcn users get a familiar experience. */ declare interface ViewerThemeColors { /** Page / root background */ background: string; /** Default text color */ foreground: string; /** Card / panel surface */ card: string; /** Text on card surfaces */ cardForeground: string; /** Popover / dropdown surface */ popover: string; /** Text inside popovers */ popoverForeground: string; /** Primary action color (buttons, active indicators) */ primary: string; /** Text on primary-colored backgrounds */ primaryForeground: string; /** Secondary / subdued action color */ secondary: string; /** Text on secondary backgrounds */ secondaryForeground: string; /** Muted / disabled surface */ muted: string; /** Text on muted surfaces (also used for secondary text) */ mutedForeground: string; /** Accent / hover-highlight surface */ accent: string; /** Text on accent surfaces */ accentForeground: string; /** Destructive / danger action color */ destructive: string; /** Text on destructive backgrounds */ destructiveForeground: string; /** Default border color */ border: string; /** Input field border color */ input: string; /** Focus ring color */ ring: string; } declare interface ViewerTrustOptions { openInProtectedView: boolean; allowExternalContent: boolean; confirmExternalHyperlinks: boolean; } /** Host layout policy, independent of authored slide dimensions and user zoom. */ export declare interface ViewportFitOptions { /** Per-side padding. Omission keeps the binding's existing decorative allowance. */ fitPadding?: ViewportFitPadding; /** Positive fit-factor ceiling; null allows enlargement without a ceiling. */ maxFitScale?: number | null; } /** Unscaled CSS pixels reserved on each side of the ordinary viewer viewport. */ export declare type ViewportFitPadding = number | { horizontal: number; vertical: number; }; export declare const WordArtText: typeof __VLS_export_14; /** * Strongly-typed parsed XML node from fast-xml-parser. * * The parser is configured with `attributeNamePrefix: '@_'`, * `parseAttributeValue: false`, and `parseTagValue: false`, so attribute and * text values are always strings at runtime. This type encodes that: * * - **Attributes** — keys matching `` `@_${string}` `` return * `string | undefined` directly. * - **Text content** — `#text` returns `string | undefined`. * - **Child elements** — any other string key returns * `XmlObject | XmlObject[] | string | undefined`. The union reflects that * fast-xml-parser may emit an object (single child), an array (repeated * children), or a bare string (text-only element collapsed by the parser). * * For traversal, prefer the helpers in {@link ./../utils/xml-access} — * `xmlChild` / `xmlChildren` / `xmlAttr` / `xmlText` / `xmlPath` — which * narrow the union and normalize the single-vs-array duality. Direct * indexing works for attributes (typed as string) but chained child access * (`obj['p:spPr']?.['a:xfrm']`) requires the helpers or a narrowing cast * because TypeScript cannot index into the `XmlObject[] | string` part of * the union. */ declare interface XmlObject { /** Attributes (`@_`-prefixed keys) are always strings at runtime. */ [attr: `@_${string}`]: string | undefined; /** Element text content surfaces under `#text` when present. */ '#text'?: string; /** * Child elements keyed by their (namespaced) tag name. fast-xml-parser * emits a single object for unique elements, an array for repeated ones, * and a bare string for elements collapsed to their text content. Use * the helpers in `utils/xml-access` to narrow this union. */ [child: string]: XmlObject | XmlObject[] | string | undefined; } declare interface YArrayLike { readonly length: number; get: (index: number) => unknown; push: (items: unknown[]) => void; delete: (index: number, length?: number) => void; insert: (index: number, items: unknown[]) => void; toArray: () => unknown[]; observe: (handler: () => void) => void; unobserve: (handler: () => void) => void; observeDeep: (handler: YDeepObserver) => void; unobserveDeep: (handler: YDeepObserver) => void; } declare type YDeepObserver = (events?: unknown, transaction?: YTransactionLike) => void; declare interface YDocLike { getMap: (name: string) => YMapLike; getArray: (name: string) => YArrayLike; transact: (fn: () => void, origin?: unknown) => void; } declare interface YjsFactories { createMap: () => YMapLike; createArray: () => YArrayLike; createText: () => YTextLike; /** Track character identities using the binding's existing Yjs runtime. */ createTextPositions?: (text: YTextEditableLike) => TextSessionPositions; } declare interface YMapLike { get: (key: string) => unknown; set: (key: string, value: unknown) => void; delete: (key: string) => void; forEach: (cb: (value: unknown, key: string) => void) => void; } /** Y.Text surface needed for in-place edits (delete/format on top of insert). */ declare interface YTextEditableLike extends YTextLike { delete: (index: number, length: number) => void; format: (index: number, length: number, attributes: Record) => void; } declare interface YTextLike { insert: (index: number, text: string, attrs?: Record) => void; toDelta: () => DeltaOp[]; toString: () => string; } /** Shape of the Yjs transaction passed to (deep) observers. */ declare interface YTransactionLike { origin?: unknown; } /** * A Slide Zoom or Section Zoom element (PowerPoint Zoom Object). * * Zoom elements display a live thumbnail of the target slide and * navigate to it on click during presentation mode. * * @example * ```ts * const zoom: ZoomPptxElement = { * type: "zoom", * id: "zm_1", x: 300, y: 200, width: 200, height: 120, * zoomType: "slide", * targetSlideIndex: 5, * }; * // => satisfies ZoomPptxElement * ``` */ declare interface ZoomPptxElement extends PptxElementBase, PptxImageProperties { type: 'zoom'; /** Type of zoom: slide-level, section-level, or a multi-section summary. */ zoomType: 'slide' | 'section' | 'summary'; /** Zero-based index of the target slide. */ targetSlideIndex: number; /** Section ID for section zoom. */ targetSectionId?: string; /** Ordered section tiles in a Summary Zoom container. */ summaryTargets?: SummaryZoomTarget[]; /** Layout mode authored on the Summary Zoom container. */ summaryLayout?: 'grid' | 'fixed'; /** * `zmPr/@returnToParent` (MS-PPTX `CT_ZoomObjectProperties`, shared by all * three Zoom kinds): whether continuing forward from the destination slide * during a live show returns to this Zoom's origin slide instead of * advancing linearly through the deck. The schema declares ``, * so an ABSENT attribute means `true`, not `false`. This codebase still * leaves the field `undefined` (rather than fabricating `true`) when the * source XML omits it, so a round-trip never invents an attribute the * source never had; a CONSUMER of this field (playback, e.g. * `pptx-viewer-shared`'s `resolveZoomNavigationTarget`) must read * `returnToParent !== false`, not `Boolean(returnToParent)`, to get the * spec-correct effective value. For `zoomType: 'summary'`, this mirrors the * first tile's own value; see {@link SummaryZoomTarget.returnToParent} for * the per-tile value. */ returnToParent?: boolean; /** * `zmPr/@transitionDur` (MS-PPTX `CT_ZoomObjectProperties`): the * zoom-transition length in milliseconds. PowerPoint's own writer emits a * unitless decimal-millisecond value for every OOXML `ST_UniversalTimeOffset` * this codebase has observed (see the media-trim/-fade parsers), so this * follows the same convention rather than the full TIMEOFFSET grammar's * unit suffixes. Undefined uses the destination slide's own transition. * For `zoomType: 'summary'`, this mirrors the first tile's own value; see * {@link SummaryZoomTarget.transitionDurationMs} for the per-tile value. */ transitionDurationMs?: number; } export declare const ZoomRenderer: typeof __VLS_export_12; export { }