@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.
Files changed (2) hide show
  1. package/README.md +375 -4
  2. 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
- Multi-track video timeline composing track-lane rows with a time ruler, playhead, zoom controls, and ripple/insert edit modes
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
- npm install @molecule/app-feature-video-timeline-solid
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
- 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.
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
- License: Apache-2.0
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": "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-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.7.2",
63
- "@molecule/app-ui": "1.4.0",
64
- "@molecule/app-ui-solid": "1.1.5",
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",