usage-rules.md

Courgette Usage Rules

Courgette is a declarative TUI framework for Elixir built on OTP. Zero runtime dependencies.

Pipeline: Component render/1 → Element Tree → Layout (Flexbox) → Paint (Buffer) → Diff → ANSI → Terminal

Core Conventions

• Root apps use use Courgette.App; children use use Courgette.LiveComponent
• Assigns are maps internally. Public APIs accept keyword lists.
• DSL macros (box, text, input, etc.) build pure-data element trees
• live_component(Module, id: "unique") — the :id is required
• Events are tuples: {:key, {:char, "a"}}, {:key, :enter}, {:key, {:ctrl, "c"}}
• Focus: set focusable: true on live_component; Tab/Shift-Tab cycles focus
• Children notify parents via send(assigns.parent_pid, {tag, value})

Sub-rules

• App & Lifecycle — run/stop, callbacks, return shapes
• Components — LiveComponent vs Component, reconciliation
• DSL & Layout — element macros, flexbox props, styling
• Events & Focus — event tuples, focus routing
• Built-in Components — TextInput, Select, Spinner, etc.
• Animation — Tween, Frames, Easing, timer patterns
• Testing — ComponentTestHelpers, headless testing