taleem-slides 0.4.0 → 0.6.0

package/README.md

@@ -1,108 +1,71 @@
 
 # 📦 taleem-slides
 
-## ⚠️  Warning :  Work in Progress — expect breaking changes
+> **Simple HTML slide templates for JSON-based presentations**
 
-> **Pure slide template library for Taleem decks**
+`taleem-slides` is a **small, focused library** that turns
+**plain slide JSON** into **HTML**.
 
-`taleem-slides` is a **simple, deterministic template library** that turns
-**deck-style slide JSON** into **HTML**.
+You give it slide data.  
+It gives you HTML.
 
-It does **one thing only**:
+That’s it.
 
-> **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
+## 🌐 Live Docs, Demo & Reference (START HERE)
 
-**Taleem.help** is an educational technology initiative focused on making
-**content-first learning tools**.
+👉 **https://bilza2023.github.io/taleem**
 
-The goal of the `taleem-*` libraries is simple:
+This site is the **official reference** for:
 
-> Enable educators to create **JSON-based presentations**
-> and display them online using **free, open tools**.
+- all supported slide types
+- visual behavior
+- real rendered output
+- examples and demos
 
-Key ideas:
-
-* Slides already encode *layout + structure*
-* Users provide **content only**
-* There are **no configuration knobs**
-* What you see is what the template decides
-
-This removal of choice is **intentional**.
-
-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.
+If something is unclear in this README,  
+**the website is the final authority**.
 
 ---
 
-## ✨ What this library is
-
-* A collection of **slide templates**
-* Each template:
+## ✅ What this library does
 
-  * 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*
+- Converts slide JSON into HTML
+- Uses fixed, opinionated layouts
+- Applies simple state-based CSS classes
+- Works in any JS environment (browser, player, SSR)
 
 ---
 
-## ❌ What this library is NOT
+## ❌ What this library does NOT do
 
 `taleem-slides` does **not**:
 
-* build decks
-* validate full decks
-* manage timing (`showAt`)
-* decide which slide is active
-* manage playback
-* mutate data
+- play slides
+- manage time or animations
+- navigate slides
+- validate full decks
+- touch the DOM
+- apply CSS styles
 
-All of that belongs elsewhere.
+It only returns HTML strings.
 
 ---
 
 ## 🧠 Mental Model
 
 ```
-slide JSON + render state
-        ↓
-   slide template
-        ↓
-       HTML
-```
 
-How the state is calculated is **not this library’s concern**.
+slide data + render state
+↓
+taleem-slides
+↓
+HTML
+
+````
+
+How slides are shown, timed, or styled is **your responsibility**.
 
 ---
 
@@ -110,77 +73,69 @@ How the state is calculated is **not this library’s concern**.
 
 ```bash
 npm install taleem-slides
-```
+````
 
 ---
 
 ## 🚀 Basic Usage
 
-### 1️⃣ Import a template
+### 1️⃣ Get a slide template
 
 ```js
 import { getSlideTemplate } from "taleem-slides";
+
+const Slide = getSlideTemplate("bulletList");
 ```
 
 ---
 
-### 2️⃣ Load slide data (once)
+### 2️⃣ Load slide data
 
 ```js
-const SlideTemplate = getSlideTemplate("bulletList");
-
-const slide = SlideTemplate.fromJSON({
+const slide = Slide.fromJSON({
   type: "bulletList",
   data: [
     { name: "bullet", content: "First point" },
-    { name: "bullet", content: "Second point" },
-    { name: "bullet", content: "Third point" }
+    { name: "bullet", content: "Second point" }
   ]
 });
 ```
 
-> `fromJSON()` only **reads and stores structure**.
-> No timing. No logic.
+`fromJSON()` reads and stores structure only.
 
 ---
 
-### 3️⃣ Render with state
+### 3️⃣ Render HTML
 
 ```js
 const html = slide.render({
-  visibleCount: 2,
-  activeIndex: 1
+  visibleCount: 1,
+  activeIndex: 0
 });
 ```
 
-This will:
-
-* render first 2 bullets
-* highlight the second bullet
-* dim the first
-
 ---
 
-## 🎨 Render State Contract
+## 🎨 Render State (Simple)
 
-Templates accept a **render state object**.
+Render state is just a plain object.
 
 Common fields:
 
 ```ts
 {
-  visibleCount?: number; // how many items exist
-  activeIndex?: number;  // which item is highlighted
+  visibleCount?: number
+  activeIndex?: number
 }
 ```
 
-Slides may choose to use one or both.
+Each slide uses only what it needs.
 
 ---
 
-## 🎯 Class Name Contract
+## 🎯 CSS Class Contract
 
-Templates apply **standard class names only**:
+Slides emit only these state classes:
 
 ```text
 .is-active
@@ -188,60 +143,64 @@ Templates apply **standard class names only**:
 .is-hidden
 ```
 
-Styling is handled entirely by the consuming app.
+You control **all styling**.
 
 ---
 
-## 🧭 How this fits in the ecosystem
-
-`taleem-slides` is intentionally **small** and **focused**.
+## 🧩 Supported Slide Types
 
-It is used by higher-level projects:
+See the **live site** for visuals and examples:
 
-### 🧩 Sister Projects
+👉 [https://bilza2023.github.io/taleem](https://bilza2023.github.io/taleem)
 
-* **taleem-browser**
-  Index-based slide viewer (manual navigation)
+Supported categories include:
 
-* **taleem-player**
-  Time-based slide player (audio / video synced)
+* titles and text slides
+* bullet lists and columns
+* images and image+text layouts
+* tables and charts
+* quotes and stats
+* equation slides
 
-Both projects:
+Layouts are **fixed by design**.
 
-* compute render state (`activeIndex`, `visibleCount`)
-* pass it to `taleem-slides`
-* receive consistent HTML output
+If you need a new layout, you add a new template.
 
 ---
 
-## 🧪 Demo & Reference Projects
+## 🧪 Stability & Guarantees
 
-* 🌐 **Live Display Center**
-  [https://bilza2023.github.io/taleem/](https://bilza2023.github.io/taleem/)
-
-* 📁 **GitHub Demo / Playground**
-  *(link can be added here when ready)*
+* Deterministic output
+* No hidden state
+* No configuration knobs
+* Same input → same HTML
 
 ---
 
-## 🧊 Stability & Versioning
+## 🔒 Design Principle
 
-* Targets **deck-v1**
-* Breaking changes allowed during WIP phase
-* HTML output is intentionally simple and predictable
+> **This library renders HTML only.
+> It does not decide when or how slides appear.**
 
 ---
 
-## 🧠 Design Principle (Locked)
+## 📍 Where this fits
+
+`taleem-slides` is meant to be used by:
+
+* slide viewers
+* presentation players
+* educational tools
+* static or dynamic renderers
 
-> **taleem-slides renders HTML.
-> It does not decide *when* or *why*.**
+It is intentionally small so it can be reused everywhere.
 
 ---
 
-If you want, next logical steps are:
+## ✅ Status
 
-* rewrite one slide as the **canonical reference**
-* or update taleem-browser to consume the new API cleanly
+* Actively used
+* Fully tested
+* Backed by live reference site
+* Ready for production
 
-This README now correctly **anchors the entire ecosystem**.

package/package.json

@@ -1,22 +1,23 @@
 {
   "name": "taleem-slides",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Convert json taleem schema into html for slides",
-
   "exports": {
     ".": "./src/index.js"
   },
-
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "lint": "echo \"no lint yet\""
   },
-
   "devDependencies": {
     "vite": "^5.0.0",
     "vitest": "^1.5.0"
+  },
+  "dependencies": {
+    "taleem-core": "^1.3.2",
+    "zod": "^4.3.5"
   }
 }

package/src/SlideTemplates.js

@@ -53,5 +53,4 @@ export const SlideTemplates = {
   contactSlide: ContactSlide,
 
   eq: EqSlide,
-  svgPointer: SvgPointerSlide
 };

package/src/index.js

@@ -2,3 +2,4 @@
 
 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,16 +1,16 @@
-// BarChartSlide.js
 export const BarChartSlide = {
   type: "barChart",
 
   fromJSON(raw) {
+    // Consume canonical deck-v1 shape directly
     const bars = raw.data
       ?.filter(d => d.name === "bar")
       .map(d => ({
-        label: d.content.label,
-        value: d.content.value
+        label: d.label,
+        value: d.value
       }));
 
-    if (!bars?.length) {
+    if (!bars || bars.length === 0) {
       throw new Error("barChart: requires at least one bar");
     }
 
@@ -27,7 +27,7 @@ export const BarChartSlide = {
                 const cls =
                   i === activeIndex
                     ? "is-active"
-                    : i < activeIndex
+                    : activeIndex !== null && i < activeIndex
                     ? "is-dim"
                     : "";
                 return `

package/src/slides/BigNumberSlide.js

@@ -1,22 +1,23 @@
-// 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;
+    const number = 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");
+    if (!number) {
+      throw new Error("bigNumber: number required");
+    }
 
     return Object.freeze({
       type: "bigNumber",
-      value,
+      number,
       label,
 
       render() {
         return `
           <section class="slide bigNumber">
-            <div class="number">${value}</div>
+            <div class="number">${number}</div>
             ${label ? `<div class="label">${label}</div>` : ""}
           </section>
         `;

package/src/slides/BulletListSlide.js

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

package/src/slides/ContactSlide.js

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

package/src/slides/CornerWordsSlide.js

@@ -1,26 +1,31 @@
-// CornerWordsSlide.js
+
 export const CornerWordsSlide = {
   type: "cornerWordsSlide",
 
   fromJSON(raw) {
-    const words = raw.data
-      ?.filter(d => d.name === "word")
-      .map(d => ({ content: d.content }));
+    const cards = raw.data
+      ?.filter(d => d.name === "card")
+      .map(d => ({ icon: d.icon, label: d.label }));
 
-    if (!words?.length) {
-      throw new Error("cornerWordsSlide: requires at least one word");
+    if (!cards || cards.length === 0) {
+      throw new Error("cornerWordsSlide: requires at least one card");
     }
 
     return Object.freeze({
       type: "cornerWordsSlide",
-      words,
+      cards,
 
-      render({ visibleCount = words.length } = {}) {
+      render({ visibleCount = cards.length } = {}) {
         return `
           <section class="slide cornerWordsSlide">
-            ${words.map((w, i) => {
+            ${cards.map((c, i) => {
               if (i >= visibleCount) return "";
-              return `<span class="corner-word corner-${i + 1}">${w.content}</span>`;
+              return `
+                <span class="corner-card corner-${i + 1}">
+                  <span class="icon">${c.icon}</span>
+                  <span class="label">${c.label}</span>
+                </span>
+              `;
             }).join("")}
           </section>
         `;

package/src/slides/DonutChartSlide.js

@@ -1,16 +1,22 @@
-// DonutChartSlide.js
 export const DonutChartSlide = {
   type: "donutChart",
 
   fromJSON(raw) {
-    const segments = raw.data
-      ?.filter(d => d.name === "segment")
-      .map(d => ({
-        label: d.content.label,
-        value: d.content.value
-      }));
+    const segments = [];
+    let current = null;
 
-    if (!segments?.length) {
+    for (const d of raw.data || []) {
+      if (d.name === "percent") {
+        current = { percent: d.content };
+        segments.push(current);
+      } else if (current && d.name === "label") {
+        current.label = d.content;
+      } else if (current && d.name === "color") {
+        current.color = d.content;
+      }
+    }
+
+    if (!segments.length) {
       throw new Error("donutChart: requires at least one segment");
     }
 
@@ -18,19 +24,13 @@ export const DonutChartSlide = {
       type: "donutChart",
       segments,
 
-      render({ visibleCount = segments.length, activeIndex = null } = {}) {
+      render({ visibleCount = segments.length } = {}) {
         return `
           <section class="slide donutChart">
             <ul>
               ${segments.map((s, i) => {
                 if (i >= visibleCount) return "";
-                const cls =
-                  i === activeIndex
-                    ? "is-active"
-                    : i < activeIndex
-                    ? "is-dim"
-                    : "";
-                return `<li class="${cls}">${s.label}: ${s.value}</li>`;
+                return `<li>${s.label}: ${s.percent}%</li>`;
               }).join("")}
             </ul>
           </section>

package/src/slides/EqSlide.js

@@ -1,28 +1,32 @@
-// EqSlide.js
+
 export const EqSlide = {
   type: "eq",
 
   fromJSON(raw) {
-    if (!Array.isArray(raw.data)) {
-      throw new Error("eq: data must be array");
-    }
+    const lines = raw.data
+      ?.filter(d => d.name === "line")
+      .map(d => ({
+        type: d.type,
+        content: d.content
+      }));
 
-    const lines = raw.data.map(d => ({
-      content: d.content
-    }));
+    if (!lines || lines.length === 0) {
+      throw new Error("eq: requires at least one line");
+    }
 
     return Object.freeze({
       type: "eq",
       lines,
 
-      render({ activeIndex = null } = {}) {
+      render({ visibleCount = lines.length, activeIndex = null } = {}) {
         return `
           <section class="slide eq">
             ${lines.map((l, i) => {
+              if (i >= visibleCount) return "";
               const cls =
                 i === activeIndex
                   ? "is-active"
-                  : i < activeIndex
+                  : activeIndex !== null && i < activeIndex
                   ? "is-dim"
                   : "";
               return `<div class="eq-line ${cls}">${l.content}</div>`;

package/src/slides/FillImageSlide.js

@@ -1,10 +1,12 @@
-// FillImageSlide.js
 export const FillImageSlide = {
   type: "fillImage",
 
   fromJSON(raw) {
     const image = raw.data?.find(d => d.name === "image")?.content;
-    if (!image) throw new Error("fillImage: image required");
+
+    if (!image) {
+      throw new Error("fillImage: image required");
+    }
 
     return Object.freeze({
       type: "fillImage",