@accelint/design-toolkit 9.3.0 → 9.4.0

package/dist/hooks/coordinate-field/use-coordinate-field-state.js

@@ -16,6 +16,56 @@ import { getSegmentConfigs } from "../../components/coordinate-field/segment-con
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
 //#region src/hooks/coordinate-field/use-coordinate-field-state.ts
+/**
+* Manages coordinate segment values, validation, and format conversion
+*
+* @example
+* ```tsx
+* function CoordinateInputs() {
+*   const [value, setValue] = useState<CoordinateValue | null>(null);
+*   const { registerTimeout } = useTimeoutCleanup();
+*
+*   const {
+*     currentValue,
+*     segmentValues,
+*     validationErrors,
+*     editableSegmentConfigs,
+*     handleSegmentChange,
+*   } = useCoordinateFieldState({
+*     value,
+*     format: 'ddm',
+*     onChange: setValue,
+*     onError: (msg) => console.error(msg),
+*     registerTimeout,
+*   });
+*
+*   return (
+*     <div>
+*       {editableSegmentConfigs.map((config, i) => (
+*         <input
+*           key={i}
+*           value={segmentValues[i]}
+*           onChange={(e) => handleSegmentChange(i, e.target.value)}
+*           placeholder={config.placeholder}
+*         />
+*       ))}
+*       {validationErrors.map((error, i) => (
+*         <span key={i}>{error}</span>
+*       ))}
+*     </div>
+*   );
+* }
+* ```
+*
+* @param options - {@link UseCoordinateFieldStateOptions}
+* @param options.value - Controlled coordinate value.
+* @param options.defaultValue - Default value for uncontrolled mode.
+* @param options.format - Coordinate format system (dd, ddm, dms, mgrs, utm).
+* @param options.onChange - Callback when coordinate value changes.
+* @param options.onError - Callback for validation errors.
+* @param options.registerTimeout - Register timeouts for cleanup on unmount.
+* @returns {@link UseCoordinateFieldStateResult} Segment state, validation, and change handlers.
+*/
 function useCoordinateFieldState({ value, defaultValue, format, onChange, onError, registerTimeout }) {
 	const [internalValue, setInternalValue] = useState(defaultValue || null);
 	const [validationErrors, setValidationErrors] = useState([]);

package/dist/hooks/coordinate-field/use-coordinate-field-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-coordinate-field-state.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-field-state.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport {\n  type Dispatch,\n  type SetStateAction,\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from 'react';\nimport {\n  areAllSegmentsFilled,\n  convertDDToDisplaySegments,\n  convertDisplaySegmentsToDD,\n  validateCoordinateSegments,\n} from '../../components/coordinate-field/coordinate-utils';\nimport { getSegmentConfigs } from '../../components/coordinate-field/segment-configs';\nimport type {\n  CoordinateSystem,\n  CoordinateValue,\n  SegmentConfig,\n} from '../../components/coordinate-field/types';\n\nexport interface UseCoordinateFieldStateOptions {\n  value?: CoordinateValue | null;\n  defaultValue?: CoordinateValue;\n  format: CoordinateSystem;\n  onChange?:\n    | Dispatch<SetStateAction<CoordinateValue | null>>\n    | ((value: CoordinateValue | null) => void);\n  onError?: (message: string, context?: Record<string, unknown>) => void;\n  registerTimeout?: (timeoutId: NodeJS.Timeout) => void;\n}\n\nexport interface UseCoordinateFieldStateResult {\n  currentValue: CoordinateValue | null;\n  segmentValues: string[];\n  validationErrors: string[];\n  segmentConfigs: SegmentConfig[];\n  editableSegmentConfigs: SegmentConfig[];\n  handleSegmentChange: (index: number, newValue: string) => void;\n  setSegmentValues: (values: string[]) => void;\n  setValidationErrors: (errors: string[]) => void;\n  effectiveErrorMessage: string | null;\n  applyPastedCoordinate: (pastedValue: CoordinateValue) => void;\n  flushPendingValidation: () => void;\n}\n\nexport function useCoordinateFieldState({\n  value,\n  defaultValue,\n  format,\n  onChange,\n  onError,\n  registerTimeout,\n}: UseCoordinateFieldStateOptions): UseCoordinateFieldStateResult {\n  const [internalValue, setInternalValue] = useState<CoordinateValue | null>(\n    defaultValue || null,\n  );\n  const [validationErrors, setValidationErrors] = useState<string[]>([]);\n  const validationTimeoutRef = useRef<NodeJS.Timeout | null>(null);\n\n  const currentValue = value !== undefined ? value : internalValue;\n\n  const clearValidationTimeout = () => {\n    if (validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n      validationTimeoutRef.current = null;\n    }\n  };\n\n  const handleChange = (newValue: CoordinateValue | null) => {\n    if (value === undefined) {\n      setInternalValue(newValue);\n    }\n    onChange?.(newValue);\n  };\n\n  const segmentConfigs = useMemo(() => getSegmentConfigs(format), [format]);\n\n  const editableSegmentConfigs = useMemo(\n    () => segmentConfigs.flat().filter((config) => config.type !== 'literal'),\n    [segmentConfigs],\n  );\n\n  const [segmentValues, setSegmentValues] = useState<string[]>(() => {\n    const initialValue = value !== undefined ? value : defaultValue;\n    if (!initialValue) {\n      return new Array(editableSegmentConfigs.length).fill('');\n    }\n\n    const segments = convertDDToDisplaySegments(initialValue, format);\n    if (!segments) {\n      return new Array(editableSegmentConfigs.length).fill('');\n    }\n\n    return segments;\n  });\n\n  const convertValueToSegmentsOrClear = useCallback(\n    (valueToConvert: CoordinateValue | null) => {\n      // Clear any pending validation when value changes\n      clearValidationTimeout();\n\n      const segments = valueToConvert\n        ? convertDDToDisplaySegments(valueToConvert, format)\n        : null;\n\n      setSegmentValues(\n        segments || new Array(editableSegmentConfigs.length).fill(''),\n      );\n      setValidationErrors([]);\n    },\n    [format, editableSegmentConfigs.length],\n  );\n\n  const prevFormatRef = useRef(format);\n\n  useEffect(() => {\n    if (prevFormatRef.current !== format) {\n      prevFormatRef.current = format;\n      const valueToConvert = value !== undefined ? value : internalValue;\n      convertValueToSegmentsOrClear(valueToConvert);\n    }\n  }, [format, value, internalValue, convertValueToSegmentsOrClear]);\n\n  useEffect(() => {\n    if (value !== undefined) {\n      convertValueToSegmentsOrClear(value);\n    }\n  }, [value, convertValueToSegmentsOrClear]);\n\n  /**\n   * Validates segment values and updates the coordinate state\n   *\n   * When validation fails, calls onError with \"Invalid coordinate value\" message\n   * and context containing the detailed validation errors from @accelint/geo.\n   *\n   * @param updatedValues - Array of segment values to validate\n   */\n  const validateAndUpdateCoordinate = (updatedValues: string[]) => {\n    const errors = validateCoordinateSegments(updatedValues, format);\n\n    if (errors.length > 0) {\n      setValidationErrors(errors);\n      onError?.('Invalid coordinate value', {\n        errors,\n        format,\n        segments: updatedValues,\n      });\n      handleChange(null);\n      return;\n    }\n\n    const ddValue = convertDisplaySegmentsToDD(updatedValues, format);\n    if (!ddValue) {\n      const errorMsg = 'Invalid coordinate value';\n      setValidationErrors([errorMsg]);\n      onError?.(errorMsg, { format, segments: updatedValues });\n      handleChange(null);\n      return;\n    }\n\n    setValidationErrors([]);\n    handleChange(ddValue);\n  };\n\n  const handleSegmentChange = (index: number, newValue: string) => {\n    const updatedValues = [...segmentValues];\n    updatedValues[index] = newValue;\n    setSegmentValues(updatedValues);\n\n    if (areAllSegmentsFilled(updatedValues)) {\n      // Clear any pending validation timeout\n      clearValidationTimeout();\n\n      // Debounce validation by 400ms when all segments are full\n      const timeoutId = setTimeout(() => {\n        validateAndUpdateCoordinate(updatedValues);\n        validationTimeoutRef.current = null;\n      }, 400);\n\n      validationTimeoutRef.current = timeoutId;\n      registerTimeout?.(timeoutId);\n    } else {\n      // Clear any pending validation when segments become incomplete\n      clearValidationTimeout();\n      setValidationErrors([]);\n      if (currentValue !== null) {\n        handleChange(null);\n      }\n    }\n  };\n\n  const applyPastedCoordinate = (pastedValue: CoordinateValue) => {\n    // Clear any pending validation when applying pasted coordinate\n    clearValidationTimeout();\n\n    const segments = convertDDToDisplaySegments(pastedValue, format);\n\n    if (segments) {\n      setSegmentValues(segments);\n      setValidationErrors([]);\n      handleChange(pastedValue);\n    }\n  };\n\n  const flushPendingValidation = () => {\n    if (validationTimeoutRef.current) {\n      clearValidationTimeout();\n\n      // Immediately validate if all segments are filled\n      if (areAllSegmentsFilled(segmentValues)) {\n        validateAndUpdateCoordinate(segmentValues);\n      }\n    }\n  };\n\n  const effectiveErrorMessage = useMemo(\n    () => validationErrors[0] || null,\n    [validationErrors],\n  );\n\n  return {\n    currentValue,\n    segmentValues,\n    validationErrors,\n    segmentConfigs,\n    editableSegmentConfigs,\n    handleSegmentChange,\n    setSegmentValues,\n    setValidationErrors,\n    effectiveErrorMessage,\n    applyPastedCoordinate,\n    flushPendingValidation,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"use-coordinate-field-state.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-field-state.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport {\n  type Dispatch,\n  type SetStateAction,\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from 'react';\nimport {\n  areAllSegmentsFilled,\n  convertDDToDisplaySegments,\n  convertDisplaySegmentsToDD,\n  validateCoordinateSegments,\n} from '../../components/coordinate-field/coordinate-utils';\nimport { getSegmentConfigs } from '../../components/coordinate-field/segment-configs';\nimport type {\n  CoordinateSystem,\n  CoordinateValue,\n  SegmentConfig,\n} from '../../components/coordinate-field/types';\n\n/** Options for the useCoordinateFieldState hook */\nexport interface UseCoordinateFieldStateOptions {\n  /** Controlled coordinate value */\n  value?: CoordinateValue | null;\n  /** Default value for uncontrolled mode */\n  defaultValue?: CoordinateValue;\n  /** Coordinate format system (dd, ddm, dms, mgrs, utm) */\n  format: CoordinateSystem;\n  /** Callback when coordinate value changes */\n  onChange?:\n    | Dispatch<SetStateAction<CoordinateValue | null>>\n    | ((value: CoordinateValue | null) => void);\n  /** Callback for validation errors */\n  onError?: (message: string, context?: Record<string, unknown>) => void;\n  /** Register timeouts for cleanup on unmount */\n  registerTimeout?: (timeoutId: NodeJS.Timeout) => void;\n}\n\n/** Return value from the useCoordinateFieldState hook */\nexport interface UseCoordinateFieldStateResult {\n  /** Current coordinate value (null if incomplete/invalid) */\n  currentValue: CoordinateValue | null;\n  /** Array of display values for each segment */\n  segmentValues: string[];\n  /** Array of validation error messages */\n  validationErrors: string[];\n  /** All segment configurations including literals */\n  segmentConfigs: SegmentConfig[];\n  /** Only editable segment configurations */\n  editableSegmentConfigs: SegmentConfig[];\n  /** Handle change of a single segment */\n  handleSegmentChange: (index: number, newValue: string) => void;\n  /** Set all segment values at once */\n  setSegmentValues: (values: string[]) => void;\n  /** Set validation errors */\n  setValidationErrors: (errors: string[]) => void;\n  /** First validation error or null */\n  effectiveErrorMessage: string | null;\n  /** Apply a pasted coordinate value */\n  applyPastedCoordinate: (pastedValue: CoordinateValue) => void;\n  /** Immediately run pending validation */\n  flushPendingValidation: () => void;\n}\n\n/**\n * Manages coordinate segment values, validation, and format conversion\n *\n * @example\n * ```tsx\n * function CoordinateInputs() {\n *   const [value, setValue] = useState<CoordinateValue | null>(null);\n *   const { registerTimeout } = useTimeoutCleanup();\n *\n *   const {\n *     currentValue,\n *     segmentValues,\n *     validationErrors,\n *     editableSegmentConfigs,\n *     handleSegmentChange,\n *   } = useCoordinateFieldState({\n *     value,\n *     format: 'ddm',\n *     onChange: setValue,\n *     onError: (msg) => console.error(msg),\n *     registerTimeout,\n *   });\n *\n *   return (\n *     <div>\n *       {editableSegmentConfigs.map((config, i) => (\n *         <input\n *           key={i}\n *           value={segmentValues[i]}\n *           onChange={(e) => handleSegmentChange(i, e.target.value)}\n *           placeholder={config.placeholder}\n *         />\n *       ))}\n *       {validationErrors.map((error, i) => (\n *         <span key={i}>{error}</span>\n *       ))}\n *     </div>\n *   );\n * }\n * ```\n *\n * @param options - {@link UseCoordinateFieldStateOptions}\n * @param options.value - Controlled coordinate value.\n * @param options.defaultValue - Default value for uncontrolled mode.\n * @param options.format - Coordinate format system (dd, ddm, dms, mgrs, utm).\n * @param options.onChange - Callback when coordinate value changes.\n * @param options.onError - Callback for validation errors.\n * @param options.registerTimeout - Register timeouts for cleanup on unmount.\n * @returns {@link UseCoordinateFieldStateResult} Segment state, validation, and change handlers.\n */\nexport function useCoordinateFieldState({\n  value,\n  defaultValue,\n  format,\n  onChange,\n  onError,\n  registerTimeout,\n}: UseCoordinateFieldStateOptions): UseCoordinateFieldStateResult {\n  const [internalValue, setInternalValue] = useState<CoordinateValue | null>(\n    defaultValue || null,\n  );\n  const [validationErrors, setValidationErrors] = useState<string[]>([]);\n  const validationTimeoutRef = useRef<NodeJS.Timeout | null>(null);\n\n  const currentValue = value !== undefined ? value : internalValue;\n\n  const clearValidationTimeout = () => {\n    if (validationTimeoutRef.current) {\n      clearTimeout(validationTimeoutRef.current);\n      validationTimeoutRef.current = null;\n    }\n  };\n\n  const handleChange = (newValue: CoordinateValue | null) => {\n    if (value === undefined) {\n      setInternalValue(newValue);\n    }\n    onChange?.(newValue);\n  };\n\n  const segmentConfigs = useMemo(() => getSegmentConfigs(format), [format]);\n\n  const editableSegmentConfigs = useMemo(\n    () => segmentConfigs.flat().filter((config) => config.type !== 'literal'),\n    [segmentConfigs],\n  );\n\n  const [segmentValues, setSegmentValues] = useState<string[]>(() => {\n    const initialValue = value !== undefined ? value : defaultValue;\n    if (!initialValue) {\n      return new Array(editableSegmentConfigs.length).fill('');\n    }\n\n    const segments = convertDDToDisplaySegments(initialValue, format);\n    if (!segments) {\n      return new Array(editableSegmentConfigs.length).fill('');\n    }\n\n    return segments;\n  });\n\n  const convertValueToSegmentsOrClear = useCallback(\n    (valueToConvert: CoordinateValue | null) => {\n      // Clear any pending validation when value changes\n      clearValidationTimeout();\n\n      const segments = valueToConvert\n        ? convertDDToDisplaySegments(valueToConvert, format)\n        : null;\n\n      setSegmentValues(\n        segments || new Array(editableSegmentConfigs.length).fill(''),\n      );\n      setValidationErrors([]);\n    },\n    [format, editableSegmentConfigs.length],\n  );\n\n  const prevFormatRef = useRef(format);\n\n  useEffect(() => {\n    if (prevFormatRef.current !== format) {\n      prevFormatRef.current = format;\n      const valueToConvert = value !== undefined ? value : internalValue;\n      convertValueToSegmentsOrClear(valueToConvert);\n    }\n  }, [format, value, internalValue, convertValueToSegmentsOrClear]);\n\n  useEffect(() => {\n    if (value !== undefined) {\n      convertValueToSegmentsOrClear(value);\n    }\n  }, [value, convertValueToSegmentsOrClear]);\n\n  /**\n   * Validates segment values and updates the coordinate state\n   *\n   * When validation fails, calls onError with \"Invalid coordinate value\" message\n   * and context containing the detailed validation errors from @accelint/geo.\n   *\n   * @param updatedValues - Array of segment values to validate\n   */\n  const validateAndUpdateCoordinate = (updatedValues: string[]) => {\n    const errors = validateCoordinateSegments(updatedValues, format);\n\n    if (errors.length > 0) {\n      setValidationErrors(errors);\n      onError?.('Invalid coordinate value', {\n        errors,\n        format,\n        segments: updatedValues,\n      });\n      handleChange(null);\n      return;\n    }\n\n    const ddValue = convertDisplaySegmentsToDD(updatedValues, format);\n    if (!ddValue) {\n      const errorMsg = 'Invalid coordinate value';\n      setValidationErrors([errorMsg]);\n      onError?.(errorMsg, { format, segments: updatedValues });\n      handleChange(null);\n      return;\n    }\n\n    setValidationErrors([]);\n    handleChange(ddValue);\n  };\n\n  const handleSegmentChange = (index: number, newValue: string) => {\n    const updatedValues = [...segmentValues];\n    updatedValues[index] = newValue;\n    setSegmentValues(updatedValues);\n\n    if (areAllSegmentsFilled(updatedValues)) {\n      // Clear any pending validation timeout\n      clearValidationTimeout();\n\n      // Debounce validation by 400ms when all segments are full\n      const timeoutId = setTimeout(() => {\n        validateAndUpdateCoordinate(updatedValues);\n        validationTimeoutRef.current = null;\n      }, 400);\n\n      validationTimeoutRef.current = timeoutId;\n      registerTimeout?.(timeoutId);\n    } else {\n      // Clear any pending validation when segments become incomplete\n      clearValidationTimeout();\n      setValidationErrors([]);\n      if (currentValue !== null) {\n        handleChange(null);\n      }\n    }\n  };\n\n  const applyPastedCoordinate = (pastedValue: CoordinateValue) => {\n    // Clear any pending validation when applying pasted coordinate\n    clearValidationTimeout();\n\n    const segments = convertDDToDisplaySegments(pastedValue, format);\n\n    if (segments) {\n      setSegmentValues(segments);\n      setValidationErrors([]);\n      handleChange(pastedValue);\n    }\n  };\n\n  const flushPendingValidation = () => {\n    if (validationTimeoutRef.current) {\n      clearValidationTimeout();\n\n      // Immediately validate if all segments are filled\n      if (areAllSegmentsFilled(segmentValues)) {\n        validateAndUpdateCoordinate(segmentValues);\n      }\n    }\n  };\n\n  const effectiveErrorMessage = useMemo(\n    () => validationErrors[0] || null,\n    [validationErrors],\n  );\n\n  return {\n    currentValue,\n    segmentValues,\n    validationErrors,\n    segmentConfigs,\n    editableSegmentConfigs,\n    handleSegmentChange,\n    setSegmentValues,\n    setValidationErrors,\n    effectiveErrorMessage,\n    applyPastedCoordinate,\n    flushPendingValidation,\n  };\n}\n"],"mappings":"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"}

package/dist/hooks/coordinate-field/use-coordinate-field.d.ts

@@ -18,12 +18,19 @@ import { useCoordinatePaste } from "./use-coordinate-paste.js";
 import { ValidationResult } from "react-aria-components";
 
 //#region src/hooks/coordinate-field/use-coordinate-field.d.ts
+/** Return value from the useCoordinateField hook */
 interface UseCoordinateFieldResult {
+  /** Coordinate state management utilities */
   state: ReturnType<typeof useCoordinateFieldState>;
+  /** Focus management utilities */
   focus: ReturnType<typeof useCoordinateFocus>;
+  /** Paste handling utilities */
   paste: ReturnType<typeof useCoordinatePaste>;
+  /** Copy handling utilities */
   copy: ReturnType<typeof useCoordinateCopy>;
+  /** Register timeouts for cleanup */
   registerTimeout: (timeoutId: NodeJS.Timeout) => void;
+  /** ARIA props for the field container */
   fieldProps: {
     id: string;
     role: 'group';
@@ -35,26 +42,80 @@ interface UseCoordinateFieldResult {
     'aria-required': boolean | undefined;
     'aria-disabled': boolean | undefined;
   };
+  /** Props for the label element */
   labelProps: {
     id: string;
     htmlFor: string;
   };
+  /** Props for the description element */
   descriptionProps: {
     id: string;
   };
+  /** Props for the error message element */
   errorProps: {
     id: string;
   };
+  /** Validation result for react-aria */
   validation: ValidationResult;
+  /** Generated element IDs */
   ids: {
     fieldId: string;
     labelId: string;
     descriptionId: string;
     errorId: string;
   };
+  /** First error message or null */
   effectiveErrorMessage: string | null;
+  /** Whether the field is in an invalid state */
   isInvalid: boolean;
 }
+/**
+ * Manages coordinate field state, focus, copy, paste, and accessibility props
+ *
+ * @example
+ * ```tsx
+ * function CoordinateFieldComponent() {
+ *   const [value, setValue] = useState<CoordinateValue | null>(null);
+ *
+ *   const {
+ *     state,
+ *     focus,
+ *     paste,
+ *     copy,
+ *     fieldProps,
+ *     labelProps,
+ *     isInvalid,
+ *     effectiveErrorMessage,
+ *   } = useCoordinateField({
+ *     value,
+ *     onChange: setValue,
+ *     format: 'dd',
+ *     label: 'Location',
+ *   });
+ *
+ *   return (
+ *     <div {...fieldProps}>
+ *       <label {...labelProps}>Location</label>
+ *       {state.editableSegmentConfigs.map((config, index) => (
+ *         <input
+ *           key={index}
+ *           ref={focus.segmentRefs[index]}
+ *           value={state.segmentValues[index]}
+ *           onChange={(e) => state.handleSegmentChange(index, e.target.value)}
+ *         />
+ *       ))}
+ *       {isInvalid && <span>{effectiveErrorMessage}</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - {@link CoordinateFieldProps}
+ * @param customAriaLabel - Custom aria-label for the field.
+ * @param customAriaDescribedby - Custom aria-describedby IDs.
+ * @param customAriaDetails - Custom aria-details ID.
+ * @returns {@link UseCoordinateFieldResult} Combined state, focus, copy, paste utilities and accessibility props.
+ */
 declare function useCoordinateField(props: CoordinateFieldProps, customAriaLabel?: string, customAriaDescribedby?: string, customAriaDetails?: string): UseCoordinateFieldResult;
 //#endregion
 export { UseCoordinateFieldResult, useCoordinateField };

package/dist/hooks/coordinate-field/use-coordinate-field.js

@@ -21,6 +21,53 @@ import { useId } from "@react-aria/utils";
 
 //#region src/hooks/coordinate-field/use-coordinate-field.ts
 const FOCUS_DELAY_MS = 0;
+/**
+* Manages coordinate field state, focus, copy, paste, and accessibility props
+*
+* @example
+* ```tsx
+* function CoordinateFieldComponent() {
+*   const [value, setValue] = useState<CoordinateValue | null>(null);
+*
+*   const {
+*     state,
+*     focus,
+*     paste,
+*     copy,
+*     fieldProps,
+*     labelProps,
+*     isInvalid,
+*     effectiveErrorMessage,
+*   } = useCoordinateField({
+*     value,
+*     onChange: setValue,
+*     format: 'dd',
+*     label: 'Location',
+*   });
+*
+*   return (
+*     <div {...fieldProps}>
+*       <label {...labelProps}>Location</label>
+*       {state.editableSegmentConfigs.map((config, index) => (
+*         <input
+*           key={index}
+*           ref={focus.segmentRefs[index]}
+*           value={state.segmentValues[index]}
+*           onChange={(e) => state.handleSegmentChange(index, e.target.value)}
+*         />
+*       ))}
+*       {isInvalid && <span>{effectiveErrorMessage}</span>}
+*     </div>
+*   );
+* }
+* ```
+*
+* @param props - {@link CoordinateFieldProps}
+* @param customAriaLabel - Custom aria-label for the field.
+* @param customAriaDescribedby - Custom aria-describedby IDs.
+* @param customAriaDetails - Custom aria-details ID.
+* @returns {@link UseCoordinateFieldResult} Combined state, focus, copy, paste utilities and accessibility props.
+*/
 function useCoordinateField(props, customAriaLabel, customAriaDescribedby, customAriaDetails) {
 	const { description, errorMessage: errorMessageProp, format = "dd", value, defaultValue, onChange, onError, isDisabled = false, isInvalid: isInvalidProp = false, isRequired = false, id: idProp } = props;
 	const fieldId = useId(idProp);

package/dist/hooks/coordinate-field/use-coordinate-field.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-coordinate-field.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-field.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { useId } from '@react-aria/utils';\nimport { useMemo } from 'react';\nimport { useCoordinateCopy } from './use-coordinate-copy';\nimport { useCoordinateFieldState } from './use-coordinate-field-state';\nimport { useCoordinateFocus } from './use-coordinate-focus';\nimport { useCoordinatePaste } from './use-coordinate-paste';\nimport { useTimeoutCleanup } from './use-timeout-cleanup';\nimport type { ValidationResult } from 'react-aria-components';\nimport type {\n  CoordinateFieldProps,\n  CoordinateSystem,\n  CoordinateValue,\n} from '../../components/coordinate-field/types';\n\nconst FOCUS_DELAY_MS = 0;\n\nexport interface UseCoordinateFieldResult {\n  state: ReturnType<typeof useCoordinateFieldState>;\n  focus: ReturnType<typeof useCoordinateFocus>;\n  paste: ReturnType<typeof useCoordinatePaste>;\n  copy: ReturnType<typeof useCoordinateCopy>;\n  registerTimeout: (timeoutId: NodeJS.Timeout) => void;\n  fieldProps: {\n    id: string;\n    role: 'group';\n    'aria-labelledby': string | undefined;\n    'aria-describedby': string | undefined;\n    'aria-label': string | undefined;\n    'aria-details': string | undefined;\n    'aria-invalid': boolean | undefined;\n    'aria-required': boolean | undefined;\n    'aria-disabled': boolean | undefined;\n  };\n  labelProps: {\n    id: string;\n    htmlFor: string;\n  };\n  descriptionProps: {\n    id: string;\n  };\n  errorProps: {\n    id: string;\n  };\n  validation: ValidationResult;\n  ids: {\n    fieldId: string;\n    labelId: string;\n    descriptionId: string;\n    errorId: string;\n  };\n  effectiveErrorMessage: string | null;\n  isInvalid: boolean;\n}\n\nexport function useCoordinateField(\n  props: CoordinateFieldProps,\n  customAriaLabel?: string,\n  customAriaDescribedby?: string,\n  customAriaDetails?: string,\n): UseCoordinateFieldResult {\n  const {\n    description,\n    errorMessage: errorMessageProp,\n    format = 'dd' as CoordinateSystem,\n    value,\n    defaultValue,\n    onChange,\n    onError,\n    isDisabled = false,\n    isInvalid: isInvalidProp = false,\n    isRequired = false,\n    id: idProp,\n  } = props;\n\n  const fieldId = useId(idProp);\n  const labelId = useId();\n  const descriptionId = useId();\n  const errorId = useId();\n\n  const { registerTimeout } = useTimeoutCleanup();\n\n  const state = useCoordinateFieldState({\n    value,\n    defaultValue,\n    format,\n    onChange,\n    onError,\n    registerTimeout,\n  });\n\n  const focus = useCoordinateFocus({\n    editableSegmentConfigs: state.editableSegmentConfigs,\n  });\n\n  const handlePasteValueApplied = (pastedValue: CoordinateValue) => {\n    state.applyPastedCoordinate(pastedValue);\n\n    // Defer focus until after React commits state updates to the DOM.\n    // applyPastedCoordinate triggers setSegmentValues which updates the input\n    // elements, and we need those updates to complete before focusing.\n    registerTimeout(\n      setTimeout(() => {\n        focus.focusFirstSegment();\n      }, FOCUS_DELAY_MS),\n    );\n  };\n\n  const paste = useCoordinatePaste({\n    onValueApplied: handlePasteValueApplied,\n    onError,\n  });\n\n  const copy = useCoordinateCopy({\n    currentValue: state.currentValue,\n    validationErrors: state.validationErrors,\n    isDisabled,\n    registerTimeout,\n  });\n\n  const effectiveErrorMessage = useMemo(\n    () => errorMessageProp || state.effectiveErrorMessage,\n    [errorMessageProp, state.effectiveErrorMessage],\n  );\n\n  const isInvalid = isInvalidProp || effectiveErrorMessage !== null;\n\n  const describedByIds = [\n    description && descriptionId,\n    effectiveErrorMessage && errorId,\n    customAriaDescribedby,\n  ].filter(Boolean);\n  const describedBy =\n    describedByIds.length > 0 ? describedByIds.join(' ') : undefined;\n\n  const labelProps = {\n    id: labelId,\n    htmlFor: fieldId,\n  };\n\n  // Only use aria-labelledby when we have a visible label (not using aria-label)\n  // When aria-label is provided (e.g., in small size), it takes precedence\n  const ariaLabelledBy = customAriaLabel ? undefined : labelId;\n\n  const fieldProps = {\n    id: fieldId,\n    role: 'group' as const,\n    'aria-labelledby': ariaLabelledBy,\n    'aria-describedby': describedBy,\n    'aria-label': customAriaLabel || undefined,\n    'aria-details': customAriaDetails || undefined,\n    'aria-invalid': isInvalid || undefined,\n    'aria-required': isRequired || undefined,\n    'aria-disabled': isDisabled || undefined,\n  };\n\n  const descriptionProps = {\n    id: descriptionId,\n  };\n\n  const errorProps = {\n    id: errorId,\n  };\n\n  const validation: ValidationResult = useMemo(\n    () => ({\n      isInvalid,\n      validationErrors: effectiveErrorMessage ? [effectiveErrorMessage] : [],\n      validationDetails: {} as ValidityState,\n    }),\n    [isInvalid, effectiveErrorMessage],\n  );\n\n  return {\n    state,\n    focus,\n    paste,\n    copy,\n    registerTimeout,\n    fieldProps,\n    labelProps,\n    descriptionProps,\n    errorProps,\n    validation,\n    ids: {\n      fieldId,\n      labelId,\n      descriptionId,\n      errorId,\n    },\n    effectiveErrorMessage,\n    isInvalid,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAM,iBAAiB;AAwCvB,SAAgB,mBACd,OACA,iBACA,uBACA,mBAC0B;CAC1B,MAAM,EACJ,aACA,cAAc,kBACd,SAAS,MACT,OACA,cACA,UACA,SACA,aAAa,OACb,WAAW,gBAAgB,OAC3B,aAAa,OACb,IAAI,WACF;CAEJ,MAAM,UAAU,MAAM,OAAO;CAC7B,MAAM,UAAU,OAAO;CACvB,MAAM,gBAAgB,OAAO;CAC7B,MAAM,UAAU,OAAO;CAEvB,MAAM,EAAE,oBAAoB,mBAAmB;CAE/C,MAAM,QAAQ,wBAAwB;EACpC;EACA;EACA;EACA;EACA;EACA;EACD,CAAC;CAEF,MAAM,QAAQ,mBAAmB,EAC/B,wBAAwB,MAAM,wBAC/B,CAAC;CAEF,MAAM,2BAA2B,gBAAiC;AAChE,QAAM,sBAAsB,YAAY;AAKxC,kBACE,iBAAiB;AACf,SAAM,mBAAmB;KACxB,eAAe,CACnB;;CAGH,MAAM,QAAQ,mBAAmB;EAC/B,gBAAgB;EAChB;EACD,CAAC;CAEF,MAAM,OAAO,kBAAkB;EAC7B,cAAc,MAAM;EACpB,kBAAkB,MAAM;EACxB;EACA;EACD,CAAC;CAEF,MAAM,wBAAwB,cACtB,oBAAoB,MAAM,uBAChC,CAAC,kBAAkB,MAAM,sBAAsB,CAChD;CAED,MAAM,YAAY,iBAAiB,0BAA0B;CAE7D,MAAM,iBAAiB;EACrB,eAAe;EACf,yBAAyB;EACzB;EACD,CAAC,OAAO,QAAQ;CACjB,MAAM,cACJ,eAAe,SAAS,IAAI,eAAe,KAAK,IAAI,GAAG;CAEzD,MAAM,aAAa;EACjB,IAAI;EACJ,SAAS;EACV;CAID,MAAM,iBAAiB,kBAAkB,SAAY;AA+BrD,QAAO;EACL;EACA;EACA;EACA;EACA;EACA,YAnCiB;GACjB,IAAI;GACJ,MAAM;GACN,mBAAmB;GACnB,oBAAoB;GACpB,cAAc,mBAAmB;GACjC,gBAAgB,qBAAqB;GACrC,gBAAgB,aAAa;GAC7B,iBAAiB,cAAc;GAC/B,iBAAiB,cAAc;GAChC;EA0BC;EACA,kBAzBuB,EACvB,IAAI,eACL;EAwBC,YAtBiB,EACjB,IAAI,SACL;EAqBC,YAnBmC,eAC5B;GACL;GACA,kBAAkB,wBAAwB,CAAC,sBAAsB,GAAG,EAAE;GACtE,mBAAmB,EAAE;GACtB,GACD,CAAC,WAAW,sBAAsB,CACnC;EAaC,KAAK;GACH;GACA;GACA;GACA;GACD;EACD;EACA;EACD"}
+{"version":3,"file":"use-coordinate-field.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-field.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { useId } from '@react-aria/utils';\nimport { useMemo } from 'react';\nimport { useCoordinateCopy } from './use-coordinate-copy';\nimport { useCoordinateFieldState } from './use-coordinate-field-state';\nimport { useCoordinateFocus } from './use-coordinate-focus';\nimport { useCoordinatePaste } from './use-coordinate-paste';\nimport { useTimeoutCleanup } from './use-timeout-cleanup';\nimport type { ValidationResult } from 'react-aria-components';\nimport type {\n  CoordinateFieldProps,\n  CoordinateSystem,\n  CoordinateValue,\n} from '../../components/coordinate-field/types';\n\nconst FOCUS_DELAY_MS = 0;\n\n/** Return value from the useCoordinateField hook */\nexport interface UseCoordinateFieldResult {\n  /** Coordinate state management utilities */\n  state: ReturnType<typeof useCoordinateFieldState>;\n  /** Focus management utilities */\n  focus: ReturnType<typeof useCoordinateFocus>;\n  /** Paste handling utilities */\n  paste: ReturnType<typeof useCoordinatePaste>;\n  /** Copy handling utilities */\n  copy: ReturnType<typeof useCoordinateCopy>;\n  /** Register timeouts for cleanup */\n  registerTimeout: (timeoutId: NodeJS.Timeout) => void;\n  /** ARIA props for the field container */\n  fieldProps: {\n    id: string;\n    role: 'group';\n    'aria-labelledby': string | undefined;\n    'aria-describedby': string | undefined;\n    'aria-label': string | undefined;\n    'aria-details': string | undefined;\n    'aria-invalid': boolean | undefined;\n    'aria-required': boolean | undefined;\n    'aria-disabled': boolean | undefined;\n  };\n  /** Props for the label element */\n  labelProps: {\n    id: string;\n    htmlFor: string;\n  };\n  /** Props for the description element */\n  descriptionProps: {\n    id: string;\n  };\n  /** Props for the error message element */\n  errorProps: {\n    id: string;\n  };\n  /** Validation result for react-aria */\n  validation: ValidationResult;\n  /** Generated element IDs */\n  ids: {\n    fieldId: string;\n    labelId: string;\n    descriptionId: string;\n    errorId: string;\n  };\n  /** First error message or null */\n  effectiveErrorMessage: string | null;\n  /** Whether the field is in an invalid state */\n  isInvalid: boolean;\n}\n\n/**\n * Manages coordinate field state, focus, copy, paste, and accessibility props\n *\n * @example\n * ```tsx\n * function CoordinateFieldComponent() {\n *   const [value, setValue] = useState<CoordinateValue | null>(null);\n *\n *   const {\n *     state,\n *     focus,\n *     paste,\n *     copy,\n *     fieldProps,\n *     labelProps,\n *     isInvalid,\n *     effectiveErrorMessage,\n *   } = useCoordinateField({\n *     value,\n *     onChange: setValue,\n *     format: 'dd',\n *     label: 'Location',\n *   });\n *\n *   return (\n *     <div {...fieldProps}>\n *       <label {...labelProps}>Location</label>\n *       {state.editableSegmentConfigs.map((config, index) => (\n *         <input\n *           key={index}\n *           ref={focus.segmentRefs[index]}\n *           value={state.segmentValues[index]}\n *           onChange={(e) => state.handleSegmentChange(index, e.target.value)}\n *         />\n *       ))}\n *       {isInvalid && <span>{effectiveErrorMessage}</span>}\n *     </div>\n *   );\n * }\n * ```\n *\n * @param props - {@link CoordinateFieldProps}\n * @param customAriaLabel - Custom aria-label for the field.\n * @param customAriaDescribedby - Custom aria-describedby IDs.\n * @param customAriaDetails - Custom aria-details ID.\n * @returns {@link UseCoordinateFieldResult} Combined state, focus, copy, paste utilities and accessibility props.\n */\nexport function useCoordinateField(\n  props: CoordinateFieldProps,\n  customAriaLabel?: string,\n  customAriaDescribedby?: string,\n  customAriaDetails?: string,\n): UseCoordinateFieldResult {\n  const {\n    description,\n    errorMessage: errorMessageProp,\n    format = 'dd' as CoordinateSystem,\n    value,\n    defaultValue,\n    onChange,\n    onError,\n    isDisabled = false,\n    isInvalid: isInvalidProp = false,\n    isRequired = false,\n    id: idProp,\n  } = props;\n\n  const fieldId = useId(idProp);\n  const labelId = useId();\n  const descriptionId = useId();\n  const errorId = useId();\n\n  const { registerTimeout } = useTimeoutCleanup();\n\n  const state = useCoordinateFieldState({\n    value,\n    defaultValue,\n    format,\n    onChange,\n    onError,\n    registerTimeout,\n  });\n\n  const focus = useCoordinateFocus({\n    editableSegmentConfigs: state.editableSegmentConfigs,\n  });\n\n  const handlePasteValueApplied = (pastedValue: CoordinateValue) => {\n    state.applyPastedCoordinate(pastedValue);\n\n    // Defer focus until after React commits state updates to the DOM.\n    // applyPastedCoordinate triggers setSegmentValues which updates the input\n    // elements, and we need those updates to complete before focusing.\n    registerTimeout(\n      setTimeout(() => {\n        focus.focusFirstSegment();\n      }, FOCUS_DELAY_MS),\n    );\n  };\n\n  const paste = useCoordinatePaste({\n    onValueApplied: handlePasteValueApplied,\n    onError,\n  });\n\n  const copy = useCoordinateCopy({\n    currentValue: state.currentValue,\n    validationErrors: state.validationErrors,\n    isDisabled,\n    registerTimeout,\n  });\n\n  const effectiveErrorMessage = useMemo(\n    () => errorMessageProp || state.effectiveErrorMessage,\n    [errorMessageProp, state.effectiveErrorMessage],\n  );\n\n  const isInvalid = isInvalidProp || effectiveErrorMessage !== null;\n\n  const describedByIds = [\n    description && descriptionId,\n    effectiveErrorMessage && errorId,\n    customAriaDescribedby,\n  ].filter(Boolean);\n  const describedBy =\n    describedByIds.length > 0 ? describedByIds.join(' ') : undefined;\n\n  const labelProps = {\n    id: labelId,\n    htmlFor: fieldId,\n  };\n\n  // Only use aria-labelledby when we have a visible label (not using aria-label)\n  // When aria-label is provided (e.g., in small size), it takes precedence\n  const ariaLabelledBy = customAriaLabel ? undefined : labelId;\n\n  const fieldProps = {\n    id: fieldId,\n    role: 'group' as const,\n    'aria-labelledby': ariaLabelledBy,\n    'aria-describedby': describedBy,\n    'aria-label': customAriaLabel || undefined,\n    'aria-details': customAriaDetails || undefined,\n    'aria-invalid': isInvalid || undefined,\n    'aria-required': isRequired || undefined,\n    'aria-disabled': isDisabled || undefined,\n  };\n\n  const descriptionProps = {\n    id: descriptionId,\n  };\n\n  const errorProps = {\n    id: errorId,\n  };\n\n  const validation: ValidationResult = useMemo(\n    () => ({\n      isInvalid,\n      validationErrors: effectiveErrorMessage ? [effectiveErrorMessage] : [],\n      validationDetails: {} as ValidityState,\n    }),\n    [isInvalid, effectiveErrorMessage],\n  );\n\n  return {\n    state,\n    focus,\n    paste,\n    copy,\n    registerTimeout,\n    fieldProps,\n    labelProps,\n    descriptionProps,\n    errorProps,\n    validation,\n    ids: {\n      fieldId,\n      labelId,\n      descriptionId,\n      errorId,\n    },\n    effectiveErrorMessage,\n    isInvalid,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqGvB,SAAgB,mBACd,OACA,iBACA,uBACA,mBAC0B;CAC1B,MAAM,EACJ,aACA,cAAc,kBACd,SAAS,MACT,OACA,cACA,UACA,SACA,aAAa,OACb,WAAW,gBAAgB,OAC3B,aAAa,OACb,IAAI,WACF;CAEJ,MAAM,UAAU,MAAM,OAAO;CAC7B,MAAM,UAAU,OAAO;CACvB,MAAM,gBAAgB,OAAO;CAC7B,MAAM,UAAU,OAAO;CAEvB,MAAM,EAAE,oBAAoB,mBAAmB;CAE/C,MAAM,QAAQ,wBAAwB;EACpC;EACA;EACA;EACA;EACA;EACA;EACD,CAAC;CAEF,MAAM,QAAQ,mBAAmB,EAC/B,wBAAwB,MAAM,wBAC/B,CAAC;CAEF,MAAM,2BAA2B,gBAAiC;AAChE,QAAM,sBAAsB,YAAY;AAKxC,kBACE,iBAAiB;AACf,SAAM,mBAAmB;KACxB,eAAe,CACnB;;CAGH,MAAM,QAAQ,mBAAmB;EAC/B,gBAAgB;EAChB;EACD,CAAC;CAEF,MAAM,OAAO,kBAAkB;EAC7B,cAAc,MAAM;EACpB,kBAAkB,MAAM;EACxB;EACA;EACD,CAAC;CAEF,MAAM,wBAAwB,cACtB,oBAAoB,MAAM,uBAChC,CAAC,kBAAkB,MAAM,sBAAsB,CAChD;CAED,MAAM,YAAY,iBAAiB,0BAA0B;CAE7D,MAAM,iBAAiB;EACrB,eAAe;EACf,yBAAyB;EACzB;EACD,CAAC,OAAO,QAAQ;CACjB,MAAM,cACJ,eAAe,SAAS,IAAI,eAAe,KAAK,IAAI,GAAG;CAEzD,MAAM,aAAa;EACjB,IAAI;EACJ,SAAS;EACV;CAID,MAAM,iBAAiB,kBAAkB,SAAY;AA+BrD,QAAO;EACL;EACA;EACA;EACA;EACA;EACA,YAnCiB;GACjB,IAAI;GACJ,MAAM;GACN,mBAAmB;GACnB,oBAAoB;GACpB,cAAc,mBAAmB;GACjC,gBAAgB,qBAAqB;GACrC,gBAAgB,aAAa;GAC7B,iBAAiB,cAAc;GAC/B,iBAAiB,cAAc;GAChC;EA0BC;EACA,kBAzBuB,EACvB,IAAI,eACL;EAwBC,YAtBiB,EACjB,IAAI,SACL;EAqBC,YAnBmC,eAC5B;GACL;GACA,kBAAkB,wBAAwB,CAAC,sBAAsB,GAAG,EAAE;GACtE,mBAAmB,EAAE;GACtB,GACD,CAAC,WAAW,sBAAsB,CACnC;EAaC,KAAK;GACH;GACA;GACA;GACA;GACD;EACD;EACA;EACD"}

package/dist/hooks/coordinate-field/use-coordinate-focus.d.ts

@@ -14,20 +14,71 @@ 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;

package/dist/hooks/coordinate-field/use-coordinate-focus.js

@@ -14,6 +14,45 @@
 import { createRef, useEffect, useRef, useState } from "react";
 
 //#region src/hooks/coordinate-field/use-coordinate-focus.ts
+/**
+* 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.
+*/
 function useCoordinateFocus({ editableSegmentConfigs }) {
 	const segmentRefsInternal = useRef([]);
 	const [focusedSegmentIndex, setFocusedSegmentIndex] = useState(-1);

package/dist/hooks/coordinate-field/use-coordinate-focus.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-coordinate-focus.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-focus.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport {\n  createRef,\n  type KeyboardEvent,\n  useEffect,\n  useRef,\n  useState,\n} from 'react';\nimport type { SegmentConfig } from '../../components/coordinate-field/types';\n\nexport interface UseCoordinateFocusOptions {\n  editableSegmentConfigs: SegmentConfig[];\n}\n\nexport interface UseCoordinateFocusResult {\n  segmentRefs: React.RefObject<HTMLInputElement>[];\n  focusedSegmentIndex: number;\n  focusSegment: (index: number) => void;\n  focusNextSegment: (currentIndex: number) => void;\n  focusPreviousSegment: (currentIndex: number) => void;\n  focusFirstSegment: () => void;\n  focusLastSegment: () => void;\n  handleSegmentKeyDown: (\n    index: number,\n    e: KeyboardEvent<HTMLInputElement>,\n  ) => void;\n  setFocusedSegmentIndex: (index: number) => void;\n}\n\nexport function useCoordinateFocus({\n  editableSegmentConfigs,\n}: UseCoordinateFocusOptions): UseCoordinateFocusResult {\n  const segmentRefsInternal = useRef<React.RefObject<HTMLInputElement>[]>([]);\n  const [focusedSegmentIndex, setFocusedSegmentIndex] = useState<number>(-1);\n\n  useEffect(() => {\n    segmentRefsInternal.current = editableSegmentConfigs.map((_, i) => {\n      const existingRef = segmentRefsInternal.current[i];\n      if (existingRef) {\n        return existingRef;\n      }\n      return createRef<HTMLInputElement>() as React.RefObject<HTMLInputElement>;\n    });\n  }, [editableSegmentConfigs]);\n\n  const focusSegment = (index: number) => {\n    if (index >= 0 && index < segmentRefsInternal.current.length) {\n      segmentRefsInternal.current[index]?.current?.focus();\n    }\n  };\n\n  const focusNextSegment = (currentIndex: number) => {\n    focusSegment(currentIndex + 1);\n  };\n\n  const focusPreviousSegment = (currentIndex: number) => {\n    focusSegment(currentIndex - 1);\n  };\n\n  const focusFirstSegment = () => {\n    focusSegment(0);\n  };\n\n  const focusLastSegment = () => {\n    focusSegment(segmentRefsInternal.current.length - 1);\n  };\n\n  const handleSegmentKeyDown = (\n    _index: number,\n    e: KeyboardEvent<HTMLInputElement>,\n  ) => {\n    if (e.key === 'Home') {\n      e.preventDefault();\n      focusFirstSegment();\n    } else if (e.key === 'End') {\n      e.preventDefault();\n      focusLastSegment();\n    }\n  };\n\n  return {\n    segmentRefs: segmentRefsInternal.current,\n    focusedSegmentIndex,\n    focusSegment,\n    focusNextSegment,\n    focusPreviousSegment,\n    focusFirstSegment,\n    focusLastSegment,\n    handleSegmentKeyDown,\n    setFocusedSegmentIndex,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAwCA,SAAgB,mBAAmB,EACjC,0BACsD;CACtD,MAAM,sBAAsB,OAA4C,EAAE,CAAC;CAC3E,MAAM,CAAC,qBAAqB,0BAA0B,SAAiB,GAAG;AAE1E,iBAAgB;AACd,sBAAoB,UAAU,uBAAuB,KAAK,GAAG,MAAM;GACjE,MAAM,cAAc,oBAAoB,QAAQ;AAChD,OAAI,YACF,QAAO;AAET,UAAO,WAA6B;IACpC;IACD,CAAC,uBAAuB,CAAC;CAE5B,MAAM,gBAAgB,UAAkB;AACtC,MAAI,SAAS,KAAK,QAAQ,oBAAoB,QAAQ,OACpD,qBAAoB,QAAQ,QAAQ,SAAS,OAAO;;CAIxD,MAAM,oBAAoB,iBAAyB;AACjD,eAAa,eAAe,EAAE;;CAGhC,MAAM,wBAAwB,iBAAyB;AACrD,eAAa,eAAe,EAAE;;CAGhC,MAAM,0BAA0B;AAC9B,eAAa,EAAE;;CAGjB,MAAM,yBAAyB;AAC7B,eAAa,oBAAoB,QAAQ,SAAS,EAAE;;CAGtD,MAAM,wBACJ,QACA,MACG;AACH,MAAI,EAAE,QAAQ,QAAQ;AACpB,KAAE,gBAAgB;AAClB,sBAAmB;aACV,EAAE,QAAQ,OAAO;AAC1B,KAAE,gBAAgB;AAClB,qBAAkB;;;AAItB,QAAO;EACL,aAAa,oBAAoB;EACjC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}
+{"version":3,"file":"use-coordinate-focus.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-focus.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport {\n  createRef,\n  type KeyboardEvent,\n  useEffect,\n  useRef,\n  useState,\n} from 'react';\nimport type { SegmentConfig } from '../../components/coordinate-field/types';\n\n/** Options for the useCoordinateFocus hook */\nexport interface UseCoordinateFocusOptions {\n  /** Array of editable segment configurations */\n  editableSegmentConfigs: SegmentConfig[];\n}\n\n/** Return value from the useCoordinateFocus hook */\nexport interface UseCoordinateFocusResult {\n  /** Array of refs for each input segment */\n  segmentRefs: React.RefObject<HTMLInputElement>[];\n  /** Index of the currently focused segment (-1 if none) */\n  focusedSegmentIndex: number;\n  /** Focus a specific segment by index */\n  focusSegment: (index: number) => void;\n  /** Focus the next segment after the current index */\n  focusNextSegment: (currentIndex: number) => void;\n  /** Focus the previous segment before the current index */\n  focusPreviousSegment: (currentIndex: number) => void;\n  /** Focus the first segment */\n  focusFirstSegment: () => void;\n  /** Focus the last segment */\n  focusLastSegment: () => void;\n  /** Handle keyboard navigation (Home/End keys) */\n  handleSegmentKeyDown: (\n    index: number,\n    e: KeyboardEvent<HTMLInputElement>,\n  ) => void;\n  /** Update the focused segment index state */\n  setFocusedSegmentIndex: (index: number) => void;\n}\n\n/**\n * Manages focus navigation between coordinate input segments\n *\n * @example\n * ```tsx\n * function CoordinateSegments({ configs }: { configs: SegmentConfig[] }) {\n *   const {\n *     segmentRefs,\n *     focusedSegmentIndex,\n *     focusNextSegment,\n *     focusPreviousSegment,\n *     handleSegmentKeyDown,\n *     setFocusedSegmentIndex,\n *   } = useCoordinateFocus({ editableSegmentConfigs: configs });\n *\n *   return (\n *     <div>\n *       {configs.map((config, i) => (\n *         <input\n *           key={i}\n *           ref={segmentRefs[i]}\n *           onFocus={() => setFocusedSegmentIndex(i)}\n *           onKeyDown={(e) => {\n *             handleSegmentKeyDown(i, e);\n *             if (e.key === 'ArrowRight') focusNextSegment(i);\n *             if (e.key === 'ArrowLeft') focusPreviousSegment(i);\n *           }}\n *           aria-current={focusedSegmentIndex === i || undefined}\n *         />\n *       ))}\n *     </div>\n *   );\n * }\n * ```\n *\n * @param options - {@link UseCoordinateFocusOptions}\n * @param options.editableSegmentConfigs - Array of editable segment configurations.\n * @returns {@link UseCoordinateFocusResult} Focus management utilities and state.\n */\nexport function useCoordinateFocus({\n  editableSegmentConfigs,\n}: UseCoordinateFocusOptions): UseCoordinateFocusResult {\n  const segmentRefsInternal = useRef<React.RefObject<HTMLInputElement>[]>([]);\n  const [focusedSegmentIndex, setFocusedSegmentIndex] = useState<number>(-1);\n\n  useEffect(() => {\n    segmentRefsInternal.current = editableSegmentConfigs.map((_, i) => {\n      const existingRef = segmentRefsInternal.current[i];\n      if (existingRef) {\n        return existingRef;\n      }\n      return createRef<HTMLInputElement>() as React.RefObject<HTMLInputElement>;\n    });\n  }, [editableSegmentConfigs]);\n\n  const focusSegment = (index: number) => {\n    if (index >= 0 && index < segmentRefsInternal.current.length) {\n      segmentRefsInternal.current[index]?.current?.focus();\n    }\n  };\n\n  const focusNextSegment = (currentIndex: number) => {\n    focusSegment(currentIndex + 1);\n  };\n\n  const focusPreviousSegment = (currentIndex: number) => {\n    focusSegment(currentIndex - 1);\n  };\n\n  const focusFirstSegment = () => {\n    focusSegment(0);\n  };\n\n  const focusLastSegment = () => {\n    focusSegment(segmentRefsInternal.current.length - 1);\n  };\n\n  const handleSegmentKeyDown = (\n    _index: number,\n    e: KeyboardEvent<HTMLInputElement>,\n  ) => {\n    if (e.key === 'Home') {\n      e.preventDefault();\n      focusFirstSegment();\n    } else if (e.key === 'End') {\n      e.preventDefault();\n      focusLastSegment();\n    }\n  };\n\n  return {\n    segmentRefs: segmentRefsInternal.current,\n    focusedSegmentIndex,\n    focusSegment,\n    focusNextSegment,\n    focusPreviousSegment,\n    focusFirstSegment,\n    focusLastSegment,\n    handleSegmentKeyDown,\n    setFocusedSegmentIndex,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2FA,SAAgB,mBAAmB,EACjC,0BACsD;CACtD,MAAM,sBAAsB,OAA4C,EAAE,CAAC;CAC3E,MAAM,CAAC,qBAAqB,0BAA0B,SAAiB,GAAG;AAE1E,iBAAgB;AACd,sBAAoB,UAAU,uBAAuB,KAAK,GAAG,MAAM;GACjE,MAAM,cAAc,oBAAoB,QAAQ;AAChD,OAAI,YACF,QAAO;AAET,UAAO,WAA6B;IACpC;IACD,CAAC,uBAAuB,CAAC;CAE5B,MAAM,gBAAgB,UAAkB;AACtC,MAAI,SAAS,KAAK,QAAQ,oBAAoB,QAAQ,OACpD,qBAAoB,QAAQ,QAAQ,SAAS,OAAO;;CAIxD,MAAM,oBAAoB,iBAAyB;AACjD,eAAa,eAAe,EAAE;;CAGhC,MAAM,wBAAwB,iBAAyB;AACrD,eAAa,eAAe,EAAE;;CAGhC,MAAM,0BAA0B;AAC9B,eAAa,EAAE;;CAGjB,MAAM,yBAAyB;AAC7B,eAAa,oBAAoB,QAAQ,SAAS,EAAE;;CAGtD,MAAM,wBACJ,QACA,MACG;AACH,MAAI,EAAE,QAAQ,QAAQ;AACpB,KAAE,gBAAgB;AAClB,sBAAmB;aACV,EAAE,QAAQ,OAAO;AAC1B,KAAE,gBAAgB;AAClB,qBAAkB;;;AAItB,QAAO;EACL,aAAa,oBAAoB;EACjC;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}

package/dist/hooks/coordinate-field/use-coordinate-paste.d.ts

@@ -13,20 +13,83 @@
 import { CoordinateSystem, CoordinateValue, ParsedCoordinateMatch } from "../../components/coordinate-field/types.js";
 
 //#region src/hooks/coordinate-field/use-coordinate-paste.d.ts
+/** Options for the useCoordinatePaste hook */
 interface UseCoordinatePasteOptions {
+  /** Callback when a coordinate value is successfully parsed and applied */
   onValueApplied: (value: CoordinateValue) => void;
+  /** Optional error callback for invalid paste attempts */
   onError?: (message: string, context?: Record<string, unknown>) => void;
 }
+/** Return value from the useCoordinatePaste hook */
 interface UseCoordinatePasteResult {
+  /** Array of parsed coordinate matches for disambiguation */
   disambiguationMatches: ParsedCoordinateMatch[];
+  /** Whether the disambiguation modal is visible */
   showDisambiguationModal: boolean;
+  /** Currently selected format in disambiguation modal */
   selectedDisambiguationFormat: CoordinateSystem | null;
+  /** Paste event handler for coordinate input */
   handleInputPaste: (e: React.ClipboardEvent<HTMLDivElement>) => void;
+  /** Confirm selection in disambiguation modal */
   handleDisambiguationSelect: () => void;
+  /** Control disambiguation modal visibility */
   setShowDisambiguationModal: (show: boolean) => void;
+  /** Set the selected format in disambiguation modal */
   setSelectedDisambiguationFormat: (format: CoordinateSystem | null) => void;
+  /** Reset disambiguation modal state */
   cleanupDisambiguationModal: () => void;
 }
+/**
+ * Handles paste events with coordinate parsing and disambiguation when multiple formats match
+ *
+ * @example
+ * ```tsx
+ * function CoordinateFieldWithPaste() {
+ *   const [value, setValue] = useState<CoordinateValue | null>(null);
+ *
+ *   const {
+ *     disambiguationMatches,
+ *     showDisambiguationModal,
+ *     selectedDisambiguationFormat,
+ *     handleInputPaste,
+ *     handleDisambiguationSelect,
+ *     setShowDisambiguationModal,
+ *     setSelectedDisambiguationFormat,
+ *   } = useCoordinatePaste({
+ *     onValueApplied: setValue,
+ *     onError: (msg) => console.error(msg),
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <div onPaste={handleInputPaste}>
+ *         // ...Coordinate input segments
+ *       </div>
+ *       {showDisambiguationModal && (
+ *         <Dialog onClose={() => setShowDisambiguationModal(false)}>
+ *           {disambiguationMatches.map((match) => (
+ *             <Radio
+ *               key={match.format}
+ *               value={match.format}
+ *               isSelected={selectedDisambiguationFormat === match.format}
+ *               onChange={() => setSelectedDisambiguationFormat(match.format)}
+ *             >
+ *               {match.format}: {match.matched}
+ *             </Radio>
+ *           ))}
+ *           <Button onPress={handleDisambiguationSelect}>Confirm</Button>
+ *         </Dialog>
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - {@link UseCoordinatePasteOptions}
+ * @param options.onValueApplied - Callback when a coordinate value is successfully parsed and applied.
+ * @param options.onError - Optional error callback for invalid paste attempts.
+ * @returns {@link UseCoordinatePasteResult} Paste handling utilities and disambiguation state.
+ */
 declare function useCoordinatePaste({
   onValueApplied,
   onError

package/dist/hooks/coordinate-field/use-coordinate-paste.js

@@ -15,6 +15,57 @@ import { deduplicateMatchesByLocation, isCompleteCoordinate, parseCoordinatePast
 import { useState } from "react";
 
 //#region src/hooks/coordinate-field/use-coordinate-paste.ts
+/**
+* Handles paste events with coordinate parsing and disambiguation when multiple formats match
+*
+* @example
+* ```tsx
+* function CoordinateFieldWithPaste() {
+*   const [value, setValue] = useState<CoordinateValue | null>(null);
+*
+*   const {
+*     disambiguationMatches,
+*     showDisambiguationModal,
+*     selectedDisambiguationFormat,
+*     handleInputPaste,
+*     handleDisambiguationSelect,
+*     setShowDisambiguationModal,
+*     setSelectedDisambiguationFormat,
+*   } = useCoordinatePaste({
+*     onValueApplied: setValue,
+*     onError: (msg) => console.error(msg),
+*   });
+*
+*   return (
+*     <>
+*       <div onPaste={handleInputPaste}>
+*         // ...Coordinate input segments
+*       </div>
+*       {showDisambiguationModal && (
+*         <Dialog onClose={() => setShowDisambiguationModal(false)}>
+*           {disambiguationMatches.map((match) => (
+*             <Radio
+*               key={match.format}
+*               value={match.format}
+*               isSelected={selectedDisambiguationFormat === match.format}
+*               onChange={() => setSelectedDisambiguationFormat(match.format)}
+*             >
+*               {match.format}: {match.matched}
+*             </Radio>
+*           ))}
+*           <Button onPress={handleDisambiguationSelect}>Confirm</Button>
+*         </Dialog>
+*       )}
+*     </>
+*   );
+* }
+* ```
+*
+* @param options - {@link UseCoordinatePasteOptions}
+* @param options.onValueApplied - Callback when a coordinate value is successfully parsed and applied.
+* @param options.onError - Optional error callback for invalid paste attempts.
+* @returns {@link UseCoordinatePasteResult} Paste handling utilities and disambiguation state.
+*/
 function useCoordinatePaste({ onValueApplied, onError }) {
 	const [disambiguationMatches, setDisambiguationMatches] = useState([]);
 	const [showDisambiguationModal, setShowDisambiguationModal] = useState(false);

package/dist/hooks/coordinate-field/use-coordinate-paste.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-coordinate-paste.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-paste.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { useState } from 'react';\nimport {\n  deduplicateMatchesByLocation,\n  isCompleteCoordinate,\n  parseCoordinatePaste,\n} from '../../components/coordinate-field/coordinate-utils';\nimport type {\n  CoordinateSystem,\n  CoordinateValue,\n  ParsedCoordinateMatch,\n} from '../../components/coordinate-field/types';\n\nexport interface UseCoordinatePasteOptions {\n  onValueApplied: (value: CoordinateValue) => void;\n  onError?: (message: string, context?: Record<string, unknown>) => void;\n}\n\nexport interface UseCoordinatePasteResult {\n  disambiguationMatches: ParsedCoordinateMatch[];\n  showDisambiguationModal: boolean;\n  selectedDisambiguationFormat: CoordinateSystem | null;\n  handleInputPaste: (e: React.ClipboardEvent<HTMLDivElement>) => void;\n  handleDisambiguationSelect: () => void;\n  setShowDisambiguationModal: (show: boolean) => void;\n  setSelectedDisambiguationFormat: (format: CoordinateSystem | null) => void;\n  cleanupDisambiguationModal: () => void;\n}\n\nexport function useCoordinatePaste({\n  onValueApplied,\n  onError,\n}: UseCoordinatePasteOptions): UseCoordinatePasteResult {\n  const [disambiguationMatches, setDisambiguationMatches] = useState<\n    ParsedCoordinateMatch[]\n  >([]);\n  const [showDisambiguationModal, setShowDisambiguationModal] = useState(false);\n  const [selectedDisambiguationFormat, setSelectedDisambiguationFormat] =\n    useState<CoordinateSystem | null>(null);\n\n  /**\n   * Handles paste failure when no coordinate formats match\n   * Calls onError with \"Invalid coordinate format\" message\n   */\n  const handlePasteNoMatches = (pastedText: string) => {\n    const errorMsg = 'Invalid coordinate format';\n    onError?.(errorMsg, { pastedText });\n  };\n\n  const handlePasteSingleMatch = (match: ParsedCoordinateMatch | undefined) => {\n    if (match) {\n      onValueApplied(match.value);\n    }\n  };\n\n  const handlePasteMultipleMatches = (matches: ParsedCoordinateMatch[]) => {\n    setDisambiguationMatches(matches);\n    const firstMatch = matches[0];\n    if (firstMatch) {\n      setSelectedDisambiguationFormat(firstMatch.format);\n    }\n    setShowDisambiguationModal(true);\n  };\n\n  const handleCoordinatePaste = (pastedText: string) => {\n    const allMatches = parseCoordinatePaste(pastedText);\n\n    if (allMatches.length === 0) {\n      handlePasteNoMatches(pastedText);\n      return;\n    }\n\n    // Deduplicate matches by location - only show modal for different locations\n    const matches = deduplicateMatchesByLocation(allMatches);\n\n    if (matches.length === 1) {\n      handlePasteSingleMatch(matches[0]);\n    } else {\n      handlePasteMultipleMatches(matches);\n    }\n  };\n\n  const handleInputPaste = (e: React.ClipboardEvent<HTMLDivElement>) => {\n    const pastedText = e.clipboardData?.getData('text/plain');\n    if (pastedText && isCompleteCoordinate(pastedText)) {\n      e.preventDefault();\n      handleCoordinatePaste(pastedText);\n    }\n  };\n\n  const cleanupDisambiguationModal = () => {\n    setShowDisambiguationModal(false);\n    setDisambiguationMatches([]);\n    setSelectedDisambiguationFormat(null);\n  };\n\n  const handleDisambiguationSelect = () => {\n    if (selectedDisambiguationFormat) {\n      const match = disambiguationMatches.find(\n        (m) => m.format === selectedDisambiguationFormat,\n      );\n      if (match) {\n        onValueApplied(match.value);\n      }\n    }\n    cleanupDisambiguationModal();\n  };\n\n  return {\n    disambiguationMatches,\n    showDisambiguationModal,\n    selectedDisambiguationFormat,\n    handleInputPaste,\n    handleDisambiguationSelect,\n    setShowDisambiguationModal,\n    setSelectedDisambiguationFormat,\n    cleanupDisambiguationModal,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAwCA,SAAgB,mBAAmB,EACjC,gBACA,WACsD;CACtD,MAAM,CAAC,uBAAuB,4BAA4B,SAExD,EAAE,CAAC;CACL,MAAM,CAAC,yBAAyB,8BAA8B,SAAS,MAAM;CAC7E,MAAM,CAAC,8BAA8B,mCACnC,SAAkC,KAAK;;;;;CAMzC,MAAM,wBAAwB,eAAuB;AAEnD,YADiB,6BACG,EAAE,YAAY,CAAC;;CAGrC,MAAM,0BAA0B,UAA6C;AAC3E,MAAI,MACF,gBAAe,MAAM,MAAM;;CAI/B,MAAM,8BAA8B,YAAqC;AACvE,2BAAyB,QAAQ;EACjC,MAAM,aAAa,QAAQ;AAC3B,MAAI,WACF,iCAAgC,WAAW,OAAO;AAEpD,6BAA2B,KAAK;;CAGlC,MAAM,yBAAyB,eAAuB;EACpD,MAAM,aAAa,qBAAqB,WAAW;AAEnD,MAAI,WAAW,WAAW,GAAG;AAC3B,wBAAqB,WAAW;AAChC;;EAIF,MAAM,UAAU,6BAA6B,WAAW;AAExD,MAAI,QAAQ,WAAW,EACrB,wBAAuB,QAAQ,GAAG;MAElC,4BAA2B,QAAQ;;CAIvC,MAAM,oBAAoB,MAA4C;EACpE,MAAM,aAAa,EAAE,eAAe,QAAQ,aAAa;AACzD,MAAI,cAAc,qBAAqB,WAAW,EAAE;AAClD,KAAE,gBAAgB;AAClB,yBAAsB,WAAW;;;CAIrC,MAAM,mCAAmC;AACvC,6BAA2B,MAAM;AACjC,2BAAyB,EAAE,CAAC;AAC5B,kCAAgC,KAAK;;CAGvC,MAAM,mCAAmC;AACvC,MAAI,8BAA8B;GAChC,MAAM,QAAQ,sBAAsB,MACjC,MAAM,EAAE,WAAW,6BACrB;AACD,OAAI,MACF,gBAAe,MAAM,MAAM;;AAG/B,8BAA4B;;AAG9B,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}
+{"version":3,"file":"use-coordinate-paste.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-paste.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { useState } from 'react';\nimport {\n  deduplicateMatchesByLocation,\n  isCompleteCoordinate,\n  parseCoordinatePaste,\n} from '../../components/coordinate-field/coordinate-utils';\nimport type {\n  CoordinateSystem,\n  CoordinateValue,\n  ParsedCoordinateMatch,\n} from '../../components/coordinate-field/types';\n\n/** Options for the useCoordinatePaste hook */\nexport interface UseCoordinatePasteOptions {\n  /** Callback when a coordinate value is successfully parsed and applied */\n  onValueApplied: (value: CoordinateValue) => void;\n  /** Optional error callback for invalid paste attempts */\n  onError?: (message: string, context?: Record<string, unknown>) => void;\n}\n\n/** Return value from the useCoordinatePaste hook */\nexport interface UseCoordinatePasteResult {\n  /** Array of parsed coordinate matches for disambiguation */\n  disambiguationMatches: ParsedCoordinateMatch[];\n  /** Whether the disambiguation modal is visible */\n  showDisambiguationModal: boolean;\n  /** Currently selected format in disambiguation modal */\n  selectedDisambiguationFormat: CoordinateSystem | null;\n  /** Paste event handler for coordinate input */\n  handleInputPaste: (e: React.ClipboardEvent<HTMLDivElement>) => void;\n  /** Confirm selection in disambiguation modal */\n  handleDisambiguationSelect: () => void;\n  /** Control disambiguation modal visibility */\n  setShowDisambiguationModal: (show: boolean) => void;\n  /** Set the selected format in disambiguation modal */\n  setSelectedDisambiguationFormat: (format: CoordinateSystem | null) => void;\n  /** Reset disambiguation modal state */\n  cleanupDisambiguationModal: () => void;\n}\n\n/**\n * Handles paste events with coordinate parsing and disambiguation when multiple formats match\n *\n * @example\n * ```tsx\n * function CoordinateFieldWithPaste() {\n *   const [value, setValue] = useState<CoordinateValue | null>(null);\n *\n *   const {\n *     disambiguationMatches,\n *     showDisambiguationModal,\n *     selectedDisambiguationFormat,\n *     handleInputPaste,\n *     handleDisambiguationSelect,\n *     setShowDisambiguationModal,\n *     setSelectedDisambiguationFormat,\n *   } = useCoordinatePaste({\n *     onValueApplied: setValue,\n *     onError: (msg) => console.error(msg),\n *   });\n *\n *   return (\n *     <>\n *       <div onPaste={handleInputPaste}>\n *         // ...Coordinate input segments\n *       </div>\n *       {showDisambiguationModal && (\n *         <Dialog onClose={() => setShowDisambiguationModal(false)}>\n *           {disambiguationMatches.map((match) => (\n *             <Radio\n *               key={match.format}\n *               value={match.format}\n *               isSelected={selectedDisambiguationFormat === match.format}\n *               onChange={() => setSelectedDisambiguationFormat(match.format)}\n *             >\n *               {match.format}: {match.matched}\n *             </Radio>\n *           ))}\n *           <Button onPress={handleDisambiguationSelect}>Confirm</Button>\n *         </Dialog>\n *       )}\n *     </>\n *   );\n * }\n * ```\n *\n * @param options - {@link UseCoordinatePasteOptions}\n * @param options.onValueApplied - Callback when a coordinate value is successfully parsed and applied.\n * @param options.onError - Optional error callback for invalid paste attempts.\n * @returns {@link UseCoordinatePasteResult} Paste handling utilities and disambiguation state.\n */\nexport function useCoordinatePaste({\n  onValueApplied,\n  onError,\n}: UseCoordinatePasteOptions): UseCoordinatePasteResult {\n  const [disambiguationMatches, setDisambiguationMatches] = useState<\n    ParsedCoordinateMatch[]\n  >([]);\n  const [showDisambiguationModal, setShowDisambiguationModal] = useState(false);\n  const [selectedDisambiguationFormat, setSelectedDisambiguationFormat] =\n    useState<CoordinateSystem | null>(null);\n\n  /**\n   * Handles paste failure when no coordinate formats match\n   * Calls onError with \"Invalid coordinate format\" message\n   */\n  const handlePasteNoMatches = (pastedText: string) => {\n    const errorMsg = 'Invalid coordinate format';\n    onError?.(errorMsg, { pastedText });\n  };\n\n  const handlePasteSingleMatch = (match: ParsedCoordinateMatch | undefined) => {\n    if (match) {\n      onValueApplied(match.value);\n    }\n  };\n\n  const handlePasteMultipleMatches = (matches: ParsedCoordinateMatch[]) => {\n    setDisambiguationMatches(matches);\n    const firstMatch = matches[0];\n    if (firstMatch) {\n      setSelectedDisambiguationFormat(firstMatch.format);\n    }\n    setShowDisambiguationModal(true);\n  };\n\n  const handleCoordinatePaste = (pastedText: string) => {\n    const allMatches = parseCoordinatePaste(pastedText);\n\n    if (allMatches.length === 0) {\n      handlePasteNoMatches(pastedText);\n      return;\n    }\n\n    // Deduplicate matches by location - only show modal for different locations\n    const matches = deduplicateMatchesByLocation(allMatches);\n\n    if (matches.length === 1) {\n      handlePasteSingleMatch(matches[0]);\n    } else {\n      handlePasteMultipleMatches(matches);\n    }\n  };\n\n  const handleInputPaste = (e: React.ClipboardEvent<HTMLDivElement>) => {\n    const pastedText = e.clipboardData?.getData('text/plain');\n    if (pastedText && isCompleteCoordinate(pastedText)) {\n      e.preventDefault();\n      handleCoordinatePaste(pastedText);\n    }\n  };\n\n  const cleanupDisambiguationModal = () => {\n    setShowDisambiguationModal(false);\n    setDisambiguationMatches([]);\n    setSelectedDisambiguationFormat(null);\n  };\n\n  const handleDisambiguationSelect = () => {\n    if (selectedDisambiguationFormat) {\n      const match = disambiguationMatches.find(\n        (m) => m.format === selectedDisambiguationFormat,\n      );\n      if (match) {\n        onValueApplied(match.value);\n      }\n    }\n    cleanupDisambiguationModal();\n  };\n\n  return {\n    disambiguationMatches,\n    showDisambiguationModal,\n    selectedDisambiguationFormat,\n    handleInputPaste,\n    handleDisambiguationSelect,\n    setShowDisambiguationModal,\n    setSelectedDisambiguationFormat,\n    cleanupDisambiguationModal,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuGA,SAAgB,mBAAmB,EACjC,gBACA,WACsD;CACtD,MAAM,CAAC,uBAAuB,4BAA4B,SAExD,EAAE,CAAC;CACL,MAAM,CAAC,yBAAyB,8BAA8B,SAAS,MAAM;CAC7E,MAAM,CAAC,8BAA8B,mCACnC,SAAkC,KAAK;;;;;CAMzC,MAAM,wBAAwB,eAAuB;AAEnD,YADiB,6BACG,EAAE,YAAY,CAAC;;CAGrC,MAAM,0BAA0B,UAA6C;AAC3E,MAAI,MACF,gBAAe,MAAM,MAAM;;CAI/B,MAAM,8BAA8B,YAAqC;AACvE,2BAAyB,QAAQ;EACjC,MAAM,aAAa,QAAQ;AAC3B,MAAI,WACF,iCAAgC,WAAW,OAAO;AAEpD,6BAA2B,KAAK;;CAGlC,MAAM,yBAAyB,eAAuB;EACpD,MAAM,aAAa,qBAAqB,WAAW;AAEnD,MAAI,WAAW,WAAW,GAAG;AAC3B,wBAAqB,WAAW;AAChC;;EAIF,MAAM,UAAU,6BAA6B,WAAW;AAExD,MAAI,QAAQ,WAAW,EACrB,wBAAuB,QAAQ,GAAG;MAElC,4BAA2B,QAAQ;;CAIvC,MAAM,oBAAoB,MAA4C;EACpE,MAAM,aAAa,EAAE,eAAe,QAAQ,aAAa;AACzD,MAAI,cAAc,qBAAqB,WAAW,EAAE;AAClD,KAAE,gBAAgB;AAClB,yBAAsB,WAAW;;;CAIrC,MAAM,mCAAmC;AACvC,6BAA2B,MAAM;AACjC,2BAAyB,EAAE,CAAC;AAC5B,kCAAgC,KAAK;;CAGvC,MAAM,mCAAmC;AACvC,MAAI,8BAA8B;GAChC,MAAM,QAAQ,sBAAsB,MACjC,MAAM,EAAE,WAAW,6BACrB;AACD,OAAI,MACF,gBAAe,MAAM,MAAM;;AAG/B,8BAA4B;;AAG9B,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACD"}