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.
This commit is contained in:
@@ -0,0 +1,178 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user