@morya-ui/setup 0.2.5

package/template/docs/components.md

@@ -0,0 +1,144 @@
+# Morya UI 组件清单（AI 选型索引）
+
+> 完整 API 以文档站 `/components` 或 MCP 为准。下表用于**场景选型**，不是 prop 手册。
+
+## 应用壳层
+
+| 组件 | 用途 |
+| --- | --- |
+| `MConfigProvider` | 根配置：locale、主题、密度、浮层挂载、组件默认 props |
+| `MLayout` / `MLayoutHeader` / `MLayoutSider` / `MLayoutContent` / `MLayoutFooter` | 后台整体布局 |
+| `MSidebar` | 独立侧栏容器（非 Layout 子项场景） |
+| `MBreadcrumb` | 页面路径 |
+| `MToolbar` | 顶栏工具区 |
+
+## 表单 · 输入
+
+| 组件 | 用途 |
+| --- | --- |
+| `MForm` / `MFormItem` | 表单容器、校验、提交 |
+| `MInput` | 单行文本 |
+| `MInputPassword` | 密码 |
+| `MInputNumber` | 数字 |
+| `MTextarea` | 多行文本 |
+| `MSelect` | 下拉选择（单选/多选/远程/filter） |
+| `MTreeSelect` | 树形选择 |
+| `MCascadeSelect` | 级联选择 |
+| `MDatePicker` | 日期 / 日期范围 |
+| `MAutoComplete` | 自动完成 |
+| `MCheckbox` / `MCheckboxGroup` | 多选 |
+| `MRadio` / `MRadioGroup` | 单选组 |
+| `MSwitch` | 开关 |
+| `MSlider` | 滑块 |
+| `MRating` | 评分 |
+| `MInputTags` | 标签输入 |
+| `MFileUpload` | 文件上传 |
+| `MFloatLabel` | 浮动标签包装 |
+| `MIconField` | 输入框前缀/后缀图标 |
+
+## 表单 · 布局
+
+| 组件 | 用途 |
+| --- | --- |
+| `MGrid` / `MGridItem` | 响应式栅格 |
+| `MFlex` | Flex 布局 |
+| `MSpace` | 间距 |
+| `MFluid` | 子项撑满宽度 |
+| `MDivider` | 分隔线 |
+| `MFieldset` | 分组fieldset |
+
+## 数据展示
+
+| 组件 | 用途 |
+| --- | --- |
+| `MTable` | 数据表格 |
+| `MTreeTable` | 树形表格 |
+| `MDataView` | 卡片/列表数据视图 |
+| `MTree` | 树 |
+| `MPagination` | 分页 |
+| `MStatus` | 行内状态（圆点 + 文案） |
+| `MTag` / `MChip` / `MBadge` | 标签、徽章 |
+| `MAvatar` / `MAvatarGroup` | 头像 |
+| `MTimeline` | 时间线 |
+| `MMeterGroup` | 多段进度条 |
+| `MVirtualScroller` | 虚拟滚动长列表 |
+
+## 反馈
+
+| API / 组件 | 用途 | 优先级 |
+| --- | --- | --- |
+| `message` | **默认**：单行操作回执（已保存 / 已删除） | ★ 首选 |
+| `toast` | 仅当需要 `summary` + `detail` 或异步通知 | 次要 |
+| `<MMessage>` | 表单/认证区**常驻**错误条 | 内嵌场景 |
+| `MEmpty` | 无数据 / 首次使用 / 筛选无结果 | 空态 |
+| `MResult` | 提交结果、403 / 404 / 500 等阻断页 | 结果页 |
+| `MProgressBar` / `MProgressSpinner` | 加载进度 | |
+| `MSkeleton` | 骨架屏 | |
+| `MBlockUI` | 遮罩阻塞 | |
+
+选型细则：[`feedback-message-vs-toast.md`](./feedback-message-vs-toast.md)
+
+## 浮层
+
+| 组件 | 用途 |
+| --- | --- |
+| `MDialog` | 模态对话框 |
+| `MDrawer` | 抽屉 |
+| `MConfirmDialog` / `MConfirmPopup` | 二次确认 |
+| `MPopover` | 气泡卡片 |
+| `MTooltip` | 文字提示 |
+| `MDropdown` | **动作**下拉菜单（非表单选项） |
+
+## 导航 · 菜单
+
+| 组件 | 用途 |
+| --- | --- |
+| `MMenu` / `MMenubar` / `MTieredMenu` / `MMegaMenu` | 菜单 |
+| `MTabs` | 标签页 |
+| `MStepper` | 步骤条 |
+| `MCommandMenu` | 命令面板 |
+| `MSplitButton` / `MSelectButton` / `MToggleButton` | 复合按钮 |
+
+## 展示 · 媒体
+
+| 组件 | 用途 |
+| --- | --- |
+| `MCard` / `MPanel` | 卡片、面板 |
+| `MAccordion` | 折叠面板 |
+| `MCarousel` / `MGallery` | 轮播、图库 |
+| `MIcon` | 图标（Tabler 集） |
+| `MScrollbar` | 主题化滚动条；供组件内置滚动壳与业务显式选用；不要塞进用户可定制插槽 |
+
+## 场景速查
+
+| 我要做… | 首选组件 |
+| --- | --- |
+| 用户列表 + 搜索 + 分页 | `MTable` + `MInput` + `MPagination` |
+| 新建/编辑实体 | `MForm` + 字段组件 + `MDialog` 或独立路由页 |
+| 删除确认 | `MConfirmDialog` |
+| 筛选侧栏 | `MDrawer` + 表单控件 |
+| 状态指示（行内） | `MStatus`（圆点 + 文案） |
+| 状态芯片 / 可关闭标签 | `MTag`（`severity`: success/warn/danger/info） |
+| 空数据 / 首次使用 | `MEmpty` |
+| 提交结果 / 403 / 404 / 500 | `MResult` |
+| 主/次按钮组 | `MSpace` + `MButton`（primary / secondary text） |
+| 后台首页 KPI | `MGrid` + `MCard` |
+| 组织架构 | `MTree` 或 `MTreeSelect` |
+| 整页后台页（MCP 生成） | `MLayout fillViewport`（主滚动内置 `MScrollbar`） |
+| 业务局部限高滚动 | 业务自行使用 `MScrollbar`（可选：`get_page_snippet("scrollable-panel")`） |
+
+## 页面标准
+
+MCP `get_design_rules` → `standards` 汇总推荐实践（非强制）。`validate_page` 仅给参考建议。
+
+## 常见对照
+
+| 错误 | 正确 |
+| --- | --- |
+| 用 `MDropdown` 做表单枚举 | 用 `MSelect` |
+| 手写 `<table>` | 用 `MTable` |
+| 手写 modal div | 用 `MDialog` |
+| `showClear` 与 `clearable` 混用概念 | Select 两者等价；其他组件看文档是否支持 `clearable` |
+| 页面壳手写 `overflow: auto` 替代 Layout 内置滚动 | 依赖 `MLayout` 内置滚动；业务局部滚动再显式用 `MScrollbar` |
+| `MPage*` 外包 `MCard` 或 padded `div` | 直接使用 `MPage*` 组件自带间距与表面 |
+| 嵌套菜单被滚动容器裁剪 | Dropdown / ContextMenu / TieredMenu 侧向子菜单已 Teleport；Menu 水平/折叠飞出层用 Popover |

package/template/docs/feedback-message-vs-toast.md

@@ -0,0 +1,103 @@
+# Message / Toast / MMessage 选型指南
+
+> **AI 默认规则：操作反馈优先用 `message` API；只有需要「标题 + 详情」或异步通知时才用 `toast`。**
+
+## 三个不同的东西
+
+| 名称 | 形态 | API / 组件 | 典型场景 |
+| --- | --- | --- | --- |
+| **Message 服务** | 顶部居中（可改 placement）单行浮层 | `message.success('已保存')` | **大多数** CRUD / 保存 / 删除回执 |
+| **Toast 服务** | 四角通知，带 `summary` + 可选 `detail` | `toast.success({ summary, detail })` | 需要补充说明的通知、后台任务结果 |
+| **MMessage 组件** | 页面内嵌条，不自动消失 | `<MMessage severity="error">…</MMessage>` | 表单/认证区**常驻**错误、警告 |
+
+## 决策树（按顺序判断）
+
+```
+用户操作完成，需要即时反馈？
+├─ 否 → 不需要 Message/Toast（可能用 MConfirmDialog / 字段 errorMessage）
+└─ 是 → 错误需留在表单区域直到用户修正？
+    ├─ 是 → 字段 invalid / errorMessage；表单级用 token 告警条（见 login-page）
+    └─ 否 → 只有一句短文案（无独立 detail）？
+        ├─ 是 → message.success / info / warn / error   ← 默认选这个
+        └─ 否 → 有 summary + detail，或异步/后台通知感 → toast.*
+```
+
+## 优先用 Message 的场景（占多数）
+
+- 创建 / 更新 / 删除成功：`message.success('已保存')`
+- 移入回收站、批量操作完成（单行概括）：`message.info('已移入回收站')`
+- 轻量警告（非表单绑定）：`message.warn('请先选择记录')`
+- 请求失败（单行）：`message.error('保存失败，请重试')`
+- 复制成功、导入触发等**一句话**反馈
+
+```ts
+import { message } from 'morya-ui'
+
+message.success('已创建')
+message.info('已移入回收站')
+message.error('操作失败')
+```
+
+## 应该用 Toast 的场景（较少）
+
+- **同时**需要标题与补充说明：
+
+  ```ts
+  toast.success({
+    summary: '选课申请已提交',
+    detail: '请等待教务审核',
+  })
+  ```
+
+- 后台任务 / 批量结果含统计明细：
+
+  ```ts
+  toast.success({
+    summary: '导入完成',
+    detail: '成功 128 条，失败 2 条',
+  })
+  ```
+
+- 登录成功且需欢迎语 + 副文案
+- 需要角落堆叠、用户可能稍后查看的多条**通知**（非即时操作回执）
+
+## 应该用表单区常驻错误的场景
+
+- 登录 / 注册表单上方的**持久**错误（用户修正前不消失）
+- 页面级配置错误、需要与表单同区域的警告条
+- **不要**把字段校验错误只丢到 Toast/Message 浮层——优先字段 `errorMessage`
+
+字段级：
+
+```vue
+<MInput v-model="email" invalid :error-message="emailError" />
+```
+
+表单级（见 `docs/golden-pages/login-page.vue`）：用 `--m-*` 样式的 `role="alert"` 条。  
+说明：`<MMessage>` 当前主要是 `message` 服务的挂载宿主，**不要**臆造 `severity` + 默认插槽的 Alert API。
+
+```vue
+<p v-if="error" class="form-alert" role="alert">{{ error }}</p>
+```
+## 反模式（AI 禁止）
+
+| 反模式 | 应改为 |
+| --- | --- |
+| `toast.add({ summary: '已保存' })` 无 detail | `message.success('已保存')` |
+| 表单校验失败只弹 Toast | 字段 `errorMessage` 或 `<MMessage>` |
+| 删除确认用 Message/Toast | `MConfirmDialog` |
+| 所有反馈都用 Toast | 默认改 Message，仅 detail 场景保留 Toast |
+
+## 与 Naive / Element Plus 的对应
+
+| Morya UI | 近似概念 |
+| --- | --- |
+| `message` | Naive `message` / Element `ElMessage` |
+| `toast` | Naive `notification` / Element `ElNotification` |
+| `<MMessage>` | 页面内 `el-alert` / 表单顶部错误条 |
+
+## 相关文档
+
+- [Message 组件文档](../../src/components/Message/docs/index.md)
+- [Toast 组件文档](../../src/components/Toast/docs/index.md)
+- [DESIGN.md §6 浮层与反馈](../DESIGN.md#6-浮层与反馈)

package/template/docs/golden-pages/dashboard-page.vue

@@ -0,0 +1,103 @@
+<script setup lang="ts">
+/**
+ * 黄金样例：仪表盘页
+ * @see DESIGN.md §3
+ */
+import {
+  MBreadcrumb,
+  MCard,
+  MConfigProvider,
+  MGrid,
+  MGridItem,
+  MLayout,
+  MLayoutContent,
+  MLayoutHeader,
+  MPageContent,
+  MPageHeader,
+  MPagePlaceholder,
+  MPageStat,
+  MTable,
+  MTag,
+  zhCN,
+} from 'morya-ui'
+
+const stats = [
+  { label: '总用户', value: '12,480', trend: '+8.2%', icon: 'users' },
+  { label: '今日活跃', value: '1,926', trend: '+3.1%', icon: 'activity' },
+  { label: '待处理工单', value: '47', trend: '-12%', trendSeverity: 'warn' as const, icon: 'clipboard' },
+  { label: '系统健康', value: '99.9%', trend: '稳定', trendSeverity: 'secondary' as const, icon: 'heart' },
+]
+
+const recentColumns = [
+  { key: 'id', label: '工单号', width: 96 },
+  { key: 'title', label: '标题' },
+  { key: 'priority', label: '优先级', width: 96 },
+  { key: 'status', label: '状态', width: 96 },
+]
+
+const recentRows = [
+  { id: 'WO-1024', title: '登录异常反馈', priority: 'high', status: 'open' },
+  { id: 'WO-1023', title: '导出任务超时', priority: 'medium', status: 'progress' },
+  { id: 'WO-1022', title: '权限配置咨询', priority: 'low', status: 'done' },
+]
+
+function prioritySeverity(p: string) {
+  if (p === 'high') return 'danger'
+  if (p === 'medium') return 'warn'
+  return 'secondary'
+}
+
+function statusLabel(s: string) {
+  if (s === 'open') return '待处理'
+  if (s === 'progress') return '进行中'
+  return '已完成'
+}
+</script>
+
+<template>
+  <MConfigProvider :locale="zhCN">
+    <MLayout fill-viewport>
+      <MLayoutHeader padding="var(--m-space-4) var(--m-space-6)">
+        <MBreadcrumb :model="[{ label: '首页' }, { label: '仪表盘' }]" />
+      </MLayoutHeader>
+
+      <MLayoutContent>
+        <MPageContent density="spacious">
+          <MPageHeader title="仪表盘" />
+
+          <MGrid :cols="4" :x-gap="16" :y-gap="16" responsive="screen">
+            <MGridItem v-for="item in stats" :key="item.label" :span="1">
+              <MPageStat
+                :label="item.label"
+                :value="item.value"
+                :trend="item.trend"
+                :trend-severity="item.trendSeverity ?? 'primary'"
+                :icon="item.icon"
+              />
+            </MGridItem>
+          </MGrid>
+
+          <MGrid :cols="2" :x-gap="16" :y-gap="16">
+            <MGridItem :span="1">
+              <MCard title="趋势概览">
+                <MPagePlaceholder aria-label="图表占位" description="图表区域（接入 ECharts / 业务组件）" />
+              </MCard>
+            </MGridItem>
+            <MGridItem :span="1">
+              <MCard title="最近工单">
+                <MTable :columns="recentColumns" :rows="recentRows" size="small" :paginator="false" bordered>
+                  <template #cell-priority="{ value }">
+                    <MTag :value="String(value)" :severity="prioritySeverity(String(value))" />
+                  </template>
+                  <template #cell-status="{ value }">
+                    <MTag :value="statusLabel(String(value))" severity="info" />
+                  </template>
+                </MTable>
+              </MCard>
+            </MGridItem>
+          </MGrid>
+        </MPageContent>
+      </MLayoutContent>
+    </MLayout>
+  </MConfigProvider>
+</template>

package/template/docs/golden-pages/empty-state.vue

@@ -0,0 +1,66 @@
+<script setup lang="ts">
+/**
+ * 黄金样例：列表空状态（Flow）
+ * @see DESIGN.md §3 · morya-ui-pages surfaces § Flow
+ * 可嵌在列表页 MPageContent / MTable #empty 中；此处给出完整可运行骨架。
+ */
+import {
+  MBreadcrumb,
+  MButton,
+  MConfigProvider,
+  MEmpty,
+  MLayout,
+  MLayoutContent,
+  MLayoutHeader,
+  MPageContent,
+  MPageToolbar,
+  zhCN,
+} from 'morya-ui'
+</script>
+
+<template>
+  <MConfigProvider :locale="zhCN">
+    <MLayout fill-viewport>
+      <MLayoutHeader padding="var(--m-space-4) var(--m-space-6)">
+        <MBreadcrumb :model="[{ label: '首页', to: '/' }, { label: '课程' }]" />
+      </MLayoutHeader>
+
+      <MLayoutContent>
+        <MPageContent>
+          <MPageToolbar title="课程">
+            <template #actions>
+              <MButton label="新建课程" />
+            </template>
+          </MPageToolbar>
+
+          <div class="empty-state-shell">
+            <MEmpty
+              title="还没有课程"
+              description="创建第一门课程后，学员就能在目录里看到它。也可以稍后从模板导入。"
+              icon="book"
+            >
+              <template #extra>
+                <MButton label="创建第一门课程" />
+                <MButton label="从模板导入" severity="secondary" text />
+              </template>
+            </MEmpty>
+          </div>
+        </MPageContent>
+      </MLayoutContent>
+    </MLayout>
+  </MConfigProvider>
+</template>
+
+<style scoped>
+.empty-state-shell {
+  border: 1px dashed color-mix(in srgb, var(--m-color-border) 80%, var(--m-color-primary));
+  border-radius: var(--m-radius-md);
+  background:
+    radial-gradient(
+      120% 80% at 50% 0%,
+      color-mix(in srgb, var(--m-color-primary) 10%, transparent),
+      transparent 55%
+    ),
+    var(--m-color-surface);
+}
+</style>

package/template/docs/golden-pages/form-page.vue

@@ -0,0 +1,107 @@
+<script setup lang="ts">
+/**
+ * 黄金样例：表单页
+ * @see DESIGN.md §3
+ */
+import {
+  MBreadcrumb,
+  MButton,
+  MConfigProvider,
+  MDatePicker,
+  MForm,
+  MFormItem,
+  MInput,
+  MLayout,
+  MLayoutContent,
+  MLayoutHeader,
+  MPageContent,
+  MPageHeader,
+  MPageSection,
+  MSelect,
+  MSpace,
+  MSwitch,
+  MTextarea,
+  zhCN,
+} from 'morya-ui'
+import { reactive, ref } from 'vue'
+
+const submitting = ref(false)
+
+const model = reactive({
+  name: '',
+  email: '',
+  role: undefined as string | undefined,
+  active: true,
+  joinedAt: null as string | null,
+  bio: '',
+})
+
+const roleOptions = [
+  { label: '管理员', value: 'admin' },
+  { label: '成员', value: 'member' },
+]
+
+async function onSubmit() {
+  submitting.value = true
+  try {
+    // await api.save(model)
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <MConfigProvider :locale="zhCN">
+    <MLayout fill-viewport>
+      <MLayoutHeader padding="var(--m-space-4) var(--m-space-6)">
+        <MBreadcrumb :model="[{ label: '首页', to: '/' }, { label: '用户管理', to: '/users' }, { label: '新建用户' }]" />
+      </MLayoutHeader>
+
+      <MLayoutContent>
+        <MPageContent width="narrow">
+          <MPageHeader title="新建用户" description="填写基本信息并分配角色。" />
+
+          <MPageSection variant="form">
+            <MForm @submit="onSubmit">
+              <MFormItem label="姓名" name="name" required>
+                <MInput v-model="model.name" placeholder="请输入姓名" fluid />
+              </MFormItem>
+
+              <MFormItem label="邮箱" name="email" required>
+                <MInput v-model="model.email" type="email" placeholder="name@example.com" fluid />
+              </MFormItem>
+
+              <MFormItem label="角色" name="role" required>
+                <MSelect v-model="model.role" :options="roleOptions" placeholder="请选择角色" fluid />
+              </MFormItem>
+
+              <MFormItem label="入职日期" name="joinedAt">
+                <MDatePicker v-model="model.joinedAt" placeholder="选择日期" fluid />
+              </MFormItem>
+
+              <MFormItem label="启用账号" name="active">
+                <MSwitch v-model="model.active" />
+              </MFormItem>
+
+              <MFormItem label="简介" name="bio">
+                <MTextarea v-model="model.bio" :rows="4" placeholder="可选" fluid />
+              </MFormItem>
+
+              <MPageSection variant="actions">
+                <MSpace>
+                  <MButton native-type="submit" severity="primary" :loading="submitting">
+                    保存
+                  </MButton>
+                  <MButton severity="secondary">
+                    取消
+                  </MButton>
+                </MSpace>
+              </MPageSection>
+            </MForm>
+          </MPageSection>
+        </MPageContent>
+      </MLayoutContent>
+    </MLayout>
+  </MConfigProvider>
+</template>