Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 14 additions & 9 deletions docs/guides/renderer-kit-components.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,15 +114,20 @@ line, in the change's hue. The kit's change runs (`pk-region-run`, for rows that
meet edge to edge) draw their edges on the lines around them: one stroke outside
the run, over a neighbouring row's line, a header's bottom line or the
container's edge. Where two runs meet, the later one's top edge is the boundary.
`Group` clips to its outer edge (`clip-path`), so a run at its edge covers the
group's border there. So a run needs that stroke to stay visible: a scrolling
container reaches over its card's edge by the line's width and pads itself by it
(as text diff's output does), and a row that draws a line of its own on a side
gives that line the hue (`--pk-region-line`, fading to `--pk-line`) instead of
an edge beside it (as runtime policy's rows, whose lines are their bottom
borders, and text diff's After column do). A changed `EntityCard` that is a
change region takes the hue on its own border, and a pill whose label is a
`ValueChange` draws no frame around its two pills.
`Group` clips to its outer edge (`overflow: clip` with the border's width as its
margin, or a `clip-path` where the browser lacks that margin), so a run at its
edge covers the group's border there. What reaches a group's corner takes its
inner radius (`--pk-group-inner-radius`, the radius less the border), so it is
concentric with the border and never covers it: the header band takes it at the
top, and a renderer's last row or band at the bottom (as runtime policy's last
rows and text diff's last line do). So a run needs that stroke to stay visible:
a scrolling container reaches over its card's edge by the line's width and pads
itself by it (as text diff's output does), and a row that draws a line of its
own on a side gives that line the hue (`--pk-region-line`, fading to
`--pk-line`) instead of an edge beside it (as runtime policy's rows, whose lines
are their bottom borders, and text diff's After column do). A changed
`EntityCard` that is a change region takes the hue on its own border, and a pill
whose label is a `ValueChange` draws no frame around its two pills.

## Item rings

Expand Down
11 changes: 7 additions & 4 deletions docs/reference/renderer-kit.md
Original file line number Diff line number Diff line change
Expand Up @@ -3540,9 +3540,11 @@ CardChangeMarks(__0: { "change": { "renamed"?: false | true | undefined; "status
```

A changed card's marks, as every kit card draws them: the card filled with its change's soft hue under a strong
edge of the same hue (inset by `inset`, see `emphasisInset`), and a footer band `footer` tall across its bottom,
ruled off from the body, holding the status words centred (see `SvgChangeStatus`). The edge is drawn again over
the band, so the band never covers the border or its corners. Draw it over the card's surface and under its text;
edge of the same hue (inset by `inset`, see `emphasisInset`, with its radius less the inset, so it is concentric with
the card's border), and a footer band `footer` tall across its bottom, ruled off from the body, holding the status
words centred (see `SvgChangeStatus`). The band is clipped to the card's shape (`node-card-shape`, rounded as the
card's surface is), so its corners follow the card's, and the edge is drawn again over it, so the band never covers
the border or pokes outside its corners. Draw it over the card's surface and under its text;
everything fades with `emphasis`, and nothing is drawn at zero. `fill: false` leaves the body's fill to the
caller, for a card whose parts tint their own slices of it.

Expand All @@ -3554,7 +3556,8 @@ The box is in card units: `x` and `y` are its top-left corner.
cardCornerRadius: 6
```

The corner radius of a graph card's shape, in card units: the footer band's bottom corners follow it.
The corner radius a graph card's shape is drawn with, in card units, where the theme's radius (`rx` in CSS,
`--projections-radius`) doesn't reach: a shape's CSS `rx` wins over it.

### `CardGrid`

Expand Down
118 changes: 118 additions & 0 deletions packages/renderers/harness/browser/corners.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
import {expect, test} from '@playwright/test'
import type {CornerReport} from '@githubnext/projections-renderer-testing/playwright'
import {cornerReport, openStage} from '@githubnext/projections-renderer-testing/playwright'
import {harnessInspector} from '@githubnext/projections-renderer-harness/playwright'

/**
* Rounded corners, in pixels (see `cornerReport`): a bordered container's border keeps its thickness around each
* curve, and nothing it holds paints over its border or outside its curve. Nested radii are concentric: a header band,
* a last changed row or a card's change edge takes its container's radius less the inset.
*/
test.use({deviceScaleFactor: 2})

async function attachPictures(report: CornerReport, label: string) {
for (const [name, url] of Object.entries(report.pictures ?? {}))
await test.info().attach(`${label} ${name}.png`, {body: Buffer.from(url.split(',')[1]!, 'base64'), contentType: 'image/png'})
}

const cases = [
{what: "a section's header band", scenario: 'runtime-policy/token-guard', selector: '.rp-panel', text: 'Network'},
{what: 'a group ending in a changed line', scenario: 'text-diff/cli-output-release', selector: '.text-diff-command'},
{what: "a workflow group's header band", scenario: 'agentic-workflows/docs-bot', selector: '.aw-group'},
{what: "a card's change edge and status band", scenario: 'dependency-injection/nestjs-orders', selector: 'rect.node-emphasis-edge.added'},
] as const

for (const colorMode of ['light', 'dark'] as const) {
for (const {what, scenario, selector, ...rest} of cases) {
test(`${scenario}: ${what} keeps the border's corners whole (${colorMode})`, async ({page}, info) => {
test.skip(!info.project.name.endsWith('desktop'), 'Corners measure the same at every width.')
const stage = await openStage(page, harnessInspector(), {scenario, progress: 1, comparisonMode: 'diff', colorMode})
await stage.measure('settle')
let target = stage.frame.locator(selector)
if ('text' in rest) target = target.filter({hasText: rest.text})
const report = await cornerReport(page, target.first(), {label: selector})
await attachPictures(report, selector)
expect(report.corners.length, 'corners measured').toBeGreaterThan(0)
expect(report.failures).toEqual([])
})
}
}

/**
* Table frames: a data table's frame, which its heading and rows draw (`frame`: the line's width), and a database
* card's, its inset outline over its header band and rows; each at rest, then with the row in its bottom corners (or
* its first row) selected and hovered, whose ring and hue reach those corners.
*/
const tables = [
{what: "a data table's frame", scenario: 'code-statistics/gateway-table', selector: '.pk-table-scroll', frame: 1, rows: '.pk-table-row'},
{
what: "a database table's card",
scenario: 'database/prisma-shop',
selector: '.database-table:not(.database-enum-card):has(> header)',
rows: '.database-column[data-entity-id]',
},
] as const

for (const colorMode of ['light', 'dark'] as const) {
for (const {what, scenario, selector, rows, ...rest} of tables) {
test(`${scenario}: ${what} keeps its corners whole at rest, selected and hovered (${colorMode})`, async ({page}, info) => {
test.skip(!info.project.name.endsWith('desktop'), 'Corners measure the same at every width.')
const stage = await openStage(page, harnessInspector(), {scenario, progress: 1, comparisonMode: 'diff', colorMode})
await stage.measure('settle')
const target = stage.frame.locator(selector).first()
const options = {label: selector, ...('frame' in rest ? {frame: rest.frame} : {})}
const ids = await target.evaluate((element, rows) => {
const all = [...element.querySelectorAll(rows)].filter(row => row.getAttribute('data-entity-id'))
const bottom = [...all].sort((a, b) => b.getBoundingClientRect().bottom - a.getBoundingClientRect().bottom)
return [...new Set([all[0], bottom[0]].filter(row => row !== undefined).map(row => row.getAttribute('data-entity-id')!))]
}, rows as string)
expect(ids.length, 'rows to ring').toBeGreaterThan(0)
const states: [string, () => Promise<void>][] = [
['at rest', async () => {}],
...ids.flatMap((id): [string, () => Promise<void>][] => [
[`${id} selected`, () => stage.select(id)],
[`${id} hovered`, async () => (await stage.select(null), await stage.hover(id))],
]),
]
for (const [state, enter] of states) {
await enter()
await stage.measure('settle')
const report = await cornerReport(page, target, {...options, label: `${selector} ${state}`})
await attachPictures(report, `${selector} ${state}`)
expect(report.corners.length, `${state}: corners measured`).toBeGreaterThan(0)
expect(report.failures).toEqual([])
}
await stage.hover(null)
})
}
}

test("the report finds a data table's square heading poking past its frame", async ({page}, info) => {
test.skip(info.project.name !== 'chromium-desktop', 'One engine shows the report reads the pictures.')
const stage = await openStage(page, harnessInspector(), {scenario: 'code-statistics/gateway-table', progress: 1, comparisonMode: 'diff'})
await stage.measure('settle')
await stage.frame.locator('head').evaluate(head => {
const style = document.createElement('style')
style.textContent =
'.pk .pk-table > .pk-table-head, .pk .pk-table > .pk-table-head > .pk-table-cell:first-child { border-radius: 0 !important }'
head.append(style)
})
await stage.measure('settle')
const report = await cornerReport(page, stage.frame.locator('.pk-table-scroll').first(), {frame: 1})
expect(report.failures.some(failure => /^box top-left corner/.test(failure))).toBe(true)
expect(report.failures.some(failure => /^box top-right corner/.test(failure))).toBe(true)
})

test('the report finds a square header band covering its group border', async ({page}, info) => {
test.skip(info.project.name !== 'chromium-desktop', 'One engine shows the report reads the pictures.')
const stage = await openStage(page, harnessInspector(), {scenario: 'runtime-policy/token-guard', progress: 1, comparisonMode: 'diff'})
await stage.measure('settle')
await stage.frame.locator('head').evaluate(head => {
const style = document.createElement('style')
style.textContent = '.pk .pk-group-header { border-radius: 0 !important }'
head.append(style)
})
await stage.measure('settle')
const report = await cornerReport(page, stage.frame.locator('.rp-panel').filter({hasText: 'Network'}).first())
expect(report.failures.filter(failure => /^box top-(left|right) corner at 45°: the border is/.test(failure))).toHaveLength(2)
})
31 changes: 24 additions & 7 deletions packages/renderers/kit/src/react/graph-canvas/card-change.tsx
Original file line number Diff line number Diff line change
@@ -1,18 +1,23 @@
// A card's change marks in a comparison: its tinted fill and change edge, and its status footer band.
import {useId} from 'react'
import {cardTextMetrics} from '../../card-text.js'
import {SvgChangeStatus} from '../components.js'
import type {ChangeClassification, StatusPart} from '../../emphasis.js'
import {cardFooterHeight} from '../../layout.js'
import {footerBand} from './cards.js'

/** The corner radius of a graph card's shape, in card units: the footer band's bottom corners follow it. */
/**
* The corner radius a graph card's shape is drawn with, in card units, where the theme's radius (`rx` in CSS,
* `--projections-radius`) doesn't reach: a shape's CSS `rx` wins over it.
*/
export const cardCornerRadius = 6

/**
* A changed card's marks, as every kit card draws them: the card filled with its change's soft hue under a strong
* edge of the same hue (inset by `inset`, see `emphasisInset`), and a footer band `footer` tall across its bottom,
* ruled off from the body, holding the status words centred (see `SvgChangeStatus`). The edge is drawn again over
* the band, so the band never covers the border or its corners. Draw it over the card's surface and under its text;
* edge of the same hue (inset by `inset`, see `emphasisInset`, with its radius less the inset, so it is concentric with
* the card's border), and a footer band `footer` tall across its bottom, ruled off from the body, holding the status
* words centred (see `SvgChangeStatus`). The band is clipped to the card's shape (`node-card-shape`, rounded as the
* card's surface is), so its corners follow the card's, and the edge is drawn again over it, so the band never covers
* the border or pokes outside its corners. Draw it over the card's surface and under its text;
* everything fades with `emphasis`, and nothing is drawn at zero. `fill: false` leaves the body's fill to the
* caller, for a card whose parts tint their own slices of it.
*
Expand Down Expand Up @@ -47,14 +52,26 @@ export function CardChangeMarks({
footer?: number
fill?: boolean
}) {
const shape = useId()
if (emphasis <= 0.01) return null
const bottom = y + height
const rule = bottom - footer
const edge = {x: x + inset, y: y + inset, width: width - 2 * inset, height: height - 2 * inset, rx: cardCornerRadius}
const edge = {x: x + inset, y: y + inset, width: width - 2 * inset, height: height - 2 * inset, rx: Math.max(0, cardCornerRadius - inset)}
return (
<>
{fill && <rect className={`node-emphasis ${classification}`} data-projections-edge="" {...edge} opacity={emphasis} />}
<path className={`node-footer-band ${classification}`} d={footerBand(x, rule, width, bottom, cardCornerRadius)} opacity={emphasis} />
<clipPath id={shape}>
<rect className="node-card-shape" x={x} y={y} width={width} height={height} rx={cardCornerRadius} />
</clipPath>
<rect
className={`node-footer-band ${classification}`}
x={x}
y={rule}
width={width}
height={footer}
clipPath={`url(#${shape})`}
opacity={emphasis}
/>
<line className={`node-footer-rule ${classification}`} x1={x} x2={x + width} y1={rule} y2={rule} opacity={emphasis} />
<rect
className={`node-emphasis node-emphasis-edge ${classification}`}
Expand Down
6 changes: 0 additions & 6 deletions packages/renderers/kit/src/react/graph-canvas/cards.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,6 @@ export function groupHeading(given: KindLineText | undefined, fallback: string,
)
}

/** A card's status footer band: its full width from `top` to the card's `bottom`, rounded on the bottom corners like the card. */
export function footerBand(x: number, top: number, width: number, bottom: number, radius: number): string {
const r = Math.min(radius, bottom - top, width / 2)
return `M${x} ${top}H${x + width}V${bottom - r}A${r} ${r} 0 0 1 ${x + width - r} ${bottom}H${x + r}A${r} ${r} 0 0 1 ${x} ${bottom - r}Z`
}

/** A diff card's text, laid out whole by `diffCardText`: each line in its own style, values struck or added. */
export function DiffCardLines({card, top, left}: {card: DiffCardText; top: number; left: number}) {
const tones = {was: 'pk-svg-was', now: 'pk-svg-now', arrow: 'pk-svg-arrow', note: 'node-note'} as const
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ export function GroupNode({node, drawing, holdsChanges = false}: {node: Transiti
y={node.y - node.height / 2 + inset}
width={node.width - 2 * inset}
height={node.height - 2 * inset}
rx="8"
rx={Math.max(0, 8 - inset)}
opacity={emphasis}
/>
)}
Expand Down
15 changes: 13 additions & 2 deletions packages/renderers/kit/styles/graph.css
Original file line number Diff line number Diff line change
Expand Up @@ -85,13 +85,24 @@
.graph-group .node-surface {
rx: var(--projections-radius-lg);
}
/*
* A change edge is inset so its outer edge is the plain border's (`emphasisInset`: half the difference of the two
* strokes), and its radius is the card's less that inset, so its curve is concentric with the border's. A card's shape
* (`node-card-shape`, which a change band is clipped to) is the card's surface without its stroke.
*/
.pk {
--pk-emphasis-inset: max(0px, calc((var(--stroke-strong) - var(--stroke)) / 2));
}
.node-emphasis {
pointer-events: none;
stroke-width: var(--stroke-strong);
rx: var(--projections-radius);
rx: max(0px, calc(var(--projections-radius) - var(--pk-emphasis-inset)));
}
.graph-group .node-emphasis {
rx: var(--projections-radius-lg);
rx: max(0px, calc(var(--projections-radius-lg) - var(--pk-emphasis-inset)));
}
.node-card-shape {
rx: var(--projections-radius);
}
.node-emphasis.added {
fill: var(--green-soft);
Expand Down
17 changes: 16 additions & 1 deletion packages/renderers/kit/styles/layout.css
Original file line number Diff line number Diff line change
Expand Up @@ -16,16 +16,29 @@
* title in a header band inside its edge. The band holds one line: the title, which truncates with an ellipsis, muted
* meta, then actions and the status cell at its end (`--pk-status-width`, reserved on every group in a comparison).
* It clips to its outer edge (`clip-path`), not inside its border as `overflow` would, so a change region at its edge
* draws its own edge over the group's: one line there, in the change's hue.
* draws its own edge over the group's: one line there, in the change's hue. Where the browser can, it clips with
* `overflow: clip` instead, its margin the border's width: the same outer edge, but snapped to whole pixels with the
* border, where a `clip-path` isn't and would cut off part of a border on a fractional edge. Its children's paint is
* not clipped inside the border, so what reaches a corner takes the inner radius (`--pk-group-inner-radius`, the radius
* less the border), concentric with the border, and never covers it: the header band its top corners, and a
* renderer's last row or band its bottom ones.
*/
.pk .pk-group {
--pk-group-inner-radius: max(0px, calc(var(--projections-radius) - var(--projections-border-width)));
display: flow-root;
min-width: 0;
border: var(--projections-border-width) solid var(--divider);
border-radius: var(--projections-radius);
background: var(--raised);
clip-path: inset(0 round var(--projections-radius));
}
@supports (overflow-clip-margin: 1px) {
.pk .pk-group {
clip-path: none;
overflow: clip;
overflow-clip-margin: var(--projections-border-width);
}
}
.pk .pk-content-view > .pk-group + .pk-group {
margin-top: var(--projections-space-3);
}
Expand All @@ -37,6 +50,8 @@
padding: var(--projections-space-1) var(--projections-space-3);
background: var(--band);
border-bottom: var(--projections-border-width) solid var(--divider);
border-start-start-radius: var(--pk-group-inner-radius);
border-start-end-radius: var(--pk-group-inner-radius);
}
.pk .pk-group-title {
display: flex;
Expand Down
20 changes: 20 additions & 0 deletions packages/renderers/testing/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,26 @@ with a capital H and check that the space above the E, below it, left of its
stem and right of the H's right stem match. Take it at a device scale of 2 or
more, and divide by the drawing's own scale when it is zoomed or fitted.

## Corners in pixels

`cornerReport(page, target, {label, frame})` checks a bordered box's rounded
corners in pictures of them: the border keeps its thickness around each curve,
within a quarter CSS px plus half a device pixel of its sides (or between them,
where the sides differ), no third color shows in it and no paint shows outside
the curve. That is what a filled band in a rounded container breaks when it
isn't concentric with it: a header, footer or last changed row with square
corners covers the inside of the border's curve, and one with the container's
own radius pokes out past it. Nested radii are the container's less the inset.
The `target` is a locator (an element's border box, radii and solid borders, its
solid outline where it has no border, or an SVG `rect`'s stroked outline, read
by `cornerBox`) or a `CornerBox` of your own. For a frame its contents draw (a
data table's scroll box, whose heading and rows draw its lines), pass `frame`,
the line's width; each corner is measured where its sides are painted, since a
browser may snap a border to whole pixels, and a box taller than the view is
scrolled for its top and then its bottom corners. Dashed outlines and corners no
larger than their border are skipped. Take the page at a device scale of 2 or
more; failing corners' pictures come back in `pictures`, to attach.

## Your own assertions

```ts
Expand Down
Loading