@arraypress/waveform-sounds 2.0.0 → 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 (75) hide show
  1. package/README.md +24 -2
  2. package/dist/waveform-sounds-no-autoinit.esm.js +495 -90
  3. package/dist/waveform-sounds-render.esm.js +55 -5
  4. package/dist/waveform-sounds.css +88 -17
  5. package/dist/waveform-sounds.esm.js +498 -92
  6. package/dist/waveform-sounds.js +494 -92
  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 +88 -17
  11. package/src/js/core/WaveformSounds.ts +350 -87
  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 +0 -5
  15. package/src/js/data/bpm.ts +14 -4
  16. package/src/js/data/navigation.ts +16 -3
  17. package/src/js/data/sounds.ts +44 -14
  18. package/src/js/data/url-state.ts +33 -10
  19. package/src/js/dom/colors.ts +28 -1
  20. package/src/js/dom/draw.ts +0 -1
  21. package/src/js/dom/menus.ts +0 -2
  22. package/src/js/dom/rows.ts +0 -3
  23. package/src/js/entry.ts +13 -3
  24. package/src/js/index.ts +7 -3
  25. package/src/js/render/html.ts +0 -2
  26. package/src/js/render/icons.ts +0 -1
  27. package/src/js/render/markup.ts +41 -13
  28. package/src/js/render/options.ts +26 -4
  29. package/src/js/render/strings.ts +4 -3
  30. package/src/js/render-entry.ts +1 -1
  31. package/src/js/shared/utils.ts +4 -4
  32. package/src/js/types.ts +30 -3
  33. package/types/core/WaveformSounds.d.ts +40 -10
  34. package/types/core/WaveformSounds.d.ts.map +1 -1
  35. package/types/core/element.d.ts +84 -0
  36. package/types/core/element.d.ts.map +1 -0
  37. package/types/core/engine.d.ts +8 -3
  38. package/types/core/engine.d.ts.map +1 -1
  39. package/types/core/options.d.ts +0 -5
  40. package/types/core/options.d.ts.map +1 -1
  41. package/types/data/bpm.d.ts +17 -4
  42. package/types/data/bpm.d.ts.map +1 -1
  43. package/types/data/navigation.d.ts +11 -2
  44. package/types/data/navigation.d.ts.map +1 -1
  45. package/types/data/sounds.d.ts +13 -12
  46. package/types/data/sounds.d.ts.map +1 -1
  47. package/types/data/url-state.d.ts +32 -6
  48. package/types/data/url-state.d.ts.map +1 -1
  49. package/types/dom/colors.d.ts +13 -0
  50. package/types/dom/colors.d.ts.map +1 -1
  51. package/types/dom/draw.d.ts +0 -1
  52. package/types/dom/draw.d.ts.map +1 -1
  53. package/types/dom/menus.d.ts +0 -2
  54. package/types/dom/menus.d.ts.map +1 -1
  55. package/types/dom/rows.d.ts +0 -3
  56. package/types/dom/rows.d.ts.map +1 -1
  57. package/types/entry.d.ts +10 -4
  58. package/types/entry.d.ts.map +1 -1
  59. package/types/index.d.ts +2 -2
  60. package/types/index.d.ts.map +1 -1
  61. package/types/render/html.d.ts +0 -2
  62. package/types/render/html.d.ts.map +1 -1
  63. package/types/render/icons.d.ts.map +1 -1
  64. package/types/render/markup.d.ts +17 -8
  65. package/types/render/markup.d.ts.map +1 -1
  66. package/types/render/options.d.ts +17 -4
  67. package/types/render/options.d.ts.map +1 -1
  68. package/types/render/strings.d.ts +0 -3
  69. package/types/render/strings.d.ts.map +1 -1
  70. package/types/render-entry.d.ts +1 -1
  71. package/types/render-entry.d.ts.map +1 -1
  72. package/types/shared/utils.d.ts +3 -3
  73. package/types/shared/utils.d.ts.map +1 -1
  74. package/types/types.d.ts +29 -3
  75. package/types/types.d.ts.map +1 -1
@@ -0,0 +1,208 @@
1
+ /**
2
+ * The `<waveform-sounds>` custom element, modelled on the core's
3
+ * `<waveform-player>`.
4
+ *
5
+ * A light-DOM wrapper: the element itself is the list's container, so the
6
+ * stylesheet applies as it does to `[data-waveform-sounds]`, server-rendered
7
+ * markup inside it (`renderSounds()` output) is ADOPTED exactly as it is
8
+ * there, and `waveformsounds:*` events bubble from the tag. Configured by
9
+ * attributes — every `data-*` option the list reads, with or without the
10
+ * `data-` prefix (`manifest`, `page-size`, `player`, …), the unprefixed form
11
+ * winning.
12
+ *
13
+ * The default entry registers it (behind the same opt-out as the scan);
14
+ * `/no-autoinit` exports {@link defineWaveformSoundsElement}, and
15
+ * `WaveformSounds.defineElement()` reaches it from a `<script>` page.
16
+ *
17
+ * @module element
18
+ */
19
+
20
+ import {WaveformSounds} from './WaveformSounds.js';
21
+ import {readDataOptions} from './options.js';
22
+ import {LOG} from '../shared/utils.js';
23
+ import type {SoundInput} from '../types.js';
24
+
25
+ declare global {
26
+ interface HTMLElementTagNameMap {
27
+ 'waveform-sounds': WaveformSoundsElement;
28
+ }
29
+ }
30
+
31
+ /**
32
+ * Every `data-*` key `readDataOptions` reads, as its `dataset` name. The
33
+ * element accepts each as `data-<kebab>` and as plain `<kebab>`.
34
+ * `test/runtime/element.test.js` fails if this list and `readDataOptions`
35
+ * drift apart.
36
+ */
37
+ export const ELEMENT_OPTION_KEYS = [
38
+ 'player', 'manifest', 'search', 'filters', 'sorts', 'showCount', 'menuSearch', 'idPrefix', 'urlState',
39
+ 'loopToggle', 'pageSize', 'maxTypeChips', 'columns', 'waveformStyle', 'waveformColor', 'progressColor',
40
+ 'barWidth', 'barGap', 'loop', 'autoAdvance', 'arrowAudition', 'strings', 'playerOptions',
41
+ ];
42
+
43
+ /**
44
+ * `pageSize` → `page-size`.
45
+ *
46
+ * @param key
47
+ */
48
+ const kebab = (key: string): string => key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
49
+
50
+ /**
51
+ * Read the element's options: each key from its plain attribute, else its
52
+ * `data-` one, through the same `readDataOptions` the `data-*` contract uses
53
+ * (so a bare boolean attribute — `<waveform-sounds auto-advance>` — is true,
54
+ * as `data-auto-advance` is).
55
+ *
56
+ * @param el
57
+ * @returns Sparse options.
58
+ */
59
+ export function readElementOptions(el: Element): Record<string, any> {
60
+ const dataset: Record<string, string> = {};
61
+ for (const key of ELEMENT_OPTION_KEYS) {
62
+ const name = kebab(key);
63
+ const value = el.getAttribute(name) ?? el.getAttribute(`data-${name}`);
64
+ if (value != null) dataset[key] = value;
65
+ }
66
+ return readDataOptions({dataset} as unknown as HTMLElement);
67
+ }
68
+
69
+ // Defined on any host: SSR and plain-Node imports have no HTMLElement, and
70
+ // this module must still evaluate there (the class is only ever constructed
71
+ // by a browser's customElements).
72
+ const Base = (typeof HTMLElement === 'undefined' ? class {} : HTMLElement) as typeof HTMLElement;
73
+
74
+ /**
75
+ * `<waveform-sounds manifest="/previews/sounds.json" page-size="20">`.
76
+ *
77
+ * - `connectedCallback` builds the list in the element (adopting
78
+ * server-rendered markup inside it); `disconnectedCallback` destroys it —
79
+ * putting adopted markup back as the server sent it — unless the element
80
+ * is put back before the current task ends (a move keeps the list, and
81
+ * its playback).
82
+ * - Changing an option attribute (either form) rebuilds the list once per
83
+ * task, from the sounds it holds (or from the new `manifest`).
84
+ * - {@link WaveformSoundsElement.sounds} is the `WaveformSounds` instance.
85
+ */
86
+ export class WaveformSoundsElement extends Base {
87
+ /** The list inside this element, or `null` while disconnected. */
88
+ declare sounds: WaveformSounds | null;
89
+ /** @internal A disconnection waiting to see whether the element comes back. */ declare _leaving: ReturnType<typeof setTimeout> | undefined;
90
+ /** @internal Attribute changes batched into one rebuild ('manifest': refetch). */ declare _pending: 'rebuild' | 'manifest' | undefined;
91
+
92
+ /** Every option attribute, plain and `data-` prefixed. */
93
+ static get observedAttributes(): string[] {
94
+ return ELEMENT_OPTION_KEYS.flatMap((key) => [kebab(key), `data-${kebab(key)}`]);
95
+ }
96
+
97
+ /** Build the list (or keep it, after a move). */
98
+ connectedCallback(): void {
99
+ if (this._leaving !== undefined) {
100
+ clearTimeout(this._leaving);
101
+ this._leaving = undefined;
102
+ return;
103
+ }
104
+ if (!this.sounds) this._build();
105
+ }
106
+
107
+ /** Destroy the list, unless the element comes straight back (a move). */
108
+ disconnectedCallback(): void {
109
+ clearTimeout(this._leaving);
110
+ this._leaving = setTimeout(() => {
111
+ this._leaving = undefined;
112
+ if (!this.isConnected) this._teardown();
113
+ }, 0);
114
+ }
115
+
116
+ /**
117
+ * An option attribute changed: rebuild once the task's changes are in.
118
+ *
119
+ * @param name
120
+ * @param previous
121
+ * @param value
122
+ */
123
+ attributeChangedCallback(name: string, previous: string | null, value: string | null): void {
124
+ // Before connection (and during the upgrade of parsed markup) the
125
+ // attributes are simply read by connectedCallback.
126
+ if (!this.sounds || previous === value) return;
127
+ const kind = name.replace(/^data-/, '') === 'manifest' ? 'manifest' : 'rebuild';
128
+ if (this._pending) {
129
+ if (kind === 'manifest') this._pending = kind;
130
+ return;
131
+ }
132
+ this._pending = kind;
133
+ queueMicrotask(() => {
134
+ const pending = this._pending;
135
+ this._pending = undefined;
136
+ if (this.sounds) this._rebuild(pending === 'manifest');
137
+ });
138
+ }
139
+
140
+ /**
141
+ * The options the list reads off this element (`WaveformSounds` calls it
142
+ * in place of reading `data-*` alone).
143
+ * @internal
144
+ */
145
+ _wsOptions(): Record<string, any> {
146
+ return readElementOptions(this);
147
+ }
148
+
149
+ /**
150
+ * Build the list into the element.
151
+ * @internal
152
+ */
153
+ _build(options: {sounds?: SoundInput[]} = {}): void {
154
+ // A declarative scan (`data-waveform-sounds` on this tag) or a script
155
+ // may have built a list here first; the element's own wins.
156
+ WaveformSounds.getInstance(this)?.destroy({restore: true});
157
+ try {
158
+ this.sounds = new WaveformSounds(this, options);
159
+ } catch (error) {
160
+ this.sounds = null;
161
+ console.error(`${LOG} Failed to initialise:`, error, this);
162
+ }
163
+ }
164
+
165
+ /**
166
+ * Destroy the list, putting server-rendered markup back as it came.
167
+ * @internal
168
+ */
169
+ _teardown(): void {
170
+ this.sounds?.destroy({restore: true});
171
+ this.sounds = null;
172
+ }
173
+
174
+ /**
175
+ * Rebuild for new options: re-rendered from the sounds the list holds
176
+ * (the markup must follow the new options), or fetched afresh when the
177
+ * manifest changed.
178
+ * @internal
179
+ */
180
+ _rebuild(refetch: boolean): void {
181
+ // Not built yet (its manifest still loading): there is nothing to
182
+ // keep, so it loads again.
183
+ const sounds = refetch || !this.sounds!.$ ? undefined : (this.sounds!.sounds as SoundInput[]).slice();
184
+ this._teardown();
185
+ this.innerHTML = '';
186
+ this._build(sounds ? {sounds} : {});
187
+ }
188
+ }
189
+
190
+ /**
191
+ * Register the `<waveform-sounds>` element (or the same element under
192
+ * another name). The default entry does this on import; `/no-autoinit`
193
+ * leaves it to you (`WaveformSounds.defineElement()` from a `<script>` page).
194
+ * A name that is already defined is left alone.
195
+ *
196
+ * @param name - Tag name; must contain a hyphen.
197
+ * @returns The registered constructor, or `undefined` outside a browser.
198
+ */
199
+ export function defineWaveformSoundsElement(name: string = 'waveform-sounds'): CustomElementConstructor | undefined {
200
+ if (typeof customElements === 'undefined') return undefined;
201
+ const existing = customElements.get(name);
202
+ if (existing) return existing;
203
+ // A constructor can only be registered once, so each name gets its own
204
+ // subclass (all of them `instanceof WaveformSoundsElement`).
205
+ const element = class extends WaveformSoundsElement {};
206
+ customElements.define(name, element);
207
+ return element;
208
+ }
@@ -67,7 +67,6 @@ export function engineOptions(user: Record<string, any> | null | undefined, layo
67
67
  *
68
68
  * @param sound
69
69
  * @param layout
70
- * @returns
71
70
  */
72
71
  export function enginePeaks(sound: {peaks: number[]|null, waveform: string|null}, layout: 'inline' | 'strip'): number[] | string | null {
73
72
  return (layout === 'strip' && sound.waveform) || sound.peaks || null;
@@ -79,6 +78,7 @@ export interface EngineTrack {
79
78
  autoplay: boolean;
80
79
  duration?: number;
81
80
  downloadUrl?: string;
81
+ preload?: string;
82
82
  }
83
83
 
84
84
  /**
@@ -88,13 +88,19 @@ export interface EngineTrack {
88
88
  * which with `preload: 'none'` is only once it plays — and its download
89
89
  * link, so a `showDownload` engine offers what the row offers.
90
90
  *
91
+ * `preload` is given every time because the core keeps the last one: the
92
+ * strip CUES its first sound with `'none'` (it shows the title, length and
93
+ * peaks from the data, and fetches nothing until it plays), and the next
94
+ * sound played must get the engine's own preload back.
95
+ *
91
96
  * @param sound
92
97
  * @param layout
93
98
  * @param autoplay - Start once loaded (false: cue only).
94
- * @returns
99
+ * @param preload - The media element's `preload` for this sound.
95
100
  */
96
- export function engineTrack(sound: {peaks: number[]|null, waveform: string|null, duration: number|null, download: string|null}, layout: 'inline' | 'strip', autoplay: boolean): EngineTrack {
101
+ export function engineTrack(sound: {peaks: number[]|null, waveform: string|null, duration: number|null, download: string|null}, layout: 'inline' | 'strip', autoplay: boolean, preload?: string): EngineTrack {
97
102
  const track: EngineTrack = {waveform: enginePeaks(sound, layout), autoplay};
103
+ if (preload) track.preload = preload;
98
104
  if (sound.duration != null && sound.duration > 0) track.duration = sound.duration;
99
105
  if (sound.download) track.downloadUrl = sound.download;
100
106
  return track;
@@ -63,7 +63,6 @@ export function parseBool(value: string | undefined): boolean | undefined {
63
63
  * is an empty list (e.g. `data-sorts=""` = no sort menu).
64
64
  *
65
65
  * @param value
66
- * @returns
67
66
  */
68
67
  export function parseList(value: string | undefined): string[] | undefined {
69
68
  if (value == null) return undefined;
@@ -74,7 +73,6 @@ export function parseList(value: string | undefined): string[] | undefined {
74
73
  * A number attribute; an empty string is "not set".
75
74
  *
76
75
  * @param value
77
- * @returns
78
76
  */
79
77
  export function parseNumber(value: string | undefined): number | undefined {
80
78
  return value === undefined || value === '' ? undefined : Number(value);
@@ -85,7 +83,6 @@ export function parseNumber(value: string | undefined): number | undefined {
85
83
  * the parameter prefix.
86
84
  *
87
85
  * @param value
88
- * @returns
89
86
  */
90
87
  export function parseUrlState(value: string | undefined): boolean | string | undefined {
91
88
  if (value === undefined) return undefined;
@@ -100,7 +97,6 @@ export function parseUrlState(value: string | undefined): boolean | string | und
100
97
  *
101
98
  * @param value
102
99
  * @param name - The attribute name, for the warning.
103
- * @returns
104
100
  */
105
101
  export function parseJson(value: string | undefined, name: string): Record<string, any> | undefined {
106
102
  if (!value) return undefined;
@@ -156,7 +152,6 @@ export function readDataOptions(el: HTMLElement): Record<string, any> {
156
152
  * overwrite (an unset prop must not erase a default).
157
153
  *
158
154
  * @param sources
159
- * @returns
160
155
  */
161
156
  export function mergeOptions(...sources: (Record<string, any> | null | undefined)[]): Record<string, any> {
162
157
  const out: Record<string, any> = {};
@@ -10,12 +10,25 @@
10
10
  * @module bpm
11
11
  */
12
12
 
13
+ /**
14
+ * The range the slider spans: the pack's BPMs widened to whole numbers
15
+ * (the handles step by 1, so a pack whose fastest loop is 128.5 BPM needs
16
+ * an end at 129, or the top handle could never reach it). A pack of whole
17
+ * BPMs is unchanged.
18
+ *
19
+ * @param range - The pack's BPM range (`facets().bpm`).
20
+ * @returns The slider's ends, or null when the pack has no BPMs.
21
+ */
22
+ export function bpmExtent(range: {min: number, max: number} | null | undefined): {min: number, max: number} | null {
23
+ return range ? {min: Math.floor(range.min), max: Math.ceil(range.max)} : null;
24
+ }
25
+
13
26
  /**
14
27
  * The filter for a pair of handle positions.
15
28
  *
16
29
  * @param lo - The lower handle.
17
30
  * @param hi - The upper handle.
18
- * @param extent - The pack's BPM range (`facets().bpm`).
31
+ * @param extent - The slider's range ({@link bpmExtent}).
19
32
  * @returns `''` for an open end.
20
33
  */
21
34
  export function bpmFilterFromRange(lo: number, hi: number, extent: {min: number, max: number}): {bpmMin: string, bpmMax: string} {
@@ -33,7 +46,6 @@ export function bpmFilterFromRange(lo: number, hi: number, extent: {min: number,
33
46
  *
34
47
  * @param filter
35
48
  * @param extent
36
- * @returns
37
49
  */
38
50
  export function bpmRangeFromFilter(filter: {bpmMin?: string|number, bpmMax?: string|number}, extent: {min: number, max: number}): {lo: number, hi: number} {
39
51
  const read = (v: string | number | undefined, fallback: number): number => {
@@ -50,7 +62,6 @@ export function bpmRangeFromFilter(filter: {bpmMin?: string|number, bpmMax?: str
50
62
  *
51
63
  * @param value
52
64
  * @param extent
53
- * @returns
54
65
  */
55
66
  export function bpmFraction(value: number, extent: {min: number, max: number}): number {
56
67
  const span = extent.max - extent.min;
@@ -61,7 +72,6 @@ export function bpmFraction(value: number, extent: {min: number, max: number}):
61
72
  * Is a BPM limit set on either side?
62
73
  *
63
74
  * @param filter
64
- * @returns
65
75
  */
66
76
  export function hasBpmFilter(filter: {bpmMin?: string|number, bpmMax?: string|number}): boolean {
67
77
  return (filter.bpmMin != null && filter.bpmMin !== '') || (filter.bpmMax != null && filter.bpmMax !== '');
@@ -43,7 +43,22 @@ export function rowTarget(key: string, at: number, count: number): number | 'sea
43
43
  */
44
44
  export function seekTarget(progress: number, key: string): number | null {
45
45
  if (key !== 'ArrowRight' && key !== 'ArrowLeft') return null;
46
- return clamp(progress + (key === 'ArrowRight' ? SEEK_STEP : -SEEK_STEP), 0, 0.999);
46
+ return clamp(progress + (key === 'ArrowRight' ? SEEK_STEP : -SEEK_STEP), 0, SEEK_END);
47
+ }
48
+
49
+ /** Where End seeks on a slider: just short of the end, so it can't end
50
+ * the sound (and with it auto-advance) by accident. */
51
+ export const SEEK_END = 0.999;
52
+
53
+ /**
54
+ * The position Home / End seek to on a row's seek slider (the ARIA slider
55
+ * pattern: they go to the minimum / maximum, not to the first / last row).
56
+ *
57
+ * @param key - `KeyboardEvent.key`.
58
+ * @returns 0 for Home, {@link SEEK_END} for End, else null.
59
+ */
60
+ export function sliderEdgeTarget(key: string): number | null {
61
+ return key === 'Home' ? 0 : key === 'End' ? SEEK_END : null;
47
62
  }
48
63
 
49
64
  /**
@@ -53,7 +68,6 @@ export function seekTarget(progress: number, key: string): number | null {
53
68
  * @template T
54
69
  * @param shown - The sounds that match, in display order.
55
70
  * @param limit - How many to show (Infinity for all).
56
- * @returns
57
71
  */
58
72
  export function pageWindow<T>(shown: T[], limit: number): {visible: Set<T>, remaining: number} {
59
73
  const visible = new Set(shown.slice(0, limit));
@@ -66,7 +80,6 @@ export function pageWindow<T>(shown: T[], limit: number): {visible: Set<T>, rema
66
80
  *
67
81
  * @param limit - The current limit.
68
82
  * @param pos - The position that must be visible.
69
- * @returns
70
83
  */
71
84
  export function limitToReveal(limit: number, pos: number): number {
72
85
  return pos >= limit ? pos + 1 : limit;
@@ -29,12 +29,36 @@ export function encodePeaks(peaks: number[]): string {
29
29
  return out;
30
30
  }
31
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
+
32
54
  /**
33
55
  * Decode peaks from any accepted form into numbers 0..1.
34
56
  *
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`.
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.
38
62
  *
39
63
  * @param value
40
64
  * @param scale - The maximum of an integer array.
@@ -43,9 +67,10 @@ export function encodePeaks(peaks: number[]): string {
43
67
  export function decodePeaks(value: string | number[] | null | undefined, scale: number = 1): number[] | null {
44
68
  if (value == null || value === '') return null;
45
69
  if (typeof value === 'string') {
70
+ if (value.startsWith(COMPACT_PREFIX)) return decodeCompact(value.slice(COMPACT_PREFIX.length));
46
71
  if (!/^[0-9a-f]+$/i.test(value) || value.length % 2) return null;
47
72
  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;
73
+ for (let i = 0; i < out.length; i++) out[i] = parseInt(value.slice(i * 2, i * 2 + 2), 16) / 255;
49
74
  return out;
50
75
  }
51
76
  if (!Array.isArray(value)) return null;
@@ -109,18 +134,31 @@ export function formatDuration(seconds: number | null | undefined): string {
109
134
  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
110
135
  }
111
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
+
112
150
  /**
113
151
  * Parse a duration given as seconds (8.02) or as "m:ss" / "h:mm:ss".
114
152
  * @param value
115
- * @returns
116
153
  */
117
154
  export function parseDuration(value: number | string | null | undefined): number | null {
118
155
  if (value == null || value === '') return null;
119
156
  if (typeof value === 'number') return Number.isFinite(value) && value >= 0 ? value : null;
120
157
  const str = String(value).trim();
121
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;
122
161
  const parts = str.split(':').map(Number);
123
- if (parts.length < 2 || parts.some((n) => !Number.isFinite(n))) return null;
124
162
  return parts.reduce((acc, n) => acc * 60 + n, 0);
125
163
  }
126
164
 
@@ -129,7 +167,6 @@ export function parseDuration(value: number | string | null | undefined): number
129
167
  * leading pack prefixes kept (they are often the label's code).
130
168
  * "NW_Bass_Loop_04_128_Fmin.wav" → "NW Bass Loop 04 128 Fmin".
131
169
  * @param url
132
- * @returns
133
170
  */
134
171
  export function titleFromUrl(url: string): string {
135
172
  const file = String(url || '').split(/[?#]/)[0].split('/').pop() || '';
@@ -183,7 +220,6 @@ export const LOOP_FILTERS = ['loop', 'one-shot'];
183
220
  * as an attribute or a CSV-ish manifest writes it. Unset is a one-shot.
184
221
  *
185
222
  * @param value
186
- * @returns
187
223
  */
188
224
  export function isLoop(value: unknown): boolean {
189
225
  return value === true || value === 1 || value === 'true' || value === '1';
@@ -195,7 +231,6 @@ export function isLoop(value: unknown): boolean {
195
231
  * Sounds without a url are dropped.
196
232
  *
197
233
  * @param manifest
198
- * @returns
199
234
  */
200
235
  export function parseManifest(manifest: SoundsManifest | SoundInput[]): Sound[] {
201
236
  const list = Array.isArray(manifest) ? manifest : Array.isArray(manifest?.sounds) ? manifest.sounds : [];
@@ -208,7 +243,6 @@ export function parseManifest(manifest: SoundsManifest | SoundInput[]): Sound[]
208
243
  * (a repeated id would make two rows answer to one play() call).
209
244
  * @param list
210
245
  * @param peakScale
211
- * @returns
212
246
  */
213
247
  export function normalizeSounds(list: SoundInput[], peakScale: number = 1): Sound[] {
214
248
  const seen = new Set<string>();
@@ -232,7 +266,6 @@ export function normalizeSounds(list: SoundInput[], peakScale: number = 1): Soun
232
266
  * offer is not rendered.
233
267
  *
234
268
  * @param sounds
235
- * @returns
236
269
  */
237
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} {
238
271
  const types = new Map<string, number>();
@@ -267,7 +300,6 @@ export function facets(sounds: Sound[]): {types: {name: string, count: number}[]
267
300
  *
268
301
  * @param sound
269
302
  * @param filter
270
- * @returns
271
303
  */
272
304
  export function matches(sound: Sound, filter: Partial<SoundsFilter> = {}): boolean {
273
305
  if (filter.type && sound.type !== filter.type) return false;
@@ -312,7 +344,6 @@ const SORT_NEEDS: Record<string, (f: ReturnType<typeof facets>) => boolean> = {
312
344
  *
313
345
  * @param sorts - The configured orders.
314
346
  * @param f - The sounds' facets.
315
- * @returns
316
347
  */
317
348
  export function availableSorts(sorts: string[], f: ReturnType<typeof facets>): string[] {
318
349
  return sorts.filter((sort) => SORT_NEEDS[sort]?.(f));
@@ -324,7 +355,6 @@ export function availableSorts(sorts: string[], f: ReturnType<typeof facets>): s
324
355
  *
325
356
  * @param sounds
326
357
  * @param by
327
- * @returns
328
358
  */
329
359
  export function sortSounds(sounds: Sound[], by: SoundsSort = 'default'): Sound[] {
330
360
  const list = sounds.map((s, i) => ({s, i}));
@@ -18,7 +18,6 @@ import type {SoundsFilter, SoundsLoopFilter} from '../types.js';
18
18
  * page don't share a filter.
19
19
  *
20
20
  * @param urlState
21
- * @returns
22
21
  */
23
22
  export function urlKeys(urlState: boolean | string | null | undefined): {q: string, type: string, key: string, bpm: string, loop: string, sort: string} | null {
24
23
  if (!urlState) return null;
@@ -27,14 +26,35 @@ export function urlKeys(urlState: boolean | string | null | undefined): {q: stri
27
26
  }
28
27
 
29
28
  /**
30
- * A BPM range parameter: "120-130", "120-" or "-130".
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.
31
32
  *
32
33
  * @param value
33
34
  * @returns null if malformed.
34
35
  */
35
36
  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;
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;
38
58
  }
39
59
 
40
60
  /**
@@ -42,7 +62,6 @@ export function parseBpmRange(value: string | null | undefined): {bpmMin: string
42
62
  *
43
63
  * @param min
44
64
  * @param max
45
- * @returns
46
65
  */
47
66
  export function formatBpmRange(min: string | number | null | undefined, max: string | number | null | undefined): string {
48
67
  const lo = min ?? '', hi = max ?? '';
@@ -51,18 +70,20 @@ export function formatBpmRange(min: string | number | null | undefined, max: str
51
70
 
52
71
  /**
53
72
  * 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)
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)
56
76
  * are ignored, never applied: a stale link shows the whole list, not an
57
77
  * empty one.
58
78
  *
59
79
  * @param search - `location.search`.
60
80
  * @param keys
61
- * @param available - From `facets()`.
81
+ * @param available - From `facets()`, with `bpm` as the slider's range
82
+ * (`bpmExtent()`).
62
83
  * @param sorts - The sort orders offered.
63
84
  * @returns A filter patch, and the sort (or null).
64
85
  */
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} {
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} {
66
87
  const out: {filter: Partial<SoundsFilter>, sort: string | null} = {filter: {}, sort: null};
67
88
  if (!keys) return out;
68
89
  const sp = new URLSearchParams(search);
@@ -72,7 +93,9 @@ export function readUrlState(search: string, keys: ReturnType<typeof urlKeys>, a
72
93
  if (type && available.types.some((t) => t.name === type)) out.filter.type = type;
73
94
  const key = normalizeKey(sp.get(keys.key));
74
95
  if (key && available.keys.includes(key)) out.filter.key = key;
75
- const bpm = parseBpmRange(sp.get(keys.bpm));
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;
76
99
  if (bpm) Object.assign(out.filter, bpm);
77
100
  const loop = sp.get(keys.loop);
78
101
  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;
@@ -58,7 +58,6 @@ export function resample(peaks: number[], count: number) {
58
58
  * @param width - Canvas width (CSS px).
59
59
  * @param height - Canvas height (CSS px).
60
60
  * @param o
61
- * @returns
62
61
  */
63
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;