Expandable Workflow Cards With Subflow Support

[JasonWarrenUK]

Expandable Workflow Cards With Subflow Support

Overview

Implements expandable workflow cards on the homepage that reveal multiple entry points per workflow. Cards now use a click-to-expand pattern instead of direct navigation, enabling each workflow to present multiple subflows (e.g., Metis now shows "Updater" and "Generator" options).

Also includes documentation updates marking the completion of Milestone 2d (System-Wide Consistency & Modularity Audit).

Tip

No additional steps required after merging. The homepage cards now toggle between summary and subflow views on click.

Changes

Component Architecture

Extracted workflow cards into reusable WorkflowCard.svelte component with expansion logic.

• New component: src/lib/components/ui/WorkflowCard.svelte (295 lines)
• Supports both single-destination (href) and multi-destination (subflows) patterns
• Implements Svelte 5 $state for toggle behaviour
• Keyboard accessible (Enter/Space to toggle, Tab navigation)
• Smart subflow handling: auto-generates subflow from href if no explicit subflows provided

UI Behaviour Changes

Breaking Change: Cards no longer link directly; all cards expand on click.

• Inactive state: Shows description + features list
• Active state: Shows subflow buttons + "Collapse ↑" action
• Icon and title always visible
• Workflow-specific colour theming on subflow button hovers

Homepage Updates

Refactored homepage to use new WorkflowCard component.

• Removed 150+ lines of inline card markup and styling
• Updated Metis card with dual subflows (Updater, Generator)
• Removed actionText prop from all card instances
• Grid layout preserved for responsive behaviour

Documentation

Updated roadmaps to reflect audit completion.

• Marked Milestone 2d (System-Wide Consistency Audit) as completed
• Documented findings: architecture fundamentally sound
• Created remediation milestones for identified validation duplication issue
• Updated cross-references and recent achievements

---

Summary

Like transforming a row of storefronts from single doors into those fancy revolving doors at department stores — you now have to spin through the door to see the directory of what's inside, but at least you look sophisticated doing it. The Metis storefront even has two revolving doors side-by-side because apparently one entrance wasn't confusing enough.

[claude]

Summary

This PR successfully implements expandable workflow cards with strong component extraction and accessibility support. The implementation is clean with good Svelte 5 patterns, though there are minor UX considerations around the breaking change to click behaviour and some accessibility improvements needed for the "Collapse" action.

🎯 Code Quality & Best Practices

Excellent Component Extraction

• WorkflowCard.svelte:1-295: Clean component API with proper TypeScript interfaces
• Smart fallback logic at lines 31-36: automatically generates single subflow from href if no explicit subflows provided
• Good separation of concerns: component handles display logic, parent provides data

Svelte 5 Patterns

• Proper use of `` (line 28) for reactive expansion toggle
• Correct () rune usage (lines 18-26)
• Event handlers follow Svelte 5 conventions

Code Reusability

• Removed 150+ lines of duplicate markup from homepage (src/routes/+page.svelte)
• Consistent styling via CSS custom properties (workflow-specific color palettes)
• Component supports both single-destination and multi-destination patterns

Minor Style Concerns

• Lines 104-106: Dead code - a.workflow-card selector but component always renders <div>
• Line 193: .card-action defaults to Metis colors; consider using var(--palette-foreground) as fallback

🐛 Potential Issues

Breaking UX Change

The PR description notes: "Cards no longer link directly; all cards expand on click."

Concern: For workflows with single destinations (Theia, Tethys, Themis), users now need two clicks instead of one:

1. Click to expand card
2. Click subflow button to navigate

Impact: This adds friction for 75% of workflows. Consider:

• Direct navigation for single-destination cards (check effectiveSubflows.length === 1 at line 31)
• Or provide visual indicator distinguishing single vs multi-destination cards

Event Propagation

• Line 79: e.stopPropagation() on subflow links is correct, but verify this works across all browsers with nested interactive elements (button role on parent, link on child)

Empty State Handling

• Lines 31-36: If both href and subflows are missing, effectiveSubflows is empty array
• Lines 74-84: No guard against empty effectiveSubflows - would render empty subflows container
• Consider adding validation or default message

TypeScript Type Safety

• Line 14: href?: string is optional but line 35 uses it without null check in ternary
• Works due to falsy check, but could be more explicit: href ? [...] : []

⚡ Performance Considerations

Minimal Performance Impact

• Single state variable (expanded) per card instance
• No expensive computations or watchers
• CSS transitions are GPU-accelerated (transform, opacity)

Potential Optimizations

• Line 31: effectiveSubflows recalculates on every render (minor)
  • Consider `` rune: let effectiveSubflows = (...)
  • Current approach is fine for 4 cards, but good practice for consistency

CSS Efficiency

• Lines 119-216: Workflow-specific styles could use CSS custom properties more aggressively
• Current approach (separate rules per workflow) is maintainable at 4 workflows but consider selector patterns if scaling beyond 5-6

🔒 Security Concerns

No Security Issues Identified

• No user input handling or data binding vulnerabilities
• href attributes are provided by parent component (trusted source)
• No XSS vectors in template interpolation
• No external resource loading or API calls

Good Practices

• Static asset paths (/metis/icon.png, etc.) are application-controlled
• Event handlers properly scoped

✅ Test Coverage

Missing Tests

No test files included in this PR. Recommended test coverage:

Unit Tests (WorkflowCard.test.ts):

• Rendering with href only (single subflow generation)
• Rendering with explicit subflows array
• Rendering with neither href nor subflows (edge case)
• Expansion toggle behaviour (click, Enter, Space)
• Event propagation (subflow clicks don't trigger parent toggle)

Integration Tests (+page.test.ts):

• All 4 workflow cards render correctly
• Metis card shows 2 subflows (Updater, Generator)
• Navigation works for single-destination cards

Accessibility Tests:

• Keyboard navigation (Tab through cards and subflows)
• Screen reader announcements (role="button", expanded state)
• Focus indicators visible

Manual Testing Checklist

Per PR description, verify:

• Cards toggle on click without navigation
• Metis shows both "Updater" and "Generator" subflows
• Subflow buttons navigate correctly
• Collapse action returns to summary view
• Keyboard navigation works (Tab, Enter, Space)
• Dark mode styling renders correctly for all workflows

---

Recommendations

High Priority

1. Reconsider UX for single-destination cards: Either skip expansion for single subflows or add visual indicator
2. Fix empty state handling: Guard against missing href and subflows at src/lib/components/ui/WorkflowCard.svelte:74
3. Improve Collapse accessibility: Change line 86 from <div class="card-action"> to <button type="button" class="card-action"> for proper keyboard/screen reader support

Medium Priority

4. Remove dead CSS: Delete lines 104-106 (a.workflow-card selector)
5. Add ARIA attributes: aria-expanded="{expanded}" on card div (line 44), aria-label on Collapse action
6. Add test coverage: At minimum, snapshot tests for all 4 card configurations

Low Priority

7. Consider `` rune: Replace line 31 with Svelte 5 derived state for consistency
8. Document behaviour: Add JSDoc comments explaining expansion logic and subflow generation

---

Overall Assessment: Strong refactoring with good component design. Address the UX concern around double-clicks and empty state handling before merging. The architecture supports future expansion well (milestone 2e objective achieved).