@orbit-work/ui 0.1.0

package/src/components/domain/office/PdfPreview/PdfPreview.stories.tsx

@@ -0,0 +1,280 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+import { BeaconSpinner } from "../../../composite/BeaconSpinner"
+import { InlineMessage } from "../../../primitives"
+import { PdfPreview } from "./index"
+
+const meta = {
+  title: "Office/PdfPreview",
+  component: PdfPreview,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof PdfPreview>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+// 本地 fixture（.storybook/public/fixtures/sample.pdf，7 页）。原来指向 "/sample.pdf"，
+// staticDirs 里根本没有这个文件，17 个 story 的 iframe 一律渲出裸 mono 的「Not Found」。
+const samplePdfUrl = "/fixtures/sample.pdf"
+/** fixture 的真实页数——翻页组的边界（首页/末页禁用）要跟真文件对得上。 */
+const samplePdfPages = 7
+
+export const Default: Story = {
+  args: {
+    src: samplePdfUrl,
+    fileName: "sample-document.pdf",
+    totalPages: samplePdfPages,
+  },
+}
+
+export const WithPageNavigation: Story = {
+  render: () => {
+    const [page, setPage] = useState(1)
+    return (
+      <PdfPreview
+        src={samplePdfUrl}
+        fileName="multi-page-doc.pdf"
+        page={page}
+        onPageChange={setPage}
+        totalPages={samplePdfPages}
+      />
+    )
+  },
+}
+
+export const LongFileName: Story = {
+  args: {
+    src: samplePdfUrl,
+    fileName: "2024-Q4-财务报告-最终版本-审计通过-v3.2-final.pdf",
+    totalPages: samplePdfPages,
+  },
+}
+
+export const NoFileName: Story = {
+  args: {
+    src: samplePdfUrl,
+    totalPages: samplePdfPages,
+  },
+}
+
+export const WithPagination: Story = {
+  render: () => {
+    const [page, setPage] = useState(3)
+    return (
+      <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
+        <div style={{ color: "var(--ow-text-2)", fontSize: "var(--ow-fs-body)" }}>当前页: {page}</div>
+        <PdfPreview
+          src={samplePdfUrl}
+          fileName="annual-report-2024.pdf"
+          page={page}
+          onPageChange={setPage}
+          totalPages={samplePdfPages}
+        />
+      </div>
+    )
+  },
+}
+
+export const FirstPage: Story = {
+  render: () => {
+    const [page, setPage] = useState(1)
+    return (
+      <PdfPreview
+        src={samplePdfUrl}
+        fileName="user-manual.pdf"
+        page={page}
+        onPageChange={setPage}
+        totalPages={samplePdfPages}
+      />
+    )
+  },
+}
+
+export const LastPage: Story = {
+  render: () => {
+    const [page, setPage] = useState(samplePdfPages)
+    return (
+      <PdfPreview
+        src={samplePdfUrl}
+        fileName="user-manual.pdf"
+        page={page}
+        onPageChange={setPage}
+        totalPages={samplePdfPages}
+      />
+    )
+  },
+}
+
+export const SinglePage: Story = {
+  args: {
+    src: samplePdfUrl,
+    fileName: "quick-guide.pdf",
+    totalPages: 1,
+  },
+}
+
+export const NoPagination: Story = {
+  args: {
+    src: samplePdfUrl,
+    fileName: "simple-doc.pdf",
+  },
+}
+
+export const NoSource: Story = {
+  args: {
+    fileName: "not-loaded.pdf",
+    totalPages: 5,
+  },
+}
+
+export const CustomLoading: Story = {
+  args: {
+    fileName: "loading-doc.pdf",
+    totalPages: samplePdfPages,
+    loading: (
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: 12,
+          color: "var(--ow-text-2)",
+        }}
+      >
+        {/* §9 旋转圈退役：原是手搓 3px 描边环自转 1s、断口色取 --ow-primary（行动极落点，
+            暗档即荧黄）。改挂锁定件 BeaconSpinner size=40 → 完整信标，加载态占状态极·限一处，
+            下面「正在加载」一句出 R1 文字编码。 */}
+        <BeaconSpinner size={40} aria-label="正在加载 PDF 文件" />
+        <p>正在加载 PDF 文件...</p>
+      </div>
+    ),
+  },
+}
+
+/**
+ * 错误态（受控）：`error` 传一句人话即进错误态，组件包成 error tint 三件套。
+ * iframe 不派发 error 事件，这条受控入口是错误态唯一可达路径（见 PdfPreviewProps.error）。
+ */
+export const ErrorState: Story = {
+  args: {
+    src: "https://invalid-url.example.com/file.pdf",
+    fileName: "broken-file.pdf",
+    totalPages: 1,
+    error: "这个 PDF 没能打开，文件可能损坏或已经不在了。",
+  },
+}
+
+/** 自绘错误内容：`error` 传 ReactNode 时组件原样渲，仍应走 InlineMessage 三件套语法。 */
+export const CustomError: Story = {
+  args: {
+    src: "https://invalid-url.example.com/file.pdf",
+    fileName: "broken-file.pdf",
+    totalPages: 1,
+    // §6 错误态＝InlineMessage error tint 三件套（人话一句 ＋ 折叠 mono 详情）。
+    // 原来这里是手搓的 48px 红叉圆 ＋ 死值字号，属判断表退役写法。
+    error: (
+      <InlineMessage variant="error" detail="HTTP 404 Not Found · https://invalid-url.example.com/file.pdf">
+        这个 PDF 没取到，检查一下文件地址还在不在。
+      </InlineMessage>
+    ),
+  },
+}
+
+export const ConstrainedWidth: Story = {
+  render: () => {
+    const [page, setPage] = useState(1)
+    return (
+      <div style={{ maxWidth: 600, margin: "0 auto" }}>
+        <PdfPreview
+          src={samplePdfUrl}
+          fileName="narrow-preview.pdf"
+          page={page}
+          onPageChange={setPage}
+          totalPages={samplePdfPages}
+        />
+      </div>
+    )
+  },
+}
+
+export const FullHeight: Story = {
+  render: () => {
+    const [page, setPage] = useState(1)
+    return (
+      <div style={{ height: 600 }}>
+        <PdfPreview
+          src={samplePdfUrl}
+          fileName="tall-preview.pdf"
+          page={page}
+          onPageChange={setPage}
+          totalPages={samplePdfPages}
+          style={{ height: "100%" }}
+        />
+      </div>
+    )
+  },
+}
+
+export const WithCustomContent: Story = {
+  render: () => {
+    const [page, setPage] = useState(1)
+    return (
+      <PdfPreview
+        src={samplePdfUrl}
+        fileName="annotated.pdf"
+        page={page}
+        onPageChange={setPage}
+        totalPages={samplePdfPages}
+      >
+        <div
+          style={{
+            position: "absolute",
+            top: 80,
+            right: 20,
+            background: "var(--ow-surface)",
+            border: "1px solid var(--ow-border)",
+            borderRadius: 8,
+            padding: 12,
+            boxShadow: "0 2px 8px rgba(0, 0, 0, 0.1)",
+          }}
+        >
+          <div style={{ fontSize: 12, color: "var(--ow-text-3)", marginBottom: 4 }}>注释</div>
+          <div style={{ fontSize: 14, color: "var(--ow-text)" }}>此页面包含重要信息</div>
+        </div>
+      </PdfPreview>
+    )
+  },
+}
+
+export const MultipleDocuments: Story = {
+  render: () => {
+    const [doc1Page, setDoc1Page] = useState(1)
+    const [doc2Page, setDoc2Page] = useState(3)
+
+    return (
+      <div style={{ display: "flex", gap: 24, flexWrap: "wrap" }}>
+        <div style={{ flex: "1 1 400px" }}>
+          <PdfPreview
+            src={samplePdfUrl}
+            fileName="contract.pdf"
+            page={doc1Page}
+            onPageChange={setDoc1Page}
+            totalPages={samplePdfPages}
+          />
+        </div>
+        <div style={{ flex: "1 1 400px" }}>
+          <PdfPreview
+            src={samplePdfUrl}
+            fileName="invoice.pdf"
+            page={doc2Page}
+            onPageChange={setDoc2Page}
+            totalPages={samplePdfPages}
+          />
+        </div>
+      </div>
+    )
+  },
+}

package/src/components/domain/office/PdfPreview/PdfPreviewDialog.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { PdfPreviewDialog } from "./PdfPreviewDialog"
+
+// 本地 fixture（.storybook/public/fixtures/sample.pdf，7 页）。原来两个内容 story 传 src:""，
+// 走的是 PdfPreview 的空态分支，注释里写的「适配器出翻页组与 iframe」一格都没渲出来。
+const samplePdfUrl = "/fixtures/sample.pdf"
+const samplePdfPages = 7
+
+const meta = {
+  title: "Preview/PdfPreviewDialog",
+  component: PdfPreviewDialog,
+  parameters: { layout: "fullscreen" },
+  tags: ["autodocs"],
+} satisfies Meta<typeof PdfPreviewDialog>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** 常规：壳出标题栏（文件名 mono ＋ 页码读数 ＋ 翻页箭头 ＋ 下载/打开方式）；适配器只出 iframe。 */
+export const Default: Story = {
+  args: {
+    open: true,
+    fileName: "2026-Q3-设计系统验收.pdf",
+    page: 3,
+    totalPages: samplePdfPages,
+    src: samplePdfUrl,
+    onClose: () => {},
+    onDownload: () => {},
+  },
+}
+
+/** 加载中：三态由壳承担，适配器不重造。 */
+export const Loading: Story = {
+  args: {
+    open: true,
+    fileName: "2026-Q3-设计系统验收.pdf",
+    loading: true,
+    onClose: () => {},
+  },
+}
+
+/** 打不开：一句人话 ＋ mono 详情。 */
+export const LoadFailed: Story = {
+  args: {
+    open: true,
+    fileName: "损坏的文件.pdf",
+    error: "这个 PDF 没能打开，文件可能损坏了。",
+    errorDetail: "InvalidPDFException: Invalid PDF structure at byte 0",
+    onClose: () => {},
+  },
+}
+
+/** 单页文档：没有总页数就不出翻页组，标题栏也不带页码读数。 */
+export const SinglePage: Story = {
+  args: {
+    open: true,
+    fileName: "邀请函.pdf",
+    src: samplePdfUrl,
+    onClose: () => {},
+  },
+}

package/src/components/domain/office/PdfPreview/PdfPreviewDialog.tsx

@@ -0,0 +1,61 @@
+"use client"
+
+import { type ReactNode, useState } from "react"
+import { FilePreviewDialog, type FilePreviewDialogProps } from "../../files/PreviewDialog"
+import { PdfPageNav, PdfPreview, type PdfPreviewProps } from "./index"
+
+/**
+ * PdfPreviewDialog —— PDF 适配器 ×「PreviewDialog 壳」的现成组合
+ * （蓝图批次④：`PreviewDialog 壳 + Code/Csv/Image/Markdown/Office/Pdf 适配器`）。
+ *
+ * 分工同 OfficePreviewDialog：壳出模态立面、标题栏文件名读数与动作组、载/错/空三态；
+ * 适配器（`chrome={false}`）只出内容。壳标题栏右侧的 `meta` 默认接上
+ * 「当前页 / 总页数」读数（§7 mono＋tabular-nums 由壳承担），翻页箭头 `PdfPageNav`
+ * 挂进壳的 `actions` 槽与读数同行——一屏只留 48 标题栏这一条横带。
+ *
+ * 衬底走 `plain`：PDF 由 iframe 内的系统阅读器自绘纸面，壳不再叠 `paper`。
+ *
+ * 继承自：PdfPreview（原自带卡片立面与文件名标题行的独立预览）。
+ */
+export type PdfPreviewDialogProps = Omit<FilePreviewDialogProps, "children" | "surface"> &
+  Pick<PdfPreviewProps, "src" | "page" | "onPageChange" | "totalPages">
+
+export function PdfPreviewDialog({
+  src,
+  page,
+  onPageChange,
+  totalPages,
+  meta,
+  actions,
+  ...shell
+}: PdfPreviewDialogProps) {
+  // 翻页搬进壳的 actions 槽后，页码状态就归壳这一层管（page 受控时以受控值为准）。
+  const [innerPage, setInnerPage] = useState(page ?? 1)
+  const activePage = page ?? innerPage
+  const handlePageChange = (next: number) => {
+    if (next < 1 || (totalPages && next > totalPages)) return
+    setInnerPage(next)
+    onPageChange?.(next)
+  }
+  const nav: ReactNode = totalPages ? (
+    <PdfPageNav page={activePage} totalPages={totalPages} onPageChange={handlePageChange} />
+  ) : null
+
+  return (
+    <FilePreviewDialog
+      {...shell}
+      meta={meta ?? (totalPages ? `${activePage} / ${totalPages}` : undefined)}
+      actions={
+        nav || actions ? (
+          <>
+            {nav}
+            {actions}
+          </>
+        ) : undefined
+      }
+      surface="plain"
+    >
+      <PdfPreview chrome={false} src={src} page={activePage} fileName={shell.fileName} />
+    </FilePreviewDialog>
+  )
+}

package/src/components/domain/office/PdfPreview/PdfPreviewSource.test.mjs

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const source = await readFile(new URL("./index.tsx", import.meta.url), "utf8")
+const dialog = await readFile(new URL("./PdfPreviewDialog.tsx", import.meta.url), "utf8")
+
+// 判断表「空态：灰字居中 → G5」。三态原来共用一个 text-3 灰字居中的 div，
+// 错误态还自画了一枚 --ow-error 的 32px 惊叹圆——母题唯一语汇是信标。
+test("§6 容器三态：空＝EmptyState 母题 / 错＝InlineMessage error tint", () => {
+  assert.match(source, /import \{ Button, EmptyState, InlineMessage \} from "\.\.\/\.\.\/\.\.\/primitives"/)
+  assert.match(source, /data-ow-part="empty"[\s\S]*?<EmptyState message="暂无 PDF 文件" \/>/)
+  assert.match(source, /data-ow-part="error"[\s\S]*?<InlineMessage variant="error">/)
+})
+
+test("自画的惊叹圆母题与灰字居中容器整块退场", () => {
+  assert.doesNotMatch(source, /className="text-ow-error"/)
+  assert.doesNotMatch(source, /<line x1="12" y1="16" x2="12\.01" y2="16" \/>/)
+  assert.doesNotMatch(source, /p-8 text-ow-text-3 font-normal/)
+})
+
+// R2：loading 原来挂在 empty 槽（`{loading ?? <EmptyState/>}`），src 一存在就永远不可达。
+// §6 三态各有各的出口：错 → 载 → 内容 → 空 四支互斥。
+test("载态是独立一态，不再寄居 empty 槽", () => {
+  assert.doesNotMatch(source, /\{loading \?\? <EmptyState/)
+  assert.match(source, /\) : loading \? \([\s\S]*?data-ow-part="loading"/)
+  assert.match(source, /data-ow-part="empty"[\s\S]*?<EmptyState message="暂无 PDF 文件" \/>/)
+})
+
+// W5：iframe 的原生 error 事件不进 React 合成事件系统，内建 hasError 分支不可达。
+// error 升级为受控入口（可选属性，非破坏）：传非 null 即进错误态；string 由组件
+// 包成 InlineMessage error tint 三件套，ReactNode 原样渲，hasError 保留为兜底。
+test("error 是受控错误态入口，且 JSDoc 记下 iframe 不派发 error 的缘由", () => {
+  assert.match(source, /error\?: ReactNode \| string/)
+  assert.match(source, /const errored = error != null \|\| hasError/)
+  assert.match(source, /typeof error === "string" \? <InlineMessage variant="error">\{error\}<\/InlineMessage>/)
+  assert.match(source, /\{errored \? \(/)
+  assert.match(source, /\{errorBody \?\? <InlineMessage variant="error">/)
+  assert.match(source, /React 18 不把[\s\S]*?iframe 的原生 `error` 事件/)
+})
+
+// 壳语法（chrome={false}）下标题栏 meta 已出「当前页 / 总页数」，适配器再出一份
+// 就是同一读数一屏渲两遍。读数归壳，箭头留适配器。
+test("页码读数只渲一遍：读数归壳的 meta，箭头挂壳的 actions 槽", () => {
+  // 翻页组单独导出，chrome=false 时适配器整条 header 不渲（不为两枚箭头单开 40 高空条）。
+  assert.match(source, /export function PdfPageNav\(/)
+  assert.match(source, /\{chrome && \(\s*<div\s*data-ow-part="header"/)
+  assert.match(source, /showReadout && \(\s*<span\s*data-ow-part="page-info"/)
+  assert.match(dialog, /meta=\{meta \?\? \(totalPages \? `\$\{activePage\} \/ \$\{totalPages\}` : undefined\)\}/)
+  assert.match(dialog, /<PdfPageNav page=\{activePage\}/)
+  assert.match(dialog, /<PdfPreview chrome=\{false\}/)
+})
+
+// ── W5 残留清扫：控件高 ＋ 图标语系 ──
+
+test("§7 控件高：header 条高钉 --ow-h-lg(40)，不再用 py-2.5 撑出 44", () => {
+  assert.match(source, /data-ow-part="header"[\s\S]*?style=\{\{ height: "var\(--ow-h-lg\)" \}\}/)
+  assert.doesNotMatch(source, /py-2\.5 px-3\.5/)
+})
+
+test("§7 图标语系单一：文件标与左右翻页并入 composite/Icons 族", () => {
+  assert.match(source, /import \{ ChevLeft, ChevRight, Memo \} from "\.\.\/\.\.\/\.\.\/composite\/Icons"/)
+  assert.match(source, /<Memo className="text-ow-text-3 flex-shrink-0" width=\{16\} height=\{16\} \/>/)
+  // 图标一律走 Button 的 icon 槽（children 落 label 槽拿不到尺寸，会渲成 0×0）
+  assert.match(source, /icon=\{<ChevLeft width=\{14\} height=\{14\} \/>\}/)
+  assert.match(source, /icon=\{<ChevRight width=\{14\} height=\{14\} \/>\}/)
+  // 文件内手绘的 24 网格 svg 整族退场
+  assert.doesNotMatch(source, /viewBox="0 0 24 24"/)
+  assert.doesNotMatch(source, /<polyline points="15 18 9 12 15 6" \/>/)
+})

package/src/components/domain/office/PdfPreview/index.tsx

@@ -0,0 +1,217 @@
+"use client"
+
+import { useState } from "react"
+import type { ComponentProps, ReactNode } from "react"
+import { cn } from "../../../../lib/utils"
+import { ChevLeft, ChevRight, Memo } from "../../../composite/Icons"
+import { Button, EmptyState, InlineMessage } from "../../../primitives"
+
+// ─── PdfPreview ───
+
+/**
+ * PdfPreview —— 04 预览域的 PDF 适配器。
+ *
+ * 归口口径（蓝图批次④「PreviewDialog 壳 ＋ 各适配器」）：坐进 `FilePreviewDialog`
+ * 时传 `chrome={false}`，交出自绘的卡片立面与文件名标题行——壳的标题栏已经承担
+ * 文件名（mono＋tabular-nums）与动作组；「当前页 / 总页数」**读数**归壳的 `meta`，
+ * 翻页箭头（`PdfPageNav`，单独导出）由壳挂进标题栏 `actions` 槽——适配器不再为
+ * 两枚箭头单开一条 40 高的空横带。开箱即用的组合见同目录 `PdfPreviewDialog`。
+ *
+ * 衬底制式：`plain`。PDF 由 iframe 内的系统阅读器自绘纸面与工具条，壳再叠一层
+ * `paper` 会出现纸中纸。R3 中性件：无信标/荧黄元素；页码读数按 §7 走 mono＋tabular-nums。
+ */
+export type PdfPreviewProps = ComponentProps<"div"> & {
+  /** PDF 文件 URL */
+  src?: string
+  /**
+   * 自绘立面与文件名标题行。坐进 `FilePreviewDialog` 壳时传 `false`：
+   * 壳已给了模态立面与文件名，适配器再画一层就成了双边框双标题。默认 `true`。
+   */
+  chrome?: boolean
+  /** 当前页码（受控） */
+  page?: number
+  /** 页码变化回调 */
+  onPageChange?: (page: number) => void
+  /** 总页数（外部传入，用于分页显示） */
+  totalPages?: number
+  /**
+   * 自定义加载指示器；传非空即进**载态**（§6 三态里独立的一态，与空态互斥）。
+   * 取文件的那一层知道自己在载，适配器不自测——和 `error` 走同一条受控路。
+   */
+  loading?: ReactNode
+  /**
+   * 错误态入口（受控）：传非 `null`/`undefined` 即进错误态。
+   *
+   * 传 `string`＝人话一句，组件替你包成 `InlineMessage variant="error"`（error tint
+   * 三件套）；传 `ReactNode`＝整块错误内容自绘，组件原样渲。传 `null`/不传＝无错误。
+   *
+   * 为什么必须受控：PDF 由 `<iframe>` 内的系统阅读器自绘，而 React 18 不把
+   * iframe 的原生 `error` 事件冒泡进合成事件系统，`onError` 在实践中永不触发
+   * ——组件内建的 `hasError` 分支因此不可达，错误只有调用方（取文件的那一层）
+   * 知道。壳 `FilePreviewDialog` 的 `error`/`errorDetail` 走的也是这条受控路。
+   * 内建 `onError` 仍留作兜底，能触发就当作 `error` 未传时的默认错误文案。
+   */
+  error?: ReactNode | string
+  /** 标题栏显示名称 */
+  fileName?: string
+}
+
+export function PdfPreview({
+  className = "",
+  src,
+  page,
+  onPageChange,
+  totalPages,
+  loading,
+  error,
+  fileName,
+  chrome = true,
+  children,
+  ...props
+}: PdfPreviewProps) {
+  const [currentPage, setCurrentPage] = useState(page ?? 1)
+  const [hasError, setHasError] = useState(false)
+
+  // 受控优先：调用方给了 error 就进错误态，iframe onError 只是兜底（见 error 的 JSDoc）。
+  const errored = error != null || hasError
+  const errorBody = typeof error === "string" ? <InlineMessage variant="error">{error}</InlineMessage> : (error ?? null)
+
+  const activePage = page ?? currentPage
+  const handlePageChange = (newPage: number) => {
+    if (newPage < 1 || (totalPages && newPage > totalPages)) return
+    setCurrentPage(newPage)
+    onPageChange?.(newPage)
+  }
+
+  return (
+    <div
+      data-slot="pdf-preview"
+      data-ow-chrome={chrome ? undefined : "none"}
+      className={cn(
+        "flex flex-col w-full h-full bg-ow-bg overflow-hidden",
+        // 坐进 PreviewDialog 壳时不再自绘立面（§5 一件事只有一层边）
+        chrome && "[border-radius:var(--ow-radius-card)] border border-ow-border-strong",
+        className,
+      )}
+      {...props}
+    >
+      {/* Header —— 壳语法下只保留翻页组：文件名由 FilePreviewDialog 标题栏承担 */}
+      {chrome && (
+        <div
+          data-ow-part="header"
+          /* §7 控件高：条高钉 --ow-h-lg(40)，不再用 py-2.5 撑出 44（同簇 WebPreviewShell 同口径）。 */
+          className="flex items-center justify-between px-3.5 border-b border-ow-border flex-shrink-0"
+          style={{ height: "var(--ow-h-lg)" }}
+        >
+          <div
+            data-ow-part="filename"
+            className="flex items-center gap-2 font-medium text-ow-fs-ui leading-none text-ow-text"
+          >
+            <Memo className="text-ow-text-3 flex-shrink-0" width={16} height={16} />
+            <span className="font-[family-name:var(--ow-font-mono)] [font-variant-numeric:tabular-nums]">
+              {fileName || "Document.pdf"}
+            </span>
+          </div>
+          {totalPages ? (
+            <PdfPageNav page={activePage} totalPages={totalPages} onPageChange={handlePageChange} showReadout />
+          ) : null}
+        </div>
+      )}
+
+      {/* Body */}
+      <div data-ow-part="body" className="flex-1 min-h-0 relative flex items-center justify-center">
+        {/* §6 容器三态：空＝EmptyState 信标母题（G5）· 错＝InlineMessage error tint 三件套。
+            原来三态共用 text-3 灰字居中的 div，错误态还自画了一枚 --ow-error 的 32px 惊叹圆
+            ——判断表「空态：灰字居中 → G5」，母题唯一语汇是信标，错误语义交给 tint 三件套。 */}
+        {errored ? (
+          <div data-ow-part="error" className="flex w-full max-w-[560px] flex-col p-8">
+            {errorBody ?? <InlineMessage variant="error">这个 PDF 没能打开，文件可能损坏或已经不在了。</InlineMessage>}
+          </div>
+        ) : loading ? (
+          /* 载态是独立的第三态：原来 loading 挂在 empty 槽里，src 一旦存在就永远出不来
+             （错→载→内容→空 四支互斥，§6 三态各有各的出口）。 */
+          <div
+            data-ow-part="loading"
+            role="status"
+            aria-live="polite"
+            className="flex w-full items-center justify-center p-8"
+          >
+            {loading}
+          </div>
+        ) : src ? (
+          <iframe
+            data-ow-part="iframe"
+            className="w-full h-full border-0 block"
+            src={`${src}#page=${activePage}`}
+            title={fileName || "PDF Preview"}
+            onError={() => setHasError(true)}
+          />
+        ) : (
+          <div data-ow-part="empty" className="flex w-full items-center justify-center p-8">
+            <EmptyState message="暂无 PDF 文件" />
+          </div>
+        )}
+        {children}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * 翻页组（左右箭头 ＋ 可选 mono 读数）。单独导出，好让「壳语法」下的调用方
+ * （`PdfPreviewDialog`）把它挂进壳标题栏的 `actions` 槽——chrome={false} 时
+ * 适配器不再为两枚箭头单开一条 40 高的空横带（一屏两条横带只装两个箭头）。
+ */
+export function PdfPageNav({
+  page,
+  totalPages,
+  onPageChange,
+  showReadout = false,
+}: {
+  page: number
+  totalPages: number
+  onPageChange: (page: number) => void
+  /** 出「当前页 / 总页数」读数；坐进壳里时读数归壳的 meta，这里传 false。 */
+  showReadout?: boolean
+}) {
+  const btn =
+    "w-7 h-7 p-0 text-[color:var(--ow-text-3)] hover:text-[color:var(--ow-text)] disabled:text-[color:var(--ow-disabled-text)] disabled:bg-transparent"
+  return (
+    <div data-ow-part="pagination" className="flex items-center gap-1">
+      <Button
+        data-ow-part="page-btn"
+        type="button"
+        variant="ghost"
+        size="sm"
+        className={btn}
+        icon={<ChevLeft width={14} height={14} />}
+        disabled={page <= 1}
+        onClick={() => onPageChange(page - 1)}
+        aria-label="上一页"
+        title="上一页"
+      />
+      {/* 读数只渲一遍：坐进 PreviewDialog 壳（chrome={false}）时标题栏的 meta 已经出了
+          「当前页 / 总页数」，适配器再出一份就是同一读数在一屏里出现两次。 */}
+      {showReadout && (
+        <span
+          data-ow-part="page-info"
+          className="font-normal text-ow-fs-caption leading-none font-[family-name:var(--ow-font-mono)] [font-variant-numeric:tabular-nums] text-ow-text-2 min-w-12 text-center"
+        >
+          {page} / {totalPages}
+        </span>
+      )}
+      <Button
+        data-ow-part="page-btn"
+        type="button"
+        variant="ghost"
+        size="sm"
+        className={btn}
+        icon={<ChevRight width={14} height={14} />}
+        disabled={page >= totalPages}
+        onClick={() => onPageChange(page + 1)}
+        aria-label="下一页"
+        title="下一页"
+      />
+    </div>
+  )
+}