aktion-runtime 0.5.9 → 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.
- package/README.md +196 -26
- package/dist/aktion.iife.js +877 -78
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +16394 -10312
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +877 -78
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/devtools.js +554 -20
- package/dist/devtools.js.map +1 -1
- package/dist/language.js +4883 -572
- package/dist/language.js.map +1 -1
- package/dist/plugin.cjs +2 -2
- package/dist/plugin.cjs.map +1 -1
- package/dist/plugin.js +2 -2
- package/dist/plugin.js.map +1 -1
- package/dist/system_prompt.txt +269 -20
- package/dist/system_prompt_chat.txt +3 -3
- package/dist/testing.js +15975 -7890
- package/dist/testing.js.map +1 -1
- package/dist/types/devtools/panel.d.ts +32 -0
- package/dist/types/devtools/styles.d.ts +1 -1
- package/dist/types/element.d.ts +26 -0
- package/dist/types/icons/index.d.ts +10 -0
- package/dist/types/library/components/_internal.d.ts +18 -0
- package/dist/types/library/components/a11y.d.ts +5 -0
- package/dist/types/library/components/canvas.d.ts +3 -0
- package/dist/types/library/components/extras.d.ts +15 -0
- package/dist/types/library/components/feedback.d.ts +1 -0
- package/dist/types/library/components/forms-shared.d.ts +55 -0
- package/dist/types/library/components/layout-motion.d.ts +14 -0
- package/dist/types/library/components/layout.d.ts +1 -0
- package/dist/types/library/components/marketing.d.ts +35 -0
- package/dist/types/library/components/new-components.d.ts +1 -0
- package/dist/types/library/components/scheduling.d.ts +2 -0
- package/dist/types/library/components/wave3.d.ts +6 -0
- package/dist/types/library/highlight.d.ts +21 -0
- package/dist/types/library/qr.d.ts +12 -0
- package/dist/types/library/responsive-style.d.ts +51 -0
- package/dist/types/library/sx.d.ts +51 -0
- package/dist/types/runtime/env.d.ts +33 -0
- package/dist/types/runtime/evaluator.d.ts +30 -0
- package/dist/types/runtime/http.d.ts +37 -1
- package/dist/types/runtime/index.d.ts +2 -0
- package/dist/types/runtime/namespaces-extra.d.ts +73 -0
- package/dist/types/runtime/realtime.d.ts +46 -0
- package/dist/types/runtime/router.d.ts +42 -4
- package/dist/types/runtime/ssr.d.ts +29 -0
- package/dist/types/runtime/util.d.ts +65 -0
- package/dist/types/testing/index.d.ts +35 -0
- package/dist/types/theme/fonts.d.ts +30 -0
- package/dist/types/theme/index.d.ts +28 -0
- package/dist/types/theme/styles.d.ts +1 -1
- package/dist/types/tooling/html-import.d.ts +19 -0
- package/dist/types/tooling/index.d.ts +3 -0
- package/dist/types/tooling/schema.d.ts +58 -0
- package/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 **
|
|
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,
|
|
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. **
|
|
142
|
-
|
|
143
|
-
|
|
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 (
|
|
520
|
-
|
|
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
|
-
|
|
527
|
-
|
|
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
|
|
533
|
-
|
|
534
|
-
|
|
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`,
|
|
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 **
|
|
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
|
|
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
|
|
1119
|
-
`radius
|
|
1120
|
-
|
|
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
|