@keplar-404/react-timeline-editor 1.0.6

package/src/components/cursor/cursor.css

@@ -0,0 +1,26 @@
+.timeline-editor-cursor {
+  cursor: ew-resize;
+  position: absolute;
+  top: 32px;
+  height: calc(100% - 32px);
+  box-sizing: border-box;
+  border-left: 1px solid #5297FF;
+  border-right: 1px solid #5297FF;
+  transform: translateX(-25%) scaleX(0.5);
+}
+.timeline-editor-cursor-top {
+  position: absolute;
+  top: 0;
+  left: 50%;
+  transform: translate(-50%, 0) scaleX(2);
+  margin: auto;
+}
+.timeline-editor-cursor-area {
+  width: 16px;
+  height: 100%;
+  cursor: ew-resize;
+  position: absolute;
+  top: 0;
+  left: 50%;
+  transform: translateX(-50%);
+}

package/src/components/cursor/cursor.tsx

@@ -0,0 +1,105 @@
+import React, { FC, useEffect, useRef } from 'react';
+import { ScrollSync } from 'react-virtualized';
+import { CommonProp } from '../../interface/common_prop';
+import { prefix } from '../../utils/deal_class_prefix';
+import { parserPixelToTime, parserTimeToPixel } from '../../utils/deal_data';
+import { RowDnd } from '../row_rnd/row_rnd';
+import { RowRndApi } from '../row_rnd/row_rnd_interface';
+import './cursor.css';
+
+/** 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 const Cursor: FC<CursorProps> = ({
+  disableDrag,
+  cursorTime,
+  setCursor,
+  startLeft,
+  timelineWidth,
+  scaleWidth,
+  scale,
+  scrollLeft,
+  scrollSync,
+  areaRef,
+  maxScaleCount,
+  deltaScrollLeft,
+  onCursorDragStart,
+  onCursorDrag,
+  onCursorDragEnd,
+}) => {
+  const rowRnd = useRef<RowRndApi>(null);
+  const draggingLeft = useRef<undefined | number>();
+
+  useEffect(() => {
+    if (typeof draggingLeft.current === 'undefined') {
+      // When not dragging, update cursor scale according to parameters
+      rowRnd.current?.updateLeft(parserTimeToPixel(cursorTime, { startLeft, scaleWidth, scale }) - scrollLeft);
+    }
+  }, [cursorTime, startLeft, scaleWidth, scale, scrollLeft]);
+
+  return (
+    <RowDnd
+      start={startLeft}
+      ref={rowRnd}
+      parentRef={areaRef}
+      bounds={{
+        left: 0,
+        right: Math.min(timelineWidth, maxScaleCount * scaleWidth + startLeft - scrollLeft),
+      }}
+      deltaScrollLeft={deltaScrollLeft}
+      enableDragging={!disableDrag}
+      enableResizing={false}
+      onDragStart={() => {
+        onCursorDragStart && onCursorDragStart(cursorTime);
+        draggingLeft.current = parserTimeToPixel(cursorTime, { startLeft, scaleWidth, scale }) - scrollLeft;
+        rowRnd.current?.updateLeft(draggingLeft.current);
+      }}
+      onDragEnd={() => {
+        const time = parserPixelToTime((draggingLeft.current || 0) + scrollLeft, { startLeft, scale, scaleWidth });
+        setCursor({ time });
+        onCursorDragEnd && onCursorDragEnd(time);
+        draggingLeft.current = undefined;
+      }}
+      onDrag={({ left }, scroll = 0) => {
+        const scrollLeft = scrollSync.current?.state.scrollLeft || 0;
+
+        if (!scroll || scrollLeft === 0) {
+          // When dragging, if current left < min left, set value to min left
+          if (left < startLeft - scrollLeft) draggingLeft.current = startLeft - scrollLeft;
+          else draggingLeft.current = left;
+        } else {
+          // During auto-scrolling, if current left < min left, set value to min left
+          if ((draggingLeft.current || 0) < startLeft - scrollLeft - scroll) {
+            draggingLeft.current = startLeft - scrollLeft - scroll;
+          }
+        }
+        rowRnd.current?.updateLeft(draggingLeft.current || 0);
+        const time = parserPixelToTime((draggingLeft.current || 0) + scrollLeft, { startLeft, scale, scaleWidth });
+        setCursor({ time });
+        onCursorDrag && onCursorDrag(time);
+        return false;
+      }}
+    >
+      <div className={prefix('cursor')}>
+        <svg className={prefix('cursor-top')} width="8" height="12" viewBox="0 0 8 12" fill="none">
+          <path
+            d="M0 1C0 0.447715 0.447715 0 1 0H7C7.55228 0 8 0.447715 8 1V9.38197C8 9.76074 7.786 10.107 7.44721 10.2764L4.44721 11.7764C4.16569 11.9172 3.83431 11.9172 3.55279 11.7764L0.552786 10.2764C0.214002 10.107 0 9.76074 0 9.38197V1Z"
+            fill="#5297FF"
+          />
+        </svg>
+        <div className={prefix('cursor-area')} />
+      </div>
+    </RowDnd>
+  );
+};

package/src/components/cut-overlay/CutOverlay.css

@@ -0,0 +1,68 @@
+/* ──────────────────────────────────────────
+   Cut Overlay — Structural Styles
+   (Colors are controlled via inline styles from CutOverlayConfig)
+────────────────────────────────────────── */
+.cut-overlay {
+  position: absolute;
+  inset: 0;
+  z-index: 20;
+  pointer-events: auto;
+  user-select: none;
+}
+/* Block clip box: sized exactly to the action block.
+   background and border are injected inline via config. */
+.cut-block-clip {
+  position: absolute;
+  pointer-events: none;
+  border-radius: 3px;
+  box-sizing: border-box;
+  overflow: visible;
+}
+/* Vertical blade line */
+.cut-blade {
+  position: absolute;
+  top: 0;
+  width: 2px;
+  height: 100%;
+  transform: translateX(-50%);
+  border-radius: 1px;
+  pointer-events: none;
+  z-index: 2;
+  animation: cut-blade-in 0.1s ease-out;
+}
+@keyframes cut-blade-in {
+  from {
+    opacity: 0;
+    transform: translateX(-50%) scaleY(0.3);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(-50%) scaleY(1);
+  }
+}
+/* Floating time pill above the block */
+.cut-pill {
+  position: absolute;
+  bottom: calc(100% + 5px);
+  transform: translateX(-50%);
+  font-size: 10px;
+  font-weight: 700;
+  font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', monospace;
+  letter-spacing: 0.04em;
+  padding: 2px 7px;
+  border-radius: 4px;
+  white-space: nowrap;
+  pointer-events: none;
+  animation: cut-pill-in 0.1s ease-out;
+  z-index: 25;
+}
+@keyframes cut-pill-in {
+  from {
+    opacity: 0;
+    transform: translateX(-50%) translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(-50%) translateY(0);
+  }
+}

package/src/components/cut-overlay/CutOverlay.tsx

@@ -0,0 +1,491 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { TimelineAction, TimelineRow } from '@keplar-404/timeline-engine';
+import './CutOverlay.css';
+
+// ─────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────
+
+function pixelToTime(px: number, startLeft: number, scale: number, scaleWidth: number): number {
+  return ((px - startLeft) / scaleWidth) * scale;
+}
+
+function timeToPixel(time: number, startLeft: number, scale: number, scaleWidth: number, scrollLeft: number): number {
+  return startLeft + (time / scale) * scaleWidth - scrollLeft;
+}
+
+function snapToGrid(time: number, scale: number, scaleSplitCount: number): number {
+  const unit = scale / scaleSplitCount;
+  return Math.round(time / unit) * unit;
+}
+
+// ─────────────────────────────────────────────
+// Public Types
+// ─────────────────────────────────────────────
+
+/**
+ * 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 {
+  // ── Blade ──────────────────────────────────────────────────────────────────
+
+  /**
+   * CSS color of the vertical blade line.
+   * @default '#ef4444'
+   */
+  bladeColor?: string;
+
+  // ── Pill ───────────────────────────────────────────────────────────────────
+
+  /**
+   * 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;
+
+  // ── Block highlight ────────────────────────────────────────────────────────
+
+  /**
+   * 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;
+
+  // ── Interactivity ──────────────────────────────────────────────────────────
+
+  /**
+   * 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 {
+  // ── Data ───────────────────────────────────────────────────────────────────
+
+  /**
+   * 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[];
+
+  // ── Timeline geometry (must match <Timeline> props) ────────────────────────
+
+  /**
+   * 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;
+
+  // ── Behaviour ──────────────────────────────────────────────────────────────
+
+  /**
+   * 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;
+
+  // ── Visual configuration ───────────────────────────────────────────────────
+
+  /**
+   * 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;
+
+  // ── Callbacks ──────────────────────────────────────────────────────────────
+
+  /**
+   * 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;
+}
+
+// ─────────────────────────────────────────────
+// Internal state
+// ─────────────────────────────────────────────
+
+interface BladeState {
+  time: number;
+  bladeX: number;
+  blockLeft: number;
+  blockWidth: number;
+  rowTop: number;
+  row: TimelineRow;
+  action: TimelineAction;
+}
+
+// ─────────────────────────────────────────────
+// Defaults
+// ─────────────────────────────────────────────
+
+const DEFAULT_CONFIG: Omit<Required<CutOverlayConfig>, 'keyboardModifier'> & { keyboardModifier?: CutOverlayConfig['keyboardModifier'] } = {
+  bladeColor: '#ef4444',
+  showPill: true,
+  formatPillLabel: (t) => `✂ ${t.toFixed(2)}s`,
+  pillColor: '#ef4444',
+  pillTextColor: '#ffffff',
+  showBlockHighlight: true,
+  blockHighlightColor: 'rgba(239,68,68,0.08)',
+  blockHighlightBorderColor: 'rgba(239,68,68,0.3)',
+  cursor: 'col-resize',
+};
+
+// ─────────────────────────────────────────────
+// Component
+// ─────────────────────────────────────────────
+
+/**
+ * `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)}
+ *   />
+ * )}
+ * ```
+ */
+const CutOverlay: React.FC<CutOverlayProps> = ({
+  data,
+  scale,
+  scaleSplitCount,
+  scaleWidth,
+  startLeft,
+  rowHeight,
+  gridSnap,
+  editAreaTopOffset,
+  config,
+  onCut,
+  onModifierChange,
+}) => {
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const [blade, setBlade] = useState<BladeState | null>(null);
+  const [isModifierHeld, setIsModifierHeld] = useState(false);
+  // Ref so handleMouseMove always reads the latest value without stale closure
+  const isModifierHeldRef = useRef(false);
+  // Ref for onModifierChange so it never needs to be in a useEffect dep array
+  const onModifierChangeRef = useRef(onModifierChange);
+
+  // Keep both refs in sync on every render (no effect needed — runs synchronously)
+  isModifierHeldRef.current = isModifierHeld;
+  onModifierChangeRef.current = onModifierChange;
+
+  // Keep isModifierHeldRef in sync with state for the memoised handleMouseMove callback
+  useEffect(() => {
+    isModifierHeldRef.current = isModifierHeld;
+  }, [isModifierHeld]);
+
+  // Merge user config with defaults
+  const cfg = { 
+    ...DEFAULT_CONFIG, 
+    ...config,
+    // We safely preserve undefined for keyboardModifier if not passed
+    keyboardModifier: config?.keyboardModifier,
+  };
+
+  React.useEffect(() => {
+    if (!cfg.keyboardModifier) {
+      // If no modifier is required, we treat it as always held
+      setIsModifierHeld(true);
+      // No need to fire onModifierChange — caller should keep drag disabled
+      return;
+    }
+
+    const modifierTarget = cfg.keyboardModifier.toLowerCase();
+    // Modifier just configured — key is not yet held
+    setIsModifierHeld(false);
+    onModifierChangeRef.current?.(false);
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key.toLowerCase() === modifierTarget) {
+        setIsModifierHeld(true);
+        onModifierChangeRef.current?.(true);
+      }
+    };
+
+    const handleKeyUp = (e: KeyboardEvent) => {
+      if (e.key.toLowerCase() === modifierTarget) {
+        setIsModifierHeld(false);
+        setBlade(null);
+        onModifierChangeRef.current?.(false);
+      }
+    };
+
+    const handleBlur = () => {
+      setIsModifierHeld(false);
+      setBlade(null);
+      onModifierChangeRef.current?.(false);
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    window.addEventListener('keyup', handleKeyUp);
+    window.addEventListener('blur', handleBlur);
+
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown);
+      window.removeEventListener('keyup', handleKeyUp);
+      window.removeEventListener('blur', handleBlur);
+    };
+  }, [cfg.keyboardModifier]); // onModifierChange intentionally omitted — accessed via ref
+
+  const handleMouseMove = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (!isModifierHeldRef.current) return;
+
+      const rect = overlayRef.current?.getBoundingClientRect();
+      if (!rect) return;
+
+      // Read actual horizontal scroll from the ReactVirtualized grid DOM element.
+      // Timeline's onScroll prop only fires for vertical scroll, so we query the DOM.
+      const editGrid = overlayRef.current
+        ?.closest('.timeline-wrapper')
+        ?.querySelector('.timeline-editor-edit-area .ReactVirtualized__Grid') as HTMLElement | null;
+      const actualScrollLeft = editGrid?.scrollLeft ?? 0;
+
+      const relativeX = e.clientX - rect.left;
+      const relativeY = e.clientY - rect.top;
+
+      const editY = relativeY - editAreaTopOffset;
+      if (editY < 0) { setBlade(null); return; }
+
+      let time = pixelToTime(relativeX + actualScrollLeft, startLeft, scale, scaleWidth);
+      if (gridSnap) {
+        time = snapToGrid(time, scale, scaleSplitCount);
+      }
+
+      const rowIndex = Math.floor(editY / rowHeight);
+      const row = data[rowIndex];
+      if (!row) { setBlade(null); return; }
+
+      const action = row.actions.find((a) => time > a.start && time < a.end) ?? null;
+      if (!action) { setBlade(null); return; }
+
+      const blockLeft = timeToPixel(action.start, startLeft, scale, scaleWidth, actualScrollLeft);
+      const blockRight = timeToPixel(action.end, startLeft, scale, scaleWidth, actualScrollLeft);
+      const blockWidth = blockRight - blockLeft;
+      const bladeX = timeToPixel(time, startLeft, scale, scaleWidth, actualScrollLeft);
+
+      setBlade({ time, bladeX, blockLeft, blockWidth, rowTop: editAreaTopOffset + rowIndex * rowHeight, row, action });
+    },
+    [data, scale, scaleSplitCount, scaleWidth, startLeft, rowHeight, gridSnap, editAreaTopOffset],
+  );
+
+  const handleMouseLeave = useCallback(() => setBlade(null), []);
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (!blade) return;
+      e.stopPropagation();
+      onCut(blade.row.id, blade.action.id, blade.time);
+    },
+    [blade, onCut],
+  );
+
+  return (
+    <div
+      ref={overlayRef}
+      className={`cut-overlay${blade ? ' cut-overlay--active' : ''}`}
+      style={{
+        cursor: isModifierHeld ? cfg.cursor : 'default',
+        // Make the overlay pass-through mouse events when the modifier isn't held,
+        // so actual timeline interactions can happen natively.
+        pointerEvents: isModifierHeld ? 'auto' : 'none',
+      }}
+      onMouseMove={handleMouseMove}
+      onMouseLeave={handleMouseLeave}
+      onClick={handleClick}
+    >
+      {blade && (
+        <div
+          className="cut-block-clip"
+          style={{
+            left: blade.blockLeft,
+            top: blade.rowTop,
+            width: blade.blockWidth,
+            height: rowHeight,
+            // Highlight: fully controllable via config
+            background: cfg.showBlockHighlight ? cfg.blockHighlightColor : 'transparent',
+            border: cfg.showBlockHighlight
+              ? `1px solid ${cfg.blockHighlightBorderColor}`
+              : 'none',
+          }}
+        >
+          {/* Vertical blade line */}
+          <div
+            className="cut-blade"
+            style={{
+              left: blade.bladeX - blade.blockLeft,
+              background: cfg.bladeColor,
+              boxShadow: `0 0 8px ${cfg.bladeColor}cc, 0 0 2px ${cfg.bladeColor}`,
+            }}
+          />
+
+          {/* Time pill — optional */}
+          {cfg.showPill && (
+            <div
+              className="cut-pill"
+              style={{
+                left: blade.bladeX - blade.blockLeft,
+                background: cfg.pillColor,
+                color: cfg.pillTextColor,
+              }}
+            >
+              {cfg.formatPillLabel(blade.time)}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default CutOverlay;