@octanejs/base-ui 0.1.50 → 0.1.52

package/src/internals/use-button/useButton.ts

@@ -0,0 +1,309 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { isHTMLElement } from '@floating-ui/utils/dom';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { error } from '@octanejs/base-ui-utils/error';
+import type { SafeReact } from '@octanejs/base-ui-utils/safeReact';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { makeEventPreventable, mergeProps } from '../../merge-props';
+import { useCompositeRootContext } from '../composite/root/CompositeRootContext';
+import type { BaseUIEvent, HTMLProps } from '../types';
+import { useFocusableWhenDisabled } from '../../utils/useFocusableWhenDisabled';
+import { dispatchClickWithModifiers } from '../../utils/dispatchClickWithModifiers';
+
+export function useButton(parameters: UseButtonParameters = {}): UseButtonReturnValue {
+	const {
+		disabled = false,
+		focusableWhenDisabled,
+		tabIndex = 0,
+		native: isNativeButton = true,
+		composite: compositeProp,
+	} = parameters;
+
+	const elementRef = React.useRef<HTMLElement | null>(null);
+
+	const compositeRootContext = useCompositeRootContext(true);
+	const isCompositeItem = compositeProp ?? compositeRootContext !== undefined;
+
+	const { props: focusableWhenDisabledProps } = useFocusableWhenDisabled({
+		focusableWhenDisabled,
+		disabled,
+		composite: isCompositeItem,
+		tabIndex,
+		isNativeButton,
+	});
+
+	if (process.env.NODE_ENV !== 'production') {
+		// eslint-disable-next-line react-hooks/rules-of-hooks
+		React.useEffect(() => {
+			if (!elementRef.current) {
+				return;
+			}
+
+			const isButtonTag = isButtonElement(elementRef.current);
+
+			if (isNativeButton) {
+				if (!isButtonTag) {
+					const ownerStackMessage = '';
+					const message =
+						'A component that acts as a button expected a native <button> because the ' +
+						'`nativeButton` prop is true. Rendering a non-<button> removes native button ' +
+						'semantics, which can impact forms and accessibility. Use a real <button> in the ' +
+						'`render` prop, or set `nativeButton` to `false`.';
+					error(`${message}${ownerStackMessage}`);
+				}
+			} else if (isButtonTag) {
+				const ownerStackMessage = '';
+				const message =
+					'A component that acts as a button expected a non-<button> because the `nativeButton` ' +
+					'prop is false. Rendering a <button> keeps native behavior while Base UI applies ' +
+					'non-native attributes and handlers, which can add unintended extra attributes (such ' +
+					'as `role` or `aria-disabled`). Use a non-<button> in the `render` prop, or set ' +
+					'`nativeButton` to `true`.';
+				error(`${message}${ownerStackMessage}`);
+			}
+		}, [isNativeButton]);
+	}
+
+	// handles a disabled composite button rendering another button, e.g.
+	// <Toolbar.Button disabled render={<Menu.Trigger />} />
+	// the `disabled` prop needs to pass through 2 `useButton`s then finally
+	// delete the `disabled` attribute from DOM
+	const updateDisabled = React.useCallback(() => {
+		const element = elementRef.current;
+
+		if (!isButtonElement(element)) {
+			return;
+		}
+
+		if (
+			isCompositeItem &&
+			disabled &&
+			focusableWhenDisabledProps.disabled === undefined &&
+			element.disabled
+		) {
+			element.disabled = false;
+		}
+	}, [disabled, focusableWhenDisabledProps.disabled, isCompositeItem]);
+
+	useIsoLayoutEffect(updateDisabled, [updateDisabled]);
+
+	const getButtonProps = React.useCallback(
+		(externalProps: GenericButtonProps = {}) => {
+			const {
+				onClick: externalOnClick,
+				onMouseDown: externalOnMouseDown,
+				onKeyUp: externalOnKeyUp,
+				onKeyDown: externalOnKeyDown,
+				onPointerDown: externalOnPointerDown,
+				...otherExternalProps
+			} = externalProps;
+
+			return mergeProps<'button'>(
+				{
+					onClick(event: React.MouseEvent) {
+						if (disabled) {
+							event.preventDefault();
+							return;
+						}
+						externalOnClick?.(event);
+					},
+					onMouseDown(event: React.MouseEvent) {
+						if (!disabled) {
+							externalOnMouseDown?.(event);
+						}
+					},
+					onKeyDown(event: BaseUIEvent<React.KeyboardEvent>) {
+						if (disabled) {
+							return;
+						}
+
+						makeEventPreventable(event);
+						externalOnKeyDown?.(event);
+						if (event.baseUIHandlerPrevented) {
+							return;
+						}
+
+						const isCurrentTarget = event.target === event.currentTarget;
+						const currentTarget = event.currentTarget as Element;
+						const isButton = isButtonElement(currentTarget);
+						const isLink = !isNativeButton && isValidLinkElement(currentTarget);
+						const shouldClick = isCurrentTarget && (isNativeButton ? isButton : !isLink);
+						const isEnterKey = event.key === 'Enter';
+						const isSpaceKey = event.key === ' ';
+						const role = currentTarget.getAttribute('role');
+						const isTextNavigationRole =
+							role?.startsWith('menuitem') || role === 'option' || role === 'gridcell';
+
+						if (isCurrentTarget && isCompositeItem && isSpaceKey) {
+							if (event.defaultPrevented && isTextNavigationRole) {
+								return;
+							}
+
+							event.preventDefault();
+
+							// Only a native-mode item that isn't a real <button> is excluded.
+							if (!isNativeButton || isButton) {
+								event.preventBaseUIHandler();
+								dispatchClickWithModifiers(currentTarget, event);
+							}
+
+							return;
+						}
+
+						// Keyboard accessibility for native and non-native elements.
+						if (!shouldClick || isNativeButton || (!isSpaceKey && !isEnterKey)) {
+							// Space activates links on keyup (`role="button"` semantics, matching the
+							// composite path); prevent the page scroll Space would otherwise trigger.
+							// Enter is left to the browser's native link activation.
+							if (isCurrentTarget && isLink && isSpaceKey) {
+								event.preventDefault();
+							}
+							return;
+						}
+
+						// Match native buttons: preventing the keydown's default cancels activation.
+						if (event.defaultPrevented) {
+							return;
+						}
+
+						event.preventDefault();
+
+						if (isEnterKey) {
+							event.preventBaseUIHandler();
+							dispatchClickWithModifiers(currentTarget, event);
+						}
+					},
+					onKeyUp(event: BaseUIEvent<React.KeyboardEvent>) {
+						if (disabled) {
+							return;
+						}
+
+						// calling preventDefault in keyUp on a <button> will not dispatch a click event if Space is pressed
+						// https://codesandbox.io/p/sandbox/button-keyup-preventdefault-dn7f0
+						makeEventPreventable(event);
+						externalOnKeyUp?.(event);
+
+						if (
+							event.target === event.currentTarget &&
+							isNativeButton &&
+							isCompositeItem &&
+							isButtonElement(event.currentTarget as HTMLElement) &&
+							event.key === ' '
+						) {
+							event.preventDefault();
+							return;
+						}
+
+						if (event.baseUIHandlerPrevented) {
+							return;
+						}
+
+						// Keyboard accessibility for non interactive elements.
+						// Match native buttons: preventing the keyup's default cancels Space activation.
+						// Limitation: unlike a native <button>, a prevented *keydown* cannot cancel the
+						// activation — no state is kept between keydown and keyup, so we can't tell
+						// whether the keydown was prevented or even happened on this element.
+						if (
+							event.target === event.currentTarget &&
+							!isNativeButton &&
+							!isCompositeItem &&
+							!event.defaultPrevented &&
+							event.key === ' '
+						) {
+							event.preventBaseUIHandler();
+							dispatchClickWithModifiers(event.currentTarget as Element, event);
+						}
+					},
+					onPointerDown(event: React.PointerEvent) {
+						if (disabled) {
+							event.preventDefault();
+							return;
+						}
+						externalOnPointerDown?.(event);
+					},
+				},
+				isNativeButton ? { type: 'button' } : { role: 'button' },
+				focusableWhenDisabledProps,
+				otherExternalProps,
+			);
+		},
+		[disabled, focusableWhenDisabledProps, isCompositeItem, isNativeButton],
+	);
+
+	const buttonRef = useStableCallback((element: HTMLElement | null) => {
+		elementRef.current = element;
+		updateDisabled();
+	});
+
+	return {
+		getButtonProps,
+		buttonRef,
+	};
+}
+
+function isButtonElement(elem: Element | null): elem is HTMLButtonElement {
+	return isHTMLElement(elem) && elem.tagName === 'BUTTON';
+}
+
+function isValidLinkElement(elem: Element | null): elem is HTMLAnchorElement {
+	return isHTMLElement(elem) && elem.tagName === 'A' && Boolean((elem as HTMLAnchorElement).href);
+}
+
+interface GenericButtonProps extends Omit<HTMLProps, 'onClick'>, AdditionalButtonProps {
+	onClick?: ((event: React.NativeEvent) => void) | undefined;
+}
+
+interface AdditionalButtonProps extends Partial<{
+	'aria-disabled': React.AriaAttributes['aria-disabled'];
+	disabled: boolean;
+	role: React.AriaRole;
+	tabIndex?: number | undefined;
+}> {}
+
+export interface UseButtonParameters {
+	/**
+	 * Whether the component should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+	/**
+	 * Whether the button may receive focus even if it is disabled.
+	 * @default false
+	 */
+	focusableWhenDisabled?: boolean | undefined;
+	tabIndex?: NonNullable<React.HTMLAttributes<any>['tabIndex']> | undefined;
+	/**
+	 * Whether the component is being rendered as a native button.
+	 * @default true
+	 */
+	native?: boolean | undefined;
+	/**
+	 * Whether the button is part of a composite widget.
+	 * When `true`, keyboard activation for Space occurs on keydown rather than keyup.
+	 * @default inferred from CompositeRoot context
+	 */
+	composite?: boolean | undefined;
+}
+
+export interface UseButtonReturnValue {
+	/**
+	 * Resolver for the button props.
+	 * @param externalProps additional props for the button
+	 * @returns props that should be spread on the button
+	 */
+	getButtonProps: (
+		externalProps?: React.ComponentPropsWithRef<any>,
+	) => React.ComponentPropsWithRef<any>;
+	/**
+	 * A ref to the button DOM element. This ref should be passed to the rendered element.
+	 * It is not a part of the props returned by `getButtonProps`.
+	 */
+	buttonRef: React.Ref<HTMLElement>;
+}
+
+export interface UseButtonState {}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };