@keplar-404/react-timeline-editor 1.0.6

package/dist/components/cursor/cursor.d.ts

@@ -0,0 +1,20 @@
+import { default as React, FC } from 'react';
+import { ScrollSync } from 'react-virtualized';
+import { CommonProp } from '../../interface/common_prop';
+/** Animation timeline component parameters */
+export type CursorProps = CommonProp & {
+    /** Scroll distance from left */
+    scrollLeft: number;
+    /** Set cursor position */
+    setCursor: (param: {
+        left?: number;
+        time?: number;
+    }) => boolean;
+    /** Timeline area DOM ref */
+    areaRef: React.RefObject<HTMLDivElement>;
+    /** Set scroll left */
+    deltaScrollLeft?: (delta: number) => void;
+    /** Scroll sync ref (TODO: This data is used to temporarily solve the out-of-sync issue when scrollLeft is dragged) */
+    scrollSync: React.RefObject<ScrollSync>;
+};
+export declare const Cursor: FC<CursorProps>;

package/dist/components/cut-overlay/CutOverlay.d.ts

@@ -0,0 +1,202 @@
+import { default as React } from 'react';
+import { TimelineRow } from '@keplar-404/timeline-engine';
+/**
+ * Visual and behavioral configuration for the {@link CutOverlay} component.
+ * All properties are optional — defaults produce a red-themed blade.
+ *
+ * @example
+ * ```tsx
+ * const cutConfig: CutOverlayConfig = {
+ *   bladeColor: '#3b82f6',
+ *   showPill: true,
+ *   formatPillLabel: (t) => `Split at ${t.toFixed(3)}s`,
+ *   showBlockHighlight: true,
+ *   blockHighlightColor: 'rgba(59,130,246,0.12)',
+ * };
+ * <CutOverlay config={cutConfig} ... />
+ * ```
+ */
+export interface CutOverlayConfig {
+    /**
+     * CSS color of the vertical blade line.
+     * @default '#ef4444'
+     */
+    bladeColor?: string;
+    /**
+     * Whether to display the floating time-label pill above the blade.
+     * Set to `false` to completely hide the pill.
+     * @default true
+     */
+    showPill?: boolean;
+    /**
+     * Custom formatter for the time label displayed inside the pill.
+     * Receives the cut time in **seconds** and should return a string.
+     *
+     * @param time - Cut time value in seconds.
+     * @returns The string to render inside the pill.
+     * @default (t) => `✂ ${t.toFixed(2)}s`
+     *
+     * @example
+     * ```tsx
+     * formatPillLabel={(t) => `Cut @ ${(t * 1000).toFixed(0)} ms`}
+     * ```
+     */
+    formatPillLabel?: (time: number) => string;
+    /**
+     * Background color of the pill label.
+     * @default '#ef4444'
+     */
+    pillColor?: string;
+    /**
+     * Text color of the pill label.
+     * @default '#ffffff'
+     */
+    pillTextColor?: string;
+    /**
+     * Whether to show the translucent highlight on the hovered action block.
+     * Set to `false` to remove all background and border from the clip container.
+     * @default true
+     */
+    showBlockHighlight?: boolean;
+    /**
+     * Background fill color for the block highlight.
+     * Accepts any valid CSS color value (e.g. `'rgba(99,102,241,0.15)'` or `'transparent'`).
+     * Only takes effect when `showBlockHighlight` is `true`.
+     * @default 'rgba(239,68,68,0.08)'
+     */
+    blockHighlightColor?: string;
+    /**
+     * Border color for the block highlight container.
+     * Only takes effect when `showBlockHighlight` is `true`.
+     * @default 'rgba(239,68,68,0.3)'
+     */
+    blockHighlightBorderColor?: string;
+    /**
+     * Custom CSS cursor to display when hovering over the active cut overlay.
+     * Standard CSS cursors like 'crosshair', 'copy', or 'default' are supported.
+     * @default 'col-resize'
+     */
+    cursor?: string;
+    /**
+     * A specific keyboard key that must be held down to activate the cut blade.
+     * When defined, standard timeline interactions (dragging, selecting) pass through
+     * normally until this precise key is physically held down.
+     *
+     * Supports standard modifier keys ('Alt', 'Control', 'Shift', 'Meta') or any
+     * exact literal character key (e.g. 'c' or 'x').
+     *
+     * Note: The `string & {}` union hack preserves autocomplete for common keys
+     * while allowing custom exact string matches.
+     */
+    keyboardModifier?: 'Alt' | 'Control' | 'Shift' | 'Meta' | (string & {});
+}
+/**
+ * Props for the {@link CutOverlay} component.
+ *
+ * Mount this absolutely inside the same container as your `<Timeline>` to
+ * overlay a blade-cut interaction on top of the timeline's edit area.
+ */
+export interface CutOverlayProps {
+    /**
+     * The current timeline row data — same array you pass to `<Timeline editorData>`.
+     * Used to hit-test which action block the cursor is over.
+     */
+    data: TimelineRow[];
+    /**
+     * Duration represented by one scale unit (seconds).
+     * Must match the `scale` prop on `<Timeline>`.
+     * @default 1
+     */
+    scale: number;
+    /**
+     * Number of sub-divisions per scale unit used for grid snapping.
+     * Must match the `scaleSplitCount` prop on `<Timeline>`.
+     * @default 10
+     */
+    scaleSplitCount: number;
+    /**
+     * Width in pixels of one scale unit.
+     * Must match the `scaleWidth` prop on `<Timeline>`.
+     * @default 160
+     */
+    scaleWidth: number;
+    /**
+     * Left inset in pixels before the first scale mark begins.
+     * Must match the `startLeft` prop on `<Timeline>`.
+     * @default 20
+     */
+    startLeft: number;
+    /**
+     * Height in pixels of each row in the edit area.
+     * Must match the `rowHeight` prop on `<Timeline>`.
+     * @default 32
+     */
+    rowHeight: number;
+    /**
+     * Height in pixels of the time-ruler strip that sits above the edit rows.
+     * This is subtracted from the mouse Y coordinate to find the correct row index.
+     * The default timeline ruler is **32 px** tall, but adjust if your layout differs.
+     * @default 32
+     */
+    editAreaTopOffset: number;
+    /**
+     * When `true` (and `<Timeline gridSnap>` is also enabled), the cut point
+     * snaps to the nearest grid boundary as the cursor moves.
+     * @default false
+     */
+    gridSnap: boolean;
+    /**
+     * Fine-grained control over the blade, pill, and block-highlight visuals.
+     * All properties are optional and fall back to red-themed defaults.
+     * @see {@link CutOverlayConfig}
+     */
+    config?: CutOverlayConfig;
+    /**
+     * Called when the user clicks while the blade is positioned over an action block.
+     *
+     * @param rowId    - `id` of the row that contains the cut action.
+     * @param actionId - `id` of the action block being cut.
+     * @param cutTime  - The time value (in seconds) at the cut point.
+     */
+    onCut: (rowId: string, actionId: string, cutTime: number) => void;
+    /**
+     * Called whenever the keyboard modifier state changes.
+     * Fires with `true` when the modifier is pressed (blade active)
+     * and `false` when released (blade inactive, pointer events pass through).
+     *
+     * Use this to dynamically control `disableDrag` on the sibling `<Timeline>`:
+     * when the modifier is held → disable drag; when released → re-enable.
+     *
+     * Not called when no `keyboardModifier` is configured — in that case
+     * the blade is always active and drag should always be disabled.
+     *
+     * @param held - Whether the modifier key is currently pressed.
+     */
+    onModifierChange?: (held: boolean) => void;
+}
+/**
+ * `CutOverlay` adds a blade-cut interaction on top of a `<Timeline>` edit area.
+ *
+ * When enabled, hovering over an action block shows a vertical blade line and
+ * an optional floating time pill. Clicking splits the block at the cut point.
+ *
+ * @example
+ * ```tsx
+ * {cutModeActive && (
+ *   <CutOverlay
+ *     data={editorData}
+ *     scale={1}
+ *     scaleSplitCount={10}
+ *     scaleWidth={160}
+ *     startLeft={20}
+ *     rowHeight={40}
+ *     editAreaTopOffset={42}
+ *     gridSnap={snapEnabled}
+ *     config={{ bladeColor: '#3b82f6', formatPillLabel: (t) => `${t.toFixed(2)}s` }}
+ *     onCut={(rowId, actionId, cutTime) => handleCut(rowId, actionId, cutTime)}
+ *   />
+ * )}
+ * ```
+ */
+declare const CutOverlay: React.FC<CutOverlayProps>;
+export default CutOverlay;

package/dist/components/edit_area/cross_row_drag.d.ts

@@ -0,0 +1,50 @@
+import { default as React } from 'react';
+import { TimelineAction, TimelineRow } from '@keplar-404/timeline-engine';
+export interface CrossRowDragState {
+    isDragging: boolean;
+    /** The action currently being dragged across rows */
+    action: TimelineAction | null;
+    /** The source row (where the action came from) */
+    sourceRow: TimelineRow | null;
+    /** Visual width of the ghost (px) */
+    ghostWidth: number;
+    /** Visual height of the ghost (px) */
+    ghostHeight: number;
+    /** Current cursor X (client) */
+    cursorX: number;
+    /** Current cursor Y (client) */
+    cursorY: number;
+    /** Offset from the left edge of the block where the user grabbed it */
+    grabOffsetX: number;
+}
+export interface CrossRowDragAPI {
+    state: CrossRowDragState;
+    startCrossRowDrag: (params: {
+        action: TimelineAction;
+        sourceRow: TimelineRow;
+        ghostWidth: number;
+        ghostHeight: number;
+        grabOffsetX: number;
+        initialX: number;
+        initialY: number;
+    }) => void;
+    endCrossRowDrag: () => void;
+    /** Called by the EditArea when mouse is released to commit the move */
+    onCommit: (action: TimelineAction, sourceRow: TimelineRow, targetRow: TimelineRow, newStart: number, newEnd: number) => void;
+    setOnCommit: (fn: CrossRowDragAPI['onCommit']) => void;
+}
+export declare const useCrossRowDrag: () => CrossRowDragAPI;
+export declare const CrossRowDragProvider: React.FC<{
+    children: React.ReactNode;
+}>;
+interface GhostProps {
+    state: CrossRowDragState;
+    enableGhostPreview: boolean;
+    /** Optional custom render function; receives the dragged action + source row */
+    getGhostPreview?: (params: {
+        action: TimelineAction;
+        row: TimelineRow;
+    }) => React.ReactNode;
+}
+export declare const CrossRowGhost: React.FC<GhostProps>;
+export {};

package/dist/components/edit_area/drag_lines.d.ts

@@ -0,0 +1,11 @@
+import { FC } from 'react';
+export interface DragLineData {
+    isMoving: boolean;
+    movePositions: number[];
+    assistPositions: number[];
+}
+export type DragLineProps = DragLineData & {
+    scrollLeft: number;
+};
+/** Drag auxiliary lines */
+export declare const DragLines: FC<DragLineProps>;

package/dist/components/edit_area/drag_preview.d.ts

@@ -0,0 +1,14 @@
+import { FC } from 'react';
+interface DragPreviewProps {
+    /** Top position of the preview element */
+    top: number;
+    /** Height of the preview element */
+    height: number;
+    /** Whether the preview element is visible */
+    visible: boolean;
+}
+/**
+ * Drag preview component - displays a preview of the row being dragged
+ */
+export declare const DragPreview: FC<DragPreviewProps>;
+export {};

package/dist/components/edit_area/drag_utils.d.ts

@@ -0,0 +1,39 @@
+import { TimelineRow } from '@keplar-404/timeline-engine';
+/**
+ * Calculate the accumulated height of rows
+ * @param editorData Editor data
+ * @param rowIndex Target row index
+ * @param defaultRowHeight Default row height
+ * @returns Accumulated height
+ */
+export declare const calculateRowAccumulatedHeight: (editorData: TimelineRow[], rowIndex: number, defaultRowHeight: number) => number;
+/**
+ * Calculate total height of all rows
+ * @param editorData Editor data
+ * @param defaultRowHeight Default row height
+ * @returns Total height
+ */
+export declare const calculateTotalHeight: (editorData: TimelineRow[], defaultRowHeight: number) => number;
+/**
+ * Get an array of actual heights for each row
+ * @param editorData Editor data
+ * @param defaultRowHeight Default row height
+ * @returns Height array
+ */
+export declare const getRowHeights: (editorData: TimelineRow[], defaultRowHeight: number) => number[];
+/**
+ * Calculate the position of the insertion line
+ * @param editorData Editor data
+ * @param targetIndex Target index
+ * @param defaultRowHeight Default row height
+ * @returns Insertion line top position
+ */
+export declare const calculateInsertionLineTop: (editorData: TimelineRow[], targetIndex: number, defaultRowHeight: number) => number;
+/**
+ * Validate whether the drag target index is valid
+ * @param targetIndex Target index
+ * @param draggedIndex Index of the row being dragged
+ * @param totalRows Total number of rows
+ * @returns Whether it is valid
+ */
+export declare const isValidDragTarget: (targetIndex: number, draggedIndex: number, totalRows: number) => boolean;

package/dist/components/edit_area/edit_action.d.ts

@@ -0,0 +1,19 @@
+import { default as React, FC } from 'react';
+import { TimelineAction, TimelineRow } from '@keplar-404/timeline-engine';
+import { CommonProp } from '../../interface/common_prop';
+import { DragLineData } from './drag_lines';
+export type EditActionProps = CommonProp & {
+    row: TimelineRow;
+    action: TimelineAction;
+    dragLineData: DragLineData;
+    setEditorData: (params: TimelineRow[]) => void;
+    handleTime: (e: React.MouseEvent<HTMLDivElement, MouseEvent>) => number;
+    areaRef: React.RefObject<HTMLDivElement>;
+    /** Scroll delta, used for auto-scroll sync */
+    deltaScrollLeft?: (delta: number) => void;
+    /** Enable dragging a block to a different row */
+    enableCrossRowDrag?: boolean;
+    /** Show ghost element while dragging */
+    enableGhostPreview?: boolean;
+};
+export declare const EditAction: FC<EditActionProps>;

package/dist/components/edit_area/edit_area.d.ts

@@ -0,0 +1,56 @@
+import { default as React } from 'react';
+import { OnScrollParams } from 'react-virtualized';
+import { TimelineAction, TimelineRow } from '@keplar-404/timeline-engine';
+import { CommonProp } from '../../interface/common_prop';
+export type EditAreaProps = CommonProp & {
+    /** Horizontal scroll offset */
+    scrollLeft: number;
+    /** Vertical scroll offset */
+    scrollTop: number;
+    /** Scroll callback for sync */
+    onScroll: (params: OnScrollParams) => void;
+    /** Update the editor data */
+    setEditorData: (params: TimelineRow[]) => void;
+    /** Horizontal auto-scroll delta */
+    deltaScrollLeft: (scrollLeft: number) => void;
+    /** Enable cross-row block drag */
+    enableCrossRowDrag?: boolean;
+    /** Show ghost preview while block dragging across rows */
+    enableGhostPreview?: boolean;
+    /**
+     * Custom render function for the drag ghost element.
+     * Replaces the default blue glowing box with your own component.
+     */
+    getGhostPreview?: (params: {
+        action: TimelineAction;
+        row: TimelineRow;
+    }) => React.ReactNode;
+};
+/** Edit area ref data */
+export interface EditAreaState {
+    domRef: React.MutableRefObject<HTMLDivElement | null>;
+}
+export declare const EditArea: React.ForwardRefExoticComponent<CommonProp & {
+    /** Horizontal scroll offset */
+    scrollLeft: number;
+    /** Vertical scroll offset */
+    scrollTop: number;
+    /** Scroll callback for sync */
+    onScroll: (params: OnScrollParams) => void;
+    /** Update the editor data */
+    setEditorData: (params: TimelineRow[]) => void;
+    /** Horizontal auto-scroll delta */
+    deltaScrollLeft: (scrollLeft: number) => void;
+    /** Enable cross-row block drag */
+    enableCrossRowDrag?: boolean;
+    /** Show ghost preview while block dragging across rows */
+    enableGhostPreview?: boolean;
+    /**
+     * Custom render function for the drag ghost element.
+     * Replaces the default blue glowing box with your own component.
+     */
+    getGhostPreview?: (params: {
+        action: TimelineAction;
+        row: TimelineRow;
+    }) => React.ReactNode;
+} & React.RefAttributes<EditAreaState>>;

package/dist/components/edit_area/edit_row.d.ts

@@ -0,0 +1,27 @@
+import { default as React, FC } from 'react';
+import { TimelineRow } from '@keplar-404/timeline-engine';
+import { CommonProp } from '../../interface/common_prop';
+import { DragLineData } from './drag_lines';
+export type EditRowProps = CommonProp & {
+    areaRef: React.RefObject<HTMLDivElement>;
+    rowData?: TimelineRow;
+    style?: React.CSSProperties;
+    dragLineData: DragLineData;
+    setEditorData: (params: TimelineRow[]) => void;
+    /** Horizontal scroll offset */
+    scrollLeft: number;
+    /** Horizontal scroll delta */
+    deltaScrollLeft: (scrollLeft: number) => void;
+    /** Row index in the editor data array */
+    rowIndex?: number;
+    /** Current row-reorder drag state */
+    dragState?: {
+        isDragging: boolean;
+        draggedIndex: number;
+    };
+    /** Enable cross-row block drag */
+    enableCrossRowDrag?: boolean;
+    /** Show ghost preview while block dragging across rows */
+    enableGhostPreview?: boolean;
+};
+export declare const EditRow: FC<EditRowProps>;

package/dist/components/edit_area/hooks/use_drag_line.d.ts

@@ -0,0 +1,33 @@
+import { TimelineAction, TimelineRow } from '@keplar-404/timeline-engine';
+import { DragLineData } from '../drag_lines';
+export declare function useDragLine(): {
+    initDragLine: (data: {
+        movePositions?: number[];
+        assistPositions?: number[];
+    }) => void;
+    updateDragLine: (data: {
+        movePositions?: number[];
+        assistPositions?: number[];
+    }) => void;
+    disposeDragLine: () => void;
+    dragLineData: DragLineData;
+    defaultGetAssistPosition: (data: {
+        editorData: TimelineRow[];
+        assistActionIds?: string[];
+        action: TimelineAction;
+        row: TimelineRow;
+        startLeft: number;
+        scale: number;
+        scaleWidth: number;
+        hideCursor: boolean;
+        cursorLeft: number;
+    }) => number[];
+    defaultGetMovePosition: (data: {
+        start: number;
+        end: number;
+        dir?: "right" | "left";
+        startLeft: number;
+        scale: number;
+        scaleWidth: number;
+    }) => number[];
+};

package/dist/components/edit_area/insertion_line.d.ts

@@ -0,0 +1,12 @@
+import { FC } from 'react';
+interface InsertionLineProps {
+    /** Distance from top */
+    top: number;
+    /** Whether the insertion line is visible */
+    visible: boolean;
+}
+/**
+ * Insertion line component - displays the drag insertion position
+ */
+export declare const InsertionLine: FC<InsertionLineProps>;
+export {};