From d3112c8a53c9f707d10b74fb63535a2d700bf22f Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 17 Nov 2026 12:43:07 +0100 Subject: [PATCH 1/4] feat(annotate): let readers hide marks and dim the others on hover --- e2e/annotate.e2e.ts | 105 ++++++++++++++++++ .../annotate/docs/components/screenshot.md | 4 +- packages/annotate/docs/index.md | 10 +- packages/annotate/src/html.ts | 7 +- packages/annotate/src/script.ts | 6 +- packages/annotate/src/styles.ts | 19 +++- packages/annotate/test/annotate.test.ts | 21 +++- 7 files changed, 161 insertions(+), 11 deletions(-) diff --git a/e2e/annotate.e2e.ts b/e2e/annotate.e2e.ts index 90122e5c..80ace085 100644 --- a/e2e/annotate.e2e.ts +++ b/e2e/annotate.e2e.ts @@ -509,3 +509,108 @@ A wide row. expect(found.outside).toBe(true); expect(found.red).toBeGreaterThan(0); }); + +test("Hide marks hides the marks and arrows without zooming, and Copy still draws them", async ({ + page, + context, +}) => { + await context.grantPermissions(["clipboard-read", "clipboard-write"]); + await open( + page, + `::screenshot{src="/before.png" alt="Filter toolbar" viewport="640x250"} +:::annotation{x=4.5 y=28.7 w=40 h=44.4 color="red"} +The toolbar wraps. +::: + +:::annotation{x=60 y=40 w=10 h=10 side="right"} +Apply sits low. +::: +::`, + ); + const figure = page.locator("main .ca-screenshot"); + const toggle = figure.locator(".ca-hide"); + const marks = figure.locator(":is(.ca-mark,.ca-arrow)"); + await expect(marks).toHaveCount(3); + // Like Copy, it shows on hover, beside Copy. + await expect(toggle).toHaveCSS("opacity", "0"); + await figure.locator(".ca-frame > img:not(.ca-overlay)").hover(); + await expect(toggle).toHaveCSS("opacity", "1"); + const [hide, copy] = [await toggle.boundingBox(), await figure.locator(".ca-copy").boundingBox()]; + expect(hide!.x + hide!.width).toBeLessThan(copy!.x); + + await expect(toggle.locator(".ca-eye")).toBeVisible(); + await expect(toggle.locator(".ca-eye-off")).toBeHidden(); + await toggle.click(); + await expect(toggle.locator("input")).toBeChecked(); + // The icon says the marks are hidden. + await expect(toggle.locator(".ca-eye")).toBeHidden(); + await expect(toggle.locator(".ca-eye-off")).toBeVisible(); + for (const mark of await marks.all()) await expect(mark).toBeHidden(); + await expect(page.locator(".cz-dialog")).toHaveCount(0); + // It stays while the marks are hidden, so the reader can bring them back. + await page.mouse.move(0, 0); + await expect(toggle).toHaveCSS("opacity", "1"); + + await figure.locator(".ca-copy").click(); + await expect(figure.locator(".ca-copy-status")).toHaveText("Copied"); + const [copied, expected] = await figure.evaluate(async (node) => { + const [item] = await navigator.clipboard.read(); + const bitmap = await createImageBitmap(await item!.getType("image/png")); + const box = node.getBoundingClientRect(); + const stamp = node.querySelector(".ca-mark .ca-stamp")!; + const at = stamp.getBoundingClientRect(); + const scale = bitmap.width / (box.width + 32); + const canvas = new OffscreenCanvas(bitmap.width, bitmap.height); + const context = canvas.getContext("2d")!; + context.drawImage(bitmap, 0, 0); + const x = Math.round((at.left + at.width / 2 - box.left + 16) * scale); + const y = Math.round((at.top + 2 - box.top + 16) * scale); + const pixel = [...context.getImageData(x, y, 1, 1).data].slice(0, 3); + context.fillStyle = getComputedStyle(stamp).backgroundColor; + context.fillRect(0, 0, 1, 1); + return [pixel, [...context.getImageData(0, 0, 1, 1).data].slice(0, 3)]; + }); + for (const [index, channel] of copied.entries()) + expect(Math.abs(channel - expected[index]!)).toBeLessThan(24); + + // A zoomed copy keeps the reader's choice, and the keyboard brings the marks back. + await figure.locator(".ca-stage").click({ position: { x: 10, y: 10 } }); + await expect(page.locator(".cz-item .ca-mark")).toHaveCount(2); + for (const mark of await page.locator(".cz-item .ca-mark").all()) await expect(mark).toBeHidden(); + await page.keyboard.press("Escape"); + await expect(page.locator(".cz-dialog")).toHaveCount(0); + await toggle.locator("input").focus(); + await page.keyboard.press("Space"); + await expect(toggle.locator("input")).not.toBeChecked(); + for (const mark of await marks.all()) await expect(mark).toBeVisible(); +}); + +test("hovering a mark or its note fades the other marks", async ({ page }) => { + await open( + page, + `::screenshot{src="/after.png" alt="Filter toolbar on one row" viewport="640x250"} +:::annotation{x=5 y=30 w=15 h=20} +Search. +::: + +:::annotation{x=40 y=30 w=15 h=20} +Chips. +::: + +:::annotation{x=75 y=30 w=15 h=20} +Apply. +::: +::`, + ); + const mark = (n: number) => page.locator(`main .ca-mark[data-n="${n}"]`); + for (const n of [1, 2, 3]) await expect(mark(n)).toHaveCSS("opacity", "1"); + await page.locator('main .ca-notes li[data-n="2"]').hover(); + await expect(mark(2)).toHaveCSS("opacity", "1"); + await expect(mark(1)).toHaveCSS("opacity", "0.35"); + await expect(mark(3)).toHaveCSS("opacity", "0.35"); + await mark(3).hover(); + await expect(mark(3)).toHaveCSS("opacity", "1"); + await expect(mark(2)).toHaveCSS("opacity", "0.35"); + await page.mouse.move(0, 0); + for (const n of [1, 2, 3]) await expect(mark(n)).toHaveCSS("opacity", "1"); +}); diff --git a/packages/annotate/docs/components/screenshot.md b/packages/annotate/docs/components/screenshot.md index dbba3f54..724fdcdc 100644 --- a/packages/annotate/docs/components/screenshot.md +++ b/packages/annotate/docs/components/screenshot.md @@ -21,6 +21,8 @@ Extra filters collapse into **+2 filters**. - Each [`annotation`](/annotate/components/annotation) inside it draws one mark and its note. - A click anywhere on the screenshot zooms it, with its notes beside it. - The Copy button copies it as a PNG with its marks and notes drawn in. +- The Hide marks toggle beside it hides the marks and arrows, so readers can see what's under them. +- Hovering a mark or its note fades the other marks. ## Usage @@ -120,7 +122,7 @@ Copying needs setup in two cases: The image keeps its `alt` text. Each numbered mark is an image named by its number and note, such as "Annotation 1: Extra filters collapse into +2 filters." A side note's mark is named "Side note:" and its note. The arrows are hidden from screen readers. -The image is one tab stop that opens the [zoomed view](/zoom). The Copy button is labelled "Copy the screenshot with its marks", and a status announces "Copied" once the PNG is on the clipboard. +The image is one tab stop that opens the [zoomed view](/zoom). The Copy button is labelled "Copy the screenshot with its marks", and a status announces "Copied" once the PNG is on the clipboard. The Hide marks toggle is a checkbox labelled "Hide marks", and works without the script. ### Keyboard interactions diff --git a/packages/annotate/docs/index.md b/packages/annotate/docs/index.md index 8f885f2c..bb0dbf64 100644 --- a/packages/annotate/docs/index.md +++ b/packages/annotate/docs/index.md @@ -307,10 +307,10 @@ Annotate reads these [shared tokens](/guide/theming): | Token | Used for | | --- | --- | -| `--comark-background` | The Copy button, the slider's line and grip, the ring around stamps | -| `--comark-foreground` | The Copy button's icon, the slider's grip, the status after a copy | -| `--comark-border` | The outline around screenshots, the Copy button, the slider's grip | -| `--comark-accent` | The hovered Copy button | +| `--comark-background` | The Copy button, the Hide marks toggle, the slider's line and grip, the ring around stamps | +| `--comark-foreground` | The icons on Copy and Hide marks, the slider's grip, the status after a copy | +| `--comark-border` | The outline around screenshots, the Copy button, the Hide marks toggle, the slider's grip | +| `--comark-accent` | The hovered Copy button and Hide marks toggle | | `--comark-ring` | Focus rings | | `--comark-radius` | Corners of screenshots and notes | | `--comark-shadow` | The slider's handle and grip | @@ -344,7 +344,7 @@ A screenshot's or compare's `ink` sets `--ca-color`, `--ca-solid`, and `--ca-ink - Every block sits in a `.ca`. A screenshot's `figure.ca-screenshot` is inside it, and a compare is `.ca.ca-compare`, plus `.ca-slider` with `mode="slider"`. - A screenshot holds `.ca-heading` with its title in `.ca-label`, then `.ca-stage` with the image in `.ca-frame`, and a `figcaption` with the notes in `ol.ca-notes`. It has `.ca-left`, `.ca-right`, `.ca-top`, or `.ca-bottom` when it has side notes there. - A mark is a `.ca-mark` with its shape as a class, such as `.ca-box` or `.ca-circle`, and its number in `.ca-stamp`. A side note is a `.ca-callout` with its arrow in `.ca-arrow`. A mark, its arrow, and its note share a `data-n`. -- The Copy button is `.ca-copy`. A slider's divider is `.ca-handle`, with its knob in `.ca-grip`. +- The Copy button is `.ca-copy`, and the Hide marks toggle is `label.ca-hide`. A slider's divider is `.ca-handle`, with its knob in `.ca-grip`. ### Example diff --git a/packages/annotate/src/html.ts b/packages/annotate/src/html.ts index af730987..c0895498 100644 --- a/packages/annotate/src/html.ts +++ b/packages/annotate/src/html.ts @@ -96,6 +96,11 @@ const COPY = `` + `` + ``; +// A checkbox, so readers can hide the marks to see what's under them without the script. +const HIDE = + ``; const HEAD_DOWN = ``; // And rising from a note below it. const ARROW_UP = ``; @@ -304,7 +309,7 @@ async function parts( return { sides: sided.map((annotation) => ` ca-${annotation.side}`), heading: heading && `
${heading}
`, - frame: `
${body ?? `${attr(shot.alt)}`}${pins.join("")}${arrows.join("")}${copy ? COPY : ""}
`, + frame: `
${body ?? `${attr(shot.alt)}`}${pins.join("")}${arrows.join("")}${copy ? `${pins.length ? HIDE : ""}${COPY}` : ""}
`, callouts, notes: caption || notes ? `${caption}${notes ? `
    ${notes}
` : ""}` : "", }; diff --git a/packages/annotate/src/script.ts b/packages/annotate/src/script.ts index fa4d7fca..72433179 100644 --- a/packages/annotate/src/script.ts +++ b/packages/annotate/src/script.ts @@ -197,7 +197,7 @@ export function start(): () => void { const copying = "clipboard" in navigator && "ClipboardItem" in window; if (copying) root.setAttribute("data-annotate-copy", ""); const PAD = 16; - const SKIP = ".ca-copy,.ca-copy-status,.ca-overlay"; + const SKIP = ".ca-copy,.ca-copy-status,.ca-overlay,.ca-hide"; type Box = [x: number, y: number, width: number, height: number]; type Paint = (context: CanvasRenderingContext2D, source: HTMLImageElement) => void; type Made = { key: string; blob: Blob; url: string }; @@ -708,7 +708,9 @@ export function start(): () => void { : null)) : null; // Zoom copies the figure as it was, a moment's "Copied" included; a thumbnail is a button and gets no button inside. - for (const part of document.querySelectorAll(".cz-thumb :is(.ca-copy,.ca-copy-status)")) + for (const part of document.querySelectorAll( + ".cz-thumb :is(.ca-copy,.ca-copy-status,.ca-hide)", + )) part.remove(); for (const button of document.querySelectorAll(".cz-dialog .ca-copy[data-state]")) button.removeAttribute("data-state"); diff --git a/packages/annotate/src/styles.ts b/packages/annotate/src/styles.ts index 68907339..1c9eab68 100644 --- a/packages/annotate/src/styles.ts +++ b/packages/annotate/src/styles.ts @@ -80,6 +80,19 @@ export const css = `@layer comark{${[ ".ca-copy:focus-visible{outline:none;box-shadow:0 0 0 3px color-mix(in srgb,var(--_comark-ring) 50%,transparent)}", ".ca-screenshot:is(:hover,:focus-visible,:has(:focus-visible)) .ca-copy,.ca-copy:focus-visible,.ca-copy[data-state],.cz-dialog .ca-copy{opacity:1}", "@media (hover:none){[data-annotate-copy] .ca-copy{opacity:1}}", + // Hide marks shows where Copy does, beside it, and stays while the marks are hidden so the reader can bring them back. + // Hidden marks keep their paint, so Copy still draws them. + ".ca-hide{position:absolute;top:.5rem;right:.5rem;display:grid;place-items:center;width:1.75rem;height:1.75rem;box-sizing:border-box;border:1px solid var(--_comark-border);border-radius:calc(var(--_comark-radius) - 4px);background:var(--_comark-background);color:var(--_comark-foreground);cursor:pointer;opacity:0;transition:opacity .15s ease,background .15s ease}", + "[data-annotate-copy] .ca-frame:has(>.ca-copy)>.ca-hide{right:2.75rem}", + ".ca-frame:has(>.ca-hide)>.ca-copy-status{right:5rem}", + ".ca-hide:hover{background:var(--_comark-accent)}", + ".ca-hide input{position:absolute;inset:0;width:100%;height:100%;margin:0;opacity:0;cursor:pointer}", + ".ca-hide:has(:focus-visible){box-shadow:0 0 0 3px color-mix(in srgb,var(--_comark-ring) 50%,transparent)}", + ".ca-screenshot:is(:hover,:focus-visible,:has(:focus-visible)) .ca-hide,.ca-hide:has(:checked),.cz-dialog .ca-hide{opacity:1}", + "@media (hover:none){.ca-hide{opacity:1}}", + ".ca-hide svg{width:.875rem;height:.875rem;fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}", + ".ca-hide input:checked~.ca-eye,.ca-hide input:not(:checked)~.ca-eye-off{display:none}", + ".ca-frame:has(>.ca-hide>:checked)>:is(.ca-mark,.ca-arrow){visibility:hidden}", ".ca-copy svg{width:.875rem;height:.875rem;fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}", ".ca-copy-done,.ca-copy[data-state=done] .ca-copy-idle{display:none}", ".ca-copy[data-state=done] .ca-copy-done{display:block}", @@ -99,8 +112,12 @@ export const css = `@layer comark{${[ ".ca-frame .ca-overlay[data-menu]{pointer-events:auto;opacity:1}", // A copy paints the marks at rest, and nothing animates while it reads them. "[data-ca-capture] *{transition:none!important}", - "[data-ca-capture=still] *{--ca-on:0!important}", + "[data-ca-capture=still] *{--ca-on:0!important;--ca-dim:0!important}", ".ca-mark{position:absolute;color:var(--ca-color);text-decoration:none;outline:none}", + // While a mark or its note is lit, the other marks fade, so it stands out among many. + `.ca:has([data-n]:is(:hover,:focus-visible,:target)){--ca-dim:1}`, + `.cz-dialog:has(${zoomed} [data-n]:is(:hover,:focus-visible)) ${zoomed}{--ca-dim:1}`, + ".ca-mark,.ca-arrow{opacity:calc(1 - .65 * var(--ca-dim,0) * (1 - var(--ca-on,0)));transition:opacity .15s ease}", // Strokes take the mark's full color so they read at a glance; the numbers sit beside the marks, so only a thin line // covers the screenshot. Hovering a mark or its note thickens it. ".ca-mark,.ca-arrow{--ca-stroke:var(--ca-color)}", diff --git a/packages/annotate/test/annotate.test.ts b/packages/annotate/test/annotate.test.ts index f20edd98..b7218f88 100644 --- a/packages/annotate/test/annotate.test.ts +++ b/packages/annotate/test/annotate.test.ts @@ -304,7 +304,7 @@ describe("comark-annotate", () => { ).toHaveLength(3); // In the frame, after the marks, so it sits on the image's corner. expect(html).toMatch( - /
]*><\/span><\/div>/, + /
]*>