feat: Implement sliding Issue Details drawer on desktop

[timothyfroehlich]

Feature Description

In the Issue List, clicking on an issue (on desktop) should open the issue details in a sliding drawer instead of navigating to a new page.

Requirements

• Trigger: Clicking an issue row in the .
• Behavior: A drawer slides in from the right.
• Layout: It should slide over to cover all fields except the 'Issue' column (name/machine/ID).
• Componentization: The issue details page should be converted into a reusable component to be used within this drawer.
• Closing: Include an 'X' button in the upper left of the drawer to close it.
• Responsive: This behavior should be specific to desktop views.

[traycerai]

Plan

Observations

The codebase uses Next.js 16 with App Router, server components, and Radix UI primitives. The Issue List (file:src/app/(app)/issues/page.tsx) renders IssueRow components that currently use Link to navigate to the detail page. The Issue Details page (file:src/app/(app)/m/[initials]/i/[issueNumber]/page.tsx) is a server component that fetches data and renders IssueTimeline, IssueSidebar, and IssueBadgeGrid. A Sheet component from Radix UI Dialog is already available. The app uses Tailwind CSS v4 for responsive design with md: breakpoint for desktop.

Approach

Convert the Issue Details page into a reusable component that can work in both standalone and drawer contexts. Create a client-side wrapper for the Issue List page that manages drawer state. Use the existing Sheet component for the sliding drawer with custom width to leave the Issue column visible. Implement desktop-only behavior using Tailwind's md: breakpoint and conditional rendering. Extract the data-fetching logic into a reusable server action or function to avoid duplication.

Implementation Steps

1. Create Issue Details Reusable Component

File: file:src/components/issues/IssueDetailsContent.tsx

Create a new client component that accepts issue data and user information as props. This component should render the same content currently in the Issue Details page: header with machine name and issue ID, IssueBadgeGrid, IssueTimeline, and IssueSidebar in a two-column grid layout. Accept an optional onClose callback prop for drawer mode and render a close button when provided.

2. Create Server Action for Fetching Issue Details

File: file:src/app/(app)/issues/fetch-issue-details.ts

Extract the data-fetching logic from file:src/app/(app)/m/[initials]/i/[issueNumber]/page.tsx into a reusable server action. This function should accept machineInitials and issueNumber as parameters, perform authentication checks, fetch the issue with all relations (machine, users, comments, watchers), fetch all users for assignment dropdown, and return the data or appropriate error states.

3. Update Issue Details Page to Use New Component

File: file:src/app/(app)/m/[initials]/i/[issueNumber]/page.tsx

Refactor this page to use the new server action for data fetching and render the new IssueDetailsContent component. Keep the PageShell wrapper and "Back to Issues" link. Pass fetched data as props to IssueDetailsContent without the onClose prop (standalone mode).

4. Create Issue Drawer Component

File: file:src/components/issues/IssueDrawer.tsx

Create a client component that wraps the Sheet component from file:src/components/ui/sheet.tsx. Accept props: open, onOpenChange, machineInitials, issueNumber. Use the server action to fetch issue details when opened. Customize the SheetContent width to cover most of the screen but leave space for the Issue column (approximately 75-80% width). Position the close button in the upper left as specified. Render IssueDetailsContent inside with the onClose callback.

5. Create useMediaQuery Hook

File: file:src/hooks/useMediaQuery.ts

Create a custom hook to detect desktop breakpoint using window.matchMedia. Listen for the md breakpoint (768px) to determine if the drawer should be shown. Handle SSR by returning false initially and updating on mount. Clean up event listeners on unmount.

6. Convert Issue List Page to Client Component Wrapper

File: file:src/app/(app)/issues/page.tsx

Split this into two files: keep the server component for data fetching, and create a new client component wrapper. The server component should fetch issues and machines as it currently does. Create file:src/components/issues/IssueListClient.tsx as a client component that manages drawer state (selected issue initials and number). Pass the fetched data to this client component.

7. Update IssueRow Component

File: file:src/components/issues/IssueRow.tsx

Add an onClick handler prop that accepts a callback function. On desktop (using the useMediaQuery hook or CSS classes), make the row clickable to trigger the drawer. On mobile, keep the existing Link behavior. Use conditional rendering: on desktop, wrap content in a clickable div; on mobile, keep the Link. Ensure keyboard accessibility (Enter/Space keys) for the clickable version.

8. Wire Up Issue List Client Component

File: file:src/components/issues/IssueListClient.tsx

Manage state for the currently selected issue (selectedIssue: { machineInitials: string, issueNumber: number } | null). Use the useMediaQuery hook to determine if on desktop. Render the issue list with IssueRow components, passing an onClick handler that sets the selected issue state (desktop only). Render the IssueDrawer component with the selected issue details, controlling its open state. On mobile, IssueRow should use the Link as before.

9. Handle URL Synchronization (Optional Enhancement)

Consider using shallow routing with useRouter and useSearchParams to sync the drawer state with URL query parameters (e.g., ?issue=ABC-123). This allows users to share links to specific issues in the drawer view and supports browser back/forward navigation. Update the drawer open state when query params change and update query params when drawer opens/closes.

10. Adjust Sheet Component Styling

File: file:src/components/ui/sheet.tsx

Add a new variant or custom className support for the wider drawer. Modify the SheetContent component to accept a custom width prop or add a new size variant (e.g., size="wide"). For this feature, the drawer should be approximately 75-80% width on desktop, leaving the Issue column visible. Move the close button position from upper right to upper left by adjusting the absolute positioning classes.

11. Add Loading and Error States

In file:src/components/issues/IssueDrawer.tsx, handle loading state while fetching issue details (show skeleton or spinner). Handle error states if the issue fetch fails (show error message with retry option). Consider using React Suspense boundaries for better loading UX.

12. Update Revalidation Paths

Ensure that server actions in file:src/app/(app)/issues/actions.ts also revalidate the /issues path when issue data changes, so the drawer content stays in sync with the list. Add revalidatePath('/issues') to relevant actions.

Architecture Diagram

sequenceDiagram
    participant User
    participant IssueListPage as Issue List Page (Server)
    participant IssueListClient as IssueListClient (Client)
    participant IssueRow
    participant IssueDrawer
    participant FetchAction as fetch-issue-details (Server Action)
    participant IssueDetailsContent

    User->>IssueListPage: Navigate to /issues
    IssueListPage->>IssueListPage: Fetch issues & machines
    IssueListPage->>IssueListClient: Pass data
    IssueListClient->>IssueRow: Render rows
    
    alt Desktop
        User->>IssueRow: Click issue
        IssueRow->>IssueListClient: onClick callback
        IssueListClient->>IssueListClient: Set selectedIssue state
        IssueListClient->>IssueDrawer: open=true, issue params
        IssueDrawer->>FetchAction: Fetch issue details
        FetchAction->>IssueDrawer: Return issue data
        IssueDrawer->>IssueDetailsContent: Render with data
        User->>IssueDrawer: Click X button
        IssueDrawer->>IssueListClient: onOpenChange(false)
        IssueListClient->>IssueListClient: Clear selectedIssue
    else Mobile
        User->>IssueRow: Click issue
        IssueRow->>IssueRow: Navigate via Link
        Note over IssueRow: Traditional navigation
    end

Loading

Component Structure

src/
├── app/(app)/
│   ├── issues/
│   │   ├── page.tsx (Server - fetches data, renders IssueListClient)
│   │   ├── actions.ts (Updated with /issues revalidation)
│   │   └── fetch-issue-details.ts (New - server action for fetching)
│   └── m/[initials]/i/[issueNumber]/
│       └── page.tsx (Updated - uses IssueDetailsContent)
├── components/
│   ├── issues/
│   │   ├── IssueListClient.tsx (New - client wrapper with drawer state)
│   │   ├── IssueRow.tsx (Updated - conditional onClick/Link)
│   │   ├── IssueDrawer.tsx (New - Sheet wrapper with data fetching)
│   │   ├── IssueDetailsContent.tsx (New - reusable details component)
│   │   ├── IssueTimeline.tsx (Existing - reused)
│   │   ├── IssueSidebar.tsx (Existing - reused)
│   │   └── IssueBadgeGrid.tsx (Existing - reused)
│   └── ui/
│       └── sheet.tsx (Updated - support for custom width/close position)
└── hooks/
    └── useMediaQuery.ts (New - desktop detection)

Key Considerations

• Responsive Behavior: Use useMediaQuery hook to detect desktop (md: breakpoint at 768px). Only show drawer on desktop; mobile continues to use full-page navigation.
• Data Fetching: Extract issue details fetching into a reusable server action to avoid code duplication between the standalone page and drawer.
• State Management: Manage drawer open/close state in IssueListClient component. Consider URL synchronization for better UX.
• Accessibility: Ensure the drawer has proper ARIA labels, focus management (trap focus in drawer when open), and keyboard navigation (Escape to close).
• Performance: Use React Suspense for loading states. Consider prefetching issue data on row hover for faster drawer opening.
• Drawer Width: Customize Sheet component to be wider (75-80% of viewport) to leave the Issue column visible as specified.
• Close Button Position: Move the close button from default upper-right to upper-left as required.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses Next.js 16 with App Router, server components, and Radix UI primitives. The Issue List (`file:src/app/(app)/issues/page.tsx`) renders `IssueRow` components that currently use `Link` to navigate to the detail page. The Issue Details page (`file:src/app/(app)/m/[initials]/i/[issueNumber]/page.tsx`) is a server component that fetches data and renders `IssueTimeline`, `IssueSidebar`, and `IssueBadgeGrid`. A `Sheet` component from Radix UI Dialog is already available. The app uses Tailwind CSS v4 for responsive design with `md:` breakpoint for desktop.

## Approach

Convert the Issue Details page into a reusable component that can work in both standalone and drawer contexts. Create a client-side wrapper for the Issue List page that manages drawer state. Use the existing Sheet component for the sliding drawer with custom width to leave the Issue column visible. Implement desktop-only behavior using Tailwind's `md:` breakpoint and conditional rendering. Extract the data-fetching logic into a reusable server action or function to avoid duplication.

## Implementation Steps

### 1. Create Issue Details Reusable Component

**File**: `file:src/components/issues/IssueDetailsContent.tsx`

Create a new client component that accepts issue data and user information as props. This component should render the same content currently in the Issue Details page: header with machine name and issue ID, `IssueBadgeGrid`, `IssueTimeline`, and `IssueSidebar` in a two-column grid layout. Accept an optional `onClose` callback prop for drawer mode and render a close button when provided.

### 2. Create Server Action for Fetching Issue Details

**File**: `file:src/app/(app)/issues/fetch-issue-details.ts`

Extract the data-fetching logic from `file:src/app/(app)/m/[initials]/i/[issueNumber]/page.tsx` into a reusable server action. This function should accept `machineInitials` and `issueNumber` as parameters, perform authentication checks, fetch the issue with all relations (machine, users, comments, watchers), fetch all users for assignment dropdown, and return the data or appropriate error states.

### 3. Update Issue Details Page to Use New Component

**File**: `file:src/app/(app)/m/[initials]/i/[issueNumber]/page.tsx`

Refactor this page to use the new server action for data fetching and render the new `IssueDetailsContent` component. Keep the `PageShell` wrapper and "Back to Issues" link. Pass fetched data as props to `IssueDetailsContent` without the `onClose` prop (standalone mode).

### 4. Create Issue Drawer Component

**File**: `file:src/components/issues/IssueDrawer.tsx`

Create a client component that wraps the `Sheet` component from `file:src/components/ui/sheet.tsx`. Accept props: `open`, `onOpenChange`, `machineInitials`, `issueNumber`. Use the server action to fetch issue details when opened. Customize the `SheetContent` width to cover most of the screen but leave space for the Issue column (approximately 75-80% width). Position the close button in the upper left as specified. Render `IssueDetailsContent` inside with the `onClose` callback.

### 5. Create useMediaQuery Hook

**File**: `file:src/hooks/useMediaQuery.ts`

Create a custom hook to detect desktop breakpoint using `window.matchMedia`. Listen for the `md` breakpoint (768px) to determine if the drawer should be shown. Handle SSR by returning `false` initially and updating on mount. Clean up event listeners on unmount.

### 6. Convert Issue List Page to Client Component Wrapper

**File**: `file:src/app/(app)/issues/page.tsx`

Split this into two files: keep the server component for data fetching, and create a new client component wrapper. The server component should fetch issues and machines as it currently does. Create `file:src/components/issues/IssueListClient.tsx` as a client component that manages drawer state (selected issue initials and number). Pass the fetched data to this client component.

### 7. Update IssueRow Component

**File**: `file:src/components/issues/IssueRow.tsx`

Add an `onClick` handler prop that accepts a callback function. On desktop (using the `useMediaQuery` hook or CSS classes), make the row clickable to trigger the drawer. On mobile, keep the existing `Link` behavior. Use conditional rendering: on desktop, wrap content in a clickable div; on mobile, keep the Link. Ensure keyboard accessibility (Enter/Space keys) for the clickable version.

### 8. Wire Up Issue List Client Component

**File**: `file:src/components/issues/IssueListClient.tsx`

Manage state for the currently selected issue (`selectedIssue: { machineInitials: string, issueNumber: number } | null`). Use the `useMediaQuery` hook to determine if on desktop. Render the issue list with `IssueRow` components, passing an `onClick` handler that sets the selected issue state (desktop only). Render the `IssueDrawer` component with the selected issue details, controlling its open state. On mobile, `IssueRow` should use the Link as before.

### 9. Handle URL Synchronization (Optional Enhancement)

Consider using shallow routing with `useRouter` and `useSearchParams` to sync the drawer state with URL query parameters (e.g., `?issue=ABC-123`). This allows users to share links to specific issues in the drawer view and supports browser back/forward navigation. Update the drawer open state when query params change and update query params when drawer opens/closes.

### 10. Adjust Sheet Component Styling

**File**: `file:src/components/ui/sheet.tsx`

Add a new variant or custom className support for the wider drawer. Modify the `SheetContent` component to accept a custom width prop or add a new `size` variant (e.g., `size="wide"`). For this feature, the drawer should be approximately 75-80% width on desktop, leaving the Issue column visible. Move the close button position from upper right to upper left by adjusting the absolute positioning classes.

### 11. Add Loading and Error States

In `file:src/components/issues/IssueDrawer.tsx`, handle loading state while fetching issue details (show skeleton or spinner). Handle error states if the issue fetch fails (show error message with retry option). Consider using React Suspense boundaries for better loading UX.

### 12. Update Revalidation Paths

Ensure that server actions in `file:src/app/(app)/issues/actions.ts` also revalidate the `/issues` path when issue data changes, so the drawer content stays in sync with the list. Add `revalidatePath('/issues')` to relevant actions.

## Architecture Diagram

```mermaid
sequenceDiagram
    participant User
    participant IssueListPage as Issue List Page (Server)
    participant IssueListClient as IssueListClient (Client)
    participant IssueRow
    participant IssueDrawer
    participant FetchAction as fetch-issue-details (Server Action)
    participant IssueDetailsContent

    User->>IssueListPage: Navigate to /issues
    IssueListPage->>IssueListPage: Fetch issues & machines
    IssueListPage->>IssueListClient: Pass data
    IssueListClient->>IssueRow: Render rows
    
    alt Desktop
        User->>IssueRow: Click issue
        IssueRow->>IssueListClient: onClick callback
        IssueListClient->>IssueListClient: Set selectedIssue state
        IssueListClient->>IssueDrawer: open=true, issue params
        IssueDrawer->>FetchAction: Fetch issue details
        FetchAction->>IssueDrawer: Return issue data
        IssueDrawer->>IssueDetailsContent: Render with data
        User->>IssueDrawer: Click X button
        IssueDrawer->>IssueListClient: onOpenChange(false)
        IssueListClient->>IssueListClient: Clear selectedIssue
    else Mobile
        User->>IssueRow: Click issue
        IssueRow->>IssueRow: Navigate via Link
        Note over IssueRow: Traditional navigation
    end
```

## Component Structure

```
src/
├── app/(app)/
│   ├── issues/
│   │   ├── page.tsx (Server - fetches data, renders IssueListClient)
│   │   ├── actions.ts (Updated with /issues revalidation)
│   │   └── fetch-issue-details.ts (New - server action for fetching)
│   └── m/[initials]/i/[issueNumber]/
│       └── page.tsx (Updated - uses IssueDetailsContent)
├── components/
│   ├── issues/
│   │   ├── IssueListClient.tsx (New - client wrapper with drawer state)
│   │   ├── IssueRow.tsx (Updated - conditional onClick/Link)
│   │   ├── IssueDrawer.tsx (New - Sheet wrapper with data fetching)
│   │   ├── IssueDetailsContent.tsx (New - reusable details component)
│   │   ├── IssueTimeline.tsx (Existing - reused)
│   │   ├── IssueSidebar.tsx (Existing - reused)
│   │   └── IssueBadgeGrid.tsx (Existing - reused)
│   └── ui/
│       └── sheet.tsx (Updated - support for custom width/close position)
└── hooks/
    └── useMediaQuery.ts (New - desktop detection)
```

## Key Considerations

- **Responsive Behavior**: Use `useMediaQuery` hook to detect desktop (`md:` breakpoint at 768px). Only show drawer on desktop; mobile continues to use full-page navigation.
- **Data Fetching**: Extract issue details fetching into a reusable server action to avoid code duplication between the standalone page and drawer.
- **State Management**: Manage drawer open/close state in `IssueListClient` component. Consider URL synchronization for better UX.
- **Accessibility**: Ensure the drawer has proper ARIA labels, focus management (trap focus in drawer when open), and keyboard navigation (Escape to close).
- **Performance**: Use React Suspense for loading states. Consider prefetching issue data on row hover for faster drawer opening.
- **Drawer Width**: Customize Sheet component to be wider (75-80% of viewport) to leave the Issue column visible as specified.
- **Close Button Position**: Move the close button from default upper-right to upper-left as required.

---

Execution Information

Branch: main
Commit: 47d7e44

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.