@arraypress/waveform-sounds 0.3.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +19 -1
  3. package/dist/waveform-sounds-no-autoinit.esm.js +121 -97
  4. package/dist/waveform-sounds-render.esm.js +24 -10
  5. package/dist/waveform-sounds.css +62 -76
  6. package/dist/waveform-sounds.esm.js +122 -98
  7. package/dist/waveform-sounds.js +123 -98
  8. package/dist/waveform-sounds.min.css +1 -1
  9. package/dist/waveform-sounds.min.js +1 -1
  10. package/package.json +36 -33
  11. package/src/css/waveform-sounds.css +62 -76
  12. package/src/js/core/{WaveformSounds.js → WaveformSounds.ts} +301 -191
  13. package/src/js/core/engine.ts +101 -0
  14. package/src/js/core/{options.js → options.ts} +33 -28
  15. package/src/js/data/{bpm.js → bpm.ts} +17 -17
  16. package/src/js/data/{navigation.js → navigation.ts} +17 -17
  17. package/src/js/data/{sounds.js → sounds.ts} +62 -61
  18. package/src/js/data/{url-state.js → url-state.ts} +27 -26
  19. package/src/js/dom/{colors.js → colors.ts} +12 -12
  20. package/src/js/dom/{draw.js → draw.ts} +17 -17
  21. package/src/js/dom/{menus.js → menus.ts} +72 -55
  22. package/src/js/dom/{rows.js → rows.ts} +18 -17
  23. package/src/js/{entry.js → entry.ts} +25 -0
  24. package/src/js/render/{html.js → html.ts} +18 -12
  25. package/src/js/render/{icons.js → icons.ts} +4 -4
  26. package/src/js/render/{markup.js → markup.ts} +82 -60
  27. package/src/js/render/{options.js → options.ts} +26 -20
  28. package/src/js/render/{strings.js → strings.ts} +17 -16
  29. package/src/js/{render-entry.js → render-entry.ts} +1 -0
  30. package/src/js/shared/{utils.js → utils.ts} +22 -22
  31. package/{index.d.ts → src/js/types.ts} +12 -87
  32. package/types/core/WaveformSounds.d.ts +145 -0
  33. package/types/core/WaveformSounds.d.ts.map +1 -0
  34. package/types/core/engine.d.ts +67 -0
  35. package/types/core/engine.d.ts.map +1 -0
  36. package/types/core/options.d.ts +76 -0
  37. package/types/core/options.d.ts.map +1 -0
  38. package/types/data/bpm.d.ts +67 -0
  39. package/types/data/bpm.d.ts.map +1 -0
  40. package/types/data/navigation.d.ts +53 -0
  41. package/types/data/navigation.d.ts.map +1 -0
  42. package/types/data/sounds.d.ts +167 -0
  43. package/types/data/sounds.d.ts.map +1 -0
  44. package/types/data/url-state.d.ts +83 -0
  45. package/types/data/url-state.d.ts.map +1 -0
  46. package/types/dom/colors.d.ts +35 -0
  47. package/types/dom/colors.d.ts.map +1 -0
  48. package/types/dom/draw.d.ts +73 -0
  49. package/types/dom/draw.d.ts.map +1 -0
  50. package/types/dom/menus.d.ts +77 -0
  51. package/types/dom/menus.d.ts.map +1 -0
  52. package/types/dom/rows.d.ts +42 -0
  53. package/types/dom/rows.d.ts.map +1 -0
  54. package/types/entry.d.ts +22 -0
  55. package/types/entry.d.ts.map +1 -0
  56. package/types/index.d.ts +16 -0
  57. package/types/index.d.ts.map +1 -0
  58. package/types/render/html.d.ts +39 -0
  59. package/types/render/html.d.ts.map +1 -0
  60. package/types/render/icons.d.ts +17 -0
  61. package/types/render/icons.d.ts.map +1 -0
  62. package/types/render/markup.d.ts +132 -0
  63. package/types/render/markup.d.ts.map +1 -0
  64. package/types/render/options.d.ts +56 -0
  65. package/types/render/options.d.ts.map +1 -0
  66. package/types/render/strings.d.ts +46 -0
  67. package/types/render/strings.d.ts.map +1 -0
  68. package/types/render-entry.d.ts +8 -0
  69. package/types/render-entry.d.ts.map +1 -0
  70. package/types/shared/utils.d.ts +57 -0
  71. package/types/shared/utils.d.ts.map +1 -0
  72. package/types/types.d.ts +254 -0
  73. package/types/types.d.ts.map +1 -0
  74. package/types/vendor/arraypress-text.d.ts +250 -0
  75. package/dist/waveform-sounds-no-autoinit.cjs +0 -2159
  76. package/dist/waveform-sounds-render.cjs +0 -614
  77. package/dist/waveform-sounds.cjs +0 -2181
  78. package/no-autoinit.d.ts +0 -2
  79. package/render.d.ts +0 -5
  80. package/src/js/core/engine.js +0 -57
  81. /package/src/js/{index.js → index.ts} +0 -0
@@ -10,16 +10,17 @@
10
10
  */
11
11
 
12
12
  import {LOOP_FILTERS, normalizeKey} from './sounds.js';
13
+ import type {SoundsFilter, SoundsLoopFilter} from '../types.js';
13
14
 
14
15
  /**
15
16
  * The parameter names, or null when urlState is off. A string urlState
16
17
  * prefixes them (`'pack'` → `pack-q`, `pack-type`, …) so two lists on one
17
18
  * page don't share a filter.
18
19
  *
19
- * @param {boolean|string|null|undefined} urlState
20
- * @returns {{q: string, type: string, key: string, bpm: string, loop: string, sort: string}|null}
20
+ * @param urlState
21
+ * @returns
21
22
  */
22
- export function urlKeys(urlState) {
23
+ export function urlKeys(urlState: boolean | string | null | undefined): {q: string, type: string, key: string, bpm: string, loop: string, sort: string} | null {
23
24
  if (!urlState) return null;
24
25
  const p = typeof urlState === 'string' ? `${urlState}-` : '';
25
26
  return {q: `${p}q`, type: `${p}type`, key: `${p}key`, bpm: `${p}bpm`, loop: `${p}loop`, sort: `${p}sort`};
@@ -28,10 +29,10 @@ export function urlKeys(urlState) {
28
29
  /**
29
30
  * A BPM range parameter: "120-130", "120-" or "-130".
30
31
  *
31
- * @param {string|null|undefined} value
32
- * @returns {{bpmMin: string, bpmMax: string}|null} null if malformed.
32
+ * @param value
33
+ * @returns null if malformed.
33
34
  */
34
- export function parseBpmRange(value) {
35
+ export function parseBpmRange(value: string | null | undefined): {bpmMin: string, bpmMax: string} | null {
35
36
  const m = String(value ?? '').match(/^(\d*)-(\d*)$/);
36
37
  return m && (m[1] || m[2]) ? {bpmMin: m[1], bpmMax: m[2]} : null;
37
38
  }
@@ -39,11 +40,11 @@ export function parseBpmRange(value) {
39
40
  /**
40
41
  * The inverse of {@link parseBpmRange}; '' when neither end is set.
41
42
  *
42
- * @param {string|number|null|undefined} min
43
- * @param {string|number|null|undefined} max
44
- * @returns {string}
43
+ * @param min
44
+ * @param max
45
+ * @returns
45
46
  */
46
- export function formatBpmRange(min, max) {
47
+ export function formatBpmRange(min: string | number | null | undefined, max: string | number | null | undefined): string {
47
48
  const lo = min ?? '', hi = max ?? '';
48
49
  return lo !== '' || hi !== '' ? `${lo}-${hi}` : '';
49
50
  }
@@ -55,14 +56,14 @@ export function formatBpmRange(min, max) {
55
56
  * are ignored, never applied: a stale link shows the whole list, not an
56
57
  * empty one.
57
58
  *
58
- * @param {string} search - `location.search`.
59
- * @param {ReturnType<typeof urlKeys>} keys
60
- * @param {{types: {name: string}[], keys: string[], loops?: number, oneShots?: number}} available - From `facets()`.
61
- * @param {string[]} sorts - The sort orders offered.
62
- * @returns {{filter: Object, sort: string|null}} A filter patch, and the sort (or null).
59
+ * @param search - `location.search`.
60
+ * @param keys
61
+ * @param available - From `facets()`.
62
+ * @param sorts - The sort orders offered.
63
+ * @returns A filter patch, and the sort (or null).
63
64
  */
64
- export function readUrlState(search, keys, available, sorts) {
65
- const out = {filter: {}, sort: null};
65
+ export function readUrlState(search: string, keys: ReturnType<typeof urlKeys>, available: {types: {name: string}[], keys: string[], loops?: number, oneShots?: number}, sorts: string[]): {filter: Partial<SoundsFilter>, sort: string|null} {
66
+ const out: {filter: Partial<SoundsFilter>, sort: string | null} = {filter: {}, sort: null};
66
67
  if (!keys) return out;
67
68
  const sp = new URLSearchParams(search);
68
69
  const q = sp.get(keys.q);
@@ -74,7 +75,7 @@ export function readUrlState(search, keys, available, sorts) {
74
75
  const bpm = parseBpmRange(sp.get(keys.bpm));
75
76
  if (bpm) Object.assign(out.filter, bpm);
76
77
  const loop = sp.get(keys.loop);
77
- if (LOOP_FILTERS.includes(loop) && available.loops > 0 && available.oneShots > 0) out.filter.loop = loop;
78
+ if (LOOP_FILTERS.includes(loop!) && available.loops! > 0 && available.oneShots! > 0) out.filter.loop = loop as SoundsLoopFilter;
78
79
  const sort = sp.get(keys.sort);
79
80
  if (sort && sorts.includes(sort)) out.sort = sort;
80
81
  return out;
@@ -85,17 +86,17 @@ export function readUrlState(search, keys, available, sorts) {
85
86
  * are removed rather than written empty; every other parameter and the
86
87
  * hash are kept.
87
88
  *
88
- * @param {string} href - `location.href`.
89
- * @param {ReturnType<typeof urlKeys>} keys
90
- * @param {{query: string, type: string, key: string, bpmMin: string, bpmMax: string, loop?: string}} filter
91
- * @param {string} sort
92
- * @param {string} defaultSort - The starting order (not written).
93
- * @returns {string} The new href (equal to `href` when nothing changed).
89
+ * @param href - `location.href`.
90
+ * @param keys
91
+ * @param filter
92
+ * @param sort
93
+ * @param defaultSort - The starting order (not written).
94
+ * @returns The new href (equal to `href` when nothing changed).
94
95
  */
95
- export function writeUrlState(href, keys, filter, sort, defaultSort) {
96
+ export function writeUrlState(href: string, keys: ReturnType<typeof urlKeys>, filter: SoundsFilter, sort: string, defaultSort: string): string {
96
97
  if (!keys) return href;
97
98
  const url = new URL(href);
98
- const set = (name, v) => (v ? url.searchParams.set(name, v) : url.searchParams.delete(name));
99
+ const set = (name: string, v: string | undefined) => (v ? url.searchParams.set(name, v) : url.searchParams.delete(name));
99
100
  set(keys.q, String(filter.query ?? '').trim());
100
101
  set(keys.type, filter.type);
101
102
  set(keys.key, filter.key);
@@ -11,10 +11,10 @@
11
11
  * `rgb(1 2 3 / 50%)`, `oklab(… / 0.9)`, `transparent`. Opaque when no alpha
12
12
  * is written.
13
13
  *
14
- * @param {string|null|undefined} color
15
- * @returns {number} 0..1.
14
+ * @param color
15
+ * @returns 0..1.
16
16
  */
17
- export function parseAlpha(color) {
17
+ export function parseAlpha(color: string | null | undefined): number {
18
18
  const c = String(color ?? '').trim();
19
19
  if (!c || c === 'transparent') return 0;
20
20
  const slash = c.match(/\/\s*([\d.]+)(%?)\s*\)$/);
@@ -28,12 +28,12 @@ export function parseAlpha(color) {
28
28
  * The first (near-)opaque background at or above an element — the page
29
29
  * surface the list sits on. Crosses shadow-root boundaries.
30
30
  *
31
- * @param {Element} el
32
- * @param {number} [minAlpha=0.95] - How opaque counts as "the surface".
33
- * @returns {string} A computed colour, or `#fff` when nothing is painted.
31
+ * @param el
32
+ * @param minAlpha - How opaque counts as "the surface".
33
+ * @returns A computed colour, or `#fff` when nothing is painted.
34
34
  */
35
- export function pageSurface(el, minAlpha = 0.95) {
36
- for (let node = el; node && node.nodeType === 1; node = node.parentElement || node.getRootNode?.().host) {
35
+ export function pageSurface(el: Element, minAlpha: number = 0.95): string {
36
+ for (let node = el; node && node.nodeType === 1; node = node.parentElement || (node as any).getRootNode?.().host) {
37
37
  const bg = getComputedStyle(node).backgroundColor;
38
38
  if (parseAlpha(bg) > minAlpha) return bg;
39
39
  }
@@ -44,11 +44,11 @@ export function pageSurface(el, minAlpha = 0.95) {
44
44
  * Resolve any CSS colour (a `var()`, `color-mix()`, `currentColor`) to a
45
45
  * concrete value, as it would compute inside `container`.
46
46
  *
47
- * @param {Element} container
48
- * @param {string} value - A CSS colour expression.
49
- * @returns {string} The computed colour.
47
+ * @param container
48
+ * @param value - A CSS colour expression.
49
+ * @returns The computed colour.
50
50
  */
51
- export function resolveCssColor(container, value) {
51
+ export function resolveCssColor(container: Element, value: string): string {
52
52
  const probe = document.createElement('span');
53
53
  probe.style.cssText = 'position:absolute;width:0;height:0;overflow:hidden;visibility:hidden';
54
54
  probe.style.color = value;
@@ -13,9 +13,9 @@
13
13
  /**
14
14
  * Size a canvas to its box at the device pixel ratio. Returns the CSS size,
15
15
  * or null when the canvas has no box (hidden row, jsdom).
16
- * @param {HTMLCanvasElement} canvas
16
+ * @param canvas
17
17
  */
18
- export function fitCanvas(canvas) {
18
+ export function fitCanvas(canvas: HTMLCanvasElement) {
19
19
  const rect = canvas.getBoundingClientRect();
20
20
  if (!rect.width || !rect.height) return null;
21
21
  const dpr = Math.min(window.devicePixelRatio || 1, 3);
@@ -28,10 +28,10 @@ export function fitCanvas(canvas) {
28
28
  /**
29
29
  * Resample peaks to `count` bars (max of each bucket, so transients
30
30
  * survive the downsample).
31
- * @param {number[]} peaks
32
- * @param {number} count
31
+ * @param peaks
32
+ * @param count
33
33
  */
34
- export function resample(peaks, count) {
34
+ export function resample(peaks: number[], count: number) {
35
35
  if (!peaks?.length || count <= 0) return [];
36
36
  if (peaks.length === count) return peaks;
37
37
  const out = new Array(count);
@@ -54,13 +54,13 @@ export function resample(peaks, count) {
54
54
  * Bars are normalised to the loudest one, so a quiet one-shot isn't a
55
55
  * flat line, and never shorter than 4% of the height.
56
56
  *
57
- * @param {number[]} peaks - 0..1.
58
- * @param {number} width - Canvas width (CSS px).
59
- * @param {number} height - Canvas height (CSS px).
60
- * @param {{style: 'mirror'|'bars', barWidth: number, barGap: number}} o
61
- * @returns {{x: number, y: number, w: number, h: number}[]}
57
+ * @param peaks - 0..1.
58
+ * @param width - Canvas width (CSS px).
59
+ * @param height - Canvas height (CSS px).
60
+ * @param o
61
+ * @returns
62
62
  */
63
- export function barRects(peaks, width, height, o) {
63
+ export function barRects(peaks: number[], width: number, height: number, o: {style: 'mirror'|'bars', barWidth: number, barGap: number}): {x: number, y: number, w: number, h: number}[] {
64
64
  const step = o.barWidth + o.barGap;
65
65
  const bars = resample(peaks, Math.max(1, Math.floor((width + o.barGap) / step)));
66
66
  const max = bars.reduce((m, b) => (b > m ? b : m), 0);
@@ -84,16 +84,16 @@ export function barRects(peaks, width, height, o) {
84
84
  * loop across ~120 bars moved in ~15 jumps a second however fast it was
85
85
  * redrawn).
86
86
  *
87
- * @param {HTMLCanvasElement} canvas
88
- * @param {number[]|null} peaks - 0..1. Null draws a flat placeholder line.
89
- * @param {number} progress - 0..1 played.
90
- * @param {{style: 'mirror'|'bars', color: string, progressColor: string, barWidth: number, barGap: number}} o
87
+ * @param canvas
88
+ * @param peaks - 0..1. Null draws a flat placeholder line.
89
+ * @param progress - 0..1 played.
90
+ * @param o
91
91
  */
92
- export function drawRowWaveform(canvas, peaks, progress, o) {
92
+ export function drawRowWaveform(canvas: HTMLCanvasElement, peaks: number[] | null, progress: number, o: {style: 'mirror'|'bars', color: string, progressColor: string, barWidth: number, barGap: number}) {
93
93
  const size = fitCanvas(canvas);
94
94
  const ctx = size && canvas.getContext && canvas.getContext('2d');
95
95
  if (!ctx) return;
96
- const {width, height, dpr} = size;
96
+ const {width, height, dpr} = size!;
97
97
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
98
98
  ctx.clearRect(0, 0, width, height);
99
99
 
@@ -21,11 +21,11 @@ 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
26
+ * @returns
27
27
  */
28
- export function optionMatches(label, query) {
28
+ export function optionMatches(label: string, query: string): boolean {
29
29
  const q = fold(String(query ?? '')).trim();
30
30
  return !q || fold(String(label ?? '')).includes(q);
31
31
  }
@@ -33,48 +33,65 @@ export function optionMatches(label, query) {
33
33
  /**
34
34
  * Move an index by `delta`, clamped to `0..length-1`.
35
35
  *
36
- * @param {number} current - -1 when nothing is active.
37
- * @param {number} delta
38
- * @param {number} length
39
- * @returns {number}
36
+ * @param current - -1 when nothing is active.
37
+ * @param delta
38
+ * @param length
39
+ * @returns
40
40
  */
41
- export function stepIndex(current, delta, length) {
41
+ export function stepIndex(current: number, delta: number, length: number): number {
42
42
  return Math.max(0, Math.min(length - 1, current + delta));
43
43
  }
44
44
 
45
+ /** One dropdown's elements. A panel (the BPM range) has no list, search or none. */
46
+ interface MenuParts {
47
+ button: HTMLElement;
48
+ pop: HTMLElement;
49
+ search: HTMLInputElement | null;
50
+ list: HTMLElement | null;
51
+ none: HTMLElement | null;
52
+ value: HTMLElement | null;
53
+ }
54
+
45
55
  /** The parts of one dropdown. */
46
- function partsOf(menu) {
56
+ function partsOf(menu: HTMLElement): MenuParts {
47
57
  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]'),
58
+ button: menu.querySelector<HTMLElement>('[data-ws-menu-btn]')!,
59
+ pop: menu.querySelector<HTMLElement>('[data-ws-menu-pop]')!,
60
+ search: menu.querySelector<HTMLInputElement>('[data-ws-menu-search]'),
61
+ list: menu.querySelector<HTMLElement>('[data-ws-menu-list]'),
62
+ none: menu.querySelector<HTMLElement>('[data-ws-menu-none]'),
63
+ value: menu.querySelector<HTMLElement>('[data-ws-menu-value]'),
54
64
  };
55
65
  }
56
66
 
57
67
  /** 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');
68
+ const focusOwner = (p: MenuParts): HTMLElement | null => p.search || p.list || p.pop.querySelector('input') || p.pop.querySelector('button');
59
69
 
60
70
  /** 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);
71
+ const optionsOf = (p: MenuParts, visibleOnly = false): HTMLElement[] => [...p.list!.querySelectorAll<HTMLElement>('[role="option"]')].filter((o) => !visibleOnly || !o.hidden);
62
72
 
63
73
  /**
64
74
  * Every dropdown inside one list, with one shared "which is open" state.
65
75
  */
66
76
  export class Menus {
77
+ /** @internal */ declare container: HTMLElement;
78
+ /** @internal */ declare onPick: (name: string, value: string) => void;
79
+ /** Each menu's root element, by its `data-ws-menu` name. */
80
+ declare menus: Record<string, HTMLElement>;
81
+ /** The open menu's root element, if any. */
82
+ declare openMenu: HTMLElement | null;
83
+
67
84
  /**
68
85
  * @param {HTMLElement} container - The list's root element.
69
86
  * @param {Object} opts
70
87
  * @param {(name: string, value: string) => void} opts.onPick - A value was chosen.
71
88
  * @param {AbortSignal} opts.signal - Removes every listener on abort.
72
89
  */
73
- constructor(container, {onPick, signal}) {
90
+ constructor(container: HTMLElement, {onPick, signal}: {onPick: (name: string, value: string) => void, signal: AbortSignal}) {
74
91
  this.container = container;
75
92
  this.onPick = onPick;
76
93
  /** @type {Record<string, HTMLElement>} */
77
- this.menus = Object.fromEntries([...container.querySelectorAll('[data-ws-menu]')].map((m) => [m.dataset.wsMenu, m]));
94
+ this.menus = Object.fromEntries([...container.querySelectorAll<HTMLElement>('[data-ws-menu]')].map((m) => [m.dataset.wsMenu!, m]));
78
95
  /** @type {HTMLElement|null} */
79
96
  this.openMenu = null;
80
97
  this._bind(signal);
@@ -82,10 +99,10 @@ export class Menus {
82
99
 
83
100
  /**
84
101
  * Wire every menu, plus closing on an outside press or focus leaving.
85
- * @param {AbortSignal} signal
86
- * @private
102
+ * @param signal
103
+ * @internal
87
104
  */
88
- _bind(signal) {
105
+ _bind(signal: AbortSignal) {
89
106
  const sig = {signal};
90
107
  for (const [name, menu] of Object.entries(this.menus)) {
91
108
  const p = partsOf(menu);
@@ -104,19 +121,19 @@ export class Menus {
104
121
  continue;
105
122
  }
106
123
  p.list.addEventListener('click', (e) => {
107
- const opt = e.target.closest('[role="option"]');
108
- if (opt) this._pick(name, opt.dataset.value);
124
+ const opt = (e.target as Element).closest<HTMLElement>('[role="option"]');
125
+ if (opt) this._pick(name, opt.dataset.value!);
109
126
  }, sig);
110
127
  // Keep focus in the field while an option is pressed.
111
128
  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);
129
+ p.search?.addEventListener('input', () => this._filter(menu, p.search!.value), sig);
130
+ focusOwner(p)!.addEventListener('keydown', (e: KeyboardEvent) => this._onKey(e, name, menu), sig);
114
131
  }
115
132
  document.addEventListener('pointerdown', (e) => {
116
- if (this.openMenu && !this.openMenu.contains(e.target)) this.close(false);
133
+ if (this.openMenu && !this.openMenu.contains(e.target as Node)) this.close(false);
117
134
  }, sig);
118
135
  this.container.addEventListener('focusout', (e) => {
119
- if (this.openMenu && !this.openMenu.contains(e.relatedTarget)) this.close(false);
136
+ if (this.openMenu && !this.openMenu.contains(e.relatedTarget as Node | null)) this.close(false);
120
137
  }, sig);
121
138
  }
122
139
 
@@ -125,9 +142,9 @@ export class Menus {
125
142
  * focus in its search field or list. Flips to open over the end edge
126
143
  * when it would overflow the list.
127
144
  *
128
- * @param {HTMLElement} menu
145
+ * @param menu
129
146
  */
130
- open(menu) {
147
+ open(menu: HTMLElement) {
131
148
  if (this.openMenu && this.openMenu !== menu) this.close(false);
132
149
  const p = partsOf(menu);
133
150
  p.button.setAttribute('aria-expanded', 'true');
@@ -136,17 +153,17 @@ export class Menus {
136
153
  if (p.search) { p.search.value = ''; this._filter(menu, ''); }
137
154
  menu.classList.remove('ws-menu--end');
138
155
  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"]'));
156
+ if (p.list) this._activate(menu, p.list.querySelector<HTMLElement>('[role="option"][aria-selected="true"]'));
140
157
  focusOwner(p)?.focus();
141
158
  }
142
159
 
143
160
  /**
144
161
  * Close the open menu, if any.
145
162
  *
146
- * @param {boolean} focusButton - Return focus to its button (after a
163
+ * @param focusButton - Return focus to its button (after a
147
164
  * pick or Esc; not after a click elsewhere).
148
165
  */
149
- close(focusButton) {
166
+ close(focusButton: boolean) {
150
167
  const menu = this.openMenu;
151
168
  if (!menu) return;
152
169
  this.openMenu = null;
@@ -160,48 +177,48 @@ export class Menus {
160
177
  * Show `value` as a menu's choice (button text + `aria-selected`). Used
161
178
  * after a pick and when the filter is changed from code.
162
179
  *
163
- * @param {string} name - 'type' | 'key' | 'sort'.
164
- * @param {string} value
180
+ * @param name - 'type' | 'key' | 'sort'.
181
+ * @param value
165
182
  */
166
- setValue(name, value) {
183
+ setValue(name: string, value: string) {
167
184
  const menu = this.menus[name];
168
185
  if (!menu) return;
169
186
  const p = partsOf(menu);
170
187
  if (!p.list) return; // a panel shows its own value
171
- let label = null;
188
+ let label: string | null = null;
172
189
  for (const opt of optionsOf(p)) {
173
190
  const on = opt.dataset.value === String(value ?? '');
174
191
  opt.setAttribute('aria-selected', String(on));
175
192
  if (on) label = opt.querySelector('.ws-menu-text')?.textContent ?? '';
176
193
  }
177
- if (label !== null) p.value.textContent = label;
194
+ if (label !== null) p.value!.textContent = label;
178
195
  }
179
196
 
180
197
  /**
181
198
  * Narrow a menu to the options matching the search, and make the first
182
199
  * match active.
183
- * @private
200
+ * @internal
184
201
  */
185
- _filter(menu, query) {
202
+ _filter(menu: HTMLElement, query: string): void {
186
203
  const p = partsOf(menu);
187
- let first = null;
204
+ let first: HTMLElement | null = null;
188
205
  for (const opt of optionsOf(p)) {
189
206
  opt.hidden = !optionMatches(opt.textContent, query);
190
207
  if (!opt.hidden) first ??= opt;
191
208
  }
192
- p.none.hidden = first !== null;
209
+ p.none!.hidden = first !== null;
193
210
  this._activate(menu, first);
194
211
  }
195
212
 
196
213
  /**
197
214
  * Mark one option active (`aria-activedescendant`) and scroll it into
198
215
  * the list's view.
199
- * @private
216
+ * @internal
200
217
  */
201
- _activate(menu, opt) {
218
+ _activate(menu: HTMLElement, opt: HTMLElement | null | undefined): void {
202
219
  const p = partsOf(menu);
203
- for (const o of p.list.querySelectorAll('.is-active')) o.classList.remove('is-active');
204
- const owner = focusOwner(p);
220
+ for (const o of p.list!.querySelectorAll('.is-active')) o.classList.remove('is-active');
221
+ const owner = focusOwner(p)!;
205
222
  if (!opt || opt.hidden) { owner.removeAttribute('aria-activedescendant'); return; }
206
223
  opt.classList.add('is-active');
207
224
  owner.setAttribute('aria-activedescendant', opt.id);
@@ -210,14 +227,14 @@ export class Menus {
210
227
 
211
228
  /**
212
229
  * Keys inside an open menu.
213
- * @private
230
+ * @internal
214
231
  */
215
- _onKey(e, name, menu) {
232
+ _onKey(e: KeyboardEvent, name: string, menu: HTMLElement) {
216
233
  const p = partsOf(menu);
217
234
  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');
235
+ const at = opts.indexOf(p.list!.querySelector<HTMLElement>('.is-active')!);
236
+ const moveTo = (i: number) => { e.preventDefault(); this._activate(menu, opts[i]); };
237
+ const inField = (e.target as Element).matches('input');
221
238
  switch (e.key) {
222
239
  case 'ArrowDown': return moveTo(stepIndex(at, 1, opts.length));
223
240
  case 'ArrowUp': return moveTo(stepIndex(at, -1, opts.length));
@@ -225,7 +242,7 @@ export class Menus {
225
242
  case 'End': return inField ? undefined : moveTo(opts.length - 1);
226
243
  case 'Enter':
227
244
  e.preventDefault();
228
- if (at >= 0) this._pick(name, opts[at].dataset.value);
245
+ if (at >= 0) this._pick(name, opts[at].dataset.value!);
229
246
  return undefined;
230
247
  case 'Escape':
231
248
  e.preventDefault();
@@ -238,9 +255,9 @@ export class Menus {
238
255
 
239
256
  /**
240
257
  * A value was chosen: close, then report it.
241
- * @private
258
+ * @internal
242
259
  */
243
- _pick(name, value) {
260
+ _pick(name: string, value: string): void {
244
261
  this.close(true);
245
262
  this.onPick(name, value);
246
263
  }
@@ -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,13 @@ 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
+ * @returns
21
22
  */
22
- export function readRows(list) {
23
- const rows = [...list.querySelectorAll(ROW)]
23
+ export function readRows(list: HTMLElement): Sound[] {
24
+ const rows = [...list.querySelectorAll<HTMLElement>(ROW)]
24
25
  .sort((a, b) => Number(a.dataset.wsIndex) - Number(b.dataset.wsIndex));
25
- const sounds = [];
26
+ const sounds: Sound[] = [];
26
27
  for (const row of rows) {
27
28
  const d = row.dataset;
28
29
  const sound = normalizeSound({
@@ -40,12 +41,12 @@ export function readRows(list) {
40
41
  * The row elements, indexed by the sound each one shows (whatever order
41
42
  * they're displayed in).
42
43
  *
43
- * @param {HTMLElement} list
44
- * @returns {HTMLElement[]}
44
+ * @param list
45
+ * @returns
45
46
  */
46
- export function indexRows(list) {
47
- const rows = [];
48
- list.querySelectorAll(ROW).forEach((row) => { rows[Number(row.dataset.wsIndex)] = row; });
47
+ export function indexRows(list: HTMLElement): HTMLElement[] {
48
+ const rows: HTMLElement[] = [];
49
+ list.querySelectorAll<HTMLElement>(ROW).forEach((row) => { rows[Number(row.dataset.wsIndex)] = row; });
49
50
  return rows;
50
51
  }
51
52
 
@@ -53,21 +54,21 @@ export function indexRows(list) {
53
54
  * The rows currently visible (not hidden by the filter or the page), in
54
55
  * display order.
55
56
  *
56
- * @param {HTMLElement} list
57
- * @returns {HTMLElement[]}
57
+ * @param list
58
+ * @returns
58
59
  */
59
- export function visibleRows(list) {
60
- return [...list.querySelectorAll(ROW)].filter((r) => !r.hidden);
60
+ export function visibleRows(list: HTMLElement): HTMLElement[] {
61
+ return [...list.querySelectorAll<HTMLElement>(ROW)].filter((r) => !r.hidden);
61
62
  }
62
63
 
63
64
  /**
64
65
  * Put the rows in the given order. Every row moves (hidden ones too), so
65
66
  * clearing a filter keeps the order.
66
67
  *
67
- * @param {HTMLElement} list
68
- * @param {HTMLElement[]} rows - In the order to show them.
68
+ * @param list
69
+ * @param rows - In the order to show them.
69
70
  */
70
- export function orderRows(list, rows) {
71
+ export function orderRows(list: HTMLElement, rows: HTMLElement[]) {
71
72
  const frag = document.createDocumentFragment();
72
73
  for (const row of rows) if (row) frag.appendChild(row);
73
74
  list.appendChild(frag);
@@ -9,6 +9,15 @@ import {
9
9
  encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration,
10
10
  } from './data/sounds.js';
11
11
  import {renderSounds, renderSoundsElement, DEFAULT_STRINGS} from './render/markup.js';
12
+ import type {WaveformSoundsEventMap} from './types.js';
13
+
14
+ declare global {
15
+ interface Window {
16
+ /** The script-tag global, set when the bundle loads in a browser. */
17
+ WaveformSounds: typeof WaveformSounds;
18
+ }
19
+ interface HTMLElementEventMap extends WaveformSoundsEventMap {}
20
+ }
12
21
 
13
22
  WaveformSounds.utils = {encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration, renderSounds};
14
23
  WaveformSounds.DEFAULT_OPTIONS = DEFAULT_OPTIONS;
@@ -23,3 +32,19 @@ export {
23
32
  encodePeaks, decodePeaks, normalizeKey, normalizeSounds, parseManifest, facets, matches, sortSounds, formatDuration,
24
33
  renderSounds, renderSoundsElement,
25
34
  };
35
+
36
+ // The public types (sounds, options, filter, events), for `import type { ... }`.
37
+ export type {
38
+ SoundInput,
39
+ Sound,
40
+ SoundsManifest,
41
+ SoundsFilter,
42
+ SoundsLoopFilter,
43
+ SoundsSort,
44
+ SoundsLayout,
45
+ SoundsFilterControl,
46
+ SoundsColumn,
47
+ WaveformSoundsStrings,
48
+ WaveformSoundsOptions,
49
+ WaveformSoundsEventMap,
50
+ } from './types.js';
@@ -12,26 +12,32 @@
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
28
+ * @returns
23
29
  */
24
- export function text(value) {
30
+ export function text(value: unknown): string {
25
31
  return escapeHtml(value ?? '');
26
32
  }
27
33
 
28
34
  /**
29
35
  * Serialise attributes, in the order given.
30
36
  *
31
- * @param {Record<string, string|number|boolean|null|undefined>} map
32
- * @returns {string} e.g. ` class="ws-row" hidden` (leading space included).
37
+ * @param map
38
+ * @returns e.g. ` class="ws-row" hidden` (leading space included).
33
39
  */
34
- export function attrs(map = {}) {
40
+ export function attrs(map: HtmlAttrs = {}): string {
35
41
  let out = '';
36
42
  for (const [name, value] of Object.entries(map)) {
37
43
  if (value === true) out += ` ${name}`;
@@ -43,13 +49,13 @@ export function attrs(map = {}) {
43
49
  /**
44
50
  * Build an element.
45
51
  *
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}
52
+ * @param tag
53
+ * @param attributes
54
+ * @param children - HTML strings; falsy ones and nested arrays are flattened away.
55
+ * @returns
50
56
  */
51
- export function h(tag, attributes = {}, ...children) {
57
+ export function h(tag: string, attributes: HtmlAttrs = {}, ...children: HtmlChild[]): string {
52
58
  const open = `<${tag}${attrs(attributes)}>`;
53
59
  if (VOID.has(tag)) return open;
54
- return open + children.flat(Infinity).filter((c) => c != null && c !== false && c !== '').join('') + `</${tag}>`;
60
+ return open + (children as any[]).flat(Infinity).filter((c) => c != null && c !== false && c !== '').join('') + `</${tag}>`;
55
61
  }