@octanejs/base-ui 0.1.49 → 0.1.51

package/src/form/Form.tsrx

@@ -0,0 +1,248 @@
+'use client';
+import * as React from 'octane';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import {
+	createGenericEventDetails,
+	type BaseUIGenericEventDetails,
+} from '../internals/createBaseUIEventDetails';
+import { REASONS } from '../internals/reasons';
+import type { BaseUIComponentProps } from '../internals/types';
+import { FormContext } from '../internals/form-context/FormContext';
+import { useRenderElement } from '../internals/useRenderElement.tsrx';
+import { useValueChanged } from '../internals/useValueChanged';
+
+/**
+ * A native form element with consolidated error handling.
+ * Renders a `<form>` element.
+ *
+ * Documentation: [Base UI Form](https://base-ui.com/react/components/form)
+ */
+export const Form = function Form<FormValues extends Record<string, any> = Record<string, any>>(
+	componentPropsWithRef: React.PropsWithoutRef<Form.Props<FormValues>> & {
+		ref?: React.Ref<HTMLFormElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		render,
+		className,
+		validationMode = 'onSubmit',
+		errors: externalErrors,
+		onSubmit,
+		onFormSubmit,
+		actionsRef,
+		style,
+		...elementProps
+	} = componentProps;
+
+	const formRef = React.useRef<FormContext['formRef']['current']>({
+		fields: new Map(),
+	});
+	const elementRef = React.useRef<HTMLFormElement | null>(null);
+	const submittedRef = React.useRef(false);
+	const submitCountRef = React.useRef(0);
+
+	const focusFirstInvalid = useStableCallback(() => {
+		// A field can be invalid without a focusable control (for example a checkbox group whose
+		// custom validation failed while every checkbox is unmounted, disabled, or reassociated).
+		// Keep submission blocked, but move focus to the first invalid field that has a usable control.
+		// Registration order can diverge from DOM order (keyed fields reordered without
+		// remounting, portals), so pick the first control by document position. For controls
+		// in disconnected trees (e.g. separate shadow roots), where document position is
+		// implementation-specific, keep registration order.
+		let hasInvalid = false;
+		let firstControl: HTMLElement | null = null;
+		for (const field of formRef.current.fields.values()) {
+			if (field.validityData.state.valid !== false) {
+				continue;
+			}
+			hasInvalid = true;
+			const control = field.controlRef.current;
+			if (control && (!firstControl || comesBeforeInSameTree(control, firstControl))) {
+				firstControl = control;
+			}
+		}
+		if (firstControl) {
+			firstControl.focus();
+			if (firstControl.tagName === 'INPUT') {
+				(firstControl as HTMLInputElement).select();
+			}
+			return true;
+		}
+		return hasInvalid;
+	});
+
+	const [errors, setErrors] = React.useState(externalErrors);
+
+	useValueChanged(externalErrors, () => {
+		setErrors(externalErrors);
+	});
+
+	React.useEffect(() => {
+		if (!submittedRef.current) {
+			return;
+		}
+
+		submittedRef.current = false;
+		focusFirstInvalid();
+	}, [errors, focusFirstInvalid]);
+
+	React.useImperativeHandle(
+		actionsRef,
+		() => ({
+			validate(fieldName?: string) {
+				if (fieldName) {
+					Array.from(formRef.current.fields.values())
+						.find((field) => field.name === fieldName)
+						?.validate();
+				} else {
+					formRef.current.fields.forEach((field) => {
+						field.validate();
+					});
+				}
+			},
+		}),
+		[],
+	);
+
+	const element = useRenderElement('form', componentProps, {
+		ref: [forwardedRef, elementRef],
+		props: [
+			{
+				noValidate: true,
+				onSubmit(event) {
+					submitCountRef.current += 1;
+
+					// Async validation isn't supported to stop the submit event.
+					formRef.current.fields.forEach((field) => {
+						field.validate();
+					});
+
+					if (focusFirstInvalid()) {
+						event.preventDefault();
+						return;
+					}
+
+					submittedRef.current = true;
+					onSubmit?.(event as any);
+
+					if (onFormSubmit) {
+						event.preventDefault();
+
+						const formValues = {} as FormValues;
+						formRef.current.fields.forEach((field) => {
+							if (field.name) {
+								(formValues as Record<string, any>)[field.name] = field.getValue();
+							}
+						});
+
+						onFormSubmit(formValues, createGenericEventDetails(REASONS.none, event));
+					}
+				},
+			},
+			elementProps,
+		],
+	});
+
+	const clearErrors = useStableCallback((name: string | undefined) => {
+		if (!name) {
+			return;
+		}
+		setErrors((previousErrors) => {
+			if (!previousErrors || !Object.hasOwn(previousErrors, name)) {
+				return previousErrors;
+			}
+			const nextErrors = { ...previousErrors };
+			delete nextErrors[name];
+			return nextErrors;
+		});
+	});
+
+	const contextValue: FormContext = React.useMemo(
+		() => ({
+			elementRef,
+			formRef,
+			validationMode,
+			errors: errors ?? EMPTY_OBJECT,
+			clearErrors,
+			submitCountRef,
+		}),
+		[formRef, validationMode, errors, clearErrors],
+	);
+
+	return <FormContext.Provider value={contextValue}>{element}</FormContext.Provider>;
+};
+
+export type FormSubmitEventReason = typeof REASONS.none;
+export type FormSubmitEventDetails = BaseUIGenericEventDetails<Form.SubmitEventReason>;
+
+export type FormValidationMode = 'onSubmit' | 'onBlur' | 'onChange';
+
+export interface FormActions {
+	validate: (fieldName?: string | undefined) => void;
+}
+
+export interface FormState {}
+
+export interface FormProps<
+	FormValues extends Record<string, any> = Record<string, any>,
+> extends BaseUIComponentProps<'form', FormState, React.ComponentPropsWithRef<'form'>> {
+	/**
+	 * Determines when the form should be validated.
+	 * The `validationMode` prop on `<Field.Root>` takes precedence over this.
+	 *
+	 * - `onSubmit` (default): validates the field when the form is submitted, afterwards fields will re-validate on change.
+	 * - `onBlur`: validates a field when it loses focus.
+	 * - `onChange`: validates the field on every change to its value.
+	 *
+	 * @default 'onSubmit'
+	 */
+	validationMode?: FormValidationMode | undefined;
+	/**
+	 * Validation errors returned externally, typically after submission by a server or a form action.
+	 * This should be an object where keys correspond to the `name` attribute on `<Field.Root>`,
+	 * and values correspond to error(s) related to that field.
+	 */
+	errors?: FormContext['errors'] | undefined;
+	/**
+	 * Event handler called when the form is submitted.
+	 * `preventDefault()` is called on the native submit event when used.
+	 */
+	onFormSubmit?:
+		((formValues: FormValues, eventDetails: Form.SubmitEventDetails) => void) | undefined;
+	/**
+	 * A ref to imperative actions.
+	 * - `validate`: Validates all fields when called. Optionally pass a field name to validate a single field.
+	 * @example
+	 * ```tsx
+	 * // validate all fields
+	 * actionsRef.current?.validate();
+	 *
+	 * // validate one field
+	 * actionsRef.current?.validate('email');
+	 * ```
+	 */
+	actionsRef?: React.RefObject<Form.Actions | null> | undefined;
+}
+
+export namespace Form {
+	export type Props<FormValues extends Record<string, any> = Record<string, any>> =
+		FormProps<FormValues>;
+	export type State = FormState;
+	export type Actions = FormActions;
+	export type ValidationMode = FormValidationMode;
+	export type SubmitEventReason = FormSubmitEventReason;
+	export type SubmitEventDetails = FormSubmitEventDetails;
+
+	export type Values<FormValues extends Record<string, any> = Record<string, any>> = FormValues;
+}
+
+/* eslint-disable no-bitwise */
+function comesBeforeInSameTree(element: Node, reference: Node) {
+	const position = element.compareDocumentPosition(reference);
+	return (
+		(position & Node.DOCUMENT_POSITION_DISCONNECTED) === 0 &&
+		(position & Node.DOCUMENT_POSITION_FOLLOWING) !== 0
+	);
+}

package/src/form/index.ts

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

package/src/global.d.ts

@@ -0,0 +1,9 @@
+declare global {
+	/**
+	 * When `true`, disables animation-related code, even if supported by the runtime environment.
+	 */
+	// eslint-disable-next-line vars-on-top
+	var BASE_UI_ANIMATIONS_DISABLED: boolean;
+}
+
+export type {};

package/src/index.ts

@@ -1,40 +1,46 @@
-// @octanejs/base-ui — Base UI (@base-ui/react) ported to the octane
-// renderer. Public API mirrors Base UI: deep-subpath imports
-// (`@octanejs/base-ui/separator`, `@octanejs/base-ui/use-render`, …). This barrel
-// re-exports the public surface for convenience as components land.
-export { Separator } from './separator';
-export { Accordion } from './accordion';
-export { AlertDialog } from './alert-dialog';
-export { Avatar } from './avatar';
-export { Button } from './button';
-export { CSPProvider } from './csp-provider';
-export { DirectionProvider, useDirection } from './direction-provider';
-export type { TextDirection } from './direction-provider';
+export * from './accordion';
+export * from './alert-dialog';
+export * from './autocomplete';
+export * from './avatar';
+export * from './button';
+export * from './checkbox';
+export * from './checkbox-group';
+export * from './collapsible';
+export * from './combobox';
+export * from './context-menu';
+export * from './csp-provider';
+export * from './dialog';
+export * from './direction-provider';
+export * from './drawer';
+export * from './field';
+export * from './fieldset';
+export * from './form';
+export * from './input';
+export * from './menu';
+export * from './menubar';
+export * from './merge-props';
+export * from './meter';
+export * from './navigation-menu';
+export * from './number-field';
+export * from './otp-field';
+export * from './popover';
+export * from './preview-card';
+export * from './progress';
+export * from './radio';
+export * from './radio-group';
+export * from './scroll-area';
+export * from './select';
+export * from './separator';
+export * from './slider';
+export * from './switch';
+export * from './tabs';
+export * from './toast';
+export * from './toggle';
+export * from './toggle-group';
+export * from './toolbar';
+export * from './tooltip';
+export * from './use-render';
+// Preserve the original Octane binding's root hook export.
 export { useMediaQuery } from './unstable-use-media-query';
-export { Checkbox } from './checkbox';
-export { Collapsible } from './collapsible';
-export { ContextMenu } from './context-menu';
-export { CheckboxGroup } from './checkbox-group';
-export { Dialog } from './dialog';
-export { Field } from './field';
-export { Fieldset } from './fieldset';
-export { Form } from './form';
-export { Input } from './input';
-export { Menu } from './menu';
-export { Menubar } from './menubar';
-export { Meter } from './meter';
-export { NumberField } from './number-field';
-export { Progress } from './progress';
-export { Radio } from './radio';
-export { RadioGroup } from './radio-group';
-export { Popover } from './popover';
-export { PreviewCard } from './preview-card';
-export { Tooltip } from './tooltip';
-export { Slider } from './slider';
-export { Switch } from './switch';
-export { Toast } from './toast';
-export { Toggle } from './toggle';
-export { ToggleGroup } from './toggle-group';
-export { useRender } from './use-render';
-export { mergeProps, mergePropsN, mergeClassNames } from './merge-props';
-// OCTANE DIVERGENCE[unported-internal-hover][differential:base-ui-tooltip-open]
+
+export type * from './types';

package/src/input/Input.tsrx

@@ -0,0 +1,44 @@
+'use client';
+import * as React from 'octane';
+import type { BaseUIComponentProps } from '../internals/types';
+import { Field, type FieldControlState } from '../field';
+
+/**
+ * A native input element that automatically works with [Field](https://base-ui.com/react/components/field).
+ * Renders an `<input>` element.
+ *
+ * Documentation: [Base UI Input](https://base-ui.com/react/components/input)
+ */
+export const Input = function Input(
+	propsWithRef: React.PropsWithoutRef<Input.Props> & { ref?: React.Ref<HTMLElement> },
+) {
+	const { ref: forwardedRef = null, ...props } = propsWithRef;
+	return <Field.Control ref={forwardedRef} {...props} />;
+};
+
+export interface InputProps extends BaseUIComponentProps<'input', InputState> {
+	/**
+	 * Callback fired when the `value` changes. Use when controlled.
+	 */
+	onValueChange?: ((value: string, eventDetails: Input.ChangeEventDetails) => void) | undefined;
+	/**
+	 * The default value of the input. Use when uncontrolled.
+	 */
+	defaultValue?: Field.Control.Props['defaultValue'] | undefined;
+	/**
+	 * The value of the input. Use when controlled.
+	 */
+	value?: React.ComponentProps<'input'>['value'] | undefined;
+}
+
+export interface InputState extends FieldControlState {}
+
+export type InputChangeEventReason = Field.Control.ChangeEventReason;
+export type InputChangeEventDetails = Field.Control.ChangeEventDetails;
+
+export namespace Input {
+	export type Props = InputProps;
+	export type State = InputState;
+	export type ChangeEventReason = InputChangeEventReason;
+	export type ChangeEventDetails = InputChangeEventDetails;
+}

package/src/input/InputDataAttributes.ts

@@ -0,0 +1,28 @@
+/**
+ * Present when the input is disabled.
+ */
+export const disabled = 'data-disabled';
+/**
+ * Present when the input is in a valid state (when wrapped in Field.Root).
+ */
+export const valid = 'data-valid';
+/**
+ * Present when the input is in an invalid state (when wrapped in Field.Root).
+ */
+export const invalid = 'data-invalid';
+/**
+ * Present when the input has been touched (when wrapped in Field.Root).
+ */
+export const touched = 'data-touched';
+/**
+ * Present when the input's value has changed (when wrapped in Field.Root).
+ */
+export const dirty = 'data-dirty';
+/**
+ * Present when the input is filled (when wrapped in Field.Root).
+ */
+export const filled = 'data-filled';
+/**
+ * Present when the input is focused (when wrapped in Field.Root).
+ */
+export const focused = 'data-focused';

package/src/input/index.ts

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

package/src/internals/PrehydrationScript.tsrx

@@ -0,0 +1,59 @@
+'use client';
+import * as React from 'octane';
+import { useIsHydrating } from '../utils/useIsHydrating';
+import { useCSPContext } from './csp-context/CSPContext.tsrx';
+
+/**
+ * Renders an inline script that runs before React hydrates, used by components that need
+ * to position server-rendered content ahead of hydration (e.g. `Tabs.Indicator`,
+ * `Slider.Thumb`).
+ *
+ * The `script` source is imported by the caller through the package's `#prehydration/*`
+ * subpath import, whose `browser` condition resolves to a stub module exporting an empty
+ * string — so the script body is excluded from client bundles. It only ever executes from
+ * server-rendered HTML.
+ *
+ * Render this only when the script should be emitted (i.e. gate `renderBeforeHydration`
+ * and any structural conditions at the call site). The element is still rendered (with
+ * empty content) on the client during the hydration pass so the React tree matches the
+ * server markup; `suppressHydrationWarning` bridges the content difference and React keeps
+ * the already-executed server script. Once `isHydrating` flips to `false` the element
+ * unmounts.
+ *
+ * The component must stay in client bundles: returning `null` on the client (e.g. by
+ * stubbing the whole component) would drop an element the server emitted and trigger a
+ * recoverable hydration error (React #418) in consumers' apps. Only the script body is
+ * excluded from client bundles, via the `#prehydration/*` `browser` condition.
+ *
+ * When adding a new consumer, register a matching `#prehydration/*` entry (with `browser`
+ * and `default` conditions) in `packages/react/package.json` `imports`; the `browser`
+ * condition reuses the shared `internals/prehydrationScript.stub.ts`.
+ */
+export function PrehydrationScript(props: PrehydrationScript.Props) {
+	const { script } = props;
+	const { nonce } = useCSPContext();
+	const isHydrating = useIsHydrating();
+
+	if (!isHydrating) {
+		return null;
+	}
+
+	return (
+		<script
+			nonce={nonce}
+			// eslint-disable-next-line react/no-danger
+			dangerouslySetInnerHTML={{ __html: script }}
+			suppressHydrationWarning
+		/>
+	);
+}
+
+export namespace PrehydrationScript {
+	export interface Props {
+		/**
+		 * The script source, imported through the `#prehydration/*` subpath import.
+		 * Empty in client bundles.
+		 */
+		script: string;
+	}
+}

package/src/internals/RequestQueue.ts

@@ -0,0 +1,126 @@
+export type RequestStatus = 'queued' | 'pending' | 'unknown';
+
+export interface RequestQueueOptions<TKey> {
+	/**
+	 * The function to call when a queued key is ready to be fetched.
+	 */
+	fetchFn: (key: TKey) => Promise<void>;
+	/**
+	 * The maximum number of concurrent requests.
+	 * @default Infinity
+	 */
+	maxConcurrentRequests?: number | undefined;
+	/**
+	 * Serialize a key to a string for use as a map key.
+	 * Required for complex key types (e.g., objects).
+	 * @default String(key)
+	 */
+	getKeyId?: ((key: TKey) => string) | undefined;
+}
+
+/**
+ * Manages concurrent fetching with a queue system.
+ * Tracks request lifecycle through queued → pending states
+ * and limits concurrency to prevent overwhelming the server.
+ */
+export class RequestQueue<TKey> {
+	protected pendingRequests = new Map<string, TKey>();
+
+	protected queuedRequests = new Map<string, TKey>();
+
+	protected fetchFn: (key: TKey) => Promise<void>;
+
+	protected maxConcurrentRequests: number;
+
+	protected getKeyId: (key: TKey) => string;
+
+	constructor(options: RequestQueueOptions<TKey>) {
+		this.fetchFn = options.fetchFn;
+		this.maxConcurrentRequests = options.maxConcurrentRequests ?? Infinity;
+		this.getKeyId = options.getKeyId ?? String;
+	}
+
+	/**
+	 * Returns the next `count` entries to process from the queue.
+	 * Default is FIFO (oldest first). Subclasses can override for different ordering.
+	 */
+	protected pickEntries(count: number): [string, TKey][] {
+		const result: [string, TKey][] = [];
+		const iterator = this.queuedRequests.entries();
+		for (let i = 0; i < count; i += 1) {
+			const { value } = iterator.next() as IteratorYieldResult<[string, TKey]>;
+			result.push(value);
+		}
+		return result;
+	}
+
+	protected processQueue = async () => {
+		if (this.queuedRequests.size === 0 || this.pendingRequests.size >= this.maxConcurrentRequests) {
+			return;
+		}
+
+		const loopLength = Math.min(
+			this.maxConcurrentRequests - this.pendingRequests.size,
+			this.queuedRequests.size,
+		);
+		if (loopLength === 0) {
+			return;
+		}
+
+		const fetchPromises: Promise<void>[] = [];
+
+		for (const [keyId, key] of this.pickEntries(loopLength)) {
+			this.queuedRequests.delete(keyId);
+			this.pendingRequests.set(keyId, key);
+
+			fetchPromises.push(
+				this.fetchFn(key).catch(() => {
+					this.pendingRequests.delete(keyId);
+				}),
+			);
+		}
+
+		await Promise.all(fetchPromises);
+		if (this.queuedRequests.size > 0) {
+			await this.processQueue();
+		}
+	};
+
+	public queue = async (keys: TKey[]) => {
+		for (const key of keys) {
+			const keyId = this.getKeyId(key);
+			if (!this.pendingRequests.has(keyId)) {
+				this.queuedRequests.set(keyId, key);
+			}
+		}
+		await this.processQueue();
+	};
+
+	public setRequestSettled = async (key: TKey) => {
+		const keyId = this.getKeyId(key);
+		this.pendingRequests.delete(keyId);
+		await this.processQueue();
+	};
+
+	public clear = () => {
+		this.queuedRequests.clear();
+		this.pendingRequests.clear();
+	};
+
+	public clearPendingRequest = async (key: TKey) => {
+		const keyId = this.getKeyId(key);
+		this.pendingRequests.delete(keyId);
+		await this.processQueue();
+	};
+
+	public getRequestStatus = (key: TKey): RequestStatus => {
+		const keyId = this.getKeyId(key);
+		if (this.pendingRequests.has(keyId)) {
+			return 'pending';
+		}
+		if (this.queuedRequests.has(keyId)) {
+			return 'queued';
+		}
+		return 'unknown';
+	};
+}

package/src/internals/TimeoutManager.ts

@@ -0,0 +1,29 @@
+/**
+ * A utility class to manage multiple timeouts.
+ */
+export class TimeoutManager {
+	private ids: Map<string, number> = new Map();
+
+	start = (key: string, delay: number, fn: () => void) => {
+		this.clear(key);
+		const id = setTimeout(() => {
+			this.ids.delete(key);
+			fn();
+		}, delay) as unknown as number; /* Node.js types are enabled in development */
+
+		this.ids.set(key, id);
+	};
+
+	clear = (key: string) => {
+		const id = this.ids.get(key);
+		if (id != null) {
+			clearTimeout(id);
+			this.ids.delete(key);
+		}
+	};
+
+	clearAll = () => {
+		this.ids.forEach(clearTimeout);
+		this.ids.clear();
+	};
+}

package/src/internals/TransitionStatusDataAttributes.ts

@@ -0,0 +1,9 @@
+/**
+ * Present when the component begins animating in.
+ */
+export const startingStyle = 'data-starting-style';
+
+/**
+ * Present when the component is animating out.
+ */
+export const endingStyle = 'data-ending-style';