@textcortex/slidewise 1.0.1 → 1.2.0

package/src/SlidewiseFileEditor.tsx

@@ -9,6 +9,8 @@ import {
 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";
 
 export interface SlidewiseFileEditorProps {
   /**
@@ -23,7 +25,11 @@ export interface SlidewiseFileEditorProps {
    * Called when `save()` is invoked on the imperative API.
    */
   saveBlob: (blob: Blob) => Promise<void>;
-  /** Disables editing affordances (TODO: not yet enforced). */
+  /**
+   * When `false`, the top bar's save / undo / redo buttons are hidden and
+   * the title input is read-only. Mirrors the host's "viewer doesn't have
+   * write access" state. Defaults to `true`.
+   */
   editable?: boolean;
   /**
    * The sha256 of the file's contents at load time, if the host wants to do
@@ -36,7 +42,43 @@ export interface SlidewiseFileEditorProps {
    * editor is mounted. Called with `null` on unmount.
    */
   onEditorApiChange?: (api: SlidewiseFileEditorApi | null) => void;
+  /** Fires after every committed mutation. Mirrors `SlidewiseEditor.onChange`. */
+  onChange?: (deck: Deck) => void;
+  /**
+   * Fires reactively when the dirty flag flips. Use this instead of polling
+   * `api.isDirty()` for "unsaved changes" UI.
+   */
+  onDirtyChange?: (dirty: boolean) => void;
+  /**
+   * Fires whenever the undo/redo stack depths change. Use this to enable/
+   * disable host-rendered Undo/Redo buttons reactively without polling
+   * `api.canUndo()` / `api.canRedo()`.
+   */
+  onHistoryChange?: (state: HistoryState) => 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
+   * want to surface their own error UI can replace it via this callback.
+   */
+  onLoadError?: (err: Error) => void;
   theme?: "light" | "dark";
+  /** Slide id to land on; falls back to the first. */
+  initialSlideId?: string;
+  /** Render the built-in top bar. Default `true`. */
+  showTopBar?: boolean;
+  /** Render the floating bottom toolbar. Default `true`. */
+  showBottomToolbar?: boolean;
+  /**
+   * Override the bundled Geist font; sets `--font-geist-sans` on the editor
+   * root.
+   */
+  fontFamily?: string;
+  /**
+   * Per-action icon overrides. Pass a ReactNode for any of `undo`, `redo`,
+   * `save`, `play`, `themeLight`, `themeDark`, `export`, `smart` to skin the
+   * editor's chrome with your own icon set.
+   */
+  icons?: SlidewiseIcons;
   className?: string;
   style?: CSSProperties;
   /**
@@ -59,6 +101,21 @@ export interface SlidewiseFileEditorApi {
   stop(): void;
   undo(): void;
   redo(): void;
+  /** True iff there's at least one snapshot to undo back to. */
+  canUndo(): boolean;
+  /** True iff there's at least one snapshot to redo forward to. */
+  canRedo(): boolean;
+  /** Current undo/redo stack depths. */
+  getHistorySize(): { undo: number; redo: number };
+  /**
+   * End the in-flight coalesce burst. Call on natural commit boundaries
+   * (mouseup after drag, blur on a text input) so the next mutation starts
+   * a fresh history step. Most hosts won't need this — a 500ms idle window
+   * handles typical typing/drag bursts automatically.
+   */
+  endCoalesce(): void;
+  /** Live deck snapshot. Hosts use this for header badges (slide count, etc.). */
+  getDeck(): Deck | null;
   getInitialSha256(): string | null;
 }
 
@@ -74,9 +131,19 @@ export const SlidewiseFileEditor = forwardRef<
   {
     loadBlob,
     saveBlob,
+    editable = true,
     initialSha256 = null,
     onEditorApiChange,
+    onChange,
+    onDirtyChange,
+    onLoadError,
+    onHistoryChange,
     theme,
+    initialSlideId,
+    showTopBar,
+    showBottomToolbar,
+    fontFamily,
+    icons,
     className,
     style,
     parse = parsePptx,
@@ -88,10 +155,16 @@ export const SlidewiseFileEditor = forwardRef<
   const editorRef = useRef<SlidewiseEditorHandle>(null);
   const [dirty, setDirty] = useState(false);
   const apiCallbackRef = useRef(onEditorApiChange);
+  const onChangeRef = useRef(onChange);
+  const onDirtyChangeRef = useRef(onDirtyChange);
+  const onLoadErrorRef = useRef(onLoadError);
 
   useEffect(() => {
     apiCallbackRef.current = onEditorApiChange;
-  }, [onEditorApiChange]);
+    onChangeRef.current = onChange;
+    onDirtyChangeRef.current = onDirtyChange;
+    onLoadErrorRef.current = onLoadError;
+  }, [onEditorApiChange, onChange, onDirtyChange, onLoadError]);
 
   // Load file once on mount.
   useEffect(() => {
@@ -103,12 +176,10 @@ export const SlidewiseFileEditor = forwardRef<
         const deck = await parse(blob);
         if (!cancelled) setState({ status: "ready", deck });
       } catch (err) {
-        if (!cancelled) {
-          setState({
-            status: "error",
-            error: err instanceof Error ? err : new Error(String(err)),
-          });
-        }
+        if (cancelled) return;
+        const error = err instanceof Error ? err : new Error(String(err));
+        setState({ status: "error", error });
+        onLoadErrorRef.current?.(error);
       }
     })();
     return () => {
@@ -125,8 +196,7 @@ export const SlidewiseFileEditor = forwardRef<
 
     const api: SlidewiseFileEditorApi = {
       save: async () => {
-        const current =
-          editorRef.current?.getDeck() ?? state.deck;
+        const current = editorRef.current?.getDeck() ?? state.deck;
         const blob = await serialize(current);
         await saveBlob(blob);
         editorRef.current?.resetDirty();
@@ -136,6 +206,12 @@ export const SlidewiseFileEditor = forwardRef<
       stop: () => editorRef.current?.stop(),
       undo: () => editorRef.current?.undo(),
       redo: () => editorRef.current?.redo(),
+      canUndo: () => editorRef.current?.canUndo() ?? false,
+      canRedo: () => editorRef.current?.canRedo() ?? false,
+      getHistorySize: () =>
+        editorRef.current?.getHistorySize() ?? { undo: 0, redo: 0 },
+      endCoalesce: () => editorRef.current?.endCoalesce(),
+      getDeck: () => editorRef.current?.getDeck() ?? state.deck,
       getInitialSha256: () => initialSha256,
     };
 
@@ -160,6 +236,15 @@ export const SlidewiseFileEditor = forwardRef<
       stop: () => editorRef.current?.stop(),
       undo: () => editorRef.current?.undo(),
       redo: () => editorRef.current?.redo(),
+      canUndo: () => editorRef.current?.canUndo() ?? false,
+      canRedo: () => editorRef.current?.canRedo() ?? false,
+      getHistorySize: () =>
+        editorRef.current?.getHistorySize() ?? { undo: 0, redo: 0 },
+      endCoalesce: () => editorRef.current?.endCoalesce(),
+      getDeck: () =>
+        state.status === "ready"
+          ? editorRef.current?.getDeck() ?? state.deck
+          : null,
       getInitialSha256: () => initialSha256,
     }),
     [state, serialize, saveBlob, initialSha256]
@@ -188,7 +273,20 @@ export const SlidewiseFileEditor = forwardRef<
         ref={editorRef}
         deck={state.deck}
         theme={theme}
-        onDirtyChange={setDirty}
+        readOnly={!editable}
+        initialSlideId={initialSlideId}
+        showTopBar={showTopBar}
+        showBottomToolbar={showBottomToolbar}
+        fontFamily={fontFamily}
+        icons={icons}
+        onChange={(next) => {
+          onChangeRef.current?.(next);
+        }}
+        onDirtyChange={(d) => {
+          setDirty(d);
+          onDirtyChangeRef.current?.(d);
+        }}
+        onHistoryChange={onHistoryChange}
         onSave={async (next) => {
           const blob = await serialize(next);
           await saveBlob(blob);

package/src/components/editor/TopBar.tsx

@@ -9,8 +9,10 @@ import {
   Moon,
 } from "lucide-react";
 import { useEditor, useEditorStore } from "@/lib/StoreProvider";
-import { useState } from "react";
+import { useState, type ReactNode } from "react";
 import type { Deck } from "@/lib/types";
+import { useIcons } from "@/compound/IconContext";
+import { useReadOnly } from "@/compound/ReadOnlyContext";
 
 interface TopBarProps {
   onSave?: (deck: Deck) => void | Promise<void>;
@@ -26,6 +28,8 @@ export function TopBar({ onSave: onSaveProp, onExport: onExportProp }: TopBarPro
   const play = useEditor((s) => s.play);
   const theme = useEditor((s) => s.theme);
   const toggleTheme = useEditor((s) => s.toggleTheme);
+  const icons = useIcons();
+  const readOnly = useReadOnly();
   const [saved, setSaved] = useState<"idle" | "saving" | "saved">("idle");
 
   const onSave = async () => {
@@ -71,7 +75,7 @@ export function TopBar({ onSave: onSaveProp, onExport: onExportProp }: TopBarPro
         alignItems: "center",
         padding: "0 14px",
         gap: 10,
-        background: "var(--app-bg)",
+        background: "var(--slidewise-bar-bg, var(--app-bg))",
         borderBottom: "1px solid var(--border)",
         boxShadow: "var(--topbar-shadow)",
         fontFamily: "Inter, system-ui, sans-serif",
@@ -80,12 +84,16 @@ export function TopBar({ onSave: onSaveProp, onExport: onExportProp }: TopBarPro
         color: "var(--ink)",
       }}
     >
-      <IconBtn onClick={undo} title="Undo">
-        <Undo2 size={16} />
-      </IconBtn>
-      <IconBtn onClick={redo} title="Redo">
-        <Redo2 size={16} />
-      </IconBtn>
+      {!readOnly && (
+        <>
+          <IconBtn onClick={undo} title="Undo">
+            {icons.undo ?? <Undo2 size={16} />}
+          </IconBtn>
+          <IconBtn onClick={redo} title="Redo">
+            {icons.redo ?? <Redo2 size={16} />}
+          </IconBtn>
+        </>
+      )}
 
       <div
         style={{
@@ -111,12 +119,13 @@ export function TopBar({ onSave: onSaveProp, onExport: onExportProp }: TopBarPro
             letterSpacing: 0.2,
           }}
         >
-          <Sparkles size={11} />
+          {icons.smart ?? <Sparkles size={11} />}
           Smart
         </span>
         <input
           aria-label="Deck title"
           value={title}
+          readOnly={readOnly}
           onChange={(e) => setTitle(e.target.value)}
           style={{
             background: "transparent",
@@ -135,18 +144,22 @@ export function TopBar({ onSave: onSaveProp, onExport: onExportProp }: TopBarPro
         onClick={toggleTheme}
         title={theme === "dark" ? "Light mode" : "Dark mode"}
       >
-        {theme === "dark" ? <Sun size={16} /> : <Moon size={16} />}
+        {theme === "dark"
+          ? (icons.themeLight ?? <Sun size={16} />)
+          : (icons.themeDark ?? <Moon size={16} />)}
       </IconBtn>
 
-      <button
-        onClick={onSave}
-        style={chromeBtnStyle()}
-        onMouseEnter={(e) => (e.currentTarget.style.background = "var(--hover)")}
-        onMouseLeave={(e) => (e.currentTarget.style.background = "transparent")}
-      >
-        <Save size={14} />
-        {saved === "saving" ? "Saving…" : saved === "saved" ? "Saved" : "Save"}
-      </button>
+      {!readOnly && (
+        <button
+          onClick={onSave}
+          style={chromeBtnStyle()}
+          onMouseEnter={(e) => (e.currentTarget.style.background = "var(--hover)")}
+          onMouseLeave={(e) => (e.currentTarget.style.background = "transparent")}
+        >
+          {icons.save ?? <Save size={14} />}
+          {saved === "saving" ? "Saving…" : saved === "saved" ? "Saved" : "Save"}
+        </button>
+      )}
 
       <button
         onClick={play}
@@ -154,7 +167,7 @@ export function TopBar({ onSave: onSaveProp, onExport: onExportProp }: TopBarPro
         onMouseEnter={(e) => (e.currentTarget.style.background = "var(--hover)")}
         onMouseLeave={(e) => (e.currentTarget.style.background = "transparent")}
       >
-        <Play size={14} />
+        {icons.play ?? <Play size={14} />}
         Play
       </button>
 
@@ -168,7 +181,7 @@ export function TopBar({ onSave: onSaveProp, onExport: onExportProp }: TopBarPro
           gap: 6,
           background: "var(--primary-bg)",
           border: "1px solid var(--primary-bg)",
-          borderRadius: 10,
+          borderRadius: "var(--slidewise-radius, 10px)",
           cursor: "pointer",
           color: "var(--primary-fg)",
           fontSize: 13,
@@ -181,7 +194,7 @@ export function TopBar({ onSave: onSaveProp, onExport: onExportProp }: TopBarPro
           (e.currentTarget.style.background = "var(--primary-bg)")
         }
       >
-        <Download size={14} />
+        {icons.export ?? <Download size={14} />}
         Export
       </button>
     </div>
@@ -197,7 +210,7 @@ function chromeBtnStyle(): React.CSSProperties {
     gap: 6,
     background: "transparent",
     border: "1px solid var(--border-strong)",
-    borderRadius: 10,
+    borderRadius: "var(--slidewise-radius, 10px)",
     cursor: "pointer",
     color: "var(--ink)",
     fontSize: 13,
@@ -210,7 +223,7 @@ function IconBtn({
   onClick,
   title,
 }: {
-  children: React.ReactNode;
+  children: ReactNode;
   onClick: () => void;
   title: string;
 }) {

package/src/compound/HostContext.tsx

@@ -0,0 +1,29 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { Deck } from "@/lib/types";
+
+/**
+ * Host-supplied callbacks consumed by leaf compound parts (e.g. TopBar's
+ * save/export buttons). Distinct from the editor store, which owns deck +
+ * UI state. This context exists so child parts can invoke host effects
+ * without prop-drilling through every region.
+ */
+export interface SlidewiseHostCallbacks {
+  onSave?: (deck: Deck) => void | Promise<void>;
+  onExport?: (deck: Deck) => void;
+}
+
+const HostContext = createContext<SlidewiseHostCallbacks>({});
+
+export function HostProvider({
+  callbacks,
+  children,
+}: {
+  callbacks: SlidewiseHostCallbacks;
+  children: ReactNode;
+}) {
+  return <HostContext.Provider value={callbacks}>{children}</HostContext.Provider>;
+}
+
+export function useHostCallbacks(): SlidewiseHostCallbacks {
+  return useContext(HostContext);
+}

package/src/compound/IconContext.tsx

@@ -0,0 +1,42 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+/**
+ * Per-action icon overrides for the editor's chrome. Pass a `ReactNode` for
+ * any button you want to skin with your own icon set (Nucleo, custom SVG,
+ * etc.). Slots you don't override fall back to the bundled lucide-react
+ * icons so partial overrides are fine.
+ *
+ * The icons are rendered inline at ~14–16px next to text labels; pick an
+ * SVG that has a transparent fill and uses `currentColor` for the stroke
+ * so it inherits the surrounding `--ink` / `--primary-fg` color.
+ */
+export interface SlidewiseIcons {
+  undo?: ReactNode;
+  redo?: ReactNode;
+  save?: ReactNode;
+  play?: ReactNode;
+  stop?: ReactNode;
+  /** Sun icon shown in the theme toggle when the dark theme is active. */
+  themeLight?: ReactNode;
+  /** Moon icon shown in the theme toggle when the light theme is active. */
+  themeDark?: ReactNode;
+  export?: ReactNode;
+  /** "Smart" pill in the title bar. */
+  smart?: ReactNode;
+}
+
+const IconContext = createContext<SlidewiseIcons>({});
+
+export function IconProvider({
+  icons,
+  children,
+}: {
+  icons: SlidewiseIcons;
+  children: ReactNode;
+}) {
+  return <IconContext.Provider value={icons}>{children}</IconContext.Provider>;
+}
+
+export function useIcons(): SlidewiseIcons {
+  return useContext(IconContext);
+}

package/src/compound/ReadOnlyContext.tsx

@@ -0,0 +1,23 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+const ReadOnlyContext = createContext<boolean>(false);
+
+export function ReadOnlyProvider({
+  readOnly,
+  children,
+}: {
+  readOnly: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <ReadOnlyContext.Provider value={readOnly}>{children}</ReadOnlyContext.Provider>
+  );
+}
+
+/**
+ * Read-only mode flag. Region parts (TopBar, Canvas) hide editing affordances
+ * and skip mutation handlers when this is `true`.
+ */
+export function useReadOnly(): boolean {
+  return useContext(ReadOnlyContext);
+}