dsh-nav-fold 0.3.3 → 0.3.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +13 -53
  2. package/lib/client.js +145 -19
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,62 +1,22 @@
1
1
  # Changelog
2
2
 
3
- ## 0.3.3 — 2026-11-16
3
+ ## 0.3.6 — 2026-11-16
4
4
 
5
- - 固定顶部区域不再"先滑一段再钉住":sticky 的 top 改为按实测内容偏移(nav 8px / 标题行 110px),滚动全程位置不变、行间间隙不再被吃掉
6
- - 设置页按档位分组:「图标档」「收起档」两个分组标题,行标签统一为「固定顶部区域」(小号),不再出现两个同名大标题
5
+ 相对 0.3.4 的全部变更。
7
6
 
8
- ## 0.3.2 — 2026-11-16
7
+ ### 修复
9
8
 
10
- 修复 0.3.1 固定方式带来的三个问题(K1–K3)。
9
+ - **固定区两条缝漏内容**:图标排上方 8px 与图标排/工作区标题之间 10px 都没有归属元素,滚动时会话内容会从缝里穿过。现在用实心阴影补齐(不参与命中测试、不影响布局)。
10
+ - **工作区标题行压住滚动条**:标题行底色会盖住右侧滚动条。现在底色改由伪元素绘制,并在可滚动时按 max(实测槽位, 12px) 让位——overlay 滚动条(实测槽位 0)同样会让开。
11
+ - **导航会往下滑**:测量偏移时用普通内联样式解除 sticky,压不过样式表里的 !important,导致偏移每次重绘都在叠加。现在改用内联 !important,并给导航偏移加 80px 上限。
12
+ - **标题行失联降级**:外壳多包几层时找不到工作区标题行,会退化成只固定导航(标题行跟着滚、缝隙露内容)。现在递归深度 6 → 12,并改为匹配任意「矮标题 + 高列表」的相邻子节点对。
13
+ - **重排瞬间露内容**:开关开发者工具等改变视口时,旧几何量会让缝短暂露出内容。现在 resize/visualViewport 触发瞬间先把缝隙归零(失败关闭),再 rAF 与 220ms 各重测一次;并给滚动区补了 ResizeObserver。
11
14
 
12
- - **改回原生滚动 + 双层 sticky**:不再重排外层布局,滚动仍由外壳负责 → 滚动条位置不变、侧栏宽度与自适应列数不再跳变
13
- - 图标排与工作区标题行一起固定在顶部,只有文件夹与会话列表滚动
14
- - 分隔线改为绝对定位满宽(图标档是 grid、收起档是 flex,之前 grid 下只占第一列)
15
- - 找不到工作区标题行时降级为「仅固定导航」,侧栏不可见时挂起,均不影响布局
16
- - 诊断区显示固定状态(已应用 / 仅固定导航 / 待定 / 未启用)与底色
15
+ ### 新增
17
16
 
18
- ## 0.3.1 — 2026-11-16
17
+ - 诊断区增加一行:滚动条实测槽位 / 实际让位 / 是否可滚动。
19
18
 
20
- 修正 0.3.0 的固定方式(0.3.0 未公开发布,仅内部迭代)。
19
+ ### 保持不变
21
20
 
22
- - 改为「顶部固定区」:图标排(或收起行)与工作区标题(含搜索/视图/新建)一起固定在顶部,**只有工作区文件夹与会话列表滚动**
23
- - 固定区底色运行时取自外壳背景,不再写死白底,浅色/深色下都不会出现色块
24
- - 侧栏不可见时(如手机抽屉收起)挂起不误报,展开后自动落位
25
- - 结构不匹配时自动回退为粘性导航,并在诊断区记录一条异常
26
- - 诊断区新增「状态 / 最近告警 / 固定状态(含底色)」三行
27
- - 其余沿用 0.3.0:列数(自适应/8/7/6/5/4,手机自适应最多 6 列)、与外壳「更多」共存、语言回退英文、观察器收窄
28
-
29
- ## 0.3.0 — 2026-11-16
30
-
31
- - 图标档支持吸附:滚动会话列表时这排图标固定在侧栏顶部(默认开);收起档可吸附(默认关);文字档不提供(置灰并说明原因),避免把会话区挤没
32
- - 图标档每行数量可选:自适应(默认,手机上最多 6 列)/ 8 / 7 / 6 / 5 / 4;选 7、8 列时会按侧栏实宽计算每列像素,低于 32px 给出提示并可一键切回自适应
33
- - 与新版外壳共存:检测到侧栏自带「取消固定 / 更多」入口管理(rc.2+ 的 `button.panelUnpin`)时,收起态不再显示本插件的「全部」入口(可在设置里关闭该行为)
34
- - 新增诊断区(默认折叠):结构版本、入口行数、档位、吸附与列数状态、最近一次告警时间,一键复制
35
- - 语言回退修正:非中文环境缺词条时回退英文(此前回退中文,会中英混排)
36
- - 性能:DOM 观察范围从整个 document 收窄到侧栏容器;另加 2 秒 `isConnected` 兜底,容器被整体替换时仍能自愈
37
- - 设置面板新增「只重置控件样式」,可只把控件样式恢复成三档选择器
38
-
39
- ## 0.2.0 — 2026-11-15
40
-
41
- 适配 DSH 0.2.2-rc.2 / rc.3 的侧栏结构变化(入口行外面多了一层 `div.panelEntry`,行内新增「取消固定」按钮)。
42
-
43
- - 定位器改为结构判定:`button`(rc.1 及更早)与 `div > button.panelRow`(rc.2+)都认,不再依赖"子节点只能是 button/span"
44
- - 窄屏/图标轨下外壳不渲染标题 span 时也能识别(用 aria-label 兜底)
45
- - 保留行、计数徽标、紧凑网格、收起态全部按包裹层生效(标记同时打在包裹层与按钮上)
46
- - rc.2+ 外壳已给每行配 Tooltip,不再叠加原生 `title`(避免双提示)
47
- - 找不到导航时打印结构诊断(各 nav 的子节点标签与层数),便于宿主改版后定位
48
- - 发布范围收紧为 `>=0.2.2-rc.1 <0.3.0`
49
-
50
- ## 0.1.0 — 2026-11-12
51
-
52
- 首个公开版本。
53
-
54
- - 三态折叠:文字行 / 图标网格 / 收起,收起时保留的行可逐项选择
55
- - 三种控件模型:三档选择器、单按钮循环、标题行(点标题展开/收起)
56
- - 自动档:首次打开按窗口宽高选档(宽 <768 或高 <760 进图标网格)
57
- - 桌面与手机分别记住档位
58
- - 收起态计数徽标;收起态「全部入口」浮层可直达任意面板
59
- - 图标档 / 56px 图标轨下每行带原生 `title`,悬停显示插件名
60
- - 设置面板:行式布局,含自动档开关、保留行多选、恢复默认(二次确认)
61
- - 文案跟随 shell 语言(zh / en)
62
- - 不读写官方 `panelPins`,不修改官方行结构,卸载即完全复原
21
+ - 滚动仍由外壳 .scrollArea 负责:侧栏宽度与自适应列数不受固定开关影响(桌面 264px / 7 列,手机 6 列)。
22
+ - 支持 DSH >= 0.2.2-rc.1 < 0.3.0(实测 rc.1 / rc.2 / rc.3)。
package/lib/client.js CHANGED
@@ -29,7 +29,7 @@ const react = require("react");
29
29
  /** 插件名(cordis 插件标识) */
30
30
  const name = "nav-fold";
31
31
  /** 版本号:必须与 package.json.version 一致(有单测守着) */
32
- const PLUGIN_VERSION = "0.3.3";
32
+ const PLUGIN_VERSION = "0.3.6";
33
33
  /** 设置分区 / 控制条占用者 id */
34
34
  const ENTRY_ID = "nav-fold";
35
35
  /** 注入样式表的幂等标记 */
@@ -329,7 +329,10 @@ const CSS_TEXT = [
329
329
  'nav[data-navfold="compact"][data-navfold-cols="5"]>button,nav[data-navfold="compact"][data-navfold-cols="5"]>div>button,nav[data-navfold="compact"][data-navfold-cols="4"]>button,nav[data-navfold="compact"][data-navfold-cols="4"]>div>button{height:36px!important;min-height:36px!important}',
330
330
  // 顶部固定区:原生滚动不变,nav 与工作区标题行用 sticky 贴在滚动口(不重排布局 → 宽度/列数不变)
331
331
  'nav[data-navfold-pinned="on"],nav[data-navfold-pinned="nav-only"]{position:sticky!important;top:var(--navfold-pin-top,0px)!important;z-index:4!important;background:var(--navfold-pin-bg,transparent)!important}',
332
- '[data-navfold-pin-head]{position:sticky!important;top:var(--navfold-pin-head-top,92px)!important;z-index:3!important;background:var(--navfold-pin-bg,transparent)!important}',
332
+ '[data-navfold-pin-head]{position:sticky!important;top:var(--navfold-pin-head-top,92px)!important;z-index:3!important;background:transparent!important}',
333
+ '[data-navfold-pin-head]::before{content:"";position:absolute;top:0;bottom:0;left:0;right:var(--navfold-gutter,0px);background:var(--navfold-pin-bg,transparent);z-index:-1;pointer-events:none}',
334
+ // 两条缝补色:nav 上方(sticky 偏移区)与 nav/标题行之间,用实心阴影,不改 DOM 不影响布局
335
+ 'nav[data-navfold-pinned="on"],nav[data-navfold-pinned="nav-only"]{box-shadow:0 calc(-1 * var(--navfold-pin-top,0px)) 0 0 var(--navfold-pin-bg,transparent),0 var(--navfold-pin-gap,0px) 0 0 var(--navfold-pin-bg,transparent)!important}',
333
336
  // 分隔线用绝对定位:grid(图标档)与 flex(收起档)下都满宽
334
337
  'nav[data-navfold-pinned="on"]::after,nav[data-navfold-pinned="nav-only"]::after{content:"";position:absolute;left:0;right:0;bottom:-1px;height:1px;pointer-events:none;background:linear-gradient(to right,transparent 0%,var(--dsw-alias-border-l1,rgba(0,0,0,.14)) 22%,var(--dsw-alias-border-l1,rgba(0,0,0,.14)) 78%,transparent 100%)}',
335
338
  // 设置面板:列数/吸附选中态沿用控件样式那套,提示用状态色
@@ -416,6 +419,14 @@ const runtime = {
416
419
  pinBg: "",
417
420
  pinTop: 0,
418
421
  pinHeadTop: 0,
422
+ pinGap: 0,
423
+ pinGutter: 0,
424
+ pinInset: 0,
425
+ pinScrollable: false,
426
+ areaResize: null,
427
+ onResize: null,
428
+ pinMeasured: false,
429
+ pinHeadMeasured: false,
419
430
  anomalies: []
420
431
  };
421
432
 
@@ -525,12 +536,13 @@ function rectHeight(el) {
525
536
  * @returns 容器元素或 null。
526
537
  */
527
538
  function findStack(node, depth) {
528
- if (!node || depth > 6) return null;
539
+ if (!node || depth > 12) return null;
529
540
  const kids = node.children || [];
530
- if (kids.length >= 2) {
531
- const head = rectHeight(kids[0]);
532
- const body = rectHeight(kids[1]);
533
- if (head > 0 && head < 64 && body > 120) return node;
541
+ // 任意相邻的两个子节点:「矮标题 + 高列表」即可(外壳可能在外面再包几层)
542
+ for (let i = 0; i + 1 < kids.length; i += 1) {
543
+ const head = rectHeight(kids[i]);
544
+ const body = rectHeight(kids[i + 1]);
545
+ if (head > 0 && head < 64 && body > 120) return { parent: node, headIndex: i };
534
546
  }
535
547
  for (let i = 0; i < kids.length; i += 1) {
536
548
  const hit = findStack(kids[i], depth + 1);
@@ -556,9 +568,11 @@ function findPinTargets(nav) {
556
568
  break;
557
569
  }
558
570
  if (!region) return null;
559
- const stack = findStack(region, 0);
560
- if (!stack || !stack.children || stack.children.length < 2) return null;
561
- return { area: area, head: stack.children[0] };
571
+ const found = findStack(region, 0);
572
+ if (!found || !found.parent || !found.parent.children) return null;
573
+ const head = found.parent.children[found.headIndex];
574
+ if (!head) return null;
575
+ return { area: area, head: head };
562
576
  }
563
577
 
564
578
  /**
@@ -589,6 +603,8 @@ function noteAnomaly(kind) {
589
603
 
590
604
  /** 清掉固定区标记(只摘标题行标记,不动外壳布局)。 */
591
605
  function clearPin() {
606
+ runtime.pinMeasured = false;
607
+ runtime.pinHeadMeasured = false;
592
608
  const nodes = runtime.pinNodes;
593
609
  if (nodes && nodes.head && typeof nodes.head.removeAttribute === "function") {
594
610
  nodes.head.removeAttribute(PIN_ATTR_HEAD);
@@ -597,24 +613,69 @@ function clearPin() {
597
613
  runtime.pinBg = "";
598
614
  }
599
615
 
616
+ /** 偏移量的合理上限(导航/标题行不会超过这个高度) */
617
+ const PIN_MAX_OFFSET = 240;
618
+ /** 导航自身偏移的合理上限(只有顶部内边距那么大) */
619
+ const PIN_MAX_NAV_OFFSET = 80;
620
+ /** 有滚动条时至少让出的宽度(cover overlay 滚动条:它不占布局但会画在内容上) */
621
+ const PIN_MIN_GUTTER = 12;
622
+
600
623
  /**
601
- * 元素在滚动内容里的偏移(与当前滚动位置无关)。
624
+ * 量元素在滚动内容里的偏移。
625
+ * 关键:测量前临时把 sticky 摘掉——否则算出来的是「已钉住的 top + 滚动量」,
626
+ * 写回变量后每次重绘都会再叠加一次滚动量(正反馈,导航会被推到列表下方)。
602
627
  * @param area - 滚动区。
603
628
  * @param el - 目标元素。
604
- * @returns 像素偏移,取不到返回 0。
605
- */
606
- function contentOffset(area, el) {
607
- if (!area || !el || typeof area.getBoundingClientRect !== "function" || typeof el.getBoundingClientRect !== "function") return 0;
629
+ * @returns 像素偏移;失败返回 NaN。
630
+ */
631
+ function measureLayoutOffset(area, el) {
632
+ if (!area || !el || typeof area.getBoundingClientRect !== "function" || typeof el.getBoundingClientRect !== "function") return NaN;
633
+ const style = el.style;
634
+ const canStyle = !!style && typeof style.setProperty === "function";
635
+ const readProp = (name, kind) => (canStyle && typeof style[kind] === "function" ? style[kind](name) || "" : "");
636
+ const prevPos = readProp("position", "getPropertyValue");
637
+ const prevPosPrio = readProp("position", "getPropertyPriority");
638
+ const prevTop = readProp("top", "getPropertyValue");
639
+ const prevTopPrio = readProp("top", "getPropertyPriority");
608
640
  try {
641
+ // 关键:我们的 sticky 规则带 !important,内联普通声明压不过它,必须是内联 !important
642
+ if (canStyle) {
643
+ style.setProperty("position", "static", "important");
644
+ style.setProperty("top", "auto", "important");
645
+ }
609
646
  const ar = area.getBoundingClientRect();
610
647
  const er = el.getBoundingClientRect();
611
648
  const scroll = typeof area.scrollTop === "number" ? area.scrollTop : 0;
612
- return Math.max(0, Math.round(er.top - ar.top + scroll));
649
+ return Math.round(er.top - ar.top + scroll);
613
650
  } catch (err) {
614
- return 0;
651
+ return NaN;
652
+ } finally {
653
+ if (canStyle) {
654
+ const put = (name, value, priority) => {
655
+ if (value) style.setProperty(name, value, priority || "");
656
+ else if (typeof style.removeProperty === "function") style.removeProperty(name);
657
+ };
658
+ put("position", prevPos, prevPosPrio);
659
+ put("top", prevTop, prevTopPrio);
660
+ }
615
661
  }
616
662
  }
617
663
 
664
+ /**
665
+ * 偏移量的准入判定:越界保留旧值;已滚动时只接受"不变或变小",防止再次测到 sticky 态。
666
+ * @param next - 新测到的值。
667
+ * @param prev - 上一次的值。
668
+ * @param scroll - 当前滚动量。
669
+ * @param measured - 是否已有基准。
670
+ * @returns 采用的值。
671
+ */
672
+ function acceptOffset(next, prev, scroll, measured) {
673
+ if (!isFinite(next) || next < 0 || next > PIN_MAX_OFFSET) return prev;
674
+ if (!measured) return next;
675
+ if (scroll > 0 && next > prev + 2) return prev;
676
+ return next;
677
+ }
678
+
618
679
  /**
619
680
  * 把 nav 高度与两个 sticky 偏移写进滚动区的 CSS 变量。
620
681
  * 用内容偏移而不是写死 0:这样滚动时顶部不动、也不吃掉行间空隙。
@@ -625,14 +686,31 @@ function contentOffset(area, el) {
625
686
  function syncPinOffsets(area, nav, head) {
626
687
  if (!area || !area.style || typeof area.style.setProperty !== "function") return;
627
688
  const height = Math.round(rectHeight(nav));
628
- const navTop = contentOffset(area, nav);
629
- const headTop = head ? contentOffset(area, head) : navTop + (height || 0);
689
+ const scroll = typeof area.scrollTop === "number" ? area.scrollTop : 0;
690
+ const navRaw = measureLayoutOffset(area, nav);
691
+ const navTop = Math.min(PIN_MAX_NAV_OFFSET, acceptOffset(navRaw, runtime.pinTop, scroll, runtime.pinMeasured));
692
+ const headTop = head
693
+ ? acceptOffset(measureLayoutOffset(area, head), runtime.pinHeadTop, scroll, runtime.pinHeadMeasured)
694
+ : navTop + (height || 0);
695
+ const gap = head ? Math.max(0, Math.min(80, headTop - (navTop + (height || 0)))) : 0;
696
+ // 滚动条让位:经典滚动条占布局宽度(可实测),overlay 滚动条不占(实测 0 但会画在内容上)
697
+ const measuredGutter = Math.max(0, Math.min(40, (area.offsetWidth || 0) - (area.clientWidth || 0)));
698
+ const scrollable = (area.scrollHeight || 0) > (area.clientHeight || 0) + 1;
699
+ const gutter = scrollable ? Math.max(measuredGutter, PIN_MIN_GUTTER) : 0;
700
+ runtime.pinGutter = measuredGutter;
701
+ runtime.pinInset = gutter;
702
+ runtime.pinScrollable = scrollable;
630
703
  runtime.pinTop = navTop;
631
704
  runtime.pinHeadTop = headTop;
705
+ runtime.pinGap = gap;
706
+ runtime.pinMeasured = true;
707
+ runtime.pinHeadMeasured = true;
632
708
  try {
633
709
  if (height) area.style.setProperty("--navfold-nav-h", height + "px");
634
710
  area.style.setProperty("--navfold-pin-top", navTop + "px");
635
711
  area.style.setProperty("--navfold-pin-head-top", headTop + "px");
712
+ area.style.setProperty("--navfold-pin-gap", gap + "px");
713
+ area.style.setProperty("--navfold-gutter", gutter + "px");
636
714
  } catch (err) {
637
715
  /* 设不上就退回 CSS 默认值 */
638
716
  }
@@ -1462,6 +1540,7 @@ function diagnosticsText() {
1462
1540
  "入口行数 " + runtime.totals.total,
1463
1541
  "当前档位 " + runtime.mode + " / 控件样式 " + runtime.model,
1464
1542
  "固定开关 图标档 " + (runtime.stickCompact ? "开" : "关") + ",收起档 " + (runtime.stickHidden ? "开" : "关"),
1543
+ "滚动条 实测槽位 " + runtime.pinGutter + "px · 实际让位 " + runtime.pinInset + "px · " + (runtime.pinScrollable ? "可滚动" : "无滚动"),
1465
1544
  "列数 " + runtime.cols + (runtime.cols === "auto" ? "(自适应)" : ""),
1466
1545
  "外壳自带入口管理 " + (runtime.shellHasMore ? "是" : "否"),
1467
1546
  "UA " + ua
@@ -1925,6 +2004,22 @@ function retargetObserver(target) {
1925
2004
  }
1926
2005
  }
1927
2006
 
2007
+ /** 重排瞬间先把缝隙归零(失败关闭),避免露出内容;随后重测恢复。 */
2008
+ function failClosedGap() {
2009
+ const nav = runtime.nav;
2010
+ const area = nav ? nav.parentElement || nav.parentNode : null;
2011
+ if (area && area.style && typeof area.style.setProperty === "function") {
2012
+ try {
2013
+ area.style.setProperty("--navfold-pin-gap", "0px");
2014
+ } catch (err) {
2015
+ /* 设不上不影响 */
2016
+ }
2017
+ }
2018
+ // 允许重新测量(此时测量是可靠的:内联 !important 会临时解除 sticky)
2019
+ runtime.pinMeasured = false;
2020
+ runtime.pinHeadMeasured = false;
2021
+ }
2022
+
1928
2023
  function attachDom() {
1929
2024
  const schedule = () => {
1930
2025
  if (runtime.timer) return;
@@ -1964,10 +2059,24 @@ function attachDom() {
1964
2059
  }, 2000);
1965
2060
  }
1966
2061
  }
2062
+ // 重排(含开发者工具开关)时先失败关闭,再重测;不依赖 MutationObserver
2063
+ runtime.onResize = () => {
2064
+ failClosedGap();
2065
+ if (typeof window.requestAnimationFrame === "function") window.requestAnimationFrame(() => scan());
2066
+ if (typeof window.setTimeout === "function") window.setTimeout(() => scan(), 220);
2067
+ };
2068
+ if (typeof window.addEventListener === "function") window.addEventListener("resize", runtime.onResize);
2069
+ const vv = window.visualViewport;
2070
+ if (vv && typeof vv.addEventListener === "function") vv.addEventListener("resize", runtime.onResize);
1967
2071
  const Resize = window.ResizeObserver;
1968
2072
  if (typeof Resize === "function" && runtime.nav) {
1969
2073
  runtime.resize = new Resize(() => schedule());
1970
2074
  runtime.resize.observe(runtime.nav);
2075
+ const area = runtime.nav.parentElement || runtime.nav.parentNode;
2076
+ if (area) {
2077
+ runtime.areaResize = new Resize(() => schedule());
2078
+ runtime.areaResize.observe(area);
2079
+ }
1971
2080
  }
1972
2081
  return () => {
1973
2082
  if (runtime.observer) {
@@ -1994,6 +2103,20 @@ function attachDom() {
1994
2103
  }
1995
2104
  runtime.resize = null;
1996
2105
  }
2106
+ if (runtime.areaResize) {
2107
+ try {
2108
+ runtime.areaResize.disconnect();
2109
+ } catch (err) {
2110
+ /* 已断开 */
2111
+ }
2112
+ runtime.areaResize = null;
2113
+ }
2114
+ if (runtime.onResize) {
2115
+ if (typeof window.removeEventListener === "function") window.removeEventListener("resize", runtime.onResize);
2116
+ const vv = window.visualViewport;
2117
+ if (vv && typeof vv.removeEventListener === "function") vv.removeEventListener("resize", runtime.onResize);
2118
+ runtime.onResize = null;
2119
+ }
1997
2120
  if (runtime.timer) {
1998
2121
  window.clearTimeout(runtime.timer);
1999
2122
  runtime.timer = 0;
@@ -2600,6 +2723,9 @@ exports.__internals = {
2600
2723
  looksLikePanelNav: looksLikePanelNav,
2601
2724
  findNav: findNav,
2602
2725
  renderBar: renderBar,
2726
+ paintNav: paintNav,
2727
+ measureLayoutOffset: measureLayoutOffset,
2728
+ acceptOffset: acceptOffset,
2603
2729
  setMode: setMode,
2604
2730
  setModel: setModel,
2605
2731
  getMode: getMode,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-nav-fold",
3
- "version": "0.3.3",
3
+ "version": "0.3.6",
4
4
  "description": "nav-fold 导航折叠 · 把 DSH 左侧栏顶部的功能入口折叠成图标网格或收起(三态 + 三种控件模型,兼容 rc.1 扁平行与 rc.2+ 包裹行)",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",