@octanejs/base-ui 0.1.49 → 0.1.51

package/src/types/index.ts

@@ -0,0 +1,29 @@
+import type * as React from 'octane';
+
+export type {
+	BaseUIChangeEventDetails,
+	BaseUIGenericEventDetails,
+} from '../internals/createBaseUIEventDetails';
+
+// Base UI composes style declarations property by property. Its style surface
+// stays object-based even though native Octane host elements also accept CSS text.
+export type HTMLProps<T = any> = Omit<React.HTMLAttributes<T>, 'style'> & {
+	style?: React.CSSProperties | undefined;
+	ref?: React.Ref<T> | undefined;
+};
+
+/**
+ * Shape of the render prop: a function that takes props to be spread on the element and component's state and returns a React element.
+ *
+ * @template Props Props to be spread on the rendered element.
+ * @template State Component's internal state.
+ */
+export type ComponentRenderFn<Props, State> = (
+	props: Props,
+	state: State,
+) => React.ReactElement<unknown>;
+
+export type BaseUIEvent<E extends Event> = E & {
+	preventBaseUIHandler: () => void;
+	readonly baseUIHandlerPrevented?: boolean | undefined;
+};

package/src/unstable-use-media-query/index.ts

@@ -0,0 +1,94 @@
+/** @jsxImportSource octane */
+import * as React from 'octane';
+import { addEventListener } from '@octanejs/base-ui-utils/addEventListener';
+import { useSyncExternalStore } from 'octane';
+
+export function useMediaQuery(query: string, options: useMediaQuery.Options = {}): boolean {
+	// Wait for jsdom to support the match media feature.
+	// All the browsers Base UI support have this built-in.
+	// This defensive check is here for simplicity.
+	// Most of the time, the match media logic isn't central to people's tests.
+	const supportMatchMedia =
+		typeof window !== 'undefined' && typeof window.matchMedia !== 'undefined';
+
+	query = query.replace(/^@media( ?)/m, '');
+
+	const {
+		defaultMatches = false,
+		matchMedia = supportMatchMedia ? window.matchMedia : null,
+		ssrMatchMedia = null,
+		noSsr = false,
+	} = options;
+
+	const getDefaultSnapshot = React.useCallback(() => defaultMatches, [defaultMatches]);
+
+	const getServerSnapshot = React.useMemo(() => {
+		if (noSsr && matchMedia) {
+			return () => matchMedia(query).matches;
+		}
+
+		if (ssrMatchMedia !== null) {
+			const { matches } = ssrMatchMedia(query);
+			return () => matches;
+		}
+		return getDefaultSnapshot;
+	}, [getDefaultSnapshot, query, ssrMatchMedia, noSsr, matchMedia]);
+
+	const [getSnapshot, subscribe] = React.useMemo(() => {
+		if (matchMedia === null) {
+			return [getDefaultSnapshot, () => () => {}];
+		}
+
+		const mediaQueryList = matchMedia(query);
+
+		return [
+			() => mediaQueryList.matches,
+			(notify: () => void) => addEventListener(mediaQueryList, 'change', notify),
+		];
+	}, [getDefaultSnapshot, matchMedia, query]);
+
+	const match = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+	if (process.env.NODE_ENV !== 'production') {
+		// eslint-disable-next-line react-hooks/rules-of-hooks
+		React.useDebugValue({ query, match });
+	}
+
+	return match;
+}
+
+export interface UseMediaQueryOptions {
+	/**
+	 * As `window.matchMedia()` is unavailable on the server,
+	 * it returns a default matches during the first mount.
+	 * @default false
+	 */
+	defaultMatches?: boolean | undefined;
+	/**
+	 * You can provide your own implementation of matchMedia.
+	 * This can be used for handling an iframe content window.
+	 */
+	matchMedia?: typeof window.matchMedia | undefined;
+	/**
+	 * To perform the server-side hydration, the hook needs to render twice.
+	 * A first time with `defaultMatches`, the value of the server, and a second time with the resolved value.
+	 * This double pass rendering cycle comes with a drawback: it's slower.
+	 * You can set this option to `true` if you use the returned value **only** client-side.
+	 * @default false
+	 */
+	noSsr?: boolean | undefined;
+	/**
+	 * You can provide your own implementation of `matchMedia`, it's used when rendering server-side.
+	 */
+	ssrMatchMedia?: ((query: string) => { matches: boolean }) | undefined;
+}
+
+export interface UseMediaQueryState {}
+
+export namespace useMediaQuery {
+	export type State = UseMediaQueryState;
+	export type Options = UseMediaQueryOptions;
+}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };

package/src/use-render/index.ts

@@ -0,0 +1,2 @@
+export * from './useRender';
+export type { HTMLProps, ComponentRenderFn } from '../internals/types';

package/src/use-render/useRender.ts

@@ -0,0 +1,113 @@
+/** @jsxImportSource octane */
+import type * as React from 'octane';
+import type { ComponentRenderFn } from '../internals/types';
+import type { HTMLProps } from '../internals/types';
+import { useRenderElement } from '../internals/useRenderElement.tsrx';
+import type { StateAttributesMapping } from '../internals/getStateAttributesProps';
+
+/**
+ * Renders a Base UI element.
+ *
+ * @public
+ */
+export function useRender<
+	State extends Record<string, unknown>,
+	RenderedElementType extends Element,
+	Enabled extends boolean | undefined = undefined,
+>(
+	params: useRender.Parameters<State, RenderedElementType, Enabled>,
+): useRender.ReturnValue<Enabled> {
+	return useRenderElement(params.defaultTagName ?? 'div', params, params);
+}
+
+export type UseRenderRenderProp<State = Record<string, unknown>> =
+	React.ReactElement | ComponentRenderFn<React.HTMLAttributes<any>, State>;
+
+export type UseRenderElementProps<ElementType extends React.ElementType> =
+	React.ComponentPropsWithRef<ElementType>;
+
+export type UseRenderComponentProps<
+	ElementType extends React.ElementType,
+	State = {},
+	RenderFunctionProps = HTMLProps,
+> = React.ComponentPropsWithRef<ElementType> & {
+	/**
+	 * Allows you to replace the component's HTML element
+	 * with a different tag, or compose it with another component.
+	 *
+	 * Accepts a `ReactElement` or a function that returns the element to render.
+	 */
+	render?: React.ReactElement | ComponentRenderFn<RenderFunctionProps, State> | undefined;
+};
+
+export interface UseRenderParameters<
+	State,
+	RenderedElementType extends Element,
+	Enabled extends boolean | undefined,
+> {
+	/**
+	 * The React element or a function that returns one to override the default element.
+	 */
+	render?: UseRenderRenderProp<State> | undefined;
+	/**
+	 * The ref to apply to the rendered element.
+	 */
+	ref?: React.Ref<RenderedElementType> | React.Ref<RenderedElementType>[] | undefined;
+	/**
+	 * The state of the component, passed as the second argument to the `render` callback.
+	 * State properties are automatically converted to data-* attributes.
+	 */
+	state?: State | undefined;
+	/**
+	 * Custom mapping for converting state properties to data-* attributes.
+	 * @example
+	 * { isActive: (value) => (value ? { 'data-is-active': '' } : null) }
+	 */
+	stateAttributesMapping?: StateAttributesMapping<State> | undefined;
+	/**
+	 * Props to be spread on the rendered element.
+	 * They are merged with the internal props of the component, so that event handlers
+	 * are merged, `className` strings and `style` properties are joined, while other external props overwrite the
+	 * internal ones.
+	 */
+	props?: Record<string, unknown> | undefined;
+	/**
+	 * If `false`, the hook will skip most of its internal logic and return `null`.
+	 * This is useful for rendering a component conditionally.
+	 * @default true
+	 */
+	enabled?: Enabled | undefined;
+	/**
+	 * The default tag name to use for the rendered element when `render` is not provided.
+	 * @default 'div'
+	 */
+	defaultTagName?: keyof React.JSX.IntrinsicElements | undefined;
+}
+
+export type UseRenderReturnValue<Enabled extends boolean | undefined> = Enabled extends false
+	? null
+	: React.ReactElement;
+
+export interface UseRenderState {}
+
+export namespace useRender {
+	export type State = UseRenderState;
+	export type RenderProp<TState = Record<string, unknown>> = UseRenderRenderProp<TState>;
+
+	export type ElementProps<ElementType extends React.ElementType> =
+		UseRenderElementProps<ElementType>;
+
+	export type ComponentProps<
+		ElementType extends React.ElementType,
+		TState = {},
+		RenderFunctionProps = HTMLProps,
+	> = UseRenderComponentProps<ElementType, TState, RenderFunctionProps>;
+
+	export type Parameters<
+		TState,
+		RenderedElementType extends Element,
+		Enabled extends boolean | undefined,
+	> = UseRenderParameters<TState, RenderedElementType, Enabled>;
+
+	export type ReturnValue<Enabled extends boolean | undefined> = UseRenderReturnValue<Enabled>;
+}

package/src/utils/CommonPopupCssVars.ts

@@ -0,0 +1,12 @@
+/**
+ * The width of the parent popup.
+ * This variable is placed on the 'previous' container and stores the width of the popup when the previous content was rendered.
+ * It can be used to freeze the dimensions of the popup when animating between different content.
+ */
+export const popupWidth = '--popup-width';
+/**
+ * The height of the parent popup.
+ * This variable is placed on the 'previous' container and stores the height of the popup when the previous content was rendered.
+ * It can be used to freeze the dimensions of the popup when animating between different content.
+ */
+export const popupHeight = '--popup-height';

package/src/utils/CommonPopupDataAttributes.ts

@@ -0,0 +1,38 @@
+import * as TransitionStatusDataAttributes from '../internals/TransitionStatusDataAttributes';
+
+/**
+ * Present when the popup is open.
+ */
+export const open = 'data-open';
+
+/**
+ * Present when the popup is closed.
+ */
+export const closed = 'data-closed';
+
+/**
+ * Present when the popup begins animating in.
+ */
+export const startingStyle = TransitionStatusDataAttributes.startingStyle;
+
+/**
+ * Present when the popup is animating out.
+ */
+export const endingStyle = TransitionStatusDataAttributes.endingStyle;
+
+/**
+ * Present when the anchor is hidden.
+ */
+export const anchorHidden = 'data-anchor-hidden';
+
+/**
+ * Indicates which side the popup is positioned relative to the trigger.
+ * @type { 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'}
+ */
+export const side = 'data-side';
+
+/**
+ * Indicates how the popup is aligned relative to specified side.
+ * @type {'start' | 'center' | 'end'}
+ */
+export const align = 'data-align';

package/src/utils/CommonPositionerCssVars.ts

@@ -0,0 +1,37 @@
+/**
+ * The available width between the trigger and the edge of the viewport.
+ * @type {number}
+ */
+export const availableWidth = '--available-width';
+/**
+ * The available height between the trigger and the edge of the viewport.
+ * @type {number}
+ */
+export const availableHeight = '--available-height';
+/**
+ * The anchor's width.
+ * @type {number}
+ */
+export const anchorWidth = '--anchor-width';
+/**
+ * The anchor's height.
+ * @type {number}
+ */
+export const anchorHeight = '--anchor-height';
+/**
+ * The coordinates that this element is anchored to. Used for animations and transitions.
+ * @type {string}
+ */
+export const transformOrigin = '--transform-origin';
+/**
+ * The width of the popup's positioner.
+ * It is important to set `width` to this value when using CSS to animate size changes.
+ * @type {number}
+ */
+export const positionerWidth = '--positioner-width';
+/**
+ * The height of the popup's positioner.
+ * It is important to set `height` to this value when using CSS to animate size changes.
+ * @type {number}
+ */
+export const positionerHeight = '--positioner-height';

package/src/utils/CommonTriggerDataAttributes.ts

@@ -0,0 +1,9 @@
+/**
+ * Present when the popup is open.
+ */
+export const popupOpen = 'data-popup-open';
+
+/**
+ * Present when a pressable trigger is pressed.
+ */
+export const pressed = 'data-pressed';

package/src/utils/CommonViewportDataAttributes.ts

@@ -0,0 +1,7 @@
+/**
+ * Indicates the direction from which the popup was activated.
+ * This can be used to create directional animations based on how the popup was triggered.
+ * Contains space-separated values for both horizontal and vertical axes.
+ * @type {`${'left' | 'right' | ''} ${'down' | 'up' | ''}`}
+ */
+export const activationDirection = 'data-activation-direction';

package/src/utils/FloatingPortalLite.tsrx

@@ -0,0 +1,51 @@
+'use client';
+import * as React from 'octane';
+import * as ReactDOM from 'octane';
+import { type BaseUIComponentProps } from '../internals/types';
+import { useFloatingPortalNode } from '../floating-ui-react/components/FloatingPortal.tsrx';
+
+type PortalContainer =
+	HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null;
+
+/**
+ * `FloatingPortal` includes tabbable logic handling for focus management.
+ * For components that don't need tabbable logic, use `FloatingPortalLite`.
+ * @internal
+ */
+export const FloatingPortalLite = function FloatingPortalLite(
+	componentPropsWithRef: React.PropsWithoutRef<FloatingPortalLite.Props<any>> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { children, container, className, render, style, ...elementProps } = componentProps;
+
+	const { node: portalNode, subtree: portalSubtree } = useFloatingPortalNode({
+		container,
+		ref: forwardedRef,
+		componentProps,
+		elementProps,
+	});
+
+	if (!portalSubtree && !portalNode) {
+		return null;
+	}
+
+	return (
+		<React.Fragment>
+			{portalSubtree}
+			{portalNode && ReactDOM.createPortal(children, portalNode)}
+		</React.Fragment>
+	);
+};
+
+export interface FloatingPortalLiteState {}
+
+export interface FloatingPortalLiteProps<TState> extends BaseUIComponentProps<'div', TState> {
+	container?: PortalContainer | undefined;
+}
+
+export namespace FloatingPortalLite {
+	export type State = FloatingPortalLiteState;
+	export type Props<TState> = FloatingPortalLiteProps<TState>;
+}

package/src/utils/FocusGuard.tsrx

@@ -0,0 +1,44 @@
+'use client';
+import * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { platform } from '@octanejs/base-ui-utils/platform';
+import { visuallyHidden } from '@octanejs/base-ui-utils/visuallyHidden';
+
+/**
+ * @internal
+ */
+export const FocusGuard = function FocusGuard(
+	propsWithRef: React.PropsWithoutRef<React.ComponentPropsWithoutRef<'span'>> & {
+		ref?: React.Ref<HTMLSpanElement>;
+	},
+) {
+	const { ref: ref = null, ...props } = propsWithRef;
+	const [role, setRole] = React.useState<'button' | undefined>();
+
+	useIsoLayoutEffect(() => {
+		// Unlike NVDA and JAWS, VoiceOver's virtual cursor triggers `onFocus` as
+		// it moves — but only on focusable/role-button elements through WebKit's
+		// NSAccessibility path. Setting `role="button"` lets the focus trap catch
+		// the cursor.
+		if (platform.screenReader.voiceOver && platform.engine.webkit) {
+			setRole('button');
+		}
+	}, []);
+
+	const restProps = {
+		tabIndex: 0,
+		// Role is only for VoiceOver
+		role,
+	};
+
+	return (
+		<span
+			{...props}
+			ref={ref}
+			style={visuallyHidden}
+			aria-hidden={role ? undefined : true}
+			{...restProps}
+			data-base-ui-focus-guard=""
+		/>
+	);
+};

package/src/utils/InternalBackdrop.tsrx

@@ -0,0 +1,50 @@
+import * as React from 'octane';
+
+/**
+ * @internal
+ */
+export const InternalBackdrop = function InternalBackdrop(
+	propsWithRef: React.PropsWithoutRef<InternalBackdrop.Props> & { ref?: React.Ref<HTMLDivElement> },
+) {
+	const { ref: ref = null, ...props } = propsWithRef;
+	const { cutout, ...otherProps } = props;
+
+	let clipPath: string | undefined;
+	if (cutout) {
+		const rect = cutout.getBoundingClientRect();
+		clipPath = `polygon(0% 0%,100% 0%,100% 100%,0% 100%,0% 0%,${rect.left}px ${rect.top}px,${rect.left}px ${rect.bottom}px,${rect.right}px ${rect.bottom}px,${rect.right}px ${rect.top}px,${rect.left}px ${rect.top}px)`;
+	}
+
+	return (
+		<div
+			ref={ref}
+			role="presentation"
+			// Ensures Floating UI's outside press detection runs, as it considers
+			// it an element that existed when the popup rendered.
+			data-base-ui-inert=""
+			{...otherProps}
+			style={{
+				position: 'fixed',
+				inset: 0,
+				userSelect: 'none',
+				WebkitUserSelect: 'none',
+				clipPath,
+			}}
+		/>
+	);
+};
+
+export interface InternalBackdropState {}
+
+export interface InternalBackdropProps extends React.HTMLAttributes<HTMLDivElement> {
+	/**
+	 * The element to cut out of the backdrop.
+	 * This is useful for allowing certain elements to be interactive while the backdrop is present.
+	 */
+	cutout?: Element | null | undefined;
+}
+
+export namespace InternalBackdrop {
+	export type State = InternalBackdropState;
+	export type Props = InternalBackdropProps;
+}

package/src/utils/NullStore.ts

@@ -0,0 +1,26 @@
+import { ReactStore } from '@octanejs/base-ui-utils/store';
+
+type SelectorFunction<State> = (state: State, ...args: any[]) => any;
+
+/**
+ * A `ReactStore` whose state never changes.
+ *
+ * Useful for fallback stores that need to support normal store reads while detached from the
+ * component that owns real state. Context values may still contain mutable refs or maps.
+ */
+export class NullStore<
+	State extends object,
+	Context = Record<string, never>,
+	Selectors extends Record<string, SelectorFunction<State>> = Record<string, never>,
+> extends ReactStore<State, Context, Selectors> {
+	// `update`/`set`/`notifyAll` funnel through `setState` in the base `Store`, so overriding
+	// `setState` alone would neutralize them today. They are overridden explicitly so the store stays
+	// inert even if a future base-class change stops routing a mutator through `setState`.
+	setState(_newState: State) {}
+
+	update<const Key extends keyof State>(_changes: Pick<State, Key>) {}
+
+	set<Key extends keyof State>(_key: Key, _value: State[Key]) {}
+
+	notifyAll() {}
+}

package/src/utils/adaptiveOriginConstants.ts

@@ -0,0 +1,12 @@
+export const DEFAULT_SIDES = {
+	sideX: 'left',
+	sideY: 'top',
+} as const;
+
+// Self-contained stand-in for Floating UI's `Middleware` type. Referencing the real type in
+// store state makes `tsc` declaration emit reference `Platform`/`detectOverflow` from
+// `@floating-ui/core` internals, which fails as non-portable (TS2883) in consuming builds.
+export type AdaptiveOriginMiddleware = {
+	name: string;
+	fn: (...args: any[]) => any;
+};

package/src/utils/adaptiveOriginMiddleware.ts

@@ -1,20 +1,11 @@
-// Ported verbatim from .base-ui/packages/react/src/utils/adaptiveOriginMiddleware.ts (v1.6.0).
-// Pure @floating-ui middleware (no React) — used only when a popup is anchored to a viewport
-// (`hasViewport`). Rewrites the resolved x/y into `right`/`bottom` origins on the sides that need
-// it so CSS transforms scale from the correct corner. `DEFAULT_SIDES` is the fallback used when the
-// middleware doesn't run (no transition, or `adaptiveOrigin` disabled).
+import { ownerDocument, ownerWindow } from '@octanejs/base-ui-utils/owner';
 import { getSide } from '@floating-ui/utils';
+import type { Middleware } from '../floating-ui-react';
+import { DEFAULT_SIDES } from './adaptiveOriginConstants';
 
-import { ownerDocument, ownerWindow } from './owner';
-
-export const DEFAULT_SIDES = {
-	sideX: 'left',
-	sideY: 'top',
-} as const;
-
-export const adaptiveOrigin: any = {
+export const adaptiveOrigin: Middleware = {
 	name: 'adaptiveOrigin',
-	async fn(state: any) {
+	async fn(state) {
 		const {
 			x: rawX,
 			y: rawY,

package/src/utils/closePart.tsrx

@@ -0,0 +1,37 @@
+'use client';
+import * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+
+interface ClosePartContextValue {
+	register: () => () => void;
+}
+
+export const ClosePartContext = React.createContext<ClosePartContextValue | undefined>(undefined);
+
+export function useClosePartCount() {
+	const [closePartCount, setClosePartCount] = React.useState(0);
+
+	const register = useStableCallback(() => {
+		setClosePartCount((count) => count + 1);
+
+		return () => {
+			setClosePartCount((count) => Math.max(0, count - 1));
+		};
+	});
+
+	const context = React.useMemo(() => ({ register }), [register]);
+
+	return {
+		context,
+		hasClosePart: closePartCount > 0,
+	};
+}
+
+export function useClosePartRegistration() {
+	const context = React.useContext(ClosePartContext);
+
+	useIsoLayoutEffect(() => {
+		return context?.register();
+	}, [context]);
+}

package/src/utils/collapsibleOpenStateMapping.ts

@@ -1,30 +1,35 @@
-// Ported from .base-ui/packages/react/src/utils/collapsibleOpenStateMapping.ts (v1.6.0).
-//
-// NAME COLLISION, upstream's not ours: Base UI exports `triggerOpenStateMapping` from BOTH
-// this module and `utils/popupStateMapping.ts`, and they emit DIFFERENT attributes —
-// `data-panel-open` here versus `data-popup-open` there. Each consumer imports the one it
-// means, and the collapsible trigger means this one. This package puts one util per file, so
-// the collapsible variant is renamed rather than shadowing the popup export: importing the
-// wrong one is a silent attribute swap that only a rendered-DOM assertion would catch.
-import type { StateAttributesMapping } from './getStateAttributesProps';
+import type { StateAttributesMapping } from '../internals/getStateAttributesProps';
+import * as CollapsiblePanelDataAttributes from '../collapsible/panel/CollapsiblePanelDataAttributes';
+import * as CollapsibleTriggerDataAttributes from '../collapsible/trigger/CollapsibleTriggerDataAttributes';
 
-// CollapsiblePanelDataAttributes.open / .closed
-const PANEL_OPEN_HOOK = { 'data-open': '' };
-const PANEL_CLOSED_HOOK = { 'data-closed': '' };
+const PANEL_OPEN_HOOK = {
+	[CollapsiblePanelDataAttributes.open]: '',
+};
 
-// CollapsibleTriggerDataAttributes.panelOpen
-const TRIGGER_PANEL_OPEN_HOOK = { 'data-panel-open': '' };
+const PANEL_CLOSED_HOOK = {
+	[CollapsiblePanelDataAttributes.closed]: '',
+};
 
-/** The panel/root mapping: `data-open` when open, `data-closed` when not. */
-export const collapsibleOpenStateMapping: StateAttributesMapping<{ open: boolean }> = {
-	open(value: boolean) {
-		return value ? PANEL_OPEN_HOOK : PANEL_CLOSED_HOOK;
+export const triggerOpenStateMapping: StateAttributesMapping<{
+	open: boolean;
+}> = {
+	open(value) {
+		if (value) {
+			return {
+				[CollapsibleTriggerDataAttributes.panelOpen]: '',
+			};
+		}
+		return null;
 	},
 };
 
-/** Upstream's `triggerOpenStateMapping` from this module: `data-panel-open`, or nothing. */
-export const collapsibleTriggerOpenStateMapping: StateAttributesMapping<{ open: boolean }> = {
-	open(value: boolean) {
-		return value ? TRIGGER_PANEL_OPEN_HOOK : null;
+export const collapsibleOpenStateMapping = {
+	open(value) {
+		if (value) {
+			return PANEL_OPEN_HOOK;
+		}
+		return PANEL_CLOSED_HOOK;
 	},
-};
+} satisfies StateAttributesMapping<{
+	open: boolean;
+}>;