@accelint/design-toolkit 9.2.0 → 9.4.0

package/dist/components/color-picker/index.js

@@ -28,11 +28,13 @@ import styles from "./styles.module.css";
 * to select that color. The component supports keyboard navigation, accessibility
 * features, and fine-grained styling control through the classNames prop.
 *
-* @param items - Array of color values to display as selectable swatches
-* @param classNames - Object containing CSS class names for fine-grained styling control
-* @param classNames.picker - CSS class name for the main picker container
-* @param classNames.item - CSS class name for individual swatch items
-* @param classNames.swatch - CSS class name for the color swatch elements
+* @param props - The color picker props.
+* @param props.items - Array of color values to display as selectable swatches.
+* @param props.classNames - Custom class names for sub-elements.
+* @param props.classNames.picker - Class name for the picker container.
+* @param props.classNames.item - Class name for individual swatch items.
+* @param props.classNames.swatch - Class name for the color swatch elements.
+* @returns The color picker component.
 *
 * @example
 * ```tsx
@@ -43,13 +45,13 @@ import styles from "./styles.module.css";
 * ];
 *
 * <ColorPicker
-*   options={colors}
-*   value={'#ff0000'}
+*   items={colors}
+*   value="#ff0000"
 *   onChange={(color) => console.log('Selected:', color)}
 *   classNames={{
 *     picker: 'gap-4',
 *     item: 'rounded-lg',
-*     swatch: 'w-8 h-8'
+*     swatch: 'w-8 h-8',
 *   }}
 * />
 * ```

package/dist/components/color-picker/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/components/color-picker/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 'client-only';\nimport { clsx } from '@accelint/design-foundation/lib/utils';\nimport {\n  ColorSwatch,\n  ColorSwatchPicker,\n  ColorSwatchPickerItem,\n  composeRenderProps,\n} from 'react-aria-components';\nimport styles from './styles.module.css';\nimport type { ColorPickerProps } from './types';\n\n/**\n * A color picker component that renders a grid of color swatches for selection.\n *\n * This component provides a simple interface for users to select from a predefined\n * set of colors. It renders each color as an interactive swatch that can be clicked\n * to select that color. The component supports keyboard navigation, accessibility\n * features, and fine-grained styling control through the classNames prop.\n *\n * @param items - Array of color values to display as selectable swatches\n * @param classNames - Object containing CSS class names for fine-grained styling control\n * @param classNames.picker - CSS class name for the main picker container\n * @param classNames.item - CSS class name for individual swatch items\n * @param classNames.swatch - CSS class name for the color swatch elements\n *\n * @example\n * ```tsx\n * const colors = [\n *   '#ff0000',\n *   '#00ff00',\n *   '#0000ff',\n * ];\n *\n * <ColorPicker\n *   options={colors}\n *   value={'#ff0000'}\n *   onChange={(color) => console.log('Selected:', color)}\n *   classNames={{\n *     picker: 'gap-4',\n *     item: 'rounded-lg',\n *     swatch: 'w-8 h-8'\n *   }}\n * />\n * ```\n *\n * @remarks\n * - Colors can be provided as Color objects or color strings\n * - The component automatically handles color parsing and validation\n * - Supports all accessibility features from react-aria-components\n * - Uses a grid layout by default but can be customized via the layout prop\n */\nexport function ColorPicker({ classNames, items, ...rest }: ColorPickerProps) {\n  return (\n    <ColorSwatchPicker\n      {...rest}\n      className={composeRenderProps(classNames?.picker, (className) =>\n        clsx(styles.picker, className),\n      )}\n    >\n      {items.map((color) => (\n        <ColorSwatchPickerItem\n          key={color.toString('hexa')}\n          className={composeRenderProps(classNames?.item, (className) =>\n            clsx(styles.item, className),\n          )}\n          color={color}\n        >\n          <ColorSwatch\n            className={composeRenderProps(classNames?.swatch, (className) =>\n              clsx(styles.swatch, className),\n            )}\n          />\n        </ColorSwatchPickerItem>\n      ))}\n    </ColorSwatchPicker>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,YAAY,EAAE,YAAY,OAAO,GAAG,QAA0B;AAC5E,QACE,oBAAC;EACC,GAAI;EACJ,WAAW,mBAAmB,YAAY,SAAS,cACjD,KAAK,OAAO,QAAQ,UAAU,CAC/B;YAEA,MAAM,KAAK,UACV,oBAAC;GAEC,WAAW,mBAAmB,YAAY,OAAO,cAC/C,KAAK,OAAO,MAAM,UAAU,CAC7B;GACM;aAEP,oBAAC,eACC,WAAW,mBAAmB,YAAY,SAAS,cACjD,KAAK,OAAO,QAAQ,UAAU,CAC/B,GACD;KAVG,MAAM,SAAS,OAAO,CAWL,CACxB;GACgB"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/components/color-picker/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 'client-only';\nimport { clsx } from '@accelint/design-foundation/lib/utils';\nimport {\n  ColorSwatch,\n  ColorSwatchPicker,\n  ColorSwatchPickerItem,\n  composeRenderProps,\n} from 'react-aria-components';\nimport styles from './styles.module.css';\nimport type { ColorPickerProps } from './types';\n\n/**\n * A color picker component that renders a grid of color swatches for selection.\n *\n * This component provides a simple interface for users to select from a predefined\n * set of colors. It renders each color as an interactive swatch that can be clicked\n * to select that color. The component supports keyboard navigation, accessibility\n * features, and fine-grained styling control through the classNames prop.\n *\n * @param props - The color picker props.\n * @param props.items - Array of color values to display as selectable swatches.\n * @param props.classNames - Custom class names for sub-elements.\n * @param props.classNames.picker - Class name for the picker container.\n * @param props.classNames.item - Class name for individual swatch items.\n * @param props.classNames.swatch - Class name for the color swatch elements.\n * @returns The color picker component.\n *\n * @example\n * ```tsx\n * const colors = [\n *   '#ff0000',\n *   '#00ff00',\n *   '#0000ff',\n * ];\n *\n * <ColorPicker\n *   items={colors}\n *   value=\"#ff0000\"\n *   onChange={(color) => console.log('Selected:', color)}\n *   classNames={{\n *     picker: 'gap-4',\n *     item: 'rounded-lg',\n *     swatch: 'w-8 h-8',\n *   }}\n * />\n * ```\n *\n * @remarks\n * - Colors can be provided as Color objects or color strings\n * - The component automatically handles color parsing and validation\n * - Supports all accessibility features from react-aria-components\n * - Uses a grid layout by default but can be customized via the layout prop\n */\nexport function ColorPicker({ classNames, items, ...rest }: ColorPickerProps) {\n  return (\n    <ColorSwatchPicker\n      {...rest}\n      className={composeRenderProps(classNames?.picker, (className) =>\n        clsx(styles.picker, className),\n      )}\n    >\n      {items.map((color) => (\n        <ColorSwatchPickerItem\n          key={color.toString('hexa')}\n          className={composeRenderProps(classNames?.item, (className) =>\n            clsx(styles.item, className),\n          )}\n          color={color}\n        >\n          <ColorSwatch\n            className={composeRenderProps(classNames?.swatch, (className) =>\n              clsx(styles.swatch, className),\n            )}\n          />\n        </ColorSwatchPickerItem>\n      ))}\n    </ColorSwatchPicker>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,SAAgB,YAAY,EAAE,YAAY,OAAO,GAAG,QAA0B;AAC5E,QACE,oBAAC;EACC,GAAI;EACJ,WAAW,mBAAmB,YAAY,SAAS,cACjD,KAAK,OAAO,QAAQ,UAAU,CAC/B;YAEA,MAAM,KAAK,UACV,oBAAC;GAEC,WAAW,mBAAmB,YAAY,OAAO,cAC/C,KAAK,OAAO,MAAM,UAAU,CAC7B;GACM;aAEP,oBAAC,eACC,WAAW,mBAAmB,YAAY,SAAS,cACjD,KAAK,OAAO,QAAQ,UAAU,CAC/B,GACD;KAVG,MAAM,SAAS,OAAO,CAWL,CACxB;GACgB"}

package/dist/components/color-picker/types.d.ts

@@ -14,12 +14,20 @@ import { RefAttributes } from "react";
 import { ColorSwatchPickerItemProps, ColorSwatchPickerProps, ColorSwatchProps } from "react-aria-components";
 
 //#region src/components/color-picker/types.d.ts
+/**
+ * Props for the ColorPicker component.
+ */
 type ColorPickerProps = Omit<ColorSwatchPickerProps, 'children' | 'layout'> & RefAttributes<HTMLDivElement> & {
+  /** Custom class names for sub-elements. */
   classNames?: {
+    /** Class name for the picker container. */
     picker?: ColorSwatchPickerProps['className'];
+    /** Class name for individual swatch items. */
     item?: ColorSwatchPickerItemProps['className'];
+    /** Class name for the color swatch elements. */
     swatch?: ColorSwatchProps['className'];
   };
+  /** Array of color values to display as selectable swatches. */
   items: ColorSwatchPickerItemProps['color'][];
 };
 //#endregion

package/dist/components/combobox-field/context.d.ts

@@ -14,16 +14,32 @@ import { ProviderProps } from "../../lib/types.js";
 import { OptionsDataItem } from "../options/types.js";
 import { ComboBoxFieldProps } from "./types.js";
 import "client-only";
-import * as react40 from "react";
+import * as react13 from "react";
 import { ContextValue } from "react-aria-components";
-import * as react_jsx_runtime154 from "react/jsx-runtime";
+import * as react_jsx_runtime31 from "react/jsx-runtime";
 
 //#region src/components/combobox-field/context.d.ts
-declare const ComboBoxFieldContext: react40.Context<ContextValue<ComboBoxFieldProps<any>, HTMLDivElement>>;
+/** React context for sharing ComboBoxField configuration across components. */
+declare const ComboBoxFieldContext: react13.Context<ContextValue<ComboBoxFieldProps<any>, HTMLDivElement>>;
+/**
+ * Context provider for setting default props across multiple ComboBoxField components.
+ *
+ * @param props - The provider props.
+ * @param props.children - Child components that will receive the combobox field context.
+ * @returns The combobox field context provider wrapping children.
+ *
+ * @example
+ * ```tsx
+ * <ComboBoxFieldProvider size="small">
+ *   <ComboBoxField defaultItems={items1}>{...}</ComboBoxField>
+ *   <ComboBoxField defaultItems={items2}>{...}</ComboBoxField>
+ * </ComboBoxFieldProvider>
+ * ```
+ */
 declare function ComboBoxFieldProvider<T extends OptionsDataItem>({
   children,
   ...props
-}: ProviderProps<ComboBoxFieldProps<T>>): react_jsx_runtime154.JSX.Element;
+}: ProviderProps<ComboBoxFieldProps<T>>): react_jsx_runtime31.JSX.Element;
 //#endregion
 export { ComboBoxFieldContext, ComboBoxFieldProvider };
 //# sourceMappingURL=context.d.ts.map

package/dist/components/combobox-field/context.js

@@ -18,7 +18,23 @@ import { createContext } from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/components/combobox-field/context.tsx
+/** React context for sharing ComboBoxField configuration across components. */
 const ComboBoxFieldContext = createContext(null);
+/**
+* Context provider for setting default props across multiple ComboBoxField components.
+*
+* @param props - The provider props.
+* @param props.children - Child components that will receive the combobox field context.
+* @returns The combobox field context provider wrapping children.
+*
+* @example
+* ```tsx
+* <ComboBoxFieldProvider size="small">
+*   <ComboBoxField defaultItems={items1}>{...}</ComboBoxField>
+*   <ComboBoxField defaultItems={items2}>{...}</ComboBoxField>
+* </ComboBoxFieldProvider>
+* ```
+*/
 function ComboBoxFieldProvider({ children, ...props }) {
 	return /* @__PURE__ */ jsx(ComboBoxFieldContext.Provider, {
 		value: props,

package/dist/components/combobox-field/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","names":[],"sources":["../../../src/components/combobox-field/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 'client-only';\nimport { createContext } from 'react';\nimport type { ContextValue } from 'react-aria-components';\nimport type { ProviderProps } from '@/lib/types';\nimport type { OptionsDataItem } from '../options/types';\nimport type { ComboBoxFieldProps } from './types';\n\nexport const ComboBoxFieldContext =\n  // biome-ignore lint/suspicious/noExplicitAny: Setting a type would restrict it beyond what the component allows to extend to\n  createContext<ContextValue<ComboBoxFieldProps<any>, HTMLDivElement>>(null);\n\nexport function ComboBoxFieldProvider<T extends OptionsDataItem>({\n  children,\n  ...props\n}: ProviderProps<ComboBoxFieldProps<T>>) {\n  return (\n    <ComboBoxFieldContext.Provider value={props}>\n      {children}\n    </ComboBoxFieldContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,uBAEX,cAAqE,KAAK;AAE5E,SAAgB,sBAAiD,EAC/D,UACA,GAAG,SACoC;AACvC,QACE,oBAAC,qBAAqB;EAAS,OAAO;EACnC;GAC6B"}
+{"version":3,"file":"context.js","names":[],"sources":["../../../src/components/combobox-field/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 'client-only';\nimport { createContext } from 'react';\nimport type { ContextValue } from 'react-aria-components';\nimport type { ProviderProps } from '@/lib/types';\nimport type { OptionsDataItem } from '../options/types';\nimport type { ComboBoxFieldProps } from './types';\n\n/** React context for sharing ComboBoxField configuration across components. */\nexport const ComboBoxFieldContext =\n  // biome-ignore lint/suspicious/noExplicitAny: Setting a type would restrict it beyond what the component allows to extend to\n  createContext<ContextValue<ComboBoxFieldProps<any>, HTMLDivElement>>(null);\n\n/**\n * Context provider for setting default props across multiple ComboBoxField components.\n *\n * @param props - The provider props.\n * @param props.children - Child components that will receive the combobox field context.\n * @returns The combobox field context provider wrapping children.\n *\n * @example\n * ```tsx\n * <ComboBoxFieldProvider size=\"small\">\n *   <ComboBoxField defaultItems={items1}>{...}</ComboBoxField>\n *   <ComboBoxField defaultItems={items2}>{...}</ComboBoxField>\n * </ComboBoxFieldProvider>\n * ```\n */\nexport function ComboBoxFieldProvider<T extends OptionsDataItem>({\n  children,\n  ...props\n}: ProviderProps<ComboBoxFieldProps<T>>) {\n  return (\n    <ComboBoxFieldContext.Provider value={props}>\n      {children}\n    </ComboBoxFieldContext.Provider>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,MAAa,uBAEX,cAAqE,KAAK;;;;;;;;;;;;;;;;AAiB5E,SAAgB,sBAAiD,EAC/D,UACA,GAAG,SACoC;AACvC,QACE,oBAAC,qBAAqB;EAAS,OAAO;EACnC;GAC6B"}

package/dist/components/combobox-field/index.d.ts

@@ -13,24 +13,37 @@
 import { OptionsDataItem } from "../options/types.js";
 import { ComboBoxFieldProps } from "./types.js";
 import "client-only";
-import * as react_jsx_runtime155 from "react/jsx-runtime";
+import * as react_jsx_runtime32 from "react/jsx-runtime";
 
 //#region src/components/combobox-field/index.d.ts
+
 /**
  * ComboBoxField - Accessible searchable combobox with dropdown options
  *
  * A combobox field that provides a searchable input with virtualized dropdown
  * options and support for sections, icons, and rich content.
  *
+ * @param props - The combobox field props.
+ * @param props.ref - Reference to the field element.
+ * @param props.children - Render function for options.
+ * @param props.classNames - Custom class names for sub-elements.
+ * @param props.label - Label text displayed above the field.
+ * @param props.description - Helper text displayed below the field.
+ * @param props.errorMessage - Error message displayed when invalid.
+ * @param props.size - Size variant of the field.
+ * @returns The combobox field component.
+ *
  * @example
+ * ```tsx
  * <ComboBoxField defaultItems={items}>
  *   {(item) => <OptionsItem key={item.id} textValue={item.name}>{item.name}</OptionsItem>}
  * </ComboBoxField>
+ * ```
  */
 declare function ComboBoxField<T extends OptionsDataItem>({
   ref,
   ...props
-}: ComboBoxFieldProps<T>): react_jsx_runtime155.JSX.Element;
+}: ComboBoxFieldProps<T>): react_jsx_runtime32.JSX.Element;
 //#endregion
 export { ComboBoxField };
 //# sourceMappingURL=index.d.ts.map

package/dist/components/combobox-field/index.js

@@ -21,7 +21,7 @@ import "client-only";
 import { clsx } from "@accelint/design-foundation/lib/utils";
 import { Button, ComboBox, FieldError, Input, ListLayout, Popover, Text, Virtualizer, composeRenderProps, useContextProps } from "react-aria-components";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { ChevronDown } from "@accelint/icons";
+import ChevronDown from "@accelint/icons/chevron-down";
 import styles from "./styles.module.css";
 
 //#region src/components/combobox-field/index.tsx
@@ -31,14 +31,26 @@ import styles from "./styles.module.css";
 * A combobox field that provides a searchable input with virtualized dropdown
 * options and support for sections, icons, and rich content.
 *
+* @param props - The combobox field props.
+* @param props.ref - Reference to the field element.
+* @param props.children - Render function for options.
+* @param props.classNames - Custom class names for sub-elements.
+* @param props.label - Label text displayed above the field.
+* @param props.description - Helper text displayed below the field.
+* @param props.errorMessage - Error message displayed when invalid.
+* @param props.size - Size variant of the field.
+* @returns The combobox field component.
+*
 * @example
+* ```tsx
 * <ComboBoxField defaultItems={items}>
 *   {(item) => <OptionsItem key={item.id} textValue={item.name}>{item.name}</OptionsItem>}
 * </ComboBoxField>
+* ```
 */
 function ComboBoxField({ ref, ...props }) {
 	[props, ref] = useContextProps(props, ref ?? null, ComboBoxFieldContext);
-	const { children, classNames, description: descriptionProp, errorMessage: errorMessageProp, inputProps, label: labelProp, layoutOptions, menuTrigger = "focus", size = "medium", isInvalid: isInvalidProp, ...rest } = props;
+	const { children, classNames, description: descriptionProp, errorMessage: errorMessageProp, inputProps, label: labelProp, layoutOptions, menuTrigger = "focus", size = "medium", isInvalid: isInvalidProp, isReadOnly = false, ...rest } = props;
 	const errorMessage = errorMessageProp || null;
 	const isSmall = size === "small";
 	return /* @__PURE__ */ jsx(ComboBox, {
@@ -47,45 +59,52 @@ function ComboBoxField({ ref, ...props }) {
 		className: composeRenderProps(classNames?.field, (className) => clsx("group/combobox-field", styles.field, className)),
 		menuTrigger,
 		isInvalid: isInvalidProp || (errorMessage ? true : void 0),
+		isReadOnly,
 		"data-size": size,
-		children: ({ isDisabled, isInvalid, isRequired }) => /* @__PURE__ */ jsxs(Fragment, { children: [
-			!!labelProp && !isSmall && /* @__PURE__ */ jsx(Label$1, {
-				className: clsx(styles.label, classNames?.label),
-				isDisabled,
-				isRequired,
-				children: labelProp
-			}),
-			/* @__PURE__ */ jsxs("div", {
-				className: clsx(styles.control, classNames?.control),
-				children: [/* @__PURE__ */ jsx(Input, {
-					...inputProps,
-					className: composeRenderProps(classNames?.input, (className) => clsx(styles.input, className))
-				}), /* @__PURE__ */ jsx(Button, {
-					className: composeRenderProps(classNames?.trigger, (className) => clsx(styles.trigger, className)),
-					children: /* @__PURE__ */ jsx(Icon, {
-						size: "small",
-						children: /* @__PURE__ */ jsx(ChevronDown, {})
+		children: ({ isDisabled, isInvalid, isRequired }) => {
+			const shouldShowDescription = !isReadOnly && !!descriptionProp && !(isSmall || isInvalid);
+			return /* @__PURE__ */ jsxs(Fragment, { children: [
+				!!labelProp && !isSmall && /* @__PURE__ */ jsx(Label$1, {
+					className: clsx(styles.label, classNames?.label),
+					isDisabled,
+					isRequired,
+					children: labelProp
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					className: clsx(styles.control, classNames?.control),
+					"data-readonly": isReadOnly || null,
+					children: [/* @__PURE__ */ jsx(Input, {
+						...inputProps,
+						tabIndex: isReadOnly ? -1 : 0,
+						className: composeRenderProps(classNames?.input, (className) => clsx(styles.input, className)),
+						title: inputProps?.value ? String(inputProps?.value) : ""
+					}), !isReadOnly && /* @__PURE__ */ jsx(Button, {
+						className: composeRenderProps(classNames?.trigger, (className) => clsx(styles.trigger, className)),
+						children: /* @__PURE__ */ jsx(Icon, {
+							size: "small",
+							children: /* @__PURE__ */ jsx(ChevronDown, {})
+						})
+					})]
+				}),
+				shouldShowDescription && /* @__PURE__ */ jsx(Text, {
+					className: clsx(styles.description, classNames?.description),
+					slot: "description",
+					children: descriptionProp
+				}),
+				/* @__PURE__ */ jsx(FieldError, {
+					className: composeRenderProps(classNames?.error, (className) => clsx(styles.error, className)),
+					children: errorMessage
+				}),
+				/* @__PURE__ */ jsx(Popover, {
+					className: composeRenderProps(classNames?.popover, (className) => clsx(styles.popover, className)),
+					children: /* @__PURE__ */ jsx(Virtualizer, {
+						layout: ListLayout,
+						layoutOptions,
+						children: /* @__PURE__ */ jsx(Options, { children })
 					})
-				})]
-			}),
-			!!descriptionProp && !(isSmall || isInvalid) && /* @__PURE__ */ jsx(Text, {
-				className: clsx(styles.description, classNames?.description),
-				slot: "description",
-				children: descriptionProp
-			}),
-			/* @__PURE__ */ jsx(FieldError, {
-				className: composeRenderProps(classNames?.error, (className) => clsx(styles.error, className)),
-				children: errorMessage
-			}),
-			/* @__PURE__ */ jsx(Popover, {
-				className: composeRenderProps(classNames?.popover, (className) => clsx(styles.popover, className)),
-				children: /* @__PURE__ */ jsx(Virtualizer, {
-					layout: ListLayout,
-					layoutOptions,
-					children: /* @__PURE__ */ jsx(Options, { children })
 				})
-			})
-		] })
+			] });
+		}
 	});
 }
 

package/dist/components/combobox-field/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Label"],"sources":["../../../src/components/combobox-field/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 { ChevronDown } from '@accelint/icons';\nimport 'client-only';\nimport { clsx } from '@accelint/design-foundation/lib/utils';\nimport {\n  Button,\n  ComboBox,\n  composeRenderProps,\n  FieldError,\n  Input,\n  ListLayout,\n  Popover,\n  Text,\n  useContextProps,\n  Virtualizer,\n} from 'react-aria-components';\nimport { Icon } from '../icon';\nimport { Label } from '../label';\nimport { Options } from '../options';\nimport { ComboBoxFieldContext } from './context';\nimport styles from './styles.module.css';\nimport type { OptionsDataItem } from '../options/types';\nimport type { ComboBoxFieldProps } from './types';\n\n/**\n * ComboBoxField - Accessible searchable combobox with dropdown options\n *\n * A combobox field that provides a searchable input with virtualized dropdown\n * options and support for sections, icons, and rich content.\n *\n * @example\n * <ComboBoxField defaultItems={items}>\n *   {(item) => <OptionsItem key={item.id} textValue={item.name}>{item.name}</OptionsItem>}\n * </ComboBoxField>\n */\nexport function ComboBoxField<T extends OptionsDataItem>({\n  ref,\n  ...props\n}: ComboBoxFieldProps<T>) {\n  [props, ref] = useContextProps(props, ref ?? null, ComboBoxFieldContext);\n\n  const {\n    children,\n    classNames,\n    description: descriptionProp,\n    errorMessage: errorMessageProp,\n    inputProps,\n    label: labelProp,\n    layoutOptions,\n    menuTrigger = 'focus',\n    size = 'medium',\n    isInvalid: isInvalidProp,\n    ...rest\n  } = props;\n  const errorMessage = errorMessageProp || null; // Protect against empty string\n  const isSmall = size === 'small';\n\n  return (\n    <ComboBox<T>\n      {...rest}\n      ref={ref}\n      className={composeRenderProps(classNames?.field, (className) =>\n        clsx('group/combobox-field', styles.field, className),\n      )}\n      menuTrigger={menuTrigger}\n      isInvalid={isInvalidProp || (errorMessage ? true : undefined)} // Leave uncontrolled if possible to fallback to validation state\n      data-size={size}\n    >\n      {(\n        { isDisabled, isInvalid, isRequired }, // Rely on internal state, not props, since state could differ from props\n      ) => (\n        <>\n          {!!labelProp && !isSmall && (\n            <Label\n              className={clsx(styles.label, classNames?.label)}\n              isDisabled={isDisabled}\n              isRequired={isRequired}\n            >\n              {labelProp}\n            </Label>\n          )}\n          <div className={clsx(styles.control, classNames?.control)}>\n            <Input\n              {...inputProps}\n              className={composeRenderProps(classNames?.input, (className) =>\n                clsx(styles.input, className),\n              )}\n            />\n            <Button\n              className={composeRenderProps(classNames?.trigger, (className) =>\n                clsx(styles.trigger, className),\n              )}\n            >\n              <Icon size='small'>\n                <ChevronDown />\n              </Icon>\n            </Button>\n          </div>\n          {!!descriptionProp && !(isSmall || isInvalid) && (\n            <Text\n              className={clsx(styles.description, classNames?.description)}\n              slot='description'\n            >\n              {descriptionProp}\n            </Text>\n          )}\n          <FieldError\n            className={composeRenderProps(classNames?.error, (className) =>\n              clsx(styles.error, className),\n            )}\n          >\n            {errorMessage}\n          </FieldError>\n          <Popover\n            className={composeRenderProps(classNames?.popover, (className) =>\n              clsx(styles.popover, className),\n            )}\n          >\n            <Virtualizer layout={ListLayout} layoutOptions={layoutOptions}>\n              <Options>{children}</Options>\n            </Virtualizer>\n          </Popover>\n        </>\n      )}\n    </ComboBox>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,SAAgB,cAAyC,EACvD,KACA,GAAG,SACqB;AACxB,EAAC,OAAO,OAAO,gBAAgB,OAAO,OAAO,MAAM,qBAAqB;CAExE,MAAM,EACJ,UACA,YACA,aAAa,iBACb,cAAc,kBACd,YACA,OAAO,WACP,eACA,cAAc,SACd,OAAO,UACP,WAAW,eACX,GAAG,SACD;CACJ,MAAM,eAAe,oBAAoB;CACzC,MAAM,UAAU,SAAS;AAEzB,QACE,oBAAC;EACC,GAAI;EACC;EACL,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,wBAAwB,OAAO,OAAO,UAAU,CACtD;EACY;EACb,WAAW,kBAAkB,eAAe,OAAO;EACnD,aAAW;aAGT,EAAE,YAAY,WAAW,iBAEzB;GACG,CAAC,CAAC,aAAa,CAAC,WACf,oBAACA;IACC,WAAW,KAAK,OAAO,OAAO,YAAY,MAAM;IACpC;IACA;cAEX;KACK;GAEV,qBAAC;IAAI,WAAW,KAAK,OAAO,SAAS,YAAY,QAAQ;eACvD,oBAAC;KACC,GAAI;KACJ,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,OAAO,OAAO,UAAU,CAC9B;MACD,EACF,oBAAC;KACC,WAAW,mBAAmB,YAAY,UAAU,cAClD,KAAK,OAAO,SAAS,UAAU,CAChC;eAED,oBAAC;MAAK,MAAK;gBACT,oBAAC,gBAAc;OACV;MACA;KACL;GACL,CAAC,CAAC,mBAAmB,EAAE,WAAW,cACjC,oBAAC;IACC,WAAW,KAAK,OAAO,aAAa,YAAY,YAAY;IAC5D,MAAK;cAEJ;KACI;GAET,oBAAC;IACC,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,OAAO,OAAO,UAAU,CAC9B;cAEA;KACU;GACb,oBAAC;IACC,WAAW,mBAAmB,YAAY,UAAU,cAClD,KAAK,OAAO,SAAS,UAAU,CAChC;cAED,oBAAC;KAAY,QAAQ;KAA2B;eAC9C,oBAAC,WAAS,WAAmB;MACjB;KACN;MACT;GAEI"}
+{"version":3,"file":"index.js","names":["Label"],"sources":["../../../src/components/combobox-field/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';\nimport 'client-only';\nimport { clsx } from '@accelint/design-foundation/lib/utils';\nimport ChevronDown from '@accelint/icons/chevron-down';\nimport {\n  Button,\n  ComboBox,\n  composeRenderProps,\n  FieldError,\n  Input,\n  ListLayout,\n  Popover,\n  Text,\n  useContextProps,\n  Virtualizer,\n} from 'react-aria-components';\nimport { Icon } from '../icon';\nimport { Label } from '../label';\nimport { Options } from '../options';\nimport { ComboBoxFieldContext } from './context';\nimport styles from './styles.module.css';\nimport type { OptionsDataItem } from '../options/types';\nimport type { ComboBoxFieldProps } from './types';\n\n/**\n * ComboBoxField - Accessible searchable combobox with dropdown options\n *\n * A combobox field that provides a searchable input with virtualized dropdown\n * options and support for sections, icons, and rich content.\n *\n * @param props - The combobox field props.\n * @param props.ref - Reference to the field element.\n * @param props.children - Render function for options.\n * @param props.classNames - Custom class names for sub-elements.\n * @param props.label - Label text displayed above the field.\n * @param props.description - Helper text displayed below the field.\n * @param props.errorMessage - Error message displayed when invalid.\n * @param props.size - Size variant of the field.\n * @returns The combobox field component.\n *\n * @example\n * ```tsx\n * <ComboBoxField defaultItems={items}>\n *   {(item) => <OptionsItem key={item.id} textValue={item.name}>{item.name}</OptionsItem>}\n * </ComboBoxField>\n * ```\n */\nexport function ComboBoxField<T extends OptionsDataItem>({\n  ref,\n  ...props\n}: ComboBoxFieldProps<T>) {\n  [props, ref] = useContextProps(props, ref ?? null, ComboBoxFieldContext);\n\n  const {\n    children,\n    classNames,\n    description: descriptionProp,\n    errorMessage: errorMessageProp,\n    inputProps,\n    label: labelProp,\n    layoutOptions,\n    menuTrigger = 'focus',\n    size = 'medium',\n    isInvalid: isInvalidProp,\n    isReadOnly = false,\n    ...rest\n  } = props;\n  const errorMessage = errorMessageProp || null; // Protect against empty string\n  const isSmall = size === 'small';\n\n  return (\n    <ComboBox<T>\n      {...rest}\n      ref={ref}\n      className={composeRenderProps(classNames?.field, (className) =>\n        clsx('group/combobox-field', styles.field, className),\n      )}\n      menuTrigger={menuTrigger}\n      isInvalid={isInvalidProp || (errorMessage ? true : undefined)} // Leave uncontrolled if possible to fallback to validation state\n      isReadOnly={isReadOnly}\n      data-size={size}\n    >\n      {(\n        { isDisabled, isInvalid, isRequired }, // Rely on internal state, not props, since state could differ from props\n      ) => {\n        const shouldShowDescription =\n          !isReadOnly && !!descriptionProp && !(isSmall || isInvalid);\n\n        return (\n          <>\n            {!!labelProp && !isSmall && (\n              <Label\n                className={clsx(styles.label, classNames?.label)}\n                isDisabled={isDisabled}\n                isRequired={isRequired}\n              >\n                {labelProp}\n              </Label>\n            )}\n            <div\n              className={clsx(styles.control, classNames?.control)}\n              data-readonly={isReadOnly || null}\n            >\n              <Input\n                {...inputProps}\n                tabIndex={isReadOnly ? -1 : 0}\n                className={composeRenderProps(classNames?.input, (className) =>\n                  clsx(styles.input, className),\n                )}\n                title={inputProps?.value ? String(inputProps?.value) : ''}\n              />\n              {!isReadOnly && (\n                <Button\n                  className={composeRenderProps(\n                    classNames?.trigger,\n                    (className) => clsx(styles.trigger, className),\n                  )}\n                >\n                  <Icon size='small'>\n                    <ChevronDown />\n                  </Icon>\n                </Button>\n              )}\n            </div>\n            {shouldShowDescription && (\n              <Text\n                className={clsx(styles.description, classNames?.description)}\n                slot='description'\n              >\n                {descriptionProp}\n              </Text>\n            )}\n            <FieldError\n              className={composeRenderProps(classNames?.error, (className) =>\n                clsx(styles.error, className),\n              )}\n            >\n              {errorMessage}\n            </FieldError>\n            <Popover\n              className={composeRenderProps(classNames?.popover, (className) =>\n                clsx(styles.popover, className),\n              )}\n            >\n              <Virtualizer layout={ListLayout} layoutOptions={layoutOptions}>\n                <Options>{children}</Options>\n              </Virtualizer>\n            </Popover>\n          </>\n        );\n      }}\n    </ComboBox>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,SAAgB,cAAyC,EACvD,KACA,GAAG,SACqB;AACxB,EAAC,OAAO,OAAO,gBAAgB,OAAO,OAAO,MAAM,qBAAqB;CAExE,MAAM,EACJ,UACA,YACA,aAAa,iBACb,cAAc,kBACd,YACA,OAAO,WACP,eACA,cAAc,SACd,OAAO,UACP,WAAW,eACX,aAAa,OACb,GAAG,SACD;CACJ,MAAM,eAAe,oBAAoB;CACzC,MAAM,UAAU,SAAS;AAEzB,QACE,oBAAC;EACC,GAAI;EACC;EACL,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,wBAAwB,OAAO,OAAO,UAAU,CACtD;EACY;EACb,WAAW,kBAAkB,eAAe,OAAO;EACvC;EACZ,aAAW;aAGT,EAAE,YAAY,WAAW,iBACtB;GACH,MAAM,wBACJ,CAAC,cAAc,CAAC,CAAC,mBAAmB,EAAE,WAAW;AAEnD,UACE;IACG,CAAC,CAAC,aAAa,CAAC,WACf,oBAACA;KACC,WAAW,KAAK,OAAO,OAAO,YAAY,MAAM;KACpC;KACA;eAEX;MACK;IAEV,qBAAC;KACC,WAAW,KAAK,OAAO,SAAS,YAAY,QAAQ;KACpD,iBAAe,cAAc;gBAE7B,oBAAC;MACC,GAAI;MACJ,UAAU,aAAa,KAAK;MAC5B,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,OAAO,OAAO,UAAU,CAC9B;MACD,OAAO,YAAY,QAAQ,OAAO,YAAY,MAAM,GAAG;OACvD,EACD,CAAC,cACA,oBAAC;MACC,WAAW,mBACT,YAAY,UACX,cAAc,KAAK,OAAO,SAAS,UAAU,CAC/C;gBAED,oBAAC;OAAK,MAAK;iBACT,oBAAC,gBAAc;QACV;OACA;MAEP;IACL,yBACC,oBAAC;KACC,WAAW,KAAK,OAAO,aAAa,YAAY,YAAY;KAC5D,MAAK;eAEJ;MACI;IAET,oBAAC;KACC,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,OAAO,OAAO,UAAU,CAC9B;eAEA;MACU;IACb,oBAAC;KACC,WAAW,mBAAmB,YAAY,UAAU,cAClD,KAAK,OAAO,SAAS,UAAU,CAChC;eAED,oBAAC;MAAY,QAAQ;MAA2B;gBAC9C,oBAAC,WAAS,WAAmB;OACjB;MACN;OACT;;GAGE"}

package/dist/components/combobox-field/styles.module.css

@@ -55,10 +55,14 @@
     @variant group-disabled/combobox-field {
       @apply fg-disabled outline-interactive-disabled;
     }
+
+    @variant read-only {
+      @apply px-0 outline-none;
+    }
   }
 
   .input {
-    @apply font-display grow outline-none;
+    @apply font-display grow overflow-hidden text-ellipsis whitespace-nowrap outline-none;
 
     @variant group-size-medium/combobox-field {
       @apply text-body-s;

package/dist/components/combobox-field/types.d.ts

@@ -16,21 +16,40 @@ import { RefAttributes } from "react";
 import { ComboBoxProps, FieldErrorProps, InputProps, LabelProps, ListLayoutOptions, PopoverProps, VirtualizerProps } from "react-aria-components";
 
 //#region src/components/combobox-field/types.d.ts
+/**
+ * Props for the ComboBoxField component.
+ *
+ * Extends ComboBox props with virtualization, styling, and field configuration.
+ */
 type ComboBoxFieldProps<T extends OptionsDataItem> = Omit<ComboBoxProps<T>, 'children' | 'className'> & Pick<VirtualizerProps<ListLayoutOptions>, 'layoutOptions'> & Pick<OptionsProps<T>, 'children'> & RefAttributes<HTMLDivElement> & {
+  /** Custom class names for sub-elements. */
   classNames?: {
+    /** Class name for the field container. */
     field?: ComboBoxProps<T>['className'];
+    /** Class name for the label. */
     label?: LabelProps['className'];
+    /** Class name for the control wrapper. */
     control?: string;
+    /** Class name for the input element. */
     input?: InputProps['className'];
+    /** Class name for the trigger button. */
     trigger?: ButtonProps$1['className'];
+    /** Class name for the description text. */
     description?: string;
+    /** Class name for the error message. */
     error?: FieldErrorProps['className'];
+    /** Class name for the popover dropdown. */
     popover?: PopoverProps['className'];
   };
+  /** Label text displayed above the field. */
   label?: string;
+  /** Additional props passed to the input element. */
   inputProps?: Omit<InputProps, 'className'>;
+  /** Helper text displayed below the field. */
   description?: string;
+  /** Error message displayed when invalid. */
   errorMessage?: string;
+  /** Size variant of the field. */
   size?: 'small' | 'medium';
 };
 //#endregion

package/dist/components/coordinate-field/context.d.ts

@@ -12,9 +12,9 @@
 
 import { ProviderProps } from "../../lib/types.js";
 import { CoordinateFieldProps, CoordinateFieldState } from "./types.js";
-import * as react41 from "react";
+import * as react14 from "react";
 import { ContextValue } from "react-aria-components";
-import * as react_jsx_runtime158 from "react/jsx-runtime";
+import * as react_jsx_runtime34 from "react/jsx-runtime";
 
 //#region src/components/coordinate-field/context.d.ts
 
@@ -48,7 +48,7 @@ import * as react_jsx_runtime158 from "react/jsx-runtime";
  *
  * @see CoordinateFieldStateContext for internal runtime state
  */
-declare const CoordinateFieldContext: react41.Context<ContextValue<CoordinateFieldProps, HTMLDivElement>>;
+declare const CoordinateFieldContext: react14.Context<ContextValue<CoordinateFieldProps, HTMLDivElement>>;
 /**
  * State Context for CoordinateField component.
  *
@@ -66,18 +66,27 @@ declare const CoordinateFieldContext: react41.Context<ContextValue<CoordinateFie
  * const state = useCoordinateFieldStateContext();
  * const { segmentValues, isDisabled, registerTimeout } = state;
  */
-declare const CoordinateFieldStateContext: react41.Context<CoordinateFieldState | null>;
+declare const CoordinateFieldStateContext: react14.Context<CoordinateFieldState | null>;
 /**
  * Provider component for CoordinateField context
  * Wraps children with CoordinateFieldContext
+ *
+ * @param props - The provider props.
+ * @param props.children - Child components that will receive the coordinate field context.
+ * @returns The coordinate field context provider wrapping children.
  */
 declare function CoordinateFieldProvider({
   children,
   ...props
-}: ProviderProps<CoordinateFieldProps>): react_jsx_runtime158.JSX.Element;
+}: ProviderProps<CoordinateFieldProps>): react_jsx_runtime34.JSX.Element;
 /**
  * Provider component for CoordinateField state context
  * Wraps children with CoordinateFieldStateContext
+ *
+ * @param props - The provider props.
+ * @param props.children - Child components that will receive the state context.
+ * @param props.value - The coordinate field state to provide.
+ * @returns The coordinate field state context provider wrapping children.
  */
 declare function CoordinateFieldStateProvider({
   children,
@@ -85,7 +94,7 @@ declare function CoordinateFieldStateProvider({
 }: {
   children: React.ReactNode;
   value: CoordinateFieldState;
-}): react_jsx_runtime158.JSX.Element;
+}): react_jsx_runtime34.JSX.Element;
 /**
  * Hook to access CoordinateField state context
  * Must be used within a CoordinateField component

package/dist/components/coordinate-field/context.js

@@ -69,6 +69,10 @@ const CoordinateFieldStateContext = createContext(null);
 /**
 * Provider component for CoordinateField context
 * Wraps children with CoordinateFieldContext
+*
+* @param props - The provider props.
+* @param props.children - Child components that will receive the coordinate field context.
+* @returns The coordinate field context provider wrapping children.
 */
 function CoordinateFieldProvider({ children, ...props }) {
 	return /* @__PURE__ */ jsx(CoordinateFieldContext.Provider, {
@@ -79,6 +83,11 @@ function CoordinateFieldProvider({ children, ...props }) {
 /**
 * Provider component for CoordinateField state context
 * Wraps children with CoordinateFieldStateContext
+*
+* @param props - The provider props.
+* @param props.children - Child components that will receive the state context.
+* @param props.value - The coordinate field state to provide.
+* @returns The coordinate field state context provider wrapping children.
 */
 function CoordinateFieldStateProvider({ children, value }) {
 	return /* @__PURE__ */ jsx(CoordinateFieldStateContext.Provider, {

package/dist/components/coordinate-field/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","names":[],"sources":["../../../src/components/coordinate-field/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\n'use client';\n\nimport { createContext, useContext } from 'react';\nimport type { ContextValue } from 'react-aria-components';\nimport type { ProviderProps } from '@/lib/types';\nimport type { CoordinateFieldProps, CoordinateFieldState } from './types';\n\n/**\n * CoordinateField Context Architecture\n *\n * This file defines two separate contexts following the React Aria component pattern:\n *\n * 1. CoordinateFieldContext (Props Context):\n *    - Contains user-provided props for the component\n *    - Used for React Aria's context-based prop merging\n *    - Part of the public composition API\n *\n * 2. CoordinateFieldStateContext (State Context):\n *    - Contains derived/computed runtime state\n *    - Used to share state with child components (e.g., CoordinateSegment)\n *    - Primarily for internal use\n\n * Separation keeps the public API (props) distinct from internal\n * implementation details (state), improving maintainability and composition.\n */\n\n/**\n * Props Context for CoordinateField component.\n *\n * Contains user-provided props (label, format, size, value, onChange, etc.)\n * and is used by React Aria's useContextProps hook for context-based prop merging.\n * This enables parent components to provide default props to nested CoordinateField\n * components, supporting composition patterns.\n *\n * Part of the public API - external consumers can use this for component composition.\n *\n * @see CoordinateFieldStateContext for internal runtime state\n */\nexport const CoordinateFieldContext =\n  createContext<ContextValue<CoordinateFieldProps, HTMLDivElement>>(null);\n\n/**\n * State Context for CoordinateField component.\n *\n * Contains derived/computed runtime state (segmentValues, currentValue,\n * validationErrors, registerTimeout, etc.) that is shared with child components\n * like CoordinateSegment. This avoids prop drilling for deeply nested children.\n *\n * This follows the React Aria pattern of separating props context (public API)\n * from state context (internal implementation). While exported for composition\n * scenarios and testing, this is primarily for internal use.\n *\n * @see CoordinateFieldContext for user-provided props\n * @example\n * // Used internally by child components\n * const state = useCoordinateFieldStateContext();\n * const { segmentValues, isDisabled, registerTimeout } = state;\n */\nexport const CoordinateFieldStateContext =\n  createContext<CoordinateFieldState | null>(null);\n\n/**\n * Provider component for CoordinateField context\n * Wraps children with CoordinateFieldContext\n */\nexport function CoordinateFieldProvider({\n  children,\n  ...props\n}: ProviderProps<CoordinateFieldProps>) {\n  return (\n    <CoordinateFieldContext.Provider value={props}>\n      {children}\n    </CoordinateFieldContext.Provider>\n  );\n}\n\n/**\n * Provider component for CoordinateField state context\n * Wraps children with CoordinateFieldStateContext\n */\nexport function CoordinateFieldStateProvider({\n  children,\n  value,\n}: {\n  children: React.ReactNode;\n  value: CoordinateFieldState;\n}) {\n  return (\n    <CoordinateFieldStateContext.Provider value={value}>\n      {children}\n    </CoordinateFieldStateContext.Provider>\n  );\n}\n\n/**\n * Hook to access CoordinateField state context\n * Must be used within a CoordinateField component\n * @throws {Error} If used outside of CoordinateField\n * @returns {CoordinateFieldState} The coordinate field state\n */\nexport const useCoordinateFieldStateContext = () => {\n  const context = useContext(CoordinateFieldStateContext);\n  if (!context) {\n    throw new Error(\n      'useCoordinateFieldStateContext must be used within CoordinateField',\n    );\n  }\n  return context;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,MAAa,yBACX,cAAkE,KAAK;;;;;;;;;;;;;;;;;;AAmBzE,MAAa,8BACX,cAA2C,KAAK;;;;;AAMlD,SAAgB,wBAAwB,EACtC,UACA,GAAG,SACmC;AACtC,QACE,oBAAC,uBAAuB;EAAS,OAAO;EACrC;GAC+B;;;;;;AAQtC,SAAgB,6BAA6B,EAC3C,UACA,SAIC;AACD,QACE,oBAAC,4BAA4B;EAAgB;EAC1C;GACoC;;;;;;;;AAU3C,MAAa,uCAAuC;CAClD,MAAM,UAAU,WAAW,4BAA4B;AACvD,KAAI,CAAC,QACH,OAAM,IAAI,MACR,qEACD;AAEH,QAAO"}
+{"version":3,"file":"context.js","names":[],"sources":["../../../src/components/coordinate-field/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\n'use client';\n\nimport { createContext, useContext } from 'react';\nimport type { ContextValue } from 'react-aria-components';\nimport type { ProviderProps } from '@/lib/types';\nimport type { CoordinateFieldProps, CoordinateFieldState } from './types';\n\n/**\n * CoordinateField Context Architecture\n *\n * This file defines two separate contexts following the React Aria component pattern:\n *\n * 1. CoordinateFieldContext (Props Context):\n *    - Contains user-provided props for the component\n *    - Used for React Aria's context-based prop merging\n *    - Part of the public composition API\n *\n * 2. CoordinateFieldStateContext (State Context):\n *    - Contains derived/computed runtime state\n *    - Used to share state with child components (e.g., CoordinateSegment)\n *    - Primarily for internal use\n\n * Separation keeps the public API (props) distinct from internal\n * implementation details (state), improving maintainability and composition.\n */\n\n/**\n * Props Context for CoordinateField component.\n *\n * Contains user-provided props (label, format, size, value, onChange, etc.)\n * and is used by React Aria's useContextProps hook for context-based prop merging.\n * This enables parent components to provide default props to nested CoordinateField\n * components, supporting composition patterns.\n *\n * Part of the public API - external consumers can use this for component composition.\n *\n * @see CoordinateFieldStateContext for internal runtime state\n */\nexport const CoordinateFieldContext =\n  createContext<ContextValue<CoordinateFieldProps, HTMLDivElement>>(null);\n\n/**\n * State Context for CoordinateField component.\n *\n * Contains derived/computed runtime state (segmentValues, currentValue,\n * validationErrors, registerTimeout, etc.) that is shared with child components\n * like CoordinateSegment. This avoids prop drilling for deeply nested children.\n *\n * This follows the React Aria pattern of separating props context (public API)\n * from state context (internal implementation). While exported for composition\n * scenarios and testing, this is primarily for internal use.\n *\n * @see CoordinateFieldContext for user-provided props\n * @example\n * // Used internally by child components\n * const state = useCoordinateFieldStateContext();\n * const { segmentValues, isDisabled, registerTimeout } = state;\n */\nexport const CoordinateFieldStateContext =\n  createContext<CoordinateFieldState | null>(null);\n\n/**\n * Provider component for CoordinateField context\n * Wraps children with CoordinateFieldContext\n *\n * @param props - The provider props.\n * @param props.children - Child components that will receive the coordinate field context.\n * @returns The coordinate field context provider wrapping children.\n */\nexport function CoordinateFieldProvider({\n  children,\n  ...props\n}: ProviderProps<CoordinateFieldProps>) {\n  return (\n    <CoordinateFieldContext.Provider value={props}>\n      {children}\n    </CoordinateFieldContext.Provider>\n  );\n}\n\n/**\n * Provider component for CoordinateField state context\n * Wraps children with CoordinateFieldStateContext\n *\n * @param props - The provider props.\n * @param props.children - Child components that will receive the state context.\n * @param props.value - The coordinate field state to provide.\n * @returns The coordinate field state context provider wrapping children.\n */\nexport function CoordinateFieldStateProvider({\n  children,\n  value,\n}: {\n  children: React.ReactNode;\n  value: CoordinateFieldState;\n}) {\n  return (\n    <CoordinateFieldStateContext.Provider value={value}>\n      {children}\n    </CoordinateFieldStateContext.Provider>\n  );\n}\n\n/**\n * Hook to access CoordinateField state context\n * Must be used within a CoordinateField component\n * @throws {Error} If used outside of CoordinateField\n * @returns {CoordinateFieldState} The coordinate field state\n */\nexport const useCoordinateFieldStateContext = () => {\n  const context = useContext(CoordinateFieldStateContext);\n  if (!context) {\n    throw new Error(\n      'useCoordinateFieldStateContext must be used within CoordinateField',\n    );\n  }\n  return context;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,MAAa,yBACX,cAAkE,KAAK;;;;;;;;;;;;;;;;;;AAmBzE,MAAa,8BACX,cAA2C,KAAK;;;;;;;;;AAUlD,SAAgB,wBAAwB,EACtC,UACA,GAAG,SACmC;AACtC,QACE,oBAAC,uBAAuB;EAAS,OAAO;EACrC;GAC+B;;;;;;;;;;;AAatC,SAAgB,6BAA6B,EAC3C,UACA,SAIC;AACD,QACE,oBAAC,4BAA4B;EAAgB;EAC1C;GACoC;;;;;;;;AAU3C,MAAa,uCAAuC;CAClD,MAAM,UAAU,WAAW,4BAA4B;AACvD,KAAI,CAAC,QACH,OAAM,IAAI,MACR,qEACD;AAEH,QAAO"}

package/dist/components/coordinate-field/coordinate-utils.d.ts

@@ -277,6 +277,11 @@ declare function isCompleteCoordinate(text: string): boolean;
 declare function parseCoordinatePaste(pastedText: string): ParsedCoordinateMatch[];
 /**
  * Check if two coordinates are equal within epsilon tolerance
+ *
+ * @param coord1 - First coordinate to compare.
+ * @param coord2 - Second coordinate to compare.
+ * @param epsilon - Tolerance for comparison (defaults to COORDINATE_EPSILON).
+ * @returns True if coordinates are equal within tolerance.
  */
 declare function areCoordinatesEqual(coord1: {
   lat: number;
@@ -287,6 +292,9 @@ declare function areCoordinatesEqual(coord1: {
 }, epsilon?: number): boolean;
 /**
  * Deduplicate coordinate matches by location, keeping first match for each unique location
+ *
+ * @param matches - Array of parsed coordinate matches to deduplicate.
+ * @returns Array of unique matches based on coordinate location.
  */
 declare function deduplicateMatchesByLocation(matches: ParsedCoordinateMatch[]): ParsedCoordinateMatch[];
 //#endregion

package/dist/components/coordinate-field/coordinate-utils.js

@@ -797,12 +797,20 @@ function parseCoordinatePaste(pastedText) {
 }
 /**
 * Check if two coordinates are equal within epsilon tolerance
+*
+* @param coord1 - First coordinate to compare.
+* @param coord2 - Second coordinate to compare.
+* @param epsilon - Tolerance for comparison (defaults to COORDINATE_EPSILON).
+* @returns True if coordinates are equal within tolerance.
 */
 function areCoordinatesEqual(coord1, coord2, epsilon = COORDINATE_EPSILON) {
 	return Math.abs(coord1.lat - coord2.lat) < epsilon && Math.abs(coord1.lon - coord2.lon) < epsilon;
 }
 /**
 * Deduplicate coordinate matches by location, keeping first match for each unique location
+*
+* @param matches - Array of parsed coordinate matches to deduplicate.
+* @returns Array of unique matches based on coordinate location.
 */
 function deduplicateMatchesByLocation(matches) {
 	const uniqueMatches = [];