nx-sk 0.9.2 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 本文件格式参考 [Keep a Changelog](https://keepachangelog.com/)，中文正文。
 
+## [0.10.0] - 2026-10-15
+
+### Added
+
+- **「栏目管理」重做成容器 + 拖拽**（设置页）。整页只有一个心智模型：一个栏目要么在「平铺」里、要么在某个分组里、要么在「隐藏」里；拖，就是把它从一个容器挪到另一个。
+  - **「隐藏」不再是一个开关，就是一个容器**：与分组同构，拖进去即不进头部（`#/栏目` 直达仍可用）——「显隐」与「归组」因此是同一套操作，不用记两种交互。
+  - **拖拽实时预览**：拖动过程中列表就按落点重排（被拖的行半透明停在新位置），松手直接提交这个顺序——所见即所得，不再「先松手再猜落在哪」。
+  - **平铺区也能拖排序**：新增 `settings.navOrder`（栏目 id 数组）——显式排过的按它排，没排过的新栏目按栏目自身 `order` 跟在后面，所以「从没拖过」= 老行为不变。
+  - 行内只留一个「移出」逃逸按钮（上一版的 上移/下移/显示中/隐藏中 全部去掉）；分组把手可拖，换分组之间顺序。
+  - 设置页改为**一次保存**：标量设置与导航配置一起存，顶部只出现一次「有未保存的改动 / 保存 / 放弃改动」。
+
+- **`settings.navHidden` / `settings.navOrder` 的后端校验**：与分组同构的「栏目 id 清单」校验（栏目必须真实存在、去重保序）；CLI 三种写法都认：`--set navOrder=["a","b"]` / `navOrder=a,b` / `navHidden=a`。`setting get` 人类模式现在能一次看全「栏目 + 隐藏状态 + 平铺顺序 + 分组」。
+
+### Fixed
+
+- **拖拽预览抖动**：两个自己推自己造成的——① 行内 `dragover` 冒泡到容器后会被当成「拖到空白处」翻成「追加到末尾」，指针压在被拖的行上时两种判断来回切；② 落点取自「预览后」的行号，预览一重排索引就变。现在行内就地拦下（`preventDefault` + `stopPropagation`，悬停在自己身上时保持落点不重算）、插入位取自原始配置（+ 指针在上半/下半决定前后）、值没变就不 setState。实测：停在落点边界采样 8 次顺序不变，慢速扫过整列只单调变化 4 次。
+- **分组下拉鼠标下滑就消失**：pill 与菜单之间那 4px 空隙被判成「离开」——补透明桥 + 离开延迟 140ms。
+
 ## [0.9.2] - 2026-10-15
 
 ### Added

package/README.md

@@ -198,8 +198,10 @@ nx-sk file get $FID                             # 反查「被引用：求职 /
 > 若你的求职栏目是很早建的，跑一次 `nx-sk section sync job`（或面板「栏目 → 编辑 → 同步模板字段」）
 > 就能把模板新增的「附件资料」组与 4 个 `file` 字段补进来，且不改动你已有的字段与数据。
 
-**头部导航分组**（栏目多了以后收拢头部，一眼分得出主次）：在设置里把同域栏目归成一组，
-头部只显示组名，**悬浮展开上下列表**选具体栏目；不归组的栏目保持平铺。
+**栏目管理**（设置页）：栏目多了以后收拢头部，一眼分得出主次——把同域栏目**拖**成一个分组，
+头部只显示组名、**悬浮展开上下列表**选具体栏目；不常用的栏目拖进「隐藏」容器即不进头部
+（`#/栏目id` 直达仍可用）。整个管理页只有「容器 + 拖拽」一套操作：平铺 / 各分组 / 隐藏，
+拖进拖出就是归组、换位、显隐；改完统一「保存」（一次存全部设置）。
 
 ```bash
 # 面板：设置 → 头部导航分组（勾选栏目 / 组内排序 / 改名 / 增删组），保存后头部立即生效

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nx-sk",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "nx-sk · 本机个人资源管理器（server-cli-web 骨架）：栏目化存储个人信息与大模型密钥，CLI 与 Web 同源，敏感字段密文落盘。",
   "type": "module",
   "bin": {

package/src/modules/settings/navManager.jsx

@@ -0,0 +1,178 @@
+// 栏目管理：**容器 + 拖拽**。整页只有一个心智模型——
+//   一个栏目要么在「平铺」里、要么在某个分组里、要么在「隐藏」里；
+//   拖，就是把它从一个容器挪到另一个。
+//
+// 「隐藏」不再是一个开关，就是一个容器：拖进去 = 不出现在头部（`#/栏目id` 直达仍可用）。
+// 这样「显隐」和「归组」是同一套操作，不用记两种交互。
+//
+// **受控组件**：数据（cfg）与保存都在设置页；这里只管画与调 onChange。
+// 所有数据操作走 navModel 的纯函数（可单测），组件里不做状态体操。
+import { useMemo, useState } from 'react';
+import * as nav from '../../web/frontend/components/navModel.js';
+
+export default function NavManager({ sections, value, onChange }) {
+  const [drag, setDrag] = useState(null); // { kind:'section', sid } | { kind:'group', gi }
+  const [over, setOver] = useState(null); // { key, index }：当前拖到哪个容器的第几位
+
+  // 注意顺序：preview 的依赖里用到 allIds / preview 的计算也用到预览配置，
+  // const 声明晚于使用就是 TDZ 崩（"Cannot access … before initialization"）
+  const allIds = sections.map((s) => s.id);
+  const sectionOf = (id) => sections.find((s) => s.id === id) || null;
+
+  const keyToTarget = (key) => {
+    if (key === 'pool') return { kind: 'pool' };
+    if (key === 'hidden') return { kind: 'hidden' };
+    const gi = Number(String(key).slice(1));
+    return Number.isFinite(gi) ? { kind: 'group', gi } : null;
+  };
+
+  /**
+   * **实时预览**：拖动过程中就把落点算出来渲染，松手前就看到最终顺序（所见即所得）。
+   * 插入位由 nav.insertionIndex 换算（同容器内往下拖要让位）——那条逻辑在模型里，有单测。
+   */
+  const preview = useMemo(() => {
+    if (drag?.kind !== 'section' || !over) return value;
+    const target = keyToTarget(over.key);
+    if (!target) return value;
+    const index = nav.insertionIndex(value, drag.sid, target, over.index, allIds);
+    return nav.moveToContainer(value, drag.sid, target, index, allIds);
+  }, [value, drag, over, allIds]);
+
+  const draggingSid = drag?.kind === 'section' ? drag.sid : null;
+  // 平铺容器的内容与顺序都来自模型：显式排过的（order）优先，其余按栏目自身顺序
+  const pool = nav.ungroupedIds(preview, allIds);
+
+  const endDrag = () => { setDrag(null); setOver(null); };
+
+  /** 松手即提交预览里的顺序（预览就是结果，不再重新算一遍）。 */
+  const commit = () => { if (preview !== value) onChange(preview); endDrag(); };
+
+  // 只在落点**真的变了**才 setState：dragover 每次鼠标移动都触发，
+  // 不做这层去重就是每次移动都重排一遍整页 → 抖
+  const setOverIfChanged = (next) => setOver((o) => (o && o.key === next.key && o.index === next.index ? o : next));
+
+  // 容器外壳：接住「拖到空白处 = 追加到末尾」，并显示落点高亮
+  const zone = (key, base = '') => ({
+    className: `${base} ${over?.key === key ? 'drop-target' : ''}`,
+    onDragOver: (e) => { if (draggingSid) { e.preventDefault(); setOverIfChanged({ key, index: null }); } },
+    onDragLeave: () => setOver((o) => (o?.key === key && o.index === null ? null : o)),
+    onDrop: (e) => { e.preventDefault(); commit(); },
+  });
+
+  /**
+   * 行的落点判定。两条防抖铁律：
+   *   ① 行内事件**就地拦下**（preventDefault + stopPropagation）：一旦冒泡到容器，
+   *      容器会把它当成「拖到空白处」翻成「追加到末尾」——指针正好压在被拖的行上时，
+   *      两个判断来回切，页面就抖。
+   *   ② 插入位取自**原始配置**里的位置（不随预览漂移）+ 指针在上半/下半决定前后。
+   *      若反过来用「预览后的行号」，预览一重排索引就变，等于自己推自己。
+   */
+  const rowProps = (key, sid) => ({
+    onDragOver: (e) => {
+      if (!draggingSid) return;
+      e.preventDefault();
+      e.stopPropagation();
+      if (draggingSid === sid) return; // 悬停在自己身上：保持当前落点，不重算
+      const rect = e.currentTarget.getBoundingClientRect();
+      const below = e.clientY > rect.top + rect.height / 2;
+      const at = nav.containerOf(value, sid, allIds);
+      const index = (typeof at.index === 'number' ? at.index : 0) + (below ? 1 : 0);
+      setOverIfChanged({ key, index });
+    },
+    onDrop: (e) => { e.preventDefault(); e.stopPropagation(); commit(); },
+    onDragStart: () => setDrag({ kind: 'section', sid }),
+  });
+
+  return (
+    <div className="stack">
+      {/* ① 平铺：不进任何容器的栏目（= 头部平铺显示） */}
+      <section {...zone('pool', 'nav-pool')}>
+        <div className="hint">平铺：不进分组也不隐藏的栏目，直接显示在头部（拖到这里 = 移出分组 / 取消隐藏）</div>
+        {pool.length ? (
+          <div className="nav-list">
+            {pool.map((sid) => (
+              <SectionRow key={sid} section={sectionOf(sid)} sid={sid}
+                dragging={draggingSid === sid}
+                {...rowProps('pool', sid)}
+                onDragEnd={endDrag}
+                actions={null} />
+            ))}
+          </div>
+        ) : <div className="muted">没有平铺的栏目。</div>}
+      </section>
+
+      {/* ② 分组：组名可改、组间可拖把手换位 */}
+      {preview.groups.map((g, gi) => (
+        <section key={gi} {...zone(`g${gi}`, 'card nav-group')}>
+          <div
+            className={`colhead ${over?.key === `g${gi}` && over.group ? 'drop-target' : ''}`}
+            onDragOver={(e) => { if (drag?.kind === 'group') { e.preventDefault(); setOver({ key: `g${gi}`, group: true }); } }}
+            onDrop={(e) => {
+              e.preventDefault();
+              if (drag?.kind === 'group' && drag.gi !== gi) onChange(nav.moveGroup(value, drag.gi, gi - drag.gi));
+              endDrag();
+            }}
+          >
+            <span className="grip" title="拖动调整分组顺序" draggable
+              onDragStart={() => setDrag({ kind: 'group', gi })} onDragEnd={endDrag} />
+            <input className="nav-title" placeholder="组名，如「求职」" value={g.title}
+              onChange={(e) => onChange(nav.renameGroup(value, gi, e.target.value))} />
+            <span className="muted">{g.sections.length} 个栏目</span>
+            <span className="right rowgap">
+              <button className="btn small ghost" onClick={() => onChange(nav.removeGroup(value, gi))}>删除组</button>
+            </span>
+          </div>
+          {g.sections.length ? (
+            <div className="nav-list">
+              {g.sections.map((sid) => (
+                <SectionRow key={sid} section={sectionOf(sid)} sid={sid}
+                  dragging={draggingSid === sid}
+                  {...rowProps(`g${gi}`, sid)}
+                  onDragEnd={endDrag}
+                  actions={<button className="btn small ghost" onClick={() => onChange(nav.ungroupSection(value, sid))}>移出</button>} />
+              ))}
+            </div>
+          ) : <div className="row"><span className="desc">空分组——把栏目拖进来。</span></div>}
+        </section>
+      ))}
+
+      {/* ③ 隐藏：与分组同构的容器——拖进去即「不进头部」 */}
+      <section {...zone('hidden', 'card nav-group nav-hidden')}>
+        <div className="colhead">
+          隐藏
+          <span className="muted">{preview.hidden.length} 个栏目</span>
+          <span className="right muted">不进头部 · #/栏目id 直达仍可用</span>
+        </div>
+        {preview.hidden.length ? (
+          <div className="nav-list">
+            {preview.hidden.map((sid) => (
+              <SectionRow key={sid} section={sectionOf(sid)} sid={sid}
+                dragging={draggingSid === sid}
+                {...rowProps('hidden', sid)}
+                onDragEnd={endDrag}
+                actions={<button className="btn small ghost" onClick={() => onChange(nav.ungroupSection(value, sid))}>移出</button>} />
+            ))}
+          </div>
+        ) : <div className="row"><span className="desc">没有隐藏的栏目——把不常用的拖进来。</span></div>}
+      </section>
+
+      <div className="rowgap">
+        <button className="btn" onClick={() => onChange(nav.addGroup(value))}>新增分组</button>
+        <span className="hint">组顺序 = 头部显示顺序；组内顺序 = 展开列表里的顺序</span>
+      </div>
+    </div>
+  );
+}
+
+/** 一行栏目：把手（拖）+ 名称 + 计数 + 容器自己的动作（移出 / 无）。 */
+function SectionRow({ section, sid, dragging, actions, onDragStart, onDragEnd, onDragOver, onDrop }) {
+  return (
+    <div className={`row nav-row ${dragging ? 'dragging' : ''}`} onDragOver={onDragOver} onDrop={onDrop}>
+      <span className="grip" title="拖动：换位 / 换容器" draggable onDragStart={onDragStart} onDragEnd={onDragEnd} />
+      <span className="name">{section ? section.title : `栏目已删除（${sid}）`}</span>
+      <span className="desc">{section ? `${section.entries} 条` : '保存前请移出'}</span>
+      <span className="acts">{actions}</span>
+    </div>
+  );
+}
+

package/src/modules/settings/service.js

@@ -4,14 +4,16 @@ import { loadStore, mutateStore, snapshotStore } from '../../core/store.js';
 import { findSection } from '../../core/fields.js';
 import { badInput, notFound } from '../../core/errors.js';
 
-export const SETTING_KEYS = ['exportDir', 'exportFormat', 'includeSecretsInExport', 'defaultSection', 'navGroups'];
+export const SETTING_KEYS = ['exportDir', 'exportFormat', 'includeSecretsInExport', 'defaultSection', 'navGroups', 'navHidden', 'navOrder'];
 
 const SCHEMA = {
   exportDir: { type: 'string', hint: '导出目录，留空 = ~/nx-sk/export' },
   exportFormat: { type: 'string', enum: ['json', 'md', 'both'], hint: '整体导出默认格式' },
   includeSecretsInExport: { type: 'boolean', hint: '整体导出是否默认带密钥明文（默认否）' },
   defaultSection: { type: 'string', hint: '默认栏目 id' },
-  navGroups: { type: 'json', hint: '头部导航分组：[{title, sections:[栏目id…]}]，数组顺序 = 显示顺序' },
+  navGroups: { type: 'json', hint: '头部导航分组：[{title, sections:[栏目id…]}]，数组顺序 = 显示顺序', coerce: coerceNavGroups },
+  navHidden: { type: 'json', hint: '头部隐藏的栏目 id（入口不显示，`#/栏目` 直达仍可用）', coerce: coerceNavHidden },
+  navOrder: { type: 'json', hint: '平铺区的显示顺序（栏目 id 数组；没列进去的按栏目自身顺序跟在后面）', coerce: coerceNavOrder },
 };
 
 export function settingsSchema() {
@@ -20,7 +22,16 @@ export function settingsSchema() {
 
 export async function getSettings() {
   const store = await loadStore();
-  return { settings: store.settings, schema: settingsSchema() };
+  return {
+    settings: store.settings,
+    // 栏目清单随设置一起给：面板的「栏目管理」按它渲染，CLI 也能一次看全
+    sections: store.sections.map((s) => ({
+      id: s.id,
+      title: s.title,
+      entries: store.entries.filter((e) => e.section === s.id).length,
+    })),
+    schema: settingsSchema(),
+  };
 }
 
 /**
@@ -67,10 +78,49 @@ function coerceNavGroups(value, store) {
   });
 }
 
+/**
+ * 「栏目 id 清单」校验（隐藏清单 / 平铺顺序共用）：每一项都必须是真实存在的栏目；
+ * 去重保序，并归一成真实 id（写标题也认）。label 只影响报错措辞。
+ */
+function coerceSectionIdList(value, store, label) {
+  // 三种写法都吃：数组（面板）、`a,b`（CLI 省事写法）、`["a","b"]`（CLI 的 JSON 写法）
+  let raw = value;
+  if (typeof raw === 'string') {
+    const s = raw.trim();
+    if (s.startsWith('[')) {
+      try {
+        raw = JSON.parse(s);
+      } catch (e) {
+        throw badInput(`${label}需要 JSON 数组或逗号分隔：${e.message}`);
+      }
+    }
+  }
+  const list = Array.isArray(raw) ? raw : String(raw ?? '').split(',');
+  const out = [];
+  for (const item of list) {
+    const ref = String(item ?? '').trim();
+    if (!ref) continue;
+    const sec = findSection(store, ref);
+    if (!sec) throw badInput(`${label}里的栏目不存在: ${ref}`);
+    if (!out.includes(sec.id)) out.push(sec.id);
+  }
+  return out;
+}
+
+// 用**函数声明**（会提升）：SCHEMA 在模块顶层就引用了它们，const 箭头函数会踩 TDZ
+function coerceNavHidden(value, store) {
+  return coerceSectionIdList(value, store, '隐藏清单');
+}
+
+function coerceNavOrder(value, store) {
+  return coerceSectionIdList(value, store, '平铺顺序');
+}
+
 function coerceSetting(key, value, store) {
   const s = SCHEMA[key];
   if (!s) throw notFound(`未知设置项: ${key}（可用: ${SETTING_KEYS.join(', ')}）`);
-  if (s.type === 'json') return coerceNavGroups(value, store);
+  // 结构化设置项（导航分组 / 隐藏）自带校验器；标量项走下面这套
+  if (s.coerce) return s.coerce(value, store);
   if (s.type === 'boolean') {
     if (typeof value === 'boolean') return value;
     const v = String(value).trim().toLowerCase();
@@ -109,16 +159,36 @@ export async function updateSettings({ set, key, value, 'dry-run': dryRun } = {}
 }
 
 export function renderSettings(data) {
-  const lines = ['当前设置（改：nx-sk setting set --key <名> --value <值>）'];
+  const lines = ['当前设置（改：nx-sk setting set --set k=v）'];
   for (const s of data.schema) {
+    if (s.coerce) continue; // 结构化项（导航分组 / 隐藏）单独可读地列在下面
     const v = data.settings[s.key];
     const shown = s.type === 'boolean' ? (v ? '是' : '否')
-      : (v === '' || v === undefined ? '（空）'
-        : (v && typeof v === 'object'
-          ? (() => { const j = JSON.stringify(v); return j.length > 56 ? `${j.slice(0, 56)}…` : j; })()
-          : String(v)));
+      : (v === '' || v === undefined ? '（空）' : String(v));
     lines.push(`  ${s.key.padEnd(22)} ${shown.padEnd(10)} ${s.hint}`);
   }
+
+  const settings = data.settings || {};
+  const hidden = new Set(settings.navHidden || []);
+  if (data.sections?.length) {
+    lines.push('', `栏目（${data.sections.length}）· 隐藏 ${hidden.size} 个`);
+    for (const s of data.sections) {
+      lines.push(`  ${String(s.id).padEnd(18)} ${String(s.title).padEnd(14)} ${hidden.has(s.id) ? '隐藏' : '显示'}`);
+    }
+  }
+
+  const order = settings.navOrder || [];
+  if (data.sections?.length) {
+    const ranked = order.filter((id) => data.sections.some((s) => s.id === id));
+    if (ranked.length) lines.push(`平铺顺序（前 ${ranked.length} 个已显式排序）: ${ranked.join(' → ')}`);
+  }
+
+  const groups = settings.navGroups || [];
+  lines.push('', groups.length
+    ? `分组（${groups.length}）· 组顺序 = 头部顺序，组内顺序 = 展开列表顺序`
+    : '分组：无（全部栏目平铺在头部）');
+  for (const g of groups) lines.push(`  ${g.title}: ${g.sections.join(' → ')}`);
+  lines.push('', '例：nx-sk setting set --set \'navGroups=[{"title":"求职","sections":["projects"]}]\' --dry-run');
   return lines.join('\n');
 }