refactoring and tests

website/src/lib/components/docs/docs.ts

@@ -16,27 +16,6 @@ import {
 } from '@lucide/svelte';
 import type { Component } from 'svelte';
 
-export const guides: Record<string, string[]> = {
-    'getting-started': [],
-    menu: ['file', 'edit', 'view', 'settings'],
-    'files-and-stats': [],
-    toolbar: [
-        'routing',
-        'poi',
-        'scissors',
-        'time',
-        'merge',
-        'extract',
-        'elevation',
-        'minify',
-        'clean',
-    ],
-    'map-controls': [],
-    gpx: [],
-    integration: [],
-    faq: [],
-};
-
 export const guideIcons: Record<string, string | Component<IconProps>> = {
     'getting-started': '🚀',
     menu: '📂 ⚙️',
@@ -61,64 +40,4 @@ export const guideIcons: Record<string, string | Component<IconProps>> = {
     faq: '🔮',
 };
 
-export function getPreviousGuide(currentGuide: string): string | undefined {
-    let subguides = currentGuide.split('/');
-
-    if (subguides.length === 1) {
-        let keys = Object.keys(guides);
-        let index = keys.indexOf(currentGuide);
-        if (index === 0) {
-            return undefined;
-        }
-        let previousGuide = keys[index - 1];
-        if (previousGuide === undefined) {
-            return undefined;
-        } else if (guides[previousGuide].length === 0) {
-            return previousGuide;
-        } else {
-            return `${previousGuide}/${guides[previousGuide][guides[previousGuide].length - 1]}`;
-        }
-    } else {
-        if (guides.hasOwnProperty(subguides[0])) {
-            let subguideIndex = guides[subguides[0]].indexOf(subguides[1]);
-            if (subguideIndex > 0) {
-                return `${subguides[0]}/${guides[subguides[0]][subguideIndex - 1]}`;
-            } else {
-                return subguides[0];
-            }
-        } else {
-            return undefined;
-        }
-    }
-}
-
-export function getNextGuide(currentGuide: string): string | undefined {
-    let subguides = currentGuide.split('/');
-
-    if (subguides.length === 1) {
-        if (guides.hasOwnProperty(currentGuide)) {
-            if (guides[currentGuide].length === 0) {
-                let keys = Object.keys(guides);
-                let index = keys.indexOf(currentGuide);
-                return keys[index + 1];
-            } else {
-                return `${currentGuide}/${guides[currentGuide][0]}`;
-            }
-        } else {
-            return undefined;
-        }
-    } else {
-        if (guides.hasOwnProperty(subguides[0])) {
-            let subguideIndex = guides[subguides[0]].indexOf(subguides[1]);
-            if (subguideIndex < guides[subguides[0]].length - 1) {
-                return `${subguides[0]}/${guides[subguides[0]][subguideIndex + 1]}`;
-            } else {
-                let keys = Object.keys(guides);
-                let index = keys.indexOf(subguides[0]);
-                return keys[index + 1];
-            }
-        } else {
-            return undefined;
-        }
-    }
-}
+export { guides, getNextGuide, getPreviousGuide } from './guides';

website/src/lib/components/docs/guides.test.ts

@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { describe, it } from 'node:test';
+import { languages } from '$lib/languages';
+import { getNextGuide, getPreviousGuide, guides } from './guides';
+
+/** Every page of the help in reading order, as the links at the bottom of the pages follow them. */
+const pages = Object.entries(guides).flatMap(([guide, subguides]) => [
+    guide,
+    ...subguides.map((subguide) => `${guide}/${subguide}`),
+]);
+
+describe('guides', () => {
+    it('go from one page to the next, subguides included', () => {
+        assert.equal(getNextGuide('getting-started'), 'menu');
+        assert.equal(getNextGuide('menu'), 'menu/file');
+        assert.equal(getNextGuide('menu/file'), 'menu/edit');
+        assert.equal(getNextGuide('menu/settings'), 'files-and-stats');
+        assert.equal(getNextGuide('toolbar/clean'), 'map-controls');
+        assert.equal(getNextGuide('integration'), 'faq');
+    });
+
+    it('go from one page to the previous one, subguides included', () => {
+        assert.equal(getPreviousGuide('menu'), 'getting-started');
+        assert.equal(getPreviousGuide('menu/file'), 'menu');
+        assert.equal(getPreviousGuide('menu/edit'), 'menu/file');
+        assert.equal(getPreviousGuide('files-and-stats'), 'menu/settings');
+        assert.equal(getPreviousGuide('map-controls'), 'toolbar/clean');
+        assert.equal(getPreviousGuide('faq'), 'integration');
+    });
+
+    it('stop at the ends', () => {
+        assert.equal(getPreviousGuide('getting-started'), undefined);
+        assert.equal(getNextGuide('faq'), undefined);
+    });
+
+    it('know nothing of pages that do not exist', () => {
+        assert.equal(getNextGuide('nope'), undefined);
+        assert.equal(getNextGuide('nope/sub'), undefined);
+        assert.equal(getPreviousGuide('nope'), undefined);
+        assert.equal(getPreviousGuide('nope/sub'), undefined);
+    });
+
+    it('walk through every page in both directions', () => {
+        const forward = [pages[0]];
+        for (let next = getNextGuide(pages[0]); next; next = getNextGuide(next)) {
+            forward.push(next);
+        }
+        assert.deepEqual(forward, pages);
+
+        const backward = [pages.at(-1)!];
+        for (
+            let previous = getPreviousGuide(pages.at(-1)!);
+            previous;
+            previous = getPreviousGuide(previous)
+        ) {
+            backward.push(previous);
+        }
+        assert.deepEqual(backward.reverse(), pages);
+    });
+
+    it('are written in every language of the site', () => {
+        const root = new URL('../../docs/', import.meta.url);
+        const missing: string[] = [];
+        for (const language of Object.keys(languages)) {
+            for (const page of pages) {
+                if (!existsSync(new URL(`${language}/${page}.mdx`, root))) {
+                    missing.push(`${language}/${page}`);
+                }
+            }
+        }
+        assert.deepEqual(missing, []);
+    });
+
+    it('have a translation of the interface for every language of the site', () => {
+        const root = new URL('../../../locales/', import.meta.url);
+        for (const language of Object.keys(languages)) {
+            assert.ok(existsSync(new URL(`${language}.json`, root)), language);
+        }
+    });
+});

website/src/lib/components/docs/guides.ts

@@ -0,0 +1,84 @@
+// The guides of the help section, and how they follow one another. The icons are in `docs.ts`.
+
+export const guides: Record<string, string[]> = {
+    'getting-started': [],
+    menu: ['file', 'edit', 'view', 'settings'],
+    'files-and-stats': [],
+    toolbar: [
+        'routing',
+        'poi',
+        'scissors',
+        'time',
+        'merge',
+        'extract',
+        'elevation',
+        'minify',
+        'clean',
+    ],
+    'map-controls': [],
+    gpx: [],
+    integration: [],
+    faq: [],
+};
+
+export function getPreviousGuide(currentGuide: string): string | undefined {
+    const subguides = currentGuide.split('/');
+
+    if (subguides.length === 1) {
+        const keys = Object.keys(guides);
+        const index = keys.indexOf(currentGuide);
+        if (index === 0) {
+            return undefined;
+        }
+        const previousGuide = keys[index - 1];
+        if (previousGuide === undefined) {
+            return undefined;
+        } else if (guides[previousGuide].length === 0) {
+            return previousGuide;
+        } else {
+            return `${previousGuide}/${guides[previousGuide][guides[previousGuide].length - 1]}`;
+        }
+    } else {
+        if (guides.hasOwnProperty(subguides[0])) {
+            const subguideIndex = guides[subguides[0]].indexOf(subguides[1]);
+            if (subguideIndex > 0) {
+                return `${subguides[0]}/${guides[subguides[0]][subguideIndex - 1]}`;
+            } else {
+                return subguides[0];
+            }
+        } else {
+            return undefined;
+        }
+    }
+}
+
+export function getNextGuide(currentGuide: string): string | undefined {
+    const subguides = currentGuide.split('/');
+
+    if (subguides.length === 1) {
+        if (guides.hasOwnProperty(currentGuide)) {
+            if (guides[currentGuide].length === 0) {
+                const keys = Object.keys(guides);
+                const index = keys.indexOf(currentGuide);
+                return keys[index + 1];
+            } else {
+                return `${currentGuide}/${guides[currentGuide][0]}`;
+            }
+        } else {
+            return undefined;
+        }
+    } else {
+        if (guides.hasOwnProperty(subguides[0])) {
+            const subguideIndex = guides[subguides[0]].indexOf(subguides[1]);
+            if (subguideIndex < guides[subguides[0]].length - 1) {
+                return `${subguides[0]}/${guides[subguides[0]][subguideIndex + 1]}`;
+            } else {
+                const keys = Object.keys(guides);
+                const index = keys.indexOf(subguides[0]);
+                return keys[index + 1];
+            }
+        } else {
+            return undefined;
+        }
+    }
+}