taleem-browser 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+
+# taleem-browser
+
+**taleem-browser** is a minimal, index-based slide document browser.
+
+At its core, it is a **JSON → Slides engine**:
+
+> **JSON in →  slides out**
+
+It takes a structured slide deck (JSON) and renders one slide at a time into the DOM, allowing simple, reliable navigation by index.
+
+There is **no timeline**, **no autoplay**, and **no animation logic** by design.
+
+---
+
+## Core idea
+
+Slides are **documents**, not animations.
+
+A deck is an **ordered list of slides**.  
+`taleem-browser` lets you **view and navigate** that list safely and deterministically.
+
+- No matter how simple or complex the deck is
+- Whether timing metadata exists or not
+- Even if timing metadata is incomplete or wrong
+
+Slides always render.
+
+---
+
+## What this library does
+
+`taleem-browser`:
+
+- Accepts a **deck JSON object**
+- Renders slides using `taleem-slides`
+- Owns a single DOM mount point
+- Displays **exactly one slide at a time**
+- Navigates slides by **index**
+- Always succeeds at rendering content
+
+Navigation is explicit and controlled via a small API:
+
+- `next()`
+- `prev()`
+- `goTo(index)`
+
+---
+
+## What this library intentionally does NOT do
+
+`taleem-browser` does **not**:
+
+- interpret `start`, `end`, or `showAt`
+- manage time or intervals
+- autoplay slides
+- sync audio or narration
+- perform animations
+- depend on any framework (React, Svelte, etc.)
+
+These concerns belong to a **separate playback layer**, not a document browser.
+
+---
+
+## Relationship to other Taleem libraries
+
+`taleem-browser` sits above lower-level libraries:
+
+- **taleem-core**  
+  Defines schemas and core data rules.
+
+- **taleem-slides**  
+  Converts slide JSON into HTML.
+
+`taleem-browser` uses `taleem-slides` internally so users don’t have to wire renderers manually.
+
+If you want full control over rendering, you can use `taleem-slides` directly.  
+If you want a **ready-to-use slide viewer**, use `taleem-browser`.
+
+---
+
+## Usage (minimal)
+
+```js
+import { createTaleemBrowser } from "taleem-browser";
+import deck from "./deck.json";
+
+const browser = createTaleemBrowser({
+  mount: "#app",
+  deck
+});
+
+browser.next();
+browser.prev();
+browser.goTo(3);
+````
+
+That’s it.
+
+---
+
+## Design philosophy
+
+* Slides are **content-first**
+* Index is more fundamental than time
+* Rendering should never fail because of timing
+* Static viewing is the default
+* Playback is an optional interpretation
+
+> **Slides are documents.
+> Timing is an optional playback layer.**
+
+---
+
+## Advanced playback
+
+If you need timed playback (e.g. animations, narration, or video-like behavior), use a higher-level utility (such as a future `taleem-player`) that **drives** `taleem-browser`.
+
+The browser itself remains simple, stable, and predictable.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "taleem-browser",
+    "version": "0.1.0",
+    "description": "Pure index-based slide document browser for Taleem decks",
+    "type": "module",
+  
+    "main": "./src/index.js",
+    "exports": {
+      ".": "./src/index.js"
+    },
+  
+    "files": [
+      "src"
+    ],
+  
+    "scripts": {
+      "test": "vitest run"
+    },
+  
+    "peerDependencies": {
+      "taleem-slides": "^0.3.0"
+    },
+  
+    "devDependencies": {
+      "vitest": "^1.6.0",
+      "jsdom": "^24.0.0"
+    },
+  
+    "keywords": [
+      "slides",
+      "presentation",
+      "education",
+      "browser",
+      "taleem"
+    ],
+  
+    "license": "MIT"
+  }
+  

package/src/index.js

@@ -0,0 +1,110 @@
+
+import { slideBuilder } from "taleem-slides";
+
+/**
+ * createTaleemBrowser
+ * A pure slide document browser (index-based, no time).
+ */
+export function createTaleemBrowser({ mount, deck }) {
+  if (!mount) {
+    throw new Error("taleem-browser: mount is required");
+  }
+  if (!deck || !Array.isArray(deck.deck)) {
+    throw new Error("taleem-browser: valid deck object required");
+  }
+
+  const root =
+    typeof mount === "string" ? document.querySelector(mount) : mount;
+
+  if (!root) {
+    throw new Error("taleem-browser: mount element not found");
+  }
+
+  let currentIndex = 0;
+  const total = deck.deck.length;
+
+  // build static DOM once
+  root.innerHTML = `
+    <div class="taleem-browser-bg"></div>
+    <div class="taleem-browser-slide"></div>
+  `;
+
+  const bgEl = root.querySelector(".taleem-browser-bg");
+  const slideEl = root.querySelector(".taleem-browser-slide");
+
+  // apply background from deck (browser-level responsibility)
+  applyBackground(bgEl, deck.background);
+
+  // build slide renderer
+  const manager = slideBuilder(deck);
+
+  function render() {
+    slideEl.innerHTML = manager.renderSlide(currentIndex);
+  }
+
+  function next() {
+    if (currentIndex < total - 1) {
+      currentIndex++;
+      render();
+    }
+  }
+
+  function prev() {
+    if (currentIndex > 0) {
+      currentIndex--;
+      render();
+    }
+  }
+
+  function goTo(index) {
+    if (index < 0 || index >= total) return;
+    currentIndex = index;
+    render();
+  }
+
+  function getIndex() {
+    return currentIndex;
+  }
+
+  function getTotal() {
+    return total;
+  }
+
+  function destroy() {
+    root.innerHTML = "";
+  }
+
+  // initial render
+  render();
+
+  return {
+    next,
+    prev,
+    goTo,
+    getIndex,
+    getTotal,
+    render,
+    destroy
+  };
+}
+
+/* -----------------------------
+   helpers (internal only)
+------------------------------ */
+
+function applyBackground(el, bg = {}) {
+  el.style.position = "absolute";
+  el.style.inset = "0";
+  el.style.zIndex = "0";
+
+  el.style.backgroundColor = bg.backgroundColor || "#000";
+  el.style.backgroundImage = bg.backgroundImage
+    ? `url(${bg.backgroundImage})`
+    : "none";
+  el.style.backgroundSize = "cover";
+  el.style.backgroundPosition = "center";
+  el.style.opacity =
+    bg.backgroundImageOpacity !== undefined
+      ? bg.backgroundImageOpacity
+      : 1;
+}