v1.1.3: Radix-composable buttons, meter ballistics/dBFS/loudness, PanKnob

- PushButton/Button forward native button props (...rest) and compose their own event handlers with consumer/Radix-injected ones, so a Button works as a Radix `asChild` trigger (dropdowns/tooltips/popovers). Prop types now extend React.ButtonHTMLAttributes. - Meter gains opt-in metering: `ballistics` (PPM attack/decay), `peakDecay` (peak-hold fall tail), `scale="db"` (feed amplitude → dBFS with reference lines; min/max default -60/0), and `integrated` (windowed LUFS-ish loudness readout + marker). New rAF engine in meterEngine.ts with ampToDb/dbToAmp helpers; default behavior unchanged. - New `PanKnob` — bipolar stereo pan: fills from center, center detent, L<n>/C/R<n> readout, -50..50 default. - Docs: ApiDocs rows + recipes (dBFS meter, pan strip, Button-as-trigger), gallery cards (dBFS meter, Pan) + a Regenerate Button in the panel. CHANGELOG 1.1.3; version 1.1.3; install URLs bumped. Library + docs typecheck and build; 46 tests pass. - Meter dBFS readout: muted-grey unit labels (LUFS matched to dB), value-first layout in an aligned 2-column grid so peak/loudness decimals line up, and ghost pad digits removed — the loudness row no longer looks like a stray tag. - Action buttons (Button / PushButton mode="action") no longer show an LED by default — an action has no state to indicate. led defaults to 'strip' for toggle/momentary and false for action; led="dot"/"strip" opts back in. - Meter dBFS readout: units (dB / LUFS) sit centered directly under each value; grid alignment tidied and ghost pad digits removed. Docs: dBFS-meter card moved next to the Meters card (same component) + a horizontal example.
2026-07-14 11:16:44 -07:00 · 2026-07-14 11:16:44 -07:00 · d183d7d16b
commit d183d7d16b
parent 605c38af51
15 changed files with 644 additions and 80 deletions
--- a/apps/docs/src/sections/ApiDocs.tsx
+++ b/apps/docs/src/sections/ApiDocs.tsx
@ -128,14 +128,15 @@ export const ApiDocs: React.FC = () => (
        <Row name="<LEDKnob />" type="digital" desc="Segmented LED ring + seven-segment readout. color, offColor, segments, digits, displayDecimals (any precision), unit label under the digits." />
        <Row name="<NeonKnob />" type="2D" desc="Glowing arc + dot pointer. color, trackColor, arcFrom." />
        <Row name="<SteppedKnob />" type="selector" desc="Detented switch. positions (named) or steps (numeric), color, faceColor." />
+        <Row name="<PanKnob />" type="2D · bipolar" desc="Stereo pan: fills from center, snaps to a center detent, reads out L<n>/C/R<n>. Defaults to −50…50 centered at 0; pass min/max for other conventions." />
        <Row name="<Fader />" type="linear" desc="Channel fader. orientation, length, breadth, color, tickCount, showFill, unit, format, valuePosition ('top' | 'end' | 'none'), fill (stretch to container)." />
        <Row name="<LEDFader />" type="linear · digital" desc="Segmented LED meter-fader. orientation, length, segments, color or zones ([{upTo, color}] — defaults to the theme's green/amber/red), glow, digits, unit, fill (stretch to container)." />
        <Row name="<ImageKnob />" type="sprite" desc="Film-strip knob (KnobMan-style PNG strips): src, frames, stripOrientation. Photoreal skins with zero drawing code." />
-        <Row name="<Meter />" type="display" desc="Read-only LED level meter: value (number or [l, r, ...]), zones (theme green/amber/red), peakHold, peakColor, orientation, unit, fill (stretch to container), disabled, seven-segment readout. Clip LED: showClip, clipThreshold, clipHold (ms or 'latch'), clipColor, onClip." />
+        <Row name="<Meter />" type="display" desc="LED level meter: value (number or [l, r, ...]), zones, peakHold, peakDecay (fall tail), ballistics (PPM attack/decay), scale='db' (feed amplitude → dBFS + reference lines), integrated (windowed loudness), fill, disabled, seven-seg readout, clip LED (showClip/clipThreshold/clipHold 'latch'/clipColor/onClip). All the new metering is opt-in." />
        <Row name="<MeterBridge />" type="display" desc="Labeled multi-strip meter block: channels ([{label, value, clipValue?}]), per-channel peak-hold text, shared clip LED — the mixer meter row, prebuilt." />
        <Row name="<XYPad />" type="2D control" desc="Two-parameter pad: x/y axis configs (each with min/max/step/invert/detents), drag + arrow keys (arrows follow the visual direction), grid, crosshair, Escape cancel, double-click reset." />
-        <Row name="<Button />" type="action" desc="Click-to-fire command button in the panel style (Regenerate, Add, Apply). PushButton locked to mode='action' — never latches, press-down + LED flash, onClick. led: 'dot' (default) | 'strip' | false." />
-        <Row name="<PushButton />" type="switch" desc="Panel button: mode 'toggle' | 'momentary' | 'action', controlled/uncontrolled, aria-pressed. led: 'strip' | 'dot'. leadingIcon slot tinted to the LED." />
+        <Row name="<Button />" type="action" desc="Click-to-fire command button in the panel style (Regenerate, Add, Apply). PushButton locked to mode='action' — never latches, press-down, onClick. No LED by default (an action has no state); opt in with led='dot' | 'strip'. Forwards native button props → usable as a Radix asChild trigger." />
+        <Row name="<PushButton />" type="switch" desc="Panel button: mode 'toggle' | 'momentary' | 'action', controlled/uncontrolled, aria-pressed. led defaults to 'strip' for toggle/momentary (state) and off for action; also 'dot'. leadingIcon slot. Forwards ...rest and composes handlers, so it works as a dropdown/tooltip/popover trigger." />
        <Row name="<IndicatorLamp />" type="switch · display" desc="Panel LED lamp: pressable toggle (role='switch') or read-only status light, blink, momentary, label either side (labelSize to shrink the caption below its 10px floor) — the checkbox, in hardware form." />
        <Row name="<SegmentSwitch />" type="selector" desc="Segmented option switch (radiogroup): options list, LED tick on the active cell, arrow/Home/End keys, controlled/uncontrolled index." />
        <Row name="<ScrubField />" type="numeric field" desc="After-Effects-style number field: drag the label to scrub (Shift = fine), click to type (Enter commits, Esc reverts), arrows step, wheel nudges. role='spinbutton'." />
@ -311,12 +312,25 @@ function MyKnob() {
  <ToggleSwitch defaultOn showStateLabel />
 </LabeledField>

-// A declarative channel strip
+// A declarative channel strip — now with a pan knob
 <Rack orientation="column" title="Channel 1">
  <FlatKnob label="Gain" sublabel="dB" />
+  <PanKnob size={56} defaultValue={0} />
  <Fader orientation="horizontal" fill valuePosition="end" />
  <Meter value={level} min={-60} max={6} fill orientation="horizontal" />
-</Rack>`}
+</Rack>
+
+// A pro dBFS meter — feed amplitude, get ballistics + peak-decay + loudness
+<Meter value={[ampL, ampR]} scale="db" ballistics
+  peakHold={1500} peakDecay={0.25} integrated showValue unit="dB" />
+
+// A Button as a Radix dropdown trigger (it forwards + composes handlers)
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button led={false}>Add channel</Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent>{/* … */}</DropdownMenuContent>
+</DropdownMenu>`}
      />

      <h3 className="api-h">Precision &amp; number handling</h3>
--- a/apps/docs/src/sections/Buttons.tsx
+++ b/apps/docs/src/sections/Buttons.tsx
@ -82,7 +82,7 @@ export const Buttons: React.FC = () => {
            </Button>
            <Button
              color="#ff4d6b"
-              led={false}
+              led="strip"
              leadingIcon={<Glyph>✕</Glyph>}
              onClick={() => setFired(n => n + 1)}
              aria-label="Clear"
@ -131,9 +131,10 @@ export const Buttons: React.FC = () => {

        <p className="section-sub" style={{ marginTop: 20 }}>
          <code>&lt;Button&gt;</code> is <code>&lt;PushButton mode=&quot;action&quot;&gt;</code> —
-          it never latches, shows a press-down and a brief LED flash, and calls{' '}
-          <code>onClick</code>. <code>led=&quot;dot&quot;</code> gives the corner-dot
-          look; <code>led=&#123;false&#125;</code> a plain button.
+          it never latches, shows a press-down, and calls <code>onClick</code>. It has{' '}
+          <strong>no LED by default</strong> — an action has no state to indicate, unlike a
+          toggle. Add <code>led=&quot;dot&quot;</code> for a corner dot that flashes on
+          press, or <code>led=&quot;strip&quot;</code> for the full strip.
        </p>
      </div>
    </section>
--- a/apps/docs/src/sections/Gallery.tsx
+++ b/apps/docs/src/sections/Gallery.tsx
@ -2,6 +2,7 @@ import React from 'react';
 import {
  AlphaDisplay,
  Arc,
+  Button,
  DreamknobProvider,
  Fader,
  FlatKnob,
@ -18,6 +19,7 @@ import {
  Meter,
  MeterBridge,
  NeonKnob,
+  PanKnob,
  Pointer,
  PushButton,
  Rack,
@ -280,7 +282,10 @@ const PanelDemo: React.FC = () => {
      <LabeledField label="Fresh seed" labelWidth={78}>
        <ToggleSwitch on={fresh} onChange={setFresh} color="#c9a6ff" showStateLabel aria-label="Fresh seed" />
      </LabeledField>
-      <SegmentSwitch options={['SOLID', 'GRAD', 'NOISE']} value={mode} onChange={setMode} color="#c9a6ff" aria-label="Fill mode" />
+      <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+        <SegmentSwitch options={['SOLID', 'GRAD', 'NOISE']} value={mode} onChange={setMode} color="#c9a6ff" aria-label="Fill mode" />
+        <Button color="#c9a6ff" size={30} title="Regenerate the world" aria-label="Regenerate">↻</Button>
+      </div>
      <LampRow
        lamps={[
          { label: 'Cue', on: playing, color: '#3df2ad' },
@ -292,6 +297,61 @@ const PanelDemo: React.FC = () => {
  );
 };

+const DbMeterDemo: React.FC = () => {
+  // Drive with linear amplitude; the meter converts to dBFS internally.
+  const [amp, setAmp] = React.useState<[number, number]>([0.3, 0.28]);
+  React.useEffect(() => {
+    let t = 0;
+    const id = setInterval(() => {
+      t += 0.11;
+      const spike = Math.random() < 0.05 ? 0.4 : 0;
+      setAmp([
+        Math.max(0.001, Math.min(1.2, 0.34 + Math.sin(t) * 0.22 + Math.random() * 0.16 + spike)),
+        Math.max(0.001, Math.min(1.2, 0.32 + Math.sin(t * 1.25 + 1) * 0.22 + Math.random() * 0.16 + spike)),
+      ]);
+    }, 90);
+    return () => clearInterval(id);
+  }, []);
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 20, alignItems: 'center' }}>
+      <Meter
+        value={amp}
+        scale="db"
+        ballistics
+        peakHold={1400}
+        peakDecay={0.22}
+        integrated
+        clipThreshold={0}
+        length={140}
+        showValue
+        unit="dB"
+        label="Vertical"
+        aria-label="dBFS meter"
+      />
+      <Meter
+        value={amp}
+        scale="db"
+        ballistics
+        peakHold={1400}
+        peakDecay={0.22}
+        clipThreshold={0}
+        orientation="horizontal"
+        length={190}
+        breadth={14}
+        label="Horizontal"
+        aria-label="dBFS meter horizontal"
+      />
+    </div>
+  );
+};
+
+const PanDemo: React.FC = () => (
+  <div style={{ display: 'flex', gap: 22, alignItems: 'center' }}>
+    <PanKnob size={84} defaultValue={0} color="#4cc2ff" aria-label="Pan center" />
+    <PanKnob size={84} defaultValue={-30} color="#3df2ad" label="Track 2" aria-label="Pan left" />
+  </div>
+);
+
 const ImageKnobDemo: React.FC = () => {
  const src = useGeneratedStrip();
  if (!src) return null;
@ -509,6 +569,10 @@ export const Gallery: React.FC = () => (
          <MeterDemo />
        </Card>

+        <Card title="dBFS meter" desc="The same <Meter>, in dB mode: feed linear amplitude and it shows dBFS with PPM ballistics, a peak-decay tail, reference lines and a windowed loudness readout." tag="<Meter scale='db' ballistics integrated />">
+          <DbMeterDemo />
+        </Card>
+
        <Card title="Lamps & switches" desc="A segmented option switch, pressable indicator lamps (blink included) and a corner-dot button — the whole panel family." tag="<SegmentSwitch /> · <IndicatorLamp />">
          <LampSwitchDemo />
        </Card>
@ -536,6 +600,10 @@ export const Gallery: React.FC = () => (
          <PanelDemo />
        </Card>

+        <Card title="Pan" desc="Bipolar stereo pan: fills from center, snaps to a center detent, and reads out L/C/R." tag="<PanKnob />">
+          <PanDemo />
+        </Card>
+
        <Card title="Gradient arc" desc="Position-anchored gradient — the red zone stays at the top of travel." tag="<Arc gradient={...} />">
          <Knob size={96} min={-60} max={6} step={0.5} defaultValue={-8} aria-label="Gradient arc demo">
            <Arc
--- a/apps/docs/src/sections/GettingStarted.tsx
+++ b/apps/docs/src/sections/GettingStarted.tsx
@ -30,12 +30,12 @@ export const GettingStarted: React.FC = () => (

      <Step n={1} title="Install">
        <CodeBlock
-          code={`pnpm add https://git.dreamodus.software/Dreamodus/DreamKnob/releases/download/v1.1.2/dreamknob-1.1.2.tgz\n# (or npm install <same url>)  ·  peer deps: react >= 18, react-dom >= 18`}
+          code={`pnpm add https://git.dreamodus.software/Dreamodus/DreamKnob/releases/download/v1.1.3/dreamknob-1.1.3.tgz\n# (or npm install <same url>)  ·  peer deps: react >= 18, react-dom >= 18`}
        />
        <p className="api-note" style={{ marginTop: 10 }}>
          Installs straight from the{' '}
          <a href="https://git.dreamodus.software/Dreamodus/DreamKnob/releases">
-            v1.1.2 release
+            v1.1.3 release
          </a>{' '}
          on our Forgejo. Zero runtime dependencies, ESM + CJS, full TypeScript types. No
          CSS file to import — everything is SVG and inline styles.
--- a/apps/docs/src/sections/Hero.tsx
+++ b/apps/docs/src/sections/Hero.tsx
@ -25,10 +25,10 @@ export const Hero: React.FC = () => {
          range, any decimal precision, and colors you fully control.
        </p>
        <div className="install">
-          <span>pnpm add https://git.dreamodus.software/Dreamodus/DreamKnob/releases/download/v1.1.2/dreamknob-1.1.2.tgz</span>
+          <span>pnpm add https://git.dreamodus.software/Dreamodus/DreamKnob/releases/download/v1.1.3/dreamknob-1.1.3.tgz</span>
          <button
            onClick={() => {
-              navigator.clipboard.writeText('pnpm add https://git.dreamodus.software/Dreamodus/DreamKnob/releases/download/v1.1.2/dreamknob-1.1.2.tgz');
+              navigator.clipboard.writeText('pnpm add https://git.dreamodus.software/Dreamodus/DreamKnob/releases/download/v1.1.3/dreamknob-1.1.3.tgz');
              setCopied(true);
              setTimeout(() => setCopied(false), 1400);
            }}