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

10 KiB
Raw Blame History

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

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.