lumina-slides 9.0.4 → 9.0.6

package/src/core/types.ts

@@ -160,7 +160,9 @@ export interface FlexElementImage {
     /** Fill entire container edge-to-edge. Default: true */
     fill?: boolean;
     /** Object-fit mode when fill is true. Default: 'cover' */
-    fit?: 'cover' | 'contain';
+    fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    /** Object-position for image placement. Default: 'center' */
+    position?: string;
     /** Border radius. Default: 'none' when fill, 'lg' otherwise */
     rounded?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
     /** Link URL when image is clicked. */
@@ -169,6 +171,8 @@ export interface FlexElementImage {
     target?: '_blank' | '_self';
     /** Custom CSS class */
     class?: string;
+    /** Custom CSS style object */
+    style?: Record<string, string>;
 }
 
 /**
@@ -248,13 +252,30 @@ export interface FlexElementSpacer {
 }
 
 /**
- * Content container - Groups child elements vertically with alignment control.
+ * HTML element - Raw HTML content.
+ */
+export interface FlexElementHtml {
+    type: 'html';
+    /** Optional id for element control (engine.element(id)). */
+    id?: string;
+    /** Raw HTML string to render */
+    html: string;
+    /** Custom CSS class */
+    class?: string;
+    /** Custom CSS style object */
+    style?: Record<string, string>;
+}
+
+/**
+ * Content container - Groups child elements with alignment control.
  */
 export interface FlexElementContent {
     type: 'content';
     /** Optional id for element control (engine.element(id)). */
     id?: string;
     elements: FlexChildElement[];
+    /** Layout direction. Default: 'vertical' */
+    direction?: 'horizontal' | 'vertical';
     /** Vertical alignment of content. Default: 'center' */
     valign?: VAlign;
     /** Horizontal alignment of content. Default: 'left' */
@@ -263,10 +284,15 @@ export interface FlexElementContent {
     gap?: SpacingToken;
     /** Internal padding. Default: 'lg' */
     padding?: SpacingToken;
+    /** Custom CSS class */
+    class?: string;
+    /** Custom CSS style object */
+    style?: Record<string, string>;
 }
 
 /**
  * Child elements that can appear inside a content container.
+ * Supports nested content containers for complex layouts.
  */
 export type FlexChildElement =
     | FlexElementTitle
@@ -276,7 +302,10 @@ export type FlexChildElement =
     | FlexElementButton
     | FlexElementTimeline
     | FlexElementStepper
-    | FlexElementSpacer;
+    | FlexElementSpacer
+    | FlexElementHtml
+    | FlexElementImage
+    | FlexElementContent;
 
 /**
  * Top-level flex elements that can have size.
@@ -285,6 +314,7 @@ export type FlexElement =
     | (FlexElementImage & { size?: FlexSize })
     | (FlexElementVideo & { size?: FlexSize })
     | (FlexElementContent & { size?: FlexSize })
+    | (FlexElementHtml & { size?: FlexSize })
     | (FlexElementTitle & { size?: FlexSize })
     | (FlexElementText & { size?: FlexSize })
     | (FlexElementBullets & { size?: FlexSize })
@@ -561,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."
  * }
  * ```
@@ -864,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. */
@@ -881,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" }] }
@@ -1358,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;
@@ -1420,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
@@ -1447,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 ---
@@ -1481,7 +1523,8 @@ export type LuminaEventType =
     | 'revealComplete'
     | 'revealElement'
     | 'diagram-node-update'
-    | 'studio:update';
+    | 'studio:update'
+    | 'save';
 
 /**
  * Payload for the 'slideChange' event.
@@ -1594,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/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;
+}