pptx-vanilla-viewer 0.3.0 → 0.5.0

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,81 @@ type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';
 
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** A single remote collaborator's cursor, in unscaled slide coordinates. */
+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[];
+}
+/**
+ * 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.
+ */
+interface SanitizedPresence {
+    clientId: number;
+    userName: string;
+    userAvatar?: string;
+    userColor: string;
+    activeSlideIndex: number;
+    cursorX: number;
+    cursorY: number;
+    lastUpdated: string;
+    selectedElementId?: string;
+    role?: CollaborationRole;
+}
+
+/**
+ * Pure, framework-agnostic helpers for freehand ink drawing, shared by every
+ * binding. No framework imports, so these can be unit-tested without TestBed.
+ */
+
+/** A 2D point in stage-local coordinates. */
+interface InkPoint {
+    x: number;
+    y: number;
+}
+/** Options for {@link strokeToInkElement}. */
+interface StrokeToInkElementOpts {
+    points: InkPoint[];
+    color: string;
+    width: number;
+    tool: 'pen' | 'highlighter' | 'freeform';
+}
+
+/**
+ * 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;
@@ -1579,6 +1690,13 @@ interface Store<T extends object> {
 
 /** `zoom` is either an explicit scale factor (1 = 100%) or fit-to-viewport. */
 type ZoomLevel = number | 'fit';
+/**
+ * The Draw ribbon tab's active tool. `'select'` means normal editing gestures
+ * (move/resize/rotate/inline-edit) apply on the stage; every other value
+ * routes stage pointer events to the ink-drawing gesture controller instead
+ * (see `editor-draw-gestures.ts`).
+ */
+type DrawTool = 'select' | 'pen' | 'highlighter' | 'eraser';
 /**
  * The vanilla viewer's reactive view state. Kept intentionally flat and small;
  * everything here is what the DOM render layer consumes.
@@ -1616,8 +1734,38 @@ interface ViewerState {
      * navigation for the life of the viewer instance (in-memory only).
      */
     notesExpanded: boolean;
+    /** Remote collaborators currently in the session (empty when not collaborating). */
+    remotePresences: SanitizedPresence[];
+    /** Remote cursors visible on the current slide, projected from `remotePresences`. */
+    cursors: RemoteCursor[];
+    /** Client id of the peer the local user is following, or null when free. */
+    followedClientId: number | null;
     /** In-memory clipboard payload from the last copy/cut, or null. */
     clipboardPayload: ElementClipboardPayload | null;
+    /** Active Draw ribbon tool; `'select'` disables the ink-drawing gesture controller. */
+    drawTool: DrawTool;
+    /** Stroke colour for the pen/highlighter tools. */
+    drawColor: string;
+    /** Stroke width (px) for the pen/highlighter tools. */
+    drawWidth: number;
+}
+
+/**
+ * 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;
 }
 
 /**
@@ -1651,6 +1799,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
@@ -1663,6 +1823,32 @@ interface ClipboardActions {
     paste(): void;
 }
 
+/**
+ * Ink stroke actions for the Draw ribbon tab: commit a freehand pen/
+ * highlighter stroke as a new `InkPptxElement`, or erase an existing one.
+ * Both mutations are history-integrated (push -> mutate -> commit), mirroring
+ * `editor-background-actions.ts` and the `insertElement` helper in
+ * `editor-edit-ops.ts`. The pointer-event lifecycle that accumulates a
+ * stroke's points lives separately in `editor-draw-gestures.ts`; this module
+ * only owns the resulting slide/history mutation.
+ */
+interface InkActions {
+    /**
+     * Build an `InkPptxElement` from a completed stroke (via the shared
+     * `strokeToInkElement`) and append it to the current slide, selected.
+     * A no-op when not editable, there is no current slide, or the stroke has
+     * fewer than 2 points (shared helper returns `null`, matching a plain tap).
+     */
+    commitStroke(stroke: StrokeToInkElementOpts): void;
+    /**
+     * Remove the ink element with `id` from the current slide (Draw tab's
+     * eraser tool). Returns `true` when an ink element was found and removed;
+     * `false` for a missing id, a non-ink element, or a read-only viewer (safe
+     * to call from a generic stage hit-test without a pre-check).
+     */
+    eraseInkElement(id: string): boolean;
+}
+
 /**
  * Insert-element factories for the vanilla editor.
  *
@@ -1676,6 +1862,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 +1934,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 +1968,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, InkActions {
     setShapeFill(color: string): void;
     setShapeStroke(color: string): void;
     setShapeStrokeWidth(width: number): void;
@@ -1743,6 +1976,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 +2027,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 +2042,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;
@@ -1824,6 +2083,12 @@ interface NotesPanel {
     setExpanded(expanded: boolean): void;
 }
 
+/** Draw tab state to reflect (current tool/colour/width). */
+interface RibbonDrawState {
+    tool: DrawTool;
+    color: string;
+    width: number;
+}
 /** Nav-row state (prev/next/counter/zoom label). */
 interface RibbonNavState {
     current: number;
@@ -1852,6 +2117,8 @@ interface Ribbon {
     setEditable(editable: boolean): void;
     /** Reflect the current selection across the Home tab's Font/Paragraph/Arrange groups. */
     updateSelection(selectedElement: a | undefined, extra: RibbonSelectionState): void;
+    /** Reflect the current Draw tab tool/colour/width (store-driven). */
+    setDrawState(state: RibbonDrawState): void;
 }
 
 interface ThumbnailRail {
@@ -1914,6 +2181,12 @@ interface EditorController {
     deleteSelected(): void;
     duplicateSelected(): string | null;
     getSelectedElementId(): string | null;
+    /** Switch the Draw ribbon tab's active tool (also clears selection when leaving `'select'`). */
+    setDrawTool(tool: DrawTool): void;
+    /** Set the pen/highlighter stroke colour used by the next committed stroke. */
+    setDrawColor(color: string): void;
+    /** Set the pen/highlighter stroke width used by the next committed stroke. */
+    setDrawWidth(width: number): void;
     /** The formatting / insert / arrange actions for the editing chrome. */
     getEditActions(): EditActions;
     /** The Find & Replace actions for the ribbon's docked panel. */
@@ -2151,6 +2424,21 @@ interface RenderController {
  */
 type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'error';
 
+/**
+ * share-helpers.ts: pure (framework-free) helpers for the Share dialog.
+ *
+ * Mirrors the Vue `ShareDialog.vue` / Angular `share-helpers.ts` form
+ * validation and config-assembly logic (see `useCollaborationWiring.onShareStart`
+ * for the `role: 'collaborator'` config this produces). No DOM here so it is
+ * trivially unit-testable; the DOM builder lives in `ui/share-dialog.ts`.
+ */
+/** Prefilled values for the Share form fields. */
+interface ShareDefaults {
+    roomId?: string;
+    userName?: string;
+    serverUrl?: string;
+}
+
 /** Per-slide progress callback: `(currentSlideIndex, totalSlides)`. */
 type ExportProgress = (current: number, total: number) => void;
 
@@ -2376,6 +2664,13 @@ interface PptxViewerOptions extends PptxViewerCallbacks {
      * slide array, so a joiner's host-provided media can degrade.
      */
     collaboration?: CollaborationConfig;
+    /**
+     * Prefilled values for the built-in Share/Broadcast dialogs' form fields
+     * (e.g. a host-generated display name), mirroring the Vue binding's
+     * `shareDefaults` prop. The broadcast dialog uses `userName` as the
+     * presenter's display name.
+     */
+    shareDefaults?: ShareDefaults;
 }
 /** The viewer handle returned by `createPptxViewer`. */
 interface PptxViewerInstance {
@@ -2500,6 +2795,9 @@ interface ChromeHost {
         commitNotes(notes: string): void;
         getEditActions(): EditActions;
         getFindReplaceActions(): FindReplaceActions;
+        setDrawTool(tool: DrawTool): void;
+        setDrawColor(color: string): void;
+        setDrawWidth(width: number): void;
     };
     prev(): void;
     next(): void;
@@ -2519,6 +2817,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`). */