@arraypress/waveform-sounds 0.3.0 → 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 +145 -98
  4. package/dist/waveform-sounds-render.esm.js +25 -11
  5. package/dist/waveform-sounds.css +66 -78
  6. package/dist/waveform-sounds.esm.js +146 -99
  7. package/dist/waveform-sounds.js +147 -99
  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 +66 -78
  12. package/src/js/core/{WaveformSounds.js → WaveformSounds.ts} +328 -189
  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} +67 -63
  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 -2136
  76. package/dist/waveform-sounds-render.cjs +0 -614
  77. package/dist/waveform-sounds.cjs +0 -2158
  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
@@ -1,3 +1,4 @@
1
+ "use strict";
1
2
  (() => {
2
3
  // node_modules/@arraypress/text/src/index.js
3
4
  var HTML_ESCAPES = Object.freeze({
@@ -9,13 +10,31 @@
9
10
  });
10
11
  function escapeHtml(input) {
11
12
  if (input === null || input === void 0) return "";
12
- return String(input).replace(/[&<>"']/g, (c) => HTML_ESCAPES[c]);
13
+ return String(input).replace(/[&<>"']/g, (c) => HTML_ESCAPES[
14
+ /** @type {keyof typeof HTML_ESCAPES} */
15
+ c
16
+ ]);
17
+ }
18
+ var NOT_A_WORD = /[^\p{L}\p{N}\p{M}]+/u;
19
+ var COMBINING_MARK = /\p{Mn}/gu;
20
+ var ACCENTS = Object.freeze([
21
+ [768, 879],
22
+ [1425, 1479],
23
+ [1552, 1562],
24
+ [1611, 1631],
25
+ [1648, 1648],
26
+ [6832, 6911],
27
+ [7616, 7679],
28
+ [8400, 8447],
29
+ [65056, 65071]
30
+ ]);
31
+ function isAccent(mark) {
32
+ const point = mark.codePointAt(0) ?? 0;
33
+ return ACCENTS.some(([from, to]) => point >= from && point <= to);
13
34
  }
14
- var NOT_A_WORD = /[^\p{L}\p{N}]+/u;
15
- var COMBINING_MARKS = /\p{Mn}+/gu;
16
35
  function fold(text2) {
17
36
  if (!text2 || typeof text2 !== "string") return "";
18
- return text2.toLowerCase().normalize("NFD").replace(COMBINING_MARKS, "");
37
+ return text2.toLowerCase().normalize("NFD").replace(COMBINING_MARK, (mark) => isAccent(mark) ? "" : mark).normalize("NFC");
19
38
  }
20
39
  function words(text2) {
21
40
  return fold(text2).split(NOT_A_WORD).filter((word) => word !== "");
@@ -53,7 +72,7 @@
53
72
  });
54
73
  }
55
74
 
56
- // src/js/data/sounds.js
75
+ // src/js/data/sounds.ts
57
76
  function encodePeaks(peaks) {
58
77
  if (!Array.isArray(peaks)) return "";
59
78
  let out = "";
@@ -99,7 +118,7 @@
99
118
  const s = Number(seconds);
100
119
  if (!Number.isFinite(s) || s < 0) return "";
101
120
  if (s > 0 && s < 0.95) return `${Math.max(0.1, Math.round(s * 10) / 10).toFixed(1)}s`;
102
- const total = Math.round(s);
121
+ const total = s < 1 ? Math.ceil(s) : Math.floor(s);
103
122
  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
104
123
  }
105
124
  function parseDuration(value) {
@@ -229,7 +248,7 @@
229
248
  return list.map((x) => x.s);
230
249
  }
231
250
 
232
- // src/js/dom/draw.js
251
+ // src/js/dom/draw.ts
233
252
  function fitCanvas(canvas) {
234
253
  const rect = canvas.getBoundingClientRect();
235
254
  if (!rect.width || !rect.height) return null;
@@ -296,8 +315,9 @@
296
315
  }
297
316
  }
298
317
 
299
- // src/js/core/engine.js
318
+ // src/js/core/engine.ts
300
319
  var CALLBACKS = ["onLoad", "onPlay", "onPause", "onEnd", "onTimeUpdate", "onError"];
320
+ var PER_TRACK = ["duration", "downloadUrl", "downloadName"];
301
321
  function engineOptions(user, layout, handlers) {
302
322
  const site = user || {};
303
323
  const strip = layout === "strip";
@@ -307,8 +327,11 @@
307
327
  preload: "metadata",
308
328
  singlePlay: true,
309
329
  ...site,
310
- audioMode: "self"
330
+ audioMode: "self",
331
+ loop: false,
332
+ showLoop: false
311
333
  };
334
+ for (const name of PER_TRACK) delete options[name];
312
335
  for (const name of CALLBACKS) {
313
336
  options[name] = (...args) => {
314
337
  handlers[name]?.(...args);
@@ -320,8 +343,14 @@
320
343
  function enginePeaks(sound, layout) {
321
344
  return layout === "strip" && sound.waveform || sound.peaks || null;
322
345
  }
346
+ function engineTrack(sound, layout, autoplay) {
347
+ const track = { waveform: enginePeaks(sound, layout), autoplay };
348
+ if (sound.duration != null && sound.duration > 0) track.duration = sound.duration;
349
+ if (sound.download) track.downloadUrl = sound.download;
350
+ return track;
351
+ }
323
352
 
324
- // src/js/dom/menus.js
353
+ // src/js/dom/menus.ts
325
354
  function optionMatches(label, query) {
326
355
  const q = fold(String(query ?? "")).trim();
327
356
  return !q || fold(String(label ?? "")).includes(q);
@@ -357,8 +386,8 @@
357
386
  }
358
387
  /**
359
388
  * Wire every menu, plus closing on an outside press or focus leaving.
360
- * @param {AbortSignal} signal
361
- * @private
389
+ * @param signal
390
+ * @internal
362
391
  */
363
392
  _bind(signal) {
364
393
  const sig = { signal };
@@ -400,7 +429,7 @@
400
429
  * focus in its search field or list. Flips to open over the end edge
401
430
  * when it would overflow the list.
402
431
  *
403
- * @param {HTMLElement} menu
432
+ * @param menu
404
433
  */
405
434
  open(menu) {
406
435
  if (this.openMenu && this.openMenu !== menu) this.close(false);
@@ -420,7 +449,7 @@
420
449
  /**
421
450
  * Close the open menu, if any.
422
451
  *
423
- * @param {boolean} focusButton - Return focus to its button (after a
452
+ * @param focusButton - Return focus to its button (after a
424
453
  * pick or Esc; not after a click elsewhere).
425
454
  */
426
455
  close(focusButton) {
@@ -436,8 +465,8 @@
436
465
  * Show `value` as a menu's choice (button text + `aria-selected`). Used
437
466
  * after a pick and when the filter is changed from code.
438
467
  *
439
- * @param {string} name - 'type' | 'key' | 'sort'.
440
- * @param {string} value
468
+ * @param name - 'type' | 'key' | 'sort'.
469
+ * @param value
441
470
  */
442
471
  setValue(name, value) {
443
472
  const menu = this.menus[name];
@@ -455,7 +484,7 @@
455
484
  /**
456
485
  * Narrow a menu to the options matching the search, and make the first
457
486
  * match active.
458
- * @private
487
+ * @internal
459
488
  */
460
489
  _filter(menu, query) {
461
490
  const p = partsOf(menu);
@@ -470,7 +499,7 @@
470
499
  /**
471
500
  * Mark one option active (`aria-activedescendant`) and scroll it into
472
501
  * the list's view.
473
- * @private
502
+ * @internal
474
503
  */
475
504
  _activate(menu, opt) {
476
505
  const p = partsOf(menu);
@@ -486,7 +515,7 @@
486
515
  }
487
516
  /**
488
517
  * Keys inside an open menu.
489
- * @private
518
+ * @internal
490
519
  */
491
520
  _onKey(e, name, menu) {
492
521
  const p = partsOf(menu);
@@ -522,7 +551,7 @@
522
551
  }
523
552
  /**
524
553
  * A value was chosen: close, then report it.
525
- * @private
554
+ * @internal
526
555
  */
527
556
  _pick(name, value) {
528
557
  this.close(true);
@@ -530,7 +559,7 @@
530
559
  }
531
560
  };
532
561
 
533
- // src/js/shared/utils.js
562
+ // src/js/shared/utils.ts
534
563
  var LOG = "[WaveformSounds]";
535
564
  function clamp(value, min = 0, max = 1) {
536
565
  return Math.min(Math.max(value, min), max);
@@ -552,7 +581,7 @@
552
581
  return hash;
553
582
  }
554
583
 
555
- // src/js/data/navigation.js
584
+ // src/js/data/navigation.ts
556
585
  var SEEK_STEP = 0.1;
557
586
  function rowTarget(key, at, count) {
558
587
  if (!count) return null;
@@ -581,7 +610,7 @@
581
610
  return pos >= limit ? pos + 1 : limit;
582
611
  }
583
612
 
584
- // src/js/data/bpm.js
613
+ // src/js/data/bpm.ts
585
614
  function bpmFilterFromRange(lo, hi, extent) {
586
615
  const a = Math.min(lo, hi), b = Math.max(lo, hi);
587
616
  return {
@@ -606,7 +635,7 @@
606
635
  return filter.bpmMin != null && filter.bpmMin !== "" || filter.bpmMax != null && filter.bpmMax !== "";
607
636
  }
608
637
 
609
- // src/js/render/strings.js
638
+ // src/js/render/strings.ts
610
639
  var DEFAULT_STRINGS = {
611
640
  search: "Search sounds",
612
641
  searchPlaceholder: "Search sounds\u2026",
@@ -667,7 +696,7 @@
667
696
  return total === 1 ? strings.countOne : fill(strings.count, { count: total });
668
697
  }
669
698
 
670
- // src/js/render/options.js
699
+ // src/js/render/options.ts
671
700
  var FILTERS = ["type", "key", "bpm", "loop"];
672
701
  var COLUMNS = ["type", "bpm", "key", "duration"];
673
702
  var RENDER_DEFAULTS = {
@@ -709,7 +738,7 @@
709
738
  };
710
739
  }
711
740
 
712
- // src/js/core/options.js
741
+ // src/js/core/options.ts
713
742
  var DEFAULT_OPTIONS = {
714
743
  ...RENDER_DEFAULTS,
715
744
  sounds: null,
@@ -722,6 +751,8 @@
722
751
  loop: null,
723
752
  autoAdvance: false,
724
753
  arrowAudition: true,
754
+ // null is "unset" (the container's id, else a hash); the public type,
755
+ // unchanged from 0.3.1, has no null, hence the cast (it emits nothing).
725
756
  idPrefix: null,
726
757
  urlState: false,
727
758
  playerOptions: null,
@@ -799,7 +830,7 @@
799
830
  return out;
800
831
  }
801
832
 
802
- // src/js/render/html.js
833
+ // src/js/render/html.ts
803
834
  var VOID = /* @__PURE__ */ new Set(["input", "br", "img"]);
804
835
  function text(value) {
805
836
  return escapeHtml(value ?? "");
@@ -818,7 +849,7 @@
818
849
  return open + children.flat(Infinity).filter((c) => c != null && c !== false && c !== "").join("") + `</${tag}>`;
819
850
  }
820
851
 
821
- // src/js/render/icons.js
852
+ // src/js/render/icons.ts
822
853
  function icon(path, extraClass = "") {
823
854
  const cls = extraClass ? `ws-icon ${extraClass}` : "ws-icon";
824
855
  return `<svg class="${cls}" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="${path}"/></svg>`;
@@ -833,7 +864,7 @@
833
864
  loop: icon("M17 4l3 3-3 3V8H8a3 3 0 0 0-3 3v1H3v-1a5 5 0 0 1 5-5h9V4zM7 20l-3-3 3-3v2h9a3 3 0 0 0 3-3v-1h2v1a5 5 0 0 1-5 5H7v2z")
834
865
  };
835
866
 
836
- // src/js/render/markup.js
867
+ // src/js/render/markup.ts
837
868
  function idBase(sounds) {
838
869
  const signature = [sounds.length, ...sounds.map((s) => s.url)].join("|");
839
870
  return `ws${hashString(signature).toString(36)}`;
@@ -1099,7 +1130,7 @@
1099
1130
  return h("div", { class: cls, "data-waveform-sounds": true, "data-player": o.player }, renderSounds(sounds, options));
1100
1131
  }
1101
1132
 
1102
- // src/js/dom/rows.js
1133
+ // src/js/dom/rows.ts
1103
1134
  var ROW = ":scope > [data-ws-index]";
1104
1135
  function readRows(list) {
1105
1136
  const rows = [...list.querySelectorAll(ROW)].sort((a, b) => Number(a.dataset.wsIndex) - Number(b.dataset.wsIndex));
@@ -1145,7 +1176,7 @@
1145
1176
  list.appendChild(frag);
1146
1177
  }
1147
1178
 
1148
- // src/js/dom/colors.js
1179
+ // src/js/dom/colors.ts
1149
1180
  function parseAlpha(color) {
1150
1181
  const c = String(color ?? "").trim();
1151
1182
  if (!c || c === "transparent") return 0;
@@ -1172,7 +1203,7 @@
1172
1203
  return color;
1173
1204
  }
1174
1205
 
1175
- // src/js/data/url-state.js
1206
+ // src/js/data/url-state.ts
1176
1207
  function urlKeys(urlState) {
1177
1208
  if (!urlState) return null;
1178
1209
  const p = typeof urlState === "string" ? `${urlState}-` : "";
@@ -1217,17 +1248,17 @@
1217
1248
  return url.href;
1218
1249
  }
1219
1250
 
1220
- // src/js/core/WaveformSounds.js
1251
+ // src/js/core/WaveformSounds.ts
1221
1252
  var NO_FILTER = Object.freeze({ query: "", type: "", key: "", bpmMin: "", bpmMax: "", loop: "" });
1222
1253
  var SEARCH_DELAY = 120;
1223
1254
  var BPM_DELAY = 200;
1224
1255
  var URL_DELAY = 250;
1225
1256
  var WaveformSounds = class _WaveformSounds {
1226
- /** @type {Map<Element, WaveformSounds>} */
1257
+ /** Every live instance, by its element. */
1227
1258
  static instances = /* @__PURE__ */ new Map();
1228
1259
  /**
1229
1260
  * @param {HTMLElement|string} container - The element (or a selector).
1230
- * @param {import('../../../index').WaveformSoundsOptions} [options]
1261
+ * @param {WaveformSoundsOptions} [options]
1231
1262
  */
1232
1263
  constructor(container, options = {}) {
1233
1264
  const el = typeof container === "string" ? document.querySelector(container) : container;
@@ -1265,7 +1296,7 @@
1265
1296
  /**
1266
1297
  * Adopt server-rendered markup or render it (from `sounds` or a fetched
1267
1298
  * manifest), then wire everything up.
1268
- * @private
1299
+ * @internal
1269
1300
  */
1270
1301
  async _init() {
1271
1302
  const el = this.container;
@@ -1294,13 +1325,14 @@
1294
1325
  this._syncControls();
1295
1326
  this._apply({ resort: this.sortBy !== "default" });
1296
1327
  if (this._playerClass()) this._ensureEngine();
1328
+ if (this.render.player === "strip" && this.engine && this.currentIndex == null) this._cueFirst();
1297
1329
  this._emit("ready", { sounds: this.sounds.length });
1298
1330
  this.options.onReady?.(this);
1299
1331
  }
1300
1332
  /**
1301
1333
  * The sounds from the `sounds` option, else the `manifest` URL.
1302
- * @returns {Promise<import('../../../index').Sound[]>}
1303
- * @private
1334
+ * @returns
1335
+ * @internal
1304
1336
  */
1305
1337
  async _loadSounds() {
1306
1338
  if (this.options.sounds || !this.options.manifest) return normalizeSounds(this.options.sounds || []);
@@ -1310,7 +1342,7 @@
1310
1342
  }
1311
1343
  /**
1312
1344
  * Look up the elements the runtime drives.
1313
- * @private
1345
+ * @internal
1314
1346
  */
1315
1347
  _cacheRefs() {
1316
1348
  const q = (sel) => this.container.querySelector(sel);
@@ -1337,7 +1369,7 @@
1337
1369
  /**
1338
1370
  * Every listener. All are removed by `destroy()` through one
1339
1371
  * AbortController.
1340
- * @private
1372
+ * @internal
1341
1373
  */
1342
1374
  _bind() {
1343
1375
  const sig = { signal: this._ctl.signal };
@@ -1389,7 +1421,7 @@
1389
1421
  /**
1390
1422
  * Clicks: type chips, loops or one-shots, Show more, Clear, Loop, a touch tap on a waveform
1391
1423
  * (seek), and anywhere else on a row (play/pause).
1392
- * @private
1424
+ * @internal
1393
1425
  */
1394
1426
  _onClick(e) {
1395
1427
  const t = e.target;
@@ -1428,7 +1460,7 @@
1428
1460
  /**
1429
1461
  * Mouse and pen seek on PRESS, like every scrubber. Remembers the
1430
1462
  * pointer type for the click that follows.
1431
- * @private
1463
+ * @internal
1432
1464
  */
1433
1465
  _onPointerDown(e) {
1434
1466
  this._lastPointer = e.pointerType;
@@ -1439,7 +1471,7 @@
1439
1471
  }
1440
1472
  /**
1441
1473
  * Seek (or start) a row's sound where its waveform was pressed.
1442
- * @private
1474
+ * @internal
1443
1475
  */
1444
1476
  _seekAt(wave, clientX) {
1445
1477
  const row = wave.closest("[data-ws-index]");
@@ -1449,7 +1481,7 @@
1449
1481
  /**
1450
1482
  * Keys on the list: `/` focuses search; ↑/↓/Home/End move between rows
1451
1483
  * (auditioning while something plays); ←/→ seek the playing row.
1452
- * @private
1484
+ * @internal
1453
1485
  */
1454
1486
  _onKey(e) {
1455
1487
  if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return;
@@ -1481,7 +1513,7 @@
1481
1513
  }
1482
1514
  /**
1483
1515
  * Focus a row's play button.
1484
- * @private
1516
+ * @internal
1485
1517
  */
1486
1518
  _focusRow(row) {
1487
1519
  row?.querySelector(".ws-play")?.focus();
@@ -1492,7 +1524,7 @@
1492
1524
  * on the title or waveform left focus on <body>, and Safari never
1493
1525
  * focuses a clicked button). No scroll jump, and no focus ring: the
1494
1526
  * browser shows none for a focus that follows a pointer.
1495
- * @private
1527
+ * @internal
1496
1528
  */
1497
1529
  _focusRowQuietly(row) {
1498
1530
  const btn = row?.querySelector(".ws-play");
@@ -1502,7 +1534,7 @@
1502
1534
  /**
1503
1535
  * Draw row canvases as they scroll into view; redraw on resize and on
1504
1536
  * theme flips (the canvas can't follow CSS by itself).
1505
- * @private
1537
+ * @internal
1506
1538
  */
1507
1539
  _observe() {
1508
1540
  if (this.render.player !== "inline" || typeof window === "undefined") return;
@@ -1546,7 +1578,7 @@
1546
1578
  /**
1547
1579
  * Resolve the canvas colours (options, else the CSS custom properties)
1548
1580
  * and keep `--ws-surface` current unless the site set it.
1549
- * @private
1581
+ * @internal
1550
1582
  */
1551
1583
  _resolveColors() {
1552
1584
  if (this._autoSurface || !getComputedStyle(this.container).getPropertyValue("--ws-surface").trim()) {
@@ -1561,7 +1593,7 @@
1561
1593
  }
1562
1594
  /**
1563
1595
  * Draw one row's waveform (only once it has been on screen).
1564
- * @private
1596
+ * @internal
1565
1597
  */
1566
1598
  _drawRow(index) {
1567
1599
  if (this.render.player !== "inline" || index == null || !this._drawn?.has(index)) return;
@@ -1579,7 +1611,7 @@
1579
1611
  }
1580
1612
  /**
1581
1613
  * Redraw every row drawn so far.
1582
- * @private
1614
+ * @internal
1583
1615
  */
1584
1616
  _redrawAll() {
1585
1617
  this._drawn?.forEach((i) => this._drawRow(i));
@@ -1587,7 +1619,7 @@
1587
1619
  /* ── Filters in the address ───────────────────────────────────────── */
1588
1620
  /**
1589
1621
  * Apply the filter and sort from the address (`urlState`).
1590
- * @private
1622
+ * @internal
1591
1623
  */
1592
1624
  _readUrl() {
1593
1625
  const keys = urlKeys(this.options.urlState);
@@ -1602,7 +1634,7 @@
1602
1634
  /**
1603
1635
  * Rewrite the address shortly after a change (replaceState: no history
1604
1636
  * entries).
1605
- * @private
1637
+ * @internal
1606
1638
  */
1607
1639
  _queueUrl() {
1608
1640
  const keys = urlKeys(this.options.urlState);
@@ -1619,12 +1651,6 @@
1619
1651
  get visible() {
1620
1652
  return sortSounds(this.sounds.filter((s) => matches(s, this.filter)), this.sortBy);
1621
1653
  }
1622
- /**
1623
- * Change the filter (merged into the current one) and re-apply. Back to
1624
- * the first page.
1625
- *
1626
- * @param {Partial<import('../../../index').SoundsFilter>} patch
1627
- */
1628
1654
  setFilter(patch = {}) {
1629
1655
  this.filter = { ...this.filter, ...patch };
1630
1656
  this.limit = this._pageSize();
@@ -1635,7 +1661,7 @@
1635
1661
  clearFilters() {
1636
1662
  this.setFilter(NO_FILTER);
1637
1663
  }
1638
- /** @param {import('../../../index').SoundsSort} by */
1664
+ /** @param by */
1639
1665
  setSort(by) {
1640
1666
  this._sortSet = true;
1641
1667
  this.sortBy = SORTS.includes(by) ? by : "default";
@@ -1650,7 +1676,7 @@
1650
1676
  }
1651
1677
  /**
1652
1678
  * Rows per page (Infinity when paging is off).
1653
- * @private
1679
+ * @internal
1654
1680
  */
1655
1681
  _pageSize() {
1656
1682
  return this.render.pageSize > 0 ? this.render.pageSize : Infinity;
@@ -1658,7 +1684,7 @@
1658
1684
  /**
1659
1685
  * Show the current filter and sort in the controls (they can be set from
1660
1686
  * code or the address, not only by the controls themselves).
1661
- * @private
1687
+ * @internal
1662
1688
  */
1663
1689
  _syncControls() {
1664
1690
  const $ = this.$, f = this.filter;
@@ -1680,7 +1706,7 @@
1680
1706
  * Show a BPM filter in its menu: the button label, the panel's readout,
1681
1707
  * the filled part of the track, and which handle sits on top (the one
1682
1708
  * that can still move, when they meet).
1683
- * @private
1709
+ * @internal
1684
1710
  */
1685
1711
  _showBpm(f) {
1686
1712
  const $ = this.$, extent = this._bpmExtent;
@@ -1697,9 +1723,9 @@
1697
1723
  * Lay the rows out for the current filter, sort and page: order, hide,
1698
1724
  * "Show more", the empty state and the count. Then report it.
1699
1725
  *
1700
- * @param {{resort: boolean}} opts - Reorder the rows even if the sort
1726
+ * @param opts - Reorder the rows even if the sort
1701
1727
  * hasn't changed.
1702
- * @private
1728
+ * @internal
1703
1729
  */
1704
1730
  _apply({ resort }) {
1705
1731
  const $ = this.$;
@@ -1719,6 +1745,7 @@
1719
1745
  }
1720
1746
  if ($.empty) $.empty.hidden = shown.length > 0;
1721
1747
  if ($.count) $.count.textContent = countText(shown.length, this.sounds.length, this.strings);
1748
+ if (this._cued && !this.playing) this._cueFirst();
1722
1749
  this._queueUrl();
1723
1750
  this._emit("filter", { visible: shown.length, total: this.sounds.length, filter: { ...this.filter }, sort: this.sortBy });
1724
1751
  this.options.onFilter?.(shown, this);
@@ -1728,9 +1755,9 @@
1728
1755
  * Resolve an index, id or sound to an index in `this.sounds`. No
1729
1756
  * target means the current sound, else the first visible one.
1730
1757
  *
1731
- * @param {number|string|Object} [target]
1732
- * @returns {number|null}
1733
- * @private
1758
+ * @param target
1759
+ * @returns
1760
+ * @internal
1734
1761
  */
1735
1762
  _indexOf(target) {
1736
1763
  if (target == null) return this.currentIndex ?? (this.visible[0] ? this.sounds.indexOf(this.visible[0]) : null);
@@ -1740,8 +1767,8 @@
1740
1767
  }
1741
1768
  /**
1742
1769
  * The WaveformPlayer class: `playerClass`, else the page's global.
1743
- * @returns {Function|null}
1744
- * @private
1770
+ * @returns
1771
+ * @internal
1745
1772
  */
1746
1773
  _playerClass() {
1747
1774
  return this.options.playerClass || (typeof window !== "undefined" ? window.WaveformPlayer : null) || null;
@@ -1752,8 +1779,8 @@
1752
1779
  * which would strip `ws-engine--strip` (and with it the docked styling).
1753
1780
  * Made here rather than in the markup so server-rendered HTML from any
1754
1781
  * version works.
1755
- * @returns {HTMLElement}
1756
- * @private
1782
+ * @returns
1783
+ * @internal
1757
1784
  */
1758
1785
  _engineMount() {
1759
1786
  const slot = this.$.engine;
@@ -1767,8 +1794,8 @@
1767
1794
  }
1768
1795
  /**
1769
1796
  * Build the engine once (it holds no audio until a play).
1770
- * @returns {Object|null} The engine, or null without a player class.
1771
- * @private
1797
+ * @returns The engine, or null without a player class.
1798
+ * @internal
1772
1799
  */
1773
1800
  _ensureEngine() {
1774
1801
  if (this.engine) return this.engine;
@@ -1791,8 +1818,8 @@
1791
1818
  * Play a sound (by index, id or sound object), or resume the current
1792
1819
  * one. Before the list is built the call waits for it.
1793
1820
  *
1794
- * @param {number|string|Object} [target]
1795
- * @param {{at?: number}} [opts] - `at`: start position 0..1.
1821
+ * @param target
1822
+ * @param opts - `at`: start position 0..1.
1796
1823
  */
1797
1824
  play(target, opts = {}) {
1798
1825
  if (!this.$) {
@@ -1803,6 +1830,7 @@
1803
1830
  }
1804
1831
  const index = this._indexOf(target);
1805
1832
  if (index == null) return;
1833
+ this._cued = false;
1806
1834
  const engine = this._ensureEngine();
1807
1835
  if (!engine) return;
1808
1836
  if (index === this.currentIndex && engine.audio?.src) {
@@ -1817,7 +1845,26 @@
1817
1845
  if (previous != null) this._paintRow(previous);
1818
1846
  this._paintRow(index);
1819
1847
  const sound = this.sounds[index];
1820
- engine.loadTrack(sound.url, sound.title, sound.type || null, { waveform: enginePeaks(sound, this.render.player), autoplay: true });
1848
+ engine.loadTrack(sound.url, sound.title, sound.type || null, engineTrack(sound, this.render.player, true));
1849
+ }
1850
+ /**
1851
+ * Strip layout: load the first sound the list shows into the docked
1852
+ * player WITHOUT playing it, so the player shows a title and waveform
1853
+ * (and its play button plays that sound) instead of an empty frame.
1854
+ * Only metadata is fetched — the browser default for any `<audio>`.
1855
+ * The row isn't marked current until it plays.
1856
+ * @internal
1857
+ */
1858
+ _cueFirst() {
1859
+ const engine = this.engine;
1860
+ const first = this.visible[0];
1861
+ if (!engine || !first) return;
1862
+ const index = this.sounds.indexOf(first);
1863
+ if (index === this.currentIndex) return;
1864
+ this.currentIndex = index;
1865
+ this.progress = 0;
1866
+ this._cued = true;
1867
+ engine.loadTrack(first.url, first.title, first.type || null, engineTrack(first, "strip", false));
1821
1868
  }
1822
1869
  /** Pause the current sound. */
1823
1870
  pause() {
@@ -1825,7 +1872,7 @@
1825
1872
  }
1826
1873
  /**
1827
1874
  * The current sound plays/pauses; another sound starts.
1828
- * @param {number|string|Object} [target]
1875
+ * @param target
1829
1876
  */
1830
1877
  toggle(target) {
1831
1878
  const index = this._indexOf(target);
@@ -1845,13 +1892,13 @@
1845
1892
  * Play the visible sound `dir` places away, revealing it if it's past
1846
1893
  * the current page.
1847
1894
  *
1848
- * @param {1|-1} dir
1849
- * @returns {boolean} Whether there was one.
1850
- * @private
1895
+ * @param dir
1896
+ * @returns Whether there was one.
1897
+ * @internal
1851
1898
  */
1852
1899
  _step(dir) {
1853
1900
  const shown = this.visible;
1854
- const at = this.currentIndex == null ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
1901
+ const at = this.currentIndex == null || this._cued ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
1855
1902
  const target = shown[at + dir];
1856
1903
  if (!target) return false;
1857
1904
  const limit = limitToReveal(this.limit, at + dir);
@@ -1866,7 +1913,7 @@
1866
1913
  * Loop the current sound (auditioning a loop is the common case). When
1867
1914
  * the list marks its loops (`loop: true` on any sound), only those
1868
1915
  * repeat: a one-shot always plays once.
1869
- * @param {boolean} on
1916
+ * @param on
1870
1917
  */
1871
1918
  setLoop(on) {
1872
1919
  this._loopSet = true;
@@ -1875,7 +1922,7 @@
1875
1922
  }
1876
1923
  /**
1877
1924
  * Apply the loop state to the toggle and the engine.
1878
- * @private
1925
+ * @internal
1879
1926
  */
1880
1927
  _setLoop(on) {
1881
1928
  this.$?.loop?.setAttribute("aria-pressed", String(on));
@@ -1884,7 +1931,7 @@
1884
1931
  /**
1885
1932
  * Should the current sound repeat? The Loop toggle is on, and either
1886
1933
  * the list doesn't say which sounds are loops or this one is.
1887
- * @private
1934
+ * @internal
1888
1935
  */
1889
1936
  _repeats() {
1890
1937
  if (!this.loop) return false;
@@ -1894,7 +1941,7 @@
1894
1941
  /**
1895
1942
  * Seek a row's sound to `fraction`; a row that isn't current starts
1896
1943
  * there. Before the duration is known the seek waits for it.
1897
- * @private
1944
+ * @internal
1898
1945
  */
1899
1946
  _seekRow(index, fraction) {
1900
1947
  if (index !== this.currentIndex || !this.engine) {
@@ -1914,7 +1961,7 @@
1914
1961
  /**
1915
1962
  * The engine loaded a sound: apply the loop, borrow decoded peaks for a
1916
1963
  * row that had none, and land a pending seek.
1917
- * @private
1964
+ * @internal
1918
1965
  */
1919
1966
  _onEngineLoad() {
1920
1967
  if (this.engine?.audio) this.engine.audio.loop = this._repeats();
@@ -1932,7 +1979,7 @@
1932
1979
  }
1933
1980
  /**
1934
1981
  * Playback progress: repaint the current row, once per frame.
1935
- * @private
1982
+ * @internal
1936
1983
  */
1937
1984
  _onTime(time, duration) {
1938
1985
  if (this.currentIndex == null || !duration) return;
@@ -1952,7 +1999,7 @@
1952
1999
  }
1953
2000
  /**
1954
2001
  * A sound finished: report it, then auto-advance or settle.
1955
- * @private
2002
+ * @internal
1956
2003
  */
1957
2004
  _onEnd() {
1958
2005
  const sound = this.sounds[this.currentIndex];
@@ -1964,7 +2011,7 @@
1964
2011
  }
1965
2012
  /**
1966
2013
  * A sound failed to load or play: mark its row and report it.
1967
- * @private
2014
+ * @internal
1968
2015
  */
1969
2016
  _onEngineError(err) {
1970
2017
  this.rows[this.currentIndex]?.classList.add("is-error");
@@ -1975,11 +2022,12 @@
1975
2022
  * Record play/pause and repaint. Events fire only on a real change: at a
1976
2023
  * natural end the browser fires `pause` then `ended`, and `_onEnd()`
1977
2024
  * also settles the state — one pause event, not two.
1978
- * @private
2025
+ * @internal
1979
2026
  */
1980
2027
  _setPlaying(on) {
1981
2028
  const changed = this.playing !== on;
1982
2029
  this.playing = on;
2030
+ if (on) this._cued = false;
1983
2031
  const index = this.currentIndex;
1984
2032
  if (index == null) return;
1985
2033
  this._paintRow(index);
@@ -1992,7 +2040,7 @@
1992
2040
  /* ── Row painting ─────────────────────────────────────────────────── */
1993
2041
  /**
1994
2042
  * A row's state classes, play-button label and waveform.
1995
- * @private
2043
+ * @internal
1996
2044
  */
1997
2045
  _paintRow(index) {
1998
2046
  const row = this.rows[index];
@@ -2016,14 +2064,14 @@
2016
2064
  /* ── Events & lifecycle ──────────────────────────────────────────── */
2017
2065
  /**
2018
2066
  * Emit a `waveformsounds:<name>` event carrying this instance.
2019
- * @private
2067
+ * @internal
2020
2068
  */
2021
2069
  _emit(name, detail = {}) {
2022
2070
  emit(this.container, name, { ...detail, instance: this });
2023
2071
  }
2024
2072
  /** The sound playing (or paused) now, or null. */
2025
2073
  get current() {
2026
- return this.currentIndex == null ? null : this.sounds[this.currentIndex];
2074
+ return this.currentIndex == null || this._cued ? null : this.sounds[this.currentIndex];
2027
2075
  }
2028
2076
  /**
2029
2077
  * Tear down: listeners, observers, timers and the engine. Markup this
@@ -2056,8 +2104,8 @@
2056
2104
  /**
2057
2105
  * Initialise every `[data-waveform-sounds]` under `root` that isn't yet.
2058
2106
  *
2059
- * @param {ParentNode} [root=document]
2060
- * @returns {WaveformSounds[]} The new instances.
2107
+ * @param root
2108
+ * @returns The new instances.
2061
2109
  */
2062
2110
  static init(root = document) {
2063
2111
  if (typeof document === "undefined") return [];
@@ -2076,8 +2124,8 @@
2076
2124
  }
2077
2125
  /**
2078
2126
  * The instance on an element (or selector), if any.
2079
- * @param {Element|string} el
2080
- * @returns {WaveformSounds|null}
2127
+ * @param el
2128
+ * @returns
2081
2129
  */
2082
2130
  static getInstance(el) {
2083
2131
  const node = typeof el === "string" ? document.querySelector(el) : el;
@@ -2090,14 +2138,14 @@
2090
2138
  }
2091
2139
  };
2092
2140
 
2093
- // src/js/entry.js
2141
+ // src/js/entry.ts
2094
2142
  WaveformSounds.utils = { encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration, renderSounds };
2095
2143
  WaveformSounds.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
2096
2144
  WaveformSounds.DEFAULT_STRINGS = DEFAULT_STRINGS;
2097
2145
  if (typeof window !== "undefined") window.WaveformSounds = WaveformSounds;
2098
2146
  var entry_default = WaveformSounds;
2099
2147
 
2100
- // src/js/index.js
2148
+ // src/js/index.ts
2101
2149
  var index_default = entry_default;
2102
2150
  if (typeof document !== "undefined" && document.documentElement?.dataset?.waveformAutoinit !== "false") {
2103
2151
  if (document.readyState === "loading") {