Files
pipelines/app/notes/P2-node.md
T
alan e63b01154b feat(app): add native content-sized graph stage node
One content-sized stage node as an ordinary native control. Material uses
stock Card.outlined/Card.filled inside an InkWell; Cupertino uses
CupertinoButton.tinted/filled. onSelected reports the definition key
verbatim, one merged button semantics node carries the exact label and
selected state, recorded status is shown only when the caller supplies it,
and invisible U+200B break opportunities reproduce the web's anywhere
wrapping. Painted-boundary and painted-surface tests cover the UI-review
2x outline and Cupertino container defects.
2026-10-21 18:44:18 +01:00

179 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P2-node — native content-sized stage-node control
## This visit: both UI-review must-fixes
| Finding | Change |
| --- | --- |
| Material stadium outline cut into a wrapped 2x label | Material no longer uses a stock **button**. It is a stock **card** body: `Card.outlined` when unselected, `Card.filled` when selected, wrapped in an `InkWell` with a 16 px content inset and the framework's `kMinInteractiveDimension` tap target. A card's painted shape is a rounded rectangle, so a long wrapped label stays inside the visible boundary at 1x and 2x. |
| Cupertino unselected stages and terminals were bare tinted text | Unselected Cupertino nodes are `CupertinoButton.tinted`, so every node has a visible native surface; selected stays `CupertinoButton.filled`. |
Both fixes use stock widgets and stock variants only: no shape override, no
font, size, padding on a button, palette value or CSS token was added.
| File | Lines | Responsibility |
| --- | ---: | --- |
| `lib/features/graph/widgets/graph_stage_node.dart` | 126 | one content-sized node as a native Material card or Cupertino button |
| `test/features/graph/widgets/graph_stage_node_test.dart` | 235 | key identity, semantics, keyboard, focus retention, wrap and terminal honesty |
| `test/features/graph/widgets/graph_stage_node_render_test.dart` | 210 | painted-boundary and painted-surface checks on real render objects/pixels |
| `tool/graph_node_probe.dart` | 83 | isolated browser fixture, 1x and 2x narrow cases |
| `tool/graph_node_probe.mjs` | 151 | headless-Chrome runner: labels, click identity, `aria-current`, captures |
| `notes/P2-node.md` | this page | facts for review/landing |
No existing app source, domain, layout, routing, shell, `main.dart`, pubspec,
server, web client or platform file was modified.
## Public API
```dart
GraphStageNode({
required GraphNode node,
String? recordedStatus,
bool selected = false,
required ValueChanged<String> onSelected,
})
```
Unchanged from the reviewed candidate. `onSelected` reports `node.key` verbatim,
including `#success` / `#failure`; the display label is never used as identity.
## Native mapping
| State | Material | Cupertino |
| --- | --- | --- |
| unselected | `Card.outlined` + `InkWell` | `CupertinoButton.tinted` |
| selected | `Card.filled` + `InkWell` | `CupertinoButton.filled` |
- The host is chosen with the existing `usesCupertinoHost` helper.
- Material content sits in a `Padding` of 16 logical px inside the card, so
wrapped glyphs stay clear of the rounded corners; the control is still
content-sized (no fixed width or height) and grows with its label.
- `MergeSemantics` + `Semantics(button: true, selected: …, label: …)` keep one
accessibility node per stage: button role, tap action, exact label/status and
selected state. The painted content stays `ExcludeSemantics`.
- Selection keeps the same widget type on both hosts (`Card` / `CupertinoButton`),
so keyboard focus survives activation; the previous Material
`OutlinedButton` → `FilledButton` swap replaced the focus node (review note 1).
- **Break-anywhere parity.** The web node uses `overflow-wrap: anywhere`; the
painted lines get invisible U+200B break opportunities. The accessible label
stays exact, with no invisible characters.
- **Recorded status only.** `recordedStatus` is shown verbatim on a second line
when non-blank; blank or whitespace-only status adds no line. Nothing is
derived from `terminal`, `stageIndex` or the label, so a terminal reads only
`Success` / `Failure` unless the caller supplies real run evidence.
## Rendered checks (new)
`graph_stage_node_render_test.dart` closes the gap the previous 2x test had
(line metrics versus paragraph width, not glyphs versus the painted boundary):
- **Painted-boundary containment.** Reads the actual `Material.shape` and render
rect of the Material control, builds its outer `Path`, converts every laid-out
line box of the label to card-local coordinates with
`RenderParagraph.localToGlobal`, and requires all four corners of every line
box to be inside the painted path — at 1x and 2x in a 150 logical px box.
A rounded rectangle is convex, so corner containment means the whole line box
is inside; no padding/shape override can hide a crossing.
- **The check has teeth.** Running the same test against the identical widget
while a `StadiumBorder` is temporarily set on the card fails with
`at 1.0x a glyph box corner at Offset(16.1, 19.0) escapes the painted control
boundary`. The shape assertion (`material node paints a rounded surface, not a
stadium`) fails too. The override was reverted before this page was written.
- **Cupertino container.** Renders the unselected node over an opaque page,
reads pixels back from a real `RepaintBoundary.toImage`, and requires the point
just inside the control's left edge to differ from the page background by more
than 24/255. Reverting to plain `CupertinoButton` fails this test.
- **Visible selection.** The same pixel path requires the painted surface to
change between unselected and selected in both hosts.
- **Focus retention.** Tab + Enter on the Material node, then the primary focus
must still be a descendant of the node's `Card`.
## Checks actually run
```
dart format --output=none --set-exit-if-changed lib/features/graph/widgets \
test/features/graph/widgets tool/graph_node_probe.dart # 0 changed, exit 0
flutter test test/features/graph/widgets # 13 passed
flutter test # 460 passed
flutter analyze # No issues found!
flutter build web -t tool/graph_node_probe.dart --release # ✓ Built build/web
PROBE_VARIANT=material PROBE_SCHEME=dark node tool/graph_node_probe.mjs # passed, 6 captures
PROBE_VARIANT=material PROBE_SCHEME=light node tool/graph_node_probe.mjs # passed, 6 captures
PROBE_VARIANT=cupertino PROBE_SCHEME=dark node tool/graph_node_probe.mjs # passed, 6 captures
PROBE_VARIANT=cupertino PROBE_SCHEME=light node tool/graph_node_probe.mjs # passed, 6 captures
```
The runner asserts the initial labels (`Selected: build`, `plan`, `build`,
`running`, `Success`, `Failure`), that exactly the `build` node carries
`aria-current="true"` (Flutter web maps `Semantics(selected:)` to `aria-current`,
not `aria-selected` — review note 5), that clicking `plan` and `Success` yields
exactly `Selected: plan` and `Selected: #success`, and that the selected
`aria-current` moves to `plan`.
## Browser evidence (current)
Real headless Chrome, loopback fixture only, 390×844 phone and 1280×800 desktop;
dark is Chrome's default scheme, light uses `prefers-color-scheme: light`.
- `/Users/alan/.local/share/pipelines/data/artifacts/64/public/p2-node-fix-material-dark-phone.png`
- `.../p2-node-fix-material-light-phone.png`
- `.../p2-node-fix-material-dark-desktop.png`
- `.../p2-node-fix-material-long-2x-crop.png` (2x enlargement of the wrapped 2x node)
- `.../p2-node-fix-material-long-1x-crop.png`
- `.../p2-node-fix-material-selected-plan.png`
- `.../p2-node-fix-cupertino-dark-phone.png`
- `.../p2-node-fix-cupertino-light-phone.png`
- `.../p2-node-fix-cupertino-dark-desktop.png`
- `.../p2-node-fix-cupertino-long-2x-crop.png`
- `.../p2-node-fix-cupertino-selected-terminal.png`
- Runner: `.../public/graph_node_probe.mjs` (same file as `tool/graph_node_probe.mjs`)
The visit-1 captures (`material-nodes-*.png`, `cupertino-nodes-*.png`) and the UI
review crops are superseded by this set; they are kept only as history.
Pixel measurements of the current 2x crops (crops are 2x, 8 logical px margin):
| Node | Container (px) | Glyph ink (px) | Corner band |
| --- | --- | --- | --- |
| Material | x 16–316, y 16–560 | x 50–269, y 66–507 | 24 px (radius 12) |
| Cupertino | x 16–316, y 16–640 | x 60–268, y 63–590 | 16 px (radius 8) |
At 1x the same nodes measure Material ink x 50–268, y 61–147 inside a
x 16–316, y 16–200 container, and Cupertino ink x 59–264, y 59–164.
No glyph ink enters a corner band or crosses the visible boundary in either
scaling; the previous outline crossing is gone.
Inspected captures: Material shows outlined node bodies, a visibly filled
selected node, `running` only on `build`, and no status on either terminal;
Cupertino shows a tinted body for every unselected node and a filled selected
node in both light and dark.
## Honest limits
- **Material selection is tonal.** `Card.filled` (surfaceContainerHighest) versus
`Card.outlined` (surface + border) is the strongest stock card pairing, but it
is lighter than the previous primary-filled button. It is visible in the
captures and asserted by pixels; if UI review wants a stronger accent, that
needs an explicit theme-colour decision rather than a bespoke palette.
- **Stage vs terminal is label-driven.** Both hosts give every node the same
stock container; the web's terminal pill and outcome tints are styling the
rules exclude. Terminals read `Success` / `Failure` (and no invented status).
Composition can add a stock type affordance if it is still wanted.
- **Material content inset is a spacing choice.** 16 logical px inside the card
keeps wrapped glyphs clear of the 12 px corner radius; the framework's
`kMinInteractiveDimension` keeps the tap target at the native minimum.
- **No measurement API yet.** The control shrink-wraps; the caller imposes width
(the fixture uses 150). The renderer still needs to measure this same control.
- **`onSelected` identity and wrapping are unchanged**, but U+200B break
opportunities would split exotic grapheme clusters (acceptable for stage keys).
- **Space activation** is a framework default and is not exercised; only
Tab + Enter is tested.
- **No composition.** No canvas, layout invocation, edge painter, visit menu,
shell registration or `main.dart` wiring: the widget is still not visible in
the app.
- **Not committed.** This stage forbids commit/push/deploy; the paths stay
untracked on `flutter/p2-node-widget` for Review and Land.
- **Fixture-only browser evidence**: no Pipelines server, real run,
authentication change, deployment or production data.
- **Mobile unverified**: web test/analyze/build only; no Android/iOS build,
emulator, ADB or install.