Gap Analysis

This document summarizes all gaps between the mdxui type definitions and the current UI component implementations.

Summary

Critical Gaps (Must Have)

Site Components

App Components

Props Alignment Needed

High Priority

1. Header (Site)

   • Current: links, primaryCta, secondaryCta
   • Target: nav, cta
   • Breaking change: Yes

2. Hero (Site)

   • Current: highlightedText, description, button props
   • Target: subtitle, cta, secondaryCta
   • Breaking change: Yes

3. DeveloperDashboard (App)

   • Current: config object
   • Target: Individual props OR config
   • Breaking change: Possible

Lower Priority

4. FAQ/FAQs naming
5. LandingLayout → LandingPage naming
6. Page components → standalone components

New Types to Consider Adding

Based on what exists in implementations but not in mdxui:

From Landing Package

// Hero enhancements
interface HeroProps {
  highlightedText?: string
  backgroundType?: 'image' | 'hatch' | 'none'
  codeTabs?: CodeTabItem[]
}

// Directory component
interface DirectoryProps {
  categories: DirectoryCategory[]
  items: DirectoryItem[]
}

From Dashboards Package

// Additional routes
interface AppComponents {
  Database?: Component<DatabaseProps>
  Integrations?: Component<IntegrationsProps>
  Vault?: Component<VaultProps>
}

// Enhanced config pattern
interface DeveloperDashboardProps {
  // Option 1: Individual props
  project: string
  showAPIKeys?: boolean
  // ...

  // Option 2: Config object
  config?: DashboardConfig
}

Migration Path

Phase 1: Non-Breaking Additions

1. Add missing components to UI packages
2. Add optional config pattern alongside props
3. Add new component types to mdxui

Phase 2: Deprecation

1. Mark old prop names as deprecated
2. Add migration warnings
3. Document migration path

Phase 3: Breaking Changes

1. Remove deprecated props
2. Enforce new naming conventions
3. Major version bump

Decision Points

These require discussion before proceeding:

1. Config Object vs Individual Props

Option A: Individual props (current mdxui approach)

<DeveloperDashboard
  project="proj-123"
  showAPIKeys={true}
  showWebhooks={true}
/>

Option B: Config object (current dashboards approach)

<DeveloperDashboard config={{
  identity: { clientId: '...' },
  routes: { keys: true, webhooks: true },
}} />

Option C: Both (flexibility)

// Either works
<DeveloperDashboard project="proj-123" />
<DeveloperDashboard config={config} />

2. Auto-Wiring Location

Where should auto-wiring logic live?

• Option A: In mdxui (types + wiring config)
• Option B: In workers (runtime only)
• Option C: Split (config in mdxui, runtime in workers)

3. Component Granularity

Should complex features be:

• Option A: Single component (<Webhooks />)
• Option B: Multiple pages (<WebhooksEndpoints />, <WebhooksLogs />)
• Option C: Composable (<Webhooks><Endpoints /><Logs /></Webhooks>)

Next Steps

1. Decide on config pattern approach
2. Create Shell, Sidebar, Header in dashboards
3. Create Site, Page in landing
4. Align Hero and Header props
5. Add Blog/Docs components (or defer to separate package)
6. Update mdxui types based on decisions