@accelint/design-toolkit 9.7.0 → 9.9.0

package/dist/components/view-stack/view.js.map

@@ -1 +1 @@
-{"version":3,"file":"view.js","names":[],"sources":["../../../src/components/view-stack/view.tsx"],"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'use client';\n\nimport { isUUID } from '@accelint/core';\nimport 'client-only';\nimport { Fragment, useContext, useEffect } from 'react';\nimport { ViewStackContext } from './context';\nimport type { ViewStackViewProps } from './types';\n\n/**\n * ViewStackView - Individual view in a ViewStack\n *\n * Represents a single view that can be pushed onto the ViewStack\n *\n * @example\n * ```tsx\n * <ViewStack id=\"app-stack\">\n *   <ViewStackView id=\"home-view\">\n *     <h1>Home Screen</h1>\n *     <p>Welcome to the app</p>\n *   </ViewStackView>\n *   <ViewStackView id=\"details-view\">\n *     <h1>Details Screen</h1>\n *     <p>Detailed information</p>\n *   </ViewStackView>\n * </ViewStack>\n * ```\n *\n * @param props - {@link ViewStackViewProps}\n * @param props.id - Unique identifier for the view.\n * @param props.children - View content to render when active.\n * @returns The rendered view content if active, or null.\n */\nexport function ViewStackView({ id, children }: ViewStackViewProps) {\n  const { parent, view, register, unregister } = useContext(ViewStackContext);\n\n  if (!parent) {\n    throw new Error('ViewStackView must be implemented within a ViewStack');\n  }\n\n  if (!isUUID(id)) {\n    throw new Error(`ViewStackView's id must be a UniqueId`);\n  }\n\n  useEffect(() => {\n    register(id);\n\n    return () => unregister(id);\n  }, [register, unregister, id]);\n\n  return view === id ? <Fragment key={id}>{children}</Fragment> : null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,SAAgB,cAAc,EAAE,IAAI,YAAgC;CAClE,MAAM,EAAE,QAAQ,MAAM,UAAU,eAAe,WAAW,iBAAiB;AAE3E,KAAI,CAAC,OACH,OAAM,IAAI,MAAM,uDAAuD;AAGzE,KAAI,CAAC,OAAO,GAAG,CACb,OAAM,IAAI,MAAM,wCAAwC;AAG1D,iBAAgB;AACd,WAAS,GAAG;AAEZ,eAAa,WAAW,GAAG;IAC1B;EAAC;EAAU;EAAY;EAAG,CAAC;AAE9B,QAAO,SAAS,KAAK,oBAAC,YAAmB,YAAL,GAAyB,GAAG"}
+{"version":3,"file":"view.js","names":[],"sources":["../../../src/components/view-stack/view.tsx"],"sourcesContent":["/*\n * Copyright 2026 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'use client';\n\nimport { isUUID } from '@accelint/core';\nimport 'client-only';\nimport { Fragment, useContext, useEffect } from 'react';\nimport { ViewStackContext } from './context';\nimport type { ViewStackViewProps } from './types';\n\n/**\n * ViewStackView - Individual view in a ViewStack\n *\n * Represents a single view that can be pushed onto the ViewStack\n *\n * @example\n * ```tsx\n * <ViewStack id=\"app-stack\">\n *   <ViewStackView id=\"home-view\">\n *     <h1>Home Screen</h1>\n *     <p>Welcome to the app</p>\n *   </ViewStackView>\n *   <ViewStackView id=\"details-view\">\n *     <h1>Details Screen</h1>\n *     <p>Detailed information</p>\n *   </ViewStackView>\n * </ViewStack>\n * ```\n *\n * @param props - {@link ViewStackViewProps}\n * @param props.id - Unique identifier for the view.\n * @param props.children - View content to render when active.\n * @returns The rendered view content if active, or null.\n */\nexport function ViewStackView({ id, children }: ViewStackViewProps) {\n  const { parent, view, register, unregister } = useContext(ViewStackContext);\n\n  if (!parent) {\n    throw new Error('ViewStackView must be implemented within a ViewStack');\n  }\n\n  if (!isUUID(id)) {\n    throw new Error(`ViewStackView's id must be a UniqueId`);\n  }\n\n  useEffect(() => {\n    register(id);\n\n    return () => unregister(id);\n  }, [register, unregister, id]);\n\n  return view === id ? <Fragment key={id}>{children}</Fragment> : null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,SAAgB,cAAc,EAAE,IAAI,YAAgC;CAClE,MAAM,EAAE,QAAQ,MAAM,UAAU,eAAe,WAAW,iBAAiB;AAE3E,KAAI,CAAC,OACH,OAAM,IAAI,MAAM,uDAAuD;AAGzE,KAAI,CAAC,OAAO,GAAG,CACb,OAAM,IAAI,MAAM,wCAAwC;AAG1D,iBAAgB;AACd,WAAS,GAAG;AAEZ,eAAa,WAAW,GAAG;IAC1B;EAAC;EAAU;EAAY;EAAG,CAAC;AAE9B,QAAO,SAAS,KAAK,oBAAC,YAAmB,YAAL,GAAyB,GAAG"}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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
@@ -11,17 +11,12 @@
  */
 
 
+import { createLoggerDomain } from "../../utils/logger/index.js";
 import { getAllCoordinateFormats } from "../../components/coordinate-field/coordinate-utils.js";
 import { useState } from "react";
-import { getLogger } from "@accelint/logger";
 
 //#region src/hooks/coordinate-field/use-coordinate-copy.ts
-const logger = getLogger({
-	enabled: process.env.NODE_ENV !== "production",
-	level: "debug",
-	prefix: "[CoordinateField]",
-	pretty: true
-});
+const logger = createLoggerDomain("[CoordinateField]");
 const COPY_FEEDBACK_DURATION_MS = 2e3;
 /**
 * Handles copying coordinates to clipboard with format conversion and visual feedback
@@ -84,7 +79,7 @@ function useCoordinateCopy({ currentValue, validationErrors, isDisabled, registe
 				setCopiedFormat(null);
 			}, COPY_FEEDBACK_DURATION_MS));
 		} catch (err) {
-			logger.withError(err).warn("Fallback copy to clipboard failed");
+			logger.withError(err).error("Fallback copy to clipboard failed");
 		}
 		document.body.removeChild(textArea);
 	};

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

@@ -1 +1 @@
-{"version":3,"file":"use-coordinate-copy.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-copy.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 { getLogger } from '@accelint/logger';\nimport { useState } from 'react';\n\nconst logger = getLogger({\n  enabled: process.env.NODE_ENV !== 'production',\n  level: 'debug',\n  prefix: '[CoordinateField]',\n  pretty: true,\n});\n\nimport { getAllCoordinateFormats } from '../../components/coordinate-field/coordinate-utils';\nimport type {\n  CoordinateSystem,\n  CoordinateValue,\n} from '../../components/coordinate-field/types';\nimport type { UseTimeoutCleanupResult } from './use-timeout-cleanup';\n\nconst COPY_FEEDBACK_DURATION_MS = 2000;\n\n/** Options for the useCoordinateCopy hook */\nexport interface UseCoordinateCopyOptions {\n  /** Current coordinate value to copy (null if empty) */\n  currentValue: CoordinateValue | null;\n  /** Array of validation error messages */\n  validationErrors: string[];\n  /** Whether copying is disabled */\n  isDisabled: boolean;\n  /** Function to register timeouts for cleanup */\n  registerTimeout: UseTimeoutCleanupResult['registerTimeout'];\n}\n\n/** Return value from the useCoordinateCopy hook */\nexport interface UseCoordinateCopyResult {\n  /** Currently copied format (for visual feedback) or null */\n  copiedFormat: CoordinateSystem | null;\n  /** Copy coordinate in specified format to clipboard */\n  handleCopyFormat: (formatToCopy: CoordinateSystem) => Promise<void>;\n  /** Whether copy format buttons should be enabled */\n  isFormatButtonEnabled: boolean;\n}\n\n/**\n * Handles copying coordinates to clipboard with format conversion and visual feedback\n *\n * @example\n * ```tsx\n * function CoordinateField() {\n *   const { registerTimeout } = useTimeoutCleanup();\n *   const [value, setValue] = useState<CoordinateValue | null>(null);\n *   const [errors, setErrors] = useState<string[]>([]);\n *\n *   const { copiedFormat, handleCopyFormat, isFormatButtonEnabled } = useCoordinateCopy({\n *     currentValue: value,\n *     validationErrors: errors,\n *     isDisabled: false,\n *     registerTimeout,\n *   });\n *\n *   return (\n *     <Button\n *       onPress={() => handleCopyFormat('dd')}\n *       isDisabled={!isFormatButtonEnabled}\n *     >\n *       {copiedFormat === 'dd' ? <Check /> : <Copy />}\n *     </Button>\n *   );\n * }\n * ```\n *\n * @param options - {@link UseCoordinateCopyOptions}\n * @param options.currentValue - Current coordinate value to copy (null if empty).\n * @param options.validationErrors - Array of validation error messages.\n * @param options.isDisabled - Whether copying is disabled.\n * @param options.registerTimeout - Function to register timeouts for cleanup.\n * @returns {@link UseCoordinateCopyResult} Copy utilities and feedback state.\n */\nexport function useCoordinateCopy({\n  currentValue,\n  validationErrors,\n  isDisabled,\n  registerTimeout,\n}: UseCoordinateCopyOptions): UseCoordinateCopyResult {\n  const [copiedFormat, setCopiedFormat] = useState<CoordinateSystem | null>(\n    null,\n  );\n\n  /**\n   * Fallback clipboard copy for browsers that don't support navigator.clipboard API.\n   * Creates a temporary textarea, copies text using document.execCommand('copy'),\n   * and provides visual feedback by setting copiedFormat state for 2 seconds.\n   *\n   * @param text - The coordinate string to copy to clipboard\n   * @param formatToCopy - The coordinate format being copied (for UI feedback)\n   */\n  const fallbackCopyToClipboard = (\n    text: string,\n    formatToCopy: CoordinateSystem,\n  ) => {\n    // Create temporary textarea for copy operation\n    const textArea = document.createElement('textarea');\n    textArea.value = text;\n    // Position off-screen so it's not visible to user\n    textArea.style.position = 'fixed';\n    textArea.style.left = '-999999px';\n    textArea.style.top = '-999999px';\n    document.body.appendChild(textArea);\n    textArea.focus();\n    textArea.select();\n\n    try {\n      document.execCommand('copy');\n\n      // Set copied format to show Check icon in UI\n      setCopiedFormat(formatToCopy);\n\n      // Reset to null after 2 seconds to return to Copy icon\n      registerTimeout(\n        setTimeout(() => {\n          setCopiedFormat(null);\n        }, COPY_FEEDBACK_DURATION_MS),\n      );\n    } catch (err) {\n      logger.withError(err).warn('Fallback copy to clipboard failed');\n    }\n\n    // Clean up temporary textarea\n    document.body.removeChild(textArea);\n  };\n\n  /**\n   * Handles copying a coordinate in the specified format to the clipboard.\n   * Uses modern clipboard API (navigator.clipboard.writeText) with fallback\n   * to document.execCommand for older browsers.\n   *\n   * Sets copiedFormat state to show visual feedback (Check icon) for 2 seconds.\n   *\n   * @param formatToCopy - The coordinate format to copy (dd, ddm, dms, mgrs, utm)\n   */\n  const handleCopyFormat = async (formatToCopy: CoordinateSystem) => {\n    if (!currentValue) {\n      return;\n    }\n\n    const allFormats = getAllCoordinateFormats(currentValue);\n    const formatResult = allFormats[formatToCopy];\n\n    if (!formatResult.isValid) {\n      return;\n    }\n\n    try {\n      // Modern clipboard API - copy and show feedback\n      await navigator.clipboard.writeText(formatResult.value);\n\n      // Set copied format to show Check icon in UI\n      setCopiedFormat(formatToCopy);\n\n      // Reset to null after 2 seconds to return to Copy icon\n      registerTimeout(\n        setTimeout(() => {\n          setCopiedFormat(null);\n        }, COPY_FEEDBACK_DURATION_MS),\n      );\n    } catch (_err) {\n      // Fall back to document.execCommand for older browsers\n      fallbackCopyToClipboard(formatResult.value, formatToCopy);\n    }\n  };\n\n  const isFormatButtonEnabled =\n    currentValue !== null && validationErrors.length === 0 && !isDisabled;\n\n  return {\n    copiedFormat,\n    handleCopyFormat,\n    isFormatButtonEnabled,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAeA,MAAM,SAAS,UAAU;CACvB,SAAS,QAAQ,IAAI,aAAa;CAClC,OAAO;CACP,QAAQ;CACR,QAAQ;CACT,CAAC;AASF,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DlC,SAAgB,kBAAkB,EAChC,cACA,kBACA,YACA,mBACoD;CACpD,MAAM,CAAC,cAAc,mBAAmB,SACtC,KACD;;;;;;;;;CAUD,MAAM,2BACJ,MACA,iBACG;EAEH,MAAM,WAAW,SAAS,cAAc,WAAW;AACnD,WAAS,QAAQ;AAEjB,WAAS,MAAM,WAAW;AAC1B,WAAS,MAAM,OAAO;AACtB,WAAS,MAAM,MAAM;AACrB,WAAS,KAAK,YAAY,SAAS;AACnC,WAAS,OAAO;AAChB,WAAS,QAAQ;AAEjB,MAAI;AACF,YAAS,YAAY,OAAO;AAG5B,mBAAgB,aAAa;AAG7B,mBACE,iBAAiB;AACf,oBAAgB,KAAK;MACpB,0BAA0B,CAC9B;WACM,KAAK;AACZ,UAAO,UAAU,IAAI,CAAC,KAAK,oCAAoC;;AAIjE,WAAS,KAAK,YAAY,SAAS;;;;;;;;;;;CAYrC,MAAM,mBAAmB,OAAO,iBAAmC;AACjE,MAAI,CAAC,aACH;EAIF,MAAM,eADa,wBAAwB,aAAa,CACxB;AAEhC,MAAI,CAAC,aAAa,QAChB;AAGF,MAAI;AAEF,SAAM,UAAU,UAAU,UAAU,aAAa,MAAM;AAGvD,mBAAgB,aAAa;AAG7B,mBACE,iBAAiB;AACf,oBAAgB,KAAK;MACpB,0BAA0B,CAC9B;WACM,MAAM;AAEb,2BAAwB,aAAa,OAAO,aAAa;;;AAO7D,QAAO;EACL;EACA;EACA,uBALA,iBAAiB,QAAQ,iBAAiB,WAAW,KAAK,CAAC;EAM5D"}
+{"version":3,"file":"use-coordinate-copy.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-copy.ts"],"sourcesContent":["/*\n * Copyright 2026 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 { createLoggerDomain } from '@/utils/logger';\n\nconst logger = createLoggerDomain('[CoordinateField]');\n\nimport { getAllCoordinateFormats } from '../../components/coordinate-field/coordinate-utils';\nimport type {\n  CoordinateSystem,\n  CoordinateValue,\n} from '../../components/coordinate-field/types';\nimport type { UseTimeoutCleanupResult } from './use-timeout-cleanup';\n\nconst COPY_FEEDBACK_DURATION_MS = 2000;\n\n/** Options for the useCoordinateCopy hook */\nexport interface UseCoordinateCopyOptions {\n  /** Current coordinate value to copy (null if empty) */\n  currentValue: CoordinateValue | null;\n  /** Array of validation error messages */\n  validationErrors: string[];\n  /** Whether copying is disabled */\n  isDisabled: boolean;\n  /** Function to register timeouts for cleanup */\n  registerTimeout: UseTimeoutCleanupResult['registerTimeout'];\n}\n\n/** Return value from the useCoordinateCopy hook */\nexport interface UseCoordinateCopyResult {\n  /** Currently copied format (for visual feedback) or null */\n  copiedFormat: CoordinateSystem | null;\n  /** Copy coordinate in specified format to clipboard */\n  handleCopyFormat: (formatToCopy: CoordinateSystem) => Promise<void>;\n  /** Whether copy format buttons should be enabled */\n  isFormatButtonEnabled: boolean;\n}\n\n/**\n * Handles copying coordinates to clipboard with format conversion and visual feedback\n *\n * @example\n * ```tsx\n * function CoordinateField() {\n *   const { registerTimeout } = useTimeoutCleanup();\n *   const [value, setValue] = useState<CoordinateValue | null>(null);\n *   const [errors, setErrors] = useState<string[]>([]);\n *\n *   const { copiedFormat, handleCopyFormat, isFormatButtonEnabled } = useCoordinateCopy({\n *     currentValue: value,\n *     validationErrors: errors,\n *     isDisabled: false,\n *     registerTimeout,\n *   });\n *\n *   return (\n *     <Button\n *       onPress={() => handleCopyFormat('dd')}\n *       isDisabled={!isFormatButtonEnabled}\n *     >\n *       {copiedFormat === 'dd' ? <Check /> : <Copy />}\n *     </Button>\n *   );\n * }\n * ```\n *\n * @param options - {@link UseCoordinateCopyOptions}\n * @param options.currentValue - Current coordinate value to copy (null if empty).\n * @param options.validationErrors - Array of validation error messages.\n * @param options.isDisabled - Whether copying is disabled.\n * @param options.registerTimeout - Function to register timeouts for cleanup.\n * @returns {@link UseCoordinateCopyResult} Copy utilities and feedback state.\n */\nexport function useCoordinateCopy({\n  currentValue,\n  validationErrors,\n  isDisabled,\n  registerTimeout,\n}: UseCoordinateCopyOptions): UseCoordinateCopyResult {\n  const [copiedFormat, setCopiedFormat] = useState<CoordinateSystem | null>(\n    null,\n  );\n\n  /**\n   * Fallback clipboard copy for browsers that don't support navigator.clipboard API.\n   * Creates a temporary textarea, copies text using document.execCommand('copy'),\n   * and provides visual feedback by setting copiedFormat state for 2 seconds.\n   *\n   * @param text - The coordinate string to copy to clipboard\n   * @param formatToCopy - The coordinate format being copied (for UI feedback)\n   */\n  const fallbackCopyToClipboard = (\n    text: string,\n    formatToCopy: CoordinateSystem,\n  ) => {\n    // Create temporary textarea for copy operation\n    const textArea = document.createElement('textarea');\n    textArea.value = text;\n    // Position off-screen so it's not visible to user\n    textArea.style.position = 'fixed';\n    textArea.style.left = '-999999px';\n    textArea.style.top = '-999999px';\n    document.body.appendChild(textArea);\n    textArea.focus();\n    textArea.select();\n\n    try {\n      document.execCommand('copy');\n\n      // Set copied format to show Check icon in UI\n      setCopiedFormat(formatToCopy);\n\n      // Reset to null after 2 seconds to return to Copy icon\n      registerTimeout(\n        setTimeout(() => {\n          setCopiedFormat(null);\n        }, COPY_FEEDBACK_DURATION_MS),\n      );\n    } catch (err) {\n      logger.withError(err).error('Fallback copy to clipboard failed');\n    }\n\n    // Clean up temporary textarea\n    document.body.removeChild(textArea);\n  };\n\n  /**\n   * Handles copying a coordinate in the specified format to the clipboard.\n   * Uses modern clipboard API (navigator.clipboard.writeText) with fallback\n   * to document.execCommand for older browsers.\n   *\n   * Sets copiedFormat state to show visual feedback (Check icon) for 2 seconds.\n   *\n   * @param formatToCopy - The coordinate format to copy (dd, ddm, dms, mgrs, utm)\n   */\n  const handleCopyFormat = async (formatToCopy: CoordinateSystem) => {\n    if (!currentValue) {\n      return;\n    }\n\n    const allFormats = getAllCoordinateFormats(currentValue);\n    const formatResult = allFormats[formatToCopy];\n\n    if (!formatResult.isValid) {\n      return;\n    }\n\n    try {\n      // Modern clipboard API - copy and show feedback\n      await navigator.clipboard.writeText(formatResult.value);\n\n      // Set copied format to show Check icon in UI\n      setCopiedFormat(formatToCopy);\n\n      // Reset to null after 2 seconds to return to Copy icon\n      registerTimeout(\n        setTimeout(() => {\n          setCopiedFormat(null);\n        }, COPY_FEEDBACK_DURATION_MS),\n      );\n    } catch (_err) {\n      // Fall back to document.execCommand for older browsers\n      fallbackCopyToClipboard(formatResult.value, formatToCopy);\n    }\n  };\n\n  const isFormatButtonEnabled =\n    currentValue !== null && validationErrors.length === 0 && !isDisabled;\n\n  return {\n    copiedFormat,\n    handleCopyFormat,\n    isFormatButtonEnabled,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAeA,MAAM,SAAS,mBAAmB,oBAAoB;AAStD,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DlC,SAAgB,kBAAkB,EAChC,cACA,kBACA,YACA,mBACoD;CACpD,MAAM,CAAC,cAAc,mBAAmB,SACtC,KACD;;;;;;;;;CAUD,MAAM,2BACJ,MACA,iBACG;EAEH,MAAM,WAAW,SAAS,cAAc,WAAW;AACnD,WAAS,QAAQ;AAEjB,WAAS,MAAM,WAAW;AAC1B,WAAS,MAAM,OAAO;AACtB,WAAS,MAAM,MAAM;AACrB,WAAS,KAAK,YAAY,SAAS;AACnC,WAAS,OAAO;AAChB,WAAS,QAAQ;AAEjB,MAAI;AACF,YAAS,YAAY,OAAO;AAG5B,mBAAgB,aAAa;AAG7B,mBACE,iBAAiB;AACf,oBAAgB,KAAK;MACpB,0BAA0B,CAC9B;WACM,KAAK;AACZ,UAAO,UAAU,IAAI,CAAC,MAAM,oCAAoC;;AAIlE,WAAS,KAAK,YAAY,SAAS;;;;;;;;;;;CAYrC,MAAM,mBAAmB,OAAO,iBAAmC;AACjE,MAAI,CAAC,aACH;EAIF,MAAM,eADa,wBAAwB,aAAa,CACxB;AAEhC,MAAI,CAAC,aAAa,QAChB;AAGF,MAAI;AAEF,SAAM,UAAU,UAAU,UAAU,aAAa,MAAM;AAGvD,mBAAgB,aAAa;AAG7B,mBACE,iBAAiB;AACf,oBAAgB,KAAK;MACpB,0BAA0B,CAC9B;WACM,MAAM;AAEb,2BAAwB,aAAa,OAAO,aAAa;;;AAO7D,QAAO;EACL;EACA;EACA,uBALA,iBAAiB,QAAQ,iBAAiB,WAAW,KAAK,CAAC;EAM5D"}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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\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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"}
+{"version":3,"file":"use-coordinate-field-state.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-field-state.ts"],"sourcesContent":["/*\n * Copyright 2026 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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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\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"}
+{"version":3,"file":"use-coordinate-field.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-field.ts"],"sourcesContent":["/*\n * Copyright 2026 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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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\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"}
+{"version":3,"file":"use-coordinate-focus.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-focus.ts"],"sourcesContent":["/*\n * Copyright 2026 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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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\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"}
+{"version":3,"file":"use-coordinate-paste.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-coordinate-paste.ts"],"sourcesContent":["/*\n * Copyright 2026 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"}

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

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

@@ -1 +1 @@
-{"version":3,"file":"use-timeout-cleanup.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-timeout-cleanup.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 { useEffect, useRef } from 'react';\n\n/** Return value from the useTimeoutCleanup hook */\nexport interface UseTimeoutCleanupResult {\n  /** Register a timeout for automatic cleanup on unmount */\n  registerTimeout: (timeoutId: NodeJS.Timeout) => void;\n}\n\n/**\n * Registers timeouts for automatic cleanup on component unmount\n *\n * @example\n * ```tsx\n * function ComponentWithTimeouts() {\n *   const { registerTimeout } = useTimeoutCleanup();\n *   const [message, setMessage] = useState('');\n *\n *   const handleClick = () => {\n *     setMessage('Saving...');\n *\n *     registerTimeout(\n *       setTimeout(() => {\n *         setMessage('Saved!');\n *       }, 1000)\n *     );\n *   };\n *\n *   return (\n *     <div>\n *       <Button onPress={handleClick}>Save</Button>\n *       <span>{message}</span>\n *     </div>\n *   );\n * }\n * ```\n *\n * @returns {@link UseTimeoutCleanupResult} Timeout registration function.\n */\nexport function useTimeoutCleanup(): UseTimeoutCleanupResult {\n  const timeoutIdsRef = useRef<Set<NodeJS.Timeout>>(new Set());\n\n  const registerTimeout = (timeoutId: NodeJS.Timeout) => {\n    timeoutIdsRef.current.add(timeoutId);\n  };\n\n  useEffect(() => {\n    return () => {\n      timeoutIdsRef.current.forEach(clearTimeout);\n      timeoutIdsRef.current.clear();\n    };\n  }, []);\n\n  return { registerTimeout };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,oBAA6C;CAC3D,MAAM,gBAAgB,uBAA4B,IAAI,KAAK,CAAC;CAE5D,MAAM,mBAAmB,cAA8B;AACrD,gBAAc,QAAQ,IAAI,UAAU;;AAGtC,iBAAgB;AACd,eAAa;AACX,iBAAc,QAAQ,QAAQ,aAAa;AAC3C,iBAAc,QAAQ,OAAO;;IAE9B,EAAE,CAAC;AAEN,QAAO,EAAE,iBAAiB"}
+{"version":3,"file":"use-timeout-cleanup.js","names":[],"sources":["../../../src/hooks/coordinate-field/use-timeout-cleanup.ts"],"sourcesContent":["/*\n * Copyright 2026 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 { useEffect, useRef } from 'react';\n\n/** Return value from the useTimeoutCleanup hook */\nexport interface UseTimeoutCleanupResult {\n  /** Register a timeout for automatic cleanup on unmount */\n  registerTimeout: (timeoutId: NodeJS.Timeout) => void;\n}\n\n/**\n * Registers timeouts for automatic cleanup on component unmount\n *\n * @example\n * ```tsx\n * function ComponentWithTimeouts() {\n *   const { registerTimeout } = useTimeoutCleanup();\n *   const [message, setMessage] = useState('');\n *\n *   const handleClick = () => {\n *     setMessage('Saving...');\n *\n *     registerTimeout(\n *       setTimeout(() => {\n *         setMessage('Saved!');\n *       }, 1000)\n *     );\n *   };\n *\n *   return (\n *     <div>\n *       <Button onPress={handleClick}>Save</Button>\n *       <span>{message}</span>\n *     </div>\n *   );\n * }\n * ```\n *\n * @returns {@link UseTimeoutCleanupResult} Timeout registration function.\n */\nexport function useTimeoutCleanup(): UseTimeoutCleanupResult {\n  const timeoutIdsRef = useRef<Set<NodeJS.Timeout>>(new Set());\n\n  const registerTimeout = (timeoutId: NodeJS.Timeout) => {\n    timeoutIdsRef.current.add(timeoutId);\n  };\n\n  useEffect(() => {\n    return () => {\n      timeoutIdsRef.current.forEach(clearTimeout);\n      timeoutIdsRef.current.clear();\n    };\n  }, []);\n\n  return { registerTimeout };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,oBAA6C;CAC3D,MAAM,gBAAgB,uBAA4B,IAAI,KAAK,CAAC;CAE5D,MAAM,mBAAmB,cAA8B;AACrD,gBAAc,QAAQ,IAAI,UAAU;;AAGtC,iBAAgB;AACd,eAAa;AACX,iBAAc,QAAQ,QAAQ,aAAa;AAC3C,iBAAc,QAAQ,OAAO;;IAE9B,EAAE,CAAC;AAEN,QAAO,EAAE,iBAAiB"}

package/dist/hooks/kanban/index.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

package/dist/hooks/kanban/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

package/dist/hooks/kanban/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["closestEdge: 'top' | 'bottom' | undefined"],"sources":["../../../src/hooks/kanban/index.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 { useDndContext, useDroppable } from '@dnd-kit/core';\nimport { useSortable } from '@dnd-kit/sortable';\nimport { CSS } from '@dnd-kit/utilities';\nimport { calculateClosestEdge } from '@/components/kanban/context';\nimport type {\n  KanbanCardData,\n  KanbanColumnData,\n} from '@/components/kanban/types';\n\n/**\n * Hook that provides drag-and-drop interactions for a kanban column.\n *\n * This hook integrates with `@dnd-kit/core` to enable dropping cards into columns.\n * It tracks hover states, validates drop targets based on the column's `canDrop` property,\n * and provides visual feedback states for both the column itself and cards within it.\n *\n * @param column - The kanban column data object containing the column's id, canDrop status, and other properties\n *\n * @returns An object containing:\n * - `ref` - Ref callback to attach to the droppable column DOM element\n * - `isHighlighted` - Boolean indicating if the column should be visually highlighted (when a card from another column is being dragged)\n * - `isActive` - Boolean indicating if the column is actively being hovered over and can accept the drop\n *\n * @example\n * ```tsx\n * function KanbanColumn({ column }: { column: KanbanColumnData }) {\n *   const { ref, isHighlighted, isActive } = useColumnInteractions(column);\n *\n *   return (\n *     <div\n *       ref={ref}\n *       className={cn({\n *         'ring-2 ring-blue-300': isHighlighted && !isActive, // Potential drop target\n *         'ring-2 ring-blue-500 bg-blue-50': isActive,        // Active drop target\n *       })}\n *     >\n *       <h2>{column.title}</h2>\n *       {column.cards.map(card => <Card key={card.id} card={card} />)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useColumnInteractions(column: KanbanColumnData) {\n  const { setNodeRef, isOver, active } = useDroppable({\n    id: column.id,\n    data: column,\n  });\n\n  // Get the global over state to detect when hovering over cards in this column\n  const { over } = useDndContext();\n\n  // Check if we're over the column itself OR over a card that belongs to this column\n  const isOverColumn = isOver || over?.data?.current?.columnId === column.id;\n\n  const isHighlighted = Boolean(\n    isOverColumn ||\n      (active &&\n        active.data.current?.columnId !== column.id &&\n        column.canDrop !== false),\n  );\n\n  const isActive = isOverColumn && column.canDrop !== false;\n\n  return {\n    ref: setNodeRef,\n    isHighlighted,\n    isActive,\n  };\n}\n\n/**\n * Hook that provides drag-and-drop interactions for a kanban card.\n *\n * This hook integrates with `@dnd-kit/sortable` to enable dragging, dropping, and reordering\n * of cards within and between columns. It handles transform animations, drag state tracking,\n * and edge detection for insertion positioning.\n *\n * @param card - The kanban card data object containing the card's id and other properties\n *\n * @returns An object containing:\n * - `ref` - Ref callback to attach to the draggable card DOM element\n * - `isDragging` - Boolean indicating if this card is currently being dragged\n * - `closestEdge` - The closest edge ('top' or 'bottom') when another card is hovering over this card, or null if not hovering\n * - `style` - CSS style object with transform and transition properties for drag animations\n * - `attributes` - Accessibility and drag attributes to spread on the card element\n * - `listeners` - Event listeners to spread on the drag handle element\n *\n * @example\n * ```tsx\n * function KanbanCard({ card }: { card: KanbanCardData }) {\n *   const { ref, isDragging, closestEdge, style, attributes, listeners } = useCardInteractions(card);\n *\n *   return (\n *     <div ref={ref} style={style} {...attributes} {...listeners}>\n *       {card.title}\n *       {closestEdge && <DropIndicator edge={closestEdge} />}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useCardInteractions(card: KanbanCardData) {\n  const {\n    attributes,\n    listeners,\n    setNodeRef,\n    transform,\n    transition,\n    isDragging,\n    over,\n    active,\n  } = useSortable({\n    id: card.id,\n    data: card,\n  });\n\n  const style = {\n    transform: CSS.Transform.toString(transform),\n    transition,\n  };\n\n  // Determine closest edge based on over position\n  let closestEdge: 'top' | 'bottom' | undefined;\n\n  if (over && over.id === card.id && active) {\n    closestEdge = calculateClosestEdge(over, active);\n  }\n\n  return {\n    ref: setNodeRef,\n    isDragging,\n    closestEdge,\n    style,\n    attributes,\n    listeners,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,SAAgB,sBAAsB,QAA0B;CAC9D,MAAM,EAAE,YAAY,QAAQ,WAAW,aAAa;EAClD,IAAI,OAAO;EACX,MAAM;EACP,CAAC;CAGF,MAAM,EAAE,SAAS,eAAe;CAGhC,MAAM,eAAe,UAAU,MAAM,MAAM,SAAS,aAAa,OAAO;AAWxE,QAAO;EACL,KAAK;EACL,eAXoB,QACpB,gBACG,UACC,OAAO,KAAK,SAAS,aAAa,OAAO,MACzC,OAAO,YAAY,MACxB;EAOC,UALe,gBAAgB,OAAO,YAAY;EAMnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCH,SAAgB,oBAAoB,MAAsB;CACxD,MAAM,EACJ,YACA,WACA,YACA,WACA,YACA,YACA,MACA,WACE,YAAY;EACd,IAAI,KAAK;EACT,MAAM;EACP,CAAC;CAEF,MAAM,QAAQ;EACZ,WAAW,IAAI,UAAU,SAAS,UAAU;EAC5C;EACD;CAGD,IAAIA;AAEJ,KAAI,QAAQ,KAAK,OAAO,KAAK,MAAM,OACjC,eAAc,qBAAqB,MAAM,OAAO;AAGlD,QAAO;EACL,KAAK;EACL;EACA;EACA;EACA;EACA;EACD"}
+{"version":3,"file":"index.js","names":["closestEdge: 'top' | 'bottom' | undefined"],"sources":["../../../src/hooks/kanban/index.ts"],"sourcesContent":["/*\n * Copyright 2026 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 { useDndContext, useDroppable } from '@dnd-kit/core';\nimport { useSortable } from '@dnd-kit/sortable';\nimport { CSS } from '@dnd-kit/utilities';\nimport { calculateClosestEdge } from '@/components/kanban/context';\nimport type {\n  KanbanCardData,\n  KanbanColumnData,\n} from '@/components/kanban/types';\n\n/**\n * Hook that provides drag-and-drop interactions for a kanban column.\n *\n * This hook integrates with `@dnd-kit/core` to enable dropping cards into columns.\n * It tracks hover states, validates drop targets based on the column's `canDrop` property,\n * and provides visual feedback states for both the column itself and cards within it.\n *\n * @param column - The kanban column data object containing the column's id, canDrop status, and other properties\n *\n * @returns An object containing:\n * - `ref` - Ref callback to attach to the droppable column DOM element\n * - `isHighlighted` - Boolean indicating if the column should be visually highlighted (when a card from another column is being dragged)\n * - `isActive` - Boolean indicating if the column is actively being hovered over and can accept the drop\n *\n * @example\n * ```tsx\n * function KanbanColumn({ column }: { column: KanbanColumnData }) {\n *   const { ref, isHighlighted, isActive } = useColumnInteractions(column);\n *\n *   return (\n *     <div\n *       ref={ref}\n *       className={cn({\n *         'ring-2 ring-blue-300': isHighlighted && !isActive, // Potential drop target\n *         'ring-2 ring-blue-500 bg-blue-50': isActive,        // Active drop target\n *       })}\n *     >\n *       <h2>{column.title}</h2>\n *       {column.cards.map(card => <Card key={card.id} card={card} />)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useColumnInteractions(column: KanbanColumnData) {\n  const { setNodeRef, isOver, active } = useDroppable({\n    id: column.id,\n    data: column,\n  });\n\n  // Get the global over state to detect when hovering over cards in this column\n  const { over } = useDndContext();\n\n  // Check if we're over the column itself OR over a card that belongs to this column\n  const isOverColumn = isOver || over?.data?.current?.columnId === column.id;\n\n  const isHighlighted = Boolean(\n    isOverColumn ||\n      (active &&\n        active.data.current?.columnId !== column.id &&\n        column.canDrop !== false),\n  );\n\n  const isActive = isOverColumn && column.canDrop !== false;\n\n  return {\n    ref: setNodeRef,\n    isHighlighted,\n    isActive,\n  };\n}\n\n/**\n * Hook that provides drag-and-drop interactions for a kanban card.\n *\n * This hook integrates with `@dnd-kit/sortable` to enable dragging, dropping, and reordering\n * of cards within and between columns. It handles transform animations, drag state tracking,\n * and edge detection for insertion positioning.\n *\n * @param card - The kanban card data object containing the card's id and other properties\n *\n * @returns An object containing:\n * - `ref` - Ref callback to attach to the draggable card DOM element\n * - `isDragging` - Boolean indicating if this card is currently being dragged\n * - `closestEdge` - The closest edge ('top' or 'bottom') when another card is hovering over this card, or null if not hovering\n * - `style` - CSS style object with transform and transition properties for drag animations\n * - `attributes` - Accessibility and drag attributes to spread on the card element\n * - `listeners` - Event listeners to spread on the drag handle element\n *\n * @example\n * ```tsx\n * function KanbanCard({ card }: { card: KanbanCardData }) {\n *   const { ref, isDragging, closestEdge, style, attributes, listeners } = useCardInteractions(card);\n *\n *   return (\n *     <div ref={ref} style={style} {...attributes} {...listeners}>\n *       {card.title}\n *       {closestEdge && <DropIndicator edge={closestEdge} />}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useCardInteractions(card: KanbanCardData) {\n  const {\n    attributes,\n    listeners,\n    setNodeRef,\n    transform,\n    transition,\n    isDragging,\n    over,\n    active,\n  } = useSortable({\n    id: card.id,\n    data: card,\n  });\n\n  const style = {\n    transform: CSS.Transform.toString(transform),\n    transition,\n  };\n\n  // Determine closest edge based on over position\n  let closestEdge: 'top' | 'bottom' | undefined;\n\n  if (over && over.id === card.id && active) {\n    closestEdge = calculateClosestEdge(over, active);\n  }\n\n  return {\n    ref: setNodeRef,\n    isDragging,\n    closestEdge,\n    style,\n    attributes,\n    listeners,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuDA,SAAgB,sBAAsB,QAA0B;CAC9D,MAAM,EAAE,YAAY,QAAQ,WAAW,aAAa;EAClD,IAAI,OAAO;EACX,MAAM;EACP,CAAC;CAGF,MAAM,EAAE,SAAS,eAAe;CAGhC,MAAM,eAAe,UAAU,MAAM,MAAM,SAAS,aAAa,OAAO;AAWxE,QAAO;EACL,KAAK;EACL,eAXoB,QACpB,gBACG,UACC,OAAO,KAAK,SAAS,aAAa,OAAO,MACzC,OAAO,YAAY,MACxB;EAOC,UALe,gBAAgB,OAAO,YAAY;EAMnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCH,SAAgB,oBAAoB,MAAsB;CACxD,MAAM,EACJ,YACA,WACA,YACA,WACA,YACA,YACA,MACA,WACE,YAAY;EACd,IAAI,KAAK;EACT,MAAM;EACP,CAAC;CAEF,MAAM,QAAQ;EACZ,WAAW,IAAI,UAAU,SAAS,UAAU;EAC5C;EACD;CAGD,IAAIA;AAEJ,KAAI,QAAQ,KAAK,OAAO,KAAK,MAAM,OACjC,eAAc,qBAAqB,MAAM,OAAO;AAGlD,QAAO;EACL,KAAK;EACL;EACA;EACA;EACA;EACA;EACD"}

package/dist/hooks/use-frame-delay/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

package/dist/hooks/use-frame-delay/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["animationId: number"],"sources":["../../../src/hooks/use-frame-delay/index.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 { useEffect, useState } from 'react';\n\nexport interface UseFrameDelayOptions {\n  /** Number of animation frames to wait (default: 2) */\n  frames?: number;\n  /** Callback fired when delay completes */\n  onReady?: () => void;\n}\n\nexport interface UseFrameDelayResult {\n  /** Whether the delay has completed */\n  isReady: boolean;\n}\n\n/**\n * Delays execution by a specified number of animation frames.\n *\n * Useful for deferring expensive renders to allow the browser to paint\n * a loading state first.\n *\n * @param options - {@link UseFrameDelayOptions}\n * @param options.frames - Number of animation frames to wait (default: 2).\n * @param options.onReady - Callback fired when delay completes.\n * @returns {@link UseFrameDelayResult} Object with isReady boolean.\n *\n * @example\n * ```tsx\n * // Pattern 1: Reactive\n * function DeferredContent() {\n *   const { isReady } = useFrameDelay();\n *   if (!isReady) return <Fallback />;\n *   return <ExpensiveContent />;\n * }\n *\n * // Pattern 2: Callback\n * function WithCallback() {\n *   const [loaded, setLoaded] = useState(false);\n *   useFrameDelay({ onReady: () => setLoaded(true) });\n *   return loaded ? <Content /> : <Loading />;\n * }\n * ```\n */\nexport function useFrameDelay(\n  options: UseFrameDelayOptions = {},\n): UseFrameDelayResult {\n  const { frames = 2, onReady } = options;\n  const [isReady, setIsReady] = useState(false);\n\n  useEffect(() => {\n    let frameCount = 0;\n    let animationId: number;\n\n    const tick = () => {\n      frameCount++;\n      if (frameCount >= frames) {\n        setIsReady(true);\n        onReady?.();\n      } else {\n        animationId = requestAnimationFrame(tick);\n      }\n    };\n\n    animationId = requestAnimationFrame(tick);\n    return () => cancelAnimationFrame(animationId);\n  }, [frames, onReady]);\n\n  return { isReady };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,SAAgB,cACd,UAAgC,EAAE,EACb;CACrB,MAAM,EAAE,SAAS,GAAG,YAAY;CAChC,MAAM,CAAC,SAAS,cAAc,SAAS,MAAM;AAE7C,iBAAgB;EACd,IAAI,aAAa;EACjB,IAAIA;EAEJ,MAAM,aAAa;AACjB;AACA,OAAI,cAAc,QAAQ;AACxB,eAAW,KAAK;AAChB,eAAW;SAEX,eAAc,sBAAsB,KAAK;;AAI7C,gBAAc,sBAAsB,KAAK;AACzC,eAAa,qBAAqB,YAAY;IAC7C,CAAC,QAAQ,QAAQ,CAAC;AAErB,QAAO,EAAE,SAAS"}
+{"version":3,"file":"index.js","names":["animationId: number"],"sources":["../../../src/hooks/use-frame-delay/index.ts"],"sourcesContent":["/*\n * Copyright 2026 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 { useEffect, useState } from 'react';\n\nexport interface UseFrameDelayOptions {\n  /** Number of animation frames to wait (default: 2) */\n  frames?: number;\n  /** Callback fired when delay completes */\n  onReady?: () => void;\n}\n\nexport interface UseFrameDelayResult {\n  /** Whether the delay has completed */\n  isReady: boolean;\n}\n\n/**\n * Delays execution by a specified number of animation frames.\n *\n * Useful for deferring expensive renders to allow the browser to paint\n * a loading state first.\n *\n * @param options - {@link UseFrameDelayOptions}\n * @param options.frames - Number of animation frames to wait (default: 2).\n * @param options.onReady - Callback fired when delay completes.\n * @returns {@link UseFrameDelayResult} Object with isReady boolean.\n *\n * @example\n * ```tsx\n * // Pattern 1: Reactive\n * function DeferredContent() {\n *   const { isReady } = useFrameDelay();\n *   if (!isReady) return <Fallback />;\n *   return <ExpensiveContent />;\n * }\n *\n * // Pattern 2: Callback\n * function WithCallback() {\n *   const [loaded, setLoaded] = useState(false);\n *   useFrameDelay({ onReady: () => setLoaded(true) });\n *   return loaded ? <Content /> : <Loading />;\n * }\n * ```\n */\nexport function useFrameDelay(\n  options: UseFrameDelayOptions = {},\n): UseFrameDelayResult {\n  const { frames = 2, onReady } = options;\n  const [isReady, setIsReady] = useState(false);\n\n  useEffect(() => {\n    let frameCount = 0;\n    let animationId: number;\n\n    const tick = () => {\n      frameCount++;\n      if (frameCount >= frames) {\n        setIsReady(true);\n        onReady?.();\n      } else {\n        animationId = requestAnimationFrame(tick);\n      }\n    };\n\n    animationId = requestAnimationFrame(tick);\n    return () => cancelAnimationFrame(animationId);\n  }, [frames, onReady]);\n\n  return { isReady };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,SAAgB,cACd,UAAgC,EAAE,EACb;CACrB,MAAM,EAAE,SAAS,GAAG,YAAY;CAChC,MAAM,CAAC,SAAS,cAAc,SAAS,MAAM;AAE7C,iBAAgB;EACd,IAAI,aAAa;EACjB,IAAIA;EAEJ,MAAM,aAAa;AACjB;AACA,OAAI,cAAc,QAAQ;AACxB,eAAW,KAAK;AAChB,eAAW;SAEX,eAAc,sBAAsB,KAAK;;AAI7C,gBAAc,sBAAsB,KAAK;AACzC,eAAa,qBAAqB,YAAY;IAC7C,CAAC,QAAQ,QAAQ,CAAC;AAErB,QAAO,EAAE,SAAS"}

package/dist/hooks/use-tree/actions/cache.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

package/dist/hooks/use-tree/actions/cache.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

package/dist/hooks/use-tree/actions/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","names":["index: number","parentKey: Key | null","key"],"sources":["../../../../src/hooks/use-tree/actions/cache.ts"],"sourcesContent":["// __private-exports\n/*\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 type { Key } from '@react-types/shared';\nimport type { TreeNode } from '../types';\n\ntype CacheTreeNode<T> = Omit<TreeNode<T>, 'children'> & {\n  children?: Key[];\n};\n\n/**\n * This is a cache created only for performance reasons and is considered\n * to be only a temporary mirror of the data. The data is *always* correct\n * cache should be updated according to the data, only. If the data and\n * the cache do not match, the cache is invalidated and rebuilt.\n *\n * This will initialize once on load with data, then\n * updated with each tree operation.\n */\nexport class Cache<T> {\n  protected cache: { lookup: Map<Key, CacheTreeNode<T>>; roots: Key[] } = {\n    lookup: new Map(),\n    roots: [],\n  };\n\n  constructor(nodes: TreeNode<T>[] = []) {\n    this.rebuild(nodes);\n  }\n\n  /**\n   * Recursively creates the cache object from tree data\n   */\n  rebuild(\n    nodes: TreeNode<T>[],\n    lookup: Map<Key, CacheTreeNode<T>> = new Map(),\n    parentKey: Key | null = null,\n  ) {\n    nodes.forEach((node) => {\n      const { children, ...rest } = node;\n\n      lookup.set(node.key, {\n        isDisabled: false,\n        isExpanded: false,\n        isSelected: false,\n        isVisible: false,\n        isVisibleComputed: false,\n        ...rest,\n        parentKey,\n        ...(children ? { children: children.map((child) => child.key) } : {}),\n      });\n\n      if (node.children) {\n        this.rebuild(node.children, lookup, node.key);\n      }\n    });\n\n    const cache = { lookup, roots: nodes.map((node) => node.key) };\n\n    if (!parentKey) {\n      this.cache = cache;\n    }\n\n    this.deriveVisibility();\n    return cache;\n  }\n\n  protected get(key: Key) {\n    const node = this.cache.lookup.get(key);\n\n    if (node === undefined) {\n      throw new Error(`Key of ${key} does not exist in tree`);\n    }\n\n    return node;\n  }\n\n  protected set(key: Key, node: CacheTreeNode<T>) {\n    this.cache.lookup.set(key, node);\n  }\n\n  protected delete(key: Key) {\n    this.cache.lookup.delete(key);\n  }\n\n  protected addToParent(parentKey: Key, childKey: Key, idx: number) {\n    const parent = this.get(parentKey);\n    const child = this.get(childKey);\n    const index = Math.max(0, idx);\n\n    this.set(childKey, {\n      ...child,\n      parentKey,\n    });\n\n    const children = (parent.children ?? []).slice(0);\n\n    children.splice(index, 0, childKey);\n\n    this.set(parentKey, {\n      ...parent,\n      children,\n    });\n  }\n\n  protected addToRoot(key: Key, idx: number) {\n    const node = this.get(key);\n    const index = Math.max(0, idx);\n\n    this.set(key, {\n      ...node,\n      parentKey: null,\n    });\n\n    this.cache.roots.splice(index, 0, key);\n  }\n\n  protected removeFromParent(parentKey: Key, childKey: Key) {\n    const parent = this.get(parentKey);\n    const child = this.get(childKey);\n\n    this.set(childKey, {\n      ...child,\n      parentKey: null,\n    });\n\n    this.cache.lookup.set(parentKey, {\n      ...parent,\n      children: parent.children?.filter((key) => key !== childKey),\n    });\n  }\n\n  protected removeFromRoot(key: Key) {\n    const node = this.get(key);\n    const idx = this.cache.roots.indexOf(key);\n\n    if (idx >= 0) {\n      this.set(key, {\n        ...node,\n        parentKey: null,\n      });\n\n      this.cache.roots.splice(idx, 1);\n    }\n  }\n\n  protected parentOrSibling(target: Key | null, position: 'before' | 'after') {\n    let index: number;\n    let parentKey: Key | null = null;\n\n    if (target === null) {\n      index = position === 'before' ? 0 : this.cache.roots.length;\n    } else {\n      const targetNode = this.get(target);\n\n      if (targetNode.parentKey) {\n        const parent = this.get(targetNode.parentKey);\n\n        parentKey = parent.key;\n        index = parent.children?.indexOf(target) ?? 0;\n      } else {\n        index = this.cache.roots.indexOf(target);\n      }\n    }\n\n    return { parentKey, index };\n  }\n\n  protected traverse(key: Key) {\n    const node = this.get(key);\n\n    this.cache.lookup.set(key, {\n      ...node,\n      isVisibleComputed: this.calculateVisibility(key),\n    });\n\n    node.children?.map((child) => this.traverse(child));\n  }\n\n  protected calculateVisibility(key: Key) {\n    let current = this.get(key);\n    const ancestry = [current];\n\n    while (current.parentKey) {\n      const parent = this.get(current.parentKey);\n      if (parent) {\n        ancestry.push(parent);\n      }\n      current = parent;\n    }\n\n    return ancestry.every((n) => n.isVisible);\n  }\n\n  protected deriveVisibility() {\n    return this.cache.roots.map((key) => this.traverse(key));\n  }\n  /**\n   * Recursively builds a TreeNode from a key\n   *\n   * @param key\n   */\n  protected buildNode(key: Key): TreeNode<T> {\n    const node = this.get(key);\n\n    const children = (node.children ?? []).reduce(\n      (acc: TreeNode<T>[], child) => {\n        const childNode = this.cache.lookup.get(child);\n\n        if (childNode && childNode.parentKey === key) {\n          acc.push(this.buildNode(child));\n        }\n\n        return acc;\n      },\n      [],\n    );\n\n    return {\n      ...node,\n      children,\n    };\n  }\n\n  /**\n   * Builds a tree structure from cache\n   *\n   * TODO: optimization - rebuild only from change to root\n   * Rebuild only from the changed node up the tree to avoid\n   * rebuilding the entire tree\n   *\n   * @param deriveVisible boolean - if true, will recompute visibility for nodes based on ancestry\n   */\n  toTree(deriveVisible?: boolean): TreeNode<T>[] {\n    if (deriveVisible) {\n      this.deriveVisibility();\n    }\n    return this.cache.roots.map((key) => this.buildNode(key));\n  }\n\n  /**\n   * CACHE FUNCTIONS\n   * These manage cache operations. No cache operations should ever be done\n   * outside this file.\n   **/\n  getNode(key: Key): TreeNode<T> {\n    const node = this.get(key);\n\n    return {\n      ...node,\n      children: node.children?.map((key) => this.buildNode(key)),\n    };\n  }\n\n  getAllKeys() {\n    return this.cache.lookup.keys();\n  }\n\n  getAllNodes() {\n    return this.cache.lookup.values();\n  }\n\n  setNode(key: Key, node: TreeNode<T>) {\n    this.set(key, {\n      ...node,\n      children: (node.children ?? []).map((child) => child.key),\n    });\n  }\n\n  setAllNodes({ parentKey, children, ...rest }: Partial<TreeNode<T>>) {\n    for (const node of this.cache.lookup.values()) {\n      this.set(node.key, {\n        ...node,\n        ...rest,\n      });\n    }\n  }\n\n  deleteNode(key: Key) {\n    const node = this.cache.lookup.get(key);\n\n    if (!node) {\n      return;\n    }\n\n    // remove children\n    node.children?.map((key) => this.deleteNode(key));\n\n    // remove node from previous parent or root\n    node.parentKey\n      ? this.removeFromParent(node.parentKey, key)\n      : this.removeFromRoot(key);\n\n    // remove the actual node\n    this.delete(key);\n  }\n\n  addNodes(\n    target: Key | null,\n    nodes: TreeNode<T>[],\n    position: 'before' | 'after',\n  ) {\n    const { parentKey, index } = this.parentOrSibling(target, position);\n    const idx = index + (position === 'before' ? 0 : 1);\n\n    nodes.map((node, i) => this.insertNode(parentKey, node, idx + i));\n  }\n\n  insertNode(parentKey: Key | null, node: TreeNode<T>, idx: number) {\n    const { children, ...rest } = node;\n\n    this.set(node.key, {\n      isDisabled: false,\n      isExpanded: false,\n      isSelected: false,\n      isVisible: false,\n      isVisibleComputed: false,\n      ...rest,\n      parentKey,\n      ...(children ? { children: children.map((child) => child.key) } : {}),\n    });\n\n    node.children?.map((child, i) => this.insertNode(node.key, child, i));\n\n    parentKey === null\n      ? this.addToRoot(node.key, idx)\n      : this.addToParent(parentKey, node.key, idx);\n  }\n\n  moveNodes(target: Key | null, nodes: Set<Key>, position: 'before' | 'after') {\n    const { parentKey, index } = this.parentOrSibling(target, position);\n    const idx = index + (position === 'before' ? 0 : 1);\n\n    Array.from(nodes).map((key, i) => this.moveNode(parentKey, key, idx + i));\n  }\n\n  moveNode(parentKey: Key | null, key: Key, idx: number) {\n    const node = this.get(key);\n\n    // remove from previous parent\n    node.parentKey\n      ? this.removeFromParent(node.parentKey, key)\n      : this.removeFromRoot(key);\n\n    // add as child to new parent or root at position\n    parentKey\n      ? this.addToParent(parentKey, key, idx)\n      : this.addToRoot(key, idx);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"cache.js","names":["index: number","parentKey: Key | null","key"],"sources":["../../../../src/hooks/use-tree/actions/cache.ts"],"sourcesContent":["// __private-exports\n/*\n * Copyright 2026 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 type { Key } from '@react-types/shared';\nimport type { TreeNode } from '../types';\n\ntype CacheTreeNode<T> = Omit<TreeNode<T>, 'children'> & {\n  children?: Key[];\n};\n\n/**\n * This is a cache created only for performance reasons and is considered\n * to be only a temporary mirror of the data. The data is *always* correct\n * cache should be updated according to the data, only. If the data and\n * the cache do not match, the cache is invalidated and rebuilt.\n *\n * This will initialize once on load with data, then\n * updated with each tree operation.\n */\nexport class Cache<T> {\n  protected cache: { lookup: Map<Key, CacheTreeNode<T>>; roots: Key[] } = {\n    lookup: new Map(),\n    roots: [],\n  };\n\n  constructor(nodes: TreeNode<T>[] = []) {\n    this.rebuild(nodes);\n  }\n\n  /**\n   * Recursively creates the cache object from tree data\n   */\n  rebuild(\n    nodes: TreeNode<T>[],\n    lookup: Map<Key, CacheTreeNode<T>> = new Map(),\n    parentKey: Key | null = null,\n  ) {\n    nodes.forEach((node) => {\n      const { children, ...rest } = node;\n\n      lookup.set(node.key, {\n        isDisabled: false,\n        isExpanded: false,\n        isSelected: false,\n        isVisible: false,\n        isVisibleComputed: false,\n        ...rest,\n        parentKey,\n        ...(children ? { children: children.map((child) => child.key) } : {}),\n      });\n\n      if (node.children) {\n        this.rebuild(node.children, lookup, node.key);\n      }\n    });\n\n    const cache = { lookup, roots: nodes.map((node) => node.key) };\n\n    if (!parentKey) {\n      this.cache = cache;\n    }\n\n    this.deriveVisibility();\n    return cache;\n  }\n\n  protected get(key: Key) {\n    const node = this.cache.lookup.get(key);\n\n    if (node === undefined) {\n      throw new Error(`Key of ${key} does not exist in tree`);\n    }\n\n    return node;\n  }\n\n  protected set(key: Key, node: CacheTreeNode<T>) {\n    this.cache.lookup.set(key, node);\n  }\n\n  protected delete(key: Key) {\n    this.cache.lookup.delete(key);\n  }\n\n  protected addToParent(parentKey: Key, childKey: Key, idx: number) {\n    const parent = this.get(parentKey);\n    const child = this.get(childKey);\n    const index = Math.max(0, idx);\n\n    this.set(childKey, {\n      ...child,\n      parentKey,\n    });\n\n    const children = (parent.children ?? []).slice(0);\n\n    children.splice(index, 0, childKey);\n\n    this.set(parentKey, {\n      ...parent,\n      children,\n    });\n  }\n\n  protected addToRoot(key: Key, idx: number) {\n    const node = this.get(key);\n    const index = Math.max(0, idx);\n\n    this.set(key, {\n      ...node,\n      parentKey: null,\n    });\n\n    this.cache.roots.splice(index, 0, key);\n  }\n\n  protected removeFromParent(parentKey: Key, childKey: Key) {\n    const parent = this.get(parentKey);\n    const child = this.get(childKey);\n\n    this.set(childKey, {\n      ...child,\n      parentKey: null,\n    });\n\n    this.cache.lookup.set(parentKey, {\n      ...parent,\n      children: parent.children?.filter((key) => key !== childKey),\n    });\n  }\n\n  protected removeFromRoot(key: Key) {\n    const node = this.get(key);\n    const idx = this.cache.roots.indexOf(key);\n\n    if (idx >= 0) {\n      this.set(key, {\n        ...node,\n        parentKey: null,\n      });\n\n      this.cache.roots.splice(idx, 1);\n    }\n  }\n\n  protected parentOrSibling(target: Key | null, position: 'before' | 'after') {\n    let index: number;\n    let parentKey: Key | null = null;\n\n    if (target === null) {\n      index = position === 'before' ? 0 : this.cache.roots.length;\n    } else {\n      const targetNode = this.get(target);\n\n      if (targetNode.parentKey) {\n        const parent = this.get(targetNode.parentKey);\n\n        parentKey = parent.key;\n        index = parent.children?.indexOf(target) ?? 0;\n      } else {\n        index = this.cache.roots.indexOf(target);\n      }\n    }\n\n    return { parentKey, index };\n  }\n\n  protected traverse(key: Key) {\n    const node = this.get(key);\n\n    this.cache.lookup.set(key, {\n      ...node,\n      isVisibleComputed: this.calculateVisibility(key),\n    });\n\n    node.children?.map((child) => this.traverse(child));\n  }\n\n  protected calculateVisibility(key: Key) {\n    let current = this.get(key);\n    const ancestry = [current];\n\n    while (current.parentKey) {\n      const parent = this.get(current.parentKey);\n      if (parent) {\n        ancestry.push(parent);\n      }\n      current = parent;\n    }\n\n    return ancestry.every((n) => n.isVisible);\n  }\n\n  protected deriveVisibility() {\n    return this.cache.roots.map((key) => this.traverse(key));\n  }\n  /**\n   * Recursively builds a TreeNode from a key\n   *\n   * @param key\n   */\n  protected buildNode(key: Key): TreeNode<T> {\n    const node = this.get(key);\n\n    const children = (node.children ?? []).reduce(\n      (acc: TreeNode<T>[], child) => {\n        const childNode = this.cache.lookup.get(child);\n\n        if (childNode && childNode.parentKey === key) {\n          acc.push(this.buildNode(child));\n        }\n\n        return acc;\n      },\n      [],\n    );\n\n    return {\n      ...node,\n      children,\n    };\n  }\n\n  /**\n   * Builds a tree structure from cache\n   *\n   * TODO: optimization - rebuild only from change to root\n   * Rebuild only from the changed node up the tree to avoid\n   * rebuilding the entire tree\n   *\n   * @param deriveVisible boolean - if true, will recompute visibility for nodes based on ancestry\n   */\n  toTree(deriveVisible?: boolean): TreeNode<T>[] {\n    if (deriveVisible) {\n      this.deriveVisibility();\n    }\n    return this.cache.roots.map((key) => this.buildNode(key));\n  }\n\n  /**\n   * CACHE FUNCTIONS\n   * These manage cache operations. No cache operations should ever be done\n   * outside this file.\n   **/\n  getNode(key: Key): TreeNode<T> {\n    const node = this.get(key);\n\n    return {\n      ...node,\n      children: node.children?.map((key) => this.buildNode(key)),\n    };\n  }\n\n  getAllKeys() {\n    return this.cache.lookup.keys();\n  }\n\n  getAllNodes() {\n    return this.cache.lookup.values();\n  }\n\n  setNode(key: Key, node: TreeNode<T>) {\n    this.set(key, {\n      ...node,\n      children: (node.children ?? []).map((child) => child.key),\n    });\n  }\n\n  setAllNodes({ parentKey, children, ...rest }: Partial<TreeNode<T>>) {\n    for (const node of this.cache.lookup.values()) {\n      this.set(node.key, {\n        ...node,\n        ...rest,\n      });\n    }\n  }\n\n  deleteNode(key: Key) {\n    const node = this.cache.lookup.get(key);\n\n    if (!node) {\n      return;\n    }\n\n    // remove children\n    node.children?.map((key) => this.deleteNode(key));\n\n    // remove node from previous parent or root\n    node.parentKey\n      ? this.removeFromParent(node.parentKey, key)\n      : this.removeFromRoot(key);\n\n    // remove the actual node\n    this.delete(key);\n  }\n\n  addNodes(\n    target: Key | null,\n    nodes: TreeNode<T>[],\n    position: 'before' | 'after',\n  ) {\n    const { parentKey, index } = this.parentOrSibling(target, position);\n    const idx = index + (position === 'before' ? 0 : 1);\n\n    nodes.map((node, i) => this.insertNode(parentKey, node, idx + i));\n  }\n\n  insertNode(parentKey: Key | null, node: TreeNode<T>, idx: number) {\n    const { children, ...rest } = node;\n\n    this.set(node.key, {\n      isDisabled: false,\n      isExpanded: false,\n      isSelected: false,\n      isVisible: false,\n      isVisibleComputed: false,\n      ...rest,\n      parentKey,\n      ...(children ? { children: children.map((child) => child.key) } : {}),\n    });\n\n    node.children?.map((child, i) => this.insertNode(node.key, child, i));\n\n    parentKey === null\n      ? this.addToRoot(node.key, idx)\n      : this.addToParent(parentKey, node.key, idx);\n  }\n\n  moveNodes(target: Key | null, nodes: Set<Key>, position: 'before' | 'after') {\n    const { parentKey, index } = this.parentOrSibling(target, position);\n    const idx = index + (position === 'before' ? 0 : 1);\n\n    Array.from(nodes).map((key, i) => this.moveNode(parentKey, key, idx + i));\n  }\n\n  moveNode(parentKey: Key | null, key: Key, idx: number) {\n    const node = this.get(key);\n\n    // remove from previous parent\n    node.parentKey\n      ? this.removeFromParent(node.parentKey, key)\n      : this.removeFromRoot(key);\n\n    // add as child to new parent or root at position\n    parentKey\n      ? this.addToParent(parentKey, key, idx)\n      : this.addToRoot(key, idx);\n  }\n}\n"],"mappings":"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"}

package/dist/hooks/use-tree/actions/index.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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

package/dist/hooks/use-tree/actions/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * 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