From fd743f3a3f5900ffcbcdbf29f722e3672a03d65b Mon Sep 17 00:00:00 2001 From: hectorqin <8m0v8c12sZDrY2infddElF+hectorqin@noreply.cnb.cool> Date: Fri, 18 Sep 2026 11:30:36 +0800 Subject: [PATCH] =?UTF-8?q?fix(web):=20=E4=BF=AE=E5=A5=BD=E5=9B=BE?= =?UTF-8?q?=E6=A0=87=E4=B8=8E=E6=96=87=E5=AD=97=E7=9A=84=E5=AF=B9=E9=BD=90?= =?UTF-8?q?=EF=BC=8C=E5=B9=B6=E8=AE=A9=E5=AD=97=E4=BD=93=E5=BA=A6=E9=87=8F?= =?UTF-8?q?=E4=B8=8D=E5=86=8D=E8=AF=B4=E8=B0=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 界面图标显示正常但歪，实测每个字形都偏离所在盒子中心 0.496em（半个盒子）， 也就是 9px 以上，且每一行歪的幅度还不一样。代价是三条互相独立的缺陷叠在 一起，而此前所有图标测试都只读 `cmap` 和字形名，一条都不覆盖这些位置。 一、`.icon` 把字体自己的行盒换成了一个方块（主因） `line-height: 0; display: inline-block; width: 1em; height: 1em` 会得到 一个**锚在基线上、向下一整个 em** 的盒子，而字形是围绕基线画的。于是墨迹贴在 盒子上沿、盒子下方整片是空的。UI 里每个容器都在居中这个盒子，盒子确实居中了， 字形却差了半个 em——这就是「显示正常但不对齐」，也是每行幅度不同的来源：各行的 容器不同，锚法就不同。 改为用字体自己的行盒（`line-height: 1`，不再给高度），只保留 `width: 1em` 这个字体给不了的东西（可预测的前进宽度），并补 `vertical-align: middle` 给 正文里行内出现的图标。**刻意不用 `transform`**：它能在 flex/grid 里生效 （`vertical-align` 在那里是惰性的），但它改的是绘制期位置，会让「图标占的位置」 和「看起来占的位置」不再一致。 二、字体度量与字形不自洽（次因） 表格声明上升部 960 / 下降部 -64（基线靠近 em 底部），而字形是按 `(GRID/2 - y)` 围绕 em 中心画的。两者各自自洽、互相矛盾，而输的是盒子。 现在上升部与下降部各取半个 em：**对称**不是审美——UI 里每个容器都在居中盒子， 只有度量对称时「居中盒子」和「居中字形」才是一回事。 同时修掉三处字段错位（都会静默通过解析）： - `OS/2` 的 `sTypoAscender/Descender` 一直写在 panose 区域，真正的排印窗口是 0/0； - `usWinAscent/Descent`（**无符号**）也写错了位置，读出来是 0 / 65506； - `fsSelection` 原本声明 BOLD，`usWeightClass` 是 500——一个不粗的字体谎称自己粗， 引擎就会合成加粗，而合成出来的图标是糊的。改为 `REGULAR | USE_TYPO_METRICS`。 `head` 的每个字形包围盒补一格下限：`more` 的三个点是用 0.06 单位描边写的， 四舍五入后两个轴各只剩一个点，包围盒为空——空包围盒是栅格化器有权跳过的图形， 于是「更多」按钮画出来是白的，而 `cmap` 依然映射它的码位，所以读表的断言全都 满意。`settings` 的路径解析出了一组跑到网格外的坐标（y 到 24.8、x 到 0.8）， 重画成真正的齿轮；`chevron-right` 与 `chevron-left` 共用同一个框却差一个单位。 三、图标按钮有两条构建路径 `manager-more` 是手搭的 ` + /> ) : null} ); diff --git a/web/src/ui/shelf-screen.tsx b/web/src/ui/shelf-screen.tsx index 3697846..07ab387 100644 --- a/web/src/ui/shelf-screen.tsx +++ b/web/src/ui/shelf-screen.tsx @@ -7,7 +7,7 @@ import type { AppSettings, ShelfSort } from '../store/settings.ts'; import { mountUI } from './mount.ts'; import { DENSITY_LABELS, ShelfSettingsPanel } from './shelf-settings.tsx'; import { sortBooks, shelfOrder } from './shelf-order.ts'; -import { Button, Icon, IconButton } from './toolkit.tsx'; +import { Icon, IconButton, IconTextButton } from './toolkit.tsx'; import { type ComponentChildren, type JSX, useEffect, useState } from './vendor/preact.ts'; export interface ShelfScreenOptions { @@ -513,10 +513,8 @@ export class ShelfScreen { 把书籍放进挂载的目录，扫一次，它们就会出现在这里

- - + this.options.onOpenManager('')} /> + void this.manualRefresh()} />
) diff --git a/web/src/ui/toolkit.tsx b/web/src/ui/toolkit.tsx index a3e8488..25dd578 100644 --- a/web/src/ui/toolkit.tsx +++ b/web/src/ui/toolkit.tsx @@ -47,6 +47,16 @@ export interface IconButtonProps { class?: string; } +/** + * A square control holding one glyph. + * + * `hidden` rather than a conditional: the attribute is what the stylesheet hides on, + * so a control that is not available disappears *and* keeps its place in the markup, + * and no caller has to decide which of the two it wants. + * + * The glyph is passed as a *name*, so it is always `.icon` — which is what makes the + * control's own alignment guaranteed rather than inherited from a caller's layout. + */ export function IconButton({ label, icon, onClick, disabled, hidden, class: className }: IconButtonProps): JSX.Element { return ( + ); +} + export interface PrimaryButtonProps { children: ComponentChildren; onClick?: (event: MouseEvent) => void; diff --git a/web/test/icons.test.ts b/web/test/icons.test.ts index 7d6fb41..3dd791c 100644 --- a/web/test/icons.test.ts +++ b/web/test/icons.test.ts @@ -94,7 +94,117 @@ describe('the icon font and its code point table', () => { }); }); -describe('the Icon component', () => { +/** + * The font's vertical metrics. + * + * These are the numbers that decide whether an icon is *aligned*, and they are the ones + * this file did not check while the icons were half an em out of place: `cmap` was + * verified, the glyph names were verified, and the metrics — the only part a layout reads + * — were not. + * + * The contract has two halves and both are needed: + * + * - the ascent and descent must be equal, because a `1em` box is symmetric and every + * container in the UI centres a box. Asymmetric metrics make "centre the box" and + * "centre the glyph" two different operations, and the difference is exactly the + * asymmetry — which is how the icons were misaligned by a different amount in every + * row of the product. + * - no glyph's ink may leave that window. A glyph that reaches outside the em paints + * outside the box the layout aligned to, which is the same defect by another route, + * and it is invisible to every check that only reads a table. + */ +function fontTables() { + const font = readFileSync(join(process.cwd(), 'src/styles/reader-icons.ttf')); + const numTables = font.readUInt16BE(4); + const offsets: Record = {}; + for (let i = 0; i < numTables; i++) { + const entry = 12 + i * 16; + offsets[font.toString('ascii', entry, entry + 4)] = font.readUInt32BE(entry + 8); + } + const unitsPerEm = font.readUInt16BE(offsets.head + 18); + const numGlyphs = font.readUInt16BE(offsets.maxp + 4); + return { + font, + offsets, + unitsPerEm, + numGlyphs, + hheaAscent: font.readInt16BE(offsets.hhea + 4), + hheaDescent: font.readInt16BE(offsets.hhea + 6), + typoAscent: font.readInt16BE(offsets['OS/2'] + 68), + typoDescent: font.readInt16BE(offsets['OS/2'] + 70), + winAscent: font.readUInt16BE(offsets['OS/2'] + 74), + winDescent: font.readUInt16BE(offsets['OS/2'] + 76), + selection: font.readUInt16BE(offsets['OS/2'] + 62), + weightClass: font.readUInt16BE(offsets['OS/2'] + 4), + }; +} + +describe('the font metrics', () => { + it('declares a symmetric window, so a centred box is a centred glyph', () => { + const t = fontTables(); + // The em's middle is the line the glyphs are drawn around, and the metrics have to + // say the same thing or every container that centres an icon centres it off by the + // difference. Zero would be symmetric too and is what the font used to declare by + // accident, which sends an engine to a fallback it has to guess at. + expect(t.hheaAscent).toBe(t.unitsPerEm / 2); + expect(t.hheaDescent).toBe(-t.unitsPerEm / 2); + expect(t.typoAscent).toBe(t.hheaAscent); + expect(t.typoDescent).toBe(t.hheaDescent); + }); + + it('declares Windows metrics that are unsigned and contain the em', () => { + const t = fontTables(); + // These were written at the wrong offsets for as long as the font existed, so they + // read as 0 / 65506 (-30, read unsigned) — a window that does not contain the glyphs + // it describes. An engine that falls back to them computes a box instead of using one. + expect(t.winAscent).toBe(t.unitsPerEm); + expect(t.winDescent).toBe(t.unitsPerEm); + }); + + it('tells engines to use the typographic metrics, and that the face is regular', () => { + const t = fontTables(); + // Without USE_TYPO_METRICS a Windows engine prefers the win pair, so getting the win + // metrics right above is only half of it. + expect(t.selection & 0x80).toBeTruthy(); + expect(t.selection & 0x40).toBeTruthy(); // regular + expect(t.selection & 0x20).toBeFalsy(); // ... and not bold + expect(t.weightClass).toBe(400); + }); + + it('keeps every glyph inside the em the metrics declare', () => { + const t = fontTables(); + // Walk `glyf` through `loca` and read each glyph's own bounding box — that box *is* + // the glyph's ink in its own coordinate system, so it is exactly what has to fit. + const offsets = [...Array(t.numGlyphs + 1)].map((_, i) => t.font.readUInt32BE(t.offsets.loca + 4 * i)); + for (let gid = 1; gid <= t.numGlyphs; gid++) { + if (offsets[gid + 1] === offsets[gid]) continue; + const start = t.offsets.glyf + offsets[gid]; + const yMin = t.font.readInt16BE(start + 4); + const yMax = t.font.readInt16BE(start + 8); + expect(yMin, `glyph ${gid} reaches below the descender`).toBeGreaterThanOrEqual(-t.unitsPerEm / 2); + expect(yMax, `glyph ${gid} reaches above the ascender`).toBeLessThanOrEqual(t.unitsPerEm / 2); + } + }); + + it('gives every non-blank glyph a non-empty bounding box', () => { + const t = fontTables(); + // An empty box is a glyph a rasteriser is entitled to skip, and `more` was one: three + // dots authored as 0.06-unit strokes rounded to a single point on each axis. The + // button drew blank while `cmap` still mapped its code point, so every table-reading + // assertion above was satisfied by a font that could not draw its own ellipsis. + const offsets = [...Array(t.numGlyphs + 1)].map((_, i) => t.font.readUInt32BE(t.offsets.loca + 4 * i)); + for (let gid = 1; gid <= t.numGlyphs; gid++) { + if (offsets[gid + 1] === offsets[gid]) continue; + const start = t.offsets.glyf + offsets[gid]; + const numContours = t.font.readInt16BE(start); + if (numContours <= 0) continue; + expect(t.font.readInt16BE(start + 6) - t.font.readInt16BE(start + 2), `glyph ${gid} has no width`).toBeGreaterThan(0); + expect(t.font.readInt16BE(start + 8) - t.font.readInt16BE(start + 4), `glyph ${gid} has no height`).toBeGreaterThan(0); + } + }); +}); + +describe('the icon box', () => { it('renders the glyph and hides it from assistive technology when decorative', async () => { const { Icon } = await import('../src/ui/icon.tsx'); const { render } = await import('../src/ui/vendor/preact.ts'); @@ -121,6 +231,64 @@ describe('the Icon component', () => { }); }); +/** + * The stylesheet's half of the contract. + * + * The font can only be right; whether the icon ends up where the font says is decided in + * CSS. These read `.icon` out of the real stylesheet, because the rules that matter are + * the ones that were wrong and a test that re-states them in its own words would have + * been updated alongside the bug. + */ +describe('the stylesheet', () => { + const css = readFileSync(join(process.cwd(), 'src/styles/reader.css'), 'utf8'); + const iconRule = /(^|\n)\.icon \{([^}]*)\}/.exec(css)?.[2] ?? ''; + const declaration = (property: string): string | undefined => + new RegExp(`(?:^|;)\\s*${property}\\s*:\\s*([^;]+)`).exec(iconRule)?.[1]?.trim(); + + it('lets the font own the line box instead of imposing a square on it', () => { + // `line-height: 1` gives the icon the font's own line box, which is symmetric because + // the font's metrics are. A fixed `height: 1em` plus `line-height: 0` anchors a box at + // the baseline while the ink is drawn around it, so the ink lands at the box's top + // edge and everything that centres the box centres the glyph half an em off — which is + // exactly what shipped, measured at 0.496em across `menu`, `close` and `folder`. + expect(declaration('line-height')).toBe('1'); + expect(declaration('height')).toBeUndefined(); + }); + + it('keeps an explicit advance width', () => { + // The one thing the layout needs that the font cannot supply: a row of icons and + // labels has to be laid out the same way whatever glyphs are in it. + expect(declaration('width')).toBe('1em'); + }); + + it('aligns on the middle for the rows that are not flex or grid', () => { + // In a paragraph, `baseline` would put the icon's baseline on the text's, and the icon + // has no baseline in the text sense — its ink is centred on the em. + expect(declaration('vertical-align')).toBe('middle'); + }); + + it('does not move the glyph with a transform', () => { + // A transform would also move the ink inside a flex or grid container, where + // `vertical-align` is inert — but it moves the glyph at paint time, so the space the + // icon reserves stops agreeing with the space it appears to occupy. + expect(declaration('transform')).toBeUndefined(); + }); + + it('is applied by every icon button, including the hand-built ones', () => { + // The glyph has to be `.icon` for any of the above to reach it, and a button that + // builds its own markup is where that gets forgotten. + const sources = ['toolkit.tsx', 'shelf-screen.tsx', 'manager-screen.tsx', 'reader-chrome.tsx', 'shelf-settings.tsx']; + for (const source of sources) { + const text = readFileSync(join(process.cwd(), 'src/ui', source), 'utf8'); + // A raw `