跳转至

Markdown 标题链接模块契约

契约概览

领域 契约
公共契约 createMarkdownHeadingLinks(options?) 返回一个从 @astryxdesign/core/Markdown/plugins 导出的第一方条目。
行为 安装该条目后,每个渲染出的 h1–h6 都会获得一个确定性的、无冲突的 ID,并且每个内置标题都会附带一个行尾的 # 复制按钮。
最终用户影响 读者可以在不改变当前 hash、滚动位置或页面的情况下,复制持久的标题 URL 并获得即时确认;传入的 fragment URL 仍会定位到对应的标题 ID。
构建方影响 构建方显式安装一个条目,并可提供稳定的标题命名空间和安全的 URL 基础。该条目同时保持 Markdown 派生的 Outline ID 对齐且仅限根级。
兼容性 新增行为且默认关闭。没有此模块时,已发布的 Markdown/Outline 标题遍历、ID、DOM、样式以及自定义标题所有权均保持不变。
评审检查 拒绝默认开启的行为、Markdown prop、仅 Outline 的命名空间、运行时 ID、模块局部条目状态、未经验证的仿冒品、锚点/伪造链接、定制揭示逻辑、强加的自定义结构或产品形态的导航。

此表是一个评审投影;以下正文为准。

意图

发布文档的构建方应能选择使用可移植、持久的标题链接,而无需将产品身份或导航策略变成永久的 Markdown prop。该模块拥有一个完整的第一方组合:身份投影、永久链接复制按钮渲染、本地化以及跨界面证据。

兼容性与迁移

  • 已发布的默认行为保留:yes
  • 兼容性类别:新增且可选加入(opt-in)
  • 迁移决策:spec:AST-002/DEC-8
  • 现有构建方无需做任何事。希望获得全深度标题身份的构建方只需创建一个稳定条目,并将其传给 Markdown 以及同一来源的任何 Outline 派生。

所有权边界

拥有

  • createMarkdownHeadingLinks() 与 MarkdownHeadingLinksOptions。
  • 稳定的内部插件名称,以及一个冻结的、带版本号、经过结构验证的配置,该配置由不透明条目在兼容的 Core 包副本间携带。
  • NFKC Unicode slug 生成、回退、已发出 ID 的保留、命名空间组合,以及全深度后变换投影。
  • 由 Markdown 和 Markdown 派生的 Outline 共同使用的 ID、标签、经过清理的永久链接基础,以及规范复制 URL。
  • 内置同级复制按钮渲染器、useContainerReveal 组合、i18n、交互样式、Storybook 示例、SSR 证明和浏览器证据。

不拥有 / 非目标

  • Markdown 的通用插件协议、解析器、变换顺序、默认标题样式,或已发布的无插件根级标题投影。
  • Outline 的仅根级条目选择、hook API 或记忆化框架。
  • 调用方自定义 components.heading 的 DOM、样式、无障碍或永久链接 UI。
  • 产品特定的文档身份、版本化、主机 URL 构造、查看器滚动、回调或路由。

公共 API 与概念

概念 封闭值或状态 含义 默认值 所有者 稳定性
createMarkdownHeadingLinks() 一个返回 MarkdownPluginEntry<never> 的工厂函数 安装一个可移植的模块条目,兼容的 Core 副本可识别它。 缺省 module:Markdown/headingLinks 稳定
headingIdPrefix 字符串或省略 调用方拥有的稳定命名空间,以 <prefix>--<slug> 形式前置。 无前缀 调用方 稳定
permalinkBaseUrl 安全导航 URL 或省略 调用方拥有的基础 URL,其现有 fragment 会被生成的 fragment 替换。 当前文档 调用方 稳定
标题投影 缺省或已安装 缺省时使用已发布的仅根级身份;安装后使用模块拥有的全深度身份。 缺省 模块 稳定
内置复制控件 作为同级的真实 type="button" 复制规范 URL 而不进行导航,并显示对勾 1.5 秒。 缺省 模块 稳定
自定义标题渲染器 调用方替换 仅接收生成的 ID,并保留对输出的完全所有权。 内置 调用方 稳定

行为契约

ID 不变量 依据
---- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------------
FR1 工厂函数和选项类型仅通过服务端安全的 @astryxdesign/core/Markdown/plugins 入口点导出。普通的 opaque(不透明)MarkdownPluginEntry<never> 在共享的、经结构校验的 Symbol.for 协议封装内携带一个冻结且带版本的模块配置,因此兼容的 Core 副本无需模块局部身份或状态即可识别它。 spec:AST-036 FR1–FR5, DEC-11
FR2 headingIdPrefix 和 permalinkBaseUrl 仅接受字符串,并随条目一起传递。URL 基础使用 Markdown 的导航清理器,拒绝不安全的 destination,并替换任何现有 fragment。使用者只识别完全兼容的模块配置。具有不兼容模块数据的有效同名泛型插件保持普通插件顺序,但不获得标题链接行为;格式错误的泛型条目遵循现有的 Markdown/Outline 故障软化路径。直接传入无效的工厂参数仍可能抛出异常。 family:navigation-destinations
FR3 转换后,每个层级的每个标题在文档顺序中恰好参与一次。标签使用规范的扩展文本投影。slug 使用 NFKC、小写 Unicode 字母/数字、移除引号、合并连字符,以及 section。 component:Markdown FR13, FR16
FR4 每个生成的 ID 都被保留。自然数字后缀绝不会与早期生成的 ID 冲突或重新生成该 ID。 模块身份所有权
FR5 省略该模块可保留已发布的根标题 ID、嵌套标题行为、DOM、样式、Outline 结果以及自定义渲染器的所有权。 component:Markdown FR12
FR6 将同一条目传递给 Markdown 和源自 Markdown 的 Outline 会共享同一个投影。嵌套标题会占用身份标识并参与冲突处理,而 Outline 继续只选择根标题。 module:Outline/parseOutlineFromMarkdown
FR7 内置标题仍是一个语义化的 h1–h6,并增加一个名副其实的兄弟节点 type="button";自定义标题接收生成的 ID,且不会被强加包装器或控件。 component:Markdown FR2–FR3
FR8 在同步 SSR、水合、多个命名空间实例、重排以及独立渲染中,ID 都是确定性的。 模块身份所有权
FR9 公共入口保持服务器安全且可摇树优化;客户端渲染器对 Markdown 保持私有。产品标识、版本控制、滚动、回调、路由和宿主 URL 构造永远不会进入该模块。 包导出与副作用约定
FR10 未经修改的点击、轻触、Enter 或 Space 会复制规范绝对 URL,且不会发生导航、滚动或哈希变更。成功时显示对勾和本地化的礼貌式播报,持续 1.5 秒;失败时保持静默。标题行使用规范的 useContainerReveal、按行高尺寸的流式布局、稳定的逻辑末尾间距、不重叠的 24px 粗指针命中区域,以及一个仅键盘可见的焦点环。 模块交互与布局所有权

可访问性契约

  • AR1 — 标题语义保持不变。 内置控件是同级元素,因此 h1–h6 的角色/名称不包含 #;作者编写的标题链接仍然有效。自定义标题仅接收身份标识。
  • AR2 — 自定义所有权保持不变。 自定义标题仅接收身份标识,并继续负责 ID 之外的所有结构、样式和无障碍特性。
  • AR3 — 渲染器扩展使用规范的显现原语。 其复制按钮保持已挂载、已命名、在无障碍树中,并在 Tab 键顺序中,同时在精细指针静止时视觉隐藏。悬停在标题行的任何位置,或将键盘焦点移入其中,都会立即显现标记。粗指针/触摸可见性、减弱动态效果和焦点保护均遵循 useContainerReveal;模块不得添加并行的媒体查询、标记、令牌或公共显现 API。

复制按钮显现扩展契约

渲染器扩展在内置标题行(显现所有者)上展开 useContainerReveal().getContainerProps(),并在其真正的同级 type="button" 元素上展开 getContentRevealProps({isLayoutPreserved: true})。这会生成精确的可观察状态:在精细指针静止时隐藏; 悬停标题行任意部分时可见;按钮或行内其他后代获得焦点时可见; 无需 display: none 或 visibility 即可通过键盘到达;并在该 hook 现有受支持语义下,在粗指针/触摸输入时可见。 流内控件盒的块尺寸与其相邻标题行的计算值一致,因此它永远不会提高标题行高或改变换行。 在最终视觉行末尾的一个稳定逻辑内联槽位,使标题文本、控件和相邻控件在任一方向上都互不重叠;显现以及 #/对勾的切换不会改变任何行几何或间距。 在粗指针输入时,交互和焦点几何体满足 24px AA 目标最小值,并通过 overflow-visible 内部几何体(而非流内 block-size)以该行高盒为中心。 该扩展保持不被裁剪,且不能重叠或抢占标题文本、相邻控件或前后行的输入。 指针激活不会绘制键盘焦点可见环;键盘焦点恰好绘制一个规范的、不被裁剪的 Astryx 环。

未经修改的点击、轻触、Enter 或 Space 会复制规范绝对永久链接,且绝不导航、滚动或变更当前哈希。 标题 ID 保持为传入的片段目标。成功时用 Astryx 的对勾图标替换 #,持续 1.5 秒,并通过规范的礼貌式实时区域播报一次本地化的 Link copied;失败时保持静默并保留 # 不变。 经修改/非主要指针的激活不会复制,且该按钮不暴露锚点、新标签页打开或链接上下文菜单语义。自定义标题不受此渲染器契约约束。

设计关系

状态 设计需求 呈现权威 模块契约
内置标题 保留语义化 h1–h6 内容,同时添加投影 ID 和同级复制控件。 当前源和 Markdown FR5, FR7, FR10
复制控件 在标题行内对齐 #/对勾;按规范显现,且仅扩展到 24px AA 命中下限。 按钮和模块契约 FR10
自定义标题 转发投影 ID,而不包裹或添加同级呈现。 调用方 FR7
No-plugin Markdown 逐字节保留已发布的仅根级标识与嵌套标题行为。 当前源码与 Markdown FR5

该模块不添加 Markdown 本地主题目标。按钮使用 Button 的现有目标;行属于私有布局。

父级与系统关系

  • component:Markdown 拥有通用插件接缝、转换后的树、内置标题部件、默认无插件投影以及自定义渲染器替换接缝。
  • module:Outline/parseOutlineFromMarkdown 拥有仅根级条目选择,并且仅在同一插件条目被安装时才消费本模块的投影。
  • spec:AST-036 拥有不透明插件协议;本第一方模块使用该协议,但不需要特权公开能力。
  • spec:AST-002/DEC-8 允许使用此工厂,而不是宽泛的 Markdown prop;因为安装、命名空间和 URL 基址都是调用方决策,Astryx 无法推导。
  • family:navigation-destinations 拥有 URL 接受/阻止策略;本模块负责清理可选基址并复制规范 URL。

实现计划与边界

  1. 将服务端安全工厂和标识投影保留在 plugins/headingLinks.ts 中;在共享的可移植插件信封内携带规范化模块配置,并仅从 plugins/index.ts 导出工厂和选项类型。
  2. 将渲染和 StyleX 保留在 plugins/ 下作为私有实现;Markdown 的内置标题路径仅在投影提供规范 URL 时才调用渲染器。默认路径和自定义渲染器路径保持不变。
  3. 将模块测试、SSR 验证、Storybook 和 Playwright 证据保留在模块中;将通用/无插件测试保留在 Markdown 中,将根级选择保留在 Outline 中。

验证映射

Contract Verification Representative states Failure expectation
FR1–FR4 模块测试、公共 API 测试、类型检查、导出/包检查 公共入口/选项、重复副本、无效条目/URL、h1–h6、Unicode、后缀冲突 导出漂移、选项丢失、错误识别、不安全 URL、不稳定 slug 或重复 ID 失败。
FR5–FR7 模块测试以及 Markdown 和 Outline 集成测试 未安装/已安装插件、根级/嵌套、真实的同级按钮、自定义标题 默认行为改变、自定义输出被包裹、控件伪造链接语义或 ID 不一致。
FR8–FR10 SSR 测试、Storybook 和 plugins/headingLinks.a11y.chromium.spec.ts 水合、复制/失败/计时器、不修改 location、静止/悬停/聚焦/触摸、line-height 行、24px 目标、RTL/缩放/强制颜色 水合恢复、反馈失真/偏移、布局扩大、目标重叠、指针绘制键盘焦点环或揭示语义漂移。
Repository 格式化、ESLint、知识/同步、i18n、Changeset 验证、核心类型检查、聚焦测试、pre-commit 模块文件、本地化目录、Markdown/Outline 接缝、文档/spec、Storybook、工作流 权威过期、未翻译漂移、重复所有权、类型/lint 失败或不相关 diff 块。

决策日志

DEC-1 — 提供单个第一方插件工厂

Reference: module:Markdown/headingLinks/DEC-1 Decider: cixzhang, 2026-10-03

单个工厂在保留不透明插件列表的同时,只暴露安装、可选稳定命名空间和可选安全 URL 基址。其配置搭载现有可移植、带版本的插件信封,而不是创建模块的 WeakMap 或对象标识,因此重复的兼容 Core 副本会保持一致。宽泛的 Markdown prop 或单独的 Outline 选项会把同一种组合变成永久的平行 API,并可能在不同界面间漂移。

兼容的重复副本消费完全相同的信封。有效的同名通用插件如果模块数据缺失或不兼容,仍作为普通插件保留在调用方声明顺序中,但永远不会获得本模块的 ID 投影。格式错误的通用信封遵循现有消费方的容错路径,因此 Markdown 和 Outline 会保留已发布行为,而不是在渲染期间抛出。无效的直接工厂参数仍属于程序员错误。

已拒绝:模块本地选项状态;将同名相似插件提升为本模块;因包版本偏差在渲染时崩溃;默认开启行为;Markdown 布尔或命名空间 prop;单独的 Outline 标识选项;产品特定的工厂选项。

DEC-2 — 拥有单一全深度标识投影

Reference: module:Markdown/headingLinks/DEC-2 Decider: cixzhang, 2026-10-03

每个转换后的标题都以深度优先方式参与,因此渲染目标和根级 Outline 条目共享同一条冲突序列。NFKC Unicode slug 化和已发出 ID 预留会生成持久且可读的片段。调用方命名空间是稳定数据;运行时树位置和 useId 则不是。

已拒绝:仅限根级的插件分配;独立的 Markdown/Outline slug 生成器;纯 ASCII slug;可能导致重新输出自然数字后缀的冲突计数;运行时 ID。

DEC-3 — 渲染器扩展是一个名副其实的显露式复制按钮

参考: module:Markdown/headingLinks/DEC-3 决策者: cixzhang, 2026-10-03

渲染器扩展使用一个内联的尾随 # 同级元素,具有基线/逻辑间距、次要颜色和继承的排版。它的主要操作是复制,因此它是一个真正的按钮,而不是抑制导航的锚点。useContainerReveal 负责精细指针静止、标题行悬停、focus-within、粗糙/触摸和动效语义。其流内盒子与标题的 line-height 匹配,具有稳定的逻辑末尾空间和不重叠的 24px 粗糙命中区域;指针激活时不会绘制键盘焦点环。标题 ID 仍然是传入的片段目标。

已拒绝:原生片段导航;复制加导航的锚点混合体;定制的显露媒体逻辑;产品路由;新的公开显露 API。

内容边界

该模块仅读取转换后的标题节点,以及由已验证的插件条目携带的、用于当前文档调用的调用方提供的配置。它不会在模块局部状态中持久化文档内容、标签、目标、选项或生成的 ID。

开放问题

无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx