@textcortex/slidewise 1.6.0 → 1.7.0

package/package.json

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

package/src/SlidewiseEditor.tsx

@@ -7,8 +7,8 @@ import {
   type SelectionSnapshot,
 } from "./compound/SlidewiseRoot";
 import { TopBar } from "./compound/topbar";
+import { SlideRail } from "./compound/sliderail";
 import {
-  SlideRail,
   Canvas,
   BottomToolbar,
   Body,

package/src/compound/index.ts

@@ -40,7 +40,6 @@ export {
   type SelectionSnapshot,
 } from "./SlidewiseRoot";
 export {
-  SlideRail,
   Canvas,
   BottomToolbar,
   RightPanel,
@@ -50,6 +49,19 @@ export {
 } from "./parts";
 
 export { TopBar, type TopBarProps, type TopBarSlotId } from "./topbar";
+export {
+  SlideRail,
+  useSlideRailItem,
+  type SlideRailProps,
+  type SlideRailRootProps,
+  type SlideRailHeaderProps,
+  type SlideRailListProps,
+  type SlideRailItemProps,
+  type SlideRailThumbnailProps,
+  type SlideRailNumberProps,
+  type SlideRailAddButtonProps,
+  type SlideRailItemContextValue,
+} from "./sliderail";
 export type {
   TopBarRootProps,
   TopBarTitleProps,

package/src/compound/parts.tsx

@@ -1,5 +1,4 @@
 import type { CSSProperties, ReactNode } from "react";
-import { SlideRail as SlideRailInternal } from "@/components/editor/SlideRail";
 import { Canvas as CanvasInternal } from "@/components/editor/Canvas";
 import { BottomToolbar as BottomToolbarInternal } from "@/components/editor/BottomToolbar";
 
@@ -8,9 +7,10 @@ import { BottomToolbar as BottomToolbarInternal } from "@/components/editor/Bott
  * 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.
+ * Note: `<Slidewise.TopBar>` and `<Slidewise.SlideRail>` are defined
+ * separately under `./topbar/` and `./sliderail/` because they decompose
+ * into their own subparts. Both ship a callable component for the default
+ * arrangement plus a namespace of named subparts.
  */
 
 export interface RegionProps {
@@ -18,13 +18,6 @@ export interface RegionProps {
   style?: CSSProperties;
 }
 
-/**
- * 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

package/src/compound/sliderail/AddButton.tsx

@@ -0,0 +1,76 @@
+import type { CSSProperties, ReactNode } from "react";
+import { Plus } from "lucide-react";
+import { useEditor } from "@/lib/StoreProvider";
+import { useReadOnly } from "../ReadOnlyContext";
+import { useLabels } from "../LabelsContext";
+
+/**
+ * Dashed "New Slide" button at the bottom of the rail. Calls
+ * `store.addSlide()`. Hidden in read-only mode.
+ *
+ * Replace with your own button when you need a different shape; the
+ * store action is exported (`useEditor((s) => s.addSlide)`).
+ */
+export interface SlideRailAddButtonProps {
+  className?: string;
+  style?: CSSProperties;
+  ariaLabel?: string;
+  /** Override the visible label. Defaults to `labels.addSlide`. */
+  label?: string;
+  children?: ReactNode;
+}
+
+export function AddButton({
+  className,
+  style,
+  ariaLabel,
+  label,
+  children,
+}: SlideRailAddButtonProps = {}) {
+  const addSlide = useEditor((s) => s.addSlide);
+  const readOnly = useReadOnly();
+  const labels = useLabels();
+  if (readOnly) return null;
+
+  const resolved = label ?? labels.addSlide;
+
+  return (
+    <button
+      type="button"
+      className={className}
+      aria-label={ariaLabel ?? resolved}
+      onClick={() => addSlide()}
+      style={{
+        height: 44,
+        margin: 12,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        gap: 6,
+        background: "var(--slidewise-bg-app, var(--app-bg))",
+        border: "1px dashed var(--border-dashed)",
+        borderRadius: "var(--slidewise-radius, 10px)",
+        color: "var(--ink)",
+        fontSize: 13,
+        fontWeight: 500,
+        cursor: "pointer",
+        transition: "background 120ms, border-color 120ms, color 120ms",
+        fontFamily: "inherit",
+        ...style,
+      }}
+      onMouseEnter={(e) => {
+        e.currentTarget.style.borderColor =
+          "var(--slidewise-accent, var(--accent))";
+        e.currentTarget.style.color =
+          "var(--slidewise-accent, var(--accent))";
+      }}
+      onMouseLeave={(e) => {
+        e.currentTarget.style.borderColor = "var(--border-dashed)";
+        e.currentTarget.style.color = "var(--ink)";
+      }}
+    >
+      {children ?? <Plus size={14} />}
+      {resolved}
+    </button>
+  );
+}

package/src/compound/sliderail/Header.tsx

@@ -0,0 +1,84 @@
+import type { CSSProperties, PropsWithChildren } from "react";
+import { LayoutGrid } from "lucide-react";
+import { useEditor } from "@/lib/StoreProvider";
+
+/**
+ * Default rail header. Renders the grid-view button and a "current / total"
+ * slide counter. Hosts can pass `children` to replace the whole content
+ * while keeping the height + border, or render their own `<header>` instead.
+ *
+ * ```tsx
+ * // Default counter
+ * <Slidewise.SlideRail.Header />
+ *
+ * // Custom content
+ * <Slidewise.SlideRail.Header>
+ *   <strong>{deckTitle}</strong>
+ * </Slidewise.SlideRail.Header>
+ * ```
+ */
+export interface SlideRailHeaderProps {
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Header({
+  className,
+  style,
+  children,
+}: PropsWithChildren<SlideRailHeaderProps>) {
+  const slides = useEditor((s) => s.deck.slides);
+  const currentId = useEditor((s) => s.currentSlideId);
+  const setView = useEditor((s) => s.setView);
+  const idx = slides.findIndex((s) => s.id === currentId);
+
+  return (
+    <div
+      className={className}
+      style={{
+        height: 36,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "space-between",
+        padding: "0 12px",
+        fontSize: 12,
+        color: "var(--ink-muted)",
+        borderBottom: "1px solid var(--border)",
+        ...style,
+      }}
+    >
+      {children ?? (
+        <>
+          <button
+            title="Slide overview"
+            aria-label="Open slide overview"
+            onClick={() => setView("grid")}
+            style={{
+              width: 28,
+              height: 28,
+              border: "none",
+              borderRadius: 6,
+              background: "transparent",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center",
+              color: "var(--ink)",
+              cursor: "pointer",
+            }}
+            onMouseEnter={(e) =>
+              (e.currentTarget.style.background = "var(--hover-strong)")
+            }
+            onMouseLeave={(e) =>
+              (e.currentTarget.style.background = "transparent")
+            }
+          >
+            <LayoutGrid size={14} />
+          </button>
+          <span>
+            {idx + 1} / {slides.length}
+          </span>
+        </>
+      )}
+    </div>
+  );
+}

package/src/compound/sliderail/Item.tsx

@@ -0,0 +1,82 @@
+import type { CSSProperties, PropsWithChildren } from "react";
+import { useEditor } from "@/lib/StoreProvider";
+import type { Slide } from "@/lib/types";
+import { SlideRailItemProvider } from "./ItemContext";
+
+/**
+ * Wraps a single slide in the rail. Provides the slide to descendants via
+ * context (read with `useSlideRailItem`) and wires click → `selectSlide`.
+ *
+ * The default subparts (`Thumbnail`, `Number`) read the slide off the
+ * context, so hosts can rearrange them freely. Host content (e.g. a
+ * three-dots menu, a duplicate button) drops in as additional children.
+ *
+ * ```tsx
+ * <Slidewise.SlideRail.Item slide={slide}>
+ *   <Slidewise.SlideRail.Thumbnail />
+ *   <Slidewise.SlideRail.Number />
+ *   <MyContextMenu slide={slide} />
+ * </Slidewise.SlideRail.Item>
+ * ```
+ */
+export interface SlideRailItemProps {
+  slide: Slide;
+  className?: string;
+  style?: CSSProperties;
+  /**
+   * Override the click handler. The default selects the slide via the
+   * editor store; pass a function here to add host behavior (e.g. open
+   * a context drawer instead of selecting).
+   */
+  onClick?: (slide: Slide) => void;
+}
+
+export function Item({
+  slide,
+  className,
+  style,
+  onClick,
+  children,
+}: PropsWithChildren<SlideRailItemProps>) {
+  const slides = useEditor((s) => s.deck.slides);
+  const currentId = useEditor((s) => s.currentSlideId);
+  const selectSlide = useEditor((s) => s.selectSlide);
+  const index = slides.findIndex((s) => s.id === slide.id);
+  const isCurrent = slide.id === currentId;
+
+  return (
+    <SlideRailItemProvider value={{ slide, index, isCurrent }}>
+      <div
+        className={className}
+        onClick={() => (onClick ? onClick(slide) : selectSlide(slide.id))}
+        role="button"
+        tabIndex={0}
+        aria-current={isCurrent ? "true" : undefined}
+        aria-label={`Open slide ${index + 1}`}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            onClick ? onClick(slide) : selectSlide(slide.id);
+          }
+        }}
+        style={{
+          position: "relative",
+          padding: "0 12px",
+          marginBottom: 14,
+          cursor: "pointer",
+          background:
+            "var(--slidewise-bg-rail-item, transparent)",
+          ...(isCurrent
+            ? {
+                background:
+                  "var(--slidewise-bg-rail-item-active, var(--accent-soft))",
+              }
+            : null),
+          ...style,
+        }}
+      >
+        {children}
+      </div>
+    </SlideRailItemProvider>
+  );
+}

package/src/compound/sliderail/ItemContext.tsx

@@ -0,0 +1,42 @@
+import { createContext, useContext } from "react";
+import type { Slide } from "@/lib/types";
+
+/**
+ * Context handed to descendants of `<SlideRail.Item>` so leaf subparts
+ * (`Thumbnail`, `Number`) and host content can read which slide they're
+ * rendering against without prop drilling.
+ */
+export interface SlideRailItemContextValue {
+  slide: Slide;
+  /** Zero-based position in `deck.slides`. */
+  index: number;
+  /** True when this is the editor's currently-focused slide. */
+  isCurrent: boolean;
+}
+
+const ItemContext = createContext<SlideRailItemContextValue | null>(null);
+
+export function SlideRailItemProvider({
+  value,
+  children,
+}: {
+  value: SlideRailItemContextValue;
+  children: React.ReactNode;
+}) {
+  return <ItemContext.Provider value={value}>{children}</ItemContext.Provider>;
+}
+
+/**
+ * Read the current item context. Throws when used outside a
+ * `<SlideRail.Item>` — the leaf subparts are meaningless without a
+ * concrete slide to render.
+ */
+export function useSlideRailItem(): SlideRailItemContextValue {
+  const ctx = useContext(ItemContext);
+  if (!ctx) {
+    throw new Error(
+      "useSlideRailItem must be used inside <Slidewise.SlideRail.Item>"
+    );
+  }
+  return ctx;
+}

package/src/compound/sliderail/List.tsx

@@ -0,0 +1,67 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useEditor } from "@/lib/StoreProvider";
+import type { Slide } from "@/lib/types";
+import { Item } from "./Item";
+import { Thumbnail } from "./Thumbnail";
+import { Number as SlideNumber } from "./Number";
+
+/**
+ * Iterates `deck.slides` and renders each one. Pass a render-prop child
+ * for full control over what each row contains; omit the child to get
+ * the default `<Item><Thumbnail /><Number /></Item>` layout.
+ *
+ * ```tsx
+ * // Default
+ * <Slidewise.SlideRail.List />
+ *
+ * // Custom — add a per-row context menu
+ * <Slidewise.SlideRail.List>
+ *   {(slide) => (
+ *     <Slidewise.SlideRail.Item slide={slide}>
+ *       <Slidewise.SlideRail.Thumbnail />
+ *       <Slidewise.SlideRail.Number />
+ *       <MyContextMenu slide={slide} />
+ *     </Slidewise.SlideRail.Item>
+ *   )}
+ * </Slidewise.SlideRail.List>
+ * ```
+ */
+export interface SlideRailListProps {
+  className?: string;
+  style?: CSSProperties;
+  /**
+   * Optional render-prop. Receives each slide + its zero-based index;
+   * return the row content. When omitted, the default row layout
+   * is used.
+   */
+  children?: (slide: Slide, index: number) => ReactNode;
+}
+
+export function List({ className, style, children }: SlideRailListProps) {
+  const slides = useEditor((s) => s.deck.slides);
+
+  return (
+    <div
+      className={className}
+      style={{
+        flex: 1,
+        overflowY: "auto",
+        padding: "12px 0",
+        ...style,
+      }}
+    >
+      {slides.map((slide, index) =>
+        children ? (
+          // Render-prop branch: host returns whatever they want, typically
+          // wrapping their JSX in a SlideRail.Item to wire selection.
+          <div key={slide.id}>{children(slide, index)}</div>
+        ) : (
+          <Item key={slide.id} slide={slide}>
+            <Thumbnail />
+            <SlideNumber />
+          </Item>
+        )
+      )}
+    </div>
+  );
+}

package/src/compound/sliderail/Number.tsx

@@ -0,0 +1,57 @@
+import type { CSSProperties } from "react";
+import { useSlideRailItem } from "./ItemContext";
+
+/**
+ * Renders the slide's "01" / "02" badge in the top-left corner of the rail
+ * item. Reads the current slide's index from `<SlideRail.Item>`'s context.
+ *
+ * Render after `<SlideRail.Thumbnail>` so it stacks on top (or position
+ * it manually via `style`).
+ */
+export interface SlideRailNumberProps {
+  className?: string;
+  style?: CSSProperties;
+  /**
+   * Format the displayed number. Default is zero-padded to width 2
+   * (`01`, `02`, …, `10`).
+   */
+  format?: (index: number) => string;
+}
+
+const defaultFormat = (i: number) => String(i + 1).padStart(2, "0");
+
+export function Number({
+  className,
+  style,
+  format = defaultFormat,
+}: SlideRailNumberProps = {}) {
+  const { index, isCurrent } = useSlideRailItem();
+
+  return (
+    <span
+      className={className}
+      aria-hidden="true"
+      style={{
+        position: "absolute",
+        left: 20,
+        top: 6,
+        zIndex: 2,
+        width: 22,
+        height: 22,
+        borderRadius: 5,
+        background: isCurrent ? "var(--ink)" : "#6B7280",
+        color: isCurrent ? "var(--app-bg)" : "#fff",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        fontSize: 11,
+        fontWeight: 700,
+        fontFamily: "Inter, system-ui, sans-serif",
+        pointerEvents: "none",
+        ...style,
+      }}
+    >
+      {format(index)}
+    </span>
+  );
+}

package/src/compound/sliderail/Root.tsx

@@ -0,0 +1,54 @@
+import type { CSSProperties, PropsWithChildren } from "react";
+
+export const SLIDERAIL_DEFAULT_WIDTH = 168;
+
+/**
+ * Container for the slide rail subparts. Owns the rail's width, surface
+ * color, and divider. Hosts replace this when they want a different rail
+ * geometry (wider, narrower, full-bleed, etc.) — otherwise just render
+ * subparts inside it.
+ *
+ * ```tsx
+ * <Slidewise.SlideRail.Root>
+ *   <Slidewise.SlideRail.Header />
+ *   <Slidewise.SlideRail.List />
+ *   <Slidewise.SlideRail.AddButton />
+ * </Slidewise.SlideRail.Root>
+ * ```
+ */
+export interface SlideRailRootProps {
+  className?: string;
+  style?: CSSProperties;
+  /** Rail width in pixels. Defaults to 168. */
+  width?: number | string;
+}
+
+export function Root({
+  className,
+  style,
+  width = SLIDERAIL_DEFAULT_WIDTH,
+  children,
+}: PropsWithChildren<SlideRailRootProps>) {
+  return (
+    <div
+      className={
+        className ? `slidewise-rail ${className}` : "slidewise-rail"
+      }
+      style={{
+        width,
+        flexShrink: 0,
+        background: "var(--slidewise-bg-rail, var(--rail-bg))",
+        borderRight: "1px solid var(--border)",
+        boxShadow: "var(--rail-shadow)",
+        display: "flex",
+        flexDirection: "column",
+        fontFamily: "Inter, system-ui, sans-serif",
+        overflow: "hidden",
+        zIndex: 5,
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/compound/sliderail/Thumbnail.tsx

@@ -0,0 +1,58 @@
+import type { CSSProperties } from "react";
+import { SlideView } from "@/components/editor/SlideView";
+import { SLIDE_W } from "@/lib/types";
+import { useSlideRailItem } from "./ItemContext";
+
+const DEFAULT_THUMB_W = 132;
+
+/**
+ * Renders the slide preview inside the rail item. Reads the current slide
+ * from `<SlideRail.Item>`'s context. Honors the focused/non-focused state
+ * via an accent border.
+ *
+ * ```tsx
+ * <Slidewise.SlideRail.Item slide={slide}>
+ *   <Slidewise.SlideRail.Thumbnail />
+ * </Slidewise.SlideRail.Item>
+ * ```
+ */
+export interface SlideRailThumbnailProps {
+  className?: string;
+  style?: CSSProperties;
+  /** Pixel width for the rendered thumbnail. Defaults to 132. */
+  width?: number;
+}
+
+export function Thumbnail({
+  className,
+  style,
+  width = DEFAULT_THUMB_W,
+}: SlideRailThumbnailProps = {}) {
+  const { slide, isCurrent } = useSlideRailItem();
+  const scale = width / SLIDE_W;
+
+  return (
+    <div style={{ position: "relative" }}>
+      <div
+        className={className}
+        style={{
+          display: "block",
+          width,
+          border: isCurrent
+            ? "2px solid var(--slidewise-accent, var(--accent))"
+            : "2px solid transparent",
+          borderRadius: 8,
+          padding: 0,
+          background: "transparent",
+          overflow: "hidden",
+          transition: "border-color 120ms",
+          ...style,
+        }}
+      >
+        <div style={{ pointerEvents: "none" }}>
+          <SlideView slide={slide} scale={scale} />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/compound/sliderail/index.tsx

@@ -0,0 +1,74 @@
+import type { CSSProperties } from "react";
+import { Root, type SlideRailRootProps } from "./Root";
+import { Header, type SlideRailHeaderProps } from "./Header";
+import { List, type SlideRailListProps } from "./List";
+import { Item, type SlideRailItemProps } from "./Item";
+import { Thumbnail, type SlideRailThumbnailProps } from "./Thumbnail";
+import { Number, type SlideRailNumberProps } from "./Number";
+import { AddButton, type SlideRailAddButtonProps } from "./AddButton";
+
+export interface SlideRailProps {
+  className?: string;
+  style?: CSSProperties;
+  /** Rail width; forwarded to `<SlideRail.Root>`. */
+  width?: number | string;
+  /** Omit the header. */
+  hideHeader?: boolean;
+  /** Omit the "New Slide" button. */
+  hideAddButton?: boolean;
+}
+
+/**
+ * Default SlideRail arrangement. Equivalent to:
+ *
+ * ```tsx
+ * <Slidewise.SlideRail.Root>
+ *   <Slidewise.SlideRail.Header />
+ *   <Slidewise.SlideRail.List />
+ *   <Slidewise.SlideRail.AddButton />
+ * </Slidewise.SlideRail.Root>
+ * ```
+ *
+ * For full control (per-row context menus, custom thumbnail layout,
+ * etc.), drop down to the subparts directly.
+ */
+function DefaultSlideRail({
+  className,
+  style,
+  width,
+  hideHeader,
+  hideAddButton,
+}: SlideRailProps = {}) {
+  return (
+    <Root className={className} style={style} width={width}>
+      {!hideHeader && <Header />}
+      <List />
+      {!hideAddButton && <AddButton />}
+    </Root>
+  );
+}
+
+/**
+ * `<Slidewise.SlideRail />` is both the default arrangement and a
+ * namespace of subparts. Mirrors `<Slidewise.TopBar>`.
+ */
+export const SlideRail = Object.assign(DefaultSlideRail, {
+  Root,
+  Header,
+  List,
+  Item,
+  Thumbnail,
+  Number,
+  AddButton,
+});
+
+export { useSlideRailItem, type SlideRailItemContextValue } from "./ItemContext";
+export type {
+  SlideRailRootProps,
+  SlideRailHeaderProps,
+  SlideRailListProps,
+  SlideRailItemProps,
+  SlideRailThumbnailProps,
+  SlideRailNumberProps,
+  SlideRailAddButtonProps,
+};