react-aria-components 1.14.0 → 1.15.0

package/src/Toast.tsx

@@ -16,6 +16,8 @@ import {
   ClassNameOrFunction,
   ContextValue,
   DEFAULT_SLOT,
+  dom,
+  DOMRenderProps,
   Provider,
   RenderProps,
   StyleRenderProps,
@@ -102,15 +104,15 @@ export const ToastRegion = /*#__PURE__*/ (forwardRef as forwardRefType)(function
 
   let region = (
     <ToastStateContext.Provider value={state}>
-      <div
+      <dom.div
         {...mergeProps(DOMProps, renderProps, regionProps, focusProps, hoverProps)}
         dir={direction}
         ref={objectRef}
         data-hovered={isHovered || undefined}
         data-focused={isFocused || undefined}
         data-focus-visible={isFocusVisible || undefined}>
-        {typeof props.children === 'function' ? <ToastList {...props} className={undefined} style={{display: 'contents'}}>{props.children}</ToastList> : props.children}
-      </div>
+        {typeof props.children === 'function' ? <ToastList {...props} render={undefined} className={undefined} style={{display: 'contents'}}>{props.children}</ToastList> : props.children}
+      </dom.div>
     </ToastStateContext.Provider>
   );
 
@@ -119,7 +121,7 @@ export const ToastRegion = /*#__PURE__*/ (forwardRef as forwardRefType)(function
     : null;
 });
 
-export interface ToastListProps<T> extends Omit<ToastRegionProps<T>, 'queue' | 'children'> {
+export interface ToastListProps<T> extends Omit<ToastRegionProps<T>, 'queue' | 'children' | 'render'>, DOMRenderProps<'ol', ToastRegionRenderProps<T>> {
   /** A function to render each toast. */
   children: (renderProps: {toast: QueuedToast<T>}) => ReactElement
 }
@@ -140,13 +142,13 @@ export const ToastList = /*#__PURE__*/ (forwardRef as forwardRefType)(function T
   });
 
   return (
-    <ol {...hoverProps} {...renderProps} ref={ref}>
+    <dom.ol {...hoverProps} {...renderProps} ref={ref}>
       {state.visibleToasts.map((toast) => (
         <li key={toast.key} style={{display: 'contents'}}>
           {props.children({toast})}
         </li>
       ))}
-    </ol>
+    </dom.ol>
   );
 });
 
@@ -201,7 +203,7 @@ export const Toast = /*#__PURE__*/ (forwardRef as forwardRefType)(function Toast
   let DOMProps = filterDOMProps(props, {global: true});
 
   return (
-    <div
+    <dom.div
       {...mergeProps(DOMProps, renderProps, toastProps, focusProps)}
       ref={objectRef}
       data-focused={isFocused || undefined}
@@ -225,20 +227,22 @@ export const Toast = /*#__PURE__*/ (forwardRef as forwardRefType)(function Toast
         ]}>
         {renderProps.children}
       </Provider>
-    </div>
+    </dom.div>
   );
 });
 
+export interface ToastContentProps extends HTMLAttributes<HTMLElement>, DOMRenderProps<'div', undefined> {}
+
 export const ToastContentContext = createContext<ContextValue<HTMLAttributes<HTMLElement>, HTMLDivElement>>({});
 
 /**
  * ToastContent wraps the main content of a toast notification.
  */
-export const ToastContent = /*#__PURE__*/ forwardRef(function ToastContent(props: HTMLAttributes<HTMLElement>, ref: ForwardedRef<HTMLDivElement>) {
+export const ToastContent = /*#__PURE__*/ forwardRef(function ToastContent(props: ToastContentProps, ref: ForwardedRef<HTMLDivElement>) {
   [props, ref] = useContextProps(props, ref, ToastContentContext);
   return (
-    <div className="react-aria-ToastContent" {...props} ref={ref}>
+    <dom.div render={props.render} className="react-aria-ToastContent" {...props} ref={ref}>
       {props.children}
-    </div>
+    </dom.div>
   );
 });

package/src/ToggleButton.tsx

@@ -15,6 +15,7 @@ import {ButtonRenderProps} from './Button';
 import {
   ClassNameOrFunction,
   ContextValue,
+  dom,
   RenderProps,
   SlotProps,
   useContextProps,
@@ -39,7 +40,7 @@ export interface ToggleButtonRenderProps extends Omit<ButtonRenderProps, 'isPend
   state: ToggleState
 }
 
-export interface ToggleButtonProps extends Omit<AriaToggleButtonProps, 'children' | 'elementType' | 'id'>, HoverEvents, SlotProps, RenderProps<ToggleButtonRenderProps>, Omit<GlobalDOMAttributes<HTMLDivElement>, 'onClick'> {
+export interface ToggleButtonProps extends Omit<AriaToggleButtonProps, 'children' | 'elementType' | 'id'>, HoverEvents, SlotProps, RenderProps<ToggleButtonRenderProps, 'button'>, Omit<GlobalDOMAttributes<HTMLDivElement>, 'onClick'> {
   /**
    * The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
    * @default 'react-aria-ToggleButton'
@@ -71,7 +72,7 @@ export const ToggleButton = /*#__PURE__*/ (forwardRef as forwardRefType)(functio
     : useToggleButton({...props, id: props.id != null ? String(props.id) : undefined}, state, ref);
 
   let {focusProps, isFocused, isFocusVisible} = useFocusRing(props);
-  let {hoverProps, isHovered} = useHover(props);
+  let {hoverProps, isHovered} = useHover({...props, isDisabled});
   let renderProps = useRenderProps({
     ...props,
     id: undefined,
@@ -84,7 +85,7 @@ export const ToggleButton = /*#__PURE__*/ (forwardRef as forwardRefType)(functio
   delete DOMProps.onClick;
 
   return (
-    <button
+    <dom.button
       {...mergeProps(DOMProps, renderProps, buttonProps, focusProps, hoverProps)}
       ref={ref}
       slot={props.slot || undefined}
@@ -97,6 +98,6 @@ export const ToggleButton = /*#__PURE__*/ (forwardRef as forwardRefType)(functio
       <SelectionIndicatorContext.Provider value={{isSelected}}>
         {renderProps.children}
       </SelectionIndicatorContext.Provider>
-    </button>
+    </dom.button>
   );
 });

package/src/ToggleButtonGroup.tsx

@@ -13,6 +13,7 @@ import {AriaToggleButtonGroupProps, useToggleButtonGroup} from 'react-aria';
 import {
   ClassNameOrFunction,
   ContextValue,
+  dom,
   RenderProps,
   SlotProps,
   useContextProps,
@@ -73,7 +74,7 @@ export const ToggleButtonGroup = /*#__PURE__*/ (forwardRef as forwardRefType)(fu
   let DOMProps = filterDOMProps(props, {global: true});
 
   return (
-    <div
+    <dom.div
       {...mergeProps(DOMProps, renderProps, groupProps)}
       ref={ref}
       slot={props.slot || undefined}
@@ -84,6 +85,6 @@ export const ToggleButtonGroup = /*#__PURE__*/ (forwardRef as forwardRefType)(fu
           {renderProps.children}
         </SharedElementTransition>
       </ToggleGroupStateContext.Provider>
-    </div>
+    </dom.div>
   );
 });

package/src/Toolbar.tsx

@@ -14,6 +14,7 @@ import {AriaToolbarProps, useToolbar} from '@react-aria/toolbar';
 import {
   ClassNameOrFunction,
   ContextValue,
+  dom,
   RenderProps,
   SlotProps,
   useContextProps,
@@ -57,12 +58,12 @@ export const Toolbar = /*#__PURE__*/ (forwardRef as forwardRefType)(function Too
   delete DOMProps.id;
 
   return (
-    <div
+    <dom.div
       {...mergeProps(DOMProps, renderProps, toolbarProps)}
       ref={ref}
       slot={props.slot || undefined}
       data-orientation={props.orientation || 'horizontal'}>
       {renderProps.children}
-    </div>
+    </dom.div>
   );
 });

package/src/Tooltip.tsx

@@ -15,6 +15,7 @@ import {AriaPositionProps, mergeProps, OverlayContainer, Placement, PlacementAxi
 import {
   ClassNameOrFunction,
   ContextValue,
+  dom,
   Provider,
   RenderProps,
   useContextProps,
@@ -167,7 +168,7 @@ function TooltipInner(props: TooltipProps & {isExiting: boolean, tooltipRef: Ref
   let DOMProps = filterDOMProps(props, {global: true});
 
   return (
-    <div
+    <dom.div
       {...mergeProps(DOMProps, renderProps, tooltipProps)}
       ref={props.tooltipRef}
       style={{
@@ -181,6 +182,6 @@ function TooltipInner(props: TooltipProps & {isExiting: boolean, tooltipRef: Ref
       <OverlayArrowContext.Provider value={{...arrowProps, placement, ref: arrowRef}}>
         {renderProps.children}
       </OverlayArrowContext.Provider>
-    </div>
+    </dom.div>
   );
 }

package/src/Tree.tsx

@@ -18,6 +18,7 @@ import {
   ClassNameOrFunction,
   ContextValue,
   DEFAULT_SLOT,
+  dom,
   Provider,
   RenderProps,
   SlotProps,
@@ -372,8 +373,8 @@ function TreeInner<T extends object>({props, collection, treeRef: ref}: TreeInne
   };
 
   let renderProps = useRenderProps({
-    className: props.className,
-    style: props.style,
+    ...props,
+    children: undefined,
     defaultClassName: 'react-aria-Tree',
     values: renderValues
   });
@@ -401,7 +402,7 @@ function TreeInner<T extends object>({props, collection, treeRef: ref}: TreeInne
   return (
     <>
       <FocusScope>
-        <div
+        <dom.div
           {...mergeProps(DOMProps, renderProps, gridProps, focusProps, droppableCollection?.collectionProps)}
           ref={ref}
           slot={props.slot || undefined}
@@ -427,7 +428,7 @@ function TreeInner<T extends object>({props, collection, treeRef: ref}: TreeInne
             </SharedElementTransition>
           </Provider>
           {emptyState}
-        </div>
+        </dom.div>
       </FocusScope>
       {dragPreview}
     </>
@@ -673,15 +674,15 @@ export const TreeItem = /*#__PURE__*/ createBranchComponent(TreeItemNode, <T ext
         </div>
       </div>
     )}
-      <div
+      <dom.div
         {...mergeProps(
-        DOMProps,
-        rowProps,
-        focusProps,
-        hoverProps,
-        focusWithinProps,
-        draggableItem?.dragProps
-      )}
+          DOMProps,
+          rowProps,
+          focusProps,
+          hoverProps,
+          focusWithinProps,
+          draggableItem?.dragProps
+        )}
         {...renderProps}
         ref={ref}
       // TODO: missing selectionBehavior, hasAction and allowsSelection data attribute equivalents (available in renderProps). Do we want those?
@@ -732,7 +733,7 @@ export const TreeItem = /*#__PURE__*/ createBranchComponent(TreeItemNode, <T ext
             {children}
           </Provider>
         </div>
-      </div>
+      </dom.div>
     </>
   );
 });
@@ -811,7 +812,7 @@ export const TreeLoadMoreItem = createLeafComponent(LoaderNode, function TreeLoa
         <div data-testid="loadMoreSentinel" ref={sentinelRef} style={{position: 'absolute', height: 1, width: 1}} />
       </div>
       {isLoading && renderProps.children && (
-        <div
+        <dom.div
           ref={ref}
           {...mergeProps(filterDOMProps(props as any), ariaProps)}
           {...renderProps}
@@ -819,7 +820,7 @@ export const TreeLoadMoreItem = createLeafComponent(LoaderNode, function TreeLoa
           <div {...gridCellProps} style={style}>
             {renderProps.children}
           </div>
-        </div>
+        </dom.div>
       )}
     </>
   );
@@ -963,7 +964,7 @@ function TreeDropIndicator(props: TreeDropIndicatorProps, ref: ForwardedRef<HTML
   });
 
   return (
-    <div
+    <dom.div
       {...renderProps}
       role="row"
       aria-level={level}
@@ -973,7 +974,7 @@ function TreeDropIndicator(props: TreeDropIndicatorProps, ref: ForwardedRef<HTML
         <div {...visuallyHiddenProps} role="button" {...dropIndicatorProps} ref={buttonRef} />
         {renderProps.children}
       </div>
-    </div>
+    </dom.div>
   );
 }
 

package/src/utils.tsx

@@ -12,7 +12,7 @@
 
 import {AriaLabelingProps, RefObject,  DOMProps as SharedDOMProps} from '@react-types/shared';
 import {mergeProps, mergeRefs, useLayoutEffect, useObjectRef} from '@react-aria/utils';
-import React, {Context, CSSProperties, ForwardedRef, JSX, ReactNode, RefCallback, useCallback, useContext, useMemo, useRef, useState} from 'react';
+import React, {AllHTMLAttributes, AnchorHTMLAttributes, Context, CSSProperties, DetailedHTMLProps, ForwardedRef, forwardRef, JSX, ReactElement, ReactNode, RefCallback, useCallback, useContext, useMemo, useRef, useState} from 'react';
 
 export const DEFAULT_SLOT = Symbol('default');
 
@@ -20,7 +20,7 @@ interface SlottedValue<T> {
   slots?: Record<string | symbol, T>
 }
 
-export type SlottedContextValue<T> = SlottedValue<T> | T | null | undefined;
+export type SlottedContextValue<T> = (SlottedValue<T> & T) | null | undefined;
 export type ContextValue<T, E> = SlottedContextValue<WithRef<T, E>>;
 
 type ProviderValue<T> = [Context<T>, T];
@@ -66,7 +66,7 @@ export interface DOMProps extends StyleProps, SharedDOMProps {
 export type ClassNameOrFunction<T> = string | ((values: T & {defaultClassName: string | undefined}) => string);
 type StyleOrFunction<T> = CSSProperties | ((values: T & {defaultStyle: CSSProperties}) => CSSProperties | undefined);
 
-export interface StyleRenderProps<T> {
+export interface StyleRenderProps<T, E extends keyof React.JSX.IntrinsicElements = 'div'> extends DOMRenderProps<E, T> {
   /** The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. */
   className?: ClassNameOrFunction<T>,
   /** The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. */
@@ -75,26 +75,27 @@ export interface StyleRenderProps<T> {
 
 export type ChildrenOrFunction<T> = ReactNode | ((values: T & {defaultChildren: ReactNode | undefined}) => ReactNode);
 
-export interface RenderProps<T> extends StyleRenderProps<T> {
+export interface RenderProps<T, E extends keyof React.JSX.IntrinsicElements = 'div'> extends StyleRenderProps<T, E> {
   /** The children of the component. A function may be provided to alter the children based on component state. */
   children?: ChildrenOrFunction<T>
 }
 
-interface RenderPropsHookOptions<T> extends RenderProps<T>, SharedDOMProps, AriaLabelingProps {
+interface RenderPropsHookOptions<T, E extends keyof React.JSX.IntrinsicElements> extends RenderProps<T, E>, SharedDOMProps, AriaLabelingProps {
   values: T,
   defaultChildren?: ReactNode,
   defaultClassName?: string,
   defaultStyle?: CSSProperties
 }
 
-interface RenderPropsHookRetVal {
+interface RenderPropsHookRetVal<T, E extends keyof React.JSX.IntrinsicElements> {
   className?: string,
   style?: CSSProperties,
   children?: ReactNode,
-  'data-rac': string
+  'data-rac': string,
+  render?: DOMRenderFunction<E, T>
 }
 
-export function useRenderProps<T>(props: RenderPropsHookOptions<T>): RenderPropsHookRetVal {
+export function useRenderProps<T, E extends keyof React.JSX.IntrinsicElements>(props: RenderPropsHookOptions<T, E>): RenderPropsHookRetVal<T, E> {
   let {
     className,
     style,
@@ -102,7 +103,8 @@ export function useRenderProps<T>(props: RenderPropsHookOptions<T>): RenderProps
     defaultClassName = undefined,
     defaultChildren = undefined,
     defaultStyle,
-    values
+    values,
+    render
   } = props;
 
   return useMemo(() => {
@@ -134,9 +136,10 @@ export function useRenderProps<T>(props: RenderPropsHookOptions<T>): RenderProps
       className: computedClassName ?? defaultClassName,
       style: (computedStyle || defaultStyle) ? {...defaultStyle, ...computedStyle} : undefined,
       children: computedChildren ?? defaultChildren,
-      'data-rac': ''
+      'data-rac': '',
+      render: render ? (props => render(props, values)) : undefined
     };
-  }, [className, style, children, defaultClassName, defaultChildren, defaultStyle, values]);
+  }, [className, style, children, defaultClassName, defaultChildren, defaultStyle, values, render]);
 }
 
 /**
@@ -262,3 +265,86 @@ export interface RACValidation {
    */
   validationBehavior?: 'native' | 'aria'
 }
+
+export type DOMRenderFunction<E extends keyof React.JSX.IntrinsicElements, T> = (props: React.JSX.IntrinsicElements[E], renderProps: T) => ReactElement;
+export interface DOMRenderProps<E extends keyof React.JSX.IntrinsicElements, T> {
+  /**
+   * Overrides the default DOM element with a custom render function.
+   * This allows rendering existing components with built-in styles and behaviors
+   * such as router links, animation libraries, and pre-styled components.
+   * 
+   * Requirements:
+   * 
+   * * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`).
+   * * Only a single root DOM element can be rendered (no fragments).
+   * * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
+   */
+  render?: DOMRenderFunction<E, T>
+}
+
+// Makes `href` required in AnchorHTMLAttributes
+type LinkWithRequiredHref = Required<Pick<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>> & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>; 
+
+// Same as DOMRenderProps but specific for the case where the element could be a 'a' or 'div' element.
+export interface PossibleLinkDOMRenderProps<Fallback extends keyof React.JSX.IntrinsicElements, T> {
+  /**
+   * Overrides the default DOM element with a custom render function.
+   * This allows rendering existing components with built-in styles and behaviors
+   * such as router links, animation libraries, and pre-styled components.
+   * 
+   * Note: You can check if `'href' in props` in order to tell whether to render an `<a>` element.
+   * 
+   * Requirements:
+   * 
+   * * You must render the expected element type (e.g. if `<a>` is expected, you cannot render a `<button>`).
+   * * Only a single root DOM element can be rendered (no fragments).
+   * * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
+   */
+  render?: (props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> | React.JSX.IntrinsicElements[Fallback], renderProps: T) => ReactElement
+}
+
+function DOMElement(ElementType: string, props: DOMRenderProps<any, any> & AllHTMLAttributes<HTMLElement>, forwardedRef: ForwardedRef<HTMLElement>) {
+  let {render, ...otherProps} = props;
+  let elementRef = useRef<HTMLElement | null>(null);
+  let ref = useMemo(() => mergeRefs(forwardedRef, elementRef), [forwardedRef, elementRef]);
+
+  useLayoutEffect(() => {
+    if (process.env.NODE_ENV !== 'production' && render) {
+      if (!elementRef.current) {
+        console.warn('Ref was not connected to DOM element returned by custom `render` function. Did you forget to pass through or merge the `ref`?');
+      } else if (elementRef.current.localName !== ElementType) {
+        console.warn(`Unexpected DOM element returned by custom \`render\` function. Expected <${ElementType}>, got <${elementRef.current.localName}>. This may break the component behavior and accessibility.`);
+      }
+    }
+  }, [ElementType, render]);
+
+  let domProps: any = {...otherProps, ref};
+  if (render) {
+    return render(domProps, undefined);
+  }
+
+  return <ElementType {...domProps} />;
+}
+
+type DOMComponents = {
+  [E in keyof React.JSX.IntrinsicElements]: (props: DOMRenderProps<E, any> & React.JSX.IntrinsicElements[E]) => ReactElement
+};
+
+const domComponentCache = {};
+
+// Dynamically generates and caches components for each DOM element (e.g. `dom.button`).
+export const dom = new Proxy({}, {
+  get(target, elementType) {
+    if (typeof elementType !== 'string') {
+      return undefined;
+    }
+
+    let res = domComponentCache[elementType];
+    if (!res) {
+      res = forwardRef(DOMElement.bind(null, elementType));
+      domComponentCache[elementType] = res;
+    }
+
+    return res;
+  }
+}) as DOMComponents;