@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
@@ -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 = "";
@@ -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;
@@ -1300,8 +1331,8 @@
1300
1331
  }
1301
1332
  /**
1302
1333
  * The sounds from the `sounds` option, else the `manifest` URL.
1303
- * @returns {Promise<import('../../../index').Sound[]>}
1304
- * @private
1334
+ * @returns
1335
+ * @internal
1305
1336
  */
1306
1337
  async _loadSounds() {
1307
1338
  if (this.options.sounds || !this.options.manifest) return normalizeSounds(this.options.sounds || []);
@@ -1311,7 +1342,7 @@
1311
1342
  }
1312
1343
  /**
1313
1344
  * Look up the elements the runtime drives.
1314
- * @private
1345
+ * @internal
1315
1346
  */
1316
1347
  _cacheRefs() {
1317
1348
  const q = (sel) => this.container.querySelector(sel);
@@ -1338,7 +1369,7 @@
1338
1369
  /**
1339
1370
  * Every listener. All are removed by `destroy()` through one
1340
1371
  * AbortController.
1341
- * @private
1372
+ * @internal
1342
1373
  */
1343
1374
  _bind() {
1344
1375
  const sig = { signal: this._ctl.signal };
@@ -1390,7 +1421,7 @@
1390
1421
  /**
1391
1422
  * Clicks: type chips, loops or one-shots, Show more, Clear, Loop, a touch tap on a waveform
1392
1423
  * (seek), and anywhere else on a row (play/pause).
1393
- * @private
1424
+ * @internal
1394
1425
  */
1395
1426
  _onClick(e) {
1396
1427
  const t = e.target;
@@ -1429,7 +1460,7 @@
1429
1460
  /**
1430
1461
  * Mouse and pen seek on PRESS, like every scrubber. Remembers the
1431
1462
  * pointer type for the click that follows.
1432
- * @private
1463
+ * @internal
1433
1464
  */
1434
1465
  _onPointerDown(e) {
1435
1466
  this._lastPointer = e.pointerType;
@@ -1440,7 +1471,7 @@
1440
1471
  }
1441
1472
  /**
1442
1473
  * Seek (or start) a row's sound where its waveform was pressed.
1443
- * @private
1474
+ * @internal
1444
1475
  */
1445
1476
  _seekAt(wave, clientX) {
1446
1477
  const row = wave.closest("[data-ws-index]");
@@ -1450,7 +1481,7 @@
1450
1481
  /**
1451
1482
  * Keys on the list: `/` focuses search; ↑/↓/Home/End move between rows
1452
1483
  * (auditioning while something plays); ←/→ seek the playing row.
1453
- * @private
1484
+ * @internal
1454
1485
  */
1455
1486
  _onKey(e) {
1456
1487
  if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return;
@@ -1482,7 +1513,7 @@
1482
1513
  }
1483
1514
  /**
1484
1515
  * Focus a row's play button.
1485
- * @private
1516
+ * @internal
1486
1517
  */
1487
1518
  _focusRow(row) {
1488
1519
  row?.querySelector(".ws-play")?.focus();
@@ -1493,7 +1524,7 @@
1493
1524
  * on the title or waveform left focus on <body>, and Safari never
1494
1525
  * focuses a clicked button). No scroll jump, and no focus ring: the
1495
1526
  * browser shows none for a focus that follows a pointer.
1496
- * @private
1527
+ * @internal
1497
1528
  */
1498
1529
  _focusRowQuietly(row) {
1499
1530
  const btn = row?.querySelector(".ws-play");
@@ -1503,7 +1534,7 @@
1503
1534
  /**
1504
1535
  * Draw row canvases as they scroll into view; redraw on resize and on
1505
1536
  * theme flips (the canvas can't follow CSS by itself).
1506
- * @private
1537
+ * @internal
1507
1538
  */
1508
1539
  _observe() {
1509
1540
  if (this.render.player !== "inline" || typeof window === "undefined") return;
@@ -1547,7 +1578,7 @@
1547
1578
  /**
1548
1579
  * Resolve the canvas colours (options, else the CSS custom properties)
1549
1580
  * and keep `--ws-surface` current unless the site set it.
1550
- * @private
1581
+ * @internal
1551
1582
  */
1552
1583
  _resolveColors() {
1553
1584
  if (this._autoSurface || !getComputedStyle(this.container).getPropertyValue("--ws-surface").trim()) {
@@ -1562,7 +1593,7 @@
1562
1593
  }
1563
1594
  /**
1564
1595
  * Draw one row's waveform (only once it has been on screen).
1565
- * @private
1596
+ * @internal
1566
1597
  */
1567
1598
  _drawRow(index) {
1568
1599
  if (this.render.player !== "inline" || index == null || !this._drawn?.has(index)) return;
@@ -1580,7 +1611,7 @@
1580
1611
  }
1581
1612
  /**
1582
1613
  * Redraw every row drawn so far.
1583
- * @private
1614
+ * @internal
1584
1615
  */
1585
1616
  _redrawAll() {
1586
1617
  this._drawn?.forEach((i) => this._drawRow(i));
@@ -1588,7 +1619,7 @@
1588
1619
  /* ── Filters in the address ───────────────────────────────────────── */
1589
1620
  /**
1590
1621
  * Apply the filter and sort from the address (`urlState`).
1591
- * @private
1622
+ * @internal
1592
1623
  */
1593
1624
  _readUrl() {
1594
1625
  const keys = urlKeys(this.options.urlState);
@@ -1603,7 +1634,7 @@
1603
1634
  /**
1604
1635
  * Rewrite the address shortly after a change (replaceState: no history
1605
1636
  * entries).
1606
- * @private
1637
+ * @internal
1607
1638
  */
1608
1639
  _queueUrl() {
1609
1640
  const keys = urlKeys(this.options.urlState);
@@ -1620,12 +1651,6 @@
1620
1651
  get visible() {
1621
1652
  return sortSounds(this.sounds.filter((s) => matches(s, this.filter)), this.sortBy);
1622
1653
  }
1623
- /**
1624
- * Change the filter (merged into the current one) and re-apply. Back to
1625
- * the first page.
1626
- *
1627
- * @param {Partial<import('../../../index').SoundsFilter>} patch
1628
- */
1629
1654
  setFilter(patch = {}) {
1630
1655
  this.filter = { ...this.filter, ...patch };
1631
1656
  this.limit = this._pageSize();
@@ -1636,7 +1661,7 @@
1636
1661
  clearFilters() {
1637
1662
  this.setFilter(NO_FILTER);
1638
1663
  }
1639
- /** @param {import('../../../index').SoundsSort} by */
1664
+ /** @param by */
1640
1665
  setSort(by) {
1641
1666
  this._sortSet = true;
1642
1667
  this.sortBy = SORTS.includes(by) ? by : "default";
@@ -1651,7 +1676,7 @@
1651
1676
  }
1652
1677
  /**
1653
1678
  * Rows per page (Infinity when paging is off).
1654
- * @private
1679
+ * @internal
1655
1680
  */
1656
1681
  _pageSize() {
1657
1682
  return this.render.pageSize > 0 ? this.render.pageSize : Infinity;
@@ -1659,7 +1684,7 @@
1659
1684
  /**
1660
1685
  * Show the current filter and sort in the controls (they can be set from
1661
1686
  * code or the address, not only by the controls themselves).
1662
- * @private
1687
+ * @internal
1663
1688
  */
1664
1689
  _syncControls() {
1665
1690
  const $ = this.$, f = this.filter;
@@ -1681,7 +1706,7 @@
1681
1706
  * Show a BPM filter in its menu: the button label, the panel's readout,
1682
1707
  * the filled part of the track, and which handle sits on top (the one
1683
1708
  * that can still move, when they meet).
1684
- * @private
1709
+ * @internal
1685
1710
  */
1686
1711
  _showBpm(f) {
1687
1712
  const $ = this.$, extent = this._bpmExtent;
@@ -1698,9 +1723,9 @@
1698
1723
  * Lay the rows out for the current filter, sort and page: order, hide,
1699
1724
  * "Show more", the empty state and the count. Then report it.
1700
1725
  *
1701
- * @param {{resort: boolean}} opts - Reorder the rows even if the sort
1726
+ * @param opts - Reorder the rows even if the sort
1702
1727
  * hasn't changed.
1703
- * @private
1728
+ * @internal
1704
1729
  */
1705
1730
  _apply({ resort }) {
1706
1731
  const $ = this.$;
@@ -1730,9 +1755,9 @@
1730
1755
  * Resolve an index, id or sound to an index in `this.sounds`. No
1731
1756
  * target means the current sound, else the first visible one.
1732
1757
  *
1733
- * @param {number|string|Object} [target]
1734
- * @returns {number|null}
1735
- * @private
1758
+ * @param target
1759
+ * @returns
1760
+ * @internal
1736
1761
  */
1737
1762
  _indexOf(target) {
1738
1763
  if (target == null) return this.currentIndex ?? (this.visible[0] ? this.sounds.indexOf(this.visible[0]) : null);
@@ -1742,8 +1767,8 @@
1742
1767
  }
1743
1768
  /**
1744
1769
  * The WaveformPlayer class: `playerClass`, else the page's global.
1745
- * @returns {Function|null}
1746
- * @private
1770
+ * @returns
1771
+ * @internal
1747
1772
  */
1748
1773
  _playerClass() {
1749
1774
  return this.options.playerClass || (typeof window !== "undefined" ? window.WaveformPlayer : null) || null;
@@ -1754,8 +1779,8 @@
1754
1779
  * which would strip `ws-engine--strip` (and with it the docked styling).
1755
1780
  * Made here rather than in the markup so server-rendered HTML from any
1756
1781
  * version works.
1757
- * @returns {HTMLElement}
1758
- * @private
1782
+ * @returns
1783
+ * @internal
1759
1784
  */
1760
1785
  _engineMount() {
1761
1786
  const slot = this.$.engine;
@@ -1769,8 +1794,8 @@
1769
1794
  }
1770
1795
  /**
1771
1796
  * Build the engine once (it holds no audio until a play).
1772
- * @returns {Object|null} The engine, or null without a player class.
1773
- * @private
1797
+ * @returns The engine, or null without a player class.
1798
+ * @internal
1774
1799
  */
1775
1800
  _ensureEngine() {
1776
1801
  if (this.engine) return this.engine;
@@ -1793,8 +1818,8 @@
1793
1818
  * Play a sound (by index, id or sound object), or resume the current
1794
1819
  * one. Before the list is built the call waits for it.
1795
1820
  *
1796
- * @param {number|string|Object} [target]
1797
- * @param {{at?: number}} [opts] - `at`: start position 0..1.
1821
+ * @param target
1822
+ * @param opts - `at`: start position 0..1.
1798
1823
  */
1799
1824
  play(target, opts = {}) {
1800
1825
  if (!this.$) {
@@ -1820,7 +1845,7 @@
1820
1845
  if (previous != null) this._paintRow(previous);
1821
1846
  this._paintRow(index);
1822
1847
  const sound = this.sounds[index];
1823
- 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));
1824
1849
  }
1825
1850
  /**
1826
1851
  * Strip layout: load the first sound the list shows into the docked
@@ -1828,7 +1853,7 @@
1828
1853
  * (and its play button plays that sound) instead of an empty frame.
1829
1854
  * Only metadata is fetched — the browser default for any `<audio>`.
1830
1855
  * The row isn't marked current until it plays.
1831
- * @private
1856
+ * @internal
1832
1857
  */
1833
1858
  _cueFirst() {
1834
1859
  const engine = this.engine;
@@ -1839,7 +1864,7 @@
1839
1864
  this.currentIndex = index;
1840
1865
  this.progress = 0;
1841
1866
  this._cued = true;
1842
- engine.loadTrack(first.url, first.title, first.type || null, { waveform: enginePeaks(first, "strip"), autoplay: false });
1867
+ engine.loadTrack(first.url, first.title, first.type || null, engineTrack(first, "strip", false));
1843
1868
  }
1844
1869
  /** Pause the current sound. */
1845
1870
  pause() {
@@ -1847,7 +1872,7 @@
1847
1872
  }
1848
1873
  /**
1849
1874
  * The current sound plays/pauses; another sound starts.
1850
- * @param {number|string|Object} [target]
1875
+ * @param target
1851
1876
  */
1852
1877
  toggle(target) {
1853
1878
  const index = this._indexOf(target);
@@ -1867,9 +1892,9 @@
1867
1892
  * Play the visible sound `dir` places away, revealing it if it's past
1868
1893
  * the current page.
1869
1894
  *
1870
- * @param {1|-1} dir
1871
- * @returns {boolean} Whether there was one.
1872
- * @private
1895
+ * @param dir
1896
+ * @returns Whether there was one.
1897
+ * @internal
1873
1898
  */
1874
1899
  _step(dir) {
1875
1900
  const shown = this.visible;
@@ -1888,7 +1913,7 @@
1888
1913
  * Loop the current sound (auditioning a loop is the common case). When
1889
1914
  * the list marks its loops (`loop: true` on any sound), only those
1890
1915
  * repeat: a one-shot always plays once.
1891
- * @param {boolean} on
1916
+ * @param on
1892
1917
  */
1893
1918
  setLoop(on) {
1894
1919
  this._loopSet = true;
@@ -1897,7 +1922,7 @@
1897
1922
  }
1898
1923
  /**
1899
1924
  * Apply the loop state to the toggle and the engine.
1900
- * @private
1925
+ * @internal
1901
1926
  */
1902
1927
  _setLoop(on) {
1903
1928
  this.$?.loop?.setAttribute("aria-pressed", String(on));
@@ -1906,7 +1931,7 @@
1906
1931
  /**
1907
1932
  * Should the current sound repeat? The Loop toggle is on, and either
1908
1933
  * the list doesn't say which sounds are loops or this one is.
1909
- * @private
1934
+ * @internal
1910
1935
  */
1911
1936
  _repeats() {
1912
1937
  if (!this.loop) return false;
@@ -1916,7 +1941,7 @@
1916
1941
  /**
1917
1942
  * Seek a row's sound to `fraction`; a row that isn't current starts
1918
1943
  * there. Before the duration is known the seek waits for it.
1919
- * @private
1944
+ * @internal
1920
1945
  */
1921
1946
  _seekRow(index, fraction) {
1922
1947
  if (index !== this.currentIndex || !this.engine) {
@@ -1936,7 +1961,7 @@
1936
1961
  /**
1937
1962
  * The engine loaded a sound: apply the loop, borrow decoded peaks for a
1938
1963
  * row that had none, and land a pending seek.
1939
- * @private
1964
+ * @internal
1940
1965
  */
1941
1966
  _onEngineLoad() {
1942
1967
  if (this.engine?.audio) this.engine.audio.loop = this._repeats();
@@ -1954,7 +1979,7 @@
1954
1979
  }
1955
1980
  /**
1956
1981
  * Playback progress: repaint the current row, once per frame.
1957
- * @private
1982
+ * @internal
1958
1983
  */
1959
1984
  _onTime(time, duration) {
1960
1985
  if (this.currentIndex == null || !duration) return;
@@ -1974,7 +1999,7 @@
1974
1999
  }
1975
2000
  /**
1976
2001
  * A sound finished: report it, then auto-advance or settle.
1977
- * @private
2002
+ * @internal
1978
2003
  */
1979
2004
  _onEnd() {
1980
2005
  const sound = this.sounds[this.currentIndex];
@@ -1986,7 +2011,7 @@
1986
2011
  }
1987
2012
  /**
1988
2013
  * A sound failed to load or play: mark its row and report it.
1989
- * @private
2014
+ * @internal
1990
2015
  */
1991
2016
  _onEngineError(err) {
1992
2017
  this.rows[this.currentIndex]?.classList.add("is-error");
@@ -1997,7 +2022,7 @@
1997
2022
  * Record play/pause and repaint. Events fire only on a real change: at a
1998
2023
  * natural end the browser fires `pause` then `ended`, and `_onEnd()`
1999
2024
  * also settles the state — one pause event, not two.
2000
- * @private
2025
+ * @internal
2001
2026
  */
2002
2027
  _setPlaying(on) {
2003
2028
  const changed = this.playing !== on;
@@ -2015,7 +2040,7 @@
2015
2040
  /* ── Row painting ─────────────────────────────────────────────────── */
2016
2041
  /**
2017
2042
  * A row's state classes, play-button label and waveform.
2018
- * @private
2043
+ * @internal
2019
2044
  */
2020
2045
  _paintRow(index) {
2021
2046
  const row = this.rows[index];
@@ -2039,7 +2064,7 @@
2039
2064
  /* ── Events & lifecycle ──────────────────────────────────────────── */
2040
2065
  /**
2041
2066
  * Emit a `waveformsounds:<name>` event carrying this instance.
2042
- * @private
2067
+ * @internal
2043
2068
  */
2044
2069
  _emit(name, detail = {}) {
2045
2070
  emit(this.container, name, { ...detail, instance: this });
@@ -2079,8 +2104,8 @@
2079
2104
  /**
2080
2105
  * Initialise every `[data-waveform-sounds]` under `root` that isn't yet.
2081
2106
  *
2082
- * @param {ParentNode} [root=document]
2083
- * @returns {WaveformSounds[]} The new instances.
2107
+ * @param root
2108
+ * @returns The new instances.
2084
2109
  */
2085
2110
  static init(root = document) {
2086
2111
  if (typeof document === "undefined") return [];
@@ -2099,8 +2124,8 @@
2099
2124
  }
2100
2125
  /**
2101
2126
  * The instance on an element (or selector), if any.
2102
- * @param {Element|string} el
2103
- * @returns {WaveformSounds|null}
2127
+ * @param el
2128
+ * @returns
2104
2129
  */
2105
2130
  static getInstance(el) {
2106
2131
  const node = typeof el === "string" ? document.querySelector(el) : el;
@@ -2113,14 +2138,14 @@
2113
2138
  }
2114
2139
  };
2115
2140
 
2116
- // src/js/entry.js
2141
+ // src/js/entry.ts
2117
2142
  WaveformSounds.utils = { encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration, renderSounds };
2118
2143
  WaveformSounds.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
2119
2144
  WaveformSounds.DEFAULT_STRINGS = DEFAULT_STRINGS;
2120
2145
  if (typeof window !== "undefined") window.WaveformSounds = WaveformSounds;
2121
2146
  var entry_default = WaveformSounds;
2122
2147
 
2123
- // src/js/index.js
2148
+ // src/js/index.ts
2124
2149
  var index_default = entry_default;
2125
2150
  if (typeof document !== "undefined" && document.documentElement?.dataset?.waveformAutoinit !== "false") {
2126
2151
  if (document.readyState === "loading") {