@arraypress/waveform-sounds 0.3.1 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +1 -1
- package/README.md +43 -3
- package/dist/waveform-sounds-no-autoinit.esm.js +607 -178
- package/dist/waveform-sounds-render.esm.js +79 -15
- package/dist/waveform-sounds.css +136 -79
- package/dist/waveform-sounds.esm.js +611 -181
- package/dist/waveform-sounds.js +608 -181
- package/dist/waveform-sounds.min.css +1 -1
- package/dist/waveform-sounds.min.js +3 -3
- package/package.json +36 -33
- package/src/css/waveform-sounds.css +136 -79
- package/src/js/core/WaveformSounds.ts +1366 -0
- package/src/js/core/element.ts +208 -0
- package/src/js/core/engine.ts +107 -0
- package/src/js/core/{options.js → options.ts} +28 -28
- package/src/js/data/{bpm.js → bpm.ts} +27 -17
- package/src/js/data/{navigation.js → navigation.ts} +31 -18
- package/src/js/data/{sounds.js → sounds.ts} +97 -66
- package/src/js/data/url-state.ts +130 -0
- package/src/js/dom/colors.ts +86 -0
- package/src/js/dom/{draw.js → draw.ts} +16 -17
- package/src/js/dom/{menus.js → menus.ts} +70 -55
- package/src/js/dom/{rows.js → rows.ts} +15 -17
- package/src/js/entry.ts +60 -0
- package/src/js/{index.js → index.ts} +7 -3
- package/src/js/render/{html.js → html.ts} +16 -12
- package/src/js/render/{icons.js → icons.ts} +3 -4
- package/src/js/render/{markup.js → markup.ts} +114 -64
- package/src/js/render/options.ts +118 -0
- package/src/js/render/{strings.js → strings.ts} +18 -16
- package/src/js/{render-entry.js → render-entry.ts} +2 -1
- package/src/js/shared/{utils.js → utils.ts} +24 -24
- package/{index.d.ts → src/js/types.ts} +40 -88
- package/types/core/WaveformSounds.d.ts +175 -0
- package/types/core/WaveformSounds.d.ts.map +1 -0
- package/types/core/element.d.ts +84 -0
- package/types/core/element.d.ts.map +1 -0
- package/types/core/engine.d.ts +72 -0
- package/types/core/engine.d.ts.map +1 -0
- package/types/core/options.d.ts +71 -0
- package/types/core/options.d.ts.map +1 -0
- package/types/data/bpm.d.ts +80 -0
- package/types/data/bpm.d.ts.map +1 -0
- package/types/data/navigation.d.ts +62 -0
- package/types/data/navigation.d.ts.map +1 -0
- package/types/data/sounds.d.ts +168 -0
- package/types/data/sounds.d.ts.map +1 -0
- package/types/data/url-state.d.ts +109 -0
- package/types/data/url-state.d.ts.map +1 -0
- package/types/dom/colors.d.ts +48 -0
- package/types/dom/colors.d.ts.map +1 -0
- package/types/dom/draw.d.ts +72 -0
- package/types/dom/draw.d.ts.map +1 -0
- package/types/dom/menus.d.ts +75 -0
- package/types/dom/menus.d.ts.map +1 -0
- package/types/dom/rows.d.ts +39 -0
- package/types/dom/rows.d.ts.map +1 -0
- package/types/entry.d.ts +28 -0
- package/types/entry.d.ts.map +1 -0
- package/types/index.d.ts +16 -0
- package/types/index.d.ts.map +1 -0
- package/types/render/html.d.ts +37 -0
- package/types/render/html.d.ts.map +1 -0
- package/types/render/icons.d.ts +17 -0
- package/types/render/icons.d.ts.map +1 -0
- package/types/render/markup.d.ts +141 -0
- package/types/render/markup.d.ts.map +1 -0
- package/types/render/options.d.ts +69 -0
- package/types/render/options.d.ts.map +1 -0
- package/types/render/strings.d.ts +43 -0
- package/types/render/strings.d.ts.map +1 -0
- package/types/render-entry.d.ts +8 -0
- package/types/render-entry.d.ts.map +1 -0
- package/types/shared/utils.d.ts +57 -0
- package/types/shared/utils.d.ts.map +1 -0
- package/types/types.d.ts +280 -0
- package/types/types.d.ts.map +1 -0
- package/types/vendor/arraypress-text.d.ts +250 -0
- package/dist/waveform-sounds-no-autoinit.cjs +0 -2159
- package/dist/waveform-sounds-render.cjs +0 -614
- package/dist/waveform-sounds.cjs +0 -2181
- package/no-autoinit.d.ts +0 -2
- package/render.d.ts +0 -5
- package/src/js/core/WaveformSounds.js +0 -993
- package/src/js/core/engine.js +0 -57
- package/src/js/data/url-state.js +0 -106
- package/src/js/dom/colors.js +0 -59
- package/src/js/entry.js +0 -25
- package/src/js/render/options.js +0 -90
|
@@ -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',
|
|
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
|
+
}
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The audio engine: ONE `WaveformPlayer` (self mode) that every sound in
|
|
3
|
+
* the list plays through. These helpers decide how it's configured and
|
|
4
|
+
* what it's given per sound; `WaveformSounds.js` owns its lifecycle.
|
|
5
|
+
*
|
|
6
|
+
* @module engine
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** The engine's own callbacks, which the list must always receive. */
|
|
10
|
+
const CALLBACKS = ['onLoad', 'onPlay', 'onPause', 'onEnd', 'onTimeUpdate', 'onError'];
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Player options that describe ONE track. The engine plays every sound in
|
|
14
|
+
* the list, so a site value would be wrong for all but one of them; the
|
|
15
|
+
* list passes each sound's own to `loadTrack()` instead (and the core resets
|
|
16
|
+
* them on every `loadTrack()` that doesn't).
|
|
17
|
+
*/
|
|
18
|
+
const PER_TRACK = ['duration', 'downloadUrl', 'downloadName'];
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* The engine player's options. The site's `playerOptions` override the
|
|
22
|
+
* defaults, except what the list depends on:
|
|
23
|
+
* - `audioMode` is always `'self'` (the list owns its audio);
|
|
24
|
+
* - `loop` and `showLoop` are always off: the list owns looping (its Loop
|
|
25
|
+
* toggle, which repeats only the sounds marked as loops). The player's
|
|
26
|
+
* own loop would stop `ended`, so `autoAdvance` and the row state would
|
|
27
|
+
* stall, and its toggle would loop one-shots behind the list's back;
|
|
28
|
+
* - the per-track options (`duration`, `downloadUrl`, `downloadName`) are
|
|
29
|
+
* dropped: each sound's come with it (see {@link engineTrack});
|
|
30
|
+
* - the six callbacks always reach the list — a site's own callback of
|
|
31
|
+
* the same name runs as well, after it, with the same arguments.
|
|
32
|
+
*
|
|
33
|
+
* @param user - The site's `playerOptions`.
|
|
34
|
+
* @param layout - Strip shows the engine, so it's taller.
|
|
35
|
+
* @param handlers - The list's callbacks, keyed by
|
|
36
|
+
* option name (`onPlay`, …).
|
|
37
|
+
* @returns Options for `new WaveformPlayer(el, options)`.
|
|
38
|
+
*/
|
|
39
|
+
export function engineOptions(user: Record<string, any> | null | undefined, layout: 'inline' | 'strip', handlers: Record<string, (...args: any[]) => void>): Record<string, any> {
|
|
40
|
+
const site = user || {};
|
|
41
|
+
const strip = layout === 'strip';
|
|
42
|
+
const options: Record<string, any> = {
|
|
43
|
+
height: strip ? 48 : 32,
|
|
44
|
+
waveformStyle: strip ? 'mirror' : 'bars',
|
|
45
|
+
preload: 'metadata',
|
|
46
|
+
singlePlay: true,
|
|
47
|
+
...site,
|
|
48
|
+
audioMode: 'self',
|
|
49
|
+
loop: false,
|
|
50
|
+
showLoop: false,
|
|
51
|
+
};
|
|
52
|
+
for (const name of PER_TRACK) delete options[name];
|
|
53
|
+
for (const name of CALLBACKS) {
|
|
54
|
+
options[name] = (...args: any[]) => {
|
|
55
|
+
handlers[name]?.(...args);
|
|
56
|
+
if (typeof site[name] === 'function') site[name](...args);
|
|
57
|
+
};
|
|
58
|
+
}
|
|
59
|
+
return options;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The waveform data to hand the engine for a sound: in the strip a
|
|
64
|
+
* full-resolution sidecar when there is one, otherwise the row's peaks.
|
|
65
|
+
* Supplied peaks also stop a hidden engine from downloading and decoding
|
|
66
|
+
* the whole file just to draw it.
|
|
67
|
+
*
|
|
68
|
+
* @param sound
|
|
69
|
+
* @param layout
|
|
70
|
+
*/
|
|
71
|
+
export function enginePeaks(sound: {peaks: number[]|null, waveform: string|null}, layout: 'inline' | 'strip'): number[] | string | null {
|
|
72
|
+
return (layout === 'strip' && sound.waveform) || sound.peaks || null;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** What `loadTrack()` is given for one sound (see {@link engineTrack}). */
|
|
76
|
+
export interface EngineTrack {
|
|
77
|
+
waveform: number[] | string | null;
|
|
78
|
+
autoplay: boolean;
|
|
79
|
+
duration?: number;
|
|
80
|
+
downloadUrl?: string;
|
|
81
|
+
preload?: string;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* The `loadTrack()` options for a sound: its peaks (see {@link enginePeaks}),
|
|
86
|
+
* its known length — so the player shows the right total, places a seek and
|
|
87
|
+
* fills the Media Session scrubber before the audio's metadata arrives,
|
|
88
|
+
* which with `preload: 'none'` is only once it plays — and its download
|
|
89
|
+
* link, so a `showDownload` engine offers what the row offers.
|
|
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
|
+
*
|
|
96
|
+
* @param sound
|
|
97
|
+
* @param layout
|
|
98
|
+
* @param autoplay - Start once loaded (false: cue only).
|
|
99
|
+
* @param preload - The media element's `preload` for this sound.
|
|
100
|
+
*/
|
|
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 {
|
|
102
|
+
const track: EngineTrack = {waveform: enginePeaks(sound, layout), autoplay};
|
|
103
|
+
if (preload) track.preload = preload;
|
|
104
|
+
if (sound.duration != null && sound.duration > 0) track.duration = sound.duration;
|
|
105
|
+
if (sound.download) track.downloadUrl = sound.download;
|
|
106
|
+
return track;
|
|
107
|
+
}
|
|
@@ -2,8 +2,10 @@
|
|
|
2
2
|
* The runtime's option surface: every option with its default, the
|
|
3
3
|
* `data-*` form a container (or a server-rendering wrapper) uses, and the
|
|
4
4
|
* merge that resolves them. The options that shape the markup are defined
|
|
5
|
-
* with the renderer (`render/options.
|
|
6
|
-
* guards compare their
|
|
5
|
+
* with the renderer (`render/options.ts`) and included here. `types.ts`
|
|
6
|
+
* documents each option; the wrappers' drift guards compare their
|
|
7
|
+
* forwarding against `WaveformSoundsOptions` (in the generated
|
|
8
|
+
* `types/types.d.ts`).
|
|
7
9
|
*
|
|
8
10
|
* Precedence, as across the waveform family: data-* > constructor > default.
|
|
9
11
|
*
|
|
@@ -12,11 +14,12 @@
|
|
|
12
14
|
|
|
13
15
|
import {RENDER_DEFAULTS} from '../render/options.js';
|
|
14
16
|
import {LOG} from '../shared/utils.js';
|
|
17
|
+
import type {WaveformSoundsOptions} from '../types.js';
|
|
15
18
|
|
|
16
19
|
export {RENDER_DEFAULTS};
|
|
17
20
|
|
|
18
21
|
/** Every option, with its default. */
|
|
19
|
-
export const DEFAULT_OPTIONS = {
|
|
22
|
+
export const DEFAULT_OPTIONS: WaveformSoundsOptions = {
|
|
20
23
|
...RENDER_DEFAULTS,
|
|
21
24
|
sounds: null,
|
|
22
25
|
manifest: null,
|
|
@@ -28,7 +31,9 @@ export const DEFAULT_OPTIONS = {
|
|
|
28
31
|
loop: null,
|
|
29
32
|
autoAdvance: false,
|
|
30
33
|
arrowAudition: true,
|
|
31
|
-
|
|
34
|
+
// null is "unset" (the container's id, else a hash); the public type,
|
|
35
|
+
// unchanged from 0.3.1, has no null, hence the cast (it emits nothing).
|
|
36
|
+
idPrefix: null as unknown as string,
|
|
32
37
|
urlState: false,
|
|
33
38
|
playerOptions: null,
|
|
34
39
|
playerClass: null,
|
|
@@ -44,10 +49,10 @@ export const DEFAULT_OPTIONS = {
|
|
|
44
49
|
/**
|
|
45
50
|
* A boolean attribute: present-and-empty or "true" → true, "false" → false.
|
|
46
51
|
*
|
|
47
|
-
* @param
|
|
48
|
-
* @returns
|
|
52
|
+
* @param value
|
|
53
|
+
* @returns undefined for anything else (not set).
|
|
49
54
|
*/
|
|
50
|
-
export function parseBool(value) {
|
|
55
|
+
export function parseBool(value: string | undefined): boolean | undefined {
|
|
51
56
|
if (value === '' || value === 'true') return true;
|
|
52
57
|
if (value === 'false') return false;
|
|
53
58
|
return undefined;
|
|
@@ -57,10 +62,9 @@ export function parseBool(value) {
|
|
|
57
62
|
* A comma list attribute ("type, key" → ['type', 'key']). An empty string
|
|
58
63
|
* is an empty list (e.g. `data-sorts=""` = no sort menu).
|
|
59
64
|
*
|
|
60
|
-
* @param
|
|
61
|
-
* @returns {string[]|undefined}
|
|
65
|
+
* @param value
|
|
62
66
|
*/
|
|
63
|
-
export function parseList(value) {
|
|
67
|
+
export function parseList(value: string | undefined): string[] | undefined {
|
|
64
68
|
if (value == null) return undefined;
|
|
65
69
|
return value.split(',').map((x) => x.trim()).filter(Boolean);
|
|
66
70
|
}
|
|
@@ -68,10 +72,9 @@ export function parseList(value) {
|
|
|
68
72
|
/**
|
|
69
73
|
* A number attribute; an empty string is "not set".
|
|
70
74
|
*
|
|
71
|
-
* @param
|
|
72
|
-
* @returns {number|undefined}
|
|
75
|
+
* @param value
|
|
73
76
|
*/
|
|
74
|
-
export function parseNumber(value) {
|
|
77
|
+
export function parseNumber(value: string | undefined): number | undefined {
|
|
75
78
|
return value === undefined || value === '' ? undefined : Number(value);
|
|
76
79
|
}
|
|
77
80
|
|
|
@@ -79,10 +82,9 @@ export function parseNumber(value) {
|
|
|
79
82
|
* `data-url-state`: "true"/empty → true, "false" → false, anything else is
|
|
80
83
|
* the parameter prefix.
|
|
81
84
|
*
|
|
82
|
-
* @param
|
|
83
|
-
* @returns {boolean|string|undefined}
|
|
85
|
+
* @param value
|
|
84
86
|
*/
|
|
85
|
-
export function parseUrlState(value) {
|
|
87
|
+
export function parseUrlState(value: string | undefined): boolean | string | undefined {
|
|
86
88
|
if (value === undefined) return undefined;
|
|
87
89
|
const b = parseBool(value);
|
|
88
90
|
return b === undefined ? value : b;
|
|
@@ -93,11 +95,10 @@ export function parseUrlState(value) {
|
|
|
93
95
|
* reported and ignored, never thrown: a typo in markup must not take the
|
|
94
96
|
* whole list down.
|
|
95
97
|
*
|
|
96
|
-
* @param
|
|
97
|
-
* @param
|
|
98
|
-
* @returns {Object|undefined}
|
|
98
|
+
* @param value
|
|
99
|
+
* @param name - The attribute name, for the warning.
|
|
99
100
|
*/
|
|
100
|
-
export function parseJson(value, name) {
|
|
101
|
+
export function parseJson(value: string | undefined, name: string): Record<string, any> | undefined {
|
|
101
102
|
if (!value) return undefined;
|
|
102
103
|
try {
|
|
103
104
|
return JSON.parse(value);
|
|
@@ -112,12 +113,12 @@ export function parseJson(value, name) {
|
|
|
112
113
|
* `data-page-size` → `pageSize`). Attributes that are absent (or unusable)
|
|
113
114
|
* are left out, so they never override a constructor option.
|
|
114
115
|
*
|
|
115
|
-
* @param
|
|
116
|
-
* @returns
|
|
116
|
+
* @param el
|
|
117
|
+
* @returns The options found.
|
|
117
118
|
*/
|
|
118
|
-
export function readDataOptions(el) {
|
|
119
|
+
export function readDataOptions(el: HTMLElement): Record<string, any> {
|
|
119
120
|
const d = el.dataset || {};
|
|
120
|
-
const out = {
|
|
121
|
+
const out: Record<string, any> = {
|
|
121
122
|
player: d.player || undefined,
|
|
122
123
|
manifest: d.manifest || undefined,
|
|
123
124
|
search: parseBool(d.search),
|
|
@@ -150,11 +151,10 @@ export function readDataOptions(el) {
|
|
|
150
151
|
* Merge option sources: later ones win, and null/undefined never
|
|
151
152
|
* overwrite (an unset prop must not erase a default).
|
|
152
153
|
*
|
|
153
|
-
* @param
|
|
154
|
-
* @returns {Object}
|
|
154
|
+
* @param sources
|
|
155
155
|
*/
|
|
156
|
-
export function mergeOptions(...sources) {
|
|
157
|
-
const out = {};
|
|
156
|
+
export function mergeOptions(...sources: (Record<string, any> | null | undefined)[]): Record<string, any> {
|
|
157
|
+
const out: Record<string, any> = {};
|
|
158
158
|
for (const src of sources) {
|
|
159
159
|
if (!src) continue;
|
|
160
160
|
for (const k in src) if (src[k] !== null && src[k] !== undefined) out[k] = src[k];
|
|
@@ -10,15 +10,28 @@
|
|
|
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
|
-
* @param
|
|
17
|
-
* @param
|
|
18
|
-
* @param
|
|
19
|
-
* @returns
|
|
29
|
+
* @param lo - The lower handle.
|
|
30
|
+
* @param hi - The upper handle.
|
|
31
|
+
* @param extent - The slider's range ({@link bpmExtent}).
|
|
32
|
+
* @returns `''` for an open end.
|
|
20
33
|
*/
|
|
21
|
-
export function bpmFilterFromRange(lo, hi, extent) {
|
|
34
|
+
export function bpmFilterFromRange(lo: number, hi: number, extent: {min: number, max: number}): {bpmMin: string, bpmMax: string} {
|
|
22
35
|
const a = Math.min(lo, hi), b = Math.max(lo, hi);
|
|
23
36
|
return {
|
|
24
37
|
bpmMin: a > extent.min ? String(a) : '',
|
|
@@ -31,12 +44,11 @@ export function bpmFilterFromRange(lo, hi, extent) {
|
|
|
31
44
|
* set one at its value (clamped into the pack's range, so a link with
|
|
32
45
|
* `?bpm=60-300` still shows sensible handles).
|
|
33
46
|
*
|
|
34
|
-
* @param
|
|
35
|
-
* @param
|
|
36
|
-
* @returns {{lo: number, hi: number}}
|
|
47
|
+
* @param filter
|
|
48
|
+
* @param extent
|
|
37
49
|
*/
|
|
38
|
-
export function bpmRangeFromFilter(filter, extent) {
|
|
39
|
-
const read = (v, fallback) => {
|
|
50
|
+
export function bpmRangeFromFilter(filter: {bpmMin?: string|number, bpmMax?: string|number}, extent: {min: number, max: number}): {lo: number, hi: number} {
|
|
51
|
+
const read = (v: string | number | undefined, fallback: number): number => {
|
|
40
52
|
const n = Number(v);
|
|
41
53
|
return v === '' || v == null || !Number.isFinite(n) ? fallback : Math.min(Math.max(n, extent.min), extent.max);
|
|
42
54
|
};
|
|
@@ -48,11 +60,10 @@ export function bpmRangeFromFilter(filter, extent) {
|
|
|
48
60
|
/**
|
|
49
61
|
* A handle's position along the track, 0..1.
|
|
50
62
|
*
|
|
51
|
-
* @param
|
|
52
|
-
* @param
|
|
53
|
-
* @returns {number}
|
|
63
|
+
* @param value
|
|
64
|
+
* @param extent
|
|
54
65
|
*/
|
|
55
|
-
export function bpmFraction(value, extent) {
|
|
66
|
+
export function bpmFraction(value: number, extent: {min: number, max: number}): number {
|
|
56
67
|
const span = extent.max - extent.min;
|
|
57
68
|
return span > 0 ? Math.min(Math.max((value - extent.min) / span, 0), 1) : 0;
|
|
58
69
|
}
|
|
@@ -60,9 +71,8 @@ export function bpmFraction(value, extent) {
|
|
|
60
71
|
/**
|
|
61
72
|
* Is a BPM limit set on either side?
|
|
62
73
|
*
|
|
63
|
-
* @param
|
|
64
|
-
* @returns {boolean}
|
|
74
|
+
* @param filter
|
|
65
75
|
*/
|
|
66
|
-
export function hasBpmFilter(filter) {
|
|
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 !== '');
|
|
68
78
|
}
|
|
@@ -15,14 +15,14 @@ export const SEEK_STEP = 0.1;
|
|
|
15
15
|
* Where a navigation key moves from position `at` in a list of `count`
|
|
16
16
|
* visible rows.
|
|
17
17
|
*
|
|
18
|
-
* @param
|
|
19
|
-
* @param
|
|
20
|
-
* @param
|
|
21
|
-
* @returns
|
|
18
|
+
* @param key - `KeyboardEvent.key`.
|
|
19
|
+
* @param at - The focused row's position among the visible rows.
|
|
20
|
+
* @param count - How many rows are visible.
|
|
21
|
+
* @returns The new position; `'search'` for ↑ on
|
|
22
22
|
* the first row (back to the search field); null when the key isn't a
|
|
23
23
|
* move or there is nowhere to go.
|
|
24
24
|
*/
|
|
25
|
-
export function rowTarget(key, at, count) {
|
|
25
|
+
export function rowTarget(key: string, at: number, count: number): number | 'search' | null {
|
|
26
26
|
if (!count) return null;
|
|
27
27
|
switch (key) {
|
|
28
28
|
case 'ArrowDown': return at + 1 < count ? at + 1 : null;
|
|
@@ -37,13 +37,28 @@ export function rowTarget(key, at, count) {
|
|
|
37
37
|
* The position an ←/→ press seeks to. Stops just short of the end, so a
|
|
38
38
|
* held → can't end the sound by accident.
|
|
39
39
|
*
|
|
40
|
-
* @param
|
|
41
|
-
* @param
|
|
42
|
-
* @returns
|
|
40
|
+
* @param progress - Current position, 0..1.
|
|
41
|
+
* @param key - `'ArrowRight'` or `'ArrowLeft'`.
|
|
42
|
+
* @returns The new position, or null for any other key.
|
|
43
43
|
*/
|
|
44
|
-
export function seekTarget(progress, key) {
|
|
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;
|
|
47
62
|
}
|
|
48
63
|
|
|
49
64
|
/**
|
|
@@ -51,11 +66,10 @@ export function seekTarget(progress, key) {
|
|
|
51
66
|
* "Show more" would reveal.
|
|
52
67
|
*
|
|
53
68
|
* @template T
|
|
54
|
-
* @param
|
|
55
|
-
* @param
|
|
56
|
-
* @returns {{visible: Set<T>, remaining: number}}
|
|
69
|
+
* @param shown - The sounds that match, in display order.
|
|
70
|
+
* @param limit - How many to show (Infinity for all).
|
|
57
71
|
*/
|
|
58
|
-
export function pageWindow(shown, limit) {
|
|
72
|
+
export function pageWindow<T>(shown: T[], limit: number): {visible: Set<T>, remaining: number} {
|
|
59
73
|
const visible = new Set(shown.slice(0, limit));
|
|
60
74
|
return {visible, remaining: shown.length - visible.size};
|
|
61
75
|
}
|
|
@@ -64,10 +78,9 @@ export function pageWindow(shown, limit) {
|
|
|
64
78
|
* The page limit that reveals position `pos` (used when playing past the
|
|
65
79
|
* end of the current page, e.g. by `next()` or auto-advance).
|
|
66
80
|
*
|
|
67
|
-
* @param
|
|
68
|
-
* @param
|
|
69
|
-
* @returns {number}
|
|
81
|
+
* @param limit - The current limit.
|
|
82
|
+
* @param pos - The position that must be visible.
|
|
70
83
|
*/
|
|
71
|
-
export function limitToReveal(limit, pos) {
|
|
84
|
+
export function limitToReveal(limit: number, pos: number): number {
|
|
72
85
|
return pos >= limit ? pos + 1 : limit;
|
|
73
86
|
}
|