refactor(ui): migrate loading placeholders

Author: Aparencia

app/src/components/NotePreviewView.tsx

@@ -15,7 +15,7 @@ import { invoke, convertFileSrc } from "@tauri-apps/api/core";
 import type { Note, NoteFilterResult, TextFilterDecision, TextFilterReview, TextFilterStatus } from "../types";
 import { escapeHtml, renderTimestampAnchors } from "../utils/html";
 import AiRefineCard from "./AiRefineCard";
-import { ConfirmDialog } from "../ui/primitives";
+import { ConfirmDialog, Loading } from "../ui/primitives";
 
 const btn: React.CSSProperties = { padding: "5px 10px", cursor: "pointer", fontSize: 12 };
 
@@ -197,7 +197,13 @@ export default function NotePreviewView({
   };
 
   if (!preview) {
-    return <p style={{ fontSize: 12, color: "#9ca3af", padding: 16 }}>{status || "加载预览中…"}</p>;
+    // 批 4 T14：加载态改由 L1 原语承载（`role="status"` + 探针 + 逐字文案）。`status` 是
+    // 可读信息（可能是"载入失败"之类的说明），故仍作 label；排版权威留在原语的 `Text` 里。
+    return (
+      <div style={{ padding: 16 }}>
+        <Loading label={status || "加载预览中…"} />
+      </div>
+    );
   }
 
   const stats = preview.stats;

app/src/components/RefineLaunchDialog.tsx

@@ -14,7 +14,7 @@
  *              的 `kind` 分支）⇒ `open` 恒为 `true`，本组件每次由父层条件挂载。
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { Button, Modal } from "../ui/primitives";
+import { Button, Loading, Modal, Skeleton } from "../ui/primitives";
 import { invoke } from "@tauri-apps/api/core";
 import type { AiSettingsView, BalanceView, RefineEstimateView, RefineStrategyMeta } from "../types";
 import {
@@ -286,7 +286,13 @@ export default function RefineLaunchDialog({
           </label>
         </div>
       )}
-      {!est && <div style={{ marginTop: 8, fontSize: 11, color: "#9ca3af" }}>成本预估加载中…（无预估则无法启动，请重试）</div>}
+      {!est && (
+        <div style={{ marginTop: 8 }}>
+          {/* 批 4 T14：文案含可操作提示（无预估则无法启动）⇒ 逐字进 label；形状（金额 + 上限）已知 ⇒ 骨架 */}
+          <Loading label="成本预估加载中…（无预估则无法启动，请重试）" />
+          <Skeleton lines={2} />
+        </div>
+      )}
       {msg && <div style={{ fontSize: 11, color: "#dc2626", marginTop: 6 }}>{msg}</div>}
     </Modal>
   );

app/src/components/RefineStrategyPicker.tsx

@@ -23,7 +23,7 @@ import {
   matchIntent,
   type StrategyDraft,
 } from "../utils/refineStrategy";
-import { Button } from "../ui/primitives";
+import { Button, Loading } from "../ui/primitives";
 
 const optBtn = (active: boolean): React.CSSProperties => ({
   padding: "2px 8px", cursor: "pointer", fontSize: 11, borderRadius: 6,
@@ -173,7 +173,7 @@ export default function RefineStrategyPicker({
             </div>
           </div>
         ))}
-        {!meta && <div style={{ fontSize: 11, color: "#9ca3af" }}>策略声明加载中…</div>}
+        {!meta && <Loading label="策略声明加载中…" />}
       </div>
     </div>
   );

app/src/components/WebArticleView.tsx

@@ -9,7 +9,7 @@
 import { useEffect, useState } from "react";
 import { invoke } from "@tauri-apps/api/core";
 import { save } from "@tauri-apps/plugin-dialog";
-import { Button } from "../ui/primitives";
+import { Button, Loading, Skeleton } from "../ui/primitives";
 
 /** WebPage 响应结构（db_web::WebPage 为 serde camelCase——字段须 camel 读取） */
 interface WebPageView {
@@ -75,7 +75,18 @@ export default function WebArticleView({ sessionId, onToNote, onRemove }: Props)
   }, [sessionId]);
 
   if (err) return <p style={{ fontSize: 12, color: "#dc2626" }}>{err}</p>;
-  if (!page) return <p style={{ fontSize: 12, color: "#9ca3af" }}>文章加载中…</p>;
+  if (!page) {
+    // 批 4 T14：文章结构已知（来源行 + 段落块）⇒ 骨架占位；可读语义由 `Loading` 给
+    // （骨架整组 `aria-hidden`：只留骨架等于把"在等什么"从无障碍树里删掉）。
+    return (
+      <div>
+        <Loading label="文章加载中…" />
+        <div style={{ marginTop: 8 }}>
+          <Skeleton lines={4} />
+        </div>
+      </div>
+    );
+  }
 
   return (
     <div>

app/src/components/WindowSelectCard.tsx

@@ -8,6 +8,7 @@
  */
 import { useEffect, useRef, useState } from "react";
 import { zIndex } from "../ui/zIndex";
+import { Button } from "../ui/primitives";
 import type { WindowInfo } from "../types";
 
 interface Props {
@@ -177,9 +178,11 @@ export function WindowSelectCard({ windows, selected, onSelect, onRefresh, loadi
         >
           <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center", padding: "0 4px 6px" }}>
             <span style={{ fontSize: 11, color: "#6b7280" }}>推荐窗口</span>
-                          <button onClick={() => onRefresh()} disabled={loading} style={{ fontSize: 11, color: "#0d9488", cursor: "pointer" }}>
+            {/* 批 4 T14：原生按钮内的忙碌文案 ⇒ 按加载态三角的第 3 档落 `Button busy`
+                （不是 `Loading`）：`busy` 保留焦点与 Tab 序、由原语给探针与 aria-busy。 */}
+            <Button variant="ghost" size="sm" busy={loading} onClick={() => onRefresh()}>
               {loading ? "加载中…" : "⟳ 刷新"}
-            </button>
+            </Button>
           </div>
           <div style={{ display: "flex", flexDirection: "column", gap: 2, maxHeight: 260, overflowY: "auto" }}>
             {windows.length === 0 && !loading && (

app/src/components/review/ReviewSessionPanel.tsx

@@ -19,6 +19,7 @@ import { useCallback, useEffect, useState } from "react";
 import { invoke } from "@tauri-apps/api/core";
 import type { Flashcard } from "../../types/notes";
 import PromoteCardButton from "../PromoteCardButton";
+import { Loading, Skeleton } from "../../ui/primitives";
 
 /** 四档评分按钮（文案=回忆质量自评） */
 const RATINGS: { value: string; label: string; color: string }[] = [
@@ -118,7 +119,15 @@ export default function ReviewSessionPanel({ groupId, groupName, active = true,
 
       <div style={{ flex: 1, minHeight: 0, overflowY: "auto", padding: 24 }}>
         <div style={{ maxWidth: 640, margin: "0 auto" }}>
-          {!loaded && <p style={{ fontSize: 13, color: "#9ca3af" }}>加载中…</p>}
+          {!loaded && (
+            <div>
+              {/* 批 4 T14：可读语义（role="status" + 逐字文案）由 `Loading` 给，骨架只承载形状 */}
+              <Loading />
+              <div style={{ marginTop: 10 }}>
+                <Skeleton lines={3} />
+              </div>
+            </div>
+          )}
 
           {finished && (
             <div data-testid="session-finished" style={{ textAlign: "center", padding: "48px 0" }}>

app/src/ui/primitives/loadingBaseline.ts

@@ -0,0 +1,129 @@
+/**
+ * @ai-context 加载态（可见加载文案）的**冻结基线**（批 4 B11 裁决 + Task 14 的落点）。
+ *
+ * Why：规格 §5.1 的病灶逐字是「全站 **0 骨架屏**，长任务只有一行灰字」——本仓至今**没有加载原语**
+ *   （`Loading` / `Skeleton` / `Probe` 批 0-D 就交付了，批 4 才接进来）。全量按规格账本数是
+ *   「85 处 / 30 文件」，T1 的机器口径（`tmp/t1/slice-manifest.mjs` 的 loading 类）实测
+ *   **18 行 / 18 文件**（计划写的 19/19 是台账 #26 的 Windows 域过滤 bug）。18 处里有 14 处在
+ *   B11 切片内（判据 ①本批已触碰 ∪ ②`pages/**` ∪ ③有同名测试），4 处是余量。
+ *
+ * Why 冻结在**文件 → 行数**粒度（与 `nativeButtonBaseline.ts` 同范式）：逐行 key 会在文件被拆件 /
+ *   行号漂移时产生假红；棘轮要防的是「永远迁不完」⇒ 总量 + 逐文件只减不增是完整的。
+ *   ⚠️ 本棘轮**只管可见加载文案**（`/加载[^"'`\n]{0,8}(中|…)/`），不含布尔门控与 `busy` 状态本身。
+ *
+ * ★ 扫描口径（与 `tmp/scan-callsites.mjs` 同源；口径本身是判据的一部分）
+ *   ① 域 = `app/src/**` 的 `.ts`/`.tsx` 减 `*.test.ts(x)` 减 `ui/primitives/**` 减 `ui/icons/**`
+ *      （原语层就是"加载态该去哪儿"的答案，不是待收敛的重复调用点）；
+ *   ② **先剥注释**（`//` 与块注释抹为等长空白）；字符串/模板字面量**只跳过、不抹内容**
+ *      （判据读的就是字符串里的用户可见文案）；
+ *   ③ 行口径：同一行多次命中只算 1 行（与 T1 的 18 行同源，保证前后读数可比）。
+ *
+ * ★ 迁移读数（T14 实施者实测，仪器 = 与守卫同源的正则扫描）
+ *   冻结时（`dev@f6dd012f`）**18 行 / 18 文件** ⇒ T14 第一提交后 **13 行 / 13 文件**。
+ *   逐文件 Δ 之和 = −5，与迁过的 5 个文件逐一对拍（每个文件 1 行 → 0 行）⇒ 机理成立。
+ *
+ * ★ 余量去向（B11 附带硬要求：切片 + 棘轮 = **中间态**，不是"五类已各自收敛成一个原语"）
+ *   ① 4 处余量（`LearningLibraryPanel` / `RetroTimeline` / `SessionDetailPanel` / `SessionListBody`）
+ *      不在 B11 切片内 ⇒ 登记给**批 5/7**，由本棘轮冻结；
+ *   ② 5 处**在切片内但本提交未迁**（`AsrConfusionPanel` / `GoalDetail` / `RefineWorkbench` /
+ *      `SecondPassPanel` / `pages/ReviewPage`）——它们同时是 T13 空态切片的成员（同文件甚至
+ *      **同一行/同一三元链**），并行窗口内改同一文件即撞车 ⇒ 按纪律让路，交 T14 的第二提交
+ *      （T13 落库后）逐处迁；本文件那时把它们的上限从 1 降到 0（棘轮只降不升）。
+ */
+export const FROZEN_LOADING_TEXT_TOTAL = 13;
+
+/**
+ * 相对 `app/src` 的路径 → 允许残留的可见加载文案**行数上限**（只许降、不许升；键不许删）。
+ *
+ * 语义：`0` = 已由原语承载（`Loading` / `Skeleton`）；`1` = 仍有一处手写文案，见 `RESIDUAL` 的理由。
+ */
+export const FROZEN_LOADING_TEXT_BY_FILE: Readonly<Record<string, number>> = {
+  // 已迁移（0 = 该文件的加载态已交给 L1 原语）
+  "components/NotePreviewView.tsx": 0,
+  "components/RefineLaunchDialog.tsx": 0,
+  "components/RefineStrategyPicker.tsx": 0,
+  "components/WebArticleView.tsx": 0,
+  "components/review/ReviewSessionPanel.tsx": 0,
+  // 残留（1 = 见 RESIDUAL 的分类与理由）
+  "components/AsrConfusionPanel.tsx": 1,
+  "components/CaptureOverlayPanel.tsx": 1,
+  "components/GoalDetail.tsx": 1,
+  "components/ImageGallery.tsx": 1,
+  "components/LearningLibraryPanel.tsx": 1,
+  "components/RefineWorkbench.tsx": 1,
+  "components/RetroTimeline.tsx": 1,
+  "components/SecondPassPanel.tsx": 1,
+  "components/SessionDetailPanel.tsx": 1,
+  "components/SessionListBody.tsx": 1,
+  "components/StructureImageSection.tsx": 1,
+  "components/WindowSelectCard.tsx": 1,
+  "pages/ReviewPage.tsx": 1,
+};
+
+/**
+ * 迁移面：这些文件的加载态**必须**由原语承载 ⇒ 判据要求「0 命中 + 含 `<Loading`/`<Skeleton`」。
+ * 少一个文件就是回潮，多一个文件要先把它在 `FROZEN_LOADING_TEXT_BY_FILE` 里降到 0。
+ */
+export const MIGRATED_FILES: readonly string[] = [
+  "components/NotePreviewView.tsx",
+  "components/RefineLaunchDialog.tsx",
+  "components/RefineStrategyPicker.tsx",
+  "components/WebArticleView.tsx",
+  "components/review/ReviewSessionPanel.tsx",
+];
+
+/** 残留命中的分类：`exception` = 原语结构上表达不了 · `button-busy` = 按钮内忙碌文案 · `backlog` = 余量/让路 */
+export type ResidualKind = "exception" | "button-busy" | "backlog";
+
+/**
+ * 允许残留的**逐文件理由**（每条都必须：理由非空 ∧ 该文件此刻**仍然命中** —— 防"僵尸豁免"：
+ * 一处被迁走却仍挂在豁免表里，下一个人就会以为它还在）。
+ */
+export const RESIDUAL: readonly { file: string; kind: ResidualKind; reason: string }[] = [
+  {
+    file: "components/CaptureOverlayPanel.tsx",
+    kind: "exception",
+    reason:
+      "B6 特殊条款未覆盖的例外：根节点 background:#000、原文案 #e5e7eb（浅字压深底）；`Loading` 的墨度权威是 `Text tone=\"ink-3\"`（深灰）⇒ 迁过去等于把对比度反转（可读性回归）。消费者只有 1 个 < B6 阈值 3 ⇒ 不改原语；行内 style 覆盖类语义被 ADR-033 §4 禁止 ⇒ 保留手写文案 + 冻结",
+  },
+  {
+    file: "components/ImageGallery.tsx",
+    kind: "button-busy",
+    reason: "该行是 `<Button variant=\"secondary\" busy={loading}>` 的**按钮文案**（`加载中…` / `⟳ 刷新`），不是独立加载态 ⇒ 已由 `Button busy` 承载（Task 14 Step 2 ③）",
+  },
+  {
+    file: "components/StructureImageSection.tsx",
+    kind: "button-busy",
+    reason: "同 ImageGallery：`<Button busy={loading}>` 的按钮文案，已由 `Button busy` 承载",
+  },
+  {
+    file: "components/WindowSelectCard.tsx",
+    kind: "button-busy",
+    reason: "原生 `<button disabled={loading}>` 的忙碌文案 ⇒ T14 改为 `<Button variant=\"ghost\" size=\"sm\" busy={loading}>`；文案仍随 loading 切换（保留可读标签），探针/aria-busy 由原语给",
+  },
+  {
+    file: "components/AsrConfusionPanel.tsx",
+    kind: "backlog",
+    reason: "在切片内但让路：该行与 T13 的空态迁移点是**同一行**（`view === null ? \"加载中…\" : \"暂无新候选…\"`）；T13 已在它的空态提交里把这条三元一并换成 `<Loading label=\"加载中…\"/>` ⇒ 待 T13 落库后由 T14 第二提交把它移到 `MIGRATED_FILES` 并把上限收紧为 0",
+  },
+  {
+    file: "components/GoalDetail.tsx",
+    kind: "backlog",
+    reason: "在切片内但让路：该文件同时是 T13 空态切片成员 ⇒ 交 T14 第二提交（目标：`Skeleton lines={3}` + `Loading`，见 `Loading.tsx:10` 点名的靶子）",
+  },
+  {
+    file: "components/RefineWorkbench.tsx",
+    kind: "backlog",
+    reason: "在切片内但让路：该文件同时是 T13 空态切片成员 ⇒ 交 T14 第二提交",
+  },
+  {
+    file: "components/SecondPassPanel.tsx",
+    kind: "backlog",
+    reason: "在切片内但让路：加载分支与 T13 的空态分支在**同一三元链**上（`:216` / `:219`）⇒ 交 T14 第二提交",
+  },
+  { file: "pages/ReviewPage.tsx", kind: "backlog", reason: "在切片内但让路：该文件同时是 T13 空态切片成员 ⇒ 交 T14 第二提交" },
+  { file: "components/LearningLibraryPanel.tsx", kind: "backlog", reason: "不在 B11 切片内 ⇒ 余量登记给批 5/7" },
+  { file: "components/RetroTimeline.tsx", kind: "backlog", reason: "不在 B11 切片内 ⇒ 余量登记给批 5/7" },
+  { file: "components/SessionDetailPanel.tsx", kind: "backlog", reason: "不在 B11 切片内 ⇒ 余量登记给批 5/7" },
+  { file: "components/SessionListBody.tsx", kind: "backlog", reason: "不在 B11 切片内 ⇒ 余量登记给批 5/7" },
+];

app/src/ui/primitives/loadingMigration.test.tsx

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+/**
+ * @ai-context `loadingMigration.test.tsx` — 批 4 T14 的**渲染级**判据（源码级棘轮见 `loadingRatchet.test.ts`）。
+ *
+ * Why 需要渲染级：棘轮只证明「文件里不再有手写加载文案」，证明不了**用户看到的是原语**。本文件对
+ * 三处已迁的形态各钉一条判据（每处各带自己的变异体，见报告）：
+ *   ① `RefineStrategyPicker` 的 label 与默认值**不同**（「策略声明加载中…」）⇒ 必须显式传，删掉就红；
+ *   ② `WebArticleView` 是「骨架 + 可读文案」成对的样板（骨架整组 `aria-hidden`，别只留骨架）；
+ *   ③ `WindowSelectCard` 的按钮内忙碌态走 `busy`（不是原生 `disabled`，也不是 `Loading`）。
+ * 另外每条都断言**根节点没有行内 style** —— ADR-033 §4 禁止用行内 style 覆盖类语义，而这三处的
+ * 旧写法正是「手写灰字 + fontSize/color 内联」。
+ *
+ * 副作用：`invoke` 与 dialog 插件全 mock（AAA；不触真实后端、不写磁盘）。
+ * 边界：jsdom **不排版、不加载样式表**（`vitest.config.ts` 的 `css` 默认 false）⇒ 判据只读 DOM
+ *   事实（类名 / 文案 / role / aria / 行内 style 的有无），不断言像素与计算样式。
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import RefineStrategyPicker from "../../components/RefineStrategyPicker";
+import WebArticleView from "../../components/WebArticleView";
+import { WindowSelectCard } from "../../components/WindowSelectCard";
+
+const invokeMock = vi.fn();
+
+vi.mock("@tauri-apps/api/core", () => ({
+  invoke: (...args: unknown[]) => invokeMock(...args),
+  convertFileSrc: (p: string) => p,
+}));
+
+vi.mock("@tauri-apps/plugin-dialog", () => ({ save: () => Promise.resolve(null) }));
+
+afterEach(() => {
+  cleanup();
+  invokeMock.mockReset();
+});
+
+/** 永不 resolve ⇒ 组件停在加载态（这就是要断言的相位） */
+const pending = (): Promise<never> => new Promise<never>(() => undefined);
+
+describe("① RefineStrategyPicker：文案与默认值不同 ⇒ 必须显式传 label（删了就红）", () => {
+  it("meta=null 时渲染原语 `Loading`：role=status + 探针 + 文案逐字 + 根节点无行内 style", () => {
+    const { container } = render(
+      <RefineStrategyPicker meta={null} value={{ presetId: "", dims: {} }} onChange={vi.fn()} />,
+    );
+    const root = container.querySelector(".ed-loading");
+    expect(root, "加载态不是 `Loading` 原语渲染的（缺 .ed-loading）").toBeTruthy();
+    expect(root?.querySelector(".ed-probe"), "原语的探针没渲染出来").toBeTruthy();
+    expect(root?.getAttribute("role"), "加载态应让辅助技术读到").toBe("status");
+    // 文案逐字：删掉 `label` 会退回原语默认「加载中…」⇒ 这条立刻红
+    expect(root?.textContent, "加载文案被改动或被默认值吃掉").toBe("策略声明加载中…");
+    // ADR-033 §4：不许用行内 style 覆盖类语义（旧写法是 fontSize:11 + color:#9ca3af）
+    expect(root?.getAttribute("style"), "加载态上出现了行内 style").toBeNull();
+    expect(screen.queryByText("加载中…"), "加载文案退化成了默认值").toBeNull();
+  });
+});
+
+describe("② WebArticleView：骨架与可读文案成对（骨架 aria-hidden，别只留骨架）", () => {
+  it("文章未到时渲染 `Loading`（逐字）+ `Skeleton`（4 条 · aria-hidden）", () => {
+    invokeMock.mockImplementation(() => pending());
+    const { container } = render(<WebArticleView sessionId={7} onToNote={vi.fn()} onRemove={vi.fn()} />);
+    const status = container.querySelector(".ed-loading");
+    expect(status?.textContent, "加载文案被改动").toBe("文章加载中…");
+    const skel = container.querySelector(".ed-skeleton");
+    expect(skel, "结构已知（来源行 + 段落块）却没渲染骨架").toBeTruthy();
+    // 骨架是纯视觉信息：整组 aria-hidden，可读语义由上面的 role=status 承载
+    expect(skel?.parentElement?.getAttribute("aria-hidden")).toBe("true");
+  });
+});
+
+describe("③ WindowSelectCard：按钮内忙碌态走 `busy`（不是原生 disabled，也不是 `Loading`）", () => {
+  it("loading=true 时刷新控件是 `.ed-btn` + aria-busy，文案仍是「加载中…」", () => {
+    const { container } = render(
+      <WindowSelectCard windows={[]} selected={null} onSelect={vi.fn()} onRefresh={vi.fn()} loading />,
+    );
+    // 打开浮层（第一颗按钮是「已选窗口」卡片）
+    const toggle = container.querySelector("button");
+    expect(toggle).toBeTruthy();
+    fireEvent.click(toggle as HTMLButtonElement);
+    return waitFor(() => {
+      const label = screen.getByText("加载中…");
+      const btn = label.closest("button");
+      expect(btn?.className, "按钮内忙碌态没走 `Button`（缺 .ed-btn）").toContain("ed-btn");
+      expect(btn?.getAttribute("aria-busy"), "`busy` 应声明 aria-busy").toBe("true");
+      expect(btn?.hasAttribute("disabled"), "原生 disabled 会把焦点丢掉 —— 忙碌态应用 `busy`").toBe(false);
+    });
+  });
+});