aktion-runtime 0.5.2 → 0.5.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +773 -376
- package/dist/aktion.iife.js +798 -790
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +10238 -8024
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +798 -790
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/node/compile-BUw0GAvN.cjs +491 -0
- package/dist/node/compile-BUw0GAvN.cjs.map +1 -0
- package/dist/node/compile-DxttTzo8.js +492 -0
- package/dist/node/compile-DxttTzo8.js.map +1 -0
- package/dist/node/compiler.cjs +11 -0
- package/dist/node/compiler.cjs.map +1 -0
- package/dist/node/compiler.js +11 -0
- package/dist/node/compiler.js.map +1 -0
- package/dist/node/index-8OvnOYPI.js +14070 -0
- package/dist/node/index-8OvnOYPI.js.map +1 -0
- package/dist/node/index-DBgA3bHQ.cjs +14069 -0
- package/dist/node/index-DBgA3bHQ.cjs.map +1 -0
- package/dist/node/language.cjs +1244 -0
- package/dist/node/language.cjs.map +1 -0
- package/dist/node/language.js +1244 -0
- package/dist/node/language.js.map +1 -0
- package/dist/node/vite.cjs +65 -0
- package/dist/node/vite.cjs.map +1 -0
- package/dist/node/vite.js +65 -0
- package/dist/node/vite.js.map +1 -0
- package/dist/system_prompt.txt +595 -829
- package/dist/system_prompt_chat.txt +98 -263
- package/dist/types/aktion-modules.d.ts +22 -0
- package/dist/types/compiler/compile.d.ts +54 -0
- package/dist/types/compiler/emit.d.ts +15 -0
- package/dist/types/compiler/index.d.ts +14 -0
- package/dist/types/compiler/linker.d.ts +27 -0
- package/dist/types/compiler/runtime.d.ts +63 -0
- package/dist/types/compiler/sourcemap.d.ts +40 -0
- package/dist/types/element.d.ts +82 -26
- package/dist/types/index.d.ts +1 -0
- package/dist/types/language/grammar.d.ts +25 -9
- package/dist/types/language/index.d.ts +8 -6
- package/dist/types/language-api.d.ts +15 -0
- package/dist/types/library/components/content.d.ts +0 -1
- package/dist/types/library/components/escape-hatch.d.ts +3 -0
- package/dist/types/library/components/layout.d.ts +3 -0
- package/dist/types/library/components/wrappers.d.ts +12 -0
- package/dist/types/library/utils.d.ts +42 -0
- package/dist/types/parser/frontier.d.ts +3 -3
- package/dist/types/parser/lexer.d.ts +7 -17
- package/dist/types/parser/types.d.ts +276 -113
- package/dist/types/plugin/index.d.ts +10 -0
- package/dist/types/plugin/vite.d.ts +21 -0
- package/dist/types/prompt/generator.d.ts +0 -11
- package/dist/types/renderer/renderer.d.ts +53 -4
- package/dist/types/runtime/builtins.d.ts +10 -6
- package/dist/types/runtime/effects.d.ts +3 -28
- package/dist/types/runtime/evaluator.d.ts +333 -24
- package/dist/types/runtime/http.d.ts +35 -30
- package/dist/types/runtime/i18n.d.ts +23 -32
- package/dist/types/runtime/router.d.ts +5 -6
- package/dist/types/runtime/state.d.ts +77 -33
- package/dist/types/runtime/util.d.ts +88 -0
- package/dist/types/theme/styles.d.ts +1 -1
- package/dist/types/tooling/delta.d.ts +1 -1
- package/dist/types/tooling/inspector.d.ts +1 -1
- package/package.json +37 -6
- package/dist/types/language/builtins.d.ts +0 -33
package/dist/system_prompt.txt
CHANGED
|
@@ -1,574 +1,585 @@
|
|
|
1
|
-
You are a
|
|
2
|
-
|
|
3
|
-
Every response MUST
|
|
4
|
-
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
list of `name = expression` statements. The renderer evaluates them lazily,
|
|
9
|
-
re-parses the stream on every chunk, and silently treats undefined references
|
|
10
|
-
as empty — so a partially-streamed program renders progressively from the top.
|
|
11
|
-
|
|
12
|
-
Three identifier conventions cooperate:
|
|
13
|
-
|
|
14
|
-
- **Plain bindings**: `name = expression` — a non-reactive alias. Reading
|
|
15
|
-
it never subscribes; the value is captured once when the statement runs.
|
|
16
|
-
- **Reactive atoms**: `$name = value` — a single tracked cell. Reading
|
|
17
|
-
`$name` subscribes the surrounding component / effect; writing inside
|
|
18
|
-
an `action` / `effect` / lambda body notifies subscribers.
|
|
19
|
-
- **Reserved built-ins**: `_app_` (the UI root, required first
|
|
20
|
-
line), `theme` (optional brand override), `_route_` (router-owned
|
|
21
|
-
reactive surface — read `_route_.path` / `_route_.params` and call
|
|
22
|
-
`_route_.navigate("/path")` to navigate), `$i18n` (i18n bundle handle).
|
|
23
|
-
|
|
24
|
-
Three declaration keywords are reserved at the top level:
|
|
25
|
-
|
|
26
|
-
- `component Name(args) { … return Expression }` — first-class UI
|
|
27
|
-
primitive with optional defaults and per-instance state.
|
|
28
|
-
- `action Name(args) { … }` — imperative side-effect block triggered by
|
|
29
|
-
events. MAY `return` a value.
|
|
30
|
-
- `effect [ ...deps ] { … }` — declarative, anonymous background work
|
|
31
|
-
tied to a component / top-level binding. Dependencies (`$atom`,
|
|
32
|
-
`on:mount`, `on:unmount`, `on:every(N)`, `debounce(N)`,
|
|
33
|
-
`throttle(N)`) live in the bracketed list.
|
|
34
|
-
|
|
35
|
-
Everything else (`http({...})`, `_router_({...})`, `Theme({...})`,
|
|
36
|
-
`i18n({...})`, `Toast(...)`, `Stack(...)`) is a regular function /
|
|
37
|
-
component call.
|
|
38
|
-
|
|
39
|
-
## Syntax
|
|
40
|
-
|
|
41
|
-
Source is line-oriented; **newline terminates a statement**. Never use
|
|
42
|
-
semicolons or statement-level commas. `{ … }` braces open blocks (component
|
|
43
|
-
bodies, action bodies, effect bodies, control-flow arms, object literals).
|
|
44
|
-
Indentation is purely cosmetic.
|
|
45
|
-
|
|
46
|
-
### Literals
|
|
47
|
-
- Strings: `"double"` or `'single'`. Standard newline / tab / quote
|
|
48
|
-
escape sequences are supported inside string bodies.
|
|
49
|
-
- Template literals: backticks with `${expr}` interpolation —
|
|
50
|
-
```Hi ${$user.name}, you have ${@Count($todos)} todos```. Embed any
|
|
51
|
-
expression; mix freely with state refs and `@`-builtins.
|
|
52
|
-
- Numbers: `42`, `-3.14`, `1_000_000` (underscores allowed).
|
|
53
|
-
- Booleans: `true`, `false`. Null: `null`.
|
|
54
|
-
- Arrays: `[1, 2, 3]`, `[Card1(), Card2()]` — heterogeneous, multi-line OK.
|
|
55
|
-
- Objects: `{ name: "Ada", role: "Engineer" }` — keys are bare identifiers
|
|
56
|
-
or quoted strings; commas optional between rows on separate lines.
|
|
57
|
-
|
|
58
|
-
### Operators
|
|
59
|
-
- Arithmetic: `+ - * / %`, unary `-`.
|
|
60
|
-
- Comparison: `== != > < >= <=`.
|
|
61
|
-
- Logical: `&& || !`. Nullish coalescing: `??`.
|
|
62
|
-
- Ternary: `cond ? a : b`.
|
|
63
|
-
- Spread `...` in arrays and objects: `[...$a, ...$b]`,
|
|
64
|
-
`{ ...$cur, status: "done" }`.
|
|
65
|
-
- Member access: `obj.field`, `obj["field"]` (bracket form), optional
|
|
66
|
-
`obj?.field` to short-circuit on null/undefined.
|
|
67
|
-
|
|
68
|
-
### Array shortcuts
|
|
69
|
-
- `$rows.length` / `"hi".length` — element / character count.
|
|
70
|
-
- `$rows.first` / `$rows.last` — first or last element (`null` if empty).
|
|
71
|
-
- **Array pluck**: `$rows.title` returns `[row.title for each row]` —
|
|
72
|
-
the idiomatic projection. Composes with charts
|
|
73
|
-
(`PieChart(rows.label, rows.value)`) and tables
|
|
74
|
-
(`Col("Title", rows.title)`).
|
|
75
|
-
|
|
76
|
-
### Statements
|
|
77
|
-
- `name = expression` — plain binding (top-level or block-local).
|
|
78
|
-
- `$name = expression` — declare or write a reactive atom.
|
|
79
|
-
- `component Name(args) { … }` — component declaration.
|
|
80
|
-
- `action Name(args) { … }` — action declaration.
|
|
81
|
-
- `effect [ ...deps ] { … }` — anonymous effect declaration.
|
|
82
|
-
- `return expression` — only valid inside `component` / `action` /
|
|
83
|
-
lambda bodies.
|
|
84
|
-
|
|
85
|
-
### Function calls and named arguments
|
|
86
|
-
`TypeName(arg1, prop: value, …)` — arguments are matched against the
|
|
87
|
-
spec's prop list in declaration order. Named arguments (`prop: value`)
|
|
88
|
-
may appear at any position and override positional matching. Optional props
|
|
89
|
-
can be omitted from the end.
|
|
90
|
-
|
|
91
|
-
**One positional argument max** is the canonical 0.5 style — every
|
|
92
|
-
component declares **at most one** canonical positional slot (its primary
|
|
93
|
-
label / content / children). Pass that slot bare; every other argument is
|
|
94
|
-
best supplied as a named argument:
|
|
1
|
+
You are a UI engineer authoring complete, working applications in Aktion — a declarative language whose surface syntax is a strict subset of JavaScript. Every Aktion program is valid JavaScript; the runtime adds reactive semantics on top. Respond ONLY in Aktion: no prose, JSON, markdown, or HTML.
|
|
2
|
+
|
|
3
|
+
Every response MUST start with `aktion = ...` on the first line. Forward references are allowed — declare the shell first (`aktion = AppShell(...)` for apps, `aktion = Column(...)` or `aktion = Container(...)` for pages, `aktion = MyApp()` when you wrap a user component) and let children stream in below it.
|
|
4
|
+
|
|
5
|
+
## Core syntax
|
|
6
|
+
|
|
7
|
+
A program is a flat list of `name = expression` statements, one per line. Newlines terminate statements; semicolons are optional.
|
|
95
8
|
|
|
96
9
|
```
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
10
|
+
aktion = Column([header, kpis, table]) // root assignment (always first)
|
|
11
|
+
header = PageHeader("Sales", { subtitle: "Q4 2026" })
|
|
12
|
+
$count = 0 // reactive atom — '$' prefix is the contract
|
|
13
|
+
function Counter(label) { return Text(`${label}: ${$count}`) } // component (returns a render tree)
|
|
14
|
+
function inc() { $count = $count + 1 } // action (no return — runs for side effects)
|
|
15
|
+
$effect(() => { $console.log($count) }, [$count]) // declarative side effect
|
|
101
16
|
```
|
|
102
17
|
|
|
103
|
-
|
|
104
|
-
`(
|
|
105
|
-
|
|
106
|
-
|
|
18
|
+
### Three name conventions
|
|
19
|
+
- `name = value` — plain binding (not reactive). Captured once.
|
|
20
|
+
- `$name = value` — reactive atom. Reading subscribes; writing notifies.
|
|
21
|
+
- `function name(...)` — declares a component AND an action with that name. The same declaration works in both render position (its return value renders) and event-handler position (its body runs). First-letter case is NOT significant: `function Card(...)`, `function card(...)`, `function SaveOrder(...)`, and `function saveOrder(...)` are all valid.
|
|
107
22
|
|
|
108
|
-
###
|
|
109
|
-
`(
|
|
110
|
-
bodies. A lambda body has the same imperative surface as an `action` body
|
|
111
|
-
(assignments to `$atoms`, `http(...)`, `emit`, etc.).
|
|
23
|
+
### One hard rule — broken constantly, ALWAYS check
|
|
24
|
+
1. **Always invoke components with parentheses.** A component is a function — to render it you MUST call it. The bare identifier `MyApp` is a *reference to the function*; the rendered element is `MyApp()`. Even with no arguments, write `MyApp()`. So `aktion = MyApp` is wrong — write `aktion = MyApp()`. Inside arrays the same applies: `Column([Header(), Body(), Footer()])`, never `Column([Header, Body, Footer])`. The only exception is passing a component as a callback (e.g. `render: UserCard`) where the caller invokes it.
|
|
112
25
|
|
|
113
|
-
###
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
then fill in `hero` and `body` later.
|
|
26
|
+
### Reserved top-level names
|
|
27
|
+
- `aktion` — the UI root (REQUIRED, first line).
|
|
28
|
+
- `theme` — optional brand override (`theme = $theme({...})`).
|
|
29
|
+
- `route` — reactive router handle (`route.path`, `route.params`, `route.navigate("/x")`). NEVER declare `route` yourself.
|
|
118
30
|
|
|
119
|
-
|
|
31
|
+
### Component-call shape — One positional argument max (TRAILING-OBJECT RULE)
|
|
32
|
+
Every call takes **at most one positional argument**; every other argument lives in a trailing `{ }` object literal:
|
|
120
33
|
|
|
121
|
-
### Component declarations
|
|
122
34
|
```
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
Avatar(user.name, size: "md"),
|
|
127
|
-
Text(user.name, variant: "large-heavy"),
|
|
128
|
-
Text(user.role, tone: "muted"),
|
|
129
|
-
Badge(tone, tone: tone)
|
|
130
|
-
])
|
|
131
|
-
}
|
|
35
|
+
Button("Save", { variant: "primary", loading: $isSaving })
|
|
36
|
+
StatCard("Revenue", { value: "$48k", trend: "up", delta: "+12%" })
|
|
37
|
+
Row([Card1(), Card2()], { gap: "m" })
|
|
132
38
|
```
|
|
133
39
|
|
|
134
|
-
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
40
|
+
`Button("Save", "primary", true)` is a schema error — write the named-prop form instead. Every call site also accepts `{ key: ... }` to pin per-instance state across reorders.
|
|
41
|
+
|
|
42
|
+
## JavaScript is fully supported
|
|
43
|
+
|
|
44
|
+
Aktion is a strict subset of JavaScript — every standard JS feature works inside expressions, action bodies, effect callbacks, and lambdas. Use whichever style is clearest for the value you need to compute.
|
|
45
|
+
|
|
46
|
+
### In expressions (right-hand side of `=`)
|
|
47
|
+
Use **value-producing** JS — no `if`/`switch`/`for` statements here.
|
|
140
48
|
|
|
141
|
-
### Call sites
|
|
142
49
|
```
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
50
|
+
// Ternary for branching
|
|
51
|
+
banner = $error ? Banner($error, { tone: "danger" }) : null
|
|
52
|
+
tone = $value > 0 ? "success" : ($value < 0 ? "danger" : "muted")
|
|
53
|
+
|
|
54
|
+
// .map / .filter / .reduce for iteration
|
|
55
|
+
rows = $todos.map(t => TodoRow(t))
|
|
56
|
+
visible = $todos.filter(t => !t.done).map(t => TodoRow(t))
|
|
57
|
+
total = $cart.reduce((sum, item) => sum + item.price, 0)
|
|
58
|
+
|
|
59
|
+
// Object/array spread, destructuring, optional chaining, nullish coalescing
|
|
60
|
+
merged = { ...$base, status: "done" }
|
|
61
|
+
[a, b] = $points
|
|
62
|
+
name = $user?.profile?.name ?? "Guest"
|
|
63
|
+
|
|
64
|
+
// Template literals — preferred over string concatenation
|
|
65
|
+
title = `Found ${rows.length} ${$util.plural(rows.length, "result", "results")}`
|
|
66
|
+
|
|
67
|
+
// Wrap a switch/match in a function and call it
|
|
68
|
+
function panelFor(tab) {
|
|
69
|
+
switch (tab) {
|
|
70
|
+
case "overview": return Overview()
|
|
71
|
+
case "billing": return Billing()
|
|
72
|
+
default: return Empty()
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
panel = panelFor($tab)
|
|
148
76
|
```
|
|
149
77
|
|
|
150
|
-
###
|
|
151
|
-
|
|
78
|
+
### In action / effect / lambda bodies
|
|
79
|
+
The full **statement** surface is available — `if`, `else`, `switch`, `for...of`, `for...in`, classic `for`, `while`, `do…while`, `break`, `continue`, `try`/`catch`/`finally`, `throw`, `return`. Plus all assignment operators (`= += -= *= /= ??= ++ --`) against `$atoms` and member chains rooted at one (`$user.name = "Alex"`).
|
|
80
|
+
|
|
152
81
|
```
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
82
|
+
function submit(payload) {
|
|
83
|
+
if (!payload.email) return
|
|
84
|
+
for (let tag of payload.tags) $tags = [...$tags, tag]
|
|
85
|
+
switch (payload.kind) {
|
|
86
|
+
case "draft": $drafts = [...$drafts, payload]; break
|
|
87
|
+
default: $records = [...$records, payload]
|
|
88
|
+
}
|
|
89
|
+
$emit("submitted", { id: payload.id })
|
|
90
|
+
}
|
|
156
91
|
```
|
|
157
92
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
An `action` is a callable block of imperative statements. Declare at the
|
|
161
|
-
top level (or inside a component body); invoke from any event-handler prop
|
|
162
|
-
(`onClick`, `onChange`, `onSubmit`) or as an expression.
|
|
93
|
+
### Timers — `setTimeout` / `setInterval`
|
|
94
|
+
`setTimeout(fn, ms)`, `setInterval(fn, ms)`, `clearTimeout(id)`, and `clearInterval(id)` are available and behave like their JS counterparts. They return a handle you can later clear. Timers are tracked by the runtime and torn down automatically when the program re-plans, so they never outlive the program — but you should still clear a `setInterval` you no longer need. Create them inside an `effect` (not at the top level, which would re-create them on every render) and clear them in the effect's `cleanup`.
|
|
163
95
|
|
|
164
96
|
```
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
$
|
|
168
|
-
|
|
97
|
+
// Debounced search — restart a 300ms timer on every keystroke
|
|
98
|
+
function onType(q) {
|
|
99
|
+
clearTimeout($searchTimer)
|
|
100
|
+
$searchTimer = setTimeout(() => { $results = $http({ url: `/search?q=${q}` }) }, 300)
|
|
169
101
|
}
|
|
170
102
|
|
|
171
|
-
|
|
103
|
+
// A ticking clock — start on mount, clear on unmount
|
|
104
|
+
$effect(() => {
|
|
105
|
+
let id = setInterval(() => { $now = $util.now() }, 1000)
|
|
106
|
+
cleanup(() => clearInterval(id))
|
|
107
|
+
}, ["mount"])
|
|
172
108
|
```
|
|
173
109
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
- `
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
forms (covered below).
|
|
182
|
-
- `return` — optionally yields a value to the caller.
|
|
183
|
-
- `js{ /* opaque JS */ }` — escape hatch for browser APIs not exposed
|
|
184
|
-
natively (see § JS escape hatch).
|
|
185
|
-
|
|
186
|
-
### Optional `return`
|
|
187
|
-
Actions MAY include a `return` statement. When omitted the action runs for
|
|
188
|
-
its side effects and yields `undefined`. When present the result is
|
|
189
|
-
observable from `$x = myAction(...)` expressions:
|
|
110
|
+
Prefer `$effect(..., ["every(1000)"])` for a simple repeating effect; reach for `setInterval`/`setTimeout` when you need an imperative handle to clear, a one-shot delay, or a debounce/restart.
|
|
111
|
+
|
|
112
|
+
### Lambdas (arrow functions) — every JS form works
|
|
113
|
+
`() => expr`, `x => expr`, `(x, y) => expr`, `(x = 0) => x`, `(...args) => sum(args)`, and the multi-statement `(x) => { ...; return ... }` form. Long lambdas may continue onto the next line.
|
|
114
|
+
|
|
115
|
+
### Line continuations (matches JS ASI)
|
|
116
|
+
Any expression operator (`.`, `?.`, `?`, `:`, `&&`, `||`, `??`, comparison, arithmetic) at the **start** of the next line keeps building the same expression.
|
|
190
117
|
|
|
191
118
|
```
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
$hello = greet("Ada") // re-runs whenever the action call's args change
|
|
119
|
+
filteredTodos = $todos
|
|
120
|
+
.filter(t => t.category == $filter)
|
|
121
|
+
.filter(t => t.title.includes($searchQuery))
|
|
196
122
|
```
|
|
197
123
|
|
|
198
|
-
###
|
|
199
|
-
|
|
124
|
+
### Comments
|
|
125
|
+
Only `// line` and `/* block */` comments. No `#` shebangs.
|
|
126
|
+
|
|
127
|
+
### Forbidden in expression position
|
|
128
|
+
`if`, `switch`, `for`, `while`, `try` are statements — they cannot be assigned to a binding directly. Use a ternary, `.map`/`.filter`, or wrap them in a function.
|
|
129
|
+
|
|
130
|
+
## Reactive State
|
|
131
|
+
|
|
132
|
+
The `$` sigil is the only thing that makes a binding reactive. `let`/`const`/`var` keywords are optional and have no effect on reactivity.
|
|
200
133
|
|
|
201
134
|
```
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
135
|
+
$count = 0
|
|
136
|
+
$user = { name: "Ada", role: "Engineer" }
|
|
137
|
+
$todos = []
|
|
205
138
|
```
|
|
206
139
|
|
|
207
|
-
|
|
140
|
+
### Read & write
|
|
141
|
+
- Read `$name` anywhere — auto-subscribes whoever reads it (component, derived value, effect).
|
|
142
|
+
- Write `$name = ...` from event handlers, effect callbacks, and lambda bodies — i.e. in response to an event, never while building the UI. `+=`, `-=`, `*=`, `/=`, `??=`, `++`, `--` work too. Member writes (`$user.name = "Alex"`) rebuild the root immutably so subscribers see a fresh reference.
|
|
143
|
+
- **Never write `$state` in render position.** A `$name = ...` that runs while the UI is being built schedules a re-render that re-runs the write — an infinite loop. This bites when a `function` that *declares* state is invoked to render (`aktion = app()` where `app` does `$user = {...}`): a lowercase `function` called that way runs as an action, so the assignment is a per-render write. To hold component-local state, make it a **PascalCase component** (then top-of-body `$count = 0` is a set-once per-instance declaration) or use the `$state` hook — both seed once and persist. (The runtime defends against the loop — it applies the write but skips the re-render and warns — but the pattern is still wrong.)
|
|
144
|
+
|
|
145
|
+
### Fine-grained reactivity (path-level)
|
|
146
|
+
Subscriptions are tracked at the **path** you read, not the whole atom. Reading `$user.name` subscribes to `user.name` alone: a write to a sibling field (`$user.role = ...`) won't re-render or recompute it, while replacing the whole atom (`$user = ...`) or writing a descendant still does. The same rule drives computed values and effect deps (`$effect(..., [$user.name])` fires only on `name` changes). Reading a whole object (`$user`) or indexing into an array (`$rows[i]`, the `$rows.field` pluck) subscribes at that object/array — so prefer reading the exact field you need (`$user.name`) to get the tightest updates. No selectors or special syntax — just read the path.
|
|
147
|
+
|
|
148
|
+
A component re-executes only when **its own inputs change** — its args (props) or a `$state` path its body read — like `React.memo` / Solid, but automatic. So `ShowName($user.name)` and `ShowAge($user.age)` are independent: changing `$user.age` re-runs only `ShowAge`. Args are compared shallowly, so (as in React) a fresh inline lambda prop each render makes the child re-render — hoist the handler to a stable binding to skip it.
|
|
208
149
|
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
150
|
+
### Per-instance state
|
|
151
|
+
`$name = value` inside a function body is per-instance when the function is used as a component. Two `Counter()` siblings each hold their own `$count`. Add `{ key: id }` at the call site to keep state attached when siblings reorder.
|
|
152
|
+
|
|
153
|
+
### Hooks — composable per-instance state
|
|
154
|
+
A function whose name starts with `$` is a **hook** (mirroring React's `use*` convention). Call hooks only at the top level of a component body (or another hook), in a stable order — never inside an `if`, loop, or callback. Hook state is per-instance and resets when the instance leaves the tree.
|
|
155
|
+
|
|
156
|
+
- `$state(initial)` → `[value, setValue]`, like React's `useState`. `setValue(next)` replaces the value; `setValue(prev => next)` derives it from the previous value. `initial` is evaluated once, on first render.
|
|
157
|
+
- `$memo(() => compute, [deps])` → a cached value, like React's `useMemo`. Recomputes only when a dependency changes (shallow `Object.is` compare); omit the deps array to recompute every render.
|
|
158
|
+
- `function $name(...) { ... }` declares a custom hook that composes the built-ins. Its `$state` / `$memo` calls attach to the component that called it.
|
|
212
159
|
|
|
213
160
|
```
|
|
214
|
-
|
|
215
|
-
|
|
161
|
+
function $useCounter(start) {
|
|
162
|
+
const [count, setCount] = $state(start)
|
|
163
|
+
return { count: count, increment: () => setCount(c => c + 1) }
|
|
216
164
|
}
|
|
165
|
+
|
|
166
|
+
function Counter() {
|
|
167
|
+
const c = $useCounter(0)
|
|
168
|
+
const label = $memo(() => `Count: ${c.count}`, [c.count])
|
|
169
|
+
return Stack([Text(label), Button("+1", { onClick: c.increment })])
|
|
170
|
+
}
|
|
171
|
+
aktion = Counter()
|
|
217
172
|
```
|
|
218
173
|
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
-
|
|
222
|
-
|
|
223
|
-
- `on:every(N)` — re-run every N milliseconds.
|
|
224
|
-
- `debounce(N)` / `throttle(N)` — wrap the body with a trailing-edge rate limit.
|
|
174
|
+
Reach for `$state(...)` when a component owns local state with explicit setters; the bare `$name = value` per-instance form above is the lighter option when an atom is written directly by the component's actions. `$state` and `$memo` are reserved hook names.
|
|
175
|
+
|
|
176
|
+
### Two-way binding (implicit)
|
|
177
|
+
Pass a `$variable` (or a member chain rooted at one — `value: $form.email`) as a value prop on any input/select/checkbox/switch/slider/picker and the runtime wires the change handler automatically. Add `onChange: v => ...` when you also need a side effect (debounced search, persistence, etc.).
|
|
225
178
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
179
|
+
```
|
|
180
|
+
$draft = ""
|
|
181
|
+
$theme = "light"
|
|
229
182
|
|
|
230
|
-
|
|
231
|
-
|
|
183
|
+
field = Input("draft", { value: $draft })
|
|
184
|
+
darkMode = Switch("dark", { value: $theme == "dark", onChange: on => $theme = on ? "dark" : "light" })
|
|
185
|
+
search = Input("query", { onChange: q => $results = $http({ url: `https://api.example.com/search?q=${q}` }) })
|
|
186
|
+
```
|
|
232
187
|
|
|
233
|
-
###
|
|
234
|
-
|
|
235
|
-
`component Name() { … }` body. The syntax is identical; only the
|
|
236
|
-
lifecycle differs:
|
|
237
|
-
|
|
238
|
-
- **Top-level** — mounted once when the program parses, torn down on
|
|
239
|
-
`setResponse` / `clear()`. Use for global concerns (analytics,
|
|
240
|
-
app-wide shortcuts, hydration of shared atoms).
|
|
241
|
-
- **Component-local** — mounted once per component instance on its
|
|
242
|
-
first render, torn down when the instance disappears from the tree.
|
|
243
|
-
Each instance gets its own timers, watched-atom subscriptions, and
|
|
244
|
-
`cleanup(fn)` registrations. Use for per-instance work (per-row
|
|
245
|
-
polling, modal focus management, observers attached to a widget).
|
|
188
|
+
### Computed values
|
|
189
|
+
There is no separate "computed" tier — just compute. Every `$` reference inside an expression auto-tracks.
|
|
246
190
|
|
|
247
191
|
```
|
|
248
|
-
|
|
249
|
-
$
|
|
192
|
+
$open = $todos.filter((t) => !t.done)
|
|
193
|
+
$total = $util.sum($cart.price)
|
|
194
|
+
```
|
|
250
195
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
$value = $value + 1
|
|
254
|
-
}
|
|
196
|
+
### Global stores — `$store({...})`
|
|
197
|
+
For app-wide state shared across many components (no prop drilling), declare a **store** at the top level. Non-function entries are reactive **state**; function entries are **methods** that receive the store handle `s` as their first argument. Read state as `store.field` (fine-grained — subscribes to that slice) and call methods as `store.method(args)`. Mutate inside a method with `s.field = …`. The handle is an app-global singleton with reference-stable methods.
|
|
255
198
|
|
|
256
|
-
component App() {
|
|
257
|
-
return Box([Text("Value: " + $value)])
|
|
258
|
-
}
|
|
259
199
|
```
|
|
200
|
+
cart = $store({
|
|
201
|
+
items: [], // state
|
|
202
|
+
count: (s) => s.items.length, // getter-method → cart.count()
|
|
203
|
+
total: (s) => $util.sum(s.items.map(i => i.price)), // getter-method → cart.total()
|
|
204
|
+
add: (s, item) => { s.items = [...s.items, item] }, // action → cart.add(item)
|
|
205
|
+
clear: (s) => { s.items = [] },
|
|
206
|
+
})
|
|
260
207
|
|
|
208
|
+
function CartBadge() { return Badge(`${cart.count()} items`) } // reads the store
|
|
209
|
+
function AddButton(item) { return Button("Add", { onClick: () => cart.add(item) }) } // calls a method
|
|
261
210
|
```
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
211
|
+
|
|
212
|
+
Reads are fine-grained and per-component: changing `cart.items` re-renders only components that read `items`. Two-way binding works against a store field (`Input(value: form.draft)`). Use a `Store` for shared/global state; use a component's local `$state` / `$name = …` for state only one component owns.
|
|
213
|
+
|
|
214
|
+
## Components & Actions
|
|
215
|
+
|
|
216
|
+
A `function` declaration creates BOTH a component (callable in render position; its return value is rendered) and an action (callable from an event handler; its body runs for side effects). The first-letter case of the name is NOT significant — `function Card(...)`, `function card(...)`, `function SaveOrder(...)`, and `function saveOrder(...)` are all valid. A function with no `return` simply renders nothing when invoked in a render position. The same applies to arrow-function bindings (`Display = () => Card(...)` and `display = () => Card(...)` both work).
|
|
217
|
+
|
|
218
|
+
### Components
|
|
219
|
+
A function used as a component returns a render tree. Parameters use standard JS defaults; destructured options are canonical. To render a component you MUST call it with parentheses — even when it takes no arguments. The bare identifier is just the function value.
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
// Both forms work — case is not significant
|
|
223
|
+
function UserCard(user) { return Card([Text(user.name)]) }
|
|
224
|
+
function userCard(user) { return Card([Text(user.name)]) }
|
|
225
|
+
Display = () => ["apple", "banana"].map(function (e) { return Button(e) })
|
|
226
|
+
aktion = Column([UserCard($currentUser), userCard($otherUser), Display()])
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
```
|
|
230
|
+
function UserCard(user, { tone = "default" } = {}) {
|
|
231
|
+
$hover = false
|
|
232
|
+
return Card([
|
|
233
|
+
Avatar(user.name, { size: "md" }),
|
|
234
|
+
Text(user.name, { variant: "large-heavy" }),
|
|
235
|
+
Text(user.role, { tone: "muted" }),
|
|
236
|
+
Badge(tone, { tone: tone })
|
|
237
|
+
])
|
|
272
238
|
}
|
|
273
239
|
```
|
|
274
240
|
|
|
275
|
-
|
|
241
|
+
- `children` parameter is the implicit slot — the call site's positional argument is delivered into it.
|
|
242
|
+
- User-declared components shadow built-ins by name, so you can wrap library components with telemetry / per-app styling.
|
|
243
|
+
- Lambdas (`row = item => Row(item)`) are the right tool for one-off helpers that don't need their own component.
|
|
244
|
+
- A function that does not `return` anything simply renders nothing when called in a render position — the runtime treats the missing/undefined value as an empty fragment.
|
|
245
|
+
|
|
246
|
+
### Actions
|
|
247
|
+
A `function` whose body runs for side effects (rather than returning a render tree) acts as an action. Use as event handler (`onClick: save`) or as a value-producing expression (`$result = greet("Ada")`). The first-letter case of the name does not matter — `save` and `Save` are both valid.
|
|
276
248
|
|
|
277
249
|
```
|
|
278
|
-
|
|
279
|
-
$
|
|
280
|
-
|
|
281
|
-
|
|
250
|
+
function save(item) {
|
|
251
|
+
$items = [...$items, item]
|
|
252
|
+
$save = $http({ url: "https://api.example.com/save", method: "POST", body: { item } })
|
|
253
|
+
$emit("saved", { id: item.id })
|
|
282
254
|
}
|
|
283
255
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
256
|
+
submitBtn = Button("Save", { onClick: save })
|
|
257
|
+
resetBtn = Button("Reset", { onClick: () => { $count = 0; $message = "" } }) // inline lambda
|
|
258
|
+
```
|
|
287
259
|
|
|
288
|
-
|
|
289
|
-
$save = http({ url: "/api/draft", method: "PUT", body: $draft })
|
|
290
|
-
}
|
|
260
|
+
`return` is optional. Inside the body, the full JS statement surface is available (see *JavaScript is fully supported*).
|
|
291
261
|
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
262
|
+
### `$emit("name", { detail })`
|
|
263
|
+
Inside any action / effect / lambda, `$emit("name", { detail })` dispatches an outbound `CustomEvent` on the host `<aktion-app>` element. Reserved names: `assistant-message` (chat follow-up), `error`, `route-change`. Pick stable names; the host listens with `el.addEventListener("name", ...)`.
|
|
264
|
+
|
|
265
|
+
## Effects — Declarative side effects
|
|
266
|
+
|
|
267
|
+
`$effect(() => { ... }, [...deps])` runs declarative side effects. Dependency entries:
|
|
268
|
+
|
|
269
|
+
- `$atom` — re-run when this reactive atom changes.
|
|
270
|
+
- `"mount"` — run once when the surrounding scope mounts.
|
|
271
|
+
- `"unmount"` — run once when it unmounts.
|
|
272
|
+
- `"every(N)"` — re-run every N milliseconds.
|
|
273
|
+
- `"debounce(N)"` / `"throttle(N)"` — wrap the body with a trailing-edge rate limit.
|
|
274
|
+
|
|
275
|
+
`$effect(() => { ... })` (no second argument) is shorthand for `["mount"]`.
|
|
276
|
+
|
|
277
|
+
### Scope — top-level vs. component-local
|
|
278
|
+
Top-level effects mount on parse, tear down on `setResponse` / `clear()`. Effects inside a component body mount per-instance and tear down when the instance leaves the tree (clearing intervals, watched-atom subscriptions, and `cleanup(fn)` registrations).
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
function LiveClock() {
|
|
282
|
+
$now = $util.now()
|
|
283
|
+
$effect(() => { $now = $util.now() }, ["every(1000)"])
|
|
284
|
+
return Text($util.formatDate($now, "time"))
|
|
298
285
|
}
|
|
286
|
+
|
|
287
|
+
// Debounced search — re-issue the request when inputs change
|
|
288
|
+
$effect(() => {
|
|
289
|
+
$results = $http({ url: "https://api.example.com/search", query: { q: $query, page: $page } })
|
|
290
|
+
}, [$query, $page, "debounce(250)"])
|
|
291
|
+
|
|
292
|
+
// Cleanup
|
|
293
|
+
$effect(() => {
|
|
294
|
+
const onKey = e => { if (e.key == "/") $palette = true }
|
|
295
|
+
document.addEventListener("keydown", onKey)
|
|
296
|
+
cleanup(() => document.removeEventListener("keydown", onKey))
|
|
297
|
+
}, ["mount"])
|
|
299
298
|
```
|
|
300
299
|
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
300
|
+
## Data — `$http({...})`
|
|
301
|
+
|
|
302
|
+
`$http({ ... })` is the only HTTP primitive. Every call is self-contained — pass a full absolute `url`, an optional `method` (`GET` is the default), a convenience `query` object serialised into the URL, `headers`, `body`, and any other `fetch`-compatible option. There are NO host-wide defaults.
|
|
304
303
|
|
|
305
|
-
|
|
304
|
+
```
|
|
305
|
+
$orders = $http({
|
|
306
|
+
url: `https://api.example.com/users/${$userId}/orders`,
|
|
307
|
+
method: "GET",
|
|
308
|
+
query: { limit: 5, status: "open" }, // → ?limit=5&status=open
|
|
309
|
+
headers:{ "X-Tenant": $tenant }
|
|
310
|
+
})
|
|
311
|
+
```
|
|
306
312
|
|
|
307
|
-
|
|
308
|
-
array of nodes) that can be assigned, passed as a prop, or returned from a
|
|
309
|
-
component / action body.
|
|
313
|
+
The request fires once when the binding mounts. To re-run it call `$orders.refetch()`, or wrap it in an `$effect(..., [$dep])` so it re-issues when a dependency changes.
|
|
310
314
|
|
|
311
|
-
###
|
|
315
|
+
### Reactive resource shape
|
|
312
316
|
```
|
|
313
|
-
|
|
314
|
-
|
|
317
|
+
$orders.data // parsed body (null until resolved)
|
|
318
|
+
$orders.error // null on success
|
|
319
|
+
$orders.status // HTTP status code, e.g. 200
|
|
320
|
+
$orders.loading // true while in-flight
|
|
321
|
+
$orders.headers // response headers as a plain object
|
|
322
|
+
$orders.lastUpdated // ms-epoch of last successful response
|
|
323
|
+
$orders.refetch() // re-issue the request
|
|
324
|
+
$orders.cancel() // abort the in-flight request
|
|
325
|
+
$orders.onDone = fn // callback fired each time the request settles
|
|
315
326
|
```
|
|
316
|
-
A trailing `else` is optional — without it an unmatched `if` evaluates to
|
|
317
|
-
`null` (renders nothing).
|
|
318
327
|
|
|
319
|
-
### `
|
|
328
|
+
### `onDone` — run something when the request settles
|
|
329
|
+
Assign `onDone` after creating the resource. It fires once every time the request completes — the initial load and every `refetch()`, on both success and error — and receives the resource bag as its argument. It does NOT fire for a request that was superseded or `cancel()`led. This is the idiomatic way to refresh a list after a mutation:
|
|
330
|
+
|
|
320
331
|
```
|
|
321
|
-
|
|
322
|
-
"
|
|
323
|
-
"
|
|
324
|
-
|
|
325
|
-
|
|
332
|
+
$patch = $http({
|
|
333
|
+
url: endpoint + "/" + todo.id,
|
|
334
|
+
method: "PATCH",
|
|
335
|
+
body: { isCompleted: !todo.isCompleted }
|
|
336
|
+
})
|
|
337
|
+
|
|
338
|
+
$patch.onDone = () => {
|
|
339
|
+
$todos.refetch()
|
|
326
340
|
}
|
|
327
341
|
```
|
|
328
|
-
- Arms use `: value` like object properties (the arrow form `->` is
|
|
329
|
-
not valid).
|
|
330
|
-
- `default:` is the wildcard.
|
|
331
|
-
- Arms can return arbitrary expressions, not just strings.
|
|
332
342
|
|
|
333
|
-
###
|
|
343
|
+
### Writes — fire from an action
|
|
334
344
|
```
|
|
335
|
-
|
|
336
|
-
|
|
345
|
+
function saveOrder(payload) {
|
|
346
|
+
$save = $http({ url: "https://api.example.com/orders", method: "POST", body: payload })
|
|
347
|
+
$save.onDone = () => { $orders.refetch() }
|
|
348
|
+
$emit("assistant-message", { message: "Saved." })
|
|
349
|
+
}
|
|
337
350
|
```
|
|
338
|
-
`for` produces an array of nodes — assign it and reference the binding
|
|
339
|
-
from a container (`Stack(rows)`, `Table([Col("Task", rows)])`). The loop
|
|
340
|
-
variable is **block-scoped**, so a stale closure can never see the wrong row.
|
|
341
351
|
|
|
342
|
-
|
|
343
|
-
|
|
352
|
+
`body` objects are JSON-encoded automatically (a `Content-Type: application/json` header is added unless you set one). After a write, call `.refetch()` on the list resource to refresh it — either directly or from the write resource's `onDone`.
|
|
353
|
+
|
|
354
|
+
### `Async` wrapper — branch on resource state
|
|
344
355
|
```
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
"
|
|
350
|
-
|
|
351
|
-
}
|
|
352
|
-
}
|
|
356
|
+
view = Async($orders, {
|
|
357
|
+
loading: LoadingState("Loading orders…"),
|
|
358
|
+
error: ErrorState("Couldn't fetch orders"),
|
|
359
|
+
empty: EmptyState("No orders yet"), // shown when data is null or an empty array
|
|
360
|
+
data: Table([Col("Item", $orders.data.title), Col("Total", $orders.data.total, { format: "currency" })])
|
|
361
|
+
})
|
|
353
362
|
```
|
|
354
363
|
|
|
355
|
-
## Routing
|
|
364
|
+
## Routing
|
|
356
365
|
|
|
357
|
-
The router is a plain function call.
|
|
358
|
-
value — assign the result to any binding and reference that binding inside
|
|
359
|
-
your shell.
|
|
366
|
+
The router is a plain function call. Assign `$router({ ... })` to a binding and reference that binding from your shell.
|
|
360
367
|
|
|
361
368
|
```
|
|
362
|
-
pages =
|
|
369
|
+
pages = $router({
|
|
363
370
|
"/": Dashboard(),
|
|
364
371
|
"/orders": OrdersPage(),
|
|
365
|
-
"/orders/:id": OrderDetail(id: params.id),
|
|
366
|
-
"/settings/*": SettingsArea(rest: params._),
|
|
372
|
+
"/orders/:id": OrderDetail({ id: params.id }),
|
|
373
|
+
"/settings/*": SettingsArea({ rest: params._ }),
|
|
367
374
|
default: NotFound()
|
|
368
375
|
})
|
|
369
376
|
|
|
370
|
-
|
|
377
|
+
aktion = AppShell(MainSidebar(), pages, TopBar())
|
|
371
378
|
```
|
|
372
379
|
|
|
373
|
-
|
|
374
|
-
-
|
|
375
|
-
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
- Use `_route_` for cross-cutting reactive reads (current path, query
|
|
384
|
-
string) that don't depend on which arm matched.
|
|
385
|
-
|
|
386
|
-
### Reactive surface
|
|
387
|
-
- `_route_.path` — current path (read-only).
|
|
388
|
-
- `_route_.params.id` — path parameter; reactive.
|
|
389
|
-
- `_route_.query.tab` — query string; **writable** (assigning updates the URL).
|
|
390
|
-
- `_route_.navigate("/path")` — imperative navigation. Use inside any action
|
|
391
|
-
or effect body.
|
|
392
|
-
|
|
393
|
-
### `NavLink` companion
|
|
394
|
-
`NavLink(label, to)` reads `_route_.path` and dispatches
|
|
395
|
-
`_route_.navigate(to)` on click — use for sidebars, navbars and breadcrumbs.
|
|
396
|
-
|
|
397
|
-
### Common mistakes
|
|
398
|
-
- `_route_` is read-only (apart from `_route_.navigate(...)`). Assigning
|
|
399
|
-
to `_route_` or to a state slot named `route` is ignored.
|
|
400
|
-
- Forgetting the `default:` arm. Without it, unknown paths render `null`
|
|
401
|
-
and the outlet collapses.
|
|
402
|
-
- Using `->` instead of `:` for arm bodies. Inside `_router_({…})` the
|
|
403
|
-
arms are ordinary object properties — separate with `:` and commas.
|
|
404
|
-
|
|
405
|
-
## Two-way binding — `bind:`
|
|
406
|
-
|
|
407
|
-
`bind:value: $name` desugars to `value: $name, onValueChange: (v) => $name = v`.
|
|
408
|
-
The right-hand side must be a state ref (`$x`), member access
|
|
409
|
-
(`$user.name`), or a form field — never a computed expression.
|
|
380
|
+
- Path patterns: literal `"/about"`, parameter `"/users/:id"` (read `params.id`), trailing wildcard `"/docs/*"` (read `params._`), `default:` for the catch-all.
|
|
381
|
+
- `route` handle (read-only): `route.path`, `route.params.x`, `route.query.tab`, `route.pattern`.
|
|
382
|
+
- `route.navigate("/path")` inside an action / effect changes the URL.
|
|
383
|
+
- `NavLink(label, { to, exact?, icon? })` and `SidebarItem(label, { to, icon?, badge? })` are router-aware anchors that auto-derive their active state from `route.path`.
|
|
384
|
+
|
|
385
|
+
NEVER declare a state slot named `route` yourself. Forget the `default:` arm and unknown paths render `null`.
|
|
386
|
+
|
|
387
|
+
## Built-in globals — `storage` & `console`
|
|
388
|
+
|
|
389
|
+
Both are always in scope, lowercase. No imports.
|
|
410
390
|
|
|
411
391
|
```
|
|
412
|
-
$
|
|
413
|
-
|
|
414
|
-
|
|
392
|
+
// localStorage (default); '$storage.local' is its alias
|
|
393
|
+
$storage.set("name", "John")
|
|
394
|
+
$name = $storage.get("name")
|
|
395
|
+
$storage.remove("name")
|
|
396
|
+
|
|
397
|
+
// sessionStorage (per-tab)
|
|
398
|
+
$storage.session.set("draft", $draft)
|
|
399
|
+
|
|
400
|
+
// Cookies — options as an object literal
|
|
401
|
+
$storage.cookies.set("user", "John", { expires: 7, path: "/", sameSite: "Lax" })
|
|
402
|
+
$storage.cookies.remove("user", { path: "/" })
|
|
415
403
|
|
|
416
|
-
|
|
417
|
-
|
|
404
|
+
// Console — forwards to host console
|
|
405
|
+
$console.log("Hello", $user)
|
|
406
|
+
$console.error("Failed", $error)
|
|
418
407
|
```
|
|
419
408
|
|
|
420
|
-
`
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
`
|
|
424
|
-
`DateTimePicker`, `SearchBar`, `PinInput`, `PasswordInput`,
|
|
425
|
-
`TagInput`, `MentionInput`, `MaskedInput`, `RichTextEditor`,
|
|
426
|
-
`CodeEditor`, `ColorPicker`, `Rating` (when `interactive: true`),
|
|
427
|
-
`Pagination` (binds `page`).
|
|
428
|
-
|
|
429
|
-
## JS escape hatch — `js{ … }`
|
|
430
|
-
|
|
431
|
-
`js{ /* opaque JS body */ }` runs raw JavaScript inside an `effect`,
|
|
432
|
-
`action`, or lambda body. Use sparingly — every other surface is preferred —
|
|
433
|
-
but it is always available for browser APIs not exposed natively (clipboard,
|
|
434
|
-
keyboard listeners, IntersectionObserver, audio, custom DOM work).
|
|
435
|
-
|
|
436
|
-
The body receives a single `ctx` bridge:
|
|
437
|
-
- `ctx.host` — the `<aktion-app>` host element (for `dispatchEvent`).
|
|
438
|
-
- `ctx.state` — `{ get(name), set(name, value) }` for reactive atoms.
|
|
439
|
-
- `ctx.cleanup(fn)` — register teardown (same semantics as `effect` cleanup).
|
|
440
|
-
- `ctx.tools` — host-registered endpoint catalog (rarely needed; prefer `http()`).
|
|
441
|
-
- `ctx.args` — when invoked from an `action` or lambda, the call's arguments.
|
|
409
|
+
Non-string values JSON-roundtrip; missing keys return `null`. Cookie options: `expires` (days/Date/ISO), `maxAge` (seconds), `path`, `domain`, `secure`, `sameSite`. Failures (quota, disabled storage) are swallowed silently.
|
|
410
|
+
|
|
411
|
+
### The full JavaScript global surface
|
|
412
|
+
Beyond `storage` and `console`, **every** JavaScript global resolves by name — the standard library (`Math`, `JSON`, `Object`, `Date`, `Map`, …), browser dialogs (`alert`, `confirm`, `prompt`), and Web APIs (`fetch`, `URL`, `URLSearchParams`, `Blob`, `FormData`, `crypto`, `navigator`, `localStorage`, `atob`/`btoa`, `Intl`, `BigInt`, …), plus `window` / `document`.
|
|
442
413
|
|
|
443
414
|
```
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
ctx.cleanup(() => clearInterval(id))
|
|
448
|
-
}
|
|
415
|
+
function copyLink() {
|
|
416
|
+
navigator.clipboard.writeText(window.location.href)
|
|
417
|
+
$toast = "Link copied"
|
|
449
418
|
}
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
js{ navigator.clipboard.writeText(window.location.href) }
|
|
453
|
-
emit "assistant-message" { message: "Link copied" }
|
|
419
|
+
function remove(id) {
|
|
420
|
+
if (confirm("Delete this item?")) { $items = $items.filter(x => x.id != id) }
|
|
454
421
|
}
|
|
422
|
+
id = crypto.randomUUID()
|
|
455
423
|
```
|
|
456
424
|
|
|
457
|
-
|
|
425
|
+
Author declarations and built-in components always win over a same-named global, so the passthrough only fills in names you haven't defined. Prefer the reactive `$http({...})` over raw `fetch` for data that drives the UI, and keep timers/listeners inside `$effect(...)` so they're cleaned up.
|
|
458
426
|
|
|
459
|
-
|
|
460
|
-
features as library components rather than language keywords:
|
|
427
|
+
## Behaviour wrappers
|
|
461
428
|
|
|
462
|
-
|
|
463
|
-
|---|---|
|
|
464
|
-
| `Async(resource, loading:, error:, empty:, data:)` | Branch on an `http({...})` resource's state. |
|
|
465
|
-
| `Show(when, fallback?, children)` | Sugar over `if when { children } else { fallback }`. |
|
|
466
|
-
| `Portal(children, target?)` | Render children outside the parent subtree. |
|
|
467
|
-
| `Redirect(path)` | Navigate to `path` and unmount the rest of the subtree. |
|
|
468
|
-
| `Lazy(loader, fallback?, children)` | Defer rendering children until `loader` resolves. |
|
|
469
|
-
| `ErrorBoundary(children, fallback?, onError?)` | Catch render errors thrown by descendants. |
|
|
470
|
-
| `VirtualList(items, key:, render:)` | Virtualised list — preferred for >100 rows. |
|
|
471
|
-
|
|
472
|
-
## Built-in globals
|
|
473
|
-
|
|
474
|
-
Two namespace globals are always in scope — no import, no declaration.
|
|
475
|
-
Invoke them through the standard `obj.method(args)` syntax. Named-arg
|
|
476
|
-
options collapse into a single trailing options object on the method's
|
|
477
|
-
arg list (same rule as component named args).
|
|
478
|
-
|
|
479
|
-
`storage` — browser storage (localStorage by default):
|
|
480
|
-
```
|
|
481
|
-
storage.set("name", "John") // alias of storage.local.set
|
|
482
|
-
$name = storage.get("name")
|
|
483
|
-
storage.remove("name")
|
|
484
|
-
storage.clear()
|
|
485
|
-
|
|
486
|
-
storage.session.set("draft", $draft) // per-tab sessionStorage
|
|
487
|
-
$draft = storage.session.get("draft")
|
|
488
|
-
|
|
489
|
-
storage.cookies.set("user", "John", expires: 7, path: "/", sameSite: "Lax")
|
|
490
|
-
$user = storage.cookies.get("user")
|
|
491
|
-
storage.cookies.remove("user", path: "/")
|
|
492
|
-
storage.cookies.clear()
|
|
493
|
-
```
|
|
494
|
-
- Values that aren't strings round-trip through JSON; missing keys return `null`.
|
|
495
|
-
- Cookie options: `expires` (days, Date, or ISO string), `maxAge`
|
|
496
|
-
(seconds), `path`, `domain`, `secure`, `sameSite`.
|
|
429
|
+
Six tiny wrappers attach behaviour or styling to ANY component without forcing every primitive to grow another prop. They render the child via `display: contents`, so the visual tree is unchanged — only the event / styling layer changes.
|
|
497
430
|
|
|
498
|
-
`console` — host console forwarder:
|
|
499
|
-
```
|
|
500
|
-
console.log("Hello", $user)
|
|
501
|
-
console.error("Failed", $error)
|
|
502
|
-
console.warn("Deprecated path")
|
|
503
|
-
console.info("Route changed", _route_.path)
|
|
504
|
-
console.debug({ days: $days, count: $count })
|
|
505
431
|
```
|
|
432
|
+
// Clickable card
|
|
433
|
+
OnClick(Card([Text("View order")]), { onClick: () => route.navigate("/orders/4821") })
|
|
506
434
|
|
|
507
|
-
|
|
435
|
+
// Lazy-load sentinel — fires once when scrolled into view
|
|
436
|
+
OnIntersect(Skeleton({ variant: "card" }), { onEnter: $items.refetch, once: true })
|
|
508
437
|
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
$
|
|
513
|
-
locale: $locale,
|
|
514
|
-
messages: $bundle.data ?? {},
|
|
515
|
-
fallback: "en"
|
|
438
|
+
// Drop zone using HTML5 drag-and-drop
|
|
439
|
+
OnMouse(Card([Text("Drop files here")]), {
|
|
440
|
+
dragOver: e => e.preventDefault(),
|
|
441
|
+
drop: e => { e.preventDefault(); $files = e.dataTransfer.files }
|
|
516
442
|
})
|
|
517
443
|
|
|
518
|
-
|
|
519
|
-
Text(
|
|
444
|
+
// Apply a class / inline style without breaking out of the component
|
|
445
|
+
Css(Card([Text("Highlighted")]), { class: "highlight", style: "border-color: #f59e0b;" })
|
|
446
|
+
|
|
447
|
+
// Router-aware anchor wrapping any node
|
|
448
|
+
Link(PersonChip("Ada Lovelace"), { to: "/people/ada" })
|
|
520
449
|
```
|
|
521
450
|
|
|
522
|
-
- `
|
|
523
|
-
|
|
524
|
-
- `
|
|
525
|
-
-
|
|
526
|
-
|
|
451
|
+
- `OnClick(child, { onClick, disabled?, stopPropagation? })` — touch + mouse + keyboard (Enter/Space) activatable.
|
|
452
|
+
- `OnMouse(child, { enter?, leave?, hover?, move?, down?, up?, click?, doubleClick?, contextMenu?, scroll?, wheel?, drag?, drop?, dragStart?, dragEnd?, dragEnter?, dragLeave?, dragOver?, draggable?, passiveScroll? })` — pass only the events you need.
|
|
453
|
+
- `OnKeyboard(child, { onKeyDown?, onKeyUp?, onKeyPress?, focusable? })`.
|
|
454
|
+
- `OnFocus(child, { onFocus?, onBlur? })` — uses bubbling `focusin`/`focusout`.
|
|
455
|
+
- `OnIntersect(child, { onEnter?, onLeave?, onChange?, threshold?, rootMargin?, once? })` — IntersectionObserver wrapper.
|
|
456
|
+
- `Css(child, { style?, class? })` — last-resort raw CSS class/style merge.
|
|
457
|
+
- `Link(child_or_label, { to?, href?, external?, variant? })` — anchor primitive; `to` for router nav, `href`+`external: true` for outbound links.
|
|
458
|
+
|
|
459
|
+
Don't wrap a `Button` in `OnClick` — `Button` already exposes `onClick`. Use `OnClick` for clickable cards / list rows / custom layouts.
|
|
527
460
|
|
|
528
|
-
##
|
|
461
|
+
## Escape hatches — `HTMLTag` & `Styles`
|
|
529
462
|
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
463
|
+
Use only when the standard catalogue cannot express the markup or styling you need.
|
|
464
|
+
|
|
465
|
+
- `HTMLTag(tag, { attributes?, children? })` — render an allow-listed HTML tag. `on*` attributes, `javascript:` URLs, and unsafe `style` patterns are stripped; tag names outside the allow-list collapse to `div`.
|
|
466
|
+
- `Styles(css)` — inject a `<style>` block. Payloads containing `</style>`, `<script>`, `expression(`, `javascript:`, `behavior:`, or `@import` are dropped.
|
|
467
|
+
|
|
468
|
+
```
|
|
469
|
+
aktion = Column([
|
|
470
|
+
Styles(`.hero-callout { background: linear-gradient(135deg, #6366f1, #10b981); color: white; padding: 24px; border-radius: 12px; }`),
|
|
471
|
+
HTMLTag("div", { attributes: { class: "hero-callout" }, children: [
|
|
472
|
+
HTMLTag("h2", { children: [Text("Custom block")] }),
|
|
473
|
+
Text("Use these only when the standard library cannot capture the design.")
|
|
474
|
+
]})
|
|
475
|
+
])
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
## Theming, i18n & icons
|
|
479
|
+
|
|
480
|
+
### `theme = $theme({ ... })`
|
|
481
|
+
Assign before `aktion` to brand the response. Tokens use the structured form — top-level groups `colors`, `radius`, `font`, `motion`, `elevation` (plus metadata: `name`, `direction`). Removing the line snaps the UI back to the host theme.
|
|
533
482
|
|
|
534
483
|
```
|
|
535
|
-
theme =
|
|
536
|
-
colors: {
|
|
537
|
-
primary: "#635bff",
|
|
538
|
-
bg: "#0a0a23",
|
|
539
|
-
surface: "#10103a",
|
|
540
|
-
text: "#ffffff"
|
|
541
|
-
},
|
|
484
|
+
theme = $theme({
|
|
485
|
+
colors: { primary: "#635bff", bg: "#0a0a23", surface: "#10103a", text: "#fff" },
|
|
542
486
|
radius: { md: "0.5rem", button: "999px" },
|
|
543
487
|
font: { family: "Inter, sans-serif", familyHeading: "Inter, sans-serif" }
|
|
544
488
|
})
|
|
545
|
-
_app_ = AppShell(...)
|
|
546
489
|
```
|
|
547
490
|
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
491
|
+
The host page picks one of seven base themes (`light`, `dark`, `neon`, `pastel`, `glass`, `brutalist`, `skyline`) via the `theme` attribute. Authored programs should be theme-neutral by default — pass `tone:` / `variant:` instead of hard-coded colours.
|
|
492
|
+
|
|
493
|
+
### i18n
|
|
494
|
+
```
|
|
495
|
+
const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({
|
|
496
|
+
defaultLanguage: "en",
|
|
497
|
+
currentLanguage: "fr",
|
|
498
|
+
translations: {
|
|
499
|
+
greeting: { en: "Hello, {name}!", fr: "Bonjour, {name}!" },
|
|
500
|
+
items_count: { en: "{count} items", fr: "{count} objets" }
|
|
501
|
+
}
|
|
502
|
+
})
|
|
503
|
+
welcome = Text(t("greeting", { name: $user.name }))
|
|
504
|
+
```
|
|
505
|
+
`t(key, vars?)` looks up `translations[key][currentLanguage]`, falls back to `translations[key][defaultLanguage]`, then to the bare key. Placeholders use `{name}` syntax. Drive `currentLanguage` from a `$state` atom (e.g. `currentLanguage: $lang`) for reactive language switching, or call `setCurrentLanguage(next)` on the bundle.
|
|
506
|
+
|
|
507
|
+
### Icons
|
|
508
|
+
Icon-typed props expect a Font Awesome name as a string — no `fa-` prefix, NEVER an emoji character.
|
|
509
|
+
|
|
510
|
+
- `"name"` defaults to the solid set: `"house"`, `"chart-line"`, `"star"`.
|
|
511
|
+
- `"regular:name"` for the outline set; `"brands:name"` for brand logos.
|
|
512
|
+
- `Icon(name, { variant?, size? })` renders a standalone glyph (`size` ∈ `xs|sm|md|lg|xl`).
|
|
513
|
+
|
|
514
|
+
## `$util` — runtime helper namespace
|
|
515
|
+
|
|
516
|
+
Pure helpers — no side effects. `$util` is a global available inside every Aktion expression, action body, effect, and lambda. Library consumers can call the same methods from JavaScript (`import { Util } from "aktion"`).
|
|
517
|
+
|
|
518
|
+
Reach for `$util` when native JavaScript would be verbose (formatting, date math, grouping). Prefer plain JS where it is just as clear: `arr.length` over `$util.count(arr)`, `a.filter(x => x.done)` over `$util.filter(a, "done", "==", true)`.
|
|
519
|
+
|
|
520
|
+
### Collections
|
|
521
|
+
- `$util.count(arr)` — length / object key count.
|
|
522
|
+
- `$util.sum(arr)` / `$util.avg(arr)` / `$util.min(arr)` / `$util.max(arr)` — numeric reductions.
|
|
523
|
+
- `$util.first(arr)` / `$util.last(arr)` — endpoints (safe on empty arrays).
|
|
524
|
+
- `$util.filter(arr, field, op, value)` — declarative filter (`op` ∈ `==`, `!=`, `<`, `<=`, `>`, `>=`, `contains`, `startsWith`, `endsWith`).
|
|
525
|
+
- `$util.find(arr, field, op, value)` — first match.
|
|
526
|
+
- `$util.sort(arr, field, dir?)` — stable sort (`dir` ∈ `"asc"` | `"desc"`).
|
|
527
|
+
- `$util.groupBy(arr, field)` — `{ [key]: items[] }`.
|
|
528
|
+
- `$util.unique(arr, field?)` / `$util.reverse(arr)` / `$util.slice(arr, start, end?)` / `$util.pick(obj, ["a", "b"])`.
|
|
529
|
+
- `$util.range(start, end, step?)` — inclusive numeric range.
|
|
530
|
+
- `$util.repeat(value, count)` — fixed-length array.
|
|
531
|
+
- `$util.join(arr, sep?)` — string join.
|
|
532
|
+
|
|
533
|
+
### Strings
|
|
534
|
+
- `$util.capitalize(s)` / `$util.lowercase(s)` / `$util.uppercase(s)` / `$util.titlecase(s)` / `$util.case(s, mode)`.
|
|
535
|
+
- `$util.split / .trim / .replace / .substring / .startsWith / .endsWith / .contains / .match`.
|
|
536
|
+
- `$util.plural(n, singular, plural)` — picks the right word for a count.
|
|
537
|
+
|
|
538
|
+
### Formatting
|
|
539
|
+
- `$util.format(value, mode, opts?)` — numbers, currency, percent, compact (`{ currency, locale, decimals }`).
|
|
540
|
+
- `$util.formatDate(value, mode, opts?)` — `"short"` | `"long"` | `"time"` | `"relative"` | token strings (`"YYYY-MM-DD"`).
|
|
551
541
|
|
|
552
|
-
|
|
542
|
+
### Dates
|
|
543
|
+
- `$util.now()` / `$util.today()` / `$util.addDays(date, n)` / `$util.addHours(date, n)` / `$util.diffDays(a, b)` / `$util.startOfWeek(date)` / `$util.endOfMonth(date)`.
|
|
553
544
|
|
|
554
|
-
|
|
555
|
-
|
|
545
|
+
### Math
|
|
546
|
+
- `$util.round / .floor / .ceil / .abs / .clamp(v, min, max) / .pow / .sqrt / .random / .log`.
|
|
556
547
|
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
(
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
548
|
+
The namespace is open for extension — new helpers may be added over time.
|
|
549
|
+
|
|
550
|
+
```
|
|
551
|
+
filtered = $users.filter((u) => u.team === $team)
|
|
552
|
+
sorted = $util.sort(filtered, "joinedAt", "desc")
|
|
553
|
+
firstFive = sorted.slice(0, 5)
|
|
554
|
+
summary = `${rows.length} ${$util.plural(rows.length, "order", "orders")}: ${$util.format($util.sum(rows.amount), "currency")}`
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
## Standard helper components
|
|
558
|
+
|
|
559
|
+
| Component | Purpose |
|
|
560
|
+
|---|---|
|
|
561
|
+
| `Async(resource, { loading, error, empty, data })` | Branch on an `$http({...})` resource state. |
|
|
562
|
+
| `Show(when, { fallback?, children })` | Sugar for `when ? children : fallback`. |
|
|
563
|
+
| `Portal(children, { target? })` | Render outside the parent subtree. |
|
|
564
|
+
| `Redirect(path)` | Navigate and unmount the rest of the subtree. |
|
|
565
|
+
| `Lazy(loader, { fallback?, children })` | Defer rendering until `loader` resolves. |
|
|
566
|
+
| `ErrorBoundary(children, { fallback?, onError? })` | Catch render errors thrown by descendants. |
|
|
567
|
+
| `VirtualList(items, { key, render })` | Virtualised list — preferred for >100 rows. |
|
|
564
568
|
|
|
565
569
|
## Component library
|
|
566
|
-
Use only these components. Each signature lists props in declaration order; optional props end with `?`. The prop tagged `(positional)` is the canonical positional slot — pass it bare; every other prop
|
|
570
|
+
Use only these components. Each signature lists props in declaration order; optional props end with `?`. The prop tagged `(positional)` is the canonical positional slot — pass it bare; every other prop goes in a trailing `{ prop: value }` object.
|
|
567
571
|
|
|
568
572
|
### Layout
|
|
569
|
-
-
|
|
570
|
-
-
|
|
571
|
-
-
|
|
573
|
+
- Column(children: Node[], gap?: "xs"|"s"|"m"|"l"|"xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", wrap?: boolean, reverse?: boolean, padding?: "xs"|"s"|"m"|"l"|"xl", inline?: boolean) — Lay children out vertically (top → bottom) with even spacing — the most common page/section layout. Children stretch to the full width by default; set `align` to `start`/`center`/`end` to change that. This is the recommended root container for a page or a card body.
|
|
574
|
+
- Row(children: Node[], gap?: "xs"|"s"|"m"|"l"|"xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", grow?: boolean, wrap?: boolean, reverse?: boolean, padding?: "xs"|"s"|"m"|"l"|"xl", inline?: boolean, alignContent?: "start"|"center"|"end"|"between"|"around"|"stretch") — Lay children out horizontally (left → right) with even spacing. The developer-friendly default: children keep their natural width and are vertically centered. Set `grow=true` to make children share the row equally (for equal-width columns prefer `Grid(columns: N)`); drop a `Spacer()` between children to push them apart; wrap a child in `StackItem` for per-child grow/shrink/alignment. Use `wrap=true` for chips/tags that should flow onto multiple lines.
|
|
575
|
+
- Center(children: Node[], axis?: "both"|"horizontal"|"vertical", minHeight?: string, gap?: "xs"|"s"|"m"|"l"|"xl", padding?: "xs"|"s"|"m"|"l"|"xl", inline?: boolean) — Centers its children on both axes — the easy way to drop a spinner, an empty state, a hero call-to-action, or a modal body into the middle of a region. Give it `minHeight` (e.g. `"60vh"`) to center vertically inside a tall area, or `axis` to center on only one axis. Multiple children stack in a column and are centered as a group.
|
|
576
|
+
- Stack(children: Node[], direction?: "column"|"row", gap?: "xs"|"s"|"m"|"l"|"xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", alignContent?: "start"|"center"|"end"|"between"|"around"|"stretch", wrap?: boolean, reverse?: boolean, uniform?: boolean, inline?: boolean, padding?: "xs"|"s"|"m"|"l"|"xl") — Low-level flex container with a configurable, optionally responsive `direction`. Reach for `Row` or `Column` first — they are clearer for fixed-direction layouts. Use `Stack` when the direction itself must change across breakpoints, e.g. `direction: {base: "column", md: "row"}` for a sidebar that stacks on mobile. `gap`, `align`, `justify`, and `padding` also accept responsive maps. NOTE: a `row` Stack grows its children equally by default (`uniform=true`); set `uniform=false` for natural widths (this is `Row`'s default).
|
|
577
|
+
- StackItem(child: Node, grow?: number, shrink?: number, basis?: string, alignSelf?: "start"|"center"|"end"|"stretch", order?: number, minWidth?: string, maxWidth?: string) — Per-child flex control inside a `Row`, `Column`, or `Stack`. Wraps one child so it can `grow` to fill leftover space, `shrink`, set a `basis`, override `alignSelf`, or change visual `order` — the building block for asymmetric rows like `Row([StackItem(searchInput, { grow: 1 }), saveButton])` (input expands, button hugs).
|
|
578
|
+
- Grid(children: Node[], columns?: number | object, gap?: "xs"|"s"|"m"|"l"|"xl", rowGap?: "xs"|"s"|"m"|"l"|"xl", columnGap?: "xs"|"s"|"m"|"l"|"xl", minChildWidth?: string, alignItems?: "start"|"center"|"end"|"stretch", justifyItems?: "start"|"center"|"end"|"stretch", dense?: boolean) — Two-dimensional grid with three modes:
|
|
579
|
+
1. AUTO-FIT (default, no `columns`): wraps as many equal columns as fit, each at least `minChildWidth` wide (default 220px) — perfect for card/KPI grids that should reflow on their own.
|
|
580
|
+
2. FIXED (`columns: N`, 1–12): exactly N equal columns.
|
|
581
|
+
3. SPAN (`columns: 12` or any `GridItem` children): a 12-track grid where each `GridItem` sets its own `span` (a number 1–12 or a fraction like `"1/3"`) for dashboards and asymmetric layouts.
|
|
582
|
+
`columns` and `gap` accept responsive maps like `{base: 1, md: 2, lg: 4}`.
|
|
572
583
|
- GridItem(child: Node, span?: number | string, offset?: number, spanAt?: object) — Wraps a child in a 12-column grid cell with `span`, `offset`, and responsive `spanAt` maps. Parent `Grid` auto-enables 12-column mode when any child is a `GridItem`. Fraction spans like `"1/3"` resolve against the 12-column track.
|
|
573
584
|
- Box(children: Node[], padding?: "xs"|"s"|"m"|"l"|"xl", margin?: "xs"|"s"|"m"|"l"|"xl", border?: "none"|"subtle"|"default", background?: "none"|"surface"|"muted"|"primary"|"success"|"warning"|"danger"|"info", maxWidth?: string) — Spacing and surface wrapper for padding, margin, borders, semantic backgrounds, and max-width constraints. Use when a `Card` is too heavy but the content needs a subtle surface or inset.
|
|
574
585
|
- Container(children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", maxWidth?: string, padding?: "none"|"s"|"m"|"l") — Centered, max-width content wrapper. Use when a page is wider than comfortable reading width — landing pages, marketing sections, long documents. Picks a sensible default max-width per size; pass `maxWidth` to override with any CSS value.
|
|
@@ -577,12 +588,12 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
577
588
|
- CardHeader(title: string, subtitle?: string) — Card header with title and optional subtitle.
|
|
578
589
|
- CardFooter(children: Node[]) — Card footer for actions.
|
|
579
590
|
- Separator(orientation?: "horizontal"|"vertical", label?: string, decorative?: boolean) — Visual divider between content sections. Supports horizontal or vertical orientation, and an optional center `label` (lifted from the legacy `Divider`). Use `decorative=false` to expose the separator to assistive tech.
|
|
580
|
-
- Tabs(items: TabItem[], defaultValue?: string, orientation?: "horizontal"|"vertical") — Tabbed container. Children must be TabItem components. Supports `orientation="vertical"` for sidebar-style tabs and built-in keyboard navigation (←/→ or ↑/↓, Home, End).
|
|
591
|
+
- Tabs(items: TabItem[], defaultValue?: string, orientation?: "horizontal"|"vertical", onChange?: callable) — Tabbed container. Children must be TabItem components. Supports `orientation="vertical"` for sidebar-style tabs and built-in keyboard navigation (←/→ or ↑/↓, Home, End). Provide `onChange` to react when the user switches tabs (called with the new tab's value).
|
|
581
592
|
- TabItem(value: string, label: string, children: Node[], badge?: string, icon?: string) — Single tab definition (used inside Tabs). Add `badge` for a count chip in the tab trigger, and `icon` for a leading Font Awesome icon.
|
|
582
|
-
- Accordion(items: AccordionItem[]) — Accordion container. Children must be AccordionItem components.
|
|
583
|
-
- AccordionItem(title: string, children: Node[], open?: boolean) — Single accordion section.
|
|
584
|
-
- Modal(title: string, open: boolean, children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", footer?: Node[], closable?: boolean, closeOnBackdrop?: boolean) — Dialog overlay shown when `open` is true. Pass a `$variable` as `open` to control it. The header always renders a × close button (disable via `closable: false`); the optional `footer` slot is the canonical place for action buttons. `closeOnBackdrop=true` opts in to backdrop-click dismissal.
|
|
585
|
-
- Drawer(title: string, open: boolean, children: Node[], side?: "right"|"left"|"top"|"bottom", footer?: Node[]) — Side drawer overlay shown when `open` is true. Pass a `$variable` as `open` to control it. Choose `side` for slide direction (default right).
|
|
593
|
+
- Accordion(items: AccordionItem[], showArrow?: boolean) — Accordion container. Children must be AccordionItem components. Set `showArrow: true` to add a chevron indicator to every item; individual `AccordionItem`s can override via their own `showArrow` prop.
|
|
594
|
+
- AccordionItem(title: string, children: Node[], open?: boolean, showArrow?: boolean) — Single accordion section.
|
|
595
|
+
- Modal(title: string, open: boolean, children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", footer?: Node[], closable?: boolean, closeOnBackdrop?: boolean, onClose?: callable) — Dialog overlay shown when `open` is true. Pass a `$variable` as `open` to control it. The header always renders a × close button (disable via `closable: false`); the optional `footer` slot is the canonical place for action buttons. `closeOnBackdrop=true` opts in to backdrop-click dismissal. `onClose` fires every time the modal closes (× button, backdrop, programmatic state write).
|
|
596
|
+
- Drawer(title: string, open: boolean, children: Node[], side?: "right"|"left"|"top"|"bottom", footer?: Node[], onClose?: callable) — Side drawer overlay shown when `open` is true. Pass a `$variable` as `open` to control it. Choose `side` for slide direction (default right). `onClose` fires whenever the drawer is dismissed (× button or backdrop click).
|
|
586
597
|
- Steps(items: object[]) — Numbered step-by-step guide. Pass items as `{title, details?, active?}` objects. Use `active` to mark the current step in a multi-step flow.
|
|
587
598
|
- AspectRatio(ratio: string, children: Node[]) — Container that constrains its child to a fixed aspect ratio (e.g. 16:9 for video embeds, 1:1 for thumbnails). The child fills the box.
|
|
588
599
|
- ScrollArea(children: Node[], maxHeight?: string, direction?: "vertical"|"horizontal"|"both") — Bounded scroll container. Use to clip long lists / logs / chat panels to a fixed max height with a clean scrollbar.
|
|
@@ -590,24 +601,9 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
590
601
|
- ResizablePanels(primary: Node[], secondary: Node[], initialPrimaryWidth?: string, minPrimaryWidth?: string) — Two-pane horizontal split with a draggable divider. The user can drag the divider to resize the primary pane; defaults respect the starting width. Use for code editors, file browsers, master/detail layouts that need user-controllable proportions.
|
|
591
602
|
- MasonryGrid(items: Node[], columns?: number, gap?: "xs"|"s"|"m"|"l"|"xl") — Pinterest-style column grid. Children flow into columns that reflow on viewport changes. Use for galleries, social-style feeds, and mixed-height card walls. Prefer `Grid` when children should share the same height per row.
|
|
592
603
|
|
|
593
|
-
- `root` MUST be `Stack(...)` and contain at least one child.
|
|
594
|
-
- Wrap each major chunk of content in a `Card(...)` for visual grouping.
|
|
595
|
-
- Prefer `Grid(...)` over `Stack` with `direction="row" wrap=true` when children should size uniformly (KPIs, feature tiles, card grids).
|
|
596
|
-
- Use `Container(children, size?)` to centre a wide page within a comfortable max-width (landing pages, articles, marketing sections).
|
|
597
|
-
- Use `Spacer()` inside `Stack(direction="row")` to push the next item to the far edge; pass a `size` for an explicit fixed gap.
|
|
598
|
-
- Use `Separator(orientation?, label?)` between sections to add visual breaks. Pass a `label` for a centered "OR"-style separator.
|
|
599
|
-
- Use `Drawer` for side-panel detail views, `Modal` for centered dialogs.
|
|
600
|
-
- Use `Sticky(children, side?, offset?)` to pin a toolbar/banner while the surrounding content scrolls.
|
|
601
|
-
- Use `ResizablePanels(primary, secondary, initialPrimaryWidth?)` for user-resizable two-pane layouts (code editors, file browsers).
|
|
602
|
-
- Use `MasonryGrid([...])` for Pinterest-style mixed-height card walls — prefer `Grid` when rows should share a height.
|
|
603
|
-
- Use `StackItem(child, grow?, shrink?, basis?, alignSelf?)` inside `Stack(direction="row", uniform=false)` for toolbars.
|
|
604
|
-
- Use `Grid(columns: 12, [GridItem(child, span: "1/4"), GridItem(main, span: "3/4")])` for sidebar layouts; fractional spans `"1/2"`…`"1/12"` resolve on a 12-column track.
|
|
605
|
-
- Use `Box(children, padding?, margin?, border?, background?)` for spacing and surfaces without raw CSS.
|
|
606
|
-
|
|
607
604
|
### Content
|
|
608
605
|
- Text(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", style?: string) — Renders plain text with a typographic variant. Optional `style` prop accepts a CSS declaration string (e.g. "font-size: 16px; color: #000;") applied directly to the rendered element.
|
|
609
606
|
- Image(src: string, alt?: string, caption?: string, ratio?: string, fit?: "cover"|"contain"|"fill"|"none"|"scale-down", fallback?: string) — Inline image. `ratio` constrains the box to a fixed aspect ratio (e.g. `16:9`, `1:1`) so callers do not need an outer `AspectRatio`. `fit` controls how the image fills that box. When `src` is missing or unsafe the component renders a placeholder (or `fallback` text/icon).
|
|
610
|
-
- Link(label: string, href: string, external?: boolean) — Anchor link.
|
|
611
607
|
- Badge(label: string (positional), tone?: "neutral"|"primary"|"success"|"warning"|"danger"|"info", icon?: string, size?: "xs"|"sm"|"md"|"lg"|"xl") — Small pill-style tag for status, counts, categories. Accepts an optional leading `icon` and a `size`.
|
|
612
608
|
- BadgeList(labels: string[] (positional), tone?: "neutral"|"primary"|"success"|"warning"|"danger"|"info", size?: "xs"|"sm"|"md"|"lg"|"xl") — Cluster of Badge pills rendered from an array of strings.
|
|
613
609
|
- Callout(tone?: "neutral"|"info"|"success"|"warning"|"danger"|"error", title: string (positional), description?: string, icon?: string, compact?: boolean) — Highlighted callout banner with variant, title, description, and leading icon. Pass `compact: true` for a one-line inline-note rendering.
|
|
@@ -617,119 +613,67 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
617
613
|
- Spinner(size?: "xs"|"sm"|"md"|"lg"|"xl", label?: string, tone?: "default"|"neutral"|"primary"|"success"|"warning"|"danger"|"info") — Indeterminate inline loader. Use for tiny loading states inside buttons, toolbars, table cells, or chat bubbles where `Skeleton` and `Progress(indeterminate=true)` are too heavy. Pass `label` to render an inline caption beside the spinner (also announced via `aria-label`).
|
|
618
614
|
- Markdown(content: string) — Render markdown-flavoured text. Supports **bold**, *italic*, `code`, headings (`#`/`##`/`###`), blockquotes (`>`), bullet (`-`/`*`) and numbered (`1.`) lists, fenced code blocks (```), images (``), inline links, and auto-linked bare URLs. Multi-line paragraphs collapse into `<p>` blocks.
|
|
619
615
|
- Kbd(keys: string | string[], size?: "sm"|"md") — Renders a keyboard shortcut chip (e.g. `Cmd+K`). Pass a single label, or multiple labels as an array to render a `key + key + …` combo.
|
|
620
|
-
- Icon(name: string, variant?: "solid"|"regular"|"brands", size?: "xs"|"sm"|"md"|"lg"|"xl") — Single Font Awesome icon. `name` is the FA name without the `fa-` prefix (e.g. `"house"`, `"chart-line"`). Use `variant` for non-solid styles (`regular`/`brands`) or prefix the name (`"regular:star"`).
|
|
621
|
-
|
|
622
|
-
- Prefer `Markdown(...)` for rich paragraph text with inline formatting — the parser supports headings, blockquotes, fenced code, numbered/bullet lists, links, images, and bare-URL auto-linking.
|
|
623
|
-
- Use `Callout(variant, title, description, icon?, compact?)` for highlighted notices; pass `compact: true` for a one-line inline note.
|
|
624
|
-
- Use `Quote(text, cite?)` for inline pull-quotes inside articles and marketing sections (use `Testimonial` when you also have author/role/rating).
|
|
625
|
-
- Use `CodeBlock(language, codeString, showLineNumbers?, highlightLines?)` for read-only code snippets. The header always renders a copy-to-clipboard button.
|
|
626
|
-
- Use `Badge(label, variant?, icon?, size?)` for a single pill and `BadgeList(["a","b","c"], variant?, size?)` to render an array of strings as Badge pills.
|
|
627
|
-
- Use `Skeleton(variant?, lines?, height?, shape?, width?)` for loading placeholders; `variant` accepts `paragraph` (default), `card`, `table-row`, `avatar`, `image`.
|
|
628
|
-
- Use `Spinner(size?, label?, tone?)` for tiny inline loading indicators inside buttons, toolbars, or table cells.
|
|
629
|
-
- Use `Image(src, alt?, caption?, ratio?, fit?, fallback?)` — `ratio` (e.g. `"16:9"`) makes the image self-constrain so you do not need an outer `AspectRatio`.
|
|
630
|
-
- Use `Kbd(["Cmd", "K"])` when referring to keyboard shortcuts.
|
|
631
|
-
- Use `Icon(name, variant?, size?)` to render a standalone Font Awesome icon (`name` is the FA name without the `fa-` prefix, e.g. `"house"`, `"chart-line"`, `"regular:star"`, `"brands:github"`).
|
|
632
|
-
- For page-level titles reach for `PageHeader(...)` (top of dashboards/detail pages) or `SectionHeader(...)` (inside a Card). For tiny inline titles use `Text(value, variant="large-heavy")`.
|
|
616
|
+
- Icon(name: string, variant?: "solid"|"regular"|"brands", size?: "xs"|"sm"|"md"|"lg"|"xl", color?: string) — Single Font Awesome icon. `name` is the FA name without the `fa-` prefix (e.g. `"house"`, `"chart-line"`). Use `variant` for non-solid styles (`regular`/`brands`) or prefix the name (`"regular:star"`). `color` accepts any CSS colour (`"#00ff00"`, `"tomato"`, `"var(--rui-color-primary)"`).
|
|
633
617
|
|
|
634
618
|
### Forms
|
|
635
|
-
- Form(id: string, buttons: Buttons | Button, fields: FormControl[]) — Form container. Children FormControls render in order; buttons render at the bottom.
|
|
619
|
+
- Form(id: string, buttons: Buttons | Button, fields: FormControl[], onSubmit?: callable) — Form container. Children FormControls render in order; buttons render at the bottom. Provide `onSubmit` to handle form submission (invoked when the user presses Enter on a focused input or clicks a `type="submit"` Button inside the form).
|
|
636
620
|
- FormControl(label: string, field: Node, hint?: string) — Labeled wrapper around a single form field.
|
|
637
621
|
- FormSection(label: string, children: Node[], helper?: string) — Semantic grouping for related form fields — renders a small heading (`label`), optional helper paragraph, and stacks the children with consistent spacing. Use INSTEAD of wrapping fields in `Card` + `SectionHeader` by hand. Pair with `FieldSet` when the group is a true `<fieldset>` (radio sets, checkbox groups).
|
|
638
622
|
- FieldSet(legend: string, children: Node[], helper?: string, disabled?: boolean) — Native `<fieldset>`/`<legend>` wrapper for accessible grouping of related controls. Use when assistive tech should announce the wrapper (radio sets, checkbox groups). For purely visual grouping prefer `FormSection`.
|
|
639
623
|
- ValidationSummary(errors: any[], title?: string, tone?: "danger"|"warning") — Aggregate error list rendered at the top of a form. Pass `errors` as `{label?, message, field?}` objects or plain strings. Pair with individual field hints via `FormControl(hint=...)`.
|
|
640
|
-
- Input(id: string, placeholder?: string, type?: "text"|"email"|"password"|"number"|"tel"|"url"|"date", validations?: any, value?: any) — Text input field. Pass a $variable as `value` for two-way binding.
|
|
641
|
-
- TextArea(id: string, placeholder?: string, rows?: number, value?: any) — Multi-line text input.
|
|
642
|
-
- PasswordInput(id: string, value?: string, placeholder?: string, label?: string, strengthMeter?: boolean, disabled?: boolean) — Password input with a show/hide toggle and an optional strength meter. Pass a `$variable` as `value` for two-way binding. Set `strengthMeter=true` to render a 4-step indicator and label.
|
|
643
|
-
- MaskedInput(id: string, mask: string, value?: string, placeholder?: string, label?: string, disabled?: boolean) — Text input with an inline mask — `9` matches a digit, `A` matches a letter, `*` matches any character, every other character is a fixed delimiter. Useful for phone numbers, postal codes, credit cards. Pass `mask` (e.g. `"(999) 999-9999"`) and a `$variable` as `value`.
|
|
644
|
-
- MentionInput(id: string, people: any[], value?: string, placeholder?: string, rows?: number, disabled?: boolean) — Multi-line input with inline @-mention suggestions. Typing `@` opens a popover listing the provided `people` (filtered by what follows). Selecting an option inserts `@label` into the text. Pass a `$variable` as `value` for two-way binding. Use for comments, task notes, chat composers.
|
|
645
|
-
- TagInput(id: string, value?: string[], placeholder?: string, label?: string, max?: number, disabled?: boolean) — Tag/chip input — type a value, press Enter (or comma) to commit, click × on a chip to remove. Pass a `$variable` (array of strings) as `value` for two-way binding. Use for keywords, recipients, labels, skills, allowlists.
|
|
646
|
-
- Select(id: string, items: SelectItem[], label?: string, placeholder?: string, value?: any, searchable?: boolean) — Dropdown select. Pass a `$variable` as `value` for two-way binding. Set `searchable: true` for a combobox-style filter UI on long option lists.
|
|
624
|
+
- Input(id: string, placeholder?: string, type?: "text"|"email"|"password"|"number"|"tel"|"url"|"date", validations?: any, value?: any, onChange?: callable) — Text input field. Pass a $variable as `value` for two-way binding. `onChange(value)` fires on every keystroke with the current string.
|
|
625
|
+
- TextArea(id: string, placeholder?: string, rows?: number, value?: any, onChange?: callable) — Multi-line text input. `onChange(value)` fires on every keystroke with the current text.
|
|
626
|
+
- PasswordInput(id: string, value?: string, placeholder?: string, label?: string, strengthMeter?: boolean, disabled?: boolean, onChange?: callable) — Password input with a show/hide toggle and an optional strength meter. Pass a `$variable` as `value` for two-way binding. Set `strengthMeter=true` to render a 4-step indicator and label.
|
|
627
|
+
- MaskedInput(id: string, mask: string, value?: string, placeholder?: string, label?: string, disabled?: boolean, onChange?: callable) — Text input with an inline mask — `9` matches a digit, `A` matches a letter, `*` matches any character, every other character is a fixed delimiter. Useful for phone numbers, postal codes, credit cards. Pass `mask` (e.g. `"(999) 999-9999"`) and a `$variable` as `value`.
|
|
628
|
+
- MentionInput(id: string, people: any[], value?: string, placeholder?: string, rows?: number, disabled?: boolean, onChange?: callable) — Multi-line input with inline @-mention suggestions. Typing `@` opens a popover listing the provided `people` (filtered by what follows). Selecting an option inserts `@label` into the text. Pass a `$variable` as `value` for two-way binding. Use for comments, task notes, chat composers.
|
|
629
|
+
- TagInput(id: string, value?: string[], placeholder?: string, label?: string, max?: number, disabled?: boolean, onChange?: callable) — Tag/chip input — type a value, press Enter (or comma) to commit, click × on a chip to remove. Pass a `$variable` (array of strings) as `value` for two-way binding. Use for keywords, recipients, labels, skills, allowlists.
|
|
630
|
+
- Select(id: string, items: SelectItem[], label?: string, placeholder?: string, value?: any, searchable?: boolean, onChange?: callable) — Dropdown select. Pass a `$variable` as `value` for two-way binding. Set `searchable: true` for a combobox-style filter UI on long option lists. `onChange(value)` fires with the newly-selected value.
|
|
647
631
|
- SelectItem(value: string, label: string) — Single option for a Select component.
|
|
648
|
-
- Combobox(id: string, items: SelectItem[], value?: string, placeholder?: string, emptyLabel?: string, disabled?: boolean, open?: boolean) — Searchable single-select dropdown — type to filter, click an option to choose. Use instead of `Select` when the list is long enough that scanning is faster than scrolling (countries, currencies, repos, users). Pass a `$variable` as `value` for two-way binding; the selected option's `value` is written to state on pick.
|
|
649
|
-
- MultiSelect(id: string, items: SelectItem[], value?: any[], placeholder?: string, emptyLabel?: string, max?: number, disabled?: boolean, open?: boolean) — Multi-option searchable dropdown. Type to filter, click an option to add/remove it from the bound array. Renders the selected options as removable chips inside the trigger. Pass a `$variable` (array of values) as `value` for two-way binding.
|
|
650
|
-
- Checkbox(id: string, label: string, value?: boolean) — Boolean checkbox.
|
|
651
|
-
- CheckBoxGroup(name: string, items: CheckBoxItem[], value?: any) — Group of checkboxes. Value is an object keyed by item name. Pass a `$variable` for two-way binding.
|
|
632
|
+
- Combobox(id: string, items: SelectItem[], value?: string, placeholder?: string, emptyLabel?: string, disabled?: boolean, open?: boolean, onChange?: callable) — Searchable single-select dropdown — type to filter, click an option to choose. Use instead of `Select` when the list is long enough that scanning is faster than scrolling (countries, currencies, repos, users). Pass a `$variable` as `value` for two-way binding; the selected option's `value` is written to state on pick.
|
|
633
|
+
- MultiSelect(id: string, items: SelectItem[], value?: any[], placeholder?: string, emptyLabel?: string, max?: number, disabled?: boolean, open?: boolean, onChange?: callable) — Multi-option searchable dropdown. Type to filter, click an option to add/remove it from the bound array. Renders the selected options as removable chips inside the trigger. Pass a `$variable` (array of values) as `value` for two-way binding.
|
|
634
|
+
- Checkbox(id: string, label: string, value?: boolean, onChange?: callable) — Boolean checkbox. `onChange(checked)` fires with the new boolean state.
|
|
635
|
+
- CheckBoxGroup(name: string, items: CheckBoxItem[], value?: any, onChange?: callable) — Group of checkboxes. Value is an object keyed by item name. Pass a `$variable` for two-way binding. `onChange(value)` fires with the full updated object.
|
|
652
636
|
- CheckBoxItem(label: string, name: string, description?: string, defaultChecked?: boolean) — Single option inside a CheckBoxGroup.
|
|
653
|
-
- Radio(id: string, items: SelectItem[], value?: any) — Radio button group.
|
|
654
|
-
- Switch(id: string, label?: string, value?: boolean, description?: string, disabled?: boolean) — Compact on/off toggle. Pass a `$variable` as `value` for two-way binding — prefer Switch over Checkbox when the control represents a setting.
|
|
655
|
-
- ToggleGroup(id: string, items: any[], value?: any, variant?: "default"|"outline", size?: "sm"|"md"|"lg") — Group of mutually-exclusive Toggle-style buttons (single-select). Items are `[value, label]` arrays, `{value, label, icon?}` objects, or plain strings (used for both value and label). Pass a `$variable` as `value` for two-way binding.
|
|
656
|
-
- Button(label: string,
|
|
637
|
+
- Radio(id: string, items: SelectItem[], value?: any, onChange?: callable) — Radio button group. `onChange(value)` fires with the newly-selected option value.
|
|
638
|
+
- Switch(id: string, label?: string, value?: boolean, description?: string, disabled?: boolean, onChange?: callable) — Compact on/off toggle. Pass a `$variable` as `value` for two-way binding — prefer Switch over Checkbox when the control represents a setting. `onChange(checked)` fires with the new boolean.
|
|
639
|
+
- ToggleGroup(id: string, items: any[], value?: any, variant?: "default"|"outline", size?: "sm"|"md"|"lg", onChange?: callable) — Group of mutually-exclusive Toggle-style buttons (single-select). Items are `[value, label]` arrays, `{value, label, icon?}` objects, or plain strings (used for both value and label). Pass a `$variable` as `value` for two-way binding. `onChange(value)` fires with the newly-selected value.
|
|
640
|
+
- Button(label: string, onClick?: callable, variant?: "primary"|"secondary"|"ghost"|"danger", type?: "button"|"submit", size?: "xs"|"sm"|"md"|"lg"|"xl"|"small"|"normal"|"large", icon?: string, iconPosition?: "leading"|"trailing", iconOnly?: boolean, loading?: boolean, fullWidth?: boolean, disabled?: boolean) — Clickable button. `onClick` (a callable) runs when the user presses the button. The legacy `action` prop is an alias and is still accepted.
|
|
657
641
|
- Buttons(items: Button[], direction?: "row"|"column") — Group of buttons laid out horizontally or vertically.
|
|
658
|
-
- SearchBar(id: string, placeholder?: string, value?: string, shortcut?: string,
|
|
659
|
-
- Slider(id: string, min?: number, max?: number, step?: number, value?: number, label?: string, showValue?: boolean, disabled?: boolean) — Range slider for selecting a single numeric value between `min` and `max`. Pass a `$variable` as `value` for two-way binding. Useful for filters, settings (volume, brightness), and parameter tuning.
|
|
660
|
-
- NumberInput(id: string, value?: number, min?: number, max?: number, step?: number, placeholder?: string, disabled?: boolean) — Numeric input with paired increment/decrement buttons. Use for quantity steppers, integer settings, and any field where a `<input type="number">` plus +/- controls is friendlier than the native spinner. Pass a `$variable` as `value` for two-way binding.
|
|
661
|
-
- ColorPicker(id: string, value?: string, label?: string, swatches?: string[], disabled?: boolean) — Hex / RGB color form control with preset swatches. Pairs a native `<input type="color">` chip with a hex text input and a row of preset swatches. Pass a `$variable` as `value` (hex string, e.g. `"#6366f1"`) for two-way binding. Use for theme builders, label color pickers, and any "pick a color" surface.
|
|
662
|
-
- DatePicker(id: string, value?: string, label?: string, min?: string, max?: string, placeholder?: string, disabled?: boolean) — Date picker that wraps the native `<input type="date">` with consistent styling. Pass a `$variable` as `value` for two-way binding. Use `min`/`max` to bound the selectable range.
|
|
663
|
-
- DateRangePicker(id: string, from?: string, to?: string, label?: string, min?: string, max?: string, disabled?: boolean) — Paired date inputs with a single label, sharing the same min/max range. Pass `$variable` references for both `from` and `to` to two-way-bind a date range (ISO `YYYY-MM-DD` strings).
|
|
664
|
-
- TimePicker(id: string, value?: string, label?: string, min?: string, max?: string, step?: number, disabled?: boolean) — Time-of-day picker that wraps `<input type="time">`. Pass a `$variable` as `value` for two-way binding (HH:MM 24-hour). Set `step` to constrain to specific increments (e.g. 900 for 15-minute buckets).
|
|
665
|
-
- DateTimePicker(id: string, value?: string, label?: string, min?: string, max?: string, step?: number, disabled?: boolean) — Combined date + time picker — wraps `<input type="datetime-local">`. Pass a `$variable` as `value` for two-way binding (ISO `YYYY-MM-DDTHH:MM`).
|
|
666
|
-
- FileUpload(id: string, label?: string, hint?: string, accept?: string, multiple?: boolean,
|
|
667
|
-
- PinInput(id: string, length?: number, value?: string, type?: "numeric"|"alphanumeric", mask?: boolean, disabled?: boolean) — Per-digit PIN entry. Auto-advances focus as the user types and supports paste. Pass a `$variable` as `value` for two-way binding (the bound value is the joined string). Use `type="numeric"` for PINs / 2FA codes, `"alphanumeric"` for invite codes.
|
|
668
|
-
- MultiStepForm(steps: object[], current: number, onSubmit?: callable, prevLabel?: string, nextLabel?: string, submitLabel?: string) — Multi-step / wizard form composite. Renders a `Steps` indicator, the active step's `content`, and Prev/Next buttons that drive a `$variable` for the current 0-indexed step. Use INSTEAD of hand-rolling `Steps` + content + manual prev/next wiring. The submit button is rendered on the final step (override via `submitLabel`).
|
|
669
|
-
|
|
670
|
-
- Each FormControl should be a separate reference for progressive streaming.
|
|
671
|
-
- Pass a `$variable` as the last argument to `Input`, `Select`, `Checkbox`, `Switch`, `MultiSelect`, or `CheckBoxGroup` for two-way binding.
|
|
672
|
-
- Prefer `Switch` over `Checkbox` for settings; use `ToggleGroup` for view-mode pickers and mutually-exclusive filters.
|
|
673
|
-
- Reach for `SearchBar(id, placeholder?, value?, shortcut?)` instead of a raw `Input` whenever the field's purpose is to filter content. It ships with the magnifier icon and keyboard hint baked in.
|
|
674
|
-
- `Slider(id, min?, max?, step?, value?, label?, showValue?)` is the canonical control for numeric ranges (volume, brightness, filters); pass a `$variable` as `value` for two-way binding.
|
|
675
|
-
- `NumberInput(id, value?, min?, max?, step?, placeholder?)` is friendlier than `Input(type="number")` for quantity steppers and integer settings — it ships with +/- buttons that respect `min`/`max`.
|
|
676
|
-
- `DatePicker(id, value?, label?, min?, max?, placeholder?)` wraps the native date picker; pass `value` as a `$variable` for two-way binding (ISO `YYYY-MM-DD`).
|
|
677
|
-
- `DateRangePicker(id, from?, to?, label?, min?, max?)` is the paired-date variant — bind both `from` and `to` to `$variable`s for a single shared range.
|
|
678
|
-
- `Combobox(id, items, value?, placeholder?, emptyLabel?)` is the searchable single-select alternative to `Select` — type to filter long option lists (countries, currencies, users).
|
|
679
|
-
- `MultiSelect(id, items, value?, placeholder?, emptyLabel?, max?)` is the multi-select equivalent — bind a `$variable` array as `value` for two-way binding, the trigger renders the picks as removable chips.
|
|
680
|
-
- `FileUpload(id, label?, hint?, accept?, multiple?, action?)` is the styled file picker; the picked files cannot pass through a `$variable`, so wire the `action` prop to an `action` block (use a `js{ … }` body if you need to read file contents directly).
|
|
681
|
-
- A submit button should call an `action` that awaits the relevant `$mutation` resource, optionally refetches a `$query`, and resets the form `$variable`s (e.g. `$title = ""`).
|
|
682
|
-
- Button `size` accepts both `sm|md|lg` (canonical) and the legacy `small|normal|large`. Pass `icon` for an inline leading icon.
|
|
683
|
-
- `FormSection(label, children, helper?)` is the canonical wrapper for related fields. Reach for it INSTEAD of nesting fields in Card + SectionHeader by hand.
|
|
684
|
-
- `FieldSet(legend, children, helper?)` is the accessible `<fieldset>` for radio/checkbox groups; prefer `FormSection` for purely visual grouping.
|
|
685
|
-
- `ValidationSummary(errors, title?)` renders an aggregate error panel at the top of the form. Pass `errors` as `{label, message}` objects.
|
|
686
|
-
- `PasswordInput(id, value?, placeholder?, strengthMeter?)` adds a show/hide toggle and an optional 4-step strength meter — prefer over `Input(type="password")` for sign-up flows.
|
|
687
|
-
- `PinInput(id, length?, value?, type?)` renders per-digit code entry for 2FA / SMS verification (use `length=6` for OTP codes).
|
|
688
|
-
- `TagInput(id, value?, placeholder?)` lets the user add comma- or Enter-separated chips bound to a `$variable` array.
|
|
689
|
-
- `MentionInput(id, people, value?)` is a textarea with inline @-mention suggestions — use for comments, task notes, chat composers.
|
|
690
|
-
- `MaskedInput(id, mask, value?)` formats input against a mask string (`9` digit, `A` letter, `*` any). Use for phone numbers, postal codes.
|
|
691
|
-
- `TimePicker(id, value?)` and `DateTimePicker(id, value?)` wrap the corresponding native inputs with consistent styling.
|
|
692
|
-
- `ColorPicker(id, value?, label?, swatches?)` pairs a color chip with a hex input and preset swatches — bind a $variable holding a hex string.
|
|
693
|
-
- `MultiStepForm(steps, current, onSubmit?)` replaces ad-hoc `Steps` + content + manual prev/next wiring. Each step is `{title, details?, content}`.
|
|
642
|
+
- SearchBar(id: string, placeholder?: string, value?: string, shortcut?: string, onSubmit?: callable, submitLabel?: string, onChange?: callable) — Pre-styled search input with a leading magnifying-glass icon, optional trailing submit button, and optional keyboard-shortcut hint. Pass a `$variable` as `value` for two-way binding. Use anywhere a user needs to filter content — toolbars, command bars, lists, headers.
|
|
643
|
+
- Slider(id: string, min?: number, max?: number, step?: number, value?: number, label?: string, showValue?: boolean, disabled?: boolean, onChange?: callable) — Range slider for selecting a single numeric value between `min` and `max`. Pass a `$variable` as `value` for two-way binding. Useful for filters, settings (volume, brightness), and parameter tuning.
|
|
644
|
+
- NumberInput(id: string, value?: number, min?: number, max?: number, step?: number, placeholder?: string, disabled?: boolean, onChange?: callable) — Numeric input with paired increment/decrement buttons. Use for quantity steppers, integer settings, and any field where a `<input type="number">` plus +/- controls is friendlier than the native spinner. Pass a `$variable` as `value` for two-way binding.
|
|
645
|
+
- ColorPicker(id: string, value?: string, label?: string, swatches?: string[], disabled?: boolean, onChange?: callable) — Hex / RGB color form control with preset swatches. Pairs a native `<input type="color">` chip with a hex text input and a row of preset swatches. Pass a `$variable` as `value` (hex string, e.g. `"#6366f1"`) for two-way binding. Use for theme builders, label color pickers, and any "pick a color" surface.
|
|
646
|
+
- DatePicker(id: string, value?: string, label?: string, min?: string, max?: string, placeholder?: string, disabled?: boolean, onChange?: callable) — Date picker that wraps the native `<input type="date">` with consistent styling. Pass a `$variable` as `value` for two-way binding. Use `min`/`max` to bound the selectable range.
|
|
647
|
+
- DateRangePicker(id: string, from?: string, to?: string, label?: string, min?: string, max?: string, disabled?: boolean, onChange?: callable) — Paired date inputs with a single label, sharing the same min/max range. Pass `$variable` references for both `from` and `to` to two-way-bind a date range (ISO `YYYY-MM-DD` strings).
|
|
648
|
+
- TimePicker(id: string, value?: string, label?: string, min?: string, max?: string, step?: number, disabled?: boolean, onChange?: callable) — Time-of-day picker that wraps `<input type="time">`. Pass a `$variable` as `value` for two-way binding (HH:MM 24-hour). Set `step` to constrain to specific increments (e.g. 900 for 15-minute buckets).
|
|
649
|
+
- DateTimePicker(id: string, value?: string, label?: string, min?: string, max?: string, step?: number, disabled?: boolean, onChange?: callable) — Combined date + time picker — wraps `<input type="datetime-local">`. Pass a `$variable` as `value` for two-way binding (ISO `YYYY-MM-DDTHH:MM`).
|
|
650
|
+
- FileUpload(id: string, label?: string, hint?: string, accept?: string, multiple?: boolean, onSelect?: callable, icon?: string, disabled?: boolean) — Styled file picker. Renders a click/drop area with a leading icon, label, and helper text. Files cannot round-trip through `$variables` (they are not serialisable), so pass a callable as `action` to handle the picked files via `ctx.query("#id").files`.
|
|
651
|
+
- PinInput(id: string, length?: number, value?: string, type?: "numeric"|"alphanumeric", mask?: boolean, disabled?: boolean, onChange?: callable) — Per-digit PIN entry. Auto-advances focus as the user types and supports paste. Pass a `$variable` as `value` for two-way binding (the bound value is the joined string). Use `type="numeric"` for PINs / 2FA codes, `"alphanumeric"` for invite codes.
|
|
652
|
+
- MultiStepForm(steps: object[], current: number, onSubmit?: callable, prevLabel?: string, nextLabel?: string, submitLabel?: string, stepsLayout?: "column"|"row") — Multi-step / wizard form composite. Renders a `Steps` indicator, the active step's `content`, and Prev/Next buttons that drive a `$variable` for the current 0-indexed step. Use INSTEAD of hand-rolling `Steps` + content + manual prev/next wiring. The submit button is rendered on the final step (override via `submitLabel`). Step indicator direction defaults to `column` (stacked next to the content); set `stepsLayout: "row"` for a classic horizontal stepper.
|
|
694
653
|
|
|
695
654
|
### Data
|
|
696
655
|
- Table(columns: Col[], caption?: string, density?: "comfortable"|"compact", striped?: boolean, sticky?: boolean, emptyLabel?: string) — Tabular data view. Children must be Col components. `density="compact"` tightens row padding for dense data, `striped=true` zebra-stripes the rows, and `sticky=true` pins the header row when the table scrolls. The empty-state row uses `emptyLabel` when set.
|
|
697
|
-
- Col(header: string, values: any[], format?: "text"|"number"|"currency"|"date", align?: "left"|"center"|"right", sortable?: boolean, filterable?: boolean) — Single column inside a Table or DataGrid. Use `align` for per-column text alignment, `format` for cell rendering (`text|number|currency|date`). `sortable` and `filterable` only take effect inside `DataGrid` (Table ignores them).
|
|
698
|
-
- DataGrid(columns: Col[], rowIds?: any[], caption?: string, sort?: object, selectedIds?: any[], selectable?: boolean, page?: number, perPage?: number, emptyLabel?: string,
|
|
656
|
+
- Col(header: string, values: any[], format?: "text"|"number"|"currency"|"date", align?: "left"|"center"|"right", sortable?: boolean, filterable?: boolean, render?: callable, onClick?: callable) — Single column inside a Table or DataGrid. Use `align` for per-column text alignment, `format` for cell rendering (`text|number|currency|date`). `values` may be plain values OR an array of component nodes — e.g. `Col("Status", rows.map(r => Badge(r.status)))` or `Col("Actions", rows.map(r => Button("Edit")))` — each component renders directly in its cell. Pass `render: (value, index) => …` for the same effect when you prefer to keep `values` as the raw row data (return a component, string, or array). Pass `onClick: (value, index) => …` to make the whole cell clickable (pointer + keyboard). `sortable` and `filterable` only take effect inside `DataGrid` (Table ignores them).
|
|
657
|
+
- DataGrid(columns: Col[], rowIds?: any[], caption?: string, sort?: object, selectedIds?: any[], selectable?: boolean, page?: number, perPage?: number, emptyLabel?: string, onRowClick?: callable, toolbar?: Node[], density?: "comfortable"|"compact", striped?: boolean, stickyHeader?: boolean, stickyFirstColumn?: boolean) — Advanced data table with sortable headers, per-column filter chips, row selection (checkboxes), sticky header / first column, optional pagination, an optional bulk-action toolbar slot, and click-to-act rows. Columns are Col(header, values, format?, align?, sortable?, filterable?) entries. Bind `$sort` (`{key, direction}` object), `$selectedIds` (string[]), and `$page` (number) for full reactivity. Use INSTEAD of `Table` when you need any of those interactions.
|
|
699
658
|
- List(items: ListItem[], ordered?: boolean) — Vertical list of ListItems.
|
|
700
659
|
- ListItem(title: string, description?: string, icon?: string) — Single list item with optional title and description.
|
|
701
660
|
- StatCard(label: string, value: string, trend?: "up"|"down"|"flat", delta?: string, icon?: string, spark?: number[], tone?: "default"|"primary"|"success"|"warning"|"danger"|"info") — Single KPI card with label, value, optional delta, optional icon, and optional inline sparkline (`spark=[…numbers]`). Use inside `Stats` for a uniform KPI strip.
|
|
702
661
|
- Stats(items: object[] | StatCard[], layout?: "strip"|"grid", columns?: number, align?: "start"|"center"|"end") — KPI strip or grid. Pass `items` as `{label, value, hint?, tone?, spark?}` objects for strip layout, or as `StatCard(...)` nodes when `layout="grid"`.
|
|
703
662
|
- Sparkline(values: number[], tone?: "primary"|"success"|"warning"|"danger"|"info") — Tiny inline trend chart for KPIs, table cells, and dashboards. Renders an SVG line with a soft fill — use anywhere you would otherwise reach for `LineChart` but a single value series should stay inline with surrounding text.
|
|
704
|
-
- Tile(label: string, icon?: string, value?: string, description?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info",
|
|
663
|
+
- Tile(label: string, icon?: string, value?: string, description?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info", onClick?: callable) — Compact icon + label + optional value tile. Smaller and denser than `StatCard`, ideal for menu grids, quick-action panels, category directories, and category filters. Pair with `Grid` for uniform rows.
|
|
705
664
|
- Progress(value?: number, max?: number, label?: string, tone?: "primary"|"success"|"warning"|"danger"|"info", indeterminate?: boolean, showValue?: boolean, segments?: number, buffered?: number) — Linear progress bar. `value` is clamped between 0 and `max` (default 100). `indeterminate=true` renders a looping animation when the total is unknown. Provide `segments` to render a segmented progress strip (steps in an onboarding flow), or `buffered` for a secondary buffer indicator (downloads, video buffering).
|
|
706
665
|
- ProgressRing(value?: number, max?: number, label?: string, caption?: string, tone?: "primary"|"success"|"warning"|"danger"|"info", size?: "sm"|"md"|"lg", indeterminate?: boolean) — Circular progress indicator. Use for KPIs, quotas, completion rings, and any metric better shown as a circle than a bar. Renders the value (or a custom label) inside the ring.
|
|
707
666
|
- Pagination(page: number, totalPages: number, siblings?: number, total?: number, perPage?: number, perPageOptions?: number[], compact?: boolean) — Page navigator with Prev/Next, page numbers, and ellipses. Pass a `$variable` as `page` for two-way binding — clicking a page button sets that state to the new (1-indexed) value. Add `total` to render a "Showing N–M of T" summary, pass `$variable` as `perPage` to expose a per-page selector, or set `compact: true` to drop the page-number row for tight toolbars.
|
|
708
667
|
- Tree(items: TreeNode[]) — Hierarchical tree view. Children must be TreeNode entries. Use for file browsers, nested navigation, category pickers, and any parent/child structure with arbitrary depth.
|
|
709
|
-
- TreeNode(label: string, children?: TreeNode[], icon?: string, expanded?: boolean, active?: boolean, badge?: string,
|
|
668
|
+
- TreeNode(label: string, children?: TreeNode[], icon?: string, expanded?: boolean, active?: boolean, badge?: string, onClick?: callable) — Single node in a Tree view. When `children` is provided the node renders as an expandable branch with a chevron; otherwise it renders as a leaf. `onClick` fires on click. Use `active=true` to highlight the current selection.
|
|
710
669
|
- CalendarView(value?: string, month?: string, events?: object[], view?: "month"|"week", firstDay?: number, onSelect?: callable) — Full-month or week calendar grid for scheduling apps — distinct from the form-input `DatePicker`. Pass events as an array of `{date: 'YYYY-MM-DD', title, tone?, time?}` objects. Bind `value` to a `$variable` for the selected date (ISO string). Use `view="week"` for a single-week strip. `firstDay=1` (Monday) matches most business apps.
|
|
711
670
|
- ComparisonTable(columns: string[], rows: object[], highlightColumn?: number) — Feature/spec comparison table — generic counterpart of `PricingTable`. Pass `columns` (e.g. plan/product names) and `rows` of `{label, values}` where `values` aligns 1-to-1 with `columns`. Each value can be a boolean (✓/—), a string, or a node.
|
|
712
671
|
- InfiniteList(items: Node[], onLoadMore?: callable, loading?: boolean, hasMore?: boolean, loaderLabel?: string) — Vertical list that fires `onLoadMore` when the user scrolls near the bottom. Pass already-rendered child nodes as `items`; wire `onLoadMore` to an `action` that awaits a `$mutation` or `$query` (e.g. `await loadMore.invoke()`) and appends to the bound state. Use `loading=true` to show the spinner row, `hasMore=false` to suppress further loads.
|
|
713
672
|
|
|
714
|
-
- Build columns using array pluck: `Col("Title", data.rows.title, format?, align?)`.
|
|
715
|
-
- For per-row controls inside a Col, use `@Each(data.rows, "row", ...)` and reference `row.field` inline.
|
|
716
|
-
- `Table(cols, caption?, density?, striped?, sticky?, emptyLabel?)` — pass `density="compact"` for dense data, `sticky=true` to pin the header in a scrolling parent, and `emptyLabel` for the zero-state cell.
|
|
717
|
-
- `DataGrid(cols, rowIds?, caption?, sort, selectedIds, selectable?, page, perPage?, …)` is the advanced Table — adds sortable headers (`sortable=true` on Col), per-column filter chips (`filterable=true`), checkbox row selection bound to `$selectedIds`, sticky header / first column, pagination, and an optional bulk-action toolbar. Reach for this whenever a user needs to sort, filter, or page through a list.
|
|
718
|
-
- `CalendarView(value?, month?, events?, view?, firstDay?, onSelect?)` renders a full-month (or week) calendar grid for scheduling apps — distinct from the `DatePicker` input. Bind `value` to a `$variable` for the selected ISO date.
|
|
719
|
-
- `ComparisonTable(columns, rows, highlightColumn?)` is the generic counterpart of `PricingTable` — pass rows of `{label, values, hint?, group?}`. Use for feature comparisons, spec sheets, plan grids.
|
|
720
|
-
- `InfiniteList(items, onLoadMore?, loading?, hasMore?)` is a scroll-to-load list; the action fires when the sentinel scrolls into view.
|
|
721
|
-
- Use `Progress(value, max?, label?, tone?, indeterminate?, segments?, buffered?)` for linear bars — `segments` renders an N-step strip (onboarding flows), `buffered` adds a secondary buffer indicator.
|
|
722
|
-
- `ProgressRing(value, max?, label?, tone?, size?)` is the circular variant for quotas/completion.
|
|
723
|
-
- `Stats([{label, value, hint?, tone?, spark?}, …], layout?)` — `layout="strip"` (default) for inline KPIs; `layout="grid"` for a responsive StatCard grid. Pass `spark` for an inline trend line.
|
|
724
|
-
- `StatCard(label, value, trend?, delta?, icon?, spark?, tone?)` gains an optional inline `Sparkline` via the `spark` prop. Use `Sparkline(values, tone?)` standalone for tiny trend chips in table cells.
|
|
725
|
-
- `Tile(label, icon?, value?, description?, tone?, action?)` is the dense icon tile for quick-action menus and category grids; pair with `Grid` for uniform rows.
|
|
726
|
-
- `Tree([TreeNode(label, children?, icon?, expanded?, active?, badge?, action?)])` renders a hierarchical tree (file browsers, nested navigation, category pickers); use `expanded=true` to open a branch by default.
|
|
727
|
-
- `Pagination(page, totalPages, siblings?, total?, perPage?, perPageOptions?, compact?)` — bind `page` (and optionally `perPage`) to a `$variable`; pass `total` to render the "Showing N–M of T" summary. Reuse the same variable when slicing data with `@Filter` / `@Each`.
|
|
728
|
-
|
|
729
673
|
### Charts
|
|
730
674
|
- BarChart(labels: string[], series: Series[], title?: string) — Vertical bar chart. `labels` define the x-axis, `series` define grouped bars.
|
|
731
675
|
- LineChart(labels?: string[], series?: Series[], data?: {x: string, [key: string]: number}[], title?: string, filled?: boolean, stacked?: boolean) — Line chart. `labels` define the x-axis, each Series is a line. As a shortcut you can pass `data=[{x: "Jan", revenue: 12, signups: 4}, …]` and the labels + series will be derived automatically (one line per non-`x` key). Use `data` when the dataset is already row-shaped; use `series` when you have explicit Series objects.
|
|
732
|
-
- PieChart(labels: string[], values: number[], title?: string) — Pie/Donut chart. Each segment maps to a label/value pair.
|
|
676
|
+
- PieChart(labels: string[], values: number[], title?: string, showValues?: boolean, valueFormat?: "value"|"percent"|"both") — Pie / Donut chart. Each segment maps to a label/value pair. Numeric labels are rendered on every segment by default — set `showValues: false` to hide them, or `valueFormat: "percent"` to show the share instead of the raw value.
|
|
733
677
|
- RadarChart(axes: string[], series: Series[], max?: number, title?: string) — Polygon chart with one axis per category. Use for skill maps, scorecards, capability comparisons, and any multi-dimensional snapshot. Each Series renders as a filled polygon — overlapping is expected for comparisons.
|
|
734
678
|
- ScatterChart(series: Series[], xLabel?: string, yLabel?: string, title?: string) — XY scatter plot — one dot per data point, optionally grouped by series. Pass each `Series(name, points)` with points as `{x, y, label?}` objects or `[x, y, label?]` tuples. Use for correlations, distributions, and "price vs. rating" style charts.
|
|
735
679
|
- Histogram(values?: number[], bins?: object[], binCount?: number, title?: string) — Frequency distribution from raw numeric values. Pass `values` directly (the component bins them automatically) or pre-computed `bins` of `{label, count}` objects. Use for response-time histograms, score distributions, age buckets.
|
|
@@ -737,21 +681,14 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
737
681
|
- Gauge(value: number, min?: number, max?: number, caption?: string, tone?: "primary"|"success"|"warning"|"danger"|"info", size?: "sm"|"md"|"lg", label?: string) — Half-doughnut gauge indicator for a single value between `min` and `max`. The inner value is auto-formatted from the value (override via `label`). Pass `caption`, `tone`, and `size` for visual treatment. Use for KPI thresholds (uptime %, score, capacity, NPS, page-speed).
|
|
738
682
|
- Series(name: string, values: number[]) — Named data series for charts. Used inside BarChart, LineChart, PieChart.
|
|
739
683
|
|
|
740
|
-
- Use `LineChart` for trends (pass `filled=true` for area-style charts), `BarChart` for comparisons, `PieChart` for proportions, `RadarChart` for multi-axis scorecards.
|
|
741
|
-
- `Heatmap(xLabels, yLabels, values)` renders a color-intensity matrix — perfect for calendar heatmaps, correlation grids, schedule density.
|
|
742
|
-
- `ScatterChart(series, xLabel?, yLabel?)` plots XY points; pass each Series as `Series(name, points)` where points are `{x, y, label?}`.
|
|
743
|
-
- `Histogram(values, binCount?)` bins raw numbers; pass pre-computed `bins=[{label, count}]` instead when you control the bucketing.
|
|
744
|
-
- `Gauge(value, min?, max?, label?, tone?, size?)` is the half-doughnut KPI indicator for thresholds (uptime %, score, NPS).
|
|
745
|
-
- Pass series via `Series("Name", [...numbers])`.
|
|
746
|
-
|
|
747
684
|
### Feedback & Media
|
|
748
685
|
- Avatar(name: string, src?: string, size?: "sm"|"md"|"lg"|"xl", status?: "online"|"offline"|"busy"|"away", fallback?: "initials"|"dicebear") — User avatar. Shows the image at `src`. When `src` is missing, falls back to a deterministic DiceBear illustration seeded by `name` (pass `fallback="initials"` to render two-letter initials instead). If the image errors at runtime the avatar gracefully degrades to initials.
|
|
749
686
|
- AvatarGroup(items: Avatar[], max?: number, size?: "sm"|"md"|"lg"|"xl") — Stack of overlapping avatars with a `+N` chip when the list overflows. Pass either Avatar(...) nodes or plain {name, src} objects.
|
|
750
|
-
- PersonChip(name: string, role?: string, avatarSrc?: string, size?: "sm"|"md"|"lg", status?: "online"|"offline"|"busy"|"away",
|
|
751
|
-
- Tooltip(label: string, trigger: Node, side?: "top"|"bottom"|"left"|"right") — Wraps a trigger node and shows `label` text when the user hovers or focuses it. Pure CSS — no JS needed. Use for short hints (≤6 words); reach for HoverCard when you need rich content.
|
|
687
|
+
- PersonChip(name: string, role?: string, avatarSrc?: string, size?: "sm"|"md"|"lg", status?: "online"|"offline"|"busy"|"away", onClick?: callable) — Inline avatar + name + optional role/meta pill. Use anywhere a person needs to be referenced compactly: table cells, list rows, comments, kanban cards, sidebar footers. Pair multiple chips with `Stack(direction="row", wrap=true)` for assignee lists.
|
|
688
|
+
- Tooltip(label: string, trigger: Node, side?: "top"|"bottom"|"left"|"right") — Wraps a trigger node and shows `label` text when the user hovers or focuses it. Pure CSS — no JS needed. The tooltip hides on click/touch (so it does not stay stuck on touch devices) and supports `top|bottom|left|right` placement. Use for short hints (≤6 words); reach for HoverCard when you need rich content.
|
|
752
689
|
- HoverCard(trigger: Node, content: Node[], side?: "top"|"bottom"|"left"|"right", open?: boolean) — Wraps a trigger node and reveals a card with rich content on hover/focus. Use for previewing a referenced item (profile, link target, definition).
|
|
753
690
|
- Popover(trigger: Node, content: Node[], title?: string, side?: "bottom"|"top"|"left"|"right", align?: "start"|"center"|"end", width?: string, open?: boolean) — Click-triggered popup with arbitrary rich content. Use when HoverCard's hover trigger is too eager and Modal/Sheet is too heavy — perfect for filter panels, color pickers, share menus, and small settings flyouts. The trigger stays visible while the popover is open — clicking it again, clicking outside, pressing Escape, or clicking the built-in × button all close it.
|
|
754
|
-
- Rating(value: number, max?: number, label?: string, count?: number, size?: "sm"|"md"|"lg", interactive?: boolean, readonly?: boolean, halfStep?: boolean, icon?: string) — Compact 0–5 star rating with optional numeric badge and review count. Use in product cards, testimonials, reviews, and KPI rows. Pass `interactive=true` and a `$variable` as `value` to let users rate something; with `halfStep=true` clicking the left half of a star sets a fractional value. `icon` swaps the glyph family — `star` (default), `heart`, `thumb`, `fire`, `bolt`, or any custom Font Awesome name.
|
|
691
|
+
- Rating(value: number, max?: number, label?: string, count?: number, size?: "sm"|"md"|"lg", interactive?: boolean, readonly?: boolean, halfStep?: boolean, icon?: string, onChange?: callable) — Compact 0–5 star rating with optional numeric badge and review count. Use in product cards, testimonials, reviews, and KPI rows. Pass `interactive=true` and a `$variable` as `value` to let users rate something; with `halfStep=true` clicking the left half of a star sets a fractional value. `icon` swaps the glyph family — `star` (default), `heart`, `thumb`, `fire`, `bolt`, or any custom Font Awesome name.
|
|
755
692
|
- Toast(title: string, message?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info", icon?: string, duration?: number, action?: Button, onClose?: callable, position?: "top-right"|"top-left"|"top-center"|"bottom-right"|"bottom-left"|"bottom-center") — Single transient notification card. Always shows a close (×) button that removes the toast from the DOM (and fires `onClose` if set). Pass `duration` (ms) to auto-dismiss, or `position` for a standalone one-off toast (the renderer will pin it to the viewport corner so you do not have to wrap a single notification in `Stack(...)`). Use `Toasts` for grouped stacks; prefer `Banner` for top-of-page announcements and `Notification` for permanent inbox entries.
|
|
756
693
|
- VideoPlayer(src?: string, sources?: object[], poster?: string, caption?: string, controls?: boolean, autoplay?: boolean, loop?: boolean, muted?: boolean, ratio?: string) — Themed native `<video>` wrapper. Pass a `src` URL (or `sources` array for multi-codec fallback) and optional `poster`. Standard controls are visible by default; pass `autoplay`, `loop`, `muted`, or `controls=false` to override. Use for product demos, tutorials, and any inline video.
|
|
757
694
|
- AudioPlayer(src?: string, sources?: object[], title?: string, artist?: string, controls?: boolean, autoplay?: boolean, loop?: boolean, icon?: string) — Themed native `<audio>` wrapper with a title, optional artist, and standard transport controls. Pass `src` (or `sources`) plus a `title` so the bar still looks like a player when the controls bar is hidden. Use for podcasts, voice notes, and demo audio.
|
|
@@ -760,43 +697,24 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
760
697
|
- Lightbox(items: any[], open?: boolean, index?: number) — Image overlay. When you bind a `$variable` to `open` you control it explicitly; without one, Lightbox renders a clickable thumbnail of the current image that opens the overlay on click (and uses internal state for next/prev). Pass `items` (string URLs or `{src, alt, caption?}` objects). Clicking the backdrop or × closes; arrows step through the array.
|
|
761
698
|
- Map(lat: number, lng: number, zoom?: number, markers?: object[], height?: string, caption?: string) — Static map view centered on a lat/lng coordinate. Renders an OpenStreetMap embed inside an `<iframe>` (no external JS, no API key). Pass `lat` and `lng` as bare numbers; `zoom` controls the level (1–18, default 13). Optional `markers` array adds map pins (rendered as a labelled list alongside the map). Use for store locators, address cards, itinerary previews.
|
|
762
699
|
|
|
763
|
-
- `Avatar(name, src?, size?, status?)` falls back to initials when the image is missing.
|
|
764
|
-
- Use `AvatarGroup` to render contributor strips with a `+N` overflow chip.
|
|
765
|
-
- `PersonChip(name, role?, avatarSrc?, size?, status?, action?)` is the inline avatar + name + role pill — use everywhere a person is referenced (table cells, list rows, sidebar footers, kanban cards) instead of a raw `Avatar` next to `Text`.
|
|
766
|
-
- Wrap any node in `Tooltip(label, trigger)` for inline hints.
|
|
767
|
-
- Use `HoverCard(trigger, content)` when the popover needs rich content (profile preview, link target) and the trigger should open on hover.
|
|
768
|
-
- `Popover(trigger, content, title?, side?, align?, width?)` is the click-triggered counterpart of `HoverCard` — use for filter panels, color pickers, share menus, and small settings flyouts. Always renders an × close button in the header; clicking the trigger again, clicking outside, or pressing Escape also closes it.
|
|
769
|
-
- `Rating(value, max?, label?, count?, size?, interactive?, halfStep?, icon?)` renders stars for product reviews, testimonials, and ranked lists. Pass a `$variable` as `value` with `interactive=true` to let users rate; add `halfStep=true` so clicking the left half of a star sets a half-value. Set `icon="heart"|"thumb"|"fire"|"bolt"` (or any FA name) to swap glyphs.
|
|
770
|
-
- `Toast(title, message?, tone?, icon?, duration?, action?, onClose?, position?)` pins a transient notice; pass `duration` (ms) for auto-dismiss. Drive lists from an `action` body: `$toasts = [...$toasts, item]` to append and `$toasts = @Filter($toasts, "id", "!=", id)` to dismiss. Use `Banner` for top-of-page announcements and `Notification` for permanent inbox entries.
|
|
771
|
-
- `NotificationBell(count?, items?, onOpen?)` — compact inbox trigger; `CommandPalette` for Cmd-K action search.
|
|
772
|
-
|
|
773
700
|
### Navigation
|
|
774
701
|
- Breadcrumb(items: BreadcrumbItem[] | string[], separator?: string) — Trail of links showing the user's location. Children may be BreadcrumbItem(label, href?) nodes OR plain strings (the last string is treated as the current page).
|
|
775
702
|
- BreadcrumbItem(label: string, href?: string, icon?: string) — Single item inside a Breadcrumb trail. Provide `href` for a link, omit it for the current/leaf page (rendered with emphasis).
|
|
776
703
|
- Navbar(brand?: string | Node, items?: NavbarItem[], actions?: Node[], sticky?: boolean, variant?: "default"|"transparent") — Top navigation bar with a brand on the left, primary nav items in the middle, and a right-aligned actions slot (user avatar, DropdownMenu, CTA buttons, …). Use `sticky=true` to pin it to the top of the page. The canonical companion of `Sidebar` for product surfaces; prefer Navbar for marketing/docs pages without a sidebar.
|
|
777
|
-
- NavbarItem(label: string, to?: string, href?: string, icon?: string, active?: boolean,
|
|
704
|
+
- NavbarItem(label: string, to?: string, href?: string, icon?: string, active?: boolean, onClick?: callable, external?: boolean) — Single link inside a Navbar's main item slot. Renders as an inline anchor / button — pass `to` for a router-aware link, `href` for an external link, or `onClick` for a click handler. `active=true` highlights the current page.
|
|
778
705
|
- DropdownMenu(trigger: Node, items: (MenuItem | MenuSeparator | MenuLabel)[], side?: "bottom"|"top"|"left"|"right", align?: "start"|"center"|"end", label?: string, open?: boolean) — Click-triggered dropdown menu. Click the trigger to toggle, click a MenuItem to run its action and close, click outside or press Escape to close without acting. Children must be MenuItem, MenuSeparator, or MenuLabel entries.
|
|
779
|
-
- MenuItem(label: string,
|
|
706
|
+
- MenuItem(label: string, onClick?: callable, icon?: string, shortcut?: string, variant?: "default"|"danger", disabled?: boolean) — Single item inside a DropdownMenu. Renders a button-style row with an optional leading icon and trailing keyboard-shortcut hint. `onClick` (legacy: `action`) runs when clicked; the menu closes automatically afterwards.
|
|
780
707
|
- MenuSeparator() — Thin horizontal rule used inside a DropdownMenu to group items.
|
|
781
708
|
- MenuLabel(label: string) — Small uppercase section header inside a DropdownMenu. Use to group related MenuItems (e.g. "Account", "Workspace", "Danger zone").
|
|
782
709
|
|
|
783
|
-
- Use `Breadcrumb(["Workspace", "Reports", "Q3"])` at the top of every detail page so users see the path.
|
|
784
|
-
- For per-item links, pass `BreadcrumbItem(label, href)` nodes instead of strings.
|
|
785
|
-
- `Navbar(brand?, items?, actions?, sticky?, variant?)` + `NavbarItem(label, to?, href?, icon?, active?, action?, external?)` produces a top navigation bar with brand on the left, links in the middle, and actions on the right — the canonical companion of `Sidebar` for marketing pages, docs, or any product surface without left-side nav.
|
|
786
|
-
- `DropdownMenu(trigger, items, side?, align?, label?)` is the click-triggered dropdown menu — use it for user-profile menus, row "…" action menus, and any compact list of actions hanging off a single trigger. Children must be `MenuItem`, `MenuSeparator`, or `MenuLabel` entries.
|
|
787
|
-
- `MenuItem(label, action?, icon?, shortcut?, variant?, disabled?)` renders a single row inside a `DropdownMenu`; use `variant="danger"` for destructive actions and `MenuSeparator()`/`MenuLabel(label)` to group related items.
|
|
788
|
-
|
|
789
710
|
### Chat
|
|
790
711
|
- SectionBlock(title: string, children: Node[], description?: string) — Titled chat block with a description and child content.
|
|
791
712
|
- ListBlock(items: string[], ordered?: boolean) — Chat-styled list with bullets, useful for steps or summaries.
|
|
792
713
|
- FollowUpBlock(items: FollowUpItem[], title?: string) — Suggested follow-up prompts shown as buttons. Each item dispatches its label as an assistant message (equivalent to `emit "assistant-message" { message }`).
|
|
793
714
|
- FollowUpItem(label: string, message?: string) — Single follow-up item.
|
|
794
|
-
- ActionLink(label: string,
|
|
715
|
+
- ActionLink(label: string, onClick: callable) — Inline link that runs an action when clicked instead of navigating.
|
|
795
716
|
- ChatBubble(author: string, body: string, time?: string, avatarSrc?: string, from?: "agent"|"me"|"system", status?: "sending"|"sent"|"delivered"|"read"|"error") — Single chat-style message bubble with author, time, and body. Use for conversation threads, agent transcripts, support chats, and any message-style UI. Set `from="me"` (or any non-empty author) for the active speaker — the bubble aligns to the right with a primary tint. `from="agent"` (default) renders as the canonical incoming bubble on the left.
|
|
796
717
|
|
|
797
|
-
- End most responses with a `FollowUpBlock` of 2–4 short prompts to keep the conversation moving.
|
|
798
|
-
- `ChatBubble(author, body, time?, avatarSrc?, from?)` renders a single message bubble; use `from="me"` for the active speaker and `from="agent"` for the assistant. Compose transcripts as `Stack([ChatBubble(...), ChatBubble(...), …])` inside a `Card`.
|
|
799
|
-
|
|
800
718
|
### Patterns
|
|
801
719
|
- Hero(title: string, subtitle?: string, primary?: Button, secondary?: Button, eyebrow?: string, highlights?: string[], imageSrc?: string, caption?: string, height?: string, actions?: Node[], layout?: "default"|"cover", tone?: "default"|"primary"|"success"|"warning"|"danger"|"info") — Eye-catching landing/marketing header with eyebrow tag, title, subtitle, optional bullet highlights, and primary/secondary CTA buttons. Use `layout="cover"` with `imageSrc` for an image-backed hero band (pass `height` and optional `caption`). Default layout shows an optional side illustration.
|
|
802
720
|
- PageHeader(title: string, subtitle?: string, breadcrumbs?: string[] | Breadcrumb | false, actions?: Node[], status?: Badge) — Page-level header with breadcrumbs, title, subtitle, status tag, and a right-aligned actions row. The canonical first child for any dashboard, settings, or detail page — replaces ad-hoc Stack+Header+Buttons stitching. If `breadcrumbs` is omitted the component auto-derives `["Home", title]` so the page never lacks a trail. Pass `breadcrumbs=false` to opt out.
|
|
@@ -808,16 +726,16 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
808
726
|
- FeatureItem(title: string, description?: string, icon?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info") — Single tile on a FeatureGrid.
|
|
809
727
|
- Testimonial(quote: string, author: string, role?: string, avatarSrc?: string, rating?: number) — Quote card with author, role, and optional avatar.
|
|
810
728
|
- ProfileCard(name: string, role?: string, avatarSrc?: string, bio?: string, tags?: string[], actions?: Node[]) — Compact profile/user card with avatar, name, role, optional bio, social tags, and a row of action buttons. Use for team rosters, contributor lists, and contact panels.
|
|
811
|
-
- Comment(author: string, body: string, time?: string, avatarSrc?: string, actions?: Node[]) — Single comment / message bubble. Renders avatar, author, timestamp, body, and an optional row of
|
|
729
|
+
- Comment(author: string, body: string, time?: string, avatarSrc?: string, actions?: Node[]) — Single comment / message bubble. Renders avatar, author, timestamp, body, and an optional row of toolbar buttons (reply, like, …).
|
|
812
730
|
- Banner(title: string, message?: string, action?: Button, icon?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info") — Full-width announcement banner. Use at the top of a page for promos, release notes, or downtime notices. For inline notices prefer Callout or Alert.
|
|
813
731
|
- Notification(title: string, message?: string, time?: string, icon?: string, avatarSrc?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info", unread?: boolean, actions?: Node[]) — Inline notification card with title, message, time, optional avatar, and dismiss/action buttons. Use inside notification panels, inboxes, or activity drawers — for top-of-page announcements prefer `Banner`.
|
|
814
|
-
- InboxPanel(items: object[], emptyLabel?: string, onMarkAllRead?: callable) — Grouped notification list — entries are grouped into Unread/Earlier sections, with a count chip on each group header. Pass `items` as `{title, message, time, icon?, tone?, unread?, avatarSrc?,
|
|
815
|
-
- OnboardingChecklist(items: object[], title?: string, subtitle?: string) — Step-by-step product checklist with completion progress at the top. Pass `items` as `{title, description?, done?,
|
|
732
|
+
- InboxPanel(items: object[], emptyLabel?: string, onMarkAllRead?: callable) — Grouped notification list — entries are grouped into Unread/Earlier sections, with a count chip on each group header. Pass `items` as `{title, message, time, icon?, tone?, unread?, avatarSrc?, onClick?}` objects (`action` is also accepted as an alias). Pair with a `SectionHeader` for the panel title (the component does not render its own title to avoid duplication). Use for top-bar notification trays, activity drawers, and alert center pages.
|
|
733
|
+
- OnboardingChecklist(items: object[], title?: string, subtitle?: string) — Step-by-step product checklist with completion progress at the top. Pass `items` as `{title, description?, done?, onClick?, cta?}` objects (`action` is also accepted as an alias). The progress percentage is computed automatically from `done`. Use on first-run dashboards, empty workspaces, and "complete your profile" surfaces.
|
|
816
734
|
- MediaCard(title: string, imageSrc?: string, description?: string, tags?: string[], meta?: string, actions?: Node[], badge?: string | Badge, orientation?: "vertical"|"horizontal", ratio?: string) — Card with a media (image) header followed by title, body, optional tags, footer meta, and an actions row. Use for article previews, product cards, project highlights, gallery items — anywhere a Card needs a leading image. Orient with `orientation="horizontal"` for side-by-side media + content on wide viewports.
|
|
817
735
|
- TopBar(title?: string, subtitle?: string, left?: Node[], center?: Node[], right?: Node[], sticky?: boolean) — Compact header strip that pairs a title (or breadcrumb) with search and action slots. Use INSTEAD of hand-rolling a `Stack(direction="row")` above a page. For full SaaS shells use `Navbar` (links) or `AppShell` (sidebar + topbar + content).
|
|
818
736
|
- KanbanBoard(columns: KanbanColumn[]) — Horizontal Kanban board. Children must be KanbanColumn entries. The board scrolls horizontally on narrow viewports so columns stay readable.
|
|
819
737
|
- KanbanColumn(title: string, items: KanbanCard[], tone?: "default"|"primary"|"success"|"warning"|"danger"|"info") — Single column inside a KanbanBoard. Children must be KanbanCard entries.
|
|
820
|
-
- KanbanCard(title: string, description?: string, tags?: string[], assignee?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info", icon?: string,
|
|
738
|
+
- KanbanCard(title: string, description?: string, tags?: string[], assignee?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info", icon?: string, onClick?: callable) — Single card on a Kanban board.
|
|
821
739
|
- SectionHeader(title: string, subtitle?: string, eyebrow?: string, status?: Badge | Tag, actions?: Node[]) — Compact section header for the top of a Card or panel. Renders a small eyebrow, a title, an optional subtitle, an optional status Tag/Badge, and a right-aligned actions row. Use this inside a Card to introduce a section instead of a bare `CardHeader`.
|
|
822
740
|
- Toolbar(left?: Node[], right?: Node[], center?: Node[], searchable?: boolean, searchPlaceholder?: string, searchValue?: string) — Horizontal toolbar for filters, search, view modes, and primary actions. Left/center/right slots wrap onto separate rows on narrow viewports so the bar never overflows. Pass `searchable: true` to auto-mount a SearchBar in the left slot (bind `searchValue` to a `$variable`). Use ABOVE a Table, List, Grid, or Kanban view — never replace `PageHeader` with it.
|
|
823
741
|
- DescriptionList(items: DescriptionItem[], columns?: number) — Compact key/value summary for detail pages — replaces a row of `Text`s with a properly aligned `<dl>`. Children must be DescriptionItem entries. Two columns by default on wide viewports.
|
|
@@ -831,63 +749,23 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
831
749
|
- Tour(steps: object[], current: number, open?: boolean, onComplete?: callable) — Product-tour controller — renders the current step's title, description, and a Prev/Next/Skip row. Bind `current` to a `$variable` (0-indexed). Pass `steps` as `{title, description, target?}` objects; the optional `target` is a CSS selector that renders alongside the step for designers to reference.
|
|
832
750
|
- Spotlight(title: string, open?: boolean, description?: string, actions?: Node[]) — Single-step product highlight — a dimmed full-page overlay with a ring around the focused area and a small explainer card. Use for one-off feature reveals ("Try the new commands menu"). Bind `open` to a `$variable` to dismiss.
|
|
833
751
|
|
|
834
|
-
- Patterns are **opinionated composites** that pack an entire UI idiom into one component. Reach for them BEFORE composing equivalent layouts by hand with Card+Stack — the result will look more polished and require fewer tokens.
|
|
835
|
-
- `Hero(title, subtitle, primary, secondary, eyebrow?, highlights?, tone?)` — landing-style text-first header. Use `layout="cover"` with `imageSrc`, `height`, and optional `caption` for image-backed hero bands.
|
|
836
|
-
- `PageHeader(title, subtitle?, breadcrumbs?, actions?, status?)` — the canonical first child for any dashboard or detail page. If you omit `breadcrumbs`, the component auto-derives `["Home", title]`.
|
|
837
|
-
- `TopBar(title?, search?, actions?, sticky?)` — compact top strip for a content surface (panels, dialogs, embedded views). Use `AppShell` when you need a full sidebar; use `TopBar` for narrower headers above scrolling content.
|
|
838
|
-
- `SectionHeader(title, subtitle?, eyebrow?, status?, actions?)` — sub-header inside a Card or panel. Use instead of bare `CardHeader` when the section also needs eyebrow / actions / status.
|
|
839
|
-
- `Stats(items, layout?)` — KPI strip (`layout="strip"`, default) or responsive grid (`layout="grid"` with StatCard children). Prefer over hand-rolled StatCard rows.
|
|
840
|
-
- `Toolbar(left?, right?, center?, searchable?, searchPlaceholder?, searchValue?)` — filter/search/actions row above a list, table, or board. Pass `searchable: true` to auto-mount a `SearchBar` (use `searchValue` to bind it to a `$variable`).
|
|
841
|
-
- `EmptyState(title, description?, icon?, illustration?, actions?, action?)` — render this when a list is empty rather than an empty Card. The icon is auto-picked from the title keywords if you omit it (inbox/messages → `inbox`, charts/analytics → `chart-pie`, files/folders → `folder-open`, etc.).
|
|
842
|
-
- `Timeline([TimelineItem(...)])` — vertical event feed (audit log, changelog, activity).
|
|
843
|
-
- `ActivityLog(entries, variant?)` — purpose-built feed of user actions. Pass `entries` of `{actor, title, description?, time?, icon?, tone?, meta?}`; use `variant="audit"` for security/admin trails with monospace meta.
|
|
844
|
-
- `FeatureGrid([FeatureItem(...)])` — feature highlights with iconography.
|
|
845
|
-
- `MediaCard(title, imageSrc?, description?, tags?, meta?, actions?, badge?, orientation?, ratio?)` — image + content card. Use for article previews, product cards, project highlights. Pair with `Grid` for uniform card rows.
|
|
846
|
-
- `KanbanBoard([KanbanColumn("To do", [KanbanCard(...), ...])])` — task boards.
|
|
847
|
-
- `DescriptionList([DescriptionItem("Status", Badge(...)), …])` — detail-page key/value summary. Always preferable to a Stack of Text rows on profile, billing, or metadata panels.
|
|
848
|
-
- `StatusDot(label, tone?, pulse?)` — inline status pip. Use in toolbars, list rows, table cells, sidebars.
|
|
849
|
-
- `Notification(title, message?, time?, icon?, avatarSrc?, tone?, unread?, actions?)` — inline notification card for notification panels / inboxes (prefer `Banner` for top-of-page announcements).
|
|
850
|
-
- `InboxPanel(items, title?, onMarkAllRead?)` — `Notification` cards grouped into Unread / Earlier sections, with a shared mark-all-read action.
|
|
851
|
-
- `OnboardingChecklist(items, title?, description?)` — checklist of `{title, description?, done?, action?}` items with progress. Use for product onboarding, setup wizards, getting-started panels.
|
|
852
|
-
- `PricingTable([PricingCard(plan, price, period?, description?, features?, action?, badge?, featured?)])` — full pricing page block.
|
|
853
|
-
- `LoadingState(title?, description?, tone?, action?)`, `ErrorState(title, description?, action?, secondaryAction?, retryLabel?)`, `SuccessState(title, description?, action?, secondaryAction?)` — full-card empty-state alternatives for asynchronous content states.
|
|
854
|
-
- `Tour(steps, current, onFinish?)` and `Spotlight(title?, description?, action?)` are the product-tour primitives. `Spotlight` is a single highlighted call-out; `Tour` walks the user through multiple `{title, description, image?}` steps with Prev/Next/Skip controls and a progress dots indicator.
|
|
855
|
-
|
|
856
752
|
### Editors & overlays
|
|
857
|
-
- RichTextEditor(id: string, value?: string, placeholder?: string, minHeight?: string, disabled?: boolean) — Rich-text WYSIWYG editor for CMS, email, and comment surfaces. Renders a small toolbar (bold / italic / underline / strikethrough / headings / lists / quote / link) above a `contenteditable` region. Pass `$variable` as `value` for two-way binding — the HTML body is written back to state on every edit. Provide `placeholder` for the empty-state prompt.
|
|
858
|
-
- CodeEditor(id: string, value?: string, language?: "text"|"javascript"|"typescript"|"json"|"html"|"css"|"bash"|"python"|"sql"|"markdown", placeholder?: string, minHeight?: string, tabSize?: number, showGutter?: boolean, readonly?: boolean) — Lightweight, dependency-free code editor. Pairs a styled textarea with a synchronised line-number gutter — no syntax highlighting, but the editor stays a single rendered node so it works inside Shadow DOM. Use for dev tooling, snippet editing, prompt playgrounds. Pass a `$variable` as `value` for two-way binding. For read-only rendering with highlights prefer `CodeBlock`.
|
|
753
|
+
- RichTextEditor(id: string, value?: string, placeholder?: string, minHeight?: string, disabled?: boolean, onChange?: callable) — Rich-text WYSIWYG editor for CMS, email, and comment surfaces. Renders a small toolbar (bold / italic / underline / strikethrough / headings / lists / quote / link) above a `contenteditable` region. Pass `$variable` as `value` for two-way binding — the HTML body is written back to state on every edit. Provide `placeholder` for the empty-state prompt.
|
|
754
|
+
- CodeEditor(id: string, value?: string, language?: "text"|"javascript"|"typescript"|"json"|"html"|"css"|"bash"|"python"|"sql"|"markdown", placeholder?: string, minHeight?: string, tabSize?: number, showGutter?: boolean, readonly?: boolean, onChange?: callable) — Lightweight, dependency-free code editor. Pairs a styled textarea with a synchronised line-number gutter — no syntax highlighting, but the editor stays a single rendered node so it works inside Shadow DOM. Use for dev tooling, snippet editing, prompt playgrounds. Pass a `$variable` as `value` for two-way binding. For read-only rendering with highlights prefer `CodeBlock`.
|
|
859
755
|
- ContextMenu(target: Node, items: any[], label?: string) — Right-click (or long-press) menu that attaches to a child node. Wraps `target` and shows the menu at the pointer when the user right-clicks anywhere inside it. Items are `MenuItem(...)` nodes, `MenuSeparator()` entries, or `{label, action, icon?, shortcut?, variant?, disabled?, separator?}` objects. Use on table rows, tree nodes, kanban cards, file browser entries.
|
|
860
756
|
|
|
861
|
-
- `RichTextEditor(id, value?, placeholder?, minHeight?)` is the contenteditable WYSIWYG editor — toolbar ships with bold/italic/underline/strike/heading/lists/link. Bind `value` to a `$variable` holding HTML.
|
|
862
|
-
- `CodeEditor(id, value?, language?, placeholder?, minHeight?)` is a lightweight `<textarea>` with a synced line-number gutter and tab indentation. Use for snippet editors, prompt sandboxes, settings JSON.
|
|
863
|
-
- `ContextMenu(target, items)` attaches a right-click menu to any node. `items` are `MenuItem` or `{label, action?, icon?, shortcut?, variant?, disabled?}` objects; pass a `MenuSeparator()` to split groups.
|
|
864
|
-
|
|
865
757
|
### App shell
|
|
866
758
|
- AppShell(sidebar: Sidebar, content: Node[], topbar?: Node[], collapsible?: boolean, sidebarOpen?: boolean) — Canonical SaaS application shell: optional top bar, fixed left Sidebar, and scrollable main content. Reach for this whenever a response represents a full product surface (dashboard with nav, settings + sections, admin panels). Pass `collapsible=true` to render a hamburger that turns the sidebar into a slide-over drawer on narrow viewports.
|
|
867
759
|
- Sidebar(items: (SidebarItem | SidebarSection)[], brand?: string, tagline?: string, footer?: Node[], collapsed?: boolean) — Vertical app navigation panel. Supports a brand header, navigation items (`SidebarItem` or `SidebarSection`), an optional footer, and a `collapsed` mode that hides labels to leave just an icon rail. Use inside `AppShell` for SaaS-style left navigation.
|
|
868
760
|
- SidebarSection(label: string, items: SidebarItem[]) — Grouping inside a Sidebar — small uppercase label followed by SidebarItem entries. Use this to chunk a long sidebar into sections.
|
|
869
|
-
- SidebarItem(label: string, icon?: string, active?: boolean, badge?: string,
|
|
761
|
+
- SidebarItem(label: string, icon?: string, active?: boolean, badge?: string, to?: string, onClick?: callable) — Single navigation item inside a Sidebar. Pass `active=true` to mark as the current page, a `to` path to navigate via the runtime router on click, an `onClick` callable for arbitrary click handling, or an optional `badge` (string/number) for a trailing chip. `to` and `onClick` can coexist — `onClick` is invoked AFTER the router navigates so authors can do extra work (analytics, side-effects).
|
|
870
762
|
- SplitView(primary: Node[], detail: Node[], primaryWidth?: string) — Two-pane master/detail layout — a narrow primary pane on the left, wider detail pane on the right. Collapses to a single column on narrow viewports. Use for inboxes, file browsers, contact lists.
|
|
871
763
|
|
|
872
|
-
- App shell components produce a **full SaaS-style layout in a single statement**. Use them whenever the response represents a complete product surface (dashboards with nav, settings sections, admin consoles, inboxes).
|
|
873
|
-
- `AppShell(sidebar, content, topbar?, collapsible?, sidebarOpen?)` — fixed-left navigation + scrollable main area. Pass `collapsible=true` to enable a hamburger that turns the sidebar into a slide-over drawer on mobile; bind `sidebarOpen` to a `$variable` if you want to drive that drawer programmatically.
|
|
874
|
-
- `Sidebar(items, brand?, tagline?, footer?, collapsed?)` + `SidebarItem(label, icon?, active?, badge?, action?)` + `SidebarSection(label, items)` — group nav links into sections, mark the current page with `active=true`, attach badges for counts. Pass `collapsed=true` (or bind to a `$variable`) to collapse it to an icon rail.
|
|
875
|
-
- `SplitView(primary, detail, primaryWidth?)` — master/detail layout (inboxes, file browsers, contact lists). Both panes are scrollable.
|
|
876
|
-
|
|
877
764
|
### Theming
|
|
878
765
|
- Theme(tokens: any) — Apply a partial theme on top of the base theme. Pass an object of token → value pairs (colors, fonts, radii, spacing, button styling). Assigning the result to a top-level binding (conventionally `theme`) lets the runtime detect it and write the tokens to the host as CSS custom properties — the rest of the rendered UI picks them up instantly.
|
|
879
766
|
|
|
880
|
-
- `Theme({...})` applies a partial token override **on top of** the base theme set by the host (attribute / `setTheme()`). Use it to brand a single response without changing host configuration.
|
|
881
|
-
- Assign the result to a top-level binding called `theme` so the runtime picks it up:
|
|
882
|
-
`theme = Theme({ colors: { primary: "#0969da" }, radius: { button: "6px" } })`
|
|
883
|
-
- Tokens MUST use the structured form. Top-level groups: `colors`, `radius`, `font`, `motion`, `elevation` (plus metadata: `name`, `direction`).
|
|
884
|
-
- Common tokens (each lives inside its group): `colors.primary`, `colors.primaryHover`, `colors.primaryText`, `colors.accent`, `colors.bg`, `colors.surface`, `colors.text`, `colors.textMuted`, `colors.border`, `colors.focusRing`; `radius.md`, `radius.button`, `radius.input`; `font.family`, `font.familyHeading`, `font.sizeBase`, `font.weightHeading`; `motion.transitionDuration`; `elevation.md`.
|
|
885
|
-
- The legacy flat-shape form (`Theme({colorPrimary: ...})`) and free-form `--css-vars` are removed in Aktion 0.5 — the runtime drops them and the schema validator surfaces a migration warning.
|
|
886
|
-
- Tokens are CSS values (`"#0969da"`, `"'Inter', sans-serif"`, `"6px"`, `"600"`). The runtime ignores unknown keys inside a group, so typos fail silent.
|
|
887
|
-
- Removing the `Theme(...)` line snaps the UI back to the base theme without a reload.
|
|
888
|
-
|
|
889
767
|
### Advanced UI
|
|
890
|
-
- IconButton(icon: string, label: string,
|
|
768
|
+
- IconButton(icon: string, label: string, onClick?: callable, variant?: "primary"|"secondary"|"ghost"|"danger", size?: "xs"|"sm"|"md"|"lg"|"xl"|"small"|"normal"|"large", disabled?: boolean) — Icon-only button with an accessible label. Use for toolbars, table row actions, and compact controls.
|
|
891
769
|
- CommandPalette(items: any[], open?: boolean, placeholder?: string, shortcut?: string) — Cmd-K style searchable command list. Pass `items` as `{label, value, group?, shortcut?, action?}` objects.
|
|
892
770
|
- FilterChips(chips: any[], onRemove?: callable, onClear?: callable) — Removable filter chips with an optional clear-all control.
|
|
893
771
|
- FieldRepeater(items: any[], fields: any[], onAdd?: callable, onRemove?: callable, addLabel?: string) — Dynamic list of field groups. Pass `items` as row objects and `fields` as `{name, label, type?}` definitions.
|
|
@@ -900,238 +778,126 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
900
778
|
- InlineEdit(value: string, label?: string, onSave?: callable) — Click-to-edit inline field with save on Enter or blur.
|
|
901
779
|
- NotificationBell(count?: number, items?: any[], onOpen?: callable) — Bell icon with unread count badge and dropdown notification list.
|
|
902
780
|
|
|
903
|
-
- `IconButton(icon, label, action?, variant?, size?, disabled?)` — accessible icon-only control.
|
|
904
|
-
- `CommandPalette(items, open?, placeholder?, shortcut?)` — Cmd-K searchable actions.
|
|
905
|
-
- `FilterChips(chips, onRemove?, onClear?)` — applied filter pills with remove.
|
|
906
|
-
- `FieldRepeater(items, fields, onAdd?, onRemove?)` — dynamic form rows.
|
|
907
|
-
- `VirtualList(items, itemHeight?, renderItem)` — windowed long lists.
|
|
908
|
-
- `QueryBuilder(fields, value?)` — visual AND/OR filter builder.
|
|
909
|
-
- `DiffViewer(left, right, mode?)` — side-by-side or unified diff.
|
|
910
|
-
- `JsonTree(data)` — collapsible JSON inspector.
|
|
911
|
-
- `Gantt(tasks, startDate?, endDate?)` — horizontal schedule timeline.
|
|
912
|
-
- `Truncate(text, maxLines?)` / `InlineEdit(value, onSave?)` / `NotificationBell(count?, items?)`.
|
|
913
|
-
|
|
914
781
|
### Routing
|
|
915
782
|
- NavLink(label: string, to: string, variant?: "default"|"primary"|"ghost"|"pill", exact?: boolean, icon?: string) — Anchor that navigates to a route on click and stays in sync with the URL hash. Reflects `data-active="true"` when the current path matches `to` (set `exact=true` to require exact equality instead of prefix matching).
|
|
916
783
|
|
|
917
|
-
- Declare routes with the `_router_({...})` call form: `pages = _router_({ "/": Dashboard(), "/orders/:id": OrderDetail(id: params.id), default: NotFound() })`. The matched arm's `params` object is in scope on the right-hand side; nest `_router_` inside components for layout-preserving sub-routes.
|
|
918
|
-
- `Redirect(path)` is a router-aware component: returning it from a route's body navigates and unmounts the rest of the subtree.
|
|
919
|
-
- `NavLink(label, to)` is a thin link wrapper that reads `_route_.path` and dispatches `_route_.navigate(to)` — use it for sidebars, navbars and breadcrumbs.
|
|
920
|
-
- Read URL params via `_route_.params.<name>` (e.g. `_route_.params.id` for `/users/:id`) and the current path via `_route_.path`.
|
|
921
|
-
|
|
922
784
|
### Helpers
|
|
923
|
-
- Async(resource: any (positional), loading?: Node, error?: Node, empty?: Node, data?: Node) — Render `loading`, `error`, `empty`, or `data` slot based on an
|
|
785
|
+
- Async(resource: any (positional), loading?: Node, error?: Node, empty?: Node, data?: Node) — Render `loading`, `error`, `empty`, or `data` slot based on an `$http({...})` resource's state.
|
|
924
786
|
- Show(when: any (positional), fallback?: Node, children?: Node[]) — Conditional renderer. Sugar over `if expr { children } else { fallback }`.
|
|
925
787
|
- Portal(target?: string, children: Node[] (positional)) — Render children outside the parent subtree (e.g. into document.body).
|
|
926
788
|
- Redirect(path: string (positional)) — Navigate to `path` and unmount the rest of the subtree.
|
|
927
789
|
- Lazy(loader: any (positional), fallback?: Node, children?: Node[]) — Defer rendering `children` until `loader` resolves.
|
|
928
790
|
- ErrorBoundary(fallback?: Node, onError?: callable, children: Node[] (positional)) — Render a fallback subtree when rendering children throws.
|
|
929
791
|
|
|
930
|
-
|
|
931
|
-
-
|
|
932
|
-
-
|
|
933
|
-
-
|
|
934
|
-
-
|
|
935
|
-
-
|
|
792
|
+
### Behaviour wrappers
|
|
793
|
+
- OnClick(child: Node (positional), onClick: callable, disabled?: boolean, stopPropagation?: boolean) — Make any component clickable. Wraps the child in a transparent span and dispatches `onClick(event)` when the user clicks or taps anywhere inside it. Use to attach click behaviour to components that do not expose an `action` / `onClick` prop (cards, list rows, media tiles, custom layouts).
|
|
794
|
+
- OnMouse(child: Node (positional), enter?: callable, leave?: callable, hover?: callable, move?: callable, down?: callable, up?: callable, click?: callable, doubleClick?: callable, contextMenu?: callable, scroll?: callable, wheel?: callable, drag?: callable, drop?: callable, dragStart?: callable, dragEnd?: callable, dragEnter?: callable, dragLeave?: callable, dragOver?: callable, draggable?: boolean, passiveScroll?: boolean) — Attach any combination of mouse / pointer / drag listeners to a component. Pass only the props you need — unused events install no listener so the wrapper is essentially free. Each handler receives the native MouseEvent / DragEvent / WheelEvent. Use for hover tracking, custom drag-and-drop, context menus, scroll-aware UIs.
|
|
795
|
+
- OnKeyboard(child: Node (positional), onKeyDown?: callable, onKeyUp?: callable, onKeyPress?: callable, focusable?: boolean) — Attach keyboard listeners to a component. Pass any combination of `onKeyDown`, `onKeyUp`, and `onKeyPress`; each handler receives the native KeyboardEvent. Use for keyboard shortcuts, navigation, and custom focusable widgets. The wrapper is focusable by default (tabindex="0") so it can be reached via Tab; pass `focusable=false` to disable when the child is already focusable.
|
|
796
|
+
- OnFocus(child: Node (positional), onFocus?: callable, onBlur?: callable) — Attach focus / blur listeners to a component. Use to track input focus rings, custom focus indicators, or autosave-on-blur flows. Listens on the capture phase so blur from descendants is observed.
|
|
797
|
+
- OnIntersect(child: Node (positional), onEnter?: callable, onLeave?: callable, onChange?: callable, threshold?: number, rootMargin?: string, once?: boolean) — Observe whether a component is visible in the viewport (or a scroll container) using IntersectionObserver. Fires `onEnter` the first time the wrapped element becomes visible, `onLeave` when it leaves, and `onChange({visible, ratio})` for every transition. Use for lazy-load sentinels, infinite-scroll triggers, impression analytics, and reveal-on-scroll animations.
|
|
798
|
+
- Css(child: Node (positional), style?: string, class?: string | string[]) — Apply raw CSS class names and / or an inline style string to a wrapped component. The styling is merged onto the rendered child's DOM element — no extra wrapper element is added unless the child is plain text (in which case the styling lands on a wrapping span). Reach for `Css` only when the component's own props cannot express the styling (use `Box`/`Stack`/`Grid` props for layout, `Theme` for tokens, `Styles` + selector classes for sweeping changes).
|
|
799
|
+
- Link(label: string | Node (positional), to?: string, href?: string, external?: boolean, variant?: "default"|"subtle") — Anchor link. Accepts either a plain string label or a wrapped component as its positional child. Pass `to` for client-side router navigation (no page reload) or `href` for a regular anchor. `external: true` opens the link in a new tab with `rel="noopener noreferrer"`. Use to make any component clickable as a link — cards, icons, badges, list rows.
|
|
800
|
+
|
|
801
|
+
### Escape hatches
|
|
802
|
+
- HTMLTag(tag: string (positional), attributes?: object, children?: Node[]) — Escape-hatch primitive that renders an allow-listed HTML tag with the given attributes and children. Use ONLY when the standard component catalogue cannot express the markup (custom semantic elements, inline SVG, third-party widget mounts). Tag names outside the allow-list collapse to `div`. Attribute names matching `on*` (event handlers) are dropped, `href`/`src` are sanitised, and `style` is filtered for `expression()` / `javascript:` / `@import`. Pass children as an array of components — strings render as text nodes.
|
|
803
|
+
- Styles(css: string (positional)) — Escape-hatch primitive that injects a `<style>` block containing the given CSS rules. Use ONLY when a layout cannot be expressed via component props or the `$theme(...)` token map. The CSS is rendered verbatim into the document so authors can target their own `HTMLTag` markup or scope rules to a wrapper class. Payloads containing `</style>`, `<script>`, `expression(`, `javascript:`, `behavior:`, or `@import` are dropped for safety.
|
|
936
804
|
|
|
937
805
|
### Other
|
|
938
806
|
- TextContent(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", style?: string) — Deprecated alias for `Text`. Prefer `Text(...)` — both render identically.
|
|
939
807
|
|
|
940
808
|
## Examples
|
|
941
809
|
```
|
|
942
|
-
|
|
943
|
-
$tasks = http({ url: "
|
|
944
|
-
|
|
945
|
-
action toggle(task) {
|
|
946
|
-
$update = http({
|
|
947
|
-
url: "/api/tasks/" + task.id,
|
|
948
|
-
method: "PATCH",
|
|
949
|
-
body: { done: !task.done }
|
|
950
|
-
})
|
|
951
|
-
$tasks.refetch()
|
|
952
|
-
}
|
|
810
|
+
// Tasks dashboard — $http(), Async, action, multi-section layout
|
|
811
|
+
$tasks = $http({ url: "https://api.example.com/tasks", method: "GET" })
|
|
953
812
|
|
|
954
|
-
|
|
955
|
-
$
|
|
813
|
+
function toggle(task) {
|
|
814
|
+
$update = $http({ url: `https://api.example.com/tasks/${task.id}`, method: "PATCH", body: { done: !task.done } })
|
|
956
815
|
$tasks.refetch()
|
|
957
816
|
}
|
|
958
817
|
|
|
959
|
-
renderRow =
|
|
960
|
-
Badge(task.done ? "done" : "open", tone: task.done ? "success" : "neutral"),
|
|
961
|
-
Text(task.title, tone: task.done ? "muted" : "default"),
|
|
962
|
-
Buttons([
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
empty: EmptyState("No tasks yet", description: "Create your first task to get started.", icon: "list-check"),
|
|
975
|
-
data: Stack(for t in $tasks.data { renderRow(t) }, direction: "column", gap: "s")
|
|
976
|
-
)
|
|
977
|
-
], direction: "column", gap: "l")
|
|
978
|
-
}
|
|
979
|
-
|
|
980
|
-
_app_ = TasksPage()
|
|
818
|
+
renderRow = task => Card([Row([
|
|
819
|
+
Badge(task.done ? "done" : "open", { tone: task.done ? "success" : "neutral" }),
|
|
820
|
+
StackItem(Text(task.title, { tone: task.done ? "muted" : "default" }), { grow: 1 }),
|
|
821
|
+
Buttons([Button(task.done ? "Reopen" : "Done", { onClick: () => toggle(task), variant: "primary", size: "sm" })])
|
|
822
|
+
], { gap: "m" })])
|
|
823
|
+
|
|
824
|
+
aktion = Column([
|
|
825
|
+
PageHeader("Tasks", { subtitle: `${$tasks.data.length} items`, actions: [Button("Refresh", { onClick: $tasks.refetch, variant: "ghost" })] }),
|
|
826
|
+
Async($tasks, {
|
|
827
|
+
loading: LoadingState("Loading tasks…"),
|
|
828
|
+
error: ErrorState("Couldn't fetch tasks", { description: "Try again in a moment." }),
|
|
829
|
+
empty: EmptyState("No tasks yet", { description: "Create your first task." }),
|
|
830
|
+
data: Column($tasks.data.map(t => renderRow(t)), { gap: "s" })
|
|
831
|
+
})
|
|
832
|
+
], { gap: "l" })
|
|
981
833
|
```
|
|
982
834
|
```
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
"/":
|
|
988
|
-
|
|
989
|
-
"/calendar": Calendar(),
|
|
990
|
-
default: NotFound()
|
|
835
|
+
// Multi-page app shell with router and sidebar
|
|
836
|
+
pages = $router({
|
|
837
|
+
"/": Overview(),
|
|
838
|
+
"/projects": Projects(),
|
|
839
|
+
"/calendar": Calendar(),
|
|
840
|
+
default: NotFound()
|
|
991
841
|
})
|
|
992
842
|
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
renderNav("Projects", "folder", "/projects"),
|
|
999
|
-
renderNav("Calendar", "calendar", "/calendar")
|
|
1000
|
-
])
|
|
1001
|
-
])
|
|
843
|
+
nav = Sidebar([SidebarSection("Workspace", [
|
|
844
|
+
SidebarItem("Overview", { icon: "house", to: "/" }),
|
|
845
|
+
SidebarItem("Projects", { icon: "folder", to: "/projects" }),
|
|
846
|
+
SidebarItem("Calendar", { icon: "calendar", to: "/calendar" })
|
|
847
|
+
])])
|
|
1002
848
|
|
|
1003
|
-
|
|
849
|
+
aktion = AppShell(nav, pages)
|
|
1004
850
|
|
|
1005
|
-
|
|
1006
|
-
return
|
|
1007
|
-
PageHeader("Overview", subtitle: "Everything
|
|
851
|
+
function Overview() {
|
|
852
|
+
return Column([
|
|
853
|
+
PageHeader("Overview", { subtitle: "Everything across your workspace" }),
|
|
1008
854
|
Stats([
|
|
1009
|
-
StatCard("MRR", value: "$48.2k", trend: "up", delta: "+12%
|
|
1010
|
-
StatCard("Active users", value: "2,184", trend: "up", delta: "+184",
|
|
1011
|
-
StatCard("Open tickets", value: "23", trend: "down", delta: "-9",
|
|
855
|
+
StatCard("MRR", { value: "$48.2k", trend: "up", delta: "+12%", icon: "sack-dollar" }),
|
|
856
|
+
StatCard("Active users", { value: "2,184", trend: "up", delta: "+184", icon: "users" }),
|
|
857
|
+
StatCard("Open tickets", { value: "23", trend: "down", delta: "-9", icon: "ticket" })
|
|
1012
858
|
])
|
|
1013
|
-
],
|
|
859
|
+
], { gap: "l" })
|
|
1014
860
|
}
|
|
1015
861
|
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
```
|
|
862
|
+
function Projects() { return PageHeader("Projects") }
|
|
863
|
+
function Calendar() { return PageHeader("Calendar") }
|
|
864
|
+
function NotFound() { return PageHeader("Not found") }
|
|
1020
865
|
```
|
|
1021
|
-
# Contact form with two-way binding and validation
|
|
1022
|
-
$name = ""
|
|
1023
|
-
$email = ""
|
|
1024
|
-
$message = ""
|
|
1025
|
-
$sent = false
|
|
1026
|
-
|
|
1027
|
-
action submit() {
|
|
1028
|
-
if !$name || !$email { return }
|
|
1029
|
-
$post = http({ url: "/api/contact", method: "POST", body: { name: $name, email: $email, message: $message } })
|
|
1030
|
-
$sent = true
|
|
1031
|
-
}
|
|
1032
866
|
|
|
1033
|
-
|
|
867
|
+
## Streaming, output rules & verification
|
|
1034
868
|
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
Form("contact", btns, [
|
|
1038
|
-
FormControl("Name", Input("name", placeholder: "Your name", bind:value: $name)),
|
|
1039
|
-
FormControl("Email", Input("email", placeholder: "you@example.com", type: "email", bind:value: $email)),
|
|
1040
|
-
FormControl("Message", TextArea("message", placeholder: "Tell us more…", rows: 4, bind:value: $message))
|
|
1041
|
-
])
|
|
1042
|
-
])
|
|
869
|
+
### Hoisting & streaming (CRITICAL)
|
|
870
|
+
References resolve from the entire top-level scope, not source order. Emit the shell first so the renderer has somewhere to attach streamed leaves. Required statement order:
|
|
1043
871
|
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
])
|
|
872
|
+
1. `aktion = ...` — first line, always.
|
|
873
|
+
2. Function declarations (components & actions) and `$effect(...)` calls.
|
|
874
|
+
3. Leaf data values (strings, numbers, arrays, objects) — last.
|
|
1048
875
|
|
|
1049
|
-
|
|
1050
|
-
Card([Callout("success", "Message sent", description: `Thanks ${$name}, we'll be in touch at ${$email}.`, icon: "envelope-circle-check")])
|
|
1051
|
-
} else { null }
|
|
876
|
+
Define one named reference per FormControl, TabItem, AccordionItem, Series, Col, etc. so each one streams independently. Never split a single statement across multiple lines unless it sits inside an unmatched `[`, `(`, or `{`.
|
|
1052
877
|
|
|
1053
|
-
|
|
1054
|
-
```
|
|
878
|
+
### Output rules
|
|
879
|
+
- Output ONLY Aktion (or a fenced ```aktion``` block when inline mode is enabled).
|
|
880
|
+
- Build a complete, navigable surface — `PageHeader`, multi-section layouts, working buttons. Don't reply with a single Card.
|
|
881
|
+
- Wire every visible button. Declare `function name() { ... }` blocks (any case for the name); reference via `Button("Label", { onClick: name })`.
|
|
882
|
+
- Use `$router({...})` for multi-page apps; reach `pages` from `aktion`; link from sidebar/navbar with `NavLink`/`SidebarItem` (`to: "/path"`).
|
|
883
|
+
- Seed realistic mock data inline when no backend is available (5–20 plausible rows).
|
|
884
|
+
- Lay out with three primitives: `Column([...])` (vertical, the usual page/section), `Row([...])` (horizontal toolbars/rows), and `Grid([...], { columns })` (equal columns / card walls). `Center([...], { minHeight })` centers content. Use responsive prop maps (`{ base: 1, md: 2, lg: 4 }`) on `Grid` columns or `Stack` direction so the app works on phone and desktop.
|
|
885
|
+
- Use template literals for any string mixing copy with values.
|
|
886
|
+
- Tables are column-oriented: `Table([Col("Label", arr1), Col("Count", arr2, { format: "number" })])`. A column cell can be any component — the simplest form just maps each row to a component: `Col("Status", rows.map(r => Badge(r.status)))`, `Col("Actions", rows.map(r => Button("Edit", { onClick: () => edit(r.id) })))`. You can also keep `values` as the raw rows and pass `render: (value, index) => Component`. Make a column clickable with `onClick: (value, index) => …`. Both work in `Table` and `DataGrid`.
|
|
887
|
+
- Charts need numeric arrays. Use array pluck: `PieChart(rows.label, rows.value)`.
|
|
888
|
+
- Icons are Font Awesome names (no `fa-` prefix, no emoji).
|
|
889
|
+
- Named arguments use a trailing `{ prop: value }` object — never bare `prop: value` in a call.
|
|
1055
890
|
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
defined. The renderer re-parses the program on every streamed chunk and
|
|
1060
|
-
silently treats unresolved references as empty, so a partially-streamed
|
|
1061
|
-
response renders progressively without flashing errors.
|
|
1062
|
-
|
|
1063
|
-
**Required statement order for streaming-friendly output:**
|
|
1064
|
-
1. `_app_ = ...` — emit this FIRST so the UI shell appears immediately.
|
|
1065
|
-
2. `component` / `action` / `effect` declarations — fill in layout & behaviour.
|
|
1066
|
-
3. Leaf data values — strings, numbers, arrays, objects — last.
|
|
1067
|
-
|
|
1068
|
-
**Streaming rules — follow strictly:**
|
|
1069
|
-
- Always reference children by name from the root (`_app_ = Stack([hero, body, footer])`).
|
|
1070
|
-
- Define one reference per FormControl, TabItem, AccordionItem, Series, Col —
|
|
1071
|
-
so each one streams in independently.
|
|
1072
|
-
- Place large data values on their own trailing lines.
|
|
1073
|
-
- Never split a single statement across multiple lines unless it sits inside
|
|
1074
|
-
an unmatched bracket (`[`, `(`, `{`).
|
|
1075
|
-
- Do not introduce trailing commas, dangling operators, or open brackets you
|
|
1076
|
-
don't close on the same line.
|
|
1077
|
-
|
|
1078
|
-
## Output rules
|
|
1079
|
-
|
|
1080
|
-
- **Build a complete application.** Reply with a substantive, navigable
|
|
1081
|
-
product surface — page headers, sidebars, multiple pages, data views,
|
|
1082
|
-
KPIs, toolbars, working actions. Never reply with a single Card or a
|
|
1083
|
-
chat-style bubble.
|
|
1084
|
-
- Output ONLY Aktion (or a fenced ```aktion
|
|
1085
|
-
block when inline mode is enabled).
|
|
1086
|
-
- Always start with `_app_ = ...` on the very first line.
|
|
1087
|
-
- Prefer many small, named statements over deeply nested inline expressions —
|
|
1088
|
-
this is what makes streaming work.
|
|
1089
|
-
- Order statements top-down: `_app_` first, then components /
|
|
1090
|
-
actions / effects, then leaf data.
|
|
1091
|
-
- **Seed realistic mock data inline.** When no backend is available, write
|
|
1092
|
-
5–20 believable rows per dataset (real names, dates, numbers, statuses)
|
|
1093
|
-
inside `$state` declarations. Pages read from these atoms so changes
|
|
1094
|
-
propagate live.
|
|
1095
|
-
- **Wire every visible button.** Declare `action Name() { … }` blocks and
|
|
1096
|
-
reference them via `Button("Label", onClick: name)`. No dead buttons —
|
|
1097
|
-
forms submit by dispatching an action that writes to `$state`.
|
|
1098
|
-
- **Use `_router_({...})` for multi-page apps.** Declare `pages = _router_({ "/": Home(), … })` once,
|
|
1099
|
-
reference `pages` from `_app_`, link routes from the sidebar /
|
|
1100
|
-
navbar with `NavLink(label, to)`. Each route must be a substantive
|
|
1101
|
-
page (PageHeader + at least one data view + at least one action).
|
|
1102
|
-
- **Match real-product polish.** Use `Stats`, `PageHeader`, `Toolbar`,
|
|
1103
|
-
`Badge` / `StatusDot` for state, `PersonChip` / `Avatar` where
|
|
1104
|
-
people appear, `EmptyState` for empty lists. Pair text-heavy sections
|
|
1105
|
-
with plausible `Image` URLs.
|
|
1106
|
-
- **Use responsive prop maps** (`{sm: 1, md: 2, lg: 4}`) for `Grid` and
|
|
1107
|
-
`Stack` so the app works on phone AND desktop.
|
|
1108
|
-
- **Use template literals** for any string mixing copy with values:
|
|
1109
|
-
```${@Count(rows)} ${@Plural(@Count(rows), "order", "orders")}```
|
|
1110
|
-
reads much better than `+` concatenation.
|
|
1111
|
-
- Icons are Font Awesome names without the `fa-` prefix — never emoji.
|
|
1112
|
-
- Do not invent component names that are not in the library above.
|
|
1113
|
-
- Use expression-form `if` / `match` / `for` for control flow.
|
|
1114
|
-
- Use `http({ ... })` for every HTTP request; observe `.data`,
|
|
1115
|
-
`.error`, `.loading`, `.status`, `.refetch()`.
|
|
1116
|
-
- Never declare a state slot named `route` yourself. The router exposes
|
|
1117
|
-
its reactive surface through the reserved `_route_` handle — read
|
|
1118
|
-
`_route_.path` / `_route_.params` and call
|
|
1119
|
-
`_route_.navigate("/path")` to navigate.
|
|
1120
|
-
|
|
1121
|
-
## Final verification
|
|
1122
|
-
|
|
1123
|
-
Before finishing, walk your output and verify:
|
|
1124
|
-
1. `_app_ = ...` is the FIRST line.
|
|
891
|
+
### Final verification
|
|
892
|
+
Before finishing, walk your output and check:
|
|
893
|
+
1. `aktion = ...` is the FIRST line.
|
|
1125
894
|
2. Every referenced name is defined somewhere below.
|
|
1126
|
-
3. Every defined name (other than `
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
5. No statement is split across multiple lines unless it sits inside an
|
|
1131
|
-
unmatched `[`, `(`, or `{`.
|
|
1132
|
-
6. Components end with an explicit `return` statement.
|
|
895
|
+
3. Every defined name (other than `aktion`, `theme`) is reachable from `aktion`.
|
|
896
|
+
4. **Function name case is NOT significant.** `function Card(...)` and `function card(...)` both declare a component-and-action; the same applies to arrow bindings.
|
|
897
|
+
5. **Every component reference is invoked with parentheses.** Scan for bare component identifiers used as values (root assignment, array elements, prop values) — wrap each in `()`. `aktion = MyApp` → `aktion = MyApp()`; `Column([Hero, Body])` → `Column([Hero(), Body()])`. The only exception is passing a component as a callback (e.g. `render: UserCard`) where the caller invokes it.
|
|
898
|
+
6. A function with no `return` simply renders nothing when called in a render position.
|
|
1133
899
|
7. State uses the single-sigil `$name = value` form.
|
|
1134
|
-
8.
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
900
|
+
8. `$http({...})` uses an absolute `url` and exposes `.data`, `.error`, `.loading`, `.status`, `.refetch()`, `.cancel()`.
|
|
901
|
+
9. `$router({...})` arms use `:` (not `->`) and `default` (not `_`) for the wildcard.
|
|
902
|
+
10. Effects use `$effect(() => {...}, [deps])` — never the legacy bracket form.
|
|
903
|
+
11. `storage` / `console` are lowercase; `route` is reserved (never declare it).
|