@octanejs/base-ui 0.1.49 → 0.1.51

package/src/combobox/utils/parts.ts

@@ -0,0 +1,59 @@
+/** @jsxImportSource octane */
+'use client';
+import { useComboboxDerivedItemsContext } from '../root/ComboboxRootContext.tsrx';
+import type { ComboboxStore } from '../store';
+import type { Side } from '../../internals/useAnchorPositioning';
+
+/**
+ * The popup side is only meaningful while the positioner is mounted, as the store retains the
+ * last resolved side after the popup unmounts.
+ */
+export function usePopupSide(store: ComboboxStore): Side | null {
+	const mounted = store.useState('mounted');
+	const popupSide = store.useState('popupSide');
+	const positionerElement = store.useState('positionerElement');
+
+	return mounted && positionerElement ? popupSide : null;
+}
+
+/**
+ * Whether the filtered list has no items to show.
+ */
+export function useListEmpty(): boolean {
+	return useComboboxDerivedItemsContext().filteredItems.length === 0;
+}
+
+/**
+ * The arrow keys that move the chip highlight backwards and forwards, in that order.
+ */
+export function getChipNavigationKeys(direction: 'ltr' | 'rtl') {
+	return direction === 'rtl'
+		? (['ArrowRight', 'ArrowLeft'] as const)
+		: (['ArrowLeft', 'ArrowRight'] as const);
+}
+
+/**
+ * Where the highlight lands once the chip at `index` is removed, or `undefined` for no highlight.
+ */
+export function getIndexAfterChipRemoval(index: number, chipCount: number) {
+	const nextIndex = index >= chipCount - 1 ? chipCount - 2 : index;
+	return nextIndex >= 0 ? nextIndex : undefined;
+}
+
+/**
+ * Commits the highlighted item by clicking it, tagging the originating event so the item's
+ * handler can attribute the selection to it.
+ */
+export function clickHighlightedItem(
+	store: ComboboxStore,
+	activeIndex: number,
+	nativeEvent: KeyboardEvent,
+) {
+	const listItem = store.context.listRef.current[activeIndex];
+
+	if (listItem) {
+		store.context.selectionEventRef.current = nativeEvent;
+		listItem.click();
+		store.context.selectionEventRef.current = null;
+	}
+}

package/src/combobox/utils/stateAttributesMapping.ts

@@ -0,0 +1,19 @@
+import { pressableTriggerOpenStateMapping } from '../../utils/popupStateMapping';
+import type { StateAttributesMapping } from '../../internals/getStateAttributesProps';
+import type { Side } from '../../internals/useAnchorPositioning';
+import { fieldValidityMapping } from '../../internals/field-constants/constants';
+import * as ComboboxInputDataAttributes from '../input/ComboboxInputDataAttributes';
+
+export const triggerStateAttributesMapping = {
+	...pressableTriggerOpenStateMapping,
+	...fieldValidityMapping,
+	popupSide: (side: Side | null) =>
+		side ? { [ComboboxInputDataAttributes.popupSide]: side } : null,
+	listEmpty: (empty: boolean) => (empty ? { [ComboboxInputDataAttributes.listEmpty]: '' } : null),
+} satisfies StateAttributesMapping<{
+	open: boolean;
+	valid: boolean | null;
+	popupSide: Side | null;
+	listEmpty: boolean;
+	placeholder: boolean;
+}>;

package/src/combobox/utils/useInitialLiveRegionTextMutation.ts

@@ -0,0 +1,66 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { platform } from '@octanejs/base-ui-utils/platform';
+import { useTimeout } from '@octanejs/base-ui-utils/useTimeout';
+
+// Word Joiner is invisible and zero-width, so it forces a text mutation without shifting layout.
+const LIVE_REGION_MARKER = '\u2060';
+// Safari VoiceOver needed roughly 200ms to reliably notice the initial polite live-region change.
+export const INITIAL_LIVE_REGION_TEXT_MUTATION_RESET_DELAY = 200;
+
+function findLastTextNode(root: HTMLElement): Text | null {
+	const walker = root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+	let lastTextNode: Text | null = null;
+
+	while (walker.nextNode()) {
+		const textNode = walker.currentNode as Text;
+		if (textNode.nodeValue !== '') {
+			lastTextNode = textNode;
+		}
+	}
+
+	return lastTextNode;
+}
+
+export function useInitialLiveRegionTextMutation<T extends HTMLElement>() {
+	const timeout = useTimeout();
+	const rootRef = React.useRef<T | null>(null);
+
+	// Only the initial mounted announcement needs the marker; later text updates announce naturally.
+	React.useEffect(() => {
+		if (platform.os.ios) {
+			return undefined;
+		}
+
+		const root = rootRef.current;
+		if (root == null) {
+			return undefined;
+		}
+
+		const textNode = findLastTextNode(root);
+		if (textNode == null) {
+			return undefined;
+		}
+
+		const originalValue = textNode.data;
+		const markedValue = `${originalValue}${LIVE_REGION_MARKER}`;
+		textNode.nodeValue = markedValue;
+
+		timeout.start(INITIAL_LIVE_REGION_TEXT_MUTATION_RESET_DELAY, () => {
+			if (textNode.nodeValue === markedValue) {
+				textNode.nodeValue = originalValue;
+			}
+		});
+
+		return () => {
+			timeout.clear();
+
+			if (textNode.nodeValue === markedValue) {
+				textNode.nodeValue = originalValue;
+			}
+		};
+	}, [rootRef, timeout]);
+
+	return rootRef;
+}

package/src/combobox/value/ComboboxValue.tsrx

@@ -0,0 +1,65 @@
+'use client';
+import * as React from 'octane';
+import { useComboboxRootContext } from '../root/ComboboxRootContext.tsrx';
+import {
+	resolveMultipleLabels,
+	resolveSelectedLabel,
+} from '../../internals/resolveValueLabel.tsrx';
+
+/**
+ * The current value of the combobox.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Combobox](https://base-ui.com/react/components/combobox)
+ */
+export function ComboboxValue(props: ComboboxValue.Props): React.ReactElement {
+	const { children: childrenProp, placeholder } = props;
+
+	const store = useComboboxRootContext();
+
+	const itemToStringLabel = store.useState('itemToStringLabel');
+	const selectedValue = store.useState('selectedValue');
+	const items = store.useState('items');
+	const multiple = store.useState('selectionMode') === 'multiple';
+	const hasSelectedValue = store.useState('hasSelectedValue');
+
+	const shouldCheckNullItemLabel = !hasSelectedValue && placeholder != null && childrenProp == null;
+	const hasNullLabel = store.useState('hasNullItemLabel', shouldCheckNullItemLabel);
+
+	let children = null;
+	if (typeof childrenProp === 'function' && !React.isChildrenBlock(childrenProp)) {
+		children = childrenProp(selectedValue);
+	} else if (childrenProp != null) {
+		children = childrenProp;
+	} else if (!hasSelectedValue && placeholder != null && !hasNullLabel) {
+		children = placeholder;
+	} else if (multiple && Array.isArray(selectedValue)) {
+		children = resolveMultipleLabels(selectedValue, items, itemToStringLabel);
+	} else {
+		children = resolveSelectedLabel(selectedValue, items, itemToStringLabel);
+	}
+
+	return <React.Fragment>{children}</React.Fragment>;
+}
+
+export interface ComboboxValueState {}
+
+export interface ComboboxValueProps {
+	/**
+	 * Accepts a function that returns a `ReactNode` to format the selected value.
+	 * Treat the value as read-only: in `multiple` mode it may be a shared frozen array
+	 * when nothing is selected.
+	 */
+	children?:
+		NonNullable<React.OctaneNode> | null | undefined | ((selectedValue: any) => React.OctaneNode);
+	/**
+	 * The placeholder value to display when no value is selected.
+	 * This is overridden by `children` if specified, or by a null item's label in `items`.
+	 */
+	placeholder?: React.OctaneNode;
+}
+
+export namespace ComboboxValue {
+	export type State = ComboboxValueState;
+	export type Props = ComboboxValueProps;
+}

package/src/context-menu/index.parts.ts

@@ -0,0 +1,21 @@
+export { ContextMenuRoot as Root } from './root/ContextMenuRoot.tsrx';
+export { ContextMenuTrigger as Trigger } from './trigger/ContextMenuTrigger.tsrx';
+
+export { MenuBackdrop as Backdrop } from '../menu/backdrop/MenuBackdrop.tsrx';
+export { MenuPortal as Portal } from '../menu/portal/MenuPortal.tsrx';
+export { ContextMenuPositioner as Positioner } from './positioner/ContextMenuPositioner.tsrx';
+export { MenuPopup as Popup } from '../menu/popup/MenuPopup.tsrx';
+export { MenuArrow as Arrow } from '../menu/arrow/MenuArrow.tsrx';
+export { MenuGroup as Group } from '../menu/group/MenuGroup.tsrx';
+export { MenuGroupLabel as GroupLabel } from '../menu/group-label/MenuGroupLabel.tsrx';
+export { MenuItem as Item } from '../menu/item/MenuItem.tsrx';
+export { MenuCheckboxItem as CheckboxItem } from '../menu/checkbox-item/MenuCheckboxItem.tsrx';
+export { MenuCheckboxItemIndicator as CheckboxItemIndicator } from '../menu/checkbox-item-indicator/MenuCheckboxItemIndicator.tsrx';
+export { MenuLinkItem as LinkItem } from '../menu/link-item/MenuLinkItem.tsrx';
+export { MenuRadioGroup as RadioGroup } from '../menu/radio-group/MenuRadioGroup.tsrx';
+export { MenuRadioItem as RadioItem } from '../menu/radio-item/MenuRadioItem.tsrx';
+export { MenuRadioItemIndicator as RadioItemIndicator } from '../menu/radio-item-indicator/MenuRadioItemIndicator.tsrx';
+export { MenuSubmenuRoot as SubmenuRoot } from '../menu/submenu-root/MenuSubmenuRoot.tsrx';
+export { MenuSubmenuTrigger as SubmenuTrigger } from '../menu/submenu-trigger/MenuSubmenuTrigger.tsrx';
+
+export { Separator } from '../separator/Separator.tsrx';

package/src/context-menu/index.ts

@@ -0,0 +1,66 @@
+export * as ContextMenu from './index.parts';
+
+export type * from './root/ContextMenuRoot.tsrx';
+export type * from './trigger/ContextMenuTrigger.tsrx';
+export type * from './positioner/ContextMenuPositioner.tsrx';
+
+export type {
+	MenuBackdropProps as ContextMenuBackdropProps,
+	MenuBackdropState as ContextMenuBackdropState,
+} from '../menu/backdrop/MenuBackdrop.tsrx';
+export type {
+	MenuPortalProps as ContextMenuPortalProps,
+	MenuPortalState as ContextMenuPortalState,
+} from '../menu/portal/MenuPortal.tsrx';
+export type {
+	MenuPopupProps as ContextMenuPopupProps,
+	MenuPopupState as ContextMenuPopupState,
+} from '../menu/popup/MenuPopup.tsrx';
+export type {
+	MenuArrowProps as ContextMenuArrowProps,
+	MenuArrowState as ContextMenuArrowState,
+} from '../menu/arrow/MenuArrow.tsrx';
+export type {
+	MenuGroupProps as ContextMenuGroupProps,
+	MenuGroupState as ContextMenuGroupState,
+} from '../menu/group/MenuGroup.tsrx';
+export type {
+	MenuGroupLabelProps as ContextMenuGroupLabelProps,
+	MenuGroupLabelState as ContextMenuGroupLabelState,
+} from '../menu/group-label/MenuGroupLabel.tsrx';
+export type {
+	MenuItemProps as ContextMenuItemProps,
+	MenuItemState as ContextMenuItemState,
+} from '../menu/item/MenuItem.tsrx';
+export type {
+	MenuLinkItemProps as ContextMenuLinkItemProps,
+	MenuLinkItemState as ContextMenuLinkItemState,
+} from '../menu/link-item/MenuLinkItem.tsrx';
+export type {
+	MenuCheckboxItemProps as ContextMenuCheckboxItemProps,
+	MenuCheckboxItemState as ContextMenuCheckboxItemState,
+} from '../menu/checkbox-item/MenuCheckboxItem.tsrx';
+export type {
+	MenuCheckboxItemIndicatorProps as ContextMenuCheckboxItemIndicatorProps,
+	MenuCheckboxItemIndicatorState as ContextMenuCheckboxItemIndicatorState,
+} from '../menu/checkbox-item-indicator/MenuCheckboxItemIndicator.tsrx';
+export type {
+	MenuRadioGroupProps as ContextMenuRadioGroupProps,
+	MenuRadioGroupState as ContextMenuRadioGroupState,
+} from '../menu/radio-group/MenuRadioGroup.tsrx';
+export type {
+	MenuRadioItemProps as ContextMenuRadioItemProps,
+	MenuRadioItemState as ContextMenuRadioItemState,
+} from '../menu/radio-item/MenuRadioItem.tsrx';
+export type {
+	MenuRadioItemIndicatorProps as ContextMenuRadioItemIndicatorProps,
+	MenuRadioItemIndicatorState as ContextMenuRadioItemIndicatorState,
+} from '../menu/radio-item-indicator/MenuRadioItemIndicator.tsrx';
+export type {
+	MenuSubmenuRootProps as ContextMenuSubmenuRootProps,
+	MenuSubmenuRootState as ContextMenuSubmenuRootState,
+} from '../menu/submenu-root/MenuSubmenuRoot.tsrx';
+export type {
+	MenuSubmenuTriggerProps as ContextMenuSubmenuTriggerProps,
+	MenuSubmenuTriggerState as ContextMenuSubmenuTriggerState,
+} from '../menu/submenu-trigger/MenuSubmenuTrigger.tsrx';

package/src/context-menu/positioner/ContextMenuPositioner.tsrx

@@ -0,0 +1,119 @@
+'use client';
+import type * as React from 'octane';
+import {
+	MenuPositioner,
+	type MenuPositionerProps,
+	type MenuPositionerState,
+} from '../../menu/positioner/MenuPositioner.tsrx';
+import type { BaseUIComponentProps } from '../../internals/types';
+
+export interface ContextMenuPositionerState extends MenuPositionerState {}
+
+/**
+ * Positions the context menu popup against the pointer or a custom anchor.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Context Menu](https://base-ui.com/react/components/context-menu)
+ */
+export const ContextMenuPositioner: React.FunctionComponent<
+	ContextMenuPositionerProps & React.RefAttributes<HTMLDivElement>
+> = MenuPositioner;
+
+export interface ContextMenuPositionerProps
+	extends
+		Omit<
+			MenuPositionerProps,
+			| keyof BaseUIComponentProps<'div', ContextMenuPositionerState>
+			| 'anchor'
+			| 'positionMethod'
+			| 'side'
+			| 'sideOffset'
+			| 'align'
+			| 'alignOffset'
+			| 'arrowPadding'
+		>,
+		BaseUIComponentProps<'div', ContextMenuPositionerState> {
+	/**
+	 * An element to position the popup against.
+	 * By default, root context menus are positioned at the pointer, and submenus are positioned
+	 * against their trigger.
+	 */
+	anchor?: MenuPositionerProps['anchor'] | undefined;
+	/**
+	 * @ignore
+	 * @deprecated This prop has no effect on Context Menu.
+	 */
+	positionMethod?: MenuPositionerProps['positionMethod'] | undefined;
+	/**
+	 * Which side of the anchor element to align the popup against.
+	 * May automatically change to avoid collisions.
+	 *
+	 * Submenus default to `'inline-end'`.
+	 * @default 'bottom'
+	 */
+	side?: MenuPositionerProps['side'] | undefined;
+	/**
+	 * Distance between the anchor and the popup in pixels.
+	 * Also accepts a function that returns the distance to read the dimensions of the anchor
+	 * and positioner elements, along with its side and alignment.
+	 *
+	 * The function takes a `data` object parameter with the following properties:
+	 * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+	 * - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.
+	 * - `data.side`: which side of the anchor element the positioner is aligned against.
+	 * - `data.align`: how the positioner is aligned relative to the specified side.
+	 *
+	 * Defaults to `-5` for root context menus when `side` is not specified and `align` is not
+	 * `'center'`. Otherwise, it defaults to `0`.
+	 *
+	 * @example
+	 * ```jsx
+	 * <ContextMenu.Positioner
+	 *   sideOffset={({ side, anchor }) => {
+	 *     return side === 'top' || side === 'bottom' ? anchor.height : anchor.width;
+	 *   }}
+	 * />
+	 * ```
+	 */
+	sideOffset?: MenuPositionerProps['sideOffset'] | undefined;
+	/**
+	 * How to align the popup relative to the specified side.
+	 * @default 'start'
+	 */
+	align?: MenuPositionerProps['align'] | undefined;
+	/**
+	 * Additional offset along the alignment axis in pixels.
+	 * Also accepts a function that returns the offset to read the dimensions of the anchor
+	 * and positioner elements, along with its side and alignment.
+	 *
+	 * The function takes a `data` object parameter with the following properties:
+	 * - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`.
+	 * - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`.
+	 * - `data.side`: which side of the anchor element the positioner is aligned against.
+	 * - `data.align`: how the positioner is aligned relative to the specified side.
+	 *
+	 * Defaults to `2` for root context menus when `side` is not specified and `align` is not
+	 * `'center'`. Otherwise, it defaults to `0`.
+	 *
+	 * @example
+	 * ```jsx
+	 * <ContextMenu.Positioner
+	 *   alignOffset={({ side, anchor }) => {
+	 *     return side === 'top' || side === 'bottom' ? anchor.width : anchor.height;
+	 *   }}
+	 * />
+	 * ```
+	 */
+	alignOffset?: MenuPositionerProps['alignOffset'] | undefined;
+	/**
+	 * Minimum distance to maintain between the arrow and the edges of the popup.
+	 *
+	 * Root context menus always use `0`. Submenus default to `5`.
+	 */
+	arrowPadding?: MenuPositionerProps['arrowPadding'] | undefined;
+}
+
+export namespace ContextMenuPositioner {
+	export type Props = ContextMenuPositionerProps;
+	export type State = ContextMenuPositionerState;
+}

package/src/context-menu/positioner/ContextMenuPositionerCssVars.ts

@@ -0,0 +1 @@
+export * from '../../menu/positioner/MenuPositionerCssVars';

package/src/context-menu/positioner/ContextMenuPositionerDataAttributes.ts

@@ -0,0 +1 @@
+export * from '../../menu/positioner/MenuPositionerDataAttributes';

package/src/context-menu/root/ContextMenuRoot.tsrx

@@ -0,0 +1,98 @@
+'use client';
+import * as React from 'octane';
+import { useId } from '@octanejs/base-ui-utils/useId';
+import { ContextMenuRootContext } from './ContextMenuRootContext';
+import { Menu } from '../../menu';
+import { MenuRootContext } from '../../menu/root/MenuRootContext';
+import type { BaseUIChangeEventDetails } from '../../types';
+import type { MenuRoot } from '../../menu/root/MenuRoot.tsrx';
+
+/**
+ * A component that creates a context menu activated by right clicking or long pressing.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Context Menu](https://base-ui.com/react/components/context-menu)
+ */
+export function ContextMenuRoot(props: ContextMenuRoot.Props) {
+	const [anchor, setAnchor] = React.useState<ContextMenuRootContext['anchor']>({
+		getBoundingClientRect() {
+			return DOMRect.fromRect({ width: 0, height: 0, x: 0, y: 0 });
+		},
+	});
+
+	const backdropRef = React.useRef<HTMLDivElement | null>(null);
+	const internalBackdropRef = React.useRef<HTMLDivElement | null>(null);
+	const actionsRef: ContextMenuRootContext['actionsRef'] = React.useRef(null);
+	const positionerRef = React.useRef<HTMLElement | null>(null);
+	const allowMouseUpTriggerRef = React.useRef(true);
+	const initialCursorPointRef = React.useRef<{ x: number; y: number } | null>(null);
+	const id = useId();
+
+	const contextValue: ContextMenuRootContext = React.useMemo(
+		() => ({
+			anchor,
+			setAnchor,
+			actionsRef,
+			backdropRef,
+			internalBackdropRef,
+			positionerRef,
+			allowMouseUpTriggerRef,
+			initialCursorPointRef,
+			rootId: id,
+		}),
+		[anchor, id],
+	);
+
+	return (
+		<ContextMenuRootContext.Provider value={contextValue}>
+			<MenuRootContext.Provider value={undefined}>
+				<Menu.Root {...props} />
+			</MenuRootContext.Provider>
+		</ContextMenuRootContext.Provider>
+	);
+}
+
+export interface ContextMenuRootState {}
+
+export interface ContextMenuRootProps extends Omit<
+	Menu.Root.Props,
+	// Context Menu has no detached-trigger support (it opens from a right-click/long-press
+	// area, not a registered trigger), so these inherited props are not applicable.
+	| 'handle'
+	| 'triggerId'
+	| 'defaultTriggerId'
+	| 'modal'
+	| 'openOnHover'
+	| 'delay'
+	| 'closeDelay'
+	| 'closeParentOnEsc'
+	| 'onOpenChange'
+	// Context Menu opens from a pointer position rather than a registered trigger, so the
+	// render-function form of `children` (which receives the active trigger's payload) is not applicable.
+	| 'children'
+> {
+	/**
+	 * Event handler called when the menu is opened or closed.
+	 */
+	onOpenChange?:
+		((open: boolean, eventDetails: ContextMenuRoot.ChangeEventDetails) => void) | undefined;
+	/**
+	 * @ignore
+	 * @deprecated This prop has no effect on Context Menu.
+	 */
+	closeParentOnEsc?: Menu.Root.Props['closeParentOnEsc'] | undefined;
+	children?: React.OctaneNode | undefined;
+}
+
+export type ContextMenuRootActions = MenuRoot.Actions;
+export type ContextMenuRootChangeEventReason = MenuRoot.ChangeEventReason;
+export type ContextMenuRootChangeEventDetails =
+	BaseUIChangeEventDetails<ContextMenuRoot.ChangeEventReason>;
+
+export namespace ContextMenuRoot {
+	export type State = ContextMenuRootState;
+	export type Props = ContextMenuRootProps;
+	export type Actions = ContextMenuRootActions;
+	export type ChangeEventReason = ContextMenuRootChangeEventReason;
+	export type ChangeEventDetails = ContextMenuRootChangeEventDetails;
+}

package/src/context-menu/root/ContextMenuRootContext.ts

@@ -0,0 +1,34 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import type { ContextMenuRoot } from './ContextMenuRoot.tsrx';
+
+export interface ContextMenuRootContext {
+	anchor: { getBoundingClientRect: () => DOMRect };
+	setAnchor: React.Dispatch<React.SetStateAction<ContextMenuRootContext['anchor']>>;
+	backdropRef: React.RefObject<HTMLDivElement | null>;
+	internalBackdropRef: React.RefObject<HTMLDivElement | null>;
+	actionsRef: React.RefObject<{
+		setOpen: (nextOpen: boolean, eventDetails: ContextMenuRoot.ChangeEventDetails) => void;
+	} | null>;
+	positionerRef: React.RefObject<HTMLElement | null>;
+	allowMouseUpTriggerRef: React.RefObject<boolean>;
+	initialCursorPointRef: React.RefObject<{ x: number; y: number } | null>;
+	rootId: string | undefined;
+}
+
+export const ContextMenuRootContext = React.createContext<ContextMenuRootContext | undefined>(
+	undefined,
+);
+
+export function useContextMenuRootContext(optional: false): ContextMenuRootContext;
+export function useContextMenuRootContext(optional?: true): ContextMenuRootContext | undefined;
+export function useContextMenuRootContext(optional = true) {
+	const context = React.useContext(ContextMenuRootContext);
+	if (context === undefined && !optional) {
+		throw new Error(
+			'Base UI: ContextMenuRootContext is missing. ContextMenu parts must be placed within <ContextMenu.Root>.',
+		);
+	}
+	return context;
+}