@kitlangton/knobs 0.4.0-next.14 → 0.4.0-next.16

package/README.md

@@ -777,7 +777,19 @@ mountPanel(station, column, {
   foldable, starting folded. Its header folds and opens it with a click, Enter or Space; it's a ↑↓
   stop of its own, ← folds and → opens. `panel.fold(group, folded?)` does it from code. On a
   [full page](#full-page) the group's tile folds to its header, the cards below follow, and the
-  filter opens it while it runs.
+  filter opens it while it runs. Folded, the header sums the card up on its right, quietly and
+  live: a one-row card's value ("CSS orb"), otherwise its matching group preset (or "Custom"),
+  else its first changed value, else its first choice, then "· 2 changed". The title keeps its
+  room; the summary truncates first. `groupSummary(group, info)` on the mount replaces it, as on a
+  page (`info` is `{ preset, changed, keys }`; `null` shows nothing).
+- **Card descriptions.** A group's `groupDescription` (on any of its fields; the first wins) or the
+  store's `groupDescriptions` puts one muted line under its card's title, wrapping under the whole
+  header. Search matches it.
+- **What's active.** `onActive: (at) => …` hears which card or row the pointer or keyboard focus is
+  on: `{ group }` for a card's header or body, `{ group, key }` for a row, `null` for nothing
+  (pinned cards and group preset strips count). Whichever moved last wins; it's called at most once
+  a frame, never twice with the same value, and once more with `null` when the panel goes. Use it
+  to outline the part of your app a card changes. `mountPage` takes it too.
 - **Group Random by the host.** `groupRandom: (group, mode) => …` runs first for a group's die, `g`
   and `⌥G` (`mode` is `"random"` or `"mutate"`). Return `true` when the host rolled the group (its
   own seeded "Randomize <group>"): the die tumbles and knobs leaves the values alone. Return
@@ -838,8 +850,13 @@ panel.tab("emitter") // shows a tab; panel.tab() answers the one showing
 - **Keys presets leave alone, in place.** `inPresets: false` on a field, or `inPresets: { Motion:
   false }` on the store for a whole group, keeps presets, scoped presets and saved variants off
   those keys exactly as they stay off pinned ones (and a preset's chip stays lit when they move),
-  but the rows stay where they are. A pinned key is one of these, moved to the top.
-  `controls.inPresets(key)` says whether presets move a key.
+  but the rows stay where they are. A pinned key is one of these, moved to the top. The rule, for
+  `inPresets: false` and `pinned` groups alike: presets and variants from *other* scopes (the
+  panel-wide presets, tab scopes, other groups') leave the group alone, but a scope keyed by the
+  group's own name still moves it. So `inPresets: { Motion: false }` with
+  `scopedPresets: { Motion: { Snappy } }` gives Motion its own strip that state presets never
+  touch; its chips apply, save, match and mark only Motion. A field's own `inPresets: false` stays
+  out of every scope. `controls.inPresets(key)` says whether presets from other scopes move a key.
 - **Presets of a tab's own.** `scopedPresets` gives a tab (or a group) presets that belong to it:
   `{ Sidebars: { snappy, smooth, calm } }`. Its strip shows only on that tab, and a tab without any
   shows none. A scoped preset moves only its tab's (or group's) keys, never pinned ones or another
@@ -854,7 +871,8 @@ panel.tab("emitter") // shows a tab; panel.tab() answers the one showing
   group keeps Shipped, Snappy and Calm beside its knobs. Every strip's default chip reads `defaultLabel`; by scope,
   `defaultLabel: { "": "Empty", Motion: "Shipped" }` names each on its own. In code, `controls.preset(id, { scope })`, `activePreset(scope)` and
   `matchingPreset(scope)` take the tab or group, and `controls.scopeOf(key)` says whose presets
-  move a key (`""` for plain `presets`, undefined when pinned). An active preset saved while the
+  move a key (`""` for plain `presets`, the group's id for a pinned or `inPresets: false`
+  group with a scope of its own, else undefined when pinned). An active preset saved while the
   presets were panel-wide comes back on the scope that now has one by that id, and variants saved
   then start out in each scope they move.
 
@@ -1093,7 +1111,7 @@ A page with many sections reads better folded. `sectionFolded` starts sections f
 
 Folded things say what's in them. A folded group card trades its presets, reset and die for "Compact · 7 changed" (the matching group preset, or "Custom", then its changed rows; each part only when it applies). A folded section's heading reads "2 changed · 3 cards". `groupSummary(group, info)` and `sectionSummary(section, info)` on the mount replace either (`info` is a `FoldSummaryInfo`: `{ preset, changed, keys }`; return `null` for nothing). Group cards fold as in a panel, by a field's or descriptor's `folded`, or `groupFolded` on the mount, `defineControls` or `createRemoteControls` (both take `sectionFolded` too).
 
-Descriptions add one muted line under a title: `groupDescriptions` and `sectionDescriptions` by id (on the store, remote options or the mount), or `groupDescription` / `sectionDescription` on any field or descriptor (the first that gives one wins). `page.card({ description })` does the same for a custom card. The filter matches descriptions too.
+Descriptions add one muted line under a title: `groupDescriptions` and `sectionDescriptions` by id (on the store, remote options or the mount), or `groupDescription` / `sectionDescription` on any field or descriptor (the first that gives one wins). `page.card({ description })` does the same for a custom card. The filter matches descriptions too. Group descriptions show in panels as well, wrapping under the card's header.
 
 What the user folds and opens (sections and group cards) is remembered under `knobs:<id>:folds:v1` (`storageKey(id, "folds")`) as `{ sections: Record<string, boolean>, groups: Record<string, boolean> }`, and wins over `sectionFolded` and `groupFolded`. Only the user's folds and those made with `remember` are written; folds for context (`remember: false`, a highlight's `expand`) and the filter's never are. By default they go to the store's own storage, or nowhere with `persist: "none"`. `foldStorage` on the mount always wins and keeps folds only, never values, locks or variants, so a remote store on `storage: null` (the phone's values always win) can still remember them; `null` keeps none.
 
@@ -2033,11 +2051,12 @@ The package has two core exports selected through the standard `development` con
 | `unlock({ panel, sequence?, query?, corner?, persist? })` / `KONAMI` | Lets a production deploy be unlocked by a typed secret, `?knobs` or three corner taps; returns `{ unlocked, unlock(), lock(), dispose() }`. See [Show, hide and unlock](#show-hide-and-unlock). |
 | `action(label, { run, shortcut?, global?, rebind? })` / `flatSpring({ duration, bounce }, meta)` | A button row, with a shortcut its key cap can rebind; two flat number fields drawn as one spring card. `actionShortcut(field)` reads an action's shortcut as `{ key, scope }`. |
 | Field meta `random?`, `disabled?`, `readOnly?`, `folded?`, `tab?`, `subsection?` | On any field or descriptor: `random: false` stays out of Random and Mutate (switches, seeds and key combinations start out; `random: true` brings them in); `disabled` / `readOnly` (boolean or `(values) => boolean`) gate the row; `folded` makes its group foldable, starting folded; `tab` puts the row on a tab; `subsection` puts it under a sub-heading in its group. |
-| Field meta `groupDescription?: string`, `sectionDescription?: string`, `sectionFolded?: boolean` | On any field or descriptor, for pages (the first field of a group or section that gives one wins): a muted line under the card's title or the section's heading; `sectionFolded` makes the section foldable, starting folded. |
-| `mountPanel(controls, container, options?)` (`knobs/panel`) | An inline panel. Beside theme, density, renderer and keys: `preset`, `header` (`false` or `{ title?, buttons? }`), `crumbs` (`true` adds the scope line), `session`, `groupFolded`, `subsectionFolded`, `tabs`, `tab`, `onTab`, `search`, `groupRandom(group, mode)`, `rowAccessory(key)`, `marks`, `haptics`, `detents`, `sound`. The handle adds `panel.fold(group, folded?)`, `panel.tab(id?)`, `panel.search(query?, chips?)` (returns `{ query, chips }`) and `panel.updateAccessories()`. |
+| Field meta `groupDescription?: string`, `sectionDescription?: string`, `sectionFolded?: boolean` | On any field or descriptor (the first field of a group or section that gives one wins): a muted line under the card's title (in a panel or a page) or a page section's heading; `sectionFolded` makes a page section foldable, starting folded. |
+| `mountPanel(controls, container, options?)` (`knobs/panel`) | An inline panel. Beside theme, density, renderer and keys: `preset`, `header` (`false` or `{ title?, buttons? }`), `crumbs` (`true` adds the scope line), `session`, `groupFolded`, `groupSummary`, `onActive`, `subsectionFolded`, `tabs`, `tab`, `onTab`, `search`, `groupRandom(group, mode)`, `rowAccessory(key)`, `marks`, `haptics`, `detents`, `sound`. The handle adds `panel.fold(group, folded?)`, `panel.tab(id?)`, `panel.search(query?, chips?)` (returns `{ query, chips }`) and `panel.updateAccessories()`. |
 | `sound` (`knobs/panel`) | The page's sound effects (see **Sound**): `enabled`, `enable(on?)`, `volume`, `setVolume(v)`, `theme`, `setTheme("glass" \| "mech")`, `play(cue \| layers, detail?)`, `output()`, `subscribe(listener)`. Panels play only with `sound` on their mount. |
 | `mountPage(controls, container, options?)` (`knobs/panel`) | A full page of group cards in sections under a sticky header; `page.card({ title?, section?, element?, collapsed?, summary?, description? })` adds custom cards (`card.collapse(collapsed?)`, `card.collapsed`, `card.summary(content \| null)`), and `page.highlight({ groups?, sections? } \| null, { reveal?, expand? })` marks what's on screen. Options take `groupLabels`, `sectionLabels`, `groupDescriptions`, `sectionDescriptions`, `presetLabels`, `defaultLabel`, `groupPresetDisplay` and `groupFolded` over the store's. |
-| `MountPageOptions` folds | `sectionFolded?: SectionFolded` (`boolean \| Record<string, boolean>`), `foldStorage?: StoragePort \| null`, `nav?: boolean`, `groupSummary?(group, info: FoldSummaryInfo): string \| Node \| null`, `sectionSummary?(section, info: FoldSummaryInfo): string \| Node \| null`; `FoldSummaryInfo` is `{ preset: string \| null, changed: number, keys: readonly string[] }`. |
+| `MountPageOptions` folds | `sectionFolded?: SectionFolded` (`boolean \| Record<string, boolean>`), `foldStorage?: StoragePort \| null`, `nav?: boolean`, `groupSummary?(group, info: FoldSummaryInfo): string \| Node \| null` (a panel's option too), `sectionSummary?(section, info: FoldSummaryInfo): string \| Node \| null`; `FoldSummaryInfo` is `{ preset: string \| null, changed: number, keys: readonly string[] }`. |
+| `MountPanelOptions.onActive?: (at: PanelActive \| null) => void` | The card (`{ group }`) or row (`{ group, key }`) under the pointer or focus, `null` for nothing; on `mountPanel`, `controls.mount` and `mountPage`. At most once a frame, never the same value twice, and a last `null` when the panel goes. `PanelActive` is `{ group: string, key?: string }`. |
 | `page.fold(group: string, folded?: boolean, options?: PageFoldOptions): void` / `page.foldSection(section: string, folded?: boolean, options?: PageFoldOptions): void` / `page.sectionFolded(section: string): boolean` | Fold a group's card or a section or open it (toggles without `folded`), and ask which a section is. `PageFoldOptions` is `{ remember?: boolean, reveal?: boolean }`; `remember` defaults to `true`. |
 | `page.reveal(target: { section: string } \| { group: string }, options?: { remember?: boolean }): void` | Open a section (or a group's card and its section) and glide it into view; `remember` defaults to `false`. |
 | `page.sections(): readonly PageSectionInfo[]` / `page.onSections(listener: (sections: readonly PageSectionInfo[]) => void): () => void` | `PageSectionInfo` is `{ id, label, description?, folded, changed, groups: PageGroupInfo[] }`; `PageGroupInfo` is `{ id, label, folded, changed, preset: string \| null }`. |

package/dist/dev/{chunk-bejz4qcg.js → chunk-9y93net8.js}

@@ -2632,6 +2632,13 @@ ${GRAD_PROPS}
 .knobs-group-head .knobs-group-die{width:20px;padding:0;display:inline-flex;align-items:center;justify-content:center;border-radius:var(--_k-round);color:var(--_k-fg-3)}
 .knobs-group-head .knobs-group-die[disabled]{opacity:var(--k-disabled-opacity);cursor:default}
 .knobs-panel .knobs-group-head button:where(:not(.knobs-group-reset)){transition:background var(--k-hover-t),color var(--k-hover-t),opacity .2s,transform .12s}
+/* A panel card's header: its title, a folded card's summary and its buttons on one line, and its
+   description on the next. The title takes its room first; the summary gets what's left. */
+.knobs-panel:not(.knobs-page) .knobs-group-head{flex-wrap:wrap;row-gap:0}
+.knobs-panel:not(.knobs-page) .knobs-group-head>.knobs-group-label{flex:1000 1 0;max-width:max-content;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.knobs-group-head>.knobs-group-desc{order:1;flex:0 0 100%;padding:0;line-height:16px;white-space:normal;overflow:visible;text-wrap:pretty}
+.knobs-group-head>.knobs-group-summary{flex:1 1 0;max-width:max-content;margin-left:auto;font-size:var(--_k-text-meta);text-transform:none}
+.knobs-group-head[data-folded]>.knobs-group-summary:not(:empty){display:block}
 
 /* Grouped cards: rows share one surface, split by hairlines that stay put whatever a row is doing */
 .knobs-card{position:relative;margin-bottom:var(--k-section-gap);border-radius:var(--_k-radius);background:var(--_k-fill);overflow:hidden}
@@ -3338,7 +3345,7 @@ ${POINTER_ROW} .knobs-slider.knobs-modified:not(:hover,.knobs-active) .knobs-val
 .knobs-group-summary{display:none;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--_k-fg-3);font-size:var(--_k-text-control);font-weight:500;letter-spacing:0;font-variant-numeric:tabular-nums}
 .knobs-tile[data-folded]>.knobs-group-head .knobs-group-summary:not(:empty){display:block}
 .knobs-tile[data-folded]>.knobs-group-head .knobs-group-ctl{display:none}
-.knobs-tile[data-fold-motion]>.knobs-group-head :is(.knobs-group-summary,.knobs-group-ctl){animation:knobs-fade .2s var(--k-ease) both}
+.knobs-tile[data-fold-motion]>.knobs-group-head :is(.knobs-group-summary,.knobs-group-ctl),.knobs-group-head[data-fold-motion]>.knobs-group-summary{animation:knobs-fade .2s var(--k-ease) both}
 /* A highlight (page.highlight): the rest dims under a veil of the page's colour (--k-page-dim at
    full), and what's highlighted on its own gets a dot in the gutter by its title. The veil and
    dot are written each frame on the panel spring (see page.ts). */

package/dist/dev/{chunk-s7d5a8vb.js → chunk-e5hbs8fe.js}

@@ -119,7 +119,7 @@ import {
   createHintController,
   pageHints,
   toggleLayer
-} from "./chunk-bejz4qcg.js";
+} from "./chunk-9y93net8.js";
 
 // src/panel/die.ts
 var ROUND = 16 * Math.sqrt(5), DIE = { half: 64 + ROUND, round: ROUND, pip: 12 }, PIPS = {
@@ -4734,6 +4734,33 @@ class GpuOverlayManager {
     let clipped = width > 0 && el.scrollWidth > el.clientWidth;
     return this.clipCache.set(el, { key, text, width, clipped }), clipped;
   }
+  lineCache = /* @__PURE__ */ new WeakMap;
+  linesOf(el, width) {
+    let text = el.textContent ?? "", hit = this.lineCache.get(el);
+    if (hit && hit.text === text && hit.width === width)
+      return hit.lines;
+    let lines = [], node = el.firstChild;
+    if (node?.nodeType === Node.TEXT_NODE) {
+      let top = el.getBoundingClientRect().top, range = el.ownerDocument.createRange(), line, flush = () => {
+        if (line)
+          lines.push({
+            text: text.slice(line.from, line.to),
+            y: (line.top + line.bottom) / 2 - top
+          });
+      };
+      for (let word of text.matchAll(/\S+/g)) {
+        let from = word.index, to = from + word[0].length;
+        range.setStart(node, from), range.setEnd(node, to);
+        let r = range.getBoundingClientRect();
+        if (line && Math.abs(r.top - line.top) < 1)
+          line.to = to, line.bottom = Math.max(line.bottom, r.bottom);
+        else
+          flush(), line = { from, to, top: r.top, bottom: r.bottom };
+      }
+      flush();
+    }
+    return this.lineCache.set(el, { text, width, lines }), lines;
+  }
   curReduced = !1;
   curLocks;
   curSelected = 0;
@@ -6146,12 +6173,10 @@ class GpuOverlayManager {
             this.drawText(this.fit(g.labelEl.textContent ?? "", lr.width, px, tokens.titleWeight), lr.left, cy, withAlpha(tokens.text, 1 - peek), { px, weight: tokens.titleWeight, track: -0.01 });
           if (g.peek && peek > 0.005)
             this.drawText(this.fit(g.peek.textContent ?? "", lr.width, px, tokens.titleWeight), lr.left, cy, withAlpha(tokens.text, peek), { px, weight: tokens.titleWeight, track: -0.01 });
-        } else
-          this.drawText(tokens.groupUpper ? (g.labelEl.textContent ?? "").toUpperCase() : g.labelEl.textContent ?? "", lr.left, lr.top + lr.height * 0.5, tokens.groupColor, {
-            px: Math.max(9, tokens.groupSize),
-            weight: tokens.titleWeight,
-            track: tokens.groupTracking
-          });
+        } else {
+          let label = tokens.groupUpper ? (g.labelEl.textContent ?? "").toUpperCase() : g.labelEl.textContent ?? "", px = Math.max(9, tokens.groupSize);
+          this.drawText(this.domClipped(g.labelEl, label, lr.width) ? this.fit(label, lr.width, px, tokens.titleWeight, void 0, tokens.groupTracking, !0) : label, lr.left, lr.top + lr.height * 0.5, tokens.groupColor, { px, weight: tokens.titleWeight, track: tokens.groupTracking });
+        }
         if (!g.title && tokens.groupDivider[3] > 0 && g.element.previousElementSibling)
           this.pushPrim({
             x: gr.left,
@@ -6162,13 +6187,14 @@ class GpuOverlayManager {
             kind: 1
           });
         if (g.desc && !g.desc.hidden) {
-          let r = this.rectOf(g.desc), cs = getComputedStyle(g.desc), left = r.left + (parseFloat(cs.paddingLeft) || 0), w = r.width - (parseFloat(cs.paddingLeft) || 0) - (parseFloat(cs.paddingRight) || 0);
-          this.drawText(this.fit(g.desc.textContent ?? "", w + 0.5, tokens.textMeta, tokens.labelWeight), left, r.top + r.height * 0.5, tokens.dim, { px: tokens.textMeta, weight: tokens.labelWeight });
+          let r = this.rectOf(g.desc), cs = getComputedStyle(g.desc), left = r.left + (parseFloat(cs.paddingLeft) || 0), w = r.width - (parseFloat(cs.paddingLeft) || 0) - (parseFloat(cs.paddingRight) || 0), lines = cs.whiteSpace.includes("nowrap") ? [{ text: g.desc.textContent ?? "", y: r.height * 0.5 }] : this.linesOf(g.desc, r.width);
+          for (let line of lines)
+            this.drawText(this.fit(line.text, w + 0.5, tokens.textMeta, tokens.labelWeight), left, r.top + line.y, tokens.dim, { px: tokens.textMeta, weight: tokens.labelWeight });
         }
         let fadeIn = (node) => node.parentElement?.closest("[data-fold-motion]") ? Number(getComputedStyle(node).opacity) || 0 : 1;
         if (g.summary && g.summary.getClientRects().length) {
-          let r = this.rectOf(g.summary), a = fadeIn(g.summary);
-          this.drawText(this.fit(g.summary.textContent ?? "", r.width + 0.5, tokens.textControl, 500), r.left, r.top + r.height * 0.5, withAlpha(tokens.dim, a), { px: tokens.textControl, weight: 500 });
+          let r = this.rectOf(g.summary), a = fadeIn(g.summary), px = g.title ? tokens.textControl : tokens.textMeta;
+          this.drawText(this.fit(g.summary.textContent ?? "", r.width + 0.5, px, 500), r.left, r.top + r.height * 0.5, withAlpha(tokens.dim, a), { px, weight: 500 });
         }
         let ctlShown = !g.controls || g.controls.getClientRects().length > 0, headAlpha = this.curAlpha;
         if (g.controls && ctlShown)
@@ -14439,6 +14465,79 @@ function createLens(o) {
   };
 }
 
+// src/panel/active.ts
+var same2 = (a, b) => a === b || a !== null && b !== null && a.group === b.group && a.key === b.key;
+function activeReporter(resolve, report, schedule) {
+  let hover = null, focus = null, lead = "pointer", last = null, cancel, flush = () => {
+    cancel = void 0;
+    let [first, second] = lead === "pointer" ? [hover, focus] : [focus, hover], at = resolve(first) ?? resolve(second);
+    if (same2(at, last))
+      return;
+    last = at, report(at);
+  }, touch = () => {
+    cancel ??= schedule(flush);
+  };
+  return {
+    pointer(target) {
+      if (hover = target, target !== null)
+        lead = "pointer";
+      touch();
+    },
+    focus(target) {
+      if (focus = target, target !== null)
+        lead = "focus";
+      touch();
+    },
+    dispose() {
+      if (cancel?.(), cancel = void 0, hover = focus = null, last !== null)
+        report(last = null);
+    }
+  };
+}
+function activeEvents(reporter, where) {
+  let inMenu = !1;
+  return {
+    over(e) {
+      reporter.pointer(e.target);
+    },
+    move(e) {
+      if (e.movementX || e.movementY)
+        reporter.pointer(e.target);
+    },
+    out(e) {
+      if (where(e.relatedTarget) !== "inside")
+        reporter.pointer(null);
+    },
+    focusIn(e) {
+      let at = where(e.target);
+      if (inMenu = at === "menu", at === "inside")
+        reporter.focus(e.target);
+      else if (at === "outside")
+        reporter.focus(null);
+    },
+    focusOut(e) {
+      if (e.relatedTarget !== null)
+        return;
+      let at = where(e.target);
+      if (at === "inside" || at === "menu" && inMenu)
+        inMenu = !1, reporter.focus(null);
+    }
+  };
+}
+function watchActive(root, resolve, report) {
+  let doc = root.ownerDocument, win = doc.defaultView, reporter = activeReporter(resolve, report, (flush) => {
+    let id = win.requestAnimationFrame(flush);
+    return () => win.cancelAnimationFrame(id);
+  }), events = activeEvents(reporter, (node) => node instanceof Node && root.contains(node) ? "inside" : node instanceof Element && node.closest(".knobs-menu") ? "menu" : "outside"), el = (node) => node, over = (e) => events.over({ target: el(e.target) }), move = (e) => events.move({ target: el(e.target), movementX: e.movementX, movementY: e.movementY }), out = (e) => events.out({ relatedTarget: el(e.relatedTarget) }), focusIn = (e) => events.focusIn({ target: el(e.target) }), focusOut = (e) => events.focusOut({ target: el(e.target), relatedTarget: el(e.relatedTarget) });
+  if (root.addEventListener("pointerover", over), root.addEventListener("pointermove", move), root.addEventListener("pointerout", out), doc.addEventListener("focusin", focusIn), doc.addEventListener("focusout", focusOut), doc.activeElement && root.contains(doc.activeElement))
+    reporter.focus(doc.activeElement);
+  return {
+    dispose() {
+      root.removeEventListener("pointerover", over), root.removeEventListener("pointermove", move), root.removeEventListener("pointerout", out), doc.removeEventListener("focusin", focusIn), doc.removeEventListener("focusout", focusOut), reporter.dispose();
+    }
+  };
+}
+
 // src/panel/has.ts
 function trackHas(root) {
   let doc = root.ownerDocument, win = doc.defaultView, marked = { fv: [], active: [] }, mark = (list, name, nodes, value = "") => {
@@ -14915,6 +15014,19 @@ function createPresence(root, options) {
   };
 }
 
+// src/panel/summary.ts
+function panelFoldSummary(rows, preset) {
+  if (rows.length === 1 && rows[0].value)
+    return rows[0].value;
+  let lead = preset ?? rows.find((r) => r.changed && r.value)?.value ?? rows.find((r) => r.choice && r.value)?.value, changed = rows.filter((r) => r.changed).length;
+  return [lead, changed ? `${changed} changed` : ""].filter(Boolean).join(" · ");
+}
+var baseSignature = (controls) => JSON.stringify([
+  controls.activePreset(),
+  Object.keys(controls.scopes).map((s) => controls.activePreset(s)),
+  Object.keys(controls.groupPresets).map((g) => controls.activeGroupPreset(g))
+]);
+
 // src/panel/panel.ts
 var layer = 2147480001, COPIED_MS = 1000, lastTab = /* @__PURE__ */ new Map, REVEAL_QUIET_MS = 2000, NUDGE_BURST_MS = 300;
 function readableTitle(id) {
@@ -15339,16 +15451,17 @@ function buildPanel(controls, host, options) {
       foldTile(card, next && !filterEl.value.trim(), animate);
     else
       applyVisibility(animate ? "reveal" : "instant");
+    let marked = page ? card.parentElement : head;
+    if (marked) {
+      if (marked.toggleAttribute("data-folded", next), animate)
+        marked.setAttribute("data-fold-motion", ""), clearTimeout(foldMotions.get(marked)), foldMotions.set(marked, setTimeout(() => marked.removeAttribute("data-fold-motion"), 400));
+    }
     if (page) {
-      let tile = card.parentElement;
-      if (tile.toggleAttribute("data-folded", next), animate)
-        tile.setAttribute("data-fold-motion", ""), clearTimeout(foldMotions.get(tile)), foldMotions.set(tile, setTimeout(() => tile.removeAttribute("data-fold-motion"), 400));
       if (remember)
         foldsKept?.set("groups", group, next);
-      refreshFolds();
     } else if (sessionKept)
       writeSession(controls.id, { groups: { ...readSession(controls.id).groups, [group]: next } });
-    positioned?.constrain(), wakeGpu();
+    refreshFolds(), positioned?.constrain(), wakeGpu();
   }
   function foldTile(card, shut, animate) {
     if ((!card.hidden && card.dataset.leaving !== "true") !== shut)
@@ -15444,11 +15557,13 @@ function buildPanel(controls, host, options) {
       desc.className = "knobs-group-desc", groupDescs.set(groupName, desc), describeGroup(groupName);
     }
     if (foldAt !== void 0) {
-      if (page)
-        summary = el("span"), summary.className = "knobs-group-summary", gRight.append(summary), groupSummaries.set(groupName, summary);
-      caret = caretSvg(), gRight.append(caret), gHead.dataset.foldable = "", gHead.tabIndex = -1, gHead.setAttribute("role", "button"), gHead.setAttribute("aria-label", title);
+      if (summary = el("span"), summary.className = "knobs-group-summary", page)
+        gRight.append(summary);
+      groupSummaries.set(groupName, summary), caret = caretSvg(), gRight.append(caret), gHead.dataset.foldable = "", gHead.tabIndex = -1, gHead.setAttribute("role", "button"), gHead.setAttribute("aria-label", title);
       let folded = (page ? foldsKept?.get("groups", groupName) : session.groups?.[groupName]) ?? foldAt;
-      folds.set(groupName, folded), gHead.setAttribute("aria-expanded", String(!folded)), gHead.addEventListener("click", (event) => {
+      if (folds.set(groupName, folded), gHead.setAttribute("aria-expanded", String(!folded)), !page)
+        gHead.toggleAttribute("data-folded", folded);
+      gHead.addEventListener("click", (event) => {
         if (event.detail > 1 || event.target.closest("button"))
           return;
         byUser(() => fold(groupName));
@@ -15457,8 +15572,10 @@ function buildPanel(controls, host, options) {
     if (page) {
       let gTitle = el("span");
       gTitle.className = "knobs-group-title", gTitle.append(gLabel, gPeek), gHead.append(gTitle, gRight);
-    } else
-      gHead.append(gLabel, gRight);
+    } else {
+      let desc = el("span");
+      desc.className = "knobs-group-desc", groupDescs.set(groupName, desc), describeGroup(groupName), gHead.append(gLabel, desc, ...summary ? [summary] : [], gRight);
+    }
     return gpuGroups.push({
       element: gHead,
       labelEl: gLabel,
@@ -16107,7 +16224,7 @@ function buildPanel(controls, host, options) {
           }
           under = name, nodes.push(r.row);
         }
-        let strip = run.group !== void 0 && !run.pinned && !stripped.has(run.group) ? groupStripFor(run.group) : void 0;
+        let strip = run.group !== void 0 && !stripped.has(run.group) ? groupStripFor(run.group) : void 0;
         if (strip)
           stripped.add(run.group);
         if (arrange(block.card, strip ? [strip.element, ...nodes] : nodes), animate && at >= 0) {
@@ -16116,6 +16233,8 @@ function buildPanel(controls, host, options) {
               motion.push({ node: r.row, show: !0 });
         }
       }
+      for (let group of groupDescs.keys())
+        describeGroup(group);
       for (let [id, sh] of subheads)
         if (!usedSubheads.has(id)) {
           sh.el.remove();
@@ -16166,9 +16285,7 @@ function buildPanel(controls, host, options) {
       let stagger = cascade(motion.length);
       motion.forEach((m, i) => present(m.node, m.show, i * stagger, m.after));
     }
-    if (applyVisibility(animate ? "reveal" : "instant"), page)
-      refreshFolds();
-    if (focused && root.contains(focused) && doc.activeElement !== focused && focused.isConnected)
+    if (applyVisibility(animate ? "reveal" : "instant"), refreshFolds(), focused && root.contains(focused) && doc.activeElement !== focused && focused.isConnected)
       focused.focus({ preventScroll: !0 });
     let gone = focused ? leaving.find((r) => r.row.contains(focused)) : void 0;
     if (gone) {
@@ -16293,7 +16410,7 @@ function buildPanel(controls, host, options) {
     return selectTab(list[(at + direction + list.length) % list.length].id, !1), !0;
   }, searching = () => search?.filtering() ?? !1, rowMatches = (r) => {
     let query = search.query();
-    if (query && !matchesFilter(query, r.display, r.key, r.group, r.group && groupTitle(r.group), r.field.subsection))
+    if (query && !matchesFilter(query, r.display, r.key, r.group, r.group && groupTitle(r.group), r.group && groupDescription(r.group), r.field.subsection))
       return !1;
     for (let chip of search.active())
       if (!r.keys.some((k) => chipTests.get(chip)?.(k)))
@@ -16585,11 +16702,7 @@ function buildPanel(controls, host, options) {
     if (changed)
       wakeGpu();
   }
-  let shownBase = "", baseSignature = () => JSON.stringify([
-    controls.activePreset(),
-    Object.keys(controls.scopes).map((s) => controls.activePreset(s)),
-    Object.keys(controls.groupPresets).map((g) => controls.activeGroupPreset(g))
-  ]);
+  let shownBase = "";
   function update() {
     if (!controls.enabled) {
       close?.();
@@ -16608,7 +16721,7 @@ function buildPanel(controls, host, options) {
         if (!fresh(r) && changed(r))
           changedCount++;
     }
-    let stagger = initialized ? cascade(changedCount) : 0, moving = initialized ? rows.filter(changed) : rows;
+    let stagger = initialized ? cascade(changedCount) : 0, moving = initialized ? rows.filter(changed) : rows, rebasing = baseSignature(controls) !== shownBase;
     if (updateStrips(), batchMeasures(() => {
       for (let row of moving)
         if (row.slider?.prime(), row.editor?.prime?.(), row.choice)
@@ -16616,7 +16729,7 @@ function buildPanel(controls, host, options) {
       for (let chips of groupChips.values())
         primeSegPill(chips.seg, chips.buttons);
       showValues(values, moving, stagger, landing);
-    }), moving.length || !initialized)
+    }), moving.length || !initialized || rebasing)
       refreshFolds();
     shown = values, initialized = !0, wakeGpu();
   }
@@ -16636,7 +16749,7 @@ function buildPanel(controls, host, options) {
     }
   }
   function showValues(values, moving, stagger, landing) {
-    let baseline = controls.baseValues(), fresh = (r) => r.row.dataset.shown === void 0, now = performance.now(), turn = 0, based = baseSignature(), rebased = based !== shownBase;
+    let baseline = controls.baseValues(), fresh = (r) => r.row.dataset.shown === void 0, now = performance.now(), turn = 0, based = baseSignature(controls), rebased = based !== shownBase;
     shownBase = based;
     for (let row of moving) {
       let instant = !initialized || landing || fresh(row);
@@ -16889,16 +17002,45 @@ function buildPanel(controls, host, options) {
     preset: null,
     changed: changedRows((r) => r.section === section),
     keys: rows.filter((r) => r.section === section).flatMap((r) => r.keys)
-  }), changedText = (n) => n && marks ? `${n} changed` : "";
+  }), changedText = (n) => n && marks ? `${n} changed` : "", valueText = (r, values) => {
+    let f = r.field, v = r.value(values), num = (n) => String(Number(n.toFixed(2)));
+    switch (f.kind) {
+      case "choice":
+        return f.labels?.[v] ?? String(v);
+      case "toggle":
+        return v ? "On" : "Off";
+      case "knob":
+        return `${v.toFixed(f.decimals ?? decimals(f.step))}${f.unit ? ` ${f.unit}` : ""}`;
+      case "spring": {
+        let { duration, bounce } = v;
+        return `${num(duration)} s${bounce ? `, bounce ${num(bounce)}` : ""}`;
+      }
+      case "color":
+        return colorHex2(v);
+      case "text":
+        return String(v);
+      default:
+        return "";
+    }
+  }, groupSummary = (group) => {
+    let info = groupInfo(group);
+    if (options.groupSummary)
+      return options.groupSummary(group, info);
+    if (page)
+      return [info.preset, changedText(info.changed)].filter(Boolean).join(" · ") || null;
+    let values = controls.get(), own = rows.filter((r) => r.group === group && !r.leaving && r.keys.length);
+    return panelFoldSummary(own.map((r) => ({
+      value: valueText(r, values),
+      changed: marks && r.keys.some((k) => controls.isModified(k)),
+      choice: r.field.kind === "choice"
+    })), info.preset) || null;
+  };
   function refreshFolds() {
+    for (let [group, node] of groupSummaries)
+      if (folds.get(group))
+        putSummary(node, groupSummary(group));
     if (!layout || !page)
       return;
-    for (let [group, node] of groupSummaries) {
-      if (!folds.get(group))
-        continue;
-      let info = groupInfo(group);
-      putSummary(node, page.groupSummary ? page.groupSummary(group, info) : [info.preset, changedText(info.changed)].filter(Boolean).join(" · ") || null);
-    }
     for (let s of layout.sectionList()) {
       let node = s.label?.querySelector(":scope > .knobs-section-summary");
       if (!node || !s.folded)
@@ -18050,7 +18192,15 @@ function buildPanel(controls, host, options) {
     attributes: !0,
     attributeFilter: ["data-knobs-renderer", "data-theme", "data-appearance", "class", "style"]
   });
-  let panel = {
+  let onActive = options.onActive, active = onActive ? watchActive(root, (node) => {
+    if (!node || !root.contains(node))
+      return null;
+    let r = rows.find((r) => !r.leaving && r.row.contains(node));
+    if (r)
+      return r.group === void 0 ? null : { group: r.group, key: r.key };
+    let card = node.closest("[data-group]");
+    return card && root.contains(card) ? { group: card.dataset.group } : null;
+  }, onActive) : void 0, panel = {
     element: root,
     presetStrip,
     focus() {
@@ -18113,7 +18263,7 @@ function buildPanel(controls, host, options) {
         doc.removeEventListener(type, onPointerUp, !0);
       for (let type of ["pointerup", "pointercancel"])
         doc.removeEventListener(type, endScrub, !0);
-      doc.defaultView?.removeEventListener("blur", endScrub), endScrub(), unregisterHints?.(), hintCtrl.stop(), modeObserver.disconnect(), unregisterGpu?.(), lens.dispose(), win?.cancelAnimationFrame(lensFrame), doc.removeEventListener("pointerdown", onPress, !0), doc.removeEventListener("pointerup", onRelease, !0), doc.removeEventListener("pointercancel", onRelease, !0), crumbs?.dispose(), clearTimeout(escTimer), win?.removeEventListener("blur", queueScope), win?.removeEventListener("focus", queueScope), unsubscribe(), unlisten?.(), rowsObserver.disconnect(), gpuObserver.disconnect(), doc.defaultView?.cancelAnimationFrame(landTimer);
+      doc.defaultView?.removeEventListener("blur", endScrub), endScrub(), unregisterHints?.(), hintCtrl.stop(), modeObserver.disconnect(), unregisterGpu?.(), lens.dispose(), win?.cancelAnimationFrame(lensFrame), doc.removeEventListener("pointerdown", onPress, !0), doc.removeEventListener("pointerup", onRelease, !0), doc.removeEventListener("pointercancel", onRelease, !0), crumbs?.dispose(), active?.dispose(), clearTimeout(escTimer), win?.removeEventListener("blur", queueScope), win?.removeEventListener("focus", queueScope), unsubscribe(), unlisten?.(), rowsObserver.disconnect(), gpuObserver.disconnect(), doc.defaultView?.cancelAnimationFrame(landTimer);
       for (let k of inHand)
         controls.hold(k, !1);
       inHand.clear(), positioned?.dispose(), die.dispose();

package/dist/dev/{chunk-f0e5tkqg.js → chunk-exaya50m.js}

@@ -6,7 +6,7 @@ import {
   writeSession,
   injectStyles,
   toggleLayer
-} from "./chunk-bejz4qcg.js";
+} from "./chunk-9y93net8.js";
 
 // src/panel/attach.ts
 function attach(controls, element, options = {}) {
@@ -82,7 +82,7 @@ function attach(controls, element, options = {}) {
       return;
     loading = !0;
     try {
-      let { createPanel } = await import("./chunk-s7d5a8vb.js");
+      let { createPanel } = await import("./chunk-e5hbs8fe.js");
       if (disposed || !controls.enabled || panel)
         return;
       if (panel = createPanel(controls, element, close, { restored, chip }), remember)

package/dist/dev/index.js

@@ -625,9 +625,13 @@ function defineControls(id, input, options = {}) {
       named.add(variants);
     let of = /* @__PURE__ */ new Map;
     for (let k of valueKeys(schema)) {
-      if (presetFree().has(k))
+      let f = fields[k];
+      if (presetFree().has(k)) {
+        if (f.inPresets !== !1 && f.group !== void 0 && named.has(f.group))
+          of.set(k, f.group);
         continue;
-      let f = fields[k], tab = tabOf(f);
+      }
+      let tab = tabOf(f);
       of.set(k, tab !== void 0 && named.has(tab) ? tab : f.group !== void 0 && named.has(f.group) ? f.group : "");
     }
     return scopingOf = { schema, of, named: [...named], variants }, scopingOf;
@@ -1522,11 +1526,11 @@ function defineControls(id, input, options = {}) {
     code: (format, values) => formatCode(values ?? get(), format),
     variants,
     attach(element, chip) {
-      let load = options.ship ? () => options.ship().then((m) => m.attach) : () => import("./chunk-f0e5tkqg.js").then((m) => m.attach);
+      let load = options.ship ? () => options.ship().then((m) => m.attach) : () => import("./chunk-exaya50m.js").then((m) => m.attach);
       return live(load, (attach) => attach(controls, element, chip), (detach) => detach());
     },
     mount(container, mountOptions) {
-      let load = options.ship ? () => options.ship().then((m) => m.mountPanel) : () => import("./chunk-s7d5a8vb.js").then((m) => m.mountPanel);
+      let load = options.ship ? () => options.ship().then((m) => m.mountPanel) : () => import("./chunk-e5hbs8fe.js").then((m) => m.mountPanel);
       return live(load, (mountPanel) => {
         let panel = mountPanel(controls, container, mountOptions);
         return mountOptions?.onReady?.(panel), panel;

package/dist/index.js

@@ -1688,9 +1688,13 @@ function defineControls(id, input, options = {}) {
       named.add(variants);
     let of = /* @__PURE__ */ new Map;
     for (let k of valueKeys(schema)) {
-      if (presetFree().has(k))
+      let f = fields[k];
+      if (presetFree().has(k)) {
+        if (f.inPresets !== !1 && f.group !== void 0 && named.has(f.group))
+          of.set(k, f.group);
         continue;
-      let f = fields[k], tab = tabOf(f);
+      }
+      let tab = tabOf(f);
       of.set(k, tab !== void 0 && named.has(tab) ? tab : f.group !== void 0 && named.has(f.group) ? f.group : "");
     }
     return scopingOf = { schema, of, named: [...named], variants }, scopingOf;