diff --git a/frontend/app/components/views/DocsView.vue b/frontend/app/components/views/DocsView.vue index 5d34cf1d..124d2289 100644 --- a/frontend/app/components/views/DocsView.vue +++ b/frontend/app/components/views/DocsView.vue @@ -108,11 +108,13 @@ useHead({ color: var(--color-text); } +/* Els dos aside fan la pàgina sencera avall: amb alçada d'una pantalla i enganxats a + dalt, el fons i la vora arriben sempre fins a baix, per molt llarg que sigui el text. */ .docs-sidebar, .docs-sections { position: sticky; top: 0; - max-height: 100vh; + height: 100vh; overflow-y: auto; box-sizing: border-box; padding: 18px 14px; @@ -208,8 +210,13 @@ useHead({ box-sizing: border-box; } -.docs-article { +/* La columna de lectura, centrada dins l'espai que deixa la barra lateral: en una finestra + ampla el text queda al mig, no enganxat a l'esquerra. */ +.docs-article, +.docs-pager { + width: 100%; max-width: 760px; + margin-inline: auto; } .docs-kicker { @@ -221,7 +228,6 @@ useHead({ } .docs-pager { - max-width: 760px; margin-top: 34px; padding-top: 18px; border-top: 1px solid var(--color-border); @@ -256,8 +262,10 @@ useHead({ } .docs-sections { - flex: 0 0 220px; - width: 220px; + flex: 0 0 240px; + width: 240px; + /* Més aire al voltant dels apartats, que ara mateix van clavats a la vora. */ + padding: 26px 22px 26px 18px; border-left: 1px solid var(--color-border); } @@ -377,6 +385,18 @@ useHead({ background-color: var(--color-background-light); } +/* Finestra molt ampla: tot el conjunt va al mig, així els apartats queden a prop del + text en lloc d'estirats cap al cantó dret de la pantalla. */ +@media (min-width: 1440px) { + .docs { + justify-content: center; + } + + .docs-main { + flex: 0 1 860px; + } +} + @media (max-width: 1200px) { .docs-sections { display: none; @@ -391,7 +411,7 @@ useHead({ .docs-sidebar, .docs-sections { position: static; - max-height: none; + height: auto; width: 100%; border-left: none; border-right: none; diff --git a/tests/docs.test.js b/tests/docs.test.js index 409792df..587f08a8 100644 --- a/tests/docs.test.js +++ b/tests/docs.test.js @@ -326,3 +326,124 @@ test("the main menu points at the documentation", () => { assert.ok(strings.documentation, `${locale} has no label for the documentation link`); } }); + +// --- How the documentation is laid out (Syndria98/dragonroll#85) --- + +// The `")) + .replace(/\/\*[\s\S]*?\*\//g, ""); + + const rules = []; + + function scan(text, media) { + let index = 0; + for (;;) { + const brace = text.indexOf("{", index); + if (brace === -1) return rules; + + const selector = text.slice(index, brace).trim(); + let depth = 1; + let cursor = brace + 1; + while (cursor < text.length && depth > 0) { + if (text[cursor] === "{") depth += 1; + else if (text[cursor] === "}") depth -= 1; + cursor += 1; + } + + const body = text.slice(brace + 1, cursor - 1); + if (selector.startsWith("@")) scan(body, selector); + else rules.push({ selector, media, declarations: body }); + index = cursor; + } + } + + return scan(css, null); +} + +const styleRules = DocsStyleRules(); + +// The rules that name a class, with `media` null for the plain ones and "min-width" / "max-width" +// for the ones a media query switches on. The last one wins where they overlap, as in a stylesheet. +function RulesFor(className, media = null) { + return styleRules.filter((rule) => + rule.selector.split(",").some((name) => name.trim() === className) && + (media === null ? rule.media === null : Boolean(rule.media) && rule.media.includes(media)) + ); +} + +// A `padding:` shorthand spread over its four sides, the way the browser reads it. +function PaddingOf(rule) { + const shorthand = rule.declarations.match(/(?:^|[;\s])padding:\s*([^;]+)/); + assert.ok(shorthand, `the ${rule.selector} rule sets no padding to compare`); + + const values = shorthand[1].trim().split(/\s+/).map((value) => parseFloat(value)); + assert.ok( + values.length <= 4 && values.every((value) => Number.isFinite(value)), + `only px padding is compared here, ${rule.selector} has "${shorthand[1].trim()}"` + ); + + return { + top: values[0], + right: values[1] ?? values[0], + bottom: values[2] ?? values[0], + left: values[3] ?? values[1] ?? values[0], + }; +} + +test("the two asides are as tall as the page they stand beside", () => { + for (const className of [".docs-sidebar", ".docs-sections"]) { + const aside = RulesFor(className).find((rule) => /position:\s*sticky/.test(rule.declarations)); + assert.ok(aside, `${className} has to stay beside the text while the page scrolls`); + assert.match(aside.declarations, /height:\s*100vh/, `${className} has to fill the page, not just its own contents`); + assert.doesNotMatch(aside.declarations, /max-height/, `${className} is capped at a screen height by 'height'`); + } +}); + +test("a narrow window stacks the columns and lets each one be its own height", () => { + const stacked = RulesFor(".docs-sidebar", "max-width"); + assert.equal(stacked.length, 1, "the stacked layout is set by one rule"); + assert.match(stacked[0].declarations, /position:\s*static/, "a stacked sidebar does not follow the scroll"); + assert.match(stacked[0].declarations, /height:\s*auto/, "…and it is not held at a screen height either"); +}); + +test("the reading column is centred in the space left beside the sidebar", () => { + const reading = RulesFor(".docs-article").find((rule) => /max-width:/.test(rule.declarations)); + assert.ok(reading, "the text has to be capped in width to be readable"); + assert.match(reading.declarations, /margin-inline:\s*auto/, "…and centred in the space left beside the sidebar"); + assert.match(reading.selector, /\.docs-pager/, "the pager under the text follows the same column"); +}); + +test("a very wide window keeps the sections next to the text, not at the edge of the screen", () => { + const centred = RulesFor(".docs", "min-width"); + assert.equal(centred.length, 1, "one wide window rule centres the documentation"); + assert.match(centred[0].declarations, /justify-content:\s*center/); + + const wider = Number(centred[0].media.match(/min-width:\s*(\d+)/)[1]); + assert.ok(wider >= 1400, `${wider}px is not a wide window: the layout breaks before that`); + + const main = RulesFor(".docs-main", "min-width"); + assert.equal(main.length, 1, "the main column is capped once the window is wide"); + assert.match(main[0].declarations, /flex:\s*0 1 \d+px/, "…so it stops growing and the sections sit next to it"); +}); + +test("the sections aside has more room around its links than the sidebar has", () => { + const shared = RulesFor(".docs-sidebar").find((rule) => /padding:/.test(rule.declarations)); + const sections = RulesFor(".docs-sections").filter((rule) => /padding:/.test(rule.declarations)).pop(); + assert.ok(sections && sections !== shared, "the sections aside sets its own padding"); + + const room = PaddingOf(sections); + const sidebar = PaddingOf(shared); + + for (const side of ["top", "right", "bottom", "left"]) { + assert.ok(room[side] >= sidebar[side], `the sections aside is tighter than the sidebar on the ${side}`); + } + assert.ok( + ["top", "right", "bottom", "left"].some((side) => room[side] > sidebar[side]), + "the sections aside asks for more padding than the two asides share" + ); +});