node-resource-utils 0.0.0-stage → 1.1.8

package/resources/src/components/appearance/AppearanceDrawer.tsx

@@ -0,0 +1,268 @@
+'use client';
+
+import { Button, Drawer } from 'antd';
+import { CheckOutlined, ReloadOutlined } from '@ant-design/icons';
+import { FONT_SCALES, SKIN_LIST, fontScaleOf, type Skin } from '@/lib/appearance';
+import { MILITARY, fs } from '@/lib/theme';
+import { useAppearance } from './AppearanceProvider';
+
+/**
+ * 外观设置面板。
+ *
+ * 三件事刻意做得不一样：
+ *   1. 皮肤用「缩略图 + 一句话」而不是色块 —— 用户选的是整体观感，
+ *      不是"主色是什么"。缩略图里带侧栏，因为三套皮肤的差别一半在侧栏。
+ *   2. 字号给的是可读的样例，而不是"14 / 15.4 / 16.8"这种数字 ——
+ *      用户只关心看起来舒服不舒服。
+ *   3. 点了立刻生效、立刻存，没有"保存"按钮：这是偏好，不是表单。
+ */
+
+/** 皮肤缩略图：左条侧栏 + 主色块 + 两张卡，用字面色板画（不能用当前皮肤的变量） */
+function SkinPreview({ skin }: { skin: Skin }) {
+  const p = skin.palette;
+  return (
+    <span
+      aria-hidden
+      style={{
+        width: 58,
+        height: 40,
+        flex: '0 0 58px',
+        display: 'flex',
+        overflow: 'hidden',
+        borderRadius: 6,
+        border: `1px solid ${p.border}`,
+        background: p.bg,
+      }}
+    >
+      <span
+        style={{
+          width: 14,
+          flex: '0 0 14px',
+          background: skin.sider.dark
+            ? `linear-gradient(180deg, ${p.primaryDark} 0%, ${p.primaryDeep} 100%)`
+            : p.card,
+          borderRight: `1px solid ${p.border}`,
+          position: 'relative',
+        }}
+      >
+        <span
+          style={{
+            position: 'absolute',
+            left: 3,
+            top: 6,
+            width: 8,
+            height: 3,
+            borderRadius: 1,
+            background: p.primary,
+          }}
+        />
+      </span>
+      <span style={{ flex: 1, minWidth: 0, padding: '5px 5px', display: 'flex', flexDirection: 'column', gap: 3 }}>
+        <span style={{ height: 4, width: '68%', borderRadius: 1, background: p.primary }} />
+        <span style={{ flex: 1, borderRadius: 2, background: p.card, border: `1px solid ${p.borderSoft}` }} />
+        <span style={{ flex: 1, borderRadius: 2, background: p.card, border: `1px solid ${p.borderSoft}` }} />
+      </span>
+    </span>
+  );
+}
+
+function SectionTitle({ title, hint }: { title: string; hint: string }) {
+  return (
+    <div style={{ marginBottom: 10 }}>
+      <div style={{ fontSize: fs(13), fontWeight: 600, color: MILITARY.text }}>{title}</div>
+      <div style={{ fontSize: fs(11.5), color: MILITARY.textMuted, marginTop: 3, lineHeight: 1.6 }}>{hint}</div>
+    </div>
+  );
+}
+
+export default function AppearanceDrawer() {
+  const { open, closePanel, settings, skin, setSkin, setFont, reset } = useAppearance();
+  const scale = fontScaleOf(settings.font);
+
+  return (
+    <Drawer
+      open={open}
+      onClose={closePanel}
+      // antd v6 把 width 收敛进 size（数字照旧按像素），写 width 会在控制台刷废弃告警
+      size={392}
+      placement="right"
+      title={
+        <div style={{ paddingRight: 8 }}>
+          <div style={{ fontSize: fs(10.5), letterSpacing: 3, color: MILITARY.textMuted, fontWeight: 600 }}>
+            APPEARANCE
+          </div>
+          <div style={{ fontSize: fs(16), fontWeight: 700, color: MILITARY.text, marginTop: 2 }}>外观设置</div>
+        </div>
+      }
+      styles={{ body: { padding: '4px 20px 20px' } }}
+    >
+      {/* ------------------------------ 皮肤 ------------------------------ */}
+      <div style={{ marginBottom: 22 }}>
+        <SectionTitle title="皮肤" hint="换的是配色、圆角与侧栏材质；功能、数据、权限都不受影响。" />
+        <div role="radiogroup" aria-label="皮肤" style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+          {SKIN_LIST.map((s) => {
+            const active = s.id === skin.id;
+            return (
+              <div
+                key={s.id}
+                role="radio"
+                aria-checked={active}
+                data-testid={`skin-${s.id}`}
+                tabIndex={0}
+                onClick={() => setSkin(s.id)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    setSkin(s.id);
+                  }
+                }}
+                className="wb-pressable"
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 12,
+                  padding: '10px 12px',
+                  borderRadius: 10,
+                  cursor: 'pointer',
+                  border: `1px solid ${active ? MILITARY.primary : MILITARY.border}`,
+                  background: active ? MILITARY.soft : MILITARY.card,
+                  boxShadow: active ? `inset 0 0 0 1px ${MILITARY.primary}` : 'none',
+                }}
+              >
+                <SkinPreview skin={s} />
+                <div style={{ flex: 1, minWidth: 0 }}>
+                  <div
+                    style={{
+                      fontSize: fs(13.5),
+                      fontWeight: 600,
+                      color: active ? MILITARY.primary : MILITARY.text,
+                    }}
+                  >
+                    {s.name}
+                  </div>
+                  <div
+                    style={{
+                      fontSize: fs(11.5),
+                      color: MILITARY.textMuted,
+                      marginTop: 2,
+                      overflow: 'hidden',
+                      textOverflow: 'ellipsis',
+                      whiteSpace: 'nowrap',
+                    }}
+                  >
+                    {s.blurb}
+                  </div>
+                </div>
+                <span
+                  style={{
+                    width: 18,
+                    height: 18,
+                    flex: '0 0 18px',
+                    borderRadius: 999,
+                    display: 'grid',
+                    placeItems: 'center',
+                    fontSize: fs(10),
+                    color: MILITARY.onPrimary,
+                    background: active ? MILITARY.primary : 'transparent',
+                    border: `1px solid ${active ? MILITARY.primary : MILITARY.border}`,
+                    opacity: active ? 1 : 0.7,
+                  }}
+                >
+                  {active ? <CheckOutlined /> : null}
+                </span>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* ---------------------------- 字体大小 ---------------------------- */}
+      <div>
+        <SectionTitle title="字体大小" hint="只放大文字，不改页面结构；表格、表单、菜单一起跟着变。" />
+        <div
+          style={{
+            display: 'grid',
+            gridTemplateColumns: `repeat(${FONT_SCALES.length}, 1fr)`,
+            gap: 6,
+            padding: 4,
+            borderRadius: 10,
+            background: MILITARY.soft,
+            border: `1px solid ${MILITARY.borderSoft}`,
+          }}
+          role="radiogroup"
+          aria-label="字体大小"
+        >
+          {FONT_SCALES.map((f) => {
+            const active = f.id === settings.font;
+            return (
+              <button
+                key={f.id}
+                type="button"
+                role="radio"
+                aria-checked={active}
+                data-testid={`font-${f.id}`}
+                onClick={() => setFont(f.id)}
+                style={{
+                  appearance: 'none',
+                  border: 'none',
+                  cursor: 'pointer',
+                  padding: '7px 0',
+                  borderRadius: 7,
+                  fontSize: fs(12.5),
+                  fontWeight: active ? 600 : 400,
+                  color: active ? MILITARY.onPrimary : MILITARY.textSecondary,
+                  background: active ? MILITARY.primary : 'transparent',
+                  transition: 'background-color .18s, color .18s',
+                }}
+              >
+                {f.name}
+              </button>
+            );
+          })}
+        </div>
+
+        {/* 样例：直接吃当前的 --wb-fs，用户拖之前就知道有多大 */}
+        <div
+          style={{
+            marginTop: 12,
+            padding: '14px 16px',
+            borderRadius: 10,
+            background: MILITARY.paper,
+            border: `1px dashed ${MILITARY.border}`,
+          }}
+        >
+          <div style={{ fontSize: fs(15), fontWeight: 600, color: MILITARY.text }}>设备巡检记录</div>
+          <div style={{ fontSize: fs(13), color: MILITARY.textSecondary, marginTop: 6, lineHeight: 1.7 }}>
+            正文与表格内容 · 现在这一档是 ×{scale}
+          </div>
+          <div
+            data-testid="font-sample"
+            style={{ fontSize: fs(11.5), color: MILITARY.textMuted, marginTop: 4 }}
+          >
+            辅助说明与时间戳
+          </div>
+        </div>
+      </div>
+
+      {/* ---------------------------- 底部 ---------------------------- */}
+      <div
+        style={{
+          marginTop: 22,
+          paddingTop: 14,
+          borderTop: `1px solid ${MILITARY.borderSoft}`,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          gap: 12,
+        }}
+      >
+        <div style={{ fontSize: fs(11), color: MILITARY.textMuted, lineHeight: 1.6 }}>
+          设置保存在这台设备的浏览器里，换设备不跟随。
+        </div>
+        <Button size="small" icon={<ReloadOutlined />} onClick={reset}>
+          恢复默认
+        </Button>
+      </div>
+    </Drawer>
+  );
+}

package/resources/src/components/appearance/AppearanceProvider.tsx

@@ -0,0 +1,160 @@
+'use client';
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from 'react';
+import {
+  APPEARANCE_KEY,
+  DEFAULT_APPEARANCE,
+  SKINS,
+  applyAppearance,
+  readAppearance,
+  saveAppearance,
+  type AppearanceSettings,
+  type FontId,
+  type Skin,
+  type SkinId,
+} from '@/lib/appearance';
+
+/**
+ * 外观状态（皮肤 + 字号）。
+ *
+ * 为什么用一个模块级 store 而不是普通 useState：
+ *   首屏 HTML 是按默认外观（原版）直出的，用户本机存的可能是炫酷/大字。
+ *   `useSyncExternalStore` 允许"服务端快照 = 默认、客户端快照 = 本机设置"，
+ *   React 会在水合完成后自己切到真值，不会报 hydration mismatch。
+ *   而 CSS 变量早就被 <head> 里的启动脚本设好了，所以看不到闪白。
+ *
+ * 作用域是**整站**（挂在根 Providers 上），登录页也带外观；
+ * 但设置存在浏览器 localStorage 里 —— 换设备不跟随，这是外观偏好，
+ * 不该占用账号数据（多人共用一台机器的考场尤其如此）。
+ */
+
+type Listener = () => void;
+
+let snapshot: AppearanceSettings | null = null;
+const listeners = new Set<Listener>();
+
+/** 缓存引用：useSyncExternalStore 要求未变化时返回同一个对象 */
+function getSnapshot(): AppearanceSettings {
+  if (!snapshot) snapshot = readAppearance();
+  return snapshot;
+}
+
+function getServerSnapshot(): AppearanceSettings {
+  return DEFAULT_APPEARANCE;
+}
+
+function subscribe(cb: Listener): () => void {
+  listeners.add(cb);
+  // 同一浏览器的其他标签页改了外观 → 这里跟着变，避免两个页面观感不一致
+  const onStorage = (e: StorageEvent) => {
+    if (e.key && e.key !== APPEARANCE_KEY) return;
+    snapshot = readAppearance();
+    applyAppearance(snapshot);
+    cb();
+  };
+  window.addEventListener('storage', onStorage);
+  return () => {
+    listeners.delete(cb);
+    window.removeEventListener('storage', onStorage);
+  };
+}
+
+function commit(next: AppearanceSettings) {
+  snapshot = next;
+  saveAppearance(next);
+  applyAppearance(next);
+  listeners.forEach((l) => l());
+}
+
+export interface AppearanceApi {
+  settings: AppearanceSettings;
+  /** 当前皮肤定义（字面色板、材质都在里面） */
+  skin: Skin;
+  /** 面板开关 */
+  open: boolean;
+  openPanel: () => void;
+  closePanel: () => void;
+  setSkin: (id: SkinId) => void;
+  setFont: (id: FontId) => void;
+  reset: () => void;
+}
+
+const Ctx = createContext<AppearanceApi | null>(null);
+
+export function AppearanceProvider({ children }: { children: ReactNode }) {
+  const settings = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const [open, setOpen] = useState(false);
+
+  /**
+   * 首次挂载再对齐一次：`<head>` 里的启动脚本可能被严格模式/隐私策略拦掉，
+   * 这里兜一层，保证 <html data-wb-skin> 一定等于真实设置。
+   */
+  const mounted = useRef(false);
+  useEffect(() => {
+    applyAppearance(settings);
+    if (!mounted.current) {
+      mounted.current = true;
+      return;
+    }
+    // 切换瞬间给一个 0.18s 的颜色过渡，别让整页"啪"地换掉
+    const el = document.documentElement;
+    el.classList.add('wb-skin-anim');
+    const timer = window.setTimeout(() => el.classList.remove('wb-skin-anim'), 240);
+    return () => {
+      window.clearTimeout(timer);
+      el.classList.remove('wb-skin-anim');
+    };
+  }, [settings]);
+
+  const api = useMemo<AppearanceApi>(
+    () => ({
+      settings,
+      skin: SKINS[settings.skin] ?? SKINS.classic,
+      open,
+      openPanel: () => setOpen(true),
+      closePanel: () => setOpen(false),
+      setSkin: (id) => commit({ ...settings, skin: id }),
+      setFont: (id) => commit({ ...settings, font: id }),
+      reset: () => commit({ ...DEFAULT_APPEARANCE }),
+    }),
+    [settings, open]
+  );
+
+  return <Ctx.Provider value={api}>{children}</Ctx.Provider>;
+}
+
+/** 取外观状态。必须在 AppearanceProvider 内部调用（Providers 已包好，页面直接用） */
+export function useAppearance(): AppearanceApi {
+  const v = useContext(Ctx);
+  if (!v) {
+    throw new Error('useAppearance 必须在 <AppearanceProvider> 内使用（根 Providers 已包）');
+  }
+  return v;
+}
+
+/**
+ * 图表调色板：跟随当前皮肤。
+ *
+ * ECharts / canvas 不认 CSS 变量，必须拿字面 hex —— 所以这里返回
+ * `SKINS[skin].palette.chart`，皮肤一换，图表重渲染就是新颜色。
+ * 普通 DOM 元素不要用它，直接用 MILITARY.xxx（那是 var()，会自己变）。
+ */
+export function useChartPalette(): string[] {
+  const { skin } = useAppearance();
+  return skin.palette.chart;
+}
+
+/** 画布 / 内联 HTML 需要真实色值时用（边缘、标签、tooltip 文案着色） */
+export function useSkinInk() {
+  const { skin } = useAppearance();
+  return skin.palette;
+}

package/resources/src/components/docs/DocArticle.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import Link from 'next/link';
+import {
+  ArrowLeftOutlined,
+  ArrowRightOutlined,
+  ClockCircleOutlined,
+  EditOutlined,
+} from '@ant-design/icons';
+import Markdown from '@/components/Markdown';
+import { docHref, type DocNavPage, type DocRecord } from '@/lib/docs-shared';
+import DocToc, { ReadingProgress } from './DocToc';
+
+/** 单篇文档：面包屑 + 标题区 + 正文 + 右侧目录 + 上下篇 */
+export default function DocArticle({
+  doc,
+  prev,
+  next,
+}: {
+  doc: DocRecord;
+  prev: DocNavPage | null;
+  next: DocNavPage | null;
+}) {
+  return (
+    <>
+      <ReadingProgress />
+
+      <div className="wb-docs-article-layout">
+        <article className="wb-docs-article">
+          <nav className="wb-docs-breadcrumb" aria-label="面包屑">
+            <Link href="/docs">帮助中心</Link>
+            {doc.groupTrail.map((group) => (
+              <span key={group}>
+                <span className="wb-docs-breadcrumb-sep">/</span>
+                {group}
+              </span>
+            ))}
+            <span className="wb-docs-breadcrumb-sep">/</span>
+            <span className="wb-docs-breadcrumb-current">{doc.title}</span>
+          </nav>
+
+          <header className="wb-docs-page-head">
+            <h1 className="wb-docs-page-title">{doc.title}</h1>
+            {doc.description && <p className="wb-docs-page-desc">{doc.description}</p>}
+
+            <div className="wb-docs-page-meta">
+              <span className="wb-docs-page-meta-item">
+                <ClockCircleOutlined /> 约 {doc.readingMinutes} 分钟
+              </span>
+              {doc.updated && (
+                <span className="wb-docs-page-meta-item">
+                  <EditOutlined /> 更新于 {doc.updated}
+                </span>
+              )}
+              {doc.tags.map((tag) => (
+                <span key={tag} className="wb-docs-tag">
+                  {tag}
+                </span>
+              ))}
+            </div>
+          </header>
+
+          <div className="wb-docs-prose">
+            <Markdown text={doc.body} anchors internalLinks copyable />
+          </div>
+
+          {(prev || next) && (
+            <nav className="wb-docs-pager" aria-label="上一篇 / 下一篇">
+              {prev ? (
+                <Link href={docHref(prev.slug)} className="wb-docs-pager-card is-prev">
+                  <span className="wb-docs-pager-label">
+                    <ArrowLeftOutlined /> 上一篇
+                  </span>
+                  <span className="wb-docs-pager-title">{prev.title}</span>
+                </Link>
+              ) : (
+                <span className="wb-docs-pager-card is-empty" />
+              )}
+
+              {next ? (
+                <Link href={docHref(next.slug)} className="wb-docs-pager-card is-next">
+                  <span className="wb-docs-pager-label">
+                    下一篇 <ArrowRightOutlined />
+                  </span>
+                  <span className="wb-docs-pager-title">{next.title}</span>
+                </Link>
+              ) : (
+                <span className="wb-docs-pager-card is-empty" />
+              )}
+            </nav>
+          )}
+
+          <footer className="wb-docs-article-foot">
+            <span>本文档由系统内置帮助中心维护，会随功能更新同步调整。</span>
+            <span>
+              发现内容有误？
+              <Link href="/feedback"> 前往问题反馈</Link>
+            </span>
+          </footer>
+        </article>
+
+        <DocToc items={doc.toc} />
+      </div>
+    </>
+  );
+}

package/resources/src/components/docs/DocToc.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { DocTocItem } from '@/lib/docs-shared';
+
+/**
+ * 右侧「本页目录」。
+ *
+ * 用滚动位置而不是 IntersectionObserver 决定当前小节：
+ * 正文里有长代码块、表格时，IntersectionObserver 的回调节流会让高亮
+ * 明显滞后；直接算「最后一个越过阅读线的标题」更跟手，逻辑也更好懂。
+ */
+export default function DocToc({ items }: { items: DocTocItem[] }) {
+  const [active, setActive] = useState(items[0]?.id ?? '');
+
+  useEffect(() => {
+    if (!items.length) return;
+
+    let frame = 0;
+    const measure = () => {
+      frame = 0;
+      let current = items[0]?.id ?? '';
+      for (const item of items) {
+        const el = document.getElementById(item.id);
+        if (!el) continue;
+        if (el.getBoundingClientRect().top <= 96) current = item.id;
+        else break;
+      }
+      setActive(current);
+    };
+
+    const onScroll = () => {
+      if (frame) return;
+      frame = window.requestAnimationFrame(measure);
+    };
+
+    measure();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', onScroll);
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', onScroll);
+      if (frame) window.cancelAnimationFrame(frame);
+    };
+  }, [items]);
+
+  if (!items.length) return null;
+
+  return (
+    <aside className="wb-docs-toc" aria-label="本页目录">
+      <div className="wb-docs-toc-title">本页目录</div>
+      <div className="wb-docs-toc-list">
+        {items.map((item) => (
+          <a
+            key={item.id}
+            href={`#${item.id}`}
+            onClick={() => setActive(item.id)}
+            className={`wb-docs-toc-link level-${item.level} ${active === item.id ? 'is-active' : ''}`}
+          >
+            {item.text}
+          </a>
+        ))}
+      </div>
+    </aside>
+  );
+}
+
+/** 顶部阅读进度条：长文档滚到哪一目了然 */
+export function ReadingProgress() {
+  const [progress, setProgress] = useState(0);
+
+  useEffect(() => {
+    let frame = 0;
+    const measure = () => {
+      frame = 0;
+      const doc = document.documentElement;
+      const max = doc.scrollHeight - doc.clientHeight;
+      setProgress(max > 0 ? Math.min(1, Math.max(0, doc.scrollTop / max)) : 0);
+    };
+    const onScroll = () => {
+      if (frame) return;
+      frame = window.requestAnimationFrame(measure);
+    };
+
+    measure();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', onScroll);
+    return () => {
+      window.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', onScroll);
+      if (frame) window.cancelAnimationFrame(frame);
+    };
+  }, []);
+
+  return (
+    <div className="wb-docs-progress" aria-hidden="true">
+      <span style={{ width: `${progress * 100}%` }} />
+    </div>
+  );
+}