@kitlangton/knobs 0.0.0-stage → 0.1.0

package/dist/react.js

@@ -0,0 +1,326 @@
+"use client";
+
+// src/react/useControls.ts
+import { useSyncExternalStore } from "react";
+"use client";
+function useControls(controls) {
+  return useSyncExternalStore(controls.subscribe, controls.get, controls.getServerSnapshot);
+}
+function useValue(controls, key) {
+  return useSyncExternalStore(controls.subscribe, () => controls.get()[key], () => controls.getServerSnapshot()[key]);
+}
+function useModified(controls, key) {
+  return useSyncExternalStore(controls.subscribe, () => controls.isModified(key), () => false);
+}
+// src/react/Knobs.tsx
+import {
+  cloneElement,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore as useSyncExternalStore2
+} from "react";
+
+// src/core/adapter.ts
+function syncPanelLook(host, controls, theme, density) {
+  const panel = host?.firstElementChild;
+  if (!panel)
+    return;
+  panel.dataset.theme = theme ?? controls.theme;
+  panel.dataset.density = density ?? controls.density;
+}
+function syncPanelValues(controls, descriptors, values, land = false) {
+  if (!controls.enabled || !descriptors && !values)
+    return;
+  if (descriptors && "update" in controls)
+    controls.update(descriptors, values, { land });
+  else if (values)
+    controls.sync(values, { replace: true, land });
+}
+function mountPanelAdapter(host, controls, getProps) {
+  const p = getProps();
+  return controls.mount(host, {
+    title: p.title,
+    theme: p.theme,
+    density: p.density,
+    renderer: p.renderer,
+    variants: p.variants,
+    history: p.history,
+    footer: p.footer,
+    header: p.header,
+    keys: p.keys,
+    marks: p.marks,
+    preset: p.preset,
+    copy: p.copy ? () => getProps().copy?.() ?? controls.code() : undefined,
+    actions: p.actions,
+    onClose: p.onClose ? () => getProps().onClose?.() : undefined,
+    onReady(panel) {
+      const cur = getProps();
+      syncPanelLook(host, controls, cur.theme, cur.density);
+      cur.onReady?.(panel);
+    }
+  });
+}
+
+// src/react/Knobs.tsx
+import { jsx } from "react/jsx-runtime";
+"use client";
+function useKnobs(controls) {
+  const [node, setNode] = useState(null);
+  useEffect(() => node ? controls.attach(node) : undefined, [controls, node]);
+  return useCallback((element) => {
+    setNode(element);
+  }, []);
+}
+function Knobs({
+  controls,
+  children
+}) {
+  const attach = useKnobs(controls);
+  const childRef = children.props.ref ?? Object.getOwnPropertyDescriptor(children, "ref")?.value;
+  const ref = useCallback((node) => {
+    attach(node);
+    if (typeof childRef === "function")
+      return childRef(node);
+    if (childRef)
+      childRef.current = node;
+  }, [attach, childRef]);
+  return cloneElement(children, { ref });
+}
+function KnobsPanel(props) {
+  const { controls, descriptors, values, land, theme, density } = props;
+  const enabled = useSyncExternalStore2(controls.subscribe, () => controls.enabled, () => false);
+  const ref = useRef(null);
+  const latest = useRef(props);
+  latest.current = props;
+  useEffect(() => {
+    if (!enabled || !ref.current)
+      return;
+    return mountPanelAdapter(ref.current, controls, () => latest.current);
+  }, [enabled, controls]);
+  useEffect(() => {
+    if (!enabled)
+      return;
+    syncPanelValues(controls, descriptors, values, Boolean(land));
+  }, [enabled, controls, descriptors, values, land]);
+  useEffect(() => {
+    syncPanelLook(ref.current, controls, theme, density);
+  }, [controls, theme, density]);
+  if (!enabled)
+    return null;
+  return /* @__PURE__ */ jsx("div", {
+    ref,
+    "data-knobs-mount": controls.id
+  });
+}
+// src/react/VariantSwitcher.tsx
+import { useEffect as useEffect2, useRef as useRef2, useSyncExternalStore as useSyncExternalStore3 } from "react";
+
+// src/core/schema.ts
+var READOUT_KINDS = new Set(["watch", "sparkline", "graph", "meter", "table", "log"]);
+function same(a, b) {
+  if (a === b)
+    return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+    return false;
+  if (Array.isArray(a) !== Array.isArray(b))
+    return false;
+  const ka = Object.keys(a);
+  return ka.length === Object.keys(b).length && ka.every((k) => same(a[k], b[k]));
+}
+function equal(a, b) {
+  return Object.keys(a).length === Object.keys(b).length && Object.keys(a).every((key) => same(a[key], b[key]));
+}
+
+// src/panel/switcher.ts
+var hoveredPreview = null;
+var lastAppliedByControls = new WeakMap;
+var interactive = "a[href],button,input,select,textarea,[contenteditable=true]";
+function getSwitcherOptions(controls, field) {
+  const values = controls.get();
+  const definition = field ? controls.schema[field] : undefined;
+  let variants = [];
+  if (!field && controls.enabled) {
+    try {
+      variants = controls.variants.list();
+    } catch {
+      variants = [];
+    }
+  }
+  const options = definition?.kind === "choice" ? definition.options.map((value) => ({
+    id: value,
+    name: value,
+    choose: () => controls.set({ [field]: value })
+  })) : [
+    ...Object.entries(controls.presets).map(([id, preset]) => ({
+      id: `p:${id}`,
+      name: id,
+      values: preset,
+      choose: () => {
+        lastAppliedByControls.set(controls, `p:${id}`);
+        controls.preset(id);
+      }
+    })),
+    ...variants.map((v) => ({
+      id: `v:${v.id}`,
+      name: v.name ?? v.id.slice(0, 8),
+      values: v.values,
+      choose: () => {
+        lastAppliedByControls.set(controls, `v:${v.id}`);
+        controls.variants.load(v.id);
+      }
+    }))
+  ];
+  let index = -1;
+  if (field) {
+    index = options.findIndex((o) => o.id === values[field]);
+  } else {
+    const pinnedId = lastAppliedByControls.get(controls);
+    if (pinnedId) {
+      const pinnedIdx = options.findIndex((o) => o.id === pinnedId && o.values !== undefined && equal(o.values, values));
+      if (pinnedIdx >= 0)
+        index = pinnedIdx;
+    }
+    if (index < 0) {
+      index = options.findIndex((o) => o.values !== undefined && equal(o.values, values));
+    }
+  }
+  return {
+    options,
+    index,
+    activeName: options[index]?.name ?? "custom"
+  };
+}
+function attachVariantSwitcher(element, controls, switcherOptions = {}) {
+  if (!controls.enabled)
+    return () => {};
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  const { field, label, onUpdate } = switcherOptions;
+  element.dataset.knobsSwitcher = controls.id;
+  if (!element.hasAttribute("role"))
+    element.setAttribute("role", "group");
+  const addedTabIndex = !element.hasAttribute("tabindex");
+  if (addedTabIndex)
+    element.tabIndex = 0;
+  const sync = () => {
+    const { activeName } = getSwitcherOptions(controls, field);
+    element.setAttribute("aria-label", label ?? `${controls.id} ${field ?? "variant"}: ${activeName}. Use 1–9 or left/right arrows.`);
+    onUpdate?.(activeName);
+  };
+  const cycle = (direction) => {
+    const { options, index } = getSwitcherOptions(controls, field);
+    if (!options.length)
+      return;
+    options[(index + direction + options.length) % options.length]?.choose();
+  };
+  const onPointerOver = (event) => {
+    if (event.target instanceof Element && event.target.closest("[data-knobs-switcher]") === element)
+      hoveredPreview = { element, target: event.target };
+  };
+  const onPointerLeave = (event) => {
+    if (hoveredPreview?.element !== element)
+      return;
+    const target = event.relatedTarget instanceof Element ? event.relatedTarget : null;
+    const parent = target?.closest("[data-knobs-switcher]");
+    hoveredPreview = parent && target ? { element: parent, target } : null;
+  };
+  const onElementKeyDown = (event) => {
+    if (event.target === element && (event.key === "Enter" || event.key === " ")) {
+      event.preventDefault();
+      cycle(1);
+    }
+  };
+  const onWindowKeyDown = (event) => {
+    if (event.defaultPrevented || event.isComposing || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey)
+      return;
+    const focused = doc.activeElement?.closest("[data-knobs-switcher]");
+    const active = hoveredPreview?.element ?? focused;
+    if (active !== element || event.target instanceof Element && event.target.closest(interactive) || hoveredPreview?.target.closest(interactive))
+      return;
+    if (win.getSelection()?.isCollapsed === false)
+      return;
+    const { options } = getSwitcherOptions(controls, field);
+    const selection = /^[1-9]$/.test(event.key) ? Number(event.key) - 1 : -1;
+    if (selection >= 0 && options[selection]) {
+      event.preventDefault();
+      options[selection].choose();
+    } else if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+      event.preventDefault();
+      cycle(event.key === "ArrowLeft" ? -1 : 1);
+    }
+  };
+  element.addEventListener("pointerover", onPointerOver);
+  element.addEventListener("pointerleave", onPointerLeave);
+  element.addEventListener("keydown", onElementKeyDown);
+  win.addEventListener("keydown", onWindowKeyDown);
+  const unsubscribe = controls.subscribe(sync);
+  sync();
+  return () => {
+    unsubscribe();
+    element.removeEventListener("pointerover", onPointerOver);
+    element.removeEventListener("pointerleave", onPointerLeave);
+    element.removeEventListener("keydown", onElementKeyDown);
+    win.removeEventListener("keydown", onWindowKeyDown);
+    if (hoveredPreview?.element === element)
+      hoveredPreview = null;
+    delete element.dataset.knobsSwitcher;
+    if (addedTabIndex && element.getAttribute("tabindex") === "0")
+      element.removeAttribute("tabindex");
+  };
+}
+
+// src/react/VariantSwitcher.tsx
+import { jsx as jsx2, Fragment } from "react/jsx-runtime";
+"use client";
+var empty = Object.freeze([]);
+function VariantSwitcher({
+  controls,
+  field,
+  children,
+  label
+}) {
+  const values = useControls(controls);
+  const enabled = useSyncExternalStore3(controls.subscribe, () => controls.enabled, () => false);
+  useSyncExternalStore3(controls.subscribe, () => {
+    if (field || !controls.enabled)
+      return empty;
+    try {
+      return controls.variants.list();
+    } catch {
+      return empty;
+    }
+  }, () => empty);
+  const ref = useRef2(null);
+  const { activeName } = getSwitcherOptions(controls, field);
+  useEffect2(() => {
+    if (!ref.current || !enabled)
+      return;
+    return attachVariantSwitcher(ref.current, controls, { field, label });
+  }, [controls, enabled, field, label]);
+  if (!enabled)
+    return /* @__PURE__ */ jsx2(Fragment, {
+      children: children ?? (field ? String(values[field]) : "default")
+    });
+  return /* @__PURE__ */ jsx2("div", {
+    ref,
+    "data-knobs-switcher": controls.id,
+    role: "group",
+    tabIndex: 0,
+    "aria-label": label ?? `${controls.id} ${field ?? "variant"}: ${activeName}. Use 1–9 or left/right arrows.`,
+    children: children ?? activeName
+  });
+}
+
+// src/react/index.ts
+"use client";
+export {
+  Knobs,
+  KnobsPanel,
+  VariantSwitcher,
+  useControls,
+  useKnobs,
+  useModified,
+  useValue
+};

package/dist/solid.js

@@ -0,0 +1,336 @@
+var __esm = (fn, res, err) => () => {
+  if (fn)
+    try {
+      res = fn(fn = 0);
+    } catch (e) {
+      err = [e];
+    }
+  if (err)
+    throw err[0];
+  return res;
+};
+
+// src/core/schema.ts
+function same(a, b) {
+  if (a === b)
+    return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+    return false;
+  if (Array.isArray(a) !== Array.isArray(b))
+    return false;
+  const ka = Object.keys(a);
+  return ka.length === Object.keys(b).length && ka.every((k) => same(a[k], b[k]));
+}
+function equal(a, b) {
+  return Object.keys(a).length === Object.keys(b).length && Object.keys(a).every((key) => same(a[key], b[key]));
+}
+var READOUT_KINDS;
+var init_schema = __esm(() => {
+  READOUT_KINDS = new Set(["watch", "sparkline", "graph", "meter", "table", "log"]);
+});
+
+// src/panel/switcher.ts
+function getSwitcherOptions(controls, field) {
+  const values = controls.get();
+  const definition = field ? controls.schema[field] : undefined;
+  let variants = [];
+  if (!field && controls.enabled) {
+    try {
+      variants = controls.variants.list();
+    } catch {
+      variants = [];
+    }
+  }
+  const options = definition?.kind === "choice" ? definition.options.map((value) => ({
+    id: value,
+    name: value,
+    choose: () => controls.set({ [field]: value })
+  })) : [
+    ...Object.entries(controls.presets).map(([id, preset]) => ({
+      id: `p:${id}`,
+      name: id,
+      values: preset,
+      choose: () => {
+        lastAppliedByControls.set(controls, `p:${id}`);
+        controls.preset(id);
+      }
+    })),
+    ...variants.map((v) => ({
+      id: `v:${v.id}`,
+      name: v.name ?? v.id.slice(0, 8),
+      values: v.values,
+      choose: () => {
+        lastAppliedByControls.set(controls, `v:${v.id}`);
+        controls.variants.load(v.id);
+      }
+    }))
+  ];
+  let index = -1;
+  if (field) {
+    index = options.findIndex((o) => o.id === values[field]);
+  } else {
+    const pinnedId = lastAppliedByControls.get(controls);
+    if (pinnedId) {
+      const pinnedIdx = options.findIndex((o) => o.id === pinnedId && o.values !== undefined && equal(o.values, values));
+      if (pinnedIdx >= 0)
+        index = pinnedIdx;
+    }
+    if (index < 0) {
+      index = options.findIndex((o) => o.values !== undefined && equal(o.values, values));
+    }
+  }
+  return {
+    options,
+    index,
+    activeName: options[index]?.name ?? "custom"
+  };
+}
+function attachVariantSwitcher(element, controls, switcherOptions = {}) {
+  if (!controls.enabled)
+    return () => {};
+  const doc = element.ownerDocument;
+  const win = doc.defaultView;
+  const { field, label, onUpdate } = switcherOptions;
+  element.dataset.knobsSwitcher = controls.id;
+  if (!element.hasAttribute("role"))
+    element.setAttribute("role", "group");
+  const addedTabIndex = !element.hasAttribute("tabindex");
+  if (addedTabIndex)
+    element.tabIndex = 0;
+  const sync = () => {
+    const { activeName } = getSwitcherOptions(controls, field);
+    element.setAttribute("aria-label", label ?? `${controls.id} ${field ?? "variant"}: ${activeName}. Use 1–9 or left/right arrows.`);
+    onUpdate?.(activeName);
+  };
+  const cycle = (direction) => {
+    const { options, index } = getSwitcherOptions(controls, field);
+    if (!options.length)
+      return;
+    options[(index + direction + options.length) % options.length]?.choose();
+  };
+  const onPointerOver = (event) => {
+    if (event.target instanceof Element && event.target.closest("[data-knobs-switcher]") === element)
+      hoveredPreview = { element, target: event.target };
+  };
+  const onPointerLeave = (event) => {
+    if (hoveredPreview?.element !== element)
+      return;
+    const target = event.relatedTarget instanceof Element ? event.relatedTarget : null;
+    const parent = target?.closest("[data-knobs-switcher]");
+    hoveredPreview = parent && target ? { element: parent, target } : null;
+  };
+  const onElementKeyDown = (event) => {
+    if (event.target === element && (event.key === "Enter" || event.key === " ")) {
+      event.preventDefault();
+      cycle(1);
+    }
+  };
+  const onWindowKeyDown = (event) => {
+    if (event.defaultPrevented || event.isComposing || event.metaKey || event.ctrlKey || event.altKey || event.shiftKey)
+      return;
+    const focused = doc.activeElement?.closest("[data-knobs-switcher]");
+    const active = hoveredPreview?.element ?? focused;
+    if (active !== element || event.target instanceof Element && event.target.closest(interactive) || hoveredPreview?.target.closest(interactive))
+      return;
+    if (win.getSelection()?.isCollapsed === false)
+      return;
+    const { options } = getSwitcherOptions(controls, field);
+    const selection = /^[1-9]$/.test(event.key) ? Number(event.key) - 1 : -1;
+    if (selection >= 0 && options[selection]) {
+      event.preventDefault();
+      options[selection].choose();
+    } else if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+      event.preventDefault();
+      cycle(event.key === "ArrowLeft" ? -1 : 1);
+    }
+  };
+  element.addEventListener("pointerover", onPointerOver);
+  element.addEventListener("pointerleave", onPointerLeave);
+  element.addEventListener("keydown", onElementKeyDown);
+  win.addEventListener("keydown", onWindowKeyDown);
+  const unsubscribe = controls.subscribe(sync);
+  sync();
+  return () => {
+    unsubscribe();
+    element.removeEventListener("pointerover", onPointerOver);
+    element.removeEventListener("pointerleave", onPointerLeave);
+    element.removeEventListener("keydown", onElementKeyDown);
+    win.removeEventListener("keydown", onWindowKeyDown);
+    if (hoveredPreview?.element === element)
+      hoveredPreview = null;
+    delete element.dataset.knobsSwitcher;
+    if (addedTabIndex && element.getAttribute("tabindex") === "0")
+      element.removeAttribute("tabindex");
+  };
+}
+var hoveredPreview = null, lastAppliedByControls, interactive = "a[href],button,input,select,textarea,[contenteditable=true]";
+var init_switcher = __esm(() => {
+  init_schema();
+  lastAppliedByControls = new WeakMap;
+});
+
+// src/solid/index.ts
+import {
+  children as resolveChildren,
+  createEffect,
+  createMemo,
+  createSignal,
+  onCleanup,
+  untrack
+} from "solid-js";
+
+// src/core/adapter.ts
+function syncPanelLook(host, controls, theme, density) {
+  const panel = host?.firstElementChild;
+  if (!panel)
+    return;
+  panel.dataset.theme = theme ?? controls.theme;
+  panel.dataset.density = density ?? controls.density;
+}
+function syncPanelValues(controls, descriptors, values, land = false) {
+  if (!controls.enabled || !descriptors && !values)
+    return;
+  if (descriptors && "update" in controls)
+    controls.update(descriptors, values, { land });
+  else if (values)
+    controls.sync(values, { replace: true, land });
+}
+function mountPanelAdapter(host, controls, getProps) {
+  const p = getProps();
+  return controls.mount(host, {
+    title: p.title,
+    theme: p.theme,
+    density: p.density,
+    renderer: p.renderer,
+    variants: p.variants,
+    history: p.history,
+    footer: p.footer,
+    header: p.header,
+    keys: p.keys,
+    marks: p.marks,
+    preset: p.preset,
+    copy: p.copy ? () => getProps().copy?.() ?? controls.code() : undefined,
+    actions: p.actions,
+    onClose: p.onClose ? () => getProps().onClose?.() : undefined,
+    onReady(panel) {
+      const cur = getProps();
+      syncPanelLook(host, controls, cur.theme, cur.density);
+      cur.onReady?.(panel);
+    }
+  });
+}
+
+// src/solid/index.ts
+init_schema();
+function useControls(controls) {
+  const [values, setValues] = createSignal(controls.get());
+  const unsubscribe = controls.subscribe(() => {
+    setValues(() => controls.get());
+  });
+  onCleanup(unsubscribe);
+  return values;
+}
+function useValue(controls, key) {
+  const [value, setValue] = createSignal(controls.get()[key], { equals: same });
+  onCleanup(controls.subscribe(() => setValue(() => controls.get()[key])));
+  return value;
+}
+function useModified(controls, key) {
+  const [modified, setModified] = createSignal(controls.isModified(key));
+  onCleanup(controls.subscribe(() => setModified(controls.isModified(key))));
+  return modified;
+}
+function useKnobs(controls) {
+  return (element) => {
+    createEffect(() => {
+      const detach = controls.attach(element);
+      onCleanup(detach);
+    });
+  };
+}
+function knobs(element, accessor) {
+  createEffect(() => {
+    const detach = accessor().attach(element);
+    onCleanup(detach);
+  });
+}
+function Knobs(props) {
+  const resolved = resolveChildren(() => props.children);
+  createEffect(() => {
+    const c = props.controls;
+    const node = resolved();
+    const target = Array.isArray(node) ? node[0] : node;
+    if (typeof HTMLElement !== "undefined" && target instanceof HTMLElement) {
+      const detach = c.attach(target);
+      onCleanup(detach);
+    }
+  });
+  return resolved;
+}
+function KnobsPanel(props) {
+  if (typeof document === "undefined")
+    return null;
+  const host = document.createElement("div");
+  createEffect(() => {
+    const c = props.controls;
+    host.dataset.knobsMount = c.id;
+    if (!c.enabled) {
+      host.replaceChildren();
+      return;
+    }
+    const dispose = untrack(() => mountPanelAdapter(host, c, () => props));
+    onCleanup(dispose);
+  });
+  createEffect(() => {
+    syncPanelValues(props.controls, props.descriptors, props.values, Boolean(props.land));
+  });
+  createEffect(() => {
+    syncPanelLook(host, props.controls, props.theme, props.density);
+  });
+  return host;
+}
+function VariantSwitcher(props) {
+  const values = useControls(props.controls);
+  const fallbackText = createMemo(() => {
+    const v = values();
+    return props.field ? String(v[props.field]) : props.controls.matchingPreset();
+  });
+  if (typeof document === "undefined" || !props.controls.enabled) {
+    return () => props.children ?? fallbackText();
+  }
+  const wrapper = document.createElement("div");
+  const resolved = resolveChildren(() => props.children ?? fallbackText());
+  createEffect(() => {
+    const nodes = resolved.toArray();
+    wrapper.replaceChildren(...nodes.map((n) => typeof Node !== "undefined" && n instanceof Node ? n : document.createTextNode(String(n ?? ""))));
+  });
+  createEffect(() => {
+    const c = props.controls;
+    const field = props.field;
+    const label = props.label;
+    if (!c.enabled)
+      return;
+    let disposed = false;
+    let detach;
+    Promise.resolve().then(() => (init_switcher(), {})).then((mod) => {
+      if (!disposed && c.enabled) {
+        detach = attachVariantSwitcher(wrapper, c, { field, label });
+      }
+    });
+    onCleanup(() => {
+      disposed = true;
+      detach?.();
+    });
+  });
+  return wrapper;
+}
+export {
+  Knobs,
+  KnobsPanel,
+  VariantSwitcher,
+  knobs,
+  useControls,
+  useKnobs,
+  useModified,
+  useValue
+};