@youwen/ai-design-system

/** * 企业级组件库统一类型系统 * 整合设计Token、组件规格、验证和AI生成的完整类型定义 */ /// <reference types="react" /> /** 主题变体 */ export type ThemeVariant = 'light' | 'dark'; /** 品牌色系 */ export type BrandColor = 'primary' | 'secondary' | 'accent' | 'warning'; /** 组件尺寸系统 */ export type ComponentSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'; /** 组件变体系统 */ export type ComponentVariant = 'default' | 'outline' | 'ghost' | 'link' | 'destructive' | 'secondary' | 'success' | 'warning' | 'info'; /** 响应式断点 */ export type ResponsiveBreakpoint = 'mobile' | 'tablet' | 'desktop' | 'wide'; /** 组件家族分类 */ export type ComponentFamily = 'radix' | 'widget' | 'composite' | 'custom'; /** 组件状态 */ export type ComponentState = 'idle' | 'loading' | 'success' | 'error' | 'warning'; /** 设计Token层级 */ export type TokenLayer = 'foundation' | 'semantic' | 'component'; /** 颜色Token接口 */ export interface ColorToken { /** Token名称 */ name: string; /** 十六进制值 */ hex: string; /** RGB值 */ rgb: { r: number; g: number; b: number; }; /** HSL值 */ hsl: { h: number; s: number; l: number; }; /** OKLCH值 (现代色彩空间) */ oklch?: { l: number; c: number; h: number; }; /** 对比度等级 */ contrast: 'AAA' | 'AA' | 'A' | 'fail'; /** 用途描述 */ purpose: string[]; } /** 字体Token接口 */ export interface TypographyToken { /** 字体家族 */ fontFamily: string; /** 字体大小 */ fontSize: string; /** 字体重量 */ fontWeight: number | string; /** 行高 */ lineHeight: string | number; /** 字符间距 */ letterSpacing?: string; /** 用途标识 */ usage: 'display' | 'heading' | 'body' | 'caption' | 'label' | 'code'; /** 响应式配置 */ responsive?: Record<ResponsiveBreakpoint, Partial<TypographyToken>>; } /** 间距Token接口 */ export interface SpacingToken { /** Token标识 */ key: string; /** 像素值 */ value: number; /** rem值 */ rem: string; /** 用途类型 */ type: 'margin' | 'padding' | 'gap' | 'border-radius' | 'border-width'; /** 使用场景 */ context: string[]; } /** 阴影Token接口 */ export interface ShadowToken { /** 名称 */ name: string; /** CSS阴影值 */ value: string; /** 阴影层级 */ elevation: number; /** 使用场景 */ usage: 'card' | 'modal' | 'dropdown' | 'button' | 'input'; } /** 动画Token接口 */ export interface AnimationToken { /** 动画名称 */ name: string; /** 持续时间 */ duration: string; /** 缓动函数 */ easing: string; /** 延迟时间 */ delay?: string; /** 使用场景 */ context: 'enter' | 'exit' | 'hover' | 'focus' | 'loading'; } /** 完整设计Token集合 */ export interface DesignTokenCollection { colors: Record<string, ColorToken>; typography: Record<string, TypographyToken>; spacing: Record<string, SpacingToken>; shadows: Record<string, ShadowToken>; animations: Record<string, AnimationToken>; breakpoints: Record<ResponsiveBreakpoint, string>; zIndex: Record<string, number>; } /** 可访问性配置 */ export interface AccessibilitySpec { /** ARIA标签 */ 'aria-label'?: string; /** ARIA描述 */ 'aria-describedby'?: string; /** ARIA标签引用 */ 'aria-labelledby'?: string; /** 展开状态 */ 'aria-expanded'?: boolean; /** 隐藏状态 */ 'aria-hidden'?: boolean; /** 禁用状态 */ 'aria-disabled'?: boolean; /** 选中状态 */ 'aria-selected'?: boolean; /** 必填标识 */ 'aria-required'?: boolean; /** 角色定义 */ role?: string; /** Tab键顺序 */ tabIndex?: number; /** 键盘导航支持 */ keyboardNavigation?: boolean; /** 屏幕阅读器支持 */ screenReaderSupport?: boolean; } /** 样式配置 */ export interface StylingSpec { /** 主题模式 */ theme: ThemeVariant; /** 品牌色 */ brandColor: BrandColor; /** 自定义样式 */ customStyles?: Record<string, string>; /** CSS类名 */ className?: string; /** 内联样式 */ inlineStyles?: React.CSSProperties; /** 应用的Token引用 */ appliedTokens?: string[]; } /** 响应式配置 */ export interface ResponsiveSpec { /** 移动端配置 */ mobile?: { size?: ComponentSize; variant?: ComponentVariant; styling?: Partial<StylingSpec>; hidden?: boolean; }; /** 平板配置 */ tablet?: { size?: ComponentSize; variant?: ComponentVariant; styling?: Partial<StylingSpec>; hidden?: boolean; }; /** 桌面配置 */ desktop?: { size?: ComponentSize; variant?: ComponentVariant; styling?: Partial<StylingSpec>; hidden?: boolean; }; /** 超宽屏配置 */ wide?: { size?: ComponentSize; variant?: ComponentVariant; styling?: Partial<StylingSpec>; hidden?: boolean; }; } /** 交互配置 */ export interface InteractionSpec { /** 点击事件 */ onClick?: (event: React.MouseEvent) => void; /** 变化事件 */ onChange?: (value: any) => void; /** 焦点事件 */ onFocus?: (event: React.FocusEvent) => void; /** 失焦事件 */ onBlur?: (event: React.FocusEvent) => void; /** 键盘事件 */ onKeyDown?: (event: React.KeyboardEvent) => void; /** 鼠标进入 */ onMouseEnter?: (event: React.MouseEvent) => void; /** 鼠标离开 */ onMouseLeave?: (event: React.MouseEvent) => void; /** 拖拽开始 */ onDragStart?: (event: React.DragEvent) => void; /** 拖拽结束 */ onDragEnd?: (event: React.DragEvent) => void; } /** 业务逻辑配置 */ export interface BusinessLogicSpec { /** 验证规则 */ validation?: { required?: boolean; pattern?: RegExp; minLength?: number; maxLength?: number; min?: number; max?: number; custom?: (value: any) => boolean | string; }; /** 数据转换 */ transform?: { input?: (value: any) => any; output?: (value: any) => any; }; /** 状态管理 */ state?: { initialValue?: any; persistent?: boolean; reset?: () => void; }; /** 权限控制 */ permissions?: { view?: boolean; edit?: boolean; delete?: boolean; admin?: boolean; }; } /** 完整组件规格 */ export interface ComponentSpec { /** 组件家族 */ componentFamily: ComponentFamily; /** 组件类型 */ componentType: string; /** 组件变体 */ variant?: ComponentVariant; /** 组件尺寸 */ size?: ComponentSize; /** 组件状态 */ state?: ComponentState; /** 组件属性 */ props: Record<string, any>; /** 子组件或内容 */ children?: string | ComponentSpec[]; /** 样式配置 */ styling: StylingSpec; /** 可访问性配置 */ accessibility: AccessibilitySpec; /** 响应式配置 */ responsive?: ResponsiveSpec; /** 交互配置 */ interaction?: InteractionSpec; /** 业务逻辑 */ businessLogic?: BusinessLogicSpec; /** 元数据 */ metadata?: { id?: string; name?: string; description?: string; tags?: string[]; version?: string; author?: string; created?: Date; modified?: Date; }; } /** 验证严重级别 */ export type ValidationSeverity = 'error' | 'warning' | 'info' | 'success'; /** 验证层级 */ export type ValidationLayer = 'token-schema' | 'design-rules' | 'component-compatibility' | 'accessibility' | 'performance' | 'business-logic' | 'security'; /** 验证错误接口 */ export interface ValidationError { /** 错误ID */ id: string; /** 验证层级 */ layer: ValidationLayer; /** 错误字段 */ field: string; /** 错误信息 */ message: string; /** 严重级别 */ severity: ValidationSeverity; /** 错误代码 */ code: string; /** 建议修复方案 */ suggestion?: string; /** 自动修复可能性 */ autoFixable: boolean; /** 相关文档链接 */ docUrl?: string; /** 错误上下文 */ context?: Record<string, any>; } /** 验证警告接口 */ export interface ValidationWarning { /** 警告ID */ id: string; /** 验证层级 */ layer: ValidationLayer; /** 警告信息 */ message: string; /** 影响级别 */ impact: 'low' | 'medium' | 'high'; /** 建议 */ recommendation: string; /** 忽略选项 */ ignorable: boolean; } /** 性能指标接口 */ export interface PerformanceMetrics { /** Bundle大小影响 */ bundleImpact: { /** 增加的KB数 */ sizeKB: number; /** 相对增长百分比 */ percentage: number; /** 对主Bundle的影响 */ mainBundleImpact: 'minimal' | 'moderate' | 'significant'; }; /** 渲染性能 */ renderComplexity: { /** 复杂度等级 */ level: 'low' | 'medium' | 'high' | 'very-high'; /** DOM节点数估算 */ estimatedNodes: number; /** 重渲染风险 */ reRenderRisk: 'low' | 'medium' | 'high'; }; /** 内存使用 */ memoryUsage: { /** 预估内存使用KB */ estimatedKB: number; /** 内存泄漏风险 */ leakRisk: 'low' | 'medium' | 'high'; }; /** 网络影响 */ networkImpact: { /** 额外请求数 */ additionalRequests: number; /** 缓存友好度 */ cacheability: 'excellent' | 'good' | 'fair' | 'poor'; }; } /** 可访问性报告接口 */ export interface AccessibilityReport { /** WCAG合规等级 */ wcagCompliance: { /** 等级 */ level: 'AAA' | 'AA' | 'A' | 'fail'; /** 合规分数 */ score: number; /** 通过的规则数 */ passedRules: number; /** 总规则数 */ totalRules: number; }; /** 可访问性问题 */ issues: Array<{ /** 问题类型 */ type: 'contrast' | 'keyboard' | 'screen-reader' | 'structure' | 'content'; /** 严重性 */ severity: 'critical' | 'serious' | 'moderate' | 'minor'; /** 问题描述 */ description: string; /** 修复建议 */ fix: string; /** WCAG准则引用 */ wcagCriteria: string; }>; /** 建议改进 */ recommendations: string[]; /** 测试覆盖 */ testCoverage: { /** 键盘导航测试 */ keyboardNavigation: boolean; /** 屏幕阅读器测试 */ screenReader: boolean; /** 对比度测试 */ colorContrast: boolean; /** 焦点管理测试 */ focusManagement: boolean; }; } /** 完整验证结果 */ export interface ValidationResult { /** 验证是否通过 */ isValid: boolean; /** 总体评分(0-100) */ score: number; /** 验证层级结果 */ layerResults: Record<ValidationLayer, { passed: boolean; score: number; errors: ValidationError[]; warnings: ValidationWarning[]; }>; /** 性能指标 */ performance: PerformanceMetrics; /** 可访问性报告 */ accessibility: AccessibilityReport; /** 总体建议 */ recommendations: string[]; /** 验证元数据 */ metadata: { /** 验证时间 */ timestamp: Date; /** 验证版本 */ validatorVersion: string; /** 验证耗时ms */ duration: number; /** 环境信息 */ environment: string; }; } /** AI分析上下文 */ export interface AIAnalysisContext { /** 业务领域 */ domain: 'dashboard' | 'form' | 'navigation' | 'data-display' | 'feedback' | 'general'; /** 置信度 */ confidence: number; /** 识别的关键词 */ keywords: string[]; /** 用户意图 */ intent: { primary: 'create' | 'modify' | 'style' | 'layout' | 'interact'; secondary: string[]; }; /** 复杂度评估 */ complexity: 'simple' | 'moderate' | 'complex' | 'very-complex'; } /** AI生成结果 */ export interface AIGenerationResult { /** 组件规格 */ component: ComponentSpec; /** AI置信度 */ confidence: number; /** AI推理过程 */ reasoning: string; /** 分析上下文 */ context: AIAnalysisContext; /** 备选方案 */ alternatives: ComponentSpec[]; /** 代码模板 */ codeTemplate: { /** TSX代码 */ tsx: string; /** 导入语句 */ imports: string[]; /** 样式代码 */ styles?: string; /** 类型定义 */ types?: string; }; /** 验证提示 */ validationHints: string[]; /** 优化建议 */ optimizationSuggestions: string[]; /** 生成元数据 */ metadata: { /** 生成时间 */ generatedAt: Date; /** AI模型版本 */ modelVersion: string; /** 用户输入 */ userInput: string; /** 处理耗时 */ processingTime: number; }; } /** 代码生成配置 */ export interface CodeGenerationOptions { /** TypeScript支持 */ typescript: boolean; /** 测试框架 */ testFramework: 'jest' | 'vitest' | 'none'; /** Storybook支持 */ storybook: boolean; /** CSS框架 */ cssFramework: 'tailwind' | 'styled-components' | 'css-modules' | 'vanilla'; /** 代码风格 */ codeStyle: { /** 缩进类型 */ indent: 'spaces' | 'tabs'; /** 缩进大小 */ indentSize: number; /** 分号使用 */ semicolons: boolean; /** 引号类型 */ quotes: 'single' | 'double'; /** 尾逗号 */ trailingComma: boolean; }; /** 企业标准 */ enterpriseStandards: { /** 代码审查标准 */ codeReview: boolean; /** 安全标准 */ security: boolean; /** 性能标准 */ performance: boolean; /** 可访问性标准 */ accessibility: boolean; }; /** 文档生成 */ documentation: { /** JSDoc注释 */ jsdoc: boolean; /** README生成 */ readme: boolean; /** 用法示例 */ examples: boolean; }; } /** 生成的代码文件 */ export interface GeneratedCodeFile { /** 文件名 */ name: string; /** 文件内容 */ content: string; /** 文件类型 */ type: 'component' | 'types' | 'styles' | 'test' | 'story' | 'config' | 'docs'; /** 文件路径 */ path: string; /** 文件大小(字节) */ size: number; /** 代码行数 */ lines: number; } /** 完整代码包 */ export interface GeneratedCodePackage { /** 生成的文件 */ files: GeneratedCodeFile[]; /** 主组件代码 */ componentCode: string; /** 依赖清单 */ dependencies: { /** 生产依赖 */ production: string[]; /** 开发依赖 */ development: string[]; /** 同级依赖 */ peer: string[]; }; /** 构建说明 */ buildInstructions: string[]; /** 使用示例 */ usageExamples: string[]; /** 代码质量评分 */ qualityScore: number; /** 代码包元数据 */ metadata: { /** 生成时间 */ generatedAt: Date; /** 生成器版本 */ generatorVersion: string; /** 配置快照 */ options: CodeGenerationOptions; /** 总文件大小KB */ totalSizeKB: number; /** 总代码行数 */ totalLines: number; }; } /** 工作流状态 */ export type WorkflowState = 'idle' | 'analyzing' | 'generating' | 'validating' | 'optimizing' | 'completed' | 'failed'; /** 工作流步骤 */ export interface WorkflowStep { /** 步骤ID */ id: string; /** 步骤名称 */ name: string; /** 步骤状态 */ status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped'; /** 开始时间 */ startTime?: Date; /** 结束时间 */ endTime?: Date; /** 错误信息 */ error?: string; /** 步骤结果 */ result?: any; /** 进度百分比 */ progress: number; } /** 完整工作流结果 */ export interface WorkflowResult { /** 执行成功 */ success: boolean; /** AI分析结果 */ aiAnalysis: AIGenerationResult; /** 最终组件规格 */ componentSpec: ComponentSpec; /** 验证结果 */ validation: ValidationResult; /** 代码包 */ codePackage: GeneratedCodePackage; /** 优化建议 */ optimization: { score: number; suggestions: string[]; metrics: PerformanceMetrics; }; /** 工作流元数据 */ metadata: { /** 执行ID */ executionId: string; /** 执行开始时间 */ startTime: Date; /** 执行结束时间 */ endTime: Date; /** 总耗时ms */ duration: number; /** 工作流版本 */ workflowVersion: string; /** 执行环境 */ environment: string; /** 用户输入 */ userInput: string; /** 组件名称 */ componentName: string; /** 尝试次数 */ attempts: number; /** 自动修复次数 */ autoFixes: number; }; } /** 深度合并类型 */ export type DeepMerge<T, U> = { [K in keyof (T & U)]: K extends keyof U ? K extends keyof T ? T[K] extends object ? U[K] extends object ? DeepMerge<T[K], U[K]> : U[K] : U[K] : U[K] : K extends keyof T ? T[K] : never; }; /** 部分必需类型 */ export type PartialRequired<T, K extends keyof T> = Partial<T> & Required<Pick<T, K>>; /** 深度只读类型 */ export type DeepReadonly<T> = { readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P]; }; /** 可选链类型 */ export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>; /** 枚举值类型 */ export type EnumValues<T> = T[keyof T]; /** 函数参数类型提取 */ export type ExtractParams<T> = T extends (...args: infer P) => any ? P : never; /** 函数返回值类型提取 */ export type ExtractReturn<T> = T extends (...args: any[]) => infer R ? R : never; /** 数组元素类型提取 */ export type ArrayElement<T> = T extends (infer U)[] ? U : never; /** Promise解析类型提取 */ export type Awaited<T> = T extends Promise<infer U> ? U : T; /** 类型系统版本 */ export declare const TYPE_SYSTEM_VERSION = "2.0.0"; /** 类型系统元数据 */ export declare const TYPE_SYSTEM_METADATA: { readonly version: "2.0.0"; readonly lastUpdated: "2024-06-21"; readonly description: "企业级AI驱动组件库类型系统"; readonly features: readonly ["完整的设计Token类型定义", "企业级组件规格类型", "多层验证类型系统", "AI生成结果类型", "代码生成配置类型", "工作流管理类型", "工具类型支持"]; readonly compatibility: { readonly typescript: ">=4.9.0"; readonly react: ">=18.0.0"; readonly node: ">=16.0.0"; }; };