aktion-runtime 0.5.0 → 0.5.2
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 +54 -17
- package/dist/aktion.iife.js +88 -46
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +1653 -1512
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +88 -46
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/system_prompt.txt +42 -0
- package/dist/types/renderer/renderer.d.ts +27 -1
- package/dist/types/runtime/effects.d.ts +23 -4
- package/dist/types/runtime/evaluator.d.ts +48 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -94,9 +94,12 @@ Everything you need at runtime ships in a single bundle:
|
|
|
94
94
|
work — anonymous blocks where the dependency list mixes state triggers
|
|
95
95
|
(`$atom`), lifecycle triggers (`on:mount`, `on:unmount`, `on:every(N)`),
|
|
96
96
|
and rate-limit modifiers (`debounce(N)`, `throttle(N)`). `effect { … }`
|
|
97
|
-
with an empty list is equivalent to `effect [on:mount] { … }`.
|
|
98
|
-
|
|
99
|
-
|
|
97
|
+
with an empty list is equivalent to `effect [on:mount] { … }`. Declare
|
|
98
|
+
an effect **at the top level** for program-wide work, or **inside a
|
|
99
|
+
`component { … }` body** to scope it to a single instance — timers,
|
|
100
|
+
watched atoms, and `cleanup(fn)` registrations tear down when the
|
|
101
|
+
component leaves the tree. `action Name(args) { … }` declares
|
|
102
|
+
click-driven mutations and may optionally `return` a value.
|
|
100
103
|
- **A built-in router.** `pages = _router_({ "/path": Component(), "/users/:id": UserPage(id: params.id), default: NotFound() })` plus
|
|
101
104
|
`NavLink(label, to)` and a reserved `_route_` handle that exposes
|
|
102
105
|
`_route_.path`, `_route_.params`, `_route_.query`, `_route_.pattern`,
|
|
@@ -147,26 +150,26 @@ For non-module setups (older bundlers, embedded contexts) use the IIFE build:
|
|
|
147
150
|
…or install from npm and import once from your client-side entry point:
|
|
148
151
|
|
|
149
152
|
```bash
|
|
150
|
-
npm install
|
|
151
|
-
# yarn add
|
|
152
|
-
# pnpm add
|
|
153
|
+
npm install aktion-runtime
|
|
154
|
+
# yarn add aktion-runtime
|
|
155
|
+
# pnpm add aktion-runtime
|
|
153
156
|
```
|
|
154
157
|
|
|
155
158
|
```js
|
|
156
|
-
import "
|
|
159
|
+
import "aktion-runtime";
|
|
157
160
|
```
|
|
158
161
|
|
|
159
162
|
The package is published as
|
|
160
|
-
[
|
|
163
|
+
[`aktion-runtime`](https://www.npmjs.com/package/aktion-runtime). The
|
|
161
164
|
npm tarball ships only the compiled `dist/` output (ESM + CJS + UMD +
|
|
162
165
|
IIFE bundles, type declarations, the stylesheet, and the two
|
|
163
166
|
`system_prompt*.txt` files), so installs stay small. Subpath imports
|
|
164
167
|
are available for convenience:
|
|
165
168
|
|
|
166
169
|
```js
|
|
167
|
-
import "
|
|
170
|
+
import "aktion-runtime/style.css";
|
|
168
171
|
const SYSTEM_PROMPT = await fetch(
|
|
169
|
-
new URL("
|
|
172
|
+
new URL("aktion-runtime/system_prompt.txt", import.meta.url),
|
|
170
173
|
).then((r) => r.text());
|
|
171
174
|
```
|
|
172
175
|
|
|
@@ -337,7 +340,7 @@ shell before the leaves arrive.
|
|
|
337
340
|
$count = 0
|
|
338
341
|
$theme = "dark"
|
|
339
342
|
|
|
340
|
-
component Counter(label
|
|
343
|
+
component Counter(label: "Count") {
|
|
341
344
|
return Stack([
|
|
342
345
|
SectionHeader(label),
|
|
343
346
|
Button("Inc", onClick: () => $count = $count + 1),
|
|
@@ -374,9 +377,12 @@ _app_ = pages
|
|
|
374
377
|
- `$name = value` — reactive state. One kind. Read or write with the
|
|
375
378
|
same sigil. Inside `action` / `effect` / lambda bodies, assignment
|
|
376
379
|
operators (`= += -= *= /= ??= ++ --`) are all allowed.
|
|
377
|
-
- `component Name(p
|
|
380
|
+
- `component Name(p: default) { return Expression }` — first-class
|
|
378
381
|
declarations with default expressions, lexical scope, and per-instance
|
|
379
|
-
state.
|
|
382
|
+
state. Inside the body, `$x = expr` is a **declaration**: the
|
|
383
|
+
initializer runs once when the instance first mounts, and re-renders
|
|
384
|
+
preserve whatever value the user (or an action / effect) has written.
|
|
385
|
+
**Always** end with an explicit `return`.
|
|
380
386
|
- `action Name(args) { body }` — callable effects with optional
|
|
381
387
|
`return`. Used as event handlers (`onClick: save`) or as expressions
|
|
382
388
|
(`$result = greet("Ada")`).
|
|
@@ -385,7 +391,11 @@ _app_ = pages
|
|
|
385
391
|
lifecycle / interval triggers (`on:mount`, `on:unmount`,
|
|
386
392
|
`on:every(N)`), and rate-limit modifiers (`debounce(N)`,
|
|
387
393
|
`throttle(N)`). `effect { ... }` (no brackets) is equivalent to
|
|
388
|
-
`effect [on:mount] { ... }`.
|
|
394
|
+
`effect [on:mount] { ... }`. Declare at the program top level for
|
|
395
|
+
global work, or inside a `component { … }` body to scope the effect
|
|
396
|
+
to that instance — the runtime mounts it on first render and tears
|
|
397
|
+
down its timers / subscriptions / `cleanup(fn)` handlers when the
|
|
398
|
+
instance leaves the tree.
|
|
389
399
|
- Expression-form control flow: `if cond { … } else { … }`,
|
|
390
400
|
`match expr { "a": A() default: Else() }`, `for x in xs { Row(x) }`.
|
|
391
401
|
Match and router arms use `:` and `default:` (not `->` / `_`).
|
|
@@ -489,6 +499,33 @@ component TaskRow(task) {
|
|
|
489
499
|
}
|
|
490
500
|
```
|
|
491
501
|
|
|
502
|
+
### Component-scoped effects
|
|
503
|
+
|
|
504
|
+
`effect [ ...deps ] { … }` blocks can live at the program top level
|
|
505
|
+
**or** inside a `component { … }` body. Inside a component body the
|
|
506
|
+
runtime mounts the effect when the instance first renders and tears it
|
|
507
|
+
down (clearing timers, unsubscribing watched atoms, firing every
|
|
508
|
+
registered `cleanup(fn)`) the moment the instance disappears from the
|
|
509
|
+
tree. Two `LiveClock()` calls produce two independent intervals — and
|
|
510
|
+
removing one stops only that one:
|
|
511
|
+
|
|
512
|
+
```text
|
|
513
|
+
_app_ = Stack([LiveClock("UTC"), LiveClock("Local")])
|
|
514
|
+
|
|
515
|
+
component LiveClock(label) {
|
|
516
|
+
$now = @Now()
|
|
517
|
+
effect [on:every(1000)] {
|
|
518
|
+
$now = @Now()
|
|
519
|
+
}
|
|
520
|
+
return Stack([Text(label), Text(@FormatDate($now, "time"))])
|
|
521
|
+
}
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
Use a top-level `effect [...] { … }` for global work (analytics,
|
|
525
|
+
app-wide keyboard shortcuts, hydration of shared atoms); use a
|
|
526
|
+
component-local effect whenever the background work logically belongs
|
|
527
|
+
to the UI it serves.
|
|
528
|
+
|
|
492
529
|
### Schema-as-truth diagnostics
|
|
493
530
|
|
|
494
531
|
`validateProgramSchema(program, library)` (exported from
|
|
@@ -947,7 +984,7 @@ import {
|
|
|
947
984
|
getDiagnostics, // merged parse + schema errors (LSP-ready)
|
|
948
985
|
getCompletions, // context-aware completions
|
|
949
986
|
getHoverInfo, // hover docs for symbols
|
|
950
|
-
} from "
|
|
987
|
+
} from "aktion-runtime";
|
|
951
988
|
```
|
|
952
989
|
|
|
953
990
|
- `formatProgram` projects the parsed AST back to canonical source —
|
|
@@ -981,7 +1018,7 @@ consumes from the CDN.
|
|
|
981
1018
|
| `language.html` | Full Aktion language reference. |
|
|
982
1019
|
| `components.html` | Every built-in component with a live preview, positional signatures, prop tables, and enum values. |
|
|
983
1020
|
| `actions.html` | `action Name() { … }` guide — declarative state mutations, optimistic snapshot/rollback, lambda-based click handlers, navigation, and end-to-end examples. |
|
|
984
|
-
| `side-effects.html` | `effect [ ...deps ] { … }` guide — anonymous side effects, dependency entries (state, lifecycle, intervals, debounce/throttle), cleanup, and effect vs. action. |
|
|
1021
|
+
| `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. |
|
|
985
1022
|
| `javascript-interactions.html` | `effect [ ...deps ] { js { … } }` + action `js{}` bodies — the JS escape hatch. |
|
|
986
1023
|
| `routing.html` | Hash-based routing guide — always available at runtime. |
|
|
987
1024
|
| `themes.html` | Built-in themes gallery, live picker, side-by-side compare, and the token customization studio. |
|
|
@@ -1098,7 +1135,7 @@ dist/system_prompt_chat.txt # Compact chat-focused prompt
|
|
|
1098
1135
|
|
|
1099
1136
|
### Publish to npm
|
|
1100
1137
|
|
|
1101
|
-
The package is published as
|
|
1138
|
+
The package is published as `aktion-runtime`. The `files` field
|
|
1102
1139
|
restricts the tarball to `dist/` only, and `prepublishOnly` runs the
|
|
1103
1140
|
full build, so a release is:
|
|
1104
1141
|
|