node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/components/feedback/motion.css

@@ -0,0 +1,204 @@
+/* ---------------------------------------------------------------
+   操作反馈层（区别于「等待反馈」）
+   归属 components/feedback，由 app/globals.css 统一 @import 进来。
+
+   这一层只回答一个问题：**我这一下，系统收到了吗？**
+   等待反馈回答的是「系统还在忙吗」，两者不要混着做。
+
+   三条约束（改之前先读）：
+     1. 只动 transform / opacity / box-shadow / 背景色 —— 不触发重排
+     2. 时长只用下面四个变量，位移 ≤2px，缩放 ≤0.02
+     3. 所有规则都要在 prefers-reduced-motion 下有静默版本
+
+   ★ 调力度只改 :root 里的变量，不要改下面的规则。
+     新题想更"稳"一点：把 --wb-dur 调到 0.24s、--wb-lift 保持 -1px。
+     动效超过 0.24s 就开始像"系统在表演"，别加。
+   --------------------------------------------------------------- */
+
+:root {
+  /* 手感：按下最快，悬停居中；这两个是"瞬时反应"，不能用慢曲线 */
+  --wb-dur-fast: 0.08s;
+  --wb-dur: 0.18s;
+  --wb-dur-slow: 0.24s;
+
+  /* 结果落地：一行闪完的总时长。0.5s 是"看见但不打断"的平衡点 */
+  --wb-flash-dur: 0.5s;
+
+  --wb-ease: cubic-bezier(0.4, 0, 0.2, 1);
+  --wb-lift: -1px;
+  --wb-shrink: 0.995;
+
+  /* 阴影 / 描边 / 悬停底色不在这里定死：外观设置换皮肤时要跟着变，
+     所以它们由 lib/appearance.ts 的 motion 字段生成，见 globals.css。
+     这里只保留"手感"常量（时长、位移、曲线）。 */
+}
+
+/* ① 可点击卡片：悬停抬起 1px，按下回落到 0 并轻微内缩
+   ---------------------------------------------------------------
+   这个类**只在真能点的时候加**。
+   由 PressableCard 自动判断（有 href / onClick 才加），
+   手写 div 的时候自己负责 —— 不能点的卡加了，比完全不动更像 bug。
+   --------------------------------------------------------------- */
+
+/* 基础态写在最前面：后面的 :hover / :active 才能盖住它 */
+.ant-card.wb-pressable {
+  position: relative;
+  border-color: var(--wb-border-idle);
+  box-shadow: 0 1px 2px var(--wb-shade-idle);
+}
+
+.wb-pressable {
+  transition:
+    transform var(--wb-dur) var(--wb-ease),
+    box-shadow var(--wb-dur) var(--wb-ease),
+    border-color var(--wb-dur) var(--wb-ease),
+    background-color var(--wb-dur) var(--wb-ease);
+}
+
+.wb-pressable:hover {
+  transform: translateY(var(--wb-lift));
+  box-shadow: 0 4px 12px var(--wb-shade-hover);
+  border-color: var(--wb-border-hover);
+}
+
+/* 卡片底色也提一点点暖白：抬起 + 变亮，比只加阴影更像"浮起来" */
+.ant-card.wb-pressable:hover {
+  background-color: var(--wb-surface-hover);
+}
+
+/* 按下用更短的时长：按下去要"利落"，回弹才从容 */
+.wb-pressable:active {
+  transform: translateY(0) scale(var(--wb-shrink));
+  box-shadow: 0 1px 3px var(--wb-shade-press);
+  transition-duration: var(--wb-dur-fast);
+}
+
+/* 键盘用户也得看得见焦点，不能只有鼠标有反馈 */
+.wb-pressable:focus-visible {
+  outline: 2px solid var(--wb-primary);
+  outline-offset: 2px;
+}
+
+/* 可点击卡片右上角的「›」提示：悬停时淡入并右移 1px。
+   它的作用是提前告诉用户"这张卡能点"，而不是点完才知道。 */
+.wb-pressable__cue {
+  position: absolute;
+  top: 12px;
+  right: 13px;
+  font-size: 13px;
+  line-height: 1;
+  color: var(--wb-text-3);
+  opacity: 0;
+  transform: translateX(-3px);
+  transition:
+    opacity var(--wb-dur) ease,
+    transform var(--wb-dur) ease,
+    color var(--wb-dur) ease;
+  pointer-events: none;
+}
+
+.wb-pressable:hover .wb-pressable__cue,
+.wb-pressable:focus-visible .wb-pressable__cue {
+  opacity: 1;
+  transform: translateX(0);
+  color: var(--wb-primary);
+}
+
+/* ② 结果落地：目标行 / 卡片闪一层卡其色再褪回去
+   ---------------------------------------------------------------
+   toast 说的是「操作成功了」，这一下说的是「成功在这个位置」。
+   改完一条记录找不到它在哪一行，是最常见的困惑。
+   --------------------------------------------------------------- */
+
+@keyframes wb-flash-bg {
+  0% {
+    background-color: transparent;
+  }
+  20% {
+    background-color: var(--wb-flash);
+  }
+  100% {
+    background-color: transparent;
+  }
+}
+
+/* 表格行：antd 把底色画在 td 上，动画必须打给 td，否则被单元格底色盖住 */
+.wb-flash > td,
+.wb-flash.ant-table-row > td {
+  animation: wb-flash-bg var(--wb-flash-dur) ease-out;
+}
+
+/* 非表格元素（卡片、列表项）直接用 */
+.wb-flash {
+  animation: wb-flash-bg var(--wb-flash-dur) ease-out;
+}
+
+/* 同一行连续触发两次时，类名不变动画不会重播。
+   给个同内容的新动画名，JS 按奇偶切换即可强制重启。 */
+@keyframes wb-flash-bg-alt {
+  0% {
+    background-color: transparent;
+  }
+  20% {
+    background-color: var(--wb-flash);
+  }
+  100% {
+    background-color: transparent;
+  }
+}
+
+.wb-flash-alt > td,
+.wb-flash-alt.ant-table-row > td {
+  animation: wb-flash-bg-alt var(--wb-flash-dur) ease-out;
+}
+
+.wb-flash-alt {
+  animation: wb-flash-bg-alt var(--wb-flash-dur) ease-out;
+}
+
+/* ③ 表格行悬停：左侧浮出一条 3px 卡其定位条
+   ---------------------------------------------------------------
+   和卡片标题的「左侧定位条」是同一套语言，不用新增类，
+   所有走 antd Table 的列表页自动获得。 */
+.ant-table-tbody > tr.ant-table-row > td:first-child {
+  transition: box-shadow var(--wb-dur) ease;
+}
+
+.ant-table-tbody > tr.ant-table-row:hover > td:first-child {
+  box-shadow: inset 3px 0 0 var(--wb-primary);
+}
+
+/* ④ 降级：系统开了「减少动态效果」时，功能一个不能少，只是不动
+   --------------------------------------------------------------- */
+@media (prefers-reduced-motion: reduce) {
+  .wb-pressable,
+  .wb-pressable:hover,
+  .wb-pressable:active {
+    transition: none;
+    transform: none;
+  }
+
+  /* 抬起没了，但"能点"这件事还得靠阴影表达 */
+  .wb-pressable:hover {
+    box-shadow: 0 4px 12px var(--wb-shade-hover);
+  }
+
+  .wb-pressable__cue {
+    transition: none;
+    opacity: 1;
+    transform: none;
+  }
+
+  .wb-flash,
+  .wb-flash > td,
+  .wb-flash.ant-table-row > td,
+  .wb-flash-alt,
+  .wb-flash-alt > td,
+  .wb-flash-alt.ant-table-row > td {
+    animation: none;
+  }
+
+  .ant-table-tbody > tr.ant-table-row > td:first-child {
+    transition: none;
+  }
+}

package/resources/src/components/feedback/motion.ts

@@ -0,0 +1,63 @@
+'use client';
+
+/**
+ * 操作反馈的命令式工具。
+ *
+ * 为什么不全用 className 切换？
+ *   同一个元素连续触发两次时，classList.add 一个已经存在的类不会重播动画。
+ *   要么切奇偶两个动画名，要么强制 reflow —— 这里两样都做了，代价最小。
+ *
+ * 对应的视觉定义在 ./motion.css。
+ */
+
+/**
+ * 与 motion.css 的 `--wb-flash-dur` 必须保持一致。
+ * 改这里就同时改那边，否则类会被提前摘掉、动画被截断。
+ */
+export const FLASH_DURATION_MS = 500;
+
+/** 多留一点余量再摘类：低于动画时长会看到"闪到一半突然没了" */
+const FLASH_CLEANUP_MS = FLASH_DURATION_MS + 40;
+
+function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false;
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/**
+ * 让某个元素闪一下（表格传 `<tr>`，普通元素直接传自己）。
+ *
+ * @param el   目标元素；null 时静默返回，调用方不用判空
+ * @param tick 自增序号，用来在奇偶两个动画名之间切换，保证连续触发也能重播
+ */
+export function flashElement(el: Element | null, tick = 0): void {
+  if (!el || prefersReducedMotion()) return;
+
+  const head = tick % 2 === 0 ? 'wb-flash' : 'wb-flash-alt';
+  const tail = tick % 2 === 0 ? 'wb-flash-alt' : 'wb-flash';
+
+  el.classList.remove(tail);
+  // 读一次布局属性，强制样式失效重算；不这么做，浏览器会把"删了又加"合并成没变
+  void (el as HTMLElement).offsetWidth;
+  el.classList.add(head);
+
+  window.setTimeout(() => el.classList.remove(head), FLASH_CLEANUP_MS);
+}
+
+/**
+ * 按行 key 找表格行并闪一下。
+ *
+ * antd 的 Table 会给每个 `<tr>` 打上 `data-row-key`，这是唯一稳定的定位依据
+ * （行下标会随排序翻页漂移，不能用）。
+ */
+export function flashTableRow(rowKey: string | number, tick = 0): boolean {
+  if (typeof document === 'undefined') return false;
+
+  // 只转义引号和反斜杠就够了：rowKey 是 cuid / 数字，不会是奇怪的 CSS 选择器
+  const safe = String(rowKey).replace(/["\\]/g, '\\$&');
+  const tr = document.querySelector(`tr[data-row-key="${safe}"]`);
+  if (!tr) return false;
+
+  flashElement(tr, tick);
+  return true;
+}

package/resources/src/components/feedback/useCountUp.ts

@@ -0,0 +1,110 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+/**
+ * 数字滚动：让「值变了」被看见，而不是唰地跳过去。
+ *
+ * 看板上的统计卡有个通病：骨架屏一撤，数字直接出现，
+ * 用户分不清「刚加载完」和「本来就是 5」。滚一下，这两个状态就分开了。
+ *
+ * 用法：
+ *   const n = useCountUp(data?.userCount, { enabled: !isLoading });
+ *   <Statistic value={n} />
+ *
+ * ⚠️ 一定要放在**独立的子组件**里调用。
+ *    这个 hook 每帧都会 setState，如果直接写在页面组件里，
+ *    60fps 会把整页重渲染 20 次 —— 5 张卡就是 100 次。
+ */
+
+/** cubic ease-out：起步快、收尾稳，像指针停下来的感觉 */
+const easeOut = (t: number) => 1 - Math.pow(1 - t, 3);
+
+function prefersReducedMotion(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false;
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+export type CountUpOptions = {
+  /**
+   * 动画时长（毫秒），默认 320。
+   * 超过 400 就开始像"系统在表演"，统计数字不值得这么久。
+   */
+  duration?: number;
+  /**
+   * 是否启用动画。数据还在 loading 时传 false，
+   * 等真实值到了再滚 —— 否则会先滚一遍 0，再滚一遍真值。
+   */
+  enabled?: boolean;
+};
+
+/**
+ * @param target 目标值；undefined / null / NaN 一律当 0
+ * @returns 当前应显示的值（整数）
+ */
+export function useCountUp(
+  target: number | null | undefined,
+  options: CountUpOptions = {}
+): number {
+  const { duration = 320, enabled = true } = options;
+
+  const to = typeof target === 'number' && Number.isFinite(target) ? target : 0;
+
+  const [display, setDisplay] = useState(0);
+  /** 和 display 同步的 ref：effect 里要读"现在停在哪"，但不能把它写进依赖 */
+  const shownRef = useRef(0);
+  const frameRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    // 卸载 / 重新触发前先撤掉上一帧，避免两条动画抢着写同一个 state
+    if (frameRef.current !== null) {
+      cancelAnimationFrame(frameRef.current);
+      frameRef.current = null;
+    }
+
+    if (!enabled) return;
+
+    const from = shownRef.current;
+    if (from === to) return;
+
+    // 用户系统开了「减少动态效果」→ 直接给终值，不装这个动效
+    if (prefersReducedMotion() || duration <= 0) {
+      shownRef.current = to;
+      setDisplay(to);
+      return;
+    }
+
+    const start = performance.now();
+
+    const run = (now: number) => {
+      const progress = Math.min(1, (now - start) / duration);
+      const value = from + (to - from) * easeOut(progress);
+      const next = Math.round(value);
+
+      // 只在整数真的变了才 setState：320ms 里最多 60 次渲染 → 通常只有几次
+      if (next !== shownRef.current) {
+        shownRef.current = next;
+        setDisplay(next);
+      }
+
+      if (progress < 1) {
+        frameRef.current = requestAnimationFrame(run);
+      } else {
+        shownRef.current = to;
+        setDisplay(to);
+        frameRef.current = null;
+      }
+    };
+
+    frameRef.current = requestAnimationFrame(run);
+
+    return () => {
+      if (frameRef.current !== null) {
+        cancelAnimationFrame(frameRef.current);
+        frameRef.current = null;
+      }
+    };
+  }, [to, duration, enabled]);
+
+  return display;
+}

package/resources/src/components/feedback/usePending.ts

@@ -0,0 +1,209 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { beginTask, endTask, WAIT } from '@/lib/pending';
+
+/**
+ * 等待反馈的三个基础 hook。
+ *
+ * 统一解决三件容易被忽略、但直接决定"等起来尴尬不尴尬"的事：
+ *   1. 快请求不要闪 spinner（延迟出现）
+ *   2. 慢请求要让用户看到「过了多久」（而不是只有一个转圈）
+ *   3. 超长请求文案要升级，并且最好能取消
+ */
+
+/** 一个任务阶段：`after` 毫秒之后，文案换成 `text` */
+export type TaskStage = { after: number; text: string };
+
+/**
+ * 默认三阶段文案。语义台阶是「在做 → 还没完 → 有点慢但没死」：
+ * 用户看到第二、第三句时，就不会去点第二次了。
+ */
+export const DEFAULT_STAGES: TaskStage[] = [
+  { after: 0, text: '正在处理…' },
+  { after: WAIT.GLOBAL_APPEAR, text: '仍在处理，请稍候…' },
+  { after: WAIT.SLOW, text: '处理时间较长，仍在继续…' },
+];
+
+/** 按已耗时挑当前阶段文案 */
+export function stageAt(stages: TaskStage[], ms: number): string {
+  let text = stages[0]?.text ?? '正在处理…';
+  for (const s of stages) {
+    if (ms >= s.after) text = s.text;
+  }
+  return text;
+}
+
+/** 把毫秒说成「3 秒」这种能一眼扫过的量级 */
+export function formatElapsed(ms: number): string {
+  const s = ms / 1000;
+  if (s < 10) return `${s.toFixed(1)} 秒`;
+  return `${Math.round(s)} 秒`;
+}
+
+/**
+ * 延迟显示。
+ *
+ * `pending` 变 true 后先等 `delay` 毫秒再返回 true；一结束立刻返回 false。
+ * 效果：200ms 内返回的请求，用户完全看不到 spinner 闪一下。
+ */
+export function useDelayedLoading(pending: boolean, delay: number = WAIT.LOCAL_DELAY): boolean {
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    if (!pending) {
+      setVisible(false);
+      return;
+    }
+    if (delay <= 0) {
+      setVisible(true);
+      return;
+    }
+    const timer = setTimeout(() => setVisible(true), delay);
+    return () => clearTimeout(timer);
+  }, [pending, delay]);
+
+  return visible;
+}
+
+/**
+ * 已耗时（毫秒）。`active` 为 false 时恒为 0。
+ *
+ * 只在 active 期间开 interval，且默认 400ms 一跳 —— 秒数变化足够，
+ * 又不会因为每帧 setState 把长任务页面拖卡。
+ */
+export function useElapsed(active: boolean, tick = 400): number {
+  const [ms, setMs] = useState(0);
+  const startRef = useRef(0);
+
+  useEffect(() => {
+    if (!active) {
+      setMs(0);
+      return;
+    }
+    startRef.current = Date.now();
+    setMs(0);
+    const timer = setInterval(() => setMs(Date.now() - startRef.current), tick);
+    return () => clearInterval(timer);
+  }, [active, tick]);
+
+  return ms;
+}
+
+export type UseAsyncTaskOptions<R> = {
+  /** 登记到全局浮层的文案；默认「正在处理…」 */
+  label?: string;
+  /** true 时只在组件内部显示 loading，不进全局浮层（例如已经有大遮罩的导入） */
+  silent?: boolean;
+  /** 分阶段文案，不传用 DEFAULT_STAGES */
+  stages?: TaskStage[];
+  onSuccess?: (result: R) => void;
+  onError?: (error: unknown) => void;
+  onCancel?: () => void;
+};
+
+export type AsyncTask<A extends unknown[], R> = {
+  /** 执行；重复调用会被忽略（防重复提交） */
+  run: (...args: A) => Promise<R | undefined>;
+  /** 立刻中止（底层要响应 signal 才有效，例如 fetch / axios） */
+  cancel: () => void;
+  /** 是否进行中（立即为 true，用于禁用按钮） */
+  pending: boolean;
+  /** 延迟后的展示态（用于 spinner，避免闪烁） */
+  visible: boolean;
+  /** 已耗时毫秒 */
+  elapsed: number;
+  /** 当前阶段文案 */
+  stageText: string;
+};
+
+/**
+ * 把一个 async 动作打包成「带等待反馈的任务」。
+ *
+ * 用它是为了不再在页面里手写这一坨：
+ *   const [loading, setLoading] = useState(false)
+ *   try { setLoading(true); await xxx() } finally { setLoading(false) }
+ * 而且天然自带你手写时最容易漏的三样：防重复提交、已耗时、阶段文案。
+ *
+ * 注意：默认**不向外抛异常**，错误交给 onError；需要自己 catch 时传 throwOnError。
+ */
+export function useAsyncTask<A extends unknown[], R>(
+  fn: (signal: AbortSignal, ...args: A) => Promise<R>,
+  options: UseAsyncTaskOptions<R> & { throwOnError?: boolean } = {}
+): AsyncTask<A, R> {
+  const fnRef = useRef(fn);
+  fnRef.current = fn;
+  const optRef = useRef(options);
+  optRef.current = options;
+
+  const [pending, setPending] = useState(false);
+  const pendingRef = useRef(false);
+  const ctrlRef = useRef<AbortController | null>(null);
+  const taskIdRef = useRef<string | null>(null);
+
+  const elapsed = useElapsed(pending);
+  const visible = useDelayedLoading(pending);
+
+  const cleanup = useCallback(() => {
+    endTask(taskIdRef.current);
+    taskIdRef.current = null;
+    ctrlRef.current = null;
+    pendingRef.current = false;
+    setPending(false);
+  }, []);
+
+  // 卸载时兜底：任务还挂着就把全局那条撤掉，否则浮层会一直转到用户离开
+  useEffect(() => {
+    return () => {
+      endTask(taskIdRef.current);
+      taskIdRef.current = null;
+      if (ctrlRef.current) ctrlRef.current.abort();
+    };
+  }, []);
+
+  const run = useCallback(
+    async (...args: A): Promise<R | undefined> => {
+      if (pendingRef.current) return undefined;
+      const o = optRef.current;
+
+      pendingRef.current = true;
+      setPending(true);
+
+      const ctrl = new AbortController();
+      ctrlRef.current = ctrl;
+      taskIdRef.current = o.silent ? null : beginTask(o.label ?? '正在处理…', 'task');
+
+      try {
+        const result = await fnRef.current(ctrl.signal, ...args);
+        o.onSuccess?.(result);
+        return result;
+      } catch (e) {
+        if (ctrl.signal.aborted) {
+          o.onCancel?.();
+          return undefined;
+        }
+        o.onError?.(e);
+        if (o.throwOnError) throw e;
+        return undefined;
+      } finally {
+        cleanup();
+      }
+    },
+    [cleanup]
+  );
+
+  const cancel = useCallback(() => {
+    ctrlRef.current?.abort();
+  }, []);
+
+  const stages = options.stages ?? DEFAULT_STAGES;
+
+  return {
+    run,
+    cancel,
+    pending,
+    visible,
+    elapsed,
+    stageText: stageAt(stages, elapsed),
+  };
+}

package/resources/src/components/feedback/useRowFlash.ts

@@ -0,0 +1,40 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+/**
+ * 列表页「刚才改的是这一行」的状态容器。
+ *
+ * 样板是这样的，每个 CRUD 页面都要写一遍，所以抽出来：
+ *
+ *   const { highlightRow, flashRow } = useRowFlash();
+ *
+ *   // 保存/切换状态成功后
+ *   flashRow(row.id);
+ *
+ *   // 交给表格
+ *   <DataTable highlightRow={highlightRow} … />
+ *
+ * 为什么必须带 tick：
+ *   同一个 id 连续触发（比如连拨两次开关），key 不变，
+ *   DataTable 那边就认为"没变化"、不会重播动画。tick 自增解决这件事。
+ */
+
+export type RowFlashTarget = { key: string | number; tick: number };
+
+export type UseRowFlashResult = {
+  /** 直接传给 DataTable 的 highlightRow */
+  highlightRow: RowFlashTarget | null;
+  /** 操作成功后调它；同一行可以反复调 */
+  flashRow: (key: string | number) => void;
+};
+
+export function useRowFlash(): UseRowFlashResult {
+  const [highlightRow, setHighlightRow] = useState<RowFlashTarget | null>(null);
+
+  const flashRow = useCallback((key: string | number) => {
+    setHighlightRow((prev) => ({ key, tick: (prev?.tick ?? 0) + 1 }));
+  }, []);
+
+  return { highlightRow, flashRow };
+}