@neatui/css 5.1.10 → 5.1.11

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# @neatui/css 更新记录
+
+## 5.1.11
+
+### 不兼容变更：Grid 对齐与间距
+
+从 5.1.10 及更早版本升级到 5.1.11 时，请按以下说明迁移 Grid 间距。
+
+`ui-grid` 新增九宫格对齐，间距统一使用 Flex / Grid 共用的 `gap-*` class。旧的属性间距值不再生效，也不再通过 `--gap` 设置间距。
+
+#### 基础迁移
+
+```html
+<!-- 升级前 -->
+<div ui-grid="3 mm">...</div>
+<div ui-grid="3 lm">...</div>
+
+<!-- 升级后：保持原来的间距和默认对齐 -->
+<div ui-grid="3" class="gap-mm">...</div>
+<div ui-grid="3" class="gap-lm">...</div>
+```
+
+所有旧间距档位 `no / xs / ss / sm / sl / ms / mm / ml / ls / lm / ll / xl` 都应从 `ui-grid` 移至 `gap-{档位}` class，数值保持不变，依次为 `0 / 1px / .25em / .5em / .75em / 1em / 1.5em / 2em / 2.5em / 3em / 4em / 5em`。
+
+**特别注意 `lm`：** 它现在表示左侧垂直居中。保留旧 `lm` 不仅会丢失 `3em` 间距，还会改变对齐方式。没有设置对齐时子项仍默认横向撑满；显式设置九宫格对齐后，子项按内容宽度定位。
+
+#### 响应式迁移
+
+Grid 属性和 gap class 的断点方向不同，不能仅在旧值前添加 `gap-`：
+
+| 配置 | 生效范围 |
+| --- | --- |
+| `ui-grid` 无前缀 / `mob:` | 所有宽度的基础值 |
+| `ui-grid` 的 `pad:` | ≥ 800px |
+| `ui-grid` 的 `dpc:` | ≥ 1280px |
+| 无前缀 `gap-*` | 所有宽度的基础值 |
+| `pad:gap-*` | ≤ 1279px，覆盖基础值 |
+| `mob:gap-*` | ≤ 799px，覆盖基础值和平板值 |
+
+```html
+<!-- 升级前：手机 .5em、平板 1.5em、桌面 3em -->
+<div ui-grid="mob:1 pad:2 dpc:4 mob:sm pad:mm dpc:lm">...</div>
+
+<!-- 升级后：列数不变，以桌面间距为基础值 -->
+<div ui-grid="mob:1 pad:2 dpc:4" class="gap-lm pad:gap-mm mob:gap-sm">...</div>
+
+<!-- 升级前：仅从平板起设置 1.5em 间距，手机默认无间距 -->
+<div ui-grid="3 pad:mm">...</div>
+
+<!-- 升级后 -->
+<div ui-grid="3" class="gap-mm mob:gap-no">...</div>
+```
+
+不支持 `dpc:gap-*`。迁移时先确定手机、平板、桌面各自的最终间距，再分别写入 `mob:gap-*`、`pad:gap-*` 和基础 `gap-*`。
+
+#### 自定义样式与按需引入
+
+原来通过 `style="--gap: ..."` 或样式表覆盖 `--gap` 的项目，应改用原生 `gap` 属性。`gap-*` 工具类带有 `!important`，使用自定义 `gap` 时请移除同一元素上的冲突工具类。
+
+`gap-*` 定义在 `core/trim.scss`。全量引入 `neatui.scss` 无需调整；仅按需引入 `core/grid.scss` 的项目还需引入 `core/trim.scss`，或自行设置原生 `gap`。
+
+#### 新增能力与升级检查
+
+- Grid 支持 `lt / lm / lb / ct / cm / cb / rt / rm / rb`，以及 `mob:`、`pad:`、`dpc:` 对齐前缀。第一位控制单元格内水平位置，第二位控制子项及整组网格行的垂直位置；同层 `block` 优先让子项纵向拉伸。
+- Flex 和 Grid 均可使用 `gap-*` 设置行列间距；间距不会增加容器外边距，也不会继承到嵌套容器。
+- 检查项目内所有 `ui-grid`（包括 Vue 动态绑定、拼接字符串和封装组件）中的旧间距值，以及自定义 `--gap`。
+- 在 799px、800px、1279px、1280px 附近检查列数、间距、对齐和嵌套布局，确认迁移前后的预期一致。

package/GUIDE.md

@@ -656,7 +656,7 @@ y: 纵向对齐
 #### 语法格式
 
 ```html
-ui-grid="{breakpoint}:{columns} {gap}"
+ui-grid="{breakpoint}:{columns} {alignment}" class="gap-{grade}"
 
 breakpoint:
   mob  (移动端)
@@ -664,25 +664,38 @@ breakpoint:
   dpc  (桌面)
 
 columns: 列数 (1-12)
-gap: 间距等级 (ss, sm, mm, ml, ll...)
+alignment: 九宫格对齐 (lt, lm, lb, ct, cm, cb, rt, rm, rb)
+grade: gap class 的间距等级 (no, xs, ss, sm, sl, ms, mm, ml, ls, lm, ll, xl)
 ```
 
 #### 基础用法
 
 ```html
 <!-- 固定 3 列，间距 medium-large -->
-<div ui-grid="3 ml">
+<div ui-grid="3" class="gap-ml">
   <div>Item 1</div>
   <div>Item 2</div>
   <div>Item 3</div>
 </div>
 ```
 
+#### 对齐
+
+`ui-grid` 与 Flex 共用九宫格位置：`lt / lm / lb`、`ct / cm / cb`、`rt / rm / rb`。第一位 `l/c/r` 控制子项在各自单元格内的水平位置，第二位 `t/m/b` 控制垂直位置；容器有额外高度时，整组网格行也会顶部、居中或底部对齐。子项内部的文字或 Flex 内容仍由自身样式控制。
+
+```html
+<div ui-grid="3 lm" class="gap-no">...</div>
+<div ui-grid="3 cm" class="gap-mm">...</div>
+<div ui-grid="3 mob:lt pad:cm dpc:rb" class="gap-mm mob:gap-sm">...</div>
+```
+
+同一响应层建议只选一个对齐值；同时包含 `block` 时，`block` 优先让子项纵向拉伸。子项未指定宽度时，默认横向撑满；显式使用九宫格对齐后，子项按其内容宽度定位，需要撑满单元格的子项可自行设置 `width: 100%`。
+
 #### 响应式网格
 
 ```html
 <!-- 移动端 1 列，平板 3 列，桌面 5 列 -->
-<div ui-grid="mob:1 pad:3 dpc:5 ml">
+<div ui-grid="mob:1 pad:3 dpc:5" class="gap-ml">
   <div>Item 1</div>
   <div>Item 2</div>
   <div>Item 3</div>
@@ -695,7 +708,7 @@ gap: 间距等级 (ss, sm, mm, ml, ll...)
 
 **产品列表**
 ```html
-<ul ui-grid="mob:1 pad:2 dpc:4 mm" class="my-lm">
+<ul ui-grid="mob:1 pad:2 dpc:4" class="my-lm gap-mm">
   <li class="bg-fore n-mm r-sm" v-for="product in products">
     <img :src="product.image" />
     <h3 class="co-main fs-ml">{{ product.name }}</h3>
@@ -1178,17 +1191,27 @@ mx-{size}-sun  // 为孙级元素设置左右 margin，并归零每组首/末项
 Padding 的 `*-sub` 在 `[ui-row]` 容器上还会生成等量负 margin 补偿，让栅格子项的
 内边距不会扩大容器的外边界。
 
-#### Grid gap
+#### Flex / Grid gap
 
 ```html
-<div ui-grid="4 sm">...</div>
-<div ui-grid="2 mob:sm pad:6 pad:mm dpc:12">...</div>
+<div ui-grid="4" class="gap-sm">...</div>
+<div ui-grid="2 pad:6 dpc:12" class="gap-mm mob:gap-sm">...</div>
 ```
 
-`ui-grid` 的 `no..xl` 设置 `--gap`，刻度为
+Flex 与 Grid 共用 `gap-no` 至 `gap-xl` class，刻度为
 `0 / 1px / .25em / .5em / .75em / 1em / 1.5em / 2em / 2.5em / 3em / 4em / 5em`。
-同一属性还可以组合 `1..12` 列数和 `block`。4.x 的 `mob:` 是无媒体条件的历史别名；
-`pad:` 从 800px、`dpc:` 从 1280px 生效。
+
+```html
+<div ui-flex="row lm" class="gap-mm">...</div>
+<div ui-grid="3 lm" class="gap-mm">...</div>
+<div ui-grid="3 cm" class="gap-lm pad:gap-mm mob:gap-sm">...</div>
+```
+
+Gap class 沿用其他 class 的响应式规则：默认作用于所有宽度，`pad:` 在最大 `1279px` 时覆盖，`mob:` 在最大 `799px` 时覆盖；不支持 `dpc:gap-*`。它设置原生 `gap`，同时控制行列间距，不增加容器外边距，也不会被嵌套容器继承。
+
+`ui-grid` 属性仅组合 `1..12` 列数、九宫格对齐与 `block`。属性的响应规则保持原样：`mob:` 是无媒体条件的基础别名，`pad:` 从 `800px`、`dpc:` 从 `1280px` 生效。注意区分属性与 class 的响应规则。
+
+**迁移旧写法：** `ui-grid="3 mm"` 改为 `ui-grid="3" class="gap-mm"`；原来表示 `3em` 间距的 `lm` 改为 `class="gap-lm"`。裸 `lm` 现在表示左侧垂直居中，不再设置间距。
 
 ### 尺寸类 (Sizing)
 
@@ -1536,7 +1559,7 @@ cursor-move
 <div class="doc my-lm">
   <h2 class="fs-xl bold co-main mb-ml">热门产品</h2>
 
-  <ul ui-grid="mob:1 pad:2 dpc:4 ml">
+  <ul ui-grid="mob:1 pad:2 dpc:4" class="gap-ml">
     <li
       v-for="product in products"
       :key="product.id"
@@ -1788,7 +1811,7 @@ co-desc co-risk bg-well
 
 <!-- 布局系统 -->
 ui-flex="row xm"
-ui-grid="mob:1 pad:3 dpc:5 ml"
+ui-grid="mob:1 pad:3 dpc:5" class="gap-ml"
 
 <!-- 响应式 -->
 fs-lm pad:fs-mm mob:fs-sm

package/README.md

@@ -4,6 +4,12 @@
 
 NeatUI 约束型原子设计系统（SCSS）。正式项目用 SCSS 自定义 `$theme`；试用可用预编译 preview（默认 light / dark）。
 
+## 更新与升级
+
+升级前请查看 [更新记录与迁移说明](./CHANGELOG.md)。
+
+升级到 5.1.11 需要迁移旧间距语法：`ui-grid="3 mm"` 改为 `ui-grid="3" class="gap-mm"`；裸 `lm` 表示左侧垂直居中。响应式间距不能直接照搬前缀，请按更新记录中的示例迁移。
+
 ## 两种用法
 
 **试用（Preview，仅默认 light / dark）**

package/core/grid.scss

@@ -2,13 +2,12 @@
 
 [ui-grid] {
   display: grid;
-  gap: var(--gap);
+  gap: 0;
   justify-content: start;
   align-items: start;
   align-content: flex-start;
   grid-template-columns: repeat(var(--col), minmax(0, 1fr));
   --col: 4;
-  --gap: 0;
 }
 
 @mixin _grid($med: '') {
@@ -50,42 +49,15 @@
     --col: 12;
   }
 
-  // 间距
-  [ui-grid~='#{$med}no'] {
-    --gap: 0;
-  }
-  [ui-grid~='#{$med}xs'] {
-    --gap: 1px;
-  }
-  [ui-grid~='#{$med}ss'] {
-    --gap: 0.25em;
-  }
-  [ui-grid~='#{$med}sm'] {
-    --gap: 0.5em;
-  }
-  [ui-grid~='#{$med}sl'] {
-    --gap: 0.75em;
-  }
-  [ui-grid~='#{$med}ms'] {
-    --gap: 1em;
-  }
-  [ui-grid~='#{$med}mm'] {
-    --gap: 1.5em;
-  }
-  [ui-grid~='#{$med}ml'] {
-    --gap: 2em;
-  }
-  [ui-grid~='#{$med}ls'] {
-    --gap: 2.5em;
-  }
-  [ui-grid~='#{$med}lm'] {
-    --gap: 3em;
-  }
-  [ui-grid~='#{$med}ll'] {
-    --gap: 4em;
-  }
-  [ui-grid~='#{$med}xl'] {
-    --gap: 5em;
+  // 与 Flex 共用九宫格位置；间距使用 gap-* class。
+  @each $x, $horizontal in (l: start, c: center, r: end) {
+    @each $y, $vertical in (t: start, m: center, b: end) {
+      [ui-grid~='#{$med}#{$x}#{$y}'] {
+        justify-items: $horizontal;
+        align-items: $vertical;
+        align-content: $vertical;
+      }
+    }
   }
 
   // 容器撑满

package/core/trim.scss

@@ -219,6 +219,13 @@ $_radius-l: (
 @mixin trim($media: "") {
   $size: (no, xs, ss, sm, sl, ms, mm, ml, ls, lm, ll, xl);
 
+  // Flex / Grid 共用的原生间距，不依赖可继承的自定义变量。
+  @each $sz, $value in $_spacing-scale {
+    .#{$media}gap-#{$sz} {
+      gap: $value !important;
+    }
+  }
+
   // 栅格负边距补偿：总项 < 轴向 < 单边
   @each $sz, $value in $_spacing-scale {
     @include _row-spacing(