@arraypress/waveform-sounds 0.3.1 → 2.0.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 (81) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +19 -1
  3. package/dist/waveform-sounds-no-autoinit.esm.js +121 -97
  4. package/dist/waveform-sounds-render.esm.js +24 -10
  5. package/dist/waveform-sounds.css +62 -76
  6. package/dist/waveform-sounds.esm.js +122 -98
  7. package/dist/waveform-sounds.js +123 -98
  8. package/dist/waveform-sounds.min.css +1 -1
  9. package/dist/waveform-sounds.min.js +1 -1
  10. package/package.json +36 -33
  11. package/src/css/waveform-sounds.css +62 -76
  12. package/src/js/core/{WaveformSounds.js → WaveformSounds.ts} +301 -191
  13. package/src/js/core/engine.ts +101 -0
  14. package/src/js/core/{options.js → options.ts} +33 -28
  15. package/src/js/data/{bpm.js → bpm.ts} +17 -17
  16. package/src/js/data/{navigation.js → navigation.ts} +17 -17
  17. package/src/js/data/{sounds.js → sounds.ts} +62 -61
  18. package/src/js/data/{url-state.js → url-state.ts} +27 -26
  19. package/src/js/dom/{colors.js → colors.ts} +12 -12
  20. package/src/js/dom/{draw.js → draw.ts} +17 -17
  21. package/src/js/dom/{menus.js → menus.ts} +72 -55
  22. package/src/js/dom/{rows.js → rows.ts} +18 -17
  23. package/src/js/{entry.js → entry.ts} +25 -0
  24. package/src/js/render/{html.js → html.ts} +18 -12
  25. package/src/js/render/{icons.js → icons.ts} +4 -4
  26. package/src/js/render/{markup.js → markup.ts} +82 -60
  27. package/src/js/render/{options.js → options.ts} +26 -20
  28. package/src/js/render/{strings.js → strings.ts} +17 -16
  29. package/src/js/{render-entry.js → render-entry.ts} +1 -0
  30. package/src/js/shared/{utils.js → utils.ts} +22 -22
  31. package/{index.d.ts → src/js/types.ts} +12 -87
  32. package/types/core/WaveformSounds.d.ts +145 -0
  33. package/types/core/WaveformSounds.d.ts.map +1 -0
  34. package/types/core/engine.d.ts +67 -0
  35. package/types/core/engine.d.ts.map +1 -0
  36. package/types/core/options.d.ts +76 -0
  37. package/types/core/options.d.ts.map +1 -0
  38. package/types/data/bpm.d.ts +67 -0
  39. package/types/data/bpm.d.ts.map +1 -0
  40. package/types/data/navigation.d.ts +53 -0
  41. package/types/data/navigation.d.ts.map +1 -0
  42. package/types/data/sounds.d.ts +167 -0
  43. package/types/data/sounds.d.ts.map +1 -0
  44. package/types/data/url-state.d.ts +83 -0
  45. package/types/data/url-state.d.ts.map +1 -0
  46. package/types/dom/colors.d.ts +35 -0
  47. package/types/dom/colors.d.ts.map +1 -0
  48. package/types/dom/draw.d.ts +73 -0
  49. package/types/dom/draw.d.ts.map +1 -0
  50. package/types/dom/menus.d.ts +77 -0
  51. package/types/dom/menus.d.ts.map +1 -0
  52. package/types/dom/rows.d.ts +42 -0
  53. package/types/dom/rows.d.ts.map +1 -0
  54. package/types/entry.d.ts +22 -0
  55. package/types/entry.d.ts.map +1 -0
  56. package/types/index.d.ts +16 -0
  57. package/types/index.d.ts.map +1 -0
  58. package/types/render/html.d.ts +39 -0
  59. package/types/render/html.d.ts.map +1 -0
  60. package/types/render/icons.d.ts +17 -0
  61. package/types/render/icons.d.ts.map +1 -0
  62. package/types/render/markup.d.ts +132 -0
  63. package/types/render/markup.d.ts.map +1 -0
  64. package/types/render/options.d.ts +56 -0
  65. package/types/render/options.d.ts.map +1 -0
  66. package/types/render/strings.d.ts +46 -0
  67. package/types/render/strings.d.ts.map +1 -0
  68. package/types/render-entry.d.ts +8 -0
  69. package/types/render-entry.d.ts.map +1 -0
  70. package/types/shared/utils.d.ts +57 -0
  71. package/types/shared/utils.d.ts.map +1 -0
  72. package/types/types.d.ts +254 -0
  73. package/types/types.d.ts.map +1 -0
  74. package/types/vendor/arraypress-text.d.ts +250 -0
  75. package/dist/waveform-sounds-no-autoinit.cjs +0 -2159
  76. package/dist/waveform-sounds-render.cjs +0 -614
  77. package/dist/waveform-sounds.cjs +0 -2181
  78. package/no-autoinit.d.ts +0 -2
  79. package/render.d.ts +0 -5
  80. package/src/js/core/engine.js +0 -57
  81. /package/src/js/{index.js → index.ts} +0 -0
@@ -28,7 +28,7 @@
28
28
 
29
29
  import {availableSorts, facets, matches, normalizeSounds, parseManifest, sortSounds, SORTS} from '../data/sounds.js';
30
30
  import {drawRowWaveform, resample} from '../dom/draw.js';
31
- import {engineOptions, enginePeaks} from './engine.js';
31
+ import {engineOptions, engineTrack} from './engine.js';
32
32
  import {Menus} from '../dom/menus.js';
33
33
  import {limitToReveal, pageWindow, rowTarget, seekTarget} from '../data/navigation.js';
34
34
  import {DEFAULT_OPTIONS, mergeOptions, readDataOptions} from './options.js';
@@ -40,11 +40,53 @@ import {bpmFilterFromRange, bpmFraction, bpmRangeFromFilter} from '../data/bpm.j
40
40
  import {pageSurface, resolveCssColor} from '../dom/colors.js';
41
41
  import {readUrlState, urlKeys, writeUrlState} from '../data/url-state.js';
42
42
  import {emit, isTyping, LOG, pointerFraction} from '../shared/utils.js';
43
+ import type {decodePeaks, encodePeaks, formatDuration, normalizeKey} from '../data/sounds.js';
44
+ import type {EngineTrack} from './engine.js';
45
+ import type {RenderOptions} from '../render/options.js';
46
+ import type {Sound, SoundInput, SoundsFilter, SoundsLoopFilter, SoundsSort, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
47
+
48
+ /** The engine `WaveformPlayer`, as far as the list uses it. */
49
+ interface Engine {
50
+ audio: HTMLAudioElement | null;
51
+ waveformData: number[];
52
+ play(): unknown;
53
+ pause(): unknown;
54
+ seekTo(seconds: number): unknown;
55
+ loadTrack(url: string, title: string, artist: string | null, options: EngineTrack): unknown;
56
+ destroy(): unknown;
57
+ }
58
+
59
+ /** The `WaveformPlayer` class (`playerClass`, or the page's global). */
60
+ type EngineClass = new (container: HTMLElement, options: Record<string, any>) => Engine;
61
+
62
+ /** The elements the runtime drives (`_cacheRefs`). */
63
+ interface Refs {
64
+ list: HTMLElement;
65
+ search: HTMLInputElement | null;
66
+ bpmMin: HTMLInputElement | null;
67
+ bpmMax: HTMLInputElement | null;
68
+ bpmRange: HTMLElement | null;
69
+ bpmReadout: HTMLElement | null;
70
+ bpmClear: HTMLElement | null;
71
+ bpmLabel: HTMLElement | null;
72
+ loop: HTMLElement | null;
73
+ count: HTMLElement | null;
74
+ empty: HTMLElement | null;
75
+ more: HTMLElement | null;
76
+ engine: HTMLElement | null;
77
+ status: HTMLElement | null;
78
+ chips: HTMLElement[];
79
+ loopFilter: HTMLElement[];
80
+ }
81
+
82
+ /** The public fields are readonly to callers; the class itself writes them
83
+ * through this (a cast: it emits nothing). */
84
+ type Writable<T> = {-readonly [K in keyof T]: T[K]};
43
85
 
44
86
  export {DEFAULT_OPTIONS};
45
87
 
46
88
  /** An empty filter: everything matches. */
47
- const NO_FILTER = Object.freeze({query: '', type: '', key: '', bpmMin: '', bpmMax: '', loop: ''});
89
+ const NO_FILTER: Readonly<SoundsFilter> = Object.freeze({query: '', type: '', key: '', bpmMin: '', bpmMax: '', loop: ''});
48
90
 
49
91
  /** Debounce for typing in the search box and the BPM fields (ms). */
50
92
  const SEARCH_DELAY = 120;
@@ -54,19 +96,84 @@ const BPM_DELAY = 200;
54
96
  const URL_DELAY = 250;
55
97
 
56
98
  export class WaveformSounds {
57
- /** @type {Map<Element, WaveformSounds>} */
58
- static instances = new Map();
99
+ /** Every live instance, by its element. */
100
+ static instances: Map<Element, WaveformSounds> = new Map();
101
+ /** The pure helpers, for `<script>` users (attached in `entry.ts`). */
102
+ declare static utils: {
103
+ encodePeaks: typeof encodePeaks;
104
+ decodePeaks: typeof decodePeaks;
105
+ normalizeKey: typeof normalizeKey;
106
+ normalizeSounds: typeof normalizeSounds;
107
+ parseManifest: typeof parseManifest;
108
+ facets: typeof facets;
109
+ matches: typeof matches;
110
+ sortSounds: typeof sortSounds;
111
+ formatDuration: typeof formatDuration;
112
+ renderSounds: typeof renderSounds;
113
+ };
114
+ /** Every option with its default (attached in `entry.ts`). */
115
+ declare static DEFAULT_OPTIONS: WaveformSoundsOptions;
116
+ /** The English UI strings (attached in `entry.ts`). */
117
+ declare static DEFAULT_STRINGS: WaveformSoundsStrings;
118
+
119
+ declare readonly container: HTMLElement;
120
+ declare readonly options: Required<WaveformSoundsOptions>;
121
+ /** Resolves once the list is built (after a manifest fetch, if any).
122
+ * The build always happens after the constructor returns, so listeners
123
+ * attached straight after `new WaveformSounds()` see `ready`. It never
124
+ * rejects: a failed build (e.g. the manifest 404s) resolves it too and
125
+ * is reported through `onError` / `waveformsounds:error`. Calls made
126
+ * before it resolves are honoured: `setFilter`/`setSort` show in the
127
+ * controls once built, and `play()` waits for the list. */
128
+ declare readonly ready: Promise<void>;
129
+ declare readonly sounds: Sound[];
130
+ declare readonly filter: SoundsFilter;
131
+ declare readonly sortBy: SoundsSort;
132
+ declare readonly playing: boolean;
133
+ /** The engine `WaveformPlayer`, created on first play. */
134
+ declare readonly engine: unknown;
135
+
136
+ /** @internal */ declare strings: WaveformSoundsStrings;
137
+ /** @internal */ declare render: RenderOptions;
138
+ /** @internal */ declare rows: HTMLElement[];
139
+ /** @internal */ declare limit: number;
140
+ /** @internal */ declare currentIndex: number | null;
141
+ /** @internal */ declare progress: number;
142
+ /** @internal */ declare loop: boolean;
143
+ /** @internal */ declare menus: Menus | null;
144
+ /** @internal */ declare destroyed: boolean;
145
+ /** @internal Unset until the list is built; code that can run before checks it. */
146
+ declare $: Refs;
147
+ /** @internal */ declare colors: {wave: string, progress: string} | undefined;
148
+ /** @internal */ declare _ctl: AbortController;
149
+ /** @internal */ declare _originalHTML: string | null;
150
+ /** @internal */ declare _pendingSeek: number | null;
151
+ /** @internal */ declare _raf: number;
152
+ /** @internal */ declare _addedClasses: string[] | undefined;
153
+ /** @internal */ declare _loopSet: boolean | undefined;
154
+ /** @internal */ declare _sortSet: boolean | undefined;
155
+ /** @internal */ declare _bpmExtent: {min: number, max: number} | null;
156
+ /** @internal */ declare _sorts: string[];
157
+ /** @internal */ declare _lastSort: string | undefined;
158
+ /** @internal */ declare _lastPointer: string | undefined;
159
+ /** @internal */ declare _drawn: Set<number> | undefined;
160
+ /** @internal */ declare _io: IntersectionObserver | undefined;
161
+ /** @internal */ declare _ro: ResizeObserver | undefined;
162
+ /** @internal */ declare _mo: MutationObserver | undefined;
163
+ /** @internal */ declare _autoSurface: boolean | undefined;
164
+ /** @internal */ declare _urlTimer: number | undefined;
165
+ /** @internal */ declare _cued: boolean | undefined;
59
166
 
60
167
  /**
61
168
  * @param {HTMLElement|string} container - The element (or a selector).
62
- * @param {import('../../../index').WaveformSoundsOptions} [options]
169
+ * @param {WaveformSoundsOptions} [options]
63
170
  */
64
- constructor(container, options = {}) {
65
- const el = typeof container === 'string' ? document.querySelector(container) : container;
171
+ constructor(container: HTMLElement | string, options: WaveformSoundsOptions = {}) {
172
+ const el = typeof container === 'string' ? document.querySelector<HTMLElement>(container) : container;
66
173
  if (!el) throw new Error(`${LOG} Container not found: ${container}`);
67
174
  this.container = el;
68
175
  // Precedence, as across the family: data-* > constructor > default.
69
- this.options = mergeOptions(DEFAULT_OPTIONS, options, readDataOptions(el));
176
+ this.options = mergeOptions(DEFAULT_OPTIONS, options, readDataOptions(el)) as Required<WaveformSoundsOptions>;
70
177
  this.options.waveformStyle = this.options.waveformStyle === 'bars' ? 'bars' : 'mirror';
71
178
  this.strings = {...DEFAULT_STRINGS, ...(this.options.strings || {})};
72
179
  this.render = {...resolveRenderOptions(this.options), strings: this.strings};
@@ -108,18 +215,18 @@ export class WaveformSounds {
108
215
  /**
109
216
  * Adopt server-rendered markup or render it (from `sounds` or a fetched
110
217
  * manifest), then wire everything up.
111
- * @private
218
+ * @internal
112
219
  */
113
- async _init() {
220
+ async _init(): Promise<void> {
114
221
  const el = this.container;
115
- const adopted = el.querySelector('[data-ws-list]');
222
+ const adopted = el.querySelector<HTMLElement>('[data-ws-list]');
116
223
  if (adopted) {
117
- this.sounds = readRows(adopted);
224
+ (this as Writable<WaveformSounds>).sounds = readRows(adopted);
118
225
  } else {
119
226
  this._originalHTML = el.innerHTML;
120
- this.sounds = await this._loadSounds();
227
+ (this as Writable<WaveformSounds>).sounds = await this._loadSounds();
121
228
  if (this.destroyed) return;
122
- el.innerHTML = renderSounds(this.sounds, {...this.render, idPrefix: this.options.idPrefix || el.id || undefined});
229
+ el.innerHTML = renderSounds(this.sounds as SoundInput[], {...this.render, idPrefix: this.options.idPrefix || el.id || undefined});
123
230
  }
124
231
  if (this.destroyed) return;
125
232
 
@@ -141,7 +248,7 @@ export class WaveformSounds {
141
248
  // The starting order is the first one offered, unless setSort()
142
249
  // already chose one; then the address may override both.
143
250
  this._sorts = availableSorts(this.render.sorts, facets(this.sounds));
144
- if (!this._sortSet) this.sortBy = this._sorts[0] || 'default';
251
+ if (!this._sortSet) (this as Writable<WaveformSounds>).sortBy = (this._sorts[0] || 'default') as SoundsSort;
145
252
  this._readUrl();
146
253
  // Show any filter/sort set before now (from code or the address).
147
254
  this._syncControls();
@@ -163,10 +270,10 @@ export class WaveformSounds {
163
270
 
164
271
  /**
165
272
  * The sounds from the `sounds` option, else the `manifest` URL.
166
- * @returns {Promise<import('../../../index').Sound[]>}
167
- * @private
273
+ * @returns
274
+ * @internal
168
275
  */
169
- async _loadSounds() {
276
+ async _loadSounds(): Promise<Sound[]> {
170
277
  if (this.options.sounds || !this.options.manifest) return normalizeSounds(this.options.sounds || []);
171
278
  const res = await fetch(this.options.manifest);
172
279
  if (!res.ok) throw new Error(`${LOG} Manifest ${this.options.manifest}: HTTP ${res.status}`);
@@ -175,15 +282,15 @@ export class WaveformSounds {
175
282
 
176
283
  /**
177
284
  * Look up the elements the runtime drives.
178
- * @private
285
+ * @internal
179
286
  */
180
287
  _cacheRefs() {
181
- const q = (sel) => this.container.querySelector(sel);
288
+ const q = <T extends HTMLElement = HTMLElement>(sel: string) => this.container.querySelector<T>(sel);
182
289
  this.$ = {
183
- list: q('[data-ws-list]'),
184
- search: q('[data-ws-search]'),
185
- bpmMin: q('[data-ws-bpm-min]'),
186
- bpmMax: q('[data-ws-bpm-max]'),
290
+ list: q('[data-ws-list]')!,
291
+ search: q<HTMLInputElement>('[data-ws-search]'),
292
+ bpmMin: q<HTMLInputElement>('[data-ws-bpm-min]'),
293
+ bpmMax: q<HTMLInputElement>('[data-ws-bpm-max]'),
187
294
  bpmRange: q('[data-ws-bpm-range]'),
188
295
  bpmReadout: q('[data-ws-bpm-readout]'),
189
296
  bpmClear: q('[data-ws-bpm-clear]'),
@@ -194,8 +301,8 @@ export class WaveformSounds {
194
301
  more: q('[data-ws-more]'),
195
302
  engine: q('[data-ws-engine]'),
196
303
  status: q('[data-ws-status]'),
197
- chips: [...this.container.querySelectorAll('[data-ws-type]')],
198
- loopFilter: [...this.container.querySelectorAll('[data-ws-loop-filter]')],
304
+ chips: [...this.container.querySelectorAll<HTMLElement>('[data-ws-type]')],
305
+ loopFilter: [...this.container.querySelectorAll<HTMLElement>('[data-ws-loop-filter]')],
199
306
  };
200
307
  this.rows = indexRows(this.$.list);
201
308
  }
@@ -203,7 +310,7 @@ export class WaveformSounds {
203
310
  /**
204
311
  * Every listener. All are removed by `destroy()` through one
205
312
  * AbortController.
206
- * @private
313
+ * @internal
207
314
  */
208
315
  _bind() {
209
316
  const sig = {signal: this._ctl.signal};
@@ -217,24 +324,24 @@ export class WaveformSounds {
217
324
  let searchTimer = 0, bpmTimer = 0;
218
325
  $.search?.addEventListener('input', () => {
219
326
  clearTimeout(searchTimer);
220
- searchTimer = setTimeout(() => this.setFilter({query: $.search.value}), SEARCH_DELAY);
327
+ searchTimer = setTimeout(() => this.setFilter({query: $.search!.value}), SEARCH_DELAY);
221
328
  }, sig);
222
329
  $.search?.addEventListener('keydown', (e) => {
223
330
  if (e.key === 'ArrowDown') { e.preventDefault(); this._focusRow(visibleRows($.list)[0]); }
224
- if (e.key === 'Escape' && $.search.value) { e.preventDefault(); $.search.value = ''; this.setFilter({query: ''}); }
331
+ if (e.key === 'Escape' && $.search!.value) { e.preventDefault(); $.search!.value = ''; this.setFilter({query: ''}); }
225
332
  }, sig);
226
333
  // The BPM handles: the label and the track follow the drag at once;
227
334
  // the list re-filters once it settles. A handle can't pass the other.
228
- const onBpm = (moved) => {
229
- const lo = Number($.bpmMin.value), hi = Number($.bpmMax.value);
335
+ const onBpm = (moved: HTMLInputElement) => {
336
+ const lo = Number($.bpmMin!.value), hi = Number($.bpmMax!.value);
230
337
  if (lo > hi) moved.value = String(moved === $.bpmMin ? hi : lo);
231
- const f = bpmFilterFromRange(Number($.bpmMin.value), Number($.bpmMax.value), this._bpmExtent);
338
+ const f = bpmFilterFromRange(Number($.bpmMin!.value), Number($.bpmMax!.value), this._bpmExtent!);
232
339
  this._showBpm(f);
233
340
  clearTimeout(bpmTimer);
234
341
  bpmTimer = setTimeout(() => this.setFilter(f), BPM_DELAY);
235
342
  };
236
- $.bpmMin?.addEventListener('input', () => onBpm($.bpmMin), sig);
237
- $.bpmMax?.addEventListener('input', () => onBpm($.bpmMax), sig);
343
+ $.bpmMin?.addEventListener('input', () => onBpm($.bpmMin!), sig);
344
+ $.bpmMax?.addEventListener('input', () => onBpm($.bpmMax!), sig);
238
345
  $.bpmClear?.addEventListener('click', () => {
239
346
  clearTimeout(bpmTimer);
240
347
  this.setFilter({bpmMin: '', bpmMax: ''});
@@ -242,15 +349,15 @@ export class WaveformSounds {
242
349
 
243
350
  this.menus = new Menus(root, {
244
351
  signal: this._ctl.signal,
245
- onPick: (name, value) => (name === 'sort' ? this.setSort(value) : this.setFilter({[name]: value})),
352
+ onPick: (name, value) => (name === 'sort' ? this.setSort(value as SoundsSort) : this.setFilter({[name]: value})),
246
353
  });
247
354
 
248
355
  // Any OTHER player starting pauses the list (every WaveformPlayer's
249
356
  // play event bubbles to the document). The engine's singlePlay only
250
357
  // reaches players that also use singlePlay — a WaveformBar's player
251
358
  // doesn't, so without this the bar and the list could play at once.
252
- document.addEventListener('waveformplayer:play', (e) => {
253
- const player = e.detail?.player;
359
+ document.addEventListener('waveformplayer:play', (e: Event) => {
360
+ const player = (e as CustomEvent).detail?.player;
254
361
  if (player && player !== this.engine && this.playing) this.pause();
255
362
  }, sig);
256
363
  }
@@ -260,25 +367,25 @@ export class WaveformSounds {
260
367
  /**
261
368
  * Clicks: type chips, loops or one-shots, Show more, Clear, Loop, a touch tap on a waveform
262
369
  * (seek), and anywhere else on a row (play/pause).
263
- * @private
370
+ * @internal
264
371
  */
265
- _onClick(e) {
266
- const t = e.target;
267
- const chip = t.closest('[data-ws-type]');
372
+ _onClick(e: MouseEvent): void {
373
+ const t = e.target as Element;
374
+ const chip = t.closest<HTMLElement>('[data-ws-type]');
268
375
  if (chip) { this.setFilter({type: chip.dataset.wsType}); return; }
269
- const seg = t.closest('[data-ws-loop-filter]');
270
- if (seg) { this.setFilter({loop: seg.dataset.wsLoopFilter}); return; }
376
+ const seg = t.closest<HTMLElement>('[data-ws-loop-filter]');
377
+ if (seg) { this.setFilter({loop: seg.dataset.wsLoopFilter as SoundsLoopFilter}); return; }
271
378
  if (t.closest('[data-ws-more]')) { this.showMore(); return; }
272
379
  if (t.closest('[data-ws-clear]')) { this.clearFilters(); return; }
273
380
  if (t.closest('[data-ws-loop]')) { this.setLoop(!this.loop); return; }
274
- const wave = t.closest('.ws-wave');
381
+ const wave = t.closest<HTMLElement>('.ws-wave');
275
382
  if (wave) {
276
383
  // Touch seeks on the TAP (this click): its press may have been
277
384
  // the start of a scroll.
278
385
  if (this._lastPointer === 'touch') this._seekAt(wave, e.clientX);
279
386
  return;
280
387
  }
281
- const row = t.closest('[data-ws-index]');
388
+ const row = t.closest<HTMLElement>('[data-ws-index]');
282
389
  if (!row || t.closest('.ws-download')) return;
283
390
  this.toggle(Number(row.dataset.wsIndex));
284
391
  this._focusRowQuietly(row);
@@ -287,11 +394,11 @@ export class WaveformSounds {
287
394
  /**
288
395
  * Mouse and pen seek on PRESS, like every scrubber. Remembers the
289
396
  * pointer type for the click that follows.
290
- * @private
397
+ * @internal
291
398
  */
292
- _onPointerDown(e) {
399
+ _onPointerDown(e: PointerEvent): void {
293
400
  this._lastPointer = e.pointerType;
294
- const wave = e.target.closest('.ws-wave');
401
+ const wave = (e.target as Element).closest<HTMLElement>('.ws-wave');
295
402
  if (!wave || e.button !== 0 || e.pointerType === 'touch') return;
296
403
  e.preventDefault();
297
404
  this._seekAt(wave, e.clientX);
@@ -299,10 +406,10 @@ export class WaveformSounds {
299
406
 
300
407
  /**
301
408
  * Seek (or start) a row's sound where its waveform was pressed.
302
- * @private
409
+ * @internal
303
410
  */
304
- _seekAt(wave, clientX) {
305
- const row = wave.closest('[data-ws-index]');
411
+ _seekAt(wave: HTMLElement, clientX: number): void {
412
+ const row = wave.closest<HTMLElement>('[data-ws-index]')!;
306
413
  this._seekRow(Number(row.dataset.wsIndex), pointerFraction(clientX, wave.getBoundingClientRect()));
307
414
  this._focusRowQuietly(row);
308
415
  }
@@ -310,16 +417,16 @@ export class WaveformSounds {
310
417
  /**
311
418
  * Keys on the list: `/` focuses search; ↑/↓/Home/End move between rows
312
419
  * (auditioning while something plays); ←/→ seek the playing row.
313
- * @private
420
+ * @internal
314
421
  */
315
- _onKey(e) {
422
+ _onKey(e: KeyboardEvent): void {
316
423
  if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return;
317
- if (e.key === '/' && !isTyping(e.target) && this.$.search) {
424
+ if (e.key === '/' && !isTyping(e.target as Element | null) && this.$.search) {
318
425
  e.preventDefault();
319
426
  this.$.search.focus();
320
427
  return;
321
428
  }
322
- const row = e.target.closest?.('[data-ws-index]');
429
+ const row = (e.target as Element).closest?.<HTMLElement>('[data-ws-index]');
323
430
  if (!row) return;
324
431
 
325
432
  const index = Number(row.dataset.wsIndex);
@@ -342,10 +449,10 @@ export class WaveformSounds {
342
449
 
343
450
  /**
344
451
  * Focus a row's play button.
345
- * @private
452
+ * @internal
346
453
  */
347
- _focusRow(row) {
348
- row?.querySelector('.ws-play')?.focus();
454
+ _focusRow(row: HTMLElement | null | undefined): void {
455
+ row?.querySelector<HTMLElement>('.ws-play')?.focus();
349
456
  }
350
457
 
351
458
  /**
@@ -354,10 +461,10 @@ export class WaveformSounds {
354
461
  * on the title or waveform left focus on <body>, and Safari never
355
462
  * focuses a clicked button). No scroll jump, and no focus ring: the
356
463
  * browser shows none for a focus that follows a pointer.
357
- * @private
464
+ * @internal
358
465
  */
359
- _focusRowQuietly(row) {
360
- const btn = row?.querySelector('.ws-play');
466
+ _focusRowQuietly(row: HTMLElement | null | undefined): void {
467
+ const btn = row?.querySelector<HTMLElement>('.ws-play');
361
468
  if (btn && document.activeElement !== btn) btn.focus({preventScroll: true});
362
469
  }
363
470
 
@@ -366,23 +473,23 @@ export class WaveformSounds {
366
473
  /**
367
474
  * Draw row canvases as they scroll into view; redraw on resize and on
368
475
  * theme flips (the canvas can't follow CSS by itself).
369
- * @private
476
+ * @internal
370
477
  */
371
- _observe() {
478
+ _observe(): void {
372
479
  if (this.render.player !== 'inline' || typeof window === 'undefined') return;
373
480
  this._drawn = new Set();
374
481
  if ('IntersectionObserver' in window) {
375
482
  this._io = new IntersectionObserver((entries) => {
376
483
  for (const entry of entries) {
377
484
  if (!entry.isIntersecting) continue;
378
- const i = Number(entry.target.dataset.wsIndex);
379
- this._drawn.add(i);
485
+ const i = Number((entry.target as HTMLElement).dataset.wsIndex);
486
+ this._drawn!.add(i);
380
487
  this._drawRow(i);
381
488
  }
382
489
  }, {rootMargin: '200px 0px'});
383
- this.rows.forEach((r) => r && this._io.observe(r));
490
+ this.rows.forEach((r) => r && this._io!.observe(r));
384
491
  } else {
385
- this.rows.forEach((r, i) => r && this._drawn.add(i));
492
+ this.rows.forEach((r, i) => r && this._drawn!.add(i));
386
493
  }
387
494
  if ('ResizeObserver' in window) {
388
495
  let width = 0;
@@ -407,9 +514,9 @@ export class WaveformSounds {
407
514
  /**
408
515
  * Resolve the canvas colours (options, else the CSS custom properties)
409
516
  * and keep `--ws-surface` current unless the site set it.
410
- * @private
517
+ * @internal
411
518
  */
412
- _resolveColors() {
519
+ _resolveColors(): void {
413
520
  if (this._autoSurface || !getComputedStyle(this.container).getPropertyValue('--ws-surface').trim()) {
414
521
  this._autoSurface = true;
415
522
  this.container.style.removeProperty('--ws-surface');
@@ -423,9 +530,9 @@ export class WaveformSounds {
423
530
 
424
531
  /**
425
532
  * Draw one row's waveform (only once it has been on screen).
426
- * @private
533
+ * @internal
427
534
  */
428
- _drawRow(index) {
535
+ _drawRow(index: number | null | undefined): void {
429
536
  if (this.render.player !== 'inline' || index == null || !this._drawn?.has(index)) return;
430
537
  const row = this.rows[index];
431
538
  const canvas = row?.querySelector('canvas');
@@ -442,9 +549,9 @@ export class WaveformSounds {
442
549
 
443
550
  /**
444
551
  * Redraw every row drawn so far.
445
- * @private
552
+ * @internal
446
553
  */
447
- _redrawAll() {
554
+ _redrawAll(): void {
448
555
  this._drawn?.forEach((i) => this._drawRow(i));
449
556
  }
450
557
 
@@ -452,22 +559,22 @@ export class WaveformSounds {
452
559
 
453
560
  /**
454
561
  * Apply the filter and sort from the address (`urlState`).
455
- * @private
562
+ * @internal
456
563
  */
457
- _readUrl() {
564
+ _readUrl(): void {
458
565
  const keys = urlKeys(this.options.urlState);
459
566
  if (!keys || typeof location === 'undefined') return;
460
567
  const {filter, sort} = readUrlState(location.search, keys, facets(this.sounds), this._sorts);
461
- this.filter = {...this.filter, ...filter};
462
- if (sort) { this.sortBy = sort; this._sortSet = true; }
568
+ (this as Writable<WaveformSounds>).filter = {...this.filter, ...filter};
569
+ if (sort) { (this as Writable<WaveformSounds>).sortBy = sort as SoundsSort; this._sortSet = true; }
463
570
  }
464
571
 
465
572
  /**
466
573
  * Rewrite the address shortly after a change (replaceState: no history
467
574
  * entries).
468
- * @private
575
+ * @internal
469
576
  */
470
- _queueUrl() {
577
+ _queueUrl(): void {
471
578
  const keys = urlKeys(this.options.urlState);
472
579
  if (!keys || typeof location === 'undefined') return;
473
580
  clearTimeout(this._urlTimer);
@@ -481,7 +588,7 @@ export class WaveformSounds {
481
588
  /* ── Filtering, sorting, paging ───────────────────────────────────── */
482
589
 
483
590
  /** The sounds that pass the filter, in the current sort order. */
484
- get visible() {
591
+ get visible(): Sound[] {
485
592
  return sortSounds(this.sounds.filter((s) => matches(s, this.filter)), this.sortBy);
486
593
  }
487
594
 
@@ -489,30 +596,33 @@ export class WaveformSounds {
489
596
  * Change the filter (merged into the current one) and re-apply. Back to
490
597
  * the first page.
491
598
  *
492
- * @param {Partial<import('../../../index').SoundsFilter>} patch
599
+ * @param patch
493
600
  */
494
- setFilter(patch = {}) {
495
- this.filter = {...this.filter, ...patch};
601
+ // The public signature (as in 0.3.1's index.d.ts: `patch` required); the
602
+ // implementation's default stays, and an overload signature emits nothing.
603
+ setFilter(patch: Partial<SoundsFilter>): void;
604
+ setFilter(patch: Partial<SoundsFilter> = {}): void {
605
+ (this as Writable<WaveformSounds>).filter = {...this.filter, ...patch};
496
606
  this.limit = this._pageSize();
497
607
  this._syncControls();
498
608
  this._apply({resort: false});
499
609
  }
500
610
 
501
611
  /** Reset every filter (the sort stays). */
502
- clearFilters() {
612
+ clearFilters(): void {
503
613
  this.setFilter(NO_FILTER);
504
614
  }
505
615
 
506
- /** @param {import('../../../index').SoundsSort} by */
507
- setSort(by) {
616
+ /** @param by */
617
+ setSort(by: SoundsSort): void {
508
618
  this._sortSet = true;
509
- this.sortBy = SORTS.includes(by) ? by : 'default';
619
+ (this as Writable<WaveformSounds>).sortBy = SORTS.includes(by) ? by : 'default';
510
620
  this.menus?.setValue('sort', this.sortBy);
511
621
  this._apply({resort: true});
512
622
  }
513
623
 
514
624
  /** Reveal the next page of results. */
515
- showMore() {
625
+ showMore(): void {
516
626
  if (this.limit === Infinity) return;
517
627
  this.limit += this.render.pageSize;
518
628
  this._apply({resort: false});
@@ -520,18 +630,18 @@ export class WaveformSounds {
520
630
 
521
631
  /**
522
632
  * Rows per page (Infinity when paging is off).
523
- * @private
633
+ * @internal
524
634
  */
525
- _pageSize() {
635
+ _pageSize(): number {
526
636
  return this.render.pageSize > 0 ? this.render.pageSize : Infinity;
527
637
  }
528
638
 
529
639
  /**
530
640
  * Show the current filter and sort in the controls (they can be set from
531
641
  * code or the address, not only by the controls themselves).
532
- * @private
642
+ * @internal
533
643
  */
534
- _syncControls() {
644
+ _syncControls(): void {
535
645
  const $ = this.$, f = this.filter;
536
646
  if (!$) return;
537
647
  if ($.search && $.search.value !== f.query) $.search.value = f.query;
@@ -552,9 +662,9 @@ export class WaveformSounds {
552
662
  * Show a BPM filter in its menu: the button label, the panel's readout,
553
663
  * the filled part of the track, and which handle sits on top (the one
554
664
  * that can still move, when they meet).
555
- * @private
665
+ * @internal
556
666
  */
557
- _showBpm(f) {
667
+ _showBpm(f: {bpmMin?: string | number, bpmMax?: string | number}): void {
558
668
  const $ = this.$, extent = this._bpmExtent;
559
669
  if (!$?.bpmRange || !extent) return;
560
670
  const {lo, hi} = bpmRangeFromFilter(f, extent);
@@ -571,11 +681,11 @@ export class WaveformSounds {
571
681
  * Lay the rows out for the current filter, sort and page: order, hide,
572
682
  * "Show more", the empty state and the count. Then report it.
573
683
  *
574
- * @param {{resort: boolean}} opts - Reorder the rows even if the sort
684
+ * @param opts - Reorder the rows even if the sort
575
685
  * hasn't changed.
576
- * @private
686
+ * @internal
577
687
  */
578
- _apply({resort}) {
688
+ _apply({resort}: {resort: boolean}): void {
579
689
  const $ = this.$;
580
690
  if (!$) return;
581
691
  if (resort || this.sortBy !== this._lastSort) {
@@ -604,11 +714,11 @@ export class WaveformSounds {
604
714
  * Resolve an index, id or sound to an index in `this.sounds`. No
605
715
  * target means the current sound, else the first visible one.
606
716
  *
607
- * @param {number|string|Object} [target]
608
- * @returns {number|null}
609
- * @private
717
+ * @param target
718
+ * @returns
719
+ * @internal
610
720
  */
611
- _indexOf(target) {
721
+ _indexOf(target?: number | string | Sound | null): number | null {
612
722
  if (target == null) return this.currentIndex ?? (this.visible[0] ? this.sounds.indexOf(this.visible[0]) : null);
613
723
  if (typeof target === 'number') return this.sounds[target] ? target : null;
614
724
  const i = typeof target === 'object' ? this.sounds.indexOf(target) : this.sounds.findIndex((s) => s.id === String(target));
@@ -617,11 +727,11 @@ export class WaveformSounds {
617
727
 
618
728
  /**
619
729
  * The WaveformPlayer class: `playerClass`, else the page's global.
620
- * @returns {Function|null}
621
- * @private
730
+ * @returns
731
+ * @internal
622
732
  */
623
- _playerClass() {
624
- return this.options.playerClass || (typeof window !== 'undefined' ? window.WaveformPlayer : null) || null;
733
+ _playerClass(): EngineClass | null {
734
+ return (this.options.playerClass || (typeof window !== 'undefined' ? (window as any).WaveformPlayer : null) || null) as EngineClass | null;
625
735
  }
626
736
 
627
737
  /**
@@ -630,12 +740,12 @@ export class WaveformSounds {
630
740
  * which would strip `ws-engine--strip` (and with it the docked styling).
631
741
  * Made here rather than in the markup so server-rendered HTML from any
632
742
  * version works.
633
- * @returns {HTMLElement}
634
- * @private
743
+ * @returns
744
+ * @internal
635
745
  */
636
- _engineMount() {
637
- const slot = this.$.engine;
638
- let mount = slot.querySelector(':scope > [data-ws-engine-mount]');
746
+ _engineMount(): HTMLElement {
747
+ const slot = this.$.engine!;
748
+ let mount = slot.querySelector<HTMLElement>(':scope > [data-ws-engine-mount]');
639
749
  if (!mount) {
640
750
  mount = document.createElement('div');
641
751
  mount.setAttribute('data-ws-engine-mount', '');
@@ -646,35 +756,35 @@ export class WaveformSounds {
646
756
 
647
757
  /**
648
758
  * Build the engine once (it holds no audio until a play).
649
- * @returns {Object|null} The engine, or null without a player class.
650
- * @private
759
+ * @returns The engine, or null without a player class.
760
+ * @internal
651
761
  */
652
- _ensureEngine() {
653
- if (this.engine) return this.engine;
762
+ _ensureEngine(): Engine | null {
763
+ if (this.engine) return this.engine as Engine;
654
764
  const Player = this._playerClass();
655
765
  if (!Player) {
656
766
  console.error(`${LOG} @arraypress/waveform-player is required: load it before playing (or pass playerClass).`);
657
767
  return null;
658
768
  }
659
- this.engine = new Player(this._engineMount(), engineOptions(this.options.playerOptions, this.render.player, {
769
+ (this as Writable<WaveformSounds>).engine = new Player(this._engineMount(), engineOptions(this.options.playerOptions, this.render.player, {
660
770
  onLoad: () => this._onEngineLoad(),
661
771
  onPlay: () => this._setPlaying(true),
662
772
  onPause: () => this._setPlaying(false),
663
773
  onEnd: () => this._onEnd(),
664
- onTimeUpdate: (time, duration) => this._onTime(time, duration),
665
- onError: (err) => this._onEngineError(err),
774
+ onTimeUpdate: (time: number, duration: number) => this._onTime(time, duration),
775
+ onError: (err: unknown) => this._onEngineError(err),
666
776
  }));
667
- return this.engine;
777
+ return this.engine as Engine;
668
778
  }
669
779
 
670
780
  /**
671
781
  * Play a sound (by index, id or sound object), or resume the current
672
782
  * one. Before the list is built the call waits for it.
673
783
  *
674
- * @param {number|string|Object} [target]
675
- * @param {{at?: number}} [opts] - `at`: start position 0..1.
784
+ * @param target
785
+ * @param opts - `at`: start position 0..1.
676
786
  */
677
- play(target, opts = {}) {
787
+ play(target?: number | string | Sound, opts: {at?: number} = {}): void {
678
788
  if (!this.$) { this.ready.then(() => { if (!this.destroyed) this.play(target, opts); }); return; }
679
789
  const index = this._indexOf(target);
680
790
  if (index == null) return;
@@ -693,7 +803,7 @@ export class WaveformSounds {
693
803
  if (previous != null) this._paintRow(previous);
694
804
  this._paintRow(index);
695
805
  const sound = this.sounds[index];
696
- engine.loadTrack(sound.url, sound.title, sound.type || null, {waveform: enginePeaks(sound, this.render.player), autoplay: true});
806
+ engine.loadTrack(sound.url, sound.title, sound.type || null, engineTrack(sound, this.render.player, true));
697
807
  }
698
808
 
699
809
  /**
@@ -702,10 +812,10 @@ export class WaveformSounds {
702
812
  * (and its play button plays that sound) instead of an empty frame.
703
813
  * Only metadata is fetched — the browser default for any `<audio>`.
704
814
  * The row isn't marked current until it plays.
705
- * @private
815
+ * @internal
706
816
  */
707
- _cueFirst() {
708
- const engine = this.engine;
817
+ _cueFirst(): void {
818
+ const engine = this.engine as Engine | null;
709
819
  const first = this.visible[0];
710
820
  if (!engine || !first) return;
711
821
  const index = this.sounds.indexOf(first);
@@ -713,19 +823,19 @@ export class WaveformSounds {
713
823
  this.currentIndex = index;
714
824
  this.progress = 0;
715
825
  this._cued = true;
716
- engine.loadTrack(first.url, first.title, first.type || null, {waveform: enginePeaks(first, 'strip'), autoplay: false});
826
+ engine.loadTrack(first.url, first.title, first.type || null, engineTrack(first, 'strip', false));
717
827
  }
718
828
 
719
829
  /** Pause the current sound. */
720
- pause() {
721
- if (this.engine && this.playing) this.engine.pause();
830
+ pause(): void {
831
+ if (this.engine && this.playing) (this.engine as Engine).pause();
722
832
  }
723
833
 
724
834
  /**
725
835
  * The current sound plays/pauses; another sound starts.
726
- * @param {number|string|Object} [target]
836
+ * @param target
727
837
  */
728
- toggle(target) {
838
+ toggle(target?: number | string | Sound): void {
729
839
  const index = this._indexOf(target);
730
840
  if (index == null) return;
731
841
  if (index === this.currentIndex && this.playing) this.pause();
@@ -733,20 +843,20 @@ export class WaveformSounds {
733
843
  }
734
844
 
735
845
  /** Play the next visible sound (no wrap at the end). */
736
- next() { this._step(1); }
846
+ next(): void { this._step(1); }
737
847
 
738
848
  /** Play the previous visible sound. */
739
- previous() { this._step(-1); }
849
+ previous(): void { this._step(-1); }
740
850
 
741
851
  /**
742
852
  * Play the visible sound `dir` places away, revealing it if it's past
743
853
  * the current page.
744
854
  *
745
- * @param {1|-1} dir
746
- * @returns {boolean} Whether there was one.
747
- * @private
855
+ * @param dir
856
+ * @returns Whether there was one.
857
+ * @internal
748
858
  */
749
- _step(dir) {
859
+ _step(dir: 1 | -1): boolean {
750
860
  const shown = this.visible;
751
861
  // A cued sound counts as nothing played: next() starts with it.
752
862
  const at = this.currentIndex == null || this._cued ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
@@ -762,9 +872,9 @@ export class WaveformSounds {
762
872
  * Loop the current sound (auditioning a loop is the common case). When
763
873
  * the list marks its loops (`loop: true` on any sound), only those
764
874
  * repeat: a one-shot always plays once.
765
- * @param {boolean} on
875
+ * @param on
766
876
  */
767
- setLoop(on) {
877
+ setLoop(on: boolean): void {
768
878
  this._loopSet = true;
769
879
  this.loop = !!on;
770
880
  this._setLoop(this.loop);
@@ -772,54 +882,54 @@ export class WaveformSounds {
772
882
 
773
883
  /**
774
884
  * Apply the loop state to the toggle and the engine.
775
- * @private
885
+ * @internal
776
886
  */
777
- _setLoop(on) {
887
+ _setLoop(on: boolean): void {
778
888
  this.$?.loop?.setAttribute('aria-pressed', String(on));
779
- if (this.engine?.audio) this.engine.audio.loop = this._repeats();
889
+ if ((this.engine as Engine | null)?.audio) (this.engine as Engine).audio!.loop = this._repeats();
780
890
  }
781
891
 
782
892
  /**
783
893
  * Should the current sound repeat? The Loop toggle is on, and either
784
894
  * the list doesn't say which sounds are loops or this one is.
785
- * @private
895
+ * @internal
786
896
  */
787
- _repeats() {
897
+ _repeats(): boolean {
788
898
  if (!this.loop) return false;
789
899
  const marksLoops = this.sounds.some((s) => s.loop);
790
- return !marksLoops || !!this.sounds[this.currentIndex]?.loop;
900
+ return !marksLoops || !!this.sounds[this.currentIndex!]?.loop;
791
901
  }
792
902
 
793
903
  /**
794
904
  * Seek a row's sound to `fraction`; a row that isn't current starts
795
905
  * there. Before the duration is known the seek waits for it.
796
- * @private
906
+ * @internal
797
907
  */
798
- _seekRow(index, fraction) {
908
+ _seekRow(index: number, fraction: number): void {
799
909
  if (index !== this.currentIndex || !this.engine) { this.play(index, {at: fraction}); return; }
800
- const duration = this.engine.audio?.duration;
801
- if (!Number.isFinite(duration) || duration <= 0) { this._pendingSeek = fraction; return; }
802
- this.engine.seekTo(fraction * duration);
910
+ const duration = (this.engine as Engine).audio?.duration;
911
+ if (!Number.isFinite(duration) || duration! <= 0) { this._pendingSeek = fraction; return; }
912
+ (this.engine as Engine).seekTo(fraction * duration!);
803
913
  this.progress = fraction;
804
914
  this._paintRow(index);
805
- if (!this.playing) this.engine.play();
915
+ if (!this.playing) (this.engine as Engine).play();
806
916
  }
807
917
 
808
918
  /**
809
919
  * The engine loaded a sound: apply the loop, borrow decoded peaks for a
810
920
  * row that had none, and land a pending seek.
811
- * @private
921
+ * @internal
812
922
  */
813
- _onEngineLoad() {
814
- if (this.engine?.audio) this.engine.audio.loop = this._repeats();
815
- const sound = this.sounds[this.currentIndex];
816
- if (sound && !sound.peaks && this.engine?.waveformData?.length) {
817
- sound.peaks = resample(this.engine.waveformData, 96);
923
+ _onEngineLoad(): void {
924
+ if ((this.engine as Engine | null)?.audio) (this.engine as Engine).audio!.loop = this._repeats();
925
+ const sound = this.sounds[this.currentIndex!];
926
+ if (sound && !sound.peaks && (this.engine as Engine | null)?.waveformData?.length) {
927
+ sound.peaks = resample((this.engine as Engine).waveformData, 96);
818
928
  this._drawRow(this.currentIndex);
819
929
  }
820
- const duration = this.engine?.audio?.duration;
821
- if (this._pendingSeek != null && Number.isFinite(duration) && duration > 0) {
822
- this.engine.seekTo(this._pendingSeek * duration);
930
+ const duration = (this.engine as Engine | null)?.audio?.duration;
931
+ if (this._pendingSeek != null && Number.isFinite(duration) && duration! > 0) {
932
+ (this.engine as Engine).seekTo(this._pendingSeek * duration!);
823
933
  this.progress = this._pendingSeek;
824
934
  this._pendingSeek = null;
825
935
  }
@@ -827,14 +937,14 @@ export class WaveformSounds {
827
937
 
828
938
  /**
829
939
  * Playback progress: repaint the current row, once per frame.
830
- * @private
940
+ * @internal
831
941
  */
832
- _onTime(time, duration) {
942
+ _onTime(time: number, duration: number): void {
833
943
  if (this.currentIndex == null || !duration) return;
834
944
  if (this._pendingSeek != null) {
835
945
  const fraction = this._pendingSeek;
836
946
  this._pendingSeek = null;
837
- this.engine.seekTo(fraction * duration);
947
+ (this.engine as Engine).seekTo(fraction * duration);
838
948
  return;
839
949
  }
840
950
  this.progress = Math.min(Math.max(time / duration, 0), 1);
@@ -842,16 +952,16 @@ export class WaveformSounds {
842
952
  this._raf = requestAnimationFrame(() => {
843
953
  this._raf = 0;
844
954
  this._drawRow(this.currentIndex);
845
- this.rows[this.currentIndex]?.querySelector('.ws-wave')?.setAttribute('aria-valuenow', String(Math.round(this.progress * 100)));
955
+ this.rows[this.currentIndex!]?.querySelector('.ws-wave')?.setAttribute('aria-valuenow', String(Math.round(this.progress * 100)));
846
956
  });
847
957
  }
848
958
 
849
959
  /**
850
960
  * A sound finished: report it, then auto-advance or settle.
851
- * @private
961
+ * @internal
852
962
  */
853
- _onEnd() {
854
- const sound = this.sounds[this.currentIndex];
963
+ _onEnd(): void {
964
+ const sound = this.sounds[this.currentIndex!];
855
965
  this._emit('end', {sound, index: this.currentIndex});
856
966
  this.options.onEnd?.(sound, this);
857
967
  if (this.options.autoAdvance && this._step(1)) return;
@@ -861,11 +971,11 @@ export class WaveformSounds {
861
971
 
862
972
  /**
863
973
  * A sound failed to load or play: mark its row and report it.
864
- * @private
974
+ * @internal
865
975
  */
866
- _onEngineError(err) {
867
- this.rows[this.currentIndex]?.classList.add('is-error');
868
- this._emit('error', {error: err, sound: this.sounds[this.currentIndex], index: this.currentIndex});
976
+ _onEngineError(err: unknown): void {
977
+ this.rows[this.currentIndex!]?.classList.add('is-error');
978
+ this._emit('error', {error: err, sound: this.sounds[this.currentIndex!], index: this.currentIndex});
869
979
  this.options.onError?.(err, this);
870
980
  }
871
981
 
@@ -873,11 +983,11 @@ export class WaveformSounds {
873
983
  * Record play/pause and repaint. Events fire only on a real change: at a
874
984
  * natural end the browser fires `pause` then `ended`, and `_onEnd()`
875
985
  * also settles the state — one pause event, not two.
876
- * @private
986
+ * @internal
877
987
  */
878
- _setPlaying(on) {
988
+ _setPlaying(on: boolean): void {
879
989
  const changed = this.playing !== on;
880
- this.playing = on;
990
+ (this as Writable<WaveformSounds>).playing = on;
881
991
  if (on) this._cued = false; // the strip's own button played the cued sound
882
992
  const index = this.currentIndex;
883
993
  if (index == null) return;
@@ -893,9 +1003,9 @@ export class WaveformSounds {
893
1003
 
894
1004
  /**
895
1005
  * A row's state classes, play-button label and waveform.
896
- * @private
1006
+ * @internal
897
1007
  */
898
- _paintRow(index) {
1008
+ _paintRow(index: number): void {
899
1009
  const row = this.rows[index];
900
1010
  if (!row) return;
901
1011
  const current = index === this.currentIndex;
@@ -907,7 +1017,7 @@ export class WaveformSounds {
907
1017
  btn.setAttribute('aria-pressed', String(on));
908
1018
  btn.setAttribute('aria-label', fill(on ? this.strings.pause : this.strings.play, {title: this.sounds[index].title}));
909
1019
  }
910
- const wave = row.querySelector('.ws-wave');
1020
+ const wave = row.querySelector<HTMLElement>('.ws-wave');
911
1021
  if (wave) {
912
1022
  wave.tabIndex = current ? 0 : -1;
913
1023
  if (!current) wave.setAttribute('aria-valuenow', '0');
@@ -919,14 +1029,14 @@ export class WaveformSounds {
919
1029
 
920
1030
  /**
921
1031
  * Emit a `waveformsounds:<name>` event carrying this instance.
922
- * @private
1032
+ * @internal
923
1033
  */
924
- _emit(name, detail = {}) {
1034
+ _emit(name: string, detail: Record<string, any> = {}): void {
925
1035
  emit(this.container, name, {...detail, instance: this});
926
1036
  }
927
1037
 
928
1038
  /** The sound playing (or paused) now, or null. */
929
- get current() {
1039
+ get current(): Sound | null {
930
1040
  // A cued sound (strip, nothing played yet) isn't "current".
931
1041
  return this.currentIndex == null || this._cued ? null : this.sounds[this.currentIndex];
932
1042
  }
@@ -938,7 +1048,7 @@ export class WaveformSounds {
938
1048
  * re-sorted, hidden or marked current — so to start again, re-render it
939
1049
  * rather than constructing a new instance over it.
940
1050
  */
941
- destroy() {
1051
+ destroy(): void {
942
1052
  if (this.destroyed) return;
943
1053
  this.destroyed = true;
944
1054
  this._ctl.abort();
@@ -947,8 +1057,8 @@ export class WaveformSounds {
947
1057
  this._mo?.disconnect();
948
1058
  if (this._raf) cancelAnimationFrame(this._raf);
949
1059
  clearTimeout(this._urlTimer);
950
- try { this.engine?.destroy(); } catch { /* engine already gone */ }
951
- this.engine = null;
1060
+ try { (this.engine as Engine | null)?.destroy(); } catch { /* engine already gone */ }
1061
+ (this as Writable<WaveformSounds>).engine = null;
952
1062
  this.$?.engine?.querySelector(':scope > [data-ws-engine-mount]')?.remove();
953
1063
  if (this._originalHTML != null) this.container.innerHTML = this._originalHTML;
954
1064
  if (this._addedClasses?.length) this.container.classList.remove(...this._addedClasses);
@@ -960,14 +1070,14 @@ export class WaveformSounds {
960
1070
  /**
961
1071
  * Initialise every `[data-waveform-sounds]` under `root` that isn't yet.
962
1072
  *
963
- * @param {ParentNode} [root=document]
964
- * @returns {WaveformSounds[]} The new instances.
1073
+ * @param root
1074
+ * @returns The new instances.
965
1075
  */
966
- static init(root = document) {
1076
+ static init(root: ParentNode = document): WaveformSounds[] {
967
1077
  if (typeof document === 'undefined') return [];
968
1078
  const scope = root || document;
969
- const els = [...(scope.matches?.('[data-waveform-sounds]') ? [scope] : []), ...scope.querySelectorAll('[data-waveform-sounds]')];
970
- const created = [];
1079
+ const els = [...((scope as Element).matches?.('[data-waveform-sounds]') ? [scope as HTMLElement] : []), ...scope.querySelectorAll<HTMLElement>('[data-waveform-sounds]')];
1080
+ const created: WaveformSounds[] = [];
971
1081
  for (const el of els) {
972
1082
  if (el.dataset.wsInitialized === 'true' || WaveformSounds.instances.has(el)) continue;
973
1083
  try { created.push(new WaveformSounds(el)); } catch (err) { console.error(`${LOG} Failed to initialise:`, err, el); }
@@ -977,17 +1087,17 @@ export class WaveformSounds {
977
1087
 
978
1088
  /**
979
1089
  * The instance on an element (or selector), if any.
980
- * @param {Element|string} el
981
- * @returns {WaveformSounds|null}
1090
+ * @param el
1091
+ * @returns
982
1092
  */
983
- static getInstance(el) {
1093
+ static getInstance(el: Element | string): WaveformSounds | null {
984
1094
  const node = typeof el === 'string' ? document.querySelector(el) : el;
985
1095
  return node ? WaveformSounds.instances.get(node) || null : null;
986
1096
  }
987
1097
 
988
1098
  /** Destroy instances whose element has left the document (after a
989
1099
  * client-side navigation). */
990
- static prune() {
1100
+ static prune(): void {
991
1101
  for (const [el, inst] of WaveformSounds.instances) if (!el.isConnected) inst.destroy();
992
1102
  }
993
1103
  }