alex
fb0f2f7b9b
- Remove inline edit modal from projects listing page - Add Settings link to project cards navigating to /projects/:id/settings - Reposition Open Workspace button to rightmost action for easier access - Update tests for new UI flow - Update documentation to reflect new editing workflow - Sync specs: frontend-foundation and project-management Quality gates: npm run lint passed
148 lines
4.4 KiB
Markdown
148 lines
4.4 KiB
Markdown
# Frontend Foundation Specification
|
|
|
|
## Purpose
|
|
|
|
Provide a modern React frontend with TypeScript, routing, and responsive layout.
|
|
## Requirements
|
|
### Requirement: React Application Setup
|
|
The system SHALL use React 18+ with TypeScript and SHALL provide a runnable application source structure in `apps/web/src`.
|
|
|
|
#### Scenario: Frontend build
|
|
- GIVEN the frontend codebase
|
|
- THEN it SHALL:
|
|
- Use React 18+ with TypeScript 5+
|
|
- Use Vite as the build tool
|
|
- Support Hot Module Replacement (HMR)
|
|
- Output optimized production builds
|
|
- Include a concrete entrypoint, app composition, and route tree
|
|
|
|
### Requirement: Client-Side Routing
|
|
The system SHALL implement client-side routing with authenticated route guards and explicit not-found handling.
|
|
|
|
#### Scenario: Navigation
|
|
- GIVEN the frontend application
|
|
- THEN React Router SHALL:
|
|
- Define routes for all foundation pages
|
|
- Support protected routes (require authentication)
|
|
- Handle 404 errors
|
|
- Support route parameters for feature pages
|
|
|
|
#### Scenario: Protected routes
|
|
- GIVEN an unauthenticated user
|
|
- WHEN they access a protected route
|
|
- THEN they are redirected to login flow
|
|
- AND post-auth navigation returns them to an authenticated landing route
|
|
|
|
### Requirement: Styling Framework
|
|
|
|
The system SHALL use Tailwind CSS for styling.
|
|
|
|
#### Scenario: UI components
|
|
- GIVEN the frontend codebase
|
|
- THEN Tailwind CSS SHALL:
|
|
- Provide utility-first styling
|
|
- Support custom theme configuration
|
|
- Include responsive design utilities
|
|
- Support dark mode
|
|
|
|
### Requirement: Layout Component
|
|
The system SHALL provide a consistent application layout for authenticated screens across desktop and mobile sizes.
|
|
|
|
#### Scenario: Application shell
|
|
- GIVEN the frontend application
|
|
- THEN a Layout component SHALL:
|
|
- Display a header with user info and logout
|
|
- Display sidebar navigation on desktop
|
|
- Show main content area
|
|
- Collapse sidebar into a mobile menu toggle on small viewports
|
|
|
|
#### Scenario: Navigation links
|
|
- GIVEN the sidebar navigation
|
|
- THEN it SHALL include links to:
|
|
- Dashboard
|
|
- Projects
|
|
- Repositories
|
|
- SSH Keys
|
|
- Settings
|
|
|
|
### Requirement: Responsive Design
|
|
|
|
The system SHALL support mobile devices.
|
|
|
|
#### Scenario: Mobile viewport
|
|
- GIVEN a mobile device
|
|
- WHEN the app loads
|
|
- THEN:
|
|
- A hamburger menu replaces the sidebar
|
|
- Content adapts to screen width
|
|
- Touch targets are appropriately sized
|
|
|
|
### Requirement: Loading States
|
|
The system SHALL handle asynchronous operations gracefully during auth bootstrap and dashboard fetches.
|
|
|
|
#### Scenario: Data fetching
|
|
- GIVEN a page loading data
|
|
- THEN:
|
|
- Loading states are shown while requests are in flight
|
|
- Errors are shown with retry affordance
|
|
- Initial auth-check loading prevents protected-layout flicker
|
|
|
|
### Requirement: HTTP Client Configuration
|
|
The system SHALL configure HTTP requests for cookie-based auth and unauthorized-session recovery.
|
|
|
|
#### Scenario: API communication
|
|
- GIVEN the frontend application
|
|
- THEN Axios/fetch SHALL:
|
|
- Send credentials (cookies) with requests
|
|
- Handle 401 responses by redirecting to login
|
|
- Set appropriate content-type headers
|
|
- Support request/response interception in a shared client module
|
|
|
|
### Requirement: Dashboard Page
|
|
|
|
The system SHALL provide a dashboard overview.
|
|
|
|
#### Scenario: Dashboard view
|
|
- GIVEN an authenticated user
|
|
- WHEN they visit the dashboard
|
|
- THEN they see:
|
|
- Total repository count
|
|
- Total project count
|
|
- Recent activity
|
|
- Quick action buttons
|
|
|
|
### Requirement: Projects Listing Page Layout
|
|
The projects listing page SHALL display project cards with Settings, Delete, and Open Workspace actions, where Open Workspace is the rightmost action.
|
|
|
|
#### Scenario: Project card action layout
|
|
- GIVEN the projects listing page
|
|
- WHEN project cards are rendered
|
|
- THEN each card shows actions in order: Settings link, Delete button, Open Workspace button (rightmost)
|
|
|
|
#### Scenario: Navigate to project settings
|
|
- GIVEN the projects listing page
|
|
- WHEN a user clicks the Settings link
|
|
- THEN they navigate to `/projects/:id/settings`
|
|
|
|
#### Scenario: No inline edit modal
|
|
- GIVEN the projects listing page
|
|
- WHEN a user views a project card
|
|
- THEN no inline Edit button or modal dialog is available
|
|
|
|
## Dependencies
|
|
|
|
- React 18+
|
|
- TypeScript 5+
|
|
- Vite
|
|
- React Router
|
|
- Tailwind CSS
|
|
- Axios
|
|
|
|
## Quality Gates
|
|
|
|
- `npm run typecheck` must pass
|
|
- `npm run lint` must pass
|
|
- `npm run build` must succeed
|
|
- Frontend handles 401 responses correctly
|
|
- Responsive design works on mobile
|