@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/src/js/index.js CHANGED
@@ -1,108 +1,75 @@
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.
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
- // Import the main class
14
- import {WaveformPlayer} from './core.js';
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 we're running in a browser (vs. SSR / Node), where `window` and
32
- * `document` are available. Guards the auto-init and global-attach steps.
33
- * @returns {boolean}
34
- */
35
- const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'undefined';
36
-
37
- /**
38
- * Scan the document for declarative player markup and instantiate one
39
- * {@link WaveformPlayer} per matching element.
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
- * Finds every element carrying the `data-waveform-player` attribute and, for
42
- * each one not already initialized, constructs a player from it (the constructor
43
- * reads the element's `data-*` attributes for configuration). Each successfully
44
- * initialized element is flagged with `data-waveform-initialized="true"` so
45
- * repeat calls are idempotent and never double-initialize the same element.
46
- * Elements already claimed by a programmatically constructed player carry no
47
- * such flag, so they are skipped by instance lookup instead. Construction errors
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
- * @returns {void}
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
- function autoInit() {
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
- if (isBrowser()) {
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
- document.addEventListener('DOMContentLoaded', autoInit);
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
- autoInit();
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