@textcortex/slidewise 1.0.1 → 1.2.0

package/src/compound/SlidewiseRoot.tsx

@@ -0,0 +1,325 @@
+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;
+  /**
+   * Fires whenever the undo/redo stacks change depth. Use this to update
+   * "Undo"/"Redo" button enabled state without polling `canUndo()`/`canRedo()`.
+   */
+  onHistoryChange?: (state: HistoryState) => 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 HistoryState {
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Snapshot counts. Useful for "X steps to redo" indicators. */
+  undoSize: number;
+  redoSize: number;
+}
+
+export interface SlidewiseRootHandle {
+  play(): void;
+  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 — the 500ms idle
+   * window handles typical typing/drag bursts.
+   */
+  endCoalesce(): 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,
+  onHistoryChange: props_onHistoryChange,
+  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);
+  const onHistoryChangeRef = useRef(props_onHistoryChange);
+
+  useEffect(() => {
+    onChangeRef.current = onChange;
+    onDirtyChangeRef.current = onDirtyChange;
+    onSaveRef.current = onSave;
+    onExportRef.current = onExport;
+    onHistoryChangeRef.current = props_onHistoryChange;
+  }, [onChange, onDirtyChange, onSave, onExport, props_onHistoryChange]);
+
+  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) => {
+      // Fire onHistoryChange whenever stack depths change. Independent of
+      // deck identity so undo/redo always emit, even if the resulting deck
+      // happens to be reference-equal (shouldn't, but defensive).
+      const prevHist = prev.history.length;
+      const prevFut = prev.future.length;
+      const nextHist = state.history.length;
+      const nextFut = state.future.length;
+      if (prevHist !== nextHist || prevFut !== nextFut) {
+        onHistoryChangeRef.current?.({
+          canUndo: nextHist > 0,
+          canRedo: nextFut > 0,
+          undoSize: nextHist,
+          redoSize: nextFut,
+        });
+      }
+      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(),
+      canUndo: () => store.getState().canUndo(),
+      canRedo: () => store.getState().canRedo(),
+      getHistorySize: () => {
+        const s = store.getState();
+        return { undo: s.history.length, redo: s.future.length };
+      },
+      endCoalesce: () => store.getState().endCoalesce(),
+      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>
+  );
+}

package/src/compound/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Compound API for Slidewise. Use these primitives when you want to compose
+ * the editor — replacing, wrapping, or omitting any region. Hosts that just
+ * want the default editor can keep using `<SlidewiseEditor>`, which is a
+ * thin wrapper rendering this same tree:
+ *
+ * ```tsx
+ * <Slidewise.Root deck={deck} onChange={…} onSave={…}>
+ *   <Slidewise.TopBar />
+ *   <Slidewise.Body>
+ *     <Slidewise.SlideRail />
+ *     <Slidewise.CanvasFrame>
+ *       <Slidewise.Canvas />
+ *       <Slidewise.BottomToolbar />
+ *     </Slidewise.CanvasFrame>
+ *   </Slidewise.Body>
+ * </Slidewise.Root>
+ * ```
+ *
+ * Use the namespace import to keep call sites tidy:
+ *
+ * ```tsx
+ * import * as Slidewise from "@textcortex/slidewise";
+ * ```
+ */
+export {
+  Root,
+  type SlidewiseRootProps,
+  type SlidewiseRootHandle,
+  type HistoryState,
+} from "./SlidewiseRoot";
+export {
+  TopBar,
+  SlideRail,
+  Canvas,
+  BottomToolbar,
+  RightPanel,
+  Body,
+  CanvasFrame,
+  type RegionProps,
+} from "./parts";
+export {
+  useHostCallbacks,
+  type SlidewiseHostCallbacks,
+} from "./HostContext";
+export {
+  IconProvider,
+  useIcons,
+  type SlidewiseIcons,
+} from "./IconContext";
+export { ReadOnlyProvider, useReadOnly } from "./ReadOnlyContext";

package/src/compound/parts.tsx

@@ -0,0 +1,160 @@
+import type { CSSProperties, ReactNode } from "react";
+import { TopBar as TopBarInternal } from "@/components/editor/TopBar";
+import { SlideRail as SlideRailInternal } from "@/components/editor/SlideRail";
+import { Canvas as CanvasInternal } from "@/components/editor/Canvas";
+import { BottomToolbar as BottomToolbarInternal } from "@/components/editor/BottomToolbar";
+import { useHostCallbacks } from "./HostContext";
+
+/**
+ * Region-level compound parts. Each consumes the editor store via context,
+ * so any part can be omitted, wrapped, or replaced. None of these accept
+ * deck/onChange/onSave props — those live on `<Slidewise.Root>`.
+ */
+
+export interface RegionProps {
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * The default top bar (title input, undo/redo, save, play, theme toggle,
+ * export). Reads host callbacks from context, so the Save and Export
+ * buttons fire the host's `onSave` / `onExport` from `<Slidewise.Root>`.
+ *
+ * Omit it from the tree to hide the whole bar; or render your own toolbar
+ * alongside `<Slidewise.Canvas>` for full control.
+ */
+export function TopBar(_props: RegionProps = {}) {
+  const { onSave, onExport } = useHostCallbacks();
+  return <TopBarInternal onSave={onSave} onExport={onExport} />;
+}
+
+/**
+ * Left-side slide thumbnail rail with add/duplicate/delete.
+ */
+export function SlideRail(_props: RegionProps = {}) {
+  return <SlideRailInternal />;
+}
+
+/**
+ * The main editing canvas. This is the only part that's effectively required
+ * — without it the editor renders nothing visible. Layout-wise it expects
+ * a flex container that gives it `flex: 1`; the default layout takes care of
+ * this when you also render `<Slidewise.Body>`.
+ */
+export function Canvas(_props: RegionProps = {}) {
+  return <CanvasInternal />;
+}
+
+/**
+ * Floating bottom toolbar with the active-tool selector (select / text /
+ * shape / etc.). Optional — omit it if your host has its own tool surface.
+ */
+export function BottomToolbar(_props: RegionProps = {}) {
+  return <BottomToolbarInternal />;
+}
+
+/**
+ * Right-side properties panel. The default editor doesn't ship a built-in
+ * inspector yet — this slot is rendered for hosts that want to inject their
+ * own (AI suggestions, comments, element properties, etc.). Pass `children`
+ * to fill the slot; the part handles the layout (fixed width column, themed
+ * surface) so injected content blends with the rest of the editor.
+ */
+export function RightPanel({
+  className,
+  style,
+  children,
+  width = 320,
+}: RegionProps & { children?: ReactNode; width?: number | string }) {
+  if (!children) return null;
+  return (
+    <aside
+      className={
+        className
+          ? `slidewise-right-panel ${className}`
+          : "slidewise-right-panel"
+      }
+      style={{
+        width,
+        flexShrink: 0,
+        height: "100%",
+        background: "var(--rail-bg)",
+        borderLeft: "1px solid var(--border)",
+        boxShadow: "var(--rail-shadow)",
+        overflow: "auto",
+        ...style,
+      }}
+    >
+      {children}
+    </aside>
+  );
+}
+
+/**
+ * Default body layout — slide rail + canvas + (optional) right panel side
+ * by side. Most hosts compose this manually:
+ *
+ * ```tsx
+ * <Slidewise.Root deck={deck}>
+ *   <Slidewise.TopBar />
+ *   <Slidewise.Body>
+ *     <Slidewise.SlideRail />
+ *     <Slidewise.Canvas />
+ *     <Slidewise.BottomToolbar />
+ *   </Slidewise.Body>
+ * </Slidewise.Root>
+ * ```
+ *
+ * Provided as a convenience so most hosts don't have to repeat the flex
+ * row + relative positioning that BottomToolbar's anchor expects.
+ */
+export function Body({ className, style, children }: RegionProps & { children?: ReactNode }) {
+  return (
+    <div
+      className={
+        className ? `slidewise-body ${className}` : "slidewise-body"
+      }
+      style={{
+        flex: 1,
+        display: "flex",
+        overflow: "hidden",
+        position: "relative",
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * Wraps `<Slidewise.Canvas>` with the relative positioning that
+ * `<Slidewise.BottomToolbar>` anchors to. Use it when you want the toolbar
+ * to float over the canvas — which is what the default editor does:
+ *
+ * ```tsx
+ * <Slidewise.CanvasFrame>
+ *   <Slidewise.Canvas />
+ *   <Slidewise.BottomToolbar />
+ * </Slidewise.CanvasFrame>
+ * ```
+ */
+export function CanvasFrame({
+  className,
+  style,
+  children,
+}: RegionProps & { children?: ReactNode }) {
+  return (
+    <div
+      className={
+        className
+          ? `slidewise-canvas-frame ${className}`
+          : "slidewise-canvas-frame"
+      }
+      style={{ flex: 1, display: "flex", position: "relative", ...style }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/css.d.ts

@@ -0,0 +1,4 @@
+// Allow side-effect imports of plain CSS files from TypeScript.
+// The library bundles its CSS into dist/slidewise.css; consumers import
+// "@textcortex/slidewise/style.css" separately (see package.json exports).
+declare module "*.css";

package/src/index.ts

@@ -10,6 +10,49 @@ export {
   type SlidewiseFileEditorApi,
 } from "./SlidewiseFileEditor";
 
+/**
+ * Compound API. Use the namespace import idiom for the full editor:
+ *
+ * ```tsx
+ * import * as Slidewise from "@textcortex/slidewise";
+ *
+ * <Slidewise.Root deck={deck} onChange={...}>
+ *   <Slidewise.TopBar />
+ *   <Slidewise.Body>
+ *     <Slidewise.SlideRail />
+ *     <Slidewise.CanvasFrame>
+ *       <Slidewise.Canvas />
+ *       <Slidewise.BottomToolbar />
+ *     </Slidewise.CanvasFrame>
+ *   </Slidewise.Body>
+ * </Slidewise.Root>
+ * ```
+ *
+ * Each region reads the editor store via context, so you can replace, wrap,
+ * or omit any one. `<Slidewise.RightPanel>` is provided so hosts can inject
+ * their own panel content (AI suggestions, comments, etc.) inside the same
+ * themed surface.
+ */
+export {
+  Root,
+  TopBar,
+  SlideRail,
+  Canvas,
+  BottomToolbar,
+  RightPanel,
+  Body,
+  CanvasFrame,
+  useHostCallbacks,
+  useIcons,
+  useReadOnly,
+  type SlidewiseRootProps,
+  type SlidewiseRootHandle,
+  type HistoryState,
+  type SlidewiseHostCallbacks,
+  type SlidewiseIcons,
+  type RegionProps,
+} from "./compound";
+
 export { parsePptx, serializeDeck } from "./lib/pptx";
 export type { ParseDiagnostics, ParseResult } from "./lib/pptx/types";