DevContainer User
2.0 KiB
ADR 004: URL Hash-Based Detail Panel State
Status: Accepted
Date: 2026-03-05
Deciders: Development Team
Context
Several pages need to show detail panels for selected resources (e.g., clicking a PVC row shows PVC details). The detail panel state (which resource is selected) needs to be shareable via URL and survive page refresh. Options include:
- React state — Lost on refresh, not shareable
- URL query parameters — May cause full page reload, potential conflicts with Headlamp routing
- URL hash fragments — Client-side only, no reload, compatible with SPA routing
Decision
Use URL hash fragments to encode detail panel state. When a user selects a resource, the hash is updated (e.g., #pvc/namespace/name). On page load, the hash is parsed to restore the selected resource. This enables deep-linking to specific resource details and browser back/forward navigation.
Consequences
- ✅ Deep-linkable resource details — users can share URLs pointing to specific resources
- ✅ Survives page refresh without losing selected resource
- ✅ Browser back/forward navigation works naturally
- ✅ No server round-trip — hash changes are purely client-side
- ✅ Compatible with Headlamp's client-side routing
- ⚠️ Hash-based state is not a standard React pattern — requires team familiarity
- ⚠️ Requires manual hash parsing and updating logic
- ⚠️ Hash changes don't trigger React re-renders by default — requires
hashchangeevent listener
Alternatives Considered
-
React state only — Rejected. State is lost on refresh and cannot be shared via URL.
-
URL query parameters — Rejected. May conflict with Headlamp's routing and could trigger unintended navigation behavior.
-
Separate detail routes — Rejected. Too heavyweight for inline detail panels; would require full page transitions for what should be a panel toggle.
Changelog
| Date | Change |
|---|---|
| 2026-03-05 | Initial decision |