Stable Document Heading Implementation Plan
> For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.
Goal: Keep the document title fixed while edit controls load and move document-status badges beside the breadcrumbs.
Architecture: DocumentTopBar receives a generic status slot. ResourcePageContent derives Private/Merged status and passes it to the top bar, while DocumentHeader stops rendering those badges. Desktop metadata affordances are positioned outside normal flow inside the existing editable-title positioning context.
Tech Stack: React, TypeScript, Tailwind CSS, Vitest, jsdom
---
Task 1: Add the top-bar status slot
Files:
Modify: frontend/packages/ui/src/document-top-bar.tsx
Test: frontend/packages/ui/src/__tests__/document-top-bar.test.tsx
[ ] Write a failing test that renders status with breadcrumbs and verifies it appears in the left group before actions.
[ ] Run the focused test and confirm it fails because status is unsupported.
[ ] Add the optional status: ReactNode prop and a non-shrinking status container after breadcrumbs.
[ ] Run the focused test and confirm it passes.
Task 2: Move Private and Merged badges out of the document header
Files:
Modify: frontend/packages/ui/src/document-header.tsx
Modify: frontend/packages/ui/src/resource-page-common.tsx
Test: frontend/packages/ui/src/__tests__/document-header-breadcrumbs.test.tsx
Test: frontend/packages/ui/src/__tests__/document-top-bar.test.tsx
[ ] Write failing tests showing status badges are absent from DocumentHeader and present in DocumentTopBar status.
[ ] Run the focused tests and confirm the expected failure.
[ ] Remove badge derivation/rendering and unused imports from DocumentHeader.
[ ] Derive status in resource-page content from visibility and version heads, then pass compact badges to DocumentTopBar.
[ ] Run the focused tests and confirm they pass.
Task 3: Remove metadata affordances from title layout flow
Files:
Modify: frontend/packages/ui/src/document-metadata-affordances.tsx
Test: frontend/packages/ui/src/__tests__/document-metadata-affordances.test.tsx
[ ] Write a failing test asserting the editable fields are a relative positioning context and the desktop affordance row is absolute above the title.
[ ] Run the focused test and confirm it fails on the missing classes.
[ ] Add the minimal positioning classes without changing visibility or mobile behavior.
[ ] Run the focused test and confirm it passes.
Task 4: Verify
Files: All files above.
[ ] Run focused tests for metadata affordances, header, and top bar.
[ ] Run direnv exec . pnpm --filter @shm/ui typecheck.
[ ] Run the frontend workspace formatter and format check required by frontend/AGENTS.md.
[ ] Run git diff --check and inspect the final diff.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime