node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/components/feedback/AsyncButton.tsx

@@ -0,0 +1,108 @@
+'use client';
+
+import { App, Button, type ButtonProps } from 'antd';
+import type { ReactNode } from 'react';
+import { errText } from '@/lib/err-text';
+import { useAsyncTask, type TaskStage } from './usePending';
+import { fs } from '@/lib/theme';
+
+/**
+ * 会自己交代进度的按钮。
+ *
+ * 比赛里最常写的一行代码是：
+ *   <Button onClick={async () => { await axios.post(...) }}>提交</Button>
+ * 它有三个隐患：不防重复点击、慢的时候没有任何反馈、失败只报 console。
+ *
+ * 换成 AsyncButton 这三件事一次解决：
+ *   <AsyncButton type="primary" task={() => axios.post('/api/xxx')} successText="已提交">
+ *     提交
+ *   </AsyncButton>
+ *
+ * 约定：`task` 收到 AbortSignal，fetch / axios 传进去就能被取消；
+ * 不响应也没关系，取消只是让按钮恢复、不再等结果。
+ */
+
+export type AsyncButtonProps = Omit<ButtonProps, 'onClick' | 'loading' | 'children' | 'href'> & {
+  /** 点击后要跑的耗时动作 */
+  task: (signal: AbortSignal) => Promise<unknown>;
+  children?: ReactNode;
+  /** 分阶段文案（只在按钮上显示短文案，长句交给全局浮层） */
+  stages?: TaskStage[];
+  /**
+   * 是否在按钮上显示已耗时：
+   *   'auto'（默认）超过 3 秒才显示，短任务完全不打扰
+   *   true  一开始就显示
+   *   false 从不显示
+   */
+  showElapsed?: boolean | 'auto';
+  /** 成功后弹的提示；不传则不弹 */
+  successText?: string;
+  /** 失败提示。返回空字符串表示不弹（自己处理） */
+  errorText?: (e: unknown) => string;
+  /** 登记到全局浮层的文案，默认用按钮文字 */
+  label?: string;
+  /** 不进全局浮层，只在按钮上转 */
+  silent?: boolean;
+  /** 成功后回调（关闭弹窗、刷新列表都放这里） */
+  onDone?: (result: unknown) => void;
+  onFail?: (e: unknown) => void;
+};
+
+function nodeToText(node: ReactNode): string {
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number') return String(node);
+  if (Array.isArray(node)) return node.map(nodeToText).join('');
+  return '';
+}
+
+export default function AsyncButton({
+  task,
+  children,
+  stages,
+  showElapsed = 'auto',
+  successText,
+  errorText,
+  label,
+  silent,
+  onDone,
+  onFail,
+  ...rest
+}: AsyncButtonProps) {
+  const { message } = App.useApp();
+
+  const job = useAsyncTask(task, {
+    label: label ?? (nodeToText(children) || undefined),
+    silent,
+    stages,
+    onSuccess: (r) => {
+      if (successText) message.success(successText);
+      onDone?.(r);
+    },
+    onError: (e) => {
+      const text = errorText ? errorText(e) : errText(e);
+      if (text) message.error(text);
+      onFail?.(e);
+    },
+  });
+
+  const seconds = job.elapsed / 1000;
+  const withSeconds =
+    job.pending &&
+    (showElapsed === true || (showElapsed === 'auto' && job.elapsed >= 3000));
+
+  return (
+    <Button
+      {...rest}
+      // 用延迟后的 visible：200ms 内完成的操作按钮不会"抖一下"
+      loading={job.visible}
+      onClick={() => void job.run()}
+    >
+      {children}
+      {withSeconds ? (
+        <span style={{ marginLeft: 6, opacity: 0.72, fontSize: fs(12) }}>
+          {seconds < 10 ? `${seconds.toFixed(0)}s` : `${Math.round(seconds)}s`}
+        </span>
+      ) : null}
+    </Button>
+  );
+}

package/resources/src/components/feedback/LoadingOverlay.tsx

@@ -0,0 +1,125 @@
+'use client';
+
+import { Spin } from 'antd';
+import type { ReactNode } from 'react';
+import { fs, MILITARY } from '@/lib/theme';
+import { WAIT } from '@/lib/pending';
+import { formatElapsed, stageAt, useDelayedLoading, useElapsed, type TaskStage } from './usePending';
+
+/**
+ * 区域级等待遮罩。
+ *
+ * 典型用法：一块卡片/一个面板整体在等数据时，把内容蒙住而不是让它空着。
+ *   <LoadingOverlay loading={q.isLoading} text="正在读取用户…">
+ *     <Table ... />
+ *   </LoadingOverlay>
+ *
+ * 三个细节决定了它好不好用：
+ *   1. **保留旧内容**（半透明蒙层）—— 翻页/刷新时不清空，用户知道自己还在原地
+ *   2. **延迟出现**—— 200ms 内返回的请求看不到这层东西，界面不会闪
+ *   3. **显示已耗时**—— 超过 3 秒开始报秒数，用户知道它没死
+ */
+export type LoadingOverlayProps = {
+  loading: boolean;
+  /** 主文案；不传用「正在加载…」 */
+  text?: string;
+  /** 分阶段文案，覆盖 text */
+  stages?: TaskStage[];
+  /** 延迟出现毫秒，默认 WAIT.LOCAL_DELAY；传 0 表示立刻出现 */
+  delay?: number;
+  /** 容器最小高度，防止空内容时遮罩塌成一条线 */
+  minHeight?: number;
+  radius?: number;
+  /** 蒙层不透明度 0~1，默认 0.82（能透出下面的版式，但字看不清） */
+  veil?: number;
+  /** 蒙层底色 */
+  tone?: 'paper' | 'card';
+  /** 从多少毫秒开始显示秒数，默认 3 秒 */
+  elapsedAfter?: number;
+  cancelText?: string;
+  onCancel?: () => void;
+  children?: ReactNode;
+};
+
+/** #RRGGBB → rgba()。遮罩用 rgba 而不是 opacity，否则文案会跟着一起被淡化 */
+function withAlpha(hex: string, a: number): string {
+  const h = hex.replace('#', '');
+  const full = h.length === 3 ? h.split('').map((c) => c + c).join('') : h;
+  const n = parseInt(full, 16);
+  return `rgba(${(n >> 16) & 255}, ${(n >> 8) & 255}, ${n & 255}, ${a})`;
+}
+
+export default function LoadingOverlay({
+  loading,
+  text = '正在加载…',
+  stages,
+  delay = WAIT.LOCAL_DELAY,
+  minHeight = 160,
+  radius = 12,
+  veil = 0.82,
+  tone = 'paper',
+  elapsedAfter = WAIT.GLOBAL_APPEAR,
+  cancelText,
+  onCancel,
+  children,
+}: LoadingOverlayProps) {
+  const visible = useDelayedLoading(loading, delay);
+  const elapsed = useElapsed(loading);
+  const stageText = stages ? stageAt(stages, elapsed) : text;
+  const base = tone === 'card' ? MILITARY.card : MILITARY.paper;
+
+  return (
+    <div style={{ position: 'relative', minHeight, borderRadius: radius }}>
+      {children}
+
+      {visible ? (
+        <div
+          role="status"
+          aria-live="polite"
+          style={{
+            position: 'absolute',
+            inset: 0,
+            borderRadius: radius,
+            // 用 rgba 而不是 opacity：opacity 会把里面的文案、spinner 一起淡化，
+            // 实测下来小字几乎看不清（踩过）
+            background: withAlpha(base, veil),
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 10,
+            zIndex: 5,
+            // 蒙层期间不拦截既有内容的滚动，只是视觉上盖住
+            pointerEvents: onCancel ? 'auto' : 'none',
+          }}
+        >
+          <Spin />
+          <div style={{ fontSize: fs(13), color: MILITARY.textSecondary }}>{stageText}</div>
+          {elapsed >= elapsedAfter ? (
+            <div style={{ fontSize: fs(11.5), color: MILITARY.textMuted }}>
+              已等待 {formatElapsed(elapsed)}
+            </div>
+          ) : null}
+          {onCancel ? (
+            <button
+              type="button"
+              onClick={onCancel}
+              style={{
+                marginTop: 2,
+                padding: '2px 10px',
+                fontSize: fs(12),
+                color: MILITARY.textSecondary,
+                background: 'transparent',
+                border: `1px solid ${MILITARY.border}`,
+                borderRadius: 999,
+                cursor: 'pointer',
+              }}
+            >
+              {cancelText ?? '取消'}
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/resources/src/components/feedback/PressableCard.tsx

@@ -0,0 +1,92 @@
+'use client';
+
+import Link from 'next/link';
+import type { KeyboardEvent, ReactNode } from 'react';
+import { Card, type CardProps } from 'antd';
+
+/**
+ * 可点击卡片 —— 「手感」这件事的唯一样板。
+ *
+ * 为什么要有这个组件，而不是让页面自己写 className：
+ *   1. `wb-pressable` 加错地方是有害的（不响应的卡却在动，比不动更像 bug）。
+ *      这里**自动判断**：只有给了 href / onPress 才加，从根上避免误用。
+ *   2. Link + Card 的组合有三处琐碎细节（display:block、颜色继承、去下划线），
+ *      每个列表页重写一遍必然会漏。
+ *   3. 右上角的「›」提示要能提前告诉用户"这张卡能点"，
+ *      它和可点性是绑定的，不该由调用方记得加。
+ *
+ * 用法：
+ *   <PressableCard href="/system/users" title="用户总数">…</PressableCard>
+ *   <PressableCard onPress={() => setOpen(true)}>…</PressableCard>
+ *   <PressableCard>…</PressableCard>   // 纯静态，不会有任何动效
+ *
+ * ⚠️ 不要再用 antd 的 `hoverable`：它只改阴影不抬升，和这套手感打架。
+ *    需要更强的反馈就调 motion.css 里的 --wb-lift / --wb-dur。
+ */
+
+export type PressableCardProps = Omit<CardProps, 'hoverable' | 'onClick'> & {
+  /** 给了就当整卡是链接：可右键新标签页、可被爬虫识别 */
+  href?: string;
+  /** 没有链接但有行为时用；给了它自动开启手感 + 键盘可达（Enter / Space） */
+  onPress?: () => void;
+  /** 右上角「›」提示，默认跟着可点性走；静态卡想伪装成可点时才手动置 true */
+  cue?: boolean;
+  children?: ReactNode;
+};
+
+export default function PressableCard({
+  href,
+  onPress,
+  cue,
+  className,
+  children,
+  ...rest
+}: PressableCardProps) {
+  const clickable = Boolean(href) || typeof onPress === 'function';
+  const showCue = cue ?? clickable;
+
+  // 不可点就不挂手感类：这一条是这个组件的核心，不要为了"统一"放开
+  const cls = [clickable ? 'wb-pressable' : '', className].filter(Boolean).join(' ') || undefined;
+
+  const body = (
+    <>
+      {showCue ? (
+        <span className="wb-pressable__cue" aria-hidden>
+          ›
+        </span>
+      ) : null}
+      {children}
+    </>
+  );
+
+  if (href) {
+    return (
+      <Link href={href} style={{ display: 'block', color: 'inherit', textDecoration: 'none' }}>
+        <Card {...rest} className={cls}>
+          {body}
+        </Card>
+      </Link>
+    );
+  }
+
+  const onKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
+    if (!onPress) return;
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      onPress();
+    }
+  };
+
+  return (
+    <Card
+      {...rest}
+      className={cls}
+      onClick={onPress}
+      role={clickable ? 'button' : undefined}
+      tabIndex={clickable ? 0 : undefined}
+      onKeyDown={clickable ? onKeyDown : undefined}
+    >
+      {body}
+    </Card>
+  );
+}

package/resources/src/components/feedback/README.md

@@ -0,0 +1,97 @@
+# 反馈底座（feedback）
+
+比赛每道新题都要重做一遍页面，但"用户点了之后有没有反应"这件事是**通用**的。
+这个目录把它做成了一层能力：换题时不用重新设计动效，照着下面的样板接就行。
+
+## 两条铁律
+
+| 类型 | 回答的问题 | 用谁 |
+|---|---|---|
+| 等待反馈 | 系统还在忙吗？ | `AsyncButton` / `LoadingOverlay` / `Skeleton*` / `TaskHint`（已全局挂好） |
+| 操作反馈 | 我这一下，系统收到了吗？ | `PressableCard` / `StatCard` / `useRowFlash` |
+
+混着用会两头不讨好：给慢请求做按压动效，用户还是在干等；给快操作做遮罩，用户被打断。
+
+## 三个高频场景（复制即用）
+
+### 1. 看板指标卡
+
+```tsx
+import { StatCard } from '@/components/feedback';
+import { CHART_COLORS } from '@/lib/theme';
+
+<Col span={6}>
+  <StatCard
+    title="订单总数"
+    value={stats?.orderCount}
+    icon={<ShoppingOutlined />}
+    color={CHART_COLORS[0]}
+    href="/orders"          // 有下钻就写，没有就删掉 —— 没有 href 时不会动，避免骗人
+    loading={isLoading}
+  />
+</Col>
+```
+
+`StatCard` 内部已经处理：骨架期间不计数、加载完从 0 滚到真实值、可点才抬升、右上角 `›` 提示。
+
+### 2. 列表页"刚才改的是哪一行"
+
+```tsx
+import { useRowFlash } from '@/components/feedback';
+
+const { highlightRow, flashRow } = useRowFlash();
+
+// 保存 / 删除 / 切换状态成功后
+await save(row);
+message.success('保存成功');
+flashRow(row.id);          // ← 只需这一行
+
+// 传给表格
+<DataTable highlightRow={highlightRow} … />
+```
+
+`DataTable` 会等新数据真的拉回来再闪，不会闪到刷新前的旧行。同一行连点两次也能重播。
+
+### 3. 自定义卡片（不走 antd Card）
+
+```tsx
+<div className="wb-pressable" onClick={open}>
+  <span className="wb-pressable__cue" aria-hidden>›</span>
+  …
+</div>
+```
+
+⚠️ 只有**真能点**才加 `wb-pressable`。静态卡片加了，鼠标过去会动、点了没反应，比完全不动更像 bug。
+
+## 调力度（只改 `motion.css` 的 `:root`）
+
+| 变量 | 默认 | 说明 |
+|---|---|---|
+| `--wb-dur` | 0.18s | 悬停抬升 / 边框变色 |
+| `--wb-dur-fast` | 0.08s | 按下回弹（必须比悬停快） |
+| `--wb-flash-dur` | 0.5s | 结果落地闪一下的总时长 |
+| `--wb-lift` | -1px | 抬升距离 |
+| `--wb-shrink` | 0.995 | 按下缩放 |
+
+超过 0.24s 的响应就开始像"系统在表演"。宁可轻，不要飘。
+
+## 三条禁令
+
+1. **不给静态内容加动效** —— 不动比乱动好。
+2. **不引动画库**（framer-motion / react-spring）—— 脚手架红线是不引新依赖，
+   CSS transition + 一个 RAF 足够覆盖上面所有场景。
+3. **新写的动画必须补 `prefers-reduced-motion` 降级** —— `motion.css` 末尾有统一处理，
+   新增规则时记得加进那段 `@media`。
+
+## 目录
+
+```
+motion.css        视觉定义（由 app/globals.css @import，页面不用引）
+motion.ts         flashElement / flashTableRow，命令式闪一下
+useCountUp.ts     计数动画（⚠️ 必须放在独立子组件里，否则每帧重渲整页）
+useRowFlash.ts    列表页行高亮的状态容器
+PressableCard.tsx 可点击卡片（自动判断可点性）
+StatCard.tsx      统计卡（计数 + 手感 + 加载态）
+```
+
+等待反馈那几个文件不在这里展开，见 `index.ts` 的注释。

package/resources/src/components/feedback/RouteProgress.tsx

@@ -0,0 +1,108 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { MILITARY } from '@/lib/theme';
+
+/**
+ * 顶部路由进度条。
+ *
+ * 解决的是「点了菜单之后什么都没发生」那 0.3~1 秒：
+ * Next.js 的客户端跳转要先把下一屏的 JS 拉下来再渲染，
+ * 重页面（知识图谱、图表工作台）尤其明显。
+ *
+ * 用法：跳转入口调一次 `startRouteProgress()`，
+ * 本条在 pathname 变化时自己收尾 —— 不需要页面配合。
+ * （菜单、全局搜索、收藏、面包屑这些入口已在 AdminShell 里接好）
+ */
+
+let startFn: (() => void) | null = null;
+
+/** 通知进度条「开始跳转了」。非 React 场景（菜单 onClick）直接调这个 */
+export function startRouteProgress(): void {
+  startFn?.();
+}
+
+/** 兜底：万一跳转被拦下（权限拦截、路由报错），8 秒后自己消失，不会卡一条线在顶上 */
+const AUTO_FINISH_MS = 8000;
+
+export default function RouteProgress() {
+  const pathname = usePathname();
+  const [state, setState] = useState<{ visible: boolean; pct: number }>({
+    visible: false,
+    pct: 0,
+  });
+  const startedRef = useRef(false);
+  const timers = useRef<ReturnType<typeof setTimeout>[]>([]);
+
+  const clearTimers = useCallback(() => {
+    for (const t of timers.current) clearTimeout(t);
+    timers.current = [];
+  }, []);
+
+  const finish = useCallback(() => {
+    if (!startedRef.current) return;
+    startedRef.current = false;
+    clearTimers();
+    setState({ visible: true, pct: 100 });
+    // 走到 100% 再淡出，视觉上才是"完成"而不是"消失"
+    timers.current.push(
+      setTimeout(() => setState({ visible: false, pct: 0 }), 320)
+    );
+  }, [clearTimers]);
+
+  const start = useCallback(() => {
+    clearTimers();
+    startedRef.current = true;
+    setState({ visible: true, pct: 6 });
+    // 三段爬升：先快（有反应）→ 再慢（在加载）→ 最后极慢（还没完但不是卡死）
+    timers.current.push(
+      setTimeout(() => setState((s) => (s.visible ? { ...s, pct: 42 } : s)), 240),
+      setTimeout(() => setState((s) => (s.visible ? { ...s, pct: 68 } : s)), 900),
+      setTimeout(() => setState((s) => (s.visible ? { ...s, pct: 84 } : s)), 2400),
+      setTimeout(finish, AUTO_FINISH_MS)
+    );
+  }, [clearTimers, finish]);
+
+  // 把 start 交给外部调用方
+  useEffect(() => {
+    startFn = start;
+    return () => {
+      if (startFn === start) startFn = null;
+    };
+  }, [start]);
+
+  // 地址变了 = 新页面已经就位，收尾
+  useEffect(() => {
+    finish();
+  }, [pathname, finish]);
+
+  useEffect(() => clearTimers, [clearTimers]);
+
+  return (
+    <div
+      aria-hidden
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        right: 0,
+        height: 2,
+        zIndex: 1200,
+        pointerEvents: 'none',
+        opacity: state.visible ? 1 : 0,
+        transition: 'opacity .28s ease',
+      }}
+    >
+      <div
+        style={{
+          height: '100%',
+          width: `${state.pct}%`,
+          background: `linear-gradient(90deg, ${MILITARY.primary}, ${MILITARY.accent})`,
+          boxShadow: `0 0 8px ${MILITARY.primary}`,
+          transition: 'width .32s ease',
+        }}
+      />
+    </div>
+  );
+}