110 lines
3.2 KiB
Markdown
110 lines
3.2 KiB
Markdown
## Layout page decomposition
|
|
|
|
Split `pages/layout.tsx` into composable layout modules with stable behavior.
|
|
|
|
---
|
|
|
|
### Summary
|
|
|
|
`packages/app/src/pages/layout.tsx` is a 3,000+ line coordinator for sidebar navigation, project/workspace controls, deep-link handling, dialogs, drag/drop overlays, and global shell interactions. This spec decomposes it into focused modules to improve maintainability and reduce merge risk for future features.
|
|
|
|
---
|
|
|
|
### Goals
|
|
|
|
- Break up `packages/app/src/pages/layout.tsx` into smaller units.
|
|
- Separate rendering concerns from orchestration/state concerns.
|
|
- Keep existing URL/navigation semantics and sidebar behavior.
|
|
- Preserve all current command and dialog entry points.
|
|
|
|
---
|
|
|
|
### Non-goals
|
|
|
|
- No major UX redesign of the sidebar or project/workspace UI.
|
|
- No changes to server/global-sync contracts.
|
|
- No refactor of `pages/session.tsx` in this workstream.
|
|
|
|
---
|
|
|
|
### Parallel ownership (important)
|
|
|
|
This workstream owns:
|
|
|
|
- `packages/app/src/pages/layout.tsx`
|
|
- New files under `packages/app/src/pages/layout/**`
|
|
|
|
This workstream must not edit:
|
|
|
|
- `packages/app/src/pages/session.tsx` (spec 09)
|
|
- `packages/app/src/components/prompt-input.tsx` (spec 11)
|
|
- `packages/app/src/context/global-sync.tsx` (spec 12)
|
|
|
|
---
|
|
|
|
### Current state
|
|
|
|
- File size: ~3,004 LOC.
|
|
- Contains mixed concerns:
|
|
- app-shell rendering
|
|
- sidebar/project/workspace UI + drag/drop
|
|
- deep-link handling and startup flows
|
|
- workspace reset/delete actions and toasts
|
|
|
|
---
|
|
|
|
### Proposed module split
|
|
|
|
Create `packages/app/src/pages/layout/` modules such as:
|
|
|
|
- `use-layout-page-state.ts` - orchestration state and handlers.
|
|
- `sidebar-panel.tsx` - sidebar shell and root interactions.
|
|
- `project-item.tsx` - project-level row and actions.
|
|
- `workspace-item.tsx` - workspace row, sessions list, and workspace actions.
|
|
- `deep-links.ts` - deep-link parsing/draining/handler utilities.
|
|
|
|
Keep `packages/app/src/pages/layout.tsx` as route-level composition and provider wiring.
|
|
|
|
---
|
|
|
|
### Phased steps
|
|
|
|
1. Extract pure helpers first (deep-link parse, shared label helpers, small utility functions).
|
|
2. Extract workspace subtree and action handlers.
|
|
3. Extract project subtree and menu actions.
|
|
4. Extract sidebar shell and drag overlay components.
|
|
5. Move orchestration logic into `use-layout-page-state.ts`.
|
|
6. Reduce `layout.tsx` to composition-only entry.
|
|
|
|
---
|
|
|
|
### Acceptance criteria
|
|
|
|
- `packages/app/src/pages/layout.tsx` is significantly smaller (target: under 1,200 LOC).
|
|
- Behavior parity for:
|
|
- project open/close/rename
|
|
- workspace expand/collapse/reset/delete
|
|
- deep-link handling
|
|
- drag/drop ordering
|
|
- No regressions in keyboard navigation and dialog actions.
|
|
|
|
---
|
|
|
|
### Validation plan
|
|
|
|
- Typecheck: `bun run typecheck` (from `packages/app`).
|
|
- Targeted e2e checks:
|
|
- `e2e/sidebar/sidebar.spec.ts`
|
|
- `e2e/projects/workspaces.spec.ts`
|
|
- `e2e/projects/project-edit.spec.ts`
|
|
- `e2e/app/navigation.spec.ts`
|
|
- Manual check: deep-link open-project flow still opens and navigates correctly.
|
|
|
|
---
|
|
|
|
### Handoff notes
|
|
|
|
- Keep action handlers close to their domain module.
|
|
- Do not merge in behavior cleanups during extraction; preserve semantics first.
|
|
- If shared components are needed, add them under `pages/layout/` for now to avoid cross-spec conflicts.
|