aktion-runtime 0.5.3 → 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 +119 -0
- package/dist/aktion.iife.js +34 -34
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +1823 -1644
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +34 -34
- 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/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 +36 -0
- 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 +10 -0
- package/dist/types/plugin/vite.d.ts +21 -0
- package/package.json +36 -5
package/README.md
CHANGED
|
@@ -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)
|
|
@@ -328,6 +329,7 @@ surfaces from the *generated prompt*, build it via
|
|
|
328
329
|
| `hydrateState(snapshot)` | Apply a snapshot to the live store and schedule a re-render. Atoms not in the snapshot are untouched. |
|
|
329
330
|
| `loadSnapshot({ programText, state })` | Atomic program + state load. The next render plans the program with the hydrated state already in place. |
|
|
330
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). |
|
|
331
333
|
|
|
332
334
|
### Events
|
|
333
335
|
|
|
@@ -1305,6 +1307,123 @@ import {
|
|
|
1305
1307
|
|
|
1306
1308
|
---
|
|
1307
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
|
+
|
|
1308
1427
|
## Documentation site
|
|
1309
1428
|
|
|
1310
1429
|
The `docs/` folder is the source for the live documentation site at
|