@molecule/app-feature-video-timeline-solid 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.
- package/README.md +375 -4
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -1,11 +1,382 @@
|
|
|
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.241Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
1
9
|
# @molecule/app-feature-video-timeline-solid
|
|
2
10
|
|
|
3
|
-
|
|
11
|
+
Solid multi-track video timeline for video editors, DAWs and animation
|
|
12
|
+
tools. Composes one `<TrackLane>` per track row with a shared time ruler,
|
|
13
|
+
playhead, zoom slider + Ctrl+wheel zoom, and ripple/insert edit modes.
|
|
14
|
+
|
|
15
|
+
Solid 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
|
+
```tsx
|
|
33
|
+
import { createSignal } from 'solid-js'
|
|
34
|
+
import { VideoTimeline } from '@molecule/app-feature-video-timeline-solid'
|
|
35
|
+
|
|
36
|
+
export function Editor() {
|
|
37
|
+
const [currentTime, setCurrentTime] = createSignal(3.2)
|
|
38
|
+
const [zoom, setZoom] = createSignal(20)
|
|
39
|
+
return (
|
|
40
|
+
<VideoTimeline
|
|
41
|
+
tracks={[
|
|
42
|
+
{
|
|
43
|
+
id: 'v1',
|
|
44
|
+
kind: 'video',
|
|
45
|
+
clips: [{ id: 'a', startTime: 0, duration: 5, label: 'Intro' }],
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
id: 'a1',
|
|
49
|
+
kind: 'audio',
|
|
50
|
+
clips: [{ id: 'b', startTime: 0, duration: 12 }],
|
|
51
|
+
},
|
|
52
|
+
]}
|
|
53
|
+
currentTime={currentTime()}
|
|
54
|
+
duration={60}
|
|
55
|
+
pixelsPerSecond={zoom()}
|
|
56
|
+
mode="ripple"
|
|
57
|
+
onSeek={(t) => setCurrentTime(t)}
|
|
58
|
+
onClipMove={(id, startTime, trackId) => updateClip(trackId, id, { startTime })}
|
|
59
|
+
onClipResize={(id, duration, trackId) => updateClip(trackId, id, { duration })}
|
|
60
|
+
onZoomChange={(pps) => setZoom(pps)}
|
|
61
|
+
/>
|
|
62
|
+
)
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Type
|
|
67
|
+
|
|
68
|
+
`feature`
|
|
69
|
+
|
|
70
|
+
## Installation
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
npm install @molecule/app-feature-video-timeline-solid @molecule/app-feature-track-lane-solid @molecule/app-solid @molecule/app-ui @molecule/app-ui-solid solid-js
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## API
|
|
77
|
+
|
|
78
|
+
### Interfaces
|
|
79
|
+
|
|
80
|
+
#### `Track`
|
|
81
|
+
|
|
82
|
+
One track row on a `<VideoTimeline>`. Tracks are rendered in array
|
|
83
|
+
order top-to-bottom and each track delegates clip rendering to a
|
|
84
|
+
`<TrackLane>` row.
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
interface Track {
|
|
88
|
+
/** Stable identifier — used as the row key and lane id passed to handlers. */
|
|
89
|
+
id: string
|
|
90
|
+
/** The kind of media on this track. */
|
|
91
|
+
kind: TrackKind
|
|
92
|
+
/** Clips on this track. Order is preserved as-is. */
|
|
93
|
+
clips: Clip[]
|
|
94
|
+
/** Optional human-friendly track name; falls back to a translated kind label. */
|
|
95
|
+
name?: string
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
#### `VideoTimelineProps`
|
|
100
|
+
|
|
101
|
+
Props accepted by the {@link VideoTimeline} component — the same props React's accepts.
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
interface VideoTimelineProps {
|
|
105
|
+
/** Tracks to render. Order is preserved as-is. */
|
|
106
|
+
tracks: Track[]
|
|
107
|
+
/** Current playhead time in seconds. Drives the playhead vertical line. */
|
|
108
|
+
currentTime: number
|
|
109
|
+
/** Total timeline duration in seconds — used to size the scrollable body. */
|
|
110
|
+
duration: number
|
|
111
|
+
/** Called when the user clicks/scrubs the ruler. */
|
|
112
|
+
onSeek?: (time: number) => void
|
|
113
|
+
/** Called when a clip on a lane is dragged horizontally. */
|
|
114
|
+
onClipMove?: (clipId: string, startTime: number, trackId: string) => void
|
|
115
|
+
/** Called when a clip's right-edge resize handle is dragged. */
|
|
116
|
+
onClipResize?: (clipId: string, duration: number, trackId: string) => void
|
|
117
|
+
/** Horizontal scale (px per second). Defaults to 20. */
|
|
118
|
+
pixelsPerSecond?: number
|
|
119
|
+
/** Lower zoom bound for Ctrl+wheel / slider. Defaults to 2. */
|
|
120
|
+
zoomMin?: number
|
|
121
|
+
/** Upper zoom bound for Ctrl+wheel / slider. Defaults to 200. */
|
|
122
|
+
zoomMax?: number
|
|
123
|
+
/** Edit mode for clip drags. Defaults to `'ripple'`. */
|
|
124
|
+
mode?: VideoTimelineMode
|
|
125
|
+
/** Called when the user changes the zoom (slider or Ctrl+wheel). */
|
|
126
|
+
onZoomChange?: (pixelsPerSecond: number) => void
|
|
127
|
+
/** Optional currently-selected clip id. */
|
|
128
|
+
selectedClipId?: string
|
|
129
|
+
/** Called when a clip is clicked (no drag). */
|
|
130
|
+
onClipClick?: (clipId: string, trackId: string) => void
|
|
131
|
+
/** Per-track row height in pixels. Defaults to 44. */
|
|
132
|
+
trackHeight?: number
|
|
133
|
+
/** Width of the leading lane-header column in pixels. Defaults to 120. */
|
|
134
|
+
laneHeaderWidth?: number
|
|
135
|
+
/** Height of the time ruler row in pixels. Defaults to 28. */
|
|
136
|
+
rulerHeight?: number
|
|
137
|
+
/** Extra classes merged onto the root element. */
|
|
138
|
+
className?: string
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Types
|
|
143
|
+
|
|
144
|
+
#### `TrackKind`
|
|
145
|
+
|
|
146
|
+
The kind of media a track holds. Drives the lane name fallback,
|
|
147
|
+
the default clip color, and the data attribute parents can hook
|
|
148
|
+
onto for kind-specific styling.
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
type TrackKind = 'video' | 'audio' | 'subtitle'
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
#### `VideoTimelineMode`
|
|
155
|
+
|
|
156
|
+
Edit mode applied to clip drags.
|
|
157
|
+
|
|
158
|
+
- `insert` — dragging a clip just drops it at the new position; other clips
|
|
159
|
+
on the lane stay where they are.
|
|
160
|
+
- `ripple` — dragging a clip shifts every later clip on the same lane by
|
|
161
|
+
the same delta, preserving inter-clip gaps.
|
|
162
|
+
|
|
163
|
+
```typescript
|
|
164
|
+
type VideoTimelineMode = 'ripple' | 'insert'
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Functions
|
|
168
|
+
|
|
169
|
+
#### `VideoTimeline(props)`
|
|
170
|
+
|
|
171
|
+
Multi-track video timeline. Composes one `<TrackLane>` per track with
|
|
172
|
+
a shared time ruler at the top, a vertical playhead, and a zoom slider
|
|
173
|
+
row. Pointer-down on the ruler scrubs `onSeek`; Ctrl+wheel anywhere
|
|
174
|
+
over the body changes zoom; the slider is keyboard-accessible.
|
|
175
|
+
|
|
176
|
+
In `'ripple'` mode (default), dragging a clip on a lane shifts every
|
|
177
|
+
subsequent clip on that lane by the same delta — `onClipMove` is
|
|
178
|
+
called once per affected clip. In `'insert'` mode, only the dragged
|
|
179
|
+
clip moves.
|
|
180
|
+
|
|
181
|
+
React keys each track row by its `id` value, so a re-passed or re-ordered
|
|
182
|
+
array keeps the rendered rows per id. Solid's `For` keys by reference, so
|
|
183
|
+
the rows are keyed through stable per-id records: the record for an id is
|
|
184
|
+
created once and reused, while the row's content reads the CURRENT track
|
|
185
|
+
for that id reactively.
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
function VideoTimeline(props: VideoTimelineProps): JSX.Element
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
- `props` — Component props (see {@link VideoTimelineProps}).
|
|
192
|
+
|
|
193
|
+
**Returns:** The multi-track timeline.
|
|
194
|
+
|
|
195
|
+
#### `clampZoom(value, min, max)`
|
|
196
|
+
|
|
197
|
+
Clamp a candidate `pixelsPerSecond` value into `[min, max]`. Used by
|
|
198
|
+
the zoom slider, Ctrl+wheel, and any external zoom button that calls
|
|
199
|
+
`onZoomChange`.
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
function clampZoom(value: number, min: number, max: number): number
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
- `value` — Candidate horizontal scale in px/sec.
|
|
206
|
+
- `min` — Lower bound (inclusive).
|
|
207
|
+
- `max` — Upper bound (inclusive).
|
|
208
|
+
|
|
209
|
+
**Returns:** The clamped value.
|
|
210
|
+
|
|
211
|
+
#### `zoomFromWheelDelta(current, deltaY, min, max)`
|
|
212
|
+
|
|
213
|
+
Compute the next zoom value for a Ctrl+wheel notch. Negative `deltaY`
|
|
214
|
+
(scroll-up) zooms in; positive zooms out. Result is clamped into
|
|
215
|
+
`[min, max]`.
|
|
216
|
+
|
|
217
|
+
```typescript
|
|
218
|
+
function zoomFromWheelDelta(current: number, deltaY: number, min: number, max: number): number
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
- `current` — Current `pixelsPerSecond`.
|
|
222
|
+
- `deltaY` — Wheel `deltaY` (sign-only — magnitude is ignored).
|
|
223
|
+
- `min` — Lower zoom bound.
|
|
224
|
+
- `max` — Upper zoom bound.
|
|
225
|
+
|
|
226
|
+
**Returns:** The clamped next zoom value.
|
|
227
|
+
|
|
228
|
+
#### `computeRulerTicks(duration, pixelsPerSecond)`
|
|
4
229
|
|
|
230
|
+
Compute time tick marks for the ruler. Picks an interval (1, 2, 5, 10,
|
|
231
|
+
30, or 60 seconds, etc.) so that adjacent ticks are at least
|
|
232
|
+
`MIN_TICK_PIXEL_SPACING` apart on screen. Always emits a tick at 0 and
|
|
233
|
+
stops at the last tick `<= duration`.
|
|
234
|
+
|
|
235
|
+
```typescript
|
|
236
|
+
function computeRulerTicks(
|
|
237
|
+
duration: number,
|
|
238
|
+
pixelsPerSecond: number,
|
|
239
|
+
): { time: number; pixel: number }[]
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
- `duration` — Total duration in seconds.
|
|
243
|
+
- `pixelsPerSecond` — Horizontal scale.
|
|
244
|
+
|
|
245
|
+
**Returns:** Tick descriptors with `{ time, pixel }`.
|
|
246
|
+
|
|
247
|
+
#### `computeRippleUpdates(clips, draggedClipId, proposedStartTime)`
|
|
248
|
+
|
|
249
|
+
Compute the ripple-mode update for a clip drag on a single lane.
|
|
250
|
+
Returns one update per affected clip — at minimum the dragged clip,
|
|
251
|
+
plus every clip whose original `startTime` is strictly greater (which
|
|
252
|
+
shifts by the same `delta`).
|
|
253
|
+
|
|
254
|
+
Negative deltas are clamped so no clip's `startTime` goes below 0
|
|
255
|
+
(the dragged clip is the limiting factor — later clips can never
|
|
256
|
+
cross zero before it does, since they all started later).
|
|
257
|
+
|
|
258
|
+
```typescript
|
|
259
|
+
function computeRippleUpdates(
|
|
260
|
+
clips: Clip[],
|
|
261
|
+
draggedClipId: string,
|
|
262
|
+
proposedStartTime: number,
|
|
263
|
+
): { id: string; startTime: number }[]
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
- `clips` — All clips on the lane (any order).
|
|
267
|
+
- `draggedClipId` — The id of the clip being dragged.
|
|
268
|
+
- `proposedStartTime` — The candidate new `startTime` for the dragged clip.
|
|
269
|
+
|
|
270
|
+
**Returns:** Array of `{ id, startTime }` updates to apply.
|
|
271
|
+
|
|
272
|
+
#### `formatTickTime(seconds)`
|
|
273
|
+
|
|
274
|
+
Format a tick time for the ruler — `mm:ss` over a minute, `s.s` below.
|
|
275
|
+
|
|
276
|
+
```typescript
|
|
277
|
+
function formatTickTime(seconds: number): string
|
|
5
278
|
```
|
|
6
|
-
|
|
279
|
+
|
|
280
|
+
- `seconds` — Time in seconds.
|
|
281
|
+
|
|
282
|
+
**Returns:** Formatted string for the tick label.
|
|
283
|
+
|
|
284
|
+
### Constants
|
|
285
|
+
|
|
286
|
+
#### `DEFAULT_PIXELS_PER_SECOND`
|
|
287
|
+
|
|
288
|
+
Default horizontal scale.
|
|
289
|
+
|
|
290
|
+
```typescript
|
|
291
|
+
const DEFAULT_PIXELS_PER_SECOND: 20
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
#### `DEFAULT_ZOOM_MIN`
|
|
295
|
+
|
|
296
|
+
Default lower zoom bound.
|
|
297
|
+
|
|
298
|
+
```typescript
|
|
299
|
+
const DEFAULT_ZOOM_MIN: 2
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
#### `DEFAULT_ZOOM_MAX`
|
|
303
|
+
|
|
304
|
+
Default upper zoom bound.
|
|
305
|
+
|
|
306
|
+
```typescript
|
|
307
|
+
const DEFAULT_ZOOM_MAX: 200
|
|
7
308
|
```
|
|
8
309
|
|
|
9
|
-
|
|
310
|
+
#### `DEFAULT_TRACK_HEIGHT`
|
|
311
|
+
|
|
312
|
+
Default per-track row height.
|
|
313
|
+
|
|
314
|
+
```typescript
|
|
315
|
+
const DEFAULT_TRACK_HEIGHT: 44
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
#### `DEFAULT_LANE_HEADER_WIDTH`
|
|
319
|
+
|
|
320
|
+
Default lane-header column width.
|
|
321
|
+
|
|
322
|
+
```typescript
|
|
323
|
+
const DEFAULT_LANE_HEADER_WIDTH: 120
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
#### `DEFAULT_RULER_HEIGHT`
|
|
327
|
+
|
|
328
|
+
Default ruler height.
|
|
329
|
+
|
|
330
|
+
```typescript
|
|
331
|
+
const DEFAULT_RULER_HEIGHT: 28
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
#### `ZOOM_WHEEL_FACTOR`
|
|
335
|
+
|
|
336
|
+
Multiplier per Ctrl+wheel notch (positive deltaY zooms out).
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
const ZOOM_WHEEL_FACTOR: 1.1
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
#### `MIN_TICK_PIXEL_SPACING`
|
|
343
|
+
|
|
344
|
+
Minimum spacing (px) between adjacent ruler ticks.
|
|
345
|
+
|
|
346
|
+
```typescript
|
|
347
|
+
const MIN_TICK_PIXEL_SPACING: 60
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
## Injection Notes
|
|
351
|
+
|
|
352
|
+
### Requirements
|
|
353
|
+
|
|
354
|
+
Peer dependencies:
|
|
355
|
+
|
|
356
|
+
- `@molecule/app-feature-track-lane-solid` ^1.0.0
|
|
357
|
+
- `@molecule/app-solid` ^3.5.0
|
|
358
|
+
- `@molecule/app-ui` ^1.0.1
|
|
359
|
+
- `@molecule/app-ui-solid` ^1.1.0
|
|
360
|
+
- `solid-js` ^1.8.0
|
|
361
|
+
|
|
362
|
+
### Runtime Dependencies
|
|
363
|
+
|
|
364
|
+
- `@molecule/app-feature-track-lane-solid`
|
|
365
|
+
- `@molecule/app-solid`
|
|
366
|
+
- `@molecule/app-ui`
|
|
367
|
+
- `@molecule/app-ui-solid`
|
|
368
|
+
- `solid-js`
|
|
369
|
+
|
|
370
|
+
- Requires a bonded ClassMap (`cm.flex`, `cm.cn`, …) and the binding's i18n
|
|
371
|
+
provider for the translated labels — rendering throws without a ClassMap.
|
|
372
|
+
- Ripple mode (default) shifts all later clips on the same lane by the same
|
|
373
|
+
delta when a clip is dragged, preserving inter-clip gaps. Switch to
|
|
374
|
+
`mode="insert"` to drop the dragged clip at its new position without
|
|
375
|
+
disturbing the rest of the lane.
|
|
376
|
+
- Every visible string comes from `useTranslation()` (`videoTimeline.aria.*`,
|
|
377
|
+
`videoTimeline.trackKind.*`, `videoTimeline.mode.*`, `videoTimeline.zoom.*`),
|
|
378
|
+
so a locale switch re-renders the timeline.
|
|
379
|
+
|
|
380
|
+
## Translations
|
|
10
381
|
|
|
11
|
-
|
|
382
|
+
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-solid",
|
|
3
|
-
"version": "
|
|
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-solid",
|
|
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-solid": "3.
|
|
63
|
-
"@molecule/app-ui": "1.
|
|
64
|
-
"@molecule/app-ui-solid": "1.1
|
|
62
|
+
"@molecule/app-solid": "3.9.0",
|
|
63
|
+
"@molecule/app-ui": "1.5.0",
|
|
64
|
+
"@molecule/app-ui-solid": "1.2.1",
|
|
65
65
|
"@types/node": "26.6.5",
|
|
66
66
|
"jsdom": "30.1.3",
|
|
67
67
|
"solid-js": "1.9.17",
|