x-next 1.8.0 → 1.8.2

package/AI_USAGE.md

@@ -1,9 +1,9 @@
 <!-- Generated by pnpm generate:ai-usage. Edit src/docs/guide/ai-usage-recipes.md and script/ai-usage/manifest.js. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.8.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.8.2**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（精选示例、映射、版本与公开类型声明）：`3e81e69933489d5ab6307ac5eaa38e89cb26004916f02f2556f74d18b1ed1766`。
+来源指纹（精选示例、映射、版本与公开类型声明）：`c34fe0b5eea3d8bce2e9746c48cb98ee067149bfd006291967c77540d25d9acb`。
 
 先按业务需要选择组件，不要求全部迁移。本手册限定在用户确认的 26 个组件及必要的同族子组件，未覆盖的导出不表示已完成业务验收。
 

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [1.8.2] - 2026-10-05
+
+### 修复
+
+- **Heatmap 行列整体错位（1.6.0 起存在）**：格子的位置由「DOM 顺序 + `grid-auto-flow` 自动填充」共同决定，而渲染顺序（行优先）与数据顺序（列优先）不一致，导致整块热力图错排——视觉上「一列」是 7 个连续周的同一天，而不是同一周的 7 天；月份标签与格子内容、悬浮提示与实际位置全部对不上（表现为「点 7 月的位置，提示显示 9-30」）。
+  现改为**显式 `grid-row` / `grid-column` 定位**：位置只由格子的行列号决定，DOM 顺序不再参与布局，与悬浮提示、键盘导航使用的语义坐标天然一致。
+- 移除网格上已无意义的 `grid-auto-flow`（自动填充顺序是本次错位的成因之一）。
+- 新增防转置回归测试：断言同一列日期连续（同周）、同一行日期相隔 7 天（同星期几），以及格子的 grid 定位与行列号一致。
+
 ## [1.8.0] - 2026-10-05
 
 ### 新增

package/dist/components/heatmap/Heatmap.d.ts

@@ -125,7 +125,6 @@ declare const _default: import('vue').DefineComponent<import('vue').ExtractPropT
     };
     mergedSize: import('vue').ComputedRef<"mini" | "small" | "medium" | "large">;
     cells: import('vue').ComputedRef<HeatmapCell[]>;
-    rows: import('vue').ComputedRef<HeatmapCell[][]>;
     range: import('vue').ComputedRef<HeatmapResolvedRange | null>;
     gridStyle: import('vue').ComputedRef<{
         '--x-heatmap-cell-size': string;

package/dist/components/heatmap/index.d.ts

@@ -62,7 +62,6 @@ export declare const Heatmap: {
         };
         mergedSize: import('vue').ComputedRef<"mini" | "small" | "medium" | "large">;
         cells: import('vue').ComputedRef<import('./interface').HeatmapCell[]>;
-        rows: import('vue').ComputedRef<import('./interface').HeatmapCell[][]>;
         range: import('vue').ComputedRef<import('./interface').HeatmapResolvedRange | null>;
         gridStyle: import('vue').ComputedRef<{
             '--x-heatmap-cell-size': string;
@@ -201,7 +200,6 @@ export declare const Heatmap: {
         };
         mergedSize: import('vue').ComputedRef<"mini" | "small" | "medium" | "large">;
         cells: import('vue').ComputedRef<import('./interface').HeatmapCell[]>;
-        rows: import('vue').ComputedRef<import('./interface').HeatmapCell[][]>;
         range: import('vue').ComputedRef<import('./interface').HeatmapResolvedRange | null>;
         gridStyle: import('vue').ComputedRef<{
             '--x-heatmap-cell-size': string;
@@ -326,7 +324,6 @@ export declare const Heatmap: {
     };
     mergedSize: import('vue').ComputedRef<"mini" | "small" | "medium" | "large">;
     cells: import('vue').ComputedRef<import('./interface').HeatmapCell[]>;
-    rows: import('vue').ComputedRef<import('./interface').HeatmapCell[][]>;
     range: import('vue').ComputedRef<import('./interface').HeatmapResolvedRange | null>;
     gridStyle: import('vue').ComputedRef<{
         '--x-heatmap-cell-size': string;

package/dist/es/components/heatmap/Heatmap.js

@@ -1,13 +1,13 @@
-import { defineComponent as ee, createVNode as n, useId as te, toRefs as le, computed as a, ref as Y, watch as ae, nextTick as ne, Fragment as oe } from "vue";
-import { getClassNameMixin as re } from "../../_utils/config.js";
-import { useSize as ie } from "../../_hooks/use-size.js";
-import { useLocale as se } from "../../locale/index.js";
-import { isObject as ue } from "../../_utils/is.js";
-import { throttleByRaf as ce } from "../../_utils/throttle-by-raf.js";
-import { Spin as de } from "../spin/index.js";
-import { getWeekdayLabels as me } from "../date-picker/utils.js";
-import { CELL_SIZE as U, resolveRange as ve, indexDataByDay as fe, getValueExtent as he, buildMatrix as pe, DEFAULT_COLOR_LEVELS as ye, getMonthLabels as ge, isCellInRequestedRange as xe } from "./helpers/matrix.js";
-const Z = 2, Ae = /* @__PURE__ */ ee({
+import { defineComponent as X, createVNode as n, useId as ee, toRefs as te, computed as o, ref as W, watch as le, nextTick as ae, Fragment as ne } from "vue";
+import { getClassNameMixin as oe } from "../../_utils/config.js";
+import { useSize as re } from "../../_hooks/use-size.js";
+import { useLocale as ie } from "../../locale/index.js";
+import { isObject as se } from "../../_utils/is.js";
+import { throttleByRaf as ue } from "../../_utils/throttle-by-raf.js";
+import { Spin as ce } from "../spin/index.js";
+import { getWeekdayLabels as de } from "../date-picker/utils.js";
+import { CELL_SIZE as K, resolveRange as me, indexDataByDay as ve, getValueExtent as fe, buildMatrix as he, DEFAULT_COLOR_LEVELS as pe, getMonthLabels as ye, isCellInRequestedRange as ge } from "./helpers/matrix.js";
+const U = 2, Ee = /* @__PURE__ */ X({
   name: "Heatmap",
   props: {
     /**
@@ -137,139 +137,131 @@ const Z = 2, Ae = /* @__PURE__ */ ee({
   slots: Object,
   setup(t, {
     emit: D,
-    slots: S
+    slots: Y
   }) {
     const {
-      t: g,
-      locale: z
-    } = se(), C = re("heatmap"), E = `x-heatmap-cell-${te()}`, {
-      mergedSize: A
-    } = ie(le(t).size, {
+      t: p,
+      locale: C
+    } = ie(), z = oe("heatmap"), S = `x-heatmap-cell-${ee()}`, {
+      mergedSize: y
+    } = re(te(t).size, {
       defaultValue: "medium"
-    }), d = a(() => U[A.value] ?? U.medium), p = a(() => {
+    }), s = o(() => K[y.value] ?? K.medium), E = o(() => {
       var e;
       return (e = t.activeColors) != null && e.length ? t.activeColors : ["var(--x-heatmap-color-level-1)", "var(--x-heatmap-color-level-2)", "var(--x-heatmap-color-level-3)", "var(--x-heatmap-color-level-4)", "var(--x-heatmap-color-level-5)"];
-    }), O = a(() => t.minimumColor ?? "var(--x-heatmap-color-empty)"), R = a(() => [O.value, ...p.value]), i = a(() => ve({
+    }), R = o(() => t.minimumColor ?? "var(--x-heatmap-color-empty)"), b = o(() => [R.value, ...E.value]), c = o(() => me({
       year: t.year,
       startDate: t.startDate,
       endDate: t.endDate,
       data: t.data
-    }, t.firstDayOfWeek)), P = a(() => fe(t.data)), q = a(() => he(t.data)), m = a(() => i.value ? pe(i.value, P.value, q.value, p.value.length || ye) : []), F = a(() => {
-      const e = Array.from({
-        length: 7
-      }, () => []);
-      return m.value.forEach((l) => {
-        e[l.rowIndex].push(l);
-      }), e;
-    }), V = a(() => me(t.firstDayOfWeek, z.value.datePicker)), _ = a(() => {
-      if (!i.value) return [];
-      const e = i.value.requestedStart.year() !== i.value.requestedEnd.year();
-      return ge(i.value, m.value, (l) => e ? l.format("YYYY-MM") : g("heatmap.month", {
+    }, t.firstDayOfWeek)), P = o(() => ve(t.data)), A = o(() => fe(t.data)), m = o(() => c.value ? he(c.value, P.value, A.value, E.value.length || pe) : []), q = o(() => de(t.firstDayOfWeek, C.value.datePicker)), F = o(() => {
+      if (!c.value) return [];
+      const e = c.value.requestedStart.year() !== c.value.requestedEnd.year();
+      return ye(c.value, m.value, (l) => e ? l.format("YYYY-MM") : p("heatmap.month", {
         month: l.month() + 1
       }));
-    }), j = (e) => R.value[e.level] ?? O.value, $ = (e) => {
-      const l = e.date.format("YYYY-MM-DD"), o = e.value;
-      return o === null ? g("heatmap.noData", {
+    }), V = (e) => b.value[e.level] ?? R.value, $ = (e) => {
+      const l = e.date.format("YYYY-MM-DD"), r = e.value;
+      return r === null ? p("heatmap.noData", {
         date: l
-      }) : g("heatmap.value", {
+      }) : p("heatmap.value", {
         date: l,
-        value: o
+        value: r
       });
-    }, v = Y(null), L = a(() => t.tooltip !== !1), b = Y(null), s = {
-      tooltip: b
-    }, w = Y(0), M = a(() => v.value === null ? null : m.value[v.value] ?? null), k = a(() => m.value.reduce((e, l) => Math.max(e, l.colIndex + 1), 0)), G = a(() => {
-      const e = Z;
-      return k.value <= 0 ? 0 : k.value * d.value + (k.value - 1) * e;
-    }), B = a(() => {
+    }, d = W(null), L = o(() => t.tooltip !== !1), x = W(null), i = {
+      tooltip: x
+    }, k = W(0), M = o(() => d.value === null ? null : m.value[d.value] ?? null), w = o(() => m.value.reduce((e, l) => Math.max(e, l.colIndex + 1), 0)), _ = o(() => {
+      const e = U;
+      return w.value <= 0 ? 0 : w.value * s.value + (w.value - 1) * e;
+    }), O = o(() => {
       const e = M.value;
       if (!e) return {};
-      const l = Z, o = e.colIndex * (d.value + l) + d.value / 2, c = e.rowIndex * (d.value + l) + d.value, h = w.value / 2, f = G.value;
-      let K = o;
-      return h > 0 && f > 0 && (K = f >= w.value ? Math.min(Math.max(o, h), f - h) : f / 2), {
-        left: `${K}px`,
-        top: `${c + 6}px`
+      const l = U, r = e.colIndex * (s.value + l) + s.value / 2, u = e.rowIndex * (s.value + l) + s.value, h = k.value / 2, f = _.value;
+      let H = r;
+      return h > 0 && f > 0 && (H = f >= k.value ? Math.min(Math.max(r, h), f - h) : f / 2), {
+        left: `${H}px`,
+        top: `${u + 6}px`
       };
     });
-    ae(v, (e) => {
+    le(d, (e) => {
       if (e === null) {
-        w.value = 0;
+        k.value = 0;
         return;
       }
-      ne(() => {
-        var o;
-        const l = ((o = b.value) == null ? void 0 : o.offsetWidth) ?? 0;
-        l !== w.value && (w.value = l);
+      ae(() => {
+        var r;
+        const l = ((r = x.value) == null ? void 0 : r.offsetWidth) ?? 0;
+        l !== k.value && (k.value = l);
       });
     });
-    const H = (e) => {
-      var c;
+    const j = (e) => {
+      var u;
       if (!L.value) return;
-      const l = e.target, o = (c = l == null ? void 0 : l.dataset) == null ? void 0 : c.index;
-      x.value = !1, v.value = o === void 0 ? null : Number(o);
-    }, N = () => {
-      v.value = null, x.value = !1;
-    }, x = Y(!1), T = (e, l = !1) => {
-      x.value = l, v.value = e;
-    }, W = (e) => {
+      const l = e.target, r = (u = l == null ? void 0 : l.dataset) == null ? void 0 : u.index;
+      g.value = !1, d.value = r === void 0 ? null : Number(r);
+    }, B = () => {
+      d.value = null, g.value = !1;
+    }, g = W(!1), N = (e, l = !1) => {
+      g.value = l, d.value = e;
+    }, T = (e) => {
       if (!L.value || m.value.length === 0) return;
-      const l = m.value.length - 1, o = v.value;
-      let c = null;
-      if (e.key === "ArrowRight") c = Math.min(l, (o ?? -1) + 1);
-      else if (e.key === "ArrowLeft") c = Math.max(0, (o ?? l + 1) - 1);
-      else if (e.key === "ArrowDown") c = Math.min(l, (o ?? -7) + 7);
-      else if (e.key === "ArrowUp") c = Math.max(0, (o ?? 7) - 7);
+      const l = m.value.length - 1, r = d.value;
+      let u = null;
+      if (e.key === "ArrowRight") u = Math.min(l, (r ?? -1) + 1);
+      else if (e.key === "ArrowLeft") u = Math.max(0, (r ?? l + 1) - 1);
+      else if (e.key === "ArrowDown") u = Math.min(l, (r ?? -7) + 7);
+      else if (e.key === "ArrowUp") u = Math.max(0, (r ?? 7) - 7);
       else if (e.key === "Home") {
-        const h = o ?? 0, f = m.value[h];
-        c = f ? Math.max(0, h - f.rowIndex) : 0;
+        const h = r ?? 0, f = m.value[h];
+        u = f ? Math.max(0, h - f.rowIndex) : 0;
       } else if (e.key === "End") {
-        const h = o ?? l, f = m.value[h];
-        c = f ? Math.min(l, h + (6 - f.rowIndex)) : l;
+        const h = r ?? l, f = m.value[h];
+        u = f ? Math.min(l, h + (6 - f.rowIndex)) : l;
       } else if (e.key === "Escape") {
-        N();
+        B();
         return;
       }
-      c !== null && (e.preventDefault(), T(c, !0));
-    }, r = () => {
-      v.value === null && T(0, !0);
-    }, y = a(() => x.value && v.value !== null ? `${E}-${v.value}` : void 0), u = a(() => t.ariaLabel ?? g("heatmap.gridLabel")), I = a(() => {
+      u !== null && (e.preventDefault(), N(u, !0));
+    }, a = () => {
+      d.value === null && N(0, !0);
+    }, v = o(() => g.value && d.value !== null ? `${S}-${d.value}` : void 0), I = o(() => t.ariaLabel ?? p("heatmap.gridLabel")), G = o(() => {
       const e = M.value;
-      return !x.value || !e ? "" : $(e);
-    }), J = (e, l) => {
+      return !g.value || !e ? "" : $(e);
+    }), Z = (e, l) => {
       D("cellClick", e, l);
-    }, Q = ce(H), X = a(() => ({
-      "--x-heatmap-cell-size": `${d.value}px`,
-      gridTemplateRows: `repeat(7, ${d.value}px)`
+    }, J = ue(j), Q = o(() => ({
+      "--x-heatmap-cell-size": `${s.value}px`,
+      gridTemplateRows: `repeat(7, ${s.value}px)`
     }));
     return {
-      t: g,
-      className: C,
-      mergedSize: A,
+      t: p,
+      className: z,
+      mergedSize: y,
       cells: m,
-      rows: F,
-      range: i,
-      gridStyle: X,
-      weekdayLabels: V,
-      monthLabels: _,
+      range: c,
+      gridStyle: Q,
+      weekdayLabels: q,
+      monthLabels: F,
       activeCell: M,
       tooltipEnabled: L,
-      tooltipStyle: B,
-      cellColor: j,
+      tooltipStyle: O,
+      cellColor: V,
       cellLabel: $,
-      handleCellClick: J,
-      throttledMove: Q,
-      clearActive: N,
-      handleKeydown: W,
-      handleGridFocus: r,
-      activeDescendant: y,
-      gridLabel: u,
-      cellIdPrefix: E,
-      liveText: I,
-      isInRange: (e) => i.value ? xe(e, i.value.requestedStart, i.value.requestedEnd) : !0,
-      colorPalette: R,
-      slots: S,
-      refs: s,
+      handleCellClick: Z,
+      throttledMove: J,
+      clearActive: B,
+      handleKeydown: T,
+      handleGridFocus: a,
+      activeDescendant: v,
+      gridLabel: I,
+      cellIdPrefix: S,
+      liveText: G,
+      isInRange: (e) => c.value ? ge(e, c.value.requestedStart, c.value.requestedEnd) : !0,
+      colorPalette: b,
+      slots: Y,
+      refs: i,
       setTooltipElement: (e) => {
-        b.value = e;
+        x.value = e;
       }
     };
   },
@@ -277,133 +269,143 @@ const Z = 2, Ae = /* @__PURE__ */ ee({
     const {
       className: t,
       mergedSize: D,
-      cells: S,
-      rows: g,
-      range: z,
+      cells: Y,
+      range: p,
       gridStyle: C,
-      weekdayLabels: E,
-      monthLabels: A,
-      activeCell: d,
-      tooltipEnabled: p,
-      tooltipStyle: O,
+      weekdayLabels: z,
+      monthLabels: S,
+      activeCell: y,
+      tooltipEnabled: s,
+      tooltipStyle: E,
       cellColor: R,
-      cellLabel: i,
-      handleCellClick: P,
-      throttledMove: q,
-      clearActive: m,
-      handleKeydown: F,
-      handleGridFocus: V,
-      activeDescendant: _,
-      gridLabel: j,
+      cellLabel: b,
+      handleCellClick: c,
+      throttledMove: P,
+      clearActive: A,
+      handleKeydown: m,
+      handleGridFocus: q,
+      activeDescendant: F,
+      gridLabel: V,
       cellIdPrefix: $,
-      liveText: v,
+      liveText: d,
       isInRange: L,
-      colorPalette: b,
-      slots: s,
-      refs: w,
+      colorPalette: x,
+      slots: i,
+      refs: k,
       setTooltipElement: M,
-      t: k
+      t: w
     } = this;
-    if (!z) return null;
-    const G = ue(this.loading) ? this.loading : {
+    if (!p) return null;
+    const _ = se(this.loading) ? this.loading : {
       loading: this.loading,
       dot: "color"
-    }, B = p && d !== null, H = () => n("div", {
+    }, O = s && y !== null, j = () => n("div", {
       class: t.element("grid"),
       style: {
         ...C,
         "--x-heatmap-cell-gap": "var(--x-spacing-1)"
       },
-      role: p ? "grid" : void 0,
-      tabindex: p ? 0 : void 0,
-      "aria-activedescendant": _,
-      "aria-label": p ? j : void 0,
-      onMousemove: q,
-      onMouseleave: m,
-      onFocus: V,
-      onBlur: m,
-      onKeydown: F
-    }, [g.map((r, y) => r.map((u) => n("div", {
-      key: u.timestamp,
-      id: `${$}-${S.indexOf(u)}`,
-      class: [t.element("cell"), t.modifier(`level-${u.level}`), {
-        [t.is("out-of-range")]: !L(u)
+      role: s ? "grid" : void 0,
+      tabindex: s ? 0 : void 0,
+      "aria-activedescendant": F,
+      "aria-label": s ? V : void 0,
+      onMousemove: P,
+      onMouseleave: A,
+      onFocus: q,
+      onBlur: A,
+      onKeydown: m
+    }, [Y.map((a, v) => n("div", {
+      key: a.timestamp,
+      id: `${$}-${v}`,
+      class: [t.element("cell"), t.modifier(`level-${a.level}`), {
+        [t.is("out-of-range")]: !L(a)
       }],
       style: {
-        backgroundColor: R(u)
+        backgroundColor: R(a),
+        /*
+         * 显式定位：位置由 rowIndex / colIndex 决定，不再依赖
+         * `grid-auto-flow` 的自动填充顺序。
+         *
+         * 这正是此前数据被整体转置的原因：cells 是列优先数组，
+         * CSS 按列填充，而渲染顺序曾是行优先，三者不一致时布局静默错位。
+         * 显式定位后 DOM 顺序对布局没有任何影响，与 tooltip 使用的
+         * 语义坐标天然一致（等价于 SVG 里用公式算 x/y）。
+         */
+        gridRow: a.rowIndex + 1,
+        gridColumn: a.colIndex + 1
       },
-      "data-index": S.indexOf(u),
-      title: B ? void 0 : i(u),
-      onClick: (I) => P(u, I),
+      "data-index": v,
+      title: O ? void 0 : b(a),
+      onClick: (I) => c(a, I),
       role: "gridcell",
-      "aria-label": i(u)
-    }, []))), N()]), N = () => {
-      if (!B || !d) return null;
-      const r = {
-        ...d,
-        label: i(d)
+      "aria-label": b(a)
+    }, [])), B()]), B = () => {
+      if (!O || !y) return null;
+      const a = {
+        ...y,
+        label: b(y)
       };
       return n("div", {
         ref: M,
         class: [t.element("tooltip"), t.is("visible")],
-        style: O,
+        style: E,
         role: "tooltip"
-      }, [s.tooltip ? s.tooltip(r) : r.label]);
-    }, x = () => {
-      var r, y;
+      }, [i.tooltip ? i.tooltip(a) : a.label]);
+    }, g = () => {
+      var a, v;
       return this.showColorIndicator ? n("div", {
         class: t.element("indicator")
-      }, [s.indicator ? s.indicator({
-        colors: b
-      }) : n(oe, null, [n("span", {
+      }, [i.indicator ? i.indicator({
+        colors: x
+      }) : n(ne, null, [n("span", {
         class: t.element("indicator-leading")
-      }, [((r = s["indicator-leading-text"]) == null ? void 0 : r.call(s)) ?? k("heatmap.less")]), b.map((u, I) => n("span", {
-        key: I,
+      }, [((a = i["indicator-leading-text"]) == null ? void 0 : a.call(i)) ?? w("heatmap.less")]), x.map((I, G) => n("span", {
+        key: G,
         class: t.element("indicator-swatch"),
         style: {
-          backgroundColor: u
+          backgroundColor: I
         }
       }, null)), n("span", {
         class: t.element("indicator-trailing")
-      }, [((y = s["indicator-trailing-text"]) == null ? void 0 : y.call(s)) ?? k("heatmap.more")])])]) : null;
-    }, T = () => n("div", {
+      }, [((v = i["indicator-trailing-text"]) == null ? void 0 : v.call(i)) ?? w("heatmap.more")])])]) : null;
+    }, N = () => n("div", {
       class: t.element("body")
     }, [this.showWeekLabels && n("div", {
       class: t.element("week-labels"),
       style: C
-    }, [E.map((r, y) => n("span", {
-      key: y,
+    }, [z.map((a, v) => n("span", {
+      key: v,
       class: t.element("week-label"),
       style: {
-        visibility: y % 2 === 1 ? "visible" : "hidden"
+        visibility: v % 2 === 1 ? "visible" : "hidden"
       }
-    }, [r]))]), n("div", {
+    }, [a]))]), n("div", {
       class: t.element("grid-wrapper")
     }, [this.showMonthLabels && n("div", {
       class: t.element("month-labels"),
       style: C
-    }, [A.map((r) => n("span", {
-      key: r.text,
+    }, [S.map((a) => n("span", {
+      key: a.text,
       class: t.element("month-label"),
       style: {
-        gridColumn: r.colIndex + 1
+        gridColumn: a.colIndex + 1
       }
-    }, [r.text]))]), H()])]), W = p;
+    }, [a.text]))]), j()])]), T = s;
     return n("div", {
       class: [t.block, t.modifier(`size-${D}`)]
     }, [n("div", {
-      role: !W && this.ariaLabel ? "img" : void 0,
-      "aria-label": W ? void 0 : this.ariaLabel
-    }, [n(de, G, {
-      default: () => [T(), x(), s.footer && n("div", {
+      role: !T && this.ariaLabel ? "img" : void 0,
+      "aria-label": T ? void 0 : this.ariaLabel
+    }, [n(ce, _, {
+      default: () => [N(), g(), i.footer && n("div", {
         class: t.element("footer")
-      }, [s.footer()])]
+      }, [i.footer()])]
     })]), n("span", {
       class: t.element("live"),
       "aria-live": "polite"
-    }, [v])]);
+    }, [d])]);
   }
 });
 export {
-  Ae as default
+  Ee as default
 };