@mks2508/mks-ui 0.6.8 → 0.8.0

package/dist/react-ui/primitives/DotMatrix/dot.css

@@ -0,0 +1,364 @@
+/* =============================================================================
+ *  DotMatrix — progressive fill model.
+ *
+ *  Cells light up one at a time in `pattern` order, stay lit until the
+ *  cycle resets, then repeat. Implementation uses ONE CSS animation per
+ *  matrix that drives a registered custom property `--dm-phase` from
+ *  0 → 1 (fill), holds it at 1 (hold), then snaps back to 0 (reset)
+ *  for a rest period.
+ *
+ *  Each cell carries a `--dm-threshold` (its position in the fill
+ *  sequence, 0..1) and computes its own `::before` opacity as a step
+ *  across `phase - threshold`, multiplied by `--dm-edge-sharpness` so
+ *  the edge can range from "instant snap" to "warm fade".
+ *
+ *  Perf shape: N matrices = N animations total (not N × cells). Cell
+ *  opacity is computed at paint time by calc(); the compositor batches
+ *  updates via the shared phase var. With `contain: layout style paint`
+ *  each cell is isolated so work doesn't cascade.
+ * ============================================================================= */
+
+@property --dm-phase {
+	syntax: '<number>';
+	initial-value: 0;
+	inherits: true;
+}
+
+.dm-root {
+	display: grid;
+	width: 100%;
+	gap: var(--dm-gap, 5px);
+	padding: var(--dm-pad, 0.25rem);
+	border-radius: 0.5rem;
+	background-color: transparent;
+
+	/* Skip render work when the matrix is offscreen. */
+	content-visibility: auto;
+	contain-intrinsic-size: auto 200px;
+	transform: translateZ(0);
+
+	--dm-on: var(--foreground);
+	--dm-off: color-mix(in oklch, var(--foreground) 12%, transparent);
+	--dm-glow: color-mix(in oklch, var(--foreground) 50%, transparent);
+}
+
+/* ─── Cell: base OFF layer — neutral dim ──────────────────────────────── */
+
+.dm-cell {
+	position: relative;
+	aspect-ratio: 1 / 1;
+	min-width: 4px;
+	min-height: 4px;
+	border-radius: var(--dm-radius, 32%);
+	background-color: color-mix(in oklch, var(--foreground) 10%, transparent);
+	opacity: var(--dm-off-opacity, 0.45);
+	transform: scale(var(--dm-off-scale, 0.9));
+	contain: layout style paint;
+
+	--dm-threshold: 0;
+	--dm-stagger-delay: 0ms;
+}
+
+/* ─── Pseudo: ON layer — LED look, fades in as phase crosses threshold ─ */
+
+.dm-cell::before {
+	content: '';
+	position: absolute;
+	inset: 0;
+	border-radius: inherit;
+	background-color: var(--dm-on);
+	background-image:
+		radial-gradient(
+			circle at 32% 26%,
+			rgb(255 255 255 / 0.35) 0%,
+			rgb(255 255 255 / 0.12) 18%,
+			transparent 48%
+		),
+		radial-gradient(
+			circle at 70% 78%,
+			rgb(0 0 0 / 0.22) 0%,
+			transparent 60%
+		);
+	box-shadow:
+		inset 0 0 1px rgb(255 255 255 / 0.55),
+		inset 0 0 0 1px color-mix(in oklch, var(--dm-on) 65%, transparent),
+		inset 0 -1px 2px color-mix(in oklch, var(--dm-on) 40%, black 20%);
+	opacity: 0;
+	pointer-events: none;
+}
+
+.dm-root[data-variant='glow'] .dm-cell::before {
+	box-shadow:
+		inset 0 0 1px rgb(255 255 255 / 0.55),
+		inset 0 0 0 1px color-mix(in oklch, var(--dm-on) 65%, transparent),
+		inset 0 -1px 2px color-mix(in oklch, var(--dm-on) 40%, black 20%),
+		0 0 2px var(--dm-glow),
+		0 0 6px var(--dm-glow),
+		0 0 12px color-mix(in oklch, var(--dm-glow) 55%, transparent);
+}
+
+/* ─── Running: phase animates on root, cells derive state from it ────── */
+
+.dm-root[data-status='running'] {
+	animation-name: var(--dm-anim-phase);
+	animation-duration: var(--dm-cycle-total, 2600ms);
+	animation-iteration-count: infinite;
+	animation-timing-function: linear;
+	animation-fill-mode: both;
+}
+
+/* Lit fraction for THIS cell — 0 when off, 1 when fully filled, ramped
+ * near the threshold by `--dm-edge-sharpness`. Reused by both the pseudo
+ * opacity (the LED glow) and the cell's scale (grows when lit). */
+.dm-root[data-status='running'] .dm-cell {
+	opacity: 1;
+	transform: scale(
+		calc(
+			var(--dm-off-scale, 0.88) +
+			(var(--dm-on-scale, 1) - var(--dm-off-scale, 0.88)) *
+			clamp(
+				0,
+				(var(--dm-phase) - var(--dm-threshold)) *
+					var(--dm-edge-sharpness, 50),
+				1
+			)
+		)
+	);
+}
+
+.dm-root[data-status='running'] .dm-cell::before {
+	opacity: clamp(
+		0,
+		calc(
+			(var(--dm-phase) - var(--dm-threshold)) *
+			var(--dm-edge-sharpness, 50)
+		),
+		1
+	);
+}
+
+/* ─── Accent cells ────────────────────────────────────────────────────── */
+
+.dm-cell[data-accent='true'] {
+	opacity: 1;
+	transform: scale(1);
+}
+
+.dm-cell[data-accent='true']::before {
+	background-color: var(--primary);
+	background-image: none;
+	box-shadow:
+		inset 0 0 1px rgb(255 255 255 / 0.5),
+		0 0 3px color-mix(in oklch, var(--primary) 70%, transparent),
+		0 0 7px color-mix(in oklch, var(--primary) 50%, transparent);
+	opacity: 1 !important;
+}
+
+/* ─── Lifecycle FINAL animations ──────────────────────────────────────── */
+
+@keyframes dm-success-pop {
+	0% {
+		transform: scale(0.94);
+		filter: brightness(0.7);
+	}
+	45% {
+		transform: scale(1.18);
+		filter: brightness(1.4);
+	}
+	100% {
+		transform: scale(1);
+		filter: brightness(1);
+	}
+}
+
+@keyframes dm-fail-strobe {
+	0% {
+		transform: scale(1);
+		filter: brightness(1);
+	}
+	22% {
+		transform: scale(1.22);
+		filter: brightness(1.55) saturate(1.4);
+	}
+	55% {
+		transform: scale(0.92);
+		filter: brightness(0.75);
+	}
+	100% {
+		transform: scale(0.97);
+		filter: brightness(1);
+	}
+}
+
+@keyframes dm-cancelled-dim {
+	0% {
+		transform: scale(1);
+		opacity: 1;
+	}
+	100% {
+		transform: scale(0.9);
+		opacity: 0.55;
+	}
+}
+
+.dm-root[data-status='success'] {
+	animation: none;
+}
+.dm-root[data-status='success'] .dm-cell {
+	opacity: 1;
+	transform: scale(1);
+	animation: dm-success-pop 520ms cubic-bezier(0.2, 0, 0.2, 1) both;
+	animation-delay: var(--dm-stagger-delay, 0ms);
+}
+.dm-root[data-status='success'] .dm-cell::before {
+	opacity: 1;
+}
+
+.dm-root[data-status='failed'] {
+	animation: none;
+}
+.dm-root[data-status='failed'] .dm-cell {
+	opacity: 1;
+	animation: dm-fail-strobe 560ms cubic-bezier(0.2, 0, 0.2, 1) both;
+	animation-delay: var(--dm-stagger-delay, 0ms);
+}
+.dm-root[data-status='failed'] .dm-cell::before {
+	background-color: var(--destructive);
+	box-shadow:
+		inset 0 0 1px rgb(255 255 255 / 0.5),
+		inset 0 0 0 1px color-mix(in oklch, var(--destructive) 55%, transparent),
+		inset 0 -1px 2px color-mix(in oklch, var(--destructive) 40%, black 20%);
+	opacity: 1;
+}
+.dm-root[data-status='failed'][data-variant='glow'] .dm-cell::before {
+	box-shadow:
+		inset 0 0 1px rgb(255 255 255 / 0.55),
+		inset 0 0 0 1px color-mix(in oklch, var(--destructive) 55%, transparent),
+		inset 0 -1px 2px color-mix(in oklch, var(--destructive) 40%, black 20%),
+		0 0 3px color-mix(in oklch, var(--destructive) 70%, transparent),
+		0 0 9px color-mix(in oklch, var(--destructive) 55%, transparent);
+}
+
+.dm-root[data-status='cancelled'] {
+	animation: none;
+}
+.dm-root[data-status='cancelled'] .dm-cell {
+	background-color: color-mix(in oklch, var(--foreground) 22%, transparent);
+	opacity: 0.65;
+	animation: dm-cancelled-dim 380ms cubic-bezier(0.4, 0, 0.8, 0.6) both;
+	animation-delay: var(--dm-stagger-delay, 0ms);
+}
+.dm-root[data-status='cancelled'] .dm-cell::before {
+	opacity: 0;
+}
+
+.dm-root[data-status='idle'] {
+	animation: none;
+}
+.dm-root[data-status='idle'] .dm-cell::before {
+	opacity: 0;
+}
+
+/* ─── Theme-token palettes ────────────────────────────────────────────── */
+
+.dm--foreground {
+	--dm-on: var(--foreground);
+	--dm-off: color-mix(in oklch, var(--foreground) 12%, transparent);
+	--dm-glow: color-mix(in oklch, var(--foreground) 55%, transparent);
+}
+
+.dm--primary {
+	--dm-on: var(--primary);
+	--dm-off: color-mix(in oklch, var(--primary) 14%, transparent);
+	--dm-glow: color-mix(in oklch, var(--primary) 65%, transparent);
+}
+
+.dm--destructive {
+	--dm-on: var(--destructive);
+	--dm-off: color-mix(in oklch, var(--destructive) 14%, transparent);
+	--dm-glow: color-mix(in oklch, var(--destructive) 65%, transparent);
+}
+
+.dm--warning {
+	--dm-on: var(--warning);
+	--dm-off: color-mix(in oklch, var(--warning) 14%, transparent);
+	--dm-glow: color-mix(in oklch, var(--warning) 65%, transparent);
+}
+
+/* ─── Named palettes (OKLCH for stability) ────────────────────────────── */
+
+.dm--cyan {
+	--dm-on: oklch(90% 0.2 195);
+	--dm-off: oklch(40% 0.08 195 / 0.4);
+	--dm-glow: oklch(80% 0.25 195 / 0.95);
+}
+.dm--magenta {
+	--dm-on: oklch(85% 0.25 330);
+	--dm-off: oklch(40% 0.08 330 / 0.4);
+	--dm-glow: oklch(75% 0.3 330 / 0.95);
+}
+.dm--yellow {
+	--dm-on: oklch(95% 0.2 90);
+	--dm-off: oklch(50% 0.08 90 / 0.4);
+	--dm-glow: oklch(90% 0.25 90 / 0.95);
+}
+.dm--green {
+	--dm-on: oklch(90% 0.25 145);
+	--dm-off: oklch(40% 0.08 145 / 0.4);
+	--dm-glow: oklch(80% 0.3 145 / 0.95);
+}
+.dm--orange {
+	--dm-on: oklch(85% 0.22 50);
+	--dm-off: oklch(45% 0.08 50 / 0.4);
+	--dm-glow: oklch(75% 0.28 50 / 0.95);
+}
+.dm--blue {
+	--dm-on: oklch(80% 0.22 260);
+	--dm-off: oklch(40% 0.08 260 / 0.4);
+	--dm-glow: oklch(70% 0.28 260 / 0.95);
+}
+.dm--red {
+	--dm-on: oklch(70% 0.25 25);
+	--dm-off: oklch(40% 0.08 25 / 0.4);
+	--dm-glow: oklch(60% 0.3 25 / 0.95);
+}
+.dm--purple {
+	--dm-on: oklch(75% 0.22 300);
+	--dm-off: oklch(40% 0.08 300 / 0.4);
+	--dm-glow: oklch(65% 0.28 300 / 0.95);
+}
+.dm--teal {
+	--dm-on: oklch(82% 0.18 175);
+	--dm-off: oklch(40% 0.08 175 / 0.4);
+	--dm-glow: oklch(72% 0.24 175 / 0.95);
+}
+.dm--pink {
+	--dm-on: oklch(80% 0.2 350);
+	--dm-off: oklch(45% 0.08 350 / 0.4);
+	--dm-glow: oklch(70% 0.26 350 / 0.95);
+}
+.dm--lime {
+	--dm-on: oklch(88% 0.22 120);
+	--dm-off: oklch(45% 0.08 120 / 0.4);
+	--dm-glow: oklch(80% 0.28 120 / 0.95);
+}
+.dm--white {
+	--dm-on: oklch(98% 0 0);
+	--dm-off: oklch(50% 0 0 / 0.3);
+	--dm-glow: oklch(95% 0 0 / 0.85);
+}
+
+/* ─── Reduced motion — freeze animations ─────────────────────────────── */
+
+@media (prefers-reduced-motion: reduce) {
+	.dm-root[data-status='running'],
+	.dm-root[data-status='success'] .dm-cell,
+	.dm-root[data-status='failed'] .dm-cell,
+	.dm-root[data-status='cancelled'] .dm-cell {
+		animation: none !important;
+	}
+	.dm-cell {
+		transform: none;
+	}
+}
+

package/dist/react-ui/primitives/DotMatrix/index.d.ts

@@ -0,0 +1,7 @@
+import './dot-matrix.css';
+import type { IDotMatrixProps } from './DotMatrix.types';
+export * from './DotMatrix.types';
+export { DOT_MATRIX_PATTERNS, buildDelays } from './patterns';
+export type { DotMatrixPattern } from './patterns';
+export declare function DotMatrix({ rows, cols, pattern, patternStep, holdSteps, restSteps, edgeSharpness, progress, status, color, bloom, variant, accentCount, accentRow, accentPositions, slots, className, 'aria-label': ariaLabel, }: IDotMatrixProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/dist/react-ui/primitives/DotMatrix/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/primitives/DotMatrix/index.tsx"],"names":[],"mappings":"AA0BA,OAAO,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAIX,eAAe,EACf,MAAM,mBAAmB,CAAC;AAE3B,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AA6GnD,wBAAgB,SAAS,CAAC,EACzB,IAAQ,EACR,IAAS,EACT,OAAiB,EACjB,WAAiB,EACjB,SAAa,EACb,SAAa,EACb,aAAkB,EAClB,QAAQ,EACR,MAAkB,EAClB,KAAoB,EACpB,KAAY,EACZ,OAAgB,EAChB,WAAe,EACf,SAAiB,EACjB,eAAe,EACf,KAAK,EACL,SAAS,EACT,YAAY,EAAE,SAAS,GACvB,EAAE,eAAe,2CAuJjB"}

package/dist/react-ui/primitives/DotMatrix/index.js

@@ -0,0 +1,185 @@
+'use client';
+
+import { cn } from "../../lib/utils.js";
+import "./dot-matrix.js";
+import { DOT_MATRIX_PATTERNS, buildDelays } from "./patterns.js";
+import { useEffect, useId, useMemo } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/react-ui/primitives/DotMatrix/index.tsx
+/**
+* DotMatrix — pattern-driven rows×cols grid with progressive-fill cycle.
+*
+*   - Cells light up one at a time in `pattern` order (`wave-lr` fills
+*     left-to-right, `spiral-cw` fills outward-in, etc.). Once lit they
+*     stay on until the cycle resets.
+*   - While `status='running'` the root runs a single CSS animation
+*     that drives `--dm-phase` from 0 → 1 (fill) → held at 1 (hold) →
+*     snapped to 0 (reset/rest). Each cell computes its opacity from
+*     `(phase − threshold) × edgeSharpness`, where `threshold` is its
+*     position in the fill sequence (0..1). One animation per matrix
+*     regardless of cell count.
+*   - Status flips to `idle / success / failed / cancelled` swap to
+*     one-shot final keyframes that force EVERY cell to the status
+*     colour (all on for success, all destructive for failed, all
+*     muted for cancelled).
+*
+* @module @mks2508/mks-ui/react/primitives/DotMatrix
+*/
+const BLOOM_SVG_ID = "dm-bloom-svg";
+const DEFAULT_BLOOM = 2;
+function ensureBloomSvg() {
+	if (typeof document === "undefined") return null;
+	let svg = document.getElementById(BLOOM_SVG_ID);
+	if (svg) return svg;
+	const ns = "http://www.w3.org/2000/svg";
+	svg = document.createElementNS(ns, "svg");
+	svg.setAttribute("id", BLOOM_SVG_ID);
+	svg.setAttribute("aria-hidden", "true");
+	svg.setAttribute("style", "position:absolute;width:0;height:0;overflow:hidden");
+	svg.appendChild(document.createElementNS(ns, "defs"));
+	document.body.appendChild(svg);
+	return svg;
+}
+function installBloomFilter(id, amount) {
+	const svg = ensureBloomSvg();
+	if (!svg) return;
+	const defs = svg.firstChild;
+	const existing = document.getElementById(id);
+	if (existing) existing.parentNode?.removeChild(existing);
+	const ns = "http://www.w3.org/2000/svg";
+	const filter = document.createElementNS(ns, "filter");
+	filter.setAttribute("id", id);
+	filter.setAttribute("x", "-100%");
+	filter.setAttribute("y", "-100%");
+	filter.setAttribute("width", "300%");
+	filter.setAttribute("height", "300%");
+	const matrix = document.createElementNS(ns, "feColorMatrix");
+	matrix.setAttribute("in", "SourceGraphic");
+	matrix.setAttribute("type", "matrix");
+	matrix.setAttribute("values", "2 0 0 0 -0.5 0 2 0 0 -0.5 0 0 2 0 -0.5 0 0 0 1 0");
+	matrix.setAttribute("result", "bright");
+	const blur = document.createElementNS(ns, "feGaussianBlur");
+	blur.setAttribute("in", "bright");
+	blur.setAttribute("stdDeviation", String(amount));
+	blur.setAttribute("result", "glow");
+	const blend = document.createElementNS(ns, "feBlend");
+	blend.setAttribute("in", "SourceGraphic");
+	blend.setAttribute("in2", "glow");
+	blend.setAttribute("mode", "screen");
+	filter.appendChild(matrix);
+	filter.appendChild(blur);
+	filter.appendChild(blend);
+	defs.appendChild(filter);
+}
+function removeBloomFilter(id) {
+	if (typeof document === "undefined") return;
+	const el = document.getElementById(id);
+	if (el) el.parentNode?.removeChild(el);
+}
+function computeAccentSet(rows, cols, count, row, positions) {
+	const set = /* @__PURE__ */ new Set();
+	if (positions?.length) {
+		for (const [r, c] of positions) if (r >= 0 && r < rows && c >= 0 && c < cols) set.add(r * cols + c);
+		return set;
+	}
+	const n = Math.max(0, Math.min(count, cols));
+	if (n === 0) return set;
+	const startCol = Math.floor((cols - n) / 2);
+	if (row === "top" || row === "both") for (let i = 0; i < n; i++) set.add(startCol + i);
+	if (row === "bottom" || row === "both") for (let i = 0; i < n; i++) set.add((rows - 1) * cols + startCol + i);
+	return set;
+}
+function DotMatrix({ rows = 6, cols = 18, pattern = "snake", patternStep = 120, holdSteps = 6, restSteps = 4, edgeSharpness = 50, progress, status = "running", color = "foreground", bloom = true, variant = "glow", accentCount = 0, accentRow = "top", accentPositions, slots, className, "aria-label": ariaLabel }) {
+	const total = rows * cols;
+	const reactId = useId().replace(/:/g, "");
+	const bloomFilterId = `dm-bloom-${reactId}`;
+	const kfPhaseName = `dmph-${reactId}`;
+	const accentSet = useMemo(() => computeAccentSet(rows, cols, accentCount, accentRow, accentPositions), [
+		rows,
+		cols,
+		accentCount,
+		accentRow,
+		accentPositions
+	]);
+	useEffect(() => {
+		if (!bloom) {
+			removeBloomFilter(bloomFilterId);
+			return;
+		}
+		installBloomFilter(bloomFilterId, typeof bloom === "number" ? bloom : DEFAULT_BLOOM);
+		return () => removeBloomFilter(bloomFilterId);
+	}, [bloom, bloomFilterId]);
+	const ranks = useMemo(() => buildDelays(pattern, rows, cols, 1), [
+		pattern,
+		rows,
+		cols
+	]);
+	const maxRank = ranks.length > 0 ? Math.max(...ranks) : 0;
+	const fillSteps = maxRank + 1;
+	const cycleSteps = Math.max(1, fillSteps + holdSteps + restSteps);
+	const cycleTotalMs = cycleSteps * patternStep;
+	const fillEndPct = fillSteps / cycleSteps * 100;
+	const holdEndPct = (fillSteps + holdSteps) / cycleSteps * 100;
+	const resetSnapPct = Math.min(100, holdEndPct + .05);
+	const keyframesCSS = useMemo(() => {
+		return `
+@keyframes ${kfPhaseName} {
+  0% { --dm-phase: 0; }
+  ${fillEndPct.toFixed(3)}% { --dm-phase: 1; }
+  ${holdEndPct.toFixed(3)}% { --dm-phase: 1; }
+  ${resetSnapPct.toFixed(3)}% { --dm-phase: 0; }
+  100% { --dm-phase: 0; }
+}`;
+	}, [
+		kfPhaseName,
+		fillEndPct,
+		holdEndPct,
+		resetSnapPct
+	]);
+	const finalStagger = useMemo(() => {
+		if (maxRank <= 0) return new Array(ranks.length).fill(0);
+		const w = 220;
+		return ranks.map((r) => Math.round(r / maxRank * w));
+	}, [ranks, maxRank]);
+	const N = Math.max(1, maxRank + 1);
+	const isControlled = typeof progress === "number";
+	const clampedProgress = isControlled ? Math.max(0, Math.min(1, progress)) : void 0;
+	const effectiveSharpness = isControlled ? N : edgeSharpness;
+	const rootStyle = {
+		gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))`,
+		["--dm-cycle-total"]: `${cycleTotalMs}ms`,
+		["--dm-edge-sharpness"]: String(effectiveSharpness),
+		...isControlled ? { ["--dm-phase"]: String(clampedProgress) } : { ["--dm-anim-phase"]: kfPhaseName },
+		...bloom ? { filter: `url(#${bloomFilterId})` } : {}
+	};
+	const paletteClass = paletteClassFor(color);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [!isControlled && /* @__PURE__ */ jsx("style", { dangerouslySetInnerHTML: { __html: keyframesCSS } }), /* @__PURE__ */ jsx("div", {
+		className: cn("dm-root", paletteClass, slots?.root, className),
+		style: rootStyle,
+		role: "img",
+		"aria-label": ariaLabel,
+		"data-status": status,
+		"data-variant": variant,
+		"data-pattern": pattern,
+		children: Array.from({ length: total }).map((_, i) => {
+			const rank = ranks[i] ?? 0;
+			const threshold = isControlled ? rank / N : maxRank > 0 ? rank / maxRank : 0;
+			return /* @__PURE__ */ jsx("div", {
+				"data-accent": accentSet.has(i) ? "true" : void 0,
+				className: cn("dm-cell", slots?.cell),
+				style: {
+					"--dm-threshold": threshold.toFixed(4),
+					"--dm-stagger-delay": `${finalStagger[i] ?? 0}ms`
+				}
+			}, i);
+		})
+	})] });
+}
+/** @internal */
+function paletteClassFor(color) {
+	return `dm--${color}`;
+}
+
+//#endregion
+export { DotMatrix };

package/dist/react-ui/primitives/DotMatrix/patterns.d.ts

@@ -0,0 +1,32 @@
+/**
+ * DotMatrix patterns — delay-field generators that scale any 3x3
+ * pattern from 3-pixel-grid (MetaHeavies) to arbitrary `rows × cols`.
+ *
+ * Each generator returns a flat array of length `rows × cols` indexed
+ * by physical position (`r * cols + c`). Values are delays in ms that
+ * tell the cycle engine *when* each cell flips on/off relative to the
+ * start of a phase.
+ *
+ * Reference: https://github.com/MetaHeavies/3-pixel-grid
+ *
+ * @module @mks2508/mks-ui/react/primitives/DotMatrix
+ */
+/** Available built-in patterns. */
+export type DotMatrixPattern = 'wave-lr' | 'wave-rl' | 'wave-tb' | 'wave-bt' | 'spiral-cw' | 'corners-first' | 'center-out' | 'diagonal-tl' | 'snake' | 'snake-up' | 'cross' | 'checkerboard' | 'rain' | 'pinwheel' | 'converge' | 'zigzag';
+/** Catalogue of all pattern names. Handy for UIs / debug labs. */
+export declare const DOT_MATRIX_PATTERNS: readonly DotMatrixPattern[];
+/**
+ * Build the delay array for `pattern` at `rows × cols`, scaled by `step`
+ * (ms between successive cells in simple sweep patterns).
+ *
+ * Always returns an array of exact length `rows * cols`.
+ *
+ * @example
+ * ```ts
+ * const delays = buildDelays('wave-lr', 6, 18, 60);
+ * // delays[0]=0, delays[1]=60, ..., delays[17]=1020
+ * // delays[18]=0, delays[19]=60, ... (all rows identical for wave-lr)
+ * ```
+ */
+export declare function buildDelays(pattern: DotMatrixPattern, rows: number, cols: number, step?: number): number[];
+//# sourceMappingURL=patterns.d.ts.map

package/dist/react-ui/primitives/DotMatrix/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../../../src/react-ui/primitives/DotMatrix/patterns.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GACzB,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,eAAe,GACf,YAAY,GACZ,aAAa,GACb,OAAO,GACP,UAAU,GACV,OAAO,GACP,cAAc,GACd,MAAM,GACN,UAAU,GACV,UAAU,GACV,QAAQ,CAAC;AAEZ,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EAiBjD,CAAC;AA0CX;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAC1B,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,SAAK,GACP,MAAM,EAAE,CAgJV"}