@shellraining/dsh-fluent-theme 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shellRaining
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# Win10 Fluent 主题
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Windows 10 风格主题，提供本地壁纸、Acrylic 亚克力材质、Reveal 光效、按压反馈和侧栏动效。沿用 DSH 设计变量（--dsw-*），跟随明暗主题与外观设置；这是网页近似，不是原生 Windows 控件的完整复刻。
+
+## 从旧包迁移
+
+本包原名 `@shellraining/dsh-acrylic-wallpaper`。备份 profile 配置，移除旧包后再安装新包，不要同时启用两者。保持相同的浏览器来源和用户数据，已有壁纸和设置会继续使用原来的本地存储，无需重新导入。Cordis 配置 ID `acrylic-wallpaper` 和已有主题 DOM 标记保持不变。
+
+## 安装
+
+```sh
+dsh plugin --profile web add @shellraining/dsh-fluent-theme
+```
+
+## Reveal 光效
+
+开启「Win10 风格」和「悬停与按压光效」后，鼠标或笔靠近控件时会照亮边缘，悬停时显示局部表面光。主聊天已发送的用户消息（含 steering 消息）、侧边聊天消息、输入卡片和待办卡片只显示边缘光，不改变文本选择、复制或焦点行为。
+
+按钮、菜单项等可交互控件还会显示独立的按压光：短按后扩散淡出，持续按住时缓慢扩散，松手后加快消退。光效参考 [WinUI 2 的 Reveal 实现](https://github.com/microsoft/microsoft-ui-xaml/blob/17bf1fc470bae72749998f2350cf19c9534da3f7/dev/Lights/RevealHoverLight.cpp)，采用 66ms 点亮、200/266ms 快速淡出及 1000/1500ms 慢速淡出；网页渐变的半径和亮度是近似值。离开控件、取消操作、失焦或关闭插件会清理按压光。光效与下文的实体按压反馈独立。
+
+光效跟随明暗主题。减少动态效果、高对比度或减少透明度模式下会关闭；触摸和键盘操作不触发装饰光，保留宿主原有反馈。现有 `reveal` 设置同时控制悬停与按压，无需迁移配置。
+
+## 控件按下状态
+
+「Win10 风格」还会补齐宿主 outline、toolbar 和 primary 按钮缺少的 Pressed 底色。底色由原生 `:active` 状态控制，按住时保持、松开时恢复，与短暂的按压光独立；关闭光效或开启减少动态效果后，按钮仍保留底色反馈。ghost 按钮沿用宿主已有的 active 配色，不重复叠色。toolbar 保留原有底色并叠加状态色；primary 没有专用 pressed token，暂用原底色与前景色的小比例混合作为网页近似，仍需在实际主题下检查对比度。消息正文和输入框不增加按压底色。
+
+实体反馈参考微软的 PointerDown/PointerUp 主题动画：按压靠左、靠右或靠边时，对应一侧向内倾斜；中心按压以轻微收缩为主。旋转中心始终在控件中心，方向取首次按下的位置，按住后不追随鼠标拖动。控件越大，倾角越小；缩放比例由中心的 97% 过渡到角落的 100%。键盘操作使用居中反馈。
+
+依据是[微软公开的原生实现](https://github.com/microsoft/microsoft-ui-xaml/blob/4a5d99f46230f25599a190b12d34ccb7daaeaaa8/dxaml/xcp/dxaml/lib/ThemeAnimations.cpp#L239-L391)和[指针位置插值](https://github.com/microsoft/microsoft-ui-xaml/blob/4a5d99f46230f25599a190b12d34ccb7daaeaaa8/dxaml/xcp/core/animation/PointerAnimationUsingKeyFrames.cpp#L202-L306)。源码将这套行为标注为从 Windows 10 开始的调整，但它来自较新的公开原生代码，不代表逐一验证了所有 Win10 系统版本。插件沿用其中的尺寸曲线、10ms 按下延迟及松手后的 150ms 保持、200ms 恢复，恢复曲线为 `cubic-bezier(.1,.25,.75,.9)`。CSS 透视采用 999px 近似，没有完整移植原生相机矩阵；早于按下延迟就释放的操作不会补播形变。普通 WinUI 按钮也不全都使用倾斜动画，因此这里是统一交互风格，不宣称所有控件都与系统默认模板一致。
+
+覆盖按操作语义统一识别，不再依赖基础 Button 类名：
+
+| 元素 | 处理 |
+| --- | --- |
+| 普通按钮、工具栏图标、个人菜单、确认卡片选项 | 同一套按压生命周期，适合变换时使用方向性形变 |
+| 侧边栏会话与项目行、搜索结果、文件按钮、子任务树行 | 整行或实际按钮响应；行内按钮优先，不同时按下父行 |
+| 菜单项、选项、导航链接、标签页、日历日期格 | 按语义接入；已有下划线伪元素、裁剪路径或变换时保留几何并补底色 |
+| 会话拖拽行、Dock 标签 | 按下可以反馈；移动达到每轴 4px 阈值或实际开始拖拽时立即清理 |
+| 轨迹表行、市场卡片的扩展点击区域、滚动容器、固定定位后代等不适合变换的结构 | 使用瞬时按压底色，不替换宿主伪元素或强行变形 |
+| 消息正文、输入框、原生表单字段、编辑器、拖拽空白区和尺寸手柄 | 不添加实体形变，不改变选择、编辑或拖拽行为 |
+
+形变跟随「Win10 风格」，独立于光效开关；减少动态效果时只保留底色反馈。只在入场时播放动画的控件（如侧栏的视图选项）在动画结束后同样形变。鼠标、笔、触摸和聚焦操作元素的空格 / Enter 键均可触发，不阻止默认事件、不合成点击、不接管指针捕获。关闭插件、失焦、取消、移除控件或布局变化时清理临时样式。
+
+Reveal 与控件使用同一透视映射，光点转换到控件局部坐标。透明逆变换伪元素保留外层原始命中边界，但行内子按钮仍随外观移动，并不保证各个子节点的命中区域固定。新会话这类 `overflow: hidden` 的按钮会把这个伪元素一起裁掉，因此按下时先试算最大形变：按压点仍落在按钮上才变形，贴着边缘按下则只显示按压底色；按住后移到收缩露出的边缘会提前结束形变，松手仍点在按钮上。带弹出层或展开语义的触发器在宿主处理点击前恢复，避免用形变后的边界定位；没有这些语义的自定义弹出层仍需实际验证。宿主列表没有统一的内容容器，因此这里变换整行，而原生 ListViewItemPresenter 可以只变换内容子层，这也是网页近似的边界。
+
+## 侧栏开合
+
+宿主先提交新的三栏宽度，下一次 React 提交才加上 `data-animating` 打开宽度过渡。0.2.1-rc.3 的右侧面板（DockLayout）每次渲染都会在这两次提交之间读取布局，浏览器提前算出了新宽度，过渡来不及生效：左侧栏开合总是直接跳变，右侧栏开合时中间对话区也经常跳变。插件关闭时同样如此。
+
+开启「Win10 风格」后，宿主标记了 `data-animating` 的开合都由插件按框架当前声明的时长和缓动重放；宿主自己的过渡偶尔启动时，也换成同样的重放，每次开合表现一致。拖动分隔条、窗口尺寸变化，以及宿主标记为全屏或瞬时的切换照旧不动画；开启减少动态效果时宿主关掉了过渡，插件也不重放。
+
+对话正文的宽度由栏宽推算：宿主每次尺寸变化后都把栏宽写到对话外层，整段对话继承这个值，动画的每一帧都要重算全部消息的样式、重新折行，长对话会明显卡顿。重放期间，插件先在对话正文上写好开合结束时的栏宽，宿主逐帧的写入只影响外层：点击后正文直接换成最终宽度，之后只随栏位平移，动画结束后再交还宿主的值。开合后的对话区放不下这个宽度时（比如打开右侧栏），正文仍会在后半段随栏位收窄。
+
+右侧栏收起时宿主会立即去掉栏位。栏宽过渡期间，滑出的面板贴着变宽的对话区，不会盖住对话，所以沿用打开时的壁纸淡色，不再变成深色底板。从全屏退出这类不动画的收起仍会盖住对话，继续使用亚克力底。
+
+## 开发
+
+开发使用仓库根目录的 Node 24.9+ / pnpm 环境，依赖版本统一由根 `pnpm-workspace.yaml` 的 catalog 管理。`build.ts` 调用共享 Vite 构建，构建前先执行 TypeScript 7 原生 `tsc` 类型检查。客户端保持 DSH ModuleLoader 加载方式，宿主入口和发布路径不变。
+
+```sh
+pnpm --filter @shellraining/dsh-fluent-theme typecheck
+pnpm --filter @shellraining/dsh-fluent-theme build
+```
+
+主聊天气泡通过宿主 CSS 模块动态解析，不依赖构建哈希；模块未加载时跳过，加载后自动更新。侧边聊天使用其作用域内的普通气泡类，排除待发送消息。升级宿主或侧边聊天后，应在实际 DSH 页面检查消息边缘、内部按钮、文本选择、滚动遮挡及插件启停。构建完成不代表界面已更新，需确认宿主加载的是该构建目录，再刷新页面。
+
+## 许可
+
+MIT