@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
@@ -9,11 +9,11 @@
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`.
14
+ * @returns
15
15
  */
16
- function icon(path, extraClass = '') {
16
+ function icon(path: string, extraClass: string = ''): string {
17
17
  const cls = extraClass ? `ws-icon ${extraClass}` : 'ws-icon';
18
18
  return `<svg class="${cls}" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="${path}"/></svg>`;
19
19
  }
@@ -22,6 +22,7 @@ import {ICONS} from './icons.js';
22
22
  import {RENDER_DEFAULTS, resolveRenderOptions} from './options.js';
23
23
  import {bpmLabel, countText, DEFAULT_STRINGS, fill, SORT_LABEL_KEYS} from './strings.js';
24
24
  import {hashString} from '../shared/utils.js';
25
+ import type {Sound, SoundInput, SoundsSort, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
25
26
 
26
27
  export {escapeHtml, RENDER_DEFAULTS, resolveRenderOptions, DEFAULT_STRINGS, countText, fill, availableSorts};
27
28
 
@@ -30,10 +31,10 @@ export {escapeHtml, RENDER_DEFAULTS, resolveRenderOptions, DEFAULT_STRINGS, coun
30
31
  * the server and in the browser. Two lists of the SAME sounds on one page
31
32
  * collide, so they need an `idPrefix` each.
32
33
  *
33
- * @param {{url: string}[]} sounds
34
- * @returns {string} e.g. `ws1x9k2f`.
34
+ * @param sounds
35
+ * @returns e.g. `ws1x9k2f`.
35
36
  */
36
- export function idBase(sounds) {
37
+ export function idBase(sounds: {url: string}[]): string {
37
38
  const signature = [sounds.length, ...sounds.map((s) => s.url)].join('|');
38
39
  return `ws${hashString(signature).toString(36)}`;
39
40
  }
@@ -46,11 +47,11 @@ export function idBase(sounds) {
46
47
  * one usable order. Types past `maxTypeChips` become a menu (a
47
48
  * pack has a handful; a whole library can have fifty).
48
49
  *
49
- * @param {ReturnType<typeof facets>} f - The sounds' facets.
50
- * @param {ReturnType<typeof resolveRenderOptions>} o - Resolved options.
51
- * @returns {{types: 'chips'|'menu'|null, key: boolean, bpm: boolean, loops: boolean, sorts: string[], search: boolean, loop: boolean, count: boolean}}
50
+ * @param f - The sounds' facets.
51
+ * @param o - Resolved options.
52
+ * @returns
52
53
  */
53
- export function toolbarPlan(f, o) {
54
+ export function toolbarPlan(f: ReturnType<typeof facets>, o: ReturnType<typeof resolveRenderOptions>): {types: 'chips'|'menu'|null, key: boolean, bpm: boolean, loops: boolean, sorts: string[], search: boolean, loop: boolean, count: boolean} {
54
55
  const typed = o.filters.includes('type') && f.types.length > 1;
55
56
  const sorts = availableSorts(o.sorts, f);
56
57
  return {
@@ -70,18 +71,39 @@ export function toolbarPlan(f, o) {
70
71
  * unset, it's on exactly when the list marks loops (only those repeat, so
71
72
  * a one-shot still plays once).
72
73
  *
73
- * @param {boolean|null|undefined} loop - The `loop` option.
74
- * @param {{loops: number}} f - The sounds' facets.
75
- * @returns {boolean}
74
+ * @param loop - The `loop` option.
75
+ * @param f - The sounds' facets.
76
+ * @returns
76
77
  */
77
- export function loopsByDefault(loop, f) {
78
+ export function loopsByDefault(loop: boolean | null | undefined, f: {loops: number}): boolean {
78
79
  return loop == null ? f.loops > 0 : !!loop;
79
80
  }
80
81
 
82
+ /** What every part of the list's markup is built from ({@link renderSounds}). */
83
+ interface RenderContext {
84
+ o: ReturnType<typeof resolveRenderOptions>;
85
+ s: WaveformSoundsStrings;
86
+ f: ReturnType<typeof facets>;
87
+ total: number;
88
+ id: string;
89
+ }
90
+
91
+ /** A dropdown's content ({@link renderMenu}). */
92
+ export interface MenuSpec {
93
+ id: string;
94
+ label: string;
95
+ prefix?: string;
96
+ value: string;
97
+ options: {value: string, label: string, count?: number}[];
98
+ searchFrom: number;
99
+ placeholder?: string;
100
+ noMatches: string;
101
+ }
102
+
81
103
  /* ── Controls ───────────────────────────────────────────────────────── */
82
104
 
83
105
  /** The search field. */
84
- function renderSearch(s) {
106
+ function renderSearch(s: WaveformSoundsStrings): string {
85
107
  return h('label', {class: 'ws-search'},
86
108
  ICONS.search,
87
109
  h('span', {class: 'ws-sr'}, text(s.search)),
@@ -94,19 +116,19 @@ function renderSearch(s) {
94
116
  * has more than `searchFrom` options. The runtime (`menus.js`) opens,
95
117
  * filters and navigates it; without JS the button still shows the value.
96
118
  *
97
- * @param {string} name - 'type' | 'key' | 'sort' (the runtime routes by it).
98
- * @param {Object} m
99
- * @param {string} m.id - Id prefix for this list.
100
- * @param {string} m.label - Accessible name ("Type").
101
- * @param {string} [m.prefix] - Visible lead-in ("Sort by"); otherwise the label is screen-reader only.
102
- * @param {string} m.value - The selected value.
103
- * @param {{value: string, label: string, count?: number}[]} m.options
104
- * @param {number} m.searchFrom - Options above which a search field is added.
105
- * @param {string} [m.placeholder] - The search field's placeholder (no field without one).
106
- * @param {string} m.noMatches - Shown when the search matches nothing.
107
- * @returns {string}
119
+ * @param name - 'type' | 'key' | 'sort' (the runtime routes by it).
120
+ * @param m
121
+ * @param m.id - Id prefix for this list.
122
+ * @param m.label - Accessible name ("Type").
123
+ * @param [m.prefix] - Visible lead-in ("Sort by"); otherwise the label is screen-reader only.
124
+ * @param m.value - The selected value.
125
+ * @param m.options
126
+ * @param m.searchFrom - Options above which a search field is added.
127
+ * @param [m.placeholder] - The search field's placeholder (no field without one).
128
+ * @param m.noMatches - Shown when the search matches nothing.
129
+ * @returns
108
130
  */
109
- export function renderMenu(name, m) {
131
+ export function renderMenu(name: string, m: MenuSpec): string {
110
132
  const listId = `${m.id}-${name}-list`;
111
133
  const current = m.options.find((o) => o.value === m.value) ?? m.options[0];
112
134
  const searchable = m.placeholder && m.options.length > m.searchFrom;
@@ -145,15 +167,15 @@ export function renderMenu(name, m) {
145
167
  * range input (keyboard, screen readers and touch for free); the two share
146
168
  * one track. The runtime (`menus.js` + the core) wires it.
147
169
  *
148
- * @param {Object} m
149
- * @param {string} m.id - Id prefix for this list.
150
- * @param {typeof DEFAULT_STRINGS} m.s
151
- * @param {{min: number, max: number}} m.range - The pack's BPM range.
152
- * @returns {string}
170
+ * @param m
171
+ * @param m.id - Id prefix for this list.
172
+ * @param m.s
173
+ * @param m.range - The pack's BPM range.
174
+ * @returns
153
175
  */
154
- function renderBpmMenu({id, s, range}) {
176
+ function renderBpmMenu({id, s, range}: {id: string, s: WaveformSoundsStrings, range: {min: number, max: number}}): string {
155
177
  const popId = `${id}-bpm-pop`;
156
- const handle = (attr, label, value) => h('input', {
178
+ const handle = (attr: string, label: string, value: number) => h('input', {
157
179
  type: 'range', class: 'ws-range-input', [attr]: true, 'aria-label': label,
158
180
  min: range.min, max: range.max, step: '1', value,
159
181
  });
@@ -180,20 +202,20 @@ function renderBpmMenu({id, s, range}) {
180
202
  /**
181
203
  * Loops or one-shots: three buttons, one pressed ('' = both).
182
204
  */
183
- function renderLoopFilter(s) {
184
- const button = (value, label) => h('button', {type: 'button', class: 'ws-seg-btn', 'data-ws-loop-filter': value, 'aria-pressed': String(value === '')},
205
+ function renderLoopFilter(s: WaveformSoundsStrings): string {
206
+ const button = (value: string, label: string) => h('button', {type: 'button', class: 'ws-seg-btn', 'data-ws-loop-filter': value, 'aria-pressed': String(value === '')},
185
207
  h('span', {}, text(label)));
186
208
  return h('div', {class: 'ws-seg', role: 'group', 'aria-label': s.loopFilter},
187
209
  button('', s.all), button('loop', s.loops), button('one-shot', s.oneShots));
188
210
  }
189
211
 
190
212
  /** The Loop toggle, pressed or not. */
191
- function renderLoopToggle(s, pressed) {
213
+ function renderLoopToggle(s: WaveformSoundsStrings, pressed: boolean): string {
192
214
  return h('button', {type: 'button', class: 'ws-loop', 'data-ws-loop': true, 'aria-pressed': String(pressed)}, ICONS.loop, h('span', {}, text(s.loop)));
193
215
  }
194
216
 
195
217
  /** One type chip ('' = all). */
196
- function renderChip(value, label, count, pressed) {
218
+ function renderChip(value: string, label: string, count: number, pressed: boolean): string {
197
219
  return h('button', {type: 'button', class: 'ws-chip', 'data-ws-type': value, 'aria-pressed': String(pressed)},
198
220
  h('span', {class: 'ws-chip-label'}, text(label)), ' ', h('span', {class: 'ws-chip-count'}, text(count)));
199
221
  }
@@ -202,12 +224,12 @@ function renderChip(value, label, count, pressed) {
202
224
  * The toolbar: search, the controls row (type menu, key menu, BPM range,
203
225
  * loops or one-shots, sort menu, Loop) and the meta row (type chips + the count).
204
226
  *
205
- * @param {ReturnType<typeof toolbarPlan>} plan
206
- * @param {Object} ctx - `{o, s, f, total, id}` from {@link renderSounds}.
207
- * @returns {string}
227
+ * @param plan
228
+ * @param ctx - `{o, s, f, total, id}` from {@link renderSounds}.
229
+ * @returns
208
230
  */
209
- function renderToolbar(plan, {o, s, f, total, id}) {
210
- const menu = (name, m) => renderMenu(name, {id, searchFrom: o.menuSearch, noMatches: s.noMatches, ...m});
231
+ function renderToolbar(plan: ReturnType<typeof toolbarPlan>, {o, s, f, total, id}: RenderContext): string {
232
+ const menu = (name: string, m: Omit<MenuSpec, 'id' | 'searchFrom' | 'noMatches'>) => renderMenu(name, {id, searchFrom: o.menuSearch, noMatches: s.noMatches, ...m});
211
233
  const controls = [
212
234
  plan.types === 'menu' && menu('type', {
213
235
  label: s.types, value: '', placeholder: s.findType,
@@ -217,11 +239,11 @@ function renderToolbar(plan, {o, s, f, total, id}) {
217
239
  label: s.key, value: '', placeholder: s.findKey,
218
240
  options: [{value: '', label: s.anyKey}, ...f.keys.map((k) => ({value: k, label: k}))],
219
241
  }),
220
- plan.bpm && renderBpmMenu({id, s, range: f.bpm}),
242
+ plan.bpm && renderBpmMenu({id, s, range: f.bpm!}),
221
243
  plan.loops && renderLoopFilter(s),
222
244
  plan.sorts.length > 0 && menu('sort', {
223
245
  label: s.sort, prefix: s.sortBy, value: plan.sorts[0],
224
- options: plan.sorts.map((k) => ({value: k, label: s[SORT_LABEL_KEYS[k]]})),
246
+ options: plan.sorts.map((k) => ({value: k, label: s[SORT_LABEL_KEYS[k as SoundsSort]]})),
225
247
  }),
226
248
  plan.loop && renderLoopToggle(s, loopsByDefault(o.loop, f)),
227
249
  ].filter(Boolean);
@@ -243,7 +265,7 @@ function renderToolbar(plan, {o, s, f, total, id}) {
243
265
  /* ── Rows ───────────────────────────────────────────────────────────── */
244
266
 
245
267
  /** The cells a column shows for a sound. */
246
- const CELLS = {
268
+ const CELLS: Record<string, (sound: Sound) => string> = {
247
269
  type: (sound) => text(sound.type),
248
270
  bpm: (sound) => text(sound.bpm ?? ''),
249
271
  key: (sound) => text(sound.key),
@@ -256,13 +278,13 @@ const CELLS = {
256
278
  * sorted into. Every field is also written as a `data-*` attribute, so the
257
279
  * runtime can rebuild the sounds from server markup.
258
280
  *
259
- * @param {import('../../../index').Sound} sound - Normalised.
260
- * @param {number} index
261
- * @param {ReturnType<typeof resolveRenderOptions>} o
262
- * @param {boolean} [hidden] - Past the first page.
263
- * @returns {string}
281
+ * @param sound - Normalised.
282
+ * @param index
283
+ * @param o
284
+ * @param hidden - Past the first page.
285
+ * @returns
264
286
  */
265
- export function renderRow(sound, index, o, hidden = false) {
287
+ export function renderRow(sound: Sound, index: number, o: ReturnType<typeof resolveRenderOptions>, hidden: boolean = false): string {
266
288
  const s = o.strings;
267
289
  const vars = {title: sound.title};
268
290
  const cells = o.columns.map((c) => h('span', {class: `ws-cell ws-${c}`}, CELLS[c](sound)));
@@ -306,7 +328,7 @@ export function renderRow(sound, index, o, hidden = false) {
306
328
  * What follows the rows: the empty state, "Show more", the engine's slot
307
329
  * (visible only in the strip layout) and a live region for announcements.
308
330
  */
309
- function renderFooter({o, s, total}) {
331
+ function renderFooter({o, s, total}: RenderContext): string {
310
332
  const page = o.pageSize > 0 ? o.pageSize : total;
311
333
  const more = Math.max(0, total - page);
312
334
  const strip = o.player === 'strip';
@@ -322,14 +344,14 @@ function renderFooter({o, s, total}) {
322
344
  /**
323
345
  * The whole component's inner markup.
324
346
  *
325
- * @param {Object[]} sounds - Sounds (normalised or raw; normalised here).
326
- * @param {Object} [options] - Render options (see `WaveformSoundsOptions`).
327
- * @returns {string} HTML for the inside of `[data-waveform-sounds]`.
347
+ * @param sounds - Sounds (normalised or raw; normalised here).
348
+ * @param options - Render options (see `WaveformSoundsOptions`).
349
+ * @returns HTML for the inside of `[data-waveform-sounds]`.
328
350
  */
329
- export function renderSounds(sounds, options = {}) {
351
+ export function renderSounds(sounds: SoundInput[], options: WaveformSoundsOptions = {}): string {
330
352
  const o = resolveRenderOptions(options);
331
353
  const list = normalizeSounds(sounds);
332
- const ctx = {o, s: o.strings, f: facets(list), total: list.length, id: o.idPrefix || idBase(list)};
354
+ const ctx: RenderContext = {o, s: o.strings, f: facets(list), total: list.length, id: o.idPrefix || idBase(list)};
333
355
  const page = o.pageSize > 0 ? o.pageSize : Infinity;
334
356
  return renderToolbar(toolbarPlan(ctx.f, o), ctx)
335
357
  + h('ul', {class: `ws-list ws-list--${o.player}`, role: 'list', 'data-ws-list': true},
@@ -341,12 +363,12 @@ export function renderSounds(sounds, options = {}) {
341
363
  * The full element, for callers who want one string: the wrapper div with
342
364
  * its `data-waveform-sounds` marker, its `data-player` and the inner markup.
343
365
  *
344
- * @param {Object[]} sounds
345
- * @param {Object} [options]
346
- * @param {string} [className] - Extra classes for the wrapper.
347
- * @returns {string}
366
+ * @param sounds
367
+ * @param options
368
+ * @param className - Extra classes for the wrapper.
369
+ * @returns
348
370
  */
349
- export function renderSoundsElement(sounds, options = {}, className = '') {
371
+ export function renderSoundsElement(sounds: SoundInput[], options: WaveformSoundsOptions = {}, className: string = ''): string {
350
372
  const o = resolveRenderOptions(options);
351
373
  const cls = ['waveform-sounds', `waveform-sounds--${o.player}`, className].filter(Boolean).join(' ');
352
374
  return h('div', {class: cls, 'data-waveform-sounds': true, 'data-player': o.player}, renderSounds(sounds, options));
@@ -8,15 +8,17 @@
8
8
 
9
9
  import {SORTS} from '../data/sounds.js';
10
10
  import {DEFAULT_STRINGS} from './strings.js';
11
+ import type {SoundsColumn, SoundsFilterControl, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
11
12
 
12
13
  /** The filter controls a list can offer. */
13
- export const FILTERS = ['type', 'key', 'bpm', 'loop'];
14
+ export const FILTERS: SoundsFilterControl[] = ['type', 'key', 'bpm', 'loop'];
14
15
 
15
16
  /** The columns a row can show after its title. */
16
- export const COLUMNS = ['type', 'bpm', 'key', 'duration'];
17
+ export const COLUMNS: SoundsColumn[] = ['type', 'bpm', 'key', 'duration'];
17
18
 
18
19
  /** The options that shape the markup (the renderer's whole input). */
19
- export const RENDER_DEFAULTS = {
20
+ export const RENDER_DEFAULTS: Required<Pick<WaveformSoundsOptions,
21
+ 'player' | 'search' | 'filters' | 'sorts' | 'loopToggle' | 'showCount' | 'menuSearch' | 'pageSize' | 'columns' | 'maxTypeChips'>> = {
20
22
  player: 'inline',
21
23
  search: true,
22
24
  filters: [...FILTERS],
@@ -29,16 +31,20 @@ export const RENDER_DEFAULTS = {
29
31
  maxTypeChips: 10,
30
32
  };
31
33
 
34
+ /** {@link resolveRenderOptions}' result: the render options, complete, plus
35
+ * whatever else the caller passed. */
36
+ export type RenderOptions = typeof RENDER_DEFAULTS & {strings: WaveformSoundsStrings, idPrefix?: string, loop?: boolean | null};
37
+
32
38
  /**
33
39
  * The object without its `undefined` entries (so spreading it can't erase
34
40
  * a default).
35
41
  *
36
- * @param {Object|null|undefined} obj
37
- * @returns {Object}
42
+ * @param obj
43
+ * @returns
38
44
  */
39
- export function defined(obj) {
40
- const out = {};
41
- for (const k in obj ?? {}) if (obj[k] !== undefined) out[k] = obj[k];
45
+ export function defined(obj: Record<string, any> | null | undefined): Record<string, any> {
46
+ const out: Record<string, any> = {};
47
+ for (const k in obj ?? {}) if (obj![k] !== undefined) out[k] = obj![k];
42
48
  return out;
43
49
  }
44
50
 
@@ -46,23 +52,23 @@ export function defined(obj) {
46
52
  * The entries of `values` that are allowed, in the caller's order; the
47
53
  * fallback when `values` isn't a list.
48
54
  *
49
- * @param {unknown} values
50
- * @param {string[]} allowed
51
- * @param {string[]} fallback
52
- * @returns {string[]}
55
+ * @param values
56
+ * @param allowed
57
+ * @param fallback
58
+ * @returns
53
59
  */
54
- export function allowedList(values, allowed, fallback) {
60
+ export function allowedList<T extends string>(values: unknown, allowed: T[], fallback: T[]): T[] {
55
61
  return Array.isArray(values) ? values.filter((v) => allowed.includes(v)) : fallback;
56
62
  }
57
63
 
58
64
  /**
59
65
  * A whole number ≥ 0, or the fallback.
60
66
  *
61
- * @param {unknown} value
62
- * @param {number} fallback
63
- * @returns {number}
67
+ * @param value
68
+ * @param fallback
69
+ * @returns
64
70
  */
65
- export function wholeNumber(value, fallback) {
71
+ export function wholeNumber(value: unknown, fallback: number): number {
66
72
  const n = Number(value);
67
73
  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
68
74
  }
@@ -71,10 +77,10 @@ export function wholeNumber(value, fallback) {
71
77
  * The render options, defaulted and validated: unknown filters, sorts and
72
78
  * columns are dropped, counts are whole numbers, `strings` is complete.
73
79
  *
74
- * @param {Object} [options]
75
- * @returns {typeof RENDER_DEFAULTS & {strings: typeof DEFAULT_STRINGS, idPrefix?: string}}
80
+ * @param options
81
+ * @returns
76
82
  */
77
- export function resolveRenderOptions(options = {}) {
83
+ export function resolveRenderOptions(options: WaveformSoundsOptions = {}): RenderOptions {
78
84
  const o = {...RENDER_DEFAULTS, ...defined(options)};
79
85
  return {
80
86
  ...o,
@@ -7,9 +7,10 @@
7
7
  */
8
8
 
9
9
  import {bpmRangeFromFilter, hasBpmFilter} from '../data/bpm.js';
10
+ import type {SoundsSort, WaveformSoundsStrings} from '../types.js';
10
11
 
11
12
  /** The English defaults. */
12
- export const DEFAULT_STRINGS = {
13
+ export const DEFAULT_STRINGS: WaveformSoundsStrings = {
13
14
  search: 'Search sounds',
14
15
  searchPlaceholder: 'Search sounds…',
15
16
  all: 'All',
@@ -51,7 +52,7 @@ export const DEFAULT_STRINGS = {
51
52
  };
52
53
 
53
54
  /** The label each sort order shows in the Sort menu. */
54
- export const SORT_LABEL_KEYS = {
55
+ export const SORT_LABEL_KEYS: Record<SoundsSort, keyof WaveformSoundsStrings> = {
55
56
  default: 'sortDefault',
56
57
  title: 'sortTitle',
57
58
  bpm: 'sortBpm',
@@ -62,11 +63,11 @@ export const SORT_LABEL_KEYS = {
62
63
  /**
63
64
  * Fill `{name}` placeholders; unknown ones are left as written.
64
65
  *
65
- * @param {string} template
66
- * @param {Record<string, string|number>} [vars]
67
- * @returns {string}
66
+ * @param template
67
+ * @param vars
68
+ * @returns
68
69
  */
69
- export function fill(template, vars = {}) {
70
+ export function fill(template: string, vars: Record<string, string|number> = {}): string {
70
71
  return String(template).replace(/\{(\w+)\}/g, (match, name) => (name in vars ? String(vars[name]) : match));
71
72
  }
72
73
 
@@ -74,12 +75,12 @@ export function fill(template, vars = {}) {
74
75
  * The BPM menu's label: "Any BPM", or the range the handles hold
75
76
  * ("120–128 BPM"; an open end shows the pack's own end).
76
77
  *
77
- * @param {{bpmMin?: string|number, bpmMax?: string|number}} filter
78
- * @param {{min: number, max: number}} extent - The pack's BPM range.
79
- * @param {typeof DEFAULT_STRINGS} [strings]
80
- * @returns {string}
78
+ * @param filter
79
+ * @param extent - The pack's BPM range.
80
+ * @param strings
81
+ * @returns
81
82
  */
82
- export function bpmLabel(filter, extent, strings = DEFAULT_STRINGS) {
83
+ export function bpmLabel(filter: {bpmMin?: string|number, bpmMax?: string|number}, extent: {min: number, max: number}, strings: typeof DEFAULT_STRINGS = DEFAULT_STRINGS): string {
83
84
  if (!hasBpmFilter(filter)) return strings.anyBpm;
84
85
  const {lo, hi} = bpmRangeFromFilter(filter, extent);
85
86
  return fill(strings.bpmRange, {min: lo, max: hi});
@@ -88,12 +89,12 @@ export function bpmLabel(filter, extent, strings = DEFAULT_STRINGS) {
88
89
  /**
89
90
  * The count line: "300 sounds", "1 sound", "12 of 300 sounds".
90
91
  *
91
- * @param {number} shown - Sounds matching the filter.
92
- * @param {number} total - All sounds.
93
- * @param {typeof DEFAULT_STRINGS} [strings]
94
- * @returns {string}
92
+ * @param shown - Sounds matching the filter.
93
+ * @param total - All sounds.
94
+ * @param strings
95
+ * @returns
95
96
  */
96
- export function countText(shown, total, strings = DEFAULT_STRINGS) {
97
+ export function countText(shown: number, total: number, strings: typeof DEFAULT_STRINGS = DEFAULT_STRINGS): string {
97
98
  if (shown !== total) return fill(strings.countFiltered, {count: shown, total});
98
99
  return total === 1 ? strings.countOne : fill(strings.count, {count: total});
99
100
  }
@@ -4,3 +4,4 @@
4
4
  */
5
5
  export {renderSounds, renderSoundsElement, DEFAULT_STRINGS, escapeHtml} from './render/markup.js';
6
6
  export {normalizeSounds, parseManifest, encodePeaks, decodePeaks, normalizeKey, facets, formatDuration} from './data/sounds.js';
7
+ export type {SoundInput, Sound, SoundsManifest, WaveformSoundsOptions, WaveformSoundsStrings} from './types.js';
@@ -11,12 +11,12 @@ export const LOG = '[WaveformSounds]';
11
11
  /**
12
12
  * Clamp a number into a range.
13
13
  *
14
- * @param {number} value
15
- * @param {number} [min=0]
16
- * @param {number} [max=1]
17
- * @returns {number}
14
+ * @param value
15
+ * @param min
16
+ * @param max
17
+ * @returns
18
18
  */
19
- export function clamp(value, min = 0, max = 1) {
19
+ export function clamp(value: number, min: number = 0, max: number = 1): number {
20
20
  return Math.min(Math.max(value, min), max);
21
21
  }
22
22
 
@@ -24,11 +24,11 @@ export function clamp(value, min = 0, max = 1) {
24
24
  * Where a pointer sits across a box, as a fraction 0..1 — the seek
25
25
  * position of a click on a row waveform.
26
26
  *
27
- * @param {number} clientX - The pointer's x (viewport coordinates).
28
- * @param {{left: number, width: number}} rect - The box (getBoundingClientRect()).
29
- * @returns {number} 0..1; 0 for a box with no width.
27
+ * @param clientX - The pointer's x (viewport coordinates).
28
+ * @param rect - The box (getBoundingClientRect()).
29
+ * @returns 0..1; 0 for a box with no width.
30
30
  */
31
- export function pointerFraction(clientX, rect) {
31
+ export function pointerFraction(clientX: number, rect: {left: number, width: number}): number {
32
32
  return rect && rect.width ? clamp((clientX - rect.left) / rect.width) : 0;
33
33
  }
34
34
 
@@ -36,11 +36,11 @@ export function pointerFraction(clientX, rect) {
36
36
  * Is the element a place the user types into? Keyboard shortcuts (`/`)
37
37
  * must not fire there.
38
38
  *
39
- * @param {Element|null|undefined} el
40
- * @returns {boolean}
39
+ * @param el
40
+ * @returns
41
41
  */
42
- export function isTyping(el) {
43
- return !!el && (el.isContentEditable || /^(INPUT|SELECT|TEXTAREA)$/.test(el.tagName));
42
+ export function isTyping(el: Element | null | undefined): boolean {
43
+ return !!el && ((el as HTMLElement).isContentEditable || /^(INPUT|SELECT|TEXTAREA)$/.test(el.tagName));
44
44
  }
45
45
 
46
46
  /**
@@ -48,12 +48,12 @@ export function isTyping(el) {
48
48
  * Every event the list emits goes through here, so they share one shape:
49
49
  * the detail plus the instance that sent it.
50
50
  *
51
- * @param {EventTarget} target
52
- * @param {string} name - Without the prefix (`'play'`).
53
- * @param {Object} detail
54
- * @returns {CustomEvent} The event dispatched.
51
+ * @param target
52
+ * @param name - Without the prefix (`'play'`).
53
+ * @param detail
54
+ * @returns The event dispatched.
55
55
  */
56
- export function emit(target, name, detail) {
56
+ export function emit(target: EventTarget, name: string, detail: Record<string, any>): CustomEvent {
57
57
  const event = new CustomEvent(`waveformsounds:${name}`, {bubbles: true, detail});
58
58
  target.dispatchEvent(event);
59
59
  return event;
@@ -63,11 +63,11 @@ export function emit(target, name, detail) {
63
63
  * A small, stable string hash (djb2, 32-bit) — for ids that must come out
64
64
  * the same on the server and in the browser. Not cryptographic.
65
65
  *
66
- * @param {string} str
67
- * @returns {number} An unsigned 32-bit integer.
66
+ * @param str
67
+ * @returns An unsigned 32-bit integer.
68
68
  */
69
- export function hashString(str) {
69
+ export function hashString(str: string): number {
70
70
  let hash = 5381;
71
- for (const char of str) hash = (hash * 33 + char.codePointAt(0)) >>> 0;
71
+ for (const char of str) hash = (hash * 33 + char.codePointAt(0)!) >>> 0;
72
72
  return hash;
73
73
  }
@@ -1,11 +1,17 @@
1
1
  /**
2
- * @arraypress/waveform-sounds — hand-written types.
2
+ * The public data, option and event types of WaveformSounds. Moved here from
3
+ * the hand-written index.d.ts so the source uses the same definitions the
4
+ * published types are generated from.
3
5
  *
4
6
  * The four `waveform-sounds-*` wrappers derive their prop types from
5
- * `WaveformSoundsOptions` here. Add or rename an option in `src/js/core/options.js`
7
+ * `WaveformSoundsOptions` here. Add or rename an option in `core/options.ts`
6
8
  * (`DEFAULT_OPTIONS`) and in this file in the same change.
9
+ *
10
+ * @module types
7
11
  */
8
12
 
13
+ import type {WaveformSounds} from './core/WaveformSounds.js';
14
+
9
15
  /** One sound, as given (a manifest entry, a `sounds` item). */
10
16
  export interface SoundInput {
11
17
  /** Audio URL. Required. */
@@ -201,7 +207,10 @@ export interface WaveformSoundsOptions {
201
207
  arrowAudition?: boolean;
202
208
  /** Options for the engine `WaveformPlayer` (colours, height, … — and its
203
209
  * callbacks, which are called alongside the list's own). `audioMode` is
204
- * always `'self'`. As markup: `data-player-options` (JSON). */
210
+ * always `'self'`; `loop` and `showLoop` are always off (the list's Loop
211
+ * toggle owns looping); `duration`, `downloadUrl` and `downloadName` are
212
+ * ignored (each sound brings its own). As markup: `data-player-options`
213
+ * (JSON). */
205
214
  playerOptions?: Record<string, unknown> | null;
206
215
  /** The `WaveformPlayer` class, for ESM setups without the global. */
207
216
  playerClass?: unknown;
@@ -226,87 +235,3 @@ export interface WaveformSoundsEventMap {
226
235
  'waveformsounds:filter': CustomEvent<{visible: number; total: number; filter: SoundsFilter; sort: SoundsSort; instance: WaveformSounds}>;
227
236
  'waveformsounds:error': CustomEvent<{error: unknown; sound?: Sound; index?: number; instance: WaveformSounds}>;
228
237
  }
229
-
230
- export declare class WaveformSounds {
231
- constructor(container: HTMLElement | string, options?: WaveformSoundsOptions);
232
- readonly container: HTMLElement;
233
- readonly options: Required<WaveformSoundsOptions>;
234
- /** Resolves once the list is built (after a manifest fetch, if any).
235
- * The build always happens after the constructor returns, so listeners
236
- * attached straight after `new WaveformSounds()` see `ready`. It never
237
- * rejects: a failed build (e.g. the manifest 404s) resolves it too and
238
- * is reported through `onError` / `waveformsounds:error`. Calls made
239
- * before it resolves are honoured: `setFilter`/`setSort` show in the
240
- * controls once built, and `play()` waits for the list. */
241
- readonly ready: Promise<void>;
242
- readonly sounds: Sound[];
243
- readonly filter: SoundsFilter;
244
- readonly sortBy: SoundsSort;
245
- readonly playing: boolean;
246
- /** The engine `WaveformPlayer`, created on first play. */
247
- readonly engine: unknown;
248
- /** The sounds passing the filter, in sort order. */
249
- readonly visible: Sound[];
250
- /** The current (playing or paused) sound. */
251
- readonly current: Sound | null;
252
-
253
- play(target?: number | string | Sound, opts?: {at?: number}): void;
254
- pause(): void;
255
- toggle(target?: number | string | Sound): void;
256
- next(): void;
257
- previous(): void;
258
- setLoop(on: boolean): void;
259
- setFilter(patch: Partial<SoundsFilter>): void;
260
- clearFilters(): void;
261
- setSort(by: SoundsSort): void;
262
- showMore(): void;
263
- /** Tear down listeners, observers and the engine. Markup the instance
264
- * rendered is restored; ADOPTED server markup is left as it is (rows may
265
- * be re-sorted/hidden) — re-render it before building a new instance. */
266
- destroy(): void;
267
-
268
- static instances: Map<Element, WaveformSounds>;
269
- static init(root?: ParentNode): WaveformSounds[];
270
- static getInstance(el: Element | string): WaveformSounds | null;
271
- /** Destroy instances whose element has left the document. */
272
- static prune(): void;
273
- static DEFAULT_OPTIONS: WaveformSoundsOptions;
274
- static DEFAULT_STRINGS: WaveformSoundsStrings;
275
- static utils: {
276
- encodePeaks: typeof encodePeaks;
277
- decodePeaks: typeof decodePeaks;
278
- normalizeKey: typeof normalizeKey;
279
- normalizeSounds: typeof normalizeSounds;
280
- parseManifest: typeof parseManifest;
281
- facets: typeof facets;
282
- matches: typeof matches;
283
- sortSounds: typeof sortSounds;
284
- formatDuration: typeof formatDuration;
285
- renderSounds: typeof renderSounds;
286
- };
287
- }
288
-
289
- export declare const DEFAULT_OPTIONS: WaveformSoundsOptions;
290
- export declare const DEFAULT_STRINGS: WaveformSoundsStrings;
291
- export declare function encodePeaks(peaks: number[]): string;
292
- export declare function decodePeaks(value: string | number[] | null | undefined, scale?: number): number[] | null;
293
- export declare function normalizeKey(key: string | null | undefined): string;
294
- export declare function normalizeSounds(list: SoundInput[], peakScale?: number): Sound[];
295
- export declare function parseManifest(manifest: SoundsManifest | SoundInput[]): Sound[];
296
- export declare function facets(sounds: Sound[]): {types: {name: string; count: number}[]; keys: string[]; bpm: {min: number; max: number} | null; hasDuration: boolean; loops: number; oneShots: number};
297
- export declare function matches(sound: Sound, filter?: Partial<SoundsFilter>): boolean;
298
- export declare function sortSounds(sounds: Sound[], by?: SoundsSort): Sound[];
299
- export declare function formatDuration(seconds: number | null | undefined): string;
300
- /** The component's inner markup, for server rendering (also exported, DOM-free, from `@arraypress/waveform-sounds/render`). */
301
- export declare function renderSounds(sounds: SoundInput[], options?: WaveformSoundsOptions): string;
302
- /** The whole element (wrapper div included). */
303
- export declare function renderSoundsElement(sounds: SoundInput[], options?: WaveformSoundsOptions, className?: string): string;
304
-
305
- export default WaveformSounds;
306
-
307
- declare global {
308
- interface Window {
309
- WaveformSounds: typeof WaveformSounds;
310
- }
311
- interface HTMLElementEventMap extends WaveformSoundsEventMap {}
312
- }