Fix #95: Make documentation a resizable window #97
@@ -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;
|
(`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
|
`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
|
nothing so `tests/docs.test.js` can load it. A new group's label goes in `docs.json` under
|
||||||
`groups.<folder>` **in all three locales**. The first page is served at `/docs` itself.
|
`groups.<folder>` **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
|
Two kinds of screens: **windows** (floating draggable/resizable overlays) and **content** — the
|
||||||
campaign workspace (`TopBar` + `ContentSidebar` + note column + `StatusBar`), turned on when
|
campaign workspace (`TopBar` + `ContentSidebar` + note column + `StatusBar`), turned on when
|
||||||
|
|||||||
@@ -418,3 +418,88 @@ span.artifact {
|
|||||||
.fold.is-collapsed > .fold-body {
|
.fold.is-collapsed > .fold-body {
|
||||||
display: none;
|
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);
|
||||||
|
}
|
||||||
@@ -13,6 +13,13 @@ function OpenCampaignSettings() {
|
|||||||
CreateWindow('campaign_settings', { campaign: Campaign.value });
|
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() {
|
function ExitCampaign() {
|
||||||
// Torn al menú principal: neteja la campanya (i el localStorage), amaga
|
// Torn al menú principal: neteja la campanya (i el localStorage), amaga
|
||||||
// l'espai de treball i reobre el menú
|
// l'espai de treball i reobre el menú
|
||||||
@@ -35,11 +42,11 @@ function ExitCampaign() {
|
|||||||
<TopSearchBar></TopSearchBar>
|
<TopSearchBar></TopSearchBar>
|
||||||
</div>
|
</div>
|
||||||
<div class="right">
|
<div class="right">
|
||||||
<!-- La documentació és una pàgina a part (/docs), i una pestanya nova deixa la
|
<!-- La documentació s'obre en una finestra seva, davant de la campanya: les notes
|
||||||
campanya tal com era: les notes obertes no es perden. -->
|
obertes no es perden i no cal obrir una pestanya nova. -->
|
||||||
<a class="btn-primary docs-button sound-click" href="/docs" target="_blank" rel="noopener noreferrer">
|
<button class="btn-primary settings-button docs-button sound-click" type="button" @click="OpenDocumentation">
|
||||||
{{ $t('main-menu.documentation') }}
|
{{ $t('main-menu.documentation') }}
|
||||||
</a>
|
</button>
|
||||||
<button class="btn-primary settings-button sound-click" type="button" @click="OpenCampaignSettings">
|
<button class="btn-primary settings-button sound-click" type="button" @click="OpenCampaignSettings">
|
||||||
{{ $t('main-menu.settings') }}
|
{{ $t('main-menu.settings') }}
|
||||||
</button>
|
</button>
|
||||||
@@ -90,29 +97,6 @@ function ExitCampaign() {
|
|||||||
padding: 5px 10px;
|
padding: 5px 10px;
|
||||||
}
|
}
|
||||||
|
|
||||||
/* L'enllaç a la documentació és un `<a>` 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 {
|
.top-bar-title {
|
||||||
padding: 10px;
|
padding: 10px;
|
||||||
display: flex;
|
display: flex;
|
||||||
|
|||||||
@@ -301,88 +301,8 @@ useHead({
|
|||||||
color: var(--color-link);
|
color: var(--color-link);
|
||||||
}
|
}
|
||||||
|
|
||||||
/* El markdown renderitzat: tot dins de .docs-markdown, perquè ve de v-html. */
|
/* El markdown renderitzat ve estilat a assets/css/main.scss, sota .docs-markdown, perquè la
|
||||||
.docs-markdown :deep(h1) {
|
finestra de documentació (windows/DocumentationWindow.vue) se'l serveix igualment. */
|
||||||
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);
|
|
||||||
}
|
|
||||||
|
|
||||||
/* Finestra molt ampla: tot el conjunt va al mig, així els apartats queden a prop del
|
/* 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. */
|
text en lloc d'estirats cap al cantó dret de la pantalla. */
|
||||||
|
|||||||
261
frontend/app/components/windows/DocumentationWindow.vue
Normal file
261
frontend/app/components/windows/DocumentationWindow.vue
Normal file
@@ -0,0 +1,261 @@
|
|||||||
|
<script setup>
|
||||||
|
import { computed, nextTick, onMounted, ref } from 'vue';
|
||||||
|
import { SetupHandle, SetSize, ResetPosition, Top, SetResizable, SetMinSize } from '@/services/Windows';
|
||||||
|
|
||||||
|
import WindowHandle from './partials/WindowHandle.vue';
|
||||||
|
import { GetDocsFirstSlug, GetDocsNav, GetDocsPage } from '~/services/Docs';
|
||||||
|
|
||||||
|
// La documentació dins d'una finestra: el sumari a l'esquerra i la pàgina al centre, amb el
|
||||||
|
// mateix contingut de app/content/docs que la pàgina pública de /docs (mira ~/services/Docs.js).
|
||||||
|
// El sumari no porta enlloc amb rutes sinó amb estat propi, així obrir la documentació dins
|
||||||
|
// d'una campanya no deixa les notes obertes enrere.
|
||||||
|
const props = defineProps(['data']);
|
||||||
|
const id = props.data.id;
|
||||||
|
|
||||||
|
const handle = ref(null);
|
||||||
|
const wrapper = ref(null);
|
||||||
|
const reading = ref(null);
|
||||||
|
|
||||||
|
const nav = GetDocsNav();
|
||||||
|
const slug = ref(GetDocsFirstSlug());
|
||||||
|
const page = computed(() => GetDocsPage(slug.value));
|
||||||
|
|
||||||
|
function GoTo(target) {
|
||||||
|
if (!GetDocsPage(target)) return;
|
||||||
|
slug.value = target;
|
||||||
|
// Cada pàgina es comença a dalt, com faria el navegador.
|
||||||
|
nextTick(() => { if (reading.value) reading.value.scrollTop = 0; });
|
||||||
|
}
|
||||||
|
|
||||||
|
// Els enllaços que el markdown porta a dins (`[Foundry](/docs/foundry)`) i els seus apartats
|
||||||
|
// s'han de seguir dins la finestra: sortir-ne per via d'una ruta deixaria la campanya enrere.
|
||||||
|
function OnContentClick(event) {
|
||||||
|
const link = event.target?.closest?.('a');
|
||||||
|
if (!link) return;
|
||||||
|
|
||||||
|
const href = link.getAttribute('href') || '';
|
||||||
|
|
||||||
|
// Un apartat de la pàgina: el que fila és la columna de lectura, no la pantalla.
|
||||||
|
if (href.startsWith('#')) {
|
||||||
|
if (href.length < 2) return;
|
||||||
|
const heading = reading.value?.querySelector('#' + CSS.escape(href.slice(1)));
|
||||||
|
if (!heading) return;
|
||||||
|
event.preventDefault();
|
||||||
|
heading.scrollIntoView({ block: 'start' });
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
const inside = /^\/docs\/?([a-z0-9-]*)$/.exec(href);
|
||||||
|
if (inside) {
|
||||||
|
event.preventDefault();
|
||||||
|
GoTo(inside[1] || GetDocsFirstSlug());
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Fora de la documentació: una pestanya nova, que la campanya no es mou d'aquí.
|
||||||
|
if (href && !href.startsWith('/')) {
|
||||||
|
event.preventDefault();
|
||||||
|
window.open(href, '_blank', 'noopener');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
onMounted(() => {
|
||||||
|
Top(wrapper);
|
||||||
|
SetupHandle(id, handle);
|
||||||
|
SetSize(id, {
|
||||||
|
width: Math.max(620, Math.min(1000, window.innerWidth - 24)),
|
||||||
|
height: Math.max(420, Math.min(780, window.innerHeight - 32))
|
||||||
|
});
|
||||||
|
ResetPosition(id, 'center');
|
||||||
|
SetResizable(id, true);
|
||||||
|
SetMinSize(id, { width: 620, height: 420 });
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<div class="window-wrapper" :id="'window-wrapper-' + id" ref="wrapper">
|
||||||
|
<WindowHandle :window="id" ref="handle"></WindowHandle>
|
||||||
|
|
||||||
|
<!-- Body -->
|
||||||
|
<div class="docs-body">
|
||||||
|
<aside class="docs-contents" :aria-label="$t('docs.contents')">
|
||||||
|
<section v-for="group in nav" :key="group.key" class="docs-group">
|
||||||
|
<h2 class="docs-group-title">{{ $t(`docs.groups.${group.key}`) }}</h2>
|
||||||
|
<ul>
|
||||||
|
<li v-for="entry in group.pages" :key="entry.slug">
|
||||||
|
<button
|
||||||
|
type="button"
|
||||||
|
class="docs-nav-link sound-click"
|
||||||
|
:class="{ active: entry.slug === slug }"
|
||||||
|
v-on:click="GoTo(entry.slug)"
|
||||||
|
>{{ entry.title }}</button>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
</section>
|
||||||
|
</aside>
|
||||||
|
|
||||||
|
<div class="docs-reading" ref="reading">
|
||||||
|
<template v-if="page">
|
||||||
|
<article class="docs-article" v-on:click="OnContentClick">
|
||||||
|
<p class="docs-kicker">{{ $t(`docs.groups.${page.group}`) }}</p>
|
||||||
|
<!-- El contingut és markdown nostre, de app/content/docs -->
|
||||||
|
<div class="docs-markdown" v-html="page.html"></div>
|
||||||
|
</article>
|
||||||
|
|
||||||
|
<nav class="docs-pager">
|
||||||
|
<button
|
||||||
|
v-if="page.previous"
|
||||||
|
type="button"
|
||||||
|
class="docs-pager-link sound-click"
|
||||||
|
v-on:click="GoTo(page.previous.slug)"
|
||||||
|
>
|
||||||
|
<span class="docs-pager-label">{{ $t('docs.previous') }}</span>
|
||||||
|
<strong>{{ page.previous.title }}</strong>
|
||||||
|
</button>
|
||||||
|
<button
|
||||||
|
v-if="page.next"
|
||||||
|
type="button"
|
||||||
|
class="docs-pager-link next sound-click"
|
||||||
|
v-on:click="GoTo(page.next.slug)"
|
||||||
|
>
|
||||||
|
<span class="docs-pager-label">{{ $t('docs.next') }}</span>
|
||||||
|
<strong>{{ page.next.title }}</strong>
|
||||||
|
</button>
|
||||||
|
</nav>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<article v-else class="docs-article">
|
||||||
|
<h1>{{ $t('docs.title') }}</h1>
|
||||||
|
<p>{{ $t('docs.not-found', { page: slug }) }}</p>
|
||||||
|
</article>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
|
||||||
|
<style scoped lang="scss">
|
||||||
|
/* El sumari i la lectura són les dues columnes d'una finestra: cada una fila per la seva,
|
||||||
|
res d'una pantalla d'alçada ni de sticky, que la finestra ja és el que es mou. */
|
||||||
|
.docs-body {
|
||||||
|
display: flex;
|
||||||
|
flex: 1;
|
||||||
|
width: 100%;
|
||||||
|
min-height: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-contents {
|
||||||
|
flex: 0 0 212px;
|
||||||
|
min-width: 0;
|
||||||
|
box-sizing: border-box;
|
||||||
|
padding: 14px 10px;
|
||||||
|
border-right: 1px solid var(--color-border);
|
||||||
|
overflow-y: auto;
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
gap: 16px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-group-title {
|
||||||
|
margin: 0 0 6px 0;
|
||||||
|
font-family: 'MrEavesRemake', serif;
|
||||||
|
font-size: 0.78rem;
|
||||||
|
font-weight: normal;
|
||||||
|
letter-spacing: 0.08em;
|
||||||
|
text-transform: uppercase;
|
||||||
|
color: var(--color-gray);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-contents ul {
|
||||||
|
margin: 0;
|
||||||
|
padding: 0;
|
||||||
|
list-style: none;
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
gap: 2px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Les pàgines del sumari són botons: una finestra no té rutes a seguir. */
|
||||||
|
.docs-nav-link {
|
||||||
|
width: 100%;
|
||||||
|
margin: 0;
|
||||||
|
padding: 6px 9px;
|
||||||
|
border: none;
|
||||||
|
border-radius: 6px;
|
||||||
|
box-shadow: none;
|
||||||
|
background-color: transparent;
|
||||||
|
font-size: 0.95rem;
|
||||||
|
line-height: 1.35;
|
||||||
|
text-align: left;
|
||||||
|
color: var(--color-text);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-nav-link:hover {
|
||||||
|
background-color: var(--color-hover);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-nav-link.active {
|
||||||
|
background-color: var(--color-background-soft);
|
||||||
|
color: var(--color-link);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-reading {
|
||||||
|
flex: 1;
|
||||||
|
min-width: 0;
|
||||||
|
box-sizing: border-box;
|
||||||
|
padding: 20px 26px 40px 26px;
|
||||||
|
overflow-y: auto;
|
||||||
|
/* El que es llegeix es pot seleccionar, encara que una finestra no ho permeti per defecte. */
|
||||||
|
user-select: text;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* La columna de lectura, centrada dins l'espai que deixa el sumari. */
|
||||||
|
.docs-article,
|
||||||
|
.docs-pager {
|
||||||
|
width: 100%;
|
||||||
|
max-width: 720px;
|
||||||
|
margin-inline: auto;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-kicker {
|
||||||
|
margin: 0 0 4px 0;
|
||||||
|
font-size: 0.8rem;
|
||||||
|
letter-spacing: 0.08em;
|
||||||
|
text-transform: uppercase;
|
||||||
|
color: var(--color-gray);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-pager {
|
||||||
|
margin-top: 30px;
|
||||||
|
padding-top: 16px;
|
||||||
|
border-top: 1px solid var(--color-border);
|
||||||
|
display: flex;
|
||||||
|
gap: 14px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* Són els botons d'abans i després, no botons d'un formulari: van plans, com a /docs. */
|
||||||
|
.docs-pager-link {
|
||||||
|
flex: 1 1 0;
|
||||||
|
min-width: 0;
|
||||||
|
margin: 0;
|
||||||
|
padding: 10px 12px;
|
||||||
|
border: 1px solid var(--color-border);
|
||||||
|
border-radius: 8px;
|
||||||
|
box-shadow: none;
|
||||||
|
text-align: left;
|
||||||
|
color: var(--color-text);
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-pager-link.next {
|
||||||
|
text-align: right;
|
||||||
|
}
|
||||||
|
|
||||||
|
.docs-pager-label {
|
||||||
|
display: block;
|
||||||
|
font-size: 0.78rem;
|
||||||
|
letter-spacing: 0.06em;
|
||||||
|
text-transform: uppercase;
|
||||||
|
color: var(--color-gray);
|
||||||
|
}
|
||||||
|
</style>
|
||||||
@@ -120,6 +120,12 @@ const defWindows = {
|
|||||||
component: () => import('~/components/windows/PinnedNoteWindow.vue'),
|
component: () => import('~/components/windows/PinnedNoteWindow.vue'),
|
||||||
close: () => ClearWindow({type: 'pinned_note'}),
|
close: () => ClearWindow({type: 'pinned_note'}),
|
||||||
movable: true
|
movable: true
|
||||||
|
},
|
||||||
|
documentation: {
|
||||||
|
title: 'windows.documentation',
|
||||||
|
component: () => import('~/components/windows/DocumentationWindow.vue'),
|
||||||
|
close: () => ClearWindow({type: 'documentation'}),
|
||||||
|
movable: true
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -10,6 +10,7 @@
|
|||||||
"create-map": "Crear mapa",
|
"create-map": "Crear mapa",
|
||||||
"map-viewer": "Mapa",
|
"map-viewer": "Mapa",
|
||||||
"pinned-note": "Nota fixada",
|
"pinned-note": "Nota fixada",
|
||||||
|
"documentation": "Documentació",
|
||||||
"item-sheet": "Objecte",
|
"item-sheet": "Objecte",
|
||||||
"icon-source": "Tria una icona",
|
"icon-source": "Tria una icona",
|
||||||
"foundry-icons": "Icones del Foundry"
|
"foundry-icons": "Icones del Foundry"
|
||||||
|
|||||||
@@ -10,6 +10,7 @@
|
|||||||
"create-map": "Create Map",
|
"create-map": "Create Map",
|
||||||
"map-viewer": "Map",
|
"map-viewer": "Map",
|
||||||
"pinned-note": "Pinned note",
|
"pinned-note": "Pinned note",
|
||||||
|
"documentation": "Documentation",
|
||||||
"item-sheet": "Item",
|
"item-sheet": "Item",
|
||||||
"icon-source": "Choose an icon",
|
"icon-source": "Choose an icon",
|
||||||
"foundry-icons": "Foundry icons"
|
"foundry-icons": "Foundry icons"
|
||||||
|
|||||||
@@ -10,6 +10,7 @@
|
|||||||
"create-map": "Crear mapa",
|
"create-map": "Crear mapa",
|
||||||
"map-viewer": "Mapa",
|
"map-viewer": "Mapa",
|
||||||
"pinned-note": "Nota fijada",
|
"pinned-note": "Nota fijada",
|
||||||
|
"documentation": "Documentación",
|
||||||
"item-sheet": "Objeto",
|
"item-sheet": "Objeto",
|
||||||
"icon-source": "Elegir icono",
|
"icon-source": "Elegir icono",
|
||||||
"foundry-icons": "Iconos de Foundry"
|
"foundry-icons": "Iconos de Foundry"
|
||||||
|
|||||||
@@ -3,8 +3,10 @@
|
|||||||
// numbered group, translations for the group's label, and no link pointing at a page that does not
|
// 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
|
// 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
|
// 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
|
// 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.
|
// 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
|
// `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
|
// 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
|
// Inside a campaign the documentation is reached from the top bar, on the left of the campaign
|
||||||
// settings button (Syndria98/dragonroll#90).
|
// settings button (Syndria98/dragonroll#90), and it opens as a window of its own in front of the
|
||||||
test("the campaign top bar points at the documentation", () => {
|
// 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 topBar = readRepoFile("frontend", "app", "components", "viewer", "TopBar.vue");
|
||||||
const right = /<div class="right">([\s\S]*?)<\/div>/.exec(topBar)?.[1];
|
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.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(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.
|
// come first in it.
|
||||||
const docsAt = right.indexOf('href="/docs"');
|
const docsAt = right.indexOf("OpenDocumentation");
|
||||||
const settingsAt = right.indexOf("OpenCampaignSettings");
|
const settingsAt = right.indexOf("OpenCampaignSettings");
|
||||||
assert.ok(
|
assert.ok(
|
||||||
docsAt !== -1 && settingsAt !== -1 && docsAt < settingsAt,
|
docsAt !== -1 && settingsAt !== -1 && docsAt < settingsAt,
|
||||||
"the documentation button sits on the left of the settings button"
|
"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
|
// The open notes of the campaign live only in memory, so nothing the top bar does may leave
|
||||||
// opens it somewhere that does not throw the campaign away.
|
// the app: a window comes to the front, an address would take the campaign away with it.
|
||||||
assert.match(right, /target="_blank"/, "the campaign stays as it was behind the documentation");
|
assert.doesNotMatch(topBar, /href="\/docs"/, "the top bar does not send the campaign to /docs");
|
||||||
assert.match(right, /rel="[^"]*noopener/, "a tab the app does not control must not be able to reach it");
|
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
|
// The window the button opens (Syndria98/dragonroll#95): registered like every other window, and
|
||||||
// theme colours like everything else.
|
// reading its pages without ever leaving the window it is drawn in.
|
||||||
const look = /\.docs-button\s*\{[^}]*\}/.exec(topBar)?.[0];
|
test("the documentation is registered as a window", () => {
|
||||||
assert.ok(look, "the documentation link has to look like the buttons next to it");
|
const definitions = readRepoFile("frontend", "app", "services", "WindowDefinitions.js");
|
||||||
for (const declaration of [
|
const definition = /\n\s*documentation:\s*\{([\s\S]*?)\n\s{2}\}/.exec(definitions);
|
||||||
"background-color: var\\(--color-button-background\\)",
|
assert.ok(definition, "the documentation is not registered as a window");
|
||||||
"color: var\\(--color-text\\)",
|
|
||||||
"border: solid 1px var\\(--color-border\\)",
|
assert.match(definition[1], /title:\s*'windows\.documentation'/, "its title is an i18n key");
|
||||||
]) {
|
assert.match(definition[1], /movable:\s*true/);
|
||||||
assert.match(look, new RegExp(declaration), "the link's look uses the theme's colours");
|
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 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