@rip-lang/ui 0.3.13 → 0.3.15

package/README.md

@@ -45,6 +45,73 @@ export Home = component
 
 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
@@ -203,6 +270,99 @@ button.('flex items-center rounded-lg')
 Blank lines between attributes and children are fine — they don't break the
 structure.
 
+## Two-Way Binding — The `<=>` Operator
+
+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.
+
+### The Problem It Solves
+
+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);
+
+<input value={name} onChange={e => setName(e.target.value)} />
+<Select value={role} onValueChange={setRole} />
+<Switch checked={notify} onCheckedChange={setNotify} />
+<Dialog open={showConfirm} onOpenChange={setShowConfirm} />
+```
+
+Every bindable property needs a state declaration AND a setter callback.
+This is the single most tedious pattern in React development.
+
+### The Rip Way
+
+In Rip, `<=>` replaces all of that with a single operator:
+
+```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?"
+```
+
+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.
+
+### Auto-Detection
+
+Even without `<=>`, the compiler auto-detects when `value:` or `checked:` is
+bound to a reactive expression and generates two-way binding automatically:
+
+```coffee
+# These are equivalent:
+input value <=> @name           # explicit two-way binding
+input value: @name              # auto-detected (name is reactive)
+```
+
+### 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` (~52KB Brotli) — which bundles the