@arraypress/waveform-sounds 0.3.0 → 2.0.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 (81) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +19 -1
  3. package/dist/waveform-sounds-no-autoinit.esm.js +145 -98
  4. package/dist/waveform-sounds-render.esm.js +25 -11
  5. package/dist/waveform-sounds.css +66 -78
  6. package/dist/waveform-sounds.esm.js +146 -99
  7. package/dist/waveform-sounds.js +147 -99
  8. package/dist/waveform-sounds.min.css +1 -1
  9. package/dist/waveform-sounds.min.js +1 -1
  10. package/package.json +36 -33
  11. package/src/css/waveform-sounds.css +66 -78
  12. package/src/js/core/{WaveformSounds.js → WaveformSounds.ts} +328 -189
  13. package/src/js/core/engine.ts +101 -0
  14. package/src/js/core/{options.js → options.ts} +33 -28
  15. package/src/js/data/{bpm.js → bpm.ts} +17 -17
  16. package/src/js/data/{navigation.js → navigation.ts} +17 -17
  17. package/src/js/data/{sounds.js → sounds.ts} +67 -63
  18. package/src/js/data/{url-state.js → url-state.ts} +27 -26
  19. package/src/js/dom/{colors.js → colors.ts} +12 -12
  20. package/src/js/dom/{draw.js → draw.ts} +17 -17
  21. package/src/js/dom/{menus.js → menus.ts} +72 -55
  22. package/src/js/dom/{rows.js → rows.ts} +18 -17
  23. package/src/js/{entry.js → entry.ts} +25 -0
  24. package/src/js/render/{html.js → html.ts} +18 -12
  25. package/src/js/render/{icons.js → icons.ts} +4 -4
  26. package/src/js/render/{markup.js → markup.ts} +82 -60
  27. package/src/js/render/{options.js → options.ts} +26 -20
  28. package/src/js/render/{strings.js → strings.ts} +17 -16
  29. package/src/js/{render-entry.js → render-entry.ts} +1 -0
  30. package/src/js/shared/{utils.js → utils.ts} +22 -22
  31. package/{index.d.ts → src/js/types.ts} +12 -87
  32. package/types/core/WaveformSounds.d.ts +145 -0
  33. package/types/core/WaveformSounds.d.ts.map +1 -0
  34. package/types/core/engine.d.ts +67 -0
  35. package/types/core/engine.d.ts.map +1 -0
  36. package/types/core/options.d.ts +76 -0
  37. package/types/core/options.d.ts.map +1 -0
  38. package/types/data/bpm.d.ts +67 -0
  39. package/types/data/bpm.d.ts.map +1 -0
  40. package/types/data/navigation.d.ts +53 -0
  41. package/types/data/navigation.d.ts.map +1 -0
  42. package/types/data/sounds.d.ts +167 -0
  43. package/types/data/sounds.d.ts.map +1 -0
  44. package/types/data/url-state.d.ts +83 -0
  45. package/types/data/url-state.d.ts.map +1 -0
  46. package/types/dom/colors.d.ts +35 -0
  47. package/types/dom/colors.d.ts.map +1 -0
  48. package/types/dom/draw.d.ts +73 -0
  49. package/types/dom/draw.d.ts.map +1 -0
  50. package/types/dom/menus.d.ts +77 -0
  51. package/types/dom/menus.d.ts.map +1 -0
  52. package/types/dom/rows.d.ts +42 -0
  53. package/types/dom/rows.d.ts.map +1 -0
  54. package/types/entry.d.ts +22 -0
  55. package/types/entry.d.ts.map +1 -0
  56. package/types/index.d.ts +16 -0
  57. package/types/index.d.ts.map +1 -0
  58. package/types/render/html.d.ts +39 -0
  59. package/types/render/html.d.ts.map +1 -0
  60. package/types/render/icons.d.ts +17 -0
  61. package/types/render/icons.d.ts.map +1 -0
  62. package/types/render/markup.d.ts +132 -0
  63. package/types/render/markup.d.ts.map +1 -0
  64. package/types/render/options.d.ts +56 -0
  65. package/types/render/options.d.ts.map +1 -0
  66. package/types/render/strings.d.ts +46 -0
  67. package/types/render/strings.d.ts.map +1 -0
  68. package/types/render-entry.d.ts +8 -0
  69. package/types/render-entry.d.ts.map +1 -0
  70. package/types/shared/utils.d.ts +57 -0
  71. package/types/shared/utils.d.ts.map +1 -0
  72. package/types/types.d.ts +254 -0
  73. package/types/types.d.ts.map +1 -0
  74. package/types/vendor/arraypress-text.d.ts +250 -0
  75. package/dist/waveform-sounds-no-autoinit.cjs +0 -2136
  76. package/dist/waveform-sounds-render.cjs +0 -614
  77. package/dist/waveform-sounds.cjs +0 -2158
  78. package/no-autoinit.d.ts +0 -2
  79. package/render.d.ts +0 -5
  80. package/src/js/core/engine.js +0 -57
  81. /package/src/js/{index.js → index.ts} +0 -0
@@ -0,0 +1,145 @@
1
+ /**
2
+ * WaveformSounds — a searchable, filterable list of sounds for showcasing
3
+ * the previews inside a sample pack, preset bank or sound library.
4
+ *
5
+ * One `WaveformPlayer` (self mode) is the audio engine for the whole list:
6
+ * every sound plays through it, so it brings the player's seeking (incl.
7
+ * hosts that ignore byte ranges), error handling, Media Session card and
8
+ * hand-off with every other player on the page. The rows are light: a
9
+ * button, some text and, in the `inline` layout, a small canvas drawn from
10
+ * low-resolution peaks only when it scrolls into view. 300 sounds is 300
11
+ * rows, not 300 players.
12
+ *
13
+ * Layouts (`player`):
14
+ * - `'inline'` (default): every row has a mini waveform; the playing row
15
+ * fills with progress and is click-to-seek. The engine is hidden.
16
+ * - `'strip'`: plain rows; the engine is shown docked under the list as a
17
+ * full player for the current sound.
18
+ *
19
+ * This class orchestrates; the pieces live by layer:
20
+ * - `core/` — this class, the engine's configuration, the option surface
21
+ * - `data/` — pure logic: sounds, filtering, the address, navigation
22
+ * - `render/` — server-safe markup (also the `/render` entry)
23
+ * - `dom/` — browser-only behaviour: dropdowns, rows, canvas, colours
24
+ * - `shared/` — small helpers
25
+ *
26
+ * @module core
27
+ */
28
+ import { facets, matches, normalizeSounds, parseManifest, sortSounds } from '../data/sounds.js';
29
+ import { DEFAULT_OPTIONS } from './options.js';
30
+ import { renderSounds } from '../render/markup.js';
31
+ import type { decodePeaks, encodePeaks, formatDuration, normalizeKey } from '../data/sounds.js';
32
+ import type { Sound, SoundsFilter, SoundsSort, WaveformSoundsOptions, WaveformSoundsStrings } from '../types.js';
33
+ export { DEFAULT_OPTIONS };
34
+ export declare class WaveformSounds {
35
+ /** Every live instance, by its element. */
36
+ static instances: Map<Element, WaveformSounds>;
37
+ /** The pure helpers, for `<script>` users (attached in `entry.ts`). */
38
+ static utils: {
39
+ encodePeaks: typeof encodePeaks;
40
+ decodePeaks: typeof decodePeaks;
41
+ normalizeKey: typeof normalizeKey;
42
+ normalizeSounds: typeof normalizeSounds;
43
+ parseManifest: typeof parseManifest;
44
+ facets: typeof facets;
45
+ matches: typeof matches;
46
+ sortSounds: typeof sortSounds;
47
+ formatDuration: typeof formatDuration;
48
+ renderSounds: typeof renderSounds;
49
+ };
50
+ /** Every option with its default (attached in `entry.ts`). */
51
+ static DEFAULT_OPTIONS: WaveformSoundsOptions;
52
+ /** The English UI strings (attached in `entry.ts`). */
53
+ static DEFAULT_STRINGS: WaveformSoundsStrings;
54
+ readonly container: HTMLElement;
55
+ readonly options: Required<WaveformSoundsOptions>;
56
+ /** Resolves once the list is built (after a manifest fetch, if any).
57
+ * The build always happens after the constructor returns, so listeners
58
+ * attached straight after `new WaveformSounds()` see `ready`. It never
59
+ * rejects: a failed build (e.g. the manifest 404s) resolves it too and
60
+ * is reported through `onError` / `waveformsounds:error`. Calls made
61
+ * before it resolves are honoured: `setFilter`/`setSort` show in the
62
+ * controls once built, and `play()` waits for the list. */
63
+ readonly ready: Promise<void>;
64
+ readonly sounds: Sound[];
65
+ readonly filter: SoundsFilter;
66
+ readonly sortBy: SoundsSort;
67
+ readonly playing: boolean;
68
+ /** The engine `WaveformPlayer`, created on first play. */
69
+ readonly engine: unknown;
70
+ /**
71
+ * @param {HTMLElement|string} container - The element (or a selector).
72
+ * @param {WaveformSoundsOptions} [options]
73
+ */
74
+ constructor(container: HTMLElement | string, options?: WaveformSoundsOptions);
75
+ /** The sounds that pass the filter, in the current sort order. */
76
+ get visible(): Sound[];
77
+ /**
78
+ * Change the filter (merged into the current one) and re-apply. Back to
79
+ * the first page.
80
+ *
81
+ * @param patch
82
+ */
83
+ setFilter(patch: Partial<SoundsFilter>): void;
84
+ /** Reset every filter (the sort stays). */
85
+ clearFilters(): void;
86
+ /** @param by */
87
+ setSort(by: SoundsSort): void;
88
+ /** Reveal the next page of results. */
89
+ showMore(): void;
90
+ /**
91
+ * Play a sound (by index, id or sound object), or resume the current
92
+ * one. Before the list is built the call waits for it.
93
+ *
94
+ * @param target
95
+ * @param opts - `at`: start position 0..1.
96
+ */
97
+ play(target?: number | string | Sound, opts?: {
98
+ at?: number;
99
+ }): void;
100
+ /** Pause the current sound. */
101
+ pause(): void;
102
+ /**
103
+ * The current sound plays/pauses; another sound starts.
104
+ * @param target
105
+ */
106
+ toggle(target?: number | string | Sound): void;
107
+ /** Play the next visible sound (no wrap at the end). */
108
+ next(): void;
109
+ /** Play the previous visible sound. */
110
+ previous(): void;
111
+ /**
112
+ * Loop the current sound (auditioning a loop is the common case). When
113
+ * the list marks its loops (`loop: true` on any sound), only those
114
+ * repeat: a one-shot always plays once.
115
+ * @param on
116
+ */
117
+ setLoop(on: boolean): void;
118
+ /** The sound playing (or paused) now, or null. */
119
+ get current(): Sound | null;
120
+ /**
121
+ * Tear down: listeners, observers, timers and the engine. Markup this
122
+ * instance rendered is restored to what the container held before.
123
+ * ADOPTED (server-rendered) markup is left as it is now — rows may be
124
+ * re-sorted, hidden or marked current — so to start again, re-render it
125
+ * rather than constructing a new instance over it.
126
+ */
127
+ destroy(): void;
128
+ /**
129
+ * Initialise every `[data-waveform-sounds]` under `root` that isn't yet.
130
+ *
131
+ * @param root
132
+ * @returns The new instances.
133
+ */
134
+ static init(root?: ParentNode): WaveformSounds[];
135
+ /**
136
+ * The instance on an element (or selector), if any.
137
+ * @param el
138
+ * @returns
139
+ */
140
+ static getInstance(el: Element | string): WaveformSounds | null;
141
+ /** Destroy instances whose element has left the document (after a
142
+ * client-side navigation). */
143
+ static prune(): void;
144
+ }
145
+ //# sourceMappingURL=WaveformSounds.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"WaveformSounds.d.ts","sourceRoot":"","sources":["../../src/js/core/WaveformSounds.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,67 @@
1
+ /**
2
+ * The audio engine: ONE `WaveformPlayer` (self mode) that every sound in
3
+ * the list plays through. These helpers decide how it's configured and
4
+ * what it's given per sound; `WaveformSounds.js` owns its lifecycle.
5
+ *
6
+ * @module engine
7
+ */
8
+ /**
9
+ * The engine player's options. The site's `playerOptions` override the
10
+ * defaults, except what the list depends on:
11
+ * - `audioMode` is always `'self'` (the list owns its audio);
12
+ * - `loop` and `showLoop` are always off: the list owns looping (its Loop
13
+ * toggle, which repeats only the sounds marked as loops). The player's
14
+ * own loop would stop `ended`, so `autoAdvance` and the row state would
15
+ * stall, and its toggle would loop one-shots behind the list's back;
16
+ * - the per-track options (`duration`, `downloadUrl`, `downloadName`) are
17
+ * dropped: each sound's come with it (see {@link engineTrack});
18
+ * - the six callbacks always reach the list — a site's own callback of
19
+ * the same name runs as well, after it, with the same arguments.
20
+ *
21
+ * @param user - The site's `playerOptions`.
22
+ * @param layout - Strip shows the engine, so it's taller.
23
+ * @param handlers - The list's callbacks, keyed by
24
+ * option name (`onPlay`, …).
25
+ * @returns Options for `new WaveformPlayer(el, options)`.
26
+ */
27
+ export declare function engineOptions(user: Record<string, any> | null | undefined, layout: 'inline' | 'strip', handlers: Record<string, (...args: any[]) => void>): Record<string, any>;
28
+ /**
29
+ * The waveform data to hand the engine for a sound: in the strip a
30
+ * full-resolution sidecar when there is one, otherwise the row's peaks.
31
+ * Supplied peaks also stop a hidden engine from downloading and decoding
32
+ * the whole file just to draw it.
33
+ *
34
+ * @param sound
35
+ * @param layout
36
+ * @returns
37
+ */
38
+ export declare function enginePeaks(sound: {
39
+ peaks: number[] | null;
40
+ waveform: string | null;
41
+ }, layout: 'inline' | 'strip'): number[] | string | null;
42
+ /** What `loadTrack()` is given for one sound (see {@link engineTrack}). */
43
+ export interface EngineTrack {
44
+ waveform: number[] | string | null;
45
+ autoplay: boolean;
46
+ duration?: number;
47
+ downloadUrl?: string;
48
+ }
49
+ /**
50
+ * The `loadTrack()` options for a sound: its peaks (see {@link enginePeaks}),
51
+ * its known length — so the player shows the right total, places a seek and
52
+ * fills the Media Session scrubber before the audio's metadata arrives,
53
+ * which with `preload: 'none'` is only once it plays — and its download
54
+ * link, so a `showDownload` engine offers what the row offers.
55
+ *
56
+ * @param sound
57
+ * @param layout
58
+ * @param autoplay - Start once loaded (false: cue only).
59
+ * @returns
60
+ */
61
+ export declare function engineTrack(sound: {
62
+ peaks: number[] | null;
63
+ waveform: string | null;
64
+ duration: number | null;
65
+ download: string | null;
66
+ }, layout: 'inline' | 'strip', autoplay: boolean): EngineTrack;
67
+ //# sourceMappingURL=engine.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/js/core/engine.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqB/K;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAC,KAAK,EAAE,MAAM,EAAE,GAAC,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAC,IAAI,CAAA;CAAC,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAEtI;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IACxB,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE;IAAC,KAAK,EAAE,MAAM,EAAE,GAAC,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAC,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAC,IAAI,CAAA;CAAC,EAAE,MAAM,EAAE,QAAQ,GAAG,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,WAAW,CAK1L"}
@@ -0,0 +1,76 @@
1
+ /**
2
+ * The runtime's option surface: every option with its default, the
3
+ * `data-*` form a container (or a server-rendering wrapper) uses, and the
4
+ * merge that resolves them. The options that shape the markup are defined
5
+ * with the renderer (`render/options.ts`) and included here. `types.ts`
6
+ * documents each option; the wrappers' drift guards compare their
7
+ * forwarding against `WaveformSoundsOptions` (in the generated
8
+ * `types/types.d.ts`).
9
+ *
10
+ * Precedence, as across the waveform family: data-* > constructor > default.
11
+ *
12
+ * @module options
13
+ */
14
+ import { RENDER_DEFAULTS } from '../render/options.js';
15
+ import type { WaveformSoundsOptions } from '../types.js';
16
+ export { RENDER_DEFAULTS };
17
+ /** Every option, with its default. */
18
+ export declare const DEFAULT_OPTIONS: WaveformSoundsOptions;
19
+ /**
20
+ * A boolean attribute: present-and-empty or "true" → true, "false" → false.
21
+ *
22
+ * @param value
23
+ * @returns undefined for anything else (not set).
24
+ */
25
+ export declare function parseBool(value: string | undefined): boolean | undefined;
26
+ /**
27
+ * A comma list attribute ("type, key" → ['type', 'key']). An empty string
28
+ * is an empty list (e.g. `data-sorts=""` = no sort menu).
29
+ *
30
+ * @param value
31
+ * @returns
32
+ */
33
+ export declare function parseList(value: string | undefined): string[] | undefined;
34
+ /**
35
+ * A number attribute; an empty string is "not set".
36
+ *
37
+ * @param value
38
+ * @returns
39
+ */
40
+ export declare function parseNumber(value: string | undefined): number | undefined;
41
+ /**
42
+ * `data-url-state`: "true"/empty → true, "false" → false, anything else is
43
+ * the parameter prefix.
44
+ *
45
+ * @param value
46
+ * @returns
47
+ */
48
+ export declare function parseUrlState(value: string | undefined): boolean | string | undefined;
49
+ /**
50
+ * A JSON attribute (`data-strings`, `data-player-options`). Invalid JSON is
51
+ * reported and ignored, never thrown: a typo in markup must not take the
52
+ * whole list down.
53
+ *
54
+ * @param value
55
+ * @param name - The attribute name, for the warning.
56
+ * @returns
57
+ */
58
+ export declare function parseJson(value: string | undefined, name: string): Record<string, any> | undefined;
59
+ /**
60
+ * The options set on a container as `data-*` attributes (kebab-case:
61
+ * `data-page-size` → `pageSize`). Attributes that are absent (or unusable)
62
+ * are left out, so they never override a constructor option.
63
+ *
64
+ * @param el
65
+ * @returns The options found.
66
+ */
67
+ export declare function readDataOptions(el: HTMLElement): Record<string, any>;
68
+ /**
69
+ * Merge option sources: later ones win, and null/undefined never
70
+ * overwrite (an unset prop must not erase a default).
71
+ *
72
+ * @param sources
73
+ * @returns
74
+ */
75
+ export declare function mergeOptions(...sources: (Record<string, any> | null | undefined)[]): Record<string, any>;
76
+ //# sourceMappingURL=options.d.ts.map
@@ -0,0 +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;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAGzE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAIrF;AAED;;;;;;;;GAQG;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;;;;;;GAMG;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,67 @@
1
+ /**
2
+ * The BPM range control's arithmetic: between the two slider handles and the
3
+ * filter, and the label its menu button shows. Pure, so the server renderer
4
+ * and the runtime agree.
5
+ *
6
+ * A handle resting at an END of the pack's range is "no limit on that side",
7
+ * not a limit at that value: sounds with no BPM are hidden by any BPM filter,
8
+ * so a slider left wide open must not filter at all.
9
+ *
10
+ * @module bpm
11
+ */
12
+ /**
13
+ * The filter for a pair of handle positions.
14
+ *
15
+ * @param lo - The lower handle.
16
+ * @param hi - The upper handle.
17
+ * @param extent - The pack's BPM range (`facets().bpm`).
18
+ * @returns `''` for an open end.
19
+ */
20
+ export declare function bpmFilterFromRange(lo: number, hi: number, extent: {
21
+ min: number;
22
+ max: number;
23
+ }): {
24
+ bpmMin: string;
25
+ bpmMax: string;
26
+ };
27
+ /**
28
+ * Where the handles sit for a filter: an open end at the pack's own end, a
29
+ * set one at its value (clamped into the pack's range, so a link with
30
+ * `?bpm=60-300` still shows sensible handles).
31
+ *
32
+ * @param filter
33
+ * @param extent
34
+ * @returns
35
+ */
36
+ export declare function bpmRangeFromFilter(filter: {
37
+ bpmMin?: string | number;
38
+ bpmMax?: string | number;
39
+ }, extent: {
40
+ min: number;
41
+ max: number;
42
+ }): {
43
+ lo: number;
44
+ hi: number;
45
+ };
46
+ /**
47
+ * A handle's position along the track, 0..1.
48
+ *
49
+ * @param value
50
+ * @param extent
51
+ * @returns
52
+ */
53
+ export declare function bpmFraction(value: number, extent: {
54
+ min: number;
55
+ max: number;
56
+ }): number;
57
+ /**
58
+ * Is a BPM limit set on either side?
59
+ *
60
+ * @param filter
61
+ * @returns
62
+ */
63
+ export declare function hasBpmFilter(filter: {
64
+ bpmMin?: string | number;
65
+ bpmMax?: string | number;
66
+ }): boolean;
67
+ //# sourceMappingURL=bpm.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bpm.d.ts","sourceRoot":"","sources":["../../src/js/data/bpm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GAAG;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAM/H;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IAAC,MAAM,CAAC,EAAE,MAAM,GAAC,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAC,MAAM,CAAA;CAAC,EAAE,MAAM,EAAE;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GAAG;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,CAQzJ;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GAAG,MAAM,CAGrF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAC,MAAM,CAAC,EAAE,MAAM,GAAC,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAC,MAAM,CAAA;CAAC,GAAG,OAAO,CAE9F"}
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Moving through the list: which row a key lands on, how far an arrow
3
+ * seeks, and which rows the current page shows. Pure — the runtime maps
4
+ * the results onto rows and the engine.
5
+ *
6
+ * @module navigation
7
+ */
8
+ /** How far ←/→ seek, as a fraction of the sound. */
9
+ export declare const SEEK_STEP = 0.1;
10
+ /**
11
+ * Where a navigation key moves from position `at` in a list of `count`
12
+ * visible rows.
13
+ *
14
+ * @param key - `KeyboardEvent.key`.
15
+ * @param at - The focused row's position among the visible rows.
16
+ * @param count - How many rows are visible.
17
+ * @returns The new position; `'search'` for ↑ on
18
+ * the first row (back to the search field); null when the key isn't a
19
+ * move or there is nowhere to go.
20
+ */
21
+ export declare function rowTarget(key: string, at: number, count: number): number | 'search' | null;
22
+ /**
23
+ * The position an ←/→ press seeks to. Stops just short of the end, so a
24
+ * held → can't end the sound by accident.
25
+ *
26
+ * @param progress - Current position, 0..1.
27
+ * @param key - `'ArrowRight'` or `'ArrowLeft'`.
28
+ * @returns The new position, or null for any other key.
29
+ */
30
+ export declare function seekTarget(progress: number, key: string): number | null;
31
+ /**
32
+ * Which of the matching sounds the current page shows, and how many more
33
+ * "Show more" would reveal.
34
+ *
35
+ * @template T
36
+ * @param shown - The sounds that match, in display order.
37
+ * @param limit - How many to show (Infinity for all).
38
+ * @returns
39
+ */
40
+ export declare function pageWindow<T>(shown: T[], limit: number): {
41
+ visible: Set<T>;
42
+ remaining: number;
43
+ };
44
+ /**
45
+ * The page limit that reveals position `pos` (used when playing past the
46
+ * end of the current page, e.g. by `next()` or auto-advance).
47
+ *
48
+ * @param limit - The current limit.
49
+ * @param pos - The position that must be visible.
50
+ * @returns
51
+ */
52
+ export declare function limitToReveal(limit: number, pos: number): number;
53
+ //# sourceMappingURL=navigation.d.ts.map
@@ -0,0 +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;;;;;;;;GAQG;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;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE"}
@@ -0,0 +1,167 @@
1
+ import type { Sound, SoundInput, SoundsFilter, SoundsManifest, SoundsSort } from '../types.js';
2
+ /**
3
+ * Pure data helpers: no DOM, no window. Shared by the browser runtime and
4
+ * the server renderer (`@arraypress/waveform-sounds/render`), so a wrapper
5
+ * that renders the list on the server produces exactly what the client
6
+ * would.
7
+ *
8
+ * @module data
9
+ */
10
+ /**
11
+ * Peaks travel as an 8-bit hex string, two characters per bar ("00"–"ff").
12
+ * A sound browser draws ~48–64 bars per row, so that is ~100 characters a
13
+ * sound: 300 sounds is ~30 KB in a manifest or in row attributes, against
14
+ * ~3x that as a JSON number array.
15
+ *
16
+ * @param peaks - Values 0..1.
17
+ * @returns Hex string.
18
+ */
19
+ export declare function encodePeaks(peaks: number[]): string;
20
+ /**
21
+ * Decode peaks from any accepted form into numbers 0..1.
22
+ *
23
+ * Accepts the hex string from {@link encodePeaks}, an array of 0..1
24
+ * numbers, or an array of integers on a larger scale (e.g. 0..100 or
25
+ * 0..255) together with that `scale`.
26
+ *
27
+ * @param value
28
+ * @param scale - The maximum of an integer array.
29
+ * @returns Peaks, or null when there are none.
30
+ */
31
+ export declare function decodePeaks(value: string | number[] | null | undefined, scale?: number): number[] | null;
32
+ /**
33
+ * Normalise a musical key to a short canonical form: root, accidental
34
+ * (`#` or `b`), and `m` for minor. "F minor", "Fmin", "f m" → "Fm";
35
+ * "C# Major", "C♯" → "C#". Anything unparseable comes back trimmed, as
36
+ * given, so an unusual label still displays.
37
+ *
38
+ * @param key
39
+ * @returns Canonical key, or '' for none.
40
+ */
41
+ export declare function normalizeKey(key: string | null | undefined): string;
42
+ /**
43
+ * Format seconds as m:ss (whole seconds, rounded down like a player's
44
+ * clock), or as tenths under a second.
45
+ *
46
+ * A one-shot (a kick, a hat) is often shorter than a second, and m:ss would
47
+ * round it to "0:00", which reads as a missing length.
48
+ *
49
+ * @param seconds
50
+ * @returns e.g. "0:08", "0.4s", or '' when unknown.
51
+ */
52
+ export declare function formatDuration(seconds: number | null | undefined): string;
53
+ /**
54
+ * Parse a duration given as seconds (8.02) or as "m:ss" / "h:mm:ss".
55
+ * @param value
56
+ * @returns
57
+ */
58
+ export declare function parseDuration(value: number | string | null | undefined): number | null;
59
+ /**
60
+ * The title a file name implies: extension and separators dropped,
61
+ * leading pack prefixes kept (they are often the label's code).
62
+ * "NW_Bass_Loop_04_128_Fmin.wav" → "NW Bass Loop 04 128 Fmin".
63
+ * @param url
64
+ * @returns
65
+ */
66
+ export declare function titleFromUrl(url: string): string;
67
+ /**
68
+ * Normalise one sound into the shape the runtime and renderer use.
69
+ *
70
+ * @param input - A sound: `{url, title?, type?, bpm?, key?,
71
+ * duration?, tags?, peaks?, waveform?, download?, loop?, id?}`.
72
+ * @param index - Its position (used for a fallback id).
73
+ * @param peakScale - Scale of an integer `peaks` array.
74
+ * @returns The sound, or null if it has
75
+ * no url.
76
+ */
77
+ export declare function normalizeSound(input: Record<string, any>, index: number, peakScale?: number): Sound | null;
78
+ /**
79
+ * The values of the loops-or-one-shots filter. A sound is a loop only when
80
+ * it says so (`loop: true`); everything else is a one-shot.
81
+ */
82
+ export declare const LOOP_FILTERS: string[];
83
+ /**
84
+ * Is this a loop? Only an explicit yes counts: `true`, or `"true"` / `"1"`
85
+ * as an attribute or a CSV-ish manifest writes it. Unset is a one-shot.
86
+ *
87
+ * @param value
88
+ * @returns
89
+ */
90
+ export declare function isLoop(value: unknown): boolean;
91
+ /**
92
+ * Read a sounds manifest. Accepts `{version, peakScale?, sounds: [...]}`
93
+ * (what `waveform-gen --manifest` writes) or a bare array of sounds.
94
+ * Sounds without a url are dropped.
95
+ *
96
+ * @param manifest
97
+ * @returns
98
+ */
99
+ export declare function parseManifest(manifest: SoundsManifest | SoundInput[]): Sound[];
100
+ /**
101
+ * Normalise a list of sounds, dropping invalid ones and de-duplicating ids
102
+ * (a repeated id would make two rows answer to one play() call).
103
+ * @param list
104
+ * @param peakScale
105
+ * @returns
106
+ */
107
+ export declare function normalizeSounds(list: SoundInput[], peakScale?: number): Sound[];
108
+ /**
109
+ * What the filter controls offer, derived from the sounds: each type with
110
+ * its count (in first-seen order), each key (in musical order), the BPM
111
+ * range, and how many are loops and one-shots. A control with nothing to
112
+ * offer is not rendered.
113
+ *
114
+ * @param sounds
115
+ * @returns
116
+ */
117
+ export declare function facets(sounds: Sound[]): {
118
+ types: {
119
+ name: string;
120
+ count: number;
121
+ }[];
122
+ keys: string[];
123
+ bpm: {
124
+ min: number;
125
+ max: number;
126
+ } | null;
127
+ hasDuration: boolean;
128
+ loops: number;
129
+ oneShots: number;
130
+ };
131
+ /**
132
+ * Does a sound match the filter? Every set criterion must hold. `loop` is
133
+ * `'loop'` (loops only), `'one-shot'` (everything else) or empty (both).
134
+ *
135
+ * `query` matches the title, type, key and tags with
136
+ * `@arraypress/text`'s `matchesAll`: every word, in any order, forgiving
137
+ * one typo in words of four letters or more ("drun" finds drum loops). A
138
+ * number in the query also matches the BPM exactly, so "bass 128" finds
139
+ * 128 BPM bass loops.
140
+ *
141
+ * @param sound
142
+ * @param filter
143
+ * @returns
144
+ */
145
+ export declare function matches(sound: Sound, filter?: Partial<SoundsFilter>): boolean;
146
+ /** The sort orders the toolbar offers. */
147
+ export declare const SORTS: SoundsSort[];
148
+ /**
149
+ * The configured sort orders the data can use (no BPM sort without BPMs),
150
+ * in the configured order. Shared by the renderer and the runtime, so the
151
+ * menu and the starting order always agree.
152
+ *
153
+ * @param sorts - The configured orders.
154
+ * @param f - The sounds' facets.
155
+ * @returns
156
+ */
157
+ export declare function availableSorts(sorts: string[], f: ReturnType<typeof facets>): string[];
158
+ /**
159
+ * Sort sounds (returns a new array; `default` keeps the given order).
160
+ * Missing values sort last in every order.
161
+ *
162
+ * @param sounds
163
+ * @param by
164
+ * @returns
165
+ */
166
+ export declare function sortSounds(sounds: Sound[], by?: SoundsSort): Sound[];
167
+ //# sourceMappingURL=sounds.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sounds.d.ts","sourceRoot":"","sources":["../../src/js/data/sounds.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAC,MAAM,aAAa,CAAC;AAE7F;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAQnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,EAAE,KAAK,GAAE,MAAU,GAAG,MAAM,EAAE,GAAG,IAAI,CAY3G;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CASnE;AAcD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAWzE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQtF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAAU,GAAG,KAAK,GAAG,IAAI,CAsB7G;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,UAAuB,CAAC;AAEjD;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9C;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,UAAU,EAAE,GAAG,KAAK,EAAE,CAI9E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,SAAS,GAAE,MAAU,GAAG,KAAK,EAAE,CAalF;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG;IAAC,KAAK,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAC,GAAC,IAAI,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAmB7L;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,OAAO,CAsBjF;AAED,0CAA0C;AAC1C,eAAO,MAAM,KAAK,EAAE,UAAU,EAAmD,CAAC;AAWlF;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,GAAG,MAAM,EAAE,CAEtF;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,GAAE,UAAsB,GAAG,KAAK,EAAE,CAW/E"}