@textcortex/slidewise 1.2.0 → 1.3.0

package/package.json

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

package/src/SlidewiseEditor.tsx

@@ -5,8 +5,8 @@ import {
   type SlidewiseRootProps,
   type HistoryState,
 } from "./compound/SlidewiseRoot";
+import { TopBar } from "./compound/topbar";
 import {
-  TopBar,
   SlideRail,
   Canvas,
   BottomToolbar,

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 {
   /**
@@ -137,6 +139,7 @@ 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);
@@ -176,6 +179,7 @@ function RootInner({
       savedDeckRef.current = deck;
       if (dirtyRef.current) {
         dirtyRef.current = false;
+        setDirty(false);
         onDirtyChangeRef.current?.(false);
       }
     }
@@ -208,6 +212,7 @@ function RootInner({
       const nextDirty = state.deck !== savedDeckRef.current;
       if (nextDirty !== dirtyRef.current) {
         dirtyRef.current = nextDirty;
+        setDirty(nextDirty);
         onDirtyChangeRef.current?.(nextDirty);
       }
       ensureGoogleFontsLoaded(instanceId, collectFontFamilies(state.deck));
@@ -263,15 +268,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>
   );

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,
+  }));
+}

package/src/compound/index.ts

@@ -5,7 +5,7 @@
  * thin wrapper rendering this same tree:
  *
  * ```tsx
- * <Slidewise.Root deck={deck} onChange={…} onSave={…}>
+ * <Slidewise.Root deck={deck} onChange={...} onSave={...}>
  *   <Slidewise.TopBar />
  *   <Slidewise.Body>
  *     <Slidewise.SlideRail />
@@ -17,10 +17,19 @@
  * </Slidewise.Root>
  * ```
  *
- * Use the namespace import to keep call sites tidy:
+ * For full control over the top bar (host buttons mixed in, subparts
+ * reordered, individual buttons skinned), drop down to its subparts:
  *
  * ```tsx
- * import * as Slidewise from "@textcortex/slidewise";
+ * <Slidewise.TopBar.Root>
+ *   <MyExitButton />
+ *   <Slidewise.TopBar.Spacer />
+ *   <Slidewise.TopBar.Group>
+ *     <Slidewise.TopBar.Undo />
+ *     <Slidewise.TopBar.Redo />
+ *   </Slidewise.TopBar.Group>
+ *   <Slidewise.TopBar.Save />
+ * </Slidewise.TopBar.Root>
  * ```
  */
 export {
@@ -30,7 +39,6 @@ export {
   type HistoryState,
 } from "./SlidewiseRoot";
 export {
-  TopBar,
   SlideRail,
   Canvas,
   BottomToolbar,
@@ -39,6 +47,21 @@ export {
   CanvasFrame,
   type RegionProps,
 } from "./parts";
+
+export { TopBar, type TopBarProps, type TopBarSlotId } from "./topbar";
+export type {
+  TopBarRootProps,
+  TopBarTitleProps,
+  TopBarUndoProps,
+  TopBarRedoProps,
+  TopBarSaveProps,
+  TopBarPlayProps,
+  TopBarThemeToggleProps,
+  TopBarExportProps,
+  TopBarSpacerProps,
+  TopBarGroupProps,
+} from "./topbar";
+
 export {
   useHostCallbacks,
   type SlidewiseHostCallbacks,
@@ -49,3 +72,22 @@ export {
   type SlidewiseIcons,
 } from "./IconContext";
 export { ReadOnlyProvider, useReadOnly } from "./ReadOnlyContext";
+export { DirtyProvider, useDirty } from "./DirtyContext";
+
+/**
+ * Store hooks. Use these from host components anywhere under
+ * `<Slidewise.Root>` to read or write editor state without prop drilling.
+ */
+export {
+  useEditor,
+  useEditorStore,
+  useSlides,
+  useActiveSlide,
+  useActiveSlideId,
+  useSelection,
+  useSelectedElements,
+  useTheme,
+  useZoom,
+  usePlaying,
+  useHistory,
+} from "./hooks";

package/src/compound/parts.tsx

@@ -1,14 +1,16 @@
 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>`.
+ *
+ * Note: `<Slidewise.TopBar>` is defined separately in `./topbar/` because
+ * it itself decomposes into subparts (`TopBar.Root`, `TopBar.Title`,
+ * `TopBar.Undo`, etc.) and ships a `hide` prop for per-button removal.
  */
 
 export interface RegionProps {
@@ -16,19 +18,6 @@ export interface RegionProps {
   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.
  */

package/src/compound/topbar/Export.tsx

@@ -0,0 +1,65 @@
+import type { CSSProperties, ReactNode } from "react";
+import { Download } from "lucide-react";
+import { useEditorStore } from "@/lib/StoreProvider";
+import { useHostCallbacks } from "../HostContext";
+import { useIcons } from "../IconContext";
+import { primaryBtnStyle, primaryHoverHandlers } from "./styles";
+
+/**
+ * Export button. Calls the host's `onExport` (from `<Slidewise.Root
+ * onExport>`) with the current deck. If no host callback is registered,
+ * falls back to downloading a `.slidewise.json` of the deck.
+ *
+ * Visually emphasized vs the chrome buttons — uses `--primary-bg` so hosts
+ * retheming the primary surface get a consistent affordance.
+ */
+export interface TopBarExportProps {
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel?: string;
+  label?: string;
+  children?: ReactNode;
+}
+
+export function Export({
+  className,
+  style,
+  ariaLabel = "Export",
+  label = "Export",
+  children,
+}: TopBarExportProps = {}) {
+  const store = useEditorStore();
+  const { onExport: onExportHost } = useHostCallbacks();
+  const icons = useIcons();
+
+  const onClick = () => {
+    const deck = store.getState().deck;
+    if (onExportHost) {
+      onExportHost(deck);
+      return;
+    }
+    const blob = new Blob([JSON.stringify(deck, null, 2)], {
+      type: "application/json",
+    });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = `${(deck.title || "deck").replace(/[^a-z0-9-_]+/gi, "-")}.slidewise.json`;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <button
+      type="button"
+      className={className}
+      aria-label={ariaLabel}
+      onClick={onClick}
+      style={{ ...primaryBtnStyle(), ...style }}
+      {...primaryHoverHandlers()}
+    >
+      {children ?? icons.export ?? <Download size={14} />}
+      {label}
+    </button>
+  );
+}

package/src/compound/topbar/Group.tsx

@@ -0,0 +1,36 @@
+import type { CSSProperties, PropsWithChildren } from "react";
+
+/**
+ * Visual cluster wrapper for a related set of buttons (e.g. Undo + Redo).
+ * Just a flex row with a small inner gap — keeps clusters visually together
+ * separate from the bar's default 10px gap.
+ *
+ * ```tsx
+ * <Slidewise.TopBar.Group>
+ *   <Slidewise.TopBar.Undo />
+ *   <Slidewise.TopBar.Redo />
+ * </Slidewise.TopBar.Group>
+ * ```
+ */
+export interface TopBarGroupProps {
+  className?: string;
+  style?: CSSProperties;
+  /** Gap between children inside the group. Default 2px. */
+  gap?: number;
+}
+
+export function Group({
+  className,
+  style,
+  gap = 2,
+  children,
+}: PropsWithChildren<TopBarGroupProps>) {
+  return (
+    <div
+      className={className}
+      style={{ display: "flex", alignItems: "center", gap, ...style }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/compound/topbar/Play.tsx

@@ -0,0 +1,42 @@
+import type { CSSProperties, ReactNode } from "react";
+import { Play as PlayIcon } from "lucide-react";
+import { useEditor } from "@/lib/StoreProvider";
+import { useIcons } from "../IconContext";
+import { chromeBtnStyle, hoverHandlers } from "./styles";
+
+/**
+ * Play button. Enters slideshow / play mode. Always rendered (read-only
+ * viewers should still be able to present).
+ */
+export interface TopBarPlayProps {
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel?: string;
+  label?: string;
+  children?: ReactNode;
+}
+
+export function Play({
+  className,
+  style,
+  ariaLabel = "Play",
+  label = "Play",
+  children,
+}: TopBarPlayProps = {}) {
+  const play = useEditor((s) => s.play);
+  const icons = useIcons();
+
+  return (
+    <button
+      type="button"
+      className={className}
+      aria-label={ariaLabel}
+      onClick={play}
+      style={{ ...chromeBtnStyle(), ...style }}
+      {...hoverHandlers()}
+    >
+      {children ?? icons.play ?? <PlayIcon size={14} />}
+      {label}
+    </button>
+  );
+}

package/src/compound/topbar/Redo.tsx

@@ -0,0 +1,50 @@
+import type { CSSProperties, ReactNode } from "react";
+import { Redo2 } from "lucide-react";
+import { useEditor } from "@/lib/StoreProvider";
+import { useIcons } from "../IconContext";
+import { useReadOnly } from "../ReadOnlyContext";
+import { iconBtnStyle, hoverHandlers } from "./styles";
+
+/**
+ * Redo button. Calls `store.redo()`. Hidden in read-only mode. Disables
+ * itself when the redo stack is empty.
+ */
+export interface TopBarRedoProps {
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel?: string;
+  children?: ReactNode;
+}
+
+export function Redo({
+  className,
+  style,
+  ariaLabel = "Redo",
+  children,
+}: TopBarRedoProps = {}) {
+  const redo = useEditor((s) => s.redo);
+  const canRedo = useEditor((s) => s.future.length > 0);
+  const icons = useIcons();
+  const readOnly = useReadOnly();
+  if (readOnly) return null;
+
+  return (
+    <button
+      type="button"
+      className={className}
+      title={ariaLabel}
+      aria-label={ariaLabel}
+      disabled={!canRedo}
+      onClick={redo}
+      style={{
+        ...iconBtnStyle(),
+        cursor: canRedo ? "pointer" : "default",
+        opacity: canRedo ? 1 : 0.4,
+        ...style,
+      }}
+      {...hoverHandlers()}
+    >
+      {children ?? icons.redo ?? <Redo2 size={16} />}
+    </button>
+  );
+}

package/src/compound/topbar/Root.tsx

@@ -0,0 +1,51 @@
+import type { CSSProperties, PropsWithChildren } from "react";
+
+/**
+ * Container for the TopBar subparts. Owns the bar's height, padding, theme
+ * background, and shadow. Hosts replace this when they want a different
+ * shell shape (taller bar, different alignment, etc.); otherwise just render
+ * subparts inside it.
+ *
+ * ```tsx
+ * <Slidewise.TopBar.Root>
+ *   <Slidewise.TopBar.Title />
+ *   <Slidewise.TopBar.Spacer />
+ *   <Slidewise.TopBar.Save />
+ * </Slidewise.TopBar.Root>
+ * ```
+ */
+export interface TopBarRootProps {
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Root({
+  className,
+  style,
+  children,
+}: PropsWithChildren<TopBarRootProps>) {
+  return (
+    <div
+      className={
+        className ? `slidewise-topbar ${className}` : "slidewise-topbar"
+      }
+      style={{
+        height: 56,
+        display: "flex",
+        alignItems: "center",
+        padding: "0 14px",
+        gap: 10,
+        background: "var(--slidewise-bar-bg, var(--app-bg))",
+        borderBottom: "1px solid var(--border)",
+        boxShadow: "var(--topbar-shadow)",
+        fontFamily: "Inter, system-ui, sans-serif",
+        position: "relative",
+        zIndex: 10,
+        color: "var(--ink)",
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/compound/topbar/Save.tsx

@@ -0,0 +1,80 @@
+import { useState, type CSSProperties, type ReactNode } from "react";
+import { Save as SaveIcon } from "lucide-react";
+import { useEditorStore } from "@/lib/StoreProvider";
+import { useHostCallbacks } from "../HostContext";
+import { useIcons } from "../IconContext";
+import { useReadOnly } from "../ReadOnlyContext";
+import { chromeBtnStyle, hoverHandlers } from "./styles";
+
+/**
+ * Save button. Calls the host's `onSave` (from `<Slidewise.Root onSave>`)
+ * with the current deck. If no host callback is registered, falls back to
+ * `localStorage.setItem("slidewise-deck", ...)` so the dev shell works
+ * without wiring.
+ *
+ * Cycles through idle → saving → saved labels around the click; hosts that
+ * want their own loading affordance render their own button using
+ * `useHostCallbacks().onSave` directly.
+ */
+export interface TopBarSaveProps {
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel?: string;
+  labels?: { idle?: string; saving?: string; saved?: string };
+  children?: ReactNode;
+}
+
+export function Save({
+  className,
+  style,
+  ariaLabel = "Save",
+  labels,
+  children,
+}: TopBarSaveProps = {}) {
+  const store = useEditorStore();
+  const { onSave: onSaveHost } = useHostCallbacks();
+  const icons = useIcons();
+  const readOnly = useReadOnly();
+  const [phase, setPhase] = useState<"idle" | "saving" | "saved">("idle");
+
+  if (readOnly) return null;
+
+  const onClick = async () => {
+    setPhase("saving");
+    const deck = store.getState().deck;
+    try {
+      if (onSaveHost) {
+        await onSaveHost(deck);
+      } else {
+        try {
+          localStorage.setItem("slidewise-deck", JSON.stringify(deck));
+        } catch {}
+      }
+      setTimeout(() => setPhase("saved"), 320);
+      setTimeout(() => setPhase("idle"), 1600);
+    } catch {
+      setPhase("idle");
+    }
+  };
+
+  const text =
+    phase === "saving"
+      ? (labels?.saving ?? "Saving…")
+      : phase === "saved"
+        ? (labels?.saved ?? "Saved")
+        : (labels?.idle ?? "Save");
+
+  return (
+    <button
+      type="button"
+      className={className}
+      aria-label={ariaLabel}
+      onClick={onClick}
+      style={{ ...chromeBtnStyle(), ...style }}
+      {...hoverHandlers()}
+    >
+      {children ?? icons.save ?? <SaveIcon size={14} />}
+      {text}
+    </button>
+  );
+}

package/src/compound/topbar/Spacer.tsx

@@ -0,0 +1,27 @@
+import type { CSSProperties } from "react";
+
+/**
+ * Pushes subsequent subparts to the far edge of `<TopBar.Root>`.
+ *
+ * ```tsx
+ * <Slidewise.TopBar.Root>
+ *   <MyExitButton />
+ *   <Slidewise.TopBar.Spacer />
+ *   <Slidewise.TopBar.Save />
+ * </Slidewise.TopBar.Root>
+ * ```
+ */
+export interface TopBarSpacerProps {
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Spacer({ className, style }: TopBarSpacerProps = {}) {
+  return (
+    <div
+      className={className}
+      aria-hidden="true"
+      style={{ flex: 1, minWidth: 0, ...style }}
+    />
+  );
+}