aktion-runtime 0.5.9 → 0.5.11
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 +216 -36
- package/dist/aktion.iife.js +920 -144
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +17025 -10815
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +920 -144
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/devtools.js +554 -20
- package/dist/devtools.js.map +1 -1
- package/dist/language.js +7042 -2455
- package/dist/language.js.map +1 -1
- package/dist/plugin.cjs +2 -2
- package/dist/plugin.cjs.map +1 -1
- package/dist/plugin.js +2 -2
- package/dist/plugin.js.map +1 -1
- package/dist/system_prompt.txt +292 -41
- package/dist/system_prompt_chat.txt +14 -14
- package/dist/testing.js +16223 -7977
- package/dist/testing.js.map +1 -1
- package/dist/types/devtools/panel.d.ts +32 -0
- package/dist/types/devtools/styles.d.ts +1 -1
- package/dist/types/element.d.ts +26 -0
- package/dist/types/icons/index.d.ts +10 -0
- package/dist/types/library/components/_internal.d.ts +18 -0
- package/dist/types/library/components/a11y.d.ts +5 -0
- package/dist/types/library/components/canvas.d.ts +3 -0
- package/dist/types/library/components/extras.d.ts +15 -0
- package/dist/types/library/components/feedback.d.ts +1 -0
- package/dist/types/library/components/forms-shared.d.ts +55 -0
- package/dist/types/library/components/layout-motion.d.ts +14 -0
- package/dist/types/library/components/layout.d.ts +1 -0
- package/dist/types/library/components/marketing.d.ts +35 -0
- package/dist/types/library/components/new-components.d.ts +1 -0
- package/dist/types/library/components/scheduling.d.ts +2 -0
- package/dist/types/library/components/wave3.d.ts +6 -0
- package/dist/types/library/highlight.d.ts +21 -0
- package/dist/types/library/qr.d.ts +12 -0
- package/dist/types/library/responsive-style.d.ts +51 -0
- package/dist/types/library/sx.d.ts +51 -0
- package/dist/types/library/types.d.ts +50 -0
- package/dist/types/library/utils.d.ts +28 -0
- package/dist/types/library/validate.d.ts +2 -2
- package/dist/types/runtime/env.d.ts +33 -0
- package/dist/types/runtime/evaluator.d.ts +38 -0
- package/dist/types/runtime/http.d.ts +37 -1
- package/dist/types/runtime/index.d.ts +2 -0
- package/dist/types/runtime/namespaces-extra.d.ts +73 -0
- package/dist/types/runtime/realtime.d.ts +46 -0
- package/dist/types/runtime/router.d.ts +42 -4
- package/dist/types/runtime/ssr.d.ts +29 -0
- package/dist/types/runtime/util.d.ts +65 -0
- package/dist/types/testing/index.d.ts +35 -0
- package/dist/types/theme/fonts.d.ts +30 -0
- package/dist/types/theme/index.d.ts +31 -0
- package/dist/types/theme/styles.d.ts +1 -1
- package/dist/types/tooling/html-import.d.ts +19 -0
- package/dist/types/tooling/index.d.ts +3 -0
- package/dist/types/tooling/schema.d.ts +58 -0
- package/dist/types/tooling/signature-help.d.ts +35 -0
- package/package.json +1 -1
package/dist/system_prompt.txt
CHANGED
|
@@ -22,15 +22,17 @@ $effect(() => $console.log($count), [$count]) // declarative
|
|
|
22
22
|
|
|
23
23
|
### Two rules, broken constantly — always check
|
|
24
24
|
1. **Invoke components with parentheses.** A component is a function; the bare name is just its value. Render it by calling it, even with no args: `$app(MyApp())` not `$app(MyApp)`; `Column([Header(), Body()])` not `Column([Header, Body])`. (Exception: passing a component as a callback, e.g. `render: UserCard`.)
|
|
25
|
-
2. **
|
|
25
|
+
2. **Argument forms** (per call, pick ONE): the canonical form is one bare positional — the prop tagged `(positional)` in the signature — plus a trailing `{ }` object for every other prop. Also supported: ALL-positional (arguments bind to the signature's props in listed order, so only use it for adjacent leading props), and ALL-named (a single `{ }` object naming every prop). Never split one object between roles.
|
|
26
26
|
|
|
27
27
|
```
|
|
28
|
-
Button("Save", { variant: "primary", loading: $isSaving })
|
|
28
|
+
Button("Save", { variant: "primary", loading: $isSaving }) // canonical: positional + trailing object
|
|
29
29
|
StatCard("Revenue", { value: "$48k", trend: "up", delta: "+12%" })
|
|
30
|
-
|
|
30
|
+
StatCard("Revenue", "$48k", "up") // all-positional, signature order
|
|
31
|
+
Button({ label: "Save", variant: "primary" }) // all-named single object
|
|
32
|
+
Row([Card1(), Card2()], { gap: "md" })
|
|
31
33
|
```
|
|
32
34
|
|
|
33
|
-
`Button("Save", "primary")`
|
|
35
|
+
Mind the signature order with all-positional calls: `Button("Save", "primary")` puts `"primary"` in the second slot (`onClick`), NOT `variant` — prefer the trailing object for non-adjacent props. A lone object argument to a component whose positional prop is itself object-typed is that prop's payload, not named props. Any call also accepts `{ key: ... }` to pin per-instance state across reorders.
|
|
34
36
|
|
|
35
37
|
### Reserved top-level names
|
|
36
38
|
- `$app(...)` — registers the UI root (REQUIRED).
|
|
@@ -139,6 +141,27 @@ function CartBadge() { return Badge(`${cart.items.length} items`) }
|
|
|
139
141
|
|
|
140
142
|
Use a store for shared state; use a component's local `$state` / `$name` for state one component owns.
|
|
141
143
|
|
|
144
|
+
Add `persist: "key"` to mirror the store's data to `localStorage` (or `persistIn: "session"` for `sessionStorage`): declared fields hydrate from the saved snapshot on first render and every change writes back. `persist` / `persistIn` are config, not state fields.
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
prefs = $store({
|
|
148
|
+
persist: "user-prefs", // restored on reload, saved on every change
|
|
149
|
+
theme: "system",
|
|
150
|
+
setTheme: (s, t) => { s.theme = t },
|
|
151
|
+
})
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Add `history: true` (or `history: 50` for a depth cap) for **undo/redo**: the store gains `store.undo()` / `store.redo()` / `store.clearHistory()` methods and reactive `store.canUndo` / `store.canRedo` flags (wire them to button `disabled`). Each user mutation records a snapshot; a fresh edit after undo clears the redo branch.
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
doc = $store({
|
|
158
|
+
history: true,
|
|
159
|
+
title: "", body: "",
|
|
160
|
+
setTitle: (s, t) => { s.title = t },
|
|
161
|
+
})
|
|
162
|
+
undoBtn = Button("Undo", { onClick: () => doc.undo(), disabled: !doc.canUndo })
|
|
163
|
+
```
|
|
164
|
+
|
|
142
165
|
## Components & Actions
|
|
143
166
|
|
|
144
167
|
A `function` declaration is both a **component** (call it in render position → its return value renders) and an **action** (call it from an event handler → its body runs). Name case is not significant, and a function with no `return` renders nothing.
|
|
@@ -158,6 +181,8 @@ $app(Column([UserCard($currentUser), UserCard($other, { tone: "primary" })]))
|
|
|
158
181
|
- The positional argument lands in the component's first parameter (the `children` slot for container-style components).
|
|
159
182
|
- User components shadow built-ins of the same name — wrap a library component to add telemetry or styling.
|
|
160
183
|
- Use a lambda (`row = item => Row(item)`) for one-off helpers that don't need a named component.
|
|
184
|
+
- **Named slots** (XIII.1): once positional args fill the params, extra named props become both a `slots` object and direct bindings — `function Panel(children) { return Column([slots.header, children, footer]) }` called as `Panel(body, { header: H, footer: F })`.
|
|
185
|
+
- **Component-local helpers** (XIII.4): a `function Row() {…}` declared inside another component's body is scoped to it (callable by siblings, not leaked globally).
|
|
161
186
|
|
|
162
187
|
### Actions
|
|
163
188
|
A `function` whose body runs for side effects is an action — use it as a handler (`onClick: save`) or call it for its result. `return` is optional; the full JS statement surface applies. Wrap optimistic writes in `$optimistic(() => { … })` to snapshot state and auto-roll-back if the callback throws (or its promise rejects).
|
|
@@ -181,6 +206,29 @@ resetBtn = Button("Reset", { onClick: () => { $count = 0; $message = "" } })
|
|
|
181
206
|
### `$emit("name", { detail })`
|
|
182
207
|
From any action / effect / lambda, `$emit` dispatches a `CustomEvent` on the host `<aktion-app>` (listen with `el.addEventListener`). Reserved names: `assistant-message`, `error`, `route-change`.
|
|
183
208
|
|
|
209
|
+
### Reactive environment globals (under `$util`)
|
|
210
|
+
Read-only reactive namespaces the UI branches on without manual listeners (listeners attach lazily on first read, re-render on change). They live under `$util` so the top-level `$`-name space stays free for your own atoms:
|
|
211
|
+
- `$util.viewport.width` / `.height`
|
|
212
|
+
- `$util.breakpoint.active` (`base|sm|md|lg|xl`) + `.sm` / `.md` / `.lg` / `.xl` booleans
|
|
213
|
+
- `$util.scroll.y` / `.x` / `.progress` (0–1) / `.direction` (`up|down`)
|
|
214
|
+
- `$util.media.prefersDark` / `.prefersReducedMotion` / `.online` / `.pointer` (`coarse|fine`) / `.portrait`
|
|
215
|
+
- `$util.mouse.x` / `.y`
|
|
216
|
+
- `$util.url.path` / `.params` (route params) / `.query` (parsed object) / `.hash` + `.navigate(to)` / `.setQuery(name, value)` / `.setQuery({…})` / `.removeQuery(name)` — a reactive snapshot of the current URL plus query-param writers (IV.6).
|
|
217
|
+
|
|
218
|
+
```
|
|
219
|
+
Show($util.breakpoint.md, { children: Sidebar(), fallback: Drawer() })
|
|
220
|
+
NavBar({ blur: $util.scroll.y > 12 })
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### `$util.onError(fn)`
|
|
224
|
+
Register a program-level error sink: `fn({ error, source })` fires when a user action body throws (before the default logging) — report to a telemetry sink or surface a toast so a bad row never blanks the page.
|
|
225
|
+
|
|
226
|
+
### `$util.onNavigate(fn)`
|
|
227
|
+
Register a navigation guard: `fn({ to, from })` runs before every route change (in-app `navigate(...)` and browser back/forward). Return `false` to block, a path string to redirect, or nothing to allow. `$util.onNavigate(null)` clears it.
|
|
228
|
+
|
|
229
|
+
### `$util.onRequest(fn)` / `$util.onResponse(fn)`
|
|
230
|
+
Cross-cutting HTTP interceptors for every `$http` / `$query` / `$mutation` request (VI.5). `$util.onRequest(req => ({ headers: { Authorization: "Bearer " + $token } }))` returns a partial that is merged over the request (headers shallow-merged) — ideal for auth tokens. `$util.onResponse(async (res, retry) => …)` can inspect/replace the response or `await retry()` to re-issue once (e.g. after refreshing a token on a 401). They reset on each new program.
|
|
231
|
+
|
|
184
232
|
## Effects — Declarative side effects
|
|
185
233
|
|
|
186
234
|
`$effect(() => { ... }, [...deps])` runs side effects. Dep entries: `$atom` (re-run on change), `"mount"` / `"unmount"` (once), `"every(N)"` (every N ms), `"debounce(N)"` / `"throttle(N)"` (trailing-edge rate limit). No second argument ≡ `["mount"]`.
|
|
@@ -235,7 +283,7 @@ view = Async($orders, {
|
|
|
235
283
|
|
|
236
284
|
### `$query({...})` and `$mutation({...})`
|
|
237
285
|
Same config shape as `$http`, for two common needs:
|
|
238
|
-
- `$query({ url, key?, ttl? })` — a **cached, deduplicated** read. Identical queries (same `key`, or same method+url+query+body) share one in-flight request and one cached bag, so calling it from several components fetches once. Pass `ttl` (ms) to auto-refetch stale data. Same bag as `$http` (`.data`/`.loading`/`.error`/`.refetch()`).
|
|
286
|
+
- `$query({ url, key?, ttl?, refetchInterval?, refetchOnFocus?, refetchOnReconnect? })` — a **cached, deduplicated** read. Identical queries (same `key`, or same method+url+query+body) share one in-flight request and one cached bag, so calling it from several components fetches once. Pass `ttl` (ms) to auto-refetch stale data, `refetchInterval` (ms) to poll a live dashboard, and `refetchOnFocus` / `refetchOnReconnect` to refresh on tab focus / network reconnect. Same bag as `$http` (`.data`/`.loading`/`.error`/`.refetch()`).
|
|
239
287
|
- `$mutation({ url, method? })` — a **deferred** write that fires only when you call `.mutate(overrides?)`, not on render (method defaults to `POST`). Assign it to an atom, then trigger it from a handler:
|
|
240
288
|
```
|
|
241
289
|
$save = $mutation({ url: "https://api.example.com/orders" })
|
|
@@ -245,6 +293,25 @@ Button("Save", { onClick: () => $save.mutate({ body: { item: $item } }) })
|
|
|
245
293
|
```
|
|
246
294
|
`.mutate()` resolves with the response body; the bag exposes `.loading`/`.error`/`.data` plus `.reset()`.
|
|
247
295
|
|
|
296
|
+
**Optimistic + invalidation (VI.2):** `$mutation({ url, optimistic: () => { … }, invalidates: ["key"] })` — `optimistic` runs synchronously before the request so the UI updates instantly (auto-rolled-back if it fails); `invalidates` refetches every cached `$query` whose key contains a listed substring once the write succeeds. `$util.invalidate("key")` does the same on demand.
|
|
297
|
+
|
|
298
|
+
**Infinite / paginated reads (VI.1):** `$feed = $query({ url, infinite: { param?: "page", start?: 1, limit?: 20, mode?: "page"|"offset", select?: body => body.items } })` — `.data` is the flattened item list across loaded pages; call `.loadMore()` (often from `OnIntersect`) while `.hasMore` is true; `.loadingMore` flags the in-flight next page.
|
|
299
|
+
|
|
300
|
+
**GraphQL (VI.6):** add `gql` (+ optional `variables`) to any `$http`/`$query`/`$mutation`: it POSTs `{ query, variables }` and `.data` is the unwrapped GraphQL `data` (a GraphQL `errors` array surfaces through `.error`).
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
$repos = $query({ url: "/graphql", gql: "query($n:Int){ repos(first:$n){ name } }", variables: { n: 10 } })
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
### Realtime — `$socket({...})` and `$sse({...})` (VI.3)
|
|
307
|
+
- `$socket({ url, protocols?, bufferSize?, onMessage?, reconnect? })` — a reactive WebSocket. Read `.status` (`"connecting"|"open"|"closed"`), `.connected`, `.last`, `.messages` (re-render on change); `.send(data)` (objects auto-JSON; messages sent while connecting queue and flush on open); `.close()` (stops for good). `reconnect: true` (or a max-attempt number) retries dropped connections with exponential backoff — `.attempts` counts the current streak.
|
|
308
|
+
- `$sse({ url, event?, withCredentials?, bufferSize? })` — a reactive Server-Sent Events stream with the same `.status`/`.connected`/`.last`/`.messages`/`.close()` surface (EventSource reconnects natively). Both tear down automatically on the next program.
|
|
309
|
+
```
|
|
310
|
+
$chat = $socket({ url: "wss://example.com/room/42" })
|
|
311
|
+
send = () => { $chat.send({ text: $draft }); $draft = "" }
|
|
312
|
+
feed = Column(map($chat.messages, m => Bubble(m.text)))
|
|
313
|
+
```
|
|
314
|
+
|
|
248
315
|
## Routing
|
|
249
316
|
|
|
250
317
|
`$router({ ... })` is a plain function call — assign it and drop the result into your page shell.
|
|
@@ -261,9 +328,32 @@ $app(AppShell(MainSidebar(), pages)) // app/dashboard shell
|
|
|
261
328
|
|
|
262
329
|
- **Pick the shell for the surface.** `AppShell(Sidebar(...), pages)` for an app/dashboard (left sidebar + optional topbar); a top `Navbar(...)` above the pages inside a `Column` for a website / marketing / docs layout (no sidebar) — never wrap a website in `AppShell`. The router result is just a node, so it drops into either.
|
|
263
330
|
- Patterns: literal, `:param` (read `params.id`), trailing `*` (read `params._`), and `default:` for the catch-all (unknown paths render `null` without it).
|
|
264
|
-
- The read-only `route` handle: `route.path`, `route.params.x`, `route.query.tab`; navigate with `route.navigate("/path")` from an action/effect.
|
|
331
|
+
- The read-only `route` handle: `route.path`, `route.params.x`, `route.query.tab`; navigate with `route.navigate("/path")` from an action/effect. `$util.url` mirrors this (`$util.url.path` / `.params` / `.query` / `.hash`).
|
|
332
|
+
- **Query-param ↔ state** (IV.6): write the URL query without leaving the page — `$util.url.setQuery("tab", "billing")`, `$util.url.setQuery({ sort: "name", page: 2 })` (a `null`/`""` value drops the key), or `$util.url.removeQuery("tab")`. Read it back reactively via `$util.url.query.tab` (or `route.query.tab`), so a tab/sort/filter survives reload and is shareable.
|
|
333
|
+
- **Navigation guards** (IV.2): `$util.onNavigate(fn)` registers a guard. `fn({ to, from })` returns `false` to block, a path string to redirect, or nothing to allow — covers in-app `navigate(...)` and browser back/forward. Call `$util.onNavigate(null)` to clear.
|
|
334
|
+
- **Scroll restoration** (IV.5): set `scroll-restoration="auto"` on `<aktion-app>` to restore scroll on back/forward and jump to top on a fresh navigation (`"top"` always jumps to top).
|
|
335
|
+
- **Nested / layout routes** (IV.1): an arm whose value is `{ layout, routes }` matches as a path PREFIX and slots the matched child into the `outlet` identifier — so a shell (sidebar/topbar) stays mounted while only the inner page swaps. Child route keys are matched against the remaining path; `params` merges parent + child captures.
|
|
336
|
+
```
|
|
337
|
+
pages = $router({
|
|
338
|
+
"/app": {
|
|
339
|
+
layout: AppShell(MainSidebar(), outlet), // `outlet` = the matched child
|
|
340
|
+
routes: {
|
|
341
|
+
"/": Dashboard(),
|
|
342
|
+
"/orders/:id": OrderDetail({ id: params.id }),
|
|
343
|
+
default: AppHome()
|
|
344
|
+
}
|
|
345
|
+
},
|
|
346
|
+
default: Landing()
|
|
347
|
+
})
|
|
348
|
+
```
|
|
265
349
|
- `NavLink(label, { to, exact?, icon? })` and `SidebarItem(label, { to, icon?, badge? })` derive active state from `route.path`. Never declare `route` yourself.
|
|
266
350
|
|
|
351
|
+
```
|
|
352
|
+
$util.onNavigate(({ to }) => $isLoggedIn || to === "/login" ? true : "/login") // auth gate
|
|
353
|
+
function selectTab(name) { $util.url.setQuery("tab", name) } // shareable tab
|
|
354
|
+
activeTab = $util.url.query.tab ?? "overview"
|
|
355
|
+
```
|
|
356
|
+
|
|
267
357
|
## Built-in globals — `storage`, `console` & `$toast`
|
|
268
358
|
|
|
269
359
|
Always in scope, lowercase, no imports.
|
|
@@ -319,16 +409,48 @@ $app(Column([
|
|
|
319
409
|
]))
|
|
320
410
|
```
|
|
321
411
|
|
|
412
|
+
## Universal style props (`sx` / `animate`) — every component
|
|
413
|
+
|
|
414
|
+
EVERY component accepts a universal style/behaviour channel as named props, in addition to its own props. These are **bounded** (tokens & enums, never raw CSS) so they stay theme-safe — prefer them over the `Css`/`Styles`/`HTMLTag` escape hatches.
|
|
415
|
+
|
|
416
|
+
- **`sx: { … }`** — token-aware inline styling. Keys (all optional):
|
|
417
|
+
- Spacing (`none|3xs|2xs|xs|sm|md|lg|xl|2xl|3xl|auto` (`none` = 0), the `safe`/`safe-top`/`safe-right`/`safe-bottom`/`safe-left` notch insets, or a CSS length): `p px py pt pr pb pl`, `m mx my mt mr mb ml`, `gap`. `px`/`mx` are logical (`padding-inline`) and `ps pe ms me` set the inline start/end sides, so RTL apps mirror automatically.
|
|
418
|
+
- Sizing (`full|half|screen|dvh|min|max|fit|auto` or length): `w h minW maxW minH maxH`.
|
|
419
|
+
- Color (token `surface|bg|text|text-muted|primary|accent|success|warning|danger|border`, a gradient ref `gradient.brand|accent|warm|cool|success|danger`, or a raw color): `bg color borderColor`.
|
|
420
|
+
- Surface: `border: none|subtle|strong|<color>`, `radius: xs|sm|md|lg|pill|full`, `shadow: sm|md|lg|none`, `opacity`, `backdrop: "blur"`, `bgImage` (http(s)/relative/data:image only) + `bgOverlay` (color or `gradient.*` wash over the image), `bgSize: cover|contain`.
|
|
421
|
+
- Typography: `fontSize: xs|sm|base|lg|xl|2xl|3xl|4xl` (or a length), `weight: 100…900|bold|normal`, `textDecoration: underline|line-through|none`, `textAlign`.
|
|
422
|
+
- Flex/grid: `display direction align justify wrap grow shrink basis columns`.
|
|
423
|
+
- Position: `position top right bottom left inset zIndex(base|dropdown|sticky|modal|toast|…)`, `overflow cursor`. Layer tokens resolve through `--rui-z-*` so `$theme({ zIndex: {...} })` rebrands them.
|
|
424
|
+
- Interaction: `hover: { lift|grow|glow|bright|border|scale }`, `focus: { glow|border }` (mapped to bounded utility classes). For arbitrary state CSS use `states: { hover|focus|active|disabled|focus-visible|checked|group-hover: { bg, color, borderColor, shadow, radius, opacity, scale, translateX, translateY, rotate, cursor } }` — compiled to scoped `:state` rules in the adopted stylesheet. Example: `sx: { states: { hover: { scale: 1.04, shadow: "lg" }, focus: { borderColor: "primary" } } }` (I.4).
|
|
425
|
+
- Responsive: any value may be `{ base, sm, md, lg, xl }` (resolves to `base`).
|
|
426
|
+
- **`animate: "fade-up"`** (or `{ preset, delay?, duration?, repeat? }`) — entrance/loop motion. Presets: `fade fade-up/down/left/right zoom slide-up/down/left/right pulse float shimmer bounce spin ping wiggle`. Auto-respects `prefers-reduced-motion`.
|
|
427
|
+
- **`id` / `anchor`** — set the element id (smooth-scroll targets).
|
|
428
|
+
- **`className` / `style`** — extra classes / a sanitised inline style string.
|
|
429
|
+
- **`aria: {…}` / `data: {…}` / `tooltip` / `hidden`** — accessibility & metadata passthrough.
|
|
430
|
+
|
|
431
|
+
```
|
|
432
|
+
Card([Text("Lift on hover")], { sx: { p: "l", radius: "lg", bg: "surface", shadow: "md", hover: { lift: true } } })
|
|
433
|
+
Badge("Live", { tone: "success", animate: "pulse" })
|
|
434
|
+
Display(["Build in ", GradientText("record time")], { size: "hero", align: "center", animate: "fade-up" })
|
|
435
|
+
```
|
|
436
|
+
|
|
322
437
|
## Theming, i18n & icons
|
|
323
438
|
|
|
324
439
|
### `$theme({ ... })`
|
|
325
|
-
A bare `$theme({...})` statement (near the top) brands the response.
|
|
440
|
+
A bare `$theme({...})` statement (near the top) brands the response. Only the **structured form** is accepted — top-level keys must be a token group (`colors`, `radius`, `font`, `spacing`, `shadows`, `gradients`, `zIndex`, `motion`, `fonts`, `icons`) or a metadata key (`name`, `direction`). Flat-shape keys like `$theme({ colorPrimary: ... })` raise a schema error; unknown keys inside a group are silently ignored. **Every token value is a string.** Omit the whole call to inherit the host theme. `zIndex` layer tokens (`{ modal: 2000, toast: 2100, … }`) feed `sx.zIndex`; `motion` (`{ fast, base, slow, ease }`) → `--rui-motion-*`. Gradients accept color-stop arrays (`gradients: { brand: ["#6366f1", "#ec4899"] }`) and are referenced as `gradient.brand` in `sx`/`GradientText`. Custom icons register inline SVG by name (`icons: { logo: "<path …/>" }`) and are then usable anywhere a Font Awesome name is — `Icon("logo")`. Load web fonts with `fonts: { import: ["Inter:400,700", "JetBrains Mono"] }` (Google Fonts shorthand) alongside the `font.family` token.
|
|
441
|
+
|
|
442
|
+
Core group keys (all optional):
|
|
443
|
+
- `name?: string` — selects a built-in theme as the base palette (`"dark"`, `"neon"`, …; unknown names are ignored).
|
|
444
|
+
- `direction?: "ltr" | "rtl"` — reading direction (metadata; not applied as a token).
|
|
445
|
+
- `colors?: { ... }` — CSS color strings. Keys: `bg`, `bgSubtle`, `surface`, `surfaceMuted`, `border`, `borderSubtle`, `text`, `textMuted`, `primary`, `primaryHover`, `primaryText`, `accent`, `accentHover`, `accentText`, `focusRing`, `success`, `warning`, `danger`, `info`.
|
|
446
|
+
- `radius?: { ... }` — CSS length strings. Keys: `xs`, `sm`, `md`, `lg`, `pill`, `button`, `input`.
|
|
447
|
+
- `font?: { ... }` — CSS strings. Keys: `family`, `familyHeading`, `familyMono`, `sizeBase`, `sizeSm`, `sizeLg`, `sizeHeading`, `sizeTitle`, `weightBody`, `weightHeading`.
|
|
326
448
|
|
|
327
449
|
```
|
|
328
450
|
$theme({
|
|
329
|
-
colors: { primary: "#635bff", bg: "#0a0a23", surface: "#10103a", text: "#fff" },
|
|
330
|
-
radius: { md: "0.5rem", button: "999px" },
|
|
331
|
-
font: { family: "Inter, sans-serif", familyHeading: "Inter, sans-serif" }
|
|
451
|
+
colors: { primary: "#635bff", primaryHover: "#4f46e5", accent: "#1f6feb", bg: "#0a0a23", surface: "#10103a", text: "#fff", textMuted: "#a5b4fc", focusRing: "#635bff" },
|
|
452
|
+
radius: { md: "0.5rem", button: "999px", input: "8px" },
|
|
453
|
+
font: { family: "Inter, sans-serif", familyHeading: "Inter, sans-serif", weightHeading: "600" }
|
|
332
454
|
})
|
|
333
455
|
```
|
|
334
456
|
|
|
@@ -342,7 +464,17 @@ const { t, setCurrentLanguage } = $i18n({
|
|
|
342
464
|
})
|
|
343
465
|
welcome = Text(t("greeting", { name: $user.name }))
|
|
344
466
|
```
|
|
345
|
-
`t(key, vars?)` resolves `translations[key][currentLanguage]`, falling back to the default language then the bare key; `{name}` placeholders interpolate. Drive `currentLanguage` from a reactive atom for live switching.
|
|
467
|
+
`t(key, vars?)` resolves `translations[key][currentLanguage]`, falling back to the default language then the bare key; `{name}` placeholders interpolate. Drive `currentLanguage` from a reactive atom for live switching. ICU plural and select forms are supported: `{ n, plural, =0{No items} one{1 item} other{# items} }`.
|
|
468
|
+
|
|
469
|
+
### RTL / bidirectional text
|
|
470
|
+
Set `dir="rtl"` / `"ltr"` / `"auto"` on the host `<aktion-app>` element (not in code). The runtime reflects it onto the render root so the whole tree — text direction, flex order, logical spacing — flips automatically. Programs do not need any code change; use logical CSS properties (no hard-coded `left`/`right`) in raw CSS.
|
|
471
|
+
|
|
472
|
+
### Accessibility primitives
|
|
473
|
+
- `VisuallyHidden(child)` — hides content visually, keeps it in the a11y tree.
|
|
474
|
+
- `SkipLink({ to: "#main", label: "Skip to content" })` — first tab stop for keyboard users.
|
|
475
|
+
- `LiveRegion(Text($status), { mode: "polite" })` — announces dynamic changes (`"polite"` queues; `"assertive"` interrupts).
|
|
476
|
+
- `FocusTrap(child, { active: $isOpen })` — Tab cycles within the subtree; required for dialogs.
|
|
477
|
+
- Pass `aria: { label, labelledBy, describedBy, ... }` to any component via the universal props channel.
|
|
346
478
|
|
|
347
479
|
### Icons
|
|
348
480
|
Icon props take a Font Awesome name (no `fa-` prefix, never an emoji): `"house"`, `"chart-line"`, `"regular:star"`, `"brands:github"`. `Icon(name, { variant?, size? })` renders a standalone glyph.
|
|
@@ -356,12 +488,47 @@ Pure helpers (no side effects), available in every expression, action, effect, a
|
|
|
356
488
|
- **Strings**: `$util.capitalize / .titlecase / .uppercase / .lowercase`, `.plural(n, singular, plural)`, `.trim / .replace / .split / .match`.
|
|
357
489
|
- **Formatting**: `$util.format(value, mode, opts?)` (number, currency, percent, compact) and `$util.formatDate(value, mode)` (`"short" | "long" | "time" | "relative"` or a token string).
|
|
358
490
|
- **Dates / math**: `.now / .today / .addDays / .diffDays / .startOfWeek`; `.round / .floor / .ceil / .abs / .clamp(v, min, max) / .random`.
|
|
491
|
+
- **Formatting / misc**: `.slugify / .truncate(text, len) / .initials / .currency(v, code?) / .percent(v) / .bytes(v) / .relativeTime(date) / .copy(text)` (async — resolves `true` once the clipboard write succeeds) `/ .sleep(ms) / .uuid() / .debounceFn(fn, ms) / .throttleFn(fn, ms)` (leading + trailing edge).
|
|
492
|
+
- **Device / platform**: `.vibrate(pattern) / .share({ title, text, url }) / .readClipboard() / .geolocate() / .isOnline() / .deviceType()` (XII.3); `.worker(pureFn, ...args)` runs a closure-free function off the main thread, resolving its result (XI.5); `.registerServiceWorker(url) / .webManifest({ name, icons, … })` for PWA setup (XII.2).
|
|
493
|
+
- **Reactive env getters**: `$util.scroll`, `$util.viewport`, `$util.breakpoint`, `$util.media`, `$util.mouse`, `$util.url` (listeners attach lazily on first read, re-render on change).
|
|
359
494
|
|
|
360
495
|
```
|
|
361
496
|
sorted = $util.sort($users.filter(u => u.team === $team), "joinedAt", "desc")
|
|
362
497
|
summary = `${rows.length} ${$util.plural(rows.length, "order", "orders")} · ${$util.format($util.sum(rows.amount), "currency")}`
|
|
363
498
|
```
|
|
364
499
|
|
|
500
|
+
## `$util.style`, `$util.rules` and `$util.derived` — styling, validation & computed helpers
|
|
501
|
+
|
|
502
|
+
- **`$util.style`** — bounded, sanitised CSS helpers (return safe strings for the `sx.style` / inline use): `$util.style.cx("a", { active: cond })` (classnames), `$util.style.gradient(["#6366f1", "#ec4899"], 120)`, `$util.style.alpha("primary", 0.12)` (color-mix), `$util.style.clamp("16px", "2vw", "24px")`, `$util.style.token("spacing.l")` → `var(--rui-spacing-l)`, `$util.style.toStyle({ padding: "8px" })`.
|
|
503
|
+
- **`$util.rules`** — composable validators that return `(value) => message | null`: `$util.rules.required() / .email() / .url() / .min(n) / .max(n) / .minLength(n) / .maxLength(n) / .pattern(re) / .oneOf([...]) / .matches(other) / .custom(fn) / .asyncCustom(fn)` (`fn` may return a Promise — server-side checks like username uniqueness; `$form` awaits it before submitting). Run them with `$util.rules.validate(value, [..])` (first error or null; a Promise when an async rule is hit) or `$util.rules.validateAll(values, schema)` (→ `{ field: message }`).
|
|
504
|
+
- **`$util.derived(fn)`** — a computed value: `total = $util.derived(() => $util.sum($cart.map(i => i.price)))` recomputes reactively from the atoms `fn` reads.
|
|
505
|
+
|
|
506
|
+
```
|
|
507
|
+
$email = ""
|
|
508
|
+
error = $util.rules.validate($email, [$util.rules.required(), $util.rules.email()])
|
|
509
|
+
Input("email", { value: $email, error: error })
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
### `$form({...})` — the form engine (managed forms)
|
|
513
|
+
For anything beyond one or two fields, reach for `$form` instead of wiring atoms by hand. `$form({ values: {...initial}, rules: { field: [validators] }, onSubmit: (values) => {...} })` returns a managed bag:
|
|
514
|
+
- `form.values.x` — two-way binds straight onto an input (`Input("email", { value: form.values.email })`).
|
|
515
|
+
- `form.errors.x` / `form.touched.x` / `form.dirty` / `form.valid` / `form.submitting` / `form.validating` — reactive reads (`dirty` flips on the first edit and clears on `reset()`; `validating` is true while async rules are in flight).
|
|
516
|
+
- `form.field("email")` — returns `{ value, error, name, onChange, onBlur }` to spread for a controlled, validated field.
|
|
517
|
+
- `form.validate()` (all) / `form.validateField(name)` / `form.touch(name)` / `form.setField(name, v)` / `form.setValues({...})` / `form.reset()`.
|
|
518
|
+
- `form.submit()` (alias `form.handleSubmit()`) — marks fields touched, validates (awaiting async rules), then calls `onSubmit(values)` only when valid. `form.submitting` stays true until an async `onSubmit` settles.
|
|
519
|
+
|
|
520
|
+
```
|
|
521
|
+
form = $form({
|
|
522
|
+
values: { email: "", age: "" },
|
|
523
|
+
rules: { email: [$util.rules.required(), $util.rules.email()], age: [$util.rules.min(18)] },
|
|
524
|
+
onSubmit: (v) => { $saved = $mutation({ url: "/signup", body: v }); $saved.mutate() }
|
|
525
|
+
})
|
|
526
|
+
$app(Column([
|
|
527
|
+
Input("email", { value: form.values.email, error: form.errors.email, onBlur: () => form.touch("email") }),
|
|
528
|
+
Button("Submit", { onClick: () => form.handleSubmit(), disabled: form.submitting })
|
|
529
|
+
]))
|
|
530
|
+
```
|
|
531
|
+
|
|
365
532
|
## Standard helper components
|
|
366
533
|
|
|
367
534
|
| Component | Purpose |
|
|
@@ -372,26 +539,34 @@ summary = `${rows.length} ${$util.plural(rows.length, "order", "orders")} · ${$
|
|
|
372
539
|
| `Redirect(path)` | Navigate and unmount the rest of the subtree. |
|
|
373
540
|
| `Lazy(loader, { fallback?, children })` | Defer rendering until the async `loader` resolves; show `fallback` while pending. |
|
|
374
541
|
| `ErrorBoundary(children, { fallback?, onError? })` | Catch render errors thrown by descendants. |
|
|
375
|
-
| `VirtualList(items, { key, render })` | Virtualised list — preferred for >100 rows. |
|
|
542
|
+
| `VirtualList(items, { key, render })` | Virtualised 1-D list — preferred for >100 rows. |
|
|
543
|
+
| `VirtualGrid(items, { columns, rowHeight, render })` | Virtualised 2-D grid — only visible rows mount; essential for tables/grids >100 rows. |
|
|
544
|
+
| `VisuallyHidden(child)` | Hides content visually but keeps it in the accessibility tree (extra context for screen readers). |
|
|
545
|
+
| `SkipLink({ to, label })` | "Skip to main content" link that appears on focus — the first tab stop for keyboard users. |
|
|
546
|
+
| `LiveRegion(child, { mode? })` | `aria-live` region (`mode: "polite"` default or `"assertive"`). Announces dynamic changes to screen readers. |
|
|
547
|
+
| `FocusTrap(child, { active })` | Cycles Tab within its subtree and autofocuses the first control — required for accessible dialogs. |
|
|
548
|
+
| `Fragment(children)` | Groups siblings without a layout box (`display:contents`) so a component can return several nodes into a parent Grid/Stack. |
|
|
549
|
+
| `Transition(child, { show, preset, duration? })` | Enter/exit transition — keeps child mounted through exit animation; reduced-motion safe. |
|
|
550
|
+
| `FlipList(children, { duration? })` | FLIP reorder animation — keyed children physically move to their new positions. |
|
|
376
551
|
|
|
377
552
|
## Component library
|
|
378
|
-
Use only these components. Each signature lists props in declaration order; optional props end with `?`. The prop tagged `(positional)` is the canonical positional slot
|
|
553
|
+
Use only these components. Each signature lists props in declaration order; optional props end with `?`. The prop tagged `(positional)` is the canonical positional slot. Canonical call: pass it bare and put every other prop in a trailing `{ prop: value }` object. Also valid: all-positional in the listed order (the first positional fills the `(positional)` slot, the rest fill the remaining slots top-to-bottom), or a single `{ prop: value }` object naming every prop.
|
|
379
554
|
|
|
380
555
|
### Layout
|
|
381
|
-
- Column(children: Node[], gap?: "xs"|"
|
|
382
|
-
- Row(children: Node[], gap?: "xs"|"
|
|
383
|
-
- Center(children: Node[], axis?: "both"|"horizontal"|"vertical", minHeight?: string, gap?: "xs"|"
|
|
384
|
-
- Stack(children: Node[], direction?: "column"|"row", gap?: "xs"|"
|
|
556
|
+
- Column(children: Node[], gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", wrap?: boolean, reverse?: boolean, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", 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.
|
|
557
|
+
- Row(children: Node[], gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", grow?: boolean, wrap?: boolean, reverse?: boolean, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", 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.
|
|
558
|
+
- Center(children: Node[], axis?: "both"|"horizontal"|"vertical", minHeight?: string, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", 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.
|
|
559
|
+
- Stack(children: Node[], direction?: "column"|"row", gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", 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?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl") — 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).
|
|
385
560
|
- 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).
|
|
386
|
-
- Grid(children: Node[], columns?: number | object, gap?: "xs"|"
|
|
561
|
+
- Grid(children: Node[], columns?: number | object, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", rowGap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", columnGap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", minChildWidth?: string, alignItems?: "start"|"center"|"end"|"stretch", justifyItems?: "start"|"center"|"end"|"stretch", dense?: boolean) — Two-dimensional grid with three modes:
|
|
387
562
|
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.
|
|
388
563
|
2. FIXED (`columns: N`, 1–12): exactly N equal columns.
|
|
389
564
|
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.
|
|
390
565
|
`columns` and `gap` accept responsive maps like `{base: 1, md: 2, lg: 4}`.
|
|
391
566
|
- 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.
|
|
392
|
-
- Box(children: Node[], padding?: "xs"|"
|
|
393
|
-
- Container(children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", maxWidth?: string, padding?: "none"|"
|
|
394
|
-
- Spacer(size?: "xs"|"
|
|
567
|
+
- Box(children: Node[], padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", margin?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", 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.
|
|
568
|
+
- Container(children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", maxWidth?: string, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl") — 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.
|
|
569
|
+
- Spacer(size?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", flex?: boolean) — Explicit space element for fine layout control. By default acts as a flex spacer that pushes following content to the far edge (use inside `Stack(direction="row")`). Pass `size` to render a fixed vertical/horizontal gap instead.
|
|
395
570
|
- Card(children: Node[], variant?: "default"|"outlined"|"elevated") — Vertical card container.
|
|
396
571
|
- CardHeader(title: string, subtitle?: string) — Card header with title and optional subtitle.
|
|
397
572
|
- CardFooter(children: Node[]) — Card footer for actions.
|
|
@@ -405,18 +580,18 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
405
580
|
- 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.
|
|
406
581
|
- 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.
|
|
407
582
|
- 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.
|
|
408
|
-
- Sticky(children: Node[], side?: "top"|"bottom", offset?: string, zIndex?: number) — Wraps content in a `position: sticky` container so it pins to the top (or bottom) of the nearest scrollable ancestor. Use for toolbar action rows above tables, in-page navs, status banners.
|
|
583
|
+
- Sticky(children: Node[], side?: "top"|"bottom", offset?: string, zIndex?: number) — Wraps content in a `position: sticky` container so it pins to the top (or bottom) of the nearest scrollable ancestor. Use for toolbar action rows above tables, in-page navs, status banners. Sets `data-stuck="true"` on itself once pinned, so a CSS hook (a shadow/border) can flag the pinned state.
|
|
409
584
|
- 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.
|
|
410
|
-
- MasonryGrid(items: Node[], columns?: number, gap?: "xs"|"
|
|
585
|
+
- MasonryGrid(items: Node[], columns?: number, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl") — 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.
|
|
411
586
|
|
|
412
587
|
### Content
|
|
413
|
-
- 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.
|
|
414
|
-
- 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
|
|
588
|
+
- Text(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", align?: "left"|"center"|"right", style?: string) — Renders plain text with a typographic variant. `align` (left|center|right) sets the horizontal alignment (the text renders as its own block). Optional `style` prop accepts a CSS declaration string (e.g. "font-size: 16px; color: #000;") applied directly to the rendered element.
|
|
589
|
+
- Image(src: string, alt?: string, caption?: string, ratio?: string, fit?: "cover"|"contain"|"fill"|"none"|"scale-down", fallback?: string, placeholder?: "blur"|"none", loading?: "lazy"|"eager", sizes?: string, srcset?: 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` (and it reserves space to avoid layout shift). `fit` controls how the image fills that box. `placeholder: "blur"` fades the image in once loaded; `sizes`/`srcset` enable responsive loading; `loading: "eager"` opts out of lazy-loading. When `src` is missing/unsafe or fails to load it shows the `fallback` text/icon.
|
|
415
590
|
- 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`.
|
|
416
591
|
- 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.
|
|
417
592
|
- 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.
|
|
418
593
|
- Quote(text: string, cite?: string, tone?: "default"|"primary"|"success"|"warning"|"danger"|"info") — Inline pull-quote with optional citation. Lighter than `Testimonial` — use inside articles, blog posts, marketing sections, or anywhere you need to highlight a sentence without the full quote/author/role + rating shape.
|
|
419
|
-
- CodeBlock(language?: string, codeString: string (positional), showLineNumbers?: boolean, highlightLines?: string, copy?: boolean) — Read-only code block with a language label and a copy-to-clipboard button. Pass `showLineNumbers=true` to render a gutter; `highlightLines` accepts a string like `"3-5,8"` to emphasise specific lines.
|
|
594
|
+
- CodeBlock(language?: string, codeString: string (positional), showLineNumbers?: boolean, highlightLines?: string, highlight?: boolean, copy?: boolean, header?: boolean, width?: string, height?: string) — Read-only code block with a language label and a copy-to-clipboard button. Pass `showLineNumbers=true` to render a gutter; `highlightLines` accepts a string like `"3-5,8"` to emphasise specific lines. `header=false` renders a chromeless variant — no language label or copy button, no border or rounding — that fills its container (100%×100%), for embedding in your own frame (CodeWindow uses it). `width`/`height` set an explicit size; overflowing code scrolls either way.
|
|
420
595
|
- Skeleton(variant?: "paragraph"|"card"|"table-row"|"avatar"|"image", lines?: number, height?: number | string, shape?: "rect"|"circle", width?: string) — Loading placeholder. Pass a `variant` for common shapes — `paragraph` (default), `card`, `table-row`, `avatar`, `image` — or use `shape` / `width` / `height` to build a custom one. All variants use a shimmer animation that respects `prefers-reduced-motion`.
|
|
421
596
|
- 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`).
|
|
422
597
|
- 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.
|
|
@@ -429,13 +604,13 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
429
604
|
- 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).
|
|
430
605
|
- 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`.
|
|
431
606
|
- 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=...)`.
|
|
432
|
-
- 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.
|
|
433
|
-
- 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.
|
|
607
|
+
- Input(id: string, placeholder?: string, type?: "text"|"email"|"password"|"number"|"tel"|"url"|"date", validations?: any, value?: any, onChange?: callable, label?: string, hint?: string, error?: string, required?: boolean, onBlur?: callable, onFocus?: callable) — Text input field. Pass a $variable as `value` for two-way binding. `onChange(value)` fires on every keystroke with the current string. Pass `label`/`hint`/`error`/`required` to render a labelled field shell with validation messaging.
|
|
608
|
+
- TextArea(id: string, placeholder?: string, rows?: number, value?: any, onChange?: callable, label?: string, hint?: string, error?: string, required?: boolean, onBlur?: callable, onFocus?: callable) — Multi-line text input. `onChange(value)` fires on every keystroke with the current text. Pass `label`/`hint`/`error`/`required` for a labelled field shell.
|
|
434
609
|
- 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.
|
|
435
610
|
- 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`.
|
|
436
611
|
- 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.
|
|
437
612
|
- 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.
|
|
438
|
-
- 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.
|
|
613
|
+
- Select(id: string, items: SelectItem[], label?: string, placeholder?: string, value?: any, searchable?: boolean, onChange?: callable, hint?: string, error?: string, required?: 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. `onChange(value)` fires with the newly-selected value.
|
|
439
614
|
- SelectItem(value: string, label: string) — Single option for a Select component.
|
|
440
615
|
- 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.
|
|
441
616
|
- 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.
|
|
@@ -445,11 +620,11 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
445
620
|
- Radio(id: string, items: SelectItem[], value?: any, onChange?: callable) — Radio button group. `onChange(value)` fires with the newly-selected option value.
|
|
446
621
|
- 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.
|
|
447
622
|
- 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.
|
|
448
|
-
- Button(label: string, onClick?: callable, variant?: "primary"|"secondary"|"ghost"|"danger", type?: "button"|"submit", size?: "xs"|"sm"|"md"|"lg"|"xl", 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.
|
|
623
|
+
- Button(label: string, onClick?: callable, variant?: "primary"|"secondary"|"outline"|"ghost"|"link"|"danger"|"default", type?: "button"|"submit", size?: "xs"|"sm"|"md"|"lg"|"xl", 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.
|
|
449
624
|
- Buttons(items: Button[], direction?: "row"|"column") — Group of buttons laid out horizontally or vertically.
|
|
450
625
|
- 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.
|
|
451
626
|
- 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.
|
|
452
|
-
- 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.
|
|
627
|
+
- NumberInput(id: string, value?: number, min?: number, max?: number, step?: number, placeholder?: string, disabled?: boolean, onChange?: callable, label?: string, hint?: string, error?: string, required?: boolean, onBlur?: callable, onFocus?: 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.
|
|
453
628
|
- 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.
|
|
454
629
|
- 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.
|
|
455
630
|
- 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).
|
|
@@ -462,7 +637,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
462
637
|
### Data
|
|
463
638
|
- 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.
|
|
464
639
|
- 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).
|
|
465
|
-
- 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.
|
|
640
|
+
- 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, exportable?: boolean, exportFilename?: string) — 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.
|
|
466
641
|
- List(items: ListItem[], ordered?: boolean) — Vertical list of ListItems.
|
|
467
642
|
- ListItem(title: string, description?: string, icon?: string) — Single list item with optional title and description.
|
|
468
643
|
- 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.
|
|
@@ -490,7 +665,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
490
665
|
- Series(name: string, values: number[]) — Named data series for charts. Used inside BarChart, LineChart, PieChart.
|
|
491
666
|
|
|
492
667
|
### Feedback & Media
|
|
493
|
-
- Avatar(name: string, src?: string, size?: "xs"|"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.
|
|
668
|
+
- Avatar(name: string, src?: string, size?: "xs"|"sm"|"md"|"lg"|"xl", status?: "online"|"offline"|"busy"|"away", fallback?: "initials"|"dicebear"|"gradient") — 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.
|
|
494
669
|
- AvatarGroup(items: Avatar[], max?: number, size?: "xs"|"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.
|
|
495
670
|
- 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.
|
|
496
671
|
- 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.
|
|
@@ -498,6 +673,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
498
673
|
- 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.
|
|
499
674
|
- 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` (or an `onChange` handler) to let users pick a rating; bind `value: $rating` for two-way binding, or read the new value from `onChange: (v) => …`. 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.
|
|
500
675
|
- 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.
|
|
676
|
+
- Toasts(children: Node[], position?: "top-right"|"top-left"|"top-center"|"bottom-right"|"bottom-left"|"bottom-center") — Stacked container for transient `Toast` notifications, pinned to a viewport corner. Render the reactive `$toast.items` list into it: `Toasts($toast.items.map(t => Toast({ title: t.message, tone: t.tone, onClose: () => $toast.dismiss(t.id) })))`. Use a standalone `Toast` with `position` for a single one-off notice.
|
|
501
677
|
- 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.
|
|
502
678
|
- 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.
|
|
503
679
|
- Carousel(items: Node[], activeIndex?: number, ratio?: string, showDots?: boolean, showArrows?: boolean) — Horizontal slider with prev/next buttons and dot navigation. Each child slide takes full width. Slides may be Component nodes (Image, Card, MediaCard, …), URL strings, or plain `{src, alt, caption?}` image objects — bare image objects are auto-wrapped into a captioned figure. Use for image galleries, onboarding carousels, hero banners, and product image strips. The active slide is preserved across re-renders via instance state.
|
|
@@ -570,7 +746,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
570
746
|
- 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.
|
|
571
747
|
|
|
572
748
|
### Advanced UI
|
|
573
|
-
- IconButton(icon: string, label: string, onClick?: callable, variant?: "primary"|"secondary"|"ghost"|"danger", size?: "xs"|"sm"|"md"|"lg"|"xl"
|
|
749
|
+
- IconButton(icon: string, label: string, onClick?: callable, variant?: "primary"|"secondary"|"ghost"|"danger", size?: "xs"|"sm"|"md"|"lg"|"xl", disabled?: boolean) — Icon-only button with an accessible label. Use for toolbars, table row actions, and compact controls.
|
|
574
750
|
- CommandPalette(items: any[], open?: boolean, placeholder?: string, shortcut?: string) — Cmd-K style searchable command list. Pass `items` as `{label, value, group?, shortcut?, action?}` objects.
|
|
575
751
|
- FilterChips(chips: any[], onRemove?: callable, onClear?: callable) — Removable filter chips with an optional clear-all control.
|
|
576
752
|
- 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.
|
|
@@ -584,7 +760,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
584
760
|
- NotificationBell(count?: number, items?: any[], onOpen?: callable) — Bell icon with unread count badge and dropdown notification list.
|
|
585
761
|
|
|
586
762
|
### Routing
|
|
587
|
-
- 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"` (and `aria-current="page"` for assistive tech) when the current path matches `to` (set `exact=true` to require exact equality instead of prefix matching).
|
|
763
|
+
- NavLink(label: string, to: string, variant?: "default"|"primary"|"ghost"|"pill", exact?: boolean, icon?: string, prefetch?: callable) — Anchor that navigates to a route on click and stays in sync with the URL hash. Reflects `data-active="true"` (and `aria-current="page"` for assistive tech) when the current path matches `to` (set `exact=true` to require exact equality instead of prefix matching).
|
|
588
764
|
|
|
589
765
|
### Helpers
|
|
590
766
|
- 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.
|
|
@@ -592,7 +768,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
592
768
|
- Portal(target?: string, children: Node[] (positional)) — Render children outside the parent subtree (e.g. into document.body).
|
|
593
769
|
- Redirect(path: string (positional)) — Navigate to `path` and unmount the rest of the subtree.
|
|
594
770
|
- Lazy(loader: any (positional), fallback?: Node, children?: Node[]) — Defer rendering until an async `loader` resolves: show `fallback` while pending, then render the resolved value (or `children`). A synchronous loader value renders immediately.
|
|
595
|
-
- ErrorBoundary(fallback?: Node, onError?: callable, children: Node[] (positional)) — Render a fallback subtree when rendering children throws.
|
|
771
|
+
- ErrorBoundary(fallback?: Node, onError?: callable, showDetails?: boolean, children: Node[] (positional)) — Render a fallback subtree when rendering children throws. Pass a `fallback` node (or omit it for a built-in friendly error card showing the message + a Retry button); `onError(err)` fires with the error. Set `showDetails=true` to reveal the message inline (great in dev).
|
|
596
772
|
|
|
597
773
|
### Behaviour wrappers
|
|
598
774
|
- 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).
|
|
@@ -606,10 +782,85 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
606
782
|
|
|
607
783
|
### Escape hatches
|
|
608
784
|
- 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.
|
|
609
|
-
- 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.
|
|
785
|
+
- Styles(css: string (positional), scope?: string, tokens?: boolean) — 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.
|
|
610
786
|
|
|
611
787
|
### Other
|
|
612
|
-
-
|
|
788
|
+
- Fragment(children: Node[]) — Groups several siblings into one value WITHOUT adding a layout box — the wrapper is `display: contents`, so the children participate in the parent's flex/grid layout directly. Use to return multiple nodes from a component, or to conditionally group siblings, without a stray `div` that would break a Grid/Stack's spacing.
|
|
789
|
+
- TextContent(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", align?: "left"|"center"|"right", style?: string) — Deprecated alias for `Text`. Prefer `Text(...)` — both render identically.
|
|
790
|
+
- VirtualGrid(items: any[], columns?: number, itemHeight?: number, gap?: number, height?: number) — Windowed 2-D grid for very large collections (galleries, tiles, thumbnails). Only the visible rows of cells are mounted. Pass pre-rendered nodes (or plain values) as `items`; set `columns`, `itemHeight`, and `gap`. Virtualizes by row so thousands of items scroll smoothly (XI.3).
|
|
791
|
+
- GradientText(text: string (positional), gradient?: "brand"|"accent"|"warm"|"cool"|"success"|"danger") — Inline text painted with a brand gradient. Use inside a Display/Heading title to emphasise a phrase: `Display(["Build in ", GradientText("record time")])`. `gradient` selects a named theme gradient (brand|accent|warm|cool|success|danger).
|
|
792
|
+
- Display(content: string | Node[] (positional), size?: "hero"|"xl"|"lg", align?: "left"|"center"|"right", balance?: boolean, weight?: number) — Oversized display headline with built-in responsive `clamp()` sizing. The positional argument may be a plain string OR an array mixing strings and `GradientText(...)` runs. `size`: hero|xl|lg. `balance` wraps for even line lengths.
|
|
793
|
+
- Heading(content: string | Node[] (positional), level?: number, size?: "section"|"lg"|"md"|"sm", align?: "left"|"center"|"right") — Section/subsection heading with token-driven sizing. `level` sets the semantic tag (1–6); `size`: section|lg|md|sm. Accepts string or mixed string/GradientText array like Display.
|
|
794
|
+
- Eyebrow(text: string (positional)) — Small uppercase, letter-spaced, primary-toned label above a heading.
|
|
795
|
+
- Section(children: Node[] (positional), background?: "base"|"soft"|"surface"|"muted"|"brand", width?: "sm"|"md"|"lg"|"xl"|"full", padding?: "none"|"xs"|"sm"|"md"|"lg"|"xl", align?: "left"|"center", eyebrow?: string, title?: string | Node[], subtitle?: string, id?: string) — Full-bleed page band → centered max-width container → optional tinted background → optional eyebrow/title/subtitle header. The single most useful primitive for marketing, docs, and settings pages. Children render below the header.
|
|
796
|
+
- Overlay(base: Node (positional), items: OverlayItem[]) — Layers OverlayItem children on top of a base node — corner badges, play buttons over thumbnails, sale ribbons, floating actions. Pass the base as the positional argument and `items` as OverlayItem entries.
|
|
797
|
+
- OverlayItem(child: Node (positional), anchor?: "top-left"|"top-right"|"bottom-left"|"bottom-right"|"top"|"bottom"|"left"|"right"|"center", offset?: string) — A child positioned over an Overlay's base. `anchor` picks a corner/edge/center.
|
|
798
|
+
- Brand(name: string (positional), logo?: string, version?: string, href?: string) — Logo + product name (+ optional version pill), linking home. Use in NavBar/Footer.
|
|
799
|
+
- NavBar(brand?: Node, links?: Node[], actions?: Node[], sticky?: boolean, blur?: boolean) — Marketing top navigation: brand on the left, links in the middle, actions (buttons/toggles) on the right. `sticky` pins it; `blur` adds a frosted-glass backdrop. On narrow viewports the links collapse behind a burger toggle. Distinct from the app-shell Navbar/TopBar.
|
|
800
|
+
- Footer(brand?: Node, tagline?: string, columns?: FooterColumn[], legal?: string) — Site footer: brand + tagline in a wide first column, then link columns, and a legal/copyright line. Pass `columns` as FooterColumn nodes.
|
|
801
|
+
- FooterColumn(title: string (positional), links: Node[]) — A titled column of links inside a Footer.
|
|
802
|
+
- LogoCloud(items: LogoChip[] (positional), label?: string) — A centered, wrapping row of LogoChip items with an optional label — 'works with' / 'trusted by' bands.
|
|
803
|
+
- LogoChip(label: string (positional), icon?: string) — A single labelled chip (icon + name) for a LogoCloud.
|
|
804
|
+
- CountUp(value: number (positional), suffix?: string, prefix?: string, duration?: number) — A number that animates from 0 to `value` when scrolled into view. `prefix`/`suffix` wrap it (e.g. `$`, `+`, `%`). Respects reduced motion.
|
|
805
|
+
- Metric(value: string | number (positional), label?: string, gradient?: boolean, countUp?: boolean) — A single big-number metric tile with a gradient accent bar and label. Use inside MetricStrip. Set `countUp` to animate.
|
|
806
|
+
- MetricStrip(items: Metric[] (positional), columns?: number) — A responsive row/grid of Metric tiles. `columns` sets the preferred count.
|
|
807
|
+
- CodeWindow(code: string (positional), file?: string, language?: string, status?: Node, preview?: boolean | Node) — An editor/IDE window chrome (traffic-light dots + filename + status area) around source code. Pass the code as a plain STRING — it renders through a chromeless CodeBlock that fills the pane (no inner border, language label, or copy button), syntax-highlighted via `language` (default: inferred from the `file` extension, else aktion). Set `preview: true` to run the source as a LIVE app beside the code (split view with a pulsing 'Live render' badge); a custom node is also accepted for non-Aktion previews. The canonical way to show code in docs/marketing.
|
|
808
|
+
- BrowserFrame(child: Node (positional), url?: string) — A browser-window chrome (dots + URL bar) wrapping a child — for screenshots/demos of web UIs.
|
|
809
|
+
- Terminal(lines: string[] (positional), file?: string) — A terminal window rendering monospace lines. Pass `lines` as an array of strings.
|
|
810
|
+
- Backdrop(grid?: boolean, blobs?: string[], particles?: number, type?: "network"|"drift"|"snow"|"stars"|"bubbles", particleColors?: string[], speed?: number, linkDistance?: number, particleSize?: number, fixed?: boolean) — Decorative background layer for hero/marketing sections: a masked grid, floating blurred color 'blobs', and an animated canvas particle field. `type` picks the particle behaviour — `network` (drifting dots joined by constellation lines, the default), `drift`, `snow`, `stars`, or `bubbles` — tuned via `particleColors`, `speed`, `linkDistance`, and `particleSize`. All theme-aware and motion-safe. Place as the first child of a Section (which is `position: relative`).
|
|
811
|
+
- ThemeToggle(light?: string, dark?: string) — A sun/moon button that toggles the host between light and dark themes — no host glue required. It flips the <aktion-app> `theme` attribute and dispatches a `theme-change` event the host can listen for.
|
|
812
|
+
- Swatch(name: string (positional), background?: string, foreground?: string, colors?: string[]) — A theme/palette preview tile — color dots over a named background. For theming galleries.
|
|
813
|
+
- CopyButton(text: string (positional), label?: string, copiedLabel?: string) — A button that copies `text` to the clipboard and confirms it — the label flips to `copiedLabel` (default 'Copied!') with a check icon for a couple of seconds, then reverts. Bounded, no host glue.
|
|
814
|
+
- SegmentedControl(options: any[] (positional), value?: string, onChange?: callable) — A compact segmented toggle (iOS-style). `options` is an array of strings or {label, value}. Bind `value` to a $variable; `onChange(value)` fires on select.
|
|
815
|
+
- FloatingActionButton(icon: string (positional), label?: string, onClick?: callable) — A fixed circular action button (FAB) anchored bottom-right. `icon` + `onClick`.
|
|
816
|
+
- Prose(children: Node[] (positional), size?: "sm"|"md"|"lg") — A styled long-form reading container — applies typographic defaults to headings, lists, blockquotes, code, links inside. Wrap Markdown(...) or raw nodes for blog posts, docs bodies, product descriptions.
|
|
817
|
+
- RelativeTime(value: string | number (positional)) — Renders a human relative time ('3m ago', 'in 2 days') from an ISO date/timestamp, localized via Intl.
|
|
818
|
+
- PriceTag(price: string | number (positional), compareAt?: string | number, currency?: string, size?: "sm"|"md"|"lg") — A formatted price with an optional struck-through compare-at price and a discount badge.
|
|
819
|
+
- QuantityStepper(value: number (positional), min?: number, max?: number, step?: number, onChange?: callable) — A −/value/+ numeric stepper. Bind `value` to a $variable; `onChange(value)` fires on change. Respects min/max.
|
|
820
|
+
- ProductCard(title: string (positional), image?: string, price?: string | number, compareAt?: string | number, currency?: string, rating?: number, badge?: string, action?: Node, onAdd?: callable) — An e-commerce product card: image, title, optional rating, a PriceTag, and an add-to-cart action. Pass `price`/`compareAt` directly or a custom `price` node.
|
|
821
|
+
- TableOfContents(items: object[] (positional), title?: string) — A navigable table of contents. `items` is an array of {label, href, level?}.
|
|
822
|
+
- TypingIndicator(name?: string (positional)) — Three animated bouncing dots — a chat 'is typing…' affordance. Optional `name` prefix.
|
|
823
|
+
- CountdownTimer(to: string | number (positional), endLabel?: string) — Live countdown to a target date/time (ISO string or timestamp). Ticks every second, then shows `endLabel`.
|
|
824
|
+
- BackToTop(label?: string) — A floating button that smoothly scrolls the page (and the host) back to the top.
|
|
825
|
+
- Split(left: Node (positional), right: Node, ratio?: string, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", divider?: boolean, sticky?: "left"|"right", stackAt?: "sm"|"md"|"lg", align?: "start"|"center"|"stretch") — Two-pane layout: a left/primary node and a right/secondary node, with a controllable `ratio` (1/1, 3/2, 2/3…), optional `divider`, an optional `sticky` pane that pins on scroll, and a `stackAt` breakpoint where it collapses to a single column. The canonical 'text + media' / 'code + preview' / 'content + sidebar' section.
|
|
826
|
+
- Bento(items: BentoCell[] (positional), columns?: number, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", rowHeight?: string, dense?: boolean) — Asymmetric 'bento box' grid — the marquee feature-section layout. Children must be BentoCell nodes (a plain node becomes a 1×1 tile). Two rules make it look right: (1) spans must tile the grid exactly — each row's column spans sum to `columns` and row-spans pair up with neighbouring cells, never leaving a dangling track (e.g. `columns: 3` with 4 cells: hero 2×2 + tall 1×2 fill rows 1–2, wide 2×1 + tile fill row 3); (2) set a fixed `rowHeight` (e.g. "180px") whenever cells hold images or cards — the default auto row stretches to the tallest cell and makes the mosaic ragged. Give 1–2 standout cells a big span (hero/wide/tall) and keep the rest 1×1 tiles. `dense` (default true) backfills gaps. Collapses to 2 columns below 920px and 1 below 640px.
|
|
827
|
+
- BentoCell(child: Node (positional), span?: string | number | object, rowSpan?: number) — A single cell in a Bento grid. `span` names a size — `tile` 1×1, `wide` 2×1 (2 columns), `tall` 1×2 (2 rows), `hero` 2×2, `full` (a whole row) — or use a "CxR" string ("2x1"), a bare column-span number, or `{ col, row }`; `rowSpan` adds rows to a named/numeric span. The child stretches to fill the cell, so images/cards crop to the cell's shape. Pick spans that tile the parent Bento with no leftover tracks.
|
|
828
|
+
- Reveal(child: Node (positional), animation?: "fade"|"fade-up"|"fade-down"|"fade-left"|"fade-right"|"zoom"|"slide-up", delay?: number, once?: boolean) — Animates its child in the first time it scrolls into view (scroll choreography). `animation` is a preset (fade-up|fade|zoom|…), `delay` staggers it (ms), `once` (default true) plays a single time. Honours prefers-reduced-motion (renders immediately).
|
|
829
|
+
- OnGesture(child: Node (positional), swipe?: callable, longPress?: callable, doubleTap?: callable, pan?: callable, threshold?: number) — Attach high-level pointer gestures to any component without raw DOM: `swipe(dir)` (left/right/up/down), `longPress()`, `doubleTap()`, and `pan({dx, dy})`. Powers swipe-to-dismiss, pull-to-refresh, carousels, and drag affordances on touch + mouse.
|
|
830
|
+
- Sortable(items: Node[] (positional), onReorder?: callable, handle?: boolean) — A vertical list whose items can be drag-reordered. Pass already-rendered `items`; `onReorder(fromIndex, toIndex)` fires after a drop so you can reorder the backing reactive array. Works with mouse + touch.
|
|
831
|
+
- Draggable(child: Node (positional), data?: any, onDragStart?: callable, onDragEnd?: callable) — Makes its child draggable, carrying a `data` payload picked up by a DropZone. `onDragStart`/`onDragEnd` optional.
|
|
832
|
+
- DropZone(child: Node (positional), onDrop?: callable, label?: string) — A target that accepts a Draggable. `onDrop(data)` receives the dropped payload (parsed JSON when possible).
|
|
833
|
+
- Parallax(child: Node (positional), speed?: number) — Translates its child vertically as the page scrolls for a depth effect. `speed` (−1…1) sets intensity/direction. Honours prefers-reduced-motion.
|
|
834
|
+
- ReadingProgress(gradient?: boolean, height?: string) — A thin progress bar that fills as the page scrolls — article/docs reading affordance. Optional gradient fill.
|
|
835
|
+
- Transition(child: Node (positional), show: boolean, preset?: "fade"|"scale"|"slide-up"|"slide-down"|"slide-left"|"slide-right", duration?: number) — Animates its child IN when `show` becomes true and OUT when it becomes false (mount/unmount choreography) — modals, toasts, dropdowns, list rows. `preset` is fade|scale|slide-up|slide-down|slide-left|slide-right, `duration` is ms. The child stays mounted through the exit animation, then is removed. Honours prefers-reduced-motion (instant swap).
|
|
836
|
+
- FlipList(children: Node[], duration?: number) — Smoothly animates its children when they reorder, are added, or removed (the FLIP technique — First/Last/Invert/Play). Wrap a keyed list whose order changes (drag-sort, filter, sort toggle) so items glide to their new positions instead of jumping. `duration` is ms. Honours prefers-reduced-motion (no animation). Use stable `key:`s on the items so their DOM nodes persist across the reorder.
|
|
837
|
+
- RouteView(children: Node (positional), routeKey: string, animation?: "fade"|"fade-up"|"fade-down"|"fade-left"|"fade-right"|"zoom"|"slide-up", duration?: number) — Wraps a router's output so the page animates whenever the route changes. Pass `routeKey: route.path` so it knows when to replay the entrance animation; `animation` is fade|fade-up|zoom|… and `duration` is ms. Works by swapping a keyed inner wrapper, so the fresh page element plays its CSS entrance on mount. Honours prefers-reduced-motion.
|
|
838
|
+
- Svg(content: string (positional), viewBox?: string, width?: string, height?: string, fill?: string) — Render inline SVG markup safely (paths, shapes, gradients) — for brand illustrations, custom icons, and data-viz overlays without the HTMLTag escape hatch. Pass the inner markup (everything inside <svg>) plus a `viewBox`. Script/event-handler payloads are stripped.
|
|
839
|
+
- Sheet(children: Node[] (positional), open?: boolean, side?: "left"|"right"|"top"|"bottom", title?: string, onClose?: callable) — A panel that slides in from an edge over a dimmed backdrop. `side` is left|right|top|bottom. Bind `open` to a $variable; `onClose` fires on backdrop click / Escape. Use BottomSheet for the mobile bottom variant.
|
|
840
|
+
- BottomSheet(children: Node[] (positional), open?: boolean, title?: string, onClose?: callable) — A mobile bottom sheet — Sheet pinned to the bottom edge with a drag handle. Bind `open`; `onClose` on dismiss.
|
|
841
|
+
- ConfirmDialog(title: string (positional), open?: boolean, message?: string, confirmLabel?: string, cancelLabel?: string, tone?: "primary"|"danger"|"warning", onConfirm?: callable, onCancel?: callable) — A confirm/cancel modal dialog. Bind `open` to a $variable; `onConfirm` fires on accept, `onCancel`/backdrop on dismiss. `tone` colors the confirm button (danger for destructive actions).
|
|
842
|
+
- PresenceAvatars(people: object[] (positional), max?: number) — An overlapping stack of avatars with online status dots — 'who's here' for collab/social. Pass `people` as {name, src?, online?}.
|
|
843
|
+
- ShareButtons(url: string (positional), title?: string, networks?: string[]) — A row of social share buttons (twitter|facebook|linkedin|reddit|email) plus a copy-link button, for the given `url`/`title`.
|
|
844
|
+
- AuthorByline(name: string (positional), avatar?: string, role?: string, date?: string) — An author byline: avatar, name, optional role and date — for articles/blog posts.
|
|
845
|
+
- VariantSelector(options: any[] (positional), value?: string, kind?: "pill"|"swatch", label?: string, onChange?: callable) — Product variant picker — color swatches or size pills. `options` is an array of strings or {label, value, color?}. Bind `value` to a $variable; `onChange(value)` fires on select.
|
|
846
|
+
- OrderSummary(items: object[] (positional), subtotal?: string | number, shipping?: string | number, tax?: string | number, total?: string | number, currency?: string) — An order/cart summary: line items, subtotal, shipping, tax, and a bold total. Pass `items` as {label, amount} and the named totals; `currency` prefixes amounts.
|
|
847
|
+
- ScrollSpy(sections: object[] (positional), title?: string) — A sticky in-page nav that highlights the section currently in view. `sections` is an array of {label, id} matching element ids on the page (set via the universal `id` prop). Clicking smooth-scrolls to a section.
|
|
848
|
+
- SpeedDial(actions: object[] (positional), icon?: string) — A floating action button that expands a stack of mini-actions on click. Pass `actions` as {icon, label, onClick}.
|
|
849
|
+
- Confetti(fire?: boolean, count?: number) — A one-shot confetti burst — celebration affordance after a success (checkout, completion). Renders a short CSS particle animation when `fire` is true. Honours prefers-reduced-motion.
|
|
850
|
+
- KbdShortcut(keys: string | string[] (positional)) — Render a keyboard shortcut as styled key caps. Pass `keys` as an array (e.g. ["Cmd", "K"]) or a '+'-joined string.
|
|
851
|
+
- Lottie(src?: string, data?: object, loop?: boolean, autoplay?: boolean, speed?: number, width?: string, height?: string, poster?: string, fallback?: Node) — Plays a Lottie/Bodymovin vector animation from `src` (a .json URL) or inline `data`. Uses the `lottie-web` library when it is present on the page (`window.lottie`); otherwise shows the `fallback` (or a poster image) so the layout never breaks. `loop`/`autoplay` default true; `speed` scales playback. No dependency is bundled.
|
|
852
|
+
- VisuallyHidden(children: Node[]) — Renders content that is invisible on screen but available to screen readers (the `sr-only` pattern). Use for icon-button labels, form hints, and context that sighted users get from layout but assistive tech needs.
|
|
853
|
+
- SkipLink(to: string (positional), label?: string) — A keyboard-only 'skip to content' link that is hidden until focused, then jumps to the element with the given id. Place it as the first node in a page so keyboard users can bypass the nav.
|
|
854
|
+
- LiveRegion(text: string (positional), politeness?: "polite"|"assertive", visible?: boolean) — An aria-live region that announces its text to screen readers whenever it changes — toasts, validation summaries, async status. `politeness` is `polite` (default) or `assertive`. Visually hidden by default; set `visible` to also show it.
|
|
855
|
+
- FocusTrap(child: Node (positional), active?: boolean) — Confines keyboard focus to its subtree while `active` (default true) — Tab from the last focusable wraps to the first and vice-versa. Use inside modals, drawers, and command palettes. Auto-focuses the first focusable on mount.
|
|
856
|
+
- QRCode(data: string (positional), size?: number, ecc?: "L"|"M"|"Q"|"H", color?: string, background?: string, margin?: number) — Renders an offline QR code as crisp SVG from `data` (a URL or text). `size` is the pixel side length, `ecc` the error-correction level (L|M|Q|H, default M), `color`/`background` override the modules. No network — encodes fully in the browser.
|
|
857
|
+
- ReactionPicker(reactions: object[] (positional), onReact?: callable) — A row of emoji reactions with counts. `reactions` is a list of { emoji, count?, active? }; `onReact(emoji)` fires on click. Use under messages, comments, and posts.
|
|
858
|
+
- LiveCursor(x: number, y: number, label?: string, color?: string) — A floating collaborator cursor positioned at `x`/`y` (px) with a name label — drive it from presence/`$socket` state for multiplayer UIs. Pointer-events are disabled so it never blocks interaction.
|
|
859
|
+
- TabBar(items: object[] (positional), active?: string, onChange?: callable) — Bottom navigation bar for mobile layouts — a row of icon+label tabs. `items` is [{ id, label, icon?, badge? }]; `active` is the current id; `onChange(id)` fires on tap. Pins to the bottom with safe-area padding.
|
|
860
|
+
- Cart(items: object[] (positional), onQty?: callable, onRemove?: callable, currency?: string, footer?: Node) — A shopping-cart line list: each item shows image, name, unit price, a quantity stepper, and a remove button, with a running subtotal. `items` is [{ id, name, price, qty, image? }]; `onQty(id, qty)` and `onRemove(id)` fire on interaction. `currency` is an ISO code (default USD).
|
|
861
|
+
- Calendar(month?: number, year?: number, selected?: string, onSelect?: callable, events?: any[], firstDay?: number, navigable?: boolean, onNavigate?: callable) — A Google Calendar-style month grid with Today/prev/next navigation. `month` (0–11) and `year` set the view (default current month); `selected` is an ISO date (YYYY-MM-DD) to highlight — bind a $variable for two-way selection; `onSelect(iso)` fires on a day click. `events` mixes bare ISO strings (rendered as dots) and `{date, label, color?, time?}` objects (rendered as colored chips with a '+N more' overflow; `color` is a tone name or CSS color). `onNavigate(year, month)` fires when the user pages months; `navigable=false` hides the toolbar buttons. Use for schedules, bookings, and availability calendars.
|
|
862
|
+
- DrawingCanvas(width?: number, height?: number, color?: string, lineWidth?: number, background?: string, clearable?: boolean, onChange?: callable, onEnd?: callable) — A freehand drawing surface (pointer / touch / stylus). `onChange(count)` fires while drawing; `onEnd(dataUrl)` fires when a stroke finishes with a PNG data URL. `color`/`lineWidth`/`background` style the ink. Includes a Clear button unless `clearable=false`.
|
|
863
|
+
- SignaturePad(width?: number, height?: number, color?: string, onChange?: callable) — A signature capture pad — a DrawingCanvas tuned for signing, with a baseline and a Clear button. `onChange(pngDataUrl)` fires when the signature changes (empty string when cleared). Use in contracts, delivery confirmation, and consent flows.
|
|
613
864
|
|
|
614
865
|
## Examples
|
|
615
866
|
```
|
|
@@ -625,7 +876,7 @@ row = task => Card([Row([
|
|
|
625
876
|
Badge(task.done ? "done" : "open", { tone: task.done ? "success" : "neutral" }),
|
|
626
877
|
StackItem(Text(task.title, { tone: task.done ? "muted" : "default" }), { grow: 1 }),
|
|
627
878
|
Button(task.done ? "Reopen" : "Done", { onClick: () => toggle(task), size: "sm" })
|
|
628
|
-
], { gap: "
|
|
879
|
+
], { gap: "md" })])
|
|
629
880
|
|
|
630
881
|
$app(Column([
|
|
631
882
|
PageHeader("Tasks", { subtitle: `${$tasks.data.length} items`, actions: [Button("Refresh", { onClick: $tasks.refetch, variant: "ghost" })] }),
|
|
@@ -633,9 +884,9 @@ $app(Column([
|
|
|
633
884
|
loading: LoadingState("Loading tasks…"),
|
|
634
885
|
error: ErrorState("Couldn't fetch tasks"),
|
|
635
886
|
empty: EmptyState("No tasks yet"),
|
|
636
|
-
data: Column($tasks.data.map(t => row(t)), { gap: "
|
|
887
|
+
data: Column($tasks.data.map(t => row(t)), { gap: "sm" })
|
|
637
888
|
})
|
|
638
|
-
], { gap: "
|
|
889
|
+
], { gap: "lg" }))
|
|
639
890
|
```
|
|
640
891
|
|
|
641
892
|
## Streaming & verification
|