jianghu-ui 1.0.1

package/dist/jianghu-ui.js.LICENSE.txt

@@ -0,0 +1 @@
+/*! regenerator-runtime -- Copyright (c) 2014-present, Facebook, Inc. -- license (MIT): https://github.com/babel/babel/blob/main/packages/babel-helpers/LICENSE */

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "jianghu-ui",
+  "version": "1.0.1",
+  "description": "JianghuJS UI Component Library with Storybook, Vue 2, and Vuetify 2",
+  "main": "src/index.js",
+  "scripts": {
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "build": "webpack --config webpack.config.js",
+    "build:watch": "webpack --config webpack.config.js --watch",
+    "serve-storybook": "npx http-server storybook-static",
+    "deploy": "npm run build && npm run build-storybook && npx gh-pages -d storybook-static"
+  },
+  "keywords": [
+    "jianghujs",
+    "vue",
+    "vuetify",
+    "ui-components",
+    "storybook"
+  ],
+  "author": "JianghuJS Team",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "@storybook/addon-docs": "^7.6.17",
+    "@storybook/addon-essentials": "^7.6.17",
+    "@storybook/addon-links": "^7.6.17",
+    "@storybook/addon-storysource": "^7.6.20",
+    "@storybook/blocks": "^7.6.17",
+    "@storybook/vue-webpack5": "^7.6.17",
+    "autoprefixer": "^10.4.20",
+    "gh-pages": "^6.1.1",
+    "http-server": "^14.1.1",
+    "postcss": "^8.4.49",
+    "postcss-loader": "^8.2.0",
+    "storybook": "^7.6.17",
+    "tailwindcss": "^3.4.16",
+    "vue": "^2.7.16",
+    "vue-loader": "^15.11.1",
+    "vue-template-compiler": "^2.7.16",
+    "@babel/core": "^7.23.0",
+    "@babel/preset-env": "^7.23.0",
+    "babel-loader": "^9.1.3",
+    "css-loader": "^6.8.1",
+    "mini-css-extract-plugin": "^2.7.6",
+    "webpack": "^5.89.0",
+    "webpack-cli": "^5.1.4"
+  },
+  "dependencies": {
+    "@mdi/font": "^7.4.47",
+    "vuetify": "^2.7.0"
+  }
+}

package/src/Design.stories.mdx

@@ -0,0 +1,195 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="介绍/设计原则" />
+
+# 设计原则
+
+JianghuJS UI 组件库遵循以下设计原则，确保组件的一致性、可用性和可维护性。
+
+## 一致性 (Consistency)
+
+### 视觉一致性
+- 所有组件遵循 Material Design 规范
+- 统一的颜色系统和间距规范
+- 一致的交互反馈和动画效果
+
+### 代码一致性
+- 统一的 props 命名规范
+- 一致的事件命名和触发方式
+- 标准化的插槽设计
+
+## 简洁性 (Simplicity)
+
+### 易于使用
+- 提供合理的默认值，减少必填配置
+- 清晰的 API 设计，避免复杂的嵌套结构
+- 完善的文档和示例代码
+
+### 代码简洁
+- 组件职责单一，避免过度封装
+- 保持组件的可组合性
+- 减少不必要的依赖
+
+## 灵活性 (Flexibility)
+
+### 高度可定制
+- 丰富的 props 支持各种使用场景
+- 插槽机制支持自定义内容
+- 支持主题定制和样式覆盖
+
+### 可扩展性
+- 组件设计预留扩展空间
+- 支持事件监听和自定义行为
+- 易于集成第三方功能
+
+## 性能 (Performance)
+
+### 优化策略
+- 按需加载，减少初始包体积
+- 合理使用计算属性和侦听器
+- 避免不必要的重渲染
+
+### CDN 优势
+- 利用浏览器缓存
+- 减少项目构建时间
+- 降低部署复杂度
+
+## 可访问性 (Accessibility)
+
+### 无障碍设计
+- 支持键盘导航
+- 合理的 ARIA 标签
+- 良好的色彩对比度
+
+### 响应式设计
+- 移动端优先
+- 适配各种屏幕尺寸
+- 支持触摸和鼠标交互
+
+## 组件设计规范
+
+### Props 设计
+
+```javascript
+// ✅ 好的设计
+{
+  color: 'primary',        // 使用预定义值
+  size: 'medium',          // 语义化的尺寸
+  disabled: false,         // 布尔值使用 is/has/should 等前缀或直接描述状态
+}
+
+// ❌ 避免的设计
+{
+  col: '#1976D2',          // 避免缩写
+  s: 2,                    // 不清晰的命名
+  dis: 0,                  // 用数字表示布尔值
+}
+```
+
+### 事件设计
+
+```javascript
+// ✅ 好的设计
+this.$emit('click', event);
+this.$emit('change', value);
+this.$emit('submit', formData);
+
+// ❌ 避免的设计
+this.$emit('c', event);              // 避免缩写
+this.$emit('on-click', event);       // 不需要 on- 前缀
+this.$emit('buttonClick', event);    // 避免组件名前缀
+```
+
+### 插槽设计
+
+```vue
+<!-- ✅ 好的设计 -->
+<template>
+  <div class="component">
+    <slot name="header"></slot>
+    <slot></slot>  <!-- 默认插槽 -->
+    <slot name="footer"></slot>
+  </div>
+</template>
+
+<!-- 提供作用域插槽支持自定义 -->
+<template v-slot:item="{ item }">
+  <slot name="item" :item="item">
+    {{ item.name }}
+  </slot>
+</template>
+```
+
+## 颜色系统
+
+### 主题色
+
+| 颜色名称 | 色值 | 用途 |
+|---------|------|------|
+| Primary | #1976D2 | 主要操作、重要信息 |
+| Secondary | #424242 | 次要操作 |
+| Success | #4CAF50 | 成功状态 |
+| Error | #FF5252 | 错误状态 |
+| Warning | #FB8C00 | 警告状态 |
+| Info | #2196F3 | 提示信息 |
+
+### 中性色
+
+| 颜色名称 | 色值 | 用途 |
+|---------|------|------|
+| Black | #000000 | 标题、重要文本 |
+| Grey-Dark | #424242 | 正文文本 |
+| Grey | #757575 | 辅助文本 |
+| Grey-Light | #BDBDBD | 禁用文本、边框 |
+| White | #FFFFFF | 背景、反色文本 |
+
+## 间距系统
+
+采用 8px 基准的间距系统:
+
+- **xs**: 4px
+- **sm**: 8px
+- **md**: 16px
+- **lg**: 24px
+- **xl**: 32px
+- **xxl**: 48px
+
+## 字体规范
+
+### 字体大小
+
+- **标题 1**: 32px
+- **标题 2**: 24px
+- **标题 3**: 20px
+- **标题 4**: 18px
+- **正文**: 16px
+- **辅助文本**: 14px
+- **小文本**: 12px
+
+### 字体粗细
+
+- **Regular**: 400
+- **Medium**: 500
+- **Bold**: 700
+
+## 响应式断点
+
+```javascript
+{
+  xs: 0,      // 手机竖屏
+  sm: 600,    // 手机横屏 / 平板竖屏
+  md: 960,    // 平板横屏 / 小屏电脑
+  lg: 1264,   // 桌面
+  xl: 1904,   // 大屏
+}
+```
+
+## 动画时长
+
+- **快速**: 100ms - 用于小元素的简单过渡
+- **标准**: 200ms - 用于大多数过渡效果
+- **复杂**: 300ms - 用于复杂动画或大元素
+
+---
+
+遵循这些设计原则，可以确保组件库的质量和一致性，提供良好的开发体验。

package/src/Introduction.stories.mdx

@@ -0,0 +1,148 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="介绍/快速开始" />
+
+# JianghuJS UI 组件库
+
+欢迎使用 **JianghuJS UI** 组件库！这是一个基于 Vue 2 和 Vuetify 2 构建的现代化 UI 组件库，专为 JianghuJS 项目设计。
+
+## 特性
+
+- 🚀 **开箱即用** - 无需复杂配置，直接通过 CDN 引入即可使用
+- 🎨 **Material Design** - 基于 Vuetify 2，遵循 Material Design 设计规范
+- 📱 **响应式设计** - 完美适配各种屏幕尺寸
+- 🔧 **高度可定制** - 丰富的 props 和插槽支持
+- 📖 **完善的文档** - 通过 Storybook 提供交互式文档和示例
+
+## 快速开始
+
+### 1. CDN 引入（推荐）
+
+在 HTML 文件的 `<head>` 标签中引入必要的资源:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link href="https://jianghujs.github.io/jianghu-ui/cdn/jianghu-ui.css" rel="stylesheet">
+</head>
+<body>
+  <div id="app">
+    <!-- 你的应用内容 -->
+  </div>
+  <script src="https://jianghujs.github.io/jianghu-ui/cdn/jianghu-ui.js"></script>
+</body>
+</html>
+```
+
+### 2. 初始化 Vue 应用
+
+```javascript
+new Vue({
+  el: '#app',
+  vuetify: new Vuetify(),
+  // 你的组件和配置
+});
+```
+
+### 3. 使用组件
+
+```vue
+<template>
+  <v-app>
+    <jh-button label="点击我" color="primary" @click="handleClick" />
+  </v-app>
+</template>
+
+<script>
+export default {
+  methods: {
+    handleClick() {
+      alert('按钮被点击了！');
+    }
+  }
+}
+</script>
+```
+
+## 组件列表
+
+### 基础组件
+- **JhButton** - 按钮组件，支持多种样式和状态
+- **JhCard** - 卡片组件，用于展示内容块
+
+### 数据展示
+- **JhTable** - 数据表格组件，支持排序、搜索、分页等功能
+
+### 表单组件
+- **JhForm** - 表单组件，支持多种输入类型和验证
+
+## 主题定制
+
+你可以在初始化 Vuetify 时自定义主题颜色:
+
+```javascript
+new Vue({
+  el: '#app',
+  vuetify: new Vuetify({
+    theme: {
+      themes: {
+        light: {
+          primary: '#1976D2',
+          secondary: '#424242',
+          accent: '#82B1FF',
+          error: '#FF5252',
+          info: '#2196F3',
+          success: '#4CAF50',
+          warning: '#FB8C00',
+        },
+      },
+    },
+  }),
+});
+```
+
+## 开发指南
+
+### 本地开发
+
+```bash
+# 安装依赖
+npm install
+
+# 启动 Storybook
+npm run storybook
+
+# 访问 http://localhost:6006
+```
+
+### 构建文档
+
+```bash
+# 构建静态文档站点
+npm run build-storybook
+
+# 预览构建结果
+npm run serve-storybook
+```
+
+## 浏览器支持
+
+- Chrome (最新版)
+- Firefox (最新版)
+- Safari (最新版)
+- Edge (最新版)
+
+## 相关资源
+
+- [Vue 2 官方文档](https://v2.vuejs.org/)
+- [Vuetify 2 官方文档](https://v2.vuetifyjs.com/)
+- [Material Design Icons](https://materialdesignicons.com/)
+
+## 贡献指南
+
+欢迎提交 Issue 和 Pull Request！
+
+## 许可证
+
+MIT License

package/src/components/JhAddressSelect/JhAddressSelect.md

@@ -0,0 +1,250 @@
+# JhAddressSelect - 省市区选择组件
+
+省市区三级联动选择组件，支持自定义显示层级、标签文本和数据源。
+
+- ✅ **四级联动**: 支持省、市、区、镇四级联动选择
+- ✅ **自定义层级**: 可配置显示 1-4 级（仅省份、省市、省市区、省市区镇）
+- ✅ **自定义标签**: 支持自定义各级别的显示文本
+- ✅ **自定义数据**: 支持传入自定义省市区数据源
+- ✅ **样式透传**: 支持 Vuetify 的 outlined、dense、loading 等样式
+- ✅ **双向绑定**: 支持 v-model 双向数据绑定
+- ✅ **事件触发**: change 事件在值变化时触发
+- ✅ **清除功能**: 支持清除已选值
+- ✅ **返回完整信息**: 事件返回包含 code 和 name 的完整对象
+
+## 基本用法
+
+```vue
+<template>
+  <jh-address-select
+    v-model="address"
+    :data="addressData"
+    @change="handleAddressChange"
+  ></jh-address-select>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      address: { province: null, city: null, district: null, town: null },
+      addressData: [
+        { code: '110000', name: '北京市', children: [...] },
+        { code: '440000', name: '广东省', children: [...] }
+      ]
+    };
+  },
+  methods: {
+    handleAddressChange(value) {
+      console.log('省份:', value.province?.name, value.province?.code);
+      console.log('城市:', value.city?.name, value.city?.code);
+      console.log('区县:', value.district?.name, value.district?.code);
+      console.log('乡镇:', value.town?.name, value.town?.code);
+    }
+  }
+};
+</script>
+```
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value / v-model | 绑定值，返回包含 code 和 name 的对象 | object | { province: null, city: null, district: null } |
+| level | 显示层级：1-仅省份，2-省市，3-省市区，4-省市区镇 | number | 3 |
+| outlined | 是否使用 outlined 样式 | boolean | true |
+| dense | 是否使用紧凑模式 | boolean | false |
+| loading | 是否显示加载状态 | boolean | false |
+| labels | 自定义标签文本 | object | { province: '省份', city: '城市', district: '区/县', town: '乡镇' } |
+| data | 省市区数据源 | array | 内置示例数据 |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| input | 值变化时触发（v-model） | (value: object) |
+| change | 值变化时触发 | (value: object) |
+
+### 返回值格式
+
+v-model 绑定值和事件回调参数的格式：
+
+```javascript
+{
+  province: { code: '440000', name: '广东省' },
+  city: { code: '440300', name: '深圳市' },
+  district: { code: '440305', name: '南山区' },
+  town: { code: '440305001', name: '南头街道' }  // level=4 时存在
+}
+```
+
+每个字段都是一个对象，包含 `code`（编码）和 `name`（名称）两个属性。未选择时为 `null`。
+
+### 数据格式
+
+data 属性需要符合以下格式：
+
+```javascript
+[
+  {
+    code: '110000',  // 省份编码
+    name: '北京市',   // 省份名称
+    children: [      // 城市列表
+      {
+        code: '110100',  // 城市编码
+        name: '市辖区',   // 城市名称
+        children: [      // 区县列表
+          {
+            code: '110101',  // 区县编码
+            name: '东城区'   // 区县名称
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+## 使用示例
+
+### 默认三级联动
+
+```vue
+<jh-address-select
+  v-model="address"
+  :data="addressData"
+></jh-address-select>
+```
+
+### 仅选择到城市
+
+```vue
+<jh-address-select
+  v-model="address"
+  :level="2"
+  :data="addressData"
+></jh-address-select>
+```
+
+### 仅选择省份
+
+```vue
+<jh-address-select
+  v-model="address"
+  :level="1"
+  :data="addressData"
+></jh-address-select>
+```
+
+### 四级联动（省市区镇）
+
+```vue
+<jh-address-select
+  v-model="address"
+  :level="4"
+  :data="addressData"
+></jh-address-select>
+```
+
+### 四级联动（带初始值）
+
+```vue
+<jh-address-select
+  v-model="address"
+  :level="4"
+  :data="addressData"
+></jh-address-select>
+
+<script>
+export default {
+  data() {
+    return {
+      address: {
+        province: { code: '440000', name: '广东省' },
+        city: { code: '440300', name: '深圳市' },
+        district: { code: '440305', name: '南山区' },
+        town: { code: '440305001', name: '南头街道' }
+      }
+    };
+  }
+};
+</script>
+```
+
+### 紧凑模式
+
+```vue
+<jh-address-select
+  v-model="address"
+  dense
+  :data="addressData"
+></jh-address-select>
+```
+
+### 自定义标签文本
+
+```vue
+<jh-address-select
+  v-model="address"
+  :labels="{ province: '所在省份', city: '所在城市', district: '所在区县' }"
+  :data="addressData"
+></jh-address-select>
+```
+
+### 加载状态
+
+```vue
+<jh-address-select
+  v-model="address"
+  :loading="isLoading"
+  :data="addressData"
+></jh-address-select>
+```
+
+### 使用 filled 样式
+
+```vue
+<jh-address-select
+  v-model="address"
+  :outlined="false"
+  :data="addressData"
+></jh-address-select>
+```
+
+### 监听变化
+
+```vue
+<template>
+  <jh-address-select
+    v-model="address"
+    :data="addressData"
+    @change="handleAddressChange"
+  ></jh-address-select>
+</template>
+
+<script>
+export default {
+  methods: {
+    handleAddressChange(value) {
+      console.log('地址变化:', value);
+    }
+  }
+};
+</script>
+```
+
+## 注意事项
+
+1. **数据格式**: data 属性必须符合指定的嵌套格式，包含 code 和 name 字段
+2. **层级控制**: level 属性控制显示的级数，设置为 1 时只显示省份，2 时显示省市，3 时显示省市区，4 时显示省市区镇
+3. **联动逻辑**: 选择省份后会清空城市、区县和乡镇，选择城市后会清空区县和乡镇，选择区县后会清空乡镇
+4. **禁用状态**: 未选择上级时，下级选择器会自动禁用
+5. **响应式布局**: 组件会根据 level 自动调整栅格布局（level=1 时占 12 列，level=2 时占 6 列，level=3 时占 4 列，level=4 时占 3 列）
+6. **返回值格式**: v-model 和事件返回的值包含 code 和 name 两个字段，方便获取编码和名称
+
+## 相关链接
+
+- [Vuetify Autocomplete](https://vuetifyjs.com/en/components/autocompletes/)
+- [中国行政区划代码](http://www.mca.gov.cn/article/sj/xzqh/)