Skip to content

Build your personal knowledge base with Trilium Notes

10.8 KB
Raw Blame
import type { HelpMetaItem } from "@triliumnext/commons";
import type { NoteMeta, NoteMetaFile } from "@triliumnext/core";
import { describe, expect, it } from "vitest";

import { buildHelpMeta, serializeHelpMeta, stripAppVersion } from "./help_meta_generator.js";

const BASE_URL = "https://docs.triliumnotes.org";

/** Wraps the given notes in a "User Guide" export root, mirroring the real markdown export. */
function metaFileOf(children: NoteMeta[], rootAttributes: NoteMeta["attributes"] = []): { formatVersion: number; appVersion: string; files: NoteMeta[] } {
    const root: NoteMeta = {
        isClone: false, noteId: "root", notePath: ["root"], title: "User Guide",
        notePosition: 1, prefix: null, isExpanded: false, type: "text", mime: "text/html",
        attributes: rootAttributes, format: "markdown", attachments: [],
        dataFileName: "User Guide.md", dirFileName: "User Guide", children
    };
    return { formatVersion: 2, appVersion: "0.103.0", files: [root] };
}

const labelOf = (item: HelpMetaItem | undefined, name: string) =>
    item?.attributes?.find((a) => a.name === name)?.value;

describe("buildHelpMeta", () => {
    it("resolves structure, icons and content sources", () => {
        const page: NoteMeta = {
            isClone: false, noteId: "text1", title: "Text", type: "text", mime: "text/html",
            attributes: [{ type: "label", name: "iconClass", value: "bx bx-star", isInheritable: false, position: 10 }],
            format: "markdown", dataFileName: "Text.md", children: []
        };
        const folder: NoteMeta = {
            isClone: false, noteId: "types", title: "Note Types", type: "text", mime: "text/html",
            attributes: [], format: "markdown", dirFileName: "Note Types", children: [page]
        };

        const { meta: items, sources } = buildHelpMeta(metaFileOf([folder]));
        const folderItem = items[0];
        const pageItem = folderItem?.children?.[0];

        // A note with no data file of its own is a folder: no source, but a directory, which is
        // the only path other pages can link to it by.
        expect(folderItem?.id).toBe("_help_types");
        expect(folderItem?.type).toBe("book");
        expect(sources._help_types?.source).toBeUndefined();
        expect(sources._help_types?.dir).toBe("User Guide/Note Types");
        expect(labelOf(folderItem, "iconClass")).toBe("bx bx-folder");

        // Sources are relative to the export directory, which already is the root note's folder,
        // so the root contributes exactly one path segment.
        expect(pageItem?.id).toBe("_help_text1");
        expect(pageItem?.type).toBe("text");
        expect(sources._help_text1?.source).toBe("User Guide/Note Types/Text.md");
        expect(labelOf(pageItem, "iconClass")).toBe("bx bx-star");
    });

    it("resolves a clone's icon and source to the primary occurrence", () => {
        // The same note is placed under two folders: a primary occurrence (isClone:false) carrying
        // a custom icon and the real file, and a clone (isClone:true) with no attributes and a
        // ".clone" data file. Both are the same note, so both must describe it identically —
        // otherwise the clone would point at a file that only exists to satisfy the export.
        const primary: NoteMeta = {
            isClone: false, noteId: "nix", title: "Nix flake", type: "text", mime: "text/html",
            attributes: [{ type: "label", name: "iconClass", value: "bx bxl-tux", isInheritable: false, position: 10 }],
            format: "markdown", dataFileName: "Nix flake.md", children: []
        };
        const clone: NoteMeta = {
            isClone: true, noteId: "nix", title: "Nix flake", type: "text", mime: "text/html",
            format: "markdown", dataFileName: "Nix flake.clone.md", children: []
        };
        const desktop: NoteMeta = {
            isClone: false, noteId: "desktop", title: "Desktop Installation", type: "text", mime: "text/html",
            attributes: [], format: "markdown", dirFileName: "Desktop Installation", children: [primary]
        };
        const server: NoteMeta = {
            isClone: false, noteId: "server", title: "Server Installation", type: "text", mime: "text/html",
            attributes: [], format: "markdown", dirFileName: "Server Installation", children: [clone]
        };

        const { meta: items, sources } = buildHelpMeta(metaFileOf([desktop, server]));
        const primaryItem = items.find((i) => i.id === "_help_desktop")?.children?.[0];
        const cloneItem = items.find((i) => i.id === "_help_server")?.children?.[0];

        expect(primaryItem?.id).toBe("_help_nix");
        expect(cloneItem?.id).toBe("_help_nix");
        expect(labelOf(cloneItem, "iconClass")).toBe("bx bxl-tux");
        // Both occurrences are the one note, so they leave one source between them — the primary's
        // file rather than the ".clone" copy the export wrote beside it.
        expect(sources._help_nix?.source).toBe("User Guide/Desktop Installation/Nix flake.md");
    });

    it("derives docUrl from the share alias chain, and only when a base URL is given", () => {
        const page: NoteMeta = {
            isClone: false, noteId: "highlights", title: "Feature Highlights", type: "text", mime: "text/html",
            attributes: [{ type: "label", name: "shareAlias", value: "feature-highlights", isInheritable: false, position: 10 }],
            format: "markdown", dataFileName: "Feature Highlights.md", children: []
        };
        const rootAlias: NoteMeta["attributes"] = [
            { type: "label", name: "shareAlias", value: "user-guide", isInheritable: false, position: 10 }
        ];

        const { meta: withBase } = buildHelpMeta(metaFileOf([page], rootAlias), BASE_URL);
        expect(labelOf(withBase[0], "docUrl")).toBe("https://docs.triliumnotes.org/user-guide/feature-highlights");

        const { meta: withoutBase } = buildHelpMeta(metaFileOf([page], rootAlias));
        expect(labelOf(withoutBase[0], "docUrl")).toBeUndefined();
    });

    it("keeps web views pointing at the online docs and gives them no source", () => {
        const embedded: NoteMeta = {
            isClone: false, noteId: "embedded", title: "Embedded", type: "webView", mime: "",
            attributes: [{ type: "label", name: "webViewSrc", value: "/user-guide/embedded", isInheritable: false, position: 10 }],
            format: "markdown", dataFileName: "Embedded.md", children: []
        };

        const { meta: items, sources } = buildHelpMeta(metaFileOf([embedded]), BASE_URL);

        expect(items[0]?.type).toBe("webView");
        expect(sources._help_embedded?.source).toBeUndefined();
        // Root-relative sources are stored that way in the notes; the docs origin is applied here.
        expect(labelOf(items[0], "webViewSrc")).toBe("https://docs.triliumnotes.org/user-guide/embedded");
    });

    it("keeps the full content width of a page", () => {
        const page = (noteId: string, attributes: NoteMeta["attributes"]): NoteMeta => ({
            isClone: false, noteId, title: noteId, type: "text", mime: "text/html",
            attributes, format: "markdown", dataFileName: `${noteId}.md`, children: []
        });
        const wide = page("wide", [{ type: "label", name: "fullContentWidth", value: "", isInheritable: false, position: 10 }]);
        const narrow = page("narrow", []);

        const { meta: items } = buildHelpMeta(metaFileOf([ wide, narrow ]));

        expect(items[0]?.attributes?.find((a) => a.name === "fullContentWidth")).toBeDefined();
        expect(items[1]?.attributes?.find((a) => a.name === "fullContentWidth")).toBeUndefined();
    });

    it("keeps the mime of code notes so their content is not treated as markdown", () => {
        const script: NoteMeta = {
            isClone: false, noteId: "script", title: "Example", type: "code", mime: "application/javascript;env=backend",
            attributes: [], format: "markdown", dataFileName: "Example.js", children: []
        };

        const { meta: items, sources } = buildHelpMeta(metaFileOf([script]));

        expect(items[0]?.type).toBe("code");
        expect(items[0]?.mime).toBe("application/javascript;env=backend");
        expect(sources._help_script?.source).toBe("User Guide/Example.js");
    });

    it("hides notes that are hidden from the share tree", () => {
        const hidden: NoteMeta = {
            isClone: false, noteId: "hidden", title: "Features", type: "text", mime: "text/html",
            attributes: [{ type: "label", name: "shareHiddenFromTree", value: "", isInheritable: false, position: 10 }],
            format: "markdown", dirFileName: "Features", children: []
        };

        expect(buildHelpMeta(metaFileOf([hidden])).meta).toHaveLength(0);
    });

    it("returns nothing when the export has no files", () => {
        expect(buildHelpMeta({ formatVersion: 2, appVersion: "0.103.0", files: undefined as never }))
            .toEqual({ meta: [], sources: {} });
    });
});

describe("stripAppVersion", () => {
    it("drops the version stamp and keeps everything else the docs metadata carries", () => {
        const meta = {
            formatVersion: 2,
            appVersion: "0.105.0",
            files: [{ noteId: "abc", title: "Note", attributes: [] }]
        } as unknown as NoteMetaFile;

        const stripped = stripAppVersion(meta);

        expect("appVersion" in stripped).toBe(false);
        expect(stripped).toStrictEqual({ formatVersion: 2, files: meta.files });
        // The input is left alone: the help tree is derived from the same object afterwards.
        expect(meta.appVersion).toBe("0.105.0");
    });
});

describe("serializeHelpMeta", () => {
    it("writes each note on a line of its own and parses back to the same tree", () => {
        const tree: HelpMetaItem[] = [
            {
                id: "_help_a",
                title: "Folder",
                type: "book",
                attributes: [ { type: "label", name: "iconClass", value: "bx" } ],
                children: [
                    { id: "_help_b", title: "Page", type: "text" },
                    { id: "_help_c", title: "Script", type: "code", mime: "text/x", children: [] }
                ]
            },
            { id: "_help_d", title: "Web view", type: "webView" }
        ];

        const json = serializeHelpMeta(tree);

        expect(JSON.parse(json)).toStrictEqual(tree);
        expect(json.split("\n")).toStrictEqual([
            "[",
            `    {"id":"_help_a","title":"Folder","type":"book",` +
                `"attributes":[{"type":"label","name":"iconClass","value":"bx"}],"children":[`,
            `        {"id":"_help_b","title":"Page","type":"text"},`,
            `        {"id":"_help_c","title":"Script","type":"code","mime":"text/x","children":[]}`,
            "    ]},",
            `    {"id":"_help_d","title":"Web view","type":"webView"}`,
            "]"
        ]);
        expect(serializeHelpMeta([])).toBe("[]");
    });
});