@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
@@ -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 = "";
@@ -98,7 +116,7 @@ function formatDuration(seconds) {
98
116
  const s = Number(seconds);
99
117
  if (!Number.isFinite(s) || s < 0) return "";
100
118
  if (s > 0 && s < 0.95) return `${Math.max(0.1, Math.round(s * 10) / 10).toFixed(1)}s`;
101
- const total = Math.round(s);
119
+ const total = s < 1 ? Math.ceil(s) : Math.floor(s);
102
120
  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
103
121
  }
104
122
  function parseDuration(value) {
@@ -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;
@@ -1293,13 +1323,14 @@ var WaveformSounds = class _WaveformSounds {
1293
1323
  this._syncControls();
1294
1324
  this._apply({ resort: this.sortBy !== "default" });
1295
1325
  if (this._playerClass()) this._ensureEngine();
1326
+ if (this.render.player === "strip" && this.engine && this.currentIndex == null) this._cueFirst();
1296
1327
  this._emit("ready", { sounds: this.sounds.length });
1297
1328
  this.options.onReady?.(this);
1298
1329
  }
1299
1330
  /**
1300
1331
  * The sounds from the `sounds` option, else the `manifest` URL.
1301
- * @returns {Promise<import('../../../index').Sound[]>}
1302
- * @private
1332
+ * @returns
1333
+ * @internal
1303
1334
  */
1304
1335
  async _loadSounds() {
1305
1336
  if (this.options.sounds || !this.options.manifest) return normalizeSounds(this.options.sounds || []);
@@ -1309,7 +1340,7 @@ var WaveformSounds = class _WaveformSounds {
1309
1340
  }
1310
1341
  /**
1311
1342
  * Look up the elements the runtime drives.
1312
- * @private
1343
+ * @internal
1313
1344
  */
1314
1345
  _cacheRefs() {
1315
1346
  const q = (sel) => this.container.querySelector(sel);
@@ -1336,7 +1367,7 @@ var WaveformSounds = class _WaveformSounds {
1336
1367
  /**
1337
1368
  * Every listener. All are removed by `destroy()` through one
1338
1369
  * AbortController.
1339
- * @private
1370
+ * @internal
1340
1371
  */
1341
1372
  _bind() {
1342
1373
  const sig = { signal: this._ctl.signal };
@@ -1388,7 +1419,7 @@ var WaveformSounds = class _WaveformSounds {
1388
1419
  /**
1389
1420
  * Clicks: type chips, loops or one-shots, Show more, Clear, Loop, a touch tap on a waveform
1390
1421
  * (seek), and anywhere else on a row (play/pause).
1391
- * @private
1422
+ * @internal
1392
1423
  */
1393
1424
  _onClick(e) {
1394
1425
  const t = e.target;
@@ -1427,7 +1458,7 @@ var WaveformSounds = class _WaveformSounds {
1427
1458
  /**
1428
1459
  * Mouse and pen seek on PRESS, like every scrubber. Remembers the
1429
1460
  * pointer type for the click that follows.
1430
- * @private
1461
+ * @internal
1431
1462
  */
1432
1463
  _onPointerDown(e) {
1433
1464
  this._lastPointer = e.pointerType;
@@ -1438,7 +1469,7 @@ var WaveformSounds = class _WaveformSounds {
1438
1469
  }
1439
1470
  /**
1440
1471
  * Seek (or start) a row's sound where its waveform was pressed.
1441
- * @private
1472
+ * @internal
1442
1473
  */
1443
1474
  _seekAt(wave, clientX) {
1444
1475
  const row = wave.closest("[data-ws-index]");
@@ -1448,7 +1479,7 @@ var WaveformSounds = class _WaveformSounds {
1448
1479
  /**
1449
1480
  * Keys on the list: `/` focuses search; ↑/↓/Home/End move between rows
1450
1481
  * (auditioning while something plays); ←/→ seek the playing row.
1451
- * @private
1482
+ * @internal
1452
1483
  */
1453
1484
  _onKey(e) {
1454
1485
  if (e.defaultPrevented || e.altKey || e.ctrlKey || e.metaKey) return;
@@ -1480,7 +1511,7 @@ var WaveformSounds = class _WaveformSounds {
1480
1511
  }
1481
1512
  /**
1482
1513
  * Focus a row's play button.
1483
- * @private
1514
+ * @internal
1484
1515
  */
1485
1516
  _focusRow(row) {
1486
1517
  row?.querySelector(".ws-play")?.focus();
@@ -1491,7 +1522,7 @@ var WaveformSounds = class _WaveformSounds {
1491
1522
  * on the title or waveform left focus on <body>, and Safari never
1492
1523
  * focuses a clicked button). No scroll jump, and no focus ring: the
1493
1524
  * browser shows none for a focus that follows a pointer.
1494
- * @private
1525
+ * @internal
1495
1526
  */
1496
1527
  _focusRowQuietly(row) {
1497
1528
  const btn = row?.querySelector(".ws-play");
@@ -1501,7 +1532,7 @@ var WaveformSounds = class _WaveformSounds {
1501
1532
  /**
1502
1533
  * Draw row canvases as they scroll into view; redraw on resize and on
1503
1534
  * theme flips (the canvas can't follow CSS by itself).
1504
- * @private
1535
+ * @internal
1505
1536
  */
1506
1537
  _observe() {
1507
1538
  if (this.render.player !== "inline" || typeof window === "undefined") return;
@@ -1545,7 +1576,7 @@ var WaveformSounds = class _WaveformSounds {
1545
1576
  /**
1546
1577
  * Resolve the canvas colours (options, else the CSS custom properties)
1547
1578
  * and keep `--ws-surface` current unless the site set it.
1548
- * @private
1579
+ * @internal
1549
1580
  */
1550
1581
  _resolveColors() {
1551
1582
  if (this._autoSurface || !getComputedStyle(this.container).getPropertyValue("--ws-surface").trim()) {
@@ -1560,7 +1591,7 @@ var WaveformSounds = class _WaveformSounds {
1560
1591
  }
1561
1592
  /**
1562
1593
  * Draw one row's waveform (only once it has been on screen).
1563
- * @private
1594
+ * @internal
1564
1595
  */
1565
1596
  _drawRow(index) {
1566
1597
  if (this.render.player !== "inline" || index == null || !this._drawn?.has(index)) return;
@@ -1578,7 +1609,7 @@ var WaveformSounds = class _WaveformSounds {
1578
1609
  }
1579
1610
  /**
1580
1611
  * Redraw every row drawn so far.
1581
- * @private
1612
+ * @internal
1582
1613
  */
1583
1614
  _redrawAll() {
1584
1615
  this._drawn?.forEach((i) => this._drawRow(i));
@@ -1586,7 +1617,7 @@ var WaveformSounds = class _WaveformSounds {
1586
1617
  /* ── Filters in the address ───────────────────────────────────────── */
1587
1618
  /**
1588
1619
  * Apply the filter and sort from the address (`urlState`).
1589
- * @private
1620
+ * @internal
1590
1621
  */
1591
1622
  _readUrl() {
1592
1623
  const keys = urlKeys(this.options.urlState);
@@ -1601,7 +1632,7 @@ var WaveformSounds = class _WaveformSounds {
1601
1632
  /**
1602
1633
  * Rewrite the address shortly after a change (replaceState: no history
1603
1634
  * entries).
1604
- * @private
1635
+ * @internal
1605
1636
  */
1606
1637
  _queueUrl() {
1607
1638
  const keys = urlKeys(this.options.urlState);
@@ -1618,12 +1649,6 @@ var WaveformSounds = class _WaveformSounds {
1618
1649
  get visible() {
1619
1650
  return sortSounds(this.sounds.filter((s) => matches(s, this.filter)), this.sortBy);
1620
1651
  }
1621
- /**
1622
- * Change the filter (merged into the current one) and re-apply. Back to
1623
- * the first page.
1624
- *
1625
- * @param {Partial<import('../../../index').SoundsFilter>} patch
1626
- */
1627
1652
  setFilter(patch = {}) {
1628
1653
  this.filter = { ...this.filter, ...patch };
1629
1654
  this.limit = this._pageSize();
@@ -1634,7 +1659,7 @@ var WaveformSounds = class _WaveformSounds {
1634
1659
  clearFilters() {
1635
1660
  this.setFilter(NO_FILTER);
1636
1661
  }
1637
- /** @param {import('../../../index').SoundsSort} by */
1662
+ /** @param by */
1638
1663
  setSort(by) {
1639
1664
  this._sortSet = true;
1640
1665
  this.sortBy = SORTS.includes(by) ? by : "default";
@@ -1649,7 +1674,7 @@ var WaveformSounds = class _WaveformSounds {
1649
1674
  }
1650
1675
  /**
1651
1676
  * Rows per page (Infinity when paging is off).
1652
- * @private
1677
+ * @internal
1653
1678
  */
1654
1679
  _pageSize() {
1655
1680
  return this.render.pageSize > 0 ? this.render.pageSize : Infinity;
@@ -1657,7 +1682,7 @@ var WaveformSounds = class _WaveformSounds {
1657
1682
  /**
1658
1683
  * Show the current filter and sort in the controls (they can be set from
1659
1684
  * code or the address, not only by the controls themselves).
1660
- * @private
1685
+ * @internal
1661
1686
  */
1662
1687
  _syncControls() {
1663
1688
  const $ = this.$, f = this.filter;
@@ -1679,7 +1704,7 @@ var WaveformSounds = class _WaveformSounds {
1679
1704
  * Show a BPM filter in its menu: the button label, the panel's readout,
1680
1705
  * the filled part of the track, and which handle sits on top (the one
1681
1706
  * that can still move, when they meet).
1682
- * @private
1707
+ * @internal
1683
1708
  */
1684
1709
  _showBpm(f) {
1685
1710
  const $ = this.$, extent = this._bpmExtent;
@@ -1696,9 +1721,9 @@ var WaveformSounds = class _WaveformSounds {
1696
1721
  * Lay the rows out for the current filter, sort and page: order, hide,
1697
1722
  * "Show more", the empty state and the count. Then report it.
1698
1723
  *
1699
- * @param {{resort: boolean}} opts - Reorder the rows even if the sort
1724
+ * @param opts - Reorder the rows even if the sort
1700
1725
  * hasn't changed.
1701
- * @private
1726
+ * @internal
1702
1727
  */
1703
1728
  _apply({ resort }) {
1704
1729
  const $ = this.$;
@@ -1718,6 +1743,7 @@ var WaveformSounds = class _WaveformSounds {
1718
1743
  }
1719
1744
  if ($.empty) $.empty.hidden = shown.length > 0;
1720
1745
  if ($.count) $.count.textContent = countText(shown.length, this.sounds.length, this.strings);
1746
+ if (this._cued && !this.playing) this._cueFirst();
1721
1747
  this._queueUrl();
1722
1748
  this._emit("filter", { visible: shown.length, total: this.sounds.length, filter: { ...this.filter }, sort: this.sortBy });
1723
1749
  this.options.onFilter?.(shown, this);
@@ -1727,9 +1753,9 @@ var WaveformSounds = class _WaveformSounds {
1727
1753
  * Resolve an index, id or sound to an index in `this.sounds`. No
1728
1754
  * target means the current sound, else the first visible one.
1729
1755
  *
1730
- * @param {number|string|Object} [target]
1731
- * @returns {number|null}
1732
- * @private
1756
+ * @param target
1757
+ * @returns
1758
+ * @internal
1733
1759
  */
1734
1760
  _indexOf(target) {
1735
1761
  if (target == null) return this.currentIndex ?? (this.visible[0] ? this.sounds.indexOf(this.visible[0]) : null);
@@ -1739,8 +1765,8 @@ var WaveformSounds = class _WaveformSounds {
1739
1765
  }
1740
1766
  /**
1741
1767
  * The WaveformPlayer class: `playerClass`, else the page's global.
1742
- * @returns {Function|null}
1743
- * @private
1768
+ * @returns
1769
+ * @internal
1744
1770
  */
1745
1771
  _playerClass() {
1746
1772
  return this.options.playerClass || (typeof window !== "undefined" ? window.WaveformPlayer : null) || null;
@@ -1751,8 +1777,8 @@ var WaveformSounds = class _WaveformSounds {
1751
1777
  * which would strip `ws-engine--strip` (and with it the docked styling).
1752
1778
  * Made here rather than in the markup so server-rendered HTML from any
1753
1779
  * version works.
1754
- * @returns {HTMLElement}
1755
- * @private
1780
+ * @returns
1781
+ * @internal
1756
1782
  */
1757
1783
  _engineMount() {
1758
1784
  const slot = this.$.engine;
@@ -1766,8 +1792,8 @@ var WaveformSounds = class _WaveformSounds {
1766
1792
  }
1767
1793
  /**
1768
1794
  * Build the engine once (it holds no audio until a play).
1769
- * @returns {Object|null} The engine, or null without a player class.
1770
- * @private
1795
+ * @returns The engine, or null without a player class.
1796
+ * @internal
1771
1797
  */
1772
1798
  _ensureEngine() {
1773
1799
  if (this.engine) return this.engine;
@@ -1790,8 +1816,8 @@ var WaveformSounds = class _WaveformSounds {
1790
1816
  * Play a sound (by index, id or sound object), or resume the current
1791
1817
  * one. Before the list is built the call waits for it.
1792
1818
  *
1793
- * @param {number|string|Object} [target]
1794
- * @param {{at?: number}} [opts] - `at`: start position 0..1.
1819
+ * @param target
1820
+ * @param opts - `at`: start position 0..1.
1795
1821
  */
1796
1822
  play(target, opts = {}) {
1797
1823
  if (!this.$) {
@@ -1802,6 +1828,7 @@ var WaveformSounds = class _WaveformSounds {
1802
1828
  }
1803
1829
  const index = this._indexOf(target);
1804
1830
  if (index == null) return;
1831
+ this._cued = false;
1805
1832
  const engine = this._ensureEngine();
1806
1833
  if (!engine) return;
1807
1834
  if (index === this.currentIndex && engine.audio?.src) {
@@ -1816,7 +1843,26 @@ var WaveformSounds = class _WaveformSounds {
1816
1843
  if (previous != null) this._paintRow(previous);
1817
1844
  this._paintRow(index);
1818
1845
  const sound = this.sounds[index];
1819
- 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));
1847
+ }
1848
+ /**
1849
+ * Strip layout: load the first sound the list shows into the docked
1850
+ * player WITHOUT playing it, so the player shows a title and waveform
1851
+ * (and its play button plays that sound) instead of an empty frame.
1852
+ * Only metadata is fetched — the browser default for any `<audio>`.
1853
+ * The row isn't marked current until it plays.
1854
+ * @internal
1855
+ */
1856
+ _cueFirst() {
1857
+ const engine = this.engine;
1858
+ const first = this.visible[0];
1859
+ if (!engine || !first) return;
1860
+ const index = this.sounds.indexOf(first);
1861
+ if (index === this.currentIndex) return;
1862
+ this.currentIndex = index;
1863
+ this.progress = 0;
1864
+ this._cued = true;
1865
+ engine.loadTrack(first.url, first.title, first.type || null, engineTrack(first, "strip", false));
1820
1866
  }
1821
1867
  /** Pause the current sound. */
1822
1868
  pause() {
@@ -1824,7 +1870,7 @@ var WaveformSounds = class _WaveformSounds {
1824
1870
  }
1825
1871
  /**
1826
1872
  * The current sound plays/pauses; another sound starts.
1827
- * @param {number|string|Object} [target]
1873
+ * @param target
1828
1874
  */
1829
1875
  toggle(target) {
1830
1876
  const index = this._indexOf(target);
@@ -1844,13 +1890,13 @@ var WaveformSounds = class _WaveformSounds {
1844
1890
  * Play the visible sound `dir` places away, revealing it if it's past
1845
1891
  * the current page.
1846
1892
  *
1847
- * @param {1|-1} dir
1848
- * @returns {boolean} Whether there was one.
1849
- * @private
1893
+ * @param dir
1894
+ * @returns Whether there was one.
1895
+ * @internal
1850
1896
  */
1851
1897
  _step(dir) {
1852
1898
  const shown = this.visible;
1853
- const at = this.currentIndex == null ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
1899
+ const at = this.currentIndex == null || this._cued ? -1 : shown.indexOf(this.sounds[this.currentIndex]);
1854
1900
  const target = shown[at + dir];
1855
1901
  if (!target) return false;
1856
1902
  const limit = limitToReveal(this.limit, at + dir);
@@ -1865,7 +1911,7 @@ var WaveformSounds = class _WaveformSounds {
1865
1911
  * Loop the current sound (auditioning a loop is the common case). When
1866
1912
  * the list marks its loops (`loop: true` on any sound), only those
1867
1913
  * repeat: a one-shot always plays once.
1868
- * @param {boolean} on
1914
+ * @param on
1869
1915
  */
1870
1916
  setLoop(on) {
1871
1917
  this._loopSet = true;
@@ -1874,7 +1920,7 @@ var WaveformSounds = class _WaveformSounds {
1874
1920
  }
1875
1921
  /**
1876
1922
  * Apply the loop state to the toggle and the engine.
1877
- * @private
1923
+ * @internal
1878
1924
  */
1879
1925
  _setLoop(on) {
1880
1926
  this.$?.loop?.setAttribute("aria-pressed", String(on));
@@ -1883,7 +1929,7 @@ var WaveformSounds = class _WaveformSounds {
1883
1929
  /**
1884
1930
  * Should the current sound repeat? The Loop toggle is on, and either
1885
1931
  * the list doesn't say which sounds are loops or this one is.
1886
- * @private
1932
+ * @internal
1887
1933
  */
1888
1934
  _repeats() {
1889
1935
  if (!this.loop) return false;
@@ -1893,7 +1939,7 @@ var WaveformSounds = class _WaveformSounds {
1893
1939
  /**
1894
1940
  * Seek a row's sound to `fraction`; a row that isn't current starts
1895
1941
  * there. Before the duration is known the seek waits for it.
1896
- * @private
1942
+ * @internal
1897
1943
  */
1898
1944
  _seekRow(index, fraction) {
1899
1945
  if (index !== this.currentIndex || !this.engine) {
@@ -1913,7 +1959,7 @@ var WaveformSounds = class _WaveformSounds {
1913
1959
  /**
1914
1960
  * The engine loaded a sound: apply the loop, borrow decoded peaks for a
1915
1961
  * row that had none, and land a pending seek.
1916
- * @private
1962
+ * @internal
1917
1963
  */
1918
1964
  _onEngineLoad() {
1919
1965
  if (this.engine?.audio) this.engine.audio.loop = this._repeats();
@@ -1931,7 +1977,7 @@ var WaveformSounds = class _WaveformSounds {
1931
1977
  }
1932
1978
  /**
1933
1979
  * Playback progress: repaint the current row, once per frame.
1934
- * @private
1980
+ * @internal
1935
1981
  */
1936
1982
  _onTime(time, duration) {
1937
1983
  if (this.currentIndex == null || !duration) return;
@@ -1951,7 +1997,7 @@ var WaveformSounds = class _WaveformSounds {
1951
1997
  }
1952
1998
  /**
1953
1999
  * A sound finished: report it, then auto-advance or settle.
1954
- * @private
2000
+ * @internal
1955
2001
  */
1956
2002
  _onEnd() {
1957
2003
  const sound = this.sounds[this.currentIndex];
@@ -1963,7 +2009,7 @@ var WaveformSounds = class _WaveformSounds {
1963
2009
  }
1964
2010
  /**
1965
2011
  * A sound failed to load or play: mark its row and report it.
1966
- * @private
2012
+ * @internal
1967
2013
  */
1968
2014
  _onEngineError(err) {
1969
2015
  this.rows[this.currentIndex]?.classList.add("is-error");
@@ -1974,11 +2020,12 @@ var WaveformSounds = class _WaveformSounds {
1974
2020
  * Record play/pause and repaint. Events fire only on a real change: at a
1975
2021
  * natural end the browser fires `pause` then `ended`, and `_onEnd()`
1976
2022
  * also settles the state — one pause event, not two.
1977
- * @private
2023
+ * @internal
1978
2024
  */
1979
2025
  _setPlaying(on) {
1980
2026
  const changed = this.playing !== on;
1981
2027
  this.playing = on;
2028
+ if (on) this._cued = false;
1982
2029
  const index = this.currentIndex;
1983
2030
  if (index == null) return;
1984
2031
  this._paintRow(index);
@@ -1991,7 +2038,7 @@ var WaveformSounds = class _WaveformSounds {
1991
2038
  /* ── Row painting ─────────────────────────────────────────────────── */
1992
2039
  /**
1993
2040
  * A row's state classes, play-button label and waveform.
1994
- * @private
2041
+ * @internal
1995
2042
  */
1996
2043
  _paintRow(index) {
1997
2044
  const row = this.rows[index];
@@ -2015,14 +2062,14 @@ var WaveformSounds = class _WaveformSounds {
2015
2062
  /* ── Events & lifecycle ──────────────────────────────────────────── */
2016
2063
  /**
2017
2064
  * Emit a `waveformsounds:<name>` event carrying this instance.
2018
- * @private
2065
+ * @internal
2019
2066
  */
2020
2067
  _emit(name, detail = {}) {
2021
2068
  emit(this.container, name, { ...detail, instance: this });
2022
2069
  }
2023
2070
  /** The sound playing (or paused) now, or null. */
2024
2071
  get current() {
2025
- return this.currentIndex == null ? null : this.sounds[this.currentIndex];
2072
+ return this.currentIndex == null || this._cued ? null : this.sounds[this.currentIndex];
2026
2073
  }
2027
2074
  /**
2028
2075
  * Tear down: listeners, observers, timers and the engine. Markup this
@@ -2055,8 +2102,8 @@ var WaveformSounds = class _WaveformSounds {
2055
2102
  /**
2056
2103
  * Initialise every `[data-waveform-sounds]` under `root` that isn't yet.
2057
2104
  *
2058
- * @param {ParentNode} [root=document]
2059
- * @returns {WaveformSounds[]} The new instances.
2105
+ * @param root
2106
+ * @returns The new instances.
2060
2107
  */
2061
2108
  static init(root = document) {
2062
2109
  if (typeof document === "undefined") return [];
@@ -2075,8 +2122,8 @@ var WaveformSounds = class _WaveformSounds {
2075
2122
  }
2076
2123
  /**
2077
2124
  * The instance on an element (or selector), if any.
2078
- * @param {Element|string} el
2079
- * @returns {WaveformSounds|null}
2125
+ * @param el
2126
+ * @returns
2080
2127
  */
2081
2128
  static getInstance(el) {
2082
2129
  const node = typeof el === "string" ? document.querySelector(el) : el;
@@ -2089,7 +2136,7 @@ var WaveformSounds = class _WaveformSounds {
2089
2136
  }
2090
2137
  };
2091
2138
 
2092
- // src/js/entry.js
2139
+ // src/js/entry.ts
2093
2140
  WaveformSounds.utils = { encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration, renderSounds };
2094
2141
  WaveformSounds.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
2095
2142
  WaveformSounds.DEFAULT_STRINGS = DEFAULT_STRINGS;