node-resource-utils 0.0.0-stage → 1.1.7

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

@@ -0,0 +1,249 @@
+'use client';
+
+import type { CSSProperties } from 'react';
+import { MILITARY } from '@/lib/theme';
+
+/**
+ * 骨架屏。
+ *
+ * 为什么不全用 Spin 转圈：
+ *   - 转圈只说明"在等"，骨架屏还告诉用户"等来的是什么东西、大概多大"
+ *   - 页面高度不会先塌再撑，内容出来时不会跳一下
+ * 列表首屏、详情面板、统计卡这三处收益最明显，所以都给了现成的组合件。
+ *
+ * 流光动画走 globals.css 的 .wb-skeleton（背景位移，不用 filter，老内核也稳）。
+ */
+
+type Size = number | string;
+
+export function SkeletonBlock({
+  width = '100%',
+  height = 12,
+  radius = 6,
+  style,
+}: {
+  width?: Size;
+  height?: Size;
+  radius?: number;
+  style?: CSSProperties;
+}) {
+  return (
+    <div
+      className="wb-skeleton"
+      style={{ width, height, borderRadius: radius, ...style }}
+      aria-hidden
+    />
+  );
+}
+
+/** 多行文字占位：最后一行短一截，看起来像真的一段话 */
+export function SkeletonText({
+  lines = 3,
+  lineHeight = 12,
+  gap = 8,
+  lastWidth = '62%',
+}: {
+  lines?: number;
+  lineHeight?: number;
+  gap?: number;
+  lastWidth?: Size;
+}) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap }}>
+      {Array.from({ length: lines }).map((_, i) => (
+        <SkeletonBlock
+          key={i}
+          height={lineHeight}
+          width={i === lines - 1 ? lastWidth : '100%'}
+        />
+      ))}
+    </div>
+  );
+}
+
+/** 统计卡占位（工作台的四个数字卡） */
+export function SkeletonCards({
+  count = 4,
+  height = 88,
+  minWidth = 150,
+  gap = 16,
+}: {
+  count?: number;
+  height?: number;
+  minWidth?: number;
+  gap?: number;
+}) {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: `repeat(auto-fit, minmax(${minWidth}px, 1fr))`,
+        gap,
+      }}
+    >
+      {Array.from({ length: count }).map((_, i) => (
+        <div
+          key={i}
+          style={{
+            height,
+            borderRadius: 10,
+            border: `1px solid ${MILITARY.borderSoft}`,
+            background: MILITARY.card,
+            padding: 14,
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 10,
+            justifyContent: 'center',
+          }}
+        >
+          <SkeletonBlock width={64} height={10} />
+          <SkeletonBlock width={96} height={20} />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * 表格占位。
+ *
+ * 列宽用同一套比例（不外传真实列定义），这样加载完切到真表格不会明显跳变；
+ * 行高对齐 antd Table 的 middle 尺寸（约 47px），高度也基本对得上。
+ */
+export function SkeletonTable({
+  rows = 6,
+  cols = 4,
+  showHeader = true,
+  pagination = false,
+}: {
+  rows?: number;
+  cols?: number;
+  showHeader?: boolean;
+  /** 是否在底部留出分页条的位置（列表页用 true，避免加载完底部跳一下） */
+  pagination?: boolean;
+}) {
+  return (
+    <div aria-hidden>
+      <div
+        style={{
+          border: `1px solid ${MILITARY.border}`,
+          borderRadius: 8,
+          overflow: 'hidden',
+          background: MILITARY.card,
+        }}
+      >
+        {showHeader ? (
+          <div
+            style={{
+              display: 'flex',
+              gap: 16,
+              padding: '12px 16px',
+              background: MILITARY.soft,
+              borderBottom: `1px solid ${MILITARY.border}`,
+            }}
+          >
+            {Array.from({ length: cols }).map((_, i) => (
+              <SkeletonBlock key={i} height={10} width={i === 0 ? 72 : `${100 / cols}%`} />
+            ))}
+          </div>
+        ) : null}
+
+        {Array.from({ length: rows }).map((_, r) => (
+          <div
+            key={r}
+            style={{
+              display: 'flex',
+              gap: 16,
+              padding: '14px 16px',
+              borderBottom: r === rows - 1 ? 'none' : `1px solid ${MILITARY.borderSoft}`,
+              alignItems: 'center',
+            }}
+          >
+            {Array.from({ length: cols }).map((_, c) => (
+              <SkeletonBlock
+                key={c}
+                height={11}
+                width={c === 0 ? 88 : `${100 / cols}%`}
+                // 中间列偶尔短一点，整体更像真实数据
+                style={c > 0 && (c + r) % 3 === 0 ? { maxWidth: '55%' } : undefined}
+              />
+            ))}
+          </div>
+        ))}
+      </div>
+
+      {pagination ? (
+        <div
+          style={{
+            display: 'flex',
+            justifyContent: 'flex-end',
+            alignItems: 'center',
+            gap: 8,
+            padding: '16px 4px 0',
+          }}
+        >
+          <SkeletonBlock width={64} height={10} />
+          {[26, 26, 26, 26].map((w, i) => (
+            <SkeletonBlock key={i} width={w} height={26} radius={6} />
+          ))}
+          <SkeletonBlock width={52} height={26} radius={6} />
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/** 表单/详情面板占位：label + 输入框，成对出现 */
+export function SkeletonDetail({
+  rows = 5,
+  labelWidth = 72,
+}: {
+  rows?: number;
+  labelWidth?: number;
+}) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }} aria-hidden>
+      {Array.from({ length: rows }).map((_, i) => (
+        <div key={i} style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+          <SkeletonBlock width={labelWidth} height={10} />
+          <SkeletonBlock height={30} radius={8} />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * 整页骨架：页头（kicker + 标题 + 说明）+ 统计卡 + 表格。
+ * 给 (admin)/loading.tsx 用，路由切换时先看到版式而不是空白。
+ */
+export function SkeletonPage({
+  cards = 4,
+  rows = 6,
+  cols = 5,
+}: {
+  cards?: number;
+  rows?: number;
+  cols?: number;
+}) {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }} aria-hidden>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+        <SkeletonBlock width={52} height={9} />
+        <SkeletonBlock width={210} height={20} />
+        <SkeletonBlock width="48%" height={10} />
+      </div>
+      {cards > 0 ? <SkeletonCards count={cards} /> : null}
+      <div
+        style={{
+          background: MILITARY.card,
+          border: `1px solid ${MILITARY.borderSoft}`,
+          borderRadius: 12,
+          padding: 16,
+        }}
+      >
+        <SkeletonTable rows={rows} cols={cols} />
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,70 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { Statistic } from 'antd';
+import PressableCard from './PressableCard';
+import { useCountUp } from './useCountUp';
+
+/**
+ * 统计卡 —— 看板 / 首页 / 任何"一个数字 + 一句说明"的地方都用它。
+ *
+ * 它把三件容易漏、漏了就显得业余的事绑在了一起：
+ *   1. 数字滚动（useCountUp）—— 用户能分清"刚加载完"和"本来就是 5"
+ *   2. 可点手感（PressableCard）—— 能下钻的卡要让人看出来能点
+ *   3. 加载态（loading）—— 骨架屏期间不滚动，避免先滚一遍 0
+ *
+ * 用法：
+ *   <StatCard title="用户总数" value={stats?.userCount} icon={<TeamOutlined />}
+ *             color={CHART_COLORS[0]} href="/system/users" loading={isLoading} />
+ *
+ * 需要 Statistic 的完整能力（精度、前后缀以外的定制）时，
+ *   直接用 <PressableCard> + <Statistic> 手工组合，别往这里堆 props。
+ */
+
+export type StatCardProps = {
+  title: ReactNode;
+  /** 目标值；undefined / null 期间显示 0，加载完自动滚到真实值 */
+  value: number | null | undefined;
+  icon?: ReactNode;
+  /** 数字与图标颜色，一般取 CHART_COLORS[n] 或 MILITARY.primary */
+  color?: string;
+  /** 给了就整卡可点并跳转；不给就是纯展示（不会有手感，避免骗人） */
+  href?: string;
+  onPress?: () => void;
+  /** 数据还在加载：此时显示 antd 骨架，且不启动计数动画 */
+  loading?: boolean;
+  /** 小数位，默认 0 */
+  precision?: number;
+  suffix?: ReactNode;
+  /** 计数时长，默认 320ms；超过 400 会显得在表演 */
+  duration?: number;
+};
+
+export default function StatCard({
+  title,
+  value,
+  icon,
+  color,
+  href,
+  onPress,
+  loading,
+  precision,
+  suffix,
+  duration,
+}: StatCardProps) {
+  const shown = useCountUp(value, { enabled: !loading, duration });
+
+  return (
+    <PressableCard href={href} onPress={onPress}>
+      <Statistic
+        title={title}
+        value={shown}
+        loading={loading}
+        precision={precision}
+        suffix={suffix}
+        prefix={icon ? <span style={{ color, marginRight: 8 }}>{icon}</span> : undefined}
+        styles={{ content: color ? { color, fontWeight: 600 } : { fontWeight: 600 } }}
+      />
+    </PressableCard>
+  );
+}

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

@@ -0,0 +1,153 @@
+'use client';
+
+import { useEffect, useState, useSyncExternalStore } from 'react';
+import { fs, MILITARY } from '@/lib/theme';
+import {
+  endTask,
+  getTasksServerSnapshot,
+  getTasksSnapshot,
+  subscribeTasks,
+  WAIT,
+} from '@/lib/pending';
+import { formatElapsed } from './usePending';
+
+/**
+ * 全局等待浮层（兜底的那一层）。
+ *
+ * 它不认识任何业务：只订阅全局任务表，发现有任务已经超过 3 秒还没结束，
+ * 就在右下角浮出一张很轻的提示卡。所以：
+ *   - 新写的页面忘了加 loading → 有它兜着
+ *   - 导出、导入、AI 报告、批量删除 → 同一个样子，不用各写一遍
+ *   - 3 秒以内完成的请求 → 它根本不出现，不打扰
+ *
+ * 刻意不做成遮罩、也不做全屏 loading：
+ * 右下角一小块、`pointer-events: none`，用户还能继续看页面、翻别的内容。
+ */
+
+/** 兜底清理：任务超过这个时间还没注销，认为是页面被关掉/跳走了，自动撤掉 */
+const STALE_MS = 5 * 60 * 1000;
+
+export default function TaskHint() {
+  const tasks = useSyncExternalStore(
+    subscribeTasks,
+    getTasksSnapshot,
+    getTasksServerSnapshot
+  );
+  const [now, setNow] = useState(0);
+
+  useEffect(() => {
+    if (!tasks.length) {
+      setNow(0);
+      return;
+    }
+    setNow(Date.now());
+    const timer = setInterval(() => {
+      const t = Date.now();
+      setNow(t);
+      // 顺手清掉"僵尸任务"，避免浮层永远挂在屏幕上
+      for (const task of getTasksSnapshot()) {
+        if (t - task.startedAt > STALE_MS) endTask(task.id);
+      }
+    }, 500);
+    return () => clearInterval(timer);
+  }, [tasks.length]);
+
+  if (!tasks.length) return null;
+
+  // 取最早开始的那条：它才是用户真正在等的
+  const head = tasks.reduce((a, b) => (a.startedAt <= b.startedAt ? a : b));
+  const elapsed = Math.max(0, now - head.startedAt);
+  if (elapsed < WAIT.GLOBAL_APPEAR) return null;
+
+  const slow = elapsed >= WAIT.SLOW;
+  const extra = tasks.length - 1;
+
+  return (
+    <div
+      className="wb-hint-enter"
+      role="status"
+      aria-live="polite"
+      style={{
+        position: 'fixed',
+        right: 20,
+        bottom: 20,
+        zIndex: 1100,
+        minWidth: 236,
+        maxWidth: 320,
+        padding: '11px 14px 10px',
+        borderRadius: 12,
+        background: MILITARY.card,
+        border: `1px solid ${MILITARY.border}`,
+        borderLeft: `3px solid ${slow ? MILITARY.warning : MILITARY.primary}`,
+        boxShadow: MILITARY.shadow,
+        // 不挡任何点击：它只是"告知"，不是"拦截"
+        pointerEvents: 'none',
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 9 }}>
+        <span
+          aria-hidden
+          style={{
+            width: 13,
+            height: 13,
+            flex: '0 0 auto',
+            borderRadius: '50%',
+            border: `2px solid ${MILITARY.softStrong}`,
+            borderTopColor: slow ? MILITARY.warning : MILITARY.primary,
+            animation: 'wb-spin 0.8s linear infinite',
+          }}
+        />
+        <span
+          style={{
+            fontSize: fs(13),
+            color: MILITARY.text,
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {head.label}
+        </span>
+      </div>
+
+      <div
+        style={{
+          marginTop: 5,
+          marginLeft: 22,
+          fontSize: fs(11.5),
+          color: MILITARY.textMuted,
+          display: 'flex',
+          gap: 6,
+          flexWrap: 'wrap',
+        }}
+      >
+        <span>已等待 {formatElapsed(elapsed)}</span>
+        {extra > 0 ? <span>· 另有 {extra} 项</span> : null}
+        {slow ? <span style={{ color: MILITARY.warning }}>· 仍在继续，请勿重复提交</span> : null}
+      </div>
+
+      {/* 不确定进度条：说明"它在动"，但不敢假装知道还剩多久 */}
+      <div
+        style={{
+          marginTop: 9,
+          height: 3,
+          borderRadius: 999,
+          background: MILITARY.soft,
+          overflow: 'hidden',
+        }}
+      >
+        <div
+          className="wb-indeterminate-bar"
+          style={{
+            width: '38%',
+            height: '100%',
+            borderRadius: 999,
+            background: slow
+              ? `linear-gradient(90deg, ${MILITARY.accent}, ${MILITARY.warning})`
+              : `linear-gradient(90deg, ${MILITARY.primaryHover}, ${MILITARY.accent})`,
+          }}
+        />
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,93 @@
+'use client';
+
+/**
+ * 反馈组件族 —— 统一出口。
+ *
+ * ★ 这个目录管两件事，别混着用：
+ *
+ *   【等待反馈】系统还在忙吗？—— 用户愿意等，只要知道在等
+ *     AsyncButton     一个按钮点了之后要等        —— 最常用，直接替换 <Button>
+ *     LoadingOverlay  一块区域整体在等            —— 卡片/面板/详情
+ *     Skeleton*       首次加载、还不知道等多久    —— 列表、详情、整页
+ *     TaskHint        全局兜底（>3s 自动出现）    —— 已在 Providers 挂好，页面不用管
+ *     RouteProgress   跳页面时的顶部进度条        —— 入口处调 startRouteProgress()
+ *     useAsyncTask    自己画等待态时用它拿状态    —— 需要自定义 UI 时
+ *
+ *   【操作反馈】我这一下，系统收到了吗？—— 用户不该怀疑自己点没点上
+ *     PressableCard   可点击卡片（自动判断可点性 + 手感 + 右上角 ›）
+ *     StatCard        统计卡 = 数字滚动 + 可点手感 + 加载态，看板首选
+ *     useRowFlash     列表页"刚才改的是这一行"的状态容器，配合 DataTable
+ *     flashElement    让任意元素闪一下（非表格场景）
+ *     useCountUp      单独用计数动画时（必须放在独立子组件里）
+ *
+ * —— 新题接入（三步，都只要一行）——
+ *
+ *   1. 看板 / 首页的指标卡
+ *      <StatCard title="订单总数" value={stats?.orderCount} icon={<ShoppingOutlined />}
+ *                color={CHART_COLORS[0]} href="/orders" loading={isLoading} />
+ *
+ *   2. 列表页保存 / 删除 / 切换状态后定位到那一行
+ *      const { highlightRow, flashRow } = useRowFlash();
+ *      // 成功后：flashRow(row.id)
+ *      <DataTable highlightRow={highlightRow} … />
+ *
+ *   3. 自定义卡片（不走 antd Card 的场景）
+ *      <div className="wb-pressable" onClick={…}>…</div>
+ *      —— 只有真能点才加这个类，加了不能点比不加更像 bug。
+ *
+ * —— 调力度只改 motion.css 的变量 ——
+ *   --wb-dur 0.18s（悬停）/ --wb-dur-fast 0.08s（按下）/ --wb-flash-dur 0.5s（结果落地）
+ *   / --wb-lift -1px（抬升）。超过 0.24s 就开始像"系统在表演"，不要加。
+ *
+ * —— 三条禁令 ——
+ *   1. 不给静态内容加手感（点了没反应会让用户以为坏了）
+ *   2. 不引 framer-motion / react-spring 之类的动画库（脚手架红线：不引新依赖）
+ *   3. 所有动效必须在 prefers-reduced-motion 下有静默版本（motion.css 已统一处理，
+ *      自己写的新动画要补上）
+ *
+ * 样式：motion.css 由 app/globals.css @import，页面里不用再引。
+ */
+
+export { default as AsyncButton } from './AsyncButton';
+export type { AsyncButtonProps } from './AsyncButton';
+
+export { default as LoadingOverlay } from './LoadingOverlay';
+export type { LoadingOverlayProps } from './LoadingOverlay';
+
+export { default as TaskHint } from './TaskHint';
+
+export { default as RouteProgress, startRouteProgress } from './RouteProgress';
+
+export {
+  SkeletonBlock,
+  SkeletonText,
+  SkeletonCards,
+  SkeletonTable,
+  SkeletonDetail,
+  SkeletonPage,
+} from './Skeleton';
+
+export {
+  useAsyncTask,
+  useDelayedLoading,
+  useElapsed,
+  stageAt,
+  formatElapsed,
+  DEFAULT_STAGES,
+} from './usePending';
+export type { TaskStage, AsyncTask, UseAsyncTaskOptions } from './usePending';
+
+// —— 操作反馈 ——
+export { default as PressableCard } from './PressableCard';
+export type { PressableCardProps } from './PressableCard';
+
+export { default as StatCard } from './StatCard';
+export type { StatCardProps } from './StatCard';
+
+export { useCountUp } from './useCountUp';
+export type { CountUpOptions } from './useCountUp';
+
+export { useRowFlash } from './useRowFlash';
+export type { RowFlashTarget, UseRowFlashResult } from './useRowFlash';
+
+export { flashElement, flashTableRow, FLASH_DURATION_MS } from './motion';