dsh-nav-fold 0.0.0-stage → 0.1.0

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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,15 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 — 2026-11-12
4
+
5
+ 首个公开版本。
6
+
7
+ - 三态折叠:文字行 / 图标网格 / 收起,收起时保留的行可逐项选择
8
+ - 三种控件模型:三档选择器、单按钮循环、标题行(点标题展开/收起)
9
+ - 自动档:首次打开按窗口宽高选档(宽 <768 或高 <760 进图标网格)
10
+ - 桌面与手机分别记住档位
11
+ - 收起态计数徽标;收起态「全部入口」浮层可直达任意面板
12
+ - 图标档 / 56px 图标轨下每行带原生 `title`,悬停显示插件名
13
+ - 设置面板:行式布局,含自动档开关、保留行多选、恢复默认(二次确认)
14
+ - 文案跟随 shell 语言(zh / en)
15
+ - 不读写官方 `panelPins`,不修改官方行结构,卸载即完全复原
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-nav-fold contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,121 @@
1
- # Temporary Holding Version
1
+ # dsh-nav-fold(nav-fold 导航折叠)
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/dsh-nav-fold)](https://www.npmjs.com/package/dsh-nav-fold)
4
+ [![ci](https://github.com/TIPE2587/dsh-nav-fold/actions/workflows/ci.yml/badge.svg)](https://github.com/TIPE2587/dsh-nav-fold/actions/workflows/ci.yml)
5
+ [![license](https://img.shields.io/npm/l/dsh-nav-fold)](./LICENSE)
6
+
7
+ 给 DSH 左侧栏顶部的**功能入口**列表加三态折叠——**文字行 → 紧凑图标网格 → 收起**,把被插件挤占的高度还给会话列表,尤其针对手机抽屉。
8
+
9
+ ## 为什么要它
10
+
11
+ 侧栏顶部那串入口(Plugins / 自动化任务 / 上下文洞察 / …)是官方 `sidebar.panellist` 列表,每装一个带主面板的插件就多一行(36px)。实测 264px 宽的一列里 8 行占 **340px**,其下工作区/会话区只剩 **170px**;手机抽屉里更惨,而且这块既不滚动也不折叠。
12
+
13
+ ## 三种形态
14
+
15
+ | 形态 | 表现 | 实测高度 |
16
+ |---|---|---|
17
+ | 文字行 `expanded` | 原样,装完零视觉变化 | 340px + 控制条 22px |
18
+ | 图标网格 `compact` | 图标网格、隐文字(保留无障碍名)、行高 32px | **92px** |
19
+ | 收起 `hidden` | 只留「收起时保留」勾选的行(默认第一行)+「更多」锚点 | **100px** |
20
+
21
+ ## 控制条在哪
22
+
23
+ 挂在**被折叠那一组的末尾**(「更多」下面一行)——它的作用对象就是上面那几行,不是会话列表,也不是设置区:
24
+
25
+ ```
26
+ [ Plugins ]
27
+ [ Automation tasks ]
28
+ … 8 行 …
29
+ [ More ]
30
+ [ ✎ 已收起 7 ≡ 文字 ▦ 图标 ⌃ 收起 ☰ 全部 ] ← 控制条
31
+ [ Workspaces 🔍 ⚙ + ]
32
+ ```
33
+
34
+ - 收起态左侧显示计数徽标(`已收起 7` / `7 collapsed`)
35
+ - 56px 图标轨里退化为单个图标,点一下换下一档
36
+ - **图标档 / 图标轨**下每行带原生 `title`(悬停显示插件名;打 `data-navfold-title` 标记,切回文字档或卸载时摘除);文字档不加,避免与可见文字重复
37
+ - 收起态多一个 **`☰ 全部`**:点开浮层列出所有入口,点任意一项即跳转(产品自带的「更多」菜单不列面板,这是收起态下的一键直达)
38
+ - 浮层优先开在控制条上方,上方放不下自动翻到下方;点条目 / Esc / 点外部 / 滚动都会关闭
39
+
40
+ ## 三种控件模型(设置里切换)
41
+
42
+ | 模型 | 样子 |
43
+ |---|---|
44
+ | `segmented`(默认) | 三个语义恒定的按钮,当前档高亮(`aria-pressed`) |
45
+ | `cycle` | 一个按钮,**一次只显示当前档那一个图标**,点了换成下一档 |
46
+ | `header` | **标题行**:整组收成一行 `⌃ 功能入口 8`(位于入口列表最上方),点标题展开/收起;只有"文字行 / 收起"两态,图标网格档不可用。被外壳挪位会自动拉回,连续 3 次失败退回 `segmented` |
47
+
48
+ ## 设置面板(设置 → nav-fold 导航折叠)
49
+
50
+ 行式布局,与 shell 自己的设置项一致:
51
+
52
+ | 分组 | 内容 |
53
+ |---|---|
54
+ | 摘要 | `文字行 · 8 个入口` |
55
+ | 控制条样式 | segmented:三档选择器 / 单按钮循环 / 标题行 |
56
+ | 自动档 | switch。开着时:窗口宽 <768 或高 <760 首次打开进图标档;手动选过以你为准 |
57
+ | 收起时保留 | `1/8 保留` 计数 + `全部`/`清空` + 逐行 chip(选中蓝底 + ✓);一个不选默认保留第一行 |
58
+ | 恢复默认 | **点两次**确认后清掉 `mode / mode-narrow / model / auto / keep / mode-stash` 六个键(第一次只进入确认态,3 秒不点自动取消) |
59
+
60
+ 所有状态样式写在注入的样式表里(属性选择器驱动),组件内联只负责布局。
61
+
62
+ ## 偏好与存储
63
+
64
+ | 键 | 含义 | 缺省 |
65
+ |---|---|---|
66
+ | `dsh-nav-fold/v1/mode` | 桌面档位 | `expanded` |
67
+ | `dsh-nav-fold/v1/mode-narrow` | 手机档位 | `compact` |
68
+ | `dsh-nav-fold/v1/model` | 控件模型 | `segmented` |
69
+ | `dsh-nav-fold/v1/auto` | 自动档开关 | `on` |
70
+ | `dsh-nav-fold/v1/keep` | 收起时保留的行(按显示名) | `[]` → 保留第一行 |
71
+
72
+ 桌面与手机**各记一份档位**;文案跟随 shell 语言(zh / en),品牌名 `nav-fold 导航折叠` 不翻译。
73
+
74
+ ## 设计边界
75
+
76
+ - **不读写官方 `panelPins`**(ui-sidebar 闭包私有内存,插件重载即重置),两套机制正交。
77
+ - **不改官方行**:只在命中的 nav 上加属性、在行上打 `data-navfold-keep`,并把自己那一个控制条节点追加到该 nav 末尾;卸载即全部摘除。
78
+ - 追加节点由 MutationObserver 守护(外壳重渲染把它挤掉时 150ms 内挂回);观察器**忽略自身变更**,避免 150ms 一次无限重绘。
79
+ - 首屏宽限 3s:React 还没渲染出侧栏时不喊"结构变了";宽限后仍找不到才 warn 一次,UI 保持原样。
80
+ - 只依赖 `slots` 与 `locale` 两个客户端服务;折叠本身是纯 DOM。
81
+
82
+ ## 安装
83
+
84
+ 要求:DSH **≥ 0.2.2-rc.1**,Node **≥ 22**。
85
+
86
+ ### 从 npm(推荐)
87
+
88
+ ```bash
89
+ dsh plugin --profile web add dsh-nav-fold
90
+ sudo systemctl restart dsh-web # 首次安装需要重启 Host 才会加载浏览器半
91
+ ```
92
+
93
+ ### 从源码(开发/二次修改)
94
+
95
+ ```bash
96
+ git clone git@github.com:TIPE2587/dsh-nav-fold.git
97
+ ```
98
+
99
+ 把仓库以 `link:` 方式加进 profile 的 `dependencies`,并把包名加入 `dsh.profile.bundles`,重启 Host。
100
+ 之后**只改浏览器半不需要重启**,刷新页面即可(浏览器会缓存模块,验证改动请 `Ctrl+Shift+R`)。
101
+
102
+ ## 卸载
103
+
104
+ 1. 从 profile `package.json` 删掉 `dependencies["dsh-nav-fold"]` 与 `bundles` 里的 `dsh-nav-fold`
105
+ 2. 删符号链接 `node_modules/dsh-nav-fold`
106
+ 3. 重启 Host;localStorage 里五个键可留可删(无引用)
107
+
108
+ ## 开发
109
+
110
+ ```bash
111
+ node --test test/*.test.mjs # 14 项,直接测上线产物 lib/client.js(vm + 假 DOM,零依赖)
112
+ ```
113
+
114
+ - `lib/client.js` 就是上线文件,无构建步骤;外层是 DSH 的 `window.__ModuleLoader__.load({ id, factory })` 包裹。
115
+ - `lib/index.js` 宿主半是空壳,存在只为让包被 Loader 收录,从而让 `dsh.client` 扫描收进浏览器半。
116
+
117
+ ## 版本契约(升级 DSH 后看这里)
118
+
119
+ 定位器只依赖结构,不依赖 CSS Modules 的 hash 类名:`nav` 的子元素必须是 `button`/`span`(外加我们自己的控制条 `div`),至少一行是"图标 span + 文字 span"两段结构,且不含 `input/textarea/select/a/form`。图标轨判定优先读外壳的 `[data-sidebar-collapsed="true"]`(收起时内容是被平移进轨道的,布局宽度量不出来),读不到再退回宽度判断。
120
+
121
+ 若控制台出现 `未找到「功能入口」导航`,说明外壳结构变了 —— 改 `looksLikePanelNav` 即可。
@@ -0,0 +1,9 @@
1
+ # dsh-nav-fold bundle patch
2
+ #
3
+ # 只插入一行宿主插件;本插件的宿主半是空壳,作用是把包挂进 Loader,
4
+ # 让 dsh-client-modules 的 dsh.client 扫描收录浏览器半。
5
+ #
6
+ # 注意:patch 会【整体替换】目标行 config,按 id 覆盖本行时必须重述下面每个键。
7
+ - insert:
8
+ - id: nav-fold
9
+ name: 'dsh-nav-fold'
package/icon.svg ADDED
@@ -0,0 +1,6 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="nav-fold">
2
+ <rect x="3" y="5" width="26" height="22" rx="5.5" fill="none" stroke="#4D6BFE" stroke-width="2.2"/>
3
+ <line x1="12.8" y1="6" x2="12.8" y2="26" stroke="#4D6BFE" stroke-width="2.2"/>
4
+ <path d="M6.2 17.4 8 15.2l1.8 2.2" fill="none" stroke="#4D6BFE" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
5
+ <path d="M16.4 11.4h9M16.4 16h9M16.4 20.6h5.6" fill="none" stroke="#8A8F98" stroke-width="2.2" stroke-linecap="round"/>
6
+ </svg>