@arraypress/waveform-player 1.26.0 → 1.27.1
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 +12 -0
- package/dist/waveform-player-no-autoinit.cjs +3042 -0
- package/dist/waveform-player-no-autoinit.esm.js +64 -0
- package/dist/waveform-player.cjs +17 -11
- package/dist/waveform-player.esm.js +2 -2
- package/dist/waveform-player.js +16 -10
- package/dist/waveform-player.min.js +2 -2
- package/no-autoinit.d.ts +17 -0
- package/package.json +17 -3
- package/src/js/core.js +6 -0
- package/src/js/entry.js +143 -0
- package/src/js/index.js +34 -121
- package/src/js/utils.js +17 -0
package/src/js/index.js
CHANGED
|
@@ -1,39 +1,26 @@
|
|
|
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
|
|
11
|
-
*
|
|
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.
|
|
12
20
|
*/
|
|
13
21
|
|
|
14
|
-
|
|
15
|
-
import {
|
|
16
|
-
import {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes} from './utils.js';
|
|
17
|
-
import {detectColorScheme} from './themes.js';
|
|
18
|
-
|
|
19
|
-
// Expose a small set of pure helpers as a single source of truth so consumers
|
|
20
|
-
// (e.g. @arraypress/waveform-bar, @arraypress/waveform-playlist) can reuse them
|
|
21
|
-
// instead of shipping divergent copies. `parseDataAttributes` lets wrappers read
|
|
22
|
-
// the player's full `data-*` option surface off a host element without
|
|
23
|
-
// re-implementing (and drifting from) the contract. `detectColorScheme` is here
|
|
24
|
-
// for the same reason: the bar used to carry its own copy of the heuristic and
|
|
25
|
-
// the two drifted (both shipped the transparent-background bug of #21, fixed
|
|
26
|
-
// independently). Attached to the class so it's reachable from the IIFE global
|
|
27
|
-
// too — which is how the bar reaches it, since it depends on this package as a
|
|
28
|
-
// runtime peer rather than importing the module.
|
|
29
|
-
WaveformPlayer.utils = {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes, detectColorScheme};
|
|
30
|
-
|
|
31
|
-
/**
|
|
32
|
-
* Whether we're running in a browser (vs. SSR / Node), where `window` and
|
|
33
|
-
* `document` are available. Guards the auto-init and global-attach steps.
|
|
34
|
-
* @returns {boolean}
|
|
35
|
-
*/
|
|
36
|
-
const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'undefined';
|
|
22
|
+
import WaveformPlayer from './entry.js';
|
|
23
|
+
import {isBrowser} from './utils.js';
|
|
37
24
|
|
|
38
25
|
/**
|
|
39
26
|
* Whether the page has opted out of the scan that runs on import.
|
|
@@ -48,7 +35,15 @@ const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'un
|
|
|
48
35
|
* Read off `<html>` rather than a global because ES module imports are evaluated
|
|
49
36
|
* before the importing module's body runs — a consumer with a static `import`
|
|
50
37
|
* never gets the chance to set a flag first. Markup is in place before any script
|
|
51
|
-
* executes, so an attribute is the one mechanism a
|
|
38
|
+
* executes, so an attribute is the one mechanism such a consumer can reach.
|
|
39
|
+
*
|
|
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.
|
|
52
47
|
*
|
|
53
48
|
* This scopes initialization; it does not sanitize anything. `playIcon` /
|
|
54
49
|
* `pauseIcon` still inject raw markup for any player that *is* built.
|
|
@@ -57,106 +52,24 @@ const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'un
|
|
|
57
52
|
*/
|
|
58
53
|
const autoInitDisabled = () => document.documentElement?.dataset.waveformAutoinit === 'false';
|
|
59
54
|
|
|
60
|
-
/**
|
|
61
|
-
* Construct a player for one declarative element, unless it already has one.
|
|
62
|
-
*
|
|
63
|
-
* Skips elements already claimed by a player. The `data-waveform-initialized`
|
|
64
|
-
* flag only covers elements a scan built; an element constructed
|
|
65
|
-
* programmatically (`new WaveformPlayer(el)`) carries no flag, so without the
|
|
66
|
-
* instance lookup a later scan would build a second player over it.
|
|
67
|
-
*
|
|
68
|
-
* Construction errors are caught and logged rather than thrown, so one broken
|
|
69
|
-
* element cannot abort the rest of a scan.
|
|
70
|
-
*
|
|
71
|
-
* @param {HTMLElement} element - Element carrying `data-waveform-player`.
|
|
72
|
-
* @returns {void}
|
|
73
|
-
*/
|
|
74
|
-
function initElement(element) {
|
|
75
|
-
if (
|
|
76
|
-
element.dataset.waveformInitialized === 'true' ||
|
|
77
|
-
WaveformPlayer.getInstance(element)
|
|
78
|
-
) {
|
|
79
|
-
return;
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
try {
|
|
83
|
-
new WaveformPlayer(element);
|
|
84
|
-
element.dataset.waveformInitialized = 'true';
|
|
85
|
-
} catch (error) {
|
|
86
|
-
console.error('[WaveformPlayer] Failed to initialize:', error, element);
|
|
87
|
-
}
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
/**
|
|
91
|
-
* Scan for declarative player markup and instantiate one {@link WaveformPlayer}
|
|
92
|
-
* per matching element.
|
|
93
|
-
*
|
|
94
|
-
* Finds every element carrying the `data-waveform-player` attribute and, for
|
|
95
|
-
* each one not already initialized, constructs a player from it (the constructor
|
|
96
|
-
* reads the element's `data-*` attributes for configuration). Each successfully
|
|
97
|
-
* initialized element is flagged with `data-waveform-initialized="true"` so
|
|
98
|
-
* repeat calls are idempotent and never double-initialize the same element.
|
|
99
|
-
* A no-op in non-DOM environments (e.g. SSR).
|
|
100
|
-
*
|
|
101
|
-
* `root` scopes the scan. It pairs with the {@link autoInitDisabled} opt-out:
|
|
102
|
-
* a page that suppresses the automatic document-wide scan can still initialize
|
|
103
|
-
* the subtree it owns, and gets the claim-checking and per-element error
|
|
104
|
-
* isolation above rather than hand-rolling a `querySelectorAll` loop that has
|
|
105
|
-
* neither.
|
|
106
|
-
*
|
|
107
|
-
* The scan itself is unconditional — the opt-out gates only the automatic
|
|
108
|
-
* invocation below, never a call made by hand.
|
|
109
|
-
*
|
|
110
|
-
* @param {Document|Element} [root=document] - Subtree to scan. Matched against
|
|
111
|
-
* itself as well as its descendants.
|
|
112
|
-
* @returns {void}
|
|
113
|
-
*/
|
|
114
|
-
function autoInit(root = document) {
|
|
115
|
-
if (!isBrowser()) return;
|
|
116
|
-
|
|
117
|
-
const scope = root || document;
|
|
118
|
-
|
|
119
|
-
// `querySelectorAll` never matches its own root, so a caller scoping the
|
|
120
|
-
// scan to a single player (`init(playerEl)`) would silently get nothing.
|
|
121
|
-
if (scope.matches?.('[data-waveform-player]')) {
|
|
122
|
-
initElement(scope);
|
|
123
|
-
}
|
|
124
|
-
|
|
125
|
-
scope.querySelectorAll('[data-waveform-player]').forEach(initElement);
|
|
126
|
-
}
|
|
127
|
-
|
|
128
55
|
// Initialize when DOM is ready: defer until DOMContentLoaded if the document is
|
|
129
56
|
// still parsing, otherwise run the scan immediately on import. Skipped entirely
|
|
130
57
|
// when the document opts out — the gate sits here rather than inside autoInit()
|
|
131
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.
|
|
132
63
|
if (isBrowser() && !autoInitDisabled()) {
|
|
133
64
|
if (document.readyState === 'loading') {
|
|
134
65
|
// Wrapped, not passed by reference: a listener is called with the Event
|
|
135
66
|
// as its first argument, which `autoInit` would take as its `root`.
|
|
136
|
-
document.addEventListener('DOMContentLoaded', () =>
|
|
67
|
+
document.addEventListener('DOMContentLoaded', () => WaveformPlayer.init());
|
|
137
68
|
} else {
|
|
138
|
-
|
|
69
|
+
WaveformPlayer.init();
|
|
139
70
|
}
|
|
140
71
|
}
|
|
141
72
|
|
|
142
|
-
/**
|
|
143
|
-
* Static re-scan hook.
|
|
144
|
-
*
|
|
145
|
-
* Exposes {@link autoInit} as `WaveformPlayer.init` so callers can manually
|
|
146
|
-
* (re-)scan the DOM after dynamically injecting `[data-waveform-player]` markup.
|
|
147
|
-
* Already-initialized elements are skipped on subsequent calls. Works whether or
|
|
148
|
-
* not the document opted out of the automatic scan.
|
|
149
|
-
*
|
|
150
|
-
* @type {typeof autoInit}
|
|
151
|
-
*/
|
|
152
|
-
WaveformPlayer.init = autoInit;
|
|
153
|
-
|
|
154
|
-
// For CDN/browser usage: expose the class as a global so it is reachable from a
|
|
155
|
-
// plain <script> tag without an ES module loader.
|
|
156
|
-
if (isBrowser()) {
|
|
157
|
-
window.WaveformPlayer = WaveformPlayer;
|
|
158
|
-
}
|
|
159
|
-
|
|
160
73
|
/**
|
|
161
74
|
* The {@link WaveformPlayer} class.
|
|
162
75
|
* @type {typeof WaveformPlayer}
|
|
@@ -164,4 +77,4 @@ if (isBrowser()) {
|
|
|
164
77
|
export default WaveformPlayer;
|
|
165
78
|
|
|
166
79
|
// Named exports
|
|
167
|
-
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
|