@proyecto-viviana/solidaria-components 0.2.9 → 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,29 +84,43 @@ 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);
 export const TooltipContext = TooltipTriggerContext;
 export const TooltipTriggerStateContext = createContext<TooltipTriggerState | null>(null);
 
-// ============================================
-// COMPONENTS
-// ============================================
-
 /**
  * TooltipTrigger wraps around a trigger element and a Tooltip.
  * It handles opening and closing the Tooltip when the user hovers
@@ -105,42 +136,68 @@ export const TooltipTriggerStateContext = createContext<TooltipTriggerState | nu
  */
 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>
@@ -167,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) {
@@ -181,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;
@@ -193,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>
   );
@@ -237,30 +349,47 @@ 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 = () => state().isOpen();
+  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'
+  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');
+    if (current === "open" && !open) {
+      setExitState("exiting");
+    } else if ((current === "closed" || current === "exiting") && open) {
+      setExitState("open");
     }
   });
 
@@ -269,26 +398,32 @@ export function Tooltip(props: TooltipProps): JSX.Element {
 
   // When exiting, wait for CSS animations to finish, then set state to closed
   createEffect(() => {
-    if (exitState() !== 'exiting') return;
+    if (exitState() !== "exiting") return;
     const el = tooltipEl();
-    if (!el || !('getAnimations' in el)) {
-      setExitState('closed');
+    if (!el || !("getAnimations" in el)) {
+      setExitState("closed");
       return;
     }
     const animations = el.getAnimations();
     if (animations.length === 0) {
-      setExitState('closed');
+      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; });
+      .then(() => {
+        if (!canceled) setExitState((s) => (s === "exiting" ? "closed" : s));
+      })
+      .catch(() => {
+        if (!canceled) setExitState((s) => (s === "exiting" ? "closed" : s));
+      });
+    onCleanup(() => {
+      canceled = true;
+    });
   });
 
-  const shouldRender = () => isOpen() || exitState() === 'exiting';
-  const isExiting = () => exitState() === 'exiting';
+  const shouldRender = () => isOpen() || exitState() === "exiting";
+  const isExiting = () => exitState() === "exiting";
 
   return (
     <Show when={shouldRender()}>
@@ -297,6 +432,12 @@ export function Tooltip(props: TooltipProps): JSX.Element {
         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}
@@ -311,12 +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;
@@ -325,15 +472,17 @@ 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,
@@ -342,7 +491,7 @@ function TooltipContent(
 
   createEffect(() => {
     if (!isEntering()) return;
-    if (!tooltipRef || !('getAnimations' in tooltipRef)) {
+    if (!tooltipRef || !("getAnimations" in tooltipRef)) {
       setIsEntering(false);
       return;
     }
@@ -359,15 +508,21 @@ function TooltipContent(
     }
     let canceled = false;
     Promise.all(animations.map((a) => a.finished))
-      .then(() => { if (!canceled) setIsEntering(false); })
-      .catch(() => { if (!canceled) setIsEntering(false); });
-    onCleanup(() => { canceled = true; });
+      .then(() => {
+        if (!canceled) setIsEntering(false);
+      })
+      .catch(() => {
+        if (!canceled) setIsEntering(false);
+      });
+    onCleanup(() => {
+      canceled = true;
+    });
   });
 
   const values = createMemo<TooltipRenderProps>(() => ({
     isEntering: isEntering(),
     isExiting: props.isExiting,
-    placement: props.placement,
+    placement: renderedPlacement(),
   }));
 
   const renderProps = useRenderProps(
@@ -375,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();
@@ -398,45 +553,81 @@ 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.
-  // Tracks pending rAF/setTimeout IDs so they can be canceled on cleanup.
+  // 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;
 
     let retryCount = 0;
     const maxRetries = 5;
@@ -455,30 +646,51 @@ function TooltipContent(
 
     pendingRaf = requestAnimationFrame(tryUpdatePosition);
 
-    // Update on scroll/resize
-    window.addEventListener('scroll', updatePosition, true);
-    window.addEventListener('resize', updatePosition);
+    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;
+      }
+
+      props.state.close(true);
+    };
+
+    window.addEventListener("scroll", closeOnScroll, true);
+    window.addEventListener("resize", updatePosition);
 
     onCleanup(() => {
       if (pendingRaf) cancelAnimationFrame(pendingRaf);
       if (pendingTimeout) clearTimeout(pendingTimeout);
-      window.removeEventListener('scroll', updatePosition, true);
-      window.removeEventListener('resize', updatePosition);
+      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);
   };
 
-  // Clean up ref on unmount
   onCleanup(() => {
     props.onTooltipRef(null);
   });
@@ -487,18 +699,18 @@ function TooltipContent(
     <OverlayContainer>
       <div
         {...domProps}
-        {...props.contextTooltipProps}
         {...cleanAriaProps}
+        id={tooltipId()}
         role="tooltip"
         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}
       >
@@ -508,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 };