Fix #85: Style corrections on /docs #88

Merged
Syndria98 merged 2 commits from ai/issue-85 into master 2026-10-15 20:56:27 +00:00
2 changed files with 147 additions and 6 deletions

View File

@@ -108,11 +108,13 @@ useHead({
color: var(--color-text); 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-sidebar,
.docs-sections { .docs-sections {
position: sticky; position: sticky;
top: 0; top: 0;
max-height: 100vh; height: 100vh;
overflow-y: auto; overflow-y: auto;
box-sizing: border-box; box-sizing: border-box;
padding: 18px 14px; padding: 18px 14px;
@@ -208,8 +210,13 @@ useHead({
box-sizing: border-box; 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; max-width: 760px;
margin-inline: auto;
} }
.docs-kicker { .docs-kicker {
@@ -221,7 +228,6 @@ useHead({
} }
.docs-pager { .docs-pager {
max-width: 760px;
margin-top: 34px; margin-top: 34px;
padding-top: 18px; padding-top: 18px;
border-top: 1px solid var(--color-border); border-top: 1px solid var(--color-border);
@@ -256,8 +262,10 @@ useHead({
} }
.docs-sections { .docs-sections {
flex: 0 0 220px; flex: 0 0 240px;
width: 220px; 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); border-left: 1px solid var(--color-border);
} }
@@ -377,6 +385,18 @@ useHead({
background-color: var(--color-background-light); 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) { @media (max-width: 1200px) {
.docs-sections { .docs-sections {
display: none; display: none;
@@ -391,7 +411,7 @@ useHead({
.docs-sidebar, .docs-sidebar,
.docs-sections { .docs-sections {
position: static; position: static;
max-height: none; height: auto;
width: 100%; width: 100%;
border-left: none; border-left: none;
border-right: none; border-right: none;

View File

@@ -326,3 +326,124 @@ test("the main menu points at the documentation", () => {
assert.ok(strings.documentation, `${locale} has no label for the documentation link`); 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"
);
});