@textcortex/slidewise 1.0.0 → 1.1.0

package/src/SlidewiseFileEditor.tsx

@@ -9,6 +9,7 @@ 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";
 
 export interface SlidewiseFileEditorProps {
   /**
@@ -23,7 +24,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 +41,37 @@ 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 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 +94,8 @@ export interface SlidewiseFileEditorApi {
   stop(): void;
   undo(): void;
   redo(): void;
+  /** Live deck snapshot. Hosts use this for header badges (slide count, etc.). */
+  getDeck(): Deck | null;
   getInitialSha256(): string | null;
 }
 
@@ -74,9 +111,18 @@ export const SlidewiseFileEditor = forwardRef<
   {
     loadBlob,
     saveBlob,
+    editable = true,
     initialSha256 = null,
     onEditorApiChange,
+    onChange,
+    onDirtyChange,
+    onLoadError,
     theme,
+    initialSlideId,
+    showTopBar,
+    showBottomToolbar,
+    fontFamily,
+    icons,
     className,
     style,
     parse = parsePptx,
@@ -88,10 +134,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 +155,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 +175,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 +185,7 @@ export const SlidewiseFileEditor = forwardRef<
       stop: () => editorRef.current?.stop(),
       undo: () => editorRef.current?.undo(),
       redo: () => editorRef.current?.redo(),
+      getDeck: () => editorRef.current?.getDeck() ?? state.deck,
       getInitialSha256: () => initialSha256,
     };
 
@@ -160,6 +210,10 @@ export const SlidewiseFileEditor = forwardRef<
       stop: () => editorRef.current?.stop(),
       undo: () => editorRef.current?.undo(),
       redo: () => editorRef.current?.redo(),
+      getDeck: () =>
+        state.status === "ready"
+          ? editorRef.current?.getDeck() ?? state.deck
+          : null,
       getInitialSha256: () => initialSha256,
     }),
     [state, serialize, saveBlob, initialSha256]
@@ -188,7 +242,19 @@ 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);
+        }}
         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);
+}

package/src/compound/SlidewiseRoot.tsx

@@ -0,0 +1,274 @@
+import {
+  forwardRef,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useRef,
+  type CSSProperties,
+  type PropsWithChildren,
+  type Ref,
+} from "react";
+import {
+  EditorStoreProvider,
+  useEditor,
+  useEditorStore,
+} from "@/lib/StoreProvider";
+import { collectFontFamilies, ensureGoogleFontsLoaded } from "@/lib/fonts";
+import type { Deck } from "@/lib/types";
+import { GridView } from "@/components/editor/GridView";
+import { PlayMode } from "@/components/editor/PlayMode";
+import { HostProvider } from "./HostContext";
+import { IconProvider, type SlidewiseIcons } from "./IconContext";
+import { ReadOnlyProvider } from "./ReadOnlyContext";
+
+export interface SlidewiseRootProps {
+  /**
+   * Deck to load on mount. Pass a new reference only when you intend to
+   * reset the editor's state (e.g. discard changes, load a different file)
+   * — passing a new reference on every `onChange` would loop.
+   */
+  deck: Deck;
+  /** Fires after every committed mutation. */
+  onChange?: (deck: Deck) => void;
+  /** Fires when the user invokes save (top bar button or imperative API). */
+  onSave?: (deck: Deck) => void | Promise<void>;
+  /** Override the default `.slidewise.json` export. */
+  onExport?: (deck: Deck) => void;
+  /** Fires when the dirty flag flips. */
+  onDirtyChange?: (dirty: boolean) => void;
+  /**
+   * Hide editing affordances (save / undo / redo) and disable canvas
+   * mutations. Use this when the host viewer doesn't have write access.
+   */
+  readOnly?: boolean;
+  /** "light" | "dark"; first-render only. */
+  theme?: "light" | "dark";
+  /** Slide id to land on; falls back to the first. */
+  initialSlideId?: string;
+  /** Override the default Geist font; sets `--slidewise-font-sans`. */
+  fontFamily?: string;
+  /**
+   * Per-action icon overrides for the chrome. Hosts pass any subset to
+   * skin Slidewise with their own icon set; missing slots fall back to
+   * the bundled lucide icons.
+   */
+  icons?: SlidewiseIcons;
+  /** Extra class names appended to the root. */
+  className?: string;
+  /** Inline style applied to the root. */
+  style?: CSSProperties;
+}
+
+export interface SlidewiseRootHandle {
+  play(): void;
+  stop(): void;
+  undo(): void;
+  redo(): void;
+  getDeck(): Deck;
+  isDirty(): boolean;
+  resetDirty(): void;
+}
+
+/**
+ * Top-level compound part. Provides the editor's store via context to all
+ * descendants and renders the themed root container. Compose any subset of
+ * `<Slidewise.TopBar />`, `<Slidewise.SlideRail />`, `<Slidewise.Canvas />`,
+ * `<Slidewise.RightPanel />`, `<Slidewise.BottomToolbar />` as children — or
+ * mix them with host UI to wrap, replace, or omit any region.
+ *
+ * Hosts that want the unopinionated default tree can use `<SlidewiseEditor>`
+ * which is just `<Slidewise.Root>` rendering the standard layout.
+ */
+export const Root = forwardRef<SlidewiseRootHandle, PropsWithChildren<SlidewiseRootProps>>(
+  function SlidewiseRoot(props, ref) {
+    return (
+      <EditorStoreProvider initialDeck={props.deck}>
+        <RootInner {...props} forwardedRef={ref} />
+      </EditorStoreProvider>
+    );
+  }
+);
+
+function RootInner({
+  deck,
+  onChange,
+  onSave,
+  onExport,
+  onDirtyChange,
+  readOnly = false,
+  theme,
+  initialSlideId,
+  fontFamily,
+  icons,
+  className,
+  style,
+  children,
+  forwardedRef,
+}: PropsWithChildren<SlidewiseRootProps> & {
+  forwardedRef: Ref<SlidewiseRootHandle>;
+}) {
+  const store = useEditorStore();
+  const savedDeckRef = useRef<Deck>(deck);
+  const dirtyRef = useRef(false);
+  const onChangeRef = useRef(onChange);
+  const onDirtyChangeRef = useRef(onDirtyChange);
+  const onSaveRef = useRef(onSave);
+  const onExportRef = useRef(onExport);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+    onDirtyChangeRef.current = onDirtyChange;
+    onSaveRef.current = onSave;
+    onExportRef.current = onExport;
+  }, [onChange, onDirtyChange, onSave, onExport]);
+
+  useEffect(() => {
+    if (theme) {
+      store.getState().setTheme(theme);
+    }
+  }, [theme, store]);
+
+  useEffect(() => {
+    if (initialSlideId) {
+      const exists = store
+        .getState()
+        .deck.slides.some((s) => s.id === initialSlideId);
+      if (exists) {
+        store.getState().selectSlide(initialSlideId);
+      }
+    }
+    // run once on mount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    if (deck !== savedDeckRef.current) {
+      store.getState().setDeck(deck);
+      savedDeckRef.current = deck;
+      if (dirtyRef.current) {
+        dirtyRef.current = false;
+        onDirtyChangeRef.current?.(false);
+      }
+    }
+  }, [deck, store]);
+
+  const instanceId = useId().replace(/[^a-z0-9]/gi, "");
+  useEffect(() => {
+    ensureGoogleFontsLoaded(
+      instanceId,
+      collectFontFamilies(store.getState().deck)
+    );
+    return store.subscribe((state, prev) => {
+      if (state.deck === prev.deck) return;
+      onChangeRef.current?.(state.deck);
+      const nextDirty = state.deck !== savedDeckRef.current;
+      if (nextDirty !== dirtyRef.current) {
+        dirtyRef.current = nextDirty;
+        onDirtyChangeRef.current?.(nextDirty);
+      }
+      ensureGoogleFontsLoaded(instanceId, collectFontFamilies(state.deck));
+    });
+  }, [store, instanceId]);
+
+  useEffect(() => {
+    return () => {
+      ensureGoogleFontsLoaded(instanceId, []);
+    };
+  }, [instanceId]);
+
+  useImperativeHandle(
+    forwardedRef,
+    () => ({
+      play: () => store.getState().play(),
+      stop: () => store.getState().stop(),
+      undo: () => store.getState().undo(),
+      redo: () => store.getState().redo(),
+      getDeck: () => store.getState().deck,
+      isDirty: () => dirtyRef.current,
+      resetDirty: () => {
+        savedDeckRef.current = store.getState().deck;
+        if (dirtyRef.current) {
+          dirtyRef.current = false;
+          onDirtyChangeRef.current?.(false);
+        }
+      },
+    }),
+    [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.
+  const wrappedSave = onSave
+    ? async (d: Deck) => {
+        await onSaveRef.current!(d);
+        savedDeckRef.current = d;
+        if (dirtyRef.current) {
+          dirtyRef.current = false;
+          onDirtyChangeRef.current?.(false);
+        }
+      }
+    : undefined;
+
+  return (
+    <ReadOnlyProvider readOnly={readOnly}>
+      <IconProvider icons={icons ?? {}}>
+        <HostProvider callbacks={{ onSave: wrappedSave, onExport }}>
+          <RootShell
+            fontFamily={fontFamily}
+            className={className}
+            style={style}
+          >
+            {children}
+          </RootShell>
+        </HostProvider>
+      </IconProvider>
+    </ReadOnlyProvider>
+  );
+}
+
+/**
+ * Renders the themed container. Split out so the children read the theme
+ * via the store (not props), letting them re-render when the theme flips.
+ */
+function RootShell({
+  fontFamily,
+  className,
+  style,
+  children,
+}: PropsWithChildren<{
+  fontFamily?: string;
+  className?: string;
+  style?: CSSProperties;
+}>) {
+  const theme = useEditor((s) => s.theme);
+  const playing = useEditor((s) => s.playing);
+  const view = useEditor((s) => s.view);
+
+  const rootStyle: CSSProperties = {
+    width: "100%",
+    height: "100%",
+    display: "flex",
+    flexDirection: "column",
+    background: "var(--app-bg)",
+    color: "var(--ink)",
+    overflow: "hidden",
+    ...(fontFamily ? { ["--font-geist-sans" as string]: fontFamily } : null),
+    ...style,
+  };
+
+  return (
+    <div
+      className={
+        className
+          ? `slidewise-editor theme-${theme} ${className}`
+          : `slidewise-editor theme-${theme}`
+      }
+      data-slidewise-theme={theme}
+      style={rootStyle}
+    >
+      {children}
+      {view === "grid" && <GridView />}
+      {playing && <PlayMode />}
+    </div>
+  );
+}