feat: shared React component library for Headlamp plugin authors

[Athang69]

Is your feature request related to a problem? Please describe the impact that the lack of the feature requested is creating.

Every Headlamp plugin that surfaces Kubernetes custom resources faces the same set of UI problems: rendering .status.conditions[] arrays, building consistent detail page layouts, displaying phase strings as colored chips, and handling loading, error, and empty states. Right now each plugin author solves these independently, which means duplicated code, inconsistent UX across plugins, and a steeper learning curve for new contributors who have to reverse-engineer patterns from existing plugins instead of reaching for a documented, tested component.

With multiple plugins either recently merged or actively in development (Agones, Argo CD, Kueue, Metal3, Tinkerbell, Cluster API, Kubeflow, Strimzi, Knative), this duplication is becoming a real cost. There is no shared foundation that plugin authors can build on.

Describe the solution you'd like

A shared component library scoped specifically to Headlamp plugin development, either living under frontend/src/plugin-components in the main repo or published as a standalone package under the @headlamp-k8s namespace.

The initial set of components I am proposing, based on patterns I have seen repeated across the existing plugin PRs:

• <CRDStatusBadge /> - renders a Kubernetes .status.conditions[] array with type, status, and reason surfaced consistently
• <ResourceDetailLayout /> - a standard scaffold for custom resource detail pages with metadata, status, and events sections
• <CRDTable /> - a table component wired for custom resources with sorting, filtering, and pagination
• <ConditionList /> - renders condition arrays with icons and color coding tied to condition status
• <PhaseChip /> - maps any .status.phase string to a MUI chip with sensible color defaults for common Kubernetes phase values

Each component would ship with:

• Full TypeScript types
• Unit tests
• Storybook stories for visual reference and manual testing
• JSDoc on all props

What users will benefit from this feature?

Plugin developers primarily. Anyone building a Headlamp plugin that surfaces custom resources would have a set of tested, documented building blocks instead of building from scratch. This also benefits end users indirectly because consistent components mean a consistent UX across all plugins, so switching between the Agones plugin and the Argo CD plugin does not feel like a different product.

Are you able to implement this feature?

Yes (I will propose a PR).

Before opening a PR I wanted to raise this here first to get maintainer input on two things:

1. Whether this belongs in the main repo or as a separate package under @headlamp-k8s
2. Whether there are existing internal patterns or component abstractions I should align with before starting

Happy to jump on the Slack channel to discuss further if that is easier.

Additional context

I have hands-on experience with the kubernetes-sigs/headlamp codebase across multiple layers and this proposal comes directly from noticing the same patterns being re-implemented across plugin PRs.

[sniok]

we already have CommonComponents in the plugin library which contains quite an extensive list of UI components

frontend/src/components/common/index.ts

[Athang69]

@sniok Thanks for pointing me to CommonComponents. I'll spend some time reviewing the existing shared components first to understand what's already available for plugin authors. My initial proposal was based on patterns I noticed across plugin PRs, but it's possible some of those use cases are already covered.

[Athang69]

Research findings: duplication patterns across the codebase

After auditing frontend/src/components/common/index.ts and cross-referencing usage patterns across the codebase, here are the concrete gaps I found.

---

Gap 1: makeStatusLabel in common/Label.tsx is not being found

common/Label.tsx line 148 already exports:

export function makeStatusLabel(label: string, successStatusName: string) {
  return <StatusLabel status={label === successStatusName ? 'success' : 'error'}>{label}</StatusLabel>
}

But namespace/Details.tsx and namespace/List.tsx both write their own inline version of the exact same logic instead of importing this.

Fix: No new component needed. Add documentation or a Storybook story pointing plugin authors to this function.

---

Gap 2: .status.conditions[] rendering is implemented in 4 different ways

File	Function	Logic
common/Resource/Resource.tsx	makeStatusLabel(condition)	checks type === 'Available' only
gateway/ClassList.tsx	makeGatewayStatusLabel(conditions[])	checks against a conditionOptions map
gateway/GatewayDetails.tsx	local makeStatusLabel	different logic from the one in common
crd/CustomResourceDetails.tsx	<ConditionsTable>	separate abstraction, accepts full resource object

A shared <ConditionList conditions={conditions} /> component in common that accepts a KubeCondition[] and renders them consistently would replace all four.

---

Gap 3: Phase-to-status mapping is per-resource

storage/utils.tsx has StatusLabelByPhase(phase) for PV/PVC but it is storage-specific. Every other resource with a phase string does it inline:

• namespace/Details.tsx: status === 'Active' ? 'success' : 'error'
• namespace/List.tsx: same logic duplicated
• portforward/index.tsx: portforward.status === PORT_FORWARD_RUNNING_STATUS ? 'success' : ''

A generic <PhaseLabel phase={phase} successPhase="Active" /> that wraps StatusLabel and accepts a configurable success phase would cover all of these.

---

Gap 4: conditions.find(c => c.type === 'Ready') duplicated 9 times

pod/List.tsx line 45        ×1
pod/List.tsx line 280       ×2
cluster/Charts/StatusCharts.tsx line 34    ×3
cluster/Charts/StatusCharts.tsx line 91    ×4
diagnostics/Diagnostics.tsx line 237       ×5
diagnostics/Diagnostics.tsx line 578       ×6
resourceMap/nodes/KubeObjectStatus.tsx line 34   ×7
node/Details.tsx line 436   ×8
node/List.tsx line 82       ×9

A utility function getReadyCondition(conditions: KubeCondition[]) exported from common would eliminate all nine.

---

Summary

Gap	New component needed?
makeStatusLabel undiscovered	No, just docs/story
Conditions rendering	Yes, <ConditionList />
Phase-to-status mapping	Yes, <PhaseLabel />
Ready condition finder	No, utility function