@octane-xplat/ui 0.9.0 → 0.10.0

package/src/toast-viewport.web.tsrx

@@ -0,0 +1,240 @@
+import { useEffect, useId, useMemo, useRef } from 'octane';
+import type { ToastEntry, ToastPosition, ToastViewportProps } from './props';
+import { ToastViewportProvider, type ToastViewportContextValue } from './toast-context';
+import {
+	FALLBACK_TOAST_VIEWPORT,
+	dismissToast,
+	registerToastViewport,
+	toastOnViewport,
+	toastStore,
+	toastTiming,
+} from './toast-store';
+
+import { useStore } from './use-store.web.tsrx';
+import { applyThemeClasses } from './theme/theme-scheme';
+import { cx } from './cx';
+import { ToastSurface } from './Toast.web.tsrx';
+import { Popover } from './Popover.web.tsrx';
+
+const POSITIONS: ToastPosition[] = ['topStart', 'topEnd', 'bottomStart', 'bottomEnd'];
+
+const FOCUSABLE =
+	'button, a[href], input, select, textarea, [tabindex]:not([tabindex="-1"]), [role="button"], [role="link"]';
+
+const firstFocusable = (container: HTMLElement | null): HTMLElement | null => {
+	if (!container) return null;
+	for (const el of container.querySelectorAll<HTMLElement>(FOCUSABLE)) {
+		if (el.hasAttribute('disabled') || el.getAttribute('aria-disabled') === 'true') continue;
+		return el;
+	}
+
+	return null;
+};
+
+const positionOf = (entry: ToastEntry, fallback: ToastPosition): ToastPosition =>
+	entry.options.position ?? fallback;
+
+/** The toast stack for one viewport id — the fixed, top-layer container
+ *  holding a column per occupied edge. Shared by `ToastViewport` and the
+ *  auto-mounted fallback stack (`showToast` without a provider). */
+export function ToastViewportSurface(props: {
+	viewportId: string;
+	position: ToastPosition;
+	maxVisible: number;
+	inset?: ToastViewportProps['inset'];
+	isTopLayer?: boolean;
+}) @{
+	const entries = useStore(toastStore);
+	const mine = entries.filter((e) => toastOnViewport(e, props.viewportId));
+	const viewport = useRef<HTMLDivElement | null>(null);
+	const prevFocus = useRef<HTMLElement | null>(null);
+	const announced = useRef<string | null>(null);
+	const livePolite = useRef<HTMLDivElement | null>(null);
+	const liveAssertive = useRef<HTMLDivElement | null>(null);
+	const themeDetach = useRef<(() => void) | undefined>(undefined);
+
+	// The fallback stack mounts on a detached container — mirror the app's
+	// theme attrs onto it so scoped theme CSS resolves (MutationObserver
+	// keeps it live). Mounted viewports inherit the tree's theme already.
+	useEffect(() => {
+		const el = viewport.current;
+		if (!el) return;
+		themeDetach.current = applyThemeClasses(el, 'vx-toast-viewport');
+		return () => themeDetach.current?.();
+	}, []);
+
+	// Top-layer promotion (above <dialog> modals) via popover=manual.
+	useEffect(() => {
+		const el = viewport.current;
+		if (!el || props.isTopLayer === false) return;
+		if (typeof (el as any).showPopover === 'function') {
+			try {
+				(el as any).showPopover();
+			} catch {
+				/* already showing */
+			}
+		}
+	}, [props.isTopLayer]);
+
+	// Announce the newest toast through the persistent live regions — the
+	// per-toast role regions are born with content, which many screen
+	// readers skip; mutating a mounted empty region is what announces.
+	// String bodies announce; structured content does not (documented).
+	useEffect(() => {
+		const newest = mine[mine.length - 1];
+		if (!newest || newest.id === announced.current) return;
+		announced.current = newest.id;
+		const body = newest.options.body;
+		if (typeof body !== 'string' || !body) return;
+		const region = (newest.options.type ?? 'info') === 'error' ? liveAssertive.current : livePolite.current;
+		if (region) region.textContent = body;
+	}, [mine]);
+
+	// F6 jumps focus into the stack (standard "go to notifications" jump);
+	// non-modal toasts let it leave naturally. Restore it when the last
+	// toast exits so focus never falls to <body>.
+	useEffect(() => {
+		if (!mine.length) {
+			const prev = prevFocus.current;
+			const el = viewport.current;
+			const active = document.activeElement as HTMLElement | null;
+			if (prev && el && active && el.contains(active)) {
+				prevFocus.current = null;
+				if (prev.isConnected) prev.focus({ preventScroll: true });
+			}
+
+			return;
+		}
+
+		const onKey = (event: KeyboardEvent) => {
+			if (event.key !== 'F6') return;
+			const el = viewport.current;
+			if (!el) return;
+			const active = document.activeElement;
+			if (active instanceof Node && el.contains(active)) return;
+			event.preventDefault();
+			if (active instanceof HTMLElement) prevFocus.current = active;
+			const toasts = el.querySelectorAll<HTMLElement>('[data-toast-id]');
+			const newestToast = toasts[toasts.length - 1] ?? null;
+			(firstFocusable(newestToast) ?? newestToast ?? el).focus?.();
+		};
+
+		document.addEventListener('keydown', onKey);
+		return () => document.removeEventListener('keydown', onKey);
+	}, [mine.length]);
+
+	// Anchored toasts bypass the edge stack — a Popover positions them
+	// against their anchor view (xplat extension, `options.anchor`).
+	const anchored = mine.filter((e) => e.options.anchor != null);
+	const stacked = mine.filter((e) => e.options.anchor == null);
+	const buckets = POSITIONS.map((pos) =>
+		stacked.filter((e) => positionOf(e, props.position) === pos).slice(-props.maxVisible),
+	);
+
+	const insetStyle: Record<string, any> = {};
+	if (props.inset?.top != null) insetStyle.top = props.inset.top;
+	if (props.inset?.bottom != null) insetStyle.bottom = props.inset.bottom;
+	if (props.inset?.start != null) insetStyle.insetInlineStart = props.inset.start;
+	if (props.inset?.end != null) insetStyle.insetInlineEnd = props.inset.end;
+
+	return (
+		<div
+			ref={viewport}
+			className="vx-toast-viewport"
+			style={insetStyle}
+			role={mine.length ? 'region' : undefined}
+			aria-label={mine.length ? 'Notifications' : undefined}
+			tabIndex={mine.length ? -1 : undefined}
+			{...(props.isTopLayer === false ? {} : { popover: 'manual' as any })}
+		>
+			{POSITIONS.map((pos, i) => {
+				const list = buckets[i];
+				if (!list.length) return null;
+				return (
+					<div
+						key={pos}
+						className={cx(
+							'vx-toast-stack',
+							`vx-toast-stack--${pos[0] === 't' ? 'top' : 'bottom'}`,
+							pos.endsWith('Start') ? 'vx-toast-stack--start' : 'vx-toast-stack--end',
+						)}
+					>
+						{list.map((entry) => {
+							const o = entry.options;
+							const timing = toastTiming(o);
+							return (
+								<div
+									key={entry.id}
+									data-toast-id={entry.id}
+									className={cx('vx-toast-row', entry.exiting && 'vx-toast-row--exiting')}
+								>
+									<ToastSurface
+										type={o.type ?? 'info'}
+										body={o.body}
+										endContent={o.endContent}
+										isAutoHide={timing.isAutoHide}
+										autoHideDuration={timing.autoHideDuration}
+										isExiting={entry.exiting}
+										renderContent={o.renderContent}
+										onDismiss={(reason) => dismissToast(entry.id, reason)}
+									/>
+								</div>
+							);
+						})}
+					</div>
+				);
+			})}
+			<div ref={livePolite} className="vx-toast-live" aria-live="polite" role="status" />
+			<div ref={liveAssertive} className="vx-toast-live" aria-live="assertive" role="alert" />
+			{anchored.map((entry) => {
+				const o = entry.options;
+				const timing = toastTiming(o);
+				return (
+					<Popover
+						key={entry.id}
+						open={!entry.exiting}
+						anchor={o.anchor!}
+						placement={o.placement ?? (positionOf(entry, props.position).startsWith('top') ? 'top' : 'bottom')}
+						dismissOnOutsideTap={false}
+						web={{ 'data-toast-id': entry.id }}
+					>
+						<ToastSurface
+							type={o.type ?? 'info'}
+							body={o.body}
+							endContent={o.endContent}
+							isAutoHide={timing.isAutoHide}
+							autoHideDuration={timing.autoHideDuration}
+							isExiting={entry.exiting}
+							renderContent={o.renderContent}
+							onDismiss={(reason) => dismissToast(entry.id, reason)}
+						/>
+					</Popover>
+				);
+			})}
+		</div>
+	);
+}
+
+/** Toast stack container (Astryx `ToastViewport`), web leaf. Provides the
+ *  context `useToast` routes through and renders its own fixed stack;
+ *  toasts pushed unscoped land on the auto-mounted fallback stack. */
+export function ToastViewport(props: ToastViewportProps) @{
+	const id = useId();
+	const ctx = useMemo<ToastViewportContextValue>(
+		() => ({ id, position: props.position ?? 'bottomEnd', maxVisible: props.maxVisible ?? 5 }),
+		[id, props.position, props.maxVisible],
+	);
+
+	useEffect(() => registerToastViewport(id), [id]);
+
+	<ToastViewportProvider value={ctx}>
+		{props.children}
+		<ToastViewportSurface
+			viewportId={id}
+			position={ctx.position}
+			maxVisible={ctx.maxVisible}
+			inset={props.inset}
+			isTopLayer={props.isTopLayer}
+		/>
+	</ToastViewportProvider>
+}

package/src/toggle-button-group-context.ts

@@ -0,0 +1,21 @@
+import { createContext, useContext } from 'octane'
+import type { FieldControlSize } from './props'
+
+export interface ToggleButtonGroupContextValue {
+	/** Currently pressed member values. */
+	selectedValues: Set<string>
+	/** Toggle a member value on/off — applies single/multiple policy. */
+	toggle: (value: string) => void
+	/** Group default size; members may override. */
+	size?: FieldControlSize
+	isDisabled?: boolean
+}
+
+export const ToggleButtonGroupContext: any = createContext<ToggleButtonGroupContextValue | null>(
+	null,
+)
+
+/** ToggleButton reads group membership here; null outside a group. */
+export function useToggleButtonGroup(): ToggleButtonGroupContextValue | null {
+	return useContext(ToggleButtonGroupContext)
+}

package/src/translate.web.ts

@@ -2,7 +2,7 @@ import type { SetTranslate } from './props'
 import { writeTransformProp } from './transform.web'
 
 /** Imperative translate write on a bound view — the gesture seam. Called
- *  per frame from pan handlers (docs/animation-gestures.md: animation
+ *  per frame from pan handlers (docs/app/animation-gestures.md: animation
  *  writes imperative, state stays declarative). Composes with other
  *  transform writes on the same element via ./transform.web. */
 export const setTranslate: SetTranslate = (el, x = 0, y = 0) => {

package/src/typeahead-source.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import { characterCount, createStaticSource, groupTypeaheadItems } from './typeahead-source'
+
+describe('Typeahead search source', () => {
+	it('matches labels and optional keywords case-insensitively', () => {
+		const items = [
+			{ id: 'nyc', label: 'New York' },
+			{ id: 'sfo', label: 'San Francisco' },
+		]
+
+		const source = createStaticSource(items, { keywords: (item) => [item.id] })
+
+		expect(source.search('  YORK ')).toEqual([items[0]])
+		expect(source.search('SFO')).toEqual([items[1]])
+		expect(source.search('')).toEqual(items)
+		expect(source.bootstrap()).toEqual(items)
+	})
+
+	it('counts grapheme clusters and groups results in stable order', () => {
+		const items = [
+			{ id: 'u', label: 'Other' },
+			{ id: 'a', label: 'A', auxiliaryData: { group: 'First' } },
+			{ id: 'b', label: 'B', auxiliaryData: { group: 'Second' } },
+			{ id: 'c', label: 'C', auxiliaryData: { group: 'First' } },
+		]
+
+		expect(characterCount('👨‍👩‍👧‍👦')).toBe(1)
+		expect(groupTypeaheadItems(items, { ungroupedFirst: true })).toEqual([
+			{ heading: null, items: [items[0]] },
+			{ heading: 'First', items: [items[1], items[3]] },
+			{ heading: 'Second', items: [items[2]] },
+		])
+	})
+})

package/src/typeahead-source.ts

@@ -0,0 +1,99 @@
+import type { CreateStaticSourceOptions, SearchableItem, SearchSource } from './props'
+
+/** Create a SearchSource from a static item array — substring match on
+ *  `label` plus optional `keywords`. For fuzzy/ranked/server-side matching
+ *  implement `SearchSource` directly. */
+export function createStaticSource<T extends SearchableItem>(
+	items: T[],
+	options?: CreateStaticSourceOptions<T>,
+): SearchSource<T> {
+	const getKeywords = options?.keywords
+	return {
+		search(query: string): T[] {
+			const lower = query.toLowerCase().trim()
+			if (lower === '') {
+				return items
+			}
+
+			return items.filter((item) => {
+				if (item.label.toLowerCase().includes(lower)) {
+					return true
+				}
+
+				return getKeywords
+					? getKeywords(item).some((kw) => kw.toLowerCase().includes(lower))
+					: false
+			})
+		},
+		bootstrap(): T[] {
+			return items
+		},
+	}
+}
+
+/** User-perceived character count — one emoji/flag/accented grapheme counts
+ *  once. `minQueryLength` is measured in these, not UTF-16 code units. */
+export function characterCount(str: string): number {
+	if (str === '') {
+		return 0
+	}
+
+	const Segmenter = (Intl as any).Segmenter
+	if (typeof Segmenter === 'function') {
+		const segmenter = new Segmenter(undefined, { granularity: 'grapheme' })
+		let count = 0
+		for (const _ of segmenter.segment(str)) {
+			count++
+		}
+
+		return count
+	}
+
+	// Code-point fallback: keeps surrogate pairs whole on runtimes without
+	// Intl.Segmenter (older JSC); joined emoji sequences may over-count.
+	return [...str].length
+}
+
+/** An item's group heading, read from `auxiliaryData.group`. */
+export function getItemGroup(item: SearchableItem): string | undefined {
+	const aux = item.auxiliaryData as Record<string, unknown> | undefined
+	return typeof aux?.group === 'string' ? aux.group : undefined
+}
+
+export interface TypeaheadItemGroup<T extends SearchableItem = SearchableItem> {
+	heading: string | null
+	items: T[]
+}
+
+/** Group results by `auxiliaryData.group`, preserving insertion order.
+ *  Ungrouped items collect into a `heading: null` group; `ungroupedFirst`
+ *  places it before the named groups. No groups → one `heading: null` group. */
+export function groupTypeaheadItems<T extends SearchableItem>(
+	items: T[],
+	{ ungroupedFirst = false }: { ungroupedFirst?: boolean } = {},
+): TypeaheadItemGroup<T>[] {
+	if (!items.some((item) => getItemGroup(item) != null)) {
+		return [{ heading: null, items }]
+	}
+
+	const order: string[] = []
+	const groups = new Map<string, T[]>()
+	const ungrouped: T[] = []
+	for (const item of items) {
+		const group = getItemGroup(item)
+		if (group != null) {
+			if (!groups.has(group)) {
+				order.push(group)
+				groups.set(group, [])
+			}
+
+			groups.get(group)?.push(item)
+		} else {
+			ungrouped.push(item)
+		}
+	}
+
+	const named = order.map((heading) => ({ heading, items: groups.get(heading) ?? [] }))
+	const tail = ungrouped.length > 0 ? [{ heading: null, items: ungrouped }] : []
+	return ungroupedFirst ? [...tail, ...named] : [...named, ...tail]
+}

package/src/unsupported.macos.tsrx

@@ -1,4 +1,4 @@
-/** @jsxImportSource @xplat/macos/renderer */
+/** @jsxImportSource @octane-xplat/macos-renderer */
 
 export function Unsupported(_props: any) @{
 	<label className="vx-unsupported">Unsupported by the AppKit host</label>

package/src/use-hover-card.mobile.tsrx

@@ -0,0 +1,126 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useCallback, useRef, useState } from 'octane';
+import type { HoverCardOptions, HoverCardReturn } from './props';
+import { useLayer } from './use-layer';
+import { cx } from './cx';
+
+/**
+ * Touch-leaf of the hover card hook. There is no hover or focus traversal
+ * on touch platforms, so `delay`/`hideDelay`/`focusTrigger` are inert;
+ * `touchTrigger` drives a tap on the interaction element. 'auto' cannot
+ * detect an action trigger on native — it behaves as 'tap' (documented
+ * deviation). The card dismisses on an outside tap (or Escape-equivalent
+ * platform back through the popover's own dismissal).
+ */
+export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn @{
+	const isEnabled = options.isEnabled ?? true;
+	const touchTrigger = options.touchTrigger ?? 'auto';
+	const controlled = options.isOpen !== undefined;
+	const [uncontrolled, setUncontrolled] = useState(options.isDefaultOpen === true);
+	const open = controlled ? options.isOpen === true : uncontrolled;
+
+	const positionEl = useRef<any>(null);
+	const interactionEl = useRef<any>(null);
+
+	const onShow = useRef(options.onShow);
+	onShow.current = options.onShow;
+	const onHide = useRef(options.onHide);
+	onHide.current = options.onHide;
+
+	const show = useCallback(() => {
+		if (!isEnabled) return;
+		if (!controlled) setUncontrolled(true);
+		onShow.current?.();
+	}, [isEnabled, controlled]);
+
+	const hide = useCallback(() => {
+		if (controlled) {
+			onHide.current?.();
+			return;
+		}
+
+		setUncontrolled(false);
+		onHide.current?.();
+	}, [controlled]);
+
+	const detachTap = useRef<(() => void) | null>(null);
+	const interactionRef = useCallback(
+		(el: any) => {
+			detachTap.current?.();
+			detachTap.current = null;
+			interactionEl.current = el;
+			if (!el?.on || touchTrigger === 'none' || !isEnabled) {
+				return;
+			}
+
+			const handler = () => {
+				if (controlled) {
+					// Report only — the consumer's isOpen update decides.
+					if (options.isOpen) {
+						onHide.current?.();
+					} else {
+						onShow.current?.();
+					}
+
+					return;
+				}
+
+				setUncontrolled((v) => {
+					if (v) {
+						onHide.current?.();
+					} else {
+						onShow.current?.();
+					}
+
+					return !v;
+				});
+			};
+
+			el.on('tap', handler);
+			detachTap.current = () => el.off?.('tap', handler);
+		},
+		[isEnabled, touchTrigger, controlled, options.isOpen],
+	);
+
+	const layer = useLayer({ mode: 'context', isOpen: open, lightDismiss: true, dismissOnEscape: true, onHide: hide });
+	const id = layer.id;
+
+	const positionRef = useCallback((el: any) => {
+		positionEl.current = el;
+		layer.ref(el);
+	}, [layer.ref]);
+
+	const ref = useCallback(
+		(el: any) => {
+			positionRef(el);
+			interactionRef(el);
+		},
+		[positionRef, interactionRef],
+	);
+
+
+	const renderHoverCard = useCallback((children: any, props?: Record<string, any>) => { return layer.render(
+		<flexboxlayout
+						flexDirection="column"
+						className="vx-hovercard-content"
+						accessibilityLabel={options.label}
+					>
+						{children}
+					</flexboxlayout>,
+		{ placement: props?.placement ?? options.placement ?? 'above', alignment: props?.alignment ?? options.alignment ?? 'center', offset: 8,
+			className: cx('vx-hovercard', props?.className), style: props?.style },
+	); }, [layer.render, options.placement, options.alignment, options.label]);
+
+	return {
+		ref,
+		positionRef,
+		interactionRef,
+		anchorId: layer.anchorId,
+		id,
+		describedBy: id,
+		isOpen: open,
+		renderHoverCard,
+		show,
+		hide,
+	};
+}

package/src/use-hover-card.tsrx

@@ -0,0 +1,153 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useLayer } from './use-layer';
+import { useCallback, useEffect, useRef, useState } from 'octane';
+import type { HoverCardOptions, HoverCardReturn } from './props';
+import { cx } from './cx';
+
+const host = () => (globalThis as any).__xplatAppKit ?? {};
+
+function HoverCardPanel(props: { body: any; enter: () => void; exit: () => void }) @{
+	const view = useRef<any>(null);
+	useEffect(() => host().observeHover?.(view.current, { enter: props.enter, exit: props.exit }), [props.enter, props.exit]);
+
+	<flexboxlayout ref={view} flexDirection="column" className="vx-hovercard-content">{props.body}</flexboxlayout>
+}
+
+/**
+ * Default (macOS) leaf of the hover-card hook — the AppKit host bridge
+ * supplies real pointer intent (`observeHover` tracking areas) and the
+ * card mounts through the in-window useLayer primitive
+ * in its own root. iOS/Android resolve the
+ * `.mobile` leaf instead.
+ */
+export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn @{
+	const isEnabled = options.isEnabled ?? true;
+	const delay = Math.max(0, options.delay ?? 300);
+	const hideDelay = Math.max(0, options.hideDelay ?? 200);
+	const controlled = options.isOpen !== undefined;
+	const [uncontrolled, setUncontrolled] = useState(options.isDefaultOpen === true);
+	const open = controlled ? options.isOpen === true : uncontrolled;
+
+	const positionEl = useRef<any>(null);
+	const interactionEl = useRef<any>(null);
+	const detachHover = useRef<(() => void) | null>(null);
+
+
+
+	const openTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const onShow = useRef(options.onShow);
+	onShow.current = options.onShow;
+	const onHide = useRef(options.onHide);
+	onHide.current = options.onHide;
+
+	const clearTimers = useCallback(() => {
+		if (openTimer.current) clearTimeout(openTimer.current);
+		if (closeTimer.current) clearTimeout(closeTimer.current);
+		openTimer.current = null;
+		closeTimer.current = null;
+	}, []);
+
+	const requestedShow = useRef(false);
+	const closeNow = useCallback(() => {
+		clearTimers();
+		if (!controlled) setUncontrolled(false);
+		onHide.current?.();
+	}, [clearTimers, controlled]);
+
+	const openNow = useCallback(() => {
+		if (!isEnabled || open || !positionEl.current || typeof host().showLayer !== 'function') return;
+		requestedShow.current = true;
+		if (!controlled) setUncontrolled(true);
+		onShow.current?.();
+	}, [isEnabled, controlled, open]);
+
+	const layer = useLayer({ mode: 'context', isOpen: open && isEnabled, dismissOnEscape: true, lightDismiss: true, onHide: closeNow });
+	const id = layer.id;
+	const scheduleShow = useCallback(() => {
+		if (!isEnabled || options.isOpen === false) return;
+		clearTimers();
+		openTimer.current = setTimeout(() => {
+			openTimer.current = null;
+			openNow();
+		}, delay);
+	}, [isEnabled, options.isOpen, clearTimers, openNow, delay]);
+
+	const scheduleHide = useCallback(() => {
+		if (options.isOpen === true) return;
+		clearTimers();
+		closeTimer.current = setTimeout(() => {
+			closeTimer.current = null;
+			closeNow();
+		}, hideDelay);
+	}, [options.isOpen, clearTimers, hideDelay, closeNow]);
+
+	const scheduleCardHide = useCallback(() => {
+		clearTimers();
+		closeTimer.current = setTimeout(closeNow, hideDelay);
+	}, [clearTimers, closeNow, hideDelay]);
+
+	const positionRef = useCallback((el: any) => {
+		positionEl.current = el;
+		layer.ref(el);
+	}, [layer.ref]);
+
+	const interactionRef = useCallback(
+		(el: any) => {
+			detachHover.current?.();
+			detachHover.current = null;
+			interactionEl.current = el;
+			if (!el || !isEnabled) return;
+			const observe = host().observeHover;
+			if (typeof observe !== 'function') return;
+			detachHover.current = observe(el, {
+				enter: scheduleShow,
+				exit: () => {
+					if (openTimer.current) {
+						clearTimeout(openTimer.current);
+						openTimer.current = null;
+					}
+
+					scheduleHide();
+				},
+			});
+		},
+		[isEnabled, scheduleShow, scheduleHide],
+	);
+
+	const ref = useCallback(
+		(el: any) => {
+			positionRef(el);
+			interactionRef(el);
+		},
+		[positionRef, interactionRef],
+	);
+
+	useEffect(() => {
+		if (open && isEnabled && typeof host().showLayer === 'function') {
+			if (!requestedShow.current) onShow.current?.();
+			requestedShow.current = false;
+		}
+	}, [open, isEnabled]);
+
+	useEffect(() => { if (options.isOpen === false) clearTimers(); }, [options.isOpen, clearTimers]);
+	useEffect(() => () => { clearTimers(); detachHover.current?.(); }, [clearTimers]);
+	const renderHoverCard = useCallback((children: any, props?: Record<string, any>) => { return layer.render(
+		<HoverCardPanel body={children} enter={clearTimers} exit={scheduleCardHide} />,
+		{ placement: props?.placement ?? options.placement ?? 'above', alignment: props?.alignment ?? options.alignment ?? 'center', offset: 8,
+			className: cx('vx-hovercard', props?.className), style: props?.style, accessibilityLabel: options.label },
+	); }, [layer.render, options.placement, options.alignment, options.label, scheduleCardHide, clearTimers]);
+
+	return {
+		ref,
+		positionRef,
+		interactionRef,
+		anchorId: layer.anchorId,
+		id,
+		describedBy: id,
+		isOpen: open,
+		renderHoverCard,
+		show: openNow,
+		hide: closeNow,
+	};
+}