aktion-runtime 0.5.11 → 0.5.13

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.
@@ -409,6 +409,45 @@ $app(Column([
409
409
  ]))
410
410
  ```
411
411
 
412
+ ## Third-party widgets & document head
413
+
414
+ ### Imperative / third-party widget interop
415
+ For a library that owns its own DOM (chart, map, editor, payment element, captcha) — NOT for normal markup (use components). The host carries `data-rui-preserve`, so the reconciler never touches the widget's DOM.
416
+ - `Mount({ setup, update?, cleanup?, props?, tag?, sx? })` — managed imperative host. `setup(node, props)` runs once after attach and **returns the instance handle**; `update(instance, props)` runs when the (shallow-compared) `props` bag changes; `cleanup(instance)` runs on unmount. `props` is the reactive boundary; `tag` sets the host (default `"div"`).
417
+ - `WebComponent(tag, { attributes?, properties?, on?, children? })` — render + hydrate a native custom element (tag must contain a hyphen). `attributes` is reactive, `properties` assigns rich JS props, `on` binds listeners that stay current.
418
+ - `$script({ src, global?, type?, as?, attributes? })` — load an external script/stylesheet once (de-duplicated per `src`) → reactive `{ ready, loading, error, value }`. Gate a widget on `.ready`; `value` = `window[global]`. Stays un-ready under SSR.
419
+ - `$dom` — managed observers, auto-disposed on replan: `$dom.onResize(node, cb)`, `$dom.onIntersect(node, cb, opts?)`, `$dom.onMutation(node, cb, opts?)`, and one-shot `$dom.measure(node)` → `{ rect, scroll, viewport }`. Pair with an `OnMount` / `Mount` node ref.
420
+
421
+ ```
422
+ $chartjs = $script({ src: "https://cdn.jsdelivr.net/npm/chart.js", global: "Chart" })
423
+ function SalesChart() {
424
+ if (!$chartjs.ready) return Skeleton({ sx: { h: "320px" } })
425
+ return Mount({
426
+ sx: { h: "320px" },
427
+ setup: (node, p) => new $chartjs.value(node, { type: "bar", data: { datasets: [{ data: p.series }] } }),
428
+ update: (chart, p) => { chart.data.datasets[0].data = p.series; chart.update() },
429
+ cleanup: (chart) => chart.destroy(),
430
+ props: { series: $series }
431
+ })
432
+ }
433
+ ```
434
+
435
+ ### Document head — `$head({...})`
436
+ Reactive head manager: call it from a page component body. Sets the title, meta, canonical/alternate links, Open Graph + Twitter cards, JSON-LD, and `<html>` attrs. Reads `$state`, so it re-applies on change; per-route calls compose (later wins). `renderToString` returns the resolved `head` + `headAttrs` for crawlable SSR.
437
+
438
+ ```
439
+ function ProductPage() {
440
+ $head({
441
+ title: `${$product.name} — Acme`,
442
+ meta: { description: $product.summary },
443
+ og: { title: $product.name, image: $product.image, type: "product" },
444
+ link: [{ rel: "canonical", href: $canonicalUrl }],
445
+ jsonLd: { "@type": "Product", name: $product.name }
446
+ })
447
+ return Column([ /* … */ ])
448
+ }
449
+ ```
450
+
412
451
  ## Universal style props (`sx` / `animate`) — every component
413
452
 
414
453
  EVERY component accepts a universal style/behaviour channel as named props, in addition to its own props. These are **bounded** (tokens & enums, never raw CSS) so they stay theme-safe — prefer them over the `Css`/`Styles`/`HTMLTag` escape hatches.
@@ -780,6 +819,10 @@ Use only these components. Each signature lists props in declaration order; opti
780
819
  - 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).
781
820
  - 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.
782
821
 
822
+ ### Interop
823
+ - Mount(setup: callable, update?: callable, cleanup?: callable, props?: object, tag?: "div"|"span"|"section"|"article"|"aside"|"figure"|"canvas"|"p"|"pre"|"form") — First-class host for an imperative / third-party widget that owns its own DOM (chart, map, editor, payment element, captcha, video SDK). Aktion creates the host element; `setup(node, props)` runs once after it attaches and returns an instance handle, `update(instance, props)` runs when `props` change (shallow-compared), and `cleanup(instance)` runs on unmount. The host is preserved across re-renders so the widget is never rebuilt. Apply layout with `sx`.
824
+ - WebComponent(tag: string (positional), attributes?: object, properties?: object, on?: object, children?: Node[]) — Render and hydrate any native custom element / web component with reactive `attributes`, JS `properties`, and `on` event hooks. Use to drop a third-party web component (`<stripe-pricing-table>`, `<model-viewer>`, a design-system element) into an Aktion app. The element is preserved across re-renders; attribute changes flow through reactively and listeners stay current. Invalid (hyphen-less) tag names fall back to a `div`.
825
+
783
826
  ### Escape hatches
784
827
  - HTMLTag(tag: string (positional), attributes?: object, children?: Node[]) — Escape-hatch primitive that renders an allow-listed HTML tag with the given attributes and children. Use ONLY when the standard component catalogue cannot express the markup (custom semantic elements, inline SVG, third-party widget mounts). Tag names outside the allow-list collapse to `div`. Attribute names matching `on*` (event handlers) are dropped, `href`/`src` are sanitised, and `style` is filtered for `expression()` / `javascript:` / `@import`. Pass children as an array of components — strings render as text nodes.
785
828
  - Styles(css: string (positional), scope?: string, tokens?: boolean) — Escape-hatch primitive that injects a `<style>` block containing the given CSS rules. Use ONLY when a layout cannot be expressed via component props or the `$theme(...)` token map. The CSS is rendered verbatim into the document so authors can target their own `HTMLTag` markup or scope rules to a wrapper class. Payloads containing `</style>`, `<script>`, `expression(`, `javascript:`, `behavior:`, or `@import` are dropped for safety.