@auscera/design-labs 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/apps/workspace/.skills/design-labs/SKILL.md +63 -0
  2. package/apps/workspace/.skills/design-labs/references/commands.md +38 -0
  3. package/apps/workspace/AGENTS.md +9 -0
  4. package/apps/workspace/app/(lab)/compare/page.tsx +2 -0
  5. package/apps/workspace/app/(lab)/lab.css +412 -0
  6. package/apps/workspace/app/(lab)/layout.tsx +21 -0
  7. package/apps/workspace/app/(lab)/page.tsx +2 -0
  8. package/apps/workspace/app/api/annotations/route.ts +94 -0
  9. package/apps/workspace/app/api/versions/events/route.ts +63 -0
  10. package/apps/workspace/app/api/versions/route.ts +7 -0
  11. package/apps/workspace/components/animated-icons.tsx +72 -0
  12. package/apps/workspace/components/dotmatrix-loader.css +1228 -0
  13. package/apps/workspace/components/glass-controls.tsx +47 -0
  14. package/apps/workspace/components/lab-providers.tsx +17 -0
  15. package/apps/workspace/components/molecules/brand-lockup.tsx +13 -0
  16. package/apps/workspace/components/molecules/pane-url-popover.css +92 -0
  17. package/apps/workspace/components/molecules/pane-url-popover.tsx +191 -0
  18. package/apps/workspace/components/pane-preferences.tsx +75 -0
  19. package/apps/workspace/components/pane-viewport.css +34 -0
  20. package/apps/workspace/components/pane-viewport.tsx +199 -0
  21. package/apps/workspace/components/preview-pane.css +293 -0
  22. package/apps/workspace/components/preview-pane.tsx +662 -0
  23. package/apps/workspace/components/ui/dotm-triangle-11.tsx +170 -0
  24. package/apps/workspace/components/ui/dotmatrix-core.tsx +1649 -0
  25. package/apps/workspace/components/ui/dotmatrix-hooks.ts +224 -0
  26. package/apps/workspace/components/version-select.tsx +220 -0
  27. package/apps/workspace/components/workspace.tsx +313 -0
  28. package/apps/workspace/eslint.config.mjs +3 -0
  29. package/apps/workspace/lab.config.json +1 -0
  30. package/apps/workspace/lib/annotation-export.ts +28 -0
  31. package/apps/workspace/lib/annotation-types.ts +38 -0
  32. package/apps/workspace/lib/device-presets.ts +103 -0
  33. package/apps/workspace/lib/use-annotation-bridge.ts +130 -0
  34. package/apps/workspace/lib/version-types.ts +12 -0
  35. package/apps/workspace/lib/website-url.ts +78 -0
  36. package/apps/workspace/next-env.d.ts +6 -0
  37. package/apps/workspace/next.config.mjs +1 -0
  38. package/apps/workspace/package.json +35 -0
  39. package/apps/workspace/public/apple-touch-icon.png +0 -0
  40. package/apps/workspace/public/brand/design-labs-script.LICENSE.txt +93 -0
  41. package/apps/workspace/public/brand/design-labs-script.woff2 +0 -0
  42. package/apps/workspace/public/brand/logo.webp +0 -0
  43. package/apps/workspace/public/brand/wordmark.css +42 -0
  44. package/apps/workspace/public/favicon.ico +0 -0
  45. package/apps/workspace/public/icon-192.png +0 -0
  46. package/apps/workspace/public/icon-512.png +0 -0
  47. package/apps/workspace/public/preview-bridge.js +411 -0
  48. package/apps/workspace/public/site.webmanifest +1 -0
  49. package/apps/workspace/scripts/annotation-store.mjs +308 -0
  50. package/apps/workspace/scripts/lab.mjs +414 -0
  51. package/apps/workspace/scripts/migrate.mjs +2 -0
  52. package/apps/workspace/scripts/prepare-preview.mjs +203 -0
  53. package/apps/workspace/tsconfig.json +24 -0
  54. package/package.json +9 -3
  55. package/scripts/install.mjs +67 -0
  56. package/scripts/update.mjs +204 -0
  57. package/README.md +0 -3
@@ -0,0 +1,1649 @@
1
+ "use client";
2
+
3
+ import type { CSSProperties } from "react";
4
+
5
+ import "../dotmatrix-loader.css";
6
+ import { useMemo } from "react";
7
+ import { useDotMatrixPhases, usePrefersReducedMotion, useCyclePhase } from "./dotmatrix-hooks";
8
+
9
+ export type MatrixPattern = "diamond" | "full" | "outline" | "rose" | "cross" | "rings";
10
+ export type DotShape = "circle" | "square" | "diamond" | "hearts";
11
+ export type DotMatrixPhase = "idle" | "collapse" | "hoverRipple" | "loadingRipple";
12
+ export type DotMatrixColorPreset =
13
+ | "solid-theme"
14
+ | "solid-mint"
15
+ | "grad-sunset"
16
+ | "grad-ocean"
17
+ | "grad-neon"
18
+ | "grad-aurora"
19
+ | "grad-fire"
20
+ | "grad-prism";
21
+
22
+ const DOT_MATRIX_COLOR_PRESETS: Record<
23
+ DotMatrixColorPreset,
24
+ {
25
+ fill: string;
26
+ glow: string;
27
+ }
28
+ > = {
29
+ "solid-theme": {
30
+ fill: "var(--color-dot-on)",
31
+ glow: "var(--color-dot-on)"
32
+ },
33
+ "solid-mint": {
34
+ fill: "#34d399",
35
+ glow: "#34d399"
36
+ },
37
+ "grad-sunset": {
38
+ fill: "linear-gradient(135deg, #ff5f6d 0%, #ffc371 52%, #ffe29a 100%)",
39
+ glow: "#ff8b73"
40
+ },
41
+ "grad-ocean": {
42
+ fill: "linear-gradient(140deg, #00c6ff 0%, #0072ff 48%, #4facfe 100%)",
43
+ glow: "#2f8fff"
44
+ },
45
+ "grad-neon": {
46
+ fill: "linear-gradient(145deg, #b4ff39 0%, #39ffb6 46%, #00d4ff 100%)",
47
+ glow: "#59ffc8"
48
+ },
49
+ "grad-aurora": {
50
+ fill: "linear-gradient(145deg, #ff3cac 0%, #784ba0 45%, #2b86c5 100%)",
51
+ glow: "#9c64bf"
52
+ },
53
+ "grad-fire": {
54
+ fill: "linear-gradient(145deg, #ff512f 0%, #dd2476 45%, #ffb347 100%)",
55
+ glow: "#f96a5f"
56
+ },
57
+ "grad-prism": {
58
+ fill: "linear-gradient(145deg, #12c2e9 0%, #c471ed 45%, #f64f59 100%)",
59
+ glow: "#9e7de8"
60
+ }
61
+ };
62
+
63
+ export function resolveDmxColorTokens(color: string, colorPreset?: DotMatrixColorPreset): {
64
+ resolvedColor: string;
65
+ dotFill: string;
66
+ } {
67
+ if (!colorPreset) {
68
+ return { resolvedColor: color, dotFill: color };
69
+ }
70
+
71
+ const preset = DOT_MATRIX_COLOR_PRESETS[colorPreset];
72
+ if (!preset) {
73
+ return { resolvedColor: color, dotFill: color };
74
+ }
75
+
76
+ return { resolvedColor: preset.glow, dotFill: preset.fill };
77
+ }
78
+
79
+ export interface DotMatrixCommonProps {
80
+ size?: number;
81
+ dotSize?: number;
82
+ color?: string;
83
+ colorPreset?: DotMatrixColorPreset;
84
+ speed?: number;
85
+ ariaLabel?: string;
86
+ className?: string;
87
+ pattern?: MatrixPattern;
88
+ muted?: boolean;
89
+ /**
90
+ * Adds a glow on dots from opacity 0.6 (weakest) through 1 (strongest), after remapping.
91
+ */
92
+ bloom?: boolean;
93
+ /** Uniform glow on every active dot (0…1); slightly wider falloff than selective `bloom`. */
94
+ halo?: number;
95
+ animated?: boolean;
96
+ hoverAnimated?: boolean;
97
+ dotClassName?: string;
98
+ dotShape?: DotShape;
99
+ opacityBase?: number;
100
+ opacityMid?: number;
101
+ opacityPeak?: number;
102
+ cellPadding?: number;
103
+ boxSize?: number;
104
+ minSize?: number;
105
+ }
106
+
107
+ export interface DotAnimationContext {
108
+ index: number;
109
+ row: number;
110
+ col: number;
111
+ distanceFromCenter: number;
112
+ angleFromCenter: number;
113
+ radiusNormalized: number;
114
+ manhattanDistance: number;
115
+ phase: DotMatrixPhase;
116
+ isActive: boolean;
117
+ reducedMotion: boolean;
118
+ }
119
+
120
+ export interface DotAnimationState {
121
+ className?: string;
122
+ style?: CSSProperties;
123
+ }
124
+
125
+ export type DotAnimationResolver = (ctx: DotAnimationContext) => DotAnimationState;
126
+
127
+ export function cx(...values: Array<string | undefined | null | false>): string {
128
+ return values.filter(Boolean).join(" ");
129
+ }
130
+
131
+ export const MATRIX_SIZE = 5;
132
+ const CENTER = Math.floor(MATRIX_SIZE / 2);
133
+ const RANGE = Array.from({ length: MATRIX_SIZE }, (_, index) => index);
134
+ const MAX_RADIUS = Math.hypot(CENTER, CENTER);
135
+
136
+ export const FULL_INDEXES = RANGE.flatMap((row) => RANGE.map((col) => rowMajorIndex(row, col)));
137
+
138
+ export const DIAMOND_INDEXES = FULL_INDEXES.filter((index) => {
139
+ const { row, col } = indexToCoord(index);
140
+ return Math.abs(row - CENTER) + Math.abs(col - CENTER) <= 2;
141
+ });
142
+
143
+ export const OUTLINE_INDEXES = FULL_INDEXES.filter((index) => {
144
+ const { row, col } = indexToCoord(index);
145
+ return row === 0 || row === MATRIX_SIZE - 1 || col === 0 || col === MATRIX_SIZE - 1;
146
+ });
147
+
148
+ export const CROSS_INDEXES = FULL_INDEXES.filter((index) => {
149
+ const { row, col } = indexToCoord(index);
150
+ return row === CENTER || col === CENTER;
151
+ });
152
+
153
+ export const RINGS_INDEXES = FULL_INDEXES.filter((index) => {
154
+ const { row, col } = indexToCoord(index);
155
+ const radius = Math.hypot(row - CENTER, col - CENTER);
156
+ return Math.round(radius) === 1 || Math.round(radius) === 2;
157
+ });
158
+
159
+ export const ROSE_INDEXES = FULL_INDEXES.filter((index) => {
160
+ const { row, col } = indexToCoord(index);
161
+ const dx = col - CENTER;
162
+ const dy = row - CENTER;
163
+ const angle = Math.atan2(dy, dx);
164
+ const radius = Math.hypot(dx, dy);
165
+ const rose = Math.abs(Math.sin(3 * angle));
166
+ return rose > 0.6 && radius >= 1;
167
+ });
168
+
169
+ const PATTERN_INDEXES: Record<MatrixPattern, number[]> = {
170
+ diamond: DIAMOND_INDEXES,
171
+ full: FULL_INDEXES,
172
+ outline: OUTLINE_INDEXES,
173
+ rose: ROSE_INDEXES,
174
+ cross: CROSS_INDEXES,
175
+ rings: RINGS_INDEXES
176
+ };
177
+
178
+ export function getPatternIndexes(pattern: MatrixPattern = "diamond"): number[] {
179
+ return PATTERN_INDEXES[pattern];
180
+ }
181
+
182
+ export function rowMajorIndex(row: number, col: number): number {
183
+ return row * MATRIX_SIZE + col;
184
+ }
185
+
186
+ export function indexToCoord(index: number): { row: number; col: number } {
187
+ return {
188
+ row: Math.floor(index / MATRIX_SIZE),
189
+ col: index % MATRIX_SIZE
190
+ };
191
+ }
192
+
193
+ export function distanceFromCenter(index: number): number {
194
+ const { row, col } = indexToCoord(index);
195
+ return Math.hypot(row - CENTER, col - CENTER);
196
+ }
197
+
198
+ export function rowDistance(index: number): number {
199
+ const { row } = indexToCoord(index);
200
+ return Math.abs(row - CENTER);
201
+ }
202
+
203
+ export function polarAngle(index: number): number {
204
+ const { row, col } = indexToCoord(index);
205
+ return Math.atan2(row - CENTER, col - CENTER);
206
+ }
207
+
208
+ export function normalizedRadius(index: number): number {
209
+ const { row, col } = indexToCoord(index);
210
+ return Math.hypot(row - CENTER, col - CENTER) / MAX_RADIUS;
211
+ }
212
+
213
+ export function manhattanDistance(index: number): number {
214
+ const { row, col } = indexToCoord(index);
215
+ return Math.abs(row - CENTER) + Math.abs(col - CENTER);
216
+ }
217
+
218
+ export function harmonicPhase(row: number, col: number, a: number, b: number): number {
219
+ return Math.sin((row + 1) * a + (col + 1) * b);
220
+ }
221
+
222
+ export function lissajousOffset(
223
+ row: number,
224
+ col: number,
225
+ amplitude = 2.25
226
+ ): { x: number; y: number; phase: number } {
227
+ const x = Math.sin((row + 1) * 1.15 + (col + 1) * 2.2) * amplitude;
228
+ const y = Math.cos((row + 1) * 2.45 + (col + 1) * 0.95) * amplitude;
229
+ const phase = Math.abs(Math.sin((row + 1) * 0.7 + (col + 1) * 1.1));
230
+ return { x, y, phase };
231
+ }
232
+
233
+ export function spiralOffset(
234
+ angle: number,
235
+ radiusNormalizedValue: number,
236
+ amplitude = 2.8
237
+ ): { x: number; y: number; phase: number } {
238
+ const spin = angle + radiusNormalizedValue * Math.PI * 2.1;
239
+ const radius = radiusNormalizedValue * amplitude;
240
+ const x = Math.cos(spin) * radius;
241
+ const y = Math.sin(spin) * radius;
242
+ const phase = Math.abs(Math.sin(spin * 0.5));
243
+ return { x, y, phase };
244
+ }
245
+
246
+ export function isPrime(value: number): boolean {
247
+ if (value <= 1) {
248
+ return false;
249
+ }
250
+ if (value === 2) {
251
+ return true;
252
+ }
253
+ if (value % 2 === 0) {
254
+ return false;
255
+ }
256
+
257
+ const limit = Math.floor(Math.sqrt(value));
258
+ for (let divisor = 3; divisor <= limit; divisor += 2) {
259
+ if (value % divisor === 0) {
260
+ return false;
261
+ }
262
+ }
263
+
264
+ return true;
265
+ }
266
+
267
+ const N = MATRIX_SIZE;
268
+ const C = Math.floor(MATRIX_SIZE / 2);
269
+ const CELLS = N * N;
270
+ const MAX_TRBL = (N - 1) * 2;
271
+
272
+ export function trBlPathNormFromIndex(index: number): number {
273
+ const { row, col } = indexToCoord(index);
274
+ return (row + (N - 1 - col)) / MAX_TRBL;
275
+ }
276
+
277
+ function buildSnakeOrderToIndexMap(): number[] {
278
+ const pathOrder = new Array<number>(CELLS);
279
+ const key = (row: number, col: number) => rowMajorIndex(row, col);
280
+ let t = 0;
281
+ for (let row = 0; row < N; row += 1) {
282
+ if (row % 2 === 0) {
283
+ for (let col = 0; col < N; col += 1) {
284
+ pathOrder[key(row, col)] = t;
285
+ t += 1;
286
+ }
287
+ } else {
288
+ for (let col = N - 1; col >= 0; col -= 1) {
289
+ pathOrder[key(row, col)] = t;
290
+ t += 1;
291
+ }
292
+ }
293
+ }
294
+ return pathOrder;
295
+ }
296
+
297
+ const SNAKE_ORDER: readonly number[] = buildSnakeOrderToIndexMap();
298
+
299
+ export function snakePathNormFromIndex(index: number): number {
300
+ return SNAKE_ORDER[index]! / (CELLS - 1);
301
+ }
302
+
303
+ export function snakePathOrderValue(index: number): number {
304
+ return SNAKE_ORDER[index]!;
305
+ }
306
+
307
+ function buildSpiralInwardOrderToIndexMap(): number[] {
308
+ const order = new Array<number>(CELLS);
309
+ let top = 0;
310
+ let bottom = N - 1;
311
+ let left = 0;
312
+ let right = N - 1;
313
+ let t = 0;
314
+
315
+ while (top <= bottom && left <= right) {
316
+ for (let col = left; col <= right; col += 1) {
317
+ order[rowMajorIndex(top, col)] = t;
318
+ t += 1;
319
+ }
320
+
321
+ for (let row = top + 1; row <= bottom; row += 1) {
322
+ order[rowMajorIndex(row, right)] = t;
323
+ t += 1;
324
+ }
325
+
326
+ if (top < bottom) {
327
+ for (let col = right - 1; col >= left; col -= 1) {
328
+ order[rowMajorIndex(bottom, col)] = t;
329
+ t += 1;
330
+ }
331
+ }
332
+
333
+ if (left < right) {
334
+ for (let row = bottom - 1; row > top; row -= 1) {
335
+ order[rowMajorIndex(row, left)] = t;
336
+ t += 1;
337
+ }
338
+ }
339
+
340
+ top += 1;
341
+ bottom -= 1;
342
+ left += 1;
343
+ right -= 1;
344
+ }
345
+
346
+ return order;
347
+ }
348
+
349
+ const SPIRAL_INWARD_ORDER: readonly number[] = buildSpiralInwardOrderToIndexMap();
350
+
351
+ export function spiralInwardNormFromIndex(index: number): number {
352
+ return SPIRAL_INWARD_ORDER[index]! / (CELLS - 1);
353
+ }
354
+
355
+ export function spiralInwardOrderValue(index: number): number {
356
+ return SPIRAL_INWARD_ORDER[index]!;
357
+ }
358
+
359
+ function buildOuterRingClockwiseOrderToIndexMap(): number[] {
360
+ const order = new Array<number>(CELLS).fill(-1);
361
+ const coords: Array<[number, number]> = [
362
+ [0, 0],
363
+ [0, 1],
364
+ [0, 2],
365
+ [0, 3],
366
+ [0, 4],
367
+ [1, 4],
368
+ [2, 4],
369
+ [3, 4],
370
+ [4, 4],
371
+ [4, 3],
372
+ [4, 2],
373
+ [4, 1],
374
+ [4, 0],
375
+ [3, 0],
376
+ [2, 0],
377
+ [1, 0]
378
+ ];
379
+
380
+ for (let t = 0; t < coords.length; t += 1) {
381
+ const [row, col] = coords[t]!;
382
+ order[rowMajorIndex(row, col)] = t;
383
+ }
384
+
385
+ return order;
386
+ }
387
+
388
+ function buildMiddleRingAntiClockwiseOrderToIndexMap(): number[] {
389
+ const order = new Array<number>(CELLS).fill(-1);
390
+ const coords: Array<[number, number]> = [
391
+ [1, 1],
392
+ [2, 1],
393
+ [3, 1],
394
+ [3, 2],
395
+ [3, 3],
396
+ [2, 3],
397
+ [1, 3],
398
+ [1, 2]
399
+ ];
400
+
401
+ for (let t = 0; t < coords.length; t += 1) {
402
+ const [row, col] = coords[t]!;
403
+ order[rowMajorIndex(row, col)] = t;
404
+ }
405
+
406
+ return order;
407
+ }
408
+
409
+ const OUTER_RING_CLOCKWISE_ORDER: readonly number[] = buildOuterRingClockwiseOrderToIndexMap();
410
+ const MIDDLE_RING_ANTI_CLOCKWISE_ORDER: readonly number[] = buildMiddleRingAntiClockwiseOrderToIndexMap();
411
+
412
+ export function outerRingClockwiseOrderValue(index: number): number {
413
+ return OUTER_RING_CLOCKWISE_ORDER[index]!;
414
+ }
415
+
416
+ export function outerRingClockwiseNormFromIndex(index: number): number {
417
+ const order = outerRingClockwiseOrderValue(index);
418
+ return order >= 0 ? order / 15 : 0;
419
+ }
420
+
421
+ export function middleRingAntiClockwiseOrderValue(index: number): number {
422
+ return MIDDLE_RING_ANTI_CLOCKWISE_ORDER[index]!;
423
+ }
424
+
425
+ export function middleRingAntiClockwiseNormFromIndex(index: number): number {
426
+ const order = middleRingAntiClockwiseOrderValue(index);
427
+ return order >= 0 ? order / 7 : 0;
428
+ }
429
+
430
+ function buildDiagonalSnakeOrderToIndexMap(): number[] {
431
+ const order = new Array<number>(CELLS);
432
+ let t = 0;
433
+
434
+ for (let diagonal = 0; diagonal <= (N - 1) * 2; diagonal += 1) {
435
+ const rowStart = Math.max(0, diagonal - (N - 1));
436
+ const rowEnd = Math.min(N - 1, diagonal);
437
+
438
+ if (diagonal % 2 === 0) {
439
+ for (let row = rowEnd; row >= rowStart; row -= 1) {
440
+ const col = diagonal - row;
441
+ order[rowMajorIndex(row, col)] = t;
442
+ t += 1;
443
+ }
444
+ } else {
445
+ for (let row = rowStart; row <= rowEnd; row += 1) {
446
+ const col = diagonal - row;
447
+ order[rowMajorIndex(row, col)] = t;
448
+ t += 1;
449
+ }
450
+ }
451
+ }
452
+
453
+ return order;
454
+ }
455
+
456
+ const DIAGONAL_SNAKE_ORDER: readonly number[] = buildDiagonalSnakeOrderToIndexMap();
457
+
458
+ export function diagonalSnakeOrderValue(index: number): number {
459
+ return DIAGONAL_SNAKE_ORDER[index]!;
460
+ }
461
+
462
+ export function diagonalSnakeNormFromIndex(index: number): number {
463
+ return DIAGONAL_SNAKE_ORDER[index]! / (CELLS - 1);
464
+ }
465
+
466
+ function buildRowWaveSnakeOrderToIndexMap(): number[] {
467
+ const order = new Array<number>(CELLS);
468
+ const route: Array<{ col: number; dir: "up" | "down" }> = [
469
+ { col: 0, dir: "up" },
470
+ { col: 2, dir: "down" },
471
+ { col: 1, dir: "up" },
472
+ { col: 3, dir: "down" },
473
+ { col: 2, dir: "up" },
474
+ { col: 4, dir: "down" }
475
+ ];
476
+
477
+ let t = 0;
478
+ for (const step of route) {
479
+ if (step.dir === "up") {
480
+ for (let row = N - 1; row >= 0; row -= 1) {
481
+ order[rowMajorIndex(row, step.col)] = t;
482
+ t += 1;
483
+ }
484
+ } else {
485
+ for (let row = 0; row < N; row += 1) {
486
+ order[rowMajorIndex(row, step.col)] = t;
487
+ t += 1;
488
+ }
489
+ }
490
+ }
491
+
492
+ return order;
493
+ }
494
+
495
+ const ROW_WAVE_SNAKE_ORDER: readonly number[] = buildRowWaveSnakeOrderToIndexMap();
496
+ const ROW_WAVE_SNAKE_MAX_ORDER = Math.max(...ROW_WAVE_SNAKE_ORDER);
497
+
498
+ export function rowWaveOrderValue(index: number): number {
499
+ return ROW_WAVE_SNAKE_ORDER[index]!;
500
+ }
501
+
502
+ export function rowWaveNormFromIndex(index: number): number {
503
+ return ROW_WAVE_SNAKE_MAX_ORDER > 0 ? rowWaveOrderValue(index) / ROW_WAVE_SNAKE_MAX_ORDER : 0;
504
+ }
505
+
506
+ export function colWaveNormFromIndex(index: number): number {
507
+ const { col } = indexToCoord(index);
508
+ return N > 1 ? col / (N - 1) : 0;
509
+ }
510
+
511
+ export function concentricRingNormFromIndex(index: number): number {
512
+ const { row, col } = indexToCoord(index);
513
+ return Math.max(Math.abs(row - C), Math.abs(col - C)) / C;
514
+ }
515
+
516
+ const CORNER_COORDS = new Set(["0,0", "0,4", "4,0", "4,4"]);
517
+
518
+ export function isWithinCircularMask(row: number, col: number): boolean {
519
+ return !CORNER_COORDS.has(`${row},${col}`);
520
+ }
521
+
522
+ export function stylePx(n: number): string {
523
+ return `${n}px`;
524
+ }
525
+
526
+ export function styleOpacity(opacity: number): number {
527
+ return Math.round(opacity * 1e6) / 1e6;
528
+ }
529
+
530
+ const SOURCE_BASE_OPACITY = 0.08;
531
+ const SOURCE_MID_OPACITY = 0.34;
532
+ const SOURCE_PEAK_OPACITY = 0.94;
533
+
534
+ function lerpDmx(start: number, end: number, progress: number): number {
535
+ return start + (end - start) * progress;
536
+ }
537
+
538
+ function normalizeProgressDmx(value: number, start: number, end: number): number {
539
+ const span = end - start;
540
+ if (Math.abs(span) < Number.EPSILON) {
541
+ return 0;
542
+ }
543
+ return Math.min(1, Math.max(0, (value - start) / span));
544
+ }
545
+
546
+ function coerceOpacityDmx(value: number | undefined): number | undefined {
547
+ if (value == null || !Number.isFinite(value)) {
548
+ return undefined;
549
+ }
550
+ return Math.min(1, Math.max(0, value));
551
+ }
552
+
553
+ export function remapOpacityToTriplet(
554
+ opacity: number,
555
+ opacityBase: number | undefined,
556
+ opacityMid: number | undefined,
557
+ opacityPeak: number | undefined
558
+ ): number {
559
+ if (!Number.isFinite(opacity)) {
560
+ return opacity;
561
+ }
562
+
563
+ const hasOverrides = opacityBase !== undefined || opacityMid !== undefined || opacityPeak !== undefined;
564
+ const safeOpacity = Math.min(1, Math.max(0, opacity));
565
+ if (!hasOverrides) {
566
+ return safeOpacity;
567
+ }
568
+
569
+ const targetBase = coerceOpacityDmx(opacityBase) ?? SOURCE_BASE_OPACITY;
570
+ const targetMid = coerceOpacityDmx(opacityMid) ?? SOURCE_MID_OPACITY;
571
+ const targetPeak = coerceOpacityDmx(opacityPeak) ?? SOURCE_PEAK_OPACITY;
572
+
573
+ if (safeOpacity <= SOURCE_BASE_OPACITY) {
574
+ const progress = normalizeProgressDmx(safeOpacity, 0, SOURCE_BASE_OPACITY);
575
+ return Math.min(1, Math.max(0, lerpDmx(0, targetBase, progress)));
576
+ }
577
+
578
+ if (safeOpacity <= SOURCE_MID_OPACITY) {
579
+ const progress = normalizeProgressDmx(safeOpacity, SOURCE_BASE_OPACITY, SOURCE_MID_OPACITY);
580
+ return Math.min(1, Math.max(0, lerpDmx(targetBase, targetMid, progress)));
581
+ }
582
+
583
+ if (safeOpacity <= SOURCE_PEAK_OPACITY) {
584
+ const progress = normalizeProgressDmx(safeOpacity, SOURCE_MID_OPACITY, SOURCE_PEAK_OPACITY);
585
+ return Math.min(1, Math.max(0, lerpDmx(targetMid, targetPeak, progress)));
586
+ }
587
+
588
+ const progress = normalizeProgressDmx(safeOpacity, SOURCE_PEAK_OPACITY, 1);
589
+ return Math.min(1, Math.max(0, lerpDmx(targetPeak, 1, progress)));
590
+ }
591
+
592
+ /** Remapped opacity where bloom begins (weakest glow); scales linearly to full bloom at 1. */
593
+ export const DMX_BLOOM_OPACITY_MIN = 0.6;
594
+
595
+ export function opacityToBloomLevel(remappedOpacity: number): number {
596
+ return Math.max(0, Math.min(1, (remappedOpacity - DMX_BLOOM_OPACITY_MIN) / (1 - DMX_BLOOM_OPACITY_MIN)));
597
+ }
598
+
599
+ export function remappedOpacityQualifiesForBloom(remappedOpacity: number): boolean {
600
+ return remappedOpacity >= DMX_BLOOM_OPACITY_MIN;
601
+ }
602
+
603
+ function clampHalo(value: number | undefined): number {
604
+ if (value == null || !Number.isFinite(value)) {
605
+ return 0;
606
+ }
607
+ return Math.min(1, Math.max(0, value));
608
+ }
609
+
610
+ export function dmxBloomRootActive(bloom: boolean, halo: number | undefined): boolean {
611
+ return bloom || clampHalo(halo) > 0;
612
+ }
613
+
614
+ /** Root class when `halo` > 0 — CSS widens drop-shadow falloff for a softer, more diffuse glow. */
615
+ export function dmxBloomHaloSpreadClass(halo: number | undefined): "dmx-bloom-halo" | false {
616
+ return clampHalo(halo) > 0 ? "dmx-bloom-halo" : false;
617
+ }
618
+
619
+ /**
620
+ * Bloom level and dot class for one cell. `curveOpacity` is the loader’s logical opacity **before**
621
+ * `remapOpacityToTriplet` (same as `bloom` uses today).
622
+ */
623
+ export function dmxDotBloomParts(
624
+ isActive: boolean,
625
+ curveOpacity: number,
626
+ bloom: boolean,
627
+ halo: number | undefined,
628
+ ob: number | undefined,
629
+ om: number | undefined,
630
+ op: number | undefined
631
+ ): { level: number; bloomDot: boolean } {
632
+ const haloN = clampHalo(halo);
633
+ if (!isActive) {
634
+ return { level: 0, bloomDot: false };
635
+ }
636
+ const remapped = remapOpacityToTriplet(curveOpacity, ob, om, op);
637
+ const fromBloom = bloom ? opacityToBloomLevel(remapped) : 0;
638
+ return {
639
+ level: fromBloom,
640
+ bloomDot: haloN > 0 || (bloom && remappedOpacityQualifiesForBloom(remapped))
641
+ };
642
+ }
643
+
644
+ function getMatrix5Layout(
645
+ size: number,
646
+ dotSize: number,
647
+ cellPadding?: number
648
+ ): { gap: number; matrixSpan: number } {
649
+ const n = MATRIX_SIZE;
650
+ if (cellPadding != null) {
651
+ const g = Math.max(0, cellPadding);
652
+ const matrixSpan = dotSize * n + g * (n - 1);
653
+ return { gap: g, matrixSpan };
654
+ }
655
+ const g = Math.max(1, Math.floor((size - dotSize * n) / (n - 1)));
656
+ return { gap: g, matrixSpan: size };
657
+ }
658
+
659
+ function resolveDmxBoxOuterDim(
660
+ options: { boxSize?: number; minSize?: number } | null | undefined
661
+ ): { outerDim: number; useWrapper: boolean } {
662
+ const b = options?.boxSize;
663
+ const hasBox = b != null && b > 0 && Number.isFinite(b);
664
+ if (!hasBox) {
665
+ return { outerDim: 0, useWrapper: false };
666
+ }
667
+ const m = options?.minSize;
668
+ if (m != null && m > 0 && Number.isFinite(m)) {
669
+ return { outerDim: Math.max(b, m), useWrapper: true };
670
+ }
671
+ return { outerDim: b, useWrapper: true };
672
+ }
673
+
674
+ function clamp01Dmx(n: number | undefined) {
675
+ if (n == null) {
676
+ return;
677
+ }
678
+ if (!Number.isFinite(n)) {
679
+ return;
680
+ }
681
+ return Math.min(1, Math.max(0, n));
682
+ }
683
+
684
+ interface DotMatrixBaseProps extends DotMatrixCommonProps {
685
+ phase: DotMatrixPhase;
686
+ reducedMotion?: boolean;
687
+ onMouseEnter?: () => void;
688
+ onMouseLeave?: () => void;
689
+ animationResolver?: DotAnimationResolver;
690
+ }
691
+
692
+ export function DotMatrixBase({
693
+ size = 24,
694
+ dotSize = 3,
695
+ color = "currentColor",
696
+ colorPreset,
697
+ speed = 1,
698
+ ariaLabel = "Loading",
699
+ className,
700
+ pattern = "diamond",
701
+ dotShape = "circle",
702
+ muted = false,
703
+ bloom = false,
704
+ halo = 0,
705
+ dotClassName,
706
+ phase,
707
+ reducedMotion = false,
708
+ onMouseEnter,
709
+ onMouseLeave,
710
+ animationResolver,
711
+ opacityBase,
712
+ opacityMid,
713
+ opacityPeak,
714
+ cellPadding,
715
+ boxSize,
716
+ minSize
717
+ }: DotMatrixBaseProps) {
718
+ const patternIndexes = new Set(getPatternIndexes(pattern));
719
+ const safeSpeed = speed > 0 ? speed : 1;
720
+ const speedScale = 1 / safeSpeed;
721
+ const { gap, matrixSpan } = getMatrix5Layout(size, dotSize, cellPadding);
722
+ const { outerDim, useWrapper } = resolveDmxBoxOuterDim({ boxSize, minSize });
723
+ const scale = useWrapper && matrixSpan > 0 ? outerDim / matrixSpan : 1;
724
+ const center = Math.floor(MATRIX_SIZE / 2);
725
+ const ob = clamp01Dmx(opacityBase);
726
+ const om = clamp01Dmx(opacityMid);
727
+ const op = clamp01Dmx(opacityPeak);
728
+ const unit = dotSize + gap;
729
+ const { resolvedColor, dotFill } = resolveDmxColorTokens(color, colorPreset);
730
+
731
+ const dmxVarStyle = {
732
+ width: matrixSpan,
733
+ height: matrixSpan,
734
+ "--dmx-speed": speedScale,
735
+ ["--dmx-dot-size" as const]: `${dotSize}px`,
736
+ ["--dmx-halo-level" as const]: halo,
737
+ ["--dmx-dot-fill" as const]: dotFill,
738
+ color: resolvedColor,
739
+ ...(ob !== undefined && { ["--dmx-opacity-base" as const]: ob }),
740
+ ...(om !== undefined && { ["--dmx-opacity-mid" as const]: om }),
741
+ ...(op !== undefined && { ["--dmx-opacity-peak" as const]: op }),
742
+ ...(useWrapper
743
+ ? {
744
+ transform: `scale(${scale})`,
745
+ transformOrigin: "center center" as const
746
+ }
747
+ : { minWidth: minSize, minHeight: minSize })
748
+ } as unknown as CSSProperties;
749
+
750
+ const dots = Array.from({ length: MATRIX_SIZE * MATRIX_SIZE }).map((_, index) => {
751
+ const { row, col } = indexToCoord(index);
752
+ const isActive = patternIndexes.has(index);
753
+ const distance = distanceFromCenter(index);
754
+ const angle = polarAngle(index);
755
+ const radiusNormalizedValue = normalizedRadius(index);
756
+ const manhattan = manhattanDistance(index);
757
+ const deltaX = (col - center) * unit;
758
+ const deltaY = (row - center) * unit;
759
+
760
+ const animationState = animationResolver
761
+ ? animationResolver({
762
+ index,
763
+ row,
764
+ col,
765
+ distanceFromCenter: distance,
766
+ angleFromCenter: angle,
767
+ radiusNormalized: radiusNormalizedValue,
768
+ manhattanDistance: manhattan,
769
+ phase,
770
+ isActive,
771
+ reducedMotion
772
+ })
773
+ : {};
774
+
775
+ const resolvedAnimationStyle = animationState.style ? { ...animationState.style } : undefined;
776
+ let isBloomDot = false;
777
+ let stylePatch: CSSProperties | undefined = resolvedAnimationStyle;
778
+
779
+ if (isActive) {
780
+ const rawOpacity = stylePatch?.opacity;
781
+ if (stylePatch != null && typeof rawOpacity === "number") {
782
+ const remappedOpacity = remapOpacityToTriplet(rawOpacity, ob, om, op);
783
+ stylePatch = { ...stylePatch, opacity: remappedOpacity };
784
+ const parts = dmxDotBloomParts(true, rawOpacity, bloom, halo, ob, om, op);
785
+ (stylePatch as CSSProperties & { "--dmx-bloom-level"?: number })["--dmx-bloom-level"] = parts.level;
786
+ isBloomDot = parts.bloomDot;
787
+ } else {
788
+ const parts = dmxDotBloomParts(true, 0, bloom, halo, ob, om, op);
789
+ if (parts.level > 0) {
790
+ stylePatch = {
791
+ ...(stylePatch ?? {}),
792
+ ["--dmx-bloom-level" as const]: parts.level
793
+ } as CSSProperties & { "--dmx-bloom-level"?: number };
794
+ }
795
+ isBloomDot = parts.bloomDot;
796
+ }
797
+ }
798
+
799
+ const dotStyle = {
800
+ width: dotSize,
801
+ height: dotSize,
802
+ "--dmx-distance": distance,
803
+ "--dmx-row": row,
804
+ "--dmx-col": col,
805
+ "--dmx-x": `${deltaX}px`,
806
+ "--dmx-y": `${deltaY}px`,
807
+ "--dmx-angle": angle,
808
+ "--dmx-radius": radiusNormalizedValue,
809
+ "--dmx-manhattan": manhattan,
810
+ ...stylePatch,
811
+ ...(!isActive
812
+ ? {
813
+ opacity: 0,
814
+ visibility: "hidden" as const,
815
+ pointerEvents: "none" as const,
816
+ animation: "none"
817
+ }
818
+ : {})
819
+ } as CSSProperties;
820
+
821
+ return (
822
+ <span
823
+ key={index}
824
+ aria-hidden="true"
825
+ className={cx(
826
+ "dmx-dot",
827
+ !isActive && "dmx-inactive",
828
+ isBloomDot && "dmx-bloom-dot",
829
+ dotClassName,
830
+ animationState.className
831
+ )}
832
+ style={dotStyle}
833
+ />
834
+ );
835
+ });
836
+
837
+ const matrix = (
838
+ <div
839
+ className={cx(
840
+ "dmx-root",
841
+ `dmx-dot-shape-${dotShape}`,
842
+ muted && "dmx-muted",
843
+ dmxBloomRootActive(bloom, halo) && "dmx-bloom",
844
+ dmxBloomHaloSpreadClass(halo),
845
+ !useWrapper && className
846
+ )}
847
+ style={dmxVarStyle}
848
+ >
849
+ <div className="dmx-grid" style={{ gap }}>{dots}</div>
850
+ </div>
851
+ );
852
+
853
+ if (useWrapper) {
854
+ return (
855
+ <div
856
+ role="status"
857
+ aria-live="polite"
858
+ aria-label={ariaLabel}
859
+ className={className}
860
+ style={{
861
+ display: "inline-flex",
862
+ alignItems: "center",
863
+ justifyContent: "center",
864
+ width: outerDim,
865
+ height: outerDim,
866
+ minWidth: minSize,
867
+ minHeight: minSize,
868
+ overflow: "hidden"
869
+ }}
870
+ onMouseEnter={onMouseEnter}
871
+ onMouseLeave={onMouseLeave}
872
+ >
873
+ {matrix}
874
+ </div>
875
+ );
876
+ }
877
+
878
+ return (
879
+ <div
880
+ role="status"
881
+ aria-live="polite"
882
+ aria-label={ariaLabel}
883
+ className={cx(
884
+ "dmx-root",
885
+ `dmx-dot-shape-${dotShape}`,
886
+ muted && "dmx-muted",
887
+ dmxBloomRootActive(bloom, halo) && "dmx-bloom",
888
+ dmxBloomHaloSpreadClass(halo),
889
+ className
890
+ )}
891
+ style={dmxVarStyle}
892
+ onMouseEnter={onMouseEnter}
893
+ onMouseLeave={onMouseLeave}
894
+ >
895
+ <div className="dmx-grid" style={{ gap }}>{dots}</div>
896
+ </div>
897
+ );
898
+ }
899
+
900
+ export const MATRIX_SIZE_3 = 3;
901
+
902
+ const CENTER_3 = Math.floor(MATRIX_SIZE_3 / 2);
903
+ const RANGE_3 = Array.from({ length: MATRIX_SIZE_3 }, (_, index) => index);
904
+ const MAX_RADIUS_3 = Math.hypot(CENTER_3, CENTER_3);
905
+
906
+ export const FULL_INDEXES_3 = RANGE_3.flatMap((row) =>
907
+ RANGE_3.map((col) => rowMajorIndex3(row, col))
908
+ );
909
+
910
+ export const OUTLINE_INDEXES_3 = FULL_INDEXES_3.filter((index) => {
911
+ const { row, col } = indexToCoord3(index);
912
+ return row === 0 || row === MATRIX_SIZE_3 - 1 || col === 0 || col === MATRIX_SIZE_3 - 1;
913
+ });
914
+
915
+ export const DIAMOND_INDEXES_3 = FULL_INDEXES_3.filter((index) => {
916
+ const { row, col } = indexToCoord3(index);
917
+ return Math.abs(row - CENTER_3) + Math.abs(col - CENTER_3) <= 1;
918
+ });
919
+
920
+ export const CROSS_INDEXES_3 = FULL_INDEXES_3.filter((index) => {
921
+ const { row, col } = indexToCoord3(index);
922
+ return row === CENTER_3 || col === CENTER_3;
923
+ });
924
+
925
+ export const RINGS_INDEXES_3 = FULL_INDEXES_3.filter((index) => {
926
+ const { row, col } = indexToCoord3(index);
927
+ return Math.round(Math.hypot(row - CENTER_3, col - CENTER_3)) === 1;
928
+ });
929
+
930
+ export const ROSE_INDEXES_3 = FULL_INDEXES_3.filter((index) => {
931
+ const { row, col } = indexToCoord3(index);
932
+ const dx = col - CENTER_3;
933
+ const dy = row - CENTER_3;
934
+ const angle = Math.atan2(dy, dx);
935
+ const radius = Math.hypot(dx, dy);
936
+ const rose = Math.abs(Math.sin(3 * angle));
937
+ return rose > 0.55 && radius >= 0.75;
938
+ });
939
+
940
+ const PATTERN_INDEXES_3: Record<MatrixPattern, number[]> = {
941
+ diamond: DIAMOND_INDEXES_3,
942
+ full: FULL_INDEXES_3,
943
+ outline: OUTLINE_INDEXES_3,
944
+ rose: ROSE_INDEXES_3,
945
+ cross: CROSS_INDEXES_3,
946
+ rings: RINGS_INDEXES_3
947
+ };
948
+
949
+ export function getPattern3Indexes(pattern: MatrixPattern = "full"): number[] {
950
+ return PATTERN_INDEXES_3[pattern];
951
+ }
952
+
953
+ export function rowMajorIndex3(row: number, col: number): number {
954
+ return row * MATRIX_SIZE_3 + col;
955
+ }
956
+
957
+ export function indexToCoord3(index: number): { row: number; col: number } {
958
+ return {
959
+ row: Math.floor(index / MATRIX_SIZE_3),
960
+ col: index % MATRIX_SIZE_3
961
+ };
962
+ }
963
+
964
+ export function distanceFromCenter3(index: number): number {
965
+ const { row, col } = indexToCoord3(index);
966
+ return Math.hypot(row - CENTER_3, col - CENTER_3);
967
+ }
968
+
969
+ export function manhattanDistance3(index: number): number {
970
+ const { row, col } = indexToCoord3(index);
971
+ return Math.abs(row - CENTER_3) + Math.abs(col - CENTER_3);
972
+ }
973
+
974
+ const MAX_DIAGONAL_3 = (MATRIX_SIZE_3 - 1) * 2;
975
+
976
+ export type DiagonalWave3Direction = "tr-bl" | "tl-br" | "br-tl" | "bl-tr";
977
+
978
+ export function trBlPath3NormFromIndex(index: number): number {
979
+ const { row, col } = indexToCoord3(index);
980
+ return (row + (MATRIX_SIZE_3 - 1 - col)) / MAX_DIAGONAL_3;
981
+ }
982
+
983
+ export function tlBrPath3NormFromIndex(index: number): number {
984
+ const { row, col } = indexToCoord3(index);
985
+ return (row + col) / MAX_DIAGONAL_3;
986
+ }
987
+
988
+ export function brTlPath3NormFromIndex(index: number): number {
989
+ const { row, col } = indexToCoord3(index);
990
+ return (MAX_DIAGONAL_3 - row - col) / MAX_DIAGONAL_3;
991
+ }
992
+
993
+ export function blTrPath3NormFromIndex(index: number): number {
994
+ const { row, col } = indexToCoord3(index);
995
+ return (MAX_DIAGONAL_3 - row - (MATRIX_SIZE_3 - 1 - col)) / MAX_DIAGONAL_3;
996
+ }
997
+
998
+ const DIAGONAL_PATH_3: Record<DiagonalWave3Direction, (index: number) => number> = {
999
+ "tr-bl": trBlPath3NormFromIndex,
1000
+ "tl-br": tlBrPath3NormFromIndex,
1001
+ "br-tl": brTlPath3NormFromIndex,
1002
+ "bl-tr": blTrPath3NormFromIndex
1003
+ };
1004
+
1005
+ export function diagonalWave3PathNormFromIndex(
1006
+ index: number,
1007
+ direction: DiagonalWave3Direction
1008
+ ): number {
1009
+ return DIAGONAL_PATH_3[direction](index);
1010
+ }
1011
+
1012
+ export function diagonalWave3BandIndex(
1013
+ row: number,
1014
+ col: number,
1015
+ direction: DiagonalWave3Direction
1016
+ ): number {
1017
+ if (direction === "tr-bl" || direction === "bl-tr") {
1018
+ return row + (MATRIX_SIZE_3 - 1 - col);
1019
+ }
1020
+ return row + col;
1021
+ }
1022
+
1023
+ function buildSpiralInwardOrderToIndexMap3(): number[] {
1024
+ const N = MATRIX_SIZE_3;
1025
+ const CELLS = N * N;
1026
+ const order = new Array<number>(CELLS);
1027
+ let top = 0;
1028
+ let bottom = N - 1;
1029
+ let left = 0;
1030
+ let right = N - 1;
1031
+ let t = 0;
1032
+
1033
+ while (top <= bottom && left <= right) {
1034
+ for (let col = left; col <= right; col += 1) {
1035
+ order[rowMajorIndex3(top, col)] = t;
1036
+ t += 1;
1037
+ }
1038
+
1039
+ for (let row = top + 1; row <= bottom; row += 1) {
1040
+ order[rowMajorIndex3(row, right)] = t;
1041
+ t += 1;
1042
+ }
1043
+
1044
+ if (top < bottom) {
1045
+ for (let col = right - 1; col >= left; col -= 1) {
1046
+ order[rowMajorIndex3(bottom, col)] = t;
1047
+ t += 1;
1048
+ }
1049
+ }
1050
+
1051
+ if (left < right) {
1052
+ for (let row = bottom - 1; row > top; row -= 1) {
1053
+ order[rowMajorIndex3(row, left)] = t;
1054
+ t += 1;
1055
+ }
1056
+ }
1057
+
1058
+ top += 1;
1059
+ bottom -= 1;
1060
+ left += 1;
1061
+ right -= 1;
1062
+ }
1063
+
1064
+ return order;
1065
+ }
1066
+
1067
+ const SPIRAL_INWARD_ORDER_3: readonly number[] = buildSpiralInwardOrderToIndexMap3();
1068
+
1069
+ export function spiralInward3NormFromIndex(index: number): number {
1070
+ return SPIRAL_INWARD_ORDER_3[index]! / (MATRIX_SIZE_3 * MATRIX_SIZE_3 - 1);
1071
+ }
1072
+
1073
+ export function spiralInward3OrderValue(index: number): number {
1074
+ return SPIRAL_INWARD_ORDER_3[index]!;
1075
+ }
1076
+
1077
+ function buildOuterRingClockwiseOrder3(): number[] {
1078
+ const order = new Array<number>(MATRIX_SIZE_3 * MATRIX_SIZE_3).fill(-1);
1079
+ const path: ReadonlyArray<readonly [number, number]> = [
1080
+ [0, 0],
1081
+ [0, 1],
1082
+ [0, 2],
1083
+ [1, 2],
1084
+ [2, 2],
1085
+ [2, 1],
1086
+ [2, 0],
1087
+ [1, 0]
1088
+ ];
1089
+
1090
+ path.forEach(([row, col], step) => {
1091
+ order[rowMajorIndex3(row, col)] = step;
1092
+ });
1093
+
1094
+ return order;
1095
+ }
1096
+
1097
+ const OUTER_RING_CLOCKWISE_ORDER_3: readonly number[] = buildOuterRingClockwiseOrder3();
1098
+
1099
+ export function outerRingClockwise3OrderValue(index: number): number {
1100
+ return OUTER_RING_CLOCKWISE_ORDER_3[index]!;
1101
+ }
1102
+
1103
+ export function outerRingClockwise3NormFromIndex(index: number): number {
1104
+ const order = OUTER_RING_CLOCKWISE_ORDER_3[index]!;
1105
+ if (order < 0) {
1106
+ return 0;
1107
+ }
1108
+ return order / 7;
1109
+ }
1110
+
1111
+ export function isCenterCell3(row: number, col: number): boolean {
1112
+ const center = Math.floor(MATRIX_SIZE_3 / 2);
1113
+ return row === center && col === center;
1114
+ }
1115
+
1116
+ export function rowWave3NormFromRow(row: number): number {
1117
+ return row / (MATRIX_SIZE_3 - 1);
1118
+ }
1119
+
1120
+ export function colWave3NormFromCol(col: number): number {
1121
+ return col / (MATRIX_SIZE_3 - 1);
1122
+ }
1123
+
1124
+ export function colWave3NormFromColReverse(col: number): number {
1125
+ return (MATRIX_SIZE_3 - 1 - col) / (MATRIX_SIZE_3 - 1);
1126
+ }
1127
+
1128
+ export function wave3PathOpacityFromNorm(
1129
+ norm: number,
1130
+ base = 0.06,
1131
+ mid = 0.38,
1132
+ peak = 0.88
1133
+ ): number {
1134
+ const t = Math.min(1, Math.max(0, norm));
1135
+ if (t <= 0.5) {
1136
+ return base + (t / 0.5) * (mid - base);
1137
+ }
1138
+ return mid + ((t - 0.5) / 0.5) * (peak - mid);
1139
+ }
1140
+
1141
+ function getMatrix3Layout(
1142
+ size: number,
1143
+ dotSize: number,
1144
+ cellPadding?: number
1145
+ ): { gap: number; matrixSpan: number } {
1146
+ const n = MATRIX_SIZE_3;
1147
+ if (cellPadding != null) {
1148
+ const g = Math.max(0, cellPadding);
1149
+ const matrixSpan = dotSize * n + g * (n - 1);
1150
+ return { gap: g, matrixSpan };
1151
+ }
1152
+ const g = Math.max(0, Math.floor((size - dotSize * n) / (n - 1)));
1153
+ return { gap: g, matrixSpan: size };
1154
+ }
1155
+
1156
+ interface DotMatrix3BaseProps extends DotMatrixCommonProps {
1157
+ phase: DotMatrixPhase;
1158
+ reducedMotion?: boolean;
1159
+ onMouseEnter?: () => void;
1160
+ onMouseLeave?: () => void;
1161
+ animationResolver?: DotAnimationResolver;
1162
+ }
1163
+
1164
+ export function DotMatrix3Base({
1165
+ size = 24,
1166
+ dotSize = 3,
1167
+ color = "currentColor",
1168
+ colorPreset,
1169
+ speed = 1,
1170
+ ariaLabel = "Loading",
1171
+ className,
1172
+ pattern = "full",
1173
+ dotShape = "circle",
1174
+ muted = false,
1175
+ bloom = false,
1176
+ halo = 0,
1177
+ dotClassName,
1178
+ phase,
1179
+ reducedMotion = false,
1180
+ onMouseEnter,
1181
+ onMouseLeave,
1182
+ animationResolver,
1183
+ opacityBase = 0.06,
1184
+ opacityMid,
1185
+ opacityPeak,
1186
+ cellPadding = 1,
1187
+ boxSize,
1188
+ minSize
1189
+ }: DotMatrix3BaseProps) {
1190
+ const patternIndexes = new Set(getPattern3Indexes(pattern));
1191
+ const safeSpeed = speed > 0 ? speed : 1;
1192
+ const speedScale = 1 / safeSpeed;
1193
+ const { gap, matrixSpan } = getMatrix3Layout(size, dotSize, cellPadding);
1194
+ const { outerDim, useWrapper } = resolveDmxBoxOuterDim({ boxSize, minSize });
1195
+ const scale = useWrapper && matrixSpan > 0 ? outerDim / matrixSpan : 1;
1196
+ const center = CENTER_3;
1197
+ const ob = clamp01Dmx(opacityBase);
1198
+ const om = clamp01Dmx(opacityMid);
1199
+ const op = clamp01Dmx(opacityPeak);
1200
+ const unit = dotSize + gap;
1201
+ const { resolvedColor, dotFill } = resolveDmxColorTokens(color, colorPreset);
1202
+
1203
+ const dmxVarStyle = {
1204
+ width: matrixSpan,
1205
+ height: matrixSpan,
1206
+ "--dmx-speed": speedScale,
1207
+ ["--dmx-dot-size" as const]: `${dotSize}px`,
1208
+ ["--dmx-halo-level" as const]: halo,
1209
+ ["--dmx-dot-fill" as const]: dotFill,
1210
+ color: resolvedColor,
1211
+ ...(ob !== undefined && { ["--dmx-opacity-base" as const]: ob }),
1212
+ ...(om !== undefined && { ["--dmx-opacity-mid" as const]: om }),
1213
+ ...(op !== undefined && { ["--dmx-opacity-peak" as const]: op }),
1214
+ ...(useWrapper
1215
+ ? {
1216
+ transform: `scale(${scale})`,
1217
+ transformOrigin: "center center" as const
1218
+ }
1219
+ : { minWidth: minSize, minHeight: minSize })
1220
+ } as unknown as CSSProperties;
1221
+
1222
+ const gridStyle = {
1223
+ gap,
1224
+ gridTemplateColumns: `repeat(${MATRIX_SIZE_3}, minmax(0, 1fr))`,
1225
+ gridTemplateRows: `repeat(${MATRIX_SIZE_3}, minmax(0, 1fr))`
1226
+ };
1227
+
1228
+ const dots = Array.from({ length: MATRIX_SIZE_3 * MATRIX_SIZE_3 }).map((_, index) => {
1229
+ const { row, col } = indexToCoord3(index);
1230
+ const isActive = patternIndexes.has(index);
1231
+ const distance = distanceFromCenter3(index);
1232
+ const angle = Math.atan2(row - center, col - center);
1233
+ const radiusNormalizedValue = Math.hypot(row - center, col - center) / MAX_RADIUS_3;
1234
+ const manhattan = manhattanDistance3(index);
1235
+ const deltaX = (col - center) * unit;
1236
+ const deltaY = (row - center) * unit;
1237
+
1238
+ const animationState = animationResolver
1239
+ ? animationResolver({
1240
+ index,
1241
+ row,
1242
+ col,
1243
+ distanceFromCenter: distance,
1244
+ angleFromCenter: angle,
1245
+ radiusNormalized: radiusNormalizedValue,
1246
+ manhattanDistance: manhattan,
1247
+ phase,
1248
+ isActive,
1249
+ reducedMotion
1250
+ })
1251
+ : {};
1252
+
1253
+ const resolvedAnimationStyle = animationState.style ? { ...animationState.style } : undefined;
1254
+ let isBloomDot = false;
1255
+ let stylePatch: CSSProperties | undefined = resolvedAnimationStyle;
1256
+
1257
+ if (isActive) {
1258
+ const rawOpacity = stylePatch?.opacity;
1259
+ if (stylePatch != null && typeof rawOpacity === "number") {
1260
+ const remappedOpacity = remapOpacityToTriplet(rawOpacity, ob, om, op);
1261
+ stylePatch = { ...stylePatch, opacity: remappedOpacity };
1262
+ const parts = dmxDotBloomParts(true, rawOpacity, bloom, halo, ob, om, op);
1263
+ (stylePatch as CSSProperties & { "--dmx-bloom-level"?: number })["--dmx-bloom-level"] = parts.level;
1264
+ isBloomDot = parts.bloomDot;
1265
+ } else {
1266
+ const parts = dmxDotBloomParts(true, 0, bloom, halo, ob, om, op);
1267
+ if (parts.level > 0) {
1268
+ stylePatch = {
1269
+ ...(stylePatch ?? {}),
1270
+ ["--dmx-bloom-level" as const]: parts.level
1271
+ } as CSSProperties & { "--dmx-bloom-level"?: number };
1272
+ }
1273
+ isBloomDot = parts.bloomDot;
1274
+ }
1275
+ }
1276
+
1277
+ const dotStyle = {
1278
+ width: dotSize,
1279
+ height: dotSize,
1280
+ "--dmx-distance": distance,
1281
+ "--dmx-row": row,
1282
+ "--dmx-col": col,
1283
+ "--dmx-x": `${deltaX}px`,
1284
+ "--dmx-y": `${deltaY}px`,
1285
+ "--dmx-angle": angle,
1286
+ "--dmx-radius": radiusNormalizedValue,
1287
+ "--dmx-manhattan": manhattan,
1288
+ ...stylePatch,
1289
+ ...(!isActive
1290
+ ? {
1291
+ opacity: 0,
1292
+ visibility: "hidden" as const,
1293
+ pointerEvents: "none" as const,
1294
+ animation: "none"
1295
+ }
1296
+ : {})
1297
+ } as CSSProperties;
1298
+
1299
+ return (
1300
+ <span
1301
+ key={index}
1302
+ aria-hidden="true"
1303
+ className={cx(
1304
+ "dmx-dot",
1305
+ !isActive && "dmx-inactive",
1306
+ isBloomDot && "dmx-bloom-dot",
1307
+ dotClassName,
1308
+ animationState.className
1309
+ )}
1310
+ style={dotStyle}
1311
+ />
1312
+ );
1313
+ });
1314
+
1315
+ const matrix = (
1316
+ <div
1317
+ className={cx(
1318
+ "dmx-root",
1319
+ "dmx-matrix-3",
1320
+ `dmx-dot-shape-${dotShape}`,
1321
+ muted && "dmx-muted",
1322
+ dmxBloomRootActive(bloom, halo) && "dmx-bloom",
1323
+ dmxBloomHaloSpreadClass(halo),
1324
+ !useWrapper && className
1325
+ )}
1326
+ style={dmxVarStyle}
1327
+ >
1328
+ <div className="dmx-grid" style={gridStyle}>{dots}</div>
1329
+ </div>
1330
+ );
1331
+
1332
+ if (useWrapper) {
1333
+ return (
1334
+ <div
1335
+ role="status"
1336
+ aria-live="polite"
1337
+ aria-label={ariaLabel}
1338
+ className={className}
1339
+ style={{
1340
+ display: "inline-flex",
1341
+ alignItems: "center",
1342
+ justifyContent: "center",
1343
+ width: outerDim,
1344
+ height: outerDim,
1345
+ minWidth: minSize,
1346
+ minHeight: minSize,
1347
+ overflow: "hidden"
1348
+ }}
1349
+ onMouseEnter={onMouseEnter}
1350
+ onMouseLeave={onMouseLeave}
1351
+ >
1352
+ {matrix}
1353
+ </div>
1354
+ );
1355
+ }
1356
+
1357
+ return (
1358
+ <div
1359
+ role="status"
1360
+ aria-live="polite"
1361
+ aria-label={ariaLabel}
1362
+ className={cx(
1363
+ "dmx-root",
1364
+ "dmx-matrix-3",
1365
+ `dmx-dot-shape-${dotShape}`,
1366
+ muted && "dmx-muted",
1367
+ dmxBloomRootActive(bloom, halo) && "dmx-bloom",
1368
+ dmxBloomHaloSpreadClass(halo),
1369
+ className
1370
+ )}
1371
+ style={dmxVarStyle}
1372
+ onMouseEnter={onMouseEnter}
1373
+ onMouseLeave={onMouseLeave}
1374
+ >
1375
+ <div className="dmx-grid" style={gridStyle}>{dots}</div>
1376
+ </div>
1377
+ );
1378
+ }
1379
+
1380
+ type NormFn = (ctx: Pick<DotAnimationContext, "row" | "col" | "index">) => number;
1381
+
1382
+ export function createPathWaveResolver(getPathNorm: NormFn): DotAnimationResolver {
1383
+ return ({ isActive, row, col, index, reducedMotion, phase }) => {
1384
+ if (!isActive) {
1385
+ return { className: "dmx-inactive" };
1386
+ }
1387
+
1388
+ const path = getPathNorm({ row, col, index });
1389
+ const style = { "--dmx-path": path } as CSSProperties;
1390
+
1391
+ if (reducedMotion || phase === "idle") {
1392
+ return {
1393
+ style: {
1394
+ ...style,
1395
+ opacity: 0.12 + path * 0.72
1396
+ }
1397
+ };
1398
+ }
1399
+
1400
+ return { className: "dmx-path", style };
1401
+ };
1402
+ }
1403
+
1404
+ type PathWaveComponentProps = DotMatrixCommonProps;
1405
+
1406
+ export function createPathWaveComponent(displayName: string, getPathNorm: NormFn) {
1407
+ const resolve = createPathWaveResolver(getPathNorm);
1408
+
1409
+ function PathWaveComponent({
1410
+ pattern = "full",
1411
+ animated = true,
1412
+ hoverAnimated = false,
1413
+ speed = 1,
1414
+ ...rest
1415
+ }: PathWaveComponentProps) {
1416
+ const reducedMotion = usePrefersReducedMotion();
1417
+ const { phase: matrixPhase, onMouseEnter, onMouseLeave } = useDotMatrixPhases({
1418
+ animated: Boolean(animated && !reducedMotion),
1419
+ hoverAnimated: Boolean(hoverAnimated && !reducedMotion),
1420
+ speed
1421
+ });
1422
+ return (
1423
+ <DotMatrixBase
1424
+ {...rest}
1425
+ speed={speed}
1426
+ pattern={pattern}
1427
+ animated={animated}
1428
+ phase={matrixPhase}
1429
+ reducedMotion={reducedMotion}
1430
+ onMouseEnter={onMouseEnter}
1431
+ onMouseLeave={onMouseLeave}
1432
+ animationResolver={resolve}
1433
+ />
1434
+ );
1435
+ }
1436
+
1437
+ PathWaveComponent.displayName = displayName;
1438
+ return PathWaveComponent;
1439
+ }
1440
+
1441
+ export function createDiagonalWave3Resolver(direction: DiagonalWave3Direction): DotAnimationResolver {
1442
+ return ({ isActive, index, reducedMotion, phase }) => {
1443
+ if (!isActive) {
1444
+ return { className: "dmx-inactive" };
1445
+ }
1446
+
1447
+ const path = diagonalWave3PathNormFromIndex(index, direction);
1448
+ const style = { "--dmx-path": path } as CSSProperties;
1449
+
1450
+ if (reducedMotion || phase === "idle") {
1451
+ return {
1452
+ style: {
1453
+ ...style,
1454
+ opacity: path * 0.88
1455
+ }
1456
+ };
1457
+ }
1458
+
1459
+ return { className: "dmx-path-3", style };
1460
+ };
1461
+ }
1462
+
1463
+ type DiagonalWave3ComponentProps = DotMatrixCommonProps;
1464
+
1465
+ export function createDiagonalWave3Component(
1466
+ displayName: string,
1467
+ direction: DiagonalWave3Direction
1468
+ ) {
1469
+ const resolve = createDiagonalWave3Resolver(direction);
1470
+
1471
+ function DiagonalWave3Component({
1472
+ pattern = "full",
1473
+ animated = true,
1474
+ hoverAnimated = false,
1475
+ speed = 1.15,
1476
+ ...rest
1477
+ }: DiagonalWave3ComponentProps) {
1478
+ const reducedMotion = usePrefersReducedMotion();
1479
+ const { phase: matrixPhase, onMouseEnter, onMouseLeave } = useDotMatrixPhases({
1480
+ animated: Boolean(animated && !reducedMotion),
1481
+ hoverAnimated: Boolean(hoverAnimated && !reducedMotion),
1482
+ speed
1483
+ });
1484
+
1485
+ return (
1486
+ <DotMatrix3Base
1487
+ {...rest}
1488
+ speed={speed}
1489
+ pattern={pattern}
1490
+ animated={animated}
1491
+ phase={matrixPhase}
1492
+ onMouseEnter={onMouseEnter}
1493
+ onMouseLeave={onMouseLeave}
1494
+ reducedMotion={reducedMotion}
1495
+ animationResolver={resolve}
1496
+ />
1497
+ );
1498
+ }
1499
+
1500
+ DiagonalWave3Component.displayName = displayName;
1501
+ return DiagonalWave3Component;
1502
+ }
1503
+
1504
+ type Dotm3x3ComponentProps = DotMatrixCommonProps;
1505
+
1506
+ export function createDotm3x3Component(
1507
+ displayName: string,
1508
+ animationResolver: DotAnimationResolver,
1509
+ defaultSpeed = 1.15
1510
+ ) {
1511
+ function Dotm3x3Component({
1512
+ pattern = "full",
1513
+ dotShape = "circle",
1514
+ animated = true,
1515
+ hoverAnimated = false,
1516
+ speed = defaultSpeed,
1517
+ ...rest
1518
+ }: Dotm3x3ComponentProps) {
1519
+ const reducedMotion = usePrefersReducedMotion();
1520
+ const { phase: matrixPhase, onMouseEnter, onMouseLeave } = useDotMatrixPhases({
1521
+ animated: Boolean(animated && !reducedMotion),
1522
+ hoverAnimated: Boolean(hoverAnimated && !reducedMotion),
1523
+ speed
1524
+ });
1525
+
1526
+ return (
1527
+ <DotMatrix3Base
1528
+ {...rest}
1529
+ speed={speed}
1530
+ pattern={pattern}
1531
+ dotShape={dotShape}
1532
+ animated={animated}
1533
+ phase={matrixPhase}
1534
+ onMouseEnter={onMouseEnter}
1535
+ onMouseLeave={onMouseLeave}
1536
+ reducedMotion={reducedMotion}
1537
+ animationResolver={animationResolver}
1538
+ />
1539
+ );
1540
+ }
1541
+
1542
+ Dotm3x3Component.displayName = displayName;
1543
+ return Dotm3x3Component;
1544
+ }
1545
+
1546
+ const GLYPH_SPIN_BASE_OPACITY = 0.09;
1547
+ const GLYPH_SPIN_PEAK_OPACITY = 0.88;
1548
+ const GLYPH_SPIN_STEP_MS = 180;
1549
+ const GLYPH_SPIN_ROTATION_STEPS = 4;
1550
+ const GLYPH_SPIN_CYCLE_MS_BASE = GLYPH_SPIN_STEP_MS * GLYPH_SPIN_ROTATION_STEPS;
1551
+
1552
+ function glyphSpinSmoothstep(value: number): number {
1553
+ const t = Math.min(1, Math.max(0, value));
1554
+ return t * t * (3 - 2 * t);
1555
+ }
1556
+
1557
+ export function rotate3x3(pattern: readonly number[], turns: number): readonly number[] {
1558
+ const t = ((turns % GLYPH_SPIN_ROTATION_STEPS) + GLYPH_SPIN_ROTATION_STEPS) % GLYPH_SPIN_ROTATION_STEPS;
1559
+ if (t === 0) {
1560
+ return pattern;
1561
+ }
1562
+
1563
+ let out = [...pattern];
1564
+ for (let k = 0; k < t; k += 1) {
1565
+ const next = new Array<number>(9).fill(0);
1566
+ for (let i = 0; i < 9; i += 1) {
1567
+ const r = Math.floor(i / 3);
1568
+ const c = i % 3;
1569
+ const nr = c;
1570
+ const nc = 2 - r;
1571
+ next[nr * 3 + nc] = out[i]!;
1572
+ }
1573
+ out = next;
1574
+ }
1575
+ return out;
1576
+ }
1577
+
1578
+ function glyphSpinOpacity(current: readonly number[], next: readonly number[], index: number, t: number): number {
1579
+ const weight = (current[index] ?? 0) * (1 - t) + (next[index] ?? 0) * t;
1580
+ return GLYPH_SPIN_BASE_OPACITY + weight * (GLYPH_SPIN_PEAK_OPACITY - GLYPH_SPIN_BASE_OPACITY);
1581
+ }
1582
+
1583
+ type GlyphSpin3ComponentProps = DotMatrixCommonProps;
1584
+
1585
+ export function createGlyphSpin3Component(
1586
+ displayName: string,
1587
+ glyph: readonly number[],
1588
+ defaultSpeed = 1
1589
+ ) {
1590
+ function GlyphSpin3Component({
1591
+ speed = defaultSpeed,
1592
+ pattern = "full",
1593
+ dotShape = "circle",
1594
+ animated = true,
1595
+ hoverAnimated = false,
1596
+ ...rest
1597
+ }: GlyphSpin3ComponentProps) {
1598
+ const reducedMotion = usePrefersReducedMotion();
1599
+ const { phase: matrixPhase, onMouseEnter, onMouseLeave } = useDotMatrixPhases({
1600
+ animated: Boolean(animated && !reducedMotion),
1601
+ hoverAnimated: Boolean(hoverAnimated && !reducedMotion),
1602
+ speed
1603
+ });
1604
+ const cyclePhase = useCyclePhase({
1605
+ active: !reducedMotion && matrixPhase !== "idle",
1606
+ cycleMsBase: GLYPH_SPIN_CYCLE_MS_BASE,
1607
+ speed
1608
+ });
1609
+
1610
+ const animationResolver = useMemo<DotAnimationResolver>(() => {
1611
+ const scaledPhase = cyclePhase * GLYPH_SPIN_ROTATION_STEPS;
1612
+ const turns = Math.floor(scaledPhase) % GLYPH_SPIN_ROTATION_STEPS;
1613
+ const segmentT = glyphSpinSmoothstep(scaledPhase - Math.floor(scaledPhase));
1614
+ const current = rotate3x3(glyph, turns);
1615
+ const next = rotate3x3(glyph, turns + 1);
1616
+
1617
+ return ({ isActive, index, reducedMotion: rm, phase }) => {
1618
+ if (!isActive) {
1619
+ return { className: "dmx-inactive" };
1620
+ }
1621
+
1622
+ if (rm || phase === "idle") {
1623
+ return { style: { opacity: glyphSpinOpacity(glyph, glyph, index, 0) } };
1624
+ }
1625
+
1626
+ return { style: { opacity: glyphSpinOpacity(current, next, index, segmentT) } };
1627
+ };
1628
+ }, [cyclePhase]);
1629
+
1630
+ return (
1631
+ <DotMatrix3Base
1632
+ {...rest}
1633
+ speed={speed}
1634
+ pattern={pattern}
1635
+ dotShape={dotShape}
1636
+ animated={animated}
1637
+ phase={matrixPhase}
1638
+ onMouseEnter={onMouseEnter}
1639
+ onMouseLeave={onMouseLeave}
1640
+ reducedMotion={reducedMotion}
1641
+ animationResolver={animationResolver}
1642
+ />
1643
+ );
1644
+ }
1645
+
1646
+ GlyphSpin3Component.displayName = displayName;
1647
+ return GlyphSpin3Component;
1648
+ }
1649
+