@skyhook-io/k8s-ui 1.14.12 → 1.16.0

package/src/components/ui/DialogPortal.tsx

@@ -1,4 +1,10 @@
-import { useEffect, useRef, type KeyboardEvent as ReactKeyboardEvent, type ReactNode } from 'react'
+import {
+  useEffect,
+  useRef,
+  type FocusEvent as ReactFocusEvent,
+  type KeyboardEvent as ReactKeyboardEvent,
+  type ReactNode,
+} from 'react'
 import { createPortal } from 'react-dom'
 import { clsx } from 'clsx'
 import { useAnimatedUnmount } from '../../hooks/useAnimatedUnmount'
@@ -12,6 +18,36 @@ interface DialogPortalProps {
   className?: string
   /** Prevent closing via Escape / backdrop click (e.g. during async operation) */
   closable?: boolean
+  /** Id of the element that names the dialog (usually its title). Preferred over `ariaLabel`. */
+  ariaLabelledBy?: string
+  /** Accessible name when there is no visible title to reference. */
+  ariaLabel?: string
+}
+
+const FOCUS_GUARD = 'fixed top-0 left-0 w-px h-0 overflow-hidden outline-none'
+
+const TABBABLE_SELECTOR = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'iframe',
+  '[contenteditable]:not([contenteditable="false"])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',')
+
+// A CSS-hidden element (display:none, visibility:hidden) can't take focus, so
+// treating it as an edge would let Tab slip past the real last element.
+function isVisible(el: HTMLElement): boolean {
+  return typeof el.checkVisibility === 'function' ? el.checkVisibility({ visibilityProperty: true }) : true
+}
+
+function tabbableElements(panel: HTMLElement): HTMLElement[] {
+  return Array.from(panel.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR)).filter(
+    el => el.tabIndex >= 0 && !el.matches(':disabled') && !el.closest('[inert],[hidden]') && isVisible(el),
+  )
 }
 
 /**
@@ -19,14 +55,30 @@ interface DialogPortalProps {
  * Renders children inside a centered panel portaled to document.body, so it works
  * correctly even inside CSS-transformed containers (drawers, slide panels).
  *
+ * Focus moves into the panel on open (unless a child already took it, e.g. via
+ * `autoFocus`), Tab wraps at the panel's edges, and focus returns to the element
+ * that opened the dialog at logical close.
+ *
  * Usage:
- *   <DialogPortal open={showDialog} onClose={() => setShowDialog(false)} className="w-80">
- *     <h3>Title</h3>
+ *   <DialogPortal open={showDialog} onClose={() => setShowDialog(false)} className="w-80" ariaLabelledBy={titleId}>
+ *     <h3 id={titleId}>Title</h3>
  *     <p>Content</p>
  *   </DialogPortal>
  */
-export function DialogPortal({ open, onClose, children, className, closable = true }: DialogPortalProps) {
+export function DialogPortal({
+  open,
+  onClose,
+  children,
+  className,
+  closable = true,
+  ariaLabelledBy,
+  ariaLabel,
+}: DialogPortalProps) {
   const dialogRef = useRef<HTMLDivElement>(null)
+  // `el` is null when focus entered from nowhere restorable (body, or an
+  // element outside the panel that has since been removed).
+  const openerRef = useRef<{ el: HTMLElement | null } | null>(null)
+  const pendingRestoreRef = useRef(false)
   // The unmount window is the exit duration: shorter than the entrance, and
   // exactly what the panel transition below runs — a mismatch here cut the
   // close at two-thirds (200ms window under a 300ms panel).
@@ -44,15 +96,69 @@ export function DialogPortal({ open, onClose, children, className, closable = tr
     }
   }
 
+  // Guards on either side of the panel catch focus leaving it, so inside the
+  // panel the browser's own Tab order applies — scroll containers, radio
+  // groups, editors that claim Tab — and only the wrap is decided here.
+  const focusEdge = (toLast: boolean) => {
+    const panel = dialogRef.current
+    if (!panel) return
+    // A candidate can still refuse focus; stopping on the first refusal would
+    // leave focus on the guard, one keypress from the page behind.
+    const items = tabbableElements(panel)
+    for (const el of toLast ? items.reverse() : items) {
+      el.focus()
+      if (document.activeElement === el) return
+    }
+    panel.focus()
+  }
+
+  // Leaving past one edge wraps to the other; arriving from outside the panel
+  // enters at the near edge.
+  const handleGuardFocus = (edge: 'start' | 'end') => (e: ReactFocusEvent<HTMLSpanElement>) => {
+    const panel = dialogRef.current
+    const fromInside = e.relatedTarget instanceof Node && !!panel?.contains(e.relatedTarget)
+    focusEdge(edge === 'start' ? fromInside : !fromInside)
+  }
+
+  // Focus drops to body when the focused control is disabled or removed (a
+  // confirm button entering its loading state); the next Tab would then land
+  // behind the modal. Focus elsewhere (a menu portaled out of the panel) is
+  // left alone.
+  const recoverStrayTab = (e: KeyboardEvent) => {
+    const panel = dialogRef.current
+    const active = document.activeElement
+    if (!panel || (active && active !== document.body)) return
+    e.preventDefault()
+    focusEdge(e.shiftKey)
+  }
+
+  // relatedTarget on the first focus into the panel is the opener. Reading
+  // document.activeElement in an effect would miss it when a child `autoFocus`
+  // has already moved focus during commit — which also happens before
+  // dialogRef is attached, hence currentTarget.
+  const handlePanelFocus = (e: ReactFocusEvent<HTMLDivElement>) => {
+    const panel = e.currentTarget
+    if (!open || openerRef.current || !panel.contains(e.target as Node)) return
+    const from = e.relatedTarget
+    openerRef.current = { el: from instanceof HTMLElement && !panel.contains(from) ? from : null }
+  }
+
   useEffect(() => {
     if (!open) return
 
     const handleDocumentKeyDown = (e: KeyboardEvent) => {
-      if (e.key !== 'Escape') return
+      if (e.key !== 'Escape' && e.key !== 'Tab') return
+      // A dialog still animating out is inert and no longer the one on top.
       const modalDialogs = Array.from(document.querySelectorAll<HTMLElement>('[role="dialog"][aria-modal="true"]'))
+        .filter(d => !d.closest('[inert]'))
       const topDialog = modalDialogs[modalDialogs.length - 1]
       if (topDialog !== dialogRef.current) return
 
+      if (e.key === 'Tab') {
+        recoverStrayTab(e)
+        return
+      }
+
       if (dialogRef.current?.contains(e.target as Node)) return
 
       e.stopPropagation()
@@ -67,17 +173,44 @@ export function DialogPortal({ open, onClose, children, className, closable = tr
     return () => document.removeEventListener('keydown', handleDocumentKeyDown, true)
   }, [open, closable, onClose])
 
-  // Move focus into the dialog for accessibility and tab navigation
+  // The panel mounts a render after `open` flips (useAnimatedUnmount sets
+  // shouldRender in an effect), so this must also wait on shouldRender.
   useEffect(() => {
-    if (open && dialogRef.current) {
-      dialogRef.current.focus()
+    const panel = dialogRef.current
+    if (!open || !shouldRender || !panel) return
+    if (!panel.contains(document.activeElement)) panel.focus()
+  }, [open, shouldRender])
+
+  // Restore at logical close (open → false, or unmount while open), not after
+  // the exit. The microtask lets StrictMode's simulated unmount/remount cancel
+  // the restore; otherwise dev builds would pull focus out of an autoFocus child.
+  useEffect(() => {
+    if (!open) return
+    pendingRestoreRef.current = false
+    return () => {
+      pendingRestoreRef.current = true
+      queueMicrotask(() => {
+        if (!pendingRestoreRef.current) return
+        pendingRestoreRef.current = false
+        const opener = openerRef.current?.el
+        openerRef.current = null
+        if (!opener?.isConnected) return
+        const active = document.activeElement
+        const panel = dialogRef.current
+        // Don't steal focus from wherever the close action deliberately sent it.
+        const focusStillOurs = !active || active === document.body || !!panel?.contains(active)
+        if (focusStillOurs) opener.focus({ preventScroll: true })
+      })
     }
   }, [open])
 
   if (!shouldRender) return null
 
   return createPortal(
-    <div className="fixed inset-0 z-50 flex items-center justify-center">
+    <div
+      className={clsx('fixed inset-0 z-50 flex items-center justify-center', !open && 'pointer-events-none')}
+      inert={!open}
+    >
       <div
         className={clsx(
           'absolute inset-0 bg-black/60 backdrop-blur-sm',
@@ -87,12 +220,16 @@ export function DialogPortal({ open, onClose, children, className, closable = tr
         style={overlayTransitionStyle(isOpen, 'dialog')}
         onClick={closable ? onClose : undefined}
       />
+      <span tabIndex={0} aria-hidden data-focus-guard onFocus={handleGuardFocus('start')} className={FOCUS_GUARD} />
       <div
         ref={dialogRef}
         role="dialog"
         aria-modal="true"
+        aria-labelledby={ariaLabelledBy}
+        aria-label={ariaLabelledBy ? undefined : ariaLabel}
         tabIndex={-1}
         onKeyDown={handleDialogKeyDown}
+        onFocus={handlePanelFocus}
         className={clsx(
           'relative bg-theme-surface border border-theme-border rounded-lg shadow-2xl mx-4 outline-none',
           TRANSITION_PANEL,
@@ -103,6 +240,7 @@ export function DialogPortal({ open, onClose, children, className, closable = tr
       >
         {children}
       </div>
+      <span tabIndex={0} aria-hidden data-focus-guard onFocus={handleGuardFocus('end')} className={FOCUS_GUARD} />
     </div>,
     document.body,
   )

package/src/components/ui/FilterPill.tsx

@@ -52,7 +52,7 @@ const TONE_ACTIVE: Record<FilterPillTone, string> = {
   high:    'bg-orange-500/15 border-orange-500/40 text-orange-800 dark:text-orange-300',
   medium:  'bg-yellow-500/15 border-yellow-500/40 text-yellow-800 dark:text-yellow-300',
   ok:      'bg-emerald-500/15 border-emerald-500/40 text-emerald-700 dark:text-emerald-300',
-  brand:   'bg-[var(--color-brand-50)] border-[var(--color-radar-accent)] text-theme-text-primary dark:bg-[var(--color-brand-950)]',
+  brand:   'bg-[var(--color-brand-50,var(--accent-muted))] border-[var(--color-radar-accent,var(--accent))] text-theme-text-primary dark:bg-[var(--color-brand-950,var(--accent-muted))]',
 }
 
 const INACTIVE = 'border-theme-border-light text-theme-text-secondary hover:border-theme-border hover:text-theme-text-primary hover:bg-theme-hover/50'

package/src/components/ui/RadarUpgradeNote.click.test.tsx

@@ -0,0 +1,24 @@
+// @vitest-environment jsdom
+import { act } from 'react'
+import { createRoot } from 'react-dom/client'
+import { expect, it, vi } from 'vitest'
+import { RadarUpgradeContext, RadarUpgradeNote } from './RadarUpgradeNote'
+
+vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+
+it('hands the whole requirement to the host when the user asks to upgrade', async () => {
+  const onRequestUpgrade = vi.fn()
+  const requirement = { feature: 'Policy results', minimumVersion: 'v1.10.0', currentVersion: 'v1.7.2', latestVersion: 'v1.16.0' }
+  const element = document.createElement('div')
+  const root = createRoot(element)
+  await act(async () => {
+    root.render(
+      <RadarUpgradeContext.Provider value={{ onRequestUpgrade }}>
+        <RadarUpgradeNote requirement={requirement} />
+      </RadarUpgradeContext.Provider>,
+    )
+  })
+  await act(async () => { element.querySelector('button')!.click() })
+  expect(onRequestUpgrade).toHaveBeenCalledWith(requirement)
+  await act(async () => root.unmount())
+})

package/src/components/ui/RadarUpgradeNote.test.tsx

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { formatRadarVersion, radarUpgradeDetail, radarUpgradeHeadline, RadarUpgradeNote } from './RadarUpgradeNote'
+import { getRadarUpgradeRequirement } from '../../types/fetch-error'
+
+describe('radarUpgradeHeadline', () => {
+  it('says the cluster is behind, not the UI', () => {
+    expect(radarUpgradeHeadline('Capacity')).toBe('Capacity needs a newer Radar on this cluster')
+  })
+})
+
+describe('radarUpgradeDetail', () => {
+  it('quotes the minimum and a real current version', () => {
+    expect(radarUpgradeDetail({ feature: 'Policy results', minimumVersion: 'v1.10.0', currentVersion: '1.7.2' }))
+      .toBe('Available from Radar v1.10. This cluster runs v1.7.2.')
+  })
+
+  it('leaves out a current version that is not a version', () => {
+    expect(radarUpgradeDetail({ feature: 'Policy results', minimumVersion: 'v1.10.0', currentVersion: 'dev' }))
+      .toBe('Available from Radar v1.10.')
+    expect(radarUpgradeDetail({ feature: 'Policy results', minimumVersion: 'v1.10.0' }))
+      .toBe('Available from Radar v1.10.')
+  })
+})
+
+describe('radarUpgradeDetail without a known first release', () => {
+  const unknownSince = { feature: 'Drift alerts', currentVersion: 'v1.7.2' }
+
+  it('asks for the latest release when it is newer than the running one', () => {
+    expect(radarUpgradeDetail({ ...unknownSince, latestVersion: '1.16.0' }))
+      .toBe('Available in the latest Radar, v1.16. This cluster runs v1.7.2.')
+  })
+
+  it('only names the running version when no target release is known', () => {
+    expect(radarUpgradeDetail(unknownSince)).toBe('This cluster runs v1.7.2.')
+    expect(radarUpgradeDetail({ ...unknownSince, currentVersion: 'v1.16.0', latestVersion: 'v1.16.0' }))
+      .toBe('This cluster runs v1.16.')
+  })
+
+  it('reads the same way inline', () => {
+    const html = renderToString(<RadarUpgradeNote requirement={{ ...unknownSince, latestVersion: 'v1.16.0' }} />)
+    expect(html).toContain('need the latest Radar (v1.16) on this cluster. It runs v1.7.2.')
+  })
+})
+
+describe('formatRadarVersion', () => {
+  it('drops a zero patch and adds the v', () => {
+    expect(formatRadarVersion('v1.14.0')).toBe('v1.14')
+    expect(formatRadarVersion('1.7.2')).toBe('v1.7.2')
+    expect(formatRadarVersion('v1.7.2-dirty')).toBe('v1.7.2-dirty')
+  })
+})
+
+describe('getRadarUpgradeRequirement', () => {
+  it('reads the requirement off any error that carries one', () => {
+    const error = Object.assign(new Error('x'), { radarUpgrade: { feature: 'Drain plans', minimumVersion: 'v1.14.0' } })
+    expect(getRadarUpgradeRequirement(error)).toEqual({ feature: 'Drain plans', minimumVersion: 'v1.14.0' })
+  })
+
+  it('ignores plain errors and malformed requirements', () => {
+    expect(getRadarUpgradeRequirement(new Error('HTTP 404 (Not Found)'))).toBeNull()
+    expect(getRadarUpgradeRequirement({ radarUpgrade: { minimumVersion: 'v1.9.0' } })).toBeNull()
+    expect(getRadarUpgradeRequirement({ radarUpgrade: { feature: 'x', minimumVersion: 9 } })).toBeNull()
+    expect(getRadarUpgradeRequirement(null)).toBeNull()
+  })
+})

package/src/components/ui/RadarUpgradeNote.tsx

@@ -0,0 +1,129 @@
+import { createContext, useContext } from 'react'
+import { clsx } from 'clsx'
+import { ArrowUpCircle, ExternalLink } from 'lucide-react'
+import type { RadarUpgradeRequirement } from '../../types/fetch-error'
+
+export interface RadarUpgradeActions {
+  /** Hands the upgrade to the host, e.g. Radar Cloud's role-aware upgrade flow. */
+  onRequestUpgrade?: (requirement: RadarUpgradeRequirement) => void
+  /** Used when there is no handler: a page with upgrade instructions. */
+  upgradeHref?: string
+}
+
+export const RadarUpgradeContext = createContext<RadarUpgradeActions>({})
+
+/** "v1.10.0" → "v1.10", "1.7.2" → "v1.7.2". Anything else is shown as given. */
+export function formatRadarVersion(version: string): string {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(version.trim())
+  if (!match) return version
+  const [, major, minor, patch] = match
+  return patch === '0' ? `v${major}.${minor}` : `v${major}.${minor}.${patch}`
+}
+
+function parseVersion(version: string | undefined): number[] | null {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(version?.trim() ?? '')
+  return match ? match.slice(1).map(Number) : null
+}
+
+function isNewer(a: number[], b: number[]): boolean {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i]
+  return false
+}
+
+/**
+ * Which Radar to ask for. The release that introduced the feature when it is
+ * known; otherwise the latest release, which serves everything this UI calls;
+ * otherwise just "a newer Radar".
+ */
+function target(requirement: RadarUpgradeRequirement): { since?: string; latest?: string } {
+  if (requirement.minimumVersion) return { since: formatRadarVersion(requirement.minimumVersion) }
+  const { latestVersion } = requirement
+  const latest = parseVersion(latestVersion)
+  const current = parseVersion(requirement.currentVersion)
+  if (latestVersion && latest && (!current || isNewer(latest, current))) {
+    return { latest: formatRadarVersion(latestVersion) }
+  }
+  return {}
+}
+
+// The Radar that is behind is the cluster's, not the UI the user is looking
+// at, so the copy names the cluster. "It runs dev." says nothing useful, so
+// only a real version is quoted.
+function clusterVersion(requirement: RadarUpgradeRequirement): string | undefined {
+  const current = requirement.currentVersion?.trim()
+  return current && /^v?\d+\.\d+/.test(current) ? formatRadarVersion(current) : undefined
+}
+
+/** Headline for a full-page state: "Capacity needs a newer Radar on this cluster". */
+export function radarUpgradeHeadline(feature: string): string {
+  return `${feature} needs a newer Radar on this cluster`
+}
+
+/** Detail under that headline: "Available from Radar v1.9. This cluster runs v1.7.2." */
+export function radarUpgradeDetail(requirement: RadarUpgradeRequirement): string {
+  const { since, latest } = target(requirement)
+  const current = clusterVersion(requirement)
+  return [
+    since ? `Available from Radar ${since}.` : latest ? `Available in the latest Radar, ${latest}.` : '',
+    current ? `This cluster runs ${current}.` : '',
+  ].filter(Boolean).join(' ')
+}
+
+/** Follows the feature name in an inline note: "need Radar v1.10 or newer on this cluster. It runs v1.7.2." */
+function radarUpgradeNeed(requirement: RadarUpgradeRequirement): string {
+  const { since, latest } = target(requirement)
+  const current = clusterVersion(requirement)
+  const need = since
+    ? `need Radar ${since} or newer on this cluster.`
+    : latest
+      ? `need the latest Radar (${latest}) on this cluster.`
+      : 'need a newer Radar on this cluster.'
+  return current ? `${need} It runs ${current}.` : need
+}
+
+/** The upgrade call to action, or nothing when the host offers no way to upgrade. */
+export function RadarUpgradeAction({ requirement }: { requirement: RadarUpgradeRequirement }) {
+  const { onRequestUpgrade, upgradeHref } = useContext(RadarUpgradeContext)
+  const className = 'inline-flex items-center gap-1 font-medium text-accent-text hover:underline'
+  if (onRequestUpgrade) {
+    return (
+      <button type="button" className={className} onClick={() => onRequestUpgrade(requirement)}>
+        Upgrade Radar
+      </button>
+    )
+  }
+  if (upgradeHref) {
+    return (
+      <a href={upgradeHref} target="_blank" rel="noopener noreferrer" className={className}>
+        How to upgrade
+        <ExternalLink className="h-3 w-3" aria-hidden />
+      </a>
+    )
+  }
+  return null
+}
+
+/**
+ * Inline note for a feature the connected Radar is too old to serve. Calm on
+ * purpose: nothing failed, the cluster just runs an older Radar than this UI.
+ */
+export function RadarUpgradeNote({
+  requirement,
+  className,
+}: {
+  requirement: RadarUpgradeRequirement
+  className?: string
+}) {
+  return (
+    <div className={clsx('flex items-start gap-2 text-xs text-theme-text-secondary', className)}>
+      <ArrowUpCircle className="mt-px h-3.5 w-3.5 shrink-0 text-accent-text" aria-hidden />
+      <p className="min-w-0">
+        <span className="font-medium text-theme-text-primary">{requirement.feature}</span>
+        {' '}
+        {radarUpgradeNeed(requirement)}
+        {' '}
+        <RadarUpgradeAction requirement={requirement} />
+      </p>
+    </div>
+  )
+}

package/src/components/ui/ResourceBar.tsx

@@ -60,7 +60,7 @@ export function ResourceBar({
   label,
 }: ResourceBarProps) {
   const track = (
-    <div className={clsx('relative', layout === 'inline' && 'min-w-0 flex-1')}>
+    <div className={clsx('relative', layout === 'inline' && 'min-w-16 flex-1')}>
       <div className={clsx('rounded-full border border-theme-border bg-theme-elevated overflow-hidden', layout === 'inline' ? 'h-1' : 'h-1.5')}>
         <div
           className={clsx('h-full rounded-full transition-[width] duration-300 ease-out', getBarColor(percent, colorScheme))}
@@ -78,7 +78,7 @@ export function ResourceBar({
 
   const bar =
     layout === 'inline' ? (
-      <div className="flex items-center gap-1.5 min-w-0">
+      <div className={clsx('flex items-center gap-1.5 min-w-0', tooltip && 'w-full')}>
         <span className="w-7 shrink-0 text-[10px] font-medium uppercase tracking-wide text-theme-text-tertiary">{label}</span>
         {track}
         <span className="w-8 shrink-0 text-right text-[10.5px] font-mono tabular-nums text-theme-text-secondary">
@@ -86,7 +86,7 @@ export function ResourceBar({
         </span>
       </div>
     ) : (
-      <div className="flex flex-col gap-0.5 min-w-0">
+      <div className={clsx('flex flex-col gap-0.5 min-w-0', tooltip && 'w-full')}>
         <div className="flex items-baseline justify-between gap-1">
           <span className="text-xs font-mono text-theme-text-secondary truncate">
             {used} / {total}
@@ -99,11 +99,17 @@ export function ResourceBar({
       </div>
     )
 
+  // Tooltip's wrapper is inline-flex: it sizes the row to its content (hence
+  // w-full on the row, or the track collapses to the labels' width) and it is
+  // inline-level, so the block div keeps sibling bars stacked instead of
+  // sharing one line.
   if (tooltip) {
     return (
-      <Tooltip content={tooltip} delay={200} position="top" wrapperClassName="w-full min-w-0">
-        {bar}
-      </Tooltip>
+      <div className="min-w-0">
+        <Tooltip content={tooltip} delay={200} position="top" wrapperClassName="w-full min-w-0">
+          {bar}
+        </Tooltip>
+      </div>
     )
   }
 

package/src/components/ui/SelectMenu.tsx

@@ -7,6 +7,8 @@ import { TRANSITION_MENU, overlayExitMs, overlayTransitionStyle } from '../../ut
 export interface SelectMenuOption {
   value: string
   label: string
+  description?: string
+  disabled?: boolean
 }
 
 export function SelectMenu({
@@ -17,6 +19,8 @@ export function SelectMenu({
   ariaDescribedBy,
   className,
   searchPlaceholder,
+  placeholder,
+  variant = 'default',
   disabled = false,
   id,
 }: {
@@ -27,6 +31,8 @@ export function SelectMenu({
   ariaDescribedBy?: string
   className?: string
   searchPlaceholder?: string
+  placeholder?: string
+  variant?: 'default' | 'text'
   disabled?: boolean
   id?: string
 }) {
@@ -40,15 +46,33 @@ export function SelectMenu({
   const searchInputRef = useRef<HTMLInputElement>(null)
   const listRef = useRef<HTMLDivElement>(null)
   const pointerDownInsideRef = useRef(false)
-  const selected = options.find((option) => option.value === value) ?? options[0]
+  // A keyboard open lands on the selected option, as a native select does; a
+  // pointer open keeps focus on the trigger.
+  const focusOptionOnOpenRef = useRef(false)
+  const selected = options.find((option) => option.value === value) ?? (placeholder ? undefined : options[0])
   const filteredOptions = useMemo(() => {
     const normalized = query.trim().toLowerCase()
     if (!normalized) return options
-    return options.filter((option) => option.label.toLowerCase().includes(normalized))
+    return options.filter((option) => `${option.label} ${option.description ?? ''}`.toLowerCase().includes(normalized))
   }, [options, query])
   const selectedIsVisible = filteredOptions.some((option) => option.value === value)
 
+  const focusTabbableOption = () => {
+    listRef.current?.querySelector<HTMLElement>('[role="option"][tabindex="0"]')?.focus()
+  }
+
+  const openMenu = () => {
+    setHighlightedIndex(
+      Math.max(
+        options.findIndex((option) => option.value === value),
+        0,
+      ),
+    )
+    setOpen(true)
+  }
+
   const selectOption = (nextValue: string) => {
+    if (options.find((option) => option.value === nextValue)?.disabled) return
     onChange(nextValue)
     setOpen(false)
     triggerRef.current?.focus()
@@ -81,7 +105,12 @@ export function SelectMenu({
   useEffect(() => {
     if (!open || !shouldRender) return
     if (!searchPlaceholder) {
-      triggerRef.current?.focus()
+      if (focusOptionOnOpenRef.current) {
+        focusOptionOnOpenRef.current = false
+        focusTabbableOption()
+      } else {
+        triggerRef.current?.focus()
+      }
       return
     }
     listRef.current
@@ -130,28 +159,38 @@ export function SelectMenu({
         aria-expanded={open}
         aria-controls={open ? listboxId : undefined}
         onClick={() => {
-          if (!open) {
-            setHighlightedIndex(
-              Math.max(
-                options.findIndex((option) => option.value === value),
-                0,
-              ),
-            )
+          if (open) setOpen(false)
+          else openMenu()
+        }}
+        onKeyDown={(event) => {
+          if (searchPlaceholder) return
+          const arrow = event.key === 'ArrowDown' || event.key === 'ArrowUp'
+          if (!arrow && (open || (event.key !== 'Enter' && event.key !== ' '))) return
+          event.preventDefault()
+          if (open) {
+            focusTabbableOption()
+            return
           }
-          setOpen(!open)
+          focusOptionOnOpenRef.current = true
+          openMenu()
         }}
         disabled={disabled}
-        className="flex h-8 w-full items-center justify-between gap-2 rounded-md border border-theme-border bg-theme-elevated px-2.5 text-xs text-theme-text-primary transition-colors hover:bg-theme-hover disabled:cursor-not-allowed disabled:opacity-60 disabled:hover:bg-theme-elevated"
+        className={clsx(
+          'flex items-center gap-1 text-xs disabled:cursor-not-allowed disabled:opacity-50',
+          variant === 'text'
+            ? 'text-accent-text hover:underline'
+            : 'h-8 w-full justify-between gap-2 rounded-md border border-theme-border bg-theme-elevated px-2.5 text-theme-text-primary transition-colors hover:bg-theme-hover disabled:hover:bg-theme-elevated',
+        )}
       >
-        <span className="truncate">{selected?.label}</span>
-        <ChevronDown className={clsx('h-3.5 w-3.5 shrink-0 text-theme-text-tertiary transition-transform', open && 'rotate-180')} />
+        <span className="truncate">{selected?.label ?? placeholder}</span>
+        <ChevronDown className={clsx('h-3.5 w-3.5 shrink-0 transition-transform', variant !== 'text' && 'text-theme-text-tertiary', open && 'rotate-180')} />
       </button>
       {shouldRender && (
         <div
           inert={!open}
           className={clsx(
             'absolute top-full z-50 mt-1 min-w-full overflow-hidden rounded-md border border-theme-border bg-theme-surface shadow-theme-lg',
-            searchPlaceholder ? 'left-0 right-0 origin-top-left' : 'right-0 origin-top-right',
+            variant === 'text' ? 'left-0 w-72 max-w-[calc(100vw-4rem)] origin-top-left' : searchPlaceholder ? 'left-0 right-0 origin-top-left' : 'right-0 origin-top-right',
             TRANSITION_MENU,
             isOpen ? 'opacity-100 translate-y-0 scale-100' : 'opacity-0 -translate-y-1 scale-[0.97]',
             !open && 'pointer-events-none',
@@ -177,8 +216,7 @@ export function SelectMenu({
                 onKeyDown={(event) => {
                   if (event.key === 'Enter' && filteredOptions.length > 0) {
                     event.preventDefault()
-                    const nextIndex = Math.min(highlightedIndex, filteredOptions.length - 1)
-                    selectOption(filteredOptions[nextIndex].value)
+                    selectOption(filteredOptions[Math.min(highlightedIndex, filteredOptions.length - 1)].value)
                   } else if (event.key === 'ArrowDown') {
                     event.preventDefault()
                     const optionElements = listRef.current?.querySelectorAll<HTMLButtonElement>('[role="option"]')
@@ -244,19 +282,24 @@ export function SelectMenu({
                   type="button"
                   role="option"
                   aria-selected={active}
+                  aria-disabled={option.disabled || undefined}
                   tabIndex={
                     searchPlaceholder ? (index === highlightedIndex ? 0 : -1) : active || (!selectedIsVisible && index === 0) ? 0 : -1
                   }
                   onClick={() => selectOption(option.value)}
                   onFocus={() => setHighlightedIndex(index)}
                   className={clsx(
-                    'flex w-full items-center gap-2 px-2.5 py-1.5 text-left text-xs text-theme-text-secondary transition-colors hover:bg-theme-hover hover:text-theme-text-primary',
+                    'flex w-full items-center gap-2 px-2.5 py-1.5 text-left text-xs text-theme-text-secondary transition-colors',
+                    option.disabled ? 'cursor-not-allowed opacity-60' : 'hover:bg-theme-hover hover:text-theme-text-primary',
                     searchPlaceholder && index === highlightedIndex && 'bg-theme-hover text-theme-text-primary',
                     !searchPlaceholder && 'whitespace-nowrap'
                   )}
                 >
                   <Check className={clsx('h-3.5 w-3.5 shrink-0 text-accent', !active && 'opacity-0')} />
-                  <span className={clsx(searchPlaceholder && 'truncate')}>{option.label}</span>
+                  <span className={clsx('min-w-0', searchPlaceholder && !option.description && 'truncate')}>
+                    <span className={clsx(option.description && 'block break-words font-medium')}>{option.label}</span>
+                    {option.description && <span className="block break-all text-theme-text-tertiary">{option.description}</span>}
+                  </span>
                 </button>
               )
             })}