pptx-vanilla-viewer 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { n, o, m, P, a, e, f, X, p, q, r, s, t, u, v, w, x, y, z, A, B, D, E, F, G, H, J, K, L, i, j, l, k, g, h, a0 } from './presentation-BfnrtJV1.js';
+import { n, o, m, P, a, e, f, X, p, q, r, s, t, u, v, w, x, y, z, A, B, D, E, F, G, H, J, K, L, i, j, l, k, g, h, a0, ca } from './presentation-BfnrtJV1.js';
 export { a as PptxElement, P as PptxSlide } from './presentation-BfnrtJV1.js';
 import { ViewerTheme } from './theme/index.js';
 export { ViewerTheme, ViewerThemeColors, defaultCssVars, defaultRadius, defaultThemeColors, themeToCssVars, vermilionDarkTheme, vermilionLightTheme } from './theme/index.js';
@@ -1431,6 +1431,42 @@ interface CollaborationConfig {
 /** A neutral CSS map (framework `CSSProperties` are structurally compatible). */
 type CssStyleMap = Record<string, string | number>;
 
+/**
+ * `animation-authoring` — pure, immutable helpers for the editor's element
+ * animation authoring UI (the Animations ribbon tab / animation panel).
+ *
+ * Animation data lives on the SLIDE (`PptxSlide.animations`), keyed by
+ * `elementId`, NOT on the element itself. The authoring UI reads and emits the
+ * entire slide-level `animations` array. Every function here returns a new
+ * `PptxElementAnimation[]` without mutating its input, so they're trivially
+ * unit-testable and safe to drive editor undo/redo from.
+ *
+ * Two families coexist here, both used across the bindings:
+ *
+ *  - **Granular field setters** (`setAnimationEntrance` / `setTrigger` /
+ *    `setDuration` / … plus `reorderAnimationUp` / `removeAnimation`): the
+ *    Angular authoring panel + React's `useAnimationHandlers` model. They
+ *    upsert a single field on the element's entry, creating the entry with
+ *    sensible defaults when absent and removing it when all three effect
+ *    buckets become empty.
+ *  - **Group preset apply/remove** (`applyAnimationPreset` /
+ *    `removeElementAnimation`): the Vue ribbon model, a coarser
+ *    "set one of entrance/emphasis/exit, keep the rest" upsert.
+ *
+ * The option *catalogs* here are intentionally **value-only** (preset id +
+ * nothing else): the human label / icon / i18n key for each option is
+ * framework-specific (React uses `react-icons` + label keys, Angular uses
+ * Unicode arrow glyphs + plain labels), so each binding maps these ids to its
+ * own display metadata.
+ *
+ * Pure: imports only `pptx-viewer-core` types; no framework, no DOM.
+ *
+ * @module render/animation-authoring
+ */
+
+/** One of the three animation buckets a preset can occupy on an element. */
+type AnimationGroup = 'entrance' | 'emphasis' | 'exit';
+
 /**
  * Pure geometry helpers for the align / distribute editor operations.
  *
@@ -1484,6 +1520,31 @@ type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';
 
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+/**
+ * Pure helpers for the gradient picker editor control, shared by every binding.
+ *
+ * Readers extract current gradient values from a PptxElement (falling back to
+ * sensible defaults), and patch-builders produce shallow-merge-ready
+ * `Partial<PptxElement>` objects safe to pass to each binding's element-update
+ * action.
+ *
+ * No framework imports; every type is concrete or `unknown` + narrowed.
+ */
+
+/** A single gradient stop, mirroring the ShapeStyle array item shape. */
+interface GradientStop {
+    color: string;
+    position: number;
+    opacity?: number;
+}
+/** The editable gradient state surfaced to the component. */
+interface GradientState {
+    type: 'linear' | 'radial';
+    /** Angle in degrees (only meaningful for linear). */
+    angle: number;
+    stops: GradientStop[];
+}
 /** In-memory clipboard payload stored when an element is copied or cut. */
 interface ElementClipboardPayload {
     element: a;
@@ -1620,6 +1681,24 @@ interface ViewerState {
     clipboardPayload: ElementClipboardPayload | null;
 }
 
+/**
+ * Element-animation actions for the ribbon's Animations tab.
+ *
+ * Animation data lives on the SLIDE (`PptxSlide.animations`, keyed by
+ * `elementId`), not on the element itself, matching how the presentation
+ * playback state machine reads it (`buildClickGroups(slide.animations)` in
+ * `animation/presentation-playback.ts`). Both actions target the currently
+ * selected element and route through the shared `animation-authoring.ts`
+ * "coarse group preset" model (`applyAnimationPreset` / `removeElementAnimation`),
+ * the same one the Vue ribbon uses: applying a preset sets one of
+ * entrance/emphasis/exit without touching the others; remove drops the whole
+ * entry.
+ */
+interface AnimationActions {
+    addAnimation(group: AnimationGroup, preset: g): void;
+    removeAnimation(): void;
+}
+
 /**
  * Z-order, align, flip, and group/ungroup actions for the ribbon's
  * Home > Arrange group.
@@ -1651,6 +1730,18 @@ interface ArrangeActions {
     ungroupSelected(): void;
 }
 
+/**
+ * Slide-background actions for the ribbon's Design > Format Background panel.
+ * Solid-colour fill only (matches the docked panel's scope: a single colour
+ * input); clearing removes every background field so the slide falls back to
+ * its layout/master background. Both mutations are history-integrated,
+ * mirroring `editor-slide-actions.ts`.
+ */
+interface SlideBackgroundActions {
+    setSlideBackgroundColor(color: string): void;
+    clearSlideBackground(): void;
+}
+
 /**
  * Cut/copy/paste actions for the ribbon's Home > Clipboard group, backed by
  * the shared `element-clipboard.ts` codec. The in-memory clipboard payload
@@ -1676,6 +1767,36 @@ interface ClipboardActions {
 /** The element kinds the Insert ribbon tab can create directly. */
 type InsertKind = 'text' | 'table' | 'shape';
 
+/**
+ * Element-type-aware inspector actions: text vertical-align/wrap/autofit,
+ * gradient fill + fill/stroke opacity, image brightness/contrast/saturation +
+ * crop, and table-level header-row/banded-rows/cell-padding. Every method is a
+ * thin `applyToSelected` wrapper around pure builders from `pptx-viewer-shared`
+ * (or the local `patchShapeStyle`), mirroring `editor-text-actions.ts`.
+ *
+ * These extend the base position/size/rotation + flat fill/stroke inspector
+ * that `editor-edit-ops.ts` already exposes; see `ui/inspector/` for the
+ * per-element-type panels that call these.
+ */
+interface InspectorActions {
+    setTextVerticalAlign(vAlign: NonNullable<a0['vAlign']>): void;
+    setTextWrap(wrap: NonNullable<a0['textWrap']>): void;
+    setAutoFitMode(mode: NonNullable<a0['autoFitMode']>): void;
+    setFillOpacity(opacity: number): void;
+    setStrokeOpacity(opacity: number): void;
+    setGradientFill(state: GradientState): void;
+    addGradientStop(color: string, position: number): void;
+    removeGradientStop(index: number): void;
+    updateGradientStop(index: number, changes: Partial<GradientState['stops'][number]>): void;
+    setImageBrightness(value: number): void;
+    setImageContrast(value: number): void;
+    setImageSaturation(value: number): void;
+    setImageCrop(edge: 'left' | 'top' | 'right' | 'bottom', value: number): void;
+    setTableHeaderRow(enabled: boolean): void;
+    setTableBandedRows(enabled: boolean): void;
+    setTableCellPadding(padding: number): void;
+}
+
 /**
  * New/duplicate/delete-slide actions for the ribbon's Home > Slides group,
  * backed by the shared `slide-operations.ts` factory. Every mutation is
@@ -1718,6 +1839,23 @@ interface TextActions {
     setLineSpacing(value: number): void;
 }
 
+/**
+ * Slide-transition actions for the ribbon's Transitions tab. Playback already
+ * reads `PptxSlide.transition` (see `animation/presentation-playback.ts`), so
+ * this only needs to write that same field, history-integrated like every
+ * other ribbon mutation.
+ *
+ * `applyTransition` covers both the preset gallery buttons and the duration
+ * input (the tab re-applies the currently-selected preset whenever the
+ * duration changes), plus the "Apply to All Slides" checkbox: when
+ * `applyToAll` is true every slide gets the same fresh `{ type, durationMs }`
+ * transition; otherwise only the current slide is patched, preserving any
+ * advanced fields (direction, sound, ...) it already carried.
+ */
+interface TransitionActions {
+    applyTransition(type: k, durationMs: number, applyToAll: boolean): void;
+}
+
 /** A geometry patch from the inspector (all fields optional). */
 interface GeometryPatch {
     x?: number;
@@ -1735,7 +1873,7 @@ interface GeometryPatch {
  * directly here. Every mutating action is history-integrated (push -> mutate
  * -> commit) via the shared {@link EditorOps}.
  */
-interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions {
+interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions, SlideBackgroundActions, TransitionActions, AnimationActions, InspectorActions {
     setShapeFill(color: string): void;
     setShapeStroke(color: string): void;
     setShapeStrokeWidth(width: number): void;
@@ -1743,6 +1881,12 @@ interface EditActions extends TextActions, ArrangeActions, ClipboardActions, Sli
     setGeometry(patch: GeometryPatch): void;
     insert(kind: InsertKind, shapeType?: ShapePresetType): void;
     insertImage(): Promise<void>;
+    insertMedia(): Promise<void>;
+    insertChart(chartType: l): void;
+    insertSmartArt(layout: ca, defaultItems: string[]): void;
+    insertEquation(omml: Record<string, unknown>): void;
+    insertActionButton(shapeType: string): void;
+    insertField(fieldType: string, value?: string): void;
     duplicateSelected(): void;
     deleteSelected(): void;
 }
@@ -1788,10 +1932,13 @@ type TranslationMessages = Record<string, Record<string, string>>;
  */
 declare function createTranslator(locale?: string, messages?: TranslationMessages): Translator;
 
-/** Selection-derived state the inspector reflects. */
+/** Selection-derived state the inspector reflects, computed by `buildInspectorState`. */
 interface InspectorState {
     hasSelection: boolean;
     canShape: boolean;
+    canText: boolean;
+    isImage: boolean;
+    isTable: boolean;
     x: number;
     y: number;
     width: number;
@@ -1800,6 +1947,23 @@ interface InspectorState {
     fillColor: string | undefined;
     strokeColor: string | undefined;
     strokeWidth: number;
+    fillOpacity: number;
+    strokeOpacity: number;
+    gradientEnabled: boolean;
+    gradient: GradientState;
+    vAlign: 'top' | 'middle' | 'bottom';
+    textWrap: 'square' | 'none';
+    autoFitMode: 'shrink' | 'normal' | 'none';
+    imageBrightness: number;
+    imageContrast: number;
+    imageSaturation: number;
+    cropLeft: number;
+    cropTop: number;
+    cropRight: number;
+    cropBottom: number;
+    tableHeaderRow: boolean;
+    tableBandedRows: boolean;
+    tableCellPadding: number;
 }
 interface Inspector {
     el: HTMLElement;
@@ -2519,6 +2683,7 @@ interface ChromeHost {
     exportGif(): Promise<void>;
     exportVideo(): Promise<void>;
     print(): Promise<boolean>;
+    setTheme(theme: ViewerTheme | undefined): void;
 }
 
 /** The export slice of the public viewer API (see `PptxViewerInstance`). */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { n, o, m, P, a, e, f, X, p, q, r, s, t, u, v, w, x, y, z, A, B, D, E, F, G, H, J, K, L, i, j, l, k, g, h, a0 } from './presentation-BfnrtJV1.js';
+import { n, o, m, P, a, e, f, X, p, q, r, s, t, u, v, w, x, y, z, A, B, D, E, F, G, H, J, K, L, i, j, l, k, g, h, a0, ca } from './presentation-BfnrtJV1.js';
 export { a as PptxElement, P as PptxSlide } from './presentation-BfnrtJV1.js';
 import { ViewerTheme } from './theme/index.js';
 export { ViewerTheme, ViewerThemeColors, defaultCssVars, defaultRadius, defaultThemeColors, themeToCssVars, vermilionDarkTheme, vermilionLightTheme } from './theme/index.js';
@@ -1431,6 +1431,42 @@ interface CollaborationConfig {
 /** A neutral CSS map (framework `CSSProperties` are structurally compatible). */
 type CssStyleMap = Record<string, string | number>;
 
+/**
+ * `animation-authoring` — pure, immutable helpers for the editor's element
+ * animation authoring UI (the Animations ribbon tab / animation panel).
+ *
+ * Animation data lives on the SLIDE (`PptxSlide.animations`), keyed by
+ * `elementId`, NOT on the element itself. The authoring UI reads and emits the
+ * entire slide-level `animations` array. Every function here returns a new
+ * `PptxElementAnimation[]` without mutating its input, so they're trivially
+ * unit-testable and safe to drive editor undo/redo from.
+ *
+ * Two families coexist here, both used across the bindings:
+ *
+ *  - **Granular field setters** (`setAnimationEntrance` / `setTrigger` /
+ *    `setDuration` / … plus `reorderAnimationUp` / `removeAnimation`): the
+ *    Angular authoring panel + React's `useAnimationHandlers` model. They
+ *    upsert a single field on the element's entry, creating the entry with
+ *    sensible defaults when absent and removing it when all three effect
+ *    buckets become empty.
+ *  - **Group preset apply/remove** (`applyAnimationPreset` /
+ *    `removeElementAnimation`): the Vue ribbon model, a coarser
+ *    "set one of entrance/emphasis/exit, keep the rest" upsert.
+ *
+ * The option *catalogs* here are intentionally **value-only** (preset id +
+ * nothing else): the human label / icon / i18n key for each option is
+ * framework-specific (React uses `react-icons` + label keys, Angular uses
+ * Unicode arrow glyphs + plain labels), so each binding maps these ids to its
+ * own display metadata.
+ *
+ * Pure: imports only `pptx-viewer-core` types; no framework, no DOM.
+ *
+ * @module render/animation-authoring
+ */
+
+/** One of the three animation buckets a preset can occupy on an element. */
+type AnimationGroup = 'entrance' | 'emphasis' | 'exit';
+
 /**
  * Pure geometry helpers for the align / distribute editor operations.
  *
@@ -1484,6 +1520,31 @@ type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';
 
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+
+/**
+ * Pure helpers for the gradient picker editor control, shared by every binding.
+ *
+ * Readers extract current gradient values from a PptxElement (falling back to
+ * sensible defaults), and patch-builders produce shallow-merge-ready
+ * `Partial<PptxElement>` objects safe to pass to each binding's element-update
+ * action.
+ *
+ * No framework imports; every type is concrete or `unknown` + narrowed.
+ */
+
+/** A single gradient stop, mirroring the ShapeStyle array item shape. */
+interface GradientStop {
+    color: string;
+    position: number;
+    opacity?: number;
+}
+/** The editable gradient state surfaced to the component. */
+interface GradientState {
+    type: 'linear' | 'radial';
+    /** Angle in degrees (only meaningful for linear). */
+    angle: number;
+    stops: GradientStop[];
+}
 /** In-memory clipboard payload stored when an element is copied or cut. */
 interface ElementClipboardPayload {
     element: a;
@@ -1620,6 +1681,24 @@ interface ViewerState {
     clipboardPayload: ElementClipboardPayload | null;
 }
 
+/**
+ * Element-animation actions for the ribbon's Animations tab.
+ *
+ * Animation data lives on the SLIDE (`PptxSlide.animations`, keyed by
+ * `elementId`), not on the element itself, matching how the presentation
+ * playback state machine reads it (`buildClickGroups(slide.animations)` in
+ * `animation/presentation-playback.ts`). Both actions target the currently
+ * selected element and route through the shared `animation-authoring.ts`
+ * "coarse group preset" model (`applyAnimationPreset` / `removeElementAnimation`),
+ * the same one the Vue ribbon uses: applying a preset sets one of
+ * entrance/emphasis/exit without touching the others; remove drops the whole
+ * entry.
+ */
+interface AnimationActions {
+    addAnimation(group: AnimationGroup, preset: g): void;
+    removeAnimation(): void;
+}
+
 /**
  * Z-order, align, flip, and group/ungroup actions for the ribbon's
  * Home > Arrange group.
@@ -1651,6 +1730,18 @@ interface ArrangeActions {
     ungroupSelected(): void;
 }
 
+/**
+ * Slide-background actions for the ribbon's Design > Format Background panel.
+ * Solid-colour fill only (matches the docked panel's scope: a single colour
+ * input); clearing removes every background field so the slide falls back to
+ * its layout/master background. Both mutations are history-integrated,
+ * mirroring `editor-slide-actions.ts`.
+ */
+interface SlideBackgroundActions {
+    setSlideBackgroundColor(color: string): void;
+    clearSlideBackground(): void;
+}
+
 /**
  * Cut/copy/paste actions for the ribbon's Home > Clipboard group, backed by
  * the shared `element-clipboard.ts` codec. The in-memory clipboard payload
@@ -1676,6 +1767,36 @@ interface ClipboardActions {
 /** The element kinds the Insert ribbon tab can create directly. */
 type InsertKind = 'text' | 'table' | 'shape';
 
+/**
+ * Element-type-aware inspector actions: text vertical-align/wrap/autofit,
+ * gradient fill + fill/stroke opacity, image brightness/contrast/saturation +
+ * crop, and table-level header-row/banded-rows/cell-padding. Every method is a
+ * thin `applyToSelected` wrapper around pure builders from `pptx-viewer-shared`
+ * (or the local `patchShapeStyle`), mirroring `editor-text-actions.ts`.
+ *
+ * These extend the base position/size/rotation + flat fill/stroke inspector
+ * that `editor-edit-ops.ts` already exposes; see `ui/inspector/` for the
+ * per-element-type panels that call these.
+ */
+interface InspectorActions {
+    setTextVerticalAlign(vAlign: NonNullable<a0['vAlign']>): void;
+    setTextWrap(wrap: NonNullable<a0['textWrap']>): void;
+    setAutoFitMode(mode: NonNullable<a0['autoFitMode']>): void;
+    setFillOpacity(opacity: number): void;
+    setStrokeOpacity(opacity: number): void;
+    setGradientFill(state: GradientState): void;
+    addGradientStop(color: string, position: number): void;
+    removeGradientStop(index: number): void;
+    updateGradientStop(index: number, changes: Partial<GradientState['stops'][number]>): void;
+    setImageBrightness(value: number): void;
+    setImageContrast(value: number): void;
+    setImageSaturation(value: number): void;
+    setImageCrop(edge: 'left' | 'top' | 'right' | 'bottom', value: number): void;
+    setTableHeaderRow(enabled: boolean): void;
+    setTableBandedRows(enabled: boolean): void;
+    setTableCellPadding(padding: number): void;
+}
+
 /**
  * New/duplicate/delete-slide actions for the ribbon's Home > Slides group,
  * backed by the shared `slide-operations.ts` factory. Every mutation is
@@ -1718,6 +1839,23 @@ interface TextActions {
     setLineSpacing(value: number): void;
 }
 
+/**
+ * Slide-transition actions for the ribbon's Transitions tab. Playback already
+ * reads `PptxSlide.transition` (see `animation/presentation-playback.ts`), so
+ * this only needs to write that same field, history-integrated like every
+ * other ribbon mutation.
+ *
+ * `applyTransition` covers both the preset gallery buttons and the duration
+ * input (the tab re-applies the currently-selected preset whenever the
+ * duration changes), plus the "Apply to All Slides" checkbox: when
+ * `applyToAll` is true every slide gets the same fresh `{ type, durationMs }`
+ * transition; otherwise only the current slide is patched, preserving any
+ * advanced fields (direction, sound, ...) it already carried.
+ */
+interface TransitionActions {
+    applyTransition(type: k, durationMs: number, applyToAll: boolean): void;
+}
+
 /** A geometry patch from the inspector (all fields optional). */
 interface GeometryPatch {
     x?: number;
@@ -1735,7 +1873,7 @@ interface GeometryPatch {
  * directly here. Every mutating action is history-integrated (push -> mutate
  * -> commit) via the shared {@link EditorOps}.
  */
-interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions {
+interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions, SlideBackgroundActions, TransitionActions, AnimationActions, InspectorActions {
     setShapeFill(color: string): void;
     setShapeStroke(color: string): void;
     setShapeStrokeWidth(width: number): void;
@@ -1743,6 +1881,12 @@ interface EditActions extends TextActions, ArrangeActions, ClipboardActions, Sli
     setGeometry(patch: GeometryPatch): void;
     insert(kind: InsertKind, shapeType?: ShapePresetType): void;
     insertImage(): Promise<void>;
+    insertMedia(): Promise<void>;
+    insertChart(chartType: l): void;
+    insertSmartArt(layout: ca, defaultItems: string[]): void;
+    insertEquation(omml: Record<string, unknown>): void;
+    insertActionButton(shapeType: string): void;
+    insertField(fieldType: string, value?: string): void;
     duplicateSelected(): void;
     deleteSelected(): void;
 }
@@ -1788,10 +1932,13 @@ type TranslationMessages = Record<string, Record<string, string>>;
  */
 declare function createTranslator(locale?: string, messages?: TranslationMessages): Translator;
 
-/** Selection-derived state the inspector reflects. */
+/** Selection-derived state the inspector reflects, computed by `buildInspectorState`. */
 interface InspectorState {
     hasSelection: boolean;
     canShape: boolean;
+    canText: boolean;
+    isImage: boolean;
+    isTable: boolean;
     x: number;
     y: number;
     width: number;
@@ -1800,6 +1947,23 @@ interface InspectorState {
     fillColor: string | undefined;
     strokeColor: string | undefined;
     strokeWidth: number;
+    fillOpacity: number;
+    strokeOpacity: number;
+    gradientEnabled: boolean;
+    gradient: GradientState;
+    vAlign: 'top' | 'middle' | 'bottom';
+    textWrap: 'square' | 'none';
+    autoFitMode: 'shrink' | 'normal' | 'none';
+    imageBrightness: number;
+    imageContrast: number;
+    imageSaturation: number;
+    cropLeft: number;
+    cropTop: number;
+    cropRight: number;
+    cropBottom: number;
+    tableHeaderRow: boolean;
+    tableBandedRows: boolean;
+    tableCellPadding: number;
 }
 interface Inspector {
     el: HTMLElement;
@@ -2519,6 +2683,7 @@ interface ChromeHost {
     exportGif(): Promise<void>;
     exportVideo(): Promise<void>;
     print(): Promise<boolean>;
+    setTheme(theme: ViewerTheme | undefined): void;
 }
 
 /** The export slice of the public viewer API (see `PptxViewerInstance`). */