feat: Further refine machine page layout

[timothyfroehlich]

Continue refining the machine detail page layout. The current two-column (4/8 split) implementation provides a solid foundation. Future refinements could include:\n- Adding icons to machine status pills (Operational, Needs Service, Unplayable) for visual consistency with issue badges.\n- Expanding machine stats and historical data visualization.\n- Optimizing the issue list display further for different screen sizes.

[traycerai]

Plan

Observations

The machine detail page (file:src/app/(app)/m/[initials]/page.tsx) currently displays machine status using Badge components without icons. The codebase already has a pattern for status icons in file:src/components/issues/StatusIndicator.tsx using lucide-react icons. The database schema includes temporal data (createdAt, resolvedAt, updatedAt) suitable for historical visualization, but no charting library is currently installed. The page uses a single-column layout with a 2x2 stats grid that could benefit from responsive optimization.

Approach

The implementation will follow the existing component patterns and styling conventions. For machine status icons, we'll mirror the StatusIndicator pattern used for issues. For data visualization, we'll add a lightweight charting library compatible with the existing tech stack (Next.js 16, React 19, Tailwind CSS). The issue list will be enhanced with responsive grid layouts similar to the dashboard pattern. All changes will maintain consistency with the Material Design 3 color system already in use.

Implementation Steps

1. Add Icons to Machine Status Pills

Update file:src/lib/machines/status.ts:

• Add a new function getMachineStatusIcon() that returns the appropriate lucide-react icon component for each status:
  • operational → CheckCircle2 (consistent with resolved issues)
  • needs_service → Wrench (consistent with dashboard service indicator)
  • unplayable → XCircle (consistent with dashboard unplayable machines)

Update file:src/app/(app)/m/[initials]/page.tsx:

• Import the new icon function and lucide-react icons
• Modify the Badge components at lines 136-144 and 198-206 to include the icon as a child element
• The Badge component already supports icons with proper styling ([&>svg]:size-3 gap-1)

sequenceDiagram
    participant Page as Machine Detail Page
    participant Status as status.ts
    participant Badge as Badge Component
    participant Lucide as lucide-react
    
    Page->>Status: getMachineStatusIcon(status)
    Status->>Lucide: Return icon component
    Page->>Badge: Render with icon + label
    Badge->>Page: Display styled pill with icon

Loading

2. Expand Machine Stats Section

Enhance stats display in file:src/app/(app)/m/[initials]/page.tsx:

• Add new stat cards to the existing grid (lines 192-250):
  • Average Resolution Time: Calculate from issues with resolvedAt timestamps
  • Critical Issues: Count of issues with priority: "critical"
  • Last Issue Reported: Display most recent issue createdAt date
  • Resolution Rate: Percentage of resolved vs total issues
• Update the grid from grid-cols-2 md:grid-cols-4 to grid-cols-2 md:grid-cols-3 lg:grid-cols-4 for better responsive behavior
• Add icons to each stat card (similar to dashboard pattern in file:src/app/(app)/dashboard/page.tsx lines 218-278)

Create helper functions in file:src/lib/machines/queries.ts:

• calculateAverageResolutionTime(issues): Compute average time between createdAt and resolvedAt
• getMachineStatistics(issues): Return aggregated stats object

3. Add Historical Data Visualization

Install charting library:

• Add recharts to dependencies (lightweight, React-friendly, works well with Tailwind)
• Alternative: Use native SVG with D3 utilities if minimal bundle size is critical

Create new component file:src/components/machines/MachineCharts.tsx:

• Issue Trend Chart: Line chart showing issue creation over time (last 30/60/90 days)
• Status Distribution: Pie or bar chart showing breakdown by status (new, in_progress, resolved)
• Severity Distribution: Bar chart showing severity levels over time
• Use the existing color system from file:src/lib/issues/status.ts for consistent styling
• Make charts responsive with Tailwind breakpoints

Add chart section to machine detail page:

• Insert new Card component after the Machine Information card (after line 252)
• Include toggle/tabs for different time ranges (30/60/90 days)
• Fetch historical data by querying issues with date filters

Chart Type	Data Source	Purpose
Issue Trend	issues.createdAt	Show issue reporting patterns
Status Distribution	issues.status	Current issue breakdown
Severity Over Time	issues.severity, issues.createdAt	Track severity trends
Resolution Time	issues.resolvedAt - issues.createdAt	Performance metric

4. Optimize Issue List Display

Enhance responsive layout in file:src/app/(app)/m/[initials]/page.tsx (lines 289-336):

• Convert the current vertical list to a responsive grid on larger screens:
  • Mobile: Single column (current behavior)
  • Tablet: md:grid-cols-2 for two-column layout
  • Desktop: Keep two columns or expand to lg:grid-cols-3 if space allows
• Add visual hierarchy improvements:
  • Make issue cards more compact on mobile (reduce padding)
  • Stack badges vertically on small screens using flex-col sm:flex-row
  • Truncate long titles with truncate class on mobile

Improve issue card component (lines 297-334):

• Extract issue card into a reusable component file:src/components/machines/MachineIssueCard.tsx
• Add hover states with scale transform for better interactivity
• Include issue status icons (from StatusIndicator pattern) alongside badges
• Add loading skeleton states for better perceived performance

Add filtering and sorting controls:

• Create filter dropdown above issue list (similar to file:src/components/IssueFilters.tsx)
• Allow filtering by: status, severity, priority
• Allow sorting by: date (newest/oldest), priority (high/low)
• Use URL search params to maintain filter state

5. Responsive Layout Refinements

Implement two-column layout mentioned in ticket:

• Wrap the page content in a responsive grid container:
  • Mobile: Single column (full width)
  • Desktop: lg:grid-cols-12 with left sidebar (4 cols) and main content (8 cols)
• Left column (4/12): Machine information card with stats
• Right column (8/12): Charts and issues list
• Use sticky positioning for the left column on desktop: lg:sticky lg:top-6

Update container structure:

<div className="grid grid-cols-1 lg:grid-cols-12 gap-6">
  <div className="lg:col-span-4">
    {/* Machine Info Card */}
  </div>
  <div className="lg:col-span-8 space-y-6">
    {/* Charts Card */}
    {/* Issues Card */}
  </div>
</div>

6. Testing Considerations

Visual regression testing:

• Test responsive breakpoints (mobile, tablet, desktop)
• Verify icon alignment in status pills
• Ensure charts render correctly with various data volumes

Data edge cases:

• Empty state: No issues (already handled)
• Single issue: Ensure charts don't break
• Large dataset: Test performance with 100+ issues
• Missing data: Handle null resolvedAt gracefully

Accessibility:

• Ensure icons have proper aria-label attributes
• Charts should have text alternatives
• Maintain keyboard navigation for filters

Import In IDE

🤖 Prompt for AI Agents

## Observations

The machine detail page (`file:src/app/(app)/m/[initials]/page.tsx`) currently displays machine status using Badge components without icons. The codebase already has a pattern for status icons in `file:src/components/issues/StatusIndicator.tsx` using lucide-react icons. The database schema includes temporal data (`createdAt`, `resolvedAt`, `updatedAt`) suitable for historical visualization, but no charting library is currently installed. The page uses a single-column layout with a 2x2 stats grid that could benefit from responsive optimization.

## Approach

The implementation will follow the existing component patterns and styling conventions. For machine status icons, we'll mirror the StatusIndicator pattern used for issues. For data visualization, we'll add a lightweight charting library compatible with the existing tech stack (Next.js 16, React 19, Tailwind CSS). The issue list will be enhanced with responsive grid layouts similar to the dashboard pattern. All changes will maintain consistency with the Material Design 3 color system already in use.

## Implementation Steps

### 1. Add Icons to Machine Status Pills

**Update `file:src/lib/machines/status.ts`:**
- Add a new function `getMachineStatusIcon()` that returns the appropriate lucide-react icon component for each status:
  - `operational` → `CheckCircle2` (consistent with resolved issues)
  - `needs_service` → `Wrench` (consistent with dashboard service indicator)
  - `unplayable` → `XCircle` (consistent with dashboard unplayable machines)

**Update `file:src/app/(app)/m/[initials]/page.tsx`:**
- Import the new icon function and lucide-react icons
- Modify the Badge components at lines 136-144 and 198-206 to include the icon as a child element
- The Badge component already supports icons with proper styling (`[&>svg]:size-3 gap-1`)

```mermaid
sequenceDiagram
    participant Page as Machine Detail Page
    participant Status as status.ts
    participant Badge as Badge Component
    participant Lucide as lucide-react
    
    Page->>Status: getMachineStatusIcon(status)
    Status->>Lucide: Return icon component
    Page->>Badge: Render with icon + label
    Badge->>Page: Display styled pill with icon
```

### 2. Expand Machine Stats Section

**Enhance stats display in `file:src/app/(app)/m/[initials]/page.tsx`:**
- Add new stat cards to the existing grid (lines 192-250):
  - **Average Resolution Time**: Calculate from issues with `resolvedAt` timestamps
  - **Critical Issues**: Count of issues with `priority: "critical"`
  - **Last Issue Reported**: Display most recent issue `createdAt` date
  - **Resolution Rate**: Percentage of resolved vs total issues
- Update the grid from `grid-cols-2 md:grid-cols-4` to `grid-cols-2 md:grid-cols-3 lg:grid-cols-4` for better responsive behavior
- Add icons to each stat card (similar to dashboard pattern in `file:src/app/(app)/dashboard/page.tsx` lines 218-278)

**Create helper functions in `file:src/lib/machines/queries.ts`:**
- `calculateAverageResolutionTime(issues)`: Compute average time between `createdAt` and `resolvedAt`
- `getMachineStatistics(issues)`: Return aggregated stats object

### 3. Add Historical Data Visualization

**Install charting library:**
- Add `recharts` to dependencies (lightweight, React-friendly, works well with Tailwind)
- Alternative: Use native SVG with D3 utilities if minimal bundle size is critical

**Create new component `file:src/components/machines/MachineCharts.tsx`:**
- **Issue Trend Chart**: Line chart showing issue creation over time (last 30/60/90 days)
- **Status Distribution**: Pie or bar chart showing breakdown by status (new, in_progress, resolved)
- **Severity Distribution**: Bar chart showing severity levels over time
- Use the existing color system from `file:src/lib/issues/status.ts` for consistent styling
- Make charts responsive with Tailwind breakpoints

**Add chart section to machine detail page:**
- Insert new Card component after the Machine Information card (after line 252)
- Include toggle/tabs for different time ranges (30/60/90 days)
- Fetch historical data by querying issues with date filters

| Chart Type | Data Source | Purpose |
|------------|-------------|---------|
| Issue Trend | `issues.createdAt` | Show issue reporting patterns |
| Status Distribution | `issues.status` | Current issue breakdown |
| Severity Over Time | `issues.severity`, `issues.createdAt` | Track severity trends |
| Resolution Time | `issues.resolvedAt - issues.createdAt` | Performance metric |

### 4. Optimize Issue List Display

**Enhance responsive layout in `file:src/app/(app)/m/[initials]/page.tsx` (lines 289-336):**
- Convert the current vertical list to a responsive grid on larger screens:
  - Mobile: Single column (current behavior)
  - Tablet: `md:grid-cols-2` for two-column layout
  - Desktop: Keep two columns or expand to `lg:grid-cols-3` if space allows
- Add visual hierarchy improvements:
  - Make issue cards more compact on mobile (reduce padding)
  - Stack badges vertically on small screens using `flex-col sm:flex-row`
  - Truncate long titles with `truncate` class on mobile

**Improve issue card component (lines 297-334):**
- Extract issue card into a reusable component `file:src/components/machines/MachineIssueCard.tsx`
- Add hover states with scale transform for better interactivity
- Include issue status icons (from StatusIndicator pattern) alongside badges
- Add loading skeleton states for better perceived performance

**Add filtering and sorting controls:**
- Create filter dropdown above issue list (similar to `file:src/components/IssueFilters.tsx`)
- Allow filtering by: status, severity, priority
- Allow sorting by: date (newest/oldest), priority (high/low)
- Use URL search params to maintain filter state

### 5. Responsive Layout Refinements

**Implement two-column layout mentioned in ticket:**
- Wrap the page content in a responsive grid container:
  - Mobile: Single column (full width)
  - Desktop: `lg:grid-cols-12` with left sidebar (4 cols) and main content (8 cols)
- Left column (4/12): Machine information card with stats
- Right column (8/12): Charts and issues list
- Use sticky positioning for the left column on desktop: `lg:sticky lg:top-6`

**Update container structure:**
```
<div className="grid grid-cols-1 lg:grid-cols-12 gap-6">
  <div className="lg:col-span-4">
    {/* Machine Info Card */}
  </div>
  <div className="lg:col-span-8 space-y-6">
    {/* Charts Card */}
    {/* Issues Card */}
  </div>
</div>
```

### 6. Testing Considerations

**Visual regression testing:**
- Test responsive breakpoints (mobile, tablet, desktop)
- Verify icon alignment in status pills
- Ensure charts render correctly with various data volumes

**Data edge cases:**
- Empty state: No issues (already handled)
- Single issue: Ensure charts don't break
- Large dataset: Test performance with 100+ issues
- Missing data: Handle null `resolvedAt` gracefully

**Accessibility:**
- Ensure icons have proper `aria-label` attributes
- Charts should have text alternatives
- Maintain keyboard navigation for filters

---

Execution Information

Branch: main
Commit: 7e83b51

---

💡 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.

[timothyfroehlich]

Closing as completed. Work has been merged. —Claude