@flamingo-stack/openframe-frontend-core 0.0.490 → 0.0.491-snapshot.20260729075221

package/src/components/ui/truncate-text.tsx

@@ -1,6 +1,7 @@
 'use client'
 
-import React, { type ReactNode, useEffect, useRef, useState } from 'react'
+import { type ReactNode } from 'react'
+import { useIsTruncated } from '../../hooks/ui/use-is-truncated'
 import { cn } from '../../utils/cn'
 import { FloatingTooltip } from './floating-tooltip'
 
@@ -69,24 +70,8 @@ export function TruncateText({
   tone = 'primary',
   mono = false,
 }: TruncateTextProps) {
-  const ref = useRef<HTMLSpanElement>(null)
-  const [isTruncated, setIsTruncated] = useState(false)
   const isMultiLine = lines > 1
-
-  useEffect(() => {
-    const el = ref.current
-    if (!el) return
-    const check = () => {
-      const overflows = isMultiLine
-        ? el.scrollHeight > el.clientHeight + 1
-        : el.scrollWidth > el.clientWidth + 1
-      setIsTruncated(overflows)
-    }
-    check()
-    const ro = new ResizeObserver(check)
-    ro.observe(el)
-    return () => ro.disconnect()
-  }, [children, isMultiLine])
+  const { ref, isTruncated } = useIsTruncated<HTMLSpanElement>(children, { multiline: isMultiLine })
 
   const clampClass = isMultiLine
     ? LINE_CLAMP_CLASS[lines as Exclude<typeof lines, 1>]

package/src/hooks/ui/index.ts

@@ -6,6 +6,7 @@ export * from './use-focus-trap'
 export * from './use-header-height'
 export * from './use-horizontal-scrollbar'
 export * from './use-image-edge-color'
+export * from './use-is-truncated'
 export * from './use-local-storage'
 export * from './use-marquee-engine'
 export * from './use-media-query'

package/src/hooks/ui/use-is-truncated.ts

@@ -0,0 +1,66 @@
+'use client'
+
+import { useCallback, useEffect, useState } from 'react'
+
+export interface UseIsTruncatedOptions {
+  /** Measure vertical clipping (`line-clamp-N`) instead of the single-line ellipsis. */
+  multiline?: boolean
+}
+
+/**
+ * Tracks whether an element's text is ACTUALLY clipped — the condition for
+ * offering a "full value" tooltip. Text that fits needs no tooltip, and showing
+ * one anyway just repeats what the user is already reading.
+ *
+ * Three things can change the answer, and all three are watched: the box
+ * resizing (`ResizeObserver`), the text itself changing, and the measured
+ * ELEMENT changing. None of them implies the others — new text inside a
+ * width-constrained box leaves the box exactly as it was, so the observer never
+ * fires; and a caller that swaps between render branches (adornment vs plain)
+ * mounts a different node under the same text, which a `useRef` would leave
+ * measured against the old, detached node. Pass the rendered value as `value`.
+ *
+ * `ref` is a CALLBACK ref, not a `RefObject` — that is what makes the element
+ * itself a dependency. Attach it exactly like a normal ref; there is no
+ * `.current` to read.
+ *
+ * ```tsx
+ * const { ref, isTruncated } = useIsTruncated<HTMLHeadingElement>(title)
+ * <FloatingTooltip content={title} disabled={!isTruncated}>
+ *   <h1 ref={ref} className="truncate">{title}</h1>
+ * </FloatingTooltip>
+ * ```
+ */
+export function useIsTruncated<T extends HTMLElement>(value: unknown, options?: UseIsTruncatedOptions) {
+  const multiline = options?.multiline ?? false
+  const [element, setElement] = useState<T | null>(null)
+  const [isTruncated, setIsTruncated] = useState(false)
+
+  // Wrapped so the identity stays stable across renders: passing the raw
+  // `useState` setter as a ref would be stable too, but this keeps the public
+  // shape a plain `RefCallback<T>` instead of a state dispatcher.
+  const ref = useCallback((node: T | null) => setElement(node), [])
+
+  useEffect(() => {
+    if (!element) {
+      setIsTruncated(false)
+      return
+    }
+    // The 1px tolerance absorbs sub-pixel layout rounding, which otherwise
+    // reports a permanent fractional "overflow" at some zoom levels / DPRs and
+    // leaves a tooltip armed on text that is fully visible.
+    const check = () => {
+      setIsTruncated(
+        multiline
+          ? element.scrollHeight > element.clientHeight + 1
+          : element.scrollWidth > element.clientWidth + 1,
+      )
+    }
+    check()
+    const observer = new ResizeObserver(check)
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [element, value, multiline])
+
+  return { ref, isTruncated }
+}