aktion-runtime 0.5.10 → 0.5.11
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 +20 -10
- package/dist/aktion.iife.js +113 -136
- package/dist/aktion.iife.js.map +1 -1
- package/dist/aktion.js +4087 -3959
- package/dist/aktion.js.map +1 -1
- package/dist/aktion.umd.cjs +113 -136
- package/dist/aktion.umd.cjs.map +1 -1
- package/dist/language.js +1938 -1662
- package/dist/language.js.map +1 -1
- package/dist/system_prompt.txt +28 -26
- package/dist/system_prompt_chat.txt +11 -11
- package/dist/testing.js +358 -197
- package/dist/testing.js.map +1 -1
- package/dist/types/library/types.d.ts +50 -0
- package/dist/types/library/utils.d.ts +28 -0
- package/dist/types/library/validate.d.ts +2 -2
- package/dist/types/runtime/evaluator.d.ts +8 -0
- package/dist/types/theme/index.d.ts +3 -0
- package/dist/types/theme/styles.d.ts +1 -1
- package/dist/types/tooling/signature-help.d.ts +35 -0
- package/package.json +1 -1
package/dist/system_prompt.txt
CHANGED
|
@@ -22,15 +22,17 @@ $effect(() => $console.log($count), [$count]) // declarative
|
|
|
22
22
|
|
|
23
23
|
### Two rules, broken constantly — always check
|
|
24
24
|
1. **Invoke components with parentheses.** A component is a function; the bare name is just its value. Render it by calling it, even with no args: `$app(MyApp())` not `$app(MyApp)`; `Column([Header(), Body()])` not `Column([Header, Body])`. (Exception: passing a component as a callback, e.g. `render: UserCard`.)
|
|
25
|
-
2. **
|
|
25
|
+
2. **Argument forms** (per call, pick ONE): the canonical form is one bare positional — the prop tagged `(positional)` in the signature — plus a trailing `{ }` object for every other prop. Also supported: ALL-positional (arguments bind to the signature's props in listed order, so only use it for adjacent leading props), and ALL-named (a single `{ }` object naming every prop). Never split one object between roles.
|
|
26
26
|
|
|
27
27
|
```
|
|
28
|
-
Button("Save", { variant: "primary", loading: $isSaving })
|
|
28
|
+
Button("Save", { variant: "primary", loading: $isSaving }) // canonical: positional + trailing object
|
|
29
29
|
StatCard("Revenue", { value: "$48k", trend: "up", delta: "+12%" })
|
|
30
|
-
|
|
30
|
+
StatCard("Revenue", "$48k", "up") // all-positional, signature order
|
|
31
|
+
Button({ label: "Save", variant: "primary" }) // all-named single object
|
|
32
|
+
Row([Card1(), Card2()], { gap: "md" })
|
|
31
33
|
```
|
|
32
34
|
|
|
33
|
-
`Button("Save", "primary")`
|
|
35
|
+
Mind the signature order with all-positional calls: `Button("Save", "primary")` puts `"primary"` in the second slot (`onClick`), NOT `variant` — prefer the trailing object for non-adjacent props. A lone object argument to a component whose positional prop is itself object-typed is that prop's payload, not named props. Any call also accepts `{ key: ... }` to pin per-instance state across reorders.
|
|
34
36
|
|
|
35
37
|
### Reserved top-level names
|
|
36
38
|
- `$app(...)` — registers the UI root (REQUIRED).
|
|
@@ -412,7 +414,7 @@ $app(Column([
|
|
|
412
414
|
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.
|
|
413
415
|
|
|
414
416
|
- **`sx: { … }`** — token-aware inline styling. Keys (all optional):
|
|
415
|
-
- Spacing (`xs|
|
|
417
|
+
- Spacing (`none|3xs|2xs|xs|sm|md|lg|xl|2xl|3xl|auto` (`none` = 0), the `safe`/`safe-top`/`safe-right`/`safe-bottom`/`safe-left` notch insets, or a CSS length): `p px py pt pr pb pl`, `m mx my mt mr mb ml`, `gap`. `px`/`mx` are logical (`padding-inline`) and `ps pe ms me` set the inline start/end sides, so RTL apps mirror automatically.
|
|
416
418
|
- Sizing (`full|half|screen|dvh|min|max|fit|auto` or length): `w h minW maxW minH maxH`.
|
|
417
419
|
- Color (token `surface|bg|text|text-muted|primary|accent|success|warning|danger|border`, a gradient ref `gradient.brand|accent|warm|cool|success|danger`, or a raw color): `bg color borderColor`.
|
|
418
420
|
- Surface: `border: none|subtle|strong|<color>`, `radius: xs|sm|md|lg|pill|full`, `shadow: sm|md|lg|none`, `opacity`, `backdrop: "blur"`, `bgImage` (http(s)/relative/data:image only) + `bgOverlay` (color or `gradient.*` wash over the image), `bgSize: cover|contain`.
|
|
@@ -548,23 +550,23 @@ $app(Column([
|
|
|
548
550
|
| `FlipList(children, { duration? })` | FLIP reorder animation — keyed children physically move to their new positions. |
|
|
549
551
|
|
|
550
552
|
## Component library
|
|
551
|
-
Use only these components. Each signature lists props in declaration order; optional props end with `?`. The prop tagged `(positional)` is the canonical positional slot
|
|
553
|
+
Use only these components. Each signature lists props in declaration order; optional props end with `?`. The prop tagged `(positional)` is the canonical positional slot. Canonical call: pass it bare and put every other prop in a trailing `{ prop: value }` object. Also valid: all-positional in the listed order (the first positional fills the `(positional)` slot, the rest fill the remaining slots top-to-bottom), or a single `{ prop: value }` object naming every prop.
|
|
552
554
|
|
|
553
555
|
### Layout
|
|
554
|
-
- Column(children: Node[], gap?: "xs"|"
|
|
555
|
-
- Row(children: Node[], gap?: "xs"|"
|
|
556
|
-
- Center(children: Node[], axis?: "both"|"horizontal"|"vertical", minHeight?: string, gap?: "xs"|"
|
|
557
|
-
- Stack(children: Node[], direction?: "column"|"row", gap?: "xs"|"
|
|
556
|
+
- Column(children: Node[], gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", wrap?: boolean, reverse?: boolean, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", inline?: boolean) — Lay children out vertically (top → bottom) with even spacing — the most common page/section layout. Children stretch to the full width by default; set `align` to `start`/`center`/`end` to change that. This is the recommended root container for a page or a card body.
|
|
557
|
+
- Row(children: Node[], gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", grow?: boolean, wrap?: boolean, reverse?: boolean, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", inline?: boolean, alignContent?: "start"|"center"|"end"|"between"|"around"|"stretch") — Lay children out horizontally (left → right) with even spacing. The developer-friendly default: children keep their natural width and are vertically centered. Set `grow=true` to make children share the row equally (for equal-width columns prefer `Grid(columns: N)`); drop a `Spacer()` between children to push them apart; wrap a child in `StackItem` for per-child grow/shrink/alignment. Use `wrap=true` for chips/tags that should flow onto multiple lines.
|
|
558
|
+
- Center(children: Node[], axis?: "both"|"horizontal"|"vertical", minHeight?: string, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", inline?: boolean) — Centers its children on both axes — the easy way to drop a spinner, an empty state, a hero call-to-action, or a modal body into the middle of a region. Give it `minHeight` (e.g. `"60vh"`) to center vertically inside a tall area, or `axis` to center on only one axis. Multiple children stack in a column and are centered as a group.
|
|
559
|
+
- Stack(children: Node[], direction?: "column"|"row", gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", alignContent?: "start"|"center"|"end"|"between"|"around"|"stretch", wrap?: boolean, reverse?: boolean, uniform?: boolean, inline?: boolean, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl") — Low-level flex container with a configurable, optionally responsive `direction`. Reach for `Row` or `Column` first — they are clearer for fixed-direction layouts. Use `Stack` when the direction itself must change across breakpoints, e.g. `direction: {base: "column", md: "row"}` for a sidebar that stacks on mobile. `gap`, `align`, `justify`, and `padding` also accept responsive maps. NOTE: a `row` Stack grows its children equally by default (`uniform=true`); set `uniform=false` for natural widths (this is `Row`'s default).
|
|
558
560
|
- StackItem(child: Node, grow?: number, shrink?: number, basis?: string, alignSelf?: "start"|"center"|"end"|"stretch", order?: number, minWidth?: string, maxWidth?: string) — Per-child flex control inside a `Row`, `Column`, or `Stack`. Wraps one child so it can `grow` to fill leftover space, `shrink`, set a `basis`, override `alignSelf`, or change visual `order` — the building block for asymmetric rows like `Row([StackItem(searchInput, { grow: 1 }), saveButton])` (input expands, button hugs).
|
|
559
|
-
- Grid(children: Node[], columns?: number | object, gap?: "xs"|"
|
|
561
|
+
- Grid(children: Node[], columns?: number | object, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", rowGap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", columnGap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", minChildWidth?: string, alignItems?: "start"|"center"|"end"|"stretch", justifyItems?: "start"|"center"|"end"|"stretch", dense?: boolean) — Two-dimensional grid with three modes:
|
|
560
562
|
1. AUTO-FIT (default, no `columns`): wraps as many equal columns as fit, each at least `minChildWidth` wide (default 220px) — perfect for card/KPI grids that should reflow on their own.
|
|
561
563
|
2. FIXED (`columns: N`, 1–12): exactly N equal columns.
|
|
562
564
|
3. SPAN (`columns: 12` or any `GridItem` children): a 12-track grid where each `GridItem` sets its own `span` (a number 1–12 or a fraction like `"1/3"`) for dashboards and asymmetric layouts.
|
|
563
565
|
`columns` and `gap` accept responsive maps like `{base: 1, md: 2, lg: 4}`.
|
|
564
566
|
- GridItem(child: Node, span?: number | string, offset?: number, spanAt?: object) — Wraps a child in a 12-column grid cell with `span`, `offset`, and responsive `spanAt` maps. Parent `Grid` auto-enables 12-column mode when any child is a `GridItem`. Fraction spans like `"1/3"` resolve against the 12-column track.
|
|
565
|
-
- Box(children: Node[], padding?: "xs"|"
|
|
566
|
-
- Container(children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", maxWidth?: string, padding?: "none"|"
|
|
567
|
-
- Spacer(size?: "xs"|"
|
|
567
|
+
- Box(children: Node[], padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", margin?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", border?: "none"|"subtle"|"default", background?: "none"|"surface"|"muted"|"primary"|"success"|"warning"|"danger"|"info", maxWidth?: string) — Spacing and surface wrapper for padding, margin, borders, semantic backgrounds, and max-width constraints. Use when a `Card` is too heavy but the content needs a subtle surface or inset.
|
|
568
|
+
- Container(children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", maxWidth?: string, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl") — Centered, max-width content wrapper. Use when a page is wider than comfortable reading width — landing pages, marketing sections, long documents. Picks a sensible default max-width per size; pass `maxWidth` to override with any CSS value.
|
|
569
|
+
- Spacer(size?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", flex?: boolean) — Explicit space element for fine layout control. By default acts as a flex spacer that pushes following content to the far edge (use inside `Stack(direction="row")`). Pass `size` to render a fixed vertical/horizontal gap instead.
|
|
568
570
|
- Card(children: Node[], variant?: "default"|"outlined"|"elevated") — Vertical card container.
|
|
569
571
|
- CardHeader(title: string, subtitle?: string) — Card header with title and optional subtitle.
|
|
570
572
|
- CardFooter(children: Node[]) — Card footer for actions.
|
|
@@ -580,10 +582,10 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
580
582
|
- ScrollArea(children: Node[], maxHeight?: string, direction?: "vertical"|"horizontal"|"both") — Bounded scroll container. Use to clip long lists / logs / chat panels to a fixed max height with a clean scrollbar.
|
|
581
583
|
- Sticky(children: Node[], side?: "top"|"bottom", offset?: string, zIndex?: number) — Wraps content in a `position: sticky` container so it pins to the top (or bottom) of the nearest scrollable ancestor. Use for toolbar action rows above tables, in-page navs, status banners. Sets `data-stuck="true"` on itself once pinned, so a CSS hook (a shadow/border) can flag the pinned state.
|
|
582
584
|
- ResizablePanels(primary: Node[], secondary: Node[], initialPrimaryWidth?: string, minPrimaryWidth?: string) — Two-pane horizontal split with a draggable divider. The user can drag the divider to resize the primary pane; defaults respect the starting width. Use for code editors, file browsers, master/detail layouts that need user-controllable proportions.
|
|
583
|
-
- MasonryGrid(items: Node[], columns?: number, gap?: "xs"|"
|
|
585
|
+
- MasonryGrid(items: Node[], columns?: number, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl") — Pinterest-style column grid. Children flow into columns that reflow on viewport changes. Use for galleries, social-style feeds, and mixed-height card walls. Prefer `Grid` when children should share the same height per row.
|
|
584
586
|
|
|
585
587
|
### Content
|
|
586
|
-
- Text(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", style?: string) — Renders plain text with a typographic variant. Optional `style` prop accepts a CSS declaration string (e.g. "font-size: 16px; color: #000;") applied directly to the rendered element.
|
|
588
|
+
- Text(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", align?: "left"|"center"|"right", style?: string) — Renders plain text with a typographic variant. `align` (left|center|right) sets the horizontal alignment (the text renders as its own block). Optional `style` prop accepts a CSS declaration string (e.g. "font-size: 16px; color: #000;") applied directly to the rendered element.
|
|
587
589
|
- Image(src: string, alt?: string, caption?: string, ratio?: string, fit?: "cover"|"contain"|"fill"|"none"|"scale-down", fallback?: string, placeholder?: "blur"|"none", loading?: "lazy"|"eager", sizes?: string, srcset?: string) — Inline image. `ratio` constrains the box to a fixed aspect ratio (e.g. `16:9`, `1:1`) so callers do not need an outer `AspectRatio` (and it reserves space to avoid layout shift). `fit` controls how the image fills that box. `placeholder: "blur"` fades the image in once loaded; `sizes`/`srcset` enable responsive loading; `loading: "eager"` opts out of lazy-loading. When `src` is missing/unsafe or fails to load it shows the `fallback` text/icon.
|
|
588
590
|
- Badge(label: string (positional), tone?: "neutral"|"primary"|"success"|"warning"|"danger"|"info", icon?: string, size?: "xs"|"sm"|"md"|"lg"|"xl") — Small pill-style tag for status, counts, categories. Accepts an optional leading `icon` and a `size`.
|
|
589
591
|
- BadgeList(labels: string[] (positional), tone?: "neutral"|"primary"|"success"|"warning"|"danger"|"info", size?: "xs"|"sm"|"md"|"lg"|"xl") — Cluster of Badge pills rendered from an array of strings.
|
|
@@ -618,7 +620,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
618
620
|
- Radio(id: string, items: SelectItem[], value?: any, onChange?: callable) — Radio button group. `onChange(value)` fires with the newly-selected option value.
|
|
619
621
|
- Switch(id: string, label?: string, value?: boolean, description?: string, disabled?: boolean, onChange?: callable) — Compact on/off toggle. Pass a `$variable` as `value` for two-way binding — prefer Switch over Checkbox when the control represents a setting. `onChange(checked)` fires with the new boolean.
|
|
620
622
|
- ToggleGroup(id: string, items: any[], value?: any, variant?: "default"|"outline", size?: "sm"|"md"|"lg", onChange?: callable) — Group of mutually-exclusive Toggle-style buttons (single-select). Items are `[value, label]` arrays, `{value, label, icon?}` objects, or plain strings (used for both value and label). Pass a `$variable` as `value` for two-way binding. `onChange(value)` fires with the newly-selected value.
|
|
621
|
-
- Button(label: string, onClick?: callable, variant?: "primary"|"secondary"|"ghost"|"danger", type?: "button"|"submit", size?: "xs"|"sm"|"md"|"lg"|"xl", icon?: string, iconPosition?: "leading"|"trailing", iconOnly?: boolean, loading?: boolean, fullWidth?: boolean, disabled?: boolean) — Clickable button. `onClick` (a callable) runs when the user presses the button. The legacy `action` prop is an alias and is still accepted.
|
|
623
|
+
- Button(label: string, onClick?: callable, variant?: "primary"|"secondary"|"outline"|"ghost"|"link"|"danger"|"default", type?: "button"|"submit", size?: "xs"|"sm"|"md"|"lg"|"xl", icon?: string, iconPosition?: "leading"|"trailing", iconOnly?: boolean, loading?: boolean, fullWidth?: boolean, disabled?: boolean) — Clickable button. `onClick` (a callable) runs when the user presses the button. The legacy `action` prop is an alias and is still accepted.
|
|
622
624
|
- Buttons(items: Button[], direction?: "row"|"column") — Group of buttons laid out horizontally or vertically.
|
|
623
625
|
- SearchBar(id: string, placeholder?: string, value?: string, shortcut?: string, onSubmit?: callable, submitLabel?: string, onChange?: callable) — Pre-styled search input with a leading magnifying-glass icon, optional trailing submit button, and optional keyboard-shortcut hint. Pass a `$variable` as `value` for two-way binding. Use anywhere a user needs to filter content — toolbars, command bars, lists, headers.
|
|
624
626
|
- Slider(id: string, min?: number, max?: number, step?: number, value?: number, label?: string, showValue?: boolean, disabled?: boolean, onChange?: callable) — Range slider for selecting a single numeric value between `min` and `max`. Pass a `$variable` as `value` for two-way binding. Useful for filters, settings (volume, brightness), and parameter tuning.
|
|
@@ -744,7 +746,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
744
746
|
- SplitView(primary: Node[], detail: Node[], primaryWidth?: string) — Two-pane master/detail layout — a narrow primary pane on the left, wider detail pane on the right. Collapses to a single column on narrow viewports. Use for inboxes, file browsers, contact lists.
|
|
745
747
|
|
|
746
748
|
### Advanced UI
|
|
747
|
-
- IconButton(icon: string, label: string, onClick?: callable, variant?: "primary"|"secondary"|"ghost"|"danger", size?: "xs"|"sm"|"md"|"lg"|"xl"
|
|
749
|
+
- IconButton(icon: string, label: string, onClick?: callable, variant?: "primary"|"secondary"|"ghost"|"danger", size?: "xs"|"sm"|"md"|"lg"|"xl", disabled?: boolean) — Icon-only button with an accessible label. Use for toolbars, table row actions, and compact controls.
|
|
748
750
|
- CommandPalette(items: any[], open?: boolean, placeholder?: string, shortcut?: string) — Cmd-K style searchable command list. Pass `items` as `{label, value, group?, shortcut?, action?}` objects.
|
|
749
751
|
- FilterChips(chips: any[], onRemove?: callable, onClear?: callable) — Removable filter chips with an optional clear-all control.
|
|
750
752
|
- FieldRepeater(items: any[], fields: any[], onAdd?: callable, onRemove?: callable, addLabel?: string) — Dynamic list of field groups. Pass `items` as row objects and `fields` as `{name, label, type?}` definitions.
|
|
@@ -784,13 +786,13 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
784
786
|
|
|
785
787
|
### Other
|
|
786
788
|
- Fragment(children: Node[]) — Groups several siblings into one value WITHOUT adding a layout box — the wrapper is `display: contents`, so the children participate in the parent's flex/grid layout directly. Use to return multiple nodes from a component, or to conditionally group siblings, without a stray `div` that would break a Grid/Stack's spacing.
|
|
787
|
-
- TextContent(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", style?: string) — Deprecated alias for `Text`. Prefer `Text(...)` — both render identically.
|
|
789
|
+
- TextContent(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", align?: "left"|"center"|"right", style?: string) — Deprecated alias for `Text`. Prefer `Text(...)` — both render identically.
|
|
788
790
|
- VirtualGrid(items: any[], columns?: number, itemHeight?: number, gap?: number, height?: number) — Windowed 2-D grid for very large collections (galleries, tiles, thumbnails). Only the visible rows of cells are mounted. Pass pre-rendered nodes (or plain values) as `items`; set `columns`, `itemHeight`, and `gap`. Virtualizes by row so thousands of items scroll smoothly (XI.3).
|
|
789
791
|
- GradientText(text: string (positional), gradient?: "brand"|"accent"|"warm"|"cool"|"success"|"danger") — Inline text painted with a brand gradient. Use inside a Display/Heading title to emphasise a phrase: `Display(["Build in ", GradientText("record time")])`. `gradient` selects a named theme gradient (brand|accent|warm|cool|success|danger).
|
|
790
792
|
- Display(content: string | Node[] (positional), size?: "hero"|"xl"|"lg", align?: "left"|"center"|"right", balance?: boolean, weight?: number) — Oversized display headline with built-in responsive `clamp()` sizing. The positional argument may be a plain string OR an array mixing strings and `GradientText(...)` runs. `size`: hero|xl|lg. `balance` wraps for even line lengths.
|
|
791
793
|
- Heading(content: string | Node[] (positional), level?: number, size?: "section"|"lg"|"md"|"sm", align?: "left"|"center"|"right") — Section/subsection heading with token-driven sizing. `level` sets the semantic tag (1–6); `size`: section|lg|md|sm. Accepts string or mixed string/GradientText array like Display.
|
|
792
794
|
- Eyebrow(text: string (positional)) — Small uppercase, letter-spaced, primary-toned label above a heading.
|
|
793
|
-
- Section(children: Node[] (positional), background?: "base"|"soft"|"surface"|"muted"|"brand", width?: "sm"|"md"|"lg"|"xl"|"full", padding?: "sm"|"md"|"lg", align?: "left"|"center", eyebrow?: string, title?: string | Node[], subtitle?: string, id?: string) — Full-bleed page band → centered max-width container → optional tinted background → optional eyebrow/title/subtitle header. The single most useful primitive for marketing, docs, and settings pages. Children render below the header.
|
|
795
|
+
- Section(children: Node[] (positional), background?: "base"|"soft"|"surface"|"muted"|"brand", width?: "sm"|"md"|"lg"|"xl"|"full", padding?: "none"|"xs"|"sm"|"md"|"lg"|"xl", align?: "left"|"center", eyebrow?: string, title?: string | Node[], subtitle?: string, id?: string) — Full-bleed page band → centered max-width container → optional tinted background → optional eyebrow/title/subtitle header. The single most useful primitive for marketing, docs, and settings pages. Children render below the header.
|
|
794
796
|
- Overlay(base: Node (positional), items: OverlayItem[]) — Layers OverlayItem children on top of a base node — corner badges, play buttons over thumbnails, sale ribbons, floating actions. Pass the base as the positional argument and `items` as OverlayItem entries.
|
|
795
797
|
- OverlayItem(child: Node (positional), anchor?: "top-left"|"top-right"|"bottom-left"|"bottom-right"|"top"|"bottom"|"left"|"right"|"center", offset?: string) — A child positioned over an Overlay's base. `anchor` picks a corner/edge/center.
|
|
796
798
|
- Brand(name: string (positional), logo?: string, version?: string, href?: string) — Logo + product name (+ optional version pill), linking home. Use in NavBar/Footer.
|
|
@@ -820,9 +822,9 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
820
822
|
- TypingIndicator(name?: string (positional)) — Three animated bouncing dots — a chat 'is typing…' affordance. Optional `name` prefix.
|
|
821
823
|
- CountdownTimer(to: string | number (positional), endLabel?: string) — Live countdown to a target date/time (ISO string or timestamp). Ticks every second, then shows `endLabel`.
|
|
822
824
|
- BackToTop(label?: string) — A floating button that smoothly scrolls the page (and the host) back to the top.
|
|
823
|
-
- Split(left: Node (positional), right: Node, ratio?: string, gap?: "none"|"
|
|
824
|
-
- Bento(items: BentoCell[] (positional), columns?: number, gap?: "
|
|
825
|
-
- BentoCell(child: Node (positional), span?: string | number | object, rowSpan?: number) — A single cell in a Bento grid. `span`
|
|
825
|
+
- Split(left: Node (positional), right: Node, ratio?: string, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", divider?: boolean, sticky?: "left"|"right", stackAt?: "sm"|"md"|"lg", align?: "start"|"center"|"stretch") — Two-pane layout: a left/primary node and a right/secondary node, with a controllable `ratio` (1/1, 3/2, 2/3…), optional `divider`, an optional `sticky` pane that pins on scroll, and a `stackAt` breakpoint where it collapses to a single column. The canonical 'text + media' / 'code + preview' / 'content + sidebar' section.
|
|
826
|
+
- Bento(items: BentoCell[] (positional), columns?: number, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", rowHeight?: string, dense?: boolean) — Asymmetric 'bento box' grid — the marquee feature-section layout. Children must be BentoCell nodes (a plain node becomes a 1×1 tile). Two rules make it look right: (1) spans must tile the grid exactly — each row's column spans sum to `columns` and row-spans pair up with neighbouring cells, never leaving a dangling track (e.g. `columns: 3` with 4 cells: hero 2×2 + tall 1×2 fill rows 1–2, wide 2×1 + tile fill row 3); (2) set a fixed `rowHeight` (e.g. "180px") whenever cells hold images or cards — the default auto row stretches to the tallest cell and makes the mosaic ragged. Give 1–2 standout cells a big span (hero/wide/tall) and keep the rest 1×1 tiles. `dense` (default true) backfills gaps. Collapses to 2 columns below 920px and 1 below 640px.
|
|
827
|
+
- BentoCell(child: Node (positional), span?: string | number | object, rowSpan?: number) — A single cell in a Bento grid. `span` names a size — `tile` 1×1, `wide` 2×1 (2 columns), `tall` 1×2 (2 rows), `hero` 2×2, `full` (a whole row) — or use a "CxR" string ("2x1"), a bare column-span number, or `{ col, row }`; `rowSpan` adds rows to a named/numeric span. The child stretches to fill the cell, so images/cards crop to the cell's shape. Pick spans that tile the parent Bento with no leftover tracks.
|
|
826
828
|
- Reveal(child: Node (positional), animation?: "fade"|"fade-up"|"fade-down"|"fade-left"|"fade-right"|"zoom"|"slide-up", delay?: number, once?: boolean) — Animates its child in the first time it scrolls into view (scroll choreography). `animation` is a preset (fade-up|fade|zoom|…), `delay` staggers it (ms), `once` (default true) plays a single time. Honours prefers-reduced-motion (renders immediately).
|
|
827
829
|
- OnGesture(child: Node (positional), swipe?: callable, longPress?: callable, doubleTap?: callable, pan?: callable, threshold?: number) — Attach high-level pointer gestures to any component without raw DOM: `swipe(dir)` (left/right/up/down), `longPress()`, `doubleTap()`, and `pan({dx, dy})`. Powers swipe-to-dismiss, pull-to-refresh, carousels, and drag affordances on touch + mouse.
|
|
828
830
|
- Sortable(items: Node[] (positional), onReorder?: callable, handle?: boolean) — A vertical list whose items can be drag-reordered. Pass already-rendered `items`; `onReorder(fromIndex, toIndex)` fires after a drop so you can reorder the backing reactive array. Works with mouse + touch.
|
|
@@ -874,7 +876,7 @@ row = task => Card([Row([
|
|
|
874
876
|
Badge(task.done ? "done" : "open", { tone: task.done ? "success" : "neutral" }),
|
|
875
877
|
StackItem(Text(task.title, { tone: task.done ? "muted" : "default" }), { grow: 1 }),
|
|
876
878
|
Button(task.done ? "Reopen" : "Done", { onClick: () => toggle(task), size: "sm" })
|
|
877
|
-
], { gap: "
|
|
879
|
+
], { gap: "md" })])
|
|
878
880
|
|
|
879
881
|
$app(Column([
|
|
880
882
|
PageHeader("Tasks", { subtitle: `${$tasks.data.length} items`, actions: [Button("Refresh", { onClick: $tasks.refetch, variant: "ghost" })] }),
|
|
@@ -882,9 +884,9 @@ $app(Column([
|
|
|
882
884
|
loading: LoadingState("Loading tasks…"),
|
|
883
885
|
error: ErrorState("Couldn't fetch tasks"),
|
|
884
886
|
empty: EmptyState("No tasks yet"),
|
|
885
|
-
data: Column($tasks.data.map(t => row(t)), { gap: "
|
|
887
|
+
data: Column($tasks.data.map(t => row(t)), { gap: "sm" })
|
|
886
888
|
})
|
|
887
|
-
], { gap: "
|
|
889
|
+
], { gap: "lg" }))
|
|
888
890
|
```
|
|
889
891
|
|
|
890
892
|
## Streaming & verification
|
|
@@ -12,7 +12,7 @@ A program is a flat list of `name = expression` statements in standard JavaScrip
|
|
|
12
12
|
### Component calls
|
|
13
13
|
- **Case doesn't matter** — `Card` and `card` are equivalent.
|
|
14
14
|
- **Always invoke with parentheses** — `Column([Header(), Body()])`, never `Column([Header, Body])`; write `Hero()` even with no args.
|
|
15
|
-
- **
|
|
15
|
+
- **Canonical call: one positional arg, the rest in a trailing object** — `Callout("info", { title: "Heads up", icon: "circle-info" })`, `Badge("Live", { tone: "success" })`. All-positional (signature order) and all-named (single `{ }` object) calls also work.
|
|
16
16
|
|
|
17
17
|
### Build UI from data — JS is fully supported
|
|
18
18
|
`.map` / `.filter` arrays into nodes (`rows.map(r => ListItem(r.title))`), ternaries for branching, and the array-pluck shortcut `rows.title` → `[each row.title]` to feed columns (`Col("Title", rows.title)`) and chart series (`PieChart(rows.label, rows.value)`). `if` / `for` are statements — not usable on the right of `=`.
|
|
@@ -29,20 +29,20 @@ rows = [{ region: "NA", revenue: 184000 }, { region: "EU", revenue: 122000 }]
|
|
|
29
29
|
Use only these components. Each signature lists props in declaration order; optional props end with `?`. Pass the positional prop bare, then all other props in a trailing `{ prop: value }` object.
|
|
30
30
|
|
|
31
31
|
### Layout
|
|
32
|
-
- Column(children: Node[], gap?: "xs"|"
|
|
33
|
-
- Row(children: Node[], gap?: "xs"|"
|
|
34
|
-
- Center(children: Node[], axis?: "both"|"horizontal"|"vertical", minHeight?: string, gap?: "xs"|"
|
|
35
|
-
- Stack(children: Node[], direction?: "column"|"row", gap?: "xs"|"
|
|
32
|
+
- Column(children: Node[], gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", wrap?: boolean, reverse?: boolean, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", inline?: boolean) — Lay children out vertically (top → bottom) with even spacing — the most common page/section layout. Children stretch to the full width by default; set `align` to `start`/`center`/`end` to change that. This is the recommended root container for a page or a card body.
|
|
33
|
+
- Row(children: Node[], gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", grow?: boolean, wrap?: boolean, reverse?: boolean, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", inline?: boolean, alignContent?: "start"|"center"|"end"|"between"|"around"|"stretch") — Lay children out horizontally (left → right) with even spacing. The developer-friendly default: children keep their natural width and are vertically centered. Set `grow=true` to make children share the row equally (for equal-width columns prefer `Grid(columns: N)`); drop a `Spacer()` between children to push them apart; wrap a child in `StackItem` for per-child grow/shrink/alignment. Use `wrap=true` for chips/tags that should flow onto multiple lines.
|
|
34
|
+
- Center(children: Node[], axis?: "both"|"horizontal"|"vertical", minHeight?: string, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", inline?: boolean) — Centers its children on both axes — the easy way to drop a spinner, an empty state, a hero call-to-action, or a modal body into the middle of a region. Give it `minHeight` (e.g. `"60vh"`) to center vertically inside a tall area, or `axis` to center on only one axis. Multiple children stack in a column and are centered as a group.
|
|
35
|
+
- Stack(children: Node[], direction?: "column"|"row", gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", align?: "start"|"center"|"end"|"stretch", justify?: "start"|"center"|"end"|"between"|"around"|"evenly", alignContent?: "start"|"center"|"end"|"between"|"around"|"stretch", wrap?: boolean, reverse?: boolean, uniform?: boolean, inline?: boolean, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl") — Low-level flex container with a configurable, optionally responsive `direction`. Reach for `Row` or `Column` first — they are clearer for fixed-direction layouts. Use `Stack` when the direction itself must change across breakpoints, e.g. `direction: {base: "column", md: "row"}` for a sidebar that stacks on mobile. `gap`, `align`, `justify`, and `padding` also accept responsive maps. NOTE: a `row` Stack grows its children equally by default (`uniform=true`); set `uniform=false` for natural widths (this is `Row`'s default).
|
|
36
36
|
- StackItem(child: Node, grow?: number, shrink?: number, basis?: string, alignSelf?: "start"|"center"|"end"|"stretch", order?: number, minWidth?: string, maxWidth?: string) — Per-child flex control inside a `Row`, `Column`, or `Stack`. Wraps one child so it can `grow` to fill leftover space, `shrink`, set a `basis`, override `alignSelf`, or change visual `order` — the building block for asymmetric rows like `Row([StackItem(searchInput, { grow: 1 }), saveButton])` (input expands, button hugs).
|
|
37
|
-
- Grid(children: Node[], columns?: number | object, gap?: "xs"|"
|
|
37
|
+
- Grid(children: Node[], columns?: number | object, gap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", rowGap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", columnGap?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", minChildWidth?: string, alignItems?: "start"|"center"|"end"|"stretch", justifyItems?: "start"|"center"|"end"|"stretch", dense?: boolean) — Two-dimensional grid with three modes:
|
|
38
38
|
1. AUTO-FIT (default, no `columns`): wraps as many equal columns as fit, each at least `minChildWidth` wide (default 220px) — perfect for card/KPI grids that should reflow on their own.
|
|
39
39
|
2. FIXED (`columns: N`, 1–12): exactly N equal columns.
|
|
40
40
|
3. SPAN (`columns: 12` or any `GridItem` children): a 12-track grid where each `GridItem` sets its own `span` (a number 1–12 or a fraction like `"1/3"`) for dashboards and asymmetric layouts.
|
|
41
41
|
`columns` and `gap` accept responsive maps like `{base: 1, md: 2, lg: 4}`.
|
|
42
42
|
- GridItem(child: Node, span?: number | string, offset?: number, spanAt?: object) — Wraps a child in a 12-column grid cell with `span`, `offset`, and responsive `spanAt` maps. Parent `Grid` auto-enables 12-column mode when any child is a `GridItem`. Fraction spans like `"1/3"` resolve against the 12-column track.
|
|
43
|
-
- Box(children: Node[], padding?: "xs"|"
|
|
44
|
-
- Container(children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", maxWidth?: string, padding?: "none"|"
|
|
45
|
-
- Spacer(size?: "xs"|"
|
|
43
|
+
- Box(children: Node[], padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", margin?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", border?: "none"|"subtle"|"default", background?: "none"|"surface"|"muted"|"primary"|"success"|"warning"|"danger"|"info", maxWidth?: string) — Spacing and surface wrapper for padding, margin, borders, semantic backgrounds, and max-width constraints. Use when a `Card` is too heavy but the content needs a subtle surface or inset.
|
|
44
|
+
- Container(children: Node[], size?: "sm"|"md"|"lg"|"xl"|"full", maxWidth?: string, padding?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl") — Centered, max-width content wrapper. Use when a page is wider than comfortable reading width — landing pages, marketing sections, long documents. Picks a sensible default max-width per size; pass `maxWidth` to override with any CSS value.
|
|
45
|
+
- Spacer(size?: "none"|"3xs"|"2xs"|"xs"|"sm"|"md"|"lg"|"xl"|"2xl"|"3xl", flex?: boolean) — Explicit space element for fine layout control. By default acts as a flex spacer that pushes following content to the far edge (use inside `Stack(direction="row")`). Pass `size` to render a fixed vertical/horizontal gap instead.
|
|
46
46
|
- Card(children: Node[], variant?: "default"|"outlined"|"elevated") — Vertical card container.
|
|
47
47
|
- CardHeader(title: string, subtitle?: string) — Card header with title and optional subtitle.
|
|
48
48
|
- CardFooter(children: Node[]) — Card footer for actions.
|
|
@@ -55,7 +55,7 @@ Use only these components. Each signature lists props in declaration order; opti
|
|
|
55
55
|
- 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.
|
|
56
56
|
|
|
57
57
|
### Content
|
|
58
|
-
- Text(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", style?: string) — Renders plain text with a typographic variant. Optional `style` prop accepts a CSS declaration string (e.g. "font-size: 16px; color: #000;") applied directly to the rendered element.
|
|
58
|
+
- Text(value: string, variant?: "small"|"small-heavy"|"body"|"body-heavy"|"large"|"large-heavy"|"heading"|"title", tone?: "default"|"muted"|"primary"|"success"|"warning"|"danger", align?: "left"|"center"|"right", style?: string) — Renders plain text with a typographic variant. `align` (left|center|right) sets the horizontal alignment (the text renders as its own block). Optional `style` prop accepts a CSS declaration string (e.g. "font-size: 16px; color: #000;") applied directly to the rendered element.
|
|
59
59
|
- Image(src: string, alt?: string, caption?: string, ratio?: string, fit?: "cover"|"contain"|"fill"|"none"|"scale-down", fallback?: string, placeholder?: "blur"|"none", loading?: "lazy"|"eager", sizes?: string, srcset?: string) — Inline image. `ratio` constrains the box to a fixed aspect ratio (e.g. `16:9`, `1:1`) so callers do not need an outer `AspectRatio` (and it reserves space to avoid layout shift). `fit` controls how the image fills that box. `placeholder: "blur"` fades the image in once loaded; `sizes`/`srcset` enable responsive loading; `loading: "eager"` opts out of lazy-loading. When `src` is missing/unsafe or fails to load it shows the `fallback` text/icon.
|
|
60
60
|
- Badge(label: string (positional), tone?: "neutral"|"primary"|"success"|"warning"|"danger"|"info", icon?: string, size?: "xs"|"sm"|"md"|"lg"|"xl") — Small pill-style tag for status, counts, categories. Accepts an optional leading `icon` and a `size`.
|
|
61
61
|
- BadgeList(labels: string[] (positional), tone?: "neutral"|"primary"|"success"|"warning"|"danger"|"info", size?: "xs"|"sm"|"md"|"lg"|"xl") — Cluster of Badge pills rendered from an array of strings.
|
|
@@ -186,4 +186,4 @@ References resolve from the whole scope, not source order — undefined refs ren
|
|
|
186
186
|
2. Every component is invoked with `()` — `Hero()`, never bare `Hero`.
|
|
187
187
|
3. Only the read-only display components above — no forms, clickable buttons, state writes, actions, effects, HTTP, or routing.
|
|
188
188
|
4. Tables are column-oriented (`Table([Col("Label", arr)])`, cells may be components via `rows.map(r => Badge(r.status))`); charts take numeric arrays (array-pluck `rows.value`).
|
|
189
|
-
5.
|
|
189
|
+
5. Prefer one positional arg per call with everything else in a trailing `{ }` object; no statement split across lines outside an unmatched bracket.
|