@yahoo/uds 3.102.0 → 3.103.0

package/dist/components/client/Tooltip/useTooltipContent.d.cts

@@ -0,0 +1,66 @@
+
+import { ParsedShadow } from "./util.cjs";
+import { CSSProperties, RefObject } from "react";
+
+//#region src/components/client/Tooltip/useTooltipContent.d.ts
+interface UseTooltipContentOptions {
+  /** Whether the tooltip is currently open. */
+  open: boolean;
+  /** Resolved placement after Ariakit positioning (e.g. `'top'`, `'bottom-start'`). */
+  effectivePlacement: string;
+  /** Optional max-width override (number = px, string = CSS value). */
+  maxWidth?: number | string;
+  /** Border-radius from the tooltip config (px). */
+  borderRadius: number;
+  /**
+   * Ref to the Ariakit `TooltipArrow` element. Its position (set by
+   * floating-ui) is read inside the `updatePosition` callback so the
+   * SVG arrow always mirrors where floating-ui places the native arrow.
+   */
+  arrowRef: RefObject<HTMLDivElement | null>;
+  /** Animation duration from the tooltip config (ms). */
+  animationDuration: number;
+}
+interface UseTooltipContentReturn {
+  internalRef: RefObject<HTMLElement | null>;
+  shadowFilterId: string;
+  maxWidthClass: string;
+  dimensions: {
+    width: number;
+    height: number;
+  };
+  shadows: ParsedShadow[];
+  shadowPadding: number;
+  svgPath: string | null;
+  blurClipPath: string | null;
+  blurStyle: CSSProperties;
+  visible: boolean;
+  childTransitionStyle: CSSProperties;
+  /**
+   * Pixel offset to apply as a CSS transform on the tooltip element so that
+   * the (clamped) SVG arrow aligns with the trigger center even when the
+   * trigger is too small / close to a rounded corner for the arrow to reach.
+   */
+  tooltipShift: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Pass as the `updatePosition` prop to the Ariakit `<Tooltip>` component.
+   * This hooks into floating-ui's positioning lifecycle so the SVG arrow
+   * center is read after every `computePosition`
+   */
+  onPositionUpdate: (props: {
+    updatePosition: () => Promise<void>;
+  }) => Promise<void>;
+}
+declare function useTooltipContent({
+  open,
+  effectivePlacement,
+  maxWidth,
+  borderRadius,
+  arrowRef,
+  animationDuration
+}: UseTooltipContentOptions): UseTooltipContentReturn;
+//#endregion
+export { type UseTooltipContentOptions, type UseTooltipContentReturn, useTooltipContent };

package/dist/components/client/Tooltip/useTooltipContent.d.ts

@@ -0,0 +1,66 @@
+
+import { ParsedShadow } from "./util.js";
+import { CSSProperties, RefObject } from "react";
+
+//#region src/components/client/Tooltip/useTooltipContent.d.ts
+interface UseTooltipContentOptions {
+  /** Whether the tooltip is currently open. */
+  open: boolean;
+  /** Resolved placement after Ariakit positioning (e.g. `'top'`, `'bottom-start'`). */
+  effectivePlacement: string;
+  /** Optional max-width override (number = px, string = CSS value). */
+  maxWidth?: number | string;
+  /** Border-radius from the tooltip config (px). */
+  borderRadius: number;
+  /**
+   * Ref to the Ariakit `TooltipArrow` element. Its position (set by
+   * floating-ui) is read inside the `updatePosition` callback so the
+   * SVG arrow always mirrors where floating-ui places the native arrow.
+   */
+  arrowRef: RefObject<HTMLDivElement | null>;
+  /** Animation duration from the tooltip config (ms). */
+  animationDuration: number;
+}
+interface UseTooltipContentReturn {
+  internalRef: RefObject<HTMLElement | null>;
+  shadowFilterId: string;
+  maxWidthClass: string;
+  dimensions: {
+    width: number;
+    height: number;
+  };
+  shadows: ParsedShadow[];
+  shadowPadding: number;
+  svgPath: string | null;
+  blurClipPath: string | null;
+  blurStyle: CSSProperties;
+  visible: boolean;
+  childTransitionStyle: CSSProperties;
+  /**
+   * Pixel offset to apply as a CSS transform on the tooltip element so that
+   * the (clamped) SVG arrow aligns with the trigger center even when the
+   * trigger is too small / close to a rounded corner for the arrow to reach.
+   */
+  tooltipShift: {
+    x: number;
+    y: number;
+  };
+  /**
+   * Pass as the `updatePosition` prop to the Ariakit `<Tooltip>` component.
+   * This hooks into floating-ui's positioning lifecycle so the SVG arrow
+   * center is read after every `computePosition`
+   */
+  onPositionUpdate: (props: {
+    updatePosition: () => Promise<void>;
+  }) => Promise<void>;
+}
+declare function useTooltipContent({
+  open,
+  effectivePlacement,
+  maxWidth,
+  borderRadius,
+  arrowRef,
+  animationDuration
+}: UseTooltipContentOptions): UseTooltipContentReturn;
+//#endregion
+export { type UseTooltipContentOptions, type UseTooltipContentReturn, useTooltipContent };

package/dist/components/client/Tooltip/useTooltipContent.js

@@ -0,0 +1,184 @@
+"use client";
+/*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
+import { DROP_SHADOW_PREFIX } from "../../../css-tokens/dist/index.js";
+import { ARROW_HEIGHT, generateTooltipPath, getArrowClampDelta, getArrowSide, parseShadow } from "./util.js";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+
+//#region src/components/client/Tooltip/useTooltipContent.ts
+function useTooltipContent({ open, effectivePlacement, maxWidth, borderRadius, arrowRef, animationDuration }) {
+	const internalRef = useRef(null);
+	const shadowFilterId = useId();
+	const [dimensions, setDimensions] = useState({
+		width: 0,
+		height: 0
+	});
+	const maxWidthClass = useMemo(() => {
+		if (maxWidth !== void 0) return typeof maxWidth === "number" ? `max-w-[${maxWidth}px]` : `max-w-[${maxWidth}]`;
+		return "max-w-lg";
+	}, [maxWidth]);
+	useEffect(() => {
+		const el = internalRef.current;
+		if (!el) return;
+		const observer = new ResizeObserver(() => {
+			setDimensions({
+				width: el.offsetWidth,
+				height: el.offsetHeight
+			});
+		});
+		observer.observe(el);
+		return () => observer.disconnect();
+	}, [open]);
+	const [shadows, setShadows] = useState([]);
+	const shadowValueRef = useRef("");
+	const readShadows = useCallback(() => {
+		if (!internalRef.current) return;
+		const shadowValue = getComputedStyle(internalRef.current).getPropertyValue(`--${DROP_SHADOW_PREFIX}`);
+		if (shadowValue !== shadowValueRef.current) {
+			shadowValueRef.current = shadowValue;
+			setShadows(parseShadow(shadowValue));
+		}
+	}, []);
+	const shadowPadding = useMemo(() => {
+		if (shadows.length === 0) return 0;
+		return shadows.reduce((max, s) => {
+			const extentX = Math.abs(s.x) + s.blur + Math.abs(s.spread);
+			const extentY = Math.abs(s.y) + s.blur + Math.abs(s.spread);
+			return Math.max(max, extentX, extentY);
+		}, 0);
+	}, [shadows]);
+	const [arrowCenter, setArrowCenter] = useState(void 0);
+	const computeArrowCenter = useCallback(() => {
+		const arrowEl = arrowRef.current;
+		const tooltipEl = internalRef.current;
+		if (!arrowEl || !tooltipEl) return;
+		const arrowRect = arrowEl.getBoundingClientRect();
+		const tooltipRect = tooltipEl.getBoundingClientRect();
+		const side = getArrowSide(effectivePlacement);
+		const raw = side === "top" || side === "bottom" ? arrowRect.left + arrowRect.width / 2 - tooltipRect.left : arrowRect.top + arrowRect.height / 2 - tooltipRect.top;
+		return Math.round(raw);
+	}, [arrowRef, effectivePlacement]);
+	const onPositionUpdate = useCallback(async ({ updatePosition }) => {
+		await updatePosition();
+		const el = internalRef.current;
+		if (el) {
+			const { offsetWidth, offsetHeight } = el;
+			if (offsetWidth > 0 && offsetHeight > 0) setDimensions((prev) => {
+				if (prev.width === offsetWidth && prev.height === offsetHeight) return prev;
+				return {
+					width: offsetWidth,
+					height: offsetHeight
+				};
+			});
+			readShadows();
+		}
+		const next = computeArrowCenter();
+		if (next !== void 0) setArrowCenter((prev) => prev === next ? prev : next);
+	}, [computeArrowCenter, readShadows]);
+	const svgPath = useMemo(() => {
+		return dimensions.width > 0 && dimensions.height > 0 ? generateTooltipPath({
+			width: dimensions.width,
+			height: dimensions.height,
+			placement: effectivePlacement,
+			borderRadius,
+			arrowCenter
+		}) : null;
+	}, [
+		effectivePlacement,
+		dimensions.width,
+		dimensions.height,
+		borderRadius,
+		arrowCenter
+	]);
+	const blurClipPath = useMemo(() => {
+		if (dimensions.width <= 0 || dimensions.height <= 0) return null;
+		const arrowSide = getArrowSide(effectivePlacement);
+		const offsetX = arrowSide === "left" ? ARROW_HEIGHT : 0;
+		const offsetY = arrowSide === "top" ? ARROW_HEIGHT : 0;
+		return generateTooltipPath({
+			width: dimensions.width,
+			height: dimensions.height,
+			placement: effectivePlacement,
+			borderRadius,
+			arrowCenter,
+			offsetX,
+			offsetY
+		});
+	}, [
+		effectivePlacement,
+		dimensions.width,
+		dimensions.height,
+		borderRadius,
+		arrowCenter
+	]);
+	const blurStyle = useMemo(() => {
+		const style = { clipPath: blurClipPath ? `path('${blurClipPath}')` : void 0 };
+		switch (getArrowSide(effectivePlacement)) {
+			case "top":
+				style.height = `calc(100% + ${ARROW_HEIGHT}px)`;
+				style.top = "auto";
+				style.bottom = "0";
+				break;
+			case "bottom":
+				style.height = `calc(100% + ${ARROW_HEIGHT}px)`;
+				break;
+			case "left":
+				style.width = `calc(100% + ${ARROW_HEIGHT}px)`;
+				style.left = "auto";
+				style.right = "0";
+				break;
+			case "right":
+				style.width = `calc(100% + ${ARROW_HEIGHT}px)`;
+				break;
+		}
+		return style;
+	}, [blurClipPath, effectivePlacement]);
+	const [visible, setVisible] = useState(false);
+	if ((!open || !svgPath) && visible) setVisible(false);
+	useEffect(() => {
+		if (open && svgPath) {
+			const raf = requestAnimationFrame(() => {
+				setVisible(true);
+			});
+			return () => cancelAnimationFrame(raf);
+		}
+	}, [open, svgPath]);
+	return {
+		internalRef,
+		shadowFilterId,
+		maxWidthClass,
+		dimensions,
+		shadows,
+		shadowPadding,
+		svgPath,
+		blurClipPath,
+		blurStyle,
+		visible,
+		childTransitionStyle: {
+			opacity: visible ? 1 : 0,
+			transition: `opacity ${animationDuration}ms ease-in-out`
+		},
+		tooltipShift: useMemo(() => {
+			if (arrowCenter === void 0 || dimensions.width <= 0 || dimensions.height <= 0) return {
+				x: 0,
+				y: 0
+			};
+			return getArrowClampDelta({
+				width: dimensions.width,
+				height: dimensions.height,
+				placement: effectivePlacement,
+				borderRadius,
+				arrowCenter
+			});
+		}, [
+			arrowCenter,
+			dimensions.width,
+			dimensions.height,
+			effectivePlacement,
+			borderRadius
+		]),
+		onPositionUpdate
+	};
+}
+
+//#endregion
+export { useTooltipContent };

package/dist/components/client/Tooltip/util.cjs

@@ -0,0 +1,248 @@
+"use client";
+/*! © 2026 Yahoo, Inc. UDS v0.0.0-development */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/components/client/Tooltip/util.ts
+/**
+* Splits a CSS value on whitespace, but keeps parenthesized groups
+* (e.g. `rgb(0, 0, 0)`) together as single tokens.
+*/
+function tokenizeCSSValue(value) {
+	const tokens = [];
+	let current = "";
+	let depth = 0;
+	for (const char of value) {
+		if (char === "(") depth++;
+		if (char === ")") depth--;
+		if (char === " " && depth === 0) {
+			if (current) tokens.push(current);
+			current = "";
+		} else current += char;
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}
+/**
+* Returns `true` if the token is a CSS color value.
+*
+* In a box-shadow context (after filtering `inset`), every token is either a
+* length or a color. Colors always start with `#` (hex), a letter (named
+* colors like `red`, `transparent`, `currentcolor`), or are a CSS function
+* containing `(` (e.g. `rgb(…)`, `hsl(…)`, `oklch(…)`).
+*/
+function isColorToken(token) {
+	const ch = token[0];
+	return ch !== "-" && ch !== "." && (ch < "0" || ch > "9");
+}
+/**
+* Splits a CSS multi-shadow value (comma-separated) into individual
+* shadow strings, correctly handling commas nested inside color functions
+* like `rgb()`, `rgba()`, `hsl()`, etc.
+*/
+function splitShadows(value) {
+	const shadows = [];
+	let current = "";
+	let depth = 0;
+	for (let i = 0; i < value.length; i++) {
+		const char = value[i];
+		if (char === "(") {
+			depth++;
+			current += char;
+		} else if (char === ")") {
+			depth--;
+			current += char;
+		} else if (char === "," && depth === 0) {
+			if (current.trim()) shadows.push(current.trim());
+			current = "";
+		} else current += char;
+	}
+	if (current.trim()) shadows.push(current.trim());
+	return shadows;
+}
+/**
+* Parses a single CSS shadow value string into its constituent parts.
+*
+* Handles all standard CSS box-shadow / drop-shadow permutations:
+* - Color before or after length values (`red 0 4px 8px` or `0 4px 8px red`)
+* - Optional blur and spread radii (defaults to 0)
+* - `inset` keyword at any position (silently ignored)
+* - All color formats: named, hex (3/4/6/8-digit), rgb/rgba, hsl/hsla, oklch,
+*   oklab, lab, lch, color(), color-mix(), light-dark(), etc.
+* - `none` / empty values → zeroed-out result with `transparent` color
+*/
+function parseSingleShadow(shadow) {
+	const value = shadow.trim();
+	if (!value || value.toLowerCase() === "none") return {
+		x: 0,
+		y: 0,
+		blur: 0,
+		spread: 0,
+		color: "transparent"
+	};
+	const tokens = tokenizeCSSValue(value);
+	const lengths = [];
+	const colorParts = [];
+	for (const token of tokens) {
+		if (token.toLowerCase() === "inset") continue;
+		if (isColorToken(token)) colorParts.push(token);
+		else lengths.push(token);
+	}
+	return {
+		x: lengths.length > 0 ? parseFloat(lengths[0]) : 0,
+		y: lengths.length > 1 ? parseFloat(lengths[1]) : 0,
+		blur: lengths.length > 2 ? parseFloat(lengths[2]) : 0,
+		spread: lengths.length > 3 ? parseFloat(lengths[3]) : 0,
+		color: colorParts.length > 0 ? colorParts.join(" ") : "rgb(0 0 0 / 1)"
+	};
+}
+/**
+* Parses a CSS shadow value — which may contain multiple comma-separated
+* layers — into an array of {@link ParsedShadow} objects.
+*
+* @example
+* ```ts
+* parseShadow('0px 4px 8px 0px rgb(0 0 0 / 0.12)')
+* // → [{ x: 0, y: 4, blur: 8, spread: 0, color: 'rgb(0 0 0 / 0.12)' }]
+*
+* parseShadow('0px 4px 8px rgb(0 0 0 / 0.12), 0px 1px 2px rgba(0, 0, 0, 0.08)')
+* // → [
+* //     { x: 0, y: 4, blur: 8, spread: 0, color: 'rgb(0 0 0 / 0.12)' },
+* //     { x: 0, y: 1, blur: 2, spread: 0, color: 'rgba(0, 0, 0, 0.08)' },
+* //   ]
+* ```
+*/
+function parseShadow(shadowValue) {
+	const trimmed = shadowValue.trim();
+	if (!trimmed || trimmed.toLowerCase() === "none") return [];
+	return splitShadows(trimmed).map(parseSingleShadow);
+}
+/** Base width of the arrow triangle (px). */
+const ARROW_WIDTH = 12;
+/** Height (protrusion) of the arrow triangle from the edge (px). */
+const ARROW_HEIGHT = 8;
+/**
+* Fraction of the container border-radius applied to round the arrow tip
+* (0 = sharp point, 1 = same radius as the container corners).
+*/
+const ARROW_TIP_RADIUS_FRACTION = .5;
+/**
+* Returns the side of the tooltip where the arrow should appear.
+* The arrow points *toward* the trigger, so it lives on the opposite
+* side of the placement direction.
+*/
+function getArrowSide(placement) {
+	switch (placement.split("-")[0]) {
+		case "bottom": return "top";
+		case "top": return "bottom";
+		case "left": return "right";
+		case "right": return "left";
+		default: return "top";
+	}
+}
+/**
+* Generates an SVG `<path>` string for a rounded rectangle with an arrow
+* pointing toward the trigger element.
+*
+* The path is traced clockwise, inserting the arrow triangle on the
+* appropriate edge.  The arrow extends *outside* the 0,0 → width,height
+* rectangle so the host `<svg>` must use `overflow: visible`.
+*/
+function generateTooltipPath({ width, height, placement, borderRadius, arrowWidth = ARROW_WIDTH, arrowHeight = ARROW_HEIGHT, arrowCenter, offsetX: ox = 0, offsetY: oy = 0 }) {
+	const aw = arrowWidth / 2;
+	const ah = arrowHeight;
+	const arrowSide = getArrowSide(placement);
+	const arrowEdge = arrowSide === "top" || arrowSide === "bottom" ? width : height;
+	const otherEdge = arrowSide === "top" || arrowSide === "bottom" ? height : width;
+	const maxRadius = Math.min(otherEdge / 2, (arrowEdge - arrowWidth) / 2);
+	const r = Math.max(0, Math.min(borderRadius, maxRadius));
+	const minAc = r + aw;
+	const edgeLength = arrowSide === "top" || arrowSide === "bottom" ? width : height;
+	let ac = arrowCenter ?? edgeLength / 2;
+	ac = Math.max(minAc, Math.min(edgeLength - minAc, ac));
+	const edgeLen = Math.sqrt(aw * aw + ah * ah);
+	const tipR = r > 0 && edgeLen > 0 ? Math.min(r * ARROW_TIP_RADIUS_FRACTION, edgeLen / 2) : 0;
+	const daw = edgeLen > 0 ? aw / edgeLen : 0;
+	const dah = edgeLen > 0 ? ah / edgeLen : 0;
+	const d = [];
+	d.push(`M ${r + ox} ${oy}`);
+	if (arrowSide === "top") {
+		d.push(`L ${ac - aw + ox} ${oy}`);
+		if (tipR > 0) {
+			d.push(`L ${ac - tipR * daw + ox} ${-ah + tipR * dah + oy}`);
+			d.push(`Q ${ac + ox} ${-ah + oy} ${ac + tipR * daw + ox} ${-ah + tipR * dah + oy}`);
+		} else d.push(`L ${ac + ox} ${-ah + oy}`);
+		d.push(`L ${ac + aw + ox} ${oy}`);
+	}
+	d.push(`L ${width - r + ox} ${oy}`);
+	d.push(`A ${r} ${r} 0 0 1 ${width + ox} ${r + oy}`);
+	if (arrowSide === "right") {
+		d.push(`L ${width + ox} ${ac - aw + oy}`);
+		if (tipR > 0) {
+			d.push(`L ${width + ah - tipR * dah + ox} ${ac - tipR * daw + oy}`);
+			d.push(`Q ${width + ah + ox} ${ac + oy} ${width + ah - tipR * dah + ox} ${ac + tipR * daw + oy}`);
+		} else d.push(`L ${width + ah + ox} ${ac + oy}`);
+		d.push(`L ${width + ox} ${ac + aw + oy}`);
+	}
+	d.push(`L ${width + ox} ${height - r + oy}`);
+	d.push(`A ${r} ${r} 0 0 1 ${width - r + ox} ${height + oy}`);
+	if (arrowSide === "bottom") {
+		d.push(`L ${ac + aw + ox} ${height + oy}`);
+		if (tipR > 0) {
+			d.push(`L ${ac + tipR * daw + ox} ${height + ah - tipR * dah + oy}`);
+			d.push(`Q ${ac + ox} ${height + ah + oy} ${ac - tipR * daw + ox} ${height + ah - tipR * dah + oy}`);
+		} else d.push(`L ${ac + ox} ${height + ah + oy}`);
+		d.push(`L ${ac - aw + ox} ${height + oy}`);
+	}
+	d.push(`L ${r + ox} ${height + oy}`);
+	d.push(`A ${r} ${r} 0 0 1 ${ox} ${height - r + oy}`);
+	if (arrowSide === "left") {
+		d.push(`L ${ox} ${ac + aw + oy}`);
+		if (tipR > 0) {
+			d.push(`L ${-ah + tipR * dah + ox} ${ac + tipR * daw + oy}`);
+			d.push(`Q ${-ah + ox} ${ac + oy} ${-ah + tipR * dah + ox} ${ac - tipR * daw + oy}`);
+		} else d.push(`L ${-ah + ox} ${ac + oy}`);
+		d.push(`L ${ox} ${ac - aw + oy}`);
+	}
+	d.push(`L ${ox} ${r + oy}`);
+	d.push(`A ${r} ${r} 0 0 1 ${r + ox} ${oy}`);
+	d.push("Z");
+	return d.join(" ");
+}
+/**
+* Computes the pixel offset the tooltip must shift so that the SVG arrow
+* (after clamping) visually aligns with the Ariakit arrow's actual position.
+*
+* When the desired `arrowCenter` falls inside the safe zone the delta is 0.
+* When it falls outside (e.g. a tiny trigger near a rounded corner), the
+* returned delta tells the caller how far to translate the tooltip element
+* so the clamped arrow ends up over the trigger center.
+*/
+function getArrowClampDelta({ width, height, placement, borderRadius, arrowCenter, arrowWidth = ARROW_WIDTH }) {
+	const aw = arrowWidth / 2;
+	const side = getArrowSide(placement);
+	const arrowEdge = side === "top" || side === "bottom" ? width : height;
+	const otherEdge = side === "top" || side === "bottom" ? height : width;
+	const maxRadius = Math.min(otherEdge / 2, (arrowEdge - arrowWidth) / 2);
+	const minAc = Math.max(0, Math.min(borderRadius, maxRadius)) + aw;
+	const maxAc = arrowEdge - minAc;
+	let delta = 0;
+	if (arrowCenter < minAc) delta = arrowCenter - minAc;
+	else if (arrowCenter > maxAc) delta = arrowCenter - maxAc;
+	if (side === "top" || side === "bottom") return {
+		x: delta,
+		y: 0
+	};
+	return {
+		x: 0,
+		y: delta
+	};
+}
+
+//#endregion
+exports.ARROW_HEIGHT = ARROW_HEIGHT;
+exports.ARROW_TIP_RADIUS_FRACTION = ARROW_TIP_RADIUS_FRACTION;
+exports.ARROW_WIDTH = ARROW_WIDTH;
+exports.generateTooltipPath = generateTooltipPath;
+exports.getArrowClampDelta = getArrowClampDelta;
+exports.getArrowSide = getArrowSide;
+exports.parseShadow = parseShadow;

package/dist/components/client/Tooltip/util.d.cts

@@ -0,0 +1,118 @@
+
+//#region src/components/client/Tooltip/util.d.ts
+interface ParsedShadow {
+  /** Horizontal offset in px. */
+  x: number;
+  /** Vertical offset in px. */
+  y: number;
+  /** Blur radius in px. */
+  blur: number;
+  /** Spread radius in px (always 0 for drop-shadow filter functions). */
+  spread: number;
+  /** The raw CSS color string (e.g. `rgb(0 0 0 / 0.12)`, `#ff0000`, `red`). */
+  color: string;
+}
+/**
+ * Parses a CSS shadow value — which may contain multiple comma-separated
+ * layers — into an array of {@link ParsedShadow} objects.
+ *
+ * @example
+ * ```ts
+ * parseShadow('0px 4px 8px 0px rgb(0 0 0 / 0.12)')
+ * // → [{ x: 0, y: 4, blur: 8, spread: 0, color: 'rgb(0 0 0 / 0.12)' }]
+ *
+ * parseShadow('0px 4px 8px rgb(0 0 0 / 0.12), 0px 1px 2px rgba(0, 0, 0, 0.08)')
+ * // → [
+ * //     { x: 0, y: 4, blur: 8, spread: 0, color: 'rgb(0 0 0 / 0.12)' },
+ * //     { x: 0, y: 1, blur: 2, spread: 0, color: 'rgba(0, 0, 0, 0.08)' },
+ * //   ]
+ * ```
+ */
+declare function parseShadow(shadowValue: string): ParsedShadow[];
+/** Base width of the arrow triangle (px). */
+declare const ARROW_WIDTH = 12;
+/** Height (protrusion) of the arrow triangle from the edge (px). */
+declare const ARROW_HEIGHT = 8;
+/**
+ * Fraction of the container border-radius applied to round the arrow tip
+ * (0 = sharp point, 1 = same radius as the container corners).
+ */
+declare const ARROW_TIP_RADIUS_FRACTION = 0.5;
+type ArrowSide = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * Returns the side of the tooltip where the arrow should appear.
+ * The arrow points *toward* the trigger, so it lives on the opposite
+ * side of the placement direction.
+ */
+declare function getArrowSide(placement: string): ArrowSide;
+interface TooltipPathOptions {
+  width: number;
+  height: number;
+  placement: string;
+  borderRadius: number;
+  arrowWidth?: number;
+  arrowHeight?: number;
+  /**
+   * Position of the arrow center along the arrow's edge (px), measured from
+   * the start of that edge (left for top/bottom sides, top for left/right).
+   * Typically derived from the Ariakit `TooltipArrow` element's position
+   * within the tooltip.
+   *
+   * Clamped so the arrow never collides with the border-radius curve
+   * Falls back to the midpoint of the edge when omitted.
+   */
+  arrowCenter?: number;
+  /** Shift every coordinate in the path by this many pixels on the x-axis. */
+  offsetX?: number;
+  /** Shift every coordinate in the path by this many pixels on the y-axis. */
+  offsetY?: number;
+}
+/**
+ * Generates an SVG `<path>` string for a rounded rectangle with an arrow
+ * pointing toward the trigger element.
+ *
+ * The path is traced clockwise, inserting the arrow triangle on the
+ * appropriate edge.  The arrow extends *outside* the 0,0 → width,height
+ * rectangle so the host `<svg>` must use `overflow: visible`.
+ */
+declare function generateTooltipPath({
+  width,
+  height,
+  placement,
+  borderRadius,
+  arrowWidth,
+  arrowHeight,
+  arrowCenter,
+  offsetX: ox,
+  offsetY: oy
+}: TooltipPathOptions): string;
+interface ArrowClampDeltaOptions {
+  width: number;
+  height: number;
+  placement: string;
+  borderRadius: number;
+  arrowCenter: number;
+  arrowWidth?: number;
+}
+/**
+ * Computes the pixel offset the tooltip must shift so that the SVG arrow
+ * (after clamping) visually aligns with the Ariakit arrow's actual position.
+ *
+ * When the desired `arrowCenter` falls inside the safe zone the delta is 0.
+ * When it falls outside (e.g. a tiny trigger near a rounded corner), the
+ * returned delta tells the caller how far to translate the tooltip element
+ * so the clamped arrow ends up over the trigger center.
+ */
+declare function getArrowClampDelta({
+  width,
+  height,
+  placement,
+  borderRadius,
+  arrowCenter,
+  arrowWidth
+}: ArrowClampDeltaOptions): {
+  x: number;
+  y: number;
+};
+//#endregion
+export { ARROW_HEIGHT, ARROW_TIP_RADIUS_FRACTION, ARROW_WIDTH, type ArrowClampDeltaOptions, type ArrowSide, type ParsedShadow, type TooltipPathOptions, generateTooltipPath, getArrowClampDelta, getArrowSide, parseShadow };