@arraypress/waveform-sounds 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/README.md +21 -1
  2. package/dist/waveform-sounds-no-autoinit.esm.js +445 -144
  3. package/dist/waveform-sounds-render.esm.js +220 -78
  4. package/dist/waveform-sounds.css +4 -0
  5. package/dist/waveform-sounds.esm.js +445 -144
  6. package/dist/waveform-sounds.js +445 -144
  7. package/dist/waveform-sounds.min.css +1 -1
  8. package/dist/waveform-sounds.min.js +1 -1
  9. package/package.json +1 -1
  10. package/src/css/waveform-sounds.css +4 -0
  11. package/src/js/core/WaveformSounds.ts +224 -67
  12. package/src/js/core/element.ts +1 -1
  13. package/src/js/core/options.ts +1 -0
  14. package/src/js/data/keys.ts +156 -0
  15. package/src/js/data/navigation.ts +35 -8
  16. package/src/js/data/sounds.ts +29 -22
  17. package/src/js/data/url-state.ts +7 -3
  18. package/src/js/dom/draw.ts +16 -2
  19. package/src/js/dom/menus.ts +2 -1
  20. package/src/js/dom/rows.ts +38 -12
  21. package/src/js/render/icons.ts +59 -16
  22. package/src/js/render/markup.ts +115 -49
  23. package/src/js/render/options.ts +3 -1
  24. package/src/js/render/strings.ts +53 -1
  25. package/src/js/types.ts +24 -0
  26. package/types/core/WaveformSounds.d.ts +3 -3
  27. package/types/core/WaveformSounds.d.ts.map +1 -1
  28. package/types/core/options.d.ts.map +1 -1
  29. package/types/data/keys.d.ts +88 -0
  30. package/types/data/keys.d.ts.map +1 -0
  31. package/types/data/navigation.d.ts +27 -9
  32. package/types/data/navigation.d.ts.map +1 -1
  33. package/types/data/sounds.d.ts +20 -5
  34. package/types/data/sounds.d.ts.map +1 -1
  35. package/types/data/url-state.d.ts +6 -1
  36. package/types/data/url-state.d.ts.map +1 -1
  37. package/types/dom/draw.d.ts +5 -2
  38. package/types/dom/draw.d.ts.map +1 -1
  39. package/types/dom/menus.d.ts.map +1 -1
  40. package/types/dom/rows.d.ts +19 -8
  41. package/types/dom/rows.d.ts.map +1 -1
  42. package/types/render/icons.d.ts +41 -3
  43. package/types/render/icons.d.ts.map +1 -1
  44. package/types/render/markup.d.ts +27 -4
  45. package/types/render/markup.d.ts.map +1 -1
  46. package/types/render/options.d.ts +1 -1
  47. package/types/render/options.d.ts.map +1 -1
  48. package/types/render/strings.d.ts +22 -1
  49. package/types/render/strings.d.ts.map +1 -1
  50. package/types/types.d.ts +24 -0
  51. package/types/types.d.ts.map +1 -1
@@ -26,26 +26,29 @@
26
26
  * @module core
27
27
  */
28
28
 
29
- import {availableSorts, facets, formatClock, formatDuration, matches, normalizeSounds, parseManifest, sortSounds, SORTS} from '../data/sounds.js';
29
+ import {availableSorts, facets, formatClock, formatDuration, matches, normalizeKey, normalizeSounds, parseManifest, sortSounds, SORTS} from '../data/sounds.js';
30
+ import {keyEntry} from '../data/keys.js';
30
31
  import {drawRowWaveform, resample} from '../dom/draw.js';
31
32
  import {engineOptions, engineTrack} from './engine.js';
32
33
  import {Menus} from '../dom/menus.js';
33
- import {limitToReveal, pageWindow, rowTarget, seekTarget, sliderEdgeTarget} from '../data/navigation.js';
34
+ import {budgetToReveal, limitToReveal, RENDER_CHUNK, renderedCount, rowTarget, seekTarget, sliderEdgeTarget} from '../data/navigation.js';
34
35
  import {DEFAULT_OPTIONS, mergeOptions, readDataOptions} from './options.js';
35
36
  import {resolveRenderOptions} from '../render/options.js';
36
- import {loopsByDefault, renderSounds} from '../render/markup.js';
37
- import {indexRows, orderRows, readRows, visibleRows} from '../dom/rows.js';
37
+ import {idBase, loopsByDefault, renderList, renderRow} from '../render/markup.js';
38
+ import type {renderSounds} from '../render/markup.js';
39
+ import {ICON_NAMES, iconSprite} from '../render/icons.js';
40
+ import {indexRows, layoutRows, readRows, readSoundsData, visibleRows} from '../dom/rows.js';
38
41
  import {bpmLabel, countText, DEFAULT_STRINGS, fill} from '../render/strings.js';
39
42
  import {bpmExtent, bpmFilterFromRange, bpmFraction, bpmRangeFromFilter} from '../data/bpm.js';
40
43
  import {ancestorsOf, forcedColors, pageSurface, resolveCssColor} from '../dom/colors.js';
41
44
  import {readUrlState, urlKeys, writeUrlState} from '../data/url-state.js';
42
45
  import {emit, isTyping, LOG, pointerFraction} from '../shared/utils.js';
43
46
  import {h, text} from '../render/html.js';
44
- import type {decodePeaks, encodePeaks, normalizeKey} from '../data/sounds.js';
47
+ import type {decodePeaks, encodePeaks} from '../data/sounds.js';
45
48
  import type {EngineTrack} from './engine.js';
46
49
  import type {WaveformPlayer} from '@arraypress/waveform-player';
47
50
  import type {RenderOptions} from '../render/options.js';
48
- import type {Sound, SoundInput, SoundsFilter, SoundsLoopFilter, SoundsSort, WaveformSoundsInstanceEventMap, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
51
+ import type {Sound, SoundsFilter, SoundsLoopFilter, SoundsSort, WaveformSoundsInstanceEventMap, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
49
52
 
50
53
  /** The engine `WaveformPlayer`, as far as the list uses it. */
51
54
  interface Engine {
@@ -162,8 +165,13 @@ export class WaveformSounds extends EventTarget {
162
165
 
163
166
  /** @internal */ declare strings: WaveformSoundsStrings;
164
167
  /** @internal */ declare render: RenderOptions;
165
- /** @internal */ declare rows: HTMLElement[];
168
+ /** @internal Each sound's row, once it has one (in the list or not). */ declare rows: HTMLElement[];
166
169
  /** @internal */ declare limit: number;
170
+ /** @internal Paging off: how many of the matching sounds have rows so far. */ declare _budget: number;
171
+ /** @internal Each sound's index. */ declare _index: Map<Sound, number>;
172
+ /** @internal The list's id prefix (its icons, rows' read-outs). */ declare _iconId: string;
173
+ /** @internal Sounds that failed to load (their rows are marked, rendered or not). */ declare _failed: Set<number>;
174
+ /** @internal Watches the last rendered row, to render the next chunk. */ declare _endIo: IntersectionObserver | undefined;
167
175
  /** @internal */ declare currentIndex: number | null;
168
176
  /** @internal */ declare progress: number;
169
177
  /** @internal */ declare loop: boolean;
@@ -181,8 +189,8 @@ export class WaveformSounds extends EventTarget {
181
189
  /** @internal */ declare _loopSet: boolean | undefined;
182
190
  /** @internal */ declare _sortSet: boolean | undefined;
183
191
  /** @internal */ declare _bpmExtent: {min: number, max: number} | null;
192
+ /** @internal What the sounds offer the controls (built once). */ declare _facets: ReturnType<typeof facets> | undefined;
184
193
  /** @internal */ declare _sorts: string[];
185
- /** @internal */ declare _lastSort: string | undefined;
186
194
  /** @internal */ declare _lastPointer: string | undefined;
187
195
  /** @internal Rows drawn at least once. */ declare _drawn: Set<number> | undefined;
188
196
  /** @internal Drawn rows whose picture is stale (redrawn when they show). */ declare _dirty: Set<number> | undefined;
@@ -220,6 +228,9 @@ export class WaveformSounds extends EventTarget {
220
228
  this.filter = {...NO_FILTER};
221
229
  this.sortBy = 'default';
222
230
  this.limit = this._pageSize();
231
+ this._budget = this._firstBudget();
232
+ this._index = new Map();
233
+ this._failed = new Set();
223
234
  this.currentIndex = null;
224
235
  this.playing = false;
225
236
  this.progress = 0;
@@ -262,38 +273,45 @@ export class WaveformSounds extends EventTarget {
262
273
  if (adopted) {
263
274
  // As the server sent it, for destroy({restore: true}).
264
275
  this._adoptedHTML = el.innerHTML;
265
- (this as Writable<WaveformSounds>).sounds = readRows(adopted);
276
+ // Every sound from the markup's JSON (2.2+); before 2.2 every
277
+ // row was in the markup, carrying its sound.
278
+ (this as Writable<WaveformSounds>).sounds = readSoundsData(el) ?? readRows(adopted);
266
279
  } else {
267
280
  this._originalHTML = el.innerHTML;
268
281
  (this as Writable<WaveformSounds>).sounds = await this._loadSounds();
269
282
  if (this.destroyed) return;
270
- el.innerHTML = renderSounds(this.sounds as SoundInput[], {...this.render, idPrefix: this.options.idPrefix || el.id || undefined});
283
+ // The server's markup, less the JSON (the sounds are here).
284
+ el.innerHTML = renderList(this.sounds, {...this.render, idPrefix: this.options.idPrefix || el.id || undefined}, false);
271
285
  }
272
286
  if (this.destroyed) return;
287
+ this._index = new Map(this.sounds.map((sound, i) => [sound, i]));
273
288
 
274
289
  // Remember which classes WE add, so destroy() takes back exactly
275
290
  // those (server-rendered markup already carries them).
276
291
  this._addedClasses = ['waveform-sounds', `waveform-sounds--${this.render.player}`].filter((c) => !el.classList.contains(c));
277
292
  el.classList.add(...this._addedClasses);
278
293
 
294
+ this._facets = facets(this.sounds, this.render);
279
295
  this._cacheRefs();
280
296
  this._bind();
281
297
  this._observe();
282
298
  this._resolveColors();
283
299
  // Unless set (option or an early setLoop()), Loop starts on exactly
284
300
  // when the list marks loops — only those repeat.
285
- if (!this._loopSet) this.loop = loopsByDefault(this.options.loop, facets(this.sounds));
301
+ if (!this._loopSet) this.loop = loopsByDefault(this.options.loop, this._facets);
286
302
  this._setLoop(this.loop);
287
- this._bpmExtent = bpmExtent(facets(this.sounds).bpm);
303
+ this._bpmExtent = bpmExtent(this._facets.bpm);
288
304
 
289
305
  // The starting order is the first one offered, unless setSort()
290
306
  // already chose one; then the address may override both.
291
- this._sorts = availableSorts(this.render.sorts, facets(this.sounds));
307
+ this._sorts = availableSorts(this.render.sorts, this._facets);
292
308
  if (!this._sortSet) (this as Writable<WaveformSounds>).sortBy = (this._sorts[0] || 'default') as SoundsSort;
293
309
  this._readUrl();
310
+ // A key set from code before now, in the list's spelling.
311
+ (this as Writable<WaveformSounds>).filter = {...this.filter, key: this._keyEntry(this.filter.key)};
294
312
  // Show any filter/sort set before now (from code or the address).
295
313
  this._syncControls();
296
- this._apply({resort: this.sortBy !== 'default'});
314
+ this._apply();
297
315
 
298
316
  // Build the engine now (no audio loads until a play) when the
299
317
  // player is on the page, so anything that hooks players on their
@@ -362,12 +380,51 @@ export class WaveformSounds extends EventTarget {
362
380
  chips: [...this.container.querySelectorAll<HTMLElement>('[data-ws-type]')],
363
381
  loopFilter: [...this.container.querySelectorAll<HTMLElement>('[data-ws-loop-filter]')],
364
382
  };
365
- this.rows = indexRows(this.$.list);
383
+ // The id prefix the rows were drawn with (their icons and
384
+ // read-outs); markup from before 2.2 has no sprite, so it gets one
385
+ // for the rows rendered from now on.
386
+ const sprite = q('[data-ws-sprite]');
387
+ this._iconId = sprite?.dataset.wsSprite ?? (this.options.idPrefix || this.container.id || idBase(this.sounds));
388
+ if (!sprite) this.$.list.insertAdjacentHTML('beforebegin', iconSprite(this._iconId, ICON_NAMES));
389
+ this.rows = [];
366
390
  // Roving tabindex: the list is ONE Tab stop (the active row's
367
391
  // controls); ↑/↓ move between rows. Set here, not in the markup, so
368
392
  // server-rendered HTML from any version gets it.
369
393
  this._active = null;
370
- for (const row of this.rows) if (row) this._rowStops(row, false);
394
+ for (const row of indexRows(this.$.list)) if (row) this._adoptRow(row);
395
+ }
396
+
397
+ /**
398
+ * Take a row (server-rendered, or just rendered) into the list's
399
+ * keeping: its index, its Tab stops off, the state of its sound (current,
400
+ * failed), and the observer that draws it.
401
+ * @internal
402
+ */
403
+ _adoptRow(row: HTMLElement): void {
404
+ const i = Number(row.dataset.wsIndex);
405
+ this.rows[i] = row;
406
+ this._rowStops(row, false);
407
+ const wave = row.querySelector<HTMLElement>('.ws-wave');
408
+ // Before 2.2 every row's waveform was a slider: only the current one is.
409
+ if (i === this.currentIndex || this._failed.has(i) || wave?.hasAttribute('role')) this._paintRow(i);
410
+ if (i === this.currentIndex) this._paintSlider();
411
+ if (this._io) this._io.observe(row);
412
+ else this._drawn?.add(i);
413
+ }
414
+
415
+ /**
416
+ * Rows for these sounds, rendered (in one pass) where they have none.
417
+ * @returns The rows, in the order given.
418
+ * @internal
419
+ */
420
+ _rowsFor(indices: number[]): HTMLElement[] {
421
+ const missing = indices.filter((i) => !this.rows[i]);
422
+ if (missing.length) {
423
+ const tpl = document.createElement('template');
424
+ tpl.innerHTML = missing.map((i) => renderRow(this.sounds[i], i, this.render, this._iconId)).join('');
425
+ for (const row of [...tpl.content.children] as HTMLElement[]) this._adoptRow(row);
426
+ }
427
+ return indices.map((i) => this.rows[i]);
371
428
  }
372
429
 
373
430
  /**
@@ -381,7 +438,7 @@ export class WaveformSounds extends EventTarget {
381
438
  const dl = row.querySelector<HTMLElement>('.ws-download');
382
439
  if (dl) dl.tabIndex = on ? 0 : -1;
383
440
  const wave = row.querySelector<HTMLElement>('.ws-wave');
384
- if (wave) wave.tabIndex = on && Number(row.dataset.wsIndex) === this.currentIndex ? 0 : -1;
441
+ if (wave && Number(row.dataset.wsIndex) === this.currentIndex) wave.tabIndex = on ? 0 : -1;
385
442
  }
386
443
 
387
444
  /**
@@ -551,13 +608,35 @@ export class WaveformSounds extends EventTarget {
551
608
  return;
552
609
  }
553
610
 
554
- const rows = visibleRows(this.$.list);
555
- const target = rowTarget(e.key, rows.indexOf(row), rows.length);
611
+ // Positions among the sounds the page shows, rows or not: ↓ past
612
+ // the last row rendered (paging off) renders the next ones.
613
+ const shown = this._shown ?? [];
614
+ const target = rowTarget(e.key, shown.indexOf(this.sounds[index]), Math.min(shown.length, this.limit));
556
615
  if (target === null) return;
557
616
  e.preventDefault();
558
617
  if (target === 'search') { this.$.search?.focus(); return; }
559
- this._focusRow(rows[target]);
560
- if (this.options.arrowAudition && this.playing) this.play(Number(rows[target].dataset.wsIndex));
618
+ this._focusRow(this._reveal(target));
619
+ if (this.options.arrowAudition && this.playing) this.play(this._index.get(shown[target]));
620
+ }
621
+
622
+ /**
623
+ * The row at position `pos` of the matching sounds, revealing it first:
624
+ * past the page, the page grows to it (as `next()` always did); with
625
+ * paging off, rows are rendered up to it.
626
+ * @internal
627
+ */
628
+ _reveal(pos: number): HTMLElement | undefined {
629
+ const sound = this._shown?.[pos];
630
+ if (!sound) return undefined;
631
+ const limit = limitToReveal(this.limit, pos);
632
+ if (limit !== this.limit) {
633
+ this.limit = limit;
634
+ this._apply();
635
+ } else if (this.limit === Infinity && pos >= this._budget) {
636
+ this._budget = budgetToReveal(this._budget, pos);
637
+ this._layout();
638
+ }
639
+ return this.rows[this._index.get(sound)!];
561
640
  }
562
641
 
563
642
  /**
@@ -678,8 +757,8 @@ export class WaveformSounds extends EventTarget {
678
757
  const row = this.rows[index];
679
758
  const canvas = row?.querySelector('canvas');
680
759
  if (!canvas) return;
681
- // Hidden (filtered, or past the page): draw it when it shows again.
682
- if (row.hidden) { this._dirty?.add(index); return; }
760
+ // Out of the list (filtered, or past the page): draw it when it is back.
761
+ if (!row.isConnected) { this._dirty?.add(index); return; }
683
762
  this._dirty?.delete(index);
684
763
  const gap = Number(this.options.barGap);
685
764
  drawRowWaveform(canvas, this.sounds[index].peaks, index === this.currentIndex ? this.progress : 0, {
@@ -714,8 +793,8 @@ export class WaveformSounds extends EventTarget {
714
793
  _readUrl(): void {
715
794
  const keys = urlKeys(this.options.urlState);
716
795
  if (!keys || typeof location === 'undefined') return;
717
- const f = facets(this.sounds);
718
- const {filter, sort} = readUrlState(location.search, keys, {...f, bpm: bpmExtent(f.bpm)}, this._sorts);
796
+ const f = this._facets!;
797
+ const {filter, sort} = readUrlState(location.search, keys, {...f, bpm: bpmExtent(f.bpm)}, this._sorts, this.render);
719
798
  (this as Writable<WaveformSounds>).filter = {...this.filter, ...filter};
720
799
  if (sort) { (this as Writable<WaveformSounds>).sortBy = sort as SoundsSort; this._sortSet = true; }
721
800
  }
@@ -750,7 +829,19 @@ export class WaveformSounds extends EventTarget {
750
829
  * @internal
751
830
  */
752
831
  _match(): Sound[] {
753
- return sortSounds(this.sounds.filter((s) => matches(s, this.filter)), this.sortBy);
832
+ return sortSounds(this.sounds.filter((s) => matches(s, this.filter, this.render)), this.sortBy);
833
+ }
834
+
835
+ /**
836
+ * A key filter in the list's own spelling: with enharmonic keys merged,
837
+ * `A#m` on a list whose entry is `Bbm` becomes `Bbm` (so the menu and
838
+ * the address show the entry). A key the list doesn't have stays as
839
+ * given (it matches nothing, as before).
840
+ * @internal
841
+ */
842
+ _keyEntry(key: string | undefined): string {
843
+ const k = normalizeKey(key);
844
+ return (this._facets && keyEntry(k, this._facets.keys, this.render.mergeEnharmonicKeys)) || k;
754
845
  }
755
846
 
756
847
  /**
@@ -764,9 +855,11 @@ export class WaveformSounds extends EventTarget {
764
855
  setFilter(patch: Partial<SoundsFilter>): void;
765
856
  setFilter(patch: Partial<SoundsFilter> = {}): void {
766
857
  (this as Writable<WaveformSounds>).filter = {...this.filter, ...patch};
858
+ if (patch.key) this.filter.key = this._keyEntry(patch.key);
767
859
  this.limit = this._pageSize();
860
+ this._budget = this._firstBudget();
768
861
  this._syncControls();
769
- this._apply({resort: false});
862
+ this._apply();
770
863
  }
771
864
 
772
865
  /** Reset every filter (the sort stays). */
@@ -779,14 +872,14 @@ export class WaveformSounds extends EventTarget {
779
872
  this._sortSet = true;
780
873
  (this as Writable<WaveformSounds>).sortBy = SORTS.includes(by) ? by : 'default';
781
874
  this.menus?.setValue('sort', this.sortBy);
782
- this._apply({resort: true});
875
+ this._apply();
783
876
  }
784
877
 
785
878
  /** Reveal the next page of results. */
786
879
  showMore(): void {
787
880
  if (this.limit === Infinity) return;
788
881
  this.limit += this.render.pageSize;
789
- this._apply({resort: false});
882
+ this._apply();
790
883
  }
791
884
 
792
885
  /**
@@ -797,6 +890,16 @@ export class WaveformSounds extends EventTarget {
797
890
  return this.render.pageSize > 0 ? this.render.pageSize : Infinity;
798
891
  }
799
892
 
893
+ /**
894
+ * Paging off: the rows a list (or a new filter) starts with — a chunk,
895
+ * more as the list scrolls (see `_watchEnd`); all of them where nothing
896
+ * can tell it scrolled (no IntersectionObserver).
897
+ * @internal
898
+ */
899
+ _firstBudget(): number {
900
+ return typeof IntersectionObserver === 'undefined' ? Infinity : RENDER_CHUNK;
901
+ }
902
+
800
903
  /**
801
904
  * Show the current filter and sort in the controls (they can be set from
802
905
  * code or the address, not only by the controls themselves).
@@ -839,27 +942,17 @@ export class WaveformSounds extends EventTarget {
839
942
  }
840
943
 
841
944
  /**
842
- * Lay the rows out for the current filter, sort and page: order, hide,
945
+ * Lay the list out for the current filter, sort and page: its rows,
843
946
  * "Show more", the empty state and the count. Then report it.
844
- *
845
- * @param opts - Reorder the rows even if the sort
846
- * hasn't changed.
847
947
  * @internal
848
948
  */
849
- _apply({resort}: {resort: boolean}): void {
949
+ _apply(): void {
850
950
  const $ = this.$;
851
951
  if (!$) return;
852
- if (resort || this.sortBy !== this._lastSort) {
853
- // Each sound's row by identity: a Map, not indexOf per sound
854
- // (quadratic — 1000 sounds was a million comparisons a sort).
855
- const index = new Map(this.sounds.map((s, i) => [s, i]));
856
- orderRows($.list, sortSounds(this.sounds, this.sortBy).map((s) => this.rows[index.get(s)!]));
857
- this._lastSort = this.sortBy;
858
- }
859
952
  const shown = this._match();
860
953
  this._shown = shown;
861
- const {visible, remaining} = pageWindow(shown, this.limit);
862
- this.sounds.forEach((s, i) => { if (this.rows[i]) this.rows[i].hidden = !visible.has(s); });
954
+ this._layout();
955
+ const remaining = shown.length - Math.min(shown.length, this.limit);
863
956
  if ($.more) {
864
957
  $.more.hidden = remaining <= 0;
865
958
  $.more.textContent = fill(this.strings.showMore, {count: Math.min(remaining, this.render.pageSize || remaining)});
@@ -871,17 +964,6 @@ export class WaveformSounds extends EventTarget {
871
964
  if (!this.sounds.length && $.empty.textContent !== this.strings.noSounds) $.empty.textContent = this.strings.noSounds;
872
965
  }
873
966
  if ($.count) $.count.textContent = countText(shown.length, this.sounds.length, this.strings);
874
- // The Tab stop never sits on a hidden row; and if focus was in the
875
- // row just filtered away, it follows the stop instead of falling
876
- // to <body>.
877
- if (!this._active || this._active.hidden) {
878
- const lost = !!this._active?.contains(document.activeElement);
879
- const first = visibleRows($.list)[0];
880
- if (first) {
881
- this._rove(first);
882
- if (lost) this._focusRowQuietly(first);
883
- } else if (this._active) { this._rowStops(this._active, false); this._active = null; }
884
- }
885
967
  // Nothing played yet: keep the cued sound one the list still shows.
886
968
  if (this._cued && !this.playing) this._cueFirst();
887
969
  this._queueUrl();
@@ -889,6 +971,52 @@ export class WaveformSounds extends EventTarget {
889
971
  this.options.onFilter?.(shown, this);
890
972
  }
891
973
 
974
+ /**
975
+ * Put exactly the rows shown in the list, in order: the page (or with
976
+ * paging off the rows rendered so far) of the matching sounds. Rows are
977
+ * rendered the first time they are shown; rows that stop being shown
978
+ * leave the DOM (kept, with their drawing, for when they come back).
979
+ * @internal
980
+ */
981
+ _layout(): void {
982
+ const $ = this.$, shown = this._shown!;
983
+ const count = renderedCount(shown.length, this.limit, this._budget);
984
+ const focused = $.list.contains(document.activeElement) ? document.activeElement as HTMLElement : null;
985
+ const rows = this._rowsFor(shown.slice(0, count).map((sound) => this._index.get(sound)!));
986
+ layoutRows($.list, rows);
987
+ // A re-sort moves rows, and a moved element loses focus: give it back.
988
+ if (focused?.isConnected && document.activeElement !== focused) focused.focus({preventScroll: true});
989
+ if (!this._io && this._drawn) for (const row of rows) this._drawRow(Number(row.dataset.wsIndex));
990
+ // The Tab stop never sits on a row that left the list; and if focus
991
+ // was in it, focus follows the stop instead of falling to <body>.
992
+ if (!this._active || !this._active.isConnected) {
993
+ const first = rows[0];
994
+ if (first) {
995
+ this._rove(first);
996
+ if (focused && !focused.isConnected) this._focusRowQuietly(first);
997
+ } else if (this._active) { this._rowStops(this._active, false); this._active = null; }
998
+ }
999
+ // Paging off and more to render: the next chunk when the last row
1000
+ // nears the viewport.
1001
+ this._watchEnd(count < Math.min(shown.length, this.limit) ? rows[rows.length - 1] : null);
1002
+ }
1003
+
1004
+ /**
1005
+ * Render the next chunk of rows once `row` (the last one rendered) comes
1006
+ * within ~1200px of the viewport; nothing to watch for `null`.
1007
+ * @internal
1008
+ */
1009
+ _watchEnd(row: HTMLElement | null | undefined): void {
1010
+ this._endIo?.disconnect();
1011
+ if (!row || typeof IntersectionObserver === 'undefined') return;
1012
+ this._endIo ??= new IntersectionObserver((entries) => {
1013
+ if (this.destroyed || !entries.some((entry) => entry.isIntersecting)) return;
1014
+ this._budget += RENDER_CHUNK;
1015
+ this._layout();
1016
+ }, {rootMargin: '0px 0px 1200px 0px'});
1017
+ this._endIo.observe(row);
1018
+ }
1019
+
892
1020
  /* ── Playback ─────────────────────────────────────────────────────── */
893
1021
 
894
1022
  /**
@@ -905,7 +1033,7 @@ export class WaveformSounds extends EventTarget {
905
1033
  return first ? this.sounds.indexOf(first) : null;
906
1034
  }
907
1035
  if (typeof target === 'number') return this.sounds[target] ? target : null;
908
- const i = typeof target === 'object' ? this.sounds.indexOf(target) : this.sounds.findIndex((s) => s.id === String(target));
1036
+ const i = typeof target === 'object' ? (this._index.get(target) ?? this.sounds.indexOf(target)) : this.sounds.findIndex((s) => s.id === String(target));
909
1037
  return i >= 0 ? i : null;
910
1038
  }
911
1039
 
@@ -1068,8 +1196,7 @@ export class WaveformSounds extends EventTarget {
1068
1196
  const at = this.currentIndex == null || this._cued ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
1069
1197
  const target = shown[at + dir];
1070
1198
  if (!target) return false;
1071
- const limit = limitToReveal(this.limit, at + dir);
1072
- if (limit !== this.limit) { this.limit = limit; this._apply({resort: false}); }
1199
+ if (this.$) this._reveal(at + dir);
1073
1200
  this.play(this.sounds.indexOf(target));
1074
1201
  return true;
1075
1202
  }
@@ -1128,7 +1255,7 @@ export class WaveformSounds extends EventTarget {
1128
1255
  * @internal
1129
1256
  */
1130
1257
  _onEngineLoad(): void {
1131
- if (this.currentIndex != null) this.rows[this.currentIndex]?.classList.remove('is-error');
1258
+ if (this.currentIndex != null) this._markFailed(this.currentIndex, false);
1132
1259
  if (this._eng()?.audio) this._eng()!.audio!.loop = this._repeats();
1133
1260
  const sound = this.sounds[this.currentIndex!];
1134
1261
  if (sound && !sound.peaks && this._eng()?.waveformData?.length) {
@@ -1185,7 +1312,7 @@ export class WaveformSounds extends EventTarget {
1185
1312
  _onEngineError(err: unknown): void {
1186
1313
  const index = this.currentIndex;
1187
1314
  const sound = index == null ? undefined : this.sounds[index];
1188
- if (index != null) this.rows[index]?.classList.add('is-error');
1315
+ if (index != null) this._markFailed(index, true);
1189
1316
  this._setPlaying(false);
1190
1317
  // A cued sound (strip, nothing played) wasn't asked for: no announcement.
1191
1318
  if (sound && !this._cued && this.$?.status) this.$.status.textContent = fill(this.strings.playError, {title: sound.title});
@@ -1209,7 +1336,7 @@ export class WaveformSounds extends EventTarget {
1209
1336
  if (on) this._cued = false; // the strip's own button played the cued sound
1210
1337
  const index = this.currentIndex;
1211
1338
  if (index == null) return;
1212
- if (on) this.rows[index]?.classList.remove('is-error'); // it plays after all
1339
+ if (on) this._markFailed(index, false); // it plays after all
1213
1340
  this._paintRow(index);
1214
1341
  const was = this._announced ?? null;
1215
1342
  if (on) {
@@ -1254,17 +1381,46 @@ export class WaveformSounds extends EventTarget {
1254
1381
  btn.setAttribute('aria-pressed', String(on));
1255
1382
  btn.setAttribute('aria-label', fill(on ? this.strings.pause : this.strings.play, {title: this.sounds[index].title}));
1256
1383
  }
1384
+ row.classList.toggle('is-error', this._failed.has(index));
1257
1385
  const wave = row.querySelector<HTMLElement>('.ws-wave');
1258
- if (wave) {
1259
- wave.tabIndex = current && row === this._active ? 0 : -1;
1260
- if (!current) {
1261
- wave.setAttribute('aria-valuenow', '0');
1262
- wave.removeAttribute('aria-valuetext');
1263
- }
1264
- }
1386
+ if (wave) this._paintWave(wave, current, row === this._active, this.sounds[index].title);
1265
1387
  this._drawRow(index);
1266
1388
  }
1267
1389
 
1390
+ /**
1391
+ * A row's waveform: the current sound's is THE seek slider (focusable,
1392
+ * labelled, with a value); every other one is a picture, hidden from
1393
+ * assistive tech and out of the Tab order (a pointer still seeks on it).
1394
+ * So a screen reader meets one slider, not one per row. Since 2.2.0.
1395
+ * @internal
1396
+ */
1397
+ _paintWave(wave: HTMLElement, current: boolean, active: boolean, title: string): void {
1398
+ if (!current) {
1399
+ if (wave.getAttribute('aria-hidden') === 'true' && !wave.hasAttribute('role')) return;
1400
+ for (const name of ['role', 'aria-label', 'aria-valuemin', 'aria-valuemax', 'aria-valuenow', 'aria-valuetext', 'tabindex']) wave.removeAttribute(name);
1401
+ wave.setAttribute('aria-hidden', 'true');
1402
+ return;
1403
+ }
1404
+ wave.removeAttribute('aria-hidden');
1405
+ wave.setAttribute('role', 'slider');
1406
+ wave.setAttribute('aria-label', fill(this.strings.seek, {title}));
1407
+ wave.setAttribute('aria-valuemin', '0');
1408
+ wave.setAttribute('aria-valuemax', '100');
1409
+ if (!wave.hasAttribute('aria-valuenow')) wave.setAttribute('aria-valuenow', String(Math.round(this.progress * 100)));
1410
+ wave.tabIndex = active ? 0 : -1;
1411
+ }
1412
+
1413
+ /**
1414
+ * Record that a sound failed (or played after all), on its row if it
1415
+ * has one; a row rendered later picks it up from `_failed`.
1416
+ * @internal
1417
+ */
1418
+ _markFailed(index: number, failed: boolean): void {
1419
+ if (failed) this._failed.add(index);
1420
+ else this._failed.delete(index);
1421
+ this.rows[index]?.classList.toggle('is-error', failed);
1422
+ }
1423
+
1268
1424
  /**
1269
1425
  * The current row's seek slider: its position (0–100) and, for a screen
1270
1426
  * reader, the time ("0:12 of 0:30").
@@ -1316,6 +1472,7 @@ export class WaveformSounds extends EventTarget {
1316
1472
  this.destroyed = true;
1317
1473
  this._ctl.abort();
1318
1474
  this._io?.disconnect();
1475
+ this._endIo?.disconnect();
1319
1476
  this._ro?.disconnect();
1320
1477
  this._mo?.disconnect();
1321
1478
  if (this._raf) cancelAnimationFrame(this._raf);
@@ -37,7 +37,7 @@ declare global {
37
37
  export const ELEMENT_OPTION_KEYS = [
38
38
  'player', 'manifest', 'search', 'filters', 'sorts', 'showCount', 'menuSearch', 'idPrefix', 'urlState',
39
39
  'loopToggle', 'pageSize', 'maxTypeChips', 'columns', 'waveformStyle', 'waveformColor', 'progressColor',
40
- 'barWidth', 'barGap', 'loop', 'autoAdvance', 'arrowAudition', 'strings', 'playerOptions',
40
+ 'barWidth', 'barGap', 'loop', 'autoAdvance', 'arrowAudition', 'strings', 'playerOptions', 'mergeEnharmonicKeys',
41
41
  ];
42
42
 
43
43
  /**
@@ -132,6 +132,7 @@ export function readDataOptions(el: HTMLElement): Record<string, any> {
132
132
  pageSize: parseNumber(d.pageSize),
133
133
  maxTypeChips: parseNumber(d.maxTypeChips),
134
134
  columns: parseList(d.columns),
135
+ mergeEnharmonicKeys: parseBool(d.mergeEnharmonicKeys),
135
136
  waveformStyle: d.waveformStyle || undefined,
136
137
  waveformColor: d.waveformColor || undefined,
137
138
  progressColor: d.progressColor || undefined,