@octanejs/base-ui 0.1.14 → 0.1.16

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

@@ -0,0 +1,101 @@
+// Ported from .base-ui/packages/react/src/unstable-use-media-query/index.ts (v1.6.0).
+// Subscribes to a CSS media query via `window.matchMedia`, with SSR escape hatches.
+//
+// octane adaptation: octane ships `useSyncExternalStore` natively, so Base UI's
+// `use-sync-external-store/shim` import is dropped; the dev-only `useDebugValue` call is
+// dropped with the rest of the dev-warning surface.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useCallback, useMemo, useSyncExternalStore } from 'octane';
+
+import { S, splitSlot, subSlot } from './internal';
+import { addEventListener } from './utils/addEventListener';
+
+export interface UseMediaQueryOptions {
+	/**
+	 * As `window.matchMedia()` is unavailable on the server, it returns a default match
+	 * 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;
+	/** Your own implementation of `matchMedia`, used when rendering server-side. */
+	ssrMatchMedia?: ((query: string) => { matches: boolean }) | undefined;
+}
+
+export function useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean;
+export function useMediaQuery(...args: any[]): boolean {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useMediaQuery');
+
+	const rawQuery = user[0] as string;
+	const options = (user[1] as UseMediaQueryOptions | undefined) ?? {};
+
+	// Wait for jsdom to support the match media feature. All the browsers Base UI supports
+	// have this built-in; this defensive check is here for simplicity.
+	const supportMatchMedia =
+		typeof window !== 'undefined' && typeof window.matchMedia !== 'undefined';
+
+	const normalizedQuery = rawQuery.replace(/^@media( ?)/m, '');
+
+	const {
+		defaultMatches = false,
+		matchMedia = supportMatchMedia ? window.matchMedia : null,
+		ssrMatchMedia = null,
+		noSsr = false,
+	} = options;
+
+	const getDefaultSnapshot = useCallback(
+		() => defaultMatches,
+		[defaultMatches],
+		subSlot(slot, 'def'),
+	);
+
+	const getServerSnapshot = useMemo(
+		() => {
+			if (noSsr && matchMedia) {
+				return () => matchMedia(normalizedQuery).matches;
+			}
+			if (ssrMatchMedia !== null) {
+				const { matches } = ssrMatchMedia(normalizedQuery);
+				return () => matches;
+			}
+			return getDefaultSnapshot;
+		},
+		[getDefaultSnapshot, normalizedQuery, ssrMatchMedia, noSsr, matchMedia],
+		subSlot(slot, 'srv'),
+	);
+
+	const [getSnapshot, subscribe] = useMemo(
+		() => {
+			if (matchMedia === null) {
+				return [getDefaultSnapshot, () => () => {}] as const;
+			}
+			const mediaQueryList = matchMedia(normalizedQuery);
+			return [
+				() => mediaQueryList.matches,
+				(notify: () => void) => addEventListener(mediaQueryList, 'change', notify),
+			] as const;
+		},
+		[getDefaultSnapshot, matchMedia, normalizedQuery],
+		subSlot(slot, 'sub'),
+	);
+
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot, subSlot(slot, 'store'));
+}
+
+export namespace useMediaQuery {
+	export type Options = UseMediaQueryOptions;
+}

package/src/utils/CSPContext.ts

@@ -0,0 +1,21 @@
+// Ported from .base-ui/packages/react/src/internals/csp-context/CSPContext.tsx (v1.6.0).
+// Carries the Content Security Policy configuration for components that need inline
+// `<style>` tags — the `nonce` to stamp on them, and whether to skip them entirely.
+import { createContext, useContext } from 'octane';
+
+export interface CSPContextValue {
+	nonce?: string | undefined;
+	disableStyleElements?: boolean | undefined;
+}
+
+export const CSPContext = createContext<CSPContextValue | undefined>(undefined);
+
+const DEFAULT_CSP_CONTEXT_VALUE: CSPContextValue = {
+	disableStyleElements: false,
+};
+
+export function useCSPContext(...args: any[]): CSPContextValue {
+	// `useContext` is slot-exempt in octane, so the caller's slot (if any) is ignored.
+	void args;
+	return useContext(CSPContext) ?? DEFAULT_CSP_CONTEXT_VALUE;
+}

package/src/utils/ContextMenuRootContext.ts

@@ -0,0 +1,44 @@
+// Ported from .base-ui/packages/react/src/context-menu/root/ContextMenuRootContext.ts (v1.6.0),
+// octane-adapted (`React.createContext` → octane `createContext`; `React.RefObject` → plain ref
+// shapes; `React.Dispatch<SetStateAction<T>>` → octane's updater signature).
+//
+// STAGING: only the CONTEXT lands here, ahead of the `ContextMenu` components themselves
+// (Phase 3f stage 4). `Menu.Root`/`Menu.Trigger`/`Menu.Positioner`/`Menu.Popup` branch on
+// `parent.type === 'context-menu'` in several places; having the context now lets those branches
+// be transcribed verbatim instead of being stubbed out and re-added later. Until `ContextMenu.Root`
+// lands nothing provides this context, so `useContextMenuRootContext()` always returns `undefined`.
+import { createContext, useContext } from 'octane';
+
+export interface ContextMenuRootContextValue {
+	anchor: { getBoundingClientRect: () => DOMRect };
+	setAnchor: (value: ContextMenuRootContextValue['anchor']) => void;
+	backdropRef: { current: HTMLDivElement | null };
+	internalBackdropRef: { current: HTMLDivElement | null };
+	actionsRef: {
+		current: {
+			setOpen: (nextOpen: boolean, eventDetails: any) => void;
+		} | null;
+	};
+	positionerRef: { current: HTMLElement | null };
+	allowMouseUpTriggerRef: { current: boolean };
+	initialCursorPointRef: { current: { x: number; y: number } | null };
+	rootId: string | undefined;
+}
+
+export const ContextMenuRootContext = createContext<ContextMenuRootContextValue | undefined>(
+	undefined,
+);
+
+export function useContextMenuRootContext(optional: false): ContextMenuRootContextValue;
+export function useContextMenuRootContext(optional?: true): ContextMenuRootContextValue | undefined;
+export function useContextMenuRootContext(
+	optional = true,
+): ContextMenuRootContextValue | undefined {
+	const context = useContext(ContextMenuRootContext);
+	if (context === undefined && !optional) {
+		throw new Error(
+			'Base UI: ContextMenuRootContext is missing. ContextMenu parts must be placed within <ContextMenu.Root>.',
+		);
+	}
+	return context;
+}

package/src/utils/FloatingPortalLite.ts

@@ -0,0 +1,29 @@
+// Ported from .base-ui/packages/react/src/utils/FloatingPortalLite.tsx (v1.6.0). `FloatingPortal`
+// also carries the tabbable/focus-guard machinery; components that don't need it (Tooltip,
+// PreviewCard, Toast) use this thinner variant, which only creates the portal node and renders the
+// children into it.
+//
+// octane adaptations: forwardRef → ref-as-prop; `createElement` instead of JSX; `ReactDOM`'s
+// `createPortal` → octane's.
+import { createElement, createPortal, Fragment } from 'octane';
+
+import { S, subSlot } from '../internal';
+import { useFloatingPortalNode } from './floating/FloatingPortal';
+
+export function FloatingPortalLite(componentProps: any): any {
+	const slot = S('FloatingPortalLite');
+	const { children, container, className, render, style, ref, ...elementProps } = componentProps;
+
+	const { portalNode, portalSubtree } = useFloatingPortalNode(
+		{ container, ref, componentProps: { render, className, style }, elementProps },
+		subSlot(slot, 'node'),
+	);
+
+	if (!portalSubtree && !portalNode) {
+		return null;
+	}
+
+	return createElement(Fragment, {
+		children: [portalSubtree, portalNode ? createPortal(children, portalNode) : null],
+	});
+}

package/src/utils/MenubarContext.ts

@@ -0,0 +1,38 @@
+// Ported from .base-ui/packages/react/src/menubar/MenubarContext.ts (v1.6.0), octane-adapted
+// (`React.createContext` → octane `createContext`; `React.RefObject` → a plain ref shape).
+//
+// STAGING: only the CONTEXT lands here, ahead of the `Menubar` component itself (Phase 3f stage 4).
+// `Menu.Root`/`Menu.Trigger`/`Menu.Positioner` branch on `parent.type === 'menubar'` in several
+// places; having the context now lets those branches be transcribed verbatim instead of being
+// stubbed out and re-added later. Until `Menubar` lands nothing provides this context, so
+// `useMenubarContext(true)` always returns `null`.
+import { createContext, useContext } from 'octane';
+
+import type { MenuRootOrientation } from '../menu';
+
+export interface MenubarContextValue {
+	modal: boolean;
+	disabled: boolean;
+	contentElement: HTMLElement | null;
+	setContentElement: (element: HTMLElement | null) => void;
+	hasSubmenuOpen: boolean;
+	setHasSubmenuOpen: (open: boolean) => void;
+	orientation: MenuRootOrientation;
+	allowMouseUpTriggerRef: { current: boolean };
+	rootId: string | undefined;
+}
+
+export const MenubarContext = createContext<MenubarContextValue | null>(null);
+
+export function useMenubarContext(optional?: false): MenubarContextValue;
+export function useMenubarContext(optional: true): MenubarContextValue | null;
+export function useMenubarContext(optional?: boolean): MenubarContextValue | null {
+	const context = useContext(MenubarContext);
+	if (context === null && !optional) {
+		throw new Error(
+			'Base UI: MenubarContext is missing. Menubar parts must be placed within <Menubar>.',
+		);
+	}
+
+	return context;
+}

package/src/utils/RequestQueue.ts

@@ -0,0 +1,132 @@
+// Ported from .base-ui/packages/react/src/internals/RequestQueue.ts (v1.6.0). Manages concurrent
+// fetching with a queue: tracks each key's lifecycle through queued → pending and caps the number
+// of in-flight requests so the server is not overwhelmed. Subclasses override `pickEntries` to
+// change the ordering (the default is FIFO).
+//
+// Pure — no renderer API is involved, so this is a straight transcription.
+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/utils/TimeoutManager.ts

@@ -0,0 +1,32 @@
+// Ported from .base-ui/packages/react/src/internals/TimeoutManager.ts (v1.6.0). Several keyed
+// timeouts behind one handle, so a caller can start/replace/cancel each independently and drop them
+// all on teardown. Distinct from `utils/useTimeout`'s `Timeout`, which owns exactly one.
+//
+// Pure — no renderer API is involved, so this is a straight transcription.
+export class TimeoutManager {
+	private ids: Map<string, number> = new Map();
+
+	/** Starts `fn` after `delay`, replacing any timeout already running under `key`. */
+	start = (key: string, delay: number, fn: () => void): void => {
+		this.clear(key);
+		const id = setTimeout(() => {
+			this.ids.delete(key);
+			fn();
+		}, delay) as unknown as number;
+
+		this.ids.set(key, id);
+	};
+
+	clear = (key: string): void => {
+		const id = this.ids.get(key);
+		if (id != null) {
+			clearTimeout(id);
+			this.ids.delete(key);
+		}
+	};
+
+	clearAll = (): void => {
+		this.ids.forEach(clearTimeout);
+		this.ids.clear();
+	};
+}