mvframe 1.0.93 → 1.0.95

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）
 
 ### 全局重置与基础
@@ -232,6 +307,21 @@ alwaysApply: true
 - 如果只是标签颜色或形态变化，不要重写 scoped tag 样式，直接叠加现有变体
 - 只有在 `tag` 无法覆盖的专属视觉下，才在局部补 scoped 样式
 
+### Dot
+
+全局 `dot{N}` 是通用圆点样式，适合状态点、图例点、时间轴节点等纯色圆形标识。
+
+| 类名 | 用途 |
+|------|------|
+| `dot4/dot8/dot10/dot12/dot14/dot16/dot18/dot20/dot24/dot28/dot30/dot32` | 圆点尺寸，源码按 px 设计稿维护，输出为 rem |
+| `dot{N} primary/blue/green/yellow/orange/red/purple/pink/black/dark/body/white/gray` | 圆点颜色变体，默认 `primary` |
+
+使用建议：
+
+- 直接组合类名：`class="dot8 orange"`、`class="dot12"`、`class="dot20 gray"`
+- `dot{N}` 默认就是主色圆点；只有需要别的颜色时再叠加颜色类
+- 这组样式只负责纯圆点本体；如果需要边框、发光、外层容器，优先额外包一层而不是改写 `dot{N}` 自身
+
 ### Tip 按钮与图标
 
 | 类名 | 用途 |

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;
+  }
+}
+```
+
 ---
 
 ## 构建库

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