taleem-slides 0.3.0 → 0.4.0

package/README.md

@@ -1,224 +1,247 @@
 
 # 📦 taleem-slides
 
-> **Deterministic slide interpretation & rendering engine for deck-v1**
+## ⚠️  Warning :  Work in Progress — expect breaking changes
 
-`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.
+> **Pure slide template library for Taleem decks**
 
-This project does **not**:
+`taleem-slides` is a **simple, deterministic template library** that turns
+**deck-style slide JSON** into **HTML**.
 
-* build decks
-* mutate data
-* manage timing state
-* expose slide internals
+It does **one thing only**:
+
+> **Given slide data + render state → return HTML**
 
-It only **interprets** and **renders**.
+It does **not** manage time, indexes, playback, or decks.
 
 ---
 
-## 🧠 Mental Model
+## 🌐 Live Display Center (Important)
 
-```
-deck-v1 JSON
-   ↓
-slideBuilder()
-   ↓
-SlideManager
-   ↓
-renderSlide(index [, showAt])
-```
+👉 **Official live display & reference implementation**
+**[https://bilza2023.github.io/taleem/](https://bilza2023.github.io/taleem/)**
 
-Key idea:
-**Slides are private. Rendering is the only contract.**
+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
 ---
 
-## ✅ What This Project Guarantees
+## ✨ Taleem.help Philosophy
 
-* 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
+**Taleem.help** is an educational technology initiative focused on making
+**content-first learning tools**.
 
----
+The goal of the `taleem-*` libraries is simple:
 
-## 🔑 Public API
+> Enable educators to create **JSON-based presentations**
+> and display them online using **free, open tools**.
 
-### `slideBuilder(deckV1Json) → SlideManager`
+Key ideas:
 
-Builds and validates a deck, returning a `SlideManager`.
+* Slides already encode *layout + structure*
+* Users provide **content only**
+* There are **no configuration knobs**
+* What you see is what the template decides
 
-```js
-import { slideBuilder } from "taleem-slides";
+This removal of choice is **intentional**.
 
-const manager = slideBuilder(deckJson);
-```
+It makes the system:
 
-Throws immediately on:
+* easy to learn
+* hard to misuse
+* consistent across platforms
 
-* invalid deck structure
-* unsupported slide types
-* invalid slide data
+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.
 
 ---
 
-### `SlideManager.renderSlide(index, showAt?) → string`
+## ✨ What this library is
 
-Renders **one slide** to HTML.
+* A collection of **slide templates**
+* Each template:
 
-```js
-const html = manager.renderSlide(0);
-```
+  * reads slide JSON
+  * renders HTML
+  * applies CSS classes based on a given state
+* Fully **stateless** and **pure**
 
-Notes:
+Think of it as:
 
-* `index` is zero-based
-* `showAt` is optional (for time-aware slides)
-* return value is **plain HTML string**
+> *Handlebars / JSX for Taleem slides*
 
 ---
 
-### `SlideManager.renderAll() → string`
+## ❌ What this library is NOT
 
-Renders **all slides** as a static HTML dump.
+`taleem-slides` does **not**:
 
-```js
-const fullHtml = manager.renderAll();
-```
+* build decks
+* validate full decks
+* manage timing (`showAt`)
+* decide which slide is active
+* manage playback
+* mutate data
+
+All of that belongs elsewhere.
 
 ---
 
-## 🔒 Encapsulation Rules (By Design)
+## 🧠 Mental Model
 
-* `SlideManager` does **not** expose slides
-* Slides are frozen internally
-* Rendered output is a string (immutable by nature)
+```
+slide JSON + render state
+        ↓
+   slide template
+        ↓
+       HTML
+```
 
-If you want to *inspect structure*, that belongs in **taleem-core**, not here.
+How the state is calculated is **not this library’s concern**.
 
 ---
 
-## 🧪 Testing Philosophy
+## 📦 Installation
 
-This project has **56 passing tests** covering:
+```bash
+npm install taleem-slides
+```
 
-* slideBuilder validation
-* every slide type
-* deterministic rendering
-* error handling
-* edge cases
+---
 
-Tests assert **behavior**, not snapshots.
+## 🚀 Basic Usage
 
-This test suite is the **living specification**.
+### 1️⃣ Import a template
 
----
+```js
+import { getSlideTemplate } from "taleem-slides";
+```
 
-## 🎞️ Supported Slide Types
+---
 
-`taleem-slides` supports all canonical `deck-v1` slide types, including:
+### 2️⃣ Load slide data (once)
 
-* titleSlide
-* titleAndSubtitle
-* titleAndPara
-* bulletList
-* twoColumnText
-* imageSlide
-* imageWithTitle
-* imageWithCaption
-* imageLeftBulletsRight
-* imageRightBulletsLeft
-* table
-* statistic
-* donutChart
-* barChart
-* bigNumber
-* quoteSlide
-* quoteWithImage
-* cornerWordsSlide
-* contactSlide
-* fillImage
-* eq
-* svgPointer
+```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" }
+  ]
+});
+```
 
-All validation rules are enforced at build time.
+> `fromJSON()` only **reads and stores structure**.
+> No timing. No logic.
 
 ---
 
-## 🧊 Versioning & Stability
+### 3️⃣ Render with state
 
-* 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
+```js
+const html = slide.render({
+  visibleCount: 2,
+  activeIndex: 1
+});
+```
+
+This will:
+
+* render first 2 bullets
+* highlight the second bullet
+* dim the first
 
 ---
 
-## 📍 When to Use This
+## 🎨 Render State Contract
 
-Use `taleem-slides` when you want:
+Templates accept a **render state object**.
 
-* a **trustworthy rendering engine**
-* clean separation from content generation
-* confidence that slides behave exactly as specified
+Common fields:
 
-Do **not** use it for:
+```ts
+{
+  visibleCount?: number; // how many items exist
+  activeIndex?: number;  // which item is highlighted
+}
+```
 
-* authoring decks
-* editing slides
-* managing playback state
+Slides may choose to use one or both.
 
 ---
 
+## 🎯 Class Name Contract
+
+Templates apply **standard class names only**:
+
+```text
+.is-active
+.is-dim
+.is-hidden
+```
+
+Styling is handled entirely by the consuming app.
+
 ---
 
-# 🧠 taleem-core (Contextual Overview)
+## 🧭 How this fits in the ecosystem
 
-> **Authoring & specification layer for deck-v1**
+`taleem-slides` is intentionally **small** and **focused**.
 
-`taleem-core` is responsible for **creating valid decks**.
-`taleem-slides` is responsible for **rendering them**.
+It is used by higher-level projects:
 
-They are intentionally separate.
+### 🧩 Sister Projects
 
----
+* **taleem-browser**
+  Index-based slide viewer (manual navigation)
+
+* **taleem-player**
+  Time-based slide player (audio / video synced)
 
-## Responsibility Split
+Both projects:
 
-| Concern             | taleem-core | taleem-slides |
-| ------------------- | ----------- | ------------- |
-| Deck creation       | ✅           | ❌             |
-| Schema validation   | ✅           | ❌             |
-| EQ expansion        | ✅           | ❌             |
-| Timing rules        | ✅           | ❌             |
-| Rendering HTML      | ❌           | ✅             |
-| Slide encapsulation | ❌           | ✅             |
+* compute render state (`activeIndex`, `visibleCount`)
+* pass it to `taleem-slides`
+* receive consistent HTML output
 
 ---
 
-## Core Artifacts
+## 🧪 Demo & Reference Projects
 
-From the docs you uploaded:
+* 🌐 **Live Display Center**
+  [https://bilza2023.github.io/taleem/](https://bilza2023.github.io/taleem/)
 
-* `api.md` → defines **deck-v1 contract**
-* `eq.md` → defines **EQ slide expansion rules**
-* `timings.md` → defines **global timing semantics**
+* 📁 **GitHub Demo / Playground**
+  *(link can be added here when ready)*
 
-`taleem-slides` **trusts** these documents.
-It does not reinterpret them.
+---
+
+## 🧊 Stability & Versioning
+
+* Targets **deck-v1**
+* Breaking changes allowed during WIP phase
+* HTML output is intentionally simple and predictable
 
 ---
 
-## Architectural Law (Important)
+## 🧠 Design Principle (Locked)
 
-> **Authoring and rendering must never mix**
+> **taleem-slides renders HTML.
+> It does not decide *when* or *why*.**
+
+---
 
-Once a deck enters `taleem-slides`, it is:
+If you want, next logical steps are:
 
-* assumed valid
-* treated as immutable
-* rendered deterministically
+* rewrite one slide as the **canonical reference**
+* or update taleem-browser to consume the new API cleanly
 
-This is why the system scales cleanly.
+This README now correctly **anchors the entire ecosystem**.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "taleem-slides",
-  "version": "0.3.0",
+  "version": "0.4.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,4 @@
-
 // src/index.js
 
-export { slideBuilder } from "./interpreter/slideBuilder.js";
-
+export { SlideTemplates } from "./SlideTemplates.js";
+export { getSlideTemplate } from "./getSlideTemplate.js";

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>
+        `;
+      }
+    });
+  }
+};

package/src/slides/BulletListSlide.js

@@ -1,26 +1,38 @@
+// BulletListSlide.js
 export const BulletListSlide = {
-    type: "bulletList",
-  
-    fromJSON(raw) {
-      const bullets = raw.data?.filter(d => d.name === "bullet").map(d => d.content);
-  
-      if (!bullets || bullets.length === 0) {
-        throw new Error("bulletList: requires at least one bullet");
-      }
-  
-      return Object.freeze({
-        type: "bulletList",
-        render() {
-          return `
-            <section class="slide bulletList">
-              <ul>
-                ${bullets.map(b => `<li>${b}</li>`).join("")}
-              </ul>
-            </section>
-          `;
-        }
-        
-      });
+  type: "bulletList",
+
+  fromJSON(raw) {
+    const bullets = raw.data
+      ?.filter(d => d.name === "bullet")
+      .map(d => ({ content: d.content }));
+
+    if (!bullets?.length) {
+      throw new Error("bulletList: requires at least one bullet");
     }
-  };
-  
+
+    return Object.freeze({
+      type: "bulletList",
+      bullets,
+
+      render({ visibleCount = bullets.length, activeIndex = null } = {}) {
+        return `
+          <section class="slide bulletList">
+            <ul>
+              ${bullets.map((b, i) => {
+                if (i >= visibleCount) return "";
+                const cls =
+                  i === activeIndex
+                    ? "is-active"
+                    : i < activeIndex
+                    ? "is-dim"
+                    : "";
+                return `<li class="${cls}">${b.content}</li>`;
+              }).join("")}
+            </ul>
+          </section>
+        `;
+      }
+    });
+  }
+};

package/src/slides/ContactSlide.js

@@ -1,22 +1,25 @@
+// ContactSlide.js
 export const ContactSlide = {
-    type: "contactSlide",
-  
-    fromJSON(raw) {
-      const items = raw.data?.map(d => `<div>${d.content}</div>`);
-  
-      if (!items?.length) throw new Error("contactSlide: content required");
-  
-      return Object.freeze({
-        type: "contactSlide",
-        render() {
-          return `
-            <section class="slide contactSlide">
-              ${items.join("")}
-            </section>
-          `;
-        }
-        
-      });
+  type: "contactSlide",
+
+  fromJSON(raw) {
+    const items = raw.data?.map(d => ({ content: d.content }));
+
+    if (!items?.length) {
+      throw new Error("contactSlide: content required");
     }
-  };
-  
+
+    return Object.freeze({
+      type: "contactSlide",
+      items,
+
+      render() {
+        return `
+          <section class="slide contactSlide">
+            ${items.map(i => `<div>${i.content}</div>`).join("")}
+          </section>
+        `;
+      }
+    });
+  }
+};