@arraypress/waveform-sounds 0.3.1 → 2.1.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 (89) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +43 -3
  3. package/dist/waveform-sounds-no-autoinit.esm.js +607 -178
  4. package/dist/waveform-sounds-render.esm.js +79 -15
  5. package/dist/waveform-sounds.css +136 -79
  6. package/dist/waveform-sounds.esm.js +611 -181
  7. package/dist/waveform-sounds.js +608 -181
  8. package/dist/waveform-sounds.min.css +1 -1
  9. package/dist/waveform-sounds.min.js +3 -3
  10. package/package.json +36 -33
  11. package/src/css/waveform-sounds.css +136 -79
  12. package/src/js/core/WaveformSounds.ts +1366 -0
  13. package/src/js/core/element.ts +208 -0
  14. package/src/js/core/engine.ts +107 -0
  15. package/src/js/core/{options.js → options.ts} +28 -28
  16. package/src/js/data/{bpm.js → bpm.ts} +27 -17
  17. package/src/js/data/{navigation.js → navigation.ts} +31 -18
  18. package/src/js/data/{sounds.js → sounds.ts} +97 -66
  19. package/src/js/data/url-state.ts +130 -0
  20. package/src/js/dom/colors.ts +86 -0
  21. package/src/js/dom/{draw.js → draw.ts} +16 -17
  22. package/src/js/dom/{menus.js → menus.ts} +70 -55
  23. package/src/js/dom/{rows.js → rows.ts} +15 -17
  24. package/src/js/entry.ts +60 -0
  25. package/src/js/{index.js → index.ts} +7 -3
  26. package/src/js/render/{html.js → html.ts} +16 -12
  27. package/src/js/render/{icons.js → icons.ts} +3 -4
  28. package/src/js/render/{markup.js → markup.ts} +114 -64
  29. package/src/js/render/options.ts +118 -0
  30. package/src/js/render/{strings.js → strings.ts} +18 -16
  31. package/src/js/{render-entry.js → render-entry.ts} +2 -1
  32. package/src/js/shared/{utils.js → utils.ts} +24 -24
  33. package/{index.d.ts → src/js/types.ts} +40 -88
  34. package/types/core/WaveformSounds.d.ts +175 -0
  35. package/types/core/WaveformSounds.d.ts.map +1 -0
  36. package/types/core/element.d.ts +84 -0
  37. package/types/core/element.d.ts.map +1 -0
  38. package/types/core/engine.d.ts +72 -0
  39. package/types/core/engine.d.ts.map +1 -0
  40. package/types/core/options.d.ts +71 -0
  41. package/types/core/options.d.ts.map +1 -0
  42. package/types/data/bpm.d.ts +80 -0
  43. package/types/data/bpm.d.ts.map +1 -0
  44. package/types/data/navigation.d.ts +62 -0
  45. package/types/data/navigation.d.ts.map +1 -0
  46. package/types/data/sounds.d.ts +168 -0
  47. package/types/data/sounds.d.ts.map +1 -0
  48. package/types/data/url-state.d.ts +109 -0
  49. package/types/data/url-state.d.ts.map +1 -0
  50. package/types/dom/colors.d.ts +48 -0
  51. package/types/dom/colors.d.ts.map +1 -0
  52. package/types/dom/draw.d.ts +72 -0
  53. package/types/dom/draw.d.ts.map +1 -0
  54. package/types/dom/menus.d.ts +75 -0
  55. package/types/dom/menus.d.ts.map +1 -0
  56. package/types/dom/rows.d.ts +39 -0
  57. package/types/dom/rows.d.ts.map +1 -0
  58. package/types/entry.d.ts +28 -0
  59. package/types/entry.d.ts.map +1 -0
  60. package/types/index.d.ts +16 -0
  61. package/types/index.d.ts.map +1 -0
  62. package/types/render/html.d.ts +37 -0
  63. package/types/render/html.d.ts.map +1 -0
  64. package/types/render/icons.d.ts +17 -0
  65. package/types/render/icons.d.ts.map +1 -0
  66. package/types/render/markup.d.ts +141 -0
  67. package/types/render/markup.d.ts.map +1 -0
  68. package/types/render/options.d.ts +69 -0
  69. package/types/render/options.d.ts.map +1 -0
  70. package/types/render/strings.d.ts +43 -0
  71. package/types/render/strings.d.ts.map +1 -0
  72. package/types/render-entry.d.ts +8 -0
  73. package/types/render-entry.d.ts.map +1 -0
  74. package/types/shared/utils.d.ts +57 -0
  75. package/types/shared/utils.d.ts.map +1 -0
  76. package/types/types.d.ts +280 -0
  77. package/types/types.d.ts.map +1 -0
  78. package/types/vendor/arraypress-text.d.ts +250 -0
  79. package/dist/waveform-sounds-no-autoinit.cjs +0 -2159
  80. package/dist/waveform-sounds-render.cjs +0 -614
  81. package/dist/waveform-sounds.cjs +0 -2181
  82. package/no-autoinit.d.ts +0 -2
  83. package/render.d.ts +0 -5
  84. package/src/js/core/WaveformSounds.js +0 -993
  85. package/src/js/core/engine.js +0 -57
  86. package/src/js/data/url-state.js +0 -106
  87. package/src/js/dom/colors.js +0 -59
  88. package/src/js/entry.js +0 -25
  89. package/src/js/render/options.js +0 -90
@@ -21,11 +21,10 @@ import {fold} from '@arraypress/text';
21
21
  * Does an option's label match what's typed in a menu's search field?
22
22
  * Case- and accent-insensitive substring.
23
23
  *
24
- * @param {string} label
25
- * @param {string} query
26
- * @returns {boolean}
24
+ * @param label
25
+ * @param query
27
26
  */
28
- export function optionMatches(label, query) {
27
+ export function optionMatches(label: string, query: string): boolean {
29
28
  const q = fold(String(query ?? '')).trim();
30
29
  return !q || fold(String(label ?? '')).includes(q);
31
30
  }
@@ -33,48 +32,64 @@ export function optionMatches(label, query) {
33
32
  /**
34
33
  * Move an index by `delta`, clamped to `0..length-1`.
35
34
  *
36
- * @param {number} current - -1 when nothing is active.
37
- * @param {number} delta
38
- * @param {number} length
39
- * @returns {number}
35
+ * @param current - -1 when nothing is active.
36
+ * @param delta
37
+ * @param length
40
38
  */
41
- export function stepIndex(current, delta, length) {
39
+ export function stepIndex(current: number, delta: number, length: number): number {
42
40
  return Math.max(0, Math.min(length - 1, current + delta));
43
41
  }
44
42
 
43
+ /** One dropdown's elements. A panel (the BPM range) has no list, search or none. */
44
+ interface MenuParts {
45
+ button: HTMLElement;
46
+ pop: HTMLElement;
47
+ search: HTMLInputElement | null;
48
+ list: HTMLElement | null;
49
+ none: HTMLElement | null;
50
+ value: HTMLElement | null;
51
+ }
52
+
45
53
  /** The parts of one dropdown. */
46
- function partsOf(menu) {
54
+ function partsOf(menu: HTMLElement): MenuParts {
47
55
  return {
48
- button: menu.querySelector('[data-ws-menu-btn]'),
49
- pop: menu.querySelector('[data-ws-menu-pop]'),
50
- search: menu.querySelector('[data-ws-menu-search]'),
51
- list: menu.querySelector('[data-ws-menu-list]'),
52
- none: menu.querySelector('[data-ws-menu-none]'),
53
- value: menu.querySelector('[data-ws-menu-value]'),
56
+ button: menu.querySelector<HTMLElement>('[data-ws-menu-btn]')!,
57
+ pop: menu.querySelector<HTMLElement>('[data-ws-menu-pop]')!,
58
+ search: menu.querySelector<HTMLInputElement>('[data-ws-menu-search]'),
59
+ list: menu.querySelector<HTMLElement>('[data-ws-menu-list]'),
60
+ none: menu.querySelector<HTMLElement>('[data-ws-menu-none]'),
61
+ value: menu.querySelector<HTMLElement>('[data-ws-menu-value]'),
54
62
  };
55
63
  }
56
64
 
57
65
  /** The element that owns focus while a menu is open (a panel: its first field, else its first button). */
58
- const focusOwner = (p) => p.search || p.list || p.pop.querySelector('input') || p.pop.querySelector('button');
66
+ const focusOwner = (p: MenuParts): HTMLElement | null => p.search || p.list || p.pop.querySelector('input') || p.pop.querySelector('button');
59
67
 
60
68
  /** A menu's options, optionally only the ones not filtered out. */
61
- const optionsOf = (p, visibleOnly = false) => [...p.list.querySelectorAll('[role="option"]')].filter((o) => !visibleOnly || !o.hidden);
69
+ const optionsOf = (p: MenuParts, visibleOnly = false): HTMLElement[] => [...p.list!.querySelectorAll<HTMLElement>('[role="option"]')].filter((o) => !visibleOnly || !o.hidden);
62
70
 
63
71
  /**
64
72
  * Every dropdown inside one list, with one shared "which is open" state.
65
73
  */
66
74
  export class Menus {
75
+ /** @internal */ declare container: HTMLElement;
76
+ /** @internal */ declare onPick: (name: string, value: string) => void;
77
+ /** Each menu's root element, by its `data-ws-menu` name. */
78
+ declare menus: Record<string, HTMLElement>;
79
+ /** The open menu's root element, if any. */
80
+ declare openMenu: HTMLElement | null;
81
+
67
82
  /**
68
83
  * @param {HTMLElement} container - The list's root element.
69
84
  * @param {Object} opts
70
85
  * @param {(name: string, value: string) => void} opts.onPick - A value was chosen.
71
86
  * @param {AbortSignal} opts.signal - Removes every listener on abort.
72
87
  */
73
- constructor(container, {onPick, signal}) {
88
+ constructor(container: HTMLElement, {onPick, signal}: {onPick: (name: string, value: string) => void, signal: AbortSignal}) {
74
89
  this.container = container;
75
90
  this.onPick = onPick;
76
91
  /** @type {Record<string, HTMLElement>} */
77
- this.menus = Object.fromEntries([...container.querySelectorAll('[data-ws-menu]')].map((m) => [m.dataset.wsMenu, m]));
92
+ this.menus = Object.fromEntries([...container.querySelectorAll<HTMLElement>('[data-ws-menu]')].map((m) => [m.dataset.wsMenu!, m]));
78
93
  /** @type {HTMLElement|null} */
79
94
  this.openMenu = null;
80
95
  this._bind(signal);
@@ -82,10 +97,10 @@ export class Menus {
82
97
 
83
98
  /**
84
99
  * Wire every menu, plus closing on an outside press or focus leaving.
85
- * @param {AbortSignal} signal
86
- * @private
100
+ * @param signal
101
+ * @internal
87
102
  */
88
- _bind(signal) {
103
+ _bind(signal: AbortSignal) {
89
104
  const sig = {signal};
90
105
  for (const [name, menu] of Object.entries(this.menus)) {
91
106
  const p = partsOf(menu);
@@ -104,19 +119,19 @@ export class Menus {
104
119
  continue;
105
120
  }
106
121
  p.list.addEventListener('click', (e) => {
107
- const opt = e.target.closest('[role="option"]');
108
- if (opt) this._pick(name, opt.dataset.value);
122
+ const opt = (e.target as Element).closest<HTMLElement>('[role="option"]');
123
+ if (opt) this._pick(name, opt.dataset.value!);
109
124
  }, sig);
110
125
  // Keep focus in the field while an option is pressed.
111
126
  p.list.addEventListener('mousedown', (e) => e.preventDefault(), sig);
112
- p.search?.addEventListener('input', () => this._filter(menu, p.search.value), sig);
113
- focusOwner(p).addEventListener('keydown', (e) => this._onKey(e, name, menu), sig);
127
+ p.search?.addEventListener('input', () => this._filter(menu, p.search!.value), sig);
128
+ focusOwner(p)!.addEventListener('keydown', (e: KeyboardEvent) => this._onKey(e, name, menu), sig);
114
129
  }
115
130
  document.addEventListener('pointerdown', (e) => {
116
- if (this.openMenu && !this.openMenu.contains(e.target)) this.close(false);
131
+ if (this.openMenu && !this.openMenu.contains(e.target as Node)) this.close(false);
117
132
  }, sig);
118
133
  this.container.addEventListener('focusout', (e) => {
119
- if (this.openMenu && !this.openMenu.contains(e.relatedTarget)) this.close(false);
134
+ if (this.openMenu && !this.openMenu.contains(e.relatedTarget as Node | null)) this.close(false);
120
135
  }, sig);
121
136
  }
122
137
 
@@ -125,9 +140,9 @@ export class Menus {
125
140
  * focus in its search field or list. Flips to open over the end edge
126
141
  * when it would overflow the list.
127
142
  *
128
- * @param {HTMLElement} menu
143
+ * @param menu
129
144
  */
130
- open(menu) {
145
+ open(menu: HTMLElement) {
131
146
  if (this.openMenu && this.openMenu !== menu) this.close(false);
132
147
  const p = partsOf(menu);
133
148
  p.button.setAttribute('aria-expanded', 'true');
@@ -136,17 +151,17 @@ export class Menus {
136
151
  if (p.search) { p.search.value = ''; this._filter(menu, ''); }
137
152
  menu.classList.remove('ws-menu--end');
138
153
  if (p.pop.getBoundingClientRect().right > this.container.getBoundingClientRect().right + 1) menu.classList.add('ws-menu--end');
139
- if (p.list) this._activate(menu, p.list.querySelector('[role="option"][aria-selected="true"]'));
154
+ if (p.list) this._activate(menu, p.list.querySelector<HTMLElement>('[role="option"][aria-selected="true"]'));
140
155
  focusOwner(p)?.focus();
141
156
  }
142
157
 
143
158
  /**
144
159
  * Close the open menu, if any.
145
160
  *
146
- * @param {boolean} focusButton - Return focus to its button (after a
161
+ * @param focusButton - Return focus to its button (after a
147
162
  * pick or Esc; not after a click elsewhere).
148
163
  */
149
- close(focusButton) {
164
+ close(focusButton: boolean) {
150
165
  const menu = this.openMenu;
151
166
  if (!menu) return;
152
167
  this.openMenu = null;
@@ -160,48 +175,48 @@ export class Menus {
160
175
  * Show `value` as a menu's choice (button text + `aria-selected`). Used
161
176
  * after a pick and when the filter is changed from code.
162
177
  *
163
- * @param {string} name - 'type' | 'key' | 'sort'.
164
- * @param {string} value
178
+ * @param name - 'type' | 'key' | 'sort'.
179
+ * @param value
165
180
  */
166
- setValue(name, value) {
181
+ setValue(name: string, value: string) {
167
182
  const menu = this.menus[name];
168
183
  if (!menu) return;
169
184
  const p = partsOf(menu);
170
185
  if (!p.list) return; // a panel shows its own value
171
- let label = null;
186
+ let label: string | null = null;
172
187
  for (const opt of optionsOf(p)) {
173
188
  const on = opt.dataset.value === String(value ?? '');
174
189
  opt.setAttribute('aria-selected', String(on));
175
190
  if (on) label = opt.querySelector('.ws-menu-text')?.textContent ?? '';
176
191
  }
177
- if (label !== null) p.value.textContent = label;
192
+ if (label !== null) p.value!.textContent = label;
178
193
  }
179
194
 
180
195
  /**
181
196
  * Narrow a menu to the options matching the search, and make the first
182
197
  * match active.
183
- * @private
198
+ * @internal
184
199
  */
185
- _filter(menu, query) {
200
+ _filter(menu: HTMLElement, query: string): void {
186
201
  const p = partsOf(menu);
187
- let first = null;
202
+ let first: HTMLElement | null = null;
188
203
  for (const opt of optionsOf(p)) {
189
204
  opt.hidden = !optionMatches(opt.textContent, query);
190
205
  if (!opt.hidden) first ??= opt;
191
206
  }
192
- p.none.hidden = first !== null;
207
+ p.none!.hidden = first !== null;
193
208
  this._activate(menu, first);
194
209
  }
195
210
 
196
211
  /**
197
212
  * Mark one option active (`aria-activedescendant`) and scroll it into
198
213
  * the list's view.
199
- * @private
214
+ * @internal
200
215
  */
201
- _activate(menu, opt) {
216
+ _activate(menu: HTMLElement, opt: HTMLElement | null | undefined): void {
202
217
  const p = partsOf(menu);
203
- for (const o of p.list.querySelectorAll('.is-active')) o.classList.remove('is-active');
204
- const owner = focusOwner(p);
218
+ for (const o of p.list!.querySelectorAll('.is-active')) o.classList.remove('is-active');
219
+ const owner = focusOwner(p)!;
205
220
  if (!opt || opt.hidden) { owner.removeAttribute('aria-activedescendant'); return; }
206
221
  opt.classList.add('is-active');
207
222
  owner.setAttribute('aria-activedescendant', opt.id);
@@ -210,14 +225,14 @@ export class Menus {
210
225
 
211
226
  /**
212
227
  * Keys inside an open menu.
213
- * @private
228
+ * @internal
214
229
  */
215
- _onKey(e, name, menu) {
230
+ _onKey(e: KeyboardEvent, name: string, menu: HTMLElement) {
216
231
  const p = partsOf(menu);
217
232
  const opts = optionsOf(p, true);
218
- const at = opts.indexOf(p.list.querySelector('.is-active'));
219
- const moveTo = (i) => { e.preventDefault(); this._activate(menu, opts[i]); };
220
- const inField = e.target.matches('input');
233
+ const at = opts.indexOf(p.list!.querySelector<HTMLElement>('.is-active')!);
234
+ const moveTo = (i: number) => { e.preventDefault(); this._activate(menu, opts[i]); };
235
+ const inField = (e.target as Element).matches('input');
221
236
  switch (e.key) {
222
237
  case 'ArrowDown': return moveTo(stepIndex(at, 1, opts.length));
223
238
  case 'ArrowUp': return moveTo(stepIndex(at, -1, opts.length));
@@ -225,7 +240,7 @@ export class Menus {
225
240
  case 'End': return inField ? undefined : moveTo(opts.length - 1);
226
241
  case 'Enter':
227
242
  e.preventDefault();
228
- if (at >= 0) this._pick(name, opts[at].dataset.value);
243
+ if (at >= 0) this._pick(name, opts[at].dataset.value!);
229
244
  return undefined;
230
245
  case 'Escape':
231
246
  e.preventDefault();
@@ -238,9 +253,9 @@ export class Menus {
238
253
 
239
254
  /**
240
255
  * A value was chosen: close, then report it.
241
- * @private
256
+ * @internal
242
257
  */
243
- _pick(name, value) {
258
+ _pick(name: string, value: string): void {
244
259
  this.close(true);
245
260
  this.onPick(name, value);
246
261
  }
@@ -6,6 +6,7 @@
6
6
  */
7
7
 
8
8
  import {normalizeSound} from '../data/sounds.js';
9
+ import type {Sound} from '../types.js';
9
10
 
10
11
  /** A list's row elements, in DOM order. */
11
12
  const ROW = ':scope > [data-ws-index]';
@@ -16,13 +17,12 @@ const ROW = ':scope > [data-ws-index]';
16
17
  * data is unusable (no url) is removed — so a row missing from the markup
17
18
  * can't leave a hole that would misalign rows and sounds.
18
19
  *
19
- * @param {HTMLElement} list - The `[data-ws-list]` element.
20
- * @returns {import('../../../index').Sound[]}
20
+ * @param list - The `[data-ws-list]` element.
21
21
  */
22
- export function readRows(list) {
23
- const rows = [...list.querySelectorAll(ROW)]
22
+ export function readRows(list: HTMLElement): Sound[] {
23
+ const rows = [...list.querySelectorAll<HTMLElement>(ROW)]
24
24
  .sort((a, b) => Number(a.dataset.wsIndex) - Number(b.dataset.wsIndex));
25
- const sounds = [];
25
+ const sounds: Sound[] = [];
26
26
  for (const row of rows) {
27
27
  const d = row.dataset;
28
28
  const sound = normalizeSound({
@@ -40,12 +40,11 @@ export function readRows(list) {
40
40
  * The row elements, indexed by the sound each one shows (whatever order
41
41
  * they're displayed in).
42
42
  *
43
- * @param {HTMLElement} list
44
- * @returns {HTMLElement[]}
43
+ * @param list
45
44
  */
46
- export function indexRows(list) {
47
- const rows = [];
48
- list.querySelectorAll(ROW).forEach((row) => { rows[Number(row.dataset.wsIndex)] = row; });
45
+ export function indexRows(list: HTMLElement): HTMLElement[] {
46
+ const rows: HTMLElement[] = [];
47
+ list.querySelectorAll<HTMLElement>(ROW).forEach((row) => { rows[Number(row.dataset.wsIndex)] = row; });
49
48
  return rows;
50
49
  }
51
50
 
@@ -53,21 +52,20 @@ export function indexRows(list) {
53
52
  * The rows currently visible (not hidden by the filter or the page), in
54
53
  * display order.
55
54
  *
56
- * @param {HTMLElement} list
57
- * @returns {HTMLElement[]}
55
+ * @param list
58
56
  */
59
- export function visibleRows(list) {
60
- return [...list.querySelectorAll(ROW)].filter((r) => !r.hidden);
57
+ export function visibleRows(list: HTMLElement): HTMLElement[] {
58
+ return [...list.querySelectorAll<HTMLElement>(ROW)].filter((r) => !r.hidden);
61
59
  }
62
60
 
63
61
  /**
64
62
  * Put the rows in the given order. Every row moves (hidden ones too), so
65
63
  * clearing a filter keeps the order.
66
64
  *
67
- * @param {HTMLElement} list
68
- * @param {HTMLElement[]} rows - In the order to show them.
65
+ * @param list
66
+ * @param rows - In the order to show them.
69
67
  */
70
- export function orderRows(list, rows) {
68
+ export function orderRows(list: HTMLElement, rows: HTMLElement[]) {
71
69
  const frag = document.createDocumentFragment();
72
70
  for (const row of rows) if (row) frag.appendChild(row);
73
71
  list.appendChild(frag);
@@ -0,0 +1,60 @@
1
+ /**
2
+ * @arraypress/waveform-sounds — public surface, without the import-time
3
+ * side effects: the auto-init scan and registering `<waveform-sounds>`
4
+ * (`index.js` adds those). Anything new belongs here.
5
+ *
6
+ * @module entry
7
+ */
8
+ import {WaveformSounds, DEFAULT_OPTIONS} from './core/WaveformSounds.js';
9
+ import {WaveformSoundsElement, defineWaveformSoundsElement} from './core/element.js';
10
+ import {
11
+ encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration,
12
+ } from './data/sounds.js';
13
+ import {renderSounds, renderSoundsElement, DEFAULT_STRINGS, RENDER_OPTION_KEYS, pickRenderOptions} from './render/markup.js';
14
+ import type {WaveformSoundsEventMap} from './types.js';
15
+
16
+ declare global {
17
+ interface Window {
18
+ /** The script-tag global, set when the bundle loads in a browser. */
19
+ WaveformSounds: typeof WaveformSounds;
20
+ }
21
+ interface HTMLElementEventMap extends WaveformSoundsEventMap {}
22
+ interface DocumentEventMap extends WaveformSoundsEventMap {}
23
+ interface WindowEventMap extends WaveformSoundsEventMap {}
24
+ }
25
+
26
+ WaveformSounds.utils = {encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration, renderSounds};
27
+ WaveformSounds.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
28
+ WaveformSounds.DEFAULT_STRINGS = DEFAULT_STRINGS;
29
+ // The element definer as a static too, so a CDN page that opted out of
30
+ // auto-init (no ES module import to reach the named export) can register
31
+ // the tag itself: `WaveformSounds.defineElement()`. Like the core's.
32
+ WaveformSounds.defineElement = defineWaveformSoundsElement;
33
+
34
+ // CDN / <script> usage: a global, like the rest of the family.
35
+ if (typeof window !== 'undefined') window.WaveformSounds = WaveformSounds;
36
+
37
+ export default WaveformSounds;
38
+ export {
39
+ WaveformSounds, DEFAULT_OPTIONS, DEFAULT_STRINGS,
40
+ encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration,
41
+ renderSounds, renderSoundsElement, RENDER_OPTION_KEYS, pickRenderOptions,
42
+ WaveformSoundsElement, defineWaveformSoundsElement,
43
+ };
44
+
45
+ // The public types (sounds, options, filter, events), for `import type { ... }`.
46
+ export type {
47
+ SoundInput,
48
+ Sound,
49
+ SoundsManifest,
50
+ SoundsFilter,
51
+ SoundsLoopFilter,
52
+ SoundsSort,
53
+ SoundsLayout,
54
+ SoundsFilterControl,
55
+ SoundsColumn,
56
+ WaveformSoundsStrings,
57
+ WaveformSoundsOptions,
58
+ WaveformSoundsEventMap,
59
+ WaveformSoundsInstanceEventMap,
60
+ } from './types.js';
@@ -2,20 +2,24 @@
2
2
  * @arraypress/waveform-sounds
3
3
  * A searchable, filterable list of sounds for WaveformPlayer.
4
4
  *
5
- * Importing this entry initialises every `[data-waveform-sounds]` element
6
- * once the DOM is ready. Opt out page-wide with
5
+ * Importing this entry registers `<waveform-sounds>` and initialises every
6
+ * `[data-waveform-sounds]` element once the DOM is ready. Opt out page-wide with
7
7
  * `<html data-waveform-autoinit="false">` (the family's switch), or import
8
8
  * `@arraypress/waveform-sounds/no-autoinit`.
9
9
  *
10
10
  * @author ArrayPress
11
11
  * @license MIT
12
12
  */
13
- import WaveformSounds from './entry.js';
13
+ import WaveformSounds, {defineWaveformSoundsElement} from './entry.js';
14
14
 
15
15
  export * from './entry.js';
16
16
  export default WaveformSounds;
17
17
 
18
18
  if (typeof document !== 'undefined' && document.documentElement?.dataset?.waveformAutoinit !== 'false') {
19
+ // The tag first: an element that upgrades now builds its own list, and
20
+ // the scan then skips it as already claimed. Behind the same opt-out (an
21
+ // opted-out page can call WaveformSounds.defineElement()).
22
+ defineWaveformSoundsElement();
19
23
  if (document.readyState === 'loading') {
20
24
  document.addEventListener('DOMContentLoaded', () => WaveformSounds.init(), {once: true});
21
25
  } else {
@@ -12,26 +12,31 @@
12
12
 
13
13
  import {escapeHtml} from '@arraypress/text';
14
14
 
15
+ /** An element's attributes: `true` writes a bare one, `false`/null/undefined leave it out. */
16
+ export type HtmlAttrs = Record<string, string | number | boolean | null | undefined>;
17
+
18
+ /** A child: an HTML string, a falsy one (skipped), or a nested list. */
19
+ export type HtmlChild = string | false | null | undefined | HtmlChild[];
20
+
15
21
  /** Elements with no closing tag. */
16
22
  const VOID = new Set(['input', 'br', 'img']);
17
23
 
18
24
  /**
19
25
  * Escape text for use as a child.
20
26
  *
21
- * @param {unknown} value
22
- * @returns {string}
27
+ * @param value
23
28
  */
24
- export function text(value) {
29
+ export function text(value: unknown): string {
25
30
  return escapeHtml(value ?? '');
26
31
  }
27
32
 
28
33
  /**
29
34
  * Serialise attributes, in the order given.
30
35
  *
31
- * @param {Record<string, string|number|boolean|null|undefined>} map
32
- * @returns {string} e.g. ` class="ws-row" hidden` (leading space included).
36
+ * @param map
37
+ * @returns e.g. ` class="ws-row" hidden` (leading space included).
33
38
  */
34
- export function attrs(map = {}) {
39
+ export function attrs(map: HtmlAttrs = {}): string {
35
40
  let out = '';
36
41
  for (const [name, value] of Object.entries(map)) {
37
42
  if (value === true) out += ` ${name}`;
@@ -43,13 +48,12 @@ export function attrs(map = {}) {
43
48
  /**
44
49
  * Build an element.
45
50
  *
46
- * @param {string} tag
47
- * @param {Record<string, string|number|boolean|null|undefined>} [attributes]
48
- * @param {...(string|false|null|undefined|Array)} children - HTML strings; falsy ones and nested arrays are flattened away.
49
- * @returns {string}
51
+ * @param tag
52
+ * @param attributes
53
+ * @param children - HTML strings; falsy ones and nested arrays are flattened away.
50
54
  */
51
- export function h(tag, attributes = {}, ...children) {
55
+ export function h(tag: string, attributes: HtmlAttrs = {}, ...children: HtmlChild[]): string {
52
56
  const open = `<${tag}${attrs(attributes)}>`;
53
57
  if (VOID.has(tag)) return open;
54
- return open + children.flat(Infinity).filter((c) => c != null && c !== false && c !== '').join('') + `</${tag}>`;
58
+ return open + (children as any[]).flat(Infinity).filter((c) => c != null && c !== false && c !== '').join('') + `</${tag}>`;
55
59
  }
@@ -9,11 +9,10 @@
9
9
  /**
10
10
  * One icon.
11
11
  *
12
- * @param {string} path - The SVG path data.
13
- * @param {string} [extraClass] - Classes beyond `ws-icon`.
14
- * @returns {string}
12
+ * @param path - The SVG path data.
13
+ * @param extraClass - Classes beyond `ws-icon`.
15
14
  */
16
- function icon(path, extraClass = '') {
15
+ function icon(path: string, extraClass: string = ''): string {
17
16
  const cls = extraClass ? `ws-icon ${extraClass}` : 'ws-icon';
18
17
  return `<svg class="${cls}" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="${path}"/></svg>`;
19
18
  }