/*
 * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.
 * This file is licensed to you under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. You may obtain a copy
 * of the License at https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software distributed under
 * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
 * OF ANY KIND, either express or implied. See the License for the specific language
 * governing permissions and limitations under the License.
 */

import { SegmentConfig } from "../../components/coordinate-field/types.js";
import { KeyboardEvent } from "react";

//#region src/hooks/coordinate-field/use-coordinate-focus.d.ts
/** Options for the useCoordinateFocus hook */
interface UseCoordinateFocusOptions {
  /** Array of editable segment configurations */
  editableSegmentConfigs: SegmentConfig[];
}
/** Return value from the useCoordinateFocus hook */
interface UseCoordinateFocusResult {
  /** Array of refs for each input segment */
  segmentRefs: React.RefObject<HTMLInputElement>[];
  /** Index of the currently focused segment (-1 if none) */
  focusedSegmentIndex: number;
  /** Focus a specific segment by index */
  focusSegment: (index: number) => void;
  /** Focus the next segment after the current index */
  focusNextSegment: (currentIndex: number) => void;
  /** Focus the previous segment before the current index */
  focusPreviousSegment: (currentIndex: number) => void;
  /** Focus the first segment */
  focusFirstSegment: () => void;
  /** Focus the last segment */
  focusLastSegment: () => void;
  /** Handle keyboard navigation (Home/End keys) */
  handleSegmentKeyDown: (index: number, e: KeyboardEvent<HTMLInputElement>) => void;
  /** Update the focused segment index state */
  setFocusedSegmentIndex: (index: number) => void;
}
/**
 * Manages focus navigation between coordinate input segments
 *
 * @example
 * ```tsx
 * function CoordinateSegments({ configs }: { configs: SegmentConfig[] }) {
 *   const {
 *     segmentRefs,
 *     focusedSegmentIndex,
 *     focusNextSegment,
 *     focusPreviousSegment,
 *     handleSegmentKeyDown,
 *     setFocusedSegmentIndex,
 *   } = useCoordinateFocus({ editableSegmentConfigs: configs });
 *
 *   return (
 *     <div>
 *       {configs.map((config, i) => (
 *         <input
 *           key={i}
 *           ref={segmentRefs[i]}
 *           onFocus={() => setFocusedSegmentIndex(i)}
 *           onKeyDown={(e) => {
 *             handleSegmentKeyDown(i, e);
 *             if (e.key === 'ArrowRight') focusNextSegment(i);
 *             if (e.key === 'ArrowLeft') focusPreviousSegment(i);
 *           }}
 *           aria-current={focusedSegmentIndex === i || undefined}
 *         />
 *       ))}
 *     </div>
 *   );
 * }
 * ```
 *
 * @param options - {@link UseCoordinateFocusOptions}
 * @param options.editableSegmentConfigs - Array of editable segment configurations.
 * @returns {@link UseCoordinateFocusResult} Focus management utilities and state.
 */
declare function useCoordinateFocus({
  editableSegmentConfigs
}: UseCoordinateFocusOptions): UseCoordinateFocusResult;
//#endregion
export { UseCoordinateFocusOptions, UseCoordinateFocusResult, useCoordinateFocus };
//# sourceMappingURL=use-coordinate-focus.d.ts.map