@thanh01.pmt/presentation-kit 0.1.0

package/README.md

@@ -0,0 +1,548 @@
+# @learnwell/presentation-kit
+
+> Standalone **client-side** slide rendering engine. Import Marp markdown, get fully rendered 16:9 slides with syntax highlighting, Mermaid diagrams, and custom themes — **zero server roundtrip**.
+
+```
+npm install @learnwell/presentation-kit
+```
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Imports — Two Subpaths](#imports--two-subpaths)
+- [Quick Start](#quick-start)
+  - [Headless (Core Only)](#headless-core-only)
+  - [React UI (Ready-to-Use)](#react-ui-ready-to-use)
+- [API Reference — Core](#api-reference--core)
+  - [`renderSlide()`](#renderslidemarkdown-options)
+  - [`renderSlideAsync()`](#renderslideasyncmarkdown-options)
+  - [`createEngine()`](#createengineconfig)
+  - [`defineTheme()`](#definetheme-definition)
+  - [`renderMermaidDiagrams()`](#rendermermaidchartscontainer-theme)
+  - [`detectMermaidBlocks()`](#detectmermaidblockhtml)
+  - [`highlightCodeBlocks()`](#highlightcodeblockhtml-theme)
+  - [`convertTextArrows()`](#converttextarrowstext)
+  - [`extractMarpSource()`](#extractmarpsourceraw)
+- [API Reference — React](#api-reference--react)
+  - [`<SlideViewer />`](#slideviewer)
+  - [`<PresentationView />`](#presentationview)
+  - [`<DeckView />`](#deckview)
+  - [`<ThemeSwitcher />`](#themeswitcher)
+  - [`<NavigationBar />`](#navigationbar)
+  - [`useSlideState()`](#useslidestate)
+- [Theme System](#theme-system)
+- [Architecture](#architecture)
+- [Bundle Size](#bundle-size)
+- [Package Structure](#package-structure)
+- [Development](#development)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+# Monorepo
+pnpm add @learnwell/presentation-kit --workspace
+
+# Standalone
+npm install @learnwell/presentation-kit
+```
+
+**Peer dependencies (optional — only needed for React subpath):**
+
+```bash
+npm install react react-dom
+```
+
+---
+
+## Imports — Two Subpaths
+
+The package provides **two import paths** so you only load what you need:
+
+| Import path | What you get | Size | When to use |
+|---|---|---|---|
+| `@learnwell/presentation-kit` | Core engine (headless) | ~36KB | You build your own UI |
+| `@learnwell/presentation-kit/react` | Core engine + React UI components | ~52KB | You want ready-to-use viewer |
+
+```ts
+// ✅ Headless — no React dependency
+import { renderSlide, defineTheme } from '@learnwell/presentation-kit';
+
+// ✅ React — full UI components
+import { SlideViewer, ThemeSwitcher } from '@learnwell/presentation-kit/react';
+
+// ✅ Mix — core engine + custom UI using React hooks
+import { renderSlide, useSlideState } from '@learnwell/presentation-kit/react';
+```
+
+> **Tree-shaking:** If you only import `renderSlide` from the React subpath, bundlers will exclude unused UI components.
+
+---
+
+## Quick Start
+
+### Headless (Core Only)
+
+For apps that want full control over the UI:
+
+```tsx
+import { renderSlide } from '@learnwell/presentation-kit';
+
+const result = renderSlide(marpMarkdown, { theme: 'dark' });
+
+// Inject into DOM
+container.innerHTML = `<style>${result.css}${result.themeCss}</style>${result.html}`;
+```
+
+### React UI (Ready-to-Use)
+
+For apps that want a complete slide viewer out of the box:
+
+```tsx
+import { SlideViewer } from '@learnwell/presentation-kit/react';
+
+function MyPage() {
+  return (
+    <SlideViewer
+      markdown={marpMarkdown}
+      initialTheme="dark"
+      showThemeSwitcher
+      showNavigation
+    />
+  );
+}
+```
+
+That's it. You get:
+- Theme switching (Dark / Navy / Light)
+- Presentation mode (single slide + keyboard nav)
+- Deck mode (vertical scroll)
+- Mermaid diagram rendering
+- Copy markdown button
+
+---
+
+## API Reference — Core
+
+### `renderSlide(markdown, options?)`
+
+**Synchronous** slide rendering. Returns instantly.
+
+```ts
+function renderSlide(markdown: string, options?: SlideRenderOptions): SlideRenderResult;
+```
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `markdown` | `string` | — | Marp markdown (with `---` separators) |
+| `options.theme` | `'dark' \| 'light' \| 'navy' \| SlideTheme` | `'dark'` | Theme to apply |
+| `options.enableShiki` | `boolean` | `true` | Detect code blocks (sync: detection only) |
+| `options.enableMermaid` | `boolean` | `true` | Detect mermaid blocks |
+| `options.containerId` | `string` | `'marp-container'` | CSS isolation ID |
+
+**Returns:** `{ html, css, themeCss, slideCount, mermaidBlocks }`
+
+---
+
+### `renderSlideAsync(markdown, options?)`
+
+**Async** render with Shiki syntax highlighting applied.
+
+```ts
+function renderSlideAsync(markdown: string, options?: SlideRenderOptions): Promise<SlideRenderAsyncResult>;
+```
+
+**Returns:** `{ ...SlideRenderResult, processedHtml }` — HTML with Shiki-highlighted code blocks.
+
+---
+
+### `createEngine(config?)`
+
+Create a reusable engine instance with default options.
+
+```ts
+const engine = createEngine({ theme: 'navy' });
+const result = engine.render(markdown); // defaults to navy theme
+```
+
+---
+
+### `defineTheme(definition)`
+
+Define a custom theme with full token control.
+
+```ts
+const myTheme = defineTheme({
+  name: 'corporate',
+  tokens: { background: '#fff', text: '#1a1a2e', /* ...24 tokens */ },
+});
+renderSlide(markdown, { theme: myTheme });
+```
+
+---
+
+### `renderMermaidDiagrams(container, theme)`
+
+Render mermaid diagrams in a DOM container. Browser only (returns early in SSR).
+
+```ts
+await renderMermaidDiagrams(document.getElementById('slides'), 'dark');
+```
+
+---
+
+### `detectMermaidBlocks(html)`
+
+Detect mermaid blocks in rendered HTML (sync, no DOM needed).
+
+```ts
+const blocks = detectMermaidBlocks(html);
+// blocks: [{ index: 0, code: 'graph TD...', sanitizedCode: '...' }]
+```
+
+---
+
+### `highlightCodeBlocks(html, theme?)`
+
+Async Shiki post-processing for code blocks.
+
+```ts
+const highlighted = await highlightCodeBlocks(html, 'dark');
+```
+
+---
+
+### `convertTextArrows(text)`
+
+Convert text arrows (`->`, `-->`, `=>`) to Unicode arrows. Preserves code fences.
+
+---
+
+### `extractMarpSource(raw)`
+
+Extract clean Marp source from wrapped markdown (strips ` ```markdown ` fences, conversational preamble).
+
+---
+
+## API Reference — React
+
+### `<SlideViewer />`
+
+Complete slide viewer with all features. The main entry point for React apps.
+
+```tsx
+import { SlideViewer } from '@learnwell/presentation-kit/react';
+
+<SlideViewer
+  markdown={marpMarkdown}           // Marp markdown source
+  initialTheme="dark"               // 'dark' | 'light' | 'navy' | SlideTheme
+  initialMode="presentation"        // 'presentation' | 'deck'
+  showThemeSwitcher={true}          // Show theme toggle buttons
+  showNavigation={true}             // Show prev/next/mode controls
+  enableKeyboard={true}             // Enable keyboard navigation
+  themeOptions={[...]}              // Custom theme options for switcher
+  onThemeChange={(theme) => {}}     // Theme change callback
+  onSlideChange={(index) => {}}     // Slide change callback
+  onModeChange={(mode) => {}}       // Mode change callback
+  onRenderComplete={(result) => {}} // Render complete callback
+  className="my-viewer"             // CSS class for root container
+/>
+```
+
+**Features:**
+- Theme switching (Dark / Navy / Light)
+- Presentation mode (single slide, keyboard: ← → Space Home End)
+- Deck mode (vertical scroll of all slides)
+- Mermaid diagram auto-rendering
+- Copy markdown button
+
+---
+
+### `<PresentationView />`
+
+Single slide display. Use this when you want to build your own controls.
+
+```tsx
+import { PresentationView } from '@learnwell/presentation-kit/react';
+
+<PresentationView
+  html={result.html}
+  css={result.css}
+  themeCss={result.themeCss}
+  currentIndex={0}
+  slideCount={5}
+/>
+```
+
+---
+
+### `<DeckView />`
+
+Vertical scroll of all slides. Use this when you want to build your own deck UI.
+
+```tsx
+import { DeckView } from '@learnwell/presentation-kit/react';
+
+<DeckView
+  html={result.html}
+  css={result.css}
+  themeCss={result.themeCss}
+  slideCount={5}
+/>
+```
+
+---
+
+### `<ThemeSwitcher />`
+
+Theme toggle buttons. Use this when you want to add theme switching to a custom UI.
+
+```tsx
+import { ThemeSwitcher } from '@learnwell/presentation-kit/react';
+
+<ThemeSwitcher
+  currentTheme="dark"
+  onThemeChange={setTheme}
+  themes={[
+    { id: 'dark', label: 'Dark' },
+    { id: 'navy', label: 'Navy' },
+    { id: 'light', label: 'Light' },
+  ]}
+/>
+```
+
+---
+
+### `<NavigationBar />`
+
+Slide navigation controls (prev/next, selector, mode toggle, copy).
+
+```tsx
+import { NavigationBar } from '@learnwell/presentation-kit/react';
+
+<NavigationBar
+  currentIndex={2}
+  slideCount={10}
+  onNavigate={setCurrentIndex}
+  mode="presentation"
+  onModeChange={setMode}
+  markdown={rawMarkdown}
+  showCopy={true}
+/>
+```
+
+---
+
+### `useSlideState()`
+
+Centralized hook for slide state management. Use this when building a fully custom viewer.
+
+```tsx
+import { useSlideState } from '@learnwell/presentation-kit/react';
+
+function CustomViewer({ markdown }) {
+  const {
+    currentIndex,   // current slide index
+    mode,           // 'presentation' | 'deck'
+    theme,          // current theme
+    result,         // render result (null before first render)
+    slideCount,     // total slides
+    isReady,        // true after first render
+    goToSlide,      // (index) => void
+    nextSlide,      // () => void
+    prevSlide,      // () => void
+    setMode,        // (mode) => void
+    setTheme,       // (theme) => void
+  } = useSlideState({
+    markdown,
+    initialTheme: 'dark',
+    initialMode: 'presentation',
+  });
+
+  // Full control over rendering and UI
+  return <div dangerouslySetInnerHTML={{ __html: result?.html ?? '' }} />;
+}
+```
+
+---
+
+## Theme System
+
+### Built-in Themes
+
+| Theme | Background | Use Case |
+|---|---|---|
+| `'dark'` | `#14151b` | Developer tools, modern UI |
+| `'light'` | `#ffffff` | Classroom projectors, print |
+| `'navy'` | `#0f172a` | STEM presentations |
+
+### Custom Theme
+
+```ts
+import { defineTheme, renderSlide } from '@learnwell/presentation-kit';
+
+const myTheme = defineTheme({
+  name: 'corporate',
+  tokens: {
+    background: '#ffffff',
+    text: '#1a1a2e',
+    heading: '#1a1a2e',
+    bold: '#1a1a2e',
+    link: '#2563eb',
+    codeBg: '#f5f5f5',
+    codeText: '#27272a',
+    inlineCodeBg: '#f5f5f5',
+    inlineCodeText: '#27272a',
+    codeBorder: 'rgba(0, 0, 0, 0.08)',
+    quoteBg: '#f8f9fa',
+    quoteBorder: 'rgba(0, 0, 0, 0.15)',
+    quoteText: '#27272a',
+    tableHeaderBg: '#f8fafc',
+    tableBorder: '#e2e8f0',
+    tableRowHover: 'rgba(0, 0, 0, 0.02)',
+    tableText: '#3f3f46',
+    cardBorder: '1px solid rgba(0, 0, 0, 0.08)',
+    cardShadow: '0 4px 16px -2px rgba(0, 0, 0, 0.05)',
+    meta: '#71717a',
+    mermaidDark: false,
+    mermaidVariables: { /* mermaid theme vars */ },
+    mermaidThemeCSS: '/* mermaid CSS overrides */',
+  },
+});
+
+renderSlide(markdown, { theme: myTheme });
+```
+
+---
+
+## Architecture
+
+```
+@learnwell/presentation-kit           ← Headless core (no React)
+│
+├── renderSlide()                     ← Sync render
+├── renderSlideAsync()                ← Async render (Shiki)
+├── createEngine()                    ← Reusable instance
+├── defineTheme()                     ← Custom themes
+├── renderMermaidDiagrams()           ← DOM mermaid rendering
+├── detectMermaidBlocks()             ← Mermaid detection
+├── highlightCodeBlocks()             ← Shiki post-process
+├── convertTextArrows()               ← Arrow utility
+└── extractMarpSource()               ← Source cleanup
+
+@learnwell/presentation-kit/react     ← React UI (optional)
+│
+├── <SlideViewer />                   ← Complete viewer (all-in-one)
+├── <PresentationView />              ← Single slide display
+├── <DeckView />                      ← Vertical scroll
+├── <ThemeSwitcher />                 ← Theme toggle buttons
+├── <NavigationBar />                 ← Navigation controls
+└── useSlideState()                   ← State management hook
+```
+
+**Render pipeline:**
+
+```
+markdown
+  → extractMarpSource()     strip wrappers
+  → convertTextArrows()     → → →, --> → ⟶
+  → marp.render()           client-side Marp-core
+  → detectMermaidBlocks()   find mermaid syntax
+  → [async] Shiki           post-process code blocks
+  → generateScopedCss()     theme typography CSS
+  → return { html, css, themeCss, slideCount, mermaidBlocks }
+```
+
+---
+
+## Bundle Size
+
+| Import | Sync | Lazy | Total |
+|---|---|---|---|
+| Core only (`@learnwell/presentation-kit`) | ~36KB | — | **~36KB** |
+| React UI (`@learnwell/presentation-kit/react`) | ~52KB | — | **~52KB** |
+| + Shiki | +0 | ~3MB | ~3MB |
+| + Mermaid | +0 | ~2MB | ~2MB |
+
+> Core and React are bundled together in the React subpath. Shiki and Mermaid are lazy-loaded.
+
+---
+
+## Package Structure
+
+```
+packages/presentation-kit/
+├── src/
+│   ├── core/                    # Headless rendering engine
+│   │   ├── render.ts
+│   │   ├── arrow-converter.ts
+│   │   └── source-extractor.ts
+│   ├── plugins/                 # Lazy-loaded plugins
+│   │   ├── shiki.ts
+│   │   └── mermaid.ts
+│   ├── themes/                  # Theme system
+│   │   ├── dark.ts / light.ts / navy.ts
+│   │   ├── scoped-css.ts
+│   │   └── index.ts
+│   ├── react/                   # React UI (subpath export)
+│   │   ├── components/
+│   │   │   ├── SlideViewer.tsx
+│   │   │   ├── PresentationView.tsx
+│   │   │   ├── DeckView.tsx
+│   │   │   ├── ThemeSwitcher.tsx
+│   │   │   └── NavigationBar.tsx
+│   │   ├── hooks/
+│   │   │   └── useSlideState.ts
+│   │   ├── types.ts
+│   │   └── index.ts
+│   ├── engine.ts
+│   ├── types.ts
+│   └── index.ts                 # Core barrel export
+├── dist/                        # Built output
+├── docs/                        # Design docs
+├── package.json
+└── README.md
+```
+
+---
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm build
+pnpm dev     # watch mode
+```
+
+### Input Format
+
+Marp-compatible markdown:
+
+```markdown
+---
+marp: true
+theme: default
+paginate: true
+---
+
+# Slide 1
+
+---
+
+# Slide 2
+
+```python
+print("Hello")
+```
+```
+
+---
+
+## License
+
+MIT