@textcortex/slidewise 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@textcortex/slidewise",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Embeddable React PPTX editor.",
   "license": "MIT",
   "type": "module",

package/src/SlidewiseEditor.tsx

@@ -4,9 +4,10 @@ import {
   type SlidewiseRootHandle,
   type SlidewiseRootProps,
   type HistoryState,
+  type SelectionSnapshot,
 } from "./compound/SlidewiseRoot";
+import { TopBar } from "./compound/topbar";
 import {
-  TopBar,
   SlideRail,
   Canvas,
   BottomToolbar,
@@ -40,6 +41,18 @@ export interface SlidewiseEditorProps {
    * Undo and Redo buttons reactively without polling `api.canUndo()`.
    */
   onHistoryChange?: (state: HistoryState) => void;
+  /** Fires when the active slide changes (user click, programmatic goToSlide). */
+  onActiveSlideChange?: (slideId: string) => void;
+  /** Fires when the selected element ids change. */
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  /** Fires when the canvas zoom level changes. */
+  onZoomChange?: (scale: number) => void;
+  /** Fires immediately before the host's `onSave` is invoked. */
+  onSaveStart?: () => void;
+  /** Fires after the host's `onSave` resolves successfully. */
+  onSaveSuccess?: () => void;
+  /** Fires when the host's `onSave` throws. The error still propagates. */
+  onSaveError?: (err: Error) => void;
   /** Reserved for future use; not enforced yet. */
   readOnly?: boolean;
   /** "light" or "dark"; defaults to "light". Ignored after first render. */
@@ -97,6 +110,12 @@ export const SlidewiseEditor = forwardRef<
     onExport,
     onDirtyChange,
     onHistoryChange,
+    onActiveSlideChange,
+    onSelectionChange,
+    onZoomChange,
+    onSaveStart,
+    onSaveSuccess,
+    onSaveError,
     readOnly,
     theme,
     initialSlideId,
@@ -116,6 +135,12 @@ export const SlidewiseEditor = forwardRef<
     onExport,
     onDirtyChange,
     onHistoryChange,
+    onActiveSlideChange,
+    onSelectionChange,
+    onZoomChange,
+    onSaveStart,
+    onSaveSuccess,
+    onSaveError,
     readOnly,
     theme,
     initialSlideId,

package/src/SlidewiseFileEditor.tsx

@@ -10,7 +10,7 @@ import { SlidewiseEditor, type SlidewiseEditorHandle } from "./SlidewiseEditor";
 import { parsePptx, serializeDeck } from "@/lib/pptx";
 import type { Deck } from "@/lib/types";
 import type { SlidewiseIcons } from "./compound/IconContext";
-import type { HistoryState } from "./compound/SlidewiseRoot";
+import type { HistoryState, SelectionSnapshot } from "./compound/SlidewiseRoot";
 
 export interface SlidewiseFileEditorProps {
   /**
@@ -55,6 +55,18 @@ export interface SlidewiseFileEditorProps {
    * `api.canUndo()` / `api.canRedo()`.
    */
   onHistoryChange?: (state: HistoryState) => void;
+  /** Fires when the active slide changes (user click, programmatic goToSlide). */
+  onActiveSlideChange?: (slideId: string) => void;
+  /** Fires when the selected element ids change. */
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  /** Fires when the canvas zoom level changes. */
+  onZoomChange?: (scale: number) => void;
+  /** Fires immediately before the host's `saveBlob` is invoked. */
+  onSaveStart?: () => void;
+  /** Fires after `saveBlob` resolves successfully. */
+  onSaveSuccess?: () => void;
+  /** Fires when `saveBlob` throws. The error still propagates. */
+  onSaveError?: (err: Error) => void;
   /**
    * Fires when `loadBlob` or `parse` throws on mount. The default render
    * still shows an in-editor "Could not open file" message, but hosts that
@@ -114,6 +126,37 @@ export interface SlidewiseFileEditorApi {
    * handles typical typing/drag bursts automatically.
    */
   endCoalesce(): void;
+
+  /** Switch the active slide. No-op when `slideId` is not in the deck. */
+  goToSlide(slideId: string): void;
+  /** Advance to the next slide. No-op past the last slide. */
+  nextSlide(): void;
+  /** Step back to the previous slide. No-op past the first. */
+  prevSlide(): void;
+
+  /** Zoom out by one step. */
+  zoomOut(): void;
+  /** Zoom in by one step. */
+  zoomIn(): void;
+  /** Set absolute zoom (1 = 100%); clamped to [0.1, 4]. */
+  setZoom(scale: number): void;
+
+  /**
+   * Insert a blank slide after `afterId`, or at the end. Returns the new
+   * slide's id. The new slide becomes active.
+   */
+  addSlide(afterId?: string): string | null;
+  /**
+   * Duplicate `slideId`. Returns the new slide's id, or `null` if not
+   * found. The duplicate becomes active.
+   */
+  duplicateSlide(slideId: string): string | null;
+  /** Delete `slideId`. No-op when the deck would be left empty. */
+  deleteSlide(slideId: string): void;
+
+  /** Current selection snapshot (slide id + selected element ids). */
+  getSelection(): SelectionSnapshot;
+
   /** Live deck snapshot. Hosts use this for header badges (slide count, etc.). */
   getDeck(): Deck | null;
   getInitialSha256(): string | null;
@@ -138,6 +181,12 @@ export const SlidewiseFileEditor = forwardRef<
     onDirtyChange,
     onLoadError,
     onHistoryChange,
+    onActiveSlideChange,
+    onSelectionChange,
+    onZoomChange,
+    onSaveStart,
+    onSaveSuccess,
+    onSaveError,
     theme,
     initialSlideId,
     showTopBar,
@@ -211,6 +260,23 @@ export const SlidewiseFileEditor = forwardRef<
       getHistorySize: () =>
         editorRef.current?.getHistorySize() ?? { undo: 0, redo: 0 },
       endCoalesce: () => editorRef.current?.endCoalesce(),
+      goToSlide: (slideId: string) => editorRef.current?.goToSlide(slideId),
+      nextSlide: () => editorRef.current?.nextSlide(),
+      prevSlide: () => editorRef.current?.prevSlide(),
+      zoomIn: () => editorRef.current?.zoomIn(),
+      zoomOut: () => editorRef.current?.zoomOut(),
+      setZoom: (scale: number) => editorRef.current?.setZoom(scale),
+      addSlide: (afterId?: string) =>
+        editorRef.current?.addSlide(afterId) ?? null,
+      duplicateSlide: (slideId: string) =>
+        editorRef.current?.duplicateSlide(slideId) ?? null,
+      deleteSlide: (slideId: string) =>
+        editorRef.current?.deleteSlide(slideId),
+      getSelection: () =>
+        editorRef.current?.getSelection() ?? {
+          slideId: state.deck.slides[0]?.id ?? "",
+          elementIds: [],
+        },
       getDeck: () => editorRef.current?.getDeck() ?? state.deck,
       getInitialSha256: () => initialSha256,
     };
@@ -241,6 +307,24 @@ export const SlidewiseFileEditor = forwardRef<
       getHistorySize: () =>
         editorRef.current?.getHistorySize() ?? { undo: 0, redo: 0 },
       endCoalesce: () => editorRef.current?.endCoalesce(),
+      goToSlide: (slideId: string) => editorRef.current?.goToSlide(slideId),
+      nextSlide: () => editorRef.current?.nextSlide(),
+      prevSlide: () => editorRef.current?.prevSlide(),
+      zoomIn: () => editorRef.current?.zoomIn(),
+      zoomOut: () => editorRef.current?.zoomOut(),
+      setZoom: (scale: number) => editorRef.current?.setZoom(scale),
+      addSlide: (afterId?: string) =>
+        editorRef.current?.addSlide(afterId) ?? null,
+      duplicateSlide: (slideId: string) =>
+        editorRef.current?.duplicateSlide(slideId) ?? null,
+      deleteSlide: (slideId: string) =>
+        editorRef.current?.deleteSlide(slideId),
+      getSelection: () =>
+        editorRef.current?.getSelection() ?? {
+          slideId:
+            state.status === "ready" ? state.deck.slides[0]?.id ?? "" : "",
+          elementIds: [],
+        },
       getDeck: () =>
         state.status === "ready"
           ? editorRef.current?.getDeck() ?? state.deck
@@ -287,6 +371,12 @@ export const SlidewiseFileEditor = forwardRef<
           onDirtyChangeRef.current?.(d);
         }}
         onHistoryChange={onHistoryChange}
+        onActiveSlideChange={onActiveSlideChange}
+        onSelectionChange={onSelectionChange}
+        onZoomChange={onZoomChange}
+        onSaveStart={onSaveStart}
+        onSaveSuccess={onSaveSuccess}
+        onSaveError={onSaveError}
         onSave={async (next) => {
           const blob = await serialize(next);
           await saveBlob(blob);

package/src/compound/DirtyContext.tsx

@@ -0,0 +1,30 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+const DirtyContext = createContext<boolean>(false);
+
+export function DirtyProvider({
+  dirty,
+  children,
+}: {
+  dirty: boolean;
+  children: ReactNode;
+}) {
+  return <DirtyContext.Provider value={dirty}>{children}</DirtyContext.Provider>;
+}
+
+/**
+ * Reactive dirty flag. `true` when the deck has uncommitted edits since the
+ * last save / mount. Use this from host components anywhere under
+ * `<Slidewise.Root>` to render "Unsaved changes" UI without polling
+ * `api.isDirty()`.
+ *
+ * ```tsx
+ * function MyHeader() {
+ *   const dirty = useDirty();
+ *   return dirty ? <Badge>Unsaved</Badge> : null;
+ * }
+ * ```
+ */
+export function useDirty(): boolean {
+  return useContext(DirtyContext);
+}

package/src/compound/SlidewiseRoot.tsx

@@ -4,6 +4,7 @@ import {
   useId,
   useImperativeHandle,
   useRef,
+  useState,
   type CSSProperties,
   type PropsWithChildren,
   type Ref,
@@ -20,6 +21,7 @@ import { PlayMode } from "@/components/editor/PlayMode";
 import { HostProvider } from "./HostContext";
 import { IconProvider, type SlidewiseIcons } from "./IconContext";
 import { ReadOnlyProvider } from "./ReadOnlyContext";
+import { DirtyProvider } from "./DirtyContext";
 
 export interface SlidewiseRootProps {
   /**
@@ -41,6 +43,18 @@ export interface SlidewiseRootProps {
    * "Undo"/"Redo" button enabled state without polling `canUndo()`/`canRedo()`.
    */
   onHistoryChange?: (state: HistoryState) => void;
+  /** Fires when the active slide changes (user click, programmatic goToSlide). */
+  onActiveSlideChange?: (slideId: string) => void;
+  /** Fires when the selected element ids change. */
+  onSelectionChange?: (selection: SelectionSnapshot) => void;
+  /** Fires when the canvas zoom level changes. */
+  onZoomChange?: (scale: number) => void;
+  /** Fires immediately before the host's `onSave` is invoked. */
+  onSaveStart?: () => void;
+  /** Fires after the host's `onSave` resolves successfully. */
+  onSaveSuccess?: () => void;
+  /** Fires when the host's `onSave` throws. The error still propagates. */
+  onSaveError?: (err: Error) => void;
   /**
    * Hide editing affordances (save / undo / redo) and disable canvas
    * mutations. Use this when the host viewer doesn't have write access.
@@ -72,6 +86,12 @@ export interface HistoryState {
   redoSize: number;
 }
 
+/** Snapshot of the current selection, scoped to the active slide. */
+export interface SelectionSnapshot {
+  slideId: string;
+  elementIds: string[];
+}
+
 export interface SlidewiseRootHandle {
   play(): void;
   stop(): void;
@@ -90,6 +110,44 @@ export interface SlidewiseRootHandle {
    * window handles typical typing/drag bursts.
    */
   endCoalesce(): void;
+
+  // ---- Navigation ----
+  /** Switch the active slide. No-op when `slideId` is not in the deck. */
+  goToSlide(slideId: string): void;
+  /** Advance to the slide after the current one. No-op past the last slide. */
+  nextSlide(): void;
+  /** Step back to the slide before the current one. No-op past the first. */
+  prevSlide(): void;
+
+  // ---- Zoom ----
+  /** Zoom out by one step (×0.8), clamped to the editor's min zoom. */
+  zoomOut(): void;
+  /** Zoom in by one step (×1.25), clamped to the editor's max zoom. */
+  zoomIn(): void;
+  /** Set the absolute zoom (1 = 100%); clamped to [0.1, 4]. */
+  setZoom(scale: number): void;
+
+  // ---- Slide CRUD ----
+  /**
+   * Insert a blank slide after `afterId`, or at the end if `afterId` is
+   * omitted. Returns the new slide's id. The new slide becomes active.
+   */
+  addSlide(afterId?: string): string;
+  /**
+   * Insert a copy of `slideId` immediately after it. Returns the new
+   * slide's id, or `null` if `slideId` wasn't found. The copy becomes
+   * active.
+   */
+  duplicateSlide(slideId: string): string | null;
+  /**
+   * Delete a slide. No-op when the deck would be left with zero slides.
+   */
+  deleteSlide(slideId: string): void;
+
+  // ---- Selection ----
+  /** Current selection snapshot (slide id + selected element ids). */
+  getSelection(): SelectionSnapshot;
+
   getDeck(): Deck;
   isDirty(): boolean;
   resetDirty(): void;
@@ -122,6 +180,12 @@ function RootInner({
   onExport,
   onDirtyChange,
   onHistoryChange: props_onHistoryChange,
+  onActiveSlideChange,
+  onSelectionChange,
+  onZoomChange,
+  onSaveStart,
+  onSaveSuccess,
+  onSaveError,
   readOnly = false,
   theme,
   initialSlideId,
@@ -137,11 +201,18 @@ function RootInner({
   const store = useEditorStore();
   const savedDeckRef = useRef<Deck>(deck);
   const dirtyRef = useRef(false);
+  const [dirty, setDirty] = useState(false);
   const onChangeRef = useRef(onChange);
   const onDirtyChangeRef = useRef(onDirtyChange);
   const onSaveRef = useRef(onSave);
   const onExportRef = useRef(onExport);
   const onHistoryChangeRef = useRef(props_onHistoryChange);
+  const onActiveSlideChangeRef = useRef(onActiveSlideChange);
+  const onSelectionChangeRef = useRef(onSelectionChange);
+  const onZoomChangeRef = useRef(onZoomChange);
+  const onSaveStartRef = useRef(onSaveStart);
+  const onSaveSuccessRef = useRef(onSaveSuccess);
+  const onSaveErrorRef = useRef(onSaveError);
 
   useEffect(() => {
     onChangeRef.current = onChange;
@@ -149,7 +220,25 @@ function RootInner({
     onSaveRef.current = onSave;
     onExportRef.current = onExport;
     onHistoryChangeRef.current = props_onHistoryChange;
-  }, [onChange, onDirtyChange, onSave, onExport, props_onHistoryChange]);
+    onActiveSlideChangeRef.current = onActiveSlideChange;
+    onSelectionChangeRef.current = onSelectionChange;
+    onZoomChangeRef.current = onZoomChange;
+    onSaveStartRef.current = onSaveStart;
+    onSaveSuccessRef.current = onSaveSuccess;
+    onSaveErrorRef.current = onSaveError;
+  }, [
+    onChange,
+    onDirtyChange,
+    onSave,
+    onExport,
+    props_onHistoryChange,
+    onActiveSlideChange,
+    onSelectionChange,
+    onZoomChange,
+    onSaveStart,
+    onSaveSuccess,
+    onSaveError,
+  ]);
 
   useEffect(() => {
     if (theme) {
@@ -176,6 +265,7 @@ function RootInner({
       savedDeckRef.current = deck;
       if (dirtyRef.current) {
         dirtyRef.current = false;
+        setDirty(false);
         onDirtyChangeRef.current?.(false);
       }
     }
@@ -203,11 +293,35 @@ function RootInner({
           redoSize: nextFut,
         });
       }
+
+      // Active slide changes (click in rail, programmatic goToSlide).
+      if (state.currentSlideId !== prev.currentSlideId) {
+        onActiveSlideChangeRef.current?.(state.currentSlideId);
+      }
+
+      // Selection — shallow compare ids since the array is rebuilt on
+      // every selectElement call. Same slideId + same ids = no emit.
+      if (
+        state.selectedIds !== prev.selectedIds &&
+        !shallowEqualIds(state.selectedIds, prev.selectedIds)
+      ) {
+        onSelectionChangeRef.current?.({
+          slideId: state.currentSlideId,
+          elementIds: state.selectedIds,
+        });
+      }
+
+      // Zoom.
+      if (state.zoom !== prev.zoom) {
+        onZoomChangeRef.current?.(state.zoom);
+      }
+
       if (state.deck === prev.deck) return;
       onChangeRef.current?.(state.deck);
       const nextDirty = state.deck !== savedDeckRef.current;
       if (nextDirty !== dirtyRef.current) {
         dirtyRef.current = nextDirty;
+        setDirty(nextDirty);
         onDirtyChangeRef.current?.(nextDirty);
       }
       ensureGoogleFontsLoaded(instanceId, collectFontFamilies(state.deck));
@@ -234,12 +348,54 @@ function RootInner({
         return { undo: s.history.length, redo: s.future.length };
       },
       endCoalesce: () => store.getState().endCoalesce(),
+
+      goToSlide: (slideId: string) => {
+        const s = store.getState();
+        if (s.deck.slides.some((sl) => sl.id === slideId)) {
+          s.selectSlide(slideId);
+        }
+      },
+      nextSlide: () => {
+        const s = store.getState();
+        const idx = s.deck.slides.findIndex(
+          (sl) => sl.id === s.currentSlideId
+        );
+        const next = s.deck.slides[idx + 1];
+        if (next) s.selectSlide(next.id);
+      },
+      prevSlide: () => {
+        const s = store.getState();
+        const idx = s.deck.slides.findIndex(
+          (sl) => sl.id === s.currentSlideId
+        );
+        const prev = s.deck.slides[idx - 1];
+        if (prev) s.selectSlide(prev.id);
+      },
+
+      zoomIn: () => store.getState().zoomIn(),
+      zoomOut: () => store.getState().zoomOut(),
+      setZoom: (scale: number) => store.getState().setZoom(scale),
+
+      addSlide: (afterId?: string) => store.getState().addSlide(afterId),
+      duplicateSlide: (slideId: string) =>
+        store.getState().duplicateSlide(slideId),
+      deleteSlide: (slideId: string) => store.getState().deleteSlide(slideId),
+
+      getSelection: (): SelectionSnapshot => {
+        const s = store.getState();
+        return {
+          slideId: s.currentSlideId,
+          elementIds: [...s.selectedIds],
+        };
+      },
+
       getDeck: () => store.getState().deck,
       isDirty: () => dirtyRef.current,
       resetDirty: () => {
         savedDeckRef.current = store.getState().deck;
         if (dirtyRef.current) {
           dirtyRef.current = false;
+          setDirty(false);
           onDirtyChangeRef.current?.(false);
         }
       },
@@ -247,15 +403,28 @@ function RootInner({
     [store]
   );
 
-  // Wrap host save with dirty-flag reset so any TopBar.Save / imperative save
-  // path that funnels through here clears the dirty state on success.
+  // Wrap host save with:
+  //   - onSaveStart / onSaveSuccess / onSaveError lifecycle hooks
+  //   - dirty-flag reset on success
+  // The error still propagates so TopBar.Save's local "Saving…" → "idle"
+  // transition kicks in correctly.
   const wrappedSave = onSave
     ? async (d: Deck) => {
-        await onSaveRef.current!(d);
-        savedDeckRef.current = d;
-        if (dirtyRef.current) {
-          dirtyRef.current = false;
-          onDirtyChangeRef.current?.(false);
+        onSaveStartRef.current?.();
+        try {
+          await onSaveRef.current!(d);
+          savedDeckRef.current = d;
+          if (dirtyRef.current) {
+            dirtyRef.current = false;
+            setDirty(false);
+            onDirtyChangeRef.current?.(false);
+          }
+          onSaveSuccessRef.current?.();
+        } catch (err) {
+          onSaveErrorRef.current?.(
+            err instanceof Error ? err : new Error(String(err))
+          );
+          throw err;
         }
       }
     : undefined;
@@ -263,15 +432,17 @@ function RootInner({
   return (
     <ReadOnlyProvider readOnly={readOnly}>
       <IconProvider icons={icons ?? {}}>
-        <HostProvider callbacks={{ onSave: wrappedSave, onExport }}>
-          <RootShell
-            fontFamily={fontFamily}
-            className={className}
-            style={style}
-          >
-            {children}
-          </RootShell>
-        </HostProvider>
+        <DirtyProvider dirty={dirty}>
+          <HostProvider callbacks={{ onSave: wrappedSave, onExport }}>
+            <RootShell
+              fontFamily={fontFamily}
+              className={className}
+              style={style}
+            >
+              {children}
+            </RootShell>
+          </HostProvider>
+        </DirtyProvider>
       </IconProvider>
     </ReadOnlyProvider>
   );
@@ -323,3 +494,12 @@ function RootShell({
     </div>
   );
 }
+
+function shallowEqualIds(a: readonly string[], b: readonly string[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}

package/src/compound/hooks.ts

@@ -0,0 +1,93 @@
+/**
+ * Public store hooks. These let host components anywhere inside
+ * `<Slidewise.Root>` read or write editor state without prop drilling.
+ *
+ * `useEditor` is the generic selector hook — pass any function that takes
+ * the editor state and returns the slice you care about. The convenience
+ * hooks below cover the common cases.
+ *
+ * Example:
+ *
+ * ```tsx
+ * import { useEditor, useSlides, useActiveSlide } from "@textcortex/slidewise";
+ *
+ * function HostHeader() {
+ *   const slideCount = useSlides().length;
+ *   const active = useActiveSlide();
+ *   return <span>Slide {active.id} of {slideCount}</span>;
+ * }
+ * ```
+ */
+import { useEditor } from "@/lib/StoreProvider";
+import type { Slide, SlideElement } from "@/lib/types";
+
+export { useEditor, useEditorStore } from "@/lib/StoreProvider";
+
+/** All slides in the current deck, in display order. */
+export function useSlides(): Slide[] {
+  return useEditor((s) => s.deck.slides);
+}
+
+/**
+ * The currently focused slide. Falls back to the first slide if the
+ * `currentSlideId` no longer exists (shouldn't happen, but defensive).
+ */
+export function useActiveSlide(): Slide {
+  return useEditor((s) => {
+    const found = s.deck.slides.find((sl) => sl.id === s.currentSlideId);
+    return found ?? s.deck.slides[0];
+  });
+}
+
+/** Id of the currently focused slide. */
+export function useActiveSlideId(): string {
+  return useEditor((s) => s.currentSlideId);
+}
+
+/** Ids of currently selected elements on the active slide. */
+export function useSelection(): string[] {
+  return useEditor((s) => s.selectedIds);
+}
+
+/**
+ * Resolved selected element objects on the active slide. Returns `[]` when
+ * nothing is selected. Use this when you need to read element properties
+ * (position, text, fill) — not just their ids.
+ */
+export function useSelectedElements(): SlideElement[] {
+  return useEditor((s) => {
+    const slide = s.deck.slides.find((sl) => sl.id === s.currentSlideId);
+    if (!slide) return [];
+    return slide.elements.filter((e) => s.selectedIds.includes(e.id));
+  });
+}
+
+/** Current theme ("light" or "dark"). */
+export function useTheme(): "light" | "dark" {
+  return useEditor((s) => s.theme);
+}
+
+/** Current zoom scale (1 = 100%). */
+export function useZoom(): number {
+  return useEditor((s) => s.zoom);
+}
+
+/** True when the editor is in present-mode. */
+export function usePlaying(): boolean {
+  return useEditor((s) => s.playing);
+}
+
+/** Live history depth — useful for host-rendered Undo/Redo button state. */
+export function useHistory(): {
+  canUndo: boolean;
+  canRedo: boolean;
+  undoSize: number;
+  redoSize: number;
+} {
+  return useEditor((s) => ({
+    canUndo: s.history.length > 0,
+    canRedo: s.future.length > 0,
+    undoSize: s.history.length,
+    redoSize: s.future.length,
+  }));
+}