@flamingo-stack/openframe-frontend-core 0.0.489 → 0.0.490-snapshot.20260728181420

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

package/src/stories/ChatMessageEnhanced.stories.tsx

@@ -183,7 +183,50 @@ export const PendingApprovalSegment: Story = {
 	},
 };
 
-/** Every remaining segment type in one message — thinking, tool execution, context compaction, error. */
+/**
+ * `[card://]` markers inside a `guide` segment resolve exactly as they do in a
+ * text segment — the host's `renderEntityCard` node is hoisted out of the
+ * markdown as a sibling block, and an unknown id degrades to the bare id.
+ * Regression guard: the guide body used to skip the marker plan entirely.
+ */
+export const GuideWithEntityCards: Story = {
+	args: {
+		role: "assistant",
+		name: "Mingo",
+		assistantType: "mingo",
+		timestamp: at247(),
+		chatRefs: {
+			"onboarding_guide:first-check": {
+				type: "onboarding_guide",
+				id: "first-check",
+				title: "Create Your First Monitoring Check",
+				url: "/help-center/onboarding-guides/first-check",
+			},
+			"onboarding_guide:add-devices": {
+				type: "onboarding_guide",
+				id: "add-devices",
+				title: "Add Devices to a Policy",
+				url: "/help-center/onboarding-guides/add-devices",
+			},
+		},
+		renderEntityCard: (ref) =>
+			ref.type === "onboarding_guide" ? (
+				<div className="flex items-center gap-[var(--spacing-system-s)] rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-s)]">
+					<span className="flex-1 text-h4 text-ods-text-primary">{ref.title}</span>
+					<span className="text-h5 text-ods-text-secondary">Guide</span>
+				</div>
+			) : null,
+		content: [
+			{
+				type: "guide",
+				text: "Here's how to create a monitoring policy (check) in OpenFrame:\n\n[card://onboarding_guide:first-check]\n\nStep-by-step:\n\n1. Go to Monitoring → Policies → Add Policy\n2. Write your osquery SQL query\n3. Save the policy",
+			},
+			{ type: "text", text: "A plain text segment renders its own marker identically:\n\n[card://onboarding_guide:add-devices]" },
+		] satisfies MessageSegment[],
+	},
+};
+
+/** Every remaining segment type in one message — thinking, guide, tool execution, context compaction, error. */
 export const AllSegmentTypes: Story = {
 	args: {
 		role: "assistant",
@@ -195,6 +238,10 @@ export const AllSegmentTypes: Story = {
 				text: "The user wants Slack installed. Homebrew is present on the endpoint, so `brew install --cask slack` is the cleanest path.",
 			},
 			{ type: "text", text: "Installing Slack now." },
+			{
+				type: "guide",
+				text: "Here's how to create a monitoring policy (check) in OpenFrame:\n\nStep-by-step:\n\n1. Go to Monitoring → Policies → Add Policy\n2. Give it a Name (something descriptive)\n3. Write your osquery SQL query — the query should return rows for devices that fail the check\n4. Set the interval — how often each device runs the check\n5. Save the policy",
+			},
 			{
 				type: "tool_execution",
 				data: {