@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
@@ -8,13 +8,31 @@ var HTML_ESCAPES = Object.freeze({
8
8
  });
9
9
  function escapeHtml(input) {
10
10
  if (input === null || input === void 0) return "";
11
- return String(input).replace(/[&<>"']/g, (c) => HTML_ESCAPES[c]);
11
+ return String(input).replace(/[&<>"']/g, (c) => HTML_ESCAPES[
12
+ /** @type {keyof typeof HTML_ESCAPES} */
13
+ c
14
+ ]);
15
+ }
16
+ var NOT_A_WORD = /[^\p{L}\p{N}\p{M}]+/u;
17
+ var COMBINING_MARK = /\p{Mn}/gu;
18
+ var ACCENTS = Object.freeze([
19
+ [768, 879],
20
+ [1425, 1479],
21
+ [1552, 1562],
22
+ [1611, 1631],
23
+ [1648, 1648],
24
+ [6832, 6911],
25
+ [7616, 7679],
26
+ [8400, 8447],
27
+ [65056, 65071]
28
+ ]);
29
+ function isAccent(mark) {
30
+ const point = mark.codePointAt(0) ?? 0;
31
+ return ACCENTS.some(([from, to]) => point >= from && point <= to);
12
32
  }
13
- var NOT_A_WORD = /[^\p{L}\p{N}]+/u;
14
- var COMBINING_MARKS = /\p{Mn}+/gu;
15
33
  function fold(text2) {
16
34
  if (!text2 || typeof text2 !== "string") return "";
17
- return text2.toLowerCase().normalize("NFD").replace(COMBINING_MARKS, "");
35
+ return text2.toLowerCase().normalize("NFD").replace(COMBINING_MARK, (mark) => isAccent(mark) ? "" : mark).normalize("NFC");
18
36
  }
19
37
  function words(text2) {
20
38
  return fold(text2).split(NOT_A_WORD).filter((word) => word !== "");
@@ -52,7 +70,7 @@ function matchesAll(name, query, options = {}) {
52
70
  });
53
71
  }
54
72
 
55
- // src/js/data/sounds.js
73
+ // src/js/data/sounds.ts
56
74
  function encodePeaks(peaks) {
57
75
  if (!Array.isArray(peaks)) return "";
58
76
  let out = "";
@@ -228,7 +246,7 @@ function sortSounds(sounds, by = "default") {
228
246
  return list.map((x) => x.s);
229
247
  }
230
248
 
231
- // src/js/dom/draw.js
249
+ // src/js/dom/draw.ts
232
250
  function fitCanvas(canvas) {
233
251
  const rect = canvas.getBoundingClientRect();
234
252
  if (!rect.width || !rect.height) return null;
@@ -295,8 +313,9 @@ function drawRowWaveform(canvas, peaks, progress, o) {
295
313
  }
296
314
  }
297
315
 
298
- // src/js/core/engine.js
316
+ // src/js/core/engine.ts
299
317
  var CALLBACKS = ["onLoad", "onPlay", "onPause", "onEnd", "onTimeUpdate", "onError"];
318
+ var PER_TRACK = ["duration", "downloadUrl", "downloadName"];
300
319
  function engineOptions(user, layout, handlers) {
301
320
  const site = user || {};
302
321
  const strip = layout === "strip";
@@ -306,8 +325,11 @@ function engineOptions(user, layout, handlers) {
306
325
  preload: "metadata",
307
326
  singlePlay: true,
308
327
  ...site,
309
- audioMode: "self"
328
+ audioMode: "self",
329
+ loop: false,
330
+ showLoop: false
310
331
  };
332
+ for (const name of PER_TRACK) delete options[name];
311
333
  for (const name of CALLBACKS) {
312
334
  options[name] = (...args) => {
313
335
  handlers[name]?.(...args);
@@ -319,8 +341,14 @@ function engineOptions(user, layout, handlers) {
319
341
  function enginePeaks(sound, layout) {
320
342
  return layout === "strip" && sound.waveform || sound.peaks || null;
321
343
  }
344
+ function engineTrack(sound, layout, autoplay) {
345
+ const track = { waveform: enginePeaks(sound, layout), autoplay };
346
+ if (sound.duration != null && sound.duration > 0) track.duration = sound.duration;
347
+ if (sound.download) track.downloadUrl = sound.download;
348
+ return track;
349
+ }
322
350
 
323
- // src/js/dom/menus.js
351
+ // src/js/dom/menus.ts
324
352
  function optionMatches(label, query) {
325
353
  const q = fold(String(query ?? "")).trim();
326
354
  return !q || fold(String(label ?? "")).includes(q);
@@ -356,8 +384,8 @@ var Menus = class {
356
384
  }
357
385
  /**
358
386
  * Wire every menu, plus closing on an outside press or focus leaving.
359
- * @param {AbortSignal} signal
360
- * @private
387
+ * @param signal
388
+ * @internal
361
389
  */
362
390
  _bind(signal) {
363
391
  const sig = { signal };
@@ -399,7 +427,7 @@ var Menus = class {
399
427
  * focus in its search field or list. Flips to open over the end edge
400
428
  * when it would overflow the list.
401
429
  *
402
- * @param {HTMLElement} menu
430
+ * @param menu
403
431
  */
404
432
  open(menu) {
405
433
  if (this.openMenu && this.openMenu !== menu) this.close(false);
@@ -419,7 +447,7 @@ var Menus = class {
419
447
  /**
420
448
  * Close the open menu, if any.
421
449
  *
422
- * @param {boolean} focusButton - Return focus to its button (after a
450
+ * @param focusButton - Return focus to its button (after a
423
451
  * pick or Esc; not after a click elsewhere).
424
452
  */
425
453
  close(focusButton) {
@@ -435,8 +463,8 @@ var Menus = class {
435
463
  * Show `value` as a menu's choice (button text + `aria-selected`). Used
436
464
  * after a pick and when the filter is changed from code.
437
465
  *
438
- * @param {string} name - 'type' | 'key' | 'sort'.
439
- * @param {string} value
466
+ * @param name - 'type' | 'key' | 'sort'.
467
+ * @param value
440
468
  */
441
469
  setValue(name, value) {
442
470
  const menu = this.menus[name];
@@ -454,7 +482,7 @@ var Menus = class {
454
482
  /**
455
483
  * Narrow a menu to the options matching the search, and make the first
456
484
  * match active.
457
- * @private
485
+ * @internal
458
486
  */
459
487
  _filter(menu, query) {
460
488
  const p = partsOf(menu);
@@ -469,7 +497,7 @@ var Menus = class {
469
497
  /**
470
498
  * Mark one option active (`aria-activedescendant`) and scroll it into
471
499
  * the list's view.
472
- * @private
500
+ * @internal
473
501
  */
474
502
  _activate(menu, opt) {
475
503
  const p = partsOf(menu);
@@ -485,7 +513,7 @@ var Menus = class {
485
513
  }
486
514
  /**
487
515
  * Keys inside an open menu.
488
- * @private
516
+ * @internal
489
517
  */
490
518
  _onKey(e, name, menu) {
491
519
  const p = partsOf(menu);
@@ -521,7 +549,7 @@ var Menus = class {
521
549
  }
522
550
  /**
523
551
  * A value was chosen: close, then report it.
524
- * @private
552
+ * @internal
525
553
  */
526
554
  _pick(name, value) {
527
555
  this.close(true);
@@ -529,7 +557,7 @@ var Menus = class {
529
557
  }
530
558
  };
531
559
 
532
- // src/js/shared/utils.js
560
+ // src/js/shared/utils.ts
533
561
  var LOG = "[WaveformSounds]";
534
562
  function clamp(value, min = 0, max = 1) {
535
563
  return Math.min(Math.max(value, min), max);
@@ -551,7 +579,7 @@ function hashString(str) {
551
579
  return hash;
552
580
  }
553
581
 
554
- // src/js/data/navigation.js
582
+ // src/js/data/navigation.ts
555
583
  var SEEK_STEP = 0.1;
556
584
  function rowTarget(key, at, count) {
557
585
  if (!count) return null;
@@ -580,7 +608,7 @@ function limitToReveal(limit, pos) {
580
608
  return pos >= limit ? pos + 1 : limit;
581
609
  }
582
610
 
583
- // src/js/data/bpm.js
611
+ // src/js/data/bpm.ts
584
612
  function bpmFilterFromRange(lo, hi, extent) {
585
613
  const a = Math.min(lo, hi), b = Math.max(lo, hi);
586
614
  return {
@@ -605,7 +633,7 @@ function hasBpmFilter(filter) {
605
633
  return filter.bpmMin != null && filter.bpmMin !== "" || filter.bpmMax != null && filter.bpmMax !== "";
606
634
  }
607
635
 
608
- // src/js/render/strings.js
636
+ // src/js/render/strings.ts
609
637
  var DEFAULT_STRINGS = {
610
638
  search: "Search sounds",
611
639
  searchPlaceholder: "Search sounds\u2026",
@@ -666,7 +694,7 @@ function countText(shown, total, strings = DEFAULT_STRINGS) {
666
694
  return total === 1 ? strings.countOne : fill(strings.count, { count: total });
667
695
  }
668
696
 
669
- // src/js/render/options.js
697
+ // src/js/render/options.ts
670
698
  var FILTERS = ["type", "key", "bpm", "loop"];
671
699
  var COLUMNS = ["type", "bpm", "key", "duration"];
672
700
  var RENDER_DEFAULTS = {
@@ -708,7 +736,7 @@ function resolveRenderOptions(options = {}) {
708
736
  };
709
737
  }
710
738
 
711
- // src/js/core/options.js
739
+ // src/js/core/options.ts
712
740
  var DEFAULT_OPTIONS = {
713
741
  ...RENDER_DEFAULTS,
714
742
  sounds: null,
@@ -721,6 +749,8 @@ var DEFAULT_OPTIONS = {
721
749
  loop: null,
722
750
  autoAdvance: false,
723
751
  arrowAudition: true,
752
+ // null is "unset" (the container's id, else a hash); the public type,
753
+ // unchanged from 0.3.1, has no null, hence the cast (it emits nothing).
724
754
  idPrefix: null,
725
755
  urlState: false,
726
756
  playerOptions: null,
@@ -798,7 +828,7 @@ function mergeOptions(...sources) {
798
828
  return out;
799
829
  }
800
830
 
801
- // src/js/render/html.js
831
+ // src/js/render/html.ts
802
832
  var VOID = /* @__PURE__ */ new Set(["input", "br", "img"]);
803
833
  function text(value) {
804
834
  return escapeHtml(value ?? "");
@@ -817,7 +847,7 @@ function h(tag, attributes = {}, ...children) {
817
847
  return open + children.flat(Infinity).filter((c) => c != null && c !== false && c !== "").join("") + `</${tag}>`;
818
848
  }
819
849
 
820
- // src/js/render/icons.js
850
+ // src/js/render/icons.ts
821
851
  function icon(path, extraClass = "") {
822
852
  const cls = extraClass ? `ws-icon ${extraClass}` : "ws-icon";
823
853
  return `<svg class="${cls}" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="${path}"/></svg>`;
@@ -832,7 +862,7 @@ var ICONS = {
832
862
  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")
833
863
  };
834
864
 
835
- // src/js/render/markup.js
865
+ // src/js/render/markup.ts
836
866
  function idBase(sounds) {
837
867
  const signature = [sounds.length, ...sounds.map((s) => s.url)].join("|");
838
868
  return `ws${hashString(signature).toString(36)}`;
@@ -1098,7 +1128,7 @@ function renderSoundsElement(sounds, options = {}, className = "") {
1098
1128
  return h("div", { class: cls, "data-waveform-sounds": true, "data-player": o.player }, renderSounds(sounds, options));
1099
1129
  }
1100
1130
 
1101
- // src/js/dom/rows.js
1131
+ // src/js/dom/rows.ts
1102
1132
  var ROW = ":scope > [data-ws-index]";
1103
1133
  function readRows(list) {
1104
1134
  const rows = [...list.querySelectorAll(ROW)].sort((a, b) => Number(a.dataset.wsIndex) - Number(b.dataset.wsIndex));
@@ -1144,7 +1174,7 @@ function orderRows(list, rows) {
1144
1174
  list.appendChild(frag);
1145
1175
  }
1146
1176
 
1147
- // src/js/dom/colors.js
1177
+ // src/js/dom/colors.ts
1148
1178
  function parseAlpha(color) {
1149
1179
  const c = String(color ?? "").trim();
1150
1180
  if (!c || c === "transparent") return 0;
@@ -1171,7 +1201,7 @@ function resolveCssColor(container, value) {
1171
1201
  return color;
1172
1202
  }
1173
1203
 
1174
- // src/js/data/url-state.js
1204
+ // src/js/data/url-state.ts
1175
1205
  function urlKeys(urlState) {
1176
1206
  if (!urlState) return null;
1177
1207
  const p = typeof urlState === "string" ? `${urlState}-` : "";
@@ -1216,17 +1246,17 @@ function writeUrlState(href, keys, filter, sort, defaultSort) {
1216
1246
  return url.href;
1217
1247
  }
1218
1248
 
1219
- // src/js/core/WaveformSounds.js
1249
+ // src/js/core/WaveformSounds.ts
1220
1250
  var NO_FILTER = Object.freeze({ query: "", type: "", key: "", bpmMin: "", bpmMax: "", loop: "" });
1221
1251
  var SEARCH_DELAY = 120;
1222
1252
  var BPM_DELAY = 200;
1223
1253
  var URL_DELAY = 250;
1224
1254
  var WaveformSounds = class _WaveformSounds {
1225
- /** @type {Map<Element, WaveformSounds>} */
1255
+ /** Every live instance, by its element. */
1226
1256
  static instances = /* @__PURE__ */ new Map();
1227
1257
  /**
1228
1258
  * @param {HTMLElement|string} container - The element (or a selector).
1229
- * @param {import('../../../index').WaveformSoundsOptions} [options]
1259
+ * @param {WaveformSoundsOptions} [options]
1230
1260
  */
1231
1261
  constructor(container, options = {}) {
1232
1262
  const el = typeof container === "string" ? document.querySelector(container) : container;
@@ -1264,7 +1294,7 @@ var WaveformSounds = class _WaveformSounds {
1264
1294
  /**
1265
1295
  * Adopt server-rendered markup or render it (from `sounds` or a fetched
1266
1296
  * manifest), then wire everything up.
1267
- * @private
1297
+ * @internal
1268
1298
  */
1269
1299
  async _init() {
1270
1300
  const el = this.container;
@@ -1299,8 +1329,8 @@ var WaveformSounds = class _WaveformSounds {
1299
1329
  }
1300
1330
  /**
1301
1331
  * The sounds from the `sounds` option, else the `manifest` URL.
1302
- * @returns {Promise<import('../../../index').Sound[]>}
1303
- * @private
1332
+ * @returns
1333
+ * @internal
1304
1334
  */
1305
1335
  async _loadSounds() {
1306
1336
  if (this.options.sounds || !this.options.manifest) return normalizeSounds(this.options.sounds || []);
@@ -1310,7 +1340,7 @@ var WaveformSounds = class _WaveformSounds {
1310
1340
  }
1311
1341
  /**
1312
1342
  * Look up the elements the runtime drives.
1313
- * @private
1343
+ * @internal
1314
1344
  */
1315
1345
  _cacheRefs() {
1316
1346
  const q = (sel) => this.container.querySelector(sel);
@@ -1337,7 +1367,7 @@ var WaveformSounds = class _WaveformSounds {
1337
1367
  /**
1338
1368
  * Every listener. All are removed by `destroy()` through one
1339
1369
  * AbortController.
1340
- * @private
1370
+ * @internal
1341
1371
  */
1342
1372
  _bind() {
1343
1373
  const sig = { signal: this._ctl.signal };
@@ -1389,7 +1419,7 @@ var WaveformSounds = class _WaveformSounds {
1389
1419
  /**
1390
1420
  * Clicks: type chips, loops or one-shots, Show more, Clear, Loop, a touch tap on a waveform
1391
1421
  * (seek), and anywhere else on a row (play/pause).
1392
- * @private
1422
+ * @internal
1393
1423
  */
1394
1424
  _onClick(e) {
1395
1425
  const t = e.target;
@@ -1428,7 +1458,7 @@ var WaveformSounds = class _WaveformSounds {
1428
1458
  /**
1429
1459
  * Mouse and pen seek on PRESS, like every scrubber. Remembers the
1430
1460
  * pointer type for the click that follows.
1431
- * @private
1461
+ * @internal
1432
1462
  */
1433
1463
  _onPointerDown(e) {
1434
1464
  this._lastPointer = e.pointerType;
@@ -1439,7 +1469,7 @@ var WaveformSounds = class _WaveformSounds {
1439
1469
  }
1440
1470
  /**
1441
1471
  * Seek (or start) a row's sound where its waveform was pressed.
1442
- * @private
1472
+ * @internal
1443
1473
  */
1444
1474
  _seekAt(wave, clientX) {
1445
1475
  const row = wave.closest("[data-ws-index]");
@@ -1449,7 +1479,7 @@ var WaveformSounds = class _WaveformSounds {
1449
1479
  /**
1450
1480
  * Keys on the list: `/` focuses search; ↑/↓/Home/End move between rows
1451
1481
  * (auditioning while something plays); ←/→ seek the playing row.
1452
- * @private
1482
+ * @internal
1453
1483
  */
1454
1484
  _onKey(e) {
1455
1485
  if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return;
@@ -1481,7 +1511,7 @@ var WaveformSounds = class _WaveformSounds {
1481
1511
  }
1482
1512
  /**
1483
1513
  * Focus a row's play button.
1484
- * @private
1514
+ * @internal
1485
1515
  */
1486
1516
  _focusRow(row) {
1487
1517
  row?.querySelector(".ws-play")?.focus();
@@ -1492,7 +1522,7 @@ var WaveformSounds = class _WaveformSounds {
1492
1522
  * on the title or waveform left focus on <body>, and Safari never
1493
1523
  * focuses a clicked button). No scroll jump, and no focus ring: the
1494
1524
  * browser shows none for a focus that follows a pointer.
1495
- * @private
1525
+ * @internal
1496
1526
  */
1497
1527
  _focusRowQuietly(row) {
1498
1528
  const btn = row?.querySelector(".ws-play");
@@ -1502,7 +1532,7 @@ var WaveformSounds = class _WaveformSounds {
1502
1532
  /**
1503
1533
  * Draw row canvases as they scroll into view; redraw on resize and on
1504
1534
  * theme flips (the canvas can't follow CSS by itself).
1505
- * @private
1535
+ * @internal
1506
1536
  */
1507
1537
  _observe() {
1508
1538
  if (this.render.player !== "inline" || typeof window === "undefined") return;
@@ -1546,7 +1576,7 @@ var WaveformSounds = class _WaveformSounds {
1546
1576
  /**
1547
1577
  * Resolve the canvas colours (options, else the CSS custom properties)
1548
1578
  * and keep `--ws-surface` current unless the site set it.
1549
- * @private
1579
+ * @internal
1550
1580
  */
1551
1581
  _resolveColors() {
1552
1582
  if (this._autoSurface || !getComputedStyle(this.container).getPropertyValue("--ws-surface").trim()) {
@@ -1561,7 +1591,7 @@ var WaveformSounds = class _WaveformSounds {
1561
1591
  }
1562
1592
  /**
1563
1593
  * Draw one row's waveform (only once it has been on screen).
1564
- * @private
1594
+ * @internal
1565
1595
  */
1566
1596
  _drawRow(index) {
1567
1597
  if (this.render.player !== "inline" || index == null || !this._drawn?.has(index)) return;
@@ -1579,7 +1609,7 @@ var WaveformSounds = class _WaveformSounds {
1579
1609
  }
1580
1610
  /**
1581
1611
  * Redraw every row drawn so far.
1582
- * @private
1612
+ * @internal
1583
1613
  */
1584
1614
  _redrawAll() {
1585
1615
  this._drawn?.forEach((i) => this._drawRow(i));
@@ -1587,7 +1617,7 @@ var WaveformSounds = class _WaveformSounds {
1587
1617
  /* ── Filters in the address ───────────────────────────────────────── */
1588
1618
  /**
1589
1619
  * Apply the filter and sort from the address (`urlState`).
1590
- * @private
1620
+ * @internal
1591
1621
  */
1592
1622
  _readUrl() {
1593
1623
  const keys = urlKeys(this.options.urlState);
@@ -1602,7 +1632,7 @@ var WaveformSounds = class _WaveformSounds {
1602
1632
  /**
1603
1633
  * Rewrite the address shortly after a change (replaceState: no history
1604
1634
  * entries).
1605
- * @private
1635
+ * @internal
1606
1636
  */
1607
1637
  _queueUrl() {
1608
1638
  const keys = urlKeys(this.options.urlState);
@@ -1619,12 +1649,6 @@ var WaveformSounds = class _WaveformSounds {
1619
1649
  get visible() {
1620
1650
  return sortSounds(this.sounds.filter((s) => matches(s, this.filter)), this.sortBy);
1621
1651
  }
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
1652
  setFilter(patch = {}) {
1629
1653
  this.filter = { ...this.filter, ...patch };
1630
1654
  this.limit = this._pageSize();
@@ -1635,7 +1659,7 @@ var WaveformSounds = class _WaveformSounds {
1635
1659
  clearFilters() {
1636
1660
  this.setFilter(NO_FILTER);
1637
1661
  }
1638
- /** @param {import('../../../index').SoundsSort} by */
1662
+ /** @param by */
1639
1663
  setSort(by) {
1640
1664
  this._sortSet = true;
1641
1665
  this.sortBy = SORTS.includes(by) ? by : "default";
@@ -1650,7 +1674,7 @@ var WaveformSounds = class _WaveformSounds {
1650
1674
  }
1651
1675
  /**
1652
1676
  * Rows per page (Infinity when paging is off).
1653
- * @private
1677
+ * @internal
1654
1678
  */
1655
1679
  _pageSize() {
1656
1680
  return this.render.pageSize > 0 ? this.render.pageSize : Infinity;
@@ -1658,7 +1682,7 @@ var WaveformSounds = class _WaveformSounds {
1658
1682
  /**
1659
1683
  * Show the current filter and sort in the controls (they can be set from
1660
1684
  * code or the address, not only by the controls themselves).
1661
- * @private
1685
+ * @internal
1662
1686
  */
1663
1687
  _syncControls() {
1664
1688
  const $ = this.$, f = this.filter;
@@ -1680,7 +1704,7 @@ var WaveformSounds = class _WaveformSounds {
1680
1704
  * Show a BPM filter in its menu: the button label, the panel's readout,
1681
1705
  * the filled part of the track, and which handle sits on top (the one
1682
1706
  * that can still move, when they meet).
1683
- * @private
1707
+ * @internal
1684
1708
  */
1685
1709
  _showBpm(f) {
1686
1710
  const $ = this.$, extent = this._bpmExtent;
@@ -1697,9 +1721,9 @@ var WaveformSounds = class _WaveformSounds {
1697
1721
  * Lay the rows out for the current filter, sort and page: order, hide,
1698
1722
  * "Show more", the empty state and the count. Then report it.
1699
1723
  *
1700
- * @param {{resort: boolean}} opts - Reorder the rows even if the sort
1724
+ * @param opts - Reorder the rows even if the sort
1701
1725
  * hasn't changed.
1702
- * @private
1726
+ * @internal
1703
1727
  */
1704
1728
  _apply({ resort }) {
1705
1729
  const $ = this.$;
@@ -1729,9 +1753,9 @@ var WaveformSounds = class _WaveformSounds {
1729
1753
  * Resolve an index, id or sound to an index in `this.sounds`. No
1730
1754
  * target means the current sound, else the first visible one.
1731
1755
  *
1732
- * @param {number|string|Object} [target]
1733
- * @returns {number|null}
1734
- * @private
1756
+ * @param target
1757
+ * @returns
1758
+ * @internal
1735
1759
  */
1736
1760
  _indexOf(target) {
1737
1761
  if (target == null) return this.currentIndex ?? (this.visible[0] ? this.sounds.indexOf(this.visible[0]) : null);
@@ -1741,8 +1765,8 @@ var WaveformSounds = class _WaveformSounds {
1741
1765
  }
1742
1766
  /**
1743
1767
  * The WaveformPlayer class: `playerClass`, else the page's global.
1744
- * @returns {Function|null}
1745
- * @private
1768
+ * @returns
1769
+ * @internal
1746
1770
  */
1747
1771
  _playerClass() {
1748
1772
  return this.options.playerClass || (typeof window !== "undefined" ? window.WaveformPlayer : null) || null;
@@ -1753,8 +1777,8 @@ var WaveformSounds = class _WaveformSounds {
1753
1777
  * which would strip `ws-engine--strip` (and with it the docked styling).
1754
1778
  * Made here rather than in the markup so server-rendered HTML from any
1755
1779
  * version works.
1756
- * @returns {HTMLElement}
1757
- * @private
1780
+ * @returns
1781
+ * @internal
1758
1782
  */
1759
1783
  _engineMount() {
1760
1784
  const slot = this.$.engine;
@@ -1768,8 +1792,8 @@ var WaveformSounds = class _WaveformSounds {
1768
1792
  }
1769
1793
  /**
1770
1794
  * Build the engine once (it holds no audio until a play).
1771
- * @returns {Object|null} The engine, or null without a player class.
1772
- * @private
1795
+ * @returns The engine, or null without a player class.
1796
+ * @internal
1773
1797
  */
1774
1798
  _ensureEngine() {
1775
1799
  if (this.engine) return this.engine;
@@ -1792,8 +1816,8 @@ var WaveformSounds = class _WaveformSounds {
1792
1816
  * Play a sound (by index, id or sound object), or resume the current
1793
1817
  * one. Before the list is built the call waits for it.
1794
1818
  *
1795
- * @param {number|string|Object} [target]
1796
- * @param {{at?: number}} [opts] - `at`: start position 0..1.
1819
+ * @param target
1820
+ * @param opts - `at`: start position 0..1.
1797
1821
  */
1798
1822
  play(target, opts = {}) {
1799
1823
  if (!this.$) {
@@ -1819,7 +1843,7 @@ var WaveformSounds = class _WaveformSounds {
1819
1843
  if (previous != null) this._paintRow(previous);
1820
1844
  this._paintRow(index);
1821
1845
  const sound = this.sounds[index];
1822
- engine.loadTrack(sound.url, sound.title, sound.type || null, { waveform: enginePeaks(sound, this.render.player), autoplay: true });
1846
+ engine.loadTrack(sound.url, sound.title, sound.type || null, engineTrack(sound, this.render.player, true));
1823
1847
  }
1824
1848
  /**
1825
1849
  * Strip layout: load the first sound the list shows into the docked
@@ -1827,7 +1851,7 @@ var WaveformSounds = class _WaveformSounds {
1827
1851
  * (and its play button plays that sound) instead of an empty frame.
1828
1852
  * Only metadata is fetched — the browser default for any `<audio>`.
1829
1853
  * The row isn't marked current until it plays.
1830
- * @private
1854
+ * @internal
1831
1855
  */
1832
1856
  _cueFirst() {
1833
1857
  const engine = this.engine;
@@ -1838,7 +1862,7 @@ var WaveformSounds = class _WaveformSounds {
1838
1862
  this.currentIndex = index;
1839
1863
  this.progress = 0;
1840
1864
  this._cued = true;
1841
- engine.loadTrack(first.url, first.title, first.type || null, { waveform: enginePeaks(first, "strip"), autoplay: false });
1865
+ engine.loadTrack(first.url, first.title, first.type || null, engineTrack(first, "strip", false));
1842
1866
  }
1843
1867
  /** Pause the current sound. */
1844
1868
  pause() {
@@ -1846,7 +1870,7 @@ var WaveformSounds = class _WaveformSounds {
1846
1870
  }
1847
1871
  /**
1848
1872
  * The current sound plays/pauses; another sound starts.
1849
- * @param {number|string|Object} [target]
1873
+ * @param target
1850
1874
  */
1851
1875
  toggle(target) {
1852
1876
  const index = this._indexOf(target);
@@ -1866,9 +1890,9 @@ var WaveformSounds = class _WaveformSounds {
1866
1890
  * Play the visible sound `dir` places away, revealing it if it's past
1867
1891
  * the current page.
1868
1892
  *
1869
- * @param {1|-1} dir
1870
- * @returns {boolean} Whether there was one.
1871
- * @private
1893
+ * @param dir
1894
+ * @returns Whether there was one.
1895
+ * @internal
1872
1896
  */
1873
1897
  _step(dir) {
1874
1898
  const shown = this.visible;
@@ -1887,7 +1911,7 @@ var WaveformSounds = class _WaveformSounds {
1887
1911
  * Loop the current sound (auditioning a loop is the common case). When
1888
1912
  * the list marks its loops (`loop: true` on any sound), only those
1889
1913
  * repeat: a one-shot always plays once.
1890
- * @param {boolean} on
1914
+ * @param on
1891
1915
  */
1892
1916
  setLoop(on) {
1893
1917
  this._loopSet = true;
@@ -1896,7 +1920,7 @@ var WaveformSounds = class _WaveformSounds {
1896
1920
  }
1897
1921
  /**
1898
1922
  * Apply the loop state to the toggle and the engine.
1899
- * @private
1923
+ * @internal
1900
1924
  */
1901
1925
  _setLoop(on) {
1902
1926
  this.$?.loop?.setAttribute("aria-pressed", String(on));
@@ -1905,7 +1929,7 @@ var WaveformSounds = class _WaveformSounds {
1905
1929
  /**
1906
1930
  * Should the current sound repeat? The Loop toggle is on, and either
1907
1931
  * the list doesn't say which sounds are loops or this one is.
1908
- * @private
1932
+ * @internal
1909
1933
  */
1910
1934
  _repeats() {
1911
1935
  if (!this.loop) return false;
@@ -1915,7 +1939,7 @@ var WaveformSounds = class _WaveformSounds {
1915
1939
  /**
1916
1940
  * Seek a row's sound to `fraction`; a row that isn't current starts
1917
1941
  * there. Before the duration is known the seek waits for it.
1918
- * @private
1942
+ * @internal
1919
1943
  */
1920
1944
  _seekRow(index, fraction) {
1921
1945
  if (index !== this.currentIndex || !this.engine) {
@@ -1935,7 +1959,7 @@ var WaveformSounds = class _WaveformSounds {
1935
1959
  /**
1936
1960
  * The engine loaded a sound: apply the loop, borrow decoded peaks for a
1937
1961
  * row that had none, and land a pending seek.
1938
- * @private
1962
+ * @internal
1939
1963
  */
1940
1964
  _onEngineLoad() {
1941
1965
  if (this.engine?.audio) this.engine.audio.loop = this._repeats();
@@ -1953,7 +1977,7 @@ var WaveformSounds = class _WaveformSounds {
1953
1977
  }
1954
1978
  /**
1955
1979
  * Playback progress: repaint the current row, once per frame.
1956
- * @private
1980
+ * @internal
1957
1981
  */
1958
1982
  _onTime(time, duration) {
1959
1983
  if (this.currentIndex == null || !duration) return;
@@ -1973,7 +1997,7 @@ var WaveformSounds = class _WaveformSounds {
1973
1997
  }
1974
1998
  /**
1975
1999
  * A sound finished: report it, then auto-advance or settle.
1976
- * @private
2000
+ * @internal
1977
2001
  */
1978
2002
  _onEnd() {
1979
2003
  const sound = this.sounds[this.currentIndex];
@@ -1985,7 +2009,7 @@ var WaveformSounds = class _WaveformSounds {
1985
2009
  }
1986
2010
  /**
1987
2011
  * A sound failed to load or play: mark its row and report it.
1988
- * @private
2012
+ * @internal
1989
2013
  */
1990
2014
  _onEngineError(err) {
1991
2015
  this.rows[this.currentIndex]?.classList.add("is-error");
@@ -1996,7 +2020,7 @@ var WaveformSounds = class _WaveformSounds {
1996
2020
  * Record play/pause and repaint. Events fire only on a real change: at a
1997
2021
  * natural end the browser fires `pause` then `ended`, and `_onEnd()`
1998
2022
  * also settles the state — one pause event, not two.
1999
- * @private
2023
+ * @internal
2000
2024
  */
2001
2025
  _setPlaying(on) {
2002
2026
  const changed = this.playing !== on;
@@ -2014,7 +2038,7 @@ var WaveformSounds = class _WaveformSounds {
2014
2038
  /* ── Row painting ─────────────────────────────────────────────────── */
2015
2039
  /**
2016
2040
  * A row's state classes, play-button label and waveform.
2017
- * @private
2041
+ * @internal
2018
2042
  */
2019
2043
  _paintRow(index) {
2020
2044
  const row = this.rows[index];
@@ -2038,7 +2062,7 @@ var WaveformSounds = class _WaveformSounds {
2038
2062
  /* ── Events & lifecycle ──────────────────────────────────────────── */
2039
2063
  /**
2040
2064
  * Emit a `waveformsounds:<name>` event carrying this instance.
2041
- * @private
2065
+ * @internal
2042
2066
  */
2043
2067
  _emit(name, detail = {}) {
2044
2068
  emit(this.container, name, { ...detail, instance: this });
@@ -2078,8 +2102,8 @@ var WaveformSounds = class _WaveformSounds {
2078
2102
  /**
2079
2103
  * Initialise every `[data-waveform-sounds]` under `root` that isn't yet.
2080
2104
  *
2081
- * @param {ParentNode} [root=document]
2082
- * @returns {WaveformSounds[]} The new instances.
2105
+ * @param root
2106
+ * @returns The new instances.
2083
2107
  */
2084
2108
  static init(root = document) {
2085
2109
  if (typeof document === "undefined") return [];
@@ -2098,8 +2122,8 @@ var WaveformSounds = class _WaveformSounds {
2098
2122
  }
2099
2123
  /**
2100
2124
  * The instance on an element (or selector), if any.
2101
- * @param {Element|string} el
2102
- * @returns {WaveformSounds|null}
2125
+ * @param el
2126
+ * @returns
2103
2127
  */
2104
2128
  static getInstance(el) {
2105
2129
  const node = typeof el === "string" ? document.querySelector(el) : el;
@@ -2112,14 +2136,14 @@ var WaveformSounds = class _WaveformSounds {
2112
2136
  }
2113
2137
  };
2114
2138
 
2115
- // src/js/entry.js
2139
+ // src/js/entry.ts
2116
2140
  WaveformSounds.utils = { encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration, renderSounds };
2117
2141
  WaveformSounds.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
2118
2142
  WaveformSounds.DEFAULT_STRINGS = DEFAULT_STRINGS;
2119
2143
  if (typeof window !== "undefined") window.WaveformSounds = WaveformSounds;
2120
2144
  var entry_default = WaveformSounds;
2121
2145
 
2122
- // src/js/index.js
2146
+ // src/js/index.ts
2123
2147
  var index_default = entry_default;
2124
2148
  if (typeof document !== "undefined" && document.documentElement?.dataset?.waveformAutoinit !== "false") {
2125
2149
  if (document.readyState === "loading") {