aktion-runtime 0.5.5 → 0.5.7
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 +120 -15
- package/dist/aktion.iife.js +42 -42
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +12655 -12123
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +42 -42
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/language.js +1348 -98
- package/dist/language.js.map +1 -1
- package/dist/plugin.cjs +12 -2
- package/dist/plugin.cjs.map +1 -1
- package/dist/plugin.js +12 -2
- package/dist/plugin.js.map +1 -1
- package/dist/system_prompt.txt +40 -8
- package/dist/system_prompt_chat.txt +2 -1
- package/dist/testing.js +15415 -14698
- package/dist/testing.js.map +1 -1
- package/dist/types/element.d.ts +0 -1
- package/dist/types/language/builtins.d.ts +52 -0
- package/dist/types/language/index.d.ts +5 -2
- package/dist/types/language-api.d.ts +5 -1
- package/dist/types/library/components/helpers.d.ts +0 -5
- package/dist/types/library/components/wrappers.d.ts +1 -0
- package/dist/types/parser/types.d.ts +0 -1
- package/dist/types/runtime/effects.d.ts +1 -18
- package/dist/types/runtime/evaluator.d.ts +46 -5
- package/dist/types/runtime/http.d.ts +41 -0
- package/dist/types/runtime/index.d.ts +2 -1
- package/dist/types/runtime/router.d.ts +28 -2
- package/dist/types/runtime/toast.d.ts +45 -0
- package/dist/types/runtime/util.d.ts +11 -1
- package/dist/types/tooling/index.d.ts +6 -0
- package/dist/types/tooling/language-service.d.ts +10 -5
- package/dist/types/tooling/navigation.d.ts +91 -0
- package/dist/types/tooling/semantic-tokens.d.ts +24 -0
- package/dist/types/tooling/signature-help.d.ts +21 -0
- package/package.json +1 -1
package/dist/system_prompt.txt
CHANGED
|
@@ -101,6 +101,9 @@ Subscriptions track the exact **path** you read. Reading `$user.name` subscribes
|
|
|
101
101
|
For composable local state, use hooks — a function whose name starts with `$`, called only at the top level of a component (or another hook) in a stable order:
|
|
102
102
|
- `$state(initial)` → `[value, setValue]` (like `useState`; `setValue(prev => next)` supported, `initial` runs once).
|
|
103
103
|
- `$memo(() => value, [deps])` → a cached value (like `useMemo`).
|
|
104
|
+
- `$ref(initial)` → a stable `{ current }` box (like `useRef`; writing `.current` does NOT re-render — for DOM nodes, timer ids, previous values).
|
|
105
|
+
- `$reducer((state, action) => next, initial)` → `[state, dispatch]` (like `useReducer`; the clean way to manage many related transitions).
|
|
106
|
+
- `$id(prefix?)` → a stable unique id per instance (like `useId`; for `for`/`aria-*` wiring).
|
|
104
107
|
- `function $name(...)` declares a custom hook composing the built-ins.
|
|
105
108
|
|
|
106
109
|
```
|
|
@@ -157,7 +160,7 @@ $app(Column([UserCard($currentUser), UserCard($other, { tone: "primary" })]))
|
|
|
157
160
|
- Use a lambda (`row = item => Row(item)`) for one-off helpers that don't need a named component.
|
|
158
161
|
|
|
159
162
|
### Actions
|
|
160
|
-
A `function` whose body runs for side effects is an action — use it as a handler (`onClick: save`) or call it for its result. `return` is optional; the full JS statement surface applies.
|
|
163
|
+
A `function` whose body runs for side effects is an action — use it as a handler (`onClick: save`) or call it for its result. `return` is optional; the full JS statement surface applies. Wrap optimistic writes in `$optimistic(() => { … })` to snapshot state and auto-roll-back if the callback throws (or its promise rejects).
|
|
161
164
|
|
|
162
165
|
```
|
|
163
166
|
function save(item) {
|
|
@@ -165,6 +168,12 @@ function save(item) {
|
|
|
165
168
|
$save = $http({ url: "https://api.example.com/save", method: "POST", body: { item } })
|
|
166
169
|
$emit("saved", { id: item.id })
|
|
167
170
|
}
|
|
171
|
+
function addTodo(text) {
|
|
172
|
+
$optimistic(() => {
|
|
173
|
+
$todos = [...$todos, { id: $todos.length + 1, text }] // optimistic write
|
|
174
|
+
if (text == "") throw new Error("empty") // → rolls $todos back
|
|
175
|
+
})
|
|
176
|
+
}
|
|
168
177
|
saveBtn = Button("Save", { onClick: save })
|
|
169
178
|
resetBtn = Button("Reset", { onClick: () => { $count = 0; $message = "" } })
|
|
170
179
|
```
|
|
@@ -224,6 +233,18 @@ view = Async($orders, {
|
|
|
224
233
|
})
|
|
225
234
|
```
|
|
226
235
|
|
|
236
|
+
### `$query({...})` and `$mutation({...})`
|
|
237
|
+
Same config shape as `$http`, for two common needs:
|
|
238
|
+
- `$query({ url, key?, ttl? })` — a **cached, deduplicated** read. Identical queries (same `key`, or same method+url+query+body) share one in-flight request and one cached bag, so calling it from several components fetches once. Pass `ttl` (ms) to auto-refetch stale data. Same bag as `$http` (`.data`/`.loading`/`.error`/`.refetch()`).
|
|
239
|
+
- `$mutation({ url, method? })` — a **deferred** write that fires only when you call `.mutate(overrides?)`, not on render (method defaults to `POST`). Assign it to an atom, then trigger it from a handler:
|
|
240
|
+
```
|
|
241
|
+
$save = $mutation({ url: "https://api.example.com/orders" })
|
|
242
|
+
$save.onDone = () => $orders.refetch()
|
|
243
|
+
...
|
|
244
|
+
Button("Save", { onClick: () => $save.mutate({ body: { item: $item } }) })
|
|
245
|
+
```
|
|
246
|
+
`.mutate()` resolves with the response body; the bag exposes `.loading`/`.error`/`.data` plus `.reset()`.
|
|
247
|
+
|
|
227
248
|
## Routing
|
|
228
249
|
|
|
229
250
|
`$router({ ... })` is a plain function call — assign it and drop the result into your page shell.
|
|
@@ -243,7 +264,7 @@ $app(AppShell(MainSidebar(), pages)) // app/dashboard shell
|
|
|
243
264
|
- The read-only `route` handle: `route.path`, `route.params.x`, `route.query.tab`; navigate with `route.navigate("/path")` from an action/effect.
|
|
244
265
|
- `NavLink(label, { to, exact?, icon? })` and `SidebarItem(label, { to, icon?, badge? })` derive active state from `route.path`. Never declare `route` yourself.
|
|
245
266
|
|
|
246
|
-
## Built-in globals — `storage` & `
|
|
267
|
+
## Built-in globals — `storage`, `console` & `$toast`
|
|
247
268
|
|
|
248
269
|
Always in scope, lowercase, no imports.
|
|
249
270
|
|
|
@@ -257,10 +278,18 @@ $console.log("Hello", $user)
|
|
|
257
278
|
Non-string values JSON-roundtrip; missing keys return `null`. Beyond these, every JavaScript global resolves by name — `Math`, `JSON`, `Date`, `crypto`, `fetch`, `URL`, `navigator`, `window`, `document`, dialogs like `confirm`, … — and your declarations and components shadow same-named globals. Prefer reactive `$http({...})` over raw `fetch` for UI data, and keep timers/listeners inside `$effect` so they're cleaned up.
|
|
258
279
|
|
|
259
280
|
```
|
|
260
|
-
function copyLink() { navigator.clipboard.writeText(window.location.href); $toast
|
|
281
|
+
function copyLink() { navigator.clipboard.writeText(window.location.href); $toast.show("Copied", { tone: "success" }) }
|
|
261
282
|
id = crypto.randomUUID()
|
|
262
283
|
```
|
|
263
284
|
|
|
285
|
+
### `$toast` — imperative notifications
|
|
286
|
+
Instead of hand-managing a `$toasts = [...]` array, use the reserved `$toast` namespace. `$toast.show(message, { tone?, title?, duration? })` appends a toast (auto-dismisses after `duration` ms, default 4000; pass `0` to keep it). Shortcuts: `$toast.success/.error/.info/.warning`. Remove with `$toast.dismiss(id)` / `$toast.clear()`. Render the reactive `$toast.items` list:
|
|
287
|
+
|
|
288
|
+
```
|
|
289
|
+
function save() { $save = $http({ url, method: "POST", body }); $save.onDone = () => $toast.success("Saved") }
|
|
290
|
+
toaster = Toasts(map($toast.items, t => Toast({ title: t.title, message: t.message, tone: t.tone, onClose: () => $toast.dismiss(t.id) })))
|
|
291
|
+
```
|
|
292
|
+
|
|
264
293
|
## Behaviour wrappers
|
|
265
294
|
|
|
266
295
|
These attach behaviour or styling to ANY node via `display: contents` (the visual tree is unchanged):
|
|
@@ -268,6 +297,7 @@ These attach behaviour or styling to ANY node via `display: contents` (the visua
|
|
|
268
297
|
- `OnMouse(child, { enter?, leave?, move?, down?, up?, drag?, drop?, dragOver?, ... })` — pass only the events you need.
|
|
269
298
|
- `OnKeyboard(child, { onKeyDown?, onKeyUp?, focusable? })` and `OnFocus(child, { onFocus?, onBlur? })`.
|
|
270
299
|
- `OnIntersect(child, { onEnter?, onLeave?, threshold?, once? })` — IntersectionObserver (lazy-load, infinite scroll).
|
|
300
|
+
- `OnMount(child, { onMount?, onUnmount? })` — DOM-ref / lifecycle. `onMount(node)` fires once after attach (grab a node, focus it, hand it to a chart/map/editor); `onUnmount(node)` on teardown. Stash the node in a `$ref(...)`.
|
|
271
301
|
- `Css(child, { class?, style? })` — last-resort class/style merge.
|
|
272
302
|
- `Link(childOrLabel, { to?, href?, external?, variant? })` — anchor; `to` for router nav, `href`+`external: true` for outbound links.
|
|
273
303
|
|
|
@@ -321,7 +351,8 @@ Icon props take a Font Awesome name (no `fa-` prefix, never an emoji): `"house"`
|
|
|
321
351
|
|
|
322
352
|
Pure helpers (no side effects), available in every expression, action, effect, and lambda. Reach for `$util` when plain JS would be verbose (formatting, dates, grouping); use plain JS when it's just as clear (`arr.length`, `arr.slice(0, 5)`).
|
|
323
353
|
|
|
324
|
-
- **Collections**: `$util.sort(arr, field, dir?)`, `$util.groupBy(arr, field)`, `$util.unique(arr, field?)`, `$util.sum / .avg / .min / .max / .count`, `.first / .last`, `.filter(arr, field, op, value)`, `.find`, `.
|
|
354
|
+
- **Collections**: `$util.sort(arr, field, dir?)`, `$util.groupBy(arr, field)`, `$util.unique(arr, field?)`, `$util.sum / .avg / .min / .max / .count`, `.first / .last`, `.filter(arr, field, op, value)`, `.find`, `.partition(arr, field, op, value)`, `.keyBy(arr, field)`, `.chunk(arr, size)`, `.flatten(arr, depth?)`, `.zip(...arrays)`, `.range(start, end, step?)`.
|
|
355
|
+
- **Objects**: `$util.pick(obj, keys)`, `.omit(obj, keys)`, `.merge(target, ...sources)` (deep), `.cloneDeep(value)`.
|
|
325
356
|
- **Strings**: `$util.capitalize / .titlecase / .uppercase / .lowercase`, `.plural(n, singular, plural)`, `.trim / .replace / .split / .match`.
|
|
326
357
|
- **Formatting**: `$util.format(value, mode, opts?)` (number, currency, percent, compact) and `$util.formatDate(value, mode)` (`"short" | "long" | "time" | "relative"` or a token string).
|
|
327
358
|
- **Dates / math**: `.now / .today / .addDays / .diffDays / .startOfWeek`; `.round / .floor / .ceil / .abs / .clamp(v, min, max) / .random`.
|
|
@@ -339,7 +370,7 @@ summary = `${rows.length} ${$util.plural(rows.length, "order", "orders")} · ${$
|
|
|
339
370
|
| `Show(when, { fallback?, children })` | Sugar for `when ? children : fallback`. |
|
|
340
371
|
| `Portal(children, { target? })` | Render outside the parent subtree. |
|
|
341
372
|
| `Redirect(path)` | Navigate and unmount the rest of the subtree. |
|
|
342
|
-
| `Lazy(loader, { fallback?, children })` | Defer rendering until `loader` resolves. |
|
|
373
|
+
| `Lazy(loader, { fallback?, children })` | Defer rendering until the async `loader` resolves; show `fallback` while pending. |
|
|
343
374
|
| `ErrorBoundary(children, { fallback?, onError? })` | Catch render errors thrown by descendants. |
|
|
344
375
|
| `VirtualList(items, { key, render })` | Virtualised list — preferred for >100 rows. |
|
|
345
376
|
|
|
@@ -369,7 +400,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
369
400
|
- TabItem(value: string, label: string, children: Node[], badge?: string, icon?: string) — Single tab definition (used inside Tabs). Add `badge` for a count chip in the tab trigger, and `icon` for a leading Font Awesome icon.
|
|
370
401
|
- Accordion(items: AccordionItem[], showArrow?: boolean) — Accordion container. Children must be AccordionItem components. Set `showArrow: true` to add a chevron indicator to every item; individual `AccordionItem`s can override via their own `showArrow` prop.
|
|
371
402
|
- AccordionItem(title: string, children: Node[], open?: boolean, showArrow?: boolean) — Single accordion section.
|
|
372
|
-
- Modal(title: string, open: boolean, children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", footer?: Node[], closable?: boolean, closeOnBackdrop?: boolean, onClose?: callable) — Dialog overlay shown when `open` is true. Pass a `$variable` as `open` to control it. The header always renders a × close button (disable via `closable: false`); the optional `footer` slot is the canonical place for action buttons. `closeOnBackdrop=true` opts in to backdrop-click dismissal. `onClose` fires every time the modal closes (× button, backdrop, programmatic state write).
|
|
403
|
+
- Modal(title: string, open: boolean, children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", footer?: Node[], closable?: boolean, closeOnBackdrop?: boolean, onClose?: callable) — Dialog overlay shown when `open` is true. Pass a `$variable` as `open` to control it. The header always renders a × close button (disable via `closable: false`); the optional `footer` slot is the canonical place for action buttons. `closeOnBackdrop=true` opts in to backdrop-click dismissal. `onClose` fires every time the modal closes (× button, backdrop, programmatic state write). Accessible by default: the dialog is labelled by its title, focus moves into it on open and is restored on close, Tab is trapped inside, and Escape closes it (unless `closable: false`).
|
|
373
404
|
- Drawer(title: string, open: boolean, children: Node[], side?: "right"|"left"|"top"|"bottom", footer?: Node[], onClose?: callable) — Side drawer overlay shown when `open` is true. Pass a `$variable` as `open` to control it. Choose `side` for slide direction (default right). `onClose` fires whenever the drawer is dismissed (× button or backdrop click).
|
|
374
405
|
- Steps(items: object[]) — Numbered step-by-step guide. Pass items as `{title, details?, active?}` objects. Use `active` to mark the current step in a multi-step flow.
|
|
375
406
|
- AspectRatio(ratio: string, children: Node[]) — Container that constrains its child to a fixed aspect ratio (e.g. 16:9 for video embeds, 1:1 for thumbnails). The child fills the box.
|
|
@@ -553,14 +584,14 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
553
584
|
- NotificationBell(count?: number, items?: any[], onOpen?: callable) — Bell icon with unread count badge and dropdown notification list.
|
|
554
585
|
|
|
555
586
|
### Routing
|
|
556
|
-
- NavLink(label: string, to: string, variant?: "default"|"primary"|"ghost"|"pill", exact?: boolean, icon?: string) — Anchor that navigates to a route on click and stays in sync with the URL hash. Reflects `data-active="true"` when the current path matches `to` (set `exact=true` to require exact equality instead of prefix matching).
|
|
587
|
+
- NavLink(label: string, to: string, variant?: "default"|"primary"|"ghost"|"pill", exact?: boolean, icon?: string) — Anchor that navigates to a route on click and stays in sync with the URL hash. Reflects `data-active="true"` (and `aria-current="page"` for assistive tech) when the current path matches `to` (set `exact=true` to require exact equality instead of prefix matching).
|
|
557
588
|
|
|
558
589
|
### Helpers
|
|
559
590
|
- Async(resource: any (positional), loading?: Node, error?: Node, empty?: Node, data?: Node) — Render `loading`, `error`, `empty`, or `data` slot based on an `$http({...})` resource's state.
|
|
560
591
|
- Show(when: any (positional), fallback?: Node, children?: Node[]) — Conditional renderer. Sugar over `if expr { children } else { fallback }`.
|
|
561
592
|
- Portal(target?: string, children: Node[] (positional)) — Render children outside the parent subtree (e.g. into document.body).
|
|
562
593
|
- Redirect(path: string (positional)) — Navigate to `path` and unmount the rest of the subtree.
|
|
563
|
-
- Lazy(loader: any (positional), fallback?: Node, children?: Node[]) — Defer rendering `
|
|
594
|
+
- Lazy(loader: any (positional), fallback?: Node, children?: Node[]) — Defer rendering until an async `loader` resolves: show `fallback` while pending, then render the resolved value (or `children`). A synchronous loader value renders immediately.
|
|
564
595
|
- ErrorBoundary(fallback?: Node, onError?: callable, children: Node[] (positional)) — Render a fallback subtree when rendering children throws.
|
|
565
596
|
|
|
566
597
|
### Behaviour wrappers
|
|
@@ -569,6 +600,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
569
600
|
- OnKeyboard(child: Node (positional), onKeyDown?: callable, onKeyUp?: callable, onKeyPress?: callable, focusable?: boolean) — Attach keyboard listeners to a component. Pass any combination of `onKeyDown`, `onKeyUp`, and `onKeyPress`; each handler receives the native KeyboardEvent. Use for keyboard shortcuts, navigation, and custom focusable widgets. The wrapper is focusable by default (tabindex="0") so it can be reached via Tab; pass `focusable=false` to disable when the child is already focusable.
|
|
570
601
|
- OnFocus(child: Node (positional), onFocus?: callable, onBlur?: callable) — Attach focus / blur listeners to a component. Use to track input focus rings, custom focus indicators, or autosave-on-blur flows. Listens on the capture phase so blur from descendants is observed.
|
|
571
602
|
- OnIntersect(child: Node (positional), onEnter?: callable, onLeave?: callable, onChange?: callable, threshold?: number, rootMargin?: string, once?: boolean) — Observe whether a component is visible in the viewport (or a scroll container) using IntersectionObserver. Fires `onEnter` the first time the wrapped element becomes visible, `onLeave` when it leaves, and `onChange({visible, ratio})` for every transition. Use for lazy-load sentinels, infinite-scroll triggers, impression analytics, and reveal-on-scroll animations.
|
|
603
|
+
- OnMount(child: Node (positional), onMount?: callable, onUnmount?: callable) — Run imperative code against the wrapped component's rendered DOM node. `onMount(node)` fires once, on a microtask after the child is attached to the DOM — the Aktion way to get a DOM ref (measure an element, focus it, or hand it to an imperative library such as a chart / map / editor). `onUnmount(node)` fires when the component leaves the tree. Pair with `$ref(...)` to stash the node across renders.
|
|
572
604
|
- Css(child: Node (positional), style?: string, class?: string | string[]) — Apply raw CSS class names and / or an inline style string to a wrapped component. The styling is merged onto the rendered child's DOM element — no extra wrapper element is added unless the child is plain text (in which case the styling lands on a wrapping span). Reach for `Css` only when the component's own props cannot express the styling (use `Box`/`Stack`/`Grid` props for layout, `Theme` for tokens, `Styles` + selector classes for sweeping changes).
|
|
573
605
|
- Link(label: string | Node (positional), to?: string, href?: string, external?: boolean, variant?: "default"|"subtle") — Anchor link. Accepts either a plain string label or a wrapped component as its positional child. Pass `to` for client-side router navigation (no page reload) or `href` for a regular anchor. `external: true` opens the link in a new tab with `rel="noopener noreferrer"`. Use to make any component clickable as a link — cards, icons, badges, list rows.
|
|
574
606
|
|
|
@@ -141,7 +141,8 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
141
141
|
Pure helpers — no side effects. Use `$util` anywhere in expressions for data shaping, formatting, math, and strings. Prefer plain JavaScript where it is just as clear (`arr.length`, `arr.slice(0, 5)`, `s.toUpperCase()`).
|
|
142
142
|
|
|
143
143
|
### Most useful helpers
|
|
144
|
-
- Collections: `$util.sum / .avg / .min / .max / .sort(arr, field, dir?) / .groupBy(arr, field) / .unique(arr, field?)`.
|
|
144
|
+
- Collections: `$util.sum / .avg / .min / .max / .sort(arr, field, dir?) / .groupBy(arr, field) / .unique(arr, field?) / .chunk / .partition / .keyBy`.
|
|
145
|
+
- Objects: `$util.pick / .omit / .merge / .cloneDeep`.
|
|
145
146
|
- Strings: `$util.capitalize / .titlecase / .plural(n, singular, plural)`.
|
|
146
147
|
- Formatting: `$util.format(value, mode, opts?)` (numbers, currency, percent, compact) and `$util.formatDate(value, mode)` (`"short"` | `"long"` | `"time"` | `"relative"`).
|
|
147
148
|
|