@cosxai/ui 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "COSX design system — React 19 component primitives shared across product-meta and other consumers",
   "license": "UNLICENSED",
   "type": "module",

package/src/primitives/Tooltip.tsx

@@ -29,23 +29,43 @@ export interface TooltipProps {
   }>;
   // ms before showing. Default 120.
   delay?: number;
-  // "top" hovers above the trigger, "bottom" below. Default "top".
-  placement?: "top" | "bottom";
+  // "top" hovers above the trigger, "bottom" below, "auto" prefers
+  // top but flips to bottom when the trigger sits near the viewport
+  // top edge (would otherwise clip against the browser chrome).
+  // Default "auto".
+  placement?: "top" | "bottom" | "auto";
   // Render even if `content` is falsy. Default false — callers can
   // wrap unconditionally without branching JSX.
   alwaysRender?: boolean;
+  // When true, force the tooltip to a single line and truncate
+  // overflow with an ellipsis. Default false — content wraps to
+  // multiple lines within `maxWidth`. Existing single-line labels
+  // (scan-status pill, date row) render identically because they
+  // fit within maxWidth without wrapping; longer hints (explanatory
+  // text under form fields, etc.) now display in full.
+  truncate?: boolean;
 }
 
+// AUTO_FLIP_THRESHOLD_PX = the vertical space "top" placement needs
+// above the trigger (tooltip height + gap + a bit of breathing room).
+// Trigger positioned closer than this to the viewport top gets a
+// bottom-flip.
+const AUTO_FLIP_THRESHOLD_PX = 48;
+
 export function Tooltip({
   content,
   children,
   delay = 120,
-  placement = "top",
+  placement = "auto",
   alwaysRender = false,
+  truncate = false,
 }: TooltipProps) {
   const triggerRef = useRef<HTMLElement | null>(null);
   const [open, setOpen] = useState(false);
   const [pos, setPos] = useState<{ x: number; y: number } | null>(null);
+  const [resolvedPlacement, setResolvedPlacement] = useState<"top" | "bottom">(
+    placement === "bottom" ? "bottom" : "top",
+  );
   const timerRef = useRef<number | null>(null);
 
   const cancelTimer = useCallback(() => {
@@ -59,9 +79,18 @@ export function Tooltip({
     const el = triggerRef.current;
     if (!el) return;
     const r = el.getBoundingClientRect();
+    // "auto" resolves to top when there's enough room above, else
+    // bottom. Explicit "top" / "bottom" are honoured verbatim.
+    let effective: "top" | "bottom";
+    if (placement === "auto") {
+      effective = r.top < AUTO_FLIP_THRESHOLD_PX ? "bottom" : "top";
+    } else {
+      effective = placement;
+    }
+    setResolvedPlacement(effective);
     setPos({
       x: r.left + r.width / 2,
-      y: placement === "top" ? r.top : r.bottom,
+      y: effective === "top" ? r.top : r.bottom,
     });
   }, [placement]);
 
@@ -137,7 +166,7 @@ export function Tooltip({
     left: pos?.x ?? -9999,
     top: pos?.y ?? -9999,
     transform:
-      placement === "top"
+      resolvedPlacement === "top"
         ? "translate(-50%, calc(-100% - 8px))"
         : "translate(-50%, 8px)",
     background: "var(--ck-bg-surface)",
@@ -153,9 +182,22 @@ export function Tooltip({
     pointerEvents: "none",
     zIndex: 9999,
     maxWidth: 320,
-    whiteSpace: "nowrap",
-    overflow: "hidden",
-    textOverflow: "ellipsis",
+    // Default: wrap long hints. Opt-in `truncate` restores the old
+    // single-line-with-ellipsis behaviour for compact labels where
+    // horizontal overflow is preferable to a taller tooltip (e.g.
+    // dense toolbars). Single-line labels shorter than maxWidth
+    // render identically in both modes — the branch only matters
+    // when content would need multiple lines.
+    ...(truncate
+      ? {
+          whiteSpace: "nowrap" as const,
+          overflow: "hidden" as const,
+          textOverflow: "ellipsis" as const,
+        }
+      : {
+          whiteSpace: "normal" as const,
+          wordBreak: "break-word" as const,
+        }),
     opacity: open && pos ? 1 : 0,
     transition: "opacity 120ms ease",
   };