lumina-slides 9.0.5 → 9.0.7

package/src/core/types.ts

@@ -591,7 +591,7 @@ export interface VideoProperties {
  *   "type": "statement",
  *   "meta": { "orbColor": "#3b82f6" },
  *   "tag": "Declarative Engine",
- *   "title": "Lumina V8",
+ *   "title": "Lumina V9",
  *   "subtitle": "A highly modular, performance-first presentation engine."
  * }
  * ```
@@ -894,8 +894,7 @@ export interface DeckMeta {
      */
     initialElementState?: InitialElementState;
     /**
-     * Element control defaults. Can be set in deck JSON so the deck is self-contained.
-     * defaultVisible: false = start all elements hidden; override per-id via initialElementState.
+     * Element control defaults. Elements are hidden by default. Set defaultVisible: true to show all.
      */
     elementControl?: { defaultVisible?: boolean };
     /** Default reveal options for all slides. Overridden by slide.reveal. */
@@ -911,8 +910,8 @@ export interface DeckMeta {
  * Complete deck object. Primary input to `engine.load(deck)`.
  *
  * @description
- * Must have `meta.title` and `slides` (array of slide objects). meta.initialElementState and
- * meta.elementControl enable reveal-on-demand. meta.effects overrides animation (see LuminaAnimationOptions).
+ * Must have `meta.title` and `slides` (array of slide objects). meta.initialElementState overrides per-element
+ * initial state. meta.elementControl.defaultVisible: true shows all. meta.effects overrides animation.
  *
  * @example
  * { meta: { title: "Demo", initialElementState: { "s0-title": { visible: false } } }, slides: [{ type: "statement", title: "Hi" }] }
@@ -1388,6 +1387,12 @@ export interface LuminaAnimationOptions {
     /** GSAP ease for reveal. Default: 'power2.out'. */
     revealEase?: string;
 
+    // --- Default cascade (when no meta.reveal or slide.reveal) ---
+    /** Delay in ms between elements for implicit default cascade. Default: 120. Override via meta.effects. */
+    defaultCascadeDelayMs?: number;
+    /** Per-element duration (s) for implicit default cascade. Default: 0.3. Override via meta.effects. */
+    defaultCascadeDuration?: number;
+
     // --- element().animate() ---
     /** Default duration in seconds. Default: 0.5. */
     elementDuration?: number;
@@ -1450,7 +1455,7 @@ export interface LuminaAnimationOptions {
  *
  * @example
  * new Lumina("#app", { theme: "midnight", loop: true, animation: { durationIn: 1.2 } });
- * new Lumina("#app", { elementControl: { defaultVisible: false } });
+ * new Lumina("#app", { elementControl: { defaultVisible: true } });  // legacy: show all
  *
  * @see Lumina
  * @see LuminaAnimationOptions
@@ -1477,16 +1482,23 @@ export interface LuminaOptions {
     /** Animation settings. */
     animation?: LuminaAnimationOptions;
     /**
-     * Element control defaults. Use for reveal-on-demand: set defaultVisible to false so all
-     * elements start hidden; override per-id via meta.initialElementState. Then reveal with
-     * engine.element(id).show().
+     * Element control defaults. Elements are hidden by default and cascade-reveal on slide enter.
+     * Set defaultVisible: true to show all elements immediately (legacy behavior).
      */
     elementControl?: {
-        /** If false, all elements start hidden unless listed in meta.initialElementState. Default: true. */
+        /** If true, all elements start visible. Default: false (elements hidden, cascade on enter). */
         defaultVisible?: boolean;
     };
     /** Enable Studio (Page Builder) mode. */
     studio?: boolean;
+    /**
+     * Enable Studio Embed mode: same editor as Studio but without back button;
+     * Save button emits a "save" event with the deck JSON instead of persisting to Firestore.
+     * Use with vanilla JS: new Lumina("#app", { studioEmbed: true, initialDeck: deck }); engine.on("save", (d) => { ... }).
+     */
+    studioEmbed?: boolean;
+    /** Initial deck when using studioEmbed. Can be updated later with engine.load(deck). */
+    initialDeck?: Deck;
 }
 
 // --- Events ---
@@ -1511,7 +1523,8 @@ export type LuminaEventType =
     | 'revealComplete'
     | 'revealElement'
     | 'diagram-node-update'
-    | 'studio:update';
+    | 'studio:update'
+    | 'save';
 
 /**
  * Payload for the 'slideChange' event.
@@ -1624,6 +1637,8 @@ export interface LuminaEventMap {
     'diagram-node-update': { slideIndex: number; nodeId: string; key: string; value: any };
     /** Fired when Studio updates a node (path, value). Internal. */
     'studio:update': { path: string; value: any };
+    /** Fired when user clicks Save in Studio Embed mode; payload is the current deck JSON. */
+    save: Deck;
 }
 
 /**

package/src/index.ts

@@ -13,8 +13,7 @@
  * **Element control:** `engine.element(id)`, `engine.element(slideIndex, path)`, or `engine.elementInCurrent(path)` → ElementController:
  * `.show()`, `.hide()`, `.toggle()`, `.opacity(n)`, `.transform(s)`, `.animate({ preset?, from?, to?, duration?, ease? })`.
  * Presets: fadeUp, fadeIn, scaleIn, slideLeft, slideRight, zoomIn, blurIn, spring, drop, fadeOut. `to` optional when using preset.
- * Ids: `engine.elements(slideIndex)` or `s{N}-{path}` (e.g. s0-tag, s1-features-0). `meta.initialElementState`:
- * `{ [id]: { visible?: false } }` to start hidden; then `engine.element(id).show()`.
+ * Ids: `engine.elements(slideIndex)` or `s{N}-{path}` (e.g. s0-tag, s1-features-0). Elements hidden by default, cascade on enter. `meta.initialElementState` overrides per-id. `elementControl.defaultVisible: true` shows all.
  *
  * **Helpers:** `hideAll(slideIndex?)`, `showAll(slideIndex?)`, `showOnly(ids?)`, `hideAllExcept(exceptIds?)`,
  * `resetSlide(slideIndex?)`, `delay(ms)`, `revealInSequence(slideIndex?, { delayMs?, staggerMode?, preset?, from?, to?, duration?, ease?, hideFirst?, only?, exclude? })`.
@@ -175,4 +174,5 @@ export type {
 
 export { default as LuminaDeck } from './components/LuminaDeck.vue';
 export { default as LuminaStudio } from './components/studio/LuminaStudio.vue';
+export { default as LuminaStudioEmbed } from './components/studio/LuminaStudioEmbed.vue';
 import './style/main.css';

package/src/utils/prepareDeckForExport.ts

@@ -0,0 +1,47 @@
+/**
+ * Prepares a deck for export: strips internal dragKey and adds explicit element ids.
+ * Used by Studio export, save, and JSON view.
+ * - slide.ids: path → id for every element
+ * - each element object that can have an id (features[i], timeline[i], elements[i], nodes[i], etc.) gets id set
+ */
+import { toRaw } from 'vue';
+import type { Deck, BaseSlideData } from '../core/types';
+import { getElementPaths, resolveId, pathToKey, getValueAt } from '../core/elementResolver';
+
+/** Recursively remove all dragKey properties from an object (mutates in place). */
+export function stripDragKeys(obj: unknown): void {
+    if (obj == null || typeof obj !== 'object') return;
+    if (Array.isArray(obj)) {
+        obj.forEach(stripDragKeys);
+        return;
+    }
+    delete (obj as Record<string, unknown>)['dragKey'];
+    Object.values(obj as Record<string, unknown>).forEach(stripDragKeys);
+}
+
+/** Prepare deck for export: clone, strip dragKey, add slide.ids, and set id on each element object. */
+export function prepareDeckForExport(deck: Deck): Deck {
+    const clone = JSON.parse(JSON.stringify(toRaw(deck))) as Deck;
+    stripDragKeys(clone);
+    const slides = clone.slides ?? [];
+    slides.forEach((slide: BaseSlideData, slideIndex: number) => {
+        const paths = getElementPaths(slide);
+        if (paths.length === 0) return;
+        const slideAny = slide as { ids?: Record<string, string> };
+        if (!slideAny.ids) slideAny.ids = {};
+        paths.forEach((path) => {
+            const pathKey = pathToKey(path);
+            const resolvedId = resolveId(slide, slideIndex, path);
+            slideAny.ids![pathKey] = resolvedId;
+
+            // Set id on the element object when it's an object (e.g. features[0], elements[0], nodes[0])
+            if (path.length > 0 && path[0] !== 'slide') {
+                const value = getValueAt(slide, path);
+                if (value != null && typeof value === 'object' && !Array.isArray(value)) {
+                    (value as Record<string, string>).id = resolvedId;
+                }
+            }
+        });
+    });
+    return clone;
+}

package/src/utils/templateInterpolation.ts

@@ -1,52 +1,52 @@
-/**
- * Template interpolation for Lumina slide content.
- *
- * Replaces `{{key}}` placeholders in strings with values from a key-value store
- * (e.g. engine.data / store.userData). When the store changes, any component
- * that uses the interpolated result will reactively update.
- *
- * @example
- * interpolateString('Hello {{name}}', { name: 'World' })  // 'Hello World'
- * interpolateObject({ title: '{{product}}', subtitle: 'v{{version}}' }, { product: 'Lumina', version: 1 })
- * // { title: 'Lumina', subtitle: 'v1' }
- */
-
-/** Matches {{key}} or {{ key }}. Key: alphanumeric, underscore. */
-const TAG_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
-
-/**
- * Replaces all {{key}} placeholders in a string with values from `data`.
- * Missing keys render as empty string. Non-string values are coerced with String().
- *
- * @param str - Raw string possibly containing `{{key}}` tags.
- * @param data - Key-value map (e.g. engine.data / store.state.userData).
- * @returns Interpolated string.
- */
-export function interpolateString(str: string, data: Record<string, unknown>): string {
-    if (typeof str !== 'string') return str;
-    return str.replace(TAG_RE, (_, key: string) => {
-        const v = data[key];
-        return v == null ? '' : String(v);
-    });
-}
-
-/**
- * Recursively interpolates all string values in an object/array with `{{key}}`
- * placeholders. Other types (number, boolean, null, etc.) are returned unchanged.
- * Does not mutate the input; returns a new structure.
- *
- * @param obj - Object, array, or primitive (strings are interpolated).
- * @param data - Key-value map (e.g. engine.data / store.state.userData).
- * @returns New structure with all strings interpolated.
- */
-export function interpolateObject<T>(obj: T, data: Record<string, unknown>): T {
-    if (obj == null) return obj;
-    if (typeof obj === 'string') return interpolateString(obj, data) as T;
-    if (Array.isArray(obj)) return obj.map((item) => interpolateObject(item, data)) as T;
-    if (typeof obj === 'object' && obj.constructor === Object) {
-        return Object.fromEntries(
-            Object.entries(obj).map(([k, v]) => [k, interpolateObject(v, data)])
-        ) as T;
-    }
-    return obj;
-}
+/**
+ * Template interpolation for Lumina slide content.
+ *
+ * Replaces `{{key}}` placeholders in strings with values from a key-value store
+ * (e.g. engine.data / store.userData). When the store changes, any component
+ * that uses the interpolated result will reactively update.
+ *
+ * @example
+ * interpolateString('Hello {{name}}', { name: 'World' })  // 'Hello World'
+ * interpolateObject({ title: '{{product}}', subtitle: 'v{{version}}' }, { product: 'Lumina', version: 1 })
+ * // { title: 'Lumina', subtitle: 'v1' }
+ */
+
+/** Matches {{key}} or {{ key }}. Key: alphanumeric, underscore. */
+const TAG_RE = /\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+
+/**
+ * Replaces all {{key}} placeholders in a string with values from `data`.
+ * Missing keys render as empty string. Non-string values are coerced with String().
+ *
+ * @param str - Raw string possibly containing `{{key}}` tags.
+ * @param data - Key-value map (e.g. engine.data / store.state.userData).
+ * @returns Interpolated string.
+ */
+export function interpolateString(str: string, data: Record<string, unknown>): string {
+    if (typeof str !== 'string') return str;
+    return str.replace(TAG_RE, (_, key: string) => {
+        const v = data[key];
+        return v == null ? '' : String(v);
+    });
+}
+
+/**
+ * Recursively interpolates all string values in an object/array with `{{key}}`
+ * placeholders. Other types (number, boolean, null, etc.) are returned unchanged.
+ * Does not mutate the input; returns a new structure.
+ *
+ * @param obj - Object, array, or primitive (strings are interpolated).
+ * @param data - Key-value map (e.g. engine.data / store.state.userData).
+ * @returns New structure with all strings interpolated.
+ */
+export function interpolateObject<T>(obj: T, data: Record<string, unknown>): T {
+    if (obj == null) return obj;
+    if (typeof obj === 'string') return interpolateString(obj, data) as T;
+    if (Array.isArray(obj)) return obj.map((item) => interpolateObject(item, data)) as T;
+    if (typeof obj === 'object' && obj.constructor === Object) {
+        return Object.fromEntries(
+            Object.entries(obj).map(([k, v]) => [k, interpolateObject(v, data)])
+        ) as T;
+    }
+    return obj;
+}