diff --git a/docs/operations/performance-evidence.md b/docs/operations/performance-evidence.md index 30de5b39..c1c6b1de 100644 --- a/docs/operations/performance-evidence.md +++ b/docs/operations/performance-evidence.md @@ -137,7 +137,8 @@ lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build Playwright 기본값은 스크롤바를 숨겨서, 첫 화면에 세로 스크롤바가 생기며 header가 밀리는 shift를 lab이 보지 못했다. 화면 쪽은 `:root`의 `scrollbar-gutter: stable`이 그 자리를 처음부터 잡는다. 다른 Playwright 게이트 - (시각 골든 포함)는 여전히 스크롤바를 숨긴다. + (시각 골든 포함)는 여전히 스크롤바를 숨긴다. 예외는 그 자리를 modal 가림막이 + 덮는지 보는 `tests/visual/scrollbar-gutter.visual.spec.ts` 하나다(1106/08-03). - preview 서버는 자기 프로세스 그룹으로 띄우고 끝날 때 그룹 전체를 멈춘다. `corepack`에만 신호를 보내던 때는 vite가 포트를 계속 잡고 있었다. diff --git a/docs/styling/design-system-platform.md b/docs/styling/design-system-platform.md index 5919321f..0618086b 100644 --- a/docs/styling/design-system-platform.md +++ b/docs/styling/design-system-platform.md @@ -213,6 +213,7 @@ primitive token -> semantic token -> component token - `button-primary-background` - `field-border-invalid` - `dialog-elevation` +- `dialog-backdrop`, `dialog-backdrop-on-surface`, `dialog-backdrop-weight` - `navigation-active-background` 컴포넌트 토큰은 제품별 variant를 만들기 위한 우회 경로가 아니다. 두 개 이상의 @@ -537,6 +538,31 @@ Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다. - Escape와 명시적 닫기 action을 제공한다. - 닫은 뒤 trigger 또는 안전한 대체 위치로 focus를 복원한다. - nested overlay와 route transition 중 orphan portal을 남기지 않는다. +- modal 가림막은 창 끝까지 덮는다. 스크롤바 자리도 덮는다(아래). + +**스크롤바 자리(1106/08-03).** `:root`의 `scrollbar-gutter: stable` +(`src/presentation/styles/theme/base.css`, 1105/15-05)은 일반(overlay가 아닌) +스크롤바를 쓰는 브라우저에서 문서가 스크롤되지 않아도 오른쪽에 스크롤바 폭 +(Chromium 15 px)을 비워 둔다. 그 자리에는 root의 배경색이 보인다. 페이지 내용, +header, 고정 위치 요소, modal의 `::backdrop`은 모두 그 자리 앞에서 끝난다. + +- modal이 열린 동안(`.ui-dialog[open]`) root 배경색을, 가림막을 페이지 바탕 위에 + 겹친 불투명한 색(`--dialog-backdrop-on-surface`)으로 바꾼다 + (`src/presentation/styles/theme/primitives.css`). 가림막 색 `--dialog-backdrop`과 + 이 색은 같은 비율(`--dialog-backdrop-weight`)을 읽는다. 첫 시도(`:modal`로 고른 + gradient 한 겹)는 Chromium에서 그 자리를 바꾸지 못했다. 페이지 바탕은 `body`가 + 같은 색으로 칠하므로 root 배경은 그 자리에만 보인다. 문서가 스크롤되면 그 + 자리에 스크롤바가 그려지고, 가림막은 스크롤바를 덮지 않는다(브라우저 동작). + 검사는 `tests/visual/scrollbar-gutter.visual.spec.ts`다. 스크롤바를 보이게 + 띄운 Chromium에서 그 자리와 바로 옆 가림막의 픽셀 색을 비교한다. +- header 띠는 그 자리 앞에서 끝나고, 그 자리는 페이지 바탕색으로 남는다. + 받아들인 모습이다. 스크롤되지 않는 화면에서만 보이고 기능 영향이 없다. header + 색으로 칠하려면 root 배경이 셸의 header 높이(4.5rem)와 색을 알아야 하고, 셸이 + 없는 화면(부팅 화면, 오류 화면)에서는 그 띠를 빼야 한다. 제품이 header를 창 + 끝까지 그리려면 그 결합을 감수하고 root 배경에 header 높이만큼의 띠를 더한다. +- 오른쪽에 붙는 drawer(`placement="end"`)를 열면 drawer와 창 끝 사이에 가림막 + 색 띠가 남는다. 템플릿은 이 배치를 쓰지 않고, 화면에서 확인하지 않았다. + RTL에서 스크롤바가 어느 쪽에 그려지는지도 확인하지 않았다. ### 8.3 Form 기준 diff --git a/docs/testing/frontend-platform-testing-strategy.md b/docs/testing/frontend-platform-testing-strategy.md index bd1443f8..e031a932 100644 --- a/docs/testing/frontend-platform-testing-strategy.md +++ b/docs/testing/frontend-platform-testing-strategy.md @@ -953,6 +953,13 @@ Playwright `toHaveScreenshot()`을 사용한다. `check-test-evidence`는 기준선 PNG가 4장 이상인지만 본다. 위 목록의 각 화면이 있는지는 검사하지 않는다. +골든과 달리 기준 이미지가 없는 시각 검사 1건이 같은 설정에서 돈다 +(1106/08-03). `tests/visual/scrollbar-gutter.visual.spec.ts`는 Chromium을 +`--hide-scrollbars` 없이 띄운다. 스크롤되지 않는 화면(`/not-found`, 390×844)에서 +drawer를 열고, 오른쪽 스크롤바 자리의 픽셀 색이 바로 옆 가림막과 같은지 본다. +골든은 스크롤바를 숨긴 채 찍으므로 그 자리에 스크롤바가 그려지는 경우를 보지 +않는다. + 아직 기준선이 없고, 제품이 화면을 늘릴 때 추가할 후보: - 각 page template diff --git a/src/presentation/design-system/tokens/component.css b/src/presentation/design-system/tokens/component.css index c8e3a17c..7e04f38d 100644 --- a/src/presentation/design-system/tokens/component.css +++ b/src/presentation/design-system/tokens/component.css @@ -5,6 +5,23 @@ --field-border: var(--color-border-strong); --field-border-invalid: var(--color-danger); --dialog-elevation: var(--elevation-dialog); + /* 1106/08-03. The modal scrim: the content colour at this weight. + `--dialog-backdrop` is the translucent scrim `::backdrop` paints. + `--dialog-backdrop-on-surface` is that scrim already laid over the page + surface, an opaque colour, for the root background under the scrollbar + gutter while a modal is open (primitives.css). The two agree because a + browser blends a translucent colour over another in sRGB. */ + --dialog-backdrop-weight: 55%; + --dialog-backdrop: color-mix( + in oklab, + var(--color-content) var(--dialog-backdrop-weight), + transparent + ); + --dialog-backdrop-on-surface: color-mix( + in srgb, + var(--color-content) var(--dialog-backdrop-weight), + var(--color-surface) + ); --navigation-active-background: color-mix( in oklab, var(--color-action) 14%, diff --git a/src/presentation/styles/theme/base.css b/src/presentation/styles/theme/base.css index 71ccec31..e9b3d5dc 100644 --- a/src/presentation/styles/theme/base.css +++ b/src/presentation/styles/theme/base.css @@ -15,6 +15,10 @@ margin: 0; min-width: 20rem; min-height: 100vh; + /* 1106/08-03. The same colour as the root background. The page covers + the window except the scrollbar gutter, so the root background shows + only there, where primitives.css darkens it under an open modal. */ + background: var(--color-surface); } /* 08-06. Korean breaks between words, not between syllables. A word too diff --git a/src/presentation/styles/theme/primitives.css b/src/presentation/styles/theme/primitives.css index 565b67ad..fd6c9434 100644 --- a/src/presentation/styles/theme/primitives.css +++ b/src/presentation/styles/theme/primitives.css @@ -414,10 +414,27 @@ } .ui-dialog::backdrop { - background: color-mix(in oklab, var(--color-content) 55%, transparent); + background: var(--dialog-backdrop); backdrop-filter: blur(2px); } + /* 1106/08-03. `scrollbar-gutter: stable` (base.css) keeps a classic + scrollbar's strip on the right even when the page does not scroll. + The strip shows the root's background colour: `::backdrop`, like every + fixed box, ends at its left edge. While a modal is open the root + background colour is the scrim over the page surface, so the scrim + reaches the window edge. The page paints its own surface (`body`, + base.css), so this shows only in the strip. A page that scrolls has + its scrollbar there instead, as before. + The first attempt (a gradient layer over the surface, matched with + `:modal`) left the strip the surface colour in Chromium; this changes + the colour itself and matches on `[open]`, the attribute showModal() + sets. The Dialog primitive always opens with showModal(), so an open + `.ui-dialog` in a browser is modal. */ + :root:has(.ui-dialog[open]) { + background-color: var(--dialog-backdrop-on-surface); + } + .ui-drawer { width: var(--drawer-width); max-width: none; diff --git a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png index 5fc74252..84f5e939 100644 Binary files a/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png and b/tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/app-shell-compact-pseudo-drawer-chromium-visual-linux.png differ diff --git a/tests/visual/scrollbar-gutter.visual.spec.ts b/tests/visual/scrollbar-gutter.visual.spec.ts new file mode 100644 index 00000000..6ad4e93a --- /dev/null +++ b/tests/visual/scrollbar-gutter.visual.spec.ts @@ -0,0 +1,165 @@ +import { fileURLToPath } from "node:url"; + +import { + expect, + test, + type Page, +} from "../support/browser/strict-browser-test.ts"; +import { KO_MESSAGES } from "../../src/presentation/i18n/catalog.ts"; + +/** + * 1106/08-03. `scrollbar-gutter: stable` (base.css, 1105/15-05) keeps a + * classic scrollbar's strip on the right even when the page does not scroll. + * Only the root background paints that strip; the page and every fixed box, + * the modal `::backdrop` included, end at its left edge. The goldens run with + * Playwright's `--hide-scrollbars`, so this spec starts Chromium with the + * scrollbar most Windows and Linux desktops draw and reads the drawn pixels. + * Hit testing is no evidence here: the strip answers `null` either way. + */ +test.use({ + launchOptions: { + // `test.use` replaces the config's launchOptions whole: the font pin + // from playwright.visual.config.ts is repeated. + env: { + ...process.env, + FONTCONFIG_FILE: fileURLToPath(new URL("./fonts.conf", import.meta.url)), + }, + ignoreDefaultArgs: ["--hide-scrollbars"], + }, +}); + +type Colour = readonly number[]; +type Strip = Readonly<{ x: number; width: number }>; + +/** + * The largest channel difference the gutter may show against the strip + * beside it. The drawer's shadow (`--shadow-dialog`, 70 px blur) still + * darkens the strip beside the gutter by about 3 levels; rounding adds 1 or + * 2. In the light theme a gutter the scrim does not cover + * (the page surface against 55% of the content colour over it) differs by + * about 120. + */ +const SAME_COLOUR = 12; + +/** The mean colour of each strip, from one screenshot of the band. */ +async function stripColours( + page: Page, + band: Readonly<{ y: number; height: number }>, + strips: readonly Strip[], +): Promise { + const left = Math.min(...strips.map((strip) => strip.x)); + const right = Math.max(...strips.map((strip) => strip.x + strip.width)); + const png = await page.screenshot({ + animations: "disabled", + clip: { x: left, y: band.y, width: right - left, height: band.height }, + scale: "css", + }); + // Decoded in a blank page, so the page under test runs nothing extra. + const decoder = await page.context().newPage(); + try { + return await decoder.evaluate( + async ({ base64, offsets }) => { + const bytes = Uint8Array.from(atob(base64), (character) => + character.charCodeAt(0), + ); + const bitmap = await createImageBitmap( + new Blob([bytes], { type: "image/png" }), + ); + const canvas = new OffscreenCanvas(bitmap.width, bitmap.height); + const context = canvas.getContext("2d"); + if (context === null) throw new Error("no 2d canvas context"); + context.drawImage(bitmap, 0, 0); + return offsets.map(({ x, width }) => { + const { data } = context.getImageData(x, 0, width, bitmap.height); + const sums = [0, 0, 0]; + for (let index = 0; index < data.length; index += 4) { + for (let channel = 0; channel < 3; channel += 1) { + sums[channel] += data[index + channel]; + } + } + return sums.map((sum) => Math.round(sum / (data.length / 4))); + }); + }, + { + base64: png.toString("base64"), + offsets: strips.map((strip) => ({ x: strip.x - left, width: strip.width })), + }, + ); + } finally { + await decoder.close(); + } +} + +async function expectGutterLikeBeside( + page: Page, + geometry: Readonly<{ + band: Readonly<{ y: number; height: number }>; + beside: Strip; + gutter: Strip; + }>, + what: string, +) { + const [beside, gutter] = await stripColours(page, geometry.band, [ + geometry.beside, + geometry.gutter, + ]); + const difference = Math.max( + ...gutter.map((value, channel) => Math.abs(value - beside[channel])), + ); + // On failure, tells a rule that did not match from a colour not drawn. + const root = await page.evaluate(() => { + const style = getComputedStyle(document.documentElement); + return `${style.backgroundColor} / ${style.backgroundImage}, open dialogs ${document.querySelectorAll(".ui-dialog[open]").length}`; + }); + expect( + difference, + `${what}: gutter rgb(${gutter.join(" ")}), beside it rgb(${beside.join(" ")}); root background ${root}`, + ).toBeLessThanOrEqual(SAME_COLOUR); +} + +test("the open drawer's scrim covers the classic scrollbar gutter on a page that does not scroll", async ({ + page, +}) => { + await page.setViewportSize({ width: 390, height: 844 }); + await page.goto("/not-found"); + await expect(page.getByRole("heading", { level: 1 })).toHaveText( + KO_MESSAGES["page.notFound.title"], + ); + + const layout = await page.evaluate(() => ({ + windowWidth: window.innerWidth, + windowHeight: window.innerHeight, + // With the gutter empty, documentElement.clientWidth is the window + // width (08-R2); the page's own box ends at the gutter. + pageRight: Math.round(document.body.getBoundingClientRect().right), + scrolls: + document.documentElement.scrollHeight > + document.documentElement.clientHeight, + })); + expect(layout.scrolls, "a page that scrolls draws its scrollbar in the gutter").toBe( + false, + ); + expect( + layout.windowWidth - layout.pageRight, + "Chromium without --hide-scrollbars reserves a classic scrollbar's gutter", + ).toBeGreaterThanOrEqual(10); + + // A band at mid-height. The strip beside the gutter lies in the page's own + // padding, 5 px in from its edge so the scrim's 2 px blur stays inside it; + // the gutter strip keeps 3 px off both of its edges. + const geometry = { + band: { y: Math.round(layout.windowHeight / 2) - 20, height: 40 }, + beside: { x: layout.pageRight - 10, width: 5 }, + gutter: { x: layout.pageRight + 3, width: layout.windowWidth - layout.pageRight - 6 }, + }; + await expectGutterLikeBeside(page, geometry, "closed, the gutter shows the page surface"); + + const menu = page.getByRole("button", { name: KO_MESSAGES["shell.menu"], exact: true }); + await menu.click(); + await expect(page.locator(".ui-drawer")).toHaveJSProperty("open", true); + await expectGutterLikeBeside(page, geometry, "open, the scrim reaches the window edge"); + + await page.keyboard.press("Escape"); + await expect(page.locator(".ui-drawer")).toHaveJSProperty("open", false); + await expectGutterLikeBeside(page, geometry, "closed again, the gutter shows the page surface"); +});