taleem-slides 0.3.0 → 0.5.0

package/README.md

@@ -1,224 +1,363 @@
 
+
 # 📦 taleem-slides
 
-> **Deterministic slide interpretation & rendering engine for deck-v1**
+## ⚠️ Warning: Work in Progress — expect breaking changes
+
+> **Pure slide template library for Taleem decks**
+
+`taleem-slides` is a **simple, deterministic template library** that turns
+**deck-style slide JSON** into **HTML**.
+
+It does **one thing only**:
+
+> **Given slide data + render state → return HTML**
+
+It does **not** manage time, indexes, playback, or decks.
+
+---
+
+## 🌐 Live Display Center (Important)
+
+👉 **Official live display & reference implementation**
+**[https://bilza2023.github.io/taleem/](https://bilza2023.github.io/taleem/)**
+
+This is **not a mock demo**.
+This link is the **active display center** where:
+
+* slide templates are rendered in real browsers
+* visual behavior is validated
+* browser / player integration is tested
+
+---
+
+## ✨ Taleem.help Philosophy
+
+**Taleem.help** is an educational technology initiative focused on making
+**content-first learning tools**.
+
+The goal of the `taleem-*` libraries is simple:
+
+> Enable educators to create **JSON-based presentations**
+> and display them online using **free, open tools**.
+
+### Key ideas
+
+* Slides already encode *layout + structure*
+* Users provide **content only**
+* There are **no configuration knobs**
+* What you see is what the template decides
 
-`taleem-slides` is a **pure, test-locked rendering layer**.
-It takes a validated `deck-v1` JSON and produces **deterministic HTML output** through a strict public API.
+This removal of choice is **intentional**.
 
-This project does **not**:
+It makes the system:
+
+* easy to learn
+* hard to misuse
+* consistent across platforms
+
+If a different layout is needed, the solution is **not configuration** —
+it is **a new slide template**.
+
+Templates are cheap.
+Even hundreds of templates add no runtime cost.
+
+---
+
+## ✨ What this library is
+
+* A collection of **slide templates**
+* Each template:
+
+  * reads slide JSON
+  * renders HTML
+  * applies CSS classes based on a given state
+* Fully **stateless** and **pure**
+
+Think of it as:
+
+> *Handlebars / JSX for Taleem slides*
+
+---
+
+## ❌ What this library is NOT
+
+`taleem-slides` does **not**:
 
 * build decks
+* validate full decks
+* manage timing (`showAt`)
+* decide which slide is active
+* manage playback
 * mutate data
-* manage timing state
-* expose slide internals
 
-It only **interprets** and **renders**.
+All of that belongs elsewhere.
 
 ---
 
 ## 🧠 Mental Model
 
 ```
-deck-v1 JSON
-   ↓
-slideBuilder()
-   ↓
-SlideManager
-   ↓
-renderSlide(index [, showAt])
+slide JSON + render state
+        ↓
+   slide template
+        ↓
+       HTML
 ```
 
-Key idea:
-**Slides are private. Rendering is the only contract.**
+How the state is calculated is **not this library’s concern**.
 
 ---
 
-## ✅ What This Project Guarantees
+## 📦 Installation
 
-* Deterministic rendering (same input → same HTML)
-* Strict validation per slide type
-* Zero mutation after build
-* No access to internal slide objects
-* Full test coverage across all slide types
+```bash
+npm install taleem-slides
+```
 
 ---
 
-## 🔑 Public API
+## 🚀 Basic Usage
 
-### `slideBuilder(deckV1Json) → SlideManager`
-
-Builds and validates a deck, returning a `SlideManager`.
+### 1️⃣ Import a template
 
 ```js
-import { slideBuilder } from "taleem-slides";
-
-const manager = slideBuilder(deckJson);
+import { getSlideTemplate } from "taleem-slides";
 ```
 
-Throws immediately on:
+---
 
-* invalid deck structure
-* unsupported slide types
-* invalid slide data
+### 2️⃣ Load slide data (once)
 
----
+```js
+const SlideTemplate = getSlideTemplate("bulletList");
+
+const slide = SlideTemplate.fromJSON({
+  type: "bulletList",
+  data: [
+    { name: "bullet", content: "First point" },
+    { name: "bullet", content: "Second point" },
+    { name: "bullet", content: "Third point" }
+  ]
+});
+```
+
+> `fromJSON()` only **reads and stores structure**.
+> No timing. No logic.
 
-### `SlideManager.renderSlide(index, showAt?) → string`
+---
 
-Renders **one slide** to HTML.
+### 3️⃣ Render with state
 
 ```js
-const html = manager.renderSlide(0);
+const html = slide.render({
+  visibleCount: 2,
+  activeIndex: 1
+});
 ```
 
-Notes:
+This will:
 
-* `index` is zero-based
-* `showAt` is optional (for time-aware slides)
-* return value is **plain HTML string**
+* render first 2 bullets
+* highlight the second bullet
+* dim the first
 
 ---
 
-### `SlideManager.renderAll() → string`
+## 🎨 Render State Contract
 
-Renders **all slides** as a static HTML dump.
+Templates accept a **render state object**.
 
-```js
-const fullHtml = manager.renderAll();
+Common fields:
+
+```ts
+{
+  visibleCount?: number; // how many items exist
+  activeIndex?: number;  // which item is highlighted
+}
 ```
 
+Slides may choose to use one or both.
+
 ---
 
-## 🔒 Encapsulation Rules (By Design)
+## 🎯 Class Name Contract
+
+Templates apply **standard class names only**:
 
-* `SlideManager` does **not** expose slides
-* Slides are frozen internally
-* Rendered output is a string (immutable by nature)
+```text
+.is-active
+.is-dim
+.is-hidden
+```
 
-If you want to *inspect structure*, that belongs in **taleem-core**, not here.
+Styling is handled entirely by the consuming app.
 
 ---
 
-## 🧪 Testing Philosophy
+## 🧭 How this fits in the ecosystem
 
-This project has **56 passing tests** covering:
+`taleem-slides` is intentionally **small** and **focused**.
 
-* slideBuilder validation
-* every slide type
-* deterministic rendering
-* error handling
-* edge cases
+It is used by higher-level projects:
 
-Tests assert **behavior**, not snapshots.
+### 🧩 Sister Projects
 
-This test suite is the **living specification**.
+* **taleem-browser**
+  Index-based slide viewer (manual navigation)
 
----
+* **taleem-player**
+  Time-based slide player (audio / video synced)
+
+Both projects:
 
-## 🎞️ Supported Slide Types
+* compute render state (`activeIndex`, `visibleCount`)
+* pass it to `taleem-slides`
+* receive consistent HTML output
 
-`taleem-slides` supports all canonical `deck-v1` slide types, including:
+---
+
+## 🧪 Demo & Reference Projects
 
-* titleSlide
-* titleAndSubtitle
-* titleAndPara
-* bulletList
-* twoColumnText
-* imageSlide
-* imageWithTitle
-* imageWithCaption
-* imageLeftBulletsRight
-* imageRightBulletsLeft
-* table
-* statistic
-* donutChart
-* barChart
-* bigNumber
-* quoteSlide
-* quoteWithImage
-* cornerWordsSlide
-* contactSlide
-* fillImage
-* eq
-* svgPointer
+* 🌐 **Live Display Center**
+  [https://bilza2023.github.io/taleem/](https://bilza2023.github.io/taleem/)
 
-All validation rules are enforced at build time.
+* 📁 **GitHub Demo / Playground**
+  *(link can be added here when ready)*
 
 ---
 
-## 🧊 Versioning & Stability
+## 🧊 Stability & Versioning
 
-* This project targets **deck-v1 only**
-* No breaking changes without `deck-v2`
-* Rendering output is intentionally simple HTML
-* Styling is the responsibility of the consuming app
+* Targets **deck-v1**
+* Breaking changes allowed during WIP phase
+* HTML output is intentionally simple and predictable
 
 ---
 
-## 📍 When to Use This
+## 🧠 Design Principle (Locked)
 
-Use `taleem-slides` when you want:
+> **taleem-slides renders HTML.
+> It does not decide *when* or *why*.**
 
-* a **trustworthy rendering engine**
-* clean separation from content generation
-* confidence that slides behave exactly as specified
+---
 
-Do **not** use it for:
+## 🔳 Deck Background Support (NEW)
 
-* authoring decks
-* editing slides
-* managing playback state
+`taleem-slides` also defines **how deck backgrounds are resolved**, while remaining fully **DOM-agnostic**.
+
+A deck background is **optional** and applies to the **entire deck**, not individual slides.
 
 ---
 
+### Background responsibility split
+
+#### taleem-slides
+
+* decides **what background should be used**
+* exposes a **pure resolver function**
+* returns **plain background data**
+
+#### player / browser
+
+* renders the background into the DOM
+* applies styles and layout
+* handles mounting and lifecycle
+
+This keeps slide rendering **pure and portable**.
+
 ---
 
-# 🧠 taleem-core (Contextual Overview)
+## 🎨 Background Resolution API
 
-> **Authoring & specification layer for deck-v1**
+`taleem-slides` exports a small helper:
 
-`taleem-core` is responsible for **creating valid decks**.
-`taleem-slides` is responsible for **rendering them**.
+```js
+import { resolveBackground } from "taleem-slides";
+```
+
+### Purpose
+
+`resolveBackground` answers one question only:
+
+> **“What background should be used for this deck?”**
 
-They are intentionally separate.
+It does **not**:
+
+* touch the DOM
+* inject styles
+* manage themes
+* animate or time anything
+
+---
+
+### Input (conceptual)
+
+```ts
+{
+  deckBackground?: {
+    backgroundColor?: string
+    backgroundImage?: string
+    backgroundImageOpacity?: number
+  },
+  themeSurfaceColor?: string
+}
+```
 
 ---
 
-## Responsibility Split
+### Output
 
-| Concern             | taleem-core | taleem-slides |
-| ------------------- | ----------- | ------------- |
-| Deck creation       | ✅           | ❌             |
-| Schema validation   | ✅           | ❌             |
-| EQ expansion        | ✅           | ❌             |
-| Timing rules        | ✅           | ❌             |
-| Rendering HTML      | ❌           | ✅             |
-| Slide encapsulation | ❌           | ✅             |
+```ts
+{
+  backgroundColor?: string
+  backgroundImage?: string
+  backgroundImageOpacity?: number
+}
+```
 
 ---
 
-## Core Artifacts
+### Resolution rules (locked)
+
+* If the deck defines a background → **use it**
+* Otherwise → **fall back to the theme’s surface color**
+
+These rules are **format-level guarantees**, not rendering behavior.
+
+---
 
-From the docs you uploaded:
+## 🧠 Mental Model (Updated)
 
-* `api.md` → defines **deck-v1 contract**
-* `eq.md` → defines **EQ slide expansion rules**
-* `timings.md` → defines **global timing semantics**
+```
+deck JSON + render state + theme surface
+        ↓
+   taleem-slides
+        ↓
+HTML + resolved background data
+        ↓
+player / browser
+        ↓
+        DOM
+```
 
-`taleem-slides` **trusts** these documents.
-It does not reinterpret them.
+`taleem-slides` decides **what exists**.
+The player / browser decides **how it appears**.
 
 ---
 
-## Architectural Law (Important)
+## 🔒 Design Principle (Extended)
 
-> **Authoring and rendering must never mix**
+> **taleem-slides renders HTML and resolves deck-level intent.
+> It never touches the DOM and never manages playback.**
 
-Once a deck enters `taleem-slides`, it is:
+---
 
-* assumed valid
-* treated as immutable
-* rendered deterministically
+## ✅ What this achieves
 
-This is why the system scales cleanly.
+* background rules are centralized
+* players remain simple
+* browsers stay dumb
+* future renderers (CLI, SSR, export) stay possible
+
+---

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "taleem-slides",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
-  "description": "Pure slide interpretation engine for deck-v1 (no DOM, no UI)",
+  "description": "Convert json taleem schema into html for slides",
 
   "exports": {
     ".": "./src/index.js"

package/src/{registry.js → SlideTemplates.js}

@@ -27,7 +27,7 @@ import { ContactSlide } from "./slides/ContactSlide.js";
 import { EqSlide } from "./slides/EqSlide.js";
 import { SvgPointerSlide } from "./slides/SvgPointerSlide.js";
 
-export const registry = {
+export const SlideTemplates = {
   titleSlide: TitleSlide,
   titleAndSubtitle: TitleAndSubtitleSlide,
   titleAndPara: TitleAndParaSlide,

package/src/getSlideTemplate.js

@@ -0,0 +1,12 @@
+// src/getSlideTemplate.js
+import { SlideTemplates } from "./SlideTemplates.js";
+
+export function getSlideTemplate(type) {
+  const template = SlideTemplates[type];
+
+  if (!template) {
+    throw new Error(`Unknown slide template type "${type}"`);
+  }
+
+  return template;
+}

package/src/index.js

@@ -1,5 +1,5 @@
-
 // src/index.js
 
-export { slideBuilder } from "./interpreter/slideBuilder.js";
-
+export { SlideTemplates } from "./SlideTemplates.js";
+export { getSlideTemplate } from "./getSlideTemplate.js";
+export { resolveBackground } from "./resolveBackground.js";

package/src/resolveBackground.js

@@ -0,0 +1,10 @@
+export function resolveBackground({ deckBackground, theme }) {
+    if (deckBackground) return deckBackground;
+  
+    return {
+      backgroundColor: theme.surfaceColor,
+      backgroundImage: null,
+      backgroundImageOpacity: 1
+    };
+  }
+  

package/src/slides/BarChartSlide.js

@@ -1,44 +1,46 @@
+// BarChartSlide.js
 export const BarChartSlide = {
-    type: "barChart",
-  
-    fromJSON(raw) {
-      const bars = raw.data?.filter(d => d.name === "bar");
-  
-      if (!bars || bars.length === 0) {
-        throw new Error("barChart: requires at least one bar");
-      }
-  
-      // validate bar structure
-      bars.forEach((b, i) => {
-        if (
-          typeof b.content !== "object" ||
-          typeof b.content.label !== "string" ||
-          typeof b.content.value !== "number"
-        ) {
-          throw new Error(`barChart: invalid bar at index ${i}`);
-        }
-      });
-  
-      return Object.freeze({
-        type: "barChart",
-  
-        render() {
-          return `
-            <section class="slide barChart">
-              <ul class="bars">
-                ${bars.map(
-                  b => `
-                    <li class="bar">
-                      <span class="bar-label">${b.content.label}</span>
-                      <span class="bar-value">${b.content.value}</span>
-                    </li>
-                  `
-                ).join("")}
-              </ul>
-            </section>
-          `;
-        }        
-      });
+  type: "barChart",
+
+  fromJSON(raw) {
+    const bars = raw.data
+      ?.filter(d => d.name === "bar")
+      .map(d => ({
+        label: d.content.label,
+        value: d.content.value
+      }));
+
+    if (!bars?.length) {
+      throw new Error("barChart: requires at least one bar");
     }
-  };
-  
+
+    return Object.freeze({
+      type: "barChart",
+      bars,
+
+      render({ visibleCount = bars.length, activeIndex = null } = {}) {
+        return `
+          <section class="slide barChart">
+            <ul class="bars">
+              ${bars.map((b, i) => {
+                if (i >= visibleCount) return "";
+                const cls =
+                  i === activeIndex
+                    ? "is-active"
+                    : i < activeIndex
+                    ? "is-dim"
+                    : "";
+                return `
+                  <li class="bar ${cls}">
+                    <span class="bar-label">${b.label}</span>
+                    <span class="bar-value">${b.value}</span>
+                  </li>
+                `;
+              }).join("")}
+            </ul>
+          </section>
+        `;
+      }
+    });
+  }
+};

package/src/slides/BigNumberSlide.js

@@ -1,24 +1,26 @@
+// BigNumberSlide.js
 export const BigNumberSlide = {
-    type: "bigNumber",
-  
-    fromJSON(raw) {
-      const value = raw.data?.find(d => d.name === "number")?.content;
-      const label = raw.data?.find(d => d.name === "label")?.content;
-  
-      if (!value) throw new Error("bigNumber: number required");
-  
-      return Object.freeze({
-        type: "bigNumber",
-        render() {
-          return `
-            <section class="slide bigNumber">
-              <div class="number">${value}</div>
-              ${label ? `<div class="label">${label}</div>` : ""}
-            </section>
-          `;
-        }
-        
-      });
-    }
-  };
-  
+  type: "bigNumber",
+
+  fromJSON(raw) {
+    const value = raw.data?.find(d => d.name === "number")?.content;
+    const label = raw.data?.find(d => d.name === "label")?.content;
+
+    if (!value) throw new Error("bigNumber: number required");
+
+    return Object.freeze({
+      type: "bigNumber",
+      value,
+      label,
+
+      render() {
+        return `
+          <section class="slide bigNumber">
+            <div class="number">${value}</div>
+            ${label ? `<div class="label">${label}</div>` : ""}
+          </section>
+        `;
+      }
+    });
+  }
+};