@phelan/design 0.0.1

package/docs/components/calendar.md

@@ -0,0 +1,111 @@
+# Calendar 日历
+
+显示日期，支持基础日历功能和甘特图任务展示。
+
+## 基础用法
+
+`AdCalendar` 组件设置 value 来指定当前显示的月份。 如果 value 未指定，则显示当月。 value 支持 v-model 双向绑定。
+
+:::preview
+
+demo-preview=../examples/calendar/calendar01.vue
+
+:::
+
+## 自定义内容
+
+`AdCalendar` 组件通过设置名为 date-cell 的 scoped-slot 来自定义日历单元格中显示的内容。 在 scoped-slot 可以获取到 date（当前单元格的日期）, data（包括 type，isSelected，day 属性）。 详情解释参考下方的 API 文档。
+
+:::preview
+
+demo-preview=../examples/calendar/calendar02.vue
+
+:::
+
+## 范围
+
+`AdCalendar` 组件通过设置 range 属性指定日历的显示范围。 开始时间必须是周起始日，结束时间必须是周结束日，且时间跨度不能超过两个月。
+:::preview
+
+demo-preview=../examples/calendar/calendar03.vue
+
+:::
+
+## 自定义日历头部
+
+`AdCalendar` 组件通过设置 插槽来自定义日历头部。
+:::preview
+
+demo-preview=../examples/calendar/calendar04.vue
+
+:::
+
+## 甘特图日历
+
+`AdCalendar` 组件在基础日历上扩展了甘特图任务展示功能，可以在日历上显示任务的时间安排。
+
+:::preview
+
+demo-preview=../examples/calendar/calendar05.vue
+
+:::
+
+## 甘特图日历 - 自定义弹窗内容
+
+`AdCalendar` 组件在使用Slot来实现自当以弹窗内容
+
+:::preview
+
+demo-preview=../examples/calendar/calendar06.vue
+
+:::
+
+## AdCalendar API
+
+### AdCalendar Attributes
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | ---- | ------ |
+| model-value / v-model | 选中项绑定值 | `Date \| string \| number` | — |
+| range | 时间范围，包括开始时间与结束时间。开始时间必须是周起始日，结束时间必须是周结束日，且时间跨度不能超过两个月 | `[Date, Date]` | — |
+| first-day-of-week | 周起始日，0 代表周日，1 代表周一，以此类推 | `number` | 0 |
+| tasks | 任务列表数组 | `Task[]` | [] |
+
+### AdCalendar Events
+
+| 事件名 | 说明 | 参数 |
+| ------ | ---- | ---- |
+| change | 当选中的日期改变时触发 | `date: Date` - 选中的日期 |
+
+
+### AdCalendar Slots
+
+| 插槽名 | 说明 | 参数 |
+| ------ | ---- | ---- |
+| date-cell | 自定义日期单元格的内容, type 表示该日期的所属月份，可选值有 prev-month、current-month 和 next-month；isSelected 标明该日期是否被选中；day 是格式化的日期，格式为 yyyy-MM-dd；date 是单元格的日期 | `{ date: Date, data: { type: string, isSelected: boolean, day: string } }` |
+| header | 自定义日历头部的内容 | `{ date: string }` |
+| task-popover | 自定义甘特图弹窗的内容 | `{ day: string, task: Task }` |
+
+
+### GanttTask 数据结构
+```md
+export interface Task {
+    id: string | number;
+    name: string;
+    startTime: string;
+    endTime: string;
+    bgColor?: string;
+    brandColor?: string;
+}
+
+export interface CalendarProps{
+    modelValue?: MaybeDate;
+    range?: [Date, Date];
+    firstDayOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+    tasks?: Task[];
+    // 允许透传 Element Plus Calendar 的所有其他属性
+    [key: string]: any;
+}
+
+```
+

package/docs/components/design/color.md

@@ -0,0 +1,137 @@
+# Color 色彩
+
+M Design 的色彩系统旨在确保应用的一致性和视觉和谐。
+
+## 主色
+
+主色是品牌色，用于主要操作和强调。
+
+
+<ColorPalette :colors="[
+  { variable: '--m-color-primary-dark-2', value: '#092867', description: '深色 2' },
+  { variable: '--m-color-primary', value: '#0D3A93', description: '主色' },
+  { variable: '--m-color-primary-light-3', value: '#5574B3', description: '浅色 3' },
+  { variable: '--m-color-primary-light-5', value: '#7A93C4', description: '浅色 5' },
+  { variable: '--m-color-primary-light-7', value: '#9EB0D4', description: '浅色 7' },
+  { variable: '--m-color-primary-light-8', value: '#DBE5F4', description: '浅色 8' },
+  { variable: '--m-color-primary-light-9', value: '#F2F7FF', description: '浅色 9' }
+]" />
+
+
+## 功能色
+
+功能色用于表示不同的状态和反馈。
+
+### 成功色
+
+用于表示成功、完成等正面反馈。
+
+
+<ColorPalette :colors="[
+  { variable: '--m-color-success-dark-2', value: '#006F3D', description: '深色 2' },
+  { variable: '--m-color-success', value: '#009258', description: '成功色' },
+  { variable: '--m-color-success-light-3', value: '#0EAF6B', description: '浅色 3' },
+  { variable: '--m-color-success-light-5', value: '#29C583', description: '浅色 5' },
+  { variable: '--m-color-success-light-7', value: '#46D298', description: '浅色 7' },
+  { variable: '--m-color-success-light-8', value: '#8DEFC3', description: '浅色 8' },
+  { variable: '--m-color-success-light-9', value: '#EDFFF7', description: '浅色 9' }
+]" />
+
+
+### 警告色
+
+用于表示警告、需要用户注意的信息。
+
+<ColorPalette :colors="[
+  { variable: '--m-color-warning-dark-2', value: '#B25400', description: '深色 2' },
+  { variable: '--m-color-warning', value: '#FF6200', description: '警告色' },
+  { variable: '--m-color-warning-light-3', value: '#FF7800', description: '浅色 3' },
+  { variable: '--m-color-warning-light-5', value: '#FF8E31', description: '浅色 5' },
+  { variable: '--m-color-warning-light-7', value: '#FFA04C', description: '浅色 7' },
+  { variable: '--m-color-warning-light-8', value: '#FFCA9B', description: '浅色 8' },
+  { variable: '--m-color-warning-light-9', value: '#FFF6EF', description: '浅色 9' }
+]" />
+
+
+### 危险色 / 错误色
+
+用于表示错误、危险操作或需要立即注意的情况。
+
+
+<ColorPalette :colors="[
+  { variable: '--m-color-danger-dark-2', value: '#960000', description: '深色 2' },
+  { variable: '--m-color-danger', value: '#D70000', description: '危险色' },
+  { variable: '--m-color-error', value: '#D70000', description: '错误色（同危险色）' },
+  { variable: '--m-color-danger-light-3', value: '#E34C4C', description: '浅色 3' },
+  { variable: '--m-color-danger-light-5', value: '#EF9999', description: '浅色 5' },
+  { variable: '--m-color-danger-light-7', value: '#FBACAC', description: '浅色 7' },
+  { variable: '--m-color-danger-light-8', value: '#FFDCDC', description: '浅色 8' },
+  { variable: '--m-color-danger-light-9', value: '#FFF5F2', description: '浅色 9' }
+]" />
+
+
+### 信息色
+
+用于表示一般信息提示。
+
+
+<ColorPalette :colors="[
+  { variable: '--m-text-color-secondary', value: '#71777E', description: '信息色' },
+  { variable: '--m-text-color-placeholder', value: '#A8ABB2', description: '信息浅色' }
+]" />
+
+
+## 中性色
+
+中性色用于文本、背景和边框，提供清晰的视觉层次。
+
+### 文本颜色
+
+
+<ColorPalette :colors="[
+  { variable: '--m-text-color-primary', value: '#101316', description: '主要文本' },
+  { variable: '--m-text-color-regular', value: '#343D46', description: '常规文本' },
+  { variable: '--m-text-color-secondary', value: '#71777E', description: '次要文本' },
+  { variable: '--m-text-color-placeholder', value: '#A8ABB2', description: '占位文本' },
+  { variable: '--m-text-color-disabled', value: '#9AA4B2', description: '禁用文本' }
+]" />
+
+
+### 边框颜色
+
+
+<ColorPalette :colors="[
+  { variable: '--m-border-color-darker', value: '#CDD0D6', description: '更深边框' },
+  { variable: '--m-border-color-dark', value: '#D4D7DE', description: '深色边框' },
+  { variable: '--m-border-color', value: '#D6D8DA', description: '基础边框' },
+  { variable: '--m-border-color-light', value: '#E4E7ED', description: '浅色边框' },
+  { variable: '--m-border-color-lighter', value: '#EBEEF5', description: '更浅边框' },
+  { variable: '--m-border-color-extra-light', value: '#F2F6FC', description: '极浅边框' }
+]" />
+
+
+## 使用方式
+
+### CSS 变量
+
+M Design 使用 CSS 变量来管理颜色，推荐使用 `m-` 开头的变量。你可以在项目中直接使用这些变量：
+
+```css
+.my-component {
+  color: var(--m-color-primary);
+  background-color: var(--m-color-primary-light-9);
+  border-color: var(--m-border-color);
+}
+```
+
+> **注意**：`--el-*` 开头的变量是为了兼容 Element Plus 组件而自动映射的，推荐使用 `--ad-*` 开头的变量以便于覆盖和自定义。
+
+### 覆盖变量
+
+你可以通过重新定义 `--ad-*` 开头的变量来覆盖默认颜色值：
+
+```css
+:root {
+  --m-color-primary: #ff0000; /* 覆盖主色 */
+}
+```

package/docs/components/index.md

@@ -0,0 +1,3 @@
+# 组件总览
+
+<ComponentOverview />

package/docs/components/link.md

@@ -0,0 +1,65 @@
+# link 链接
+
+文字超链接
+
+## 基础用法
+
+基础的文字链接用法。
+
+:::preview
+
+demo-preview=../examples/link/index01.vue
+
+:::
+
+## 禁用状态
+
+文字链接不可用状态。
+
+:::preview
+
+demo-preview=../examples/link/index02.vue
+
+:::
+
+## 下划线
+
+控制下划线是否出现
+
+:::preview
+
+demo-preview=../examples/link/index03.vue
+
+:::
+
+## 带图标的链接
+
+使用 icon 属性来为按钮添加图标。 您可以传递组件名称的字符串（提前注册）或组件本身是一个 SVG Vue 组件。
+
+:::preview
+
+demo-preview=../examples/link/index04.vue
+
+:::
+
+## Link API
+
+### Link Attributes
+
+| 属性名 | 说明 | 类型     | 默认值 |
+| ------ | ---- | -------- | ------ |
+| type    | 类型  | `'default' \| 'primary' \| 'success' \| 'warning' \| 'info' \| 'danger'` | `'default'`     |
+| underline | 是否显示下划线 | `'always' \| 'hover' \| 'never' \| boolean` | `'never'` |
+| disabled | 是否禁用 | `boolean` | `false` |
+| href | 链接地址 | `string` | `''` |
+| target | 链接跳转方式 | `string` | `'_self'` |
+| icon | 图标组件 | `Component` | — |
+
+
+
+### Link Slots
+
+| 插槽名 | 说明 |
+| ------ | ---- | 
+| default    | 自定义默认内容  |
+| icon    | 自定义图标组件  |

package/docs/components/search-panel.md

@@ -0,0 +1,53 @@
+# Search Panel 查询面板
+
+通用列表页的查询面板样式。支持列数配置和展开收起功能。
+
+## 基础用法
+
+通用列表页的查询面板样式。支持列数配置。当表单项数量超过 `visible-count` 时，会自动显示展开/收起按钮。
+
+:::preview
+
+demo-preview=../examples/search-panel/index.vue
+
+:::
+
+## 无展开收起
+
+如果表单数较少情况下，可以配置无展开收起。
+
+:::preview
+
+demo-preview=../examples/search-panel/nowrap.vue
+
+:::
+
+## SearchPanel API
+
+### SearchPanel Attributes
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | -------- | ------ |
+| default-span | 默认列宽（基于 24 栅格系统） | `number` | `8` |
+| gutter | 栅格间距（单位：px） | `number` | `16` |
+| visible-count | 折叠时显示的表单项数量，超过此数量会显示展开/收起按钮 | `number` | `6` |
+| expandable | 是否可展开收起 | `boolean` | `true` |
+
+### SearchPanel Events
+
+| 事件名 | 说明 | 参数 |
+| ------ | ---- | ---- |
+| search | 点击查询按钮时触发 | `(fields: object, formInstance: FormInstance) => void` |
+| reset | 点击重置按钮时触发 | `(formInstance: FormInstance) => void` |
+
+### SearchPanel Slots
+
+| 插槽名 | 说明 |
+| ------ | ---- |
+| default | 自定义默认内容，用于放置 `ad-form` 或 `el-form` 表单组件 |
+
+### SearchPanel Exposes
+
+| 方法名 | 说明 | 类型 |
+| ------ | ---- | ---- |
+| getForm | 获取表单实例的方法 | `() => FormInstance` |

package/docs/components/table-grid.md

@@ -0,0 +1,120 @@
+# 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' }` |
+| showCard | 是否显示表格卡片 | `boolean` | `true` |
+| cardShadow | 卡片阴影效果 | `string` | `'hover'` |
+| 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` |
+| show | 是否显示，函数返回布尔值 | `(row: any) => boolean` | — |
+| 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 | 工具栏右侧内容 | — |
+| tableCardName | 表格卡片标题 | — |
+| header-${prop} | 自定义列头，`${prop}` 为列的 `prop` 值 | `{ column, $index }` |
+| action | 自定义操作列内容 | `{ row }` |
+
+### TableGrid Exposes
+
+| 方法名 | 说明 | 类型 |
+| ------ | ---- | ---- |
+| getPagination | 获取分页配置对象 | `() => PaginationConfig` |
+