图示
DiagramInspector - 检查面板
读者刚刚选中的东西，写在图旁边。
用法
什么时候用它
来自@misoto22/folio/diagrams
import { DiagramInspector } from '@misoto22/folio/diagrams'说明
读者刚刚选中的东西，写出来。
一张图里每个节点大概能装八个词，再多它就不是图、而是一份画了线的文档。超出这八个的一切——端口、归属团队、它是从哪个文件读出来的、它参与的那六条关系——都属于图旁边而不是图里面，而这里就是那个地方。
不是对话框，而且这是刻意的。检查面板是一个随选择变化的区域，不是一个模态。给它 role="dialog" 会为一个读者从未打开过的东西劫持焦点、索要关闭——他们点的是一个节点，面板是跟过来的。所以它是一个带 aria-live="polite" 的具名区域，这正是让读屏软件播报新选择、同时不把光标从读者手上的事情里抢走的做法。
关系带了 onSelect 时是真按钮，这就是这张图变得可用键盘导航的方式：读者可以一个邻居一个邻居地走完整张图，全程不碰那张画。
结构
| 部件 | 说明 |
|---|---|
| 区域必填 | 一个名为「<title> details」、带 aria-live="polite" 的 <section>，落在一块面板底上。是区域而不是对话框：没有任何东西困住焦点，也没有任何东西要求被关掉，因为读者点的是一个节点，不是打开了一扇窗。 |
| 标题必填 | 标题上方的眉标——先说这是哪一类东西，再说它叫什么。板块自己的那个引导词就该落在这个眉标里，这样面板和画面对同一个节点说的是同一句话。 |
| 事实 | 一份定义列表，一行一个词条和一个值，遇到 id、路径、端口时值可以设成等宽。是列表而不是一堆 div 摆出来的网格，因为网格不会告诉读屏软件哪个值属于哪个标签。 |
| 关系 | 节点参与的每一条边各占一行，带了 onSelect 就各自变成真按钮。箭头字形是隐藏的，方向在它旁边写成文字，所以「to」和「from」是听得见的，不用猜。 |
| 关闭 | 一个按它所做的事命名的小控件——清掉选择，不是关掉一扇窗。它是唯一能把这块面板清空的东西。 |
| 操作 | 事实下方一排会换行的、由调用方提供的按钮：复制 id，打开这个节点是从哪里读出来的那份源。 |
实践建议
推荐
- 把它和图的 onSelectNode 配起来用。正是那一下把隐藏的摘要列表变成真按钮；没有它，这块面板永远只能靠指针填满——图里的板块按设计就是纯装饰的。
- 每一条关系都要给 onSelect。这些行会变成按钮，整张图也就能一个邻居一个邻居地走下去——键盘读者正是这样从一个节点走到与它相连的那个节点，而不必再回到列表里去。
- 长的事实挪到这里来，板块上留大约八个词。一个要装端口、归属团队和文件路径的方框，会长大到把三样都装下，而不是把它们裁掉；而由这么大的方框组成的图，就是一份画了几条线的文档。
避免
- 两条共用一个标签的事实，就是两行用了同一个 key——这份列表是拿标签本身当 key 的，所以出现两次「Source」的面板得到的是一个协调 bug，而不是两行。要么给第二条另起一个名字，要么让一行同时装下两个值。
- floating 把这块面板钉在界面上方，所以只要它还挂着，就一直盖着图的那个角。它自己没有任何关闭契约——不传 onClose，读者就没有任何东西可按，那个角也一直被盖到选择发生变化为止。
示例
default
一次选择会往屏幕上放的东西：它是哪一类东西、它的名字、那些长到印不进板子里的事实，以及它参与的每一条关系，方向都写明白。它是一个带 aria-live 的具名区域，不是一个对话框——读者点的是一个节点，不是打开了一块面板，所以这里没有任何东西劫持焦点，也没有什么必须先关掉页面才重新能用。mono 是给读者可能会重新敲一遍的值用的；那些事实是一份定义列表，所以读屏软件能说清哪个值属于哪个标签。
API
FastAPI, behind the load balancer. Owns every read the cache misses.
- 8000
- ap-southeast-2
- api
- fromCloudFront
- toRedis
- toPostgres
nothing selected
这块面板自己没有空状态——title 是必填的，所以根本没法渲染一个里面什么都没有的它，而读者在挑中任何东西之前看到的是什么，归调用方去画。一定要画点什么：一根在选择被清空时就消失的列，每次有人关掉面板都会把布局的其余部分一起带走。关系那一行是一个真的按钮，因为它带着 onSelect，而正是这一点让键盘可以一个邻居一个邻居地走完整张图，全程不碰那幅画；onClose 回到那个空的情形。
Pick a component to see what it is and what reaches it.
pinned over the figure
floating 会把这块面板变成一块钉在最近的定位祖先左下角的板，所以那层容器必须自己建立一个定位上下文，否则它会把自己钉到页面更上方的某个东西上。当图形占据整个视口、而排在文档流下面的面板在最需要它的那一刻却在屏幕之外时，就把它钉住；当图形只是一篇文章里的一项时，就让它留在文档流里。activeIds 会点亮这块面板正在讲的那个节点，而两者谁也不伸手去够对方——画面和面板是同一份选择的两个消费方。actions 是「读者拿这次选择去做什么」的去处。这个区域的无障碍名称取自 title，所以一页上的两块面板绝不能检查同一个节点——这一块选的是那个数据存储，而不是第一个例子所讲的那个服务。
3 elements and 2 relationships.
- CloudFront (cloud) — CDN
- API (backend) — FastAPI
- Postgres (database)
- CloudFront → API: HTTPS
- API → Postgres: SQL
Postgres
The primary, and the end of the request path above it.
- db
- 1
无障碍
- 是一个带 aria-live="polite" 的具名区域，不是对话框：读者点的是节点，他们没有“打开”任何东西，所以焦点从不被劫持或索要。
- 关系带了 onSelect 时是真按钮，这样这张图就能用键盘一个邻居一个邻居地走下去。