@westpac/ui 1.18.0 → 1.19.0

package/src/components/date-picker/date-picker.component.tsx

@@ -2,7 +2,7 @@
 
 import { DateValue, getDayOfWeek, isWeekend } from '@internationalized/date';
 import { Breakpoint } from '@westpac/style-config/constants';
-import React, { useMemo, useRef } from 'react';
+import React, { ForwardedRef, forwardRef, useMemo, useRef } from 'react';
 import { useButton, useDatePicker, useLocale } from 'react-aria';
 import { useDatePickerState } from 'react-stately';
 
@@ -19,19 +19,24 @@ import { styles as datePickerStyles } from './date-picker.styles.js';
 import { type DatePickerProps } from './date-picker.types.js';
 
 const BREAKPOINTS_DECRECENT = ['xl', 'lg', 'md', 'sm', 'xsl', 'initial'] as const;
-export function DatePicker({
-  size = 'medium',
-  className,
-  bottomSheetView = { initial: true, xsl: false },
-  block,
-  isDateUnavailable,
-  disableDaysOfWeek,
-  disableWeekends,
-  separator,
-  portalContainer,
-  placement = 'bottom left',
-  ...props
-}: DatePickerProps) {
+function BaseDatePicker(
+  {
+    size = 'medium',
+    className,
+    bottomSheetView = { initial: true, xsl: false },
+    block,
+    isDateUnavailable,
+    disableDaysOfWeek,
+    disableWeekends,
+    separator,
+    portalContainer,
+    placement = 'bottom left',
+    ...props
+  }: DatePickerProps,
+  // Attached to the first editable date segment, so `ref.current.focus()` (e.g. react-hook-form
+  // focusing a field with a validation error) lands on a focusable control.
+  forwardedRef: ForwardedRef<HTMLSpanElement>,
+) {
   const { locale } = useLocale();
 
   const enhancedIsDateUnavailable = useMemo(() => {
@@ -60,7 +65,7 @@ export function DatePicker({
     isReadOnly: props.isReadOnly,
     isDisabled: props.isDisabled,
   });
-  const ref = useRef(null);
+  const ref = useRef<HTMLDivElement>(null);
 
   const { groupProps, labelProps, fieldProps, buttonProps, dialogProps, calendarProps } = useDatePicker(
     { isDateUnavailable: enhancedIsDateUnavailable, ...props },
@@ -84,12 +89,15 @@ export function DatePicker({
 
   const { buttonProps: newButtonProps } = useButton(buttonProps, buttonRef);
 
+  // This is required so branding applies correctly by default due to portal location, can be overridden with portalContainer prop
   const brandContainer = useMemo(() => {
-    return (
-      document.querySelector('[data-brand]') ||
-      document.querySelector('[class^="theme-"], [class*=" theme-"]') ||
-      undefined
-    );
+    if (typeof window !== 'undefined') {
+      return (
+        document.querySelector('[data-brand]') ||
+        document.querySelector('[class^="theme-"], [class*=" theme-"]') ||
+        undefined
+      );
+    }
   }, []);
 
   return (
@@ -107,7 +115,7 @@ export function DatePicker({
         }}
         className={styles.input({ className })}
       >
-        <DateField className={styles.dateField()} separator={separator} {...fieldProps} />
+        <DateField className={styles.dateField()} separator={separator} {...fieldProps} ref={forwardedRef} />
         <Button
           look="faint"
           className={styles.button()}
@@ -134,3 +142,6 @@ export function DatePicker({
     </>
   );
 }
+
+export const DatePicker = forwardRef(BaseDatePicker);
+DatePicker.displayName = 'DatePicker';

package/src/components/date-picker/date-picker.styles.ts

@@ -3,26 +3,26 @@ import { tv } from 'tailwind-variants';
 export const styles = tv({
   slots: {
     input: 'form-control flex items-center border-0',
-    dateField: 'rounded rounded-r-none border border-r-0 border-border-muted-strong',
+    dateField: 'rounded rounded-r-none border border-r-0 border-border-muted-strong whitespace-nowrap',
     button: 'flex items-center justify-center rounded-l-none border-border-muted-strong bg-surface-muted-pale',
   },
   variants: {
     size: {
       small: {
         input: 'max-h-5',
-        dateField: 'h-5 w-[120px] form-control-small',
+        dateField: 'h-5 min-w-[120px] form-control-small',
       },
       medium: {
         input: 'max-h-6',
-        dateField: 'h-6 w-[140px] form-control-medium',
+        dateField: 'h-6 min-w-[140px] form-control-medium',
       },
       large: {
         input: 'max-h-7',
-        dateField: 'h-7 w-[145px] form-control-large',
+        dateField: 'h-7 min-w-[145px] form-control-large',
       },
       xlarge: {
         input: 'max-h-8',
-        dateField: 'h-8 w-[165px] form-control-xlarge',
+        dateField: 'h-8 min-w-[165px] form-control-xlarge',
       },
     },
     block: {

package/src/components/multi-select/components/multi-select-list-box/components/multi-select-option/multi-select-option.component.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import { focusWithoutScrolling } from '@react-aria/utils';
 import React, { useCallback, useContext, useRef, KeyboardEvent } from 'react';
 import { mergeProps, useFocusRing, useOption } from 'react-aria';
 
@@ -27,11 +28,8 @@ export function MultiSelectOption<T>({ item }: MultiSelectOptionProps<T>) {
     (e: KeyboardEvent<HTMLLIElement>) => {
       if (e.key === 'ArrowUp' && item.index === 0) {
         e.preventDefault();
-        if (selectAllRef.current) {
-          selectAllRef.current?.focus();
-        } else {
-          inputRef.current?.focus();
-        }
+        const target = selectAllRef.current || inputRef.current;
+        if (target) focusWithoutScrolling(target);
       }
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();

package/src/components/multi-select/components/multi-select-list-box/components/multi-select-select-all-option/multi-select-select-all-option.component.tsx

@@ -1,5 +1,6 @@
 'use client';
 
+import { focusWithoutScrolling } from '@react-aria/utils';
 import React, { useCallback, useContext, useMemo, KeyboardEvent } from 'react';
 import { useOption, useFocusRing, mergeProps } from 'react-aria';
 
@@ -54,12 +55,12 @@ export function MultiSelectSelectAllOption() {
     (e: KeyboardEvent<HTMLDivElement>) => {
       if (e.key === 'ArrowDown') {
         e.preventDefault();
-        const firstItem = listBoxRef.current?.querySelector('[data-key]') as HTMLElement;
-        firstItem?.focus();
+        const firstItem = listBoxRef.current?.querySelector('[data-key]') as HTMLElement | null;
+        if (firstItem) focusWithoutScrolling(firstItem);
       }
       if (e.key === 'ArrowUp') {
         e.preventDefault();
-        inputRef.current?.focus();
+        if (inputRef.current) focusWithoutScrolling(inputRef.current);
       }
       if (e.key === 'Enter' || e.key === ' ') {
         e.preventDefault();

package/src/components/multi-select/components/multi-select-popover/multi-select-popover.component.tsx

@@ -24,6 +24,13 @@ export function MultiSelectPopover({ children, className, ...props }: MultiSelec
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // react-aria assumes a non-modal popover never receives DOM focus, so it closes it whenever the page
+  // scrolls (useOverlayPosition -> useCloseOnScroll via `state.close`). Focus does move into this popover
+  // (filter input / options), and browsers may scroll the page when it does, which closed the dropdown
+  // mid keyboard navigation. Dismissal (blur, Escape, Tab, DismissButton) is handled explicitly below, so
+  // give react-aria a state it cannot close.
+  const positioningState = { ...overlayState, close: () => undefined };
+
   const { popoverProps } = usePopover(
     {
       ...props,
@@ -35,7 +42,7 @@ export function MultiSelectPopover({ children, className, ...props }: MultiSelec
       shouldCloseOnInteractOutside: () => false, // need to manage accessibility manually due to complexity of component
       offset: 6,
     },
-    overlayState,
+    positioningState,
   );
 
   // This is required so branding applies correctly by default due to portal location, can be overridden with portalContainer prop
@@ -80,7 +87,6 @@ export function MultiSelectPopover({ children, className, ...props }: MultiSelec
           }
         }}
         role="dialog"
-        aria-modal="true"
         aria-label="Options list with filter"
       >
         {children}

package/src/components/multi-select/components/multi-select-searchbar/multi-select-searchbar.component.tsx

@@ -1,3 +1,4 @@
+import { focusWithoutScrolling } from '@react-aria/utils';
 import React, { useContext, useCallback, KeyboardEvent } from 'react';
 
 import { Button } from '../../../../components/button/index.js';
@@ -21,12 +22,8 @@ export function MultiSelectSearchbar({
     (e: KeyboardEvent<HTMLInputElement>) => {
       if (e.key === 'ArrowDown') {
         e.preventDefault();
-        if (selectAllRef.current) {
-          selectAllRef.current.focus();
-        } else {
-          const firstItem = listBoxRef.current?.querySelector('[data-key]') as HTMLElement;
-          firstItem?.focus();
-        }
+        const target = selectAllRef.current || (listBoxRef.current?.querySelector('[data-key]') as HTMLElement | null);
+        if (target) focusWithoutScrolling(target);
       }
       if (e.key === 'Escape' && filterText.length > 0) {
         e.stopPropagation();

package/src/components/multi-select/multi-select.component.tsx

@@ -1,8 +1,9 @@
 'use client';
 
+import { focusWithoutScrolling } from '@react-aria/utils';
 import { Node } from '@react-types/shared';
-import React, { useRef, useState, memo, createContext } from 'react';
-import { useFilter, useOverlayTrigger } from 'react-aria';
+import React, { ForwardedRef, forwardRef, useRef, useState, memo, createContext } from 'react';
+import { useFilter, useObjectRef, useOverlayTrigger } from 'react-aria';
 import { Item, useListState, useOverlayTriggerState } from 'react-stately';
 
 import { MultiSelectDropdown } from './components/multi-select-dropdown/multi-select-dropdown.component.js';
@@ -30,22 +31,25 @@ export const MultiSelectContext = createContext<MultiSelectContextProps>({
   hideSelectAll: false,
 });
 
-export function BaseMultiSelect<T extends MultiSelectValue = MultiSelectValue>({
-  size = 'medium',
-  listBoxProps,
-  selectionMode = 'multiple',
-  selectedKeys,
-  onSelectionChange,
-  placeholder = 'Select',
-  showSingleSectionTitle = false,
-  placement = 'bottom left',
-  portalContainer,
-  id,
-  hideFilter = false,
-  hideSelectAll = false,
-  width = 'full',
-  ...props
-}: MultiSelectProps<T>) {
+export function BaseMultiSelect<T extends MultiSelectValue = MultiSelectValue>(
+  {
+    size = 'medium',
+    listBoxProps,
+    selectionMode = 'multiple',
+    selectedKeys,
+    onSelectionChange,
+    placeholder = 'Select',
+    showSingleSectionTitle = false,
+    placement = 'bottom left',
+    portalContainer,
+    id,
+    hideFilter = false,
+    hideSelectAll = false,
+    width = 'full',
+    ...props
+  }: MultiSelectProps<T>,
+  forwardedRef: ForwardedRef<HTMLButtonElement>,
+) {
   const [filterText, setFilterText] = useState('');
   const filter = useFilter({ sensitivity: 'base' });
 
@@ -62,7 +66,7 @@ export function BaseMultiSelect<T extends MultiSelectValue = MultiSelectValue>({
 
   // refs
   const inputRef = useRef<HTMLInputElement>(null);
-  const buttonRef = useRef<HTMLButtonElement>(null);
+  const buttonRef = useObjectRef(forwardedRef);
   const popoverRef = useRef<HTMLDivElement>(null);
   const selectAllRef = useRef<HTMLInputElement>(null);
   const listBoxRef = useRef<HTMLUListElement>(null);
@@ -70,15 +74,14 @@ export function BaseMultiSelect<T extends MultiSelectValue = MultiSelectValue>({
   const overlayState = useOverlayTriggerState({
     onOpenChange: isOpen => {
       if (isOpen) {
+        // Focus moves into the popover without scrolling the page (react-aria's own focus helper), so the
+        // dropdown does not jump around, and page scroll cannot dismiss it while the user navigates.
         requestAnimationFrame(() => {
-          if (!hideFilter) {
-            inputRef.current?.focus();
-          } else if (selectionMode === 'multiple' && !hideSelectAll) {
-            selectAllRef.current?.focus();
-          } else {
-            const firstItem = listBoxRef.current?.querySelector('[data-key]') as HTMLElement;
-            firstItem?.focus();
-          }
+          const target =
+            (!hideFilter && inputRef.current) ||
+            (selectionMode === 'multiple' && !hideSelectAll && selectAllRef.current) ||
+            (listBoxRef.current?.querySelector('[data-key]') as HTMLElement | null);
+          if (target) focusWithoutScrolling(target);
         });
       }
       if (!isOpen) {
@@ -124,7 +127,9 @@ export function BaseMultiSelect<T extends MultiSelectValue = MultiSelectValue>({
     </MultiSelectContext.Provider>
   );
 }
-export const MultiSelect = memo(BaseMultiSelect);
+
+export const MultiSelect = memo(forwardRef(BaseMultiSelect));
+MultiSelect.displayName = 'MultiSelect';
 
 // Exporting react-stately's Item with custom props/naming and Section with custom naming to align with other components
 export const MultiSelectItem = Item as (props: MultiSelectItemProps) => JSX.Element;

package/src/components/radio-group/components/radio-group-radio/radio-group-radio.component.tsx

@@ -1,24 +1,27 @@
 'use client';
 
-import React, { Ref, forwardRef, useContext, useRef } from 'react';
-import { VisuallyHidden, mergeProps, useFocusRing, useRadio } from 'react-aria';
+import React, { ForwardedRef, forwardRef, useContext } from 'react';
+import { VisuallyHidden, mergeProps, useFocusRing, useObjectRef, useRadio } from 'react-aria';
 
 import { RadioGroupContext } from '../../radio-group.component.js';
 
 import { styles as radioStyles } from './radio-group-radio.styles.js';
 import { type RadioGroupRadioProps } from './radio-group-radio.types.js';
 
-function BaseRadioGroupRadio({ className, hint, label, ...props }: RadioGroupRadioProps, ref: Ref<HTMLLabelElement>) {
+function BaseRadioGroupRadio(
+  { className, hint, label, ...props }: RadioGroupRadioProps,
+  ref: ForwardedRef<HTMLInputElement>,
+) {
   const { state, size, orientation } = useContext(RadioGroupContext);
-  const localRef = useRef(null);
-  const { inputProps, labelProps, isSelected, isDisabled } = useRadio({ ...props, children: label }, state, localRef);
+  const inputRef = useObjectRef(ref);
+  const { inputProps, labelProps, isSelected, isDisabled } = useRadio({ ...props, children: label }, state, inputRef);
   const { isFocusVisible, focusProps } = useFocusRing();
   const styles = radioStyles({ isDisabled, isSelected, isFocusVisible, size, orientation });
 
   return (
-    <label className={styles.base({ className })} ref={ref} {...labelProps}>
+    <label className={styles.base({ className })} {...labelProps}>
       <VisuallyHidden elementType="span">
-        <input {...mergeProps(inputProps, focusProps)} ref={localRef} />
+        <input {...mergeProps(inputProps, focusProps)} ref={inputRef} />
       </VisuallyHidden>
       <span className={styles.selector()} />
       <span className={styles.textWrapper()}>

package/src/components/radio-group/radio-group.component.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import React, { createContext, useEffect, useId, useMemo, useRef, useState } from 'react';
+import React, { ForwardedRef, createContext, forwardRef, useEffect, useId, useMemo, useRef, useState } from 'react';
 import { useFocusRing, useRadioGroup } from 'react-aria';
 import { useRadioGroupState } from 'react-stately';
 
 import { FUNCTION_NOT_IMPLEMENTED } from '../../constants/message.js';
 import { useBreakpoint } from '../../hook/breakpoints.hook.js';
+import { FocusHandle, acceptInputs, useFocusManagerRef } from '../../hook/focus-manager-ref.hook.js';
 import { resolveResponsiveVariant } from '../../utils/breakpoint.util.js';
 import { Button } from '../button/index.js';
 import { ExpandMoreIcon } from '../icon/index.js';
@@ -75,17 +76,23 @@ export const RadioGroupContext = createContext<RadioGroupContextState>({
   },
 });
 
-export function RadioGroup({
-  className,
-  radios,
-  label,
-  orientation = 'vertical',
-  showAmount = 0,
-  size = 'medium',
-  errorMessage,
-  hintMessage,
-  ...props
-}: RadioGroupProps) {
+function BaseRadioGroup(
+  {
+    className,
+    radios,
+    label,
+    orientation = 'vertical',
+    showAmount = 0,
+    size = 'medium',
+    errorMessage,
+    hintMessage,
+    ...props
+  }: RadioGroupProps,
+  // `ref.current.focus()` (e.g. react-hook-form focusing a field with a validation error) moves focus
+  // to the group's tab stop: the selected radio, or the first enabled radio when nothing is selected.
+  ref: ForwardedRef<FocusHandle>,
+) {
+  const wrapperRef = useFocusManagerRef(ref, { accept: acceptInputs });
   const breakpoint = useBreakpoint();
   const resolvedOrientation = resolveResponsiveVariant(orientation, breakpoint);
   const resolvedSize = resolveResponsiveVariant(size, breakpoint);
@@ -96,7 +103,7 @@ export function RadioGroup({
   );
   const { isFocusVisible, focusProps } = useFocusRing();
   const [hiddenOptions, setHiddenOptions] = useState<boolean>(showAmount > 0);
-  const firstNewRadioRef = useRef<HTMLLabelElement>(null);
+  const firstNewRadioRef = useRef<HTMLInputElement>(null);
   const revealAmount = radios && radios.length - showAmount;
   const styles = radioGroupStyles({ orientation: resolvedOrientation, isFocusVisible });
   const panelId = useId();
@@ -119,7 +126,7 @@ export function RadioGroup({
       <Label {...labelProps}>{label}</Label>
       {hintMessage && <Hint {...descriptionProps}>{hintMessage}</Hint>}
       {errorMessage && state.isInvalid && <ErrorMessage {...errorMessageProps} message={errorMessage} />}
-      <div className={styles.radioWrapper()} id={panelId}>
+      <div className={styles.radioWrapper()} id={panelId} ref={wrapperRef}>
         <RadioGroupContext.Provider value={{ state, orientation: resolvedOrientation, size: resolvedSize }}>
           {childrenToRender}
         </RadioGroupContext.Provider>
@@ -142,3 +149,6 @@ export function RadioGroup({
     </div>
   );
 }
+
+export const RadioGroup = forwardRef(BaseRadioGroup);
+RadioGroup.displayName = 'RadioGroup';

package/src/components/selector/components/selector-button-group/selector-button-group.component.tsx

@@ -1,9 +1,10 @@
 'use client';
 
-import React, { createContext, useCallback, useMemo, useState } from 'react';
+import React, { ForwardedRef, createContext, forwardRef, useCallback, useMemo, useState } from 'react';
 import { useField } from 'react-aria';
 
 import { useBreakpoint } from '../../../../hook/breakpoints.hook.js';
+import { FocusHandle, useFocusManagerRef } from '../../../../hook/focus-manager-ref.hook.js';
 import { resolveResponsiveVariant } from '../../../../utils/breakpoint.util.js';
 import { ErrorMessage, Hint, Label } from '../../../index.js';
 
@@ -17,18 +18,23 @@ export const SelectorButtonContext = createContext<SelectorButtonGroupContextSta
   isDisabled: undefined,
 });
 
-export function SelectorButtonGroup({
-  className,
-  children,
-  label,
-  orientation = 'vertical',
-  errorMessage,
-  description,
-  value = '',
-  onChange,
-  isDisabled,
-  ...props
-}: SelectorButtonGroupProps) {
+function BaseSelectorButtonGroup(
+  {
+    className,
+    children,
+    label,
+    orientation = 'vertical',
+    errorMessage,
+    description,
+    value = '',
+    onChange,
+    isDisabled,
+    ...props
+  }: SelectorButtonGroupProps,
+  // `ref.current.focus()` moves focus to the first tabbable option button.
+  ref: ForwardedRef<FocusHandle>,
+) {
+  const wrapperRef = useFocusManagerRef(ref);
   const isControlled = onChange !== undefined;
   const onChangeCallback = onChange as ((value: string) => void) | undefined;
   const [selected, setSelected] = useState(value);
@@ -69,9 +75,12 @@ export function SelectorButtonGroup({
       {label && <Label {...labelProps}>{label}</Label>}
       {description && <Hint {...descriptionProps}>{description}</Hint>}
       {errorMessage && <ErrorMessage {...errorMessageProps} message={errorMessage} />}
-      <div className={styles({ className, orientation: resolvedOrientation })} {...fieldProps}>
+      <div className={styles({ className, orientation: resolvedOrientation })} {...fieldProps} ref={wrapperRef}>
         <SelectorButtonContext.Provider value={state}>{children}</SelectorButtonContext.Provider>
       </div>
     </>
   );
 }
+
+export const SelectorButtonGroup = forwardRef(BaseSelectorButtonGroup);
+SelectorButtonGroup.displayName = 'SelectorButtonGroup';

package/src/components/selector/components/selector-checkbox-group/selector-checkbox-group.component.tsx

@@ -1,10 +1,11 @@
 'use client';
 
-import React, { createContext } from 'react';
+import React, { ForwardedRef, createContext, forwardRef } from 'react';
 import { useCheckboxGroup } from 'react-aria';
 import { useCheckboxGroupState } from 'react-stately';
 
 import { FUNCTION_NOT_IMPLEMENTED } from '../../../../constants/message.js';
+import { FocusHandle, useFocusManagerRef } from '../../../../hook/focus-manager-ref.hook.js';
 import { ErrorMessage, Hint, Label } from '../../../index.js';
 
 import { styles } from './selector-checkbox-group.styles.js';
@@ -74,8 +75,13 @@ export const SelectorCheckboxGroupContext = createContext<SelectorCheckboxGroupC
   },
 });
 
-export function SelectorCheckboxGroup(props: SelectorCheckboxGroupProps) {
+function BaseSelectorCheckboxGroup(
+  props: SelectorCheckboxGroupProps,
+  // `ref.current.focus()` moves focus to the first tabbable checkbox input.
+  ref: ForwardedRef<FocusHandle>,
+) {
   const { children, label, description, errorMessage } = props;
+  const wrapperRef = useFocusManagerRef(ref);
   const state = useCheckboxGroupState(props);
   const { groupProps, labelProps, descriptionProps, errorMessageProps } = useCheckboxGroup(props, state);
 
@@ -84,9 +90,12 @@ export function SelectorCheckboxGroup(props: SelectorCheckboxGroupProps) {
       {label && <Label {...labelProps}>{label}</Label>}
       {description && <Hint {...descriptionProps}>{description}</Hint>}
       {errorMessage && state.isInvalid && <ErrorMessage {...errorMessageProps} message={errorMessage} />}
-      <div {...groupProps} className={styles({ className: groupProps.className })}>
+      <div {...groupProps} className={styles({ className: groupProps.className })} ref={wrapperRef}>
         <SelectorCheckboxGroupContext.Provider value={state}>{children}</SelectorCheckboxGroupContext.Provider>
       </div>
     </>
   );
 }
+
+export const SelectorCheckboxGroup = forwardRef(BaseSelectorCheckboxGroup);
+SelectorCheckboxGroup.displayName = 'SelectorCheckboxGroup';

package/src/components/selector/components/selector-radio-group/selector-radio-group.component.tsx

@@ -1,11 +1,12 @@
 'use client';
 
-import React, { createContext } from 'react';
+import React, { ForwardedRef, createContext, forwardRef } from 'react';
 import { useRadioGroup } from 'react-aria';
 import { useRadioGroupState } from 'react-stately';
 
 import { FUNCTION_NOT_IMPLEMENTED } from '../../../../constants/message.js';
 import { useBreakpoint } from '../../../../hook/breakpoints.hook.js';
+import { FocusHandle, useFocusManagerRef } from '../../../../hook/focus-manager-ref.hook.js';
 import { resolveResponsiveVariant } from '../../../../utils/breakpoint.util.js';
 import { ErrorMessage, Hint, Label } from '../../../index.js';
 
@@ -73,15 +74,21 @@ export const SelectorRadioGroupContext = createContext<SelectorRadioGroupContext
   },
 });
 
-export function SelectorRadioGroup({
-  className,
-  children,
-  label,
-  orientation = 'vertical',
-  errorMessage,
-  description,
-  ...props
-}: SelectorRadioGroupProps) {
+function BaseSelectorRadioGroup(
+  {
+    className,
+    children,
+    label,
+    orientation = 'vertical',
+    errorMessage,
+    description,
+    ...props
+  }: SelectorRadioGroupProps,
+  // `ref.current.focus()` moves focus to the group's tab stop: the selected radio, or the first
+  // enabled radio when nothing is selected.
+  ref: ForwardedRef<FocusHandle>,
+) {
+  const wrapperRef = useFocusManagerRef(ref);
   const breakpoint = useBreakpoint();
   const resolvedOrientation = resolveResponsiveVariant(orientation, breakpoint);
   const state = useRadioGroupState({ ...props, errorMessage, label, orientation: resolvedOrientation });
@@ -95,7 +102,7 @@ export function SelectorRadioGroup({
       {label && <Label {...labelProps}>{label}</Label>}
       {description && <Hint {...descriptionProps}>{description}</Hint>}
       {errorMessage && state.isInvalid && <ErrorMessage {...errorMessageProps} message={errorMessage} />}
-      <div className={styles({ className, orientation: resolvedOrientation })} {...radioGroupProps}>
+      <div className={styles({ className, orientation: resolvedOrientation })} {...radioGroupProps} ref={wrapperRef}>
         <SelectorRadioGroupContext.Provider value={{ state, orientation: resolvedOrientation }}>
           {children}
         </SelectorRadioGroupContext.Provider>
@@ -103,3 +110,6 @@ export function SelectorRadioGroup({
     </>
   );
 }
+
+export const SelectorRadioGroup = forwardRef(BaseSelectorRadioGroup);
+SelectorRadioGroup.displayName = 'SelectorRadioGroup';

package/src/components/selector/selector.component.tsx

@@ -1,6 +1,8 @@
 'use client';
 
-import React from 'react';
+import React, { ForwardedRef, forwardRef } from 'react';
+
+import { FocusHandle } from '../../hook/focus-manager-ref.hook.js';
 
 import {
   SelectorButtonGroup,
@@ -11,17 +13,26 @@ import {
 import { type SelectorProps } from './selector.types.js';
 
 // TODO: react-aria doesn't consider the click as focus. so the focusRing will appeared just with the tab.
-export function Selector(props: SelectorProps) {
+function BaseSelector(
+  props: SelectorProps,
+  // `ref.current.focus()` (e.g. react-hook-form focusing a field with a validation error) moves
+  // focus to the first tabbable option (radio/checkbox input or button).
+  // The `link` type is navigation, not a form field, and does not receive the ref.
+  ref: ForwardedRef<FocusHandle>,
+) {
   if (props.type === 'checkbox') {
-    return <SelectorCheckboxGroup {...props} />;
+    return <SelectorCheckboxGroup {...props} ref={ref} />;
   }
   if (props.type === 'radio') {
-    return <SelectorRadioGroup {...props} />;
+    return <SelectorRadioGroup {...props} ref={ref} />;
   }
   if (props.type === 'button') {
-    return <SelectorButtonGroup {...props} />;
+    return <SelectorButtonGroup {...props} ref={ref} />;
   }
   if (props.type === 'link') {
     return <SelectorLinkGroup {...props} />;
   }
 }
+
+export const Selector = forwardRef(BaseSelector);
+Selector.displayName = 'Selector';