@accelint/design-toolkit 9.3.0 → 9.4.1

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

@@ -21,9 +21,7 @@ import { useEmit } from "@accelint/bus/react";
 
 //#region src/components/view-stack/context.tsx
 const bus = Broadcast.getInstance();
-/**
-* Context for ViewStack component
-*/
+/** Context for sharing state across ViewStack components */
 const ViewStackContext = createContext({
 	parent: null,
 	stack: [],
@@ -31,9 +29,7 @@ const ViewStackContext = createContext({
 	register: () => void 0,
 	unregister: () => void 0
 });
-/**
-* Event handlers for ViewStack events
-*/
+/** Event handlers for ViewStack events */
 const ViewStackEventHandlers = {
 	back: (stack) => bus.emit(ViewStackEventTypes.back, { stack }),
 	clear: (stack) => bus.emit(ViewStackEventTypes.clear, { stack }),
@@ -41,7 +37,22 @@ const ViewStackEventHandlers = {
 	reset: (stack) => bus.emit(ViewStackEventTypes.reset, { stack })
 };
 /**
-* Hook for emitting ViewStack events
+* Hook for programmatic ViewStack control from anywhere in the application
+*
+* @example
+* ```tsx
+* function MyComponent() {
+*   const viewStack = useViewStackEmit();
+*
+*   return (
+*     <Button onPress={() => viewStack.push('view-id')}>
+*       Navigate to View
+*     </Button>
+*   );
+* }
+* ```
+*
+* @returns Object with emit functions for back, clear, push, and reset actions.
 */
 function useViewStackEmit() {
 	const emitBack = useEmit(ViewStackEventTypes.back);

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

@@ -1 +1 @@
-{"version":3,"file":"context.js","names":[],"sources":["../../../src/components/view-stack/context.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 { Broadcast } from '@accelint/bus';\nimport { useEmit } from '@accelint/bus/react';\nimport type { UniqueId } from '@accelint/core';\nimport 'client-only';\nimport { createContext } from 'react';\nimport { ViewStackEventTypes } from './events';\nimport type { ViewStackContextValue, ViewStackEvent } from './types';\n\nconst bus = Broadcast.getInstance<ViewStackEvent>();\n\n/**\n * Context for ViewStack component\n */\nexport const ViewStackContext = createContext<ViewStackContextValue>({\n  parent: null,\n  stack: [],\n  view: null,\n  register: () => undefined,\n  unregister: () => undefined,\n});\n\n/**\n * Event handlers for ViewStack events\n */\nexport const ViewStackEventHandlers = {\n  back: (stack: UniqueId) => bus.emit(ViewStackEventTypes.back, { stack }),\n  clear: (stack: UniqueId) => bus.emit(ViewStackEventTypes.clear, { stack }),\n  push: (view: UniqueId) => bus.emit(ViewStackEventTypes.push, { view }),\n  reset: (stack: UniqueId) => bus.emit(ViewStackEventTypes.reset, { stack }),\n} as const;\n\n/**\n * Hook for emitting ViewStack events\n */\nexport function useViewStackEmit() {\n  const emitBack = useEmit<ViewStackEvent>(ViewStackEventTypes.back);\n  const emitClear = useEmit<ViewStackEvent>(ViewStackEventTypes.clear);\n  const emitPush = useEmit<ViewStackEvent>(ViewStackEventTypes.push);\n  const emitReset = useEmit<ViewStackEvent>(ViewStackEventTypes.reset);\n\n  return {\n    back: (stack: UniqueId) => emitBack({ stack }),\n    clear: (stack: UniqueId) => emitClear({ stack }),\n    push: (view: UniqueId) => emitPush({ view }),\n    reset: (stack: UniqueId) => emitReset({ stack }),\n  } as const;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,MAAM,MAAM,UAAU,aAA6B;;;;AAKnD,MAAa,mBAAmB,cAAqC;CACnE,QAAQ;CACR,OAAO,EAAE;CACT,MAAM;CACN,gBAAgB;CAChB,kBAAkB;CACnB,CAAC;;;;AAKF,MAAa,yBAAyB;CACpC,OAAO,UAAoB,IAAI,KAAK,oBAAoB,MAAM,EAAE,OAAO,CAAC;CACxE,QAAQ,UAAoB,IAAI,KAAK,oBAAoB,OAAO,EAAE,OAAO,CAAC;CAC1E,OAAO,SAAmB,IAAI,KAAK,oBAAoB,MAAM,EAAE,MAAM,CAAC;CACtE,QAAQ,UAAoB,IAAI,KAAK,oBAAoB,OAAO,EAAE,OAAO,CAAC;CAC3E;;;;AAKD,SAAgB,mBAAmB;CACjC,MAAM,WAAW,QAAwB,oBAAoB,KAAK;CAClE,MAAM,YAAY,QAAwB,oBAAoB,MAAM;CACpE,MAAM,WAAW,QAAwB,oBAAoB,KAAK;CAClE,MAAM,YAAY,QAAwB,oBAAoB,MAAM;AAEpE,QAAO;EACL,OAAO,UAAoB,SAAS,EAAE,OAAO,CAAC;EAC9C,QAAQ,UAAoB,UAAU,EAAE,OAAO,CAAC;EAChD,OAAO,SAAmB,SAAS,EAAE,MAAM,CAAC;EAC5C,QAAQ,UAAoB,UAAU,EAAE,OAAO,CAAC;EACjD"}
+{"version":3,"file":"context.js","names":[],"sources":["../../../src/components/view-stack/context.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 { Broadcast } from '@accelint/bus';\nimport { useEmit } from '@accelint/bus/react';\nimport type { UniqueId } from '@accelint/core';\nimport 'client-only';\nimport { createContext } from 'react';\nimport { ViewStackEventTypes } from './events';\nimport type { ViewStackContextValue, ViewStackEvent } from './types';\n\nconst bus = Broadcast.getInstance<ViewStackEvent>();\n\n/** Context for sharing state across ViewStack components */\nexport const ViewStackContext = createContext<ViewStackContextValue>({\n  parent: null,\n  stack: [],\n  view: null,\n  register: () => undefined,\n  unregister: () => undefined,\n});\n\n/** Event handlers for ViewStack events */\nexport const ViewStackEventHandlers = {\n  back: (stack: UniqueId) => bus.emit(ViewStackEventTypes.back, { stack }),\n  clear: (stack: UniqueId) => bus.emit(ViewStackEventTypes.clear, { stack }),\n  push: (view: UniqueId) => bus.emit(ViewStackEventTypes.push, { view }),\n  reset: (stack: UniqueId) => bus.emit(ViewStackEventTypes.reset, { stack }),\n} as const;\n\n/**\n * Hook for programmatic ViewStack control from anywhere in the application\n *\n * @example\n * ```tsx\n * function MyComponent() {\n *   const viewStack = useViewStackEmit();\n *\n *   return (\n *     <Button onPress={() => viewStack.push('view-id')}>\n *       Navigate to View\n *     </Button>\n *   );\n * }\n * ```\n *\n * @returns Object with emit functions for back, clear, push, and reset actions.\n */\nexport function useViewStackEmit() {\n  const emitBack = useEmit<ViewStackEvent>(ViewStackEventTypes.back);\n  const emitClear = useEmit<ViewStackEvent>(ViewStackEventTypes.clear);\n  const emitPush = useEmit<ViewStackEvent>(ViewStackEventTypes.push);\n  const emitReset = useEmit<ViewStackEvent>(ViewStackEventTypes.reset);\n\n  return {\n    back: (stack: UniqueId) => emitBack({ stack }),\n    clear: (stack: UniqueId) => emitClear({ stack }),\n    push: (view: UniqueId) => emitPush({ view }),\n    reset: (stack: UniqueId) => emitReset({ stack }),\n  } as const;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,MAAM,MAAM,UAAU,aAA6B;;AAGnD,MAAa,mBAAmB,cAAqC;CACnE,QAAQ;CACR,OAAO,EAAE;CACT,MAAM;CACN,gBAAgB;CAChB,kBAAkB;CACnB,CAAC;;AAGF,MAAa,yBAAyB;CACpC,OAAO,UAAoB,IAAI,KAAK,oBAAoB,MAAM,EAAE,OAAO,CAAC;CACxE,QAAQ,UAAoB,IAAI,KAAK,oBAAoB,OAAO,EAAE,OAAO,CAAC;CAC1E,OAAO,SAAmB,IAAI,KAAK,oBAAoB,MAAM,EAAE,MAAM,CAAC;CACtE,QAAQ,UAAoB,IAAI,KAAK,oBAAoB,OAAO,EAAE,OAAO,CAAC;CAC3E;;;;;;;;;;;;;;;;;;;AAoBD,SAAgB,mBAAmB;CACjC,MAAM,WAAW,QAAwB,oBAAoB,KAAK;CAClE,MAAM,YAAY,QAAwB,oBAAoB,MAAM;CACpE,MAAM,WAAW,QAAwB,oBAAoB,KAAK;CAClE,MAAM,YAAY,QAAwB,oBAAoB,MAAM;AAEpE,QAAO;EACL,OAAO,UAAoB,SAAS,EAAE,OAAO,CAAC;EAC9C,QAAQ,UAAoB,UAAU,EAAE,OAAO,CAAC;EAChD,OAAO,SAAmB,SAAS,EAAE,MAAM,CAAC;EAC5C,QAAQ,UAAoB,UAAU,EAAE,OAAO,CAAC;EACjD"}

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

@@ -1,5 +1,7 @@
 //#region src/components/view-stack/events.d.ts
+/** Namespace prefix for ViewStack events. */
 declare const ViewStackEventNamespace = "ViewStack";
+/** Event type constants for ViewStack navigation actions. */
 declare const ViewStackEventTypes: {
   readonly back: "ViewStack:back";
   readonly clear: "ViewStack:clear";

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

@@ -12,7 +12,9 @@
 
 
 //#region src/components/view-stack/events.ts
+/** Namespace prefix for ViewStack events. */
 const ViewStackEventNamespace = "ViewStack";
+/** Event type constants for ViewStack navigation actions. */
 const ViewStackEventTypes = {
 	back: `${ViewStackEventNamespace}:back`,
 	clear: `${ViewStackEventNamespace}:clear`,

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

@@ -1 +1 @@
-{"version":3,"file":"events.js","names":[],"sources":["../../../src/components/view-stack/events.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\nexport const ViewStackEventNamespace = 'ViewStack';\n\nexport const ViewStackEventTypes = {\n  back: `${ViewStackEventNamespace}:back`,\n  clear: `${ViewStackEventNamespace}:clear`,\n  reset: `${ViewStackEventNamespace}:reset`,\n  push: `${ViewStackEventNamespace}:push`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,0BAA0B;AAEvC,MAAa,sBAAsB;CACjC,MAAM,GAAG,wBAAwB;CACjC,OAAO,GAAG,wBAAwB;CAClC,OAAO,GAAG,wBAAwB;CAClC,MAAM,GAAG,wBAAwB;CAClC"}
+{"version":3,"file":"events.js","names":[],"sources":["../../../src/components/view-stack/events.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\n/** Namespace prefix for ViewStack events. */\nexport const ViewStackEventNamespace = 'ViewStack';\n\n/** Event type constants for ViewStack navigation actions. */\nexport const ViewStackEventTypes = {\n  back: `${ViewStackEventNamespace}:back`,\n  clear: `${ViewStackEventNamespace}:clear`,\n  reset: `${ViewStackEventNamespace}:reset`,\n  push: `${ViewStackEventNamespace}:push`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;AAaA,MAAa,0BAA0B;;AAGvC,MAAa,sBAAsB;CACjC,MAAM,GAAG,wBAAwB;CACjC,OAAO,GAAG,wBAAwB;CAClC,OAAO,GAAG,wBAAwB;CAClC,MAAM,GAAG,wBAAwB;CAClC"}

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_runtime186 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_runtime186.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_runtime188 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_runtime188.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);
 	/**