@flamingo-stack/openframe-frontend-core 0.0.490 → 0.0.492-1506.3956.1

package/src/components/features/select-button.tsx

@@ -36,9 +36,12 @@ export const SelectButton = React.forwardRef<HTMLButtonElement, SelectButtonProp
           "font-body text-left w-full",
           "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ods-focus",
           "disabled:pointer-events-none disabled:opacity-50",
+          // Hover / active move the BACKGROUND only, like Input — the accent
+          // border is reserved for the selected state, so an unselected button
+          // no longer flashes "selected" under the cursor.
           selected
             ? "bg-ods-open-yellow-light border-ods-accent hover:bg-ods-open-yellow-light-hover active:bg-ods-open-yellow-light-action"
-            : "bg-ods-card border-ods-border hover:bg-ods-bg-hover hover:border-ods-accent active:bg-ods-bg-active active:border-ods-accent",
+            : "bg-ods-card border-ods-border hover:bg-ods-bg-hover active:bg-ods-bg-active",
           className,
         )}
       >

package/src/components/layout/page-layout.tsx

@@ -36,6 +36,12 @@
  * `titleWrap` prop, forwarded to `TitleBlock`. Defaults to `false` (frozen
  * single-line truncate). Content detail pages with CMS titles pass it to let
  * long titles wrap instead of ellipsis-clip. Additive + default-preserving.
+ *
+ * SANCTIONED EXCEPTION (2026-07, explicit human sign-off): the OPTIONAL
+ * `subtitleRow` prop, forwarded to `TitleBlock`. Defaults to `'when-set'` (the
+ * subtitle row renders only when there is text for it). Pages whose subtitle is
+ * optional record data use it to choose how the row behaves while loading.
+ * Additive + default-preserving.
  * ========================================================================== */
 
 import React from 'react'
@@ -68,6 +74,12 @@ export interface PageLayoutProps {
   /** When true, the title/subtitle render as line-box-accurate skeleton bars (forwarded to
    *  `TitleBlock`). Header height stays identical to the loaded state — for page skeletons. */
   loading?: boolean
+  /** Render the header ACTIONS as placeholders (their set depends on data still loading). */
+  loadingActions?: boolean
+  /** When the subtitle row occupies the layout (forwarded to `TitleBlock`):
+   *  `'when-set'` (default), `'while-loading'` (skeleton bar while loading, collapses
+   *  if the record has no subtitle), or `'always'` (never collapses). */
+  subtitleRow?: 'when-set' | 'while-loading' | 'always'
   /** When true, a long title wraps onto multiple lines instead of the frozen single-line
    *  ellipsis clamp (forwarded to `TitleBlock`). For content detail pages whose h1 is CMS
    *  data of arbitrary length. Additive + default-preserving. */
@@ -96,6 +108,8 @@ export function PageLayout({
   titleSize,
   titleAdornment,
   loading,
+  loadingActions,
+  subtitleRow,
   titleWrap,
 }: PageLayoutProps) {
   const hasActions = actions && actions.length > 0
@@ -118,6 +132,8 @@ export function PageLayout({
           titleSize={titleSize}
           titleAdornment={titleAdornment}
           loading={loading}
+          loadingActions={loadingActions}
+          subtitleRow={subtitleRow}
           titleWrap={titleWrap}
         />
       )}

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/onboarding-guides/onboarding-guide-detail-view.tsx

@@ -15,7 +15,7 @@
  * renderer with extra plugins.
  */
 
-import { type ComponentType, type ReactNode } from 'react'
+import { Fragment, type ComponentType, type ReactNode } from 'react'
 import { PageLayout } from '../layout/page-layout'
 
 import { useRouter } from '../../embed-shims'
@@ -30,7 +30,7 @@ import { VideoBitesStrip } from '../features/video-bites-strip'
 import { toStripProfile } from '../features/video-bites-shared'
 import { useVideoWarmup } from '../features/use-video-warmup'
 import { getCaptionsUrl } from '../features/captions-url'
-import { RichMarkdownRenderer } from '../ui/rich-markdown-renderer'
+import { RichMarkdownRenderer } from '../ui/markdown'
 import { EntityTagBadges } from '../features/entity-tag-badges'
 import { LoadError } from '../ui/error-state'
 import { ArticleAuthorByline } from '../shared/article-author-byline'
@@ -244,8 +244,26 @@ export function OnboardingGuideDetailView({
           </div>
         )}
 
-        {/* Host slot — cross-type related-content / FAQ rail. */}
-        {relatedContent}
+        {/*
+         * Host slot — cross-type related-content / FAQ rail.
+         *
+         * KEYED DELIBERATELY. This is one member of PageLayout's static children
+         * array, and the only member whose element may be created in a SERVER
+         * component and crossed over the RSC boundary. Static JSX children are
+         * normally exempt from the key warning because `jsxs` runs
+         * `validateChildKeys` and stamps `_store.validated = 1` on each element —
+         * but a slot arriving over the wire is referenced as a lazy chunk wrapper,
+         * so validation marks the WRAPPER and the fulfilled path never copies the
+         * flag onto the revived element. It reaches the reconciler with
+         * `validated: 0, key: null` and warns, blaming PageLayout (the owner of the
+         * enclosing element) rather than anything actually at fault.
+         *
+         * A keyed Fragment emits no DOM, so rendered output is byte-identical.
+         * Do NOT "fix" this in PageLayout via `React.Children.toArray` — that would
+         * auto-key every consumer's children and change reconciliation identity for
+         * all of them, and that file carries an explicit FROZEN contract.
+         */}
+        <Fragment key="related-content">{relatedContent}</Fragment>
       </PageLayout>
   )
 }

package/src/components/shared/legal-document/legal-document-page.tsx

@@ -19,7 +19,7 @@
 
 import type { ComponentType } from 'react';
 import { PageShell, PageLayout } from '../../ui';
-import { RichMarkdownRenderer } from '../../ui/rich-markdown-renderer';
+import { RichMarkdownRenderer } from '../../ui/markdown';
 import { useRouter } from '../../../embed-shims/next-navigation';
 import { useLegalDocs, type LegalDocument } from './use-legal-docs';
 import { formatLegalDate } from '../../../utils/format';

package/src/components/shared/product-release/release-detail-page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useState, useEffect, ComponentType, type ReactNode } from 'react';
+import { useState, useEffect, Fragment, ComponentType, type ReactNode } from 'react';
 import Link from '../../../embed-shims/next-link';
 import { useRouter } from '../../../embed-shims/next-navigation';
 import { Card, CardContent } from '../../ui/card';
@@ -11,7 +11,7 @@ import { PageShell } from '../../layout/article-detail-layout';
 import { PageLayout } from '../../layout/page-layout';
 import { FadePreview } from '../../ui/fade-preview';
 import { ReleaseChangelogSection } from '../../ui/release-changelog-section';
-import { RichMarkdownRenderer } from '../../ui/rich-markdown-renderer';
+import { RichMarkdownRenderer } from '../../ui/markdown';
 import { EntityTagBadges } from '../../features/entity-tag-badges';
 import { EntityMetadataAuthorCell } from '../../chat/entity-cards/entity-author-card';
 import type { EntityAuthor } from '../../../types/entity-author';
@@ -582,8 +582,23 @@ export function ReleaseDetailPage({
         )}
       </div>
 
-      {/* Host slot — end-of-article byline + related-content / FAQ rail. */}
-      {relatedContent}
+      {/*
+       * Host slot — end-of-article byline + related-content / FAQ rail.
+       *
+       * KEYED for the same reason as `onboarding-guide-detail-view.tsx`: this is a
+       * member of PageLayout's static children array, and a slot element built in a
+       * SERVER component crosses the RSC boundary as a lazy chunk wrapper, so
+       * `validateChildKeys` marks the wrapper and the fulfilled path never copies
+       * `_store.validated` onto the revived element — it reaches the reconciler
+       * unvalidated and warns.
+       *
+       * Today the hub's only consumer of this view is a `'use client'` wrapper that
+       * builds the slot locally, so no element actually crosses the boundary and
+       * this is pre-emptive. It is kept because the trap is invisible from here: a
+       * future server-built slot would warn with no clue pointing at this line.
+       * A keyed Fragment emits no DOM, so output is byte-identical either way.
+       */}
+      <Fragment key="related-content">{relatedContent}</Fragment>
       </PageLayout>
   );
 }

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}