The <waveform-sounds> element
2.1.0 adds a custom element, modelled on the core’s
<waveform-player>. It is the same list as
<div data-waveform-sounds>, as a tag:
<waveform-sounds manifest="/previews/sounds.json" page-size="20"></waveform-sounds>Load the player and the list as usual (Install); the default entry registers the tag.
Attributes
Section titled “Attributes”Every data-* option is an attribute, with or
without the data- prefix: manifest, player, page-size, filters,
columns, url-state, auto-advance, strings, player-options, … When both
forms are present, the plain one wins.
- Booleans: a bare attribute means true —
<waveform-sounds auto-advance>, asdata-auto-advanceis. - Values are parsed exactly as
data-*values are: lists are comma-separated (filters="type,bpm"), andstrings/player-optionstake JSON.
<waveform-sounds manifest="/previews/sounds.json" player="strip" filters="type,bpm" columns="bpm,key" url-state></waveform-sounds>Light DOM
Section titled “Light DOM”The element renders into itself — no shadow root — so:
- the stylesheet applies, as to any
[data-waveform-sounds](its rules name the tag as well as the class); waveformsounds:*events bubble from the tag, so one listener ondocumenthears it like any other list.
The stylesheet makes the element a block. An empty element that isn’t defined
yet (its manifest still to load) holds --ws-element-height if you set one
(default 0), so the page doesn’t shift as it fills in.
Adopting server-rendered markup
Section titled “Adopting server-rendered markup”Put renderSounds() output
inside the tag and the element adopts it, as [data-waveform-sounds] does:
the list is there, readable and crawlable, before any script runs, and the
runtime wires it up instead of rebuilding it.
import { renderSounds } from '@arraypress/waveform-sounds/render';
const html = `<waveform-sounds page-size="20">${renderSounds(sounds, { pageSize: 20 })}</waveform-sounds>`;The runtime reads its options from the element’s attributes, not from the markup — give the tag the same options you gave the renderer (see Server rendering).
When the element is removed, the list is destroyed with
destroy({ restore: true }): adopted
markup is put back exactly as the server sent it, so the same markup can be
mounted again. Do the same when you tear down a list built in script over
server markup that a framework will re-mount:
list.destroy({ restore: true }); // adopted markup back as it arrivedWhen it’s built, and rebuilt
Section titled “When it’s built, and rebuilt”- Built on connect, adopting any server markup inside it, or fetching its
manifest. - Changing an option attribute (either form) rebuilds the list once per
microtask, from the sounds it already holds — or fetches afresh when
manifestchanged. - Removing the element destroys its list. Moving it within the DOM (removed and re-added in the same task) does not, and playback carries on.
Scripting it
Section titled “Scripting it”const el = document.querySelector('waveform-sounds');
el.sounds; // the WaveformSounds instance (null while disconnected)await el.sounds?.ready;el.sounds?.setFilter({ type: 'Bass' });el.setAttribute('page-size', '50'); // rebuilt with the new page sizeA rebuild makes a new instance, so read el.sounds when you need it rather than
keeping a reference.
Registration
Section titled “Registration”The default entry — import '@arraypress/waveform-sounds' or the CDN script —
registers <waveform-sounds> before it scans the page, unless the page sets
<html data-waveform-autoinit="false">.
That opt-out switches both off.
The /no-autoinit entry registers
nothing. Call defineWaveformSoundsElement() yourself — optionally with another
tag name:
import { defineWaveformSoundsElement } from '@arraypress/waveform-sounds/no-autoinit';
defineWaveformSoundsElement(); // <waveform-sounds>defineWaveformSoundsElement('pack-sounds'); // or your own nameA <script> page that opted out uses the same function from the global,
WaveformSounds.defineElement():
<html data-waveform-autoinit="false"> … <script>WaveformSounds.defineElement();</script>Either returns the registered constructor (or undefined outside a browser), and
a name that is already defined is left alone. The class is exported too, as
WaveformSoundsElement.