@mdxui/terminal 2.0.0

package/src/components/types.ts

@@ -0,0 +1,777 @@
+/**
+ * @mdxui/terminal/components/types
+ *
+ * Component prop interfaces and type guards for terminal components.
+ */
+
+import type { ReactNode } from 'react'
+
+// ============================================================================
+// Render Context
+// ============================================================================
+
+export interface RenderContext {
+  width: number
+  parentWidth?: number
+  /** Enable color output (optional, for testing) */
+  colors?: boolean
+  /** Color support level (optional, for testing) */
+  colorSupport?: 'none' | '16' | '256' | 'truecolor'
+}
+
+// ============================================================================
+// Component Type
+// ============================================================================
+
+/**
+ * Valid component type strings used in createElement
+ */
+export type TerminalComponentType =
+  | 'box'
+  | 'text'
+  | 'table'
+  | 'input'
+  | 'select'
+  | 'sidebar'
+  | 'sidebar-item'
+  | 'breadcrumb'
+  | 'badge'
+  | 'dialog'
+  | 'spinner'
+  | 'button'
+  | 'panel'
+  | 'list'
+  | 'card'
+
+/**
+ * Set of all valid component types for O(1) lookup
+ */
+export const COMPONENT_TYPES: Set<string> = new Set<TerminalComponentType>([
+  'box',
+  'text',
+  'table',
+  'input',
+  'select',
+  'sidebar',
+  'sidebar-item',
+  'breadcrumb',
+  'badge',
+  'dialog',
+  'spinner',
+  'button',
+  'panel',
+  'list',
+  'card',
+])
+
+// ============================================================================
+// Primitive Component Props
+// ============================================================================
+
+export interface BoxProps {
+  children?: ReactNode
+  border?: 'none' | 'single' | 'double' | 'rounded'
+  padding?: number
+  margin?: number
+  width?: number | string
+  height?: number | string
+  flexDirection?: 'row' | 'column'
+  justifyContent?: 'flex-start' | 'center' | 'flex-end' | 'space-between'
+  alignItems?: 'flex-start' | 'center' | 'flex-end' | 'stretch'
+  gap?: number
+  bg?: string
+}
+
+export interface TextProps {
+  children?: ReactNode
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  dim?: boolean
+  color?: string
+  backgroundColor?: string
+  wrap?: 'wrap' | 'truncate' | 'truncate-middle' | 'truncate-end'
+}
+
+export interface InputProps {
+  value?: string
+  onChange?: (value: string) => void
+  placeholder?: string
+  label?: string
+  disabled?: boolean
+  focused?: boolean
+  type?: 'text' | 'password'
+  /** Cursor position within the input value (defaults to end of value) */
+  cursorPosition?: number
+  /** Width of the input field */
+  width?: number
+}
+
+export interface SelectOption<T> {
+  label: string
+  value: T
+  /** Optional: disable this option */
+  disabled?: boolean
+}
+
+export interface SelectProps<T> {
+  options: SelectOption<T>[]
+  value?: T
+  onChange?: (value: T) => void
+  label?: string
+  focused?: boolean
+  highlightedIndex?: number
+  /** Maximum visible options when expanded (defaults to 5) */
+  maxVisible?: number
+}
+
+export interface ButtonProps {
+  children?: ReactNode
+  onPress?: () => void
+  hotkey?: string
+  disabled?: boolean
+  focused?: boolean
+  variant?: 'primary' | 'secondary' | 'destructive'
+}
+
+// ============================================================================
+// Container Component Props
+// ============================================================================
+
+export interface PanelProps {
+  children?: ReactNode
+  title?: string
+  border?: 'none' | 'single' | 'double' | 'rounded'
+  collapsible?: boolean
+  collapsed?: boolean
+  padding?: number
+}
+
+export interface CardProps {
+  children?: ReactNode
+  title?: string
+  border?: 'none' | 'single' | 'double'
+}
+
+export interface DialogProps {
+  open?: boolean
+  onClose?: () => void
+  title?: string
+  children?: ReactNode
+}
+
+// ============================================================================
+// Layout Component Props
+// ============================================================================
+
+/**
+ * Sidebar layout component props (internal terminal component).
+ * This is distinct from the mdxui SidebarProps for AppComponents.
+ * @deprecated Use SidebarProps (mdxui-compatible) instead for new code.
+ */
+export interface TerminalSidebarLayoutProps {
+  children?: ReactNode
+  width?: number
+  collapsed?: boolean
+}
+
+export interface SidebarItemProps {
+  label: string
+  icon?: string
+  active?: boolean
+  onSelect?: () => void
+  children?: ReactNode
+}
+
+export interface BreadcrumbProps {
+  items: Array<{ label: string; path?: string }>
+  separator?: string
+}
+
+export interface ListProps {
+  items: string[] | ReactNode[]
+  selectedIndex?: number
+  onSelect?: (item: string | ReactNode, index: number) => void
+  bullet?: string
+  numbered?: boolean
+}
+
+export interface TableColumn<T> {
+  key: keyof T | string
+  header: string
+  width?: number
+  align?: 'left' | 'center' | 'right'
+  render?: (value: unknown, row: T) => ReactNode
+}
+
+export interface TableProps<T> {
+  data: T[]
+  columns: TableColumn<T>[]
+  onSelect?: (row: T, index: number) => void
+  selectedIndex?: number
+  navigable?: boolean
+}
+
+// ============================================================================
+// Feedback Component Props
+// ============================================================================
+
+export interface BadgeProps {
+  children?: ReactNode
+  variant?: 'default' | 'success' | 'warning' | 'error' | 'info'
+}
+
+export interface SpinnerProps {
+  label?: string
+}
+
+// ============================================================================
+// mdxui Common Types (re-exported from mdxui for convenience)
+// ============================================================================
+
+/**
+ * Navigation item for headers, sidebars, etc.
+ * Compatible with mdxui NavItem.
+ */
+export interface NavItem {
+  label: string
+  href: string
+  icon?: string
+  description?: string
+  children?: NavItem[]
+}
+
+/**
+ * Action configuration for behavior props.
+ * Compatible with mdxui ActionConfig.
+ */
+export interface ActionConfig {
+  kind?: 'config'
+  href: string
+  onClick?: () => void
+  target?: '_blank' | '_self'
+}
+
+/**
+ * Action prop accepts either a simple string (href) or full config.
+ */
+export type ActionProp = string | ActionConfig
+
+/**
+ * Standard actions object for components with primary/secondary actions.
+ */
+export interface ActionsProps {
+  primary?: ActionProp
+  secondary?: ActionProp
+}
+
+/**
+ * Footer link group structure.
+ */
+export interface FooterLinkGroup {
+  title: string
+  links: Array<{ label: string; href: string }>
+}
+
+/**
+ * Social link structure.
+ */
+export interface SocialLink {
+  platform: string
+  href: string
+  icon?: ReactNode
+}
+
+/**
+ * Feature item for Features section.
+ */
+export interface FeatureItem {
+  title: string
+  description: string
+  icon?: ReactNode
+  actions?: { link?: ActionProp }
+}
+
+/**
+ * Pricing tier structure.
+ */
+export interface PricingTier {
+  name: string
+  price: string
+  description?: string
+  features: string[]
+  callToAction: string
+  highlighted?: boolean
+  actions?: ActionsProps
+}
+
+/**
+ * FAQ item structure.
+ */
+export interface FAQItem {
+  question: string
+  answer: string
+}
+
+/**
+ * Dashboard metric structure.
+ */
+export interface DashboardMetric {
+  label: string
+  value: string | number
+  change?: number
+  trend?: 'up' | 'down' | 'neutral'
+}
+
+/**
+ * Settings section types.
+ */
+export type SettingsSection =
+  | 'profile'
+  | 'security'
+  | 'notifications'
+  | 'billing'
+  | 'team'
+  | 'api'
+  | 'integrations'
+
+/**
+ * App header user structure.
+ */
+export interface AppHeaderUser {
+  name: string
+  email: string
+  avatar?: string
+}
+
+/**
+ * Breadcrumb item structure.
+ */
+export interface BreadcrumbItem {
+  label: string
+  href?: string
+}
+
+// ============================================================================
+// Site Component Props (mdxui SiteComponents interface)
+// ============================================================================
+
+/**
+ * Site component props - root container for marketing sites.
+ * Compatible with mdxui SiteProps.
+ */
+export interface SiteProps {
+  /** Site display name (required by mdxui) */
+  name: string
+  /** Primary domain (e.g., "example.com") */
+  domain?: string
+  /** Theme mode */
+  theme?: 'light' | 'dark' | 'system'
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * Header component props - navigation header.
+ * Compatible with both mdxui HeaderProps (SiteComponents) and AppHeaderProps (AppComponents).
+ *
+ * This combined interface allows the terminal Header component to work in
+ * both site and app contexts. In site mode, logo and nav are typically used.
+ * In app mode, user and breadcrumbs are typically used.
+ *
+ * Note: For strict mdxui HeaderProps compatibility in site context,
+ * logo and nav should be provided. They are optional here to allow
+ * the same component to work with AppHeaderProps.
+ */
+export interface HeaderProps {
+  // Site header props (from mdxui HeaderProps)
+  /**
+   * Logo element or URL.
+   * Required for site usage (mdxui HeaderProps).
+   * Optional here to support dual use with AppHeaderProps.
+   */
+  logo?: ReactNode
+  /**
+   * Navigation links.
+   * Required for site usage (mdxui HeaderProps).
+   * Optional here to support dual use with AppHeaderProps.
+   */
+  nav?: NavItem[]
+  /** Primary CTA button text */
+  callToAction?: string
+  /** Action behaviors */
+  actions?: ActionsProps
+  /** Custom link component */
+  LinkComponent?: ReactNode
+
+  // App header props (from mdxui AppHeaderProps)
+  /** Current user (used in app mode) */
+  user?: AppHeaderUser
+  /** Show search */
+  showSearch?: boolean
+  /** Show notifications */
+  showNotifications?: boolean
+  /** Breadcrumbs */
+  breadcrumbs?: BreadcrumbItem[]
+
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * Footer component props - site footer.
+ * Compatible with mdxui FooterProps.
+ */
+export interface FooterProps {
+  /** Logo element or URL (required by mdxui) */
+  logo: ReactNode
+  /** Footer link groups (required by mdxui) */
+  links: FooterLinkGroup[]
+  /** Social media links */
+  social?: SocialLink[]
+  /** Copyright text */
+  copyright?: string
+  /** Newsletter signup configuration */
+  newsletter?: {
+    headline: string
+    subheadline: string
+  }
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * Hero component props - hero section.
+ * Compatible with mdxui HeroProps.
+ */
+export interface HeroProps {
+  /** Main title (required by mdxui as string) */
+  title: string
+  /** Subtitle or description */
+  subtitle?: string
+  /** Badge text (above headline) */
+  badge?: string
+  /** Primary call-to-action text (required by mdxui) */
+  callToAction: string
+  /** Secondary call-to-action text */
+  secondaryCallToAction?: string
+  /** Layout variant */
+  variant?: 'default' | 'centered' | 'split' | 'code-below' | 'video-beside' | 'image-split'
+  /** Hero image URL */
+  image?: string
+  /** Hero video URL */
+  video?: string
+  /** Product screenshot URL */
+  screenshot?: string
+  /** Code block content */
+  code?: {
+    language: string
+    code: string
+  }
+  /** Action behaviors */
+  actions?: ActionsProps
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * Features component props - features section.
+ * Compatible with mdxui FeaturesProps.
+ */
+export interface FeaturesProps {
+  /** Section title */
+  title?: string
+  /** Section description */
+  description?: string
+  /** Feature items (required by mdxui) */
+  features: FeatureItem[]
+  /** Layout variant */
+  variant?: 'grid' | 'list' | 'bento'
+  /** Number of columns (for grid) */
+  columns?: number
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * Pricing component props - pricing section.
+ * Compatible with mdxui PricingProps.
+ */
+export interface PricingProps {
+  /** Section title */
+  title?: string
+  /** Section description */
+  description?: string
+  /** Pricing tiers (required by mdxui) */
+  tiers: PricingTier[]
+  /** Show annual/monthly toggle */
+  showToggle?: boolean
+  /** Layout variant */
+  variant?: 'cards' | 'comparison-table' | 'toggle'
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * FAQ component props - FAQ section.
+ * Compatible with mdxui FAQProps.
+ */
+export interface FAQProps {
+  /** Section title */
+  title?: string
+  /** FAQ items (required by mdxui) */
+  items: FAQItem[]
+  /** Layout variant */
+  variant?: 'accordion' | 'grid' | 'list'
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * LandingPage component props - homepage layout.
+ * Compatible with mdxui LandingPageProps.
+ */
+export interface LandingPageProps {
+  /** Child sections (Hero, Features, Pricing, etc.) */
+  children?: ReactNode
+}
+
+/**
+ * Page component props - generic content page.
+ * Compatible with mdxui PageProps.
+ */
+export interface PageProps {
+  /** Page title */
+  title?: string
+  /** Page description */
+  description?: string
+  /** Page content */
+  children?: ReactNode
+}
+
+// ============================================================================
+// App Component Props (mdxui AppComponents interface)
+// ============================================================================
+
+/**
+ * App component props - root container for SaaS applications.
+ * Compatible with mdxui AppProps.
+ */
+export interface AppProps {
+  /** App display name (required by mdxui) */
+  name: string
+  /** Authentication configuration */
+  auth?: {
+    provider: 'workos' | 'clerk' | 'auth0' | 'custom'
+    clientId?: string
+    loginUrl?: string
+    redirectUri?: string
+  }
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * Shell component props - app shell layout.
+ * Compatible with mdxui ShellProps.
+ */
+export interface ShellProps {
+  /** Show sidebar */
+  sidebar?: boolean
+  /** Show header */
+  header?: boolean
+  /** Sidebar collapsed by default */
+  sidebarCollapsed?: boolean
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * Sidebar component props - navigation sidebar.
+ * Compatible with mdxui SidebarProps.
+ */
+export interface SidebarProps {
+  /** Navigation items (required by mdxui) */
+  nav: NavItem[]
+  /** User info for bottom of sidebar */
+  user?: AppHeaderUser
+  /** Branding */
+  logo?: ReactNode
+  /** Collapsed state */
+  collapsed?: boolean
+  /** On collapse toggle */
+  onCollapse?: () => void
+  /** Width */
+  width?: number
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * AppHeader component props - top header bar.
+ * Compatible with mdxui AppHeaderProps.
+ */
+export interface AppHeaderProps {
+  /** Current user */
+  user?: AppHeaderUser
+  /** Show search */
+  showSearch?: boolean
+  /** Show notifications */
+  showNotifications?: boolean
+  /** Breadcrumbs */
+  breadcrumbs?: BreadcrumbItem[]
+  /** Child content */
+  children?: ReactNode
+}
+
+/**
+ * Dashboard component props - main dashboard view.
+ * Compatible with mdxui DashboardProps.
+ */
+export interface DashboardProps {
+  /** Dashboard title */
+  title?: string
+  /** Metrics to display */
+  metrics?: DashboardMetric[]
+  /** Child widgets/content */
+  children?: ReactNode
+}
+
+/**
+ * Settings component props - settings page layout.
+ * Compatible with mdxui SettingsProps.
+ */
+export interface SettingsProps {
+  /** Settings sections to show */
+  sections?: SettingsSection[]
+  /** Child content */
+  children?: ReactNode
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Type guard to check if a value is a valid TerminalComponentType
+ */
+export function isTerminalComponentType(type: unknown): type is TerminalComponentType {
+  return typeof type === 'string' && COMPONENT_TYPES.has(type)
+}
+
+/**
+ * Type guard for props objects - validates object shape
+ */
+export function isPropsObject(props: unknown): props is Record<string, unknown> {
+  return typeof props === 'object' && props !== null
+}
+
+/**
+ * Type guard for BoxProps
+ */
+export function isBoxProps(props: unknown): props is BoxProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for TextProps
+ */
+export function isTextProps(props: unknown): props is TextProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for TableProps
+ */
+export function isTableProps(props: unknown): props is TableProps<unknown> {
+  if (!isPropsObject(props)) return false
+  return Array.isArray(props.data) && Array.isArray(props.columns)
+}
+
+/**
+ * Type guard for InputProps
+ */
+export function isInputProps(props: unknown): props is InputProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for SelectProps
+ */
+export function isSelectProps(props: unknown): props is SelectProps<unknown> {
+  if (!isPropsObject(props)) return false
+  return Array.isArray(props.options)
+}
+
+/**
+ * Type guard for SidebarProps
+ */
+export function isSidebarProps(props: unknown): props is SidebarProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for SidebarItemProps
+ */
+export function isSidebarItemProps(props: unknown): props is SidebarItemProps {
+  if (!isPropsObject(props)) return false
+  return typeof props.label === 'string'
+}
+
+/**
+ * Type guard for BreadcrumbProps
+ */
+export function isBreadcrumbProps(props: unknown): props is BreadcrumbProps {
+  if (!isPropsObject(props)) return false
+  return Array.isArray(props.items)
+}
+
+/**
+ * Type guard for BadgeProps
+ */
+export function isBadgeProps(props: unknown): props is BadgeProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for DialogProps
+ */
+export function isDialogProps(props: unknown): props is DialogProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for SpinnerProps
+ */
+export function isSpinnerProps(props: unknown): props is SpinnerProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for ButtonProps
+ */
+export function isButtonProps(props: unknown): props is ButtonProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for PanelProps
+ */
+export function isPanelProps(props: unknown): props is PanelProps {
+  return isPropsObject(props)
+}
+
+/**
+ * Type guard for ListProps
+ */
+export function isListProps(props: unknown): props is ListProps {
+  if (!isPropsObject(props)) return false
+  return Array.isArray(props.items)
+}
+
+/**
+ * Type guard for CardProps
+ */
+export function isCardProps(props: unknown): props is CardProps {
+  return isPropsObject(props)
+}