@seed-design/lynx-react 0.7.1 → 0.8.0

package/lib/components/HelpBubble/HelpBubble.d.ts

@@ -0,0 +1,67 @@
+import { HelpBubbleVariantProps } from '@seed-design/lynx-css/recipes/help-bubble';
+import { LynxAccessibilityProps, LynxPressableProps, LynxStyledElementProps, LynxViewProps } from '../../types';
+import { StyleProps } from '../../utils/styled';
+import { Placement } from '../private/Positioning';
+import * as React from "@lynx-js/react";
+type HelpBubblePublicVariantProps = Omit<HelpBubbleVariantProps, "open" | "positioned" | "side" | "pressed">;
+export interface HelpBubbleRootProps extends HelpBubblePublicVariantProps, LynxStyledElementProps {
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** @default "top" */
+    placement?: Placement;
+    /** @default 4 */
+    gutter?: number;
+    /** @default 16 */
+    overflowPadding?: number;
+    /** @default 14 */
+    arrowPadding?: number;
+    /** @default true */
+    flip?: boolean | {
+        fallbackStrategy?: "bestFit" | "initialPlacement";
+        fallbackPlacements?: Placement[];
+    };
+    /** @default true */
+    closeOnInteractOutside?: boolean;
+}
+/**
+ * @platform Lynx
+ *
+ * The native implementation uses fixed positioned views rather than DOM portals.
+ * `closeOnInteractOutside={false}` has no full-screen hit surface, so other native
+ * controls and independently-open HelpBubbles remain interactive.
+ */
+export declare const HelpBubbleRoot: React.ForwardRefExoticComponent<HelpBubbleRootProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleAnchorProps extends LynxStyledElementProps, Pick<LynxViewProps, "bindlayoutchange"> {
+}
+export declare const HelpBubbleAnchor: React.ForwardRefExoticComponent<HelpBubbleAnchorProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleTriggerProps extends LynxStyledElementProps, LynxPressableProps, LynxAccessibilityProps, Pick<LynxViewProps, "bindlayoutchange"> {
+}
+export declare const HelpBubbleTrigger: React.ForwardRefExoticComponent<HelpBubbleTriggerProps & React.RefAttributes<unknown>>;
+export interface HelpBubblePositionerProps extends LynxStyledElementProps {
+    zIndexOffset?: number;
+}
+export declare const HelpBubblePositioner: React.ForwardRefExoticComponent<HelpBubblePositionerProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleContentProps extends Pick<StyleProps, "maxWidth">, LynxStyledElementProps {
+}
+export declare const HelpBubbleContent: React.ForwardRefExoticComponent<HelpBubbleContentProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleArrowProps extends LynxStyledElementProps {
+}
+export declare const HelpBubbleArrow: React.ForwardRefExoticComponent<HelpBubbleArrowProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleArrowTipProps extends LynxStyledElementProps {
+}
+export declare const HelpBubbleArrowTip: React.ForwardRefExoticComponent<HelpBubbleArrowTipProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleBodyProps extends LynxStyledElementProps {
+}
+export declare const HelpBubbleBody: React.ForwardRefExoticComponent<HelpBubbleBodyProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleTitleProps extends LynxStyledElementProps, LynxAccessibilityProps {
+}
+export declare const HelpBubbleTitle: React.ForwardRefExoticComponent<HelpBubbleTitleProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleDescriptionProps extends LynxStyledElementProps, LynxAccessibilityProps {
+}
+export declare const HelpBubbleDescription: React.ForwardRefExoticComponent<HelpBubbleDescriptionProps & React.RefAttributes<unknown>>;
+export interface HelpBubbleCloseButtonProps extends LynxStyledElementProps, LynxPressableProps, LynxAccessibilityProps {
+}
+export declare const HelpBubbleCloseButton: React.ForwardRefExoticComponent<HelpBubbleCloseButtonProps & React.RefAttributes<unknown>>;
+export {};
+//# sourceMappingURL=HelpBubble.d.ts.map

package/lib/components/HelpBubble/HelpBubble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HelpBubble.d.ts","sourceRoot":"","sources":["../../../src/components/HelpBubble/HelpBubble.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,sBAAsB,EAAE,MAAM,2CAA2C,CAAC;AAGpG,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAC;AAKxC,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EAEtB,aAAa,EAEd,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAEL,KAAK,SAAS,EAIf,MAAM,wBAAwB,CAAC;AAIhC,KAAK,4BAA4B,GAAG,IAAI,CACtC,sBAAsB,EACtB,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,CAC3C,CAAC;AAoFF,MAAM,WAAW,mBAAoB,SAAQ,4BAA4B,EAAE,sBAAsB;IAC/F,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC,qBAAqB;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iBAAiB;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB;IACpB,IAAI,CAAC,EACD,OAAO,GACP;QACE,gBAAgB,CAAC,EAAE,SAAS,GAAG,kBAAkB,CAAC;QAClD,kBAAkB,CAAC,EAAE,SAAS,EAAE,CAAC;KAClC,CAAC;IACN,oBAAoB;IACpB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,qFAsLzB,CAAC;AAKH,MAAM,WAAW,qBACf,SAAQ,sBAAsB,EAC5B,IAAI,CAAC,aAAa,EAAE,kBAAkB,CAAC;CAAG;AAE9C,eAAO,MAAM,gBAAgB,uFA8B3B,CAAC;AAKH,MAAM,WAAW,sBACf,SAAQ,sBAAsB,EAC5B,kBAAkB,EAClB,sBAAsB,EACtB,IAAI,CAAC,aAAa,EAAE,kBAAkB,CAAC;CAAG;AAE9C,eAAO,MAAM,iBAAiB,wFAgE5B,CAAC;AAKH,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA8DD,eAAO,MAAM,oBAAoB,2FA+BhC,CAAC;AAKF,MAAM,WAAW,sBACf,SAAQ,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,EAClC,sBAAsB;CAAG;AAE7B,eAAO,MAAM,iBAAiB,wFAyR5B,CAAC;AAKH,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;CAAG;AAEvE,eAAO,MAAM,eAAe,sFAuB1B,CAAC;AAGH,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB;CAAG;AAE1E,eAAO,MAAM,kBAAkB,yFAc9B,CAAC;AAKF,MAAM,WAAW,mBAAoB,SAAQ,sBAAsB;CAAG;AAEtE,eAAO,MAAM,cAAc,qFAWzB,CAAC;AAGH,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB,EAAE,sBAAsB;CAAG;AAE/F,eAAO,MAAM,eAAe,sFAW1B,CAAC;AAGH,MAAM,WAAW,0BACf,SAAQ,sBAAsB,EAC5B,sBAAsB;CAAG;AAE7B,eAAO,MAAM,qBAAqB,4FAajC,CAAC;AAKF,MAAM,WAAW,0BACf,SAAQ,sBAAsB,EAC5B,kBAAkB,EAClB,sBAAsB;CAAG;AAE7B,eAAO,MAAM,qBAAqB,4FAmDjC,CAAC"}

package/lib/components/HelpBubble/HelpBubble.jsx

@@ -0,0 +1,600 @@
+import { useControllableState } from "../../packages/lynx-react-headless/use-controllable-state/lib/index.js";
+import { usePressTap } from "../../packages/lynx-react-headless/use-press-tap/lib/index.js";
+import { mergeProps } from "../../utils/merge-props.js";
+import { createSlotRecipeContext } from "../../utils/create-slot-recipe-context.jsx";
+import { useStyleProps } from "../../utils/styled.js";
+import { computePosition } from "../private/Positioning.js";
+import * as React from "@lynx-js/react";
+import clsx from "clsx";
+import { getRectByRef } from "@lynx-js/lynx-ui-common";
+import { helpBubble } from "@seed-design/lynx-css/recipes/help-bubble";
+//#region src/components/HelpBubble/HelpBubble.tsx
+var { ClassNamesProvider, useClassNames } = createSlotRecipeContext(helpBubble);
+var HelpBubbleContext = React.createContext(null);
+function useHelpBubbleContext(consumer) {
+	const context = React.useContext(HelpBubbleContext);
+	if (!context) throw new Error(`<${consumer}/> must be rendered inside <HelpBubbleRoot/>.`);
+	return context;
+}
+function mergeNodeRef(forwardedRef, node) {
+	if (typeof forwardedRef === "function") forwardedRef(node);
+	else if (forwardedRef) forwardedRef.current = node;
+}
+function toPixel(value) {
+	return `${value}px`;
+}
+function getLayoutSize(event) {
+	const width = event.detail?.width ?? event.params?.width;
+	const height = event.detail?.height ?? event.params?.height;
+	if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+	return {
+		width: Math.max(0, width),
+		height: Math.max(0, height)
+	};
+}
+function hasExitTransition(event) {
+	if (event.target.uid !== event.currentTarget.uid) return false;
+	return event.params.animation_type === "transition-opacity" || event.params.animation_name === "opacity";
+}
+var EXIT_TRANSITION_FALLBACK_MS = 200;
+function getRootRect() {
+	"background only";
+	return getRectByRef({ current: lynx.createSelectorQuery().selectRoot() }, true);
+}
+function areStylesEqual(left, right) {
+	if (left === right) return true;
+	if (!left || !right) return false;
+	const leftEntries = Object.entries(left);
+	if (leftEntries.length !== Object.keys(right).length) return false;
+	return leftEntries.every(([key, value]) => Object.is(value, right[key]));
+}
+/**
+* @platform Lynx
+*
+* The native implementation uses fixed positioned views rather than DOM portals.
+* `closeOnInteractOutside={false}` has no full-screen hit surface, so other native
+* controls and independently-open HelpBubbles remain interactive.
+*/
+var HelpBubbleRoot = React.forwardRef((props, ref) => {
+	const { children, className, style, open: openProp, defaultOpen = false, onOpenChange, placement = "top", gutter = 4, overflowPadding = 16, arrowPadding = 14, flip = true, closeOnInteractOutside = true, ...nativeProps } = props;
+	const [open, setOpen] = useControllableState({
+		value: openProp,
+		defaultValue: defaultOpen
+	});
+	const [mounted, setMounted] = React.useState(open);
+	const [position, setPositionState] = React.useState(null);
+	const [positionedEpoch, setPositionedEpoch] = React.useState(null);
+	const [referenceRect, setReferenceRect] = React.useState(null);
+	const [positionRevision, setPositionRevision] = React.useState(0);
+	const positionRevisionRef = React.useRef(0);
+	const isOpenRef = React.useRef(open);
+	const openEpochRef = React.useRef(0);
+	const anchorRef = React.useRef(null);
+	const triggerRef = React.useRef(null);
+	if (open && !isOpenRef.current) openEpochRef.current += 1;
+	isOpenRef.current = open;
+	const openEpoch = openEpochRef.current;
+	const positioned = positionedEpoch === openEpoch;
+	React.useEffect(() => {
+		"background only";
+		if (open) {
+			setMounted(true);
+			return;
+		}
+		if (!positioned) setMounted(false);
+	}, [open, positioned]);
+	const requestOpen = React.useCallback((nextOpen) => {
+		"background only";
+		if (nextOpen === open) return;
+		setOpen(nextOpen);
+		onOpenChange?.(nextOpen);
+	}, [
+		onOpenChange,
+		open,
+		setOpen
+	]);
+	const finishClose = React.useCallback(() => {
+		"background only";
+		if (!isOpenRef.current) {
+			setMounted(false);
+			setPositionedEpoch(null);
+			setPositionState(null);
+			setReferenceRect(null);
+		}
+	}, []);
+	const setPosition = React.useCallback((nextPosition, nextReferenceRect) => {
+		setPositionState((previous) => {
+			if (previous !== null && nextPosition !== null && previous.left === nextPosition.left && previous.top === nextPosition.top && previous.width === nextPosition.width && previous.height === nextPosition.height && previous.placement === nextPosition.placement && previous.transformOrigin === nextPosition.transformOrigin && previous.availableWidth === nextPosition.availableWidth && previous.availableHeight === nextPosition.availableHeight && previous.arrow?.left === nextPosition.arrow?.left && previous.arrow?.top === nextPosition.arrow?.top && previous.arrow?.centerOffset === nextPosition.arrow?.centerOffset) return previous;
+			return nextPosition;
+		});
+		setReferenceRect((previous) => {
+			if (previous !== null && nextReferenceRect !== null && previous.left === nextReferenceRect.left && previous.top === nextReferenceRect.top && previous.right === nextReferenceRect.right && previous.bottom === nextReferenceRect.bottom && previous.width === nextReferenceRect.width && previous.height === nextReferenceRect.height) return previous;
+			return nextReferenceRect;
+		});
+		setPositionedEpoch(nextPosition ? openEpochRef.current : null);
+	}, []);
+	const resetPosition = React.useCallback(() => {
+		setPositionState(null);
+		setReferenceRect(null);
+		setPositionedEpoch(null);
+	}, []);
+	const requestPositionUpdate = React.useCallback(() => {
+		positionRevisionRef.current += 1;
+		setPositionRevision(positionRevisionRef.current);
+	}, []);
+	const classes = helpBubble({
+		open,
+		positioned,
+		side: position?.placement.split("-")[0],
+		pressed: false
+	});
+	const contextValue = React.useMemo(() => ({
+		open,
+		mounted,
+		positioned,
+		side: position?.placement.split("-")[0] ?? "top",
+		placement,
+		gutter,
+		overflowPadding,
+		arrowPadding,
+		flip,
+		closeOnInteractOutside,
+		openEpoch,
+		isOpenRef,
+		openEpochRef,
+		anchorRef,
+		triggerRef,
+		position,
+		referenceRect,
+		positionRevision,
+		positionRevisionRef,
+		requestOpen,
+		finishClose,
+		setPosition,
+		resetPosition,
+		requestPositionUpdate
+	}), [
+		arrowPadding,
+		closeOnInteractOutside,
+		finishClose,
+		flip,
+		gutter,
+		mounted,
+		open,
+		openEpoch,
+		overflowPadding,
+		placement,
+		position,
+		positioned,
+		requestOpen,
+		resetPosition,
+		setPosition,
+		referenceRect,
+		positionRevisionRef,
+		positionRevision,
+		requestPositionUpdate
+	]);
+	return <HelpBubbleContext.Provider value={contextValue}>
+      <ClassNamesProvider value={classes}>
+        <view {...mergeProps(ref ? { ref } : {}, nativeProps)} className={className} style={style}>
+          {children}
+        </view>
+      </ClassNamesProvider>
+    </HelpBubbleContext.Provider>;
+});
+HelpBubbleRoot.displayName = "HelpBubbleRoot";
+var HelpBubbleAnchor = React.forwardRef((props, ref) => {
+	const { children, className, style, bindlayoutchange, ...nativeProps } = props;
+	const context = useHelpBubbleContext("HelpBubbleAnchor");
+	const handleRef = React.useCallback((node) => {
+		context.anchorRef.current = node;
+		mergeNodeRef(ref, node);
+	}, [context.anchorRef, ref]);
+	const handleLayoutChange = React.useCallback((...args) => {
+		"background only";
+		context.requestPositionUpdate();
+		bindlayoutchange?.(...args);
+	}, [bindlayoutchange, context.requestPositionUpdate]);
+	return <view ref={handleRef} className={className} style={style} bindlayoutchange={handleLayoutChange} {...nativeProps}>
+      {children}
+    </view>;
+});
+HelpBubbleAnchor.displayName = "HelpBubbleAnchor";
+var HelpBubbleTrigger = React.forwardRef((props, ref) => {
+	const { children, className, style, bindtap, bindlayoutchange, "main-thread:bindtap": mainThreadBindtap, "accessibility-element": accessibilityElement = true, "accessibility-label": accessibilityLabel, "accessibility-traits": accessibilityTraits, ...nativeProps } = props;
+	const context = useHelpBubbleContext("HelpBubbleTrigger");
+	const { pressed: _pressed, bindtap: triggerTap, ...pressHandlers } = usePressTap({
+		onTap: React.useCallback((event, instance) => {
+			"background only";
+			context.requestOpen(!context.open);
+			bindtap?.(event, instance);
+		}, [bindtap, context]),
+		mainThreadOnTap: mainThreadBindtap
+	});
+	const handleRef = React.useCallback((node) => {
+		context.triggerRef.current = node;
+		mergeNodeRef(ref, node);
+	}, [context.triggerRef, ref]);
+	const handleLayoutChange = React.useCallback((...args) => {
+		"background only";
+		context.requestPositionUpdate();
+		bindlayoutchange?.(...args);
+	}, [bindlayoutchange, context.requestPositionUpdate]);
+	return <view ref={handleRef} className={className} style={style} accessibility-element={accessibilityElement} accessibility-label={accessibilityLabel} accessibility-role-description="button" accessibility-value={context.open ? "expanded" : "collapsed"} accessibility-traits={accessibilityTraits ?? "button"} {...nativeProps} {...pressHandlers} bindtap={triggerTap} bindlayoutchange={handleLayoutChange}>
+      {children}
+    </view>;
+});
+HelpBubbleTrigger.displayName = "HelpBubbleTrigger";
+function OutsidePressCatcher({ referenceRect, onTap }) {
+	const screen = typeof SystemInfo === "undefined" ? void 0 : SystemInfo;
+	const pixelRatio = screen?.pixelRatio;
+	const width = screen?.pixelWidth;
+	const height = screen?.pixelHeight;
+	if (typeof pixelRatio !== "number" || pixelRatio <= 0 || typeof width !== "number" || typeof height !== "number") return null;
+	const screenWidth = width / pixelRatio;
+	const screenHeight = height / pixelRatio;
+	const left = Math.max(0, referenceRect.left);
+	const top = Math.max(0, referenceRect.top);
+	const right = Math.min(screenWidth, referenceRect.right);
+	const bottom = Math.min(screenHeight, referenceRect.bottom);
+	const areas = [
+		{
+			top: 0,
+			left: 0,
+			width: screenWidth,
+			height: top
+		},
+		{
+			top: bottom,
+			left: 0,
+			width: screenWidth,
+			height: Math.max(0, screenHeight - bottom)
+		},
+		{
+			top,
+			left: 0,
+			width: left,
+			height: Math.max(0, bottom - top)
+		},
+		{
+			top,
+			left: right,
+			width: Math.max(0, screenWidth - right),
+			height: Math.max(0, bottom - top)
+		}
+	];
+	return <>
+      {areas.map((area, index) => area.width > 0 && area.height > 0 ? <view key={index} style={{
+		position: "fixed",
+		top: toPixel(area.top),
+		left: toPixel(area.left),
+		width: toPixel(area.width),
+		height: toPixel(area.height),
+		zIndex: 0
+	}} bindtap={onTap} /> : null)}
+    </>;
+}
+var HelpBubblePositioner = React.forwardRef((props, ref) => {
+	const { children, className, style, zIndexOffset = 0, ...nativeProps } = props;
+	const context = useHelpBubbleContext("HelpBubblePositioner");
+	const classNames = useClassNames();
+	const handleOutsideTap = React.useCallback(() => {
+		"background only";
+		context.requestOpen(false);
+	}, [context.requestOpen]);
+	if (!context.mounted) return null;
+	return <view {...mergeProps(ref ? { ref } : {}, nativeProps)} className={clsx(classNames.positioner, className)} style={{
+		left: toPixel(context.position?.left ?? 0),
+		top: toPixel(context.position?.top ?? 0),
+		width: context.position ? toPixel(context.position.width) : void 0,
+		zIndex: 99 + zIndexOffset,
+		...style
+	}}>
+        {context.closeOnInteractOutside && context.open && context.referenceRect ? <OutsidePressCatcher referenceRect={context.referenceRect} onTap={handleOutsideTap} /> : null}
+        {children}
+      </view>;
+});
+HelpBubblePositioner.displayName = "HelpBubblePositioner";
+var HelpBubbleContent = React.forwardRef((props, ref) => {
+	const { style, restProps } = useStyleProps(props);
+	const { children, className, ...nativeProps } = restProps;
+	const context = useHelpBubbleContext("HelpBubbleContent");
+	const measurementVersionRef = React.useRef(0);
+	const intrinsicWidthRef = React.useRef(null);
+	const measurementConfigRef = React.useRef(0);
+	const configuredClassNameRef = React.useRef(className);
+	const configuredStyleRef = React.useRef(style);
+	const [contentNode, setContentNode] = React.useState(null);
+	const [measurementRevision, setMeasurementRevision] = React.useState(0);
+	const [intrinsicSize, setIntrinsicSize] = React.useState(null);
+	const [widthConstraint, setWidthConstraint] = React.useState(null);
+	const closeFinishedRef = React.useRef(false);
+	const finishClose = React.useCallback(() => {
+		"background only";
+		if (closeFinishedRef.current) return;
+		closeFinishedRef.current = true;
+		context.finishClose();
+	}, [context.finishClose]);
+	const measureIntrinsicSize = React.useCallback(async () => {
+		"background only";
+		const openEpoch = context.openEpoch;
+		const config = measurementConfigRef.current;
+		if (!context.open || !contentNode) return;
+		const version = ++measurementVersionRef.current;
+		try {
+			const rect = await getRectByRef({ current: contentNode }, true);
+			if (version !== measurementVersionRef.current || !context.isOpenRef.current || openEpoch !== context.openEpochRef.current || config !== measurementConfigRef.current) return;
+			if (intrinsicWidthRef.current === null) intrinsicWidthRef.current = rect.width;
+			setIntrinsicSize((current) => {
+				const width = intrinsicWidthRef.current ?? rect.width;
+				if (current?.width === width && current.height === rect.height && current.epoch === openEpoch && current.config === config) return current;
+				return {
+					width,
+					height: rect.height,
+					epoch: openEpoch,
+					config
+				};
+			});
+		} catch {}
+	}, [
+		contentNode,
+		context.isOpenRef,
+		context.open,
+		context.openEpoch,
+		context.openEpochRef
+	]);
+	const measurePosition = React.useCallback(async () => {
+		"background only";
+		const referenceNode = context.anchorRef.current ?? context.triggerRef.current;
+		const openEpoch = context.openEpoch;
+		const positionRevision = context.positionRevisionRef.current;
+		if (!context.open || !referenceNode || !intrinsicSize || intrinsicSize.epoch !== openEpoch || intrinsicSize.config !== measurementConfigRef.current) return;
+		const version = ++measurementVersionRef.current;
+		try {
+			const [reference, boundary] = await Promise.all([getRectByRef({ current: referenceNode }, true), getRootRect()]);
+			if (version !== measurementVersionRef.current || !context.isOpenRef.current || openEpoch !== context.openEpochRef.current || positionRevision !== context.positionRevisionRef.current) return;
+			const width = widthConstraint ?? intrinsicWidthRef.current ?? intrinsicSize.width;
+			const nextPosition = await computePosition({
+				reference,
+				boundary,
+				width,
+				height: intrinsicSize.height,
+				placement: context.placement,
+				gutter: context.gutter,
+				overflowPadding: context.overflowPadding,
+				flip: context.flip === false ? false : context.flip === true ? { fallbackStrategy: "bestFit" } : context.flip,
+				shift: {
+					crossAxis: true,
+					limit: true
+				},
+				arrow: {
+					size: 12,
+					tipHeight: 8,
+					padding: context.arrowPadding
+				}
+			});
+			if (version !== measurementVersionRef.current || !context.isOpenRef.current || openEpoch !== context.openEpochRef.current || positionRevision !== context.positionRevisionRef.current) return;
+			if (nextPosition.availableWidth < width) {
+				const constrainedWidth = nextPosition.availableWidth;
+				if (widthConstraint !== constrainedWidth) {
+					setWidthConstraint(constrainedWidth);
+					setIntrinsicSize(null);
+					context.resetPosition();
+					setMeasurementRevision((current) => current + 1);
+				}
+				return;
+			}
+			context.setPosition(nextPosition, reference);
+		} catch {}
+	}, [
+		context.anchorRef,
+		context.arrowPadding,
+		context.flip,
+		context.gutter,
+		context.isOpenRef,
+		context.open,
+		context.openEpoch,
+		context.openEpochRef,
+		context.overflowPadding,
+		context.placement,
+		context.resetPosition,
+		context.setPosition,
+		context.triggerRef,
+		intrinsicSize,
+		widthConstraint
+	]);
+	React.useEffect(() => {
+		"background only";
+		measurementVersionRef.current += 1;
+		intrinsicWidthRef.current = null;
+		setWidthConstraint(null);
+		setIntrinsicSize(null);
+		context.resetPosition();
+	}, [context.openEpoch, context.resetPosition]);
+	React.useEffect(() => {
+		"background only";
+		if (configuredClassNameRef.current === className && areStylesEqual(configuredStyleRef.current, style)) return;
+		measurementVersionRef.current += 1;
+		intrinsicWidthRef.current = null;
+		measurementConfigRef.current += 1;
+		configuredClassNameRef.current = className;
+		configuredStyleRef.current = style;
+		setWidthConstraint(null);
+		setIntrinsicSize(null);
+		context.resetPosition();
+		setMeasurementRevision((current) => current + 1);
+	}, [
+		className,
+		context.resetPosition,
+		style
+	]);
+	React.useEffect(() => {
+		"background only";
+		if (!context.open) return;
+		const frame = requestAnimationFrame(() => {
+			"background only";
+			measureIntrinsicSize();
+		});
+		return () => cancelAnimationFrame(frame);
+	}, [
+		context.open,
+		context.openEpoch,
+		measureIntrinsicSize,
+		measurementRevision
+	]);
+	React.useEffect(() => {
+		"background only";
+		if (!context.open) return;
+		let disposed = false;
+		let frame;
+		const trackPosition = () => {
+			measurePosition().finally(() => {
+				if (!disposed && context.isOpenRef.current) frame = requestAnimationFrame(trackPosition);
+			});
+		};
+		trackPosition();
+		return () => {
+			disposed = true;
+			measurementVersionRef.current += 1;
+			if (frame !== void 0) cancelAnimationFrame(frame);
+		};
+	}, [
+		context.isOpenRef,
+		context.open,
+		context.openEpoch,
+		context.positionRevision,
+		measurePosition
+	]);
+	React.useEffect(() => {
+		"background only";
+		if (context.open) {
+			closeFinishedRef.current = false;
+			return;
+		}
+		if (!context.mounted) return;
+		const timer = setTimeout(() => {
+			"background only";
+			finishClose();
+		}, EXIT_TRANSITION_FALLBACK_MS);
+		return () => clearTimeout(timer);
+	}, [
+		context.mounted,
+		context.open,
+		finishClose
+	]);
+	const handleRef = React.useCallback((node) => {
+		measurementVersionRef.current += 1;
+		setContentNode(node);
+		mergeNodeRef(ref, node);
+	}, [ref]);
+	const handleLayoutChange = React.useCallback((event) => {
+		"background only";
+		const nextSize = getLayoutSize(event);
+		if (!nextSize || !context.open) return;
+		measurementVersionRef.current += 1;
+		if (intrinsicWidthRef.current === null) intrinsicWidthRef.current = nextSize.width;
+		setIntrinsicSize((current) => {
+			const width = intrinsicWidthRef.current ?? nextSize.width;
+			if (current?.width === width && current.height === nextSize.height && current.epoch === context.openEpoch && current.config === measurementConfigRef.current) return current;
+			return {
+				width,
+				height: nextSize.height,
+				epoch: context.openEpoch,
+				config: measurementConfigRef.current
+			};
+		});
+	}, [context.open, context.openEpoch]);
+	const handleTransitionEnd = React.useCallback((event) => {
+		"background only";
+		if (!context.open && hasExitTransition(event)) finishClose();
+	}, [context.open, finishClose]);
+	const motionClassName = useClassNames().motion;
+	return <view className={motionClassName} bindtransitionend={handleTransitionEnd}>
+      <view ref={handleRef} className={clsx(useClassNames().content, className)} style={{
+		...style,
+		...widthConstraint != null ? { width: toPixel(widthConstraint) } : {}
+	}} bindlayoutchange={handleLayoutChange} {...nativeProps}>
+        {children}
+      </view>
+    </view>;
+});
+HelpBubbleContent.displayName = "HelpBubbleContent";
+var HelpBubbleArrow = React.forwardRef((props, ref) => {
+	const { children, className, style, ...nativeProps } = props;
+	const context = useHelpBubbleContext("HelpBubbleArrow");
+	const arrow = context.position?.arrow;
+	const side = context.side;
+	const geometryStyle = side === "top" ? {
+		left: toPixel(arrow?.left ?? 0),
+		top: "100%"
+	} : side === "bottom" ? {
+		left: toPixel(arrow?.left ?? 0),
+		bottom: "100%"
+	} : side === "right" ? {
+		top: toPixel(arrow?.top ?? 0),
+		right: "100%"
+	} : {
+		top: toPixel(arrow?.top ?? 0),
+		left: "100%"
+	};
+	return <view {...mergeProps(ref ? { ref } : {}, nativeProps)} className={clsx(useClassNames().arrow, className)} style={{
+		...geometryStyle,
+		...style
+	}}>
+      {children}
+    </view>;
+});
+HelpBubbleArrow.displayName = "HelpBubbleArrow";
+var HelpBubbleArrowTip = React.forwardRef((props, ref) => {
+	const { children, className, style, ...nativeProps } = props;
+	return <view {...mergeProps(ref ? { ref } : {}, nativeProps)} className={clsx(useClassNames().arrowTip, className)} style={style} accessibility-elements-hidden={true}>
+        {children}
+      </view>;
+});
+HelpBubbleArrowTip.displayName = "HelpBubbleArrowTip";
+var HelpBubbleBody = React.forwardRef((props, ref) => {
+	const { children, className, style, ...nativeProps } = props;
+	return <view {...mergeProps(ref ? { ref } : {}, nativeProps)} className={clsx(useClassNames().body, className)} style={style}>
+      {children}
+    </view>;
+});
+HelpBubbleBody.displayName = "HelpBubbleBody";
+var HelpBubbleTitle = React.forwardRef((props, ref) => {
+	const { children, className, style, ...nativeProps } = props;
+	return <text {...mergeProps(ref ? { ref } : {}, nativeProps)} className={clsx(useClassNames().title, className)} style={style}>
+      {children}
+    </text>;
+});
+HelpBubbleTitle.displayName = "HelpBubbleTitle";
+var HelpBubbleDescription = React.forwardRef((props, ref) => {
+	const { children, className, style, ...nativeProps } = props;
+	return <text {...mergeProps(ref ? { ref } : {}, nativeProps)} className={clsx(useClassNames().description, className)} style={style}>
+        {children}
+      </text>;
+});
+HelpBubbleDescription.displayName = "HelpBubbleDescription";
+var HelpBubbleCloseButton = React.forwardRef((props, ref) => {
+	const { children, className, style, bindtap, "main-thread:bindtap": mainThreadBindtap, "accessibility-element": accessibilityElement = true, "accessibility-label": accessibilityLabel, "accessibility-traits": accessibilityTraits = "button", ...nativeProps } = props;
+	const context = useHelpBubbleContext("HelpBubbleCloseButton");
+	const { pressed, ...pressHandlers } = usePressTap({
+		onTap: React.useCallback((event, instance) => {
+			"background only";
+			bindtap?.(event, instance);
+			context.requestOpen(false);
+		}, [bindtap, context]),
+		mainThreadOnTap: mainThreadBindtap
+	});
+	const closeButtonClassNames = helpBubble({
+		open: context.open,
+		positioned: context.positioned,
+		side: context.side,
+		pressed
+	});
+	if (process.env.NODE_ENV !== "production" && accessibilityElement && !accessibilityLabel) console.warn("HelpBubbleCloseButton requires `accessibility-label` for accessibility.");
+	return <view {...mergeProps(ref ? { ref } : {}, pressHandlers, nativeProps)} accessibility-element={accessibilityElement} accessibility-label={accessibilityLabel} accessibility-traits={accessibilityTraits} className={clsx(closeButtonClassNames.closeButton, className)} style={style} flatten={false}>
+        {children}
+      </view>;
+});
+HelpBubbleCloseButton.displayName = "HelpBubbleCloseButton";
+//#endregion
+export { HelpBubbleAnchor, HelpBubbleArrow, HelpBubbleArrowTip, HelpBubbleBody, HelpBubbleCloseButton, HelpBubbleContent, HelpBubbleDescription, HelpBubblePositioner, HelpBubbleRoot, HelpBubbleTitle, HelpBubbleTrigger };

package/lib/components/HelpBubble/HelpBubble.namespace.d.ts

@@ -0,0 +1,2 @@
+export { HelpBubbleAnchor as Anchor, HelpBubbleArrow as Arrow, HelpBubbleArrowTip as ArrowTip, HelpBubbleBody as Body, HelpBubbleCloseButton as CloseButton, HelpBubbleContent as Content, HelpBubbleDescription as Description, HelpBubblePositioner as Positioner, HelpBubbleRoot as Root, HelpBubbleTitle as Title, HelpBubbleTrigger as Trigger, type HelpBubbleAnchorProps as AnchorProps, type HelpBubbleArrowProps as ArrowProps, type HelpBubbleArrowTipProps as ArrowTipProps, type HelpBubbleBodyProps as BodyProps, type HelpBubbleCloseButtonProps as CloseButtonProps, type HelpBubbleContentProps as ContentProps, type HelpBubbleDescriptionProps as DescriptionProps, type HelpBubblePositionerProps as PositionerProps, type HelpBubbleRootProps as RootProps, type HelpBubbleTitleProps as TitleProps, type HelpBubbleTriggerProps as TriggerProps, } from './HelpBubble';
+//# sourceMappingURL=HelpBubble.namespace.d.ts.map

package/lib/components/HelpBubble/HelpBubble.namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HelpBubble.namespace.d.ts","sourceRoot":"","sources":["../../../src/components/HelpBubble/HelpBubble.namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,IAAI,MAAM,EAC1B,eAAe,IAAI,KAAK,EACxB,kBAAkB,IAAI,QAAQ,EAC9B,cAAc,IAAI,IAAI,EACtB,qBAAqB,IAAI,WAAW,EACpC,iBAAiB,IAAI,OAAO,EAC5B,qBAAqB,IAAI,WAAW,EACpC,oBAAoB,IAAI,UAAU,EAClC,cAAc,IAAI,IAAI,EACtB,eAAe,IAAI,KAAK,EACxB,iBAAiB,IAAI,OAAO,EAC5B,KAAK,qBAAqB,IAAI,WAAW,EACzC,KAAK,oBAAoB,IAAI,UAAU,EACvC,KAAK,uBAAuB,IAAI,aAAa,EAC7C,KAAK,mBAAmB,IAAI,SAAS,EACrC,KAAK,0BAA0B,IAAI,gBAAgB,EACnD,KAAK,sBAAsB,IAAI,YAAY,EAC3C,KAAK,0BAA0B,IAAI,gBAAgB,EACnD,KAAK,yBAAyB,IAAI,eAAe,EACjD,KAAK,mBAAmB,IAAI,SAAS,EACrC,KAAK,oBAAoB,IAAI,UAAU,EACvC,KAAK,sBAAsB,IAAI,YAAY,GAC5C,MAAM,cAAc,CAAC"}