feat(734): field-level progressive disclosure — shared FieldHelp trigger + panel #841
7
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
f3d003b8ac |
fix(734): a fifth wrong copy claim, and the N5 replacement was vacuous too
Build ErsatzTV Image / CI toolchain image resolves (pull_request) Successful in 8s
review-verdict/h10 Review-verdict: MERGEABLE @ f3d003b (base: main)
PR Gates / CI image pin matches docker/ci (pull_request) Successful in 11s
PR Gates / Docs update reminder (pull_request) Successful in 16s
Build ErsatzTV Image / Delimiter ban (release path) (pull_request) Successful in 25s
PR Gates / decisions lifecycle (pull_request) Successful in 22s
PR Gates / Fix proofs (Proves trailers) (pull_request) Successful in 16s
Review verdict / Set review-verdict status (pull_request_target) Successful in 10s
PR Gates / Script lint and tests (ruff + pytest) (pull_request) Successful in 5m50s
Build ErsatzTV Image / Build & test (.NET) (pull_request) Successful in 8m34s
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (pull_request) Successful in 6m27s
Build ErsatzTV Image / Build & push image (amd64) (pull_request) Skipped
Build ErsatzTV Image / Functional E2E (curl + UI contracts) (pull_request) Successful in 5m54s
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (pull_request) Successful in 8s
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (pull_request) Successful in 6s
Third cold review: BLOCKED on N8, with N9/N10 non-blocking. N8 — the hardware-acceleration paragraph told the operator to worry about whether the FFmpeg build supports a kind. It does not have to: `GetSupportedHardwareAccelerationKindsHandler` adds a kind only when `FFmpegCapabilities.HasHardwareAcceleration` is already true, so an unsupported kind never reaches the dropdown and cannot fail at playback. On this host the dropdown offers exactly ["None","VideoToolbox"]. The device-passthrough half was right, and is now the whole claim: nothing checks at save time whether the device is present and passed through, and that is what fails at playback. That is the FIFTH wrong copy claim across three review rounds, in nine paragraphs — three fixed in round two, a fourth found in round three, this one found after I asked for a fifth. The decision record now says so plainly, because the pattern is the lesson: prose about behaviour is not cheaper to get right than code, and one pass over it is demonstrably not enough. N9 — the test I wrote to replace the vacuously-arranged one was itself vacuous. Deleting the panel's onMouseEnter/onMouseLeave left 14/14 green, for two reasons the reviewer's mutation established: there was no assertion between the panel enter and leave, so the "keeps open" half was never checked; and React propagates portal events through the React tree, so mouseLeave(panel) also fires the WRAPPER's onMouseLeave — with `hoveredTrigger` never cleared, the closing assertion passed on the wrapper's signal alone. The test now leaves the wrapper first, so `hoveredPanel` is the only thing holding the panel open, and asserts the panel is still present at that point. Re-run with the reviewer's exact mutation: it now kills exactly that test, and the restored control is 14/14. N10 — `.ctv-field-help-panel-top`/`-bottom` were emptied by the bridge's removal and are now pure state hooks. Commented as such: do not hang an offset off them, because that is how the bridge started. Follow-ups filed rather than bolted on at round four: - #839 — panel placement (unclipped, auto-flip) is verified by live measurement, not by a committed test; jsdom has no layout and cannot see it. - #840 — the portal puts a panel-internal `docsHref` link at the end of the tab order. Trigger: the first screen that passes `docsHref`. Both linked from §15's adopting checklist and from the decision record, so an adopter meets them where it matters. Gate: lint clean, build clean, 1220/1220, decisions-validate OK, mirror 6/6 byte-identical (checker asserts it read all six before reporting). refs #734 |
||
|
|
14d1fbaabd |
fix(734): withdraw the hover bridge and say so; drop a fourth wrong copy claim
Second cold review: BLOCKED on N1 and N4, plus three regressions the portal round introduced. N1 — the bridge only ever worked on a strictly vertical descent. The reviewer measured a diagonal walk toward the panel (down-and-right, the natural reach for a 320px panel sitting below-right) closing at step 4 of 12 — the same signature the bridge commit claimed to have fixed. A boundary scan puts the safe sideways exit at the bottom 1.25px of an 18px icon, about 7% of its height. The bridge is WITHDRAWN, not patched. Two rounds of live measurement of this component's hover model were both taken along the vertical axis — the one where it works — so a third patch would have been guessing at an axis again. §15 and the decision record now say what is true: hover is for reading the paragraph in place, and the panel's interactive content is reached by PINNING, which survives any pointer motion and is the only gesture a touch user has regardless. A mechanism needing a 1.25px caveat is not a mechanism. N4 — a fourth wrong copy claim survived the round that fixed the first three: "the server raises anything smaller to 64 and logs the override". Neither CreateFFmpegProfileHandler nor UpdateFFmpegProfileHandler has an ILogger; the Math.Max is silent. The warning lives in QsvPipelineBuilder at pipeline-build time, and since the save path normalises the value first, the log the copy promised cannot be produced by anything a user does on that screen. Non-blocking regressions from the portal round, also fixed: - N3: the panel left every dialog's stacking context on being portalled and painted BEHIND `.ctv-dialog-overlay` / `.ctv-slideover-scrim` (fixed, z-index 100). Raised to 110 and measured against an injected scrim: hit-test now returns the panel. - N6: the horizontal clamp used the 320px max-width constant instead of the panel's measured width, which would shove a narrower panel left of its own trigger near the right edge. - N7: the loudness paragraph pointed at "the fixed integrated loudness below", but the Target loudness row only renders once loudnorm is already selected — so in the state where the reader is deciding, there is nothing below. - N5: the hover test fired mouseEnter(panel) BEFORE mouseLeave(wrap), the reverse of the browser's own order, so it could only confirm its own arrangement. Replaced with two tests that assert what is actually claimed: a panel already entered stays open, and a pinned panel's link survives arbitrary pointer motion. N2 (the portal puts a panel-internal link at the end of the document tab order) is recorded in §15 and the record as a known limitation rather than fixed — no screen passes `docsHref`, and inventing custom Tab forwarding at round three is how the bridge happened. Re-measured live at this head: bridge absent from the shipped stylesheet, all 7 triggers fully visible at 320px, three auto-flipped to `top`, none out of viewport. Gate green: lint clean, build clean, 1220/1220, decisions-validate OK. refs #734 |
||
|
|
f0da323a41 |
fix(734): portal the panel out of the card clip; correct three wrong copy claims
Cold adversarial review returned BLOCKED on four findings. All four fixed, plus
the reviewer's medium/low items.
BLOCKER — the panel was clipped away near a card bottom. `.ctv-card` sets
`overflow: hidden`, which clips a positioned descendant whatever its z-index, so
`z-index: 60` bought nothing. Measured on the reference screen: "Target
loudness" showed 12px of a 92px paragraph and "Scaling behavior" sat at exactly
0px of slack. Not an edge case — the Audio card's last row always carries a
`detail`, so one field's explainer was destroyed in every state of that card.
The panel is now portalled to `document.body` with `position: fixed`, placed
from the trigger's viewport rect in a layout effect that flips it above when it
would run off the bottom and clamps it inside the horizontal edges. Re-measured
across all seven rendered triggers: every panel fully visible, three flipped to
`top` automatically, none out of viewport. The portal cost the wrapper's
`mouseleave` as a proxy for "pointer still in this widget", so the panel now
owns its own hover state; the walk was re-measured on a flipped panel
(`[1]x12`, negative control 0).
Copy — three claims were wrong about the software they describe, which is the
exact drift §15 exists to prevent:
- loudnorm was compared to a dynamic-normalization mode this fork does not have
(`NormalizeLoudnessMode` is `{ Off, LoudNorm }`).
- scaling was described as a binary choice, silently dropping `Stretch` — the
only option that distorts the picture.
- `1..63` extra hardware frames were asserted known-bad, where
`ffmpeg.qsv-extra-hw-frames-floor` states in terms that only `0` and `64` were
measured and the rest are untested. The level-1 summary was already correct.
All three are corrected in the app and in the design mirror; a checker that
proves it read every key confirms the six shared strings stay byte-identical.
Also from the review:
- The `preventDefault` justification was false: per spec a label's activation
behaviour is skipped for interactive-content targets, verified in Chromium.
The call stays as belt-and-braces; the doc, the code comment and the test name
no longer claim it fixes an observed bug.
- `role="note"` is not a live region and announced nothing. `aria-describedby`
on the trigger, set only while open, is what reads the paragraph out.
- `aria-controls`/`aria-describedby` are omitted while collapsed rather than
pointing at an id that is not in the document.
- Escape/outside-press are armed only when pinned or focused; armed on hover, a
document-level Escape stole focus whenever a pointer rested on an info icon.
- The trigger joined the shared `--ring-focus` list instead of the UA default.
- `box-sizing: border-box` — the panel rendered 344px against a 320px max-width.
- `FIELD_HELP` is `as const`, so a mistyped key is a build error rather than a
trigger with an empty panel.
- Added the missing decision record `spa.field-progressive-disclosure` and
regenerated the catalog; §§8-13 each have one and §15 was the outlier.
Four new tests, each mutation-proved to fail for its own reason: portalling,
panel-owned hover, hover-scoped Escape, and collapsed-state aria. Restored
control green.
refs #734
|
||
|
|
d059647226 |
design(734): mirror the FieldHelp pattern into the FFmpegProfiles prototype
docs/design-sync.md step 7 — design-system/ changes land with the feature branch so the repo and Claude Design stay mirrored. Adds a mockup `FieldHelp` (the two opening signals that read in a static review: tap-pins and hover) plus the same FIELD_HELP copy on the six rows the prototype actually renders. The shipped component additionally handles Escape, outside-press dismissal and the hover bridge; the prototype is a reference, never shipped code. Parse-checked with the TypeScript JSX parser. The DesignSync push back to Claude Design is main-session-only and needs the user's approval, so it is not done here. refs #734 |
||
|
|
64c030d2da |
fix(734): the docs link's colour token never existed
`var(--text-accent, var(--text-primary))` always took the fallback: the SPA has no `--text-accent` token — the accent is `--ctv-accent`, defined per theme (#e08a3c dark / #5b7cfa light) in the built stylesheet. So the level-3 "Learn more" link rendered in body colour and read as prose rather than a link until hovered. No screen passes `docsHref` yet, so nothing shipped wrong; the next adopter would have inherited it. refs #734 |
||
|
|
6f6520f560 |
fix(734): bridge the trigger→panel gap so a hovered panel stays reachable
Measured live (dotnet host + built SPA, twelve-step mouse walk from the trigger down into the panel): the panel disappeared at step four. `mouseleave` on the wrapper does not fire while the pointer is over a descendant however it is positioned, but the 7px offset between trigger and panel belongs to the ROW, not to the wrapper — so the pointer leaves the wrapper in transit and the panel closes under the cursor. That makes the level-3 `docsHref` link unreachable by mouse, which is the whole point of the panel being interactive. A transparent `::before` on the panel spans the offset, making the path continuously a descendant. Re-measured after the fix: all twelve steps keep the panel open, and a negative control (pointer moved 500px clear) still dismisses it, so the bridge did not simply disable the close path. refs #734 |
||
|
|
3b29865b9b |
feat(734): field-level progressive disclosure — shared FieldHelp trigger + panel
Settings fields carry consequences that are severe and non-obvious while the UI gives a bare label; the explanation existed only in decision records and source comments. Adds the three-level pattern from #734 as a shared component so it is identical everywhere rather than sprinkled per screen. - `FieldHelp` (web/src/components/fieldHelp.tsx): an Info-icon <button> beside a field name that opens a one-paragraph `role="note"` panel, with an optional level-3 `docsHref` deep link. Opens on three independent signals — tap (the only gesture a touch user has, and it pins), hover (wrapper-scoped so the panel stays reachable), and keyboard focus. Escape closes and returns focus without re-opening; an outside pointer press dismisses a pinned panel. - Deliberately NOT an extension of `Tooltip`: that primitive is single-line, `nowrap`, `pointer-events: none` and hover/focus-only, so it can hold neither a paragraph nor a link and touch users never see it. - Reference adoption on FFmpegProfilesScreen (9 consequential fields). `Row` gains `detail`/`docsHref`; copy lives in a module-level `FIELD_HELP` record next to the field definitions, interpolating existing bound constants rather than restating them. Two over-long level-1 summaries are cut to one sentence with the rest moved to level 2. - No screen passes `docsHref` — the external docs do not exist yet; the affordance is built and typed, and exercised by the unit test. The Escape-then-refocus regression (re-focusing the trigger re-opened what was just closed) was found by its test before the fix and is pinned by it. The label-activation assertion is on `defaultPrevented`, not on "the input did not focus": a positive control confirmed jsdom does not implement label activation at all, so the obvious assertion would pass vacuously. fixes #734 |