pptx-angular-viewer 1.29.0 → 1.30.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.
 
+## [1.30.0](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-angular-viewer@1.30.0) - 2026-07-18
+
+### Features
+
+- **angular:** Promote RibbonComponent for independent composition (by @ChristopherVR) ([00ab33e](https://github.com/ChristopherVR/pptx-viewer/commit/00ab33e515857cd60a5aef01537c1024297e08e5))
+
+## [1.29.0](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-angular-viewer@1.29.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))
+
 ## [1.28.1](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-angular-viewer@1.28.1) - 2026-07-18
 
 ## [1.28.0](https://github.com/ChristopherVR/pptx-viewer/releases/tag/pptx-angular-viewer@1.28.0) - 2026-07-18

package/README.md

@@ -14,8 +14,6 @@ The rendering is done by the framework-agnostic [`pptx-viewer-core`](https://www
 
 <samp>**[▶️ Try the live demo](https://christophervr.github.io/pptx-viewer/demo-angular/)** · **[📦 npm](https://www.npmjs.com/package/pptx-angular-viewer)** · **[📖 Full docs](https://christophervr.github.io/pptx-viewer/)** · **[🧩 Core SDK](https://www.npmjs.com/package/pptx-viewer-core)**</samp>
 
-> **[▶️ Try the live demo](https://christophervr.github.io/pptx-viewer/demo-angular/)**: open a `.pptx` and render it in your browser, no install required.
-
 ## Features
 
 - **Standalone component**: `<pptx-viewer>`, no NgModule needed.
@@ -48,7 +46,18 @@ The rendering is done by the framework-agnostic [`pptx-viewer-core`](https://www
 npm install pptx-angular-viewer
 ```
 
-**Peer requirements:** Angular 22+ (`@angular/core`, `@angular/common`) and `rxjs`.
+**Peer requirements:** Angular 22+ (`@angular/core`, `@angular/common`), `rxjs`,
+and `@ngx-translate/core` (all UI labels go through it, see
+[Localization](#localization-i18n)):
+
+```bash
+npm install @angular/core @angular/common rxjs @ngx-translate/core
+```
+
+**Optional peers:** `three` enables interactive GLB/GLTF 3D models and the
+`smartArt3D` renderer; `yjs` + `y-websocket` (or `y-webrtc` for serverless
+peer-to-peer) enable real-time collaboration. Without them those features
+degrade gracefully (poster images, no live session).
 
 ## Usage
 
@@ -141,30 +150,107 @@ async save() {
 }
 ```
 
+### Composing your own custom viewer host
+
+`<pptx-viewer>` (`PowerPointViewerComponent`) is the bundled, batteries-included
+chrome, but its building blocks are curated exports too, so you can compose
+your own host component instead: bring your own layout/toolbar and reuse the
+ribbon and slide canvas directly, wired to the same shared DI state via
+`POWER_POINT_VIEWER_PROVIDERS`, the exact provider list `PowerPointViewerComponent`
+itself uses.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import {
+	DEFAULT_CANVAS_HEIGHT,
+	DEFAULT_CANVAS_WIDTH,
+	EditorStateService,
+	LoadContentService,
+	POWER_POINT_VIEWER_PROVIDERS,
+	RibbonComponent,
+	SlideCanvasComponent,
+} from 'pptx-angular-viewer';
+
+@Component({
+	selector: 'my-custom-viewer',
+	standalone: true,
+	providers: [...POWER_POINT_VIEWER_PROVIDERS],
+	imports: [RibbonComponent, SlideCanvasComponent],
+	template: `
+		<pptx-ribbon
+			[slideIndex]="loader.activeSlideIndex()"
+			[slideCount]="editor.slides().length"
+			[canEdit]="true"
+			(save)="onSave()"
+		/>
+		<pptx-slide-canvas
+			[slide]="editor.slides()[loader.activeSlideIndex()]"
+			[canvasSize]="{ width: DEFAULT_CANVAS_WIDTH, height: DEFAULT_CANVAS_HEIGHT }"
+			[editable]="true"
+		/>
+	`,
+})
+export class MyCustomViewerComponent {
+	protected readonly loader = inject(LoadContentService);
+	protected readonly editor = inject(EditorStateService);
+	protected readonly DEFAULT_CANVAS_WIDTH = DEFAULT_CANVAS_WIDTH;
+	protected readonly DEFAULT_CANVAS_HEIGHT = DEFAULT_CANVAS_HEIGHT;
+
+	onSave() {
+		/* ... */
+	}
+}
+```
+
+`RibbonComponent` and `SlideCanvasComponent` are plain, DI-free `input()`/`output()`
+signal components (the ribbon renders ~90 bindings for the full Office-style tab
+set; the snippet above shows an illustrative subset, not the exhaustive list),
+so this recipe scales down too: provide only the services the pieces you use
+actually need instead of the full `POWER_POINT_VIEWER_PROVIDERS` list, as long
+as you cover whatever `inject()` calls those pieces make (`EditorStateService`
+and `LoadContentService` are the two nearly everything depends on).
+
 ## API
 
 ### Inputs
 
-| Input           | Type                                | Default | Description                                                                                                            |
-| --------------- | ----------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `content`       | `Uint8Array \| ArrayBuffer \| null` | `null`  | The `.pptx` bytes to render.                                                                                           |
-| `theme`         | `ViewerTheme`                       | n/a     | Color/radius overrides applied as CSS custom properties.                                                               |
-| `class`         | `string`                            | `''`    | Class applied to the root element.                                                                                     |
-| `canEdit`       | `boolean`                           | `false` | Enables the editor toolbar, inspector, and drag-and-drop editing.                                                      |
-| `collaboration` | `CollaborationConfig`               | n/a     | Yjs real-time collaboration config (server URL, room, role).                                                           |
-| `hiddenActions` | `ToolbarActionId[]`                 | `[]`    | Toolbar buttons/ribbon tabs to hide individually (e.g. `['share', 'broadcast']`), instead of hiding the whole toolbar. |
+| Input              | Type                                 | Default | Description                                                                                                            |
+| ------------------ | ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `content`          | `Uint8Array \| ArrayBuffer \| null`  | `null`  | The `.pptx` bytes to render.                                                                                           |
+| `theme`            | `ViewerTheme`                        | n/a     | Color/radius overrides applied as CSS custom properties. Always wins over the File > Options theme picker.             |
+| `class`            | `string`                             | `''`    | Class applied to the root element.                                                                                     |
+| `canEdit`          | `boolean`                            | `false` | Enables the editor toolbar, inspector, and drag-and-drop editing.                                                      |
+| `filePath`         | `string`                             | n/a     | Host file path/identifier keying the version-history store.                                                            |
+| `fileName`         | `string`                             | n/a     | Display name of the open document, shown in the title bar.                                                             |
+| `fonts`            | `ViewerFontSource[]`                 | `[]`    | Licensed font sources supplied by the host application.                                                                |
+| `authorName`       | `string`                             | n/a     | Display name for the local user in collaboration/broadcast sessions and presence avatars.                              |
+| `collaboration`    | `CollaborationConfig`                | n/a     | Yjs real-time collaboration config (server URL, room, role).                                                           |
+| `shareDefaults`    | `{ roomId?, userName?, serverUrl? }` | n/a     | Seed values for the Share dialog's start form.                                                                         |
+| `onOpenFile`       | `() => void`                         | n/a     | Host override for File > Open; bypasses the built-in file picker.                                                      |
+| `smartArt3D`       | `boolean`                            | `false` | Opt-in Three.js 3D SmartArt renderer (needs the optional `three` peer; falls back to SVG without it).                  |
+| `hiddenActions`    | `ToolbarActionId[]`                  | `[]`    | Toolbar buttons/ribbon tabs to hide individually (e.g. `['share', 'broadcast']`), instead of hiding the whole toolbar. |
+| `defaultThemeKey`  | `string`                             | n/a     | Initial File > Options > Appearance selection when no persisted preference exists.                                     |
+| `availableThemes`  | `ThemeCatalogEntry[]`                | n/a     | Theme choices offered by File > Options > Appearance (defaults to the built-in catalog).                               |
+| `onThemeChange`    | `(key: string) => void`              | n/a     | Host hook for the appearance picker; when set, the host owns persisting the choice.                                    |
+| `defaultLocale`    | `string`                             | n/a     | Initial locale code when no persisted preference exists.                                                               |
+| `availableLocales` | `LocaleCatalogEntry[]`               | n/a     | Locale choices offered by File > Options > Language (defaults to the registered `TranslateService` languages).         |
+| `onLocaleChange`   | `(code: string) => void`             | n/a     | Host hook for the language picker; when set, the host owns applying/persisting the switch.                             |
+| `accountAuth`      | `AccountAuthConfig`                  | n/a     | Optional sign-in hook point for File > Account (disabled unless `enabled: true`).                                      |
 
 ### Outputs
 
-| Output              | Payload      | Description                                                          |
-| ------------------- | ------------ | -------------------------------------------------------------------- |
-| `activeSlideChange` | `number`     | Emits the active slide index on navigation.                          |
-| `dirtyChange`       | `boolean`    | Emits `true`/`false` when the dirty state changes.                   |
-| `contentChange`     | `Uint8Array` | Emits updated bytes after any editing change.                        |
-| `modeChange`        | `string`     | Emits the new mode (`'preview'`, `'edit'`, `'present'`, `'master'`). |
-| `zoomChange`        | `number`     | Emits the new zoom level (1 = 100%).                                 |
-| `selectionChange`   | `string[]`   | Emits the selected element IDs when selection changes.               |
-| `slideCountChange`  | `number`     | Emits the total slide count when slides change.                      |
+| Output               | Payload                       | Description                                                          |
+| -------------------- | ----------------------------- | -------------------------------------------------------------------- |
+| `activeSlideChange`  | `number`                      | Emits the active slide index on navigation.                          |
+| `dirtyChange`        | `boolean`                     | Emits `true`/`false` when the dirty state changes.                   |
+| `contentChange`      | `Uint8Array`                  | Emits updated bytes after any editing change.                        |
+| `modeChange`         | `string`                      | Emits the new mode (`'preview'`, `'edit'`, `'present'`, `'master'`). |
+| `zoomChange`         | `number`                      | Emits the new zoom level (1 = 100%).                                 |
+| `selectionChange`    | `string[]`                    | Emits the selected element IDs when selection changes.               |
+| `slideCountChange`   | `number`                      | Emits the total slide count when slides change.                      |
+| `propertiesChange`   | `Partial<PptxCoreProperties>` | Emits when the user edits document properties in the Info dialog.    |
+| `startCollaboration` | `CollaborationConfig`         | Emits when a collaboration/broadcast session starts.                 |
+| `stopCollaboration`  | `void`                        | Emits when the collaboration/broadcast session stops.                |
 
 ### Methods
 
@@ -192,11 +278,23 @@ async save() {
 | `selectElements(ids)`     | `void`                | Programmatically select elements by ID.        |
 | `clearSelection()`        | `void`                | Clear the current selection.                   |
 
+The component implements the full shared `PowerPointViewerAPI`, so the
+following slide/element manipulation methods are also available:
+`setActiveSlideIndex(index)`, `getSlides()`, `getSlide(index)`,
+`getActiveSlide()`, `addSlide(afterIndex?)`, `deleteSlides(indexes)`,
+`duplicateSlides(indexes)`, `moveSlide(from, to)`, `toggleHideSlides(indexes)`,
+`getElements(slideIndex?)`, `getElementById(id, slideIndex?)`,
+`updateElement(id, patch)`, `deleteElements(ids)`, and
+`duplicateElement(id)`.
+
 ### Exported components & helpers
 
-`PowerPointViewerComponent`, `SlideCanvasComponent`, `ElementRendererComponent`,
-`LoadContentService`, `provideViewerTheme`, `VIEWER_THEME`, and the
-`ViewerTheme` / `CanvasSize` / `CollaborationConfig` types.
+`PowerPointViewerComponent`, `SlideCanvasComponent`, `RibbonComponent`,
+`ElementRendererComponent`, `LoadContentService`, `POWER_POINT_VIEWER_PROVIDERS`,
+`provideViewerTheme`, `VIEWER_THEME`, and the `ViewerTheme` / `CanvasSize` /
+`CollaborationConfig` types. See "Composing your own custom viewer host" above
+for using `RibbonComponent` and `SlideCanvasComponent` outside
+`PowerPointViewerComponent`.
 
 ## Localization (i18n)