@arraypress/waveform-sounds 0.0.0-stage → 0.1.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.
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The list's icons: 24×24 single-path SVGs that take `currentColor`, so
3
+ * they follow whatever colour their control has. Decorative (aria-hidden);
4
+ * every control carries its own label.
5
+ *
6
+ * @module icons
7
+ */
8
+
9
+ /**
10
+ * One icon.
11
+ *
12
+ * @param {string} path - The SVG path data.
13
+ * @param {string} [extraClass] - Classes beyond `ws-icon`.
14
+ * @returns {string}
15
+ */
16
+ function icon(path, extraClass = '') {
17
+ const cls = extraClass ? `ws-icon ${extraClass}` : 'ws-icon';
18
+ return `<svg class="${cls}" viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="${path}"/></svg>`;
19
+ }
20
+
21
+ export const ICONS = {
22
+ play: icon('M8 5.5v13l11-6.5z', 'ws-icon-play'),
23
+ pause: icon('M7 5h3.5v14H7zM13.5 5H17v14h-3.5z', 'ws-icon-pause'),
24
+ search: icon('M10.5 4a6.5 6.5 0 1 0 4.03 11.6l4.43 4.43 1.41-1.41-4.43-4.43A6.5 6.5 0 0 0 10.5 4zm0 2a4.5 4.5 0 1 1 0 9 4.5 4.5 0 0 1 0-9z'),
25
+ chevron: icon('M6.4 8.6 12 14.2l5.6-5.6L19 10l-7 7-7-7z', 'ws-menu-chevron'),
26
+ check: icon('M9.5 16.2 5.3 12l-1.4 1.4 5.6 5.6 11-11-1.4-1.4z', 'ws-menu-check'),
27
+ download: icon('M11 4h2v8.6l3.3-3.3 1.4 1.4L12 16.4l-5.7-5.7 1.4-1.4 3.3 3.3zM5 18h14v2H5z'),
28
+ loop: icon('M17 4l3 3-3 3V8H8a3 3 0 0 0-3 3v1H3v-1a5 5 0 0 1 5-5h9V4zM7 20l-3-3 3-3v2h9a3 3 0 0 0 3-3v-1h2v1a5 5 0 0 1-5 5H7v2z'),
29
+ };
@@ -0,0 +1,295 @@
1
+ /**
2
+ * Server-safe renderer: the component's markup as an HTML string, from the
3
+ * same data helpers the browser uses. No DOM, no window.
4
+ *
5
+ * A wrapper that renders on the server (Astro, SSR React/Vue/Svelte) calls
6
+ * {@link renderSounds} and emits the result inside a
7
+ * `[data-waveform-sounds]` element; the browser runtime then ADOPTS that
8
+ * markup instead of building its own, so the list is there (and readable,
9
+ * and crawlable) before any script runs.
10
+ *
11
+ * The markup is the contract between the two halves: every class and
12
+ * `data-ws-*` attribute here is read by the runtime (`core.js`,
13
+ * `menus.js`, `rows.js`).
14
+ *
15
+ * @module render
16
+ */
17
+
18
+ import {escapeHtml} from '@arraypress/text';
19
+ import {availableSorts, encodePeaks, facets, formatDuration, normalizeSounds} from '../data/sounds.js';
20
+ import {h, text} from './html.js';
21
+ import {ICONS} from './icons.js';
22
+ import {RENDER_DEFAULTS, resolveRenderOptions} from './options.js';
23
+ import {countText, DEFAULT_STRINGS, fill, SORT_LABEL_KEYS} from './strings.js';
24
+ import {hashString} from '../shared/utils.js';
25
+
26
+ export {escapeHtml, RENDER_DEFAULTS, resolveRenderOptions, DEFAULT_STRINGS, countText, fill, availableSorts};
27
+
28
+ /**
29
+ * A stable id prefix for a list's dropdowns, from its sounds: the same on
30
+ * the server and in the browser. Two lists of the SAME sounds on one page
31
+ * collide, so they need an `idPrefix` each.
32
+ *
33
+ * @param {{url: string}[]} sounds
34
+ * @returns {string} e.g. `ws1x9k2f`.
35
+ */
36
+ export function idBase(sounds) {
37
+ const signature = [sounds.length, ...sounds.map((s) => s.url)].join('|');
38
+ return `ws${hashString(signature).toString(36)}`;
39
+ }
40
+
41
+ /**
42
+ * Which controls the toolbar shows. Each appears only when it's enabled
43
+ * AND the data gives it something to do: no type filter for one type, no
44
+ * key menu for one key, no BPM range without a spread of BPMs, no sort
45
+ * menu with one usable order. Types past `maxTypeChips` become a menu (a
46
+ * pack has a handful; a whole library can have fifty).
47
+ *
48
+ * @param {ReturnType<typeof facets>} f - The sounds' facets.
49
+ * @param {ReturnType<typeof resolveRenderOptions>} o - Resolved options.
50
+ * @returns {{types: 'chips'|'menu'|null, key: boolean, bpm: boolean, sorts: string[], search: boolean, loop: boolean, count: boolean}}
51
+ */
52
+ export function toolbarPlan(f, o) {
53
+ const typed = o.filters.includes('type') && f.types.length > 1;
54
+ const sorts = availableSorts(o.sorts, f);
55
+ return {
56
+ types: !typed ? null : f.types.length > o.maxTypeChips ? 'menu' : 'chips',
57
+ key: o.filters.includes('key') && f.keys.length > 1,
58
+ bpm: o.filters.includes('bpm') && f.bpm !== null && f.bpm.max > f.bpm.min,
59
+ sorts: sorts.length > 1 ? sorts : [],
60
+ search: !!o.search,
61
+ loop: !!o.loopToggle,
62
+ count: !!o.showCount,
63
+ };
64
+ }
65
+
66
+ /* ── Controls ───────────────────────────────────────────────────────── */
67
+
68
+ /** The search field. */
69
+ function renderSearch(s) {
70
+ return h('label', {class: 'ws-search'},
71
+ ICONS.search,
72
+ h('span', {class: 'ws-sr'}, text(s.search)),
73
+ h('input', {type: 'search', class: 'ws-search-input', 'data-ws-search': true, placeholder: s.searchPlaceholder, autocomplete: 'off', spellcheck: 'false'}),
74
+ );
75
+ }
76
+
77
+ /**
78
+ * A dropdown: a button and a popup listbox, with a search field when it
79
+ * has more than `searchFrom` options. The runtime (`menus.js`) opens,
80
+ * filters and navigates it; without JS the button still shows the value.
81
+ *
82
+ * @param {string} name - 'type' | 'key' | 'sort' (the runtime routes by it).
83
+ * @param {Object} m
84
+ * @param {string} m.id - Id prefix for this list.
85
+ * @param {string} m.label - Accessible name ("Type").
86
+ * @param {string} [m.prefix] - Visible lead-in ("Sort by"); otherwise the label is screen-reader only.
87
+ * @param {string} m.value - The selected value.
88
+ * @param {{value: string, label: string, count?: number}[]} m.options
89
+ * @param {number} m.searchFrom - Options above which a search field is added.
90
+ * @param {string} [m.placeholder] - The search field's placeholder (no field without one).
91
+ * @param {string} m.noMatches - Shown when the search matches nothing.
92
+ * @returns {string}
93
+ */
94
+ export function renderMenu(name, m) {
95
+ const listId = `${m.id}-${name}-list`;
96
+ const current = m.options.find((o) => o.value === m.value) ?? m.options[0];
97
+ const searchable = m.placeholder && m.options.length > m.searchFrom;
98
+
99
+ const button = h('button', {type: 'button', class: 'ws-menu-btn', 'data-ws-menu-btn': true, 'aria-haspopup': 'listbox', 'aria-expanded': 'false', 'aria-controls': listId},
100
+ m.prefix
101
+ ? h('span', {class: 'ws-menu-prefix'}, text(m.prefix))
102
+ : h('span', {class: 'ws-sr'}, text(`${m.label}: `)),
103
+ h('span', {class: 'ws-menu-value', 'data-ws-menu-value': true}, text(current.label)),
104
+ ICONS.chevron,
105
+ );
106
+ const search = searchable && h('input', {
107
+ type: 'search', class: 'ws-menu-search', 'data-ws-menu-search': true, role: 'combobox',
108
+ 'aria-expanded': 'true', 'aria-controls': listId, 'aria-autocomplete': 'list',
109
+ 'aria-label': m.placeholder, placeholder: m.placeholder, autocomplete: 'off', spellcheck: 'false',
110
+ });
111
+ const options = m.options.map((o, i) => h('li', {role: 'option', id: `${m.id}-${name}-${i}`, class: 'ws-menu-option', 'data-value': o.value, 'aria-selected': String(o === current)},
112
+ ICONS.check,
113
+ h('span', {class: 'ws-menu-text'}, text(o.label)),
114
+ o.count != null && h('span', {class: 'ws-menu-count'}, text(o.count)),
115
+ ));
116
+
117
+ return h('div', {class: 'ws-menu', 'data-ws-menu': name},
118
+ button,
119
+ h('div', {class: 'ws-menu-pop', 'data-ws-menu-pop': true, hidden: true},
120
+ search,
121
+ h('ul', {class: 'ws-menu-list', role: 'listbox', id: listId, 'aria-label': m.label, tabindex: '-1', 'data-ws-menu-list': true}, options),
122
+ h('p', {class: 'ws-menu-none', 'data-ws-menu-none': true, hidden: true}, text(m.noMatches)),
123
+ ),
124
+ );
125
+ }
126
+
127
+ /** The BPM range: two number fields, with the data's range as placeholders. */
128
+ function renderBpmRange(s, range) {
129
+ const field = (attr, label, placeholder) => h('input', {type: 'number', inputmode: 'numeric', [attr]: true, 'aria-label': label, placeholder, min: '0', step: '1'});
130
+ return h('span', {class: 'ws-bpm-range', role: 'group', 'aria-label': s.bpm},
131
+ field('data-ws-bpm-min', s.bpmMin, range.min),
132
+ h('span', {'aria-hidden': 'true'}, '–'),
133
+ field('data-ws-bpm-max', s.bpmMax, range.max),
134
+ h('span', {class: 'ws-bpm-unit', 'aria-hidden': 'true'}, text(s.bpm)),
135
+ );
136
+ }
137
+
138
+ /** The Loop toggle. */
139
+ function renderLoopToggle(s) {
140
+ return h('button', {type: 'button', class: 'ws-loop', 'data-ws-loop': true, 'aria-pressed': 'false'}, ICONS.loop, h('span', {}, text(s.loop)));
141
+ }
142
+
143
+ /** One type chip ('' = all). */
144
+ function renderChip(value, label, count, pressed) {
145
+ return h('button', {type: 'button', class: 'ws-chip', 'data-ws-type': value, 'aria-pressed': String(pressed)},
146
+ h('span', {class: 'ws-chip-label'}, text(label)), ' ', h('span', {class: 'ws-chip-count'}, text(count)));
147
+ }
148
+
149
+ /**
150
+ * The toolbar: search, the controls row (type menu, key menu, BPM range,
151
+ * sort menu, Loop) and the meta row (type chips + the count).
152
+ *
153
+ * @param {ReturnType<typeof toolbarPlan>} plan
154
+ * @param {Object} ctx - `{o, s, f, total, id}` from {@link renderSounds}.
155
+ * @returns {string}
156
+ */
157
+ function renderToolbar(plan, {o, s, f, total, id}) {
158
+ const menu = (name, m) => renderMenu(name, {id, searchFrom: o.menuSearch, noMatches: s.noMatches, ...m});
159
+ const controls = [
160
+ plan.types === 'menu' && menu('type', {
161
+ label: s.types, value: '', placeholder: s.findType,
162
+ options: [{value: '', label: s.allTypes, count: total}, ...f.types.map((t) => ({value: t.name, label: t.name, count: t.count}))],
163
+ }),
164
+ plan.key && menu('key', {
165
+ label: s.key, value: '', placeholder: s.findKey,
166
+ options: [{value: '', label: s.anyKey}, ...f.keys.map((k) => ({value: k, label: k}))],
167
+ }),
168
+ plan.bpm && renderBpmRange(s, f.bpm),
169
+ plan.sorts.length > 0 && menu('sort', {
170
+ label: s.sort, prefix: s.sortBy, value: plan.sorts[0],
171
+ options: plan.sorts.map((k) => ({value: k, label: s[SORT_LABEL_KEYS[k]]})),
172
+ }),
173
+ plan.loop && renderLoopToggle(s),
174
+ ].filter(Boolean);
175
+
176
+ const chips = plan.types === 'chips' && h('div', {class: 'ws-types', role: 'group', 'aria-label': s.types},
177
+ renderChip('', s.all, total, true),
178
+ f.types.map((t) => renderChip(t.name, t.name, t.count, false)),
179
+ );
180
+ const count = plan.count && h('p', {class: 'ws-count', 'data-ws-count': true, 'aria-live': 'polite'}, text(countText(total, total, s)));
181
+
182
+ return h('div', {class: 'ws-toolbar'},
183
+ plan.search && renderSearch(s),
184
+ controls.length > 0 && h('div', {class: 'ws-controls'}, controls),
185
+ // The chips and the count share a row (the count alone without chips).
186
+ (chips || count) && h('div', {class: 'ws-meta'}, chips, count),
187
+ );
188
+ }
189
+
190
+ /* ── Rows ───────────────────────────────────────────────────────────── */
191
+
192
+ /** The cells a column shows for a sound. */
193
+ const CELLS = {
194
+ type: (sound) => text(sound.type),
195
+ bpm: (sound) => text(sound.bpm ?? ''),
196
+ key: (sound) => text(sound.key),
197
+ duration: (sound) => text(formatDuration(sound.duration)),
198
+ };
199
+
200
+ /**
201
+ * One row. `index` is the sound's position in the ORIGINAL list: the
202
+ * runtime maps rows back to sounds through it, whatever order they are
203
+ * sorted into. Every field is also written as a `data-*` attribute, so the
204
+ * runtime can rebuild the sounds from server markup.
205
+ *
206
+ * @param {import('../../../index').Sound} sound - Normalised.
207
+ * @param {number} index
208
+ * @param {ReturnType<typeof resolveRenderOptions>} o
209
+ * @param {boolean} [hidden] - Past the first page.
210
+ * @returns {string}
211
+ */
212
+ export function renderRow(sound, index, o, hidden = false) {
213
+ const s = o.strings;
214
+ const vars = {title: sound.title};
215
+ const cells = o.columns.map((c) => h('span', {class: `ws-cell ws-${c}`}, CELLS[c](sound)));
216
+
217
+ return h('li', {
218
+ class: 'ws-row',
219
+ 'data-ws-index': index,
220
+ 'data-ws-id': sound.id,
221
+ 'data-url': sound.url,
222
+ 'data-title': sound.title,
223
+ 'data-type': sound.type || null,
224
+ 'data-bpm': sound.bpm,
225
+ 'data-key': sound.key || null,
226
+ 'data-duration': sound.duration,
227
+ 'data-tags': sound.tags?.length ? sound.tags.join(',') : null,
228
+ 'data-peaks': sound.peaks ? encodePeaks(sound.peaks) : null,
229
+ 'data-waveform': sound.waveform,
230
+ 'data-download': sound.download,
231
+ hidden,
232
+ },
233
+ h('button', {type: 'button', class: 'ws-play', 'aria-pressed': 'false', 'aria-label': fill(s.play, vars)}, ICONS.play, ICONS.pause),
234
+ h('span', {class: 'ws-cell ws-title'}, text(sound.title)),
235
+ // Wide rows: `display: contents` makes each cell a column. Narrow
236
+ // rows: one line under the title.
237
+ cells.length > 0 && h('span', {class: 'ws-cells'}, cells),
238
+ o.player === 'inline' && h('span', {class: 'ws-wave', role: 'slider', 'aria-label': fill(s.seek, vars), 'aria-valuemin': '0', 'aria-valuemax': '100', 'aria-valuenow': '0', tabindex: '-1'},
239
+ h('canvas', {class: 'ws-canvas', 'aria-hidden': 'true'})),
240
+ // Optional, per sound: a plain link. Rows without one carry nothing.
241
+ sound.download && h('a', {class: 'ws-download', href: sound.download, download: true, 'aria-label': fill(s.download, vars)}, ICONS.download),
242
+ );
243
+ }
244
+
245
+ /* ── The whole list ─────────────────────────────────────────────────── */
246
+
247
+ /**
248
+ * What follows the rows: the empty state, "Show more", the engine's slot
249
+ * (visible only in the strip layout) and a live region for announcements.
250
+ */
251
+ function renderFooter({o, s, total}) {
252
+ const page = o.pageSize > 0 ? o.pageSize : total;
253
+ const more = Math.max(0, total - page);
254
+ const strip = o.player === 'strip';
255
+ return [
256
+ h('p', {class: 'ws-empty', 'data-ws-empty': true, hidden: true}, text(s.empty), ' ',
257
+ h('button', {type: 'button', class: 'ws-clear', 'data-ws-clear': true}, text(s.clear))),
258
+ h('button', {type: 'button', class: 'ws-more', 'data-ws-more': true, hidden: more === 0}, text(fill(s.showMore, {count: Math.min(more, page)}))),
259
+ h('div', {class: strip ? 'ws-engine ws-engine--strip' : 'ws-engine', 'data-ws-engine': true, hidden: !strip}),
260
+ h('p', {class: 'ws-sr', 'data-ws-status': true, 'aria-live': 'polite'}),
261
+ ].join('');
262
+ }
263
+
264
+ /**
265
+ * The whole component's inner markup.
266
+ *
267
+ * @param {Object[]} sounds - Sounds (normalised or raw; normalised here).
268
+ * @param {Object} [options] - Render options (see `WaveformSoundsOptions`).
269
+ * @returns {string} HTML for the inside of `[data-waveform-sounds]`.
270
+ */
271
+ export function renderSounds(sounds, options = {}) {
272
+ const o = resolveRenderOptions(options);
273
+ const list = normalizeSounds(sounds);
274
+ const ctx = {o, s: o.strings, f: facets(list), total: list.length, id: o.idPrefix || idBase(list)};
275
+ const page = o.pageSize > 0 ? o.pageSize : Infinity;
276
+ return renderToolbar(toolbarPlan(ctx.f, o), ctx)
277
+ + h('ul', {class: `ws-list ws-list--${o.player}`, role: 'list', 'data-ws-list': true},
278
+ list.map((sound, i) => renderRow(sound, i, o, i >= page)))
279
+ + renderFooter(ctx);
280
+ }
281
+
282
+ /**
283
+ * The full element, for callers who want one string: the wrapper div with
284
+ * its `data-waveform-sounds` marker, its `data-player` and the inner markup.
285
+ *
286
+ * @param {Object[]} sounds
287
+ * @param {Object} [options]
288
+ * @param {string} [className] - Extra classes for the wrapper.
289
+ * @returns {string}
290
+ */
291
+ export function renderSoundsElement(sounds, options = {}, className = '') {
292
+ const o = resolveRenderOptions(options);
293
+ const cls = ['waveform-sounds', `waveform-sounds--${o.player}`, className].filter(Boolean).join(' ');
294
+ return h('div', {class: cls, 'data-waveform-sounds': true, 'data-player': o.player}, renderSounds(sounds, options));
295
+ }
@@ -0,0 +1,90 @@
1
+ /**
2
+ * The options that shape the markup — the renderer's whole input — with
3
+ * their defaults and validation. DOM-free: the server renderer uses it,
4
+ * and the runtime's option surface (`core/options.js`) builds on it.
5
+ *
6
+ * @module render/options
7
+ */
8
+
9
+ import {SORTS} from '../data/sounds.js';
10
+ import {DEFAULT_STRINGS} from './strings.js';
11
+
12
+ /** The filter controls a list can offer. */
13
+ export const FILTERS = ['type', 'key', 'bpm'];
14
+
15
+ /** The columns a row can show after its title. */
16
+ export const COLUMNS = ['type', 'bpm', 'key', 'duration'];
17
+
18
+ /** The options that shape the markup (the renderer's whole input). */
19
+ export const RENDER_DEFAULTS = {
20
+ player: 'inline',
21
+ search: true,
22
+ filters: [...FILTERS],
23
+ sorts: [...SORTS],
24
+ loopToggle: true,
25
+ showCount: true,
26
+ menuSearch: 8,
27
+ pageSize: 50,
28
+ columns: [...COLUMNS],
29
+ maxTypeChips: 10,
30
+ };
31
+
32
+ /**
33
+ * The object without its `undefined` entries (so spreading it can't erase
34
+ * a default).
35
+ *
36
+ * @param {Object|null|undefined} obj
37
+ * @returns {Object}
38
+ */
39
+ export function defined(obj) {
40
+ const out = {};
41
+ for (const k in obj ?? {}) if (obj[k] !== undefined) out[k] = obj[k];
42
+ return out;
43
+ }
44
+
45
+ /**
46
+ * The entries of `values` that are allowed, in the caller's order; the
47
+ * fallback when `values` isn't a list.
48
+ *
49
+ * @param {unknown} values
50
+ * @param {string[]} allowed
51
+ * @param {string[]} fallback
52
+ * @returns {string[]}
53
+ */
54
+ export function allowedList(values, allowed, fallback) {
55
+ return Array.isArray(values) ? values.filter((v) => allowed.includes(v)) : fallback;
56
+ }
57
+
58
+ /**
59
+ * A whole number ≥ 0, or the fallback.
60
+ *
61
+ * @param {unknown} value
62
+ * @param {number} fallback
63
+ * @returns {number}
64
+ */
65
+ export function wholeNumber(value, fallback) {
66
+ const n = Number(value);
67
+ return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
68
+ }
69
+
70
+ /**
71
+ * The render options, defaulted and validated: unknown filters, sorts and
72
+ * columns are dropped, counts are whole numbers, `strings` is complete.
73
+ *
74
+ * @param {Object} [options]
75
+ * @returns {typeof RENDER_DEFAULTS & {strings: typeof DEFAULT_STRINGS, idPrefix?: string}}
76
+ */
77
+ export function resolveRenderOptions(options = {}) {
78
+ const o = {...RENDER_DEFAULTS, ...defined(options)};
79
+ return {
80
+ ...o,
81
+ player: o.player === 'strip' ? 'strip' : 'inline',
82
+ filters: allowedList(o.filters, FILTERS, RENDER_DEFAULTS.filters),
83
+ sorts: allowedList(o.sorts, SORTS, RENDER_DEFAULTS.sorts),
84
+ columns: allowedList(o.columns, COLUMNS, RENDER_DEFAULTS.columns),
85
+ menuSearch: wholeNumber(o.menuSearch, RENDER_DEFAULTS.menuSearch),
86
+ maxTypeChips: wholeNumber(o.maxTypeChips, RENDER_DEFAULTS.maxTypeChips),
87
+ pageSize: wholeNumber(o.pageSize, RENDER_DEFAULTS.pageSize),
88
+ strings: {...DEFAULT_STRINGS, ...defined(options.strings)},
89
+ };
90
+ }
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Every word the list shows or announces, so a site can translate it
3
+ * (`strings` option, or `data-strings` JSON). `{title}`, `{count}` and
4
+ * `{total}` are filled in.
5
+ *
6
+ * @module strings
7
+ */
8
+
9
+ /** The English defaults. */
10
+ export const DEFAULT_STRINGS = {
11
+ search: 'Search sounds',
12
+ searchPlaceholder: 'Search sounds…',
13
+ all: 'All',
14
+ types: 'Type',
15
+ key: 'Key',
16
+ anyKey: 'Any key',
17
+ allTypes: 'All types',
18
+ findType: 'Find a type…',
19
+ findKey: 'Find a key…',
20
+ noMatches: 'No matches',
21
+ bpm: 'BPM',
22
+ bpmMin: 'Min BPM',
23
+ bpmMax: 'Max BPM',
24
+ sort: 'Sort',
25
+ sortBy: 'Sort by',
26
+ sortDefault: 'Default',
27
+ sortTitle: 'Name',
28
+ sortBpm: 'BPM',
29
+ sortKey: 'Key',
30
+ sortDuration: 'Length',
31
+ loop: 'Loop',
32
+ play: 'Play {title}',
33
+ pause: 'Pause {title}',
34
+ seek: 'Seek {title}',
35
+ download: 'Download {title}',
36
+ count: '{count} sounds',
37
+ countOne: '1 sound',
38
+ countFiltered: '{count} of {total} sounds',
39
+ showMore: 'Show {count} more',
40
+ empty: 'No sounds match.',
41
+ clear: 'Clear filters',
42
+ nowPlaying: 'Playing {title}',
43
+ };
44
+
45
+ /** The label each sort order shows in the Sort menu. */
46
+ export const SORT_LABEL_KEYS = {
47
+ default: 'sortDefault',
48
+ title: 'sortTitle',
49
+ bpm: 'sortBpm',
50
+ key: 'sortKey',
51
+ duration: 'sortDuration',
52
+ };
53
+
54
+ /**
55
+ * Fill `{name}` placeholders; unknown ones are left as written.
56
+ *
57
+ * @param {string} template
58
+ * @param {Record<string, string|number>} [vars]
59
+ * @returns {string}
60
+ */
61
+ export function fill(template, vars = {}) {
62
+ return String(template).replace(/\{(\w+)\}/g, (match, name) => (name in vars ? String(vars[name]) : match));
63
+ }
64
+
65
+ /**
66
+ * The count line: "300 sounds", "1 sound", "12 of 300 sounds".
67
+ *
68
+ * @param {number} shown - Sounds matching the filter.
69
+ * @param {number} total - All sounds.
70
+ * @param {typeof DEFAULT_STRINGS} [strings]
71
+ * @returns {string}
72
+ */
73
+ export function countText(shown, total, strings = DEFAULT_STRINGS) {
74
+ if (shown !== total) return fill(strings.countFiltered, {count: shown, total});
75
+ return total === 1 ? strings.countOne : fill(strings.count, {count: total});
76
+ }
@@ -0,0 +1,6 @@
1
+ /**
2
+ * `@arraypress/waveform-sounds/render` — the DOM-free half, for server
3
+ * rendering. Importing it never touches `window` or `document`.
4
+ */
5
+ export {renderSounds, renderSoundsElement, DEFAULT_STRINGS, escapeHtml} from './render/markup.js';
6
+ export {normalizeSounds, parseManifest, encodePeaks, decodePeaks, normalizeKey, facets, formatDuration} from './data/sounds.js';
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Small shared helpers with no state. The pure ones run anywhere; the two
3
+ * that take an element only read from it.
4
+ *
5
+ * @module utils
6
+ */
7
+
8
+ /** Prefix for every console message and thrown error. */
9
+ export const LOG = '[WaveformSounds]';
10
+
11
+ /**
12
+ * Clamp a number into a range.
13
+ *
14
+ * @param {number} value
15
+ * @param {number} [min=0]
16
+ * @param {number} [max=1]
17
+ * @returns {number}
18
+ */
19
+ export function clamp(value, min = 0, max = 1) {
20
+ return Math.min(Math.max(value, min), max);
21
+ }
22
+
23
+ /**
24
+ * Where a pointer sits across a box, as a fraction 0..1 — the seek
25
+ * position of a click on a row waveform.
26
+ *
27
+ * @param {number} clientX - The pointer's x (viewport coordinates).
28
+ * @param {{left: number, width: number}} rect - The box (getBoundingClientRect()).
29
+ * @returns {number} 0..1; 0 for a box with no width.
30
+ */
31
+ export function pointerFraction(clientX, rect) {
32
+ return rect && rect.width ? clamp((clientX - rect.left) / rect.width) : 0;
33
+ }
34
+
35
+ /**
36
+ * Is the element a place the user types into? Keyboard shortcuts (`/`)
37
+ * must not fire there.
38
+ *
39
+ * @param {Element|null|undefined} el
40
+ * @returns {boolean}
41
+ */
42
+ export function isTyping(el) {
43
+ return !!el && (el.isContentEditable || /^(INPUT|SELECT|TEXTAREA)$/.test(el.tagName));
44
+ }
45
+
46
+ /**
47
+ * Dispatch a bubbling `waveformsounds:<name>` CustomEvent from an element.
48
+ * Every event the list emits goes through here, so they share one shape:
49
+ * the detail plus the instance that sent it.
50
+ *
51
+ * @param {EventTarget} target
52
+ * @param {string} name - Without the prefix (`'play'`).
53
+ * @param {Object} detail
54
+ * @returns {CustomEvent} The event dispatched.
55
+ */
56
+ export function emit(target, name, detail) {
57
+ const event = new CustomEvent(`waveformsounds:${name}`, {bubbles: true, detail});
58
+ target.dispatchEvent(event);
59
+ return event;
60
+ }
61
+
62
+ /**
63
+ * A small, stable string hash (djb2, 32-bit) — for ids that must come out
64
+ * the same on the server and in the browser. Not cryptographic.
65
+ *
66
+ * @param {string} str
67
+ * @returns {number} An unsigned 32-bit integer.
68
+ */
69
+ export function hashString(str) {
70
+ let hash = 5381;
71
+ for (const char of str) hash = (hash * 33 + char.codePointAt(0)) >>> 0;
72
+ return hash;
73
+ }