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

package/src/components/layout/title-block.tsx

@@ -40,6 +40,14 @@
  * byte-identical. Do NOT change defaults or touch anything else here.
  *
  * SANCTIONED EXCEPTION (2026-07, explicit human sign-off): the OPTIONAL
+ * `subtitleRow` prop. Defaults to `'when-set'` — the subtitle row keeps
+ * rendering only when `subtitle` is truthy, so every existing caller is
+ * byte-identical. The other two values decide how a page trades a header that
+ * never moves against a header that never shows an empty line; see the prop's
+ * own doc for which to pick. Additive + default-preserving; do NOT change the
+ * default.
+ *
+ * SANCTIONED EXCEPTION (2026-07, explicit human sign-off): the OPTIONAL
  * `titleWrap` prop. Defaults to `false` — the frozen single-line `truncate`
  * baseline is unchanged for every existing caller. Content DETAIL pages (whose
  * h1 is CMS data of arbitrary length — releases, legal docs, FAQ docs, dev
@@ -58,12 +66,27 @@
  * so its natural width drives the wrap while `truncate` still clamps a title
  * that alone exceeds the container. The mobile (base) layout is untouched.
  * This is the new frozen baseline; do NOT re-introduce breakpoint stacking.
+ *
+ * SANCTIONED EXCEPTION (2026-07, explicit human sign-off): overflow tooltips on
+ * the title and subtitle. This one CHANGES the baseline for every caller: the
+ * native `title=""` attribute on both is replaced by the ODS `FloatingTooltip`,
+ * armed only when the text is genuinely clipped (`useIsTruncated`). Both stay
+ * single-line — that is the design, and the tooltip is what makes a clipped
+ * title readable instead of merely pretty. Nothing is lost for assistive tech:
+ * `text-overflow: ellipsis` never hid the text from the accessibility tree, so
+ * the full string was always exposed; the attribute only ever served a mouse.
+ * The wrapper `div` the tooltip needs goes OUTSIDE the `h1`/`p` — never inside:
+ * a `div` inside a `p` is auto-closed by the HTML parser, which would split the
+ * subtitle paragraph and desync hydration. The `titleWrap` branch is untouched
+ * (wrapped text never clips, so it never needs a tooltip).
  * ========================================================================== */
 
 import React from 'react'
+import { useIsTruncated } from '../../hooks/ui/use-is-truncated'
 import { cn } from '../../utils/cn'
 import type { ActionsMenuGroup } from '../ui/actions-menu'
 import { EntityImage } from '../ui/entity-image'
+import { FloatingTooltip } from '../ui/floating-tooltip'
 import { PageActions, type PageActionButton } from '../ui/page-actions'
 import { BackButton } from './back-button'
 
@@ -106,6 +129,28 @@ export interface TitleBlockProps {
    *  (typography + surrounding markup unchanged, so header height is identical to loaded).
    *  Additive + default-preserving: omit it and every existing caller is byte-identical. */
   loading?: boolean
+  /**
+   * Render the ACTIONS as placeholders too. Separate from `loading` on purpose:
+   * a page whose action set is already final (it depends on the route, not on
+   * the record) keeps showing its real buttons while the title loads.
+   */
+  loadingActions?: boolean
+  /**
+   * When the subtitle row occupies the layout. The subtitle is often optional
+   * RECORD data — unknown while loading, sometimes absent afterwards — and there
+   * is no setting that both fills the loading header and never leaves a blank
+   * line, so the caller picks which one matters.
+   *
+   * - `'when-set'` (default) — only when `subtitle` has text.
+   * - `'while-loading'` — also during `loading`, as a skeleton bar. The header
+   *   looks complete while it loads, and the row collapses if the record turns
+   *   out to have no subtitle (so that case settles one line shorter).
+   * - `'always'` — the row never collapses; an empty subtitle holds its line
+   *   with an invisible spacer. The header cannot change height. Use it when the
+   *   loaded page ALWAYS has a subtitle — typically a standalone skeleton
+   *   component matching a page whose subtitle is guaranteed.
+   */
+  subtitleRow?: 'when-set' | 'while-loading' | 'always'
   /** When true, a long title WRAPS onto multiple lines instead of the frozen single-line
    *  ellipsis clamp. For content detail pages whose h1 is CMS data of arbitrary length.
    *  Additive + default-preserving: omit it and every existing caller is byte-identical. */
@@ -129,6 +174,22 @@ function TitleTextSkeleton({ widthClass, heightClass }: { widthClass: string; he
   )
 }
 
+/**
+ * Bar geometry per title size, following the ODS type scale across breakpoints
+ * (`md` = 800px, `lg` = 1280px here — the SAME widths the typography tokens
+ * switch at, so bar and text step together).
+ *
+ * `h2` needs no `lg` step because `text-h2` has none: it is 24/32 on mobile and
+ * 32/40 from tablet up. `text-h1` scales at both breakpoints (40 → 48 → 56), so
+ * its bar does too — reusing the h2 bar there would leave a stamp-sized smudge
+ * inside a 64px line. Heights stay well under the line box's ascent on purpose;
+ * see `TitleTextSkeleton` for why that is what keeps the header height honest.
+ */
+const TITLE_SKELETON_SIZE = {
+  h1: { width: 'w-56 md:w-80 lg:w-96', height: 'h-7 md:h-8 lg:h-9' },
+  h2: { width: 'w-48 md:w-72', height: 'h-4 md:h-6' },
+} as const
+
 export function TitleBlock({
   title,
   subtitle,
@@ -143,14 +204,28 @@ export function TitleBlock({
   titleSize = 'h2',
   titleAdornment,
   loading,
+  loadingActions,
+  subtitleRow = 'when-set',
   titleWrap = false,
 }: TitleBlockProps) {
+  const hasSubtitleRow =
+    !!subtitle || subtitleRow === 'always' || (subtitleRow === 'while-loading' && !!loading)
   const hasActions = actions && actions.length > 0
   const hasMenuActions = !!menuActions && menuActions.some(g => g.items.length > 0)
   const titleClass = titleSize === 'h1' ? 'text-h1' : 'text-h2'
   // Frozen baseline is the single-line `truncate`; `titleWrap` swaps it for
   // multi-line wrapping (break-words guards pathological unbroken tokens).
   const titleOverflowClass = titleWrap ? 'break-words' : 'truncate'
+  const skeletonSize = TITLE_SKELETON_SIZE[titleSize]
+
+  // Exactly one title element renders per pass, so one ref covers every branch.
+  // The tooltip arms itself only on real clipping — repeating a fully visible
+  // title back to the user is noise, and `titleWrap`/loading never clip at all.
+  const { ref: titleRef, isTruncated: titleTruncated } = useIsTruncated<HTMLHeadingElement>(loading ? null : title)
+  const { ref: subtitleRef, isTruncated: subtitleTruncated } = useIsTruncated<HTMLParagraphElement>(
+    loading ? null : subtitle,
+  )
+  const titleNode = loading ? <TitleTextSkeleton widthClass={skeletonSize.width} heightClass={skeletonSize.height} /> : title
 
   return (
     <div
@@ -183,7 +258,7 @@ export function TitleBlock({
             className="hidden md:inline-flex"
           />
         )}
-        {(image || subtitle || loading) ? (
+        {(image || hasSubtitleRow || loading) ? (
           <div className="flex items-center gap-[var(--spacing-system-m)] min-w-0 w-full">
             {image && (
               <EntityImage
@@ -196,15 +271,32 @@ export function TitleBlock({
               {(loading || title) && (
                 titleAdornment ? (
                   <div className="flex items-center gap-[var(--spacing-system-m)] min-w-0 w-full">
-                    <h1 className={cn(titleClass, 'text-ods-text-primary min-w-0', titleOverflowClass)} title={title}>{loading ? <TitleTextSkeleton widthClass="w-48 md:w-72" heightClass="h-4 md:h-6" /> : title}</h1>
+                    {/* `min-w-0` moves onto the tooltip's wrapper: the wrapper is
+                        now the flex item, and without it the row refuses to
+                        shrink and pushes the adornment out. */}
+                    <FloatingTooltip content={title} side="bottom" disabled={!titleTruncated} triggerClassName="min-w-0">
+                      <h1 ref={titleRef} className={cn(titleClass, 'text-ods-text-primary min-w-0', titleOverflowClass)}>{titleNode}</h1>
+                    </FloatingTooltip>
                     <span className="shrink-0">{titleAdornment}</span>
                   </div>
                 ) : (
-                  <h1 className={cn(titleClass, 'text-ods-text-primary', titleOverflowClass)} title={title}>{loading ? <TitleTextSkeleton widthClass="w-48 md:w-72" heightClass="h-4 md:h-6" /> : title}</h1>
+                  <FloatingTooltip content={title} side="bottom" disabled={!titleTruncated}>
+                    <h1 ref={titleRef} className={cn(titleClass, 'text-ods-text-primary', titleOverflowClass)}>{titleNode}</h1>
+                  </FloatingTooltip>
                 )
               )}
-              {subtitle && (
-                <p className="text-h6 text-ods-text-secondary truncate" title={subtitle}>{loading ? <TitleTextSkeleton widthClass="w-28 md:w-36" heightClass="h-2.5 md:h-3" /> : subtitle}</p>
+              {hasSubtitleRow && (
+                /* The NBSP is a pure spacer, reached only in `'always'` mode: an
+                   empty `p` collapses to zero height (its only content would be
+                   collapsible whitespace), which is exactly the shift that mode
+                   exists to prevent. Hidden from AT — it carries no meaning. */
+                <FloatingTooltip content={subtitle} side="bottom" disabled={!subtitleTruncated}>
+                  <p
+                    ref={subtitleRef}
+                    className="text-h6 text-ods-text-secondary truncate"
+                    aria-hidden={!loading && !subtitle ? true : undefined}
+                  >{loading ? <TitleTextSkeleton widthClass="w-28 md:w-36" heightClass="h-2.5 md:h-3" /> : (subtitle || '\u00A0')}</p>
+                </FloatingTooltip>
               )}
             </div>
           </div>
@@ -212,7 +304,9 @@ export function TitleBlock({
           title && (
             titleAdornment ? (
               <div className="flex items-center gap-[var(--spacing-system-m)] min-w-0 w-full">
-                <h1 className={cn(titleClass, 'text-ods-text-primary min-w-0', titleOverflowClass)} title={title}>{title}</h1>
+                <FloatingTooltip content={title} side="bottom" disabled={!titleTruncated} triggerClassName="min-w-0">
+                  <h1 ref={titleRef} className={cn(titleClass, 'text-ods-text-primary min-w-0', titleOverflowClass)}>{title}</h1>
+                </FloatingTooltip>
                 <span className="shrink-0">{titleAdornment}</span>
               </div>
             ) : (
@@ -226,13 +320,18 @@ export function TitleBlock({
         )}
       </div>
 
-      {(hasActions || hasMenuActions || selector) && (
+      {/* `loadingActions` opens this gate on its own: the case the flag exists for
+          is a page that does not YET know its action set, which is exactly the
+          page that passes `actions={[]}` — gating on `hasActions` alone would
+          render nothing and then pop the real buttons in. */}
+      {(hasActions || hasMenuActions || selector || loadingActions) && (
         <div className="flex gap-2 items-center shrink-0">
           <PageActions
             variant={actionsVariant}
             actions={actions ?? []}
             menuActions={menuActions}
             selector={selector}
+            loading={loadingActions}
           />
         </div>
       )}

package/src/components/navigation/navigation-sidebar-item.tsx

@@ -1,6 +1,7 @@
 "use client"
 
-import { cloneElement, type ReactElement } from 'react'
+import { cloneElement, memo, type ReactElement, type ReactNode } from 'react'
+import Link from '../../embed-shims/next-link'
 import { NavigationSidebarItem } from '../../types/navigation'
 import { cn } from '../../utils'
 
@@ -11,46 +12,72 @@ interface IconProps {
 
 export interface NavigationSidebarItemButtonProps {
   item: NavigationSidebarItem
+  /** "You are on this page" — pathname-derived, and the only thing that carries `aria-current`. */
+  isActive: boolean
+  /**
+   * "You clicked this one and it has not arrived yet" — deliberately a separate,
+   * weaker state. Never promoted to active: the accent belongs to the page you
+   * are actually on.
+   */
+  isPending: boolean
   showLabel: boolean
   disabled: boolean
   onClick: (item: NavigationSidebarItem, event?: React.MouseEvent) => void
 }
 
-export function NavigationSidebarItemButton({
+/**
+ * One sidebar entry.
+ *
+ * Rendered as a real anchor whenever it has a `path` — which is what buys the
+ * two things a `<button>` + `router.push` cannot: Next prefetches links that
+ * are in the viewport (so the section is usually already loaded by the time it
+ * is clicked, instead of every first visit paying a cold segment fetch), and
+ * the browser's own affordances work — middle-click, ⌘/Ctrl-click, "open in new
+ * tab", copy link, and a status-bar URL on hover.
+ *
+ * Falls back to a `<button>` for entries that only carry an `onClick` (no
+ * destination to link to) and for the disabled state, which an anchor cannot
+ * express.
+ */
+export const NavigationSidebarItemButton = memo(function NavigationSidebarItemButton({
   item,
+  isActive,
+  isPending,
   showLabel,
   disabled,
   onClick,
 }: NavigationSidebarItemButtonProps) {
-  const isActive = item.isActive ?? false
   const unreadCount = item.unreadCount ?? 0
   const hasUnread = unreadCount > 0
 
-  return (
-    <button
-      onClick={(event) => onClick(item, event)}
-      disabled={disabled}
-      className={cn(
-        "w-full flex items-center justify-start relative",
-        "h-14 p-[var(--spacing-system-m)]",
-        "transition-colors duration-300",
-        "[&_svg]:transition-colors [&_svg]:duration-300",
-        "before:content-[''] before:absolute before:left-0 before:top-0 before:bottom-0 before:w-1",
-        "before:transition-colors before:duration-300",
-        !isActive && !disabled && "hover:bg-ods-bg-hover text-ods-text-primary [&_svg]:fill-ods-text-secondary",
-        !isActive && disabled && "text-ods-text-secondary [&_svg]:fill-ods-text-secondary",
-        isActive && !disabled && [
-          "bg-[var(--ods-open-yellow-light)] text-ods-accent",
-          "[&_svg]:fill-ods-accent",
-          "before:bg-ods-accent",
-        ],
-        isActive && disabled && "text-ods-text-secondary [&_svg]:fill-ods-text-secondary",
-        disabled && "cursor-not-allowed opacity-50",
-      )}
-      title={!showLabel ? item.label : undefined}
-      aria-label={item.label}
-      aria-current={isActive ? 'page' : undefined}
-    >
+  const className = cn(
+    "w-full flex items-center justify-start relative",
+    "h-14 p-[var(--spacing-system-m)]",
+    // 150ms, not 300: the outgoing and incoming entries cross-fade, so for the
+    // whole duration TWO rows read as half-active. At 300ms that window is long
+    // enough to look like a flicker rather than a transition.
+    "transition-colors duration-150",
+    "[&_svg]:transition-colors [&_svg]:duration-150",
+    "before:content-[''] before:absolute before:left-0 before:top-0 before:bottom-0 before:w-1",
+    "before:transition-colors before:duration-150",
+    // Pending borrows the HOVER weight and nothing else — no accent bar, no
+    // accent text, no `aria-current`. It says "this row is working", not "this
+    // is where you are", and it reads as the row staying pressed under the
+    // cursor, which is exactly what happened.
+    !isActive && !disabled && "hover:bg-ods-bg-hover text-ods-text-primary [&_svg]:fill-ods-text-secondary",
+    !isActive && !disabled && isPending && "bg-ods-bg-hover",
+    !isActive && disabled && "text-ods-text-secondary [&_svg]:fill-ods-text-secondary",
+    isActive && !disabled && [
+      "bg-[var(--ods-open-yellow-light)] text-ods-accent",
+      "[&_svg]:fill-ods-accent",
+      "before:bg-ods-accent",
+    ],
+    isActive && disabled && "text-ods-text-secondary [&_svg]:fill-ods-text-secondary",
+    disabled && "cursor-not-allowed opacity-50",
+  )
+
+  const content: ReactNode = (
+    <>
       <div className="relative flex items-center justify-center flex-shrink-0">
         {cloneElement(item.icon as ReactElement<IconProps>, {
           color: isActive && !disabled ? "text-ods-accent" : "text-ods-text-secondary",
@@ -77,6 +104,29 @@ export function NavigationSidebarItemButton({
           </span>
         </span>
       )}
-    </button>
+    </>
   )
-}
+
+  const shared = {
+    className,
+    title: !showLabel ? item.label : undefined,
+    'aria-label': item.label,
+    'aria-current': isActive ? ('page' as const) : undefined,
+  }
+
+  // An entry with a custom onClick has no destination of its own, and a
+  // disabled one must not be followable — both stay buttons.
+  if (disabled || !item.path || item.onClick) {
+    return (
+      <button type="button" onClick={(event) => onClick(item, event)} disabled={disabled} {...shared}>
+        {content}
+      </button>
+    )
+  }
+
+  return (
+    <Link href={item.path} onClick={(event) => onClick(item, event)} {...shared}>
+      {content}
+    </Link>
+  )
+})

package/src/components/navigation/navigation-sidebar.tsx

@@ -13,6 +13,10 @@ const MINIMIZED_WIDTH = 56 // 3.5rem = 56px
 const EXPANDED_WIDTH = 224 // 14rem = 224px
 const STORAGE_KEY = 'of.navigationSidebar.minimized'
 
+/** A click the browser will resolve itself — new tab, new window, middle button. */
+const isModifiedClick = (event?: React.MouseEvent): boolean =>
+  !!event && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0)
+
 export interface NavigationSidebarProps {
   config: NavigationSidebarConfig
   /**
@@ -75,17 +79,68 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
     return () => document.removeEventListener('keydown', handleKeyDown)
   }, [isOverlayOpen, closeOverlay])
 
+  // The entry the user just clicked, held until the route commits.
+  //
+  // PENDING IS NOT ACTIVE, and keeping the two apart is the whole point. Active
+  // means "this is the page you are on" — it carries the accent bar and
+  // `aria-current="page"`, and it stays derived from the pathname, so it is
+  // never asserted before it is true. Pending only means "this is the one you
+  // clicked": a click deserves an answer, but the answer must not be a claim
+  // about where you are. Folding pending into active would light the accent on
+  // a section still loading and announce it as the current page to a screen
+  // reader — a statement that is simply false until the router says otherwise.
+  const [pendingItemId, setPendingItemId] = useState<string | null>(null)
+  const committedActiveId = useMemo(
+    () => config.items.find(item => item.isActive)?.id ?? null,
+    [config.items],
+  )
+
+  // Any committed change clears it — including one that landed somewhere else
+  // entirely (a redirect, a link elsewhere on the page). A navigation that never
+  // commits leaves a faint hold on the row it started from; because pending is
+  // only ever a soft hint, that costs nothing but a stale hover-weight tint,
+  // where a stale ACTIVE state would have been a lie about the current page.
+  useEffect(() => {
+    setPendingItemId(null)
+  }, [committedActiveId])
+
   const handleItemClick = useCallback((item: NavigationSidebarItem, event?: React.MouseEvent) => {
     event?.stopPropagation()
 
     if (item.onClick) {
       item.onClick()
-    } else if (item.path) {
-      config.onNavigate?.(item.path)
+      if (isTablet) setTabletMinimized(true)
+      return
+    }
+
+    if (!item.path) return
+
+    // ⌘/Ctrl/Shift-click and middle-click open the link somewhere else. THIS
+    // window is not going anywhere, so the browser is left to it: no
+    // preventDefault, no optimistic highlight, no closing the tablet overlay.
+    // Entries render as real anchors precisely so those gestures work at all.
+    if (isModifiedClick(event)) return
+
+    // A plain click stays the host's to perform, through `onNavigate` exactly
+    // as before — the anchor is here for the href (Next prefetches links in the
+    // viewport) and for the browser affordances, not to take over routing.
+    //
+    // `onNavigate` is optional, though, and with no host router there is nothing
+    // to hand the click to: swallowing it would leave a real anchor, with a real
+    // href, that does nothing at all. So the guard is on having somewhere to
+    // send it — otherwise the anchor navigates on its own and we only close the
+    // overlay behind it.
+    if (config.onNavigate) {
+      event?.preventDefault()
+      // Re-clicking the page you are already on starts no navigation, so there
+      // is nothing to mark — and nothing would ever clear it, since the
+      // committed active id is not about to change.
+      if (item.id !== committedActiveId) setPendingItemId(item.id)
+      config.onNavigate(item.path)
     }
 
     if (isTablet) setTabletMinimized(true)
-  }, [config, isTablet])
+  }, [config, isTablet, committedActiveId])
 
   const { primaryItems, secondaryItems } = useMemo(() => ({
     primaryItems: config.items.filter(item => item.section !== 'secondary'),
@@ -97,16 +152,21 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
     [minimized],
   )
 
-  const isHydrated = isMdUp !== undefined && isLgUp !== undefined
-
+  // There used to be an `isHydrated` gate here — `isMdUp !== undefined && ...`
+  // — meant to hold the sidebar's contents back until the media queries
+  // resolved. It could never be false: the `?? false` above had already
+  // swallowed the `undefined` it tested for. Removed rather than repaired,
+  // because repairing it would be the regression: the contents are server-
+  // rendered today, and gating them behind a client-only media query would
+  // trade a first paint of the real navigation for an empty rail.
   useLayoutEffect(() => {
-    if (isHydrated && !transitionsEnabled) {
+    if (!transitionsEnabled) {
       const id = requestAnimationFrame(() => {
         setTransitionsEnabled(true)
       })
       return () => cancelAnimationFrame(id)
     }
-  }, [isHydrated, transitionsEnabled])
+  }, [transitionsEnabled])
 
   return (
     <>
@@ -148,45 +208,45 @@ export function NavigationSidebar({ config, disabled = false }: NavigationSideba
         style={{ width: sidebarWidth }}
         aria-label="Main navigation sidebar"
       >
-        {isHydrated && (
-          <>
-            <NavigationSidebarHeader minimized={minimized} />
-
-            <div className="flex-1 flex flex-col justify-between py-4 overflow-y-auto">
-              <nav className="flex flex-col" aria-label="Primary navigation">
-                {primaryItems.map(item => (
-                  <NavigationSidebarItemButton
-                    key={item.id}
-                    item={item}
-                    showLabel={showLabel}
-                    disabled={disabled}
-                    onClick={handleItemClick}
-                  />
-                ))}
-              </nav>
-
-              {secondaryItems.length > 0 && (
-                <nav className="flex flex-col" aria-label="Secondary navigation">
-                  {secondaryItems.map(item => (
-                    <NavigationSidebarItemButton
-                      key={item.id}
-                      item={item}
-                      showLabel={showLabel}
-                      disabled={disabled}
-                      onClick={handleItemClick}
-                    />
-                  ))}
-                </nav>
-              )}
-            </div>
-
-            <NavigationSidebarToggle
-              minimized={minimized}
-              showLabel={showLabel}
-              onToggle={handleToggle}
-            />
-          </>
-        )}
+        <NavigationSidebarHeader minimized={minimized} />
+
+        <div className="flex-1 flex flex-col justify-between py-4 overflow-y-auto">
+          <nav className="flex flex-col" aria-label="Primary navigation">
+            {primaryItems.map(item => (
+              <NavigationSidebarItemButton
+                key={item.id}
+                item={item}
+                isActive={item.id === committedActiveId}
+                isPending={item.id === pendingItemId}
+                showLabel={showLabel}
+                disabled={disabled}
+                onClick={handleItemClick}
+              />
+            ))}
+          </nav>
+
+          {secondaryItems.length > 0 && (
+            <nav className="flex flex-col" aria-label="Secondary navigation">
+              {secondaryItems.map(item => (
+                <NavigationSidebarItemButton
+                  key={item.id}
+                  item={item}
+                  isActive={item.id === committedActiveId}
+                isPending={item.id === pendingItemId}
+                  showLabel={showLabel}
+                  disabled={disabled}
+                  onClick={handleItemClick}
+                />
+              ))}
+            </nav>
+          )}
+        </div>
+
+        <NavigationSidebarToggle
+          minimized={minimized}
+          showLabel={showLabel}
+          onToggle={handleToggle}
+        />
       </aside>
     </>
   )

package/src/components/ui/.field-wrapper.md

@@ -1,4 +1,4 @@
-<!-- source-hash: bd15d4489bb0eca1b2faabacba129705 -->
+<!-- source-hash: 674794aef9f624e4f74a99dae56b9617 -->
 A layout wrapper component that adds an optional label above and a status message below any form field, handling the visual chrome (label + feedback text) while letting the field itself remain unstyled.
 
 ## Key Components
@@ -11,15 +11,16 @@ A `forwardRef` component that wraps form fields with consistent label and feedba
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `label` | `string` | — | Label text rendered above the field |
-| `error` | `string` | — | Status/feedback message rendered below the field |
+| `error` | `string` | — | Status/feedback message rendered below the field (out of flow) |
 | `errorVariant` | `"error" \| "warning" \| "success" \| "muted"` | `"error"` | Color variant for the feedback message |
 | `className` | `string` | — | Additional class applied to the outer wrapper |
 | `children` | `React.ReactNode` | — | The field element(s) to wrap |
 
 **Behavior:**
 - When neither `label` nor `error` is present, the wrapper renders as `contents` (no layout box introduced).
-- When either exists, it renders as a full-width flex column.
-- The feedback message clamps to 2 lines with ellipsis; the full text is accessible via the native `title` tooltip.
+- When either exists, it renders as a full-width **relative** flex column.
+- The feedback message is a single line, ellipsized on overflow; the full text is accessible via the native `title` tooltip.
+- The message is positioned **absolutely** (`bottom-0` + `translate-y-full`), so showing or hiding it never changes the field's height — no layout shift on validation. The trade-off: it hangs BELOW the wrapper box and overlaps whatever follows, so a form stacking fields must leave at least ~20px of vertical gap (e.g. `gap-[var(--spacing-system-lf)]`) for it to land in clear space. `CheckboxBlock` uses the same treatment.
 
 **Color Variants:**
 

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

@@ -1,4 +1,4 @@
-<!-- source-hash: 4f81360202d7fa9875b28cdae48c29a5 -->
+<!-- source-hash: ef59a6aa7c2983608cd2d9c678c34323 -->
 Accessible, scrollable tab navigation bar component with optional URL synchronization, overflow scroll shadows, and support for both controlled and URL-driven active tab state.
 
 ## Key Components
@@ -46,6 +46,19 @@ Configuration object for URL synchronization:
   {(activeTab) => <ContentPanel tab={activeTab} />}
 </TabNavigation>
 
+// Render prop with the pending flag. The tab BODY is deferred
+// (`useDeferredValue`), so the underline moves instantly while the body keeps
+// showing the previous tab until the new one is ready — no Suspense-fallback
+// flash. `isStale` is true during that window; mark the body so stale data
+// doesn't read as fresh data.
+<TabNavigation tabs={tabs} urlSync>
+  {(activeTab, { isStale }) => (
+    <div className={cn(isStale && 'opacity-60 transition-opacity')}>
+      <ContentPanel tab={activeTab} />
+    </div>
+  )}
+</TabNavigation>
+
 // Stretched tabs with forced gradients
 <TabNavigation
   tabs={tabs}