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.
Files changed (37) hide show
  1. package/README.md +120 -15
  2. package/dist/aktion.iife.js +42 -42
  3. package/dist/aktion.iife.js.map +1 -1
  4. package/dist/aktion.js +12655 -12123
  5. package/dist/aktion.js.map +1 -1
  6. package/dist/aktion.umd.cjs +42 -42
  7. package/dist/aktion.umd.cjs.map +1 -1
  8. package/dist/language.js +1348 -98
  9. package/dist/language.js.map +1 -1
  10. package/dist/plugin.cjs +12 -2
  11. package/dist/plugin.cjs.map +1 -1
  12. package/dist/plugin.js +12 -2
  13. package/dist/plugin.js.map +1 -1
  14. package/dist/system_prompt.txt +40 -8
  15. package/dist/system_prompt_chat.txt +2 -1
  16. package/dist/testing.js +15415 -14698
  17. package/dist/testing.js.map +1 -1
  18. package/dist/types/element.d.ts +0 -1
  19. package/dist/types/language/builtins.d.ts +52 -0
  20. package/dist/types/language/index.d.ts +5 -2
  21. package/dist/types/language-api.d.ts +5 -1
  22. package/dist/types/library/components/helpers.d.ts +0 -5
  23. package/dist/types/library/components/wrappers.d.ts +1 -0
  24. package/dist/types/parser/types.d.ts +0 -1
  25. package/dist/types/runtime/effects.d.ts +1 -18
  26. package/dist/types/runtime/evaluator.d.ts +46 -5
  27. package/dist/types/runtime/http.d.ts +41 -0
  28. package/dist/types/runtime/index.d.ts +2 -1
  29. package/dist/types/runtime/router.d.ts +28 -2
  30. package/dist/types/runtime/toast.d.ts +45 -0
  31. package/dist/types/runtime/util.d.ts +11 -1
  32. package/dist/types/tooling/index.d.ts +6 -0
  33. package/dist/types/tooling/language-service.d.ts +10 -5
  34. package/dist/types/tooling/navigation.d.ts +91 -0
  35. package/dist/types/tooling/semantic-tokens.d.ts +24 -0
  36. package/dist/types/tooling/signature-help.d.ts +21 -0
  37. package/package.json +1 -1
@@ -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` & `console`
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 = "Copied" }
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`, `.range(start, end, step?)`, `.pick(obj, keys)`.
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 `children` until `loader` resolves.
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