@westpac/ui 1.16.0 → 1.19.0

package/dist/index.d.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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@westpac/ui",
-  "version": "1.16.0",
+  "version": "1.19.0",
   "license": "MIT",
   "sideEffects": false,
   "type": "module",
@@ -259,14 +259,15 @@
     "typescript": "^5.5.4",
     "vite": "^7.3.5",
     "vitest": "^3.2.6",
-    "@westpac/eslint-config": "~1.1.0",
     "@westpac/test-config": "~0.0.0",
     "@westpac/ts-config": "~0.0.0",
-    "@westpac/style-config": "~1.0.2"
+    "@westpac/style-config": "~1.0.2",
+    "@westpac/eslint-config": "~1.1.0"
   },
   "dependencies": {
     "@internationalized/date": "^3.12.0",
     "@react-aria/accordion": "3.0.0-alpha.37",
+    "@react-aria/focus": "~3.21.5",
     "@react-aria/utils": "~3.29.1",
     "@react-spectrum/utils": "~3.11.5",
     "clsx": "^1.2.1",
@@ -280,6 +281,7 @@
   },
   "peerDependencies": {
     "react": ">=18.2.0",
+    "react-dom": ">=18.2.0",
     "tailwindcss": "~4.1.12"
   },
   "repository": {

package/src/components/button/button.component.tsx

@@ -1,13 +1,13 @@
 'use client';
 
-import React, { Ref, forwardRef, useMemo } from 'react';
+import React, { ForwardedRef, forwardRef, useMemo } from 'react';
 import { mergeProps, useFocusRing } from 'react-aria';
 
 import { useBreakpoint } from '../../hook/breakpoints.hook.js';
 import { resolveResponsiveVariant } from '../../utils/breakpoint.util.js';
 
 import { styles as buttonStyles } from './button.styles.js';
-import { type ButtonProps, ButtonRef } from './button.types.js';
+import { ButtonImplementationProps, ButtonComponent } from './button.types.js';
 import { getIconSize } from './button.utils.js';
 
 function BaseButton(
@@ -18,7 +18,7 @@ function BaseButton(
     soft,
     block = false,
     justify,
-    tag: Tag = 'button',
+    tag: Tag,
     iconBefore: IconBefore,
     iconAfter: IconAfter,
     iconLook,
@@ -26,11 +26,12 @@ function BaseButton(
     iconSize,
     children,
     removeLinkPadding,
-    type = Tag === 'button' ? 'button' : undefined,
     ...props
-  }: ButtonProps,
-  ref: Ref<ButtonRef>,
+  }: ButtonImplementationProps,
+  ref: ForwardedRef<unknown>,
 ) {
+  const Component = Tag ?? 'button';
+  const renderProps = Component === 'button' ? { ...props, type: props.type ?? 'button' } : props;
   const { isFocusVisible, focusProps } = useFocusRing();
   const btnIconSize = useMemo(() => iconSize || getIconSize(size), [iconSize, size]);
   const breakpoint = useBreakpoint();
@@ -76,7 +77,7 @@ function BaseButton(
   }, [iconColor, look, soft]);
 
   return (
-    <Tag ref={ref} className={styles.base({ className })} {...mergeProps(props, focusProps)} type={type}>
+    <Component ref={ref} className={styles.base({ className })} {...mergeProps(renderProps, focusProps)}>
       {IconBefore && (
         <IconBefore
           look={iconLook}
@@ -96,8 +97,8 @@ function BaseButton(
           aria-hidden
         />
       )}
-    </Tag>
+    </Component>
   );
 }
 
-export const Button = forwardRef(BaseButton);
+export const Button = forwardRef(BaseButton) as unknown as ButtonComponent;

package/src/components/button/button.types.ts

@@ -1,4 +1,4 @@
-import { AnchorHTMLAttributes, ButtonHTMLAttributes, ReactNode } from 'react';
+import { ReactNode } from 'react';
 import { type VariantProps } from 'tailwind-variants';
 
 import { ResponsiveVariants } from '../../types/responsive-variants.types.js';
@@ -8,9 +8,7 @@ import { styles } from './button.styles.js';
 
 type Variants = VariantProps<typeof styles>;
 
-export type ButtonRef = HTMLButtonElement & HTMLAnchorElement & HTMLSpanElement & HTMLDivElement;
-
-export type ButtonProps = {
+export type BaseButtonProps = {
   /**
    * Fit button width to its parent width.
    * @default false
@@ -69,10 +67,25 @@ export type ButtonProps = {
    * Removes background colour and adjusts text colour.
    */
   soft?: ResponsiveVariants<Variants['soft']>;
+};
+
+export type ButtonRef<C extends React.ElementType = 'button'> = React.ComponentRef<C>;
+
+export type PolymorphicRef<C extends React.ElementType> = React.ComponentPropsWithRef<C>['ref'];
+
+export type ButtonProps<C extends React.ElementType = 'button'> = BaseButtonProps & {
   /**
-   * Tag to render
+   * Type to render
    * @default button
    */
-  tag?: keyof Pick<JSX.IntrinsicElements, 'a' | 'span' | 'button' | 'div'>;
-} & ButtonHTMLAttributes<Element> &
-  AnchorHTMLAttributes<Element>;
+  tag?: C;
+} & Omit<React.ComponentPropsWithoutRef<C>, keyof BaseButtonProps | 'tag'>;
+
+export type ButtonImplementationProps = BaseButtonProps & {
+  className?: string;
+  tag?: React.ElementType;
+} & Record<string, unknown>;
+
+export type ButtonComponent = <C extends React.ElementType = 'button'>(
+  props: ButtonProps<C> & { ref?: PolymorphicRef<C> },
+) => React.ReactElement | null;

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

@@ -1,9 +1,11 @@
 'use client';
 
-import React, { useCallback, useMemo } from 'react';
+import React, { ForwardedRef, forwardRef, useCallback, useMemo } from 'react';
 import { useToggleButtonGroup } from 'react-aria';
 import { useToggleGroupState } from 'react-stately';
 
+import { FocusHandle, useFocusManagerRef } from '../../hook/focus-manager-ref.hook.js';
+
 import { styles as buttonGroupStyles } from './button-group.styles.js';
 
 import type { ButtonGroupProps } from './button-group.types.js';
@@ -19,20 +21,26 @@ export const ToggleButtonGroupContext = React.createContext<
   | null
 >(null);
 
-export function ButtonGroup({
-  size,
-  look,
-  block,
-  children,
-  onSelect,
-  orientation = 'horizontal',
-  selectionMode,
-  selectedKeys,
-  defaultSelectedKeys,
-  onSelectionChange,
-  className,
-  ...props
-}: ButtonGroupProps) {
+function BaseButtonGroup(
+  {
+    size,
+    look,
+    block,
+    children,
+    onSelect,
+    orientation = 'horizontal',
+    selectionMode,
+    selectedKeys,
+    defaultSelectedKeys,
+    onSelectionChange,
+    className,
+    ...props
+  }: ButtonGroupProps,
+  // `ref.current.focus()` (e.g. react-hook-form focusing a field with a validation error) moves
+  // focus to the first tabbable button in the group.
+  forwardedRef: ForwardedRef<FocusHandle>,
+) {
+  const ref = useFocusManagerRef(forwardedRef);
   /**
    * Normalizes key sets depending on selection mode.
    */
@@ -71,7 +79,6 @@ export function ButtonGroup({
     selectedKeys: finalSelectedKeys,
   });
 
-  const ref = React.useRef<HTMLDivElement | null>(null);
   const { groupProps } = useToggleButtonGroup(
     {
       ...props,
@@ -95,3 +102,6 @@ export function ButtonGroup({
     </div>
   );
 }
+
+export const ButtonGroup = forwardRef(BaseButtonGroup);
+ButtonGroup.displayName = 'ButtonGroup';

package/src/components/checkbox-group/checkbox-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 { useCheckboxGroup, useFocusRing } from 'react-aria';
 import { useCheckboxGroupState } 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';
@@ -79,22 +80,28 @@ export const CheckboxGroupContext = createContext<CheckboxGroupContextState>({
     },
   },
 });
-export function CheckboxGroup({
-  className,
-  checkboxes,
-  label,
-  orientation = 'vertical',
-  showAmount = 0,
-  size = 'medium',
-  errorMessage,
-  hintMessage,
-  ...props
-}: CheckboxGroupProps) {
+function BaseCheckboxGroup(
+  {
+    className,
+    checkboxes,
+    label,
+    orientation = 'vertical',
+    showAmount = 0,
+    size = 'medium',
+    errorMessage,
+    hintMessage,
+    ...props
+  }: CheckboxGroupProps,
+  // `ref.current.focus()` (e.g. react-hook-form focusing a field with a validation error) moves focus
+  // to the first enabled checkbox.
+  ref: ForwardedRef<FocusHandle>,
+) {
+  const wrapperRef = useFocusManagerRef(ref, { accept: acceptInputs });
   const state = useCheckboxGroupState({ ...props, label });
   const { groupProps, labelProps, errorMessageProps, descriptionProps } = useCheckboxGroup({ ...props, label }, state);
   const { isFocusVisible, focusProps } = useFocusRing();
   const [hiddenOptions, setHiddenOptions] = useState<boolean>(showAmount > 0);
-  const firstNewCheckboxRef = useRef<HTMLLabelElement>(null);
+  const firstNewCheckboxRef = useRef<HTMLInputElement>(null);
   const revealAmount = checkboxes && checkboxes.length - showAmount;
   const breakpoint = useBreakpoint();
   const styles = checkboxStyles({ orientation: resolveResponsiveVariant(orientation, breakpoint), isFocusVisible });
@@ -118,7 +125,7 @@ export function CheckboxGroup({
       <Label {...labelProps}>{label}</Label>
       {hintMessage && <Hint {...descriptionProps}>{hintMessage}</Hint>}
       {errorMessage && state.isInvalid && <ErrorMessage {...errorMessageProps} message={errorMessage} />}
-      <div className={styles.itemWrapper()} id={panelId}>
+      <div className={styles.itemWrapper()} id={panelId} ref={wrapperRef}>
         <CheckboxGroupContext.Provider
           value={{
             state,
@@ -147,3 +154,6 @@ export function CheckboxGroup({
     </div>
   );
 }
+
+export const CheckboxGroup = forwardRef(BaseCheckboxGroup);
+CheckboxGroup.displayName = 'CheckboxGroup';

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

@@ -1,7 +1,7 @@
 'use client';
 
-import React, { Ref, forwardRef, useContext, useRef } from 'react';
-import { VisuallyHidden, mergeProps, useCheckboxGroupItem, useFocusRing } from 'react-aria';
+import React, { ForwardedRef, forwardRef, useContext } from 'react';
+import { VisuallyHidden, mergeProps, useCheckboxGroupItem, useFocusRing, useObjectRef } from 'react-aria';
 
 import { Icon } from '../../../icon/icon.component.js';
 import { IconProps } from '../../../icon/index.js';
@@ -33,22 +33,22 @@ function CheckIcon({ copyrightYear = '2025', size, ...props }: IconProps) {
 
 function BaseCheckbox(
   { className, hint, label, value, ...props }: CheckboxGroupCheckboxProps,
-  ref: Ref<HTMLLabelElement>,
+  ref: ForwardedRef<HTMLInputElement>,
 ) {
   const { state, size, orientation } = useContext(CheckboxGroupContext);
-  const localRef = useRef(null);
+  const inputRef = useObjectRef(ref);
   const { inputProps, labelProps, isDisabled, isSelected } = useCheckboxGroupItem(
     { ...props, value, children: label },
     state,
-    localRef,
+    inputRef,
   );
   const { isFocusVisible, focusProps } = useFocusRing();
   const styles = checkboxItemStyles({ isDisabled, size, orientation, isFocusVisible });
 
   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.checkbox()}>
         {isSelected && <CheckIcon className={styles.checkIcon()} size={size} color={isDisabled ? 'muted' : 'hero'} />}

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

@@ -1,7 +1,7 @@
 'use client';
 
-import React, { useRef } from 'react';
-import { mergeProps, useDateSegment, useFocusRing } from 'react-aria';
+import React, { ForwardedRef, forwardRef } from 'react';
+import { mergeProps, useDateSegment, useFocusRing, useObjectRef } from 'react-aria';
 
 import { styles as dateSegmentStyles } from './date-segment.styles.js';
 import { DateSegmentProps } from './date-segment.types.js';
@@ -9,8 +9,11 @@ import { DateSegmentProps } from './date-segment.types.js';
 /**
  * @private
  */
-export function DateSegment({ segment, state, separator, ...props }: DateSegmentProps) {
-  const ref = useRef(null);
+function BaseDateSegment(
+  { segment, state, separator, ...props }: DateSegmentProps,
+  forwardedRef: ForwardedRef<HTMLSpanElement>,
+) {
+  const ref = useObjectRef(forwardedRef);
   const { focusProps, isFocusVisible } = useFocusRing();
   const { segmentProps } = useDateSegment(segment, state, ref);
   const styles = dateSegmentStyles({
@@ -23,3 +26,6 @@ export function DateSegment({ segment, state, separator, ...props }: DateSegment
     </span>
   );
 }
+
+export const DateSegment = forwardRef(BaseDateSegment);
+DateSegment.displayName = 'DateSegment';

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

@@ -1,7 +1,7 @@
 'use client';
 
 import { createCalendar } from '@internationalized/date';
-import React, { useRef } from 'react';
+import React, { ForwardedRef, forwardRef, useRef } from 'react';
 import { useDateField, useLocale } from 'react-aria';
 import { useDateFieldState } from 'react-stately';
 
@@ -11,7 +11,11 @@ import { type DateFieldProps } from './date-field.types.js';
 /**
  * @private
  */
-export function DateField({ separator, className, ...props }: DateFieldProps) {
+function BaseDateField(
+  { separator, className, ...props }: DateFieldProps,
+  // Attached to the first editable segment, the same element react-aria focuses for this field.
+  forwardedRef: ForwardedRef<HTMLSpanElement>,
+) {
   const { locale } = useLocale();
   const state = useDateFieldState({
     ...props,
@@ -21,12 +25,22 @@ export function DateField({ separator, className, ...props }: DateFieldProps) {
 
   const ref = useRef(null);
   const { fieldProps } = useDateField(props, state, ref);
+  const firstEditableIndex = state.segments.findIndex(segment => segment.isEditable);
 
   return (
     <div {...fieldProps} className={className} ref={ref}>
       {state.segments.map((segment, i) => (
-        <DateSegment separator={separator} key={i} segment={segment} state={state} />
+        <DateSegment
+          separator={separator}
+          key={i}
+          segment={segment}
+          state={state}
+          ref={i === firstEditableIndex ? forwardedRef : null}
+        />
       ))}
     </div>
   );
 }
+
+export const DateField = forwardRef(BaseDateField);
+DateField.displayName = 'DateField';

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/link/link.component.tsx

@@ -1,30 +1,77 @@
-// TODO: This component will not work with the Next Link component in Next.js 16+ as legacyBehavior as has been deprecated in 15. Need to find a solution.
 'use client';
 
-import React, { ForwardedRef, RefObject, forwardRef } from 'react';
-import { mergeProps, useFocusRing, useLink } from 'react-aria';
+import { type FocusableElement } from '@react-types/shared';
+import React, { ForwardedRef, forwardRef } from 'react';
+import { mergeProps, useFocusRing, useLink, useObjectRef } from 'react-aria';
 
 import { ArrowRightIcon } from '../icon/index.js';
 
 import { styles as linkStyles } from './link.styles.js';
-import { type LinkProps } from './link.types.js';
+import { LinkComponent, LinkImplementationProps } from './link.types.js';
 
 export function BaseLink(
   {
     className,
     children,
     href,
+    tag: Tag,
     iconBefore: IconBefore,
     iconAfter: IconAfter,
     iconSize = 'small',
     target,
     type = 'standalone',
     underline = true,
-    ...props
-  }: LinkProps,
-  ref: ForwardedRef<HTMLAnchorElement>,
+    autoFocus,
+    elementType,
+    onBlur,
+    onClick,
+    onFocus,
+    onFocusChange,
+    onKeyDown,
+    onKeyUp,
+    onPress,
+    onPressChange,
+    onPressEnd,
+    onPressStart,
+    onPressUp,
+    download,
+    ping,
+    referrerPolicy,
+    rel,
+    routerOptions,
+    ...componentProps
+  }: LinkImplementationProps,
+  ref: ForwardedRef<unknown>,
 ) {
-  const { linkProps } = useLink({ ...props, elementType: 'a' }, ref as RefObject<HTMLAnchorElement>);
+  const Component = Tag ?? 'a';
+  const ariaElementType = typeof Component === 'string' ? Component : (elementType ?? 'a');
+  const linkRef = useObjectRef(ref as ForwardedRef<FocusableElement>);
+  const { linkProps } = useLink(
+    {
+      ...componentProps,
+      autoFocus,
+      download,
+      elementType: ariaElementType,
+      href: typeof href === 'string' ? href : undefined,
+      onBlur,
+      onClick,
+      onFocus,
+      onFocusChange,
+      onKeyDown,
+      onKeyUp,
+      onPress,
+      onPressChange,
+      onPressEnd,
+      onPressStart,
+      onPressUp,
+      ping,
+      referrerPolicy,
+      rel,
+      routerOptions,
+      target,
+    },
+    linkRef,
+  );
   const { isFocusVisible, focusProps } = useFocusRing();
   const styles = linkStyles({ type, underline, isFocusVisible });
 
@@ -33,9 +80,10 @@ export function BaseLink(
   }
 
   return (
-    <a
+    <Component
+      {...componentProps}
       {...mergeProps(linkProps, focusProps)}
-      ref={ref}
+      ref={linkRef}
       href={href}
       target={target}
       className={styles.base({ className })}
@@ -43,8 +91,8 @@ export function BaseLink(
       {IconBefore && <IconBefore size={iconSize} color="primary" className={styles.iconBefore()} />}
       <span>{children}</span>
       {IconAfter && <IconAfter size={iconSize} color="primary" className={styles.iconAfter()} />}
-    </a>
+    </Component>
   );
 }
 
-export const Link = forwardRef(BaseLink);
+export const Link = forwardRef(BaseLink) as unknown as LinkComponent;