aktion-runtime 0.5.2 → 0.5.4
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 +773 -376
- package/dist/aktion.iife.js +798 -790
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +10238 -8024
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +798 -790
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/node/compile-BUw0GAvN.cjs +491 -0
- package/dist/node/compile-BUw0GAvN.cjs.map +1 -0
- package/dist/node/compile-DxttTzo8.js +492 -0
- package/dist/node/compile-DxttTzo8.js.map +1 -0
- package/dist/node/compiler.cjs +11 -0
- package/dist/node/compiler.cjs.map +1 -0
- package/dist/node/compiler.js +11 -0
- package/dist/node/compiler.js.map +1 -0
- package/dist/node/index-8OvnOYPI.js +14070 -0
- package/dist/node/index-8OvnOYPI.js.map +1 -0
- package/dist/node/index-DBgA3bHQ.cjs +14069 -0
- package/dist/node/index-DBgA3bHQ.cjs.map +1 -0
- package/dist/node/language.cjs +1244 -0
- package/dist/node/language.cjs.map +1 -0
- package/dist/node/language.js +1244 -0
- package/dist/node/language.js.map +1 -0
- package/dist/node/vite.cjs +65 -0
- package/dist/node/vite.cjs.map +1 -0
- package/dist/node/vite.js +65 -0
- package/dist/node/vite.js.map +1 -0
- package/dist/system_prompt.txt +595 -829
- package/dist/system_prompt_chat.txt +98 -263
- package/dist/types/aktion-modules.d.ts +22 -0
- package/dist/types/compiler/compile.d.ts +54 -0
- package/dist/types/compiler/emit.d.ts +15 -0
- package/dist/types/compiler/index.d.ts +14 -0
- package/dist/types/compiler/linker.d.ts +27 -0
- package/dist/types/compiler/runtime.d.ts +63 -0
- package/dist/types/compiler/sourcemap.d.ts +40 -0
- package/dist/types/element.d.ts +82 -26
- package/dist/types/index.d.ts +1 -0
- package/dist/types/language/grammar.d.ts +25 -9
- package/dist/types/language/index.d.ts +8 -6
- package/dist/types/language-api.d.ts +15 -0
- package/dist/types/library/components/content.d.ts +0 -1
- package/dist/types/library/components/escape-hatch.d.ts +3 -0
- package/dist/types/library/components/layout.d.ts +3 -0
- package/dist/types/library/components/wrappers.d.ts +12 -0
- package/dist/types/library/utils.d.ts +42 -0
- package/dist/types/parser/frontier.d.ts +3 -3
- package/dist/types/parser/lexer.d.ts +7 -17
- package/dist/types/parser/types.d.ts +276 -113
- package/dist/types/plugin/index.d.ts +10 -0
- package/dist/types/plugin/vite.d.ts +21 -0
- package/dist/types/prompt/generator.d.ts +0 -11
- package/dist/types/renderer/renderer.d.ts +53 -4
- package/dist/types/runtime/builtins.d.ts +10 -6
- package/dist/types/runtime/effects.d.ts +3 -28
- package/dist/types/runtime/evaluator.d.ts +333 -24
- package/dist/types/runtime/http.d.ts +35 -30
- package/dist/types/runtime/i18n.d.ts +23 -32
- package/dist/types/runtime/router.d.ts +5 -6
- package/dist/types/runtime/state.d.ts +77 -33
- package/dist/types/runtime/util.d.ts +88 -0
- package/dist/types/theme/styles.d.ts +1 -1
- package/dist/types/tooling/delta.d.ts +1 -1
- package/dist/types/tooling/inspector.d.ts +1 -1
- package/package.json +37 -6
- package/dist/types/language/builtins.d.ts +0 -33
package/README.md
CHANGED
|
@@ -5,16 +5,16 @@
|
|
|
5
5
|
[](#contributing)
|
|
6
6
|
|
|
7
7
|
A framework-agnostic web component that renders LLM-generated UI from
|
|
8
|
-
**Aktion** — a
|
|
9
|
-
assistants. Drop one `<script>` tag and one
|
|
10
|
-
any HTML page and you have a streaming, interactive
|
|
11
|
-
response.
|
|
8
|
+
**Aktion** — a reactive language whose surface syntax is a strict subset of
|
|
9
|
+
JavaScript, designed for chat assistants. Drop one `<script>` tag and one
|
|
10
|
+
`<aktion-app>` tag into any HTML page and you have a streaming, interactive
|
|
11
|
+
renderer for an LLM's response.
|
|
12
12
|
|
|
13
13
|
```html
|
|
14
14
|
<script type="module" src="https://asfand-dev.github.io/aktion/dist/aktion.js"></script>
|
|
15
15
|
<aktion-app theme="light">
|
|
16
|
-
|
|
17
|
-
CardHeader("Hello", subtitle: "Generative UI in plain HTML"),
|
|
16
|
+
aktion = Card([
|
|
17
|
+
CardHeader("Hello", { subtitle: "Generative UI in plain HTML" }),
|
|
18
18
|
Markdown("This card was streamed in as **plain text**.")
|
|
19
19
|
])
|
|
20
20
|
</aktion-app>
|
|
@@ -42,11 +42,11 @@ HTML, or no framework at all.
|
|
|
42
42
|
- [Themes](#themes)
|
|
43
43
|
- [Icons](#icons)
|
|
44
44
|
- [Routing](#routing)
|
|
45
|
-
- [
|
|
46
|
-
- [
|
|
47
|
-
- [Internationalization (`i18n`)](#internationalization)
|
|
45
|
+
- [Built-in globals (`$storage`, `$console`)](#built-in-globals)
|
|
46
|
+
- [Internationalization (`$i18n`)](#internationalization)
|
|
48
47
|
- [System prompt generator](#system-prompt-generator)
|
|
49
48
|
- [Tooling](#tooling)
|
|
49
|
+
- [Build-time compiler & multi-file modules](#build-time-compiler--multi-file-modules)
|
|
50
50
|
- [Documentation site](#documentation-site)
|
|
51
51
|
- [Live examples](#live-examples)
|
|
52
52
|
- [Project layout](#project-layout)
|
|
@@ -62,61 +62,85 @@ HTML, or no framework at all.
|
|
|
62
62
|
Everything you need at runtime ships in a single bundle:
|
|
63
63
|
|
|
64
64
|
- **A streaming-first parser.** Line-oriented, error-tolerant. Each
|
|
65
|
-
statement commits to the DOM as soon as it arrives.
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
`
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
65
|
+
statement commits to the DOM as soon as it arrives. The surface syntax
|
|
66
|
+
is a **strict subset of JavaScript** — `function` declarations,
|
|
67
|
+
`for...of`, `if/else`, `switch/case`, template literals with
|
|
68
|
+
`${expression}` interpolation, arrow functions, default parameters,
|
|
69
|
+
destructuring, spread, optional chaining (`a?.b`), nullish coalescing
|
|
70
|
+
(`a ?? b`), and object-literal named arguments. Every Aktion program
|
|
71
|
+
is valid JavaScript.
|
|
72
|
+
- **One reactive atom kind.** Declare any reactive state with
|
|
73
|
+
`$name = value` and read or write it with `$name`. The `$` prefix is
|
|
74
|
+
the only thing that makes a binding reactive — `let` / `const` /
|
|
75
|
+
`var` keywords are optional and have no effect on reactivity. The
|
|
76
|
+
runtime tracks dependencies automatically — and at **path
|
|
77
|
+
granularity**: reading `$user.name` subscribes to `user.name` alone,
|
|
78
|
+
so a write to `$user.role` never re-renders, recomputes, or re-fires
|
|
79
|
+
an effect that only read `name` (see *Fine-grained reactivity* below).
|
|
80
|
+
Automatic two-way binding
|
|
81
|
+
via direct state refs (and member chains rooted at one —
|
|
82
|
+
`value: $form.email`), and a **`$util` runtime namespace** of pure
|
|
83
|
+
helpers (`$util.filter`, `$util.sort`, `$util.find`, `$util.groupBy`,
|
|
84
|
+
`$util.format`, `$util.formatDate`, `$util.plural`, `$util.case`,
|
|
85
|
+
`$util.range`, `$util.pick`, …) callable from Aktion expressions and
|
|
86
|
+
ordinary JavaScript alike.
|
|
87
|
+
- **One component-call shape.** Every call follows the trailing-object
|
|
88
|
+
rule — `Component(positionalArg, { prop: value, … })`. At most one
|
|
89
|
+
positional argument; every other argument goes in a trailing
|
|
90
|
+
`{ }` object literal.
|
|
91
|
+
- **One HTTP primitive.** `$http({ url, method, headers, body, query, ... })`
|
|
92
|
+
is the only network call. Each call is self-contained (pass a full
|
|
93
|
+
absolute `url`; `GET` is the default; no host-wide defaults). It returns
|
|
94
|
+
a reactive resource bag exposing
|
|
78
95
|
`data | error | status | loading | headers | lastUpdated`, plus the
|
|
79
|
-
callables `refetch()` and `cancel()`. Re-
|
|
80
|
-
|
|
81
|
-
-
|
|
82
|
-
(localStorage by default),
|
|
83
|
-
|
|
84
|
-
|
|
96
|
+
callables `refetch()` and `cancel()`. Re-run a request via `refetch()`
|
|
97
|
+
or by wrapping it in an `$effect(..., [$dep])`.
|
|
98
|
+
- **`$storage` and `$console` globals.** Always in scope, no import,
|
|
99
|
+
lowercase. `$storage.set/get` (localStorage by default),
|
|
100
|
+
`$storage.session.*`, `$storage.cookies.*` with object-literal options,
|
|
101
|
+
and `console.log/error/warn/info/debug`.
|
|
85
102
|
- **A React-like DOM reconciler.** Diffs each re-render against the live
|
|
86
103
|
DOM. Text-input value, selection, IME state, scroll positions,
|
|
87
104
|
`<details>.open`, and stateful primitives like `Tabs` are all preserved
|
|
88
105
|
across renders. Components that need to hold UI state get a
|
|
89
106
|
`helpers.useInstanceState(...)` slot keyed by their position in the tree.
|
|
90
|
-
- **A rich component library** of **
|
|
107
|
+
- **A rich component library** of **170+ components** spanning layout,
|
|
91
108
|
forms, charts, data, feedback, navigation, patterns, app-shell composites,
|
|
92
109
|
editors, advanced UI, and standard helpers. See [Component library](#component-library).
|
|
93
|
-
- **Declarative side effects.**
|
|
94
|
-
work — anonymous blocks where the dependency list mixes
|
|
95
|
-
(`$atom`), lifecycle triggers (`
|
|
96
|
-
and rate-limit modifiers (`debounce(N)`,
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
`
|
|
106
|
-
|
|
107
|
-
|
|
110
|
+
- **Declarative side effects.** `$effect(() => { body }, [...deps])` for
|
|
111
|
+
background work — anonymous blocks where the dependency list mixes
|
|
112
|
+
state triggers (`$atom`), lifecycle triggers (`"mount"`, `"unmount"`,
|
|
113
|
+
`"every(N)"`), and rate-limit modifiers (`"debounce(N)"`,
|
|
114
|
+
`"throttle(N)"`). `$effect(() => { … })` with no dependency array is
|
|
115
|
+
equivalent to `$effect(() => { … }, ["mount"])`. Declare an effect
|
|
116
|
+
**at the top level** for program-wide work, or **inside a component
|
|
117
|
+
function body** to scope it to a single instance — timers, watched
|
|
118
|
+
atoms, and `cleanup(fn)` registrations tear down when the component
|
|
119
|
+
leaves the tree. `function name(args) { … }` (camelCase) declares an
|
|
120
|
+
action — click-driven mutations that may optionally `return` a value.
|
|
121
|
+
- **Outbound events.** `$emit("name", { detail })` dispatches a
|
|
122
|
+
`CustomEvent` on the host element from inside any action / effect /
|
|
123
|
+
lambda body. The host listens with
|
|
124
|
+
`el.addEventListener("name", …)`.
|
|
125
|
+
- **A built-in router.**
|
|
126
|
+
`pages = $router({ "/path": Component(), "/users/:id": UserPage({ id: params.id }), default: NotFound() })`
|
|
127
|
+
plus `NavLink(label, { to })` and a reserved `route` handle that
|
|
128
|
+
exposes `route.path`, `route.params`, `route.query`, `route.pattern`,
|
|
129
|
+
and `route.navigate("/path")`. Hash-based, framework-agnostic, always
|
|
130
|
+
wired up.
|
|
108
131
|
- **Seven built-in themes** (`light`, `dark`, `neon`, `pastel`, `glass`,
|
|
109
132
|
`brutalist`, `skyline`) plus full custom-token support via CSS custom
|
|
110
133
|
properties. **50+ design tokens** organised into `colors`, `radius`,
|
|
111
|
-
`font`, `motion`, and `elevation` groups. Brand the UI from inside
|
|
112
|
-
script with `theme =
|
|
113
|
-
-
|
|
114
|
-
a global `t("key", vars?)` builtin and a `Locale()` helper that feeds
|
|
115
|
-
the active locale into `@Format` / `@FormatDate`.
|
|
134
|
+
`font`, `motion`, and `elevation` groups. Brand the UI from inside
|
|
135
|
+
the script with `theme = $theme({...})`.
|
|
136
|
+
- **`$i18n` factory.** `const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({ defaultLanguage, currentLanguage, translations })` builds a translation bundle keyed by language, with `{name}` placeholder interpolation.
|
|
116
137
|
- **Font Awesome 6.7.2** auto-loaded — every `icon` prop accepts a Free
|
|
117
|
-
Font Awesome name (no `fa-` prefix). Use `Icon(name, variant?, size?)`
|
|
138
|
+
Font Awesome name (no `fa-` prefix). Use `Icon(name, { variant?, size? })`
|
|
118
139
|
for standalone glyphs. Variant prefixes supported: `"regular:star"`,
|
|
119
140
|
`"brands:github"`.
|
|
141
|
+
- **Markup escape hatches.** `HTMLTag(tag, { attributes?, children? })`
|
|
142
|
+
and `Styles(css)` are the last-resort raw-HTML / raw-CSS injectors
|
|
143
|
+
when no standard component captures the design.
|
|
120
144
|
- **A system prompt generator.** Emits a clean, ordered prompt teaching
|
|
121
145
|
the LLM exactly which components, builtins, and tools are available.
|
|
122
146
|
Two flavours ship: `system_prompt.txt` (full — every feature) and
|
|
@@ -188,19 +212,19 @@ Three equivalent ways:
|
|
|
188
212
|
|
|
189
213
|
```html
|
|
190
214
|
<!-- as an attribute -->
|
|
191
|
-
<aktion-app response='
|
|
215
|
+
<aktion-app response='aktion = Card([CardHeader("Hi")])'></aktion-app>
|
|
192
216
|
|
|
193
217
|
<!-- as inner text (rendered on connect) -->
|
|
194
218
|
<aktion-app>
|
|
195
|
-
|
|
219
|
+
aktion = Card([CardHeader("Hi")])
|
|
196
220
|
</aktion-app>
|
|
197
221
|
|
|
198
222
|
<!-- as a property/method -->
|
|
199
223
|
<script>
|
|
200
224
|
const el = document.querySelector("aktion-app");
|
|
201
225
|
el.setResponse(`
|
|
202
|
-
|
|
203
|
-
greeting = Card([CardHeader("Hello", subtitle: "Generative UI in plain HTML")])
|
|
226
|
+
aktion = Column([greeting])
|
|
227
|
+
greeting = Card([CardHeader("Hello", { subtitle: "Generative UI in plain HTML" })])
|
|
204
228
|
`);
|
|
205
229
|
</script>
|
|
206
230
|
```
|
|
@@ -242,24 +266,15 @@ const prompt = el.getSystemPrompt({
|
|
|
242
266
|
mode: "full", // or "chat" for the compact read-only prompt
|
|
243
267
|
preamble: "You are an analytics assistant.",
|
|
244
268
|
additionalRules: ["Always end with a FollowUpBlock of 2 prompts."],
|
|
245
|
-
tools: [{ name: "list_orders", description: "Return recent orders.", argsExample: { limit: 10 } }],
|
|
246
269
|
});
|
|
247
270
|
```
|
|
248
271
|
|
|
249
|
-
|
|
272
|
+
> Network calls are issued by the LLM-authored code itself via the
|
|
273
|
+
> `$http({ url, method, body, ... })` primitive. The host is not involved.
|
|
274
|
+
> Install `el.registerHttpInterceptors(...)` if you need to attach auth
|
|
275
|
+
> headers, retry on 401, or log every request.
|
|
250
276
|
|
|
251
|
-
|
|
252
|
-
`ctx.tools.<name>(args)`:
|
|
253
|
-
|
|
254
|
-
```js
|
|
255
|
-
el.setTools({
|
|
256
|
-
list_orders: async ({ limit }) => fetch(`/api/orders?limit=${limit}`).then(r => r.json()),
|
|
257
|
-
update_order: async ({ id, status }) =>
|
|
258
|
-
fetch(`/api/orders/${id}`, { method: "PATCH", body: JSON.stringify({ status }) }).then(r => r.json()),
|
|
259
|
-
});
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
### 7. (Optional) Listen for assistant messages
|
|
277
|
+
### 6. (Optional) Listen for assistant messages
|
|
263
278
|
|
|
264
279
|
Wire LLM-driven follow-ups back into your chat loop:
|
|
265
280
|
|
|
@@ -284,9 +299,9 @@ All members live on the `<aktion-app>` element.
|
|
|
284
299
|
| `response` | Aktion text | Sets the program declaratively. Re-renders whenever the attribute changes. |
|
|
285
300
|
| `showerrors` | `true` / unset | If present and `true`, displays parse errors in the rendered UI. Defaults to off. |
|
|
286
301
|
|
|
287
|
-
Routing and
|
|
288
|
-
|
|
289
|
-
|
|
302
|
+
Routing and JavaScript execution inside `effect` / action bodies are
|
|
303
|
+
always available — no host attribute, no allow-list. To omit those
|
|
304
|
+
surfaces from the *generated prompt*, build it via
|
|
290
305
|
`getSystemPrompt({ mode: "chat" })`.
|
|
291
306
|
|
|
292
307
|
### Properties
|
|
@@ -306,129 +321,264 @@ To omit those surfaces from the *generated prompt*, build it via
|
|
|
306
321
|
| `appendChunk(chunk)` | Append a streaming chunk and re-render. |
|
|
307
322
|
| `clear()` | Reset state, queries, and the rendered output. |
|
|
308
323
|
| `setTheme(name \| tokens)` | Apply a built-in theme by name or a partial token map. |
|
|
309
|
-
| `setTools(tools)` | Register host async tools exposed to `js{}` blocks as `ctx.tools.<name>(args)`. Replaces previously-registered tools. |
|
|
310
324
|
| `registerComponents(specs, root?)` | Extend the built-in library with your own components. |
|
|
311
|
-
| `getSystemPrompt(options?)` | Build a system prompt that matches the current library
|
|
325
|
+
| `getSystemPrompt(options?)` | Build a system prompt that matches the current library. Pass `{ mode: "chat" }` for the compact variant. |
|
|
312
326
|
| `navigate(path)` | Programmatically navigate. Updates `window.location.hash`. |
|
|
313
|
-
| `registerHttpInterceptors({ onRequest?, onResponse?, onError? })` | Install interceptors for the
|
|
327
|
+
| `registerHttpInterceptors({ onRequest?, onResponse?, onError? })` | Install interceptors for the `$http({...})` layer. `onResponse` receives a `retry()` one-shot for e.g. 401 refresh flows. |
|
|
314
328
|
| `serializeState()` | Return every reactive atom as a plain JSON-friendly object (for SSR / resumption). |
|
|
315
329
|
| `hydrateState(snapshot)` | Apply a snapshot to the live store and schedule a re-render. Atoms not in the snapshot are untouched. |
|
|
316
330
|
| `loadSnapshot({ programText, state })` | Atomic program + state load. The next render plans the program with the hydrated state already in place. |
|
|
317
331
|
| `applyDelta(ops)` | Apply a structured delta (`patch` / `replace` / `append` / `new` / `delete`). User `$state` is preserved across the diff. |
|
|
332
|
+
| `mountCompiled(compiled, state?)` | Mount a build-time-compiled program (from the [Vite/Rollup plugin](#build-time-compiler--multi-file-modules) or `compile()`), skipping the runtime parser. Optional `state` seeds reactive values (SSR / HMR). |
|
|
318
333
|
|
|
319
334
|
### Events
|
|
320
335
|
|
|
321
336
|
| Event | Detail | When it fires |
|
|
322
337
|
| -------------------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
323
|
-
| `assistant-message` | `{ message: string }` | When an action or lambda
|
|
338
|
+
| `assistant-message` | `{ message: string }` | When an action or lambda calls `$emit("assistant-message", { message: "..." })`. |
|
|
324
339
|
| `error` | `{ errors: ParseError[] }` | After each render whose source had parse errors. |
|
|
325
340
|
| `route-change` | `{ path, previousPath, source }` | When the current hash path changes. `source` is `"init" \| "hashchange" \| "navigate" \| "external"`. |
|
|
326
|
-
| `<custom-name>` | User-defined `{ ... }` | When script
|
|
341
|
+
| `<custom-name>` | User-defined `{ ... }` | When script calls `$emit("name", { ... })` inside an action / effect body. |
|
|
327
342
|
|
|
328
343
|
The `error` event always fires regardless of `showerrors`, so host apps
|
|
329
344
|
can log or report errors even when the in-page banner is suppressed.
|
|
330
345
|
|
|
346
|
+
### Runtime safety limits
|
|
347
|
+
|
|
348
|
+
Every program is evaluated under a per-render **runtime budget** that
|
|
349
|
+
bounds three independent dimensions so a partial / accidentally
|
|
350
|
+
recursive program (typed live in the playground, mid-stream LLM token,
|
|
351
|
+
…) can't freeze the browser:
|
|
352
|
+
|
|
353
|
+
| Dimension | Default | Triggers on |
|
|
354
|
+
| ------------------- | ------------ | -------------------------------------------------------- |
|
|
355
|
+
| `componentDepth` | 150 levels | `function Foo() { return Foo() }` and other recursive trees |
|
|
356
|
+
| `iterations` | 250 000 / render | unbounded `for`/`while` loops inside function bodies |
|
|
357
|
+
| `arrayLength` | 100 000 entries | `$util.range(0, 1e9)`, `$util.repeat(value, 1e9)` |
|
|
358
|
+
|
|
359
|
+
When a limit trips, the runtime aborts the render, emits an `error`
|
|
360
|
+
event whose detail is shaped like a parse error (`{ line: 0, column:
|
|
361
|
+
0, message }`), and leaves the previous tick's DOM intact so the user
|
|
362
|
+
still sees something useful. The defaults comfortably fit any
|
|
363
|
+
realistic app; tighten or relax them by constructing a custom budget
|
|
364
|
+
via `createRuntimeBudget({ … })` and passing it through `createContext`
|
|
365
|
+
(or pass `null` to disable enforcement entirely in trusted offline
|
|
366
|
+
pipelines).
|
|
367
|
+
|
|
331
368
|
---
|
|
332
369
|
|
|
333
370
|
## Aktion — the language
|
|
334
371
|
|
|
335
|
-
|
|
372
|
+
Aktion's surface syntax is a **strict subset of JavaScript**. Every
|
|
373
|
+
declaration uses standard JS constructs — `function`, `for...of`,
|
|
374
|
+
`if/else`, `switch/case`, arrow functions, object literals — so any
|
|
375
|
+
developer reading the output immediately knows what it does. The renderer
|
|
336
376
|
commits each line as soon as it streams in, so the user sees the page
|
|
337
377
|
shell before the leaves arrive.
|
|
338
378
|
|
|
339
|
-
```
|
|
379
|
+
```js
|
|
340
380
|
$count = 0
|
|
341
381
|
$theme = "dark"
|
|
342
382
|
|
|
343
|
-
|
|
383
|
+
function Counter(label = "Count") {
|
|
344
384
|
return Stack([
|
|
345
385
|
SectionHeader(label),
|
|
346
|
-
Button("Inc", onClick: () => $count = $count + 1),
|
|
386
|
+
Button("Inc", { onClick: () => $count = $count + 1 }),
|
|
347
387
|
Text(`Current: ${$count}`)
|
|
348
388
|
])
|
|
349
389
|
}
|
|
350
390
|
|
|
351
|
-
|
|
352
|
-
$orders = http({ url: "
|
|
391
|
+
function loadOrders() {
|
|
392
|
+
$orders = $http({ url: "https://api.example.com/orders", method: "GET" })
|
|
353
393
|
}
|
|
354
394
|
|
|
355
|
-
effect
|
|
356
|
-
$save = http({ url: "
|
|
357
|
-
}
|
|
395
|
+
$effect(() => {
|
|
396
|
+
$save = $http({ url: "https://api.example.com/draft", method: "PUT", body: $draft })
|
|
397
|
+
}, [$draft, "debounce(500)"])
|
|
358
398
|
|
|
359
|
-
$orders = http({
|
|
360
|
-
url: "
|
|
399
|
+
$orders = $http({
|
|
400
|
+
url: "https://api.example.com/users/42/orders",
|
|
361
401
|
method: "GET",
|
|
362
402
|
query: { limit: 5 }
|
|
363
403
|
})
|
|
364
404
|
|
|
365
|
-
pages =
|
|
405
|
+
pages = $router({
|
|
366
406
|
"/": Counter(),
|
|
367
|
-
"/orders": Async($orders, loading: Spinner(), data: OrderTable($orders.data)),
|
|
407
|
+
"/orders": Async($orders, { loading: Spinner(), data: OrderTable($orders.data) }),
|
|
368
408
|
default: NotFound()
|
|
369
409
|
})
|
|
370
410
|
|
|
371
|
-
|
|
411
|
+
aktion = pages
|
|
372
412
|
```
|
|
373
413
|
|
|
374
414
|
### Key constructs
|
|
375
415
|
|
|
376
|
-
- `
|
|
416
|
+
- `aktion = …` — the reserved entry point. Every program renders from
|
|
417
|
+
it.
|
|
377
418
|
- `$name = value` — reactive state. One kind. Read or write with the
|
|
378
|
-
same sigil. Inside
|
|
419
|
+
same sigil. Inside action / effect / lambda bodies, assignment
|
|
379
420
|
operators (`= += -= *= /= ??= ++ --`) are all allowed.
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
`
|
|
393
|
-
`
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
`
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
421
|
+
`let/const/var` are optional and do not affect reactivity — only the
|
|
422
|
+
`$` prefix makes a value reactive.
|
|
423
|
+
- **Component-call shape** — every call follows the trailing-object
|
|
424
|
+
rule:
|
|
425
|
+
|
|
426
|
+
```js
|
|
427
|
+
Component(positionalArg, { prop: value, … })
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Each component accepts **at most one positional argument** (typically
|
|
431
|
+
the title, children array, or primary value); every other argument
|
|
432
|
+
goes in a trailing `{ }` object literal. This is the *only* call
|
|
433
|
+
shape — `Button("Save", "primary", true)` is a schema error; write
|
|
434
|
+
`Button("Save", { variant: "primary", loading: true })` instead.
|
|
435
|
+
- `function Name(p = default) { return Expression }` — PascalCase name
|
|
436
|
+
means it's a component. Parameters use standard JS defaults (`=`).
|
|
437
|
+
Inside the body, `$x = expr` is a **declaration**: the initializer
|
|
438
|
+
runs once when the instance first mounts, and re-renders preserve
|
|
439
|
+
whatever value the user (or an action / effect) has written.
|
|
440
|
+
**Always** end with an explicit `return`. Components do not have a
|
|
441
|
+
`props` object — every parameter is a real JS parameter.
|
|
442
|
+
- `function name(args) { body }` — camelCase name means it's an action.
|
|
443
|
+
Callable effects with optional `return`. Used as event handlers
|
|
444
|
+
(`onClick: save`) or as expressions (`$result = greet("Ada")`).
|
|
445
|
+
- `$effect(() => { body }, [...deps])` — declarative, anonymous side
|
|
446
|
+
effects. The dependency array mixes state triggers (`$atom`),
|
|
447
|
+
lifecycle / interval triggers (`"mount"`, `"unmount"`, `"every(N)"`),
|
|
448
|
+
and rate-limit modifiers (`"debounce(N)"`, `"throttle(N)"`).
|
|
449
|
+
`$effect(() => { … })` (no second argument) is equivalent to
|
|
450
|
+
`$effect(() => { … }, ["mount"])`. Declare at the program top level
|
|
451
|
+
for global work, or inside a component function body to scope the
|
|
452
|
+
effect to that instance — the runtime mounts it on first render and
|
|
453
|
+
tears down its timers / subscriptions / `cleanup(fn)` handlers when
|
|
454
|
+
the instance leaves the tree.
|
|
455
|
+
- `$emit("name", { detail })` — dispatch an outbound `CustomEvent` on
|
|
456
|
+
the host element. Call from any action / effect / lambda body
|
|
457
|
+
whenever the surrounding host page needs to react to a user
|
|
458
|
+
interaction.
|
|
459
|
+
- Standard JS control flow — `if`, `switch`, `for`, `while`, `do…while`,
|
|
460
|
+
`try` are **statements**, exactly as in JavaScript. They run inside
|
|
461
|
+
any imperative body (`function`, lambda with `{ … }`, `effect`) but
|
|
462
|
+
cannot appear on the right-hand side of an assignment. Use ternaries
|
|
463
|
+
and `.map`/`.filter` for value-producing expressions. Bodies may be
|
|
464
|
+
either a block or a single statement (`if (!ok) return`):
|
|
465
|
+
|
|
466
|
+
```js
|
|
467
|
+
banner = $error ? ErrorAlert($error) : Notice("All good")
|
|
468
|
+
rows = $items.map(item => Row(item))
|
|
469
|
+
// Multi-way dispatch: wrap a `switch` in a function and `return` per arm.
|
|
470
|
+
function viewFor(tab) {
|
|
471
|
+
switch (tab) {
|
|
472
|
+
case "list": return ListView($items)
|
|
473
|
+
case "grid": return GridView($items)
|
|
474
|
+
default: return EmptyState("Pick a view")
|
|
475
|
+
}
|
|
476
|
+
}
|
|
477
|
+
view = viewFor($tab)
|
|
478
|
+
```
|
|
479
|
+
- Full operator set — arithmetic (`+`, `-`, `*`, `/`, `%`, `**`),
|
|
480
|
+
comparison (`==` / `!=` / `===` / `!==`, `<` / `>` / `<=` / `>=`),
|
|
481
|
+
logical (`&&`, `||`, `??`), bitwise / shift (`&`, `|`, `^`, `~`, `<<`,
|
|
482
|
+
`>>`, `>>>`), and the relational keywords `instanceof` / `in`. Every
|
|
483
|
+
compound-assignment form is supported too (`+=`, `-=`, `*=`, `/=`,
|
|
484
|
+
`%=`, `**=`, `&&=`, `||=`, `??=`, `&=`, `|=`, `^=`, `<<=`, `>>=`,
|
|
485
|
+
`>>>=`).
|
|
486
|
+
- Line continuations — any expression operator (`.`, `?.`, `?`, `:`,
|
|
487
|
+
`&&`, `||`, `??`, `==` / `!=` / `===` / `!==`, `<` / `>` / `<=` /
|
|
488
|
+
`>=`, `instanceof`, `+`, `-`, `*`, `/`, `%`, `**`) may appear at the
|
|
489
|
+
start of the next line and the parser keeps building the same
|
|
490
|
+
expression — matches JavaScript's ASI rules. Use this to split long
|
|
491
|
+
method chains, ternaries, and logical expressions across lines.
|
|
492
|
+
- `$http({ url, method, headers, body, query, ... })` — the only network
|
|
493
|
+
primitive (absolute `url`; `GET` default; no host-wide defaults).
|
|
494
|
+
Returns a reactive resource with `.data`, `.error`,
|
|
404
495
|
`.status`, `.loading`, `.headers`, `.lastUpdated`, `.refetch()`,
|
|
405
|
-
`.cancel()`.
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
-
|
|
414
|
-
|
|
415
|
-
|
|
496
|
+
`.cancel()`, and a settable `.onDone` callback that fires each time the
|
|
497
|
+
request settles (handy for `$todos.refetch()` after a write).
|
|
498
|
+
- `pages = $router({ "/path": Component(), default: NotFound() })` —
|
|
499
|
+
function-call router. The reserved `route` handle exposes the
|
|
500
|
+
reactive surface (`route.path`, `route.params`, `route.query`,
|
|
501
|
+
`route.pattern`) and a `route.navigate("/path")` method; each arm
|
|
502
|
+
body additionally receives a scoped `params` loop var with its
|
|
503
|
+
captures.
|
|
504
|
+
- Two-way binding is implicit: pass a `$variable` (or a member chain
|
|
505
|
+
rooted at one — `value: $form.email`) as an input prop and the
|
|
506
|
+
runtime wires it both ways.
|
|
507
|
+
- Lambdas — every JavaScript arrow form is supported: `() => expr`,
|
|
508
|
+
`x => expr` (single param, no parens), `(x) => expr`, `(x, y) => expr`,
|
|
509
|
+
`(x = 0) => x + 1` (defaults), `(...args) => sum(args)` (rest),
|
|
510
|
+
`({ a, b }) => a + b` / `([x, y]) => x` (destructured params),
|
|
511
|
+
`(args) => { … }` (multi-statement, may `return`). The body can wrap
|
|
512
|
+
onto the next line (`x =>\n expr`).
|
|
513
|
+
- Destructured parameters — both `function` declarations and lambdas
|
|
514
|
+
accept array / object patterns (`function Card({ title, tone = "info" })`,
|
|
515
|
+
`function head([first, ...rest])`), with the same defaults / renames /
|
|
516
|
+
rest support as `let`-destructuring.
|
|
517
|
+
- JS expression niceties — array / object spread (`[...xs, y]`,
|
|
518
|
+
`{ ...base, k: v }`), array / object destructuring in `let` / `const`
|
|
519
|
+
/ `var` (`let [a, b, ...rest] = arr`, `let { name, age = 0 } = user`),
|
|
520
|
+
computed property keys (`{ [$dynamic]: value }`), prefix and postfix
|
|
521
|
+
`++` / `--` (with JS-accurate return semantics), `new Constructor(...)`
|
|
522
|
+
with trailing member / call chains (`new Date(0).getTime()`), trailing
|
|
523
|
+
commas in function params / call args / literal lists. `async function`
|
|
524
|
+
is accepted as a no-op modifier; `await` is allowed in both statement
|
|
525
|
+
and expression position inside action / effect bodies.
|
|
526
|
+
- Top-level imperative statements — `if` / `for` / `while` / `try` and
|
|
527
|
+
bare expression statements written at the program top level run once
|
|
528
|
+
per plan (e.g. building a `$state` array with a `while` loop). Inside
|
|
529
|
+
a render they behave like a module init block; prefer pure expressions
|
|
530
|
+
(`.map`, `$util.range`) where you can.
|
|
531
|
+
- **`$util` runtime namespace** — pure, side-effect-free helpers for data
|
|
532
|
+
shaping, formatting, dates, math, and strings (`$util.filter`, `$util.sort`,
|
|
533
|
+
`$util.groupBy`, `$util.format`, `$util.formatDate`, `$util.plural`, `$util.range`,
|
|
534
|
+
`$util.addDays`, `$util.pick`, `$util.count`, …). Never carry hidden state —
|
|
535
|
+
safe to call anywhere.
|
|
536
|
+
- **Escape hatches** — `HTMLTag(tag, { attributes?, children? })` for
|
|
537
|
+
raw HTML elements and `Styles(css)` for raw CSS injected into the
|
|
538
|
+
shadow root. Use only when the standard component library cannot
|
|
539
|
+
express the design.
|
|
540
|
+
- **Hoisting & streaming** — references resolve from the entire
|
|
541
|
+
top-level scope, not source order. Always emit `aktion = …` first
|
|
542
|
+
so the reconciler has the page shell to attach streamed leaves to.
|
|
543
|
+
- Comments: `//` line comments and `/* block */` comments — standard
|
|
544
|
+
JS style.
|
|
545
|
+
|
|
546
|
+
#### Built-in globals at a glance
|
|
547
|
+
|
|
548
|
+
| Global | Purpose |
|
|
549
|
+
| --------- | -------------------------------------------------------------------- |
|
|
550
|
+
| `$storage` | Browser persistence — `$storage.set/get`, `$storage.session.*`, `$storage.cookies.*`. |
|
|
551
|
+
| `$console` | Forwards to the host console — `log` / `error` / `warn` / `info` / `debug`. |
|
|
552
|
+
| `route` | Reactive router handle — `path`, `params`, `query`, `pattern`, `navigate(path)`. |
|
|
553
|
+
| JS stdlib | The JS standard library — `Math`, `JSON`, `Object`, `Array`, `Number`, `String`, `Boolean`, `Date`, `Map`, `Set`, `RegExp`, `Promise`, plus `parseInt` / `parseFloat` / `isNaN` / `isFinite` / `encodeURIComponent` / … Use directly (`Math.max(a, b)`, `JSON.stringify(x)`, `Object.keys(o)`) or with `new` (`new Date()`, `new Map()`). |
|
|
554
|
+
| timers | `setTimeout` / `setInterval` / `clearTimeout` / `clearInterval` — like their JS counterparts, but tracked by the runtime and cleared automatically on re-plan/disconnect. Use inside an `effect` and clear in `cleanup`. |
|
|
555
|
+
| full JS globals | The **entire** JavaScript global surface is available — dialogs (`alert`, `confirm`, `prompt`), Web APIs (`fetch`, `URL`, `URLSearchParams`, `Blob`, `FormData`, `crypto`, `navigator`, `localStorage`, `atob`/`btoa`, `Intl`, `BigInt`, `Reflect`, …), and `window` / `document` themselves. Any `globalThis` member resolves by name. |
|
|
556
|
+
|
|
557
|
+
Both `$storage` and `$console` are **lowercase**; the `route` handle is
|
|
558
|
+
**reserved** (never declare a state slot named `route`). Author declarations
|
|
559
|
+
and built-in components always win over a same-named global (a library
|
|
560
|
+
`Text` / `Map` component is never shadowed by the DOM `Text` / `Map`), so the
|
|
561
|
+
global passthrough only resolves names you haven't otherwise defined. For
|
|
562
|
+
reactive data prefer `$http({...})` over raw `fetch`, and timers/listeners
|
|
563
|
+
belong inside an `$effect(...)` so they're cleaned up on unmount.
|
|
416
564
|
|
|
417
565
|
### The 60-second pitch
|
|
418
566
|
|
|
419
|
-
```
|
|
567
|
+
```js
|
|
420
568
|
$days = "7"
|
|
421
|
-
$data = http({ url: "
|
|
569
|
+
$data = $http({ url: "https://api.example.com/metrics", method: "GET", query: { days: $days } })
|
|
422
570
|
|
|
423
|
-
filter = FormControl("Range", control: Select("days",
|
|
571
|
+
filter = FormControl("Range", { control: Select("days", {
|
|
424
572
|
items: [SelectItem("7", "7d"), SelectItem("30", "30d")],
|
|
425
|
-
value: $days
|
|
426
|
-
|
|
427
|
-
|
|
573
|
+
value: $days
|
|
574
|
+
}) })
|
|
575
|
+
kpi = StatCard("Events", { value: `${$data.data?.events ?? 0}`, trend: "up" })
|
|
576
|
+
chart = LineChart({
|
|
428
577
|
labels: $data.data?.daily?.day ?? [],
|
|
429
|
-
series: [Series("Events", $data.data?.daily?.events ?? [])]
|
|
578
|
+
series: [Series("Events", $data.data?.daily?.events ?? [])]
|
|
579
|
+
})
|
|
430
580
|
|
|
431
|
-
|
|
581
|
+
aktion = Column([CardHeader("Analytics"), filter, kpi, chart])
|
|
432
582
|
```
|
|
433
583
|
|
|
434
584
|
Highlights:
|
|
@@ -442,86 +592,239 @@ Highlights:
|
|
|
442
592
|
- Array shortcuts: `$rows.length`, `$rows.first`, `$rows.last`,
|
|
443
593
|
plus pluck (`$rows.title` → `[title1, title2, …]`).
|
|
444
594
|
- Responsive prop maps on layout components:
|
|
445
|
-
`Grid(items, columns: { sm: 1, md: 2, lg: 4 }, gap: "l")`.
|
|
446
|
-
- Forward references are allowed — list `
|
|
595
|
+
`Grid(items, { columns: { sm: 1, md: 2, lg: 4 }, gap: "l" })`.
|
|
596
|
+
- Forward references are allowed — list `aktion = Column([...])` first
|
|
447
597
|
and let the children stream in beneath it.
|
|
448
598
|
|
|
449
|
-
### Declarative todo app
|
|
599
|
+
### Declarative todo app
|
|
450
600
|
|
|
451
|
-
```
|
|
601
|
+
```js
|
|
452
602
|
$todos = [{ id: 1, text: "Welcome — try editing", done: false }]
|
|
453
603
|
$draft = ""
|
|
454
604
|
|
|
455
|
-
|
|
605
|
+
function add() {
|
|
456
606
|
$todos = [...$todos, { id: $todos.length + 1, text: $draft, done: false }]
|
|
457
607
|
$draft = ""
|
|
458
608
|
}
|
|
459
609
|
|
|
460
|
-
|
|
461
|
-
$todos =
|
|
610
|
+
function remove(id) {
|
|
611
|
+
$todos = $util.filter($todos, "id", "!=", id)
|
|
462
612
|
}
|
|
463
613
|
|
|
464
|
-
row =
|
|
614
|
+
row = t => Card([Stack([
|
|
465
615
|
Text(t.text),
|
|
466
|
-
Button("Delete", onClick: () => remove(t.id), variant: "ghost")
|
|
616
|
+
Button("Delete", { onClick: () => remove(t.id), variant: "ghost" })
|
|
467
617
|
])])
|
|
468
618
|
|
|
469
|
-
list =
|
|
470
|
-
|
|
471
|
-
Input("draft-input", placeholder: "What needs doing?", value: $draft),
|
|
472
|
-
Button("Add", onClick: add, variant: "primary"),
|
|
619
|
+
list = $todos.map(t => row(t))
|
|
620
|
+
aktion = Stack([
|
|
621
|
+
Input("draft-input", { placeholder: "What needs doing?", value: $draft }),
|
|
622
|
+
Button("Add", { onClick: add, variant: "primary" }),
|
|
473
623
|
list
|
|
474
624
|
])
|
|
475
625
|
```
|
|
476
626
|
|
|
627
|
+
### Fine-grained reactivity
|
|
628
|
+
|
|
629
|
+
Dependencies are tracked at the **path** you read, not the whole atom.
|
|
630
|
+
Reading `$user.name` subscribes to `user.name` — so a write to a
|
|
631
|
+
**sibling** field leaves that reader untouched, while replacing the whole
|
|
632
|
+
atom (an ancestor) or writing a descendant still wakes it. This is the
|
|
633
|
+
auto-tracking of MobX, the path-granularity of Solid, and the
|
|
634
|
+
"recompute-only-on-input-change" of Redux selectors — with no selectors
|
|
635
|
+
or special syntax. You just read the path.
|
|
636
|
+
|
|
637
|
+
```js
|
|
638
|
+
$user = { name: "Ada", role: "Engineer" }
|
|
639
|
+
|
|
640
|
+
// Reads `user.name` → depends on `user.name` only.
|
|
641
|
+
greeting = Text(`Hi ${$user.name}`)
|
|
642
|
+
|
|
643
|
+
// Writing the sibling `role` does NOT re-render `greeting`, recompute a
|
|
644
|
+
// `$user.name`-derived value, or fire a `[$user.name]` effect.
|
|
645
|
+
function promote() { $user.role = "Manager" } // greeting stays put
|
|
646
|
+
function rename(next) { $user.name = next } // greeting updates
|
|
647
|
+
```
|
|
648
|
+
|
|
649
|
+
The rule that keeps it predictable:
|
|
650
|
+
|
|
651
|
+
| You read… | You depend on… |
|
|
652
|
+
| --- | --- |
|
|
653
|
+
| `$user` | `user` (the whole atom) |
|
|
654
|
+
| `$user.name` | `user.name` |
|
|
655
|
+
| `$user.address.city` | `user.address.city` |
|
|
656
|
+
| `$rows[i]` / `$rows.name` (array index / pluck) | `rows` (the array) |
|
|
657
|
+
| `$obj[$key]` (dynamic key) | `obj` + whatever `$key` reads |
|
|
658
|
+
|
|
659
|
+
A change to path **C** wakes a dependency on path **D** exactly when one
|
|
660
|
+
is a prefix of the other (equal, ancestor, or descendant) — sibling paths
|
|
661
|
+
never interfere. Object fields are tracked field-by-field; reading into an
|
|
662
|
+
array (or through a dynamic key) subscribes at the array/container, so
|
|
663
|
+
mutating any element re-renders the list. The same model powers the four
|
|
664
|
+
places work is triggered: **render scheduling** (the app re-renders only
|
|
665
|
+
when a changed path overlaps what it displayed), **computed values**
|
|
666
|
+
(`$total = $util.sum($cart.lines)` recomputes only when `cart.lines`
|
|
667
|
+
changes), **effects** (`$effect(..., [$user.name])`), and **per-component
|
|
668
|
+
re-rendering** (below).
|
|
669
|
+
|
|
670
|
+
#### Per-component re-rendering
|
|
671
|
+
|
|
672
|
+
A component only re-executes when **its own inputs change** — its args
|
|
673
|
+
(props) or a `$state` path its body read. This is the granularity of
|
|
674
|
+
`React.memo` / Solid, but automatic: no `memo()` wrapper. If `$user.age`
|
|
675
|
+
changes, a `ShowName($user.name)` that only read `name` is skipped (its
|
|
676
|
+
body — and any `console.log` in it — doesn't run); only the components that
|
|
677
|
+
actually depend on `age` re-execute.
|
|
678
|
+
|
|
679
|
+
```js
|
|
680
|
+
function App() {
|
|
681
|
+
$user = { name: "Ada", age: 30 }
|
|
682
|
+
return [ShowName($user.name), ShowAge($user.age)] // siblings, independent
|
|
683
|
+
}
|
|
684
|
+
// Changing $user.age re-runs ShowAge only; ShowName is reused (memoized).
|
|
685
|
+
```
|
|
686
|
+
|
|
687
|
+
Args are compared shallowly (`Object.is`), so — exactly as in React —
|
|
688
|
+
passing a **fresh inline lambda** each render (`onClick: () => …`) makes the
|
|
689
|
+
receiving component re-render every time; hoist the handler to a stable
|
|
690
|
+
binding if you want it skipped. State changes the path-tracker can't see
|
|
691
|
+
(hook setters, timers, HTTP, effects) fall back to a full re-render.
|
|
692
|
+
|
|
693
|
+
> Granularity is at both the *subscription* and *component* level. When a
|
|
694
|
+
> component does re-execute, Aktion rebuilds its render tree and the morph
|
|
695
|
+
> reconciler patches only the DOM that actually differs.
|
|
696
|
+
|
|
477
697
|
### Per-instance state & content-addressed identity
|
|
478
698
|
|
|
479
|
-
```
|
|
480
|
-
|
|
699
|
+
```js
|
|
700
|
+
function Counter(label) {
|
|
481
701
|
$n = 0
|
|
482
702
|
return Stack([
|
|
483
703
|
Text(`${label}: ${$n}`),
|
|
484
|
-
Button("inc", onClick: () => $n = $n + 1)
|
|
704
|
+
Button("inc", { onClick: () => $n = $n + 1 })
|
|
485
705
|
])
|
|
486
706
|
}
|
|
487
707
|
|
|
488
|
-
|
|
489
|
-
|
|
708
|
+
// Two independent counters — each holds its own atom.
|
|
709
|
+
aktion = Stack([Counter("A"), Counter("B")])
|
|
490
710
|
```
|
|
491
711
|
|
|
492
|
-
Every call site accepts a universal `key
|
|
712
|
+
Every call site accepts a universal `key` named argument. The renderer
|
|
493
713
|
uses it as the instance suffix instead of source location, so reordering
|
|
494
714
|
siblings keeps per-instance state attached to the right element:
|
|
495
715
|
|
|
496
|
-
```
|
|
497
|
-
|
|
498
|
-
return Stack([Text(task.title)], key: task.id)
|
|
716
|
+
```js
|
|
717
|
+
function TaskRow(task) {
|
|
718
|
+
return Stack([Text(task.title)], { key: task.id })
|
|
719
|
+
}
|
|
720
|
+
```
|
|
721
|
+
|
|
722
|
+
### Hooks — `$state`, `$memo`, and custom `$name`
|
|
723
|
+
|
|
724
|
+
A function whose name starts with `$` is a **hook**, mirroring React's
|
|
725
|
+
`use*` convention. Hooks are the composable way to manage per-instance
|
|
726
|
+
state. Built-in `$state` and `$memo` mirror React's `useState` and
|
|
727
|
+
`useMemo`:
|
|
728
|
+
|
|
729
|
+
```js
|
|
730
|
+
function Counter() {
|
|
731
|
+
const [count, setCount] = $state(0)
|
|
732
|
+
const label = $memo(() => `Count: ${count}`, [count])
|
|
733
|
+
return Stack([
|
|
734
|
+
Text(label),
|
|
735
|
+
Button("+1", { onClick: () => setCount(c => c + 1) })
|
|
736
|
+
])
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
aktion = Counter()
|
|
740
|
+
```
|
|
741
|
+
|
|
742
|
+
- `$state(initial)` returns a `[value, setValue]` pair. `setValue(next)`
|
|
743
|
+
replaces the value; `setValue(prev => next)` derives it from the
|
|
744
|
+
previous value. The initializer is evaluated once, on first render.
|
|
745
|
+
- `$memo(() => compute, [deps])` returns a cached value and recomputes
|
|
746
|
+
only when a dependency changes (shallow `Object.is` compare). Omit the
|
|
747
|
+
deps array to recompute every render.
|
|
748
|
+
|
|
749
|
+
Declare your own hooks with `function $name(...)`. A custom hook's
|
|
750
|
+
body runs **inline in the calling component's hook scope**, so its
|
|
751
|
+
`$state` / `$memo` calls attach to that component — exactly how a React
|
|
752
|
+
custom hook shares its caller's slots:
|
|
753
|
+
|
|
754
|
+
```js
|
|
755
|
+
function $useCounter(start) {
|
|
756
|
+
const [count, setCount] = $state(start)
|
|
757
|
+
return { count: count, increment: () => setCount(c => c + 1) }
|
|
758
|
+
}
|
|
759
|
+
|
|
760
|
+
function Counter(label) {
|
|
761
|
+
const c = $useCounter(0)
|
|
762
|
+
return Stack([Text(`${label}: ${c.count}`), Button("+1", { onClick: c.increment })])
|
|
499
763
|
}
|
|
500
764
|
```
|
|
501
765
|
|
|
766
|
+
Two rules, both inherited from React: call hooks **unconditionally and in
|
|
767
|
+
a stable order** at the top level of a component / hook body (slots are
|
|
768
|
+
matched by call order across renders), and remember that hook state
|
|
769
|
+
**resets when the instance leaves the tree** — a remounted component
|
|
770
|
+
starts again from its initial value. `$state` and `$memo` are reserved
|
|
771
|
+
names. The lighter `$name = value` per-instance form above remains
|
|
772
|
+
available when an atom is written directly by the component's actions.
|
|
773
|
+
|
|
774
|
+
### Global stores — `$store({...})`
|
|
775
|
+
|
|
776
|
+
For state shared across components — the role Redux / Zustand / Pinia play
|
|
777
|
+
elsewhere — declare a **store**. Non-function entries are reactive state;
|
|
778
|
+
function entries are methods that receive the store handle `s` first. Read
|
|
779
|
+
state with `store.field` (fine-grained), call methods with
|
|
780
|
+
`store.method(args)`, and mutate inside a method with `s.field = …`. The
|
|
781
|
+
handle is an app-global singleton with reference-stable methods, so any
|
|
782
|
+
component reads it or calls its actions directly — no prop drilling.
|
|
783
|
+
|
|
784
|
+
```js
|
|
785
|
+
cart = $store({
|
|
786
|
+
items: [], // state
|
|
787
|
+
count: (s) => s.items.length, // getter → cart.count()
|
|
788
|
+
total: (s) => $util.sum(s.items.map(i => i.price)), // getter → cart.total()
|
|
789
|
+
add: (s, item) => { s.items = [...s.items, item] }, // action → cart.add(item)
|
|
790
|
+
clear: (s) => { s.items = [] },
|
|
791
|
+
})
|
|
792
|
+
|
|
793
|
+
// Siblings with no relationship both talk to the same cart.
|
|
794
|
+
function AddLatte() { return Button("Add", { onClick: () => cart.add({ price: 4.5 }) }) }
|
|
795
|
+
function MiniCart() { return Text(`${cart.count()} items — ${$util.format(cart.total(), "currency")}`) }
|
|
796
|
+
aktion = Column([AddLatte(), MiniCart()])
|
|
797
|
+
```
|
|
798
|
+
|
|
799
|
+
Reads are fine-grained and per-component (changing `cart.items` re-renders
|
|
800
|
+
only components that read it), and store fields support two-way binding
|
|
801
|
+
(`Input(value: form.draft)`). Use a `$store` for shared state; use a
|
|
802
|
+
component's local `$state` / `$name = value` for state one component owns.
|
|
803
|
+
See the [Global state guide](https://asfand-dev.github.io/aktion/stores.html).
|
|
804
|
+
|
|
502
805
|
### Component-scoped effects
|
|
503
806
|
|
|
504
|
-
|
|
505
|
-
**or** inside a
|
|
807
|
+
`$effect(() => { … }, [...deps])` blocks can live at the program top level
|
|
808
|
+
**or** inside a component function body. Inside a component body the
|
|
506
809
|
runtime mounts the effect when the instance first renders and tears it
|
|
507
810
|
down (clearing timers, unsubscribing watched atoms, firing every
|
|
508
811
|
registered `cleanup(fn)`) the moment the instance disappears from the
|
|
509
812
|
tree. Two `LiveClock()` calls produce two independent intervals — and
|
|
510
813
|
removing one stops only that one:
|
|
511
814
|
|
|
512
|
-
```
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
$now =
|
|
517
|
-
effect
|
|
518
|
-
$now =
|
|
519
|
-
}
|
|
520
|
-
return Stack([Text(label), Text(
|
|
815
|
+
```js
|
|
816
|
+
aktion = Stack([LiveClock("UTC"), LiveClock("Local")])
|
|
817
|
+
|
|
818
|
+
function LiveClock(label) {
|
|
819
|
+
$now = $util.now()
|
|
820
|
+
$effect(() => {
|
|
821
|
+
$now = $util.now()
|
|
822
|
+
}, ["every(1000)"])
|
|
823
|
+
return Stack([Text(label), Text($util.formatDate($now, "time"))])
|
|
521
824
|
}
|
|
522
825
|
```
|
|
523
826
|
|
|
524
|
-
Use a top-level
|
|
827
|
+
Use a top-level `$effect(() => { … }, [...])` for global work (analytics,
|
|
525
828
|
app-wide keyboard shortcuts, hydration of shared atoms); use a
|
|
526
829
|
component-local effect whenever the background work logically belongs
|
|
527
830
|
to the UI it serves.
|
|
@@ -532,10 +835,10 @@ to the UI it serves.
|
|
|
532
835
|
[`src/library/index.js`](./src/library/index.ts)) emits **hard errors**
|
|
533
836
|
for:
|
|
534
837
|
|
|
535
|
-
- Closed-token enum mismatches (`Button("Save", variant: "magic")`).
|
|
536
|
-
- Unknown named args (`Stack(junk: 1)`).
|
|
838
|
+
- Closed-token enum mismatches (`Button("Save", { variant: "magic" })`).
|
|
839
|
+
- Unknown named args (`Stack({ junk: 1 })`).
|
|
537
840
|
- One-positional-max violations (`Button("Save", "primary", true)` →
|
|
538
|
-
"use `variant: "primary"
|
|
841
|
+
"use `{ variant: "primary", loading: true }`").
|
|
539
842
|
|
|
540
843
|
The host element merges these into `program.errors` so the on-screen
|
|
541
844
|
banner surfaces every violation.
|
|
@@ -555,7 +858,7 @@ deep authoring guide [`coding-gen-skill.md`](./coding-gen-skill.md).
|
|
|
555
858
|
|
|
556
859
|
## Component library
|
|
557
860
|
|
|
558
|
-
The bundle ships **
|
|
861
|
+
The bundle ships **170+ components** grouped by domain. Reach for **pattern composites**
|
|
559
862
|
(`Hero`, `PageHeader`, `Stats`, `Toolbar`, `EmptyState`, `Timeline`,
|
|
560
863
|
`KanbanBoard`, `DescriptionList`, `PricingTable`, …) before hand-rolling
|
|
561
864
|
the equivalent with `Card` + `Stack` — they're tuned to produce dense,
|
|
@@ -563,8 +866,8 @@ production-quality SaaS UI in a single line.
|
|
|
563
866
|
|
|
564
867
|
| Group | Components |
|
|
565
868
|
| ------------------ | ---------- |
|
|
566
|
-
| **Layout** | `Stack`, `StackItem`, `Grid`, `GridItem`, `Container`, `Box`, `Spacer`, `Card`, `CardHeader`, `CardFooter`, `Separator`, `Tabs`, `TabItem`, `Accordion`, `AccordionItem`, `Modal`, `Drawer`, `Steps`, `AspectRatio`, `ScrollArea`, `Sticky`, `ResizablePanels`, `MasonryGrid` |
|
|
567
|
-
| **Content** | `Text`, `Image`, `Icon`, `
|
|
869
|
+
| **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` |
|
|
870
|
+
| **Content** | `Text`, `Image`, `Icon`, `Badge`, `BadgeList`, `Callout`, `Quote`, `CodeBlock`, `Skeleton`, `Spinner`, `Markdown`, `Kbd` |
|
|
568
871
|
| **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` |
|
|
569
872
|
| **Data** | `Table`, `Col`, `DataGrid`, `List`, `ListItem`, `StatCard`, `Stats`, `Sparkline`, `Tile`, `Progress`, `ProgressRing`, `Pagination`, `Tree`, `TreeNode`, `CalendarView`, `ComparisonTable`, `InfiniteList` |
|
|
570
873
|
| **Charts** | `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `ScatterChart`, `Histogram`, `Heatmap`, `Gauge`, `Series` |
|
|
@@ -574,11 +877,56 @@ production-quality SaaS UI in a single line.
|
|
|
574
877
|
| **Editors** | `RichTextEditor`, `CodeEditor` |
|
|
575
878
|
| **Chat** | `SectionBlock`, `ListBlock`, `FollowUpBlock`, `FollowUpItem`, `ActionLink`, `ChatBubble` |
|
|
576
879
|
| **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` |
|
|
577
|
-
| **App shell** | `AppShell`, `Sidebar`, `SidebarSection`, `SidebarItem
|
|
880
|
+
| **App shell** | `AppShell`, `Sidebar`, `SidebarSection`, `SidebarItem` (supports `to` for router navigation), `SplitView` |
|
|
578
881
|
| **Advanced UI** | `IconButton`, `CommandPalette`, `FilterChips`, `FieldRepeater`, `VirtualList`, `QueryBuilder`, `DiffViewer`, `JsonTree`, `Gantt`, `Truncate`, `InlineEdit`, `NotificationBell` |
|
|
579
882
|
| **Helpers** | `Async`, `Show`, `Portal`, `Redirect`, `Lazy`, `ErrorBoundary` |
|
|
580
|
-
| **
|
|
581
|
-
| **
|
|
883
|
+
| **Behaviour wrappers** | `OnClick`, `OnMouse`, `OnKeyboard`, `OnFocus`, `OnIntersect`, `Css`, `Link` — attach click / mouse / keyboard / focus / intersection listeners or raw class / style to ANY component without it needing a dedicated prop. `Link(label_or_child, { to?, href?, external? })` wraps either a string or a component as a router-aware anchor. |
|
|
884
|
+
| **Escape hatches** | `HTMLTag`, `Styles` (last-resort raw HTML / CSS — see [language.html](https://asfand-dev.github.io/aktion/language.html#escape-hatches)) |
|
|
885
|
+
| **Theming** | `$theme` |
|
|
886
|
+
| **Routing** | `$router({ … })`, `NavLink` |
|
|
887
|
+
|
|
888
|
+
### Form `onChange` callback
|
|
889
|
+
|
|
890
|
+
Every input component accepts an optional `onChange(value)` callable
|
|
891
|
+
that fires with the freshly-read value on every change. Use it alongside
|
|
892
|
+
(or instead of) `$variable` two-way binding when you need to react
|
|
893
|
+
beyond a state write (debounce a search, persist a setting, kick off
|
|
894
|
+
a fetch).
|
|
895
|
+
|
|
896
|
+
```js
|
|
897
|
+
Input("query", { onChange: q => $results = $http({ url: `https://api.example.com/search?q=${q}` }) })
|
|
898
|
+
Slider("vol", { min: 0, max: 100, value: $vol, onChange: v => $storage.set("volume", v) })
|
|
899
|
+
Switch("dark", { value: $theme == "dark", onChange: on => $theme = on ? "dark" : "light" })
|
|
900
|
+
```
|
|
901
|
+
|
|
902
|
+
### Behaviour wrappers
|
|
903
|
+
|
|
904
|
+
Six tiny wrappers attach behaviour to any component:
|
|
905
|
+
|
|
906
|
+
```js
|
|
907
|
+
// Clickable / tappable card
|
|
908
|
+
OnClick(Card([Text("View order")]), { onClick: () => route.navigate("/orders/4821") })
|
|
909
|
+
|
|
910
|
+
// Lazy-load sentinel — fires once when the placeholder scrolls into view
|
|
911
|
+
OnIntersect(Skeleton({ variant: "card" }), { onEnter: $items.refetch, once: true })
|
|
912
|
+
|
|
913
|
+
// Drop zone — uses standard HTML5 drag-and-drop
|
|
914
|
+
OnMouse(Card([Text("Drop files here")]), {
|
|
915
|
+
dragOver: e => e.preventDefault(),
|
|
916
|
+
drop: e => { e.preventDefault(); $files = e.dataTransfer.files }
|
|
917
|
+
})
|
|
918
|
+
|
|
919
|
+
// Apply a custom class / style without breaking out of the component
|
|
920
|
+
Css(Card([Text("Highlighted")]), { class: "highlight", style: "border-color: #f59e0b;" })
|
|
921
|
+
```
|
|
922
|
+
|
|
923
|
+
`OnClick` / `OnMouse` / `OnKeyboard` / `OnFocus` render the child via a
|
|
924
|
+
transparent wrapper (`display: contents`) so the visual tree is
|
|
925
|
+
unchanged — only events bubble through the wrapper. `OnIntersect` uses
|
|
926
|
+
`IntersectionObserver` and disposes cleanly when the component leaves
|
|
927
|
+
the tree. `Css` merges classes / inline styles directly onto the
|
|
928
|
+
rendered child element. `Link` is the same wrapper applied as an
|
|
929
|
+
`<a>` anchor with optional router-aware navigation (`to`).
|
|
582
930
|
|
|
583
931
|
The full catalog with positional signatures, prop tables, enum values, and
|
|
584
932
|
live previews is at
|
|
@@ -586,27 +934,27 @@ live previews is at
|
|
|
586
934
|
|
|
587
935
|
### Rich pattern composites
|
|
588
936
|
|
|
589
|
-
```
|
|
590
|
-
|
|
591
|
-
|
|
937
|
+
```js
|
|
938
|
+
function export_q3() { $exp = $http({ url: "https://api.example.com/exports/q3", method: "POST" }) }
|
|
939
|
+
function new_project() { route.navigate("/projects/new") }
|
|
592
940
|
|
|
593
|
-
dashHeader = PageHeader("Engineering Q3", subtitle: "12 active · 4 at risk", breadcrumbs: ["Workspace", "Engineering"], actions: dashActions, status: Badge("On track", "success"))
|
|
594
|
-
dashActions = [Button("Export", onClick: export_q3, variant: "secondary"), Button("New project", onClick: new_project, variant: "primary")]
|
|
941
|
+
dashHeader = PageHeader("Engineering Q3", { subtitle: "12 active · 4 at risk", breadcrumbs: ["Workspace", "Engineering"], actions: dashActions, status: Badge("On track", "success") })
|
|
942
|
+
dashActions = [Button("Export", { onClick: export_q3, variant: "secondary" }), Button("New project", { onClick: new_project, variant: "primary" })]
|
|
595
943
|
kpis = Stats([
|
|
596
|
-
StatCard("Active", value: "12", trend: "flat"),
|
|
597
|
-
StatCard("At risk", value: "4", trend: "up", delta: "+2"),
|
|
598
|
-
StatCard("Shipped", value: "8", trend: "up", delta: "+3"),
|
|
599
|
-
StatCard("On-time", value: "87%", trend: "down", delta: "-3%")
|
|
944
|
+
StatCard("Active", { value: "12", trend: "flat" }),
|
|
945
|
+
StatCard("At risk", { value: "4", trend: "up", delta: "+2" }),
|
|
946
|
+
StatCard("Shipped", { value: "8", trend: "up", delta: "+3" }),
|
|
947
|
+
StatCard("On-time", { value: "87%", trend: "down", delta: "-3%" })
|
|
600
948
|
])
|
|
601
949
|
board = KanbanBoard([
|
|
602
|
-
KanbanColumn("To do", items: [KanbanCard("Migrate auth", description: "Roll out new SDK.", tags: ["auth"], assignee: "Asha")]),
|
|
603
|
-
KanbanColumn("Doing", items: [KanbanCard("Streaming UI v2", description: "20 new components.", tags: ["frontend"], assignee: "Alex", tone: "primary")]),
|
|
604
|
-
KanbanColumn("Review", items: [KanbanCard("Mobile onboarding", description: "Awaiting design.", tags: ["mobile"], assignee: "Wren", tone: "warning")]),
|
|
605
|
-
KanbanColumn("Done", items: [KanbanCard("Activity timeline", description: "Shipped to 100%.", tags: ["shipped"], assignee: "Mira", tone: "success")])
|
|
950
|
+
KanbanColumn("To do", { items: [KanbanCard("Migrate auth", { description: "Roll out new SDK.", tags: ["auth"], assignee: "Asha" })] }),
|
|
951
|
+
KanbanColumn("Doing", { items: [KanbanCard("Streaming UI v2", { description: "20 new components.", tags: ["frontend"], assignee: "Alex", tone: "primary" })] }),
|
|
952
|
+
KanbanColumn("Review", { items: [KanbanCard("Mobile onboarding", { description: "Awaiting design.", tags: ["mobile"], assignee: "Wren", tone: "warning" })] }),
|
|
953
|
+
KanbanColumn("Done", { items: [KanbanCard("Activity timeline", { description: "Shipped to 100%.", tags: ["shipped"], assignee: "Mira", tone: "success" })] })
|
|
606
954
|
])
|
|
607
955
|
follow = FollowUpBlock(["Show at-risk projects", "Compare to Q2", "Who needs help?"])
|
|
608
956
|
|
|
609
|
-
|
|
957
|
+
aktion = Column([dashHeader, kpis, board, follow])
|
|
610
958
|
```
|
|
611
959
|
|
|
612
960
|
### Adding your own components
|
|
@@ -676,14 +1024,14 @@ el.setTheme({
|
|
|
676
1024
|
});
|
|
677
1025
|
```
|
|
678
1026
|
|
|
679
|
-
###
|
|
1027
|
+
### `$theme({...})` from inside a response
|
|
680
1028
|
|
|
681
|
-
A response can brand itself by assigning a
|
|
682
|
-
reserved `theme` binding. The tokens land on the host as CSS
|
|
683
|
-
top of the base theme.
|
|
1029
|
+
A response can brand itself by assigning a `$theme({...})` call to the
|
|
1030
|
+
reserved top-level `theme` binding. The tokens land on the host as CSS
|
|
1031
|
+
variables on top of the base theme.
|
|
684
1032
|
|
|
685
|
-
```
|
|
686
|
-
theme =
|
|
1033
|
+
```js
|
|
1034
|
+
theme = $theme({
|
|
687
1035
|
colors: {
|
|
688
1036
|
primary: "#0969da",
|
|
689
1037
|
border: "#d0d7de",
|
|
@@ -697,12 +1045,12 @@ theme = Theme({
|
|
|
697
1045
|
radius: { button: "6px", input: "6px" }
|
|
698
1046
|
})
|
|
699
1047
|
|
|
700
|
-
|
|
1048
|
+
aktion = Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])])
|
|
701
1049
|
```
|
|
702
1050
|
|
|
703
|
-
`
|
|
1051
|
+
`$theme` expects the **structured** form — top-level groups `colors` /
|
|
704
1052
|
`radius` / `font` / `motion` / `elevation` (plus metadata keys `name`
|
|
705
|
-
and `direction`). Removing the
|
|
1053
|
+
and `direction`). Removing the `$theme(...)` line snaps the UI back to
|
|
706
1054
|
the base theme. Unknown keys are ignored silently, so typos in an
|
|
707
1055
|
LLM-emitted token map can never break the page.
|
|
708
1056
|
|
|
@@ -737,8 +1085,8 @@ shadow root. Host apps do **not** need to add a stylesheet.
|
|
|
737
1085
|
`"circle-check"`, `"triangle-exclamation"`, `"sack-dollar"`.
|
|
738
1086
|
- Optional variant prefix: `"regular:star"`, `"brands:github"`. The
|
|
739
1087
|
default variant is `solid`.
|
|
740
|
-
- Use the dedicated `Icon(name, variant?, size?)` component to render
|
|
741
|
-
standalone glyph (`size` ∈ `xs`, `sm`, `md`, `lg`, `xl`).
|
|
1088
|
+
- Use the dedicated `Icon(name, { variant?, size? })` component to render
|
|
1089
|
+
a standalone glyph (`size` ∈ `xs`, `sm`, `md`, `lg`, `xl`).
|
|
742
1090
|
- Every component prop named `icon` — `NavLink`, `SidebarItem`, `Banner`,
|
|
743
1091
|
`Notification`, `FeatureItem`, `Badge`, `StatCard`, `ListItem`,
|
|
744
1092
|
`TimelineItem`, `DescriptionItem`, `Tile`, `EmptyState`, … — expects a
|
|
@@ -747,16 +1095,16 @@ shadow root. Host apps do **not** need to add a stylesheet.
|
|
|
747
1095
|
stripped silently so legacy emoji leftovers still resolve to the
|
|
748
1096
|
proper icon.
|
|
749
1097
|
|
|
750
|
-
```
|
|
751
|
-
brandIcon = Icon("rocket", "solid", "lg")
|
|
1098
|
+
```js
|
|
1099
|
+
brandIcon = Icon("rocket", { variant: "solid", size: "lg" })
|
|
752
1100
|
homeIcon = Icon("house")
|
|
753
|
-
profileTab = NavLink("Profile", to: "/profile", variant: "ghost", icon: "user")
|
|
1101
|
+
profileTab = NavLink("Profile", { to: "/profile", variant: "ghost", icon: "user" })
|
|
754
1102
|
kpis = Stats([
|
|
755
|
-
StatCard("Revenue", value: "$48k", trend: "up", delta: "+12%", icon: "sack-dollar"),
|
|
756
|
-
StatCard("Orders", value: "1,284", trend: "up", delta: "+8%", icon: "cart-shopping"),
|
|
757
|
-
StatCard("Refunds", value: "12", trend: "down", delta: "-3", icon: "rotate-left")
|
|
1103
|
+
StatCard("Revenue", { value: "$48k", trend: "up", delta: "+12%", icon: "sack-dollar" }),
|
|
1104
|
+
StatCard("Orders", { value: "1,284", trend: "up", delta: "+8%", icon: "cart-shopping" }),
|
|
1105
|
+
StatCard("Refunds", { value: "12", trend: "down", delta: "-3", icon: "rotate-left" })
|
|
758
1106
|
])
|
|
759
|
-
|
|
1107
|
+
aktion = Stack([brandIcon, kpis, profileTab])
|
|
760
1108
|
```
|
|
761
1109
|
|
|
762
1110
|
---
|
|
@@ -768,39 +1116,39 @@ stay in sync with the URL (`#/dashboard`, `#/users/42`). Browser
|
|
|
768
1116
|
back/forward, bookmarks, and deep links all work — and the host page
|
|
769
1117
|
never reloads.
|
|
770
1118
|
|
|
771
|
-
```
|
|
772
|
-
pages =
|
|
1119
|
+
```js
|
|
1120
|
+
pages = $router({
|
|
773
1121
|
"/": homePage,
|
|
774
1122
|
"/dashboard": dashboardPage,
|
|
775
|
-
"/users/:id": userPage(id: params.id),
|
|
1123
|
+
"/users/:id": userPage({ id: params.id }),
|
|
776
1124
|
default: notFoundPage
|
|
777
1125
|
})
|
|
778
1126
|
|
|
779
|
-
nav =
|
|
780
|
-
NavLink("Home", to: "/", exact: true),
|
|
781
|
-
NavLink("Dashboard", to: "/dashboard"),
|
|
782
|
-
NavLink("Users", to: "/users")
|
|
783
|
-
],
|
|
1127
|
+
nav = Row([
|
|
1128
|
+
NavLink("Home", { to: "/", exact: true }),
|
|
1129
|
+
NavLink("Dashboard", { to: "/dashboard" }),
|
|
1130
|
+
NavLink("Users", { to: "/users" })
|
|
1131
|
+
], { gap: "s" })
|
|
784
1132
|
|
|
785
|
-
|
|
1133
|
+
aktion = Stack([nav, pages])
|
|
786
1134
|
|
|
787
1135
|
homePage = Card([CardHeader("Welcome")])
|
|
788
1136
|
dashboardPage = Card([CardHeader("Dashboard")])
|
|
789
1137
|
userPage = (id) => Card([CardHeader(`User ${id}`)])
|
|
790
|
-
notFoundPage = Callout("Not found", description: `We couldn't find ${
|
|
1138
|
+
notFoundPage = Callout("Not found", { description: `We couldn't find ${route.path}.`, variant: "warning" })
|
|
791
1139
|
```
|
|
792
1140
|
|
|
793
|
-
- `pages =
|
|
1141
|
+
- `pages = $router({ "/path": Component(), default: Fallback() })` picks
|
|
794
1142
|
the matching arm based on the current hash path. First match wins;
|
|
795
1143
|
`default:` is the fallback.
|
|
796
1144
|
- Route patterns support literal segments (`"/about"`), parameter
|
|
797
1145
|
segments (`"/users/:id"` → `params.id`), and trailing wildcards
|
|
798
1146
|
(`"/docs/*"` → `params._`).
|
|
799
|
-
- `NavLink(label, to
|
|
800
|
-
that intercepts clicks and reflects `data-active="true"` for the
|
|
1147
|
+
- `NavLink(label, { to, variant?, exact?, icon? })` is a router-aware
|
|
1148
|
+
anchor that intercepts clicks and reflects `data-active="true"` for the
|
|
801
1149
|
current path.
|
|
802
|
-
- The reactive `
|
|
803
|
-
`
|
|
1150
|
+
- The reactive `route` handle exposes `route.path`, `route.params`,
|
|
1151
|
+
`route.query`, and `route.pattern`. Call `route.navigate("/path")`
|
|
804
1152
|
from inside the script, or `el.navigate("/path")` from the host.
|
|
805
1153
|
|
|
806
1154
|
The default ("full") system prompt teaches the LLM about routing. The
|
|
@@ -810,88 +1158,27 @@ for the full walkthrough.
|
|
|
810
1158
|
|
|
811
1159
|
---
|
|
812
1160
|
|
|
813
|
-
## JavaScript escape hatch
|
|
814
|
-
|
|
815
|
-
`js{ … }` blocks live inside `effect` or `action` bodies — no host
|
|
816
|
-
attribute, no allow-list. Reach for them only when no declarative path
|
|
817
|
-
captures the behaviour (timers, clipboard, audio, complex computations,
|
|
818
|
-
host-tool calls).
|
|
819
|
-
|
|
820
|
-
```text
|
|
821
|
-
$todos = []
|
|
822
|
-
|
|
823
|
-
action toggle(id) {
|
|
824
|
-
js {
|
|
825
|
-
const todos = ctx.state.get("todos") || []
|
|
826
|
-
ctx.state.set("todos", todos.map(t => t.id === ctx.args.id ? { ...t, done: !t.done } : t))
|
|
827
|
-
}
|
|
828
|
-
}
|
|
829
|
-
|
|
830
|
-
row = (t) => Card([Stack([
|
|
831
|
-
Text(t.text),
|
|
832
|
-
Button("Toggle", onClick: () => toggle(t.id))
|
|
833
|
-
])])
|
|
834
|
-
|
|
835
|
-
list = for t in $todos { row(t) }
|
|
836
|
-
_app_ = Stack([list])
|
|
837
|
-
```
|
|
838
|
-
|
|
839
|
-
Inside the `js{ … }` block:
|
|
840
|
-
|
|
841
|
-
- `ctx.state.get(name)` / `ctx.state.set(name, value)` read and write
|
|
842
|
-
reactive atoms.
|
|
843
|
-
- `ctx.args` exposes the action's positional parameters keyed by name.
|
|
844
|
-
- `ctx.cleanup(fn)` (effects only) registers a teardown to fire on
|
|
845
|
-
re-run and unmount.
|
|
846
|
-
- `ctx.host` is the host element, for DOM-observing effects.
|
|
847
|
-
- `ctx.tools` is a host-registered async tool registry (see `el.setTools(...)`).
|
|
848
|
-
|
|
849
|
-
The body runs inside `(async () => { … })()` so `await` is free. Errors
|
|
850
|
-
are caught and logged — a broken body never crashes the host page.
|
|
851
|
-
|
|
852
|
-
For long-lived behaviour, prefer an `effect`:
|
|
853
|
-
|
|
854
|
-
```text
|
|
855
|
-
effect [$draft, debounce(500)] {
|
|
856
|
-
js {
|
|
857
|
-
await fetch("/save", { method: "POST", body: JSON.stringify({ draft: ctx.state.get("draft") }) })
|
|
858
|
-
}
|
|
859
|
-
}
|
|
860
|
-
```
|
|
861
|
-
|
|
862
|
-
The default (full) system prompt teaches `effect` / `action` / `js{}`;
|
|
863
|
-
the chat-flavoured prompt (`getSystemPrompt({ mode: "chat" })`) omits
|
|
864
|
-
the JS section entirely.
|
|
865
|
-
|
|
866
|
-
See the
|
|
867
|
-
[JavaScript interactions guide](https://asfand-dev.github.io/aktion/javascript-interactions.html)
|
|
868
|
-
or the deep
|
|
869
|
-
[`coding-gen-skill.md`](./coding-gen-skill.md)
|
|
870
|
-
for a full walkthrough.
|
|
871
|
-
|
|
872
|
-
---
|
|
873
|
-
|
|
874
1161
|
## Built-in globals
|
|
875
1162
|
|
|
876
|
-
Two namespace globals are always in scope inside
|
|
877
|
-
program — no import
|
|
878
|
-
`obj.method(args)` method-call syntax and accept
|
|
1163
|
+
Two namespace globals are always in scope inside an Aktion
|
|
1164
|
+
program — no import required. Both follow the standard
|
|
1165
|
+
`obj.method(args)` method-call syntax and accept object-literal options.
|
|
879
1166
|
|
|
880
|
-
```
|
|
881
|
-
|
|
882
|
-
storage.set("name", "John")
|
|
883
|
-
$name = storage.get("name")
|
|
1167
|
+
```js
|
|
1168
|
+
// localStorage is the default; `$storage.local` is its alias.
|
|
1169
|
+
$storage.set("name", "John")
|
|
1170
|
+
$name = $storage.get("name")
|
|
884
1171
|
|
|
885
|
-
|
|
886
|
-
storage.session.set("draft", $draft)
|
|
887
|
-
$draft = storage.session.get("draft")
|
|
1172
|
+
// Per-tab sessionStorage.
|
|
1173
|
+
$storage.session.set("draft", $draft)
|
|
1174
|
+
$draft = $storage.session.get("draft")
|
|
888
1175
|
|
|
889
|
-
|
|
890
|
-
storage.cookies.set("user", "John", expires: 7, path: "/", sameSite: "Lax")
|
|
891
|
-
$user = storage.cookies.get("user")
|
|
892
|
-
storage.cookies.remove("user", path: "/")
|
|
1176
|
+
// Cookies — options as an object literal.
|
|
1177
|
+
$storage.cookies.set("user", "John", { expires: 7, path: "/", sameSite: "Lax" })
|
|
1178
|
+
$user = $storage.cookies.get("user")
|
|
1179
|
+
$storage.cookies.remove("user", { path: "/" })
|
|
893
1180
|
|
|
894
|
-
|
|
1181
|
+
// Forwards to the host console.
|
|
895
1182
|
console.log("Hello", $user)
|
|
896
1183
|
console.error("Something failed", $error)
|
|
897
1184
|
```
|
|
@@ -912,28 +1199,45 @@ for the full surface.
|
|
|
912
1199
|
|
|
913
1200
|
## Internationalization
|
|
914
1201
|
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
```
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
greeting: "Bonjour,
|
|
925
|
-
|
|
1202
|
+
Call `$i18n({...})` to build a translation bundle. You can destructure
|
|
1203
|
+
`t`, `setCurrentLanguage`, and `getCurrentLanguage`, or keep the result
|
|
1204
|
+
as an instance and call its methods.
|
|
1205
|
+
|
|
1206
|
+
```js
|
|
1207
|
+
const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({
|
|
1208
|
+
defaultLanguage: "en",
|
|
1209
|
+
currentLanguage: "fr",
|
|
1210
|
+
translations: {
|
|
1211
|
+
greeting: { en: "Hello, {name}!", fr: "Bonjour, {name}!" },
|
|
1212
|
+
orders_title:{ en: "Recent orders", fr: "Commandes récentes" },
|
|
1213
|
+
items_count: { en: "{count} items", fr: "{count} objets" }
|
|
926
1214
|
}
|
|
927
1215
|
})
|
|
928
1216
|
|
|
929
|
-
welcome
|
|
930
|
-
sectionTitle = SectionHeader(t("
|
|
931
|
-
|
|
1217
|
+
welcome = Text(t("greeting", { name: $user.name }))
|
|
1218
|
+
sectionTitle = SectionHeader(t("orders_title"))
|
|
1219
|
+
count = Text(t("items_count", { count: 5 }))
|
|
932
1220
|
```
|
|
933
1221
|
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
1222
|
+
Lookups resolve `translations[key][currentLanguage]`, fall back to
|
|
1223
|
+
`translations[key][defaultLanguage]`, then to the bare key as a literal
|
|
1224
|
+
string. Variables are interpolated using `{name}` placeholders.
|
|
1225
|
+
|
|
1226
|
+
For reactive language switching, drive `currentLanguage` from a state
|
|
1227
|
+
atom and either call `setCurrentLanguage(...)` or rebuild the bundle:
|
|
1228
|
+
|
|
1229
|
+
```js
|
|
1230
|
+
$lang = "fr"
|
|
1231
|
+
const i18nInstance = $i18n({
|
|
1232
|
+
defaultLanguage: "en",
|
|
1233
|
+
currentLanguage: $lang,
|
|
1234
|
+
translations: { hi: { en: "Hi", fr: "Salut", de: "Hallo" } }
|
|
1235
|
+
})
|
|
1236
|
+
aktion = Column([
|
|
1237
|
+
Text(i18nInstance.t("hi")),
|
|
1238
|
+
Button("Deutsch", { onClick: () => { $lang = "de" } })
|
|
1239
|
+
])
|
|
1240
|
+
```
|
|
937
1241
|
|
|
938
1242
|
---
|
|
939
1243
|
|
|
@@ -988,8 +1292,8 @@ import {
|
|
|
988
1292
|
```
|
|
989
1293
|
|
|
990
1294
|
- `formatProgram` projects the parsed AST back to canonical source —
|
|
991
|
-
|
|
992
|
-
indentation,
|
|
1295
|
+
object-literal named args, double-quoted strings, two-space block
|
|
1296
|
+
indentation, template literals intact.
|
|
993
1297
|
- `inspectAST(source)` returns a JSON-friendly view of the Committed +
|
|
994
1298
|
Drafting ASTs at the current byte position — bindings (with
|
|
995
1299
|
kind / line / column / summary), in-flight names, and any parse errors.
|
|
@@ -1003,6 +1307,123 @@ import {
|
|
|
1003
1307
|
|
|
1004
1308
|
---
|
|
1005
1309
|
|
|
1310
|
+
## Build-time compiler & multi-file modules
|
|
1311
|
+
|
|
1312
|
+
> **Optional.** The CDN bundle and the streamed-string path
|
|
1313
|
+
> (`<aktion-app response="...">`, `setResponse`, `appendChunk`) work exactly as
|
|
1314
|
+
> before. This is an opt-in enhancement for NPM consumers who author UI by hand
|
|
1315
|
+
> and want multi-file modules, type-safety, source maps, and IDE integration.
|
|
1316
|
+
|
|
1317
|
+
When you install `aktion-runtime` from NPM you can author UI in `.aktion` files
|
|
1318
|
+
and let a Vite/Rollup plugin **compile them at build time** into the
|
|
1319
|
+
already-parsed, schema-validated component tree. The browser then mounts that
|
|
1320
|
+
pre-parsed AST without running the parser. The runtime stays fully reactive —
|
|
1321
|
+
`$state`, `$http`, effects, and routing all run in the browser as usual; only
|
|
1322
|
+
parsing, linking, and validation move to build time.
|
|
1323
|
+
|
|
1324
|
+
**What you get:** multi-file `import`/`export`; parse + schema errors become
|
|
1325
|
+
**build errors** (unknown component / prop / enum, surfaced in Vite's overlay
|
|
1326
|
+
with a code frame); a typed `CompiledProgram` default export; **source maps**
|
|
1327
|
+
back to your `.aktion` file; and editor diagnostics/hover/completions (see
|
|
1328
|
+
[Editor support](#editor-support)). HMR is automatic and **preserves live
|
|
1329
|
+
`$state`** across edits — even when you edit an imported module.
|
|
1330
|
+
|
|
1331
|
+
### Setup
|
|
1332
|
+
|
|
1333
|
+
```ts
|
|
1334
|
+
// vite.config.ts
|
|
1335
|
+
import { defineConfig } from "vite";
|
|
1336
|
+
import aktion from "aktion-runtime/vite";
|
|
1337
|
+
|
|
1338
|
+
export default defineConfig({ plugins: [aktion()] });
|
|
1339
|
+
```
|
|
1340
|
+
|
|
1341
|
+
```jsonc
|
|
1342
|
+
// tsconfig.json — make TypeScript resolve `import ui from "./app.aktion"`
|
|
1343
|
+
{ "compilerOptions": { "types": ["aktion-runtime/aktion-modules"] } }
|
|
1344
|
+
```
|
|
1345
|
+
|
|
1346
|
+
### Authoring
|
|
1347
|
+
|
|
1348
|
+
A `.aktion` file is pure DSL (identical grammar to a streamed response):
|
|
1349
|
+
|
|
1350
|
+
```
|
|
1351
|
+
// src/dashboard.aktion
|
|
1352
|
+
$count = 0
|
|
1353
|
+
aktion = Card([
|
|
1354
|
+
CardHeader("Counter"),
|
|
1355
|
+
Button(`Clicked ${$count} times`, { action: increment })
|
|
1356
|
+
])
|
|
1357
|
+
function increment() { $count = $count + 1 }
|
|
1358
|
+
```
|
|
1359
|
+
|
|
1360
|
+
### Multi-file modules
|
|
1361
|
+
|
|
1362
|
+
`.aktion` files `import`/`export` like JS/TS, with **true module scope** — a
|
|
1363
|
+
file's non-exported top-level names (components, actions, `$state`, helpers) are
|
|
1364
|
+
private to that file:
|
|
1365
|
+
|
|
1366
|
+
```
|
|
1367
|
+
// src/components/counter.aktion
|
|
1368
|
+
export $count = 0
|
|
1369
|
+
export function Counter() {
|
|
1370
|
+
return Button(`Clicked ${$count}`, { action: bump })
|
|
1371
|
+
}
|
|
1372
|
+
function bump() { $count = $count + 1 } // private to this module
|
|
1373
|
+
```
|
|
1374
|
+
|
|
1375
|
+
```
|
|
1376
|
+
// src/app.aktion (entry — must define `aktion`)
|
|
1377
|
+
import { Counter, $count } from "./components/counter.aktion"
|
|
1378
|
+
aktion = Column([Markdown(`Shared count: ${$count}`), Counter()])
|
|
1379
|
+
```
|
|
1380
|
+
|
|
1381
|
+
Named imports only (`import { A, B as C, $shared } from "./mod.aktion"`); a
|
|
1382
|
+
`$state` import keeps its `$`. The compiler resolves the import graph at build
|
|
1383
|
+
time and links it into one program, renaming each module's private names so two
|
|
1384
|
+
files can reuse a name without clashing. The **entry** keeps its own names
|
|
1385
|
+
canonical (the `aktion` binding and the `$state` names that `serializeState` /
|
|
1386
|
+
`applyDelta` target). Importing is a build-time feature — the streaming runtime
|
|
1387
|
+
path stays single-file.
|
|
1388
|
+
|
|
1389
|
+
### Mounting
|
|
1390
|
+
|
|
1391
|
+
```ts
|
|
1392
|
+
import "aktion-runtime"; // registers <aktion-app>
|
|
1393
|
+
import app from "./app.aktion"; // a typed CompiledProgram (the whole linked graph)
|
|
1394
|
+
|
|
1395
|
+
document.querySelector("aktion-app").mountCompiled(app);
|
|
1396
|
+
```
|
|
1397
|
+
|
|
1398
|
+
Editing any file in the graph hot-reloads in place: the plugin recompiles
|
|
1399
|
+
(imported files are registered as watched dependencies), and the self-accepting
|
|
1400
|
+
module re-mounts the program while replaying the current `$state` via
|
|
1401
|
+
`serializeState()`, so live state survives the edit.
|
|
1402
|
+
|
|
1403
|
+
### Editor support
|
|
1404
|
+
|
|
1405
|
+
The [Aktion VS Code extension](./editors/vscode/) treats `.aktion` as
|
|
1406
|
+
TypeScript (highlighting) and adds inline diagnostics, hover, completions, and
|
|
1407
|
+
snippets via the DOM-free `aktion-runtime/language` API — the same schema-aware
|
|
1408
|
+
language service the docs playground uses.
|
|
1409
|
+
|
|
1410
|
+
### Package entry points
|
|
1411
|
+
|
|
1412
|
+
| Import | Runs in | Purpose |
|
|
1413
|
+
| ------------------------------- | ------- | ------------------------------------------------------------- |
|
|
1414
|
+
| `aktion-runtime` | browser | the `<aktion-app>` element + `mountCompiled` |
|
|
1415
|
+
| `aktion-runtime/vite` | Node | the Vite/Rollup plugin (`aktion()`) |
|
|
1416
|
+
| `aktion-runtime/compiler` | Node | `compile(source, opts)` for programmatic/build use |
|
|
1417
|
+
| `aktion-runtime/language` | Node | DOM-free diagnostics/hover/completions/snippets (editors/LSP) |
|
|
1418
|
+
| `aktion-runtime/aktion-modules` | types | ambient `*.aktion` module declarations |
|
|
1419
|
+
|
|
1420
|
+
The plugin, compiler, and language service ship as a **separate Node entry**
|
|
1421
|
+
(`dist/node/`) and never enter the browser bundle, so `dist/aktion.js` is
|
|
1422
|
+
unchanged. A runnable example lives in
|
|
1423
|
+
[`examples/vite-compiler/`](./examples/vite-compiler/).
|
|
1424
|
+
|
|
1425
|
+
---
|
|
1426
|
+
|
|
1006
1427
|
## Documentation site
|
|
1007
1428
|
|
|
1008
1429
|
The `docs/` folder is the source for the live documentation site at
|
|
@@ -1016,14 +1437,16 @@ consumes from the CDN.
|
|
|
1016
1437
|
| `get-started.html` | Step-by-step integration walkthrough. |
|
|
1017
1438
|
| `frameworks.html` | Integration recipes for React, Next.js, Vue, Angular, Svelte, plain HTML. |
|
|
1018
1439
|
| `language.html` | Full Aktion language reference. |
|
|
1440
|
+
| `http.html` | HTTP guide — the `$http({...})` primitive, config options, the reactive resource bag, `Async`, refetch/cancel patterns, and a full CRUD walkthrough. |
|
|
1019
1441
|
| `components.html` | Every built-in component with a live preview, positional signatures, prop tables, and enum values. |
|
|
1020
|
-
| `actions.html` | `
|
|
1021
|
-
| `side-effects.html` |
|
|
1022
|
-
| `javascript-interactions.html` |
|
|
1442
|
+
| `actions.html` | `function name() { … }` guide — declarative state mutations, optimistic snapshot/rollback, lambda-based click handlers, navigation, and end-to-end examples. |
|
|
1443
|
+
| `side-effects.html` | `$effect(() => { … }, [...deps])` guide — anonymous side effects, dependency entries (state, lifecycle, intervals, debounce/throttle), top-level vs. component-local scope, cleanup, and effect vs. action. |
|
|
1444
|
+
| `javascript-interactions.html` | Effect + action bodies — the JavaScript execution surface. |
|
|
1023
1445
|
| `routing.html` | Hash-based routing guide — always available at runtime. |
|
|
1024
1446
|
| `themes.html` | Built-in themes gallery, live picker, side-by-side compare, and the token customization studio. |
|
|
1025
1447
|
| `examples.html` | Curated showcase of real-world block UIs (auth, products, FAQ, cart, todos, …). |
|
|
1026
1448
|
| `playground.html` | CodeMirror 6 editor with custom highlighting / autocomplete, live preview, share links, hover-over component info, and an inspection mode. |
|
|
1449
|
+
| `visual-editor.html` | Drag-and-drop visual editor for the full 170+ component library. Three canvas modes (Raw Edit / Visual Edit / Preview), an Outline tab for top-level entity navigation, typed prop editors, cross-entity selection, and import / export of `.aktion` + self-contained HTML via an editable Source drawer. |
|
|
1027
1450
|
| `chat-bot.html` | OpenRouter-powered streaming chat with four generation modes (Chat Compact, Chat Full, Website Builder, App Builder), image / PDF attachment support, and download-as-standalone-HTML. |
|
|
1028
1451
|
| `live-examples.html` | Catalog page that links every demo into the shared `live-example.html?example=<slug>` shell. |
|
|
1029
1452
|
| `live-example.html` | Shared shell for the bundled live examples — picks the demo from the `?example=<slug>` query parameter. |
|
|
@@ -1034,20 +1457,19 @@ consumes from the CDN.
|
|
|
1034
1457
|
|
|
1035
1458
|
Every standalone demo is served by a single shell page
|
|
1036
1459
|
(`docs/live-example.html`) and a single JS bundle
|
|
1037
|
-
(`docs/assets/live-example.js`) that ships every demo's
|
|
1460
|
+
(`docs/assets/live-example.js`) that ships every demo's Aktion source
|
|
1038
1461
|
and setup code together. Open any example with
|
|
1039
1462
|
`live-example.html?example=<slug>` — the shell renders the original
|
|
1040
1463
|
hero / source / output layout, so each demo doubles as an integration
|
|
1041
|
-
recipe for `setResponse`, `appendChunk`,
|
|
1464
|
+
recipe for `setResponse`, `appendChunk`, and `setTheme`.
|
|
1042
1465
|
|
|
1043
1466
|
| Demo slug | Highlights |
|
|
1044
1467
|
| ------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
1045
|
-
| `routing-demo` | A four-page app driven by `pages = _router_({ … })` + `NavLink`, deep links, browser back/forward. |
|
|
1046
1468
|
| `settings-app` | Tabs, `Switch`, `ToggleGroup`, `Progress`, `Kbd`, danger-zone confirmation `Drawer`. |
|
|
1047
1469
|
| `data-explorer` | Analytics surface: sortable `DataGrid` + bulk toolbar, `Gauge` SLA dials, `LineChart`, `Heatmap`, `RadarChart`, `ScatterChart`, `Histogram`, `InfiniteList`, `ActivityLog`. |
|
|
1048
1470
|
| `media-gallery` | Travel magazine: `Carousel` hero, `Gallery` + click-to-zoom `Lightbox`, `VideoPlayer`, `AudioPlayer`, Leaflet-backed `Map`. |
|
|
1049
1471
|
| `content-studio` | CMS-style authoring surface: `RichTextEditor`, `CodeEditor`, `MultiStepForm`, `ColorPicker`, `TagInput`, `MentionInput`, `PinInput`, `ValidationSummary`, `TopBar`. |
|
|
1050
|
-
| `brand-themes.html` | Same UI reskinned with
|
|
1472
|
+
| `brand-themes.html` | Same UI reskinned with `$theme({...})` for **GitHub**, **Apple**, **Stripe**, **IONOS**, **Notion**, **Vercel** (bespoke UI on its own page). |
|
|
1051
1473
|
|
|
1052
1474
|
The full catalog with tag filters lives at
|
|
1053
1475
|
[`docs/live-examples.html`](https://asfand-dev.github.io/aktion/live-examples.html).
|
|
@@ -1064,12 +1486,12 @@ The full catalog with tag filters lives at
|
|
|
1064
1486
|
│ │ ├── builtins.ts # pure @-function helpers
|
|
1065
1487
|
│ │ ├── evaluator.ts # program planner + binding resolver
|
|
1066
1488
|
│ │ ├── state.ts # reactive store — `$name = value`
|
|
1067
|
-
│ │ ├── effects.ts # EffectRunner + ActionDeclRunner
|
|
1068
|
-
│ │ ├── http.ts # http({...}) reactive HTTP primitive + interceptors
|
|
1069
|
-
│ │ ├── i18n.ts # $i18n
|
|
1070
|
-
│ │ ├── storage.ts # storage.local / .session / .cookies bridge
|
|
1489
|
+
│ │ ├── effects.ts # EffectRunner + ActionDeclRunner
|
|
1490
|
+
│ │ ├── http.ts # $http({...}) reactive HTTP primitive + interceptors
|
|
1491
|
+
│ │ ├── i18n.ts # $i18n({...}) factory — returns { t, setCurrentLanguage, getCurrentLanguage }
|
|
1492
|
+
│ │ ├── $storage.ts # $storage.local / .session / .cookies bridge
|
|
1071
1493
|
│ │ ├── console.ts # console.* host bridge
|
|
1072
|
-
│ │ └── router.ts # Hash-based router for
|
|
1494
|
+
│ │ └── router.ts # Hash-based router for $router({…}) calls and NavLink
|
|
1073
1495
|
│ ├── library/ # Component specs and registry
|
|
1074
1496
|
│ │ └── components/ # layout / content / forms / data / charts / chat /
|
|
1075
1497
|
│ │ # feedback / navigation / menu / patterns / helpers / router
|
|
@@ -1156,23 +1578,14 @@ script.
|
|
|
1156
1578
|
npm test
|
|
1157
1579
|
```
|
|
1158
1580
|
|
|
1159
|
-
The suite covers
|
|
1160
|
-
|
|
1161
|
-
-
|
|
1162
|
-
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
- Component library smoke tests (`tests/library.test.ts`).
|
|
1168
|
-
- Element-level integration via happy-dom (`tests/element.test.ts`).
|
|
1169
|
-
- System prompt generator output (`tests/prompt.test.ts`).
|
|
1170
|
-
- Storage + console globals (`tests/storage-console.test.ts`).
|
|
1171
|
-
- End-to-end programs (`tests/suis2-end-to-end.test.ts`).
|
|
1172
|
-
- Language support spec for editor / tooling integrations (`tests/language.test.ts`).
|
|
1173
|
-
- One-positional-max enforcement (`tests/suis2-one-positional.test.ts`).
|
|
1174
|
-
- Component prop aliases (`tests/suis2-prop-aliases.test.ts`).
|
|
1175
|
-
- Icon rendering (`tests/icons.test.ts`).
|
|
1581
|
+
The suite covers parser/lexer, runtime evaluator + reactive state +
|
|
1582
|
+
`$http({...})`, effects / actions, the hash-based router + `NavLink`,
|
|
1583
|
+
theme resolution, in-script `$theme(...)` overrides, the component
|
|
1584
|
+
library, element-level integration via happy-dom, the system prompt
|
|
1585
|
+
generator, storage / console globals, the language-support spec for
|
|
1586
|
+
editor tooling, prop aliases & one-positional-max enforcement, icon
|
|
1587
|
+
rendering, and language-concept coverage (computed values, math,
|
|
1588
|
+
lambdas, hoisting, i18n, `for` extensions, user components).
|
|
1176
1589
|
|
|
1177
1590
|
### Build the documentation site
|
|
1178
1591
|
|
|
@@ -1197,7 +1610,7 @@ Then open <http://localhost:4321/index.html>.
|
|
|
1197
1610
|
|
|
1198
1611
|
The library treats every LLM-supplied attribute as untrusted and runs
|
|
1199
1612
|
it through a small set of sanitisers before it lands on the DOM. HTTP
|
|
1200
|
-
requests issued by the LLM through
|
|
1613
|
+
requests issued by the LLM through `$http({...})` flow through your host's
|
|
1201
1614
|
`registerHttpInterceptors({ onRequest, onResponse, onError })` chain so
|
|
1202
1615
|
auth headers, CORS workarounds, and refresh-token retries stay under
|
|
1203
1616
|
host control.
|
|
@@ -1215,37 +1628,21 @@ renderer get `rel="noopener noreferrer"` so the destination cannot
|
|
|
1215
1628
|
read the opener's `document.referrer`.
|
|
1216
1629
|
|
|
1217
1630
|
If you embed `<aktion-app>` behind a CSP, the bundle does not
|
|
1218
|
-
use `eval`.
|
|
1219
|
-
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
1631
|
+
use `eval`. Effect and action bodies are evaluated with
|
|
1632
|
+
`new Function(...)` which requires `'unsafe-eval'` if you want them to
|
|
1633
|
+
run arbitrary JavaScript; if you cannot relax CSP, simply avoid emitting
|
|
1634
|
+
complex JS expressions from the LLM — declarative constructs (component
|
|
1635
|
+
trees, `$http()`, `@`-functions) keep working without `unsafe-eval`.
|
|
1223
1636
|
|
|
1224
1637
|
---
|
|
1225
1638
|
|
|
1226
1639
|
## CDN deployment
|
|
1227
1640
|
|
|
1228
|
-
This
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
<aktion-app theme="dark"></aktion-app>
|
|
1234
|
-
```
|
|
1235
|
-
|
|
1236
|
-
…plus a fetch of `system_prompt.txt` server-side to build LLM messages:
|
|
1237
|
-
|
|
1238
|
-
```bash
|
|
1239
|
-
curl https://asfand-dev.github.io/aktion/dist/system_prompt.txt
|
|
1240
|
-
```
|
|
1241
|
-
|
|
1242
|
-
To ship your own copy, run `npm run build` and serve the `dist/` folder
|
|
1243
|
-
from any static host — every artifact in `dist/` is self-contained.
|
|
1244
|
-
|
|
1245
|
-
GitHub Pages deployment for this repo is automated via
|
|
1246
|
-
[`.github/workflows/deploy-pages.yml`](.github/workflows/deploy-pages.yml).
|
|
1247
|
-
Push to `main` and the workflow will build, test, assemble `site/`, and
|
|
1248
|
-
publish.
|
|
1641
|
+
This repo serves its own bundle on GitHub Pages (see Quick start §1).
|
|
1642
|
+
To ship your own copy, run `npm run build` and serve `dist/` from any
|
|
1643
|
+
static host — every artifact in `dist/` is self-contained. Push to
|
|
1644
|
+
`main` and [`.github/workflows/deploy-pages.yml`](.github/workflows/deploy-pages.yml)
|
|
1645
|
+
builds, tests, and publishes.
|
|
1249
1646
|
|
|
1250
1647
|
---
|
|
1251
1648
|
|