pptx-react-viewer 4.17.0 → 4.18.0

package/dist/internals.d.ts

@@ -2617,10 +2617,127 @@ interface PresentationInkStroke {
   points: PresentationInkPoint[];
 }
 //#endregion
+//#region src/render/presentation-blackboard.d.ts
+/** Blackout state, as carried by {@link PresentationSnapshot}. */
+type PresentationBlackout = PresentationSnapshot['blackout'];
+//#endregion
 //#region src/render/paste-special.d.ts
 /** The four paste formats PowerPoint's Paste Options / Paste Special offer. */
 type PasteSpecialFormat = 'keep-source-formatting' | 'use-destination-theme' | 'picture' | 'keep-text-only';
 //#endregion
+//#region src/render/chrome-controls-state.d.ts
+type ChromeTranslate = (key: string, params?: Record<string, string | number>) => string;
+type ReadOnlyBannerPasswordError = 'wrong-password' | 'unsupported-algorithm';
+interface ReadOnlyBannerViewState {
+  /** `ReadOnlyRecommendation.kind`; mirrored onto the host's `data-kind`. */
+  kind: string | null;
+  /** `ReadOnlyRecommendation.messageKey`, translated by `translate`. */
+  messageKey: string;
+  /** Swap the Edit anyway / Dismiss pair for the inline password form. */
+  passwordPromptOpen?: boolean;
+  passwordError?: ReadOnlyBannerPasswordError | null;
+  /** Disables the form while a submitted password is being checked. */
+  checkingPassword?: boolean;
+  translate?: ChromeTranslate;
+}
+interface PasteOptionsViewState {
+  /** Right edge of the pasted element in viewport pixels. */
+  left: number;
+  /** Bottom edge of the pasted element in viewport pixels. */
+  top: number;
+  translate?: ChromeTranslate;
+}
+interface CompatToastViewItem {
+  readonly id: string;
+  readonly code: string;
+  readonly severity: 'info' | 'warning';
+  readonly messageKey: string;
+  readonly params?: Readonly<Record<string, string>>;
+}
+interface CompatToastsViewState {
+  /** Dismiss-filtered toasts. The element shows the first {@link COMPAT_TOAST_VISIBLE_LIMIT}. */
+  toasts: readonly CompatToastViewItem[];
+  /** Extra toasts a host already trimmed off the list it passes. */
+  overflowCount?: number;
+  /** Width of the open right-docked panel (see `compatToastStackStyle`). */
+  rightInset?: number;
+  /** Live height of the docked notes strip (see `compatToastStackStyle`). */
+  bottomInset?: number;
+  translate?: ChromeTranslate;
+}
+type DialogFooterVariant = 'secondary' | 'primary' | 'warning';
+type DialogFooterIcon = 'trash' | 'pen' | 'restore' | 'print' | 'check';
+interface DialogFooterAction {
+  /** Stable id echoed back in the `dialog-footer-request` intent. */
+  id: string;
+  /** Already-translated visible label and accessible name. */
+  label: string;
+  variant?: DialogFooterVariant;
+  icon?: DialogFooterIcon;
+  disabled?: boolean;
+  /** Optional `data-testid` stamped on the button. */
+  testId?: string;
+}
+interface DialogFooterViewState {
+  actions: readonly DialogFooterAction[];
+}
+type MobileBarId = 'slides' | 'insert' | 'inspector' | 'comments' | 'notes';
+interface MobileBarViewState {
+  /** Every button disables at 0 (see `buildBarActions`). */
+  slideCount: number;
+  /** The button whose sheet is open; reflected as `aria-pressed` and a top pill. */
+  activeSheet?: MobileBarId | null;
+  /** Comment count on the badge of Comments (`99+` above 99). */
+  commentCount?: number;
+  /** Buttons dropped entirely, such as Notes when `hiddenActions` hides it. */
+  hidden?: readonly MobileBarId[];
+  /** Buttons disabled beyond the no-slides rule, such as edit-only ones in view mode. */
+  disabled?: readonly MobileBarId[];
+  translate?: ChromeTranslate;
+}
+type MobileToolbarId = 'menu' | 'undo' | 'redo' | 'ai' | 'save' | 'present' | 'share';
+interface MobileToolbarViewState {
+  /** Menu, Undo, Redo, AI and Share only show while editing. */
+  editable: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Host opted into the AI assistant; the element draws its toggle. */
+  aiVisible?: boolean;
+  aiActive?: boolean;
+  /** Reflected as `aria-expanded` on Menu when given. */
+  menuOpen?: boolean;
+  /** Buttons dropped entirely (`hiddenActions`, or Share when the host has none). */
+  hidden?: readonly MobileToolbarId[];
+  /** Buttons disabled, such as Present while there is nothing to present. */
+  disabled?: readonly MobileToolbarId[];
+  translate?: ChromeTranslate;
+}
+interface PresentToolbarViewState {
+  /** Zero-based slide on screen. */
+  current: number;
+  total: number;
+  /** The armed annotation tool; `none` leaves every tool unpressed. */
+  tool: PresentationPointerTool;
+  penColor: string;
+  highlighterColor: string;
+  hasAnnotations: boolean;
+  /** With the pen, marks the Blackboard toggle active (`isBlackboardActive`). */
+  blackout: PresentationBlackout;
+  /** Show the presenter-view toggle (default false). */
+  presenterViewVisible?: boolean;
+  presenterViewActive?: boolean;
+  /** Epoch ms the show started. The element ticks the readout; null shows 00:00. */
+  startTime: number | null;
+  translate?: ChromeTranslate;
+}
+interface PresenterConsoleViewState {
+  /** Ids of toggles that read as on (and the resume / close-window variants). */
+  active: readonly string[];
+  /** Ids of controls that are disabled. */
+  disabled: readonly string[];
+  translate?: ChromeTranslate;
+}
+//#endregion
 //#region src/render/find-replace.d.ts
 /** Identifies a single match of the find query at segment-level precision. */
 interface FindResult {
@@ -2724,6 +2841,24 @@ interface ZoomExcursion {
   /** The zoom's own `transitionDur`, applied to the jump INTO the target and to the return jump. */
   transitionDurationMs?: number;
 }
+//#endregion
+//#region src/render/command-search.d.ts
+/**
+ * Command-search data for the PowerPoint-style "Tell me what you want to do"
+ * search bar. Provides searchable command entries grouped by category, each
+ * mapping a label translation key to a command identifier that bindings can
+ * dispatch.
+ */
+interface CommandSearchEntry {
+  /** Translation key for the display label. */
+  labelKey: string;
+  /** Command identifier dispatched to the host binding. */
+  command: string;
+  /** Optional icon hint (binding resolves to framework icon component). */
+  icon?: string;
+  /** Category grouping key; hosts with their own short list may omit it. */
+  category?: 'format' | 'insert' | 'view' | 'slideShow' | 'design' | 'arrange';
+}
 /** Everything a binding needs to render the recovery dialog, and nothing else. */
 interface AutosaveRecoveryPrompt {
   /** IndexedDB key the snapshot is stored under (the deck's file path/name). */
@@ -3152,11 +3287,15 @@ interface RibbonHomeControlState {
   disabled?: boolean;
   /** Omit for ordinary commands; a boolean reflects `aria-pressed`. */
   pressed?: boolean;
+  /** Popover triggers only: reflects `aria-expanded` while the native popover is open. */
+  expanded?: boolean;
   hidden?: boolean;
 }
+/** State key of a control: its id, or `id#part` when several buttons share one id. */
+type RibbonHomeKey = RibbonControlId | `${RibbonControlId}#${string}`;
 interface RibbonHomeViewState {
   /** Missing entries are enabled, unpressed and visible. */
-  controls: Readonly<Partial<Record<RibbonControlId, RibbonHomeControlState>>>;
+  controls: Readonly<Partial<Record<RibbonHomeKey, RibbonHomeControlState>>>;
   translate?: (key: string) => string;
 }
 /** Controlled View tab state. Native viewers own the values and every side effect. */
@@ -3189,6 +3328,113 @@ interface RibbonTransitionsViewState {
   translate?: RibbonTransitionsTranslate;
 }
 //#endregion
+//#region src/render/status-bar-state.d.ts
+/**
+ * Shared model for the bottom status bar (`pptx-ui-status-bar`).
+ *
+ * The slide counter, save indicator, notes toggle, view-mode buttons and zoom
+ * cluster were hand-built five times. The view owns the markup, pressed state
+ * and gating; hosts own every effect (notes panel, view switching, zoom).
+ */
+type StatusBarTranslate = (key: string, params?: Record<string, string | number>) => string;
+type StatusBarSaveKind = 'idle' | 'saving' | 'error';
+type StatusBarViewMode = 'normal' | 'sorter' | 'slideShow';
+interface StatusBarViewState {
+  slideCount: number;
+  /** Zero-based active slide; clamped into range for display. */
+  activeSlideIndex: number;
+  /** Already-translated save indicator, see {@link resolveStatusBarSave}. */
+  saveText: string;
+  saveKind?: StatusBarSaveKind;
+  /** Omit to hide the whole zoom cluster. */
+  zoomPercent?: number;
+  showNotes?: boolean;
+  notesExpanded?: boolean;
+  /** Default true. False drops the Normal / Sorter / Slide Show cluster. */
+  showViewModes?: boolean;
+  /** Default true. */
+  showSorter?: boolean;
+  /** Default true. */
+  showSlideShow?: boolean;
+  /** The pressed view button; omit when none is active. */
+  viewMode?: StatusBarViewMode;
+  translate?: StatusBarTranslate;
+}
+//#endregion
+//#region src/render/notes-toolbar-state.d.ts
+/**
+ * Shared model for the speaker-notes formatting toolbar (`pptx-ui-notes-toolbar`).
+ *
+ * The toolbar owns the buttons, their order, icons, labels, enabled state and
+ * the hyperlink popover. Hosts own the contenteditable editor, selection-based
+ * edits, history, printing and persistence, and route typed intents to them.
+ */
+type NotesToolbarTranslate = (key: string, params?: Record<string, string | number>) => string;
+interface NotesToolbarViewState {
+  /** True while the rich (contenteditable) surface is active. Drives the mode button label. */
+  rich: boolean;
+  /** Enables the formatting buttons. False in the plain editor, where they cannot act. */
+  canFormat: boolean;
+  /** Shows the Print button. */
+  showPrint: boolean;
+  /** Disables every button, for example while no slide is selected. */
+  disabled?: boolean;
+  /** Host translator; keys are the canonical `pptx.notes.*` set. Omitted: keys are shown. */
+  translate?: NotesToolbarTranslate;
+}
+//#endregion
+//#region src/render/title-bar-state.d.ts
+type TitleBarTranslate = (key: string, params?: Record<string, string | number>) => string;
+type TitleBarPlacement = 'titleBar' | 'belowRibbon';
+type TitleBarTone = 'idle' | 'saving' | 'error';
+interface TitleBarAutosaveView {
+  enabled: boolean;
+  /** Default true. False renders the switch inert (host policy `autosave: false`). */
+  toggleAvailable?: boolean;
+  /** Translation key from `resolveTitleBarStatusKey`. */
+  statusKey: string;
+  /** Colour of the status text; only meaningful while `enabled`. */
+  tone?: TitleBarTone;
+}
+interface TitleBarHistoryState {
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Description of the pending action, e.g. "Delete shape". */
+  undoLabel?: string | null;
+  redoLabel?: string | null;
+  /** Default true. Maps to `hiddenActions: ['undo']`. */
+  showUndo?: boolean;
+  /** Default true. Maps to `hiddenActions: ['redo']`. */
+  showRedo?: boolean;
+}
+interface TitleBarQuickAccessView {
+  visible: boolean;
+  position: QuickAccessPosition;
+  showCommandLabels: boolean;
+  /** Ordered catalog ids (File > Options > Quick Access Toolbar). */
+  commandIds: readonly string[];
+}
+interface TitleBarViewState {
+  /** Edit mode with an editable deck. Gates AutoSave, the strip, status and search. */
+  editing: boolean;
+  /** Whether the command search shows; hosts pass `editing`. */
+  searchVisible: boolean;
+  /** Display name; the translated default shows when empty. */
+  fileName?: string;
+  autosave: TitleBarAutosaveView;
+  history: TitleBarHistoryState;
+  /** Default true. */
+  showSave?: boolean;
+  quickAccess: TitleBarQuickAccessView;
+  /** Search catalogue; defaults to the shared `COMMAND_SEARCH_ENTRIES`. */
+  commands?: readonly CommandSearchEntry[];
+  /** Default true. False drops the "Find in Slides" fallback row. */
+  contentSearch?: boolean;
+  /** ScreenTip rule (Options > General); returning undefined suppresses the title. */
+  screenTip?: (label: string) => string | undefined;
+  translate?: TitleBarTranslate;
+}
+//#endregion
 //#region src/web-components/theme-editor.d.ts
 interface PptxUiThemeEditorElement extends HTMLElement {
   theme: PptxTheme | undefined;
@@ -3200,6 +3446,74 @@ declare global {
     'pptx-ui-theme-editor': PptxUiThemeEditorElement;
   }
 }
+interface PptxUiCompatToastsElement extends HTMLElement {
+  state: CompatToastsViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-compat-toasts': PptxUiCompatToastsElement;
+  }
+}
+interface PptxUiDialogFooterElement extends HTMLElement {
+  state: DialogFooterViewState;
+  /** Move keyboard focus to an action, e.g. the primary one when a dialog opens. */
+  focusAction(id: string): void;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-dialog-footer': PptxUiDialogFooterElement;
+  }
+}
+interface PptxUiMobileBarElement extends HTMLElement {
+  state: MobileBarViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-mobile-bar': PptxUiMobileBarElement;
+  }
+}
+interface PptxUiMobileToolbarElement extends HTMLElement {
+  state: MobileToolbarViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-mobile-toolbar': PptxUiMobileToolbarElement;
+  }
+}
+interface PptxUiPasteOptionsElement extends HTMLElement {
+  state: PasteOptionsViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-paste-options': PptxUiPasteOptionsElement;
+  }
+}
+interface PptxUiPresentToolbarElement extends HTMLElement {
+  state: PresentToolbarViewState;
+  /** Close an open colour palette, e.g. when the host auto-hides the bar. */
+  closePalettes(): void;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-present-toolbar': PptxUiPresentToolbarElement;
+  }
+}
+interface PptxUiPresenterConsoleElement extends HTMLElement {
+  state: PresenterConsoleViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-presenter-console': PptxUiPresenterConsoleElement;
+  }
+}
+interface PptxUiReadOnlyBannerElement extends HTMLElement {
+  state: ReadOnlyBannerViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-read-only-banner': PptxUiReadOnlyBannerElement;
+  }
+}
 interface PptxUiRibbonAnimationsElement extends HTMLElement {
   state: RibbonAnimationsViewState;
 }
@@ -3218,6 +3532,8 @@ declare global {
 }
 interface PptxUiRibbonHomeElement extends HTMLElement {
   state: RibbonHomeViewState;
+  /** Wrapper (or button) of a control id, where a host mounts or anchors its native popover. */
+  anchor(id: string): HTMLElement | undefined;
 }
 declare global {
   interface HTMLElementTagNameMap {
@@ -3225,6 +3541,12 @@ declare global {
     'pptx-ui-ribbon-home-font': PptxUiRibbonHomeElement;
     'pptx-ui-ribbon-home-paragraph': PptxUiRibbonHomeElement;
     'pptx-ui-ribbon-home-editing': PptxUiRibbonHomeElement;
+    'pptx-ui-ribbon-home-slides': PptxUiRibbonHomeElement;
+    'pptx-ui-ribbon-home-drawing': PptxUiRibbonHomeElement;
+    'pptx-ui-ribbon-home-arrange-align': PptxUiRibbonHomeElement;
+    'pptx-ui-ribbon-home-arrange-flip': PptxUiRibbonHomeElement;
+    'pptx-ui-ribbon-home-arrange-order': PptxUiRibbonHomeElement;
+    'pptx-ui-ribbon-home-arrange-edit': PptxUiRibbonHomeElement;
   }
 }
 interface PptxUiRibbonTransitionsElement extends HTMLElement {
@@ -3292,6 +3614,74 @@ declare global {
     'pptx-ui-subtitle-settings': PptxUiSubtitleSettingsElement;
   }
 }
+interface PptxUiStatusBarElement extends HTMLElement {
+  state: StatusBarViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-status-bar': PptxUiStatusBarElement;
+  }
+}
+interface PptxUiNotesToolbarElement extends HTMLElement {
+  state: NotesToolbarViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-notes-toolbar': PptxUiNotesToolbarElement;
+  }
+}
+interface PptxUiTitleBarElement extends HTMLElement {
+  state: TitleBarViewState | undefined;
+  placement: TitleBarPlacement;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-title-bar': PptxUiTitleBarElement;
+  }
+}
+/** One row of a context menu. Hosts decide `id`, wording, gating and what activation does. */
+interface ContextMenuViewItem {
+  /** Stable command id, echoed by `menu-request`. */
+  id: string;
+  /** Already-translated visible label. */
+  label: string;
+  /** Draw a rule before this row. */
+  separatorBefore?: boolean;
+  /** Group heading shown before this row; the row and the ones after it join that group. */
+  heading?: string;
+  /** Destructive command (Delete): tinted. */
+  danger?: boolean;
+  /** Offered but unavailable: announced and drawn dim, skipped by arrow keys. */
+  disabled?: boolean;
+  /** A toggle (Grid and Guides, Ruler) in this state; omitted for one-shot commands. */
+  checked?: boolean;
+}
+/** Everything the controlled element needs to draw one menu. */
+interface ContextMenuViewState {
+  /** Pointer position, in viewport pixels. The element clamps it into the window. */
+  x: number;
+  y: number;
+  /** Accessible name of the menu. */
+  label: string;
+  items: readonly ContextMenuViewItem[];
+  /**
+   * Test-hook attributes copied onto the host element (`data-pptx-context-menu`,
+   * `data-pptx-canvas-context-menu`, ...). Only `data-pptx-*` names are accepted.
+   */
+  markers?: readonly string[];
+  /** Stacking order; defaults to {@link CONTEXT_MENU_EDITOR_LAYER}. */
+  zIndex?: number;
+  /** Move focus onto the first command on open. Default true. */
+  autoFocus?: boolean;
+}
+interface PptxUiContextMenuElement extends HTMLElement {
+  state: ContextMenuViewState;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'pptx-ui-context-menu': PptxUiContextMenuElement;
+  }
+}
 //#endregion
 //#region src/web-components/select-value.d.ts
 /** Public DOM shape used by all bindings; the element is not a native select. */