@octanejs/base-ui 0.1.49 → 0.1.51

package/src/internals/labelable-provider/LabelableProvider.tsrx

@@ -0,0 +1,120 @@
+'use client';
+import * as React from 'octane';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useRefWithInit } from '@octanejs/base-ui-utils/useRefWithInit';
+import type { HTMLProps } from '../types';
+import { useBaseUiId } from '../useBaseUiId';
+import { LabelableContext, useLabelableContext } from './LabelableContext';
+
+export const LabelableProvider: React.FC<LabelableProvider.Props> = function LabelableProvider(
+	props,
+) {
+	const defaultId = useBaseUiId();
+
+	const [controlIdState, setControlIdState] = React.useState<string | null | undefined>(defaultId);
+	const [labelId, setLabelId] = React.useState<string | undefined>();
+	const [messageIds, setMessageIds] = React.useState<string[]>([]);
+
+	// `undefined` only survives until the React 17 fallback id is assigned. Do not use `??`:
+	// `null` deliberately suppresses `htmlFor`.
+	const controlId = controlIdState === undefined ? defaultId : controlIdState;
+
+	const registrationsRef = useRefWithInit(() => new Map<symbol, string | null>());
+
+	const { messageIds: parentMessageIds } = useLabelableContext();
+
+	const registerControlId = useStableCallback(
+		(source: symbol, nextId: string | null | undefined) => {
+			const registrations = registrationsRef.current;
+
+			if (nextId === undefined) {
+				registrations.delete(source);
+			} else {
+				registrations.set(source, nextId);
+			}
+
+			setControlIdState((prev) => {
+				if (registrations.size === 0) {
+					// A hidden subtree (React Activity, a re-suspending Suspense) destroys effects but keeps
+					// its DOM, so preserve its selected control.
+					return prev;
+				}
+
+				let nextControlId: string | null | undefined;
+
+				for (const id of registrations.values()) {
+					// Keep the current selection while it is still registered, so rapid unmount/remount
+					// cycles don't churn it.
+					if (id === prev) {
+						return prev;
+					}
+
+					if (nextControlId === undefined) {
+						nextControlId = id;
+					}
+				}
+
+				return nextControlId;
+			});
+		},
+	);
+
+	const resetControlId = useStableCallback(() => {
+		if (registrationsRef.current.size === 0) {
+			setControlIdState(defaultId);
+		}
+	});
+
+	const getDescriptionProps = React.useCallback(
+		<Props extends { 'aria-describedby'?: string }>(externalProps: Props) => {
+			const ids = externalProps['aria-describedby']
+				? externalProps['aria-describedby'].split(' ')
+				: [];
+			ids.push(...parentMessageIds, ...messageIds);
+
+			return {
+				...externalProps,
+				'aria-describedby': Array.from(new Set(ids)).join(' ') || undefined,
+			};
+		},
+		[parentMessageIds, messageIds],
+	);
+
+	const contextValue: LabelableContext = React.useMemo(
+		() => ({
+			controlId,
+			registerControlId,
+			resetControlId,
+			labelId,
+			setLabelId,
+			messageIds,
+			setMessageIds,
+			getDescriptionProps,
+		}),
+		[
+			controlId,
+			registerControlId,
+			resetControlId,
+			labelId,
+			setLabelId,
+			messageIds,
+			setMessageIds,
+			getDescriptionProps,
+		],
+	);
+
+	return (
+		<LabelableContext.Provider value={contextValue}>{props.children}</LabelableContext.Provider>
+	);
+};
+
+export interface LabelableProviderState {}
+
+export interface LabelableProviderProps {
+	children?: React.OctaneNode;
+}
+
+export namespace LabelableProvider {
+	export type State = LabelableProviderState;
+	export type Props = LabelableProviderProps;
+}

package/src/internals/labelable-provider/index.ts

@@ -0,0 +1,6 @@
+export * from './LabelableProvider.tsrx';
+export { useAriaLabelledBy } from './useAriaLabelledBy';
+export { useLabelableContext } from './LabelableContext';
+export { useLabelableId } from './useLabelableId';
+export { useLabel } from './useLabel';
+export type { UseLabelParameters, UseLabelReturnValue } from './useLabel';

package/src/internals/labelable-provider/useAriaLabelledBy.ts

@@ -0,0 +1,73 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useBaseUiId } from '../useBaseUiId';
+
+export function useAriaLabelledBy(
+	explicitAriaLabelledBy: string | undefined,
+	labelId: string | undefined,
+	labelSourceRef: React.RefObject<LabelSource | null>,
+	enableFallback = true,
+	labelSourceId?: string,
+) {
+	const [fallbackAriaLabelledBy, setFallbackAriaLabelledBy] = React.useState<string | undefined>();
+
+	const generatedLabelId = useBaseUiId(labelSourceId ? `${labelSourceId}-label` : undefined);
+	const ariaLabelledBy = explicitAriaLabelledBy ?? labelId ?? fallbackAriaLabelledBy;
+
+	// Fallback for <span> controls labelled by wrapping/sibling native <label>.
+	// Run after every commit so DOM association changes (e.g. label mount/unmount)
+	// are reflected even when props/state deps are unchanged.
+	// eslint-disable-next-line react-hooks/exhaustive-deps
+	useIsoLayoutEffect(() => {
+		const nextAriaLabelledBy =
+			explicitAriaLabelledBy || labelId || !enableFallback
+				? undefined
+				: getAriaLabelledBy(labelSourceRef.current, generatedLabelId);
+
+		if (fallbackAriaLabelledBy !== nextAriaLabelledBy) {
+			setFallbackAriaLabelledBy(nextAriaLabelledBy);
+		}
+	});
+
+	return ariaLabelledBy;
+}
+
+function getAriaLabelledBy(labelSource?: LabelSource | null, generatedLabelId?: string) {
+	const label = findAssociatedLabel(labelSource);
+	if (!label) {
+		return undefined;
+	}
+
+	if (!label.id && generatedLabelId) {
+		label.id = generatedLabelId;
+	}
+
+	return label.id || undefined;
+}
+
+function findAssociatedLabel(labelSource?: LabelSource | null) {
+	if (!labelSource) {
+		return undefined;
+	}
+
+	// Fast path before the expensive `.labels` read.
+	const parent = labelSource.parentElement;
+	if (parent && parent.tagName === 'LABEL') {
+		return parent as HTMLLabelElement;
+	}
+
+	const controlId = labelSource.id;
+	if (controlId) {
+		const nextSibling = labelSource.nextElementSibling as HTMLLabelElement | null;
+		if (nextSibling && nextSibling.htmlFor === controlId) {
+			return nextSibling;
+		}
+	}
+
+	const labels = labelSource.labels;
+	return labels && labels[0];
+}
+
+type LabelSource = HTMLElement & { labels?: NodeListOf<HTMLLabelElement> | null | undefined };

package/src/internals/labelable-provider/useLabel.ts

@@ -0,0 +1,113 @@
+/** @jsxImportSource octane */
+'use client';
+import type * as React from 'octane';
+import { isHTMLElement } from '@floating-ui/utils/dom';
+import { ownerDocument } from '@octanejs/base-ui-utils/owner';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { getTarget } from '../../floating-ui-react/utils';
+import { useRegisteredLabelId } from '../../utils/useRegisteredLabelId';
+import { useLabelableContext } from './LabelableContext';
+
+export function useLabel(params: UseLabelParameters = {}): UseLabelReturnValue {
+	const {
+		id: idProp,
+		fallbackControlId,
+		native = false,
+		setLabelId: setLabelIdProp,
+		focusControl: focusControlProp,
+	} = params;
+
+	const { controlId: contextControlId, setLabelId: setContextLabelId } = useLabelableContext();
+
+	const syncLabelId = useStableCallback((nextLabelId: React.SetStateAction<string | undefined>) => {
+		setContextLabelId(nextLabelId);
+		setLabelIdProp?.(nextLabelId);
+	});
+
+	const id = useRegisteredLabelId(idProp, syncLabelId);
+
+	const resolvedControlId = contextControlId ?? fallbackControlId;
+
+	function focusControl(event: React.MouseEvent) {
+		if (focusControlProp) {
+			focusControlProp(event, resolvedControlId);
+			return;
+		}
+
+		if (!resolvedControlId) {
+			return;
+		}
+
+		const controlElement = ownerDocument(event.currentTarget).getElementById(resolvedControlId);
+		if (isHTMLElement(controlElement)) {
+			focusElementWithVisible(controlElement);
+		}
+	}
+
+	function handleInteraction(event: React.MouseEvent) {
+		const target = getTarget(event) as HTMLElement | null;
+		if (target?.closest('button,input,select,textarea')) {
+			return;
+		}
+
+		// Prevent text selection when double clicking label.
+		if (!event.defaultPrevented && event.detail > 1) {
+			event.preventDefault();
+		}
+
+		if (native) {
+			return;
+		}
+
+		focusControl(event);
+	}
+
+	return native
+		? {
+				id,
+				htmlFor: resolvedControlId,
+				onMouseDown: handleInteraction,
+			}
+		: {
+				id,
+				onClick: handleInteraction,
+				onPointerDown(event: React.PointerEvent) {
+					event.preventDefault();
+				},
+			};
+}
+
+export interface UseLabelParameters {
+	id?: string | undefined;
+	/**
+	 * Control id used when no labelable context control id exists.
+	 */
+	fallbackControlId?: string | undefined;
+	/**
+	 * Whether the rendered element is a native `<label>`.
+	 * @default false
+	 */
+	native?: boolean | undefined;
+	/**
+	 * Additional callback to sync the current label id with local component state/store.
+	 */
+	setLabelId?: React.Dispatch<React.SetStateAction<string | undefined>> | undefined;
+	/**
+	 * Custom focus handler for non-native labels.
+	 * If omitted, focus behavior targets the resolved control id.
+	 */
+	focusControl?: ((event: React.MouseEvent, controlId: string | undefined) => void) | undefined;
+}
+
+export type UseLabelReturnValue = Omit<React.LabelHTMLAttributes<any>, 'style' | 'className'> & {
+	style?: React.CSSProperties | undefined;
+	className?: string | undefined;
+};
+
+export function focusElementWithVisible(element: HTMLElement) {
+	element.focus({
+		// Available from Chrome 144+ (January 2026).
+		// Safari and Firefox already support it.
+		focusVisible: true,
+	} as FocusOptions & { focusVisible?: boolean });
+}

package/src/internals/labelable-provider/useLabelableId.ts

@@ -0,0 +1,101 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useRefWithInit } from '@octanejs/base-ui-utils/useRefWithInit';
+import { NOOP } from '../noop';
+import { useBaseUiId } from '../useBaseUiId';
+import { useLabelableContext } from './LabelableContext';
+
+export function useLabelableId(params: UseLabelableIdParameters = {}) {
+	const { id, enabled = true } = params;
+
+	const { controlId, registerControlId, resetControlId } = useLabelableContext();
+
+	// Deliberately not seeded with `id`: on React 17 the seed would stick around after the
+	// `id` prop is removed, leaving the control on a stale id forever.
+	const defaultId = useBaseUiId();
+
+	const controlSourceRef = useRefWithInit(() => Symbol());
+	const hasRegisteredRef = React.useRef(false);
+	const hadExplicitIdRef = React.useRef(false);
+
+	const unregisterControlId = useStableCallback(() => {
+		if (!hasRegisteredRef.current || registerControlId === NOOP) {
+			return;
+		}
+
+		hasRegisteredRef.current = false;
+		registerControlId(controlSourceRef.current, undefined);
+	});
+
+	useIsoLayoutEffect(() => {
+		if (!enabled || registerControlId === NOOP) {
+			unregisterControlId();
+			return undefined;
+		}
+
+		let nextId: string | null | undefined;
+
+		if (id !== undefined) {
+			hadExplicitIdRef.current = true;
+			nextId = id;
+		} else if (hadExplicitIdRef.current) {
+			nextId = defaultId;
+		} else {
+			// An id-less replacement must claim the provider's fallback so a previously registered
+			// explicit id is not retained after its control unmounts.
+			resetControlId();
+			return undefined;
+		}
+
+		// Either the control never had an explicit `id`, or React 17 has not assigned the
+		// fallback id yet. Neither is worth registering.
+		if (nextId === undefined) {
+			unregisterControlId();
+			return undefined;
+		}
+
+		hasRegisteredRef.current = true;
+		registerControlId(controlSourceRef.current, nextId);
+
+		return undefined;
+	}, [
+		id,
+		enabled,
+		registerControlId,
+		resetControlId,
+		defaultId,
+		controlSourceRef,
+		unregisterControlId,
+	]);
+
+	// Unregistering in the layout phase, not a passive effect: a replacement control's layout
+	// effect would otherwise run first and still see the outgoing control's registration.
+	useIsoLayoutEffect(() => {
+		return unregisterControlId;
+	}, [unregisterControlId]);
+
+	// The provider's id wins until registration runs: the label renders `htmlFor` from the
+	// provider's pre-registration state, so preempting it with an explicit `id` here would
+	// leave the pair unassociated in server-rendered markup.
+	return (enabled ? controlId : undefined) ?? id ?? defaultId;
+}
+
+export interface UseLabelableIdParameters {
+	/**
+	 * The control's `id`. Pass `null` for a control that takes its name from `aria-labelledby`
+	 * instead, so that the label omits `htmlFor`.
+	 */
+	id?: string | null | undefined;
+	/**
+	 * Whether the control owns the label association of its labelable scope.
+	 * @default true
+	 */
+	enabled?: boolean | undefined;
+}
+
+export type UseLabelableIdReturnValue = string;
+
+export interface UseLabelableIdState {}

package/src/internals/noop.ts

@@ -0,0 +1 @@
+export { NOOP } from '@octanejs/base-ui-utils/empty';

package/src/internals/prehydrationScript.stub.ts

@@ -0,0 +1,6 @@
+// Shared browser-bundle replacement for the per-component `prehydrationScript.min.ts` files,
+// selected via the `browser` condition of every `#prehydration/*` entry in package.json
+// `imports`. The real scripts only ever execute from server-rendered HTML, so client bundles
+// don't need their contents. See `internals/PrehydrationScript.tsx` for why an empty script is
+// still rendered during hydration.
+export const script = '';

package/src/internals/reason-parts.ts

@@ -0,0 +1,42 @@
+export const none = 'none' as const;
+
+export const triggerPress = 'trigger-press' as const;
+export const triggerHover = 'trigger-hover' as const;
+export const triggerFocus = 'trigger-focus' as const;
+
+export const outsidePress = 'outside-press' as const;
+export const itemPress = 'item-press' as const;
+export const closePress = 'close-press' as const;
+export const linkPress = 'link-press' as const;
+export const clearPress = 'clear-press' as const;
+export const chipRemovePress = 'chip-remove-press' as const;
+export const trackPress = 'track-press' as const;
+export const incrementPress = 'increment-press' as const;
+export const decrementPress = 'decrement-press' as const;
+
+export const inputChange = 'input-change' as const;
+export const inputClear = 'input-clear' as const;
+export const inputBlur = 'input-blur' as const;
+export const inputPaste = 'input-paste' as const;
+export const inputPress = 'input-press' as const;
+
+export const focusOut = 'focus-out' as const;
+export const escapeKey = 'escape-key' as const;
+export const closeWatcher = 'close-watcher' as const;
+export const listNavigation = 'list-navigation' as const;
+export const keyboard = 'keyboard' as const;
+
+export const pointer = 'pointer' as const;
+export const drag = 'drag' as const;
+export const wheel = 'wheel' as const;
+export const scrub = 'scrub' as const;
+
+export const cancelOpen = 'cancel-open' as const;
+export const siblingOpen = 'sibling-open' as const;
+export const disabled = 'disabled' as const;
+export const missing = 'missing' as const;
+export const initial = 'initial' as const;
+export const imperativeAction = 'imperative-action' as const;
+export const swipe = 'swipe' as const;
+
+export const windowResize = 'window-resize' as const;

package/src/internals/reasons.ts

@@ -0,0 +1,5 @@
+import * as REASONS from './reason-parts';
+
+export { REASONS };
+export type BaseUIEventReasons = typeof REASONS;
+export type BaseUIEventReason = BaseUIEventReasons[keyof BaseUIEventReasons];

package/src/internals/resolveValueLabel.tsrx

@@ -0,0 +1,158 @@
+'use client';
+import * as React from 'octane';
+import { serializeValue } from './serializeValue';
+
+type ItemRecord = Record<string, React.OctaneNode>;
+type ItemsInput = ItemRecord | ReadonlyArray<LabeledItem> | ReadonlyArray<Group<any>> | undefined;
+
+interface LabeledItem {
+	value: any;
+	label: React.OctaneNode;
+}
+
+export interface Group<Item = any> {
+	[key: string]: unknown;
+	items: ReadonlyArray<Item>;
+}
+
+function isGroup(item: any): item is Group<any> {
+	return typeof item === 'object' && item != null && Array.isArray(item.items);
+}
+
+export function isGroupedItems(
+	items: ReadonlyArray<any | Group<any>> | undefined,
+): items is ReadonlyArray<Group<any>> {
+	// A group must carry an actual `items` array: key presence alone would misclassify an item
+	// with an unrelated or optional `items` field.
+	return isGroup(items?.[0]);
+}
+
+export function flattenLeafItems<Item>(
+	items: readonly Item[] | readonly Group<Item>[],
+): readonly Item[] {
+	return isGroupedItems(items)
+		? (items as readonly Group<Item>[]).flatMap((group) => group.items)
+		: (items as readonly Item[]);
+}
+
+/**
+ * Checks if the items array contains an item with a null value that has a non-null label.
+ */
+export function hasNullItemLabel(items: ItemsInput): boolean {
+	if (!Array.isArray(items)) {
+		return items != null && 'null' in items;
+	}
+
+	const arrayItems = items as ReadonlyArray<LabeledItem> | ReadonlyArray<Group<any>>;
+
+	if (isGroupedItems(arrayItems)) {
+		for (const group of arrayItems) {
+			for (const item of group.items) {
+				if (item && item.value == null && item.label != null) {
+					return true;
+				}
+			}
+		}
+		return false;
+	}
+
+	for (const item of arrayItems) {
+		if (item && item.value == null && item.label != null) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+export function stringifyAsLabel(item: any, itemToStringLabel?: (item: any) => string) {
+	if (itemToStringLabel && item != null) {
+		return itemToStringLabel(item) ?? '';
+	}
+	if (item && typeof item === 'object') {
+		if ('label' in item && item.label != null) {
+			return String(item.label);
+		}
+		if ('value' in item) {
+			return String(item.value);
+		}
+	}
+	return serializeValue(item);
+}
+
+export function stringifyAsValue(item: any, itemToStringValue?: (item: any) => string) {
+	if (itemToStringValue && item != null) {
+		return itemToStringValue(item) ?? '';
+	}
+	if (item && typeof item === 'object' && 'value' in item && 'label' in item) {
+		return serializeValue(item.value);
+	}
+	return serializeValue(item);
+}
+
+export function resolveSelectedLabel(
+	value: any,
+	items: ItemsInput,
+	itemToStringLabel?: (item: any) => string,
+): React.OctaneNode {
+	function fallback() {
+		return stringifyAsLabel(value, itemToStringLabel);
+	}
+
+	if (itemToStringLabel && value != null) {
+		return itemToStringLabel(value);
+	}
+
+	// Custom object with explicit label takes precedence
+	if (value && typeof value === 'object' && 'label' in value && value.label != null) {
+		return value.label;
+	}
+
+	// Items provided as plain record map
+	if (items && !Array.isArray(items)) {
+		const label = Object.hasOwn(items, value) ? (items as any)[value] : undefined;
+		return label ?? fallback();
+	}
+
+	// Items provided as array (flat or grouped)
+	if (Array.isArray(items)) {
+		const arrayItems = items as ReadonlyArray<LabeledItem> | ReadonlyArray<Group<any>>;
+		const flatItems = flattenLeafItems<LabeledItem>(arrayItems);
+
+		if (value == null || typeof value !== 'object') {
+			const match = flatItems.find((item) => item.value === value);
+			if (match && match.label != null) {
+				return match.label;
+			}
+			return fallback();
+		}
+
+		// Object without explicit label: try matching by its `value` property
+		if ('value' in value) {
+			const match = flatItems.find((item) => item && item.value === value.value);
+			if (match && match.label != null) {
+				return match.label;
+			}
+		}
+	}
+
+	return fallback();
+}
+
+export function resolveMultipleLabels(
+	values: any[],
+	items: ItemsInput,
+	itemToStringLabel?: (item: any) => string,
+): React.OctaneNode {
+	return values.reduce((acc, value, index) => {
+		if (index > 0) {
+			acc.push(', ');
+		}
+		acc.push(
+			<React.Fragment key={index}>
+				{resolveSelectedLabel(value, items, itemToStringLabel)}
+			</React.Fragment>,
+		);
+		return acc;
+	}, []);
+}

package/src/internals/serializeValue.ts

@@ -0,0 +1,13 @@
+export function serializeValue(value: unknown): string {
+	if (value == null) {
+		return '';
+	}
+	if (typeof value === 'string') {
+		return value;
+	}
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}

package/src/internals/stateAttributesMapping.ts

@@ -0,0 +1,20 @@
+import type { TransitionStatus } from './useTransitionStatus';
+import type { StateAttributesMapping } from './getStateAttributesProps';
+import * as TransitionStatusDataAttributes from './TransitionStatusDataAttributes';
+
+export { TransitionStatusDataAttributes };
+
+const STARTING_HOOK = { [TransitionStatusDataAttributes.startingStyle]: '' };
+const ENDING_HOOK = { [TransitionStatusDataAttributes.endingStyle]: '' };
+
+export const transitionStatusMapping = {
+	transitionStatus(value): Record<string, string> | null {
+		if (value === 'starting') {
+			return STARTING_HOOK;
+		}
+		if (value === 'ending') {
+			return ENDING_HOOK;
+		}
+		return null;
+	},
+} satisfies StateAttributesMapping<{ transitionStatus: TransitionStatus }>;

package/src/internals/temporal/index.ts

@@ -0,0 +1,2 @@
+export * from './temporal-adapter';
+export * from './temporal';