From fea03a0b783c5b8034964491e2f09abf8d416626 Mon Sep 17 00:00:00 2001 From: Roland Date: Wed, 5 Aug 2026 15:40:27 -0600 Subject: [PATCH] ui: pages own the space between their blocks Panels shared edges: two 1px borders meeting, which reads as one tall surface with a rule across it rather than a seam between two. Done as `margin-bottom` on the panel first, which is the anti-pattern, and it failed in both of the ways that rule is known to fail before the reading was done. It compounded with the gap of every Stack that already held panels -- four of them, spacing those lists at 35.2px against the app's 17.6px -- and the `:last-child` reset meant to keep trailing space off the bottom of a container silently did nothing, because Media wrapping makes a panel the only child of its own wrapper. On Status that separated four pairs out of five and left the first touching. So the space belongs to whatever stacks the blocks. `.wrolpi-stack` is on PageContainer, which every page uses, and on the three wrappers that stack blocks somewhere the page's own stack cannot reach: Settings' panel wrapper, the block below the video player, and the Zim and Map route wrappers, which hold their tab bar outside PageContainer. A gap rather than `> * + * { margin-top }`, which was tried and is quietly broken here: Media injects `.fresnel-container { margin: 0; padding: 0 }` at runtime, same specificity, later source order, so every wrapped block threw the margin away. A child cannot zero its parent's gap. It also means Media's hidden half contributes nothing, where the owl selector spaced around something invisible. With the page owning the spacing, the blocks that owned some of it had to give it up, or their margin was added to the gap: the tab bar (33px against 17.6 everywhere else), the shared search control bar and paginator on Videos/Archives/Docs/Files, the card grid, the file browser's filter row and the inventory search. Two margins deliberately stay -- the file browser's 4em, which reserves room for the sticky buttons (62645831), and heading margins, which bind a heading to the content below it. Tests plant each of the three failures: the wrapped block, a child that zeroes its own margin, and a hidden Media half. Verified in the browser on sixteen routes and in all four themes -- every stacked pair 17.6px, the map's 85vh box and the video player unchanged, no horizontal overflow. Co-Authored-By: Claude Opus 5 (1M context) --- app/src/App.css | 3 +- app/src/components/Common.js | 25 ++- app/src/components/Common.test.js | 18 +++ app/src/components/Files.js | 16 +- app/src/components/Map.js | 4 +- app/src/components/VideoPlayer.js | 4 +- app/src/components/Zim.js | 4 +- app/src/components/admin/Settings.js | 4 +- .../components/inventory/InventoryRoute.js | 5 +- app/src/components/ui/ui-layout.cy.js | 152 ++++++++++++++++++ app/src/components/ui/ui.css | 51 +++++- 11 files changed, 272 insertions(+), 14 deletions(-) diff --git a/app/src/App.css b/app/src/App.css index 20349c40..374a7609 100644 --- a/app/src/App.css +++ b/app/src/App.css @@ -590,7 +590,8 @@ tr.drag-deselecting td { .file-browser-filter-container { display: flex; justify-content: flex-end; - margin-bottom: 0.5em; + /* No `margin-bottom`: this is a top-level block of the Files page, and the page's stack + spaces it (see `.wrolpi-stack`). Its own 0.5em was added to that. */ } /* Double the default input width on desktop. */ diff --git a/app/src/components/Common.js b/app/src/components/Common.js index cd397fc2..93bc8414 100644 --- a/app/src/components/Common.js +++ b/app/src/components/Common.js @@ -660,13 +660,29 @@ export function TabLinks({links, right}) { } +/** + * The outer wrapper of a page, and the thing that decides how far apart its blocks sit. + * + * A page is a stack of panels -- the dashboard is five, Status six, Settings six -- and they used + * to share edges, because nothing anywhere put space between them. The space belongs here rather + * than on the panel: how far a panel sits from its neighbour is a property of the two being + * stacked, not of the panel, which also appears inside modals and grids that space it themselves. + * + * `.wrolpi-stack` spaces every top-level block of the page, whatever it is -- which is why it + * works through the `Media` wrappers that several pages put around a panel. It spaces the + * wrapper, and the wrapper is the sibling. + */ export function PageContainer(props) { return <> -
{props.children}
+
+ {props.children} +
-
{props.children}
+
+ {props.children} +
; } @@ -674,7 +690,10 @@ export function PageContainer(props) { export function CardGroupCentered(props) { // One responsive grid; it centres what it cannot fill, so the two viewports no // longer need separate markup. - return
+ // + // No `marginTop`: this is a top-level block on every module page, and the page's stack + // spaces it. Carrying one added to that gap. + return
{props.children}
} diff --git a/app/src/components/Common.test.js b/app/src/components/Common.test.js index 5996dc3d..f49767ba 100644 --- a/app/src/components/Common.test.js +++ b/app/src/components/Common.test.js @@ -4,6 +4,7 @@ import userEvent from '@testing-library/user-event'; import { CardLink, contrastingColor, contrastRatio, DirectorySearch, ExternalCardLink, HelpHeader, InfoHeader, loadRole, + PageContainer, SearchResultsInput, TAG_TEXT_DARK, TAG_TEXT_LIGHT, } from './Common'; import {healthRole} from './admin/ControllerPage'; @@ -707,3 +708,20 @@ describe('card links', () => { expect(link).toHaveClass('card-title-ellipsis'); }); }); + +describe('PageContainer', () => { + /* + * The wrapper that decides how far apart a page's blocks sit. The spacing itself is a + * stylesheet rule and is measured in ui-layout.cy.js, where there is a layout engine; what + * this asserts is that the rule is REACHED -- the class has to be on both of the responsive + * branches, or the spacing silently applies on one viewport and not the other. + */ + it('marks both of its viewport branches as a stack', () => { + const {container} = render(
Body
); + + const stacks = container.querySelectorAll('.wrolpi-stack'); + // Mobile and tablet-and-up, both rendered; `Media` hides one with CSS. + expect(stacks).toHaveLength(2); + stacks.forEach(stack => expect(stack.textContent).toBe('Body')); + }); +}); diff --git a/app/src/components/Files.js b/app/src/components/Files.js index f5b455ea..09e8428b 100644 --- a/app/src/components/Files.js +++ b/app/src/components/Files.js @@ -333,7 +333,14 @@ export function FilesView( ) { const {view} = useSearchView(); - const paginator =
+ /* + * No margin of its own. Videos, Archives, Docs and Files all render this as a top-level block + * of the page, and the page spaces its blocks (see `wrolpi-stack`) -- so a `marginTop: 2em` + * here added to that and put the pager twice as far from the results as anything else on the + * page sits from its neighbour. Zim keeps its own paginator, inside an accordion panel that + * does not stack, and is untouched. + */ + const paginator =
; @@ -817,7 +824,9 @@ export function SearchControlBar( inputRef={inputRef} />; - return
+ // No `marginBottom`: this is a top-level block on Videos, Archives and Docs, and the page + // spaces its own blocks. Carrying one here added to that gap. + return
{viewButton}
{searchInput}
- {showView &&
{viewButton}
} + {/* No margin: another top-level block, spaced by the page. */} + {showView &&
{viewButton}
} {body} {deepHint} {paginator} diff --git a/app/src/components/Map.js b/app/src/components/Map.js index d3487bf7..54993d3c 100644 --- a/app/src/components/Map.js +++ b/app/src/components/Map.js @@ -649,7 +649,9 @@ export function MapRoute() { {text: 'Manage', to: '/map/manage', key: 'manage'}, ]; - return
+ // `wrolpi-stack`: as in ZimRoute, this route wraps its own content instead of using + // PageContainer, so the spacing below the tab bar is this element's to provide. + return
}/> diff --git a/app/src/components/VideoPlayer.js b/app/src/components/VideoPlayer.js index 0e88cdc9..8e447387 100644 --- a/app/src/components/VideoPlayer.js +++ b/app/src/components/VideoPlayer.js @@ -472,7 +472,9 @@ function VideoPage({videoFile, prevFile, nextFile, fetchVideo, ...props}) { {captionUrls.map(i => )} } -
+ {/* `wrolpi-stack`: everything below the player is stacked in here rather than in the + page, so this is what spaces it. */} +
{title}
diff --git a/app/src/components/Zim.js b/app/src/components/Zim.js index cc055214..bb024057 100644 --- a/app/src/components/Zim.js +++ b/app/src/components/Zim.js @@ -527,7 +527,9 @@ export function ZimRoute() { {text: 'Manage', to: '/zim/manage', key: 'manage'}, ] - return
+ // `wrolpi-stack`: this route wraps its own content rather than using PageContainer, so it is + // what spaces the tab bar from the page below it. + return
}/> diff --git a/app/src/components/admin/Settings.js b/app/src/components/admin/Settings.js index 98cf6f23..8cfc8644 100644 --- a/app/src/components/admin/Settings.js +++ b/app/src/components/admin/Settings.js @@ -901,7 +901,9 @@ export function SettingsPage() { ; - return
+ // `wrolpi-stack`: these panels sit in a wrapper of this page's own, so the stack on + // PageContainer does not reach them and this wrapper is what has to space them. + return
diff --git a/app/src/components/inventory/InventoryRoute.js b/app/src/components/inventory/InventoryRoute.js index 00d353c2..4beb9c90 100644 --- a/app/src/components/inventory/InventoryRoute.js +++ b/app/src/components/inventory/InventoryRoute.js @@ -183,8 +183,9 @@ export function InventoryRoute() { {tab === 'items' && <> - {/* The search filter lives here so it clearly applies to the Items tab only, not Summary/Ration/Export. */} -
+ {/* The search filter lives here so it clearly applies to the Items tab only, not Summary/Ration/Export. + No margin of its own: it is a top-level block and the page's stack spaces it. */} +
diff --git a/app/src/components/ui/ui-layout.cy.js b/app/src/components/ui/ui-layout.cy.js index 93ed74b7..8e9d1105 100644 --- a/app/src/components/ui/ui-layout.cy.js +++ b/app/src/components/ui/ui-layout.cy.js @@ -116,6 +116,158 @@ describe('the interface scale actually reaches what it is supposed to', () => { }); }); +describe('a page stacks its own blocks', () => { + /* + * A page is built out of panels -- the dashboard is five, Status is six, Settings is six -- + * and nothing put space between them, so every pair shared an edge. Two 1px borders meeting + * do not read as a seam between two surfaces; they read as one tall surface with a rule across + * it, and which heading owns which content stops being obvious. + * + * The space is the page's, not the panel's. How far a panel sits from its neighbour is a + * property of the two of them being stacked, and the same panel also appears inside modals, + * grids and Mantine `Stack`s that space it themselves. This was tried the other way first, as + * `margin-bottom` on `.wrolpi-panel`, and it failed in both of the ways that rule is known to + * fail -- see the sibling test below, which is what stops it being tried again. + */ + + const gapsBetween = ($panels) => { + const rects = [...$panels].map((el) => el.getBoundingClientRect()); + return rects.slice(1).map((rect, index) => rect.top - rects[index].bottom); + }; + + it('leaves a gap between the panels it stacks', () => { + cy.mountUI(
+ Tags + Status + Calculators +
); + + cy.get('.wrolpi-panel').should(($panels) => { + const gaps = gapsBetween($panels); + expect(gaps, 'both pairs measured').to.have.length(2); + gaps.forEach((gap) => { + // Enough to read as a seam rather than a heavier border ... + expect(gap, 'gap between panels').to.be.at.least(12); + // ... and not so much that one page reads as unrelated cards. + expect(gap, 'gap between panels').to.be.at.most(28); + }); + }); + }); + + it('spaces a block that is wrapped as readily as a bare one', () => { + /* + * This is the case that chose where the rule lives. Several pages put a panel inside the + * responsive `Media` component, so the page's child is a wrapper rather than the panel. + * + * Spacing from the page handles that for free -- it spaces the wrapper, and the wrapper is + * the sibling. A `margin-bottom` on the panel plus the `:last-child` reset that would + * keep the trailing space off the bottom of a container does NOT: the panel is the only + * child of its wrapper, so `:last-child` matches it, zeroes the margin, and leaves it hard + * against the next panel. On Status that separated four pairs out of five and left the + * first touching -- one page showing both, which reads as a rendering glitch. + */ + cy.mountUI(
+
Wrapped, as Media does it
+ Bare +
); + + cy.get('.wrolpi-panel').should(($panels) => + expect(gapsBetween($panels)[0], 'gap across a wrapper').to.be.at.least(12)); + }); + + it('survives a block that zeroes its own margin', () => { + /* + * The reason this is a gap and not `> * + * { margin-top }`. The responsive `Media` + * component injects `.fresnel-container { margin: 0; padding: 0 }` into the document at + * runtime -- same specificity as the owl selector, later in source order -- so a wrapped + * block threw the margin away and went on touching its neighbour, while the bare blocks + * on the same page separated. A gap is the parent's, and a child cannot zero it. + * + * The margin here stands in for fresnel's rule; the point is that the spacing does not + * depend on the child's own margin being left alone. + */ + cy.mountUI(
+ Before +
Zeroed its own margin
+
); + + cy.get('.wrolpi-panel').should(($panels) => + expect(gapsBetween($panels)[0], 'gap despite the child margin').to.be.at.least(12)); + }); + + it('adds nothing before the first block or after the last', () => { + // A gap goes only between, so the page's own padding decides its edges. + cy.mountUI(
+ First + Last +
); + + cy.get('.wrolpi-stack').should(($stack) => { + const stack = $stack[0].getBoundingClientRect(); + const panels = [...$stack[0].querySelectorAll('.wrolpi-panel')] + .map(el => el.getBoundingClientRect()); + expect(panels[0].top - stack.top, 'above the first').to.be.closeTo(0, 0.5); + expect(stack.bottom - panels[1].bottom, 'below the last').to.be.closeTo(0, 0.5); + }); + }); + + it('grows the gap with the interface scale', () => { + // In px it would hold still while the panels either side of it grew. + cy.mountUI(
+ One + Two +
); + + cy.get('.wrolpi-stack').should(($stack) => { + const before = parseFloat(getComputedStyle($stack[0]).rowGap); + const root = Cypress.$('html')[0]; + const scale = parseFloat(getComputedStyle(root).getPropertyValue('--ui-scale')) || 1; + root.style.setProperty('--ui-scale', String(scale * 2)); + const after = parseFloat(getComputedStyle($stack[0]).rowGap); + root.style.removeProperty('--ui-scale'); + + expect(before, 'the gap exists at all').to.be.greaterThan(0); + expect(after / before, 'and doubles with the scale').to.be.closeTo(2, 0.05); + }); + }); + + it('contributes no gap for the half of a Media pair that is hidden', () => { + /* + * `Media` renders both viewports and hides one with `display: none`. A hidden flex item + * is not a flex item at all, so it takes no gap -- where `* + *` would have put space + * around something invisible and left a page with a stray 1rem hole in it. + */ + cy.mountUI(
+ Shown +
The other viewport
+ Also shown +
); + + cy.get('.wrolpi-panel:visible').should(($panels) => { + expect($panels, 'the hidden panel is not measured').to.have.length(2); + expect(gapsBetween($panels)[0], 'one gap, not two').to.be.at.most(28); + }); + }); + + it('leaves a panel with no outer margin, so a Stack can space it instead', () => { + /* + * The inverse rule, and the reason it is worth its own test: the moment a panel carries + * its own margin, it adds to the spacing of every container that already spaces its + * children. Four `Stack`s in the app hold nothing but panels -- the conflict list, both + * halves of the one-time pad, the electrical calculators -- and with `margin-bottom` on + * the panel they spaced those lists at 35.2px against the 17.6px used everywhere else. + */ + cy.mountUI(Composable); + + cy.get('.wrolpi-panel').should(($panel) => { + const styles = getComputedStyle($panel[0]); + ['marginTop', 'marginRight', 'marginBottom', 'marginLeft'].forEach((side) => { + expect(parseFloat(styles[side]), side).to.equal(0); + }); + }); + }); +}); + /* `--panel` is authored as a hex; computed backgrounds come back as rgb(). */ const hexToRgb = (hex) => { const value = hex.replace('#', ''); diff --git a/app/src/components/ui/ui.css b/app/src/components/ui/ui.css index 925c9c84..2706a468 100644 --- a/app/src/components/ui/ui.css +++ b/app/src/components/ui/ui.css @@ -250,7 +250,11 @@ html[data-theme="amber"] .wrolpi-pagination button[data-active] { justify-content: space-between; gap: 0.75rem; border-bottom: 1px solid var(--border); - margin-bottom: 0.875rem; + /* + * No `margin-bottom`. A tab bar is always the first block of a page, inside the page's own + * stack, so the 0.875rem it used to carry was added to the stack's gap and put the bar 33px + * from the content it labels where every other pair of blocks sat 17.6px apart. + */ } .wrolpi-tabs-links { @@ -1270,12 +1274,57 @@ html[data-theme="amber"] .wrolpi-progress-fill { background: var(--muted); } +/* ----------------------------------------------------------------- Stacks */ + +/* + * The space between stacked blocks, owned by whatever stacks them rather than by the blocks. + * + * `PageContainer` puts this on every page, so a page's own blocks are spaced without asking. A + * component that stacks blocks one level deeper -- Settings holds its six panels in a wrapper of + * its own -- puts it on that wrapper. Mantine's `Stack` is the same thing with the same 1rem gap + * and is equally correct where a call site already reaches for it. + * + * `gap`, not the `> * + * { margin-top }` this was written as first. The margin version is the + * older recommendation and it is quietly broken here: the responsive `Media` component injects + * `.fresnel-container { margin: 0; padding: 0 }` into the document at runtime, which has the same + * specificity as `.wrolpi-stack > * + *` and comes later in source order -- so every block a + * page wraps in `Media`, which on Status is the one carrying the CPU and RAM bars, threw the + * margin away and went on touching its neighbour. A gap belongs to the parent and a child cannot + * zero it. + * + * It also handles `Media`'s hidden half for free: the branch for the other viewport is + * `display: none`, so it is not a flex item and contributes no gap, where `* + *` would have + * spaced around something invisible. + * + * `align-items: stretch` is the default and is what keeps every block full-width, as it was as a + * block element. Heights are unaffected: the column is auto-height, so nothing shrinks, and the + * map's 85vh box and the CBZ viewer's full-height page measure the same as before. + */ +.wrolpi-stack { + display: flex; + flex-direction: column; + gap: 1rem; +} + /* ----------------------------------------------------------------- Panels */ .wrolpi-panel { background: var(--panel); border: 1px solid var(--border); padding: 0.875rem 1rem; + /* + * Deliberately NO outer margin. A panel is dropped into pages, modals, Stacks and grids, and + * how far it sits from its neighbour is a property of that relationship rather than of the + * panel -- so the space between stacked panels is owned by whatever stacks them + * (`.wrolpi-stack` for a page, Mantine's `Stack` gap inside a modal). + * + * This was tried the other way first, as `margin-bottom: 1rem` here, and it went wrong in + * both of the documented ways within the hour: it compounded with the gap of every `Stack` + * that already held panels (four of them, spacing those lists at 35.2px against the app's + * 17.6px), and the `:last-child` reset that would have kept the trailing space off the bottom + * of a container silently did nothing, because WROLPi wraps panels in the responsive `Media` + * component and a panel is frequently the only child of its own wrapper. + */ } /* Danger zones are dashed in every theme; it doubles as a colorblind-safe cue. */