@miozu/jera 0.3.0 → 0.4.2

package/CLAUDE.md

@@ -28,7 +28,8 @@ jera/
 │       ├── forms/            # Input, Select, Checkbox, Switch
 │       ├── feedback/         # Toast, Skeleton, ProgressBar, Spinner
 │       ├── overlays/         # Modal, Popover
-│       └── navigation/       # Tabs, Accordion, AccordionItem
+│       ├── navigation/       # Tabs, Accordion, Sidebar
+│       └── docs/             # CodeBlock, PropsTable, SplitPane, DocSection
 ├── llms.txt                  # AI documentation index
 ├── CLAUDE.md                 # This file
 └── package.json
@@ -83,47 +84,49 @@ export const componentStyles = cv({
 
 ### Naming Conventions
 - Components: PascalCase (`Button.svelte`)
-- Utilities: camelCase (`createThemeContext`)
+- Utilities: camelCase (`getTheme`)
 - CSS tokens: kebab-case (`--color-primary`)
 - Actions: camelCase (`clickOutside`)
 
 ---
 
-## Miozu Color System
-
-### Base Colors (Grayscale)
-| Token | Hex | Usage |
-|-------|-----|-------|
-| `--base0` | #232733 | Darkest background |
-| `--base1` | #2C3040 | Default dark bg |
-| `--base2` | #3E4359 | Selection, hover |
-| `--base3` | #565E78 | Comments, subtle |
-| `--base4` | #737E99 | Muted text |
-| `--base5` | #D0D2DB | Default text |
-| `--base6` | #F3F4F7 | Light text |
-| `--base7` | #FAFDFB | Lightest/white |
-
-### Accent Colors
-| Token | Hex | Usage |
-|-------|-----|-------|
-| `--magenta` | #C974E6 | Primary brand |
-| `--blue` | #83D2FC | Info, links |
-| `--green` | #6DD672 | Success |
-| `--yellow` | #E8D176 | Warning |
-| `--red` | #EB3137 | Error |
-| `--cyan` | #40FFE2 | Accent |
-| `--orange` | #FF9837 | Attention |
-| `--peach` | #FF9982 | Warm accent |
+## Miozu Base16 Color System
+
+Uses standard Base16 naming: `base00`-`base0F` (hex digits, NOT decimal).
+
+### Grayscale (base00-base07)
+| Token | Dark Theme | Light Theme | Usage |
+|-------|------------|-------------|-------|
+| `--color-base00` | #0f1419 | #ffffff | Primary background |
+| `--color-base01` | #1a1f26 | #f8f9fa | Surface/card |
+| `--color-base02` | #242a33 | #f1f3f5 | Selection/hover |
+| `--color-base03` | #4a5568 | #adb5bd | Muted/disabled |
+| `--color-base04` | #a0aec0 | #6c757d | Secondary text |
+| `--color-base05` | #e2e8f0 | #212529 | Primary text |
+| `--color-base06` | #f7fafc | #1a1d20 | High emphasis |
+| `--color-base07` | #ffffff | #0d0f10 | Maximum contrast |
+
+### Accents (base08-base0F)
+| Token | Color | Usage |
+|-------|-------|-------|
+| `--color-base08` | Red | Error |
+| `--color-base09` | Orange | Warning |
+| `--color-base0A` | Yellow | Highlight |
+| `--color-base0B` | Green | Success |
+| `--color-base0C` | Cyan | Info |
+| `--color-base0D` | Blue | Primary |
+| `--color-base0E` | Purple | Accent |
+| `--color-base0F` | Brown/Orange | Secondary accent |
 
 ### Semantic Mappings
 ```css
---color-bg: var(--base0);
---color-surface: var(--base1);
---color-text: var(--base5);
---color-text-strong: var(--base7);
---color-primary: var(--magenta);
---color-success: var(--green);
---color-error: var(--red);
+--color-bg: var(--color-base00);
+--color-surface: var(--color-base01);
+--color-text: var(--color-base05);
+--color-text-strong: var(--color-base07);
+--color-primary: var(--color-base0D);
+--color-success: var(--color-base0B);
+--color-error: var(--color-base08);
 ```
 
 ---
@@ -241,6 +244,34 @@ Props: `content`, `position` (top/bottom/left/right), `delay` ({show, hide}), `o
 
 Props: `orientation` (horizontal/vertical), `thickness`, `spacing`, `children`
 
+### Stat
+```svelte
+<Stat value="42" label="Users" />
+<Stat value="95%" label="Uptime" status="success" />
+<Stat value="75" max={100} label="Progress" showBar />
+<Stat value="12" unit="/15" label="Tasks" status="warning" />
+<Stat value="8" label="Errors" href="/errors" status="error" />
+```
+
+Props: `value`, `label`, `unit`, `secondary`, `status` (success/warning/error/info), `size` (sm/md/lg), `showBar`, `barValue`, `max`, `href`
+
+### Alert
+```svelte
+<Alert variant="info">This is an informational message.</Alert>
+<Alert variant="warning" title="Warning">Please review your settings.</Alert>
+<Alert variant="error" dismissible onclose={() => showAlert = false}>
+  An error occurred.
+</Alert>
+<Alert variant="success">
+  {#snippet icon()}
+    <CheckIcon size={16} />
+  {/snippet}
+  Your changes have been saved.
+</Alert>
+```
+
+Props: `variant` (info/success/warning/error), `title`, `dismissible`, `size` (sm/md/lg), `onclose`, `icon` (snippet), `actions` (snippet)
+
 ### Avatar
 ```svelte
 <Avatar src="/user.jpg" alt="John Doe" />
@@ -316,6 +347,72 @@ Props: `tabs` (array), `active`, `variant` (default/underline/pills), `size` (sm
 Accordion props: `expanded` (array of ids), `multiple`
 AccordionItem props: `id`, `title`, `disabled`
 
+### CodeBlock
+```svelte
+<script>
+  import { CodeBlock } from '@miozu/jera';
+</script>
+
+<CodeBlock
+  code={`const greeting = "Hello";`}
+  lang="javascript"
+  filename="example.js"
+  showLineNumbers
+/>
+```
+
+Props: `code`, `lang` (default: javascript), `filename`, `showLineNumbers`, `class`
+
+**Requires:** `shiki` package for syntax highlighting.
+
+### PropsTable
+```svelte
+<script>
+  import { PropsTable } from '@miozu/jera';
+</script>
+
+<PropsTable props={[
+  { name: 'variant', type: 'string', default: '"default"', description: 'Visual style' },
+  { name: 'onclick', type: 'function', required: true, description: 'Click handler' }
+]} />
+```
+
+Props: `props` (array of PropDef), `class`
+
+PropDef: `{ name, type, default?, description, required? }`
+
+### SplitPane
+```svelte
+<script>
+  import { SplitPane, CodeBlock } from '@miozu/jera';
+</script>
+
+<SplitPane ratio="1:1" gap="2rem" stickyRight>
+  {#snippet left()}
+    <h2>Description</h2>
+    <p>Explanation of the feature...</p>
+  {/snippet}
+  {#snippet right()}
+    <CodeBlock code={exampleCode} lang="javascript" />
+  {/snippet}
+</SplitPane>
+```
+
+Props: `left` (snippet), `right` (snippet), `ratio` (e.g., '1:1', '2:1'), `gap`, `minHeight`, `stickyRight`, `class`
+
+### DocSection
+```svelte
+<script>
+  import { DocSection, CodeBlock } from '@miozu/jera';
+</script>
+
+<DocSection id="installation" title="Installation" description="How to install">
+  <CodeBlock code="npm install @miozu/jera" lang="bash" />
+</DocSection>
+```
+
+Props: `id`, `title`, `description`, `level` (2-6), `showAnchor`, `children`, `class`
+
 ---
 
 ## Actions Reference
@@ -358,32 +455,226 @@ AccordionItem props: `id`, `title`, `disabled`
 2. Use semantic naming
 3. Add light theme variant if applicable
 
-### Theme Switching
+### Theme Switching (Single Source of Truth Pattern)
+
+jera uses a singleton pattern for global theme state. Storage key: `miozu-theme`.
+
+#### SvelteKit Execution Order (from source code analysis)
+
+Understanding when code runs helps choose the right pattern:
+
+| Phase | File | Server | Client | Notes |
+|-------|------|--------|--------|-------|
+| 1 | +layout.server.js | ✓ | - | Server-only data |
+| 2 | +layout.js | ✓ | ✓ | Universal load, runs on EVERY navigation |
+| 3 | +layout.svelte `<script>` | ✓ | ✓ | Component script, runs once on mount |
+| 4 | +layout.svelte `onMount()` | - | ✓ | Client-only, after hydration |
+
+**Key insight from SvelteKit source (`client.js:684`):**
+```javascript
+data = { ...data, ...node.data };  // Parent data cascades to children
+```
+
+#### Recommended Pattern: +layout.svelte (for singletons like theme)
+
+For global singleton state that doesn't need server context:
+
+```svelte
+<!-- +layout.svelte - Initialize ONCE, pass via props -->
+<script>
+  import { getTheme } from '@miozu/jera';
+  import { onMount } from 'svelte';
+  import { Sidebar } from '$components';
+
+  // Call singleton once in root layout
+  const themeState = getTheme();
+
+  onMount(() => {
+    themeState.sync();  // Hydrate from DOM (app.html)
+    themeState.init();  // Setup media query listener
+  });
+</script>
+
+<!-- Pass themeState as prop to children -->
+<Sidebar {themeState} />
+```
+
+```svelte
+<!-- Child component - receives themeState as prop -->
+<script>
+  // DON'T call getTheme() here - receive as prop instead
+  let { themeState } = $props();
+
+  function handleToggle() {
+    themeState.toggle();
+  }
+
+  let isDark = $derived(themeState.isDark);
+</script>
+```
+
+#### Alternative Pattern: +layout.js (for data-heavy state)
+
+For state that needs server context or async initialization:
+
 ```javascript
-// System preference detection
-const theme = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
-document.documentElement.setAttribute('data-theme', theme);
-
-// Or use ThemeState class
-import { createThemeContext } from '@miozu/jera';
-const theme = createThemeContext();
-theme.init(); // Reads from localStorage/system
-theme.toggle();
-```
-
-### Supported Theme Selectors
-jera supports multiple theme attribute values for flexibility:
-
-| Theme | Selectors |
-|-------|-----------|
-| Dark | `[data-theme="dark"]`, `[data-theme="miozu-dark"]`, `.dark` |
-| Light | `[data-theme="light"]`, `[data-theme="miozu-light"]`, `.light` |
-| High Contrast | `[data-theme="high-contrast"]` |
-
-This allows jera to integrate with any theming system. For example:
-- Selify apps use `miozu-dark` / `miozu-light`
-- Generic apps can use `dark` / `light`
-- Class-based theming via `.dark` / `.light`
+// +layout.js - Universal load
+export const load = async ({ data, fetch }) => {
+  // Can fetch data, access parent(), etc.
+  const someData = await fetch('/api/data').then(r => r.json());
+
+  return {
+    ...data,
+    someData
+  };
+};
+```
+
+**When to use which:**
+
+| Use +layout.svelte | Use +layout.js |
+|-------------------|----------------|
+| Singletons (theme, toast) | Fetched data |
+| Client-only initialization | Async operations |
+| No server context needed | Needs `parent()` data |
+| Runs once per mount | Needs invalidation support |
+
+**ThemeState API:**
+```javascript
+themeState.toggle();         // Toggle dark/light
+themeState.set('dark');      // Set to dark
+themeState.set('light');     // Set to light
+themeState.set('system');    // Follow system preference
+
+// Reactive properties
+themeState.current;    // 'light' | 'dark' | 'system'
+themeState.resolved;   // 'light' | 'dark' (actual resolved value)
+themeState.dataTheme;  // 'miozu-light' | 'miozu-dark'
+themeState.isDark;     // boolean
+themeState.isLight;    // boolean
+```
+
+**Why pass as props instead of calling `getTheme()` everywhere?**
+1. **Explicit data flow** - You see what state each component depends on
+2. **Better testing** - Can inject mock state easily
+3. **Single initialization** - Clear where state originates
+4. **Efficiency** - Singleton runs once, not on every navigation
+
+### Theme Data Attributes
+
+| Theme | data-theme value |
+|-------|------------------|
+| Dark | `miozu-dark` |
+| Light | `miozu-light` |
+
+CSS selectors should use:
+```css
+[data-theme='miozu-dark'] { /* dark styles */ }
+[data-theme='miozu-light'] { /* light styles */ }
+```
+
+### Migration Guide: Custom Theme → Jera Singleton
+
+If you have a custom `theme.svelte.js` or similar, follow these steps:
+
+#### Step 1: Update app.html
+Replace custom theme script with unified storage key:
+```javascript
+// CRITICAL: Prevent FOUC - runs before any CSS
+(function () {
+  try {
+    let pref = localStorage.getItem('miozu-theme');
+
+    // Migrate from old keys if needed
+    if (!pref || !['light', 'dark', 'system'].includes(pref)) {
+      const oldTheme = localStorage.getItem('theme'); // or your old key
+      if (oldTheme === 'miozu-dark' || oldTheme === 'dark') pref = 'dark';
+      else if (oldTheme === 'miozu-light' || oldTheme === 'light') pref = 'light';
+    }
+
+    // Resolve theme
+    let theme;
+    if (pref === 'light') theme = 'miozu-light';
+    else if (pref === 'dark') theme = 'miozu-dark';
+    else {
+      theme = window.matchMedia?.('(prefers-color-scheme: dark)').matches
+        ? 'miozu-dark' : 'miozu-light';
+      pref = 'system';
+    }
+
+    // Apply and persist
+    document.documentElement.setAttribute('data-theme', theme);
+    document.documentElement.style.colorScheme = theme === 'miozu-dark' ? 'dark' : 'light';
+    localStorage.setItem('miozu-theme', pref);
+    document.cookie = 'miozu-theme=' + pref + '; path=/; max-age=31536000; SameSite=Lax';
+
+    // Clean up old keys
+    localStorage.removeItem('theme');
+  } catch (e) {
+    document.documentElement.setAttribute('data-theme', 'miozu-dark');
+  }
+})();
+```
+
+#### Step 2: Update +layout.svelte
+```svelte
+<script>
+  import { getTheme } from '@miozu/jera';
+  import { onMount } from 'svelte';
+
+  const themeState = getTheme();
+
+  onMount(() => {
+    themeState.sync();
+    themeState.init();
+  });
+</script>
+```
+
+#### Step 3: Update +layout.js
+Remove any theme initialization - it should NOT be in +layout.js:
+```javascript
+// REMOVE these lines:
+// import { ThemeReactiveState } from '$lib/reactiveStates/theme.svelte.js';
+// const themeState = new ThemeReactiveState();
+// return { themeState, ... };
+```
+
+#### Step 4: Update components using theme
+```svelte
+<script>
+  // OLD (remove):
+  // import { getThemeState } from '$lib/reactiveStates/theme.svelte.js';
+  // const themeState = getThemeState();
+
+  // NEW:
+  import { getTheme } from '@miozu/jera';
+  const themeState = getTheme();
+
+  let isDark = $derived(themeState.isDark);
+</script>
+```
+
+#### Step 5: Delete old theme file
+```bash
+rm src/lib/reactiveStates/theme.svelte.js
+```
+
+#### Step 6: Verify no old imports remain
+```bash
+grep -r "theme.svelte.js\|getThemeState\|ThemeReactiveState" src/
+# Should return no matches
+```
+
+### Apps Using Jera Theme (Proof of Concept)
+
+| App | Status | Storage Key |
+|-----|--------|-------------|
+| dash.selify.ai | ✓ Migrated | `miozu-theme` |
+| admin.selify.ai | ✓ Migrated | `miozu-theme` |
+| miozu.com | ✓ Migrated | `miozu-theme` |
+
+All three apps share the same theme preference via unified `miozu-theme` localStorage key.
 
 ---
 

package/README.md

@@ -48,18 +48,20 @@ Import tokens for consistent styling:
 @import '@miozu/jera/tokens/effects';
 ```
 
-### Miozu Color Palette
-
-| Base | Hex | Accent | Hex |
-|------|-----|--------|-----|
-| base0 | `#232733` | magenta | `#C974E6` |
-| base1 | `#2C3040` | blue | `#83D2FC` |
-| base2 | `#3E4359` | green | `#6DD672` |
-| base3 | `#565E78` | yellow | `#E8D176` |
-| base4 | `#737E99` | red | `#EB3137` |
-| base5 | `#D0D2DB` | cyan | `#40FFE2` |
-| base6 | `#F3F4F7` | orange | `#FF9837` |
-| base7 | `#FAFDFB` | peach | `#FF9982` |
+### Miozu Base16 Color Palette
+
+Standard Base16 naming: `base00`-`base0F` (hex digits).
+
+| Grayscale | Usage | Accents | Usage |
+|-----------|-------|---------|-------|
+| `base00` | Background | `base08` | Error (Red) |
+| `base01` | Surface | `base09` | Warning (Orange) |
+| `base02` | Selection | `base0A` | Highlight (Yellow) |
+| `base03` | Muted | `base0B` | Success (Green) |
+| `base04` | Secondary text | `base0C` | Info (Cyan) |
+| `base05` | Primary text | `base0D` | Primary (Blue) |
+| `base06` | High emphasis | `base0E` | Accent (Purple) |
+| `base07` | Maximum contrast | `base0F` | Secondary accent |
 
 ## Components
 
@@ -172,23 +174,29 @@ button({ variant: 'secondary' }); // => "inline-flex items-center bg-surface h-1
 
 ## Theming
 
-Dark theme is default. Switch themes with `data-theme` attribute:
+Dark theme is default. Uses singleton pattern with `miozu-theme` storage key.
 
-```html
-<html data-theme="dark">  <!-- Dark (default) -->
-<html data-theme="light"> <!-- Light -->
-```
+```javascript
+// In root +layout.svelte
+import { getTheme } from '@miozu/jera';
+import { onMount } from 'svelte';
 
-Or use ThemeState:
+const theme = getTheme();
+onMount(() => theme.init());
+```
 
 ```javascript
-import { createThemeContext } from '@miozu/jera';
+// Anywhere in your app
+import { getTheme } from '@miozu/jera';
 
-const theme = createThemeContext();
-theme.init();    // Reads from localStorage/system preference
-theme.toggle();  // Switch between light/dark
+const theme = getTheme();
+theme.toggle();        // Switch between light/dark
+theme.set('system');   // Follow system preference
+theme.isDark;          // boolean reactive property
 ```
 
+Data-theme values: `miozu-dark` (default) or `miozu-light`.
+
 ## AI-First Design
 
 This library includes AI-optimized documentation:

package/llms.txt

@@ -56,9 +56,42 @@ const button = cv({
 // Usage: button({ variant: 'secondary', size: 'sm' })
 ```
 
-### Theme Usage Pattern
+### Theme Usage Pattern (Single Source of Truth)
+
+**SvelteKit Execution Order:**
+1. +layout.server.js (server only)
+2. +layout.js (server + client, runs on EVERY navigation)
+3. +layout.svelte script (runs once on mount)
+4. onMount() (client only, after hydration)
+
+**Recommended: Initialize in +layout.svelte** (for singletons):
+```svelte
+<!-- +layout.svelte -->
+<script>
+  import { getTheme } from '@miozu/jera';
+  import { onMount } from 'svelte';
+
+  const themeState = getTheme();  // Call ONCE
+  onMount(() => {
+    themeState.sync();   // Hydrate from DOM
+    themeState.init();   // Setup media query listener
+  });
+</script>
+
+<!-- Pass to children as props -->
+<Sidebar {themeState} />
+```
+
+**Child components receive as prop:**
 ```javascript
-import { ThemeState, createThemeContext } from '@miozu/jera';
-const theme = createThemeContext(); // In root layout
-theme.toggle(); // Switch between light/dark
+let { themeState } = $props();  // DON'T call getTheme()
+themeState.toggle();            // Switch light/dark
+themeState.isDark;              // Reactive boolean
 ```
+
+**Why +layout.svelte over +layout.js for singletons?**
+- Runs once per mount (not on every navigation)
+- onMount clearly separates SSR from client code
+- More efficient for global state that doesn't change
+
+Storage key: `miozu-theme`. Data-theme values: `miozu-dark` | `miozu-light`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miozu/jera",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "Minimal, reactive component library for Svelte 5",
   "type": "module",
   "scripts": {
@@ -26,7 +26,17 @@
     "CLAUDE.md"
   ],
   "peerDependencies": {
-    "svelte": "^5.0.0"
+    "svelte": "^5.0.0",
+    "shiki": "^3.0.0",
+    "@lucide/svelte": "^0.500.0"
+  },
+  "peerDependenciesMeta": {
+    "shiki": {
+      "optional": true
+    },
+    "@lucide/svelte": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "svelte": "^5.41.0"