mvframe 1.0.94 → 1.0.96

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

@@ -11,7 +11,7 @@ alwaysApply: true
 - **`alwaysApply: true` 只作用于 Cursor**：把本文件当作对话上下文里的规范读给 AI，**不会**在构建时自动给任何 `.vue` 挂上样式，也**不等于**工具类已生效。
 - **运行时要用工具类**，必须在应用入口（如 demo `main.js`、宿主项目）**已 `import` `mvframe` 的 `src/style/index.scss`（或包导出的 `style`）**；然后在组件 **template 里写上工具类名**（如 `flexMode`、`g16`、`fs14`），尽量少写与工具类等价的 scoped 声明。
 
-样式入口为 `src/style/index.scss`，按模块拆分为 `chip/*.scss`。
+样式入口为 `src/style/index.scss`，按模块拆分为 `chip/*.scss`。宿主项目如果只消费发布包，直接 `import "mvframe/style"` 即可拿到全局工具类；如果要在业务 SCSS 里复用框架断点 mixin，用 `@use "mvframe/style/mixin" as *;`。
 
 ## 1. 变量与颜色（var.scss）
 
@@ -166,6 +166,81 @@ alwaysApply: true
 - `g{N}`：gap，N=2~40（步长 2）
 - `mauto`：margin-inline auto
 
+## 4.1 响应式（media.scss + mixin.scss）
+
+### 断点
+
+| 名称 | 范围 |
+|------|------|
+| `xs` | `< 40rem`（< 640px） |
+| `sm` | `40rem ~ 47.99875rem`（640px ~ 767.98px） |
+| `md` | `48rem ~ 63.99875rem`（768px ~ 1023.98px） |
+| `lg` | `64rem ~ 79.99875rem`（1024px ~ 1279.98px） |
+| `xl` | `80rem ~ 95.99875rem`（1280px ~ 1535.98px） |
+| `xxl` | `>= 96rem`（>= 1536px） |
+
+### SCSS mixin
+
+- `@include media-up(md) { ... }`：`md` 及以上
+- `@include media-down(md) { ... }`：`md` 及以下
+- `@include media-only(md) { ... }`：仅 `md`
+- `@include media-between(sm, lg) { ... }`：`sm` 到 `lg`
+
+宿主项目若使用发布包，可直接在业务 SCSS 中：
+
+```scss
+@use "mvframe/style/mixin" as *;
+
+.panel {
+  padding: 1.5rem;
+
+  @include media-down(sm) {
+    padding: 1rem;
+  }
+}
+```
+
+### 响应式工具类
+
+`media.scss` 额外提供一批按断点包裹的全局工具类，命名为 `断点-范围-工具类`：
+
+- 范围：`up` / `down` / `only`
+- 工具类：`hide`、`block`、`inline`、`inlineBlock`、`flexMode`、`inlineFlex`、`grid`、`flexV`、`flexV-1`、`flexWrap`、`flexWrap-1`、`hl`、`hb`、`ha`、`hc`、`hr`、`vl`、`vr`、`vc`、`vs`、`txt-c`、`txt-r`
+
+示例：
+
+- `class="md-down-hide"`：`md` 及以下隐藏
+- `class="lg-up-flexMode lg-up-hb lg-up-vc"`：`lg` 及以上切到横向 flex 并两端对齐
+- `class="xs-only-block sm-only-hide"`：只在手机端显示
+
+### Grid 断点列数类
+
+如果容器同时带有 `grid`，可直接写 `断点+列数` 来按屏宽切列数：
+
+- `grid col2 md2 lg3 sm1`
+- `grid col1 md2 xl4`
+
+规则：
+
+- `col{N}`：默认列数（所有屏宽的基础值）
+- `xs{N}` / `sm{N}` / `md{N}` / `lg{N}` / `xl{N}` / `xxl{N}`：仅在该断点区间覆盖 `grid-template-columns`
+- 列数当前支持 `1~12`
+
+示例：
+
+```html
+<div class="grid col2 md2 lg3 sm1 g16">
+  ...
+</div>
+```
+
+含义：
+
+- 默认 2 列
+- `sm` 屏 1 列
+- `md` 屏 2 列
+- `lg` 屏 3 列
+
 ## 5. 其它样式（other.scss / static.scss）
 
 ### 全局重置与基础

package/README.cn.md

@@ -20,6 +20,7 @@
 - `"./composition"` → `dist/composition.js`（`import { useMap, … } from 'mvframe/composition'`）
 - `"./store"`、`"./directive"`、`"./util"` → 对应 `dist` 下分包
 - `"./notify"` → `dist/notify.js`（浏览器端请求本地 `mvframe-notify` 服务的通知 helper）
+- `"./style/mixin"` → `src/style/chip/mixin.scss`（宿主项目 SCSS 可复用的断点 / 通用 mixin）
 - `"./style"` → `dist/css/style.css`（由 `src/style/index.scss` 单独入口打包的全量工具类/变量）
 - `"./style/cpt"` → `dist/css/cpt.css`（随组件抽取的样式；一般用 `mvframe/style` 即可）
 
@@ -147,8 +148,25 @@ app.use(mvframe, {
 
 - 工具类与变量说明见 `.cursor/rules/style-system.mdc`（`--color-*`、间距、字体、布局类等）。  
 - SCSS 会通过 `vite.config.js` 的 **`additionalData`** 注入 **`src/style/chip/mixin.scss`**，与库同构构建的业务项目可保持一致配置。  
+- 响应式断点统一在 `mixin.scss`：`xs / sm / md / lg / xl / xxl`；业务 SCSS 可直接 `@use "mvframe/style/mixin" as *;`，然后使用 `@include media-up(md)`、`media-down(md)`、`media-only(md)`、`media-between(sm, lg)`。  
+- 发布包的 `mvframe/style` 里已内置一组响应式工具类：`{断点}-{up|down|only}-{工具类}`，例如 `md-down-hide`、`lg-up-flexMode`、`xs-only-block`。  
+- Grid 容器还支持断点列数类：`class="grid col2 md2 lg3 sm1"`，表示默认 2 列，`sm` 1 列，`md` 2 列，`lg` 3 列。  
 - 发布包可 **`import 'mvframe/style'`**（即 `dist/css/style.css`）；需与 Element Plus 等并存时仍可在业务工程中链入源码 **`src/style/index.scss`** 以便覆写变量。
 
+业务侧示例：
+
+```scss
+@use "mvframe/style/mixin" as *;
+
+.BillingPanel {
+  padding: 1.5rem;
+
+  @include media-down(sm) {
+    padding: 1rem;
+  }
+}
+```
+
 ---
 
 ## 构建库
@@ -275,16 +293,41 @@ Codex 不会自动读取 Cursor 的 `.cursor/rules/*.mdc`。宿主项目需要
 
 ```bash
 cd /path/to/your-app
+yarn exec mvframe-init-rules
+# 或：npx mvframe-init-rules
+
+# 仅初始化 Codex 规则
 yarn exec mvframe-install-codex-rules
 # 或：npx mvframe-install-codex-rules
 
 # 克隆 / monorepo 中指向 mvframe 源码时
+node /path/to/mvframe/scripts/init-rules.js
+node /path/to/mvframe/scripts/init-rules.js /path/to/your-app
+
+# 仅初始化 Codex 规则
 node /path/to/mvframe/scripts/install-codex-agents.js
 node /path/to/mvframe/scripts/install-codex-agents.js /path/to/your-app
 ```
 
 脚手架命令已自动执行这一步。生成区块带有 `MVFRAME-CODEX-RULES` 标记，重复执行只更新这段内容，不覆盖你在 `AGENTS.md` 中的其它规则。
 
+## Cursor 规则（`.cursor/rules`）
+
+统一命令 `mvframe-init-rules` 会同时把 **mvframe 包内**与仓库一致的 **`*.mdc`** 补充到目标项目 **`/.cursor/rules/`**（`component-hierarchy`、`script-setup`、`style-system`、`views`、`router`、`global-components`、`data`、`util`）。
+若宿主项目已存在同名规则文件，则保留宿主文件，仅补缺失项。
+
+仅安装 Cursor 规则时：
+
+```bash
+cd /path/to/your-app
+yarn exec mvframe-install-cursor-rules
+# 或：npx mvframe-install-cursor-rules
+
+# 克隆 / monorepo 中指向 mvframe 源码时
+node /path/to/mvframe/scripts/install-cursor-rules.js
+node /path/to/mvframe/scripts/install-cursor-rules.js /path/to/your-app
+```
+
 ## Cursor Skill（应用初始化）
 
 本仓库自带 **`.cursor/skills/mvframe-app-init`**，消费方项目可复制到自身 `.cursor/skills` 以便 Cursor 识别 MVFrame 接入规范。

package/README.md

@@ -20,6 +20,7 @@ A Vue 3 + Vite oriented admin-shell toolkit: **Frame layout**, **common business
 - `"./composition"` → `dist/composition.js` (e.g. `import { useMap } from 'mvframe/composition'`)
 - `"./store"`, `"./directive"`, `"./util"` → matching chunks under `dist`
 - `"./notify"` → `dist/notify.js` (browser helper for the local `mvframe-notify` service)
+- `"./style/mixin"` → `src/style/chip/mixin.scss` (shared breakpoint and helper mixins for host SCSS)
 - `"./style"` → `dist/css/style.css` (full toolkit CSS from `src/style/index.scss` entry)
 - `"./style/cpt"` → `dist/css/cpt.css` (component-extracted CSS; usually `import 'mvframe/style'` is enough)
 
@@ -147,8 +148,25 @@ Full helper list: `.cursor/rules/util.mdc` and `src/util/index.js`.
 
 - Utility classes & tokens: `.cursor/rules/style-system.mdc` (`--color-*`, spacing, typography, layout).  
 - `vite.config.js` **`additionalData`** injects **`src/style/chip/mixin.scss`**; mirror this in apps that compile the same SCSS tree.  
+- Breakpoints are centralized in `mixin.scss`: `xs / sm / md / lg / xl / xxl`. Host SCSS can `@use "mvframe/style/mixin" as *;` and use `@include media-up(md)`, `media-down(md)`, `media-only(md)`, or `media-between(sm, lg)`.  
+- `mvframe/style` now ships responsive utility classes in the shape `{breakpoint}-{up|down|only}-{utility}`, for example `md-down-hide`, `lg-up-flexMode`, and `xs-only-block`.  
+- Grid containers also support breakpoint column-count classes such as `class="grid col2 md2 lg3 sm1"`: default 2 columns, `sm` 1 column, `md` 2 columns, `lg` 3 columns.  
 - Published packages can use **`import 'mvframe/style'`** (`dist/css/style.css`). For SCSS overrides, still link **`src/style/index.scss`** from Git/monorepo when needed.
 
+Host SCSS example:
+
+```scss
+@use "mvframe/style/mixin" as *;
+
+.BillingPanel {
+  padding: 1.5rem;
+
+  @include media-down(sm) {
+    padding: 1rem;
+  }
+}
+```
+
 ---
 
 ## Building the library
@@ -260,16 +278,41 @@ Codex does **not** automatically read Cursor `.cursor/rules/*.mdc`. For host pro
 
 ```bash
 cd /path/to/your-app
+yarn exec mvframe-init-rules
+# or: npx mvframe-init-rules
+
+# Codex rules only
 yarn exec mvframe-install-codex-rules
 # or: npx mvframe-install-codex-rules
 
 # Full checkout / monorepo path to mvframe
+node /path/to/mvframe/scripts/init-rules.js
+node /path/to/mvframe/scripts/init-rules.js /path/to/your-app
+
+# Codex rules only
 node /path/to/mvframe/scripts/install-codex-agents.js
 node /path/to/mvframe/scripts/install-codex-agents.js /path/to/your-app
 ```
 
 The scaffold command already runs this step. The generated block is bounded by `MVFRAME-CODEX-RULES` markers, so rerunning the command updates only that block and preserves other `AGENTS.md` content.
 
+## Cursor Rules (`.cursor/rules`)
+
+The unified `mvframe-init-rules` command also adds the package’s **`*.mdc`** files into the target project’s **`/.cursor/rules/`** (`component-hierarchy`, `script-setup`, `style-system`, `views`, `router`, `global-components`, `data`, `util`).
+If the host project already has a same-named rule file, the host file is kept and only missing rules are added.
+
+Install Cursor rules only:
+
+```bash
+cd /path/to/your-app
+yarn exec mvframe-install-cursor-rules
+# or: npx mvframe-install-cursor-rules
+
+# Full checkout / monorepo path to mvframe
+node /path/to/mvframe/scripts/install-cursor-rules.js
+node /path/to/mvframe/scripts/install-cursor-rules.js /path/to/your-app
+```
+
 ## Cursor Skill (app scaffold)
 
 This repo ships **`.cursor/skills/mvframe-app-init`**. Copy it into your app’s **`.cursor/skills`** so Cursor can pick up MVFrame integration conventions.