Matrix

1<script lang="ts" module>
2	import type { HTMLAttributes } from "svelte/elements";
3	import type { Frame } from "./presets.js";
4 
5	export type MatrixMode = "default" | "vu";
6 
7	export type MatrixProps = HTMLAttributes<HTMLDivElement> & {
8		/** Number of rows in the matrix grid. */
9		rows: number;
10		/** Number of columns in the matrix grid. */
11		cols: number;
12		/**
13		 * Static pattern to display. A 2D array of brightness values in
14		 * `[0, 1]`. When set, animation is disabled and `frames` is ignored.
15		 */
16		pattern?: Frame;
17		/**
18		 * Ordered frames to loop through for animation. Ignored when
19		 * `pattern` is provided.
20		 */
21		frames?: Frame[];
22		/**
23		 * Playback rate in frames per second when animating `frames`.
24		 * @default 12
25		 */
26		fps?: number;
27		/**
28		 * Start animating automatically on mount. Ignored when a static
29		 * `pattern` is provided.
30		 * @default true
31		 */
32		autoplay?: boolean;
33		/**
34		 * Loop the frame sequence. When `false`, animation halts on the last
35		 * frame.
36		 * @default true
37		 */
38		loop?: boolean;
39		/**
40		 * Cell diameter in pixels.
41		 * @default 10
42		 */
43		size?: number;
44		/**
45		 * Gap between cells in pixels.
46		 * @default 2
47		 */
48		gap?: number;
49		/**
50		 * CSS colors for active and inactive cells. Defaults map `on` to the
51		 * current text color and `off` to the muted foreground token.
52		 * @default { on: "currentColor", off: "var(--muted-foreground)" }
53		 */
54		palette?: { on: string; off: string };
55		/**
56		 * Global brightness multiplier applied to every cell, clamped to
57		 * `[0, 1]`.
58		 * @default 1
59		 */
60		brightness?: number;
61		/**
62		 * ARIA label for the container. Falls back to `"matrix display"` when
63		 * omitted.
64		 */
65		ariaLabel?: string;
66		/** Invoked whenever the active frame index changes during animation. */
67		onFrame?: (index: number) => void;
68		/**
69		 * Rendering mode. `"vu"` reads `levels` each render to draw a
70		 * bottom-anchored meter instead of `frames` or `pattern`.
71		 * @default "default"
72		 */
73		mode?: MatrixMode;
74		/**
75		 * Per-column level values in `[0, 1]` used when `mode="vu"`. Ignored
76		 * in other modes.
77		 */
78		levels?: number[];
79		/** Bound reference to the root container element. */
80		ref?: HTMLDivElement | null;
81	};
82</script>
83 
84<script lang="ts">
85	import { cn } from "$UTILS$.js";
86	import { clamp, ensureFrameSize, vu } from "./presets.js";
87 
88	let {
89		rows,
90		cols,
91		pattern,
92		frames,
93		fps = 12,
94		autoplay = true,
95		loop = true,
96		size = 10,
97		gap = 2,
98// … truncated