@particle-academy/fancy-slides 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 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, j as SlideTransition, g as SlideBackground, k as TextElement, I as ImageElement, S as ShapeElement, i as SlideLayout } from './types-B2ecrEAz.cjs';
-export { C as ChartElement, a as CodeElement, b as DeckActivity, E as ElementBase, d as EmbedElement, T as TableElement, l as TextStyle, n as ThemeColors, o as ThemeFonts, p as TransitionKind } from './types-B2ecrEAz.cjs';
+import { h as Slide$1, o as Theme, j as SlideElement, D as Deck, d as DeckOp, g as ShapeKind, l as SlideTransition, i as SlideBackground, E as ElementAnimation, m as TextElement, I as ImageElement, S as ShapeElement, k as SlideLayout } from './types-P-9MmnGU.cjs';
+export { A as AnimationEffect, a as AnimationTrigger, C as ChartElement, b as CodeElement, c as DeckActivity, e as ElementBase, f as EmbedElement, T as TableElement, n as TextStyle, p as ThemeColors, q as ThemeFonts, r as TransitionKind } from './types-P-9MmnGU.cjs';
 
 interface SlideProps {
     /** The slide to render. */
@@ -14,6 +14,13 @@ interface SlideProps {
     aspectRatio?: number;
     /** Edit mode flag — passed to element renderers + enables drag/resize affordances. */
     editing?: boolean;
+    /**
+     * Current build step (0..totalSteps). `0` = nothing built (only non-animated
+     * elements visible); each step reveals more animated elements. Omit (or pass
+     * a number ≥ total) to show the fully-built slide. Ignored when `editing` —
+     * the editor always shows every element so authors can position them.
+     */
+    buildStep?: number;
     /** 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. */
@@ -47,7 +54,7 @@ interface SlideProps {
  * 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;
+declare function Slide({ slide, theme, width, aspectRatio, editing, buildStep, onElementContentChange, onElementSelect, selectedElementId, onElementMove, onElementResize, renderElement, className, style, }: SlideProps): react_jsx_runtime.JSX.Element;
 
 /**
  * What the surrounding <Slide> knows about itself. Exposed to children
@@ -293,6 +300,10 @@ interface ElementInspectorProps {
     onSetTransition?: (transition?: SlideTransition) => void;
     /** Set the slide's background. */
     onSetBackground?: (background?: SlideBackground) => void;
+    /** Set or clear the selected element's entrance build animation. */
+    onSetAnimation?: (animation?: ElementAnimation) => void;
+    /** Set a specific element's build animation by id — used by the slide-level build-order list. */
+    onSetElementAnimation?: (elementId: string, animation?: ElementAnimation) => void;
 }
 /**
  * Right-hand inspector. Tabs split position + style + advanced properties.
@@ -300,7 +311,7 @@ interface ElementInspectorProps {
  * react-fancy `Card`, `Tabs`, `Input`, `Select`, `Slider`, `ColorPicker`,
  * `Action`.
  */
-declare function ElementInspector({ element, onPatch, onDelete, onLockToggle, slide, onSetTransition, onSetBackground }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
+declare function ElementInspector({ element, onPatch, onDelete, onLockToggle, slide, onSetTransition, onSetBackground, onSetAnimation, onSetElementAnimation }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
 
 interface SpeakerNotesProps {
     notes?: string;
@@ -375,8 +386,19 @@ interface SlideKeyboardOptions {
     total: number;
     /** Current slide index. */
     index: number;
-    /** Move to a specific slide. */
+    /** Move to a specific slide. Used by Home/End/1-9 (and by arrows when no `onAdvance`/`onRetreat`). */
     goTo: (index: number) => void;
+    /**
+     * Forward step (→ / Space / PageDown). When provided it OWNS forward nav —
+     * e.g. step through builds, then advance the slide. Falls back to
+     * `goTo(index + 1)` when omitted.
+     */
+    onAdvance?: () => void;
+    /**
+     * Backward step (← / PageUp). When provided it OWNS backward nav. Falls back
+     * to `goTo(index - 1)` when omitted.
+     */
+    onRetreat?: () => void;
     /** Called on Esc — typically exits fullscreen. */
     onExit?: () => void;
     /** Called on `B` — typically blacks/whites out the screen. */
@@ -389,8 +411,8 @@ interface SlideKeyboardOptions {
 /**
  * Standard slideshow keyboard plumbing:
  *
- *   ←   / PageUp     — previous slide
- *   →   / PageDown / Space — next slide
+ *   ←   / PageUp     — retreat (onRetreat, else previous slide)
+ *   →   / PageDown / Space — advance (onAdvance, else next slide)
  *   Home              — first slide
  *   End               — last slide
  *   Esc               — onExit
@@ -398,7 +420,7 @@ interface SlideKeyboardOptions {
  *   F                 — onFullscreen
  *   1..9              — jump to slide N
  */
-declare function useSlideKeyboard({ total, index, goTo, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
+declare function useSlideKeyboard({ total, index, goTo, onAdvance, onRetreat, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
 
 /**
  * Hook that wraps a controlled deck with a typed mutation API. Every helper
@@ -436,6 +458,8 @@ interface DeckStateApi {
     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;
+    /** Set or clear an element's entrance build animation. Pass `undefined` to clear. */
+    setAnimation: (slideId: string, elementId: string, animation?: ElementAnimation) => void;
     /** Convenience lookups. */
     getSlide: (id: string) => Slide$1 | undefined;
     getElement: (slideId: string, elementId: string) => SlideElement | undefined;
@@ -496,4 +520,68 @@ 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, SlideTransition, 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 };
+/**
+ * Build (entrance-animation) sequencing — the shared model used by both
+ * `SlideViewer` and `PresenterView` so step-through behaves identically.
+ *
+ * A slide's *builds* are the elements that carry an `animation`. They are
+ * stable-sorted by `(order ?? 0)` then original element array index, then
+ * grouped into *click steps*:
+ *
+ *   - The first build, and every build whose trigger is `"on-click"`, starts
+ *     a NEW step.
+ *   - `"with-prev"` plays simultaneously with the current step's lead.
+ *   - `"after-prev"` plays after a delay equal to the current step's lead
+ *     duration (chained onto its `delay`).
+ *
+ * `buildStep` semantics (used by the viewer/presenter):
+ *   - `0`  → nothing built yet; only non-animated elements are visible.
+ *   - `n`  → the first `n` steps have fired; their elements are visible.
+ *   - `totalSteps` → every build is shown (the fully-built slide).
+ */
+
+/** One element participating in a build, paired with its (defaulted) animation. */
+interface Build {
+    element: SlideElement;
+    animation: ElementAnimation;
+    /** Original index of the element in the slide's `elements` array (tie-breaker). */
+    index: number;
+}
+/** A click step — the set of builds revealed by a single forward advance. */
+interface BuildStep {
+    /** Builds that reveal on this step (lead first, then with-prev / after-prev). */
+    builds: Build[];
+}
+/**
+ * Collect a slide's builds in resolved order: every element with an
+ * `animation`, stable-sorted by `(order ?? 0)` then array index.
+ */
+declare function collectBuilds(slide: Slide$1 | undefined): Build[];
+/**
+ * Group a slide's builds into click steps. The first build always opens a
+ * step; thereafter an `"on-click"` trigger opens a new step while
+ * `"with-prev"` / `"after-prev"` attach to the current one.
+ */
+declare function buildSteps(slide: Slide$1 | undefined): BuildStep[];
+/** Total number of click steps for a slide (0 when the slide has no builds). */
+declare function totalBuildSteps(slide: Slide$1 | undefined): number;
+/**
+ * Given a slide and a `buildStep` (0..totalSteps), return the set of element
+ * ids that should be VISIBLE. Elements with no animation are always visible;
+ * animated elements become visible once their owning step has fired.
+ */
+declare function visibleElementIds(slide: Slide$1 | undefined, buildStep: number): Set<string>;
+/**
+ * The builds that fire when advancing INTO `buildStep` (1-based). Returns the
+ * lead build first; the viewer uses `with-prev` / `after-prev` to compute each
+ * element's effective `delay`. Empty when `buildStep` is out of range.
+ */
+declare function buildsForStep(slide: Slide$1 | undefined, buildStep: number): Build[];
+/**
+ * Compute the effective entrance delay (ms) for each build within a step,
+ * honouring `with-prev` (0 extra) and `after-prev` (lead duration). The lead
+ * build keeps its own `delay`; followers add to it. Keyed by element id.
+ */
+declare function stepDelays(builds: Build[]): Map<string, number>;
+
+export { type Build, type BuildStep, type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementAnimation, 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, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, nextId, reduce as reduceDeck, resolveTheme, slideId, stepDelays, totalBuildSteps, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, visibleElementIds, vividTheme };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, j as SlideTransition, g as SlideBackground, k as TextElement, I as ImageElement, S as ShapeElement, i as SlideLayout } from './types-B2ecrEAz.js';
-export { C as ChartElement, a as CodeElement, b as DeckActivity, E as ElementBase, d as EmbedElement, T as TableElement, l as TextStyle, n as ThemeColors, o as ThemeFonts, p as TransitionKind } from './types-B2ecrEAz.js';
+import { h as Slide$1, o as Theme, j as SlideElement, D as Deck, d as DeckOp, g as ShapeKind, l as SlideTransition, i as SlideBackground, E as ElementAnimation, m as TextElement, I as ImageElement, S as ShapeElement, k as SlideLayout } from './types-P-9MmnGU.js';
+export { A as AnimationEffect, a as AnimationTrigger, C as ChartElement, b as CodeElement, c as DeckActivity, e as ElementBase, f as EmbedElement, T as TableElement, n as TextStyle, p as ThemeColors, q as ThemeFonts, r as TransitionKind } from './types-P-9MmnGU.js';
 
 interface SlideProps {
     /** The slide to render. */
@@ -14,6 +14,13 @@ interface SlideProps {
     aspectRatio?: number;
     /** Edit mode flag — passed to element renderers + enables drag/resize affordances. */
     editing?: boolean;
+    /**
+     * Current build step (0..totalSteps). `0` = nothing built (only non-animated
+     * elements visible); each step reveals more animated elements. Omit (or pass
+     * a number ≥ total) to show the fully-built slide. Ignored when `editing` —
+     * the editor always shows every element so authors can position them.
+     */
+    buildStep?: number;
     /** 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. */
@@ -47,7 +54,7 @@ interface SlideProps {
  * 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;
+declare function Slide({ slide, theme, width, aspectRatio, editing, buildStep, onElementContentChange, onElementSelect, selectedElementId, onElementMove, onElementResize, renderElement, className, style, }: SlideProps): react_jsx_runtime.JSX.Element;
 
 /**
  * What the surrounding <Slide> knows about itself. Exposed to children
@@ -293,6 +300,10 @@ interface ElementInspectorProps {
     onSetTransition?: (transition?: SlideTransition) => void;
     /** Set the slide's background. */
     onSetBackground?: (background?: SlideBackground) => void;
+    /** Set or clear the selected element's entrance build animation. */
+    onSetAnimation?: (animation?: ElementAnimation) => void;
+    /** Set a specific element's build animation by id — used by the slide-level build-order list. */
+    onSetElementAnimation?: (elementId: string, animation?: ElementAnimation) => void;
 }
 /**
  * Right-hand inspector. Tabs split position + style + advanced properties.
@@ -300,7 +311,7 @@ interface ElementInspectorProps {
  * react-fancy `Card`, `Tabs`, `Input`, `Select`, `Slider`, `ColorPicker`,
  * `Action`.
  */
-declare function ElementInspector({ element, onPatch, onDelete, onLockToggle, slide, onSetTransition, onSetBackground }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
+declare function ElementInspector({ element, onPatch, onDelete, onLockToggle, slide, onSetTransition, onSetBackground, onSetAnimation, onSetElementAnimation }: ElementInspectorProps): react_jsx_runtime.JSX.Element;
 
 interface SpeakerNotesProps {
     notes?: string;
@@ -375,8 +386,19 @@ interface SlideKeyboardOptions {
     total: number;
     /** Current slide index. */
     index: number;
-    /** Move to a specific slide. */
+    /** Move to a specific slide. Used by Home/End/1-9 (and by arrows when no `onAdvance`/`onRetreat`). */
     goTo: (index: number) => void;
+    /**
+     * Forward step (→ / Space / PageDown). When provided it OWNS forward nav —
+     * e.g. step through builds, then advance the slide. Falls back to
+     * `goTo(index + 1)` when omitted.
+     */
+    onAdvance?: () => void;
+    /**
+     * Backward step (← / PageUp). When provided it OWNS backward nav. Falls back
+     * to `goTo(index - 1)` when omitted.
+     */
+    onRetreat?: () => void;
     /** Called on Esc — typically exits fullscreen. */
     onExit?: () => void;
     /** Called on `B` — typically blacks/whites out the screen. */
@@ -389,8 +411,8 @@ interface SlideKeyboardOptions {
 /**
  * Standard slideshow keyboard plumbing:
  *
- *   ←   / PageUp     — previous slide
- *   →   / PageDown / Space — next slide
+ *   ←   / PageUp     — retreat (onRetreat, else previous slide)
+ *   →   / PageDown / Space — advance (onAdvance, else next slide)
  *   Home              — first slide
  *   End               — last slide
  *   Esc               — onExit
@@ -398,7 +420,7 @@ interface SlideKeyboardOptions {
  *   F                 — onFullscreen
  *   1..9              — jump to slide N
  */
-declare function useSlideKeyboard({ total, index, goTo, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
+declare function useSlideKeyboard({ total, index, goTo, onAdvance, onRetreat, onExit, onBlank, onFullscreen, enabled, }: SlideKeyboardOptions): void;
 
 /**
  * Hook that wraps a controlled deck with a typed mutation API. Every helper
@@ -436,6 +458,8 @@ interface DeckStateApi {
     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;
+    /** Set or clear an element's entrance build animation. Pass `undefined` to clear. */
+    setAnimation: (slideId: string, elementId: string, animation?: ElementAnimation) => void;
     /** Convenience lookups. */
     getSlide: (id: string) => Slide$1 | undefined;
     getElement: (slideId: string, elementId: string) => SlideElement | undefined;
@@ -496,4 +520,68 @@ 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, SlideTransition, 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 };
+/**
+ * Build (entrance-animation) sequencing — the shared model used by both
+ * `SlideViewer` and `PresenterView` so step-through behaves identically.
+ *
+ * A slide's *builds* are the elements that carry an `animation`. They are
+ * stable-sorted by `(order ?? 0)` then original element array index, then
+ * grouped into *click steps*:
+ *
+ *   - The first build, and every build whose trigger is `"on-click"`, starts
+ *     a NEW step.
+ *   - `"with-prev"` plays simultaneously with the current step's lead.
+ *   - `"after-prev"` plays after a delay equal to the current step's lead
+ *     duration (chained onto its `delay`).
+ *
+ * `buildStep` semantics (used by the viewer/presenter):
+ *   - `0`  → nothing built yet; only non-animated elements are visible.
+ *   - `n`  → the first `n` steps have fired; their elements are visible.
+ *   - `totalSteps` → every build is shown (the fully-built slide).
+ */
+
+/** One element participating in a build, paired with its (defaulted) animation. */
+interface Build {
+    element: SlideElement;
+    animation: ElementAnimation;
+    /** Original index of the element in the slide's `elements` array (tie-breaker). */
+    index: number;
+}
+/** A click step — the set of builds revealed by a single forward advance. */
+interface BuildStep {
+    /** Builds that reveal on this step (lead first, then with-prev / after-prev). */
+    builds: Build[];
+}
+/**
+ * Collect a slide's builds in resolved order: every element with an
+ * `animation`, stable-sorted by `(order ?? 0)` then array index.
+ */
+declare function collectBuilds(slide: Slide$1 | undefined): Build[];
+/**
+ * Group a slide's builds into click steps. The first build always opens a
+ * step; thereafter an `"on-click"` trigger opens a new step while
+ * `"with-prev"` / `"after-prev"` attach to the current one.
+ */
+declare function buildSteps(slide: Slide$1 | undefined): BuildStep[];
+/** Total number of click steps for a slide (0 when the slide has no builds). */
+declare function totalBuildSteps(slide: Slide$1 | undefined): number;
+/**
+ * Given a slide and a `buildStep` (0..totalSteps), return the set of element
+ * ids that should be VISIBLE. Elements with no animation are always visible;
+ * animated elements become visible once their owning step has fired.
+ */
+declare function visibleElementIds(slide: Slide$1 | undefined, buildStep: number): Set<string>;
+/**
+ * The builds that fire when advancing INTO `buildStep` (1-based). Returns the
+ * lead build first; the viewer uses `with-prev` / `after-prev` to compute each
+ * element's effective `delay`. Empty when `buildStep` is out of range.
+ */
+declare function buildsForStep(slide: Slide$1 | undefined, buildStep: number): Build[];
+/**
+ * Compute the effective entrance delay (ms) for each build within a step,
+ * honouring `with-prev` (0 extra) and `after-prev` (lead duration). The lead
+ * build keeps its own `delay`; followers add to it. Keyed by element id.
+ */
+declare function stepDelays(builds: Build[]): Map<string, number>;
+
+export { type Build, type BuildStep, type ChartKind$1 as ChartKind, Deck, DeckEditor, type DeckEditorProps, DeckOp, type DeckStateApi, EditorToolbar, type EditorToolbarProps, ElementAnimation, 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, SlideTransition, SlideViewer, type SlideViewerProps, SpeakerNotes, type SpeakerNotesProps, TextElement, TextElementRenderer, type TextElementRendererProps, Theme, type UseDeckStateOptions, buildSteps, buildsForStep, builtinThemes, chartStarterOption, collectBuilds, darkTheme, deckId, defaultTheme, defineTheme, elementId, nextId, reduce as reduceDeck, resolveTheme, slideId, stepDelays, totalBuildSteps, useDeckState, useIsDarkSlide, useSlideContext, useSlideKeyboard, useSlideTheme, visibleElementIds, vividTheme };