@octanejs/base-ui 0.1.50 → 0.1.51

package/src/toggle/Toggle.tsrx

@@ -0,0 +1,198 @@
+'use client';
+import * as React from 'octane';
+import { useControlled } from '@octanejs/base-ui-utils/useControlled';
+import { error } from '@octanejs/base-ui-utils/error';
+import { useBaseUiId } from '../internals/useBaseUiId';
+import { useRenderElement } from '../internals/useRenderElement.tsrx';
+import type { BaseUIComponentProps, NativeButtonProps } from '../internals/types';
+import { useToggleGroupContext } from '../toggle-group/ToggleGroupContext';
+import type { ToolbarRoot } from '../toolbar/root/ToolbarRoot.tsrx';
+import { useButton } from '../internals/use-button/useButton';
+import { CompositeItem } from '../internals/composite/item/CompositeItem.tsrx';
+import {
+	type BaseUIChangeEventDetails,
+	createChangeEventDetails,
+} from '../internals/createBaseUIEventDetails';
+import { REASONS } from '../internals/reasons';
+
+/**
+ * A two-state button that can be on or off.
+ * Renders a `<button>` element.
+ *
+ * Documentation: [Base UI Toggle](https://base-ui.com/react/components/toggle)
+ */
+export const Toggle = function Toggle<Value extends string>(
+	componentPropsWithRef: React.PropsWithoutRef<Toggle.Props<Value>> & {
+		ref?: React.Ref<HTMLButtonElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		className,
+		defaultPressed = false,
+		disabled: disabledProp = false,
+		form, // never participates in form validation
+		onPressedChange,
+		pressed: pressedProp,
+		render,
+		type, // cannot change button type
+		value: valueProp,
+		nativeButton = true,
+		style,
+		...elementProps
+	} = componentProps;
+
+	// `|| undefined` handles cases, where value is falsy (i.e. "")
+	const value = useBaseUiId(valueProp || undefined);
+	const groupContext = useToggleGroupContext();
+	const groupValue = groupContext?.value ?? [];
+
+	const disabled = (disabledProp || groupContext?.disabled) ?? false;
+
+	if (process.env.NODE_ENV !== 'production') {
+		// eslint-disable-next-line react-hooks/rules-of-hooks
+		React.useEffect(() => {
+			if (groupContext && valueProp === undefined && groupContext.isValueInitialized) {
+				error(
+					'A `<Toggle>` component rendered in a `<ToggleGroup>` has no explicit `value` prop.',
+					'This will cause issues between the Toggle Group and Toggle values.',
+					'Provide the `<Toggle>` with a `value` prop matching the `<ToggleGroup>` values prop type.',
+				);
+			}
+		}, [groupContext, valueProp, groupContext?.isValueInitialized]);
+	}
+
+	const [pressed, setPressedState] = useControlled({
+		controlled: groupContext ? value !== undefined && groupValue.indexOf(value) > -1 : pressedProp,
+		default: defaultPressed,
+		name: 'Toggle',
+		state: 'pressed',
+	});
+
+	const { getButtonProps, buttonRef } = useButton({
+		disabled,
+		native: nativeButton,
+	});
+
+	const state: ToggleState = {
+		disabled,
+		pressed,
+	};
+
+	const refs = [buttonRef, forwardedRef];
+	const props = [
+		{
+			'aria-pressed': pressed,
+			onClick(event: React.MouseEvent) {
+				const nextPressed = !pressed;
+				const details = createChangeEventDetails(REASONS.none, event);
+
+				// `onPressedChange` runs before the group commits so that canceling here
+				// can also veto the group value change, which shares this `details` object.
+				onPressedChange?.(nextPressed, details);
+
+				if (details.isCanceled) {
+					return;
+				}
+
+				if (value) {
+					groupContext?.setGroupValue?.(value, nextPressed, details);
+				}
+
+				if (details.isCanceled) {
+					return;
+				}
+
+				setPressedState(nextPressed);
+			},
+		},
+		elementProps,
+		getButtonProps,
+	];
+
+	const element = useRenderElement('button', componentProps, {
+		enabled: !groupContext,
+		state,
+		ref: refs,
+		props,
+	});
+
+	// A disabled toggle is natively disabled and cannot hold roving focus.
+	// Toolbar reads this metadata to compute its `disabledIndices`.
+	const itemMetadata: ToolbarRoot.ItemMetadata = React.useMemo(
+		() => ({ disabled, focusableWhenDisabled: false }),
+		[disabled],
+	);
+
+	if (groupContext) {
+		return (
+			<CompositeItem
+				tag="button"
+				render={render}
+				className={className}
+				style={style}
+				metadata={itemMetadata}
+				state={state}
+				refs={refs}
+				props={props}
+			/>
+		);
+	}
+
+	return element;
+};
+
+export interface ToggleState {
+	/**
+	 * Whether the toggle is currently pressed.
+	 */
+	pressed: boolean;
+	/**
+	 * Whether the toggle should ignore user interaction.
+	 */
+	disabled: boolean;
+}
+
+export interface ToggleProps<Value extends string>
+	extends NativeButtonProps, BaseUIComponentProps<'button', ToggleState> {
+	/**
+	 * Whether the toggle button is currently pressed.
+	 * This is the controlled counterpart of `defaultPressed`.
+	 */
+	pressed?: boolean | undefined;
+	/**
+	 * Whether the toggle button is currently pressed.
+	 * This is the uncontrolled counterpart of `pressed`.
+	 * @default false
+	 */
+	defaultPressed?: boolean | undefined;
+	/**
+	 * Whether the component should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+	/**
+	 * Callback fired when the pressed state is changed.
+	 */
+	onPressedChange?:
+		((pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void) | undefined;
+	/**
+	 * A unique string that identifies the toggle when used
+	 * inside a toggle group.
+	 */
+	value?: Value | undefined;
+}
+
+export type ToggleChangeEventReason = typeof REASONS.none;
+
+export type ToggleChangeEventDetails = BaseUIChangeEventDetails<Toggle.ChangeEventReason>;
+
+export namespace Toggle {
+	export type State = ToggleState;
+	export type Props<TValue extends string = string> = ToggleProps<TValue>;
+	export type ChangeEventReason = ToggleChangeEventReason;
+	export type ChangeEventDetails = ToggleChangeEventDetails;
+}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };

package/src/toggle/ToggleDataAttributes.ts

@@ -0,0 +1,8 @@
+/**
+ * Present when the toggle button is pressed.
+ */
+export const pressed = 'data-pressed';
+/**
+ * Present when the toggle button is disabled.
+ */
+export const disabled = 'data-disabled';

package/src/toggle/index.ts

@@ -0,0 +1,3 @@
+export { Toggle } from './Toggle.tsrx';
+
+export type * from './Toggle.tsrx';

package/src/toggle-group/ToggleGroup.tsrx

@@ -0,0 +1,201 @@
+'use client';
+import * as React from 'octane';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useControlled } from '@octanejs/base-ui-utils/useControlled';
+import { EMPTY_ARRAY } from '@octanejs/base-ui-utils/empty';
+import { useRenderElement } from '../internals/useRenderElement.tsrx';
+import type { BaseUIComponentProps, HTMLProps, Orientation } from '../internals/types';
+import { CompositeRoot } from '../internals/composite/root/CompositeRoot.tsrx';
+import { useToolbarRootContext } from '../toolbar/root/ToolbarRootContext';
+import { useToolbarGroupContext } from '../toolbar/group/ToolbarGroupContext';
+import { ToggleGroupContext } from './ToggleGroupContext';
+import type { BaseUIChangeEventDetails } from '../internals/createBaseUIEventDetails';
+import type { REASONS } from '../internals/reasons';
+
+/**
+ * Provides a shared state to a series of toggle buttons.
+ *
+ * Documentation: [Base UI Toggle Group](https://base-ui.com/react/components/toggle-group)
+ */
+export const ToggleGroup = function ToggleGroup<Value extends string>(
+	componentPropsWithRef: React.PropsWithoutRef<ToggleGroup.Props<Value>> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		defaultValue: defaultValueProp,
+		disabled: disabledProp = false,
+		loopFocus = true,
+		onValueChange,
+		orientation = 'horizontal',
+		multiple = false,
+		value: valueProp,
+		className,
+		render,
+		style,
+		...elementProps
+	} = componentProps;
+
+	const toolbarContext = useToolbarRootContext(true);
+	const toolbarGroupContext = useToolbarGroupContext();
+
+	const defaultValue = defaultValueProp ?? EMPTY_ARRAY;
+	// Use the raw prop to distinguish an omitted value from the empty default.
+	const isValueInitialized = valueProp !== undefined || defaultValueProp !== undefined;
+
+	const disabled =
+		(toolbarContext?.disabled ?? false) || (toolbarGroupContext?.disabled ?? false) || disabledProp;
+
+	const [groupValue, setValueState] = useControlled({
+		controlled: valueProp,
+		default: defaultValue,
+		name: 'ToggleGroup',
+		state: 'value',
+	});
+
+	const setGroupValue = useStableCallback(
+		(
+			newValue: Value,
+			nextPressed: boolean,
+			eventDetails: BaseUIChangeEventDetails<typeof REASONS.none>,
+		) => {
+			let newGroupValue: Value[];
+			if (multiple) {
+				newGroupValue = groupValue.slice();
+				if (nextPressed) {
+					newGroupValue.push(newValue);
+				} else {
+					newGroupValue.splice(groupValue.indexOf(newValue), 1);
+				}
+			} else {
+				newGroupValue = nextPressed ? [newValue] : [];
+			}
+
+			onValueChange?.(newGroupValue, eventDetails);
+
+			if (eventDetails.isCanceled) {
+				return;
+			}
+
+			setValueState(newGroupValue);
+		},
+	);
+
+	const state: ToggleGroupState = { disabled, multiple, orientation };
+
+	const contextValue: ToggleGroupContext<Value> = React.useMemo(
+		() => ({
+			disabled,
+			setGroupValue,
+			value: groupValue,
+			isValueInitialized,
+		}),
+		[disabled, setGroupValue, groupValue, isValueInitialized],
+	);
+
+	const defaultProps: HTMLProps = {
+		role: 'group',
+	};
+
+	const element = useRenderElement('div', componentProps, {
+		enabled: Boolean(toolbarContext),
+		state,
+		ref: forwardedRef,
+		props: [defaultProps, elementProps],
+	});
+
+	return (
+		<ToggleGroupContext.Provider value={contextValue}>
+			{toolbarContext ? (
+				element
+			) : (
+				<CompositeRoot
+					render={render}
+					className={className}
+					style={style}
+					state={state}
+					refs={[forwardedRef]}
+					props={[defaultProps, elementProps]}
+					loopFocus={loopFocus}
+					enableHomeAndEndKeys
+					orientation={orientation}
+				/>
+			)}
+		</ToggleGroupContext.Provider>
+	);
+};
+
+export interface ToggleGroupState {
+	/**
+	 * Whether the component should ignore user interaction.
+	 */
+	disabled: boolean;
+	/**
+	 * When `false` only one item in the group can be pressed. If any item in
+	 * the group becomes pressed, the others will become unpressed.
+	 * When `true` multiple items can be pressed.
+	 * @default false
+	 */
+	multiple: boolean;
+	/**
+	 * The orientation of the toggle group.
+	 */
+	orientation: Orientation;
+}
+
+export interface ToggleGroupProps<Value extends string> extends BaseUIComponentProps<
+	'div',
+	ToggleGroupState
+> {
+	/**
+	 * The pressed state of the toggle group represented by an array of
+	 * the values of all pressed toggle buttons.
+	 * This is the controlled counterpart of `defaultValue`.
+	 */
+	value?: readonly Value[] | undefined;
+	/**
+	 * The pressed state of the toggle group represented by an array of
+	 * the values of all pressed toggle buttons.
+	 * This is the uncontrolled counterpart of `value`.
+	 */
+	defaultValue?: readonly Value[] | undefined;
+	/**
+	 * Callback fired when the pressed states of the toggle group changes.
+	 */
+	onValueChange?:
+		((groupValue: Value[], eventDetails: ToggleGroup.ChangeEventDetails) => void) | undefined;
+	/**
+	 * Whether the toggle group should ignore user interaction.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+	/**
+	 * @default 'horizontal'
+	 */
+	orientation?: Orientation | undefined;
+	/**
+	 * Whether to loop keyboard focus back to the first item
+	 * when the end of the list is reached while using the arrow keys.
+	 * @default true
+	 */
+	loopFocus?: boolean | undefined;
+	/**
+	 * When `false` only one item in the group can be pressed. If any item in
+	 * the group becomes pressed, the others will become unpressed.
+	 * When `true` multiple items can be pressed.
+	 * @default false
+	 */
+	multiple?: boolean | undefined;
+}
+
+export type ToggleGroupChangeEventReason = typeof REASONS.none;
+
+export type ToggleGroupChangeEventDetails = BaseUIChangeEventDetails<ToggleGroup.ChangeEventReason>;
+
+export namespace ToggleGroup {
+	export type State = ToggleGroupState;
+	export type Props<Value extends string = string> = ToggleGroupProps<Value>;
+	export type ChangeEventReason = ToggleGroupChangeEventReason;
+	export type ChangeEventDetails = ToggleGroupChangeEventDetails;
+}

package/src/toggle-group/ToggleGroupContext.ts

@@ -0,0 +1,28 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import type { BaseUIChangeEventDetails } from '../internals/createBaseUIEventDetails';
+import type { BaseUIEventReasons } from '../internals/reasons';
+
+export interface ToggleGroupContext<Value> {
+	value: readonly Value[];
+	setGroupValue: (
+		newValue: Value,
+		nextPressed: boolean,
+		eventDetails: BaseUIChangeEventDetails<BaseUIEventReasons['none']>,
+	) => void;
+	disabled: boolean;
+	/**
+	 * Indicates whether the value has been initialized via `value` or `defaultValue` props.
+	 * Used to determine if Toggle should warn users about data inconsistency problems.
+	 */
+	isValueInitialized: boolean;
+}
+
+export const ToggleGroupContext = React.createContext<ToggleGroupContext<any> | undefined>(
+	undefined,
+);
+
+export function useToggleGroupContext<Value>() {
+	return React.useContext<ToggleGroupContext<Value> | undefined>(ToggleGroupContext);
+}

package/src/toggle-group/ToggleGroupDataAttributes.ts

@@ -0,0 +1,13 @@
+/**
+ * Present when the toggle group is disabled.
+ */
+export const disabled = 'data-disabled';
+/**
+ * Indicates the orientation of the toggle group.
+ * @type {'horizontal' | 'vertical'}
+ */
+export const orientation = 'data-orientation';
+/**
+ * Present when the toggle group allows multiple buttons to be in the pressed state at the same time.
+ */
+export const multiple = 'data-multiple';

package/src/toggle-group/index.ts

@@ -0,0 +1,3 @@
+export { ToggleGroup } from './ToggleGroup.tsrx';
+
+export type * from './ToggleGroup.tsrx';

package/src/toolbar/button/ToolbarButton.tsrx

@@ -0,0 +1,108 @@
+'use client';
+import * as React from 'octane';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import type { BaseUIComponentProps, NativeButtonProps } from '../../internals/types';
+import { useButton } from '../../internals/use-button';
+import type { ToolbarRootState } from '../root/ToolbarRoot.tsrx';
+import { useToolbarRootContext } from '../root/ToolbarRootContext';
+import { useToolbarGroupContext } from '../group/ToolbarGroupContext';
+import { CompositeItem } from '../../internals/composite/item/CompositeItem.tsrx';
+
+/**
+ * A button that can be used as-is or as a trigger for other components.
+ * Renders a `<button>` element.
+ *
+ * Documentation: [Base UI Toolbar](https://base-ui.com/react/components/toolbar)
+ */
+export const ToolbarButton = function ToolbarButton(
+	componentPropsWithRef: React.PropsWithoutRef<ToolbarButton.Props> & {
+		ref?: React.Ref<HTMLButtonElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		className,
+		disabled: disabledProp = false,
+		focusableWhenDisabled = true,
+		render,
+		nativeButton,
+		style,
+		...elementProps
+	} = componentProps;
+
+	const { disabled: toolbarDisabled, orientation } = useToolbarRootContext();
+
+	const groupContext = useToolbarGroupContext();
+
+	const disabled = toolbarDisabled || (groupContext?.disabled ?? false) || disabledProp;
+
+	const itemMetadata = React.useMemo(
+		() => ({ disabled, focusableWhenDisabled }),
+		[disabled, focusableWhenDisabled],
+	);
+
+	const { getButtonProps, buttonRef } = useButton({
+		disabled,
+		focusableWhenDisabled,
+		native: nativeButton,
+	});
+
+	const state: ToolbarButtonState = {
+		disabled,
+		orientation,
+		focusable: focusableWhenDisabled,
+	};
+
+	return (
+		<CompositeItem
+			tag="button"
+			render={render}
+			className={className}
+			style={style}
+			metadata={itemMetadata}
+			state={state}
+			refs={[forwardedRef, buttonRef]}
+			props={[
+				elementProps,
+				// When a render prop is provided (typically another Base UI component
+				// like Menu.Trigger), forward `disabled` so the rendered component can
+				// derive its own disabled state. For the default toolbar button, avoid
+				// forwarding a React `disabled` prop so focusable disabled buttons remain
+				// hoverable for interactions like tooltips.
+				// TODO: follow up after https://github.com/mui/base-ui/issues/1976#issuecomment-2916905663
+				render ? { disabled } : EMPTY_OBJECT,
+				getButtonProps,
+			]}
+		/>
+	);
+};
+
+export interface ToolbarButtonState extends ToolbarRootState {
+	/**
+	 * Whether the component is disabled.
+	 */
+	disabled: boolean;
+	/**
+	 * Whether the component remains focusable when disabled.
+	 */
+	focusable: boolean;
+}
+
+export interface ToolbarButtonProps
+	extends NativeButtonProps, BaseUIComponentProps<'button', ToolbarButtonState> {
+	/**
+	 * When `true` the item is disabled.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+	/**
+	 * When `true` the item remains focusable when disabled.
+	 * @default true
+	 */
+	focusableWhenDisabled?: boolean | undefined;
+}
+
+export namespace ToolbarButton {
+	export type State = ToolbarButtonState;
+	export type Props = ToolbarButtonProps;
+}

package/src/toolbar/button/ToolbarButtonDataAttributes.ts

@@ -0,0 +1,13 @@
+/**
+ * Present when the button is disabled.
+ */
+export const disabled = 'data-disabled';
+/**
+ * Indicates the orientation of the toolbar.
+ * @type {'horizontal' | 'vertical'}
+ */
+export const orientation = 'data-orientation';
+/**
+ * Present when the button remains focusable when disabled.
+ */
+export const focusable = 'data-focusable';

package/src/toolbar/group/ToolbarGroup.tsrx

@@ -0,0 +1,69 @@
+'use client';
+import * as React from 'octane';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useToolbarRootContext } from '../root/ToolbarRootContext';
+import type { ToolbarRootState } from '../root/ToolbarRoot.tsrx';
+import { ToolbarGroupContext } from './ToolbarGroupContext';
+
+/**
+ * Groups several toolbar items or toggles.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Toolbar](https://base-ui.com/react/components/toolbar)
+ */
+export const ToolbarGroup = function ToolbarGroup(
+	componentPropsWithRef: React.PropsWithoutRef<ToolbarGroup.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		className,
+		disabled: disabledProp = false,
+		render,
+		style,
+		...elementProps
+	} = componentProps;
+
+	const { orientation, disabled: toolbarDisabled } = useToolbarRootContext();
+
+	const disabled = toolbarDisabled || disabledProp;
+
+	const contextValue: ToolbarGroupContext = React.useMemo(
+		() => ({
+			disabled,
+		}),
+		[disabled],
+	);
+
+	const state: ToolbarRootState = {
+		disabled,
+		orientation,
+	};
+
+	const element = useRenderElement('div', componentProps, {
+		state,
+		ref: forwardedRef,
+		props: [{ role: 'group' }, elementProps],
+	});
+
+	return (
+		<ToolbarGroupContext.Provider value={contextValue}>{element}</ToolbarGroupContext.Provider>
+	);
+};
+
+export interface ToolbarGroupState extends ToolbarRootState {}
+
+export interface ToolbarGroupProps extends BaseUIComponentProps<'div', ToolbarGroupState> {
+	/**
+	 * When `true` all toolbar items in the group are disabled.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+}
+
+export namespace ToolbarGroup {
+	export type State = ToolbarGroupState;
+	export type Props = ToolbarGroupProps;
+}

package/src/toolbar/group/ToolbarGroupContext.ts

@@ -0,0 +1,13 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+
+export interface ToolbarGroupContext {
+	disabled: boolean;
+}
+
+export const ToolbarGroupContext = React.createContext<ToolbarGroupContext | undefined>(undefined);
+
+export function useToolbarGroupContext(): ToolbarGroupContext | undefined {
+	return React.useContext(ToolbarGroupContext);
+}

package/src/toolbar/group/ToolbarGroupDataAttributes.ts

@@ -0,0 +1,9 @@
+/**
+ * Present when the group is disabled.
+ */
+export const disabled = 'data-disabled';
+/**
+ * Indicates the orientation of the toolbar.
+ * @type {'horizontal' | 'vertical'}
+ */
+export const orientation = 'data-orientation';

package/src/toolbar/index.parts.ts

@@ -0,0 +1,8 @@
+export { ToolbarSeparator as Separator } from './separator/ToolbarSeparator.tsrx';
+export { ToolbarRoot as Root } from './root/ToolbarRoot.tsrx';
+export { ToolbarGroup as Group } from './group/ToolbarGroup.tsrx';
+export { ToolbarButton as Button } from './button/ToolbarButton.tsrx';
+export { ToolbarLink as Link } from './link/ToolbarLink.tsrx';
+export { ToolbarInput as Input } from './input/ToolbarInput.tsrx';
+
+export { type Orientation } from '../internals/types';