Skip to content

Build your personal knowledge base with Trilium Notes

124 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

import appContext from "../../../components/app_context";
import type NoteContext from "../../../components/note_context";
import FAttribute from "../../../entities/fattribute";
import type FBranch from "../../../entities/fbranch";
import branches from "../../../services/branches";
import attributes from "../../../services/attributes";
import { executeBulkActions } from "../../../services/bulk_action";
import dialog from "../../../services/dialog";
import toast from "../../../services/toast";
import FNote from "../../../entities/fnote";
import froca from "../../../services/froca";
import note_create from "../../../services/note_create";
import noteAttributeCache from "../../../services/note_attribute_cache";
import server from "../../../services/server";
import ws from "../../../services/ws";
import { buildNote } from "../../../test/easy-froca";
import { BoardViewData } from ".";
import BoardApi, { getPendingWrites, PendingColumnWrites } from "./api";
import { ColumnItem, ColumnMap } from "./data";
import {
    BOARD_TEMPLATE_ID, DEFAULT_CARD_TEMPLATES, DEFAULT_COLUMN_ICON, getStatusDefinition, INBOX_COLUMN
} from "./columns";
import { COLUMN_ID_LENGTH } from "./reference";

vi.mock("../../../services/bulk_action", () => ({
    executeBulkActions: vi.fn(async () => {})
}));

/** Makes the next bulk action fail, as an offline or rejecting server does. */
function failNextBulkAction() {
    vi.mocked(executeBulkActions).mockRejectedValueOnce(new Error("offline"));
}

/** The same for a column rename, which the server makes in one write of its own. */
function failNextRename() {
    vi.spyOn(server, "put").mockRejectedValueOnce(new Error("offline"));
}

/** Holds the next rename open, answering it only once the returned function is called. */
function holdNextRename() {
    let release = () => {};
    vi.spyOn(server, "put").mockImplementationOnce(
        () => new Promise<void>((resolve) => { release = resolve; }));
    return () => release();
}

vi.mock("../../../services/branches", () => ({
    default: {
        cloneNoteToParentNote: vi.fn(async () => {}),
        moveBeforeBranch: vi.fn(async () => {}),
        moveAfterBranch: vi.fn(async () => {})
    }
}));

vi.mock("../../../services/note_create", () => ({
    default: { createNote: vi.fn(async () => ({ note: null, branch: null })) }
}));

vi.mock("../../../services/dialog", () => ({
    default: {
        confirm: vi.fn(async () => true),
        confirmWithNoteDeletion: vi.fn(async () => ({
            confirmed: true,
            isDeleteNoteChecked: false
        }))
    }
}));

vi.mock("../../../services/i18n", () => ({
    // i18next is never initialised under test, so the real `t` yields nothing and the alias would
    // silently vanish from the definitions asserted below rather than being checked.
    t: (key: string) => (key === "board_view.status-alias" ? "Status" : key)
}));

function createApi(
    viewConfig: BoardViewData,
    columns: string[],
    parentNote?: FNote,
    statusAttribute = "status",
    byColumn: ColumnMap = new Map(),
    allByColumn?: ColumnMap,
    keepNote?: (noteId: string) => void
) {
    const board = parentNote ?? buildNote({ title: "Board" });
    const saved: BoardViewData[] = [];
    const editing: (string | undefined)[] = [];
    const pending: PendingColumnWrites =
        { renames: new Map(), claims: new Map(), inFlight: 0 };
    const api = new BoardApi(
        byColumn,
        columns,
        board,
        statusAttribute,
        viewConfig,
        (newConfig) => saved.push(newConfig),
        (branchId) => editing.push(branchId),
        pending,
        getStatusDefinition(board, statusAttribute),
        allByColumn,
        keepNote
    );
    return { api, board, saved, editing, pending, pendingRenames: pending.renames };
}

/** Cards named by their note id, which is all the operations under test read them for. */
function cards(columns: Record<string, string[]>): ColumnMap {
    return new Map(Object.entries(columns).map(([ column, ids ]) => [
        column,
        ids.map((noteId) => ({ note: { noteId }, branch: { branchId: `b_${noteId}` } }))
    ])) as unknown as ColumnMap;
}

describe("BoardApi filtering", () => {
    it("stores a submitted filter query and clears it for an empty one", () => {
        const { api, saved } = createApi({ filterQuery: undefined }, []);

        api.setFilterQuery("#done");
        expect(saved.at(-1)?.filterQuery).toBe("#done");

        api.setFilterQuery("#done");
        expect(saved).toHaveLength(1);

        api.setFilterQuery("");
        expect(saved).toHaveLength(2);
        expect(saved.at(-1)?.filterQuery).toBeUndefined();
    });

    it("does not save for a cleared filter that was never set", () => {
        const { api, saved } = createApi({}, []);

        api.setFilterQuery("");
        expect(saved).toHaveLength(0);
    });

    it("removes a column's value from the cards the filter is not showing too", async () => {
        const { api } = createApi(
            { columns: [ { value: "To Do" } ] },
            [ "To Do" ],
            undefined,
            "status",
            cards({ "To Do": [ "visible" ] }),
            cards({ "To Do": [ "visible", "hidden" ] })
        );

        await api.removeColumn("To Do");

        expect(executeBulkActions).toHaveBeenCalledWith(
            [ "visible", "hidden" ],
            [ { name: "deleteLabel", labelName: "status" } ],
            { silent: true }
        );
    });
});

describe("BoardApi column mutations", () => {
    /**
     * #10689: the view re-renders off the identity of the config object it is handed
     * (`useEffect(refresh, [ …, viewConfig ])`). A mutator that edits the config in place and saves
     * the same reference persists the change but never redraws the board.
     */
    it("hands the caller a new config object rather than mutating in place", async () => {
        const viewConfig: BoardViewData = { columns: [ { value: "To Do" }, { value: "Done" } ] };
        const { api, saved } = createApi(viewConfig, [ "To Do", "Done" ]);

        await api.addNewColumn("In Progress");
        await api.removeColumn("To Do");

        expect(saved).toHaveLength(2);
        for (const config of saved) {
            expect(config).not.toBe(viewConfig);
            expect(config.columns).not.toBe(viewConfig.columns);
        }
        expect(saved.map(config => config.columns?.map(col => col.value))).toEqual([
            [ "To Do", "Done", "In Progress" ],
            [ "Done", "In Progress" ]
        ]);
    });

    it("does not save anything for a duplicate column", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);
        expect(await api.addNewColumn("To Do")).toBe(false);
        expect(saved).toHaveLength(0);
    });

    it("puts a new column on either side of the one it is given", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );

        expect(await api.insertColumn("To Do", "after")).toBe("board_view.new-column");
        expect(saved.at(-1)?.columns?.map(col => col.value))
            .toEqual([ "To Do", "board_view.new-column", "Done" ]);

        // The second is placed against the config just written, not the list the view still shows.
        expect(await api.insertColumn("Done", "before")).toBe("board_view.new-column 2");
        expect(saved.at(-1)?.columns?.map(col => col.value)).toEqual([
            "To Do", "board_view.new-column", "board_view.new-column 2", "Done"
        ]);
    });

    it("keeps the icon of a column it puts one beside", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-list-ul", color: "#e64d4d" } ] },
            [ "To Do" ]
        );

        await api.insertColumn("To Do", "before");

        expect(saved.at(-1)?.columns)
            .toEqual([
                { value: "board_view.new-column", id: expect.any(String) },
                { value: "To Do", icon: "bx bx-list-ul", color: "#e64d4d" }
            ]);
    });

    it("keeps the icon of every column it reorders", () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-list-ul" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );

        api.reorderColumn(0, 2);

        expect(saved.at(-1)?.columns)
            .toEqual([ { value: "Done" }, { value: "To Do", icon: "bx bx-list-ul" } ]);
    });

    it("stores an icon, creating the entry a resolved column may not have yet", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do", "Done" ]);

        await api.setColumnIcon("To Do", "bx bx-list-ul");
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", icon: "bx bx-list-ul" } ]);

        // "Done" is resolved from the definition, so nothing has written it down yet.
        await api.setColumnIcon("Done", "bx bx-check");
        expect(saved.at(-1)?.columns).toEqual([
            { value: "To Do", icon: "bx bx-list-ul" },
            { value: "Done", icon: "bx bx-check" }
        ]);
    });

    it("clears the icon back to the default rather than storing an empty one", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-list-ul" } ] }, [ "To Do" ]);

        await api.setColumnIcon("To Do", undefined);

        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do" } ]);
    });

    it("reads back the icon a column carries, falling back to the default", async () => {
        const { api } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-list-ul" }, { value: "Done" } ] },
            [ "To Do", "Done", "Backlog" ]);

        expect(api.getColumnIcon("To Do")).toBe("bx bx-list-ul");
        expect(api.getColumnIcon("Done")).toBe(DEFAULT_COLUMN_ICON);
        // Resolved from the definition, so it has no stored entry at all.
        expect(api.getColumnIcon("Backlog")).toBe(DEFAULT_COLUMN_ICON);
    });

    it("reads a relation column's icon off the note the column is", async () => {
        const column = buildNote({ title: "Done", "#iconClass": "bx bx-check" });
        const { api } = createApi({ columns: [] }, [ column.noteId ], undefined, "~status");

        expect(api.getColumnIcon(column.noteId)).toContain("bx bx-check");
    });

    it("reads back the colour a column carries as the classes that tint with it", async () => {
        const { api } = createApi(
            { columns: [ { value: "To Do", color: "#e64d4d" }, { value: "Done" } ] },
            [ "To Do", "Done" ]);

        expect(api.getColumnColorClass("To Do")).toContain("use-note-color");
        expect(api.getColumnColorClass("Done")).toBe("");
    });

    it("stores a colour beside the icon, without either clearing the other", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        await api.setColumnIcon("To Do", "bx bx-list-ul");
        await api.setColumnColor("To Do", "#e64d4d");
        expect(saved.at(-1)?.columns).toEqual([
            { value: "To Do", icon: "bx bx-list-ul", color: "#e64d4d" }
        ]);

        // Clearing one leaves the other where it is.
        await api.setColumnColor("To Do", null);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", icon: "bx bx-list-ul" } ]);
    });

    it("archives a column and brings it back, storing nothing once it is not", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-list-ul" } ] }, [ "To Do" ]);

        await api.setColumnArchived("To Do", true);
        expect(saved.at(-1)?.columns).toEqual([
            { value: "To Do", icon: "bx bx-list-ul", archived: true }
        ]);

        await api.setColumnArchived("To Do", false);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", icon: "bx bx-list-ul" } ]);
    });

    /**
     * What the column is drawn with is kept by the server, which renames it in the stored columns
     * as well as in the cards and the definition. Checked there; asked for here.
     */
    it("asks the server to rename the column, rather than writing each place itself", async () => {
        const put = vi.spyOn(server, "put").mockResolvedValue(undefined);
        const { api, saved } = createApi(
            { columns: [ { value: "Done", icon: "bx bx-check" } ] }, [ "Done" ]);
        // Cleared: the mock outlives the test that first stood it up, and its calls with it.
        vi.mocked(executeBulkActions).mockClear();

        await api.renameColumn("Done", "Shipped");

        expect(put).toHaveBeenCalledWith(expect.stringMatching(/board\/rename-column$/), {
            attribute: "status", isRelation: false, oldValue: "Done", newValue: "Shipped"
        });
        expect(saved).toEqual([]);
        expect(executeBulkActions).not.toHaveBeenCalled();
    });

    it("records what each column it renames away or deletes became", async () => {
        const { api, pendingRenames } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );

        await api.renameColumn("Done", "Shipped");
        expect([ ...pendingRenames ]).toEqual([ [ "Done", "Shipped" ] ]);

        await api.removeColumn("To Do");
        expect([ ...pendingRenames ]).toEqual([ [ "Done", "Shipped" ], [ "To Do", undefined ] ]);

        // A name is only held back while its removal is still landing, never against a column the
        // user deliberately creates under it again.
        await api.addNewColumn("To Do");
        expect([ ...pendingRenames ]).toEqual([ [ "Done", "Shipped" ] ]);
    });

    /**
     * A record left behind by a write that never landed goes on being applied: the column would
     * show under a name nothing carries, or stay hidden though it is still there.
     */
    it("keeps no record of a rename or a deletion the server refused", async () => {
        const { api, saved, pendingRenames } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );

        failNextRename();
        await expect(api.renameColumn("Done", "Shipped")).rejects.toThrow("offline");

        failNextBulkAction();
        await expect(api.removeColumn("To Do")).rejects.toThrow("offline");

        expect([ ...pendingRenames ]).toEqual([]);
        expect(saved).toHaveLength(0);
    });

    it("restores the record of an earlier rename when a later one is refused", async () => {
        const { api, pendingRenames } = createApi({ columns: [ { value: "Done" } ] }, [ "Done" ]);

        await api.renameColumn("Done", "Shipped");

        // The refused rename re-pointed the first one on its way in, which has to be put back.
        failNextRename();
        await expect(api.renameColumn("Shipped", "Delivered")).rejects.toThrow("offline");

        expect([ ...pendingRenames ]).toEqual([ [ "Done", "Shipped" ] ]);
    });

    /**
     * Two mutations can be in flight at once, so an undo has to take back what its own call did and
     * nothing else: the record of a mutation still running, or one that has already failed, is not
     * this one's to put back.
     */
    it("takes back only its own record when overlapping mutations fail", async () => {
        const { api, pendingRenames } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );

        // Both start before either finishes, and both are refused.
        failNextRename();
        failNextBulkAction();
        const first = api.renameColumn("Done", "Shipped");
        const second = api.removeColumn("To Do");

        await expect(first).rejects.toThrow("offline");
        await expect(second).rejects.toThrow("offline");
        expect([ ...pendingRenames ]).toEqual([]);
    });

    it("leaves a mutation still in flight alone when another one fails", async () => {
        const { api, pendingRenames } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );

        let releaseSecond = () => {};
        const second = new Promise<void>((resolve) => { releaseSecond = resolve; });
        failNextRename();
        vi.mocked(executeBulkActions).mockImplementationOnce(() => second);

        const failing = api.renameColumn("Done", "Shipped");
        const running = api.removeColumn("To Do");

        await expect(failing).rejects.toThrow("offline");
        // The deletion is still going; its record must have survived the other one's undo.
        expect([ ...pendingRenames ]).toEqual([ [ "To Do", undefined ] ]);

        releaseSecond();
        await running;
    });

    /**
     * The later rename re-points the record the earlier one left, taking the key over. An undo that
     * reverted it anyway would strip a rename still running of the record it needs.
     */
    it("leaves a key a later rename has taken over alone when the earlier one fails", async () => {
        const { api, pendingRenames } = createApi({ columns: [ { value: "Done" } ] }, [ "Done" ]);

        let releaseSecond = () => {};
        failNextRename();
        releaseSecond = holdNextRename();

        const failing = api.renameColumn("Done", "Shipped");
        const running = api.renameColumn("Shipped", "Delivered");

        await expect(failing).rejects.toThrow("offline");
        expect([ ...pendingRenames ])
            .toEqual([ [ "Done", "Delivered" ], [ "Shipped", "Delivered" ] ]);

        releaseSecond();
        await running;
    });

    /**
     * Both writes ask for the same thing and both fail, the earlier one first. Its undo rightly
     * leaves the record alone, the later write still having it; the later undo must then take the
     * record away rather than put back what the earlier one left, which nothing is going to answer
     * for any more.
     */
    it("leaves no record behind when two identical writes both fail", async () => {
        const { api, pendingRenames } = createApi({ columns: [ { value: "Done" } ] }, [ "Done" ]);

        let failSecond = (_: Error) => {};
        failNextRename();
        vi.spyOn(server, "put").mockImplementationOnce(
            () => new Promise<void>((_, reject) => { failSecond = reject; }));

        const first = api.renameColumn("Done", "Shipped");
        const second = api.renameColumn("Done", "Shipped");

        await expect(first).rejects.toThrow("offline");
        expect([ ...pendingRenames ]).toEqual([ [ "Done", "Shipped" ] ]);

        failSecond(new Error("offline"));
        await expect(second).rejects.toThrow("offline");

        // Neither rename landed, so the board has to read the column as it stands.
        expect([ ...pendingRenames ]).toEqual([]);
    });

    /**
     * Two writes can ask for exactly the same thing, and what they leave behind is then the same
     * record. Only the owner tells them apart, so the one that fails cannot take back the other's.
     */
    it("leaves an identical record made by another write alone when one fails", async () => {
        const { api, pendingRenames } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );

        let releaseSecond = () => {};
        const second = new Promise<void>((resolve) => { releaseSecond = resolve; });
        vi.mocked(executeBulkActions).mockRejectedValueOnce(new Error("offline"));
        vi.mocked(executeBulkActions).mockImplementationOnce(() => second);

        // The same column, deleted twice over before either has answered.
        const failing = api.removeColumn("Done");
        const running = api.removeColumn("Done");

        await expect(failing).rejects.toThrow("offline");
        expect([ ...pendingRenames ]).toEqual([ [ "Done", undefined ] ]);

        releaseSecond();
        await running;
    });

    it("follows a rename through when the one before it has not landed yet", async () => {
        const { api, pendingRenames } = createApi({ columns: [ { value: "Done" } ] }, [ "Done" ]);

        await api.renameColumn("Done", "Shipped");
        await api.renameColumn("Shipped", "Delivered");
        expect([ ...pendingRenames ])
            .toEqual([ [ "Done", "Delivered" ], [ "Shipped", "Delivered" ] ]);

        // Renaming back to a name still pending leaves nothing mapping it to itself.
        await api.renameColumn("Delivered", "Done");
        expect([ ...pendingRenames ]).toEqual([ [ "Shipped", "Done" ], [ "Delivered", "Done" ] ]);
    });

    /**
     * #10689 (second symptom): `columns` is derived render state, so it can lag behind the persisted
     * config. Rebuilding the whole config from it drops every column it has not caught up with.
     */
    it("preserves persisted columns missing from the derived column list", () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" }, { value: "In Progress" } ] },
            [ "To Do", "Done" ]
        );

        api.reorderColumn(0, 2);

        // "In Progress" followed "Done" before the move and still does.
        expect(saved.at(-1)?.columns?.map(col => col.value)).toEqual([ "Done", "In Progress", "To Do" ]);
    });
});

/**
 * Migration 0240 only ever saw the boards that existed when the document was upgraded, and
 * `_template_board` no longer defines the status label, so a board created afterwards has no
 * definition at all until the board view writes one from the columns it resolved.
 */
describe("BoardApi card operations", () => {
    beforeEach(() => {
        // Spies outlive a test otherwise, and one standing in for a write is read by the next.
        vi.restoreAllMocks();
        // Every write the api makes over the wire, answered rather than attempted.
        vi.spyOn(server, "put").mockResolvedValue(undefined);
        vi.mocked(branches.moveBeforeBranch).mockClear();
        vi.mocked(branches.moveAfterBranch).mockClear();
        vi.mocked(note_create.createNote).mockClear();
    });

    /** A board whose second column holds three cards to move among. */
    function createBoardWithCards() {
        const board = buildNote({
            title: "Board",
            children: [
                { title: "First", "#status": "Done" },
                { title: "Second", "#status": "Done" },
                { title: "Third", "#status": "Done" }
            ]
        });

        const items = board.getChildBranches().flatMap(branch => {
            const note = froca.getNoteFromCache(branch.noteId);
            return note ? [ { branch, note } ] : [];
        });
        const byColumn: ColumnMap = new Map([ [ "To Do", [] ], [ "Done", items ] ]);

        return { ...createApi({}, [ "To Do", "Done" ], board, "status", byColumn), items };
    }

    describe("opening a card", () => {
        /**
         * The board can be one split of several, and the focused pane is often the one the reader
         * came from, so a redirect navigates the pane the board itself is drawn in.
         */
        it("navigates the board's own pane rather than the focused one", () => {
            const { api, items } = createBoardWithCards();
            const own = vi.fn();
            const focused = vi.fn();
            api.noteContext = { setNote: own } as never;
            const previousTabManager = appContext.tabManager;
            appContext.tabManager = { getActiveContext: () => ({ setNote: focused }) } as never;

            try {
                addRedirect(items[0].note, "targetNote");
                api.openCard(items[0].note);
            } finally {
                appContext.tabManager = previousTabManager;
            }

            expect(own).toHaveBeenCalledWith("targetNote");
            expect(focused).not.toHaveBeenCalled();
        });

        it("opens the card itself where it redirects nowhere", () => {
            const { api, items } = createBoardWithCards();
            const open = vi.spyOn(appContext, "triggerCommand").mockReturnValue(undefined);

            api.openCard(items[0].note);

            expect(open).toHaveBeenCalledWith(
                "openInPopup", { noteIdOrPath: items[0].note.noteId });
        });

        /**
         * `openCard` reads both names. Written as literals rather than as the constants, so the
         * test pins the attribute names users type.
         */
        it.each([ "board:cardRedirectTo", "boardCardRedirectTo" ])(
            "redirects through the %s relation", (relation) => {
                const { api, items } = createBoardWithCards();
                const setNote = vi.fn();
                api.noteContext = { setNote } as never;

                addRedirect(items[0].note, "targetNote", relation);
                api.openCard(items[0].note);

                expect(setNote).toHaveBeenCalledWith("targetNote");
            });

        /** Files the relation straight into froca, which is all `openCard` reads. */
        function addRedirect(note: FNote, target: string, name = "board:cardRedirectTo") {
            const attributeId = `redirect-${name}-${note.noteId}`;
            froca.attributes[attributeId] = new FAttribute(froca, {
                noteId: note.noteId, attributeId, type: "relation",
                name, value: target, position: 0, isInheritable: false
            });
            note.attributes.push(attributeId);
            // Cleared rather than emptied: the cache is rebuilt only for a note it has no entry for.
            delete noteAttributeCache.attributes[note.noteId];
        }
    });

    it("files a card moved to another column before the one it was dropped on", async () => {
        const { api, items } = createBoardWithCards();
        const [ first ] = items;

        // The target column is empty, so there is nothing to place it against.
        await api.moveWithinBoard(
            [ { noteId: first.note.noteId, branchId: first.branch.branchId } ], "To Do", 1);
        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
        expect(branches.moveAfterBranch).not.toHaveBeenCalled();

    });

    it("files a card arriving from another column before the one it was dropped on", async () => {
        const { api, done, spare } = createBoardWithSpareCard();

        await api.moveWithinBoard(
            [ { noteId: spare.note.noteId, branchId: spare.branch.branchId } ], "Done", 1);

        expect(branches.moveBeforeBranch)
            .toHaveBeenCalledWith([ spare.branch.branchId ], done[1].branch.branchId);
    });

    /** A board whose "Done" column holds three cards, with a fourth waiting in "To Do". */
    function createBoardWithSpareCard(shownInDone?: (done: ColumnItem[]) => ColumnItem[]) {
        const board = buildNote({
            title: "Board",
            children: [
                { title: "First", "#status": "Done" },
                { title: "Second", "#status": "Done" },
                { title: "Third", "#status": "Done" },
                { title: "Spare", "#status": "To Do" }
            ]
        });

        const items = board.getChildBranches().flatMap(branch => {
            const note = froca.getNoteFromCache(branch.noteId);
            return note ? [ { branch, note } ] : [];
        });
        const done = items.slice(0, 3);
        const spare = items[3];
        const allByColumn: ColumnMap = new Map([ [ "To Do", [ spare ] ], [ "Done", done ] ]);
        const byColumn: ColumnMap = shownInDone
            ? new Map([ [ "To Do", [ spare ] ], [ "Done", shownInDone(done) ] ])
            : allByColumn;

        const created = createApi(
            {}, [ "To Do", "Done" ], board, "status", byColumn, allByColumn);
        return { ...created, done, spare };
    }

    /**
     * Crossing columns writes a placement too. Left with the tree position it came with, the card
     * would rank among the target's cards by wherever it happened to sit before the drop.
     */
    it("files a card dropped past the last card of another column after it", async () => {
        const { api, done, spare } = createBoardWithSpareCard();

        await api.moveWithinBoard(
            [ { noteId: spare.note.noteId, branchId: spare.branch.branchId } ], "Done", 3);

        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
        expect(branches.moveAfterBranch)
            .toHaveBeenCalledWith([ spare.branch.branchId ], done[2].branch.branchId);
    });

    it("files a card dropped into a column a filter empties after the cards it hides", async () => {
        const { api, done, spare } = createBoardWithSpareCard(() => []);

        await api.moveWithinBoard(
            [ { noteId: spare.note.noteId, branchId: spare.branch.branchId } ], "Done", 0);

        expect(branches.moveAfterBranch)
            .toHaveBeenCalledWith([ spare.branch.branchId ], done[2].branch.branchId);
    });

    it("files a card dropped past the last card shown after that one, not the hidden", async () => {
        const { api, done, spare } = createBoardWithSpareCard((all) => [ all[0] ]);

        await api.moveWithinBoard(
            [ { noteId: spare.note.noteId, branchId: spare.branch.branchId } ], "Done", 1);

        expect(branches.moveAfterBranch)
            .toHaveBeenCalledWith([ spare.branch.branchId ], done[0].branch.branchId);
    });

    it("sends a card after the last one drawn in a column a filter narrows", async () => {
        const { api, done, spare } = createBoardWithSpareCard((all) => [ all[0] ]);

        await api.moveToColumnEnd(
            [ { noteId: spare.note.noteId, branchId: spare.branch.branchId } ], "Done");

        expect(branches.moveAfterBranch)
            .toHaveBeenCalledWith([ spare.branch.branchId ], done[0].branch.branchId);
    });

    it("sends a card past the cards a filter hides when it draws none of them", async () => {
        const { api, done, spare } = createBoardWithSpareCard(() => []);

        await api.moveToColumnEnd(
            [ { noteId: spare.note.noteId, branchId: spare.branch.branchId } ], "Done");

        expect(branches.moveAfterBranch)
            .toHaveBeenCalledWith([ spare.branch.branchId ], done[2].branch.branchId);
    });

    /**
     * A card is rarely made to match the query in force, so one made here is drawn anyway rather
     * than the board answering an addition by showing nothing at all.
     */
    it("reports every card it gains, so a filter does not swallow it", async () => {
        const kept: string[] = [];
        const { api } = createApi(
            {}, [ "Done" ], undefined, "status", new Map(), undefined,
            (noteId) => kept.push(noteId));
        vi.mocked(note_create.createNote).mockResolvedValue(
            { note: { noteId: "made" } } as never);

        await api.createNewItem("Done", "Made now");

        expect(kept).toEqual([ "made" ]);
    });

    it("makes a card at the head of a column above the first one drawn", async () => {
        const { api, done } = createBoardWithSpareCard((all) => [ all[1] ]);

        await api.createNewItem("Done", "Newest", "top");

        expect(note_create.createNote).toHaveBeenCalledWith(
            expect.any(String),
            expect.objectContaining({ target: "before", targetBranchId: done[1].branch.branchId }));
    });

    it("reorders within a column, and places past the last card after it", async () => {
        const { api, items } = createBoardWithCards();
        const [ first, , third ] = items;

        await api.moveWithinBoard(
            [ { noteId: first.note.noteId, branchId: first.branch.branchId } ], "Done", 2);
        expect(branches.moveBeforeBranch)
            .toHaveBeenCalledWith([ first.branch.branchId ], third.branch.branchId);

        await api.moveWithinBoard(
            [ { noteId: first.note.noteId, branchId: first.branch.branchId } ], "Done", 3);
        expect(branches.moveAfterBranch)
            .toHaveBeenCalledWith([ first.branch.branchId ], third.branch.branchId);
    });

    /**
     * Nothing waits for the board to redraw between two keystrokes, so the column map the API holds
     * still shows the target as it was before the first card arrived.
     */
    it("sends each card past the one it sent before, without waiting for a redraw", async () => {
        const { api, items } = createBoardWithCards();
        const [ first, second ] = items;

        await api.moveToColumnEnd(
            [ { noteId: first.note.noteId, branchId: first.branch.branchId } ], "To Do");
        expect(branches.moveAfterBranch).not.toHaveBeenCalled();

        await api.moveToColumnEnd(
            [ { noteId: second.note.noteId, branchId: second.branch.branchId } ], "To Do");
        expect(branches.moveAfterBranch)
            .toHaveBeenLastCalledWith([ second.branch.branchId ], first.branch.branchId);
    });

    /**
     * That memory stands in for what the column map does not show yet, so it is worth exactly as
     * long as the map: kept across a refresh it names a card that is no longer last, and the next
     * one is filed behind it rather than at the end.
     */
    it("forgets what it sent to a column once the board has drawn that column again", async () => {
        const { api, items } = createBoardWithCards();
        const [ first, second, third ] = items;

        await api.moveToColumnEnd(
            [ { noteId: first.note.noteId, branchId: first.branch.branchId } ], "To Do");

        // The refresh that catches up, and with it a card that now stands last in that column.
        api.update(
            new Map([ [ "To Do", [ first, third ] ], [ "Done", [ second ] ] ]),
            [ "To Do", "Done" ], first.note.getParentNotes()[0], "status", {}, () => {}, () => {});

        // Behind what the board now shows last, not behind what this sent before it.
        await api.moveToColumnEnd(
            [ { noteId: second.note.noteId, branchId: second.branch.branchId } ], "To Do");
        expect(branches.moveAfterBranch)
            .toHaveBeenLastCalledWith([ second.branch.branchId ], third.branch.branchId);
    });

    /**
     * A card can only be placed against a neighbour that is drawn, so a move leaving the cards on
     * screen where they are would move the ones a filter hides instead: dropping the second card
     * drawn back at the end writes `moveAfterBranch` against the first, taking it past the hidden
     * card between them.
     */
    it("moves nothing for a drop that leaves the cards a filter draws where they are", async () => {
        const { api, done } = createBoardWithSpareCard((all) => [ all[0], all[2] ]);

        // Back at the end of the two cards drawn, which is where the second one already stands.
        await api.moveWithinBoard(
            [ { noteId: done[2].note.noteId, branchId: done[2].branch.branchId } ], "Done", 2);
        // And the same drop read from the other card: before the second drawn, where it already is.
        await api.moveWithinBoard(
            [ { noteId: done[0].note.noteId, branchId: done[0].branch.branchId } ], "Done", 1);

        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
        expect(branches.moveAfterBranch).not.toHaveBeenCalled();
    });

    it("moves nothing for a card dropped where it is, or one it cannot find", async () => {
        const { api, items } = createBoardWithCards();
        const [ first ] = items;

        await api.moveWithinBoard(
            [ { noteId: first.note.noteId, branchId: first.branch.branchId } ], "Done", 1);
        await api.moveWithinBoard(
            [ { noteId: "missingNote", branchId: "missingBranch" } ], "Done", 2);

        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
        expect(branches.moveAfterBranch).not.toHaveBeenCalled();
    });

    it("takes a card off the board by removing the value it is grouped by", async () => {
        const { api, items } = createBoardWithCards();
        const removeLabel = vi.spyOn(attributes, "removeOwnedLabelByName").mockResolvedValue(true);

        await api.removeFromBoard([ items[0].note.noteId ]);
        expect(removeLabel).toHaveBeenCalledWith(items[0].note, "status");

        // A note the cache has never heard of is left alone rather than throwing.
        await api.removeFromBoard([ "missingNote" ]);
        expect(removeLabel).toHaveBeenCalledTimes(1);
    });

    /**
     * A value the card takes from an ancestor is not the card's to remove, and the board reads the
     * value it ends up with rather than the one it owns.
     */
    it("covers a value the card inherits rather than uncovering it", async () => {
        const board = buildNote({
            title: "Board",
            "#status(inheritable)": "Done",
            children: [ { title: "Card" } ]
        });
        const [ cardId ] = [ ...board.getChildNoteIds() ];
        const { api } = createApi({}, [], board);
        const removeLabel = vi.spyOn(attributes, "removeOwnedLabelByName").mockResolvedValue(true);
        const setLabel = vi.spyOn(attributes, "setLabel").mockResolvedValue(undefined as never);

        await api.removeFromBoard([ cardId ]);

        expect(setLabel).toHaveBeenCalledWith(cardId, "status", "");
        expect(removeLabel).not.toHaveBeenCalled();
    });

    it("takes a card off a relation board by removing that relation", async () => {
        const board = buildNote({ title: "Board", children: [ { title: "Card" } ] });
        const { api } = createApi({}, [], board, "~status");
        const removeRelation = vi.spyOn(attributes, "removeOwnedRelationByName")
            .mockResolvedValue(true);

        await api.removeFromBoard([ board.getChildNoteIds()[0] ]);
        expect(removeRelation).toHaveBeenCalledWith(expect.anything(), "status");
    });

    /**
     * A relation points at a note, so there is no empty one to cover an inherited value with. The
     * card cannot leave its column here, and saying so beats appearing to do nothing.
     */
    it("says why a card cannot leave a column it takes from elsewhere", async () => {
        const board = buildNote({
            title: "Board",
            "~status(inheritable)": "root",
            children: [ { title: "Card" } ]
        });
        const { api } = createApi({}, [], board, "~status");
        const removeRelation = vi.spyOn(attributes, "removeOwnedRelationByName")
            .mockResolvedValue(true);
        const message = vi.spyOn(toast, "showMessage").mockReturnValue(undefined);

        await api.removeFromBoard([ board.getChildNoteIds()[0] ]);

        expect(message).toHaveBeenCalledWith("board_view.inherited-column", 3000);
        expect(removeRelation).not.toHaveBeenCalled();
    });

    it("trims the title it renames a card to", async () => {
        const { api, items } = createBoardWithCards();
        const put = vi.spyOn(server, "put").mockResolvedValue(undefined);

        await api.renameCard(items[0].note.noteId, "  Fresh title  ");

        expect(put).toHaveBeenCalledWith(
            "notes/" + items[0].note.noteId + "/title", { title: "Fresh title" });
    });

    it("inserts a card beside another, named and iconed as it was typed", async () => {
        const { api, items } = createBoardWithCards();
        const created = buildNote({ title: "Created" });
        vi.spyOn(server, "put").mockResolvedValue(undefined);
        vi.mocked(note_create.createNote).mockResolvedValue({
            note: created, branch: { branchId: "createdBranch" }
        } as never);

        const result = await api.insertRowAtPosition(
            "Done", items[0].branch.branchId, "after", "Typed", "bx bx-star");

        expect(result).toEqual({ note: created, branch: { branchId: "createdBranch" } });
        expect(note_create.createNote).toHaveBeenCalledWith(
            expect.any(String),
            expect.objectContaining({
                targetBranchId: items[0].branch.branchId,
                target: "after",
                title: "Typed",
                attributes: expect.arrayContaining([
                    expect.objectContaining({ name: "iconClass", value: "bx bx-star" })
                ])
            }));
    });

    /**
     * What a field standing among a column's cards makes: the card goes above the one the field
     * stands over, and a field standing below the last card makes one at the end of the column.
     */
    it("creates a card above the one a field stands over", async () => {
        const { api, items } = createBoardWithCards();
        const created = buildNote({ title: "Created" });
        vi.spyOn(server, "put").mockResolvedValue(undefined);
        vi.mocked(note_create.createNote).mockResolvedValue({
            note: created, branch: { branchId: "createdBranch" }
        } as never);

        expect(await api.createNewItemBefore("Done", items[0].branch.branchId, "First"))
            .toBe(created.noteId);
        expect(note_create.createNote).toHaveBeenLastCalledWith(
            expect.any(String),
            expect.objectContaining({
                targetBranchId: items[0].branch.branchId, target: "before", title: "First"
            }));

        // Below the last card there is nothing to go above, so the card is made at the end.
        expect(await api.createNewItemBefore("Done", undefined, "Last")).toBe(created.noteId);
        const last = vi.mocked(note_create.createNote).mock.calls.at(-1)?.[1];
        expect(last).toEqual(expect.objectContaining({ title: "Last" }));
        expect(last).not.toHaveProperty("target");
    });

    it("reports a card it could not create rather than filing nothing", async () => {
        const { api, items } = createBoardWithCards();
        vi.mocked(note_create.createNote).mockResolvedValue({ note: null, branch: null } as never);

        await expect(api.insertRowAtPosition("Done", items[0].branch.branchId, "after", "Typed"))
            .rejects.toThrow("Failed to create note");
    });

    it("creates a card in a column, and reports a failure without throwing", async () => {
        const { api } = createBoardWithCards();
        const created = buildNote({ title: "Created" });
        const put = vi.spyOn(server, "put").mockResolvedValue(undefined);
        vi.mocked(note_create.createNote).mockResolvedValue({
            note: created, branch: { branchId: "createdBranch" }
        } as never);

        // The column goes in with the note. A write of its own would refresh the whole board a
        // second time, which is what adding a card costs on a board of any size.
        await api.createNewItem("Done", "Created");
        expect(note_create.createNote).toHaveBeenCalledWith(
            expect.any(String),
            expect.objectContaining({
                title: "Created",
                attributes: [ expect.objectContaining({
                    type: "label", name: "status", value: "Done"
                }) ]
            }));
        expect(put).not.toHaveBeenCalled();

        // The board has already drawn the card, so a failure here is logged rather than thrown.
        const logged = vi.spyOn(console, "error").mockImplementation(() => {});
        vi.mocked(note_create.createNote).mockRejectedValueOnce(new Error("offline"));
        await expect(api.createNewItem("Done", "Another")).resolves.toBeUndefined();
        expect(logged).toHaveBeenCalled();
    });

    /**
     * A column is drawn in the order its notes stand in, so the head of one is the card before its
     * first, not the first child of the board: the columns share one list between them.
     */
    it("makes a card at the head of a column against that column's first card", async () => {
        const { api, items } = createBoardWithCards();
        vi.mocked(note_create.createNote).mockResolvedValue({
            note: buildNote({ title: "Created" }), branch: { branchId: "createdBranch" }
        } as never);

        await api.createNewItem("Done", "First of all", "top");
        expect(note_create.createNote).toHaveBeenCalledWith(
            expect.any(String),
            expect.objectContaining({
                target: "before", targetBranchId: items[0].branch.branchId
            }));

        // An empty column has nothing to be placed against, and the card is simply made.
        await api.createNewItem("Nowhere", "Only one", "top");
        expect(note_create.createNote).toHaveBeenLastCalledWith(
            expect.any(String),
            expect.not.objectContaining({ target: "before" }));
    });

    it("sends a card to the head of its column, and leaves one already there alone", async () => {
        const { api, items } = createBoardWithCards();
        const moveBefore = vi.spyOn(branches, "moveBeforeBranch").mockResolvedValue(true);

        const last = items[items.length - 1];
        await api.moveToColumnStart(last.note.noteId, last.branch.branchId, "Done");
        expect(moveBefore).toHaveBeenCalledWith(
            [ last.branch.branchId ], items[0].branch.branchId);

        moveBefore.mockClear();
        await api.moveToColumnStart(items[0].note.noteId, items[0].branch.branchId, "Done");
        expect(moveBefore).not.toHaveBeenCalled();
    });

    /**
     * What a board offers and what it last made a card from live in its own configuration, beside
     * the columns: the templates are the board's, not a column's.
     */
    it("offers the stock templates until the board has its own, and remembers the last used", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        expect(api.getCardTemplateIds()).toEqual(DEFAULT_CARD_TEMPLATES);
        expect(api.getLastCardTemplateId()).toBeUndefined();

        await api.setCardTemplateIds([ "type:canvas:application/json", "note:mine" ]);
        expect(saved.at(-1)?.templates).toEqual([ "type:canvas:application/json", "note:mine" ]);
        // Written beside the columns rather than over them.
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do" } ]);
        expect(api.getCardTemplateIds()).toEqual([ "type:canvas:application/json", "note:mine" ]);

        await api.setLastCardTemplateId("note:mine");
        expect(saved.at(-1)?.template).toBe("note:mine");
        expect(saved.at(-1)?.templates).toEqual([ "type:canvas:application/json", "note:mine" ]);

        // The same one again is not a change, and writing it would refresh the board for nothing.
        const writes = saved.length;
        await api.setLastCardTemplateId("note:mine");
        expect(saved.length).toBe(writes);
    });

    /**
     * A card inserted beside another one is made from the same template as one made in the footer,
     * without the editor it is named in having to know about templates at all.
     */
    it("makes an inserted card from the template last used", async () => {
        const { api } = createBoardWithCards();
        api.setAvailableCardTemplates([
            {
                id: "type:text:text/html", title: "Text", icon: "bx bx-note", group: "type",
                options: { type: "text", mime: "text/html" }
            },
            {
                id: "type:canvas:application/json", title: "Canvas", icon: "bx bx-pen",
                group: "type", options: { type: "canvas", mime: "application/json" }
            }
        ]);
        vi.mocked(note_create.createNote).mockResolvedValue({
            note: buildNote({ title: "Created" }), branch: { branchId: "createdBranch" }
        } as never);

        // Nothing has been used yet, so the first the board offers stands.
        await api.insertRowAtPosition("Done", "branchId", "after", "Typed");
        expect(note_create.createNote).toHaveBeenLastCalledWith(
            expect.any(String), expect.objectContaining({ type: "text" }));

        await api.setLastCardTemplateId("type:canvas:application/json");
        await api.insertRowAtPosition("Done", "branchId", "after", "Typed");
        expect(note_create.createNote).toHaveBeenLastCalledWith(
            expect.any(String), expect.objectContaining({ type: "canvas" }));

        // And a card made in the footer, where the editor hands one over, is made from that.
        await api.createNewItem("Done", "Typed");
        expect(note_create.createNote).toHaveBeenLastCalledWith(
            expect.any(String), expect.objectContaining({ type: "canvas" }));
    });

    /** A board with nothing offered could make no card at all, so an empty set is refused. */
    it("refuses to store an empty set of templates", async () => {
        const { api, saved } = createApi(
            { columns: [], templates: [ "type:text:text/html" ] }, []);

        await api.setCardTemplateIds([]);

        expect(saved).toEqual([]);
        expect(api.getCardTemplateIds()).toEqual([ "type:text:text/html" ]);
    });

    /** What the template names is what the note is made from, in the same write as the card. */
    it("makes a card from the template it is given", async () => {
        const { api } = createBoardWithCards();
        vi.mocked(note_create.createNote).mockResolvedValue({
            note: buildNote({ title: "Created" }), branch: { branchId: "createdBranch" }
        } as never);

        await api.createNewItem("Done", "Drawn", "bottom", undefined, {
            id: "type:canvas:application/json",
            title: "Canvas",
            icon: "bx bx-pen",
            group: "type",
            options: { type: "canvas", mime: "application/json" }
        });

        expect(note_create.createNote).toHaveBeenCalledWith(
            expect.any(String),
            expect.objectContaining({ type: "canvas", mime: "application/json" }));

        // And the same for a card inserted beside another one.
        await api.insertRowAtPosition("Done", "branchId", "after", "Typed", undefined, {
            id: "note:mine",
            title: "My template",
            icon: "bx bx-star",
            group: "user",
            options: { type: "text", mime: "text/html", templateNoteId: "mine" }
        });

        expect(note_create.createNote).toHaveBeenLastCalledWith(
            expect.any(String),
            expect.objectContaining({ templateNoteId: "mine", type: "text" }));
    });

    it("hands the editing state straight through to the board", () => {
        const { api, editing } = createBoardWithCards();

        api.startEditing("someBranch");
        api.dismissEditingTitle();

        expect(editing).toEqual([ "someBranch", undefined ]);
    });
});

describe("BoardApi.addExistingItem", () => {
    let put: ReturnType<typeof vi.spyOn>;

    beforeEach(() => {
        put = vi.spyOn(server, "put").mockResolvedValue(undefined);
        vi.mocked(branches.cloneNoteToParentNote).mockClear();
        vi.mocked(dialog.confirm).mockClear().mockResolvedValue(true);
    });

    /**
     * A board holding `insider` a level down, alongside an unrelated `outsider`.
     *
     * The ids are generated rather than fixed: `buildNote` appends to the note attribute cache
     * under the id given, so one reused across tests carries the previous test's attributes.
     */
    function createBoardWith(outsiderAttributes: Record<string, string> = {}) {
        const board = buildNote({
            title: "Board",
            children: [
                { title: "Branch", children: [ { title: "Insider", "#status": "To Do" } ] }
            ]
        });
        const outsider = buildNote({ title: "Outsider", ...outsiderAttributes });
        const branch = froca.getNoteFromCache(board.getChildNoteIds()[0]);

        return {
            api: createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ], board).api,
            boardId: board.noteId,
            insiderId: branch?.getChildNoteIds()[0] ?? "",
            outsiderId: outsider.noteId
        };
    }

    it("clones a note from outside the board, then files it in the column", async () => {
        const { api, boardId, outsiderId } = createBoardWith();

        expect(await api.addExistingItem("To Do", outsiderId)).toBe(true);
        expect(branches.cloneNoteToParentNote).toHaveBeenCalledWith(outsiderId, boardId);

        const [ url, body ] = put.mock.calls.at(-1) ?? [];
        expect(url).toBe(`notes/${outsiderId}/set-attribute`);
        expect(body).toMatchObject({ type: "label", name: "status", value: "To Do" });
    });

    // The board shows its whole subtree, so a grandchild is already on it.
    it("only changes the column of a note already under the board", async () => {
        const { api, insiderId } = createBoardWith();

        expect(await api.addExistingItem("To Do", insiderId)).toBe(true);
        expect(branches.cloneNoteToParentNote).not.toHaveBeenCalled();
    });

    it("warns before taking a note that carries the grouping label from elsewhere", async () => {
        const { api, outsiderId } = createBoardWith({ "#status": "Done" });

        expect(await api.addExistingItem("To Do", outsiderId)).toBe(true);
        expect(dialog.confirm).toHaveBeenCalledTimes(1);

        vi.mocked(dialog.confirm).mockResolvedValue(false);
        vi.mocked(branches.cloneNoteToParentNote).mockClear();

        expect(await api.addExistingItem("To Do", outsiderId)).toBe(false);
        expect(branches.cloneNoteToParentNote).not.toHaveBeenCalled();
    });

    it("does not warn for a note that carries no value of its own", async () => {
        const { api, outsiderId } = createBoardWith();

        await api.addExistingItem("To Do", outsiderId);
        expect(dialog.confirm).not.toHaveBeenCalled();
    });
});

describe("BoardApi.syncColumnsToDefinition", () => {
    let put: ReturnType<typeof vi.spyOn>;

    beforeEach(() => {
        // Without restoring first, each spy wraps the previous one and the calls accumulate.
        vi.restoreAllMocks();
        put = vi.spyOn(server, "put").mockResolvedValue(undefined);
    });

    function definitionWritten() {
        const [ url, body ] = put.mock.calls.at(-1) ?? [];
        return { url, ...(body as Record<string, unknown> | undefined) } as {
            url?: string;
            attributeId?: string;
            type?: string;
            name?: string;
            value?: string;
            isInheritable?: boolean;
        };
    }

    it("gives a board with no definition its own promoted select carrying the resolved columns", async () => {
        const { api } = createApi({}, [], buildBoard({}));

        await api.syncColumnsToDefinition([ "To Do", "Done" ], api.groupBy);

        expect(definitionWritten()).toMatchObject({
            // The upsert endpoint, which matches the board's own attribute of this name.
            url: "notes/boardNote/set-attribute",
            type: "label",
            name: "label:status",
            // Promoted, so the column a card sits in is a field the card actually shows.
            value: "promoted,alias=Status,single,select,options=To Do;Done",
            isInheritable: true
        });
    });

    /**
     * Two syncs can be in flight at once — a column edit landing mid-refresh, or a refresh starting
     * before the previous write is back — and both read the same "no definition yet" state. Asking
     * for a new attribute by id would have each create one, leaving the board with two definitions
     * of the same name and every lookup seeing only the first.
     */
    it("addresses the definition by name, so overlapping syncs cannot each create one", async () => {
        const { api } = createApi({}, [], buildBoard({}));

        await Promise.all([
            api.syncColumnsToDefinition([ "To Do" ], api.groupBy),
            api.syncColumnsToDefinition([ "To Do", "Done" ], api.groupBy)
        ]);

        expect(put).toHaveBeenCalledTimes(2);
        for (const [ url, body ] of put.mock.calls) {
            expect(url).toBe("notes/boardNote/set-attribute");
            // No id to create a second row under: the server matches the one owned attribute of this
            // name, so whichever request arrives second updates what the first wrote.
            expect(body).not.toHaveProperty("attributeId");
            expect(body).toMatchObject({ name: "label:status" });
        }
    });

    it("names a board grouping by its own label after that label rather than after status", async () => {
        const { api } = createApi({}, [], buildBoard({}), "priority");

        await api.syncColumnsToDefinition([ "High" ], api.groupBy);

        expect(definitionWritten()).toMatchObject({
            name: "label:priority",
            // Still promoted, but unaliased — "Status" is only the name of the default label.
            value: "promoted,single,select,options=High"
        });
    });

    /**
     * Migration 0240 leaves a board that never showed a Status field without one, so re-promoting it
     * here would make a field appear on every card of a board that had deliberately gone without.
     */
    it("keeps an existing definition unpromoted rather than promoting it on the way past", async () => {
        const { api } = createApi({}, [], buildBoard({
            "#label:status": "single,select,options=To Do"
        }));

        await api.syncColumnsToDefinition([ "To Do", "Done" ], api.groupBy);

        expect(definitionWritten().value).toBe("single,select,options=To Do;Done");
    });

    /**
     * The write lands as an entity change, which re-renders the board, which syncs again — so a board
     * whose definition already says what it shows has to write nothing, or it never stops.
     */
    it("writes nothing when the definition already offers exactly those columns", async () => {
        const { api } = createApi({}, [], buildBoard({
            "#label:status": "promoted,single,select,options=To Do;Done"
        }));

        await api.syncColumnsToDefinition([ "To Do", "Done" ], api.groupBy);

        expect(put).not.toHaveBeenCalled();
    });

    it("updates its own definition in place when a column appeared from outside the board", async () => {
        const board = buildBoard({ "#label:status": "promoted,single,select,options=To Do" });
        const { api } = createApi({}, [], board);

        // A note given `#status=Blocked` from the table view shows up as a column here, and the
        // definition has to learn about it as well.
        await api.syncColumnsToDefinition([ "To Do", "Blocked" ], api.groupBy);

        const written = definitionWritten();
        expect(written.value).toBe("promoted,single,select,options=To Do;Blocked");
        // Matched by name on the board itself, so the row it already owns is updated rather than a
        // second definition of the same name being added beside it.
        expect(written.url).toBe(`notes/${board.noteId}/set-attribute`);
        expect(written.name).toBe("label:status");
    });

    it("keeps a differently ordered list, since the order is the one the user arranged", async () => {
        const { api } = createApi({}, [], buildBoard({
            "#label:status": "single,select,options=To Do;Done"
        }));

        await api.syncColumnsToDefinition([ "Done", "To Do" ], api.groupBy);

        expect(definitionWritten().value).toBe("single,select,options=Done;To Do");
    });

    it("copies a definition it does not own into one of its own rather than editing it", async () => {
        const board = buildBoard({}, [
            { noteId: BOARD_TEMPLATE_ID, name: "label:status", value: "promoted,single,text" }
        ]);
        const { api } = createApi({}, [], board);

        await api.syncColumnsToDefinition([ "To Do" ], api.groupBy);

        const written = definitionWritten();
        // The endpoint only ever matches attributes owned by this note, so the template's own row is
        // left alone and the board gains one of its own.
        expect(written.url).toBe(`notes/${board.noteId}/set-attribute`);
        // What the template said is kept, so a board whose field was promoted keeps a promoted field.
        expect(written.value).toBe("promoted,single,select,options=To Do");
    });

    it.each<[ string, string, UntouchableBoard ]>([
        [ "grouping by a relation", "~status", {} ],
        [ "a definition owned by an ancestor", "status", {
            inherited: { noteId: "someAncestor", name: "label:status", value: "promoted,single,text" }
        } ],
        [ "a multi-valued definition", "status", { owned: { "#label:status": "promoted,multi,text" } } ],
        [ "a definition typed as something else", "status", { owned: { "#label:status": "promoted,single,date" } } ]
    ])("leaves the definition alone for %s", async (_label, groupBy, { owned, inherited }) => {
        const board = buildBoard(owned ?? {}, inherited ? [ inherited ] : []);
        const { api } = createApi({}, [], board, groupBy);

        await api.syncColumnsToDefinition([ "To Do" ], api.groupBy);

        expect(put).not.toHaveBeenCalled();
    });

    it("does not invent an empty definition, but does empty one the board owns", async () => {
        const { api: withoutDefinition } = createApi({}, [], buildBoard({}));
        await withoutDefinition.syncColumnsToDefinition([], withoutDefinition.groupBy);
        expect(put).not.toHaveBeenCalled();

        const { api: withDefinition } = createApi({}, [], buildBoard({
            "#label:status": "promoted,single,select,options=To Do"
        }));
        await withDefinition.syncColumnsToDefinition([], withDefinition.groupBy);
        expect(definitionWritten().value).toBe("promoted,single,select");
    });
});

describe("BoardApi column storage", () => {
    /** A board grouped by `priority`, with columns stored for it and for the default grouping. */
    function priorityBoard(byColumn: ColumnMap = new Map()) {
        return createApi({
            columns: [ { value: "To Do", icon: "bx bx-time" } ],
            priorityViewColumns: [ { value: "High", icon: "bx bx-up-arrow", limit: 3 } ]
        }, [ "High" ], buildBoard({}), "priority", byColumn);
    }

    it("reads what a column is drawn with from the grouping's own key", () => {
        const { api } = priorityBoard();

        expect(api.getColumnIcon("High")).toBe("bx bx-up-arrow");
        expect(api.getColumnLimit("High")).toBe(3);
        // The default grouping's column, which this grouping knows nothing about.
        expect(api.getColumnIcon("To Do")).toBe(DEFAULT_COLUMN_ICON);
    });

    it("stores a new column under its key, leaving the other grouping's alone", async () => {
        const { api, saved } = priorityBoard();

        await api.addNewColumn("Low");

        expect(saved.at(-1)?.priorityViewColumns?.map(col => col.value)).toEqual([ "High", "Low" ]);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", icon: "bx bx-time" } ]);
    });

    it("keeps a column's icon and colour out of the other grouping's list", async () => {
        const { api, saved } = priorityBoard();

        await api.setColumnIcon("High", "bx bx-star");
        await api.setColumnColor("High", "#0f0");

        expect(saved.at(-1)?.priorityViewColumns)
            .toEqual([ { value: "High", icon: "bx bx-star", color: "#0f0", limit: 3 } ]);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", icon: "bx bx-time" } ]);
    });

    it("removes a column from the grouping's key alone", async () => {
        const { api, saved } = priorityBoard(new Map([ [ "High", [] ] ]));

        await api.removeColumn("High");

        expect(saved.at(-1)?.priorityViewColumns).toEqual([]);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", icon: "bx bx-time" } ]);
    });

    it("stores the default grouping under the key every board already uses", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" } ] }, [ "To Do" ], buildBoard({}));

        await api.addNewColumn("Done");

        expect(saved.at(-1)?.columns?.map(col => col.value)).toEqual([ "To Do", "Done" ]);
        expect(Object.keys(saved.at(-1) ?? {})).not.toContain("statusViewColumns");
    });

    /**
     * The board reads for a grouping it is being switched to before the api is pointed at it, so a
     * sync answering for that read would put one grouping's columns into another's definition.
     */
    it("refuses a sync made for a grouping it is not on", async () => {
        const put = vi.spyOn(server, "put").mockResolvedValue(undefined);
        const { api } = createApi({}, [], buildBoard({}), "priority");

        await api.syncColumnsToDefinition([ "To Do", "Done" ], "status");
        expect(put).not.toHaveBeenCalled();

        await api.syncColumnsToDefinition([ "High", "Low" ], "priority");
        expect(put).toHaveBeenCalledTimes(1);
        expect(put.mock.calls[0][0]).toBe("notes/boardNote/set-attribute");
        expect(put.mock.calls[0][1]).toMatchObject({
            name: "label:priority", value: "promoted,single,select,options=High;Low"
        });
    });
});

/** A board whose definition the sync must not touch, however it came to have one. */
interface UntouchableBoard {
    owned?: Record<string, string>;
    inherited?: { noteId: string; name: string; value: string };
}

/**
 * A board note, optionally reached by definitions it does not own.
 *
 * Froca's mock does not resolve templates, so an inherited definition is pushed onto the note's
 * attribute cache directly — after the owned ones, which is the order `__getCachedAttributes`
 * produces and which the nearest-wins deduplication depends on.
 */
function buildBoard(
    ownedAttributes: Record<string, string>,
    inheritedDefinitions: { noteId: string; name: string; value: string }[] = []
): FNote {
    // buildNote appends to whatever the cache already holds for the id, so the previous test's
    // definitions would otherwise still be on the note.
    delete noteAttributeCache.attributes["boardNote"];

    const board = buildNote({ id: "boardNote", title: "Board", "#viewType": "board", ...ownedAttributes });

    for (const [ index, { noteId, name, value } ] of inheritedDefinitions.entries()) {
        noteAttributeCache.attributes[board.noteId].push(new FAttribute(froca, {
            noteId,
            attributeId: `inherited${index}`,
            type: "label",
            name,
            value,
            position: index,
            isInheritable: true
        }));
    }

    return board;
}

describe("pending writes shared between the views of a board", () => {
    /**
     * Two tabs on one board read the same notes, definition and attachment, so a write in flight on
     * one has to be a write in flight on the other. A view with a record of its own would resolve a
     * column being deleted elsewhere out of the sources that still carry it, and write it back.
     */
    it("hands every view of one board the same record, and another board its own", () => {
        const writes = getPendingWrites("board1|status");

        expect(getPendingWrites("board1|status")).toBe(writes);
        expect(getPendingWrites("board1|priority")).not.toBe(writes);
        expect(getPendingWrites("board2|status")).not.toBe(writes);
    });

    /**
     * A view is handed the record once and holds it while it is mounted, so a record dropped for
     * being empty would leave the views that already have it talking to nobody.
     */
    it("keeps a board's record after the writes on it have all landed", () => {
        const writes = getPendingWrites("board3|status");
        writes.renames.set("Done", undefined);
        writes.renames.delete("Done");

        expect(getPendingWrites("board3|status")).toBe(writes);
    });
});

describe("removing a column with the question put first", () => {
    it("drops it only once agreed, and says so when the write is refused", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );
        const confirm = vi.spyOn(dialog, "confirmWithNoteDeletion").mockResolvedValue(false);
        const error = vi.spyOn(toast, "showError").mockReturnValue(undefined);

        expect(await api.confirmAndRemoveColumn("Done")).toBe(false);
        // The box is about notes to delete, and an empty column has none.
        expect(confirm).toHaveBeenCalledWith("board_view.delete-column-confirmation", undefined);
        expect(saved).toEqual([]);

        confirm.mockResolvedValue({ confirmed: true, isDeleteNoteChecked: false });
        expect(await api.confirmAndRemoveColumn("Done")).toBe(true);
        expect(saved.at(-1)?.columns?.map(column => column.value)).toEqual([ "To Do" ]);
        expect(error).not.toHaveBeenCalled();

        // A refusal from the server is reported rather than passing for a deletion.
        vi.mocked(executeBulkActions).mockRejectedValueOnce(new Error("offline"));
        expect(await api.confirmAndRemoveColumn("To Do")).toBe(false);
        expect(error).toHaveBeenCalledWith("board_view.save-error");
    });

    /**
     * Taking the offer deletes the column's cards, rather than stripping the grouping value and
     * leaving them on the board.
     */
    it("deletes the notes in the column when the offer is taken", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ], undefined, "status", cards({ Done: [ "one", "two" ] }));
        const confirm = vi.spyOn(dialog, "confirmWithNoteDeletion")
            .mockResolvedValue({ confirmed: true, isDeleteNoteChecked: true });

        expect(await api.confirmAndRemoveColumn("Done")).toBe(true);

        expect(confirm).toHaveBeenCalledWith(
            "board_view.delete-column-confirmation", "board_view.delete-column-notes");
        expect(executeBulkActions).toHaveBeenCalledWith(
            [ "one", "two" ], [ { name: "deleteNote" } ], { silent: true });
        expect(saved.at(-1)?.columns?.map(column => column.value)).toEqual([ "To Do" ]);
    });

    /** Left untaken, the cards stay on the board without the value that put them in the column. */
    it("strips the grouping value when the offer is left untaken", async () => {
        const { api } = createApi(
            { columns: [ { value: "Done" } ] },
            [ "Done" ], undefined, "status", cards({ Done: [ "one" ] }));
        vi.spyOn(dialog, "confirmWithNoteDeletion")
            .mockResolvedValue({ confirmed: true, isDeleteNoteChecked: false });

        expect(await api.confirmAndRemoveColumn("Done")).toBe(true);

        expect(executeBulkActions).toHaveBeenCalledWith(
            [ "one" ], [ { name: "deleteLabel", labelName: "status" } ], { silent: true });
    });
});

describe("duplicating a card", () => {
    it("copies it into the board and puts the copy straight after the original", async () => {
        const { api, board } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);
        const post = vi.spyOn(server, "post")
            .mockResolvedValue({ branch: { branchId: "copyBranch" } } as never);
        // The global ws stub carries no such method, so it is put there the way bulk_action does.
        const wait = vi.fn(async () => {});
        ws.waitForMaxKnownEntityChangeId = wait as typeof ws.waitForMaxKnownEntityChangeId;

        await api.duplicateItem("card1", "card1Branch");

        expect(post).toHaveBeenCalledWith(`notes/card1/duplicate/${board.noteId}`);
        // Waited for, since the branch the server names has to be in froca before it can be moved.
        expect(wait).toHaveBeenCalled();
        expect(branches.moveAfterBranch).toHaveBeenCalledWith([ "copyBranch" ], "card1Branch");
    });
});

describe("what the board calls the field it groups by", () => {
    it("uses the promoted alias, and the stock word where the definition gives none", () => {
        const named = buildNote({
            title: "Board",
            "#collection": "",
            "#viewType": "board",
            "#label:status": "promoted,alias=Stage,single,select,options=To Do"
        });
        const bare = buildNote({
            title: "Board",
            "#collection": "",
            "#viewType": "board",
            "#label:status": "promoted,single,select,options=To Do"
        });

        expect(createApi({}, [], named).api.getStatusLabel()).toBe("Stage");
        // i18next is never initialised under test, so the fallback comes back as its key.
        expect(createApi({}, [], bare).api.getStatusLabel()).toBe("board_view.status-header");
    });

    /** Handed back by the parser for a bare , which names nothing. */
    it("falls back where the alias is empty", () => {
        const empty = buildNote({
            title: "Board",
            "#collection": "",
            "#viewType": "board",
            "#label:status": "promoted,alias=,single,select,options=To Do"
        });

        expect(createApi({}, [], empty).api.getStatusLabel()).toBe("board_view.status-header");
    });
});

describe("renaming a column to nothing", () => {
    /**
     * The value a column carries is what its cards are grouped by, so an empty name would write an
     * empty label over all of them and take the column with it.
     */
    it("leaves the column and its cards alone", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Done" ]
        );
        // A module mock outlives a test, so what earlier ones asked for is cleared first.
        vi.mocked(executeBulkActions).mockClear();

        await api.renameColumn("Done", "");
        await api.renameColumn("Done", "   ");

        expect(executeBulkActions).not.toHaveBeenCalled();
        expect(saved).toEqual([]);
    });
});

describe("collapsing a column", () => {
    it("stores the flag and clears it rather than storing it false", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] }, [ "To Do", "Done" ]);

        expect(api.isColumnCollapsed("To Do")).toBe(false);

        await api.setColumnCollapsed("To Do", true);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", collapsed: true }, { value: "Done" } ]);

        await api.setColumnCollapsed("To Do", false);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do" }, { value: "Done" } ]);
    });

    /** While a filter is on, the board holds the collapse state and nothing reaches the config. */
    it("answers to the volatile collapse in place of the stored flags while set", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", collapsed: true, keepCollapsed: true } ] },
            [ "To Do", "Done" ]);
        const setCollapsed = vi.fn();
        api.volatileCollapse = { isCollapsed: (column) => column === "Done", setCollapsed };

        expect(api.isColumnCollapsed("To Do")).toBe(false);
        expect(api.isColumnCollapsed("Done")).toBe(true);
        expect(api.isColumnKeptCollapsed("To Do")).toBe(false);

        await api.setColumnCollapsed("Done", false);
        await api.setAllColumnsCollapsed(true);
        expect(setCollapsed.mock.calls).toEqual([ [ "Done", false ], [ null, true ] ]);
        expect(saved).toEqual([]);

        api.volatileCollapse = undefined;
        expect(api.isColumnCollapsed("To Do")).toBe(true);
        expect(api.isColumnKeptCollapsed("To Do")).toBe(true);
    });

    /**
     * Turning it on collapses the column as well, so the entry does something the reader can see
     * rather than only deciding what the next open does.
     */
    it("collapses the column as it is set to stay collapsed", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        expect(api.isColumnKeptCollapsed("To Do")).toBe(false);

        await api.setColumnKeepCollapsed("To Do", true);
        expect(saved.at(-1)?.columns)
            .toEqual([ { value: "To Do", collapsed: true, keepCollapsed: true } ]);

        // Turning it off on a strip leaves the column collapsed: opening it is what clears that.
        await api.setColumnKeepCollapsed("To Do", false);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", collapsed: true } ]);

        // Turning it off on a column drawn open keeps it open, rather than letting the next
        // column selected shut it again.
        await api.setColumnKeepCollapsed("To Do", true);
        await api.setColumnKeepCollapsed("To Do", false, true);
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do" } ]);
    });

    /**
     * The inbox is drawn at the head of the board without ever having been written, so the first
     * thing picked for it is also the first entry it gets. Appended, that entry would send the
     * column to the end of the board, the stored order being what the board reads first.
     */
    it("writes a column with no entry yet where the board draws it", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ INBOX_COLUMN, "To Do", "Done" ]);

        await api.setColumnCollapsed(INBOX_COLUMN, true);
        expect(saved.at(-1)?.columns).toEqual([
            { value: INBOX_COLUMN, collapsed: true }, { value: "To Do" }, { value: "Done" }
        ]);

        // One drawn between two stored columns lands between them.
        const middle = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] },
            [ "To Do", "Doing", "Done" ]);
        await middle.api.setColumnCollapsed("Doing", true);
        expect(middle.saved.at(-1)?.columns?.map(column => column.value))
            .toEqual([ "To Do", "Doing", "Done" ]);
    });

    /** The icon goes in with the column, rather than as a second write and a second refresh. */
    it("stores a new column with the icon picked for it", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        await api.addNewColumn("Blocked", false, "bx bx-star");
        expect(saved.at(-1)?.columns).toEqual([
            { value: "To Do" },
            { value: "Blocked", icon: "bx bx-star", id: expect.any(String) }
        ]);

        await api.addNewColumn("Doing", true, "bx bx-run");
        expect(saved.at(-1)?.columns?.[0])
            .toEqual({ value: "Doing", icon: "bx bx-run", id: expect.any(String) });
    });

    /**
     * A column drawn from the definition or from a value its cards carry has no stored entry until
     * something is picked for it, and collapsing the board is what picks for all of them at once.
     */
    it("collapses every column, and opens the ones that are not kept collapsed", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", keepCollapsed: true } ] }, [ "To Do", "Done" ]);

        await api.setAllColumnsCollapsed(true);
        expect(saved.at(-1)?.columns).toEqual([
            { value: "To Do", keepCollapsed: true, collapsed: true },
            { value: "Done", collapsed: true }
        ]);

        await api.setAllColumnsCollapsed(false);
        expect(saved.at(-1)?.columns).toEqual([
            { value: "To Do", keepCollapsed: true, collapsed: true },
            { value: "Done" }
        ]);
    });

    it("leaves the column's other properties alone", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-star", limit: 3 } ] }, [ "To Do" ]);

        await api.setColumnCollapsed("To Do", true);

        expect(saved.at(-1)?.columns).toEqual([
            { value: "To Do", icon: "bx bx-star", limit: 3, collapsed: true }
        ]);
    });
});

describe("reordering around the inbox", () => {
    /** The inbox leads whatever the board groups by, so a reorder cannot take it off the front. */
    function boardWithInbox() {
        return createApi(
            { columns: [ { value: "" }, { value: "To Do" }, { value: "Done" } ] },
            [ "", "To Do", "Done" ]
        );
    }

    it("refuses to carry the inbox off the front", () => {
        const { api, saved } = boardWithInbox();

        expect(api.reorderColumn(0, 2)).toBeUndefined();
        expect(saved).toEqual([]);
    });

    it("refuses to place another column in front of it", () => {
        const { api, saved } = boardWithInbox();

        expect(api.reorderColumn(2, 0)).toBeUndefined();
        expect(saved).toEqual([]);
    });

    it("leaves the columns behind it free to move among themselves", () => {
        const { api, saved } = boardWithInbox();

        api.reorderColumn(2, 1);

        expect(saved.at(-1)?.columns)
            .toEqual([ { value: "" }, { value: "Done" }, { value: "To Do" } ]);
    });
});

describe("reordering columns the board is not showing all of", () => {
    /**
     * A column the config keeps but the board does not show, such as a disabled inbox, is missing
     * from the list the reorder counts in. It is kept rather than dropped or moved to the end.
     */
    it("keeps a stored column the render list does not carry", () => {
        const { api, saved } = createApi(
            { columns: [
                { value: "", icon: "bx bx-inbox" }, { value: "To Do" }, { value: "Done" }
            ] },
            [ "To Do", "Done" ]
        );

        // "Done" before "To Do", counted among the two the board shows.
        api.reorderColumn(1, 0);

        expect(saved.at(-1)?.columns).toEqual([
            { value: "", icon: "bx bx-inbox" },
            { value: "Done" },
            { value: "To Do" }
        ]);
    });

    /**
     * The hidden column follows the same column it followed before. Reinserting it at the index it
     * held in the config would place it between whichever columns the move left there.
     */
    it("keeps a hidden column beside the column it followed", () => {
        const { api, saved } = createApi(
            { columns: [
                { value: "To Do" }, { value: "" }, { value: "Done" }
            ] },
            [ "To Do", "Done" ]
        );

        // "Done" before "To Do", counted among the two the board shows.
        api.reorderColumn(1, 0);

        expect(saved.at(-1)?.columns).toEqual([
            { value: "Done" },
            { value: "To Do" },
            { value: "" }
        ]);
    });

    it("keeps a run of hidden columns in order behind the same column", () => {
        const { api, saved } = createApi(
            { columns: [
                { value: "To Do" }, { value: "" }, { value: "Archived" }, { value: "Done" }
            ] },
            [ "To Do", "Done" ]
        );

        api.reorderColumn(1, 0);

        expect(saved.at(-1)?.columns).toEqual([
            { value: "Done" },
            { value: "To Do" },
            { value: "" },
            { value: "Archived" }
        ]);
    });
});

describe("the icon the inbox column wears", () => {
    it("is an inbox until one is picked for it", () => {
        const { api } = createApi(
            { columns: [ { value: "" }, { value: "To Do" } ] }, [ "", "To Do" ]);

        expect(api.getColumnIcon("")).toBe("bx bxs-inbox");
        // Every other column keeps the stock one.
        expect(api.getColumnIcon("To Do")).toBe(DEFAULT_COLUMN_ICON);
    });

    it("gives way to the one picked for it", () => {
        const { api } = createApi(
            { columns: [ { value: "", icon: "bx bx-star" } ] }, [ "" ]);

        expect(api.getColumnIcon("")).toBe("bx bx-star");
    });
});

describe("renaming a column that names itself", () => {
    /** The inbox stands for the cards carrying no value, so its name is its own, not theirs. */
    it("writes the inbox a name of its own and leaves its cards alone", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "", icon: "bx bxs-inbox" }, { value: "To Do" } ] },
            [ "", "To Do" ]
        );
        vi.mocked(executeBulkActions).mockClear();

        await api.setColumnTitle("", "Unsorted");

        expect(saved.at(-1)?.columns).toEqual([
            { value: "", icon: "bx bxs-inbox", displayName: "Unsorted" },
            { value: "To Do" }
        ]);
        expect(api.getColumnTitle("")).toBe("Unsorted");
        // Its cards carry no value, so there is none to write across them.
        expect(executeBulkActions).not.toHaveBeenCalled();
    });

    it("renames any other column by the value its cards carry", async () => {
        const { api } = createApi(
            { columns: [ { value: "" }, { value: "To Do" } ] }, [ "", "To Do" ]);
        const put = vi.spyOn(server, "put").mockResolvedValue(undefined);

        await api.setColumnTitle("To Do", "Doing");

        expect(put).toHaveBeenCalledWith(expect.stringMatching(/board\/rename-column$/),
            expect.objectContaining({ oldValue: "To Do", newValue: "Doing" }));
    });

    it("leaves either kind alone when given nothing", async () => {
        const { api, saved } = createApi({ columns: [ { value: "" } ] }, [ "" ]);
        vi.mocked(executeBulkActions).mockClear();

        await api.setColumnTitle("", "   ");

        expect(saved).toEqual([]);
        expect(api.getColumnTitle("")).toBe("board_view.inbox");
    });
});

describe("renaming a column to a name already taken", () => {
    /**
     * A column is identified by the name its cards carry, so writing another column's name over it
     * would merge the two. The rename is refused and reported instead.
     */
    it("refuses the rename, says so and leaves both columns alone", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] }, [ "To Do", "Done" ]);
        const put = vi.spyOn(server, "put").mockResolvedValue(undefined);
        const message = vi.spyOn(toast, "showMessage").mockReturnValue(undefined);

        expect(await api.setColumnTitle("To Do", "Done")).toBe(false);

        expect(message).toHaveBeenCalledWith(
            "board_view.column-name-taken", undefined, "bx bx-duplicate");
        expect(put).not.toHaveBeenCalled();
        expect(saved).toEqual([]);
    });

    /**
     * The name a column is known by, not only the value its cards carry: the inbox has no value
     * and is named by `displayName`, so a second column under that name reads as a duplicate.
     */
    it("counts a column with no cards yet, and the name the inbox goes by", async () => {
        const { api, saved } = createApi(
            {
                columns: [
                    { value: "", displayName: "Unsorted" },
                    { value: "To Do" },
                    { value: "Done" }
                ]
            },
            // "Done" is stored but holds no cards, so the board does not derive it.
            [ "", "To Do" ]
        );
        vi.spyOn(server, "put").mockResolvedValue(undefined);
        vi.spyOn(toast, "showMessage").mockReturnValue(undefined);

        expect(await api.setColumnTitle("To Do", "Done")).toBe(false);
        expect(await api.setColumnTitle("To Do", "Unsorted")).toBe(false);
        expect(await api.setColumnTitle("", "Done")).toBe(false);
        expect(saved).toEqual([]);
    });

    it("takes a free name, and a column keeping the one it has", async () => {
        const { api } = createApi(
            { columns: [ { value: "To Do" }, { value: "Done" } ] }, [ "To Do", "Done" ]);
        const put = vi.spyOn(server, "put").mockResolvedValue(undefined);

        await api.setColumnTitle("To Do", "Doing");
        await api.setColumnTitle("Done", "Done");

        expect(put).toHaveBeenCalledTimes(2);
    });
});

describe("filing a card under the inbox", () => {
    /**
     * Landing in the inbox means carrying no value at all. A relation the card takes from elsewhere
     * would still point somewhere once the owned one goes, so the card would arrive in that column
     * rather than the inbox: it is refused and said so, instead of moved somewhere unasked.
     */
    it("refuses a relation card that would still point somewhere", async () => {
        const board = buildNote({
            title: "Board",
            "~status(inheritable)": "root",
            children: [ { title: "Card", "~status": "root" } ]
        });
        const { api } = createApi({}, [], board, "~status");
        const removeRelation = vi.spyOn(attributes, "removeOwnedRelationByName")
            .mockResolvedValue(true);
        const message = vi.spyOn(toast, "showMessage").mockReturnValue(undefined);

        await api.changeColumn(board.getChildNoteIds()[0], "");

        expect(message).toHaveBeenCalledWith("board_view.inherited-column", 3000);
        expect(removeRelation).not.toHaveBeenCalled();
    });

    /** Taking the card off the board is a lesser thing to ask, and still takes what it owns. */
    it("still removes what such a card owns when it is taken off the board", async () => {
        const board = buildNote({
            title: "Board",
            "~status(inheritable)": "root",
            children: [ { title: "Card", "~status": "root" } ]
        });
        const { api } = createApi({}, [], board, "~status");
        const removeRelation = vi.spyOn(attributes, "removeOwnedRelationByName")
            .mockResolvedValue(true);

        await api.removeFromBoard([ board.getChildNoteIds()[0] ]);

        expect(removeRelation).toHaveBeenCalled();
    });
});

describe("the limit set on a column", () => {
    /**
     * The inbox takes every card without a grouping value, however many that is. A limit stored
     * for it by an older board is read as none.
     */
    it("reads no limit for the inbox and writes none to it", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "", limit: 2 }, { value: "To Do", limit: 3 } ] },
            [ "", "To Do" ]);

        expect(api.getColumnLimit("")).toBeUndefined();
        expect(api.getColumnLimit("To Do")).toBe(3);

        await api.setColumnLimit("", 5);

        expect(saved).toHaveLength(0);
    });
});

describe("the promoted attributes a card shows", () => {
    /** A board defining two promoted labels, which is what the cards can show. */
    function boardWithAttributes() {
        return buildNote({
            title: "Board",
            "#label:dueDate(inheritable)": "promoted,single,date",
            "#label:owner(inheritable)": "promoted,single,text"
        });
    }

    /**
     * A board is usually given `#hidePromotedAttributes` so its own title row stays clear, and it
     * groups by a label its cards draw as columns rather than as a value.
     */
    it("lists what the cards can draw, whatever the board hides on itself", () => {
        const board = buildNote({
            title: "Board",
            "#hidePromotedAttributes": "",
            "#label:status(inheritable)": "promoted,single,text",
            "#label:dueDate(inheritable)": "promoted,single,date",
            "#label:internal(inheritable)": "single,text"
        });
        const { api } = createApi({}, [], board);

        // The label it groups by is drawn as a column, and an unpromoted one is still drawn.
        expect(api.getVisiblePromotedAttributeNames()).toEqual([ "dueDate", "internal" ]);
    });

    it("shows every one of them until the reader arranges them", () => {
        const { api } = createApi({}, [], boardWithAttributes());

        expect(api.getVisiblePromotedAttributeNames()).toEqual([ "dueDate", "owner" ]);
        expect(api.getStoredPromotedAttributes()).toBeUndefined();
    });

    it("follows the stored order, and leaves out what is hidden", () => {
        const stored = [ { name: "owner" }, { name: "dueDate", hidden: true } ];
        const { api } = createApi({ promotedAttributes: stored }, [], boardWithAttributes());

        expect(api.getVisiblePromotedAttributeNames()).toEqual([ "owner" ]);
        expect(api.getPromotedAttributes().map(attribute => attribute.name))
            .toEqual([ "owner", "dueDate" ]);
        expect(api.getStoredPromotedAttributes()).toBe(stored);
    });

    /** A card shows attributes defined by its template, so `getPromotedAttributes()` lists them. */
    it("lists what the cards define through another note, after the board's own", () => {
        buildNote({
            id: "projectTemplate",
            title: "Project",
            "#label:project(inheritable)": "promoted,single,color",
            "#label:owner(inheritable)": "promoted,single,relation"
        });
        const task = buildNote({ title: "Task", "~template": "projectTemplate" });
        // `buildNote()` caches only the owned attributes. Deleting the entry makes
        // `getAttributes()` rebuild it, including the template's attributes.
        delete noteAttributeCache.attributes[task.noteId];
        const plain = buildNote({ title: "Plain" });
        const byColumn: ColumnMap = new Map([ [ "To Do", [
            { note: task, branch: { branchId: "b_task" } as FBranch },
            { note: plain, branch: { branchId: "b_plain" } as FBranch }
        ] ] ]);
        const { api } = createApi({}, [ "To Do" ], boardWithAttributes(), "status", byColumn);

        expect(api.getVisiblePromotedAttributeNames()).toEqual([ "dueDate", "owner", "project" ]);
        const [ , owner, project ] = api.getPromotedAttributes();
        // The board and the template both define `owner`; the board's definition wins.
        expect(owner).toMatchObject({ labelType: "text", isDefinedByItems: false });
        expect(project).toMatchObject({ labelType: "color", isDefinedByItems: true });
    });

    it("stores the whole list, an attribute the board has dropped along with it", async () => {
        const { api, saved } = createApi(
            { promotedAttributes: [ { name: "gone" } ] }, [], boardWithAttributes());

        await api.setPromotedAttributes(api.getPromotedAttributes().map(
            attribute => attribute.name === "owner" ? { ...attribute, hidden: true } : attribute));

        expect(saved.at(-1)?.promotedAttributes)
            .toEqual([ { name: "dueDate" }, { name: "owner", hidden: true } ]);
    });
});

describe("deleting the attribute of a grouping", () => {
    /**
     * Left in `board.json`, the columns of a deleted grouping are written back into a new
     * definition by `syncColumnsToDefinition` once the board groups by it again.
     */
    it("empties the stored columns of the grouping once deleted, leaving the rest", async () => {
        const { api, saved } = createApi({
            columns: [ { value: "To Do" }, { value: "Done" } ],
            testViewColumns: [ { value: "A" } ],
            filterQuery: "#urgent"
        }, [ "A" ], undefined, "test");
        const savedDuringDeletion: number[] = [];

        await api.deleteGrouping("status", async () => { savedDuringDeletion.push(saved.length); });

        expect(savedDuringDeletion).toEqual([ 0 ]);
        expect(saved).toEqual([
            { columns: [], testViewColumns: [ { value: "A" } ], filterQuery: "#urgent" }
        ]);
    });

    /**
     * A refresh that lands while the definition is being deleted still reads the stored columns,
     * and would write them into a new definition; `pending.inFlight` holds its writes back.
     */
    it("counts as a write on the board while the definition is deleted", async () => {
        const { api, pending, saved } = createApi(
            { columns: [ { value: "To Do" } ] }, [ "To Do" ]);
        let inFlightDuringDeletion = 0;

        await api.deleteGrouping("status", async () => {
            inFlightDuringDeletion = pending.inFlight;
        });

        expect(inFlightDuringDeletion).toBe(1);
        expect(saved).toEqual([ { columns: [] } ]);
        expect(pending.inFlight).toBe(0);
    });

    /**
     * A refresh that started during the deletion reads the old columns, and can resolve after
     * `pending.inFlight` drops back to 0. `hasStoredSince()` tells the board not to write them.
     */
    it("reports the config read before the deletion as replaced, until the board draws the new one",
        async () => {
            const config = { columns: [ { value: "To Do" } ] };
            const { api, board, saved } = createApi(config, [ "To Do" ]);
            expect(api.hasStoredSince(config)).toBe(false);

            await api.deleteGrouping("status", async () => {});
            expect(api.hasStoredSince(config)).toBe(true);

            const [ stored ] = saved;
            api.update(new Map(), [], board, "status", stored, () => {}, () => {});
            expect(api.hasStoredSince(stored)).toBe(false);
        });

    it("keeps the columns of a grouping whose deletion failed, and stops counting it", async () => {
        const { api, pending, saved } = createApi(
            { columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        await expect(api.deleteGrouping("status", async () => { throw new Error("offline"); }))
            .rejects.toThrow("offline");

        expect(saved).toEqual([]);
        expect(pending.inFlight).toBe(0);
    });

    it("writes nothing for a grouping that stores no columns", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        await api.deleteGrouping("priority", async () => {});

        expect(saved).toEqual([]);
    });
});

describe("how a column orders its cards", () => {
    /** Storing nothing is what takes the board's order, so a fresh column reads as taking it. */
    it("reads a column nobody has sorted as taking the board's order", () => {
        const { api } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        expect(api.getColumnSort("To Do")).toEqual({ orderBy: "default", isDescending: false });
        expect(api.getColumnSort("Unwritten")).toEqual({ orderBy: "default", isDescending: false });
    });

    it("reads a column stored as manual as the order the user arranged", () => {
        const { api } = createApi(
            { columns: [ { value: "To Do", orderBy: "manual" } ] },
            [ "To Do" ],
            buildNote({ title: "Board", "#board:sortColumns": "title" }));

        expect(api.getColumnSort("To Do").orderBy).toBeUndefined();
        expect(api.getEffectiveColumnSort("To Do").orderBy).toBeUndefined();
        expect(api.isColumnSorted("To Do")).toBe(false);
    });

    it("stores what a column sorts by, and writes the manual order out", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-list-ul" }, { value: "Done" } ] },
            [ "To Do", "Done" ]);

        await api.setColumnSort("To Do", "attr:dueDate");
        expect(saved.at(-1)?.columns).toEqual([
            { value: "To Do", icon: "bx bx-list-ul", orderBy: "attr:dueDate" },
            { value: "Done" }
        ]);
        expect(api.getColumnSort("To Do"))
            .toEqual({ orderBy: "attr:dueDate", isDescending: false });

        // Written rather than dropped: a column storing nothing takes the board's order.
        await api.setColumnSort("To Do", undefined);
        expect(saved.at(-1)?.columns).toStrictEqual([
            { value: "To Do", icon: "bx bx-list-ul", orderBy: "manual" },
            { value: "Done" }
        ]);
        expect(api.getColumnSort("To Do").orderBy).toBeUndefined();
    });

    it("stores the direction and clears it rather than storing it false", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        await api.setColumnSort("To Do", "title");
        await api.setColumnSortDirection("To Do", true);
        expect(saved.at(-1)?.columns)
            .toEqual([ { value: "To Do", orderBy: "title", descendingOrder: true } ]);
        expect(api.getColumnSort("To Do")).toEqual({ orderBy: "title", isDescending: true });

        await api.setColumnSortDirection("To Do", false);
        expect(saved.at(-1)?.columns).toStrictEqual([ { value: "To Do", orderBy: "title" } ]);
    });

    it("keeps the direction while the key changes, and reads a stale key as manual", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", orderBy: "creationDate", descendingOrder: true } ] },
            [ "To Do" ]);

        expect(api.getColumnSort("To Do"))
            .toEqual({ orderBy: "creationDate", isDescending: true });

        await api.setColumnSort("To Do", "title");
        expect(saved.at(-1)?.columns)
            .toEqual([ { value: "To Do", orderBy: "title", descendingOrder: true } ]);

        // A key written by a newer version, or by hand, leaves the column in the manual order.
        const stale = createApi(
            { columns: [ { value: "To Do", orderBy: "dateModified" } ] }, [ "To Do" ]);
        expect(stale.api.getColumnSort("To Do").orderBy).toBeUndefined();
    });

    it("writes an entry for a column that has none yet, where the board draws it", async () => {
        const { api, saved } = createApi(
            { columns: [ { value: "To Do" } ] }, [ "To Do", "Doing", "Done" ]);

        await api.setColumnSort("Doing", "title");
        expect(saved.at(-1)?.columns)
            .toEqual([ { value: "To Do" }, { value: "Doing", orderBy: "title" } ]);
    });
});

describe("a column that takes the board's order", () => {
    /** A board holding an order of its own, which a column can be stored as taking. */
    function boardSorting() {
        return buildNote({
            title: "Board", "#board:sortColumns": "attr:dueDate", "#board:sortColumnsDescending": ""
        });
    }

    it("keeps the stored value apart from the order the column is drawn in", () => {
        const { api } = createApi(
            { columns: [ { value: "To Do", orderBy: "default" } ] }, [ "To Do" ], boardSorting());

        // What the menu marks, and what the cards are ordered by.
        expect(api.getColumnSort("To Do"))
            .toEqual({ orderBy: "default", isDescending: false });
        expect(api.getEffectiveColumnSort("To Do"))
            .toEqual({ orderBy: "attr:dueDate", isDescending: true });
        expect(api.isColumnSorted("To Do")).toBe(true);
    });

    it("keeps the manual order while the board holds none", () => {
        const { api } = createApi(
            { columns: [ { value: "To Do", orderBy: "default" } ] }, [ "To Do" ]);

        expect(api.getColumnSort("To Do").orderBy).toBe("default");
        expect(api.getEffectiveColumnSort("To Do").orderBy).toBeUndefined();
        expect(api.isColumnSorted("To Do")).toBe(false);
    });

    it("leaves a column with an order of its own alone", () => {
        const { api } = createApi(
            { columns: [ { value: "To Do", orderBy: "title", descendingOrder: true } ] },
            [ "To Do" ],
            boardSorting());

        expect(api.getEffectiveColumnSort("To Do"))
            .toEqual({ orderBy: "title", isDescending: true });
    });

    it("stores the value a pick names", async () => {
        const { api, saved } = createApi({ columns: [ { value: "To Do" } ] }, [ "To Do" ]);

        await api.setColumnSort("To Do", "default");
        expect(saved.at(-1)?.columns).toEqual([ { value: "To Do", orderBy: "default" } ]);
    });
});

describe("the order the board offers its columns", () => {
    beforeEach(() => vi.restoreAllMocks());

    it("reads the labels the board carries, and a board with none as the manual order", () => {
        const plain = createApi({}, []);
        expect(plain.api.getDefaultSort()).toEqual({ orderBy: undefined, isDescending: false });

        const { api } = createApi({}, [], buildNote({
            title: "Board",
            "#board:sortColumns": "attr:dueDate",
            "#board:sortColumnsDescending": ""
        }));
        expect(api.getDefaultSort()).toEqual({ orderBy: "attr:dueDate", isDescending: true });
    });

    // A key written by hand, or by a newer version, leaves the board offering the manual order.
    it("reads a key it does not know as the manual order", () => {
        const { api } = createApi({}, [], buildNote({
            title: "Board", "#board:sortColumns": "dateModified"
        }));

        expect(api.getDefaultSort().orderBy).toBeUndefined();
    });

    it("writes what is picked to the board note, and takes the label off for the manual order",
        async () => {
            const setAttribute = vi.spyOn(attributes, "setAttribute")
                .mockResolvedValue(undefined as never);
            const setBoolean = vi.spyOn(attributes, "setBooleanWithInheritance")
                .mockResolvedValue(undefined as never);
            const { api, board } = createApi({}, []);

            await api.setDefaultSort("title");
            expect(setAttribute).toHaveBeenCalledWith(board, "label", "board:sortColumns", "title");

            await api.setDefaultSort(undefined);
            expect(setAttribute).toHaveBeenLastCalledWith(board, "label", "board:sortColumns", null);

            await api.setDefaultSortDirection(true);
            expect(setBoolean).toHaveBeenCalledWith(board, "board:sortColumnsDescending", true);
        });

    it("puts every column back to the board's order, keeping what else each one holds", async () => {
        const { api, saved } = createApi(
            {
                columns: [
                    { value: "To Do", icon: "bx bx-list-ul", orderBy: "manual" },
                    { value: "Done", orderBy: "title", descendingOrder: true }
                ]
            },
            [ "To Do", "Doing", "Done" ]);

        await api.resetColumnSortsToDefault();

        // One write for the board. Strict, so the assertion catches a key stored as undefined
        // rather than dropped, and the column with no entry is left without one.
        expect(saved.length).toBe(1);
        expect(saved.at(-1)?.columns).toStrictEqual([
            { value: "To Do", icon: "bx bx-list-ul" },
            { value: "Done" }
        ]);
    });
});

/**
 * A sorted column places its own cards, so nothing writes a branch position for one. The branch
 * order is the order the reader arranged, which the column goes back to when it is sorted by hand
 * again.
 */
describe("moving a card into or inside a sorted column", () => {
    let setLabel: ReturnType<typeof vi.spyOn>;

    beforeEach(() => {
        vi.restoreAllMocks();
        setLabel = vi.spyOn(attributes, "setLabel").mockResolvedValue(undefined as never);
        vi.mocked(branches.moveBeforeBranch).mockClear();
        vi.mocked(branches.moveAfterBranch).mockClear();
    });

    function board(cards: Record<string, string[]>): ColumnMap {
        return new Map(Object.entries(cards).map(([ column, ids ]) => [
            column,
            ids.map((noteId) => {
                buildNote({ id: noteId, title: noteId });
                return {
                    note: froca.notes[noteId],
                    branch: { branchId: `b_${noteId}` } as FBranch
                };
            })
        ]));
    }

    function sortedApi(sortedColumns: string[]) {
        return createApi(
            {
                columns: [ "To Do", "Done" ].map(value => ({
                    value,
                    ...(sortedColumns.includes(value) ? { orderBy: "title" } : {})
                }))
            },
            [ "To Do", "Done" ],
            undefined,
            "status",
            board({ "To Do": [ "a1", "a2", "a3" ], Done: [ "b1", "b2" ] }));
    }

    it("writes the value alone when a card crosses into one", async () => {
        const { api } = sortedApi([ "Done" ]);

        await api.moveWithinBoard(
            [ { noteId: "a2", branchId: "b_a2" } ], "Done", 0);

        expect(setLabel).toHaveBeenCalledWith("a2", "status", "Done");
        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
        expect(branches.moveAfterBranch).not.toHaveBeenCalled();
    });

    it("writes nothing at all for a move inside one", async () => {
        const { api } = sortedApi([ "To Do" ]);

        await api.moveWithinBoard(
            [ { noteId: "a1", branchId: "b_a1" } ], "To Do", 2);

        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
        expect(branches.moveAfterBranch).not.toHaveBeenCalled();
    });

    it("still places a card in a column left in the manual order", async () => {
        const { api } = sortedApi([ "To Do" ]);

        await api.moveWithinBoard(
            [ { noteId: "a2", branchId: "b_a2" } ], "Done", 0);

        expect(setLabel).toHaveBeenCalledWith("a2", "status", "Done");
        expect(branches.moveBeforeBranch).toHaveBeenCalledWith([ "b_a2" ], "b_b1");
    });

    it("sends a card across to a sorted column by value alone", async () => {
        const { api } = sortedApi([ "Done" ]);

        await api.moveToColumnEnd([ { noteId: "a1", branchId: "b_a1" } ], "Done");

        expect(setLabel).toHaveBeenCalledWith("a1", "status", "Done");
        expect(branches.moveAfterBranch).not.toHaveBeenCalled();
    });

    it("refuses to send a card to the head of a sorted column", async () => {
        const { api } = sortedApi([ "To Do" ]);

        await api.moveToColumnStart("a3", "b_a3", "To Do");

        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
    });

    it("answers which columns order their own cards", () => {
        const { api } = sortedApi([ "Done" ]);

        expect(api.isColumnSorted("Done")).toBe(true);
        expect(api.isColumnSorted("To Do")).toBe(false);
    });
});

describe("a selection of cards", () => {
    beforeEach(() => {
        vi.restoreAllMocks();
        vi.spyOn(server, "put").mockResolvedValue(undefined);
        vi.mocked(branches.moveBeforeBranch).mockClear();
        vi.mocked(branches.moveAfterBranch).mockClear();
    });

    /** A board of four cards, three under "Done" and one under "To Do". */
    function createBoard(sorts?: BoardViewData) {
        const board = buildNote({
            title: "Board",
            children: [
                { title: "First", "#status": "Done" },
                { title: "Second", "#status": "Done" },
                { title: "Third", "#status": "Done" },
                { title: "Spare", "#status": "To Do" }
            ]
        });

        const items = board.getChildBranches().flatMap(branch => {
            const note = froca.getNoteFromCache(branch.noteId);
            return note ? [ { branch, note } ] : [];
        });
        const byColumn: ColumnMap = new Map([
            [ "To Do", [ items[3] ] ],
            [ "Done", items.slice(0, 3) ]
        ]);

        return {
            ...createApi(sorts ?? {}, [ "To Do", "Done" ], board, "status", byColumn),
            items
        };
    }

    const ids = (items: ColumnItem[]) => items.map((item) => item.note.noteId);
    const branchIds = (items: ColumnItem[]) => items.map((item) => item.branch.branchId);

    it("names the cards a column draws, in the order it draws them", () => {
        const { api, items } = createBoard();

        expect(api.getColumnNoteIds("Done")).toEqual(ids(items.slice(0, 3)));
        expect(api.getColumnNoteIds("Nowhere")).toEqual([]);
    });

    it("says which column a card stands in, and nothing for one it is not drawing", () => {
        const { api, items } = createBoard();

        expect(api.getCardColumn(items[0].note.noteId)).toBe("Done");
        expect(api.getCardColumn(items[3].note.noteId)).toBe("To Do");
        expect(api.getCardColumn("elsewhere")).toBeUndefined();
    });

    /**
     * A selection kept from before a refresh can name a card the board has stopped drawing, which
     * is left out rather than making a command act on something that is no longer there.
     */
    it("resolves a selection in board order, leaving out what it no longer holds", () => {
        const { api, items } = createBoard();
        const asked = new Set([ items[2].note.noteId, items[3].note.noteId, "gone" ]);

        expect(ids(api.getCards(asked))).toEqual([ items[3].note.noteId, items[2].note.noteId ]);
    });

    it("files every card under the column and places them before the card dropped on", async () => {
        const { api, items } = createBoard();
        const moved = [ items[3], items[0] ];

        await api.moveWithinBoard(
            moved.map((item) => ({ noteId: item.note.noteId, branchId: item.branch.branchId })),
            "Done", 2);

        // Each card's grouping value is written, then one placement carries the whole set.
        expect(server.put).toHaveBeenCalledWith(
            `notes/${items[3].note.noteId}/set-attribute`,
            { type: "label", name: "status", value: "Done", isInheritable: false }, undefined);
        // Counted among the cards as drawn: `First` is moving and stands above the place, so the
        // set lands before `Third` rather than before `Second`.
        expect(branches.moveBeforeBranch)
            .toHaveBeenCalledWith(branchIds(moved), items[2].branch.branchId);
    });

    it("places a set dropped past the last card after the one staying at the end", async () => {
        const { api, items } = createBoard();
        const moved = [ items[3] ];

        await api.moveWithinBoard(
            moved.map((item) => ({ noteId: item.note.noteId, branchId: item.branch.branchId })),
            "Done", 3);

        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
        expect(branches.moveAfterBranch)
            .toHaveBeenCalledWith(branchIds(moved), items[2].branch.branchId);
    });

    /** A sorted column decides where its own cards go, so nothing is written against one. */
    it("writes no placement into a column that sorts itself", async () => {
        const { api, items } = createBoard(
            { columns: [ { value: "Done", orderBy: "title" } ] });
        const moved = [ items[3] ];

        await api.moveWithinBoard(
            moved.map((item) => ({ noteId: item.note.noteId, branchId: item.branch.branchId })),
            "Done", 0);

        expect(server.put).toHaveBeenCalledWith(
            `notes/${items[3].note.noteId}/set-attribute`,
            { type: "label", name: "status", value: "Done", isInheritable: false }, undefined);
        expect(branches.moveBeforeBranch).not.toHaveBeenCalled();
        expect(branches.moveAfterBranch).not.toHaveBeenCalled();
    });
});

describe("how wide the board draws its columns", () => {
    afterEach(() => vi.restoreAllMocks());

    it("reads the label, falling back to the default for a width it does not offer", () => {
        const width = (label?: string) => createApi(
            {}, [], buildNote(label ? { title: "Board", "#board:columnWidth": label }
                : { title: "Board" })).api.columnWidth;

        expect(width()).toBe("narrow");
        expect(width("medium")).toBe("medium");
        expect(width("wide")).toBe("wide");
        expect(width("enormous")).toBe("narrow");
    });

    it("writes the label for a width other than the default", async () => {
        const board = buildNote({ title: "Board" });
        const setLabel = vi.spyOn(attributes, "setLabel").mockResolvedValue(undefined);
        const { api } = createApi({}, [], board);

        await api.setColumnWidth("wide");

        expect(setLabel).toHaveBeenCalledWith(board.noteId, "board:columnWidth", "wide");
    });

    /** Kept tidy: a board drawn at the default width carries no label for it at all. */
    it("takes the label off for the default width", async () => {
        const board = buildNote({ title: "Board", "#board:columnWidth": "wide" });
        const setLabel = vi.spyOn(attributes, "setLabel").mockResolvedValue(undefined);
        const removeLabel = vi.spyOn(attributes, "removeOwnedLabelByName")
            .mockResolvedValue(true);
        const { api } = createApi({}, [], board);

        await api.setColumnWidth("narrow");

        expect(removeLabel).toHaveBeenCalledWith(board, "board:columnWidth");
        expect(setLabel).not.toHaveBeenCalled();
    });

    /** Dropping its own label there would hand the board the inherited width straight back. */
    it("writes the default out where the board inherits another width", async () => {
        const parent = buildNote({
            title: "Parent",
            "#board:columnWidth(inheritable)": "wide",
            children: [ { title: "Board" } ]
        });
        const board = froca.getNoteFromCache(parent.getChildNoteIds()[0]);
        if (!board) throw new Error("expected the board to be in froca");
        const setLabel = vi.spyOn(attributes, "setLabel").mockResolvedValue(undefined);
        const removeLabel = vi.spyOn(attributes, "removeOwnedLabelByName")
            .mockResolvedValue(true);
        const { api } = createApi({}, [], board);

        expect(api.columnWidth).toBe("wide");

        await api.setColumnWidth("narrow");

        expect(setLabel).toHaveBeenCalledWith(board.noteId, "board:columnWidth", "narrow");
        expect(removeLabel).not.toHaveBeenCalled();
    });
});

describe("the columns as the right pane lists them", () => {
    it("names each column, gives it its icon and counts the cards it holds", () => {
        const board = buildNote({ title: "Board" });
        const cards = new Map([
            [ "", [ { note: { noteId: "a" } }, { note: { noteId: "b" } } ] ],
            [ "To Do", [ { note: { noteId: "c" } } ] ]
        ]) as unknown as ColumnMap;
        const { api } = createApi(
            {
                columns: [
                    { value: "", displayName: "Unsorted" },
                    { value: "To Do", icon: "bx bx-star" },
                    { value: "Done" }
                ]
            },
            [ "", "To Do", "Done" ], board, "status", cards);

        expect(api.getColumnOutline([ "", "To Do", "Done" ])).toEqual([
            { value: "", title: "Unsorted", icon: "bx bxs-inbox", count: 2 },
            { value: "To Do", title: "To Do", icon: "bx bx-star", count: 1 },
            // A column the board draws no cards for still stands, and counts none.
            { value: "Done", title: "Done", icon: DEFAULT_COLUMN_ICON, count: 0 }
        ]);
    });

    /** A relation board keys its columns by note id, which says nothing to a reader on its own. */
    it("names a relation board's columns by the notes they point at", () => {
        const target = buildNote({ title: "Alice", "#iconClass": "bx bx-user" });
        const board = buildNote({ title: "Board" });
        const { api } = createApi({}, [ "", target.noteId ], board, "~assignee");

        expect(api.getColumnOutline([ "", target.noteId, "missing" ])).toEqual([
            { value: "", title: "board_view.inbox", icon: "bx bxs-inbox", count: 0 },
            // The note's own icon, as `FNote` gives it, class and all.
            { value: target.noteId, title: "Alice", icon: "tn-icon bx bx-user", count: 0 },
            // A note the cache has not got: the value is all there is to go on.
            { value: "missing", title: "missing", icon: DEFAULT_COLUMN_ICON, count: 0 }
        ]);
    });
});

describe("references to a board's columns and cards", () => {
    it("keeps the id a column already has, without asking the server", async () => {
        const put = vi.spyOn(server, "put");
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", id: "colTodo00001" } ] }, [ "To Do" ]);

        await expect(api.ensureColumnId("To Do")).resolves.toBe("colTodo00001");
        await expect(api.ensureColumnId("To Do")).resolves.toBe("colTodo00001");
        expect(put).not.toHaveBeenCalled();
        // Nothing to store, so the board is left alone.
        expect(saved).toEqual([]);
    });

    /**
     * A column drawn from the definition or from a value its cards carry has no stored entry at
     * all, so the first reference taken of it is what assigns one.
     *
     * The server reads and writes `board.json` in one request, so it decides: two clients copying a
     * reference to the same column at once are both answered with the id that arrived first.
     */
    it("asks the server to assign an id for a column that has none, and uses its answer",
        async () => {
            const board = buildNote({ title: "Board" });
            const put = vi.spyOn(server, "put")
                .mockResolvedValue({ id: "colOther0001", stored: true } as never);
            const { api, saved } = createApi(
                { columns: [ { value: "To Do", icon: "bx bx-list-ul" } ] }, [ "To Do" ], board);

            await expect(api.ensureColumnId("To Do")).resolves.toBe("colOther0001");
            expect(put).toHaveBeenCalledWith(
                `notes/${board.noteId}/board/column-id`,
                { groupBy: "status", value: "To Do", id: expect.any(String) });
            // The server owns the write, so nothing is stored from here.
            expect(saved).toEqual([]);

            // The id offered is a fresh one of the right length, and is not what came back.
            const offered = put.mock.calls.at(-1)?.[1] as { id: string };
            expect(offered.id).toHaveLength(COLUMN_ID_LENGTH);
            expect(offered.id).not.toBe("colOther0001");
        });

    it("names the grouping the column belongs to when asking for an id", async () => {
        const board = buildNote({ title: "Board" });
        const put = vi.spyOn(server, "put")
            .mockResolvedValue({ id: "colHigh00001", stored: true } as never);
        const { api } = createApi(
            { columns: [ { value: "To Do", id: "colTodo00001" } ] }, [ "High" ], board,
            "priority");

        await expect(api.ensureColumnId("High")).resolves.toBe("colHigh00001");
        expect(put).toHaveBeenCalledWith(`notes/${board.noteId}/board/column-id`,
            { groupBy: "priority", value: "High", id: expect.any(String) });
    });

    /**
     * The server leaves a configuration it cannot read as it stands, so that it can be repaired by
     * hand, and says it stored nothing. The board writes the id out with the rest of what it draws.
     */
    it("stores the id itself when the server reports it stored nothing", async () => {
        vi.spyOn(server, "put")
            .mockResolvedValue({ id: "colOther0001", stored: false } as never);
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-list-ul" } ] }, [ "To Do" ]);

        await expect(api.ensureColumnId("To Do")).resolves.toBe("colOther0001");
        expect(saved.at(-1)?.columns)
            .toEqual([ { value: "To Do", icon: "bx bx-list-ul", id: "colOther0001" } ]);
    });

    /** The link still works for as long as nothing else claims the column. */
    it("stores the id it generated when the server cannot be reached", async () => {
        vi.spyOn(console, "error").mockImplementation(() => {});
        vi.spyOn(server, "put").mockRejectedValue(new Error("offline"));
        const { api, saved } = createApi(
            { columns: [ { value: "To Do", icon: "bx bx-list-ul" } ] }, [ "To Do" ]);

        const id = await api.ensureColumnId("To Do");
        expect(id).toHaveLength(COLUMN_ID_LENGTH);
        expect(saved.at(-1)?.columns)
            .toEqual([ { value: "To Do", icon: "bx bx-list-ul", id } ]);
    });

    it("builds the links the menu copies, from the path the pane reached the board by",
        async () => {
            const board = buildNote({ title: "Board" });
            const { api } = createApi(
                {
                    columns: [
                        { value: "To Do", id: "colTodo00001", icon: "bx bx-star",
                            color: "#ff8800" },
                        { value: "Done", id: "colDone00001" }
                    ]
                },
                [ "To Do", "Done" ], board);
            api.noteContext = { notePath: `root/parent1234/${board.noteId}` } as NoteContext;

            const path = `root/parent1234/${board.noteId}`;
            await expect(api.getColumnReference("To Do")).resolves.toBe(
                `#${path}?column=colTodo00001&columnTitle=To%20Do&columnIcon=bx%20bx-star`
                + "&columnColor=%23ff8800");
            // A column carrying no colour of its own leaves the parameter out.
            await expect(api.getColumnReference("Done")).resolves.toBe(
                `#${path}?column=colDone00001&columnTitle=Done&columnIcon=bx%20bx-circle`);
            expect(api.getCardReference("card00000001")).toBe(`#${path}?card=card00000001`);
        });

    /**
     * A relation board titles its columns from the notes they point at, and that title is written
     * into the link permanently. The heading loads the note only after the board is interactive,
     * so a reference copied before then would carry the note id as the title.
     */
    it("loads a relation column's note before naming it", async () => {
        const target = buildNote({ title: "Alice", "#iconClass": "bx bx-user" });
        const board = buildNote({ title: "Board" });
        vi.spyOn(server, "put").mockResolvedValue({ id: "colAlice0001", stored: true } as never);
        const { api } = createApi({}, [ target.noteId ], board, "~assignee");

        // Not in the cache until it has been asked for, which is the state the board opens in.
        let isCached = false;
        vi.spyOn(froca, "getNoteFromCache").mockImplementation(
            (noteId) => (isCached && noteId === target.noteId ? target : null) as never);
        const getNote = vi.spyOn(froca, "getNote").mockImplementation(async () => {
            isCached = true;
            return target as never;
        });

        await expect(api.getColumnReference(target.noteId)).resolves.toBe(
            `#${board.noteId}?column=colAlice0001&columnTitle=Alice`
            + `&columnIcon=${encodeURIComponent("tn-icon bx bx-user")}`);
        expect(getNote).toHaveBeenCalledWith(target.noteId, true);
    });

    /** A board drawn outside a pane, such as in a note preview, still has itself to name. */
    it("falls back to the board's own id where the pane names no path", () => {
        const board = buildNote({ title: "Board" });
        const { api } = createApi({}, [], board);

        expect(api.getCardReference("card00000001"))
            .toBe(`#${board.noteId}?card=card00000001`);
    });
});