@arraypress/waveform-sounds 0.3.1 → 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.
- package/LICENSE +1 -1
- package/README.md +19 -1
- package/dist/waveform-sounds-no-autoinit.esm.js +121 -97
- package/dist/waveform-sounds-render.esm.js +24 -10
- package/dist/waveform-sounds.css +62 -76
- package/dist/waveform-sounds.esm.js +122 -98
- package/dist/waveform-sounds.js +123 -98
- package/dist/waveform-sounds.min.css +1 -1
- package/dist/waveform-sounds.min.js +1 -1
- package/package.json +36 -33
- package/src/css/waveform-sounds.css +62 -76
- package/src/js/core/{WaveformSounds.js → WaveformSounds.ts} +301 -191
- package/src/js/core/engine.ts +101 -0
- package/src/js/core/{options.js → options.ts} +33 -28
- package/src/js/data/{bpm.js → bpm.ts} +17 -17
- package/src/js/data/{navigation.js → navigation.ts} +17 -17
- package/src/js/data/{sounds.js → sounds.ts} +62 -61
- package/src/js/data/{url-state.js → url-state.ts} +27 -26
- package/src/js/dom/{colors.js → colors.ts} +12 -12
- package/src/js/dom/{draw.js → draw.ts} +17 -17
- package/src/js/dom/{menus.js → menus.ts} +72 -55
- package/src/js/dom/{rows.js → rows.ts} +18 -17
- package/src/js/{entry.js → entry.ts} +25 -0
- package/src/js/render/{html.js → html.ts} +18 -12
- package/src/js/render/{icons.js → icons.ts} +4 -4
- package/src/js/render/{markup.js → markup.ts} +82 -60
- package/src/js/render/{options.js → options.ts} +26 -20
- package/src/js/render/{strings.js → strings.ts} +17 -16
- package/src/js/{render-entry.js → render-entry.ts} +1 -0
- package/src/js/shared/{utils.js → utils.ts} +22 -22
- package/{index.d.ts → src/js/types.ts} +12 -87
- package/types/core/WaveformSounds.d.ts +145 -0
- package/types/core/WaveformSounds.d.ts.map +1 -0
- package/types/core/engine.d.ts +67 -0
- package/types/core/engine.d.ts.map +1 -0
- package/types/core/options.d.ts +76 -0
- package/types/core/options.d.ts.map +1 -0
- package/types/data/bpm.d.ts +67 -0
- package/types/data/bpm.d.ts.map +1 -0
- package/types/data/navigation.d.ts +53 -0
- package/types/data/navigation.d.ts.map +1 -0
- package/types/data/sounds.d.ts +167 -0
- package/types/data/sounds.d.ts.map +1 -0
- package/types/data/url-state.d.ts +83 -0
- package/types/data/url-state.d.ts.map +1 -0
- package/types/dom/colors.d.ts +35 -0
- package/types/dom/colors.d.ts.map +1 -0
- package/types/dom/draw.d.ts +73 -0
- package/types/dom/draw.d.ts.map +1 -0
- package/types/dom/menus.d.ts +77 -0
- package/types/dom/menus.d.ts.map +1 -0
- package/types/dom/rows.d.ts +42 -0
- package/types/dom/rows.d.ts.map +1 -0
- package/types/entry.d.ts +22 -0
- package/types/entry.d.ts.map +1 -0
- package/types/index.d.ts +16 -0
- package/types/index.d.ts.map +1 -0
- package/types/render/html.d.ts +39 -0
- package/types/render/html.d.ts.map +1 -0
- package/types/render/icons.d.ts +17 -0
- package/types/render/icons.d.ts.map +1 -0
- package/types/render/markup.d.ts +132 -0
- package/types/render/markup.d.ts.map +1 -0
- package/types/render/options.d.ts +56 -0
- package/types/render/options.d.ts.map +1 -0
- package/types/render/strings.d.ts +46 -0
- package/types/render/strings.d.ts.map +1 -0
- package/types/render-entry.d.ts +8 -0
- package/types/render-entry.d.ts.map +1 -0
- package/types/shared/utils.d.ts +57 -0
- package/types/shared/utils.d.ts.map +1 -0
- package/types/types.d.ts +254 -0
- package/types/types.d.ts.map +1 -0
- package/types/vendor/arraypress-text.d.ts +250 -0
- package/dist/waveform-sounds-no-autoinit.cjs +0 -2159
- package/dist/waveform-sounds-render.cjs +0 -614
- package/dist/waveform-sounds.cjs +0 -2181
- package/no-autoinit.d.ts +0 -2
- package/render.d.ts +0 -5
- package/src/js/core/engine.js +0 -57
- /package/src/js/{index.js → index.ts} +0 -0
|
@@ -0,0 +1,46 @@
|
|
|
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
|
+
import type { SoundsSort, WaveformSoundsStrings } from '../types.js';
|
|
9
|
+
/** The English defaults. */
|
|
10
|
+
export declare const DEFAULT_STRINGS: WaveformSoundsStrings;
|
|
11
|
+
/** The label each sort order shows in the Sort menu. */
|
|
12
|
+
export declare const SORT_LABEL_KEYS: Record<SoundsSort, keyof WaveformSoundsStrings>;
|
|
13
|
+
/**
|
|
14
|
+
* Fill `{name}` placeholders; unknown ones are left as written.
|
|
15
|
+
*
|
|
16
|
+
* @param template
|
|
17
|
+
* @param vars
|
|
18
|
+
* @returns
|
|
19
|
+
*/
|
|
20
|
+
export declare function fill(template: string, vars?: Record<string, string | number>): string;
|
|
21
|
+
/**
|
|
22
|
+
* The BPM menu's label: "Any BPM", or the range the handles hold
|
|
23
|
+
* ("120–128 BPM"; an open end shows the pack's own end).
|
|
24
|
+
*
|
|
25
|
+
* @param filter
|
|
26
|
+
* @param extent - The pack's BPM range.
|
|
27
|
+
* @param strings
|
|
28
|
+
* @returns
|
|
29
|
+
*/
|
|
30
|
+
export declare function bpmLabel(filter: {
|
|
31
|
+
bpmMin?: string | number;
|
|
32
|
+
bpmMax?: string | number;
|
|
33
|
+
}, extent: {
|
|
34
|
+
min: number;
|
|
35
|
+
max: number;
|
|
36
|
+
}, strings?: typeof DEFAULT_STRINGS): string;
|
|
37
|
+
/**
|
|
38
|
+
* The count line: "300 sounds", "1 sound", "12 of 300 sounds".
|
|
39
|
+
*
|
|
40
|
+
* @param shown - Sounds matching the filter.
|
|
41
|
+
* @param total - All sounds.
|
|
42
|
+
* @param strings
|
|
43
|
+
* @returns
|
|
44
|
+
*/
|
|
45
|
+
export declare function countText(shown: number, total: number, strings?: typeof DEFAULT_STRINGS): string;
|
|
46
|
+
//# sourceMappingURL=strings.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"strings.d.ts","sourceRoot":"","sources":["../../src/js/render/strings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAC,UAAU,EAAE,qBAAqB,EAAC,MAAM,aAAa,CAAC;AAEnE,4BAA4B;AAC5B,eAAO,MAAM,eAAe,EAAE,qBAuC7B,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,qBAAqB,CAM3E,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAC,MAAM,CAAM,GAAG,MAAM,CAEvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,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,EAAE,OAAO,GAAE,OAAO,eAAiC,GAAG,MAAM,CAIhL;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,eAAiC,GAAG,MAAM,CAGjH"}
|
|
@@ -0,0 +1,8 @@
|
|
|
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';
|
|
7
|
+
export type { SoundInput, Sound, SoundsManifest, WaveformSoundsOptions, WaveformSoundsStrings } from './types.js';
|
|
8
|
+
//# sourceMappingURL=render-entry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"render-entry.d.ts","sourceRoot":"","sources":["../src/js/render-entry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAC,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAClG,OAAO,EAAC,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAC,MAAM,kBAAkB,CAAC;AAChI,YAAY,EAAC,UAAU,EAAE,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,qBAAqB,EAAC,MAAM,YAAY,CAAC"}
|
|
@@ -0,0 +1,57 @@
|
|
|
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
|
+
/** Prefix for every console message and thrown error. */
|
|
8
|
+
export declare const LOG = "[WaveformSounds]";
|
|
9
|
+
/**
|
|
10
|
+
* Clamp a number into a range.
|
|
11
|
+
*
|
|
12
|
+
* @param value
|
|
13
|
+
* @param min
|
|
14
|
+
* @param max
|
|
15
|
+
* @returns
|
|
16
|
+
*/
|
|
17
|
+
export declare function clamp(value: number, min?: number, max?: number): number;
|
|
18
|
+
/**
|
|
19
|
+
* Where a pointer sits across a box, as a fraction 0..1 — the seek
|
|
20
|
+
* position of a click on a row waveform.
|
|
21
|
+
*
|
|
22
|
+
* @param clientX - The pointer's x (viewport coordinates).
|
|
23
|
+
* @param rect - The box (getBoundingClientRect()).
|
|
24
|
+
* @returns 0..1; 0 for a box with no width.
|
|
25
|
+
*/
|
|
26
|
+
export declare function pointerFraction(clientX: number, rect: {
|
|
27
|
+
left: number;
|
|
28
|
+
width: number;
|
|
29
|
+
}): number;
|
|
30
|
+
/**
|
|
31
|
+
* Is the element a place the user types into? Keyboard shortcuts (`/`)
|
|
32
|
+
* must not fire there.
|
|
33
|
+
*
|
|
34
|
+
* @param el
|
|
35
|
+
* @returns
|
|
36
|
+
*/
|
|
37
|
+
export declare function isTyping(el: Element | null | undefined): boolean;
|
|
38
|
+
/**
|
|
39
|
+
* Dispatch a bubbling `waveformsounds:<name>` CustomEvent from an element.
|
|
40
|
+
* Every event the list emits goes through here, so they share one shape:
|
|
41
|
+
* the detail plus the instance that sent it.
|
|
42
|
+
*
|
|
43
|
+
* @param target
|
|
44
|
+
* @param name - Without the prefix (`'play'`).
|
|
45
|
+
* @param detail
|
|
46
|
+
* @returns The event dispatched.
|
|
47
|
+
*/
|
|
48
|
+
export declare function emit(target: EventTarget, name: string, detail: Record<string, any>): CustomEvent;
|
|
49
|
+
/**
|
|
50
|
+
* A small, stable string hash (djb2, 32-bit) — for ids that must come out
|
|
51
|
+
* the same on the server and in the browser. Not cryptographic.
|
|
52
|
+
*
|
|
53
|
+
* @param str
|
|
54
|
+
* @returns An unsigned 32-bit integer.
|
|
55
|
+
*/
|
|
56
|
+
export declare function hashString(str: string): number;
|
|
57
|
+
//# sourceMappingURL=utils.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/js/shared/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yDAAyD;AACzD,eAAO,MAAM,GAAG,qBAAqB,CAAC;AAEtC;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAU,EAAE,GAAG,GAAE,MAAU,GAAG,MAAM,CAE7E;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,GAAG,MAAM,CAE5F;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,WAAW,CAIhG;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI9C"}
|
package/types/types.d.ts
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The public data, option and event types of WaveformSounds. Moved here from
|
|
3
|
+
* the hand-written index.d.ts so the source uses the same definitions the
|
|
4
|
+
* published types are generated from.
|
|
5
|
+
*
|
|
6
|
+
* The four `waveform-sounds-*` wrappers derive their prop types from
|
|
7
|
+
* `WaveformSoundsOptions` here. Add or rename an option in `core/options.ts`
|
|
8
|
+
* (`DEFAULT_OPTIONS`) and in this file in the same change.
|
|
9
|
+
*
|
|
10
|
+
* @module types
|
|
11
|
+
*/
|
|
12
|
+
import type { WaveformSounds } from './core/WaveformSounds.js';
|
|
13
|
+
/** One sound, as given (a manifest entry, a `sounds` item). */
|
|
14
|
+
export interface SoundInput {
|
|
15
|
+
/** Audio URL. Required. */
|
|
16
|
+
url: string;
|
|
17
|
+
/** Display name. Defaults to the file name. */
|
|
18
|
+
title?: string;
|
|
19
|
+
/** Kind of sound ("Drum loops", "Bass", "One-shots"): the type chips. */
|
|
20
|
+
type?: string;
|
|
21
|
+
/** Tempo. Enables the BPM range filter and sort. */
|
|
22
|
+
bpm?: number | string;
|
|
23
|
+
/** Musical key, any common spelling ("F minor", "Fmin", "F#"). Shown
|
|
24
|
+
* and filtered in a short canonical form ("Fm", "F#"). */
|
|
25
|
+
key?: string;
|
|
26
|
+
/** Length: seconds (8.02) or "m:ss". */
|
|
27
|
+
duration?: number | string;
|
|
28
|
+
/** Extra words the search matches. */
|
|
29
|
+
tags?: string[] | string;
|
|
30
|
+
/** Low-resolution peaks for the row waveform: an 8-bit hex string
|
|
31
|
+
* (two characters per bar, what `waveform-gen --manifest` writes) or
|
|
32
|
+
* numbers 0..1. Without them the row shows a flat line until played. */
|
|
33
|
+
peaks?: string | number[];
|
|
34
|
+
/** Full-resolution peaks for the `strip` player (a waveform-gen `.json`
|
|
35
|
+
* URL or an array). */
|
|
36
|
+
waveform?: string | number[];
|
|
37
|
+
/** Optional download link for this sound (a free sample, the `.mid` of
|
|
38
|
+
* a MIDI preview). Rows with one get a download button; rows without
|
|
39
|
+
* carry nothing. A plain `<a download>`: gating is the site's job. */
|
|
40
|
+
download?: string;
|
|
41
|
+
/** A loop (`true`) rather than a one-shot (the default). Loops get a
|
|
42
|
+
* loop icon beside their name, the "Loops / One-shots" filter appears
|
|
43
|
+
* once a list has both, and with any sound marked the Loop toggle
|
|
44
|
+
* repeats only loops. */
|
|
45
|
+
loop?: boolean;
|
|
46
|
+
/** Stable id for `play('id')`. Defaults to `sound-<n>`, 1-based
|
|
47
|
+
* (`sound-1` is the first sound). */
|
|
48
|
+
id?: string;
|
|
49
|
+
}
|
|
50
|
+
/** A sound after normalisation (what the runtime holds). */
|
|
51
|
+
export interface Sound {
|
|
52
|
+
id: string;
|
|
53
|
+
url: string;
|
|
54
|
+
title: string;
|
|
55
|
+
type: string;
|
|
56
|
+
bpm: number | null;
|
|
57
|
+
key: string;
|
|
58
|
+
duration: number | null;
|
|
59
|
+
tags: string[];
|
|
60
|
+
peaks: number[] | null;
|
|
61
|
+
waveform: string | null;
|
|
62
|
+
download: string | null;
|
|
63
|
+
loop: boolean;
|
|
64
|
+
}
|
|
65
|
+
/** What `waveform-gen --manifest` writes (a bare array also works). */
|
|
66
|
+
export interface SoundsManifest {
|
|
67
|
+
version?: number;
|
|
68
|
+
/** Scale of integer `peaks` arrays (e.g. 100). Ignored for hex peaks. */
|
|
69
|
+
peakScale?: number;
|
|
70
|
+
sounds: SoundInput[];
|
|
71
|
+
}
|
|
72
|
+
export interface SoundsFilter {
|
|
73
|
+
/** Words matched (all of them, any order) against title, type, key and
|
|
74
|
+
* tags; a number also matches the BPM exactly. */
|
|
75
|
+
query: string;
|
|
76
|
+
/** One type, or '' for all. */
|
|
77
|
+
type: string;
|
|
78
|
+
/** One key, or '' for any. */
|
|
79
|
+
key: string;
|
|
80
|
+
bpmMin: number | string;
|
|
81
|
+
bpmMax: number | string;
|
|
82
|
+
/** `'loop'`: loops only. `'one-shot'`: everything else. '' for both. */
|
|
83
|
+
loop?: SoundsLoopFilter;
|
|
84
|
+
}
|
|
85
|
+
export type SoundsLoopFilter = '' | 'loop' | 'one-shot';
|
|
86
|
+
export type SoundsSort = 'default' | 'title' | 'bpm' | 'key' | 'duration';
|
|
87
|
+
export type SoundsLayout = 'inline' | 'strip';
|
|
88
|
+
export type SoundsFilterControl = 'type' | 'key' | 'bpm' | 'loop';
|
|
89
|
+
export type SoundsColumn = 'type' | 'bpm' | 'key' | 'duration';
|
|
90
|
+
/** Every visible or announced word. `{title}`, `{count}`, `{total}` are filled in. */
|
|
91
|
+
export interface WaveformSoundsStrings {
|
|
92
|
+
search: string;
|
|
93
|
+
searchPlaceholder: string;
|
|
94
|
+
all: string;
|
|
95
|
+
types: string;
|
|
96
|
+
key: string;
|
|
97
|
+
anyKey: string;
|
|
98
|
+
allTypes: string;
|
|
99
|
+
findType: string;
|
|
100
|
+
findKey: string;
|
|
101
|
+
noMatches: string;
|
|
102
|
+
bpm: string;
|
|
103
|
+
bpmMin: string;
|
|
104
|
+
bpmMax: string;
|
|
105
|
+
/** The BPM menu with no limit set. */
|
|
106
|
+
anyBpm: string;
|
|
107
|
+
/** The BPM menu's range: `{min}`, `{max}`. */
|
|
108
|
+
bpmRange: string;
|
|
109
|
+
sort: string;
|
|
110
|
+
sortBy: string;
|
|
111
|
+
sortDefault: string;
|
|
112
|
+
sortTitle: string;
|
|
113
|
+
sortBpm: string;
|
|
114
|
+
sortKey: string;
|
|
115
|
+
sortDuration: string;
|
|
116
|
+
loop: string;
|
|
117
|
+
loopFilter: string;
|
|
118
|
+
loops: string;
|
|
119
|
+
oneShots: string;
|
|
120
|
+
isLoop: string;
|
|
121
|
+
play: string;
|
|
122
|
+
pause: string;
|
|
123
|
+
seek: string;
|
|
124
|
+
download: string;
|
|
125
|
+
count: string;
|
|
126
|
+
countOne: string;
|
|
127
|
+
countFiltered: string;
|
|
128
|
+
showMore: string;
|
|
129
|
+
empty: string;
|
|
130
|
+
clear: string;
|
|
131
|
+
nowPlaying: string;
|
|
132
|
+
}
|
|
133
|
+
export interface WaveformSoundsOptions {
|
|
134
|
+
/** The sounds. Or `manifest`, or server-rendered rows in the container. */
|
|
135
|
+
sounds?: SoundInput[] | null;
|
|
136
|
+
/** URL of a sounds manifest (JSON), fetched when there are no `sounds`
|
|
137
|
+
* and no server-rendered rows. */
|
|
138
|
+
manifest?: string | null;
|
|
139
|
+
/** `'inline'` (default): a mini waveform per row, the playing row fills
|
|
140
|
+
* and seeks. `'strip'`: plain rows and one full player docked below. */
|
|
141
|
+
player?: SoundsLayout;
|
|
142
|
+
/** Show the search box. Default true. */
|
|
143
|
+
search?: boolean;
|
|
144
|
+
/** Which filter controls to offer (each appears only when the data has
|
|
145
|
+
* something to filter: 2+ types, 2+ keys, a BPM range, both loops and
|
|
146
|
+
* one-shots). Drop one to
|
|
147
|
+
* remove it, e.g. `['type']` for no key or BPM filtering — and leave
|
|
148
|
+
* it out of `columns` and `sorts` to remove it everywhere. `[]` = no
|
|
149
|
+
* filters. */
|
|
150
|
+
filters?: SoundsFilterControl[];
|
|
151
|
+
/** The sort orders the Sort menu offers, in order; the first is the
|
|
152
|
+
* starting order. Orders the data can't use are dropped (no BPM sort
|
|
153
|
+
* without BPMs). `[]` (or one usable order) hides the menu.
|
|
154
|
+
* Default `['default', 'title', 'bpm', 'key', 'duration']`. */
|
|
155
|
+
sorts?: SoundsSort[];
|
|
156
|
+
/** Show the "12 of 300 sounds" count. Default true. */
|
|
157
|
+
showCount?: boolean;
|
|
158
|
+
/** A dropdown (type / key / sort) gets a search field when it has more
|
|
159
|
+
* than this many options. Default 8. */
|
|
160
|
+
menuSearch?: number;
|
|
161
|
+
/** Prefix for the dropdowns' element ids. Default: the container's `id`,
|
|
162
|
+
* else a hash of the sounds — so two lists of the SAME sounds on one
|
|
163
|
+
* page each need one (or an `id`). Wrappers pass a framework-unique id. */
|
|
164
|
+
idPrefix?: string;
|
|
165
|
+
/** Keep the filters in the address (`?q=bass&type=Bass+loops&key=Fm&
|
|
166
|
+
* bpm=120-130&sort=bpm`), so a filtered list can be shared and survives
|
|
167
|
+
* a refresh. `true` uses those names; a string prefixes them
|
|
168
|
+
* (`'pack'` → `pack-q`, `pack-type`, …) for several lists on a page.
|
|
169
|
+
* Uses replaceState: filtering adds no history entries. Default false. */
|
|
170
|
+
urlState?: boolean | string;
|
|
171
|
+
/** Show the Loop toggle. Default true. When any sound is marked
|
|
172
|
+
* `loop: true`, only loops repeat. */
|
|
173
|
+
loopToggle?: boolean;
|
|
174
|
+
/** Up to this many types show as chips; more become a "Type" menu
|
|
175
|
+
* (a pack has a handful, a whole library can have fifty). Default 10. */
|
|
176
|
+
maxTypeChips?: number;
|
|
177
|
+
/** Rows shown before "Show more" (0 = all). Default 50. */
|
|
178
|
+
pageSize?: number;
|
|
179
|
+
/** Columns after the title, in order. Default all four. */
|
|
180
|
+
columns?: SoundsColumn[];
|
|
181
|
+
/** Row waveform style. Default `'mirror'`. */
|
|
182
|
+
waveformStyle?: 'mirror' | 'bars';
|
|
183
|
+
/** Row waveform colour. Default: CSS `--ws-wave-color`. */
|
|
184
|
+
waveformColor?: string | null;
|
|
185
|
+
/** Played-part colour. Default: CSS `--ws-progress-color` (the accent). */
|
|
186
|
+
progressColor?: string | null;
|
|
187
|
+
/** Row bar width in CSS px. Default 2. */
|
|
188
|
+
barWidth?: number;
|
|
189
|
+
/** Gap between row bars in CSS px. Default 1. */
|
|
190
|
+
barGap?: number;
|
|
191
|
+
/** Start with Loop on or off. Unset (default): on when any sound is
|
|
192
|
+
* marked `loop: true` (then only loops repeat), off otherwise. */
|
|
193
|
+
loop?: boolean | null;
|
|
194
|
+
/** Play the next visible sound when one ends. Default false. */
|
|
195
|
+
autoAdvance?: boolean;
|
|
196
|
+
/** While a sound plays, ↑/↓ move to the next row AND play it (the
|
|
197
|
+
* sample-browser audition). Default true. */
|
|
198
|
+
arrowAudition?: boolean;
|
|
199
|
+
/** Options for the engine `WaveformPlayer` (colours, height, … — and its
|
|
200
|
+
* callbacks, which are called alongside the list's own). `audioMode` is
|
|
201
|
+
* always `'self'`; `loop` and `showLoop` are always off (the list's Loop
|
|
202
|
+
* toggle owns looping); `duration`, `downloadUrl` and `downloadName` are
|
|
203
|
+
* ignored (each sound brings its own). As markup: `data-player-options`
|
|
204
|
+
* (JSON). */
|
|
205
|
+
playerOptions?: Record<string, unknown> | null;
|
|
206
|
+
/** The `WaveformPlayer` class, for ESM setups without the global. */
|
|
207
|
+
playerClass?: unknown;
|
|
208
|
+
/** UI strings (partial: merged over the English defaults). As markup:
|
|
209
|
+
* `data-strings='{"count":"{count} geluiden"}'` (JSON). */
|
|
210
|
+
strings?: Partial<WaveformSoundsStrings> | null;
|
|
211
|
+
onReady?: ((instance: WaveformSounds) => void) | null;
|
|
212
|
+
onPlay?: ((sound: Sound, instance: WaveformSounds) => void) | null;
|
|
213
|
+
onPause?: ((sound: Sound, instance: WaveformSounds) => void) | null;
|
|
214
|
+
onEnd?: ((sound: Sound, instance: WaveformSounds) => void) | null;
|
|
215
|
+
/** After every filter/sort/page change, with the matching sounds. */
|
|
216
|
+
onFilter?: ((visible: Sound[], instance: WaveformSounds) => void) | null;
|
|
217
|
+
onError?: ((error: unknown, instance: WaveformSounds) => void) | null;
|
|
218
|
+
}
|
|
219
|
+
/** `detail` of the `waveformsounds:*` DOM events (all bubble). */
|
|
220
|
+
export interface WaveformSoundsEventMap {
|
|
221
|
+
'waveformsounds:ready': CustomEvent<{
|
|
222
|
+
sounds: number;
|
|
223
|
+
instance: WaveformSounds;
|
|
224
|
+
}>;
|
|
225
|
+
'waveformsounds:play': CustomEvent<{
|
|
226
|
+
sound: Sound;
|
|
227
|
+
index: number;
|
|
228
|
+
instance: WaveformSounds;
|
|
229
|
+
}>;
|
|
230
|
+
'waveformsounds:pause': CustomEvent<{
|
|
231
|
+
sound: Sound;
|
|
232
|
+
index: number;
|
|
233
|
+
instance: WaveformSounds;
|
|
234
|
+
}>;
|
|
235
|
+
'waveformsounds:end': CustomEvent<{
|
|
236
|
+
sound: Sound;
|
|
237
|
+
index: number;
|
|
238
|
+
instance: WaveformSounds;
|
|
239
|
+
}>;
|
|
240
|
+
'waveformsounds:filter': CustomEvent<{
|
|
241
|
+
visible: number;
|
|
242
|
+
total: number;
|
|
243
|
+
filter: SoundsFilter;
|
|
244
|
+
sort: SoundsSort;
|
|
245
|
+
instance: WaveformSounds;
|
|
246
|
+
}>;
|
|
247
|
+
'waveformsounds:error': CustomEvent<{
|
|
248
|
+
error: unknown;
|
|
249
|
+
sound?: Sound;
|
|
250
|
+
index?: number;
|
|
251
|
+
instance: WaveformSounds;
|
|
252
|
+
}>;
|
|
253
|
+
}
|
|
254
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/js/types.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @arraypress/text
|
|
3
|
+
*
|
|
4
|
+
* Practical text utilities — truncation, CSV and HTML escaping, initials,
|
|
5
|
+
* plurals, first lines, and accent-blind, typo-tolerant search.
|
|
6
|
+
* Designed for ecommerce admin UIs, data export, and URL generation.
|
|
7
|
+
*
|
|
8
|
+
* Zero dependencies. Works in any JS runtime.
|
|
9
|
+
*
|
|
10
|
+
* @module @arraypress/text
|
|
11
|
+
*/
|
|
12
|
+
export type TruncateOptions = {
|
|
13
|
+
/**
|
|
14
|
+
* Where the ellipsis goes. Default `'end'`.
|
|
15
|
+
*/
|
|
16
|
+
position?: 'end' | 'middle';
|
|
17
|
+
/**
|
|
18
|
+
* What marks the cut. Default `'...'` at the end, `'…'` in the middle.
|
|
19
|
+
*/
|
|
20
|
+
ellipsis?: string;
|
|
21
|
+
};
|
|
22
|
+
export type GetInitialsOptions = {
|
|
23
|
+
/**
|
|
24
|
+
* Maximum number of characters to return. Default 2.
|
|
25
|
+
*/
|
|
26
|
+
max?: number;
|
|
27
|
+
};
|
|
28
|
+
export type MatchesAllOptions = {
|
|
29
|
+
/**
|
|
30
|
+
* Shortest word allowed a typo. Default 4.
|
|
31
|
+
*/
|
|
32
|
+
fuzzyFrom?: number;
|
|
33
|
+
};
|
|
34
|
+
/**
|
|
35
|
+
* Truncate a string with an ellipsis.
|
|
36
|
+
*
|
|
37
|
+
* Supports two modes:
|
|
38
|
+
* - End truncation (default): "A very long str..."
|
|
39
|
+
* - Middle truncation: "pi_3abc1…789" (useful for IDs)
|
|
40
|
+
*
|
|
41
|
+
* @param {string | null | undefined} str - The string to truncate.
|
|
42
|
+
* @param {number} maxLength - Maximum length including ellipsis.
|
|
43
|
+
* @param {TruncateOptions} [options]
|
|
44
|
+
* @returns {string} Truncated string.
|
|
45
|
+
*
|
|
46
|
+
* @example
|
|
47
|
+
* truncate('A very long product name here', 20)
|
|
48
|
+
* // 'A very long produ...'
|
|
49
|
+
*
|
|
50
|
+
* truncate('pi_3PBxyz123abc456def', 16, { position: 'middle' })
|
|
51
|
+
* // 'pi_3PBx…456def'
|
|
52
|
+
*/
|
|
53
|
+
export declare function truncate(str: string | null | undefined, maxLength: number, options?: TruncateOptions): string;
|
|
54
|
+
/**
|
|
55
|
+
* Escape a string for safe use in a CSV field.
|
|
56
|
+
*
|
|
57
|
+
* Wraps the value in double quotes if it contains commas, quotes,
|
|
58
|
+
* or newlines. Escapes internal double quotes by doubling them.
|
|
59
|
+
*
|
|
60
|
+
* @param {string | number | boolean | null | undefined} str - The value to escape; a number or a
|
|
61
|
+
* boolean is written as it prints.
|
|
62
|
+
* @returns {string} CSV-safe string.
|
|
63
|
+
*
|
|
64
|
+
* @example
|
|
65
|
+
* escapeCSV('Simple value') // 'Simple value'
|
|
66
|
+
* escapeCSV('Has, comma') // '"Has, comma"'
|
|
67
|
+
* escapeCSV('Has "quotes"') // '"Has ""quotes"""'
|
|
68
|
+
* escapeCSV('Line 1\nLine 2') // '"Line 1\nLine 2"'
|
|
69
|
+
* escapeCSV(0) // '0'
|
|
70
|
+
*/
|
|
71
|
+
export declare function escapeCSV(str: string | number | boolean | null | undefined): string;
|
|
72
|
+
/**
|
|
73
|
+
* Escape a string for safe embedding in HTML.
|
|
74
|
+
*
|
|
75
|
+
* Replaces `& < > " '` with their entity forms. Accepts `unknown` so
|
|
76
|
+
* callers don't need to pre-coerce — `null`/`undefined` collapse to
|
|
77
|
+
* the empty string and anything else is `String()`-ified first. The
|
|
78
|
+
* apostrophe is escaped as `'` (not `'`) for maximum legacy
|
|
79
|
+
* compatibility; most HTML parsers handle the numeric form reliably.
|
|
80
|
+
*
|
|
81
|
+
* Use this EVERY time you're interpolating user-authored data into an
|
|
82
|
+
* HTML template — email bodies, server-rendered pages, OG metadata —
|
|
83
|
+
* rather than hand-rolling the replace call. One canonical
|
|
84
|
+
* implementation avoids the classic forget-to-escape-the-apostrophe
|
|
85
|
+
* bug class.
|
|
86
|
+
*
|
|
87
|
+
* @param {unknown} input - Value to escape.
|
|
88
|
+
* @returns {string} HTML-safe string.
|
|
89
|
+
*
|
|
90
|
+
* @example
|
|
91
|
+
* escapeHtml('<b>Acme</b>') // '<b>Acme</b>'
|
|
92
|
+
* escapeHtml(`O'Brien & Co`) // 'O'Brien & Co'
|
|
93
|
+
* escapeHtml(null) // ''
|
|
94
|
+
*/
|
|
95
|
+
export declare function escapeHtml(input: unknown): string;
|
|
96
|
+
/**
|
|
97
|
+
* Returns the uppercase initials of a name. Handles both multi-word
|
|
98
|
+
* and single-word inputs gracefully.
|
|
99
|
+
*
|
|
100
|
+
* Multi-word names take the first letter of each word, up to `max`.
|
|
101
|
+
* Single-word names use the first `max` characters of the word so
|
|
102
|
+
* the avatar tile always has something to show (`"Dave"` → `"DA"`
|
|
103
|
+
* rather than `"D"`).
|
|
104
|
+
*
|
|
105
|
+
* Typical use: monogram tiles / fallback avatars on cards, author
|
|
106
|
+
* blocks, testimonials — anything that needs a placeholder when no
|
|
107
|
+
* image is available. Paired with the `generateInitialsAvatar()`
|
|
108
|
+
* helper in `@arraypress/color-utils` to render the actual SVG.
|
|
109
|
+
*
|
|
110
|
+
* @param {string|undefined|null} name - The full name (or any noun phrase).
|
|
111
|
+
* @param {GetInitialsOptions} [opts] - Configuration. `max` defaults to `2`.
|
|
112
|
+
* @returns {string} Initials, uppercase. Empty string for empty input.
|
|
113
|
+
*
|
|
114
|
+
* @example
|
|
115
|
+
* getInitials('David Sherlock') // 'DS'
|
|
116
|
+
* getInitials('Sean Tyas Darren', { max: 3 }) // 'STD'
|
|
117
|
+
* getInitials('Dave') // 'DA' (single-word fallback)
|
|
118
|
+
* getInitials(' spaces trimmed ') // 'ST'
|
|
119
|
+
* getInitials('') // ''
|
|
120
|
+
* getInitials(undefined) // ''
|
|
121
|
+
*/
|
|
122
|
+
export declare function getInitials(name: string | undefined | null, opts?: GetInitialsOptions): string;
|
|
123
|
+
/**
|
|
124
|
+
* English pluralisation helper for `"{n} thing" / "{n} things"`
|
|
125
|
+
* patterns. Returns the FULL phrase (count + word) so the call
|
|
126
|
+
* site collapses to a single expression:
|
|
127
|
+
*
|
|
128
|
+
* pluralize(1, 'post', 'posts') // '1 post'
|
|
129
|
+
* pluralize(12, 'post', 'posts') // '12 posts'
|
|
130
|
+
* pluralize(0, 'item', 'items') // '0 items'
|
|
131
|
+
*
|
|
132
|
+
* For non-English locales pass the translated singular + plural;
|
|
133
|
+
* this helper doesn't pretend to know your language's plural
|
|
134
|
+
* rules. Languages with more than two plural forms (Russian,
|
|
135
|
+
* Polish, Arabic, …) need `Intl.PluralRules`.
|
|
136
|
+
*
|
|
137
|
+
* @param {number} n - The count.
|
|
138
|
+
* @param {string} singular - Word for n === 1.
|
|
139
|
+
* @param {string} plural - Word for anything else.
|
|
140
|
+
* @returns {string} `"<n> <word>"` — full phrase.
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* pluralize(1, 'item', 'items') // '1 item'
|
|
144
|
+
* pluralize(0, 'result', 'results') // '0 results'
|
|
145
|
+
* pluralize(7, 'tag', 'tags') // '7 tags'
|
|
146
|
+
*/
|
|
147
|
+
export declare function pluralize(n: number, singular: string, plural: string): string;
|
|
148
|
+
/**
|
|
149
|
+
* Aggressive comparison normaliser.
|
|
150
|
+
*
|
|
151
|
+
* Lowercase → trim → strip every non-word / non-space character →
|
|
152
|
+
* collapse runs of whitespace into single spaces. The output is
|
|
153
|
+
* intended for equality comparison or deduplication, NOT for display
|
|
154
|
+
* or URL generation (use `slugify` for URLs).
|
|
155
|
+
*
|
|
156
|
+
* Typical use: fuzzy-matching product titles and user-entered aliases
|
|
157
|
+
* so `"Pro Bundle™ (2024)"` and `"pro bundle 2024"` collide. Running
|
|
158
|
+
* the same normaliser on both sides of the compare keeps the match
|
|
159
|
+
* engine consistent across admin UI, API, and import paths.
|
|
160
|
+
*
|
|
161
|
+
* @param {string | null | undefined} s - Input string.
|
|
162
|
+
* @returns {string} Normalised form.
|
|
163
|
+
*
|
|
164
|
+
* @example
|
|
165
|
+
* normalize(' Pro Bundle™ (2024) ') // 'pro bundle 2024'
|
|
166
|
+
* normalize('Pro—Bundle') // 'probundle' (em-dash stripped, no space inserted)
|
|
167
|
+
* normalize('Café & Résumé') // 'café résumé' (letters of every script kept)
|
|
168
|
+
*/
|
|
169
|
+
export declare function normalize(s: string | null | undefined): string;
|
|
170
|
+
/**
|
|
171
|
+
* Fold text for searching: lower case, and accents off — so "résumé" is
|
|
172
|
+
* found by "resume".
|
|
173
|
+
*
|
|
174
|
+
* Decomposes to NFD and drops the accents (the PHP twin,
|
|
175
|
+
* `SugarCommerce\Format\Search`, drops every combining mark with the intl
|
|
176
|
+
* extension, and agrees for Latin, Greek and Cyrillic). The marks that
|
|
177
|
+
* spell a word stay, recomposed: a Hindi or Thai vowel sign, a kana's
|
|
178
|
+
* voicing mark. Dropping those made "हिंदी" the letters "हद" and "が" a "か".
|
|
179
|
+
*
|
|
180
|
+
* @param {string | null | undefined} text - Name or query.
|
|
181
|
+
* @returns {string} Folded text.
|
|
182
|
+
*
|
|
183
|
+
* @example
|
|
184
|
+
* fold('Résumé.PDF') // 'resume.pdf'
|
|
185
|
+
* fold('がっこう') // 'がっこう'
|
|
186
|
+
*/
|
|
187
|
+
export declare function fold(text: string | null | undefined): string;
|
|
188
|
+
/**
|
|
189
|
+
* The words in a name or a query, folded. Anything that is not a letter, a
|
|
190
|
+
* digit or a mark that spells a word, in any script, separates words.
|
|
191
|
+
*
|
|
192
|
+
* @param {string | null | undefined} text - Name or query.
|
|
193
|
+
* @returns {string[]} Words, in order, none empty.
|
|
194
|
+
*
|
|
195
|
+
* @example
|
|
196
|
+
* words('Midnight Drive - Master.wav') // ['midnight', 'drive', 'master', 'wav']
|
|
197
|
+
*/
|
|
198
|
+
export declare function words(text: string | null | undefined): string[];
|
|
199
|
+
/**
|
|
200
|
+
* Edit distance by character (code point), counting a swap of two
|
|
201
|
+
* neighbouring characters as one edit — optimal string alignment.
|
|
202
|
+
*
|
|
203
|
+
* Plain Levenshtein calls "midnigth" two edits from "midnight", but the
|
|
204
|
+
* commonest typing slip is exactly that swap, so a search forgiving one edit
|
|
205
|
+
* missed the file the person plainly meant. Optimal string alignment edits
|
|
206
|
+
* each part once: "ca" → "abc" is 3 (unrestricted Damerau says 2).
|
|
207
|
+
*
|
|
208
|
+
* @param {string} a - One word.
|
|
209
|
+
* @param {string} b - The other.
|
|
210
|
+
* @returns {number} Edits between them.
|
|
211
|
+
*
|
|
212
|
+
* @example
|
|
213
|
+
* editDistance('midnigth', 'midnight') // 1
|
|
214
|
+
* editDistance('résumé', 'resume') // 2
|
|
215
|
+
*/
|
|
216
|
+
export declare function editDistance(a: string, b: string): number;
|
|
217
|
+
/**
|
|
218
|
+
* Whether every word of a query is in a name: in any order, as part of the
|
|
219
|
+
* name, or — for words of `fuzzyFrom` characters or more — within one edit
|
|
220
|
+
* of a word of the name or of its start, so "licens" finds "Licence" while
|
|
221
|
+
* it is still being typed.
|
|
222
|
+
*
|
|
223
|
+
* The same rules as `SugarCommerce\Format\Search` in PHP, so a list
|
|
224
|
+
* filtered in the browser and one filtered on the server agree.
|
|
225
|
+
*
|
|
226
|
+
* @param {string} name - What is searched, e.g. a filename.
|
|
227
|
+
* @param {string} query - What was typed. An empty query matches everything.
|
|
228
|
+
* @param {MatchesAllOptions} [options] - Shortest word allowed a typo.
|
|
229
|
+
* Default 4: below that one wrong letter is a different word ("wav", "way").
|
|
230
|
+
* @returns {boolean}
|
|
231
|
+
*
|
|
232
|
+
* @example
|
|
233
|
+
* matchesAll('Licence Agreement.pdf', 'license') // true
|
|
234
|
+
* matchesAll('Midnight Drive - Master.wav', 'mastr midnigth') // true
|
|
235
|
+
* matchesAll('Neon Rain - Master.wav', 'way') // false
|
|
236
|
+
*/
|
|
237
|
+
export declare function matchesAll(name: string, query: string, options?: MatchesAllOptions): boolean;
|
|
238
|
+
/**
|
|
239
|
+
* The first line of a text that has anything on it, trimmed: what a list
|
|
240
|
+
* row shows for a long note or template ("Hi {name}," for a reply that
|
|
241
|
+
* starts with a blank line).
|
|
242
|
+
*
|
|
243
|
+
* @param {string | null | undefined} text - Any text; `null` and `undefined` read as empty.
|
|
244
|
+
* @returns {string} The first non-blank line, trimmed, or `''` when there is none.
|
|
245
|
+
*
|
|
246
|
+
* @example
|
|
247
|
+
* firstLine('\n Hi Sam,\nThanks for…') // 'Hi Sam,'
|
|
248
|
+
* firstLine(' ') // ''
|
|
249
|
+
*/
|
|
250
|
+
export declare function firstLine(text: string | null | undefined): string;
|