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
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 |
@@ -515,23 +587,23 @@ $app(pages)
515
587
  `.status`, `.loading`, `.headers`, `.lastUpdated`, `.refetch()`,
516
588
  `.cancel()`, and a settable `.onDone` callback that fires each time the
517
589
  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
590
+ - `$query({ url, key?, ttl?, refetchInterval?, refetchOnFocus?, refetchOnReconnect? })` — a **cached, deduplicated** read built on
591
+ `$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.
592
+ - `$mutation({ url, method?, optimistic?, invalidates? })` — a **deferred** write that fires only when
524
593
  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 }) })`.
594
+ `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.
595
+ - `$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.
596
+ - `$sse({ url, event?, withCredentials?, bufferSize? })` — reactive **Server-Sent Events** stream with the same `.status`/`.connected`/`.last`/`.messages`/`.close()` surface (EventSource reconnects natively).
529
597
  - `pages = $router({ "/path": Component(), default: NotFound() })` —
530
598
  function-call router. The reserved `route` handle exposes the
531
599
  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.
600
+ `route.pattern`) and a `route.navigate("/path")` method. Supports
601
+ **nested layout routes** (`"/app": { layout: AppShell, routes: {...} }` —
602
+ the shell stays mounted while only the `outlet` swaps), **navigation guards**
603
+ (`$util.onNavigate(({ to, from }) => …)` — return `false` to block or a
604
+ path to redirect), **query-param state** (`$util.url.setQuery("tab","v")`),
605
+ **lazy routes** (`Lazy(() => import(…))`), and **scroll restoration**
606
+ (set `scroll-restoration="auto"` on `<aktion-app>`).
535
607
  - Two-way binding is implicit: pass a `$variable` (or a member chain
536
608
  rooted at one — `value: $form.email`) as an input prop and the
537
609
  runtime wires it both ways.
@@ -564,7 +636,23 @@ $app(pages)
564
636
  `$util.groupBy`, `$util.format`, `$util.formatDate`, `$util.plural`, `$util.range`,
565
637
  `$util.addDays`, `$util.pick`, `$util.omit`, `$util.merge`, `$util.cloneDeep`,
566
638
  `$util.chunk`, `$util.partition`, `$util.keyBy`, `$util.zip`, `$util.flatten`,
567
- `$util.count`, …). Never carry hidden state — safe to call anywhere.
639
+ `$util.count`, `$util.slugify`, `$util.truncate`, `$util.initials`, `$util.currency`,
640
+ `$util.bytes`, `$util.relativeTime`, `$util.uuid`, `$util.copy` (async — resolves
641
+ `true` only when the clipboard write succeeds), `$util.sleep(ms)`,
642
+ `$util.debounceFn`, `$util.throttleFn` (leading + trailing edge), …). Never
643
+ carry hidden state — safe to call anywhere.
644
+ Also exposes **reactive env getters** (`$util.scroll`, `$util.viewport`,
645
+ `$util.breakpoint`, `$util.media`, `$util.mouse`, `$util.url` — lazy listeners,
646
+ re-render on change; `$util.url.setQuery`/`.removeQuery` write query params),
647
+ **styling/validation sub-namespaces** (`$util.style.cx`,
648
+ `.gradient`, `.alpha`, `.clamp`, `.token`, `.toStyle`; `$util.rules.required()`,
649
+ `.email()`, `.min()`, `.pattern()`, `.custom()`, `.asyncCustom()` — awaited by
650
+ `$form` —, `.validate()`, `.validateAll()`), **computed helper**
651
+ (`$util.derived(fn)`), **side-effect hooks** (`$util.onError`, `$util.onNavigate`,
652
+ `$util.onRequest`, `$util.onResponse`, `$util.invalidate`), and **device/platform
653
+ helpers** (`$util.vibrate`, `.share`, `.readClipboard`, `.geolocate`, `.isOnline`,
654
+ `.deviceType`, `.worker(pureFn)`, `.registerServiceWorker`, `.webManifest`,
655
+ `.nativeShell`, `.isNativeApp`).
568
656
  - **Escape hatches** — `HTMLTag(tag, { attributes?, children? })` for
569
657
  raw HTML elements and `Styles(css)` for raw CSS injected into the
570
658
  shadow root. Use only when the standard component library cannot
@@ -870,6 +958,20 @@ only components that read it), and store fields support two-way binding
870
958
  component's local `$state` / `$name = value` for state one component owns.
871
959
  See the [Global state guide](https://asfand-dev.github.io/aktion/stores.html).
872
960
 
961
+ **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.
962
+
963
+ **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.
964
+
965
+ ```js
966
+ doc = $store({
967
+ persist: "my-doc", // survives reload
968
+ history: 25, // undo/redo up to 25 steps
969
+ title: "Untitled",
970
+ setTitle: (s, v) => { s.title = v }
971
+ })
972
+ // doc.undo() / doc.redo() / doc.canUndo / doc.canRedo
973
+ ```
974
+
873
975
  ### Component-scoped effects
874
976
 
875
977
  `$effect(() => { … }, [...deps])` blocks can live at the program top level
@@ -926,7 +1028,7 @@ deep authoring guide [`coding-gen-skill.md`](./coding-gen-skill.md).
926
1028
 
927
1029
  ## Component library
928
1030
 
929
- The bundle ships **170+ components** grouped by domain. Reach for **pattern composites**
1031
+ The bundle ships **271 components** grouped by domain. Reach for **pattern composites**
930
1032
  (`Hero`, `PageHeader`, `Stats`, `Toolbar`, `EmptyState`, `Timeline`,
931
1033
  `KanbanBoard`, `DescriptionList`, `PricingTable`, …) before hand-rolling
932
1034
  the equivalent with `Card` + `Stack` — they're tuned to produce dense,
@@ -934,7 +1036,7 @@ production-quality SaaS UI in a single line.
934
1036
 
935
1037
  | Group | Components |
936
1038
  | ------------------ | ---------- |
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` |
1039
+ | **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
1040
  | **Content** | `Text`, `Image`, `Icon`, `Badge`, `BadgeList`, `Callout`, `Quote`, `CodeBlock`, `Skeleton`, `Spinner`, `Markdown`, `Kbd` |
939
1041
  | **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
1042
  | **Data** | `Table`, `Col`, `DataGrid`, `List`, `ListItem`, `StatCard`, `Stats`, `Sparkline`, `Tile`, `Progress`, `ProgressRing`, `Pagination`, `Tree`, `TreeNode`, `CalendarView`, `ComparisonTable`, `InfiniteList` |
@@ -947,6 +1049,16 @@ production-quality SaaS UI in a single line.
947
1049
  | **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
1050
  | **App shell** | `AppShell`, `Sidebar`, `SidebarSection`, `SidebarItem` (supports `to` for router navigation), `SplitView` |
949
1051
  | **Advanced UI** | `IconButton`, `CommandPalette`, `FilterChips`, `FieldRepeater`, `VirtualList`, `QueryBuilder`, `DiffViewer`, `JsonTree`, `Gantt`, `Truncate`, `InlineEdit`, `NotificationBell` |
1052
+ | **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` |
1053
+ | **E-commerce** | `ProductCard`, `PriceTag`, `QuantityStepper`, `VariantSelector`, `OrderSummary`, `Cart` |
1054
+ | **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` |
1055
+ | **Overlays** | `Sheet`, `BottomSheet`, `ConfirmDialog` — all with Escape-to-close, a Tab focus trap, and focus restore |
1056
+ | **Content & docs** | `TableOfContents`, `ReadingProgress`, `ScrollSpy`, `AuthorByline`, `ShareButtons`, `RelativeTime`, `CopyButton`, `KbdShortcut`, `QRCode`, `Svg` (sanitised inline SVG) |
1057
+ | **Realtime & social** | `TypingIndicator`, `PresenceAvatars`, `ReactionPicker`, `LiveCursor`, `TabBar` (mobile bottom nav) |
1058
+ | **Scheduling** | `Calendar` (month grid with arrow-key navigation, event chips/dots), `CountdownTimer` |
1059
+ | **Canvas** | `DrawingCanvas`, `SignaturePad` |
1060
+ | **Accessibility** | `VisuallyHidden`, `SkipLink`, `LiveRegion`, `FocusTrap` |
1061
+ | **Utility** | `SegmentedControl`, `FloatingActionButton`, `SpeedDial`, `BackToTop`, `VirtualGrid` (windowed 2-D grid) |
950
1062
  | **Helpers** | `Async`, `Show`, `Portal`, `Redirect`, `Lazy`, `ErrorBoundary` |
951
1063
  | **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
1064
  | **Escape hatches** | `HTMLTag`, `Styles` (last-resort raw HTML / CSS — see [language.html](https://asfand-dev.github.io/aktion/language.html#escape-hatches)) |
@@ -1074,9 +1186,11 @@ Themes are flat maps of CSS-valued strings, grouped by domain:
1074
1186
  | Semantic | `colorSuccess`, `colorWarning`, `colorDanger`, `colorInfo` |
1075
1187
  | Typography | `fontFamily`, `fontFamilyHeading`, `fontFamilyMono`, `fontSizeBase`, `fontSizeHeading`, `fontSizeTitle`, `fontWeightBody`, `fontWeightHeading`, `letterSpacingHeading`, `headingTextTransform` |
1076
1188
  | Shape | `radiusXs`, `radiusSm`, `radiusMd`, `radiusLg`, `radiusPill`, `radiusButton`, `radiusInput`, `borderWidth`, `shadowSm`, `shadowMd`, `shadowLg` |
1077
- | Spacing | `spacingXs`, `spacingS`, `spacingM`, `spacingL`, `spacingXl` |
1189
+ | Spacing | `spacingXs`, `spacingS`, `spacingM`, `spacingL`, `spacingXl`, `spacing2xl`, `spacing3xl` |
1190
+ | Gradients | `gradientBrand`, `gradientAccent`, `gradientWarm`, `gradientCool`, `gradientSuccess`, `gradientDanger` — referenced as `"gradient.brand"` from `sx`, `GradientText`, `fill` props |
1078
1191
  | Buttons | `buttonFontWeight`, `buttonTextTransform`, `buttonLetterSpacing`, `buttonPaddingY`, `buttonPaddingX` |
1079
- | Motion | `transitionDuration` |
1192
+ | Motion | `transitionDuration`, `motionFast`, `motionBase`, `motionSlow`, `motionEase` (optional — set via `$theme({ motion: {...} })`) |
1193
+ | Layers | `zBase`, `zRaised`, `zDropdown`, `zSticky`, `zBanner`, `zOverlay`, `zModal`, `zPopover`, `zToast`, `zTooltip` (optional — set via `$theme({ zIndex: {...} })`; consumed by `sx.zIndex` tokens) |
1080
1194
  | Charts | `chart1`–`chart6` |
1081
1195
 
1082
1196
  ### Custom token map from the host
@@ -1115,12 +1229,36 @@ $theme({
1115
1229
  $app(Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])]))
1116
1230
  ```
1117
1231
 
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
1232
+ `$theme` expects the **structured** form — top-level token groups
1233
+ (`colors`, `radius`, `font`, `spacing`, `shadows`, `gradients`,
1234
+ `zIndex`, `motion`, `fonts`, `icons`) plus metadata keys `name` and
1235
+ `direction`. Removing the `$theme(...)` line snaps the UI back to
1121
1236
  the base theme. Unknown keys are ignored silently, so typos in an
1122
1237
  LLM-emitted token map can never break the page.
1123
1238
 
1239
+ **Full property list** (all optional; token values are strings — bare
1240
+ numbers are coerced):
1241
+
1242
+ | Key | Type | Notes |
1243
+ | ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1244
+ | `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. |
1245
+ | `direction` | `"ltr"` \| `"rtl"` | Reading direction. Metadata only — not applied as a token. |
1246
+ | `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`. |
1247
+ | `radius` | `{ [key]: string }` | CSS length strings. Keys: `xs`, `sm`, `md`, `lg`, `pill`, `button`, `input`. |
1248
+ | `font` | `{ [key]: string }` | CSS strings. Keys: `family`, `familyHeading`, `familyMono`, `sizeBase`, `sizeSm`, `sizeLg`, `sizeHeading`, `sizeTitle`, `weightBody`, `weightHeading`. Also accepts `import` for web fonts (see `fonts`). |
1249
+ | `spacing` | `{ [key]: string }` | CSS length strings. Keys: `xs`, `s`, `m`, `l`, `xl`, `2xl`, `3xl`. |
1250
+ | `shadows` | `{ [key]: string }` | CSS shadow strings. Keys: `sm`, `md`, `lg`. |
1251
+ | `gradients` | `object` | Named gradients. Keys: `brand`, `accent`, `warm`, `cool`, `success`, `danger`. Values: color-stop arrays (`["#6366f1", "#ec4899"]`), `{ stops, angle? }`, or a safe gradient string. |
1252
+ | `zIndex` | `object` | Layer tokens (numbers OK). Keys: `base`, `raised`, `dropdown`, `sticky`, `banner`, `overlay`, `modal`, `popover`, `toast`, `tooltip`. |
1253
+ | `motion` | `{ [key]: string }` | Motion tokens. Keys: `fast`, `base`, `slow`, `ease`. |
1254
+ | `fonts` | `object` | Web-font loader: `{ import: ["Inter:400,700"] }` (Google Fonts shorthand). |
1255
+ | `icons` | `object` | Custom inline-SVG icons: `{ logo: "<path …/>" }` — usable anywhere a Font Awesome name works. |
1256
+
1257
+ Tokens outside these groups (line-height, letter-spacing, heading
1258
+ text-transform, border width, button styling, chart series, transition
1259
+ duration) are base-theme-only — set them from the host via
1260
+ `el.setTheme(...)` or CSS variables, not `$theme({...})`.
1261
+
1124
1262
  ### Host-page CSS variable override
1125
1263
 
1126
1264
  ```css
@@ -1221,6 +1359,24 @@ notFoundPage = Callout("Not found", { description: `We couldn't find ${route.pa
1221
1359
  - Route patterns support literal segments (`"/about"`), parameter
1222
1360
  segments (`"/users/:id"` → `params.id`), and trailing wildcards
1223
1361
  (`"/docs/*"` → `params._`).
1362
+ - **Nested layout routes** — an arm shaped `{ layout, routes }` matches as
1363
+ a path *prefix*: the shell stays mounted while the matched child binds to
1364
+ the `outlet` identifier inside the layout (params merge parent + child;
1365
+ layouts compose).
1366
+ - **Navigation guards** — `$util.onNavigate(({ to, from }) => …)`: return
1367
+ `false` to block, a path string to redirect (`"/login"`), anything else
1368
+ to allow. Enforced for in-app navigation, browser back/forward, and
1369
+ manual URL edits.
1370
+ - **Query-param state** — `$util.url.setQuery("sort", v)` /
1371
+ `.removeQuery("sort")` write the URL query in place (shareable filters /
1372
+ tabs); read back reactively via `$util.url.query` or `route.query`.
1373
+ - **Scroll restoration** — set `scroll-restoration="auto"` on
1374
+ `<aktion-app>` to restore per-path scroll on back/forward (`"top"`
1375
+ always jumps to top). **Route transitions** — wrap the outlet in
1376
+ `RouteView(pages, { routeKey: route.path, animation: "fade" })` to
1377
+ replay an entrance animation on navigation. **Prefetch** —
1378
+ `NavLink(..., { prefetch: () => $query({...}) })` warms a query cache on
1379
+ first hover/focus.
1224
1380
  - `NavLink(label, { to, variant?, exact?, icon? })` is a router-aware
1225
1381
  anchor that intercepts clicks and reflects `data-active="true"` for the
1226
1382
  current path.
@@ -1384,6 +1540,20 @@ import {
1384
1540
  the library + reserved words it surfaces the symbols declared in the
1385
1541
  current document — your own reactive atoms, components, and actions.
1386
1542
 
1543
+ ### Migration & DX tooling
1544
+
1545
+ The same entry exports the migration/DX suite:
1546
+
1547
+ | Export | What it does |
1548
+ | ------ | ------------ |
1549
+ | `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`. |
1550
+ | `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`. |
1551
+ | `componentSchema(library)` | Stable, machine-readable JSON schema of every component (props/types/enums/flags) for editor autocomplete and release diffing. |
1552
+ | `buildGallery(library)` | Self-contained HTML component explorer ("Storybook page") generated from the schema. |
1553
+ | `suggestComponent(name, library)` | "Did you mean?" typo candidates by edit distance. |
1554
+ | `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. |
1555
+ | `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`). |
1556
+
1387
1557
  ---
1388
1558
 
1389
1559
  ## Build-time compiler & multi-file modules