pptx-vanilla-viewer 0.15.0 → 0.16.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project are documented here.
 This file is generated from [Conventional Commits](https://www.conventionalcommits.org)
 by [git-cliff](https://git-cliff.org); do not edit it by hand.
 
+## [0.16.0](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-vanilla-viewer@0.16.0) - 2026-07-18
+
+### Features
+
+- **vanilla:** Export createRibbon for independent composition (by @ChristopherVR) ([521d494](https://github.com/ChristopherVR/pptx-viewer/commit/521d4943e2d457d87e5305c15090928212c58a3c))
+
+## [0.15.0](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-vanilla-viewer@0.15.0) - 2026-07-18
+
+### Dependencies
+
+- **deps:** Update dependencies to latest and migrate core/shared/locales to TypeScript 7 (by @ChristopherVR) ([cc72948](https://github.com/ChristopherVR/pptx-viewer/commit/cc729482cc5ae4ae56e1219f290c2953ec83c12a))
+
 ## [0.14.0](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-vanilla-viewer@0.14.0) - 2026-07-18
 
 ### Bug Fixes

package/README.md

@@ -71,6 +71,73 @@ viewer.destroy();
 
 The container should have a size (the viewer fills it: `width/height: 100%`).
 
+## Options
+
+All options are optional except the container element itself. Beyond the ones
+shown above:
+
+| Option                                 | Type                                                  | Default               | Description                                                                                 |
+| -------------------------------------- | ----------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------- |
+| `source`                               | `string \| ArrayBuffer \| Uint8Array \| Blob \| File` | -                     | The presentation to open (URL or bytes). Omit to start empty and call `loadFile`/`loadUrl`. |
+| `fonts`                                | `ViewerFontSource[]`                                  | -                     | Licensed font sources supplied by the host application.                                     |
+| `theme`                                | `ViewerTheme`                                         | -                     | Chrome theme (colors, radius, CSS vars).                                                    |
+| `fileName`                             | `string`                                              | -                     | Display name shown in the title bar.                                                        |
+| `locale` / `messages`                  | `string` / `TranslationMessages`                      | `'en'`                | UI locale and per-locale `pptx.*` dictionaries (see [i18n](#i18n)).                         |
+| `initialSlide`                         | `number`                                              | `0`                   | Zero-based slide shown after load.                                                          |
+| `editable`                             | `boolean`                                             | `false`               | Enable editing (see [Editing](#editing)).                                                   |
+| `showToolbar`                          | `boolean`                                             | `true`                | Whole ribbon/title-bar/status-bar chrome.                                                   |
+| `showThumbnails`                       | `boolean`                                             | `true`                | Thumbnail sidebar.                                                                          |
+| `showFormatToolbar`                    | `boolean`                                             | `true`                | Editing format toolbar row (visible only while editing).                                    |
+| `showInspector`                        | `boolean`                                             | `true`                | Property inspector panel (visible only while editing).                                      |
+| `hiddenActions`                        | `ToolbarActionId[]`                                   | -                     | Hide individual buttons/tabs (see [Toolbar customization](#toolbar-customization)).         |
+| `registry`                             | `ElementRendererRegistry`                             | -                     | Custom element-renderer registry (see [Element coverage](#element-coverage)).               |
+| `smartArt3D`                           | `boolean`                                             | `false`               | Opt-in Three.js 3D SmartArt renderer (optional `three` peer, lazily imported).              |
+| `autosave`                             | `boolean`                                             | `false`               | Debounced crash-recovery autosave to IndexedDB.                                             |
+| `autosaveIntervalMs`                   | `number`                                              | `2000`                | Autosave debounce window.                                                                   |
+| `autosaveFilePath`                     | `string`                                              | `'presentation.pptx'` | IndexedDB recovery key for autosave snapshots.                                              |
+| `collaboration`                        | `CollaborationConfig`                                 | -                     | Start a Yjs collaboration session immediately (y-websocket or serverless y-webrtc).         |
+| `shareDefaults`                        | `{ roomId?, userName?, serverUrl? }`                  | -                     | Prefilled values for the Share/Broadcast dialogs.                                           |
+| `availableThemes` / `availableLocales` | catalog entries                                       | -                     | Choices offered by File > Options.                                                          |
+| `onThemeChange` / `onLocaleChange`     | `(key: string) => void`                               | -                     | Host hooks for the File > Options pickers (host owns persistence when supplied).            |
+| `accountAuth`                          | `AccountAuthConfig`                                   | -                     | Optional sign-in hook point for File > Account.                                             |
+
+Callbacks: `onLoad`, `onError`, `onSlideChange`, `onZoomChange`,
+`onPresentationChange`, `onChange` (any document mutation), `onDirtyChange`,
+`onSelectionChange`, `onAutosaveStatus`, `onAutosaveRecovery` (offers a prior
+session's recovery snapshot), `onToggleAutosave`, and `onCollaborationStatus`.
+
+## Instance API
+
+The handle returned by `createPptxViewer` implements the shared
+`PowerPointViewerAPI` (the same imperative contract as the React/Vue/Angular/
+Svelte bindings: `getContent`, `goTo`, `undo`/`redo`, zoom and mode getters/
+setters, `getSlides`/`getSlide`/`getActiveSlide`, `addSlide`/`deleteSlides`/
+`duplicateSlides`/`moveSlide`/`toggleHideSlides`, `getElements`/
+`getElementById`/`updateElement`/`deleteElements`/`duplicateElement`, and the
+selection methods) plus vanilla-specific methods:
+
+- **Loading**: `loadFile(bytesOrBlob)`, `loadUrl(url)`.
+- **Navigation / zoom**: `next()`, `prev()`, `goToSlide(index)`,
+  `getSlideCount()`, `getCurrentSlide()`, `getZoom()`, `setZoom(scale)`,
+  `zoomIn()`, `zoomOut()`, `zoomToFit()`.
+- **Presentation**: `enterPresentation()`, `exitPresentation()`.
+- **Editing**: `setEditable(flag)`, `setEditTemplateMode(flag)`, `undo()`,
+  `redo()`, `canUndo()`, `canRedo()`, `deleteSelected()`,
+  `getSelectedElementId()`.
+- **Saving**: `save(format?)`, `downloadPptx(fileName?)`,
+  `downloadAs(format, fileName?)`, `packageForSharing(fileName?)`.
+- **Export / print**: `exportSlidePng(index?)`, `copySlideAsImage(index?)`,
+  `exportPdf(options?)`, `exportGif(options?)`, `exportVideo(options?)`,
+  `print(options?)` (returns `false` when the popup was blocked; call from a
+  click handler).
+- **Collaboration**: `startCollaboration(config)`, `stopCollaboration()`,
+  `getCollaborationStatus()`.
+- **Autosave**: `autosaveNow()`, `setAutosaveEnabled(flag)`,
+  `isAutosaveEnabled()`.
+- **Chrome / extension**: `setTheme(theme?)`, `setLocale(locale)`,
+  `getRegistry()`, `getHandler()` (the live `pptx-viewer-core` handler),
+  `destroy()`.
+
 ## Keyboard
 
 Navigation: arrow keys / PageUp / PageDown / Space, Home/End jump to the
@@ -137,9 +204,6 @@ Pass `editable: true` (or call `setEditable(true)` at runtime) to turn on:
 - The toolbar's Save button (shown only when `editable`), which calls
   `downloadPptx()` to serialise and download the edited `.pptx`.
 
-For CSP-strict hosts, import `pptx-vanilla-viewer/styles.css` instead of using
-automatic style injection.
-
 Use `viewer.getSelectedElementId()` and the `onSelectionChange` /
 `onDirtyChange` callbacks to build your own chrome around the selection
 state.
@@ -172,6 +236,76 @@ viewer.getRegistry().register('table', renderTable);
 
 See `src/viewer/render/elements/README.md` for the full renderer contract.
 
+## Building your own chrome
+
+`createPptxViewer` mounts the whole viewer (ribbon, canvas, inspector,
+controllers) as one unit. If you want to build custom chrome around the same
+primitives instead, the ribbon builder and the canvas renderer are both
+importable independently:
+
+```ts
+import {
+	createRibbon,
+	createStore,
+	createInitialViewerState,
+	renderSlideStage,
+	createDefaultRegistry,
+	type RibbonHandlers,
+	type Store,
+	type ViewerState,
+} from 'pptx-vanilla-viewer';
+
+// Your own reactive container, seeded with the same shape `createPptxViewer`
+// uses internally.
+const store: Store<ViewerState> = createStore(createInitialViewerState());
+
+// `createRibbon` is callback-driven: it never reaches into a `PptxViewer`
+// instance or a store directly, so it renders against whatever `RibbonHandlers`
+// you hand it.
+const handlers: RibbonHandlers = {
+	/* nav, primary, file, slideShow, insert, edit, findReplace, design, draw */
+};
+const ribbon = createRibbon(document, t, handlers);
+host.appendChild(ribbon.el);
+
+// Draw the current slide with the same DOM renderer the bundled viewer uses.
+const registry = createDefaultRegistry();
+const stageEl = renderSlideStage({
+	doc: document,
+	slide: store.get().slides[store.get().currentSlide],
+	registry,
+	// ...canvasSize, scale, editable, selection, etc. (see `SlideStageOptions`)
+});
+canvasHost.appendChild(stageEl);
+
+// Re-render on every store change.
+store.subscribe((state) => {
+	ribbon.update({ current: state.currentSlide, total: state.slides.length, zoomPercent: 100 });
+	/* re-render the stage, drive ribbon.setEditState/updateSelection/etc. */
+});
+```
+
+Be aware of what this buys you and what it doesn't:
+
+- `renderSlideStage`, `createElementRendererRegistry` / `createDefaultRegistry`,
+  and `createRibbon` are pure, callback-driven building blocks with no hidden
+  coupling to `PptxViewer`; they are safe to use standalone.
+- `createStore` / `createInitialViewerState` give you the same reactive
+  container and `ViewerState` shape `createPptxViewer` uses, so you can seed
+  state and pass slices of it into `renderSlideStage`.
+- `RibbonHandlers` (the `edit` and `findReplace` groups especially, typed by
+  the exported `EditActions` / `FindReplaceActions` interfaces) is a large
+  surface: insert/format/arrange/clipboard/history/animation/transition
+  actions, comments, sections, and more. The built-in implementations of
+  these (`createEditorController`, `createEditActions`, `RenderController`,
+  `LoadingController`, ...) are **not** exported: they're wired directly
+  into `PptxViewer`'s own mount lifecycle (`getChrome`, `getHandler`, history,
+  autosave) and aren't decomposable into standalone pieces without a larger
+  refactor. Building a fully-featured custom editor chrome today means
+  implementing `RibbonHandlers` yourself against your own store and history,
+  not reusing the bundled editor logic; `createPptxViewer` remains the
+  supported path for a complete, batteries-included editor.
+
 ## License
 
 Apache-2.0. See `LICENSE` and `NOTICE`.