@skyhook-io/k8s-ui 1.7.14 → 1.8.0

package/src/components/resources/resource-utils-hpa.ts

@@ -0,0 +1,106 @@
+import type { HealthLevel, StatusBadge } from './resource-utils'
+import type { HPADiagnosisState } from '../../types'
+
+export function getHPATableState(hpa: any): HPADiagnosisState {
+  // List rows only classify states worth scanning in a table; the Go diagnosis powers the full drawer context.
+  const conditions = Array.isArray(hpa?.status?.conditions) ? hpa.status.conditions : []
+  const current = hpa?.status?.currentReplicas ?? 0
+  const desired = hpa?.status?.desiredReplicas ?? 0
+  const min = hpa?.spec?.minReplicas ?? 1
+  const max = hpa?.spec?.maxReplicas ?? 0
+
+  if (conditionStatus(conditions, 'AbleToScale') === 'False') return 'unable_to_scale'
+  const scalingActive = condition(conditions, 'ScalingActive')
+  if (scalingActive?.status === 'False') {
+    if (isScalingDisabled(scalingActive)) return 'disabled'
+    return 'metrics_unavailable'
+  }
+  if (max > 0 && min === max && current === desired && desired === max) return 'pinned'
+  if (isMaxLimited(condition(conditions, 'ScalingLimited'))) return 'limited_max'
+
+  if (current < desired) return 'scaling_up'
+  if (current > desired) return 'scaling_down'
+  return 'ok'
+}
+
+export function hpaStateLabel(state: HPADiagnosisState): string {
+  switch (state) {
+    case 'unable_to_scale':
+      return 'Unable to scale'
+    case 'metrics_unavailable':
+      return 'Metrics unavailable'
+    case 'metrics_incomplete':
+      return 'Metrics incomplete'
+    case 'disabled':
+      return 'Disabled'
+    case 'pinned':
+      return 'Pinned'
+    case 'limited_max':
+      return 'Maxed'
+    case 'limited_min':
+      return 'At min'
+    case 'stale':
+      return 'Stale'
+    case 'stabilized':
+      return 'Stabilized'
+    case 'scaling_up':
+      return 'Scaling Up'
+    case 'scaling_down':
+      return 'Scaling Down'
+    case 'ok':
+      return 'Stable'
+    default:
+      return 'Unknown'
+  }
+}
+
+export function hpaStateLevel(state: HPADiagnosisState): HealthLevel {
+  switch (state) {
+    case 'unable_to_scale':
+    case 'metrics_unavailable':
+      return 'unhealthy'
+    case 'limited_max':
+    case 'metrics_incomplete':
+      return 'degraded'
+    case 'scaling_up':
+    case 'scaling_down':
+      return 'degraded'
+    case 'limited_min':
+    case 'disabled':
+    case 'pinned':
+    case 'stabilized':
+      return 'neutral'
+    case 'stale':
+      return 'unknown'
+    case 'ok':
+      return 'healthy'
+    default:
+      return 'unknown'
+  }
+}
+
+export function hpaStatusFromState(state: HPADiagnosisState, healthColors: Record<HealthLevel, string>): StatusBadge {
+  const level = hpaStateLevel(state)
+  return { text: hpaStateLabel(state), color: healthColors[level], level }
+}
+
+function conditionStatus(conditions: any[], type: string): string | undefined {
+  return condition(conditions, type)?.status
+}
+
+function condition(conditions: any[], type: string): any | undefined {
+  return conditions.find((item) => item?.type === type)
+}
+
+function isScalingDisabled(item: any): boolean {
+  const reason = String(item?.reason ?? '').toLowerCase()
+  const message = String(item?.message ?? '').toLowerCase()
+  return reason === 'scalingdisabled' || message.includes('scaling is disabled')
+}
+
+function isMaxLimited(item: any): boolean {
+  if (item?.status !== 'True') return false
+  const reason = String(item?.reason ?? '').toLowerCase()
+  const message = String(item?.message ?? '').toLowerCase()
+  return reason.includes('toomany') || message.includes('maximum')
+}

package/src/components/resources/resource-utils.ts

@@ -14,6 +14,7 @@ import { getResourceClaimStatus as _getResourceClaimStatus, getResourceClaimDevi
 import { getNvidiaClusterPolicyStatus as _getNvidiaClusterPolicyStatus, getNvidiaClusterPolicyEnabledComponents as _getNvidiaClusterPolicyEnabledComponents, getNvidiaDriverStatus as _getNvidiaDriverStatus } from './resource-utils-nvidia'
 import { getBackupStatus as _getBackupStatus, getRestoreStatus as _getRestoreStatus, getScheduleStatus as _getScheduleStatus, getBSLStatus as _getBSLStatus } from './resource-utils-velero'
 import { getExternalSecretStatus as _getExternalSecretStatus, getClusterExternalSecretStatus as _getClusterExternalSecretStatus, getSecretStoreStatus as _getSecretStoreStatus, getClusterSecretStoreStatus as _getClusterSecretStoreStatus, getSecretStoreProviderType as _getSecretStoreProviderType } from './resource-utils-eso'
+import { getHPATableState, hpaStatusFromState } from './resource-utils-hpa'
 
 // ============================================================================
 // STATUS & HEALTH UTILITIES
@@ -267,26 +268,39 @@ export function getPodProblems(pod: any): PodProblem[] {
   const initContainerStatuses = pod.status?.initContainerStatuses || []
   const conditions = pod.status?.conditions || []
   const phase = pod.status?.phase
+  const podStatusMessage = pod.status?.message || undefined
+  const hasPodIP = Boolean(pod.status?.podIP || pod.status?.podIPs?.some((ip: any) => ip?.ip))
+  const hasScheduledNode = Boolean(pod.spec?.nodeName)
+  const hasUnschedulableCondition = conditions.some((cond: any) => cond.type === 'PodScheduled' && cond.status === 'False')
+  const hasContainerCreating = containerStatuses.some((cs: any) => cs.state?.waiting?.reason === 'ContainerCreating')
+  const createdAtMs = pod.metadata?.creationTimestamp ? new Date(pod.metadata.creationTimestamp).getTime() : NaN
+  const podAgeMs = Number.isFinite(createdAtMs) ? Date.now() - createdAtMs : 0
+  const sandboxStartupStallAgeMs = 10 * 60 * 1000
+  const sandboxStartupStallCriticalAgeMs = 30 * 60 * 1000
+  const inferredSandboxStartupStall = phase === 'Pending' && hasScheduledNode && !hasUnschedulableCondition && hasContainerCreating && !hasPodIP && podAgeMs > sandboxStartupStallAgeMs
+  const inferredSandboxStartupStallSeverity: PodProblem['severity'] = podAgeMs >= sandboxStartupStallCriticalAgeMs ? 'critical' : 'high'
+  let hasSandboxStartupStallProblem = false
 
   // Failed or Unknown phase
   if (phase === 'Failed' && pod.status?.reason !== 'Evicted') {
-    problems.push({ severity: 'critical', message: 'Failed' })
+    problems.push({ severity: 'critical', message: 'Failed', detail: podStatusMessage })
   } else if (phase === 'Unknown') {
-    problems.push({ severity: 'high', message: 'Unknown' })
+    problems.push({ severity: 'high', message: 'Unknown', detail: podStatusMessage })
   }
 
   // Init container failures
   for (const cs of initContainerStatuses) {
     if (cs.state?.waiting?.reason && cs.state.waiting.reason !== 'PodInitializing') {
       const reason = cs.state.waiting.reason
+      const detail = cs.state.waiting.message || undefined
       if (['CrashLoopBackOff', 'ImagePullBackOff', 'ErrImagePull'].includes(reason)) {
-        problems.push({ severity: 'critical', message: `Init: ${reason}` })
+        problems.push({ severity: 'critical', message: `Init: ${reason}`, detail })
       } else {
-        problems.push({ severity: 'high', message: `Init: ${reason}` })
+        problems.push({ severity: 'high', message: `Init: ${reason}`, detail })
       }
     }
     if (cs.state?.terminated?.exitCode && cs.state.terminated.exitCode !== 0) {
-      problems.push({ severity: 'high', message: `Init: Exit Code ${cs.state.terminated.exitCode}` })
+      problems.push({ severity: 'high', message: `Init: Exit Code ${cs.state.terminated.exitCode}`, detail: cs.state.terminated.message || undefined })
     }
   }
 
@@ -294,30 +308,32 @@ export function getPodProblems(pod: any): PodProblem[] {
     // Check waiting state
     if (cs.state?.waiting?.reason) {
       const reason = cs.state.waiting.reason
+      const detail = cs.state.waiting.message || undefined
       if (['CrashLoopBackOff', 'ImagePullBackOff', 'ErrImagePull'].includes(reason)) {
-        problems.push({ severity: 'critical', message: reason })
+        problems.push({ severity: 'critical', message: reason, detail })
       } else if (reason === 'CreateContainerConfigError') {
-        problems.push({ severity: 'critical', message: 'Config Error' })
+        problems.push({ severity: 'critical', message: 'Config Error', detail })
       } else if (reason === 'ContainerCannotRun') {
-        problems.push({ severity: 'critical', message: 'Cannot Run' })
+        problems.push({ severity: 'critical', message: 'Cannot Run', detail })
       } else if (reason !== 'ContainerCreating' && reason !== 'PodInitializing') {
-        problems.push({ severity: 'high', message: reason })
+        problems.push({ severity: 'high', message: reason, detail })
       }
     }
     // Check terminated state
     if (cs.state?.terminated?.reason === 'OOMKilled') {
-      problems.push({ severity: 'critical', message: 'OOMKilled' })
+      problems.push({ severity: 'critical', message: 'OOMKilled', detail: cs.state.terminated.message || undefined })
     } else if (cs.state?.terminated?.exitCode && cs.state.terminated.exitCode !== 0) {
-      problems.push({ severity: 'high', message: `Exit Code ${cs.state.terminated.exitCode}` })
+      problems.push({ severity: 'high', message: `Exit Code ${cs.state.terminated.exitCode}`, detail: cs.state.terminated.message || undefined })
     }
     // High restart count
     if (cs.restartCount > 5) {
       problems.push({ severity: 'medium', message: `${cs.restartCount} restarts` })
     }
     // Volume mount issues from last state
-    const lastMsg = cs.lastState?.terminated?.message?.toLowerCase() || ''
+    const lastMsgRaw = cs.lastState?.terminated?.message || ''
+    const lastMsg = lastMsgRaw.toLowerCase()
     if (lastMsg.includes('failed to mount') || lastMsg.includes('failedattachvolume')) {
-      problems.push({ severity: 'high', message: 'Volume Mount Failed' })
+      problems.push({ severity: 'high', message: 'Volume Mount Failed', detail: lastMsgRaw || undefined })
     }
   }
 
@@ -332,23 +348,29 @@ export function getPodProblems(pod: any): PodProblem[] {
     if (cond.type === 'ContainersReady' && cond.status === 'False') {
       const msg = (cond.message || '').toLowerCase()
       if (msg.includes('readiness')) {
-        problems.push({ severity: 'medium', message: 'Readiness Probe Failing' })
+        problems.push({ severity: 'medium', message: 'Readiness Probe Failing', detail: cond.message || undefined })
       } else if (msg.includes('liveness')) {
-        problems.push({ severity: 'high', message: 'Liveness Probe Failing' })
+        problems.push({ severity: 'high', message: 'Liveness Probe Failing', detail: cond.message || undefined })
       }
     }
     // IP allocation failures (subnet exhaustion)
     if (cond.type === 'PodReadyToStartContainers' && cond.status === 'False') {
       const msg = (cond.message || '').toLowerCase()
-      if (msg.includes('failed to assign an ip') || msg.includes('pod sandbox')) {
-        problems.push({ severity: 'critical', message: 'IP Allocation Failed' })
+      if (msg.includes('failed to assign an ip')) {
+        problems.push({ severity: 'critical', message: 'IP Allocation Failed', detail: cond.message || undefined })
+      } else if (msg.includes('pod sandbox')) {
+        problems.push({ severity: 'critical', message: 'Sandbox Startup Stalled', detail: cond.message || undefined })
+        hasSandboxStartupStallProblem = true
       }
     }
   }
+  if (inferredSandboxStartupStall && !hasSandboxStartupStallProblem) {
+    problems.push({ severity: inferredSandboxStartupStallSeverity, message: 'Sandbox Startup Stalled' })
+  }
 
   // Evicted pods
   if (phase === 'Failed' && pod.status?.reason === 'Evicted') {
-    problems.push({ severity: 'high', message: 'Evicted' })
+    problems.push({ severity: 'high', message: 'Evicted', detail: podStatusMessage })
   }
 
   // Stuck terminating (zombie pod)
@@ -939,16 +961,7 @@ export function getCronJobLastRun(cj: any): string | null {
 // ============================================================================
 
 export function getHPAStatus(hpa: any): StatusBadge {
-  const current = hpa.status?.currentReplicas || 0
-  const desired = hpa.status?.desiredReplicas || 0
-
-  if (current === desired) {
-    return { text: 'Stable', color: healthColors.healthy, level: 'healthy' }
-  }
-  if (current < desired) {
-    return { text: 'Scaling Up', color: healthColors.degraded, level: 'degraded' }
-  }
-  return { text: 'Scaling Down', color: healthColors.degraded, level: 'degraded' }
+  return hpaStatusFromState(getHPATableState(hpa), healthColors)
 }
 
 export function getHPAReplicas(hpa: any): { current: number; min: number; max: number } {

package/src/components/shared/ResourceRendererDispatch.tsx

@@ -226,10 +226,11 @@ import {
   isComposite,
   isClaim,
 } from '../resources/resource-utils-crossplane'
-import type { SelectedResource, Relationships, ResourceRef, SecretCertificateInfo, ResolvedEnvFrom, TimelineEvent } from '../../types'
+import type { SelectedResource, Relationships, ResourceRef, SecretCertificateInfo, ResolvedEnvFrom, TimelineEvent, HPADiagnosis } from '../../types'
 import type { CopyHandler } from '../ui/drawer-components'
 import { AlertBanner } from '../ui/drawer-components'
 import { replicaScalers } from '../../utils/replica-scalers'
+import type { ScalerDiagnosis } from '../resources/renderers/WorkloadRenderer'
 
 /**
  * Override map letting each platform consumer swap in its own renderer components.
@@ -258,6 +259,7 @@ export interface RendererOverrides {
     onNavigate?: (ref: ResourceRef) => void
     relationships?: Relationships
     scaleBlockedBy?: ResourceRef[]
+    scalerDiagnostics?: ScalerDiagnosis[]
   }>
   // Optional override for Crossplane Composite / Claim — host wraps the
   // package renderer to fan out per-composed-ref status fetches via React Query.
@@ -297,6 +299,7 @@ export interface RendererOverrides {
   HPARenderer?: React.ComponentType<{
     data: any
     onNavigate?: (ref: ResourceRef) => void
+    hpaDiagnosis?: HPADiagnosis
   }>
   // PVC: host wraps the base renderer to add a kubelet-derived usage gauge
   // when Prometheus is scraping kubelet endpoints.
@@ -376,6 +379,8 @@ interface ResourceRendererDispatchProps {
   data: any
   relationships?: Relationships
   certificateInfo?: SecretCertificateInfo
+  hpaDiagnosis?: HPADiagnosis
+  scalerDiagnostics?: ScalerDiagnosis[]
   onCopy: (text: string, key: string) => void
   copied: string | null
   onNavigate?: (ref: ResourceRef) => void
@@ -417,6 +422,8 @@ export function ResourceRendererDispatch({
   data,
   relationships,
   certificateInfo,
+  hpaDiagnosis,
+  scalerDiagnostics,
   onCopy,
   copied,
   onNavigate,
@@ -503,6 +510,7 @@ export function ResourceRendererDispatch({
             onNavigate={onNavigate}
             relationships={relationships}
             scaleBlockedBy={scaleBlockedBy}
+            scalerDiagnostics={scalerDiagnostics}
           />
         )}
         {kind === 'replicasets' && <ReplicaSetRenderer data={data} />}
@@ -513,7 +521,7 @@ export function ResourceRendererDispatch({
         {kind === 'secrets' && <SecretRenderer data={data} certificateInfo={certificateInfo} resourceData={data} onSaveSecretValue={onSaveSecretValue} isSaving={isSavingSecret} />}
         {kind === 'jobs' && <JobRenderer data={data} />}
         {kind === 'cronjobs' && <CronJobRenderer data={data} onNavigate={onNavigate} />}
-        {(kind === 'hpas' || kind === 'horizontalpodautoscalers') && <HPAComp data={data} onNavigate={onNavigate} />}
+        {(kind === 'hpas' || kind === 'horizontalpodautoscalers') && <HPAComp data={data} onNavigate={onNavigate} hpaDiagnosis={hpaDiagnosis} />}
         {kind === 'nodes' && <NodeComp data={data} relationships={relationships} />}
         {kind === 'persistentvolumeclaims' && <PVCComp data={data} onNavigate={onNavigate} />}
         {kind === 'rollouts' && <RolloutRenderer data={data} />}

package/src/components/ui/DistributionBar.tsx

@@ -0,0 +1,88 @@
+import { clsx } from 'clsx'
+
+export interface DistributionSegment {
+  key: string
+  count: number
+  /** Tailwind background class for this segment's fill (e.g. status-tone bg). */
+  fillClass: string
+}
+
+// A single segmented proportion bar — the shared "distribution of statuses"
+// element behind the Checks severity rollup, the Applications/GitOps health
+// rollup, and the Issues rollup. One height, one track, one radius everywhere.
+//
+// Intentional empty state: with no data (sum === 0) it renders NOTHING rather
+// than a flat grey track that reads as a skeleton/loading bar on sparse clusters.
+export function DistributionBar({
+  segments,
+  className,
+  ariaLabel = 'Distribution',
+}: {
+  segments: DistributionSegment[]
+  className?: string
+  ariaLabel?: string
+}) {
+  const sum = segments.reduce((n, s) => n + s.count, 0)
+  if (sum === 0) return null
+  return (
+    <div
+      className={clsx('flex h-1.5 overflow-hidden rounded-full bg-theme-elevated', className)}
+      role="img"
+      aria-label={ariaLabel}
+    >
+      {segments.map((s) =>
+        s.count > 0 ? (
+          <div
+            key={s.key}
+            className={clsx(s.fillClass, 'transition-[width] duration-500 ease-out')}
+            style={{ width: `${(s.count / sum) * 100}%` }}
+          />
+        ) : null,
+      )}
+    </div>
+  )
+}
+
+// A legend entry for a DistributionBar: a tone dot + count + label. When onClick
+// is provided it's a toggle (the legend doubles as the filter, as in the Checks
+// and Issues queues); without it, it's a static legend item.
+export function DistributionLegendChip({
+  label,
+  count,
+  fillClass,
+  textClass,
+  active = false,
+  onClick,
+}: {
+  label: string
+  count: number
+  fillClass: string
+  /** Tone text class applied to the count when count > 0. */
+  textClass?: string
+  active?: boolean
+  onClick?: () => void
+}) {
+  const inner = (
+    <>
+      <span className={clsx('h-2 w-2 rounded-full', fillClass, count === 0 && 'opacity-30')} />
+      <span className={clsx('font-semibold tabular-nums', count > 0 ? textClass : 'text-theme-text-tertiary')}>{count}</span>
+      <span>{label}</span>
+    </>
+  )
+  if (!onClick) {
+    return <span className="inline-flex items-center gap-1.5 px-2.5 py-1 text-xs text-theme-text-secondary">{inner}</span>
+  }
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      className={clsx(
+        'group inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 text-xs transition-colors',
+        active ? 'border-theme-border bg-theme-elevated text-theme-text-primary' : 'border-transparent text-theme-text-secondary hover:bg-theme-hover/60',
+      )}
+    >
+      {inner}
+    </button>
+  )
+}

package/src/components/ui/Facet.tsx

@@ -0,0 +1,130 @@
+import type { ComponentType, ReactNode } from 'react'
+import { clsx } from 'clsx'
+import { Info } from 'lucide-react'
+import { Tooltip } from './Tooltip'
+
+// Shared faceted-filter primitives for sidebar filter rails. One implementation
+// behind the GitOps and Applications rails so the "this filter is on" language
+// stays identical everywhere — active = the skyhook accent, the same signal the
+// nav rail and header status tiles use.
+
+export type FacetTone = 'neutral' | 'success' | 'warning' | 'error' | 'info'
+
+const DOT_CLASS: Record<FacetTone, string> = {
+  neutral: 'bg-theme-text-tertiary',
+  success: 'bg-emerald-500',
+  warning: 'bg-amber-500',
+  error: 'bg-red-500',
+  info: 'bg-sky-500',
+}
+
+// A titled group in a filter rail: optional leading icon, optional info tooltip,
+// and a bottom divider so stacked sections read as distinct facets.
+export function FacetSection({
+  icon: Icon,
+  title,
+  info,
+  children,
+}: {
+  icon?: ComponentType<{ className?: string }>
+  title: string
+  info?: ReactNode
+  children: ReactNode
+}) {
+  return (
+    <section className="border-b border-theme-border px-3 py-2">
+      <div className="mb-1.5 flex items-center gap-1.5">
+        {Icon && <Icon className="h-3.5 w-3.5 text-theme-text-tertiary" />}
+        <span className="text-[10px] font-semibold uppercase tracking-wide text-theme-text-tertiary">{title}</span>
+        {info && (
+          <Tooltip content={info} delay={150} position="right">
+            <Info className="h-3 w-3 cursor-default text-theme-text-tertiary/70 hover:text-theme-text-secondary" aria-label={`About ${title}`} />
+          </Tooltip>
+        )}
+      </div>
+      <div className="space-y-0.5">{children}</div>
+    </section>
+  )
+}
+
+// A single multi-select filter toggle: leading status dot (tone-colored), label,
+// trailing count. Active uses the skyhook accent.
+export function FacetButton({
+  label,
+  count,
+  active,
+  tone = 'neutral',
+  tooltip,
+  onClick,
+}: {
+  label: string
+  count?: number
+  active: boolean
+  tone?: FacetTone
+  tooltip?: ReactNode
+  onClick: () => void
+}) {
+  const btn = (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={active}
+      className={clsx(
+        'flex w-full items-center gap-2 rounded px-2 py-1 text-left text-[11px] transition-colors',
+        active
+          ? 'bg-skyhook-500/15 text-skyhook-700 dark:text-skyhook-300'
+          : 'text-theme-text-secondary hover:bg-theme-hover hover:text-theme-text-primary',
+      )}
+    >
+      <span className={clsx('h-2 w-2 shrink-0 rounded-full', DOT_CLASS[tone])} />
+      <span className="min-w-0 flex-1 truncate font-medium">{label}</span>
+      {count != null && count > 0 && <span className="tabular-nums text-theme-text-tertiary">{count}</span>}
+    </button>
+  )
+  return tooltip ? (
+    <Tooltip content={tooltip} delay={300} position="right" wrapperClassName="w-full">
+      {btn}
+    </Tooltip>
+  ) : (
+    btn
+  )
+}
+
+// Convenience wrapper: a FacetSection of multi-select FacetButtons driven by a
+// Set. Auto-hides zero-count options (quieter than a hard slice cap) unless
+// hideZero is turned off.
+export function Facet<T extends string>({
+  title,
+  icon,
+  info,
+  options,
+  selected,
+  onToggle,
+  hideZero = true,
+}: {
+  title: string
+  icon?: ComponentType<{ className?: string }>
+  info?: ReactNode
+  options: { value: T; label: string; count: number; tone?: FacetTone; tooltip?: ReactNode }[]
+  selected: Set<T>
+  onToggle: (v: T) => void
+  hideZero?: boolean
+}) {
+  const visible = hideZero ? options.filter((o) => o.count > 0) : options
+  if (visible.length === 0) return null
+  return (
+    <FacetSection icon={icon} title={title} info={info}>
+      {visible.map((o) => (
+        <FacetButton
+          key={o.value}
+          label={o.label}
+          count={o.count}
+          active={selected.has(o.value)}
+          tone={o.tone}
+          tooltip={o.tooltip}
+          onClick={() => onToggle(o.value)}
+        />
+      ))}
+    </FacetSection>
+  )
+}

package/src/components/ui/PageHeader.tsx

@@ -0,0 +1,43 @@
+import type { ComponentType, ReactNode } from 'react'
+import { ArrowLeft } from 'lucide-react'
+
+// Standard view page header — icon + title + description, optional back button
+// and right-aligned custom content (counts, tiles, settings, actions…). The
+// consistent "where am I / what is this page" signal across views (Rancher
+// Masthead / Headlamp SectionHeader pattern).
+interface PageHeaderProps {
+  icon: ComponentType<{ className?: string }>
+  title: string
+  description?: string
+  /** Renders a back button to the left of the title when provided. */
+  onBack?: () => void
+  /** Right-aligned custom content — wraps onto multiple lines when it overflows
+   *  (e.g. a row of count tiles). */
+  actions?: ReactNode
+}
+
+export function PageHeader({ icon: Icon, title, description, onBack, actions }: PageHeaderProps) {
+  return (
+    <div className="flex items-center gap-4">
+      {onBack && (
+        <button
+          onClick={onBack}
+          aria-label="Back"
+          className="p-1.5 rounded-lg hover:bg-theme-hover transition-colors shrink-0"
+        >
+          <ArrowLeft className="w-5 h-5 text-theme-text-secondary" />
+        </button>
+      )}
+      <div className="flex-1 min-w-0">
+        <div className="flex items-center gap-2">
+          <Icon className="w-5 h-5 text-theme-text-secondary shrink-0" />
+          <h1 className="text-lg font-semibold text-theme-text-primary truncate">{title}</h1>
+        </div>
+        {description && (
+          <p className="text-sm text-theme-text-tertiary mt-1 ml-7 truncate">{description}</p>
+        )}
+      </div>
+      {actions && <div className="flex flex-wrap items-center justify-end gap-2 shrink-0">{actions}</div>}
+    </div>
+  )
+}