@particle-academy/fancy-slides 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -0,0 +1,484 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties } from 'react';
+import { f as Slide$1, m as Theme, h as SlideElement, D as Deck, c as DeckOp, e as ShapeKind, k as TextElement, I as ImageElement, S as ShapeElement, i as SlideLayout, g as SlideBackground } from './types-Bc-psiRF.cjs';
+export { C as ChartElement, a as CodeElement, b as DeckActivity, E as ElementBase, d as EmbedElement, j as SlideTransition, T as TableElement, l as TextStyle, n as ThemeColors, o as ThemeFonts, p as TransitionKind } from './types-Bc-psiRF.cjs';
+
+interface SlideProps {
+    /** The slide to render. */
+    slide: Slide$1;
+    /** Deck theme — controls fonts/colors/aspect-ratio when the slide doesn't override. */
+    theme?: Theme;
+    /** Pin the slide to this width in px. When omitted, the slide fills its container with auto-resize. */
+    width?: number;
+    /** Aspect ratio override — falls back to theme.aspectRatio. */
+    aspectRatio?: number;
+    /** Edit mode flag — passed to element renderers + enables drag/resize affordances. */
+    editing?: boolean;
+    /** Called when a text element's content is edited (only in editing mode). */
+    onElementContentChange?: (elementId: string, content: string) => void;
+    /** Called when an element is clicked — host-driven selection. */
+    onElementSelect?: (elementId: string | null) => void;
+    /** Selected element id — adds a focus ring and shows resize handles when editing. */
+    selectedElementId?: string | null;
+    /** Called when the user drags an element body to a new position (slide-relative 0..1). */
+    onElementMove?: (elementId: string, x: number, y: number) => void;
+    /** Called when the user resizes via a corner / edge handle (slide-relative 0..1). */
+    onElementResize?: (elementId: string, patch: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }) => void;
+    /** Optional override renderer for a custom element type (or to replace one of the built-ins). */
+    renderElement?: (element: SlideElement, slideWidthPx: number) => ReactNode | undefined;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Slide — the shared renderer. Used by SlideViewer, DeckEditor canvas,
+ * SlideThumbnail, and the agent bridge's preview tools. All resolution-
+ * independence lives here: child elements get a `slideWidthPx` so they can
+ * scale font sizes / stroke widths to the rendered slide size.
+ *
+ * In `editing` mode this component grows two extra affordances:
+ *   - pointer-drag on an element body moves it
+ *   - selected elements show 8 resize handles (4 corners, 4 edges)
+ *
+ * Both fire through `onElementMove` / `onElementResize` so the host owns
+ * the state — Slide stays a pure renderer.
+ */
+declare function Slide({ slide, theme, width, aspectRatio, editing, onElementContentChange, onElementSelect, selectedElementId, onElementMove, onElementResize, renderElement, className, style, }: SlideProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * What the surrounding <Slide> knows about itself. Exposed to children
+ * (including `renderElement` callbacks and registry hosts like chart-host)
+ * via React context so they can react to the deck's theme without the
+ * renderElement signature having to carry it around.
+ */
+interface SlideContextValue {
+    /** Fully-resolved theme (merged with defaults). */
+    theme: Theme;
+    /**
+     * Heuristic: true when the resolved background is dark enough that
+     * native-rendered widgets (charts, code blocks) should use a dark variant.
+     * Computed once from `theme.colors.background` luminance.
+     */
+    isDark: boolean;
+    /** Slide width in CSS pixels at the current render size. */
+    slideWidthPx: number;
+}
+/**
+ * Read the surrounding <Slide>'s context. Returns null when called outside
+ * a Slide — chart-host / code-host can use that signal to fall back to
+ * a sensible default (light theme, no resize anchor).
+ */
+declare function useSlideContext(): SlideContextValue | null;
+/**
+ * Convenience: returns the resolved theme, or undefined when the caller
+ * isn't inside a Slide.
+ */
+declare function useSlideTheme(): Theme | undefined;
+/**
+ * Convenience: returns true when the surrounding slide's background reads
+ * as "dark enough" — useful for charts/code blocks that ship a dark variant.
+ */
+declare function useIsDarkSlide(): boolean;
+
+interface SlideViewerProps {
+    /** Deck to play. */
+    deck: Deck;
+    /** Controlled current slide index. Use with `onIndexChange`. */
+    index?: number;
+    /** Default current slide index (uncontrolled). */
+    defaultIndex?: number;
+    /** Called when the viewer advances. */
+    onIndexChange?: (index: number) => void;
+    /** Called when the viewer exits (Esc). */
+    onExit?: () => void;
+    /** Auto-advance interval in ms — kiosk mode. Omit to disable. */
+    autoAdvanceMs?: number;
+    /** Hide the bottom progress bar + slide counter. */
+    hideChrome?: boolean;
+    /** Optional custom renderer for element types Slide doesn't render natively (chart/code/table/embed). */
+    renderElement?: (element: SlideElement, slideWidthPx: number) => ReactNode | undefined;
+    /** Extra classes on the viewer wrapper. */
+    className?: string;
+}
+/**
+ * Read-only deck viewer. Renders one slide at a time at the maximum size
+ * that fits the container while preserving the theme's aspect ratio.
+ * Keyboard nav is built in; expand a fullscreen-ready container around
+ * `<SlideViewer>` to get the F11-style experience.
+ */
+declare function SlideViewer({ deck, index: controlledIndex, defaultIndex, onIndexChange, onExit, autoAdvanceMs, hideChrome, renderElement, className, }: SlideViewerProps): react_jsx_runtime.JSX.Element;
+
+interface PresenterViewProps {
+    /** Deck being presented. */
+    deck: Deck;
+    /** Controlled current slide index. */
+    index?: number;
+    /** Default current slide index (uncontrolled). */
+    defaultIndex?: number;
+    /** Called when the presenter advances. */
+    onIndexChange?: (index: number) => void;
+    /** Called when the presenter exits (Esc). */
+    onExit?: () => void;
+    /** Reset the elapsed timer to this `Date.now()` value. Defaults to mount time. */
+    startedAt?: number;
+    /** Optional custom renderer for non-built-in element types. */
+    renderElement?: (element: SlideElement, slideWidthPx: number) => ReactNode | undefined;
+    className?: string;
+}
+/**
+ * Speaker-only side view designed to live on a second monitor while the
+ * audience sees a `<SlideViewer>`. Layout:
+ *
+ *   ┌────────────────────────────┬────────────────────┐
+ *   │                            │  next slide        │
+ *   │                            ├────────────────────┤
+ *   │  current slide             │                    │
+ *   │  (largest viewport)        │  speaker notes     │
+ *   │                            │                    │
+ *   ├────────────────────────────┴────────────────────┤
+ *   │  3 / 12   elapsed 04:21   clock 14:35   prev /  │
+ *   │                                          next   │
+ *   └─────────────────────────────────────────────────┘
+ *
+ * Keyboard: same set as SlideViewer — ←/→/Space/Esc/Home/End/B/F/1-9.
+ * Notes pane shows the current slide's `notes` field (rendered as
+ * preformatted text for now; markdown rendering arrives with the
+ * ContentRenderer integration in 0.2).
+ */
+declare function PresenterView({ deck, index: controlledIndex, defaultIndex, onIndexChange, onExit, startedAt, renderElement, className, }: PresenterViewProps): react_jsx_runtime.JSX.Element;
+
+interface SlideThumbnailProps {
+    slide: Slide$1;
+    theme?: Theme;
+    /** Width of the thumbnail in px. Height comes from the theme's aspect ratio. */
+    width?: number;
+    /** When true, the thumbnail is rendered with a focused outline. */
+    active?: boolean;
+    onClick?: () => void;
+    onContextMenu?: (e: React.MouseEvent) => void;
+    renderElement?: (element: SlideElement, slideWidthPx: number) => ReactNode | undefined;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Compact slide preview. Used by the slide rail in the editor, by the
+ * presenter view, and anywhere else a deck wants to show its slides as
+ * thumbnails. Re-uses the shared <Slide> so the layout matches the viewer
+ * exactly — no second rendering path.
+ */
+declare function SlideThumbnail({ slide, theme, width, active, onClick, onContextMenu, renderElement, className, style, }: SlideThumbnailProps): react_jsx_runtime.JSX.Element;
+
+interface DeckEditorProps {
+    /** Controlled deck — pair with `onChange`. */
+    value: Deck;
+    onChange: (next: Deck) => void;
+    /** Called after every mutation with the op that produced it — feed into AgentPanel / audit log. */
+    onOp?: (op: DeckOp) => void;
+    /** Called when the user clicks Present. The host decides how to open the SlideViewer. */
+    onPresent?: () => void;
+    /** Controlled selected slide id. Uncontrolled by default. */
+    selectedSlideId?: string | null;
+    onSelectedSlideChange?: (id: string | null) => void;
+    /** Optional renderer for chart / code / table / embed elements (the elements this package doesn't render natively). */
+    renderElement?: (element: SlideElement, slideWidthPx: number) => ReactNode | undefined;
+    /** Hide the slide rail (e.g. for embedded use). */
+    hideRail?: boolean;
+    /** Hide the speaker notes panel. */
+    hideNotes?: boolean;
+    /** Hide the toolbar. */
+    hideToolbar?: boolean;
+    /** Hide the inspector. */
+    hideInspector?: boolean;
+    /** Optional extra content on the toolbar's trailing edge. */
+    toolbarExtra?: ReactNode;
+    className?: string;
+}
+/**
+ * Full deck editor — toolbar + rail + canvas + inspector + speaker notes.
+ *
+ * Controlled (`value` + `onChange`). State is intentionally simple: deck
+ * lives in the consumer, the editor just renders a view + dispatches ops.
+ * The same `DeckOp` enum that the agent bridge speaks runs through here —
+ * agents and humans drive identical mutations.
+ */
+declare function DeckEditor({ value, onChange, onOp, onPresent, selectedSlideId: controlledSlideId, onSelectedSlideChange, renderElement, hideRail, hideNotes, hideToolbar, hideInspector, toolbarExtra, className, }: DeckEditorProps): react_jsx_runtime.JSX.Element;
+
+interface SlideRailProps {
+    /** Slides to render in the rail. */
+    slides: Slide$1[];
+    /** Currently-selected slide id. */
+    selectedId: string | null;
+    /** Theme used for thumbnail rendering. */
+    theme?: Theme;
+    /** Select a slide by id. */
+    onSelect: (id: string) => void;
+    /** Add a slide after the given index (or at the end if absent). */
+    onAdd: (afterIndex?: number) => void;
+    /** Duplicate the given slide. */
+    onDuplicate: (id: string) => void;
+    /** Delete the given slide. */
+    onRemove: (id: string) => void;
+    /** Move a slide from `fromIndex` to `toIndex`. */
+    onReorder: (id: string, toIndex: number) => void;
+    /** Optional custom renderer for non-built-in element types — forwarded to the thumbnails. */
+    renderElement?: (element: SlideElement, slideWidthPx: number) => ReactNode | undefined;
+    /** Thumbnail width in px. Defaults to 184. */
+    thumbnailWidth?: number;
+}
+/**
+ * Left-hand slide rail. Built on react-fancy's `Sidebar` for the chrome and
+ * `ContextMenu` for right-click actions. Drag-to-reorder uses native HTML5
+ * drag events so we don't take a DnD dependency.
+ */
+declare function SlideRail({ slides, selectedId, theme, onSelect, onAdd, onDuplicate, onRemove, onReorder, renderElement, thumbnailWidth, }: SlideRailProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Starter chart-element preset. Picked from the toolbar Insert→Chart
+ * dropdown; expands into a starter `ChartElement.option` inside
+ * `DeckEditor.insertChart`. The actual saved `ChartElement` doesn't
+ * carry this — once the agent or user edits the option JSON, the
+ * "kind" is just whatever ECharts series.type the option says.
+ */
+type ChartKind$1 = "bar" | "line" | "pie" | "area" | "scatter";
+interface EditorToolbarProps {
+    /** Current deck title — shown left of the toolbar. */
+    title: string;
+    onTitleChange?: (title: string) => void;
+    /** Current theme name. */
+    themeName?: string;
+    /** Apply a theme. */
+    onApplyTheme?: (theme: Theme) => void;
+    /** Insert a text element on the active slide. */
+    onInsertText?: () => void;
+    /** Insert an image element. */
+    onInsertImage?: () => void;
+    /** Insert a shape element. */
+    onInsertShape?: (shape: ShapeKind) => void;
+    /** Insert a chart element. The `kind` arg picks a starter ECharts option
+     *  (`bar` / `line` / `pie` / `area` / `scatter`). Hosts can ignore the
+     *  arg if they only support a single chart type. */
+    onInsertChart?: (kind: ChartKind$1) => void;
+    /** Insert a code element. */
+    onInsertCode?: () => void;
+    /** Insert a table element. */
+    onInsertTable?: () => void;
+    /** Open the viewer (presentation mode). */
+    onPresent?: () => void;
+    /** When true, disables every Insert button (e.g. when no slide is selected). */
+    disabled?: boolean;
+}
+/**
+ * Top toolbar. Built on react-fancy's `Action`, `Dropdown`, `Tooltip`,
+ * `Badge`, `Separator`. Designed to be slotted into the editor chrome —
+ * doesn't manage its own scroll or sticky behavior.
+ */
+declare function EditorToolbar({ title, onTitleChange, themeName, onApplyTheme, onInsertText, onInsertImage, onInsertShape, onInsertChart, onInsertCode, onInsertTable, onPresent, disabled, }: EditorToolbarProps): react_jsx_runtime.JSX.Element;
+
+interface ElementInspectorProps {
+    /** Element being inspected. `null` shows the empty state. */
+    element: SlideElement | null;
+    /** Patch a property on the element. */
+    onPatch: (patch: Partial<SlideElement>) => void;
+    /** Delete the element. */
+    onDelete?: () => void;
+    /** Lock toggle. */
+    onLockToggle?: (locked: boolean) => void;
+}
+/**
+ * Right-hand inspector. Tabs split position + style + advanced properties.
+ * Per-element-type controls drop in under the Style tab. Built on
+ * react-fancy `Card`, `Tabs`, `Input`, `Select`, `Slider`, `ColorPicker`,
+ * `Action`.
+ */
+declare function ElementInspector({ element, onPatch, onDelete, onLockToggle }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
+
+interface SpeakerNotesProps {
+    notes?: string;
+    onChange: (notes: string) => void;
+    placeholder?: string;
+}
+/**
+ * Bottom-of-editor speaker notes panel. Just a labelled `Textarea` from
+ * react-fancy — the rest of the editor chrome controls how much vertical
+ * space this gets.
+ */
+declare function SpeakerNotes({ notes, onChange, placeholder }: SpeakerNotesProps): react_jsx_runtime.JSX.Element;
+
+interface TextElementRendererProps {
+    element: TextElement;
+    theme?: Theme;
+    /** Rendered slide width in px (for font-size scaling). */
+    slideWidthPx: number;
+    /**
+     * Edit mode — when true, the element is potentially editable.
+     * The textarea actually becomes pointer-interactive only when both
+     * `editing` and `selected` are true, so the first click on an
+     * unselected text element selects it (handled by the parent Slide)
+     * rather than landing on the textarea.
+     */
+    editing?: boolean;
+    /** Element is selected — gates whether the textarea grabs pointer events. */
+    selected?: boolean;
+    /** Called when the user edits the content (only fires when the textarea is focusable). */
+    onContentChange?: (content: string) => void;
+}
+/**
+ * Renderer for `text` elements. Three formats:
+ *
+ *   - `"markdown"` (default) — parsed via react-fancy's ContentRenderer.
+ *     Bullets, bold/italic, code spans, links, headings.
+ *   - `"html"` — parsed sanitized HTML via ContentRenderer's html path.
+ *   - `"plain"` — raw text rendered into a single block; preserves newlines
+ *     via `white-space: pre-wrap`.
+ *
+ * In editing mode + when the element is selected, the renderer swaps to a
+ * textarea showing the raw source. Edits flow back via `onContentChange`.
+ */
+declare function TextElementRenderer({ element, theme, slideWidthPx, editing, selected, onContentChange, }: TextElementRendererProps): react_jsx_runtime.JSX.Element;
+
+interface ImageElementRendererProps {
+    element: ImageElement;
+}
+declare function ImageElementRenderer({ element }: ImageElementRendererProps): react_jsx_runtime.JSX.Element;
+
+interface ShapeElementRendererProps {
+    element: ShapeElement;
+    theme?: Theme;
+    slideWidthPx: number;
+}
+/**
+ * SVG-rendered shape primitive. Sized to fill its element box; the box
+ * decides world position via the parent Slide's positioning wrapper.
+ */
+declare function ShapeElementRenderer({ element, theme, slideWidthPx }: ShapeElementRendererProps): react_jsx_runtime.JSX.Element;
+
+interface SlideKeyboardOptions {
+    /** Number of slides — clamps next/prev to bounds. */
+    total: number;
+    /** Current slide index. */
+    index: number;
+    /** Move to a specific slide. */
+    goTo: (index: number) => void;
+    /** Called on Esc — typically exits fullscreen. */
+    onExit?: () => void;
+    /** Called on `B` — typically blacks/whites out the screen. */
+    onBlank?: () => void;
+    /** Called on `F` — typically toggles fullscreen. */
+    onFullscreen?: () => void;
+    /** Disable when the editor is focused / a modal is open. */
+    enabled?: boolean;
+}
+/**
+ * Standard slideshow keyboard plumbing:
+ *
+ *   ←   / PageUp     — previous slide
+ *   →   / PageDown / Space — next slide
+ *   Home              — first slide
+ *   End               — last slide
+ *   Esc               — onExit
+ *   B / .             — onBlank (blackout)
+ *   F                 — onFullscreen
+ *   1..9              — jump to slide N
+ */
+declare function useSlideKeyboard({ total, index, goTo, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
+
+/**
+ * Hook that wraps a controlled deck with a typed mutation API. Every helper
+ * applies a `DeckOp` and emits the new deck via `onChange`. Consumers that
+ * want raw control over the deck can skip this and edit the deck directly
+ * — the helpers exist so the editor / agent bridge / undo system all funnel
+ * through the same shape.
+ */
+interface UseDeckStateOptions {
+    value: Deck;
+    onChange: (next: Deck) => void;
+    /** Called after every mutation with the op that produced it — wire up an AgentPanel / audit log. */
+    onOp?: (op: DeckOp) => void;
+}
+interface DeckStateApi {
+    /** Apply a raw DeckOp — the catch-all that every helper funnels through. */
+    apply: (op: DeckOp) => void;
+    /** Deck-level helpers. */
+    setTitle: (title: string) => void;
+    applyTheme: (theme: Theme) => void;
+    /** Slide-level helpers. */
+    addSlide: (index?: number, partial?: Partial<Slide$1>) => string;
+    duplicateSlide: (id: string) => string;
+    removeSlide: (id: string) => void;
+    reorderSlide: (id: string, toIndex: number) => void;
+    setLayout: (id: string, layout: SlideLayout) => void;
+    setNotes: (id: string, notes: string) => void;
+    setBackground: (id: string, bg?: SlideBackground) => void;
+    /** Element-level helpers. */
+    addElement: (slideId: string, element: Omit<SlideElement, "id"> & {
+        id?: string;
+    }) => string;
+    removeElement: (slideId: string, elementId: string) => void;
+    updateElement: (slideId: string, elementId: string, patch: Partial<SlideElement>) => void;
+    moveElement: (slideId: string, elementId: string, x: number, y: number) => void;
+    resizeElement: (slideId: string, elementId: string, w: number, h: number) => void;
+    /** Convenience lookups. */
+    getSlide: (id: string) => Slide$1 | undefined;
+    getElement: (slideId: string, elementId: string) => SlideElement | undefined;
+}
+declare function useDeckState({ value, onChange, onOp }: UseDeckStateOptions): DeckStateApi;
+/**
+ * Pure reducer — the single source of truth for how every DeckOp mutates a
+ * Deck. Agents, undo stacks, replay logs, and the editor all funnel through
+ * this. Never mutates the input.
+ */
+declare function reduce(deck: Deck, op: DeckOp): Deck;
+
+/**
+ * The default Fancy UI deck theme. Conservative neutral palette, modern
+ * geometric typography, 16:9 ratio. Custom themes can extend this — see
+ * `defineTheme()` in `./theme-utils`.
+ */
+declare const defaultTheme: Theme;
+/** Dark inverse of the default theme. */
+declare const darkTheme: Theme;
+/** A loud, brand-forward theme — handy for marketing decks. */
+declare const vividTheme: Theme;
+declare const builtinThemes: Record<string, Theme>;
+
+/**
+ * Merge a partial theme with the defaults so consumers can override just the
+ * pieces they care about (colors, fonts, aspect ratio) and inherit the rest.
+ */
+declare function defineTheme(overrides: Partial<Theme> & {
+    name: string;
+}): Theme;
+/** Resolve the effective theme for a deck — applies the default for any missing fields. */
+declare function resolveTheme(theme: Theme | undefined): Theme;
+
+/**
+ * Stable id generator. Deliberately simple — uses a counter + timestamp so
+ * generated ids are URL-safe and human-readable, not cryptographically
+ * unique. Servers / collaborative sessions should overwrite these with real
+ * UUIDs when persisting.
+ */
+declare function nextId(prefix?: string): string;
+declare function slideId(): string;
+declare function elementId(): string;
+declare function deckId(): string;
+
+/**
+ * Starter ECharts option objects for each `ChartKind`. Used by
+ * `DeckEditor.insertChart(kind)` so each toolbar dropdown choice spawns
+ * a renderable chart with sensible defaults — bar/line/area on a
+ * Q1-Q4 category axis, pie with three slices, scatter with a small
+ * random cluster.
+ *
+ * Once the agent or user edits the chart's `option`, the original
+ * `kind` is irrelevant — `option.series[0].type` is the source of
+ * truth from then on.
+ */
+type ChartKind = "bar" | "line" | "pie" | "area" | "scatter";
+type Option = Record<string, unknown>;
+declare function chartStarterOption(kind: ChartKind): Option;
+
+export { type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementInspector, type ElementInspectorProps, ImageElement, ImageElementRenderer, type ImageElementRendererProps, PresenterView, type PresenterViewProps, ShapeElement, ShapeElementRenderer, type ShapeElementRendererProps, ShapeKind, Slide, SlideBackground, type SlideContextValue, Slide$1 as SlideData, SlideElement, type SlideKeyboardOptions, SlideLayout, type SlideProps, SlideRail, type SlideRailProps, SlideThumbnail, type SlideThumbnailProps, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, builtinThemes, chartStarterOption, darkTheme, deckId, defaultTheme, defineTheme, elementId, nextId, reduce as reduceDeck, resolveTheme, slideId, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, vividTheme };