aktion-runtime 0.5.8 → 0.5.10

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.
Files changed (56) hide show
  1. package/README.md +196 -26
  2. package/dist/aktion.iife.js +879 -78
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +16396 -10312
  5. package/dist/aktion.js.map +1 -1
  6. package/dist/aktion.umd.cjs +879 -78
  7. package/dist/aktion.umd.cjs.map +1 -1
  8. package/dist/devtools.js +554 -20
  9. package/dist/devtools.js.map +1 -1
  10. package/dist/language.js +4883 -572
  11. package/dist/language.js.map +1 -1
  12. package/dist/plugin.cjs +2 -2
  13. package/dist/plugin.cjs.map +1 -1
  14. package/dist/plugin.js +2 -2
  15. package/dist/plugin.js.map +1 -1
  16. package/dist/system_prompt.txt +269 -20
  17. package/dist/system_prompt_chat.txt +3 -3
  18. package/dist/testing.js +15977 -7890
  19. package/dist/testing.js.map +1 -1
  20. package/dist/types/devtools/panel.d.ts +32 -0
  21. package/dist/types/devtools/styles.d.ts +1 -1
  22. package/dist/types/element.d.ts +26 -0
  23. package/dist/types/icons/index.d.ts +10 -0
  24. package/dist/types/library/components/_internal.d.ts +18 -0
  25. package/dist/types/library/components/a11y.d.ts +5 -0
  26. package/dist/types/library/components/canvas.d.ts +3 -0
  27. package/dist/types/library/components/extras.d.ts +15 -0
  28. package/dist/types/library/components/feedback.d.ts +1 -0
  29. package/dist/types/library/components/forms-shared.d.ts +55 -0
  30. package/dist/types/library/components/layout-motion.d.ts +14 -0
  31. package/dist/types/library/components/layout.d.ts +1 -0
  32. package/dist/types/library/components/marketing.d.ts +35 -0
  33. package/dist/types/library/components/new-components.d.ts +1 -0
  34. package/dist/types/library/components/scheduling.d.ts +2 -0
  35. package/dist/types/library/components/wave3.d.ts +6 -0
  36. package/dist/types/library/highlight.d.ts +21 -0
  37. package/dist/types/library/qr.d.ts +12 -0
  38. package/dist/types/library/responsive-style.d.ts +51 -0
  39. package/dist/types/library/sx.d.ts +51 -0
  40. package/dist/types/runtime/env.d.ts +33 -0
  41. package/dist/types/runtime/evaluator.d.ts +30 -0
  42. package/dist/types/runtime/http.d.ts +37 -1
  43. package/dist/types/runtime/index.d.ts +2 -0
  44. package/dist/types/runtime/namespaces-extra.d.ts +73 -0
  45. package/dist/types/runtime/realtime.d.ts +46 -0
  46. package/dist/types/runtime/router.d.ts +42 -4
  47. package/dist/types/runtime/ssr.d.ts +29 -0
  48. package/dist/types/runtime/util.d.ts +65 -0
  49. package/dist/types/testing/index.d.ts +35 -0
  50. package/dist/types/theme/fonts.d.ts +30 -0
  51. package/dist/types/theme/index.d.ts +28 -0
  52. package/dist/types/theme/styles.d.ts +1 -1
  53. package/dist/types/tooling/html-import.d.ts +19 -0
  54. package/dist/types/tooling/index.d.ts +3 -0
  55. package/dist/types/tooling/schema.d.ts +58 -0
  56. package/package.json +1 -1
@@ -139,6 +139,27 @@ function CartBadge() { return Badge(`${cart.items.length} items`) }
139
139
 
140
140
  Use a store for shared state; use a component's local `$state` / `$name` for state one component owns.
141
141
 
142
+ 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.
143
+
144
+ ```
145
+ prefs = $store({
146
+ persist: "user-prefs", // restored on reload, saved on every change
147
+ theme: "system",
148
+ setTheme: (s, t) => { s.theme = t },
149
+ })
150
+ ```
151
+
152
+ 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.
153
+
154
+ ```
155
+ doc = $store({
156
+ history: true,
157
+ title: "", body: "",
158
+ setTitle: (s, t) => { s.title = t },
159
+ })
160
+ undoBtn = Button("Undo", { onClick: () => doc.undo(), disabled: !doc.canUndo })
161
+ ```
162
+
142
163
  ## Components & Actions
143
164
 
144
165
  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 +179,8 @@ $app(Column([UserCard($currentUser), UserCard($other, { tone: "primary" })]))
158
179
  - The positional argument lands in the component's first parameter (the `children` slot for container-style components).
159
180
  - User components shadow built-ins of the same name — wrap a library component to add telemetry or styling.
160
181
  - Use a lambda (`row = item => Row(item)`) for one-off helpers that don't need a named component.
182
+ - **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 })`.
183
+ - **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
184
 
162
185
  ### Actions
163
186
  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 +204,29 @@ resetBtn = Button("Reset", { onClick: () => { $count = 0; $message = "" } })
181
204
  ### `$emit("name", { detail })`
182
205
  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
206
 
207
+ ### Reactive environment globals (under `$util`)
208
+ 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:
209
+ - `$util.viewport.width` / `.height`
210
+ - `$util.breakpoint.active` (`base|sm|md|lg|xl`) + `.sm` / `.md` / `.lg` / `.xl` booleans
211
+ - `$util.scroll.y` / `.x` / `.progress` (0–1) / `.direction` (`up|down`)
212
+ - `$util.media.prefersDark` / `.prefersReducedMotion` / `.online` / `.pointer` (`coarse|fine`) / `.portrait`
213
+ - `$util.mouse.x` / `.y`
214
+ - `$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).
215
+
216
+ ```
217
+ Show($util.breakpoint.md, { children: Sidebar(), fallback: Drawer() })
218
+ NavBar({ blur: $util.scroll.y > 12 })
219
+ ```
220
+
221
+ ### `$util.onError(fn)`
222
+ 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.
223
+
224
+ ### `$util.onNavigate(fn)`
225
+ 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.
226
+
227
+ ### `$util.onRequest(fn)` / `$util.onResponse(fn)`
228
+ 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.
229
+
184
230
  ## Effects — Declarative side effects
185
231
 
186
232
  `$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 +281,7 @@ view = Async($orders, {
235
281
 
236
282
  ### `$query({...})` and `$mutation({...})`
237
283
  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()`).
284
+ - `$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
285
  - `$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
286
  ```
241
287
  $save = $mutation({ url: "https://api.example.com/orders" })
@@ -245,6 +291,25 @@ Button("Save", { onClick: () => $save.mutate({ body: { item: $item } }) })
245
291
  ```
246
292
  `.mutate()` resolves with the response body; the bag exposes `.loading`/`.error`/`.data` plus `.reset()`.
247
293
 
294
+ **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.
295
+
296
+ **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.
297
+
298
+ **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`).
299
+
300
+ ```
301
+ $repos = $query({ url: "/graphql", gql: "query($n:Int){ repos(first:$n){ name } }", variables: { n: 10 } })
302
+ ```
303
+
304
+ ### Realtime — `$socket({...})` and `$sse({...})` (VI.3)
305
+ - `$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.
306
+ - `$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.
307
+ ```
308
+ $chat = $socket({ url: "wss://example.com/room/42" })
309
+ send = () => { $chat.send({ text: $draft }); $draft = "" }
310
+ feed = Column(map($chat.messages, m => Bubble(m.text)))
311
+ ```
312
+
248
313
  ## Routing
249
314
 
250
315
  `$router({ ... })` is a plain function call — assign it and drop the result into your page shell.
@@ -261,9 +326,32 @@ $app(AppShell(MainSidebar(), pages)) // app/dashboard shell
261
326
 
262
327
  - **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
328
  - 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.
329
+ - 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`).
330
+ - **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.
331
+ - **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.
332
+ - **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).
333
+ - **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.
334
+ ```
335
+ pages = $router({
336
+ "/app": {
337
+ layout: AppShell(MainSidebar(), outlet), // `outlet` = the matched child
338
+ routes: {
339
+ "/": Dashboard(),
340
+ "/orders/:id": OrderDetail({ id: params.id }),
341
+ default: AppHome()
342
+ }
343
+ },
344
+ default: Landing()
345
+ })
346
+ ```
265
347
  - `NavLink(label, { to, exact?, icon? })` and `SidebarItem(label, { to, icon?, badge? })` derive active state from `route.path`. Never declare `route` yourself.
266
348
 
349
+ ```
350
+ $util.onNavigate(({ to }) => $isLoggedIn || to === "/login" ? true : "/login") // auth gate
351
+ function selectTab(name) { $util.url.setQuery("tab", name) } // shareable tab
352
+ activeTab = $util.url.query.tab ?? "overview"
353
+ ```
354
+
267
355
  ## Built-in globals — `storage`, `console` & `$toast`
268
356
 
269
357
  Always in scope, lowercase, no imports.
@@ -319,16 +407,48 @@ $app(Column([
319
407
  ]))
320
408
  ```
321
409
 
410
+ ## Universal style props (`sx` / `animate`) — every component
411
+
412
+ 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.
413
+
414
+ - **`sx: { … }`** — token-aware inline styling. Keys (all optional):
415
+ - Spacing (`xs|s|m|l|xl|2xl|3xl|none|auto`, 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.
416
+ - Sizing (`full|half|screen|dvh|min|max|fit|auto` or length): `w h minW maxW minH maxH`.
417
+ - 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`.
418
+ - 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`.
419
+ - Typography: `fontSize: xs|sm|base|lg|xl|2xl|3xl|4xl` (or a length), `weight: 100…900|bold|normal`, `textDecoration: underline|line-through|none`, `textAlign`.
420
+ - Flex/grid: `display direction align justify wrap grow shrink basis columns`.
421
+ - 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.
422
+ - 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).
423
+ - Responsive: any value may be `{ base, sm, md, lg, xl }` (resolves to `base`).
424
+ - **`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`.
425
+ - **`id` / `anchor`** — set the element id (smooth-scroll targets).
426
+ - **`className` / `style`** — extra classes / a sanitised inline style string.
427
+ - **`aria: {…}` / `data: {…}` / `tooltip` / `hidden`** — accessibility & metadata passthrough.
428
+
429
+ ```
430
+ Card([Text("Lift on hover")], { sx: { p: "l", radius: "lg", bg: "surface", shadow: "md", hover: { lift: true } } })
431
+ Badge("Live", { tone: "success", animate: "pulse" })
432
+ Display(["Build in ", GradientText("record time")], { size: "hero", align: "center", animate: "fade-up" })
433
+ ```
434
+
322
435
  ## Theming, i18n & icons
323
436
 
324
437
  ### `$theme({ ... })`
325
- A bare `$theme({...})` statement (near the top) brands the response. Structured groups: `colors`, `radius`, `font` (plus metadata `name`, `direction`). Omit it to inherit the host theme.
438
+ 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.
439
+
440
+ Core group keys (all optional):
441
+ - `name?: string` — selects a built-in theme as the base palette (`"dark"`, `"neon"`, …; unknown names are ignored).
442
+ - `direction?: "ltr" | "rtl"` — reading direction (metadata; not applied as a token).
443
+ - `colors?: { ... }` — CSS color strings. Keys: `bg`, `bgSubtle`, `surface`, `surfaceMuted`, `border`, `borderSubtle`, `text`, `textMuted`, `primary`, `primaryHover`, `primaryText`, `accent`, `accentHover`, `accentText`, `focusRing`, `success`, `warning`, `danger`, `info`.
444
+ - `radius?: { ... }` — CSS length strings. Keys: `xs`, `sm`, `md`, `lg`, `pill`, `button`, `input`.
445
+ - `font?: { ... }` — CSS strings. Keys: `family`, `familyHeading`, `familyMono`, `sizeBase`, `sizeSm`, `sizeLg`, `sizeHeading`, `sizeTitle`, `weightBody`, `weightHeading`.
326
446
 
327
447
  ```
328
448
  $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" }
449
+ colors: { primary: "#635bff", primaryHover: "#4f46e5", accent: "#1f6feb", bg: "#0a0a23", surface: "#10103a", text: "#fff", textMuted: "#a5b4fc", focusRing: "#635bff" },
450
+ radius: { md: "0.5rem", button: "999px", input: "8px" },
451
+ font: { family: "Inter, sans-serif", familyHeading: "Inter, sans-serif", weightHeading: "600" }
332
452
  })
333
453
  ```
334
454
 
@@ -342,7 +462,17 @@ const { t, setCurrentLanguage } = $i18n({
342
462
  })
343
463
  welcome = Text(t("greeting", { name: $user.name }))
344
464
  ```
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.
465
+ `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} }`.
466
+
467
+ ### RTL / bidirectional text
468
+ 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.
469
+
470
+ ### Accessibility primitives
471
+ - `VisuallyHidden(child)` — hides content visually, keeps it in the a11y tree.
472
+ - `SkipLink({ to: "#main", label: "Skip to content" })` — first tab stop for keyboard users.
473
+ - `LiveRegion(Text($status), { mode: "polite" })` — announces dynamic changes (`"polite"` queues; `"assertive"` interrupts).
474
+ - `FocusTrap(child, { active: $isOpen })` — Tab cycles within the subtree; required for dialogs.
475
+ - Pass `aria: { label, labelledBy, describedBy, ... }` to any component via the universal props channel.
346
476
 
347
477
  ### Icons
348
478
  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 +486,47 @@ Pure helpers (no side effects), available in every expression, action, effect, a
356
486
  - **Strings**: `$util.capitalize / .titlecase / .uppercase / .lowercase`, `.plural(n, singular, plural)`, `.trim / .replace / .split / .match`.
357
487
  - **Formatting**: `$util.format(value, mode, opts?)` (number, currency, percent, compact) and `$util.formatDate(value, mode)` (`"short" | "long" | "time" | "relative"` or a token string).
358
488
  - **Dates / math**: `.now / .today / .addDays / .diffDays / .startOfWeek`; `.round / .floor / .ceil / .abs / .clamp(v, min, max) / .random`.
489
+ - **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).
490
+ - **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).
491
+ - **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
492
 
360
493
  ```
361
494
  sorted = $util.sort($users.filter(u => u.team === $team), "joinedAt", "desc")
362
495
  summary = `${rows.length} ${$util.plural(rows.length, "order", "orders")} · ${$util.format($util.sum(rows.amount), "currency")}`
363
496
  ```
364
497
 
498
+ ## `$util.style`, `$util.rules` and `$util.derived` — styling, validation & computed helpers
499
+
500
+ - **`$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" })`.
501
+ - **`$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 }`).
502
+ - **`$util.derived(fn)`** — a computed value: `total = $util.derived(() => $util.sum($cart.map(i => i.price)))` recomputes reactively from the atoms `fn` reads.
503
+
504
+ ```
505
+ $email = ""
506
+ error = $util.rules.validate($email, [$util.rules.required(), $util.rules.email()])
507
+ Input("email", { value: $email, error: error })
508
+ ```
509
+
510
+ ### `$form({...})` — the form engine (managed forms)
511
+ 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:
512
+ - `form.values.x` — two-way binds straight onto an input (`Input("email", { value: form.values.email })`).
513
+ - `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).
514
+ - `form.field("email")` — returns `{ value, error, name, onChange, onBlur }` to spread for a controlled, validated field.
515
+ - `form.validate()` (all) / `form.validateField(name)` / `form.touch(name)` / `form.setField(name, v)` / `form.setValues({...})` / `form.reset()`.
516
+ - `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.
517
+
518
+ ```
519
+ form = $form({
520
+ values: { email: "", age: "" },
521
+ rules: { email: [$util.rules.required(), $util.rules.email()], age: [$util.rules.min(18)] },
522
+ onSubmit: (v) => { $saved = $mutation({ url: "/signup", body: v }); $saved.mutate() }
523
+ })
524
+ $app(Column([
525
+ Input("email", { value: form.values.email, error: form.errors.email, onBlur: () => form.touch("email") }),
526
+ Button("Submit", { onClick: () => form.handleSubmit(), disabled: form.submitting })
527
+ ]))
528
+ ```
529
+
365
530
  ## Standard helper components
366
531
 
367
532
  | Component | Purpose |
@@ -372,7 +537,15 @@ summary = `${rows.length} ${$util.plural(rows.length, "order", "orders")} · ${$
372
537
  | `Redirect(path)` | Navigate and unmount the rest of the subtree. |
373
538
  | `Lazy(loader, { fallback?, children })` | Defer rendering until the async `loader` resolves; show `fallback` while pending. |
374
539
  | `ErrorBoundary(children, { fallback?, onError? })` | Catch render errors thrown by descendants. |
375
- | `VirtualList(items, { key, render })` | Virtualised list — preferred for >100 rows. |
540
+ | `VirtualList(items, { key, render })` | Virtualised 1-D list — preferred for >100 rows. |
541
+ | `VirtualGrid(items, { columns, rowHeight, render })` | Virtualised 2-D grid — only visible rows mount; essential for tables/grids >100 rows. |
542
+ | `VisuallyHidden(child)` | Hides content visually but keeps it in the accessibility tree (extra context for screen readers). |
543
+ | `SkipLink({ to, label })` | "Skip to main content" link that appears on focus — the first tab stop for keyboard users. |
544
+ | `LiveRegion(child, { mode? })` | `aria-live` region (`mode: "polite"` default or `"assertive"`). Announces dynamic changes to screen readers. |
545
+ | `FocusTrap(child, { active })` | Cycles Tab within its subtree and autofocuses the first control — required for accessible dialogs. |
546
+ | `Fragment(children)` | Groups siblings without a layout box (`display:contents`) so a component can return several nodes into a parent Grid/Stack. |
547
+ | `Transition(child, { show, preset, duration? })` | Enter/exit transition — keeps child mounted through exit animation; reduced-motion safe. |
548
+ | `FlipList(children, { duration? })` | FLIP reorder animation — keyed children physically move to their new positions. |
376
549
 
377
550
  ## Component library
378
551
  Use only these components. Each signature lists props in declaration order; optional props end with `?`. The prop tagged `(positional)` is the canonical positional slot — pass it bare; every other prop goes in a trailing `{ prop: value }` object.
@@ -405,18 +578,18 @@ Use only these components. Each signature lists props in declaration order; opti
405
578
  - 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
579
  - 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
580
  - 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.
581
+ - 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
582
  - 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
583
  - MasonryGrid(items: Node[], columns?: number, gap?: "xs"|"s"|"m"|"l"|"xl") — Pinterest-style column grid. Children flow into columns that reflow on viewport changes. Use for galleries, social-style feeds, and mixed-height card walls. Prefer `Grid` when children should share the same height per row.
411
584
 
412
585
  ### Content
413
586
  - 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`. `fit` controls how the image fills that box. When `src` is missing or unsafe the component renders a placeholder (or `fallback` text/icon).
587
+ - 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
588
  - 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
589
  - 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
590
  - 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
591
  - 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.
592
+ - 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
593
  - 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
594
  - 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
595
  - Markdown(content: string) — Render markdown-flavoured text. Supports **bold**, *italic*, `code`, headings (`#`/`##`/`###`), blockquotes (`>`), bullet (`-`/`*`) and numbered (`1.`) lists, fenced code blocks (```), images (`![alt](src)`), inline links, and auto-linked bare URLs. Multi-line paragraphs collapse into `<p>` blocks.
@@ -429,13 +602,13 @@ Use only these components. Each signature lists props in declaration order; opti
429
602
  - 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
603
  - 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
604
  - 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.
605
+ - 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.
606
+ - 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
607
  - 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
608
  - 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
609
  - 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
610
  - 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.
611
+ - 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
612
  - SelectItem(value: string, label: string) — Single option for a Select component.
440
613
  - 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
614
  - 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.
@@ -449,7 +622,7 @@ Use only these components. Each signature lists props in declaration order; opti
449
622
  - Buttons(items: Button[], direction?: "row"|"column") — Group of buttons laid out horizontally or vertically.
450
623
  - 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
624
  - 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.
625
+ - 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
626
  - 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
627
  - 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
628
  - 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 +635,7 @@ Use only these components. Each signature lists props in declaration order; opti
462
635
  ### Data
463
636
  - 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
637
  - 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.
638
+ - 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
639
  - List(items: ListItem[], ordered?: boolean) — Vertical list of ListItems.
467
640
  - ListItem(title: string, description?: string, icon?: string) — Single list item with optional title and description.
468
641
  - 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 +663,7 @@ Use only these components. Each signature lists props in declaration order; opti
490
663
  - Series(name: string, values: number[]) — Named data series for charts. Used inside BarChart, LineChart, PieChart.
491
664
 
492
665
  ### 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.
666
+ - 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
667
  - 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
668
  - 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
669
  - 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 +671,7 @@ Use only these components. Each signature lists props in declaration order; opti
498
671
  - 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
672
  - 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
673
  - 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.
674
+ - 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
675
  - 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
676
  - 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
677
  - 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.
@@ -584,7 +758,7 @@ Use only these components. Each signature lists props in declaration order; opti
584
758
  - NotificationBell(count?: number, items?: any[], onOpen?: callable) — Bell icon with unread count badge and dropdown notification list.
585
759
 
586
760
  ### 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).
761
+ - 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
762
 
589
763
  ### Helpers
590
764
  - 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 +766,7 @@ Use only these components. Each signature lists props in declaration order; opti
592
766
  - Portal(target?: string, children: Node[] (positional)) — Render children outside the parent subtree (e.g. into document.body).
593
767
  - Redirect(path: string (positional)) — Navigate to `path` and unmount the rest of the subtree.
594
768
  - 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.
769
+ - 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
770
 
597
771
  ### Behaviour wrappers
598
772
  - 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 +780,85 @@ Use only these components. Each signature lists props in declaration order; opti
606
780
 
607
781
  ### Escape hatches
608
782
  - 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.
783
+ - 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
784
 
611
785
  ### Other
786
+ - 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.
612
787
  - TextContent(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", style?: string) — Deprecated alias for `Text`. Prefer `Text(...)` — both render identically.
788
+ - 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).
789
+ - 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).
790
+ - 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.
791
+ - 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.
792
+ - Eyebrow(text: string (positional)) — Small uppercase, letter-spaced, primary-toned label above a heading.
793
+ - Section(children: Node[] (positional), background?: "base"|"soft"|"surface"|"muted"|"brand", width?: "sm"|"md"|"lg"|"xl"|"full", padding?: "sm"|"md"|"lg", 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.
794
+ - 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.
795
+ - 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.
796
+ - Brand(name: string (positional), logo?: string, version?: string, href?: string) — Logo + product name (+ optional version pill), linking home. Use in NavBar/Footer.
797
+ - 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.
798
+ - 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.
799
+ - FooterColumn(title: string (positional), links: Node[]) — A titled column of links inside a Footer.
800
+ - LogoCloud(items: LogoChip[] (positional), label?: string) — A centered, wrapping row of LogoChip items with an optional label — 'works with' / 'trusted by' bands.
801
+ - LogoChip(label: string (positional), icon?: string) — A single labelled chip (icon + name) for a LogoCloud.
802
+ - 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.
803
+ - 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.
804
+ - MetricStrip(items: Metric[] (positional), columns?: number) — A responsive row/grid of Metric tiles. `columns` sets the preferred count.
805
+ - 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.
806
+ - BrowserFrame(child: Node (positional), url?: string) — A browser-window chrome (dots + URL bar) wrapping a child — for screenshots/demos of web UIs.
807
+ - Terminal(lines: string[] (positional), file?: string) — A terminal window rendering monospace lines. Pass `lines` as an array of strings.
808
+ - 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`).
809
+ - 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.
810
+ - Swatch(name: string (positional), background?: string, foreground?: string, colors?: string[]) — A theme/palette preview tile — color dots over a named background. For theming galleries.
811
+ - 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.
812
+ - 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.
813
+ - FloatingActionButton(icon: string (positional), label?: string, onClick?: callable) — A fixed circular action button (FAB) anchored bottom-right. `icon` + `onClick`.
814
+ - 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.
815
+ - RelativeTime(value: string | number (positional)) — Renders a human relative time ('3m ago', 'in 2 days') from an ISO date/timestamp, localized via Intl.
816
+ - 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.
817
+ - 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.
818
+ - 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.
819
+ - TableOfContents(items: object[] (positional), title?: string) — A navigable table of contents. `items` is an array of {label, href, level?}.
820
+ - TypingIndicator(name?: string (positional)) — Three animated bouncing dots — a chat 'is typing…' affordance. Optional `name` prefix.
821
+ - CountdownTimer(to: string | number (positional), endLabel?: string) — Live countdown to a target date/time (ISO string or timestamp). Ticks every second, then shows `endLabel`.
822
+ - BackToTop(label?: string) — A floating button that smoothly scrolls the page (and the host) back to the top.
823
+ - Split(left: Node (positional), right: Node, ratio?: string, gap?: "none"|"s"|"m"|"l"|"xl", 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.
824
+ - Bento(items: BentoCell[] (positional), columns?: number, gap?: "s"|"m"|"l"|"xl", rowHeight?: string, dense?: boolean) — Asymmetric 'bento box' grid where cells span varied widths/heights — the marquee feature-section layout. Children should be BentoCell nodes (plain nodes are treated as 1×1). `columns` sets the track count (default 6), `rowHeight` sizes the implicit rows so `tall`/`hero` cells actually grow, and `dense` (default true) backfills gaps. Collapses to 2 columns below 920px and 1 below 640px.
825
+ - BentoCell(child: Node (positional), span?: string | number | object, rowSpan?: number) — A single cell in a Bento grid. `span` is a named size (tile|wide|tall|hero|full), a "CxR" string like "2x1", a bare column-span number, or `{ col, row }`. The child stretches to fill the cell.
826
+ - 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).
827
+ - 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.
828
+ - 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.
829
+ - 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.
830
+ - DropZone(child: Node (positional), onDrop?: callable, label?: string) — A target that accepts a Draggable. `onDrop(data)` receives the dropped payload (parsed JSON when possible).
831
+ - 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.
832
+ - ReadingProgress(gradient?: boolean, height?: string) — A thin progress bar that fills as the page scrolls — article/docs reading affordance. Optional gradient fill.
833
+ - 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).
834
+ - 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.
835
+ - 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.
836
+ - 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.
837
+ - 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.
838
+ - 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.
839
+ - 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).
840
+ - 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?}.
841
+ - 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`.
842
+ - AuthorByline(name: string (positional), avatar?: string, role?: string, date?: string) — An author byline: avatar, name, optional role and date — for articles/blog posts.
843
+ - 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.
844
+ - 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.
845
+ - 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.
846
+ - 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}.
847
+ - 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.
848
+ - 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.
849
+ - 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.
850
+ - 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.
851
+ - 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.
852
+ - 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.
853
+ - 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.
854
+ - 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.
855
+ - 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.
856
+ - 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.
857
+ - 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.
858
+ - 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).
859
+ - 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.
860
+ - 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`.
861
+ - 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
862
 
614
863
  ## Examples
615
864
  ```
@@ -56,12 +56,12 @@ Use only these components. Each signature lists props in declaration order; opti
56
56
 
57
57
  ### Content
58
58
  - 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.
59
- - Image(src: string, alt?: string, caption?: string, ratio?: string, fit?: "cover"|"contain"|"fill"|"none"|"scale-down", fallback?: string) — Inline image. `ratio` constrains the box to a fixed aspect ratio (e.g. `16:9`, `1:1`) so callers do not need an outer `AspectRatio`. `fit` controls how the image fills that box. When `src` is missing or unsafe the component renders a placeholder (or `fallback` text/icon).
59
+ - 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.
60
60
  - 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`.
61
61
  - 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.
62
62
  - 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.
63
63
  - 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.
64
- - 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.
64
+ - 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.
65
65
  - 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`.
66
66
  - 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`).
67
67
  - Markdown(content: string) — Render markdown-flavoured text. Supports **bold**, *italic*, `code`, headings (`#`/`##`/`###`), blockquotes (`>`), bullet (`-`/`*`) and numbered (`1.`) lists, fenced code blocks (```), images (`![alt](src)`), inline links, and auto-linked bare URLs. Multi-line paragraphs collapse into `<p>` blocks.
@@ -94,7 +94,7 @@ Use only these components. Each signature lists props in declaration order; opti
94
94
  - Series(name: string, values: number[]) — Named data series for charts. Used inside BarChart, LineChart, PieChart.
95
95
 
96
96
  ### Feedback & Media
97
- - 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.
97
+ - 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.
98
98
  - 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.
99
99
  - 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.
100
100
  - 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.