isotone 1.1.2 → 1.1.3

package/dist/core.d.ts

@@ -212,7 +212,7 @@ interface OverlayVariantStatus extends OverlayVariant {
     missing: string[];
 }
 /**
- * A knob: a range or colour axis the host declares in `.isotone/knobs.json`
+ * A knob: a range, colour or select axis the host declares in `.isotone/knobs.json`
  * next to its overlay variants. The panel renders it as a slider (or a colour
  * pick) on the routes it names, and the value reaches the page as a CSS
  * custom property on `<html>`, `--knob-<id>`, with the axis unit appended
@@ -220,8 +220,12 @@ interface OverlayVariantStatus extends OverlayVariant {
  * committed default: `var(--knob-fade-from, 0%)`. "Save as defaults" files
  * the moved knobs in the same `[set-defaults]` note as the variant picks, so
  * the agent writes the numbers into the source and the knob file.
+ *
+ * A select knob's value is its option id, which CSS cannot branch on through a
+ * custom property, so it also lands as `data-knob-<id>` on `<html>`. Code that
+ * draws for itself listens for {@link KNOBS_EVENT} on the document.
  */
-type KnobAxis = (RangeVariantAxis | ColorVariantAxis) & {
+type KnobAxis = (RangeVariantAxis | ColorVariantAxis | SelectVariantAxis) & {
     /** Route pattern(s) the knob belongs on, like a variant's `route`; absent means every route. */
     route?: string | string[];
 };
@@ -235,7 +239,11 @@ interface OverlayVariantsList {
 }
 /** The custom property a knob writes: `--knob-<id>`. */
 declare function knobVar(id: string): string;
-/** The property's value: a range carries its unit, a colour is its hex. */
+/** Fired on `<html>`, bubbling, when a knob's value changes. `detail` is
+ *  `{ id, value }` with the same value the custom property holds, or `null`
+ *  when the knob went back to its default. */
+declare const KNOBS_EVENT = "isotone:knob";
+/** The property's value: a range carries its unit, a colour is its hex, a select is the option id. */
 declare function knobCssValue(axis: KnobAxis, value: string): string;
 /** The knobs that belong on `route`. */
 declare function knobsFor(knobs: KnobAxis[] | undefined, route: string): KnobAxis[];
@@ -245,6 +253,10 @@ declare function applyKnobValues(knobs: KnobAxis[], values: VariantSelections, r
         setProperty(name: string, value: string): void;
         removeProperty(name: string): void;
     };
+    setAttribute?(name: string, value: string): void;
+    removeAttribute?(name: string): void;
+    getAttribute?(name: string): string | null;
+    dispatchEvent?(event: Event): boolean;
 }): void;
 /** The knobs that sit off their default, with the value the panel showed. */
 declare function knobDelta(knobs: KnobAxis[], values: VariantSelections): {
@@ -344,8 +356,25 @@ interface IterationElement {
     tag: string;
     /** Trimmed text-content snippet (may be empty for visual elements). */
     text: string;
-    /** Best-effort CSS path for locating the element in code. */
+    /** CSS path to the element. A pin made in a browser matches only this element. */
     selector: string;
+    /** Identifying attributes: role, name, aria-label, data-*, class and so on. */
+    attributes?: Record<string, string>;
+    /** React components around the element, outermost first. */
+    component?: string[];
+    /** `file:line` of the JSX, where the host's React still records it. */
+    source?: string;
+    /** Labelled or headed ancestors, outermost first. */
+    within?: string[];
+    /** The closest ancestor's text, for an element with none of its own. */
+    near?: string;
+    /** Where it sat on the page when pinned, in CSS pixels from the document's corner. */
+    rect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
 }
 /** A durable reference to a selector or one of its options, not a DOM path. */
 interface VariantReference {
@@ -399,12 +428,18 @@ interface NodeLike {
     textContent?: string | null;
     /** One-based child position, when the adapter can provide it cheaply. */
     indexInParent?: number;
+    /** Whether a selector finds this node and nothing else. Without one, the
+     *  path stops at an id or the depth cap, unchecked. */
+    isOnlyMatch?(selector: string): boolean;
+    /** What else identifies the node, beyond its path. */
+    context?(): Partial<IterationElement>;
 }
 /**
- * Best-effort descriptor of a picked element for locating it in code. Walks
- * up the tree collecting `#id` (preferred) or `tag:nth-child(n)` segments up
- * to a shallow depth, stopping at `BODY` or the depth cap. Kept framework-free
- * so it is unit-testable.
+ * Descriptor of a picked element for locating it in code. Walks up the tree
+ * collecting `#id` (preferred) or `tag:nth-child(n)` segments. The panel finds
+ * pins again with `querySelector`, which takes the first match, so with a real
+ * DOM the walk goes on past `maxDepth` until the path matches this element
+ * alone. Kept framework-free so it is unit-testable.
  */
 declare function describeIterationElement(el: NodeLike, maxDepth?: number): IterationElement;
 declare function elementAsNode(el: Element): NodeLike;
@@ -451,4 +486,4 @@ declare function createIterationStore(cfg?: IterationStoreConfig): {
     readonly hasUnsyncedNotes: boolean;
 };
 
-export { type ColorSwatch, type ColorVariantAxis, type IterationElement, type IterationNote, type IterationStoreConfig, KNOBS_STORAGE_KEY, type KnobAxis, type LiveVariantSelection, type NodeLike, type NoteContext, OVERLAY_DEFAULT_OPTION, OVERLAY_GROUP_ID, type OverlayGroup, type OverlayVariant, type OverlayVariantStatus, type OverlayVariantsList, type RangeVariantAxis, type RouteGateOptions, type SaveLocation, type SelectVariantAxis, VARIANTS_ENDPOINT, type VariantAction, type VariantAxis, type VariantAxisCondition, type VariantOption, type VariantReference, type VariantRemoval, type VariantSelections, type VariantsSource, applyKnobValues, axisDefault, createIterationStore, createOverlayVariantsSource, createVariantsSource, defaultSelections, describeIterationElement, elementAsNode, formatRangeValue, isAxisVisible, isDirty, isRouteVisible, isValidSelection, knobCssValue, knobDelta, knobVar, knobsFor, overlayAxes, overlayGroups, parseVariantParam, serializeVariantParam, variantAppliesTo, visibleAxes };
+export { type ColorSwatch, type ColorVariantAxis, type IterationElement, type IterationNote, type IterationStoreConfig, KNOBS_EVENT, KNOBS_STORAGE_KEY, type KnobAxis, type LiveVariantSelection, type NodeLike, type NoteContext, OVERLAY_DEFAULT_OPTION, OVERLAY_GROUP_ID, type OverlayGroup, type OverlayVariant, type OverlayVariantStatus, type OverlayVariantsList, type RangeVariantAxis, type RouteGateOptions, type SaveLocation, type SelectVariantAxis, VARIANTS_ENDPOINT, type VariantAction, type VariantAxis, type VariantAxisCondition, type VariantOption, type VariantReference, type VariantRemoval, type VariantSelections, type VariantsSource, applyKnobValues, axisDefault, createIterationStore, createOverlayVariantsSource, createVariantsSource, defaultSelections, describeIterationElement, elementAsNode, formatRangeValue, isAxisVisible, isDirty, isRouteVisible, isValidSelection, knobCssValue, knobDelta, knobVar, knobsFor, overlayAxes, overlayGroups, parseVariantParam, serializeVariantParam, variantAppliesTo, visibleAxes };

package/dist/core.js

@@ -3,8 +3,9 @@ import {
   describeIterationElement,
   elementAsNode,
   isRouteVisible
-} from "./chunk-FKEKBZ3E.js";
+} from "./chunk-K5RAC2BT.js";
 import {
+  KNOBS_EVENT,
   KNOBS_STORAGE_KEY,
   OVERLAY_DEFAULT_OPTION,
   OVERLAY_GROUP_ID,
@@ -28,9 +29,10 @@ import {
   serializeVariantParam,
   variantAppliesTo,
   visibleAxes
-} from "./chunk-PUXQGUMQ.js";
+} from "./chunk-RKZWO37H.js";
 import "./chunk-A4DX2V4C.js";
 export {
+  KNOBS_EVENT,
   KNOBS_STORAGE_KEY,
   OVERLAY_DEFAULT_OPTION,
   OVERLAY_GROUP_ID,

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   describeIterationElement,
   elementAsNode,
   isRouteVisible
-} from "./chunk-FKEKBZ3E.js";
+} from "./chunk-K5RAC2BT.js";
 import {
   FEEDBACK_STORAGE_KEY,
   KNOBS_STORAGE_KEY,
@@ -32,7 +32,7 @@ import {
   serializeVariantParam,
   visibleAxes,
   writeBrowserStorage
-} from "./chunk-PUXQGUMQ.js";
+} from "./chunk-RKZWO37H.js";
 import {
   MAX_FEEDBACK_LENGTH
 } from "./chunk-A4DX2V4C.js";
@@ -1887,6 +1887,16 @@ function IterationPanel({
   );
   const [hoverRect, setHoverRect] = useState3(null);
   const [rects, setRects] = useState3([]);
+  const pinnedElements = useRef4(/* @__PURE__ */ new Map());
+  const locate = useCallback((selector) => {
+    const pinned = pinnedElements.current.get(selector);
+    if (pinned?.isConnected) return pinned;
+    try {
+      return document.querySelector(selector);
+    } catch {
+      return null;
+    }
+  }, []);
   const [text, setText] = useState3("");
   const [notes, setNotes] = useState3([]);
   const [scope, setScope] = useState3(null);
@@ -2358,6 +2368,7 @@ function IterationPanel({
     };
     const toggleTarget = (el) => {
       const target = describeIterationElement(elementAsNode(el));
+      pinnedElements.current.set(target.selector, el);
       const added = !targetsRef.current.some((t) => t.selector === target.selector);
       setTargets(
         (prev) => prev.some((t) => t.selector === target.selector) ? prev.filter((t) => t.selector !== target.selector) : prev.length < 50 ? [...prev, target] : prev
@@ -2453,14 +2464,11 @@ function IterationPanel({
     const place = () => {
       frame = void 0;
       let { x, y } = anchor;
-      try {
-        const el = document.querySelector(anchor.selector);
-        if (el) {
-          const r = el.getBoundingClientRect();
-          x = r.left + anchor.dx;
-          y = r.top + anchor.dy;
-        }
-      } catch {
+      const el = locate(anchor.selector);
+      if (el) {
+        const r = el.getBoundingClientRect();
+        x = r.left + anchor.dx;
+        y = r.top + anchor.dy;
       }
       const vw = document.documentElement.clientWidth || innerWidth;
       const vh = innerHeight;
@@ -2516,7 +2524,7 @@ function IterationPanel({
       window.removeEventListener("scroll", schedule, true);
       window.removeEventListener("resize", schedule);
     };
-  }, [anchor]);
+  }, [anchor, locate]);
   useLayoutEffect4(() => {
     const last = floatNode.current;
     const root = rootRef.current;
@@ -2543,6 +2551,10 @@ function IterationPanel({
       ghost.remove();
     };
   }, [floating]);
+  useEffect3(() => {
+    const kept = new Set(targets.map((t) => t.selector));
+    for (const selector of pinnedElements.current.keys()) if (!kept.has(selector)) pinnedElements.current.delete(selector);
+  }, [targets]);
   useEffect3(() => {
     if (!picking && !floating) {
       setRects([]);
@@ -2553,22 +2565,18 @@ function IterationPanel({
       frame = void 0;
       setRects(
         targets.flatMap((t) => {
-          try {
-            const el = document.querySelector(t.selector);
-            if (!el) return [];
-            const r = el.getBoundingClientRect();
-            return [
-              {
-                top: r.top,
-                left: r.left,
-                width: r.width,
-                height: r.height,
-                selector: t.selector
-              }
-            ];
-          } catch {
-            return [];
-          }
+          const el = locate(t.selector);
+          if (!el) return [];
+          const r = el.getBoundingClientRect();
+          return [
+            {
+              top: r.top,
+              left: r.left,
+              width: r.width,
+              height: r.height,
+              selector: t.selector
+            }
+          ];
         })
       );
     };
@@ -2583,7 +2591,7 @@ function IterationPanel({
       window.removeEventListener("scroll", schedule, true);
       window.removeEventListener("resize", schedule);
     };
-  }, [targets, picking, floating]);
+  }, [targets, picking, floating, locate]);
   const variantsPanel = variants && /* @__PURE__ */ jsxs4(
     "section",
     {
@@ -3154,7 +3162,7 @@ function overlaySourceWithSave(getRoute, endpoint, key) {
   if (!endpoint) return source;
   const notes = createIterationStore({ endpoint, key });
   source.saveDefaults = async (selections) => {
-    const picked = source.getAxes().filter((axis) => axis.kind === void 0 || axis.kind === "select").flatMap((axis) => {
+    const picked = source.getAxes().filter((axis) => (axis.kind === void 0 || axis.kind === "select") && !source.knobs.axes.includes(axis)).flatMap((axis) => {
       const id = selections[axis.id];
       if (!id || id === OVERLAY_DEFAULT_OPTION) return [];
       const variant = source.list?.variants.find((v) => v.id === id);