@keplar-404/react-timeline-editor 1.0.6

package/src/components/transport/TransportBar.tsx

@@ -0,0 +1,322 @@
+import React from 'react';
+import { TimelinePlayerState, formatTime } from './useTimelinePlayer';
+import './TransportBar.css';
+
+// ─────────────────────────────────────────────
+// Public Types
+// ─────────────────────────────────────────────
+
+/**
+ * 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;
+}
+
+// ─────────────────────────────────────────────
+// Default values
+// ─────────────────────────────────────────────
+
+const DEFAULT_PLAY_RATES = [0.25, 0.5, 1, 2, 4];
+
+// ─────────────────────────────────────────────
+// Component
+// ─────────────────────────────────────────────
+
+/**
+ * `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.
+ */
+const TransportBar: React.FC<TransportBarProps> = ({
+  player,
+  loop,
+  playRates = DEFAULT_PLAY_RATES,
+  formatDisplayTime = formatTime,
+  className,
+  style,
+}) => {
+  const {
+    isPlaying, currentTime, playRate,
+    play, pause, stop, toStart, rewind, forward, setPlayRate,
+  } = player;
+
+  return (
+    <div
+      className={`timeline-transport-bar${className ? ` ${className}` : ''}`}
+      style={style}
+    >
+      {/* ── Left: transport controls ── */}
+      <div className="timeline-transport-controls">
+        {/* To start */}
+        <button
+          className="timeline-transport-btn"
+          title="Return to start"
+          onClick={toStart}
+        >
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+            <rect x="1" y="1" width="2" height="12" rx="1" />
+            <path d="M13 2.27L5.5 7 13 11.73V2.27z" />
+          </svg>
+        </button>
+
+        {/* Rewind */}
+        <button
+          className="timeline-transport-btn"
+          title="Rewind"
+          onClick={rewind}
+        >
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+            <path d="M7.5 2.27L0 7l7.5 4.73V8.96L2.92 7l4.58-5zM14 2.27L6.5 7 14 11.73V2.27z" />
+          </svg>
+        </button>
+
+        {/* Play / Pause */}
+        {isPlaying ? (
+          <button
+            className="timeline-transport-btn timeline-transport-btn--primary"
+            title="Pause"
+            onClick={pause}
+          >
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+              <rect x="2" y="1" width="4" height="12" rx="1" />
+              <rect x="8" y="1" width="4" height="12" rx="1" />
+            </svg>
+          </button>
+        ) : (
+          <button
+            className="timeline-transport-btn timeline-transport-btn--primary"
+            title="Play"
+            onClick={play}
+          >
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+              <path d="M2 1.5l11 5.5-11 5.5z" />
+            </svg>
+          </button>
+        )}
+
+        {/* Forward */}
+        <button
+          className="timeline-transport-btn"
+          title="Forward"
+          onClick={forward}
+        >
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+            <path d="M6.5 2.27V5.04L11.08 7 6.5 8.96v2.77L14 7 6.5 2.27zM0 2.27L7.5 7 0 11.73V2.27z" />
+          </svg>
+        </button>
+
+        {/* Stop */}
+        <button
+          className="timeline-transport-btn timeline-transport-btn--stop"
+          title="Stop"
+          onClick={stop}
+        >
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="currentColor">
+            <rect x="1" y="1" width="12" height="12" rx="2" />
+          </svg>
+        </button>
+
+        {/* ── Loop controls (optional) ── */}
+        {loop && (
+          <>
+            <div className="timeline-transport-divider" />
+
+            <button
+              className={`timeline-transport-btn timeline-transport-btn--loop${loop.enabled ? ' timeline-transport-btn--loop-active' : ''}`}
+              title={loop.enabled ? 'Disable loop' : 'Enable loop'}
+              onClick={loop.onToggle}
+            >
+              🔁
+            </button>
+
+            {loop.enabled && (
+              <div className="timeline-transport-loop-inputs">
+                <input
+                  className="timeline-transport-loop-input"
+                  type="number"
+                  step="0.1"
+                  min="0"
+                  value={loop.start}
+                  title="Loop start (seconds)"
+                  onChange={(e) => {
+                    const v = parseFloat(e.target.value);
+                    if (!isNaN(v) && v >= 0 && v < loop.end) loop.onStartChange(v);
+                  }}
+                />
+                <span className="timeline-transport-loop-arrow">→</span>
+                <input
+                  className="timeline-transport-loop-input"
+                  type="number"
+                  step="0.1"
+                  min="0"
+                  value={loop.end}
+                  title="Loop end (seconds)"
+                  onChange={(e) => {
+                    const v = parseFloat(e.target.value);
+                    if (!isNaN(v) && v > loop.start) loop.onEndChange(v);
+                  }}
+                />
+                <span className="timeline-transport-loop-unit">s</span>
+              </div>
+            )}
+          </>
+        )}
+      </div>
+
+      {/* ── Centre: time display ── */}
+      <div className="timeline-transport-time">
+        <span className="timeline-transport-time-value">
+          {formatDisplayTime(currentTime)}
+        </span>
+        <span className="timeline-transport-time-label">TIME</span>
+      </div>
+
+      {/* ── Right: playback rate ── */}
+      <div className="timeline-transport-rate">
+        <span className="timeline-transport-rate-label">SPEED</span>
+        <div className="timeline-transport-rate-buttons">
+          {playRates.map((r) => (
+            <button
+              key={r}
+              className={`timeline-transport-rate-btn${playRate === r ? ' timeline-transport-rate-btn--active' : ''}`}
+              onClick={() => setPlayRate(r)}
+            >
+              {r}×
+            </button>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default TransportBar;

package/src/components/transport/useTimelinePlayer.ts

@@ -0,0 +1,319 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { TimelineState } from '../../interface/timeline';
+
+// ─────────────────────────────────────────────
+// Utility
+// ─────────────────────────────────────────────
+
+/**
+ * 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 function formatTime(seconds: number): string {
+  const m  = Math.floor(seconds / 60);
+  const s  = Math.floor(seconds % 60);
+  const ms = Math.floor((seconds % 1) * 100);
+  return `${m}:${String(s).padStart(2, '0')}.${String(ms).padStart(2, '0')}`;
+}
+
+// ─────────────────────────────────────────────
+// Public Types
+// ─────────────────────────────────────────────
+
+/**
+ * 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 {
+  // ── Reactive state ─────────────────────────────────────────────────────────
+
+  /**
+   * 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;
+
+  // ── Playback controls ──────────────────────────────────────────────────────
+
+  /**
+   * 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;
+}
+
+// ─────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────
+
+/**
+ * `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 function useTimelinePlayer(
+  ref: React.RefObject<TimelineState>,
+  options: UseTimelinePlayerOptions = {},
+): TimelinePlayerState {
+  const { seekStep = 5, loop } = options;
+
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [playRate, setPlayRateState] = useState(1);
+
+  // ── Refs for loop values ──
+  // Using refs instead of state in the tick callback avoids stale closures;
+  // we never need to re-create the listener when loop params change.
+  const loopEnabledRef = useRef(false);
+  const loopStartRef   = useRef(0);
+  const loopEndRef     = useRef(0);
+
+  // Keep refs in sync with options synchronously on every render
+  loopEnabledRef.current = loop?.enabled ?? false;
+  loopStartRef.current   = loop?.start   ?? 0;
+  loopEndRef.current     = loop?.end     ?? 0;
+
+  // ── Engine event listeners ──
+  useEffect(() => {
+    const timeline = ref.current;
+    if (!timeline) return;
+
+    const handlePlay   = () => setIsPlaying(true);
+    const handlePaused = () => setIsPlaying(false);
+
+    const handleTick = ({ time }: { time: number }) => {
+      setCurrentTime(time);
+      // Loop: if loop is enabled and we've passed the end, snap back to start
+      if (loopEnabledRef.current && time >= loopEndRef.current) {
+        ref.current?.setTime(loopStartRef.current);
+      }
+    };
+
+    timeline.listener.on('play',          handlePlay);
+    timeline.listener.on('paused',        handlePaused);
+    timeline.listener.on('setTimeByTick', handleTick);
+
+    return () => {
+      timeline.listener.off('play',          handlePlay);
+      timeline.listener.off('paused',        handlePaused);
+      timeline.listener.off('setTimeByTick', handleTick);
+    };
+  }, [ref]); // ref object is stable across renders — runs once on mount
+
+  // ── Control callbacks ──
+  const play = useCallback(() => {
+    // When loop is enabled, playback must always start inside the loop zone.
+    // If the cursor is sitting before loopStart, snap it there first so the
+    // engine starts from the correct position (the tick handler already handles
+    // the case where the cursor is past loopEnd).
+    if (loopEnabledRef.current) {
+      const currentTime = ref.current?.getTime() ?? 0;
+      if (currentTime < loopStartRef.current) {
+        ref.current?.setTime(loopStartRef.current);
+      }
+    }
+    ref.current?.play({ autoEnd: true });
+  }, [ref]);
+
+  const pause = useCallback(() => {
+    ref.current?.pause();
+  }, [ref]);
+
+  const stop = useCallback(() => {
+    ref.current?.pause();
+    ref.current?.setTime(0);
+    setCurrentTime(0);
+  }, [ref]);
+
+  const toStart = useCallback(() => {
+    ref.current?.pause();
+    ref.current?.setTime(0);
+    setCurrentTime(0);
+  }, [ref]);
+
+  const rewind = useCallback(() => {
+    const cur  = ref.current?.getTime() ?? 0;
+    const next = Math.max(0, cur - seekStep);
+    ref.current?.setTime(next);
+    setCurrentTime(next);
+  }, [ref, seekStep]);
+
+  const forward = useCallback(() => {
+    const cur = ref.current?.getTime() ?? 0;
+    ref.current?.setTime(cur + seekStep);
+  }, [ref, seekStep]);
+
+  const setTime = useCallback((time: number) => {
+    ref.current?.setTime(time);
+    setCurrentTime(time);
+  }, [ref]);
+
+  const setPlayRate = useCallback((rate: number) => {
+    ref.current?.setPlayRate(rate);
+    setPlayRateState(rate);
+  }, [ref]);
+
+  return {
+    isPlaying,
+    currentTime,
+    playRate,
+    play,
+    pause,
+    stop,
+    toStart,
+    rewind,
+    forward,
+    setTime,
+    setPlayRate,
+  };
+}

package/src/index.tsx

@@ -0,0 +1,17 @@
+export * from './components/timeline';
+export { default as CutOverlay } from './components/cut-overlay/CutOverlay';
+export * from './components/cut-overlay/CutOverlay';
+export { default as LoopZoneOverlay } from './components/loop-zone/LoopZoneOverlay';
+export * from './components/loop-zone/LoopZoneOverlay';
+export { default as TransportBar } from './components/transport/TransportBar';
+export * from './components/transport/TransportBar';
+export { useTimelinePlayer, formatTime } from './components/transport/useTimelinePlayer';
+export type {
+  UseTimelinePlayerOptions,
+  UseTimelinePlayerLoop,
+  TimelinePlayerState,
+} from './components/transport/useTimelinePlayer';
+export { splitActionInRow } from './utils/deal_data';
+export * from './interface/timeline';
+export * from '@keplar-404/timeline-engine';
+

package/src/interface/common_prop.ts

@@ -0,0 +1,13 @@
+import { EditData, RequiredEditData } from "./timeline";
+
+/** Common component parameters */
+export interface CommonProp extends RequiredEditData {
+  /** Scale count */
+  scaleCount: number;
+  /** Set scale count */
+  setScaleCount: (scaleCount: number) => void;
+  /** Cursor time */
+  cursorTime: number;
+  /** Current timeline width */
+  timelineWidth: number;
+}

package/src/interface/const.ts

@@ -0,0 +1,32 @@
+export const PREFIX = `timeline-editor`;
+
+/** Cursor time at start */
+export const START_CURSOR_TIME = 0;
+/** Default scale */
+export const DEFAULT_SCALE = 1;
+/** Default scale split count */
+export const DEFAULT_SCALE_SPLIT_COUNT = 10;
+
+/** Default scale display width */
+export const DEFAULT_SCALE_WIDTH = 160;
+/** Default scale start distance from left */
+export const DEFAULT_START_LEFT = 20;
+/** Default minimum movement in pixels */
+export const DEFAULT_MOVE_GRID = 1;
+/** Default adsorption distance in pixels */
+export const DEFAULT_ADSORPTION_DISTANCE = 8;
+/** Default action row height */
+export const DEFAULT_ROW_HEIGHT = 32;
+
+/** Minimum scale count */
+export const MIN_SCALE_COUNT = 20;
+/** Maximum scale count */
+export const MAX_SCALE_COUNT = Infinity;
+/** Number of scale marks to add each time */
+export const ADD_SCALE_COUNT = 5;
+
+/** Error messages */
+export const ERROR = {
+  START_TIME_LESS_THEN_ZERO: 'Action start time cannot be less than 0!',
+  END_TIME_LESS_THEN_START_TIME: 'Action end time cannot be less then start time!',
+}