dsh-data-domain-knowledge 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/client/PreviewSections.tsx

@@ -1,19 +1,32 @@
 /**
- * 预览抽屉的三个公共分块（0035）：**元信息 → 内容 → 版本**。
+ * 预览抽屉的公共分块（0035 起）：**元信息 → 内容 → 版本**。
  *
  * SourceRaw 的原文预览与 wiki 卡片的预览必须是**同一种形态**。两处各写一遍结构，
  * 就会出现「一个把元信息放最上面、一个放最下面」「一个能给文本预览、另一个不能」
  * 这类漂移 —— 而它们回答的是同一个问题：这份东西是什么、写了什么、改过几次。
  *
- * 这一层只定义**顺序与分块**（小节标题 + 计数 + 内容），字段仍由调用方给：原文有
+ * 这一层只定义**顺序与分块**（小节头 + 计数 + 内容），字段仍由调用方给：原文有
  * `content_hash`，卡片有 `entity_id`，本来就不一样，硬凑成同一张表只会两处都别扭。
  * 时间也由调用方格式化（见 `format.ts`）—— 元信息用标准格式，列表行用紧凑格式。
+ *
+ * 0042 重排了三件事，理由都是「三种层级要一眼分得开」：
+ *
+ * 1. **小节头换了字号**（`drawerSubHead` 13px/700，上加分隔线）。此前小节头是
+ *    12px/700、正文 12px/400 —— 同字号只差一个字重，于是「内容」两个字和它下面的
+ *    正文在视觉上是同一段文字的第 0 行与第 1 行。
+ * 2. **视图切换离开小节头那一行。** 它被压到 20px 高站在 12px 的小节标题旁边，与
+ *    小节名、字符数、（曾经的）出口按钮四种东西共享一行。现在它有自己的「读法工具栏」。
+ * 3. **正文块锁高度、自己滚。** 此前整条抽屉体是一根长滚动条：正文有多长，「版本」
+ *    就被推到多远，而版本是要动手的地方（回滚）。现在正文块有上限、块内滚动，
+ *    下面的分块位置不再随正文长度漂移。
  */
 
-import { useState, type ReactNode } from 'react'
-import { FileCode2, FileText, History, Image, ListTree } from '@tita-data-agent/ui/icons'
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@tita-data-agent/ui/components'
+import { useMemo, useState, type ReactNode } from 'react'
+import { ChevronDown, ChevronUp, FileCode2, FileText, GitBranch, History, ListTree } from '@tita-data-agent/ui/icons'
+import { Button, Tabs, TabsContent, TabsList, TabsTrigger, cn } from '@tita-data-agent/ui/components'
 import { VersionManager, type VersionManagerProps } from '@tita-data-agent/ui/versions'
+import { DrawerSectionHead } from './DrawerSection.tsx'
+import { pathImagesOf, referencedRelsOf } from './asset-images.ts'
 // 平台提供的 Markdown 原子（DSH 的模块表里有它，本插件的 client bundle 也已把它列为
 // external）。原文与卡片正文本身就是 Markdown，用 `<pre>` 显示等于把标题、表格、链接
 // 全都拍平成源码 —— 所以默认阅读态走它，源码视图是**另一个**选项，不是替代品。
@@ -35,27 +48,35 @@ const MARKDOWN_LABELS: MarkdownLabels = {
   footnotes: '脚注',
 }
 
-/** 正文只渲染前 2 万字符：更长的原文在抽屉里没有阅读意义，也会拖慢 Markdown 渲染。 */
-const PREVIEW_CHARS = 20000
+/**
+ * 正文在抽屉里最多渲染这么多字符。**与服务端 `SOURCE_PREVIEW_CHARS` 同值。**
+ *
+ * 服务端在传输层就把原文封顶了，前端再取同一个数，是为了让「界面上写出来的那个数」
+ * 与「服务端封顶的那个数」不可能是两个：0042 之前客户端另有一个 20000，
+ * 于是同一份材料有两个上限，而界面上一个都没写。
+ *
+ * wiki 卡片没有独立整页出口，所以卡片正文超过它时给**本地展开**（见 `PreviewContent`
+ * 的「展开全部」），不是只截断不给出路。
+ */
+const PREVIEW_CHARS = 4000
 
 export interface PreviewRow {
   label: string
   value: ReactNode
   /** 等宽显示：hash / id / 路径这类要逐字比对的值。 */
   code?: boolean
+  /** 悬停说明。**必须渲染出来** —— 否则调用方写了它、界面上什么也没有。 */
+  title?: string
 }
 
 /** 元信息：一张两列的事实表。标签列宽固定，所以标签要短且彼此对齐。 */
 export function PreviewMeta({ rows }: { rows: PreviewRow[] }): ReactNode {
-  // 每一块都包一层 `drawerSection`：标题与它自己的内容是一块，块与块之间的间距由
-  // 外层 `drawerStack` 给。不包的话「元信息」标题和它下面那张表是两个同级节点，
-  // 外层 gap 会把标题和自己的表也拉开。
   return <section className={styles.drawerSection}>
-    <div className={styles.kbSubHead}><h4><ListTree size={13} />元信息</h4></div>
+    <DrawerSectionHead icon={<ListTree size={13} />} title="元信息" />
     <dl className={styles.kbKv}>
       {rows.map(row => <div key={row.label}>
         <dt>{row.label}</dt>
-        <dd className={row.code ? styles.kbCode : undefined}>{row.value}</dd>
+        <dd className={row.code ? styles.kbCode : undefined} {...(row.title ? { title: row.title } : {})}>{row.value}</dd>
       </div>)}
     </dl>
   </section>
@@ -64,52 +85,166 @@ export function PreviewMeta({ rows }: { rows: PreviewRow[] }): ReactNode {
 export interface PreviewAsset { rel: string; url: string; bytes: number }
 
 /**
- * 内容：小节标题 + 视图切换 + 正文。
+ * 内容：小节头 + 读法工具栏 + 正文（锁高内滚）+ 正文没提到的图。
  *
  * 两个视图是**同一份内容**的两种读法：Markdown 是阅读态（默认），文本是源码态，
  * 用于逐字核对 —— 与版本 diff 是同一种读法。切换不重新取数，也不改内容。
- * 图片素材排在这一块的末尾：它也是内容，只是渲染器没能就地展开的那部分。
+ *
+ * **图片与正文是一份内容，不是一个附件区**（0049）。此前末尾另起一块「图片素材」
+ * 网格：正文里的图已经就地渲染过一遍，末尾再排一遍，同一张图一屏里出现两次。
+ * 现在只有一份读法 —— 正文里提到过的图就地渲染，**没提到的排在正文末尾**，
+ * 都在同一个滚动容器里。独立整页也是这么读的（它靠 `resolveImage` 就地渲染）。
+ *
+ * **正文里的图要就地显示**（0047）：`MarkdownText` 的 `pathImages` 拿 `assets` 把
+ * 相对引用换成 `/knowledge/assets/...`。不接它的话，浏览器会按当前页面地址去解析
+ * `_assets/<bucket>/img-x.png`（结果是 `/_assets/...` 404），于是「预览里看不到图」。
+ *
+ * `totalChars` 说全文有多少字符（服务端按 `SOURCE_PREVIEW_CHARS` 封顶，
+ * `content.length` 已经不是全文长度了）。读全文的出口由调用方放在**小节头上**
+ * （`action`）：它是「这份东西还能去哪看」，位置要固定，不该随正文是否被截断而出现或消失。
  */
-export function PreviewContent({ content, assets = [] }: { content: string; assets?: PreviewAsset[] }): ReactNode {
+export function PreviewContent({ content, assets = [], totalChars, action }: {
+  content: string
+  assets?: PreviewAsset[]
+  /** 全文总字符数。省略时按 `content.length` 算（它本来就是全文）。 */
+  totalChars?: number
+  /** 小节头右侧的动作（例如「新页面打开」）。与「内容」同一行，不占正文宽度。 */
+  action?: ReactNode
+}): ReactNode {
   const [view, setView] = useState<'md' | 'text'>('md')
-  const shown = content.slice(0, PREVIEW_CHARS)
-  const clipped = shown.length < content.length
-  return <section className={styles.drawerSection}><Tabs value={view} onValueChange={next => setView(next as 'md' | 'text')}>
-    <div className={styles.kbSubHead}>
-      <h4><FileText size={13} />内容</h4>
-      <TabsList className={`${styles.tabsList} ${styles.kbViewTabs}`}>
-        <TabsTrigger value="md">Markdown</TabsTrigger>
-        <TabsTrigger value="text"><FileCode2 size={11} />文本</TabsTrigger>
-      </TabsList>
-      <span>{content.length} 字符{clipped ? ` · 只渲染前 ${shown.length}` : ''}</span>
-    </div>
-    <TabsContent value="md">
-      <div className={styles.kbMarkdown}><MarkdownText text={shown} labels={MARKDOWN_LABELS} /></div>
-    </TabsContent>
-    <TabsContent value="text">
-      <pre className={styles.kbPre}>{shown}</pre>
-    </TabsContent>
-    {assets.length > 0 && <>
-      <div className={styles.kbSubHead}><h4><Image size={13} />图片素材</h4><span>{assets.length} 张</span></div>
-      <div className={styles.kbAssets}>
-        {assets.map(asset => <figure key={asset.rel} className={styles.kbAsset}>
-          <img src={asset.url} alt={asset.rel} loading="lazy" />
-          <figcaption>{formatBytes(asset.bytes)}</figcaption>
-        </figure>)}
+  /** 卡片正文超过上限时的本地展开：卡片没有整页出口，只能在这里给出路。 */
+  const [expanded, setExpanded] = useState(false)
+  const shown = expanded ? content : content.slice(0, PREVIEW_CHARS)
+  const total = totalChars ?? content.length
+  const clipped = shown.length < total
+  const canExpand = content.length > PREVIEW_CHARS
+  /**
+   * 解析器按 `assets` 的记忆化：`MarkdownText` 是 memo 组件，每次渲染换一个新对象
+   * 会让它的流式渲染缓存整体作废（平台对这个 prop 的身份有明确要求）。
+   */
+  const pathImages = useMemo(() => pathImagesOf(assets), [assets])
+  /** 正文没提到的图：排在正文末尾，与正文同一个滚动容器。 */
+  const extra = useMemo(() => {
+    const referenced = referencedRelsOf(content, assets)
+    return assets.filter(asset => !referenced.has(asset.rel))
+  }, [content, assets])
+  return <section className={styles.drawerSection}>
+    <DrawerSectionHead icon={<FileText size={13} />} title="内容">
+      {/* 事实与动作**成组**靠右：`drawerSubHead` 是 `space-between`，三个平级子节点会
+          把「20 字符」摆到行的正中间，读起来像另一栏。 */}
+      <span className={styles.drawerHeadAside}>
+        <span className={styles.drawerHeadFact}>
+          {total} 字符{clipped ? ` · 这里显示前 ${shown.length}` : ''}{assets.length > 0 ? ` · ${assets.length} 张图` : ''}
+        </span>
+        {action}
+      </span>
+    </DrawerSectionHead>
+    {/* 读法工具栏：这个分块的**两种读法**是它自己的事，不再挤进小节标题那一行。 */}
+    <Tabs value={view} onValueChange={next => setView(next as 'md' | 'text')}>
+      <div className={styles.drawerToolbar}>
+        <TabsList className={cn(styles.tabsList, styles.kbViewTabs)}>
+          <TabsTrigger value="md">Markdown</TabsTrigger>
+          <TabsTrigger value="text"><FileCode2 size={11} />文本</TabsTrigger>
+        </TabsList>
+        {canExpand && <Button
+          variant="ghost" size="sm" className={styles.drawerMore}
+          onClick={() => setExpanded(value => !value)}
+        >{expanded ? <ChevronUp size={11} /> : <ChevronDown size={11} />}
+          {expanded ? '收起' : `展开全部（还有 ${content.length - PREVIEW_CHARS} 字符）`}</Button>}
       </div>
-    </>}
-  </Tabs></section>
+      <TabsContent value="md">
+        <div className={styles.drawerBody}>
+          <div className={styles.kbMarkdown}>
+            <MarkdownText text={shown} labels={MARKDOWN_LABELS} {...(pathImages === undefined ? {} : { pathImages })} />
+          </div>
+          {extra.length > 0 && <>
+            {/* 这块不是「另一些内容」，是**同一份内容的余下部分**：正文里没出现（或落在
+                预览长度之外）的图。写清楚它是什么，人才不会以为图丢了。 */}
+            <p className={styles.kbAssetsNote}>
+              正文里没出现的图 · {extra.length} 张{clipped ? `（正文只显示前 ${shown.length} 字符）` : ''}
+            </p>
+            <div className={styles.kbAssets}>
+            {extra.map(asset => <figure key={asset.rel} className={styles.kbAsset} title={asset.rel}>
+              {/* alt 用文件名而不是整条相对路径：图挂了的时候，`01_source_raw/_assets/…`
+                  会在 84px 的格子里折成三行，把这一块撑得比正文还高。 */}
+              <img src={asset.url} alt={asset.rel.split('/').pop() ?? asset.rel} loading="lazy" />
+              <figcaption>{formatBytes(asset.bytes)}</figcaption>
+            </figure>)}
+            </div>
+          </>}
+        </div>
+      </TabsContent>
+      <TabsContent value="text">
+        <div className={styles.drawerBody}><pre className={styles.kbPre}>{shown}</pre></div>
+      </TabsContent>
+    </Tabs>
+  </section>
+}
+
+/**
+ * 相关卡片（0049）：出链与入链，两处都是**可点的入口**。
+ *
+ * 为什么正文里已经有 `## 相关` 一块、这里还要再列一遍：正文里那一块写的是
+ * `[[类型/标题]]`，是给 `grep` 和编辑器用的**文件内引用**（面板渲染不了它，卡片也没有
+ * 自己的页面地址）；这里这几行是面板里真的能点开的东西 —— 点一下换到那张卡片。两处
+ * 的清单来自同一个计划（服务端的 `planRelated`），所以不会一处写着 A、一处列着 B。
+ *
+ * 「它引用 / 引用它」分开列，是因为方向不同：前者是这张卡片自己的判断，后者是别人
+ * 把它拉进来的。合成一列就分不清「我提到它」和「它提到我」。
+ */
+export interface RelatedLink {
+  entityId: string
+  entityType: string
+  title: string
+  reason: 'relation' | 'source'
+}
+
+const RELATED_REASON: Record<RelatedLink['reason'], string> = {
+  relation: '来源里写明的关系',
+  source: '同一份来源',
+}
+
+export function PreviewRelated({ outgoing, incoming, onOpen }: {
+  outgoing: RelatedLink[]
+  incoming: RelatedLink[]
+  onOpen: (link: RelatedLink) => void
+}): ReactNode {
+  if (outgoing.length === 0 && incoming.length === 0) return null
+  const group = (label: string, links: RelatedLink[], prefix: string): ReactNode => links.length === 0 ? null : <>
+    <p className={styles.kbRelatedGroup}>{label}</p>
+    <ul className={styles.kbRelatedList}>
+      {links.map(link => <li key={`${prefix}-${link.entityType}:${link.entityId}`}>
+        <button type="button" className={styles.kbRelatedRow} title={`${link.entityType}/${link.entityId}`} onClick={() => onOpen(link)}>
+          <span className={styles.kbRelatedTitle}>{link.title}</span>
+          <span className={styles.kbRelatedMeta}>{RELATED_REASON[link.reason]}</span>
+        </button>
+      </li>)}
+    </ul>
+  </>
+  return <section className={styles.drawerSection}>
+    <DrawerSectionHead icon={<GitBranch size={13} />} title="相关卡片">
+      <span className={styles.drawerHeadFact}>{outgoing.length + incoming.length} 条</span>
+    </DrawerSectionHead>
+    <div className={styles.kbRelated}>
+      {group('它引用', outgoing, 'out')}
+      {group('引用它', incoming, 'in')}
+    </div>
+  </section>
 }
 
 /**
- * 版本：小节标题 + 计数 + 一句「什么时候会留快照」+ 时间线。
+ * 版本：小节头 + 计数 + 一句「什么时候会留快照」+ 时间线。
  *
  * `hint` 不是可有可无的装饰：两种产物的快照触发条件不同（原文是内容变化，卡片是
  * 正文变化 —— 只改状态不造版本），不写清楚，用户会以为「我改过它，为什么没有版本」。
+ *
+ * 0042 没有把它降级成抽屉头的一枚按钮，理由有两条：它是当前**唯一**的回滚入口
+ * （`setRestoreTarget` 只在它这里被调用），而且正文块锁高之后它已经在一屏之内 ——
+ * 降级要新造一层状态，收益只是省一块高度。
  */
 export function PreviewVersions({ hint, ...manager }: { hint?: string } & VersionManagerProps): ReactNode {
   return <section className={styles.drawerSection}>
-    <div className={styles.kbSubHead}><h4><History size={13} />版本</h4><span>{manager.entries?.length ?? 0} 个</span></div>
+    <DrawerSectionHead icon={<History size={13} />} title="版本"><span className={styles.drawerHeadFact}>{manager.entries?.length ?? 0} 个</span></DrawerSectionHead>
     {hint && <p className={styles.kbHint}>{hint}</p>}
     <VersionManager {...manager} />
   </section>