Skip to content

Create professional demos and 3D mockups in seconds, directly in your browser

2.9 KB
Raw Blame
/**
 * Snapping helpers for the timeline.
 *
 * Collects all "snap points" (clip edges, fragment edges, playhead, zero) and
 * finds the nearest one within a pixel threshold. Used by drag handlers for
 * clips, fragments, and the playhead to implement magnetic snapping.
 */

export interface SnapPoint {
    time: number;
    label?: string;
}

export interface SnapResult {
    /** The snapped time, or null if no snap point was within range. */
    time: number;
    /** The pixel offset that was applied (for rendering snap indicators). */
    offsetPx: number;
}

/**
 * Collects snap points from all timeline entities.
 * De-duplicates and sorts them.
 */
export function collectSnapPoints(opts: {
    clipEdges?: Array<{ start: number; end: number }>;
    fragmentEdges?: Array<{ start: number; end: number }>;
    audioEdges?: Array<{ start: number; end: number }>;
    elementEdges?: Array<{ start: number; end: number }>;
    motionEdges?: Array<{ start: number; end: number }>;
    markers?: number[];
    playhead?: number;
    zero?: boolean;
}): SnapPoint[] {
    const points: SnapPoint[] = [];
    const add = (t: number) => points.push({ time: Math.max(0, t) });

    if (opts.zero !== false) add(0);

    for (const e of opts.clipEdges ?? []) {
        add(e.start);
        add(e.end);
    }
    for (const e of opts.fragmentEdges ?? []) {
        add(e.start);
        add(e.end);
    }
    for (const e of opts.audioEdges ?? []) {
        add(e.start);
        add(e.end);
    }
    for (const e of opts.elementEdges ?? []) {
        add(e.start);
        if (e.end !== undefined) add(e.end);
    }
    for (const e of opts.motionEdges ?? []) {
        add(e.start);
        add(e.end);
    }
    for (const marker of opts.markers ?? []) add(marker);
    if (opts.playhead !== undefined) add(opts.playhead);

    // De-duplicate within 1ms
    const sorted = points.sort((a, b) => a.time - b.time);
    const deduped: SnapPoint[] = [];
    for (const p of sorted) {
        if (deduped.length === 0 || Math.abs(p.time - deduped[deduped.length - 1].time) > 0.001) {
            deduped.push(p);
        }
    }
    return deduped;
}

/**
 * Finds the nearest snap point to `time` within `thresholdPx` pixels.
 * Returns the snapped time (unchanged if no snap), and the pixel offset.
 */
export function findSnap(
    time: number,
    snapPoints: SnapPoint[],
    timeToPx: (t: number) => number,
    thresholdPx: number,
): SnapResult {
    let bestTime = time;
    let bestDist = thresholdPx;
    let found = false;

    for (const p of snapPoints) {
        const distPx = Math.abs(timeToPx(p.time) - timeToPx(time));
        if (distPx <= bestDist) {
            bestDist = distPx;
            bestTime = p.time;
            found = true;
        }
    }

    if (!found) {
        return { time, offsetPx: 0 };
    }

    const offsetPx = timeToPx(bestTime) - timeToPx(time);
    return { time: bestTime, offsetPx };
}