@westpac/ui 1.18.0 → 1.19.0

package/src/components/switch/switch.component.tsx

@@ -1,7 +1,7 @@
 'use client';
 
-import React, { useId, useRef } from 'react';
-import { VisuallyHidden, mergeProps, useCheckbox, useFocusRing } from 'react-aria';
+import React, { ForwardedRef, forwardRef, useId } from 'react';
+import { VisuallyHidden, mergeProps, useCheckbox, useFocusRing, useObjectRef } from 'react-aria';
 import { useToggleState } from 'react-stately';
 
 import { useBreakpoint } from '../../hook/breakpoints.hook.js';
@@ -10,18 +10,13 @@ import { resolveResponsiveVariant } from '../../utils/breakpoint.util.js';
 import { styles as switchStyles } from './switch.styles.js';
 import { type SwitchProps } from './switch.types.js';
 
-export function Switch({
-  className,
-  label,
-  size = 'medium',
-  block = false,
-  checked = false,
-  isDisabled,
-  ...props
-}: SwitchProps) {
+function BaseSwitch(
+  { className, label, size = 'medium', block = false, checked = false, isDisabled, ...props }: SwitchProps,
+  forwardedRef: ForwardedRef<HTMLInputElement>,
+) {
   const state = useToggleState({ ...props, defaultSelected: checked });
   const labelId = useId();
-  const ref = useRef(null);
+  const ref = useObjectRef(forwardedRef);
   const { isSelected } = state;
   const { inputProps, labelProps } = useCheckbox(
     { isDisabled, 'aria-labelledby': labelId, defaultSelected: checked, ...props },
@@ -50,3 +45,6 @@ export function Switch({
     </label>
   );
 }
+
+export const Switch = forwardRef(BaseSwitch);
+Switch.displayName = 'Switch';

package/src/hook/focus-manager-ref.hook.ts

@@ -0,0 +1,56 @@
+'use client';
+
+import { createFocusManager } from '@react-aria/focus';
+import { ForwardedRef, RefObject, useImperativeHandle, useRef } from 'react';
+
+/**
+ * Imperative handle exposed by group fields (`RadioGroup`, `CheckboxGroup`, `Selector`, `ButtonGroup`) whose
+ * focusable control is not a single element the group can point a DOM ref at.
+ *
+ * `focus()` moves focus to the group's first tabbable option at call time, which is what form libraries
+ * such as react-hook-form need (`field.ref` → `ref.focus()` on validation error).
+ */
+export type FocusHandle = {
+  focus: () => void;
+};
+
+export type UseFocusManagerRefOptions = {
+  /**
+   * Restricts which descendants of the wrapper may receive focus, e.g. only `<input>`s when the wrapper also
+   * contains other controls (such as a "show more" button).
+   */
+  accept?: (node: Element) => boolean;
+};
+
+/**
+ * Bridges a forwarded {@link FocusHandle} ref to a wrapper element. Returns the ref to attach to the
+ * wrapper; `focus()` on the forwarded handle focuses the first tabbable descendant via react-aria's
+ * focus manager. Resolution happens when `focus()` is called, so options that render, enable or
+ * disable after mount are handled, and roving-tabindex groups (radios) focus their tab stop
+ * (the selected option) rather than the first option. When no option is tabbable (e.g. a radio
+ * group whose `value` matches no radio, such as `''`), the first focusable option is used instead.
+ */
+export function useFocusManagerRef<T extends HTMLElement = HTMLDivElement>(
+  forwardedRef: ForwardedRef<FocusHandle>,
+  { accept }: UseFocusManagerRefOptions = {},
+): RefObject<T> {
+  const wrapperRef = useRef<T>(null);
+
+  useImperativeHandle(
+    forwardedRef,
+    () => ({
+      focus: () => {
+        const focusManager = createFocusManager(wrapperRef);
+        if (!focusManager.focusFirst({ tabbable: true, accept })) {
+          focusManager.focusFirst({ accept });
+        }
+      },
+    }),
+    [accept],
+  );
+
+  return wrapperRef;
+}
+
+/** `accept` predicate for groups whose options are `<input>` elements. */
+export const acceptInputs = (node: Element) => node.tagName === 'INPUT';

package/src/hook/index.ts

@@ -1,4 +1,5 @@
 export * from './dark-mode.hook.js';
 export * from './breakpoints.hook.js';
+export { type FocusHandle } from './focus-manager-ref.hook.js';
 export * from '../components/pagination/pagination.hooks.js';
 export * from './breakpoints.hook.js';

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './components/index.js';
 export * from './types/index.js';
+export { type FocusHandle } from './hook/focus-manager-ref.hook.js';