pptx-vanilla-viewer 0.2.0 → 0.3.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 } 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 } 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,35 @@ interface CollaborationConfig {
 /** A neutral CSS map (framework `CSSProperties` are structurally compatible). */
 type CssStyleMap = Record<string, string | number>;
 
+/**
+ * Pure geometry helpers for the align / distribute editor operations.
+ *
+ * These functions operate over a list of slide elements (anything carrying the
+ * `{ id, x, y, width, height }` bounding-box fields of {@link PptxElement}) and
+ * return a `Map` keyed by element `id` describing the *new* position(s) for the
+ * elements that need to move. Elements that already sit on the target edge (or
+ * the two outer-most elements during distribution) are still included with
+ * their unchanged coordinate so callers can apply the whole map uniformly — the
+ * map only ever contains the axis that the operation touches.
+ *
+ * The helpers are deliberately framework-agnostic: no DOM, no Vue reactivity,
+ * no side effects. The host wires them into the editor by feeding the current
+ * selection in and applying the returned `Map` via its element-transform
+ * operation (one batched history entry per call).
+ */
+/** Edge / centre that {@link alignElements} can snap a selection to. */
+type AlignEdge = 'left' | 'centerH' | 'right' | 'top' | 'middle' | 'bottom';
+
+/**
+ * "Change Case" text mutation (PowerPoint's Aa dropdown: Sentence case, lower,
+ * UPPER, Capitalize Each Word, tOGGLE cASE). Unlike `textCaps` (a purely
+ * visual `text-transform`-style render hint), these modes rewrite the actual
+ * characters, matching PowerPoint's own behaviour. Framework-agnostic; no
+ * framework imports.
+ */
+
+type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';
+
 /**
  * collaboration-presence.ts: Pure, framework-agnostic logic for the real-time
  * collaboration subsystem (Yjs-backed presence + remote cursors).
@@ -1455,6 +1484,29 @@ type CssStyleMap = Record<string, string | number>;
 
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** In-memory clipboard payload stored when an element is copied or cut. */
+interface ElementClipboardPayload {
+    element: a;
+    isTemplate: boolean;
+}
+
+/**
+ * shape-preset-catalog.ts: the Insert > Shape picker catalogue shared by every
+ * binding's toolbar/inspector.
+ *
+ * Pure data: each entry carries the preset geometry `type` (OOXML `a:prstGeom`
+ * value the editor can insert), an English fallback `label`, the shared-i18n
+ * `i18nKey`, and a framework-neutral icon descriptor ({@link ShapePresetGlyph}
+ * name + optional utility-class modifier for rotation/skew). Each binding maps
+ * the glyph name onto its own icon component/SVG.
+ *
+ * Order matters: bindings surface the first 12 entries as the quick "top
+ * shapes" row, so new presets should be appended, not inserted.
+ *
+ * @module render/shape-preset-catalog
+ */
+/** Shape preset geometry types offered by the insert picker. */
+type ShapePresetType = 'rect' | 'roundRect' | 'ellipse' | 'cylinder' | 'rtArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'triangle' | 'rtTriangle' | 'diamond' | 'parallelogram' | 'trapezoid' | 'pentagon' | 'hexagon' | 'octagon' | 'chevron' | 'star5' | 'star6' | 'star8' | 'plus' | 'heart' | 'cloud' | 'sun' | 'moon' | 'pie' | 'plaque' | 'teardrop' | 'line' | 'connector';
 interface AutosaveRecord {
     key: string;
     data: Uint8Array;
@@ -1506,29 +1558,6 @@ interface PrintSettings {
     customRangeTo: number;
 }
 
-/**
- * Minimal i18n for the vanilla binding.
- *
- * The other bindings delegate to their framework's i18n runtime (react-i18next,
- * vue-i18n, ngx-translate) fed by the shared `pptx.*` dictionary. The vanilla
- * binding has no framework, so this module provides the one missing piece: a
- * `t(key, params)` lookup with `{{param}}` interpolation over the same shared
- * English dictionary, plus per-locale overrides supplied by the host.
- *
- * Resolution order: host dictionary for the active locale, then the built-in
- * English dictionary, then a humanised fallback derived from the key (shared
- * `keyToLabel`), so a missing key never renders as a raw `pptx.*` string.
- */
-/** Translate a dotted `pptx.*` key with optional `{{param}}` interpolation. */
-type Translator = (key: string, params?: Record<string, string | number>) => string;
-/** Locale to flat `key: message` dictionary map supplied by the host. */
-type TranslationMessages = Record<string, Record<string, string>>;
-/**
- * Build a {@link Translator} for a locale. `messages[locale]` (when provided)
- * wins over the built-in English dictionary; English is always the fallback.
- */
-declare function createTranslator(locale?: string, messages?: TranslationMessages): Translator;
-
 /**
  * A tiny framework-free reactive store: `get` / `set(patch)` / `subscribe`.
  *
@@ -1587,6 +1616,51 @@ interface ViewerState {
      * navigation for the life of the viewer instance (in-memory only).
      */
     notesExpanded: boolean;
+    /** In-memory clipboard payload from the last copy/cut, or null. */
+    clipboardPayload: ElementClipboardPayload | null;
+}
+
+/**
+ * Z-order, align, flip, and group/ungroup actions for the ribbon's
+ * Home > Arrange group.
+ *
+ * Align/distribute: the vanilla editor's selection model is single-element
+ * only (see `state/viewer-state.ts`), so `alignElements` reaches the
+ * single-selection "align to slide" mode ({@link alignToCanvas}), matching
+ * PowerPoint's own behaviour when nothing else is selected. Multi-selection
+ * "align to selection bounding box" / distribute (needing >= 2 / >= 3
+ * elements, see `editor-arrange-mutations.ts`) is unreachable until a
+ * multi-select model lands; `canDistribute` is therefore always `false` today
+ * (see `editing-chrome-sync.ts`), a documented limitation rather than a bug.
+ *
+ * Group: needs >= 2 selected elements to be meaningful, so it too is
+ * unreachable under single selection; `groupSelected` is a deliberate no-op
+ * kept only so the ribbon button (permanently disabled, with an explanatory
+ * title) has something to call. Ungroup works today: it applies to whichever
+ * single `group` element is selected.
+ */
+interface ArrangeActions {
+    bringForward(): void;
+    sendBackward(): void;
+    bringToFront(): void;
+    sendToBack(): void;
+    alignElements(edge: AlignEdge): void;
+    flipHorizontal(): void;
+    flipVertical(): void;
+    groupSelected(): void;
+    ungroupSelected(): 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
+ * lives on `ViewerState.clipboardPayload` (not a module-level variable) so
+ * the ribbon's selection sync can reactively enable/disable the Paste button.
+ */
+interface ClipboardActions {
+    copy(): void;
+    cut(): void;
+    paste(): void;
 }
 
 /**
@@ -1599,29 +1673,49 @@ interface ViewerState {
  * side effects needed to turn a chosen image file into a data-URL image
  * element; it too returns a centred, ready-to-insert element.
  */
-/** The shape/text/table element kinds the insert menu can create directly. */
-type InsertKind = 'text' | 'rect' | 'ellipse' | 'line' | 'table';
+/** The element kinds the Insert ribbon tab can create directly. */
+type InsertKind = 'text' | 'table' | 'shape';
 
-/** The selection-derived state the toolbar reflects (enable/disable + values). */
-interface FormatSelectionState {
-    hasSelection: boolean;
-    canText: boolean;
-    canShape: boolean;
-    bold: boolean;
-    italic: boolean;
-    underline: boolean;
-    fontSize: number;
-    textColor: string | undefined;
-    highlightColor: string | undefined;
-    fillColor: string | undefined;
-    strokeColor: string | undefined;
+/**
+ * New/duplicate/delete-slide actions for the ribbon's Home > Slides group,
+ * backed by the shared `slide-operations.ts` factory. Every mutation is
+ * history-integrated (matches the element-level actions in `editor-edit-ops`)
+ * and renumbers `slideNumber` across the whole deck so it always matches the
+ * array index (mirrors the Vue `useSlideOperations` contract).
+ */
+interface SlideActions {
+    addSlide(): void;
+    duplicateSlide(): void;
+    deleteSlide(): void;
 }
-interface FormatToolbar {
-    el: HTMLElement;
-    /** Reflect the current selection (enable/disable controls + seed values). */
-    update(state: FormatSelectionState): void;
-    /** Show/hide the whole row (editing mode on/off). */
-    setEditable(editable: boolean): void;
+
+/**
+ * Character + paragraph formatting actions for the ribbon's Home > Font and
+ * Home > Paragraph groups. Every method is a thin `applyToSelected` wrapper
+ * around the pure builders in `editor-format-mutations.ts` /
+ * `editor-paragraph-mutations.ts`; this file owns none of the mutation logic
+ * itself, only the selection/history wiring shared by the whole action set.
+ */
+interface TextActions {
+    toggleBold(): void;
+    toggleItalic(): void;
+    toggleUnderline(): void;
+    toggleStrikethrough(): void;
+    toggleTextShadow(): void;
+    changeFontSize(delta: number): void;
+    setFontSize(size: number): void;
+    setFontFamily(family: string): void;
+    setTextColor(color: string): void;
+    setHighlightColor(color: string): void;
+    setCharacterSpacing(value: number): void;
+    changeCase(mode: ChangeCaseMode): void;
+    clearFormatting(): void;
+    toggleBulletList(): void;
+    toggleNumberedList(): void;
+    increaseIndent(): void;
+    decreaseIndent(): void;
+    setTextAlign(align: a0['align']): void;
+    setLineSpacing(value: number): void;
 }
 
 /** A geometry patch from the inspector (all fields optional). */
@@ -1633,31 +1727,67 @@ interface GeometryPatch {
     rotation?: number;
 }
 /**
- * The formatting / insert / arrange actions exposed to the editing chrome
- * (format toolbar, inspector, insert menu). Every mutating action is
- * history-integrated (push -> mutate -> commit) via the shared {@link EditorOps}.
+ * The full set of formatting / insert / arrange / clipboard / slide actions
+ * exposed to the editing chrome (ribbon, inspector). Composed from the
+ * focused per-concern action files (`editor-text-actions.ts`,
+ * `editor-arrange-actions.ts`, `editor-clipboard-actions.ts`,
+ * `editor-slide-actions.ts`) plus the shape/geometry/insert actions owned
+ * directly here. Every mutating action is history-integrated (push -> mutate
+ * -> commit) via the shared {@link EditorOps}.
  */
-interface EditActions {
-    toggleBold(): void;
-    toggleItalic(): void;
-    toggleUnderline(): void;
-    changeFontSize(delta: number): void;
-    setFontSize(size: number): void;
-    setTextColor(color: string): void;
-    setHighlightColor(color: string): void;
+interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions {
     setShapeFill(color: string): void;
     setShapeStroke(color: string): void;
     setShapeStrokeWidth(width: number): void;
     /** Commit an inspector geometry edit (X/Y/W/H/rotation). */
     setGeometry(patch: GeometryPatch): void;
-    insert(kind: InsertKind): void;
+    insert(kind: InsertKind, shapeType?: ShapePresetType): void;
     insertImage(): Promise<void>;
-    bringForward(): void;
-    sendBackward(): void;
-    bringToFront(): void;
-    sendToBack(): void;
+    duplicateSelected(): void;
+    deleteSelected(): void;
+}
+
+/**
+ * Find & Replace actions for the ribbon's Home > Editing group, backed by the
+ * shared `find-replace.ts` helpers. A lean, docked-panel implementation:
+ * `search` reports a match count for the query, `replaceCurrent` replaces the
+ * first match, and `replaceAll` replaces every match; there is no in-canvas
+ * match highlighting or "next/previous match" cursor (that needs per-match
+ * selection/scroll wiring into the renderer, out of scope for this wave).
+ * Every replace is history-integrated like every other editor action.
+ */
+interface FindReplaceActions {
+    /** Count occurrences of `query` across all slides (does not mutate). */
+    search(query: string, matchCase: boolean): number;
+    /** Replace the first match of `query`; returns the number replaced (0 or 1). */
+    replaceCurrent(query: string, replacement: string, matchCase: boolean): number;
+    /** Replace every match of `query`; returns the number replaced. */
+    replaceAll(query: string, replacement: string, matchCase: boolean): number;
 }
 
+/**
+ * Minimal i18n for the vanilla binding.
+ *
+ * The other bindings delegate to their framework's i18n runtime (react-i18next,
+ * vue-i18n, ngx-translate) fed by the shared `pptx.*` dictionary. The vanilla
+ * binding has no framework, so this module provides the one missing piece: a
+ * `t(key, params)` lookup with `{{param}}` interpolation over the same shared
+ * English dictionary, plus per-locale overrides supplied by the host.
+ *
+ * Resolution order: host dictionary for the active locale, then the built-in
+ * English dictionary, then a humanised fallback derived from the key (shared
+ * `keyToLabel`), so a missing key never renders as a raw `pptx.*` string.
+ */
+/** Translate a dotted `pptx.*` key with optional `{{param}}` interpolation. */
+type Translator = (key: string, params?: Record<string, string | number>) => string;
+/** Locale to flat `key: message` dictionary map supplied by the host. */
+type TranslationMessages = Record<string, Record<string, string>>;
+/**
+ * Build a {@link Translator} for a locale. `messages[locale]` (when provided)
+ * wins over the built-in English dictionary; English is always the fallback.
+ */
+declare function createTranslator(locale?: string, messages?: TranslationMessages): Translator;
+
 /** Selection-derived state the inspector reflects. */
 interface InspectorState {
     hasSelection: boolean;
@@ -1694,52 +1824,52 @@ interface NotesPanel {
     setExpanded(expanded: boolean): void;
 }
 
-interface ThumbnailRail {
-    el: HTMLElement;
-    /** Rebuild the rail for a new slide list (uses `renderStage` per slide). */
-    render(slides: P[], canvasSize: CanvasSize, renderStage: (slide: P, scale: number) => HTMLElement): void;
-    /** Highlight the active slide and scroll it into view. */
-    setActive(index: number): void;
-    /** Show or hide the rail. */
-    setVisible(visible: boolean): void;
-}
-
-interface ToolbarUpdate {
-    /** Zero-based current slide index. */
+/** Nav-row state (prev/next/counter/zoom label). */
+interface RibbonNavState {
     current: number;
-    /** Total slide count. */
     total: number;
-    /** Effective zoom percentage (100 = 1:1). */
     zoomPercent: number;
 }
-/** Editing-cluster state (Save / Undo / Redo buttons). */
-interface ToolbarEditState {
-    /** Shows/hides the whole editing cluster. */
+/** Primary-row + tab-bar visibility state. */
+interface RibbonEditState {
     editable: boolean;
     canUndo: boolean;
     canRedo: boolean;
 }
-interface Toolbar {
+/** Selection-derived state the Home tab's Font/Paragraph/Arrange groups reflect. */
+interface RibbonSelectionState {
+    hasClipboard: boolean;
+    slideCount: number;
+}
+
+interface Ribbon {
     el: HTMLElement;
-    update(state: ToolbarUpdate): void;
-    setEditState(state: ToolbarEditState): void;
-    /** Reflect the notes panel's expanded/collapsed state on the Notes button. */
+    update(state: RibbonNavState): void;
+    setEditState(state: RibbonEditState): void;
     setNotesExpanded(expanded: boolean): void;
-    /**
-     * Show the autosave status pill. `label` is the (already localized) text;
-     * `kind` drives the styling hook (`is-saving` / `is-error`). An empty label
-     * hides the pill.
-     */
     setAutosaveStatus(label: string, kind: 'idle' | 'saving' | 'saved' | 'error'): void;
+    /** Show/hide the whole editing surface (Home/Insert tab content + find/replace). */
+    setEditable(editable: boolean): void;
+    /** Reflect the current selection across the Home tab's Font/Paragraph/Arrange groups. */
+    updateSelection(selectedElement: a | undefined, extra: RibbonSelectionState): void;
+}
+
+interface ThumbnailRail {
+    el: HTMLElement;
+    /** Rebuild the rail for a new slide list (uses `renderStage` per slide). */
+    render(slides: P[], canvasSize: CanvasSize, renderStage: (slide: P, scale: number) => HTMLElement): void;
+    /** Highlight the active slide and scroll it into view. */
+    setActive(index: number): void;
+    /** Show or hide the rail. */
+    setVisible(visible: boolean): void;
 }
 
 /** The viewer's static DOM skeleton plus the mutable overlay controls. */
 interface ViewerChrome {
     /** `.pptxv` root (focusable; keyboard navigation attaches here). */
     root: HTMLElement;
-    toolbar: Toolbar | null;
-    /** Editing format toolbar (bold/fill/insert/z-order); null when disabled. */
-    formatToolbar: FormatToolbar | null;
+    /** The tabbed ribbon (primary row, nav row, tab bar + File/Home/Insert/View content); null when disabled. */
+    ribbon: Ribbon | null;
     /** Property inspector panel; null when disabled. */
     inspector: Inspector | null;
     thumbnails: ThumbnailRail | null;
@@ -1786,6 +1916,8 @@ interface EditorController {
     getSelectedElementId(): string | null;
     /** The formatting / insert / arrange actions for the editing chrome. */
     getEditActions(): EditActions;
+    /** The Find & Replace actions for the ribbon's docked panel. */
+    getFindReplaceActions(): FindReplaceActions;
     /** Commit the speaker-notes textarea's plain text onto the current slide. */
     commitNotes(notes: string): void;
     save(): Promise<Uint8Array>;
@@ -2367,6 +2499,7 @@ interface ChromeHost {
     editor: {
         commitNotes(notes: string): void;
         getEditActions(): EditActions;
+        getFindReplaceActions(): FindReplaceActions;
     };
     prev(): void;
     next(): void;
@@ -2381,6 +2514,11 @@ interface ChromeHost {
     getSlideCount(): number;
     enterPresentation(): Promise<void>;
     exitPresentation(): Promise<void>;
+    exportSlidePng(): Promise<void>;
+    exportPdf(): Promise<void>;
+    exportGif(): Promise<void>;
+    exportVideo(): Promise<void>;
+    print(): Promise<boolean>;
 }
 
 /** The export slice of the public viewer API (see `PptxViewerInstance`). */