TypeScript Types and Interfaces

interface ReactFocusLockProps<ChildrenType = ReactNode, LockProps = Record<string, any>> {
  /** Enable or disable the focus lock */
  disabled?: boolean;

  /** 
   * Return focus to previous position on unmount
   * Can be boolean, FocusOptions, or function for custom control
   */
  returnFocus?: boolean | FocusOptions | ((returnTo: Element) => boolean | FocusOptions);

  /** 
   * @deprecated Can lead to wrong user experience. Use only if you know what you are doing.
   * Controls behavior of returning focus back to the lock
   */
  focusOptions?: FocusOptions;

  /** 
   * @deprecated Use persistentFocus=false instead
   * Enable text selection, allows no focus
   */
  allowTextSelection?: boolean;

  /** 
   * Require persistent focus, disables text selection
   * @default false
   */
  persistentFocus?: boolean;

  /** 
   * Enable cross-iframe focus handling
   * @default true
   */
  crossFrame?: boolean;

  /** 
   * Auto-focus on activation
   * @default true
   */
  autoFocus?: boolean;

  /** Disable focus guards */
  noFocusGuards?: boolean | "tail";

  /** 
   * Handle positive tab indices
   * @default false
   */
  hasPositiveIndices?: boolean;

  /** Named group for scattered locks */
  group?: string;

  /** CSS class name */
  className?: string;

  /** Lifecycle callback on lock activation */
  onActivation?(node: HTMLElement): void;

  /** Lifecycle callback on lock deactivation */
  onDeactivation?(node: HTMLElement): void;

  /** Component element type, defaults to 'div' */
  as?: string | ElementType<LockProps & { children: ChildrenType }>;

  /** Additional props for wrapper element */
  lockProps?: LockProps;

  /** React ref */
  ref?: Ref<HTMLElement>;

  /** Focus whitelist function */
  whiteList?: (activeElement: HTMLElement) => boolean;

  /** Scattered lock elements */
  shards?: Array<RefObject<any> | HTMLElement>;

  /** Child components */
  children?: ChildrenType;
}

interface FocusControl {
  /** 
   * Move focus to the current scope, acts as autofocus
   * @returns Promise that resolves when focus is moved
   */
  autoFocus(): Promise<void>;

  /** 
   * Focus the next element in the scope
   * If active element is not in scope, autofocus will be triggered first
   * @param options - Focus behavior options
   * @returns Promise that resolves when focus is moved
   */
  focusNext(options?: FocusOptions): Promise<void>;

  /** 
   * Focus the previous element in the scope
   * If active element is not in scope, autofocus will be triggered first
   * @param options - Focus behavior options
   * @returns Promise that resolves when focus is moved
   */
  focusPrev(options?: FocusOptions): Promise<void>;

  /** 
   * Focus the first element in the scope
   * @param options - Focus behavior options
   * @returns Promise that resolves when focus is moved
   */
  focusFirst(options?: Pick<FocusOptions, 'onlyTabbable'>): Promise<void>;

  /** 
   * Focus the last element in the scope
   * @param options - Focus behavior options
   * @returns Promise that resolves when focus is moved
   */
  focusLast(options?: Pick<FocusOptions, 'onlyTabbable'>): Promise<void>;
}

interface FocusOptions {
  /** 
   * Enable focus cycle behavior
   * @default true
   */
  cycle?: boolean;

  /** 
   * Limit focusables to tabbable elements only (tabindex >= 0)
   * @default true
   */
  onlyTabbable?: boolean;
}

interface FocusCallbacks {
  /** Called when focus enters the tracked element */
  onFocus(): void;

  /** Called when focus leaves the tracked element */
  onBlur(): void;
}

interface AutoFocusProps {
  /** Child components */
  children: ReactNode;

  /** Disable the autofocus behavior */
  disabled?: boolean;

  /** CSS class name */
  className?: string;
}

interface FreeFocusProps {
  /** Child components */
  children: ReactNode;

  /** CSS class name */
  className?: string;
}

interface InFocusGuardProps {
  /** Child components */
  children?: ReactNode;
}

interface UseFocusStateReturn<T extends Element> {
  /** 
   * Whether currently focused or focus is inside
   * Updates when focus enters or leaves the element
   */
  active: boolean;

  /** 
   * Focus state string indicating type of focus relationship
   * Indicates the type of focus relationship
   */
  state: string;

  /** 
   * Focus event handler to be passed to the tracked element
   * Required for proper focus state tracking
   */
  onFocus: FocusEventHandler<T>;

  /** 
   * React ref to the tracked element
   * Used internally to monitor focus state
   */
  ref: RefObject<T>;
}

/**
 * Generic type constraint for HTML elements in focus controller
 * Extends HTMLElement to ensure proper element handling
 */
type Elements = HTMLElement;

/**
 * Generic type for children prop in focus lock components
 * Defaults to ReactNode for maximum flexibility
 */
type ChildrenType = ReactNode;

/**
 * Generic type for additional properties passed to lock wrapper
 * Defaults to Record<string, any> for flexibility
 */
type LockProps = Record<string, any>;

import React, { useRef } from "react";
import FocusLock, { 
  ReactFocusLockProps, 
  FocusControl, 
  useFocusScope 
} from "react-focus-lock";

// Type-safe props
const focusLockProps: ReactFocusLockProps = {
  disabled: false,
  returnFocus: true,
  autoFocus: true,
  onActivation: (node: HTMLElement) => {
    console.log("Activated:", node);
  }
};

// Type-safe hook usage
function TypedModal() {
  const focusControl: FocusControl = useFocusScope();
  
  const handleNext = async (): Promise<void> => {
    await focusControl.focusNext({ cycle: true, onlyTabbable: false });
  };

  return (
    <div>
      <input />
      <button onClick={handleNext}>Next</button>
    </div>
  );
}

// Full example with types
function App() {
  return (
    <FocusLock {...focusLockProps}>
      <TypedModal />
    </FocusLock>
  );
}