popiart-node-canvas/.planning/phases/25-template-explorer-ui/25-01-PLAN.md

phase	plan	type
25-template-explorer-ui	1	execute

Create the template explorer component architecture with cards layout and template metadata.

Purpose: Build the foundational UI components for template browsing that scales to many templates. Output: TemplateExplorerView component with TemplateCard, template metadata types, and grid layout.

<execution_context> ~/.claude/get-shit-done/workflows/execute-phase.md ~/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md

Key files: @src/lib/quickstart/templates.ts @src/components/quickstart/QuickstartTemplatesView.tsx @src/components/quickstart/WelcomeModal.tsx @src/types/quickstart.ts

Current state:

• 6 preset templates in templates.ts with name, description, icon, workflow
• QuickstartTemplatesView uses compact button layout (grid of small buttons)
• Community workflows fetched from /api/community-workflows
• WelcomeModal manages view state: initial, templates, vibe

Established patterns:

• Template data in src/lib/quickstart/templates.ts
• QuickstartView type manages view navigation
• Tailwind CSS with neutral-* colors
• Icon components using inline SVG paths

Task 1: Extend template types with rich metadata src/types/quickstart.ts, src/lib/quickstart/templates.ts 1. Add TemplateMetadata interface to quickstart.ts: - nodeCount: number - category: 'product' | 'style' | 'composition' | 'community' - tags: string[] (e.g., ['product', 'scene', 'fashion']) - previewImage?: string (optional for now)

2. Update PresetTemplate interface in templates.ts to include metadata:
   • Add category and tags to each template
   • Add getTemplateMetadata() function that extracts node count from workflow

Categories for existing templates:

• product-shot: category='product', tags=['product', 'scene', 'placement']
• model-product: category='product', tags=['product', 'model', 'fashion']
• color-variations: category='product', tags=['product', 'color', 'variations']
• background-swap: category='composition', tags=['composite', 'background', 'subject']
• style-transfer: category='style', tags=['style', 'artistic', 'transfer']
• scene-composite: category='composition', tags=['composite', 'scene', 'elements'] TypeScript compiles without errors: npm run build TemplateMetadata interface exists, all preset templates have category/tags, getTemplateMetadata() returns node count

Task 2: Create TemplateCard component src/components/quickstart/TemplateCard.tsx Create a new TemplateCard component that displays template in a card format:

1. Props:

   • template: PresetTemplate with metadata
   • isLoading: boolean
   • onClick: () => void
   • disabled: boolean

2. Layout (approximately 280px wide):

   • Top section: Icon in a larger container (48x48 icon area with neutral-700/50 bg)
   • Template name (text-sm font-medium)
   • Description (text-xs text-neutral-400, max 2 lines with line-clamp-2)
   • Metadata row: node count badge, category badge
   • Tags displayed as small pills (text-[10px])

3. States:

   • Default: border-neutral-700, hover:border-neutral-600, hover:bg-neutral-800/50
   • Loading: bg-blue-600/20 border-blue-500/50, spinner animation
   • Disabled: opacity-50, cursor-not-allowed

4. Use existing patterns from QuickstartTemplatesView for loading spinner SVG

Keep the card compact but informative - focus on scannability. Use group hover for icon color transitions. Component renders without errors in isolation (check TypeScript): npm run build TemplateCard.tsx exists with card layout, displays metadata, handles loading/disabled states

Task 3: Create TemplateExplorerView with grid layout src/components/quickstart/TemplateExplorerView.tsx Create TemplateExplorerView component that replaces QuickstartTemplatesView with a full explorer layout:

1. Layout structure (flex container):

   • Header: Back button + "Template Explorer" title (reuse QuickstartBackButton)
   • Main content area with card grid (grid-cols-2 on mobile, grid-cols-3 on larger)
   • Cards use TemplateCard component

2. State management:

   • Templates from getAllPresets()
   • Community workflows from /api/community-workflows
   • Loading states for list and individual template loading
   • Error handling (reuse existing error display pattern)

3. Template selection:

   • On click: fetch full workflow via /api/quickstart POST (for presets) or /api/community-workflows/[id] (for community)
   • Pass workflow to onWorkflowSelected callback
   • Track model usage like existing implementation

4. For now, display all templates in single grid (filtering added in Plan 02)

   • Presets section first with "Quick Start" header
   • Community section with "Community" header (if any exist)

Keep consistent with existing visual style from QuickstartTemplatesView but use card layout instead of compact buttons. npm run build succeeds, component structure is correct TemplateExplorerView.tsx exists with grid of TemplateCards, fetches and displays templates, handles selection

Before declaring plan complete: - [ ] `npm run build` succeeds without TypeScript errors - [ ] TemplateMetadata types are properly defined - [ ] TemplateCard component renders template info in card format - [ ] TemplateExplorerView displays templates in grid layout

<success_criteria>

• All tasks completed
• TypeScript builds without errors
• Template cards display name, description, node count, category, tags
• Grid layout adapts to screen size
• Ready for Plan 02 to add filtering/search </success_criteria>

After completion, create `.planning/phases/25-template-explorer-ui/25-01-SUMMARY.md`