pptx-react-viewer 4.51.1 → 4.52.1

package/dist/internals.d.ts

@@ -1,6 +1,6 @@
-import { CollaborationRole, CollaborationConfig, PowerPointViewerAPI, ViewerCustomizationApi, PptxAutosaveStatus, ShapeAdjustmentHandleDescriptor, ChangeCaseMode, ResolvedKeyboardCustomization, FindResult, EditorImagePasteOptions, InsertChartKind, InsertChartOptions, PasteSpecialFormat, SlidePasteRequest, SlideTemplateId, MorphTransitionPlan, ElementAnimationState, ZoomNavigationTarget, PresentationSnapshot, DocumentStorage, InlineTextDraftSink, ViewerMode, ShapeAdjustmentDragState, GestureKind, PointerLike, InlineTextEditSnapshot, InlineListReadResult, FreeformToolKind, CollaborationLivePatcher, SlideSizeEmu, ElementClipboardPayload, CropSession, FontEmbeddingDescriptor, MasterViewTarget, ViewportFitOptions, CollaborationInput, ToolbarActionId, CollaborationShellState, AnimationApplyGroup, ReviewCommentsHost, RulerUnit, FieldSubstitutionContext, EditPointsCommandId, EditPointsElementPatch, PresentationPointerTool, RunProgramNotice, BorrowedCollaborationAwareness, CollabLoadOrigin, AuthoredSlideRange, DocumentSaveReason, FragmentedLayer, PrintSettings, ThemeEditorEdit, CompareResult, ReadOnlyRecommendation, CompatibilityWarningToast, DeviceOrientation, ResolvedCustomization, AutosaveRecord, DeckSavePurpose, ZoomExcursion, TouchGestureCallbacks, ViewerAutosaveStatus, ViewerOptionsStore, ViewerOptions, AutosaveRecoveryPrompt, VirtualizedRange, ToolbarTabId } from 'ooxml-ui/pptx';
+import { CollaborationRole, CollaborationConfig, HistoryTheme, PowerPointViewerAPI, ViewerCustomizationApi, PptxAutosaveStatus, ShapeAdjustmentHandleDescriptor, ChangeCaseMode, ResolvedKeyboardCustomization, FindResult, EditorImagePasteOptions, InsertChartKind, InsertChartOptions, PasteSpecialFormat, SlidePasteRequest, SlideTemplateId, MorphTransitionPlan, ElementAnimationState, ZoomNavigationTarget, PresentationSnapshot, DocumentStorage, InlineTextDraftSink, ViewerMode, ShapeAdjustmentDragState, GestureKind, PointerLike, InlineTextEditSnapshot, InlineListReadResult, FreeformToolKind, CollaborationLivePatcher, SlideSizeEmu, ElementClipboardPayload, CropSession, FontEmbeddingDescriptor, MasterViewTarget, ViewportFitOptions, CollaborationInput, GoogleFontsOption, ToolbarActionId, CollaborationShellState, AnimationApplyGroup, ReviewCommentsHost, RulerUnit, FieldSubstitutionContext, EditPointsCommandId, EditPointsElementPatch, PresentationPointerTool, RunProgramNotice, BorrowedCollaborationAwareness, CollabLoadOrigin, AuthoredSlideRange, DocumentSaveReason, FragmentedLayer, PrintSettings, ThemeEditorEdit, CompareResult, ReadOnlyRecommendation, CompatibilityWarningToast, DeviceOrientation, ResolvedCustomization, AutosaveRecord, DeckSavePurpose, ZoomExcursion, TouchGestureCallbacks, ViewerAutosaveStatus, ViewerOptionsStore, ViewerOptions, AutosaveRecoveryPrompt, VirtualizedRange, ToolbarTabId } from 'ooxml-ui/pptx';
 export { CINEMATIC_TRANSITION_KEYFRAMES, CollaborationConfig, DEFAULT_MORPH_DURATION_MS, DEFAULT_TRANSITION_DURATION_MS, DeviceOrientation, EASE, INSTANT, MOBILE_BREAKPOINT, P14_TRANSITION_KEYFRAMES, P14_TRANSITION_KEYFRAMES_2, P14_TRANSITION_KEYFRAMES_ALL, RANDOM_ELIGIBLE_TYPES, ResolvedDirection, ResolvedDirection8, SLIDE_TRANSITION_KEYFRAMES, SLIDE_TRANSITION_KEYFRAMES_CSS, SlideTransitionAnimations, TABLET_BREAKPOINT, TRANSITION_SPEED_DURATION_MS, TouchGestureCallbacks, VirtualizedRange, WHEEL_SPOKE_COUNTS, computeVirtualRange, getCinematicTransitionAnimations, getP14TransitionAnimations, getSlideTransitionAnimations, resolveDirection, resolveDirection8, resolveOrientation, resolveSlideTransition, resolveTransitionDurationMs, resolveWheelSpokeCount } from 'ooxml-ui/pptx';
-import { PptxSlide, PptxElement, PptxElementAnimation, TextStyle, PptxHeaderFooter, ShapeStyle, PptxCommentMention, SmartArtLayout, InkPptxElement, ShapePptxElement, MergeShapeOperation, PptxSlideTransition, PptxAction, PptxSlideMaster, PptxModernCommentAuthor, PptxTheme, ParsedTableStyleMap, PptxThemeOption, PptxCustomShow, PptxSection, PptxPresentationProperties, PptxViewProperties, PptxNotesMaster, PptxHandoutMaster, PptxCustomProperty, PptxTagCollection, PptxCoreProperties, PptxAppProperties, PptxEmbeddedFont, MasterViewTab, PptxSlideLayout, PptxHandler, PptxLayoutOption, PptxLayoutPreview, PptxComment, ConnectorPptxElement, PptxThemePreset, PptxThemeColorScheme, PptxThemeFontScheme, PptxData, PptxHandlerSaveOptions, PptxSaveFormat, TextSegment, PptxModifyVerifier } from 'ooxml-core/pptx';
+import { PptxSlide, PptxElement, PptxElementAnimation, TextStyle, PptxHeaderFooter, PptxTheme, PptxSlideMaster, ShapeStyle, PptxCommentMention, SmartArtLayout, InkPptxElement, ShapePptxElement, MergeShapeOperation, PptxSlideTransition, PptxAction, PptxModernCommentAuthor, ParsedTableStyleMap, PptxThemeOption, PptxCustomShow, PptxSection, PptxPresentationProperties, PptxViewProperties, PptxNotesMaster, PptxHandoutMaster, PptxCustomProperty, PptxTagCollection, PptxCoreProperties, PptxAppProperties, PptxEmbeddedFont, MasterViewTab, PptxSlideLayout, PptxHandler, PptxLayoutOption, PptxLayoutPreview, PptxComment, ConnectorPptxElement, PptxThemePreset, PptxThemeColorScheme, PptxThemeFontScheme, PptxData, PptxHandlerSaveOptions, PptxSaveFormat, TextSegment, PptxModifyVerifier } from 'ooxml-core/pptx';
 import { CollaborationWriteBackState } from 'ooxml-core/collab';
 import * as Y from 'yjs';
 import { Doc } from 'yjs';
@@ -91,6 +91,8 @@ interface EditorHistorySnapshot {
   activeSlideIndex: number;
   slides: PptxSlide[];
   templateElementsBySlideId: Record<string, PptxElement[]>;
+  /** The theme at that point, so undoing a theme pick puts the theme back with the slides. */
+  theme?: HistoryTheme;
   actionLabel?: string;
 }
 //#endregion
@@ -639,6 +641,22 @@ interface EditorHistoryInput {
    * Slide or a notes edit left the flag false and crash recovery never ran.
    */
   onDirty?: () => void;
+  /**
+   * The deck's theme. Its colour scheme, font scheme and name are recorded with every snapshot,
+   * so a theme pick is an undo step like any other edit.
+   */
+  theme?: PptxTheme | undefined;
+  /**
+   * The slide masters. The theme part each one uses is recorded with the theme, so a theme
+   * applied by path is an undo step too, and its Undo points the masters back.
+   */
+  slideMasters?: readonly PptxSlideMaster[] | undefined;
+  /**
+   * Put a recorded theme back (an undo or redo crossing a theme change). The slides come back
+   * with the snapshot; the theme has to be written to the handler's theme part too, which this
+   * hook cannot reach, so the theme handlers do it.
+   */
+  onRestoreTheme?: (theme: HistoryTheme) => void;
   setSlides: (slides: PptxSlide[]) => void;
   setCanvasSize: (size: CanvasSize$1) => void;
   setActiveSlideIndex: (index: number) => void;
@@ -649,7 +667,12 @@ interface EditorHistoryInput {
   setHeaderFooter: (hf: PptxHeaderFooter) => void;
 }
 interface EditorHistoryResult {
-  commitSlides: (slides: PptxSlide[], label?: string, beforeSlides?: PptxSlide[]) => void;
+  /**
+   * Commit `slides` as one undo step. Pass `nextSlideMasters` when the same commit replaces the
+   * slide masters (a slide paste brings its own): the step's after state records their theme
+   * parts, so the masters arriving a render later are not read as a second step.
+   */
+  commitSlides: (slides: PptxSlide[], label?: string, beforeSlides?: PptxSlide[], nextSlideMasters?: readonly PptxSlideMaster[]) => void;
   canUndo: boolean;
   canRedo: boolean;
   undoLabel: string | undefined;
@@ -657,6 +680,11 @@ interface EditorHistoryResult {
   handleUndo: () => void;
   handleRedo: () => void;
   resetHistory: () => void;
+  /**
+   * Drop the undo and redo steps that would bring back a state `reaches` matches, with the steps
+   * behind them: a Slide Master view command removed a layout the package cannot get back.
+   */
+  forgetHistory: (reaches: (snapshot: EditorHistorySnapshot) => boolean) => void;
   /**
    * Pause (`true`) and resume (`false`) change tracking. A gallery hover preview swaps the
    * slides in for a moment; while tracking is held that is neither an undo step nor an edit, and
@@ -664,6 +692,15 @@ interface EditorHistoryResult {
    */
   holdTracking: (held: boolean) => void;
   markDirty: () => void;
+  /**
+   * Run `apply` without arming the undo tracker: the edits it makes show at
+   * once but are no undo step and leave the dirty flag alone, and the next
+   * committed edit records the state from before them. A colour picker drag
+   * applies its shades this way (shared `createLiveColorInput`), so the drag
+   * is one undo step when it settles. Synchronous: only edits made inside
+   * `apply` are exempt.
+   */
+  withoutUndoStep: (apply: () => void) => void;
   buildHistorySnapshot: (actionLabel?: string) => EditorHistorySnapshot;
 }
 declare function useEditorHistory(input: EditorHistoryInput): EditorHistoryResult;
@@ -957,8 +994,11 @@ declare function useElementManipulation(input: UseElementManipulationInput): Ele
 interface UseFindReplaceInput {
   slides: PptxSlide[];
   mode: string;
-  onSetActiveSlideIndex: (index: number) => void;
-  onSetSelectedElementId: (id: string | null) => void;
+  /**
+   * Go to a match's slide and select its element there (null for a speaker-notes match), in one
+   * step: the viewer's `showSlideSelection`, which keeps the selection across the slide change.
+   */
+  onShowMatch: (slideIndex: number, elementId: string | null) => void;
   onUpdateSlides: (updater: (slides: PptxSlide[]) => PptxSlide[]) => void;
   onMarkDirty: () => void;
   /** Host keyboard customisation (disabled / remapped Find shortcuts). */
@@ -979,14 +1019,14 @@ interface UseFindReplaceResult {
   setFindIncludeChartData: (value: boolean) => void;
   setFindIncludeNotes: (value: boolean) => void;
   setFindMatchCase: (matchCase: boolean) => void;
-  findResults: FindResult[];
+  findResults: readonly FindResult[];
   findResultIndex: number;
   performFind: () => void;
   navigateFindResult: (direction: 1 | -1) => void;
   handleReplace: () => void;
   handleReplaceAll: () => void;
 }
-declare function useFindReplace({ slides, mode, onSetActiveSlideIndex, onSetSelectedElementId, onUpdateSlides, onMarkDirty, keyboard }: UseFindReplaceInput): UseFindReplaceResult;
+declare function useFindReplace({ slides, mode, onShowMatch, onUpdateSlides, onMarkDirty, keyboard }: UseFindReplaceInput): UseFindReplaceResult;
 //#endregion
 //#region src/viewer/components/hyperlink-edit-types.d.ts
 /** The type of hyperlink target. */
@@ -1617,6 +1657,14 @@ interface EditPointsModeState {
   setActiveFreeformTool: (tool: FreeformToolKind | null) => void;
 }
 //#endregion
+//#region src/viewer/hooks/useSlideChangeSelection.d.ts
+interface SlideChangeSelection {
+  /** The slide the last {@link showSlideSelection} selected on, until the next slide change. */
+  slideSelectionRef: MutableRefObject<number | null>;
+  /** Go to `slideIndex` and select `elementId` there (nothing, for null), across the slide change. */
+  showSlideSelection: (slideIndex: number, elementId: string | null) => void;
+}
+//#endregion
 //#region src/viewer/hooks/viewer-core-state-types.d.ts
 /**
  * Input parameters for the {@link useViewerCoreState} hook.
@@ -1635,7 +1683,7 @@ interface UseViewerCoreStateInput {
  * that comprises the core viewer state. It is merged with {@link ViewerUIState}
  * inside {@link useViewerState} to produce the unified {@link ViewerState}.
  */
-interface ViewerCoreState extends InlineEditingState, EditPointsModeState {
+interface ViewerCoreState extends InlineEditingState, EditPointsModeState, SlideChangeSelection {
   /** Ref to the outermost container `<div>` wrapping the viewer. */
   containerRef: React$1.RefObject<HTMLDivElement | null>;
   /** Hidden `<input type="file">` used to trigger image file selection. */
@@ -2192,7 +2240,7 @@ interface SlideCanvasProps {
   /** Called when a table row is resized. */
   onResizeTableRow?: (elementId: string, rowIndex: number, newHeight: number) => void;
   /** Find & Replace results (all matches across all slides). */
-  findResults?: Array<{
+  findResults?: ReadonlyArray<{
     slideIndex: number;
     elementId: string;
     segmentIndex: number;
@@ -2332,6 +2380,8 @@ interface UseViewerBuildingBlocksInput extends ViewportFitOptions {
    * the handle's `goTo` to move an open deck.
    */
   initialSlide?: number;
+  /** As `PowerPointViewer`'s `googleFonts`: the Google Fonts fallback policy (off, or a self-hosted mirror). */
+  googleFonts?: GoogleFontsOption;
   /** Whether the built-in autosave-to-localStorage recovery timer is active. Defaults to true. */
   autosaveEnabled?: boolean;
   /** Display name used as the author for comments. */
@@ -3182,11 +3232,21 @@ declare function useExportHandlers(input: UseExportHandlersInput): ExportHandler
 //#endregion
 //#region src/viewer/hooks/usePrintHandlers.d.ts
 interface UsePrintHandlersInput {
+  /** The editable slides (template elements partitioned out, as the viewer state holds them). */
   slides: PptxSlide[];
   activeSlideIndex: number;
   canvasStageRef: RefObject<HTMLDivElement | null>;
   setActiveSlideIndex: React.Dispatch<React.SetStateAction<number>>;
-  /** Parsed PPTX data (needed for SVG print path). Optional for backward compat. */
+  /** Slide size in CSS pixels: the vector slides are exported at it. */
+  canvasSize: CanvasSize$1;
+  /**
+   * The layout and master elements partitioned out of each slide, merged back
+   * for the vector export and the outline (`buildSaveSlides`).
+   */
+  templateElementsBySlideId?: Record<string, PptxElement[]>;
+  /** The deck's handout master, painted on every handouts page. */
+  handoutMaster?: PptxHandoutMaster;
+  /** @deprecated Pass `canvasSize` and `handoutMaster`; only its `handoutMaster` is still read. */
   pptxData?: PptxData;
 }
 interface PrintHandlersResult {
@@ -3201,13 +3261,14 @@ declare function usePrintHandlers(input: UsePrintHandlersInput): PrintHandlersRe
 //#region src/viewer/hooks/useThemeHandlers.d.ts
 interface UseThemeHandlersInput {
   handlerRef: RefObject<PptxHandler | null>;
-  serializeSlides: () => Promise<Uint8Array | null>;
-  setContent: React.Dispatch<React.SetStateAction<ArrayBuffer | Uint8Array | null>>;
-  onContentChange: ((data: Uint8Array) => void) | undefined;
   setTheme: React.Dispatch<React.SetStateAction<Record<string, unknown> | null>>;
   setSlideMasters: React.Dispatch<React.SetStateAction<Array<Record<string, unknown>>>>;
   slideMasters: Array<Record<string, unknown>>;
+  /** The deck's theme parts as loaded; an undo back to the loaded theme restores its name. */
+  themeOptions?: PptxThemeOption[];
   history: EditorHistoryResult;
+  /** The live slides, which a theme applied by path re-themes in place. */
+  slides: PptxSlide[];
   /** Current live slides, re-coloured in place on a scheme-colour change. */
   setSlides: React.Dispatch<React.SetStateAction<PptxSlide[]>>;
   /**
@@ -3234,13 +3295,15 @@ interface ThemeHandlersResult {
   handleUpdateThemeName: (name: string) => Promise<void>;
   handleApplyThemeToPresentation: () => Promise<void>;
   handleApplyThemeData: (colorScheme: PptxThemeColorScheme, fontScheme: PptxThemeFontScheme, themeName?: string) => Promise<void>;
+  /** Undo or redo crossed a theme change: put that theme back (see `useEditorHistory`). */
+  handleRestoreHistoryTheme: (theme: HistoryTheme) => Promise<void>;
   handleSetTemplateBackground: (path: string, backgroundColor: string | undefined) => void;
   handleGetTemplateBackgroundColor: (path: string) => string | undefined;
   /** Return theme parts discovered in the loaded PPTX archive. */
   handleGetAvailableThemes: () => Promise<PptxThemeOption[]>;
   /**
-   * Switch the presentation to an existing theme by its archive path,
-   * update all slide masters, and refresh the serialised content.
+   * Switch every slide master to an existing theme part by its archive path, in place, as one
+   * undo step.
    */
   handleSwitchTheme: (themePath: string) => Promise<void>;
 }
@@ -3503,14 +3566,7 @@ interface UseIOHandlersInput {
    * output format, so the downloaded file carries every save option Save does.
    */
   serializeSlides: SerializeSlides;
-  /**
-   * Plaintext serialisation for bytes the viewer feeds straight back into its
-   * own loader. "Apply theme" does exactly that, and the loader has no password
-   * to offer, so it must never receive an encrypted package.
-   */
-  serializeForRecovery: () => Promise<Uint8Array | null>;
   setContent: React$1.Dispatch<React$1.SetStateAction<ArrayBuffer | Uint8Array | null>>;
-  onContentChange: ((content: Uint8Array) => void) | undefined;
   /** The host's `onPropertiesChange` (document-properties edits). */
   onPropertiesChange?: ((updates: Partial<PptxCoreProperties>) => void) | undefined;
   /** The host's `onNotesUpdate` (speaker-notes edits). */
@@ -3571,6 +3627,8 @@ interface UseContentLifecycleInput {
   allowExternalImages?: boolean;
   /** Forwarded to {@link useLoadContent}: the host `initialSlide` prop. */
   initialSlide?: number;
+  /** Forwarded to {@link useFontInjection}: the host `googleFonts` prop. */
+  googleFonts?: GoogleFontsOption;
   /** Forwarded to {@link useLoadContent}: see `useReadOnlyRecommendationState`. */
   setReadOnlyRecommendation: React$1.Dispatch<React$1.SetStateAction<ReadOnlyRecommendation>>;
   /** Forwarded to {@link useLoadContent}: see `useReadOnlyRecommendationState`. */
@@ -3673,6 +3731,8 @@ interface UseViewerIntegrationInput {
   allowExternalImages?: boolean;
   /** Host `initialSlide` prop: the slide shown after each load; forwarded to `useContentLifecycle`. */
   initialSlide?: number;
+  /** Host `googleFonts` prop: the Google Fonts fallback policy; forwarded to `useFontInjection`. */
+  googleFonts?: GoogleFontsOption;
   /** Forwarded to `useContentLifecycle` -> `useLoadContent`: see `useReadOnlyRecommendationState`. */
   setReadOnlyRecommendation: Dispatch<SetStateAction<ReadOnlyRecommendation>>;
   /** Forwarded to `useContentLifecycle` -> `useLoadContent`: see `useReadOnlyRecommendationState`. */
@@ -4102,8 +4162,10 @@ declare function useExportSaveAs(input: UseExportSaveAsInput): ExportSaveAsResul
 interface UseFontInjectionInput {
   embeddedFonts: PptxEmbeddedFont[];
   slides: PptxSlide[];
+  /** Host `googleFonts` policy: unset loads from Google, `false` disables, `{ baseUrl }` mirrors. */
+  googleFonts?: GoogleFontsOption;
 }
-declare function useFontInjection({ embeddedFonts, slides }: UseFontInjectionInput): void;
+declare function useFontInjection({ embeddedFonts, slides, googleFonts }: UseFontInjectionInput): void;
 //#endregion
 //#region src/viewer/hooks/useGroupAlignLayerHandlers.d.ts
 interface GroupAlignLayerInput {