{"_id":"@bill.gong/lumina-ui","name":"@bill.gong/lumina-ui","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bill.gong/lumina-ui","version":"0.1.0","description":"A lightweight React component library with Material Design style","type":"module","main":"dist/lumina.cjs.js","module":"dist/lumina.es.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/lumina.es.js","require":"./dist/lumina.cjs.js"}},"sideEffects":false,"scripts":{"dev":"storybook dev -p 6006","build":"tsc -p tsconfig.build.json && vite build","build:types":"tsc -p tsconfig.build.json","lint":"eslint src --ext .ts,.tsx","storybook":"storybook dev -p 6006","build-storybook":"storybook build"},"peerDependencies":{"react":">=18.0.0","react-dom":">=18.0.0","styled-components":">=6.0.0"},"devDependencies":{"@storybook/addon-essentials":"^8.5.0","@storybook/react":"^8.5.0","@storybook/react-vite":"^8.5.0","@types/react":"^18.3.0","@types/react-dom":"^18.3.0","@vitejs/plugin-react":"^4.3.0","react":"^18.3.0","react-dom":"^18.3.0","storybook":"^8.5.0","styled-components":"^6.1.0","typescript":"^5.6.0","vite":"^6.1.0","vite-plugin-dts":"^4.5.0"},"keywords":["react","components","ui","material-design","typescript","component-library","styled-components","lumina"],"author":{"name":"kyouseibill"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/kyouseibill/Lumina.git"},"homepage":"https://github.com/kyouseibill/Lumina#readme","bugs":{"url":"https://github.com/kyouseibill/Lumina/issues"},"_id":"@bill.gong/lumina-ui@0.1.0","gitHead":"3780860b5603e1d172de90e020040c770a59a94e","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-meDO7D/C3cR8jmjj+02dc2oG2vm+A/pNfRUVsWYhJN6TuxKhQMo7U+aXLaDkJlOknQyDLT1JGvohn5EXCi4MDA==","shasum":"591b6cb3f5b31333dea1007bc8fe1fba3786f5c8","tarball":"https://registry.npmjs.org/@bill.gong/lumina-ui/-/lumina-ui-0.1.0.tgz","fileCount":291,"unpackedSize":952035,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEUBEJcoFTnILc5aD4SF+F91wzXVxUIxa7IppbJFXCeRAiEA9mnSwEzT6tzjo7IiZ4VU2gNP8umN+fTJ665JZbAPIy8="}]},"_npmUser":{"name":"bill.gong","email":"bill.gong790510@gmail.com"},"directories":{},"maintainers":[{"name":"bill.gong","email":"bill.gong790510@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/lumina-ui_0.1.0_1771036441580_0.12211264679672285"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-14T02:34:01.489Z","0.1.0":"2026-02-14T02:34:01.849Z","modified":"2026-02-14T02:34:02.072Z"},"maintainers":[{"name":"bill.gong","email":"bill.gong790510@gmail.com"}],"description":"A lightweight React component library with Material Design style","homepage":"https://github.com/kyouseibill/Lumina#readme","keywords":["react","components","ui","material-design","typescript","component-library","styled-components","lumina"],"repository":{"type":"git","url":"git+https://github.com/kyouseibill/Lumina.git"},"author":{"name":"kyouseibill"},"bugs":{"url":"https://github.com/kyouseibill/Lumina/issues"},"license":"MIT","readme":"# Lumina UI\r\n\r\n一个轻量级的 React 组件库，采用 Material Design 设计风格，基于 TypeScript + styled-components 构建。\r\n\r\n---\r\n\r\n## 技术栈\r\n\r\n| 技术 | 版本 | 用途 |\r\n|------|------|------|\r\n| React | ≥ 18.0 | UI 框架 |\r\n| TypeScript | 5.6 | 类型安全 |\r\n| styled-components | ≥ 6.0 | CSS-in-JS 样式方案 |\r\n| Vite | 6.x | 构建工具（Library Mode） |\r\n| vite-plugin-dts | 4.5 | 自动生成 `.d.ts` 类型声明 |\r\n| Storybook | 8.5 | 组件文档与交互演示 |\r\n\r\n## 产物规格\r\n\r\n- **ESM** — `dist/lumina.es.js`\r\n- **CJS** — `dist/lumina.cjs.js`\r\n- **类型声明** — `dist/index.d.ts`（含 declarationMap）\r\n- `sideEffects: false`，支持 Tree-shaking\r\n\r\n---\r\n\r\n## 快速开始\r\n\r\n### 安装\r\n\r\n```bash\r\n# 使用 npm\r\nnpm install lumina-ui react react-dom styled-components\r\n\r\n# 使用 pnpm\r\npnpm add lumina-ui react react-dom styled-components\r\n```\r\n\r\n> `react`、`react-dom`、`styled-components` 为 peerDependencies，项目中需自行安装。\r\n\r\n### 基本用法\r\n\r\n```tsx\r\nimport React from 'react';\r\nimport { LuminaProvider, Button, Input } from 'lumina-ui';\r\n\r\nfunction App() {\r\n  return (\r\n    <LuminaProvider>\r\n      <Button color=\"primary\" onClick={() => alert('Hello!')}>\r\n        点击我\r\n      </Button>\r\n      <Input label=\"用户名\" placeholder=\"请输入用户名\" />\r\n    </LuminaProvider>\r\n  );\r\n}\r\n```\r\n\r\n### 自定义主题\r\n\r\n```tsx\r\nimport { LuminaProvider } from 'lumina-ui';\r\n\r\nconst myTheme = {\r\n  colors: {\r\n    primary: {\r\n      light: '#6ec6ff',\r\n      main: '#2196f3',\r\n      dark: '#0069c0',\r\n      contrastText: '#fff',\r\n    },\r\n  },\r\n  borderRadius: {\r\n    sm: '8px',\r\n    md: '12px',\r\n  },\r\n};\r\n\r\nfunction App() {\r\n  return (\r\n    <LuminaProvider theme={myTheme}>\r\n      {/* 传入的主题会与默认主题深度合并 */}\r\n      {/* ... */}\r\n    </LuminaProvider>\r\n  );\r\n}\r\n```\r\n\r\n### Toast 消息提示\r\n\r\nToast 需要额外包裹 `ToastProvider`：\r\n\r\n```tsx\r\nimport { LuminaProvider, ToastProvider, ToastBinder, useToast, Button } from 'lumina-ui';\r\n\r\nfunction Inner() {\r\n  const { addToast } = useToast();\r\n  return <Button onClick={() => addToast('success', '操作成功！')}>提示</Button>;\r\n}\r\n\r\nfunction App() {\r\n  return (\r\n    <LuminaProvider>\r\n      <ToastProvider>\r\n        <Inner />\r\n        <ToastBinder />\r\n      </ToastProvider>\r\n    </LuminaProvider>\r\n  );\r\n}\r\n```\r\n\r\n---\r\n\r\n## 组件总览\r\n\r\n共 **33** 个组件，覆盖通用、数据录入、数据展示、反馈、导航五大类。\r\n\r\n### 通用组件\r\n\r\n| 组件 | 导入名 | 说明 |\r\n|------|--------|------|\r\n| Button | `Button` | 按钮，支持 contained / outlined / text 变体，5 种颜色，3 种尺寸，loading 状态 |\r\n| Divider | `Divider` | 分割线，水平 / 垂直方向，支持带文字分割 |\r\n| Spinner | `Spinner` | 加载指示器，可包裹内容或全屏显示 |\r\n| Tag | `Tag` | 标签，filled / outlined 变体，可关闭 |\r\n\r\n### 数据录入\r\n\r\n| 组件 | 导入名 | 说明 |\r\n|------|--------|------|\r\n| Input | `Input` | 输入框，outlined / filled / standard 变体，浮动标签 |\r\n| Radio | `Radio`, `RadioGroup` | 单选按钮组，Context 管理受控/非受控 |\r\n| Checkbox | `Checkbox` | 复选框，支持 indeterminate 半选状态 |\r\n| Switch | `Switch` | 开关，small / medium 尺寸 |\r\n| Select | `Select` | 下拉选择框，支持搜索过滤、键盘导航 |\r\n| Slider | `Slider` | 滑块选择器，拖拽操作 + tooltip 实时数值 |\r\n| DatePicker | `DatePicker` | 日期选择器，日历面板，支持 min/max 限制 |\r\n| TimePicker | `TimePicker` | 时间选择器，小时/分/秒滚动列 |\r\n| Upload | `Upload` | 文件上传，支持拖拽区域和点击上传 |\r\n| Form | `Form`, `FormItem` | 表单容器，内置校验规则（required / min / max / pattern / 自定义） |\r\n\r\n### 数据展示\r\n\r\n| 组件 | 导入名 | 说明 |\r\n|------|--------|------|\r\n| Table | `Table` | 表格，列定义 + 排序 + striped / bordered 样式 |\r\n| List | `List`, `ListItem`, ... | 列表组件，支持 icon / text / action 插槽 |\r\n| Avatar | `Avatar` | 头像，圆形 / 方形，支持图片 / 文字 / fallback |\r\n| Badge | `Badge` | 徽标数，数字 / 小圆点模式 |\r\n| Card | `Card` | 卡片容器，title / subtitle / cover / actions |\r\n| Collapse | `Collapse` | 折叠面板，支持手风琴模式 |\r\n| Tooltip | `Tooltip` | 文字提示，4 方向定位 |\r\n| Popover | `Popover` | 气泡卡片，click / hover 触发 |\r\n| Skeleton | `Skeleton` | 骨架屏占位，pulse / wave 动画 |\r\n| Progress | `Progress` | 进度条，线性 + 环形，active 动画 |\r\n| ImageViewer | `ImageViewer` | 图片查看器弹层，缩放 / 旋转 / 拖拽 / 导航 / 缩略图 |\r\n\r\n### 反馈\r\n\r\n| 组件 | 导入名 | 说明 |\r\n|------|--------|------|\r\n| Modal | `Modal` | 模态弹窗，Portal 渲染，ESC 关闭，背景滚动锁定 |\r\n| Drawer | `Drawer` | 抽屉面板，4 方向 (left / right / top / bottom) |\r\n| Toast | `useToast`, `Toast.success()` | 消息提示，声明式 + 命令式双模式 |\r\n| Alert | `Alert` | 警告提示条，4 种严重级别，可关闭 |\r\n| Popconfirm | `Popconfirm` | 气泡确认框，确定/取消按钮 |\r\n\r\n### 导航\r\n\r\n| 组件 | 导入名 | 说明 |\r\n|------|--------|------|\r\n| Tabs | `Tabs`, `Tab`, `TabPanel` | 选项卡，滑动指示器动画 |\r\n| Pagination | `Pagination` | 分页器，支持每页条数选择 (`pageSizeOptions`) |\r\n| Breadcrumb | `Breadcrumb` | 面包屑导航，超长路径折叠 |\r\n| Dropdown | `Dropdown` | 下拉菜单，click / hover 触发，支持分割线 + 危险项 |\r\n\r\n---\r\n\r\n## 主题系统\r\n\r\n### 设计令牌 (Design Tokens)\r\n\r\n所有组件通过 `styled-components` 的 `ThemeProvider` 消费统一的主题对象 `LuminaTheme`。\r\n\r\n```typescript\r\ninterface LuminaTheme {\r\n  colors: {\r\n    primary: ColorShade;      // { light, main, dark, contrastText }\r\n    secondary: ColorShade;\r\n    error: ColorShade;\r\n    warning: ColorShade;\r\n    success: ColorShade;\r\n    info: ColorShade;\r\n    grey: { 50 ~ 900 };\r\n    text: { primary, secondary, disabled };\r\n    background: { default, paper };\r\n    divider: string;\r\n    action: { hover, selected, disabled, disabledBackground, focus };\r\n  };\r\n  typography: {\r\n    fontFamily: string;\r\n    fontSize: { xs ~ 3xl };\r\n    fontWeight: { light, regular, medium, semibold, bold };\r\n    lineHeight: { tight, normal, relaxed };\r\n  };\r\n  spacing: (factor: number) => string;   // spacing(2) => '16px'\r\n  borderRadius: { none, sm, md, lg, xl, full };\r\n  elevation: { 0 ~ 24 };                // box-shadow 预设\r\n  transition: { duration, easing };\r\n  breakpoints: { xs ~ xl };\r\n  zIndex: { appBar, drawer, modal, snackbar, tooltip };\r\n}\r\n```\r\n\r\n### 主题定制\r\n\r\n`LuminaProvider` 接受 `Partial<LuminaTheme>`，内部自动与默认主题 **深度合并**，仅需传入需要覆盖的字段：\r\n\r\n```tsx\r\n<LuminaProvider theme={{ colors: { primary: { main: '#ff5722' } } }}>\r\n```\r\n\r\n---\r\n\r\n## 公共 Hooks\r\n\r\n组件库导出了以下可复用 Hooks：\r\n\r\n| Hook | 说明 |\r\n|------|------|\r\n| `useControlled(value, defaultValue, onChange)` | 统一受控/非受控模式管理 |\r\n| `useClickOutside(handler, active?)` | 检测点击元素外部，返回 ref |\r\n| `useKeyboard(handlers)` | 键盘事件快捷绑定 (Enter / Escape / Arrow 等) |\r\n\r\n---\r\n\r\n## 项目结构\r\n\r\n```\r\nLumina/\r\n├── src/\r\n│   ├── index.ts                  # 统一导出入口\r\n│   ├── theme/\r\n│   │   ├── types.ts              # LuminaTheme 类型定义\r\n│   │   ├── defaultTheme.ts       # Material Design 默认主题令牌\r\n│   │   └── index.tsx             # LuminaProvider + useTheme\r\n│   ├── styles/\r\n│   │   ├── reset.ts              # GlobalStyle CSS Reset\r\n│   │   └── mixins.ts             # elevation / transition / focusVisible 等工具\r\n│   ├── hooks/\r\n│   │   ├── useControlled.ts\r\n│   │   ├── useClickOutside.ts\r\n│   │   └── useKeyboard.ts\r\n│   ├── utils/\r\n│   │   └── helpers.ts            # uniqueId / clamp / mergeRefs\r\n│   └── components/\r\n│       ├── Button/               # 每个组件一个目录\r\n│       │   ├── Button.types.ts   # Props 类型定义\r\n│       │   ├── Button.styles.ts  # styled-components 样式\r\n│       │   ├── Button.tsx        # 组件实现\r\n│       │   └── index.ts          # 目录导出\r\n│       ├── Input/\r\n│       ├── ...                   # 其余 31 个组件同构\r\n│       └── Upload/\r\n├── demo/\r\n│   ├── main.tsx                  # Demo 入口\r\n│   └── App.tsx                   # 完整预览页（展示全部 33 个组件）\r\n├── .storybook/\r\n│   ├── main.ts                   # Storybook 配置\r\n│   └── preview.tsx               # 全局装饰器（LuminaProvider 包裹）\r\n├── package.json\r\n├── tsconfig.json                 # 开发用 TS 配置\r\n├── tsconfig.build.json           # 构建用 TS 配置（excludes demo/stories）\r\n├── vite.config.ts                # Vite Library Mode 构建配置\r\n└── index.html                    # Vite dev 入口\r\n```\r\n\r\n### 组件目录约定\r\n\r\n每个组件目录包含 4 个文件，保持一致的结构：\r\n\r\n```\r\nComponentName/\r\n├── ComponentName.types.ts   # Props 接口、类型别名\r\n├── ComponentName.styles.ts  # styled-components 样式组件\r\n├── ComponentName.tsx        # React 组件实现\r\n└── index.ts                 # 导出组件和类型\r\n```\r\n\r\n---\r\n\r\n## 开发指南\r\n\r\n### 环境要求\r\n\r\n- **Node.js** ≥ 18\r\n- **pnpm** ≥ 8（推荐）或 npm ≥ 9\r\n\r\n### 本地开发\r\n\r\n```bash\r\n# 1. 安装依赖\r\npnpm install\r\n\r\n# 2. 启动 Demo 预览（http://localhost:5173）\r\npnpm exec vite\r\n\r\n# 3. 启动 Storybook（http://localhost:6006）\r\npnpm dev\r\n```\r\n\r\n### 构建\r\n\r\n```bash\r\n# 完整构建（类型声明 + 打包）\r\npnpm build\r\n\r\n# 仅生成类型声明\r\npnpm build:types\r\n```\r\n\r\n构建产物输出到 `dist/` 目录：\r\n\r\n```\r\ndist/\r\n├── lumina.es.js       # ESM 格式（~130 KB, gzip ~27 KB）\r\n├── lumina.cjs.js      # CommonJS 格式\r\n├── index.d.ts         # 类型声明入口\r\n└── components/        # 各组件类型声明\r\n```\r\n\r\n### 类型检查\r\n\r\n```bash\r\nnpx tsc --noEmit\r\n```\r\n\r\n### 添加新组件\r\n\r\n1. 在 `src/components/` 下新建组件目录，包含 4 个文件：\r\n\r\n```bash\r\nsrc/components/MyComponent/\r\n├── MyComponent.types.ts\r\n├── MyComponent.styles.ts\r\n├── MyComponent.tsx\r\n└── index.ts\r\n```\r\n\r\n2. **types.ts** — 定义 Props 接口：\r\n\r\n```typescript\r\nimport React from 'react';\r\n\r\nexport interface MyComponentProps {\r\n  /** 属性说明 */\r\n  label: string;\r\n  children?: React.ReactNode;\r\n}\r\n```\r\n\r\n3. **styles.ts** — 编写样式组件，从 `theme` 获取设计令牌：\r\n\r\n```typescript\r\nimport styled from 'styled-components';\r\n\r\nexport const Root = styled.div`\r\n  padding: ${({ theme }) => theme.spacing(2)};\r\n  border-radius: ${({ theme }) => theme.borderRadius.md};\r\n  color: ${({ theme }) => theme.colors.text.primary};\r\n`;\r\n```\r\n\r\n4. **Component.tsx** — 实现组件逻辑：\r\n\r\n```tsx\r\nimport React from 'react';\r\nimport type { MyComponentProps } from './MyComponent.types';\r\nimport { Root } from './MyComponent.styles';\r\n\r\nexport const MyComponent: React.FC<MyComponentProps> = ({ label, children }) => (\r\n  <Root>{label}{children}</Root>\r\n);\r\n\r\nMyComponent.displayName = 'MyComponent';\r\n```\r\n\r\n5. **index.ts** — 导出：\r\n\r\n```typescript\r\nexport { MyComponent } from './MyComponent';\r\nexport type { MyComponentProps } from './MyComponent.types';\r\n```\r\n\r\n6. 在 `src/index.ts` 中添加导出：\r\n\r\n```typescript\r\nexport { MyComponent } from './components/MyComponent';\r\nexport type { MyComponentProps } from './components/MyComponent';\r\n```\r\n\r\n7. 运行 `npx tsc --noEmit` 确认无类型错误。\r\n\r\n### 开发规范\r\n\r\n- **受控/非受控**：使用 `useControlled` hook 统一管理\r\n- **样式**：全部通过 `styled-components` 编写，使用 `$` 前缀标记 transient props（不传递到 DOM）\r\n- **主题变量**：禁止硬编码颜色/间距/圆角等值，一律从 `theme` 对象读取\r\n- **类型安全**：所有 Props 必须有 TypeScript 接口定义，导出供外部使用\r\n- **displayName**：每个组件必须设置 `displayName`，便于 React DevTools 调试\r\n- **无障碍**：为交互组件添加 `role`、`aria-*` 属性\r\n\r\n### 已知 TypeScript 注意事项\r\n\r\n- `useClickOutside` 返回 `RefObject<T | null>`，传递给 styled-components 时需要类型断言：\r\n  ```typescript\r\n  const ref = useClickOutside<HTMLDivElement>(() => {}) as React.RefObject<HTMLDivElement>;\r\n  ```\r\n- 主题深度合并时使用 `as unknown as` 双重断言以绕过严格类型检查\r\n\r\n---\r\n\r\n## 构建配置\r\n\r\n### Vite Library Mode\r\n\r\n- 入口：`src/index.ts`\r\n- 输出格式：ESM + CJS\r\n- 外部依赖（不打包）：`react`、`react-dom`、`react/jsx-runtime`、`styled-components`\r\n- Source Map：启用\r\n\r\n### TypeScript\r\n\r\n- 严格模式 (`strict: true`)\r\n- JSX 转换：`react-jsx`（新版自动导入，不需要 `import React`）\r\n- `declarationMap: true`，支持 \"Go to Definition\" 跳转到源码\r\n\r\n---\r\n\r\n## Scripts 速查\r\n\r\n| 命令 | 说明 |\r\n|------|------|\r\n| `pnpm exec vite` | 启动 Demo 开发服务器 (5173) |\r\n| `pnpm dev` | 启动 Storybook (6006) |\r\n| `pnpm build` | 完整构建（类型 + 打包） |\r\n| `pnpm build:types` | 仅生成类型声明 |\r\n| `pnpm build-storybook` | 构建 Storybook 静态站点 |\r\n| `npx tsc --noEmit` | 类型检查 |\r\n\r\n---\r\n\r\n## 许可证\r\n\r\n[MIT](LICENSE)\r\n","readmeFilename":"README.md","_rev":"1-a107f5e53a4f3dc1ad9d57f2d8b04e92"}