@skyhook-io/k8s-ui 1.18.0 → 1.18.2

package/src/components/workload/WorkloadView.tsx

@@ -43,7 +43,7 @@ import type { NavigateToResource } from '../../utils/navigation'
 import { refToSelectedResource, pluralToKind, knownKindForPluralWithGroup, kindToPlural, kindToPluralWithGroup, apiVersionToGroup } from '../../utils/navigation'
 import { neighborhoodFor, seedNodeIds, topologyNodeResourceKind } from '../../utils/topology-neighborhood'
 import { TopologyGraph } from '../topology/TopologyGraph'
-import { gitOpsOwnerFromRelationships, type GitOpsOwnerRef } from '../../utils/gitops-owner'
+import { gitOpsOwnerFromRelationships, managerChipCoversGroup, managerChipPresentation, managerListing, type GitOpsOwnerRef } from '../../utils/gitops-owner'
 import { gitOpsRouteForResource } from '../../utils/gitops-route'
 import { buildResourceHierarchy, getAllEventsFromHierarchy, isProblematicEvent, type ResourceLane } from '../../utils/resource-hierarchy'
 import { TimelineSwimlanes, type TimeWindow } from '../timeline/TimelineSwimlanes'
@@ -57,11 +57,13 @@ import {
 import { ResourceRendererDispatch, getResourceStatus, diagnoseHealthHint, type DiagnoseHealthHint, type RendererOverrides } from '../shared/ResourceRendererDispatch'
 import type { ScalerDiagnosis } from '../resources/renderers/WorkloadRenderer'
 import { DetailShell, type DetailShellTab } from '../shared/DetailShell'
-import { HelmManagedByChip, ManagedByChip, type HelmOwnerRef } from '../shared/ManagedByChip'
+import { gitOpsOwnerKindLabel, HelmManagedByChip, ManagedByChip, type HelmOwnerRef } from '../shared/ManagedByChip'
 import { AlertBanner, getKindColorOutline, displayKindName, OperationalIssuesShownContext, ResourceRefBadge } from '../ui/drawer-components'
 import { Badge, type BadgeSeverity } from '../ui/Badge'
 import { Tooltip } from '../ui/Tooltip'
 import { midTruncate } from '../../utils/format'
+import { isManagedResource, isComposite, getCrossplanePauseState } from '../resources/resource-utils-crossplane'
+import { CrossplanePauseChip } from '../resources/renderers/CrossplanePauseContext'
 import { hpaStateLabel } from '../resources/resource-utils-hpa'
 import {
   cronToHuman,
@@ -216,6 +218,8 @@ interface WorkloadViewProps {
   /** Timeline events the history lanes are built from: this workload's own
    *  history, or events for its namespace from a host that has no scoped query. */
   allEvents?: TimelineEvent[]
+  /** Reveals one event, loading older pages if needed. Use a new object for each navigation request. */
+  timelineFocusEvent?: { id: string }
   /** Older history exists beyond allEvents. */
   historyTruncated?: boolean
   /** Loads the next older page of history; omit when the host can't page. */
@@ -469,6 +473,7 @@ export function WorkloadView({
   refetch: refetchProp,
   // Timeline
   allEvents,
+  timelineFocusEvent,
   historyTruncated = false,
   onLoadOlderHistory,
   loadingOlderHistory = false,
@@ -537,7 +542,7 @@ export function WorkloadView({
   gitOpsOwnerPending = false,
   gitOpsOwnerSource,
   gitOpsOwnerStatus,
-  helmOwner,
+  helmOwner: resolvedHelmOwner,
   helmOwnerSource,
   onOpenHelmRelease,
   onNavigateGitOpsPath,
@@ -722,7 +727,24 @@ export function WorkloadView({
   // Metadata
   const metadata = useMemo(() => extractMetadata(kind, resource), [kind, resource])
   const relationshipGitOpsOwner = useMemo(() => gitOpsOwnerFromRelationships(relationships), [relationships])
-  const gitopsOwner = resolvedGitOpsOwner ?? relationshipGitOpsOwner
+  const manager = relationships?.ownership?.manager
+  const gitopsOwner = manager ? relationshipGitOpsOwner : resolvedGitOpsOwner ?? relationshipGitOpsOwner
+  const helmOwner = manager
+    ? manager.lead?.kind === 'HelmRelease' && !manager.lead.group ? { namespace: manager.lead.namespace, name: manager.lead.name } : null
+    : resolvedHelmOwner
+  const showGitOpsChip = manager ? !helmOwner && Boolean(managerChipPresentation(manager)) : Boolean(gitopsOwner)
+  const listing = useMemo(
+    () => managerListing(gitopsOwner, relationships?.managers, gitOpsOwnerVerified, !relationships?.ownership?.managers),
+    [gitopsOwner, relationships?.managers, relationships?.ownership?.managers, gitOpsOwnerVerified],
+  )
+  // When the chip's manager is the only one whose status lists the resource,
+  // the chip says it all: Related Resources would repeat it.
+  const rendererRelationships = useMemo(
+    () => (relationships && (manager ? managerChipCoversGroup(relationships) : listing?.state === 'confirmed') ? { ...relationships, managers: undefined } : relationships),
+    [relationships, manager, listing],
+  )
+  // When they disagree, Related Resources says which manager the label names.
+  const trackedBy = !manager && listing?.state === 'conflict' && gitopsOwner ? `${gitOpsOwnerKindLabel(gitopsOwner)} ${gitopsOwner.namespace ? `${gitopsOwner.namespace}/` : ''}${gitopsOwner.name}` : undefined
   // When the resource itself is a portal GitOps CR (Application, Kustomization,
   // HelmRelease, etc.), surface a link to its dedicated GitOps detail page —
   // the drawer's renderer is thorough but the tab has the tree + insights +
@@ -820,6 +842,7 @@ export function WorkloadView({
     ? getWorkloadDisplayStatus(resource, apiKind, workloadPods)
     : null
   const rolloutActivity = rolloutDisplay?.activity ?? null
+  const crossplaneResource = isManagedResource(resource) || isComposite(resource) || getCrossplanePauseState(resource) === 'acknowledged'
   // A 404 with a cached copy: the object was deleted while this view was
   // open. Everything below that copy describes the past.
   const resourceGone = Boolean(resource) && isFetchError(resourceError) && resourceError.status === 404
@@ -907,7 +930,7 @@ export function WorkloadView({
       icon: <Activity className="w-4 h-4" />,
       badge: resourceEvents.length > 0 ? <span className="ml-1 badge-sm bg-theme-elevated">{resourceEvents.length}</span> : undefined,
     },
-    { id: 'logs', label: 'Logs', icon: <Terminal className="w-4 h-4" />, hidden: !logsTabVisible },
+    { id: 'logs', label: 'Logs', icon: <Terminal className="w-4 h-4" />, hidden: !logsTabVisible, phoneCompactHeader: true },
     { id: 'metrics', label: 'Metrics', icon: <BarChart3 className="w-4 h-4" />, hidden: !metricsTabVisible },
     {
       id: 'reachability',
@@ -960,6 +983,7 @@ export function WorkloadView({
                   {status.text}
                 </span>
               )}
+              {!resourceGone && crossplaneResource && <CrossplanePauseChip state={getCrossplanePauseState(resource)} />}
             </div>
             <div className="flex shrink-0 flex-nowrap items-center justify-end gap-1.5">
               {diagnoseAction}
@@ -1020,10 +1044,10 @@ export function WorkloadView({
               </Tooltip>
             </div>
             <p className="text-sm text-theme-text-tertiary">{namespace}</p>
-            {(gitopsOwner || helmOwner || (gitOpsResourcePath && onNavigateGitOpsPath) || onOpenLiveTraffic) && (
+            {(showGitOpsChip || helmOwner || (gitOpsResourcePath && onNavigateGitOpsPath) || onOpenLiveTraffic) && (
               <div className="mt-1 flex flex-wrap items-center gap-1.5">
-                {gitopsOwner && <ManagedByChip owner={gitopsOwner} status={gitOpsOwnerStatus} verified={gitOpsOwnerVerified} pending={gitOpsOwnerPending} source={gitOpsOwnerSource} onOpen={onOpenGitOpsResource} />}
-                {helmOwner && <HelmManagedByChip owner={helmOwner} source={helmOwnerSource} onOpen={onOpenHelmRelease} />}
+                {showGitOpsChip && <ManagedByChip manager={manager} owner={gitopsOwner} status={gitOpsOwnerStatus} verified={gitOpsOwnerVerified} pending={gitOpsOwnerPending} source={gitOpsOwnerSource} listing={listing} onOpen={onOpenGitOpsResource} />}
+                {helmOwner && <HelmManagedByChip manager={manager} owner={helmOwner} source={helmOwnerSource} onOpen={onOpenHelmRelease} />}
                 {gitOpsResourcePath && onNavigateGitOpsPath && (
                   <OpenInGitOpsChip onClick={() => onNavigateGitOpsPath(gitOpsResourcePath)} />
                 )}
@@ -1109,7 +1133,8 @@ export function WorkloadView({
               <ResourceRendererDispatch
                 resource={selectedResource}
                 data={resource}
-                relationships={relationships}
+                relationships={rendererRelationships}
+                trackedBy={trackedBy}
                 certificateInfo={certificateInfo}
                 hpaDiagnosis={hpaDiagnosis}
                 scalerDiagnostics={scalerDiagnostics}
@@ -1139,10 +1164,35 @@ export function WorkloadView({
   }
 
   // ── Expanded (full) mode ─────────────────────────────────────────────────
+    const nameAndCopy = (
+      <>
+        <h1 className="text-lg font-semibold text-theme-text-primary truncate">{name}</h1>
+        <Tooltip content="Copy name" delay={150}>
+          <button
+            onClick={() => copyToClipboard(name, 'name')}
+            className="p-1 text-theme-text-secondary hover:text-theme-text-primary hover:bg-theme-elevated rounded shrink-0"
+            aria-label="Copy name"
+          >
+            {copied === 'name' ? <Check className="w-3.5 h-3.5 text-green-400" /> : <Copy className="w-3.5 h-3.5" />}
+          </button>
+        </Tooltip>
+      </>
+    )
   return (
     <OperationalIssuesShownContext.Provider value={!!hasOperationalIssues || !!operationalIssuesPending}>
     <DetailShell
       breadcrumb={breadcrumb}
+      compactIdentity={
+        // The namespace stays: Restart and the other actions sit right below.
+        <div className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1">
+          {titlePrefix}
+          <div className="flex min-w-0 max-w-full items-center gap-2">{nameAndCopy}</div>
+          {namespace && namespace !== '_' && (
+            <span className="whitespace-nowrap text-sm text-theme-text-secondary">Namespace: <span className="text-theme-text-primary">{namespace}</span></span>
+          )}
+          {namespace && namespace !== '_' && namespaceNote}
+        </div>
+      }
       wrapHeader={inlineBadges}
       subheader={resourceGone ? undefined : subheader}
       nav={
@@ -1159,20 +1209,6 @@ export function WorkloadView({
         )
       }
       identity={(() => {
-        const nameAndCopy = (
-          <>
-            <h1 className="text-lg font-semibold text-theme-text-primary truncate">{name}</h1>
-            <Tooltip content="Copy name" delay={150}>
-              <button
-                onClick={() => copyToClipboard(name, 'name')}
-                className="p-1 text-theme-text-secondary hover:text-theme-text-primary hover:bg-theme-elevated rounded shrink-0"
-                aria-label="Copy name"
-              >
-                {copied === 'name' ? <Check className="w-3.5 h-3.5 text-green-400" /> : <Copy className="w-3.5 h-3.5" />}
-              </button>
-            </Tooltip>
-          </>
-        )
         const kindAndStatus = (
           <>
             {!hideKindBadge && (
@@ -1185,6 +1221,7 @@ export function WorkloadView({
                 {status.text}
               </span>
             )}
+            {!resourceGone && crossplaneResource && <CrossplanePauseChip state={getCrossplanePauseState(resource)} />}
             {!resourceGone && statusNote}
           </>
         )
@@ -1206,11 +1243,11 @@ export function WorkloadView({
               </span>
             </Tooltip>
           ),
-          gitopsOwner && (
-            <ManagedByChip key="gitops" owner={gitopsOwner} status={gitOpsOwnerStatus} verified={gitOpsOwnerVerified} pending={gitOpsOwnerPending} source={gitOpsOwnerSource} onOpen={onOpenGitOpsResource} variant="block" />
+          showGitOpsChip && (
+            <ManagedByChip key="gitops" manager={manager} owner={gitopsOwner} status={gitOpsOwnerStatus} verified={gitOpsOwnerVerified} pending={gitOpsOwnerPending} source={gitOpsOwnerSource} listing={listing} onOpen={onOpenGitOpsResource} variant="block" />
           ),
           helmOwner && (
-            <HelmManagedByChip key="helm" owner={helmOwner} source={helmOwnerSource} onOpen={onOpenHelmRelease} variant="block" />
+            <HelmManagedByChip key="helm" manager={manager} owner={helmOwner} source={helmOwnerSource} onOpen={onOpenHelmRelease} variant="block" />
           ),
           gitOpsResourcePath && onNavigateGitOpsPath && (
             <OpenInGitOpsChip key="open-gitops" onClick={() => onNavigateGitOpsPath(gitOpsResourcePath)} />
@@ -1322,7 +1359,8 @@ export function WorkloadView({
             <InfoTab
               resource={resource}
               selectedResource={selectedResource}
-              relationships={relationships}
+              relationships={rendererRelationships}
+              trackedBy={trackedBy}
               certificateInfo={certificateInfo}
               hpaDiagnosis={hpaDiagnosis}
               scalerDiagnostics={scalerDiagnostics}
@@ -1383,6 +1421,7 @@ export function WorkloadView({
         )}
         {effectiveTab === 'timeline' && (
           <EventsTab
+            focusEvent={timelineFocusEvent}
             events={resourceEvents}
             isLoading={eventsLoading}
             truncated={historyTruncated}
@@ -1429,10 +1468,12 @@ export function WorkloadView({
           </div>
         )}
         {effectiveTab === 'yaml' && (
-          <div className="flex h-full min-h-0">
+          // Phones put the objects in a scrolling row above the YAML, which
+          // gets the full width.
+          <div className="flex h-full min-h-0 phone:flex-col">
             {renderRelatedYaml && yamlObjects.length > 1 && (
-              <div className="flex w-56 shrink-0 flex-col gap-0.5 overflow-y-auto border-r border-theme-border bg-theme-base px-2 py-2">
-                <div className="px-1.5 pb-1 pt-0.5 text-[10px] font-medium uppercase tracking-wide text-theme-text-tertiary">Objects</div>
+              <div className="flex w-56 shrink-0 flex-col gap-0.5 overflow-y-auto border-r border-theme-border bg-theme-base px-2 py-2 phone:w-full phone:flex-row phone:gap-1 phone:overflow-x-auto phone:overflow-y-hidden phone:border-b phone:border-r-0">
+                <div className="px-1.5 pb-1 pt-0.5 text-[10px] font-medium uppercase tracking-wide text-theme-text-tertiary phone:hidden">Objects</div>
                 {yamlObjects.map((o) => {
                   const active = o.primary ? yamlObjectId === null : yamlObjectId === o.id
                   return (
@@ -1441,7 +1482,7 @@ export function WorkloadView({
                       type="button"
                       onClick={() => setYamlObjectId(o.primary ? null : o.id)}
                       className={clsx(
-                        'flex w-full flex-col rounded-md px-1.5 py-1.5 text-left transition-colors',
+                        'flex w-full flex-col rounded-md px-1.5 py-1.5 text-left transition-colors phone:w-auto phone:max-w-[11rem] phone:shrink-0',
                         active ? 'selection selection-ring' : 'hover:bg-theme-hover',
                       )}
                     >
@@ -1688,6 +1729,7 @@ function OwnershipHeading({
 // ============================================================================
 
 function EventsTab({
+  focusEvent,
   events,
   isLoading,
   truncated,
@@ -1703,6 +1745,7 @@ function EventsTab({
   topology,
   onResourceClick,
 }: {
+  focusEvent?: { id: string }
   events: TimelineEvent[]
   isLoading: boolean
   truncated?: boolean
@@ -1798,6 +1841,22 @@ function EventsTab({
     onSelectEvent(id)
   }, [onSelectEvent])
 
+  const focusedRequest = useRef<typeof focusEvent>(undefined)
+  const requestedPage = useRef<{ focus: typeof focusEvent; events: TimelineEvent[] } | undefined>(undefined)
+  const focusFound = Boolean(focusEvent && cleanEvents.some((event) => event.id === focusEvent.id))
+  useEffect(() => {
+    if (!focusEvent || focusedRequest.current === focusEvent || isLoading) return
+    if (focusFound) {
+      handleSelect(focusEvent.id)
+      focusedRequest.current = focusEvent
+    } else if (truncated && onLoadOlder && !loadingOlder && !olderError && !error) {
+      // Strict Mode can replay this effect before the loading prop updates.
+      if (requestedPage.current?.focus === focusEvent && requestedPage.current.events === events) return
+      requestedPage.current = { focus: focusEvent, events }
+      onLoadOlder()
+    }
+  }, [focusEvent, focusFound, events, isLoading, truncated, onLoadOlder, loadingOlder, olderError, error, handleSelect])
+
   if (isLoading) {
     return (
       <div className="flex items-center justify-center h-full text-theme-text-tertiary">
@@ -1827,6 +1886,15 @@ function EventsTab({
 
   return (
     <div className="h-full flex flex-col overflow-hidden">
+      {focusEvent && !focusFound && (
+        <div className="shrink-0 border-b border-theme-border px-4 py-2 text-xs text-theme-text-secondary" role="status">
+          {olderError || error
+            ? "Couldn't find the reported error because some history couldn't be loaded."
+            : truncated && onLoadOlder
+              ? 'Finding the reported error in older history…'
+              : 'The reported error is not available in the retained timeline history.'}
+        </div>
+      )}
       {error && (
         <div className="shrink-0 flex flex-wrap items-center gap-x-2 border-b border-theme-border bg-theme-base px-4 py-1.5 text-xs" role="alert">
           <span className="text-[var(--color-error)]" title={error.message}>
@@ -1932,6 +2000,7 @@ function InfoTab({
   resource,
   selectedResource,
   relationships,
+  trackedBy,
   certificateInfo,
   hpaDiagnosis,
   scalerDiagnostics,
@@ -1968,6 +2037,7 @@ function InfoTab({
   resource: any
   selectedResource: SelectedResource
   relationships?: Relationships
+  trackedBy?: string
   certificateInfo?: any
   hpaDiagnosis?: HPADiagnosis
   scalerDiagnostics?: ScalerDiagnosis[]
@@ -2022,6 +2092,7 @@ function InfoTab({
           resource={selectedResource}
           data={resource}
           relationships={relationships}
+          trackedBy={trackedBy}
           certificateInfo={certificateInfo}
           hpaDiagnosis={hpaDiagnosis}
           scalerDiagnostics={scalerDiagnostics}
@@ -2252,7 +2323,7 @@ function WorkloadOverviewTab({
 
           <div className="grid items-start gap-4 xl:grid-cols-[minmax(0,1fr)_360px] 2xl:grid-cols-[minmax(0,1fr)_400px]">
             <div className="space-y-4">
-              <div className="grid items-start gap-4 2xl:grid-cols-[minmax(0,1fr)_minmax(320px,420px)]">
+              <div className="grid items-start gap-4 phone:grid-cols-[minmax(0,1fr)] 2xl:grid-cols-[minmax(0,1fr)_minmax(320px,420px)]">
                 <div className="space-y-4">
                   {showServingPath && (
                     <ServingConfigurationCard
@@ -2345,7 +2416,7 @@ function WorkloadOverviewTab({
         <div className="grid items-start gap-4 xl:grid-cols-[minmax(0,1fr)_360px] 2xl:grid-cols-[minmax(0,1fr)_400px]">
           <div className="space-y-4">
             <CurrentStateCard resource={resource} apiKind={apiKind} readiness={readiness} />
-            <div className="grid items-start gap-4 2xl:grid-cols-2">
+            <div className="grid items-start gap-4 phone:grid-cols-[minmax(0,1fr)] 2xl:grid-cols-2">
               {overviewShape === 'cronjob' ? (
                 <CronJobRunsCard
                   resource={resource}
@@ -2385,7 +2456,7 @@ function WorkloadOverviewTab({
               />
             ) : null}
             {extraContent && (
-              <div className="grid items-start gap-4 2xl:grid-cols-2">
+              <div className="grid items-start gap-4 phone:grid-cols-[minmax(0,1fr)] 2xl:grid-cols-2">
                 {extraContent}
               </div>
             )}

package/src/hooks/index.ts

@@ -1,6 +1,8 @@
 export { useAnimatedUnmount } from './useAnimatedUnmount'
 export { useDebouncedValue } from './useDebouncedValue'
 export { useRefreshAnimation } from './useRefreshAnimation'
+export { useMediaQuery } from './useMediaQuery'
+export { usePhoneLayout, PHONE_MEDIA_QUERY } from './usePhoneLayout'
 export {
   KeyboardShortcutProvider,
   useRegisterShortcut,

package/src/hooks/useKeepInViewport.mounted.test.tsx

@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+//
+// The hook must leave a caller's own width constraints alone unless the menu
+// can't fit, and put them back exactly once it fits again.
+import { act, useRef } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, expect, it } from 'vitest'
+import { useKeepInViewport } from './useKeepInViewport'
+
+let root: Root | undefined
+let host: HTMLDivElement | undefined
+afterEach(() => {
+  act(() => root?.unmount())
+  host?.remove()
+})
+
+function Menu({ tick }: { tick: number }) {
+  const ref = useRef<HTMLDivElement>(null)
+  useKeepInViewport(ref, true)
+  return <div ref={ref} data-tick={tick} style={{ minWidth: 240 }} />
+}
+
+function setMenuWidth(el: HTMLElement, width: number) {
+  Object.defineProperty(el, 'offsetWidth', { configurable: true, value: width })
+  el.getBoundingClientRect = () => ({ left: 0, right: width, top: 0, bottom: 0, width, height: 0, x: 0, y: 0, toJSON: () => ({}) })
+}
+
+function render(tick: number) {
+  act(() => root!.render(<Menu tick={tick} />))
+  return host!.querySelector('div')!
+}
+
+it('keeps the caller min-width when the menu fits, and restores it after a squeeze', () => {
+  Object.defineProperty(document.documentElement, 'clientWidth', { configurable: true, value: 1024 })
+  host = document.createElement('div')
+  document.body.appendChild(host)
+  root = createRoot(host)
+  let el = render(1)
+  setMenuWidth(el, 260)
+  el = render(2)
+  expect(el.style.minWidth).toBe('240px')
+  expect(el.style.maxWidth).toBe('')
+
+  Object.defineProperty(document.documentElement, 'clientWidth', { configurable: true, value: 200 })
+  el = render(3)
+  expect(el.style.minWidth).toBe('0px')
+  expect(el.style.maxWidth).toBe('184px')
+
+  Object.defineProperty(document.documentElement, 'clientWidth', { configurable: true, value: 1024 })
+  el = render(4)
+  expect(el.style.minWidth).toBe('240px')
+  expect(el.style.maxWidth).toBe('')
+})
+
+it('measures with transitions off and restores the caller transition', () => {
+  Object.defineProperty(document.documentElement, 'clientWidth', { configurable: true, value: 1024 })
+  host = document.createElement('div')
+  document.body.appendChild(host)
+  root = createRoot(host)
+  let el = render(1)
+  el.style.transition = 'opacity 100ms'
+  const seen: string[] = []
+  el.getBoundingClientRect = () => {
+    seen.push(el.style.transition)
+    return { left: 410, right: 650, top: 0, bottom: 0, width: 240, height: 0, x: 410, y: 0, toJSON: () => ({}) }
+  }
+  el = render(2)
+  expect(seen.length).toBeGreaterThan(0)
+  expect(seen.every((t) => t === 'none')).toBe(true)
+  expect(el.style.transition).toBe('opacity 100ms')
+  expect(el.style.translate).toBe('')
+})

package/src/hooks/useKeepInViewport.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { keepInViewportShift } from './useKeepInViewport'
+
+describe('keepInViewportShift', () => {
+  it('leaves a menu that fits alone', () => {
+    expect(keepInViewportShift(56, 336, 8, 1272)).toBe(0)
+  })
+
+  it('pulls a menu past the right edge back inside', () => {
+    // A 280px menu opened at x=56 on a 320px phone.
+    expect(keepInViewportShift(56, 336, 8, 312)).toBe(-24)
+  })
+
+  it('stops at a clipping ancestor, not the viewport edge', () => {
+    // Content column starts after a 56px rail: the left bound is 64, not 8,
+    // so a menu sitting under the rail moves out from behind it.
+    expect(keepInViewportShift(40, 240, 64, 312)).toBe(24)
+  })
+
+  it('keeps the left edge when the menu is wider than the bounds', () => {
+    expect(keepInViewportShift(20, 420, 8, 312)).toBe(-12)
+  })
+
+  it('pushes a menu past the left edge back in', () => {
+    expect(keepInViewportShift(-30, 200, 8, 382)).toBe(38)
+  })
+})

package/src/hooks/useKeepInViewport.ts

@@ -0,0 +1,87 @@
+import { useLayoutEffect, useEffect, type RefObject } from 'react'
+
+/** Keeps an open menu or popover horizontally inside the visible area: the
+ *  viewport, narrowed by any ancestor that clips horizontally (a content
+ *  column beside a nav rail clips what slides under the rail). Anchored menus
+ *  open at their trigger's edge with a fixed minimum width, so on a narrow
+ *  screen a trigger near the edge pushes the menu out of view. After each
+ *  layout, and on resize while open, this shifts the element back with the
+ *  `translate` property (which moves it whichever side it's anchored to), and
+ *  narrows it only if it can't fit. Don't use it on an element whose own
+ *  motion animates `translate`: the inline value would override it.
+ *
+ *  Runs after every render while `active`, so a menu whose content changes
+ *  width (a filter narrowing a list) is re-measured. */
+export function useKeepInViewport(ref: RefObject<HTMLElement | null>, active: boolean, margin = 8): void {
+  useLayoutEffect(() => {
+    if (active) keepInView(ref.current, margin)
+  })
+  useEffect(() => {
+    if (!active) return
+    const onResize = () => keepInView(ref.current, margin)
+    window.addEventListener('resize', onResize)
+    return () => window.removeEventListener('resize', onResize)
+  }, [ref, active, margin])
+}
+
+// Width overrides this hook applied, keyed by element, with the inline values
+// they replaced, so a later measurement can put back exactly what the caller set
+// (React won't re-apply an inline style whose value it thinks is unchanged).
+const sizedBy = new WeakMap<HTMLElement, { minWidth: string; maxWidth: string }>()
+
+function keepInView(el: HTMLElement | null, margin: number): void {
+  if (!el) return
+  // Measure and move with transitions off. Under reduced motion every
+  // element gets a near-zero transition on all properties, and a transitioned
+  // element reports its pre-change box in the same frame: a menu just moved
+  // from left 0 to its trigger still measured at 0, and was pushed off its
+  // trigger by the margin.
+  const transition = el.style.transition
+  el.style.transition = 'none'
+  place(el, margin)
+  el.getBoundingClientRect() // apply the move before transitions return
+  el.style.transition = transition
+}
+
+function place(el: HTMLElement, margin: number): void {
+  el.style.translate = ''
+  const saved = sizedBy.get(el)
+  if (saved) {
+    el.style.minWidth = saved.minWidth
+    el.style.maxWidth = saved.maxWidth
+    sizedBy.delete(el)
+  }
+  const [boundLeft, boundRight] = visibleBounds(el, margin)
+  const room = boundRight - boundLeft
+  // Only a menu that can't fit gets resized; otherwise the caller's own
+  // minimum and maximum widths stand.
+  if (el.offsetWidth > room) {
+    sizedBy.set(el, { minWidth: el.style.minWidth, maxWidth: el.style.maxWidth })
+    el.style.minWidth = '0'
+    el.style.maxWidth = `${room}px`
+  }
+  const { left, right } = el.getBoundingClientRect()
+  const shift = keepInViewportShift(left, right, boundLeft, boundRight)
+  if (shift !== 0) el.style.translate = `${shift}px 0`
+}
+
+function visibleBounds(el: HTMLElement, margin: number): [number, number] {
+  let left = margin
+  let right = document.documentElement.clientWidth - margin
+  for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+    if (getComputedStyle(p).overflowX === 'visible') continue
+    const r = p.getBoundingClientRect()
+    left = Math.max(left, r.left + margin)
+    right = Math.min(right, r.right - margin)
+  }
+  return [left, Math.max(left, right)]
+}
+
+/** Horizontal shift (px) that brings [left, right] inside [boundLeft,
+ *  boundRight], preferring the left edge when the element is wider. */
+export function keepInViewportShift(left: number, right: number, boundLeft: number, boundRight: number): number {
+  let shift = 0
+  if (right > boundRight) shift = boundRight - right
+  if (left + shift < boundLeft) shift = boundLeft - left
+  return shift
+}

package/src/hooks/useMediaQuery.ts

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react'
+
+// Subscribe to a CSS media query. SSR-safe (returns false before mount) and
+// updates on viewport changes.
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return false
+    return window.matchMedia(query).matches
+  })
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return
+    const mql = window.matchMedia(query)
+    const onChange = () => setMatches(mql.matches)
+    onChange()
+    mql.addEventListener('change', onChange)
+    return () => mql.removeEventListener('change', onChange)
+  }, [query])
+
+  return matches
+}

package/src/hooks/usePhoneLayout.ts

@@ -0,0 +1,12 @@
+import { useMediaQuery } from './useMediaQuery'
+
+// A phone: a narrow screen whose primary pointer is touch. A desktop browser
+// narrowed below this width keeps the desktop layout (and its content floor),
+// since a wider window can show the full UI; browser dev-tools device mode
+// emulates touch and gets the phone layout. Keep in sync with the `phone:`
+// variant in theme/tailwind-theme.css.
+export const PHONE_MEDIA_QUERY = '(max-width: 639px) and (pointer: coarse)'
+
+export function usePhoneLayout(): boolean {
+  return useMediaQuery(PHONE_MEDIA_QUERY)
+}

package/src/theme/tailwind-theme.css

@@ -6,6 +6,11 @@
  * Import after variables.css.
  */
 
+/* `phone:` styles apply on a narrow touch-first screen only (see
+ * PHONE_MEDIA_QUERY in hooks/usePhoneLayout.ts). A narrowed desktop window
+ * keeps the desktop layout. */
+@custom-variant phone (@media (max-width: 639px) and (pointer: coarse));
+
 @theme inline {
   /* Backgrounds */
   --color-theme-sidebar: var(--bg-sidebar);