@kitlangton/knobs 0.4.0-next.10 → 0.4.0-next.12

package/README.md

@@ -202,10 +202,10 @@ keeps a gradient's stop count and walks its hue along a lightness ramp. On a cur
 a built-in shape and jitters it. Mutate nudges colours as it does a `color` and moves stops and
 points without letting them pass each other.
 
-### Inspector fields: vectors, ranges, angles, seeds, key combinations and toolbars
+### Inspector fields: vectors, ranges, angles, seeds, key combinations, text and toolbars
 
 ```ts
-import { action, angle, defineControls, keybind, range, seed, toolbar, vec2, vec3 } from "knobs"
+import { action, angle, defineControls, keybind, range, seed, text, toolbar, vec2, vec3 } from "knobs"
 
 const node = defineControls("node", {
   replay: action("Replay", { run: replay, shortcut: "Shift+K", global: true, rebind: true }),
@@ -222,6 +222,8 @@ const node = defineControls("node", {
   yaw: angle(90),                                                             // degrees
   seed: seed(1234),                                                           // a whole number
   fire: keybind("Space"),                                                     // "Meta+Shift+K", "" for none
+  name: text("Lamp", { placeholder: "Untitled" }),                            // one line
+  notes: text("", { multiline: true }),                                       // lines in a box
 }, { onAction: (id) => run(id) })
 ```
 
@@ -246,7 +248,12 @@ const node = defineControls("node", {
   Esc cancels and ⌫ clears. Not rolled by Random or Mutate. Letters follow the user's layout
   (Dvorak's K records and matches as K), with ⌥ combinations read through the browser's layout
   map; `comboFromEvent`, `matchesCombo` and `letterOf` do the same for a host's own keys.
-- **`toolbar(items)`**: a row of buttons with an icon (`play`, `pause`, `frame`,
+- **`text(value?, { multiline?, placeholder? })`**: words typed into a field beside the label, or
+  with `multiline` a box under it that grows with its lines (up to eight, then it scrolls). Each
+  keystroke sets the value and one focus's typing is one undo step; Enter (`⌘Enter` in a box) or
+  Esc lets go. A one-line field turns a line break into a space. Presets, copy and remote
+  descriptors carry it like any string; Random and Mutate leave it alone.
+- **`toolbar(items, { labels? })`**: a row of buttons with an icon (`play`, `pause`, `frame`,
   `retrigger`, `clear`, `target`, `camera`, `sparkle`, … or SVG path data on a 256 grid), a label
   and a shortcut chip. The buttons share equal columns, as many as fit, balanced across the rows
   (four that don't fit in one row wrap as two and two), each chip at its button's end. A press calls the item's `run` and `onAction(id)`; `controls.action(key, id)`
@@ -255,7 +262,8 @@ const node = defineControls("node", {
   `shortcut: { key, scope }` says where one works: `"panel"` (the default), `"page"` (as `global`)
   or `"none"`, a chip that only shows a key the host binds itself (a canvas's `F`), so the panel's
   own `f` and `g` still work beside it. The row holds no value; ←/→ move along it and Enter or
-  Space presses.
+  Space presses. When every button has an icon and the labels don't fit on one row, it's one row
+  of icons, each label and shortcut in its tooltip; `labels: false` always shows icons only.
 - **`action(label, { run, shortcut?, global?, rebind? })`**: a button row, whose `shortcut` (a
   combination such as `"Shift+K"`, or `{ key, scope }`) presses it under the same rules as a
   toolbar button's: while the panel has focus, or anywhere on the page with `global: true` (not
@@ -268,9 +276,9 @@ const node = defineControls("node", {
   button's too (by its id), which has no cap of its own to rebind it from.
 
 Remote descriptors use the same names: `kind: "vec2" | "vec3" | "range" | "angle" | "seed" |
-"keybind"` with `default`, `min`, `max`, `step`, `unit`, `decimals`, `link`, `linked` and `wrap`, and
-`{ kind: "toolbar", items: [{ key, label, icon?, shortcut?, global?, disabled? }] }`; vectors take
-`axes`. Each kind takes
+"keybind" | "text"` with `default`, `min`, `max`, `step`, `unit`, `decimals`, `link`, `linked` and `wrap`, and
+`{ kind: "toolbar", items: [{ key, label, icon?, shortcut?, global?, disabled? }], labels? }`; vectors take
+`axes`, text `multiline` and `placeholder`. Each kind takes
 `disabled`, `readOnly` and mixed values like the rest ("—" in place of the value).
 
 Spring, point, easing, gradient and curve values compare by their contents everywhere (`isModified`, presets, undo, variants), and unchanged ones keep their identity across updates so memoized React children skip them. Random values stay in range people use (springs 0.2–0.9 s with bounce up to 0.45, mid-light colours of moderate chroma, any point, a named curve). Switches sit out of Random and Mutate unless a field says `random: true`: they usually show or hide things (a view, a scene's part), and a roll that hides the page isn't a new take on it.
@@ -317,6 +325,38 @@ live.watch("events", { level: "warn", text: "Gutter drip over budget" })
 
 Readouts cost nothing at rest. They draw on one shared clock, only while on screen and only when something arrived, so a paused feed lets the page, and the GPU overlay, sleep. Graphics are canvases redrawn from a list of drawing ops (the GPU overlay draws the same ops). Text changes at most `hz` times a second (4 by default), in boxes that only grow, so nothing reflows as numbers change. Scales snap to round steps (1, 2 or 5 × 10ⁿ) and ease there on a spring, in log space, so a spike rescales smoothly. The store keeps each readout's history, so a panel mounted later starts with it. On their own, outside a panel: `readout(sparkline({ unit: "ms" }), { preset })` from `knobs/ui` returns `{ element, push(value), value, dispose() }`.
 
+## Versions of a design: variants in the strip
+
+When a page has several versions of one design (nine hero animations, three card layouts), the
+preset strip at the top of the panel is where you switch them. Each version is a preset. Don't
+add a `variant` choice beside it: two ways to switch the same thing is one too many.
+
+When the page's code branches on which version is on, give that choice `variants: true`:
+
+```ts
+const controls = defineControls("upsell", {
+  variant: choice("Stand up", ["Stand up", "Anamorphic", "Roll", "Trace"], { variants: true }),
+  speed: knob(1, { min: 0.25, max: 2, step: 0.05 }),
+}, {
+  presets: { Roll: { speed: 0.8 } }, // optional: values a variant changes beside itself
+})
+
+render(controls.get().variant) // "Stand up", until another chip is picked
+```
+
+- **Each option is a chip in the strip.** The default option is the `default` preset, named after
+  it; the others follow in order, then any other `presets`. Their ids are the options, and
+  `labels` name the chips.
+- **The choice has no row.** The strip is the one place to switch, with a click, a sideways pan,
+  `[` / `]`, or `1`–`9` from anywhere in the panel but a number row.
+- **Random leaves it be** (`random: false` unless you say otherwise). Random explores around the
+  active variant, and Reset goes back to it, as with any preset.
+- **`presets` keyed by an option add to that variant.** The default variant's values are the
+  schema's defaults, so it takes none there.
+
+Versions that differ only in their values need no choice at all: they're plain `presets`, with
+`defaultLabel` naming the first.
+
 ## Presets: names and the base
 
 The strip holds the schema's `presets` (and `default`) beside the variants you save. Saving (`+` or `⇧S`) puts a field where the new chip goes, its name ("Variant 3") selected so typing replaces it; `Enter` keeps what you typed, `Esc` keeps "Variant 3", and the field opens out to the chip's width without moving anything else. `F2` or `Enter` on the strip, or a double-click, renames a saved one the same way (`controls.variants.rename(id, name)`); names are kept with the variants in the store's storage. The schema's presets keep their names.
@@ -344,7 +384,7 @@ Panels and switchers are keyboard-first:
 | Arrows on a pad or curve handle | Move the puck or handle (`⇧` ×10, `⌥` finest); `j` / `k` or `Tab` move on |
 | On a gradient strip or curve graph | Arrows move the selected stop or point; `Tab` / `⇧Tab` and `[` / `]` pick another; `n` adds one, `Delete` removes it; `Enter` edits a stop's colour (`Esc` returns) |
 | `[` / `]` | Cycle presets and saved variants from anywhere in the panel; with no preset strip, cycle tabs |
-| `1`–`9` | Pick the focused row's Nth option: a choice (segmented or menu) or a curve's, easing's or gradient's presets. Tiny digit hints show on the options once focus settles. A row with options keeps the digits; elsewhere they do what they did before (inline number edits, a page's group presets) |
+| `1`–`9` | Pick the focused row's Nth option: a choice (segmented or menu) or a curve's, easing's or gradient's presets. Anywhere else in the panel, pick the preset strip's Nth chip (a design's variants). While you use keys, tiny digit hints show on the options once focus settles, and on the strip's chips while focus is on the strip or the panel. A number row keeps its digits for inline edits, and a page's card for its group presets |
 | `⌥1`–`⌥9` | Show tab 1–9 |
 | `/` | Focus the search field (`Esc` clears it, then hands focus back; `↓` or `Enter` go to the first row left) |
 | `Home` / `End` | Jump slider to `min` or `max` |
@@ -395,8 +435,10 @@ Three things show which, in both renderers, on floating and inline panels and on
   Cohesion`, the deepest crumb bright and its parents dim. Crumbs glide to their places as focus
   moves, and one that changes fades out as the new one fades in. For a moment after a key below
   the panel's level, a faint `esc ↑ Shape` follows it, then fades. Clicking a crumb takes focus to
-  its level; clicking the title takes it to the panel. When it doesn't fit, the first crumbs fold
-  into `…`. `crumbs: false` on the mount drops the line (the lens and the armed frame stay).
+  its level; clicking the title takes it to the panel. The line lives in the room between the
+  title and the header's buttons: when it doesn't fit, the first crumbs drop off, and without room
+  for the deepest it stays empty, so it never runs under the buttons and the title never moves.
+  `crumbs: false` on the mount drops the line (the lens and the armed frame stay).
 
 Tune them with tokens on the panel or any ancestor:
 
@@ -709,6 +751,18 @@ mountPanel(station, column, {
   the close X): a list picks which show, not their order. A button left out takes no slot; Undo,
   Redo and Reset keep theirs while they're away (`data-shown="false"`, `disabled`, out of the
   tab order and the accessibility tree).
+- **On a surface.** An inline panel in a split's pane (or inside anything with the class
+  `knobs-surface`) is one surface with it: no card, padding or background of its own, its groups
+  plain sections on hairlines, its rows and preset chips keeping their inset so their text lines
+  up with the pane's. Without a title, its header buttons join the pane's header (left of the
+  collapse button) and it draws no header band; elsewhere an untitled header shows only while one
+  of its buttons does.
+- **Presets as a list.** `presetDisplay: "auto"` (the default) shows the preset strip's chips
+  while they fit on two lines and a list once they'd take more (many presets, or long names):
+  left-aligned rows, like a menu's, with the selection gliding between them. `"list"` and
+  `"chips"` pick one.
+- **Empty.** `empty: "This story has no controls"` shows that line, quietly, while the panel has
+  no rows. Without it an empty panel shows nothing.
 - **Height-bounded panels.** The header (title and buttons) stays pinned while the rows scroll
   under it; the preset strip, tabs and search scroll with the rows. Once rows are under it, and
   only then, it frosts and softens its foot with a short fade, scroll-driven with no script, in
@@ -765,7 +819,36 @@ panel.tab("emitter") // shows a tab; panel.tab() answers the one showing
   none show on every tab. The strip's underline slides to the chosen tab and the rows cross: what
   leaves folds away as what arrives unfolds, a moment behind. `⌥1`–`⌥9` pick a tab, and `[` / `]`
   cycle tabs when there's no preset strip. The tab last shown is remembered for these controls (and
-  in the session).
+  in the session). The preset strip sits under the tabs and crosses a tab change with the rows; a
+  tab that no preset or saved variant moves shows no strip at all (not even its `+`).
+- **Pinned groups.** Groups that apply to every tab (a global speed, a slow-motion switch) sit at
+  the top of the panel, under its one header and above the tab strip, and a tab change never moves
+  them. Name them on the store, `pinned: ["Global"]`, or say `pinned: true` on a field (the first
+  field of a group that says wins; a field without a group pins itself). A pinned field's `tab` is
+  ignored. Pinned groups keep their own die and reset. Presets and saved variants leave them out:
+  applying one keeps their values, saving one doesn't record them, a preset's chip doesn't drift
+  when they change, and their modified marks are against their defaults. Random rolls them freely
+  even under an active preset. The header's Random and Reset still cover everything, pinned
+  groups included, as they cover every tab; give a field `random: false` to keep it out of
+  Random. Keyboard order and search follow the panel top to bottom: pinned rows, the tabs, the
+  preset strip, then the tab's rows. `controls.isPinned(key)` says whether a key is pinned.
+  A pinned `variants: true` choice is an ordinary choice with a row: pinned wins, and its options
+  make no presets. A tab whose rows no preset moves shows no preset strip; a variants choice moves
+  every tab (or its own, if it names one).
+
+  ```ts
+  const motion = defineControls(
+    "motion",
+    {
+      speed: knob(1, { min: 0.25, max: 4, step: 0.05, unit: "×", group: "Global" }),
+      slow: toggle(false, { label: "Slow motion (0.25×)", group: "Global" }),
+      sidebars: spring({ duration: 0.3, bounce: 0 }, { group: "Sidebars", tab: "Sidebars" }),
+      hover: spring({ duration: 0.14, bounce: 0 }, { group: "Experiments", tab: "Experiments" }),
+    },
+    { pinned: ["Global"], defaultLabel: "Shipped", presets: { snappy, smooth, calm } },
+  )
+  motion.mount(el, { title: "Knobs", tabs: ["Sidebars", "Experiments"] })
+  ```
 - **Sub-headings.** Fields with the same `subsection` in a group sit under a flat heading inside the
   group's card, split off by a hairline (never a card inside a card). They're gathered: a group's
   rows without a sub-heading come first, then each sub-heading's rows together, in the order the
@@ -1335,6 +1418,23 @@ Click or `Enter` zooms a tile to fill the view, aspect-fit and centred: one cont
 
 The handle has `update(items)`, `zoom(id | null)`, `zoomed`, `active`, `focus(id?)`, `picks`, `pick(ids)`, `plan`, `moving`, `stats()` (the frame loop's script time) and `dispose()`; `onZoom` and `onActive` report changes. It takes the pieces' tokens and `restyle`, in dark and light; tiles round at `--k-ui-bento-radius` (3px), square under `--k-frame: flat`; `--k-ui-bento-bg` and `--k-ui-scrim` set the page under the tiles and the zoom. `planBento(aspects, { width, height, … })` is the layout on its own, with `bentoNeighbour`, `bentoWindow` and `fitRect`. `Bento` in `knobs/ui/react` and `knobs/ui/solid` follows `items` and `picks`. The demo is `examples/ideas.html` (`?n=500` for a big set, `?groups`, `?hero=3`, `?perf` for a frame-time readout, `?bench` to scroll and zoom on its own and report).
 
+### Infinite canvas
+
+```ts
+import { canvas } from "knobs/ui"
+
+const board = canvas(container, {
+  items: stories.map((s) => ({ id: s.id, title: s.name, render: (el) => s.mount(el) })),
+})
+board.focus("button-primary")
+```
+
+**`canvas(container, options)`** puts items on a dotted page that pans and zooms freely, as a components lab's grid. Items take `id`, `render(el)` (return a cleanup), `title` (shown above the card), `w`/`h` (the card's size; without them it takes its content's) and `x`/`y` (a place; items without one pack into rows under the placed ones, in order, the rows as wide as makes the set about the canvas's shape, or `width`). Each item is one hairline card; the dots scale with the zoom and fade out at the extremes; the edges fade over 16px (`--k-ui-canvas-fade`).
+
+Dragging the page, two-finger scrolling, or holding Space or the middle button and dragging anywhere pans; a pinch or `⌘`/`Ctrl`-scroll zooms around the pointer. Both follow the hand 1:1 and a fling coasts. What the hand didn't do springs (no bounce): `0` fits, `1` is 100%, `=`/`-` step 1.5×, and a double-click on an item focuses it (again, or on the page, fits). A mouse wheel's notch under `⌘` zooms directly too, at most 1.25× an event. Each jump zooms around the one point both views share, so everything on screen travels in a straight line. Items stay live: clicks and keys reach them, and a dragged Space still presses a focused button if nothing moved. Nothing moves on load: the first fit is instant, and until someone touches the view a change in size or content fits again. The world is one transformed layer; at rest its translate snaps to device pixels and, after a zoom, it's drawn again at the new scale so text is crisp.
+
+The handle has `fit()`, `focus(id)` (at most 200%), `zoomTo(scale, at?)`, `update(items)` (items that stay keep their content and glide to new places; new ones come in, gone ones soften out), `view`, `rects`, `moving`, `stats()` and `dispose()`; `onView` reports the view, `minZoom`/`maxZoom` (.05–8) bound it, `gap` (48) parts packed items, `padding` (48) frames a fit and `readout: false` drops the zoom pill. `layoutCanvas`, `packRows`, `fitView`, `zoomAround`, `viewPath` and `dotGrid` are the math on its own. `Canvas` in `knobs/ui/react` and `knobs/ui/solid` follows `items`. The demo is `examples/canvas.html` (`?n=200`, `?perf`).
+
 ### Review pieces (`knobs/review`)
 
 The walkthrough and what it shows (compare, player, code diff, history, facts, decision, taste test, `mediaSlot`) are their own subsystem: `knobs/review` (and `knobs/review/react`, `knobs/review/solid`). They have their own quiet look, `themes.review` (true black, flat, hairlines held to an APCA target, the platform's own face), one type scale and a short set of rules: [docs/review-design.md](docs/review-design.md), with every piece alone in `examples/review.html`. `knobs/ui` still exports them. `reviewFont(document, { href, sans: "Inter" })` gives the review look in a webfont.
@@ -1882,7 +1982,7 @@ The package has two core exports selected through the standard `development` con
 | Function | Behavior |
 | --- | --- |
 | `knob(value, { min, max, step?, unit?, decimals?, detents?, shortcut?, label?, group?, groupLabel?, section?, sectionLabel? })` | Numeric slider control with rolling readout and inline editor. `detents: false` lets drags glide through the default, the base and the middle. |
-| `choice(value, ["a", "b"], { label?, group?, shortcut? }?)` | Nonempty string choices with literal union inference. |
+| `choice(value, ["a", "b"], { label?, group?, shortcut?, labels?, display?, variants? }?)` | Nonempty string choices with literal union inference. `variants: true` makes the options the preset strip's chips, with no row (see [Versions of a design](#versions-of-a-design-variants-in-the-strip)). |
 | `toggle(value, { label?, group?, shortcut?, random? }?)` | Boolean switch control. Out of Random and Mutate unless `random: true`. |
 | `spring({ duration?, bounce? }?, meta?)` | SwiftUI-style spring: two sliders beside its live curve. |
 | `color("#hex" \| "oklch(L C H)" \| { l, c, h }, meta?)` | OKLCH colour kept inside sRGB, as an `oklch()` string; swatch, hex and hue/chroma/lightness strips. |
@@ -1896,7 +1996,8 @@ The package has two core exports selected through the standard `development` con
 | `range([low, high], { min, max, step?, unit? })` | One slider with two thumbs. |
 | `angle(degrees, { min?, max?, step?, wrap? })` | A dial, 0° up and clockwise; 0–360 wrapping by default. |
 | `seed(value, { min?, max? })` / `keybind(combo?)` | A whole number with a die; a captured key combination. Both stay out of Random and Mutate by default. |
-| `toolbar([{ id?, label, icon?, shortcut?, global?, disabled?, run? }])` | A row of buttons with shortcut chips; presses call `onAction(id)`. `shortcut` is a key, or `{ key, scope: "page" \| "panel" \| "none" }`; `toolbarShortcut(item)` reads either. |
+| `text(value?, { multiline?, placeholder? })` | Words in a field, or lines in a box that grows with them. Out of Random and Mutate. |
+| `toolbar([{ id?, label, icon?, shortcut?, global?, disabled?, run? }], { labels? })` | A row of buttons with shortcut chips; presses call `onAction(id)`. `shortcut` is a key, or `{ key, scope: "page" \| "panel" \| "none" }`; `toolbarShortcut(item)` reads either. |
 | `watch` / `sparkline` / `graph` / `meter` / `table` / `log` (`{ label?, unit?, decimals?, format?, hz?, get?, … }`) | Readout rows that hold no value; push with `controls.watch(key, value)`. See [Readouts](#readouts-live-values-sparklines-graphs-meters-tables-and-logs). |
 | `springCss(spring)` / `springMotion(spring)` / `bezierCss(curve)` / `colorHex(color)` | Turn values into CSS, ω/ζ, or hex. |
 | `fromDescriptors(descriptors)` | Converts runtime `ControlDescriptor[]` into a `Schema`. |
@@ -1969,6 +2070,7 @@ The package has two core exports selected through the standard `development` con
 | `optionPicker(container, { options, selected?, chosen?, onSelect?, onChoose?, body?, digits? })` | Options 1–n on a gliding card, the selected one's parameters (a panel) open under it. |
 | `bento(container, { items, gap?, tolerance?, rowHeight?, fit?, blur?, picks?, onPick?, onZoom?, onActive? })` | An ideas grid: a bento of images and live content that zooms an item to fill the view; picks with Space. |
 | `planBento(aspects, { width, height, gap?, tolerance?, rowHeight?, groups?, hero? })` | The bento's layout on its own: rects, mode, coverage and crop. |
+| `canvas(container, { items, gap?, padding?, width?, minZoom?, maxZoom?, readout?, onView? })` | An infinite canvas: items as cards on a dotted page that pans and zooms freely; `fit`, `focus(id)`, `zoomTo`. |
 | `walkthrough(container, { doc, onFeedback?, storage?, keys?, rail?, advance? })` / `mediaSlot(container, { media, steps? })` | The review page an agent writes (sections, steps, media from compares to histories, stacks and tables, notes and picks handed back); one step's media on its own. |
 | `overlayLook({ preset?, theme? })` | The look every overlay takes. |
 | `hints.register(root, () => targets, { listen?, rank? })` / `data-hint` | Joins the page's hint mode (`s`); `hints.start()`, `hints.stop()`. |

package/dist/dev/{chunk-3ygqgy1x.js → chunk-7kns3qe6.js}

@@ -1,24 +1,3 @@
-var __chunkGraphs, __chunkSeen, __chunkNonce, __preload = (id, seenOnly) => {
-  for (var [base, graph, ids] of __chunkGraphs || [])
-    for (var stack = [id], g = globalThis, d = g.document, head, j, node, k, link;j = stack.pop(); )
-      if (!__chunkSeen[j] && (node = graph[j])) {
-        __chunkSeen[j] = 1;
-        for (k = 1;k < node.length; k++)
-          stack.push(ids[node[k]]);
-        if (!seenOnly && j !== id && (head = d && d.head)) {
-          if (__chunkNonce === void 0)
-            __chunkNonce = (k = d.querySelector("meta[property=csp-nonce]")) && (k.nonce || k.getAttribute("nonce")) || "";
-          if (link = d.createElement("link"), link.rel = "modulepreload", link.crossOrigin = "", __chunkNonce)
-            link.nonce = __chunkNonce;
-          link.href = new g.URL(node[0], base), head.appendChild(link);
-        }
-      }
-}, __chunks = (base, ids, nodes, entry) => {
-  for (var graph = {}, i = 0;i < ids.length; i++)
-    graph[ids[i]] = nodes[i];
-  (__chunkGraphs ||= []).push([base, graph, ids]), __chunkSeen ||= {}, __preload(ids[entry], 1);
-};
-
 // src/core/color.ts
 var round = (n, places) => Number(n.toFixed(places)), clamp01 = (n) => Math.min(1, Math.max(0, n)), gamma = (c) => c <= 0.0031308 ? 12.92 * c : 1.055 * c ** 0.4166666666666667 - 0.055, linear = (c) => c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
 function oklchToLinear({ l, c, h }) {
@@ -516,6 +495,7 @@ var META_KEYS = [
   "folded",
   "sectionFolded",
   "tab",
+  "pinned",
   "subsection"
 ];
 function pickMeta(source, skip = []) {
@@ -527,7 +507,29 @@ function pickMeta(source, skip = []) {
   }
   return out;
 }
-var READOUT_KINDS = /* @__PURE__ */ new Set(["watch", "sparkline", "graph", "meter", "table", "log"]), isReadout2 = (field) => READOUT_KINDS.has(field.kind), hasValue2 = (field) => field.kind !== "action" && field.kind !== "toolbar" && !READOUT_KINDS.has(field.kind), SPRING2 = {
+var READOUT_KINDS = /* @__PURE__ */ new Set(["watch", "sparkline", "graph", "meter", "table", "log"]), isReadout2 = (field) => READOUT_KINDS.has(field.kind), hasValue2 = (field) => field.kind !== "action" && field.kind !== "toolbar" && !READOUT_KINDS.has(field.kind);
+function variantsOf(schema, isPinned = () => !1) {
+  let found;
+  for (let [key, field] of Object.entries(schema))
+    if (field.kind === "choice" && field.variants && !isPinned(key)) {
+      if (found)
+        throw Error(`Only one choice can hold the variants (${found.key}, ${key}).`);
+      found = { key, field };
+    }
+  return found;
+}
+function pinnedKeys(schema, groups = []) {
+  let byGroup = new Map(groups.map((g) => [g, !0]));
+  for (let f of Object.values(schema))
+    if (f.group !== void 0 && f.pinned !== void 0 && !byGroup.has(f.group))
+      byGroup.set(f.group, f.pinned);
+  let out = /* @__PURE__ */ new Set;
+  for (let [key, f] of Object.entries(schema))
+    if (f.group === void 0 ? f.pinned === !0 : byGroup.get(f.group) === !0)
+      out.add(key);
+  return out;
+}
+var SPRING2 = {
   duration: { min: 0.05, max: 2, step: 0.01 },
   bounce: { min: -0.5, max: 1, step: 0.01 }
 };
@@ -558,8 +560,9 @@ function choice2(value, options, meta) {
     value,
     options: Object.freeze([...options]),
     ...labels && Object.keys(labels).length ? { labels } : {},
-    ...meta?.display ? { display: meta.display } : {}
-  }, meta);
+    ...meta?.display ? { display: meta.display } : {},
+    ...meta?.variants ? { variants: !0 } : {}
+  }, meta?.variants ? { ...meta, random: meta.random ?? !1 } : meta);
 }
 function action2(label, meta) {
   let { shortcut, global, rebind, run, ...rest } = meta ?? {}, key = shortcutOf({ ...shortcut ? { shortcut } : {}, ...global ? { global } : {} }), combo = key ? normalizeCombo2(key.key) : "";
@@ -704,6 +707,17 @@ function keybind2(value = "", meta) {
   let field = { kind: "keybind", value: normalizeCombo2(value) };
   return withMeta(field, { random: !1, ...meta });
 }
+function text2(value = "", options) {
+  let { multiline, placeholder, ...meta } = options ?? {}, field = {
+    kind: "text",
+    value: "",
+    ...multiline ? { multiline: !0 } : {},
+    ...placeholder ? { placeholder } : {}
+  };
+  return withMeta({ ...field, value: normalizeText(field, value) }, { random: !1, ...meta });
+}
+var normalizeText = (field, input) => field.multiline ? input.replace(/\r\n?/g, `
+`) : input.replace(/\r\n?|\n/g, " ");
 function gradient2(stops, options = {}) {
   let value = normalizeStops(stops);
   if (!value)
@@ -758,7 +772,8 @@ function toolbar2(items, meta) {
     throw Error("A toolbar needs at least one item.");
   return withMeta({
     kind: "toolbar",
-    items: Object.freeze(items.map((item) => Object.freeze({ ...item })))
+    items: Object.freeze(items.map((item) => Object.freeze({ ...item }))),
+    ...meta?.labels !== void 0 ? { labels: meta.labels } : {}
   }, meta);
 }
 var readoutMeta = (o) => {
@@ -902,6 +917,8 @@ function normalizeField(field, input) {
       return typeof input === "number" && Number.isFinite(input) ? Math.round(Math.min(field.max, Math.max(field.min, input))) : field.value;
     case "keybind":
       return typeof input === "string" ? normalizeCombo2(input) : field.value;
+    case "text":
+      return typeof input === "string" ? normalizeText(field, input) : field.value;
     case "gradient":
       return normalizeStops(input) ?? field.value;
     case "curve":
@@ -1160,4 +1177,4 @@ function urlFlag2(name) {
 }
 var storageKey = (id, part) => `knobs:${encodeURIComponent(id)}:${part}:v1`;
 
-export { __preload, __chunks, maxChroma, oklchToRgb, parseColor2, fitColor, formatColor, colorHex2, EASINGS2, EASING_Y, easingName, bezierPoint2, bezierCss2, normalizeCombo2, letterOf2, comboFromEvent2, heldMods, matchesCombo2, comboParts2, comboLabel2, isTypingTarget, GRADIENT_SAMPLES, sampleGradient2, gradientSamples, gradientCss2, stopColorAt, sampleCurve2, curveSamples, CURVE_SHAPES2, inRange, sameRamp, randomStops, mutateStops, randomPoints, mutatePoints, pickMeta, isReadout2, hasValue2, SPRING2, valueKeys, knob2, choice2, action2, flatSpring2, toggle2, spring2, color2, point2, easing2, vec22, vec32, range2, angle2, seed2, keybind2, gradient2, curve2, toolbarShortcut2, actionShortcut2, toolbar2, watch2, sparkline2, graph2, meter2, table2, log2, wrapAngle2, normalizeField, normalize, isRecord, same, equal, Spring, springMotion2, springResponse, springEasing, springCss2, SPRINGS2, FADE, MOTION, reducedMotion, reducedSpring2, springLinear, DEFAULT_LINEAR, motionCss, RESHAPE, RESET_KEYS, REFRESHES, readoutState, pushReadout, READOUT, memoryStorage2, browserStorage, urlFlag2, storageKey };
+export { maxChroma, oklchToRgb, parseColor2, fitColor, formatColor, colorHex2, EASINGS2, EASING_Y, easingName, bezierPoint2, bezierCss2, normalizeCombo2, letterOf2, comboFromEvent2, heldMods, matchesCombo2, comboParts2, comboLabel2, isTypingTarget, GRADIENT_SAMPLES, sampleGradient2, gradientSamples, gradientCss2, stopColorAt, sampleCurve2, curveSamples, CURVE_SHAPES2, inRange, sameRamp, randomStops, mutateStops, randomPoints, mutatePoints, pickMeta, isReadout2, hasValue2, variantsOf, pinnedKeys, SPRING2, valueKeys, knob2, choice2, action2, flatSpring2, toggle2, spring2, color2, point2, easing2, vec22, vec32, range2, angle2, seed2, keybind2, text2, gradient2, curve2, toolbarShortcut2, actionShortcut2, toolbar2, watch2, sparkline2, graph2, meter2, table2, log2, wrapAngle2, normalizeField, normalize, isRecord, same, equal, Spring, springMotion2, springResponse, springEasing, springCss2, SPRINGS2, FADE, MOTION, reducedMotion, reducedSpring2, springLinear, DEFAULT_LINEAR, motionCss, RESHAPE, RESET_KEYS, REFRESHES, readoutState, pushReadout, READOUT, memoryStorage2, browserStorage, urlFlag2, storageKey };