@arraypress/waveform-player 1.26.0 → 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/src/js/index.js CHANGED
@@ -1,39 +1,26 @@
1
1
  /**
2
2
  * @module index
3
- * @description Public entry point for the WaveformPlayer library.
3
+ * @description Default public entry point for the WaveformPlayer library.
4
4
  *
5
- * Wires together the runtime surfaces for the player: it re-exports the
6
- * {@link WaveformPlayer} class (default and named), exposes a static
7
- * `WaveformPlayer.init` hook, scans the DOM for declarative `[data-waveform-player]`
8
- * markup and auto-instantiates a player for each match, and attaches the class
9
- * to `window` for plain `<script>`/CDN usage. Loading this module is enough to
10
- * make any markup-driven players on the page come alive once the DOM is ready —
11
- * unless the page opts out of that scan (see {@link autoInitDisabled}).
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
- // Import the main class
15
- import {WaveformPlayer} from './core.js';
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 bundled consumer can reach.
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', () => autoInit());
67
+ document.addEventListener('DOMContentLoaded', () => WaveformPlayer.init());
137
68
  } else {
138
- autoInit();
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