decantr 0.9.0

package/reference/component-lifecycle.md

@@ -0,0 +1,137 @@
+# Component Lifecycle & Cleanup
+
+## The Problem
+
+Decantr components return raw `HTMLElement` nodes — not wrapper objects with lifecycle methods. This means cleanup (removing document listeners, clearing timers, disconnecting observers) requires explicit wiring. Without it, components leak resources when removed from the DOM.
+
+## Cleanup Contract
+
+**Every component that adds document-level listeners, timers, or observers MUST clean them up.** This applies to:
+
+- `document.addEventListener(...)` — click-outside, escape-to-close, resize, scroll
+- `setTimeout` / `setInterval` — debounced actions, animation timers, polling
+- `IntersectionObserver` / `ResizeObserver` / `MutationObserver`
+- `window.addEventListener(...)` — resize, scroll, popstate
+
+## How Cleanup Works
+
+### Pattern 1: Use `_behaviors.js` primitives (preferred)
+
+All behavioral primitives in `_behaviors.js` return `{ destroy() }`. Components MUST call `.destroy()` when removed.
+
+```javascript
+import { createOverlay, createListbox, createFocusTrap } from './_behaviors.js';
+
+export function Select(props) {
+  const trigger = /* ... */;
+  const panel = /* ... */;
+
+  const overlay = createOverlay(trigger, panel, { trigger: 'click' });
+  const listbox = createListbox(panel, { onSelect: /* ... */ });
+
+  // Wire cleanup to element removal
+  const el = h('div', { class: 'd-select' }, trigger, panel);
+  onDestroy(() => {
+    overlay.destroy();
+    listbox.destroy();
+  });
+  return el;
+}
+```
+
+### Pattern 2: Manual cleanup collection
+
+For components that add their own listeners (not via behaviors):
+
+```javascript
+export function MyComponent(props) {
+  const cleanups = [];
+
+  const onResize = () => { /* ... */ };
+  window.addEventListener('resize', onResize);
+  cleanups.push(() => window.removeEventListener('resize', onResize));
+
+  const timer = setInterval(poll, 5000);
+  cleanups.push(() => clearInterval(timer));
+
+  const el = h('div', { /* ... */ });
+  onDestroy(() => cleanups.forEach(fn => fn()));
+  return el;
+}
+```
+
+### Pattern 3: MutationObserver self-cleanup (last resort)
+
+When `onDestroy` context is unavailable (e.g., dynamically created elements):
+
+```javascript
+const observer = new MutationObserver((mutations) => {
+  for (const m of mutations) {
+    for (const node of m.removedNodes) {
+      if (node === el || node.contains(el)) {
+        cleanup();
+        observer.disconnect();
+      }
+    }
+  }
+});
+observer.observe(el.parentNode, { childList: true });
+```
+
+## Available `_behaviors.js` Primitives
+
+| Primitive | Returns `destroy()`? | Use For |
+|-----------|---------------------|---------|
+| `createOverlay()` | Yes | Click-outside, escape, show/hide, ARIA expanded |
+| `createListbox()` | Yes | Arrow-key navigation, selection, type-ahead |
+| `createDisclosure()` | No (uses element listeners only) | Expand/collapse with animation |
+| `createRovingTabindex()` | Yes | Tab navigation within groups |
+| `createFocusTrap()` | Yes (via `deactivate()`) | Modal/drawer focus containment |
+| `createDrag()` | Yes | Pointer-based drag interactions |
+| `createVirtualScroll()` | Yes | Large list rendering |
+| `createInfiniteScroll()` | Yes | Load-more sentinel |
+| `createMasonry()` | Yes | Pinterest-style layout |
+| `createScrollSpy()` | Yes (via `disconnect()`) | Section tracking |
+| `createHotkey()` | Yes | Keyboard shortcuts |
+
+## Checklist Before Shipping a Component
+
+1. Does this component add `document.addEventListener`? -> Use `createOverlay` or collect cleanup
+2. Does this component use `setTimeout`/`setInterval`? -> Clear on destroy
+3. Does this component create an `Observer`? -> Disconnect on destroy
+4. Does this component use `createOverlay`/`createListbox`/etc.? -> Call `.destroy()` via `onDestroy`
+5. Does this component add `window.addEventListener`? -> Remove on destroy
+
+## Known Components Needing Cleanup Audit
+
+**Completed** (have `onDestroy` wired — verified March 2026):
+- `modal.js` — uses `createFocusTrap`, cleanup via `onDestroy`
+- `select.js` — `onDestroy` added
+- `combobox.js` — `onDestroy` added
+- `context-menu.js` — `onDestroy` added
+- `tooltip.js` — `onDestroy` added
+- `slider.js` — `onDestroy` added
+- `image.js` — `onDestroy` added
+- `data-table.js` — `onDestroy` added
+- `dropdown.js` — `onDestroy` added
+
+**Remaining** — components that may still benefit from migrating to `_behaviors.js` primitives:
+- `slider.js` — document pointermove/pointerup (candidate for `createDrag`)
+- `data-table.js` — document pointermove/pointerup for column resize (candidate for `createDrag`)
+- `tour.js` — document keydown, window resize (has manual cleanup, could use `createHotkey`)
+
+## Workbench & Tooling Lifecycle
+
+The cleanup contract applies to **ALL code**, not just `src/components/`. Workbench explorer modules, docs site scripts, CLI preview tools — any code that adds event listeners, timers, or observers MUST wire `onDestroy` cleanup.
+
+**Common violations in tooling code:**
+
+- **Motion/animation demos** that add `mouseenter`/`mouseleave` listeners directly via `addEventListener` instead of element props (props are cleaned up with the element)
+- **Search modals** that add `keydown` document listeners without cleanup
+- **Live previews** that create `ResizeObserver` or `MutationObserver` without disconnecting
+
+**Rule:** If a workbench explorer section adds listeners, it follows the same contract as a framework component. Use element event props (e.g. `onmouseenter`) for element-scoped events, and `onDestroy` + `_behaviors.js` for document-level listeners.
+
+---
+
+**See also:** `reference/behaviors.md`, `reference/compound-spacing.md`

package/reference/compound-spacing.md

@@ -0,0 +1,95 @@
+# Compound Spacing, Offsets & Density
+
+> **Strategic guide**: For the full spatial design language — proximity tiers, density zones, responsive behavior, visual weight, and decision tables — see `reference/spatial-guidelines.md`. This document covers the implementation contracts for compound components.
+
+## Compound Spacing Contract
+
+All compound components (Card, Modal, AlertDialog, Drawer) follow a unified spacing contract via `--d-compound-pad` and `--d-compound-gap`. This ensures consistent header/body/footer spacing across all overlay and container components.
+
+| Section | Padding Rule |
+|---------|-------------|
+| **Header** | `var(--d-compound-pad) var(--d-compound-pad) 0` |
+| **Body** | `var(--d-compound-gap) var(--d-compound-pad)` |
+| **Body:last-child** | adds `padding-bottom: var(--d-compound-pad)` |
+| **Footer** | `var(--d-compound-gap) var(--d-compound-pad) var(--d-compound-pad)` |
+
+**Bordered footer exception:** When a compound footer has a visible `border-top` (e.g. Card), the border provides inter-section separation, so the footer uses `var(--d-compound-pad)` on all sides for vertical centering. The asymmetric `compound-gap` top is only appropriate when the gap alone is the separator (Modal, Drawer).
+
+New compound components MUST follow this contract. Never hardcode padding in header/body/footer — use the compound tokens.
+
+## Popup Offset Hierarchy
+
+> Full elevation hierarchy and offset strategy: `reference/spatial-guidelines.md` §11 Z-Axis Spatial Rules.
+
+All floating elements use offset tokens for trigger->panel distance. The hierarchy reflects visual weight:
+
+`--d-offset-dropdown` (2px) < `--d-offset-menu` (4px) < `--d-offset-tooltip` (6px) < `--d-offset-popover` (8px)
+
+New floating components MUST use the appropriate offset token, never hardcoded pixel values.
+
+## Density Classes
+
+> Full density rules, character mapping, and usage guidance: `reference/spatial-guidelines.md` §16 Density System Integration.
+
+`.d-compact`, `.d-comfortable`, `.d-spacious` — cascade to children, override `--d-density-pad-x`, `--d-density-pad-y`, `--d-density-gap`, `--d-density-min-h`, `--d-density-text`, `--d-compound-pad`, `--d-compound-gap`
+
+| Density | `--d-compound-pad` | `--d-compound-gap` | Controls | Interiors |
+|---------|--------------------|--------------------|----------|-----------|
+| compact | `var(--d-sp-3)` | `var(--d-sp-2)` | Tighter | Tighter |
+| comfortable | `var(--d-sp-5)` | `var(--d-sp-3)` | Default | Default |
+| spacious | `var(--d-sp-8)` | `var(--d-sp-4)` | Wider | Wider |
+
+## Field Sizing Contract
+
+> Component sizing tiers, touch targets, and inset patterns: `reference/spatial-guidelines.md` §7 Component Sizing.
+
+All form components support a unified 4-tier sizing system (xs/sm/md/lg). Height is the primary constraint; padding and font-size follow.
+
+**Core components** (Button, Select, Input, Toggle, Combobox) use per-component size classes (`.d-btn-sm`, `.d-select-sm .d-select`, `.d-input-sm`, etc.) that include `min-height` overrides.
+
+**Picker components** (DatePicker, TimePicker, Cascader, TreeSelect, ColorPicker, Mentions, InputNumber, DateRangePicker, TimeRangePicker) use `.d-field-{size}` utility classes that override density tokens locally:
+
+```css
+.d-field-xs { --d-density-min-h:var(--d-field-h-xs); --d-density-pad-y:var(--d-field-py-xs); ... }
+.d-field-sm { --d-density-min-h:var(--d-field-h-sm); ... }
+.d-field-lg { --d-density-min-h:var(--d-field-h-lg); ... }
+```
+
+Any child `.d-select`, `.d-input`, etc. inside a `.d-field-sm` wrapper inherits sm sizing via the density cascade — no per-component CSS needed.
+
+**Tier ↔ density mapping:** compact defaults = sm tokens, comfortable defaults = md tokens, spacious defaults = lg tokens. This means setting density to "compact" automatically makes all form elements 28px height.
+
+**Components with own size tokens:** Switch (`--d-switch-w/h/thumb-{tier}`), Checkbox/Radio (`--d-checkbox-size-{tier}`), InputOTP (`--d-otp-w/h/text-{tier}`).
+
+## Prose System
+
+`.d-prose` — auto-applies vertical rhythm to child elements. Use for long-form content (articles, documentation, modal descriptions).
+
+- Base: `font-size:var(--d-text-base); line-height:var(--d-lh-relaxed)`
+- Between siblings: `> * + * { margin-top: var(--d-sp-4) }`
+- Headings: graduated margin-top (sp-12->sp-10->sp-8->sp-6) + margin-bottom (sp-4->sp-3)
+- Lists: left padding, per-item spacing
+- Blockquote: left border + padding + italic
+- Code/pre: mono font, padding, surface background
+- Tables: cell padding, bottom borders
+
+Usage: `div({ class: 'd-prose' }, h1('Title'), p('Body text...'), ul(li('Item')))`
+
+## Spacing Utilities
+
+Child-spacing utilities use the `d-` prefix (not `_` atom prefix) because they require child combinators (`> * + *`) which cannot be expressed in the atom resolver.
+
+| Class | Effect |
+|-------|--------|
+| `d-spacey-{1-24}` | `> * + * { margin-top: {scale} }` — vertical child spacing |
+| `d-spacex-{1-24}` | `> * + * { margin-left: {scale} }` — horizontal child spacing |
+| `d-dividey` | `> * + * { border-top: 1px solid var(--d-border) }` |
+| `d-dividex` | `> * + * { border-left: 1px solid var(--d-border) }` |
+| `d-dividey-strong` | `> * + * { border-top: 1px solid var(--d-border-strong) }` |
+| `d-dividex-strong` | `> * + * { border-left: 1px solid var(--d-border-strong) }` |
+
+Scale: 1 (0.25rem) through 24 (6rem). Same spacing scale as `_p`/`_m` atoms.
+
+---
+
+**See also:** `reference/spatial-guidelines.md`, `reference/atoms.md`, `reference/tokens.md`