mvframe 1.0.82 → 1.0.83

package/.cursor/rules/style-system.mdc

@@ -238,6 +238,51 @@ alwaysApply: true
 | `tipbtn bottom/left/right` | 控制提示方向 |
 | `MvcIcon` | 组件图标类，默认 `flex-shrink: 0` |
 
+### 表单 Label（element.scss）
+
+`Input`、`Textarea`、`Select`、`SelectV2` 支持统一的 label 接口：
+
+| 属性 | 用途 |
+|------|------|
+| `label` | 显示表单标题 |
+| `material-label` | 启用 Material 风格浮动 label |
+
+使用规则：
+
+- 只传 `label`：渲染为普通上方标题
+- 传 `label` + `material-label`：渲染为 Material 风格浮动标签
+- 不传 `label`：保持原组件默认外观
+
+Material 风格的上浮条件：
+
+- 当前控件有值
+- 当前控件有 placeholder
+- 当前控件处于 focus / 打开状态（Select / SelectV2）
+
+推荐写法：
+
+```vue
+<Input v-model="form.name" label="Name" />
+<Input v-model="form.name" label="Material Name" material-label />
+
+<Textarea v-model="form.remark" label="Remark" />
+<Textarea v-model="form.remark" label="Material Remark" material-label />
+
+<Select v-model="form.type" :options="options" label="Type" />
+<Select
+  v-model="form.type"
+  :options="options"
+  label="Material Type"
+  material-label
+/>
+```
+
+约束：
+
+- Material label 的壳样式统一在 `src/style/chip/element.scss`，不要在业务组件里重复写一套 scoped 浮动 label
+- 如果要做 Material 风格，优先直接使用 `label` + `material-label`，不要再额外包一层自定义标题
+- 如需特殊背景色，优先通过 field surface 相关变量覆写，不要直接把 label 写死成固定背景色
+
 ## 7. 动画（ani.scss）
 
 | 类名 | 用途 |

package/README.cn.md

@@ -220,6 +220,29 @@ await notify("需要发送到钉钉的消息");
 - **组件 class 与单位**：根节点 `Mvc*` + 子命名 camelCase；组件内尺寸除 1px/2px 外建议 **rem**（根号 16px），与 `style-system.mdc` 一致。  
 - 工具函数、Store、路由在非 setup 场景（如守卫）中通过 **`globalThis`** 或 **`store` / `pinia` 导出**访问，与 `src/router/chip/guard.js` 用法一致。
 
+## 表单 Label
+
+`Input`、`Textarea`、`Select`、`SelectV2` 现已支持统一的 label 接口：
+
+```vue
+<Input v-model="form.name" label="Name" />
+<Input v-model="form.name" label="Material Name" material-label />
+
+<Textarea v-model="form.remark" label="Remark" />
+<Textarea v-model="form.remark" label="Material Remark" material-label />
+
+<Select v-model="form.type" :options="options" label="Type" />
+<Select v-model="form.type" :options="options" label="Material Type" material-label />
+```
+
+规则：
+
+- 只传 `label`：渲染普通上方标题
+- 传 `label` + `material-label`：渲染 Material 风格浮动标签
+- 不传 `label`：保持组件默认外观
+
+浮动 label 的公共壳样式统一实现在 `src/style/chip/element.scss`。如果你希望表单控件呈现 Material 风格，优先直接使用 `label` + `material-label`，不要在业务侧再重复造一套浮动标题样式。
+
 ---
 
 ## 命令行：项目目录雏形（推荐）

package/README.md

@@ -207,6 +207,29 @@ Send messages with `globalThis.$notify.send("message")` or `import { notify } fr
 - **CSS naming & units**: root `Mvc*`, children camelCase; prefer **rem** for sizes other than 1px/2px (16px root)—see `style-system.mdc`.  
 - Use **`globalThis`** or **`store` / `pinia` exports** outside `setup` (e.g. guards), as in `src/router/chip/guard.js`.
 
+## Form Labels
+
+`Input`, `Textarea`, `Select`, and `SelectV2` support a shared label API:
+
+```vue
+<Input v-model="form.name" label="Name" />
+<Input v-model="form.name" label="Material Name" material-label />
+
+<Textarea v-model="form.remark" label="Remark" />
+<Textarea v-model="form.remark" label="Material Remark" material-label />
+
+<Select v-model="form.type" :options="options" label="Type" />
+<Select v-model="form.type" :options="options" label="Material Type" material-label />
+```
+
+Rules:
+
+- `label` only: renders a normal top label
+- `label` + `material-label`: renders a Material-style floating label
+- no `label`: keeps the default control appearance
+
+The floating label shell is implemented centrally in `src/style/chip/element.scss`. When you want a Material-style form field, prefer the built-in `label` + `material-label` API instead of recreating the same pattern locally.
+
 ---
 
 ## CLI: project skeleton

package/dist/vendor.js

@@ -7798,7 +7798,7 @@ const As = (e, o = {}) => {
 }, Cs = {
   name: "Matt Avias Frame",
   copyright: "©2026",
-  version: "1.0.82",
+  version: "1.0.83",
   author: "Matt Avias",
   date: "2026-02-26",
   /** 默认语言 key，与 `$getLang`、localStorage `lang` 一致；业务在 app.use(mvframe, { config }) 里覆盖 */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mvframe",
   "packageManager": "yarn@4.4.1",
-  "version": "1.0.82",
+  "version": "1.0.83",
   "author": "matt avis",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/scripts/scaffold-app.js

@@ -867,6 +867,29 @@ yarn exec mvframe-d
 
 \`src/main.js\` 已包含 \`import "mvframe/style"\` 与 \`import "mvframe/style/cpt"\`（分别对应工具类/变量与 **Mvc\*** 组件 scoped 等样式），一般 **无需** 在 \`index.scss\` 再引一遍 mvframe 的 dist CSS，以免重复。项目级覆盖写在 \`src/assets/style/index.scss\` 即可。
 
+## 表单 Label
+
+\`Input\`、\`Textarea\`、\`Select\`、\`SelectV2\` 支持统一的 label 接口：
+
+\`\`\`vue
+<Input v-model="form.name" label="Name" />
+<Input v-model="form.name" label="Material Name" material-label />
+
+<Textarea v-model="form.remark" label="Remark" />
+<Textarea v-model="form.remark" label="Material Remark" material-label />
+
+<Select v-model="form.type" :options="options" label="Type" />
+<Select v-model="form.type" :options="options" label="Material Type" material-label />
+\`\`\`
+
+规则：
+
+- 只传 \`label\`：渲染普通上方标题
+- 传 \`label\` + \`material-label\`：渲染 Material 风格浮动标签
+- 不传 \`label\`：保持组件默认外观
+
+Material 风格 label 的公共壳样式统一在 \`src/style/chip/element.scss\`。如果你要做 Material 风格表单，优先直接使用 \`label\` + \`material-label\`，不要在业务侧再重复写一套浮动标题。
+
 ## 子路径（按需）
 
 发布包 \`exports\` 还提供 \`mvframe/composition\`、\`mvframe/util\`、\`mvframe/store\`、\`mvframe/notify\` 等，业务侧可 \`import { ... } from "mvframe/composition"\` 等，参见包内 \`package.json\` 的 \`exports\`。