@fusion.dev/helix 0.217.0 → 0.218.0

package/dist/index.d.ts

@@ -126,3 +126,4 @@ export * from './trend/index.js';
 export * from './video/index.js';
 export * from './video-playlist/index.js';
 export * from './virtual-list/index.js';
+export * from './voice-level/index.js';

package/dist/index.js

@@ -121,3 +121,4 @@ export * from './trend/index.js';
 export * from './video/index.js';
 export * from './video-playlist/index.js';
 export * from './virtual-list/index.js';
+export * from './voice-level/index.js';

package/dist/voice-level/draw.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The arithmetic behind a voice level's two drawings, with no canvas in it.
+ *
+ * Every function takes plain numbers and returns plain numbers, so the shapes
+ * are held by a pure spec and the element is left with measuring a box and
+ * filling paths.
+ */
+/** What a voice level draws. */
+export type VoiceLevelVariant = 'spectrum' | 'waves';
+/** The bar count the spectrum draws where `--voice-level-bars` says nothing. */
+export declare const DEFAULT_BARS = 24;
+/** The fewest and the most bars a spectrum draws, whatever the hook asks for. */
+export declare const MIN_BARS = 3;
+export declare const MAX_BARS = 96;
+/**
+ * How fast a bar or a wave follows a louder reading and a quieter one, as a
+ * rate per second.
+ *
+ * **Up fast and down slower**, as a meter's needle moves: a syllable shows the
+ * frame it starts, and the fall that follows is slow enough to read.
+ */
+export declare const RISE = 22;
+export declare const FALL = 6;
+/**
+ * How long the drawing has to rest at zero before its loop stops, in seconds,
+ * counted from the end of the fall, so the last frame drawn is the resting
+ * shape.
+ */
+export declare const QUIET_STOP = 0.5;
+/** Below this a reading is silence. */
+export declare const SILENT = 0.002;
+/** A reading clamped to the range a level is written in. */
+export declare const unit: (value: number) => number;
+/**
+ * The bar count, from what the hook computed to.
+ *
+ * Anything that is not a whole number in the range keeps the default or is
+ * brought into it.
+ */
+export declare const barCount: (written: string) => number;
+/**
+ * How tall bar `index` of `count` may stand, from about a quarter at either end
+ * to the whole box in the middle.
+ *
+ * **Center weighted**, so the row reads as one shape that swells with the
+ * voice. Without it, the loud low bands sit at one end and the drawing leans.
+ */
+export declare const envelope: (index: number, count: number) => number;
+/**
+ * Whether bar `index` of `count` is one of the center bars, which take the
+ * stronger color. The middle half of the row is.
+ */
+export declare const centered: (index: number, count: number) => boolean;
+/**
+ * The reading bar `index` of `count` follows: its band, where `bands` holds a
+ * different number of bands than there are bars read between the two nearest,
+ * and the level where there are no bands at all.
+ */
+export declare const bandFor: (bands: readonly number[], level: number, index: number, count: number) => number;
+/**
+ * One step of `current` toward `target` over `delta` seconds, rising at
+ * `RISE` and falling at `FALL`. Exponential, so the step is the same however
+ * the frames are spaced.
+ */
+export declare const ease: (current: number, target: number, delta: number) => number;
+/** One of the three lines the waves draw. */
+export interface WaveLine {
+    /** How many whole waves fit across the box. */
+    cycles: number;
+    /** Which color the line takes: the main color, the accent, or the main color faded. */
+    ink: 'accent' | 'faint' | 'main';
+    /** Where the line starts in its cycle, in radians. */
+    phase: number;
+    /** How fast it travels, in radians a second. A negative speed travels the other way. */
+    speed: number;
+    /** Its share of the amplitude, `1` for the main line. */
+    weight: number;
+    /** Its stroke, in CSS pixels. */
+    width: number;
+}
+/**
+ * The three lines, in the order they are drawn, the main line last so it lies
+ * on top. **Different speeds, phases, and weights**, so the three cross and
+ * part and never move as one.
+ */
+export declare const WAVE_LINES: readonly WaveLine[];
+/**
+ * The moment the waves are drawn at when the element is `still`, in seconds.
+ * Fixed, so a still picture is the same on every load.
+ */
+export declare const STILL_TIME = 0;
+/**
+ * How far a wave may leave the center line at `across`, from `0` at the start
+ * to `1` at the end: nothing at either end and all of it in the middle, so
+ * every line is pinned to the center at both ends.
+ */
+export declare const pinned: (across: number) => number;
+/**
+ * How far `line` stands from the center line at `across`, at `time` seconds,
+ * as a share of the amplitude: from `-1` to `1`.
+ */
+export declare const waveAt: (line: WaveLine, across: number, time: number) => number;
+/**
+ * The length of the still bar drawn under `prefers-reduced-motion`: the level's
+ * share of `span`, and never shorter than its own `thickness`, so silence is a
+ * dot.
+ */
+export declare const stillLength: (level: number, span: number, thickness: number) => number;

package/dist/voice-level/draw.js

@@ -0,0 +1,53 @@
+export const DEFAULT_BARS = 24;
+export const MIN_BARS = 3;
+export const MAX_BARS = 96;
+export const RISE = 22;
+export const FALL = 6;
+export const QUIET_STOP = 0.5;
+export const SILENT = 0.002;
+const SETTLED = 0.004;
+export const unit = (value) => Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
+export const barCount = (written) => {
+    const read = Number.parseInt(written, 10);
+    if (!Number.isFinite(read)) {
+        return DEFAULT_BARS;
+    }
+    return Math.min(MAX_BARS, Math.max(MIN_BARS, read));
+};
+export const envelope = (index, count) => {
+    if (count <= 1) {
+        return 1;
+    }
+    const across = Math.sin((Math.PI * (index + 0.5)) / count);
+    return 0.25 + 0.75 * across ** 1.2;
+};
+export const centered = (index, count) => Math.abs(index + 0.5 - count / 2) < count / 4;
+export const bandFor = (bands, level, index, count) => {
+    if (bands.length === 0) {
+        return unit(level);
+    }
+    if (bands.length === 1) {
+        return unit(bands[0] ?? 0);
+    }
+    const at = ((index + 0.5) / count) * bands.length - 0.5;
+    const low = Math.max(0, Math.min(bands.length - 1, Math.floor(at)));
+    const high = Math.min(bands.length - 1, low + 1);
+    const mix = Math.min(1, Math.max(0, at - low));
+    return unit((bands[low] ?? 0) * (1 - mix) + (bands[high] ?? 0) * mix);
+};
+export const ease = (current, target, delta) => {
+    const rate = target > current ? RISE : FALL;
+    const next = current + (target - current) * (1 - Math.exp(-rate * delta));
+    return Math.abs(next - target) < SETTLED ? target : next;
+};
+export const WAVE_LINES = [
+    { cycles: 2.6, ink: 'faint', phase: 2.4, speed: 3.4, weight: 0.5, width: 1 },
+    { cycles: 1.9, ink: 'accent', phase: 1.1, speed: -2.3, weight: 0.75, width: 1.5 },
+    { cycles: 1.3, ink: 'main', phase: 0, speed: 1.8, weight: 1, width: 2 },
+];
+export const STILL_TIME = 0;
+export const pinned = (across) => Math.sin(Math.PI * unit(across)) ** 2;
+export const waveAt = (line, across, time) => line.weight *
+    pinned(across) *
+    Math.sin(Math.PI * 2 * line.cycles * across + line.phase + line.speed * time);
+export const stillLength = (level, span, thickness) => Math.max(thickness, unit(level) * span);

package/dist/voice-level/index.d.ts

@@ -0,0 +1,2 @@
+export type { VoiceLevelVariant } from './draw.js';
+export * from './root/voice-level-root.js';

package/dist/voice-level/index.js

@@ -0,0 +1 @@
+export * from './root/voice-level-root.js';

package/dist/voice-level/root/voice-level-root.css.d.ts

@@ -0,0 +1 @@
+export declare const styles: import("lit").CSSResult;

package/dist/voice-level/root/voice-level-root.css.js

@@ -0,0 +1,2 @@
+import { createSheet } from '@fusion.dev/helix-core';
+export const styles = createSheet(`:host {--_voice-level-block-size: var(--voice-level-block-size, var(--helix-size-icon));--_voice-level-ratio: 4;--_voice-level-color: var(--voice-level-color, var(--helix-color-primary));block-size: var(--_voice-level-block-size);display: inline-block;flex-shrink: 0;inline-size: var(--voice-level-inline-size, calc(var(--_voice-level-block-size) * var(--_voice-level-ratio)));vertical-align: middle}:host([variant="waves"]) {--_voice-level-block-size: var(--voice-level-block-size, var(--helix-size-control));--_voice-level-ratio: 3}[part="canvas"] {animation-iteration-count: var(--voice-level-bars, 24);block-size: 100%;color: var(--_voice-level-color);column-rule-color: var(--voice-level-accent-color, var(--helix-color-accent));display: block;inline-size: 100%;text-decoration-color: var(--voice-level-edge-color, color-mix(in oklab, var(--_voice-level-color) 55%, transparent));transition-duration: var(--helix-duration-fast);transition-property: color, column-rule-color, text-decoration-color}[part="canvas"][hidden] {display: none}@media print {:host {display: none}}`);

package/dist/voice-level/root/voice-level-root.d.ts

@@ -0,0 +1,186 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
+import { type VoiceLevelVariant } from '../draw.js';
+/**
+ * @summary A live level of a voice, drawn as a row of bars or as moving waves.
+ *
+ * @description
+ * Two drawings, chosen with `variant`:
+ *
+ * - `spectrum`: a row of thin rounded bars, one for each frequency band in
+ *   `bands`, tallest in the middle. The middle half of the row takes the
+ *   stronger color. A quiet bar rests as a dot.
+ * - `waves`: three sine lines with different speeds, phases, and weights, held
+ *   to the center line at both ends. `level` sets how far they swing, and a
+ *   quiet level rests as a flat line.
+ *
+ * Set `level` and `bands` from your audio as often as you have readings, about
+ * 30 times a second. Each bar and wave eases toward its reading: up fast and
+ * down slower. A spectrum given no `bands` draws every bar from `level`.
+ *
+ * The drawing stops when it is off screen, in a background tab, or after the
+ * level has been zero for under a second, and starts again with the next
+ * reading. With `prefers-reduced-motion`, it draws one bar from the middle
+ * over a faint track, whose length is the level, and redraws it on each
+ * reading. With `still`, it draws either drawing as a still picture of its
+ * readings, whatever the motion preference.
+ *
+ * The level is an image named by `label`. A meter's value would be announced
+ * on every change, and a level changes many times a second.
+ *
+ * Voice Level is styled only and has behavior, which the tier split does not
+ * otherwise allow. Its role and name are set on the host, and the rest is
+ * drawing to a canvas.
+ *
+ * @since 0.215.0
+ * @status experimental
+ * @category feedback
+ * @aliases Audio Level, Waveform, Microphone Level, Equalizer, VU Meter
+ * @documentation https://fusion.dev/helix/components/voice-level
+ *
+ * @csspart canvas - The canvas the level is drawn on.
+ *
+ * @cssproperty --voice-level-accent-color - The color of the second wave. Defaults to the accent color.
+ * @cssproperty --voice-level-bars - How many bars the spectrum draws, from 3 to 96. Defaults to `24`.
+ * @cssproperty --voice-level-block-size - The height. Defaults to the icon size for `spectrum` and the control size for `waves`.
+ * @cssproperty --voice-level-color - The color of the center bars and the main wave. Defaults to the primary color.
+ * @cssproperty --voice-level-edge-color - The color of the bars at either end. Defaults to `--voice-level-color` at 55 percent.
+ * @cssproperty --voice-level-inline-size - The width. Defaults to four times the height for `spectrum` and three times for `waves`.
+ */
+export declare class HelixVoiceLevel extends HelixElement {
+    /**
+     * The key this family's words are registered under, its tag:
+     * `registerWords('de', { 'helix-voice-level': { fallbackLabel: 'Sprachpegel' } })`.
+     */
+    static words: string;
+    static styles: CSSResultGroup;
+    /**
+     * How loud each frequency band is, from `0` to `1`, lowest band first.
+     *
+     * Each bar of the spectrum follows one band. Where there are more or fewer
+     * bands than bars, each bar reads between the two nearest bands. Empty draws
+     * every bar from `level`. Written as an attribute, the numbers are separated
+     * by spaces or commas: `bands="0.1 0.4 0.6 0.3"`. Assign an array to the
+     * property for readings that change many times a second.
+     */
+    bands: string | readonly number[];
+    /**
+     * The name where `label` is empty. Translate it with the rest of your
+     * interface.
+     */
+    fallbackLabel: string;
+    /**
+     * The name read by screen readers, such as "Your voice". Defaults to
+     * `fallbackLabel`.
+     */
+    label: string;
+    /**
+     * How loud the voice is, from `0` for silence to `1`.
+     *
+     * It sets how far the waves swing, the length of the still bar under
+     * `prefers-reduced-motion`, and every bar of a spectrum that has no
+     * `bands`. A value outside the range is drawn at the nearer end.
+     */
+    level: number;
+    /**
+     * Draws the readings as a still picture: each bar at its band and the waves
+     * at one fixed moment, swung as far as `level`.
+     *
+     * For a level that holds, such as the loudness of a recorded clip or a
+     * picture of the drawing. No frame loop runs, and each new reading is drawn
+     * at once with no easing. Because nothing moves, the drawing is the same
+     * under `prefers-reduced-motion`. Clearing it starts the motion from the
+     * readings as they are.
+     */
+    still: boolean;
+    /**
+     * The drawing: a row of bars, one for each band, or three moving waves.
+     *
+     * Reflected because the stylesheet sizes each drawing differently. Absent
+     * is `spectrum`, the resting value, which selects nothing.
+     */
+    variant?: VoiceLevelVariant;
+    private canvas;
+    private context;
+    /** Whether the browser has taken the canvas, as its own two events say. */
+    private lost;
+    /** The box the canvas was last measured at, in CSS pixels. */
+    private width;
+    private height;
+    /** Each bar as it is drawn now, eased toward its band. */
+    private shown;
+    /** The waves' amplitude as it is drawn now, eased toward the level. */
+    private swing;
+    /** The waves' clock, in seconds. */
+    private time;
+    /** How long everything drawn has been at rest, in seconds. */
+    private quiet;
+    /**
+     * Whether the loop has stopped for a level at rest. A reading above zero
+     * clears it. Held here so the gate's own paths to a frame, a tab coming back
+     * or the element scrolling into view, do not start a loop with nothing to
+     * draw.
+     */
+    private resting;
+    private readonly gate;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+    protected firstUpdated(changed: PropertyValues): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Readings as numbers, each brought into `0` to `1`. */
+    private get readings();
+    /** Whether anything is to be drawn above rest: a level or a band above silence. */
+    private get sounding();
+    /**
+     * A new reading. Drawn at once under reduced motion, and otherwise handed to
+     * the loop, which is started where it had stopped for a level at rest.
+     */
+    private wake;
+    /**
+     * One frame for a still level, once a color the canvas carries has moved,
+     * so a theme changed while nothing moves is drawn in its own colors.
+     */
+    private readonly handleRestyle;
+    /**
+     * Everything the canvas needs, in one place both lifecycles reach, so an
+     * element moved by a framework keeps its observers.
+     */
+    private start;
+    /**
+     * Matches the drawing buffer to the box, at the device's pixel ratio capped
+     * at 2, and reports whether it changed.
+     */
+    private measure;
+    /** A 2D context comes back on its own, so a loss only stops the loop and hides the canvas. */
+    private readonly handleLost;
+    /** Sized again, because a restored canvas comes back in its default state. */
+    private readonly handleRestored;
+    /** Moves every bar and the waves one frame toward their readings. */
+    private step;
+    /**
+     * Every bar and the waves set to their readings with no easing, and the
+     * clock to the still moment, which is what `still` draws. The moving drawing
+     * starts from here when it is cleared.
+     */
+    private settle;
+    /** The bar count the hook asks for. */
+    private get bars();
+    /** One frame of whichever drawing `variant` names, or the still one. */
+    private paint;
+    /** The bars, the center ones in `main` and the rest in `edge`. */
+    private paintSpectrum;
+    /** The three waves at `time` seconds, the main one on top. */
+    private paintWaves;
+    /**
+     * Under reduced motion: one bar from the middle, as long as the level, in
+     * the main color, over a faint track the width of the box. As thick as a
+     * spectrum's bar or the main wave.
+     */
+    private paintStill;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-voice-level': HelixVoiceLevel;
+    }
+}