@camstack/ui-library 0.1.57 → 0.1.58

package/dist/composites/device-controls/control-registry.d.ts

@@ -0,0 +1,74 @@
+import { ReactNode } from 'react';
+import { DeviceType } from '@camstack/types';
+import { UseDeviceProxyTrpc } from '../../hooks/use-device-proxy';
+import { ControlAlign } from './atoms';
+export { coverHighlight } from './cover-inline';
+export interface DeviceControlProps {
+    readonly trpc: UseDeviceProxyTrpc;
+    readonly deviceId: number;
+    readonly features: readonly string[] | undefined;
+    /** Enable optimistic UI mode (default: true). Set to false to disable. */
+    readonly optimistic?: boolean;
+}
+export interface DeviceTypeControl {
+    /** Compact, state-aware controls rendered directly in a device-list row. */
+    readonly InlineControl: (p: DeviceControlProps) => ReactNode;
+    /** Full control surface rendered as a card in the device-detail hero area. */
+    readonly HeroCard: (p: DeviceControlProps) => ReactNode;
+}
+/**
+ * Exhaustive record over DeviceType. Omitting a member causes a
+ * TypeScript build error (same pattern as DEVICE_TYPE_ACTIONS).
+ */
+export declare const DEVICE_TYPE_CONTROL: Record<DeviceType, DeviceTypeControl>;
+/**
+ * Per-type FILL flag.
+ *
+ *   true  — range / choice / button controls (cover ▲■▼ triad, thermostat
+ *           setpoint stepper, media/control/button action buttons, alarm
+ *           segmented control). The child STRETCHES to the full column width.
+ *   false — readouts, tap-toggles, icon controls (lock), and dummy/placeholder
+ *           types. The child keeps its NATURAL width; where it sits in the
+ *           column (flush right vs centered) is decided by the caller via a
+ *           `ControlPlacement` — see `resolveControlAlign`.
+ *
+ * Dummy types (Camera, Hub, Generic, Weather, Vacuum, Container, and placeholder
+ * types Notifier/Script/Automation whose InlineControl renders "—") are `false` —
+ * the dash placeholder must not be stretched to the full column width. (AlarmPanel
+ * has a real segmented inline control and is `true`.) When a later task gives a
+ * remaining placeholder type a real stretchy inline control, flip its flag to true.
+ *
+ * Exhaustive over DeviceType — a missing member is a TypeScript build error.
+ */
+export declare const CONTROL_FILLS: Record<DeviceType, boolean>;
+/**
+ * Where a control sits, and whether the column carries the fixed `w-[140px]` box.
+ *   'right'  — natural-width content flush to the fixed column's right edge (card / minimal views).
+ *   'center' — natural-width content centered in the fixed column.
+ *   'table'  — the column DROPS its fixed width and sizes to its content (table view). Every type
+ *              resolves to FIT so the control takes its natural width and lays out in sequence with
+ *              the trailing trash + status dot, never overflowing a fixed box and colliding.
+ * FILL controls ignore 'right'/'center' (they always stretch to the fixed width); under 'table'
+ * a FILL control simply takes its natural width in the content-sized wrapper.
+ */
+export type ControlPlacement = 'right' | 'center' | 'table';
+/**
+ * Runtime-string-safe lookup: a device row's `type` crosses the wire
+ * as a plain string, so an unrecognised value resolves to null instead
+ * of indexing the registry with an unverified key.
+ */
+export declare function resolveDeviceControl(type: string): DeviceTypeControl | null;
+/**
+ * Runtime-string-safe alignment lookup for the fixed-width control column.
+ *
+ * A device's `type` crosses the wire as a plain string;
+ * `DEVICE_TYPE_VALUES.has(type)` narrows it to `DeviceType` before indexing
+ * `CONTROL_FILLS`, making the cast sound. The `'table'` placement is
+ * content-width for EVERY type (returns `FIT`), so a wide control never
+ * overflows a fixed box — the FILL flag is irrelevant there. For the fixed-box
+ * placements a FILL type always stretches (`FILL`) and a natural-width type is
+ * placed by the caller's `placement` — `'center'` → `CENTER`, `'right'` →
+ * `RIGHT` (card / minimal view). An unrecognised type falls back to
+ * natural-width placement.
+ */
+export declare function resolveControlAlign(type: string, placement: ControlPlacement): ControlAlign;

package/dist/composites/device-controls/cover-hero-card.d.ts

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * CoverHeroCard — full control surface for the device-detail hero area.
+ *
+ * TWO VARIANTS based on whether the cover reports a position:
+ *
+ * With position (position !== null):
+ *  - Window graphic with slats descending from top to (100-position)%
+ *  - Visual (display-only) lever at the slat boundary with % label
+ *  - Open / Stop / Close buttons with state-aware highlight
+ *  - Interactive position range input (gated on CoverPositionable)
+ *  - Tilt range input (gated on CoverTilt)
+ *
+ * Without position (open/close-only, position === null):
+ *  - Window graphic showing state via clear pane (open) or full slats (closed)
+ *  - NO lever, NO % label; the value slot shows the cover STATE text (no %)
+ *  - Open / Stop / Close buttons with state-aware highlight
+ *
+ * Position support is detected via `CoverStatus.position !== null`.
+ * The interactive setPosition slider is gated on `DeviceFeature.CoverPositionable`.
+ *
+ * Follows the same `useDeviceCapability` pattern as CoverPanel / CoverInlineControl.
+ * Only hides when the device truly has no cover cap — a transient undefined slice
+ * renders a neutral "unknown" state with all buttons still mounted.
+ */
+export declare function CoverHeroCard({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/cover-inline.d.ts

@@ -0,0 +1,27 @@
+import { ReactNode } from 'react';
+import { CoverState } from '@camstack/types';
+import { DeviceControlProps } from './control-registry';
+/** Button highlight variant for cover state-aware colouring. */
+export type CoverHighlightVariant = 'accent' | 'filled' | 'neutral';
+export interface CoverButtonHighlight {
+    readonly up: CoverHighlightVariant;
+    readonly stop: CoverHighlightVariant;
+    readonly down: CoverHighlightVariant;
+}
+/**
+ * Pure helper — maps a live CoverState (or undefined when no slice yet)
+ * to per-button highlight variants.
+ *
+ *   opening → up:accent  (transient/active upward motion)
+ *   closing → down:accent (transient/active downward motion)
+ *   open    → up:filled   (stable fully-open state)
+ *   closed  → down:filled (stable fully-closed state)
+ *   stopped / undefined → neutral (no active state)
+ */
+export declare function coverHighlight(state: CoverState | undefined): CoverButtonHighlight;
+/**
+ * CoverInlineControl — compact, state-aware cover controls for a
+ * device-list row. Renders ↑ ■ ↓ buttons + optional % open badge.
+ * Reuses `useDeviceCapability` exactly as `CoverPanel` does.
+ */
+export declare function CoverInlineControl({ trpc, deviceId, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/cover-panel.d.ts

@@ -0,0 +1,3 @@
+import { ReactNode } from 'react';
+import { ControlPanelProps } from './types';
+export declare function CoverPanel({ trpc, deviceId, features, layout }: ControlPanelProps): ReactNode;

package/dist/composites/device-controls/dummy-hero-card.d.ts

@@ -0,0 +1,6 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/** Inline placeholder: renders nothing (no-op row atom for types with no inline control). */
+export declare function DummyInline(_p: DeviceControlProps): ReactNode;
+/** Hero card placeholder: shows a muted "Controls coming soon" card for unimplemented types. */
+export declare function DummyHeroCard(_p: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/fan-hero-card.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * FanHeroCard — radial speed-dial hero for Fan devices.
+ *
+ * Renders:
+ *  - RadialGauge: draggable speed ArcKnob riding a 270° ring at the speed
+ *    fraction (drag snaps to the device's percentageStep), centered fan glyph +
+ *    percentage readout. The gauge is the sole speed control — no slider.
+ *  - Preset selector (centered) — ONLY when the device advertises
+ *    DeviceFeature.FanPreset AND the slice exposes a non-empty
+ *    `availablePresets`.
+ *  - TAP TOGGLE for on/off (Spec §3 — NOT a SlideToggle; slide is safety-only).
+ *  - Oscillate toggle button — ONLY when the device advertises
+ *    DeviceFeature.FanOscillating AND the slice exposes a non-null
+ *    `oscillating` value.
+ *
+ * Composes two caps: `switch` (on/off) + `fan-control` (speed / oscillate).
+ * Cap-gated on `switch` (always present on a Fan) — returns null without it.
+ */
+export declare function FanHeroCard({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/fan-panel.d.ts

@@ -0,0 +1,3 @@
+import { ReactNode } from 'react';
+import { ControlPanelProps } from './types';
+export declare function FanPanel({ trpc, deviceId, features, layout, optimistic }: ControlPanelProps): ReactNode;

package/dist/composites/device-controls/humidifier-control.d.ts

@@ -0,0 +1,37 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/** The `action` HA attribute drives the droplet / mist tint. */
+export type HumidifierAction = 'humidifying' | 'drying' | 'idle' | 'off';
+export interface HumidifierTint {
+    /** Tailwind class for the wash behind the droplet. */
+    readonly glow: string;
+    /** Tailwind text token driving the droplet via currentColor. */
+    readonly accent: string;
+    /** Whether to render the upward mist dashes (actively humidifying). */
+    readonly misting: boolean;
+}
+/**
+ * Pure helper — maps the device's on-state + HA `action` to a tint.
+ * Exhaustive over the known action strings; an unknown / null action
+ * falls back to on/off heuristics.
+ *
+ *   humidifying → primary (blue)
+ *   drying      → warning
+ *   idle / off  → muted
+ */
+export declare function humidifierTint(on: boolean, action: string | null): HumidifierTint;
+/**
+ * HumidifierInlineControl — compact on/off toggle + current→target readout
+ * for a device-list row. Must NOT blow out the row width.
+ */
+export declare function HumidifierInlineControl({ trpc, deviceId, optimistic }: DeviceControlProps): ReactNode;
+/**
+ * HumidifierHeroCard — full control surface for the device-detail hero.
+ *
+ * Bespoke droplet + mist graphic + a large target-humidity readout +
+ * an on/off toggle + a target-humidity range slider (bounds from
+ * min/maxHumidity ?? 0..100) + a current-humidity readout + a mode
+ * `<select>` (only when modes are available). Gated on `available`.
+ * Only hides when the device truly has no humidifier cap.
+ */
+export declare function HumidifierHeroCard({ trpc, deviceId, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/image-control.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * ImageInlineControl — compact thumbnail for a device-list row that expands
+ * into a floating preview on hover/focus (shared `HoverZoomImage`). Shows a
+ * muted ImageOff placeholder box when no url is available. Row-narrow.
+ *
+ * `DeviceControlProps` carries no device name, so the alt/caption is the
+ * generic 'Image'; the framed hero (ImageHeroCard) carries the real name.
+ */
+export declare function ImageInlineControl({ trpc, deviceId }: DeviceControlProps): ReactNode;
+export interface ImageHeroCardProps extends DeviceControlProps {
+    /** Optional device name for the image alt text. */
+    readonly deviceName?: string;
+}
+/**
+ * ImageHeroCard — read-only framed image for the device-detail hero.
+ *
+ * A still image in the cover-style framed box (rounded border,
+ * object-contain) when a url is present; a centered ImageOff + "No image"
+ * placeholder when null. Keeps the framed-box chrome for visual
+ * consistency with the other heroes.
+ */
+export declare function ImageHeroCard({ trpc, deviceId, deviceName }: ImageHeroCardProps): ReactNode;

package/dist/composites/device-controls/index.d.ts

@@ -0,0 +1,33 @@
+export { ControlColumn, ValueReadout, FILL, RIGHT, CENTER, type ControlAlign, Stepper, SlideToggle, ArcKnob, GripTrack } from './atoms';
+export { RadialGauge, type RadialGaugeProps } from './radial-gauge';
+export { TapToggle, type TapToggleProps } from './tap-toggle';
+export { ButtonControl, ButtonHeroCard } from './button-control';
+export { CoverPanel } from './cover-panel';
+export { LockPanel } from './lock-panel';
+export { SwitchPanel } from './switch-panel';
+export { BrightnessPanel } from './brightness-panel';
+export { FanPanel } from './fan-panel';
+export { ClimatePanel, MODE_COLOR } from './climate-panel';
+export { MediaPlayerPanel, STATE_COLOR } from './media-player-panel';
+export { ControlPanel } from './control-panel';
+export { CONTROL_CAP_NAMES, type ControlCapName, type ControlPanelProps } from './types';
+export { PopoverRowAction } from './popover-row-action';
+export { SensorValueAtom, ROLE_DESCRIPTOR, type SensorDescriptor, type SensorValueAtomProps } from './sensor-value-atom';
+export { DEVICE_TYPE_CONTROL, CONTROL_FILLS, resolveDeviceControl, resolveControlAlign, coverHighlight, type DeviceTypeControl, type DeviceControlProps, type ControlPlacement, } from './control-registry';
+export { OfflineBadge, type OfflineBadgeProps } from './offline-badge';
+export { CoverInlineControl, type CoverHighlightVariant, type CoverButtonHighlight } from './cover-inline';
+export { CoverHeroCard } from './cover-hero-card';
+export { VacuumInlineControl, VacuumHeroCard, vacuumStateMeta, tankAlert, type VacuumStateMeta, type TankKind, type TankAlert, } from './vacuum-control';
+export { LawnMowerInlineControl, LawnMowerHeroCard, lawnMowerActivityMeta, type LawnMowerActivityMeta } from './lawn-mower-control';
+export { ValveInlineControl, ValveHeroCard, valveStateMeta, type ValveStateMeta } from './valve-control';
+export { HumidifierInlineControl, HumidifierHeroCard, humidifierTint, type HumidifierTint, type HumidifierAction, } from './humidifier-control';
+export { WaterHeaterInlineControl, WaterHeaterHeroCard, waterHeaterTint, waterHeaterPhase, type WaterHeaterTint, type WaterHeaterPhase, } from './water-heater-control';
+export { WeatherInlineControl, WeatherHeroCard, weatherTint, weatherConditionMeta, type WeatherTint, type WeatherConditionMeta, type WeatherGlyph, } from './weather-control';
+export { ImageInlineControl, ImageHeroCard, type ImageHeroCardProps, } from './image-control';
+export { DummyInline, DummyHeroCard } from './dummy-hero-card';
+export { SensorInlineControl } from './sensor-inline-control';
+export { SensorHeroCard } from './sensor-hero-card';
+export { SwitchInlineControl, SwitchHeroCard, LockInlineControl, LockHeroCard, LightInlineControl, LightHeroCard, FanInlineControl, FanHeroCard, ThermostatInlineControl, ThermostatHeroCard, MediaPlayerInlineControl, MediaPlayerHeroCard, AlarmPanelInlineControl, AlarmHeroCard, ControlInlineControl, ControlHeroCard, } from './panel-controls';
+export { resolvePrimaryChild, PRIORITY, type ChildRef } from './primary-child';
+export { resolveContainerPrimary, overrideEntityIdFromLink, containerChildToRef, childEntityId, type ContainerChild, } from './container-primary';
+export { ContainerPrimaryHero, type ContainerPrimaryHeroProps, type ContainerHeroChild, } from './container-primary-hero';

package/dist/composites/device-controls/lawn-mower-control.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode } from 'react';
+import { LawnMowerActivity } from '@camstack/types';
+import { DeviceControlProps } from './control-registry';
+export interface LawnMowerActivityMeta {
+    readonly label: string;
+    /** Tailwind text-colour token for the activity label. */
+    readonly tone: string;
+}
+/**
+ * Pure helper — maps a LawnMowerActivity (or undefined when no slice
+ * yet) to a human label + colour tone. Exhaustive switch: a new enum
+ * member fails the build.
+ */
+export declare function lawnMowerActivityMeta(activity: LawnMowerActivity | undefined): LawnMowerActivityMeta;
+/**
+ * LawnMowerInlineControl — compact, activity-aware mower controls for a
+ * device-list row. Mow / Pause / Dock + battery badge.
+ */
+export declare function LawnMowerInlineControl({ trpc, deviceId }: DeviceControlProps): ReactNode;
+/**
+ * LawnMowerHeroCard — full control surface for the device-detail hero
+ * area. Activity label + action buttons + battery readout.
+ */
+export declare function LawnMowerHeroCard({ trpc, deviceId }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/light-hero-card.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * LightHeroCard — radial dimmer hero for Light devices.
+ *
+ * Renders:
+ *  - RadialGauge: brightness ArcKnob riding a 270° ring at the level fraction,
+ *    centered bulb glyph + percentage readout.
+ *  - TAP TOGGLE for on/off (Spec §3 — NOT a SlideToggle; slide is safety-only).
+ *  - Colour-temperature GripTrack strip — ONLY when the device advertises
+ *    DeviceFeature.LightColorMired AND the `color` cap is bound.
+ *
+ * Composes three caps: `switch` (on/off), `brightness` (level), `color` (CT).
+ * Cap-gated on `switch` (always present on a Light) — returns null without it.
+ */
+export declare function LightHeroCard({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/lock-hero-card.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * LockHeroCard — padlock hero for lock devices.
+ *
+ * Renders:
+ *  - Padlock glyph: state-colored (locked=green, unlocked=amber, jammed=red)
+ *  - SlideToggle (safety gesture): thumb must be dragged past threshold to
+ *    confirm lock/unlock — a plain tap never triggers the action (Spec §3).
+ *  - Open (unlatch) button: rendered ONLY when device.features includes
+ *    DeviceFeature.LockOpen ('lock-open'). Absent otherwise.
+ *
+ * Cap-gated: returns null when the device has no lockControl cap.
+ */
+export declare function LockHeroCard({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/lock-panel.d.ts

@@ -0,0 +1,3 @@
+import { ReactNode } from 'react';
+import { ControlPanelProps } from './types';
+export declare function LockPanel({ trpc, deviceId, layout, optimistic, features }: ControlPanelProps): ReactNode;

package/dist/composites/device-controls/media-player-hero-card.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * MediaPlayerHeroCard — now-playing hero for MediaPlayer devices.
+ *
+ * Renders (Spec §3):
+ *  - Now-playing block: cover glyph + title + artist/album.
+ *  - Seek GripTrack with a native range overlay (gated on DeviceFeature
+ *    MediaPlayerSeek + a known duration).
+ *  - Transport row: SkipBack / Play-Pause / SkipForward (lucide icons). Skip
+ *    buttons are gated on MediaPlayerPrevious / MediaPlayerNext.
+ *  - Volume GripTrack with a native range overlay + mute toggle (gated on a
+ *    non-null volume surface + DeviceFeature.MediaPlayerVolume).
+ *
+ * Cap-gated on `media-player` — returns null when the device lacks the cap.
+ */
+export declare function MediaPlayerHeroCard({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/media-player-panel.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+import { ControlPanelProps } from './types.js';
+import { MediaPlayerState } from '@camstack/types';
+/**
+ * Exhaustive colour map — one entry per MediaPlayerState.
+ * Build fails if a state is added and not reflected here.
+ */
+export declare const STATE_COLOR: Record<MediaPlayerState, string>;
+export declare function MediaPlayerPanel({ trpc, deviceId, features: _features, layout, optimistic }: ControlPanelProps): ReactNode;

package/dist/composites/device-controls/offline-badge.d.ts

@@ -0,0 +1,11 @@
+import { ReactElement } from 'react';
+export interface OfflineBadgeProps {
+    /**
+     * Ms epoch of the last online→offline transition (device-status
+     * `lastChangedAt`). `null`/`undefined`/non-positive → no "last seen"
+     * suffix is shown.
+     */
+    readonly lastChangedAt?: number | null;
+    readonly className?: string;
+}
+export declare function OfflineBadge({ lastChangedAt, className }: OfflineBadgeProps): ReactElement;

package/dist/composites/device-controls/panel-controls.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+export { ThermostatHeroCard } from './thermostat-hero-card';
+export { LockHeroCard } from './lock-hero-card';
+export { LightHeroCard } from './light-hero-card';
+export { FanHeroCard } from './fan-hero-card';
+export { SwitchHeroCard } from './switch-hero-card';
+export { MediaPlayerHeroCard } from './media-player-hero-card';
+export { AlarmHeroCard, AlarmInlineControl as AlarmPanelInlineControl } from './alarm-hero-card';
+export declare function SwitchInlineControl({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;
+export declare function LockInlineControl({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;
+export declare function LightInlineControl({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;
+export declare function FanInlineControl({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;
+export declare function ThermostatInlineControl({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;
+export declare function MediaPlayerInlineControl({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;
+export declare function ControlInlineControl({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;
+export declare function ControlHeroCard({ trpc, deviceId, features, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/popover-row-action.d.ts

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+import { LucideIcon } from 'lucide-react';
+interface PopoverRowActionProps {
+    readonly icon: LucideIcon;
+    readonly title: string;
+    readonly children: ReactNode;
+}
+export declare function PopoverRowAction({ icon: Icon, title, children }: PopoverRowActionProps): ReactNode;
+export {};

package/dist/composites/device-controls/primary-child.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure resolver: given a container's entity-children and an optional picker
+ * override (stored as an entityId string, re-sync-stable), returns the child
+ * that should be rendered as the container's PRIMARY child.
+ *
+ * Design note: ChildRef.type is kept as `string` (not `DeviceType`) to decouple
+ * this pure resolver from the types enum. The resolver is tolerant of unknown
+ * type names — they sort after all known PRIORITY entries. This avoids creating
+ * a hard import dependency between the resolver and the enum, and handles future
+ * entity types gracefully.
+ */
+export declare const PRIORITY: readonly string[];
+export interface ChildRef {
+    readonly id: number;
+    readonly entityId: string;
+    readonly type: string;
+}
+export declare function resolvePrimaryChild(children: readonly ChildRef[], overrideEntityId: string | undefined): ChildRef | null;

package/dist/composites/device-controls/radial-gauge.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+export interface RadialGaugeProps {
+    /** Fill fraction 0..1 (brightness or speed level). */
+    readonly fraction: number;
+    /** Hex/CSS colour for the fill arc + knob border. */
+    readonly color: string;
+    /** Centered content (icon + value readout). */
+    readonly children: ReactNode;
+    /**
+     * When provided, the ArcKnob becomes draggable: dragging it reports the new
+     * arc fraction (0..1) to the parent, which owns the value and re-renders the
+     * gauge at the new `fraction`. When omitted the knob is display-only.
+     */
+    readonly onDragFraction?: (fraction: number) => void;
+}
+/**
+ * Circular gauge with an ArcKnob at `fraction` and centered children.
+ * The knob wrapper carries `data-testid="arc-knob"` for test assertions.
+ */
+export declare function RadialGauge({ fraction, color, children, onDragFraction }: RadialGaugeProps): ReactNode;

package/dist/composites/device-controls/sensor-hero-card.d.ts

@@ -0,0 +1,10 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * SensorHeroCard — full hero card for the device-detail area.
+ *
+ * Fetches the device row (name, role, sourceInfo) via React Query
+ * (`deviceManager.getDevice`), then delegates rendering to the inner
+ * component that reads the live state slice via the proxy.
+ */
+export declare function SensorHeroCard({ trpc, deviceId }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/sensor-inline-control.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * Registry InlineControl for Sensor and Presence device types.
+ *
+ * Fetches the device row once (React Query cache — no waterfall for
+ * repeated renders), maps to DeviceItemDevice, and delegates rendering
+ * to the existing SensorValueAtom so both the row special-case path and
+ * the registry path stay in sync.
+ */
+export declare function SensorInlineControl({ trpc, deviceId }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/sensor-value-atom.d.ts

@@ -0,0 +1,106 @@
+import { ReactNode } from 'react';
+import { DeviceProxy, SliceHandle } from '@camstack/types';
+import { UseDeviceProxyTrpc } from '../../hooks/use-device-proxy';
+import { ControlDateTimeFormat } from '../../lib/format-control-datetime';
+import { DeviceItemDevice } from '../device-item/helpers';
+interface NumericDescriptor {
+    readonly kind: 'numeric';
+    /** Field in the slice that holds the numeric value. */
+    readonly field: string;
+    /** Canonical display unit for TYPED roles (temperature → '°C', humidity → '%',
+     *  ambient-light → 'lx', pressure → 'hPa'). When present the UI renders this
+     *  directly WITHOUT consulting the slice or sourceInfo.
+     *  For the generic `numeric-sensor` role this is `undefined` — the unit is
+     *  read live from the slice (`slice.unit`). */
+    readonly canonicalUnit?: string;
+    /** Accessor into DeviceProxy['state'] — returns a typed slice handle. */
+    readonly getSliceHandle: (state: DeviceProxy['state']) => SliceHandle<unknown>;
+}
+interface BinaryDescriptor {
+    readonly kind: 'binary';
+    /** Field in the slice that holds the boolean trigger. */
+    readonly field: string;
+    /** Label shown when the boolean field is truthy. */
+    readonly onLabel: string;
+    /** Label shown when the boolean field is falsy. */
+    readonly offLabel: string;
+    readonly getSliceHandle: (state: DeviceProxy['state']) => SliceHandle<unknown>;
+}
+interface PresenceDescriptor {
+    readonly kind: 'presence';
+    readonly getSliceHandle: (state: DeviceProxy['state']) => SliceHandle<unknown>;
+}
+/**
+ * String-valued sensor whose slice holds `{ value: string, lastFetchedAt }`.
+ * Used for HA free-text sensors (IP address, SSID, firmware version, …) that
+ * have no numeric device_class and whose state is a plain string.
+ */
+interface StringDescriptor {
+    readonly kind: 'string';
+    readonly getSliceHandle: (state: DeviceProxy['state']) => SliceHandle<unknown>;
+}
+/**
+ * Date / timestamp sensor whose slice holds `{ value: string, format? }`
+ * carrying a raw ISO string (e.g. '2025-12-02T09:36:12+00:00'). Rendered
+ * locale-formatted via `formatControlDateTime`. The slice's own `format` (seeded
+ * by the HA provider from the entity's `device_class` — `timestamp` → 'datetime',
+ * `date` → 'date', time-only → 'time') selects the shape; `descriptor.format` is
+ * the fallback for slices adopted before the field was threaded ('datetime').
+ */
+interface DateTimeDescriptor {
+    readonly kind: 'datetime';
+    readonly format: ControlDateTimeFormat;
+    readonly getSliceHandle: (state: DeviceProxy['state']) => SliceHandle<unknown>;
+}
+export type SensorDescriptor = NumericDescriptor | BinaryDescriptor | PresenceDescriptor | StringDescriptor | DateTimeDescriptor;
+/**
+ * Binary fallback for the `battery-sensor` role.
+ *
+ * HA assigns role `battery-sensor` to BOTH numeric battery entities
+ * (`sensor.*` device_class=battery → cap `numeric-sensor`) AND binary battery
+ * entities (`binary_sensor.*` device_class=battery → cap `binary`, e.g. a
+ * HomeMatic `LOW_BAT` flag). When the numeric slice is absent the binary slice
+ * is rendered instead, with battery-specific polarity: `on:true` means LOW
+ * (bad → warning style + "Low"), `on:false` means Normal (neutral).
+ */
+export declare const BINARY_BATTERY_DESCRIPTOR: BinaryDescriptor;
+/** True for the role that can resolve to either a numeric or a binary slice. */
+export declare function isBatterySensorRole(role: string | null | undefined): boolean;
+/**
+ * A numeric slice counts as "present" only when it carries a real numeric value
+ * at the descriptor field — a cold-start slice (`{ value: 0, lastFetchedAt: 0 }`)
+ * or a binary slice (no numeric field) does NOT, so the binary fallback wins.
+ */
+export declare function hasBatteryNumericValue(slice: unknown, field: string): boolean;
+/**
+ * Keyed by DeviceRole string value. Every entry maps a role to the
+ * exact proxy state accessor + rendering instructions. The accessor
+ * avoids dynamic string indexing — each one is a concrete property
+ * access on the typed `DeviceProxy['state']` shape.
+ *
+ * Canonical unit rules:
+ *  - Typed roles (temperature/humidity/ambient-light/pressure/power/energy)
+ *    carry a `canonicalUnit` constant. The slice is normalised to one unit
+ *    so no per-device lookup is needed.
+ *  - Generic `numeric-sensor` has no `canonicalUnit`. The unit is read live
+ *    from the slice (`slice.unit`) as populated by the provider from the
+ *    upstream source on every state push.
+ */
+export declare const ROLE_DESCRIPTOR: Record<string, SensorDescriptor>;
+export interface StringSliceValue {
+    readonly value: string;
+}
+export declare function isStringSliceValue(v: unknown): v is StringSliceValue;
+/**
+ * The enum-sensor slice carries an optional `format` ('date' | 'time' |
+ * 'datetime') for `DateTimeSensor`-role sensors. Read it off the live slice so
+ * each sensor renders its true shape; returns `undefined` when absent (older
+ * adoptions) so the caller falls back to the descriptor default.
+ */
+export declare function readSliceDateTimeFormat(slice: unknown): ControlDateTimeFormat | undefined;
+export interface SensorValueAtomProps {
+    readonly trpc: UseDeviceProxyTrpc;
+    readonly device: DeviceItemDevice;
+}
+export declare function SensorValueAtom({ trpc, device }: SensorValueAtomProps): ReactNode;
+export {};

package/dist/composites/device-controls/switch-hero-card.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * SwitchHeroCard — large tap-toggle hero for Switch / Siren devices.
+ *
+ * Renders (Spec §3):
+ *  - A power glyph tinted by on/off state (success when on, muted when off).
+ *  - A large TAP TOGGLE for on/off — a single tap flips state. This is NOT a
+ *    SlideToggle; slide-to-confirm is reserved for safety-gated locks ONLY.
+ *
+ * Cap-gated on `switch` — returns null when the device has no switch cap.
+ */
+export declare function SwitchHeroCard({ trpc, deviceId, optimistic }: DeviceControlProps): ReactNode;

package/dist/composites/device-controls/switch-panel.d.ts

@@ -0,0 +1,3 @@
+import { ReactNode } from 'react';
+import { ControlPanelProps } from './types';
+export declare function SwitchPanel({ trpc, deviceId, optimistic }: ControlPanelProps): ReactNode;

package/dist/composites/device-controls/tap-toggle.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+/**
+ * TapToggle — plain tap-to-toggle on/off control.
+ *
+ * Spec §3: everyday on/off (switch, light, fan) uses a plain TAP TOGGLE.
+ * slide-to-confirm is reserved for safety-gated actions (lock) ONLY. This
+ * component must NEVER be built on `SlideToggle` — a single tap flips state.
+ *
+ * Presentational: the caller owns the cap mutation + optimistic update via
+ * `onToggle`. Mirrors the `SwitchPanel` button treatment at hero scale.
+ */
+export interface TapToggleProps {
+    readonly on: boolean;
+    readonly busy: boolean;
+    readonly onToggle: () => void;
+}
+export declare function TapToggle({ on, busy, onToggle }: TapToggleProps): ReactNode;

package/dist/composites/device-controls/thermostat-hero-card.d.ts

@@ -0,0 +1,17 @@
+import { ReactNode } from 'react';
+import { DeviceControlProps } from './control-registry';
+/**
+ * ThermostatHeroCard — circular gauge hero for thermostat / HVAC devices.
+ *
+ * Renders:
+ *  - SVG ring gauge: track + fill arc representing the setpoint fraction
+ *  - Centered current temperature (large, prominent)
+ *  - ArcKnob(s) at the setpoint fraction(s) riding the ring
+ *    - Single knob for heat / cool / auto / dry modes
+ *    - Two knobs (low + high) with a band fill for heat_cool mode
+ *  - Stepper (single) or "Low / High" display (range) for the setpoint
+ *  - Mode select
+ *
+ * Cap-gated: returns null when the device has no climateControl cap.
+ */
+export declare function ThermostatHeroCard({ trpc, deviceId, features: _features, optimistic }: DeviceControlProps): ReactNode;