@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.
- package/README.md +44 -2
- package/dist/waveform-sounds-no-autoinit.esm.js +914 -208
- package/dist/waveform-sounds-render.esm.js +274 -82
- package/dist/waveform-sounds.css +92 -17
- package/dist/waveform-sounds.esm.js +917 -210
- package/dist/waveform-sounds.js +913 -210
- package/dist/waveform-sounds.min.css +1 -1
- package/dist/waveform-sounds.min.js +3 -3
- package/package.json +1 -1
- package/src/css/waveform-sounds.css +92 -17
- package/src/js/core/WaveformSounds.ts +540 -120
- package/src/js/core/element.ts +208 -0
- package/src/js/core/engine.ts +9 -3
- package/src/js/core/options.ts +1 -5
- package/src/js/data/bpm.ts +14 -4
- package/src/js/data/keys.ts +156 -0
- package/src/js/data/navigation.ts +51 -11
- package/src/js/data/sounds.ts +73 -36
- package/src/js/data/url-state.ts +39 -12
- package/src/js/dom/colors.ts +28 -1
- package/src/js/dom/draw.ts +16 -3
- package/src/js/dom/menus.ts +2 -3
- package/src/js/dom/rows.ts +38 -15
- package/src/js/entry.ts +13 -3
- package/src/js/index.ts +7 -3
- package/src/js/render/html.ts +0 -2
- package/src/js/render/icons.ts +59 -17
- package/src/js/render/markup.ts +156 -62
- package/src/js/render/options.ts +29 -5
- package/src/js/render/strings.ts +57 -4
- package/src/js/render-entry.ts +1 -1
- package/src/js/shared/utils.ts +4 -4
- package/src/js/types.ts +54 -3
- package/types/core/WaveformSounds.d.ts +41 -11
- package/types/core/WaveformSounds.d.ts.map +1 -1
- package/types/core/element.d.ts +84 -0
- package/types/core/element.d.ts.map +1 -0
- package/types/core/engine.d.ts +8 -3
- package/types/core/engine.d.ts.map +1 -1
- package/types/core/options.d.ts +0 -5
- package/types/core/options.d.ts.map +1 -1
- package/types/data/bpm.d.ts +17 -4
- package/types/data/bpm.d.ts.map +1 -1
- package/types/data/keys.d.ts +88 -0
- package/types/data/keys.d.ts.map +1 -0
- package/types/data/navigation.d.ts +38 -11
- package/types/data/navigation.d.ts.map +1 -1
- package/types/data/sounds.d.ts +33 -17
- package/types/data/sounds.d.ts.map +1 -1
- package/types/data/url-state.d.ts +38 -7
- package/types/data/url-state.d.ts.map +1 -1
- package/types/dom/colors.d.ts +13 -0
- package/types/dom/colors.d.ts.map +1 -1
- package/types/dom/draw.d.ts +5 -3
- package/types/dom/draw.d.ts.map +1 -1
- package/types/dom/menus.d.ts +0 -2
- package/types/dom/menus.d.ts.map +1 -1
- package/types/dom/rows.d.ts +19 -11
- package/types/dom/rows.d.ts.map +1 -1
- package/types/entry.d.ts +10 -4
- package/types/entry.d.ts.map +1 -1
- package/types/index.d.ts +2 -2
- package/types/index.d.ts.map +1 -1
- package/types/render/html.d.ts +0 -2
- package/types/render/html.d.ts.map +1 -1
- package/types/render/icons.d.ts +41 -3
- package/types/render/icons.d.ts.map +1 -1
- package/types/render/markup.d.ts +44 -12
- package/types/render/markup.d.ts.map +1 -1
- package/types/render/options.d.ts +18 -5
- package/types/render/options.d.ts.map +1 -1
- package/types/render/strings.d.ts +22 -4
- package/types/render/strings.d.ts.map +1 -1
- package/types/render-entry.d.ts +1 -1
- package/types/render-entry.d.ts.map +1 -1
- package/types/shared/utils.d.ts +3 -3
- package/types/shared/utils.d.ts.map +1 -1
- package/types/types.d.ts +53 -3
- 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
|
+
}
|
package/src/js/core/engine.ts
CHANGED
|
@@ -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
|
-
* @
|
|
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;
|
package/src/js/core/options.ts
CHANGED
|
@@ -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> = {};
|
package/src/js/data/bpm.ts
CHANGED
|
@@ -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
|
|
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,
|
|
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
|
-
*
|
|
51
|
-
* "Show more" would reveal.
|
|
95
|
+
* The budget that renders position `pos` with paging off: whole chunks.
|
|
52
96
|
*
|
|
53
|
-
* @
|
|
54
|
-
* @param
|
|
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
|
|
59
|
-
|
|
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;
|