mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
fix(client): theme the scrollbars and reserve the workspace list gutter
design-platform.css declared four --dsw-alias-scrollbar-* tokens in both palettes that no rule read, so every scrolling region rendered the user agent's own scrollbar and the dark theme showed a light native bar against dark surfaces. The symptom that surfaced the gap was in the sidebar: the workspace browser's session list is its only scrolling region, and each row's trailing content (the relative timestamp, and the hover action buttons that replace it) is `flex: none` flush against the row's 8px right padding, so an overlaid scrollbar painted on top of the timestamp. ui-theme/styles/scrollbar.css becomes the sole consumer of the four tokens, imported by the web shell's base.css after design-platform.css because it reads that sheet's tokens. The rules sit on `body`, not `html`: the alias tokens are declared on `body`, custom properties inherit only downward, and from `html` they resolve to the guaranteed-invalid value with scrollbar-color computing to `auto`. scrollbar-width and scrollbar-color are declared on `body, body *` rather than inherited, because inheritance would carry the color already substituted at `body` and an elevated surface could not retint its own thumb; scrollbar-width does not inherit at all. Both the standard properties and the ::-webkit-scrollbar pseudo-elements read one indirection pair bound to the l1 tokens, so an elevated surface rebinds that pair to the l2 tokens once and retints both renderings. The command popup, slash menu, model-select panel, and settings panel do so, which gives the l2 tokens their first consumers. WorkspaceBrowser's `.list` declares scrollbar-gutter: stable, keeping the bar beside the rows. `stable` rather than `auto` so the reservation holds when the list is short enough not to scroll: expanding a workspace group would otherwise shift every row sideways at the moment it starts scrolling.
This commit is contained in:
Chinesezjc
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md
|
||||
2026-07-28-themed-scrollbars-and-reserved-gutter.md: 29aad9976610b02b42e0c69222504a84188e34d7
|
||||
2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md: 2c5c4eefee88680df35d1a069e6ab5de7884144f
|
||||
@@ -0,0 +1,57 @@
|
||||
# Agent Note: The scrollbar tokens get their consumer, and the workspace list reserves its gutter
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
`design-platform.css` declares four `--dsw-alias-scrollbar-*` tokens (`bg-l1`, `bg-l2`, `hover-l1`, `hover-l2`) in both palettes, and no rule anywhere in the client read them. A defined token with no consumer is not a theme: every scrolling region rendered the user agent's own scrollbar, which knows nothing about the palette, so the dark theme showed a light native bar against dark surfaces.
|
||||
|
||||
The visible symptom that surfaced the gap was elsewhere. The workspace browser's session list (`.list` in `WorkspaceBrowser.module.css`) is the sidebar's only scrolling region, and each row's trailing content sits flush against the row's 8px right padding — `.time` in `rows/Rows.module.css` is `flex: none`, as are the action buttons that replace it on hover. An overlaid scrollbar therefore painted on top of the relative timestamp. Reserving space in that one list would have left the bar itself unthemed, so the two halves are one change.
|
||||
|
||||
## Decision
|
||||
|
||||
`packages/client/ui-theme/src/styles/scrollbar.css` is the sole consumer of the four tokens, and the fifth ui-theme sheet in the shell's import chain (`packages/client/web/src/base.css`). It follows `design-platform.css` there because it reads that sheet's tokens.
|
||||
|
||||
The rules sit on `body`, not `html`. `design-platform.css` declares the `--dsw-alias-*` tokens on `body`, with the dark overrides on `body[data-ds-dark-theme]`, and custom properties inherit only downward; an `html` rule resolves them to the guaranteed-invalid value, at which point `scrollbar-color` computes to `auto` and no theming happens at all.
|
||||
|
||||
`scrollbar-width` and `scrollbar-color` are declared on `body, body *` rather than once at the top. Inheritance would pass down the color already substituted at `body`, so a descendant rebinding the indirection could not change its own scrollbar; re-declaring makes each element substitute the variable as it sees it. `scrollbar-width` is not an inherited property in the first place, so it needs the per-element declaration regardless. The `::-webkit-scrollbar*` pseudo-elements are likewise not inherited and are matched unscoped.
|
||||
|
||||
Both halves read one indirection pair, `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover`, bound on `body` to the l1 (base-surface) tokens. **This is the rebinding contract, and it is the part the CSS alone does not state**: an elevated surface sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container, and that one rebind reaches the standard properties and the WebKit pseudo-elements together. The pair is rebound as a pair; rebinding the resting thumb alone leaves the hover state on the base-surface token. Four surfaces rebind today: the command popup, the slash menu, the model-select panel, and the settings panel. The last two declare it on the elevated panel rather than on the scrolling descendant, because the elevation is a property of the surface and custom properties inherit down to whichever child actually scrolls.
|
||||
|
||||
The track and the corner stay transparent, so the thumb reads against whatever surface scrolls under it; only the thumb and its hover state carry a token color.
|
||||
|
||||
`.list` declares `scrollbar-gutter: stable`, which keeps the bar beside the rows instead of on top of them. `stable` rather than `auto` because `auto` reserves the gutter only while the list actually overflows: expanding a workspace group would then shift every row horizontally at the moment it starts scrolling. The reservation is unconditional and the rows never move.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Per-module `::-webkit-scrollbar` rules in each scrolling component sheet.** Rejected: the client has thirteen scrolling containers across nine packages, every one would carry the same block, and the fourteenth would ship unthemed with nothing failing. A skin driven by design tokens belongs in the package that owns the tokens.
|
||||
|
||||
**An opt-in utility class that each scroll container adds.** Same duplication removed, but the failure mode stays: a new scroll container is themed only if its author remembers the class, and the omission is invisible in review. The `body, body *` form has no opt-in step to forget; a container that genuinely wants a different bar overrides the indirection, which is the same mechanism elevated surfaces use.
|
||||
|
||||
**Bind the properties on `html`.** The natural place for a document-wide skin, and it fails measurably: with the rule on `html` a scroll container computes `scrollbar-color: auto` in chromium, because the alias tokens are not in scope there.
|
||||
|
||||
**Declare the properties once and let them inherit.** Fewer matched elements, and it breaks the rebinding contract — inheritance carries the substituted color, not the variable reference, so an elevated surface could not retint its own scrollbar. It is also incomplete on its own terms, since `scrollbar-width` does not inherit.
|
||||
|
||||
**Pad the rows instead of reserving the gutter (extra right padding on `.list`, or moving `.time` inward).** Rejected: padding applies whether or not a bar is present, so it costs horizontal room in the common short-list case, and it fixes exactly one container while leaving every other scrolling region's content under its bar.
|
||||
|
||||
**`scrollbar-gutter: auto` on `.list`.** The reservation appears when the list overflows, which is when the bar exists. Rejected because the sidebar's lists grow and shrink as groups expand, so the reservation would appear and disappear under the user's cursor and shift the rows with it.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Every scroll container in the client draws the themed thumb: `rgb(229, 229, 229)` on a light base surface, `rgb(60, 60, 61)` on a dark one, and `rgb(84, 85, 87)` for a dark elevated surface that rebinds to the l2 pair.
|
||||
- The two renderings are separately specified, so a change to the thumb's geometry or hover behavior has to be made twice — once in `scrollbar-width`/`scrollbar-color`, once in the pseudo-elements. Routing both through the indirection pair confines that duplication to the properties Firefox and WebKit do not share.
|
||||
- `body *` matches every element, for two properties whose effect the user agent already limits to elements that actually scroll. The cost is a broad selector; the alternative was a rebinding contract that does not work.
|
||||
- The workspace list is permanently narrower by the reserved band, at every list length. That is the trade the fix buys: stable row geometry instead of a timestamp that is legible only while the list is short.
|
||||
- There is no track token in the palette, so a design that later wants an opaque track needs a new alias token rather than a literal color in this sheet.
|
||||
|
||||
## Testing
|
||||
|
||||
Three unit specs read the CSS text on disk. `ui-theme/tests/scrollbar-styles.spec.ts` scans the scrollbar token set out of `design-platform.css` rather than hardcoding it, so adding, renaming, or dropping a token moves the assertions with it, and checks that every token has a consumer and that each elevated surface rebinds a complete pair. `web/tests/base-styles.spec.ts` pins the import order and the existence of every sheet `base.css` names. `ui-workspace/tests/browser-styles.spec.ts` pins the gutter reservation on `.list`.
|
||||
|
||||
`apps/web/tests/sidebar-scrollbar.e2e.ts` covers the two facts only a real engine reports: the reserved band width, and the substituted `scrollbar-color`. It needs no model calls — the list only has to overflow — so it seeds cold sessions from an existing committed fixture read-only.
|
||||
|
||||
Confirmed in headless chromium on the built client by reading computed values, which is what distinguishes a working token chain from a syntactically valid one: a scroll container computes the l1 thumb color in each palette, and a container that rebinds the indirection computes the l2 color, proving the rebind reaches the computed value rather than only the custom property.
|
||||
|
||||
Headless chromium draws overlay scrollbars, so a reserved gutter there does not shrink `clientWidth`. The reservation shows up as a non-zero `offsetWidth - clientWidth` band on the list; client-area geometry alone does not demonstrate it, and an assertion comparing the time element's right edge against the client-area edge holds with and without the reservation, so it would pass or fail on the platform's scrollbar style rather than on the declaration under test.
|
||||
@@ -0,0 +1,57 @@
|
||||
# Agent Note: 滚动条 token 有了消费方，工作区列表预留出滚动条空位
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-28-themed-scrollbars-and-reserved-gutter.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
`design-platform.css` 在亮色与暗色两套调色板中都声明了四个 `--dsw-alias-scrollbar-*` token（`bg-l1`、`bg-l2`、`hover-l1`、`hover-l2`），而客户端里没有任何一条规则读取它们。定义了却无人消费的 token 构不成主题：所有滚动区域渲染的都是浏览器自带的滚动条，它对调色板一无所知，因此暗色主题下暗色表面上出现的是一条亮色的原生滚动条。
|
||||
|
||||
暴露这一缺口的可见症状出在别处。工作区浏览器的会话列表（`WorkspaceBrowser.module.css` 中的 `.list`）是侧边栏里唯一的滚动区域，而每一行的尾部内容都紧贴该行 8px 的右内边距——`rows/Rows.module.css` 中的 `.time` 取 `flex: none`，hover 时取代它的操作按钮也是如此。于是覆盖式滚动条会画在相对时间戳之上。只在这一个列表里预留空间，滚动条本身仍然没有主题，因此两部分合为一次变更。
|
||||
|
||||
## 决策
|
||||
|
||||
`packages/client/ui-theme/src/styles/scrollbar.css` 是这四个 token 的唯一消费方，也是壳的导入链（`packages/client/web/src/base.css`）中第五张 ui-theme 样式表。它排在 `design-platform.css` 之后，因为它读取那张样式表的 token。
|
||||
|
||||
规则挂在 `body` 上，而非 `html`。`design-platform.css` 在 `body` 上声明 `--dsw-alias-*` token，暗色覆盖挂在 `body[data-ds-dark-theme]` 上，而自定义属性只向下继承；挂在 `html` 上的规则会把它们解析为 guaranteed-invalid 值，此时 `scrollbar-color` 计算为 `auto`，主题完全不起作用。
|
||||
|
||||
`scrollbar-width` 与 `scrollbar-color` 声明在 `body, body *` 上，而不是只在顶层声明一次。继承传下去的是已经在 `body` 处代入完成的颜色值，因此后代元素重新绑定这层间接变量也无法改变自己的滚动条；逐元素重新声明使每个元素按它自己看到的取值代入变量。`scrollbar-width` 本身就不是可继承属性，无论如何都需要逐元素声明。`::-webkit-scrollbar*` 伪元素同样不继承，因此以不加限定的选择器匹配。
|
||||
|
||||
两侧都读取同一组间接变量 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover`，它们在 `body` 上绑定到 l1（基础表面）token。**这就是重新绑定契约，也是单看 CSS 无法得知的部分**：抬升表面在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`，这一次重新绑定同时作用于标准属性和 WebKit 伪元素。这组变量必须成对重新绑定；只改静止态滑块会让 hover 状态仍留在基础表面的 token 上。目前有四处抬升表面做了重新绑定：命令浮层、斜杠菜单、模型选择面板与设置面板。后两者把声明写在抬升面板上而非滚动的后代元素上，因为抬升层级是这个表面的属性，而自定义属性会继承到真正滚动的那个子元素。
|
||||
|
||||
轨道与两条滚动条相交的角落保持透明，因此滑块是以其下滚动的任何表面为背景被看到；只有滑块及其 hover 状态带 token 颜色。
|
||||
|
||||
`.list` 声明 `scrollbar-gutter: stable`，使滚动条位于行的旁边而非行的上方。取 `stable` 而非 `auto`，因为 `auto` 只在列表确实溢出时才预留空位：那样展开一个工作区分组时，所有行会在列表开始滚动的那一刻发生水平位移。`stable` 的预留是无条件的，行不会移动。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**在每个滚动组件的样式表里各写一份 `::-webkit-scrollbar` 规则。** 之所以否决：客户端共有分布在九个包中的十三个滚动容器，每一个都要带上同一段规则，而第十四个会在没有任何门禁报错的情况下漏掉主题。由设计 token 驱动的皮肤应当归属于拥有这些 token 的包。
|
||||
|
||||
**提供一个工具类，由各滚动容器自行加上。** 重复同样被消除，但失败方式依旧存在：新的滚动容器只有在作者记得加类名时才有主题，而遗漏在评审中看不出来。`body, body *` 这种写法没有需要记住的启用步骤；确实想要不同滚动条的容器可以覆盖间接变量，这与抬升表面使用的机制相同。
|
||||
|
||||
**把这两个属性绑定在 `html` 上。** 这是文档级皮肤最自然的落点，而它的失败是可测量的：规则挂在 `html` 上时，chromium 中滚动容器计算出的 `scrollbar-color` 为 `auto`，因为别名 token 在那个作用域内不存在。
|
||||
|
||||
**只声明一次，靠继承下传。** 匹配的元素更少，但它破坏重新绑定契约——继承携带的是代入后的颜色，而不是变量引用，因此抬升表面无法给自己的滚动条换色。它本身也不完整，因为 `scrollbar-width` 不继承。
|
||||
|
||||
**改用内边距而不是预留空位（给 `.list` 加右内边距，或把 `.time` 向内移）。** 之所以否决：内边距无论滚动条是否存在都生效，因此在常见的短列表情形下白白占用横向空间；而且它只修好一个容器，其余每个滚动区域的内容仍然压在滚动条之下。
|
||||
|
||||
**给 `.list` 用 `scrollbar-gutter: auto`。** 空位在列表溢出时出现，也就是滚动条存在的时候。之所以否决：侧边栏的列表会随分组展开与收起而伸缩，因此空位会在用户光标之下出现又消失，并带动行一起位移。
|
||||
|
||||
## 后果
|
||||
|
||||
- 客户端的每个滚动容器都绘制带主题的滑块：亮色基础表面为 `rgb(229, 229, 229)`，暗色基础表面为 `rgb(60, 60, 61)`，重新绑定到 l2 的暗色抬升表面为 `rgb(84, 85, 87)`。
|
||||
- 两种渲染分别指定，因此改动滑块的几何或 hover 行为需要改两处：一处在 `scrollbar-width`／`scrollbar-color`，一处在伪元素。让两者都经由这组间接变量，把这份重复限制在 Firefox 与 WebKit 不共用的那些属性上。
|
||||
- `body *` 匹配所有元素，涉及的两个属性其效果本就被浏览器限制在实际会滚动的元素上。代价是一个覆盖面很宽的选择器；另一种选择是一个不生效的重新绑定契约。
|
||||
- 工作区列表在任何列表长度下都永久少了预留空位那一条宽度。这正是该修复换来的代价：以稳定的行几何，换掉只在列表较短时才可读的时间戳。
|
||||
- 调色板中没有轨道 token，因此日后若设计需要不透明轨道，要新增一个别名 token，而不是在这张样式表里写字面颜色。
|
||||
|
||||
## 测试
|
||||
|
||||
三份单元测试读取磁盘上的 CSS 文本。`ui-theme/tests/scrollbar-styles.spec.ts` 从 `design-platform.css` 中扫描出滚动条 token 集合，而不是把它写死，因此新增、重命名或删除 token 时断言会随之变化；它检查每个 token 都有消费方，且每处抬升表面重新绑定的都是完整的一对。`web/tests/base-styles.spec.ts` 锁定导入顺序，以及 `base.css` 列出的每张样式表确实存在。`ui-workspace/tests/browser-styles.spec.ts` 锁定 `.list` 上的空位预留。
|
||||
|
||||
`apps/web/tests/sidebar-scrollbar.e2e.ts` 覆盖只有真实渲染引擎才能报告的两个事实：预留条带的宽度，以及代入后的 `scrollbar-color`。它不需要任何模型调用——列表只要溢出即可——因此以只读方式复用一份既有的已提交 fixture（测试前置数据）来铺入冷会话。
|
||||
|
||||
在构建产物客户端上于 headless chromium 中读取计算值确认，这正是区分「token 链真正生效」与「语法合法」的手段：滚动容器在两套调色板下分别计算出 l1 的滑块颜色，而重新绑定间接变量的容器计算出 l2 的颜色，证明重新绑定作用到了计算值，而不只是作用到自定义属性上。
|
||||
|
||||
headless chromium 绘制的是覆盖式滚动条，因此其中预留空位不会缩小 `clientWidth`。该预留表现为列表上非零的 `offsetWidth - clientWidth` 条带；仅凭内容区几何无法证明它，而把时间元素右边缘与内容区右边缘做比较的断言，在有无预留的两种状态下都成立，因此它的通过或失败取决于平台的滚动条样式，而不是取决于被测的那条声明。
|
||||
202
apps/web/tests/sidebar-scrollbar.e2e.ts
Normal file
202
apps/web/tests/sidebar-scrollbar.e2e.ts
Normal file
@@ -0,0 +1,202 @@
|
||||
// Web e2e scenario: the sidebar session list's scrollbar as the browser
|
||||
// actually lays it out — the observable half of the themed-scrollbar change
|
||||
// (packages/client/ui-theme/src/styles/scrollbar.css plus the
|
||||
// `scrollbar-gutter: stable` reservation on WorkspaceBrowser's `.list`). The
|
||||
// ui-theme/ui-workspace unit specs read the CSS text; only a real engine
|
||||
// reports the reserved gutter width and the substituted `scrollbar-color`, so
|
||||
// those two facts live here.
|
||||
//
|
||||
// Zero model calls: the list only has to overflow, so the scenario seeds many
|
||||
// cold sessions from another spec's committed fixture (seeded-history's
|
||||
// seed.jsonl, reused read-only — this spec needs row count, not new recorded
|
||||
// content) and never launches a replay row. A stray stream would fail loud
|
||||
// with NO_ADAPTER.
|
||||
//
|
||||
// Headless-chromium caveat, load-bearing for what is asserted below: chromium
|
||||
// paints an OVERLAY scrollbar that consumes no layout width. Comparing the
|
||||
// time element's right edge against the list's client-area right edge
|
||||
// therefore holds with and without the reservation and proves nothing; the
|
||||
// reserved band width is the only layout signal that distinguishes the two
|
||||
// states. See the assertions for which one is the control.
|
||||
import { readFile } from 'node:fs/promises'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import type { Browser, Page } from 'playwright'
|
||||
import { chromium } from 'playwright'
|
||||
import { afterAll, beforeAll, describe, expect, it, onTestFailed } from 'vitest'
|
||||
import { launchWebScaffold, seedSession, watchConsole, webSnapshotMode, type WebScaffold } from './scaffold.ts'
|
||||
import { saveFailureShot } from './support.ts'
|
||||
|
||||
const SEED = fileURLToPath(new URL('./snapshots/seeded-history/seed.jsonl', import.meta.url))
|
||||
const MODE = webSnapshotMode()
|
||||
/** Enough rows that the list overflows the 800px-tall viewport's sidebar; the scenario asserts the overflow rather than trusting it. */
|
||||
const SEED_COUNT = 24
|
||||
|
||||
/** Geometry and resolved scrollbar style of one scroll container, measured in the page. */
|
||||
interface ListMetrics {
|
||||
/** Resolved `scrollbar-gutter`. */
|
||||
gutter: string
|
||||
/** Resolved `scrollbar-width`. */
|
||||
width: string
|
||||
/** Resolved `scrollbar-color` (thumb then track). */
|
||||
color: string
|
||||
/** The thumb half of `scrollbar-color`, split off the track half. */
|
||||
thumb: string
|
||||
/** `--dsw-alias-scrollbar-bg-l1` resolved on the list into the same colour serialization `scrollbar-color` reports. */
|
||||
token: string
|
||||
/** True when the list actually scrolls. */
|
||||
overflows: boolean
|
||||
/** Border-box width minus client width: the space the scrollbar takes out of the content area. */
|
||||
band: number
|
||||
/** Client-area right edge in viewport coordinates (`clientWidth` excludes the scrollbar band). */
|
||||
clientRight: number
|
||||
/** Border-box right edge in viewport coordinates. */
|
||||
borderRight: number
|
||||
/** Right edge of the first row's relative-time element, the content the unreserved bar covered. */
|
||||
timeRight: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Measure the sidebar list in the page.
|
||||
* @param page - the page under test.
|
||||
* @returns the list's resolved scrollbar style and the geometry the fix changes.
|
||||
*/
|
||||
function measureList(page: Page): Promise<ListMetrics> {
|
||||
return page.evaluate(() => {
|
||||
const list = document.querySelector<HTMLElement>('[role="tree"][aria-label="Sessions"]')
|
||||
if (list === null) throw new Error('sidebar session list not in the DOM')
|
||||
const time = list.querySelector<HTMLElement>('[class*="time"]')
|
||||
if (time === null) throw new Error('no row relative-time element in the sidebar list')
|
||||
// The token needs the same serialization `scrollbar-color` reports: the
|
||||
// palette sheet writes it in whatever notation it chose, so it is
|
||||
// resolved through a probe element's `color`. The probe is appended to
|
||||
// the list so `var()` substitution happens where the list sits in the
|
||||
// cascade — the token reaching THIS element is the claim.
|
||||
const probe = document.createElement('span')
|
||||
list.append(probe)
|
||||
probe.style.color = 'var(--dsw-alias-scrollbar-bg-l1)'
|
||||
const token = getComputedStyle(probe).color
|
||||
probe.remove()
|
||||
const style = getComputedStyle(list)
|
||||
// `scrollbar-color` serializes as `<thumb> <track>`; both halves are
|
||||
// functional colours, so the split is on the space before the track's
|
||||
// opening token, not on every space.
|
||||
const thumb = style.scrollbarColor.replace(/\s+rgba?\([^)]*\)$/, '')
|
||||
return {
|
||||
gutter: style.scrollbarGutter,
|
||||
width: style.scrollbarWidth,
|
||||
color: style.scrollbarColor,
|
||||
thumb,
|
||||
token,
|
||||
overflows: list.scrollHeight > list.clientHeight,
|
||||
band: list.getBoundingClientRect().width - list.clientWidth,
|
||||
clientRight: list.getBoundingClientRect().left + list.clientWidth,
|
||||
borderRight: list.getBoundingClientRect().right,
|
||||
timeRight: time.getBoundingClientRect().right,
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/**
|
||||
* Reveal the seeded rows: every seeded session is unattached, so they all sit
|
||||
* in the collapsed Ungrouped bucket. Converges on expanded rather than
|
||||
* clicking once — startup auto-selection can expand the bucket first, and a
|
||||
* second click would collapse it again. Hand-rolled polling because
|
||||
* `expect.poll` is test-scoped and this runs in `beforeAll`.
|
||||
* @param page - the page under test.
|
||||
*/
|
||||
async function expandSeededSessions(page: Page): Promise<void> {
|
||||
const bucket = page.getByText('Ungrouped', { exact: true }).locator('..').locator('..')
|
||||
await bucket.waitFor({ timeout: 15_000 })
|
||||
const rows = page.locator('[role="tree"][aria-label="Sessions"] [role="treeitem"]')
|
||||
const deadline = Date.now() + 30_000
|
||||
for (;;) {
|
||||
if (await bucket.getAttribute('aria-expanded') !== 'true') {
|
||||
await page.getByText('Ungrouped', { exact: true }).click()
|
||||
}
|
||||
if (await bucket.getAttribute('aria-expanded') === 'true' && await rows.count() > SEED_COUNT / 2) return
|
||||
if (Date.now() > deadline) {
|
||||
throw new Error(`Ungrouped bucket never revealed more than ${SEED_COUNT / 2} rows`)
|
||||
}
|
||||
await page.waitForTimeout(200)
|
||||
}
|
||||
}
|
||||
|
||||
describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thumb)', () => {
|
||||
let scaffold: WebScaffold
|
||||
let browser: Browser
|
||||
let page: Page
|
||||
let tripwire: ReturnType<typeof watchConsole>
|
||||
|
||||
beforeAll(async () => {
|
||||
scaffold = await launchWebScaffold({})
|
||||
const fixture = await readFile(SEED, 'utf8')
|
||||
for (let index = 0; index < SEED_COUNT; index += 1) {
|
||||
await seedSession(scaffold, fixture, `sidebar-scrollbar-web-e2e-${String(index).padStart(2, '0')}`)
|
||||
}
|
||||
browser = await chromium.launch()
|
||||
// Shorter than the other scenarios' 1000px so SEED_COUNT rows overflow
|
||||
// the list with room to spare.
|
||||
page = await browser.newPage({ viewport: { width: 1680, height: 800 } })
|
||||
tripwire = watchConsole(page)
|
||||
await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
|
||||
await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
|
||||
await expandSeededSessions(page)
|
||||
}, 180_000)
|
||||
|
||||
afterAll(async () => {
|
||||
await browser?.close()
|
||||
await scaffold?.close()
|
||||
})
|
||||
|
||||
it('reserves a scrollbar gutter on the overflowing session list', async () => {
|
||||
onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-scrollbar-gutter'))
|
||||
// Vacuity guard: with a non-overflowing list `stable` still reserves, but
|
||||
// the scenario would no longer be reproducing the reported situation.
|
||||
await expect.poll(async () => (await measureList(page)).overflows, { timeout: 10_000 }).toBe(true)
|
||||
const metrics = await measureList(page)
|
||||
expect(metrics.gutter).toBe('stable')
|
||||
// The control. `band > 0` is the whole observable effect of the
|
||||
// reservation: the scrollbar is taken out of the content area instead of
|
||||
// drawn over it. Removing the declaration makes it exactly 0. The value
|
||||
// itself is not pinned — it tracks `scrollbar-width` and the platform.
|
||||
expect(metrics.band).toBeGreaterThan(0)
|
||||
// With the band reserved, the row's relative time — flush against the
|
||||
// row's right padding, the element the unreserved bar covered — ends
|
||||
// inside the content area, clear of the bar. Alone this would be vacuous
|
||||
// under chromium's overlay scrollbar (see the file header); it is
|
||||
// meaningful only conjoined with the band assertion above.
|
||||
expect(metrics.timeRight).toBeLessThanOrEqual(metrics.clientRight)
|
||||
expect(metrics.clientRight).toBeLessThan(metrics.borderRight)
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
}, 60_000)
|
||||
|
||||
it('resolves the themed thumb colour on the list in both palettes', async () => {
|
||||
onTestFailed(() => saveFailureShot(page, 'web-e2e-sidebar-scrollbar-theme'))
|
||||
const light = await measureList(page)
|
||||
// `thin`, not `auto`: the sheet's per-element declaration reached a
|
||||
// container it never names.
|
||||
expect(light.width).toBe('thin')
|
||||
// A concrete colour, not `auto`, and byte-equal to the alias token
|
||||
// resolved on this element: the indirection carried the token here rather
|
||||
// than falling back to the UA thumb.
|
||||
expect(light.color).not.toBe('auto')
|
||||
expect(light.thumb).toBe(light.token)
|
||||
// Transparent track, so the thumb reads against the scrolling surface.
|
||||
expect(light.color.endsWith('rgba(0, 0, 0, 0)')).toBe(true)
|
||||
// The dark palette declares different scrollbar tokens; driving the body
|
||||
// attribute pins the cascade the way lifecycle-chrome does (the Settings
|
||||
// gesture that sets it is owned there).
|
||||
await page.evaluate(() => { document.body.setAttribute('data-ds-dark-theme', '') })
|
||||
const dark = await measureList(page)
|
||||
expect(dark.thumb).toBe(dark.token)
|
||||
expect(dark.thumb).not.toBe(light.thumb)
|
||||
await page.evaluate(() => { document.body.removeAttribute('data-ds-dark-theme') })
|
||||
expect((await measureList(page)).thumb).toBe(light.thumb)
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
}, 60_000)
|
||||
|
||||
it.skipIf(MODE === 'record')('issued zero model calls and stayed clean', () => {
|
||||
expect(tripwire.warnings).toEqual([])
|
||||
expect(tripwire.pageErrors).toEqual([])
|
||||
})
|
||||
})
|
||||
@@ -15,6 +15,10 @@
|
||||
min-width: 220px;
|
||||
max-height: 320px;
|
||||
overflow-y: auto;
|
||||
/* Elevated surface: the scrollbar thumb takes the l2 elevation tokens
|
||||
(see ui-theme styles/scrollbar.css for the rebinding contract). */
|
||||
--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
|
||||
--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
|
||||
border: 1px solid var(--dsw-alias-border-inverted);
|
||||
border-radius: 12px;
|
||||
background: var(--dsw-specific-menu);
|
||||
|
||||
@@ -77,6 +77,13 @@
|
||||
background: var(--dsw-specific-input-major);
|
||||
box-shadow: var(--dsw-shadow-lv3);
|
||||
color: var(--dsw-alias-label-primary);
|
||||
/* Elevated surface: the scrollbar thumb takes the l2 elevation tokens.
|
||||
Declared here rather than on the scrolling `.groups` child so the
|
||||
elevation choice sits with the surface; the custom properties inherit
|
||||
down to whichever descendant actually scrolls (see ui-theme
|
||||
styles/scrollbar.css for the rebinding contract). */
|
||||
--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
|
||||
--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
|
||||
}
|
||||
|
||||
.status,
|
||||
|
||||
@@ -74,6 +74,13 @@
|
||||
overflow: hidden;
|
||||
background: var(--dsw-alias-bg-layer-1);
|
||||
box-shadow: var(--dsw-shadow-lv3);
|
||||
/* Elevated surface: the scrollbar thumb takes the l2 elevation tokens.
|
||||
Declared on the panel rather than the scrolling `.options` child so the
|
||||
elevation choice sits with the surface; the custom properties inherit
|
||||
down to whichever descendant scrolls (see ui-theme
|
||||
styles/scrollbar.css for the rebinding contract). */
|
||||
--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
|
||||
--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
|
||||
}
|
||||
|
||||
/* Nav rail (figma .Setting-nav 501:29958): 188 wide, pad (12,22,12,0),
|
||||
|
||||
@@ -13,6 +13,10 @@
|
||||
max-width: 537px;
|
||||
max-height: 320px;
|
||||
overflow-y: auto;
|
||||
/* Elevated surface: the scrollbar thumb takes the l2 elevation tokens
|
||||
(see ui-theme styles/scrollbar.css for the rebinding contract). */
|
||||
--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2);
|
||||
--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2);
|
||||
padding: 4px;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/client/ui-theme/README.md
|
||||
README.md: 1227df357cb93241fcf28da9b74d7ba15207e9c5
|
||||
README.zh.md: cd87ede7264c8d47dd780acaa11128e83d7862f9
|
||||
README.md: 9bf232d506c599a6302c04d5769b43993d84dbf6
|
||||
README.zh.md: 84dba38d751b74c13f4af42c40484995900dfc12
|
||||
|
||||
@@ -4,6 +4,10 @@ English | [中文](README.zh.md)
|
||||
|
||||
Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the theme preference (`light`/`dark`/`system`, persisted under `dsh.theme`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens). Contract: api-contracts v3 §8.
|
||||
|
||||
`src/styles/` holds five sheets, all imported by the web shell's `base.css`: `base.css`, `design-platform.css`, `scrollbar.css`, `gradient-shadow-text.css`, and `shiki.css`. `scrollbar.css` is the sole consumer of the `--dsw-alias-scrollbar-*` tokens and must follow `design-platform.css`, which declares them.
|
||||
|
||||
Scrollbar rebinding contract: `scrollbar.css` binds `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover` on `body` to the l1 (base-surface) tokens, and both the standard `scrollbar-color` and the `::-webkit-scrollbar-thumb` rules read that pair. An elevated surface (menu, popover, dialog) sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container; one rebind retints both renderings. Reasoning and the measured computed values: [the scrollbar Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md).
|
||||
|
||||
## Model Experience
|
||||
|
||||
None, as the theme service manages a browser preference; nothing here reaches a model request.
|
||||
|
||||
@@ -4,6 +4,10 @@
|
||||
|
||||
主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有主题偏好（`light`／`dark`／`system`，以 `dsh.theme` 为键持久化），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。契约：api-contracts v3 §8。
|
||||
|
||||
`src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
|
||||
|
||||
滚动条重新绑定契约：`scrollbar.css` 在 `body` 上把 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover` 绑定到 l1（基础表面）token，标准属性 `scrollbar-color` 与 `::-webkit-scrollbar-thumb` 规则都读取这一组变量。抬升表面（菜单、浮层、对话框）在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`；一次重新绑定即可为两种渲染同时换色。推理过程与实测计算值见[滚动条 Agent Note](../../../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)。
|
||||
|
||||
## 模型体验
|
||||
|
||||
无。主题服务管理浏览器偏好；这里没有任何内容进入模型请求。
|
||||
|
||||
66
packages/client/ui-theme/src/styles/scrollbar.css
Normal file
66
packages/client/ui-theme/src/styles/scrollbar.css
Normal file
@@ -0,0 +1,66 @@
|
||||
/* Scrollbar skin: the sole consumer of the four --dsw-alias-scrollbar-*
|
||||
* tokens. Without it every scrolling region renders the UA scrollbar, which
|
||||
* ignores the theme — a light native bar over the dark palette.
|
||||
*
|
||||
* The rule sits on `body`, not `html`: design-platform.css declares the
|
||||
* --dsw-alias-* tokens on `body` (and the dark overrides on
|
||||
* `body[data-ds-dark-theme]`), and custom properties only inherit downward,
|
||||
* so an `html` rule resolves them to the guaranteed-invalid value and
|
||||
* `scrollbar-color` falls back to `auto`.
|
||||
*
|
||||
* `scrollbar-color` is an inherited property, so binding it once on `body`
|
||||
* reaches every scroll container without enumerating module class names.
|
||||
* `scrollbar-width` is NOT inherited, so it is applied to all elements.
|
||||
* The WebKit pseudo-elements are not inherited either, hence the unscoped
|
||||
* `::-webkit-scrollbar` rules.
|
||||
*
|
||||
* Surfaces pick their elevation by rebinding --dsh-scrollbar-thumb{,-hover}:
|
||||
* the l1 pair here is the base-surface default, and an elevated surface
|
||||
* (menu, popover, dialog) rebinds to the l2 pair on its own container. Both
|
||||
* the standard properties and the WebKit pseudo-elements read the
|
||||
* indirection, so one rebind reaches both renderings. */
|
||||
|
||||
body {
|
||||
--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l1);
|
||||
--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l1);
|
||||
}
|
||||
|
||||
/* `scrollbar-color` and `scrollbar-width` are declared on every element
|
||||
rather than inherited from `body`. Inheriting would pass down the COLOUR
|
||||
already substituted at `body`, so a descendant rebinding
|
||||
--dsh-scrollbar-thumb could not change it; re-declaring makes each element
|
||||
substitute the variable as it sees it, which is what gives an elevated
|
||||
surface a working rebind. `scrollbar-width` is not an inherited property
|
||||
at all, so it needs the per-element declaration regardless.
|
||||
|
||||
Track stays transparent so the thumb reads against whatever surface
|
||||
scrolls under it; only the thumb carries a token colour. */
|
||||
body,
|
||||
body * {
|
||||
scrollbar-width: thin;
|
||||
scrollbar-color: var(--dsh-scrollbar-thumb) transparent;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar {
|
||||
width: 8px;
|
||||
height: 8px;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-track {
|
||||
background: transparent;
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb {
|
||||
border-radius: 4px;
|
||||
background: var(--dsh-scrollbar-thumb);
|
||||
}
|
||||
|
||||
::-webkit-scrollbar-thumb:hover {
|
||||
background: var(--dsh-scrollbar-thumb-hover);
|
||||
}
|
||||
|
||||
/* Both scrollbars meeting in a corner: no separate token, so the corner
|
||||
matches the transparent track rather than the UA's opaque default. */
|
||||
::-webkit-scrollbar-corner {
|
||||
background: transparent;
|
||||
}
|
||||
311
packages/client/ui-theme/tests/scrollbar-styles.spec.ts
Normal file
311
packages/client/ui-theme/tests/scrollbar-styles.spec.ts
Normal file
@@ -0,0 +1,311 @@
|
||||
/**
|
||||
* Scrollbar stylesheet contract, asserted against the CSS text on disk: every
|
||||
* --dsw-alias-scrollbar-* token design-platform.css defines has a consumer,
|
||||
* scrollbar.css binds the base-surface pair through the rebindable
|
||||
* indirection, and elevated surfaces rebind that indirection in complete
|
||||
* pairs. The expected token set is scanned out of design-platform.css, so
|
||||
* adding, renaming, or dropping a scrollbar token moves these assertions with
|
||||
* it.
|
||||
*/
|
||||
import { readdirSync, readFileSync } from 'node:fs'
|
||||
import { join } from 'node:path'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
|
||||
/** One flattened CSS rule: its comma-separated selector parts and its declarations in source order. */
|
||||
interface CssRule {
|
||||
selectors: string[]
|
||||
declarations: [property: string, value: string][]
|
||||
}
|
||||
|
||||
const STYLES = new URL('../src/styles/', import.meta.url)
|
||||
const PACKAGES_DIR = fileURLToPath(new URL('../../../', import.meta.url))
|
||||
const read = (name: string): string => readFileSync(fileURLToPath(new URL(name, STYLES)), 'utf8')
|
||||
|
||||
const platformCss = read('design-platform.css')
|
||||
const scrollbarCss = read('scrollbar.css')
|
||||
|
||||
/** Body attribute selecting the dark palette; ui-layout's ThemePresenter sets it. */
|
||||
const DARK_ATTRIBUTE = '[data-ds-dark-theme]'
|
||||
/** Alias tokens under test: the prefix the elevation pairs share. */
|
||||
const TOKEN_PREFIX = '--dsw-alias-scrollbar-'
|
||||
/** Prefix of the rebindable indirection scrollbar.css owns. */
|
||||
const INDIRECTION_PREFIX = '--dsh-scrollbar-'
|
||||
|
||||
/**
|
||||
* Flatten a stylesheet into rules. Whitespace, declaration order, and trailing
|
||||
* semicolons are normalized away; nesting and at-rules are not handled, which
|
||||
* no sheet under test uses for scrollbar declarations.
|
||||
* @param css - stylesheet text.
|
||||
* @returns one entry per rule, in source order.
|
||||
*/
|
||||
function parseRules(css: string): CssRule[] {
|
||||
const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, ' ')
|
||||
const rules: CssRule[] = []
|
||||
// Destructuring defaults only satisfy noUncheckedIndexedAccess; both groups
|
||||
// are unconditional in the pattern.
|
||||
for (const [, selector = '', body = ''] of withoutComments.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
|
||||
const declarations = body
|
||||
.split(';')
|
||||
.map(part => part.trim())
|
||||
.filter(part => part.includes(':'))
|
||||
.map((part): [string, string] => {
|
||||
const colon = part.indexOf(':')
|
||||
return [part.slice(0, colon).trim(), part.slice(colon + 1).trim()]
|
||||
})
|
||||
rules.push({ selectors: selector.split(',').map(part => part.trim()), declarations })
|
||||
}
|
||||
return rules
|
||||
}
|
||||
|
||||
/**
|
||||
* Custom-property names a value reads.
|
||||
* @param value - declaration value, possibly with nested var() calls.
|
||||
* @returns every referenced custom-property name, in source order.
|
||||
*/
|
||||
function varReferences(value: string): string[] {
|
||||
return [...value.matchAll(/var\(\s*(--[\w-]+)/g)].map(([, name = '']) => name)
|
||||
}
|
||||
|
||||
/**
|
||||
* Every CSS file shipped as package source, excluding build output and
|
||||
* installed dependencies.
|
||||
* @returns absolute paths of the stylesheets under packages/.
|
||||
*/
|
||||
function packageStylesheets(): string[] {
|
||||
const found: string[] = []
|
||||
const walk = (dir: string): void => {
|
||||
for (const entry of readdirSync(dir, { withFileTypes: true })) {
|
||||
const path = join(dir, entry.name)
|
||||
if (entry.isDirectory()) {
|
||||
if (entry.name !== 'node_modules' && entry.name !== 'lib' && entry.name !== 'dist') walk(path)
|
||||
} else if (entry.name.endsWith('.css')) found.push(path)
|
||||
}
|
||||
}
|
||||
walk(PACKAGES_DIR)
|
||||
return found
|
||||
}
|
||||
|
||||
/**
|
||||
* Tokens a stylesheet reads through its rendering declarations, following its
|
||||
* own custom-property definitions transitively so a token reached only through
|
||||
* an indirection counts. The walk starts from the standard-property
|
||||
* declarations, so a defined-but-unread indirection contributes nothing.
|
||||
* @param rules - parsed rules of one stylesheet.
|
||||
* @returns every `--dsw-*` token the sheet's rendering declarations depend on.
|
||||
*/
|
||||
function tokensRendered(rules: CssRule[]): Set<string> {
|
||||
const definitions = new Map<string, string>()
|
||||
const pending: string[] = []
|
||||
for (const rule of rules) {
|
||||
for (const [property, value] of rule.declarations) {
|
||||
if (property.startsWith('--')) definitions.set(property, value)
|
||||
else pending.push(value)
|
||||
}
|
||||
}
|
||||
const reached = new Set<string>()
|
||||
const visited = new Set<string>()
|
||||
while (pending.length > 0) {
|
||||
for (const name of varReferences(pending.pop()!)) {
|
||||
if (name.startsWith('--dsw-')) reached.add(name)
|
||||
if (visited.has(name)) continue
|
||||
visited.add(name)
|
||||
const definition = definitions.get(name)
|
||||
if (definition !== undefined) pending.push(definition)
|
||||
}
|
||||
}
|
||||
return reached
|
||||
}
|
||||
|
||||
const platformRules = parseRules(platformCss)
|
||||
const scrollbarRules = parseRules(scrollbarCss)
|
||||
const sorted = (names: Iterable<string>): string[] => [...names].sort()
|
||||
|
||||
/**
|
||||
* Scrollbar tokens defined by the rules whose selectors carry (or do not
|
||||
* carry) the dark palette attribute.
|
||||
* @param dark - true to scan the dark blocks, false to scan the light blocks.
|
||||
* @returns the scrollbar token names defined there.
|
||||
*/
|
||||
function definedTokens(dark: boolean): Set<string> {
|
||||
const names = new Set<string>()
|
||||
for (const rule of platformRules) {
|
||||
if (rule.selectors.every(selector => selector.includes(DARK_ATTRIBUTE)) !== dark) continue
|
||||
for (const [property] of rule.declarations) {
|
||||
if (property.startsWith(TOKEN_PREFIX)) names.add(property)
|
||||
}
|
||||
}
|
||||
return names
|
||||
}
|
||||
|
||||
const lightTokens = definedTokens(false)
|
||||
const darkTokens = definedTokens(true)
|
||||
const allTokens = new Set([...lightTokens, ...darkTokens])
|
||||
|
||||
/** Every scrollbar token any package stylesheet references, mapped to the files referencing it. */
|
||||
const referencedTokens = new Map<string, string[]>()
|
||||
/** Every indirection property any package stylesheet outside ui-theme declares, mapped to its declaring rules. */
|
||||
const rebindRules: { file: string; rule: CssRule }[] = []
|
||||
|
||||
for (const file of packageStylesheets()) {
|
||||
const rules = parseRules(readFileSync(file, 'utf8'))
|
||||
for (const rule of rules) {
|
||||
let rebinds = false
|
||||
for (const [property, value] of rule.declarations) {
|
||||
if (property.startsWith(INDIRECTION_PREFIX) && file !== fileURLToPath(new URL('scrollbar.css', STYLES))) rebinds = true
|
||||
for (const token of varReferences(value)) {
|
||||
if (!token.startsWith(TOKEN_PREFIX)) continue
|
||||
referencedTokens.set(token, [...referencedTokens.get(token) ?? [], file])
|
||||
}
|
||||
}
|
||||
if (rebinds) rebindRules.push({ file, rule })
|
||||
}
|
||||
}
|
||||
|
||||
describe('design-platform.css scrollbar tokens', () => {
|
||||
it('defines the same scrollbar token set in the light and the dark block', () => {
|
||||
// A token present only in the light block silently keeps its light value
|
||||
// under the dark palette, since the dark block only overrides.
|
||||
expect(allTokens.size).toBeGreaterThan(0)
|
||||
expect(sorted(lightTokens)).toEqual(sorted(allTokens))
|
||||
expect(sorted(darkTokens)).toEqual(sorted(allTokens))
|
||||
})
|
||||
|
||||
it('resolves every scrollbar token to a static scale value, not to another alias', () => {
|
||||
// The alias layer is the only indirection in the token sheet: an alias
|
||||
// pointing at a second alias makes the dark override order-dependent.
|
||||
for (const rule of platformRules) {
|
||||
for (const [property, value] of rule.declarations) {
|
||||
if (!property.startsWith(TOKEN_PREFIX)) continue
|
||||
for (const reference of varReferences(value)) {
|
||||
expect(reference, `${property}: ${value}`).toMatch(/^--dsw-static-/)
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('scrollbar token consumers', () => {
|
||||
it('every defined scrollbar token is referenced by some package stylesheet', () => {
|
||||
// Before scrollbar.css existed these tokens had no consumer at all and
|
||||
// every scroll container rendered the unthemed UA bar. A fifth token, or a
|
||||
// rename on one side only, leaves the new name unreferenced here.
|
||||
expect(sorted(referencedTokens.keys())).toEqual(sorted(allTokens))
|
||||
})
|
||||
|
||||
it('every referenced scrollbar token is defined in design-platform.css', () => {
|
||||
// A dangling var() renders the UA default instead of failing loudly, so a
|
||||
// rename has to move the reference and the definition together.
|
||||
for (const [token, files] of referencedTokens) {
|
||||
expect(allTokens, files.join(', ')).toContain(token)
|
||||
}
|
||||
})
|
||||
})
|
||||
|
||||
describe('scrollbar.css base-surface binding', () => {
|
||||
const rendered = tokensRendered(scrollbarRules)
|
||||
|
||||
it('renders the l1 pair through the rebindable indirection', () => {
|
||||
// l1 is the base-surface default the indirection resolves to; the
|
||||
// indirection only counts as bound when a rendering declaration reads it.
|
||||
expect(rendered).toContain(`${TOKEN_PREFIX}bg-l1`)
|
||||
expect(rendered).toContain(`${TOKEN_PREFIX}hover-l1`)
|
||||
})
|
||||
|
||||
it('routes the standard property and the WebKit thumb through the same indirection', () => {
|
||||
// A rebind on an elevated container has to move the Firefox and the WebKit
|
||||
// rendering together, which only holds while both read the same variable.
|
||||
const declaration = (property: string, selectorPart: string): string | undefined => scrollbarRules
|
||||
.filter(rule => rule.selectors.includes(selectorPart))
|
||||
.flatMap(rule => rule.declarations)
|
||||
.findLast(([name]) => name === property)?.[1]
|
||||
const thumbColor = declaration('scrollbar-color', 'body')
|
||||
expect(thumbColor).toBeDefined()
|
||||
const indirection = varReferences(thumbColor!)[0]
|
||||
expect(indirection).toBe(`${INDIRECTION_PREFIX}thumb`)
|
||||
expect(varReferences(declaration('background', '::-webkit-scrollbar-thumb')!)).toEqual([indirection])
|
||||
})
|
||||
})
|
||||
|
||||
describe('scrollbar.css selectors', () => {
|
||||
const scrollbarColorSelectors = scrollbarRules
|
||||
.filter(rule => rule.declarations.some(([property]) => property === 'scrollbar-color'))
|
||||
.flatMap(rule => rule.selectors)
|
||||
|
||||
it('declares scrollbar-color only where the body-scoped tokens are visible', () => {
|
||||
// design-platform.css defines the alias tokens on `body`, and custom
|
||||
// properties inherit downward only: the same declaration on `html` or
|
||||
// `:root` resolves to the guaranteed-invalid value, which computes
|
||||
// scrollbar-color to `auto` and drops the theming entirely.
|
||||
expect(scrollbarColorSelectors.length).toBeGreaterThan(0)
|
||||
for (const selector of scrollbarColorSelectors) {
|
||||
expect(selector, selector).toMatch(/^body\b/)
|
||||
}
|
||||
})
|
||||
|
||||
it('defines the indirection where the alias tokens are visible', () => {
|
||||
const definesIndirection = ([property, value]: [string, string]): boolean =>
|
||||
property.startsWith(INDIRECTION_PREFIX) && value.includes(TOKEN_PREFIX)
|
||||
const hosts = scrollbarRules
|
||||
.filter(rule => rule.declarations.some(definesIndirection))
|
||||
.flatMap(rule => rule.selectors)
|
||||
expect(hosts.length).toBeGreaterThan(0)
|
||||
for (const selector of hosts) expect(selector, selector).toMatch(/^body\b/)
|
||||
})
|
||||
|
||||
it('re-declares the scrollbar properties per element rather than inheriting them', () => {
|
||||
// scrollbar-width is not an inherited property, and an inherited
|
||||
// scrollbar-color carries the colour already substituted at `body`, which
|
||||
// a descendant rebinding the indirection could no longer change.
|
||||
expect(scrollbarColorSelectors).toContain('body *')
|
||||
const widthSelectors = scrollbarRules
|
||||
.filter(rule => rule.declarations.some(([property]) => property === 'scrollbar-width'))
|
||||
.flatMap(rule => rule.selectors)
|
||||
expect(widthSelectors).toContain('body *')
|
||||
})
|
||||
})
|
||||
|
||||
describe('elevated surface rebinds', () => {
|
||||
it('at least one surface rebinds the indirection', () => {
|
||||
expect(rebindRules.length).toBeGreaterThan(0)
|
||||
})
|
||||
|
||||
it('each rebinding rule sets the thumb and the hover variable together', () => {
|
||||
// A surface rebinding only the resting colour keeps the l1 hover colour,
|
||||
// so the elevation is wrong only while the pointer is over the thumb.
|
||||
for (const { file, rule } of rebindRules) {
|
||||
const properties = rule.declarations.map(([property]) => property).filter(property => property.startsWith(INDIRECTION_PREFIX))
|
||||
expect(sorted(properties), `${file} ${rule.selectors.join(', ')}`).toEqual([
|
||||
`${INDIRECTION_PREFIX}thumb-hover`, `${INDIRECTION_PREFIX}thumb`,
|
||||
].sort())
|
||||
}
|
||||
})
|
||||
|
||||
it('each rebinding rule binds the indirection names scrollbar.css renders', () => {
|
||||
// A misspelled property name declares an unused variable, and the surface
|
||||
// silently keeps the base-surface colour.
|
||||
const rendered = new Set(
|
||||
scrollbarRules
|
||||
.flatMap(rule => rule.declarations)
|
||||
.filter(([property]) => !property.startsWith('--'))
|
||||
.flatMap(([, value]) => varReferences(value))
|
||||
.filter(name => name.startsWith(INDIRECTION_PREFIX)),
|
||||
)
|
||||
for (const { file, rule } of rebindRules) {
|
||||
for (const [property] of rule.declarations) {
|
||||
if (property.startsWith(INDIRECTION_PREFIX)) expect(rendered, `${file}: ${property}`).toContain(property)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
it('every rebind targets the l2 elevation pair', () => {
|
||||
for (const { file, rule } of rebindRules) {
|
||||
for (const [property, value] of rule.declarations) {
|
||||
if (!property.startsWith(INDIRECTION_PREFIX)) continue
|
||||
for (const token of varReferences(value)) {
|
||||
expect(token, `${file}: ${property}`).toMatch(/-l2$/)
|
||||
}
|
||||
}
|
||||
}
|
||||
})
|
||||
})
|
||||
@@ -207,6 +207,13 @@
|
||||
min-height: 0;
|
||||
overflow-y: auto;
|
||||
padding-bottom: 12px;
|
||||
/* Row trailing content (the relative time, and the hover action buttons
|
||||
that replace it) sits flush against the row's 8px right padding, so an
|
||||
overlaid scrollbar covers it. Reserving the gutter keeps the bar beside
|
||||
the rows instead of on top of them; `stable` holds the reservation when
|
||||
the list is short enough not to scroll, so expanding a group does not
|
||||
shift every row left. */
|
||||
scrollbar-gutter: stable;
|
||||
}
|
||||
|
||||
/* One workspace section: header row + expanded session run. Rows inside
|
||||
|
||||
48
packages/client/ui-workspace/tests/browser-styles.spec.ts
Normal file
48
packages/client/ui-workspace/tests/browser-styles.spec.ts
Normal file
@@ -0,0 +1,48 @@
|
||||
/**
|
||||
* WorkspaceBrowser scroll-region style contract, asserted against the CSS text
|
||||
* on disk: the session list reserves its scrollbar gutter so the scrollbar
|
||||
* cannot overlay row trailing content, and reserves it whether or not the list
|
||||
* currently overflows so expanding a group does not shift rows sideways.
|
||||
*/
|
||||
import { readFileSync } from 'node:fs'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
|
||||
const css = readFileSync(fileURLToPath(new URL('../src/client/WorkspaceBrowser.module.css', import.meta.url)), 'utf8')
|
||||
|
||||
/**
|
||||
* Declarations of one class rule, keyed by property with whitespace collapsed.
|
||||
* Declaration order and trailing semicolons are normalized away.
|
||||
* @param className - local class name, without the leading dot.
|
||||
* @returns the rule's declarations, or undefined when no such rule exists.
|
||||
*/
|
||||
function declarations(className: string): Map<string, string> | undefined {
|
||||
const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, ' ')
|
||||
const match = new RegExp(String.raw`(^|[\s,}])\.${className}\s*\{([^{}]*)\}`).exec(withoutComments)
|
||||
if (match === null) return undefined
|
||||
const found = new Map<string, string>()
|
||||
// The body group is unconditional in the pattern; the fallback only satisfies
|
||||
// noUncheckedIndexedAccess.
|
||||
for (const part of (match[2] ?? '').split(';')) {
|
||||
const colon = part.indexOf(':')
|
||||
if (colon === -1) continue
|
||||
found.set(part.slice(0, colon).trim(), part.slice(colon + 1).trim().replace(/\s+/g, ' '))
|
||||
}
|
||||
return found
|
||||
}
|
||||
|
||||
describe('WorkspaceBrowser.module.css list', () => {
|
||||
const list = declarations('list')
|
||||
|
||||
it('is the scrolling region', () => {
|
||||
expect(list).toBeDefined()
|
||||
expect(list!.get('overflow-y')).toBe('auto')
|
||||
})
|
||||
|
||||
it('reserves the scrollbar gutter unconditionally', () => {
|
||||
// Row trailing content sits flush against the row's right padding, so an
|
||||
// overlay scrollbar covers it. `stable` keeps the reservation when the list
|
||||
// is short enough not to scroll, so expanding a group does not shift rows.
|
||||
expect(list!.get('scrollbar-gutter')).toBe('stable')
|
||||
})
|
||||
})
|
||||
@@ -1,8 +1,10 @@
|
||||
/* Shell-owned global base: full-height mount plus the theme token sheets.
|
||||
* The four ui-theme sheets are the sole token source (--dsw-*); the shell
|
||||
* links them here so tokens exist before any plugin CSS lands. */
|
||||
* The five ui-theme sheets are the sole token source (--dsw-*); the shell
|
||||
* links them here so tokens exist before any plugin CSS lands. scrollbar.css
|
||||
* follows design-platform.css because it reads that sheet's tokens. */
|
||||
@import '@deepseek-ai/dsh-client-ui-theme/styles/base.css';
|
||||
@import '@deepseek-ai/dsh-client-ui-theme/styles/design-platform.css';
|
||||
@import '@deepseek-ai/dsh-client-ui-theme/styles/scrollbar.css';
|
||||
@import '@deepseek-ai/dsh-client-ui-theme/styles/gradient-shadow-text.css';
|
||||
@import '@deepseek-ai/dsh-client-ui-theme/styles/shiki.css';
|
||||
|
||||
|
||||
58
packages/client/web/tests/base-styles.spec.ts
Normal file
58
packages/client/web/tests/base-styles.spec.ts
Normal file
@@ -0,0 +1,58 @@
|
||||
/**
|
||||
* Shell base sheet contract, asserted against the CSS text on disk: base.css is
|
||||
* where the ui-theme token sheets enter the bundle, every sheet it names exists,
|
||||
* and scrollbar.css follows design-platform.css because it reads that sheet's
|
||||
* tokens.
|
||||
*/
|
||||
import { existsSync, readFileSync } from 'node:fs'
|
||||
import { fileURLToPath } from 'node:url'
|
||||
import { describe, expect, it } from 'vitest'
|
||||
|
||||
const THEME_PACKAGE = '@deepseek-ai/dsh-client-ui-theme'
|
||||
const baseCss = readFileSync(fileURLToPath(new URL('../src/base.css', import.meta.url)), 'utf8')
|
||||
|
||||
/**
|
||||
* Import specifiers of the sheet, in source order. Quote style and surrounding
|
||||
* whitespace are normalized away.
|
||||
* @param css - stylesheet text.
|
||||
* @returns each `@import` target in the order the sheet lists it.
|
||||
*/
|
||||
function importOrder(css: string): string[] {
|
||||
// The destructuring default only satisfies noUncheckedIndexedAccess; the
|
||||
// group is unconditional in the pattern.
|
||||
return [...css.matchAll(/@import\s+['"]([^'"]+)['"]/g)].map(([, specifier = '']) => specifier)
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a `<package>/styles/<file>` specifier to its path in the workspace.
|
||||
* The theme package maps `./styles/*` to `./src/styles/*`, so the sheets stay
|
||||
* on the source plane rather than needing a build.
|
||||
* @param specifier - import specifier from base.css.
|
||||
* @returns absolute path of the file the specifier names.
|
||||
*/
|
||||
function resolveThemeSheet(specifier: string): string {
|
||||
const name = specifier.slice(`${THEME_PACKAGE}/styles/`.length)
|
||||
return fileURLToPath(new URL(`../../ui-theme/src/styles/${name}`, import.meta.url))
|
||||
}
|
||||
|
||||
const imports = importOrder(baseCss)
|
||||
|
||||
describe('web shell base.css', () => {
|
||||
it('imports every sheet from the theme package and each one exists', () => {
|
||||
expect(imports.length).toBeGreaterThan(0)
|
||||
for (const specifier of imports) {
|
||||
expect(specifier.startsWith(`${THEME_PACKAGE}/styles/`), specifier).toBe(true)
|
||||
expect(existsSync(resolveThemeSheet(specifier)), specifier).toBe(true)
|
||||
}
|
||||
})
|
||||
|
||||
it('imports the scrollbar sheet after the token sheet it reads', () => {
|
||||
// Both sheets bind on `body`, so with scrollbar.css first the alias tokens
|
||||
// would still resolve; the order encodes the dependency direction so a
|
||||
// later specificity or selector change cannot silently invert it.
|
||||
const platform = imports.indexOf(`${THEME_PACKAGE}/styles/design-platform.css`)
|
||||
const scrollbar = imports.indexOf(`${THEME_PACKAGE}/styles/scrollbar.css`)
|
||||
expect(platform).toBeGreaterThanOrEqual(0)
|
||||
expect(scrollbar).toBeGreaterThan(platform)
|
||||
})
|
||||
})
|
||||
Reference in New Issue
Block a user