@bm-fe/icons 0.1.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0-beta.0] - 2024-01-XX
+
+### Added
+
+- 初始版本
+- SVG 源文件管理
+- React 适配层
+- 自动生成器脚本
+- Manifest 生成系统
+- IconBase 基座组件
+
+### Changed
+
+- 移除 Vue2/Vue3 适配层，仅保留 React 适配层
+

package/README.md

@@ -0,0 +1,353 @@
+# @bm-fe/icons
+
+BitMart 图标库，提供 SVG 源文件和框架适配层。
+
+## 特性
+
+- 🎨 **SVG 单一事实源**：所有图标源文件统一管理
+- ⚛️ **React 组件**：开箱即用的 React 适配层
+- 🟢 **Vue 支持**：通过 unplugin-icons / vite-svg-loader 引入
+- 🚀 **自动生成**：组件通过生成器自动生成，禁止手改
+- 📦 **类型安全**：完整的 TypeScript 类型定义
+- 🎯 **语义稳定**：图标 API 长期稳定，设计变更不影响业务代码
+- 🖼️ **PNG 优化**：国旗图标自动压缩，节省 67%+ 空间
+
+## 安装
+
+```bash
+pnpm add @bm-fe/icons
+```
+
+## React 使用
+
+直接导入生成的 React 组件：
+
+```tsx
+import { Add, Close, ArrowUp } from '@bm-fe/icons';
+// 或者
+import { Add, Close, ArrowUp } from '@bm-fe/icons/react';
+
+function App() {
+  return (
+    <div>
+      <Add size={16} />
+      <Close size={20} />
+      <ArrowUp size="1.25em" />
+    </div>
+  );
+}
+```
+
+### React 组件 Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `size` | `number \| string` | `24` | 图标尺寸 |
+| `className` | `string` | - | 自定义类名 |
+| `style` | `CSSProperties` | - | 自定义样式 |
+
+## Vue 使用
+
+### 方式一：unplugin-icons（推荐）
+
+[unplugin-icons](https://github.com/unplugin/unplugin-icons) 支持 Vue 2、Vue 3、Vite、Webpack 等多种构建工具。
+
+**1. 安装依赖**
+
+```bash
+pnpm add -D unplugin-icons unplugin-vue-components
+```
+
+**2. 配置 Vite（Vue 3）**
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import Icons from 'unplugin-icons/vite';
+import { FileSystemIconLoader } from 'unplugin-icons/loaders';
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    Icons({
+      compiler: 'vue3',
+      customCollections: {
+        // 自定义 bm 图标集合，指向 @bm-fe/icons 的 SVG 目录
+        bm: FileSystemIconLoader(
+          './node_modules/@bm-fe/icons/svg/primary',
+          (svg) => svg.replace(/^<svg /, '<svg fill="currentColor" ')
+        ),
+        'bm-product': FileSystemIconLoader(
+          './node_modules/@bm-fe/icons/svg/product'
+        ),
+        'bm-coin': FileSystemIconLoader(
+          './node_modules/@bm-fe/icons/svg/coin'
+        ),
+      },
+    }),
+  ],
+});
+```
+
+**3. 配置 Vue 2 / Nuxt 2（Webpack）**
+
+```js
+// nuxt.config.js 或 vue.config.js
+const Icons = require('unplugin-icons/webpack');
+const { FileSystemIconLoader } = require('unplugin-icons/loaders');
+
+module.exports = {
+  configureWebpack: {
+    plugins: [
+      Icons({
+        compiler: 'vue2',
+        customCollections: {
+          bm: FileSystemIconLoader(
+            './node_modules/@bm-fe/icons/svg/primary',
+            (svg) => svg.replace(/^<svg /, '<svg fill="currentColor" ')
+          ),
+        },
+      }),
+    ],
+  },
+};
+```
+
+**4. 在组件中使用**
+
+```vue
+<template>
+  <div>
+    <!-- 自动导入方式 -->
+    <IBmAdd class="w-6 h-6 text-blue-500" />
+    <IBmClose class="w-4 h-4" />
+    
+    <!-- 显式导入方式 -->
+    <AddIcon class="w-6 h-6" />
+  </div>
+</template>
+
+<script setup>
+// 显式导入（可选）
+import AddIcon from '~icons/bm/add';
+</script>
+```
+
+**命名规则：** `I` + `集合名（首字母大写）` + `图标名（PascalCase）`
+- `svg/primary/add.svg` → `<IBmAdd />`
+- `svg/product/google.svg` → `<IBmProductGoogle />`
+
+### 方式二：vite-svg-loader
+
+仅支持 Vite 项目，更轻量但功能较少。
+
+**1. 安装**
+
+```bash
+pnpm add -D vite-svg-loader
+```
+
+**2. 配置 Vite**
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import svgLoader from 'vite-svg-loader';
+
+export default defineConfig({
+  plugins: [vue(), svgLoader()],
+  resolve: {
+    alias: {
+      '@icons': './node_modules/@bm-fe/icons/svg',
+    },
+  },
+});
+```
+
+**3. 使用**
+
+```vue
+<template>
+  <AddIcon class="w-6 h-6 text-current" />
+</template>
+
+<script setup>
+import AddIcon from '@icons/primary/add.svg?component';
+</script>
+```
+
+### 路径别名配置
+
+推荐在项目中配置 `@icons` 别名：
+
+**Vite:**
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@icons': './node_modules/@bm-fe/icons/svg',
+    },
+  },
+});
+```
+
+**Webpack / Vue CLI:**
+
+```js
+// vue.config.js
+const path = require('path');
+
+module.exports = {
+  configureWebpack: {
+    resolve: {
+      alias: {
+        '@icons': path.resolve(__dirname, 'node_modules/@bm-fe/icons/svg'),
+      },
+    },
+  },
+};
+```
+
+## PNG 国旗使用
+
+国旗图标为 PNG 格式，不包装为组件，直接作为静态资源使用。
+
+### 目录说明
+
+| 目录 | 说明 |
+|------|------|
+| `svg/flags/` | 原始 PNG 文件 |
+| `dist/flags/` | 压缩后的 PNG 文件（构建时生成，体积减少 67%+） |
+
+**生产环境建议使用 `dist/flags/` 目录下的压缩文件。**
+
+### 静态导入
+
+```vue
+<template>
+  <img :src="cnFlag" alt="China" class="w-6 h-4" />
+</template>
+
+<script setup>
+// 开发环境（原始文件）
+import cnFlag from '@bm-fe/icons/svg/flags/cn.png';
+
+// 生产环境（压缩文件，需配置构建）
+// import cnFlag from '@bm-fe/icons/dist/flags/cn.png';
+</script>
+```
+
+### 动态导入（Vite）
+
+```ts
+// 批量导入所有国旗
+const flagModules = import.meta.glob('@bm-fe/icons/svg/flags/*.png', {
+  eager: true,
+  import: 'default',
+});
+
+// 获取特定国旗
+function getFlagUrl(countryCode: string): string {
+  const key = `/node_modules/@bm-fe/icons/svg/flags/${countryCode}.png`;
+  return flagModules[key] as string;
+}
+
+// 使用
+const cnFlagUrl = getFlagUrl('cn');
+```
+
+### 动态导入（Webpack）
+
+```js
+// 使用 require.context
+const flagContext = require.context(
+  '@bm-fe/icons/svg/flags',
+  false,
+  /\.png$/
+);
+
+function getFlagUrl(countryCode) {
+  return flagContext(`./${countryCode}.png`);
+}
+```
+
+## 图标分类
+
+| 分类 | 目录 | 颜色策略 | 说明 |
+|------|------|----------|------|
+| **Primary** | `svg/primary/` | `currentColor` | 基础 UI 图标，支持颜色继承 |
+| **Product** | `svg/product/` | `currentColor` | 产品图标，支持颜色继承 |
+| **Coin** | `svg/coin/` | 固定色 | 币种图标，保持原始颜色 |
+| **Currency** | `svg/currency/` | 固定色 | 货币符号，保持原始颜色 |
+| **Flags** | `svg/flags/` | PNG | 国旗图标，PNG 静态资源 |
+
+### 颜色策略说明
+
+- **currentColor**: 图标颜色继承父元素的 `color` 属性，可通过 CSS 自定义颜色
+- **固定色**: 图标保持原始设计颜色，不支持颜色自定义
+
+## 尺寸规范
+
+推荐尺寸：`12 | 16 | 20 | 24 | 32`
+
+也支持自定义 `number | string` 值。
+
+## 开发
+
+### 添加新图标
+
+1. 将 SVG 文件放入对应的分类目录（`svg/primary/`, `svg/product/`, 等）
+2. 文件名使用 `kebab-case`（如 `arrow-up.svg`）
+3. 运行 `pnpm build` 生成组件
+
+### 添加新国旗
+
+1. 将 PNG 文件放入 `svg/flags/` 目录
+2. 文件名使用国家代码小写（如 `cn.png`, `us.png`）
+3. 运行 `pnpm build` 会自动压缩到 `dist/flags/`
+
+### 构建
+
+```bash
+pnpm build
+```
+
+构建流程：
+1. `optimize:images` - 压缩 PNG 国旗到 `dist/flags/`
+2. `generate:manifest` - 扫描 SVG 目录，生成 `core/manifest.json`
+3. `generate:react` - 基于 manifest 生成 React 组件
+4. `build:react` - 构建 React 组件（生成 CJS/ESM 和类型定义）
+
+## 目录结构
+
+```
+packages/icons/
+├── svg/              # SVG/PNG 源文件（单一事实源）
+│   ├── primary/      # Primary 图标
+│   ├── product/      # Product 图标
+│   ├── coin/         # Coin 图标
+│   ├── currency/     # Currency 图标
+│   └── flags/        # Flags PNG 静态资源
+├── dist/
+│   └── flags/        # 压缩后的 PNG 国旗
+├── core/             # 核心层（manifest + 工具函数）
+├── react/            # React 适配层
+└── scripts/          # 生成器脚本
+```
+
+## 约束
+
+- ✅ SVG 作为单一事实源
+- ✅ 生成器自动生成，禁止手改产物
+- ✅ Primary/Product 支持 `currentColor`
+- ✅ Coin/Currency 使用固定色
+- ✅ Flags 仅作为静态资源，不包装为组件
+- ✅ PNG 自动压缩，生产环境使用压缩版
+
+## License
+
+ISC

package/core/index.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import type { Manifest, IconMetadata, FlagMetadata } from './types';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * 读取 manifest.json
+ */
+export function readManifest(manifestPath?: string): Manifest {
+  const path = manifestPath || join(__dirname, 'manifest.json');
+  const content = readFileSync(path, 'utf-8');
+  return JSON.parse(content);
+}
+
+/**
+ * 根据名称查找图标
+ */
+export function findIcon(manifest: Manifest, name: string): IconMetadata | undefined {
+  return manifest.icons.find((icon) => icon.name === name || icon.componentName === name);
+}
+
+/**
+ * 根据分类获取图标列表
+ */
+export function getIconsByCategory(
+  manifest: Manifest,
+  category: IconMetadata['category']
+): IconMetadata[] {
+  return manifest.icons.filter((icon) => icon.category === category);
+}
+
+/**
+ * 获取所有图标名称
+ */
+export function getAllIconNames(manifest: Manifest): string[] {
+  return manifest.icons.map((icon) => icon.componentName);
+}
+
+/**
+ * 导出类型
+ */
+export type { Manifest, IconMetadata, FlagMetadata, IconCategory, ColorStrategy } from './types';
+