@accelint/design-toolkit 9.2.0 → 9.4.0

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

@@ -30,7 +30,29 @@ import { jsx } from "react/jsx-runtime";
 * - Directional: "[NSEW]" - for DDM/DMS direction indicators
 * - Alphanumeric: "[0-9A-Z]" - for MGRS/UTM zone identifiers
 *
+* @param props - The coordinate segment props.
+* @param props.value - Current value of the segment.
+* @param props.onChange - Callback when the segment value changes.
+* @param props.onFocus - Callback when the segment gains focus.
+* @param props.onBlur - Callback when the segment loses focus.
+* @param props.onKeyDown - Callback for key down events.
+* @param props.placeholder - Placeholder text for the segment.
+* @param props.maxLength - Maximum character length for the segment.
+* @param props.className - Additional CSS class name.
+* @param props.isDisabled - Whether the segment is disabled.
+* @param props.isReadOnly - Whether the segment is read-only.
+* @param props.allowedChars - Regex pattern for allowed characters.
+* @param props.segmentRef - Ref for the segment input element.
+* @param props.segmentIndex - Index of this segment within the coordinate field.
+* @param props.totalSegments - Total number of segments in the coordinate field.
+* @param props.onAutoAdvance - Callback to advance focus to the next segment.
+* @param props.onAutoRetreat - Callback to retreat focus to the previous segment.
+* @param props.pad - Padding value for width calculation.
+* @param props.ariaLabel - Accessible label for the segment.
+* @returns The coordinate segment input component.
+*
 * @example
+* ```tsx
 * // Numeric segment (latitude degrees)
 * <CoordinateSegment
 *   value={latDegrees}
@@ -39,8 +61,10 @@ import { jsx } from "react/jsx-runtime";
 *   maxLength={10}
 *   placeholder="00.00000"
 * />
+* ```
 *
 * @example
+* ```tsx
 * // Directional segment (latitude direction)
 * <CoordinateSegment
 *   value={latDir}
@@ -49,8 +73,9 @@ import { jsx } from "react/jsx-runtime";
 *   maxLength={1}
 *   placeholder="N"
 * />
+* ```
 */
-function CoordinateSegment({ value, onChange, onFocus, onBlur, onKeyDown, placeholder, maxLength, className, isDisabled, allowedChars, segmentRef, segmentIndex, totalSegments: _totalSegments, onAutoAdvance, onAutoRetreat, pad, ariaLabel }) {
+function CoordinateSegment({ value, onChange, onFocus, onBlur, onKeyDown, placeholder, maxLength, className, isDisabled, isReadOnly, allowedChars, segmentRef, segmentIndex, totalSegments: _totalSegments, onAutoAdvance, onAutoRetreat, pad, ariaLabel }) {
 	const contextState = useCoordinateFieldStateContext();
 	const effectiveIsDisabled = contextState.isDisabled ?? isDisabled;
 	const dynamicWidth = useMemo(() => {
@@ -120,7 +145,9 @@ function CoordinateSegment({ value, onChange, onFocus, onBlur, onKeyDown, placeh
 		onBlur?.();
 	};
 	return /* @__PURE__ */ jsx("input", {
+		readOnly: isReadOnly,
 		ref: segmentRef,
+		tabIndex: isReadOnly ? -1 : 0,
 		type: "text",
 		value,
 		onChange: handleChange,

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

@@ -1 +1 @@
-{"version":3,"file":"segment.js","names":[],"sources":["../../../src/components/coordinate-field/segment.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 'client-only';\nimport { useMemo } from 'react';\nimport { useCoordinateFieldStateContext } from './context';\nimport type { ChangeEvent, FocusEvent, KeyboardEvent } from 'react';\nimport type { CoordinateSegmentProps } from './types';\n\n/**\n * CoordinateSegment - A controlled input component for a single coordinate segment\n *\n * This component represents one editable part of a coordinate (e.g., degrees, minutes, direction).\n * It handles character filtering, focus management, and keyboard navigation.\n *\n * Segment Types (determined by allowedChars):\n * - Numeric: \"[0-9\\\\-\\\\.]\" - for DD degrees, DDM/DMS degrees/minutes/seconds\n * - Directional: \"[NSEW]\" - for DDM/DMS direction indicators\n * - Alphanumeric: \"[0-9A-Z]\" - for MGRS/UTM zone identifiers\n *\n * @example\n * // Numeric segment (latitude degrees)\n * <CoordinateSegment\n *   value={latDegrees}\n *   onChange={setLatDegrees}\n *   allowedChars=\"[0-9\\\\-\\\\.]\"\n *   maxLength={10}\n *   placeholder=\"00.00000\"\n * />\n *\n * @example\n * // Directional segment (latitude direction)\n * <CoordinateSegment\n *   value={latDir}\n *   onChange={setLatDir}\n *   allowedChars=\"[NS]\"\n *   maxLength={1}\n *   placeholder=\"N\"\n * />\n */\nexport function CoordinateSegment({\n  value,\n  onChange,\n  onFocus,\n  onBlur,\n  onKeyDown,\n  placeholder,\n  maxLength,\n  className,\n  isDisabled,\n  allowedChars,\n  segmentRef,\n  segmentIndex,\n  totalSegments: _totalSegments,\n  onAutoAdvance,\n  onAutoRetreat,\n  pad,\n  ariaLabel,\n}: CoordinateSegmentProps) {\n  const contextState = useCoordinateFieldStateContext();\n\n  const effectiveIsDisabled = contextState.isDisabled ?? isDisabled;\n\n  // Calculate dynamic width based on focus state\n  const dynamicWidth = useMemo(() => {\n    if (maxLength === undefined) {\n      return undefined;\n    }\n\n    // Default padding to 0.5 if not specified\n    const padding = pad ?? 0.5;\n\n    // When blurred, use value length (or maxLength if empty) + padding\n    const contentLength = value.length > 0 ? value.length : maxLength;\n    return contentLength + padding;\n  }, [maxLength, pad, value.length]);\n\n  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {\n    const newValue = e.target.value;\n\n    if (allowedChars) {\n      const regex = new RegExp(`^${allowedChars}*$`);\n      if (!regex.test(newValue)) {\n        return;\n      }\n    }\n\n    if (maxLength && newValue.length > maxLength) {\n      return;\n    }\n\n    onChange(newValue);\n\n    if (maxLength && newValue.length === maxLength && onAutoAdvance) {\n      const timeoutId = setTimeout(() => {\n        onAutoAdvance();\n      }, 0);\n      contextState.registerTimeout(timeoutId);\n    }\n  };\n\n  const handlePaste = (e: React.ClipboardEvent<HTMLInputElement>) => {\n    const pastedText = e.clipboardData.getData('text');\n\n    if (allowedChars) {\n      const regex = new RegExp(`^${allowedChars}*$`);\n      if (!regex.test(pastedText)) {\n        e.preventDefault();\n        return;\n      }\n    }\n\n    if (maxLength && pastedText.length > maxLength) {\n      e.preventDefault();\n      onChange(pastedText.slice(0, maxLength));\n      return;\n    }\n  };\n\n  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {\n    const input = e.currentTarget;\n    const cursorAtStart = input.selectionStart === 0;\n    const cursorAtEnd = input.selectionStart === value.length;\n    const isEmpty = value.length === 0;\n\n    if (e.key === 'Backspace' && isEmpty && onAutoRetreat) {\n      e.preventDefault();\n      onAutoRetreat();\n      return;\n    }\n\n    if (e.key === 'ArrowLeft' && cursorAtStart && onAutoRetreat) {\n      e.preventDefault();\n      onAutoRetreat();\n      return;\n    }\n\n    if (e.key === 'ArrowRight' && cursorAtEnd && onAutoAdvance) {\n      e.preventDefault();\n      onAutoAdvance();\n      return;\n    }\n\n    onKeyDown?.(e);\n  };\n\n  const handleFocus = (e: FocusEvent<HTMLInputElement>) => {\n    e.target.select();\n    onFocus?.();\n  };\n\n  const handleBlur = () => {\n    onBlur?.();\n  };\n\n  return (\n    <input\n      ref={segmentRef}\n      type='text'\n      value={value}\n      onChange={handleChange}\n      onPaste={handlePaste}\n      onKeyDown={handleKeyDown}\n      onFocus={handleFocus}\n      onBlur={handleBlur}\n      placeholder={placeholder}\n      maxLength={maxLength}\n      className={className}\n      disabled={effectiveIsDisabled}\n      style={dynamicWidth ? { width: `${dynamicWidth}ch` } : undefined}\n      aria-label={\n        ariaLabel ||\n        `Coordinate segment ${segmentIndex !== undefined ? segmentIndex + 1 : ''}`\n      }\n      aria-disabled={effectiveIsDisabled}\n      autoComplete='off'\n      inputMode={\n        allowedChars?.includes('0-9')\n          ? allowedChars.includes('\\\\-\\\\.')\n            ? 'decimal'\n            : 'numeric'\n          : 'text'\n      }\n    />\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,kBAAkB,EAChC,OACA,UACA,SACA,QACA,WACA,aACA,WACA,WACA,YACA,cACA,YACA,cACA,eAAe,gBACf,eACA,eACA,KACA,aACyB;CACzB,MAAM,eAAe,gCAAgC;CAErD,MAAM,sBAAsB,aAAa,cAAc;CAGvD,MAAM,eAAe,cAAc;AACjC,MAAI,cAAc,OAChB;EAIF,MAAM,UAAU,OAAO;AAIvB,UADsB,MAAM,SAAS,IAAI,MAAM,SAAS,aACjC;IACtB;EAAC;EAAW;EAAK,MAAM;EAAO,CAAC;CAElC,MAAM,gBAAgB,MAAqC;EACzD,MAAM,WAAW,EAAE,OAAO;AAE1B,MAAI,cAEF;OAAI,kBADU,IAAI,OAAO,IAAI,aAAa,IAAI,EACnC,KAAK,SAAS,CACvB;;AAIJ,MAAI,aAAa,SAAS,SAAS,UACjC;AAGF,WAAS,SAAS;AAElB,MAAI,aAAa,SAAS,WAAW,aAAa,eAAe;GAC/D,MAAM,YAAY,iBAAiB;AACjC,mBAAe;MACd,EAAE;AACL,gBAAa,gBAAgB,UAAU;;;CAI3C,MAAM,eAAe,MAA8C;EACjE,MAAM,aAAa,EAAE,cAAc,QAAQ,OAAO;AAElD,MAAI,cAEF;OAAI,kBADU,IAAI,OAAO,IAAI,aAAa,IAAI,EACnC,KAAK,WAAW,EAAE;AAC3B,MAAE,gBAAgB;AAClB;;;AAIJ,MAAI,aAAa,WAAW,SAAS,WAAW;AAC9C,KAAE,gBAAgB;AAClB,YAAS,WAAW,MAAM,GAAG,UAAU,CAAC;AACxC;;;CAIJ,MAAM,iBAAiB,MAAuC;EAC5D,MAAM,QAAQ,EAAE;EAChB,MAAM,gBAAgB,MAAM,mBAAmB;EAC/C,MAAM,cAAc,MAAM,mBAAmB,MAAM;EACnD,MAAM,UAAU,MAAM,WAAW;AAEjC,MAAI,EAAE,QAAQ,eAAe,WAAW,eAAe;AACrD,KAAE,gBAAgB;AAClB,kBAAe;AACf;;AAGF,MAAI,EAAE,QAAQ,eAAe,iBAAiB,eAAe;AAC3D,KAAE,gBAAgB;AAClB,kBAAe;AACf;;AAGF,MAAI,EAAE,QAAQ,gBAAgB,eAAe,eAAe;AAC1D,KAAE,gBAAgB;AAClB,kBAAe;AACf;;AAGF,cAAY,EAAE;;CAGhB,MAAM,eAAe,MAAoC;AACvD,IAAE,OAAO,QAAQ;AACjB,aAAW;;CAGb,MAAM,mBAAmB;AACvB,YAAU;;AAGZ,QACE,oBAAC;EACC,KAAK;EACL,MAAK;EACE;EACP,UAAU;EACV,SAAS;EACT,WAAW;EACX,SAAS;EACT,QAAQ;EACK;EACF;EACA;EACX,UAAU;EACV,OAAO,eAAe,EAAE,OAAO,GAAG,aAAa,KAAK,GAAG;EACvD,cACE,aACA,sBAAsB,iBAAiB,SAAY,eAAe,IAAI;EAExE,iBAAe;EACf,cAAa;EACb,WACE,cAAc,SAAS,MAAM,GACzB,aAAa,SAAS,SAAS,GAC7B,YACA,YACF;GAEN"}
+{"version":3,"file":"segment.js","names":[],"sources":["../../../src/components/coordinate-field/segment.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 'client-only';\nimport { useMemo } from 'react';\nimport { useCoordinateFieldStateContext } from './context';\nimport type { ChangeEvent, FocusEvent, KeyboardEvent } from 'react';\nimport type { CoordinateSegmentProps } from './types';\n\n/**\n * CoordinateSegment - A controlled input component for a single coordinate segment\n *\n * This component represents one editable part of a coordinate (e.g., degrees, minutes, direction).\n * It handles character filtering, focus management, and keyboard navigation.\n *\n * Segment Types (determined by allowedChars):\n * - Numeric: \"[0-9\\\\-\\\\.]\" - for DD degrees, DDM/DMS degrees/minutes/seconds\n * - Directional: \"[NSEW]\" - for DDM/DMS direction indicators\n * - Alphanumeric: \"[0-9A-Z]\" - for MGRS/UTM zone identifiers\n *\n * @param props - The coordinate segment props.\n * @param props.value - Current value of the segment.\n * @param props.onChange - Callback when the segment value changes.\n * @param props.onFocus - Callback when the segment gains focus.\n * @param props.onBlur - Callback when the segment loses focus.\n * @param props.onKeyDown - Callback for key down events.\n * @param props.placeholder - Placeholder text for the segment.\n * @param props.maxLength - Maximum character length for the segment.\n * @param props.className - Additional CSS class name.\n * @param props.isDisabled - Whether the segment is disabled.\n * @param props.isReadOnly - Whether the segment is read-only.\n * @param props.allowedChars - Regex pattern for allowed characters.\n * @param props.segmentRef - Ref for the segment input element.\n * @param props.segmentIndex - Index of this segment within the coordinate field.\n * @param props.totalSegments - Total number of segments in the coordinate field.\n * @param props.onAutoAdvance - Callback to advance focus to the next segment.\n * @param props.onAutoRetreat - Callback to retreat focus to the previous segment.\n * @param props.pad - Padding value for width calculation.\n * @param props.ariaLabel - Accessible label for the segment.\n * @returns The coordinate segment input component.\n *\n * @example\n * ```tsx\n * // Numeric segment (latitude degrees)\n * <CoordinateSegment\n *   value={latDegrees}\n *   onChange={setLatDegrees}\n *   allowedChars=\"[0-9\\\\-\\\\.]\"\n *   maxLength={10}\n *   placeholder=\"00.00000\"\n * />\n * ```\n *\n * @example\n * ```tsx\n * // Directional segment (latitude direction)\n * <CoordinateSegment\n *   value={latDir}\n *   onChange={setLatDir}\n *   allowedChars=\"[NS]\"\n *   maxLength={1}\n *   placeholder=\"N\"\n * />\n * ```\n */\nexport function CoordinateSegment({\n  value,\n  onChange,\n  onFocus,\n  onBlur,\n  onKeyDown,\n  placeholder,\n  maxLength,\n  className,\n  isDisabled,\n  isReadOnly,\n  allowedChars,\n  segmentRef,\n  segmentIndex,\n  totalSegments: _totalSegments,\n  onAutoAdvance,\n  onAutoRetreat,\n  pad,\n  ariaLabel,\n}: CoordinateSegmentProps) {\n  const contextState = useCoordinateFieldStateContext();\n\n  const effectiveIsDisabled = contextState.isDisabled ?? isDisabled;\n\n  // Calculate dynamic width based on focus state\n  const dynamicWidth = useMemo(() => {\n    if (maxLength === undefined) {\n      return undefined;\n    }\n\n    // Default padding to 0.5 if not specified\n    const padding = pad ?? 0.5;\n\n    // When blurred, use value length (or maxLength if empty) + padding\n    const contentLength = value.length > 0 ? value.length : maxLength;\n    return contentLength + padding;\n  }, [maxLength, pad, value.length]);\n\n  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {\n    const newValue = e.target.value;\n\n    if (allowedChars) {\n      const regex = new RegExp(`^${allowedChars}*$`);\n      if (!regex.test(newValue)) {\n        return;\n      }\n    }\n\n    if (maxLength && newValue.length > maxLength) {\n      return;\n    }\n\n    onChange(newValue);\n\n    if (maxLength && newValue.length === maxLength && onAutoAdvance) {\n      const timeoutId = setTimeout(() => {\n        onAutoAdvance();\n      }, 0);\n      contextState.registerTimeout(timeoutId);\n    }\n  };\n\n  const handlePaste = (e: React.ClipboardEvent<HTMLInputElement>) => {\n    const pastedText = e.clipboardData.getData('text');\n\n    if (allowedChars) {\n      const regex = new RegExp(`^${allowedChars}*$`);\n      if (!regex.test(pastedText)) {\n        e.preventDefault();\n        return;\n      }\n    }\n\n    if (maxLength && pastedText.length > maxLength) {\n      e.preventDefault();\n      onChange(pastedText.slice(0, maxLength));\n      return;\n    }\n  };\n\n  const handleKeyDown = (e: KeyboardEvent<HTMLInputElement>) => {\n    const input = e.currentTarget;\n    const cursorAtStart = input.selectionStart === 0;\n    const cursorAtEnd = input.selectionStart === value.length;\n    const isEmpty = value.length === 0;\n\n    if (e.key === 'Backspace' && isEmpty && onAutoRetreat) {\n      e.preventDefault();\n      onAutoRetreat();\n      return;\n    }\n\n    if (e.key === 'ArrowLeft' && cursorAtStart && onAutoRetreat) {\n      e.preventDefault();\n      onAutoRetreat();\n      return;\n    }\n\n    if (e.key === 'ArrowRight' && cursorAtEnd && onAutoAdvance) {\n      e.preventDefault();\n      onAutoAdvance();\n      return;\n    }\n\n    onKeyDown?.(e);\n  };\n\n  const handleFocus = (e: FocusEvent<HTMLInputElement>) => {\n    e.target.select();\n    onFocus?.();\n  };\n\n  const handleBlur = () => {\n    onBlur?.();\n  };\n\n  return (\n    <input\n      readOnly={isReadOnly}\n      ref={segmentRef}\n      tabIndex={isReadOnly ? -1 : 0}\n      type='text'\n      value={value}\n      onChange={handleChange}\n      onPaste={handlePaste}\n      onKeyDown={handleKeyDown}\n      onFocus={handleFocus}\n      onBlur={handleBlur}\n      placeholder={placeholder}\n      maxLength={maxLength}\n      className={className}\n      disabled={effectiveIsDisabled}\n      style={dynamicWidth ? { width: `${dynamicWidth}ch` } : undefined}\n      aria-label={\n        ariaLabel ||\n        `Coordinate segment ${segmentIndex !== undefined ? segmentIndex + 1 : ''}`\n      }\n      aria-disabled={effectiveIsDisabled}\n      autoComplete='off'\n      inputMode={\n        allowedChars?.includes('0-9')\n          ? allowedChars.includes('\\\\-\\\\.')\n            ? 'decimal'\n            : 'numeric'\n          : 'text'\n      }\n    />\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4EA,SAAgB,kBAAkB,EAChC,OACA,UACA,SACA,QACA,WACA,aACA,WACA,WACA,YACA,YACA,cACA,YACA,cACA,eAAe,gBACf,eACA,eACA,KACA,aACyB;CACzB,MAAM,eAAe,gCAAgC;CAErD,MAAM,sBAAsB,aAAa,cAAc;CAGvD,MAAM,eAAe,cAAc;AACjC,MAAI,cAAc,OAChB;EAIF,MAAM,UAAU,OAAO;AAIvB,UADsB,MAAM,SAAS,IAAI,MAAM,SAAS,aACjC;IACtB;EAAC;EAAW;EAAK,MAAM;EAAO,CAAC;CAElC,MAAM,gBAAgB,MAAqC;EACzD,MAAM,WAAW,EAAE,OAAO;AAE1B,MAAI,cAEF;OAAI,kBADU,IAAI,OAAO,IAAI,aAAa,IAAI,EACnC,KAAK,SAAS,CACvB;;AAIJ,MAAI,aAAa,SAAS,SAAS,UACjC;AAGF,WAAS,SAAS;AAElB,MAAI,aAAa,SAAS,WAAW,aAAa,eAAe;GAC/D,MAAM,YAAY,iBAAiB;AACjC,mBAAe;MACd,EAAE;AACL,gBAAa,gBAAgB,UAAU;;;CAI3C,MAAM,eAAe,MAA8C;EACjE,MAAM,aAAa,EAAE,cAAc,QAAQ,OAAO;AAElD,MAAI,cAEF;OAAI,kBADU,IAAI,OAAO,IAAI,aAAa,IAAI,EACnC,KAAK,WAAW,EAAE;AAC3B,MAAE,gBAAgB;AAClB;;;AAIJ,MAAI,aAAa,WAAW,SAAS,WAAW;AAC9C,KAAE,gBAAgB;AAClB,YAAS,WAAW,MAAM,GAAG,UAAU,CAAC;AACxC;;;CAIJ,MAAM,iBAAiB,MAAuC;EAC5D,MAAM,QAAQ,EAAE;EAChB,MAAM,gBAAgB,MAAM,mBAAmB;EAC/C,MAAM,cAAc,MAAM,mBAAmB,MAAM;EACnD,MAAM,UAAU,MAAM,WAAW;AAEjC,MAAI,EAAE,QAAQ,eAAe,WAAW,eAAe;AACrD,KAAE,gBAAgB;AAClB,kBAAe;AACf;;AAGF,MAAI,EAAE,QAAQ,eAAe,iBAAiB,eAAe;AAC3D,KAAE,gBAAgB;AAClB,kBAAe;AACf;;AAGF,MAAI,EAAE,QAAQ,gBAAgB,eAAe,eAAe;AAC1D,KAAE,gBAAgB;AAClB,kBAAe;AACf;;AAGF,cAAY,EAAE;;CAGhB,MAAM,eAAe,MAAoC;AACvD,IAAE,OAAO,QAAQ;AACjB,aAAW;;CAGb,MAAM,mBAAmB;AACvB,YAAU;;AAGZ,QACE,oBAAC;EACC,UAAU;EACV,KAAK;EACL,UAAU,aAAa,KAAK;EAC5B,MAAK;EACE;EACP,UAAU;EACV,SAAS;EACT,WAAW;EACX,SAAS;EACT,QAAQ;EACK;EACF;EACA;EACX,UAAU;EACV,OAAO,eAAe,EAAE,OAAO,GAAG,aAAa,KAAK,GAAG;EACvD,cACE,aACA,sBAAsB,iBAAiB,SAAY,eAAe,IAAI;EAExE,iBAAe;EACf,cAAa;EACb,WACE,cAAc,SAAS,MAAM,GACzB,aAAa,SAAS,SAAS,GAC7B,YACA,YACF;GAEN"}

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

@@ -18,7 +18,7 @@
   }
 
   .control {
-    @apply fg-primary-bold gap-m rounded-medium px-s py-xs font-display outline-interactive flex w-full items-center outline;
+    @apply fg-primary-bold gap-m rounded-medium pl-s pr-xs py-xs font-display outline-interactive flex w-full items-center outline;
 
     min-width: var(--min-width, unset);
 
@@ -41,6 +41,10 @@
     @variant hover {
       @apply outline-interactive-hover;
     }
+
+    @variant read-only {
+      @apply px-0 outline-none;
+    }
   }
 
   .input {
@@ -73,6 +77,16 @@
     @variant selection {
       @apply fg-a11y-on-accent bg-accent-primary-bold;
     }
+
+    @variant read-only {
+      @variant focus-visible {
+        @apply bg-surface-default;
+      }
+
+      @variant selection {
+        @apply bg-surface-default;
+      }
+    }
   }
 
   .segmentGroup {
@@ -148,4 +162,8 @@
   .popoverTitle {
     @apply fg-primary-muted text-header-s;
   }
+
+  .hiddenTrigger {
+    @apply hidden;
+  }
 }

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

@@ -117,6 +117,8 @@ type CoordinateSegmentProps = {
   className?: string;
   /** Whether the segment is disabled */
   isDisabled?: boolean;
+  /** Whether the segment is read-only */
+  isReadOnly?: boolean;
   /** Regex pattern for allowed characters (e.g., "[0-9\\-\\.]" for numeric, "[NSEW]" for directional) */
   allowedChars?: string;
   /** Ref to the input element for programmatic focus management */

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

@@ -1 +1 @@
-{"version":3,"file":"types.js","names":["COORDINATE_FORMAT_LABELS: Record<CoordinateSystem, string>","COORDINATE_FORMAT_NAMES: Record<CoordinateSystem, string>","COORDINATE_SYSTEMS: readonly CoordinateSystem[]"],"sources":["../../../src/components/coordinate-field/types.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport type {\n  Dispatch,\n  KeyboardEvent,\n  RefAttributes,\n  SetStateAction,\n} from 'react';\nimport type {\n  TextFieldProps as AriaTextFieldProps,\n  FieldErrorProps,\n  LabelProps,\n} from 'react-aria-components';\n\n/**\n * Supported coordinate systems for display and input\n */\nexport type CoordinateSystem = 'dd' | 'ddm' | 'dms' | 'mgrs' | 'utm';\n\n/**\n * Short labels for coordinate formats (used in popover)\n */\nexport const COORDINATE_FORMAT_LABELS: Record<CoordinateSystem, string> = {\n  dd: 'DD',\n  ddm: 'DDM',\n  dms: 'DMS',\n  mgrs: 'MGRS',\n  utm: 'UTM',\n};\n\n/**\n * Full names for coordinate formats (used in popover titles/descriptions)\n */\nexport const COORDINATE_FORMAT_NAMES: Record<CoordinateSystem, string> = {\n  dd: 'Decimal Degrees',\n  ddm: 'Degrees Decimal Minutes',\n  dms: 'Degrees Minutes Seconds',\n  mgrs: 'Military Grid Reference System',\n  utm: 'Universal Transverse Mercator',\n};\n\n/**\n * All supported coordinate systems\n * Use this constant instead of hardcoding the array in multiple places\n */\nexport const COORDINATE_SYSTEMS: readonly CoordinateSystem[] = [\n  'dd',\n  'dms',\n  'ddm',\n  'mgrs',\n  'utm',\n] as const;\n\n/**\n * Coordinate value in Decimal Degrees format (internal representation)\n * All coordinate values are normalized to this format internally\n */\nexport type CoordinateValue = {\n  lat: number; // Latitude in decimal degrees (-90 to 90)\n  lon: number; // Longitude in decimal degrees (-180 to 180)\n};\n\n/**\n * Types of segments in a coordinate input\n */\nexport type SegmentType =\n  | 'numeric'\n  | 'directional'\n  | 'literal'\n  | 'alphanumeric';\n\n/**\n * Configuration for a single coordinate segment\n */\nexport type SegmentConfig = {\n  type: SegmentType;\n  /** Placeholder text shown when segment is empty */\n  placeholder?: string;\n  /** Maximum character length for the segment */\n  maxLength?: number;\n  /** Regex pattern for allowed characters */\n  allowedChars?: string;\n  /** Fixed value for literal segments (e.g., \", \" or \"º\") */\n  value?: string;\n  /** Padding in CSS 'ch' units to add to the segment width (defaults to 0.5 if not specified) */\n  pad?: number;\n};\n\n/**\n * Result of parsing a pasted coordinate string\n */\nexport type ParsedCoordinateMatch = {\n  /** The coordinate system format that matched */\n  format: CoordinateSystem;\n  /** The coordinate value in DD format */\n  value: CoordinateValue;\n  /** Display string in the matched format */\n  displayString: string;\n};\n\n/**\n * State shared with child components through context\n */\nexport type CoordinateFieldState = {\n  segmentValues: string[];\n  format: CoordinateFieldProps['format'];\n  /**\n   * Current coordinate value in DD format\n   * - undefined: uncontrolled mode with no default value\n   * - null: controlled mode with empty/invalid value\n   * - CoordinateValue: valid coordinate\n   */\n  currentValue?: CoordinateValue | null;\n  /** Validation errors from @accelint/geo */\n  validationErrors: string[];\n  isDisabled: boolean;\n  isInvalid: boolean;\n  isRequired: boolean;\n  /** Size variant of the field */\n  size: CoordinateFieldProps['size'];\n  /** Whether or not the logical coordinate fields are inlined or stacked */\n  variant: CoordinateFieldProps['variant'];\n  /** Function to register timeouts for cleanup on unmount */\n  registerTimeout: (timeoutId: NodeJS.Timeout) => void;\n};\n\n/**\n * Props for the CoordinateSegment component\n */\nexport type CoordinateSegmentProps = {\n  /** Current value of the segment */\n  value: string;\n  /** Callback when the segment value changes */\n  onChange: (value: string) => void;\n  /** Callback when the segment receives focus */\n  onFocus?: () => void;\n  /** Callback when the segment loses focus */\n  onBlur?: () => void;\n  /** Callback for keyboard events (used for navigation between segments) */\n  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;\n  /** Placeholder text to display when segment is empty */\n  placeholder?: string;\n  /** Maximum character length for the segment */\n  maxLength?: number;\n  /** Custom className for styling */\n  className?: string;\n  /** Whether the segment is disabled */\n  isDisabled?: boolean;\n  /** Regex pattern for allowed characters (e.g., \"[0-9\\\\-\\\\.]\" for numeric, \"[NSEW]\" for directional) */\n  allowedChars?: string;\n  /** Ref to the input element for programmatic focus management */\n  segmentRef?: React.RefObject<HTMLInputElement>;\n  /** Index of this segment in the parent field (for accessibility) */\n  segmentIndex?: number;\n  /** Total number of segments (for accessibility) */\n  totalSegments?: number;\n  /** Callback to trigger auto-advance to next segment */\n  onAutoAdvance?: () => void;\n  /** Callback to trigger auto-retreat to previous segment */\n  onAutoRetreat?: () => void;\n  /** Padding in CSS 'ch' units to add to the segment width (defaults to 0.5 if not specified) */\n  pad?: number;\n  /** Semantic accessibility label for the segment (e.g., \"Latitude degrees\") */\n  ariaLabel?: string;\n};\n\n/**\n * Props for the CoordinateField component\n *\n * Extends AriaTextFieldProps to inherit standard form field props (id, isDisabled, isRequired, etc.)\n */\nexport type CoordinateFieldProps = Omit<\n  AriaTextFieldProps,\n  | 'children'\n  | 'className'\n  | 'placeholder'\n  | 'type'\n  | 'pattern'\n  | 'value'\n  | 'defaultValue'\n  | 'onChange'\n  | 'name' // Not applicable to multi-segment fields\n> &\n  RefAttributes<HTMLDivElement> & {\n    /**\n     * Custom class names for component slots\n     */\n    classNames?: {\n      field?: string;\n      label?: LabelProps['className'];\n      control?: string;\n      input?: string;\n      segment?: string;\n      description?: string;\n      error?: FieldErrorProps['className'];\n      formatButton?: string;\n    };\n\n    /**\n     * Label text displayed above the input (medium size only)\n     */\n    label?: string;\n\n    /**\n     * Helper text displayed below the input\n     */\n    description?: string;\n\n    /**\n     * Error message to display when the field is invalid\n     */\n    errorMessage?: string;\n\n    /**\n     * Display format for coordinate input\n     * @default 'dd' (Decimal Degrees)\n     */\n    format?: CoordinateSystem;\n\n    /**\n     * Size variant of the field\n     * @default 'medium'\n     */\n    size?: 'small' | 'medium';\n\n    /**\n     * Whether to show the format button for copying coordinates in different formats\n     * @default true\n     */\n    showFormatButton?: boolean;\n\n    /**\n     * Controlled value in Decimal Degrees format\n     * - undefined: uncontrolled mode\n     * - null: controlled mode with no/invalid value\n     * - CoordinateValue: controlled mode with valid value\n     */\n    value?: CoordinateValue | null;\n\n    /**\n     * Whether or not the input is stacked or inline\n     * @default 'inline'\n     */\n    variant?: 'inline' | 'stacked';\n\n    /**\n     * Default uncontrolled value in Decimal Degrees format\n     */\n    defaultValue?: CoordinateValue;\n\n    /**\n     * Callback fired when the coordinate value changes\n     * @param value - The new coordinate value in DD format, or null if invalid\n     */\n    onChange?:\n      | Dispatch<SetStateAction<CoordinateValue | null>>\n      | ((value: CoordinateValue | null) => void);\n\n    /**\n     * Callback fired when validation or paste errors occur\n     * @param message - Error message (\"Invalid coordinate value\" for validation errors, \"Invalid coordinate format\" for paste errors)\n     * @param context - Additional context about the error:\n     *   - Validation errors: `{ errors: string[], format: string, segments: string[] }`\n     *   - Paste errors: `{ pastedText: string }`\n     */\n    onError?: (message: string, context?: Record<string, unknown>) => void;\n  };\n"],"mappings":";;;;;;;;;;;;;;;;;AAgCA,MAAaA,2BAA6D;CACxE,IAAI;CACJ,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACN;;;;AAKD,MAAaC,0BAA4D;CACvE,IAAI;CACJ,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACN;;;;;AAMD,MAAaC,qBAAkD;CAC7D;CACA;CACA;CACA;CACA;CACD"}
+{"version":3,"file":"types.js","names":["COORDINATE_FORMAT_LABELS: Record<CoordinateSystem, string>","COORDINATE_FORMAT_NAMES: Record<CoordinateSystem, string>","COORDINATE_SYSTEMS: readonly CoordinateSystem[]"],"sources":["../../../src/components/coordinate-field/types.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport type {\n  Dispatch,\n  KeyboardEvent,\n  RefAttributes,\n  SetStateAction,\n} from 'react';\nimport type {\n  TextFieldProps as AriaTextFieldProps,\n  FieldErrorProps,\n  LabelProps,\n} from 'react-aria-components';\n\n/**\n * Supported coordinate systems for display and input\n */\nexport type CoordinateSystem = 'dd' | 'ddm' | 'dms' | 'mgrs' | 'utm';\n\n/**\n * Short labels for coordinate formats (used in popover)\n */\nexport const COORDINATE_FORMAT_LABELS: Record<CoordinateSystem, string> = {\n  dd: 'DD',\n  ddm: 'DDM',\n  dms: 'DMS',\n  mgrs: 'MGRS',\n  utm: 'UTM',\n};\n\n/**\n * Full names for coordinate formats (used in popover titles/descriptions)\n */\nexport const COORDINATE_FORMAT_NAMES: Record<CoordinateSystem, string> = {\n  dd: 'Decimal Degrees',\n  ddm: 'Degrees Decimal Minutes',\n  dms: 'Degrees Minutes Seconds',\n  mgrs: 'Military Grid Reference System',\n  utm: 'Universal Transverse Mercator',\n};\n\n/**\n * All supported coordinate systems\n * Use this constant instead of hardcoding the array in multiple places\n */\nexport const COORDINATE_SYSTEMS: readonly CoordinateSystem[] = [\n  'dd',\n  'dms',\n  'ddm',\n  'mgrs',\n  'utm',\n] as const;\n\n/**\n * Coordinate value in Decimal Degrees format (internal representation)\n * All coordinate values are normalized to this format internally\n */\nexport type CoordinateValue = {\n  lat: number; // Latitude in decimal degrees (-90 to 90)\n  lon: number; // Longitude in decimal degrees (-180 to 180)\n};\n\n/**\n * Types of segments in a coordinate input\n */\nexport type SegmentType =\n  | 'numeric'\n  | 'directional'\n  | 'literal'\n  | 'alphanumeric';\n\n/**\n * Configuration for a single coordinate segment\n */\nexport type SegmentConfig = {\n  type: SegmentType;\n  /** Placeholder text shown when segment is empty */\n  placeholder?: string;\n  /** Maximum character length for the segment */\n  maxLength?: number;\n  /** Regex pattern for allowed characters */\n  allowedChars?: string;\n  /** Fixed value for literal segments (e.g., \", \" or \"º\") */\n  value?: string;\n  /** Padding in CSS 'ch' units to add to the segment width (defaults to 0.5 if not specified) */\n  pad?: number;\n};\n\n/**\n * Result of parsing a pasted coordinate string\n */\nexport type ParsedCoordinateMatch = {\n  /** The coordinate system format that matched */\n  format: CoordinateSystem;\n  /** The coordinate value in DD format */\n  value: CoordinateValue;\n  /** Display string in the matched format */\n  displayString: string;\n};\n\n/**\n * State shared with child components through context\n */\nexport type CoordinateFieldState = {\n  segmentValues: string[];\n  format: CoordinateFieldProps['format'];\n  /**\n   * Current coordinate value in DD format\n   * - undefined: uncontrolled mode with no default value\n   * - null: controlled mode with empty/invalid value\n   * - CoordinateValue: valid coordinate\n   */\n  currentValue?: CoordinateValue | null;\n  /** Validation errors from @accelint/geo */\n  validationErrors: string[];\n  isDisabled: boolean;\n  isInvalid: boolean;\n  isRequired: boolean;\n  /** Size variant of the field */\n  size: CoordinateFieldProps['size'];\n  /** Whether or not the logical coordinate fields are inlined or stacked */\n  variant: CoordinateFieldProps['variant'];\n  /** Function to register timeouts for cleanup on unmount */\n  registerTimeout: (timeoutId: NodeJS.Timeout) => void;\n};\n\n/**\n * Props for the CoordinateSegment component\n */\nexport type CoordinateSegmentProps = {\n  /** Current value of the segment */\n  value: string;\n  /** Callback when the segment value changes */\n  onChange: (value: string) => void;\n  /** Callback when the segment receives focus */\n  onFocus?: () => void;\n  /** Callback when the segment loses focus */\n  onBlur?: () => void;\n  /** Callback for keyboard events (used for navigation between segments) */\n  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;\n  /** Placeholder text to display when segment is empty */\n  placeholder?: string;\n  /** Maximum character length for the segment */\n  maxLength?: number;\n  /** Custom className for styling */\n  className?: string;\n  /** Whether the segment is disabled */\n  isDisabled?: boolean;\n  /** Whether the segment is read-only */\n  isReadOnly?: boolean;\n  /** Regex pattern for allowed characters (e.g., \"[0-9\\\\-\\\\.]\" for numeric, \"[NSEW]\" for directional) */\n  allowedChars?: string;\n  /** Ref to the input element for programmatic focus management */\n  segmentRef?: React.RefObject<HTMLInputElement>;\n  /** Index of this segment in the parent field (for accessibility) */\n  segmentIndex?: number;\n  /** Total number of segments (for accessibility) */\n  totalSegments?: number;\n  /** Callback to trigger auto-advance to next segment */\n  onAutoAdvance?: () => void;\n  /** Callback to trigger auto-retreat to previous segment */\n  onAutoRetreat?: () => void;\n  /** Padding in CSS 'ch' units to add to the segment width (defaults to 0.5 if not specified) */\n  pad?: number;\n  /** Semantic accessibility label for the segment (e.g., \"Latitude degrees\") */\n  ariaLabel?: string;\n};\n\n/**\n * Props for the CoordinateField component\n *\n * Extends AriaTextFieldProps to inherit standard form field props (id, isDisabled, isRequired, etc.)\n */\nexport type CoordinateFieldProps = Omit<\n  AriaTextFieldProps,\n  | 'children'\n  | 'className'\n  | 'placeholder'\n  | 'type'\n  | 'pattern'\n  | 'value'\n  | 'defaultValue'\n  | 'onChange'\n  | 'name' // Not applicable to multi-segment fields\n> &\n  RefAttributes<HTMLDivElement> & {\n    /**\n     * Custom class names for component slots\n     */\n    classNames?: {\n      field?: string;\n      label?: LabelProps['className'];\n      control?: string;\n      input?: string;\n      segment?: string;\n      description?: string;\n      error?: FieldErrorProps['className'];\n      formatButton?: string;\n    };\n\n    /**\n     * Label text displayed above the input (medium size only)\n     */\n    label?: string;\n\n    /**\n     * Helper text displayed below the input\n     */\n    description?: string;\n\n    /**\n     * Error message to display when the field is invalid\n     */\n    errorMessage?: string;\n\n    /**\n     * Display format for coordinate input\n     * @default 'dd' (Decimal Degrees)\n     */\n    format?: CoordinateSystem;\n\n    /**\n     * Size variant of the field\n     * @default 'medium'\n     */\n    size?: 'small' | 'medium';\n\n    /**\n     * Whether to show the format button for copying coordinates in different formats\n     * @default true\n     */\n    showFormatButton?: boolean;\n\n    /**\n     * Controlled value in Decimal Degrees format\n     * - undefined: uncontrolled mode\n     * - null: controlled mode with no/invalid value\n     * - CoordinateValue: controlled mode with valid value\n     */\n    value?: CoordinateValue | null;\n\n    /**\n     * Whether or not the input is stacked or inline\n     * @default 'inline'\n     */\n    variant?: 'inline' | 'stacked';\n\n    /**\n     * Default uncontrolled value in Decimal Degrees format\n     */\n    defaultValue?: CoordinateValue;\n\n    /**\n     * Callback fired when the coordinate value changes\n     * @param value - The new coordinate value in DD format, or null if invalid\n     */\n    onChange?:\n      | Dispatch<SetStateAction<CoordinateValue | null>>\n      | ((value: CoordinateValue | null) => void);\n\n    /**\n     * Callback fired when validation or paste errors occur\n     * @param message - Error message (\"Invalid coordinate value\" for validation errors, \"Invalid coordinate format\" for paste errors)\n     * @param context - Additional context about the error:\n     *   - Validation errors: `{ errors: string[], format: string, segments: string[] }`\n     *   - Paste errors: `{ pastedText: string }`\n     */\n    onError?: (message: string, context?: Record<string, unknown>) => void;\n  };\n"],"mappings":";;;;;;;;;;;;;;;;;AAgCA,MAAaA,2BAA6D;CACxE,IAAI;CACJ,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACN;;;;AAKD,MAAaC,0BAA4D;CACvE,IAAI;CACJ,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACN;;;;;AAMD,MAAaC,qBAAkD;CAC7D;CACA;CACA;CACA;CACA;CACD"}

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

@@ -12,7 +12,7 @@
 
 import { DateFieldProps } from "./types.js";
 import "client-only";
-import * as react_jsx_runtime185 from "react/jsx-runtime";
+import * as react_jsx_runtime40 from "react/jsx-runtime";
 import { DateValue } from "@internationalized/date";
 
 //#region src/components/date-field/index.d.ts
@@ -24,11 +24,29 @@ import { DateValue } from "@internationalized/date";
  * month, and year. Includes calendar icon, validation states, and international
  * date format support with keyboard navigation between segments.
  *
+ * @param props - The date field props.
+ * @param props.classNames - Custom class names for sub-elements.
+ * @param props.description - Helper text displayed below the field.
+ * @param props.errorMessage - Error message displayed when invalid.
+ * @param props.inputProps - Additional props for the date input element.
+ * @param props.label - Label text displayed above the field.
+ * @param props.size - Size variant of the field.
+ * @param props.shortMonth - When true, displays 3-letter month abbreviation when not editing.
+ * @param props.shouldForceLeadingZeros - Whether to force leading zeros in segments.
+ * @param props.isDisabled - Whether the field is disabled.
+ * @param props.isInvalid - Whether the field is in an invalid state.
+ * @param props.isRequired - Whether the field is required.
+ * @param props.isReadOnly - Whether the field is read-only.
+ * @returns The date field component.
+ *
  * @example
+ * ```tsx
  * // Basic date field
  * <DateField label="Birth Date" />
+ * ```
  *
  * @example
+ * ```tsx
  * // Date field with validation
  * <DateField
  *   label="Event Date"
@@ -36,30 +54,37 @@ import { DateValue } from "@internationalized/date";
  *   isInvalid={hasError}
  *   errorMessage="Please select a valid date"
  * />
+ * ```
  *
  * @example
+ * ```tsx
  * // Date field with custom formatting
  * <DateField
  *   label="Meeting Date"
  *   shortMonth={false}
  *   placeholder="Select meeting date"
  * />
+ * ```
  *
  * @example
+ * ```tsx
  * // Compact date field
  * <DateField
  *   label="Due Date"
  *   size="small"
  *   description="When is this task due?"
  * />
+ * ```
  *
  * @example
+ * ```tsx
  * // Controlled date field
  * <DateField
  *   label="Selected Date"
  *   value={selectedDate}
  *   onChange={setSelectedDate}
  * />
+ * ```
  */
 declare function DateField<T extends DateValue>({
   classNames,
@@ -73,8 +98,9 @@ declare function DateField<T extends DateValue>({
   isDisabled,
   isInvalid: isInvalidProp,
   isRequired,
+  isReadOnly,
   ...rest
-}: DateFieldProps<T>): react_jsx_runtime185.JSX.Element;
+}: DateFieldProps<T>): react_jsx_runtime40.JSX.Element;
 //#endregion
 export { DateField };
 //# sourceMappingURL=index.d.ts.map

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

@@ -44,11 +44,29 @@ const months = [
 * month, and year. Includes calendar icon, validation states, and international
 * date format support with keyboard navigation between segments.
 *
+* @param props - The date field props.
+* @param props.classNames - Custom class names for sub-elements.
+* @param props.description - Helper text displayed below the field.
+* @param props.errorMessage - Error message displayed when invalid.
+* @param props.inputProps - Additional props for the date input element.
+* @param props.label - Label text displayed above the field.
+* @param props.size - Size variant of the field.
+* @param props.shortMonth - When true, displays 3-letter month abbreviation when not editing.
+* @param props.shouldForceLeadingZeros - Whether to force leading zeros in segments.
+* @param props.isDisabled - Whether the field is disabled.
+* @param props.isInvalid - Whether the field is in an invalid state.
+* @param props.isRequired - Whether the field is required.
+* @param props.isReadOnly - Whether the field is read-only.
+* @returns The date field component.
+*
 * @example
+* ```tsx
 * // Basic date field
 * <DateField label="Birth Date" />
+* ```
 *
 * @example
+* ```tsx
 * // Date field with validation
 * <DateField
 *   label="Event Date"
@@ -56,32 +74,39 @@ const months = [
 *   isInvalid={hasError}
 *   errorMessage="Please select a valid date"
 * />
+* ```
 *
 * @example
+* ```tsx
 * // Date field with custom formatting
 * <DateField
 *   label="Meeting Date"
 *   shortMonth={false}
 *   placeholder="Select meeting date"
 * />
+* ```
 *
 * @example
+* ```tsx
 * // Compact date field
 * <DateField
 *   label="Due Date"
 *   size="small"
 *   description="When is this task due?"
 * />
+* ```
 *
 * @example
+* ```tsx
 * // Controlled date field
 * <DateField
 *   label="Selected Date"
 *   value={selectedDate}
 *   onChange={setSelectedDate}
 * />
+* ```
 */
-function DateField({ classNames, description: descriptionProp, errorMessage: errorMessageProp, inputProps, label: labelProp, size = "medium", shortMonth = true, shouldForceLeadingZeros = true, isDisabled, isInvalid: isInvalidProp, isRequired, ...rest }) {
+function DateField({ classNames, description: descriptionProp, errorMessage: errorMessageProp, inputProps, label: labelProp, size = "medium", shortMonth = true, shouldForceLeadingZeros = true, isDisabled, isInvalid: isInvalidProp, isRequired, isReadOnly = false, ...rest }) {
 	const errorMessage = errorMessageProp || null;
 	const isSmall = size === "small";
 	return /* @__PURE__ */ jsx(DateField$1, {
@@ -91,6 +116,7 @@ function DateField({ classNames, description: descriptionProp, errorMessage: err
 		isDisabled,
 		isInvalid: isInvalidProp || (errorMessage ? true : void 0),
 		isRequired,
+		isReadOnly,
 		"aria-label": labelProp,
 		"data-size": size,
 		children: ({ isDisabled: isDisabled$1 }) => /* @__PURE__ */ jsxs(Fragment, { children: [
@@ -102,7 +128,8 @@ function DateField({ classNames, description: descriptionProp, errorMessage: err
 			}),
 			/* @__PURE__ */ jsxs("div", {
 				className: clsx(styles.control, classNames?.control),
-				children: [size === "medium" && /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx(Calendar, {}) }), /* @__PURE__ */ jsx(DateInput, {
+				"data-readonly": isReadOnly || null,
+				children: [!isReadOnly && size === "medium" && /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx(Calendar, {}) }), /* @__PURE__ */ jsx(DateInput, {
 					...inputProps,
 					className: composeRenderProps(classNames?.input, (className) => clsx(styles.input, className)),
 					children: (segmentProp) => {

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["AriaDateField","Label","isDisabled","AriaDateInput","AriaText"],"sources":["../../../src/components/date-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\n'use client';\n\nimport 'client-only';\nimport { clsx } from '@accelint/design-foundation/lib/utils';\nimport Calendar from '@accelint/icons/calendar';\nimport {\n  DateField as AriaDateField,\n  DateInput as AriaDateInput,\n  Text as AriaText,\n  composeRenderProps,\n  DateSegment,\n  FieldError,\n} from 'react-aria-components';\nimport { Icon } from '../icon';\nimport { Label } from '../label';\nimport styles from './styles.module.css';\nimport type { DateValue } from '@internationalized/date';\nimport type { DateFieldProps } from './types';\n\nconst months = [\n  'JAN',\n  'FEB',\n  'MAR',\n  'APR',\n  'MAY',\n  'JUN',\n  'JUL',\n  'AUG',\n  'SEP',\n  'OCT',\n  'NOV',\n  'DEC',\n];\n\n/**\n * DateField - A comprehensive date input component with segmented editing\n *\n * Provides accessible date input functionality with separate segments for day,\n * month, and year. Includes calendar icon, validation states, and international\n * date format support with keyboard navigation between segments.\n *\n * @example\n * // Basic date field\n * <DateField label=\"Birth Date\" />\n *\n * @example\n * // Date field with validation\n * <DateField\n *   label=\"Event Date\"\n *   isRequired\n *   isInvalid={hasError}\n *   errorMessage=\"Please select a valid date\"\n * />\n *\n * @example\n * // Date field with custom formatting\n * <DateField\n *   label=\"Meeting Date\"\n *   shortMonth={false}\n *   placeholder=\"Select meeting date\"\n * />\n *\n * @example\n * // Compact date field\n * <DateField\n *   label=\"Due Date\"\n *   size=\"small\"\n *   description=\"When is this task due?\"\n * />\n *\n * @example\n * // Controlled date field\n * <DateField\n *   label=\"Selected Date\"\n *   value={selectedDate}\n *   onChange={setSelectedDate}\n * />\n */\nexport function DateField<T extends DateValue>({\n  classNames,\n  description: descriptionProp,\n  errorMessage: errorMessageProp,\n  inputProps,\n  label: labelProp,\n  size = 'medium',\n  shortMonth = true,\n  shouldForceLeadingZeros = true,\n  isDisabled,\n  isInvalid: isInvalidProp,\n  isRequired,\n  ...rest\n}: DateFieldProps<T>) {\n  const errorMessage = errorMessageProp || null; // Protect against empty string\n  const isSmall = size === 'small';\n\n  return (\n    <AriaDateField<T>\n      {...rest}\n      className={composeRenderProps(classNames?.field, (className) =>\n        clsx('group/date-field', styles.field, className),\n      )}\n      shouldForceLeadingZeros={shouldForceLeadingZeros}\n      isDisabled={isDisabled}\n      isInvalid={isInvalidProp || (errorMessage ? true : undefined)} // Leave uncontrolled if possible to fallback to validation state\n      isRequired={isRequired}\n      aria-label={labelProp}\n      data-size={size}\n    >\n      {(\n        { isDisabled }, // Rely on internal state, not props, since state could differ from props\n      ) => (\n        <>\n          {!isSmall && labelProp && (\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            {size === 'medium' && (\n              <Icon>\n                <Calendar />\n              </Icon>\n            )}\n            <AriaDateInput\n              {...inputProps}\n              className={composeRenderProps(classNames?.input, (className) =>\n                clsx(styles.input, className),\n              )}\n            >\n              {(segmentProp) => {\n                // Remove extra space and punctuation from input display\n                if (segmentProp.type === 'literal') {\n                  return <>{segmentProp.text === ':' ? ':' : null}</>;\n                }\n\n                return (\n                  <DateSegment\n                    className={composeRenderProps(\n                      classNames?.segment,\n                      (className) =>\n                        clsx(\n                          styles.segment,\n                          segmentProp.type === 'month' &&\n                            shortMonth &&\n                            styles.shortMonth,\n                          className,\n                        ),\n                    )}\n                    segment={segmentProp}\n                  >\n                    {({\n                      placeholder,\n                      text,\n                      value,\n                      isFocused,\n                      isPlaceholder,\n                    }) => {\n                      if (isPlaceholder) {\n                        return placeholder;\n                      }\n\n                      return segmentProp.type === 'month' &&\n                        shortMonth &&\n                        !isFocused\n                        ? months[(value ?? 0) - 1]\n                        : text;\n                    }}\n                  </DateSegment>\n                );\n              }}\n            </AriaDateInput>\n          </div>\n          {descriptionProp && (!(isSmall || isInvalidProp) || isDisabled) && (\n            <AriaText\n              className={clsx(styles.description, classNames?.description)}\n              slot='description'\n            >\n              {descriptionProp}\n            </AriaText>\n          )}\n          <FieldError\n            className={composeRenderProps(classNames?.error, (className) =>\n              clsx(styles.error, className),\n            )}\n          >\n            {errorMessage}\n          </FieldError>\n        </>\n      )}\n    </AriaDateField>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAM,SAAS;CACb;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CD,SAAgB,UAA+B,EAC7C,YACA,aAAa,iBACb,cAAc,kBACd,YACA,OAAO,WACP,OAAO,UACP,aAAa,MACb,0BAA0B,MAC1B,YACA,WAAW,eACX,YACA,GAAG,QACiB;CACpB,MAAM,eAAe,oBAAoB;CACzC,MAAM,UAAU,SAAS;AAEzB,QACE,oBAACA;EACC,GAAI;EACJ,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,oBAAoB,OAAO,OAAO,UAAU,CAClD;EACwB;EACb;EACZ,WAAW,kBAAkB,eAAe,OAAO;EACvC;EACZ,cAAY;EACZ,aAAW;aAGT,EAAE,+BAEF;GACG,CAAC,WAAW,aACX,oBAACC;IACC,WAAW,KAAK,OAAO,OAAO,YAAY,MAAM;IAChD,YAAYC;IACA;cAEX;KACK;GAEV,qBAAC;IAAI,WAAW,KAAK,OAAO,SAAS,YAAY,QAAQ;eACtD,SAAS,YACR,oBAAC,kBACC,oBAAC,aAAW,GACP,EAET,oBAACC;KACC,GAAI;KACJ,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,OAAO,OAAO,UAAU,CAC9B;gBAEC,gBAAgB;AAEhB,UAAI,YAAY,SAAS,UACvB,QAAO,0CAAG,YAAY,SAAS,MAAM,MAAM,OAAQ;AAGrD,aACE,oBAAC;OACC,WAAW,mBACT,YAAY,UACX,cACC,KACE,OAAO,SACP,YAAY,SAAS,WACnB,cACA,OAAO,YACT,UACD,CACJ;OACD,SAAS;kBAEP,EACA,aACA,MACA,OACA,WACA,oBACI;AACJ,YAAI,cACF,QAAO;AAGT,eAAO,YAAY,SAAS,WAC1B,cACA,CAAC,YACC,QAAQ,SAAS,KAAK,KACtB;;QAEM;;MAGJ;KACZ;GACL,oBAAoB,EAAE,WAAW,kBAAkBD,iBAClD,oBAACE;IACC,WAAW,KAAK,OAAO,aAAa,YAAY,YAAY;IAC5D,MAAK;cAEJ;KACQ;GAEb,oBAAC;IACC,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,OAAO,OAAO,UAAU,CAC9B;cAEA;KACU;MACZ;GAES"}
+{"version":3,"file":"index.js","names":["AriaDateField","Label","isDisabled","AriaDateInput","AriaText"],"sources":["../../../src/components/date-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\n'use client';\n\nimport 'client-only';\nimport { clsx } from '@accelint/design-foundation/lib/utils';\nimport Calendar from '@accelint/icons/calendar';\nimport {\n  DateField as AriaDateField,\n  DateInput as AriaDateInput,\n  Text as AriaText,\n  composeRenderProps,\n  DateSegment,\n  FieldError,\n} from 'react-aria-components';\nimport { Icon } from '../icon';\nimport { Label } from '../label';\nimport styles from './styles.module.css';\nimport type { DateValue } from '@internationalized/date';\nimport type { DateFieldProps } from './types';\n\nconst months = [\n  'JAN',\n  'FEB',\n  'MAR',\n  'APR',\n  'MAY',\n  'JUN',\n  'JUL',\n  'AUG',\n  'SEP',\n  'OCT',\n  'NOV',\n  'DEC',\n];\n\n/**\n * DateField - A comprehensive date input component with segmented editing\n *\n * Provides accessible date input functionality with separate segments for day,\n * month, and year. Includes calendar icon, validation states, and international\n * date format support with keyboard navigation between segments.\n *\n * @param props - The date field props.\n * @param props.classNames - Custom class names for sub-elements.\n * @param props.description - Helper text displayed below the field.\n * @param props.errorMessage - Error message displayed when invalid.\n * @param props.inputProps - Additional props for the date input element.\n * @param props.label - Label text displayed above the field.\n * @param props.size - Size variant of the field.\n * @param props.shortMonth - When true, displays 3-letter month abbreviation when not editing.\n * @param props.shouldForceLeadingZeros - Whether to force leading zeros in segments.\n * @param props.isDisabled - Whether the field is disabled.\n * @param props.isInvalid - Whether the field is in an invalid state.\n * @param props.isRequired - Whether the field is required.\n * @param props.isReadOnly - Whether the field is read-only.\n * @returns The date field component.\n *\n * @example\n * ```tsx\n * // Basic date field\n * <DateField label=\"Birth Date\" />\n * ```\n *\n * @example\n * ```tsx\n * // Date field with validation\n * <DateField\n *   label=\"Event Date\"\n *   isRequired\n *   isInvalid={hasError}\n *   errorMessage=\"Please select a valid date\"\n * />\n * ```\n *\n * @example\n * ```tsx\n * // Date field with custom formatting\n * <DateField\n *   label=\"Meeting Date\"\n *   shortMonth={false}\n *   placeholder=\"Select meeting date\"\n * />\n * ```\n *\n * @example\n * ```tsx\n * // Compact date field\n * <DateField\n *   label=\"Due Date\"\n *   size=\"small\"\n *   description=\"When is this task due?\"\n * />\n * ```\n *\n * @example\n * ```tsx\n * // Controlled date field\n * <DateField\n *   label=\"Selected Date\"\n *   value={selectedDate}\n *   onChange={setSelectedDate}\n * />\n * ```\n */\nexport function DateField<T extends DateValue>({\n  classNames,\n  description: descriptionProp,\n  errorMessage: errorMessageProp,\n  inputProps,\n  label: labelProp,\n  size = 'medium',\n  shortMonth = true,\n  shouldForceLeadingZeros = true,\n  isDisabled,\n  isInvalid: isInvalidProp,\n  isRequired,\n  isReadOnly = false,\n  ...rest\n}: DateFieldProps<T>) {\n  const errorMessage = errorMessageProp || null; // Protect against empty string\n  const isSmall = size === 'small';\n\n  return (\n    <AriaDateField<T>\n      {...rest}\n      className={composeRenderProps(classNames?.field, (className) =>\n        clsx('group/date-field', styles.field, className),\n      )}\n      shouldForceLeadingZeros={shouldForceLeadingZeros}\n      isDisabled={isDisabled}\n      isInvalid={isInvalidProp || (errorMessage ? true : undefined)} // Leave uncontrolled if possible to fallback to validation state\n      isRequired={isRequired}\n      isReadOnly={isReadOnly}\n      aria-label={labelProp}\n      data-size={size}\n    >\n      {(\n        { isDisabled }, // Rely on internal state, not props, since state could differ from props\n      ) => (\n        <>\n          {!isSmall && labelProp && (\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            {!isReadOnly && size === 'medium' && (\n              <Icon>\n                <Calendar />\n              </Icon>\n            )}\n            <AriaDateInput\n              {...inputProps}\n              className={composeRenderProps(classNames?.input, (className) =>\n                clsx(styles.input, className),\n              )}\n            >\n              {(segmentProp) => {\n                // Remove extra space and punctuation from input display\n                if (segmentProp.type === 'literal') {\n                  return <>{segmentProp.text === ':' ? ':' : null}</>;\n                }\n\n                return (\n                  <DateSegment\n                    className={composeRenderProps(\n                      classNames?.segment,\n                      (className) =>\n                        clsx(\n                          styles.segment,\n                          segmentProp.type === 'month' &&\n                            shortMonth &&\n                            styles.shortMonth,\n                          className,\n                        ),\n                    )}\n                    segment={segmentProp}\n                  >\n                    {({\n                      placeholder,\n                      text,\n                      value,\n                      isFocused,\n                      isPlaceholder,\n                    }) => {\n                      if (isPlaceholder) {\n                        return placeholder;\n                      }\n\n                      return segmentProp.type === 'month' &&\n                        shortMonth &&\n                        !isFocused\n                        ? months[(value ?? 0) - 1]\n                        : text;\n                    }}\n                  </DateSegment>\n                );\n              }}\n            </AriaDateInput>\n          </div>\n          {descriptionProp && (!(isSmall || isInvalidProp) || isDisabled) && (\n            <AriaText\n              className={clsx(styles.description, classNames?.description)}\n              slot='description'\n            >\n              {descriptionProp}\n            </AriaText>\n          )}\n          <FieldError\n            className={composeRenderProps(classNames?.error, (className) =>\n              clsx(styles.error, className),\n            )}\n          >\n            {errorMessage}\n          </FieldError>\n        </>\n      )}\n    </AriaDateField>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAM,SAAS;CACb;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuED,SAAgB,UAA+B,EAC7C,YACA,aAAa,iBACb,cAAc,kBACd,YACA,OAAO,WACP,OAAO,UACP,aAAa,MACb,0BAA0B,MAC1B,YACA,WAAW,eACX,YACA,aAAa,OACb,GAAG,QACiB;CACpB,MAAM,eAAe,oBAAoB;CACzC,MAAM,UAAU,SAAS;AAEzB,QACE,oBAACA;EACC,GAAI;EACJ,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,oBAAoB,OAAO,OAAO,UAAU,CAClD;EACwB;EACb;EACZ,WAAW,kBAAkB,eAAe,OAAO;EACvC;EACA;EACZ,cAAY;EACZ,aAAW;aAGT,EAAE,+BAEF;GACG,CAAC,WAAW,aACX,oBAACC;IACC,WAAW,KAAK,OAAO,OAAO,YAAY,MAAM;IAChD,YAAYC;IACA;cAEX;KACK;GAEV,qBAAC;IACC,WAAW,KAAK,OAAO,SAAS,YAAY,QAAQ;IACpD,iBAAe,cAAc;eAE5B,CAAC,cAAc,SAAS,YACvB,oBAAC,kBACC,oBAAC,aAAW,GACP,EAET,oBAACC;KACC,GAAI;KACJ,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,OAAO,OAAO,UAAU,CAC9B;gBAEC,gBAAgB;AAEhB,UAAI,YAAY,SAAS,UACvB,QAAO,0CAAG,YAAY,SAAS,MAAM,MAAM,OAAQ;AAGrD,aACE,oBAAC;OACC,WAAW,mBACT,YAAY,UACX,cACC,KACE,OAAO,SACP,YAAY,SAAS,WACnB,cACA,OAAO,YACT,UACD,CACJ;OACD,SAAS;kBAEP,EACA,aACA,MACA,OACA,WACA,oBACI;AACJ,YAAI,cACF,QAAO;AAGT,eAAO,YAAY,SAAS,WAC1B,cACA,CAAC,YACC,QAAQ,SAAS,KAAK,KACtB;;QAEM;;MAGJ;KACZ;GACL,oBAAoB,EAAE,WAAW,kBAAkBD,iBAClD,oBAACE;IACC,WAAW,KAAK,OAAO,aAAa,YAAY,YAAY;IAC5D,MAAK;cAEJ;KACQ;GAEb,oBAAC;IACC,WAAW,mBAAmB,YAAY,QAAQ,cAChD,KAAK,OAAO,OAAO,UAAU,CAC9B;cAEA;KACU;MACZ;GAES"}

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

@@ -43,6 +43,10 @@
     @variant group-disabled/date-field {
       @apply fg-disabled outline-interactive-disabled;
     }
+
+    @variant read-only {
+      @apply px-0 outline-none;
+    }
   }
 
   .input {

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

@@ -13,24 +13,40 @@
 import { DateFieldProps as DateFieldProps$1, DateInputProps, DateSegmentProps, DateValue, FieldErrorProps, LabelProps } from "react-aria-components";
 
 //#region src/components/date-field/types.d.ts
+/**
+ * Props for the DateField component.
+ *
+ * Extends AriaDateFieldProps with custom styling, labels, and size variants.
+ */
 type DateFieldProps<T extends DateValue> = Omit<DateFieldProps$1<T>, 'children' | 'className' | 'placeholder'> & {
+  /** Custom class names for sub-elements. */
   classNames?: {
+    /** Class name for the field container. */
     field?: DateFieldProps$1<T>['className'];
+    /** Class name for the label. */
     label?: LabelProps['className'];
+    /** Class name for the control wrapper. */
     control?: string;
+    /** Class name for the date input. */
     input?: DateInputProps['className'];
+    /** Class name for individual date segments. */
     segment?: DateSegmentProps['className'];
+    /** Class name for the description text. */
     description?: string;
+    /** Class name for the error message. */
     error?: FieldErrorProps['className'];
   };
+  /** Label text displayed above the field. */
   label?: string;
+  /** Helper text displayed below the field. */
   description?: string;
+  /** Error message displayed when invalid. */
   errorMessage?: string;
+  /** Additional props passed to the date input element. */
   inputProps?: Omit<DateInputProps, 'children' | 'className'>;
-  /**
-   * When true, will convert month value to 3 letter abbreviation when not editing
-   */
+  /** When true, will convert month value to 3 letter abbreviation when not editing. */
   shortMonth?: boolean;
+  /** Size variant of the field. */
   size?: 'small' | 'medium';
 };
 //#endregion

package/dist/components/deferred-collection/index.d.ts

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { DeferredCollectionProps } from "./types.js";
+import * as react_jsx_runtime42 from "react/jsx-runtime";
+
+//#region src/components/deferred-collection/index.d.ts
+
+/**
+ * DeferredCollection - Defers rendering of large collections to prevent UI freezes.
+ *
+ * React Aria's collection system processes ALL items synchronously before
+ * virtualization begins. This component defers the collection render by a few
+ * animation frames, allowing a fallback to display first.
+ *
+ * @param props - The deferred collection props.
+ * @param props.children - Content to render once ready (ReactNode or function returning ReactNode).
+ * @param props.fallback - Fallback element to show while deferring render.
+ * @param props.deferFrames - Number of animation frames to defer before rendering.
+ * @returns The deferred collection component with fallback or children.
+ *
+ * @example
+ * ```tsx
+ * <DeferredCollection fallback={<LoadingState />}>
+ *   {() => (
+ *     <Virtualizer>
+ *       <ListBox items={items}>
+ *         {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
+ *       </ListBox>
+ *     </Virtualizer>
+ *   )}
+ * </DeferredCollection>
+ * ```
+ */
+declare function DeferredCollection({
+  children,
+  fallback,
+  deferFrames
+}: DeferredCollectionProps): react_jsx_runtime42.JSX.Element;
+//#endregion
+export { DeferredCollection, type DeferredCollectionProps };
+//# sourceMappingURL=index.d.ts.map

package/dist/components/deferred-collection/index.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+import { useFrameDelay } from "../../hooks/use-frame-delay/index.js";
+import { Fragment, jsx } from "react/jsx-runtime";
+
+//#region src/components/deferred-collection/index.tsx
+/**
+* DeferredCollection - Defers rendering of large collections to prevent UI freezes.
+*
+* React Aria's collection system processes ALL items synchronously before
+* virtualization begins. This component defers the collection render by a few
+* animation frames, allowing a fallback to display first.
+*
+* @param props - The deferred collection props.
+* @param props.children - Content to render once ready (ReactNode or function returning ReactNode).
+* @param props.fallback - Fallback element to show while deferring render.
+* @param props.deferFrames - Number of animation frames to defer before rendering.
+* @returns The deferred collection component with fallback or children.
+*
+* @example
+* ```tsx
+* <DeferredCollection fallback={<LoadingState />}>
+*   {() => (
+*     <Virtualizer>
+*       <ListBox items={items}>
+*         {(item) => <ListBoxItem>{item.name}</ListBoxItem>}
+*       </ListBox>
+*     </Virtualizer>
+*   )}
+* </DeferredCollection>
+* ```
+*/
+function DeferredCollection({ children, fallback, deferFrames }) {
+	const { isReady } = useFrameDelay({ frames: deferFrames });
+	if (isReady) return /* @__PURE__ */ jsx(Fragment, { children: typeof children === "function" ? children() : children });
+	return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+}
+
+//#endregion
+export { DeferredCollection };
+//# sourceMappingURL=index.js.map

package/dist/components/deferred-collection/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/components/deferred-collection/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\nimport { useFrameDelay } from '../../hooks/use-frame-delay';\nimport type { DeferredCollectionProps } from './types';\n\n/**\n * DeferredCollection - Defers rendering of large collections to prevent UI freezes.\n *\n * React Aria's collection system processes ALL items synchronously before\n * virtualization begins. This component defers the collection render by a few\n * animation frames, allowing a fallback to display first.\n *\n * @param props - The deferred collection props.\n * @param props.children - Content to render once ready (ReactNode or function returning ReactNode).\n * @param props.fallback - Fallback element to show while deferring render.\n * @param props.deferFrames - Number of animation frames to defer before rendering.\n * @returns The deferred collection component with fallback or children.\n *\n * @example\n * ```tsx\n * <DeferredCollection fallback={<LoadingState />}>\n *   {() => (\n *     <Virtualizer>\n *       <ListBox items={items}>\n *         {(item) => <ListBoxItem>{item.name}</ListBoxItem>}\n *       </ListBox>\n *     </Virtualizer>\n *   )}\n * </DeferredCollection>\n * ```\n */\nexport function DeferredCollection({\n  children,\n  fallback,\n  deferFrames,\n}: DeferredCollectionProps) {\n  const { isReady } = useFrameDelay({ frames: deferFrames });\n\n  if (isReady) {\n    return <>{typeof children === 'function' ? children() : children}</>;\n  }\n\n  return <>{fallback}</>;\n}\n\nexport type { DeferredCollectionProps } from './types';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,mBAAmB,EACjC,UACA,UACA,eAC0B;CAC1B,MAAM,EAAE,YAAY,cAAc,EAAE,QAAQ,aAAa,CAAC;AAE1D,KAAI,QACF,QAAO,0CAAG,OAAO,aAAa,aAAa,UAAU,GAAG,WAAY;AAGtE,QAAO,0CAAG,WAAY"}

package/dist/components/deferred-collection/types.d.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { ReactNode } from "react";
+
+//#region src/components/deferred-collection/types.d.ts
+/**
+ * Props for the DeferredCollection component.
+ */
+interface DeferredCollectionProps {
+  /** The content to render once ready - can be ReactNode or a function returning ReactNode for deferred creation. */
+  children: ReactNode | (() => ReactNode);
+  /** Fallback element to show while deferring render. */
+  fallback?: ReactNode;
+  /** Number of animation frames to defer before rendering (default: 2). */
+  deferFrames?: number;
+}
+//#endregion
+export { DeferredCollectionProps };
+//# sourceMappingURL=types.d.ts.map

package/dist/components/deferred-collection/types.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+