@rip-lang/ui 0.3.20 → 0.3.21

package/README.md

@@ -1,720 +1,590 @@
-<img src="https://raw.githubusercontent.com/shreeve/rip-lang/main/docs/rip.png" style="width:50px" /> <br>
+# Rip UI
 
-# Rip UI - @rip-lang/ui
+Headless, accessible UI components written in Rip. Zero dependencies. Zero CSS.
+Every widget exposes `$` attributes (compiled to `data-*`) for styling and
+handles keyboard interactions per WAI-ARIA Authoring Practices.
 
-> **Zero-build reactive web framework for the Rip language.**
+Components are plain `.rip` source files — no build step. The browser compiles
+them on the fly.
 
-Load the Rip compiler in the browser. Write inline Rip. Launch your app.
-No build step, no bundler, no configuration.
+---
 
 ## Quick Start
 
-**`index.rip`** — the server:
+Add the components directory to your serve middleware:
 
 ```coffee
-import { get, use, start, notFound } from '@rip-lang/api'
-import { ripUI } from '@rip-lang/ui/serve'
-
-dir = import.meta.dir
-use ripUI dir: dir, components: 'routes', includes: ['ui'], watch: true, title: 'My App'
-get '/css/*', -> @send "#{dir}/css/#{@req.path.slice(5)}"
-notFound -> @send "#{dir}/index.html", 'text/html; charset=UTF-8'
-start port: 3000
+use serve
+  dir: dir
+  components: ['components', '../../../packages/ui']
 ```
 
-**`index.html`** — the page:
+All widgets become available by name (`Select`, `Dialog`, `Grid`, etc.) in the
+shared scope — no imports needed.
 
-```html
-<script type="module" src="/rip/rip-ui.min.js"></script>
+```bash
+cd packages/ui
+rip server
 ```
 
-**`pages/index.rip`** — a page component:
+Every widget:
+- Handles all keyboard interactions per WAI-ARIA Authoring Practices
+- Sets correct ARIA attributes automatically
+- Exposes state via `$` sigil (`$open`, `$selected`) for CSS styling
+- Ships zero CSS — styling is entirely yours
+- Uses Rip's reactive primitives for all state management
 
-```coffee
-export Home = component
-  @count := 0
-  render
-    .
-      h1 "Hello from Rip UI"
-      button @click: (-> @count += 1), "Clicked #{@count} times"
-```
+---
 
-Run `bun index.rip`, open `http://localhost:3000`.
-
-## The Two Keywords
-
-Rip UI adds two keywords to the language: `component` and `render`. Each
-serves a distinct role, and together they form a complete reactive UI model.
-
-### `component` — the model
-
-Raw Rip Lang has no concept of a self-contained, reusable UI unit. The
-`component` keyword adds everything needed to manage interactive state:
-
-- **Reactive state** (`:=`) — assignments create signals that trigger
-  updates automatically. `count := 0` is not a plain variable; changing
-  it updates the DOM.
-- **Computed values** (`~=`) — derived values that recalculate when their
-  dependencies change. `remaining ~= todos.filter((t) -> not t.done).length`
-- **Effects** (`~>`) — side effects that run whenever reactive dependencies
-  change. `~> @app.data.count = count`
-- **Props** (`@` prefix, `=!` for readonly) — a public API for parent
-  components to pass data in, with signal passthrough for shared reactivity.
-- **Lifecycle hooks** — `beforeMount`, `mounted`, `updated`, `beforeUnmount`,
-  `unmounted` for running code at specific points in a component's life.
-- **Context API** — `setContext` and `getContext` for ancestor-to-descendant
-  data sharing without prop drilling.
-- **Mount/unmount mechanics** — attaching to the DOM, cascading teardown
-  to children, and keep-alive caching across navigation.
-- **Encapsulation** — each component is a class with its own scope, state,
-  and methods. No global variable collisions, no leaking internals.
-
-A component without a render block can still hold state, run effects, and
-participate in the component tree — it just has no visual output.
-
-### `render` — the view
-
-The `render` keyword provides a declarative template DSL for describing DOM
-structure. It has its own lexer pass and syntax rules distinct from regular
-Rip code:
-
-- **Element creation** — tag names become DOM nodes: `div`, `h1`, `button`
-- **CSS-selector shortcuts** — `div.card.active`, `#main`, `.card` (implicit `div`)
-- **Dynamic classes** — `div.('card', active && 'active')` with CLSX semantics
-- **Event handlers** — `@click: handler` compiles to `addEventListener`
-- **Two-way binding** — `value <=> username` wires reactive read and write
-  (see [Two-Way Binding](#two-way-binding--the--operator) below)
-- **Conditionals and loops** — `if`/`else` and `for item in items` with
-  anchor-based DOM insertion and keyed reconciliation
-- **Children/slots** — `@children` receives child nodes, `#content` marks
-  layout insertion points
-- **Component instantiation** — PascalCase names like `Card title: "Hello"`
-  resolve to components automatically, no imports needed
-
-Render compiles to two methods: `_create()` builds the DOM tree once, and
-`_setup()` wires reactive effects for fine-grained updates. There is no
-virtual DOM — each reactive binding creates a direct DOM effect that updates
-the specific text node or attribute that depends on it.
-
-A render block can only exist inside a component. It needs the component's
-signals, computed values, and lifecycle to have something to render and
-react to.
-
-### Together
-
-`component` provides the **model** — state, reactivity, lifecycle, identity.
-`render` provides the **view** — a concise way to describe what the DOM
-should look like and how it stays in sync with that state. One defines
-behavior, the other defines structure. Neither is useful without the other
-in practice, but they are separate concerns with separate syntax.
-
-## Component Composition
-
-Page components in `pages/` map to routes via file-based routing. Shared
-components in `ui/` (or any `includes` directory) are available by PascalCase
-name. No imports needed:
+## Rip in 60 Seconds
 
-```coffee
-# ui/card.rip
-export Card = component
-  title =! ""
-  render
-    .card
-      if title
-        h3 "#{title}"
-      @children
+If you're coming from React or another framework, here's the Rip you need
+to know to use these widgets:
 
-# pages/about.rip
-export About = component
-  render
-    .
-      h1 "About"
-      Card title: "The Idea"
-        p "Components compose naturally."
-      Card title: "Architecture"
-        p "PascalCase resolution, signal passthrough, children blocks."
-```
+| Syntax | Name | What It Does |
+|--------|------|-------------|
+| `:=` | State | `count := 0` — reactive state (like `useState`) |
+| `~=` | Computed | `doubled ~= count * 2` — derived value (like `useMemo`, but auto-tracked) |
+| `~>` | Effect | `~> document.title = "#{count}"` — side effect (like `useEffect`, but auto-tracked) |
+| `<=>` | Bind | `value <=> @name` — two-way binding between parent and child |
+| `@prop` | Prop | `@checked`, `@disabled` — component props (reactive) |
+| `$attr` | Data attr | `$open`, `$selected` — compiles to `data-open`, `data-selected` in HTML |
+| `@emit` | Event | `@emit 'change', value` — dispatches a CustomEvent |
+| `ref:` | DOM ref | `ref: "_panel"` — saves DOM element reference |
+| `slot` | Children | Projects parent-provided content into the component |
+| `offer` / `accept` | Context | Share reactive state between ancestor and descendant components |
 
-Reactive props via `:=` signal passthrough. Readonly props via `=!`.
-Children blocks passed as DOM nodes via `@children`.
-
-## Props — The `@` Contract
-
-The `@` prefix on a member declaration marks it as a **public prop** — settable
-by a parent component. Members without `@` are **private state** and ignore
-any value a parent tries to pass in.
+Two-way binding example — React vs Rip:
 
 ```coffee
-export Drawer = component
-  @open := false        # public — parent can pass `open: true`
-  @breakpoint := 480    # public — parent can pass `breakpoint: 768`
-  isRight := false      # private — always starts as false
-  closing := false      # private — always starts as false
+# React: 4 lines per binding
+const [show, setShow] = useState(false)
+<Dialog open={show} onOpenChange={setShow} />
+const [name, setName] = useState('')
+<input value={name} onChange={e => setName(e.target.value)} />
 
-  render
-    if open
-      div "Drawer is open"
+# Rip: 1 line per binding
+Dialog open <=> show
+input value <=> @name
 ```
 
-The compiler enforces the boundary:
+---
 
-```javascript
-// @open := false  →  accepts parent value
-this.open = __state(props.open ?? false);
+## Why Rip UI
 
-// isRight := false  →  ignores parent, always uses default
-this.isRight = __state(false);
-```
+| | ShadCN / Radix | Rip UI |
+|--|---------------|--------|
+| Runtime dependency | React (~42KB gz) + ReactDOM | None |
+| Component count | ~40 | 54 |
+| Total source | ShadCN wrappers (~3K LOC) atop Radix (~20K+ LOC) | 5,191 SLOC — everything included |
+| Build step | Required (Next.js, Vite, etc.) | None — browser compiles `.rip` source |
+| Styling | Pre-wired Tailwind (ShadCN) or unstyled (Radix) | Zero CSS — `data-*` contract, any methodology |
+| Controlled components | `value` + `onChange` callback pair | `<=>` two-way binding |
+| Shared state | React Context + Provider wrappers | `offer` / `accept` keywords |
+| Reactivity | `useState` + `useEffect` + dependency arrays | `:=` / `~=` / `~>` — language-level |
+| Virtual DOM | Yes (diffing on every render) | No — fine-grained updates to exact nodes |
+| Data grid | Not included | 901 SLOC — 100K+ rows at 60fps |
 
-This works for all member types:
+### Architecture
 
-| Declaration | Visibility | Meaning |
-|-------------|-----------|---------|
-| `@title := 'Hello'` | Public | Reactive state, settable by parent |
-| `@label =! 'Default'` | Public | Readonly prop, settable by parent |
-| `count := 0` | Private | Reactive state, internal only |
-| `cache =! null` | Private | Readonly, internal only |
-| `total ~= items.length` | — | Computed (always derived, never a prop) |
+**Fine-grained reactivity.** When `count` changes, only the text node
+displaying `count` updates. No tree diffing, no wasted renders, no
+memoization needed. Same model as SolidJS and Svelte 5's runes, but built
+into the language.
 
-A parent passes props as key-value pairs when using a component:
+**Components compile to JavaScript.** The `component` keyword, `render`
+block, and reactive operators resolve at compile time into ES2022 classes
+with direct DOM operations. Source maps point back to `.rip` source for
+debugging.
 
-```coffee
-Drawer open: showDrawer, breakpoint: 768
-  div "Content here"
-```
-
-The `@` declarations at the top of a component are its public API. Everything
-else is an implementation detail. No separate type files, no prop validation
-boilerplate — one character that says "this is settable from outside."
-
-## Render Block Syntax
+**No build pipeline.** The browser loads the Rip compiler (~50KB) once and
+compiles `.rip` files on the fly. For production, pre-compile. For
+development, save and see — SSE-based hot reload.
 
-Inside a `render` block, elements are declared by tag name. Classes, attributes,
-and children can be expressed inline or across multiple indented lines.
+**Source as distribution.** Components are served as `.rip` source files.
+Read them, understand them, modify them.
 
-### Classes with `.(...)`
+### Why We Build Our Own
 
-The `.()` helper applies classes using CLSX semantics — strings are included
-directly, and object keys are conditionally included based on their values:
+Radix and Base UI implement proven WAI-ARIA patterns, but they require
+React. Rip reimplements the same behavioral patterns using its own
+primitives:
 
-```coffee
-button.('px-4 py-2 rounded-full') "Click"
-button.('px-4 py-2', active: isActive) "Click"
-```
+| Capability | React | Rip |
+|-----------|-------|-----|
+| Child projection | No equivalent | `slot` |
+| DOM ownership | Virtual DOM abstraction | Direct DOM + `ref:` |
+| State sharing | Context + Provider wrappers | `offer` / `accept` |
+| Two-way binding | `value` + `onChange` pair | `<=>` operator |
+| Reactivity | Hooks + dependency arrays | `:=` / `~=` / `~>` |
 
-Arguments can span multiple lines, just like a normal function call:
+This lets Rip use the **right pattern for each widget**: single-component
+for data-driven widgets (Select, Combobox, Menu), compositional via
+`offer`/`accept` when children contain complex content the parent shouldn't
+own.
 
-```coffee
-input.(
-  'block w-full rounded-lg border border-primary',
-  'text-sm-plus text-tertiary shadow-xs'
-)
-```
+---
 
-### Indented Attributes
+## Styling
 
-Attributes can be placed on separate indented lines after the element:
+All widgets ship zero CSS. The contract between behavior and styling is
+`data-*` attributes:
 
 ```coffee
-input.('rounded-lg border px-3.5 py-2.5')
-  type: "email"
-  value: user.email
-  disabled: true
+# Widget exposes semantic state
+button $open: open?!, $disabled: @disabled?!
 ```
 
-This is equivalent to the inline form:
-
-```coffee
-input.('rounded-lg border px-3.5 py-2.5') type: "email", value: user.email, disabled: true
+```css
+/* You write the styles */
+[data-open]     { border-color: var(--color-primary); }
+[data-disabled] { opacity: 0.5; cursor: not-allowed; }
 ```
 
-### The `class:` Attribute
+Any CSS methodology works — vanilla CSS, Tailwind, Open Props, a custom
+design system. The widgets don't care.
 
-The `class:` attribute works like `.()` and merges cumulatively with any
-existing `.()` classes on the same element:
+For our recommended approach — design tokens, CSS architecture, dark mode,
+and the rationale behind it — see **[STYLING.md](STYLING.md)**.
 
-```coffee
-input.('block w-full rounded-lg')
-  class: 'text-sm text-tertiary'
-  type: "email"
-```
+---
 
-This produces a single combined class expression: `block w-full rounded-lg text-sm text-tertiary`.
+## Code Density
 
-The `class:` value also supports `.()` syntax for conditional classes:
+### Checkbox — 18 Lines
 
 ```coffee
-div.('mt-4 p-4')
-  class: .('ring-1', highlighted: isHighlighted)
-  span "Content"
-```
+export Checkbox = component
+  @checked := false
+  @disabled := false
+  @indeterminate := false
+  @switch := false
+
+  onClick: ->
+    return if @disabled
+    @indeterminate = false
+    @checked = not @checked
+    @emit 'change', @checked
 
-### Attributes and Children Together
-
-Attributes and children can coexist at the same indentation level. Attributes
-(key-value pairs) are listed first, followed by child elements:
-
-```coffee
-button.('flex items-center rounded-lg')
-  type: "submit"
-  disabled: saving
-
-  span.('font-bold') "Submit"
-  span.('text-sm text-secondary') "or press Enter"
+  render
+    button role: @switch ? 'switch' : 'checkbox'
+      aria-checked: @indeterminate ? 'mixed' : !!@checked
+      aria-disabled: @disabled?!
+      $checked: @checked?!
+      $indeterminate: @indeterminate?!
+      $disabled: @disabled?!
+      slot
 ```
 
-Blank lines between attributes and children are fine — they don't break the
-structure.
-
-## Two-Way Binding — The `<=>` Operator
+Full ARIA. Checkbox and switch modes. Indeterminate state. Data attributes
+for styling. 18 lines, complete.
 
-The `<=>` operator is one of Rip UI's most powerful features. It creates a
-bidirectional reactive binding between a parent's state and a child element
-or component — changes flow in both directions automatically.
+### Dialog — Effect-Based Lifecycle
 
-### The Problem It Solves
+Focus trap, scroll lock, escape dismiss, click-outside dismiss, focus
+restore — all in one reactive effect with automatic cleanup:
 
-In React, wiring state to interactive elements requires explicit value props
-and callback handlers for every bindable property:
-
-```jsx
-// React: verbose, repetitive ceremony
-const [name, setName] = useState('');
-const [role, setRole] = useState('viewer');
-const [notify, setNotify] = useState(true);
-const [showConfirm, setShowConfirm] = useState(false);
+```coffee
+~>
+  if @open
+    _prevFocus = document.activeElement
+    # lock scroll, trap focus, wire ARIA ...
+    return ->
+      # cleanup runs automatically when @open becomes false
+```
+
+No `useEffect`. No dependency array. No cleanup that captures stale state.
+
+### Grid — 901 Lines
+
+No equivalent in ShadCN, Radix, or Headless UI. Virtual scrolling, DOM
+recycling, Sheets-style selection, full keyboard nav, inline editing,
+multi-column sort, column resizing, clipboard (Ctrl+C/V/X as TSV — interop
+with Excel, Google Sheets, Numbers). 901 lines vs 50,000+ for AG Grid.
+
+---
+
+## Component Overview
+
+54 headless components across 10 categories — 5,191 lines total.
+
+### Selection
+
+| Widget | Description | Key Props | Events |
+|--------|-------------|-----------|--------|
+| **Select** | Dropdown with typeahead, ARIA listbox | `@value`, `@placeholder`, `@disabled` | `@change` |
+| **Combobox** | Filterable input + listbox | `@query`, `@placeholder`, `@disabled` | `@select`, `@filter` |
+| **MultiSelect** | Multi-select with chips and filtering | `@value`, `@query`, `@placeholder` | `@change` |
+| **Autocomplete** | Type to filter, select to fill | `@value`, `@query`, `@placeholder` | `@change` |
+
+### Toggle
+
+| Widget | Description | Key Props | Events |
+|--------|-------------|-----------|--------|
+| **Checkbox** | Toggle with checkbox/switch semantics | `@checked`, `@disabled`, `@switch` | `@change` |
+| **Toggle** | Two-state toggle button | `@pressed`, `@disabled` | `@change` |
+| **ToggleGroup** | Single or multi-select toggles | `@value`, `@multiple` | `@change` |
+| **RadioGroup** | Exactly one selected, arrow nav | `@value`, `@disabled` | `@change` |
+| **CheckboxGroup** | Multiple checked independently | `@value`, `@disabled` | `@change` |
+
+### Input
+
+| Widget | Description | Key Props | Events |
+|--------|-------------|-----------|--------|
+| **Input** | Focus, touch, and validation tracking | `@value`, `@type`, `@placeholder` | `@change` |
+| **Textarea** | Auto-resizing text area | `@value`, `@autoResize`, `@rows` | `@change` |
+| **NumberField** | Stepper buttons, hold-to-repeat | `@value`, `@min`, `@max`, `@step` | `@change` |
+| **Slider** | Drag with pointer capture + keyboard | `@value`, `@min`, `@max`, `@step` | `@change` |
+| **OTPField** | Multi-digit code, auto-advance + paste | `@value`, `@length` | `@complete` |
+| **DatePicker** | Calendar dropdown, single or range | `@value`, `@min`, `@max`, `@range` | `@change` |
+| **EditableValue** | Click-to-edit inline value | `@value`, `@placeholder` | `@change` |
+| **NativeSelect** | Styled native `<select>` wrapper | `@value`, `@disabled` | `@change` |
+| **InputGroup** | Input with prefix/suffix addons | `@disabled` | — |
+
+### Navigation
+
+| Widget | Description | Key Props | Events |
+|--------|-------------|-----------|--------|
+| **Tabs** | Arrow key nav, roving tabindex | `@active`, `@orientation` | `@change` |
+| **Menu** | Dropdown action menu | `@disabled` | `@select` |
+| **ContextMenu** | Right-click context menu | `@disabled` | `@select` |
+| **Menubar** | Horizontal menu bar with dropdowns | — | `@select` |
+| **NavMenu** | Site nav with hover/click panels | — | — |
+| **Toolbar** | Grouped controls, roving tabindex | `@orientation`, `@label` | — |
+| **Breadcrumb** | Navigation trail with separator | `@separator`, `@label` | — |
+
+### Overlay
+
+| Widget | Description | Key Props | Events |
+|--------|-------------|-----------|--------|
+| **Dialog** | Focus trap, scroll lock, ARIA modal | `@open` | `@close` |
+| **AlertDialog** | Non-dismissable modal | `@open`, `@initialFocus` | `@close` |
+| **Drawer** | Slide-out panel with focus trap | `@open`, `@side` | `@close` |
+| **Popover** | Anchored floating with flip/shift | `@placement`, `@offset` | — |
+| **Tooltip** | Hover/focus with delay | `@text`, `@placement`, `@delay` | — |
+| **PreviewCard** | Hover/focus preview card | `@delay`, `@placement` | — |
+| **Toast** | Auto-dismiss, ARIA live region | `@toast` (object) | `@dismiss` |
+
+### Display
+
+| Widget | Description | Key Props |
+|--------|-------------|-----------|
+| **Button** | Disabled-but-focusable pattern | `@disabled` |
+| **Badge** | Inline label (solid/outline/subtle) | `@variant` |
+| **Card** | Container with header/content/footer | `@interactive` |
+| **Separator** | Decorative or semantic divider | `@orientation`, `@decorative` |
+| **Progress** | Progress bar via CSS custom prop | `@value`, `@max` |
+| **Meter** | Gauge with thresholds | `@value`, `@min`, `@max`, `@low`, `@high` |
+| **Spinner** | Loading indicator | `@label`, `@size` |
+| **Skeleton** | Loading placeholder with shimmer | `@width`, `@height`, `@circle` |
+| **Avatar** | Image with fallback to initials | `@src`, `@alt`, `@fallback` |
+| **Label** | Accessible form label | `@for`, `@required` |
+| **ScrollArea** | Custom scrollbar, draggable thumb | `@orientation` |
+
+### Form
+
+| Widget | Description | Key Props |
+|--------|-------------|-----------|
+| **Field** | Label + description + error wrapper | `@label`, `@error`, `@required` |
+| **Fieldset** | Grouped fields with cascading disable | `@legend`, `@disabled` |
+| **Form** | Submit handling + validation state | `@onSubmit` |
+| **ButtonGroup** | Grouped buttons, ARIA semantics | `@orientation`, `@disabled` |
+
+### Data
+
+| Widget | Description | Key Props |
+|--------|-------------|-----------|
+| **Grid** | Virtual scroll, 100K+ rows at 60fps | `@data`, `@columns`, `@rowHeight` |
+| **Accordion** | Expand/collapse, single or multiple | `@multiple` |
+| **Table** | Semantic table wrapper | `@caption`, `@striped` |
+
+### Interactive
+
+| Widget | Description | Key Props | Events |
+|--------|-------------|-----------|--------|
+| **Collapsible** | Animated expand/collapse | `@open`, `@disabled` | `@change` |
+| **Pagination** | Page nav with ellipsis gaps | `@page`, `@total`, `@perPage` | `@change` |
+| **Carousel** | Slide with autoplay + loop | `@loop`, `@autoplay`, `@interval` | `@change` |
+| **Resizable** | Draggable resize handles | `@orientation`, `@minSize` | `@resize` |
+
+---
+
+## Widget Reference
+
+### Select
 
-<input value={name} onChange={e => setName(e.target.value)} />
-<Select value={role} onValueChange={setRole} />
-<Switch checked={notify} onCheckedChange={setNotify} />
-<Dialog open={showConfirm} onOpenChange={setShowConfirm} />
+```coffee
+Select value <=> selectedRole, @change: handleChange
+  option value: "eng", "Engineer"
+  option value: "des", "Designer"
+  option value: "mgr", "Manager"
 ```
 
-Every bindable property needs a state declaration AND a setter callback.
-This is the single most tedious pattern in React development.
-
-### The Rip Way
+**Keyboard:** ArrowDown/Up navigate, Enter/Space select, Escape close, Home/End, type-ahead
+**Data attributes:** `$open`, `$highlighted`, `$selected`, `$disabled`
 
-In Rip, `<=>` replaces all of that with a single operator:
+### Combobox
 
 ```coffee
-export UserForm = component
-  @name := ''
-  @role := 'viewer'
-  @notify := true
-  @showConfirm := false
-
-  render
-    input value <=> @name
-    Select value <=> @role
-      Option value: "viewer", "Viewer"
-      Option value: "editor", "Editor"
-      Option value: "admin",  "Admin"
-    Switch checked <=> @notify
-    Dialog open <=> @showConfirm
-      p "Save changes?"
+Combobox query <=> searchText, @select: handleSelect, @filter: handleFilter
+  for item in filteredItems
+    div $value: item.id
+      span item.name
 ```
 
-No `onChange`. No `onValueChange`. No `onOpenChange`. No `setName`, `setRole`,
-`setNotify`, `setShowConfirm`. The reactive system handles everything — state
-flows down, user interactions flow back up.
-
-### How It Works
-
-`value <=> username` compiles to two things:
-
-1. **State → DOM** (reactive effect): `__effect(() => { el.value = username; })`
-2. **DOM → State** (event listener): `el.addEventListener('input', (e) => { username = e.target.value; })`
-
-The compiler is smart about types:
-- `value <=>` on text inputs uses the `input` event and `e.target.value`
-- `value <=>` on number/range inputs uses `e.target.valueAsNumber`
-- `checked <=>` uses the `change` event and `e.target.checked`
-
-For custom components, `<=>` passes the reactive signal itself, enabling the
-child to both read and write the parent's state directly — no callback
-indirection.
+**Keyboard:** ArrowDown/Up navigate, Enter select, Escape close/clear, Tab close
+**Data attributes:** `$open`, `$highlighted`
 
-### Auto-Detection
-
-Even without `<=>`, the compiler auto-detects when `value:` or `checked:` is
-bound to a reactive expression and generates two-way binding automatically:
+### Dialog
 
 ```coffee
-# These are equivalent:
-input value <=> @name           # explicit two-way binding
-input value: @name              # auto-detected (name is reactive)
+Dialog open <=> showDialog, @close: handleClose
+  h2 "Confirm Action"
+  p "Are you sure?"
+  button @click: (=> showDialog = false), "Cancel"
+  button @click: handleConfirm, "Confirm"
 ```
 
-### Why This Matters
-
-Two-way binding is what Vue has with `v-model`, what Svelte has with `bind:`,
-and what Angular has with `[(ngModel)]`. React is the only major framework
-that deliberately omits it, forcing the verbose controlled component pattern
-instead.
-
-Rip's `<=>` goes further than Vue or Svelte — it works uniformly across HTML
-elements and custom components with the same syntax. A `Dialog open <=> show`
-and an `input value <=> name` use the same operator, the same mental model,
-and the same compilation strategy. This makes headless interactive components
-dramatically cleaner to use than their React equivalents.
-
-## How It Works
-
-The browser loads one file — `rip-ui.min.js` (~53KB Brotli) — which bundles the
-Rip compiler and the pre-compiled UI framework. No runtime compilation of the
-framework, no extra network requests.
-
-The runtime auto-detects `<script type="text/rip" data-name="...">` components
-on the page and calls `launch()` automatically with hash routing enabled by
-default. For server-rendered apps, `launch()` fetches the app bundle from the
-server. Either way, it hydrates the stash and renders.
+**Keyboard:** Escape to close, Tab trapped within dialog
+**Data attributes:** `$open`
+**Behavior:** Focus trap, body scroll lock, focus restore on close
 
-### Browser Execution Contexts
+### AlertDialog
 
-Rip provides full async/await support across every browser context — no other
-compile-to-JS language has this:
-
-| Context | How async works | Returns value? |
-|---------|-----------------|----------------|
-| `<script type="text/rip">` | Async IIFE wrapper | No (fire-and-forget) |
-| Playground "Run" button | Async IIFE wrapper | No (use console.log) |
-| `rip()` console REPL | Rip `do ->` block | Yes (sync direct, async via Promise) |
-| `.rip` files via `importRip()` | ES module import | Yes (module exports) |
-
-The `!` postfix compiles to `await`. Inline scripts are wrapped in an async IIFE
-automatically. The `rip()` console function wraps user code in a `do ->` block
-so the Rip compiler handles implicit return and auto-async natively.
-
-### globalThis Exports
-
-When `rip-ui.min.js` loads, it registers these on `globalThis`:
-
-| Function | Purpose |
-|----------|---------|
-| `rip(code)` | Console REPL — compile and execute Rip code |
-| `importRip(url)` | Fetch, compile, and import a `.rip` file as an ES module |
-| `compileToJS(code)` | Compile Rip source to JavaScript |
-| `__rip` | Reactive runtime — `__state`, `__computed`, `__effect`, `__batch` |
-| `__ripComponent` | Component runtime — `__Component`, `__clsx`, `__fragment` |
-| `__ripExports` | All compiler exports — `compile`, `formatSExpr`, `VERSION`, etc. |
-
-## The Stash
-
-App state lives in one reactive tree:
-
-```
-app
-├── routes    ← navigation state (path, params, query, hash)
-└── data      ← reactive app state (title, theme, user, etc.)
-```
-
-Writing to `app.data.theme` updates any component reading it. The stash
-uses Rip's built-in reactive primitives — the same signals that power
-`:=` and `~=` in components.
-
-## The App Bundle
-
-The bundle is JSON served at `/{app}/bundle`:
-
-```json
-{
-  "components": {
-    "components/index.rip": "export Home = component...",
-    "components/counter.rip": "export Counter = component...",
-    "components/_lib/card.rip": "export Card = component..."
-  },
-  "data": {
-    "title": "My App",
-    "theme": "light"
-  }
-}
+```coffee
+AlertDialog open <=> showConfirm
+  h2 "Delete account?"
+  p "This action cannot be undone."
+  button @click: (=> showConfirm = false), "Cancel"
+  button @click: handleDelete, "Delete"
 ```
 
-On disk you organize your app into `pages/` and `ui/`. The middleware
-maps them into a flat `components/` namespace in the bundle — pages go
-under `components/`, shared components under `components/_lib/`. The `_`
-prefix tells the router to skip `_lib/` entries when generating routes.
-
-## Component Loading Modes
+Like Dialog but cannot be closed by Escape or click outside.
+**ARIA:** `role="alertdialog"`, auto-wired `aria-labelledby`/`aria-describedby`
 
-`launch()` supports three ways to load component sources, checked in priority
-order. All three produce the same internal bundle format — everything downstream
-(compilation, routing, rendering) works identically regardless of source.
-
-### 1. Static File URLs — `launch components: [...]`
-
-Fetch individual `.rip` files as plain text from any static server:
+### Toast
 
 ```coffee
-launch components: [
-  'components/index.rip'
-  'components/dashboard.rip'
-  'components/line-chart.rip'
-]
+toasts := []
+toasts = [...toasts, { message: "Saved!", type: "success" }]
+toasts = toasts.filter (t) -> t isnt target
+ToastViewport toasts <=> toasts
 ```
 
-No server middleware needed. Serve `.rip` files as static text from any HTTP
-server, CDN, or `file://` path. Each URL is fetched individually and compiled
-in the browser.
-
-### 2. Inline DOM — `<script type="text/rip" data-name="...">`
+**Props:** `@toasts`, `@placement` (bottom-right, top-right, etc.)
+**Per-toast:** `message`, `type`, `duration` (default 4000ms), `title`, `action`
+**Data attributes:** `$type`, `$leaving`
+**Behavior:** Timer pauses on hover, resumes on leave
 
-Embed component source directly in the HTML page:
+### Tabs
 
-```html
-<script type="module" src="rip-ui.min.js"></script>
-
-<script type="text/rip" data-name="index">
-  export Home = component
-    render
-      h1 "Hello from inline"
-</script>
-
-<script type="text/rip" data-name="counter">
-  export Counter = component
-    @count := 0
-    render
-      button @click: (-> count += 1), "#{count}"
-</script>
+```coffee
+Tabs active <=> currentTab
+  div $tab: "one", "Tab One"
+  div $tab: "two", "Tab Two"
+  div $panel: "one"
+    p "Content for tab one"
+  div $panel: "two"
+    p "Content for tab two"
 ```
 
-The runtime auto-detects `data-name` scripts and launches automatically — no
-bootstrap script needed. The `data-name` attribute maps to the component
-filename (`.rip` extension is added automatically if omitted). Scripts with
-`data-name` are collected as component sources and are not executed as
-top-level code.
+**Keyboard:** ArrowLeft/Right navigate, Home/End jump
+**Data attributes:** `$active`
 
-### 3. Server Bundle (default)
-
-When neither `components` nor inline `data-name` scripts are present, `launch()`
-fetches the app bundle from the server at `/{app}/bundle`. This is the default
-mode when using the `ripUI` server middleware.
+### Accordion
 
 ```coffee
-launch()  # fetches /bundle automatically
+Accordion multiple: false
+  div $item: "a"
+    button $trigger: true, "Section A"
+    div $content: true
+      p "Content A"
 ```
 
-## Server Middleware
+**Keyboard:** Enter/Space toggle, ArrowDown/Up between triggers, Home/End
+**Methods:** `toggle(id)`, `isOpen(id)`
 
-The `ripUI` middleware registers routes for the framework files, the app
-bundle, and optional SSE hot-reload:
+### Checkbox
 
 ```coffee
-use ripUI dir: dir, components: 'routes', includes: ['ui'], watch: true, title: 'My App'
-```
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `app` | `''` | URL mount point |
-| `dir` | `'.'` | App directory on disk |
-| `components` | `'components'` | Directory for page components (file-based routing) |
-| `includes` | `[]` | Directories for shared components (no routes) |
-| `watch` | `false` | Enable SSE hot-reload |
-| `debounce` | `250` | Milliseconds to batch file change events |
-| `state` | `null` | Initial app state |
-| `title` | `null` | Document title |
+Checkbox checked <=> isActive, @change: handleChange
+  span "Enable notifications"
 
-Routes registered:
-
-```
-/rip/rip-ui.min.js   — Rip compiler + pre-compiled UI framework
-/{app}/bundle        — app bundle (components + data as JSON)
-/{app}/watch         — SSE hot-reload stream (when watch: true)
-/{app}/components/*  — individual component files (for hot-reload refetch)
+Checkbox checked <=> isDark, switch: true
+  span "Dark mode"
 ```
 
-## State Preservation (Keep-Alive)
-
-Components are cached when navigating away instead of destroyed. Navigate
-to `/counter`, increment the count, go to `/about`, come back — the count
-is preserved. Configurable via `cacheSize` (default 10).
+**ARIA:** `role="checkbox"` or `role="switch"`, `aria-checked` (true/false/mixed)
+**Data attributes:** `$checked`, `$indeterminate`, `$disabled`
 
-## Data Loading
-
-`createResource` manages async data with reactive `loading`, `error`, and
-`data` properties:
+### Menu
 
 ```coffee
-export UserPage = component
-  user := createResource -> fetch!("/api/users/#{@params.id}").json!
-
-  render
-    if user.loading
-      p "Loading..."
-    else if user.error
-      p "Error: #{user.error.message}"
-    else
-      h1 user.data.name
+Menu @select: handleAction
+  button $trigger: true, "Actions"
+  div $item: "edit", "Edit"
+  div $item: "delete", "Delete"
 ```
 
-## Error Boundaries
+**Keyboard:** ArrowDown/Up navigate, Enter/Space select, Escape close
+**Data attributes:** `$open`, `$highlighted`
 
-Layouts with an `onError` method catch errors from child components:
+### Popover
 
 ```coffee
-export Layout = component
-  errorMsg := null
-
-  onError: (err) -> errorMsg = err.message
-
-  render
-    .app-layout
-      if errorMsg
-        .error-banner "#{errorMsg}"
-      #content
+Popover placement: "bottom-start"
+  button "Options"
+  div
+    p "Popover content here"
 ```
 
-## Navigation Indicator
+**Keyboard:** Enter/Space/ArrowDown toggle, Escape close
+**Data attributes:** `$open`, `$placement`
 
-`router.navigating` is a reactive signal — true while a route transition
-is in progress:
+### Tooltip
 
 ```coffee
-if @router.navigating
-  span "Loading..."
+Tooltip text: "Save your changes", placement: "top"
+  button "Save"
 ```
 
-## Multi-App Hosting
+**Data attributes:** `$open`, `$entering`, `$exiting`, `$placement`
+**Behavior:** Shows after delay on hover/focus, uses `aria-describedby`
 
-Mount multiple apps under one server:
+### Grid
 
 ```coffee
-import { get, start, notFound } from '@rip-lang/api'
-import { mount as demo } from './demo/index.rip'
-import { mount as labs } from './labs/index.rip'
-
-demo '/demo'
-labs '/labs'
-get '/', -> Response.redirect('/demo/', 302)
-start port: 3002
+Grid
+  data: employees
+  columns: [
+    { key: 'name',   title: 'Name',   width: 200 }
+    { key: 'age',    title: 'Age',    width: 80,  align: 'right' }
+    { key: 'role',   title: 'Role',   width: 150, type: 'select', source: roles }
+    { key: 'active', title: 'Active', width: 60,  type: 'checkbox' }
+  ]
+  rowHeight: 32
+  striped: true
 ```
 
-The `/rip/` namespace is shared — all apps use the same compiler and framework.
+**Column types:** `text`, `number`, `checkbox`, `select`
+**Methods:** `getCell`, `setCell`, `getData`, `setData`, `sort`, `scrollToRow`, `copySelection`, `cutSelection`, `pasteAtActive`
+**Keyboard:** Arrows, Tab, Enter/F2 edit, Escape cancel, Ctrl+arrows jump, PageUp/Down, Ctrl+A, Ctrl+C/V/X, Delete, Space (checkboxes), type-to-edit
+**Sorting:** Click header (asc/desc/none), Shift+click for multi-column
+**Clipboard:** TSV format — interop with Excel, Sheets, Numbers
+**Data attributes:** `$active`, `$selected`, `$sorted`, `$editing`, `$selecting`
 
-## File Structure
+### Collapsible
 
-```
-my-app/
-├── index.rip            # Server
-├── index.html           # HTML page
-├── pages/               # Page components (file-based routing)
-│   ├── _layout.rip      # Root layout
-│   ├── index.rip        # Home          → /
-│   ├── about.rip        # About         → /about
-│   └── users/
-│       └── [id].rip     # User profile  → /users/:id
-├── ui/                  # Shared components (no routes)
-│   └── card.rip         # Card          → available as Card
-└── css/
-    └── styles.css       # Styles
+```coffee
+Collapsible open <=> isOpen
+  button $trigger: true, "Show details"
+  div $content: true
+    p "Hidden content here"
 ```
 
-Files starting with `_` don't generate routes (`_layout.rip` is a layout,
-not a page). Directories starting with `_` are also excluded, which is how
-shared components from `includes` stay out of the router.
+**Methods:** `toggle()`
+**Data attributes:** `$open`, `$disabled`
+**CSS custom properties:** `--collapsible-height`, `--collapsible-width`
 
-## Hash Routing
+### Pagination
 
-Hash routing is **enabled by default** for auto-launched apps — ideal for
-static hosting (GitHub Pages, S3, etc.) where the server can't handle SPA
-fallback routing. URLs use `page.html#/about` instead of `/about`.
-Back/forward navigation, direct URL loading, and `href="#/path"` links all
-work correctly.
-
-To disable hash routing (e.g., for server-rendered apps with proper fallback):
-
-```html
-<script type="module" src="rip-ui.min.js" data-hash="false"></script>
+```coffee
+Pagination page <=> currentPage, total: 100, perPage: 10
 ```
 
-Or when calling `launch()` manually:
+**Keyboard:** ArrowLeft/Right, Home/End
+**Data attributes:** `$active`, `$disabled`, `$ellipsis`
+
+### Carousel
 
 ```coffee
-launch hash: false
+Carousel loop: true
+  div $slide: true, "Slide 1"
+  div $slide: true, "Slide 2"
+  div $slide: true, "Slide 3"
 ```
 
-## Static Deployment
+**Methods:** `goto(index)`, `next()`, `prev()`
+**Behavior:** Autoplay pauses on hover
 
-For zero-server deployment, use inline `data-name` scripts or a `components`
-URL list. Both work with `rip-ui.min.js` (~53KB Brotli) from a CDN — no
-server middleware needed, no bootstrap script needed.
+### Drawer
 
-**Inline mode** — everything in one HTML file:
+```coffee
+Drawer open <=> showDrawer, side: "left"
+  nav "Sidebar content"
+```
 
-```html
-<script type="module" src="rip-ui.min.js"></script>
+**Props:** `@open`, `@side` (top/right/bottom/left), `@dismissable`
+**Behavior:** Focus trap, scroll lock, Escape to close
 
-<script type="text/rip" data-name="index">
-  export Home = component
-    render
-      h1 "Hello"
-</script>
+### Breadcrumb
 
-<script type="text/rip" data-name="about">
-  export About = component
-    render
-      h1 "About"
-</script>
+```coffee
+Breadcrumb
+  a $item: true, href: "/", "Home"
+  a $item: true, href: "/products", "Products"
+  span $item: true, "Widget Pro"
 ```
 
-The runtime auto-detects the `data-name` components and launches with hash
-routing. That's it — no bootstrap, no config.
+**ARIA:** `aria-current="page"` on last item
 
-**Remote bundle** — fetch components from a URL:
+### Resizable
 
-```html
-<script type="module" src="rip-ui.min.js" data-url="https://example.com/app/"></script>
+```coffee
+Resizable
+  div $panel: true, "Left"
+  div $panel: true, "Right"
 ```
 
-The `data-url` attribute tells the runtime to fetch the app bundle from the
-given URL (appending `/bundle` to the path).
+**ARIA:** `role="separator"` on handles
+**CSS custom properties:** `--panel-size` on each panel
 
-**Manual launch** — for full control, use a bare `<script type="text/rip">`:
+### Context Sharing: `offer` / `accept`
 
-```html
-<script type="module" src="rip-ui.min.js"></script>
-<script type="text/rip">
-  { launch } = importRip! 'ui.rip'
-  launch components: ['components/index.rip', 'components/about.rip']
-</script>
-```
+For compound components where descendants need shared state:
 
-**Inline Rip** — run arbitrary Rip code alongside auto-launched apps:
+```coffee
+# Parent offers reactive state to all descendants
+export Tabs = component
+  offer active := 'overview'
 
-```html
-<script type="text/rip">
-  alert "Free cheese rollups for the girls!"
-</script>
+# Child accepts the shared signal
+export TabContent = component
+  accept active
+  render
+    div hidden: active isnt @value
+      slot
 ```
 
-See `docs/results/index.html` for a complete example — a full Lab Results
-brochure app with 7 components, SVG gauges, and inline CSS in one HTML file.
+Parent and child share the same reactive object — mutations in either
+direction are instantly visible. No Provider wrappers, no string keys.
 
-## Tailwind CSS Autocompletion
+---
 
-To get Tailwind class autocompletion inside `.()` CLSX helpers in render
-templates, install the
-[Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss)
-extension and add these to your VS Code / Cursor settings:
+## File Summary
 
-```json
-{
-  "tailwindCSS.includeLanguages": { "rip": "html" },
-  "tailwindCSS.experimental.classRegex": [
-    ["\\.\\(([\\s\\S]*?)\\)", "'([^']*)'"]
-  ]
-}
-```
+| Category | Files | Lines |
+|----------|-------|-------|
+| Selection | 4 | 638 |
+| Toggle | 5 | 267 |
+| Input | 9 | 854 |
+| Navigation | 7 | 767 |
+| Overlay | 7 | 700 |
+| Display | 11 | 378 |
+| Form | 4 | 140 |
+| Data | 3 | 1,041 |
+| Interactive | 4 | 406 |
+| **Total** | **54** | **5,191** |
 
-This gives you autocompletion, hover previews, and linting for Tailwind
-classes in expressions like:
+---
 
-```coffee
-h1.('text-3xl font-semibold') "Hello"
-button.('flex items-center px-4 py-2 rounded-full') "Click"
-```
+## Status
 
-## License
+The reactive model, headless contract, and performance architecture are
+proven. The compiler has 1,436 tests. The widget suite is comprehensive
+but still maturing — tests are being added, and a few widgets have known
+structural issues being resolved (see [CONTRIBUTING.md](CONTRIBUTING.md)
+for details).
 
-MIT
+For widget authoring patterns, implementation notes, known issues, and the
+development roadmap, see **[CONTRIBUTING.md](CONTRIBUTING.md)**.