# Button 更新日志

先阅读 [完整 LICENSE](https://snowui.dev/LICENSE)；同任务、同版本、同范围去重。

### v2.20.0 (2026-10-22)

- 内部内容复用共享单行间距下限；保留Hug、size／padding、图标尺寸、动效和事件，不要求调用方外包Frame。

- 2026-10-05：原 Indigo 默认配色改为 Brand（`--brand`），保留原有透明度、状态与覆盖机制。


### 2026-09-28

- 稳定内置 hover 的背景合成层，消除反复移入 / 移出时的图层重建和背景重绘；保留文字缩放、现有比例、颜色与时序。

### v2.19.0 (2026-09-27)

- 新增 contentScaleOnHover，内容默认作为整体跟随背景 hover 与点击缩放；可独立关闭。背景不缩放时内容也不缩放，布局与命中区保持不变。
- 修复 hover 缩放结束时文字重绘造成的视觉下移；sm / md / lg 覆盖动画尾帧与结束帧的像素一致性回归。

- 2026-09-21：统一使用文档、源码属性表与 Site / AI 阅读入口；仅文档修订，不改变组件行为。

### v2.18.1 (2026-09-12)

- 背景横向总外扩限制为 0.25rem，纵向保持原比例；Borderless 隐藏起点与点击缩回同步补偿，长按钮不再随宽度无限增加外扩量。复用共享尺寸监听，内容、布局和时序保持不变。

### v2.18.0 (2026-09-04)

- 按标准高度反比补偿 md / lg 的 hover 终点、Borderless 隐藏起点与点击中点；默认 / sm 视觉不变。保留背景等比 transform、颜色、时序、内容和组合开关；最终效果待 Owner 视觉验收。

### 2026-09-03

- 为内置 hover 背景放大增加配套点击缩回 / 恢复，统一由 scaleOnHover 控制。

### v2.17.1 (2026-09-02)

- 根据现有源码补齐逐属性说明、默认回退和使用边界；未改变组件运行时行为。

### v2.17.0 (2026-08-27)

- **BTN-Hover.14** 恢复 2026-08-19 Owner 已确认的背景层比例方案并取代 BTN-Hover.9–13 的现行效果：gray / filled / outline 为 `1 → 1.06`，Borderless 为隐藏的 `0.84 → 1.06`，背景 transform 使用 `200ms ease`，颜色使用通用 `150ms ease-out`；内容、命中区、布局和复合控件关闭规则不变。

### v2.16.0 (2026-08-19)

- **BTN-Hover.13** hover 颜色 opacity 与背景 inset / radius 统一使用 `150ms ease-in-out`，进入和退出时同时开始、同时结束；最终颜色与几何终点不变。

### v2.15.0 (2026-08-19)

#### 动效稳定性
- **BTN-Hover.12** filled 实际浏览器逐帧观察确认根布局稳定，抖动感来自高对比边缘在 `200ms ease` 亚像素重绘以及几何 / 颜色分段结束；几何改为 `150ms ease-in-out`，缩短重绘窗口并缓和进入 / 退出首段，颜色继续以 `300ms ease-in-out` 柔和变化。

### v2.14.0 (2026-08-19)

#### 动效几何
- **BTN-Hover.11** 独立 hover 背景的圆角半径改为“根 Button 最终解析半径 + 当前外扩量”，并与 inset 共用 `200ms ease`；sm / md / lg、`iconOnly` 与普通内容 Button 每边外扩 `1px` 时圆角同步增加 `1px`，根尺寸、内容和连续角曲线不变。

### v2.13.0 (2026-08-19)

#### 视觉架构
- **BTN-Corner.2** Button 从组件内硬编码连续角改为接入 `tokens.css` + `layout.css` 的跨组件圆角矩形共享视觉原语；hover 背景层显式继承根曲线，既有 radius 数值、variant、bare 与组合嵌入态不变。

### v2.12.0 (2026-08-19)

#### 视觉
- **BTN-Corner.1** gray / filled / outline / borderless 根外壳与独立 hover 背景层新增 `corner-shape: superellipse(1.1)`，以接近原普通圆角的视觉圆度表达轻微连续角平滑；保留 sm / md / lg、公开 radius override、bare 与 ButtonGroup 嵌入态的原有圆角数值和所有权，不支持时回退为普通 `border-radius`。

### v2.11.0 (2026-08-19)

#### 动效
- **BTN-Hover.10** hover 颜色层恢复 opacity 过渡，并改为 `300ms ease-in-out`；它慢于 `200ms ease` 背景外扩，使颜色进入与退出更柔和。reduced-motion 下两者都立即提交最终状态。

### v2.10.0 (2026-08-19)

#### 动效
- **BTN-Hover.9** 以真实 Test A2 sm `Small` Button 的 `54.78125 × 24px` 为基准：原 `scale(1.05)` 对应总宽增加 `2.739px`、总高增加 `1.2px`，分别按最近的 2px 倍数取整为 `2px`。默认 hover 改为三档背景总宽、总高统一增加 `2px`，不再按 Button 尺寸或内容宽度使用比例 scale。

### v2.9.0 (2026-08-19)

#### 动效
- **BTN-Hover.8** lg hover 背景层终点由 `1.01` 调整为 `1.015`；Button hover 背景颜色层移除 opacity transition，进入与移出均立即切换，scale 动效保持不变。

### v2.8.0 (2026-08-19)

#### 动效
- **BTN-Hover.7** hover 背景层终点比例改为按最终解析尺寸选择：sm `1.05`、md `1.03`、lg `1.01`；尺寸 Context 与显式 `size` 继续沿用 Button 原有优先级。

### v2.7.2 (2026-08-19)

#### 动效
- **BTN-Hover.6** `BUTTON_HOVER_SCALE_UP_MOTION` 的背景层终点比例由 `1.06` 调整为 `1.05`；内容、布局尺寸、颜色反馈和组合控件关闭规则不变。

### v2.7.1 (2026-08-19)

#### 性能
- **BTN-Hover.5** 基础背景与 hover 颜色叠层分离；缩放只更新背景层 `transform`，颜色反馈只更新独立叠层 `opacity`，不再在 scale 期间逐帧重算 `color-mix()` 背景。Outline 原有边框颜色过渡保持不变。

### v2.7.0 (2026-08-19)

#### 动效
- **BTN-Hover.3** 内置 hover scale 从 Button 根迁移到独立背景层；文字、Icon、Spinner、状态内容和命中区保持原尺寸。
- **BTN-Hover.4** gray / filled / outline / borderless 继续使用原有 base background + overlay 颜色合成；Borderless 背景从 `0.84` 扩张到 `1.06`，bare 因无背景层不执行内置放大。

### v2.6.0 (2026-08-19)

#### 动效
- **BTN-Hover.1** 独立动作 Button 默认通过组件根视觉通道放大到 `1.06`，不改变布局尺寸；Borderless 保留 Light 4% / Dark 10% 的原有 hover 颜色，并让独立背景层从 `0.84` 扩张到完整面积；bare 保持无背景。
- **BTN-Hover.2** `scaleOnHover` 独立控制内置默认，复合控件项由 owner 默认关闭并允许实例显式开启；显式 `whileHover` 接管默认缩放，disabled 不缩放，reduced-motion 直接提交最终比例。

### v2.5.1 (2026-08-16)

- Filled 的 Static White 文字与图标色恢复；宿主基线的继承色不再依赖 CSS 注入顺序覆盖组件自有前景色。
- 外部 class / inline style 的既有覆盖优先级保持不变。

- **Button-Docs.2026-05-25** 源码顶部历史更新日志已归档；后续新增变更统一写入本文档 更新日志，源码顶部只保留职责、当前关键架构与文档路径。

### v2.5.0 (2026-08-11)

#### 破坏性变更
- **BTN-IconOnly.2** 新增显式 `iconOnly` Prop，默认 `false`；Button 不再根据 children DOM 自动推断单视觉内容布局。
- **BTN-IconOnly.3** `iconOnly=true` 输出 `data-icon-only="true"`，统一控制对称 padding、尺寸上下文、bare 最小命中区域与 render hints。
- **BTN-A11y.2** 开发环境下，icon-only Button 缺少 `aria-label`、`aria-labelledby` 或 `title` 时输出警告。
- **BTN-IconOnly.4** ColorSchemeButton、StyleButton、CopyButton、ExpandButton 及仓库内纯图标 Button 消费点改为主动声明 `iconOnly`。

### v2.4.0 (2026-08-09)

#### 调整
- **BTN-Bare.2** `bare` 默认改为 `emphasis="normal"`，常态与 hover 均保持 100% 不透明；次级操作显式使用 `emphasis="muted"` 获得 40% → hover 100%。disabled 继续优先消费全局 `--snowui-state-opacity`。
- **BTN-Bare.3** CopyButton 反馈期继承宿主 Button 的 bare 静止强调级别，不再无条件回落到 40%。

### v2.3.2 (2026-07-08)

#### 修复
- **BTN-Text.2** Button 默认 `--snowui-button-min-width` 改为 `max-content`，让按钮在 Pagination `widthMode="fill"` 等外层 flex fill 场景中保留“文字 + gap + padding”的自然下限；空间充足时仍可被外层拉宽，空间不足时由外层换行或溢出策略承接。

### v2.3.1 (2026-07-08)

#### 修复
- **BTN-Text.1** 文字型 Button 默认增加 `white-space: nowrap`，避免在 Pagination `widthMode="fill"` 等压缩布局中把“上一页 / 下一页”等中文短文案逐字换行。

### v2.3.0 (2026-07-04)

#### 新功能
- **BTN-Blur.1** 新增默认关闭的 `backgroundBlur`，开启时复用 BarChart 模糊浮层的 `backdrop-filter: blur(1.25rem)`。
- **BTN-Blur.2** 提供 `--snowui-button-background-blur-override` 覆盖模糊强度。

### v2.2.0 (2026-06-23)

#### 破坏性变更
- **BTN-Bare.3** 无外壳按钮能力统一归入 `bare`，不保留平行入口。`bare` 保留普通内容 gap；单 Icon 时自动注入 12/16/20px 档位尺寸上下文并提供至少 16×16px 的透明点击热区。
- **BTN-Bare.4** 精确 Icon 尺寸改由子 Icon 的 `size` 声明，Button 不再通过无外壳模式接收数值尺寸。

### v2.1.0 (2026-06-22)

#### 新功能
- **BTN-Bare.1** 最初新增 `bare` 无外壳按钮模式：内容可包含文字、Icon 或其他元素；无 padding / radius / 背景 / 边框。当时使用 `currentColor × opacity: 0.4 -> 1`；2026-08-09 起该视觉改由 `emphasis="muted"` 显式启用，bare 默认 100%。
- **BTN-Bare.2** `bare` 放入 Tab 时由 Tab 的 `--snowui-button-opacity-override` 接管透明度；两者作用于同一 Button 根节点，不发生透明度叠乘。

### v2.0.0 (2026-06-01)

#### 破坏性变更
- **BTN-Link.1** 移除 `variant="link"`，不保留兼容入口。文字链接统一使用独立 `<Link>`；按钮式跳转继续使用 `<Button href>`。

### v1.5.1 (2026-05-25)

#### 新功能
- **BTN-Breadcrumb.1** 新增 `as="item"` 组合角色，用于 Breadcrumb 路径片段。
- **BTN-Breadcrumb.2** 当 `as="item"` 的 Button 被 Breadcrumb 标记为 `aria-current="page"` 时，禁用 hover overlay、click、Enter 与 Space 激活，并保持 Button 尺寸不被 Breadcrumb 强制覆盖。
- **BTN-Breadcrumb.3** `Button as="item"` 未显式写 `variant` 时可继承 Breadcrumb 的 `variant`；显式 Button `variant` 优先，Breadcrumb 未写 `variant` 时回到 Button 默认变体。
- **BTN-Pagination.1** 新增 `as="current"` / `as="page"` / `as="prev"` / `as="next"` 组合角色，用于 Pagination 角色样式模板；Button 自身不承担页码计算。

### v1.5.0 (2026-05-21)

#### 新功能
- **BTN-A11y.1** 自动输出 `aria-pressed`:当 `Click` 字典是 `Idle ↔ Active` toggle、且 `currentState ∈ {Idle, Active}` 时,根节点根据当前状态输出 `aria-pressed="true|false"`。
- **BTN-A11y.2** 外部显式传入 `aria-pressed` / `aria-selected` 时优先级最高,组件不再覆盖,以支持 listbox / tab 等列表选择语境。
- **BTN-Toggle.1** 新增 `toggle` prop 语法糖:`<Button toggle>` 内部自动注入 `Click={{ Idle: "Active", Active: "Idle" }}` 与 `whileClick=false`,配合下方激活态规则零样板得到完整 toggle 行为(状态切换 + Indigo 配色 + aria-pressed)。消费方仍可显式传 `Click` / `whileClick` 覆盖默认。

#### 调整
- **BTN-Active.1** 激活态视觉改用 Frame 自动暴露的 `data-state="Active"` 驱动:根节点在 Active 状态下自动套用 Secondary/Indigo 配色,**消费方无需在 `stateClass` 里引用任何内部 class**(此前 v1.5.0 早期方案要求消费方写 `stateClass={{ Active: "snowui-button-active" }}`,已废弃)。
- **BTN-Active.2** Indigo 自动激活态对 `gray` / `outline` / `borderless` 三类 variant 生效;`filled` 排除以避免与变体既有配色冲突。需在 filled 上做激活反馈时由消费方通过 `stateClass` / `stateStyle` 自定义。

### v1.4.4 (2026-03-16)

#### 调整
- **BTN-Role.4** 移除 `control="date-picker"` 行为协议；日期触发器重新收敛为纯 `as="trailing"` 组合规则。
- **BTN-Role.5** 复杂结构中的日期触发器仅在可识别的局部容器内生效，例如 `Field` 直系或 `Frame as="row"`。

### v1.4.3 (2026-03-15)

#### 修复
- **BTN-Role.3** Button 现在正确透传 `as` 给 Frame 角色类，`as="trailing"` 可参与 Field 组合协议。

### v1.3.10 (2026-03-10)

#### 新功能
- **BTN-Role.1** Button 现在可通过 `as="badge"` / `as="icon"` 接入 `Image` 宿主定位协议。
- **BTN-Role.2** Button 现在可通过 `as="prev"` / `as="next"` / `as="close"` 接入 `ImageViewer` 控制按钮定位协议。

### v1.3.8 (2026-02-26)

#### 架构调整
- **BTN-Refactor.1** 移除 `stateText` 特化能力，Button 回归通用 children 渲染。
- **BTN-Refactor.2** 状态变量、状态 class、状态 style 统一由 Frame 的通用能力承载（`stateVars/stateClass/stateStyle`）。

### v1.3.6 (2026-02-26)

#### 新功能
- **BTN-Feat.1** Button 子内容现在透传 Frame 的状态对象（含 `currentState`），可在 `<Button>` 内通过 `children` snippet 直接做声明式状态文案切换。

### v1.3.5 (2026-02-25)

#### 修复
- **BTN-Fix.3** 注入 `RESOURCE_ICON_CONTEXT_KEY` 尺寸上下文；当时直放资源图标会由 DOM 自动识别并使用 sm/md/lg => 16/20/24，v2.5.0 起改为 `<Button iconOnly>` 显式启用。

### v1.3.4 (2026-02-25)

#### 修复
- **BTN-Fix.2** `as="more"` 角色识别不再依赖 `TextContext`：只要声明 `as="more"` 即挂载 `snowui-text-expand-button` 样式类，确保在 `Text` 内容中声明后稳定可见；点击时仍在存在 `TextContext` 时触发展开联动。

### v1.3.3 (2026-02-25)

#### 修复
- **BTN-Fix.1** 调整 `as="more"` 渲染策略：不再由 `isCollapsed` 作为显隐条件，`Text` 容器中声明了 `<Button as="more">` 即参与渲染；保留点击后与 Text 展开逻辑联动。

### v1.3.2 (2026-02-23)

#### 架构调整
- **BT-Refactor.1** 移除 Button 内置文本截断能力（`buttonLines` + `truncate` action）。
- **BT-Refactor.2** 截断能力统一由 `Text` 组件提供，Button 保持交互与布局职责。

### v1.3.1 (2026-02-18)

#### 样式优化
- **BT-Bridge.1** Button 核心视觉属性（`width/height/padding/gap/radius/font-size/line-height/color/background/inner-border`）改为变量桥接链：`override -> internal -> token`。
- **BT-Bridge.2** `sm/md/lg` 与 `icon-only` 改为只覆写内部变量，不直接写视觉终值，便于宿主组合覆盖。
- **BT-Bridge.3** 变体状态改为通过桥接变量驱动，使用 `data-variant` 作为 Level 4 选择器入口，并保留禁用态 hover 排除。

### v1.3.0 (2026-02-18)

#### 调整
- **BT-Layout.1** 移除 `sm/md/lg` 所有按钮的 `min-width/min-height` 约束，按钮尺寸完全由内容与内边距决定。
- **BT-Style.2** 精简尺寸样式变量结构：默认档位改为 `sm`，仅在 `md/lg` 覆写差异变量；合并 `icon-only` 重复选择器。
- **BT-Spec.1** 对齐 Figma 按钮三档规格：`sm/md/lg` 的 `icon-size`、`padding`、`gap`、`radius` 更新为 `16/20/24`、`4x12/8x16/12x20`、`4/6/8`、`12/16/20`
- **BT-Typography.1** 字号与行高改为强配对：`sm=--text-12 + --leading-12`，`md=--text-14 + --leading-14`，`lg=--text-16 + --leading-16`
- **BT-IconOnly.1** 单图标按钮 `icon-only` 的 padding 与档位纵向内边距保持一致（`4/8/12`）

### v1.2.8 (2026-02-07)

#### 修复
- **BT-Fix.5** 修复 `icon + text` 被误判为 `icon-only` 的问题
- **BT-Fix.6** 当时将 `icon-only` 识别改为运行时精确检测（单图标元素 + 无文本节点）；该自动识别已由 v2.5.0 移除。

### v1.2.3 (2026-02-07)

#### 修复
- **BT-Fix.2** 修复 `Icon.svelte` 在 Button 中未按 `sm/md/lg` 自动匹配 `16/20/24` 的问题（通过 Frame Size Context 传递）
- **BT-Fix.3** 修复单图标按钮规则未命中 `Icon` 根节点（补充 `.snowui-icon-wrapper`）
- **BT-Fix.4** 修正 `link` 变体最小高度重置（`min-height: 0`）

### v1.2.2 (2026-02-07)

#### 新功能
- **BT-Size.1** 补齐 `sm/md/lg` 的最小宽高（`28/40/56`）
- **BT-Size.2** 增加 `Icon.svelte` 子组件尺寸与按钮尺寸联动（`16/20/24`）
- **BT-Size.3** 增加单图标按钮（仅 1 个 icon）的独立 padding 规则

#### 调整
- **BT-Style.1** `sm` 常规 padding 调整为 `左右 12 / 上下 4`

### v1.2.1 (2026-02-03)

#### 修复
- **BT-Fix.1** 补齐 Frame 能力开关显式传参

### v1.2.0 (Initial)
- 初始版本