@arraypress/waveform-sounds 2.0.0 → 2.2.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 (79) hide show
  1. package/README.md +44 -2
  2. package/dist/waveform-sounds-no-autoinit.esm.js +914 -208
  3. package/dist/waveform-sounds-render.esm.js +274 -82
  4. package/dist/waveform-sounds.css +92 -17
  5. package/dist/waveform-sounds.esm.js +917 -210
  6. package/dist/waveform-sounds.js +913 -210
  7. package/dist/waveform-sounds.min.css +1 -1
  8. package/dist/waveform-sounds.min.js +3 -3
  9. package/package.json +1 -1
  10. package/src/css/waveform-sounds.css +92 -17
  11. package/src/js/core/WaveformSounds.ts +540 -120
  12. package/src/js/core/element.ts +208 -0
  13. package/src/js/core/engine.ts +9 -3
  14. package/src/js/core/options.ts +1 -5
  15. package/src/js/data/bpm.ts +14 -4
  16. package/src/js/data/keys.ts +156 -0
  17. package/src/js/data/navigation.ts +51 -11
  18. package/src/js/data/sounds.ts +73 -36
  19. package/src/js/data/url-state.ts +39 -12
  20. package/src/js/dom/colors.ts +28 -1
  21. package/src/js/dom/draw.ts +16 -3
  22. package/src/js/dom/menus.ts +2 -3
  23. package/src/js/dom/rows.ts +38 -15
  24. package/src/js/entry.ts +13 -3
  25. package/src/js/index.ts +7 -3
  26. package/src/js/render/html.ts +0 -2
  27. package/src/js/render/icons.ts +59 -17
  28. package/src/js/render/markup.ts +156 -62
  29. package/src/js/render/options.ts +29 -5
  30. package/src/js/render/strings.ts +57 -4
  31. package/src/js/render-entry.ts +1 -1
  32. package/src/js/shared/utils.ts +4 -4
  33. package/src/js/types.ts +54 -3
  34. package/types/core/WaveformSounds.d.ts +41 -11
  35. package/types/core/WaveformSounds.d.ts.map +1 -1
  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 +8 -3
  39. package/types/core/engine.d.ts.map +1 -1
  40. package/types/core/options.d.ts +0 -5
  41. package/types/core/options.d.ts.map +1 -1
  42. package/types/data/bpm.d.ts +17 -4
  43. package/types/data/bpm.d.ts.map +1 -1
  44. package/types/data/keys.d.ts +88 -0
  45. package/types/data/keys.d.ts.map +1 -0
  46. package/types/data/navigation.d.ts +38 -11
  47. package/types/data/navigation.d.ts.map +1 -1
  48. package/types/data/sounds.d.ts +33 -17
  49. package/types/data/sounds.d.ts.map +1 -1
  50. package/types/data/url-state.d.ts +38 -7
  51. package/types/data/url-state.d.ts.map +1 -1
  52. package/types/dom/colors.d.ts +13 -0
  53. package/types/dom/colors.d.ts.map +1 -1
  54. package/types/dom/draw.d.ts +5 -3
  55. package/types/dom/draw.d.ts.map +1 -1
  56. package/types/dom/menus.d.ts +0 -2
  57. package/types/dom/menus.d.ts.map +1 -1
  58. package/types/dom/rows.d.ts +19 -11
  59. package/types/dom/rows.d.ts.map +1 -1
  60. package/types/entry.d.ts +10 -4
  61. package/types/entry.d.ts.map +1 -1
  62. package/types/index.d.ts +2 -2
  63. package/types/index.d.ts.map +1 -1
  64. package/types/render/html.d.ts +0 -2
  65. package/types/render/html.d.ts.map +1 -1
  66. package/types/render/icons.d.ts +41 -3
  67. package/types/render/icons.d.ts.map +1 -1
  68. package/types/render/markup.d.ts +44 -12
  69. package/types/render/markup.d.ts.map +1 -1
  70. package/types/render/options.d.ts +18 -5
  71. package/types/render/options.d.ts.map +1 -1
  72. package/types/render/strings.d.ts +22 -4
  73. package/types/render/strings.d.ts.map +1 -1
  74. package/types/render-entry.d.ts +1 -1
  75. package/types/render-entry.d.ts.map +1 -1
  76. package/types/shared/utils.d.ts +3 -3
  77. package/types/shared/utils.d.ts.map +1 -1
  78. package/types/types.d.ts +53 -3
  79. package/types/types.d.ts.map +1 -1
@@ -1,4 +1,5 @@
1
1
  import {fold, matchesAll, words} from '@arraypress/text';
2
+ import {enharmonics, keyEntries, keyRank, sameKey} from './keys.js';
2
3
  import type {Sound, SoundInput, SoundsFilter, SoundsManifest, SoundsSort} from '../types.js';
3
4
 
4
5
  /**
@@ -29,12 +30,36 @@ export function encodePeaks(peaks: number[]): string {
29
30
  return out;
30
31
  }
31
32
 
33
+ /** The player's compact peaks format: `"wp1:"` + base64url (no padding). */
34
+ const COMPACT_PREFIX = 'wp1:';
35
+
36
+ /**
37
+ * The body of a `wp1:` string to 0..1 peaks (as the core decodes it).
38
+ *
39
+ * @param body - base64url, after the prefix.
40
+ * @returns Peaks, or null when malformed or empty.
41
+ */
42
+ function decodeCompact(body: string): number[] | null {
43
+ // A length of 4n+1 can't come from whole bytes.
44
+ if (!body || !/^[\w-]+$/.test(body) || body.length % 4 === 1) return null;
45
+ try {
46
+ const bytes = atob(body.replace(/-/g, '+').replace(/_/g, '/'));
47
+ const out = new Array(bytes.length);
48
+ for (let i = 0; i < bytes.length; i++) out[i] = bytes.charCodeAt(i) / 255;
49
+ return out;
50
+ } catch {
51
+ return null;
52
+ }
53
+ }
54
+
32
55
  /**
33
56
  * Decode peaks from any accepted form into numbers 0..1.
34
57
  *
35
- * Accepts the hex string from {@link encodePeaks}, an array of 0..1
36
- * numbers, or an array of integers on a larger scale (e.g. 0..100 or
37
- * 0..255) together with that `scale`.
58
+ * Accepts the hex string from {@link encodePeaks}, the player's compact
59
+ * `wp1:` string (`"wp1:"` + base64url of one byte per peak, what the 2.0
60
+ * core and waveform-gen write), an array of 0..1 numbers, or an array of
61
+ * integers on a larger scale (e.g. 0..100 or 0..255) together with that
62
+ * `scale`. Server markup still writes hex.
38
63
  *
39
64
  * @param value
40
65
  * @param scale - The maximum of an integer array.
@@ -43,9 +68,10 @@ export function encodePeaks(peaks: number[]): string {
43
68
  export function decodePeaks(value: string | number[] | null | undefined, scale: number = 1): number[] | null {
44
69
  if (value == null || value === '') return null;
45
70
  if (typeof value === 'string') {
71
+ if (value.startsWith(COMPACT_PREFIX)) return decodeCompact(value.slice(COMPACT_PREFIX.length));
46
72
  if (!/^[0-9a-f]+$/i.test(value) || value.length % 2) return null;
47
73
  const out = new Array(value.length / 2);
48
- for (let i = 0; i < out.length; i++) out[i] = parseInt(value.substr(i * 2, 2), 16) / 255;
74
+ for (let i = 0; i < out.length; i++) out[i] = parseInt(value.slice(i * 2, i * 2 + 2), 16) / 255;
49
75
  return out;
50
76
  }
51
77
  if (!Array.isArray(value)) return null;
@@ -74,18 +100,6 @@ export function normalizeKey(key: string | null | undefined): string {
74
100
  return root + acc + (minor ? 'm' : '');
75
101
  }
76
102
 
77
- /** Pitch class of each root, for sorting keys: C, C#, D … B, majors before minors. */
78
- 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};
79
-
80
- /** Sort rank of a canonical key; unknown keys sort last. */
81
- function keyRank(key: string): number {
82
- if (!key) return Infinity;
83
- const minor = key.endsWith('m');
84
- const root = minor ? key.slice(0, -1) : key;
85
- const p = KEY_PITCH[root];
86
- return p === undefined ? 1000 : p * 2 + (minor ? 1 : 0);
87
- }
88
-
89
103
  /**
90
104
  * Format seconds as m:ss (whole seconds, rounded down like a player's
91
105
  * clock), or as tenths under a second.
@@ -109,18 +123,31 @@ export function formatDuration(seconds: number | null | undefined): string {
109
123
  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
110
124
  }
111
125
 
126
+ /**
127
+ * A playback position as a clock: whole seconds, rounded down like a
128
+ * player's ("0:12", "1:05:09" past an hour).
129
+ *
130
+ * @param seconds
131
+ * @returns e.g. "0:12"; "0:00" for anything unusable.
132
+ */
133
+ export function formatClock(seconds: number): string {
134
+ const total = Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds) : 0;
135
+ const h = Math.floor(total / 3600), m = Math.floor((total % 3600) / 60), sec = String(total % 60).padStart(2, '0');
136
+ return h ? `${h}:${String(m).padStart(2, '0')}:${sec}` : `${m}:${sec}`;
137
+ }
138
+
112
139
  /**
113
140
  * Parse a duration given as seconds (8.02) or as "m:ss" / "h:mm:ss".
114
141
  * @param value
115
- * @returns
116
142
  */
117
143
  export function parseDuration(value: number | string | null | undefined): number | null {
118
144
  if (value == null || value === '') return null;
119
145
  if (typeof value === 'number') return Number.isFinite(value) && value >= 0 ? value : null;
120
146
  const str = String(value).trim();
121
147
  if (/^\d+(\.\d+)?$/.test(str)) return Number(str);
148
+ // Each part a plain non-negative number: "1:-30" is not a length.
149
+ if (!/^\d+(\.\d+)?(:\d+(\.\d+)?)+$/.test(str)) return null;
122
150
  const parts = str.split(':').map(Number);
123
- if (parts.length < 2 || parts.some((n) => !Number.isFinite(n))) return null;
124
151
  return parts.reduce((acc, n) => acc * 60 + n, 0);
125
152
  }
126
153
 
@@ -129,7 +156,6 @@ export function parseDuration(value: number | string | null | undefined): number
129
156
  * leading pack prefixes kept (they are often the label's code).
130
157
  * "NW_Bass_Loop_04_128_Fmin.wav" → "NW Bass Loop 04 128 Fmin".
131
158
  * @param url
132
- * @returns
133
159
  */
134
160
  export function titleFromUrl(url: string): string {
135
161
  const file = String(url || '').split(/[?#]/)[0].split('/').pop() || '';
@@ -183,7 +209,6 @@ export const LOOP_FILTERS = ['loop', 'one-shot'];
183
209
  * as an attribute or a CSV-ish manifest writes it. Unset is a one-shot.
184
210
  *
185
211
  * @param value
186
- * @returns
187
212
  */
188
213
  export function isLoop(value: unknown): boolean {
189
214
  return value === true || value === 1 || value === 'true' || value === '1';
@@ -195,7 +220,6 @@ export function isLoop(value: unknown): boolean {
195
220
  * Sounds without a url are dropped.
196
221
  *
197
222
  * @param manifest
198
- * @returns
199
223
  */
200
224
  export function parseManifest(manifest: SoundsManifest | SoundInput[]): Sound[] {
201
225
  const list = Array.isArray(manifest) ? manifest : Array.isArray(manifest?.sounds) ? manifest.sounds : [];
@@ -208,7 +232,6 @@ export function parseManifest(manifest: SoundsManifest | SoundInput[]): Sound[]
208
232
  * (a repeated id would make two rows answer to one play() call).
209
233
  * @param list
210
234
  * @param peakScale
211
- * @returns
212
235
  */
213
236
  export function normalizeSounds(list: SoundInput[], peakScale: number = 1): Sound[] {
214
237
  const seen = new Set<string>();
@@ -225,29 +248,40 @@ export function normalizeSounds(list: SoundInput[], peakScale: number = 1): Soun
225
248
  return out;
226
249
  }
227
250
 
251
+ /** Options of the pure filter helpers ({@link facets}, {@link matches}). */
252
+ export interface KeyOptions {
253
+ /** Enharmonic keys (A#m and Bbm) are one key. Default true. Since 2.2.0. */
254
+ mergeEnharmonicKeys?: boolean;
255
+ }
256
+
228
257
  /**
229
258
  * What the filter controls offer, derived from the sounds: each type with
230
- * its count (in first-seen order), each key (in musical order), the BPM
231
- * range, and how many are loops and one-shots. A control with nothing to
232
- * offer is not rendered.
259
+ * its count (in first-seen order), each key (in musical order; enharmonic
260
+ * spellings merged into one entry unless `mergeEnharmonicKeys` is false —
261
+ * see `keyEntries` for the spelling it shows), the BPM range, and how many
262
+ * are loops and one-shots. A control with nothing to offer is not rendered.
233
263
  *
234
264
  * @param sounds
235
- * @returns
265
+ * @param options
266
+ * @returns `keyAliases`: each merged key entry's other spellings in the
267
+ * list (since 2.2.0).
236
268
  */
237
- export function facets(sounds: Sound[]): {types: {name: string, count: number}[], keys: string[], bpm: {min: number, max: number}|null, hasDuration: boolean, loops: number, oneShots: number} {
269
+ export function facets(sounds: Sound[], options: KeyOptions = {}): {types: {name: string, count: number}[], keys: string[], keyAliases: Record<string, string[]>, bpm: {min: number, max: number}|null, hasDuration: boolean, loops: number, oneShots: number} {
238
270
  const types = new Map<string, number>();
239
- const keys = new Set<string>();
271
+ const keys: string[] = [];
240
272
  let min = Infinity, max = -Infinity, hasDuration = false, loops = 0;
241
273
  for (const s of sounds) {
242
274
  if (s.type) types.set(s.type, (types.get(s.type) || 0) + 1);
243
- if (s.key) keys.add(s.key);
275
+ if (s.key) keys.push(s.key);
244
276
  if (s.bpm != null) { min = Math.min(min, s.bpm); max = Math.max(max, s.bpm); }
245
277
  if (s.duration != null) hasDuration = true;
246
278
  if (s.loop) loops++;
247
279
  }
280
+ const entries = keyEntries(keys, options.mergeEnharmonicKeys !== false);
248
281
  return {
249
282
  types: [...types].map(([name, count]) => ({name, count})),
250
- keys: [...keys].sort((a, b) => keyRank(a) - keyRank(b) || a.localeCompare(b)),
283
+ keys: entries.keys,
284
+ keyAliases: entries.aliases,
251
285
  bpm: min === Infinity ? null : {min, max},
252
286
  hasDuration,
253
287
  loops,
@@ -265,13 +299,18 @@ export function facets(sounds: Sound[]): {types: {name: string, count: number}[]
265
299
  * number in the query also matches the BPM exactly, so "bass 128" finds
266
300
  * 128 BPM bass loops.
267
301
  *
302
+ * Keys: unless `mergeEnharmonicKeys` is false, a key filter matches every
303
+ * spelling of that key (A#m finds Bbm too), and a key typed in the search
304
+ * finds its other spellings.
305
+ *
268
306
  * @param sound
269
307
  * @param filter
270
- * @returns
308
+ * @param options
271
309
  */
272
- export function matches(sound: Sound, filter: Partial<SoundsFilter> = {}): boolean {
310
+ export function matches(sound: Sound, filter: Partial<SoundsFilter> = {}, options: KeyOptions = {}): boolean {
311
+ const merge = options.mergeEnharmonicKeys !== false;
273
312
  if (filter.type && sound.type !== filter.type) return false;
274
- if (filter.key && sound.key !== normalizeKey(filter.key)) return false;
313
+ if (filter.key && !sameKey(sound.key, normalizeKey(filter.key), merge)) return false;
275
314
  if (filter.loop === 'loop' && !sound.loop) return false;
276
315
  if (filter.loop === 'one-shot' && sound.loop) return false;
277
316
  const lo = Number(filter.bpmMin), hi = Number(filter.bpmMax);
@@ -283,7 +322,7 @@ export function matches(sound: Sound, filter: Partial<SoundsFilter> = {}): boole
283
322
  }
284
323
  const terms = words(filter.query || '');
285
324
  if (terms.length) {
286
- const hay = [sound.title, sound.type, sound.key, ...(sound.tags || [])].join(' ');
325
+ const hay = [sound.title, sound.type, ...(merge ? enharmonics(sound.key) : [sound.key]), ...(sound.tags || [])].join(' ');
287
326
  const folded = fold(hay);
288
327
  // A number naming this sound's BPM is satisfied; the rest is text.
289
328
  const rest = terms.filter((w) => !(/^\d+$/.test(w) && !folded.includes(w)
@@ -312,7 +351,6 @@ const SORT_NEEDS: Record<string, (f: ReturnType<typeof facets>) => boolean> = {
312
351
  *
313
352
  * @param sorts - The configured orders.
314
353
  * @param f - The sounds' facets.
315
- * @returns
316
354
  */
317
355
  export function availableSorts(sorts: string[], f: ReturnType<typeof facets>): string[] {
318
356
  return sorts.filter((sort) => SORT_NEEDS[sort]?.(f));
@@ -324,7 +362,6 @@ export function availableSorts(sorts: string[], f: ReturnType<typeof facets>): s
324
362
  *
325
363
  * @param sounds
326
364
  * @param by
327
- * @returns
328
365
  */
329
366
  export function sortSounds(sounds: Sound[], by: SoundsSort = 'default'): Sound[] {
330
367
  const list = sounds.map((s, i) => ({s, i}));
@@ -10,6 +10,7 @@
10
10
  */
11
11
 
12
12
  import {LOOP_FILTERS, normalizeKey} from './sounds.js';
13
+ import {keyEntry} from './keys.js';
13
14
  import type {SoundsFilter, SoundsLoopFilter} from '../types.js';
14
15
 
15
16
  /**
@@ -18,7 +19,6 @@ import type {SoundsFilter, SoundsLoopFilter} from '../types.js';
18
19
  * page don't share a filter.
19
20
  *
20
21
  * @param urlState
21
- * @returns
22
22
  */
23
23
  export function urlKeys(urlState: boolean | string | null | undefined): {q: string, type: string, key: string, bpm: string, loop: string, sort: string} | null {
24
24
  if (!urlState) return null;
@@ -27,14 +27,35 @@ export function urlKeys(urlState: boolean | string | null | undefined): {q: stri
27
27
  }
28
28
 
29
29
  /**
30
- * A BPM range parameter: "120-130", "120-" or "-130".
30
+ * A BPM range parameter: "120-130", "120-", "-130", or with decimals
31
+ * ("128.5-130", what `setFilter({bpmMin: 128.5})` writes). Reversed ends
32
+ * are put in order.
31
33
  *
32
34
  * @param value
33
35
  * @returns null if malformed.
34
36
  */
35
37
  export function parseBpmRange(value: string | null | undefined): {bpmMin: string, bpmMax: string} | null {
36
- const m = String(value ?? '').match(/^(\d*)-(\d*)$/);
37
- return m && (m[1] || m[2]) ? {bpmMin: m[1], bpmMax: m[2]} : null;
38
+ const m = String(value ?? '').match(/^(\d+(?:\.\d+)?)?-(\d+(?:\.\d+)?)?$/);
39
+ if (!m || !(m[1] || m[2])) return null;
40
+ const lo = m[1] ?? '', hi = m[2] ?? '';
41
+ return lo && hi && Number(lo) > Number(hi) ? {bpmMin: hi, bpmMax: lo} : {bpmMin: lo, bpmMax: hi};
42
+ }
43
+
44
+ /**
45
+ * Keep only the limits that fall inside the pack's BPM range: a link made
46
+ * for another pack (`?bpm=200-` on one topping out at 174) must not empty
47
+ * the list, and a limit beyond an end is no limit at all.
48
+ *
49
+ * @param range - From {@link parseBpmRange}.
50
+ * @param extent - The slider's range; null when the pack has no BPMs
51
+ * (then any BPM filter would hide everything, so none is kept).
52
+ * @returns The usable limits, or null when none is left.
53
+ */
54
+ export function bpmRangeWithin(range: {bpmMin: string, bpmMax: string}, extent: {min: number, max: number} | null): {bpmMin: string, bpmMax: string} | null {
55
+ if (!extent) return null;
56
+ const inside = (v: string) => (v !== '' && Number(v) >= extent.min && Number(v) <= extent.max ? v : '');
57
+ const out = {bpmMin: inside(range.bpmMin), bpmMax: inside(range.bpmMax)};
58
+ return out.bpmMin || out.bpmMax ? out : null;
38
59
  }
39
60
 
40
61
  /**
@@ -42,7 +63,6 @@ export function parseBpmRange(value: string | null | undefined): {bpmMin: string
42
63
  *
43
64
  * @param min
44
65
  * @param max
45
- * @returns
46
66
  */
47
67
  export function formatBpmRange(min: string | number | null | undefined, max: string | number | null | undefined): string {
48
68
  const lo = min ?? '', hi = max ?? '';
@@ -51,18 +71,23 @@ export function formatBpmRange(min: string | number | null | undefined, max: str
51
71
 
52
72
  /**
53
73
  * Read the filter and sort from a query string. Values the list can't use
54
- * (a type it doesn't have, a key no sound is in, a loops filter on a list
55
- * that isn't a mix of loops and one-shots, a sort it doesn't offer)
74
+ * (a type it doesn't have, a key no sound is in, a BPM limit outside its
75
+ * range, a loops filter on a list that isn't a mix of loops and one-shots,
76
+ * a sort it doesn't offer)
56
77
  * are ignored, never applied: a stale link shows the whole list, not an
57
78
  * empty one.
58
79
  *
59
80
  * @param search - `location.search`.
60
81
  * @param keys
61
- * @param available - From `facets()`.
82
+ * @param available - From `facets()`, with `bpm` as the slider's range
83
+ * (`bpmExtent()`).
62
84
  * @param sorts - The sort orders offered.
85
+ * @param options
86
+ * @param options.mergeEnharmonicKeys - A key in either spelling selects
87
+ * the list's entry for it (`?key=A#m` → `Bbm`). Default true. Since 2.2.0.
63
88
  * @returns A filter patch, and the sort (or null).
64
89
  */
65
- export function readUrlState(search: string, keys: ReturnType<typeof urlKeys>, available: {types: {name: string}[], keys: string[], loops?: number, oneShots?: number}, sorts: string[]): {filter: Partial<SoundsFilter>, sort: string|null} {
90
+ 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[], options: {mergeEnharmonicKeys?: boolean} = {}): {filter: Partial<SoundsFilter>, sort: string|null} {
66
91
  const out: {filter: Partial<SoundsFilter>, sort: string | null} = {filter: {}, sort: null};
67
92
  if (!keys) return out;
68
93
  const sp = new URLSearchParams(search);
@@ -70,9 +95,11 @@ export function readUrlState(search: string, keys: ReturnType<typeof urlKeys>, a
70
95
  if (q) out.filter.query = q;
71
96
  const type = sp.get(keys.type);
72
97
  if (type && available.types.some((t) => t.name === type)) out.filter.type = type;
73
- const key = normalizeKey(sp.get(keys.key));
74
- if (key && available.keys.includes(key)) out.filter.key = key;
75
- const bpm = parseBpmRange(sp.get(keys.bpm));
98
+ const key = keyEntry(normalizeKey(sp.get(keys.key)), available.keys, options.mergeEnharmonicKeys !== false);
99
+ if (key) out.filter.key = key;
100
+ const parsed = parseBpmRange(sp.get(keys.bpm));
101
+ // Without the pack's range (an older caller), the limits apply as given.
102
+ const bpm = parsed && available.bpm !== undefined ? bpmRangeWithin(parsed, available.bpm) : parsed;
76
103
  if (bpm) Object.assign(out.filter, bpm);
77
104
  const loop = sp.get(keys.loop);
78
105
  if (LOOP_FILTERS.includes(loop!) && available.loops! > 0 && available.oneShots! > 0) out.filter.loop = loop as SoundsLoopFilter;
@@ -40,6 +40,31 @@ export function pageSurface(el: Element, minAlpha: number = 0.95): string {
40
40
  return '#fff';
41
41
  }
42
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
+
43
68
  /**
44
69
  * Resolve any CSS colour (a `var()`, `color-mix()`, `currentColor`) to a
45
70
  * concrete value, as it would compute inside `container`.
@@ -50,7 +75,9 @@ export function pageSurface(el: Element, minAlpha: number = 0.95): string {
50
75
  */
51
76
  export function resolveCssColor(container: Element, value: string): string {
52
77
  const probe = document.createElement('span');
53
- probe.style.cssText = 'position:absolute;width:0;height:0;overflow:hidden;visibility:hidden';
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';
54
81
  probe.style.color = value;
55
82
  container.appendChild(probe);
56
83
  const color = getComputedStyle(probe).color;
@@ -26,8 +26,11 @@ export function fitCanvas(canvas: HTMLCanvasElement) {
26
26
  }
27
27
 
28
28
  /**
29
- * Resample peaks to `count` bars (max of each bucket, so transients
30
- * survive the downsample).
29
+ * Resample peaks to `count` bars, whatever their number (64 or 128 from
30
+ * waveform-gen, any length of `wp1:`). Fewer bars than peaks: the max of
31
+ * each bucket, so transients survive. More bars than peaks: linear
32
+ * interpolation between neighbouring peaks — repeating each peak drew
33
+ * flat steps (64 peaks across a 400px row were plateaus three bars wide).
31
34
  * @param peaks
32
35
  * @param count
33
36
  */
@@ -35,6 +38,17 @@ export function resample(peaks: number[], count: number) {
35
38
  if (!peaks?.length || count <= 0) return [];
36
39
  if (peaks.length === count) return peaks;
37
40
  const out = new Array(count);
41
+ if (count > peaks.length) {
42
+ // Bar i's centre, on the peaks' own axis (peak j's centre is j).
43
+ const last = peaks.length - 1;
44
+ const ratio = peaks.length / count;
45
+ for (let i = 0; i < count; i++) {
46
+ const x = Math.min(Math.max((i + 0.5) * ratio - 0.5, 0), last);
47
+ const j = Math.floor(x), t = x - j;
48
+ out[i] = j >= last ? peaks[last] : peaks[j] + (peaks[j + 1] - peaks[j]) * t;
49
+ }
50
+ return out;
51
+ }
38
52
  const step = peaks.length / count;
39
53
  for (let i = 0; i < count; i++) {
40
54
  const start = Math.floor(i * step);
@@ -58,7 +72,6 @@ export function resample(peaks: number[], count: number) {
58
72
  * @param width - Canvas width (CSS px).
59
73
  * @param height - Canvas height (CSS px).
60
74
  * @param o
61
- * @returns
62
75
  */
63
76
  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
77
  const step = o.barWidth + o.barGap;
@@ -23,7 +23,6 @@ import {fold} from '@arraypress/text';
23
23
  *
24
24
  * @param label
25
25
  * @param query
26
- * @returns
27
26
  */
28
27
  export function optionMatches(label: string, query: string): boolean {
29
28
  const q = fold(String(query ?? '')).trim();
@@ -36,7 +35,6 @@ export function optionMatches(label: string, query: string): boolean {
36
35
  * @param current - -1 when nothing is active.
37
36
  * @param delta
38
37
  * @param length
39
- * @returns
40
38
  */
41
39
  export function stepIndex(current: number, delta: number, length: number): number {
42
40
  return Math.max(0, Math.min(length - 1, current + delta));
@@ -203,7 +201,8 @@ export class Menus {
203
201
  const p = partsOf(menu);
204
202
  let first: HTMLElement | null = null;
205
203
  for (const opt of optionsOf(p)) {
206
- opt.hidden = !optionMatches(opt.textContent, query);
204
+ // A merged key is found by any of its spellings (`data-alt`).
205
+ opt.hidden = !optionMatches(`${opt.textContent} ${opt.dataset.alt ?? ''}`, query);
207
206
  if (!opt.hidden) first ??= opt;
208
207
  }
209
208
  p.none!.hidden = first !== null;
@@ -1,24 +1,44 @@
1
1
  /**
2
- * The rows in the DOM: reading server-rendered rows back into sounds, and
3
- * finding a row by the sound it shows.
2
+ * The rows in the DOM: reading server-rendered sounds back, finding a row
3
+ * by the sound it shows, and putting exactly the rows shown in the list.
4
4
  *
5
5
  * @module rows
6
6
  */
7
7
 
8
- import {normalizeSound} from '../data/sounds.js';
8
+ import {normalizeSound, normalizeSounds} from '../data/sounds.js';
9
+ import {LOG} from '../shared/utils.js';
9
10
  import type {Sound} from '../types.js';
10
11
 
11
12
  /** A list's row elements, in DOM order. */
12
13
  const ROW = ':scope > [data-ws-index]';
13
14
 
14
15
  /**
15
- * Read server-rendered rows back into sounds. Rows are taken in their
16
+ * Read the sounds of server-rendered markup from its JSON
17
+ * (`<script type="application/json" data-ws-sounds>`, since 2.2.0).
18
+ *
19
+ * @param root - The list's container.
20
+ * @returns The sounds, or null when there is no (usable) JSON — then the
21
+ * rows themselves are read ({@link readRows}, markup from before 2.2).
22
+ */
23
+ export function readSoundsData(root: HTMLElement): Sound[] | null {
24
+ const script = root.querySelector(':scope > script[data-ws-sounds]');
25
+ if (!script) return null;
26
+ try {
27
+ const list = JSON.parse(script.textContent || '');
28
+ if (Array.isArray(list)) return normalizeSounds(list);
29
+ } catch { /* reported below */ }
30
+ console.warn(`${LOG} Ignoring unreadable sounds JSON (data-ws-sounds)`);
31
+ return null;
32
+ }
33
+
34
+ /**
35
+ * Read server-rendered rows back into sounds (markup from before 2.2.0,
36
+ * whose rows carry every field as a `data-*` attribute). Rows are taken in their
16
37
  * original order (`data-ws-index`) and renumbered 0..n-1, and a row whose
17
38
  * data is unusable (no url) is removed — so a row missing from the markup
18
39
  * can't leave a hole that would misalign rows and sounds.
19
40
  *
20
41
  * @param list - The `[data-ws-list]` element.
21
- * @returns
22
42
  */
23
43
  export function readRows(list: HTMLElement): Sound[] {
24
44
  const rows = [...list.querySelectorAll<HTMLElement>(ROW)]
@@ -42,7 +62,6 @@ export function readRows(list: HTMLElement): Sound[] {
42
62
  * they're displayed in).
43
63
  *
44
64
  * @param list
45
- * @returns
46
65
  */
47
66
  export function indexRows(list: HTMLElement): HTMLElement[] {
48
67
  const rows: HTMLElement[] = [];
@@ -51,25 +70,29 @@ export function indexRows(list: HTMLElement): HTMLElement[] {
51
70
  }
52
71
 
53
72
  /**
54
- * The rows currently visible (not hidden by the filter or the page), in
55
- * display order.
73
+ * The rows in the list (not hidden), in display order.
56
74
  *
57
75
  * @param list
58
- * @returns
59
76
  */
60
77
  export function visibleRows(list: HTMLElement): HTMLElement[] {
61
78
  return [...list.querySelectorAll<HTMLElement>(ROW)].filter((r) => !r.hidden);
62
79
  }
63
80
 
64
81
  /**
65
- * Put the rows in the given order. Every row moves (hidden ones too), so
66
- * clearing a filter keeps the order.
82
+ * Make the list hold exactly `rows`, in that order: rows not among them
83
+ * leave the DOM, new ones go in, and rows already in order are not moved
84
+ * (moving an element drops its focus, so a filter change keeps focus
85
+ * where it was; only a re-sort moves rows).
67
86
  *
68
87
  * @param list
69
88
  * @param rows - In the order to show them.
70
89
  */
71
- export function orderRows(list: HTMLElement, rows: HTMLElement[]) {
72
- const frag = document.createDocumentFragment();
73
- for (const row of rows) if (row) frag.appendChild(row);
74
- list.appendChild(frag);
90
+ export function layoutRows(list: HTMLElement, rows: HTMLElement[]): void {
91
+ const keep = new Set(rows);
92
+ for (const el of [...list.children]) if (!keep.has(el as HTMLElement)) el.remove();
93
+ let cursor = list.firstElementChild;
94
+ for (const row of rows) {
95
+ if (row === cursor) cursor = cursor.nextElementSibling;
96
+ else list.insertBefore(row, cursor);
97
+ }
75
98
  }
package/src/js/entry.ts CHANGED
@@ -1,14 +1,16 @@
1
1
  /**
2
2
  * @arraypress/waveform-sounds — public surface, without the import-time
3
- * auto-init scan (`index.js` adds that). Anything new belongs here.
3
+ * side effects: the auto-init scan and registering `<waveform-sounds>`
4
+ * (`index.js` adds those). Anything new belongs here.
4
5
  *
5
6
  * @module entry
6
7
  */
7
8
  import {WaveformSounds, DEFAULT_OPTIONS} from './core/WaveformSounds.js';
9
+ import {WaveformSoundsElement, defineWaveformSoundsElement} from './core/element.js';
8
10
  import {
9
11
  encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration,
10
12
  } from './data/sounds.js';
11
- import {renderSounds, renderSoundsElement, DEFAULT_STRINGS} from './render/markup.js';
13
+ import {renderSounds, renderSoundsElement, DEFAULT_STRINGS, RENDER_OPTION_KEYS, pickRenderOptions} from './render/markup.js';
12
14
  import type {WaveformSoundsEventMap} from './types.js';
13
15
 
14
16
  declare global {
@@ -17,11 +19,17 @@ declare global {
17
19
  WaveformSounds: typeof WaveformSounds;
18
20
  }
19
21
  interface HTMLElementEventMap extends WaveformSoundsEventMap {}
22
+ interface DocumentEventMap extends WaveformSoundsEventMap {}
23
+ interface WindowEventMap extends WaveformSoundsEventMap {}
20
24
  }
21
25
 
22
26
  WaveformSounds.utils = {encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration, renderSounds};
23
27
  WaveformSounds.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
24
28
  WaveformSounds.DEFAULT_STRINGS = DEFAULT_STRINGS;
29
+ // The element definer as a static too, so a CDN page that opted out of
30
+ // auto-init (no ES module import to reach the named export) can register
31
+ // the tag itself: `WaveformSounds.defineElement()`. Like the core's.
32
+ WaveformSounds.defineElement = defineWaveformSoundsElement;
25
33
 
26
34
  // CDN / <script> usage: a global, like the rest of the family.
27
35
  if (typeof window !== 'undefined') window.WaveformSounds = WaveformSounds;
@@ -30,7 +38,8 @@ export default WaveformSounds;
30
38
  export {
31
39
  WaveformSounds, DEFAULT_OPTIONS, DEFAULT_STRINGS,
32
40
  encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration,
33
- renderSounds, renderSoundsElement,
41
+ renderSounds, renderSoundsElement, RENDER_OPTION_KEYS, pickRenderOptions,
42
+ WaveformSoundsElement, defineWaveformSoundsElement,
34
43
  };
35
44
 
36
45
  // The public types (sounds, options, filter, events), for `import type { ... }`.
@@ -47,4 +56,5 @@ export type {
47
56
  WaveformSoundsStrings,
48
57
  WaveformSoundsOptions,
49
58
  WaveformSoundsEventMap,
59
+ WaveformSoundsInstanceEventMap,
50
60
  } from './types.js';
package/src/js/index.ts CHANGED
@@ -2,20 +2,24 @@
2
2
  * @arraypress/waveform-sounds
3
3
  * A searchable, filterable list of sounds for WaveformPlayer.
4
4
  *
5
- * Importing this entry initialises every `[data-waveform-sounds]` element
6
- * once the DOM is ready. Opt out page-wide with
5
+ * Importing this entry registers `<waveform-sounds>` and initialises every
6
+ * `[data-waveform-sounds]` element once the DOM is ready. Opt out page-wide with
7
7
  * `<html data-waveform-autoinit="false">` (the family's switch), or import
8
8
  * `@arraypress/waveform-sounds/no-autoinit`.
9
9
  *
10
10
  * @author ArrayPress
11
11
  * @license MIT
12
12
  */
13
- import WaveformSounds from './entry.js';
13
+ import WaveformSounds, {defineWaveformSoundsElement} from './entry.js';
14
14
 
15
15
  export * from './entry.js';
16
16
  export default WaveformSounds;
17
17
 
18
18
  if (typeof document !== 'undefined' && document.documentElement?.dataset?.waveformAutoinit !== 'false') {
19
+ // The tag first: an element that upgrades now builds its own list, and
20
+ // the scan then skips it as already claimed. Behind the same opt-out (an
21
+ // opted-out page can call WaveformSounds.defineElement()).
22
+ defineWaveformSoundsElement();
19
23
  if (document.readyState === 'loading') {
20
24
  document.addEventListener('DOMContentLoaded', () => WaveformSounds.init(), {once: true});
21
25
  } else {
@@ -25,7 +25,6 @@ const VOID = new Set(['input', 'br', 'img']);
25
25
  * Escape text for use as a child.
26
26
  *
27
27
  * @param value
28
- * @returns
29
28
  */
30
29
  export function text(value: unknown): string {
31
30
  return escapeHtml(value ?? '');
@@ -52,7 +51,6 @@ export function attrs(map: HtmlAttrs = {}): string {
52
51
  * @param tag
53
52
  * @param attributes
54
53
  * @param children - HTML strings; falsy ones and nested arrays are flattened away.
55
- * @returns
56
54
  */
57
55
  export function h(tag: string, attributes: HtmlAttrs = {}, ...children: HtmlChild[]): string {
58
56
  const open = `<${tag}${attrs(attributes)}>`;