@westpac/ui 1.16.0 → 1.19.0

package/src/components/link/link.types.ts

@@ -1,9 +1,9 @@
-import { AnchorHTMLAttributes, ReactNode } from 'react';
+import { ReactNode } from 'react';
 import { AriaLinkOptions } from 'react-aria';
 
 import { IconProps } from '../icon/index.js';
 
-export type LinkProps = {
+export type BaseLinkProps = {
   /**
    * Link text or component
    */
@@ -35,5 +35,32 @@ export type LinkProps = {
    * @default true
    */
   underline?: boolean;
-} & Omit<AriaLinkOptions, 'isDisabled' | 'elementType'> &
-  AnchorHTMLAttributes<Element>;
+  /**
+   * Specifies DOM element rendered by a custom component
+   * Required when the custom component does not render an '<a>' element
+   * @default 'a'
+   */
+  elementType?: AriaLinkOptions['elementType'];
+} & Omit<AriaLinkOptions, 'elementType' | 'href' | 'isDisabled'>;
+
+export type LinkRef<C extends React.ElementType = 'a'> = React.ComponentRef<C>;
+
+export type PolymorphicRef<C extends React.ElementType> = React.ComponentPropsWithRef<C>['ref'];
+
+export type LinkProps<C extends React.ElementType = 'a'> = BaseLinkProps & {
+  /**
+   * Type to render
+   * @default a
+   */
+  tag?: C;
+} & Omit<React.ComponentPropsWithoutRef<C>, keyof BaseLinkProps | 'tag'>;
+
+export type LinkImplementationProps = BaseLinkProps & {
+  className?: string;
+  href?: unknown;
+  tag?: React.ElementType;
+} & Record<string, unknown>;
+
+export type LinkComponent = <C extends React.ElementType = 'a'>(
+  props: LinkProps<C> & { ref?: PolymorphicRef<C> },
+) => React.ReactElement | null;

package/src/components/modal/components/modal-dialog/components/modal-dialog-footer/modal-dialog-footer.component.tsx

@@ -12,8 +12,10 @@ import { type ModalDialogFooterProps } from './modal-dialog-footer.types.js';
 
 export function ModalDialogFooter({
   className,
+  primaryButtonProps,
   primaryLabel,
   primaryOnClick,
+  secondaryButtonProps,
   secondaryLabel,
   secondaryOnClick,
   ...props
@@ -29,11 +31,23 @@ export function ModalDialogFooter({
 
   return (
     <div className={styles.base({ className })} {...props}>
-      <Button look="primary" size="large" className={styles.primaryBtn()} onClick={primaryOnClick}>
+      <Button
+        {...primaryButtonProps}
+        look={primaryButtonProps?.look ?? 'primary'}
+        size={primaryButtonProps?.size ?? 'large'}
+        className={styles.primaryBtn({ className: primaryButtonProps?.className })}
+        onClick={primaryOnClick}
+      >
         {primaryLabel}
       </Button>
       {secondaryLabel && (
-        <Button look="link" size="large" className={styles.secondaryBtn()} onClick={secondaryOnClick}>
+        <Button
+          {...secondaryButtonProps}
+          look={secondaryButtonProps?.look ?? 'link'}
+          size={secondaryButtonProps?.size ?? 'large'}
+          className={styles.secondaryBtn({ className: secondaryButtonProps?.className })}
+          onClick={secondaryOnClick}
+        >
           {secondaryLabel}
         </Button>
       )}

package/src/components/modal/components/modal-dialog/components/modal-dialog-footer/modal-dialog-footer.types.ts

@@ -1,10 +1,18 @@
 import { HTMLAttributes, ReactNode } from 'react';
 
+import { type ButtonProps } from '../../../../../button/index.js';
+
+type ModalFooterButtonProps = Omit<ButtonProps, 'children' | 'onClick'>;
+
 export type ModalDialogFooterProps = {
   /**
    * Footer content
    */
   children?: ReactNode;
+  /**
+   * Props passed to the primary button
+   */
+  primaryButtonProps?: ModalFooterButtonProps;
   /**
    * Label for primary button
    */
@@ -13,6 +21,10 @@ export type ModalDialogFooterProps = {
    * onClick for primary button
    */
   primaryOnClick: () => void;
+  /**
+   * Props passed to the secondary button
+   */
+  secondaryButtonProps?: ModalFooterButtonProps;
   /**
    * Label for secondary button
    */

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';