@icc-grow/web-components 1.0.0

package/skills/icc-web-components/patterns/dialog-form.md

@@ -0,0 +1,180 @@
+# Pattern: 弹窗表单
+
+> 弹窗/抽屉中嵌入表单
+
+## IDialog + IForm 骨架
+
+```vue
+<!-- UserFormDialog.vue — 独立子组件 -->
+<template>
+  <IDialog
+    v-model:visible="visible"
+    :title="isEdit ? '编辑用户' : '新增用户'"
+    width="560px"
+    @closed="handleClosed"
+    @open="handleOpen"
+  >
+    <IForm :model="form" :rules="rules" ref="formRef">
+      <IFormItem label="姓名" prop="name" >
+        <IInput v-model="form.name" placeholder="请输入姓名"  />
+      </IFormItem>
+
+      <IFormItem label="邮箱" prop="email" >
+        <IInput v-model="form.email" placeholder="请输入邮箱" />
+      </IFormItem>
+
+      <IFormItem label="角色" prop="role" >
+        <ISelect
+          v-model="form.role"
+          :options="roleOptions"
+          placeholder="请选择角色"
+        />
+      </IFormItem>
+    </IForm>
+
+    <template #footer>
+      <ISpace :size="12">
+        <IButton type="black" plain @click="visible = false">取消</IButton>
+        <IButton :loading="loading" @click="handleSubmit">确定</IButton>
+      </ISpace>
+    </template>
+  </IDialog>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, nextTick } from 'vue'
+import {
+  IDialog, IForm, IFormItem, IInput, ISelect,
+  IButton, ISpace, IMessage,
+} from '@icc-grow/web-components'
+import type { IFormInstance } from '@icc-grow/web-components'
+import type { Rules } from 'async-validator'
+
+interface FormItem {
+  id?:string
+  name:string
+  email:string
+  role:number
+}
+  
+
+interface Props {
+  data:FormItem,
+  visible:boolean
+}
+
+interface Emits {
+  success:()=>void
+  'update:visible':(value:boolean)=>void
+}
+
+// ---- Props / Emits ----
+const props = withDefaults(defineProps<Props>(), {});
+  
+
+const emit = defineEmits<Emits>()
+
+// ---- 状态 ----
+const visible = ref(false)
+const isEdit = ref(false)
+const loading = ref(false)
+const formRef = ref<IFormInstance>()
+
+
+const form = reactive<FormItem>({
+  id:null,
+  name: '',
+  email: '',
+  role: 0,
+})
+
+const rules: Rules = {
+  name: [{ required: true, message: '请输入姓名', trigger: 'blur' }],
+  email: [
+    { required: true, message: '请输入邮箱', trigger: 'blur' },
+    { type: 'email', message: '邮箱格式不正确', trigger: 'blur' },
+  ],
+  role: [{ required: true, message: '请选择角色', trigger: 'change' }],
+}
+// ---- 方法 ----
+function handleOpen() {
+  isEdit.value = !!props.data?.id
+  Object.assign(form, props.data)
+}
+  
+
+async function handleSubmit() {
+  try {
+   const {valid, firstMessage} = await formRef.value?.validate()
+   if(!valid){
+    IMessage.error(firstMessage)
+     return;
+   }
+    loading.value = true
+    if (isEdit.value) {
+      await api.updateUser(editId.value!, form)
+    } else {
+      await api.createUser(form)
+    }
+    IMessage.success(isEdit.value ? '编辑成功' : '新增成功')
+    visible.value = false
+    emit('success')
+  } catch {
+    // 校验失败
+  } finally {
+    loading.value = false
+  }
+}
+
+function handleClosed() {
+  formRef.value?.resetFields()
+  emit('update:visible',false);
+}
+
+</script>
+```
+
+## 父组件调用
+
+```vue
+<script setup lang="ts">
+const formDialogRef = ref()
+
+function handleAdd() {
+  formDialogRef.value?.openAdd()
+}
+
+function handleEdit(row) {
+  formDialogRef.value?.openEdit(row)
+}
+</script>
+
+<template>
+  <!-- 页面内容... -->
+  <UserFormDialog ref="formDialogRef" :role-options="roleOptions" @success="fetchList" />
+</template>
+```
+
+## IDrawer 变体
+
+将 `IDialog` 替换为 `IDrawer` 即可，API 几乎一致：
+
+```vue
+<IDrawer
+  v-model:visible="visible"
+  :title="isEdit ? '编辑用户' : '新增用户'"
+  placement="right"
+  size="560px"
+  @closed="handleClosed"
+>
+  <!-- 内容和 footer 同上 -->
+</IDrawer>
+```
+
+## 关键要点
+
+1. **弹窗表单必须抽离为独立子组件**，不要混在列表页中
+2. 通过 `defineExpose` 暴露 `openAdd` / `openEdit` 方法给父组件
+3. `@closed` 事件中调用 `resetFields()` 重置表单
+4. 弹窗内表单控件用 `class="w-full"` 撑满
+5. `#footer` 用 `ISpace` 排列取消和确定按钮

package/skills/icc-web-components/patterns/form-page.md

@@ -0,0 +1,139 @@
+# Pattern: 表单页
+
+> 整页表单 + 提交/返回按钮
+
+## 完整骨架
+
+```vue
+<template>
+  <IPageLayout title="新增用户">
+    <template #header-action>
+      <ISpace :size="12">
+        <IButton @click="handleBack">返回</IButton>
+        <IButton type="primary" :loading="submitting" @click="handleSubmit">保存</IButton>
+      </ISpace>
+    </template>
+
+    <ICard title="基本信息">
+      <IForm :model="form" :rules="rules" ref="formRef">
+        <IFormItem label="姓名" prop="name" required>
+          <IInput v-model="form.name" placeholder="请输入姓名" class="w-[400px]" />
+        </IFormItem>
+
+        <IFormItem label="手机号" prop="phone" required>
+          <IInput v-model="form.phone" placeholder="请输入手机号" class="w-[400px]" />
+        </IFormItem>
+
+        <IFormItem label="邮箱" prop="email">
+          <IInput v-model="form.email" placeholder="请输入邮箱" class="w-[400px]" />
+        </IFormItem>
+
+        <IFormItem label="部门" prop="department" required>
+          <ITreeSelect
+            v-model="form.department"
+            :data="departmentTree"
+            placeholder="请选择部门"
+            class="w-[400px]"
+          />
+        </IFormItem>
+
+        <IFormItem label="角色" prop="roles" required>
+          <ISelect
+            v-model="form.roles"
+            :options="roleOptions"
+            multiple
+            placeholder="请选择角色"
+            class="w-[400px]"
+          />
+        </IFormItem>
+
+        <IFormItem label="状态" prop="status">
+          <ISwitch v-model="form.status" :true-value="1" :false-value="0" />
+        </IFormItem>
+
+        <IFormItem label="备注" prop="remark">
+          <ITextarea
+            v-model="form.remark"
+            placeholder="请输入备注"
+            :autosize="{ minRows: 3, maxRows: 6 }"
+            :maxlength="200"
+            show-word-limit
+            class="w-[400px]"
+          />
+        </IFormItem>
+      </IForm>
+    </ICard>
+  </IPageLayout>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive } from 'vue'
+import {
+  IPageLayout, ICard, IForm, IFormItem,
+  IInput, ITextarea, ISelect, ITreeSelect,
+  ISwitch, IButton, ISpace, IMessage,
+} from '@icc-grow/web-components'
+import type { FormExpose } from '@icc-grow/web-components'
+import type { Rules } from 'async-validator'
+
+// ---- 表单数据 ----
+const formRef = ref<FormExpose>()
+const submitting = ref(false)
+
+const form = reactive({
+  name: '',
+  phone: '',
+  email: '',
+  department: undefined as string | undefined,
+  roles: [] as number[],
+  status: 1,
+  remark: '',
+})
+
+// ---- 校验规则 ----
+const rules: Rules = {
+  name: [{ required: true, message: '请输入姓名', trigger: 'blur' }],
+  phone: [
+    { required: true, message: '请输入手机号', trigger: 'blur' },
+    { pattern: /^1\d{10}$/, message: '手机号格式不正确', trigger: 'blur' },
+  ],
+  email: [
+    { type: 'email', message: '邮箱格式不正确', trigger: 'blur' },
+  ],
+  department: [{ required: true, message: '请选择部门', trigger: 'change' }],
+  roles: [{ required: true, message: '请选择角色', trigger: 'change' }],
+}
+
+// ---- 选项数据 ----
+const departmentTree = ref([])   // 从接口获取
+const roleOptions = ref([])      // 从接口获取
+
+// ---- 方法 ----
+async function handleSubmit() {
+  try {
+    await formRef.value?.validate()
+    submitting.value = true
+    await api.saveUser(form)
+    IMessage.success('保存成功')
+    handleBack()
+  } catch {
+    // 校验失败，自动显示错误
+  } finally {
+    submitting.value = false
+  }
+}
+
+function handleBack() {
+  router.back()
+}
+</script>
+```
+
+## 关键要点
+
+1. 标题栏用 `#header-action` 放返回和保存按钮
+2. 表单用 `ICard` 包裹，视觉分区
+3. 所有输入组件限制宽度 `class="w-[400px]"`
+4. 校验规则统一在 `rules` 对象中定义
+5. 提交前调用 `formRef.value?.validate()`
+6. **编辑场景**：onMounted 中根据路由 ID 加载数据，回填 form

package/skills/icc-web-components/patterns/tabs-page.md

@@ -0,0 +1,164 @@
+# Pattern: 标签页切换
+
+> 顶部 Tabs 切换多个子页面/子模块
+
+## 完整骨架
+
+```vue
+<template>
+  <IPageLayout title="系统设置">
+    <!-- Tabs 放在搜索区位置 -->
+    <template #search>
+      <ITabs v-model="activeTab" :options="tabOptions" @change="handleTabChange" />
+    </template>
+
+    <!-- 根据 activeTab 条件渲染不同内容 -->
+    <template v-if="activeTab === 'basic'">
+      <BasicSettings />
+    </template>
+
+    <template v-else-if="activeTab === 'security'">
+      <SecuritySettings />
+    </template>
+
+    <template v-else-if="activeTab === 'notification'">
+      <NotificationSettings />
+    </template>
+  </IPageLayout>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { IPageLayout, ITabs } from '@icc-grow/web-components'
+import type { TabItem } from '@icc-grow/web-components'
+import BasicSettings from './components/BasicSettings.vue'
+import SecuritySettings from './components/SecuritySettings.vue'
+import NotificationSettings from './components/NotificationSettings.vue'
+
+const activeTab = ref('basic')
+
+const tabOptions: TabItem[] = [
+  { label: '基本设置', value: 'basic' },
+  { label: '安全设置', value: 'security' },
+  { label: '通知设置', value: 'notification' },
+]
+
+function handleTabChange(value: string | number) {
+  // 可选：路由同步
+  // router.replace({ query: { tab: value } })
+}
+</script>
+```
+
+## 变体：Tabs 内嵌 CRUD 列表
+
+当每个 Tab 页面是独立的 CRUD 列表时：
+
+```vue
+<template>
+  <IPageLayout title="订单管理">
+    <template #search>
+      <ITabs v-model="activeTab" :options="tabOptions" @change="handleTabChange" />
+    </template>
+
+    <!-- 搜索区跟随 Tab 切换 -->
+    <!-- 注意：搜索区需要放在 default 插槽内，因为 #search 已被 Tabs 占用 -->
+    <div class="mb-16">
+      <IPageSearch>
+        <IInput v-model="query.keyword" placeholder="订单号" clearable />
+        <template #action>
+          <IButton type="primary" @click="handleSearch">查询</IButton>
+        </template>
+      </IPageSearch>
+    </div>
+
+    <ITable v-loading="loading" :data="tableData" :columns="currentColumns" />
+
+    <template #footer>
+      <IPagination
+        v-model:currentPage="pagination.currentPage"
+        v-model:pageSize="pagination.pageSize"
+        :total="pagination.total"
+        @change="fetchList"
+      />
+    </template>
+  </IPageLayout>
+</template>
+
+<script setup lang="ts">
+import { ref, reactive, computed, watch } from 'vue'
+import {
+  IPageLayout, ITabs, IPageSearch, ITable, IPagination,
+  IInput, IButton,
+} from '@icc-grow/web-components'
+import type { TabItem, TableColumn } from '@icc-grow/web-components'
+
+const activeTab = ref('pending')
+
+const tabOptions: TabItem[] = [
+  { label: '待处理', value: 'pending', count: 12 },
+  { label: '进行中', value: 'processing', count: 5 },
+  { label: '已完成', value: 'completed' },
+  { label: '已取消', value: 'cancelled' },
+]
+
+const query = reactive({ keyword: '' })
+const loading = ref(false)
+const tableData = ref([])
+const pagination = reactive({ currentPage: 1, pageSize: 20, total: 0 })
+
+// 不同 Tab 可能需要不同的列配置
+const pendingColumns: TableColumn[] = [
+  { label: '订单号', prop: 'orderNo' },
+  { label: '金额', prop: 'amount' },
+  { label: '操作', prop: 'action', width: 120 },
+]
+
+const completedColumns: TableColumn[] = [
+  { label: '订单号', prop: 'orderNo' },
+  { label: '金额', prop: 'amount' },
+  { label: '完成时间', prop: 'completedAt', width: 180 },
+]
+
+const currentColumns = computed(() => {
+  return activeTab.value === 'completed' ? completedColumns : pendingColumns
+})
+
+function handleTabChange() {
+  pagination.currentPage = 1
+  fetchList()
+}
+
+function handleSearch() {
+  pagination.currentPage = 1
+  fetchList()
+}
+
+async function fetchList() {
+  loading.value = true
+  try {
+    const res = await api.getOrders({
+      status: activeTab.value,
+      ...query,
+      page: pagination.currentPage,
+      size: pagination.pageSize,
+    })
+    tableData.value = res.data.list
+    pagination.total = res.data.total
+  } finally {
+    loading.value = false
+  }
+}
+
+watch(activeTab, handleTabChange, { immediate: true })
+</script>
+```
+
+## 关键要点
+
+1. `ITabs` 通常放在 `#search` 插槽位置
+2. 每个 Tab 的内容建议抽离为独立子组件
+3. Tab 切换时需要重置分页 `currentPage = 1`
+4. `TabItem.count` 可以在标签上显示角标数字
+5. 支持权限过滤：`authList` + `authCode`
+6. 如果 Tabs 和搜索区要共存，搜索区放在 default 插槽内

package/skills/icc-web-components/patterns/tree-manage.md

@@ -0,0 +1,169 @@
+# Pattern: 树形管理
+
+> 左侧树形结构 + 右侧内容区
+
+## 完整骨架
+
+```vue
+<template>
+  <IPageLayout title="部门管理">
+    <div class="tree-manage">
+      <!-- 左侧树形 -->
+      <div class="tree-manage__aside">
+        <ICard>
+          <template #header>
+            <div class="flex items-center justify-between">
+              <span class="text-black-70 font-medium">组织架构</span>
+              <IButton text type="primary" icon="icon-add" @click="handleAddDept">新增</IButton>
+            </div>
+          </template>
+
+          <IInput
+            v-model="treeKeyword"
+            placeholder="搜索部门"
+            clearable
+            class="mb-12"
+          />
+
+          <ITree
+            ref="treeRef"
+            :data="treeData"
+            :props="{ children: 'children', label: 'name' }"
+            row-key="id"
+            selectable
+            default-expand-all
+            height="calc(100vh - 320px)"
+            @node-click="handleNodeClick"
+          />
+        </ICard>
+      </div>
+
+      <!-- 右侧内容区 -->
+      <div class="tree-manage__content">
+        <ICard title="部门详情" v-if="currentDept">
+          <template #header>
+            <div class="flex items-center justify-between">
+              <span class="text-black-70 font-medium">{{ currentDept.name }}</span>
+              <ISpace :size="8">
+                <IButton text type="primary" @click="handleEditDept">编辑</IButton>
+                <IButton text type="danger" @click="handleDeleteDept">删除</IButton>
+              </ISpace>
+            </div>
+          </template>
+
+          <!-- 部门信息 / 人员列表等 -->
+          <ITable
+            v-loading="loading"
+            :data="memberList"
+            :columns="memberColumns"
+          >
+            <template #action="{ row }">
+              <IButton text type="primary" @click="handleEditMember(row)">编辑</IButton>
+            </template>
+          </ITable>
+        </ICard>
+
+        <IEmpty v-else desc="请从左侧选择部门" />
+      </div>
+    </div>
+  </IPageLayout>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import {
+  IPageLayout, ICard, ITree, ITable,
+  IInput, IButton, ISpace, IEmpty, IConfirm, IMessage,
+} from '@icc-grow/web-components'
+import type { TableColumn, TreeExpose, TreeRawData } from '@icc-grow/web-components'
+
+// ---- 类型定义 ----
+interface DeptItem {
+  id: number
+  name: string
+  children?: DeptItem[]
+}
+
+interface MemberItem {
+  id: number
+  name: string
+  position: string
+}
+
+// ---- 树形数据 ----
+const treeRef = ref<TreeExpose>()
+const treeData = ref<DeptItem[]>([])
+const treeKeyword = ref('')
+const currentDept = ref<DeptItem>()
+
+// ---- 人员列表 ----
+const loading = ref(false)
+const memberList = ref<MemberItem[]>([])
+
+const memberColumns: TableColumn<MemberItem>[] = [
+  { label: '姓名', prop: 'name', minWidth: 120 },
+  { label: '职位', prop: 'position', minWidth: 120 },
+  { label: '操作', prop: 'action', width: 100, fixed: 'right' },
+]
+
+// ---- 方法 ----
+function handleNodeClick(data: TreeRawData) {
+  currentDept.value = data as unknown as DeptItem
+  fetchMembers(data.id as number)
+}
+
+async function fetchMembers(deptId: number) {
+  loading.value = true
+  try {
+    const res = await api.getDeptMembers(deptId)
+    memberList.value = res.data
+  } finally {
+    loading.value = false
+  }
+}
+
+function handleAddDept() { /* 打开新增部门弹窗 */ }
+function handleEditDept() { /* 打开编辑部门弹窗 */ }
+function handleEditMember(row: MemberItem) { /* 打开编辑成员弹窗 */ }
+
+function handleDeleteDept() {
+  if (!currentDept.value) return
+  IConfirm({
+    type: 'warning',
+    title: '确认删除',
+    content: `确定删除部门「${currentDept.value.name}」吗？`,
+  }).then(async () => {
+    await api.deleteDept(currentDept.value!.id)
+    IMessage.success('删除成功')
+    currentDept.value = undefined
+    // 重新加载树
+  })
+}
+</script>
+
+<style scoped>
+.tree-manage {
+  display: flex;
+  gap: 16px;
+  height: 100%;
+}
+
+.tree-manage__aside {
+  width: 280px;
+  flex-shrink: 0;
+}
+
+.tree-manage__content {
+  flex: 1;
+  min-width: 0;
+}
+</style>
+```
+
+## 关键要点
+
+1. 左右布局用 `flex` + 固定左侧宽度
+2. 左侧搜索用 `IInput` + 树形数据过滤
+3. 右侧未选中时显示 `IEmpty` 占位
+4. 树节点点击后加载右侧数据
+5. 如果右侧内容是列表，直接复用 `ITable`；如果是表单详情，用 `IForm`

package/skills/icc-web-components/references/i-avatar.md

@@ -0,0 +1,29 @@
+# IAvatar / IAvatarGroup
+
+## IAvatar
+
+图片失败时以 `name` 首字符兜底。
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| src | `string` | — | 头像图片 URL |
+| name | `string` | — | 用户姓名（兜底 + alt + 哈希背景色） |
+| size | `number \| string` | `26` | 尺寸(px) |
+| shape | `'circle' \| 'square'` | `'circle'` | 形状 |
+
+---
+
+## IAvatarGroup
+
+重叠排列，超出显示 +N。
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | `number \| string` | — | 统一尺寸 |
+| limit | `number \| string` | — | 最大展示数 |
+
+**Slots**: `default`（放置多个 `IAvatar`）

package/skills/icc-web-components/references/i-badge.md

@@ -0,0 +1,19 @@
+# IBadge
+
+角标，右上角覆盖在子元素上。
+
+**Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| count | `number` | — | 显示数字 |
+| max | `number` | — | 最大值，超出显示 `max+` |
+| showZero | `boolean` | `false` | count=0 时是否显示 |
+| dot | `boolean` | `false` | 红点模式 |
+
+**Slots**: `default`
+
+```vue
+<IBadge :count="5"><IIcon name="icon-bell" /></IBadge>
+<IBadge dot><IIcon name="icon-notification" /></IBadge>
+```