@arraypress/waveform-player 1.25.1 → 1.27.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 +30 -0
- package/dist/waveform-player-no-autoinit.cjs +3041 -0
- package/dist/waveform-player-no-autoinit.esm.js +64 -0
- package/dist/waveform-player.cjs +40 -24
- package/dist/waveform-player.esm.js +2 -2
- package/dist/waveform-player.js +39 -23
- package/dist/waveform-player.min.js +2 -2
- package/index.d.ts +9 -2
- package/no-autoinit.d.ts +17 -0
- package/package.json +17 -3
- package/src/js/core.js +16 -2
- package/src/js/entry.js +143 -0
- package/src/js/index.js +56 -89
- package/src/js/utils.js +17 -0
package/src/js/index.js
CHANGED
|
@@ -1,108 +1,75 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @module index
|
|
3
|
-
* @description
|
|
3
|
+
* @description Default public entry point for the WaveformPlayer library.
|
|
4
4
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* `
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* make any markup-driven players on the page come alive once the DOM
|
|
5
|
+
* The full runtime surface from `./entry.js` — the {@link WaveformPlayer} class
|
|
6
|
+
* (default and named), the `WaveformPlayer.init` hook, the `WaveformPlayer.utils`
|
|
7
|
+
* helpers and the `window` global — *plus* the one thing that entry point
|
|
8
|
+
* deliberately omits: a scan of the DOM for declarative `[data-waveform-player]`
|
|
9
|
+
* markup, auto-instantiating a player for each match. Loading this module is
|
|
10
|
+
* enough to make any markup-driven players on the page come alive once the DOM
|
|
11
|
+
* is ready.
|
|
12
|
+
*
|
|
13
|
+
* Two opt-outs, for two different kinds of consumer:
|
|
14
|
+
*
|
|
15
|
+
* - A page that controls its own `<html>` sets `data-waveform-autoinit="false"`
|
|
16
|
+
* (see {@link autoInitDisabled}).
|
|
17
|
+
* - A bundled consumer that controls no markup at all imports
|
|
18
|
+
* `@arraypress/waveform-player/no-autoinit` instead, and never loads this
|
|
19
|
+
* module.
|
|
11
20
|
*/
|
|
12
21
|
|
|
13
|
-
|
|
14
|
-
import {
|
|
15
|
-
import {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes} from './utils.js';
|
|
16
|
-
import {detectColorScheme} from './themes.js';
|
|
17
|
-
|
|
18
|
-
// Expose a small set of pure helpers as a single source of truth so consumers
|
|
19
|
-
// (e.g. @arraypress/waveform-bar, @arraypress/waveform-playlist) can reuse them
|
|
20
|
-
// instead of shipping divergent copies. `parseDataAttributes` lets wrappers read
|
|
21
|
-
// the player's full `data-*` option surface off a host element without
|
|
22
|
-
// re-implementing (and drifting from) the contract. `detectColorScheme` is here
|
|
23
|
-
// for the same reason: the bar used to carry its own copy of the heuristic and
|
|
24
|
-
// the two drifted (both shipped the transparent-background bug of #21, fixed
|
|
25
|
-
// independently). Attached to the class so it's reachable from the IIFE global
|
|
26
|
-
// too — which is how the bar reaches it, since it depends on this package as a
|
|
27
|
-
// runtime peer rather than importing the module.
|
|
28
|
-
WaveformPlayer.utils = {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes, detectColorScheme};
|
|
22
|
+
import WaveformPlayer from './entry.js';
|
|
23
|
+
import {isBrowser} from './utils.js';
|
|
29
24
|
|
|
30
25
|
/**
|
|
31
|
-
* Whether
|
|
32
|
-
*
|
|
33
|
-
*
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
*
|
|
39
|
-
*
|
|
26
|
+
* Whether the page has opted out of the scan that runs on import.
|
|
27
|
+
*
|
|
28
|
+
* A page that renders markup it does not author — user content, a CMS, an editor
|
|
29
|
+
* canvas — may not want every `[data-waveform-player]` on it to become a player.
|
|
30
|
+
* Setting `data-waveform-autoinit="false"` on the document element suppresses the
|
|
31
|
+
* automatic scan: nothing is initialized unless the page asks for it, either by
|
|
32
|
+
* constructing players itself or by calling {@link WaveformPlayer.init} against
|
|
33
|
+
* markup it trusts. Both remain available; only the automatic call is gated.
|
|
34
|
+
*
|
|
35
|
+
* Read off `<html>` rather than a global because ES module imports are evaluated
|
|
36
|
+
* before the importing module's body runs — a consumer with a static `import`
|
|
37
|
+
* never gets the chance to set a flag first. Markup is in place before any script
|
|
38
|
+
* executes, so an attribute is the one mechanism such a consumer can reach.
|
|
40
39
|
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
-
*
|
|
44
|
-
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
48
|
-
* are caught and logged so one broken element cannot abort the rest of the scan.
|
|
49
|
-
* A no-op in non-DOM environments (e.g. SSR).
|
|
40
|
+
* It only reaches that far, though. A consumer bundled *into* a page it doesn't
|
|
41
|
+
* author — a CMS block, a plugin, a widget embedded in someone else's template —
|
|
42
|
+
* has no `<html>` in scope to mark: the document element belongs to the host
|
|
43
|
+
* page (and, in an editor, to an iframe it doesn't own). For those, the opt-out
|
|
44
|
+
* is the `@arraypress/waveform-player/no-autoinit` entry point, which never
|
|
45
|
+
* evaluates this module at all. This attribute is for pages; that entry point is
|
|
46
|
+
* for bundles.
|
|
50
47
|
*
|
|
51
|
-
*
|
|
48
|
+
* This scopes initialization; it does not sanitize anything. `playIcon` /
|
|
49
|
+
* `pauseIcon` still inject raw markup for any player that *is* built.
|
|
50
|
+
*
|
|
51
|
+
* @returns {boolean}
|
|
52
52
|
*/
|
|
53
|
-
|
|
54
|
-
if (!isBrowser()) return;
|
|
55
|
-
|
|
56
|
-
const elements = document.querySelectorAll('[data-waveform-player]');
|
|
57
|
-
|
|
58
|
-
elements.forEach(element => {
|
|
59
|
-
// Skip elements already claimed by a player. The `data-waveform-initialized`
|
|
60
|
-
// flag only covers elements this scan built; an element constructed
|
|
61
|
-
// programmatically (`new WaveformPlayer(el)`) carries no flag, so without
|
|
62
|
-
// the instance lookup a later scan would build a second player over it.
|
|
63
|
-
if (
|
|
64
|
-
element.dataset.waveformInitialized === 'true' ||
|
|
65
|
-
WaveformPlayer.getInstance(element)
|
|
66
|
-
) {
|
|
67
|
-
return;
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
try {
|
|
71
|
-
new WaveformPlayer(element);
|
|
72
|
-
element.dataset.waveformInitialized = 'true';
|
|
73
|
-
} catch (error) {
|
|
74
|
-
console.error('[WaveformPlayer] Failed to initialize:', error, element);
|
|
75
|
-
}
|
|
76
|
-
});
|
|
77
|
-
}
|
|
53
|
+
const autoInitDisabled = () => document.documentElement?.dataset.waveformAutoinit === 'false';
|
|
78
54
|
|
|
79
55
|
// Initialize when DOM is ready: defer until DOMContentLoaded if the document is
|
|
80
|
-
// still parsing, otherwise run the scan immediately on import.
|
|
81
|
-
|
|
56
|
+
// still parsing, otherwise run the scan immediately on import. Skipped entirely
|
|
57
|
+
// when the document opts out — the gate sits here rather than inside autoInit()
|
|
58
|
+
// so `WaveformPlayer.init()` stays usable as a manual, page-controlled scan.
|
|
59
|
+
//
|
|
60
|
+
// This block is the *entire* difference between this module and `./entry.js`.
|
|
61
|
+
// Keep it that way: anything added below it belongs in entry.js, or the
|
|
62
|
+
// no-autoinit entry point silently stops matching this one.
|
|
63
|
+
if (isBrowser() && !autoInitDisabled()) {
|
|
82
64
|
if (document.readyState === 'loading') {
|
|
83
|
-
|
|
65
|
+
// Wrapped, not passed by reference: a listener is called with the Event
|
|
66
|
+
// as its first argument, which `autoInit` would take as its `root`.
|
|
67
|
+
document.addEventListener('DOMContentLoaded', () => WaveformPlayer.init());
|
|
84
68
|
} else {
|
|
85
|
-
|
|
69
|
+
WaveformPlayer.init();
|
|
86
70
|
}
|
|
87
71
|
}
|
|
88
72
|
|
|
89
|
-
/**
|
|
90
|
-
* Static re-scan hook.
|
|
91
|
-
*
|
|
92
|
-
* Exposes {@link autoInit} as `WaveformPlayer.init` so callers can manually
|
|
93
|
-
* (re-)scan the DOM after dynamically injecting `[data-waveform-player]` markup.
|
|
94
|
-
* Already-initialized elements are skipped on subsequent calls.
|
|
95
|
-
*
|
|
96
|
-
* @type {typeof autoInit}
|
|
97
|
-
*/
|
|
98
|
-
WaveformPlayer.init = autoInit;
|
|
99
|
-
|
|
100
|
-
// For CDN/browser usage: expose the class as a global so it is reachable from a
|
|
101
|
-
// plain <script> tag without an ES module loader.
|
|
102
|
-
if (isBrowser()) {
|
|
103
|
-
window.WaveformPlayer = WaveformPlayer;
|
|
104
|
-
}
|
|
105
|
-
|
|
106
73
|
/**
|
|
107
74
|
* The {@link WaveformPlayer} class.
|
|
108
75
|
* @type {typeof WaveformPlayer}
|
|
@@ -110,4 +77,4 @@ if (isBrowser()) {
|
|
|
110
77
|
export default WaveformPlayer;
|
|
111
78
|
|
|
112
79
|
// Named exports
|
|
113
|
-
export {WaveformPlayer};
|
|
80
|
+
export {WaveformPlayer};
|
package/src/js/utils.js
CHANGED
|
@@ -11,6 +11,23 @@
|
|
|
11
11
|
*/
|
|
12
12
|
export const DEFAULT_SAMPLES = 1800;
|
|
13
13
|
|
|
14
|
+
/**
|
|
15
|
+
* Whether we're running in a browser (vs. SSR / Node), where `window` and
|
|
16
|
+
* `document` are available.
|
|
17
|
+
*
|
|
18
|
+
* Lives here rather than in an entry point because both entry points need it —
|
|
19
|
+
* `index.js` to gate its import-time scan, `entry.js` to guard `autoInit` and
|
|
20
|
+
* the `window` attach — and a local copy in each is exactly the kind of
|
|
21
|
+
* duplicate that drifts (see the `detectColorScheme` note in `entry.js`).
|
|
22
|
+
* Deliberately *not* added to the public `WaveformPlayer.utils` bag: it's an
|
|
23
|
+
* internal guard, not part of the consumer contract.
|
|
24
|
+
*
|
|
25
|
+
* @returns {boolean}
|
|
26
|
+
*/
|
|
27
|
+
export function isBrowser() {
|
|
28
|
+
return typeof window !== 'undefined' && typeof document !== 'undefined';
|
|
29
|
+
}
|
|
30
|
+
|
|
14
31
|
/**
|
|
15
32
|
* Largest value in an array, via a loop — NOT `Math.max(...arr)`, whose
|
|
16
33
|
* argument spread throws `RangeError: Maximum call stack size exceeded` for
|