Fix #85: Style corrections on /docs #88
@@ -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;
|
||||
|
||||
@@ -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 `<style>` of DocsView.vue read as `{ selector, media, declarations }` rules: the block is
|
||||
// flat — every rule is a top level selector and the only nesting is the media queries — so pairing
|
||||
// braces is enough, and the test does not need a stylesheet parser the repository root lacks.
|
||||
function DocsStyleRules() {
|
||||
const source = readRepoFile("frontend", "app", "components", "views", "DocsView.vue");
|
||||
const css = source
|
||||
.slice(source.indexOf(">", source.indexOf("<style")) + 1, source.indexOf("</style>"))
|
||||
.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"
|
||||
);
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user