@miozu/jera 0.0.2 → 0.4.2

package/README.md

@@ -1 +1,219 @@
-# Jera
+# @miozu/jera
+
+A minimal, reactive component library for Svelte 5.
+
+**Jera** (ᛃ) — the rune of harvest and cycles. Build on foundations, yield results.
+
+## Features
+
+- **Miozu Design Tokens** — Base16 color system, spacing, typography, effects
+- **Reactive Utilities** — `cn()`, `cv()` for class composition with Svelte 5 runes
+- **Accessible Components** — Button, Input, Select, Badge, Checkbox, Switch, Toast
+- **Svelte Actions** — clickOutside, focusTrap, portal, escapeKey, and more
+- **AI-First Documentation** — Optimized for LLM-assisted development
+
+## Installation
+
+```bash
+pnpm add @miozu/jera
+```
+
+## Quick Start
+
+```svelte
+<script>
+  import { Button, Input, Badge } from '@miozu/jera';
+  import '@miozu/jera/tokens';
+
+  let email = $state('');
+</script>
+
+<Input bind:value={email} type="email" placeholder="Enter email" />
+<Button onclick={() => console.log(email)}>Submit</Button>
+<Badge variant="success">Active</Badge>
+```
+
+## Design Tokens
+
+Import tokens for consistent styling:
+
+```css
+/* All tokens */
+@import '@miozu/jera/tokens';
+
+/* Individual token sets */
+@import '@miozu/jera/tokens/colors';
+@import '@miozu/jera/tokens/spacing';
+@import '@miozu/jera/tokens/typography';
+@import '@miozu/jera/tokens/effects';
+```
+
+### 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
+
+### Button
+
+```svelte
+<Button variant="primary|secondary|ghost|outline|danger|success" size="xs|sm|md|lg|xl">
+  Click me
+</Button>
+<Button href="/about">Link Button</Button>
+<Button loading>Loading...</Button>
+```
+
+### Input
+
+```svelte
+<Input bind:value={text} placeholder="Enter text" />
+<Input type="password" disableBrowserFeatures />
+<Input error={!isValid} />
+```
+
+### Select
+
+```svelte
+<Select
+  options={[{ value: '1', label: 'Option 1' }]}
+  bind:value={selected}
+  placeholder="Choose..."
+/>
+```
+
+### Badge
+
+```svelte
+<Badge variant="default|primary|secondary|success|warning|error|info">
+  Status
+</Badge>
+```
+
+### Checkbox & Switch
+
+```svelte
+<Checkbox bind:checked={agreed}>I agree</Checkbox>
+<Switch bind:checked={enabled}>Enable notifications</Switch>
+```
+
+### Toast
+
+```svelte
+<!-- Root layout -->
+<script>
+  import { Toast, createToastContext } from '@miozu/jera';
+  createToastContext();
+</script>
+<Toast />
+
+<!-- Any component -->
+<script>
+  import { getToastContext } from '@miozu/jera';
+  const toast = getToastContext();
+  toast.success('Saved!');
+</script>
+```
+
+## Utilities
+
+### cn() — Class concatenation
+
+```javascript
+import { cn } from '@miozu/jera';
+
+cn('base', condition && 'conditional', ['array', 'classes']);
+// => "base conditional array classes"
+```
+
+### cv() — Class variants
+
+```javascript
+import { cv } from '@miozu/jera';
+
+const button = cv({
+  base: 'inline-flex items-center',
+  variants: {
+    variant: { primary: 'bg-primary', secondary: 'bg-surface' },
+    size: { sm: 'h-8', md: 'h-10' }
+  },
+  defaults: { variant: 'primary', size: 'md' }
+});
+
+button({ variant: 'secondary' }); // => "inline-flex items-center bg-surface h-10"
+```
+
+## Actions
+
+```svelte
+<script>
+  import { clickOutside, focusTrap, escapeKey, portal } from '@miozu/jera/actions';
+</script>
+
+<div use:clickOutside={() => close()}>
+  <dialog use:focusTrap={{ enabled: isOpen }}>
+    <div use:escapeKey={() => close()}>
+      Content
+    </div>
+  </dialog>
+</div>
+
+<div use:portal={'body'}>Renders at body level</div>
+```
+
+## Theming
+
+Dark theme is default. Uses singleton pattern with `miozu-theme` storage key.
+
+```javascript
+// In root +layout.svelte
+import { getTheme } from '@miozu/jera';
+import { onMount } from 'svelte';
+
+const theme = getTheme();
+onMount(() => theme.init());
+```
+
+```javascript
+// Anywhere in your app
+import { getTheme } from '@miozu/jera';
+
+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:
+
+- `llms.txt` — Structured index for LLM consumption
+- `CLAUDE.md` — Detailed context for AI assistants
+- JSDoc comments throughout the codebase
+
+## Browser Support
+
+- Chrome 88+
+- Firefox 78+
+- Safari 14+
+- Edge 88+
+
+Requires Svelte 5.0+
+
+## License
+
+MIT © [Nicholas Glazer](https://miozu.com)

package/llms.txt

@@ -0,0 +1,97 @@
+# @miozu/jera
+
+> A minimal, reactive component library for Svelte 5. Provides design tokens (Miozu Base16 color system), utility functions (cn, cv), Svelte actions, and accessible components. Designed for AI-assisted development with clear, predictable APIs.
+
+## Quick Start
+- [Installation](#installation): `pnpm add @miozu/jera`
+- [Basic Usage](#usage): Import components and tokens
+
+## Design Tokens
+- [Colors](/src/tokens/colors.css): Miozu Base16 palette with dark/light themes
+- [Spacing](/src/tokens/spacing.css): 4px-based spacing scale
+- [Typography](/src/tokens/typography.css): Font scales and weights
+- [Effects](/src/tokens/effects.css): Shadows, radius, transitions, z-index
+
+## Utilities
+- [cn()](/src/utils/cn.svelte.js): Class name concatenation with falsy filtering
+- [cv()](/src/utils/cn.svelte.js): Class variants for type-safe variant composition
+- [ThemeState](/src/utils/reactive.svelte.js): SSR-safe theme management
+
+## Components
+- [Button](/src/components/primitives/Button.svelte): Polymorphic button with 6 variants, 5 sizes
+- [Input](/src/components/forms/Input.svelte): Text input with validation support
+- [Select](/src/components/forms/Select.svelte): Accessible dropdown with keyboard navigation
+- [Badge](/src/components/primitives/Badge.svelte): Status tags with semantic variants
+- [Checkbox](/src/components/forms/Checkbox.svelte): Checkbox input
+- [Switch](/src/components/forms/Switch.svelte): Toggle switch
+- [Toast](/src/components/feedback/Toast.svelte): Notification system
+
+## Actions
+- [clickOutside](/src/actions/index.js): Detect clicks outside element
+- [focusTrap](/src/actions/index.js): Trap focus within element
+- [portal](/src/actions/index.js): Render element in different DOM location
+- [escapeKey](/src/actions/index.js): Handle escape key press
+
+## API Patterns
+
+### Component Props Pattern
+All components accept these common props:
+- `class`: Additional CSS classes (always merged)
+- `disabled`: Boolean to disable interaction
+- Event handlers: `onclick`, `onchange`, etc.
+
+### Class Variants Pattern
+```javascript
+import { cv } from '@miozu/jera';
+
+const button = cv({
+  base: 'inline-flex items-center',
+  variants: {
+    variant: { primary: 'bg-primary', secondary: 'bg-surface' },
+    size: { sm: 'h-8 px-3', md: 'h-10 px-4' }
+  },
+  defaults: { variant: 'primary', size: 'md' }
+});
+
+// Usage: button({ variant: 'secondary', size: 'sm' })
+```
+
+### 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
+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,24 +1,64 @@
 {
   "name": "@miozu/jera",
-  "version": "0.0.2",
-  "description": "Svelte 5 component library",
-  "main": "jera.js",
-  "bin": {
-    "jera": "./jera.js"
-  },
+  "version": "0.4.2",
+  "description": "Minimal, reactive component library for Svelte 5",
   "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "prepublishOnly": "echo 'Publishing @miozu/jera...' && test -f src/index.js"
+  },
+  "svelte": "./src/index.js",
+  "exports": {
+    ".": {
+      "svelte": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./tokens": "./src/tokens/index.css",
+    "./tokens/colors": "./src/tokens/colors.css",
+    "./tokens/spacing": "./src/tokens/spacing.css",
+    "./tokens/typography": "./src/tokens/typography.css",
+    "./tokens/effects": "./src/tokens/effects.css",
+    "./utils": "./src/utils/index.js",
+    "./actions": "./src/actions/index.js"
+  },
+  "files": [
+    "src",
+    "llms.txt",
+    "CLAUDE.md"
+  ],
+  "peerDependencies": {
+    "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"
+  },
+  "keywords": [
+    "svelte",
+    "svelte5",
+    "components",
+    "design-system",
+    "ui",
+    "miozu",
+    "base16",
+    "dark-theme"
+  ],
+  "author": "Nicholas Glazer <glazer.nicholas@gmail.com>",
+  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://codeberg.org/miozu/jera"
+    "url": "https://github.com/miozu-com/jera"
   },
-  "keywords": ["component library", "svelte 5", "sveltekit"],
-  "author": "Nicholas Glazer <info@nicgl.com>",
-  "license": "MIT",
-  "packageManager": "pnpm@10.6.5",
-  "dependencies": {
-    "commander": "^13.1.0"
+  "homepage": "https://miozu.com",
+  "bugs": {
+    "url": "https://github.com/miozu-com/jera/issues"
   }
 }