@flamingo-stack/openframe-frontend-core 0.0.490 → 0.0.491

package/src/components/ui/page-actions.tsx

@@ -6,6 +6,7 @@ import { Chevron02DownIcon } from '../icons-v2-generated'
 import { ActionsMenuDropdown, type ActionsMenuGroup, type ActionsMenuItem } from './actions-menu'
 import type { ButtonProps, SplitButtonIconAction } from './button'
 import { Button, SplitButton } from './button'
+import { Skeleton } from './skeleton'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './tooltip'
 
 export type PageActionButton = {
@@ -206,26 +207,104 @@ export interface PageActionsProps {
    */
   selector?: React.ReactNode
   className?: string
+  /**
+   * Render placeholders instead of the actions — for pages whose action SET
+   * depends on data still in flight. Opt-in: a page whose actions are already
+   * final while its title loads keeps rendering them.
+   */
+  loading?: boolean
 }
 
 const ACTIONS_GAP = 'gap-[var(--spacing-system-xs)]'
 
+/** Matches `Button` size="icon" / size="default" exactly, so a placeholder and the
+ *  button that replaces it occupy the same box at both breakpoints. `rounded-md`
+ *  is the same token `Button` itself uses — a raw `6px` would agree today and
+ *  drift the moment a platform overrides `--radius`. */
+const SKELETON_HEIGHT = 'h-11 md:h-12'
+const SKELETON_ICON_WIDTH = 'w-11 md:w-12'
+const SKELETON_LABEL_WIDTH = 'w-[120px] md:w-[140px]'
+const SKELETON_RADIUS = 'rounded-md'
+
+/**
+ * Placeholders for actions whose SHAPE isn't known yet — the page is still
+ * loading the record that decides which actions exist (e.g. an archived entity
+ * offers "Unarchive" where an active one offers "Edit").
+ *
+ * Why not render the actions anyway: a button is a promise. Painting the
+ * optimistic set means a flash of the wrong header AND a live click target that
+ * can act on the wrong assumption before the data lands. A grey box promises
+ * nothing and can't be clicked.
+ *
+ * The placeholders are derived from the actions the caller passed — one per
+ * action, each sized like the button that action WILL render — so the common
+ * case (the data confirms that set) settles with no layout shift at all. Sizing
+ * per action matters: `renderRawActionButton` collapses a label-less action (or
+ * one flagged `iconOnlyOnDesktop`) to a square `size="icon"` button, and a
+ * 140px-wide placeholder snapping to 48px is exactly the shift this is meant to
+ * avoid.
+ *
+ * An empty list still yields one placeholder: `loading` means the action set is
+ * unknown, not known-empty. Its shape comes from `emptyFallback`, because what
+ * an empty header settles into differs per variant — `icon-buttons` and
+ * `menu-primary` fall back to the square "…" overflow trigger, `primary-buttons`
+ * has no overflow trigger at all and settles into a labelled button.
+ */
+function ActionSkeletons({
+  actions,
+  fullWidth,
+  emptyFallback = 'icon',
+}: {
+  actions: PageActionButton[]
+  fullWidth?: boolean
+  emptyFallback?: 'icon' | 'label'
+}) {
+  const items = actions.length > 0 ? actions : [null]
+  return (
+    <>
+      {items.map((action, idx) => {
+        // Mirrors `renderRawActionButton`'s `isIconOnly`. The mobile bottom bar
+        // stretches only labelled buttons (`fullWidth: !!action.label`), so an
+        // icon action keeps its square box there too.
+        const isIconOnly = action ? !action.label || !!action.iconOnlyOnDesktop : emptyFallback === 'icon'
+        return (
+          <Skeleton
+            // Static placeholder list — index IS the identity here.
+            key={`action-skeleton-${idx}`}
+            className={cn(
+              SKELETON_HEIGHT,
+              SKELETON_RADIUS,
+              isIconOnly ? SKELETON_ICON_WIDTH : fullWidth ? 'flex-1' : SKELETON_LABEL_WIDTH,
+            )}
+          />
+        )
+      })}
+    </>
+  )
+}
+
+/** Mobile placeholder for the variants that collapse to ONE trigger (icon button or "…"). */
+function MobileTriggerSkeleton() {
+  return <Skeleton className={cn(SKELETON_HEIGHT, SKELETON_ICON_WIDTH, SKELETON_RADIUS)} />
+}
+
 export function PageActions({
   variant = 'icon-buttons',
   actions,
   menuActions,
   selector,
   className,
+  loading,
 }: PageActionsProps) {
   if (variant === 'icon-buttons') {
-    return <IconButtonsVariant actions={actions} menuActions={menuActions} selector={selector} className={className} />
+    return <IconButtonsVariant actions={actions} menuActions={menuActions} selector={selector} className={className} loading={loading} />
   }
 
   if (variant === 'menu-primary') {
-    return <MenuPrimaryVariant actions={actions} menuActions={menuActions || []} selector={selector} className={className} />
+    return <MenuPrimaryVariant actions={actions} menuActions={menuActions || []} selector={selector} className={className} loading={loading} />
   }
 
-  return <PrimaryButtonsVariant actions={actions} className={className} />
+  return <PrimaryButtonsVariant actions={actions} className={className} loading={loading} />
 }
 
 function IconButtonsVariant({
@@ -233,11 +312,13 @@ function IconButtonsVariant({
   menuActions,
   selector,
   className,
+  loading,
 }: {
   actions: PageActionButton[]
   menuActions?: ActionsMenuGroup[]
   selector?: React.ReactNode
   className?: string
+  loading?: boolean
 }) {
   const desktopActions = actions.filter(a => !a.showOnlyMobile)
   const hasMenuActions = !!menuActions && menuActions.some(g => g.items.length > 0)
@@ -257,17 +338,25 @@ function IconButtonsVariant({
       {/* Desktop: every action as an icon button + optional overflow menu */}
       <div className={cn('hidden md:flex items-center', ACTIONS_GAP, className)}>
         {selector}
-        {desktopActions.map((action, idx) => (
-          <React.Fragment key={actionKey(action, idx)}>
-            {renderActionButton(action)}
-          </React.Fragment>
-        ))}
-        {hasMenuActions && <ActionsMenuDropdown groups={menuActions} />}
+        {loading ? (
+          <ActionSkeletons actions={desktopActions} />
+        ) : (
+          <>
+            {desktopActions.map((action, idx) => (
+              <React.Fragment key={actionKey(action, idx)}>
+                {renderActionButton(action)}
+              </React.Fragment>
+            ))}
+            {hasMenuActions && <ActionsMenuDropdown groups={menuActions} />}
+          </>
+        )}
       </div>
 
       {/* Mobile: single icon button OR all actions merged into one "..." menu */}
       <div className={cn('flex md:hidden', className)}>
-        {useSingleActionMobile && singleAction ? (
+        {loading ? (
+          <MobileTriggerSkeleton />
+        ) : useSingleActionMobile && singleAction ? (
           renderActionButton(singleAction, { iconOnly: true })
         ) : hasMobileMenuItems ? (
           <ActionsMenuDropdown groups={mobileMenuGroups} />
@@ -284,9 +373,11 @@ function IconButtonsVariant({
 function PrimaryButtonsVariant({
   actions,
   className,
+  loading,
 }: {
   actions: PageActionButton[]
   className?: string
+  loading?: boolean
 }) {
   // Sort: outline first, accent last (rightmost on desktop).
   const sortedActions = [...actions].sort((a, b) => {
@@ -300,14 +391,20 @@ function PrimaryButtonsVariant({
   return (
     <>
       <div className={cn('hidden md:flex items-center', ACTIONS_GAP, className)}>
-        {desktopActions.map((action, idx) => (
-          <React.Fragment key={`desktop-${actionKey(action, idx)}`}>
-            {renderActionButton(action)}
-          </React.Fragment>
-        ))}
+        {loading ? (
+          // No overflow trigger in this variant — an unknown action set settles
+          // into a labelled button, not a square one.
+          <ActionSkeletons actions={desktopActions} emptyFallback="label" />
+        ) : (
+          desktopActions.map((action, idx) => (
+            <React.Fragment key={`desktop-${actionKey(action, idx)}`}>
+              {renderActionButton(action)}
+            </React.Fragment>
+          ))
+        )}
       </div>
 
-      <MobileBottomActions actions={sortedActions} />
+      <MobileBottomActions actions={sortedActions} loading={loading} />
     </>
   )
 }
@@ -321,11 +418,13 @@ function MenuPrimaryVariant({
   menuActions,
   selector,
   className,
+  loading,
 }: {
   actions: PageActionButton[]
   menuActions: ActionsMenuGroup[]
   selector?: React.ReactNode
   className?: string
+  loading?: boolean
 }) {
   const desktopActions = actions.filter(a => !a.showOnlyMobile)
   const hasMenuActions = menuActions.some(g => g.items.length > 0)
@@ -340,34 +439,47 @@ function MenuPrimaryVariant({
     <>
       <div className={cn('hidden md:flex items-center', ACTIONS_GAP, className)}>
         {selector}
-        {hasMenuActions && <ActionsMenuDropdown groups={menuActions} />}
-        {desktopActions.map((action, idx) => (
-          <React.Fragment key={`desktop-${actionKey(action, idx)}`}>
-            {renderActionButton({ ...action, variant: action.variant || 'accent' })}
-          </React.Fragment>
-        ))}
+        {loading ? (
+          <ActionSkeletons actions={desktopActions} />
+        ) : (
+          <>
+            {hasMenuActions && <ActionsMenuDropdown groups={menuActions} />}
+            {desktopActions.map((action, idx) => (
+              <React.Fragment key={`desktop-${actionKey(action, idx)}`}>
+                {renderActionButton({ ...action, variant: action.variant || 'accent' })}
+              </React.Fragment>
+            ))}
+          </>
+        )}
       </div>
 
       <div className={cn('flex md:hidden', className)}>
-        {hasMobileMenuItems ? <ActionsMenuDropdown groups={mobileMenuGroups} /> : null}
+        {loading ? <MobileTriggerSkeleton /> : hasMobileMenuItems ? <ActionsMenuDropdown groups={mobileMenuGroups} /> : null}
       </div>
     </>
   )
 }
 
-function MobileBottomActions({ actions }: { actions: PageActionButton[] }) {
+function MobileBottomActions({ actions, loading }: { actions: PageActionButton[]; loading?: boolean }) {
   return (
     <div className={cn(
       'fixed md:hidden bottom-0 left-0 right-0 z-50',
       'bg-ods-card border-t border-ods-border',
-      'flex items-start pt-6 pb-6 px-6',
+      // `lf` (24px at every breakpoint), NOT `l` — this bar is `md:hidden`, so the
+      // only value it ever uses is the MOBILE one, and `l` is 16px there. The
+      // fixed variant is what keeps the 24px the bar has always had.
+      'flex items-start p-[var(--spacing-system-lf)]',
       ACTIONS_GAP,
     )}>
-      {actions.map((action, idx) => (
-        <React.Fragment key={`mobile-${actionKey(action, idx)}`}>
-          {renderActionButton(action, { fullWidth: !!action.label })}
-        </React.Fragment>
-      ))}
+      {loading ? (
+        <ActionSkeletons actions={actions} fullWidth emptyFallback="label" />
+      ) : (
+        actions.map((action, idx) => (
+          <React.Fragment key={`mobile-${actionKey(action, idx)}`}>
+            {renderActionButton(action, { fullWidth: !!action.label })}
+          </React.Fragment>
+        ))
+      )}
     </div>
   )
 }

package/src/components/ui/radio-group.tsx

@@ -81,6 +81,10 @@ const RadioGroupBlock = React.forwardRef<
       <div className={cn("relative flex w-full flex-col", className)}>
         <RadioGroupPrimitive.Root
           ref={ref}
+          // Same marker every field exposes — it is how a form finds (and
+          // scrolls to) the first control that failed validation. The GROUP is
+          // the field here; the individual options are not separately invalid.
+          data-invalid={error ? true : undefined}
           className={cn(
             "w-full",
             isGrouped
@@ -106,6 +110,10 @@ const RadioGroupBlock = React.forwardRef<
                   "flex w-full items-center gap-3",
                   "transition-colors duration-200",
                   isDisabled ? "cursor-not-allowed" : "cursor-pointer",
+                  // Hover / active move the BACKGROUND only, like Input and
+                  // CheckboxBlock — the border stays put so an unselected row
+                  // never flashes "selected" under the cursor.
+                  !isDisabled && "hover:bg-ods-bg-hover active:bg-ods-bg-active",
                   isGrouped
                     ? cn(
                         "bg-ods-card px-[var(--spacing-system-sf)] py-[var(--spacing-system-xs,8px)]",
@@ -114,12 +122,17 @@ const RadioGroupBlock = React.forwardRef<
                       )
                     : cn(
                         "rounded-[6px] border bg-ods-card p-[var(--spacing-system-sf)]",
-                        !isDisabled && "hover:border-ods-accent/30",
                         !isDisabled &&
                           "has-[[data-state=checked]]:bg-[var(--ods-system-greys-soft-grey)]/30 has-[[data-state=checked]]:border-ods-accent/40",
                         error ? "border-ods-error" : "border-ods-border"
                       ),
-                  isDisabled && "opacity-50",
+                  // Disabled matches a disabled field: flat `ods-bg` fill and
+                  // greyed text, not a fade of the whole row. The greying lives
+                  // on the TEXT COLUMN below, not here: as a descendant rule on
+                  // the row it also repainted whatever `trailing` renders — a
+                  // `Tag`'s label is a span too, and it went invisible against
+                  // its own fill.
+                  isDisabled && "bg-ods-bg",
                   itemClassName
                 )}
               >
@@ -132,7 +145,10 @@ const RadioGroupBlock = React.forwardRef<
                     error ? "border-ods-error" : "border-[var(--color-border-strong)]",
                     "transition-colors duration-150",
                     "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent focus-visible:ring-offset-2 focus-visible:ring-offset-ods-card",
+                    // Disabled: the EMPTY dot dims with the text; a selected one
+                    // keeps its accent so "on but locked" stays readable.
                     "disabled:cursor-not-allowed",
+                    "disabled:data-[state=unchecked]:bg-ods-bg disabled:data-[state=unchecked]:border-ods-border",
                     "data-[state=checked]:border-ods-accent"
                   )}
                 >
@@ -140,7 +156,16 @@ const RadioGroupBlock = React.forwardRef<
                     <span className="block h-1/2 w-1/2 rounded-full bg-ods-accent" />
                   </RadioGroupPrimitive.Indicator>
                 </RadioGroupPrimitive.Item>
-                <div className="flex min-w-0 flex-1 flex-col justify-center">
+                <div
+                  className={cn(
+                    "flex min-w-0 flex-1 flex-col justify-center",
+                    // Direct children only — these are the two component-owned
+                    // wrappers. `option.label` / `option.description` are
+                    // ReactNode, so a descendant rule would repaint content the
+                    // caller styled itself.
+                    isDisabled && "[&>span]:text-ods-text-disabled",
+                  )}
+                >
                   <span
                     className={cn(
                       "font-[family-name:var(--font-h4-family)] font-[number:var(--font-h4-weight)] text-[length:var(--font-size-h4-body)] leading-[24px]",

package/src/components/ui/search-input.tsx

@@ -106,7 +106,8 @@ const innerInputStyles = cn(
   "flex-1 min-w-[60px] bg-transparent border-none outline-none",
   "text-h4",
   "text-ods-text-primary placeholder:text-ods-text-secondary",
-  "disabled:cursor-not-allowed",
+  // Disabled - match Input exactly (value greys out, placeholder dims further)
+  "disabled:cursor-not-allowed disabled:text-ods-text-disabled disabled:placeholder:text-ods-border",
   "touch-manipulation"
 )
 

package/src/components/ui/select.tsx

@@ -42,7 +42,14 @@ const SelectTrigger = React.forwardRef<
         "enabled:hover:bg-ods-bg-hover enabled:hover:border-ods-border-hover enabled:active:bg-ods-bg-active enabled:active:border-ods-border-active",
         !isInvalid && "data-[state=open]:border-ods-accent data-[state=open]:hover:border-ods-accent",
         "group",
+        // Disabled - match Input exactly: value greys out, placeholder dims
+        // further. The `data-[placeholder]` rule above is a class+attribute
+        // selector, so the disabled placeholder rule stacks `:disabled` on top
+        // of it to win on specificity rather than on source order.
         "disabled:!cursor-not-allowed disabled:bg-ods-bg",
+        "disabled:text-ods-text-disabled disabled:data-[placeholder]:text-ods-border",
+        // The chevron sets its own colour — grey it with the value.
+        "disabled:[&_svg]:text-ods-text-disabled",
         "transition-colors duration-200 cursor-pointer",
         "[&>span]:line-clamp-1",
         isInvalid && "border-ods-error enabled:hover:border-ods-error enabled:active:border-ods-error data-[state=open]:border-ods-error",

package/src/components/ui/tab-navigation.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import React, { useState, useEffect, useMemo, useRef, useCallback } from 'react'
+import React, { useState, useEffect, useDeferredValue, useMemo, useRef, useCallback } from 'react'
 import { useSearchParams, useRouter, usePathname } from '../../embed-shims/next-navigation'
 import { cn } from '../../utils/cn'
 
@@ -38,8 +38,14 @@ interface TabNavigationProps {
   urlSync?: boolean | TabNavigationUrlSyncOptions
   defaultTab?: string  // Fallback when no valid tab in URL or initial value
 
-  // Render prop to provide active tab to children
-  children?: (activeTab: string) => React.ReactNode
+  /**
+   * Render prop for the tab BODY. Receives the tab to render and, additively,
+   * a `isStale` flag — true while the bar has already moved to a newly clicked
+   * tab but the body is still showing the PREVIOUS one (see `deferredActiveTab`
+   * below). Use it to dim the body or show a pending hint; without it a slow
+   * tab looks like a tab that simply did nothing.
+   */
+  children?: (activeTab: string, state: { isStale: boolean }) => React.ReactNode
 }
 
 export function TabNavigation({
@@ -119,6 +125,22 @@ export function TabNavigation({
     }
   }
 
+  // The tab BAR follows the click immediately; the tab BODY is deferred, which
+  // makes React treat swapping it as a transition. That is the whole fix for the
+  // flash: a tab whose data is not in the client cache yet SUSPENDS the moment it
+  // mounts, and outside a transition React has to show that Suspense fallback —
+  // so the skeleton appears for a frame before the real content lands. Inside a
+  // transition React keeps the previous tab on screen and swaps only once the new
+  // one is ready. Deferring the body rather than the whole state keeps the
+  // underline responsive, so the click still feels instant.
+  //
+  // The cost of that trade is that a SLOW tab leaves the previous tab's content
+  // under the new tab's underline with nothing saying so — worse than a skeleton,
+  // because stale data reads as fresh data. `isStale` is handed to the render prop
+  // so the body can mark itself while it waits.
+  const deferredActiveTab = useDeferredValue(activeTab)
+  const isStale = activeTab !== deferredActiveTab
+
   const scrollRef = useRef<HTMLDivElement>(null)
   const activeTabRef = useRef<HTMLButtonElement>(null)
   const isFirstActiveScrollRef = useRef(true)
@@ -291,7 +313,7 @@ export function TabNavigation({
       </div>
 
       {/* Render children with active tab if provided */}
-      {children && children(activeTab)}
+      {children && children(deferredActiveTab, { isStale })}
     </>
   )
 }

package/src/components/ui/tag-search-input.tsx

@@ -140,7 +140,13 @@ export function TagSearchInput<T = string>({
           "has-[:focus]:border-ods-accent",
           !disabled && "hover:bg-ods-bg-hover hover:border-ods-border-hover",
           disabled && "bg-ods-bg",
-          disabled && "cursor-not-allowed opacity-50",
+          disabled && "cursor-not-allowed",
+          // Match Input: grey the text and the icons, don't fade the whole
+          // control (a blanket opacity also washes out the border). Icons only —
+          // this container has no adornment spans of its own, so a `[&_span]`
+          // rule would ONLY have reached the selected `Tag` chips, whose label is
+          // a span, and greyed them into their own fill in the light theme.
+          "has-[:disabled]:[&_svg]:text-ods-text-disabled",
           className,
         )}
         onClick={() => {
@@ -199,7 +205,8 @@ export function TagSearchInput<T = string>({
               "flex-1 min-w-[60px] bg-transparent border-none outline-none",
               "text-h4",
               "text-ods-text-primary placeholder:text-ods-text-secondary",
-              "disabled:cursor-not-allowed",
+              // Disabled - match Input exactly (value greys out, placeholder dims further)
+              "disabled:cursor-not-allowed disabled:text-ods-text-disabled disabled:placeholder:text-ods-border",
             )}
           />
         </div>

package/src/components/ui/textarea.tsx

@@ -119,6 +119,12 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
           !hideBorder && cn("rounded-[6px] border bg-ods-card border-ods-border", accentBorder),
           !hideBorder && !props.disabled && "hover:bg-ods-bg-hover hover:border-ods-border-hover active:bg-ods-bg-active active:border-ods-border-active",
           !hideBorder && props.disabled && "!cursor-not-allowed bg-ods-bg",
+          // Start / end icons carry their own colour — grey them with the value
+          // so a disabled field reads as one flat colour. Scoped to the DIRECT
+          // span children (the two icon wrappers): the nodes inside them are
+          // rendered verbatim so callers can pass an interactive trigger and own
+          // its styling, and a descendant rule would overwrite exactly that.
+          "has-[:disabled]:[&>span]:text-ods-text-disabled has-[:disabled]:[&_svg]:text-ods-text-disabled",
           !hideBorder && isInvalid && cn("border-ods-error hover:border-ods-error", accentBorderError),
           hideBorder && "bg-transparent",
         )}
@@ -150,7 +156,8 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
             // internally instead of pushing the icon out of frame.
             "max-h-[160px] overflow-y-auto",
             "scrollbar-thin scrollbar-track-transparent scrollbar-thumb-ods-border/30 hover:scrollbar-thumb-ods-text-secondary/30",
-            "disabled:cursor-not-allowed disabled:placeholder:text-ods-border",
+            // Disabled - match Input exactly (value greys out, placeholder dims further)
+            "disabled:cursor-not-allowed disabled:text-ods-text-disabled disabled:placeholder:text-ods-border",
             className,
           )}
           {...props}

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 }
+}