@arraypress/waveform-sounds 2.0.0 → 2.2.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 (79) hide show
  1. package/README.md +44 -2
  2. package/dist/waveform-sounds-no-autoinit.esm.js +914 -208
  3. package/dist/waveform-sounds-render.esm.js +274 -82
  4. package/dist/waveform-sounds.css +92 -17
  5. package/dist/waveform-sounds.esm.js +917 -210
  6. package/dist/waveform-sounds.js +913 -210
  7. package/dist/waveform-sounds.min.css +1 -1
  8. package/dist/waveform-sounds.min.js +3 -3
  9. package/package.json +1 -1
  10. package/src/css/waveform-sounds.css +92 -17
  11. package/src/js/core/WaveformSounds.ts +540 -120
  12. package/src/js/core/element.ts +208 -0
  13. package/src/js/core/engine.ts +9 -3
  14. package/src/js/core/options.ts +1 -5
  15. package/src/js/data/bpm.ts +14 -4
  16. package/src/js/data/keys.ts +156 -0
  17. package/src/js/data/navigation.ts +51 -11
  18. package/src/js/data/sounds.ts +73 -36
  19. package/src/js/data/url-state.ts +39 -12
  20. package/src/js/dom/colors.ts +28 -1
  21. package/src/js/dom/draw.ts +16 -3
  22. package/src/js/dom/menus.ts +2 -3
  23. package/src/js/dom/rows.ts +38 -15
  24. package/src/js/entry.ts +13 -3
  25. package/src/js/index.ts +7 -3
  26. package/src/js/render/html.ts +0 -2
  27. package/src/js/render/icons.ts +59 -17
  28. package/src/js/render/markup.ts +156 -62
  29. package/src/js/render/options.ts +29 -5
  30. package/src/js/render/strings.ts +57 -4
  31. package/src/js/render-entry.ts +1 -1
  32. package/src/js/shared/utils.ts +4 -4
  33. package/src/js/types.ts +54 -3
  34. package/types/core/WaveformSounds.d.ts +41 -11
  35. package/types/core/WaveformSounds.d.ts.map +1 -1
  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 +8 -3
  39. package/types/core/engine.d.ts.map +1 -1
  40. package/types/core/options.d.ts +0 -5
  41. package/types/core/options.d.ts.map +1 -1
  42. package/types/data/bpm.d.ts +17 -4
  43. package/types/data/bpm.d.ts.map +1 -1
  44. package/types/data/keys.d.ts +88 -0
  45. package/types/data/keys.d.ts.map +1 -0
  46. package/types/data/navigation.d.ts +38 -11
  47. package/types/data/navigation.d.ts.map +1 -1
  48. package/types/data/sounds.d.ts +33 -17
  49. package/types/data/sounds.d.ts.map +1 -1
  50. package/types/data/url-state.d.ts +38 -7
  51. package/types/data/url-state.d.ts.map +1 -1
  52. package/types/dom/colors.d.ts +13 -0
  53. package/types/dom/colors.d.ts.map +1 -1
  54. package/types/dom/draw.d.ts +5 -3
  55. package/types/dom/draw.d.ts.map +1 -1
  56. package/types/dom/menus.d.ts +0 -2
  57. package/types/dom/menus.d.ts.map +1 -1
  58. package/types/dom/rows.d.ts +19 -11
  59. package/types/dom/rows.d.ts.map +1 -1
  60. package/types/entry.d.ts +10 -4
  61. package/types/entry.d.ts.map +1 -1
  62. package/types/index.d.ts +2 -2
  63. package/types/index.d.ts.map +1 -1
  64. package/types/render/html.d.ts +0 -2
  65. package/types/render/html.d.ts.map +1 -1
  66. package/types/render/icons.d.ts +41 -3
  67. package/types/render/icons.d.ts.map +1 -1
  68. package/types/render/markup.d.ts +44 -12
  69. package/types/render/markup.d.ts.map +1 -1
  70. package/types/render/options.d.ts +18 -5
  71. package/types/render/options.d.ts.map +1 -1
  72. package/types/render/strings.d.ts +22 -4
  73. package/types/render/strings.d.ts.map +1 -1
  74. package/types/render-entry.d.ts +1 -1
  75. package/types/render-entry.d.ts.map +1 -1
  76. package/types/shared/utils.d.ts +3 -3
  77. package/types/shared/utils.d.ts.map +1 -1
  78. package/types/types.d.ts +53 -3
  79. package/types/types.d.ts.map +1 -1
@@ -0,0 +1,208 @@
1
+ /**
2
+ * The `<waveform-sounds>` custom element, modelled on the core's
3
+ * `<waveform-player>`.
4
+ *
5
+ * A light-DOM wrapper: the element itself is the list's container, so the
6
+ * stylesheet applies as it does to `[data-waveform-sounds]`, server-rendered
7
+ * markup inside it (`renderSounds()` output) is ADOPTED exactly as it is
8
+ * there, and `waveformsounds:*` events bubble from the tag. Configured by
9
+ * attributes — every `data-*` option the list reads, with or without the
10
+ * `data-` prefix (`manifest`, `page-size`, `player`, …), the unprefixed form
11
+ * winning.
12
+ *
13
+ * The default entry registers it (behind the same opt-out as the scan);
14
+ * `/no-autoinit` exports {@link defineWaveformSoundsElement}, and
15
+ * `WaveformSounds.defineElement()` reaches it from a `<script>` page.
16
+ *
17
+ * @module element
18
+ */
19
+
20
+ import {WaveformSounds} from './WaveformSounds.js';
21
+ import {readDataOptions} from './options.js';
22
+ import {LOG} from '../shared/utils.js';
23
+ import type {SoundInput} from '../types.js';
24
+
25
+ declare global {
26
+ interface HTMLElementTagNameMap {
27
+ 'waveform-sounds': WaveformSoundsElement;
28
+ }
29
+ }
30
+
31
+ /**
32
+ * Every `data-*` key `readDataOptions` reads, as its `dataset` name. The
33
+ * element accepts each as `data-<kebab>` and as plain `<kebab>`.
34
+ * `test/runtime/element.test.js` fails if this list and `readDataOptions`
35
+ * drift apart.
36
+ */
37
+ export const ELEMENT_OPTION_KEYS = [
38
+ 'player', 'manifest', 'search', 'filters', 'sorts', 'showCount', 'menuSearch', 'idPrefix', 'urlState',
39
+ 'loopToggle', 'pageSize', 'maxTypeChips', 'columns', 'waveformStyle', 'waveformColor', 'progressColor',
40
+ 'barWidth', 'barGap', 'loop', 'autoAdvance', 'arrowAudition', 'strings', 'playerOptions', 'mergeEnharmonicKeys',
41
+ ];
42
+
43
+ /**
44
+ * `pageSize` → `page-size`.
45
+ *
46
+ * @param key
47
+ */
48
+ const kebab = (key: string): string => key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
49
+
50
+ /**
51
+ * Read the element's options: each key from its plain attribute, else its
52
+ * `data-` one, through the same `readDataOptions` the `data-*` contract uses
53
+ * (so a bare boolean attribute — `<waveform-sounds auto-advance>` — is true,
54
+ * as `data-auto-advance` is).
55
+ *
56
+ * @param el
57
+ * @returns Sparse options.
58
+ */
59
+ export function readElementOptions(el: Element): Record<string, any> {
60
+ const dataset: Record<string, string> = {};
61
+ for (const key of ELEMENT_OPTION_KEYS) {
62
+ const name = kebab(key);
63
+ const value = el.getAttribute(name) ?? el.getAttribute(`data-${name}`);
64
+ if (value != null) dataset[key] = value;
65
+ }
66
+ return readDataOptions({dataset} as unknown as HTMLElement);
67
+ }
68
+
69
+ // Defined on any host: SSR and plain-Node imports have no HTMLElement, and
70
+ // this module must still evaluate there (the class is only ever constructed
71
+ // by a browser's customElements).
72
+ const Base = (typeof HTMLElement === 'undefined' ? class {} : HTMLElement) as typeof HTMLElement;
73
+
74
+ /**
75
+ * `<waveform-sounds manifest="/previews/sounds.json" page-size="20">`.
76
+ *
77
+ * - `connectedCallback` builds the list in the element (adopting
78
+ * server-rendered markup inside it); `disconnectedCallback` destroys it —
79
+ * putting adopted markup back as the server sent it — unless the element
80
+ * is put back before the current task ends (a move keeps the list, and
81
+ * its playback).
82
+ * - Changing an option attribute (either form) rebuilds the list once per
83
+ * task, from the sounds it holds (or from the new `manifest`).
84
+ * - {@link WaveformSoundsElement.sounds} is the `WaveformSounds` instance.
85
+ */
86
+ export class WaveformSoundsElement extends Base {
87
+ /** The list inside this element, or `null` while disconnected. */
88
+ declare sounds: WaveformSounds | null;
89
+ /** @internal A disconnection waiting to see whether the element comes back. */ declare _leaving: ReturnType<typeof setTimeout> | undefined;
90
+ /** @internal Attribute changes batched into one rebuild ('manifest': refetch). */ declare _pending: 'rebuild' | 'manifest' | undefined;
91
+
92
+ /** Every option attribute, plain and `data-` prefixed. */
93
+ static get observedAttributes(): string[] {
94
+ return ELEMENT_OPTION_KEYS.flatMap((key) => [kebab(key), `data-${kebab(key)}`]);
95
+ }
96
+
97
+ /** Build the list (or keep it, after a move). */
98
+ connectedCallback(): void {
99
+ if (this._leaving !== undefined) {
100
+ clearTimeout(this._leaving);
101
+ this._leaving = undefined;
102
+ return;
103
+ }
104
+ if (!this.sounds) this._build();
105
+ }
106
+
107
+ /** Destroy the list, unless the element comes straight back (a move). */
108
+ disconnectedCallback(): void {
109
+ clearTimeout(this._leaving);
110
+ this._leaving = setTimeout(() => {
111
+ this._leaving = undefined;
112
+ if (!this.isConnected) this._teardown();
113
+ }, 0);
114
+ }
115
+
116
+ /**
117
+ * An option attribute changed: rebuild once the task's changes are in.
118
+ *
119
+ * @param name
120
+ * @param previous
121
+ * @param value
122
+ */
123
+ attributeChangedCallback(name: string, previous: string | null, value: string | null): void {
124
+ // Before connection (and during the upgrade of parsed markup) the
125
+ // attributes are simply read by connectedCallback.
126
+ if (!this.sounds || previous === value) return;
127
+ const kind = name.replace(/^data-/, '') === 'manifest' ? 'manifest' : 'rebuild';
128
+ if (this._pending) {
129
+ if (kind === 'manifest') this._pending = kind;
130
+ return;
131
+ }
132
+ this._pending = kind;
133
+ queueMicrotask(() => {
134
+ const pending = this._pending;
135
+ this._pending = undefined;
136
+ if (this.sounds) this._rebuild(pending === 'manifest');
137
+ });
138
+ }
139
+
140
+ /**
141
+ * The options the list reads off this element (`WaveformSounds` calls it
142
+ * in place of reading `data-*` alone).
143
+ * @internal
144
+ */
145
+ _wsOptions(): Record<string, any> {
146
+ return readElementOptions(this);
147
+ }
148
+
149
+ /**
150
+ * Build the list into the element.
151
+ * @internal
152
+ */
153
+ _build(options: {sounds?: SoundInput[]} = {}): void {
154
+ // A declarative scan (`data-waveform-sounds` on this tag) or a script
155
+ // may have built a list here first; the element's own wins.
156
+ WaveformSounds.getInstance(this)?.destroy({restore: true});
157
+ try {
158
+ this.sounds = new WaveformSounds(this, options);
159
+ } catch (error) {
160
+ this.sounds = null;
161
+ console.error(`${LOG} Failed to initialise:`, error, this);
162
+ }
163
+ }
164
+
165
+ /**
166
+ * Destroy the list, putting server-rendered markup back as it came.
167
+ * @internal
168
+ */
169
+ _teardown(): void {
170
+ this.sounds?.destroy({restore: true});
171
+ this.sounds = null;
172
+ }
173
+
174
+ /**
175
+ * Rebuild for new options: re-rendered from the sounds the list holds
176
+ * (the markup must follow the new options), or fetched afresh when the
177
+ * manifest changed.
178
+ * @internal
179
+ */
180
+ _rebuild(refetch: boolean): void {
181
+ // Not built yet (its manifest still loading): there is nothing to
182
+ // keep, so it loads again.
183
+ const sounds = refetch || !this.sounds!.$ ? undefined : (this.sounds!.sounds as SoundInput[]).slice();
184
+ this._teardown();
185
+ this.innerHTML = '';
186
+ this._build(sounds ? {sounds} : {});
187
+ }
188
+ }
189
+
190
+ /**
191
+ * Register the `<waveform-sounds>` element (or the same element under
192
+ * another name). The default entry does this on import; `/no-autoinit`
193
+ * leaves it to you (`WaveformSounds.defineElement()` from a `<script>` page).
194
+ * A name that is already defined is left alone.
195
+ *
196
+ * @param name - Tag name; must contain a hyphen.
197
+ * @returns The registered constructor, or `undefined` outside a browser.
198
+ */
199
+ export function defineWaveformSoundsElement(name: string = 'waveform-sounds'): CustomElementConstructor | undefined {
200
+ if (typeof customElements === 'undefined') return undefined;
201
+ const existing = customElements.get(name);
202
+ if (existing) return existing;
203
+ // A constructor can only be registered once, so each name gets its own
204
+ // subclass (all of them `instanceof WaveformSoundsElement`).
205
+ const element = class extends WaveformSoundsElement {};
206
+ customElements.define(name, element);
207
+ return element;
208
+ }
@@ -67,7 +67,6 @@ export function engineOptions(user: Record<string, any> | null | undefined, layo
67
67
  *
68
68
  * @param sound
69
69
  * @param layout
70
- * @returns
71
70
  */
72
71
  export function enginePeaks(sound: {peaks: number[]|null, waveform: string|null}, layout: 'inline' | 'strip'): number[] | string | null {
73
72
  return (layout === 'strip' && sound.waveform) || sound.peaks || null;
@@ -79,6 +78,7 @@ export interface EngineTrack {
79
78
  autoplay: boolean;
80
79
  duration?: number;
81
80
  downloadUrl?: string;
81
+ preload?: string;
82
82
  }
83
83
 
84
84
  /**
@@ -88,13 +88,19 @@ export interface EngineTrack {
88
88
  * which with `preload: 'none'` is only once it plays — and its download
89
89
  * link, so a `showDownload` engine offers what the row offers.
90
90
  *
91
+ * `preload` is given every time because the core keeps the last one: the
92
+ * strip CUES its first sound with `'none'` (it shows the title, length and
93
+ * peaks from the data, and fetches nothing until it plays), and the next
94
+ * sound played must get the engine's own preload back.
95
+ *
91
96
  * @param sound
92
97
  * @param layout
93
98
  * @param autoplay - Start once loaded (false: cue only).
94
- * @returns
99
+ * @param preload - The media element's `preload` for this sound.
95
100
  */
96
- export function engineTrack(sound: {peaks: number[]|null, waveform: string|null, duration: number|null, download: string|null}, layout: 'inline' | 'strip', autoplay: boolean): EngineTrack {
101
+ export function engineTrack(sound: {peaks: number[]|null, waveform: string|null, duration: number|null, download: string|null}, layout: 'inline' | 'strip', autoplay: boolean, preload?: string): EngineTrack {
97
102
  const track: EngineTrack = {waveform: enginePeaks(sound, layout), autoplay};
103
+ if (preload) track.preload = preload;
98
104
  if (sound.duration != null && sound.duration > 0) track.duration = sound.duration;
99
105
  if (sound.download) track.downloadUrl = sound.download;
100
106
  return track;
@@ -63,7 +63,6 @@ export function parseBool(value: string | undefined): boolean | undefined {
63
63
  * is an empty list (e.g. `data-sorts=""` = no sort menu).
64
64
  *
65
65
  * @param value
66
- * @returns
67
66
  */
68
67
  export function parseList(value: string | undefined): string[] | undefined {
69
68
  if (value == null) return undefined;
@@ -74,7 +73,6 @@ export function parseList(value: string | undefined): string[] | undefined {
74
73
  * A number attribute; an empty string is "not set".
75
74
  *
76
75
  * @param value
77
- * @returns
78
76
  */
79
77
  export function parseNumber(value: string | undefined): number | undefined {
80
78
  return value === undefined || value === '' ? undefined : Number(value);
@@ -85,7 +83,6 @@ export function parseNumber(value: string | undefined): number | undefined {
85
83
  * the parameter prefix.
86
84
  *
87
85
  * @param value
88
- * @returns
89
86
  */
90
87
  export function parseUrlState(value: string | undefined): boolean | string | undefined {
91
88
  if (value === undefined) return undefined;
@@ -100,7 +97,6 @@ export function parseUrlState(value: string | undefined): boolean | string | und
100
97
  *
101
98
  * @param value
102
99
  * @param name - The attribute name, for the warning.
103
- * @returns
104
100
  */
105
101
  export function parseJson(value: string | undefined, name: string): Record<string, any> | undefined {
106
102
  if (!value) return undefined;
@@ -136,6 +132,7 @@ export function readDataOptions(el: HTMLElement): Record<string, any> {
136
132
  pageSize: parseNumber(d.pageSize),
137
133
  maxTypeChips: parseNumber(d.maxTypeChips),
138
134
  columns: parseList(d.columns),
135
+ mergeEnharmonicKeys: parseBool(d.mergeEnharmonicKeys),
139
136
  waveformStyle: d.waveformStyle || undefined,
140
137
  waveformColor: d.waveformColor || undefined,
141
138
  progressColor: d.progressColor || undefined,
@@ -156,7 +153,6 @@ export function readDataOptions(el: HTMLElement): Record<string, any> {
156
153
  * overwrite (an unset prop must not erase a default).
157
154
  *
158
155
  * @param sources
159
- * @returns
160
156
  */
161
157
  export function mergeOptions(...sources: (Record<string, any> | null | undefined)[]): Record<string, any> {
162
158
  const out: Record<string, any> = {};
@@ -10,12 +10,25 @@
10
10
  * @module bpm
11
11
  */
12
12
 
13
+ /**
14
+ * The range the slider spans: the pack's BPMs widened to whole numbers
15
+ * (the handles step by 1, so a pack whose fastest loop is 128.5 BPM needs
16
+ * an end at 129, or the top handle could never reach it). A pack of whole
17
+ * BPMs is unchanged.
18
+ *
19
+ * @param range - The pack's BPM range (`facets().bpm`).
20
+ * @returns The slider's ends, or null when the pack has no BPMs.
21
+ */
22
+ export function bpmExtent(range: {min: number, max: number} | null | undefined): {min: number, max: number} | null {
23
+ return range ? {min: Math.floor(range.min), max: Math.ceil(range.max)} : null;
24
+ }
25
+
13
26
  /**
14
27
  * The filter for a pair of handle positions.
15
28
  *
16
29
  * @param lo - The lower handle.
17
30
  * @param hi - The upper handle.
18
- * @param extent - The pack's BPM range (`facets().bpm`).
31
+ * @param extent - The slider's range ({@link bpmExtent}).
19
32
  * @returns `''` for an open end.
20
33
  */
21
34
  export function bpmFilterFromRange(lo: number, hi: number, extent: {min: number, max: number}): {bpmMin: string, bpmMax: string} {
@@ -33,7 +46,6 @@ export function bpmFilterFromRange(lo: number, hi: number, extent: {min: number,
33
46
  *
34
47
  * @param filter
35
48
  * @param extent
36
- * @returns
37
49
  */
38
50
  export function bpmRangeFromFilter(filter: {bpmMin?: string|number, bpmMax?: string|number}, extent: {min: number, max: number}): {lo: number, hi: number} {
39
51
  const read = (v: string | number | undefined, fallback: number): number => {
@@ -50,7 +62,6 @@ export function bpmRangeFromFilter(filter: {bpmMin?: string|number, bpmMax?: str
50
62
  *
51
63
  * @param value
52
64
  * @param extent
53
- * @returns
54
65
  */
55
66
  export function bpmFraction(value: number, extent: {min: number, max: number}): number {
56
67
  const span = extent.max - extent.min;
@@ -61,7 +72,6 @@ export function bpmFraction(value: number, extent: {min: number, max: number}):
61
72
  * Is a BPM limit set on either side?
62
73
  *
63
74
  * @param filter
64
- * @returns
65
75
  */
66
76
  export function hasBpmFilter(filter: {bpmMin?: string|number, bpmMax?: string|number}): boolean {
67
77
  return (filter.bpmMin != null && filter.bpmMin !== '') || (filter.bpmMax != null && filter.bpmMax !== '');
@@ -0,0 +1,156 @@
1
+ /**
2
+ * Musical keys beyond their spelling: which keys sound the same
3
+ * (enharmonics: A#m and Bbm), which spelling a merged filter entry shows,
4
+ * and how keys sort. Pure — shared by the renderer and the runtime.
5
+ *
6
+ * Keys arrive here already in the short form `normalizeKey()` writes
7
+ * (`'Fm'`, `'C#'`, `'Bb'`); anything else is a label to keep as given.
8
+ *
9
+ * @module keys
10
+ */
11
+
12
+ /** Pitch class of each root spelling, C = 0. The theoretical spellings
13
+ * (Cb, B#, E#, Fb) are here so they merge with the keys they sound as. */
14
+ export const KEY_PITCH: Record<string, number> = {
15
+ C: 0, 'B#': 0, 'C#': 1, Db: 1, D: 2, 'D#': 3, Eb: 3, E: 4, Fb: 4, 'E#': 5, F: 5, 'F#': 6, Gb: 6,
16
+ G: 7, 'G#': 8, Ab: 8, A: 9, 'A#': 10, Bb: 10, B: 11, Cb: 11,
17
+ };
18
+
19
+ /**
20
+ * The conventional spelling of each key: its key signature with the fewest
21
+ * accidentals (Db major has 5 flats, C# major 7 sharps), and for the two
22
+ * six-and-six ties the Camelot wheel's (F# major, Eb minor). Index = pitch
23
+ * class.
24
+ */
25
+ const CONVENTIONAL_MAJOR = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'F#', 'G', 'Ab', 'A', 'Bb', 'B'];
26
+ const CONVENTIONAL_MINOR = ['Cm', 'C#m', 'Dm', 'Ebm', 'Em', 'Fm', 'F#m', 'Gm', 'G#m', 'Am', 'Bbm', 'Bm'];
27
+
28
+ /** The sharp and flat spelling of each pitch class (for search). */
29
+ const SHARPS = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
30
+ const FLATS = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'];
31
+
32
+ /**
33
+ * A key's parts: its root spelling, pitch class and mode.
34
+ *
35
+ * @param key - A normalised key (`'A#m'`).
36
+ * @returns null for a label that isn't a key.
37
+ */
38
+ export function parseKey(key: string | null | undefined): {root: string, pitch: number, minor: boolean} | null {
39
+ const m = /^([A-G][#b]?)(m?)$/.exec(String(key ?? ''));
40
+ if (!m || KEY_PITCH[m[1]] === undefined) return null;
41
+ return {root: m[1], pitch: KEY_PITCH[m[1]], minor: m[2] === 'm'};
42
+ }
43
+
44
+ /**
45
+ * What a key sounds as: pitch class and mode (`'10m'` for A#m and Bbm).
46
+ * Two keys are enharmonic when their classes match.
47
+ *
48
+ * @param key - A normalised key.
49
+ * @returns The class, or the label itself when it isn't a key (so it only
50
+ * ever matches itself).
51
+ */
52
+ export function keyClass(key: string): string {
53
+ const k = parseKey(key);
54
+ return k ? `${k.pitch}${k.minor ? 'm' : ''}` : key;
55
+ }
56
+
57
+ /**
58
+ * Is a sound in key `b` (the filter's) when it is written `a`? The same
59
+ * spelling always is; with `merge`, so is any enharmonic one.
60
+ *
61
+ * @param a - The sound's key.
62
+ * @param b - The filter's key.
63
+ * @param merge - Treat enharmonic spellings as one key.
64
+ */
65
+ export function sameKey(a: string, b: string, merge: boolean = true): boolean {
66
+ return a === b || (merge && !!a && keyClass(a) === keyClass(b));
67
+ }
68
+
69
+ /**
70
+ * Sort rank of a key: by pitch from C, majors before minors; unknown
71
+ * labels after every key, no key at all last.
72
+ *
73
+ * @param key
74
+ */
75
+ export function keyRank(key: string): number {
76
+ if (!key) return Infinity;
77
+ const k = parseKey(key);
78
+ return k ? k.pitch * 2 + (k.minor ? 1 : 0) : 1000;
79
+ }
80
+
81
+ /**
82
+ * Every common spelling of a key (`'A#m'` → `['A#m', 'Bbm']`), for search:
83
+ * typing either finds both when keys are merged.
84
+ *
85
+ * @param key
86
+ */
87
+ export function enharmonics(key: string): string[] {
88
+ const k = parseKey(key);
89
+ if (!k) return key ? [key] : [];
90
+ const mode = k.minor ? 'm' : '';
91
+ return [...new Set([key, SHARPS[k.pitch] + mode, FLATS[k.pitch] + mode])];
92
+ }
93
+
94
+ /**
95
+ * The spelling a merged key entry shows: the one the pack uses most; a
96
+ * tie goes to the conventional spelling (see {@link CONVENTIONAL_MAJOR})
97
+ * when it is one of the tied, else to the first in alphabetical order.
98
+ *
99
+ * @param counts - Each spelling of ONE key, with how many sounds use it.
100
+ */
101
+ export function canonicalSpelling(counts: Map<string, number>): string {
102
+ let best = 0;
103
+ for (const n of counts.values()) if (n > best) best = n;
104
+ const tied = [...counts].filter(([, n]) => n === best).map(([k]) => k).sort();
105
+ if (tied.length === 1) return tied[0];
106
+ const k = parseKey(tied[0]);
107
+ const conventional = k ? (k.minor ? CONVENTIONAL_MINOR : CONVENTIONAL_MAJOR)[k.pitch] : '';
108
+ return tied.includes(conventional) ? conventional : tied[0];
109
+ }
110
+
111
+ /**
112
+ * The keys a list offers, merged or not: each entry once, in musical
113
+ * order, with the other spellings merged into it.
114
+ *
115
+ * @param keys - Every sound's key ('' for none), duplicates included.
116
+ * @param merge - Merge enharmonic spellings into one entry.
117
+ * @returns `keys` (the entries) and `aliases` (entry → the other spellings
118
+ * the list uses for it; only entries that have some).
119
+ */
120
+ export function keyEntries(keys: string[], merge: boolean = true): {keys: string[], aliases: Record<string, string[]>} {
121
+ const groups = new Map<string, Map<string, number>>();
122
+ for (const key of keys) {
123
+ if (!key) continue;
124
+ const cls = merge ? keyClass(key) : key;
125
+ const g = groups.get(cls) ?? new Map<string, number>();
126
+ groups.set(cls, g);
127
+ g.set(key, (g.get(key) || 0) + 1);
128
+ }
129
+ const out: string[] = [];
130
+ const aliases: Record<string, string[]> = {};
131
+ for (const g of groups.values()) {
132
+ const entry = canonicalSpelling(g);
133
+ out.push(entry);
134
+ const others = [...g.keys()].filter((k) => k !== entry).sort();
135
+ if (others.length) aliases[entry] = others;
136
+ }
137
+ out.sort((a, b) => keyRank(a) - keyRank(b) || a.localeCompare(b));
138
+ return {keys: out, aliases};
139
+ }
140
+
141
+ /**
142
+ * The entry of `entries` a key belongs to: itself, or with `merge` the
143
+ * entry it is enharmonic to (`?key=A#m` on a list whose entry is Bbm).
144
+ *
145
+ * @param key - A normalised key.
146
+ * @param entries - The list's key entries ({@link keyEntries}).
147
+ * @param merge
148
+ * @returns The entry, or '' when the list has no such key.
149
+ */
150
+ export function keyEntry(key: string, entries: string[], merge: boolean = true): string {
151
+ if (!key) return '';
152
+ if (entries.includes(key)) return key;
153
+ if (!merge) return '';
154
+ const cls = keyClass(key);
155
+ return entries.find((e) => keyClass(e) === cls) ?? '';
156
+ }
@@ -43,21 +43,62 @@ export function rowTarget(key: string, at: number, count: number): number | 'sea
43
43
  */
44
44
  export function seekTarget(progress: number, key: string): number | null {
45
45
  if (key !== 'ArrowRight' && key !== 'ArrowLeft') return null;
46
- return clamp(progress + (key === 'ArrowRight' ? SEEK_STEP : -SEEK_STEP), 0, 0.999);
46
+ return clamp(progress + (key === 'ArrowRight' ? SEEK_STEP : -SEEK_STEP), 0, SEEK_END);
47
+ }
48
+
49
+ /** Where End seeks on a slider: just short of the end, so it can't end
50
+ * the sound (and with it auto-advance) by accident. */
51
+ export const SEEK_END = 0.999;
52
+
53
+ /**
54
+ * The position Home / End seek to on a row's seek slider (the ARIA slider
55
+ * pattern: they go to the minimum / maximum, not to the first / last row).
56
+ *
57
+ * @param key - `KeyboardEvent.key`.
58
+ * @returns 0 for Home, {@link SEEK_END} for End, else null.
59
+ */
60
+ export function sliderEdgeTarget(key: string): number | null {
61
+ return key === 'Home' ? 0 : key === 'End' ? SEEK_END : null;
62
+ }
63
+
64
+ /**
65
+ * Rows are rendered as they are revealed, never all up front: a page's
66
+ * worth, or with paging off this many at a time, more as the list
67
+ * scrolls toward its end. Since 2.2.0.
68
+ */
69
+ export const RENDER_CHUNK = 50;
70
+
71
+ /**
72
+ * How many of the matching sounds have rows: the page, or with paging off
73
+ * the rows rendered so far (`budget`). The server renders the first of
74
+ * these ({@link firstRender}).
75
+ *
76
+ * @param matching - How many sounds match.
77
+ * @param limit - The page limit (Infinity when paging is off).
78
+ * @param budget - Rows rendered so far when paging is off.
79
+ */
80
+ export function renderedCount(matching: number, limit: number, budget: number): number {
81
+ return Math.min(matching, limit === Infinity ? budget : limit);
82
+ }
83
+
84
+ /**
85
+ * How many rows a list starts with: a page, or with paging off
86
+ * {@link RENDER_CHUNK}.
87
+ *
88
+ * @param pageSize - The `pageSize` option (0 = paging off).
89
+ */
90
+ export function firstRender(pageSize: number): number {
91
+ return pageSize > 0 ? pageSize : RENDER_CHUNK;
47
92
  }
48
93
 
49
94
  /**
50
- * Which of the matching sounds the current page shows, and how many more
51
- * "Show more" would reveal.
95
+ * The budget that renders position `pos` with paging off: whole chunks.
52
96
  *
53
- * @template T
54
- * @param shown - The sounds that match, in display order.
55
- * @param limit - How many to show (Infinity for all).
56
- * @returns
97
+ * @param budget - Rows rendered so far.
98
+ * @param pos - The position that must have a row.
57
99
  */
58
- export function pageWindow<T>(shown: T[], limit: number): {visible: Set<T>, remaining: number} {
59
- const visible = new Set(shown.slice(0, limit));
60
- return {visible, remaining: shown.length - visible.size};
100
+ export function budgetToReveal(budget: number, pos: number): number {
101
+ return pos < budget ? budget : Math.ceil((pos + 1) / RENDER_CHUNK) * RENDER_CHUNK;
61
102
  }
62
103
 
63
104
  /**
@@ -66,7 +107,6 @@ export function pageWindow<T>(shown: T[], limit: number): {visible: Set<T>, rema
66
107
  *
67
108
  * @param limit - The current limit.
68
109
  * @param pos - The position that must be visible.
69
- * @returns
70
110
  */
71
111
  export function limitToReveal(limit: number, pos: number): number {
72
112
  return pos >= limit ? pos + 1 : limit;