taleem-slides 0.5.0 → 0.6.0

package/README.md

@@ -1,111 +1,71 @@
 
-
 # 📦 taleem-slides
 
-## ⚠️ 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**.
+> **Simple HTML slide templates for JSON-based presentations**
 
-It does **one thing only**:
+`taleem-slides` is a **small, focused library** that turns
+**plain slide JSON** into **HTML**.
 
-> **Given slide data + render state → return HTML**
+You give it slide data.  
+It gives you HTML.
 
-It does **not** manage time, indexes, playback, or decks.
+That’s it.
 
 ---
 
-## 🌐 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:
+## 🌐 Live Docs, Demo & Reference (START HERE)
 
-> Enable educators to create **JSON-based presentations**
-> and display them online using **free, open tools**.
+👉 **https://bilza2023.github.io/taleem**
 
-### Key ideas
+This site is the **official reference** for:
 
-* Slides already encode *layout + structure*
-* Users provide **content only**
-* There are **no configuration knobs**
-* What you see is what the template decides
+- all supported slide types
+- visual behavior
+- real rendered output
+- examples and demos
 
-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**.
 
 ---
 
@@ -113,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
@@ -191,173 +143,64 @@ Templates apply **standard class names only**:
 .is-hidden
 ```
 
-Styling is handled entirely by the consuming app.
-
----
-
-## 🧭 How this fits in the ecosystem
-
-`taleem-slides` is intentionally **small** and **focused**.
-
-It is used by higher-level projects:
-
-### 🧩 Sister Projects
-
-* **taleem-browser**
-  Index-based slide viewer (manual navigation)
-
-* **taleem-player**
-  Time-based slide player (audio / video synced)
-
-Both projects:
-
-* compute render state (`activeIndex`, `visibleCount`)
-* pass it to `taleem-slides`
-* receive consistent HTML output
-
----
-
-## 🧪 Demo & Reference Projects
-
-* 🌐 **Live Display Center**
-  [https://bilza2023.github.io/taleem/](https://bilza2023.github.io/taleem/)
-
-* 📁 **GitHub Demo / Playground**
-  *(link can be added here when ready)*
-
----
-
-## 🧊 Stability & Versioning
-
-* Targets **deck-v1**
-* Breaking changes allowed during WIP phase
-* HTML output is intentionally simple and predictable
+You control **all styling**.
 
 ---
 
-## 🧠 Design Principle (Locked)
-
-> **taleem-slides renders HTML.
-> It does not decide *when* or *why*.**
-
----
-
-## 🔳 Deck Background Support (NEW)
-
-`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**.
-
----
-
-## 🎨 Background Resolution API
-
-`taleem-slides` exports a small helper:
+## 🧩 Supported Slide Types
 
-```js
-import { resolveBackground } from "taleem-slides";
-```
+See the **live site** for visuals and examples:
 
-### Purpose
+👉 [https://bilza2023.github.io/taleem](https://bilza2023.github.io/taleem)
 
-`resolveBackground` answers one question only:
+Supported categories include:
 
-> **“What background should be used for this deck?”**
+* titles and text slides
+* bullet lists and columns
+* images and image+text layouts
+* tables and charts
+* quotes and stats
+* equation slides
 
-It does **not**:
+Layouts are **fixed by design**.
 
-* touch the DOM
-* inject styles
-* manage themes
-* animate or time anything
+If you need a new layout, you add a new template.
 
 ---
 
-### Input (conceptual)
+## 🧪 Stability & Guarantees
 
-```ts
-{
-  deckBackground?: {
-    backgroundColor?: string
-    backgroundImage?: string
-    backgroundImageOpacity?: number
-  },
-  themeSurfaceColor?: string
-}
-```
+* Deterministic output
+* No hidden state
+* No configuration knobs
+* Same input → same HTML
 
 ---
 
-### Output
+## 🔒 Design Principle
 
-```ts
-{
-  backgroundColor?: string
-  backgroundImage?: string
-  backgroundImageOpacity?: number
-}
-```
+> **This library renders HTML only.
+> It does not decide when or how slides appear.**
 
 ---
 
-### Resolution rules (locked)
+## 📍 Where this fits
 
-* If the deck defines a background → **use it**
-* Otherwise → **fall back to the theme’s surface color**
+`taleem-slides` is meant to be used by:
 
-These rules are **format-level guarantees**, not rendering behavior.
+* slide viewers
+* presentation players
+* educational tools
+* static or dynamic renderers
 
----
-
-## 🧠 Mental Model (Updated)
-
-```
-deck JSON + render state + theme surface
-        ↓
-   taleem-slides
-        ↓
-HTML + resolved background data
-        ↓
-player / browser
-        ↓
-        DOM
-```
-
-`taleem-slides` decides **what exists**.
-The player / browser decides **how it appears**.
+It is intentionally small so it can be reused everywhere.
 
 ---
 
-## 🔒 Design Principle (Extended)
+## ✅ Status
 
-> **taleem-slides renders HTML and resolves deck-level intent.
-> It never touches the DOM and never manages playback.**
+* Actively used
+* Fully tested
+* Backed by live reference site
+* Ready for production
 
----
-
-## ✅ What this achieves
-
-* background rules are centralized
-* players remain simple
-* browsers stay dumb
-* future renderers (CLI, SSR, export) stay possible
-
----

package/package.json

@@ -1,22 +1,23 @@
 {
   "name": "taleem-slides",
-  "version": "0.5.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/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>
         `;