aktion-runtime 0.5.3 → 0.5.5
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 +126 -31
- package/dist/aktion.iife.js +106 -460
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +5688 -5055
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +106 -460
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/devtools.js +1367 -0
- package/dist/devtools.js.map +1 -0
- package/dist/language.js +15311 -0
- package/dist/language.js.map +1 -0
- package/dist/plugin.cjs +2650 -0
- package/dist/plugin.cjs.map +1 -0
- package/dist/plugin.js +2650 -0
- package/dist/plugin.js.map +1 -0
- package/dist/system_prompt.txt +164 -447
- package/dist/system_prompt_chat.txt +33 -84
- package/dist/testing.js +29496 -0
- package/dist/testing.js.map +1 -0
- package/dist/types/aktion-modules.d.ts +18 -0
- package/dist/types/compiler/index.d.ts +12 -0
- package/dist/types/compiler/linker.d.ts +27 -0
- package/dist/types/compiler/project.d.ts +45 -0
- package/dist/types/compiler/runtime.d.ts +59 -0
- package/dist/types/devtools/hook.d.ts +88 -0
- package/dist/types/devtools/index.d.ts +35 -0
- package/dist/types/devtools/panel.d.ts +109 -0
- package/dist/types/devtools/protocol.d.ts +130 -0
- package/dist/types/devtools/styles.d.ts +7 -0
- package/dist/types/element.d.ts +76 -8
- package/dist/types/index.d.ts +1 -0
- package/dist/types/language-api.d.ts +15 -0
- package/dist/types/parser/types.d.ts +38 -1
- package/dist/types/plugin/index.d.ts +17 -0
- package/dist/types/renderer/renderer.d.ts +28 -0
- package/dist/types/runtime/builtins.d.ts +5 -11
- package/dist/types/runtime/effects.d.ts +15 -0
- package/dist/types/runtime/http.d.ts +0 -1
- package/dist/types/testing/index.d.ts +201 -0
- package/dist/types/theme/index.d.ts +3 -3
- package/dist/types/theme/styles.d.ts +1 -1
- package/dist/types/tooling/formatter.d.ts +7 -1
- package/dist/types/tooling/index.d.ts +0 -3
- package/package.json +35 -2
- package/dist/types/library/components/theme.d.ts +0 -2
- package/dist/types/tooling/codemod.d.ts +0 -36
package/README.md
CHANGED
|
@@ -13,10 +13,10 @@ renderer for an LLM's response.
|
|
|
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
|
-
|
|
16
|
+
$app(Card([
|
|
17
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>
|
|
21
21
|
```
|
|
22
22
|
|
|
@@ -46,6 +46,7 @@ HTML, or no framework at all.
|
|
|
46
46
|
- [Internationalization (`$i18n`)](#internationalization)
|
|
47
47
|
- [System prompt generator](#system-prompt-generator)
|
|
48
48
|
- [Tooling](#tooling)
|
|
49
|
+
- [Build-time compiler & multi-file modules](#build-time-compiler--multi-file-modules)
|
|
49
50
|
- [Documentation site](#documentation-site)
|
|
50
51
|
- [Live examples](#live-examples)
|
|
51
52
|
- [Project layout](#project-layout)
|
|
@@ -130,8 +131,8 @@ Everything you need at runtime ships in a single bundle:
|
|
|
130
131
|
- **Seven built-in themes** (`light`, `dark`, `neon`, `pastel`, `glass`,
|
|
131
132
|
`brutalist`, `skyline`) plus full custom-token support via CSS custom
|
|
132
133
|
properties. **50+ design tokens** organised into `colors`, `radius`,
|
|
133
|
-
|
|
134
|
-
|
|
134
|
+
and `font` groups. Brand the UI from inside the script with
|
|
135
|
+
`$theme({...})` statement.
|
|
135
136
|
- **`$i18n` factory.** `const { t, setCurrentLanguage, getCurrentLanguage } = $i18n({ defaultLanguage, currentLanguage, translations })` builds a translation bundle keyed by language, with `{name}` placeholder interpolation.
|
|
136
137
|
- **Font Awesome 6.7.2** auto-loaded — every `icon` prop accepts a Free
|
|
137
138
|
Font Awesome name (no `fa-` prefix). Use `Icon(name, { variant?, size? })`
|
|
@@ -211,18 +212,18 @@ Three equivalent ways:
|
|
|
211
212
|
|
|
212
213
|
```html
|
|
213
214
|
<!-- as an attribute -->
|
|
214
|
-
<aktion-app response='
|
|
215
|
+
<aktion-app response='$app(Card([CardHeader("Hi")]))'></aktion-app>
|
|
215
216
|
|
|
216
217
|
<!-- as inner text (rendered on connect) -->
|
|
217
218
|
<aktion-app>
|
|
218
|
-
|
|
219
|
+
$app(Card([CardHeader("Hi")]))
|
|
219
220
|
</aktion-app>
|
|
220
221
|
|
|
221
222
|
<!-- as a property/method -->
|
|
222
223
|
<script>
|
|
223
224
|
const el = document.querySelector("aktion-app");
|
|
224
225
|
el.setResponse(`
|
|
225
|
-
|
|
226
|
+
$app(Column([greeting]))
|
|
226
227
|
greeting = Card([CardHeader("Hello", { subtitle: "Generative UI in plain HTML" })])
|
|
227
228
|
`);
|
|
228
229
|
</script>
|
|
@@ -406,13 +407,14 @@ pages = $router({
|
|
|
406
407
|
default: NotFound()
|
|
407
408
|
})
|
|
408
409
|
|
|
409
|
-
|
|
410
|
+
$app(pages)
|
|
410
411
|
```
|
|
411
412
|
|
|
412
413
|
### Key constructs
|
|
413
414
|
|
|
414
|
-
- `
|
|
415
|
-
it.
|
|
415
|
+
- `$app(…)` — the reserved entry point. Every program renders from
|
|
416
|
+
it. It accepts a single root node, an array of nodes (rendered as
|
|
417
|
+
siblings), or variadic nodes.
|
|
416
418
|
- `$name = value` — reactive state. One kind. Read or write with the
|
|
417
419
|
same sigil. Inside action / effect / lambda bodies, assignment
|
|
418
420
|
operators (`= += -= *= /= ??= ++ --`) are all allowed.
|
|
@@ -536,7 +538,7 @@ aktion = pages
|
|
|
536
538
|
shadow root. Use only when the standard component library cannot
|
|
537
539
|
express the design.
|
|
538
540
|
- **Hoisting & streaming** — references resolve from the entire
|
|
539
|
-
top-level scope, not source order. Always
|
|
541
|
+
top-level scope, not source order. Always call `$app(…)` first
|
|
540
542
|
so the reconciler has the page shell to attach streamed leaves to.
|
|
541
543
|
- Comments: `//` line comments and `/* block */` comments — standard
|
|
542
544
|
JS style.
|
|
@@ -576,7 +578,7 @@ chart = LineChart({
|
|
|
576
578
|
series: [Series("Events", $data.data?.daily?.events ?? [])]
|
|
577
579
|
})
|
|
578
580
|
|
|
579
|
-
|
|
581
|
+
$app(Column([CardHeader("Analytics"), filter, kpi, chart]))
|
|
580
582
|
```
|
|
581
583
|
|
|
582
584
|
Highlights:
|
|
@@ -591,7 +593,7 @@ Highlights:
|
|
|
591
593
|
plus pluck (`$rows.title` → `[title1, title2, …]`).
|
|
592
594
|
- Responsive prop maps on layout components:
|
|
593
595
|
`Grid(items, { columns: { sm: 1, md: 2, lg: 4 }, gap: "l" })`.
|
|
594
|
-
- Forward references are allowed —
|
|
596
|
+
- Forward references are allowed — call `$app(Column([...]))` first
|
|
595
597
|
and let the children stream in beneath it.
|
|
596
598
|
|
|
597
599
|
### Declarative todo app
|
|
@@ -615,11 +617,11 @@ row = t => Card([Stack([
|
|
|
615
617
|
])])
|
|
616
618
|
|
|
617
619
|
list = $todos.map(t => row(t))
|
|
618
|
-
|
|
620
|
+
$app(Stack([
|
|
619
621
|
Input("draft-input", { placeholder: "What needs doing?", value: $draft }),
|
|
620
622
|
Button("Add", { onClick: add, variant: "primary" }),
|
|
621
623
|
list
|
|
622
|
-
])
|
|
624
|
+
]))
|
|
623
625
|
```
|
|
624
626
|
|
|
625
627
|
### Fine-grained reactivity
|
|
@@ -704,7 +706,7 @@ function Counter(label) {
|
|
|
704
706
|
}
|
|
705
707
|
|
|
706
708
|
// Two independent counters — each holds its own atom.
|
|
707
|
-
|
|
709
|
+
$app(Stack([Counter("A"), Counter("B")]))
|
|
708
710
|
```
|
|
709
711
|
|
|
710
712
|
Every call site accepts a universal `key` named argument. The renderer
|
|
@@ -734,7 +736,7 @@ function Counter() {
|
|
|
734
736
|
])
|
|
735
737
|
}
|
|
736
738
|
|
|
737
|
-
|
|
739
|
+
$app(Counter())
|
|
738
740
|
```
|
|
739
741
|
|
|
740
742
|
- `$state(initial)` returns a `[value, setValue]` pair. `setValue(next)`
|
|
@@ -791,7 +793,7 @@ cart = $store({
|
|
|
791
793
|
// Siblings with no relationship both talk to the same cart.
|
|
792
794
|
function AddLatte() { return Button("Add", { onClick: () => cart.add({ price: 4.5 }) }) }
|
|
793
795
|
function MiniCart() { return Text(`${cart.count()} items — ${$util.format(cart.total(), "currency")}`) }
|
|
794
|
-
|
|
796
|
+
$app(Column([AddLatte(), MiniCart()]))
|
|
795
797
|
```
|
|
796
798
|
|
|
797
799
|
Reads are fine-grained and per-component (changing `cart.items` re-renders
|
|
@@ -811,7 +813,7 @@ tree. Two `LiveClock()` calls produce two independent intervals — and
|
|
|
811
813
|
removing one stops only that one:
|
|
812
814
|
|
|
813
815
|
```js
|
|
814
|
-
|
|
816
|
+
$app(Stack([LiveClock("UTC"), LiveClock("Local")]))
|
|
815
817
|
|
|
816
818
|
function LiveClock(label) {
|
|
817
819
|
$now = $util.now()
|
|
@@ -952,7 +954,7 @@ board = KanbanBoard([
|
|
|
952
954
|
])
|
|
953
955
|
follow = FollowUpBlock(["Show at-risk projects", "Compare to Q2", "Who needs help?"])
|
|
954
956
|
|
|
955
|
-
|
|
957
|
+
$app(Column([dashHeader, kpis, board, follow]))
|
|
956
958
|
```
|
|
957
959
|
|
|
958
960
|
### Adding your own components
|
|
@@ -1024,12 +1026,11 @@ el.setTheme({
|
|
|
1024
1026
|
|
|
1025
1027
|
### `$theme({...})` from inside a response
|
|
1026
1028
|
|
|
1027
|
-
A response can brand itself
|
|
1028
|
-
|
|
1029
|
-
variables on top of the base theme.
|
|
1029
|
+
A response can brand itself with a `$theme({...})` statement. The tokens land on the host as CSS variables on top
|
|
1030
|
+
of the base theme.
|
|
1030
1031
|
|
|
1031
1032
|
```js
|
|
1032
|
-
|
|
1033
|
+
$theme({
|
|
1033
1034
|
colors: {
|
|
1034
1035
|
primary: "#0969da",
|
|
1035
1036
|
border: "#d0d7de",
|
|
@@ -1043,12 +1044,12 @@ theme = $theme({
|
|
|
1043
1044
|
radius: { button: "6px", input: "6px" }
|
|
1044
1045
|
})
|
|
1045
1046
|
|
|
1046
|
-
|
|
1047
|
+
$app(Column([CardHeader("GitHub-style page"), Buttons([Button("New repository")])]))
|
|
1047
1048
|
```
|
|
1048
1049
|
|
|
1049
1050
|
`$theme` expects the **structured** form — top-level groups `colors` /
|
|
1050
|
-
`radius` / `font`
|
|
1051
|
-
|
|
1051
|
+
`radius` / `font` (plus metadata keys `name` and `direction`). Removing
|
|
1052
|
+
the `$theme(...)` line snaps the UI back to
|
|
1052
1053
|
the base theme. Unknown keys are ignored silently, so typos in an
|
|
1053
1054
|
LLM-emitted token map can never break the page.
|
|
1054
1055
|
|
|
@@ -1102,7 +1103,7 @@ kpis = Stats([
|
|
|
1102
1103
|
StatCard("Orders", { value: "1,284", trend: "up", delta: "+8%", icon: "cart-shopping" }),
|
|
1103
1104
|
StatCard("Refunds", { value: "12", trend: "down", delta: "-3", icon: "rotate-left" })
|
|
1104
1105
|
])
|
|
1105
|
-
|
|
1106
|
+
$app(Stack([brandIcon, kpis, profileTab]))
|
|
1106
1107
|
```
|
|
1107
1108
|
|
|
1108
1109
|
---
|
|
@@ -1128,7 +1129,7 @@ nav = Row([
|
|
|
1128
1129
|
NavLink("Users", { to: "/users" })
|
|
1129
1130
|
], { gap: "s" })
|
|
1130
1131
|
|
|
1131
|
-
|
|
1132
|
+
$app(Stack([nav, pages]))
|
|
1132
1133
|
|
|
1133
1134
|
homePage = Card([CardHeader("Welcome")])
|
|
1134
1135
|
dashboardPage = Card([CardHeader("Dashboard")])
|
|
@@ -1231,10 +1232,10 @@ const i18nInstance = $i18n({
|
|
|
1231
1232
|
currentLanguage: $lang,
|
|
1232
1233
|
translations: { hi: { en: "Hi", fr: "Salut", de: "Hallo" } }
|
|
1233
1234
|
})
|
|
1234
|
-
|
|
1235
|
+
$app(Column([
|
|
1235
1236
|
Text(i18nInstance.t("hi")),
|
|
1236
1237
|
Button("Deutsch", { onClick: () => { $lang = "de" } })
|
|
1237
|
-
])
|
|
1238
|
+
]))
|
|
1238
1239
|
```
|
|
1239
1240
|
|
|
1240
1241
|
---
|
|
@@ -1305,6 +1306,100 @@ import {
|
|
|
1305
1306
|
|
|
1306
1307
|
---
|
|
1307
1308
|
|
|
1309
|
+
## Build-time compiler & multi-file modules
|
|
1310
|
+
|
|
1311
|
+
> **Optional.** The CDN bundle and the streamed-string path
|
|
1312
|
+
> (`<aktion-app response="...">`, `setResponse`, `appendChunk`) work exactly as
|
|
1313
|
+
> before. This is an opt-in enhancement for NPM consumers who author UI by hand.
|
|
1314
|
+
|
|
1315
|
+
Author UI in `.aktion` files that `import`/`export` from one another like JS/TS
|
|
1316
|
+
modules, then mount the pre-parsed, linked program with
|
|
1317
|
+
`el.mountCompiled(program)` — the runtime parser never runs in the browser. The
|
|
1318
|
+
runtime stays fully reactive (`$state`, `$http`, effects, routing run as usual);
|
|
1319
|
+
only parsing + linking move ahead of time.
|
|
1320
|
+
|
|
1321
|
+
### Multi-file modules
|
|
1322
|
+
|
|
1323
|
+
Named `import`/`export` with **true module scope** — a file's non-exported
|
|
1324
|
+
top-level names are private:
|
|
1325
|
+
|
|
1326
|
+
```js
|
|
1327
|
+
// src/components/counter.aktion
|
|
1328
|
+
export $count = 0
|
|
1329
|
+
export function Counter() { return Button(`Clicked ${$count}`, { action: bump }) }
|
|
1330
|
+
function bump() { $count = $count + 1 } // private to this module
|
|
1331
|
+
|
|
1332
|
+
// src/app.aktion (entry — must define `aktion`)
|
|
1333
|
+
import { Counter, $count } from "./components/counter.aktion"
|
|
1334
|
+
aktion = Column([Markdown(`Shared count: ${$count}`), Counter()])
|
|
1335
|
+
```
|
|
1336
|
+
|
|
1337
|
+
The linker merges the graph into one program, renaming each module's private
|
|
1338
|
+
names so two files can reuse a name without clashing; the entry keeps its own
|
|
1339
|
+
names canonical (the `aktion` binding + the `$state` names that `serializeState`
|
|
1340
|
+
/ `applyDelta` target).
|
|
1341
|
+
|
|
1342
|
+
### Vite plugin
|
|
1343
|
+
|
|
1344
|
+
The `aktion-runtime/vite` plugin compiles `.aktion` files at build time so you
|
|
1345
|
+
can import them directly, with HMR that preserves live `$state`:
|
|
1346
|
+
|
|
1347
|
+
```ts
|
|
1348
|
+
// vite.config.ts
|
|
1349
|
+
import aktion from "aktion-runtime/vite";
|
|
1350
|
+
export default { plugins: [aktion()] };
|
|
1351
|
+
```
|
|
1352
|
+
|
|
1353
|
+
```jsonc
|
|
1354
|
+
// tsconfig.json — resolve `import app from "./app.aktion"`
|
|
1355
|
+
{ "compilerOptions": { "types": ["aktion-runtime/aktion-modules"] } }
|
|
1356
|
+
```
|
|
1357
|
+
|
|
1358
|
+
```ts
|
|
1359
|
+
import "aktion-runtime";
|
|
1360
|
+
import app from "./app.aktion"; // a typed CompiledProgram (the linked graph)
|
|
1361
|
+
document.querySelector("aktion-app").mountCompiled(app);
|
|
1362
|
+
```
|
|
1363
|
+
|
|
1364
|
+
Scaffold a ready-made Vite + TypeScript project with **`npm create aktion@latest`**
|
|
1365
|
+
(see [`create-aktion`](./create-aktion/)). A runnable example lives in
|
|
1366
|
+
[`examples/vite-compiler/`](./examples/vite-compiler/).
|
|
1367
|
+
|
|
1368
|
+
### Link in the browser (no bundler)
|
|
1369
|
+
|
|
1370
|
+
The linker is browser-safe and re-exported from the package root, so a host (or
|
|
1371
|
+
the playground) can link a project in-page from raw sources:
|
|
1372
|
+
|
|
1373
|
+
```ts
|
|
1374
|
+
import { linkProject, defineCompiledProgram } from "aktion-runtime";
|
|
1375
|
+
const { program, source } = await linkProject({
|
|
1376
|
+
entry: "app.aktion",
|
|
1377
|
+
files: { "app.aktion": "…", "components/counter.aktion": "…" },
|
|
1378
|
+
});
|
|
1379
|
+
el.mountCompiled(defineCompiledProgram({ __aktionCompiled: 1, program, source, path: "app.aktion" }));
|
|
1380
|
+
```
|
|
1381
|
+
|
|
1382
|
+
### Editor support
|
|
1383
|
+
|
|
1384
|
+
The [Aktion VS Code extension](./editors/vscode/) treats `.aktion` as
|
|
1385
|
+
TypeScript (highlighting) and adds inline diagnostics, hover, completions, and
|
|
1386
|
+
snippets via the DOM-free `aktion-runtime/language` API. Its README covers local
|
|
1387
|
+
F5 debugging **and** publishing to the VS Code Marketplace + Open VSX.
|
|
1388
|
+
|
|
1389
|
+
### Package entry points
|
|
1390
|
+
|
|
1391
|
+
| Import | Runs in | Purpose |
|
|
1392
|
+
| ------------------------------- | ------- | --------------------------------------------------------------------------- |
|
|
1393
|
+
| `aktion-runtime` | browser | `<aktion-app>` + `mountCompiled` + the browser-safe linker (`linkProject`) |
|
|
1394
|
+
| `aktion-runtime/vite` | Node | the Vite/Rollup plugin (`aktion()`) |
|
|
1395
|
+
| `aktion-runtime/language` | Node | DOM-free diagnostics / hover / completions / snippets (editors, LSP) |
|
|
1396
|
+
| `aktion-runtime/aktion-modules` | types | ambient `*.aktion` module declarations |
|
|
1397
|
+
|
|
1398
|
+
The plugin + language service ship as separate entries and never enter the
|
|
1399
|
+
browser bundle, so `dist/aktion.js` is unchanged.
|
|
1400
|
+
|
|
1401
|
+
---
|
|
1402
|
+
|
|
1308
1403
|
## Documentation site
|
|
1309
1404
|
|
|
1310
1405
|
The `docs/` folder is the source for the live documentation site at
|