aktion-runtime 0.5.9 → 0.5.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +216 -36
- package/dist/aktion.iife.js +920 -144
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +17025 -10815
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +920 -144
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/devtools.js +554 -20
- package/dist/devtools.js.map +1 -1
- package/dist/language.js +7042 -2455
- package/dist/language.js.map +1 -1
- package/dist/plugin.cjs +2 -2
- package/dist/plugin.cjs.map +1 -1
- package/dist/plugin.js +2 -2
- package/dist/plugin.js.map +1 -1
- package/dist/system_prompt.txt +292 -41
- package/dist/system_prompt_chat.txt +14 -14
- package/dist/testing.js +16223 -7977
- package/dist/testing.js.map +1 -1
- package/dist/types/devtools/panel.d.ts +32 -0
- package/dist/types/devtools/styles.d.ts +1 -1
- package/dist/types/element.d.ts +26 -0
- package/dist/types/icons/index.d.ts +10 -0
- package/dist/types/library/components/_internal.d.ts +18 -0
- package/dist/types/library/components/a11y.d.ts +5 -0
- package/dist/types/library/components/canvas.d.ts +3 -0
- package/dist/types/library/components/extras.d.ts +15 -0
- package/dist/types/library/components/feedback.d.ts +1 -0
- package/dist/types/library/components/forms-shared.d.ts +55 -0
- package/dist/types/library/components/layout-motion.d.ts +14 -0
- package/dist/types/library/components/layout.d.ts +1 -0
- package/dist/types/library/components/marketing.d.ts +35 -0
- package/dist/types/library/components/new-components.d.ts +1 -0
- package/dist/types/library/components/scheduling.d.ts +2 -0
- package/dist/types/library/components/wave3.d.ts +6 -0
- package/dist/types/library/highlight.d.ts +21 -0
- package/dist/types/library/qr.d.ts +12 -0
- package/dist/types/library/responsive-style.d.ts +51 -0
- package/dist/types/library/sx.d.ts +51 -0
- package/dist/types/library/types.d.ts +50 -0
- package/dist/types/library/utils.d.ts +28 -0
- package/dist/types/library/validate.d.ts +2 -2
- package/dist/types/runtime/env.d.ts +33 -0
- package/dist/types/runtime/evaluator.d.ts +38 -0
- package/dist/types/runtime/http.d.ts +37 -1
- package/dist/types/runtime/index.d.ts +2 -0
- package/dist/types/runtime/namespaces-extra.d.ts +73 -0
- package/dist/types/runtime/realtime.d.ts +46 -0
- package/dist/types/runtime/router.d.ts +42 -4
- package/dist/types/runtime/ssr.d.ts +29 -0
- package/dist/types/runtime/util.d.ts +65 -0
- package/dist/types/testing/index.d.ts +35 -0
- package/dist/types/theme/fonts.d.ts +30 -0
- package/dist/types/theme/index.d.ts +31 -0
- package/dist/types/theme/styles.d.ts +1 -1
- package/dist/types/tooling/html-import.d.ts +19 -0
- package/dist/types/tooling/index.d.ts +3 -0
- package/dist/types/tooling/schema.d.ts +58 -0
- package/dist/types/tooling/signature-help.d.ts +35 -0
- package/package.json +1 -1
package/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 |
|
|
@@ -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
|
|
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
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
`
|
|
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 (
|
|
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
|
|
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
|
-
|
|
527
|
-
|
|
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
|
|
533
|
-
|
|
534
|
-
|
|
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`,
|
|
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: "
|
|
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 **
|
|
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
|
|
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
|
|
1119
|
-
`radius
|
|
1120
|
-
|
|
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: "
|
|
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
|