panelui-web 0.6.0 → 0.8.0

package/dist/components/soundwave/index.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Soundwave — what a voice looks like while an app listens to it.
+ *
+ * ```tsx
+ * <Soundwave variant="dots" state="listening" level={level} />
+ *
+ * <Soundwave variant="radial" state="speaking">
+ *   <Soundwave.Center>
+ *     <Avatar name="Khalid Abdi" size="xl" />
+ *   </Soundwave.Center>
+ * </Soundwave>
+ * ```
+ *
+ * Seven looks. Four are the app's: `pills` over a microphone button, `bars`
+ * for a metering strip, `line` for a travelling wave, `ambient` for a glow
+ * behind a whole screen. Three are drawn in dots and spokes: `dots`, a field
+ * of dots lit into a wave; `radial`, spokes around a person; and `ring`,
+ * rings of dots lit outward by angle.
+ *
+ * ## It draws a level; it does not record one
+ *
+ * Nothing here touches the microphone. The app owns the recorder and hands
+ * over a number from 0 to 1, so the same wave works against a real meter, a
+ * synthesised one or a remote peer's. With no level it runs its own motion
+ * for the current `state`, so a voice screen can be built before any audio
+ * exists.
+ *
+ * ## Levels arrive faster than React should render
+ *
+ * A meter reports dozens of times a second. `level` takes a ref as well as a
+ * number: write each reading into `ref.current` and the wave picks it up on
+ * its next frame with nothing above it rendering. Each frame writes the `d`
+ * of one or two SVG paths, never React state, and the dots are zero-length
+ * round-capped segments, so a field of four hundred dots is a single path.
+ *
+ * Either way the level is smoothed with a fast attack and a slow release,
+ * which is what makes it read as a meter: it snaps up on a syllable and falls
+ * back gently instead of chattering on every sample.
+ */
+import { type ComponentProps, type ReactNode, type RefObject } from 'react';
+export type SoundwaveVariant = 'pills' | 'bars' | 'line' | 'ambient' | 'dots' | 'radial' | 'ring';
+export type SoundwaveState = 'idle' | 'listening' | 'thinking' | 'speaking';
+/** A role from the theme. The wave never carries a colour of its own. */
+export type SoundwaveColor = 'foreground' | 'primary' | 'info' | 'success' | 'warning' | 'destructive' | 'chart-1' | 'chart-2' | 'chart-3' | 'chart-4' | 'chart-5';
+export interface SoundwaveProps extends Omit<ComponentProps<'div'>, 'color' | 'children'> {
+    /**
+     * Which look to draw: `pills` for a few capsules over a microphone button,
+     * `bars` for a metering strip, `line` for a travelling wave, `ambient` for a
+     * glow that fills its parent, `dots` for a field of dots lit into a wave,
+     * `radial` for spokes around a centre, and `ring` for rings of dots lit
+     * outward by angle.
+     */
+    variant?: SoundwaveVariant;
+    /**
+     * What the app is doing. With no `level` it picks the motion the wave runs
+     * on its own, and it always sets what a screen reader announces.
+     */
+    state?: SoundwaveState;
+    /**
+     * How loud the input is now, from 0 to 1. Pass a ref and write each
+     * reading into `ref.current` to keep updates out of React entirely. Leave
+     * it out and the wave runs its own motion for `state`.
+     */
+    level?: number | RefObject<number | null>;
+    /**
+     * Sound to draw, in place of `level`: a `MediaStream` from a microphone or
+     * a call, or an `<audio>` or `<video>` element. A media file has to be on
+     * the same site or sent with CORS headers, or the browser hides its sound
+     * from the page and the wave stays still.
+     */
+    source?: SoundwaveSource | null;
+    /**
+     * Fixed values, 0 to 1 each: the stored shape of a recording, a frequency
+     * analysis, or one value per angle for `ring` (24 for the hours of a day).
+     * Resampled to the bar count, and drawn still rather than animated.
+     */
+    levels?: readonly number[];
+    /**
+     * How far a recording has played, from 0 to 1. Bars and dots behind it keep
+     * full ink and the rest are dimmed. `bars` and `dots`, with `levels`.
+     */
+    progress?: number;
+    /** How many capsules, bars or spokes, or how many angles for `ring`. `dots` fits as many columns as the width allows. */
+    bars?: number;
+    /** Capsule or bar width, the stroke of `line` and `radial`, or the size of a dot. */
+    barWidth?: number;
+    /** Space between capsules, or between dots. `bars` spaces itself across the width. */
+    barGap?: number;
+    /** Drawing height. For `radial` and `ring` it is the diameter. `ambient` fills its parent instead. */
+    height?: number;
+    /**
+     * `static` gives every bar a share of the current level; `scrolling` keeps a
+     * history that slides across, newest at the trailing edge. `bars` and `dots`.
+     */
+    mode?: 'static' | 'scrolling';
+    /** Grow bars and dots from the middle out rather than up from the bottom. */
+    centered?: boolean;
+    /** Fade a strip out at both ends, so it does not stop at a hard edge. */
+    fadeEdges?: boolean;
+    /** Multiplier on the incoming level, applied before it is capped at 1. */
+    sensitivity?: number;
+    /** Multiplier on the wave's own tempo, including how fast a history scrolls. */
+    speed?: number;
+    /**
+     * The ink, as a role from the theme. Left unset the wave is drawn in the
+     * text colour of whatever it sits in, which is right on most surfaces;
+     * `ambient` defaults to `info`, since a glow in the text colour reads as a
+     * shadow.
+     */
+    color?: SoundwaveColor;
+    /**
+     * Colours across the wave instead of one ink, as theme roles: left to right
+     * for the strips, up from the bottom for `ambient`.
+     */
+    gradient?: readonly SoundwaveColor[];
+    /**
+     * The colour of the unlit dots in `dots` and `ring`, and of the part of a
+     * recording not yet played in `bars`. Defaults to the ink, faint.
+     */
+    trackColor?: SoundwaveColor;
+    /** Hold the current frame. */
+    paused?: boolean;
+    /** What a screen reader calls it. Defaults to the state: "Listening". */
+    label?: string;
+    /** For `radial` and `ring`: a `Soundwave.Center` holding what sits in the middle. */
+    children?: ReactNode;
+}
+/** A voice as a wave. Draws a `level` it is handed, or runs its own motion for `state`. */
+declare function SoundwaveRoot({ variant, state, level: levelProp, source, levels, progress, bars, barWidth, barGap, height, mode, centered, fadeEdges, sensitivity, speed, color, gradient, trackColor, paused, label, className, style, children, ...props }: SoundwaveProps): import("react").JSX.Element;
+declare namespace SoundwaveRoot {
+    var displayName: string;
+}
+export interface SoundwaveCenterProps extends ComponentProps<'div'> {
+}
+/**
+ * What sits in the hole of a `radial` or `ring` wave: a person's avatar, a
+ * figure, a button. It is sized to the hole and centred in it.
+ */
+declare function SoundwaveCenter({ className, ...props }: SoundwaveCenterProps): import("react").JSX.Element;
+declare namespace SoundwaveCenter {
+    var displayName: string;
+}
+export declare const Soundwave: typeof SoundwaveRoot & {
+    Center: typeof SoundwaveCenter;
+};
+export { SoundwaveCenter };
+/** Something with sound in it: a microphone or call stream, or an `<audio>` or `<video>` element. */
+export type SoundwaveSource = MediaStream | HTMLMediaElement;
+export interface AudioLevelOptions {
+    /**
+     * The quietest sound that still moves the wave, in decibels below full
+     * scale. Default `-60`. Raise it towards `-45` in a noisy room.
+     */
+    floor?: number;
+    /** The loudness that fills the wave, in decibels below full scale. Default `-12`. */
+    ceiling?: number;
+}
+/**
+ * How loud `source` is, from 0 to 1, kept in a ref that is updated every
+ * frame. Pass the ref to `Soundwave` as `level`, or read `ref.current`
+ * yourself. With no source the ref holds 0.
+ */
+export declare function useAudioLevel(source: SoundwaveSource | null | undefined, { floor, ceiling }?: AudioLevelOptions): RefObject<number>;
+export type MicrophoneStatus = 'idle' | 'requesting' | 'listening' | 'denied' | 'unsupported';
+export interface UseMicrophoneOptions extends AudioLevelOptions {
+    /** Passed to `getUserMedia` as `audio`, to pick a device or change its processing. */
+    constraints?: MediaTrackConstraints;
+}
+export interface MicrophoneControls {
+    /** How loud the microphone is, from 0 to 1. Pass it to `Soundwave` as `level`. */
+    level: RefObject<number>;
+    /** The live stream while listening, for a recorder or a call. `null` otherwise. */
+    stream: MediaStream | null;
+    /** `requesting` while the browser asks for permission, `denied` if it was refused or there is no microphone. */
+    status: MicrophoneStatus;
+    /** Whether it is listening now. */
+    active: boolean;
+    /** Ask for the microphone and start listening. Call it from a click: browsers only allow sound to start from one. */
+    start: () => Promise<void>;
+    /** Stop listening and release the microphone, which turns the browser's recording light off. */
+    stop: () => void;
+    /** `start` when stopped, `stop` when listening. */
+    toggle: () => void;
+}
+/**
+ * The microphone, ready to draw. Nothing is asked for until `start`, and the
+ * microphone is released on `stop` and when the component unmounts.
+ *
+ * ```tsx
+ * const mic = useMicrophone();
+ * <Soundwave level={mic.active ? mic.level : undefined} />
+ * <Button onClick={mic.toggle}>{mic.active ? 'Stop' : 'Speak'}</Button>
+ * ```
+ */
+export declare function useMicrophone({ constraints, ...options }?: UseMicrophoneOptions): MicrophoneControls;