Fix issue #95: Make documentation a resizable window
All checks were successful
Test / test (push) Successful in 2s
All checks were successful
Test / test (push) Successful in 2s
This commit is contained in:
@@ -3,8 +3,10 @@
|
||||
// numbered group, translations for the group's label, and no link pointing at a page that does not
|
||||
// exist, (2) the page about an integration really documents what that integration offers, which is
|
||||
// checked against the sources that define it: the slash commands of discord-bot/src/commands.js and
|
||||
// the commands the Obsidian plugin registers, and (3) the routes: /docs and /docs/<slug> render the
|
||||
// documentation and every other address still opens the window app.
|
||||
// the commands the Obsidian plugin registers, (3) the routes: /docs and /docs/<slug> render the
|
||||
// documentation and every other address still opens the window app, and (4) inside a campaign the
|
||||
// same documentation opens as a window of its own instead of a trip to /docs
|
||||
// (Syndria98/dragonroll#95).
|
||||
//
|
||||
// `frontend/app/services/DocsMarkdown.js` is the pure part of the docs (headings, slugs, titles) and
|
||||
// is loaded straight from source, the way the other tests load the frontend services; it imports
|
||||
@@ -328,39 +330,89 @@ test("the main menu points at the documentation", () => {
|
||||
});
|
||||
|
||||
// Inside a campaign the documentation is reached from the top bar, on the left of the campaign
|
||||
// settings button (Syndria98/dragonroll#90).
|
||||
test("the campaign top bar points at the documentation", () => {
|
||||
// settings button (Syndria98/dragonroll#90), and it opens as a window of its own in front of the
|
||||
// workspace rather than as a trip to /docs (Syndria98/dragonroll#95).
|
||||
test("the campaign top bar opens the documentation as a window", () => {
|
||||
const topBar = readRepoFile("frontend", "app", "components", "viewer", "TopBar.vue");
|
||||
const right = /<div class="right">([\s\S]*?)<\/div>/.exec(topBar)?.[1];
|
||||
assert.ok(right, "expected the top bar to have its buttons in a right-hand group");
|
||||
|
||||
assert.match(right, /href="\/docs"/, "the top bar has to link to /docs");
|
||||
assert.match(right, /OpenDocumentation/, "the top bar has a button for the documentation");
|
||||
assert.match(right, /main-menu\.documentation/, "under the same label the main menu uses");
|
||||
assert.match(topBar, /CreateWindow\('documentation'\)/, "the button opens the documentation window");
|
||||
|
||||
// To the left of the settings button: the group is read left to right, so the link has to
|
||||
// To the left of the settings button: the group is read left to right, so the button has to
|
||||
// come first in it.
|
||||
const docsAt = right.indexOf('href="/docs"');
|
||||
const docsAt = right.indexOf("OpenDocumentation");
|
||||
const settingsAt = right.indexOf("OpenCampaignSettings");
|
||||
assert.ok(
|
||||
docsAt !== -1 && settingsAt !== -1 && docsAt < settingsAt,
|
||||
"the documentation button sits on the left of the settings button"
|
||||
);
|
||||
|
||||
// /docs is another page, and the open notes of the campaign live only in memory, so the link
|
||||
// opens it somewhere that does not throw the campaign away.
|
||||
assert.match(right, /target="_blank"/, "the campaign stays as it was behind the documentation");
|
||||
assert.match(right, /rel="[^"]*noopener/, "a tab the app does not control must not be able to reach it");
|
||||
// The open notes of the campaign live only in memory, so nothing the top bar does may leave
|
||||
// the app: a window comes to the front, an address would take the campaign away with it.
|
||||
assert.doesNotMatch(topBar, /href="\/docs"/, "the top bar does not send the campaign to /docs");
|
||||
assert.doesNotMatch(topBar, /target="_blank"/, "…nor opens a tab out of it");
|
||||
});
|
||||
|
||||
// The link is an `<a>` and the buttons are styled by element, so it carries its own look, in
|
||||
// theme colours like everything else.
|
||||
const look = /\.docs-button\s*\{[^}]*\}/.exec(topBar)?.[0];
|
||||
assert.ok(look, "the documentation link has to look like the buttons next to it");
|
||||
for (const declaration of [
|
||||
"background-color: var\\(--color-button-background\\)",
|
||||
"color: var\\(--color-text\\)",
|
||||
"border: solid 1px var\\(--color-border\\)",
|
||||
]) {
|
||||
assert.match(look, new RegExp(declaration), "the link's look uses the theme's colours");
|
||||
// The window the button opens (Syndria98/dragonroll#95): registered like every other window, and
|
||||
// reading its pages without ever leaving the window it is drawn in.
|
||||
test("the documentation is registered as a window", () => {
|
||||
const definitions = readRepoFile("frontend", "app", "services", "WindowDefinitions.js");
|
||||
const definition = /\n\s*documentation:\s*\{([\s\S]*?)\n\s{2}\}/.exec(definitions);
|
||||
assert.ok(definition, "the documentation is not registered as a window");
|
||||
|
||||
assert.match(definition[1], /title:\s*'windows\.documentation'/, "its title is an i18n key");
|
||||
assert.match(definition[1], /movable:\s*true/);
|
||||
assert.match(definition[1], /close:\s*\(\)\s*=>\s*ClearWindow\(\{\s*type:\s*'documentation'\s*\}\)/);
|
||||
|
||||
const component = /component:\s*\(\)\s*=>\s*import\(['"]~\/components\/windows\/([^'"]+)['"]\)/.exec(definition[1]);
|
||||
assert.ok(component, "the documentation window names no component of its own");
|
||||
assert.ok(
|
||||
fs.existsSync(path.join(__dirname, "..", "frontend", "app", "components", "windows", component[1])),
|
||||
`the documentation window points at a component that does not exist: ${component[1]}`
|
||||
);
|
||||
});
|
||||
|
||||
test("the documentation window reads the published pages without leaving itself", () => {
|
||||
const source = readRepoFile("frontend", "app", "components", "windows", "DocumentationWindow.vue");
|
||||
|
||||
// The pages are the ones of app/content/docs, read through the same service the /docs page uses.
|
||||
assert.match(source, /from '~\/services\/Docs'/, "the window reads the documentation through the docs service");
|
||||
for (const lookup of ["GetDocsNav", "GetDocsPage", "GetDocsFirstSlug"]) {
|
||||
assert.match(source, new RegExp(lookup), `the window does not use ${lookup}`);
|
||||
}
|
||||
|
||||
// Resizable, with a floor low enough to read the two columns on a small screen.
|
||||
assert.match(source, /SetResizable\(id,\s*true\)/, "the window is resizable");
|
||||
assert.match(source, /SetMinSize\(id,\s*\{\s*width:\s*\d+,\s*height:\s*\d+\s*\}\)/, "…and it says how small it goes");
|
||||
|
||||
// Nothing in it is a route: the window holds the page it shows, so following the sidebar
|
||||
// leaves the campaign behind it exactly as it was.
|
||||
assert.doesNotMatch(source, /NuxtLink|useRoute|navigateTo/, "the documentation window does not navigate the app");
|
||||
|
||||
// Which means the links the markdown carries (`[Foundry](/docs/foundry)`) and the sections of
|
||||
// a page have to be answered inside the window.
|
||||
assert.match(source, /\\\/docs/, "the markdown's links to the other pages are followed in the window");
|
||||
assert.match(source, /scrollIntoView/, "so are the sections of the page it is showing");
|
||||
assert.match(source, /preventDefault/, "…and none of them reaches the app's address");
|
||||
|
||||
// A window is not a page: the reading column is what scrolls, nothing is as tall as the viewport.
|
||||
const reading = /\.docs-reading\s*\{[^}]*\}/.exec(source)?.[0];
|
||||
assert.ok(reading, "the window has a reading column of its own");
|
||||
assert.match(reading, /overflow-y:\s*auto/, "…and that is what scrolls");
|
||||
assert.doesNotMatch(source, /100vh/, "a window fills itself, not the viewport");
|
||||
});
|
||||
|
||||
test("the documentation window is titled in every locale", () => {
|
||||
for (const locale of ["en", "es", "ca"]) {
|
||||
const strings = JSON.parse(readRepoFile("frontend", "i18n", "locales", locale, "windows.json"));
|
||||
const title = strings.documentation;
|
||||
assert.ok(title, `${locale} has no title for the documentation window`);
|
||||
if (locale !== "en") {
|
||||
assert.notEqual(title.toLowerCase(), "documentation", `the ${locale} window title is untranslated`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
@@ -484,3 +536,29 @@ test("the sections aside has more room around its links than the sidebar has", (
|
||||
"the sections aside asks for more padding than the two asides share"
|
||||
);
|
||||
});
|
||||
|
||||
// The /docs page and the documentation window render the very same HTML, so the markdown it renders
|
||||
// is styled once, in the stylesheet both of them load, rather than in whichever one asked for it
|
||||
// first (Syndria98/dragonroll#95).
|
||||
test("the rendered markdown is styled once, where both readers reach it", () => {
|
||||
const styles = readRepoFile("frontend", "app", "assets", "css", "main.scss");
|
||||
const markdown = styles.slice(styles.indexOf(".docs-markdown h1"));
|
||||
|
||||
for (const selector of [
|
||||
".docs-markdown h1",
|
||||
".docs-markdown h2",
|
||||
".docs-markdown h3",
|
||||
".docs-markdown p",
|
||||
".docs-markdown a",
|
||||
".docs-markdown code",
|
||||
".docs-markdown pre",
|
||||
".docs-markdown table",
|
||||
]) {
|
||||
assert.ok(markdown.includes(selector), `${selector} has to be styled for both readers of the docs`);
|
||||
}
|
||||
|
||||
// Theme colours, as everywhere: the window and the page are read on either theme.
|
||||
for (const colour of ["var\\(--color-border\\)", "var\\(--color-link\\)", "var\\(--color-background-light\\)"]) {
|
||||
assert.match(markdown, new RegExp(colour), "the markdown's look uses the theme's colours");
|
||||
}
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user