@astryxdesign/core 0.1.2 → 0.1.3-canary.6d57c8d

package/dist/DateRangeInput/DateRangeInput.js

@@ -25,6 +25,7 @@ import { Icon } from "../Icon/index.js";
 import { Spinner } from "../Spinner/index.js";
 import { Calendar } from "../Calendar/index.js";
 import { usePopover } from "../Popover/index.js";
+import { useTooltip } from "../Tooltip/index.js";
 import { mergeProps } from "../utils/index.js";
 import { useSize } from "../SizeContext/SizeContext.js";
 import { themeProps } from "../utils/themeProps.js";
@@ -89,6 +90,7 @@ export function DateRangeInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   value,
   onChange,
   changeAction,
@@ -118,6 +120,21 @@ export function DateRangeInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
   const isEffectivelyDisabled = isDisabled || isBusy;
+
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the trigger container (which already exists)
+  // and the trigger button stays perceivable via aria-disabled instead of the
+  // disabled attribute. Activation is blocked by the isEffectivelyDisabled
+  // guard in handleToggle. Only the persistent isDisabled state (not the
+  // transient busy state) surfaces a reason.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the trigger button, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage
+  });
   const statusIconMap = {
     warning: 'warning',
     error: 'error',
@@ -128,7 +145,7 @@ export function DateRangeInput({
     error: 'error',
     success: 'success'
   };
-  const ariaDescribedBy = [description ? descriptionID : null, status?.message ? statusMessageID : null].filter(Boolean).join(' ') || undefined;
+  const ariaDescribedBy = [description ? descriptionID : null, status?.message ? statusMessageID : null, showsDisabledMessage ? disabledMessageTooltip.describedBy : null].filter(Boolean).join(' ') || undefined;
   const displayValue = useMemo(() => formatRangeDisplay(optimisticValue), [optimisticValue]);
   const popover = usePopover({
     dialogLabel: 'Choose date range',
@@ -185,7 +202,13 @@ export function DateRangeInput({
     labelTooltip: labelTooltip,
     width: width,
     children: [/*#__PURE__*/_jsxs("div", {
-      ref: popover.triggerRef,
+      ref: el => {
+        popover.triggerRef(el);
+        // Anchor + hover/focus listeners for the disabled-message tooltip.
+        // Handlers are gated internally by isEnabled, and anchor names
+        // compose, so attaching unconditionally is safe.
+        disabledMessageTooltip.ref(el);
+      },
       ...rest,
       ...mergeProps(themeProps('date-range-input', {
         size,
@@ -214,8 +237,13 @@ export function DateRangeInput({
         ref: ref,
         id: id,
         type: "button",
-        onClick: handleToggle,
-        disabled: isEffectivelyDisabled,
+        onClick: handleToggle
+        // With a disabledMessage the trigger keeps focusability via
+        // aria-disabled so the reason is focus-discoverable; activation is
+        // still blocked by the isEffectivelyDisabled guard in handleToggle.
+        ,
+        disabled: isEffectivelyDisabled && !showsDisabledMessage,
+        "aria-disabled": showsDisabledMessage ? 'true' : undefined,
         "aria-label": triggerAriaLabel,
         "aria-describedby": ariaDescribedBy,
         "aria-required": isRequired === true ? 'true' : undefined,
@@ -263,7 +291,7 @@ export function DateRangeInput({
         className: "x78zum5"
       },
       children: [presets && presets.length > 0 && /*#__PURE__*/_jsx("div", {
-        role: "listbox",
+        role: "group",
         "aria-label": "Preset date ranges",
         ...{
           className: "x78zum5 xdt5ytf xzye2dw x1b2ylru x1pcaw5z x32b0ac xdz7fjg x1d77m7x"
@@ -272,9 +300,14 @@ export function DateRangeInput({
           const presetRange = preset.getRange();
           const isActive = isRangeEqual(value, presetRange);
           return /*#__PURE__*/_jsx("button", {
-            type: "button",
-            role: "option",
-            "aria-selected": isActive,
+            type: "button"
+            // These presets are independent action buttons navigated by
+            // Tab, not a single-tab-stop listbox — so they are a labeled
+            // group of buttons, and the currently-applied preset is
+            // marked with aria-current (not aria-selected, a listbox
+            // concept that contradicted the Tab interaction) (forms-5).
+            ,
+            "aria-current": isActive ? 'true' : undefined,
             onClick: () => handlePresetClick(preset),
             ...{
               0: {
@@ -299,7 +332,7 @@ export function DateRangeInput({
     }), {
       placement: 'below',
       alignment: 'start'
-    })]
+    }), showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
   });
 }
 DateRangeInput.displayName = 'DateRangeInput';

package/dist/DateTimeInput/DateTimeInput.d.ts

@@ -39,6 +39,28 @@ export interface DateTimeInputProps extends Omit<BaseProps, 'onChange' | 'defaul
      * @default false
      */
     isDisabled?: boolean;
+    /**
+     * Explains why the input is disabled. When set together with
+     * `isDisabled`, the input shows a tooltip with this text on hover and
+     * keyboard focus, and the date and time fields stay focusable (via
+     * `aria-disabled`) so the reason is discoverable by keyboard and assistive
+     * technology. Typing and calendar activation stay blocked.
+     *
+     * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+     * controls don't emit the pointer events an external tooltip needs.
+     *
+     * @example
+     * ```
+     * <DateTimeInput
+     *   label="Meeting time"
+     *   value={dateTime}
+     *   onChange={setDateTime}
+     *   isDisabled
+     *   disabledMessage="You need the Editor role to change this"
+     * />
+     * ```
+     */
+    disabledMessage?: string;
     /**
      * The selected datetime in ISO 8601 format ("YYYY-MM-DDTHH:MM" or "YYYY-MM-DDTHH:MM:SS").
      */
@@ -93,10 +115,21 @@ export interface DateTimeInputProps extends Omit<BaseProps, 'onChange' | 'defaul
      */
     hasClear?: boolean;
     /**
-     * Placeholder text shown when no date is selected.
+     * Placeholder text shown in the date portion when no date is selected.
      * @default "Select a date"
      */
     placeholder?: string;
+    /**
+     * Placeholder text shown in the time portion when no time is selected.
+     * @default "Select a time"
+     */
+    timePlaceholder?: string;
+    /**
+     * Accessible label for the time portion of the field. Defaults to
+     * `"{label} time"` so it is tied to the field's own label and localizable,
+     * rather than a hardcoded English "Time".
+     */
+    timeLabel?: string;
     /**
      * The size of the inputs.
      * @default 'md'
@@ -140,7 +173,7 @@ export interface DateTimeInputProps extends Omit<BaseProps, 'onChange' | 'defaul
  * />
  * ```
  */
-export declare function DateTimeInput({ label, isLabelHidden, description, isOptional, isRequired, isDisabled, value, onChange, changeAction, isLoading, min, max, dateConstraints, hasSeconds, hourFormat, timeIncrement, hasClear, placeholder, size: sizeProp, status, labelTooltip, numberOfMonths, width, xstyle, className, style, ref, ...rest }: DateTimeInputProps): import("react").JSX.Element;
+export declare function DateTimeInput({ label, isLabelHidden, description, isOptional, isRequired, isDisabled, disabledMessage, value, onChange, changeAction, isLoading, min, max, dateConstraints, hasSeconds, hourFormat, timeIncrement, hasClear, placeholder, timePlaceholder, timeLabel, size: sizeProp, status, labelTooltip, numberOfMonths, width, xstyle, className, style, ref, ...rest }: DateTimeInputProps): import("react").JSX.Element;
 export declare namespace DateTimeInput {
     var displayName: string;
 }

package/dist/DateTimeInput/DateTimeInput.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DateTimeInput.d.ts","sourceRoot":"","sources":["../../src/DateTimeInput/DateTimeInput.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"DateTimeInput.d.ts","sourceRoot":"","sources":["../../src/DateTimeInput/DateTimeInput.tsx"],"names":[],"mappings":"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"}

package/dist/DateTimeInput/DateTimeInput.js

@@ -21,10 +21,12 @@ import "../theme/tokens.stylex.js";
 import { colorVars, sizeVars, radiusVars, spacingVars, typographyVars, typeScaleVars, borderVars } from "../theme/tokens.stylex.js";
 import { Field, inputWrapperStyles, inputStatusBorderStyles, inputStatusHoverShadowStyles, inputStatusFocusWithinStyles } from "../Field/index.js";
 import { Icon } from "../Icon/index.js";
+import { VisuallyHidden } from "../VisuallyHidden/index.js";
 import { Spinner } from "../Spinner/index.js";
 import { Calendar } from "../Calendar/index.js";
 import { useCalendarConstraints } from "../Calendar/hooks/index.js";
 import { usePopover } from "../Popover/index.js";
+import { useTooltip } from "../Tooltip/index.js";
 import { useInputContainer } from "../hooks/useInputContainer.js";
 import { parseDateInput, parseTimeInput, formatDisplayTime12h, formatDisplayTime24h, formatISOTime, isTimeInRange, adjustTime, mergeProps, mergeRefs } from "../utils/index.js";
 import { plainDateFromISO, plainDateToISO, plainDateFormat, DATE_FORMAT_LONG } from "../utils/plainDate.js";
@@ -117,6 +119,7 @@ export function DateTimeInput({
   isOptional = false,
   isRequired = false,
   isDisabled = false,
+  disabledMessage,
   value,
   onChange,
   changeAction,
@@ -129,6 +132,8 @@ export function DateTimeInput({
   timeIncrement = 1,
   hasClear = false,
   placeholder = 'Select a date',
+  timePlaceholder = 'Select a time',
+  timeLabel,
   size: sizeProp,
   status,
   labelTooltip,
@@ -154,6 +159,22 @@ export function DateTimeInput({
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
   const isBusy = isLoading || optimisticValue !== value;
   const isEffectivelyDisabled = isDisabled || isBusy;
+
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the outer row container (which already exists)
+  // and both the date and time inputs stay perceivable via aria-disabled
+  // instead of the disabled attribute. Typing is blocked with readOnly and the
+  // value mutation guards; calendar activation is blocked by the
+  // isEffectivelyDisabled guards. Only the persistent isDisabled state (not the
+  // transient busy state) surfaces a reason.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The container div is not naturally focusable; focusin bubbles up from
+    // the inputs, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage
+  });
   const statusIconMap = {
     warning: 'warning',
     error: 'error',
@@ -164,7 +185,7 @@ export function DateTimeInput({
     error: 'error',
     success: 'success'
   };
-  const ariaDescribedBy = [description ? descriptionID : null, status?.message ? statusMessageID : null].filter(Boolean).join(' ') || undefined;
+  const ariaDescribedBy = [description ? descriptionID : null, status?.message ? statusMessageID : null, showsDisabledMessage ? disabledMessageTooltip.describedBy : null].filter(Boolean).join(' ') || undefined;
 
   // Split min/max and current value
   const minParts = useMemo(() => splitDateTime(min), [min]);
@@ -231,12 +252,12 @@ export function DateTimeInput({
     }
     return isTimeInRange(parsed, timeMin, timeMax);
   }, [timePendingInput, hasSeconds, timeMin, timeMax]);
-  const timePlaceholder = useMemo(() => {
+  const resolvedTimePlaceholder = useMemo(() => {
     if (isTimeFocused && !timeDisplayValue) {
       return hourFormat === '12h' ? 'e.g., 2:30 PM' : 'e.g., 14:30';
     }
-    return 'Select a time';
-  }, [isTimeFocused, timeDisplayValue, hourFormat]);
+    return timePlaceholder;
+  }, [isTimeFocused, timeDisplayValue, hourFormat, timePlaceholder]);
 
   // --- Unified change handler ---
   const fireChange = useCallback(newValue => {
@@ -299,6 +320,11 @@ export function DateTimeInput({
     }
   }, [valueParts.time, hasSeconds, minParts, maxParts, fireChange, popover]);
   const handleDateInputChange = useCallback(e => {
+    // With a disabledMessage the input drops `disabled` for focusability, so
+    // guard value mutation explicitly (readOnly also blocks typing).
+    if (isEffectivelyDisabled) {
+      return;
+    }
     const text = e.target.value;
     setDatePendingInput(text);
     const parsed = parseDateInput(text);
@@ -308,7 +334,7 @@ export function DateTimeInput({
       handleDateChange(parsedISO, 'input');
       calendarRef.current?.navigateTo(parsedISO);
     }
-  }, [valueParts.date, isDateDisabled, handleDateChange]);
+  }, [valueParts.date, isDateDisabled, handleDateChange, isEffectivelyDisabled]);
   const commitDatePendingInput = useCallback(() => {
     if (datePendingInput === null) {
       return;
@@ -344,6 +370,11 @@ export function DateTimeInput({
 
   // --- Time handlers ---
   const handleTimeInputChange = useCallback(e => {
+    // With a disabledMessage the input drops `disabled` for focusability, so
+    // guard value mutation explicitly (readOnly also blocks typing).
+    if (isEffectivelyDisabled) {
+      return;
+    }
     const text = e.target.value;
     setTimePendingInput(text);
     const parsed = parseTimeInput(text, hasSeconds);
@@ -355,8 +386,16 @@ export function DateTimeInput({
         }
       }
     }
-  }, [hasSeconds, timeMin, timeMax, valueParts.time, valueParts.date, fireChange]);
-  const handleTimeFocus = useCallback(() => setIsTimeFocused(true), []);
+  }, [hasSeconds, timeMin, timeMax, valueParts.time, valueParts.date, fireChange, isEffectivelyDisabled]);
+  const handleTimeFocus = useCallback(() => {
+    // A disabled/busy input stays focusable (via aria-disabled) so its reason
+    // is discoverable, but it must not present editing affordances — keep the
+    // static placeholder rather than swapping in the format hint.
+    if (isEffectivelyDisabled) {
+      return;
+    }
+    setIsTimeFocused(true);
+  }, [isEffectivelyDisabled]);
   const handleTimeBlur = useCallback(() => {
     setIsTimeFocused(false);
     if (timePendingInput === null) {
@@ -434,6 +473,7 @@ export function DateTimeInput({
     statusVariant: "detached",
     width: width,
     children: [/*#__PURE__*/_jsxs("div", {
+      ref: disabledMessageTooltip.ref,
       ...rest,
       ...mergeProps(themeProps('date-time-input', {
         size,
@@ -470,11 +510,18 @@ export function DateTimeInput({
           onBlur: handleDateBlur,
           onClick: handleDateInputClick,
           onKeyDown: handleDateKeyDown,
-          placeholder: placeholder,
-          disabled: isEffectivelyDisabled,
+          placeholder: placeholder
+          // With a disabledMessage the input keeps focusability via
+          // aria-disabled so the reason is focus-discoverable; typing is
+          // blocked with readOnly and the mutation guards, and calendar
+          // activation is blocked by the isEffectivelyDisabled guards.
+          ,
+          disabled: isEffectivelyDisabled && !showsDisabledMessage,
+          "aria-disabled": showsDisabledMessage ? 'true' : undefined,
+          readOnly: showsDisabledMessage || undefined,
           "aria-describedby": ariaDescribedBy,
           "aria-required": isRequired === true ? 'true' : undefined,
-          "aria-invalid": status?.type === 'error' ? 'true' : undefined,
+          "aria-invalid": status?.type === 'error' || !isDateInputValid ? 'true' : undefined,
           "aria-busy": isBusy || undefined,
           "aria-expanded": popover.isOpen,
           "aria-haspopup": "dialog",
@@ -495,6 +542,11 @@ export function DateTimeInput({
               className: "x1lliihq x98rzlu xeuugli xc342km xng3xce x1717udv x9ynric xjm74w1 x6pjikd xw6l6zx xjbqb8w x1a2a7pz xeyghm5 x1h6gzvc xv1l7n4"
             }
           }[!!isEffectivelyDisabled << 1 | !!!isDateInputValid << 0]
+        }), /*#__PURE__*/_jsx(VisuallyHidden, {
+          as: "div",
+          role: "alert",
+          "aria-live": "assertive",
+          children: !isDateInputValid ? 'Invalid date' : ''
         }), hasClear && value !== undefined && !isEffectivelyDisabled && /*#__PURE__*/_jsx("button", {
           type: "button",
           onClick: handleClear,
@@ -537,11 +589,17 @@ export function DateTimeInput({
           onFocus: handleTimeFocus,
           onBlur: handleTimeBlur,
           onKeyDown: handleTimeKeyDown,
-          placeholder: timePlaceholder,
-          disabled: isEffectivelyDisabled,
-          "aria-label": "Time",
+          placeholder: resolvedTimePlaceholder
+          // With a disabledMessage the input keeps focusability via
+          // aria-disabled so the reason is focus-discoverable; typing is
+          // blocked with readOnly and the mutation guards.
+          ,
+          disabled: isEffectivelyDisabled && !showsDisabledMessage,
+          "aria-disabled": showsDisabledMessage ? 'true' : undefined,
+          readOnly: showsDisabledMessage || undefined,
+          "aria-label": timeLabel ?? `${label} time`,
           "aria-required": isRequired === true ? 'true' : undefined,
-          "aria-invalid": status?.type === 'error' ? 'true' : undefined,
+          "aria-invalid": status?.type === 'error' || !isTimeInputValid ? 'true' : undefined,
           ...{
             0: {
               className: "x1lliihq x98rzlu xeuugli xc342km xng3xce x1717udv x9ynric xjm74w1 x6pjikd xw6l6zx x1tgivj0 xjbqb8w x1a2a7pz xeyghm5"
@@ -556,6 +614,11 @@ export function DateTimeInput({
               className: "x1lliihq x98rzlu xeuugli xc342km xng3xce x1717udv x9ynric xjm74w1 x6pjikd xw6l6zx xjbqb8w x1a2a7pz xeyghm5 x1h6gzvc xv1l7n4"
             }
           }[!!isEffectivelyDisabled << 1 | !!!isTimeInputValid << 0]
+        }), /*#__PURE__*/_jsx(VisuallyHidden, {
+          as: "div",
+          role: "alert",
+          "aria-live": "assertive",
+          children: !isTimeInputValid ? 'Invalid time' : ''
         })]
       })]
     }), popover.render(/*#__PURE__*/_jsx(Calendar, {
@@ -570,7 +633,7 @@ export function DateTimeInput({
     }), {
       placement: 'below',
       alignment: 'start'
-    })]
+    }), showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
   });
 }
 DateTimeInput.displayName = 'DateTimeInput';

package/dist/Dialog/Dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Dialog.d.ts","sourceRoot":"","sources":["../../src/Dialog/Dialog.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA6B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACjE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAmB5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAwBhD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,EAAE,IAAI,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAyHD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC/D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAE3C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,QAAgB,EAChB,YAAY,EACZ,KAAW,EACX,SAAkB,EAClB,QAAQ,EACR,OAAoB,EACpB,OAAgB,EAChB,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,sCA8Nb;yBA9Oe,MAAM"}
+{"version":3,"file":"Dialog.d.ts","sourceRoot":"","sources":["../../src/Dialog/Dialog.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAA6B,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AACjE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAoB5C,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAwBhD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,EAAE,IAAI,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAyHD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC/D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAE3C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;OAIG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;;OAGG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,QAAgB,EAChB,YAAY,EACZ,KAAW,EACX,SAAkB,EAClB,QAAQ,EACR,OAAoB,EACpB,OAAgB,EAChB,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,sCAyOb;yBAzPe,MAAM"}

package/dist/Dialog/Dialog.js

@@ -18,6 +18,7 @@
 import { useEffect, useMemo, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { useScrollLock } from "../hooks/useScrollLock.js";
+import { hasActiveFocusTrapEscape, isImeKeyEvent } from "../hooks/useFocusTrap.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, radiusVars, durationVars, easeVars, shadowVars } from "../theme/tokens.stylex.js";
 import { container } from "../Layout/container.stylex.js";
@@ -300,6 +301,12 @@ export function Dialog({
     }
     const handleKeyDown = event => {
       if (event.key === 'Escape') {
+        // Ignore IME composition-cancel, and defer to any popover/menu layered
+        // on top of this dialog so a single Escape closes only the top-most
+        // layer (the popover's own focus trap handles it and stops propagation).
+        if (isImeKeyEvent(event) || hasActiveFocusTrapEscape()) {
+          return;
+        }
         event.preventDefault();
         if (allowEscape) {
           onOpenChange(false);
@@ -324,6 +331,11 @@ export function Dialog({
   // Handle native cancel event (browser Escape handling)
   const handleCancel = event => {
     event.preventDefault();
+    // Defer to a popover/menu layered on top of this dialog; it will dismiss
+    // itself on the same Escape press.
+    if (hasActiveFocusTrapEscape()) {
+      return;
+    }
     if (allowEscape) {
       onOpenChange(false);
     }

package/dist/DropdownMenu/DropdownMenu.d.ts

@@ -51,13 +51,6 @@ interface DropdownMenuBaseProps extends BaseProps {
      * @default 'below'
      */
     placement?: LayerPlacement;
-    /**
-     * Whether to auto-focus the first menu item when the menu opens.
-     * Set to `false` for inline showcases or documentation previews
-     * where stealing focus is undesirable.
-     * @default true
-     */
-    hasAutoFocus?: boolean;
     'data-testid'?: string;
 }
 interface DropdownMenuDataProps extends DropdownMenuBaseProps {
@@ -69,7 +62,7 @@ interface DropdownMenuCompoundProps extends DropdownMenuBaseProps {
     children: ReactNode;
 }
 export type DropdownMenuProps = DropdownMenuDataProps | DropdownMenuCompoundProps;
-export declare function DropdownMenu({ button, isMenuOpen: controlledIsOpen, onOpenChange, menuWidth, onClick, hasChevron, placement, hasAutoFocus, className, style, xstyle, 'data-testid': testId, ...props }: DropdownMenuProps): React.JSX.Element;
+export declare function DropdownMenu({ button, isMenuOpen: controlledIsOpen, onOpenChange, menuWidth, onClick, hasChevron, placement, className, style, xstyle, 'data-testid': testId, ...props }: DropdownMenuProps): React.JSX.Element;
 export declare namespace DropdownMenu {
     var displayName: string;
 }

package/dist/DropdownMenu/DropdownMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DropdownMenu.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAOZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,EAAS,KAAK,WAAW,EAAC,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAStC,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAQtD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAwC5C,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,mBAAmB,GACnB,mBAAmB,CAAC;AAMxB,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAEnE,UAAU,qBAAsB,SAAQ,SAAS;IAC/C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,qBAAsB,SAAQ,qBAAqB;IAC3D,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,UAAU,yBAA0B,SAAQ,qBAAqB;IAC/D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GACzB,qBAAqB,GACrB,yBAAyB,CAAC;AA4B9B,wBAAgB,YAAY,CAAC,EAC3B,MAAuB,EACvB,UAAU,EAAE,gBAAgB,EAC5B,YAAY,EACZ,SAAS,EACT,OAAO,EACP,UAAiB,EACjB,SAAmB,EACnB,YAAmB,EACnB,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,iBAAiB,qBA4NnB;yBA1Oe,YAAY"}
+{"version":3,"file":"DropdownMenu.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenu.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,EAOZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,OAAO,EAAS,KAAK,WAAW,EAAC,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAUtC,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,mBAAmB,CAAC;AAQtD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAwC5C,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,oBAAoB,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,mBAAmB,GACnB,mBAAmB,CAAC;AAMxB,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAEnE,UAAU,qBAAsB,SAAQ,SAAS;IAC/C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,qBAAsB,SAAQ,qBAAqB;IAC3D,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,UAAU,yBAA0B,SAAQ,qBAAqB;IAC/D,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GACzB,qBAAqB,GACrB,yBAAyB,CAAC;AA4B9B,wBAAgB,YAAY,CAAC,EAC3B,MAAuB,EACvB,UAAU,EAAE,gBAAgB,EAC5B,YAAY,EACZ,SAAS,EACT,OAAO,EACP,UAAiB,EACjB,SAAmB,EACnB,SAAS,EACT,KAAK,EACL,MAAM,EACN,aAAa,EAAE,MAAM,EACrB,GAAG,KAAK,EACT,EAAE,iBAAiB,qBAqQnB;yBAlRe,YAAY"}

package/dist/DropdownMenu/DropdownMenu.js

@@ -29,6 +29,7 @@ import { Icon } from "../Icon/index.js";
 import { renderDropdownItems } from "./renderDropdownItems.js";
 import { DropdownMenuContext } from "./DropdownMenuContext.js";
 import { useListFocus } from "../hooks/useListFocus.js";
+import { useTypeahead } from "../hooks/useTypeahead.js";
 import { layerAnimations } from "../Layer/layerAnimations.stylex.js";
 import "../theme/tokens.stylex.js";
 import { spacingVars, radiusVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
@@ -118,7 +119,6 @@ export function DropdownMenu({
   onClick,
   hasChevron = true,
   placement = 'below',
-  hasAutoFocus = true,
   className,
   style,
   xstyle,
@@ -171,7 +171,10 @@ export function DropdownMenu({
     onShow: handleLayerShow,
     hasLightDismiss: true,
     hasCloseButton: false,
-    hasAutoFocus: false
+    hasAutoFocus: false,
+    // The popup's own role="menu" is the exposed semantics; wrapping it in a
+    // modal dialog would announce an unnamed dialog around the menu.
+    role: 'none'
   });
   const closeMenu = useCallback(() => {
     popover.hide();
@@ -181,28 +184,36 @@ export function DropdownMenu({
   const {
     listRef,
     handleKeyDown: listNavKeyDown,
-    focusFirst
+    focusFirst,
+    focusItem
   } = useListFocus({
     itemSelector: '[role="menuitem"]:not([aria-disabled="true"])',
     wrap: false,
     onEscape: closeMenu
   });
 
+  // First-character typeahead over the (enabled) menu items — jump to the next
+  // item whose label starts with the typed text (menus-11).
+  const getMenuItems = useCallback(() => listRef.current ? Array.from(listRef.current.querySelectorAll('[role="menuitem"]:not([aria-disabled="true"])')) : [], [listRef]);
+  const typeahead = useTypeahead({
+    getItemLabels: () => getMenuItems().map(el => el.textContent),
+    onMatch: focusItem,
+    getCurrentIndex: () => getMenuItems().findIndex(el => el === document.activeElement || el.contains(document.activeElement))
+  });
+
   // Sync controlled open state → popover, and focus first item on open
   useEffect(() => {
     if (isControlled) {
       if (controlledIsOpen && !popover.isOpen) {
         popover.show();
-        if (hasAutoFocus) {
-          requestAnimationFrame(() => focusFirst());
-        }
+        requestAnimationFrame(() => focusFirst());
       } else if (!controlledIsOpen && popover.isOpen) {
         popover.hide();
       }
     }
-  }, [controlledIsOpen, isControlled, popover, hasAutoFocus, focusFirst]);
+  }, [controlledIsOpen, isControlled, popover, focusFirst]);
 
-  // Extend useListFocus with Enter/Space activation
+  // Extend useListFocus with Enter/Space activation + typeahead
   const listKeyDown = useCallback(e => {
     if (e.key === 'Enter' || e.key === ' ') {
       e.preventDefault();
@@ -212,14 +223,26 @@ export function DropdownMenu({
       }
       return;
     }
+    // APG menu-button pattern: Tab closes the menu. Menu items are
+    // tabIndex={-1} so the focus trap has nothing trappable and Tab would
+    // otherwise leak into the page while the menu stayed open (menus-5).
+    // Do NOT preventDefault — closing restores focus to the trigger, and the
+    // browser's default Tab then continues from there to the next element.
+    if (e.key === 'Tab') {
+      closeMenu();
+      return;
+    }
+    // Type-to-focus next; if it consumed a printable key, stop here.
+    if (typeahead.onKeyDown(e)) {
+      e.preventDefault();
+      return;
+    }
     listNavKeyDown(e);
-  }, [listNavKeyDown]);
+  }, [listNavKeyDown, closeMenu, typeahead]);
   const openAndFocus = useCallback(() => {
     popover.show();
-    if (hasAutoFocus) {
-      requestAnimationFrame(() => focusFirst());
-    }
-  }, [popover, hasAutoFocus, focusFirst]);
+    requestAnimationFrame(() => focusFirst());
+  }, [popover, focusFirst]);
   const handleButtonClick = useCallback(() => {
     // If the menu was just closed by light dismiss (e.g. iOS Safari fires
     // pointerdown → hide before the trigger's click), the click would
@@ -292,7 +315,12 @@ export function DropdownMenu({
     }), popover.render(/*#__PURE__*/_jsx("div", {
       ref: listRef,
       id: menuId,
-      role: "menu",
+      role: "menu"
+      // Give the menu an accessible name from its trigger's label, so
+      // screen readers announce e.g. "Actions menu" rather than an unnamed
+      // menu (menus-13).
+      ,
+      "aria-label": button.label,
       onKeyDown: listKeyDown,
       ...mergeProps(themeProps('dropdown-menu'), stylex.props(styles.dropdown, xstyle), className, style),
       children: /*#__PURE__*/_jsx(DropdownMenuContext, {

package/dist/Field/Field.d.ts

@@ -49,9 +49,26 @@ export interface FieldProps extends Omit<BaseProps<HTMLDivElement>, 'children'>
      */
     description?: string;
     /**
-     * ID for the input element (used for label's htmlFor attribute).
+     * ID of the input element this label points AT (used as the label's
+     * `htmlFor`). This is the id of the *control*, not of the label element —
+     * see `labelID` for the latter.
      */
     inputID: string;
+    /**
+     * The `id` applied TO the label element itself (distinct from `inputID`,
+     * which is the control the label points at). A grouping control
+     * (radiogroup, checkbox group) references this via `aria-labelledby` to take
+     * the label as its accessible name. Pair with `isGroupLabel`.
+     */
+    labelID?: string;
+    /**
+     * When the field wraps a group of controls rather than a single input, set
+     * this so the label renders as a non-`<label>` element (a `<span>`): a
+     * `<label>` semantically names one control and can't be associated with a
+     * group. Pair with `labelID` + `aria-labelledby` on the group.
+     * @default false
+     */
+    isGroupLabel?: boolean;
     /**
      * ID for the description element (use for aria-describedby on the input).
      */
@@ -116,7 +133,7 @@ export interface FieldProps extends Omit<BaseProps<HTMLDivElement>, 'children'>
  * </Field>
  * ```
  */
-export declare function Field({ label, isLabelHidden, description, inputID, descriptionID, isOptional, isRequired, isDisabled, labelIcon, status, labelTooltip, statusVariant, width, xstyle, children, className, style, ref, ...props }: FieldProps): import("react").JSX.Element;
+export declare function Field({ label, isLabelHidden, description, inputID, labelID, isGroupLabel, descriptionID, isOptional, isRequired, isDisabled, labelIcon, status, labelTooltip, statusVariant, width, xstyle, children, className, style, ref, ...props }: FieldProps): import("react").JSX.Element;
 export declare namespace Field {
     var displayName: string;
 }

package/dist/Field/Field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Field.d.ts","sourceRoot":"","sources":["../../src/Field/Field.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAM,MAAM,OAAO,CAAC;AAE1C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAI9C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAoCtC,YAAY,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,IAAI,EAAE,eAAe,CAAC;IACtB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAW,SAAQ,IAAI,CACtC,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,OAAO,EACP,aAAa,EACb,UAAkB,EAClB,UAAkB,EAClB,UAAkB,EAClB,SAAS,EACT,MAAM,EACN,YAAY,EACZ,aAA0B,EAC1B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,UAAU,+BAsGZ;yBA1He,KAAK"}
+{"version":3,"file":"Field.d.ts","sourceRoot":"","sources":["../../src/Field/Field.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAM,MAAM,OAAO,CAAC;AAE1C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAI9C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAoCtC,YAAY,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,IAAI,EAAE,eAAe,CAAC;IACtB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAW,SAAQ,IAAI,CACtC,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,OAAO,EACP,OAAO,EACP,YAAoB,EACpB,aAAa,EACb,UAAkB,EAClB,UAAkB,EAClB,UAAkB,EAClB,SAAS,EACT,MAAM,EACN,YAAY,EACZ,aAA0B,EAC1B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,UAAU,+BAqGZ;yBA3He,KAAK"}

package/dist/Field/Field.js

@@ -69,6 +69,8 @@ export function Field({
   isLabelHidden = false,
   description,
   inputID,
+  labelID,
+  isGroupLabel = false,
   descriptionID,
   isOptional = false,
   isRequired = false,
@@ -97,6 +99,8 @@ export function Field({
   const labelNode = /*#__PURE__*/_jsx(FieldLabel, {
     label: label,
     inputID: inputID,
+    labelID: labelID,
+    isGroupLabel: isGroupLabel,
     isLabelHidden: isLabelHidden,
     isDisabled: isDisabled,
     isOptional: isOptional,