跳到主要内容

变更日志

@plaud/design 的发布历史，按发布版本组织（最新在前）。每个版本内部按 ✨ 新功能 与 🐛 缺陷修复 二级标题分组，并按组件逐条列出。版本号取自包的 changeset 变更日志。早于首次发版的变更归入 Pre-release 分组。

v0.9.0​

✨ 新功能​

  • Select — 新增 ghost 触发器变体 (WEB-1277) (详情)
    • Select 新增 variant prop（'outline' | 'ghost'），默认 'outline'，现有用法零回归。对外通过 <Select variant="ghost" /> 使用；内部 SelectTrigger 子组件消费该 prop，但保持内部实现、不从包出口导出
    • ghost 为无边框、内容自适应、值右对齐的触发器，带尾部 sort（上下）双向箭头与 hover/open 灰底，用于行内 / 工具栏选择场景
    • ui/select.tsx 的 SelectTrigger 新增可选 icon prop，覆盖默认 chevron（内部能力透传）
    • SortIcon 中性态（sortDirection === null）改用 currentColor，跟随父级文字色（使 ghost disabled 态图标正确变灰）；asc/desc 激活态高亮不变
    • (WEB-1277) fix(Select): 修复 ghost 触发器的 WCAG AA 对比度问题
    • hover/open 态文字从 Labels/Tertiary 加深为 Labels/Secondary（叠加 Grays/Gray-1 背景），对比度从 4.47:1（不达标）提升到 9.11:1
    • 键盘焦点指示不再单独依赖低对比度灰底（相对白色仅 1.19:1，不满足非文本对比度 3:1 要求），改为可见的 Labels/Primary 焦点环（21:1）
    • (WEB-1277) fix(Select): 修复 ghost 触发器宽度撑满整行的 bug
    • ghost base class 此前只覆盖了宽度（w-full → w-auto），未覆盖 display；底层 ui/select.tsx primitive 是块级 flex 容器，仅 width: auto 在普通文档流（非 flex/grid 父容器）中仍会撑满父宽度，导致 hover/focus 灰底横跨整行而非贴合内容
    • 在 ghost base class 中于 w-auto 旁追加 inline-flex，使触发器变为行内级 flex 盒子，在任意布局上下文中都能真正按内容宽度收缩
  • (WEB-1310) feat(Select)!: 单选 Select 支持左置对勾选项变体，并把 MultiSelect.menuItemVariant 改名为 optionItemVariant (详情)
    • 破坏性变更：MultiSelect.menuItemVariant 重命名为 optionItemVariant（含义、取值、默认值 'checkmark' 均不变）——下拉里的一行是 SelectOptionItem，不是「菜单项」，改名对齐领域词汇，并让 Select 与 MultiSelect 共用同一个 prop 名
    • SelectContent（组合式子组件）新增 optionItemVariant?: 'checkmark' | 'checkmark-right' prop，默认 'checkmark-right'（零回归），通过 context 下发给面板内渲染的每个 SelectItem
    • Select 新增同名 optionItemVariant prop，透传到声明式非 searchable options 分支渲染的 SelectContent
    • 刻意不放在 SelectItem 自身上：同一下拉面板内所有行必须共享同一个对勾位置（Figma 没有同一菜单内左右混搭的变体），若做成 per-item prop，调用方漏设一项就会静默产生左右不一致的菜单
    • checkmark 把选中态指示器从文案右侧移到左侧，对齐 Ghost trigger 菜单项 Figma 变体；item 内边距相应从预留右侧空间改为预留左侧空间
    • 范围：仅组合式 SelectContent/SelectItem 与声明式非 searchable 分支——searchable 单选已通过 SearchableOptionItem 支持左/右置对勾

🐛 缺陷修复​

  • Calendar — 月/年下拉打开时定位并聚焦到当前月/年 (WEB-1295) (详情)
    • 月/年下拉（CalendarMonthCaption）用 Radix DropdownMenu 渲染，打开时默认聚焦列表首项，年份下拉（当前年 ±50 共 101 项）停在最早的 1976 而非当前选中年份（如 2026）；月份下拉存在同样的潜在问题
    • 给当前月/年项打 data-current="true" 标记，并给两个下拉的内容容器加 pd-calendar__scroll-menu 标记类
    • 新增 useEffect：下拉打开时（一个 requestAnimationFrame 后）对 [data-current] 项 focus({ preventScroll: true })，并仅调整容器 scrollTop 把它在滚动容器内居中（不触发页面滚动）
    • 新增 2 条单测，锁定当前年 / 当前月的 data-current 标记契约
  • DropdownMenu — 修复 modal Dialog/Popover 内 portal 浮层列表无法滚动 (WEB-1286) (详情)
    • useStopWheelPropagation 之前用 useEffect 读 ref.current 且依赖稳定，只在挂载时跑一次；而 Radix Content 的 DOM 经 Portal/Presence 延迟挂载，effect 首次运行时节点尚为 null 便 early-return，wheel 监听器从未绑定，面板真正打开后也不会重绑
    • 结果：modal Dialog 内 portal 到 document.body 的 DropdownMenu（如日历的月/年选择器）无法滚动——Dialog 的 react-remove-scroll 隔离逻辑会 preventDefault 掉所有目标不在其 shards 白名单内的 wheel，而（从未绑定的）stopPropagation 守卫无法阻止事件冒泡到该 document 级监听器
    • 将 useStopWheelPropagation 重写为返回稳定的 ref 回调，在节点挂载/卸载的精确时刻绑定/解绑 wheel 的 stopPropagation 监听，从而兼容延迟挂载的 portal 内容
    • 在所有调用方改用 ref 回调形态：DropdownMenu、ContextMenu、Menubar（Content + SubContent）、Popover、Select
    • 新增单测：断言 hook 在挂载时绑定、收到 null 时解绑

v0.8.0​

✨ 新功能​

  • Tree — 修复 light/dark 主题切换时行颜色过渡延迟 (WEB-1207) (详情)
    • Tree item 的 transition-colors（本为 hover/selected 背景服务）会把主题切换时整套 CSS 变量的翻转也做插值动画，导致行背景/边框在 light↔dark 切换时"慢慢过渡"（颜色切换延迟观感）
    • 新增并导出共享工具 suppressThemeTransition(apply)：自行注入一次性 <style>（.pd-theme-switching * { transition: none !important }，无需 import globals.css），在执行 apply 前加 class、apply 后强制一次同步样式计算让变量翻转在过渡禁用状态下提交，再于下一帧移除 class——主题瞬时切换，hover/selected 等交互过渡不受影响
    • DesignProvider 改用 suppressThemeTransition 包裹 data-theme / .dark 翻转；在 DesignProvider 之外自行切换主题的消费方（如 design-site 的 Docusaurus 桥接、web4 的 darkMode.ts）可复用该工具
    • 补充工具单测

🐛 缺陷修复​

  • Dialog — Modal 背景改用 Grays/White token，dark mode 从近黑恢复为 #292929 (WEB-1244) (详情)
  • Select — 修复下拉自动滚到选中项时顶部首项被裁切 (WEB-1194) (详情)
    • Radix SelectPrimitive.Viewport 自带 inline overflow: hidden auto 且 flex: 1，是真正的滚动容器（撑满到 content 的 max-h-[268px]）。下拉的上下 py-(--Spacing_8) 此前落在 viewport 上、即位于滚动区之内——当列表自动滚动以显示靠后的选中项（如显示语言选到「中文（简体）」，index 8）时，顶部 padding 随列表滚走，首个可见项（「Español」）紧贴面板顶边被裁切
    • 将 SELECT_VIEWPORT_TOKEN_CLASS 精简为仅保留语义标识 pd-select__viewport（移除滚动区内的 py-(--Spacing_8) 及冗余的 overflow-y-auto，后者 Radix inline 样式已提供）
    • 改把 py-(--Spacing_8) 加在 SelectContent 外框上；Radix 给 popper content 强制 display:flex; flex-direction:column，padding 落在不滚动的 flex 容器上恒定显示。未改动被 searchable Popover / MultiSelect 复用的共享 SELECT_CONTENT_TOKEN_CLASS
    • SELECT_DROPDOWN_MAX_HEIGHT 由 max-h-[268px] 修正为 max-h-[270px]：content 带 1px border，Tailwind preflight 下 box-sizing: border-box，max-height 含 border。268px 时 viewport 实际只有 268 − 2(border) − 16(padding) = 250px（＜ 7×36 = 252px），滚动时首项仍被裁切约 2px；计入上下 2px border 后 viewport 恰为 252px = 正好 7 × 36px，滚动按整项对齐
    • 新增回归测试：断言 padding 落在 content 外框（listbox）而非 viewport 上，且 listbox 为 max-h-[270px]
  • Toast — 修复 variant 背景透明，更新到重命名后的 Accent token (WEB-1208) (详情)

v0.7.0​

✨ 新功能​

  • MultiSelect — 开放 menuItemVariant='checkmark' 并设为默认（左侧对勾） (WEB-1201) (详情)
    • 将 MultiSelect.menuItemVariant 从 'checkmark-right' | 'checkbox' 拓宽为 'checkmark' | 'checkmark-right' | 'checkbox'，放开 SearchableOptionItem 已支持的左侧对勾
    • 将默认 menuItemVariant 从 'checkmark-right' 改为 'checkmark'（左置对勾），对齐 Figma 默认；此前依赖隐式右置对勾的调用方需显式传 menuItemVariant="checkmark-right"
    • 无渲染改动：'checkmark' 在左侧渲染对勾，菜单项带前导 icon 时按既有 Figma 规则自动移到右侧
    • 补充单测与文档站示例（中英）覆盖左侧对勾变体

🐛 缺陷修复​

  • Button — 禁用按钮点击/悬停时不显示视觉效果 (WEB-1203) (详情)
    • 为所有按钮变体（primary、secondary、tertiary、quaternary、destructive、destructive-outline、link-color、link-gray）添加 disabled:hover: 和 disabled:active: 防护类
    • 确保禁用按钮在点击或悬停时保持一致的样式，防止边框/背景意外变化
    • 覆盖启用 pointer-events-auto 的禁用状态下可能泄露的任何 hover/active 伪类效果
  • Dialog — DialogTitle 字重对齐 Figma Modal（font-normal → font-semibold） (WEB-1193) (详情)
    • ui/dialog 的 DialogTitle 原为 font-normal（400）；Figma DS Modal 标题（节点 21231:6298，Size=Default）为 H3/Emphasized：18px / 24px / 字重 600（token --Font-Weight-Emphasized = Semibold）
    • 将 font-normal 改为 font-semibold（600）；字号（18px）与行高（--Line-Height-H3，24px）不变
    • 所有使用结构化 title prop 的弹窗标题字重统一变为 600，向设计稿收敛
  • DropdownMenu — 禁用项图标/箭头置灰为 Labels/Disabled，并显示 not-allowed 光标 (WEB-1190) (详情)
    • 新增共享类 DROPDOWN_ICON_DISABLED_COLOR_CLASS，通过祖先 [data-disabled] 选择器让图标容器在父项禁用时跟随 Labels/Disabled（图标颜色为显式声明，不会自动继承 Item 文字的 disabled 色）
    • 应用到 DropdownMenuItem 前置图标（经 getDropdownMenuItemIconColorClass）、DropdownMenuSubTrigger 前置图标以及尾部级联箭头（DROPDOWN_SUB_ARROW_COLOR_CLASS）
    • 在共享 item base 追加 data-disabled:pointer-events-auto + data-disabled:cursor-not-allowed，覆盖 ui 层的 pointer-events-none，让禁用项显示 not-allowed 光标（对齐 Button）

v0.6.8​

🐛 缺陷修复​

  • DropdownMenu — 级联子菜单指示箭头颜色改为 Grays/Gray-4（设计规范 labels-gray4） (WEB-1183) (详情)
    • 箭头图标（icon_list_chevron_right）已在 WEB-1129 替换，本次仅改颜色，此前为 Labels/Primary
    • 通过新增 DROPDOWN_SUB_ARROW_COLOR_CLASS 将箭头颜色与前置图标解耦，前置图标仍保持 Labels/Primary

v0.6.7​

🐛 缺陷修复​

  • Toast — action 支持透传 actionProps 到底层 action 按钮 (WEB-1181) (详情)
    • actionProps 在默认 variant/size 之后展开（使调用方可覆盖），但在组合 onClick 之前，因此点击 + 自动关闭行为不可被覆盖
    • 排除 children（由 label 承担）与 onClick（由 Toast 组合）；data-* 索引签名沿用 Dialog okButtonProps 既有约定

v0.6.6​

🐛 缺陷修复​

  • AiButton — 新增 Loading 与 Disabled（预留）状态 (WEB-1176) (详情)
    • loading 以 16px Spinner 替换 sparkle 图标、文字转灰，保留白底 + 渐变描边，并以原生 disabled 阻断交互（aria-busy + not-allowed 光标）
    • disabled（预留）将按钮置为灰底（--Grays-Gray-2）、去除渐变描边并灰显 sparkle 图标

v0.6.5​

🐛 缺陷修复​

  • Select — 菜单项存在前导 icon 时，选中 indicator 移到右侧 (WEB-1174) (详情)
    • 将「有 icon → indicator 在右」的布局规则从 checkbox 变体泛化到 checkmark 变体（SearchableOptionItem），对齐 Figma 规范（Show Icon=True → [icon][text][indicator]）

v0.6.4​

🐛 缺陷修复​

  • Toast — 带标题（Alert）变体顶部 padding 由 8px 调整为 12px (WEB-1128) (详情)
    • 仅 Alert 形态顶部；Message 形态与左右/底部 padding 不变

v0.6.3​

🐛 缺陷修复​

  • DropdownMenu — 级联子菜单样式调优 (WEB-1129) (详情)
    • 向 IconRegistry 新增必填 key listChevronRight（破坏性：图标 registry 必须补 icon_list_chevron_right 实现）
    • 级联箭头改用 ListChevronRightIcon，20px 容器，Labels/Primary
    • SubContent 默认 sideOffset={-8} / alignOffset={-8}（叠在父菜单之上 + 首项对齐父级选项）
    • SubTrigger 展开态背景覆盖为 Grays/Gray-1（修复展开时黑底）
    • 前置图标容器默认 Labels/Primary（业务传入 node 可覆盖）

v0.6.2​

🐛 缺陷修复​

v0.6.1​

🐛 缺陷修复​

v0.6.0​

✨ 新功能​

  • Select / MultiSelect — 新增图标支持、menuItemVariant 与搜索图标开关；SearchableOptionItem 新增 variant prop（'checkmark-right' | 'checkmark' | 'checkbox'）及可选前导 icon；MultiSelect 新增 menuItemVariant 切换下拉项视觉风格，Chip 新增 hover/active/focus-visible 状态；Select 新增 showSearchIcon（默认 true），checkbox 变体改为复用 Checkbox 组件；Input 边框新增 hover 态；下拉项默认文字色由 Labels-Secondary 调整为 Labels-Primary（WEB-1075、WEB-1076、WEB-1118）

🐛 缺陷修复​

v0.5.0​

✨ 新功能​

  • ImageViewer — 放大后支持鼠标拖拽平移；zoom > 1 时可拖拽图片定位局部区域，光标自动切换为 grab / grabbing；含边界约束，图片不会被拖出视口；切图、缩小到默认倍率或关闭时平移量自动复位（WEB-1062）

🐛 缺陷修复​

v0.4.6​

🐛 缺陷修复​

v0.4.5​

🐛 缺陷修复​

v0.4.4​

🐛 缺陷修复​

v0.4.3​

🐛 缺陷修复​

  • Dialog — showClose 为 true（默认）时，DialogTitle 增加右侧留白（--Spacing_40），防止长标题被关闭按钮遮挡。

v0.4.2​

🐛 缺陷修复​

v0.4.1​

🐛 缺陷修复​

  • ImageViewer —— ImageViewer: 默认导出改为先 fetch 成 blob 再用同源 objectURL 下载，跨域 CDN 图片也能真正下载而非跳转新页面；fetch 失败或 HTTP 非 2xx 时回退到原始地址，objectURL 延迟回收（DES-133）。

v0.4.0​

✨ 新功能​

  • Tree —— Tree title 溢出检测改为按需测量（DES-132）。useTitleOverflow 改为在指针进入 / 聚焦该行时按需测量，不再挂载即测，消除大数据量列表的布局抖动。契约变化：超长 title 仅在首次 hover/focus 后才包成 Tooltip trigger，并移除 ResizeObserver。

v0.3.1​

🐛 缺陷修复​

  • ImageViewer —— 单图工具栏优化 + 无障碍修复（DES-130）。单图隐藏上一张/下一张导航，禁用图标光标恢复 not-allowed，新增 role="status" / aria-live="polite" 缩放播报，支持键盘缩放（+ / = / -）。

v0.3.0​

✨ 新功能​

v0.2.2​

🐛 缺陷修复​

  • Input —— Input 家族 PR review 修复，记录在 Input 新增 allowClear + 补充 visual case。useClearableInput 改用原生 value setter + 真实 input 事件派发（完整 SyntheticEvent）；InputSearch 清空按钮补 focus-visible 焦点环；仅 allowClear 时托管聚焦态；新增可本地化的 clearButtonAriaLabel prop。

v0.2.1​

🐛 缺陷修复​

v0.2.0​

✨ 新功能​

🐛 缺陷修复​

v0.1.0​

Skeleton 重构与若干组件细化（大部分已被上方更详细的 v0.2.0 条目覆盖）。

✨ 新功能​

  • Skeleton —— 重构支持 items 多块渲染，新增 SkeletonGroup 卡片级扫光。
  • Button —— 对齐 icon-only 状态。
  • Dialog —— 支持可滚动内容。
  • Checkbox / RadioGroup / Menu / Slider —— 样式与行为细化。
  • utils —— 新增 merge-refs helper，并从包入口导出。

🐛 缺陷修复​

  • Button —— 修复 disabled label 样式。

v0.0.1​

首次发布 —— 将 design 包发布到私有源。@plaud/design-tokens 与 @plaud/design 以构建产物 dist 形态发布（0.0.1）。

Pre-release​

早于 changeset 发布流程的变更 —— 未单独发版。

✨ 新功能​

🐛 缺陷修复​

关联​