@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 CHANGED
@@ -38,6 +38,36 @@ import WaveformPlayer from '@arraypress/waveform-player';
38
38
  new WaveformPlayer('#player', { url: 'track.mp3', title: 'My Song', artist: 'The Artist' });
39
39
  ```
40
40
 
41
+ ### Initializing only what you control
42
+
43
+ Pages that render markup they don't author — user content, a CMS, an editor canvas — can turn the automatic scan off from the document element:
44
+
45
+ ```html
46
+ <html data-waveform-autoinit="false">
47
+ ```
48
+
49
+ Nothing is initialized until you ask for it. Pass `init()` a root to scan only the subtree you own:
50
+
51
+ ```js
52
+ WaveformPlayer.init( document.querySelector( '#my-app' ) );
53
+ ```
54
+
55
+ Constructing players directly still works too; only the scan on import is suppressed.
56
+
57
+ That attribute is for pages. If you're **bundled into a page you don't author** — a CMS block, a plugin, a widget dropped into someone else's template — there's no `<html>` in scope to mark before your `import` is evaluated. Import the library without the scan instead:
58
+
59
+ ```js
60
+ import WaveformPlayer from '@arraypress/waveform-player/no-autoinit';
61
+
62
+ // Identical in every other way. Nothing is initialized until you say so:
63
+ WaveformPlayer.init( myContainer );
64
+ new WaveformPlayer( el, { url: 'track.mp3' } );
65
+ ```
66
+
67
+ Same class, same options, same `window.WaveformPlayer`; ships as ESM and CJS. Pick one entry point per bundle — each carries its own copy of the class and its own instance registry.
68
+
69
+ This scopes initialization — it isn't a sanitizer. `playIcon` / `pauseIcon` (and their `data-play-icon` / `data-pause-icon` equivalents) inject raw markup by design, for any player you do build. Untrusted content still needs sanitizing before it reaches the page.
70
+
41
71
  ## Documentation
42
72
 
43
73
  Every option, style, event and method is documented on the docs site.