pptx-react-viewer 1.0.10 → 1.0.12

package/README.md

@@ -40,6 +40,9 @@ A full-featured **React** component for viewing, editing, and presenting PowerPo
   - [Hooks Reference](#hooks-reference)
   - [Utility Modules Reference](#utility-modules-reference)
   - [File Structure Reference](#file-structure-reference)
+  - [Localization (i18n)](#localization-i18n)
+    - [Setup](#setup)
+    - [How it works](#how-it-works)
   - [Limitations](#limitations)
 
 ---
@@ -767,6 +770,71 @@ src/
 
 ---
 
+## Localization (i18n)
+
+The viewer uses [i18next](https://www.i18next.com/) with [react-i18next](https://react.i18next.com/) for UI labels. Components call `useTranslation()` and look up dotted keys such as `t('pptx.statusBar.allSaved')`.
+
+### Setup
+
+Initialise an i18next instance with your translations and wrap your app in the `I18nextProvider` (or call `i18next.init()` before rendering). The demo app (`demo/i18n.ts`) shows a minimal configuration:
+
+```ts
+import { createInstance } from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+const i18n = createInstance();
+
+i18n.use(initReactI18next).init({
+	resources: {
+		en: {
+			translation: {
+				'pptx.statusBar.allSaved': 'All saved',
+				'pptx.sections.addSlide': 'Add Slide',
+				'pptx.notes.clickToAddNotes': 'Click to add notes',
+				// ... see demo/i18n.ts for the full key list
+			},
+		},
+	},
+	lng: 'en',
+	fallbackLng: 'en',
+	interpolation: { escapeValue: false },
+	// Optional: derive display text from dotted keys for undefined keys
+	parseMissingKeyHandler: (key) => {
+		const last = key.split('.').pop() ?? key;
+		return last.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/^./, (c) => c.toUpperCase());
+	},
+});
+```
+
+To add a new language, add a resource bundle under its language code (e.g. `fr`, `de`) and set `lng` accordingly.
+
+### How it works
+
+Translation keys follow the pattern `pptx.<area>.<label>` (e.g. `pptx.slideSorter.zoomIn`, `pptx.comments.addComment`). The demo configures a `parseMissingKeyHandler` that converts any undefined key into a Title Case label automatically, so components can reference keys that are not explicitly listed and still render sensible English text.
+
+Key namespaces currently in use:
+
+| Namespace               | Examples                                       |
+| ----------------------- | ---------------------------------------------- |
+| `pptx.statusBar.*`      | `allSaved`, `unsavedChanges`                   |
+| `pptx.autosave.*`       | `saving`, `saved`, `error`                     |
+| `pptx.sections.*`       | `addSlide`, `addSection`, `rename`, `delete`   |
+| `pptx.notes.*`          | `slideN`, `clickToAddNotes`, `noNotes`         |
+| `pptx.slideSorter.*`    | `zoomIn`, `zoomOut`, `close`                   |
+| `pptx.grid.*`           | `toggleGrid`, `snapToGrid`                     |
+| `pptx.field.*`          | `insertField`, `slideNumber`, `dateTime`       |
+| `pptx.master.*`         | `layout`, `noMasters`                          |
+| `pptx.export.*`         | `processing`, `cancel`                         |
+| `pptx.versionHistory.*` | `restore`, `noVersions`                        |
+| `pptx.presenter.*`      | `speakerNotes`, `nextSlidePreview`             |
+| `pptx.presentation.*`   | `pen`, `highlighter`, `eraser`, `laserPointer` |
+| `pptx.selectionPane.*`  | `show`, `hide`, `close`                        |
+| `pptx.inspector.*`      | `element`, `noSlideSelected`                   |
+| `pptx.comments.*`       | `addComment`, `noComments`                     |
+| `pptx.encryptedFile.*`  | `title`, `message`, `instructions`             |
+
+---
+
 ## Limitations
 
 - **CSS-based rendering** -- Slides are rendered as HTML/CSS rather than Canvas, which gives sharp text at any zoom, native accessibility, and DOM interactivity. The tradeoff is that some visual effects are approximated: `backdrop-filter` is replaced with semi-transparent backgrounds, `mix-blend-mode` is mapped to opacity fallbacks, and CSS 3D transforms (rotateX/Y) are flattened to 2D. Path gradients are approximated as elliptical radials.

package/dist/{PowerPointViewer-K2URyPlJ.d.mts → PowerPointViewer-DtLlYf0r.d.mts}

@@ -264,6 +264,8 @@ interface ViewerTheme {
  * `CollaborationProvider` and wires up presence tracking, remote cursors,
  * and CRDT-based state synchronisation.
  */
+/** Role of a user within a collaboration or broadcast session. */
+type CollaborationRole = 'collaborator' | 'broadcaster' | 'viewer';
 interface CollaborationConfig {
     /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
     roomId: string;
@@ -277,6 +279,8 @@ interface CollaborationConfig {
     userColor?: string;
     /** Optional authentication token sent with the WebSocket handshake. */
     authToken?: string;
+    /** Role in the session — defaults to `'collaborator'`. */
+    role?: CollaborationRole;
 }
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
@@ -303,6 +307,8 @@ interface UserPresence {
     lastUpdated: string;
     /** Optional currently selected element ID. */
     selectedElementId?: string;
+    /** Role in the session (broadcaster, viewer, or collaborator). */
+    role?: CollaborationRole;
 }
 /** Value exposed by `CollaborationContext`. */
 interface CollaborationContextValue {
@@ -316,6 +322,8 @@ interface CollaborationContextValue {
     connectedCount: number;
     /** The collaboration config that was provided. */
     config: CollaborationConfig;
+    /** The Yjs document (for document sync). */
+    doc: unknown | null;
 }
 
 /**
@@ -405,7 +413,7 @@ interface SlideSectionGroup {
 /** Alignment direction for distributing/aligning multiple selected elements on the slide. */
 type SlideAlignment = 'left' | 'center' | 'right' | 'top' | 'middle' | 'bottom';
 /** Identifies one of the ribbon-style toolbar tabs (home, insert, text, etc.). */
-type ToolbarSection = 'home' | 'insert' | 'text' | 'arrange' | 'draw' | 'design' | 'transitions' | 'review' | 'view';
+type ToolbarSection = 'file' | 'home' | 'insert' | 'text' | 'arrange' | 'draw' | 'design' | 'transitions' | 'animations' | 'slideShow' | 'review' | 'view' | 'help';
 /** The active drawing/inking tool selected in the Draw toolbar tab. */
 type DrawingTool = 'select' | 'pen' | 'highlighter' | 'eraser' | 'freeform';
 /** A single entry in the keyboard shortcuts help panel. */
@@ -459,6 +467,11 @@ interface PowerPointViewerProps {
     canEdit?: boolean;
     /** Optional class name */
     className?: string;
+    /**
+     * Display name used as the author for comments and annotations.
+     * Falls back to `collaboration.userName` when collaborating, or `'You'`.
+     */
+    authorName?: string;
     /**
      * Theme configuration for customising the viewer's appearance.
      *
@@ -501,6 +514,38 @@ interface PowerPointViewerProps {
      * ```
      */
     collaboration?: CollaborationConfig;
+    /**
+     * Callback invoked when the user starts a collaboration session from the
+     * Share dialog. The host app should use this to set the `collaboration`
+     * prop with the returned config.
+     */
+    onStartCollaboration?: (config: CollaborationConfig) => void;
+    /**
+     * Callback invoked when the user stops a collaboration session from the
+     * Share dialog. The host app should clear the `collaboration` prop.
+     */
+    onStopCollaboration?: () => void;
+    /**
+     * Default values for the Share dialog fields. The host app should provide
+     * these to control the session name, user display name, and server URL.
+     * If omitted, the Share dialog fields will be empty and require user input.
+     *
+     * @example
+     * ```tsx
+     * <PowerPointViewer
+     *   shareDefaults={{
+     *     roomId: "session-abc123",
+     *     userName: "Alice",
+     *     serverUrl: "ws://localhost:1234",
+     *   }}
+     * />
+     * ```
+     */
+    shareDefaults?: {
+        roomId?: string;
+        userName?: string;
+        serverUrl?: string;
+    };
 }
 interface PowerPointViewerHandle extends FileViewerHandle {
     getContent: () => Promise<Uint8Array>;
@@ -519,4 +564,4 @@ declare function getAnimationInitialStyle(preset: PptxAnimationPreset | undefine
  */
 declare const PowerPointViewer: React.ForwardRefExoticComponent<PowerPointViewerProps & React.RefAttributes<PowerPointViewerHandle>>;
 
-export { type AccessibilityIssue as A, type SlideSectionGroup as B, type CollaborationConfig as C, type DragState as D, type EditorHistorySnapshot as E, type FileViewerHandle as F, type SlideTransitionOption as G, type StrokeDashOption as H, type SupportedShapeType as I, type ToolbarSection as J, type ViewerMode as K, type MarqueeSelectionState as M, PowerPointViewer as P, type ResizeHandle as R, type ShapeAdjustmentDragState as S, type TableCellEditorState as T, type UserPresence as U, type ViewerThemeColors as V, type ViewerTheme as a, type PowerPointViewerHandle as b, type PowerPointViewerProps as c, type ConnectionStatus as d, type CollaborationContextValue as e, type AnimationPresetOption as f, getAnimationInitialStyle as g, type CanvasSize as h, type ConnectorArrowOption as i, type ConnectorGeometryOption as j, type ConnectorGeometryType as k, type ConnectorPathGeometry as l, type DrawingTool as m, type ElementBounds as n, type ElementClipboardPayload as o, type ElementContextMenuAction as p, type ElementContextMenuState as q, type ParsedTableCell as r, type ParsedTableData as s, type PresentationAnimationRuntime as t, type ResizeState as u, type ShapeAdjustmentHandleDescriptor as v, type ShapePreset as w, type ShapeQuickStyle as x, type ShortcutReferenceItem as y, type SlideAlignment as z };
+export { type AccessibilityIssue as A, type SlideAlignment as B, type CollaborationConfig as C, type DragState as D, type EditorHistorySnapshot as E, type FileViewerHandle as F, type SlideSectionGroup as G, type SlideTransitionOption as H, type StrokeDashOption as I, type SupportedShapeType as J, type ToolbarSection as K, type ViewerMode as L, type MarqueeSelectionState as M, PowerPointViewer as P, type ResizeHandle as R, type ShapeAdjustmentDragState as S, type TableCellEditorState as T, type UserPresence as U, type ViewerThemeColors as V, type ViewerTheme as a, type PowerPointViewerHandle as b, type PowerPointViewerProps as c, type ConnectionStatus as d, type CollaborationContextValue as e, type AnimationPresetOption as f, getAnimationInitialStyle as g, type CanvasSize as h, type CollaborationRole as i, type ConnectorArrowOption as j, type ConnectorGeometryOption as k, type ConnectorGeometryType as l, type ConnectorPathGeometry as m, type DrawingTool as n, type ElementBounds as o, type ElementClipboardPayload as p, type ElementContextMenuAction as q, type ElementContextMenuState as r, type ParsedTableCell as s, type ParsedTableData as t, type PresentationAnimationRuntime as u, type ResizeState as v, type ShapeAdjustmentHandleDescriptor as w, type ShapePreset as x, type ShapeQuickStyle as y, type ShortcutReferenceItem as z };

package/dist/{PowerPointViewer-K2URyPlJ.d.ts → PowerPointViewer-DtLlYf0r.d.ts}

@@ -264,6 +264,8 @@ interface ViewerTheme {
  * `CollaborationProvider` and wires up presence tracking, remote cursors,
  * and CRDT-based state synchronisation.
  */
+/** Role of a user within a collaboration or broadcast session. */
+type CollaborationRole = 'collaborator' | 'broadcaster' | 'viewer';
 interface CollaborationConfig {
     /** Unique identifier for the collaboration room (alphanumeric, hyphens, underscores). */
     roomId: string;
@@ -277,6 +279,8 @@ interface CollaborationConfig {
     userColor?: string;
     /** Optional authentication token sent with the WebSocket handshake. */
     authToken?: string;
+    /** Role in the session — defaults to `'collaborator'`. */
+    role?: CollaborationRole;
 }
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
@@ -303,6 +307,8 @@ interface UserPresence {
     lastUpdated: string;
     /** Optional currently selected element ID. */
     selectedElementId?: string;
+    /** Role in the session (broadcaster, viewer, or collaborator). */
+    role?: CollaborationRole;
 }
 /** Value exposed by `CollaborationContext`. */
 interface CollaborationContextValue {
@@ -316,6 +322,8 @@ interface CollaborationContextValue {
     connectedCount: number;
     /** The collaboration config that was provided. */
     config: CollaborationConfig;
+    /** The Yjs document (for document sync). */
+    doc: unknown | null;
 }
 
 /**
@@ -405,7 +413,7 @@ interface SlideSectionGroup {
 /** Alignment direction for distributing/aligning multiple selected elements on the slide. */
 type SlideAlignment = 'left' | 'center' | 'right' | 'top' | 'middle' | 'bottom';
 /** Identifies one of the ribbon-style toolbar tabs (home, insert, text, etc.). */
-type ToolbarSection = 'home' | 'insert' | 'text' | 'arrange' | 'draw' | 'design' | 'transitions' | 'review' | 'view';
+type ToolbarSection = 'file' | 'home' | 'insert' | 'text' | 'arrange' | 'draw' | 'design' | 'transitions' | 'animations' | 'slideShow' | 'review' | 'view' | 'help';
 /** The active drawing/inking tool selected in the Draw toolbar tab. */
 type DrawingTool = 'select' | 'pen' | 'highlighter' | 'eraser' | 'freeform';
 /** A single entry in the keyboard shortcuts help panel. */
@@ -459,6 +467,11 @@ interface PowerPointViewerProps {
     canEdit?: boolean;
     /** Optional class name */
     className?: string;
+    /**
+     * Display name used as the author for comments and annotations.
+     * Falls back to `collaboration.userName` when collaborating, or `'You'`.
+     */
+    authorName?: string;
     /**
      * Theme configuration for customising the viewer's appearance.
      *
@@ -501,6 +514,38 @@ interface PowerPointViewerProps {
      * ```
      */
     collaboration?: CollaborationConfig;
+    /**
+     * Callback invoked when the user starts a collaboration session from the
+     * Share dialog. The host app should use this to set the `collaboration`
+     * prop with the returned config.
+     */
+    onStartCollaboration?: (config: CollaborationConfig) => void;
+    /**
+     * Callback invoked when the user stops a collaboration session from the
+     * Share dialog. The host app should clear the `collaboration` prop.
+     */
+    onStopCollaboration?: () => void;
+    /**
+     * Default values for the Share dialog fields. The host app should provide
+     * these to control the session name, user display name, and server URL.
+     * If omitted, the Share dialog fields will be empty and require user input.
+     *
+     * @example
+     * ```tsx
+     * <PowerPointViewer
+     *   shareDefaults={{
+     *     roomId: "session-abc123",
+     *     userName: "Alice",
+     *     serverUrl: "ws://localhost:1234",
+     *   }}
+     * />
+     * ```
+     */
+    shareDefaults?: {
+        roomId?: string;
+        userName?: string;
+        serverUrl?: string;
+    };
 }
 interface PowerPointViewerHandle extends FileViewerHandle {
     getContent: () => Promise<Uint8Array>;
@@ -519,4 +564,4 @@ declare function getAnimationInitialStyle(preset: PptxAnimationPreset | undefine
  */
 declare const PowerPointViewer: React.ForwardRefExoticComponent<PowerPointViewerProps & React.RefAttributes<PowerPointViewerHandle>>;
 
-export { type AccessibilityIssue as A, type SlideSectionGroup as B, type CollaborationConfig as C, type DragState as D, type EditorHistorySnapshot as E, type FileViewerHandle as F, type SlideTransitionOption as G, type StrokeDashOption as H, type SupportedShapeType as I, type ToolbarSection as J, type ViewerMode as K, type MarqueeSelectionState as M, PowerPointViewer as P, type ResizeHandle as R, type ShapeAdjustmentDragState as S, type TableCellEditorState as T, type UserPresence as U, type ViewerThemeColors as V, type ViewerTheme as a, type PowerPointViewerHandle as b, type PowerPointViewerProps as c, type ConnectionStatus as d, type CollaborationContextValue as e, type AnimationPresetOption as f, getAnimationInitialStyle as g, type CanvasSize as h, type ConnectorArrowOption as i, type ConnectorGeometryOption as j, type ConnectorGeometryType as k, type ConnectorPathGeometry as l, type DrawingTool as m, type ElementBounds as n, type ElementClipboardPayload as o, type ElementContextMenuAction as p, type ElementContextMenuState as q, type ParsedTableCell as r, type ParsedTableData as s, type PresentationAnimationRuntime as t, type ResizeState as u, type ShapeAdjustmentHandleDescriptor as v, type ShapePreset as w, type ShapeQuickStyle as x, type ShortcutReferenceItem as y, type SlideAlignment as z };
+export { type AccessibilityIssue as A, type SlideAlignment as B, type CollaborationConfig as C, type DragState as D, type EditorHistorySnapshot as E, type FileViewerHandle as F, type SlideSectionGroup as G, type SlideTransitionOption as H, type StrokeDashOption as I, type SupportedShapeType as J, type ToolbarSection as K, type ViewerMode as L, type MarqueeSelectionState as M, PowerPointViewer as P, type ResizeHandle as R, type ShapeAdjustmentDragState as S, type TableCellEditorState as T, type UserPresence as U, type ViewerThemeColors as V, type ViewerTheme as a, type PowerPointViewerHandle as b, type PowerPointViewerProps as c, type ConnectionStatus as d, type CollaborationContextValue as e, type AnimationPresetOption as f, getAnimationInitialStyle as g, type CanvasSize as h, type CollaborationRole as i, type ConnectorArrowOption as j, type ConnectorGeometryOption as k, type ConnectorGeometryType as l, type ConnectorPathGeometry as m, type DrawingTool as n, type ElementBounds as o, type ElementClipboardPayload as p, type ElementContextMenuAction as q, type ElementContextMenuState as r, type ParsedTableCell as s, type ParsedTableData as t, type PresentationAnimationRuntime as u, type ResizeState as v, type ShapeAdjustmentHandleDescriptor as w, type ShapePreset as x, type ShapeQuickStyle as y, type ShortcutReferenceItem as z };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { V as ViewerThemeColors, a as ViewerTheme } from './PowerPointViewer-K2URyPlJ.mjs';
-export { P as PowerPointViewer, b as PowerPointViewerHandle, c as PowerPointViewerProps, g as getAnimationInitialStyle } from './PowerPointViewer-K2URyPlJ.mjs';
+import { V as ViewerThemeColors, a as ViewerTheme } from './PowerPointViewer-DtLlYf0r.mjs';
+export { P as PowerPointViewer, b as PowerPointViewerHandle, c as PowerPointViewerProps, g as getAnimationInitialStyle } from './PowerPointViewer-DtLlYf0r.mjs';
 import { Options } from 'html2canvas-pro';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import 'pptx-viewer-core';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { V as ViewerThemeColors, a as ViewerTheme } from './PowerPointViewer-K2URyPlJ.js';
-export { P as PowerPointViewer, b as PowerPointViewerHandle, c as PowerPointViewerProps, g as getAnimationInitialStyle } from './PowerPointViewer-K2URyPlJ.js';
+import { V as ViewerThemeColors, a as ViewerTheme } from './PowerPointViewer-DtLlYf0r.js';
+export { P as PowerPointViewer, b as PowerPointViewerHandle, c as PowerPointViewerProps, g as getAnimationInitialStyle } from './PowerPointViewer-DtLlYf0r.js';
 import { Options } from 'html2canvas-pro';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import 'pptx-viewer-core';