Skip to content

fix(case): a section that resolves to nothing is silent, not a heading over a void - #2052

Merged
rubenvdlinde merged 2 commits into
developmentfrom
dq2-empty-section-absent
Sep 9, 2026
Merged

rubenvdlinde merged 2 commits into
developmentfrom
dq2-empty-section-absent

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

The defect my own test caught, and the fix for it

case-sections rendered a heading for every section whether or not its widget resolved. CnDetailWidgetHost renders nothing for a type it cannot resolve, so on CI the Documents tab showed Documents with its rows, then a rule, then Files with nothing under it.

As a whole tab, an unresolvable Files panel was merely an empty tab. Folded into a section it became a label over a void, which looks more broken than what it replaced. That is a regression the fold introduced in #2031, and the assertion added alongside it is what found it.

Why local green did not predict it, which is the part worth carrying further

Two of the ten sections are type: integration. An integration leaf is served by OpenRegister's global registry bundle, and CI never has it, because openregister gitignores its /js/. So case-files renders on a dev instance and renders nothing on CI.

Eleven of eleven locally with nothing unrun was necessary and not sufficient. A local run cannot distinguish the leaf rendered from the leaf exists here and not there, and no number of local repetitions closes that gap. That is a real limit on local verification for anything integration-typed.

What changed

The heading waits for content; the host never does. Gating the host would deadlock: a widget that has not mounted cannot fetch, so it could never gain the content that would let it render. A MutationObserver per section watches the host, because nearly every widget here mounts empty and fills after its own fetch, so a check taken once on mount would record every section as empty and hide every heading on the page. An empty section also drops its divider and padding, so it reserves no space and reads as absent.

My first attempt at this was wrong, and the same spec caught that too. It called measure() synchronously inside the :ref callback, which runs during the patch. Writing reactive state there either loops or is dropped, so filled never became true, every heading stayed hidden, and two previously-passing tests went red on a change meant to fix one of them. It now measures on nextTick, and only assigns on an actual change, so a mutation that does not alter the answer cannot re-render and re-fire the observer.

The assertion is narrowed, not weakened

Both kinds are held to the honest invariant: absent or non-empty, never a heading over a void. It is read through one polled evaluate that sees the heading and the host together, rather than a snapshot of one compared against a retrying matcher on the other, which is how a test passes for the wrong reason.

The eight sections that resolve from dossiq's own bundle keep the full content assertion. They are the eight a broken case-sections registration would take down, which is the mutation this test was originally proved against, so the teeth remain exactly where the failure mode is. The two integration sections stop at the shared invariant, and the comment says all of this in place, because the next reader will otherwise read the relaxation as weakening.

Sections are asserted toBeAttached rather than toBeVisible, because a correctly-empty section now has zero height and toBeVisible would fail on it for the very reason the component is right. The registry sections keep a visibility check, where it is a claim rather than a measurement of CSS. The Files ordering test moves off bounding boxes onto DOM order for the same reason: a box comparison asserts both sections have height, which is no longer true and was never the claim that test was making.

The mutation matrix

Every cell was run against the live instance, not reasoned about.

component Files leaf result
fixed resolvable (a dev instance) 11 of 11 pass, 0 did not run
fixed unresolvable (the CI condition) passes — the section is silent
pre-fix unresolvable (the CI condition) fails: case-section-case-files must never be a heading over nothing
fixed, registration disabled resolvable fails: case-section-case-documents did not render inside Documents

Rows two and three together are the point: the test detects the bad state, and the fix is what removes it. Row four is the original mutation, confirming the assertion still catches a broken registration after the narrowing.

The CI condition was reproduced locally by pointing case-files at an integrationId nothing answers to, which is the same thing the absent bundle does.

Verified by exit code

vitest 1075 tests over 85 files 0 · eslint 0 · prettier 0 · check:manifest 0 · test:l10n 0 · npm run build 0 · the tab spec against a live instance 11 of 11, 0 did not run.

Not in this change

The tab strip wrapping two tabs per line at 1024 is not touched, because it is not dossiq's. Measured on the same instance, the first five tabs sit at byte-identical positions before and after #2031:

before (5 tabs): 478.59, 478.59, 520.59, 520.59, 561.59      → 3 lines
after  (6 tabs): 478.59, 478.59, 520.59, 520.59, 561.59, 602.59 → 4 lines

Each tab takes about half the strip regardless of its label, so REQ-CDV-16's "fits one row at 1024" has never been true, and cutting fourteen tabs to six could neither have caused nor fixed it. Placement row A33 diagnosed a count problem where there is a width problem in CnTabs. That belongs upstream, and a workaround in this app's stylesheet would be the wrong place for it.

…g over a void

WHAT MY OWN TEST CAUGHT. `case-sections` rendered a heading for every
section whether or not its widget resolved. CnDetailWidgetHost renders
NOTHING for a type it cannot resolve, so the Documents tab showed
`Documents` with rows, then `Files` with a rule above it and nothing
under it. As a whole tab an unresolvable panel was merely an empty tab;
folding it into a section made it look broken. That is a regression the
fold introduced, and the assertion added with it is what found it, on CI,
after eleven of eleven passed locally.

THE HEADING NOW WAITS FOR CONTENT, the host does not. Gating the host
would deadlock: a widget that has not mounted cannot fetch, so it could
never gain the content that would let it render. A MutationObserver per
section watches the host, because nearly every widget here mounts empty
and fills after its own fetch, so a check taken once on mount would
record every section as empty and hide every heading on the page. An
empty section also drops its divider and its padding, so it reserves no
space and reads as absent.

WHY LOCAL GREEN DID NOT PREDICT THIS, which is the part worth carrying
further than this change. Two of the ten sections are `type: integration`,
and an integration leaf is served by OpenRegister's global registry
bundle, which CI never has because openregister gitignores its `/js/`.
So `case-files` renders on a dev instance and renders nothing on CI. A
local run cannot tell "the leaf rendered" from "the leaf exists here and
not there", and no number of local repetitions closes that gap.

THE ASSERTION IS NARROWED, NOT WEAKENED. Both kinds are held to the
honest invariant, ABSENT OR NON-EMPTY, never a heading over a void, read
through ONE polled evaluate rather than a snapshot of the host compared
against a retrying matcher on the heading. The eight sections that
resolve from dossiq's own bundle keep the full content assertion, and
they are the eight a broken `case-sections` registration would take
down, which is the mutation this test was proved against. The teeth are
still where the failure mode is.

Sections are asserted ATTACHED rather than visible, because an empty one
now has zero height: `toBeVisible` would fail on it for the very reason
the component is correct. The registry sections keep a visibility check,
where it is a claim rather than a measurement of CSS.

Verified by exit code: vitest 1075 tests over 85 files 0, eslint 0,
prettier 0, check:manifest 0, test:l10n 0, npm run build 0.
The first attempt wrote `filled` from inside the `:ref` callback, which
runs DURING the patch. Writing reactive state there either loops or is
dropped, so every section read as empty, every heading stayed hidden, and
two specs that had passed went red on a change meant to fix one of them.
Measure on `nextTick` instead, and only ASSIGN on an actual change, so a
mutation that does not alter the answer cannot re-render and re-fire the
observer.

The Files ordering spec moves off bounding boxes onto DOM order. A box
comparison asserts that both sections have height, and an empty section
correctly has none now, so it would fail on CI for the very reason the
component is right. Order is the claim that spec is actually making.
@rubenvdlinde
rubenvdlinde merged commit 811b284 into development Sep 9, 2026
46 of 48 checks passed
@rubenvdlinde
rubenvdlinde deleted the dq2-empty-section-absent branch September 9, 2026 08:16
@github-actions

github-actions Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Quality Report — ConductionNL/dossiq @ 154510c

Check PHP Vue Security License Tests
lint ✅
phpcs ✅
phpmd ✅
psalm ✅
phpstan ✅
phpmetrics ✅
eslint ✅
stylelint ✅
build ✅
check-manifest ✅
check-vue3-compile ✅
test-l10n ✅
format ✅
check-schema-l10n ✅
check-l10n-js ✅
composer ✅ ✅ 106/106
npm ✅ ✅ 549/549
app:check-code ⏭️
info.xml ✅
REUSE ❌
PHPUnit ✅
Newman ⏭️
Playwright ❌
Hydra gates ❌

Quality workflow — 2026-09-09 08:17 UTC

Download the full PDF report from the workflow artifacts.

rubenvdlinde added a commit that referenced this pull request Sep 9, 2026
…plementation (#2119)

Gate-16 failed on development with three changed methods missing @SPEC:
`setHostRef`, `hasContent` and `stopObserving` in CaseSectionsWidget, all
three added by #2052.

THE ANNOTATION WAS THE SMALL HALF. The reason the three had no @SPEC is that
#2052 shipped the behaviour with no spec delta at all: it changed the
component and its e2e test, and nothing else. So there was no requirement to
name. The nearest one, REQ-CDV-16, says the opposite of what now ships:
"each section SHALL carry its own heading", unconditionally.

Copying the neighbour would have been wrong twice over. `sections()` above
these methods anchors at
`openspec/changes/the-case-page-finished/specs/case-dashboard-view/spec.md`,
and that change was archived this morning, so the path resolves only through
gate-46's archive fallback rather than on disk.

SO THE REQUIREMENT IS WRITTEN DOWN. REQ-CDV-16 gains the clause the code
already enforces: a section is absent or non-empty, never a heading over a
void, and an empty state is content that keeps its heading. The scenario
carries the e2e test that already asserts exactly that invariant, so gate-19
is satisfied by a test that exists rather than one that is owed.

The three methods then anchor at the canonical spec, which resolves on disk.
Verified by running the gates at the same hydra-gates commit CI uses.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant