@vsreact/core 0.0.3 → 0.0.5

package/src/controls.test.tsx

@@ -7,12 +7,13 @@ let paramGetResult: any = { value: 0.5, text: "0.0 dB", name: "Gain", label: "dB
 (globalThis as Record<string, any>).__vsreact_flush = (json: string) => {
   batches.push(JSON.parse(json));
 };
-(globalThis as Record<string, any>).__vsreact_nativeCall = (name: string, argsJson: string) => {
+const defaultNativeCall = (name: string, argsJson: string) => {
   const args = JSON.parse(argsJson);
   nativeCalls.push({ name, args });
   if (name === "param:get") return JSON.stringify(paramGetResult);
   return "null";
 };
+(globalThis as Record<string, any>).__vsreact_nativeCall = defaultNativeCall;
 
 import { render, unmount, Slider, Toggle, XYPad, Segmented, ParamSegmented, ParamToggle } from "./index";
 
@@ -33,6 +34,7 @@ beforeEach(() => {
   batches.length = 0;
   nativeCalls.length = 0;
   paramGetResult = { value: 0.5, text: "0.0 dB", name: "Gain", label: "dB" };
+  (globalThis as Record<string, any>).__vsreact_nativeCall = defaultNativeCall;
 });
 
 describe("vertical Slider", () => {
@@ -129,3 +131,174 @@ describe("Segmented", () => {
     expect(set?.args).toEqual({ id: "shape", value: 0 });
   });
 });
+
+describe("GenericEditor", () => {
+  test("renders one knob per parameter from param:list", () => {
+    (globalThis as Record<string, any>).__vsreact_nativeCall = (name: string, argsJson: string) => {
+      const args = JSON.parse(argsJson);
+      nativeCalls.push({ name, args });
+      if (name === "param:list")
+        return JSON.stringify([
+          { id: "gain", name: "Gain", label: "dB", value: 0.5, text: "0.0 dB" },
+          { id: "pan", name: "Pan", label: "", value: 0.5, text: "C" },
+          { id: "mix", name: "Mix", label: "%", value: 1, text: "100%" },
+        ]);
+      if (name === "param:get") return JSON.stringify(paramGetResult);
+      return "null";
+    };
+
+    const { GenericEditor } = require("./index");
+    render(<GenericEditor columns={2} size={64} />);
+
+    expect(nativeCalls.some((c) => c.name === "param:list")).toBe(true);
+    const arcs = opsNamed("setProps").filter((op: any) => op[2]?.style?.arcValueEnd !== undefined);
+    expect(arcs.length).toBe(3);
+    expect(nativeCalls.filter((c) => c.name === "param:get").length).toBe(3);
+  });
+
+  test("empty parameter list renders no knobs and doesn't crash", () => {
+    (globalThis as Record<string, any>).__vsreact_nativeCall = (name: string) => {
+      if (name === "param:list") return JSON.stringify([]);
+      return "null";
+    };
+
+    const { GenericEditor } = require("./index");
+    render(<GenericEditor />);
+    const arcs = opsNamed("setProps").filter((op: any) => op[2]?.style?.arcValueEnd !== undefined);
+    expect(arcs.length).toBe(0);
+  });
+});
+
+describe("Meter", () => {
+  test("fill splits at the hot zone and peak line renders", () => {
+    const { Meter } = require("./index");
+    render(<Meter value={0.95} length={100} hotFrom={0.85} peak />);
+
+    // main fill capped at the hot boundary
+    const fill = opsNamed("setProps").find((op: any) => op[2]?.style?.height === 85);
+    expect(fill).toBeDefined();
+    // hot overflow segment: ~(0.95 - 0.85) * 100 tall, anchored at 85
+    const hot: any = opsNamed("setProps").find((op: any) => op[2]?.style?.bottom === 85);
+    expect(hot).toBeDefined();
+    expect(hot[2].style.height).toBeCloseTo(10);
+  });
+
+  test("below the hot zone there is no hot segment", () => {
+    const { Meter } = require("./index");
+    render(<Meter value={0.5} length={100} hotFrom={0.85} peak={false} />);
+
+    const fill = opsNamed("setProps").find((op: any) => op[2]?.style?.height === 50);
+    expect(fill).toBeDefined();
+    const hot = opsNamed("setProps").find((op: any) => op[2]?.style?.bottom === 85);
+    expect(hot).toBeUndefined();
+  });
+});
+
+describe("onLayout + Select", () => {
+  /** Map child → parent from appendChild ops, to find a row by its text. */
+  const parentMap = () => {
+    const map = new Map<number, number>();
+    for (const op of allOps() as any[])
+      if (op[0] === "appendChild" || op[0] === "insertBefore") map.set(op[2], op[1]);
+    return map;
+  };
+
+  test("onLayout registers a layout listener and receives the rect", () => {
+    const seen: any[] = [];
+    render(<Slider value={0.5} onChange={() => {}} />); // warm-up unrelated tree
+    unmount();
+    batches.length = 0;
+
+    const { View: V } = require("./index");
+    render(<V onLayout={(r: any) => seen.push(r)} className="w-4" />);
+
+    const props: any = opsNamed("setProps").find((op: any) =>
+      op[2]?.listeners?.includes("layout"),
+    );
+    expect(props).toBeDefined();
+
+    dispatch({
+      kind: "event",
+      nodeId: props[1],
+      type: "layout",
+      payload: { x: 5, y: 10, width: 160, height: 32 },
+    });
+    expect(seen).toEqual([{ x: 5, y: 10, width: 160, height: 32 }]);
+  });
+
+  test("Select opens a positioned overlay menu and selects on click", async () => {
+    const { Select } = require("./index");
+    const seen: number[] = [];
+    render(
+      <Select options={["SINE", "SAW", "SQR"]} index={0} width={160} onChange={(i: number) => seen.push(i)} />,
+    );
+    await new Promise((r) => setTimeout(r, 0)); // let effects flush
+
+    // trigger has both layout + click listeners
+    const trigger: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.listeners?.includes("layout") && op[2]?.listeners?.includes("click"),
+    );
+    expect(trigger).toBeDefined();
+
+    // layout arrives, then the click opens the menu
+    dispatch({
+      kind: "event",
+      nodeId: trigger[1],
+      type: "layout",
+      payload: { x: 20, y: 40, width: 160, height: 33 },
+    });
+    await new Promise((r) => setTimeout(r, 0));
+    dispatch({ kind: "event", nodeId: trigger[1], type: "click" });
+    await new Promise((r) => setTimeout(r, 0));
+
+    // menu panel positioned under the trigger, same width
+    const panel: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.style?.top === 40 + 33 + 4 && op[2]?.style?.left === 20,
+    );
+    expect(panel).toBeDefined();
+    expect(panel[2].style.width).toBe(160);
+
+    // find the "SAW" row: rawtext -> Text -> row
+    const sawText: any = allOps().find((op: any) => op[0] === "setText" && op[2] === "SAW");
+    expect(sawText).toBeDefined();
+    const parents = parentMap();
+    const rowId = parents.get(parents.get(sawText[1])!)!;
+
+    dispatch({ kind: "event", nodeId: rowId, type: "click" });
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(seen).toEqual([1]);
+    // menu removed after selection
+    expect(allOps().some((op: any) => op[0] === "removeChild")).toBe(true);
+  });
+
+  test("ParamSelect writes a begin/set/end gesture with the index mapping", async () => {
+    paramGetResult = { value: 0, text: "Sine", name: "Shape", label: "" };
+    const { ParamSelect } = require("./index");
+    render(<ParamSelect paramId="shape" options={["SINE", "SAW", "SQR"]} />);
+    await new Promise((r) => setTimeout(r, 0));
+
+    const trigger: any = opsNamed("setProps").find(
+      (op: any) => op[2]?.listeners?.includes("layout") && op[2]?.listeners?.includes("click"),
+    );
+    dispatch({
+      kind: "event",
+      nodeId: trigger[1],
+      type: "layout",
+      payload: { x: 0, y: 0, width: 160, height: 33 },
+    });
+    await new Promise((r) => setTimeout(r, 0));
+    dispatch({ kind: "event", nodeId: trigger[1], type: "click" });
+    await new Promise((r) => setTimeout(r, 0));
+
+    const sqrText: any = allOps().find((op: any) => op[0] === "setText" && op[2] === "SQR");
+    const parents = parentMap();
+    const rowId = parents.get(parents.get(sqrText[1])!)!;
+    dispatch({ kind: "event", nodeId: rowId, type: "click" });
+
+    const set = nativeCalls.find((c) => c.name === "param:set");
+    expect(set?.args).toEqual({ id: "shape", value: 1 });
+    expect(nativeCalls.some((c) => c.name === "param:begin")).toBe(true);
+    expect(nativeCalls.some((c) => c.name === "param:end")).toBe(true);
+  });
+});

package/src/controls.tsx

@@ -2,10 +2,12 @@
 // switches — drawn by the VSReacT painter and driven by drag gestures.
 // Each has a Param* variant bound to an APVTS parameter.
 
-import { useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import { View, Text } from "./primitives";
-import { useParameter } from "./parameters";
+import { useParameter, useParameterList } from "./parameters";
 import { useSpring } from "./animation";
+import { useLayoutRect } from "./hooks";
+import { useOverlay } from "./overlay";
 
 const clamp01 = (v: number) => Math.min(1, Math.max(0, v));
 
@@ -525,3 +527,190 @@ export function ParamSegmented({ paramId, options, label, ...rest }: ParamSegmen
     />
   );
 }
+
+// ── GenericEditor ──────────────────────────────────────────────────────
+
+export interface GenericEditorProps {
+  /** Knobs per row. Default 4. */
+  columns?: number;
+  /** Knob diameter. Default 72. */
+  size?: number;
+  trackColor?: string;
+  valueColor?: string;
+}
+
+/** The zero-effort editor: one knob per APVTS parameter, laid out in
+    rows. `render(<GenericEditor />)` is a complete, working plugin UI. */
+export function GenericEditor({ columns = 4, size = 72, trackColor, valueColor }: GenericEditorProps) {
+  const params = useParameterList();
+
+  const rows: (typeof params)[] = [];
+  for (let i = 0; i < params.length; i += Math.max(1, columns))
+    rows.push(params.slice(i, i + Math.max(1, columns)));
+
+  return (
+    <View className="flex-1 flex-col items-center justify-center gap-6 p-4">
+      {rows.map((row, index) => (
+        <View key={index} className="flex-row gap-7">
+          {row.map((param) => (
+            <ParamKnob
+              key={param.id}
+              paramId={param.id}
+              size={size}
+              trackColor={trackColor}
+              valueColor={valueColor}
+            />
+          ))}
+        </View>
+      ))}
+    </View>
+  );
+}
+
+// ── Select ─────────────────────────────────────────────────────────────
+
+export interface SelectProps {
+  options: string[];
+  index: number;
+  /** Trigger width; the menu matches it. Default 160. */
+  width?: number;
+  label?: string;
+  disabled?: boolean;
+  trackColor?: string;
+  menuColor?: string;
+  activeColor?: string;
+  textColor?: string;
+  activeTextColor?: string;
+  /** Menu scrolls beyond this height. Default 190. */
+  maxMenuHeight?: number;
+  onChange: (index: number) => void;
+}
+
+const SELECT_ROW_HEIGHT = 30;
+
+/** A dropdown: the menu renders in the overlay layer, positioned under
+    the trigger via onLayout, with a click-away backdrop and a scrolling
+    option list. */
+export function Select({
+  options,
+  index,
+  width = 160,
+  label,
+  disabled,
+  trackColor = "#2A2F27",
+  menuColor = "#20241F",
+  activeColor = "#C6F135",
+  textColor = "#d4d4d8",
+  activeTextColor = "#09090b",
+  maxMenuHeight = 190,
+  onChange,
+}: SelectProps) {
+  const [open, setOpen] = useState(false);
+  const [rect, onLayout] = useLayoutRect();
+  const overlay = useOverlay();
+  const current = Math.min(options.length - 1, Math.max(0, index));
+
+  useEffect(() => {
+    if (!open || rect === null) {
+      overlay.hide();
+      return;
+    }
+
+    const menuHeight = Math.min(options.length * SELECT_ROW_HEIGHT + 8, maxMenuHeight);
+
+    overlay.show(
+      <View className="absolute inset-0" onClick={() => setOpen(false)}>
+        <View
+          className="absolute rounded-lg border shadow-lg overflow-hidden"
+          style={{
+            left: rect.x,
+            top: rect.y + rect.height + 4,
+            width: rect.width,
+            backgroundColor: menuColor,
+            borderColor: "#00000066",
+          }}
+        >
+          <View className="overflow-y-scroll p-[4] gap-[2]" style={{ height: menuHeight }}>
+            {options.map((option, i) => (
+              <View
+                key={`${option}-${i}`}
+                className="px-3 py-[6] rounded cursor-pointer hover:bg-white/10"
+                style={{ backgroundColor: i === current ? activeColor : "#00000000" }}
+                onClick={() => {
+                  onChange(i);
+                  setOpen(false);
+                }}
+              >
+                <Text
+                  className="text-[12] font-medium"
+                  style={{ color: i === current ? activeTextColor : textColor }}
+                >
+                  {option}
+                </Text>
+              </View>
+            ))}
+          </View>
+        </View>
+      </View>,
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, rect, options, current, menuColor, activeColor, textColor, activeTextColor, maxMenuHeight]);
+
+  return (
+    <View className="items-center gap-2">
+      <View
+        className={`flex-row items-center justify-between rounded-lg border px-3 py-[8] ${
+          disabled ? "opacity-40" : "cursor-pointer"
+        }`}
+        style={{ width, backgroundColor: trackColor, borderColor: "#00000055" }}
+        onLayout={onLayout}
+        onClick={disabled ? undefined : () => setOpen((v) => !v)}
+      >
+        <Text className="text-[12] font-medium" style={{ color: textColor }}>
+          {options[current] ?? ""}
+        </Text>
+        <Text className="text-[9]" style={{ color: textColor, opacity: 0.7 }}>
+          {open ? "▲" : "▼"}
+        </Text>
+      </View>
+      {label !== undefined ? (
+        <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+      ) : null}
+    </View>
+  );
+}
+
+export interface ParamSelectProps {
+  paramId: string;
+  options: string[];
+  width?: number;
+  label?: string;
+  trackColor?: string;
+  menuColor?: string;
+  activeColor?: string;
+  textColor?: string;
+  activeTextColor?: string;
+  maxMenuHeight?: number;
+}
+
+/** A Select bound to a choice-style APVTS parameter (same value↔index
+    mapping as ParamSegmented). */
+export function ParamSelect({ paramId, options, label, ...rest }: ParamSelectProps) {
+  const param = useParameter(paramId);
+  const count = Math.max(1, options.length);
+  const index = Math.round(param.value * (count - 1));
+
+  return (
+    <Select
+      options={options}
+      index={index}
+      label={label ?? param.name.toUpperCase()}
+      onChange={(i) => {
+        param.begin();
+        param.set(count <= 1 ? 0 : i / (count - 1));
+        param.end();
+      }}
+      {...rest}
+    />
+  );
+}

package/src/hooks.ts

@@ -1,7 +1,19 @@
 // Convenience hooks over the native bridge.
 
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState } from "react";
 import { native } from "./native";
+import type { LayoutRect } from "./primitives";
+
+/**
+ * Captures a node's root-space rect from its onLayout prop:
+ *
+ *   const [rect, onLayout] = useLayoutRect();
+ *   <View onLayout={onLayout} />   // rect updates whenever layout moves it
+ */
+export function useLayoutRect(): [LayoutRect | null, (rect: LayoutRect) => void] {
+  const [rect, setRect] = useState<LayoutRect | null>(null);
+  return [rect, setRect];
+}
 
 /**
  * Subscribes to a C++ event (RootView::sendNativeEvent) for the lifetime
@@ -16,3 +28,21 @@ export function useNativeEvent(name: string, handler: (payload: any) => void): v
 
   useEffect(() => native.on(name, (payload) => handlerRef.current(payload)), [name]);
 }
+
+/**
+ * The value, but only after it has stopped changing for `delayMs` —
+ * classic input debouncing for expensive native calls:
+ *
+ *   const query = useDebounced(text, 250);
+ *   useEffect(() => { native.call("library:search", { query }); }, [query]);
+ */
+export function useDebounced<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(id);
+  }, [value, delayMs]);
+
+  return debounced;
+}

package/src/hostConfig.ts

@@ -31,6 +31,7 @@ const eventPropNames: Record<string, string> = {
   onDragStart: "dragstart",
   onDrag: "drag",
   onDragEnd: "dragend",
+  onLayout: "layout",
   onChange: "change",
   onSubmit: "submit",
   onFocus: "focus",

package/src/index.ts

@@ -13,26 +13,30 @@ export type {
 } from "./primitives";
 export { render, unmount } from "./render";
 export { native } from "./native";
-export { useNativeEvent } from "./hooks";
+export { useNativeEvent, useDebounced, useLayoutRect } from "./hooks";
+export { useOverlay, OverlayLayer } from "./overlay";
 export { configureTheme, tw } from "./tw";
 export type { Style, ResolvedClasses } from "./tw";
 export { cx } from "./cx";
 export type { ClassValue } from "./cx";
 export { useTween, useSpring, springStep, lerp, Easing } from "./animation";
 export type { TweenOptions, SpringOptions, EasingFn } from "./animation";
-export { useParameter } from "./parameters";
-export type { ParameterState, ParameterHandle } from "./parameters";
+export { useParameter, useParameterList } from "./parameters";
+export type { ParameterState, ParameterHandle, ParameterInfo } from "./parameters";
 export {
   Knob,
   Slider,
   Toggle,
   XYPad,
   Segmented,
+  Select,
+  GenericEditor,
   ParamKnob,
   ParamSlider,
   ParamToggle,
   ParamXYPad,
   ParamSegmented,
+  ParamSelect,
   dragToValue,
 } from "./controls";
 export type {
@@ -41,10 +45,15 @@ export type {
   ToggleProps,
   XYPadProps,
   SegmentedProps,
+  SelectProps,
+  GenericEditorProps,
   ParamKnobProps,
   ParamSliderProps,
   ParamToggleProps,
   ParamXYPadProps,
   ParamSegmentedProps,
+  ParamSelectProps,
 } from "./controls";
-export type { DragEventPayload } from "./primitives";
+export { Meter, usePeakHold, peakHoldStep } from "./meter";
+export type { MeterProps, PeakHoldOptions, PeakHoldState } from "./meter";
+export type { DragEventPayload, LayoutRect } from "./primitives";

package/src/meter.tsx

@@ -0,0 +1,159 @@
+// Meter — the level meter every plugin needs: painted bar with a hot zone
+// and a peak-hold line that holds, then falls. Feed it any 0..1 value
+// (typically pushed from C++ via useNativeEvent).
+
+import { useEffect, useRef, useState } from "react";
+import { View, Text } from "./primitives";
+
+const clamp01 = (v: number) => Math.min(1, Math.max(0, v));
+
+export interface PeakHoldOptions {
+  /** How long a peak is held before it starts falling. Default 600ms. */
+  holdMs?: number;
+  /** Fall rate once the hold expires, in value/second. Default 1.5. */
+  decayPerSecond?: number;
+}
+
+export interface PeakHoldState {
+  peak: number;
+  heldForMs: number;
+}
+
+/** One peak-hold step (pure, testable): new peaks latch instantly and
+    reset the hold timer; after holdMs the peak decays toward the value. */
+export function peakHoldStep(
+  state: PeakHoldState,
+  value: number,
+  dtMs: number,
+  { holdMs = 600, decayPerSecond = 1.5 }: PeakHoldOptions = {},
+): PeakHoldState {
+  if (value >= state.peak) return { peak: value, heldForMs: 0 };
+
+  const heldForMs = state.heldForMs + dtMs;
+  if (heldForMs < holdMs) return { peak: state.peak, heldForMs };
+
+  return { peak: Math.max(value, state.peak - decayPerSecond * (dtMs / 1000)), heldForMs };
+}
+
+const FRAME_MS = 33; // meters read fine at ~30fps
+
+/** The held peak for a live value — drives the Meter's peak line. */
+export function usePeakHold(value: number, options: PeakHoldOptions = {}): number {
+  const [peak, setPeak] = useState(value);
+  const state = useRef<PeakHoldState>({ peak: value, heldForMs: 0 });
+  const valueRef = useRef(value);
+  valueRef.current = value;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  useEffect(() => {
+    const id = setInterval(() => {
+      state.current = peakHoldStep(state.current, valueRef.current, FRAME_MS, optionsRef.current);
+      setPeak(state.current.peak);
+    }, FRAME_MS);
+
+    return () => clearInterval(id);
+  }, []);
+
+  return Math.max(peak, value);
+}
+
+export interface MeterProps {
+  /** Level 0..1. */
+  value: number;
+  /** Long-axis length. Default 120. */
+  length?: number;
+  /** Short-axis thickness. Default 10. */
+  thickness?: number;
+  /** Horizontal bar instead of the vertical default. */
+  horizontal?: boolean;
+  /** Show the peak-hold line. Default true. */
+  peak?: boolean;
+  holdMs?: number;
+  decayPerSecond?: number;
+  /** Where the fill turns hot, 0..1. Default 0.85. */
+  hotFrom?: number;
+  trackColor?: string;
+  color?: string;
+  hotColor?: string;
+  label?: string;
+}
+
+/** A natively painted level meter with hot zone + peak hold. */
+export function Meter({
+  value,
+  length = 120,
+  thickness = 10,
+  horizontal,
+  peak = true,
+  holdMs,
+  decayPerSecond,
+  hotFrom = 0.85,
+  trackColor = "#141714",
+  color = "#C6F135",
+  hotColor = "#FF4545",
+  label,
+}: MeterProps) {
+  const level = clamp01(value);
+  const held = usePeakHold(level, { holdMs, decayPerSecond });
+  const hot = clamp01(hotFrom);
+
+  const fill = Math.min(level, hot) * length;
+  const hotFill = level > hot ? (level - hot) * length : 0;
+  const peakAt = clamp01(held) * length;
+
+  const bar = horizontal ? (
+    <View
+      className="relative rounded overflow-hidden"
+      style={{ width: length, height: thickness, backgroundColor: trackColor }}
+    >
+      <View
+        className="absolute left-0 top-0 bottom-0"
+        style={{ width: fill, backgroundColor: color }}
+      />
+      {hotFill > 0 ? (
+        <View
+          className="absolute top-0 bottom-0"
+          style={{ left: hot * length, width: hotFill, backgroundColor: hotColor }}
+        />
+      ) : null}
+      {peak && peakAt > 2 ? (
+        <View
+          className="absolute top-0 bottom-0 w-[2]"
+          style={{ left: peakAt - 2, backgroundColor: held >= hot ? hotColor : color }}
+        />
+      ) : null}
+    </View>
+  ) : (
+    <View
+      className="relative rounded overflow-hidden"
+      style={{ width: thickness, height: length, backgroundColor: trackColor }}
+    >
+      <View
+        className="absolute bottom-0 left-0 right-0"
+        style={{ height: fill, backgroundColor: color }}
+      />
+      {hotFill > 0 ? (
+        <View
+          className="absolute left-0 right-0"
+          style={{ bottom: hot * length, height: hotFill, backgroundColor: hotColor }}
+        />
+      ) : null}
+      {peak && peakAt > 2 ? (
+        <View
+          className="absolute left-0 right-0 h-[2]"
+          style={{ bottom: peakAt - 2, backgroundColor: held >= hot ? hotColor : color }}
+        />
+      ) : null}
+    </View>
+  );
+
+  if (label === undefined) return bar;
+
+  return (
+    <View className="items-center gap-2">
+      {bar}
+      <Text className="text-faint text-[10] font-bold tracking-widest">{label}</Text>
+    </View>
+  );
+}