@arraypress/waveform-sounds 2.1.0 → 2.2.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.
Files changed (51) hide show
  1. package/README.md +21 -1
  2. package/dist/waveform-sounds-no-autoinit.esm.js +445 -144
  3. package/dist/waveform-sounds-render.esm.js +220 -78
  4. package/dist/waveform-sounds.css +4 -0
  5. package/dist/waveform-sounds.esm.js +445 -144
  6. package/dist/waveform-sounds.js +445 -144
  7. package/dist/waveform-sounds.min.css +1 -1
  8. package/dist/waveform-sounds.min.js +1 -1
  9. package/package.json +1 -1
  10. package/src/css/waveform-sounds.css +4 -0
  11. package/src/js/core/WaveformSounds.ts +224 -67
  12. package/src/js/core/element.ts +1 -1
  13. package/src/js/core/options.ts +1 -0
  14. package/src/js/data/keys.ts +156 -0
  15. package/src/js/data/navigation.ts +35 -8
  16. package/src/js/data/sounds.ts +29 -22
  17. package/src/js/data/url-state.ts +7 -3
  18. package/src/js/dom/draw.ts +16 -2
  19. package/src/js/dom/menus.ts +2 -1
  20. package/src/js/dom/rows.ts +38 -12
  21. package/src/js/render/icons.ts +59 -16
  22. package/src/js/render/markup.ts +115 -49
  23. package/src/js/render/options.ts +3 -1
  24. package/src/js/render/strings.ts +53 -1
  25. package/src/js/types.ts +24 -0
  26. package/types/core/WaveformSounds.d.ts +3 -3
  27. package/types/core/WaveformSounds.d.ts.map +1 -1
  28. package/types/core/options.d.ts.map +1 -1
  29. package/types/data/keys.d.ts +88 -0
  30. package/types/data/keys.d.ts.map +1 -0
  31. package/types/data/navigation.d.ts +27 -9
  32. package/types/data/navigation.d.ts.map +1 -1
  33. package/types/data/sounds.d.ts +20 -5
  34. package/types/data/sounds.d.ts.map +1 -1
  35. package/types/data/url-state.d.ts +6 -1
  36. package/types/data/url-state.d.ts.map +1 -1
  37. package/types/dom/draw.d.ts +5 -2
  38. package/types/dom/draw.d.ts.map +1 -1
  39. package/types/dom/menus.d.ts.map +1 -1
  40. package/types/dom/rows.d.ts +19 -8
  41. package/types/dom/rows.d.ts.map +1 -1
  42. package/types/render/icons.d.ts +41 -3
  43. package/types/render/icons.d.ts.map +1 -1
  44. package/types/render/markup.d.ts +27 -4
  45. package/types/render/markup.d.ts.map +1 -1
  46. package/types/render/options.d.ts +1 -1
  47. package/types/render/options.d.ts.map +1 -1
  48. package/types/render/strings.d.ts +22 -1
  49. package/types/render/strings.d.ts.map +1 -1
  50. package/types/types.d.ts +24 -0
  51. package/types/types.d.ts.map +1 -1
@@ -12,15 +12,23 @@
12
12
  * `data-ws-*` attribute here is read by the runtime (`core.js`,
13
13
  * `menus.js`, `rows.js`).
14
14
  *
15
+ * Since 2.2.0 the markup carries the rows the list starts with (a page, or
16
+ * with paging off the first `RENDER_CHUNK`), in its starting order,
17
+ * and EVERY sound as JSON (`<script type="application/json"
18
+ * data-ws-sounds>`); the runtime renders the other rows from it as they
19
+ * are revealed. Icons are `<use>`s of one sprite per list.
20
+ *
15
21
  * @module render
16
22
  */
17
23
 
18
24
  import {escapeHtml} from '@arraypress/text';
19
- import {availableSorts, encodePeaks, facets, formatDuration, normalizeSounds} from '../data/sounds.js';
25
+ import {availableSorts, encodePeaks, facets, formatDuration, normalizeSounds, sortSounds} from '../data/sounds.js';
26
+ import {firstRender} from '../data/navigation.js';
20
27
  import {h, text} from './html.js';
21
- import {ICONS} from './icons.js';
28
+ import {icon, iconSprite} from './icons.js';
29
+ import type {IconName} from './icons.js';
22
30
  import {defined, pickRenderOptions, RENDER_DEFAULTS, RENDER_OPTION_KEYS, resolveRenderOptions} from './options.js';
23
- import {bpmLabel, countText, DEFAULT_STRINGS, fill, SORT_LABEL_KEYS} from './strings.js';
31
+ import {bpmLabel, countText, DEFAULT_STRINGS, fill, rowSummary, SORT_LABEL_KEYS} from './strings.js';
24
32
  import {hashString} from '../shared/utils.js';
25
33
  import {bpmExtent} from '../data/bpm.js';
26
34
  import type {Sound, SoundInput, SoundsSort, WaveformSoundsOptions, WaveformSoundsStrings} from '../types.js';
@@ -93,7 +101,9 @@ export interface MenuSpec {
93
101
  label: string;
94
102
  prefix?: string;
95
103
  value: string;
96
- options: {value: string, label: string, count?: number}[];
104
+ /** `alt`: other names the menu's search finds the option by (a merged
105
+ * key's other spellings). */
106
+ options: {value: string, label: string, count?: number, alt?: string}[];
97
107
  searchFrom: number;
98
108
  placeholder?: string;
99
109
  noMatches: string;
@@ -102,9 +112,9 @@ export interface MenuSpec {
102
112
  /* ── Controls ───────────────────────────────────────────────────────── */
103
113
 
104
114
  /** The search field. */
105
- function renderSearch(s: WaveformSoundsStrings): string {
115
+ function renderSearch(s: WaveformSoundsStrings, id: string): string {
106
116
  return h('label', {class: 'ws-search'},
107
- ICONS.search,
117
+ icon(id, 'search'),
108
118
  h('span', {class: 'ws-sr'}, text(s.search)),
109
119
  h('input', {type: 'search', class: 'ws-search-input', 'data-ws-search': true, placeholder: s.searchPlaceholder, autocomplete: 'off', spellcheck: 'false'}),
110
120
  );
@@ -136,15 +146,15 @@ export function renderMenu(name: string, m: MenuSpec): string {
136
146
  ? h('span', {class: 'ws-menu-prefix'}, text(m.prefix))
137
147
  : h('span', {class: 'ws-sr'}, text(`${m.label}: `)),
138
148
  h('span', {class: 'ws-menu-value', 'data-ws-menu-value': true}, text(current.label)),
139
- ICONS.chevron,
149
+ icon(m.id, 'chevron', 'ws-menu-chevron'),
140
150
  );
141
151
  const search = searchable && h('input', {
142
152
  type: 'search', class: 'ws-menu-search', 'data-ws-menu-search': true, role: 'combobox',
143
153
  'aria-expanded': 'true', 'aria-controls': listId, 'aria-autocomplete': 'list',
144
154
  'aria-label': m.placeholder, placeholder: m.placeholder, autocomplete: 'off', spellcheck: 'false',
145
155
  });
146
- 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)},
147
- ICONS.check,
156
+ const options = m.options.map((o, i) => h('li', {role: 'option', id: `${m.id}-${name}-${i}`, class: 'ws-menu-option', 'data-value': o.value, 'data-alt': o.alt, 'aria-selected': String(o === current)},
157
+ icon(m.id, 'check', 'ws-menu-check'),
148
158
  h('span', {class: 'ws-menu-text'}, text(o.label)),
149
159
  o.count != null && h('span', {class: 'ws-menu-count'}, text(o.count)),
150
160
  ));
@@ -181,7 +191,7 @@ function renderBpmMenu({id, s, range}: {id: string, s: WaveformSoundsStrings, ra
181
191
  h('button', {type: 'button', class: 'ws-menu-btn', 'data-ws-menu-btn': true, 'aria-haspopup': 'dialog', 'aria-expanded': 'false', 'aria-controls': popId},
182
192
  h('span', {class: 'ws-sr'}, text(`${s.bpm}: `)),
183
193
  h('span', {class: 'ws-menu-value', 'data-ws-menu-value': true}, text(bpmLabel({}, range, s))),
184
- ICONS.chevron,
194
+ icon(id, 'chevron', 'ws-menu-chevron'),
185
195
  ),
186
196
  h('div', {class: 'ws-menu-pop ws-bpm-pop', id: popId, role: 'dialog', 'aria-label': s.bpm, 'data-ws-menu-pop': true, hidden: true},
187
197
  h('div', {class: 'ws-bpm-head'},
@@ -208,8 +218,8 @@ function renderLoopFilter(s: WaveformSoundsStrings): string {
208
218
  }
209
219
 
210
220
  /** The Loop toggle, pressed or not. */
211
- function renderLoopToggle(s: WaveformSoundsStrings, pressed: boolean): string {
212
- return h('button', {type: 'button', class: 'ws-loop', 'data-ws-loop': true, 'aria-pressed': String(pressed)}, ICONS.loop, h('span', {}, text(s.loop)));
221
+ function renderLoopToggle(s: WaveformSoundsStrings, pressed: boolean, id: string): string {
222
+ return h('button', {type: 'button', class: 'ws-loop', 'data-ws-loop': true, 'aria-pressed': String(pressed)}, icon(id, 'loop'), h('span', {}, text(s.loop)));
213
223
  }
214
224
 
215
225
  /** One type chip ('' = all). */
@@ -234,7 +244,7 @@ function renderToolbar(plan: ReturnType<typeof toolbarPlan>, {o, s, f, total, id
234
244
  }),
235
245
  plan.key && menu('key', {
236
246
  label: s.key, value: '', placeholder: s.findKey,
237
- options: [{value: '', label: s.anyKey}, ...f.keys.map((k) => ({value: k, label: k}))],
247
+ options: [{value: '', label: s.anyKey}, ...f.keys.map((k) => ({value: k, label: k, alt: f.keyAliases[k]?.join(' ')}))],
238
248
  }),
239
249
  plan.bpm && renderBpmMenu({id, s, range: bpmExtent(f.bpm)!}),
240
250
  plan.loops && renderLoopFilter(s),
@@ -242,7 +252,7 @@ function renderToolbar(plan: ReturnType<typeof toolbarPlan>, {o, s, f, total, id
242
252
  label: s.sort, prefix: s.sortBy, value: plan.sorts[0],
243
253
  options: plan.sorts.map((k) => ({value: k, label: s[SORT_LABEL_KEYS[k as SoundsSort]]})),
244
254
  }),
245
- plan.loop && renderLoopToggle(s, loopsByDefault(o.loop, f)),
255
+ plan.loop && renderLoopToggle(s, loopsByDefault(o.loop, f), id),
246
256
  ].filter(Boolean);
247
257
 
248
258
  const chips = plan.types === 'chips' && h('div', {class: 'ws-types', role: 'group', 'aria-label': s.types},
@@ -252,7 +262,7 @@ function renderToolbar(plan: ReturnType<typeof toolbarPlan>, {o, s, f, total, id
252
262
  const count = plan.count && h('p', {class: 'ws-count', 'data-ws-count': true, 'aria-live': 'polite'}, text(countText(total, total, s)));
253
263
 
254
264
  return h('div', {class: 'ws-toolbar'},
255
- plan.search && renderSearch(s),
265
+ plan.search && renderSearch(s, id),
256
266
  controls.length > 0 && h('div', {class: 'ws-controls'}, controls),
257
267
  // The chips and the count share a row (the count alone without chips).
258
268
  (chips || count) && h('div', {class: 'ws-meta'}, chips, count),
@@ -272,52 +282,90 @@ const CELLS: Record<string, (sound: Sound) => string> = {
272
282
  /**
273
283
  * One row. `index` is the sound's position in the ORIGINAL list: the
274
284
  * runtime maps rows back to sounds through it, whatever order they are
275
- * sorted into. Every field is also written as a `data-*` attribute, so the
276
- * runtime can rebuild the sounds from server markup.
285
+ * sorted into. The sound's data is not on the row (since 2.2.0): it travels
286
+ * once, in the list's JSON ({@link renderSoundsData}).
287
+ *
288
+ * For a screen reader the cells are one read-out ("Bass loops, 130 BPM,
289
+ * key B minor, 0:07") that also describes the play button; the visible
290
+ * cells are hidden from it. The waveform is a picture until its sound is
291
+ * current: the runtime makes the current row's the seek slider.
277
292
  *
278
293
  * @param sound - Normalised.
279
294
  * @param index
280
295
  * @param o
281
- * @param hidden - Past the first page.
296
+ * @param id - The list's id prefix (its icons, the read-out's id).
282
297
  */
283
- export function renderRow(sound: Sound, index: number, o: ReturnType<typeof resolveRenderOptions>, hidden: boolean = false): string {
298
+ export function renderRow(sound: Sound, index: number, o: ReturnType<typeof resolveRenderOptions>, id: string): string {
284
299
  const s = o.strings;
285
300
  const vars = {title: sound.title};
286
301
  const cells = o.columns.map((c) => h('span', {class: `ws-cell ws-${c}`}, CELLS[c](sound)));
302
+ const summary = rowSummary(sound, o.columns, s);
303
+ const described = summary ? `${id}-d${index}` : null;
287
304
 
288
- return h('li', {
289
- class: 'ws-row',
290
- 'data-ws-index': index,
291
- 'data-ws-id': sound.id,
292
- 'data-url': sound.url,
293
- 'data-title': sound.title,
294
- 'data-type': sound.type || null,
295
- 'data-bpm': sound.bpm,
296
- 'data-key': sound.key || null,
297
- 'data-duration': sound.duration,
298
- 'data-tags': sound.tags?.length ? sound.tags.join(',') : null,
299
- 'data-peaks': sound.peaks ? encodePeaks(sound.peaks) : null,
300
- 'data-waveform': sound.waveform,
301
- 'data-download': sound.download,
302
- 'data-loop': sound.loop ? 'true' : null,
303
- hidden,
304
- },
305
- h('button', {type: 'button', class: 'ws-play', 'aria-pressed': 'false', 'aria-label': fill(s.play, vars)}, ICONS.play, ICONS.pause),
305
+ return h('li', {class: 'ws-row', 'data-ws-index': index},
306
+ h('button', {type: 'button', class: 'ws-play', 'aria-pressed': 'false', 'aria-label': fill(s.play, vars), 'aria-describedby': described},
307
+ icon(id, 'play', 'ws-icon-play'), icon(id, 'pause', 'ws-icon-pause')),
306
308
  h('span', {class: 'ws-cell ws-title'},
307
309
  h('span', {class: 'ws-title-text'}, text(sound.title)),
308
- // A loop says so beside its name; a one-shot carries nothing.
309
- sound.loop && h('span', {class: 'ws-loop-mark', title: s.isLoop}, ICONS.loop, h('span', {class: 'ws-sr'}, text(s.isLoop))),
310
+ // A loop says so beside its name (and in the read-out); a one-shot carries nothing.
311
+ sound.loop && h('span', {class: 'ws-loop-mark', title: s.isLoop, 'aria-hidden': 'true'}, icon(id, 'loop')),
310
312
  ),
311
313
  // Wide rows: `display: contents` makes each cell a column. Narrow
312
314
  // rows: one line under the title.
313
- cells.length > 0 && h('span', {class: 'ws-cells'}, cells),
314
- 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'},
315
- h('canvas', {class: 'ws-canvas', 'aria-hidden': 'true'})),
315
+ cells.length > 0 && h('span', {class: 'ws-cells', 'aria-hidden': 'true'}, cells),
316
+ summary && h('span', {class: 'ws-sr', id: described}, text(summary)),
317
+ o.player === 'inline' && h('span', {class: 'ws-wave', 'aria-hidden': 'true'}, h('canvas', {class: 'ws-canvas'})),
316
318
  // Optional, per sound: a plain link. Rows without one carry nothing.
317
- sound.download && h('a', {class: 'ws-download', href: sound.download, download: true, 'aria-label': fill(s.download, vars)}, ICONS.download),
319
+ sound.download && h('a', {class: 'ws-download', href: sound.download, download: true, 'aria-label': fill(s.download, vars)}, icon(id, 'download')),
318
320
  );
319
321
  }
320
322
 
323
+ /**
324
+ * Every sound, as the JSON the runtime reads back (`readSoundsData`):
325
+ * normalised, with what normalising would fill in left out (an id that is
326
+ * the default `sound-<n>`, empty fields), peaks as hex. `<` is escaped, so
327
+ * no value can close the script element.
328
+ *
329
+ * @param list - Normalised.
330
+ */
331
+ export function renderSoundsData(list: Sound[]): string {
332
+ const data = list.map((s, i) => {
333
+ const d: Record<string, unknown> = {};
334
+ if (s.id !== `sound-${i + 1}`) d.id = s.id;
335
+ d.url = s.url;
336
+ d.title = s.title;
337
+ if (s.type) d.type = s.type;
338
+ if (s.bpm != null) d.bpm = s.bpm;
339
+ if (s.key) d.key = s.key;
340
+ if (s.duration != null) d.duration = s.duration;
341
+ if (s.tags.length) d.tags = s.tags;
342
+ if (s.peaks) d.peaks = encodePeaks(s.peaks);
343
+ if (s.waveform) d.waveform = s.waveform;
344
+ if (s.download) d.download = s.download;
345
+ if (s.loop) d.loop = true;
346
+ return d;
347
+ });
348
+ return `<script type="application/json" data-ws-sounds>${JSON.stringify(data).replace(/</g, '\\u003c')}</script>`;
349
+ }
350
+
351
+ /**
352
+ * The icons a list uses: its toolbar's, and its rows' — for every sound, as
353
+ * rows the runtime renders later use the same sprite.
354
+ *
355
+ * @param plan
356
+ * @param list
357
+ */
358
+ function iconsUsed(plan: ReturnType<typeof toolbarPlan>, list: Sound[]): IconName[] {
359
+ const names: IconName[] = [];
360
+ if (list.length) names.push('play', 'pause');
361
+ if (plan.search) names.push('search');
362
+ if (plan.types === 'menu' || plan.key || plan.sorts.length) names.push('chevron', 'check');
363
+ else if (plan.bpm) names.push('chevron');
364
+ if (plan.loop || list.some((s) => s.loop)) names.push('loop');
365
+ if (list.some((s) => s.download)) names.push('download');
366
+ return names;
367
+ }
368
+
321
369
  /* ── The whole list ─────────────────────────────────────────────────── */
322
370
 
323
371
  /**
@@ -345,14 +393,32 @@ function renderFooter({o, s, total}: RenderContext): string {
345
393
  * @returns HTML for the inside of `[data-waveform-sounds]`.
346
394
  */
347
395
  export function renderSounds(sounds: SoundInput[], options: WaveformSoundsOptions = {}): string {
396
+ return renderList(normalizeSounds(sounds), options, true);
397
+ }
398
+
399
+ /**
400
+ * {@link renderSounds}, from normalised sounds. The runtime renders a list
401
+ * it built itself through this without the JSON (it holds the sounds).
402
+ *
403
+ * @param list - Normalised.
404
+ * @param options
405
+ * @param withData - Append the sounds' JSON.
406
+ * @internal
407
+ */
408
+ export function renderList(list: Sound[], options: WaveformSoundsOptions, withData: boolean): string {
348
409
  const o = resolveRenderOptions(options);
349
- const list = normalizeSounds(sounds);
350
- const ctx: RenderContext = {o, s: o.strings, f: facets(list), total: list.length, id: o.idPrefix || idBase(list)};
351
- const page = o.pageSize > 0 ? o.pageSize : Infinity;
352
- return renderToolbar(toolbarPlan(ctx.f, o), ctx)
410
+ const ctx: RenderContext = {o, s: o.strings, f: facets(list, o), total: list.length, id: o.idPrefix || idBase(list)};
411
+ const plan = toolbarPlan(ctx.f, o);
412
+ // The rows the list starts with, in its starting order (the first sort
413
+ // offered, as the runtime starts): it adopts them as they are.
414
+ const index = new Map(list.map((sound, i) => [sound, i]));
415
+ const first = sortSounds(list, (availableSorts(o.sorts, ctx.f)[0] || 'default') as SoundsSort).slice(0, firstRender(o.pageSize));
416
+ return iconSprite(ctx.id, iconsUsed(plan, list))
417
+ + renderToolbar(plan, ctx)
353
418
  + h('ul', {class: `ws-list ws-list--${o.player}`, role: 'list', 'data-ws-list': true},
354
- list.map((sound, i) => renderRow(sound, i, o, i >= page)))
355
- + renderFooter(ctx);
419
+ first.map((sound) => renderRow(sound, index.get(sound)!, o, ctx.id)))
420
+ + renderFooter(ctx)
421
+ + (withData ? renderSoundsData(list) : '');
356
422
  }
357
423
 
358
424
  /**
@@ -18,7 +18,7 @@ export const COLUMNS: SoundsColumn[] = ['type', 'bpm', 'key', 'duration'];
18
18
 
19
19
  /** The options that shape the markup (the renderer's whole input). */
20
20
  export const RENDER_DEFAULTS: Required<Pick<WaveformSoundsOptions,
21
- 'player' | 'search' | 'filters' | 'sorts' | 'loopToggle' | 'showCount' | 'menuSearch' | 'pageSize' | 'columns' | 'maxTypeChips'>> = {
21
+ 'player' | 'search' | 'filters' | 'sorts' | 'loopToggle' | 'showCount' | 'menuSearch' | 'pageSize' | 'columns' | 'maxTypeChips' | 'mergeEnharmonicKeys'>> = {
22
22
  player: 'inline',
23
23
  search: true,
24
24
  filters: [...FILTERS],
@@ -29,6 +29,7 @@ export const RENDER_DEFAULTS: Required<Pick<WaveformSoundsOptions,
29
29
  pageSize: 50,
30
30
  columns: [...COLUMNS],
31
31
  maxTypeChips: 10,
32
+ mergeEnharmonicKeys: true,
32
33
  };
33
34
 
34
35
  /** {@link resolveRenderOptions}' result: the render options, complete, plus
@@ -113,6 +114,7 @@ export function resolveRenderOptions(options: WaveformSoundsOptions = {}): Rende
113
114
  menuSearch: wholeNumber(o.menuSearch, RENDER_DEFAULTS.menuSearch),
114
115
  maxTypeChips: wholeNumber(o.maxTypeChips, RENDER_DEFAULTS.maxTypeChips),
115
116
  pageSize: wholeNumber(o.pageSize, RENDER_DEFAULTS.pageSize),
117
+ mergeEnharmonicKeys: o.mergeEnharmonicKeys !== false,
116
118
  strings: {...DEFAULT_STRINGS, ...defined(options.strings)},
117
119
  };
118
120
  }
@@ -7,7 +7,9 @@
7
7
  */
8
8
 
9
9
  import {bpmRangeFromFilter, hasBpmFilter} from '../data/bpm.js';
10
- import type {SoundsSort, WaveformSoundsStrings} from '../types.js';
10
+ import {parseKey} from '../data/keys.js';
11
+ import {formatDuration} from '../data/sounds.js';
12
+ import type {Sound, SoundsColumn, SoundsSort, WaveformSoundsStrings} from '../types.js';
11
13
 
12
14
  /** The English defaults. */
13
15
  export const DEFAULT_STRINGS: WaveformSoundsStrings = {
@@ -53,6 +55,14 @@ export const DEFAULT_STRINGS: WaveformSoundsStrings = {
53
55
  playError: 'Could not play {title}',
54
56
  loadError: 'Could not load the sounds.',
55
57
  noSounds: 'No sounds.',
58
+ rowBpm: '{bpm} BPM',
59
+ rowKey: 'key {key}',
60
+ rowDuration: '{duration}',
61
+ keyMajor: '{note} major',
62
+ keyMinor: '{note} minor',
63
+ noteSharp: '{note} sharp',
64
+ noteFlat: '{note} flat',
65
+ listSeparator: ', ',
56
66
  };
57
67
 
58
68
  /** The label each sort order shows in the Sort menu. */
@@ -99,3 +109,45 @@ export function countText(shown: number, total: number, strings: typeof DEFAULT_
99
109
  if (shown !== total) return fill(strings.countFiltered, {count: shown, total});
100
110
  return total === 1 ? strings.countOne : fill(strings.count, {count: total});
101
111
  }
112
+
113
+ /**
114
+ * A key as a screen reader should say it: "Bm" → "B minor", "F#" → "F
115
+ * sharp major" (a bare "F#m" is read "F number m"). A label that isn't a
116
+ * key is said as written.
117
+ *
118
+ * @param key - A normalised key.
119
+ * @param strings
120
+ */
121
+ export function spokenKey(key: string, strings: WaveformSoundsStrings = DEFAULT_STRINGS): string {
122
+ const k = parseKey(key);
123
+ if (!k) return key;
124
+ const letter = k.root[0], acc = k.root.slice(1);
125
+ const note = acc === '#' ? fill(strings.noteSharp, {note: letter}) : acc === 'b' ? fill(strings.noteFlat, {note: letter}) : letter;
126
+ return fill(k.minor ? strings.keyMinor : strings.keyMajor, {note});
127
+ }
128
+
129
+ /**
130
+ * What a row's cells say, for a screen reader: the visible cells read "Bass
131
+ * loops 130 Bm 0:07"; this reads "Bass loops, 130 BPM, key B minor, 0:07"
132
+ * (and ", Loop" for a loop). Only the columns the row shows, only the
133
+ * values it has. Since 2.2.0.
134
+ *
135
+ * @param sound
136
+ * @param columns - The row's columns, in order.
137
+ * @param strings
138
+ * @returns '' when there is nothing to say.
139
+ */
140
+ export function rowSummary(sound: Sound, columns: SoundsColumn[], strings: WaveformSoundsStrings = DEFAULT_STRINGS): string {
141
+ const parts: string[] = [];
142
+ for (const c of columns) {
143
+ if (c === 'type' && sound.type) parts.push(sound.type);
144
+ else if (c === 'bpm' && sound.bpm != null) parts.push(fill(strings.rowBpm, {bpm: sound.bpm}));
145
+ else if (c === 'key' && sound.key) parts.push(fill(strings.rowKey, {key: spokenKey(sound.key, strings)}));
146
+ else if (c === 'duration') {
147
+ const d = formatDuration(sound.duration);
148
+ if (d) parts.push(fill(strings.rowDuration, {duration: d}));
149
+ }
150
+ }
151
+ if (sound.loop) parts.push(strings.isLoop);
152
+ return parts.join(strings.listSeparator);
153
+ }
package/src/js/types.ts CHANGED
@@ -148,6 +148,22 @@ export interface WaveformSoundsStrings {
148
148
  loadError: string;
149
149
  /** The empty state of a list with no sounds at all. Since 2.1.0. */
150
150
  noSounds: string;
151
+ /** A row's BPM, read out: `{bpm}` ("130 BPM"). Since 2.2.0. */
152
+ rowBpm: string;
153
+ /** A row's key, read out: `{key}`, spoken ("key B minor"). Since 2.2.0. */
154
+ rowKey: string;
155
+ /** A row's length, read out: `{duration}` ("0:07"). Since 2.2.0. */
156
+ rowDuration: string;
157
+ /** A major key, spoken: `{note}` ("F sharp major"). Since 2.2.0. */
158
+ keyMajor: string;
159
+ /** A minor key, spoken: `{note}` ("B minor"). Since 2.2.0. */
160
+ keyMinor: string;
161
+ /** A sharp note, spoken: `{note}` is the letter ("F sharp"). Since 2.2.0. */
162
+ noteSharp: string;
163
+ /** A flat note, spoken: `{note}` is the letter ("B flat"). Since 2.2.0. */
164
+ noteFlat: string;
165
+ /** Between the parts of a row's read-out (", "). Since 2.2.0. */
166
+ listSeparator: string;
151
167
  }
152
168
 
153
169
  export interface WaveformSoundsOptions {
@@ -198,6 +214,14 @@ export interface WaveformSoundsOptions {
198
214
  pageSize?: number;
199
215
  /** Columns after the title, in order. Default all four. */
200
216
  columns?: SoundsColumn[];
217
+ /** Enharmonic keys are one key: A#m and Bbm (C# and Db, …) are one
218
+ * entry in the key menu, a filter on either finds both, and the address
219
+ * accepts either spelling. The entry shows the spelling the list uses
220
+ * most (a tie: the conventional one — Db, Eb, F#, Ab, Bb major; C#m,
221
+ * Ebm, F#m, G#m, Bbm minor); each row still shows its key as written.
222
+ * `false` keeps every spelling apart. As markup:
223
+ * `data-merge-enharmonic-keys="false"`. Default true. Since 2.2.0. */
224
+ mergeEnharmonicKeys?: boolean;
201
225
  /** Row waveform style. Default `'mirror'`. */
202
226
  waveformStyle?: 'mirror' | 'bars';
203
227
  /** Row waveform colour. Default: CSS `--ws-wave-color`. */
@@ -25,10 +25,10 @@
25
25
  *
26
26
  * @module core
27
27
  */
28
- import { facets, formatDuration, matches, normalizeSounds, parseManifest, sortSounds } from '../data/sounds.js';
28
+ import { facets, formatDuration, matches, normalizeKey, normalizeSounds, parseManifest, sortSounds } from '../data/sounds.js';
29
29
  import { DEFAULT_OPTIONS } from './options.js';
30
- import { renderSounds } from '../render/markup.js';
31
- import type { decodePeaks, encodePeaks, normalizeKey } from '../data/sounds.js';
30
+ import type { renderSounds } from '../render/markup.js';
31
+ import type { decodePeaks, encodePeaks } from '../data/sounds.js';
32
32
  import type { WaveformPlayer } from '@arraypress/waveform-player';
33
33
  import type { Sound, SoundsFilter, SoundsSort, WaveformSoundsInstanceEventMap, WaveformSoundsOptions, WaveformSoundsStrings } from '../types.js';
34
34
  export { DEFAULT_OPTIONS };
@@ -1 +1 @@
1
- {"version":3,"file":"WaveformSounds.d.ts","sourceRoot":"","sources":["../../src/js/core/WaveformSounds.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"WaveformSounds.d.ts","sourceRoot":"","sources":["../../src/js/core/WaveformSounds.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/js/core/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,eAAe,EAAC,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAC,eAAe,EAAC,CAAC;AAEzB,sCAAsC;AACtC,eAAO,MAAM,eAAe,EAAE,qBAyB7B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAIxE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAIrF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAQlG;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA6BpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOxG"}
1
+ {"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/js/core/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,eAAe,EAAC,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAC,eAAe,EAAC,CAAC;AAEzB,sCAAsC;AACtC,eAAO,MAAM,eAAe,EAAE,qBAyB7B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAIxE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAGzE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAIrF;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAQlG;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA8BpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,OAAO,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAOxG"}
@@ -0,0 +1,88 @@
1
+ /**
2
+ * Musical keys beyond their spelling: which keys sound the same
3
+ * (enharmonics: A#m and Bbm), which spelling a merged filter entry shows,
4
+ * and how keys sort. Pure — shared by the renderer and the runtime.
5
+ *
6
+ * Keys arrive here already in the short form `normalizeKey()` writes
7
+ * (`'Fm'`, `'C#'`, `'Bb'`); anything else is a label to keep as given.
8
+ *
9
+ * @module keys
10
+ */
11
+ /** Pitch class of each root spelling, C = 0. The theoretical spellings
12
+ * (Cb, B#, E#, Fb) are here so they merge with the keys they sound as. */
13
+ export declare const KEY_PITCH: Record<string, number>;
14
+ /**
15
+ * A key's parts: its root spelling, pitch class and mode.
16
+ *
17
+ * @param key - A normalised key (`'A#m'`).
18
+ * @returns null for a label that isn't a key.
19
+ */
20
+ export declare function parseKey(key: string | null | undefined): {
21
+ root: string;
22
+ pitch: number;
23
+ minor: boolean;
24
+ } | null;
25
+ /**
26
+ * What a key sounds as: pitch class and mode (`'10m'` for A#m and Bbm).
27
+ * Two keys are enharmonic when their classes match.
28
+ *
29
+ * @param key - A normalised key.
30
+ * @returns The class, or the label itself when it isn't a key (so it only
31
+ * ever matches itself).
32
+ */
33
+ export declare function keyClass(key: string): string;
34
+ /**
35
+ * Is a sound in key `b` (the filter's) when it is written `a`? The same
36
+ * spelling always is; with `merge`, so is any enharmonic one.
37
+ *
38
+ * @param a - The sound's key.
39
+ * @param b - The filter's key.
40
+ * @param merge - Treat enharmonic spellings as one key.
41
+ */
42
+ export declare function sameKey(a: string, b: string, merge?: boolean): boolean;
43
+ /**
44
+ * Sort rank of a key: by pitch from C, majors before minors; unknown
45
+ * labels after every key, no key at all last.
46
+ *
47
+ * @param key
48
+ */
49
+ export declare function keyRank(key: string): number;
50
+ /**
51
+ * Every common spelling of a key (`'A#m'` → `['A#m', 'Bbm']`), for search:
52
+ * typing either finds both when keys are merged.
53
+ *
54
+ * @param key
55
+ */
56
+ export declare function enharmonics(key: string): string[];
57
+ /**
58
+ * The spelling a merged key entry shows: the one the pack uses most; a
59
+ * tie goes to the conventional spelling (see {@link CONVENTIONAL_MAJOR})
60
+ * when it is one of the tied, else to the first in alphabetical order.
61
+ *
62
+ * @param counts - Each spelling of ONE key, with how many sounds use it.
63
+ */
64
+ export declare function canonicalSpelling(counts: Map<string, number>): string;
65
+ /**
66
+ * The keys a list offers, merged or not: each entry once, in musical
67
+ * order, with the other spellings merged into it.
68
+ *
69
+ * @param keys - Every sound's key ('' for none), duplicates included.
70
+ * @param merge - Merge enharmonic spellings into one entry.
71
+ * @returns `keys` (the entries) and `aliases` (entry → the other spellings
72
+ * the list uses for it; only entries that have some).
73
+ */
74
+ export declare function keyEntries(keys: string[], merge?: boolean): {
75
+ keys: string[];
76
+ aliases: Record<string, string[]>;
77
+ };
78
+ /**
79
+ * The entry of `entries` a key belongs to: itself, or with `merge` the
80
+ * entry it is enharmonic to (`?key=A#m` on a list whose entry is Bbm).
81
+ *
82
+ * @param key - A normalised key.
83
+ * @param entries - The list's key entries ({@link keyEntries}).
84
+ * @param merge
85
+ * @returns The entry, or '' when the list has no such key.
86
+ */
87
+ export declare function keyEntry(key: string, entries: string[], merge?: boolean): string;
88
+ //# sourceMappingURL=keys.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/js/data/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;2EAC2E;AAC3E,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG5C,CAAC;AAeF;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAC,GAAG,IAAI,CAI7G;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG5C;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,OAAc,GAAG,OAAO,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI3C;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAQrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,GAAE,OAAc,GAAG;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CAAC,CAmBrH;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,GAAE,OAAc,GAAG,MAAM,CAMtF"}
@@ -40,17 +40,35 @@ export declare const SEEK_END = 0.999;
40
40
  */
41
41
  export declare function sliderEdgeTarget(key: string): number | null;
42
42
  /**
43
- * Which of the matching sounds the current page shows, and how many more
44
- * "Show more" would reveal.
43
+ * Rows are rendered as they are revealed, never all up front: a page's
44
+ * worth, or with paging off this many at a time, more as the list
45
+ * scrolls toward its end. Since 2.2.0.
46
+ */
47
+ export declare const RENDER_CHUNK = 50;
48
+ /**
49
+ * How many of the matching sounds have rows: the page, or with paging off
50
+ * the rows rendered so far (`budget`). The server renders the first of
51
+ * these ({@link firstRender}).
52
+ *
53
+ * @param matching - How many sounds match.
54
+ * @param limit - The page limit (Infinity when paging is off).
55
+ * @param budget - Rows rendered so far when paging is off.
56
+ */
57
+ export declare function renderedCount(matching: number, limit: number, budget: number): number;
58
+ /**
59
+ * How many rows a list starts with: a page, or with paging off
60
+ * {@link RENDER_CHUNK}.
61
+ *
62
+ * @param pageSize - The `pageSize` option (0 = paging off).
63
+ */
64
+ export declare function firstRender(pageSize: number): number;
65
+ /**
66
+ * The budget that renders position `pos` with paging off: whole chunks.
45
67
  *
46
- * @template T
47
- * @param shown - The sounds that match, in display order.
48
- * @param limit - How many to show (Infinity for all).
68
+ * @param budget - Rows rendered so far.
69
+ * @param pos - The position that must have a row.
49
70
  */
50
- export declare function pageWindow<T>(shown: T[], limit: number): {
51
- visible: Set<T>;
52
- remaining: number;
53
- };
71
+ export declare function budgetToReveal(budget: number, pos: number): number;
54
72
  /**
55
73
  * The page limit that reveals position `pos` (used when playing past the
56
74
  * end of the current page, e.g. by `next()` or auto-advance).
@@ -1 +1 @@
1
- {"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/js/data/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,oDAAoD;AACpD,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAS1F;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvE;AAED;wDACwD;AACxD,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAE9B;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG;IAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,CAG7F;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE"}
1
+ {"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/js/data/navigation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,oDAAoD;AACpD,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAS1F;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvE;AAED;wDACwD;AACxD,eAAO,MAAM,QAAQ,QAAQ,CAAC;AAE9B;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3D;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE"}