@proyecto-viviana/solidaria-components 0.2.5 → 0.3.0

package/src/Tooltip.tsx

@@ -15,19 +15,19 @@ import {
   createEffect,
   onCleanup,
   Show,
-} from 'solid-js';
-import { isServer } from 'solid-js/web';
+} from "solid-js";
+import { isServer } from "solid-js/web";
 import {
   createTooltipTriggerState,
   type TooltipTriggerState,
   type TooltipTriggerProps as StateProps,
-} from '@proyecto-viviana/solid-stately';
+} from "@proyecto-viviana/solid-stately";
 import {
   createTooltip,
   createTooltipTrigger,
   type TooltipTriggerProps as AriaProps,
   OverlayContainer,
-} from '@proyecto-viviana/solidaria';
+} from "@proyecto-viviana/solidaria";
 import {
   type RenderChildren,
   type ClassNameOrFunction,
@@ -35,11 +35,7 @@ import {
   type SlotProps,
   useRenderProps,
   filterDOMProps,
-} from './utils';
-
-// ============================================
-// TYPES
-// ============================================
+} from "./utils";
 
 export interface TooltipRenderProps {
   /** Whether the tooltip is currently entering (for animations). */
@@ -47,15 +43,36 @@ export interface TooltipRenderProps {
   /** Whether the tooltip is currently exiting (for animations). */
   isExiting: boolean;
   /** The placement of the tooltip relative to the trigger. */
-  placement: 'top' | 'bottom' | 'left' | 'right' | null;
+  placement: TooltipResolvedPlacement | null;
 }
 
+export type TooltipPlacement = "top" | "bottom" | "left" | "right" | "start" | "end";
+export type TooltipResolvedPlacement = "top" | "bottom" | "left" | "right";
+
 export interface TooltipTriggerComponentProps extends StateProps, AriaProps {
   /** The children of the tooltip trigger (trigger element and tooltip). */
   children: JSX.Element;
+  /** The placement of the tooltip relative to the trigger. */
+  placement?: TooltipPlacement;
+  /** The placement padding between the tooltip and viewport edge. */
+  containerPadding?: number;
+  /** The additional offset along the cross axis. */
+  crossOffset?: number;
+  /** Whether the tooltip should flip when there is insufficient room. */
+  shouldFlip?: boolean;
 }
 
 export interface TooltipProps extends SlotProps {
+  /** The element id. */
+  id?: string;
+  /** Custom aria-label for the tooltip. */
+  "aria-label"?: string;
+  /** ID of an element that labels the tooltip. */
+  "aria-labelledby"?: string;
+  /** ID of an element that describes the tooltip. */
+  "aria-describedby"?: string;
+  /** ID of an element that provides details for the tooltip. */
+  "aria-details"?: string;
   /** The children of the tooltip. A function may be provided to receive render props. */
   children?: RenderChildren<TooltipRenderProps>;
   /** The CSS className for the element. */
@@ -67,26 +84,42 @@ export interface TooltipProps extends SlotProps {
   /** Whether the tooltip is open by default (uncontrolled). */
   defaultOpen?: boolean;
   /** The placement of the tooltip relative to the trigger. */
-  placement?: 'top' | 'bottom' | 'left' | 'right';
-  /** Whether to render the tooltip in a portal. */
+  placement?: TooltipPlacement;
+  /** The placement padding between the tooltip and viewport edge. */
+  containerPadding?: number;
+  /** The additional offset along the cross axis. */
+  crossOffset?: number;
+  /** Whether the tooltip should flip when there is insufficient room. */
   shouldFlip?: boolean;
+  /** The offset between the tooltip and trigger. */
+  offset?: number;
+  /** The arrow size used to keep the arrow overlapping the trigger. */
+  arrowSize?: number;
+  /** The padding between the arrow and tooltip edge. */
+  arrowBoundaryOffset?: number;
+  /** Whether the tooltip should be disabled. */
+  isDisabled?: boolean;
+  /** The element language. */
+  lang?: string;
+  /** The text direction. */
+  dir?: "ltr" | "rtl";
 }
 
-// ============================================
-// CONTEXT
-// ============================================
-
 interface TooltipTriggerContextValue {
   state: TooltipTriggerState;
-  tooltipProps: { id: string };
+  tooltipProps: { readonly id: string };
+  setTooltipId: (id: string | undefined) => void;
   triggerRef: () => HTMLElement | null | undefined;
+  placement: () => TooltipPlacement | undefined;
+  containerPadding: () => number | undefined;
+  crossOffset: () => number | undefined;
+  shouldFlip: () => boolean | undefined;
+  isDisabled: () => boolean | undefined;
 }
 
 const TooltipTriggerContext = createContext<TooltipTriggerContextValue | null>(null);
-
-// ============================================
-// COMPONENTS
-// ============================================
+export const TooltipContext = TooltipTriggerContext;
+export const TooltipTriggerStateContext = createContext<TooltipTriggerState | null>(null);
 
 /**
  * TooltipTrigger wraps around a trigger element and a Tooltip.
@@ -103,42 +136,68 @@ const TooltipTriggerContext = createContext<TooltipTriggerContextValue | null>(n
  */
 export const TooltipTrigger: ParentComponent<TooltipTriggerComponentProps> = (props) => {
   let triggerRef: HTMLElement | null = null;
+  const [tooltipId, setTooltipId] = createSignal<string | undefined>();
 
   const state = createTooltipTriggerState({
-    get delay() { return props.delay; },
-    get closeDelay() { return props.closeDelay; },
-    get isOpen() { return props.isOpen; },
-    get defaultOpen() { return props.defaultOpen; },
-    get onOpenChange() { return props.onOpenChange; },
+    get delay() {
+      return props.delay;
+    },
+    get closeDelay() {
+      return props.closeDelay;
+    },
+    get isOpen() {
+      return props.isOpen;
+    },
+    get defaultOpen() {
+      return props.defaultOpen;
+    },
+    get onOpenChange() {
+      return props.onOpenChange;
+    },
   });
 
   const { triggerProps, tooltipProps } = createTooltipTrigger(
     {
-      get isDisabled() { return props.isDisabled; },
-      get trigger() { return props.trigger; },
-      get shouldCloseOnPress() { return props.shouldCloseOnPress; },
+      get isDisabled() {
+        return props.isDisabled;
+      },
+      get trigger() {
+        return props.trigger;
+      },
+      get shouldCloseOnPress() {
+        return props.shouldCloseOnPress;
+      },
+      get tooltipId() {
+        return tooltipId();
+      },
     },
     state,
-    () => triggerRef
+    () => triggerRef,
   );
 
   const context: TooltipTriggerContextValue = {
     state,
     tooltipProps,
+    setTooltipId,
     triggerRef: () => triggerRef,
+    placement: () => props.placement,
+    containerPadding: () => props.containerPadding,
+    crossOffset: () => props.crossOffset,
+    shouldFlip: () => props.shouldFlip,
+    isDisabled: () => props.isDisabled,
   };
 
-  // Clone children and inject trigger props into the first child
   const processChildren = () => {
     const children = props.children;
     if (Array.isArray(children)) {
-      // First child is the trigger, rest are tooltip(s)
       const [trigger, ...rest] = children;
       return (
         <>
           <TriggerWrapper
             triggerProps={triggerProps}
-            ref={(el) => { triggerRef = el; }}
+            ref={(el) => {
+              triggerRef = el;
+            }}
           >
             {trigger}
           </TriggerWrapper>
@@ -150,9 +209,11 @@ export const TooltipTrigger: ParentComponent<TooltipTriggerComponentProps> = (pr
   };
 
   return (
-    <TooltipTriggerContext.Provider value={context}>
-      {processChildren()}
-    </TooltipTriggerContext.Provider>
+    <TooltipTriggerStateContext.Provider value={state}>
+      <TooltipTriggerContext.Provider value={context}>
+        {processChildren()}
+      </TooltipTriggerContext.Provider>
+    </TooltipTriggerStateContext.Provider>
   );
 };
 
@@ -163,13 +224,72 @@ const TriggerWrapper: ParentComponent<{
   triggerProps: JSX.HTMLAttributes<HTMLElement>;
   ref: (el: HTMLElement) => void;
 }> = (props) => {
-  // Get the child element and clone it with trigger props
   const child = () => props.children as JSX.Element;
+  const [triggerElement, setTriggerElement] = createSignal<HTMLElement | null>(null);
+
+  createEffect(() => {
+    const element = triggerElement();
+    if (!element) {
+      return;
+    }
+
+    const triggerProps = props.triggerProps as Record<string, unknown>;
+    const describedBy = triggerProps["aria-describedby"] as string | undefined;
+    if (describedBy) {
+      element.setAttribute("aria-describedby", describedBy);
+    } else {
+      element.removeAttribute("aria-describedby");
+    }
+
+    const listeners: Array<[string, EventListener]> = [];
+    const eventProps = [
+      ["onFocus", "focus"],
+      ["onBlur", "blur"],
+      ["onPointerEnter", "pointerenter"],
+      ["onPointerLeave", "pointerleave"],
+      ["onPointerOver", "pointerover"],
+      ["onPointerOut", "pointerout"],
+      ["onMouseEnter", "mouseenter"],
+      ["onMouseLeave", "mouseleave"],
+      ["onTouchStart", "touchstart"],
+      ["onPointerDown", "pointerdown"],
+      ["onKeyDown", "keydown"],
+    ] as const;
+
+    for (const [propName, eventName] of eventProps) {
+      const handler = triggerProps[propName];
+      if (typeof handler === "function") {
+        const listener = handler as EventListener;
+        element.addEventListener(eventName, listener);
+        listeners.push([eventName, listener]);
+      }
+    }
+
+    onCleanup(() => {
+      for (const [eventName, listener] of listeners) {
+        element.removeEventListener(eventName, listener);
+      }
+      if (describedBy && element.getAttribute("aria-describedby") === describedBy) {
+        element.removeAttribute("aria-describedby");
+      }
+    });
+  });
 
   // We wrap in a span with display:contents to not affect layout.
   // However, display:contents makes getBoundingClientRect return zeros,
   // so we pass a ref callback that finds the first actual element child.
   const handleRef = (span: HTMLSpanElement) => {
+    const findElementChild = (el: Element): HTMLElement | null => {
+      for (const child of el.children) {
+        if (child instanceof HTMLElement) {
+          return child;
+        }
+        const found = findElementChild(child);
+        if (found) return found;
+      }
+      return null;
+    };
+
     // Find the first element child that has dimensions (not display:contents)
     const findVisibleChild = (el: Element): HTMLElement | null => {
       if (el instanceof HTMLElement) {
@@ -177,7 +297,6 @@ const TriggerWrapper: ParentComponent<{
         if (rect.width > 0 && rect.height > 0) {
           return el;
         }
-        // Check children
         for (const child of el.children) {
           const found = findVisibleChild(child);
           if (found) return found;
@@ -189,31 +308,28 @@ const TriggerWrapper: ParentComponent<{
     // Use requestAnimationFrame to ensure children are rendered and have dimensions
     // This is necessary because SolidJS may not have computed child layout yet
     const resolveRef = () => {
+      const elementChild = findElementChild(span);
       const visibleChild = findVisibleChild(span);
-      if (visibleChild) {
-        props.ref(visibleChild);
-      } else {
-        // Fallback to span itself
-        props.ref(span);
-      }
+      setTriggerElement(elementChild ?? visibleChild ?? span);
+      props.ref(visibleChild ?? elementChild ?? span);
     };
 
-    // Try immediately first (in case layout is already computed)
+    const elementChild = findElementChild(span);
+    if (elementChild) {
+      setTriggerElement(elementChild);
+    }
+
     const immediateChild = findVisibleChild(span);
     if (immediateChild) {
+      setTriggerElement(elementChild ?? immediateChild);
       props.ref(immediateChild);
     } else {
-      // Defer to next frame when layout should be computed
       requestAnimationFrame(resolveRef);
     }
   };
 
   return (
-    <span
-      {...props.triggerProps}
-      ref={handleRef}
-      style={{ display: 'contents' }}
-    >
+    <span ref={handleRef} style={{ display: "contents" }}>
       {child()}
     </span>
   );
@@ -233,26 +349,98 @@ const TriggerWrapper: ParentComponent<{
 export function Tooltip(props: TooltipProps): JSX.Element {
   const context = useContext(TooltipTriggerContext);
 
-  // Support standalone usage
+  createEffect(() => {
+    context?.setTooltipId(props.id);
+    onCleanup(() => {
+      context?.setTooltipId(undefined);
+    });
+  });
+
   const localState = createTooltipTriggerState({
-    get isOpen() { return props.isOpen; },
-    get defaultOpen() { return props.defaultOpen; },
+    get isOpen() {
+      return props.isOpen;
+    },
+    get defaultOpen() {
+      return props.defaultOpen;
+    },
   });
 
   const state = () => context?.state ?? localState;
-  const placement = () => props.placement ?? 'top';
+  const placement = () => props.placement ?? context?.placement() ?? "top";
+  const containerPadding = () => props.containerPadding ?? context?.containerPadding() ?? 12;
+  const crossOffset = () => props.crossOffset ?? context?.crossOffset() ?? 0;
+  const shouldFlip = () => props.shouldFlip ?? context?.shouldFlip() ?? true;
+  const offset = () => props.offset ?? 9;
+  const arrowSize = () => props.arrowSize ?? 0;
+  const arrowBoundaryOffset = () => props.arrowBoundaryOffset ?? 0;
+  const isDisabled = () => props.isDisabled ?? context?.isDisabled() ?? false;
+
+  const isOpen = () => !isDisabled() && state().isOpen();
+
+  // Exit animation state machine: 'closed' | 'open' | 'exiting'
+  // Keeps the tooltip mounted during exit animation so CSS transitions can play.
+  const [exitState, setExitState] = createSignal<"closed" | "open" | "exiting">(
+    isOpen() ? "open" : "closed",
+  );
+
+  createEffect(() => {
+    const open = isOpen();
+    const current = exitState();
+    if (current === "open" && !open) {
+      setExitState("exiting");
+    } else if ((current === "closed" || current === "exiting") && open) {
+      setExitState("open");
+    }
+  });
+
+  // Signal for the tooltip ref so we can observe exit animations
+  const [tooltipEl, setTooltipEl] = createSignal<HTMLDivElement | null>(null);
+
+  // When exiting, wait for CSS animations to finish, then set state to closed
+  createEffect(() => {
+    if (exitState() !== "exiting") return;
+    const el = tooltipEl();
+    if (!el || !("getAnimations" in el)) {
+      setExitState("closed");
+      return;
+    }
+    const animations = el.getAnimations();
+    if (animations.length === 0) {
+      setExitState("closed");
+      return;
+    }
+    let canceled = false;
+    Promise.all(animations.map((a) => a.finished))
+      .then(() => {
+        if (!canceled) setExitState((s) => (s === "exiting" ? "closed" : s));
+      })
+      .catch(() => {
+        if (!canceled) setExitState((s) => (s === "exiting" ? "closed" : s));
+      });
+    onCleanup(() => {
+      canceled = true;
+    });
+  });
 
-  // Only render when open
-  const isOpen = () => state().isOpen();
+  const shouldRender = () => isOpen() || exitState() === "exiting";
+  const isExiting = () => exitState() === "exiting";
 
   return (
-    <Show when={isOpen()}>
+    <Show when={shouldRender()}>
       <TooltipContent
         {...props}
         state={state()}
         contextTooltipProps={context?.tooltipProps ?? {}}
         placement={placement()}
+        containerPadding={containerPadding()}
+        crossOffset={crossOffset()}
+        shouldFlip={shouldFlip()}
+        offset={offset()}
+        arrowSize={arrowSize()}
+        arrowBoundaryOffset={arrowBoundaryOffset()}
         triggerRef={context?.triggerRef ?? (() => null)}
+        isExiting={isExiting()}
+        onTooltipRef={setTooltipEl}
       />
     </Show>
   );
@@ -264,10 +452,18 @@ export function Tooltip(props: TooltipProps): JSX.Element {
 function TooltipContent(
   props: TooltipProps & {
     state: TooltipTriggerState;
-    contextTooltipProps: { id?: string };
-    placement: 'top' | 'bottom' | 'left' | 'right';
+    contextTooltipProps: { readonly id?: string };
+    placement: TooltipPlacement;
+    containerPadding: number;
+    crossOffset: number;
+    shouldFlip: boolean;
+    offset: number;
+    arrowSize: number;
+    arrowBoundaryOffset: number;
     triggerRef: () => HTMLElement | null | undefined;
-  }
+    isExiting: boolean;
+    onTooltipRef: (el: HTMLDivElement | null) => void;
+  },
 ): JSX.Element {
   if (isServer) {
     return null as unknown as JSX.Element;
@@ -276,20 +472,57 @@ function TooltipContent(
   let tooltipRef!: HTMLDivElement;
   const { tooltipProps: ariaTooltipProps } = createTooltip({}, props.state);
 
-  // Signal to track position styles
   // Start visible at 0,0 and update position asynchronously
   // This ensures the tooltip is immediately accessible (for screen readers and tests)
   // while the visual position gets calculated
   const [positionStyles, setPositionStyles] = createSignal({
-    top: '0px',
-    left: '0px',
-    visibility: 'visible' as 'hidden' | 'visible',
+    top: "0px",
+    left: "0px",
+    visibility: "visible" as "hidden" | "visible",
+  });
+  const [renderedPlacement, setRenderedPlacement] = createSignal<TooltipResolvedPlacement>(
+    resolvePlacement(props.placement),
+  );
+
+  // Enter animation state: starts true on mount, clears after first animation frame.
+  // Uses getAnimations() to detect CSS animations/transitions - if none exist (JSDOM,
+  // no CSS defined, reduced-motion), clears immediately.
+  const [isEntering, setIsEntering] = createSignal(true);
+
+  createEffect(() => {
+    if (!isEntering()) return;
+    if (!tooltipRef || !("getAnimations" in tooltipRef)) {
+      setIsEntering(false);
+      return;
+    }
+    // Cancel any premature CSS transitions triggered before layout
+    for (const anim of tooltipRef.getAnimations()) {
+      if (anim instanceof CSSTransition) {
+        anim.cancel();
+      }
+    }
+    const animations = tooltipRef.getAnimations();
+    if (animations.length === 0) {
+      setIsEntering(false);
+      return;
+    }
+    let canceled = false;
+    Promise.all(animations.map((a) => a.finished))
+      .then(() => {
+        if (!canceled) setIsEntering(false);
+      })
+      .catch(() => {
+        if (!canceled) setIsEntering(false);
+      });
+    onCleanup(() => {
+      canceled = true;
+    });
   });
 
   const values = createMemo<TooltipRenderProps>(() => ({
-    isEntering: false, // TODO: animation support
-    isExiting: false,
-    placement: props.placement,
+    isEntering: isEntering(),
+    isExiting: props.isExiting,
+    placement: renderedPlacement(),
   }));
 
   const renderProps = useRenderProps(
@@ -297,13 +530,13 @@ function TooltipContent(
       class: props.class,
       style: props.style,
       children: props.children,
-      defaultClassName: 'solidaria-Tooltip',
+      defaultClassName: "solidaria-Tooltip",
     },
-    values
+    values,
   );
 
-  // Calculate position based on trigger element
-  // Using position: fixed so we use viewport coordinates directly from getBoundingClientRect
+  // Position the overlay in document coordinates, matching React Aria's
+  // absolute overlay positioning when the portal container is the document.
   // Returns true if position was successfully updated, false if we need to retry
   const updatePosition = (): boolean => {
     const triggerEl = props.triggerRef();
@@ -320,98 +553,166 @@ function TooltipContent(
     // when the element might be positioned off-screen initially
     const tooltipWidth = tooltipRef.offsetWidth;
     const tooltipHeight = tooltipRef.offsetHeight;
-    const offset = 8; // Gap between trigger and tooltip
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    const containerPadding = props.containerPadding;
+    const crossOffset = props.crossOffset;
+    const placement = maybeFlipPlacement(
+      resolvePlacement(props.placement),
+      triggerRect,
+      tooltipWidth,
+      tooltipHeight,
+      viewportWidth,
+      viewportHeight,
+      containerPadding,
+      props.offset,
+      props.shouldFlip,
+    );
 
     let top = 0;
     let left = 0;
 
-    // Using viewport coordinates for position: fixed
-    switch (props.placement) {
-      case 'top':
-        top = triggerRect.top - tooltipHeight - offset;
-        left = triggerRect.left + (triggerRect.width - tooltipWidth) / 2;
+    switch (placement) {
+      case "top":
+        top = triggerRect.top - tooltipHeight - props.offset;
+        left = triggerRect.left + (triggerRect.width - tooltipWidth) / 2 + crossOffset;
         break;
-      case 'bottom':
-        top = triggerRect.bottom + offset;
-        left = triggerRect.left + (triggerRect.width - tooltipWidth) / 2;
+      case "bottom":
+        top = triggerRect.bottom + props.offset;
+        left = triggerRect.left + (triggerRect.width - tooltipWidth) / 2 + crossOffset;
         break;
-      case 'left':
-        top = triggerRect.top + (triggerRect.height - tooltipHeight) / 2;
-        left = triggerRect.left - tooltipWidth - offset;
+      case "left":
+        top = triggerRect.top + (triggerRect.height - tooltipHeight) / 2 + crossOffset;
+        left = triggerRect.left - tooltipWidth - props.offset;
         break;
-      case 'right':
-        top = triggerRect.top + (triggerRect.height - tooltipHeight) / 2;
-        left = triggerRect.right + offset;
+      case "right":
+        top = triggerRect.top + (triggerRect.height - tooltipHeight) / 2 + crossOffset;
+        left = triggerRect.right + props.offset;
         break;
     }
 
+    if (placement === "top" || placement === "bottom") {
+      left = clamp(
+        left,
+        triggerRect.left - tooltipWidth + props.arrowSize + props.arrowBoundaryOffset,
+        triggerRect.left + triggerRect.width - props.arrowSize - props.arrowBoundaryOffset,
+      );
+      left = clamp(left, containerPadding, viewportWidth - tooltipWidth - containerPadding);
+    } else {
+      top = clamp(
+        top,
+        triggerRect.top - tooltipHeight + props.arrowSize + props.arrowBoundaryOffset,
+        triggerRect.top + triggerRect.height - props.arrowSize - props.arrowBoundaryOffset,
+      );
+      top = clamp(top, containerPadding, viewportHeight - tooltipHeight - containerPadding);
+    }
+    setRenderedPlacement(placement);
     setPositionStyles({
-      top: `${top}px`,
-      left: `${left}px`,
-      visibility: 'visible',
+      top: `${Math.floor(top + window.scrollY)}px`,
+      left: `${Math.floor(left + window.scrollX)}px`,
+      visibility: "visible",
     });
 
     return true;
   };
 
-  // Set up positioning effect - runs when trigger ref is available
+  // Set up positioning and scroll-close effects. Positioning retries while the
+  // trigger ref resolves, and pending rAF/setTimeout IDs are canceled on cleanup.
   createEffect(() => {
-    const trigger = props.triggerRef();
-    if (!trigger) return;
+    // Track positioning inputs synchronously so updates from controlled route
+    // props reschedule measurement even though layout reads happen in rAF.
+    props.placement;
+    props.containerPadding;
+    props.crossOffset;
+    props.shouldFlip;
+    props.offset;
+    props.arrowSize;
+    props.arrowBoundaryOffset;
 
-    // Initial position calculation - use requestAnimationFrame to ensure
-    // the element is rendered and has proper dimensions
-    // We may need multiple frames if the trigger ref hasn't resolved yet
     let retryCount = 0;
     const maxRetries = 5;
+    let pendingRaf = 0;
+    let pendingTimeout = 0;
 
     const tryUpdatePosition = () => {
+      pendingRaf = 0;
+      pendingTimeout = 0;
       const success = updatePosition();
       if (!success && retryCount < maxRetries) {
         retryCount++;
-        // In JSDOM, requestAnimationFrame may not trigger layout properly
-        // Use setTimeout for more reliable deferral across environments
-        setTimeout(tryUpdatePosition, 16); // ~60fps
+        pendingTimeout = window.setTimeout(tryUpdatePosition, 16);
       }
-      // If all retries fail, tooltip stays at 0,0 (test environments)
-      // The tooltip is visible by default, so it remains accessible
     };
 
-    // Initial attempt - use rAF for real browsers, then fall back to timeout retries
-    requestAnimationFrame(tryUpdatePosition);
+    pendingRaf = requestAnimationFrame(tryUpdatePosition);
+
+    const closeOnScroll = (event: Event) => {
+      const trigger = props.triggerRef();
+      const target = event.target;
+      if (!trigger || (target instanceof Node && !target.contains(trigger))) {
+        return;
+      }
+      if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+        return;
+      }
 
-    // Update on scroll/resize
-    window.addEventListener('scroll', updatePosition, true);
-    window.addEventListener('resize', updatePosition);
+      props.state.close(true);
+    };
+
+    window.addEventListener("scroll", closeOnScroll, true);
+    window.addEventListener("resize", updatePosition);
 
     onCleanup(() => {
-      window.removeEventListener('scroll', updatePosition, true);
-      window.removeEventListener('resize', updatePosition);
+      if (pendingRaf) cancelAnimationFrame(pendingRaf);
+      if (pendingTimeout) clearTimeout(pendingTimeout);
+      window.removeEventListener("scroll", closeOnScroll, true);
+      window.removeEventListener("resize", updatePosition);
     });
   });
 
-  // Filter to only valid DOM props (aria-*, data-*, events)
-  const domProps = filterDOMProps(props);
+  const domProps = filterDOMProps(props, { global: true });
+  const tooltipId = () => props.contextTooltipProps.id ?? (domProps as { id?: string }).id;
 
   // Extract ref from ariaTooltipProps to avoid type conflicts (SolidJS ref types are element-specific)
   const { ref: _ariaRef, ...cleanAriaProps } = ariaTooltipProps as Record<string, unknown>;
 
+  const setRef = (el: HTMLDivElement) => {
+    tooltipRef = el;
+    if (!props.dir) {
+      el.dir = getDocumentDirection();
+    }
+    if (!props.lang) {
+      const documentLang = document.documentElement.lang;
+      const navigatorLang = typeof navigator !== "undefined" ? navigator.language : "";
+      el.lang = documentLang.includes("-")
+        ? documentLang
+        : navigatorLang || documentLang || "en-US";
+    }
+    props.onTooltipRef(el);
+  };
+
+  onCleanup(() => {
+    props.onTooltipRef(null);
+  });
+
   return (
     <OverlayContainer>
       <div
         {...domProps}
-        {...props.contextTooltipProps}
         {...cleanAriaProps}
+        id={tooltipId()}
         role="tooltip"
-        ref={tooltipRef}
+        ref={setRef}
         class={renderProps.class()}
         style={{
-          position: 'fixed',
-          'z-index': 100000,
+          position: "absolute",
+          "z-index": 100000,
           ...positionStyles(),
           ...renderProps.style(),
         }}
-        data-placement={props.placement}
+        data-placement={renderedPlacement()}
+        data-entering={isEntering() || undefined}
+        data-exiting={props.isExiting || undefined}
       >
         {renderProps.renderChildren()}
       </div>
@@ -419,5 +720,61 @@ function TooltipContent(
   );
 }
 
-// Re-export types
+function resolvePlacement(placement: TooltipPlacement): TooltipResolvedPlacement {
+  if (placement === "start") {
+    return getDocumentDirection() === "rtl" ? "right" : "left";
+  }
+  if (placement === "end") {
+    return getDocumentDirection() === "rtl" ? "left" : "right";
+  }
+  return placement;
+}
+
+function getDocumentDirection(): "ltr" | "rtl" {
+  if (typeof document === "undefined") {
+    return "ltr";
+  }
+
+  return document.documentElement.dir === "rtl" ? "rtl" : "ltr";
+}
+
+function maybeFlipPlacement(
+  placement: TooltipResolvedPlacement,
+  triggerRect: DOMRect,
+  tooltipWidth: number,
+  tooltipHeight: number,
+  viewportWidth: number,
+  viewportHeight: number,
+  containerPadding: number,
+  offset: number,
+  shouldFlip: boolean,
+): TooltipResolvedPlacement {
+  if (!shouldFlip) {
+    return placement;
+  }
+
+  switch (placement) {
+    case "top":
+      return triggerRect.top - tooltipHeight - offset < containerPadding ? "bottom" : placement;
+    case "bottom":
+      return triggerRect.bottom + tooltipHeight + offset > viewportHeight - containerPadding
+        ? "top"
+        : placement;
+    case "left":
+      return triggerRect.left - tooltipWidth - offset < containerPadding ? "right" : placement;
+    case "right":
+      return triggerRect.right + tooltipWidth + offset > viewportWidth - containerPadding
+        ? "left"
+        : placement;
+  }
+}
+
+function clamp(value: number, min: number, max: number): number {
+  if (max < min) {
+    return min;
+  }
+
+  return Math.min(Math.max(value, min), max);
+}
+
 export type { TooltipTriggerState };