pptx-react-viewer 1.0.10 → 1.0.11

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-gSKLhZDo.d.mts}

@@ -316,6 +316,8 @@ interface CollaborationContextValue {
     connectedCount: number;
     /** The collaboration config that was provided. */
     config: CollaborationConfig;
+    /** The Yjs document (for document sync). */
+    doc: unknown | null;
 }
 
 /**
@@ -405,7 +407,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. */
@@ -501,6 +503,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>;

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

@@ -316,6 +316,8 @@ interface CollaborationContextValue {
     connectedCount: number;
     /** The collaboration config that was provided. */
     config: CollaborationConfig;
+    /** The Yjs document (for document sync). */
+    doc: unknown | null;
 }
 
 /**
@@ -405,7 +407,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. */
@@ -501,6 +503,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>;

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-gSKLhZDo.mjs';
+export { P as PowerPointViewer, b as PowerPointViewerHandle, c as PowerPointViewerProps, g as getAnimationInitialStyle } from './PowerPointViewer-gSKLhZDo.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-gSKLhZDo.js';
+export { P as PowerPointViewer, b as PowerPointViewerHandle, c as PowerPointViewerProps, g as getAnimationInitialStyle } from './PowerPointViewer-gSKLhZDo.js';
 import { Options } from 'html2canvas-pro';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import 'pptx-viewer-core';