@accelint/design-toolkit 9.3.0 → 9.4.0

package/dist/components/view-stack/index.d.ts

@@ -12,50 +12,42 @@
 
 import { ViewStackProps } from "./types.js";
 import "client-only";
-import * as react_jsx_runtime114 from "react/jsx-runtime";
+import * as react_jsx_runtime170 from "react/jsx-runtime";
 
 //#region src/components/view-stack/index.d.ts
 
 /**
- * ViewStack - Stack-based view manager for pushing/popping views
+ * ViewStack - Stack-based navigation for managing multiple views
  *
- * Manages a stack of views that can be pushed, popped, or reset programmatically
- * and is intended for building nested or stacked UIs such as Drawer views.
+ * Supports push, pop, clear, and reset operations with global event system.
+ *
+ * @param props - {@link ViewStackProps}
+ * @param props.id - Unique identifier for the stack.
+ * @param props.children - ViewStackView components.
+ * @param props.defaultView - Default view to display when the stack is initialized.
+ * @param props.onChange - Callback when the active view changes.
+ * @returns The rendered ViewStack component.
  *
  * @example
- * const ids = {
- *   stack: uuid(),
- *   a: uuid(),
- *   b: uuid(),
- * };
+ * ```tsx
+ * const ids = { stack: uuid(), a: uuid(), b: uuid() };
  *
  * <ViewStack id={ids.stack} defaultView={ids.a}>
  *   <ViewStackView id={ids.a}>
- *     <ViewStackTrigger for={ids.b}>
- *       <Button>
- *         Push View B
- *       </Button>
- *     </ViewStackTrigger>
- *     <h1>View A</h1>
+ *     <ViewStackTrigger for={ids.b}><Button>Go to B</Button></ViewStackTrigger>
  *   </ViewStackView>
  *   <ViewStackView id={ids.b}>
- *     <ViewStackTrigger for='back'>
- *       <Button variant='icon'>
- *         <Icon>
- *           <ChevronLeft />
- *         </Icon>
- *       </Button>
- *     </ViewStackTrigger>
- *     <h1>View B</h1>
+ *     <ViewStackTrigger for="back"><Button>Back</Button></ViewStackTrigger>
  *   </ViewStackView>
  * </ViewStack>
+ * ```
  */
 declare function ViewStack({
   id,
   children,
   defaultView,
   onChange
-}: ViewStackProps): react_jsx_runtime114.JSX.Element;
+}: ViewStackProps): react_jsx_runtime170.JSX.Element;
 //#endregion
 export { ViewStack };
 //# sourceMappingURL=index.d.ts.map

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

@@ -23,38 +23,30 @@ import { isUUID } from "@accelint/core";
 
 //#region src/components/view-stack/index.tsx
 /**
-* ViewStack - Stack-based view manager for pushing/popping views
+* ViewStack - Stack-based navigation for managing multiple views
 *
-* Manages a stack of views that can be pushed, popped, or reset programmatically
-* and is intended for building nested or stacked UIs such as Drawer views.
+* Supports push, pop, clear, and reset operations with global event system.
+*
+* @param props - {@link ViewStackProps}
+* @param props.id - Unique identifier for the stack.
+* @param props.children - ViewStackView components.
+* @param props.defaultView - Default view to display when the stack is initialized.
+* @param props.onChange - Callback when the active view changes.
+* @returns The rendered ViewStack component.
 *
 * @example
-* const ids = {
-*   stack: uuid(),
-*   a: uuid(),
-*   b: uuid(),
-* };
+* ```tsx
+* const ids = { stack: uuid(), a: uuid(), b: uuid() };
 *
 * <ViewStack id={ids.stack} defaultView={ids.a}>
 *   <ViewStackView id={ids.a}>
-*     <ViewStackTrigger for={ids.b}>
-*       <Button>
-*         Push View B
-*       </Button>
-*     </ViewStackTrigger>
-*     <h1>View A</h1>
+*     <ViewStackTrigger for={ids.b}><Button>Go to B</Button></ViewStackTrigger>
 *   </ViewStackView>
 *   <ViewStackView id={ids.b}>
-*     <ViewStackTrigger for='back'>
-*       <Button variant='icon'>
-*         <Icon>
-*           <ChevronLeft />
-*         </Icon>
-*       </Button>
-*     </ViewStackTrigger>
-*     <h1>View B</h1>
+*     <ViewStackTrigger for="back"><Button>Back</Button></ViewStackTrigger>
 *   </ViewStackView>
 * </ViewStack>
+* ```
 */
 function ViewStack({ id, children, defaultView, onChange }) {
 	if (!isUUID(id)) throw new Error(`ViewStack's id must be a UniqueId`);

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["view"],"sources":["../../../src/components/view-stack/index.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 { useOn } from '@accelint/bus/react';\nimport { isUUID, type UniqueId } from '@accelint/core';\nimport 'client-only';\nimport { useCallback, useRef, useState } from 'react';\nimport { ViewStackContext } from './context';\nimport { ViewStackEventTypes } from './events';\nimport type {\n  ViewStackBackEvent,\n  ViewStackClearEvent,\n  ViewStackProps,\n  ViewStackPushEvent,\n  ViewStackResetEvent,\n} from './types';\n\n/**\n * ViewStack - Stack-based view manager for pushing/popping views\n *\n * Manages a stack of views that can be pushed, popped, or reset programmatically\n * and is intended for building nested or stacked UIs such as Drawer views.\n *\n * @example\n * const ids = {\n *   stack: uuid(),\n *   a: uuid(),\n *   b: uuid(),\n * };\n *\n * <ViewStack id={ids.stack} defaultView={ids.a}>\n *   <ViewStackView id={ids.a}>\n *     <ViewStackTrigger for={ids.b}>\n *       <Button>\n *         Push View B\n *       </Button>\n *     </ViewStackTrigger>\n *     <h1>View A</h1>\n *   </ViewStackView>\n *   <ViewStackView id={ids.b}>\n *     <ViewStackTrigger for='back'>\n *       <Button variant='icon'>\n *         <Icon>\n *           <ChevronLeft />\n *         </Icon>\n *       </Button>\n *     </ViewStackTrigger>\n *     <h1>View B</h1>\n *   </ViewStackView>\n * </ViewStack>\n */\nexport function ViewStack({\n  id,\n  children,\n  defaultView,\n  onChange,\n}: ViewStackProps) {\n  if (!isUUID(id)) {\n    throw new Error(`ViewStack's id must be a UniqueId`);\n  }\n\n  const views = useRef(new Set<UniqueId>());\n  const [stack, setStack] = useState<UniqueId[]>(\n    defaultView ? [defaultView] : [],\n  );\n  const view = stack.at(-1) ?? null;\n\n  const handleBack = useCallback(\n    (data: ViewStackBackEvent) => {\n      if (id === data?.payload?.stack) {\n        const next = stack.slice(0, -1);\n\n        if (!next.length && defaultView) {\n          next.push(defaultView);\n        }\n\n        setStack(next);\n        onChange?.(next.at(-1) ?? null);\n      }\n    },\n    [id, defaultView, onChange, stack],\n  );\n\n  const handleClear = useCallback(\n    (data: ViewStackClearEvent) => {\n      if (id === data?.payload?.stack) {\n        setStack([]);\n        onChange?.(null);\n      }\n    },\n    [id, onChange],\n  );\n\n  const handlePush = useCallback(\n    (data: ViewStackPushEvent) => {\n      if (views.current.has(data?.payload?.view)) {\n        setStack((prev) => [...prev, data?.payload?.view]);\n        onChange?.(data?.payload?.view);\n      }\n    },\n    [onChange],\n  );\n\n  const handleReset = useCallback(\n    (data: ViewStackResetEvent) => {\n      if (id === data?.payload?.stack) {\n        setStack(defaultView ? [defaultView] : []);\n        onChange?.(defaultView ?? null);\n      }\n    },\n    [id, defaultView, onChange],\n  );\n  useOn(ViewStackEventTypes.back, handleBack);\n  useOn(ViewStackEventTypes.clear, handleClear);\n  useOn(ViewStackEventTypes.push, handlePush);\n  useOn(ViewStackEventTypes.reset, handleReset);\n\n  return (\n    <ViewStackContext.Provider\n      value={{\n        parent: id,\n        stack,\n        view,\n        register: (view: UniqueId) => views.current.add(view),\n        unregister: (view: UniqueId) => views.current.delete(view),\n      }}\n    >\n      {children}\n    </ViewStackContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6DA,SAAgB,UAAU,EACxB,IACA,UACA,aACA,YACiB;AACjB,KAAI,CAAC,OAAO,GAAG,CACb,OAAM,IAAI,MAAM,oCAAoC;CAGtD,MAAM,QAAQ,uBAAO,IAAI,KAAe,CAAC;CACzC,MAAM,CAAC,OAAO,YAAY,SACxB,cAAc,CAAC,YAAY,GAAG,EAAE,CACjC;CACD,MAAM,OAAO,MAAM,GAAG,GAAG,IAAI;CAE7B,MAAM,aAAa,aAChB,SAA6B;AAC5B,MAAI,OAAO,MAAM,SAAS,OAAO;GAC/B,MAAM,OAAO,MAAM,MAAM,GAAG,GAAG;AAE/B,OAAI,CAAC,KAAK,UAAU,YAClB,MAAK,KAAK,YAAY;AAGxB,YAAS,KAAK;AACd,cAAW,KAAK,GAAG,GAAG,IAAI,KAAK;;IAGnC;EAAC;EAAI;EAAa;EAAU;EAAM,CACnC;CAED,MAAM,cAAc,aACjB,SAA8B;AAC7B,MAAI,OAAO,MAAM,SAAS,OAAO;AAC/B,YAAS,EAAE,CAAC;AACZ,cAAW,KAAK;;IAGpB,CAAC,IAAI,SAAS,CACf;CAED,MAAM,aAAa,aAChB,SAA6B;AAC5B,MAAI,MAAM,QAAQ,IAAI,MAAM,SAAS,KAAK,EAAE;AAC1C,aAAU,SAAS,CAAC,GAAG,MAAM,MAAM,SAAS,KAAK,CAAC;AAClD,cAAW,MAAM,SAAS,KAAK;;IAGnC,CAAC,SAAS,CACX;CAED,MAAM,cAAc,aACjB,SAA8B;AAC7B,MAAI,OAAO,MAAM,SAAS,OAAO;AAC/B,YAAS,cAAc,CAAC,YAAY,GAAG,EAAE,CAAC;AAC1C,cAAW,eAAe,KAAK;;IAGnC;EAAC;EAAI;EAAa;EAAS,CAC5B;AACD,OAAM,oBAAoB,MAAM,WAAW;AAC3C,OAAM,oBAAoB,OAAO,YAAY;AAC7C,OAAM,oBAAoB,MAAM,WAAW;AAC3C,OAAM,oBAAoB,OAAO,YAAY;AAE7C,QACE,oBAAC,iBAAiB;EAChB,OAAO;GACL,QAAQ;GACR;GACA;GACA,WAAW,WAAmB,MAAM,QAAQ,IAAIA,OAAK;GACrD,aAAa,WAAmB,MAAM,QAAQ,OAAOA,OAAK;GAC3D;EAEA;GACyB"}
+{"version":3,"file":"index.js","names":["view"],"sources":["../../../src/components/view-stack/index.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 { useOn } from '@accelint/bus/react';\nimport { isUUID, type UniqueId } from '@accelint/core';\nimport 'client-only';\nimport { useCallback, useRef, useState } from 'react';\nimport { ViewStackContext } from './context';\nimport { ViewStackEventTypes } from './events';\nimport type {\n  ViewStackBackEvent,\n  ViewStackClearEvent,\n  ViewStackProps,\n  ViewStackPushEvent,\n  ViewStackResetEvent,\n} from './types';\n\n/**\n * ViewStack - Stack-based navigation for managing multiple views\n *\n * Supports push, pop, clear, and reset operations with global event system.\n *\n * @param props - {@link ViewStackProps}\n * @param props.id - Unique identifier for the stack.\n * @param props.children - ViewStackView components.\n * @param props.defaultView - Default view to display when the stack is initialized.\n * @param props.onChange - Callback when the active view changes.\n * @returns The rendered ViewStack component.\n *\n * @example\n * ```tsx\n * const ids = { stack: uuid(), a: uuid(), b: uuid() };\n *\n * <ViewStack id={ids.stack} defaultView={ids.a}>\n *   <ViewStackView id={ids.a}>\n *     <ViewStackTrigger for={ids.b}><Button>Go to B</Button></ViewStackTrigger>\n *   </ViewStackView>\n *   <ViewStackView id={ids.b}>\n *     <ViewStackTrigger for=\"back\"><Button>Back</Button></ViewStackTrigger>\n *   </ViewStackView>\n * </ViewStack>\n * ```\n */\nexport function ViewStack({\n  id,\n  children,\n  defaultView,\n  onChange,\n}: ViewStackProps) {\n  if (!isUUID(id)) {\n    throw new Error(`ViewStack's id must be a UniqueId`);\n  }\n\n  const views = useRef(new Set<UniqueId>());\n  const [stack, setStack] = useState<UniqueId[]>(\n    defaultView ? [defaultView] : [],\n  );\n  const view = stack.at(-1) ?? null;\n\n  const handleBack = useCallback(\n    (data: ViewStackBackEvent) => {\n      if (id === data?.payload?.stack) {\n        const next = stack.slice(0, -1);\n\n        if (!next.length && defaultView) {\n          next.push(defaultView);\n        }\n\n        setStack(next);\n        onChange?.(next.at(-1) ?? null);\n      }\n    },\n    [id, defaultView, onChange, stack],\n  );\n\n  const handleClear = useCallback(\n    (data: ViewStackClearEvent) => {\n      if (id === data?.payload?.stack) {\n        setStack([]);\n        onChange?.(null);\n      }\n    },\n    [id, onChange],\n  );\n\n  const handlePush = useCallback(\n    (data: ViewStackPushEvent) => {\n      if (views.current.has(data?.payload?.view)) {\n        setStack((prev) => [...prev, data?.payload?.view]);\n        onChange?.(data?.payload?.view);\n      }\n    },\n    [onChange],\n  );\n\n  const handleReset = useCallback(\n    (data: ViewStackResetEvent) => {\n      if (id === data?.payload?.stack) {\n        setStack(defaultView ? [defaultView] : []);\n        onChange?.(defaultView ?? null);\n      }\n    },\n    [id, defaultView, onChange],\n  );\n  useOn(ViewStackEventTypes.back, handleBack);\n  useOn(ViewStackEventTypes.clear, handleClear);\n  useOn(ViewStackEventTypes.push, handlePush);\n  useOn(ViewStackEventTypes.reset, handleReset);\n\n  return (\n    <ViewStackContext.Provider\n      value={{\n        parent: id,\n        stack,\n        view,\n        register: (view: UniqueId) => views.current.add(view),\n        unregister: (view: UniqueId) => views.current.delete(view),\n      }}\n    >\n      {children}\n    </ViewStackContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqDA,SAAgB,UAAU,EACxB,IACA,UACA,aACA,YACiB;AACjB,KAAI,CAAC,OAAO,GAAG,CACb,OAAM,IAAI,MAAM,oCAAoC;CAGtD,MAAM,QAAQ,uBAAO,IAAI,KAAe,CAAC;CACzC,MAAM,CAAC,OAAO,YAAY,SACxB,cAAc,CAAC,YAAY,GAAG,EAAE,CACjC;CACD,MAAM,OAAO,MAAM,GAAG,GAAG,IAAI;CAE7B,MAAM,aAAa,aAChB,SAA6B;AAC5B,MAAI,OAAO,MAAM,SAAS,OAAO;GAC/B,MAAM,OAAO,MAAM,MAAM,GAAG,GAAG;AAE/B,OAAI,CAAC,KAAK,UAAU,YAClB,MAAK,KAAK,YAAY;AAGxB,YAAS,KAAK;AACd,cAAW,KAAK,GAAG,GAAG,IAAI,KAAK;;IAGnC;EAAC;EAAI;EAAa;EAAU;EAAM,CACnC;CAED,MAAM,cAAc,aACjB,SAA8B;AAC7B,MAAI,OAAO,MAAM,SAAS,OAAO;AAC/B,YAAS,EAAE,CAAC;AACZ,cAAW,KAAK;;IAGpB,CAAC,IAAI,SAAS,CACf;CAED,MAAM,aAAa,aAChB,SAA6B;AAC5B,MAAI,MAAM,QAAQ,IAAI,MAAM,SAAS,KAAK,EAAE;AAC1C,aAAU,SAAS,CAAC,GAAG,MAAM,MAAM,SAAS,KAAK,CAAC;AAClD,cAAW,MAAM,SAAS,KAAK;;IAGnC,CAAC,SAAS,CACX;CAED,MAAM,cAAc,aACjB,SAA8B;AAC7B,MAAI,OAAO,MAAM,SAAS,OAAO;AAC/B,YAAS,cAAc,CAAC,YAAY,GAAG,EAAE,CAAC;AAC1C,cAAW,eAAe,KAAK;;IAGnC;EAAC;EAAI;EAAa;EAAS,CAC5B;AACD,OAAM,oBAAoB,MAAM,WAAW;AAC3C,OAAM,oBAAoB,OAAO,YAAY;AAC7C,OAAM,oBAAoB,MAAM,WAAW;AAC3C,OAAM,oBAAoB,OAAO,YAAY;AAE7C,QACE,oBAAC,iBAAiB;EAChB,OAAO;GACL,QAAQ;GACR;GACA;GACA,WAAW,WAAmB,MAAM,QAAQ,IAAIA,OAAK;GACrD,aAAa,WAAmB,MAAM,QAAQ,OAAOA,OAAK;GAC3D;EAEA;GACyB"}

package/dist/components/view-stack/trigger.d.ts

@@ -12,18 +12,40 @@
 
 import { ViewStackTriggerProps } from "./types.js";
 import "client-only";
-import * as react_jsx_runtime116 from "react/jsx-runtime";
+import * as react_jsx_runtime172 from "react/jsx-runtime";
 
 //#region src/components/view-stack/trigger.d.ts
+
 /**
- * ViewStackTrigger - Trigger for ViewStack actions
+ * ViewStackTrigger - Pressable element that triggers ViewStack navigation actions
+ *
+ * @example
+ * ```tsx
+ * <ViewStack id="main-stack">
+ *   <ViewStackView id="home">
+ *     <h1>Home</h1>
+ *     <ViewStackTrigger for="settings-view-id">
+ *       <Button>Go to Settings</Button>
+ *     </ViewStackTrigger>
+ *   </ViewStackView>
+ *   <ViewStackView id="settings-view-id">
+ *     <h1>Settings</h1>
+ *     <ViewStackTrigger for="back:main-stack">
+ *       <Button>Back</Button>
+ *     </ViewStackTrigger>
+ *   </ViewStackView>
+ * </ViewStack>
+ * ```
  *
- * Provides a pressable element that triggers ViewStack actions
+ * @param props - {@link ViewStackTriggerProps}
+ * @param props.children - Pressable children content.
+ * @param props.for - Navigation action(s) to trigger on press.
+ * @returns The rendered ViewStackTrigger component.
  */
 declare function ViewStackTrigger({
   children,
   for: types
-}: ViewStackTriggerProps): react_jsx_runtime116.JSX.Element;
+}: ViewStackTriggerProps): react_jsx_runtime172.JSX.Element;
 //#endregion
 export { ViewStackTrigger };
 //# sourceMappingURL=trigger.d.ts.map

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

@@ -22,9 +22,30 @@ import { isUUID } from "@accelint/core";
 
 //#region src/components/view-stack/trigger.tsx
 /**
-* ViewStackTrigger - Trigger for ViewStack actions
+* ViewStackTrigger - Pressable element that triggers ViewStack navigation actions
 *
-* Provides a pressable element that triggers ViewStack actions
+* @example
+* ```tsx
+* <ViewStack id="main-stack">
+*   <ViewStackView id="home">
+*     <h1>Home</h1>
+*     <ViewStackTrigger for="settings-view-id">
+*       <Button>Go to Settings</Button>
+*     </ViewStackTrigger>
+*   </ViewStackView>
+*   <ViewStackView id="settings-view-id">
+*     <h1>Settings</h1>
+*     <ViewStackTrigger for="back:main-stack">
+*       <Button>Back</Button>
+*     </ViewStackTrigger>
+*   </ViewStackView>
+* </ViewStack>
+* ```
+*
+* @param props - {@link ViewStackTriggerProps}
+* @param props.children - Pressable children content.
+* @param props.for - Navigation action(s) to trigger on press.
+* @returns The rendered ViewStackTrigger component.
 */
 function ViewStackTrigger({ children, for: types }) {
 	const { parent } = useContext(ViewStackContext);

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

@@ -1 +1 @@
-{"version":3,"file":"trigger.js","names":[],"sources":["../../../src/components/view-stack/trigger.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 'client-only';\nimport { isUUID, type UniqueId } from '@accelint/core';\nimport { useContext } from 'react';\nimport { Pressable } from 'react-aria-components';\nimport { useViewStackEmit, ViewStackContext } from './context';\nimport type { ViewStackTriggerProps } from './types';\n\n/**\n * ViewStackTrigger - Trigger for ViewStack actions\n *\n * Provides a pressable element that triggers ViewStack actions\n */\nexport function ViewStackTrigger({\n  children,\n  for: types,\n}: ViewStackTriggerProps) {\n  const { parent } = useContext(ViewStackContext);\n  const viewStackEmit = useViewStackEmit();\n\n  function handlePress() {\n    for (const type of Array.isArray(types) ? types : [types]) {\n      let [event, id] = (isUUID(type) ? ['push', type] : type.split(':')) as [\n        'back' | 'clear' | 'reset' | 'push',\n        UniqueId | undefined | null,\n      ];\n\n      id ??= parent;\n\n      if (!id) {\n        continue;\n      }\n\n      viewStackEmit[event](id);\n    }\n  }\n\n  return <Pressable onPress={handlePress}>{children}</Pressable>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,iBAAiB,EAC/B,UACA,KAAK,SACmB;CACxB,MAAM,EAAE,WAAW,WAAW,iBAAiB;CAC/C,MAAM,gBAAgB,kBAAkB;CAExC,SAAS,cAAc;AACrB,OAAK,MAAM,QAAQ,MAAM,QAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE;GACzD,IAAI,CAAC,OAAO,MAAO,OAAO,KAAK,GAAG,CAAC,QAAQ,KAAK,GAAG,KAAK,MAAM,IAAI;AAKlE,UAAO;AAEP,OAAI,CAAC,GACH;AAGF,iBAAc,OAAO,GAAG;;;AAI5B,QAAO,oBAAC;EAAU,SAAS;EAAc;GAAqB"}
+{"version":3,"file":"trigger.js","names":[],"sources":["../../../src/components/view-stack/trigger.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 'client-only';\nimport { isUUID, type UniqueId } from '@accelint/core';\nimport { useContext } from 'react';\nimport { Pressable } from 'react-aria-components';\nimport { useViewStackEmit, ViewStackContext } from './context';\nimport type { ViewStackTriggerProps } from './types';\n\n/**\n * ViewStackTrigger - Pressable element that triggers ViewStack navigation actions\n *\n * @example\n * ```tsx\n * <ViewStack id=\"main-stack\">\n *   <ViewStackView id=\"home\">\n *     <h1>Home</h1>\n *     <ViewStackTrigger for=\"settings-view-id\">\n *       <Button>Go to Settings</Button>\n *     </ViewStackTrigger>\n *   </ViewStackView>\n *   <ViewStackView id=\"settings-view-id\">\n *     <h1>Settings</h1>\n *     <ViewStackTrigger for=\"back:main-stack\">\n *       <Button>Back</Button>\n *     </ViewStackTrigger>\n *   </ViewStackView>\n * </ViewStack>\n * ```\n *\n * @param props - {@link ViewStackTriggerProps}\n * @param props.children - Pressable children content.\n * @param props.for - Navigation action(s) to trigger on press.\n * @returns The rendered ViewStackTrigger component.\n */\nexport function ViewStackTrigger({\n  children,\n  for: types,\n}: ViewStackTriggerProps) {\n  const { parent } = useContext(ViewStackContext);\n  const viewStackEmit = useViewStackEmit();\n\n  function handlePress() {\n    for (const type of Array.isArray(types) ? types : [types]) {\n      let [event, id] = (isUUID(type) ? ['push', type] : type.split(':')) as [\n        'back' | 'clear' | 'reset' | 'push',\n        UniqueId | undefined | null,\n      ];\n\n      id ??= parent;\n\n      if (!id) {\n        continue;\n      }\n\n      viewStackEmit[event](id);\n    }\n  }\n\n  return <Pressable onPress={handlePress}>{children}</Pressable>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,SAAgB,iBAAiB,EAC/B,UACA,KAAK,SACmB;CACxB,MAAM,EAAE,WAAW,WAAW,iBAAiB;CAC/C,MAAM,gBAAgB,kBAAkB;CAExC,SAAS,cAAc;AACrB,OAAK,MAAM,QAAQ,MAAM,QAAQ,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE;GACzD,IAAI,CAAC,OAAO,MAAO,OAAO,KAAK,GAAG,CAAC,QAAQ,KAAK,GAAG,KAAK,MAAM,IAAI;AAKlE,UAAO;AAEP,OAAI,CAAC,GACH;AAGF,iBAAc,OAAO,GAAG;;;AAI5B,QAAO,oBAAC;EAAU,SAAS;EAAc;GAAqB"}

package/dist/components/view-stack/types.d.ts

@@ -17,31 +17,50 @@ import { Payload } from "@accelint/bus";
 import { UniqueId } from "@accelint/core";
 
 //#region src/components/view-stack/types.d.ts
+/**
+ * Props for the ViewStack component.
+ */
 type ViewStackProps = RefAttributes<HTMLDivElement> & PropsWithChildren<{
+  /** Unique identifier for the stack. */
   id: UniqueId;
+  /** Default view to display when the stack is initialized. */
   defaultView?: UniqueId;
+  /** Callback when the active view changes. */
   onChange?: (view: UniqueId | null) => void;
 }>;
+/**
+ * Props for the ViewStackView component.
+ */
 type ViewStackViewProps = RefAttributes<HTMLDivElement> & PropsWithChildren<{
+  /** Unique identifier for the view. */
   id: UniqueId;
 }>;
+/** Event payload for navigating back in a ViewStack. */
 type ViewStackBackEvent = Payload<typeof ViewStackEventTypes.back, {
   stack: UniqueId;
 }>;
+/** Event payload for clearing all views in a ViewStack. */
 type ViewStackClearEvent = Payload<typeof ViewStackEventTypes.clear, {
   stack: UniqueId;
 }>;
+/** Event payload for resetting a ViewStack to its default view. */
 type ViewStackResetEvent = Payload<typeof ViewStackEventTypes.reset, {
   stack: UniqueId;
 }>;
+/** Event payload for pushing a view onto a ViewStack. */
 type ViewStackPushEvent = Payload<typeof ViewStackEventTypes.push, {
   view: UniqueId;
 }>;
+/** Union of all ViewStack event types. */
 type ViewStackEvent = ViewStackBackEvent | ViewStackClearEvent | ViewStackResetEvent | ViewStackPushEvent;
 type SimpleEvents = 'back' | 'clear' | 'reset' | UniqueId;
 type TargetedEvents = `back:${UniqueId}` | `clear:${UniqueId}` | `reset:${UniqueId}`;
 type ChainedEvents = (SimpleEvents | TargetedEvents)[];
+/**
+ * Props for the ViewStackTrigger component.
+ */
 type ViewStackTriggerProps = {
+  /** Pressable children content. */
   children: ComponentProps<typeof Pressable>['children'];
   /**
    * __SimpleEvents__ allow the easiest implementation of events, but come with some restrictions:
@@ -53,6 +72,7 @@ type ViewStackTriggerProps = {
    * __ChainedEvents__ allow a list of events from a single control to enable multiple behaviors
    *
    * @example
+   * ```ts
    * // Clear a stack and then push a view on:
    * ['clear', myViewId]
    *
@@ -61,14 +81,23 @@ type ViewStackTriggerProps = {
    *
    * // Hydrate a stack with multiple views:
    * [viewOneId, viewTwoId, viewThreeId]
+   * ```
    */
   for: SimpleEvents | TargetedEvents | ChainedEvents;
 };
+/**
+ * Context value for the ViewStack component.
+ */
 type ViewStackContextValue = {
+  /** Parent stack identifier, or null if at root. */
   parent: UniqueId | null;
+  /** Array of view IDs currently in the stack. */
   stack: string[];
+  /** Currently active view ID, or null if empty. */
   view: UniqueId | null;
+  /** Registers a view with the stack. */
   register: (view: UniqueId) => void;
+  /** Unregisters a view from the stack. */
   unregister: (view: UniqueId) => void;
 };
 //#endregion

package/dist/components/view-stack/view.d.ts

@@ -12,18 +12,38 @@
 
 import { ViewStackViewProps } from "./types.js";
 import "client-only";
-import * as react_jsx_runtime117 from "react/jsx-runtime";
+import * as react_jsx_runtime175 from "react/jsx-runtime";
 
 //#region src/components/view-stack/view.d.ts
+
 /**
  * ViewStackView - Individual view in a ViewStack
  *
  * Represents a single view that can be pushed onto the ViewStack
+ *
+ * @example
+ * ```tsx
+ * <ViewStack id="app-stack">
+ *   <ViewStackView id="home-view">
+ *     <h1>Home Screen</h1>
+ *     <p>Welcome to the app</p>
+ *   </ViewStackView>
+ *   <ViewStackView id="details-view">
+ *     <h1>Details Screen</h1>
+ *     <p>Detailed information</p>
+ *   </ViewStackView>
+ * </ViewStack>
+ * ```
+ *
+ * @param props - {@link ViewStackViewProps}
+ * @param props.id - Unique identifier for the view.
+ * @param props.children - View content to render when active.
+ * @returns The rendered view content if active, or null.
  */
 declare function ViewStackView({
   id,
   children
-}: ViewStackViewProps): react_jsx_runtime117.JSX.Element | null;
+}: ViewStackViewProps): react_jsx_runtime175.JSX.Element | null;
 //#endregion
 export { ViewStackView };
 //# sourceMappingURL=view.d.ts.map

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

@@ -24,6 +24,25 @@ import { isUUID } from "@accelint/core";
 * ViewStackView - Individual view in a ViewStack
 *
 * Represents a single view that can be pushed onto the ViewStack
+*
+* @example
+* ```tsx
+* <ViewStack id="app-stack">
+*   <ViewStackView id="home-view">
+*     <h1>Home Screen</h1>
+*     <p>Welcome to the app</p>
+*   </ViewStackView>
+*   <ViewStackView id="details-view">
+*     <h1>Details Screen</h1>
+*     <p>Detailed information</p>
+*   </ViewStackView>
+* </ViewStack>
+* ```
+*
+* @param props - {@link ViewStackViewProps}
+* @param props.id - Unique identifier for the view.
+* @param props.children - View content to render when active.
+* @returns The rendered view content if active, or null.
 */
 function ViewStackView({ id, children }) {
 	const { parent, view, register, unregister } = useContext(ViewStackContext);

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 */\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,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 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"}

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

@@ -14,17 +14,61 @@ import { CoordinateSystem, CoordinateValue } from "../../components/coordinate-f
 import { UseTimeoutCleanupResult } from "./use-timeout-cleanup.js";
 
 //#region src/hooks/coordinate-field/use-coordinate-copy.d.ts
+/** Options for the useCoordinateCopy hook */
 interface UseCoordinateCopyOptions {
+  /** Current coordinate value to copy (null if empty) */
   currentValue: CoordinateValue | null;
+  /** Array of validation error messages */
   validationErrors: string[];
+  /** Whether copying is disabled */
   isDisabled: boolean;
+  /** Function to register timeouts for cleanup */
   registerTimeout: UseTimeoutCleanupResult['registerTimeout'];
 }
+/** Return value from the useCoordinateCopy hook */
 interface UseCoordinateCopyResult {
+  /** Currently copied format (for visual feedback) or null */
   copiedFormat: CoordinateSystem | null;
+  /** Copy coordinate in specified format to clipboard */
   handleCopyFormat: (formatToCopy: CoordinateSystem) => Promise<void>;
+  /** Whether copy format buttons should be enabled */
   isFormatButtonEnabled: boolean;
 }
+/**
+ * Handles copying coordinates to clipboard with format conversion and visual feedback
+ *
+ * @example
+ * ```tsx
+ * function CoordinateField() {
+ *   const { registerTimeout } = useTimeoutCleanup();
+ *   const [value, setValue] = useState<CoordinateValue | null>(null);
+ *   const [errors, setErrors] = useState<string[]>([]);
+ *
+ *   const { copiedFormat, handleCopyFormat, isFormatButtonEnabled } = useCoordinateCopy({
+ *     currentValue: value,
+ *     validationErrors: errors,
+ *     isDisabled: false,
+ *     registerTimeout,
+ *   });
+ *
+ *   return (
+ *     <Button
+ *       onPress={() => handleCopyFormat('dd')}
+ *       isDisabled={!isFormatButtonEnabled}
+ *     >
+ *       {copiedFormat === 'dd' ? <Check /> : <Copy />}
+ *     </Button>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - {@link UseCoordinateCopyOptions}
+ * @param options.currentValue - Current coordinate value to copy (null if empty).
+ * @param options.validationErrors - Array of validation error messages.
+ * @param options.isDisabled - Whether copying is disabled.
+ * @param options.registerTimeout - Function to register timeouts for cleanup.
+ * @returns {@link UseCoordinateCopyResult} Copy utilities and feedback state.
+ */
 declare function useCoordinateCopy({
   currentValue,
   validationErrors,

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

@@ -23,6 +23,41 @@ const logger = getLogger({
 	pretty: true
 });
 const COPY_FEEDBACK_DURATION_MS = 2e3;
+/**
+* Handles copying coordinates to clipboard with format conversion and visual feedback
+*
+* @example
+* ```tsx
+* function CoordinateField() {
+*   const { registerTimeout } = useTimeoutCleanup();
+*   const [value, setValue] = useState<CoordinateValue | null>(null);
+*   const [errors, setErrors] = useState<string[]>([]);
+*
+*   const { copiedFormat, handleCopyFormat, isFormatButtonEnabled } = useCoordinateCopy({
+*     currentValue: value,
+*     validationErrors: errors,
+*     isDisabled: false,
+*     registerTimeout,
+*   });
+*
+*   return (
+*     <Button
+*       onPress={() => handleCopyFormat('dd')}
+*       isDisabled={!isFormatButtonEnabled}
+*     >
+*       {copiedFormat === 'dd' ? <Check /> : <Copy />}
+*     </Button>
+*   );
+* }
+* ```
+*
+* @param options - {@link UseCoordinateCopyOptions}
+* @param options.currentValue - Current coordinate value to copy (null if empty).
+* @param options.validationErrors - Array of validation error messages.
+* @param options.isDisabled - Whether copying is disabled.
+* @param options.registerTimeout - Function to register timeouts for cleanup.
+* @returns {@link UseCoordinateCopyResult} Copy utilities and feedback state.
+*/
 function useCoordinateCopy({ currentValue, validationErrors, isDisabled, registerTimeout }) {
 	const [copiedFormat, setCopiedFormat] = useState(null);
 	/**

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\nexport interface UseCoordinateCopyOptions {\n  currentValue: CoordinateValue | null;\n  validationErrors: string[];\n  isDisabled: boolean;\n  registerTimeout: UseTimeoutCleanupResult['registerTimeout'];\n}\n\nexport interface UseCoordinateCopyResult {\n  copiedFormat: CoordinateSystem | null;\n  handleCopyFormat: (formatToCopy: CoordinateSystem) => Promise<void>;\n  isFormatButtonEnabled: boolean;\n}\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;AAelC,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 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"}

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

@@ -14,27 +14,96 @@ import { CoordinateSystem, CoordinateValue, SegmentConfig } from "../../componen
 import { Dispatch, SetStateAction } from "react";
 
 //#region src/hooks/coordinate-field/use-coordinate-field-state.d.ts
+/** Options for the useCoordinateFieldState hook */
 interface UseCoordinateFieldStateOptions {
+  /** Controlled coordinate value */
   value?: CoordinateValue | null;
+  /** Default value for uncontrolled mode */
   defaultValue?: CoordinateValue;
+  /** Coordinate format system (dd, ddm, dms, mgrs, utm) */
   format: CoordinateSystem;
+  /** Callback when coordinate value changes */
   onChange?: Dispatch<SetStateAction<CoordinateValue | null>> | ((value: CoordinateValue | null) => void);
+  /** Callback for validation errors */
   onError?: (message: string, context?: Record<string, unknown>) => void;
+  /** Register timeouts for cleanup on unmount */
   registerTimeout?: (timeoutId: NodeJS.Timeout) => void;
 }
+/** Return value from the useCoordinateFieldState hook */
 interface UseCoordinateFieldStateResult {
+  /** Current coordinate value (null if incomplete/invalid) */
   currentValue: CoordinateValue | null;
+  /** Array of display values for each segment */
   segmentValues: string[];
+  /** Array of validation error messages */
   validationErrors: string[];
+  /** All segment configurations including literals */
   segmentConfigs: SegmentConfig[];
+  /** Only editable segment configurations */
   editableSegmentConfigs: SegmentConfig[];
+  /** Handle change of a single segment */
   handleSegmentChange: (index: number, newValue: string) => void;
+  /** Set all segment values at once */
   setSegmentValues: (values: string[]) => void;
+  /** Set validation errors */
   setValidationErrors: (errors: string[]) => void;
+  /** First validation error or null */
   effectiveErrorMessage: string | null;
+  /** Apply a pasted coordinate value */
   applyPastedCoordinate: (pastedValue: CoordinateValue) => void;
+  /** Immediately run pending validation */
   flushPendingValidation: () => void;
 }
+/**
+ * Manages coordinate segment values, validation, and format conversion
+ *
+ * @example
+ * ```tsx
+ * function CoordinateInputs() {
+ *   const [value, setValue] = useState<CoordinateValue | null>(null);
+ *   const { registerTimeout } = useTimeoutCleanup();
+ *
+ *   const {
+ *     currentValue,
+ *     segmentValues,
+ *     validationErrors,
+ *     editableSegmentConfigs,
+ *     handleSegmentChange,
+ *   } = useCoordinateFieldState({
+ *     value,
+ *     format: 'ddm',
+ *     onChange: setValue,
+ *     onError: (msg) => console.error(msg),
+ *     registerTimeout,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {editableSegmentConfigs.map((config, i) => (
+ *         <input
+ *           key={i}
+ *           value={segmentValues[i]}
+ *           onChange={(e) => handleSegmentChange(i, e.target.value)}
+ *           placeholder={config.placeholder}
+ *         />
+ *       ))}
+ *       {validationErrors.map((error, i) => (
+ *         <span key={i}>{error}</span>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param options - {@link UseCoordinateFieldStateOptions}
+ * @param options.value - Controlled coordinate value.
+ * @param options.defaultValue - Default value for uncontrolled mode.
+ * @param options.format - Coordinate format system (dd, ddm, dms, mgrs, utm).
+ * @param options.onChange - Callback when coordinate value changes.
+ * @param options.onError - Callback for validation errors.
+ * @param options.registerTimeout - Register timeouts for cleanup on unmount.
+ * @returns {@link UseCoordinateFieldStateResult} Segment state, validation, and change handlers.
+ */
 declare function useCoordinateFieldState({
   value,
   defaultValue,