lumina-slides 8.9.2 → 8.9.4

package/IMPLEMENTATION.md

@@ -1,44 +1,46 @@
 # Implementing lumina-slides
 
-Guía para integrar la librería `lumina-slides` en tu aplicación. Pensada para desarrolladores y para **agentes de código** (Cursor, Copilot, etc.) que escriben el código que consume la librería.
+Guide for integrating the `lumina-slides` library into your application. For developers and **code agents** (Cursor, Copilot, etc.) that write the code that consumes the library.
+
+**Vanilla JavaScript library:** use `import { Lumina } from "lumina-slides"`, `new Lumina(selector)`, and `engine.load(deck)`. The host app can be vanilla JS, React, or any framework; **Vue is not required**. All control (render, element control, animations, events) is done via the engine API and the deck JSON. The API is designed for vanilla JS.
 
 ---
 
-## 1. Instalación
+## 1. Installation
 
 ```bash
 npm install lumina-slides
-# Opcional, solo si usas slides tipo "chart":
+# Optional, only if you use "chart" slides:
 npm install lumina-slides chart.js
 ```
 
 ---
 
-## 2. Imports principales
+## 2. Main imports
 
 ```ts
 import { Lumina, parsePartialJson, generateSystemPrompt, getLuminaJsonSchema } from "lumina-slides";
 import "lumina-slides/style.css";
 ```
 
-Otras exportaciones útiles: `createDebouncedLoader`, `isSlideReady`, `generateThemePrompt`, tipos `Deck`, `LuminaOptions`, `LuminaEventMap`, etc.
+Other useful exports: `createDebouncedLoader`, `isSlideReady`, `generateThemePrompt`, types `Deck`, `LuminaOptions`, `LuminaEventMap`, etc.
 
 ---
 
-## 3. Crear el motor y cargar un deck
+## 3. Create the engine and load a deck
 
 ```ts
 const engine = new Lumina("#app", {
-  theme: "ocean",   // preset: default, ocean, midnight, forest, cyber, latte, sunset, monochrome
+  theme: "ocean",   // presets: default, ocean, midnight, forest, cyber, latte, sunset, monochrome
   loop: true,
   navigation: true,
   touch: true,
 });
 
 engine.load({
-  meta: { title: "Mi presentación" },
+  meta: { title: "My presentation" },
   slides: [
-    { type: "statement", title: "Título", subtitle: "Subtítulo" },
+    { type: "statement", title: "Title", subtitle: "Subtitle" },
     { type: "features", title: "Features", features: [
       { title: "A", desc: "Desc A", icon: "star" },
       { title: "B", desc: "Desc B", icon: "zap" },
@@ -49,34 +51,34 @@ engine.load({
 
 ---
 
-## 4. Actualizar el deck (patch)
+## 4. Update the deck (patch)
 
-Para cambios incrementales sin recargar todo:
+For incremental updates without reloading:
 
 ```ts
-engine.patch({ meta: { title: "Nuevo título" } });
-// slides se reemplaza por completo si lo pasas:
-// engine.patch({ slides: [...nuevosSlides] });
+engine.patch({ meta: { title: "New title" } });
+// slides are replaced entirely if provided:
+// engine.patch({ slides: [...newSlides] });
 ```
 
 ---
 
-## 5. Eventos
+## 5. Events
 
 ```ts
-engine.on("ready", (deck) => { /* deck cargado */ });
-engine.on("slideChange", ({ index, previousIndex, slide }) => { /* cambió la diapositiva */ });
+engine.on("ready", (deck) => { /* deck loaded */ });
+engine.on("slideChange", ({ index, previousIndex, slide }) => { /* slide changed */ });
 engine.on("action", (p) => {
-  // p: { type, label?, value? } — p.ej. clicks en botones
+  // p: { type, label?, value? } — e.g. button clicks
 });
-engine.on("error", (err) => { /* error interno */ });
+engine.on("error", (err) => { /* internal error */ });
 ```
 
-Para desuscribirse: `engine.off("slideChange", handler)` con la misma referencia de función.
+To unsubscribe: `engine.off("slideChange", handler)` with the same function reference.
 
 ---
 
-## 6. Navegación programática
+## 6. Programmatic navigation
 
 ```ts
 engine.next();
@@ -87,19 +89,19 @@ const i = engine.currentSlideIndex;
 
 ---
 
-## 7. Estado para el agente / LLM
+## 7. State for the agent / LLM
 
 ```ts
 const state = engine.exportState();
 // { status, currentSlide: { index, id, type, title }, narrative, engagementLevel, history }
-// Útil para incluir en el contexto de un LLM: "El usuario está en la diapositiva X, ha hecho Y".
+// Use in LLM context: "User is on slide X, did Y".
 ```
 
 ---
 
-## 8. Streaming desde un LLM
+## 8. Streaming from an LLM
 
-Cuando el modelo va devolviendo JSON por chunks:
+When the model streams JSON in chunks:
 
 ```ts
 import { Lumina, parsePartialJson } from "lumina-slides";
@@ -107,44 +109,44 @@ import { Lumina, parsePartialJson } from "lumina-slides";
 const engine = new Lumina("#app", { theme: "midnight" });
 let buffer = "";
 
-async function onStream(chunk: string) {
+function onStream(chunk) {
   buffer += chunk;
   const json = parsePartialJson(buffer);
   if (json) engine.load(json);
 }
 ```
 
-O con debounce para evitar parpadeos:
+Or with debounce to reduce flicker:
 
 ```ts
 import { createDebouncedLoader } from "lumina-slides";
 
 const onChunk = createDebouncedLoader((deck) => engine.load(deck), 80);
-// En el bucle de stream: onChunk(buffer);
+// In the stream loop: onChunk(buffer);
 ```
 
 ---
 
-## 9. Generar el system prompt para un LLM que crea slides
+## 9. Generate the system prompt for an LLM that creates slides
 
-Si un LLM va a generar el JSON del deck:
+If an LLM will generate the deck JSON:
 
 ```ts
 const systemPrompt = generateSystemPrompt({
-  mode: "fast",           // 'reasoning' si quieres CoT antes del JSON
+  mode: "fast",           // 'reasoning' for CoT before JSON
   includeSchema: true,
   includeTheming: true,
 });
-// Usar systemPrompt como mensaje de sistema en OpenAI, Anthropic, etc.
+// Use systemPrompt as the system message in OpenAI, Anthropic, etc.
 ```
 
-Solo temas: `generateThemePrompt()`.
+Theming only: `generateThemePrompt()`.
 
 ---
 
-## 10. Schema JSON
+## 10. JSON Schema
 
-Para validar o para dárselo al LLM:
+To validate or pass to the LLM:
 
 ```ts
 const schema = getLuminaJsonSchema();
@@ -152,9 +154,9 @@ const schema = getLuminaJsonSchema();
 
 ---
 
-## 11. Destruir la instancia
+## 11. Destroy the instance
 
-Al desmontar el componente o salir de la vista:
+When unmounting or leaving the view:
 
 ```ts
 engine.destroy();
@@ -162,11 +164,19 @@ engine.destroy();
 
 ---
 
-## Estructura de un `Deck`
+## Deck structure
 
 ```ts
 interface Deck {
-  meta: { title: string; author?: string; theme?: string; themeConfig?: ThemeConfig; [k: string]: any };
+  meta: {
+    title: string;
+    author?: string;
+    theme?: string;
+    themeConfig?: ThemeConfig;
+    elementControl?: { defaultVisible?: boolean };  // false = all hidden by default
+    initialElementState?: { [id: string]: { visible?: boolean; opacity?: number; transform?: string; class?: string; style?: Record<string, string | number> } };
+    [k: string]: any;
+  };
   slides: Array<
     | { type: "statement"; title: string; subtitle?: string; tag?: string; notes?: string }
     | { type: "features"; title: string; features: { title: string; desc: string; icon?: string }[]; description?: string; notes?: string }
@@ -181,12 +191,228 @@ interface Deck {
 }
 ```
 
-Los tipos detallados están en el paquete: `Deck`, `SlideStatement`, `SlideFeatures`, `LuminaOptions`, `LuminaEventMap`, etc.
+Detailed types in the package: `Deck`, `SlideStatement`, `SlideFeatures`, `LuminaOptions`, `LuminaEventMap`, etc.
+
+---
+
+## Element IDs and `data-lumina-id` (vanilla JS / JSON API)
+
+The library assigns a `data-lumina-id` attribute to each controllable element when **rendering the deck from JSON**. You use only `engine.load(deck)` and the engine API; no framework or component code is required.
+
+**ID resolution order:** (1) `slide.id` for the root; (2) if the object at that path has `id: string`, it is used; (3) `slide.ids[path]` if present; (4) fallback `s{N}-{path}` (e.g. `s0-tag`, `s1-features-2`).
+
+**Discovering IDs from vanilla JS:** `engine.elements(slideIndex)` returns the array of ids for that slide. To predict ids without mounting: `getElementIds(slide, slideIndex)` or `resolveId(slide, slideIndex, path)` / `elemId(slideIndex, ...path)` (exported for advanced use).
+
+**Paths per slide type** (default id is `s{N}-{path}`):
+
+| Type     | Paths (e.g. `s0-tag`, `s1-features-0`) |
+|----------|----------------------------------------|
+| statement| `tag`, `title`, `subtitle`             |
+| features | `header`, `features.0`, `features.1`…  |
+| half     | `media`, `tag`, `title`, `paragraphs`, `cta` |
+| timeline | `title`, `subtitle`, `timeline.0`…     |
+| steps    | `header`, `steps.0`, `steps.1`…        |
+| flex     | `elements.0`, `elements.0.elements.0`… |
+| chart    | `title`, `subtitle`, `chart`           |
+| video    | `video`, `title`                       |
+| diagram  | `nodes.0`, `nodes.1`…, `edges.0`…      |
+| custom   | (none by default)                      |
+
+**Control from JSON:**
+
+- `meta.initialElementState`: `{ [id]: { visible?: false, opacity?, transform?, class?, style? } }` — initial state when the deck loads.
+- `meta.elementControl`: `{ defaultVisible?: boolean }` — if `false`, all elements start hidden; override per id with `initialElementState`.
+
+**APIs (vanilla JS):** `engine.element(id)`, `engine.element(slideIndex, path)`, `engine.getElementById(id)`, `engine.elements(slideIndex)`.
+
+---
+
+## Element control and animations (vanilla JS)
+
+Use `engine.element(id)` or `engine.element(slideIndex, path)` to get an **ElementController**:
+
+- **Visibility:** `.show()`, `.hide()`, `.toggle(force?)`
+- **Style:** `.opacity(n)`, `.transform(s)`, `.css({ ... })`, `.addClass(name)`, `.removeClass(name)`
+- **Animations:** `.animate({ from?, to, duration?, ease?, onComplete? })`, `.animateAsync(...)`
+
+`engine.getElementById(id)` returns the DOM node with `data-lumina-id`, or `null` if the slide is not mounted. Animations (GSAP) are no-op when the node is null.
+
+**Avoiding null / no visible effect:** The element must be in the DOM when you call `.show()` or `.animate()`. Pattern in **vanilla JS**:
+
+1. **Register `ready` and `slideChange` before `engine.load(deck)`** so callbacks run when the deck/slide is mounted.
+
+2. **In `ready`:** use `setTimeout` (e.g. `(i + 1) * 700` ms per element) before each `engine.element(id).show()` for the first slide.
+
+3. **In `slideChange`:** when `index` is the slide with controlled elements, repeat the same `setTimeout` + `.show()` for that slide’s ids.
+
+4. **Order:** `new Lumina(...)` → `engine.on('ready', ...)` → `engine.on('slideChange', ...)` → `engine.load(deck)`.
+
+**Example (vanilla JS) — simple reveal with delay:**
+
+```js
+const engine = new Lumina("#app", { theme: "midnight" });
+
+engine.on("ready", (deck) => {
+  const ids = engine.elements(0);
+  ids.forEach((id, i) => {
+    setTimeout(() => engine.element(id).show(), (i + 1) * 500);
+  });
+});
+
+engine.on("slideChange", ({ index }) => {
+  const ids = engine.elements(index);
+  ids.forEach((id, i) => {
+    setTimeout(() => engine.element(id).show(), (i + 1) * 500);
+  });
+});
+
+engine.load({
+  meta: {
+    title: "Reveal",
+    elementControl: { defaultVisible: false },
+    initialElementState: { "s0-tag": { visible: false }, "s0-title": { visible: false }, "s0-subtitle": { visible: false } },
+  },
+  slides: [{ type: "statement", title: "Hello", subtitle: "World", tag: "Intro" }],
+});
+```
+
+---
+
+## Delay-controlled animations (vanilla JS, no Vue)
+
+Staggered reveals and per-element animations are driven from vanilla JS using `setTimeout`, `engine.element(id).show()`, and `engine.element(id).animate()`. Register `ready` and `slideChange` **before** `engine.load(deck)`.
+
+**Helper to reveal a slide’s elements with delay and optional animation:**
+
+```js
+/**
+ * Reveal all elements of a slide with staggered delay. Pure JavaScript, no Vue.
+ * @param {import('lumina-slides').Lumina} engine
+ * @param {number} slideIndex
+ * @param {Object} [opts]
+ * @param {number} [opts.delayMs=500] - Delay between each element (ms).
+ * @param {boolean} [opts.animate=true] - If true, animate from { opacity: 0, y: 20 } to { opacity: 1, y: 0 }.
+ * @param {number} [opts.animDuration=0.5] - Animation duration in seconds.
+ */
+function revealSlideWithDelay(engine, slideIndex, opts = {}) {
+  const { delayMs = 500, animate = true, animDuration = 0.5 } = opts;
+  const ids = engine.elements(slideIndex);
+  if (!ids || !ids.length) return;
+
+  ids.forEach((id, i) => {
+    const t = (i + 1) * delayMs;
+    setTimeout(() => {
+      const el = engine.element(id);
+      el.show();
+      if (animate) {
+        el.animate({
+          from: { opacity: 0, y: 20 },
+          to: { opacity: 1, y: 0 },
+          duration: animDuration,
+          ease: "power2.out",
+        });
+      }
+    }, t);
+  });
+}
+```
+
+**Full HTML + vanilla JS example (delay-controlled animations):**
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Lumina – delay-controlled animations (vanilla JS)</title>
+  <link rel="stylesheet" href="node_modules/lumina-slides/dist/style.css" />
+</head>
+<body>
+  <div id="app" style="width:100vw;height:100vh;"></div>
+  <script type="module">
+    import { Lumina } from "lumina-slides";
+
+    const engine = new Lumina("#app", { theme: "midnight" });
+
+    function revealSlideWithDelay(engine, slideIndex, opts = {}) {
+      const { delayMs = 500, animate = true, animDuration = 0.5 } = opts;
+      const ids = engine.elements(slideIndex);
+      if (!ids || !ids.length) return;
+      ids.forEach((id, i) => {
+        setTimeout(() => {
+          engine.element(id).show();
+          if (animate) {
+            engine.element(id).animate({
+              from: { opacity: 0, y: 20 },
+              to: { opacity: 1, y: 0 },
+              duration: animDuration,
+              ease: "power2.out",
+            });
+          }
+        }, (i + 1) * delayMs);
+      });
+    }
+
+    // Must register before load so callbacks run when DOM is ready
+    engine.on("ready", () => revealSlideWithDelay(engine, 0, { delayMs: 600, animDuration: 0.5 }));
+    engine.on("slideChange", ({ index }) => revealSlideWithDelay(engine, index, { delayMs: 600, animDuration: 0.5 }));
+
+    engine.load({
+      meta: {
+        title: "Staggered reveal",
+        elementControl: { defaultVisible: false },
+        initialElementState: {
+          "s0-tag": { visible: false },
+          "s0-title": { visible: false },
+          "s0-subtitle": { visible: false },
+          "s1-header": { visible: false },
+          "s1-features-0": { visible: false },
+          "s1-features-1": { visible: false },
+        },
+      },
+      slides: [
+        { type: "statement", title: "Welcome", subtitle: "Each line appears with a delay", tag: "Intro" },
+        { type: "features", title: "Highlights", features: [
+          { title: "First", desc: "Revealed after 600ms", icon: "star" },
+          { title: "Second", desc: "Revealed after 1200ms", icon: "zap" },
+        ]},
+      ],
+    });
+  </script>
+</body>
+</html>
+```
+
+**Animation-only (no show/hide), with custom stagger:**
+
+```js
+engine.on("ready", () => {
+  const ids = engine.elements(0);
+  ids.forEach((id, i) => {
+    setTimeout(() => {
+      engine.element(id).animate({
+        from: { opacity: 0, scale: 0.95 },
+        to: { opacity: 1, scale: 1 },
+        duration: 0.6,
+        ease: "back.out(1.2)",
+      });
+    }, i * 400);
+  });
+});
+```
+
+---
+
+## Animation options (engine and deck)
+
+- **Engine options:** `options.animation: { enabled?: boolean, type?: 'fade'|'cascade'|'zoom', durationIn?, durationOut? }` when creating `new Lumina(selector, options)`.
+- **Slide transitions** are applied by the engine; you listen to `slideChange` for timing.
+- **Per-element animations** are done with `engine.element(id).animate({ from: { opacity: 0, y: 20 }, to: { opacity: 1, y: 0 }, duration: 0.5 })` from vanilla JS.
 
 ---
 
-## Dónde seguir
+## Where to go next
 
-- **API y tipos**: los JSDoc en el código y los `.d.ts` generados.
-- **Guía para agentes que generan slides**: [AGENTS.md](./AGENTS.md).
-- **Docs y playground**: [lumina-slides](https://pailletjuanpablo.github.io/lumina-slides/).
+- **API and types:** JSDoc in the code and generated `.d.ts`.
+- **Guide for agents that generate slides:** [AGENTS.md](./AGENTS.md).
+- **Docs and playground:** [lumina-slides](https://pailletjuanpablo.github.io/lumina-slides/).