@rdna/ctrl

Control surface primitives for RDNA tool and editor surfaces.

@rdna/ctrl is a private workspace package that provides a small registry of dense UI controls, selectors, readouts, and panel layout primitives for RDNA tool and editor surfaces. Standalone RadOS is one external consumer of these primitives.

Package status: private workspace package. Source truth is package.json exports, ctrl.css, adjacent *.meta.ts files, generated schemas, and the runtime registry.

Public Surface

The package exports React components, control tokens, generated metadata, generated schemas, and a component registry.

| Subpath | Provides | | --- | --- | | @rdna/ctrl | Root barrel for the canonical controls plus supporting composition helpers, hooks, and types. | | @rdna/ctrl/css | Control surface token CSS. Import this when consuming ctrl outside a shared RDNA global stylesheet. | | @rdna/ctrl/controls | Canonical continuous controls: ValueSlider and NumberInput; older implementation files may remain private internals. | | @rdna/ctrl/selectors | Canonical selectors: Dropdown, Toggle, ColorSwatch, and IconCell; other selector shapes should become variants or app-local helpers. | | @rdna/ctrl/readouts | Canonical readouts: Meter and LEDProgress; specialized visualizations should wrap these at the app layer. | | @rdna/ctrl/layout | Canonical layout/action surface: ControlPanel and ActionButton, with supporting composition helpers for consumer apps. | | @rdna/ctrl/meta | Generated componentMetaIndex for the ctrl component contract. | | @rdna/ctrl/schemas | Generated componentData schema barrel. | | @rdna/ctrl/registry | Runtime registry, registry metadata builders, preview-state helpers, showcase prop helpers, and registry types. |

Usage

import '@rdna/ctrl/css';

import { ActionButton, ControlPanel, Meter, NumberInput, ValueSlider } from '@rdna/ctrl';

export function ToolPanel() {
  return (
    <ControlPanel>
      <NumberInput value={42} onValueChange={() => {}} min={0} max={100} />
      <ValueSlider value={75} onChange={() => {}} />
      <ActionButton label="Apply" onClick={() => {}} />
      <Meter value={0.72} />
    </ControlPanel>
  );
}

Consumer apps can import @rdna/ctrl/css directly or load it once from their global RDNA stylesheet.

Component Contract

Ctrl follows the same metadata and schema pattern as Radiants:

ComponentName/
├── ComponentName.tsx
├── ComponentName.meta.ts
└── ComponentName.schema.json

Current source state:

• 10 canonical ctrl components have adjacent *.meta.ts files.
• 10 canonical ctrl components have adjacent *.schema.json files.
• packages/ctrl/meta/index.ts and packages/ctrl/schemas/index.ts are generated barrels.
• packages/ctrl/registry/index.ts exports the prebuilt registry plus registry helpers and types.

Regenerate metadata and schemas after editing ctrl component metadata:

pnpm --filter @rdna/ctrl generate:schemas

Run the package test suite:

pnpm --filter @rdna/ctrl test

Styling Contract

ctrl.css imports @rdna/radiants/tokens and registers a small ctrl-specific semantic layer:

• sizing and density tokens such as --ctrl-cell-gap, --ctrl-row-height, --ctrl-size-sm, --ctrl-size-md, and --ctrl-size-lg
• color utilities such as bg-ctrl-cell-bg, text-ctrl-label, border-ctrl-border-active, and meter/readout token families
• .dark overrides for LCD, glow, meter, and active-control states

Keep hardcoded DAW/editor colors out of consuming apps. If a control surface needs a reusable value, add it to ctrl.css and use the generated token utility.

Package Boundary

@rdna/ctrl depends on @rdna/radiants for the base RDNA token system and shared visual language. Radiants must not import from ctrl; if a lower-level primitive is needed by both packages, move it down into Radiants or a future shared package before consuming it from Radiants.