@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,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"}
@@ -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 `&#39;` (not `&apos;`) 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>') // '&lt;b&gt;Acme&lt;/b&gt;'
92
+ * escapeHtml(`O'Brien & Co`) // 'O&#39;Brien &amp; 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;