taleem-slides 0.5.0 → 0.6.1

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/dist/taleem.css

@@ -0,0 +1,232 @@
+/* =====================================================
+   TALEEM — Single Public Stylesheet
+   ===================================================== */
+
+/* -------------------------------
+   Theme Contract (User Editable)
+   ------------------------------- */
+   
+  /* -------------------------------
+     Global Page Reset
+     ------------------------------- */
+  body {
+    margin: 0;
+    font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
+    background: var(--backgroundColor, #0b1220);
+    color: var(--primaryColor, #e6e9ff);
+  }
+  
+  #app {
+    position: relative;
+    width: 100vw;
+    min-height: 100vh;
+    overflow: hidden;
+  }
+  
+  /* -------------------------------
+     Browser / Player Layers
+     ------------------------------- */
+  .taleem-browser-bg {
+    position: absolute;
+    inset: 0;
+    z-index: 0;
+    background-size: cover;
+    background-position: center;
+  }
+  
+  .taleem-browser-slide {
+    position: relative;
+    z-index: 1;
+  }
+  
+  /* -------------------------------
+     Base Slide Grammar
+     ------------------------------- */
+  .slide {
+    height: 100vh;
+    box-sizing: border-box;
+  
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+  
+    padding: 64px 80px;
+    gap: 32px;
+  
+    overflow: hidden;
+    background: transparent;
+    color: var(--primaryColor, #e6e9ff);
+  
+    font-size: 2.4rem;
+    line-height: 1.6;
+    letter-spacing: 0.01em;
+    text-align: center;
+  }
+  
+  /* -------------------------------
+     Global Image Safety
+     ------------------------------- */
+  .slide img {
+    max-width: 100%;
+    max-height: 100%;
+    height: auto;
+    width: auto;
+    display: block;
+  }
+  
+  /* -------------------------------
+     Headings
+     ------------------------------- */
+  .slide h1 {
+    margin: 0;
+    letter-spacing: -0.015em;
+  }
+  
+  /* -------------------------------
+     Slide Types
+     ------------------------------- */
+  .slide.titleSlide h1 {
+    font-size: 5.6rem;
+    font-weight: 700;
+    line-height: 1.2;
+  }
+  
+  .slide.titleAndSubtitle h1 {
+    font-size: 5.8rem;
+    font-weight: 700;
+  }
+  
+  .slide.titleAndSubtitle h2 {
+    font-size: 3.8rem;
+    font-weight: 400;
+    opacity: 0.8;
+    margin: 0;
+  }
+  
+  .slide.titleAndPara h1 {
+    font-size: 4.8rem;
+    font-weight: 600;
+  }
+  
+  .slide.titleAndPara p {
+    font-size: 3rem;
+    max-width: 70ch;
+    opacity: 0.9;
+    margin: 0;
+  }
+  
+  /* -------------------------------
+     Bullet List
+     ------------------------------- */
+  .slide.bulletList ul {
+    list-style: disc;
+    padding-left: 2rem;
+    margin: 0;
+  }
+  
+  .slide.bulletList li {
+    font-size: 3.6rem;
+    margin-bottom: 1rem;
+    text-align: left;
+    font-weight: 500;
+  }
+  
+  /* -------------------------------
+     Image Variants
+     ------------------------------- */
+  .slide.imageSlide {
+    padding: 0;
+  }
+  
+  .slide.imageSlide img {
+    object-fit: contain;
+  }
+  
+  .slide.imageWithTitle {
+    position: relative;
+    padding: 48px;
+  }
+  
+  .slide.imageWithTitle img {
+    height: calc(100vh - 96px);
+    border-radius: 12px;
+  }
+  
+  .slide.imageWithTitle h1 {
+    position: absolute;
+    bottom: 64px;
+    left: 50%;
+    transform: translateX(-50%);
+    font-size: 4.6rem;
+    background: rgba(0, 0, 0, 0.45);
+    padding: 0.4em 0.8em;
+    border-radius: 6px;
+  }
+  
+  /* -------------------------------
+     Two Column Text
+     ------------------------------- */
+  .slide.twoColumnText .columns {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 64px;
+    max-width: 1200px;
+  }
+  
+  .slide.twoColumnText p {
+    font-size: 3rem;
+    text-align: left;
+  }
+  
+  /* -------------------------------
+     Quote Slide
+     ------------------------------- */
+  .slide.quoteSlide blockquote {
+    font-size: 3.8rem;
+    font-style: italic;
+    max-width: 60ch;
+  }
+  
+  .slide.quoteSlide cite {
+    font-size: 2.4rem;
+    opacity: 0.75;
+  }
+  
+  /* -------------------------------
+     Big Number
+     ------------------------------- */
+  .slide.bigNumber .number {
+    font-size: 9rem;
+    font-weight: 700;
+  }
+  
+  /* -------------------------------
+     Fill Image (Full Bleed)
+     ------------------------------- */
+  .slide.fillImage {
+    padding: 0;
+    height: 100vh;
+    display: block;
+  }
+  
+  .slide.fillImage img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+  
+  /* -------------------------------
+     Demo / Player UI (Optional)
+     ------------------------------- */
+  #timebar {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    height: 32px;
+    background: rgba(0, 0, 0, 0.6);
+    backdrop-filter: blur(6px);
+    z-index: 10;
+  }
+  

package/dist/themes/dark.css

@@ -0,0 +1,6 @@
+
+:root {
+    --backgroundColor: #081b7a;
+    --primaryColor: #ccd0e4;
+  }
+  

package/dist/themes/light.css

@@ -0,0 +1,6 @@
+
+:root {
+    --backgroundColor: #15df1b;
+    --primaryColor: #cbd44b;
+  }
+  

package/dist/themes/paper.css

@@ -0,0 +1,6 @@
+
+:root {
+    --backgroundColor: #f8f9fb;
+    --primaryColor: #1a1f36;
+  }
+