@molecule/app-feature-audio-waveform-vue 0.0.1-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +257 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,264 @@
1
+ <!--
2
+ AUTO-GENERATED — DO NOT EDIT THIS FILE.
3
+ Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
4
+ Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
5
+ To change this document, edit the module-level JSDoc in src/index.ts.
6
+ Generated: 2026-11-21T12:46:28.075Z
7
+ -->
8
+
1
9
  # @molecule/app-feature-audio-waveform-vue
2
10
 
3
- Stylized SVG audio waveform with click-to-seek + region overlays — renders pre-computed peaks for music-daw / podcast / streaming
11
+ Audio waveform — stylized SVG renderer of pre-computed audio peaks
12
+ with progress overlay, click-to-seek, and timed region markers.
13
+
14
+ Vue counterpart of `@molecule/app-feature-audio-waveform-react`: the same
15
+ props (React names), the same DOM for the same input.
16
+
17
+ Used by music-daw, podcast, and music-streaming surfaces to display
18
+ a waveform of the underlying audio source. Peak amplitudes must be
19
+ computed by the caller (typically offline with `wavesurfer.js`,
20
+ `peaks.js`, or an `AudioContext` analysis pass) — this package is
21
+ intentionally just the renderer.
22
+
23
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
24
+ > It is written to be read by coding agents as much as by people, and is generated from this
25
+ > package's source — edit `src/index.ts` JSDoc, not this file.
26
+
27
+ ## Quick Start
28
+
29
+ ```ts
30
+ import { defineComponent, h } from 'vue'
31
+ import { AudioWaveform } from '@molecule/app-feature-audio-waveform-vue'
32
+
33
+ const Player = defineComponent({
34
+ props: { peaks: Array, duration: Number, currentTime: Number },
35
+ setup(props) {
36
+ return () =>
37
+ h(AudioWaveform, {
38
+ peaks: props.peaks,
39
+ duration: props.duration,
40
+ currentTime: props.currentTime,
41
+ onSeek: (seconds: number) => {
42
+ // move the audio element to `seconds`
43
+ },
44
+ regions: [{ id: 'loop', startTime: 12, duration: 3, color: '#a78bfa55' }],
45
+ })
46
+ },
47
+ })
48
+ ```
49
+
50
+ ## Type
51
+
52
+ `feature`
53
+
54
+ ## Installation
55
+
56
+ ```bash
57
+ npm install @molecule/app-feature-audio-waveform-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
58
+ ```
59
+
60
+ ## API
61
+
62
+ ### Interfaces
63
+
64
+ #### `WaveformRegion`
65
+
66
+ A timed colored band overlaid on top of the waveform — used to mark
67
+ loop ranges, comments, edit selections, chapter spans, etc.
68
+
69
+ ```typescript
70
+ interface WaveformRegion {
71
+ /** Stable identifier for the region (used as a render key). */
72
+ id: string
73
+ /** Start of the region, in seconds. */
74
+ startTime: number
75
+ /** Duration of the region, in seconds. Negative / zero hides the region. */
76
+ duration: number
77
+ /**
78
+ * Optional CSS color applied to the region rectangle. Defaults to a
79
+ * semi-transparent accent ink. Use semi-transparent fills so the
80
+ * underlying waveform stays visible.
81
+ */
82
+ color?: string
83
+ }
84
+ ```
85
+
86
+ #### `AudioWaveformProps`
87
+
88
+ AudioWaveform component props (React's prop names).
89
+
90
+ ```typescript
91
+ interface AudioWaveformProps {
92
+ /**
93
+ * Pre-computed peak amplitudes in playback order. Each value should
94
+ * be normalized into the closed interval `[0, 1]` (the renderer clamps
95
+ * out-of-range values). One bar is drawn per peak.
96
+ */
97
+ peaks: number[]
98
+ /**
99
+ * Total duration of the underlying audio in seconds. Used to translate
100
+ * click positions into seek timestamps and to size region overlays.
101
+ * Must be `> 0` for `onSeek` and `regions` to render correctly.
102
+ */
103
+ duration: number
104
+ /**
105
+ * Current playback time in seconds. Drives the progress overlay that
106
+ * fills the waveform from the left up to this point. Defaults to `0`.
107
+ */
108
+ currentTime?: number
109
+ /**
110
+ * Optional click handler called with the seek target time (in
111
+ * seconds) when the user clicks anywhere on the waveform. When
112
+ * omitted, the waveform renders as a non-interactive display.
113
+ */
114
+ onSeek?: (seekTime: number) => void
115
+ /** Optional region markers overlaid on top of the waveform. */
116
+ regions?: WaveformRegion[]
117
+ /** Pixel height of the waveform. Defaults to `64`. */
118
+ height?: number
119
+ /**
120
+ * CSS color used for the progress overlay (the played portion of the
121
+ * waveform). Defaults to `currentColor`.
122
+ */
123
+ progressColor?: string
124
+ /**
125
+ * CSS color used for the unplayed portion of the waveform. Defaults
126
+ * to `currentColor`.
127
+ */
128
+ waveColor?: string
129
+ /** Extra classes merged onto the root element. */
130
+ className?: string
131
+ }
132
+ ```
133
+
134
+ ### Functions
4
135
 
136
+ #### `clamp(value, min, max)`
137
+
138
+ Clamp a value into the closed interval `[min, max]`. Returns `min`
139
+ for `NaN` / non-finite inputs.
140
+
141
+ ```typescript
142
+ function clamp(value: number, min: number, max: number): number
143
+ ```
144
+
145
+ - `value` — Value to clamp.
146
+ - `min` — Minimum (inclusive).
147
+ - `max` — Maximum (inclusive).
148
+
149
+ **Returns:** The clamped value.
150
+
151
+ #### `seekTimeFromClick(x, width, duration)`
152
+
153
+ Compute the seek time (in seconds) for a click at horizontal pixel
154
+ `x` inside a waveform bounding box of `width` pixels covering an
155
+ audio of `duration` seconds. Clamps the result into `[0, duration]`.
156
+
157
+ ```typescript
158
+ function seekTimeFromClick(x: number, width: number, duration: number): number
5
159
  ```
6
- npm install @molecule/app-feature-audio-waveform-vue
160
+
161
+ - `x` — Horizontal pixel offset of the click inside the bounding box.
162
+ - `width` — Width of the bounding box in pixels.
163
+ - `duration` — Total audio duration in seconds.
164
+
165
+ **Returns:** The seek target time, in seconds.
166
+
167
+ ### Constants
168
+
169
+ #### `AudioWaveform`
170
+
171
+ Stylized SVG audio waveform with click-to-seek + region overlays.
172
+ Renders pre-computed peak amplitudes as vertical bars centered on a
173
+ baseline. A progress overlay fills the played portion from the left;
174
+ region markers render as colored rectangles spanning their time range.
175
+
176
+ All styling routes through `getClassMap()` and all user-visible text
177
+ routes through `t()` so the waveform translates via the companion
178
+ `@molecule/app-locales-feature-audio-waveform` locale bond.
179
+
180
+ ```typescript
181
+ const AudioWaveform: DefineComponent<
182
+ ExtractPropTypes<{
183
+ peaks: { type: PropType<number[]>; required: true }
184
+ duration: { type: NumberConstructor; required: true }
185
+ currentTime: { type: NumberConstructor; default: number }
186
+ onSeek: { type: PropType<(seekTime: number) => void>; default: undefined }
187
+ regions: { type: PropType<WaveformRegion[]>; default: undefined }
188
+ height: { type: NumberConstructor; default: number }
189
+ progressColor: { type: StringConstructor; default: undefined }
190
+ waveColor: { type: StringConstructor; default: undefined }
191
+ className: { type: StringConstructor; default: undefined }
192
+ }>,
193
+ () => VNode,
194
+ {},
195
+ {},
196
+ {},
197
+ ComponentOptionsMixin,
198
+ ComponentOptionsMixin,
199
+ {},
200
+ string,
201
+ PublicProps,
202
+ Readonly<
203
+ ExtractPropTypes<{
204
+ peaks: { type: PropType<number[]>; required: true }
205
+ duration: { type: NumberConstructor; required: true }
206
+ currentTime: { type: NumberConstructor; default: number }
207
+ onSeek: { type: PropType<(seekTime: number) => void>; default: undefined }
208
+ regions: { type: PropType<WaveformRegion[]>; default: undefined }
209
+ height: { type: NumberConstructor; default: number }
210
+ progressColor: { type: StringConstructor; default: undefined }
211
+ waveColor: { type: StringConstructor; default: undefined }
212
+ className: { type: StringConstructor; default: undefined }
213
+ }>
214
+ > &
215
+ Readonly<{}>,
216
+ {
217
+ currentTime: number
218
+ onSeek: (seekTime: number) => void
219
+ regions: WaveformRegion[]
220
+ height: number
221
+ progressColor: string
222
+ waveColor: string
223
+ className: string
224
+ },
225
+ {},
226
+ {},
227
+ {},
228
+ string,
229
+ ComponentProvideOptions,
230
+ true,
231
+ {},
232
+ any
233
+ >
7
234
  ```
8
235
 
9
- Part of the [Molecule](https://www.molecule.dev) package fleet. This page carries the manifest summary; the full generated documentation ships with the package's first committed version.
236
+ - `props` — Component props (see {@link AudioWaveformProps}).
237
+
238
+ **Returns:** The audio-waveform element.
239
+
240
+ ## Injection Notes
241
+
242
+ ### Requirements
243
+
244
+ Peer dependencies:
245
+
246
+ - `@molecule/app-ui` ^1.0.1
247
+ - `@molecule/app-ui-vue` ^1.1.0
248
+ - `@molecule/app-vue` ^3.5.0
249
+ - `vue` ^3.4.0
250
+
251
+ ### Runtime Dependencies
252
+
253
+ - `@molecule/app-ui`
254
+ - `@molecule/app-ui-vue`
255
+ - `@molecule/app-vue`
256
+ - `vue`
257
+
258
+ - Requires a bonded ClassMap — rendering throws otherwise.
259
+ - Text (aria labels + the empty state) routes through the binding's
260
+ `useTranslation()`, so a locale switch re-renders it.
261
+
262
+ ## Translations
10
263
 
11
- License: Apache-2.0
264
+ Translation strings are provided by `@molecule/app-locales-feature-audio-waveform`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-feature-audio-waveform-vue",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Stylized SVG audio waveform with click-to-seek + region overlays — renders pre-computed peaks for music-daw / podcast / streaming",
5
5
  "homepage": "https://www.molecule.dev/packages/app-feature-audio-waveform-vue",
6
6
  "type": "module",
@@ -55,9 +55,9 @@
55
55
  "@molecule/app-framework-conformance": "0.0.0",
56
56
  "@molecule/app-i18n": "1.2.2",
57
57
  "@molecule/app-icons": "1.0.4",
58
- "@molecule/app-ui": "1.4.0",
59
- "@molecule/app-ui-vue": "1.1.5",
60
- "@molecule/app-vue": "3.7.2",
58
+ "@molecule/app-ui": "1.5.0",
59
+ "@molecule/app-ui-vue": "1.2.1",
60
+ "@molecule/app-vue": "3.9.0",
61
61
  "@types/node": "26.6.5",
62
62
  "jsdom": "30.1.3",
63
63
  "typescript": "6.0.3",