pptx-vanilla-viewer 0.4.0 → 0.5.1

package/dist/index.d.cts

@@ -1520,6 +1520,56 @@ type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';
 
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** A single remote collaborator's cursor, in unscaled slide coordinates. */
+interface RemoteCursor {
+    /** Stable id for the remote client (awareness clientId or peer id). */
+    clientId: number | string;
+    /** Display name shown in the label chip. */
+    userName: string;
+    /** Cursor + chip colour (any CSS colour string). */
+    color: string;
+    /** Unscaled slide-space X coordinate (px). */
+    x: number;
+    /** Unscaled slide-space Y coordinate (px). */
+    y: number;
+    /** Optional ids of elements this user has selected. */
+    selectionIds?: string[];
+}
+/**
+ * Presence data for a remote collaborator, sanitised from the awareness
+ * protocol. Returned by {@link sanitizePresence}; coordinates are in unscaled
+ * slide pixels, clamped to the supplied canvas bounds.
+ */
+interface SanitizedPresence {
+    clientId: number;
+    userName: string;
+    userAvatar?: string;
+    userColor: string;
+    activeSlideIndex: number;
+    cursorX: number;
+    cursorY: number;
+    lastUpdated: string;
+    selectedElementId?: string;
+    role?: CollaborationRole;
+}
+
+/**
+ * Pure, framework-agnostic helpers for freehand ink drawing, shared by every
+ * binding. No framework imports, so these can be unit-tested without TestBed.
+ */
+
+/** A 2D point in stage-local coordinates. */
+interface InkPoint {
+    x: number;
+    y: number;
+}
+/** Options for {@link strokeToInkElement}. */
+interface StrokeToInkElementOpts {
+    points: InkPoint[];
+    color: string;
+    width: number;
+    tool: 'pen' | 'highlighter' | 'freeform';
+}
 
 /**
  * Pure helpers for the gradient picker editor control, shared by every binding.
@@ -1640,6 +1690,13 @@ interface Store<T extends object> {
 
 /** `zoom` is either an explicit scale factor (1 = 100%) or fit-to-viewport. */
 type ZoomLevel = number | 'fit';
+/**
+ * The Draw ribbon tab's active tool. `'select'` means normal editing gestures
+ * (move/resize/rotate/inline-edit) apply on the stage; every other value
+ * routes stage pointer events to the ink-drawing gesture controller instead
+ * (see `editor-draw-gestures.ts`).
+ */
+type DrawTool = 'select' | 'pen' | 'highlighter' | 'eraser';
 /**
  * The vanilla viewer's reactive view state. Kept intentionally flat and small;
  * everything here is what the DOM render layer consumes.
@@ -1677,8 +1734,20 @@ interface ViewerState {
      * navigation for the life of the viewer instance (in-memory only).
      */
     notesExpanded: boolean;
+    /** Remote collaborators currently in the session (empty when not collaborating). */
+    remotePresences: SanitizedPresence[];
+    /** Remote cursors visible on the current slide, projected from `remotePresences`. */
+    cursors: RemoteCursor[];
+    /** Client id of the peer the local user is following, or null when free. */
+    followedClientId: number | null;
     /** In-memory clipboard payload from the last copy/cut, or null. */
     clipboardPayload: ElementClipboardPayload | null;
+    /** Active Draw ribbon tool; `'select'` disables the ink-drawing gesture controller. */
+    drawTool: DrawTool;
+    /** Stroke colour for the pen/highlighter tools. */
+    drawColor: string;
+    /** Stroke width (px) for the pen/highlighter tools. */
+    drawWidth: number;
 }
 
 /**
@@ -1754,6 +1823,32 @@ interface ClipboardActions {
     paste(): void;
 }
 
+/**
+ * Ink stroke actions for the Draw ribbon tab: commit a freehand pen/
+ * highlighter stroke as a new `InkPptxElement`, or erase an existing one.
+ * Both mutations are history-integrated (push -> mutate -> commit), mirroring
+ * `editor-background-actions.ts` and the `insertElement` helper in
+ * `editor-edit-ops.ts`. The pointer-event lifecycle that accumulates a
+ * stroke's points lives separately in `editor-draw-gestures.ts`; this module
+ * only owns the resulting slide/history mutation.
+ */
+interface InkActions {
+    /**
+     * Build an `InkPptxElement` from a completed stroke (via the shared
+     * `strokeToInkElement`) and append it to the current slide, selected.
+     * A no-op when not editable, there is no current slide, or the stroke has
+     * fewer than 2 points (shared helper returns `null`, matching a plain tap).
+     */
+    commitStroke(stroke: StrokeToInkElementOpts): void;
+    /**
+     * Remove the ink element with `id` from the current slide (Draw tab's
+     * eraser tool). Returns `true` when an ink element was found and removed;
+     * `false` for a missing id, a non-ink element, or a read-only viewer (safe
+     * to call from a generic stage hit-test without a pre-check).
+     */
+    eraseInkElement(id: string): boolean;
+}
+
 /**
  * Insert-element factories for the vanilla editor.
  *
@@ -1873,7 +1968,7 @@ interface GeometryPatch {
  * directly here. Every mutating action is history-integrated (push -> mutate
  * -> commit) via the shared {@link EditorOps}.
  */
-interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions, SlideBackgroundActions, TransitionActions, AnimationActions, InspectorActions {
+interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions, SlideBackgroundActions, TransitionActions, AnimationActions, InspectorActions, InkActions {
     setShapeFill(color: string): void;
     setShapeStroke(color: string): void;
     setShapeStrokeWidth(width: number): void;
@@ -1988,6 +2083,12 @@ interface NotesPanel {
     setExpanded(expanded: boolean): void;
 }
 
+/** Draw tab state to reflect (current tool/colour/width). */
+interface RibbonDrawState {
+    tool: DrawTool;
+    color: string;
+    width: number;
+}
 /** Nav-row state (prev/next/counter/zoom label). */
 interface RibbonNavState {
     current: number;
@@ -2016,6 +2117,8 @@ interface Ribbon {
     setEditable(editable: boolean): void;
     /** Reflect the current selection across the Home tab's Font/Paragraph/Arrange groups. */
     updateSelection(selectedElement: a | undefined, extra: RibbonSelectionState): void;
+    /** Reflect the current Draw tab tool/colour/width (store-driven). */
+    setDrawState(state: RibbonDrawState): void;
 }
 
 interface ThumbnailRail {
@@ -2078,6 +2181,12 @@ interface EditorController {
     deleteSelected(): void;
     duplicateSelected(): string | null;
     getSelectedElementId(): string | null;
+    /** Switch the Draw ribbon tab's active tool (also clears selection when leaving `'select'`). */
+    setDrawTool(tool: DrawTool): void;
+    /** Set the pen/highlighter stroke colour used by the next committed stroke. */
+    setDrawColor(color: string): void;
+    /** Set the pen/highlighter stroke width used by the next committed stroke. */
+    setDrawWidth(width: number): void;
     /** The formatting / insert / arrange actions for the editing chrome. */
     getEditActions(): EditActions;
     /** The Find & Replace actions for the ribbon's docked panel. */
@@ -2315,6 +2424,21 @@ interface RenderController {
  */
 type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'error';
 
+/**
+ * share-helpers.ts: pure (framework-free) helpers for the Share dialog.
+ *
+ * Mirrors the Vue `ShareDialog.vue` / Angular `share-helpers.ts` form
+ * validation and config-assembly logic (see `useCollaborationWiring.onShareStart`
+ * for the `role: 'collaborator'` config this produces). No DOM here so it is
+ * trivially unit-testable; the DOM builder lives in `ui/share-dialog.ts`.
+ */
+/** Prefilled values for the Share form fields. */
+interface ShareDefaults {
+    roomId?: string;
+    userName?: string;
+    serverUrl?: string;
+}
+
 /** Per-slide progress callback: `(currentSlideIndex, totalSlides)`. */
 type ExportProgress = (current: number, total: number) => void;
 
@@ -2540,6 +2664,13 @@ interface PptxViewerOptions extends PptxViewerCallbacks {
      * slide array, so a joiner's host-provided media can degrade.
      */
     collaboration?: CollaborationConfig;
+    /**
+     * Prefilled values for the built-in Share/Broadcast dialogs' form fields
+     * (e.g. a host-generated display name), mirroring the Vue binding's
+     * `shareDefaults` prop. The broadcast dialog uses `userName` as the
+     * presenter's display name.
+     */
+    shareDefaults?: ShareDefaults;
 }
 /** The viewer handle returned by `createPptxViewer`. */
 interface PptxViewerInstance {
@@ -2664,6 +2795,9 @@ interface ChromeHost {
         commitNotes(notes: string): void;
         getEditActions(): EditActions;
         getFindReplaceActions(): FindReplaceActions;
+        setDrawTool(tool: DrawTool): void;
+        setDrawColor(color: string): void;
+        setDrawWidth(width: number): void;
     };
     prev(): void;
     next(): void;

package/dist/index.d.ts

@@ -1520,6 +1520,56 @@ type ChangeCaseMode = 'sentence' | 'lower' | 'upper' | 'capitalize' | 'toggle';
 
 /** Connection lifecycle states for the Yjs WebSocket provider. */
 type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/** A single remote collaborator's cursor, in unscaled slide coordinates. */
+interface RemoteCursor {
+    /** Stable id for the remote client (awareness clientId or peer id). */
+    clientId: number | string;
+    /** Display name shown in the label chip. */
+    userName: string;
+    /** Cursor + chip colour (any CSS colour string). */
+    color: string;
+    /** Unscaled slide-space X coordinate (px). */
+    x: number;
+    /** Unscaled slide-space Y coordinate (px). */
+    y: number;
+    /** Optional ids of elements this user has selected. */
+    selectionIds?: string[];
+}
+/**
+ * Presence data for a remote collaborator, sanitised from the awareness
+ * protocol. Returned by {@link sanitizePresence}; coordinates are in unscaled
+ * slide pixels, clamped to the supplied canvas bounds.
+ */
+interface SanitizedPresence {
+    clientId: number;
+    userName: string;
+    userAvatar?: string;
+    userColor: string;
+    activeSlideIndex: number;
+    cursorX: number;
+    cursorY: number;
+    lastUpdated: string;
+    selectedElementId?: string;
+    role?: CollaborationRole;
+}
+
+/**
+ * Pure, framework-agnostic helpers for freehand ink drawing, shared by every
+ * binding. No framework imports, so these can be unit-tested without TestBed.
+ */
+
+/** A 2D point in stage-local coordinates. */
+interface InkPoint {
+    x: number;
+    y: number;
+}
+/** Options for {@link strokeToInkElement}. */
+interface StrokeToInkElementOpts {
+    points: InkPoint[];
+    color: string;
+    width: number;
+    tool: 'pen' | 'highlighter' | 'freeform';
+}
 
 /**
  * Pure helpers for the gradient picker editor control, shared by every binding.
@@ -1640,6 +1690,13 @@ interface Store<T extends object> {
 
 /** `zoom` is either an explicit scale factor (1 = 100%) or fit-to-viewport. */
 type ZoomLevel = number | 'fit';
+/**
+ * The Draw ribbon tab's active tool. `'select'` means normal editing gestures
+ * (move/resize/rotate/inline-edit) apply on the stage; every other value
+ * routes stage pointer events to the ink-drawing gesture controller instead
+ * (see `editor-draw-gestures.ts`).
+ */
+type DrawTool = 'select' | 'pen' | 'highlighter' | 'eraser';
 /**
  * The vanilla viewer's reactive view state. Kept intentionally flat and small;
  * everything here is what the DOM render layer consumes.
@@ -1677,8 +1734,20 @@ interface ViewerState {
      * navigation for the life of the viewer instance (in-memory only).
      */
     notesExpanded: boolean;
+    /** Remote collaborators currently in the session (empty when not collaborating). */
+    remotePresences: SanitizedPresence[];
+    /** Remote cursors visible on the current slide, projected from `remotePresences`. */
+    cursors: RemoteCursor[];
+    /** Client id of the peer the local user is following, or null when free. */
+    followedClientId: number | null;
     /** In-memory clipboard payload from the last copy/cut, or null. */
     clipboardPayload: ElementClipboardPayload | null;
+    /** Active Draw ribbon tool; `'select'` disables the ink-drawing gesture controller. */
+    drawTool: DrawTool;
+    /** Stroke colour for the pen/highlighter tools. */
+    drawColor: string;
+    /** Stroke width (px) for the pen/highlighter tools. */
+    drawWidth: number;
 }
 
 /**
@@ -1754,6 +1823,32 @@ interface ClipboardActions {
     paste(): void;
 }
 
+/**
+ * Ink stroke actions for the Draw ribbon tab: commit a freehand pen/
+ * highlighter stroke as a new `InkPptxElement`, or erase an existing one.
+ * Both mutations are history-integrated (push -> mutate -> commit), mirroring
+ * `editor-background-actions.ts` and the `insertElement` helper in
+ * `editor-edit-ops.ts`. The pointer-event lifecycle that accumulates a
+ * stroke's points lives separately in `editor-draw-gestures.ts`; this module
+ * only owns the resulting slide/history mutation.
+ */
+interface InkActions {
+    /**
+     * Build an `InkPptxElement` from a completed stroke (via the shared
+     * `strokeToInkElement`) and append it to the current slide, selected.
+     * A no-op when not editable, there is no current slide, or the stroke has
+     * fewer than 2 points (shared helper returns `null`, matching a plain tap).
+     */
+    commitStroke(stroke: StrokeToInkElementOpts): void;
+    /**
+     * Remove the ink element with `id` from the current slide (Draw tab's
+     * eraser tool). Returns `true` when an ink element was found and removed;
+     * `false` for a missing id, a non-ink element, or a read-only viewer (safe
+     * to call from a generic stage hit-test without a pre-check).
+     */
+    eraseInkElement(id: string): boolean;
+}
+
 /**
  * Insert-element factories for the vanilla editor.
  *
@@ -1873,7 +1968,7 @@ interface GeometryPatch {
  * directly here. Every mutating action is history-integrated (push -> mutate
  * -> commit) via the shared {@link EditorOps}.
  */
-interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions, SlideBackgroundActions, TransitionActions, AnimationActions, InspectorActions {
+interface EditActions extends TextActions, ArrangeActions, ClipboardActions, SlideActions, SlideBackgroundActions, TransitionActions, AnimationActions, InspectorActions, InkActions {
     setShapeFill(color: string): void;
     setShapeStroke(color: string): void;
     setShapeStrokeWidth(width: number): void;
@@ -1988,6 +2083,12 @@ interface NotesPanel {
     setExpanded(expanded: boolean): void;
 }
 
+/** Draw tab state to reflect (current tool/colour/width). */
+interface RibbonDrawState {
+    tool: DrawTool;
+    color: string;
+    width: number;
+}
 /** Nav-row state (prev/next/counter/zoom label). */
 interface RibbonNavState {
     current: number;
@@ -2016,6 +2117,8 @@ interface Ribbon {
     setEditable(editable: boolean): void;
     /** Reflect the current selection across the Home tab's Font/Paragraph/Arrange groups. */
     updateSelection(selectedElement: a | undefined, extra: RibbonSelectionState): void;
+    /** Reflect the current Draw tab tool/colour/width (store-driven). */
+    setDrawState(state: RibbonDrawState): void;
 }
 
 interface ThumbnailRail {
@@ -2078,6 +2181,12 @@ interface EditorController {
     deleteSelected(): void;
     duplicateSelected(): string | null;
     getSelectedElementId(): string | null;
+    /** Switch the Draw ribbon tab's active tool (also clears selection when leaving `'select'`). */
+    setDrawTool(tool: DrawTool): void;
+    /** Set the pen/highlighter stroke colour used by the next committed stroke. */
+    setDrawColor(color: string): void;
+    /** Set the pen/highlighter stroke width used by the next committed stroke. */
+    setDrawWidth(width: number): void;
     /** The formatting / insert / arrange actions for the editing chrome. */
     getEditActions(): EditActions;
     /** The Find & Replace actions for the ribbon's docked panel. */
@@ -2315,6 +2424,21 @@ interface RenderController {
  */
 type AutosaveStatus = 'idle' | 'saving' | 'saved' | 'error';
 
+/**
+ * share-helpers.ts: pure (framework-free) helpers for the Share dialog.
+ *
+ * Mirrors the Vue `ShareDialog.vue` / Angular `share-helpers.ts` form
+ * validation and config-assembly logic (see `useCollaborationWiring.onShareStart`
+ * for the `role: 'collaborator'` config this produces). No DOM here so it is
+ * trivially unit-testable; the DOM builder lives in `ui/share-dialog.ts`.
+ */
+/** Prefilled values for the Share form fields. */
+interface ShareDefaults {
+    roomId?: string;
+    userName?: string;
+    serverUrl?: string;
+}
+
 /** Per-slide progress callback: `(currentSlideIndex, totalSlides)`. */
 type ExportProgress = (current: number, total: number) => void;
 
@@ -2540,6 +2664,13 @@ interface PptxViewerOptions extends PptxViewerCallbacks {
      * slide array, so a joiner's host-provided media can degrade.
      */
     collaboration?: CollaborationConfig;
+    /**
+     * Prefilled values for the built-in Share/Broadcast dialogs' form fields
+     * (e.g. a host-generated display name), mirroring the Vue binding's
+     * `shareDefaults` prop. The broadcast dialog uses `userName` as the
+     * presenter's display name.
+     */
+    shareDefaults?: ShareDefaults;
 }
 /** The viewer handle returned by `createPptxViewer`. */
 interface PptxViewerInstance {
@@ -2664,6 +2795,9 @@ interface ChromeHost {
         commitNotes(notes: string): void;
         getEditActions(): EditActions;
         getFindReplaceActions(): FindReplaceActions;
+        setDrawTool(tool: DrawTool): void;
+        setDrawColor(color: string): void;
+        setDrawWidth(width: number): void;
     };
     prev(): void;
     next(): void;