@textcortex/slidewise 1.3.0 → 1.5.0

package/package.json

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

package/src/SlidewiseEditor.css

@@ -34,6 +34,34 @@
   --slidewise-bar-bg: var(--app-bg);
   --slidewise-accent: var(--accent);
 
+  /* Per-surface background tokens. Map onto internal vars by default so
+     existing theme styling is preserved. Hosts override any subset (or
+     pass the `surfaces` prop on <Slidewise.Root>) to retint individual
+     regions independently. */
+  --slidewise-bg-app: var(--app-bg);
+  --slidewise-bg-topbar: var(--app-bg);
+  --slidewise-bg-rail: var(--rail-bg);
+  --slidewise-bg-rail-item: transparent;
+  --slidewise-bg-rail-item-active: var(--accent-soft);
+  --slidewise-bg-canvas-frame: transparent;
+  --slidewise-bg-canvas-from: var(--canvas-bg-from);
+  --slidewise-bg-canvas-to: var(--canvas-bg-to);
+  --slidewise-bg-bottom-toolbar: var(--toolbar-bg);
+  --slidewise-bg-right-panel: var(--rail-bg);
+  --slidewise-bg-menu: var(--menu-bg);
+  --slidewise-bg-tooltip: var(--menu-bg);
+  --slidewise-bg-popover: var(--menu-bg);
+  --slidewise-bg-dialog: var(--menu-bg);
+  --slidewise-bg-slide: #ffffff;
+  --slidewise-bg-selection: var(--accent-soft);
+  --slidewise-bg-hover: var(--hover);
+  --slidewise-bg-active: var(--active);
+  --slidewise-bg-input: var(--input-bg);
+  --slidewise-bg-button: transparent;
+  --slidewise-bg-button-hover: var(--hover);
+  --slidewise-bg-pill: var(--smart-grad);
+  --slidewise-bg-unsaved-badge: rgba(232, 80, 76, 0.12);
+
   /* Layout backgrounds */
   --app-bg: #ffffff;
   --rail-bg: #fafafb;
@@ -126,6 +154,12 @@
   --canvas-bg-from: #181c38;
   --canvas-bg-to: #0c1027;
 
+  /* Dark-mode overrides for the public --slidewise-bg-* surface tokens.
+     Hosts can still override any one of these from a higher specificity
+     selector or via the `surfaces` prop. */
+  --slidewise-bg-slide: #ffffff;
+  --slidewise-bg-unsaved-badge: rgba(232, 80, 76, 0.18);
+
   /* Charcoal-purple surface kit from textcortex/platform#7428 — neutral
      dark base, faint inset highlight, layered shadow that lifts to a
      subtle plum tint on hover. */

package/src/SlidewiseEditor.tsx

@@ -4,6 +4,7 @@ import {
   type SlidewiseRootHandle,
   type SlidewiseRootProps,
   type HistoryState,
+  type SelectionSnapshot,
 } from "./compound/SlidewiseRoot";
 import { TopBar } from "./compound/topbar";
 import {
@@ -14,6 +15,8 @@ import {
   CanvasFrame,
 } from "./compound/parts";
 import type { SlidewiseIcons } from "./compound/IconContext";
+import type { SlidewiseLabels } from "./compound/LabelsContext";
+import type { SlidewiseSurfaces } from "./compound/SurfacesContext";
 import type { Deck } from "@/lib/types";
 import "./SlidewiseEditor.css";
 
@@ -40,6 +43,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. */
@@ -59,6 +74,17 @@ export interface SlidewiseEditorProps {
    * bundled lucide-react icons.
    */
   icons?: SlidewiseIcons;
+  /**
+   * User-visible string overrides for i18n. Pass any subset; missing
+   * entries fall back to English defaults.
+   */
+  labels?: SlidewiseLabels;
+  /**
+   * Per-surface background overrides, equivalent to setting the
+   * `--slidewise-bg-*` CSS variables. See `SlidewiseSurfaces` for the full
+   * list of keys.
+   */
+  surfaces?: SlidewiseSurfaces;
   /** Extra class names appended to the editor root. */
   className?: string;
   /** Inline style applied to the editor root. */
@@ -97,6 +123,12 @@ export const SlidewiseEditor = forwardRef<
     onExport,
     onDirtyChange,
     onHistoryChange,
+    onActiveSlideChange,
+    onSelectionChange,
+    onZoomChange,
+    onSaveStart,
+    onSaveSuccess,
+    onSaveError,
     readOnly,
     theme,
     initialSlideId,
@@ -104,6 +136,8 @@ export const SlidewiseEditor = forwardRef<
     showBottomToolbar = true,
     fontFamily,
     icons,
+    labels,
+    surfaces,
     className,
     style,
   },
@@ -116,11 +150,19 @@ export const SlidewiseEditor = forwardRef<
     onExport,
     onDirtyChange,
     onHistoryChange,
+    onActiveSlideChange,
+    onSelectionChange,
+    onZoomChange,
+    onSaveStart,
+    onSaveSuccess,
+    onSaveError,
     readOnly,
     theme,
     initialSlideId,
     fontFamily,
     icons,
+    labels,
+    surfaces,
     className,
     style,
   };

package/src/SlidewiseFileEditor.tsx

@@ -10,7 +10,10 @@ 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 { SlidewiseLabels } from "./compound/LabelsContext";
+import type { SlidewiseSurfaces } from "./compound/SurfacesContext";
+import { DEFAULT_LABELS } from "./compound/LabelsContext";
+import type { HistoryState, SelectionSnapshot } from "./compound/SlidewiseRoot";
 
 export interface SlidewiseFileEditorProps {
   /**
@@ -55,6 +58,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
@@ -79,6 +94,17 @@ export interface SlidewiseFileEditorProps {
    * editor's chrome with your own icon set.
    */
   icons?: SlidewiseIcons;
+  /**
+   * User-visible string overrides for i18n. Pass any subset; missing
+   * entries fall back to English defaults. The "Unsaved changes" badge
+   * and the loading / load-error messages also key off this table.
+   */
+  labels?: SlidewiseLabels;
+  /**
+   * Per-surface background overrides; equivalent to setting the
+   * `--slidewise-bg-*` CSS variables.
+   */
+  surfaces?: SlidewiseSurfaces;
   className?: string;
   style?: CSSProperties;
   /**
@@ -114,6 +140,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,12 +195,20 @@ export const SlidewiseFileEditor = forwardRef<
     onDirtyChange,
     onLoadError,
     onHistoryChange,
+    onActiveSlideChange,
+    onSelectionChange,
+    onZoomChange,
+    onSaveStart,
+    onSaveSuccess,
+    onSaveError,
     theme,
     initialSlideId,
     showTopBar,
     showBottomToolbar,
     fontFamily,
     icons,
+    labels,
+    surfaces,
     className,
     style,
     parse = parsePptx,
@@ -211,6 +276,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 +323,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
@@ -253,15 +353,18 @@ export const SlidewiseFileEditor = forwardRef<
   if (state.status === "loading") {
     return (
       <div style={{ ...frameStyle, ...style }} className={className}>
-        <div style={messageStyle}>Loading…</div>
+        <div style={messageStyle}>
+          {labels?.fileLoading ?? DEFAULT_LABELS.fileLoading}
+        </div>
       </div>
     );
   }
   if (state.status === "error") {
+    const fmt = labels?.fileLoadError ?? DEFAULT_LABELS.fileLoadError;
     return (
       <div style={{ ...frameStyle, ...style }} className={className}>
         <div style={{ ...messageStyle, color: "#E8504C" }}>
-          Could not open file: {state.error.message}
+          {fmt(state.error.message)}
         </div>
       </div>
     );
@@ -279,6 +382,8 @@ export const SlidewiseFileEditor = forwardRef<
         showBottomToolbar={showBottomToolbar}
         fontFamily={fontFamily}
         icons={icons}
+        labels={labels}
+        surfaces={surfaces}
         onChange={(next) => {
           onChangeRef.current?.(next);
         }}
@@ -287,12 +392,22 @@ 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);
         }}
       />
-      {dirty && <UnsavedBadge />}
+      {dirty && (
+        <UnsavedBadge
+          label={labels?.unsavedBadge ?? DEFAULT_LABELS.unsavedBadge}
+        />
+      )}
     </div>
   );
 });
@@ -313,7 +428,7 @@ const messageStyle: CSSProperties = {
   color: "#5b6178",
 };
 
-function UnsavedBadge() {
+function UnsavedBadge({ label }: { label: string }) {
   return (
     <div
       style={{
@@ -321,7 +436,8 @@ function UnsavedBadge() {
         top: 12,
         right: 12,
         padding: "4px 10px",
-        background: "rgba(232, 80, 76, 0.12)",
+        background:
+          "var(--slidewise-bg-unsaved-badge, rgba(232, 80, 76, 0.12))",
         color: "#E8504C",
         borderRadius: 999,
         fontFamily: "Inter, system-ui, sans-serif",
@@ -332,7 +448,7 @@ function UnsavedBadge() {
         pointerEvents: "none",
       }}
     >
-      Unsaved changes
+      {label}
     </div>
   );
 }

package/src/compound/LabelsContext.tsx

@@ -0,0 +1,121 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+
+/**
+ * Every user-visible string in the editor's chrome. Pass any subset on
+ * `<Slidewise.Root labels={...}>` to localise; missing entries fall back
+ * to the English defaults. Use this prop together with `icons` to fully
+ * skin Slidewise for non-English deployments.
+ *
+ * Single-string entries are used both as the button's visible label AND
+ * as its `aria-label`. Where the two need to diverge (the Save button
+ * cycles through three states; the theme toggle shows different labels
+ * per theme), nested keys are provided.
+ */
+export interface SlidewiseLabels {
+  // TopBar buttons (visible text)
+  save?: { idle?: string; saving?: string; saved?: string };
+  play?: string;
+  stop?: string;
+  export?: string;
+  undo?: string;
+  redo?: string;
+  themeToggle?: { toDark?: string; toLight?: string };
+
+  // Pills + status indicators
+  smart?: string;
+  unsavedBadge?: string;
+
+  // Inputs
+  titleAriaLabel?: string;
+
+  // SlideRail (reserved for the future SlideRail compound subparts)
+  addSlide?: string;
+  duplicateSlide?: string;
+  deleteSlide?: string;
+
+  // Errors
+  fileLoadError?: (msg: string) => string;
+  fileLoading?: string;
+}
+
+/**
+ * The fully-resolved label table — every key present, no optionals. Internal
+ * components read this directly so they never have to check for undefined.
+ */
+export interface ResolvedLabels {
+  save: { idle: string; saving: string; saved: string };
+  play: string;
+  stop: string;
+  export: string;
+  undo: string;
+  redo: string;
+  themeToggle: { toDark: string; toLight: string };
+  smart: string;
+  unsavedBadge: string;
+  titleAriaLabel: string;
+  addSlide: string;
+  duplicateSlide: string;
+  deleteSlide: string;
+  fileLoadError: (msg: string) => string;
+  fileLoading: string;
+}
+
+export const DEFAULT_LABELS: ResolvedLabels = {
+  save: { idle: "Save", saving: "Saving…", saved: "Saved" },
+  play: "Play",
+  stop: "Stop",
+  export: "Export",
+  undo: "Undo",
+  redo: "Redo",
+  themeToggle: { toDark: "Dark mode", toLight: "Light mode" },
+  smart: "Smart",
+  unsavedBadge: "Unsaved changes",
+  titleAriaLabel: "Deck title",
+  addSlide: "Add slide",
+  duplicateSlide: "Duplicate slide",
+  deleteSlide: "Delete slide",
+  fileLoadError: (msg) => `Could not open file: ${msg}`,
+  fileLoading: "Loading…",
+};
+
+function mergeLabels(
+  overrides: SlidewiseLabels | undefined
+): ResolvedLabels {
+  if (!overrides) return DEFAULT_LABELS;
+  return {
+    save: { ...DEFAULT_LABELS.save, ...overrides.save },
+    play: overrides.play ?? DEFAULT_LABELS.play,
+    stop: overrides.stop ?? DEFAULT_LABELS.stop,
+    export: overrides.export ?? DEFAULT_LABELS.export,
+    undo: overrides.undo ?? DEFAULT_LABELS.undo,
+    redo: overrides.redo ?? DEFAULT_LABELS.redo,
+    themeToggle: { ...DEFAULT_LABELS.themeToggle, ...overrides.themeToggle },
+    smart: overrides.smart ?? DEFAULT_LABELS.smart,
+    unsavedBadge: overrides.unsavedBadge ?? DEFAULT_LABELS.unsavedBadge,
+    titleAriaLabel: overrides.titleAriaLabel ?? DEFAULT_LABELS.titleAriaLabel,
+    addSlide: overrides.addSlide ?? DEFAULT_LABELS.addSlide,
+    duplicateSlide: overrides.duplicateSlide ?? DEFAULT_LABELS.duplicateSlide,
+    deleteSlide: overrides.deleteSlide ?? DEFAULT_LABELS.deleteSlide,
+    fileLoadError: overrides.fileLoadError ?? DEFAULT_LABELS.fileLoadError,
+    fileLoading: overrides.fileLoading ?? DEFAULT_LABELS.fileLoading,
+  };
+}
+
+const LabelsContext = createContext<ResolvedLabels>(DEFAULT_LABELS);
+
+export function LabelsProvider({
+  labels,
+  children,
+}: {
+  labels: SlidewiseLabels | undefined;
+  children: ReactNode;
+}) {
+  const resolved = useMemo(() => mergeLabels(labels), [labels]);
+  return (
+    <LabelsContext.Provider value={resolved}>{children}</LabelsContext.Provider>
+  );
+}
+
+export function useLabels(): ResolvedLabels {
+  return useContext(LabelsContext);
+}