feat: catalogue grid component for cookbook browser (#1444)

* feat: add catalogue grid component with filter bar for cookbook browser

- CatalogueGrid: responsive card grid (1-4 cols) with type badges,
  category badges, complexity indicators, and click-to-navigate
- FilterBar: search input, type/category/industry chip filters with
  URL query param sync via useSearchParams
- applyFilters: pure filtering logic with AND semantics
- Empty states for no items and no filter matches
- 20 vitest tests covering filter logic and grid rendering

* fix: address CodeRabbit review - keyboard accessibility and type validation

- Add role, tabIndex, and onKeyDown to CookbookCard for keyboard nav
- Wrap filter chips in <button> with aria-pressed for accessibility
- Handle unknown type query param values explicitly (filter returns empty)
- Add test for invalid type filter value

* fix: resolve eslint errors - split filter logic from components

- Move useFilterState and applyFilters to hooks/use-filter-state.ts
  to satisfy react-refresh/only-export-components rule
- Remove typeof import() annotation in test to fix
  consistent-type-imports rule

* fix: only render CardContent when categories exist

Separate the categories guard from complexity check to prevent
rendering an empty CardContent section.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

frontend/src/features/cookbook/components/catalogue-grid.test.tsx

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi } from 'vitest'
+import { screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { MemoryRouter } from 'react-router-dom'
+import { renderWithProviders } from '@/test/test-utils'
+import { CatalogueGrid } from './catalogue-grid'
+import type { CookbookItem } from '../hooks/use-cookbook'
+
+vi.mock('@/api/transport', () => ({
+  createTenantTransport: vi.fn(() => ({ __type: 'mock-transport' })),
+}))
+
+vi.mock('@/api/clients', () => ({
+  createServiceClients: vi.fn(() => ({})),
+}))
+
+const mockItems: CookbookItem[] = [
+  {
+    name: 'energy-trading',
+    type: 'registry:pattern',
+    title: 'Energy Trading',
+    description: 'Buy and sell electricity',
+    categories: ['energy', 'trading'],
+    meta: { complexity: 7, design_pattern: 'saga', industries: ['energy'] },
+  },
+  {
+    name: 'balance-card',
+    type: 'registry:ui',
+    title: 'Balance Card',
+    description: 'Displays account balance',
+    categories: ['accounts'],
+    meta: { feature_module: 'accounts', configurable: true },
+  },
+]
+
+const mockNavigate = vi.fn()
+vi.mock('react-router-dom', async () => {
+  const actual = await vi.importActual('react-router-dom')
+  return { ...actual, useNavigate: () => mockNavigate }
+})
+
+function renderGrid(items: CookbookItem[], hasActiveFilters = false) {
+  return renderWithProviders(
+    <MemoryRouter>
+      <CatalogueGrid items={items} hasActiveFilters={hasActiveFilters} />
+    </MemoryRouter>,
+  )
+}
+
+describe('CatalogueGrid', () => {
+  it('renders cards for each item', () => {
+    renderGrid(mockItems)
+    expect(screen.getByText('Energy Trading')).toBeInTheDocument()
+    expect(screen.getByText('Balance Card')).toBeInTheDocument()
+  })
+
+  it('shows type badges', () => {
+    renderGrid(mockItems)
+    expect(screen.getByText('Pattern')).toBeInTheDocument()
+    expect(screen.getByText('UI')).toBeInTheDocument()
+  })
+
+  it('shows category badges', () => {
+    renderGrid(mockItems)
+    expect(screen.getByText('energy')).toBeInTheDocument()
+    expect(screen.getByText('trading')).toBeInTheDocument()
+    expect(screen.getByText('accounts')).toBeInTheDocument()
+  })
+
+  it('shows empty state when no items', () => {
+    renderGrid([])
+    expect(screen.getByText('No cookbook entries yet')).toBeInTheDocument()
+  })
+
+  it('shows filter-specific empty state', () => {
+    renderGrid([], true)
+    expect(screen.getByText('No matching items')).toBeInTheDocument()
+  })
+
+  it('navigates on card click', async () => {
+    const user = userEvent.setup()
+    renderGrid(mockItems)
+    await user.click(screen.getByText('Energy Trading'))
+    expect(mockNavigate).toHaveBeenCalledWith('/cookbook/energy-trading')
+  })
+
+  it('shows complexity indicator for patterns', () => {
+    renderGrid(mockItems)
+    const complexityDots = document.querySelectorAll('[title="Complexity: 7/10"]')
+    expect(complexityDots.length).toBe(1)
+  })
+
+  it('shows design pattern label', () => {
+    renderGrid(mockItems)
+    expect(screen.getByText('saga')).toBeInTheDocument()
+  })
+})

frontend/src/features/cookbook/components/catalogue-grid.tsx

@@ -0,0 +1,118 @@
+import { useNavigate } from 'react-router-dom'
+import { Blocks, BookOpen, SearchX } from 'lucide-react'
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@/components/ui/card'
+import { Badge } from '@/components/ui/badge'
+import { EmptyState } from '@/components/ui/empty-state'
+import type { CookbookItem, PatternMeta, ComponentMeta } from '../hooks/use-cookbook'
+
+interface CatalogueGridProps {
+  items: CookbookItem[]
+  hasActiveFilters?: boolean
+}
+
+function isPatternMeta(meta: PatternMeta | ComponentMeta | undefined): meta is PatternMeta {
+  return meta !== undefined && 'complexity' in meta
+}
+
+function ComplexityIndicator({ score }: { score: number }) {
+  return (
+    <div className="flex items-center gap-1" title={`Complexity: ${score}/10`}>
+      {Array.from({ length: 5 }, (_, i) => (
+        <div
+          key={i}
+          className={`size-1.5 rounded-full ${
+            i < Math.ceil(score / 2) ? 'bg-primary' : 'bg-muted'
+          }`}
+        />
+      ))}
+    </div>
+  )
+}
+
+function CookbookCard({ item }: { item: CookbookItem }) {
+  const navigate = useNavigate()
+  const isPattern = item.type === 'registry:pattern'
+  const meta = item.meta
+  const patternMeta = isPatternMeta(meta) ? meta : undefined
+
+  return (
+    <Card
+      role="link"
+      tabIndex={0}
+      className="cursor-pointer transition-colors hover:border-primary/50 focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] outline-none"
+      onClick={() => navigate(`/cookbook/${item.name}`)}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault()
+          navigate(`/cookbook/${item.name}`)
+        }
+      }}
+    >
+      <CardHeader>
+        <div className="flex items-start justify-between gap-2">
+          <div className="flex items-center gap-2">
+            {isPattern ? (
+              <BookOpen className="size-4 text-primary shrink-0" />
+            ) : (
+              <Blocks className="size-4 text-muted-foreground shrink-0" />
+            )}
+            <CardTitle className="text-sm">{item.title}</CardTitle>
+          </div>
+          <Badge variant={isPattern ? 'default' : 'secondary'} className="text-[10px] shrink-0">
+            {isPattern ? 'Pattern' : 'UI'}
+          </Badge>
+        </div>
+        {item.description && (
+          <CardDescription className="line-clamp-2 text-xs">
+            {item.description}
+          </CardDescription>
+        )}
+      </CardHeader>
+
+      {item.categories && item.categories.length > 0 && (
+        <CardContent>
+          <div className="flex flex-wrap gap-1">
+            {item.categories.map((cat) => (
+              <Badge key={cat} variant="outline" className="text-[10px]">
+                {cat}
+              </Badge>
+            ))}
+          </div>
+        </CardContent>
+      )}
+
+      {patternMeta?.complexity !== undefined && (
+        <CardFooter className="justify-between">
+          <ComplexityIndicator score={patternMeta.complexity} />
+          {patternMeta.design_pattern && (
+            <span className="text-[10px] text-muted-foreground">{patternMeta.design_pattern}</span>
+          )}
+        </CardFooter>
+      )}
+    </Card>
+  )
+}
+
+export function CatalogueGrid({ items, hasActiveFilters }: CatalogueGridProps) {
+  if (items.length === 0) {
+    return (
+      <EmptyState
+        icon={hasActiveFilters ? SearchX : BookOpen}
+        title={hasActiveFilters ? 'No matching items' : 'No cookbook entries yet'}
+        description={
+          hasActiveFilters
+            ? 'Try adjusting your filters or search terms.'
+            : 'Cookbook entries will appear here once patterns and components are registered.'
+        }
+      />
+    )
+  }
+
+  return (
+    <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+      {items.map((item) => (
+        <CookbookCard key={item.name} item={item} />
+      ))}
+    </div>
+  )
+}

frontend/src/features/cookbook/components/filter-bar.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest'
+import { applyFilters, type FilterState } from '../hooks/use-filter-state'
+import type { CookbookItem } from '../hooks/use-cookbook'
+
+const mockItems: CookbookItem[] = [
+  {
+    name: 'energy-trading',
+    type: 'registry:pattern',
+    title: 'Energy Trading',
+    description: 'Buy and sell electricity on wholesale markets',
+    categories: ['energy', 'trading'],
+    meta: {
+      complexity: 7,
+      design_pattern: 'saga',
+      industries: ['energy', 'utilities'],
+    },
+  },
+  {
+    name: 'carbon-offset',
+    type: 'registry:pattern',
+    title: 'Carbon Offset',
+    description: 'Track carbon credits and offsets',
+    categories: ['carbon', 'compliance'],
+    meta: {
+      complexity: 5,
+      industries: ['energy', 'finance'],
+    },
+  },
+  {
+    name: 'balance-card',
+    type: 'registry:ui',
+    title: 'Balance Card',
+    description: 'Displays account balance with currency formatting',
+    categories: ['accounts'],
+    meta: {
+      feature_module: 'accounts',
+      configurable: true,
+    },
+  },
+]
+
+const emptyFilters: FilterState = { search: '', type: '', category: '', industry: '' }
+
+describe('applyFilters', () => {
+  it('returns all items when no filters active', () => {
+    const result = applyFilters(mockItems, emptyFilters)
+    expect(result).toHaveLength(3)
+  })
+
+  it('filters by type pattern', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, type: 'pattern' })
+    expect(result).toHaveLength(2)
+    expect(result.every((i) => i.type === 'registry:pattern')).toBe(true)
+  })
+
+  it('filters by type ui', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, type: 'ui' })
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('balance-card')
+  })
+
+  it('filters by category', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, category: 'energy' })
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('energy-trading')
+  })
+
+  it('filters by industry', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, industry: 'finance' })
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('carbon-offset')
+  })
+
+  it('filters by search term in title', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, search: 'balance' })
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('balance-card')
+  })
+
+  it('filters by search term in description', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, search: 'electricity' })
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('energy-trading')
+  })
+
+  it('search is case-insensitive', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, search: 'CARBON' })
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('carbon-offset')
+  })
+
+  it('combines multiple filters with AND logic', () => {
+    const result = applyFilters(mockItems, {
+      type: 'pattern',
+      industry: 'energy',
+      category: '',
+      search: '',
+    })
+    expect(result).toHaveLength(2)
+  })
+
+  it('returns empty when no items match', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, search: 'nonexistent' })
+    expect(result).toHaveLength(0)
+  })
+
+  it('handles items without categories or meta gracefully', () => {
+    const sparse: CookbookItem[] = [
+      { name: 'bare', type: 'registry:pattern', title: 'Bare Item' },
+    ]
+    const result = applyFilters(sparse, { ...emptyFilters, category: 'anything' })
+    expect(result).toHaveLength(0)
+  })
+
+  it('handles items without meta.industries for industry filter', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, industry: 'utilities' })
+    expect(result).toHaveLength(1)
+    expect(result[0].name).toBe('energy-trading')
+  })
+
+  it('filters out all items for unknown type value', () => {
+    const result = applyFilters(mockItems, { ...emptyFilters, type: 'invalid' })
+    expect(result).toHaveLength(0)
+  })
+})