cmzya-modern-ui

CmzYa Modern UI

面向 Vue 3 的轻量级组件库，提供 25 个组件、TypeScript 声明、亮色、暗色与系统主题、CSS 变量、毛玻璃效果和全局动画控制。

环境要求

• Node.js 18.18 或更高版本
• pnpm 9 或更高版本
• Vue 3.5 或更高版本
• lucide-vue-next 0.400 或更高版本

安装

pnpm add cmzya-modern-ui lucide-vue-next

使用

<script setup lang="ts">
import { Cmz_Button, Cmz_Card } from "cmzya-modern-ui";
import "cmzya-modern-ui/style.css";
</script>

<template>
  <Cmz_Card title="示例">
    <Cmz_Button>确认</Cmz_Button>
  </Cmz_Card>
</template>

组件代码和样式作为独立产物发布。使用组件时需在应用入口显式导入一次 cmzya-modern-ui/style.css；该路径同时包含组件样式和 --cmz-* 设计变量，适用于 ESM、CommonJS 及支持包导出映射的构建工具。已有按此路径导入样式的项目无需调整。

主题与 CSS

组件样式由 --cmz-* 自定义属性驱动，可在应用样式中覆盖。主题和效果通过根元素属性控制：

<html data-theme="dark" data-acrylic="off" data-animation="off">

• data-theme="light" 和 data-theme="dark" 分别启用亮色与暗色主题，data-theme="system" 跟随系统偏好。
• data-acrylic="off" 关闭毛玻璃并降级为纯色背景。
• data-animation="off" 关闭组件过渡和关键帧动画。

:root {
  --cmz-primary: #2563eb;
  --cmz-radius-md: 12px;
  --cmz-font-sans: system-ui, sans-serif;
}

完整组件 API 和 CSS 变量说明见 ui库.md。

行为说明

• Cmz_Select 的 maxHeight 与 dropdownWidth 接受任意有效 CSS 长度，例如 50vh、20rem 和 min(90vw, 32rem)，组件不会将其强制转换为像素。
• Cmz_Select 与 Cmz_Field 在 Cmz_FormField 内使用时，会合并并去重组件自身的 ariaDescribedby 与容器提供的提示或错误描述 ID。
• Cmz_Input 及 Cmz_Field 的文本、数字变体会将 required 接入原生表单校验。
• Cmz_Markdown 始终将原始 HTML 按文本处理；sanitized 仅作为兼容属性保留。
• Cmz_Modal 显示期间动态修改 autoClose 会从修改时重新计时，设为 0 会取消当前自动关闭计时。
• Cmz_ColorPicker 的 modelValue 统一规范化为小写 #rrggbb；presetColors 传空数组可隐藏预设色板，面板中的 HEX 输入框输入非法值会自动回退到当前颜色。
• Cmz_Field 的 select 变体内部渲染 Cmz_Select，因此继承搜索、加载态和 Teleport 定位等全部下拉能力。
• Cmz_Toast 进出场方向跟随 position（顶部位置上顶入上顶出，底部位置下顶入下顶出）；useToast({ defaultDuration }) 设置默认自动关闭时长，显式传 0 仍为常驻。
• Cmz_Console 支持解析行首裸时间（如 23:41:21 [main] [INFO] ...），后续方括号标签照常识别，ANSI 残留码清理不误伤 [main] 这类普通括号。
• 动效规范：全库只使用平滑过渡曲线，回弹/过冲曲线由回归测试强制拦截；交互位移量走 --cmz-btn-hover-lift / --cmz-card-hover-lift / --cmz-toast-slide-distance 变量。

开发

pnpm install
pnpm dev

质量检查

pnpm check
pnpm build
pnpm verify:package
pnpm pack --dry-run

• pnpm check 依次执行 ESLint、类型检查和测试。
• pnpm build 生成 ESM、CommonJS、CSS 和 TypeScript 声明。
• pnpm verify:package 检查文件、外部依赖及 ESM/CommonJS 入口。
• pnpm pack --dry-run 展示 npm 包实际包含的文件。

发布产物

• dist/cmzya.es.js：ESM 入口
• dist/cmzya.cjs：CommonJS 入口
• dist/style.css：组件样式和设计变量
• dist/types/index.d.ts：TypeScript 声明入口

Vue 与 lucide-vue-next 作为 peer dependency 和构建 external，不会打入 JavaScript 产物。

License

MIT