Instruction file imported from chunrichi/dingshi (.github/instructions/component.instructions.md). Copyright stays with the author.

Reusable Component Rules

复用组件清单

以下组件来自设计文档 ui-design.md，每个组件一个独立文件：

核心组件

图表组件

装饰组件

组件规范

• 无状态组件：所有复用组件不可依赖 ViewModel，仅通过 Composable 参数接收数据
• 单一职责：一个文件只包含一个公开 Composable，其余用 private 修饰
• Modifier 参数：每个公开 Composable 必须接收 modifier: Modifier = Modifier 参数
• 预览：每个组件至少一个 @Preview 预览函数

数据契约

HeroCard

@Composable
fun HeroCard(
    title: String,           // 标题（如"本月预计"）
    amount: String,          // 金额文本
    subtitle: String? = null, // 副标题（如"↓12% vs 上月"）
    gradientColors: List<Color>? = null, // 渐变装饰色
    modifier: Modifier = Modifier
)

SubscriptionCard

@Composable
fun SubscriptionCard(
    subscription: SubscriptionUiModel, // 非 Entity，是 UI 专用 data class
    mode: SubscriptionCardMode,        // LIST / HORIZONTAL
    onClick: () -> Unit,
    modifier: Modifier = Modifier
)

MoneyText

@Composable
fun MoneyText(
    amount: Double,
    currencyCode: String,
    showBaseConverted: Boolean = true, // 是否显示主币种换算小字
    modifier: Modifier = Modifier
)

EmptyState

@Composable
fun EmptyState(
    title: String,
    subtitle: String? = null,
    actionLabel: String? = null,
    onAction: (() -> Unit)? = null,
    modifier: Modifier = Modifier
)

ConfirmDialog

@Composable
fun ConfirmDialog(
    title: String,
    message: String,
    confirmLabel: String = "确认",
    dismissLabel: String = "取消",
    onConfirm: () -> Unit,
    onDismiss: () -> Unit
)

DonutChart

@Composable
fun DonutChart(
    data: List<ChartEntry>,  // 分类数据
    modifier: Modifier = Modifier,
    centerContent: @Composable () -> Unit = {} // 中心内容（可选）
)

data class ChartEntry(
    val label: String,
    val value: Float,
    val color: Color
)

禁止做法

• 不在 ui/component/ 外定义这些组件
• 组件中不可包含导航逻辑（navController.navigate()）
• 组件中不可访问 ViewModel 或 Repository