@keplar-404/react-timeline-editor 1.0.6

package/dist/components/loop-zone/LoopZoneOverlay.d.ts

@@ -0,0 +1,243 @@
+import { default as React } from 'react';
+/**
+ * Visual and behavioral configuration for the {@link LoopZoneOverlay} component.
+ * All properties are optional — defaults produce a green-themed loop zone.
+ *
+ * @example
+ * ```tsx
+ * const loopConfig: LoopZoneConfig = {
+ *   bandColor: '#a855f7',
+ *   bandOpacity: 0.1,
+ *   handleColor: '#c084fc',
+ *   showBoundaryLines: true,
+ * };
+ * <LoopZoneOverlay config={loopConfig} ... />
+ * ```
+ */
+export interface LoopZoneConfig {
+    /**
+     * CSS color of the loop region shaded band.
+     * @default '#10b981'
+     */
+    bandColor?: string;
+    /**
+     * Opacity of the loop region band (0–1).
+     * Keep this low (< 0.15) so underlying blocks remain visible.
+     * @default 0.07
+     */
+    bandOpacity?: number;
+    /**
+     * Border/stripe color used on the band's edges and stripe pattern.
+     * Falls back to `bandColor` when not set.
+     */
+    bandBorderColor?: string;
+    /**
+     * CSS color of the default drag handle grip pills.
+     * Falls back to `bandColor` when not set.
+     * Has no effect when `renderHandle` is provided.
+     */
+    handleColor?: string;
+    /**
+     * Whether to render the dashed vertical boundary lines
+     * extending through the edit rows below the time ruler.
+     * @default true
+     */
+    showBoundaryLines?: boolean;
+    /**
+     * CSS color of the dashed boundary lines.
+     * @default 'rgba(16, 185, 129, 0.4)'
+     */
+    boundaryLineColor?: string;
+}
+/**
+ * Props passed into a custom handle renderer supplied via `LoopZoneOverlayProps.renderHandle`.
+ *
+ * Attach `onMouseDown` to your draggable element to enable the drag interaction.
+ * The overlay provides all pixel math — your renderer only needs to call `onMouseDown`.
+ *
+ * @example
+ * ```tsx
+ * renderHandle={({ type, time, onMouseDown }) => (
+ *   <div
+ *     onMouseDown={onMouseDown}
+ *     style={{ cursor: 'ew-resize', background: 'purple' }}
+ *     title={`${type === 'start' ? 'Loop start' : 'Loop end'}: ${time.toFixed(2)}s`}
+ *   >
+ *     {type === 'start' ? '⟨' : '⟩'}
+ *   </div>
+ * )}
+ * ```
+ */
+export interface LoopHandleRenderProps {
+    /**
+     * Which boundary this handle controls.
+     * Use to differentiate styling between the two handles.
+     */
+    type: 'start' | 'end';
+    /**
+     * The current time value (in seconds) for this boundary.
+     * Useful for displaying a tooltip or label.
+     */
+    time: number;
+    /**
+     * Attach this to your draggable element's `onMouseDown` to activate dragging.
+     * The LoopZoneOverlay hooks into document `mousemove`/`mouseup` internally —
+     * you do not need to manage drag events yourself.
+     */
+    onMouseDown: (e: React.MouseEvent) => void;
+}
+/**
+ * Props for the {@link LoopZoneOverlay} component.
+ *
+ * Mount this absolutely inside the same container as your `<Timeline>` to render
+ * a draggable loop region on top of the timeline ruler and edit area.
+ *
+ * @example
+ * ```tsx
+ * const [loopStart, setLoopStart] = useState(1);
+ * const [loopEnd, setLoopEnd]     = useState(3);
+ * const [scrollLeft, setScrollLeft] = useState(0);
+ *
+ * // Inside your container:
+ * <div style={{ position: 'relative' }}>
+ *   <Timeline
+ *     ref={timelineRef}
+ *     scale={1}
+ *     scaleWidth={160}
+ *     startLeft={20}
+ *     onScroll={(p) => setScrollLeft(p.scrollLeft)}
+ *     ...
+ *   />
+ *   {loopEnabled && (
+ *     <LoopZoneOverlay
+ *       scale={1}
+ *       scaleWidth={160}
+ *       startLeft={20}
+ *       scrollLeft={scrollLeft}
+ *       loopStart={loopStart}
+ *       loopEnd={loopEnd}
+ *       onLoopStartChange={setLoopStart}
+ *       onLoopEndChange={setLoopEnd}
+ *     />
+ *   )}
+ * </div>
+ * ```
+ */
+export interface LoopZoneOverlayProps {
+    /**
+     * Duration represented by one scale unit (seconds).
+     * Must match the `scale` prop on `<Timeline>`.
+     * @default 1
+     */
+    scale: 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;
+    /**
+     * Current horizontal scroll offset of the timeline.
+     * Track this via the `onScroll` callback on `<Timeline>`:
+     * ```tsx
+     * onScroll={(params) => setScrollLeft(params.scrollLeft)}
+     * ```
+     */
+    scrollLeft: number;
+    /**
+     * Loop region start time in seconds.
+     * This is a **controlled** prop — manage it in parent state.
+     */
+    loopStart: number;
+    /**
+     * Loop region end time in seconds.
+     * Must be greater than `loopStart`.
+     * This is a **controlled** prop — manage it in parent state.
+     */
+    loopEnd: number;
+    /**
+     * Called when the user drags the start handle to a new time value.
+     * Update your `loopStart` state here.
+     *
+     * @param time - New loop start time in seconds.
+     */
+    onLoopStartChange: (time: number) => void;
+    /**
+     * Called when the user drags the end handle to a new time value.
+     * Update your `loopEnd` state here.
+     *
+     * @param time - New loop end time in seconds.
+     */
+    onLoopEndChange: (time: number) => void;
+    /**
+     * Fine-grained control over the band color, opacity, handle color, and
+     * boundary line appearance. All properties are optional and fall back
+     * to green-themed defaults.
+     *
+     * @see {@link LoopZoneConfig}
+     */
+    config?: LoopZoneConfig;
+    /**
+     * Custom render function for the drag handles.
+     *
+     * When provided, the default SVG grip pill is replaced by whatever
+     * your function returns. The function is called once for each handle
+     * (`'start'` and `'end'`).
+     *
+     * You **must** attach the provided `onMouseDown` to your draggable
+     * element to preserve the drag interaction.
+     *
+     * @see {@link LoopHandleRenderProps}
+     *
+     * @example
+     * ```tsx
+     * renderHandle={({ type, time, onMouseDown }) => (
+     *   <MyHandle side={type} label={`${time.toFixed(2)}s`} onMouseDown={onMouseDown} />
+     * )}
+     * ```
+     */
+    renderHandle?: (props: LoopHandleRenderProps) => React.ReactNode;
+    /**
+     * Additional CSS class name appended to the overlay root element.
+     * Use to apply custom styles alongside or instead of `config`.
+     */
+    className?: string;
+    /**
+     * Inline styles applied to the overlay root element.
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * `LoopZoneOverlay` renders a draggable loop/repeat region on top of a `<Timeline>`.
+ *
+ * When mounted inside the same positioned container as `<Timeline>`, it draws:
+ * - A **semi-transparent band** spanning the ruler and edit rows between `loopStart` and `loopEnd`
+ * - Two **draggable handles** at the boundaries (or custom handles via `renderHandle`)
+ * - Optional **dashed boundary lines** extending through the edit rows
+ *
+ * The component is **fully controlled** — it calls `onLoopStartChange` /
+ * `onLoopEndChange` as the user drags and does not hold its own loop state.
+ *
+ * @example
+ * ```tsx
+ * <LoopZoneOverlay
+ *   scale={1}
+ *   scaleWidth={160}
+ *   startLeft={20}
+ *   scrollLeft={scrollLeft}
+ *   loopStart={loopStart}
+ *   loopEnd={loopEnd}
+ *   onLoopStartChange={setLoopStart}
+ *   onLoopEndChange={setLoopEnd}
+ *   config={{ bandColor: '#6366f1', bandOpacity: 0.1 }}
+ * />
+ * ```
+ */
+declare const LoopZoneOverlay: React.FC<LoopZoneOverlayProps>;
+export default LoopZoneOverlay;

package/dist/components/row_rnd/hooks/useAutoScroll.d.ts

@@ -0,0 +1,7 @@
+import { DragEvent, ResizeEvent } from '@interactjs/types/index';
+export declare function useAutoScroll(target: React.RefObject<HTMLDivElement>): {
+    initAutoScroll: () => void;
+    dealDragAutoScroll: (e: DragEvent, deltaScroll?: (delta: number) => void) => boolean;
+    dealResizeAutoScroll: (e: ResizeEvent, dir: "left" | "right", deltaScroll?: (delta: number) => void) => boolean;
+    stopAutoScroll: () => void;
+};

package/dist/components/row_rnd/interactable.d.ts

@@ -0,0 +1,14 @@
+import { DraggableOptions } from '@interactjs/actions/drag/plugin';
+import { ResizableOptions } from '@interactjs/actions/resize/plugin';
+import { Interactable } from '@interactjs/types';
+import { FC, ReactElement } from 'react';
+interface InteractCompProps {
+    children: ReactElement;
+    interactRef: React.MutableRefObject<Interactable | null>;
+    draggable: boolean;
+    draggableOptions: DraggableOptions;
+    resizable: boolean;
+    resizableOptions: ResizableOptions;
+}
+export declare const InteractComp: FC<InteractCompProps>;
+export {};

package/dist/components/row_rnd/row_rnd.d.ts

@@ -0,0 +1,3 @@
+import { default as React } from 'react';
+import { RowRndApi, RowRndProps } from './row_rnd_interface';
+export declare const RowDnd: React.ForwardRefExoticComponent<RowRndProps & React.RefAttributes<RowRndApi>>;

package/dist/components/row_rnd/row_rnd_interface.d.ts

@@ -0,0 +1,47 @@
+type EventData = {
+    lastLeft: number;
+    left: number;
+    lastWidth: number;
+    width: number;
+};
+export type RndDragStartCallback = () => void;
+export type RndDragCallback = (data: EventData, scrollDelta?: number) => boolean | void;
+export type RndDragEndCallback = (data: Pick<EventData, 'left' | 'width'>) => void;
+export type Direction = "left" | "right";
+export type RndResizeStartCallback = (dir: Direction) => void;
+export type RndResizeCallback = (dir: Direction, data: EventData) => boolean | void;
+export type RndResizeEndCallback = (dir: Direction, data: Pick<EventData, 'left' | 'width'>) => void;
+export interface RowRndApi {
+    updateWidth: (size: number) => void;
+    updateLeft: (left: number) => void;
+    getLeft: () => number;
+    getWidth: () => number;
+}
+export interface RowRndProps {
+    width?: number;
+    left?: number;
+    grid?: number;
+    start?: number;
+    bounds?: {
+        left: number;
+        right: number;
+    };
+    edges?: {
+        left: boolean | string;
+        right: boolean | string;
+    };
+    onResizeStart?: RndResizeStartCallback;
+    onResize?: RndResizeCallback;
+    onResizeEnd?: RndResizeEndCallback;
+    onDragStart?: RndDragStartCallback;
+    onDrag?: RndDragCallback;
+    onDragEnd?: RndDragEndCallback;
+    parentRef: React.RefObject<HTMLDivElement>;
+    deltaScrollLeft?: (delta: number) => void;
+    children?: React.ReactNode;
+    enableResizing?: boolean;
+    enableDragging?: boolean;
+    adsorptionPositions?: number[];
+    adsorptionDistance?: number;
+}
+export {};

package/dist/components/time_area/time_area.d.ts

@@ -0,0 +1,17 @@
+import { FC } from 'react';
+import { OnScrollParams } from 'react-virtualized';
+import { CommonProp } from '../../interface/common_prop';
+/** Animation timeline component parameters */
+export type TimeAreaProps = CommonProp & {
+    /** Scroll distance from left */
+    scrollLeft: number;
+    /** Scroll callback, used for synchronous scrolling */
+    onScroll: (params: OnScrollParams) => void;
+    /** Set cursor position */
+    setCursor: (param: {
+        left?: number;
+        time?: number;
+    }) => void;
+};
+/** Animation timeline component */
+export declare const TimeArea: FC<TimeAreaProps>;

package/dist/components/timeline.d.ts

@@ -0,0 +1,3 @@
+import { default as React } from 'react';
+import { TimelineEditor, TimelineState } from '../interface/timeline';
+export declare const Timeline: React.ForwardRefExoticComponent<TimelineEditor & React.RefAttributes<TimelineState>>;

package/dist/components/transport/TransportBar.d.ts

@@ -0,0 +1,132 @@
+import { default as React } from 'react';
+import { TimelinePlayerState } from './useTimelinePlayer';
+/**
+ * Loop control props for the {@link TransportBar} component.
+ * Supply this to enable the loop toggle button and start/end inputs.
+ */
+export interface TransportBarLoopProps {
+    /**
+     * Whether the loop is currently active.
+     * Controls the visual state of the loop button (lit vs. dim).
+     */
+    enabled: boolean;
+    /**
+     * Loop region start time in seconds.
+     */
+    start: number;
+    /**
+     * Loop region end time in seconds.
+     */
+    end: number;
+    /**
+     * Called when the user clicks the loop toggle button.
+     */
+    onToggle: () => void;
+    /**
+     * Called when the user edits the loop start input.
+     * @param time - New start time in seconds.
+     */
+    onStartChange: (time: number) => void;
+    /**
+     * Called when the user edits the loop end input.
+     * @param time - New end time in seconds.
+     */
+    onEndChange: (time: number) => void;
+}
+/**
+ * Props for the {@link TransportBar} component.
+ *
+ * @example
+ * ```tsx
+ * const player = useTimelinePlayer(timelineRef, { loop: { enabled, start, end } });
+ *
+ * <TransportBar
+ *   player={player}
+ *   loop={{ enabled, start, end, onToggle, onStartChange, onEndChange }}
+ * />
+ * ```
+ */
+export interface TransportBarProps {
+    /**
+     * The return value of `useTimelinePlayer()`.
+     * Provides all reactive state and control functions.
+     *
+     * @see {@link TimelinePlayerState}
+     */
+    player: TimelinePlayerState;
+    /**
+     * Optional loop controls.
+     * When provided, a loop toggle button (🔁) appears after the stop button,
+     * and start/end time inputs appear when the loop is active.
+     *
+     * @see {@link TransportBarLoopProps}
+     */
+    loop?: TransportBarLoopProps;
+    /**
+     * Playback rate options displayed as speed buttons.
+     * @default [0.25, 0.5, 1, 2, 4]
+     */
+    playRates?: number[];
+    /**
+     * Custom time format function.
+     * Receives the current time in seconds, should return a display string.
+     *
+     * @default Built-in `formatTime` (produces `'M:SS.mm'` format)
+     *
+     * @example
+     * ```tsx
+     * formatDisplayTime={(t) => `${(t * 1000).toFixed(0)} ms`}
+     * ```
+     */
+    formatDisplayTime?: (seconds: number) => string;
+    /**
+     * Additional CSS class name for the transport bar root element.
+     */
+    className?: string;
+    /**
+     * Inline styles for the transport bar root element.
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * `TransportBar` is a pre-built playback control bar for use with `<Timeline>`.
+ *
+ * It renders transport controls (to-start, rewind, play/pause, forward, stop),
+ * a time display, playback rate buttons, and optionally a loop toggle with
+ * start/end inputs.
+ *
+ * Pair it with {@link useTimelinePlayer} to wire it to a `<Timeline>` ref:
+ *
+ * @example
+ * ```tsx
+ * const timelineRef = useRef<TimelineState>(null);
+ * const [loopOn, setLoopOn] = useState(false);
+ * const [loopStart, setLoopStart] = useState(1);
+ * const [loopEnd, setLoopEnd] = useState(3);
+ *
+ * const player = useTimelinePlayer(timelineRef, {
+ *   loop: { enabled: loopOn, start: loopStart, end: loopEnd },
+ * });
+ *
+ * return (
+ *   <>
+ *     <TransportBar
+ *       player={player}
+ *       loop={{
+ *         enabled: loopOn, start: loopStart, end: loopEnd,
+ *         onToggle: () => setLoopOn((v) => !v),
+ *         onStartChange: setLoopStart,
+ *         onEndChange: setLoopEnd,
+ *       }}
+ *     />
+ *     <Timeline ref={timelineRef} ... />
+ *   </>
+ * );
+ * ```
+ *
+ * **Building your own UI?**
+ * Skip this component entirely and use just `useTimelinePlayer()` to get the state
+ * and handlers, then wire them to your own custom controls.
+ */
+declare const TransportBar: React.FC<TransportBarProps>;
+export default TransportBar;

package/dist/components/transport/useTimelinePlayer.d.ts

@@ -0,0 +1,164 @@
+import { TimelineState } from '../../interface/timeline';
+/**
+ * Formats a time value in seconds to a `M:SS.mm` display string.
+ *
+ * @param seconds - Time in seconds (e.g. `75.4` → `'1:15.40'`).
+ * @returns Formatted time string.
+ *
+ * @example
+ * ```ts
+ * formatTime(0);      // '0:00.00'
+ * formatTime(75.4);   // '1:15.40'
+ * formatTime(3661.1); // '61:01.10'
+ * ```
+ */
+export declare function formatTime(seconds: number): string;
+/**
+ * Loop configuration passed to {@link useTimelinePlayer}.
+ *
+ * When `enabled` is `true`, the hook automatically resets playback to `start`
+ * whenever the current time reaches `end`. The check uses React refs internally,
+ * so it never suffers from stale-closure issues even as values change.
+ */
+export interface UseTimelinePlayerLoop {
+    /**
+     * Whether the loop is active. Safe to toggle while the timeline is playing.
+     */
+    enabled: boolean;
+    /**
+     * Loop region start time in seconds.
+     * Must be less than `end`.
+     */
+    start: number;
+    /**
+     * Loop region end time in seconds.
+     * Must be greater than `start`.
+     */
+    end: number;
+}
+/**
+ * Options for the {@link useTimelinePlayer} hook.
+ */
+export interface UseTimelinePlayerOptions {
+    /**
+     * Number of seconds to jump when calling `rewind()` or `forward()`.
+     * @default 5
+     */
+    seekStep?: number;
+    /**
+     * Optional loop configuration.
+     * When provided, the hook handles the loop clock internally — no extra code needed.
+     *
+     * @see {@link UseTimelinePlayerLoop}
+     *
+     * @example
+     * ```tsx
+     * const player = useTimelinePlayer(ref, {
+     *   loop: { enabled: loopOn, start: 1, end: 3 },
+     * });
+     * ```
+     */
+    loop?: UseTimelinePlayerLoop;
+}
+/**
+ * State and controls returned by {@link useTimelinePlayer}.
+ *
+ * Destructure what you need — use it with the built-in `<TransportBar>` component
+ * or wire it to your own custom controls.
+ *
+ * @example
+ * ```tsx
+ * const { isPlaying, currentTime, play, pause, stop } = useTimelinePlayer(ref);
+ *
+ * <button onClick={isPlaying ? pause : play}>
+ *   {isPlaying ? '⏸' : '▶'}
+ * </button>
+ * <span>{formatTime(currentTime)}</span>
+ * ```
+ */
+export interface TimelinePlayerState {
+    /**
+     * Whether the timeline is currently playing.
+     * Updated automatically from engine events — no polling required.
+     */
+    isPlaying: boolean;
+    /**
+     * Current playback position in seconds.
+     * Updated on every engine tick — suitable for display.
+     */
+    currentTime: number;
+    /**
+     * Current playback rate multiplier (e.g. `1` = 1×, `2` = 2×).
+     * Updated when `setPlayRate` is called.
+     */
+    playRate: number;
+    /**
+     * Start playback from the current position.
+     * Plays to the end of the timeline and then stops.
+     */
+    play: () => void;
+    /**
+     * Pause playback at the current position.
+     */
+    pause: () => void;
+    /**
+     * Stop playback and reset the cursor to time `0`.
+     */
+    stop: () => void;
+    /**
+     * Pause and jump the cursor back to time `0`.
+     * Differs from `stop` only in semantics — both do the same thing currently.
+     */
+    toStart: () => void;
+    /**
+     * Jump backwards by `seekStep` seconds (clamped to 0).
+     */
+    rewind: () => void;
+    /**
+     * Jump forwards by `seekStep` seconds.
+     */
+    forward: () => void;
+    /**
+     * Jump to a specific time value (seconds).
+     *
+     * @param time - Target time in seconds.
+     */
+    setTime: (time: number) => void;
+    /**
+     * Change the playback rate multiplier.
+     *
+     * @param rate - Multiplier value (e.g. `0.5`, `1`, `2`, `4`).
+     */
+    setPlayRate: (rate: number) => void;
+}
+/**
+ * `useTimelinePlayer` manages playback state and controls for a `<Timeline>` component.
+ *
+ * It attaches engine event listeners (`play`, `paused`, `setTimeByTick`) on mount,
+ * exposes reactive state (`isPlaying`, `currentTime`, `playRate`) and all control
+ * functions. Optionally handles loop playback internally via the `loop` option.
+ *
+ * @param ref     - A React ref pointing to the `<Timeline>` component's imperative handle.
+ * @param options - Optional configuration (`seekStep`, `loop`).
+ * @returns {@link TimelinePlayerState} — reactive state + control functions.
+ *
+ * @example
+ * ```tsx
+ * const timelineRef = useRef<TimelineState>(null);
+ *
+ * const player = useTimelinePlayer(timelineRef, {
+ *   seekStep: 5,
+ *   loop: { enabled: loopOn, start: loopStart, end: loopEnd },
+ * });
+ *
+ * // Option A: use the pre-built TransportBar
+ * <TransportBar player={player} />
+ *
+ * // Option B: build your own UI
+ * <button onClick={player.isPlaying ? player.pause : player.play}>
+ *   {player.isPlaying ? '⏸' : '▶'}
+ * </button>
+ * <span>{formatTime(player.currentTime)}</span>
+ * ```
+ */
+export declare function useTimelinePlayer(ref: React.RefObject<TimelineState>, options?: UseTimelinePlayerOptions): TimelinePlayerState;