@octanejs/base-ui 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @octanejs/base-ui
+
+[Base UI](https://base-ui.com) (`@base-ui/react`) ported to the
+[octane](https://github.com/octanejs/octane) renderer — headless, accessible, unstyled
+UI primitives.
+
+Alpha, in progress. Ported at full fidelity from the pinned `mui/base-ui` source
+(`v1.6.0`), proven by differential parity tests against the real
+`@base-ui/react`. See `docs/base-ui-migration-plan.md` for the phased plan
+and progress.
+
+## API
+
+Mirrors Base UI's deep-subpath imports:
+
+```ts
+import { Separator } from '@octanejs/base-ui/separator';
+import { useRender } from '@octanejs/base-ui/use-render';
+import { mergeProps } from '@octanejs/base-ui/merge-props';
+```
+
+Every component takes Base UI's universal composition props — `render` (a JSX element or
+`(props, state) => element`), `className` (string or `(state) => string`), and `style`
+(object or `(state) => object`) — routed through `useRenderElement`.
+
+## Intentional divergences from Base UI (React)
+
+- **Native events, not synthetic.** Handlers receive native DOM events (octane delegates
+  natively). `event.preventBaseUIHandler()` still works — the shim is attached to the
+  native event.
+- **ref-as-prop.** No `forwardRef`; `ref` is a normal prop (React-19 shape).
+- **`className` composition** follows octane's `normalizeClass` at the apply site; the
+  `render`-prop merge concatenates strings exactly like Base UI.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@octanejs/base-ui",
+  "version": "0.1.1",
+  "license": "MIT",
+  "type": "module",
+  "description": "Base UI (@base-ui/react) for the octane renderer — headless, accessible, unstyled UI primitives ported from base-ui.com at full fidelity.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/base-ui"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "dependencies": {
+    "aria-hidden": "^1.2.6",
+    "tabbable": "^6.5.0",
+    "@octanejs/floating-ui": "0.1.2",
+    "octane": "0.1.3"
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.6.0",
+    "@tsrx/react": "^0.2.33",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/avatar.ts

@@ -0,0 +1,308 @@
+// Ported from .base-ui/packages/react/src/avatar/ (v1.6.0): root/AvatarRoot,
+// root/AvatarRootContext, root/stateAttributesMapping, image/AvatarImage,
+// image/useImageLoadingStatus, fallback/AvatarFallback — plus its `index.parts` (the
+// `Avatar` namespace).
+//
+// Displays a profile image with a graceful fallback. `Avatar.Root` (`<span>`) tracks the
+// image load status via context; `Avatar.Image` (`<img>`) loads off-DOM and only mounts once
+// loaded (through the transition system); `Avatar.Fallback` (`<span>`) shows until then.
+// Base UI uses a PLAIN React context — ported as a plain octane createContext.
+import {
+	createContext,
+	createElement,
+	useContext,
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+} from 'octane';
+
+import { S, splitSlot, subSlot } from './internal';
+import { useRenderElement, type RenderProp } from './utils/useRenderElement';
+import type { StateAttributesMapping } from './utils/getStateAttributesProps';
+import { useStableCallback } from './utils/useStableCallback';
+import {
+	useTransitionStatus,
+	transitionStatusMapping,
+	type TransitionStatus,
+} from './utils/useTransitionStatus';
+import { useOpenChangeComplete } from './utils/useOpenChangeComplete';
+import { useTimeout } from './utils/useTimeout';
+
+export type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error';
+
+// The avatar's `imageLoadingStatus` state is NOT surfaced as a data-* attribute.
+const avatarStateAttributesMapping: StateAttributesMapping<{
+	imageLoadingStatus: ImageLoadingStatus;
+}> = {
+	imageLoadingStatus: () => null,
+};
+
+const imageStateAttributesMapping = {
+	...avatarStateAttributesMapping,
+	...transitionStatusMapping,
+};
+
+// --- Context -----------------------------------------------------------------
+
+export interface AvatarRootContextValue {
+	imageLoadingStatus: ImageLoadingStatus;
+	setImageLoadingStatus: (status: ImageLoadingStatus) => void;
+}
+
+const AvatarRootContext = createContext<AvatarRootContextValue | undefined>(undefined);
+
+function useAvatarRootContext(): AvatarRootContextValue {
+	const context = useContext(AvatarRootContext);
+	if (context === undefined) {
+		throw new Error(
+			'Base UI: AvatarRootContext is missing. Avatar parts must be placed within <Avatar.Root>.',
+		);
+	}
+	return context;
+}
+
+// --- Image load status hook --------------------------------------------------
+
+function useImageLoadingStatus(...args: any[]): ImageLoadingStatus {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useImageLoadingStatus');
+	const src = user[0] as string | undefined;
+	const options = (user[1] as any) ?? {};
+	const { referrerPolicy, crossOrigin, sizes, srcSet } = options;
+
+	const [loadingStatus, setLoadingStatus] = useState<ImageLoadingStatus>(
+		'idle',
+		subSlot(slot, 'ls'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (!src && !srcSet) {
+				setLoadingStatus('error');
+				return undefined;
+			}
+
+			let isMounted = true;
+			const image = new window.Image();
+
+			const updateStatus = (status: ImageLoadingStatus) => () => {
+				if (!isMounted) {
+					return;
+				}
+				setLoadingStatus(status);
+			};
+
+			setLoadingStatus('loading');
+			image.onload = updateStatus('loaded');
+			image.onerror = updateStatus('error');
+			if (referrerPolicy) {
+				image.referrerPolicy = referrerPolicy;
+			}
+			image.crossOrigin = crossOrigin ?? null;
+			if (sizes) {
+				image.sizes = sizes;
+			}
+			if (srcSet) {
+				image.srcset = srcSet;
+			}
+			if (src) {
+				image.src = src;
+			}
+
+			// Fast path for cached/decoded images.
+			if (image.complete) {
+				setLoadingStatus(image.naturalWidth > 0 ? 'loaded' : 'error');
+			}
+
+			return () => {
+				isMounted = false;
+			};
+		},
+		[src, srcSet, sizes, crossOrigin, referrerPolicy],
+		subSlot(slot, 'e:load'),
+	);
+
+	return loadingStatus;
+}
+
+// --- Root --------------------------------------------------------------------
+
+export interface AvatarRootState {
+	imageLoadingStatus: ImageLoadingStatus;
+}
+
+export interface AvatarRootProps {
+	render?: RenderProp<AvatarRootState>;
+	className?: string | ((state: AvatarRootState) => string | undefined);
+	style?: Record<string, any> | ((state: AvatarRootState) => Record<string, any> | undefined);
+	ref?: any;
+	[key: string]: any;
+}
+
+function AvatarRoot(props: AvatarRootProps): any {
+	const slot = S('AvatarRoot');
+	const { className, render, style, ref, ...elementProps } = props;
+
+	const [imageLoadingStatus, setImageLoadingStatus] = useState<ImageLoadingStatus>(
+		'idle',
+		subSlot(slot, 'ls'),
+	);
+
+	const state: AvatarRootState = { imageLoadingStatus };
+
+	const contextValue: AvatarRootContextValue = useMemo(
+		() => ({ imageLoadingStatus, setImageLoadingStatus }),
+		[imageLoadingStatus, setImageLoadingStatus],
+		subSlot(slot, 'ctx'),
+	);
+
+	const element = useRenderElement(
+		'span',
+		{ render, className, style },
+		{ state, ref, props: elementProps, stateAttributesMapping: avatarStateAttributesMapping },
+		subSlot(slot, 're'),
+	);
+
+	return createElement(AvatarRootContext.Provider, { value: contextValue, children: element });
+}
+
+// --- Image -------------------------------------------------------------------
+
+export interface AvatarImageState extends AvatarRootState {
+	transitionStatus: TransitionStatus;
+}
+
+function AvatarImage(props: any): any {
+	const slot = S('AvatarImage');
+	const {
+		className,
+		render,
+		onLoadingStatusChange: onLoadingStatusChangeProp,
+		style,
+		ref,
+		...elementProps
+	} = props;
+
+	const { setImageLoadingStatus } = useAvatarRootContext();
+	const imageLoadingStatus = useImageLoadingStatus(
+		elementProps.src,
+		elementProps,
+		subSlot(slot, 'ils'),
+	);
+
+	const isVisible = imageLoadingStatus === 'loaded';
+	const { mounted, transitionStatus, setMounted } = useTransitionStatus(
+		isVisible,
+		subSlot(slot, 'ts'),
+	);
+
+	const imageRef = useRef<HTMLImageElement | null>(null, subSlot(slot, 'imgRef'));
+
+	const handleLoadingStatusChange = useStableCallback(
+		(status: ImageLoadingStatus) => {
+			onLoadingStatusChangeProp?.(status);
+			setImageLoadingStatus(status);
+		},
+		subSlot(slot, 'hlsc'),
+	);
+
+	useLayoutEffect(
+		() => {
+			if (imageLoadingStatus !== 'idle') {
+				handleLoadingStatusChange(imageLoadingStatus);
+			}
+		},
+		[imageLoadingStatus, handleLoadingStatusChange],
+		subSlot(slot, 'e:status'),
+	);
+
+	useLayoutEffect(
+		() => () => setImageLoadingStatus('idle'),
+		[setImageLoadingStatus],
+		subSlot(slot, 'e:reset'),
+	);
+
+	useOpenChangeComplete(
+		{
+			open: isVisible,
+			ref: imageRef,
+			onComplete() {
+				if (!isVisible) {
+					setMounted(false);
+				}
+			},
+		},
+		subSlot(slot, 'occ'),
+	);
+
+	const state: AvatarImageState = { imageLoadingStatus, transitionStatus };
+
+	const element = useRenderElement(
+		'img',
+		{ render, className, style },
+		{
+			state,
+			ref: [ref, imageRef],
+			props: elementProps,
+			stateAttributesMapping: imageStateAttributesMapping,
+			enabled: mounted,
+		},
+		subSlot(slot, 're'),
+	);
+
+	if (!mounted) {
+		return null;
+	}
+
+	return element;
+}
+
+// --- Fallback ----------------------------------------------------------------
+
+function AvatarFallback(props: any): any {
+	const slot = S('AvatarFallback');
+	const { className, render, delay, style, ref, ...elementProps } = props;
+
+	const { imageLoadingStatus } = useAvatarRootContext();
+	const [delayPassed, setDelayPassed] = useState(delay === undefined, subSlot(slot, 'dp'));
+	const timeout = useTimeout(subSlot(slot, 'to'));
+
+	useEffect(
+		() => {
+			if (delay !== undefined) {
+				timeout.start(delay, () => setDelayPassed(true));
+			} else {
+				// Once shown without a delay, keep it visible.
+				setDelayPassed(true);
+			}
+			return timeout.clear;
+		},
+		[timeout, delay],
+		subSlot(slot, 'e:delay'),
+	);
+
+	const state: AvatarRootState = { imageLoadingStatus };
+
+	return useRenderElement(
+		'span',
+		{ render, className, style },
+		{
+			state,
+			ref,
+			props: elementProps,
+			stateAttributesMapping: avatarStateAttributesMapping,
+			enabled: imageLoadingStatus !== 'loaded' && (delay === undefined || delayPassed),
+		},
+		subSlot(slot, 're'),
+	);
+}
+
+// --- Namespace (mirrors `export * as Avatar`) --------------------------------
+
+export const Avatar = {
+	Root: AvatarRoot,
+	Image: AvatarImage,
+	Fallback: AvatarFallback,
+};

package/src/checkbox-group.ts

@@ -0,0 +1,183 @@
+// Ported from .base-ui/packages/react/src/checkbox-group/CheckboxGroup.tsx (v1.6.0). Provides a
+// shared value array to a set of <Checkbox.Root>s (with an optional select-all parent checkbox
+// via `allValues` + `useCheckboxGroupParent`). Renders a `<div role="group">`. octane:
+// forwardRef → ref-as-prop.
+import { createElement, useCallback, useMemo, useRef } from 'octane';
+
+import { S, subSlot } from './internal';
+import { useRenderElement, type RenderProp } from './utils/useRenderElement';
+import { useBaseUiId } from './utils/useBaseUiId';
+import { useControlled } from './utils/useControlled';
+import { useStableCallback } from './utils/useStableCallback';
+import { useValueChanged } from './utils/useValueChanged';
+import { areArraysEqual } from './utils/areArraysEqual';
+import { useCheckboxGroupParent } from './utils/useCheckboxGroupParent';
+import { CheckboxGroupContext, type CheckboxGroupContextValue } from './utils/CheckboxGroupContext';
+import { fieldValidityMapping, type FieldRootState } from './utils/field/constants';
+import { useFieldRootContext } from './utils/field/FieldRootContext';
+import { useFormContext } from './utils/field/FormContext';
+import { useLabelableContext } from './utils/field/LabelableContext';
+import { useRegisterFieldControl } from './utils/field/useRegisterFieldControl';
+import { PARENT_CHECKBOX } from './checkbox';
+
+const EMPTY_ARRAY: string[] = [];
+
+export interface CheckboxGroupState extends FieldRootState {
+	disabled: boolean;
+}
+
+export interface CheckboxGroupProps {
+	value?: string[];
+	defaultValue?: string[];
+	onValueChange?: (value: string[], eventDetails: any) => void;
+	allValues?: string[];
+	disabled?: boolean;
+	id?: string;
+	render?: RenderProp<CheckboxGroupState>;
+	className?: string | ((state: CheckboxGroupState) => string | undefined);
+	style?: Record<string, any> | ((state: CheckboxGroupState) => Record<string, any> | undefined);
+	ref?: any;
+	[key: string]: any;
+}
+
+function CheckboxGroup(props: CheckboxGroupProps): any {
+	const slot = S('CheckboxGroup');
+	const {
+		allValues,
+		className,
+		defaultValue: defaultValueProp,
+		disabled: disabledProp = false,
+		id: idProp,
+		onValueChange,
+		render,
+		value: externalValue,
+		style,
+		ref,
+		...elementProps
+	} = props;
+
+	const {
+		disabled: fieldDisabled,
+		name: fieldName,
+		state: fieldState,
+		validation,
+		setFilled,
+		setDirty,
+		validityData,
+	} = useFieldRootContext();
+	const { labelId, getDescriptionProps } = useLabelableContext();
+	const { clearErrors } = useFormContext();
+
+	const disabled = fieldDisabled || disabledProp;
+
+	const defaultValue = useMemo<string[] | undefined>(
+		() => {
+			if (externalValue === undefined) {
+				return defaultValueProp ?? [];
+			}
+			return undefined;
+		},
+		[externalValue, defaultValueProp],
+		subSlot(slot, 'defaultValue'),
+	);
+
+	const [value, setValueUnwrapped] = useControlled<string[]>(
+		{ controlled: externalValue, default: defaultValue, name: 'CheckboxGroup', state: 'value' },
+		subSlot(slot, 'value'),
+	);
+
+	const setValue = useStableCallback(
+		(v: string[], eventDetails: any) => {
+			onValueChange?.(v, eventDetails);
+			if (eventDetails.isCanceled) {
+				return;
+			}
+			setValueUnwrapped(v);
+		},
+		subSlot(slot, 'setValue'),
+	);
+
+	const parent = useCheckboxGroupParent(
+		{ allValues, value, onValueChange: setValue },
+		subSlot(slot, 'parent'),
+	);
+
+	const id = useBaseUiId(idProp, subSlot(slot, 'id'));
+
+	const controlRef = useRef<HTMLButtonElement | null>(null, subSlot(slot, 'controlRef'));
+
+	const registerControlRef = useCallback(
+		(element: HTMLButtonElement | null) => {
+			if (controlRef.current == null && element != null && !element.hasAttribute(PARENT_CHECKBOX)) {
+				controlRef.current = element;
+			}
+		},
+		[],
+		subSlot(slot, 'registerControl'),
+	);
+
+	useRegisterFieldControl(
+		controlRef,
+		id,
+		value,
+		undefined,
+		!!fieldName && !disabled,
+		fieldName,
+		subSlot(slot, 'register'),
+	);
+
+	const resolvedValue = value ?? EMPTY_ARRAY;
+
+	useValueChanged(
+		resolvedValue,
+		() => {
+			if (fieldName) {
+				clearErrors(fieldName);
+			}
+			const initialValue = Array.isArray(validityData.initialValue)
+				? (validityData.initialValue as readonly string[])
+				: EMPTY_ARRAY;
+			setFilled(resolvedValue.length > 0);
+			setDirty(!areArraysEqual(resolvedValue, initialValue));
+			validation.change(resolvedValue);
+		},
+		subSlot(slot, 'valueChanged'),
+	);
+
+	const state: CheckboxGroupState = { ...fieldState, disabled };
+
+	const contextValue: CheckboxGroupContextValue = useMemo(
+		() => ({
+			allValues,
+			value,
+			defaultValue,
+			setValue,
+			parent,
+			disabled,
+			validation,
+			registerControlRef,
+		}),
+		[allValues, value, defaultValue, setValue, parent, disabled, validation, registerControlRef],
+		subSlot(slot, 'ctx'),
+	);
+
+	const element = useRenderElement(
+		'div',
+		{ render, className, style },
+		{
+			state,
+			ref,
+			props: [
+				{ id: idProp, role: 'group', 'aria-labelledby': labelId },
+				elementProps,
+				getDescriptionProps,
+			],
+			stateAttributesMapping: fieldValidityMapping,
+		},
+		subSlot(slot, 're'),
+	);
+
+	return createElement(CheckboxGroupContext.Provider, { value: contextValue, children: element });
+}
+
+export { CheckboxGroup };