Waveform

1<script lang="ts">
2	import type { HTMLAttributes } from "svelte/elements";
3	import { cn } from "$UTILS$.js";
4	import { getComputedBarColor, heightToCssSize } from "./utils.js";
5 
6	export type WaveformProps = HTMLAttributes<HTMLDivElement> & {
7		/**
8		 * Array of normalized bar values in `[0, 1]`. The component samples from
9		 * this array to fill the available width.
10		 * @default []
11		 */
12		data?: number[];
13		/**
14		 * Width of each bar in pixels.
15		 * @default 4
16		 */
17		barWidth?: number;
18		/**
19		 * Minimum bar height in pixels. Bars are drawn at least this tall even
20		 * when their value is near zero.
21		 * @default 4
22		 */
23		barHeight?: number;
24		/**
25		 * Gap between bars in pixels.
26		 * @default 2
27		 */
28		barGap?: number;
29		/**
30		 * Corner radius applied to each bar. Set to `0` for square bars.
31		 * @default 2
32		 */
33		barRadius?: number;
34		/**
35		 * Custom bar color. Falls back to the canvas's computed `--foreground`
36		 * CSS variable when unset.
37		 */
38		barColor?: string;
39		/**
40		 * Fade the left and right edges of the waveform via a destination-out
41		 * gradient mask.
42		 * @default true
43		 */
44		fadeEdges?: boolean;
45		/**
46		 * Width of the edge fade region in pixels.
47		 * @default 24
48		 */
49		fadeWidth?: number;
50		/**
51		 * Height of the waveform container. Numbers are treated as pixels;
52		 * strings are passed through as a CSS length.
53		 * @default 128
54		 */
55		height?: string | number;
56		/**
57		 * Marks the waveform as actively capturing or rendering audio. Rendered
58		 * as `data-active` on the root element for CSS styling hooks.
59		 */
60		active?: boolean;
61		/** Called when a bar is clicked with the data index and its value. */
62		onBarClick?: (index: number, value: number) => void;
63	};
64 
65	let {
66		data = [],
67		barWidth = 4,
68		barHeight: baseBarHeight = 4,
69		barGap = 2,
70		barRadius = 2,
71		barColor,
72		fadeEdges = true,
73		fadeWidth = 24,
74		height = 128,
75		active,
76		onBarClick,
77		class: className,
78		...restProps
79	}: WaveformProps = $props();
80 
81	let canvasEl: HTMLCanvasElement | null = $state(null);
82	let containerEl: HTMLDivElement | null = $state(null);
83 
84	const heightStyle = $derived(heightToCssSize(height));
85 
86	$effect(() => {
87		const canvas = canvasEl;
88		const container = containerEl;
89		if (!canvas || !container) return;
90 
91		// Reactive dependency reads — re-runs the effect when any of these change.
92		const _data = data;
93		const _barWidth = barWidth;
94		const _baseBarHeight = baseBarHeight;
95		const _barGap = barGap;
96		const _barRadius = barRadius;
97// … truncated