feat: add session list overhaul proposal
- Add proposal for unified session list components - Add design doc with component architecture - Add specs for SessionCard and SessionList requirements - Add implementation tasks Refs: session-list-overhaul
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-05-24
|
||||
@@ -0,0 +1,60 @@
|
||||
## Context
|
||||
|
||||
The current session list implementation duplicates rendering logic across `dashboard.tsx` and `sessions.tsx`. Both pages fetch the same data, apply similar filtering (active vs recent/stopped), and render session cards with inconsistent styling and controls. The dashboard has a compact grid view while the sessions page has a list view, but neither provides all control actions (open, stop, start, delete) in a consistent way.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Unified session card component with all control actions visible and accessible
|
||||
- Unified session list component that handles filtering, grouping, and empty states
|
||||
- Consistent visual design across dashboard and sessions pages
|
||||
- Clear status indicators (running, stopped, error, building, etc.)
|
||||
- Project/repository context visible on each card
|
||||
- Responsive layout that works on mobile and desktop
|
||||
|
||||
**Non-Goals:**
|
||||
- No API changes
|
||||
- No new session management features (just better UI for existing ones)
|
||||
- No changes to session creation flow
|
||||
- No real-time updates beyond existing polling
|
||||
|
||||
## Decisions
|
||||
|
||||
**Decision: Two levels of components**
|
||||
- `SessionCard`: Individual session display with actions
|
||||
- `SessionList`: Container that handles grouping and layout
|
||||
This allows the dashboard to use `SessionList` directly while the sessions page can add additional filtering/controls around it.
|
||||
|
||||
**Decision: Card-based layout over table**
|
||||
Cards provide better mobile experience and can show richer information (project context, tool icon, status badge). Tables are harder to make responsive.
|
||||
|
||||
**Decision: Inline actions on cards**
|
||||
Each card shows primary action (Open for running, Start for stopped) and secondary actions in a dropdown or secondary button row. This matches the existing dashboard pattern but makes it consistent.
|
||||
|
||||
**Decision: Status colors**
|
||||
- Running: green
|
||||
- Building/Starting/Probing: yellow/amber
|
||||
- Stopped: gray
|
||||
- Error: red
|
||||
- Unhealthy: orange
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
**Risk: Breaking existing dashboard layout**
|
||||
→ Mitigation: Keep the same grid layout structure, just swap the inner rendering to use SessionCard
|
||||
|
||||
**Risk: Mobile experience with many action buttons**
|
||||
→ Mitigation: Use icon buttons on mobile, text buttons on desktop. Collapse secondary actions into a "..." menu.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Create SessionCard and SessionList components
|
||||
2. Update dashboard.tsx to use SessionList
|
||||
3. Update sessions.tsx to use SessionList
|
||||
4. Remove old duplicated session rendering code
|
||||
5. Update styles
|
||||
6. Test both pages
|
||||
|
||||
## Open Questions
|
||||
|
||||
None
|
||||
@@ -0,0 +1,28 @@
|
||||
## Why
|
||||
|
||||
The current session list UI is fragmented between the dashboard home page and the dedicated sessions page, with duplicated rendering logic, inconsistent styling, and missing control actions. Users need a unified, clear view of their sessions with easy access to controls (start, stop, delete, open) regardless of which page they're on.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Create a unified `SessionCard` component used on both dashboard and sessions pages
|
||||
- Create a `SessionList` component that handles filtering, grouping, and layout
|
||||
- Add clear status indicators and action buttons (open, stop, start, delete) to each session card
|
||||
- Remove duplicated session rendering logic from dashboard.tsx and sessions.tsx
|
||||
- Consistent empty states and loading states across both pages
|
||||
- Better visual hierarchy with project/repository context
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `session-list-ui`: Unified session list components with clear information display and control buttons
|
||||
|
||||
### Modified Capabilities
|
||||
- `session-lifecycle-ux`: Update to include unified list component requirements
|
||||
- `sessions-hub`: Update to use unified components instead of page-specific rendering
|
||||
|
||||
## Impact
|
||||
|
||||
- Frontend: New components in `apps/web/src/components/session-list.tsx` and `apps/web/src/components/session-card.tsx`
|
||||
- Modified pages: `apps/web/src/pages/dashboard.tsx`, `apps/web/src/pages/sessions.tsx`
|
||||
- Modified styles: `apps/web/src/styles.css`
|
||||
- No API changes required
|
||||
@@ -0,0 +1,93 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Session card displays session information
|
||||
The system SHALL display each session in a card format showing:
|
||||
- Tool type name and icon
|
||||
- Session display name or generated name
|
||||
- Project and repository name
|
||||
- Current status with visual indicator
|
||||
- Clone mode indicator (if clone mode)
|
||||
- Port number (if applicable)
|
||||
- Created time
|
||||
|
||||
#### Scenario: View active session card
|
||||
- **WHEN** user views the sessions list
|
||||
- **THEN** each running session card shows a green status indicator
|
||||
- **AND** the card displays the tool type name
|
||||
- **AND** the card displays the project and repository names
|
||||
- **AND** the card displays the port number
|
||||
|
||||
#### Scenario: View stopped session card
|
||||
- **WHEN** user views the sessions list
|
||||
- **THEN** each stopped session card shows a gray status indicator
|
||||
- **AND** the card does not display a port number
|
||||
- **AND** the card shows when it was last active
|
||||
|
||||
#### Scenario: View clone mode session card
|
||||
- **WHEN** user views a clone-mode session
|
||||
- **THEN** the card displays a clone indicator
|
||||
- **AND** the card shows the branch name (if applicable)
|
||||
|
||||
### Requirement: Session card provides control actions
|
||||
The system SHALL provide action buttons on each session card:
|
||||
- Running sessions: Open (primary), Stop, Delete
|
||||
- Stopped sessions: Start (primary), Delete
|
||||
- Building/Starting sessions: Show progress indicator, no actions
|
||||
- Error sessions: Show error state, Delete
|
||||
|
||||
#### Scenario: Open running session
|
||||
- **WHEN** user clicks the "Open" button on a running session card
|
||||
- **THEN** the session opens in the appropriate interface (web, terminal, IDE)
|
||||
|
||||
#### Scenario: Stop running session
|
||||
- **WHEN** user clicks the "Stop" button on a running session card
|
||||
- **THEN** a confirmation dialog appears
|
||||
- **AND** upon confirmation, the session stops
|
||||
|
||||
#### Scenario: Start stopped session
|
||||
- **WHEN** user clicks the "Start" button on a stopped session card
|
||||
- **THEN** the session starts
|
||||
- **AND** the card updates to show building/starting status
|
||||
|
||||
#### Scenario: Delete session
|
||||
- **WHEN** user clicks the "Delete" button on any session card
|
||||
- **THEN** a confirmation dialog appears
|
||||
- **AND** upon confirmation, the session is deleted
|
||||
- **AND** the card is removed from the list immediately
|
||||
|
||||
### Requirement: Session list supports grouping and filtering
|
||||
The system SHALL group sessions by status category:
|
||||
- Active: running, building, starting, probing
|
||||
- Recent: stopped, error (limited to last 5)
|
||||
- The list SHALL support filtering by status
|
||||
|
||||
#### Scenario: View grouped sessions
|
||||
- **WHEN** user views the sessions page
|
||||
- **THEN** active sessions appear in an "Active" section
|
||||
- **AND** recent stopped sessions appear in a "Recent" section
|
||||
- **AND** each section has a clear heading with count
|
||||
|
||||
### Requirement: Unified components across pages
|
||||
The system SHALL use the same SessionCard and SessionList components on both the dashboard and sessions pages.
|
||||
|
||||
#### Scenario: Dashboard uses unified components
|
||||
- **WHEN** user views the dashboard home page
|
||||
- **THEN** the session grid uses SessionCard components
|
||||
- **AND** the visual style matches the sessions page
|
||||
|
||||
#### Scenario: Sessions page uses unified components
|
||||
- **WHEN** user views the sessions page
|
||||
- **THEN** the session list uses SessionList and SessionCard components
|
||||
- **AND** the visual style matches the dashboard
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Sessions page layout
|
||||
**FROM:** Sessions page renders sessions with page-specific layout and styling
|
||||
**TO:** Sessions page uses SessionList component with consistent layout and styling
|
||||
|
||||
#### Scenario: Sessions page renders unified list
|
||||
- **WHEN** user navigates to the sessions page
|
||||
- **THEN** the page uses the SessionList component
|
||||
- **AND** sessions are displayed in a card grid
|
||||
- **AND** each card has consistent control actions
|
||||
@@ -0,0 +1,53 @@
|
||||
## 1. Create SessionCard Component
|
||||
|
||||
- [ ] 1.1 Create `apps/web/src/components/session-card.tsx` with session display and actions
|
||||
- [ ] 1.2 Implement status indicator with color coding (running=green, building=yellow, stopped=gray, error=red)
|
||||
- [ ] 1.3 Display tool type name, session name, project/repo context
|
||||
- [ ] 1.4 Add clone mode indicator and branch name when applicable
|
||||
- [ ] 1.5 Implement action buttons: Open (running), Start (stopped), Stop (running), Delete (all)
|
||||
- [ ] 1.6 Add confirmation dialogs for Stop and Delete actions
|
||||
- [ ] 1.7 Handle loading states during actions
|
||||
|
||||
## 2. Create SessionList Component
|
||||
|
||||
- [ ] 2.1 Create `apps/web/src/components/session-list.tsx` with grouping logic
|
||||
- [ ] 2.2 Implement active sessions grouping (running, building, starting, probing)
|
||||
- [ ] 2.3 Implement recent sessions grouping (stopped, error, limited to last 5)
|
||||
- [ ] 2.4 Add section headers with counts
|
||||
- [ ] 2.5 Handle empty states for each section
|
||||
- [ ] 2.6 Support filtering by status
|
||||
|
||||
## 3. Update Dashboard Page
|
||||
|
||||
- [ ] 3.1 Import SessionCard and SessionList in dashboard.tsx
|
||||
- [ ] 3.2 Replace existing session grid rendering with SessionList
|
||||
- [ ] 3.3 Remove duplicated session rendering code
|
||||
- [ ] 3.4 Ensure "Open sessions" section uses unified components
|
||||
- [ ] 3.5 Ensure "Recent sessions" section uses unified components
|
||||
|
||||
## 4. Update Sessions Page
|
||||
|
||||
- [ ] 4.1 Import SessionCard and SessionList in sessions.tsx
|
||||
- [ ] 4.2 Replace existing session list rendering with SessionList
|
||||
- [ ] 4.3 Remove duplicated session rendering code
|
||||
- [ ] 4.4 Keep page-level controls (create session button, filters)
|
||||
- [ ] 4.5 Ensure "Last Session" section uses SessionCard
|
||||
|
||||
## 5. Styles and Polish
|
||||
|
||||
- [ ] 5.1 Add CSS styles for SessionCard layout (responsive grid)
|
||||
- [ ] 5.2 Add CSS styles for action buttons (icon vs text based on viewport)
|
||||
- [ ] 5.3 Style status indicators and badges
|
||||
- [ ] 5.4 Ensure consistent spacing and typography
|
||||
- [ ] 5.5 Test responsive layout on mobile viewport
|
||||
|
||||
## 6. Testing and Verification
|
||||
|
||||
- [ ] 6.1 Verify dashboard renders sessions correctly
|
||||
- [ ] 6.2 Verify sessions page renders sessions correctly
|
||||
- [ ] 6.3 Test action buttons (open, start, stop, delete)
|
||||
- [ ] 6.4 Test confirmation dialogs
|
||||
- [ ] 6.5 Test empty states
|
||||
- [ ] 6.6 Test responsive layout
|
||||
- [ ] 6.7 Run TypeScript compilation
|
||||
- [ ] 6.8 Run ESLint
|
||||
Reference in New Issue
Block a user