@linker-design-plus/timeline-track 1.0.9 → 1.0.11

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

@@ -0,0 +1,392 @@
+export type TrackType = 'video' | 'audio';
+export type PlayState = 'playing' | 'paused';
+export type TimeMs = number;
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogConfig {
+    enabled?: boolean;
+    level?: LogLevel;
+    moduleLevels?: Record<string, LogLevel>;
+}
+export interface ThumbnailProvider {
+    /**
+     * 获取片段的封面图片
+     * @param clip 片段对象
+     * @returns 封面图片URL、Promise<URL>或封面图片URL数组、Promise<URL数组>
+     */
+    getThumbnails(clip: Clip): string[] | Promise<string[]>;
+}
+export interface ClipVisualTransform {
+    x: number;
+    y: number;
+    scale: number;
+}
+export type PreviewBackendType = 'dom' | 'canvas' | 'pixi' | 'auto';
+export interface Mp4PreviewMediaSource {
+    url: string;
+    mimeType: string;
+    kind: 'mp4';
+}
+export interface HlsFmp4PreviewMediaSource {
+    url: string;
+    mimeType: string;
+    kind: 'hls-fmp4';
+}
+export type PreviewMediaSource = Mp4PreviewMediaSource | HlsFmp4PreviewMediaSource;
+export type PreviewSourceResolver = (clip: Clip) => PreviewMediaSource | null | Promise<PreviewMediaSource | null>;
+export interface ClipConfig {
+    id?: string;
+    type?: TrackType;
+    externalId?: string;
+    src: string;
+    name: string;
+    isMuted?: boolean;
+    startTime?: TimeMs;
+    duration: TimeMs;
+    startTimeAtSource?: TimeMs;
+    endTimeAtSource?: TimeMs;
+    sourceDuration?: TimeMs;
+    thumbnails?: string[];
+    style?: Record<string, any>;
+    visualTransform?: ClipVisualTransform;
+    separatedAudioClipId?: string;
+    separatedFromVideoClipId?: string;
+}
+export interface ClipEntity {
+    id: string;
+    type: TrackType;
+    externalId?: string;
+    src: string;
+    name: string;
+    isMuted?: boolean;
+    startTime: TimeMs;
+    duration: TimeMs;
+    endTime: TimeMs;
+    startTimeAtSource: TimeMs;
+    endTimeAtSource: TimeMs;
+    sourceDuration: TimeMs;
+    thumbnails?: string[];
+    style?: Record<string, any>;
+    visualTransform?: ClipVisualTransform;
+    separatedAudioClipId?: string;
+    separatedFromVideoClipId?: string;
+}
+export interface ClipViewState {
+    isDragging: boolean;
+    isResizing: boolean;
+    isResizingLeft: boolean;
+    isResizingRight: boolean;
+    isSelected: boolean;
+    zIndex: number;
+    opacity: number;
+}
+export type Clip = ClipEntity & ClipViewState;
+export declare const DEFAULT_CLIP_VIEW_STATE: ClipViewState;
+export interface TrackConfig {
+    id?: string;
+    type?: TrackType;
+    name?: string;
+    isMuted?: boolean;
+    role?: 'primary' | 'normal';
+    clips: Clip[];
+}
+export type TrackInsertionPlacement = 'before_primary' | 'after_primary' | 'top_of_type_region' | 'bottom_of_type_region' | 'before_track' | 'after_track';
+export interface Track extends TrackConfig {
+    id: string;
+    type: TrackType;
+    name: string;
+    order: number;
+    role: 'primary' | 'normal';
+}
+export interface Theme {
+    background: string;
+    border: string;
+    timeTick: string;
+    timeText: string;
+    trackBackground: string;
+    trackSelectedBackground?: string;
+    trackBorder: string;
+    clipBackground: string;
+    clipBorder: string;
+    clipName: string;
+    clipDuration: string;
+    clipHandle: string;
+    clipCoverBackground: string;
+    audioClipBackground?: string;
+    audioClipText?: string;
+    audioClipAccent?: string;
+    clipSelectedBackground: string;
+    clipSelectedBorder: string;
+    clipSelectedName: string;
+    clipSelectedDuration: string;
+    clipSelectedHandle: string;
+    clipSelectedCoverBackground: string;
+    playhead: string;
+    grid: string;
+    snapGuideLineColor?: string;
+    snapGuideLineWidth?: number;
+    scrollbarBackground?: string;
+    scrollbarBorder?: string;
+    scrollbarThumb?: string;
+    scrollbarThumbBorder?: string;
+}
+export type ThemeConfig = Partial<Theme>;
+export type ResolvedTimelineConfig = Omit<TimelineConfig, 'theme'> & {
+    theme: Theme;
+};
+export declare const defaultDarkTheme: Theme;
+export declare function resolveTheme(theme?: ThemeConfig): Theme;
+export interface TimelineConfig {
+    duration: TimeMs;
+    zoom: number;
+    currentTime: TimeMs;
+    playState: PlayState;
+    container?: HTMLElement;
+    theme?: ThemeConfig;
+    timeScaleHeight?: number;
+    logConfig?: LogConfig;
+    speed?: number;
+    dragActivationThreshold?: number;
+    enableClipSnap?: boolean;
+    clipSnapThreshold?: number;
+    thumbnailProvider?: ThumbnailProvider;
+    previewBackend?: PreviewBackendType;
+    previewSourceResolver?: PreviewSourceResolver;
+}
+export type PreviewAspectRatioMode = 'auto-first-added-video' | 'auto-first-video' | 'manual';
+export interface PreviewAspectRatio {
+    mode: PreviewAspectRatioMode;
+    width: number;
+    height: number;
+}
+export interface PreviewAspectRatioPreset {
+    key: 'default' | '9:16' | '16:9' | '3:4' | '4:3';
+    label: string;
+    aspectRatio: PreviewAspectRatio;
+}
+export declare const DEFAULT_PREVIEW_ASPECT_RATIO: PreviewAspectRatio;
+export declare const PREVIEW_ASPECT_RATIO_PRESETS: PreviewAspectRatioPreset[];
+export declare function normalizePreviewAspectRatioMode(mode?: PreviewAspectRatioMode | null): PreviewAspectRatioMode;
+export declare function isAutoPreviewAspectRatioMode(mode?: PreviewAspectRatioMode | null): boolean;
+export declare function normalizePreviewAspectRatio(aspectRatio?: Partial<PreviewAspectRatio> | null): PreviewAspectRatio;
+export interface PreviewMountConfig {
+    container: HTMLElement;
+    aspectRatio?: {
+        mode?: PreviewAspectRatioMode;
+        width?: number;
+        height?: number;
+    };
+}
+export interface ActiveClipPlaybackInfo {
+    trackId: string;
+    trackType: TrackType;
+    trackOrder: number;
+    clip: Clip;
+    mediaTime: TimeMs;
+    muted: boolean;
+    kind: TrackType;
+    hasVisual: boolean;
+    hasAudio: boolean;
+}
+export interface ClipStateUpdate {
+    clipId: string;
+    newState: Clip;
+    previousState: Clip;
+}
+export interface AddClipAction {
+    type: 'add_clip';
+    data: Clip;
+    timestamp: number;
+}
+export interface RemoveClipAction {
+    type: 'remove_clip';
+    data: Clip;
+    timestamp: number;
+}
+export interface UpdateClipAction {
+    type: 'update_clip';
+    data: {
+        clipId: string;
+        updates: Partial<Clip>;
+        previousState: Partial<Clip>;
+    };
+    timestamp: number;
+}
+export interface SplitClipAction {
+    type: 'split_clip';
+    data: {
+        originalClip: Clip;
+        clip1: Clip;
+        clip2: Clip;
+    };
+    timestamp: number;
+}
+export interface MoveClipAction {
+    type: 'move_clip';
+    data: {
+        clipId: string;
+        newStartTime: number;
+        previousStartTime: number;
+    };
+    timestamp: number;
+}
+export interface ResizeClipAction {
+    type: 'resize_clip';
+    data: {
+        clipId: string;
+        newDuration: number;
+        newStartTime: number;
+        previousDuration: number;
+        previousStartTime: number;
+    };
+    timestamp: number;
+}
+export interface SetTimeAction {
+    type: 'set_time';
+    data: {
+        newTime: number;
+        previousTime: number;
+    };
+    timestamp: number;
+}
+export interface RemoveGapsAction {
+    type: 'remove_gaps';
+    data: {
+        clipsBefore: Clip[];
+    };
+    timestamp: number;
+}
+export interface MultiClipUpdateAction {
+    type: 'multi_clip_update';
+    data: {
+        clipUpdates: ClipStateUpdate[];
+    };
+    timestamp: number;
+}
+export interface MoveClipBetweenTracksAction {
+    type: 'move_clip_between_tracks';
+    data: {
+        clipId: string;
+        sourceTrackId: string;
+        targetTrackId: string;
+        clipBefore: Clip;
+        clipAfter: Clip;
+        sourceTrackSnapshot: Track | null;
+        targetTrackSnapshot: Track | null;
+    };
+    timestamp: number;
+}
+export interface SeparateClipAudioAction {
+    type: 'separate_clip_audio';
+    data: {
+        videoClipBefore: Clip;
+        videoClipAfter: Clip;
+        audioClip: Clip | null;
+        audioTrackId: string | null;
+    };
+    timestamp: number;
+}
+export interface RestoreClipAudioAction {
+    type: 'restore_clip_audio';
+    data: {
+        videoClipBefore: Clip;
+        videoClipAfter: Clip;
+        audioClip: Clip | null;
+        audioTrackId: string | null;
+    };
+    timestamp: number;
+}
+export type Action = AddClipAction | RemoveClipAction | UpdateClipAction | SplitClipAction | MoveClipAction | ResizeClipAction | SetTimeAction | RemoveGapsAction | MultiClipUpdateAction | MoveClipBetweenTracksAction | SeparateClipAudioAction | RestoreClipAudioAction;
+export type ActionType = Action['type'];
+export interface Position {
+    x: number;
+    y: number;
+}
+export interface Range {
+    start: number;
+    end: number;
+}
+export interface HistoryState {
+    past: Action[];
+    future: Action[];
+}
+export type TimelineEvent = 'time_change' | 'play_state_change' | 'clip_added' | 'clip_removed' | 'clip_updated' | 'zoom_change' | 'history_change' | 'track_duration_change' | 'clip_selected' | 'selected_clip_change' | 'speed_change' | 'can_play_change' | 'buffering_state_change' | 'source_loading_change' | 'preview_aspect_ratio_change';
+export interface TimeChangeData {
+    time: TimeMs;
+}
+export interface PlayStateChangeData {
+    playState: PlayState;
+}
+export interface ZoomChangeData {
+    zoom: number;
+}
+export interface ClipEventData {
+    clip: Clip;
+}
+export interface SelectedClipChangeData {
+    clip: Clip | null;
+    hasSelectedClip: boolean;
+}
+export interface ClipRemovedEventData {
+    clipId: string;
+}
+export interface CanPlayChangeData {
+    canPlay: boolean;
+}
+export interface BufferingStateChangeData {
+    isBuffering: boolean;
+}
+export interface SourceLoadingChangeData {
+    isLoading: boolean;
+    pending: number;
+}
+export interface PreviewAspectRatioChangeData {
+    aspectRatio: PreviewAspectRatio;
+}
+export interface EventListener {
+    (event: TimelineEvent, data?: any): void;
+}
+export interface TimelineManagerConfig {
+    initialDuration?: TimeMs;
+    initialZoom?: number;
+    logConfig?: LogConfig;
+    thumbnailProvider?: ThumbnailProvider;
+}
+export interface TimelineExportData {
+    version: string;
+    exportTime: number;
+    coverUrl: string;
+    composition: TimelineCompositionExportData;
+    tracks: TrackExportData[];
+}
+export interface TimelineCompositionExportData {
+    width: number;
+    height: number;
+    aspectRatio: string;
+    mode: PreviewAspectRatioMode;
+}
+export interface TrackExportData {
+    id: string;
+    type: TrackType;
+    name: string;
+    order: number;
+    isMuted: boolean;
+    clips: ClipExportData[];
+}
+export interface ClipExportData {
+    id: string;
+    type: TrackType;
+    externalId?: string;
+    src: string;
+    name: string;
+    isMuted: boolean;
+    startTime: TimeMs;
+    duration: TimeMs;
+    endTime: TimeMs;
+    startTimeAtSource: TimeMs;
+    endTimeAtSource: TimeMs;
+    sourceDuration: TimeMs;
+    thumbnails?: string[];
+    visualTransform?: ClipVisualTransform;
+    separatedAudioClipId?: string;
+    separatedFromVideoClipId?: string;
+}

package/dist/core/presentation/index.d.ts

@@ -0,0 +1 @@
+export { TimelinePresentationAdapter } from './timelinePresentationAdapter';

package/dist/core/presentation/timelinePresentationAdapter.d.ts

@@ -0,0 +1,22 @@
+import type { Clip, TimeMs } from '../models/types';
+import type { TimelineTrackCollection } from '../tracks/timelineTrackCollection';
+export interface TimelineTimeView {
+    setCurrentTime(time: TimeMs): void;
+}
+export interface TimelineZoomView {
+    setZoom(zoom: number): void;
+}
+export interface TimelineScrollView {
+    setScrollLeft(scrollLeft: number): void;
+}
+export interface TimelineVerticalScrollView {
+    setScrollTop(scrollTop: number): void;
+}
+export declare class TimelinePresentationAdapter {
+    syncCurrentTime(timeline: TimelineTimeView | null, playhead: TimelineTimeView | null, tracks: TimelineTrackCollection, time: TimeMs): void;
+    syncZoom(timeline: TimelineZoomView | null, playhead: TimelineZoomView | null, tracks: TimelineTrackCollection, zoom: number): void;
+    syncScrollLeft(playhead: TimelineScrollView | null, tracks: TimelineTrackCollection, scrollLeft: number): void;
+    syncScrollTop(panel: TimelineVerticalScrollView | null, scrollbar: TimelineVerticalScrollView | null, scrollTop: number): void;
+    syncSelection(tracks: TimelineTrackCollection, selectedClipId: string | null): void;
+    findSelectedClip(tracks: TimelineTrackCollection): Clip | null;
+}

package/dist/core/stores/index.d.ts

@@ -0,0 +1,4 @@
+export { PlaybackStore } from './playbackStore';
+export { SelectionStore } from './selectionStore';
+export { TimelineStore } from './timelineStore';
+export { ViewportStore } from './viewportStore';

package/dist/core/stores/playbackStore.d.ts

@@ -0,0 +1,17 @@
+import type { PlayState, TimeMs } from '../models/types';
+export declare class PlaybackStore {
+    private currentTime;
+    private playState;
+    private speed;
+    constructor(initial: {
+        currentTime: TimeMs;
+        playState: PlayState;
+        speed: number;
+    });
+    getCurrentTime(): TimeMs;
+    setCurrentTime(time: TimeMs): void;
+    getPlayState(): PlayState;
+    setPlayState(playState: PlayState): void;
+    getSpeed(): number;
+    setSpeed(speed: number): void;
+}

package/dist/core/stores/selectionStore.d.ts

@@ -0,0 +1,7 @@
+export declare class SelectionStore {
+    private selectedClipId;
+    getSelectedClipId(): string | null;
+    setSelectedClipId(clipId: string | null): void;
+    clear(): void;
+    hasSelection(): boolean;
+}

package/dist/core/stores/timelineStore.d.ts

@@ -0,0 +1,44 @@
+import type { PlayState, TimeMs } from '../models/types';
+export interface TimelineStoreInitialState {
+    currentTime: TimeMs;
+    playState: PlayState;
+    speed: number;
+    zoom: number;
+    duration: TimeMs;
+    scrollLeft?: number;
+    scrollTop?: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    contentHeight?: number;
+    selectedClipId?: string | null;
+}
+export declare class TimelineStore {
+    private readonly selectionStore;
+    private readonly playbackStore;
+    private readonly viewportStore;
+    constructor(initial: TimelineStoreInitialState);
+    getSelectedClipId(): string | null;
+    setSelectedClipId(clipId: string | null): void;
+    clearSelection(): void;
+    hasSelection(): boolean;
+    getCurrentTime(): TimeMs;
+    setCurrentTime(time: TimeMs): void;
+    getPlayState(): PlayState;
+    setPlayState(playState: PlayState): void;
+    getSpeed(): number;
+    setSpeed(speed: number): void;
+    getZoom(): number;
+    setZoom(zoom: number): void;
+    getDuration(): TimeMs;
+    setDuration(duration: TimeMs): void;
+    getScrollLeft(): number;
+    setScrollLeft(scrollLeft: number): void;
+    getScrollTop(): number;
+    setScrollTop(scrollTop: number): void;
+    getViewportWidth(): number;
+    setViewportWidth(viewportWidth: number): void;
+    getViewportHeight(): number;
+    setViewportHeight(viewportHeight: number): void;
+    getContentHeight(): number;
+    setContentHeight(contentHeight: number): void;
+}

package/dist/core/stores/viewportStore.d.ts

@@ -0,0 +1,33 @@
+import type { TimeMs } from '../models/types';
+export declare class ViewportStore {
+    private zoom;
+    private duration;
+    private scrollLeft;
+    private scrollTop;
+    private viewportWidth;
+    private viewportHeight;
+    private contentHeight;
+    constructor(initial: {
+        zoom: number;
+        duration: TimeMs;
+        scrollLeft?: number;
+        scrollTop?: number;
+        viewportWidth?: number;
+        viewportHeight?: number;
+        contentHeight?: number;
+    });
+    getZoom(): number;
+    setZoom(zoom: number): void;
+    getDuration(): TimeMs;
+    setDuration(duration: TimeMs): void;
+    getScrollLeft(): number;
+    setScrollLeft(scrollLeft: number): void;
+    getScrollTop(): number;
+    setScrollTop(scrollTop: number): void;
+    getViewportWidth(): number;
+    setViewportWidth(viewportWidth: number): void;
+    getViewportHeight(): number;
+    setViewportHeight(viewportHeight: number): void;
+    getContentHeight(): number;
+    setContentHeight(contentHeight: number): void;
+}

package/dist/core/testing/konva-test-stub.d.ts

@@ -0,0 +1,81 @@
+type AttrMap = Record<string, any>;
+declare class MockNode {
+    protected attrs: AttrMap;
+    protected children: MockNode[];
+    protected listeners: Map<string, ((event: any) => void)[]>;
+    constructor(attrs?: AttrMap);
+    name(value?: string): any;
+    x(value?: number): any;
+    y(value?: number): any;
+    width(value?: number): any;
+    height(value?: number): any;
+    visible(value?: boolean): any;
+    fill(value?: string): any;
+    stroke(value?: string): any;
+    strokeWidth(value?: number): any;
+    fillEnabled(value?: boolean): any;
+    dash(value?: number[]): any;
+    cornerRadius(value?: number): any;
+    text(value?: string): any;
+    ellipsis(value?: boolean): any;
+    points(value?: number[]): any;
+    setAttr(key: string, value: any): void;
+    getAttr(key: string): any;
+    add(child: MockNode): this;
+    on(eventName: string, handler: (event: any) => void): this;
+    off(eventName: string, handler?: (event: any) => void): this;
+    fire(eventName: string, event: any): this;
+    getChildren(): MockNode[];
+    destroyChildren(): void;
+    clip(value?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): any;
+    clipWidth(): number;
+    clipHeight(): number;
+    container(): any;
+    batchDraw(): this;
+    draw(): this;
+    destroy(): void;
+    findOne(selector: string): MockNode | undefined;
+    find(selector: string): MockNode[];
+    getClassName(): string;
+}
+declare class MockGroup extends MockNode {
+}
+declare class MockLayer extends MockGroup {
+}
+declare class MockRect extends MockNode {
+}
+declare class MockText extends MockNode {
+}
+declare class MockLine extends MockNode {
+}
+declare class MockImage extends MockNode {
+}
+declare class MockRegularPolygon extends MockNode {
+}
+declare class MockStage extends MockNode {
+}
+declare class MockTween {
+    private readonly config;
+    constructor(config: Record<string, any>);
+    play(): void;
+}
+export declare function createKonvaMock(): {
+    Group: typeof MockGroup;
+    Layer: typeof MockLayer;
+    Rect: typeof MockRect;
+    Text: typeof MockText;
+    Line: typeof MockLine;
+    Image: typeof MockImage;
+    RegularPolygon: typeof MockRegularPolygon;
+    Stage: typeof MockStage;
+    Tween: typeof MockTween;
+    Easings: {
+        EaseInOut: string;
+    };
+};
+export {};

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

@@ -0,0 +1,3 @@
+export { TimelineTrackBridge } from './timelineTrackBridge';
+export { TimelineTrackCollection } from './timelineTrackCollection';
+export { TrackManager } from './trackManager';

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

@@ -0,0 +1,37 @@
+import Konva from 'konva';
+import { Track } from '../../components/track/Track';
+import type { Clip, ClipStateUpdate, Theme, TimeMs, TrackConfig, TrackType } from '../models/types';
+export interface TimelineTrackBridgeHandlers {
+    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) => 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;
+}
+export interface TimelineTrackBridgeCreateOptions {
+    layer: Konva.Layer;
+    config: TrackConfig;
+    trackType: TrackType;
+    zoom: number;
+    trackY: number;
+    trackHeight: number;
+    theme: Theme;
+    dragActivationThreshold?: number;
+    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) => 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, dragActivationThreshold?: number, enableClipSnap?: boolean, clipSnapThreshold?: number) => TTrack;
+export declare class TimelineTrackBridge<TTrack = Track> {
+    private readonly handlers;
+    private readonly TrackCtor;
+    constructor(handlers: TimelineTrackBridgeHandlers, TrackCtor?: TimelineTrackConstructor<TTrack>);
+    createTrack(options: TimelineTrackBridgeCreateOptions): TTrack;
+}