diff --git a/AGENTS.md b/AGENTS.md index 0de66540..a309b38d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -142,7 +142,10 @@ name is the slug, and the first heading is the title. `services/Docs.js` reads t (`import.meta.glob(..., {query:'?raw'})`), builds the sidebar and renders a page with marked; `services/DocsMarkdown.js` holds the heading/slug helpers the sidebar and the anchors share and imports nothing so `tests/docs.test.js` can load it. A new group's label goes in `docs.json` under -`groups.` **in all three locales**. The first page is served at `/docs` itself. +`groups.` **in all three locales**. The first page is served at `/docs` itself, and inside a +campaign the top bar opens the same pages in the `documentation` window +(`components/windows/DocumentationWindow.vue`), which holds the page it shows as its own state instead +of a route so the campaign stays behind it. Two kinds of screens: **windows** (floating draggable/resizable overlays) and **content** — the campaign workspace (`TopBar` + `ContentSidebar` + note column + `StatusBar`), turned on when diff --git a/frontend/app/assets/css/main.scss b/frontend/app/assets/css/main.scss index 73addaa6..fc2c1019 100644 --- a/frontend/app/assets/css/main.scss +++ b/frontend/app/assets/css/main.scss @@ -417,4 +417,89 @@ span.artifact { .fold.is-collapsed > .fold-body { display: none; +} + +/* El markdown renderitzat de la documentació: tot dins de .docs-markdown, que ve de v-html. + Va aquí perquè la pàgina de /docs (views/DocsView.vue) i la finestra de documentació + (windows/DocumentationWindow.vue) se'l serveixen plegades. */ +.docs-markdown h1 { + margin: 0 0 14px 0; + font-family: 'MrEavesRemake', serif; + font-size: 2rem; + font-weight: normal; + line-height: 1.2; +} + +.docs-markdown h2 { + margin: 30px 0 10px 0; + padding-bottom: 4px; + border-bottom: 1px solid var(--color-border); + font-family: 'MrEavesRemake', serif; + font-size: 1.35rem; + font-weight: normal; + scroll-margin-top: 20px; +} + +.docs-markdown h3 { + margin: 22px 0 8px 0; + font-family: 'MrEavesRemake', serif; + font-size: 1.1rem; + font-weight: normal; + scroll-margin-top: 20px; +} + +.docs-markdown p, +.docs-markdown li { + line-height: 1.65; +} + +.docs-markdown ul, +.docs-markdown ol { + margin: 10px 0; + padding-left: 1.5em; +} + +.docs-markdown a { + color: var(--color-link); +} + +.docs-markdown code { + padding: 1px 5px; + border-radius: 4px; + background-color: var(--color-background-light); + font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; + font-size: 0.9em; +} + +.docs-markdown pre { + margin: 14px 0; + padding: 12px 14px; + border: 1px solid var(--color-border); + border-radius: 8px; + background-color: var(--color-background-light); + overflow-x: auto; +} + +.docs-markdown pre code { + padding: 0; + background-color: transparent; +} + +.docs-markdown table { + margin: 14px 0; + border-collapse: collapse; + width: 100%; +} + +.docs-markdown th, +.docs-markdown td { + padding: 7px 10px; + border: 1px solid var(--color-border); + text-align: left; + vertical-align: top; + line-height: 1.5; +} + +.docs-markdown th { + background-color: var(--color-background-light); } \ No newline at end of file diff --git a/frontend/app/components/viewer/TopBar.vue b/frontend/app/components/viewer/TopBar.vue index 083acca4..cddfa3e9 100644 --- a/frontend/app/components/viewer/TopBar.vue +++ b/frontend/app/components/viewer/TopBar.vue @@ -13,6 +13,13 @@ function OpenCampaignSettings() { CreateWindow('campaign_settings', { campaign: Campaign.value }); } +function OpenDocumentation() { + // La documentació és una finestra que va davant de l'espai de treball, així que les notes + // obertes no es perden. CreateWindow deixa sola una finestra que ja és oberta: tornar a + // prémer el botó no la torna a la primera pàgina. + CreateWindow('documentation'); +} + function ExitCampaign() { // Torn al menú principal: neteja la campanya (i el localStorage), amaga // l'espai de treball i reobre el menú @@ -35,11 +42,11 @@ function ExitCampaign() {
- - + + @@ -90,29 +97,6 @@ function ExitCampaign() { padding: 5px 10px; } -/* L'enllaç a la documentació és un `` i els botons estan estilats per element, així - que li toca portar el mateix look que els dos que té al costat. */ -.docs-button { - padding: 5px 10px; - margin: 5px 0; - font-size: 15px; - border-radius: 6px; - border: solid 1px var(--color-border); - background-color: var(--color-button-background); - color: var(--color-text); - text-align: center; - text-decoration: none; - transition: 300ms background-color; -} - -.docs-button:hover { - background-color: var(--color-button-hover); -} - -.docs-button:active { - background-color: var(--color-button-active); -} - .top-bar-title { padding: 10px; display: flex; diff --git a/frontend/app/components/views/DocsView.vue b/frontend/app/components/views/DocsView.vue index a08921f3..f9f834a5 100644 --- a/frontend/app/components/views/DocsView.vue +++ b/frontend/app/components/views/DocsView.vue @@ -301,88 +301,8 @@ useHead({ color: var(--color-link); } -/* El markdown renderitzat: tot dins de .docs-markdown, perquè ve de v-html. */ -.docs-markdown :deep(h1) { - margin: 0 0 14px 0; - font-family: 'MrEavesRemake', serif; - font-size: 2rem; - font-weight: normal; - line-height: 1.2; -} - -.docs-markdown :deep(h2) { - margin: 30px 0 10px 0; - padding-bottom: 4px; - border-bottom: 1px solid var(--color-border); - font-family: 'MrEavesRemake', serif; - font-size: 1.35rem; - font-weight: normal; - scroll-margin-top: 20px; -} - -.docs-markdown :deep(h3) { - margin: 22px 0 8px 0; - font-family: 'MrEavesRemake', serif; - font-size: 1.1rem; - font-weight: normal; - scroll-margin-top: 20px; -} - -.docs-markdown :deep(p), -.docs-markdown :deep(li) { - line-height: 1.65; -} - -.docs-markdown :deep(ul), -.docs-markdown :deep(ol) { - margin: 10px 0; - padding-left: 1.5em; -} - -.docs-markdown :deep(a) { - color: var(--color-link); -} - -.docs-markdown :deep(code) { - padding: 1px 5px; - border-radius: 4px; - background-color: var(--color-background-light); - font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; - font-size: 0.9em; -} - -.docs-markdown :deep(pre) { - margin: 14px 0; - padding: 12px 14px; - border: 1px solid var(--color-border); - border-radius: 8px; - background-color: var(--color-background-light); - overflow-x: auto; -} - -.docs-markdown :deep(pre code) { - padding: 0; - background-color: transparent; -} - -.docs-markdown :deep(table) { - margin: 14px 0; - border-collapse: collapse; - width: 100%; -} - -.docs-markdown :deep(th), -.docs-markdown :deep(td) { - padding: 7px 10px; - border: 1px solid var(--color-border); - text-align: left; - vertical-align: top; - line-height: 1.5; -} - -.docs-markdown :deep(th) { - background-color: var(--color-background-light); -} +/* El markdown renderitzat ve estilat a assets/css/main.scss, sota .docs-markdown, perquè la + finestra de documentació (windows/DocumentationWindow.vue) se'l serveix igualment. */ /* 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. */ diff --git a/frontend/app/components/windows/DocumentationWindow.vue b/frontend/app/components/windows/DocumentationWindow.vue new file mode 100644 index 00000000..1a04aeca --- /dev/null +++ b/frontend/app/components/windows/DocumentationWindow.vue @@ -0,0 +1,261 @@ + + + + + + + diff --git a/frontend/app/services/WindowDefinitions.js b/frontend/app/services/WindowDefinitions.js index 5b51fd6a..a16110b6 100644 --- a/frontend/app/services/WindowDefinitions.js +++ b/frontend/app/services/WindowDefinitions.js @@ -120,6 +120,12 @@ const defWindows = { component: () => import('~/components/windows/PinnedNoteWindow.vue'), close: () => ClearWindow({type: 'pinned_note'}), movable: true + }, + documentation: { + title: 'windows.documentation', + component: () => import('~/components/windows/DocumentationWindow.vue'), + close: () => ClearWindow({type: 'documentation'}), + movable: true } } diff --git a/frontend/i18n/locales/ca/windows.json b/frontend/i18n/locales/ca/windows.json index 792fb2f4..522aec26 100644 --- a/frontend/i18n/locales/ca/windows.json +++ b/frontend/i18n/locales/ca/windows.json @@ -10,6 +10,7 @@ "create-map": "Crear mapa", "map-viewer": "Mapa", "pinned-note": "Nota fixada", + "documentation": "Documentació", "item-sheet": "Objecte", "icon-source": "Tria una icona", "foundry-icons": "Icones del Foundry" diff --git a/frontend/i18n/locales/en/windows.json b/frontend/i18n/locales/en/windows.json index b1b98510..0e631520 100644 --- a/frontend/i18n/locales/en/windows.json +++ b/frontend/i18n/locales/en/windows.json @@ -10,6 +10,7 @@ "create-map": "Create Map", "map-viewer": "Map", "pinned-note": "Pinned note", + "documentation": "Documentation", "item-sheet": "Item", "icon-source": "Choose an icon", "foundry-icons": "Foundry icons" diff --git a/frontend/i18n/locales/es/windows.json b/frontend/i18n/locales/es/windows.json index fb897d13..3f245670 100644 --- a/frontend/i18n/locales/es/windows.json +++ b/frontend/i18n/locales/es/windows.json @@ -10,6 +10,7 @@ "create-map": "Crear mapa", "map-viewer": "Mapa", "pinned-note": "Nota fijada", + "documentation": "Documentación", "item-sheet": "Objeto", "icon-source": "Elegir icono", "foundry-icons": "Iconos de Foundry" diff --git a/tests/docs.test.js b/tests/docs.test.js index d78d5b53..1f23c1d7 100644 --- a/tests/docs.test.js +++ b/tests/docs.test.js @@ -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/ render the -// documentation and every other address still opens the window app. +// the commands the Obsidian plugin registers, (3) the routes: /docs and /docs/ 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 = /
([\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 `` 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"); + } +});