dsh-calendar 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.8.2（2026-09-20）
+
+- **修主题色误用**：此前把宿主遮罩 token `--dsw-alias-bg-mask-3` 当淡色 hover/底纹用；DSH 0.1.6-alpha.2 里它实测亮/暗主题都是 `rgba(0,0,0,.48)`，导致周视图「今天」整列、月视图格子 hover、加载骨架屏、详情 tag 全部发深灰（浏览器视觉验收抓到，视觉上像一块无字灰板）。现改为 `color-mix`（label-primary 5%~7% / business-primary 7%），mask-3 只保留在 `.dshc-overlay` / `.dshc-modalwrap` 两处真正的遮罩上。
+- **修 Esc 关错层**：详情抽屉/新建表单打开时按 Esc 会连整个日历浮层面板一起关掉。现在 Esc 只关最上面一层，第二次才关面板；焦点在上层宿主 `PRIM.Modal` 里时让行给宿主；输入法组合状态（`isComposing`）不误关；设置页与对话页两个面板并存时一次也只关一层，并按实际打开顺序关。
+- **测试**：render 测试 7 → 15 条（新增抽屉/宿主 Modal 真假路径/宿主高层浮层让行/普通宿主元素兜底/层序/IME 等用例），全量 154 pass。该版经两位独立评审：首轮抓到「宿主 Portal 抢 Esc」「双面板一次连关两层」「IME 误关」，二轮抓到「宿主高层 Modal 盖上来时关错下面那层」，均已修。
+
+## 0.8.1（2026-09-19）
+
+- **新增真 DOM 行为测试层**（`test/render.test.mjs`，devDependencies 里加 `react` / `react-dom` / `jsdom`，不进发布包）：用 jsdom + 真 React 渲染周视图，然后真派发 `pointerdown/move/up`、`click`、`keydown`。7 条覆盖：渲染不抛、点事件不会顺手弹「新建」、拖动只提交一次且按视口坐标换算、拖动中 Esc 零请求、卸载后不留监听器且之后的 pointerup 不提交、拖到边缘 rAF 持续滚动、重复日程被面板挡住。
+- **它的第一批产出就是三个真问题**：
+  ① **同一批次内拖动不提交**：提交前的「有没有落点」判断读的是 React state（`ghost`），而 `pointermove` 与 `pointerup` 落在同一批次时 state 还没刷新 → 明明拖了却不落盘。改为在 `dragRef` 上记同步标记。
+  ② `requestAnimationFrame` / `cancelAnimationFrame` 按全局调用：浏览器里有，但模块作用域下应当显式走 `window.*`。
+  ③ 三处 React key 警告（日期头、事件块、幽灵块、日列的子节点用了数组却没给 key）——dev 模式控制台一直在吵。
+
 ## 0.8.0（2026-09-19）
 
 - **新增：周视图拖拽改期**。拖动事件块上下改时间、左右换天（15 分钟吸附）；拖块底部 6px 改时长；拖动中显示幽灵落点，与已有日程重叠时描成黄色（允许重叠，只是提醒）；拖到容器上下边缘自动滚动，长会议不用先滚再拖。

package/README.md

@@ -230,6 +230,8 @@ Nextcloud / 自定义 Basic 服务：检查账号、密码或服务要求的应
 
 ## 开发
 
+- **UI 行为测试**：`test/render.test.mjs` 用 jsdom + 真 React 渲染周视图并派发真实事件（点击 / 拖动 / Esc / 卸载 / 边缘滚动）。改前端交互时它会替你点一遍；`pnpm test` 会一起跑。
+
 ```bash
 pnpm install
 pnpm test   # 构建 + node --test

package/lib/client.js

@@ -47,7 +47,7 @@ const CSS = [
   ".dshc-sub{color:var(--dsw-alias-label-tertiary,#6b7280);font-size:12px}",
   ".dshc-spacer{flex:1}",
   ".dshc-btn{display:inline-flex;align-items:center;gap:4px;border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.1));background:var(--dsw-alias-bg-layer-1,#fff);color:var(--dsw-alias-label-primary,#111);border-radius:9px;padding:5px 11px;font-size:12px;cursor:pointer;transition:background .12s,border-color .12s}",
-  ".dshc-btn:hover:not(:disabled){background:var(--dsw-alias-bg-mask-3,rgba(0,0,0,.05))}",
+  ".dshc-btn:hover:not(:disabled){background:color-mix(in srgb,var(--dsw-alias-label-primary,#111) 6%,transparent)}",
   ".dshc-btn:disabled{opacity:.5;cursor:not-allowed}",
   ".dshc-btn.primary{background:var(--dsw-alias-button-primary-fill,#2563eb);border-color:transparent;color:var(--dsw-alias-label-primary-foreground,#fff)}",
   ".dshc-btn.primary:hover:not(:disabled){background:var(--dsw-alias-button-primary-hover,#1d4ed8)}",
@@ -60,7 +60,7 @@ const CSS = [
   ".dshc-grid{display:grid;grid-template-columns:repeat(7,minmax(0,1fr));gap:6px}",
   ".dshc-dow{text-align:center;font-size:11px;color:var(--dsw-alias-label-tertiary,#9ca3af);padding:2px 0 4px}",
   ".dshc-cell{display:block;width:100%;min-height:88px;box-sizing:border-box;border-radius:10px;padding:5px 5px 6px;background:var(--dsw-alias-bg-layer-2,rgba(0,0,0,.03));border:1px solid transparent;cursor:pointer;text-align:left;font:inherit;color:inherit;transition:background .12s,border-color .12s;overflow:hidden}",
-  ".dshc-cell:hover{background:var(--dsw-alias-bg-mask-3,rgba(0,0,0,.07))}",
+  ".dshc-cell:hover{background:color-mix(in srgb,var(--dsw-alias-label-primary,#111) 7%,transparent)}",
   ".dshc-cell.out{opacity:.45}",
   ".dshc-cell.today{border-color:var(--dsw-alias-state-business-primary,#2563eb)}",
   ".dshc-daynum{font-size:11px;color:var(--dsw-alias-label-tertiary,#9ca3af);margin:0 0 3px;display:flex;justify-content:space-between}",
@@ -75,7 +75,7 @@ const CSS = [
   ".dshc-week{display:grid;grid-template-columns:56px repeat(7,minmax(0,1fr));gap:4px;max-height:520px;overflow:auto}",
   ".dshc-hour{font-size:11px;color:var(--dsw-alias-label-tertiary,#9ca3af);text-align:right;padding-right:4px;height:44px}",
   ".dshc-daycol{position:relative;border-left:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.07));min-height:44px}",
-  ".dshc-daycol.today{background:var(--dsw-alias-bg-mask-3,rgba(37,99,235,.06))}",
+  ".dshc-daycol.today{background:color-mix(in srgb,var(--dsw-alias-state-business-primary,#2563eb) 7%,transparent)}",
   ".dshc-dayhead{position:sticky;top:0;background:var(--dsw-alias-bg-layer-1,#fff);z-index:2;text-align:center;font-size:11px;color:var(--dsw-alias-label-tertiary,#9ca3af);padding-bottom:4px}",
   ".dshc-dayhead b{color:var(--dsw-alias-label-primary,#111);font-weight:600;font-size:13px}",
   ".dshc-slot{position:absolute;left:2px;right:2px;border-radius:7px;padding:3px 5px;font-size:11px;line-height:1.3;overflow:hidden;cursor:grab;background:var(--dsw-alias-state-business-primary,#2563eb);color:var(--dsw-alias-label-primary-foreground,#fff);border:0;text-align:left;touch-action:none;user-select:none}",
@@ -98,22 +98,22 @@ const CSS = [
   ".dshc-daylabel{display:flex;align-items:baseline;gap:8px;position:sticky;top:0;background:var(--dsw-alias-bg-layer-1,#fff);padding:2px 0}",
   ".dshc-daylabel b{font-size:13px}",
   ".dshc-row{display:flex;gap:10px;align-items:flex-start;padding:8px 10px;border-radius:10px;background:var(--dsw-alias-bg-layer-2,rgba(0,0,0,.03));cursor:pointer;border-left:3px solid var(--dsw-alias-state-business-primary,#2563eb)}",
-  ".dshc-row:hover{background:var(--dsw-alias-bg-mask-3,rgba(0,0,0,.07))}",
+  ".dshc-row:hover{background:color-mix(in srgb,var(--dsw-alias-label-primary,#111) 7%,transparent)}",
   ".dshc-row.allday{border-left-color:var(--dsw-alias-state-success-primary,#16a34a)}",
   ".dshc-row.recurring{border-left-color:var(--dsw-alias-state-warn-primary,#f59e0b)}",
   ".dshc-time{font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-tertiary,#6b7280);min-width:96px;font-size:12px;padding-top:1px}",
   ".dshc-main{flex:1;min-width:0}",
   ".dshc-name{font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}",
   ".dshc-meta{color:var(--dsw-alias-label-tertiary,#6b7280);font-size:12px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}",
-  ".dshc-tag{display:inline-block;font-size:11px;padding:1px 6px;border-radius:999px;background:var(--dsw-alias-bg-mask-3,rgba(0,0,0,.07));color:var(--dsw-alias-label-tertiary,#6b7280);margin-left:6px}",
+  ".dshc-tag{display:inline-block;font-size:11px;padding:1px 6px;border-radius:999px;background:color-mix(in srgb,var(--dsw-alias-label-primary,#111) 7%,transparent);color:var(--dsw-alias-label-tertiary,#6b7280);margin-left:6px}",
   ".dshc-empty{padding:26px 18px;text-align:center;color:var(--dsw-alias-label-tertiary,#6b7280)}",
   ".dshc-empty h3{color:var(--dsw-alias-label-primary,#111);margin:0 0 6px;font-size:14px}",
   ".dshc-empty code{background:var(--dsw-alias-bg-layer-2,rgba(0,0,0,.05));padding:1px 5px;border-radius:5px;font-size:12px}",
-  ".dshc-alert{display:flex;gap:8px;align-items:flex-start;border-radius:10px;padding:8px 10px;font-size:12px;margin-bottom:10px;background:var(--dsw-alias-bg-mask-3,rgba(0,0,0,.05))}",
+  ".dshc-alert{display:flex;gap:8px;align-items:flex-start;border-radius:10px;padding:8px 10px;font-size:12px;margin-bottom:10px;background:color-mix(in srgb,var(--dsw-alias-label-primary,#111) 5%,transparent)}",
   ".dshc-alert.error{background:color-mix(in srgb,var(--dsw-alias-state-error-primary,#dc2626) 12%,transparent);color:var(--dsw-alias-state-error-primary,#dc2626)}",
   ".dshc-alert.warn{background:color-mix(in srgb,var(--dsw-alias-state-warn-primary,#f59e0b) 16%,transparent)}",
   ".dshc-alert.demo{background:color-mix(in srgb,var(--dsw-alias-state-business-primary,#2563eb) 12%,transparent)}",
-  ".dshc-skel{height:88px;border-radius:10px;background:linear-gradient(90deg,var(--dsw-alias-bg-layer-2,rgba(0,0,0,.04)) 25%,var(--dsw-alias-bg-mask-3,rgba(0,0,0,.08)) 37%,var(--dsw-alias-bg-layer-2,rgba(0,0,0,.04)) 63%);background-size:400% 100%;animation:dshc-shimmer 1.4s ease infinite}",
+  ".dshc-skel{height:88px;border-radius:10px;background:linear-gradient(90deg,var(--dsw-alias-bg-layer-2,rgba(0,0,0,.04)) 25%,color-mix(in srgb,var(--dsw-alias-label-primary,#111) 10%,transparent) 37%,var(--dsw-alias-bg-layer-2,rgba(0,0,0,.04)) 63%);background-size:400% 100%;animation:dshc-shimmer 1.4s ease infinite}",
   "@keyframes dshc-shimmer{0%{background-position:100% 0}100%{background-position:0 0}}",
   ".dshc-overlay{position:fixed;inset:0;background:var(--dsw-alias-bg-mask-3,rgba(15,23,42,.42));display:flex;justify-content:flex-end;z-index:60}",
   ".dshc-drawer{width:min(420px,92vw);height:100%;background:var(--dsw-alias-bg-layer-1,#fff);border-left:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.08));padding:18px;overflow:auto;box-shadow:var(--dsw-elevation-prominent,0 10px 30px rgba(0,0,0,.2))}",
@@ -557,7 +557,7 @@ function Dlg(props) {
       onClose: props.onClose,
       title: props.title,
       closeLabel: props.closeLabel || props.title,
-      children: props.children,
+      children: h("div", { "data-dshc-scope": "1" }, props.children),
       footer: props.footer
     });
   }
@@ -834,9 +834,9 @@ function WeekView(props) {
     }
     if (commit !== false && moved === true && canEdit === true) {
       const slot = drag.previewSlot === undefined ? drag.slot : drag.previewSlot;
-      // 没有幽灵块就没有落点：比如纵向拖出本周（跨到下周）时不该盲提交。
-      const visible = days.some((day) => dayKey(day) === slot.dayKey) && ghost !== null;
-      if (visible === true) onReschedule(drag.event, rangeOfSlot(slot), drag.mode);
+      // 没有落点就不提交：比如纵向拖出本周（跨到下周）时幽灵没地方画，这时盲提交会让事件从视图消失。
+      // 用 dragRef 上的同步标记，而不是 React state（见 applyPreviewAt 的注释）。
+      if (drag.previewVisible === true) onReschedule(drag.event, rangeOfSlot(slot), drag.mode);
     }
   };
 
@@ -858,6 +858,9 @@ function WeekView(props) {
       ? resizeSlot(drag.slot, (dy / HOUR_PX) * 60, SNAP_MINUTES)
       : slotFromDrag(drag.slot, { columns, pixelsY: dy, hourPx: HOUR_PX }, SNAP_MINUTES);
     drag.previewSlot = slot;
+    // 可见性判断必须同步落在 dragRef 上：pointermove 与 pointerup 可能在同一批次里，
+    // 此时读 React state（ghost）拿到的是旧值，会导致「拖了却不提交」。
+    drag.previewVisible = days.some((day) => dayKey(day) === slot.dayKey);
     setGhost({ uid: drag.uid, slot, conflicts: conflictsForSlot(events, slot, drag.uid).length });
   };
 
@@ -868,7 +871,7 @@ function WeekView(props) {
    */
   const autoScroll = useRef({ raf: 0, x: 0, y: 0 });
   const stopAutoScroll = () => {
-    if (autoScroll.current.raf !== 0) { cancelAnimationFrame(autoScroll.current.raf); autoScroll.current.raf = 0; }
+    if (autoScroll.current.raf !== 0) { window.cancelAnimationFrame(autoScroll.current.raf); autoScroll.current.raf = 0; }
   };
   const stepAutoScroll = () => {
     autoScroll.current.raf = 0;
@@ -883,7 +886,7 @@ function WeekView(props) {
     if (delta === 0) return;   // 指针离开边缘：循环自然停下，下次移动会再起
     node.scrollTop += delta;
     applyPreviewAt(autoScroll.current.x, y, drag);   // 滚动后重算落点（含滚动补偿）
-    autoScroll.current.raf = requestAnimationFrame(stepAutoScroll);
+    autoScroll.current.raf = window.requestAnimationFrame(stepAutoScroll);
   };
   const ensureAutoScroll = (pointerEvent) => {
     autoScroll.current.x = pointerEvent.clientX;
@@ -892,7 +895,7 @@ function WeekView(props) {
     if (node === null || node === undefined) return;
     const rect = node.getBoundingClientRect();
     const nearEdge = pointerEvent.clientY < rect.top + 40 || pointerEvent.clientY > rect.bottom - 40;
-    if (nearEdge === true && autoScroll.current.raf === 0) autoScroll.current.raf = requestAnimationFrame(stepAutoScroll);
+    if (nearEdge === true && autoScroll.current.raf === 0) autoScroll.current.raf = window.requestAnimationFrame(stepAutoScroll);
   };
 
   const updatePreview = (pointerEvent) => {
@@ -929,7 +932,7 @@ function WeekView(props) {
       window.removeEventListener("pointerup", onUp);
       window.removeEventListener("pointercancel", onCancel);
       window.removeEventListener("keydown", onKey, true);
-      if (autoScroll.current.raf !== 0) { cancelAnimationFrame(autoScroll.current.raf); autoScroll.current.raf = 0; }
+      if (autoScroll.current.raf !== 0) { window.cancelAnimationFrame(autoScroll.current.raf); autoScroll.current.raf = 0; }
       window.removeEventListener("blur", onBlur);
       dragRef.current = null;   // 卸载时不能留着半截拖拽状态
     };
@@ -1009,24 +1012,25 @@ function WeekView(props) {
           if (suppressClick.current === true) { suppressClick.current = false; return; }
           onPick(event);
         }
-      }, [
+      },
         h("div", { className: "dshc-slot-title" }, event.summary),
         h("div", { className: "dshc-slot-time" }, hhmm(from) + "\u2013" + hhmm(to)),
         canEdit === true ? h("div", { className: "dshc-resize", title: t("drag.resizeTitle"), onPointerDown: (e) => { e.stopPropagation(); beginDrag(event, e, "resize"); } }) : null
-      ]);
+      );
     });
     const ghostBlock = ghost !== null && ghost.slot.dayKey === key
       ? h("div", {
           className: "dshc-slot dshc-ghost" + (ghost.conflicts > 0 ? " conflict" : ""),
           style: Object.assign({ top: (ghost.slot.minutes * (HOUR_PX / 60)) + "px", height: Math.max(18, ghost.slot.durationMinutes * (HOUR_PX / 60)) + "px" }, laneStyle(0)),
           key: "__ghost"
-        }, [
+        },
           h("div", { className: "dshc-slot-title" }, ghost.conflicts > 0 ? t("drag.conflict", { n: ghost.conflicts }) + " · " + t("drag.keep") : t("drag.drop")),
           h("div", { className: "dshc-slot-time" }, pad2(Math.floor(ghost.slot.minutes / 60)) + ":" + pad2(ghost.slot.minutes % 60) + " \u2192 " + pad2(Math.floor((ghost.slot.minutes + ghost.slot.durationMinutes) / 60)) + ":" + pad2((ghost.slot.minutes + ghost.slot.durationMinutes) % 60))
-        ])
+        )
       : null;
-    return h("div", { key, style: { minWidth: 0 } }, [
-      h("div", { className: "dshc-dayhead" }, [h("b", null, String(day.getDate())), " ", relativeDay(day)]),
+    // 可变参数：数组子节点要求 key，而这两块在这里各只出现一次。
+    return h("div", { key, style: { minWidth: 0 } },
+      h("div", { className: "dshc-dayhead" }, h("b", null, String(day.getDate())), " ", relativeDay(day)),
       h("div", {
         className: "dshc-daycol" + (key === today ? " today" : ""),
         "data-day": key,
@@ -1039,16 +1043,17 @@ function WeekView(props) {
         },
         title: t("action.new")
       }, blocks.concat(ghostBlock === null ? [] : [ghostBlock]))
-    ]);
+    );
   });
 
-  return h("div", null, [
+  // 可变参数而不是数组：数组子节点要求 key，而这三个都只在 WeekView 里出现一次。
+  return h("div", null,
     allDay.length > 0
       ? h("div", { style: { marginBottom: "8px" } }, allDay.map((event) => h(Row, { key: event.uid, event, onClick: onPick })))
       : null,
     h("div", { className: "dshc-week", ref: scroller }, [hoursColumn].concat(dayColumns)),
     canEdit === true ? h("div", { className: "dshc-draghint" }, t("drag.hint")) : null
-  ]);
+  );
 }
 
 /** 议程视图：从今天起按天分组，最像「接下来要干什么」。 */
@@ -1500,6 +1505,82 @@ function ConnectionForm(props) {
 
 // ───────────────────────────── 主面板 ─────────────────────────────
 
+// ───────────────────────────── 浮层 Esc 的模块级栈 ─────────────────────────────
+// 一个页面可能同时有多个 CalendarPanel（设置页一节 + 对话页悬浮面板）。如果各自往
+// document 挂捕获监听，stopPropagation 拦不住同阶段的其他监听 —— 一次 Esc 会连关
+// 两层；用全局 querySelector 兜底也会被另一个面板的浮层误触发。这里共用一个捕获
+// 监听，按「焦点所在 root / 最近打开的层」只关一层。
+const LAYER_ESCAPE_STACK = [];
+let layerEscapeListener = null;
+
+function panelRootOf(node) {
+  if (node === null || node === undefined || typeof node.closest !== "function") return null;
+  return node.closest(".dshc-root");
+}
+
+/** 目标是否位于别的宿主浮层内（那类浮层会自己处理 Esc）。 */
+function isForeignHostLayer(node) {
+  if (node === null || node === undefined || typeof node.closest !== "function") return false;
+  const layer = node.closest('[role="dialog"], [role="alertdialog"]');
+  if (layer === null) return false;
+  if (layer.closest(".dshc-root") !== null) return false;
+  if (layer.querySelector('[data-dshc-scope="1"]') !== null) return false;
+  return true;
+}
+
+/** 是否有别的宿主浮层盖在上面：有就把 Esc 让给宿主，别关下面的日历层。 */
+function hasForeignHostDialog() {
+  const dialogs = document.querySelectorAll('[role="dialog"], [role="alertdialog"]');
+  for (let i = 0; i < dialogs.length; i++) {
+    const layer = dialogs[i];
+    if (layer.closest(".dshc-root") !== null) continue;
+    if (layer.querySelector('[data-dshc-scope="1"]') !== null) continue;
+    if (layer.hidden === true || layer.getAttribute("aria-hidden") === "true") continue;
+    if (typeof window !== "undefined" && window !== null && typeof window.getComputedStyle === "function") {
+      const style = window.getComputedStyle(layer);
+      if (style.display === "none" || style.visibility === "hidden") continue;
+    }
+    return true;
+  }
+  return false;
+}
+
+function registerLayerEscape(root, closeTop) {
+  const entry = { root, closeTop };
+  LAYER_ESCAPE_STACK.push(entry);
+  if (layerEscapeListener === null) {
+    layerEscapeListener = (event) => {
+      if (event.key !== "Escape" || event.isComposing === true) return;
+      const target = event.target;
+      // 上层有别的宿主浮层（不是本插件渲染的）时，Esc 归它；
+      // 普通宿主元素（不在任何浮层里）仍然兜底关我们自己的层。
+      if (hasForeignHostDialog() || isForeignHostLayer(target)) return;
+      const root = panelRootOf(target);
+      let owner = null;
+      if (root !== null) {
+        for (let i = LAYER_ESCAPE_STACK.length - 1; i >= 0; i--) {
+          const candidate = LAYER_ESCAPE_STACK[i];
+          if (candidate.root !== null && candidate.root.contains(target)) { owner = candidate; break; }
+        }
+      }
+      if (owner === null) owner = LAYER_ESCAPE_STACK[LAYER_ESCAPE_STACK.length - 1] || null;
+      if (owner === null) return;
+      event.preventDefault();
+      event.stopPropagation();
+      owner.closeTop();
+    };
+    document.addEventListener("keydown", layerEscapeListener, true);
+  }
+  return () => {
+    const index = LAYER_ESCAPE_STACK.indexOf(entry);
+    if (index >= 0) LAYER_ESCAPE_STACK.splice(index, 1);
+    if (LAYER_ESCAPE_STACK.length === 0 && layerEscapeListener !== null) {
+      document.removeEventListener("keydown", layerEscapeListener, true);
+      layerEscapeListener = null;
+    }
+  };
+}
+
 function CalendarPanel(props) {
   const compact = props.compact === true;
   const [view, setView] = useState(loadStoredView);
@@ -1516,6 +1597,48 @@ function CalendarPanel(props) {
   const [configured, setConfigured] = useState(null);
   const [conn, setConn] = useState(null);
   const [connOpen, setConnOpen] = useState(false);
+
+  const layerOpen = draft !== null || selected !== null || connOpen === true;
+  const rootRef = useRef(null);
+
+  /** 让 Launcher 知道本面板里有没有浮层：宿主 Portal 的 Esc 不能被面板级监听抢走。 */
+  useEffect(() => {
+    const notify = typeof props.onLayerChange === "function" ? props.onLayerChange : null;
+    if (notify !== null) notify(layerOpen);
+    return () => { if (notify !== null) notify(false); };
+  }, [layerOpen]);
+
+  /** 面板内浮层的打开顺序：Esc 关最后打开的那个，而不是按类型硬编码。 */
+  const layerOrderRef = useRef([]);
+  useEffect(() => {
+    const openKeys = [];
+    if (selected !== null) openKeys.push("selected");
+    if (draft !== null) openKeys.push("draft");
+    if (connOpen === true) openKeys.push("conn");
+    const kept = layerOrderRef.current.filter((key) => openKeys.indexOf(key) !== -1);
+    const added = openKeys.filter((key) => kept.indexOf(key) === -1);
+    layerOrderRef.current = kept.concat(added);
+  }, [draft, connOpen, selected]);
+
+  /**
+   * Esc 分层关闭：有浮层时只关最上面一层（表单/连接设置 > 详情抽屉）。
+   * 监听走模块级的层栈 —— 多个 CalendarPanel 并存时一次 Esc 只关一层；
+   * 焦点在上层宿主 Portal 里时直接让行，交给宿主自己的 Esc 语义。
+   */
+  useEffect(() => {
+    if (layerOpen !== true) return () => {};
+    const root = rootRef.current;
+    if (root === null) return () => {};
+    const closeTop = () => {
+      const order = layerOrderRef.current;
+      const top = order.length === 0 ? null : order[order.length - 1];
+      if (top === "draft") { setDraft(null); setFormError(null); }
+      else if (top === "conn") setConnOpen(false);
+      else if (top === "selected") { setSelected(null); setConfirmDelete(false); }
+    };
+    return registerLayerEscape(root, closeTop);
+  }, [draft, selected, connOpen]);
+
   /** 乐观改期：uid → { start, end }。等服务器回读到同样的时间再撤掉，避免闪回。 */
   const [overrides, setOverrides] = useState({});
   const [undo, setUndo] = useState(null);
@@ -1737,7 +1860,7 @@ function CalendarPanel(props) {
   const openEvent = (event) => { setConfirmDelete(false); setSelected(event); };
   const createAt = (day, hour) => setDraft(draftAt(day, hour));
 
-  return h("div", { className: "dshc-root" }, [
+  return h("div", { ref: rootRef, className: "dshc-root" }, [
     h("div", { className: "dshc-shell" }, [
       banner !== null ? h("div", { className: "dshc-alert demo", role: "status", "aria-live": "polite" }, banner) : null,
       undo !== null
@@ -1812,12 +1935,18 @@ function CalendarSection() {
 /** 对话页右下角的小按钮 + 悬浮面板（自己挂 root，不占用宿主槽位）。 */
 function Launcher() {
   const [open, setOpen] = useState(false);
+  const [layerOpen, setLayerOpen] = useState(false);
   useEffect(() => {
     if (open !== true) return () => {};
-    const onKey = (event) => { if (event.key === "Escape") setOpen(false); };
+    const onKey = (event) => {
+      if (event.key !== "Escape" || event.isComposing === true) return;
+      // 浮层交给 CalendarPanel 的层栈；宿主 Portal 的 Esc 交给宿主组件。
+      if (layerOpen === true) return;
+      setOpen(false);
+    };
     document.addEventListener("keydown", onKey);
     return () => document.removeEventListener("keydown", onKey);
-  }, [open]);
+  }, [open, layerOpen]);
   const calendarIcon = h("svg", { width: 18, height: 18, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: 1.8, strokeLinecap: "round" }, [
     h("rect", { key: "r", x: 3, y: 5, width: 18, height: 16, rx: 3 }),
     h("path", { key: "l", d: "M3 10h18M8 3v4M16 3v4" })
@@ -1830,7 +1959,7 @@ function Launcher() {
       "aria-label": t("nav.title"),
       onClick: () => setOpen((value) => !value)
     }, calendarIcon),
-    open === true ? h("div", { className: "dshc-float" }, h(CalendarPanel, { compact: true })) : null
+    open === true ? h("div", { className: "dshc-float" }, h(CalendarPanel, { compact: true, onLayerChange: setLayerOpen })) : null
   ]);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-calendar",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "DSH 日历插件：CalDAV 日程查询、创建、修改、删除与搜索，支持 Google OAuth2、iCloud、Nextcloud 与自建服务。",
   "type": "module",
   "main": "lib/index.js",
@@ -60,6 +60,9 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "jsdom": "^30.1.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "typescript": "^5.6.0"
   },
   "repository": {