import React from "react";
import { Clip, TimelineReadonly, Track } from "@techsquidtv/canvas-timeline-core";
//#region src/hooks/clips/useTimelineClipNavigation.d.ts
/**
 * Metadata for one canvas-rendered clip exposed through clip navigation.
 *
 * @remarks
 *
 * Canvas Timeline keeps clip visuals on canvas for performance. This model
 * gives a single DOM focus target enough metadata to announce and manipulate
 * whichever canvas clip is currently active.
 *
 *
 * @see {@link useTimelineClipNavigation}
 */
interface TimelineNavigableClip {
  /** Raw timeline clip represented by this navigation item. */
  clip: TimelineReadonly<Clip>;
  /** Track containing the clip. */
  track: TimelineReadonly<Track<string>>;
  /** Zero-based track index in timeline order. */
  trackIndex: number;
  /** Zero-based clip index inside the track. */
  clipIndex: number;
  /** Zero-based flattened clip index across all tracks. */
  index: number;
  /** Whether the active clip may be moved by command helpers. */
  canMove: boolean;
  /** Whether the active clip may be trimmed by command helpers. */
  canTrim: boolean;
  /** Concise accessible name derived from clip and track labels. */
  name: string;
  /** Longer accessible description with timing and edit-state details. */
  description: string;
}
/**
 * Options for constant-DOM canvas clip navigation.
 *
 * @remarks
 *
 * Use these options when a canvas timeline needs keyboard navigation without
 * rendering one DOM button per clip. `selectOnNavigate` is useful for inspector
 * workflows; leave it disabled when navigation should move a virtual cursor
 * without mutating timeline selection.
 *
 * and description formatters.
 */
interface TimelineClipNavigationOptions {
  /** Initial active clip id. Defaults to selected clip, then the first clip. */
  initialClipId?: string | null;
  /** Whether next/previous navigation wraps around the clip list. Defaults to true. */
  wrap?: boolean;
  /** Whether navigation also selects the active clip in the engine. Defaults to false. */
  selectOnNavigate?: boolean;
  /** Optional accessible label formatter for a canvas-rendered clip. */
  getClipAriaLabel?: (clip: TimelineReadonly<Clip>, track: TimelineReadonly<Track<string>>) => string;
  /** Optional accessible description formatter for a canvas-rendered clip. */
  getClipAriaDescription?: (clip: TimelineReadonly<Clip>, track: TimelineReadonly<Track<string>>) => string;
}
/**
 * Provides constant-DOM keyboard navigation and commands for canvas clips.
 *
 * The hook flattens canvas-rendered clips into a navigable model without
 * mounting one DOM element per clip. Consumers can use the returned
 * `focusTargetProps` on a single focused element, or wire the navigation and
 * edit commands into their own shortcut system and selected-clip inspector.
 *
 * @param options - Initial active clip and navigation behavior options.
 * @returns Active clip metadata, flattened clip list, navigation commands, edit commands, and optional focus-target props.
 * clips.
 *
 * @example
 * ```tsx
 * import { useTimelineClipNavigation } from '@techsquidtv/canvas-timeline-react';
 *
 * export function CanvasClipNavigator() {
 *   const clipNavigation = useTimelineClipNavigation({ selectOnNavigate: true });
 *
 *   return (
 *     <div {...clipNavigation.focusTargetProps}>
 *       <p>{clipNavigation.activeClipStatus}</p>
 *       <button type="button" onClick={() => clipNavigation.navigatePrevious()}>
 *         Previous clip
 *       </button>
 *       <button type="button" onClick={() => clipNavigation.navigateNext()}>
 *         Next clip
 *       </button>
 *     </div>
 *   );
 * }
 * ```
 *
 * @see {@link TimelineNavigableClip}
 * @see {@link https://canvastimeline.com/docs/react-hooks | React editor hooks}
 */
declare function useTimelineClipNavigation(options?: TimelineClipNavigationOptions): {
  /** Metadata for the active navigable clip, or `null` when no clips exist. */
  activeClip: TimelineNavigableClip | null;
  /** Clip id for the active navigable clip. */
  activeClipId: any;
  /** Flattened list of canvas clips with accessibility metadata. */
  clips: TimelineNavigableClip[];
  /** Number of navigable clips. */
  clipCount: number;
  /** Sets the active clip id and optionally selects it in the engine. */
  setActiveClip: (clipId: string | null) => void;
  /** Moves active navigation by a flattened clip delta. */
  navigateBy: (delta: number) => TimelineNavigableClip | null;
  /** Moves active navigation vertically between tracks. */
  navigateToTrack: (delta: number) => TimelineNavigableClip | null;
  /** Moves active navigation to the first clip in timeline order. */
  navigateToFirst: () => TimelineNavigableClip;
  /** Moves active navigation to the last clip in timeline order. */
  navigateToLast: () => TimelineNavigableClip;
  /** Selects the active clip in the timeline engine. */
  selectActiveClip: () => void;
  /** Moves the active clip by a relative number of seconds and returns the command result. */
  moveActiveClipBy: (deltaSeconds: number) => any;
  /** Moves the active clip vertically by a relative track delta and returns the command result. */
  moveActiveClipToTrack: (deltaTrackIndex: number) => any;
  /** Trims one edge of the active clip by a relative number of seconds and returns the command result. */
  trimActiveClipBy: (edge: "start" | "end", deltaSeconds: number) => any;
  /** Builds props for a single focusable clip-navigation target. */
  getFocusTargetProps: <T extends HTMLElement>(props?: React.HTMLAttributes<T>) => React.HTMLAttributes<T>;
  /** Whether the returned focus target currently contains focus. */
  isFocusTargetFocused: boolean;
  /** Active clip summary suitable for an accessible label or live status. */
  activeClipStatusText: string;
  /** Default props for a single focusable clip-navigation target. */
  focusTargetProps: React.HTMLAttributes<HTMLElement>;
};
//#endregion
export { TimelineClipNavigationOptions, TimelineNavigableClip, useTimelineClipNavigation };
//# sourceMappingURL=useTimelineClipNavigation.d.mts.map