@octanejs/base-ui 0.1.1

package/src/utils/useButton.ts

@@ -0,0 +1,217 @@
+// Ported from .base-ui/packages/react/src/internals/use-button/useButton.ts (v1.6.0).
+// Produces `getButtonProps` (a prop-merger that adds `type="button"`/`role="button"`,
+// the disabled/aria/tabIndex props, and keyboard-accessibility handlers) plus a
+// `buttonRef`. octane adaptations: events are NATIVE (not synthetic), so the handlers act
+// on the native event directly and `makeEventPreventable` shims `preventBaseUIHandler` /
+// `baseUIHandlerPrevented` onto it; the dev native-<button> warning is dropped.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useCallback, useLayoutEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { mergeProps, makeEventPreventable } from './mergeProps';
+import { useCompositeRootContext } from './CompositeRootContext';
+import { useFocusableWhenDisabled } from './useFocusableWhenDisabled';
+import { useStableCallback } from './useStableCallback';
+
+export interface UseButtonParameters {
+	disabled?: boolean;
+	focusableWhenDisabled?: boolean;
+	tabIndex?: number;
+	native?: boolean;
+	composite?: boolean;
+}
+
+export interface UseButtonReturnValue {
+	getButtonProps: (externalProps?: Record<string, any>) => Record<string, any>;
+	buttonRef: (element: HTMLElement | null) => void;
+}
+
+function isButtonElement(elem: Element | null): elem is HTMLButtonElement {
+	return elem != null && elem instanceof HTMLElement && elem.tagName === 'BUTTON';
+}
+
+function isValidLinkElement(elem: Element | null): elem is HTMLAnchorElement {
+	return Boolean(elem != null && elem.tagName === 'A' && (elem as HTMLAnchorElement).href);
+}
+
+export function useButton(...args: any[]): UseButtonReturnValue {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useButton');
+	const {
+		disabled = false,
+		focusableWhenDisabled,
+		tabIndex = 0,
+		native: isNativeButton = true,
+		composite: compositeProp,
+	} = (user[0] as UseButtonParameters) ?? {};
+
+	const elementRef = useRef<HTMLElement | null>(null, subSlot(slot, 'el'));
+
+	const compositeRootContext = useCompositeRootContext(true);
+	const isCompositeItem = compositeProp ?? compositeRootContext !== undefined;
+
+	const { props: focusableWhenDisabledProps } = useFocusableWhenDisabled(
+		{ focusableWhenDisabled, disabled, composite: isCompositeItem, tabIndex, isNativeButton },
+		subSlot(slot, 'fwd'),
+	);
+
+	// Handle a disabled composite button that renders another button — the `disabled` prop
+	// passes through two `useButton`s, then the attribute is removed from the DOM.
+	const updateDisabled = useCallback(
+		() => {
+			const element = elementRef.current;
+			if (!isButtonElement(element)) {
+				return;
+			}
+			if (
+				isCompositeItem &&
+				disabled &&
+				(focusableWhenDisabledProps as any).disabled === undefined &&
+				element.disabled
+			) {
+				element.disabled = false;
+			}
+		},
+		[disabled, (focusableWhenDisabledProps as any).disabled, isCompositeItem],
+		subSlot(slot, 'upd'),
+	);
+
+	useLayoutEffect(updateDisabled, [updateDisabled], subSlot(slot, 'e:upd'));
+
+	const getButtonProps = useCallback(
+		(externalProps: Record<string, any> = {}) => {
+			const {
+				onClick: externalOnClick,
+				onMouseDown: externalOnMouseDown,
+				onKeyUp: externalOnKeyUp,
+				onKeyDown: externalOnKeyDown,
+				onPointerDown: externalOnPointerDown,
+				...otherExternalProps
+			} = externalProps;
+
+			return mergeProps(
+				{
+					onClick(event: any) {
+						if (disabled) {
+							event.preventDefault();
+							return;
+						}
+						externalOnClick?.(event);
+					},
+					onMouseDown(event: any) {
+						if (!disabled) {
+							externalOnMouseDown?.(event);
+						}
+					},
+					onKeyDown(event: any) {
+						if (disabled) {
+							return;
+						}
+
+						makeEventPreventable(event);
+						externalOnKeyDown?.(event);
+						if (event.baseUIHandlerPrevented) {
+							return;
+						}
+
+						const isCurrentTarget = event.target === event.currentTarget;
+						const currentTarget = event.currentTarget as HTMLElement;
+						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();
+
+							if (isLink || (isNativeButton && isButton)) {
+								currentTarget.click();
+								event.preventBaseUIHandler();
+							} else if (shouldClick) {
+								externalOnClick?.(event);
+								event.preventBaseUIHandler();
+							}
+
+							return;
+						}
+
+						// Keyboard accessibility for native and non-native elements.
+						if (shouldClick) {
+							if (!isNativeButton && (isSpaceKey || isEnterKey)) {
+								event.preventDefault();
+							}
+							if (!isNativeButton && isEnterKey) {
+								externalOnClick?.(event);
+							}
+						}
+					},
+					onKeyUp(event: any) {
+						if (disabled) {
+							return;
+						}
+
+						// preventDefault in keyUp on a <button> won't dispatch a click if Space is pressed.
+						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.
+						if (
+							event.target === event.currentTarget &&
+							!isNativeButton &&
+							!isCompositeItem &&
+							event.key === ' '
+						) {
+							externalOnClick?.(event);
+						}
+					},
+					onPointerDown(event: any) {
+						if (disabled) {
+							event.preventDefault();
+							return;
+						}
+						externalOnPointerDown?.(event);
+					},
+				},
+				isNativeButton ? { type: 'button' } : { role: 'button' },
+				focusableWhenDisabledProps,
+				otherExternalProps,
+			);
+		},
+		[disabled, focusableWhenDisabledProps, isCompositeItem, isNativeButton],
+		subSlot(slot, 'gbp'),
+	);
+
+	const buttonRef = useStableCallback(
+		(element: HTMLElement | null) => {
+			elementRef.current = element;
+			updateDisabled();
+		},
+		subSlot(slot, 'ref'),
+	);
+
+	return { getButtonProps, buttonRef };
+}

package/src/utils/useCheckboxGroupParent.ts

@@ -0,0 +1,113 @@
+// Ported from .base-ui/packages/react/src/checkbox-group/useCheckboxGroupParent.ts. Drives a
+// "select-all" parent checkbox for a CheckboxGroup: checked when all children are on,
+// indeterminate when some are, and a 3-state toggle cycle honoring disabled children.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useCallback, useMemo, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useBaseUiId } from './useBaseUiId';
+import { useStableCallback } from './useStableCallback';
+
+const EMPTY: string[] = [];
+
+export interface UseCheckboxGroupParentParameters {
+	allValues?: string[];
+	value?: string[];
+	onValueChange?: (value: string[], eventDetails: any) => void;
+}
+
+export function useCheckboxGroupParent(...args: any[]): any {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCheckboxGroupParent');
+	const {
+		allValues = EMPTY,
+		value = EMPTY,
+		onValueChange: onValueChangeProp,
+	} = (user[0] as UseCheckboxGroupParentParameters) ?? {};
+
+	const uncontrolledStateRef = useRef(value, subSlot(slot, 'uncontrolled'));
+	const disabledStatesRef = useRef(new Map<string, boolean>(), subSlot(slot, 'disabledStates'));
+
+	const [status, setStatus] = useState<'on' | 'off' | 'mixed'>('mixed', subSlot(slot, 'status'));
+
+	const id = useBaseUiId(undefined, subSlot(slot, 'id'));
+	const checked = value.length === allValues.length;
+	const indeterminate = value.length !== allValues.length && value.length > 0;
+
+	const onValueChange = useStableCallback(onValueChangeProp, subSlot(slot, 'onValueChange'));
+
+	const getParentProps = useCallback(
+		() => ({
+			id,
+			indeterminate,
+			checked,
+			'aria-controls': allValues.map((v) => `${id}-${v}`).join(' '),
+			onCheckedChange(_: boolean, eventDetails: any) {
+				const uncontrolledState = uncontrolledStateRef.current;
+				const none = allValues.filter(
+					(v) => disabledStatesRef.current.get(v) && uncontrolledState.includes(v),
+				);
+				const all = allValues.filter(
+					(v) =>
+						!disabledStatesRef.current.get(v) ||
+						(disabledStatesRef.current.get(v) && uncontrolledState.includes(v)),
+				);
+				const allOnOrOff =
+					uncontrolledState.length === all.length || uncontrolledState.length === 0;
+
+				if (allOnOrOff) {
+					if (value.length === all.length) {
+						onValueChange(none, eventDetails);
+					} else {
+						onValueChange(all, eventDetails);
+					}
+					return;
+				}
+
+				let nextStatus: 'on' | 'off' | 'mixed' = 'mixed';
+				let nextValue = uncontrolledState;
+				if (status === 'mixed') {
+					nextStatus = 'on';
+					nextValue = all;
+				} else if (status === 'on') {
+					nextStatus = 'off';
+					nextValue = none;
+				}
+				onValueChange(nextValue, eventDetails);
+				if (!eventDetails.isCanceled) {
+					setStatus(nextStatus);
+				}
+			},
+		}),
+		[allValues, checked, id, indeterminate, onValueChange, status, value.length],
+		subSlot(slot, 'getParentProps'),
+	);
+
+	const getChildProps = useCallback(
+		(childValue: string) => ({
+			checked: value.includes(childValue),
+			onCheckedChange(nextChecked: boolean, eventDetails: any) {
+				const newValue = value.slice();
+				if (nextChecked) {
+					newValue.push(childValue);
+				} else {
+					newValue.splice(newValue.indexOf(childValue), 1);
+				}
+				onValueChange(newValue, eventDetails);
+				if (!eventDetails.isCanceled) {
+					uncontrolledStateRef.current = newValue;
+					setStatus('mixed');
+				}
+			},
+		}),
+		[onValueChange, value],
+		subSlot(slot, 'getChildProps'),
+	);
+
+	return useMemo(
+		() => ({ id, indeterminate, getParentProps, getChildProps, disabledStatesRef }),
+		[id, indeterminate, getParentProps, getChildProps],
+		subSlot(slot, 'return'),
+	);
+}

package/src/utils/useControlled.ts

@@ -0,0 +1,42 @@
+// Ported from .base-ui/packages/utils/src/useControlled.ts. The controlled/uncontrolled
+// state hook: `controlled !== undefined` decides (once, at first render) whether the
+// component is controlled; the setter only writes local state when uncontrolled. Base UI's
+// dev warnings (switching controlled↔uncontrolled, changing the default) are dropped
+// (dev-only surface).
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useCallback, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface UseControlledProps<T = unknown> {
+	controlled: T | undefined;
+	default: T | undefined;
+	name: string;
+	state?: string;
+}
+
+export function useControlled<T = unknown>(
+	...args: any[]
+): [T, (newValue: T | ((prevValue: T) => T)) => void] {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useControlled');
+	const { controlled, default: defaultProp } = user[0] as UseControlledProps<T>;
+
+	// `isControlled` never changes over the component's lifetime.
+	const { current: isControlled } = useRef(controlled !== undefined, subSlot(slot, 'ctrl'));
+	const [valueState, setValue] = useState(defaultProp, subSlot(slot, 'val'));
+	const value = isControlled ? controlled : valueState;
+
+	const setValueIfUncontrolled = useCallback(
+		(newValue: T | ((prevValue: T) => T)) => {
+			if (!isControlled) {
+				setValue(newValue as any);
+			}
+		},
+		[],
+		subSlot(slot, 'set'),
+	);
+
+	return [value as T, setValueIfUncontrolled];
+}

package/src/utils/useFocusableWhenDisabled.ts

@@ -0,0 +1,84 @@
+// Ported verbatim from .base-ui/packages/react/src/utils/useFocusableWhenDisabled.ts.
+// Computes the tabIndex / aria-disabled / disabled / onKeyDown props a button-like element
+// needs so it can (optionally) stay focusable while disabled. Pure prop computation.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useMemo } from 'octane';
+
+import { S, splitSlot } from '../internal';
+
+export interface UseFocusableWhenDisabledParameters {
+	focusableWhenDisabled?: boolean;
+	disabled: boolean;
+	composite?: boolean;
+	tabIndex?: number;
+	isNativeButton: boolean;
+}
+
+export interface FocusableWhenDisabledProps {
+	'aria-disabled'?: boolean;
+	disabled?: boolean;
+	onKeyDown: (event: KeyboardEvent) => void;
+	tabIndex: number;
+}
+
+export function useFocusableWhenDisabled(...args: any[]): { props: FocusableWhenDisabledProps } {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFocusableWhenDisabled');
+	const {
+		focusableWhenDisabled,
+		disabled,
+		composite = false,
+		tabIndex: tabIndexProp = 0,
+		isNativeButton,
+	} = user[0] as UseFocusableWhenDisabledParameters;
+
+	const isFocusableComposite = composite && focusableWhenDisabled !== false;
+	const isNonFocusableComposite = composite && focusableWhenDisabled === false;
+
+	// We can't explicitly assign `undefined` to any of these props — that would prevent a
+	// subsequently merged prop from setting them.
+	const props = useMemo(
+		() => {
+			const additionalProps = {
+				onKeyDown(event: KeyboardEvent) {
+					if (disabled && focusableWhenDisabled && event.key !== 'Tab') {
+						event.preventDefault();
+					}
+				},
+			} as FocusableWhenDisabledProps;
+
+			if (!composite) {
+				additionalProps.tabIndex = tabIndexProp;
+				if (!isNativeButton && disabled) {
+					additionalProps.tabIndex = focusableWhenDisabled ? tabIndexProp : -1;
+				}
+			}
+
+			if (
+				(isNativeButton && (focusableWhenDisabled || isFocusableComposite)) ||
+				(!isNativeButton && disabled)
+			) {
+				additionalProps['aria-disabled'] = disabled;
+			}
+
+			if (isNativeButton && (!focusableWhenDisabled || isNonFocusableComposite)) {
+				additionalProps.disabled = disabled;
+			}
+
+			return additionalProps;
+		},
+		[
+			composite,
+			disabled,
+			focusableWhenDisabled,
+			isFocusableComposite,
+			isNonFocusableComposite,
+			isNativeButton,
+			tabIndexProp,
+		],
+		slot,
+	);
+
+	return { props };
+}

package/src/utils/useForcedRerendering.ts

@@ -0,0 +1,11 @@
+// Ported from .base-ui/packages/utils/src/useForcedRerendering.ts.
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useCallback, useState } from 'octane';
+import { S, splitSlot, subSlot } from '../internal';
+
+export function useForcedRerendering(...args: any[]): () => void {
+	const [, slotArg] = splitSlot(['_', ...args]);
+	const slot = slotArg ?? S('useForcedRerendering');
+	const [, setState] = useState({}, subSlot(slot, 'state'));
+	return useCallback(() => setState({}), [], subSlot(slot, 'cb'));
+}

package/src/utils/useIsHydrating.ts

@@ -0,0 +1,9 @@
+// Ported from .base-ui/packages/react/src/utils/useIsHydrating.ts. React drives this via
+// `useSyncExternalStore` (server snapshot `true`, client snapshot `false`) so the first client
+// paint of a hydrated tree matches the server, then flips to `false`. octane's binding renders
+// client-only in these tests, so a fresh mount is never hydrating — returns `false`. It only
+// gates the `thumbAlignment: 'edge'` pre-hydration visibility path (inert for the default
+// `center` alignment).
+export function useIsHydrating(): boolean {
+	return false;
+}

package/src/utils/useOpenChangeComplete.ts

@@ -0,0 +1,46 @@
+// Ported from .base-ui/packages/react/src/internals/useOpenChangeComplete.tsx. Calls
+// `onComplete` once the element's open/close CSS animation finishes (or immediately when
+// there's no animation / no element).
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useEffect } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useStableCallback } from './useStableCallback';
+import { useAnimationsFinished } from './useAnimationsFinished';
+
+export interface UseOpenChangeCompleteParameters {
+	enabled?: boolean;
+	open?: boolean;
+	ref: { current: HTMLElement | null };
+	onComplete: () => void;
+}
+
+export function useOpenChangeComplete(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useOpenChangeComplete');
+	const {
+		enabled = true,
+		open,
+		ref,
+		onComplete: onCompleteParam,
+	} = user[0] as UseOpenChangeCompleteParameters;
+
+	const onComplete = useStableCallback(onCompleteParam, subSlot(slot, 'oc'));
+	const runOnceAnimationsFinish = useAnimationsFinished(ref, open, false, subSlot(slot, 'raf'));
+
+	useEffect(
+		() => {
+			if (!enabled) {
+				return undefined;
+			}
+			const abortController = new AbortController();
+			runOnceAnimationsFinish(onComplete, abortController.signal);
+			return () => {
+				abortController.abort();
+			};
+		},
+		[enabled, open, onComplete, runOnceAnimationsFinish],
+		subSlot(slot, 'e:run'),
+	);
+}

package/src/utils/usePressAndHold.ts

@@ -0,0 +1,35 @@
+// Minimal stand-in for .base-ui/packages/react/src/internals/usePressAndHold.ts. The full hook
+// implements hold-to-auto-repeat + touch/scroll heuristics (288 lines, deferred). This stub
+// provides inert pointer handlers so single-press stepping (via the button's own onClick) works
+// and never skips a click. TODO: port the full auto-repeat behavior + dedicated timing tests.
+export function isTouchLikePointerType(pointerType: string): boolean {
+	return pointerType === 'touch' || pointerType === 'pen';
+}
+
+export interface UsePressAndHoldParameters {
+	disabled: boolean;
+	readOnly?: boolean;
+	tick: (triggerEvent?: any) => boolean;
+	onStop?: (nativeEvent: any) => void;
+	tickDelay?: number;
+	startDelay?: number;
+	scrollDistance?: number;
+	elementRef: { current: HTMLElement | null };
+}
+
+export function usePressAndHold(_params: UsePressAndHoldParameters): {
+	pointerHandlers: Record<string, (event: any) => void>;
+	shouldSkipClick: (event: any) => boolean;
+} {
+	return {
+		pointerHandlers: {
+			onTouchStart() {},
+			onTouchEnd() {},
+			onPointerDown() {},
+			onPointerUp() {},
+			onPointerMove() {},
+			onPointerLeave() {},
+		},
+		shouldSkipClick: () => false,
+	};
+}

package/src/utils/useRefWithInit.ts

@@ -0,0 +1,23 @@
+// Ported from .base-ui/packages/utils/src/useRefWithInit.ts. A ref whose `.current` is
+// lazily initialized once via `init(arg)` — avoids re-running the factory (and the
+// allocation) on every render that a plain `useRef(init())` would incur.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+const UNSET: unique symbol = Symbol('base-ui.useRefWithInit.unset');
+
+export function useRefWithInit<T, A = undefined>(...args: any[]): { current: T } {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useRefWithInit');
+	const init = user[0] as (arg?: A) => T;
+	const arg = user[1] as A | undefined;
+
+	const ref = useRef<T | typeof UNSET>(UNSET, subSlot(slot, 'ref'));
+	if (ref.current === UNSET) {
+		ref.current = init(arg);
+	}
+	return ref as { current: T };
+}

package/src/utils/useRegisteredLabelId.ts

@@ -0,0 +1,32 @@
+// Ported from .base-ui/packages/react/src/utils/useRegisteredLabelId.ts. Generates a
+// stable id (via useBaseUiId) and registers it with the owning Root through a layout
+// effect (`setLabelId(id)`; cleared on unmount) — the Root reflects it as
+// `aria-labelledby`. Shared by Meter.Label / Progress.Label.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useBaseUiId } from './useBaseUiId';
+
+export function useRegisteredLabelId(...args: any[]): string | undefined {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useRegisteredLabelId');
+	const idProp = user[0] as string | undefined;
+	const setLabelId = user[1] as (id: string | undefined) => void;
+
+	const id = useBaseUiId(idProp, subSlot(slot, 'id'));
+
+	useLayoutEffect(
+		() => {
+			setLabelId(id);
+			return () => {
+				setLabelId(undefined);
+			};
+		},
+		[id, setLabelId],
+		subSlot(slot, 'e:label'),
+	);
+
+	return id;
+}