@molecule/app-feature-video-timeline-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 +455 -4
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,11 +1,462 @@
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:33.694Z
7
+ -->
8
+
1
9
  # @molecule/app-feature-video-timeline-vue
2
10
 
3
- Multi-track video timeline composing track-lane rows with a time ruler, playhead, zoom controls, and ripple/insert edit modes
11
+ Vue multi-track video timeline for video editors, DAWs and animation tools.
12
+ Composes one `<TrackLane>` per track row with a shared time ruler, playhead,
13
+ zoom slider + Ctrl+wheel zoom, and ripple/insert edit modes.
14
+
15
+ Vue counterpart of `@molecule/app-feature-video-timeline-react`: the same
16
+ props (React names), the same DOM for the same input, and the same callback
17
+ calls, so an app switches framework by changing only the package name it
18
+ imports.
19
+
20
+ Exports `<VideoTimeline>`, the `Track` and `VideoTimelineMode` types,
21
+ and the pure-function helpers `clampZoom`, `zoomFromWheelDelta`,
22
+ `computeRulerTicks`, `computeRippleUpdates`, and `formatTickTime`
23
+ that back the zoom math, ruler tick generation, and ripple-mode
24
+ fan-out.
25
+
26
+ > **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
27
+ > It is written to be read by coding agents as much as by people, and is generated from this
28
+ > package's source — edit `src/index.ts` JSDoc, not this file.
29
+
30
+ ## Quick Start
31
+
32
+ ```ts
33
+ import { createApp, defineComponent, h, ref } from 'vue'
34
+ import { VideoTimeline } from '@molecule/app-feature-video-timeline-vue'
35
+
36
+ const App = defineComponent({
37
+ setup() {
38
+ const currentTime = ref(3.2)
39
+ const zoom = ref(20)
40
+ return () =>
41
+ h(VideoTimeline, {
42
+ tracks: [
43
+ {
44
+ id: 'v1',
45
+ kind: 'video',
46
+ clips: [{ id: 'a', startTime: 0, duration: 5, label: 'Intro' }],
47
+ },
48
+ {
49
+ id: 'a1',
50
+ kind: 'audio',
51
+ clips: [{ id: 'b', startTime: 0, duration: 12 }],
52
+ },
53
+ ],
54
+ currentTime: currentTime.value,
55
+ duration: 60,
56
+ pixelsPerSecond: zoom.value,
57
+ mode: 'ripple',
58
+ onSeek: (t: number) => {
59
+ currentTime.value = t
60
+ },
61
+ onClipMove: (id: string, startTime: number, trackId: string) => {
62
+ updateClip(trackId, id, { startTime })
63
+ },
64
+ onClipResize: (id: string, duration: number, trackId: string) => {
65
+ updateClip(trackId, id, { duration })
66
+ },
67
+ onZoomChange: (pps: number) => {
68
+ zoom.value = pps
69
+ },
70
+ })
71
+ },
72
+ })
73
+
74
+ createApp(App).mount('#app')
75
+ ```
76
+
77
+ ## Type
78
+
79
+ `feature`
80
+
81
+ ## Installation
82
+
83
+ ```bash
84
+ npm install @molecule/app-feature-video-timeline-vue @molecule/app-feature-track-lane-vue @molecule/app-ui @molecule/app-ui-vue @molecule/app-vue vue
85
+ ```
86
+
87
+ ## API
88
+
89
+ ### Interfaces
90
+
91
+ #### `Track`
92
+
93
+ One track row on a `<VideoTimeline>`. Tracks are rendered in array
94
+ order top-to-bottom and each track delegates clip rendering to a
95
+ `<TrackLane>` row.
96
+
97
+ ```typescript
98
+ interface Track {
99
+ /** Stable identifier — used as the row key and lane id passed to handlers. */
100
+ id: string
101
+ /** The kind of media on this track. */
102
+ kind: TrackKind
103
+ /** Clips on this track. Order is preserved as-is. */
104
+ clips: Clip[]
105
+ /** Optional human-friendly track name; falls back to a translated kind label. */
106
+ name?: string
107
+ }
108
+ ```
109
+
110
+ #### `VideoTimelineProps`
111
+
112
+ Props accepted by the {@link VideoTimeline} component — the same props React's accepts.
113
+
114
+ ```typescript
115
+ interface VideoTimelineProps {
116
+ /** Tracks to render. Order is preserved as-is. */
117
+ tracks: Track[]
118
+ /** Current playhead time in seconds. Drives the playhead vertical line. */
119
+ currentTime: number
120
+ /** Total timeline duration in seconds — used to size the scrollable body. */
121
+ duration: number
122
+ /** Called when the user clicks/scrubs the ruler. */
123
+ onSeek?: (time: number) => void
124
+ /** Called when a clip on a lane is dragged horizontally. */
125
+ onClipMove?: (clipId: string, startTime: number, trackId: string) => void
126
+ /** Called when a clip's right-edge resize handle is dragged. */
127
+ onClipResize?: (clipId: string, duration: number, trackId: string) => void
128
+ /** Horizontal scale (px per second). Defaults to 20. */
129
+ pixelsPerSecond?: number
130
+ /** Lower zoom bound for Ctrl+wheel / slider. Defaults to 2. */
131
+ zoomMin?: number
132
+ /** Upper zoom bound for Ctrl+wheel / slider. Defaults to 200. */
133
+ zoomMax?: number
134
+ /** Edit mode for clip drags. Defaults to `'ripple'`. */
135
+ mode?: VideoTimelineMode
136
+ /** Called when the user changes the zoom (slider or Ctrl+wheel). */
137
+ onZoomChange?: (pixelsPerSecond: number) => void
138
+ /** Optional currently-selected clip id. */
139
+ selectedClipId?: string
140
+ /** Called when a clip is clicked (no drag). */
141
+ onClipClick?: (clipId: string, trackId: string) => void
142
+ /** Per-track row height in pixels. Defaults to 44. */
143
+ trackHeight?: number
144
+ /** Width of the leading lane-header column in pixels. Defaults to 120. */
145
+ laneHeaderWidth?: number
146
+ /** Height of the time ruler row in pixels. Defaults to 28. */
147
+ rulerHeight?: number
148
+ /** Extra classes merged onto the root element. */
149
+ className?: string
150
+ }
151
+ ```
152
+
153
+ ### Types
154
+
155
+ #### `TrackKind`
156
+
157
+ The kind of media a track holds. Drives the lane name fallback,
158
+ the default clip color, and the data attribute parents can hook
159
+ onto for kind-specific styling.
160
+
161
+ ```typescript
162
+ type TrackKind = 'video' | 'audio' | 'subtitle'
163
+ ```
164
+
165
+ #### `VideoTimelineMode`
166
+
167
+ Edit mode applied to clip drags.
168
+
169
+ - `insert` — dragging a clip just drops it at the new position; other clips
170
+ on the lane stay where they are.
171
+ - `ripple` — dragging a clip shifts every later clip on the same lane by
172
+ the same delta, preserving inter-clip gaps.
173
+
174
+ ```typescript
175
+ type VideoTimelineMode = 'ripple' | 'insert'
176
+ ```
177
+
178
+ ### Functions
179
+
180
+ #### `clampZoom(value, min, max)`
181
+
182
+ Clamp a candidate `pixelsPerSecond` value into `[min, max]`. Used by
183
+ the zoom slider, Ctrl+wheel, and any external zoom button that calls
184
+ `onZoomChange`.
185
+
186
+ ```typescript
187
+ function clampZoom(value: number, min: number, max: number): number
188
+ ```
189
+
190
+ - `value` — Candidate horizontal scale in px/sec.
191
+ - `min` — Lower bound (inclusive).
192
+ - `max` — Upper bound (inclusive).
193
+
194
+ **Returns:** The clamped value.
195
+
196
+ #### `zoomFromWheelDelta(current, deltaY, min, max)`
197
+
198
+ Compute the next zoom value for a Ctrl+wheel notch. Negative `deltaY`
199
+ (scroll-up) zooms in; positive zooms out. Result is clamped into
200
+ `[min, max]`.
201
+
202
+ ```typescript
203
+ function zoomFromWheelDelta(current: number, deltaY: number, min: number, max: number): number
204
+ ```
205
+
206
+ - `current` — Current `pixelsPerSecond`.
207
+ - `deltaY` — Wheel `deltaY` (sign-only — magnitude is ignored).
208
+ - `min` — Lower zoom bound.
209
+ - `max` — Upper zoom bound.
210
+
211
+ **Returns:** The clamped next zoom value.
212
+
213
+ #### `computeRulerTicks(duration, pixelsPerSecond)`
214
+
215
+ Compute time tick marks for the ruler. Picks an interval (1, 2, 5, 10,
216
+ 30, or 60 seconds, etc.) so that adjacent ticks are at least
217
+ `MIN_TICK_PIXEL_SPACING` apart on screen. Always emits a tick at 0 and
218
+ stops at the last tick `<= duration`.
219
+
220
+ ```typescript
221
+ function computeRulerTicks(
222
+ duration: number,
223
+ pixelsPerSecond: number,
224
+ ): { time: number; pixel: number }[]
225
+ ```
226
+
227
+ - `duration` — Total duration in seconds.
228
+ - `pixelsPerSecond` — Horizontal scale.
229
+
230
+ **Returns:** Tick descriptors with `{ time, pixel }`.
231
+
232
+ #### `computeRippleUpdates(clips, draggedClipId, proposedStartTime)`
233
+
234
+ Compute the ripple-mode update for a clip drag on a single lane.
235
+ Returns one update per affected clip — at minimum the dragged clip,
236
+ plus every clip whose original `startTime` is strictly greater (which
237
+ shifts by the same `delta`).
4
238
 
239
+ Negative deltas are clamped so no clip's `startTime` goes below 0
240
+ (the dragged clip is the limiting factor — later clips can never
241
+ cross zero before it does, since they all started later).
242
+
243
+ ```typescript
244
+ function computeRippleUpdates(
245
+ clips: Clip[],
246
+ draggedClipId: string,
247
+ proposedStartTime: number,
248
+ ): { id: string; startTime: number }[]
249
+ ```
250
+
251
+ - `clips` — All clips on the lane (any order).
252
+ - `draggedClipId` — The id of the clip being dragged.
253
+ - `proposedStartTime` — The candidate new `startTime` for the dragged clip.
254
+
255
+ **Returns:** Array of `{ id, startTime }` updates to apply.
256
+
257
+ #### `formatTickTime(seconds)`
258
+
259
+ Format a tick time for the ruler — `mm:ss` over a minute, `s.s` below.
260
+
261
+ ```typescript
262
+ function formatTickTime(seconds: number): string
263
+ ```
264
+
265
+ - `seconds` — Time in seconds.
266
+
267
+ **Returns:** Formatted string for the tick label.
268
+
269
+ ### Constants
270
+
271
+ #### `VideoTimeline`
272
+
273
+ Multi-track video timeline. Composes one `<TrackLane>` per track with
274
+ a shared time ruler at the top, a vertical playhead, and a zoom slider
275
+ row. Pointer-down on the ruler scrubs `onSeek`; Ctrl+wheel anywhere
276
+ over the body changes zoom; the slider is keyboard-accessible.
277
+
278
+ In `'ripple'` mode (default), dragging a clip on a lane shifts every
279
+ subsequent clip on that lane by the same delta — `onClipMove` is
280
+ called once per affected clip. In `'insert'` mode, only the dragged
281
+ clip moves.
282
+
283
+ ```typescript
284
+ const VideoTimeline: DefineComponent<
285
+ ExtractPropTypes<{
286
+ tracks: { type: PropType<Track[]>; required: true }
287
+ currentTime: { type: NumberConstructor; required: true }
288
+ duration: { type: NumberConstructor; required: true }
289
+ onSeek: { type: PropType<VideoTimelineProps['onSeek']>; default: undefined }
290
+ onClipMove: { type: PropType<VideoTimelineProps['onClipMove']>; default: undefined }
291
+ onClipResize: { type: PropType<VideoTimelineProps['onClipResize']>; default: undefined }
292
+ pixelsPerSecond: { type: PropType<number | undefined>; default: undefined }
293
+ zoomMin: { type: PropType<number | undefined>; default: undefined }
294
+ zoomMax: { type: PropType<number | undefined>; default: undefined }
295
+ mode: { type: PropType<VideoTimelineMode | undefined>; default: undefined }
296
+ onZoomChange: { type: PropType<VideoTimelineProps['onZoomChange']>; default: undefined }
297
+ selectedClipId: { type: PropType<string | undefined>; default: undefined }
298
+ onClipClick: { type: PropType<VideoTimelineProps['onClipClick']>; default: undefined }
299
+ trackHeight: { type: PropType<number | undefined>; default: undefined }
300
+ laneHeaderWidth: { type: PropType<number | undefined>; default: undefined }
301
+ rulerHeight: { type: PropType<number | undefined>; default: undefined }
302
+ className: { type: PropType<string | undefined>; default: undefined }
303
+ }>,
304
+ () => VNode,
305
+ {},
306
+ {},
307
+ {},
308
+ ComponentOptionsMixin,
309
+ ComponentOptionsMixin,
310
+ {},
311
+ string,
312
+ PublicProps,
313
+ Readonly<
314
+ ExtractPropTypes<{
315
+ tracks: { type: PropType<Track[]>; required: true }
316
+ currentTime: { type: NumberConstructor; required: true }
317
+ duration: { type: NumberConstructor; required: true }
318
+ onSeek: { type: PropType<VideoTimelineProps['onSeek']>; default: undefined }
319
+ onClipMove: { type: PropType<VideoTimelineProps['onClipMove']>; default: undefined }
320
+ onClipResize: { type: PropType<VideoTimelineProps['onClipResize']>; default: undefined }
321
+ pixelsPerSecond: { type: PropType<number | undefined>; default: undefined }
322
+ zoomMin: { type: PropType<number | undefined>; default: undefined }
323
+ zoomMax: { type: PropType<number | undefined>; default: undefined }
324
+ mode: { type: PropType<VideoTimelineMode | undefined>; default: undefined }
325
+ onZoomChange: { type: PropType<VideoTimelineProps['onZoomChange']>; default: undefined }
326
+ selectedClipId: { type: PropType<string | undefined>; default: undefined }
327
+ onClipClick: { type: PropType<VideoTimelineProps['onClipClick']>; default: undefined }
328
+ trackHeight: { type: PropType<number | undefined>; default: undefined }
329
+ laneHeaderWidth: { type: PropType<number | undefined>; default: undefined }
330
+ rulerHeight: { type: PropType<number | undefined>; default: undefined }
331
+ className: { type: PropType<string | undefined>; default: undefined }
332
+ }>
333
+ > &
334
+ Readonly<{}>,
335
+ {
336
+ onSeek: ((time: number) => void) | undefined
337
+ onClipMove: ((clipId: string, startTime: number, trackId: string) => void) | undefined
338
+ onClipResize: ((clipId: string, duration: number, trackId: string) => void) | undefined
339
+ onZoomChange: ((pixelsPerSecond: number) => void) | undefined
340
+ onClipClick: ((clipId: string, trackId: string) => void) | undefined
341
+ pixelsPerSecond: number | undefined
342
+ zoomMin: number | undefined
343
+ zoomMax: number | undefined
344
+ mode: VideoTimelineMode | undefined
345
+ selectedClipId: string | undefined
346
+ trackHeight: number | undefined
347
+ laneHeaderWidth: number | undefined
348
+ rulerHeight: number | undefined
349
+ className: string | undefined
350
+ },
351
+ {},
352
+ {},
353
+ {},
354
+ string,
355
+ ComponentProvideOptions,
356
+ true,
357
+ {},
358
+ any
359
+ >
360
+ ```
361
+
362
+ - `props` — Component props (see {@link VideoTimelineProps}).
363
+
364
+ **Returns:** The multi-track timeline component.
365
+
366
+ #### `DEFAULT_PIXELS_PER_SECOND`
367
+
368
+ Default horizontal scale.
369
+
370
+ ```typescript
371
+ const DEFAULT_PIXELS_PER_SECOND: 20
5
372
  ```
6
- npm install @molecule/app-feature-video-timeline-vue
373
+
374
+ #### `DEFAULT_ZOOM_MIN`
375
+
376
+ Default lower zoom bound.
377
+
378
+ ```typescript
379
+ const DEFAULT_ZOOM_MIN: 2
380
+ ```
381
+
382
+ #### `DEFAULT_ZOOM_MAX`
383
+
384
+ Default upper zoom bound.
385
+
386
+ ```typescript
387
+ const DEFAULT_ZOOM_MAX: 200
7
388
  ```
8
389
 
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.
390
+ #### `DEFAULT_TRACK_HEIGHT`
391
+
392
+ Default per-track row height.
393
+
394
+ ```typescript
395
+ const DEFAULT_TRACK_HEIGHT: 44
396
+ ```
397
+
398
+ #### `DEFAULT_LANE_HEADER_WIDTH`
399
+
400
+ Default lane-header column width.
401
+
402
+ ```typescript
403
+ const DEFAULT_LANE_HEADER_WIDTH: 120
404
+ ```
405
+
406
+ #### `DEFAULT_RULER_HEIGHT`
407
+
408
+ Default ruler height.
409
+
410
+ ```typescript
411
+ const DEFAULT_RULER_HEIGHT: 28
412
+ ```
413
+
414
+ #### `ZOOM_WHEEL_FACTOR`
415
+
416
+ Multiplier per Ctrl+wheel notch (positive deltaY zooms out).
417
+
418
+ ```typescript
419
+ const ZOOM_WHEEL_FACTOR: 1.1
420
+ ```
421
+
422
+ #### `MIN_TICK_PIXEL_SPACING`
423
+
424
+ Minimum spacing (px) between adjacent ruler ticks.
425
+
426
+ ```typescript
427
+ const MIN_TICK_PIXEL_SPACING: 60
428
+ ```
429
+
430
+ ## Injection Notes
431
+
432
+ ### Requirements
433
+
434
+ Peer dependencies:
435
+
436
+ - `@molecule/app-feature-track-lane-vue` ^1.0.0
437
+ - `@molecule/app-ui` ^1.0.1
438
+ - `@molecule/app-ui-vue` ^1.1.0
439
+ - `@molecule/app-vue` ^3.5.0
440
+ - `vue` ^3.4.0
441
+
442
+ ### Runtime Dependencies
443
+
444
+ - `@molecule/app-feature-track-lane-vue`
445
+ - `@molecule/app-ui`
446
+ - `@molecule/app-ui-vue`
447
+ - `@molecule/app-vue`
448
+ - `vue`
449
+
450
+ - Requires a bonded ClassMap (`cm.flex`, `cm.cn`, …) and the binding's i18n
451
+ plugin for the translated labels — rendering throws without a ClassMap.
452
+ - Ripple mode (default) shifts all later clips on the same lane by the same
453
+ delta when a clip is dragged, preserving inter-clip gaps. Switch to
454
+ `mode: 'insert'` to drop the dragged clip at its new position without
455
+ disturbing the rest of the lane.
456
+ - Every visible string comes from `useTranslation()` (`videoTimeline.aria.*`,
457
+ `videoTimeline.trackKind.*`, `videoTimeline.mode.*`, `videoTimeline.zoom.*`),
458
+ so a locale switch re-renders the timeline.
459
+
460
+ ## Translations
10
461
 
11
- License: Apache-2.0
462
+ Translation strings are provided by `@molecule/app-locales-feature-video-timeline`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@molecule/app-feature-video-timeline-vue",
3
- "version": "0.0.1-stage",
3
+ "version": "1.1.0",
4
4
  "description": "Multi-track video timeline composing track-lane rows with a time ruler, playhead, zoom controls, and ripple/insert edit modes",
5
5
  "homepage": "https://www.molecule.dev/packages/app-feature-video-timeline-vue",
6
6
  "type": "module",
@@ -59,9 +59,9 @@
59
59
  "@molecule/app-framework-conformance": "0.0.0",
60
60
  "@molecule/app-i18n": "1.2.2",
61
61
  "@molecule/app-icons": "1.0.4",
62
- "@molecule/app-ui": "1.4.0",
63
- "@molecule/app-ui-vue": "1.1.5",
64
- "@molecule/app-vue": "3.7.2",
62
+ "@molecule/app-ui": "1.5.0",
63
+ "@molecule/app-ui-vue": "1.2.1",
64
+ "@molecule/app-vue": "3.9.0",
65
65
  "@types/node": "26.6.5",
66
66
  "jsdom": "30.1.3",
67
67
  "typescript": "6.0.3",