组件 API 设计：少传布尔值，多用组合

<Card
  title="用户信息"
  showIcon
  withBadge
  isLoading={false}
  highlighted
  dense
  collapsible
  defaultExpanded={false}
  showActions
  showDivider
  bordered
  hoverable
  compact
>
  {/* ... */}
</Card>

// ❌ 配置式：调用方需要记住每个 prop 的含义和组合规则
<UserCard
  name="张三"
  showAvatar
  avatarSize="md"
  showStatus
  statusPosition="top-right"
  showBadge
  badgeColor="green"
/>
 
// ✅ 组合式：调用方直接描述想要的结构
<UserCard>
  <UserCard.Avatar src="..." status="online" />
  <UserCard.Name>张三</UserCard.Name>
  <UserCard.Badge color="green">在线</UserCard.Badge>
</UserCard>

// ❌ 布尔属性堆叠，调用方无法直观理解组件结构
<Card
  title="用户信息"
  showHeader
  showFooter={false}
  showActions
  collapsible
  defaultExpanded
  compact={isMobile}
>
  <UserInfo user={user} />
  <div className="card-footer-actions">
    <Button>编辑</Button>
    <Button>删除</Button>
  </div>
</Card>

// ❌ 组件内部：条件分支森林
function Card({
  title,
  showHeader = true,
  showFooter = true,
  showActions = false,
  collapsible = false,
  defaultExpanded = true,
  compact = false,
  children,
}) {
  const [expanded, setExpanded] = useState(defaultExpanded)
 
  return (
    <div className={cn('card', compact && 'card-compact')}>
      {showHeader && (
        <div className="card-header">
          <span>{title}</span>
          {collapsible && (
            <button onClick={() => setExpanded(!expanded)}>
              {expanded ? '收起' : '展开'}
            </button>
          )}
        </div>
      )}
      {(!collapsible || expanded) && (
        <div className="card-body">{children}</div>
      )}
      {showFooter && showActions && (
        <div className="card-actions">
          {/* 这里耦合了 footer 和 actions 两个概念 */}
        </div>
      )}
    </div>
  )
}

// ✅ 复合组件：每个区域独立控制，结构一目了然
function Card({ children }: { children: React.ReactNode }) {
  return <div className="card">{children}</div>
}
 
function CardHeader({
  title,
  children,
}: {
  title?: string
  children?: React.ReactNode
}) {
  return (
    <div className="card-header">
      {title && <span>{title}</span>}
      {children}
    </div>
  )
}
 
function CardBody({ children }: { children: React.ReactNode }) {
  return <div className="card-body">{children}</div>
}
 
function CardActions({ children }: { children: React.ReactNode }) {
  return <div className="card-actions">{children}</div>
}
 
Card.Header = CardHeader
Card.Body = CardBody
Card.Actions = CardActions

// ✅ 调用方：结构和视觉层级完全一致
<Card>
  <Card.Header title="用户信息" />
  <Card.Body>
    <UserInfo user={user} />
  </Card.Body>
  <Card.Actions>
    <Button>编辑</Button>
    <Button>删除</Button>
  </Card.Actions>
</Card>

// ✅ 通过 Context 共享状态，避免 prop 透传
const CardContext = createContext<{
  expanded: boolean
  toggle: () => void
} | null>(null)
 
function Card({ children, defaultExpanded = true }: CardProps) {
  const [expanded, setExpanded] = useState(defaultExpanded)
  const toggle = useCallback(() => setExpanded((v) => !v), [])
 
  return (
    <CardContext.Provider value={{ expanded, toggle }}>
      <div className="card">{children}</div>
    </CardContext.Provider>
  )
}
 
function CardHeader({ title, children }: CardHeaderProps) {
  const { toggle } = useCardContext()
  return (
    <div className="card-header">
      <span>{title}</span>
      {children}
      <button onClick={toggle}>切换</button>
    </div>
  )
}
 
function CardBody({ children }: { children: React.ReactNode }) {
  const { expanded } = useCardContext()
  if (!expanded) return null
  return <div className="card-body">{children}</div>
}

// ❌ 四种样式 × 三种尺寸 = 12 个 prop
<Button primary outline sm>
  提交
</Button>
 
// primary 和 outline 同时为 true 是什么效果？
// outline 和 ghost 同时为 true 呢？

// ✅ 一个 variant 替代多个布尔属性
<Button variant="primary-outline" size="sm">
  提交
</Button>
 
// 或者用更细粒度的变体命名
<Button variant="primary" size="sm">
  提交
</Button>
<Button variant="outline" size="sm">
  取消
</Button>
<Button variant="ghost" size="md">
  更多
</Button>

// ✅ 映射表替代条件分支
const variantStyles: Record<string, string> = {
  primary: 'bg-blue-600 text-white',
  secondary: 'bg-gray-200 text-gray-800',
  outline: 'border border-gray-300 bg-transparent',
  ghost: 'bg-transparent hover:bg-gray-100',
  danger: 'bg-red-600 text-white',
  'primary-outline': 'border border-blue-600 text-blue-600 bg-transparent',
}
 
function Button({
  variant = 'primary',
  size = 'md',
  children,
  ...props
}: ButtonProps) {
  return (
    <button className={cn('btn', variantStyles[variant], sizeStyles[size])} {...props}>
      {children}
    </button>
  )
}

// ❌ 7 个布尔值，closable 和 showClose 语义重叠
<Modal
  open={visible}
  showClose
  showMask
  closable
  maskClosable={false}
  showFooter
  footerAlign="right"
  centered
  onClose={handleClose}
>
  <p>确认删除这条记录？</p>
</Modal>

// ✅ 按职责分组 + 子组件化
<Modal open={visible} onClose={handleClose}>
  <Modal.Header closable>确认操作</Modal.Header>
  <Modal.Body>
    <p>确认删除这条记录？</p>
  </Modal.Body>
  <Modal.Footer align="right">
    <Button variant="ghost" onClick={handleClose}>
      取消
    </Button>
    <Button variant="danger" onClick={handleConfirm}>
      删除
    </Button>
  </Modal.Footer>
</Modal>

// ✅ 行为配置合并为对象
<Modal
  open={visible}
  onClose={handleClose}
  mask={{ closable: false, blur: true }}
  position="center"
>
  {/* ... */}
</Modal>

// ❌ 无法约束互斥关系：href 和 onClick 可以同时传
interface ButtonProps {
  variant?: 'primary' | 'ghost'
  href?: string
  onClick?: () => void
  children: React.ReactNode
}
 
// ✅ 联合类型：让非法状态不可表示
type ButtonProps =
  | {
      as?: 'button'
      variant?: 'primary' | 'ghost'
      onClick?: () => void
      children: React.ReactNode
    }
  | {
      as: 'a'
      variant?: 'primary' | 'ghost'
      href: string
      children: React.ReactNode
    }
 
// TypeScript 会在这里报错：
// Property 'onClick' does not exist on type '{ as: "a"; href: string; ... }'
<Button as="a" href="/submit" onClick={handleClick}>
  提交
</Button>

type ModalProps =
  | {
      variant: 'confirm'
      onConfirm: () => void
      onCancel: () => void
      confirmText?: string
      cancelText?: string
      children: React.ReactNode
    }
  | {
      variant: 'info'
      onClose: () => void
      children: React.ReactNode
    }
 
// ✅ confirm 模式必须传 onConfirm
<Modal variant="confirm" onConfirm={handleDelete} onCancel={handleCancel}>
  确认删除？
</Modal>
 
// ✅ info 模式只需要 onClose
<Modal variant="info" onClose={handleClose}>
  操作成功
</Modal>
 
// ❌ 编译报错：info 模式不需要 onConfirm
<Modal variant="info" onConfirm={handleDelete}>
  操作成功
</Modal>