decantr 0.9.0

package/reference/state.md

@@ -0,0 +1,194 @@
+# State Module Reference
+
+`import { createSignal, createEffect, createMemo, createStore, batch, createContext, createSelector, createDeferred, createHistory, useLocalStorage, untrack, peek, createRoot, getOwner, runWithOwner, onError, on } from 'decantr/state';`
+
+## What's New (v0.5.0)
+
+| Feature | Description | Cross-ref |
+|---------|-------------|-----------|
+| `createRoot` | Independent reactive scope with disposal | §createRoot |
+| `getOwner` / `runWithOwner` | Ownership tree introspection and transfer | §Ownership |
+| `onError` | Error boundaries in the reactive graph | §Error Boundaries |
+| `on()` | Explicit dependency tracking | §on |
+| Dependency cleanup | Effects auto-remove from old signal subscriber sets on re-run | Automatic |
+| Topological flush | Diamond-problem fix — effects sorted by level before flush | Automatic |
+| `createResource` **removed** | Replaced by `createQuery` in `decantr/data` | `reference/state-data.md` |
+
+## createSignal(initial)
+
+Returns `[getter, setter]` tuple. Getter auto-tracks in effects/memos. Setter accepts value or updater function.
+
+| Call | Behavior |
+|------|----------|
+| `setter(5)` | Set value to `5` |
+| `setter(prev => prev + 1)` | Update from previous value |
+
+Skips notification if new value is identical (`Object.is`).
+
+## createEffect(fn)
+
+Runs `fn` immediately, auto-tracks all signal reads inside. Re-runs when any tracked signal changes. Returns `dispose()` function.
+
+| Detail | Behavior |
+|--------|----------|
+| Auto-tracking | Reads during `fn` execution subscribe the effect |
+| Dependency cleanup | On re-run, effect removes itself from old signal subscriber sets before re-tracking |
+| Cleanup | If `fn` returns a function, it runs before next execution and on dispose |
+| Dispose | `const dispose = createEffect(fn); dispose();` stops all future runs |
+| Batching | During `batch()`, effects are deferred to topological flush |
+| Error handling | Errors propagate up the ownership tree to nearest `onError` handler |
+
+## createMemo(fn)
+
+Cached derived computation. Returns a getter. Recomputes lazily when dependencies change. Tracks reads like a signal — effects depending on the memo re-run only when the memo's value changes.
+
+```js
+const [a, setA] = createSignal(1);
+const double = createMemo(() => a() * 2);
+double(); // 2
+```
+
+## createStore(initialValue)
+
+Proxy-wrapped object with per-property reactive tracking. Reading a property inside an effect subscribes to that property. Writing a property notifies only subscribers of that specific key.
+
+| Detail | Behavior |
+|--------|----------|
+| Tracking granularity | Per top-level property (not deep — see `decantr/state/store` for deep stores) |
+| Identity check | Skips notification on `Object.is` equality |
+| Return value | The proxy itself (mutate in place) |
+
+## batch(fn)
+
+Defers all effect runs until `fn` completes. Supports nesting — flush happens when outermost `batch` exits. Flush uses topological ordering.
+
+```js
+batch(() => {
+  setA(1);
+  setB(2); // effects run once after both updates
+});
+```
+
+## createRoot(fn)
+
+Create an independent reactive scope. `fn` receives a `dispose` function. All effects/memos created inside are owned by this root and disposed when `dispose()` is called.
+
+```js
+const result = createRoot(dispose => {
+  const [count, setCount] = createSignal(0);
+  createEffect(() => console.log(count()));
+  // dispose() cleans up effect and all children
+  return { count, setCount, dispose };
+});
+```
+
+## getOwner() / runWithOwner(owner, fn)
+
+Introspect and transfer ownership context. Useful for effects created outside the normal component tree (e.g., in setTimeout, event handlers).
+
+```js
+const owner = getOwner(); // capture in sync context
+setTimeout(() => {
+  runWithOwner(owner, () => {
+    createEffect(() => { /* properly owned */ });
+  });
+}, 1000);
+```
+
+## onError(handler)
+
+Register an error handler on the current owner. When an effect throws, the error walks up the ownership tree to find the nearest handler.
+
+```js
+createRoot(() => {
+  onError(err => console.error('Caught:', err));
+  createEffect(() => { throw new Error('boom'); }); // caught by handler
+});
+```
+
+## on(deps, fn, options?)
+
+Explicit dependency tracking. Reads `deps` inside tracking context, calls `fn` inside `untrack()`. Useful when you need to read a signal inside an effect without subscribing to it.
+
+| Option | Description |
+|--------|-------------|
+| `defer` | If `true`, skip initial run (default: `false`) |
+
+```js
+const [count, setCount] = createSignal(0);
+const [name] = createSignal('World');
+
+// Only re-runs when count changes, not when name changes
+on(count, (value, prev) => {
+  console.log(`count: ${prev} → ${value}, name: ${name()}`);
+});
+```
+
+Supports array of dependencies:
+```js
+on([a, b], ([aVal, bVal], [prevA, prevB]) => { ... });
+```
+
+## createContext(defaultValue?)
+
+Dependency injection via Provider/consume pattern. Returns `{ Provider, consume }`.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `Provider` | `(value: T) => () => void` | Sets context value, returns restore function |
+| `consume` | `() => T` | Reads current value (or `defaultValue`) |
+
+```js
+const ThemeCtx = createContext('light');
+const restore = ThemeCtx.Provider('dark');
+ThemeCtx.consume(); // 'dark'
+restore(); // restores previous value
+```
+
+## createSelector(source)
+
+Per-key memoization for efficient list highlighting. Returns `isSelected(key)` — a reactive check that only notifies when a specific key's match status changes.
+
+```js
+const [selected, setSelected] = createSignal('a');
+const isSelected = createSelector(selected);
+// In a list item: isSelected('a') returns true, re-runs only when 'a' gains/loses selection
+```
+
+## createDeferred(fn)
+
+Like `createMemo` but lazy-initialized — does not compute until the returned getter is first called. Subsequent reads use cached value until dependencies change, then recomputes on next read.
+
+## createHistory(signal, options?)
+
+Undo/redo history tracking for a signal.
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `signal` | `[getter, setter]` | Signal tuple from `createSignal` |
+| `options.maxLength` | `number` | Max undo depth (default: `100`) |
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `canUndo` | `() => boolean` | Signal getter |
+| `canRedo` | `() => boolean` | Signal getter |
+| `undo` | `() => void` | Restore previous value |
+| `redo` | `() => void` | Re-apply undone value |
+| `clear` | `() => void` | Reset history to current value |
+
+## useLocalStorage(key, initial)
+
+Signal backed by `localStorage` with JSON serialization. Returns `[getter, setter]` — same API as `createSignal`.
+
+## untrack(fn) / peek(getter)
+
+Read signals without subscribing the current effect.
+
+| Function | Use case |
+|----------|----------|
+| `untrack(fn)` | Run `fn` with tracking disabled |
+| `peek(getter)` | Alias for `untrack(getter)` |
+
+---
+
+**See also:** `reference/state-data.md`, `reference/component-lifecycle.md`, `reference/router.md`

package/reference/style-system.md

@@ -0,0 +1,110 @@
+# Style + Mode System
+
+Decantr uses an orthogonal **style x mode** architecture. Visual personality (style) is independent from color mode (light/dark/auto).
+
+## Styles (Visual Personality)
+
+| Style | Description | Personality |
+|-------|-------------|-------------|
+| auradecantism | **(default)** Dark glass aesthetic — vibrant purple/cyan/pink palette, mesh gradients, luminous glow, frosted surfaces | radius:pill, elevation:glass, motion:bouncy, borders:thin, density:comfortable, gradient:vivid |
+| clean | Modern minimal — rounded corners, subtle shadows, smooth motion | radius:rounded, elevation:subtle, motion:smooth, borders:thin, density:comfortable, gradient:none |
+| retro | Neobrutalism — sharp corners, offset shadows, bold borders | radius:sharp, elevation:brutalist, motion:snappy, borders:bold, density:comfortable, gradient:none |
+| glassmorphism | Frosted glass — translucent surfaces, vivid gradients, bouncy motion | radius:pill, elevation:glass, motion:bouncy, borders:thin, density:comfortable, gradient:vivid |
+| command-center | HUD/radar monochromatic — dark operational panels, beveled frames, scanlines, monospace typography | radius:sharp, elevation:flat, motion:snappy, borders:bold, density:compact, gradient:none, palette:monochrome |
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| light | Light color scheme |
+| dark | Dark color scheme |
+| auto | Tracks system `prefers-color-scheme`, listens for changes |
+
+## Seed-Derived Token System
+
+10 seed colors + 6 personality traits are algorithmically expanded into **280+ CSS custom properties** by `src/css/derive.js`. No manual color definitions needed — everything is computed.
+
+**Seed colors:** primary, accent, tertiary, neutral, success, warning, error, info, bg, bgDark
+**Personality traits:** radius (sharp/rounded/pill), elevation (flat/subtle/raised/glass/brutalist), motion (instant/snappy/smooth/bouncy), borders (none/thin/bold), density (compact/comfortable/spacious), gradient (none/subtle/vivid/mesh)
+
+## Custom Styles
+
+```javascript
+registerStyle({
+  id: 'my-style',
+  name: 'My Style',
+  seed: { primary: '#6366f1', accent: '#ec4899', bg: '#ffffff', bgDark: '#0a0a0a' },
+  personality: { radius: 'pill', elevation: 'glass', motion: 'bouncy', borders: 'none' },
+  typography: { '--d-fw-heading': '800' },  // optional overrides
+  overrides: { light: {}, dark: {} },       // optional per-mode token overrides
+  components: '',                            // optional component CSS
+});
+```
+
+## Shape API
+
+Shapes control border-radius personality independently from the style. Available shapes: `sharp`, `rounded`, `pill`.
+
+```javascript
+setShape('pill');   // All components use pill radius
+getShape();         // 'pill'
+getShapeList();     // ['sharp', 'rounded', 'pill']
+```
+
+Shapes override the style's default radius. The command-center style defaults to `sharp`; glassmorphism defaults to `pill`.
+
+## Colorblind Mode
+
+Colorblind mode is an orthogonal axis alongside style, mode, and shape: `Style x Mode x Shape x ColorblindMode`.
+
+```javascript
+setColorblindMode('protanopia');  // Red-green CVD safety
+setColorblindMode('deuteranopia'); // Red-green CVD safety (same shifts)
+setColorblindMode('tritanopia');   // Blue-yellow CVD safety
+setColorblindMode('off');          // Default (no transformation)
+getColorblindMode();               // Signal getter
+```
+
+**Architecture:** Seeds are transformed BEFORE `derive()` processes them, so all derived tokens (hover, active, subtle, border, chart, gradient) automatically adapt. Chart tokens are replaced with Wong/Okabe-Ito adapted palettes for maximum CVD safety.
+
+**Seed shifts (protanopia/deuteranopia):** error red -> magenta (OKLCH H ~345), success green -> teal (OKLCH H ~190). Primary/accent/tertiary shifted if in red or green hue zones.
+
+**Seed shifts (tritanopia):** info blue -> teal (OKLCH H ~170), warning yellow -> orange (OKLCH H ~50). Primary shifted if in blue hue zone.
+
+`resetStyles()` resets colorblind mode to `'off'`. See `reference/color-guidelines.md` for full documentation.
+
+## OKLCH Color Space
+
+All color math in `derive.js` uses **OKLCH** (perceptually uniform color space) instead of HSL. This means:
+- `lighten(hex, amount)` and `darken(hex, amount)` adjust the OKLCH L channel
+- `mixColors(hex1, hex2, weight)` interpolates in OKLCH space with short-arc hue blending
+- `rotateHue(hex, degrees)` rotates the OKLCH H channel
+- Hover states look more consistent across all 7 palette roles (same perceived brightness shift regardless of hue)
+- `adjustForContrast()` converges faster due to perceptual uniformity
+
+Internal exports for testing/advanced use: `rgbToOklch(r,g,b)`, `oklchToRgb(L,C,H)`, `gamutMap(L,C,H)`.
+
+## Monochrome Palette
+
+The `palette: 'monochrome'` personality trait (used by command-center) derives all 7 role colors from a single primary hue. All shifts stay within ±20° of base hue; distinguishability comes via lightness/saturation. WCAG AA validated via `validateContrast()`.
+
+## Backward Compatibility
+
+`setTheme()`, `getTheme()`, `registerTheme()` are backward-compatible wrappers around the Style+Mode API. Legacy `--c0`–`--c9` color variables and `_fg0`–`_fg9` atoms have been removed — use semantic atoms (`_fgfg`, `_fgmutedfg`, `_fgprimary`, etc.) instead.
+
+## Build-Time Style Elimination
+
+At build time, unused style modules are automatically detected and removed from the bundle. The build pipeline scans user code for `setStyle()` and `setTheme()` calls, and checks `decantr.essence.json` and `decantr.config.json` for style references. Only the default style (auradecantism) and explicitly referenced styles are shipped. For a default app using only auradecantism, this eliminates 4 unused styles and saves ~17 KB raw.
+
+See `reference/build-tooling.md` for full details on the detection and elimination pipeline.
+
+## Key Files
+
+- `src/css/derive.js` — Color math, personality presets, main `derive()` function
+- `src/css/styles/auradecantism.js` / `clean.js` / `retro.js` / `glassmorphism.js` / `command-center.js` — Style definitions
+- `src/css/theme-registry.js` — State management, DOM injection, public API
+- `src/css/index.js` — Public CSS module exports
+
+---
+
+**See also:** `reference/tokens.md`, `reference/decantation-process.md`, `reference/atoms.md`