@octanejs/base-ui 0.1.1

package/src/utils/useRenderElement.ts

@@ -0,0 +1,165 @@
+// Ported from .base-ui/packages/react/src/internals/useRenderElement.tsx (v1.6.0).
+//
+// The single composition engine every Base UI part routes through. It resolves the
+// component's `render` (a JSX element OR `(props, state) => element`) + `className`
+// (string|fn) + `style` (object|fn) + `state`→`data-*`, merges them with the
+// behavior/intrinsic props, composes refs, and produces the final element via
+// octane's `cloneElement`/`createElement`.
+//
+// octane specifics: no rules of hooks, so the ref-merge hook is called
+// unconditionally (Base UI's `typeof document` + conditional-hook dance is dropped);
+// `render`-as-function returns octane JSX directly; ref is a plain prop.
+//
+// SLOT: this is a plain-`.ts` hook consumed from source (excluded from auto-slotting),
+// so it forwards the caller's slot. The component passes `subSlot(componentSlot, 're')`
+// as the trailing arg.
+import { createElement, cloneElement } from 'octane';
+
+import { splitSlot, subSlot, S } from '../internal';
+import { useComposedRefs } from './composeRefs';
+import { getElementRef } from './getElementRef';
+import { getStateAttributesProps, type StateAttributesMapping } from './getStateAttributesProps';
+import { mergeObjects } from './mergeObjects';
+import { resolveClassName } from './resolveClassName';
+import { resolveStyle } from './resolveStyle';
+import { mergeProps, mergePropsN, mergeClassNames } from './mergeProps';
+
+const EMPTY_OBJECT: Record<string, any> = {};
+
+export type RenderProp<State> =
+	| ((props: Record<string, any>, state: State) => any)
+	| any /* element descriptor */;
+
+export interface UseRenderElementComponentProps<State> {
+	className?: string | ((state: State) => string | undefined);
+	render?: RenderProp<State>;
+	style?: Record<string, any> | ((state: State) => Record<string, any> | undefined);
+}
+
+export interface UseRenderElementParameters<State> {
+	enabled?: boolean;
+	ref?: any;
+	state?: State;
+	props?: Record<string, any> | Array<Record<string, any> | undefined | ((p: any) => any)>;
+	stateAttributesMapping?: StateAttributesMapping<State>;
+}
+
+export function useRenderElement<State extends Record<string, any>>(
+	element: string | undefined,
+	componentProps: UseRenderElementComponentProps<State>,
+	params: UseRenderElementParameters<State> = {},
+	...slotArgs: any[]
+): any {
+	const [, slotArg] = splitSlot(['_', ...slotArgs]);
+	const slot = slotArg ?? S('useRenderElement');
+
+	const renderProp = componentProps.render;
+	const outProps = useRenderElementProps(componentProps, params, subSlot(slot, 'rp'));
+
+	if (params.enabled === false) {
+		return null;
+	}
+
+	const state = params.state ?? (EMPTY_OBJECT as State);
+	return evaluateRenderProp(element, renderProp, outProps, state);
+}
+
+function useRenderElementProps<State extends Record<string, any>>(
+	componentProps: UseRenderElementComponentProps<State>,
+	params: UseRenderElementParameters<State>,
+	slot: symbol | undefined,
+): Record<string, any> {
+	const { className: classNameProp, style: styleProp, render: renderProp } = componentProps;
+	const {
+		state = EMPTY_OBJECT as State,
+		ref,
+		props,
+		stateAttributesMapping,
+		enabled = true,
+	} = params;
+
+	const className = enabled ? resolveClassName(classNameProp, state) : undefined;
+	const style = enabled ? resolveStyle(styleProp, state) : undefined;
+	const stateProps = enabled
+		? getStateAttributesProps(state, stateAttributesMapping)
+		: EMPTY_OBJECT;
+
+	const resolvedProps = enabled && props ? resolveRenderFunctionProps(props) : undefined;
+
+	// When enabled, always a FRESH mutable object (never the shared EMPTY_OBJECT — we set
+	// ref/className/style below). Matches Base UI's `?? {}`.
+	const outProps: Record<string, any> = enabled
+		? (mergeObjects(stateProps, resolvedProps) ?? {})
+		: EMPTY_OBJECT;
+
+	// Compose the intrinsic-prop ref, the render-element's own ref, and the forwarded
+	// ref into one. octane has no rules of hooks, so this is unconditional; the
+	// composed-refs hook is memoized under its own sub-slot.
+	const renderRef = getElementRef(renderProp);
+	const refs = Array.isArray(ref)
+		? [outProps.ref, renderRef, ...ref]
+		: [outProps.ref, renderRef, ref];
+	const composedRef = useComposedRefs(...refs, subSlot(slot, 'refs'));
+
+	// When disabled, `outProps` IS the shared EMPTY_OBJECT — assigning `.ref` (or
+	// className/style) would mutate it and leak (e.g. a later component reading default
+	// state via getStateAttributesProps would render `data-ref="<fn>"`). Return it
+	// untouched; the composed-refs hook still ran above for slot stability.
+	if (!enabled) {
+		return EMPTY_OBJECT;
+	}
+
+	outProps.ref = composedRef;
+
+	if (className !== undefined) {
+		outProps.className = mergeClassNames(outProps.className, className);
+	}
+	if (style !== undefined) {
+		outProps.style = mergeObjects(outProps.style, style);
+	}
+
+	return outProps;
+}
+
+function evaluateRenderProp<State>(
+	element: string | undefined,
+	render: RenderProp<State> | undefined,
+	props: Record<string, any>,
+	state: State,
+): any {
+	if (render) {
+		if (typeof render === 'function') {
+			return render(props, state);
+		}
+		// Element descriptor: merge the behavior props UNDER the element's own props
+		// (external wins), thread the composed ref, and clone.
+		const mergedProps = mergeProps(props, (render as any).props);
+		mergedProps.ref = props.ref;
+		return cloneElement(render, mergedProps);
+	}
+	if (element) {
+		return renderTag(element, props);
+	}
+	throw new Error('Base UI: render element or function are not defined.');
+}
+
+// A single (non-array) `props` goes through `mergeProps(undefined, props)` so its event
+// handlers are wrapped (preventable) like an array's would be via `mergePropsN`.
+function resolveRenderFunctionProps(
+	props: NonNullable<UseRenderElementParameters<any>['props']>,
+): Record<string, any> {
+	if (Array.isArray(props)) {
+		return mergePropsN(props);
+	}
+	return mergeProps(undefined, props);
+}
+
+function renderTag(tag: string, props: Record<string, any>): any {
+	if (tag === 'button') {
+		return createElement('button', { type: 'button', ...props });
+	}
+	if (tag === 'img') {
+		return createElement('img', { alt: '', ...props });
+	}
+	return createElement(tag, props);
+}

package/src/utils/useStableCallback.ts

@@ -0,0 +1,26 @@
+// Ported from .base-ui/packages/utils/src/useStableCallback.ts. Returns a stable
+// (identity-constant) trampoline that always calls the LATEST callback — safe to pass as
+// a memo/effect dependency without re-triggering. Base UI uses `useInsertionEffect` to
+// swap the callback; octane has no insertion effect, so (like @octanejs/floating-ui's
+// useEffectEvent) we refresh the ref synchronously each render. The dev "called during
+// render" guard is dropped (dev-only surface).
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useCallback, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export function useStableCallback<T extends (...args: any[]) => any>(...args: any[]): T {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useStableCallback');
+	const callback = user[0] as T | undefined;
+
+	const ref = useRef<T | undefined>(undefined, subSlot(slot, 'ref'));
+	ref.current = callback;
+
+	return useCallback(
+		((...a: any[]) => (ref.current == null ? undefined : ref.current(...a))) as T,
+		[],
+		subSlot(slot, 'cb'),
+	);
+}

package/src/utils/useTimeout.ts

@@ -0,0 +1,51 @@
+// Ported from .base-ui/packages/utils/src/useTimeout.ts. A `setTimeout` with automatic
+// cleanup on unmount. `useOnMount` → an octane effect with empty deps whose cleanup runs on
+// unmount.
+//
+// SLOT: `useTimeout` is a plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useEffect } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useRefWithInit } from './useRefWithInit';
+
+const EMPTY = 0;
+
+export class Timeout {
+	static create(): Timeout {
+		return new Timeout();
+	}
+
+	currentId: number = EMPTY;
+
+	/** Executes `fn` after `delay`, clearing any previously scheduled call. */
+	start(delay: number, fn: Function): void {
+		this.clear();
+		this.currentId = setTimeout(() => {
+			this.currentId = EMPTY;
+			fn();
+		}, delay) as unknown as number;
+	}
+
+	isStarted(): boolean {
+		return this.currentId !== EMPTY;
+	}
+
+	clear = (): void => {
+		if (this.currentId !== EMPTY) {
+			clearTimeout(this.currentId);
+			this.currentId = EMPTY;
+		}
+	};
+
+	disposeEffect = (): (() => void) => {
+		return this.clear;
+	};
+}
+
+export function useTimeout(...args: any[]): Timeout {
+	const [, slotArg] = splitSlot(['_', ...args]);
+	const slot = slotArg ?? S('useTimeout');
+	const timeout = useRefWithInit<Timeout>(Timeout.create, subSlot(slot, 'to')).current;
+	useEffect(timeout.disposeEffect, [], subSlot(slot, 'e:mount'));
+	return timeout;
+}

package/src/utils/useTransitionStatus.ts

@@ -0,0 +1,115 @@
+// Ported from .base-ui/packages/react/src/internals/useTransitionStatus.ts +
+// internals/stateAttributesMapping.ts (transitionStatusMapping). Drives the CSS enter/exit
+// animation status ('starting' | 'ending' | 'idle' | undefined) and the `mounted` flag.
+// `useIsoLayoutEffect` → octane `useLayoutEffect`; the render-phase `setState` calls are kept
+// as-is (octane supports bounded render-phase updates, like React).
+//
+// SLOT: `useTransitionStatus` is a plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { AnimationFrame } from './useAnimationFrame';
+import type { StateAttributesMapping } from './getStateAttributesProps';
+
+export type TransitionStatus = 'starting' | 'ending' | 'idle' | undefined;
+
+const STARTING_HOOK = { 'data-starting-style': '' };
+const ENDING_HOOK = { 'data-ending-style': '' };
+
+export const transitionStatusMapping: StateAttributesMapping<{
+	transitionStatus: TransitionStatus;
+}> = {
+	transitionStatus(value: TransitionStatus): Record<string, string> | null {
+		if (value === 'starting') {
+			return STARTING_HOOK;
+		}
+		if (value === 'ending') {
+			return ENDING_HOOK;
+		}
+		return null;
+	},
+};
+
+export function useTransitionStatus(...args: any[]): {
+	mounted: boolean;
+	setMounted: (next: boolean | ((prev: boolean) => boolean)) => void;
+	transitionStatus: TransitionStatus;
+} {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTransitionStatus');
+	const open = user[0] as boolean;
+	const enableIdleState = (user[1] as boolean | undefined) ?? false;
+	const deferEndingState = (user[2] as boolean | undefined) ?? false;
+
+	const [transitionStatus, setTransitionStatus] = useState<TransitionStatus>(
+		open && enableIdleState ? 'idle' : undefined,
+		subSlot(slot, 'ts'),
+	);
+	const [mounted, setMounted] = useState(open, subSlot(slot, 'mounted'));
+
+	if (open && !mounted) {
+		setMounted(true);
+		setTransitionStatus('starting');
+	}
+
+	if (!open && mounted && transitionStatus !== 'ending' && !deferEndingState) {
+		setTransitionStatus('ending');
+	}
+
+	if (!open && !mounted && transitionStatus === 'ending') {
+		setTransitionStatus(undefined);
+	}
+
+	useLayoutEffect(
+		() => {
+			if (!open && mounted && transitionStatus !== 'ending' && deferEndingState) {
+				const frame = AnimationFrame.request(() => {
+					setTransitionStatus('ending');
+				});
+				return () => {
+					AnimationFrame.cancel(frame);
+				};
+			}
+			return undefined;
+		},
+		[open, mounted, transitionStatus, deferEndingState],
+		subSlot(slot, 'e:defer'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (!open || enableIdleState) {
+				return undefined;
+			}
+			const frame = AnimationFrame.request(() => {
+				setTransitionStatus(undefined);
+			});
+			return () => {
+				AnimationFrame.cancel(frame);
+			};
+		},
+		[enableIdleState, open],
+		subSlot(slot, 'e:clear'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (!open || !enableIdleState) {
+				return undefined;
+			}
+			if (open && mounted && transitionStatus !== 'idle') {
+				setTransitionStatus('starting');
+			}
+			const frame = AnimationFrame.request(() => {
+				setTransitionStatus('idle');
+			});
+			return () => {
+				AnimationFrame.cancel(frame);
+			};
+		},
+		[enableIdleState, open, mounted, transitionStatus],
+		subSlot(slot, 'e:idle'),
+	);
+
+	return { mounted, setMounted, transitionStatus };
+}

package/src/utils/useValueAsRef.ts

@@ -0,0 +1,25 @@
+// Ported from .base-ui/packages/utils/src/useValueAsRef.ts — untracks a value into a ref
+// so an effect can read the latest without re-running on change. Base UI's `.next`/`.effect`
+// indirection collapses to setting `ref.current = value` in a layout effect that runs every
+// render — the same observable behavior, and the same shape as @octanejs/floating-ui's
+// `useLatestRef`.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export function useValueAsRef<T>(...args: any[]): { current: T } {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useValueAsRef');
+	const value = user[0] as T;
+	const ref = useRef(value, subSlot(slot, 'ref'));
+	useLayoutEffect(
+		() => {
+			ref.current = value;
+		},
+		undefined,
+		subSlot(slot, 'eff'),
+	);
+	return ref;
+}

package/src/utils/useValueChanged.ts

@@ -0,0 +1,37 @@
+// Ported from .base-ui/packages/react/src/internals/useValueChanged.ts. Calls `onChange`
+// (with the previous value) in a layout effect whenever `value` changes.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useLayoutEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useStableCallback } from './useStableCallback';
+
+export function useValueChanged<T>(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useValueChanged');
+	const value = user[0] as T;
+	const onChange = user[1] as (previousValue: T) => void;
+
+	const valueRef = useRef(value, subSlot(slot, 'ref'));
+	const onChangeCallback = useStableCallback(onChange, subSlot(slot, 'cb'));
+
+	useLayoutEffect(
+		() => {
+			if (valueRef.current === value) {
+				return;
+			}
+			onChangeCallback(valueRef.current);
+		},
+		[value, onChangeCallback],
+		subSlot(slot, 'e:change'),
+	);
+
+	useLayoutEffect(
+		() => {
+			valueRef.current = value;
+		},
+		[value],
+		subSlot(slot, 'e:set'),
+	);
+}

package/src/utils/valueToPercent.ts

@@ -0,0 +1,4 @@
+// Ported verbatim from .base-ui/packages/react/src/utils/valueToPercent.ts.
+export function valueToPercent(value: number, min: number, max: number): number {
+	return ((value - min) * 100) / (max - min);
+}

package/src/utils/visuallyHidden.ts

@@ -0,0 +1,24 @@
+// Ported from .base-ui/packages/utils/src/visuallyHidden.ts — the screen-reader-only
+// style object (a plain CSS-in-JS object; octane serializes it at the apply site).
+const visuallyHiddenBase: Record<string, any> = {
+	clipPath: 'inset(50%)',
+	overflow: 'hidden',
+	whiteSpace: 'nowrap',
+	border: 0,
+	padding: 0,
+	width: 1,
+	height: 1,
+	margin: -1,
+};
+
+export const visuallyHidden: Record<string, any> = {
+	...visuallyHiddenBase,
+	position: 'fixed',
+	top: 0,
+	left: 0,
+};
+
+export const visuallyHiddenInput: Record<string, any> = {
+	...visuallyHiddenBase,
+	position: 'absolute',
+};