@arraypress/waveform-sounds 0.3.1 → 2.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 (89) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +43 -3
  3. package/dist/waveform-sounds-no-autoinit.esm.js +607 -178
  4. package/dist/waveform-sounds-render.esm.js +79 -15
  5. package/dist/waveform-sounds.css +136 -79
  6. package/dist/waveform-sounds.esm.js +611 -181
  7. package/dist/waveform-sounds.js +608 -181
  8. package/dist/waveform-sounds.min.css +1 -1
  9. package/dist/waveform-sounds.min.js +3 -3
  10. package/package.json +36 -33
  11. package/src/css/waveform-sounds.css +136 -79
  12. package/src/js/core/WaveformSounds.ts +1366 -0
  13. package/src/js/core/element.ts +208 -0
  14. package/src/js/core/engine.ts +107 -0
  15. package/src/js/core/{options.js → options.ts} +28 -28
  16. package/src/js/data/{bpm.js → bpm.ts} +27 -17
  17. package/src/js/data/{navigation.js → navigation.ts} +31 -18
  18. package/src/js/data/{sounds.js → sounds.ts} +97 -66
  19. package/src/js/data/url-state.ts +130 -0
  20. package/src/js/dom/colors.ts +86 -0
  21. package/src/js/dom/{draw.js → draw.ts} +16 -17
  22. package/src/js/dom/{menus.js → menus.ts} +70 -55
  23. package/src/js/dom/{rows.js → rows.ts} +15 -17
  24. package/src/js/entry.ts +60 -0
  25. package/src/js/{index.js → index.ts} +7 -3
  26. package/src/js/render/{html.js → html.ts} +16 -12
  27. package/src/js/render/{icons.js → icons.ts} +3 -4
  28. package/src/js/render/{markup.js → markup.ts} +114 -64
  29. package/src/js/render/options.ts +118 -0
  30. package/src/js/render/{strings.js → strings.ts} +18 -16
  31. package/src/js/{render-entry.js → render-entry.ts} +2 -1
  32. package/src/js/shared/{utils.js → utils.ts} +24 -24
  33. package/{index.d.ts → src/js/types.ts} +40 -88
  34. package/types/core/WaveformSounds.d.ts +175 -0
  35. package/types/core/WaveformSounds.d.ts.map +1 -0
  36. package/types/core/element.d.ts +84 -0
  37. package/types/core/element.d.ts.map +1 -0
  38. package/types/core/engine.d.ts +72 -0
  39. package/types/core/engine.d.ts.map +1 -0
  40. package/types/core/options.d.ts +71 -0
  41. package/types/core/options.d.ts.map +1 -0
  42. package/types/data/bpm.d.ts +80 -0
  43. package/types/data/bpm.d.ts.map +1 -0
  44. package/types/data/navigation.d.ts +62 -0
  45. package/types/data/navigation.d.ts.map +1 -0
  46. package/types/data/sounds.d.ts +168 -0
  47. package/types/data/sounds.d.ts.map +1 -0
  48. package/types/data/url-state.d.ts +109 -0
  49. package/types/data/url-state.d.ts.map +1 -0
  50. package/types/dom/colors.d.ts +48 -0
  51. package/types/dom/colors.d.ts.map +1 -0
  52. package/types/dom/draw.d.ts +72 -0
  53. package/types/dom/draw.d.ts.map +1 -0
  54. package/types/dom/menus.d.ts +75 -0
  55. package/types/dom/menus.d.ts.map +1 -0
  56. package/types/dom/rows.d.ts +39 -0
  57. package/types/dom/rows.d.ts.map +1 -0
  58. package/types/entry.d.ts +28 -0
  59. package/types/entry.d.ts.map +1 -0
  60. package/types/index.d.ts +16 -0
  61. package/types/index.d.ts.map +1 -0
  62. package/types/render/html.d.ts +37 -0
  63. package/types/render/html.d.ts.map +1 -0
  64. package/types/render/icons.d.ts +17 -0
  65. package/types/render/icons.d.ts.map +1 -0
  66. package/types/render/markup.d.ts +141 -0
  67. package/types/render/markup.d.ts.map +1 -0
  68. package/types/render/options.d.ts +69 -0
  69. package/types/render/options.d.ts.map +1 -0
  70. package/types/render/strings.d.ts +43 -0
  71. package/types/render/strings.d.ts.map +1 -0
  72. package/types/render-entry.d.ts +8 -0
  73. package/types/render-entry.d.ts.map +1 -0
  74. package/types/shared/utils.d.ts +57 -0
  75. package/types/shared/utils.d.ts.map +1 -0
  76. package/types/types.d.ts +280 -0
  77. package/types/types.d.ts.map +1 -0
  78. package/types/vendor/arraypress-text.d.ts +250 -0
  79. package/dist/waveform-sounds-no-autoinit.cjs +0 -2159
  80. package/dist/waveform-sounds-render.cjs +0 -614
  81. package/dist/waveform-sounds.cjs +0 -2181
  82. package/no-autoinit.d.ts +0 -2
  83. package/render.d.ts +0 -5
  84. package/src/js/core/WaveformSounds.js +0 -993
  85. package/src/js/core/engine.js +0 -57
  86. package/src/js/data/url-state.js +0 -106
  87. package/src/js/dom/colors.js +0 -59
  88. package/src/js/entry.js +0 -25
  89. package/src/js/render/options.js +0 -90
@@ -1,4 +1,5 @@
1
1
  import {fold, matchesAll, words} from '@arraypress/text';
2
+ import type {Sound, SoundInput, SoundsFilter, SoundsManifest, SoundsSort} from '../types.js';
2
3
 
3
4
  /**
4
5
  * Pure data helpers: no DOM, no window. Shared by the browser runtime and
@@ -15,10 +16,10 @@ import {fold, matchesAll, words} from '@arraypress/text';
15
16
  * sound: 300 sounds is ~30 KB in a manifest or in row attributes, against
16
17
  * ~3x that as a JSON number array.
17
18
  *
18
- * @param {number[]} peaks - Values 0..1.
19
- * @returns {string} Hex string.
19
+ * @param peaks - Values 0..1.
20
+ * @returns Hex string.
20
21
  */
21
- export function encodePeaks(peaks) {
22
+ export function encodePeaks(peaks: number[]): string {
22
23
  if (!Array.isArray(peaks)) return '';
23
24
  let out = '';
24
25
  for (const p of peaks) {
@@ -28,23 +29,48 @@ export function encodePeaks(peaks) {
28
29
  return out;
29
30
  }
30
31
 
32
+ /** The player's compact peaks format: `"wp1:"` + base64url (no padding). */
33
+ const COMPACT_PREFIX = 'wp1:';
34
+
35
+ /**
36
+ * The body of a `wp1:` string to 0..1 peaks (as the core decodes it).
37
+ *
38
+ * @param body - base64url, after the prefix.
39
+ * @returns Peaks, or null when malformed or empty.
40
+ */
41
+ function decodeCompact(body: string): number[] | null {
42
+ // A length of 4n+1 can't come from whole bytes.
43
+ if (!body || !/^[\w-]+$/.test(body) || body.length % 4 === 1) return null;
44
+ try {
45
+ const bytes = atob(body.replace(/-/g, '+').replace(/_/g, '/'));
46
+ const out = new Array(bytes.length);
47
+ for (let i = 0; i < bytes.length; i++) out[i] = bytes.charCodeAt(i) / 255;
48
+ return out;
49
+ } catch {
50
+ return null;
51
+ }
52
+ }
53
+
31
54
  /**
32
55
  * Decode peaks from any accepted form into numbers 0..1.
33
56
  *
34
- * Accepts the hex string from {@link encodePeaks}, an array of 0..1
35
- * numbers, or an array of integers on a larger scale (e.g. 0..100 or
36
- * 0..255) together with that `scale`.
57
+ * Accepts the hex string from {@link encodePeaks}, the player's compact
58
+ * `wp1:` string (`"wp1:"` + base64url of one byte per peak, what the 2.0
59
+ * core and waveform-gen write), an array of 0..1 numbers, or an array of
60
+ * integers on a larger scale (e.g. 0..100 or 0..255) together with that
61
+ * `scale`. Server markup still writes hex.
37
62
  *
38
- * @param {string|number[]|null|undefined} value
39
- * @param {number} [scale=1] - The maximum of an integer array.
40
- * @returns {number[]|null} Peaks, or null when there are none.
63
+ * @param value
64
+ * @param scale - The maximum of an integer array.
65
+ * @returns Peaks, or null when there are none.
41
66
  */
42
- export function decodePeaks(value, scale = 1) {
67
+ export function decodePeaks(value: string | number[] | null | undefined, scale: number = 1): number[] | null {
43
68
  if (value == null || value === '') return null;
44
69
  if (typeof value === 'string') {
70
+ if (value.startsWith(COMPACT_PREFIX)) return decodeCompact(value.slice(COMPACT_PREFIX.length));
45
71
  if (!/^[0-9a-f]+$/i.test(value) || value.length % 2) return null;
46
72
  const out = new Array(value.length / 2);
47
- for (let i = 0; i < out.length; i++) out[i] = parseInt(value.substr(i * 2, 2), 16) / 255;
73
+ for (let i = 0; i < out.length; i++) out[i] = parseInt(value.slice(i * 2, i * 2 + 2), 16) / 255;
48
74
  return out;
49
75
  }
50
76
  if (!Array.isArray(value)) return null;
@@ -59,10 +85,10 @@ export function decodePeaks(value, scale = 1) {
59
85
  * "C# Major", "C♯" → "C#". Anything unparseable comes back trimmed, as
60
86
  * given, so an unusual label still displays.
61
87
  *
62
- * @param {string|null|undefined} key
63
- * @returns {string} Canonical key, or '' for none.
88
+ * @param key
89
+ * @returns Canonical key, or '' for none.
64
90
  */
65
- export function normalizeKey(key) {
91
+ export function normalizeKey(key: string | null | undefined): string {
66
92
  if (key == null) return '';
67
93
  const raw = String(key).trim();
68
94
  const m = raw.match(/^([A-Ga-g])[\s_-]*([#♯b♭]?)[\s_-]*(m|min|minor|maj|major)?$/i);
@@ -74,10 +100,10 @@ export function normalizeKey(key) {
74
100
  }
75
101
 
76
102
  /** Pitch class of each root, for sorting keys: C, C#, D … B, majors before minors. */
77
- const KEY_PITCH = {C: 0, 'C#': 1, Db: 1, D: 2, 'D#': 3, Eb: 3, E: 4, F: 5, 'F#': 6, Gb: 6, G: 7, 'G#': 8, Ab: 8, A: 9, 'A#': 10, Bb: 10, B: 11};
103
+ const KEY_PITCH: Record<string, number> = {C: 0, 'C#': 1, Db: 1, D: 2, 'D#': 3, Eb: 3, E: 4, F: 5, 'F#': 6, Gb: 6, G: 7, 'G#': 8, Ab: 8, A: 9, 'A#': 10, Bb: 10, B: 11};
78
104
 
79
105
  /** Sort rank of a canonical key; unknown keys sort last. */
80
- function keyRank(key) {
106
+ function keyRank(key: string): number {
81
107
  if (!key) return Infinity;
82
108
  const minor = key.endsWith('m');
83
109
  const root = minor ? key.slice(0, -1) : key;
@@ -92,12 +118,12 @@ function keyRank(key) {
92
118
  * A one-shot (a kick, a hat) is often shorter than a second, and m:ss would
93
119
  * round it to "0:00", which reads as a missing length.
94
120
  *
95
- * @param {number|null|undefined} seconds
96
- * @returns {string} e.g. "0:08", "0.4s", or '' when unknown.
121
+ * @param seconds
122
+ * @returns e.g. "0:08", "0.4s", or '' when unknown.
97
123
  */
98
- export function formatDuration(seconds) {
124
+ export function formatDuration(seconds: number | null | undefined): string {
99
125
  // Number(null) is 0: an unknown length must not render as "0:00".
100
- if (seconds == null || seconds === '') return '';
126
+ if (seconds == null || (seconds as unknown) === '') return '';
101
127
  const s = Number(seconds);
102
128
  if (!Number.isFinite(s) || s < 0) return '';
103
129
  // Anything that would round to "1.0s" is shown as "0:01" instead.
@@ -108,18 +134,31 @@ export function formatDuration(seconds) {
108
134
  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
109
135
  }
110
136
 
137
+ /**
138
+ * A playback position as a clock: whole seconds, rounded down like a
139
+ * player's ("0:12", "1:05:09" past an hour).
140
+ *
141
+ * @param seconds
142
+ * @returns e.g. "0:12"; "0:00" for anything unusable.
143
+ */
144
+ export function formatClock(seconds: number): string {
145
+ const total = Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds) : 0;
146
+ const h = Math.floor(total / 3600), m = Math.floor((total % 3600) / 60), sec = String(total % 60).padStart(2, '0');
147
+ return h ? `${h}:${String(m).padStart(2, '0')}:${sec}` : `${m}:${sec}`;
148
+ }
149
+
111
150
  /**
112
151
  * Parse a duration given as seconds (8.02) or as "m:ss" / "h:mm:ss".
113
- * @param {number|string|null|undefined} value
114
- * @returns {number|null}
152
+ * @param value
115
153
  */
116
- export function parseDuration(value) {
154
+ export function parseDuration(value: number | string | null | undefined): number | null {
117
155
  if (value == null || value === '') return null;
118
156
  if (typeof value === 'number') return Number.isFinite(value) && value >= 0 ? value : null;
119
157
  const str = String(value).trim();
120
158
  if (/^\d+(\.\d+)?$/.test(str)) return Number(str);
159
+ // Each part a plain non-negative number: "1:-30" is not a length.
160
+ if (!/^\d+(\.\d+)?(:\d+(\.\d+)?)+$/.test(str)) return null;
121
161
  const parts = str.split(':').map(Number);
122
- if (parts.length < 2 || parts.some((n) => !Number.isFinite(n))) return null;
123
162
  return parts.reduce((acc, n) => acc * 60 + n, 0);
124
163
  }
125
164
 
@@ -127,10 +166,9 @@ export function parseDuration(value) {
127
166
  * The title a file name implies: extension and separators dropped,
128
167
  * leading pack prefixes kept (they are often the label's code).
129
168
  * "NW_Bass_Loop_04_128_Fmin.wav" → "NW Bass Loop 04 128 Fmin".
130
- * @param {string} url
131
- * @returns {string}
169
+ * @param url
132
170
  */
133
- export function titleFromUrl(url) {
171
+ export function titleFromUrl(url: string): string {
134
172
  const file = String(url || '').split(/[?#]/)[0].split('/').pop() || '';
135
173
  let name = file.replace(/\.[a-z0-9]+$/i, '');
136
174
  try { name = decodeURIComponent(name); } catch { /* keep as is */ }
@@ -140,14 +178,14 @@ export function titleFromUrl(url) {
140
178
  /**
141
179
  * Normalise one sound into the shape the runtime and renderer use.
142
180
  *
143
- * @param {Object} input - A sound: `{url, title?, type?, bpm?, key?,
181
+ * @param input - A sound: `{url, title?, type?, bpm?, key?,
144
182
  * duration?, tags?, peaks?, waveform?, download?, loop?, id?}`.
145
- * @param {number} index - Its position (used for a fallback id).
146
- * @param {number} [peakScale=1] - Scale of an integer `peaks` array.
147
- * @returns {import('../../../index').Sound|null} The sound, or null if it has
183
+ * @param index - Its position (used for a fallback id).
184
+ * @param peakScale - Scale of an integer `peaks` array.
185
+ * @returns The sound, or null if it has
148
186
  * no url.
149
187
  */
150
- export function normalizeSound(input, index, peakScale = 1) {
188
+ export function normalizeSound(input: Record<string, any>, index: number, peakScale: number = 1): Sound | null {
151
189
  if (!input || typeof input !== 'object' || !input.url) return null;
152
190
  const bpm = Number(input.bpm);
153
191
  const tags = Array.isArray(input.tags)
@@ -181,10 +219,9 @@ export const LOOP_FILTERS = ['loop', 'one-shot'];
181
219
  * Is this a loop? Only an explicit yes counts: `true`, or `"true"` / `"1"`
182
220
  * as an attribute or a CSV-ish manifest writes it. Unset is a one-shot.
183
221
  *
184
- * @param {unknown} value
185
- * @returns {boolean}
222
+ * @param value
186
223
  */
187
- export function isLoop(value) {
224
+ export function isLoop(value: unknown): boolean {
188
225
  return value === true || value === 1 || value === 'true' || value === '1';
189
226
  }
190
227
 
@@ -193,10 +230,9 @@ export function isLoop(value) {
193
230
  * (what `waveform-gen --manifest` writes) or a bare array of sounds.
194
231
  * Sounds without a url are dropped.
195
232
  *
196
- * @param {Object|Array} manifest
197
- * @returns {import('../../../index').Sound[]}
233
+ * @param manifest
198
234
  */
199
- export function parseManifest(manifest) {
235
+ export function parseManifest(manifest: SoundsManifest | SoundInput[]): Sound[] {
200
236
  const list = Array.isArray(manifest) ? manifest : Array.isArray(manifest?.sounds) ? manifest.sounds : [];
201
237
  const scale = Array.isArray(manifest) ? 1 : Number(manifest?.peakScale) || 1;
202
238
  return normalizeSounds(list, scale);
@@ -205,13 +241,12 @@ export function parseManifest(manifest) {
205
241
  /**
206
242
  * Normalise a list of sounds, dropping invalid ones and de-duplicating ids
207
243
  * (a repeated id would make two rows answer to one play() call).
208
- * @param {Array} list
209
- * @param {number} [peakScale=1]
210
- * @returns {import('../../../index').Sound[]}
244
+ * @param list
245
+ * @param peakScale
211
246
  */
212
- export function normalizeSounds(list, peakScale = 1) {
213
- const seen = new Set();
214
- const out = [];
247
+ export function normalizeSounds(list: SoundInput[], peakScale: number = 1): Sound[] {
248
+ const seen = new Set<string>();
249
+ const out: Sound[] = [];
215
250
  (Array.isArray(list) ? list : []).forEach((item, i) => {
216
251
  const s = normalizeSound(item, i, peakScale);
217
252
  if (!s) return;
@@ -230,12 +265,11 @@ export function normalizeSounds(list, peakScale = 1) {
230
265
  * range, and how many are loops and one-shots. A control with nothing to
231
266
  * offer is not rendered.
232
267
  *
233
- * @param {import('../../../index').Sound[]} sounds
234
- * @returns {{types: {name: string, count: number}[], keys: string[], bpm: {min: number, max: number}|null, hasDuration: boolean, loops: number, oneShots: number}}
268
+ * @param sounds
235
269
  */
236
- export function facets(sounds) {
237
- const types = new Map();
238
- const keys = new Set();
270
+ export function facets(sounds: Sound[]): {types: {name: string, count: number}[], keys: string[], bpm: {min: number, max: number}|null, hasDuration: boolean, loops: number, oneShots: number} {
271
+ const types = new Map<string, number>();
272
+ const keys = new Set<string>();
239
273
  let min = Infinity, max = -Infinity, hasDuration = false, loops = 0;
240
274
  for (const s of sounds) {
241
275
  if (s.type) types.set(s.type, (types.get(s.type) || 0) + 1);
@@ -264,11 +298,10 @@ export function facets(sounds) {
264
298
  * number in the query also matches the BPM exactly, so "bass 128" finds
265
299
  * 128 BPM bass loops.
266
300
  *
267
- * @param {import('../../../index').Sound} sound
268
- * @param {import('../../../index').SoundsFilter} filter
269
- * @returns {boolean}
301
+ * @param sound
302
+ * @param filter
270
303
  */
271
- export function matches(sound, filter = {}) {
304
+ export function matches(sound: Sound, filter: Partial<SoundsFilter> = {}): boolean {
272
305
  if (filter.type && sound.type !== filter.type) return false;
273
306
  if (filter.key && sound.key !== normalizeKey(filter.key)) return false;
274
307
  if (filter.loop === 'loop' && !sound.loop) return false;
@@ -293,10 +326,10 @@ export function matches(sound, filter = {}) {
293
326
  }
294
327
 
295
328
  /** The sort orders the toolbar offers. */
296
- export const SORTS = ['default', 'title', 'bpm', 'key', 'duration'];
329
+ export const SORTS: SoundsSort[] = ['default', 'title', 'bpm', 'key', 'duration'];
297
330
 
298
331
  /** What each sort order needs from the data before it's worth offering. */
299
- const SORT_NEEDS = {
332
+ const SORT_NEEDS: Record<string, (f: ReturnType<typeof facets>) => boolean> = {
300
333
  default: () => true,
301
334
  title: () => true,
302
335
  bpm: (f) => f.bpm !== null,
@@ -309,11 +342,10 @@ const SORT_NEEDS = {
309
342
  * in the configured order. Shared by the renderer and the runtime, so the
310
343
  * menu and the starting order always agree.
311
344
  *
312
- * @param {string[]} sorts - The configured orders.
313
- * @param {ReturnType<typeof facets>} f - The sounds' facets.
314
- * @returns {string[]}
345
+ * @param sorts - The configured orders.
346
+ * @param f - The sounds' facets.
315
347
  */
316
- export function availableSorts(sorts, f) {
348
+ export function availableSorts(sorts: string[], f: ReturnType<typeof facets>): string[] {
317
349
  return sorts.filter((sort) => SORT_NEEDS[sort]?.(f));
318
350
  }
319
351
 
@@ -321,19 +353,18 @@ export function availableSorts(sorts, f) {
321
353
  * Sort sounds (returns a new array; `default` keeps the given order).
322
354
  * Missing values sort last in every order.
323
355
  *
324
- * @param {import('../../../index').Sound[]} sounds
325
- * @param {string} [by='default']
326
- * @returns {import('../../../index').Sound[]}
356
+ * @param sounds
357
+ * @param by
327
358
  */
328
- export function sortSounds(sounds, by = 'default') {
359
+ export function sortSounds(sounds: Sound[], by: SoundsSort = 'default'): Sound[] {
329
360
  const list = sounds.map((s, i) => ({s, i}));
330
- const last = (v) => (v == null ? Infinity : v);
331
- const cmp = {
361
+ const last = (v: number | null): number => (v == null ? Infinity : v);
362
+ const cmp = ({
332
363
  title: (a, b) => a.s.title.localeCompare(b.s.title, undefined, {numeric: true, sensitivity: 'base'}),
333
364
  bpm: (a, b) => last(a.s.bpm) - last(b.s.bpm),
334
365
  key: (a, b) => keyRank(a.s.key) - keyRank(b.s.key),
335
366
  duration: (a, b) => last(a.s.duration) - last(b.s.duration),
336
- }[by];
367
+ } as Record<string, (a: {s: Sound, i: number}, b: {s: Sound, i: number}) => number>)[by];
337
368
  if (cmp) list.sort((a, b) => cmp(a, b) || a.i - b.i);
338
369
  return list.map((x) => x.s);
339
370
  }
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Filters in the address (`urlState`): which query parameters hold them,
3
+ * reading them into a filter, and writing a filter back into a URL. Pure:
4
+ * the runtime passes `location.search` / `location.href` in and calls
5
+ * `history.replaceState` with what comes out.
6
+ *
7
+ * ?q=bass&type=Bass+loops&key=Fm&bpm=120-130&loop=one-shot&sort=bpm
8
+ *
9
+ * @module url-state
10
+ */
11
+
12
+ import {LOOP_FILTERS, normalizeKey} from './sounds.js';
13
+ import type {SoundsFilter, SoundsLoopFilter} from '../types.js';
14
+
15
+ /**
16
+ * The parameter names, or null when urlState is off. A string urlState
17
+ * prefixes them (`'pack'` → `pack-q`, `pack-type`, …) so two lists on one
18
+ * page don't share a filter.
19
+ *
20
+ * @param urlState
21
+ */
22
+ export function urlKeys(urlState: boolean | string | null | undefined): {q: string, type: string, key: string, bpm: string, loop: string, sort: string} | null {
23
+ if (!urlState) return null;
24
+ const p = typeof urlState === 'string' ? `${urlState}-` : '';
25
+ return {q: `${p}q`, type: `${p}type`, key: `${p}key`, bpm: `${p}bpm`, loop: `${p}loop`, sort: `${p}sort`};
26
+ }
27
+
28
+ /**
29
+ * A BPM range parameter: "120-130", "120-", "-130", or with decimals
30
+ * ("128.5-130", what `setFilter({bpmMin: 128.5})` writes). Reversed ends
31
+ * are put in order.
32
+ *
33
+ * @param value
34
+ * @returns null if malformed.
35
+ */
36
+ export function parseBpmRange(value: string | null | undefined): {bpmMin: string, bpmMax: string} | null {
37
+ const m = String(value ?? '').match(/^(\d+(?:\.\d+)?)?-(\d+(?:\.\d+)?)?$/);
38
+ if (!m || !(m[1] || m[2])) return null;
39
+ const lo = m[1] ?? '', hi = m[2] ?? '';
40
+ return lo && hi && Number(lo) > Number(hi) ? {bpmMin: hi, bpmMax: lo} : {bpmMin: lo, bpmMax: hi};
41
+ }
42
+
43
+ /**
44
+ * Keep only the limits that fall inside the pack's BPM range: a link made
45
+ * for another pack (`?bpm=200-` on one topping out at 174) must not empty
46
+ * the list, and a limit beyond an end is no limit at all.
47
+ *
48
+ * @param range - From {@link parseBpmRange}.
49
+ * @param extent - The slider's range; null when the pack has no BPMs
50
+ * (then any BPM filter would hide everything, so none is kept).
51
+ * @returns The usable limits, or null when none is left.
52
+ */
53
+ export function bpmRangeWithin(range: {bpmMin: string, bpmMax: string}, extent: {min: number, max: number} | null): {bpmMin: string, bpmMax: string} | null {
54
+ if (!extent) return null;
55
+ const inside = (v: string) => (v !== '' && Number(v) >= extent.min && Number(v) <= extent.max ? v : '');
56
+ const out = {bpmMin: inside(range.bpmMin), bpmMax: inside(range.bpmMax)};
57
+ return out.bpmMin || out.bpmMax ? out : null;
58
+ }
59
+
60
+ /**
61
+ * The inverse of {@link parseBpmRange}; '' when neither end is set.
62
+ *
63
+ * @param min
64
+ * @param max
65
+ */
66
+ export function formatBpmRange(min: string | number | null | undefined, max: string | number | null | undefined): string {
67
+ const lo = min ?? '', hi = max ?? '';
68
+ return lo !== '' || hi !== '' ? `${lo}-${hi}` : '';
69
+ }
70
+
71
+ /**
72
+ * Read the filter and sort from a query string. Values the list can't use
73
+ * (a type it doesn't have, a key no sound is in, a BPM limit outside its
74
+ * range, a loops filter on a list that isn't a mix of loops and one-shots,
75
+ * a sort it doesn't offer)
76
+ * are ignored, never applied: a stale link shows the whole list, not an
77
+ * empty one.
78
+ *
79
+ * @param search - `location.search`.
80
+ * @param keys
81
+ * @param available - From `facets()`, with `bpm` as the slider's range
82
+ * (`bpmExtent()`).
83
+ * @param sorts - The sort orders offered.
84
+ * @returns A filter patch, and the sort (or null).
85
+ */
86
+ export function readUrlState(search: string, keys: ReturnType<typeof urlKeys>, available: {types: {name: string}[], keys: string[], loops?: number, oneShots?: number, bpm?: {min: number, max: number} | null}, sorts: string[]): {filter: Partial<SoundsFilter>, sort: string|null} {
87
+ const out: {filter: Partial<SoundsFilter>, sort: string | null} = {filter: {}, sort: null};
88
+ if (!keys) return out;
89
+ const sp = new URLSearchParams(search);
90
+ const q = sp.get(keys.q);
91
+ if (q) out.filter.query = q;
92
+ const type = sp.get(keys.type);
93
+ if (type && available.types.some((t) => t.name === type)) out.filter.type = type;
94
+ const key = normalizeKey(sp.get(keys.key));
95
+ if (key && available.keys.includes(key)) out.filter.key = key;
96
+ const parsed = parseBpmRange(sp.get(keys.bpm));
97
+ // Without the pack's range (an older caller), the limits apply as given.
98
+ const bpm = parsed && available.bpm !== undefined ? bpmRangeWithin(parsed, available.bpm) : parsed;
99
+ if (bpm) Object.assign(out.filter, bpm);
100
+ const loop = sp.get(keys.loop);
101
+ if (LOOP_FILTERS.includes(loop!) && available.loops! > 0 && available.oneShots! > 0) out.filter.loop = loop as SoundsLoopFilter;
102
+ const sort = sp.get(keys.sort);
103
+ if (sort && sorts.includes(sort)) out.sort = sort;
104
+ return out;
105
+ }
106
+
107
+ /**
108
+ * The URL with the filter written in. Empty values (and the starting sort)
109
+ * are removed rather than written empty; every other parameter and the
110
+ * hash are kept.
111
+ *
112
+ * @param href - `location.href`.
113
+ * @param keys
114
+ * @param filter
115
+ * @param sort
116
+ * @param defaultSort - The starting order (not written).
117
+ * @returns The new href (equal to `href` when nothing changed).
118
+ */
119
+ export function writeUrlState(href: string, keys: ReturnType<typeof urlKeys>, filter: SoundsFilter, sort: string, defaultSort: string): string {
120
+ if (!keys) return href;
121
+ const url = new URL(href);
122
+ const set = (name: string, v: string | undefined) => (v ? url.searchParams.set(name, v) : url.searchParams.delete(name));
123
+ set(keys.q, String(filter.query ?? '').trim());
124
+ set(keys.type, filter.type);
125
+ set(keys.key, filter.key);
126
+ set(keys.bpm, formatBpmRange(filter.bpmMin, filter.bpmMax));
127
+ set(keys.loop, filter.loop);
128
+ set(keys.sort, sort !== defaultSort ? sort : '');
129
+ return url.href;
130
+ }
@@ -0,0 +1,86 @@
1
+ /**
2
+ * Colours the CSS can't hand the runtime directly: the canvas needs real
3
+ * colour values (it can't read `var()` or `color-mix()`), and the inverted
4
+ * "on" states need the page surface behind the list.
5
+ *
6
+ * @module colors
7
+ */
8
+
9
+ /**
10
+ * The alpha of a computed colour string: `rgba(0, 0, 0, 0)`,
11
+ * `rgb(1 2 3 / 50%)`, `oklab(… / 0.9)`, `transparent`. Opaque when no alpha
12
+ * is written.
13
+ *
14
+ * @param color
15
+ * @returns 0..1.
16
+ */
17
+ export function parseAlpha(color: string | null | undefined): number {
18
+ const c = String(color ?? '').trim();
19
+ if (!c || c === 'transparent') return 0;
20
+ const slash = c.match(/\/\s*([\d.]+)(%?)\s*\)$/);
21
+ if (slash) return Number(slash[1]) / (slash[2] ? 100 : 1);
22
+ const rgba = c.match(/^rgba\(\s*[^,]+,[^,]+,[^,]+,\s*([\d.]+)\s*\)$/);
23
+ if (rgba) return Number(rgba[1]);
24
+ return 1;
25
+ }
26
+
27
+ /**
28
+ * The first (near-)opaque background at or above an element — the page
29
+ * surface the list sits on. Crosses shadow-root boundaries.
30
+ *
31
+ * @param el
32
+ * @param minAlpha - How opaque counts as "the surface".
33
+ * @returns A computed colour, or `#fff` when nothing is painted.
34
+ */
35
+ export function pageSurface(el: Element, minAlpha: number = 0.95): string {
36
+ for (let node = el; node && node.nodeType === 1; node = node.parentElement || (node as any).getRootNode?.().host) {
37
+ const bg = getComputedStyle(node).backgroundColor;
38
+ if (parseAlpha(bg) > minAlpha) return bg;
39
+ }
40
+ return '#fff';
41
+ }
42
+
43
+ /**
44
+ * Is the page in forced colours (Windows High Contrast)? Then the canvas
45
+ * must draw in system colours too.
46
+ */
47
+ export function forcedColors(): boolean {
48
+ try {
49
+ return typeof matchMedia === 'function' && matchMedia('(forced-colors: active)').matches;
50
+ } catch {
51
+ return false;
52
+ }
53
+ }
54
+
55
+ /**
56
+ * Every element above `el`, nearest first, crossing shadow-root boundaries
57
+ * (the elements whose class, style or theme attribute can change what the
58
+ * list inherits).
59
+ *
60
+ * @param el
61
+ */
62
+ export function ancestorsOf(el: Element): Element[] {
63
+ const out: Element[] = [];
64
+ for (let node = el.parentElement || (el.getRootNode?.() as ShadowRoot | undefined)?.host; node; node = node.parentElement || (node.getRootNode?.() as ShadowRoot | undefined)?.host) out.push(node);
65
+ return out;
66
+ }
67
+
68
+ /**
69
+ * Resolve any CSS colour (a `var()`, `color-mix()`, `currentColor`) to a
70
+ * concrete value, as it would compute inside `container`.
71
+ *
72
+ * @param container
73
+ * @param value - A CSS colour expression.
74
+ * @returns The computed colour.
75
+ */
76
+ export function resolveCssColor(container: Element, value: string): string {
77
+ const probe = document.createElement('span');
78
+ // forced-color-adjust: none, so a system colour (CanvasText, Highlight)
79
+ // resolves as itself under forced colours instead of being forced.
80
+ probe.style.cssText = 'position:absolute;width:0;height:0;overflow:hidden;visibility:hidden;forced-color-adjust:none';
81
+ probe.style.color = value;
82
+ container.appendChild(probe);
83
+ const color = getComputedStyle(probe).color;
84
+ probe.remove();
85
+ return color;
86
+ }
@@ -13,9 +13,9 @@
13
13
  /**
14
14
  * Size a canvas to its box at the device pixel ratio. Returns the CSS size,
15
15
  * or null when the canvas has no box (hidden row, jsdom).
16
- * @param {HTMLCanvasElement} canvas
16
+ * @param canvas
17
17
  */
18
- export function fitCanvas(canvas) {
18
+ export function fitCanvas(canvas: HTMLCanvasElement) {
19
19
  const rect = canvas.getBoundingClientRect();
20
20
  if (!rect.width || !rect.height) return null;
21
21
  const dpr = Math.min(window.devicePixelRatio || 1, 3);
@@ -28,10 +28,10 @@ export function fitCanvas(canvas) {
28
28
  /**
29
29
  * Resample peaks to `count` bars (max of each bucket, so transients
30
30
  * survive the downsample).
31
- * @param {number[]} peaks
32
- * @param {number} count
31
+ * @param peaks
32
+ * @param count
33
33
  */
34
- export function resample(peaks, count) {
34
+ export function resample(peaks: number[], count: number) {
35
35
  if (!peaks?.length || count <= 0) return [];
36
36
  if (peaks.length === count) return peaks;
37
37
  const out = new Array(count);
@@ -54,13 +54,12 @@ export function resample(peaks, count) {
54
54
  * Bars are normalised to the loudest one, so a quiet one-shot isn't a
55
55
  * flat line, and never shorter than 4% of the height.
56
56
  *
57
- * @param {number[]} peaks - 0..1.
58
- * @param {number} width - Canvas width (CSS px).
59
- * @param {number} height - Canvas height (CSS px).
60
- * @param {{style: 'mirror'|'bars', barWidth: number, barGap: number}} o
61
- * @returns {{x: number, y: number, w: number, h: number}[]}
57
+ * @param peaks - 0..1.
58
+ * @param width - Canvas width (CSS px).
59
+ * @param height - Canvas height (CSS px).
60
+ * @param o
62
61
  */
63
- export function barRects(peaks, width, height, o) {
62
+ export function barRects(peaks: number[], width: number, height: number, o: {style: 'mirror'|'bars', barWidth: number, barGap: number}): {x: number, y: number, w: number, h: number}[] {
64
63
  const step = o.barWidth + o.barGap;
65
64
  const bars = resample(peaks, Math.max(1, Math.floor((width + o.barGap) / step)));
66
65
  const max = bars.reduce((m, b) => (b > m ? b : m), 0);
@@ -84,16 +83,16 @@ export function barRects(peaks, width, height, o) {
84
83
  * loop across ~120 bars moved in ~15 jumps a second however fast it was
85
84
  * redrawn).
86
85
  *
87
- * @param {HTMLCanvasElement} canvas
88
- * @param {number[]|null} peaks - 0..1. Null draws a flat placeholder line.
89
- * @param {number} progress - 0..1 played.
90
- * @param {{style: 'mirror'|'bars', color: string, progressColor: string, barWidth: number, barGap: number}} o
86
+ * @param canvas
87
+ * @param peaks - 0..1. Null draws a flat placeholder line.
88
+ * @param progress - 0..1 played.
89
+ * @param o
91
90
  */
92
- export function drawRowWaveform(canvas, peaks, progress, o) {
91
+ export function drawRowWaveform(canvas: HTMLCanvasElement, peaks: number[] | null, progress: number, o: {style: 'mirror'|'bars', color: string, progressColor: string, barWidth: number, barGap: number}) {
93
92
  const size = fitCanvas(canvas);
94
93
  const ctx = size && canvas.getContext && canvas.getContext('2d');
95
94
  if (!ctx) return;
96
- const {width, height, dpr} = size;
95
+ const {width, height, dpr} = size!;
97
96
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
98
97
  ctx.clearRect(0, 0, width, height);
99
98