@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
@@ -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
+ }
@@ -0,0 +1,107 @@
1
+ /**
2
+ * The audio engine: ONE `WaveformPlayer` (self mode) that every sound in
3
+ * the list plays through. These helpers decide how it's configured and
4
+ * what it's given per sound; `WaveformSounds.js` owns its lifecycle.
5
+ *
6
+ * @module engine
7
+ */
8
+
9
+ /** The engine's own callbacks, which the list must always receive. */
10
+ const CALLBACKS = ['onLoad', 'onPlay', 'onPause', 'onEnd', 'onTimeUpdate', 'onError'];
11
+
12
+ /**
13
+ * Player options that describe ONE track. The engine plays every sound in
14
+ * the list, so a site value would be wrong for all but one of them; the
15
+ * list passes each sound's own to `loadTrack()` instead (and the core resets
16
+ * them on every `loadTrack()` that doesn't).
17
+ */
18
+ const PER_TRACK = ['duration', 'downloadUrl', 'downloadName'];
19
+
20
+ /**
21
+ * The engine player's options. The site's `playerOptions` override the
22
+ * defaults, except what the list depends on:
23
+ * - `audioMode` is always `'self'` (the list owns its audio);
24
+ * - `loop` and `showLoop` are always off: the list owns looping (its Loop
25
+ * toggle, which repeats only the sounds marked as loops). The player's
26
+ * own loop would stop `ended`, so `autoAdvance` and the row state would
27
+ * stall, and its toggle would loop one-shots behind the list's back;
28
+ * - the per-track options (`duration`, `downloadUrl`, `downloadName`) are
29
+ * dropped: each sound's come with it (see {@link engineTrack});
30
+ * - the six callbacks always reach the list — a site's own callback of
31
+ * the same name runs as well, after it, with the same arguments.
32
+ *
33
+ * @param user - The site's `playerOptions`.
34
+ * @param layout - Strip shows the engine, so it's taller.
35
+ * @param handlers - The list's callbacks, keyed by
36
+ * option name (`onPlay`, …).
37
+ * @returns Options for `new WaveformPlayer(el, options)`.
38
+ */
39
+ export function engineOptions(user: Record<string, any> | null | undefined, layout: 'inline' | 'strip', handlers: Record<string, (...args: any[]) => void>): Record<string, any> {
40
+ const site = user || {};
41
+ const strip = layout === 'strip';
42
+ const options: Record<string, any> = {
43
+ height: strip ? 48 : 32,
44
+ waveformStyle: strip ? 'mirror' : 'bars',
45
+ preload: 'metadata',
46
+ singlePlay: true,
47
+ ...site,
48
+ audioMode: 'self',
49
+ loop: false,
50
+ showLoop: false,
51
+ };
52
+ for (const name of PER_TRACK) delete options[name];
53
+ for (const name of CALLBACKS) {
54
+ options[name] = (...args: any[]) => {
55
+ handlers[name]?.(...args);
56
+ if (typeof site[name] === 'function') site[name](...args);
57
+ };
58
+ }
59
+ return options;
60
+ }
61
+
62
+ /**
63
+ * The waveform data to hand the engine for a sound: in the strip a
64
+ * full-resolution sidecar when there is one, otherwise the row's peaks.
65
+ * Supplied peaks also stop a hidden engine from downloading and decoding
66
+ * the whole file just to draw it.
67
+ *
68
+ * @param sound
69
+ * @param layout
70
+ */
71
+ export function enginePeaks(sound: {peaks: number[]|null, waveform: string|null}, layout: 'inline' | 'strip'): number[] | string | null {
72
+ return (layout === 'strip' && sound.waveform) || sound.peaks || null;
73
+ }
74
+
75
+ /** What `loadTrack()` is given for one sound (see {@link engineTrack}). */
76
+ export interface EngineTrack {
77
+ waveform: number[] | string | null;
78
+ autoplay: boolean;
79
+ duration?: number;
80
+ downloadUrl?: string;
81
+ preload?: string;
82
+ }
83
+
84
+ /**
85
+ * The `loadTrack()` options for a sound: its peaks (see {@link enginePeaks}),
86
+ * its known length — so the player shows the right total, places a seek and
87
+ * fills the Media Session scrubber before the audio's metadata arrives,
88
+ * which with `preload: 'none'` is only once it plays — and its download
89
+ * link, so a `showDownload` engine offers what the row offers.
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
+ *
96
+ * @param sound
97
+ * @param layout
98
+ * @param autoplay - Start once loaded (false: cue only).
99
+ * @param preload - The media element's `preload` for this sound.
100
+ */
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 {
102
+ const track: EngineTrack = {waveform: enginePeaks(sound, layout), autoplay};
103
+ if (preload) track.preload = preload;
104
+ if (sound.duration != null && sound.duration > 0) track.duration = sound.duration;
105
+ if (sound.download) track.downloadUrl = sound.download;
106
+ return track;
107
+ }
@@ -2,8 +2,10 @@
2
2
  * The runtime's option surface: every option with its default, the
3
3
  * `data-*` form a container (or a server-rendering wrapper) uses, and the
4
4
  * merge that resolves them. The options that shape the markup are defined
5
- * with the renderer (`render/options.js`) and included here. `index.d.ts` documents each option; the wrappers' drift
6
- * guards compare their forwarding against `DEFAULT_OPTIONS`.
5
+ * with the renderer (`render/options.ts`) and included here. `types.ts`
6
+ * documents each option; the wrappers' drift guards compare their
7
+ * forwarding against `WaveformSoundsOptions` (in the generated
8
+ * `types/types.d.ts`).
7
9
  *
8
10
  * Precedence, as across the waveform family: data-* > constructor > default.
9
11
  *
@@ -12,11 +14,12 @@
12
14
 
13
15
  import {RENDER_DEFAULTS} from '../render/options.js';
14
16
  import {LOG} from '../shared/utils.js';
17
+ import type {WaveformSoundsOptions} from '../types.js';
15
18
 
16
19
  export {RENDER_DEFAULTS};
17
20
 
18
21
  /** Every option, with its default. */
19
- export const DEFAULT_OPTIONS = {
22
+ export const DEFAULT_OPTIONS: WaveformSoundsOptions = {
20
23
  ...RENDER_DEFAULTS,
21
24
  sounds: null,
22
25
  manifest: null,
@@ -28,7 +31,9 @@ export const DEFAULT_OPTIONS = {
28
31
  loop: null,
29
32
  autoAdvance: false,
30
33
  arrowAudition: true,
31
- idPrefix: null,
34
+ // null is "unset" (the container's id, else a hash); the public type,
35
+ // unchanged from 0.3.1, has no null, hence the cast (it emits nothing).
36
+ idPrefix: null as unknown as string,
32
37
  urlState: false,
33
38
  playerOptions: null,
34
39
  playerClass: null,
@@ -44,10 +49,10 @@ export const DEFAULT_OPTIONS = {
44
49
  /**
45
50
  * A boolean attribute: present-and-empty or "true" → true, "false" → false.
46
51
  *
47
- * @param {string|undefined} value
48
- * @returns {boolean|undefined} undefined for anything else (not set).
52
+ * @param value
53
+ * @returns undefined for anything else (not set).
49
54
  */
50
- export function parseBool(value) {
55
+ export function parseBool(value: string | undefined): boolean | undefined {
51
56
  if (value === '' || value === 'true') return true;
52
57
  if (value === 'false') return false;
53
58
  return undefined;
@@ -57,10 +62,9 @@ export function parseBool(value) {
57
62
  * A comma list attribute ("type, key" → ['type', 'key']). An empty string
58
63
  * is an empty list (e.g. `data-sorts=""` = no sort menu).
59
64
  *
60
- * @param {string|undefined} value
61
- * @returns {string[]|undefined}
65
+ * @param value
62
66
  */
63
- export function parseList(value) {
67
+ export function parseList(value: string | undefined): string[] | undefined {
64
68
  if (value == null) return undefined;
65
69
  return value.split(',').map((x) => x.trim()).filter(Boolean);
66
70
  }
@@ -68,10 +72,9 @@ export function parseList(value) {
68
72
  /**
69
73
  * A number attribute; an empty string is "not set".
70
74
  *
71
- * @param {string|undefined} value
72
- * @returns {number|undefined}
75
+ * @param value
73
76
  */
74
- export function parseNumber(value) {
77
+ export function parseNumber(value: string | undefined): number | undefined {
75
78
  return value === undefined || value === '' ? undefined : Number(value);
76
79
  }
77
80
 
@@ -79,10 +82,9 @@ export function parseNumber(value) {
79
82
  * `data-url-state`: "true"/empty → true, "false" → false, anything else is
80
83
  * the parameter prefix.
81
84
  *
82
- * @param {string|undefined} value
83
- * @returns {boolean|string|undefined}
85
+ * @param value
84
86
  */
85
- export function parseUrlState(value) {
87
+ export function parseUrlState(value: string | undefined): boolean | string | undefined {
86
88
  if (value === undefined) return undefined;
87
89
  const b = parseBool(value);
88
90
  return b === undefined ? value : b;
@@ -93,11 +95,10 @@ export function parseUrlState(value) {
93
95
  * reported and ignored, never thrown: a typo in markup must not take the
94
96
  * whole list down.
95
97
  *
96
- * @param {string|undefined} value
97
- * @param {string} name - The attribute name, for the warning.
98
- * @returns {Object|undefined}
98
+ * @param value
99
+ * @param name - The attribute name, for the warning.
99
100
  */
100
- export function parseJson(value, name) {
101
+ export function parseJson(value: string | undefined, name: string): Record<string, any> | undefined {
101
102
  if (!value) return undefined;
102
103
  try {
103
104
  return JSON.parse(value);
@@ -112,12 +113,12 @@ export function parseJson(value, name) {
112
113
  * `data-page-size` → `pageSize`). Attributes that are absent (or unusable)
113
114
  * are left out, so they never override a constructor option.
114
115
  *
115
- * @param {HTMLElement} el
116
- * @returns {Object} The options found.
116
+ * @param el
117
+ * @returns The options found.
117
118
  */
118
- export function readDataOptions(el) {
119
+ export function readDataOptions(el: HTMLElement): Record<string, any> {
119
120
  const d = el.dataset || {};
120
- const out = {
121
+ const out: Record<string, any> = {
121
122
  player: d.player || undefined,
122
123
  manifest: d.manifest || undefined,
123
124
  search: parseBool(d.search),
@@ -150,11 +151,10 @@ export function readDataOptions(el) {
150
151
  * Merge option sources: later ones win, and null/undefined never
151
152
  * overwrite (an unset prop must not erase a default).
152
153
  *
153
- * @param {...(Object|null|undefined)} sources
154
- * @returns {Object}
154
+ * @param sources
155
155
  */
156
- export function mergeOptions(...sources) {
157
- const out = {};
156
+ export function mergeOptions(...sources: (Record<string, any> | null | undefined)[]): Record<string, any> {
157
+ const out: Record<string, any> = {};
158
158
  for (const src of sources) {
159
159
  if (!src) continue;
160
160
  for (const k in src) if (src[k] !== null && src[k] !== undefined) out[k] = src[k];
@@ -10,15 +10,28 @@
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
- * @param {number} lo - The lower handle.
17
- * @param {number} hi - The upper handle.
18
- * @param {{min: number, max: number}} extent - The pack's BPM range (`facets().bpm`).
19
- * @returns {{bpmMin: string, bpmMax: string}} `''` for an open end.
29
+ * @param lo - The lower handle.
30
+ * @param hi - The upper handle.
31
+ * @param extent - The slider's range ({@link bpmExtent}).
32
+ * @returns `''` for an open end.
20
33
  */
21
- export function bpmFilterFromRange(lo, hi, extent) {
34
+ export function bpmFilterFromRange(lo: number, hi: number, extent: {min: number, max: number}): {bpmMin: string, bpmMax: string} {
22
35
  const a = Math.min(lo, hi), b = Math.max(lo, hi);
23
36
  return {
24
37
  bpmMin: a > extent.min ? String(a) : '',
@@ -31,12 +44,11 @@ export function bpmFilterFromRange(lo, hi, extent) {
31
44
  * set one at its value (clamped into the pack's range, so a link with
32
45
  * `?bpm=60-300` still shows sensible handles).
33
46
  *
34
- * @param {{bpmMin?: string|number, bpmMax?: string|number}} filter
35
- * @param {{min: number, max: number}} extent
36
- * @returns {{lo: number, hi: number}}
47
+ * @param filter
48
+ * @param extent
37
49
  */
38
- export function bpmRangeFromFilter(filter, extent) {
39
- const read = (v, fallback) => {
50
+ export function bpmRangeFromFilter(filter: {bpmMin?: string|number, bpmMax?: string|number}, extent: {min: number, max: number}): {lo: number, hi: number} {
51
+ const read = (v: string | number | undefined, fallback: number): number => {
40
52
  const n = Number(v);
41
53
  return v === '' || v == null || !Number.isFinite(n) ? fallback : Math.min(Math.max(n, extent.min), extent.max);
42
54
  };
@@ -48,11 +60,10 @@ export function bpmRangeFromFilter(filter, extent) {
48
60
  /**
49
61
  * A handle's position along the track, 0..1.
50
62
  *
51
- * @param {number} value
52
- * @param {{min: number, max: number}} extent
53
- * @returns {number}
63
+ * @param value
64
+ * @param extent
54
65
  */
55
- export function bpmFraction(value, extent) {
66
+ export function bpmFraction(value: number, extent: {min: number, max: number}): number {
56
67
  const span = extent.max - extent.min;
57
68
  return span > 0 ? Math.min(Math.max((value - extent.min) / span, 0), 1) : 0;
58
69
  }
@@ -60,9 +71,8 @@ export function bpmFraction(value, extent) {
60
71
  /**
61
72
  * Is a BPM limit set on either side?
62
73
  *
63
- * @param {{bpmMin?: string|number, bpmMax?: string|number}} filter
64
- * @returns {boolean}
74
+ * @param filter
65
75
  */
66
- export function hasBpmFilter(filter) {
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 !== '');
68
78
  }
@@ -15,14 +15,14 @@ export const SEEK_STEP = 0.1;
15
15
  * Where a navigation key moves from position `at` in a list of `count`
16
16
  * visible rows.
17
17
  *
18
- * @param {string} key - `KeyboardEvent.key`.
19
- * @param {number} at - The focused row's position among the visible rows.
20
- * @param {number} count - How many rows are visible.
21
- * @returns {number|'search'|null} The new position; `'search'` for ↑ on
18
+ * @param key - `KeyboardEvent.key`.
19
+ * @param at - The focused row's position among the visible rows.
20
+ * @param count - How many rows are visible.
21
+ * @returns The new position; `'search'` for ↑ on
22
22
  * the first row (back to the search field); null when the key isn't a
23
23
  * move or there is nowhere to go.
24
24
  */
25
- export function rowTarget(key, at, count) {
25
+ export function rowTarget(key: string, at: number, count: number): number | 'search' | null {
26
26
  if (!count) return null;
27
27
  switch (key) {
28
28
  case 'ArrowDown': return at + 1 < count ? at + 1 : null;
@@ -37,13 +37,28 @@ export function rowTarget(key, at, count) {
37
37
  * The position an ←/→ press seeks to. Stops just short of the end, so a
38
38
  * held → can't end the sound by accident.
39
39
  *
40
- * @param {number} progress - Current position, 0..1.
41
- * @param {string} key - `'ArrowRight'` or `'ArrowLeft'`.
42
- * @returns {number|null} The new position, or null for any other key.
40
+ * @param progress - Current position, 0..1.
41
+ * @param key - `'ArrowRight'` or `'ArrowLeft'`.
42
+ * @returns The new position, or null for any other key.
43
43
  */
44
- export function seekTarget(progress, key) {
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
  /**
@@ -51,11 +66,10 @@ export function seekTarget(progress, key) {
51
66
  * "Show more" would reveal.
52
67
  *
53
68
  * @template T
54
- * @param {T[]} shown - The sounds that match, in display order.
55
- * @param {number} limit - How many to show (Infinity for all).
56
- * @returns {{visible: Set<T>, remaining: number}}
69
+ * @param shown - The sounds that match, in display order.
70
+ * @param limit - How many to show (Infinity for all).
57
71
  */
58
- export function pageWindow(shown, limit) {
72
+ export function pageWindow<T>(shown: T[], limit: number): {visible: Set<T>, remaining: number} {
59
73
  const visible = new Set(shown.slice(0, limit));
60
74
  return {visible, remaining: shown.length - visible.size};
61
75
  }
@@ -64,10 +78,9 @@ export function pageWindow(shown, limit) {
64
78
  * The page limit that reveals position `pos` (used when playing past the
65
79
  * end of the current page, e.g. by `next()` or auto-advance).
66
80
  *
67
- * @param {number} limit - The current limit.
68
- * @param {number} pos - The position that must be visible.
69
- * @returns {number}
81
+ * @param limit - The current limit.
82
+ * @param pos - The position that must be visible.
70
83
  */
71
- export function limitToReveal(limit, pos) {
84
+ export function limitToReveal(limit: number, pos: number): number {
72
85
  return pos >= limit ? pos + 1 : limit;
73
86
  }