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.
Files changed (60) hide show
  1. package/README.md +216 -36
  2. package/dist/aktion.iife.js +920 -144
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +17025 -10815
  5. package/dist/aktion.js.map +1 -1
  6. package/dist/aktion.umd.cjs +920 -144
  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 +7042 -2455
  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 +292 -41
  17. package/dist/system_prompt_chat.txt +14 -14
  18. package/dist/testing.js +16223 -7977
  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/library/types.d.ts +50 -0
  41. package/dist/types/library/utils.d.ts +28 -0
  42. package/dist/types/library/validate.d.ts +2 -2
  43. package/dist/types/runtime/env.d.ts +33 -0
  44. package/dist/types/runtime/evaluator.d.ts +38 -0
  45. package/dist/types/runtime/http.d.ts +37 -1
  46. package/dist/types/runtime/index.d.ts +2 -0
  47. package/dist/types/runtime/namespaces-extra.d.ts +73 -0
  48. package/dist/types/runtime/realtime.d.ts +46 -0
  49. package/dist/types/runtime/router.d.ts +42 -4
  50. package/dist/types/runtime/ssr.d.ts +29 -0
  51. package/dist/types/runtime/util.d.ts +65 -0
  52. package/dist/types/testing/index.d.ts +35 -0
  53. package/dist/types/theme/fonts.d.ts +30 -0
  54. package/dist/types/theme/index.d.ts +31 -0
  55. package/dist/types/theme/styles.d.ts +1 -1
  56. package/dist/types/tooling/html-import.d.ts +19 -0
  57. package/dist/types/tooling/index.d.ts +3 -0
  58. package/dist/types/tooling/schema.d.ts +58 -0
  59. package/dist/types/tooling/signature-help.d.ts +35 -0
  60. package/package.json +1 -1
package/README.md CHANGED
@@ -107,14 +107,57 @@ Everything you need at runtime ships in a single bundle:
107
107
  `$toast.success/.error/.info/.warning`, `$toast.dismiss(id)`,
108
108
  `$toast.clear()`, and a reactive `$toast.items` list to render with
109
109
  `Toasts`/`Toast`.
110
+ - **`$form({ values, rules, onSubmit })` — the form engine.** Managed
111
+ reactive form with per-field `$util.rules` validators (including async
112
+ ones via `$util.rules.asyncCustom` — think server-side uniqueness checks),
113
+ touched/dirty tracking, and `form.submit()` (alias `handleSubmit()`) that
114
+ validates — awaiting async rules — then calls `onSubmit`. Access
115
+ `form.values.field` (two-way bindable), `form.errors.field`,
116
+ `form.touched.field`, `form.dirty` (flips on the first edit, even via
117
+ two-way binding; clears on reset), `form.valid`, `form.submitting`
118
+ (stays `true` until an async `onSubmit` settles), `form.validating`
119
+ (async rules in flight), and call `form.setField()`, `form.touch()`,
120
+ `form.reset()`. `Input`/`TextArea`/`Select`/`NumberInput` accept
121
+ `onBlur`/`onFocus`, so validate-on-blur is one prop:
122
+ `Input("email", { value: form.values.email, onBlur: () => form.touch("email") })`.
123
+ - **`$store` persistence + undo/redo.** Add `persist: "key"` to mirror the
124
+ store to `localStorage` (or `persistIn: "session"` for `sessionStorage`) — hydrates on mount. Add `history: true` (or a depth number) for full undo/redo: `store.undo()` / `store.redo()` / `store.canUndo` / `store.canRedo`.
125
+ - **Universal `sx` / `animate` styling channel.** Every component accepts a
126
+ token-aware `sx` object — spacing (`p px py pt…`, logical `ps pe ms me`;
127
+ `px`/`mx` emit `padding-inline`/`margin-inline` so RTL apps mirror
128
+ automatically), sizing (`w h minW maxW…`), color (`bg color borderColor`,
129
+ gradient refs like `"gradient.brand"`), surface (`border radius shadow
130
+ opacity backdrop`), background imagery (`bgImage` + `bgOverlay` wash +
131
+ `bgSize`), typography (`fontSize weight textDecoration textAlign`),
132
+ flex/grid (`display direction align justify wrap grow shrink basis
133
+ columns`), position/layering (`position top right bottom left inset
134
+ zIndex` — layer tokens resolve through themeable `--rui-z-*` vars), and
135
+ interaction `states: { hover|focus|active|disabled|… }` compiled to
136
+ scoped CSS rules — plus `animate: "fade-up"` motion presets. Any value
137
+ accepts a `{ base, sm, md, lg, xl }` map that resolves to real `@media`
138
+ breakpoints. No stylesheet required.
139
+ - **60+ new components** since v0.4: marketing bands (`Section`, `Split`,
140
+ `Bento`), motion (`Reveal`, `Transition`, `FlipList`, `Parallax`),
141
+ accessibility primitives (`VisuallyHidden`, `SkipLink`, `LiveRegion`,
142
+ `FocusTrap`), realtime (`TypingIndicator`, `PresenceAvatars`,
143
+ `ReactionPicker`, `LiveCursor`), e-commerce (`Cart`, `ProductCard`,
144
+ `OrderSummary`), canvas (`DrawingCanvas`, `SignaturePad`), scheduling
145
+ (`Calendar`), virtualization (`VirtualGrid`), and many more.
146
+ - **RTL + logical layout.** Set `dir="rtl"` on `<aktion-app>` and the whole
147
+ tree flips (text direction, flex order, logical spacing). Programs need no
148
+ code change.
149
+ - **SSR / SSG.** `renderToString(program, { path, initialState })` → `{ html, state }` for server-side rendering. `renderToStaticMarkup` for static pages.
150
+ - **DX tooling.** `tailwindToSx(classString)` maps Tailwind classes to `sx`; `htmlToAktion(html)` imports common HTML/JSX; `componentSchema()` emits a stable JSON schema for editor autocomplete; `buildGallery()` generates a self-contained component explorer; `suggestComponent("Buttn")` returns typo candidates.
151
+ - **Testing utilities.** `within(node)` for scoped queries, `axe(node)` for a11y audits from the `aktion-runtime/test` entry.
110
152
  - **A React-like DOM reconciler.** Diffs each re-render against the live
111
153
  DOM. Text-input value, selection, IME state, scroll positions,
112
154
  `<details>.open`, and stateful primitives like `Tabs` are all preserved
113
155
  across renders. Components that need to hold UI state get a
114
156
  `helpers.useInstanceState(...)` slot keyed by their position in the tree.
115
- - **A rich component library** of **170+ components** spanning layout,
157
+ - **A rich component library** of **271 components** spanning layout,
116
158
  forms, charts, data, feedback, navigation, patterns, app-shell composites,
117
- editors, advanced UI, and standard helpers. See [Component library](#component-library).
159
+ editors, advanced UI, motion, marketing, e-commerce, accessibility,
160
+ realtime, and standard helpers. See [Component library](#component-library).
118
161
  - **Declarative side effects.** `$effect(() => { body }, [...deps])` for
119
162
  background work — anonymous blocks where the dependency list mixes
120
163
  state triggers (`$atom`), lifecycle triggers (`"mount"`, `"unmount"`,
@@ -138,9 +181,12 @@ Everything you need at runtime ships in a single bundle:
138
181
  wired up.
139
182
  - **Seven built-in themes** (`light`, `dark`, `neon`, `pastel`, `glass`,
140
183
  `brutalist`, `skyline`) plus full custom-token support via CSS custom
141
- properties. **50+ design tokens** organised into `colors`, `radius`,
142
- and `font` groups. Brand the UI from inside the script with
143
- `$theme({...})` statement.
184
+ properties. **80+ design tokens** organised into `colors`, `radius`,
185
+ `font`, `spacing`, `shadows`, `gradients` (referenced as
186
+ `"gradient.brand"` from `sx`/`GradientText`), `zIndex` (layer tokens
187
+ feeding `sx.zIndex`), and `motion` groups — plus `fonts` (Google-Fonts
188
+ shorthand import) and `icons` (custom inline-SVG registration). Brand
189
+ the UI from inside the script with a `$theme({...})` statement.
144
190
  - **`$i18n` factory.** `const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({ defaultLanguage, currentLanguage, translations })` builds a translation bundle keyed by language, with `{name}` placeholder interpolation.
145
191
  - **Font Awesome 6.7.2** auto-loaded — every `icon` prop accepts a Free
146
192
  Font Awesome name (no `fa-` prefix). Use `Icon(name, { variant?, size? })`
@@ -313,6 +359,8 @@ All members live on the `<aktion-app>` element.
313
359
  | `strict` | `true` / unset | Dev/strict mode. Surfaces silent failures as `console.warn`s — unknown identifiers that would resolve to `null`, and trailing `{...}` objects passed to a user component whose keys match no parameter (the silent named→positional flip). Off by default; enable while developing. |
314
360
  | `router-mode` | `hash` (default) / `history` | URL strategy. `history` uses the History API for clean `/about` URLs (needs an `index.html` fallback on the server); `hash` works on any static host. |
315
361
  | `router-base` | path string (e.g. `/app`) | Sub-directory the SPA is served under, stripped from / prepended to URLs in `history` mode. |
362
+ | `dir` | `ltr` / `rtl` / `auto` | Writing direction. Reflects onto the render root so logical CSS properties, flex order, and text direction flip automatically. Programs need no code change. |
363
+ | `scroll-restoration` | `auto` / `top` | Opt-in scroll restoration. `auto` restores per-path scroll on back/forward and jumps to top on fresh navigation; `top` always jumps to top. |
316
364
 
317
365
  Routing and JavaScript execution inside `effect` / action bodies are
318
366
  always available — no host attribute, no allow-list. To omit those
@@ -346,6 +394,30 @@ surfaces from the *generated prompt*, build it via
346
394
  | `loadSnapshot({ programText, state })` | Atomic program + state load. The next render plans the program with the hydrated state already in place. |
347
395
  | `applyDelta(ops)` | Apply a structured delta (`patch` / `replace` / `append` / `new` / `delete`). User `$state` is preserved across the diff. |
348
396
 
397
+ ### Module exports
398
+
399
+ Beyond the element, `aktion-runtime` exports a set of standalone utilities importable from subpaths:
400
+
401
+ ```ts
402
+ import { renderToString, renderToStaticMarkup } from "aktion-runtime";
403
+ // → { html, state } for SSR; renderToStaticMarkup for SSG
404
+
405
+ import { htmlToAktion, tailwindToSx, componentSchema, buildGallery, suggestComponent } from "aktion-runtime";
406
+ // htmlToAktion(html) → Aktion program string from common HTML/JSX
407
+ // tailwindToSx("p-4 bg-white") → sx object ({ p: "m", bg: "surface", _unmapped: [...] })
408
+ // componentSchema() → stable JSON schema for editor tooling
409
+ // buildGallery() → self-contained HTML component explorer
410
+ // suggestComponent("Buttn") → ["Button", ...] typo suggestions
411
+
412
+ import { render, within, axe, cleanup } from "aktion-runtime/test";
413
+ // render(program, opts) → Screen with Testing-Library-style queries + interactions
414
+ // within(node) → scoped query set
415
+ // axe(node) → a11y audit (returns array of violations)
416
+
417
+ import { getDiagnostics, getCompletions, formatProgram } from "aktion-runtime/language";
418
+ // DOM-free language service for editor integrations
419
+ ```
420
+
349
421
  ### Events
350
422
 
351
423
  | Event | Detail | When it fires |
@@ -436,18 +508,23 @@ $app(pages)
436
508
  operators (`= += -= *= /= ??= ++ --`) are all allowed.
437
509
  `let/const/var` are optional and do not affect reactivity — only the
438
510
  `$` prefix makes a value reactive.
439
- - **Component-call shape** — every call follows the trailing-object
440
- rule:
511
+ - **Component-call shapes** — pick ONE per call:
441
512
 
442
513
  ```js
443
- Component(positionalArg, { prop: value, … })
514
+ Component(positionalArg, { prop: value, … }) // canonical
515
+ Component(arg1, arg2, arg3) // all-positional, signature order
516
+ Component({ prop: value, … }) // all-named single object
444
517
  ```
445
518
 
446
- Each component accepts **at most one positional argument** (typically
447
- the title, children array, or primary value); every other argument
448
- goes in a trailing `{ }` object literal. This is the *only* call
449
- shape — `Button("Save", "primary", true)` is a schema error; write
450
- `Button("Save", { variant: "primary", loading: true })` instead.
519
+ The canonical form passes the prop tagged `(positional)` bare and every
520
+ other prop in a trailing `{ }` object. All-positional calls bind
521
+ arguments to the signature's props in listed order — mind that order:
522
+ `Button("Save", "primary")` puts `"primary"` in the second slot
523
+ (`onClick`), not `variant`, so prefer the trailing object for
524
+ non-adjacent props. A single `{ }` argument whose keys are prop names
525
+ is an all-named call; when the component's positional prop is itself
526
+ object-typed, a lone object is that prop's payload instead. One object
527
+ is never split between the two roles.
451
528
  - `function Name(p = default) { return Expression }` — PascalCase name
452
529
  means it's a component. Parameters use standard JS defaults (`=`).
453
530
  Inside the body, `$x = expr` is a **declaration**: the initializer
@@ -455,6 +532,11 @@ $app(pages)
455
532
  whatever value the user (or an action / effect) has written.
456
533
  **Always** end with an explicit `return`. Components do not have a
457
534
  `props` object — every parameter is a real JS parameter.
535
+ A custom component may NOT reuse a built-in component's name (the
536
+ validator flags it) — unless its body calls that same name, the
537
+ supported **wrapper pattern**: inside its own body the name resolves to
538
+ the BUILT-IN, so `function Badge(l) { return Badge(l, { tone:
539
+ "success" }) }` extends the library Badge instead of recursing.
458
540
  - `function name(args) { body }` — camelCase name means it's an action.
459
541
  Callable effects with optional `return`. Used as event handlers
460
542
  (`onClick: save`) or as expressions (`$result = greet("Ada")`). Wrap
@@ -515,23 +597,23 @@ $app(pages)
515
597
  `.status`, `.loading`, `.headers`, `.lastUpdated`, `.refetch()`,
516
598
  `.cancel()`, and a settable `.onDone` callback that fires each time the
517
599
  request settles (handy for `$todos.refetch()` after a write).
518
- - `$query({ url, key?, ttl? })` — a **cached, deduplicated** read built on
519
- `$http`. Identical queries (same `key`, or same method + url + query +
520
- body) share one in-flight request and one cached bag, so the same data
521
- fetched from several components hits the network once. Optional `ttl` (ms)
522
- auto-refetches stale data. Same reactive bag as `$http`.
523
- - `$mutation({ url, method? })` — a **deferred** write that fires only when
600
+ - `$query({ url, key?, ttl?, refetchInterval?, refetchOnFocus?, refetchOnReconnect? })` — a **cached, deduplicated** read built on
601
+ `$http`. Identical queries share one bag. Optional `ttl` auto-refetches stale data; `refetchInterval` (ms) polls a live feed; `refetchOnFocus` / `refetchOnReconnect` refresh on tab focus / reconnect. Add `infinite: { param, limit, mode, select }` for a paginated list — `$feed.loadMore()` appends the next page while `$feed.hasMore` is true. Pass `gql` (+ optional `variables`) to POST a GraphQL document and unwrap `.data` automatically.
602
+ - `$mutation({ url, method?, optimistic?, invalidates? })` — a **deferred** write that fires only when
524
603
  you call `.mutate(overrides?)` (not on render; `method` defaults to
525
- `POST`). The bag exposes `.loading` / `.error` / `.data`, plus `.reset()`
526
- and a settable `.onDone`. `.mutate()` resolves with the response body.
527
- Assign it to an atom and trigger it from a handler:
528
- `$save = $mutation({ url }); Button("Save", { onClick: () => $save.mutate({ body: $form }) })`.
604
+ `POST`). `optimistic: (overrides) => { … }` runs synchronously before the request and auto-rolls-back if it fails; `invalidates: ["key"]` refetches matching cached queries after success. The bag exposes `.loading` / `.error` / `.data`, plus `.reset()` and a settable `.onDone`. Use `$util.invalidate(keys)` to manually trigger cache invalidation from anywhere.
605
+ - `$socket({ url, protocols?, bufferSize?, reconnect? })` — reactive **WebSocket**. Read `.status` (`"connecting" | "open" | "closed"`), `.connected`, `.last`, `.messages`, `.attempts`; call `.send(data)` (queues while connecting, flushes on open) or `.close()` (stops for good). `reconnect: true` (or a max-attempt number) retries dropped connections with exponential backoff. Auto-tears-down on re-plan.
606
+ - `$sse({ url, event?, withCredentials?, bufferSize? })` — reactive **Server-Sent Events** stream with the same `.status`/`.connected`/`.last`/`.messages`/`.close()` surface (EventSource reconnects natively).
529
607
  - `pages = $router({ "/path": Component(), default: NotFound() })` —
530
608
  function-call router. The reserved `route` handle exposes the
531
609
  reactive surface (`route.path`, `route.params`, `route.query`,
532
- `route.pattern`) and a `route.navigate("/path")` method; each arm
533
- body additionally receives a scoped `params` loop var with its
534
- captures.
610
+ `route.pattern`) and a `route.navigate("/path")` method. Supports
611
+ **nested layout routes** (`"/app": { layout: AppShell, routes: {...} }` —
612
+ the shell stays mounted while only the `outlet` swaps), **navigation guards**
613
+ (`$util.onNavigate(({ to, from }) => …)` — return `false` to block or a
614
+ path to redirect), **query-param state** (`$util.url.setQuery("tab","v")`),
615
+ **lazy routes** (`Lazy(() => import(…))`), and **scroll restoration**
616
+ (set `scroll-restoration="auto"` on `<aktion-app>`).
535
617
  - Two-way binding is implicit: pass a `$variable` (or a member chain
536
618
  rooted at one — `value: $form.email`) as an input prop and the
537
619
  runtime wires it both ways.
@@ -564,7 +646,23 @@ $app(pages)
564
646
  `$util.groupBy`, `$util.format`, `$util.formatDate`, `$util.plural`, `$util.range`,
565
647
  `$util.addDays`, `$util.pick`, `$util.omit`, `$util.merge`, `$util.cloneDeep`,
566
648
  `$util.chunk`, `$util.partition`, `$util.keyBy`, `$util.zip`, `$util.flatten`,
567
- `$util.count`, …). Never carry hidden state — safe to call anywhere.
649
+ `$util.count`, `$util.slugify`, `$util.truncate`, `$util.initials`, `$util.currency`,
650
+ `$util.bytes`, `$util.relativeTime`, `$util.uuid`, `$util.copy` (async — resolves
651
+ `true` only when the clipboard write succeeds), `$util.sleep(ms)`,
652
+ `$util.debounceFn`, `$util.throttleFn` (leading + trailing edge), …). Never
653
+ carry hidden state — safe to call anywhere.
654
+ Also exposes **reactive env getters** (`$util.scroll`, `$util.viewport`,
655
+ `$util.breakpoint`, `$util.media`, `$util.mouse`, `$util.url` — lazy listeners,
656
+ re-render on change; `$util.url.setQuery`/`.removeQuery` write query params),
657
+ **styling/validation sub-namespaces** (`$util.style.cx`,
658
+ `.gradient`, `.alpha`, `.clamp`, `.token`, `.toStyle`; `$util.rules.required()`,
659
+ `.email()`, `.min()`, `.pattern()`, `.custom()`, `.asyncCustom()` — awaited by
660
+ `$form` —, `.validate()`, `.validateAll()`), **computed helper**
661
+ (`$util.derived(fn)`), **side-effect hooks** (`$util.onError`, `$util.onNavigate`,
662
+ `$util.onRequest`, `$util.onResponse`, `$util.invalidate`), and **device/platform
663
+ helpers** (`$util.vibrate`, `.share`, `.readClipboard`, `.geolocate`, `.isOnline`,
664
+ `.deviceType`, `.worker(pureFn)`, `.registerServiceWorker`, `.webManifest`,
665
+ `.nativeShell`, `.isNativeApp`).
568
666
  - **Escape hatches** — `HTMLTag(tag, { attributes?, children? })` for
569
667
  raw HTML elements and `Styles(css)` for raw CSS injected into the
570
668
  shadow root. Use only when the standard component library cannot
@@ -625,7 +723,7 @@ Highlights:
625
723
  - Array shortcuts: `$rows.length`, `$rows.first`, `$rows.last`,
626
724
  plus pluck (`$rows.title` → `[title1, title2, …]`).
627
725
  - Responsive prop maps on layout components:
628
- `Grid(items, { columns: { sm: 1, md: 2, lg: 4 }, gap: "l" })`.
726
+ `Grid(items, { columns: { sm: 1, md: 2, lg: 4 }, gap: "lg" })`.
629
727
  - Forward references are allowed — call `$app(Column([...]))` first
630
728
  and let the children stream in beneath it.
631
729
 
@@ -870,6 +968,20 @@ only components that read it), and store fields support two-way binding
870
968
  component's local `$state` / `$name = value` for state one component owns.
871
969
  See the [Global state guide](https://asfand-dev.github.io/aktion/stores.html).
872
970
 
971
+ **Persistence.** Add `persist: "key"` and the store's data round-trips to `localStorage` on every change and hydrates on mount. Use `persistIn: "session"` for `sessionStorage`. `persist` and `persistIn` are config-only — they're never exposed as state fields.
972
+
973
+ **Undo/redo.** Add `history: true` (or a depth cap) and the store records per-mutation snapshots. `store.undo()` / `store.redo()` / `store.clearHistory()` plus reactive `store.canUndo` / `store.canRedo` for wiring button `disabled` states.
974
+
975
+ ```js
976
+ doc = $store({
977
+ persist: "my-doc", // survives reload
978
+ history: 25, // undo/redo up to 25 steps
979
+ title: "Untitled",
980
+ setTitle: (s, v) => { s.title = v }
981
+ })
982
+ // doc.undo() / doc.redo() / doc.canUndo / doc.canRedo
983
+ ```
984
+
873
985
  ### Component-scoped effects
874
986
 
875
987
  `$effect(() => { … }, [...deps])` blocks can live at the program top level
@@ -926,7 +1038,7 @@ deep authoring guide [`coding-gen-skill.md`](./coding-gen-skill.md).
926
1038
 
927
1039
  ## Component library
928
1040
 
929
- The bundle ships **170+ components** grouped by domain. Reach for **pattern composites**
1041
+ The bundle ships **271 components** grouped by domain. Reach for **pattern composites**
930
1042
  (`Hero`, `PageHeader`, `Stats`, `Toolbar`, `EmptyState`, `Timeline`,
931
1043
  `KanbanBoard`, `DescriptionList`, `PricingTable`, …) before hand-rolling
932
1044
  the equivalent with `Card` + `Stack` — they're tuned to produce dense,
@@ -934,7 +1046,7 @@ production-quality SaaS UI in a single line.
934
1046
 
935
1047
  | Group | Components |
936
1048
  | ------------------ | ---------- |
937
- | **Layout** | `Column`, `Row`, `Center`, `Stack`, `StackItem`, `Grid`, `GridItem`, `Container`, `Box`, `Spacer`, `Card`, `CardHeader`, `CardFooter`, `Separator`, `Tabs`, `TabItem`, `Accordion`, `AccordionItem`, `Modal`, `Drawer`, `Steps`, `AspectRatio`, `ScrollArea`, `Sticky`, `ResizablePanels`, `MasonryGrid` |
1049
+ | **Layout** | `Column`, `Row`, `Center`, `Stack`, `StackItem`, `Grid`, `GridItem`, `Container`, `Box`, `Spacer`, `Card`, `CardHeader`, `CardFooter`, `Separator`, `Tabs`, `TabItem`, `Accordion`, `AccordionItem`, `Modal`, `Drawer`, `Steps`, `AspectRatio`, `ScrollArea`, `Sticky` (with a `data-stuck` pinned hook), `ResizablePanels`, `MasonryGrid`, `Section` (page band with eyebrow/title/subtitle), `Split` (sticky two-pane), `Bento`/`BentoCell` (asymmetric grid), `Overlay`/`OverlayItem` (anchored layering), `Fragment` |
938
1050
  | **Content** | `Text`, `Image`, `Icon`, `Badge`, `BadgeList`, `Callout`, `Quote`, `CodeBlock`, `Skeleton`, `Spinner`, `Markdown`, `Kbd` |
939
1051
  | **Forms** | `Form`, `FormControl`, `FormSection`, `FieldSet`, `ValidationSummary`, `Input`, `TextArea`, `PasswordInput`, `MaskedInput`, `MentionInput`, `TagInput`, `Select`, `SelectItem`, `Combobox`, `MultiSelect`, `Checkbox`, `CheckBoxGroup`, `CheckBoxItem`, `Radio`, `Switch`, `ToggleGroup`, `Button`, `Buttons`, `SearchBar`, `Slider`, `NumberInput`, `ColorPicker`, `DatePicker`, `DateRangePicker`, `TimePicker`, `DateTimePicker`, `FileUpload`, `PinInput`, `MultiStepForm` |
940
1052
  | **Data** | `Table`, `Col`, `DataGrid`, `List`, `ListItem`, `StatCard`, `Stats`, `Sparkline`, `Tile`, `Progress`, `ProgressRing`, `Pagination`, `Tree`, `TreeNode`, `CalendarView`, `ComparisonTable`, `InfiniteList` |
@@ -947,6 +1059,16 @@ production-quality SaaS UI in a single line.
947
1059
  | **Patterns** | `Hero`, `PageHeader`, `SectionHeader`, `Toolbar`, `EmptyState`, `Timeline`, `TimelineItem`, `ActivityLog`, `FeatureGrid`, `FeatureItem`, `MediaCard`, `Testimonial`, `ProfileCard`, `Comment`, `Banner`, `Notification`, `InboxPanel`, `OnboardingChecklist`, `KanbanBoard`, `KanbanColumn`, `KanbanCard`, `DescriptionList`, `DescriptionItem`, `StatusDot`, `PricingTable`, `PricingCard`, `LoadingState`, `ErrorState`, `SuccessState`, `Tour`, `Spotlight` |
948
1060
  | **App shell** | `AppShell`, `Sidebar`, `SidebarSection`, `SidebarItem` (supports `to` for router navigation), `SplitView` |
949
1061
  | **Advanced UI** | `IconButton`, `CommandPalette`, `FilterChips`, `FieldRepeater`, `VirtualList`, `QueryBuilder`, `DiffViewer`, `JsonTree`, `Gantt`, `Truncate`, `InlineEdit`, `NotificationBell` |
1062
+ | **Marketing** | `NavBar` (sticky/blur + mobile burger menu), `Brand`, `Footer`, `FooterColumn`, `LogoCloud`, `LogoChip`, `Display`, `Heading`, `Eyebrow`, `GradientText`, `CountUp`, `Metric`, `MetricStrip`, `CodeWindow`, `BrowserFrame`, `Terminal`, `Backdrop` (grid/blobs/particles), `ThemeToggle`, `Swatch`, `Prose` |
1063
+ | **E-commerce** | `ProductCard`, `PriceTag`, `QuantityStepper`, `VariantSelector`, `OrderSummary`, `Cart` |
1064
+ | **Motion & gestures** | `Reveal` (scroll-triggered), `Transition` (enter/exit), `FlipList` (FLIP reorder), `RouteView` (route transitions), `Parallax`, `OnGesture` (swipe/pan/longPress/doubleTap), `Sortable`, `Draggable`, `DropZone`, `Confetti`, `Lottie` |
1065
+ | **Overlays** | `Sheet`, `BottomSheet`, `ConfirmDialog` — all with Escape-to-close, a Tab focus trap, and focus restore |
1066
+ | **Content & docs** | `TableOfContents`, `ReadingProgress`, `ScrollSpy`, `AuthorByline`, `ShareButtons`, `RelativeTime`, `CopyButton`, `KbdShortcut`, `QRCode`, `Svg` (sanitised inline SVG) |
1067
+ | **Realtime & social** | `TypingIndicator`, `PresenceAvatars`, `ReactionPicker`, `LiveCursor`, `TabBar` (mobile bottom nav) |
1068
+ | **Scheduling** | `Calendar` (month grid with arrow-key navigation, event chips/dots), `CountdownTimer` |
1069
+ | **Canvas** | `DrawingCanvas`, `SignaturePad` |
1070
+ | **Accessibility** | `VisuallyHidden`, `SkipLink`, `LiveRegion`, `FocusTrap` |
1071
+ | **Utility** | `SegmentedControl`, `FloatingActionButton`, `SpeedDial`, `BackToTop`, `VirtualGrid` (windowed 2-D grid) |
950
1072
  | **Helpers** | `Async`, `Show`, `Portal`, `Redirect`, `Lazy`, `ErrorBoundary` |
951
1073
  | **Behaviour wrappers** | `OnClick`, `OnMouse`, `OnKeyboard`, `OnFocus`, `OnIntersect`, `OnMount`, `Css`, `Link` — attach click / mouse / keyboard / focus / intersection / lifecycle listeners or raw class / style to ANY component without it needing a dedicated prop. `OnMount(child, { onMount, onUnmount })` is the DOM-ref escape hatch — `onMount(node)` fires once after attach so you can measure, focus, or hand the node to an imperative library. `Link(label_or_child, { to?, href?, external? })` wraps either a string or a component as a router-aware anchor. |
952
1074
  | **Escape hatches** | `HTMLTag`, `Styles` (last-resort raw HTML / CSS — see [language.html](https://asfand-dev.github.io/aktion/language.html#escape-hatches)) |
@@ -1074,9 +1196,11 @@ Themes are flat maps of CSS-valued strings, grouped by domain:
1074
1196
  | Semantic | `colorSuccess`, `colorWarning`, `colorDanger`, `colorInfo` |
1075
1197
  | Typography | `fontFamily`, `fontFamilyHeading`, `fontFamilyMono`, `fontSizeBase`, `fontSizeHeading`, `fontSizeTitle`, `fontWeightBody`, `fontWeightHeading`, `letterSpacingHeading`, `headingTextTransform` |
1076
1198
  | Shape | `radiusXs`, `radiusSm`, `radiusMd`, `radiusLg`, `radiusPill`, `radiusButton`, `radiusInput`, `borderWidth`, `shadowSm`, `shadowMd`, `shadowLg` |
1077
- | Spacing | `spacingXs`, `spacingS`, `spacingM`, `spacingL`, `spacingXl` |
1199
+ | Spacing | `spacingXs`, `spacingS`, `spacingM`, `spacingL`, `spacingXl`, `spacing2xl`, `spacing3xl` |
1200
+ | Gradients | `gradientBrand`, `gradientAccent`, `gradientWarm`, `gradientCool`, `gradientSuccess`, `gradientDanger` — referenced as `"gradient.brand"` from `sx`, `GradientText`, `fill` props |
1078
1201
  | Buttons | `buttonFontWeight`, `buttonTextTransform`, `buttonLetterSpacing`, `buttonPaddingY`, `buttonPaddingX` |
1079
- | Motion | `transitionDuration` |
1202
+ | Motion | `transitionDuration`, `motionFast`, `motionBase`, `motionSlow`, `motionEase` (optional — set via `$theme({ motion: {...} })`) |
1203
+ | Layers | `zBase`, `zRaised`, `zDropdown`, `zSticky`, `zBanner`, `zOverlay`, `zModal`, `zPopover`, `zToast`, `zTooltip` (optional — set via `$theme({ zIndex: {...} })`; consumed by `sx.zIndex` tokens) |
1080
1204
  | Charts | `chart1`–`chart6` |
1081
1205
 
1082
1206
  ### Custom token map from the host
@@ -1115,12 +1239,36 @@ $theme({
1115
1239
  $app(Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])]))
1116
1240
  ```
1117
1241
 
1118
- `$theme` expects the **structured** form — top-level groups `colors` /
1119
- `radius` / `font` (plus metadata keys `name` and `direction`). Removing
1120
- the `$theme(...)` line snaps the UI back to
1242
+ `$theme` expects the **structured** form — top-level token groups
1243
+ (`colors`, `radius`, `font`, `spacing`, `shadows`, `gradients`,
1244
+ `zIndex`, `motion`, `fonts`, `icons`) plus metadata keys `name` and
1245
+ `direction`. Removing the `$theme(...)` line snaps the UI back to
1121
1246
  the base theme. Unknown keys are ignored silently, so typos in an
1122
1247
  LLM-emitted token map can never break the page.
1123
1248
 
1249
+ **Full property list** (all optional; token values are strings — bare
1250
+ numbers are coerced):
1251
+
1252
+ | Key | Type | Notes |
1253
+ | ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1254
+ | `name` | `string` | Selects a built-in theme as the base palette (`"dark"`, `"neon"`, `"pastel"`, `"glass"`, `"brutalist"`, `"skyline"`); structured overrides layer on top. Unknown names are ignored. |
1255
+ | `direction` | `"ltr"` \| `"rtl"` | Reading direction. Metadata only — not applied as a token. |
1256
+ | `colors` | `{ [key]: string }` | CSS color strings. Keys: `bg`, `bgSubtle`, `surface`, `surfaceMuted`, `border`, `borderSubtle`, `text`, `textMuted`, `primary`, `primaryHover`, `primaryText`, `accent`, `accentHover`, `accentText`, `focusRing`, `success`, `warning`, `danger`, `info`. |
1257
+ | `radius` | `{ [key]: string }` | CSS length strings. Keys: `xs`, `sm`, `md`, `lg`, `pill`, `button`, `input`. |
1258
+ | `font` | `{ [key]: string }` | CSS strings. Keys: `family`, `familyHeading`, `familyMono`, `sizeBase`, `sizeSm`, `sizeLg`, `sizeHeading`, `sizeTitle`, `weightBody`, `weightHeading`. Also accepts `import` for web fonts (see `fonts`). |
1259
+ | `spacing` | `{ [key]: string }` | CSS length strings. Keys: `xs`, `s`, `m`, `l`, `xl`, `2xl`, `3xl`. |
1260
+ | `shadows` | `{ [key]: string }` | CSS shadow strings. Keys: `sm`, `md`, `lg`. |
1261
+ | `gradients` | `object` | Named gradients. Keys: `brand`, `accent`, `warm`, `cool`, `success`, `danger`. Values: color-stop arrays (`["#6366f1", "#ec4899"]`), `{ stops, angle? }`, or a safe gradient string. |
1262
+ | `zIndex` | `object` | Layer tokens (numbers OK). Keys: `base`, `raised`, `dropdown`, `sticky`, `banner`, `overlay`, `modal`, `popover`, `toast`, `tooltip`. |
1263
+ | `motion` | `{ [key]: string }` | Motion tokens. Keys: `fast`, `base`, `slow`, `ease`. |
1264
+ | `fonts` | `object` | Web-font loader: `{ import: ["Inter:400,700"] }` (Google Fonts shorthand). |
1265
+ | `icons` | `object` | Custom inline-SVG icons: `{ logo: "<path …/>" }` — usable anywhere a Font Awesome name works. |
1266
+
1267
+ Tokens outside these groups (line-height, letter-spacing, heading
1268
+ text-transform, border width, button styling, chart series, transition
1269
+ duration) are base-theme-only — set them from the host via
1270
+ `el.setTheme(...)` or CSS variables, not `$theme({...})`.
1271
+
1124
1272
  ### Host-page CSS variable override
1125
1273
 
1126
1274
  ```css
@@ -1205,7 +1353,7 @@ nav = Row([
1205
1353
  NavLink("Home", { to: "/", exact: true }),
1206
1354
  NavLink("Dashboard", { to: "/dashboard" }),
1207
1355
  NavLink("Users", { to: "/users" })
1208
- ], { gap: "s" })
1356
+ ], { gap: "sm" })
1209
1357
 
1210
1358
  $app(Stack([nav, pages]))
1211
1359
 
@@ -1221,6 +1369,24 @@ notFoundPage = Callout("Not found", { description: `We couldn't find ${route.pa
1221
1369
  - Route patterns support literal segments (`"/about"`), parameter
1222
1370
  segments (`"/users/:id"` → `params.id`), and trailing wildcards
1223
1371
  (`"/docs/*"` → `params._`).
1372
+ - **Nested layout routes** — an arm shaped `{ layout, routes }` matches as
1373
+ a path *prefix*: the shell stays mounted while the matched child binds to
1374
+ the `outlet` identifier inside the layout (params merge parent + child;
1375
+ layouts compose).
1376
+ - **Navigation guards** — `$util.onNavigate(({ to, from }) => …)`: return
1377
+ `false` to block, a path string to redirect (`"/login"`), anything else
1378
+ to allow. Enforced for in-app navigation, browser back/forward, and
1379
+ manual URL edits.
1380
+ - **Query-param state** — `$util.url.setQuery("sort", v)` /
1381
+ `.removeQuery("sort")` write the URL query in place (shareable filters /
1382
+ tabs); read back reactively via `$util.url.query` or `route.query`.
1383
+ - **Scroll restoration** — set `scroll-restoration="auto"` on
1384
+ `<aktion-app>` to restore per-path scroll on back/forward (`"top"`
1385
+ always jumps to top). **Route transitions** — wrap the outlet in
1386
+ `RouteView(pages, { routeKey: route.path, animation: "fade" })` to
1387
+ replay an entrance animation on navigation. **Prefetch** —
1388
+ `NavLink(..., { prefetch: () => $query({...}) })` warms a query cache on
1389
+ first hover/focus.
1224
1390
  - `NavLink(label, { to, variant?, exact?, icon? })` is a router-aware
1225
1391
  anchor that intercepts clicks and reflects `data-active="true"` for the
1226
1392
  current path.
@@ -1384,6 +1550,20 @@ import {
1384
1550
  the library + reserved words it surfaces the symbols declared in the
1385
1551
  current document — your own reactive atoms, components, and actions.
1386
1552
 
1553
+ ### Migration & DX tooling
1554
+
1555
+ The same entry exports the migration/DX suite:
1556
+
1557
+ | Export | What it does |
1558
+ | ------ | ------------ |
1559
+ | `htmlToAktion(html)` | Convert static HTML to an Aktion program — common tags map to components, `class` attributes run through `tailwindToSx` (mapped utilities become `sx`, leftovers stay under `className`), and `flex`/`flex-col` containers become `Row`/`Column`. |
1560
+ | `tailwindToSx(classString)` | Map Tailwind utilities to an `sx` object — spacing/color/typography/flex/grid/radius/shadow/sizing/position/z-index/overflow, with responsive prefixes (`md:p-8`) becoming `sx` breakpoint maps and state prefixes (`hover:bg-primary`) becoming `sx.states` entries. Unrecognised classes come back under `_unmapped`. |
1561
+ | `componentSchema(library)` | Stable, machine-readable JSON schema of every component (props/types/enums/flags) for editor autocomplete and release diffing. |
1562
+ | `buildGallery(library)` | Self-contained HTML component explorer ("Storybook page") generated from the schema. |
1563
+ | `suggestComponent(name, library)` | "Did you mean?" typo candidates by edit distance. |
1564
+ | `renderToString(program, opts)` / `renderToStaticMarkup` | SSR/SSG — render a program to `{ html, state }` under any DOM (browser or Node + happy-dom/jsdom); pair with `StateStore.hydrate`. From the main entry. |
1565
+ | `within(node)` / `axe(node)` | Testing helpers from `aktion-runtime/test` — scoped queries and a dependency-free a11y audit (`img-alt`, `svg-name`, `button-name`, `link-name`, `label` — with `aria-labelledby` resolution —, `duplicate-id`, `tabindex`). |
1566
+
1387
1567
  ---
1388
1568
 
1389
1569
  ## Build-time compiler & multi-file modules