@phelan/design 0.0.1

package/docs/components/basic/switch.md

@@ -0,0 +1,115 @@
+# Switch 开关
+
+表示两种相互对立的状态间的切换，多用于触发「开/关」。
+
+## 基础用法
+
+绑定 `v-model` 到一个 `Boolean` 类型的变量。 可以使用 `active-text` 属性与 `inactive-text` 属性来设置开关的文字描述。
+
+:::preview
+
+demo-preview=../../examples/switch/index.vue
+
+:::
+
+## 禁用状态
+
+设置 `disabled` 属性，接受一个 `Boolean`，设置 `true` 即可禁用。
+
+:::preview
+
+demo-preview=../../examples/switch/disabled.vue
+
+:::
+
+## 文字描述
+
+使用 `active-text` 与 `inactive-text` 属性来设置开关的文字描述。 使用 `inline-prompt` 属性可以将文字展示在开关内部。
+
+:::preview
+
+demo-preview=../../examples/switch/text.vue
+
+:::
+
+## 自定义图标
+
+使用 `active-icon` 与 `inactive-icon` 属性来设置开关的图标。 需要是 `Element Plus` 的图标组件。
+
+:::preview
+
+demo-preview=../../examples/switch/icon.vue
+
+:::
+
+## 不同尺寸
+
+Switch 组件提供除了默认值以外的三种尺寸，可以在不同场景下选择合适的开关尺寸。
+
+:::preview
+
+demo-preview=../../examples/switch/size.vue
+
+:::
+
+## 加载中
+
+设置 `loading` 属性为 `true` 来显示加载中状态。
+
+:::preview
+
+demo-preview=../../examples/switch/loading.vue
+
+:::
+
+## 扩展的 value 类型
+
+设置 `active-value` 和 `inactive-value` 属性，接受 `Boolean`, `String` 或 `Number` 类型的值。
+
+:::preview
+
+demo-preview=../../examples/switch/validate-value.vue
+
+:::
+
+## API
+
+### Attributes
+
+| 属性名              | 说明                    | 类型                        | 默认值    |
+| ---------------- | --------------------- | ------------------------- | ------ |
+| model-value / v-model | 绑定值                   | boolean / string / number | false  |
+| disabled         | 是否禁用                  | boolean                   | false  |
+| size             | 开关的尺寸                 | string                    | default |
+| width            | 开关的宽度（像素）             | number / string           | 40     |
+| active-icon      | switch 打开时所显示图标的类名     | string                    | —      |
+| inactive-icon    | switch 关闭时所显示图标的类名     | string                    | —      |
+| active-text      | switch 打开时的文字描述        | string                    | —      |
+| inactive-text    | switch 关闭时的文字描述        | string                    | —      |
+| active-value     | switch 打开时的值            | boolean / string / number | true   |
+| inactive-value   | switch 关闭时的值            | boolean / string / number | false  |
+| name             | switch 对应的 name 属性      | string                    | —      |
+| validate-event   | 改变 switch 状态时是否触发表单的校验 | boolean                   | true   |
+| inline-prompt    | 无论图标或文本是否显示在点内，只会呈现文本的第一个字符 | boolean                   | false  |
+| active-action-icon | switch 打开时的操作图标       | string                    | —      |
+| inactive-action-icon | switch 关闭时的操作图标       | string                    | —      |
+| loading          | 是否显示加载中状态             | boolean                   | false  |
+| loading-icon     | 自定义加载中状态图标            | string                    | —      |
+| before-change    | switch 状态改变前的钩子，返回 `false` 或者返回 `Promise` 且被 reject 则停止切换 | function()                | —      |
+| tabindex         | switch 的 tabindex        | string / number           | —      |
+
+### Events
+
+| 事件名     | 说明                    | 回调参数                |
+| ------- | --------------------- | ------------------- |
+| change  | switch 状态发生变化时的回调函数 | (value: boolean / string / number) => void |
+
+### Slots
+
+| 插槽名     | 说明      |
+| ------- | ------- |
+| default | 自定义默认内容 |
+
+## Owner
+
+Aric.Li@aldi.cn

package/docs/components/basic/table-grid.md

@@ -0,0 +1,116 @@
+# TableGrid 表格网格
+
+表格和分页的组合组件，提供完整的表格展示和分页功能。支持查询面板、列配置、操作列、自定义渲染等功能。适用于常见的列表页场景。
+
+## 基础用法
+
+基础的表格网格用法，包含表格和分页。
+
+:::preview
+
+demo-preview=../../examples/table-grid/basic.vue
+
+:::
+
+## 完整示例
+
+以下示例展示了 TableGrid 的所有功能，包括：
+- 查询面板（`queryParams` 插槽）
+- 工具栏（`toolbarLeft` 和 `toolbarRight` 插槽）
+- 列配置（包括 `selection`、`index` 特殊列类型）
+- 自定义列渲染（`formatter` 和 `render` 函数）
+- 操作列（`actionColumns` 配置和 `action` 插槽）
+- 自定义列头（`header-${prop}` 插槽）
+- 分页配置
+- 加载状态
+
+:::preview
+
+demo-preview=../../examples/table-grid/complete.vue
+
+:::
+
+## TableGrid API
+
+### TableGrid Attributes
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | -------- | ------ |
+| data | 表格数据 | `array` | `[]` |
+| columns | 列配置数组 | `TableGridColumn[]` | 必填 |
+| actionColumns | 操作列配置数组 | `ActionColumn[]` | `[]` |
+| actionColumnWidth | 操作列宽度 | `number` | `130` |
+| rowKey | 表格行 key | `string` | `'id'` |
+| loading | 是否显示加载状态 | `boolean` | `false` |
+| pagination | 分页配置，设置为 `false` 可隐藏分页 | `PaginationConfig \| false` | `{ currentPage: 1, pageSize: 10, total: 0, pageSizes: [10, 20, 50, 100], layout: 'total, sizes, prev, pager, next, jumper' }` |
+| defaultSpan | 查询面板默认列宽（基于 24 栅格系统） | `number` | `8` |
+| gutter | 查询面板栅格间距（单位：px） | `number` | `16` |
+| visibleCount | 查询面板折叠时显示的表单项数量 | `number` | `6` |
+| expandable | 查询面板是否可展开收起 | `boolean` | `true` |
+
+### PaginationConfig
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | -------- | ------ |
+| currentPage | 当前页码 | `number` | `1` |
+| pageSize | 每页条数 | `number` | `10` |
+| total | 总条数 | `number` | `0` |
+| pageSizes | 每页条数选项 | `number[]` | `[10, 20, 50, 100]` |
+| layout | 分页布局 | `string` | `'total, sizes, prev, pager, next, jumper'` |
+
+### TableGridColumn
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | -------- | ------ |
+| prop | 列字段名 | `string` | — |
+| label | 列标题 | `string` | — |
+| type | 列类型：`'selection' \| 'index' \| 'expand'` | `string` | — |
+| width | 列宽度 | `string \| number` | — |
+| minWidth | 列最小宽度 | `string \| number` | — |
+| fixed | 是否固定列 | `'left' \| 'right' \| boolean` | `false` |
+| align | 对齐方式 | `'left' \| 'center' \| 'right'` | `'left'` |
+| headerAlign | 表头对齐方式 | `'left' \| 'center' \| 'right'` | — |
+| sortable | 是否可排序 | `boolean` | `false` |
+| formatter | 格式化函数 | `(row: any, column: any, cellValue: any, index: number) => string` | — |
+| render | 自定义渲染函数 | `(row: any, column: any, index: number) => any` | — |
+| showOverflowTooltip | 当内容过长被隐藏时显示 tooltip | `boolean` | `true` |
+
+> 注意：`TableGridColumn` 继承自 Element Plus 的 `TableColumnCtx`，支持所有 Element Plus Table Column 的属性。
+
+### ActionColumn
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | -------- | ------ |
+| text | 按钮文本 | `string` | 必填 |
+| type | 按钮类型 | `'primary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'text' \| 'default'` | `'default'` |
+| textType | 文本类型：`'text'`（文本按钮）或 `'icon'`（图标按钮） | `'text' \| 'icon'` | `'text'` |
+| icon | 图标组件 | `Component \| string` | — |
+| disabled | 是否禁用，可以是布尔值或函数 | `boolean \| ((row: any) => boolean)` | `false` |
+| onClick | 点击事件处理函数 | `(row: any) => void` | 必填 |
+
+### TableGrid Events
+
+| 事件名 | 说明 | 参数 |
+| ------ | ---- | ---- |
+| search | 点击查询按钮时触发 | `() => void` |
+| reset | 点击重置按钮时触发 | `() => void` |
+| update:selection | 当选择项发生变化时触发 | `(selection: any[]) => void` |
+| page-change | 当页码发生变化时触发 | `(page: number) => void` |
+| size-change | 当每页条数发生变化时触发 | `(size: number) => void` |
+
+### TableGrid Slots
+
+| 插槽名 | 说明 | 参数 |
+| ------ | ---- | ---- |
+| queryParams | 查询表单内容，用于放置 `el-form` 或 `m-form` 表单组件 | — |
+| toolbarLeft | 工具栏左侧内容 | — |
+| toolbarRight | 工具栏右侧内容 | — |
+| header-${prop} | 自定义列头，`${prop}` 为列的 `prop` 值 | `{ column, $index }` |
+| action | 自定义操作列内容 | `{ row }` |
+
+### TableGrid Exposes
+
+| 方法名 | 说明 | 类型 |
+| ------ | ---- | ---- |
+| getPagination | 获取分页配置对象 | `() => PaginationConfig` |
+

package/docs/components/basic/table-head-editor.md

@@ -0,0 +1,135 @@
+# TableHeadEditor 表头编辑器
+
+表头编辑器组件，用于自定义表格列头的显示和编辑。该组件基于 `Drawer` 封装，提供了一个抽屉式的编辑界面，允许用户自定义表格列的配置。
+
+## 基础用法
+
+通过 `v-model` 控制抽屉的显示和隐藏，通过 `data` 属性传入列表项数据。组件内部已经实现了列表项的展示和选择功能。
+
+:::preview
+
+demo-preview=../../examples/table-head-editor/index.vue
+
+:::
+
+## 二级表头
+
+支持通过 `children` 属性配置二级表头，实现表格列的分组显示。
+
+:::preview
+
+demo-preview=../../examples/table-head-editor/grouping-header.vue
+
+:::
+
+## TableHeadEditor API
+
+### TableHeadEditor Attributes
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | -------- | ------ |
+| model-value / v-model | 控制显隐 | `boolean` | `false` |
+| title | 标题 | `string` | `"自定义列表"` |
+| size | 容器宽度，当使用 number 类型时, 以像素为单位, 当使用 string 类型时, 请传入 'x%' 或 'xvw', 否则便会以 number 类型解释 | `number / string` | `"700px"` |
+| data | 列表项data | `TreeItem[]` | `[]` |
+
+### TreeItem 类型定义
+
+```typescript
+interface TreeItem {
+  label: string;                    // 标签名称
+  visible: boolean;                 // 是否可见/显示
+  fixed: boolean | 'left' | 'right'; // 是否固定列，或固定方向
+  editable: boolean;                 // 是否可编辑
+  children?: TreeItem[];              // 子项（可选，用于二级表头）
+}
+```
+
+### TableHeadEditor Events
+
+| 事件名 | 说明 | 回调参数 |
+| ------ | ---- | ---- |
+| cancel | 取消时回调 | `() => void` |
+| confirm | 确认提交时回调 | `(newData: TreeItem[]) => void` |
+
+## 使用示例
+
+### 基础用法
+
+```vue
+<template>
+  <m-button @click="visible = true">自定义列表</m-button>
+  <m-table-head-editor
+    v-model="visible"
+    :data="columnConfig"
+    title="自定义列表"
+    :size="600"
+    @confirm="handleConfirm"
+    @cancel="handleCancel"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const visible = ref(false);
+const columnConfig = ref([
+  { label: 'Article Code', visible: true, fixed: 'left', editable: true },
+  { label: 'Article Name', visible: true, fixed: false, editable: true },
+  { label: 'Price', visible: true, fixed: false, editable: true },
+]);
+
+const handleConfirm = (newData) => {
+  console.log('确认提交', newData);
+  columnConfig.value = newData;
+};
+
+const handleCancel = () => {
+  console.log('取消');
+};
+</script>
+```
+
+### 二级表头用法
+
+```vue
+<template>
+  <m-table-head-editor
+    v-model="visible"
+    :data="columnConfig"
+    @confirm="handleConfirm"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue';
+
+const visible = ref(false);
+const columnConfig = ref([
+  {
+    label: 'Delivery Info',
+    visible: true,
+    fixed: false,
+    editable: false,
+    children: [
+      { label: 'Name', visible: true, fixed: false, editable: false },
+      {
+        label: 'Address Info',
+        visible: true,
+        fixed: false,
+        editable: false,
+        children: [
+          { label: 'State', visible: true, fixed: false, editable: false },
+          { label: 'City', visible: true, fixed: false, editable: false },
+        ],
+      },
+    ],
+  },
+]);
+
+const handleConfirm = (newData) => {
+  columnConfig.value = newData;
+};
+</script>
+```
+