@linker-design-plus/timeline-track 2.1.3 → 2.1.4

package/dist/components/track/Track.d.ts

@@ -35,6 +35,7 @@ export declare class Track {
     private onClipSelect;
     private onTimeJump;
     private onClipOverlap?;
+    private onPrimaryTrackMagnetMove?;
     private hasBoundGlobalPointerListenersForDrag;
     private hasLockedGlobalCursor;
     private edgeAutoScrollAnimationFrameId;
@@ -56,7 +57,7 @@ export declare class Track {
     private handleGlobalPointerMove;
     private handleGlobalPointerEnd;
     private handleWindowBlur;
-    constructor(layer: Konva.Layer, config: TrackConfig, trackType: TrackType, zoom: number, trackY: number, trackHeight: number, theme: Theme, onClipUpdate: (clip: ClipType, originalClip?: ClipType, clipUpdates?: ClipStateUpdate[]) => void, onClipAdd: (clip: ClipType) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: ClipType, clip2: ClipType) => void, onClipSelect: (clip: ClipType) => void, onTimeJump: (time: TimeMs) => void, onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number, onClipOverlap?: (clip: ClipType, currentTrackId: string, originalClip?: ClipType | null) => void, onClipCrossTrackPreview?: (clip: ClipType, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear', onClipCrossTrack?: (clip: ClipType, originalClip: ClipType | null, targetTrackY: number, currentTrackId: string) => boolean | void, onClearDropPreview?: () => void, onClearSelection?: () => void, onSnapGuideChange?: (guideTime: TimeMs | null) => void, onClipToggleSelection?: (clipId: string) => void, onSetSingleSelection?: (clipId: string) => void, getMultiDragClipIds?: (clipId: string) => string[] | null, onMultiDragMove?: (request: MultiDragMoveRequest) => boolean | void, onMultiDragInteractionEnd?: () => void, dragActivationThreshold?: number, enableClipSnap?: boolean, clipSnapThreshold?: number);
+    constructor(layer: Konva.Layer, config: TrackConfig, trackType: TrackType, zoom: number, trackY: number, trackHeight: number, theme: Theme, onClipUpdate: (clip: ClipType, originalClip?: ClipType, clipUpdates?: ClipStateUpdate[]) => void, onClipAdd: (clip: ClipType) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: ClipType, clip2: ClipType) => void, onClipSelect: (clip: ClipType) => void, onTimeJump: (time: TimeMs) => void, onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number, onClipOverlap?: (clip: ClipType, currentTrackId: string, originalClip?: ClipType | null) => void, onPrimaryTrackMagnetMove?: (clip: ClipType, originalClip: ClipType | null, peerClips: ClipType[], currentTrackId: string) => boolean | void, onClipCrossTrackPreview?: (clip: ClipType, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear', onClipCrossTrack?: (clip: ClipType, originalClip: ClipType | null, targetTrackY: number, currentTrackId: string) => boolean | void, onClearDropPreview?: () => void, onClearSelection?: () => void, onSnapGuideChange?: (guideTime: TimeMs | null) => void, onClipToggleSelection?: (clipId: string) => void, onSetSingleSelection?: (clipId: string) => void, getMultiDragClipIds?: (clipId: string) => string[] | null, onMultiDragMove?: (request: MultiDragMoveRequest) => boolean | void, onMultiDragInteractionEnd?: () => void, dragActivationThreshold?: number, enableClipSnap?: boolean, clipSnapThreshold?: number);
     private initClips;
     private ensureDropPreviewGroup;
     private createDropPreviewRect;
@@ -83,6 +84,7 @@ export declare class Track {
     private resolveDraggedClipForInteraction;
     private applyInteractionTransition;
     private handleClipMoveEnd;
+    private compactPrimaryTrackClips;
     private updateAllClips;
     private buildAndSendUpdates;
     private updateHoverCursor;

package/dist/core/controllers/timelinePlaybackViewportFollow.d.ts

@@ -0,0 +1,16 @@
+import type { TimeMs } from '../models/types';
+export declare const PLAYBACK_VIEWPORT_FOLLOW_MARGIN_PX = 48;
+export declare function getPlayheadScreenX(time: TimeMs, zoom: number, scrollLeft: number): number;
+export interface PlaybackViewportFollowInput {
+    time: TimeMs;
+    zoom: number;
+    scrollLeft: number;
+    viewportWidth: number;
+    contentWidth: number;
+    margin?: number;
+}
+export declare function clampScrollLeft(scrollLeft: number, viewportWidth: number, contentWidth: number): number;
+/**
+ * 播放边距跟随：播放头超出左右安全边距时返回目标 scrollLeft，否则返回 null。
+ */
+export declare function resolveScrollLeftForPlaybackFollow(input: PlaybackViewportFollowInput): number | null;

package/dist/core/controllers/timelineStructureSession.d.ts

@@ -20,6 +20,7 @@ interface TimelineStructureSessionOptions {
     trackCollection: TimelineTrackCollection;
     ensureTrackFromHistorySnapshot: (trackSnapshot: Track, restoreAnchor?: TrackRestoreAnchor | null) => string | null;
     removeClipGaps: () => void;
+    setPrimaryTrackMagnetEnabled: (enabled: boolean) => void;
     loadClipThumbnails?: (clip: Clip) => Promise<boolean> | void;
     addClipToTrack?: (trackId: string, clip: Clip) => boolean;
     removeClip?: (clipId: string) => void;

package/dist/core/facade/timelineManager.d.ts

@@ -89,6 +89,8 @@ export declare class TimelineManager {
     private activeStructureSession;
     private structureSessionDepth;
     private preserveEmptyTracksDepth;
+    private playbackViewportFollowSuspended;
+    private isProgrammaticScrollChange;
     constructor(config?: Partial<TimelineConfig>);
     private createPlaybackAttemptId;
     private refreshPlaybackAttempt;
@@ -134,6 +136,10 @@ export declare class TimelineManager {
     private get selectedClipId();
     private set selectedClipId(value);
     private ensureConfigState;
+    private isPlaybackViewportFollowEnabled;
+    private suspendPlaybackViewportFollowIfUserScrolling;
+    private runProgrammaticScrollChange;
+    private followPlaybackViewportIfNeeded;
     private getCurrentTimeState;
     private getPlayStateState;
     private setPlayStateState;
@@ -247,6 +253,17 @@ export declare class TimelineManager {
     getCurrentTime(): TimeMs;
     setEnableClipSnap(enabled: boolean): void;
     getEnableClipSnap(): boolean;
+    setEnablePrimaryTrackMagnet(enabled: boolean): void;
+    getEnablePrimaryTrackMagnet(): boolean;
+    private setPrimaryTrackMagnetEnabledFromHistory;
+    private setPrimaryTrackMagnetEnabledState;
+    private getPrimaryTrackId;
+    private isPrimaryTrackId;
+    private shouldNormalizePrimaryTrackForTrackIds;
+    private getStableStartOrderedClips;
+    private buildPrimaryTrackContinuousClips;
+    private buildPrimaryTrackMultiDragOrderedClips;
+    private normalizePrimaryTrackInSession;
     setZoom(zoom: number): void;
     /**
      * 以游标（playhead）为中心设置缩放，用于外置 slider 等非幕布上的缩放操作
@@ -415,6 +432,7 @@ export declare class TimelineManager {
     private emitSelectedClipChangeIfNeeded;
     private beginSourceLoading;
     private endSourceLoading;
+    private handlePrimaryTrackMagnetMove;
     private handleClipOverlap;
     private handleClipCrossTrackPreview;
     private handleClipCrossTrack;
@@ -586,6 +604,7 @@ export declare class TimelineManager {
     private resolveMultiDragOverlapTargetTrackId;
     private commitMultiDragPlacements;
     private finalizeMultiDragSameTrack;
+    private compactPrimaryTrackAfterMultiDrag;
     private previewMultiDragCrossTrack;
     private finalizeMultiDragCrossTrack;
     private resolveTrackIndexDelta;

package/dist/core/history/history.d.ts

@@ -1,4 +1,4 @@
-import { Action, Clip, ClipStateUpdate, CompoundAction, HistoryState, MoveClipBetweenTracksAction, MoveClipAction, MultiClipUpdateAction, RemoveClipAction, RemoveGapsAction, RestoreClipAudioAction, ResizeClipAction, SeparateClipAudioAction, SetTimeAction, SplitClipAction, Track, TrackRestoreAnchor, TrackHistoryReference, UpdateClipAction, AddClipAction } from '../models/types';
+import { Action, Clip, ClipStateUpdate, CompoundAction, HistoryState, MoveClipBetweenTracksAction, MoveClipAction, MultiClipUpdateAction, RemoveClipAction, RemoveGapsAction, RestoreClipAudioAction, ResizeClipAction, SeparateClipAudioAction, SetPrimaryTrackMagnetAction, SetTimeAction, SplitClipAction, Track, TrackRestoreAnchor, TrackHistoryReference, UpdateClipAction, AddClipAction } from '../models/types';
 export declare class HistoryManager {
     private state;
     private maxHistorySize;
@@ -77,5 +77,6 @@ export declare class HistoryManager {
     createMoveClipBetweenTracksAction(clipId: string, sourceTrackId: string, targetTrackId: string, clipBefore: Clip, clipAfter: Clip, sourceTrackSnapshot: Track | null, targetTrackSnapshot: Track | null, sourceTrackRestoreAnchor?: TrackRestoreAnchor | null, targetTrackRestoreAnchor?: TrackRestoreAnchor | null): MoveClipBetweenTracksAction;
     createSeparateClipAudioAction(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): SeparateClipAudioAction;
     createRestoreClipAudioAction(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): RestoreClipAudioAction;
+    createSetPrimaryTrackMagnetAction(previousEnabled: boolean, nextEnabled: boolean): SetPrimaryTrackMagnetAction;
     createCompoundAction(actions: Action[], label?: string): CompoundAction;
 }

package/dist/core/history/timelineHistoryExecutor.d.ts

@@ -7,6 +7,7 @@ export interface TimelineHistoryExecutionTarget {
     addClipToTrack(trackId: string, clip: Clip): boolean;
     updateClip(clipId: string, updates: Partial<Clip>): void;
     moveClipToTrack(clipId: string, targetTrackId: string): boolean;
+    setPrimaryTrackMagnetEnabled?(enabled: boolean): void;
     ensureTrackFromHistorySnapshot(trackSnapshot: Track, restoreAnchor?: TrackRestoreAnchor | null): string | null;
     removeClipGaps(): void;
     getClips(): Clip[];

package/dist/core/history/timelineHistoryRecorder.d.ts

@@ -16,6 +16,7 @@ export declare class TimelineHistoryRecorder {
     recordRestoreClipAudio(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): Action;
     createSeparateClipAudioAction(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): Action;
     createRestoreClipAudioAction(videoClipBefore: Clip, videoClipAfter: Clip, audioClip: Clip | null, audioTrackId: string | null): Action;
+    recordSetPrimaryTrackMagnet(previousEnabled: boolean, nextEnabled: boolean): Action;
     recordCompoundAction(actions: Action[], label?: string): Action | null;
     createClipUpdateAction(clip: Clip, originalClip?: Clip, clipUpdates?: ClipStateUpdate[]): Action | null;
     withTransaction<T>(label: string | undefined, callback: () => T): T;

package/dist/core/models/types.d.ts

@@ -223,6 +223,7 @@ export interface TimelineConfig {
     speed?: number;
     dragActivationThreshold?: number;
     enableClipSnap?: boolean;
+    enablePrimaryTrackMagnet?: boolean;
     clipSnapThreshold?: number;
     thumbnailProvider?: ThumbnailProvider;
     previewBackend?: PreviewBackendType;
@@ -231,6 +232,8 @@ export interface TimelineConfig {
     textPreviewFont?: TextPreviewFontConfig | null;
     draftData?: TimelineExportData;
     keyboardShortcuts?: false | TimelineKeyboardShortcutsConfig;
+    /** 播放时自动横向滚动以保持播放头在可视安全区内；默认开启 */
+    playbackViewportFollow?: boolean;
 }
 export type PreviewAspectRatioMode = 'auto-first-added-video' | 'auto-first-video' | 'manual';
 export interface PreviewAspectRatio {
@@ -405,6 +408,14 @@ export interface RestoreClipAudioAction {
     };
     timestamp: number;
 }
+export interface SetPrimaryTrackMagnetAction {
+    type: 'set_primary_track_magnet';
+    data: {
+        previousEnabled: boolean;
+        nextEnabled: boolean;
+    };
+    timestamp: number;
+}
 export interface CompoundAction {
     type: 'compound';
     data: {
@@ -413,7 +424,7 @@ export interface CompoundAction {
     };
     timestamp: number;
 }
-export type Action = AddClipAction | RemoveClipAction | UpdateClipAction | SplitClipAction | MoveClipAction | ResizeClipAction | SetTimeAction | RemoveGapsAction | MultiClipUpdateAction | MoveClipBetweenTracksAction | SeparateClipAudioAction | RestoreClipAudioAction | CompoundAction;
+export type Action = AddClipAction | RemoveClipAction | UpdateClipAction | SplitClipAction | MoveClipAction | ResizeClipAction | SetTimeAction | RemoveGapsAction | MultiClipUpdateAction | MoveClipBetweenTracksAction | SeparateClipAudioAction | RestoreClipAudioAction | SetPrimaryTrackMagnetAction | CompoundAction;
 export type ActionType = Action['type'];
 export interface Position {
     x: number;

package/dist/core/tracks/timelineTrackBridge.d.ts

@@ -18,6 +18,7 @@ export interface TimelineTrackBridgeHandlers {
     onTimeJump: (time: TimeMs) => void;
     onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number;
     onClipOverlap?: (clip: Clip, currentTrackId: string, originalClip?: Clip | null) => void;
+    onPrimaryTrackMagnetMove?: (clip: Clip, originalClip: Clip | null, peerClips: Clip[], currentTrackId: string) => boolean | void;
     onClipCrossTrackPreview?: (clip: Clip, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear';
     onClipCrossTrack?: (clip: Clip, originalClip: Clip | null, targetTrackY: number, currentTrackId: string) => boolean | void;
     onClearDropPreview?: () => void;
@@ -41,7 +42,7 @@ export interface TimelineTrackBridgeCreateOptions {
     enableClipSnap?: boolean;
     clipSnapThreshold?: number;
 }
-export type TimelineTrackConstructor<TTrack = Track> = new (layer: Konva.Layer, config: TrackConfig, trackType: TrackType, zoom: number, trackY: number, trackHeight: number, theme: Theme, onClipUpdate: (clip: Clip, originalClip?: Clip, clipUpdates?: ClipStateUpdate[]) => void, onClipAdd: (clip: Clip) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: Clip, clip2: Clip) => void, onClipSelect: (clip: Clip) => void, onTimeJump: (time: TimeMs) => void, onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number, onClipOverlap?: (clip: Clip, currentTrackId: string, originalClip?: Clip | null) => void, onClipCrossTrackPreview?: (clip: Clip, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear', onClipCrossTrack?: (clip: Clip, originalClip: Clip | null, targetTrackY: number, currentTrackId: string) => boolean | void, onClearDropPreview?: () => void, onClearSelection?: () => void, onSnapGuideChange?: (guideTime: TimeMs | null) => void, onClipToggleSelection?: (clipId: string) => void, onSetSingleSelection?: (clipId: string) => void, getMultiDragClipIds?: (clipId: string) => string[] | null, onMultiDragMove?: (request: MultiDragMoveRequest) => boolean | void, onMultiDragInteractionEnd?: () => void, dragActivationThreshold?: number, enableClipSnap?: boolean, clipSnapThreshold?: number) => TTrack;
+export type TimelineTrackConstructor<TTrack = Track> = new (layer: Konva.Layer, config: TrackConfig, trackType: TrackType, zoom: number, trackY: number, trackHeight: number, theme: Theme, onClipUpdate: (clip: Clip, originalClip?: Clip, clipUpdates?: ClipStateUpdate[]) => void, onClipAdd: (clip: Clip) => void, onClipRemove: (clipId: string) => void, onClipSplit: (clip1: Clip, clip2: Clip) => void, onClipSelect: (clip: Clip) => void, onTimeJump: (time: TimeMs) => void, onHorizontalDragAutoScroll?: (nextScrollLeft: number) => number, onClipOverlap?: (clip: Clip, currentTrackId: string, originalClip?: Clip | null) => void, onPrimaryTrackMagnetMove?: (clip: Clip, originalClip: Clip | null, peerClips: Clip[], currentTrackId: string) => boolean | void, onClipCrossTrackPreview?: (clip: Clip, targetTrackY: number, currentTrackId: string) => 'self' | 'external' | 'clear', onClipCrossTrack?: (clip: Clip, originalClip: Clip | null, targetTrackY: number, currentTrackId: string) => boolean | void, onClearDropPreview?: () => void, onClearSelection?: () => void, onSnapGuideChange?: (guideTime: TimeMs | null) => void, onClipToggleSelection?: (clipId: string) => void, onSetSingleSelection?: (clipId: string) => void, getMultiDragClipIds?: (clipId: string) => string[] | null, onMultiDragMove?: (request: MultiDragMoveRequest) => boolean | void, onMultiDragInteractionEnd?: () => void, dragActivationThreshold?: number, enableClipSnap?: boolean, clipSnapThreshold?: number) => TTrack;
 export declare class TimelineTrackBridge<TTrack = Track> {
     private readonly handlers;
     private readonly TrackCtor;