Skip to content

Build your personal knowledge base with Trilium Notes

75.8 KB
Raw Blame
import { BulkAction, type DefinitionObject, promotedAttributeDefinitionParser } from "@triliumnext/commons";

import appContext from "../../../components/app_context";
import type NoteContext from "../../../components/note_context";
import FNote from "../../../entities/fnote";
import attributes from "../../../services/attributes";
import branches from "../../../services/branches";
import cssClassManager from "../../../services/css_class_manager";
import dialog from "../../../services/dialog";
import froca from "../../../services/froca";
import { t } from "../../../services/i18n";
import note_create from "../../../services/note_create";
import {
    currentNoteTypeOption, type NoteTypeOption, resolveNoteTypeOptions
} from "../../../services/note_types";
import server from "../../../services/server";
import ws from "../../../services/ws";
import toast from "../../../services/toast";
import { offeredTemplateIds } from "../../react/TemplateDropdown";
import {
    type PromotedAttribute, resolvePromotedAttributes, storedPromotedAttributes,
    visiblePromotedAttributeNames
} from "../promoted_attributes";
import {
    DEFAULT_SORT, MANUAL_SORT, parseSortKey, parseStoredSortKey, type SortKey, type StoredSortKey
} from "../sorting";
import { BoardColumnData, BoardViewData } from ".";
import {
    type BoardStatusDefinition, canStoreColumnsInDefinition, COLUMN_WIDTH_LABEL, type ColumnWidth,
    DEFAULT_CARD_TEMPLATES, DEFAULT_COLUMN_ICON, DEFAULT_COLUMN_WIDTH, DEFAULT_GROUP_BY, INBOX_COLUMN,
    INBOX_COLUMN_ICON, parseColumnWidth
} from "./columns";
import { readColumns, writeColumns } from "./column_storage";
import { cardNotes, ColumnItem, ColumnMap } from "./data";
import {
    cardReference, ColumnReferenceLabel, columnReference, newColumnId, readColumnId
} from "./reference";
import { SORT_DESCENDING_LABEL, SORT_LABEL } from "./sort";

/** Which end of a column a new card is made at. */
export type CardPlacement = "top" | "bottom";

/** The relation a card carries to stand in for another note rather than open an editor of its own. */
export const CARD_REDIRECT_RELATION = "board:cardRedirectTo";

/** The previous name of the relation above. `openCard` falls back to it. */
export const CARD_REDIRECT_RELATION_LEGACY = "boardCardRedirectTo";

/** One write's claim on a column, held until that write lands or is taken back. */
interface ColumnClaim {
    /**
     * Stands for the write that made the claim, since what two writes leave behind need not tell
     * them apart: one board read twice over can ask for the very same rename or deletion.
     */
    owner: object;
    value: string | undefined;
    /** Whether a record is left at all, as against the column being left to read as it stands. */
    records: boolean;
}

/**
 * The collapse state the board draws while a filter narrows it, in place of the stored flags.
 *
 * A column without matches is drawn as a strip so the results are read at a glance, and what the
 * reader opens or closes meanwhile is held by the board rather than written: clearing the filter
 * brings the stored state back.
 */
export interface VolatileCollapse {
    isCollapsed(column: string): boolean;
    /** Opens or closes one column, or every column when given `null`. */
    setCollapsed(column: string | null, collapsed: boolean): void;
}

/**
 * The columns a board has in flight.
 *
 * Every write claims the columns it touches, and `renames` is what the last claim on each says.
 * Claims are kept rather than a value and its predecessor because writes finish in any order: one
 * taken back from under another leaves the one above it standing, and a column with no claims left
 * has no record at all, whichever of the two failed first.
 */
export interface PendingColumnWrites {
    renames: Map<string, string | undefined>;
    claims: Map<string, ColumnClaim[]>;
    /**
     * How many writes are running on the board right now.
     *
     * Counted apart from the records because a record outlives its write: it is given up only once
     * no source names the old value, and a definition the board cannot write keeps naming it for
     * good. What must not be put on disk is an answer no write has given yet, which is this.
     */
    inFlight: number;
}

/** Drops the record of a column the board now reads the same way from every source. */
export function settleColumn(pending: PendingColumnWrites, column: string) {
    pending.renames.delete(column);
    pending.claims.delete(column);
}

/**
 * The writes in flight on each board, by the note it is and the label it groups by.
 *
 * Shared by every view of one board rather than held per view, because what a record stands in for
 * is shared too: the notes, the definition and the attachment. A second tab open on the same board
 * refreshes on the same entity changes, and one that knew nothing of a deletion under way would
 * resolve the column from whichever source still carries it and write it back.
 */
const pendingWritesByBoard = new Map<string, PendingColumnWrites>();

/**
 * The record every view of one board writes into, made on first use and kept for good.
 *
 * Never dropped, however empty: a view is handed the record once, when it first draws a board, and
 * holds that object for as long as it is mounted. Dropping an empty one would hand the next view a
 * different record, and the two would stop hearing about each other's writes. What is left behind
 * is one string and two empty maps per board opened.
 */
export function getPendingWrites(board: string) {
    const existing = pendingWritesByBoard.get(board);
    if (existing) {
        return existing;
    }

    const writes: PendingColumnWrites = { renames: new Map(), claims: new Map(), inFlight: 0 };
    pendingWritesByBoard.set(board, writes);
    return writes;
}

export default class BoardApi {

    private isRelationMode: boolean;
    /** The branch last sent to the end of each column, by {@link moveToColumnEnd}. */
    private sentToColumnEnd = new Map<string, string>();
    statusAttribute: string;
    /**
     * What the board groups by, with the `#`/`~` prefix it is written with. Every column read and
     * write is keyed by it, so one grouping's columns can never be stored under another's.
     */
    groupBy: string;

    /**
     * The pane the board is drawn in, set by the board on every render.
     *
     * A redirecting card navigates this rather than whichever pane holds the focus: the board can be
     * one split of several, and the focused one is often the pane the reader came from.
     */
    noteContext: NoteContext | null | undefined;
    /** Opens a note where the board's host shows notes, in place of the quick edit popup. */
    onOpenNote: ((noteId: string) => void) | undefined;
    /** Whether the board only shows its cards, set by the board on every render. */
    isReadOnly = false;

    /**
     * Stands in for the stored collapse flags while a filter is on, set by the board on every
     * render and cleared with the filter. See {@link VolatileCollapse}.
     */
    volatileCollapse: VolatileCollapse | undefined;

    /** The config as the board last handed it over, against which a fresh one is recognised. */
    private viewConfigSource: BoardViewData | undefined;
    private viewConfig: BoardViewData;
    /** `viewConfig` as last taken from the board, before the api stored a config of its own. */
    private drawnConfig: BoardViewData;

    constructor(
        private byColumn: ColumnMap | undefined,
        public columns: string[],
        private parentNote: FNote,
        statusAttribute: string,
        viewConfig: BoardViewData | undefined,
        private saveConfig: (newConfig: BoardViewData) => void,
        private setBranchIdToEdit: (branchId: string | undefined) => void,
        private pending: PendingColumnWrites =
            { renames: new Map(), claims: new Map(), inFlight: 0 },
        private statusDefinition?: BoardStatusDefinition,
        /**
         * Every card, when `byColumn` is narrowed by a filter. Bulk operations read this one, so a
         * column operation reaches the cards the filter leaves out too.
         */
        private allByColumn?: ColumnMap,
        /** Draws a card the active filter does not match. See {@link keepInView}. */
        private keepNote?: (noteId: string) => void
    ) {
        this.viewConfigSource = viewConfig;
        this.viewConfig = viewConfig ?? {};
        this.drawnConfig = this.viewConfig;
        this.groupBy = statusAttribute;
        this.isRelationMode = statusAttribute.startsWith("~");

        if (statusAttribute.startsWith("~") || statusAttribute.startsWith("#")) {
            statusAttribute = statusAttribute.substring(1);
        }
        this.statusAttribute = statusAttribute;
    };

    /**
     * Points the api at the board as it now stands.
     *
     * A refresh calls this instead of building a new api, so that the object every card holds keeps
     * its identity and a move redraws only the cards whose position changed.
     */
    update(
        byColumn: ColumnMap | undefined,
        columns: string[],
        parentNote: FNote,
        statusAttribute: string,
        viewConfig: BoardViewData | undefined,
        saveConfig: (newConfig: BoardViewData) => void,
        setBranchIdToEdit: (branchId: string | undefined) => void,
        statusDefinition?: BoardStatusDefinition,
        allByColumn?: ColumnMap,
        keepNote?: (noteId: string) => void
    ) {
        // What was sent to the end of a column stands in for what the map does not show yet, so it
        // is given up with the map it stands in for. Kept across a refresh, it would name a branch
        // that is no longer last and put the next card before it.
        if (byColumn !== this.byColumn) {
            this.sentToColumnEnd.clear();
        }

        this.byColumn = byColumn;
        this.allByColumn = allByColumn;
        this.keepNote = keepNote;
        this.columns = columns;
        this.parentNote = parentNote;
        // Only a config the board has actually replaced, since `storeColumns` moves this one ahead
        // of what the board holds and an unrelated render must not take that back.
        if (viewConfig !== this.viewConfigSource) {
            this.viewConfigSource = viewConfig;
            this.viewConfig = viewConfig ?? {};
            this.drawnConfig = this.viewConfig;
        }
        this.saveConfig = saveConfig;
        this.setBranchIdToEdit = setBranchIdToEdit;
        this.statusDefinition = statusDefinition;
        this.groupBy = statusAttribute;
        this.isRelationMode = statusAttribute.startsWith("~");
        this.statusAttribute = statusAttribute.replace(/^[~#]/, "");
    }

    /**
     * Creates a card at one end of a column.
     *
     * Cards are drawn in the order the board's children stand in, so a card created under the
     * board lands at the bottom. The top is created before the column's own first card: all
     * columns share one list of children, so the board's first child is not this column's.
     */
    async createNewItem(
        column: string, title: string, placement: CardPlacement = "bottom", icon?: string,
        template: NoteTypeOption | undefined = this.getCurrentCardTemplate()
    ) {
        const first = placement === "top" ? this.firstInColumn(column) : undefined;

        try {
            const { note } = await note_create.createNote(this.parentNote.noteId, {
                activate: false,
                title,
                isProtected: this.parentNote.isProtected,
                ...(template?.options ?? {}),
                attributes: this.attributesFor(column, icon),
                ...(first ? { target: "before", targetBranchId: first } : {})
            });

            this.keepInView(note?.noteId);
            return note?.noteId;
        } catch (error) {
            console.error("Failed to create new item:", error);
        }
    }

    /**
     * Creates a card above another one, for a field standing among a column's cards.
     *
     * Without a card to go above, which is where the field stands below the last one, the card is
     * made at the end of the column.
     */
    async createNewItemBefore(
        column: string, beforeBranchId: string | undefined, title: string, icon?: string,
        template: NoteTypeOption | undefined = this.getCurrentCardTemplate()
    ) {
        if (!beforeBranchId) {
            return this.createNewItem(column, title, "bottom", icon, template);
        }

        const { note } = await this.insertRowAtPosition(
            column, beforeBranchId, "before", title, icon, template);
        return note.noteId;
    }

    /**
     * Reports a card the board has just gained, which `useCollectionFilter` draws and marks even
     * when the query misses it. Without this, adding a card to a filtered board shows nothing.
     */
    private keepInView(noteId: string | undefined) {
        if (noteId) {
            this.keepNote?.(noteId);
        }
    }

    /** What a new card carries besides its title: the column it lands in, and its icon. */
    private attributesFor(column: string, icon?: string) {
        return [
            ...this.groupingFor(column),
            ...(icon
                ? [ {
                    type: "label" as const,
                    name: "iconClass",
                    value: icon,
                    isInheritable: false
                } ]
                : [])
        ];
    }

    /**
     * What a new card carries so that it lands in the column it was added to.
     *
     * Written with the note rather than after it: a write of its own is a second round trip and a
     * second refresh, which on a large board is most of what adding a card costs. The inbox is the
     * column held by having no value at all, so it carries nothing.
     */
    private groupingFor(column: string) {
        if (column === INBOX_COLUMN) {
            return [];
        }

        return [ {
            type: this.isRelationMode ? "relation" as const : "label" as const,
            name: this.statusAttribute,
            value: column,
            isInheritable: false
        } ];
    }

    /**
     * Puts a note that already exists into a column, cloning it onto the board unless it is already
     * somewhere beneath it.
     *
     * A note that already carries a value for the label the board groups by is on some other board
     * grouped the same way, or is about to look like it: the value is the note's, not the board's,
     * so writing ours moves it there too. Worth knowing but not worth refusing, since a note
     * tracked on two boards is a fair thing to want.
     *
     * @returns whether the note was added, `false` when the user backed out.
     */
    async addExistingItem(column: string, noteId: string, beforeBranchId?: string) {
        const note = await froca.getNote(noteId, true);
        if (!note) return false;

        const isAlreadyOnBoard = note.hasAncestor(this.parentNote.noteId);
        const currentValue = this.isRelationMode
            ? note.getRelationValue(this.statusAttribute)
            : note.getLabelValue(this.statusAttribute);

        if (!isAlreadyOnBoard && currentValue) {
            const confirmed = await dialog.confirm(t("board_view.existing-item-conflict", {
                label: this.statusAttribute
            }));
            if (!confirmed) return false;
        }

        if (!isAlreadyOnBoard) {
            await branches.cloneNoteToParentNote(noteId, this.parentNote.noteId);
        }

        await this.changeColumn(noteId, column);

        if (beforeBranchId) {
            await this.moveIntoPlace(noteId, beforeBranchId);
        }

        this.keepInView(noteId);
        return true;
    }

    /**
     * Puts a card that was just added above another one, which is where a field standing among a
     * column's cards adds it, rather than leaving it at the end of the column.
     *
     * The wait is what makes the move possible: a note cloned onto the board is given its branch by
     * the server, and that branch has to be in froca before it can be moved.
     */
    private async moveIntoPlace(noteId: string, beforeBranchId: string) {
        await ws.waitForMaxKnownEntityChangeId();

        const note = await froca.getNote(noteId);
        const branchId = note?.getParentBranches()
            .find(branch => branch.parentNoteId === this.parentNote.noteId)?.branchId;

        if (branchId && branchId !== beforeBranchId) {
            await branches.moveBeforeBranch([ branchId ], beforeBranchId);
        }
    }

    async changeColumn(noteId: string, newColumn: string) {
        if (newColumn === INBOX_COLUMN) {
            return this.moveToInbox(noteId);
        }

        if (this.isRelationMode) {
            await attributes.setRelation(noteId, this.statusAttribute, newColumn);
        } else {
            await attributes.setLabel(noteId, this.statusAttribute, newColumn);
        }
    }

    /**
     * Files a card under the inbox, which means leaving it with no grouping value at all.
     *
     * Different from {@link removeFromBoard}, which removes only the value the card owns and may
     * uncover an inherited one. Reaching the inbox is stricter: an inherited relation would still
     * point somewhere, so the card would end up in that column instead.
     */
    private moveToInbox(noteId: string) {
        const note = froca.getNoteFromCache(noteId);
        if (!note) return;

        if (this.isRelationMode && this.isInherited(note, "relation")) {
            toast.showMessage(t("board_view.inherited-column"), 3000);
            return;
        }

        return this.removeCardFromBoard(noteId);
    }

    /**
     * Adds a column at one end of the board.
     *
     * @param atStart whether it goes at the head of the board rather than after the last column.
     */
    async addNewColumn(columnName: string, atStart = false, icon?: string) {
        if (!columnName.trim()) {
            return;
        }

        const columns = this.storedColumns;

        // Add the new column to persisted data if it doesn't exist
        if (columns.some(col => col.value === columnName)) return false;
        settleColumn(this.pending, columnName);

        // The icon goes in with the column rather than after it: a write of its own would be a
        // second refresh of the board for a column that has only just been drawn.
        const added: BoardColumnData = { value: columnName, id: newColumnId() };
        if (icon) {
            added.icon = icon;
        }

        if (!atStart) {
            this.storeColumns([ ...columns, added ]);
            return true;
        }

        // The whole order has to be written for the column to stand before the others: the stored
        // list is what the board reads first, and a column missing from it keeps its derived place
        // at the end whatever is put in front. The inbox holds the head where it has one.
        const order = columns.map(col => col.value);
        for (const derived of this.columns) {
            if (!order.includes(derived)) {
                order.push(derived);
            }
        }

        const byValue = new Map(columns.map(col => [ col.value, col ]));
        const placed: BoardColumnData[] = order.map(value => byValue.get(value) ?? { value });
        placed.splice(order[0] === INBOX_COLUMN ? 1 : 0, 0, added);
        this.storeColumns(placed);
        return true;
    }

    /**
     * Puts a new column beside an existing one, and hands back the name it was given for the caller
     * to open its title editor with.
     *
     * Named rather than left blank: a column is known by its value, so until it has one there is
     * nothing to place it by, nothing to store and nothing to rename. The stock name is numbered
     * where it is already taken, so adding several in a row cannot silently do nothing.
     */
    async insertColumn(relativeTo: string, direction: "before" | "after") {
        const stored = this.storedColumns;
        const taken = new Set([ ...this.columns, ...stored.map(col => col.value) ]);

        const stockName = t("board_view.new-column");
        let name = stockName;
        for (let suffix = 2; taken.has(name); suffix++) {
            name = `${stockName} ${suffix}`;
        }

        // Placed by the stored order rather than the derived one, which lags a column just added:
        // `columns` is rebuilt only when the view re-renders, while the config is written here.
        // Columns the config does not know yet keep their derived places, at the end.
        const order = stored.map(col => col.value);
        for (const derived of this.columns) {
            if (!order.includes(derived)) {
                order.push(derived);
            }
        }

        const neighbour = order.indexOf(relativeTo);
        order.splice(
            neighbour < 0 ? order.length : neighbour + (direction === "after" ? 1 : 0), 0, name);

        // Entries carry more than their name, so each is moved rather than rebuilt. The new one is
        // the only one written from scratch, and is the only one given an id.
        const byValue = new Map(stored.map(col => [ col.value, col ]));
        this.storeColumns(order.map(value =>
            byValue.get(value) ?? (value === name ? { value, id: newColumnId() } : { value })));

        return name;
    }

    /**
     * Asks before taking a column off the board, offering to delete its cards as well.
     * Both the menu and the Delete key come through here, so the question is put once and the same
     * way, and a refusal from the server is reported rather than passing for a deletion.
     *
     * @returns whether the column went, for a caller with something to do afterwards.
     */
    async confirmAndRemoveColumn(column: string) {
        // Count from the unfiltered map, which is the one `removeColumn` deletes from.
        const cards = (this.allByColumn ?? this.byColumn)?.get(column)?.length ?? 0;
        const answer = await dialog.confirmWithNoteDeletion(
            t("board_view.delete-column-confirmation"),
            cards ? t("board_view.delete-column-notes", { count: cards }) : undefined);
        if (!answer || !answer.confirmed) {
            return false;
        }

        try {
            await this.removeColumn(column, answer.isDeleteNoteChecked);
            return true;
        } catch (e) {
            console.error("Failed to delete the board column:", e);
            toast.showError(t("board_view.save-error"));
            return false;
        }
    }

    /**
     * Takes a column off the board.
     *
     * @param deleteNotes deletes the column's cards instead of removing the grouping value from
     *                    them.
     */
    async removeColumn(column: string, deleteNotes = false) {
        // `allByColumn` covers the cards an active filter is not showing.
        const items = (this.allByColumn ?? this.byColumn)?.get(column);
        const noteIds = items?.map(item => item.note.noteId) || [];

        const action: BulkAction = deleteNotes
            ? { name: "deleteNote" }
            : this.isRelationMode
                ? { name: "deleteRelation", relationName: this.statusAttribute }
                : { name: "deleteLabel", labelName: this.statusAttribute };
        await this.retiredWhile(column, undefined, async () => {
            const { executeBulkActions } = await loadBulkActions();
            return executeBulkActions(noteIds, [ action ], { silent: true });
        });

        this.storeColumns(this.storedColumns.filter(col => col.value !== column));
    }

    async renameColumn(oldValue: string, newValue: string) {
        // A column is identified by the value its cards carry, so a blank name would write an
        // empty label over every card and leave nothing to group by. The old name is kept.
        if (!newValue.trim()) {
            return;
        }

        // One write, which the server makes over the cards, the stored columns and the definition
        // together. Renaming them from here one at a time leaves a window in which they disagree,
        // and another client reading the board during it resolves the old name back from whichever
        // of them still carries it and writes that back, undoing the rename.
        const renamed = await this.retiredWhile(oldValue, newValue, () =>
            server.put<{ config?: BoardViewData }>(
                `notes/${this.parentNote.noteId}/board/rename-column`, {
                    attribute: this.statusAttribute,
                    isRelation: this.isRelationMode,
                    oldValue,
                    newValue
                }));

        // Taken from the answer rather than waited for: until the change arrives, this still holds
        // the configuration it read before the rename, and a refresh landing in between would write
        // that back and bring the old name with it.
        if (renamed?.config) {
            this.viewConfig = renamed.config;
            this.viewConfigSource = renamed.config;
            this.drawnConfig = renamed.config;
        }
    }

    /** Stores the icon a column shows, or clears it back to the default when given nothing. */
    async setColumnIcon(column: string, icon: string | undefined) {
        this.updateColumn(column, { icon });
    }

    /** Stores the colour a column is tinted with, or clears it when given nothing. */
    async setColumnColor(column: string, color: string | null) {
        this.updateColumn(column, { color: color ?? undefined });
    }

    /**
     * The title shown for a column. For most columns this is the grouping value itself; the
     * inbox has no value, so it uses a name stored in the config.
     */
    getColumnTitle(column: string) {
        const named = this.storedColumns.find(col => col.value === column)?.displayName;
        return named || (column === INBOX_COLUMN ? t("board_view.inbox") : column);
    }

    /**
     * Renames a column however that column is named.
     *
     * Most columns are identified by the value their cards carry, so renaming writes that value
     * to every card in the column. The inbox has no value, so it stores a display name instead and
     * its cards are left untouched.
     *
     * @returns `false` when nothing was written, which keeps the caller's editor open: the name
     *          is blank, or another column already uses it and renaming would merge the two.
     */
    setColumnTitle(column: string, title: string): false | void | Promise<void> {
        const name = title.trim();
        if (!name) {
            return false;
        }

        if (this.isColumnNameTaken(name, column)) {
            toast.showMessage(t("board_view.column-name-taken", { column: name }), undefined,
                "bx bx-duplicate");
            return false;
        }

        return column === INBOX_COLUMN
            ? this.updateColumn(column, { displayName: name })
            : this.renameColumn(column, name);
    }

    /**
     * Whether a column other than `except` already uses a name.
     *
     * Compares titles as well as values, since the inbox is named by `displayName`, and covers the
     * stored columns so that an empty one counts.
     */
    private isColumnNameTaken(name: string, except: string) {
        const values = new Set([ ...this.columns, ...this.storedColumns.map(col => col.value) ]);
        for (const value of values) {
            if (value !== except && (value === name || this.getColumnTitle(value) === name)) {
                return true;
            }
        }

        return false;
    }

    /**
     * What each column is called, the icon it shows and how many cards it holds, which the right
     * pane's outline is drawn from.
     */
    getColumnOutline(columns: string[]) {
        return columns.map(column => {
            const { title, icon } = this.getColumnLabel(column);
            return { value: column, title, icon, count: this.byColumn?.get(column)?.length ?? 0 };
        });
    }

    /**
     * The title, icon and colour naming a column outside the board itself.
     *
     * A relation board keys its columns by note id, so the title comes from the note.
     */
    getColumnLabel(column: string): ColumnReferenceLabel {
        return {
            title: this.isRelationMode && column !== INBOX_COLUMN
                ? froca.getNoteFromCache(column)?.title ?? column
                : this.getColumnTitle(column),
            icon: this.getColumnIcon(column) ?? DEFAULT_COLUMN_ICON,
            color: this.storedColumns.find(col => col.value === column)?.color
        };
    }

    /**
     * The icon a column heading shows, for anything else that stands in for the column.
     *
     * In relation mode the column is a note, so the icon is that note's own — the same one
     * `NoteLink` puts in the heading — and `setColumnIcon` is not offered there.
     */
    getColumnIcon(column: string) {
        // The inbox stands for the cards carrying no value at all, so there is no note behind it
        // even on a relation board, where every other column is one.
        if (this.isRelationMode && column !== INBOX_COLUMN) {
            return froca.getNoteFromCache(column)?.getIcon();
        }

        const stored = this.storedColumns.find(col => col.value === column)?.icon;
        if (stored) {
            return stored;
        }

        return column === INBOX_COLUMN ? INBOX_COLUMN_ICON : DEFAULT_COLUMN_ICON;
    }

    /**
     * The classes tinting anything that stands in for a column with the colour picked for it, empty
     * while it carries none. The colour is stored per column in both modes, unlike the icon.
     */
    getColumnColorClass(column: string) {
        const color = this.storedColumns.find(col => col.value === column)?.color;
        return cssClassManager.createClassForColor(color ?? null);
    }

    /**
     * What to call the field the board groups by, for a heading standing over its columns.
     *
     * The promoted alias is what a card shows the field as, so it is the name a reader already
     * knows. A board whose definition gives none, or none of its own, falls back to the stock word.
     */
    getStatusLabel() {
        return this.statusDefinition?.definition.promotedAlias || t("board_view.status-header");
    }

    /**
     * Whether the board keeps an inbox column. The stored entry outlives being switched off, so
     * its icon, colour and position come back with it.
     */
    async setInboxEnabled(enabled: boolean) {
        await attributes.setBooleanWithInheritance(
            this.parentNote, "board:showInbox", enabled);
    }

    /** Hides the inbox column, which is what its own menu offers. */
    async disableInbox() {
        await this.setInboxEnabled(false);
    }

    /** Whether the board draws the button after its last column that adds a column. */
    async setAddColumnShown(shown: boolean) {
        await attributes.setBooleanWithInheritance(this.parentNote, "board:hideAddColumn", !shown);
    }

    /** Whether the board draws the notes filed as archived, cards and columns alike. */
    async setArchivedShown(shown: boolean) {
        await attributes.setBooleanWithInheritance(this.parentNote, "includeArchived", shown);
    }

    /** How wide the board draws its columns, which the board turns into a class of its own. */
    get columnWidth() {
        return parseColumnWidth(this.parentNote?.getLabelValue(COLUMN_WIDTH_LABEL));
    }

    /**
     * Sets how wide the columns are drawn.
     *
     * Picking the default removes the label, to keep the note tidy. Where a template or a parent
     * sets the label, the default is written out instead: `removeOwnedLabelByName` would leave the
     * inherited value in force.
     */
    async setColumnWidth(width: ColumnWidth) {
        const note = this.parentNote;
        if (!note) return;

        const inherited = note.getAttributes("label", COLUMN_WIDTH_LABEL)
            .find(attribute => attribute.noteId !== note.noteId);
        if (width === DEFAULT_COLUMN_WIDTH
                && parseColumnWidth(inherited?.value) === DEFAULT_COLUMN_WIDTH) {
            await attributes.removeOwnedLabelByName(note, COLUMN_WIDTH_LABEL);
            return;
        }

        await attributes.setLabel(note.noteId, COLUMN_WIDTH_LABEL, width);
    }

    /** The note limit set for a column, absent if disabled or for the inbox. */
    getColumnLimit(column: string) {
        if (column === INBOX_COLUMN) {
            return undefined;
        }

        return this.storedColumns.find(col => col.value === column)?.limit;
    }

    /** Sets a column's note limit. Pass `undefined` to disable it. */
    async setColumnLimit(column: string, limit: number | undefined) {
        if (column === INBOX_COLUMN) {
            return;
        }

        await this.updateColumn(column, { limit });
    }

    /**
     * Reads a column's stored `orderBy` and `descendingOrder`.
     *
     * @returns {@link DEFAULT_SORT} when the column stores nothing, undefined for the manual
     *          order, and otherwise the stored key. Use {@link getEffectiveColumnSort} to resolve
     *          {@link DEFAULT_SORT} against the board's own order.
     */
    getColumnSort(column: string) {
        const stored = this.storedColumns.find(col => col.value === column);
        return {
            orderBy: parseStoredSortKey(stored?.orderBy),
            isDescending: !!stored?.descendingOrder
        };
    }

    /**
     * Resolves {@link getColumnSort} against {@link getDefaultSort}: a column storing
     * {@link DEFAULT_SORT} sorts by the board's key and direction, and by nothing when the board
     * holds no key.
     */
    getEffectiveColumnSort(column: string) {
        const stored = this.getColumnSort(column);
        if (stored.orderBy !== DEFAULT_SORT) {
            return { orderBy: stored.orderBy, isDescending: stored.isDescending };
        }

        const board = this.getDefaultSort();
        return { orderBy: board.orderBy, isDescending: board.isDescending };
    }

    /**
     * Sets what a column sorts by. `undefined` stores {@link MANUAL_SORT}, since a column storing
     * nothing sorts by the board's order instead.
     */
    async setColumnSort(column: string, orderBy: StoredSortKey | undefined) {
        await this.updateColumn(column, { orderBy: orderBy ?? MANUAL_SORT });
    }

    /** Sets whether a column's order runs backwards. */
    async setColumnSortDirection(column: string, isDescending: boolean) {
        await this.updateColumn(column, { descendingOrder: isDescending });
    }

    /**
     * Reads `#board:sortColumns` and `#board:sortColumnsDescending` off the board note, which is where the
     * order the columns default to is stored rather than in `board.json`.
     */
    getDefaultSort() {
        return {
            orderBy: parseSortKey(this.parentNote?.getLabelValue(SORT_LABEL)),
            isDescending: !!this.parentNote?.isLabelTruthy(SORT_DESCENDING_LABEL)
        };
    }

    /** Sets what the board offers to sort by. Pass `undefined` for the manual order. */
    async setDefaultSort(orderBy: SortKey | undefined) {
        if (!this.parentNote) return;
        await attributes.setAttribute(this.parentNote, "label", SORT_LABEL, orderBy ?? null);
    }

    /** Sets whether the order the board offers runs backwards. */
    async setDefaultSortDirection(isDescending: boolean) {
        if (!this.parentNote) return;
        await attributes.setBooleanWithInheritance(
            this.parentNote, SORT_DESCENDING_LABEL, isDescending);
    }

    /**
     * Removes `orderBy` and `descendingOrder` from every stored column, so all of them sort by the
     * board's order again.
     *
     * Only columns `board.json` holds an entry for are written; a column with no entry already
     * sorts by the board's order. Written through {@link updateColumns} in one go, since
     * `updateColumn` rewrites the whole config and a run of them would each start from the config
     * as it stood before the first.
     */
    async resetColumnSortsToDefault() {
        const stored = this.storedColumns;
        this.updateColumns(
            stored.map(({ value }) => value), { orderBy: undefined, descendingOrder: false });
    }

    /** Whether the inbox also collects notes deeper than the board's direct children. */
    async setInboxNested(nested: boolean) {
        await this.updateColumn(INBOX_COLUMN, { nested });
    }

    /**
     * The id a reference names a column by, assigning one where the column has none yet.
     *
     * A column with no stored entry at all is given one here: it is drawn from the definition or
     * from a value its cards carry, and until something is stored for it there is nothing to hold
     * an id.
     *
     * The assignment goes through the server, which reads and writes `board.json` in one request.
     * Two clients copying a reference to the same id-less column would otherwise each generate an
     * id and the second write would replace the first, breaking the link already copied from it.
     * The server answers with the id the column actually holds, which is this one only when it
     * arrived first, and says whether it stored it: a configuration the server cannot read is left
     * for the board to write out again from here.
     */
    async ensureColumnId(column: string) {
        const stored = readColumnId(this.viewConfig, this.groupBy, column);
        if (stored) {
            return stored;
        }

        const id = newColumnId();
        try {
            const settled = await server.put<{ id: string, stored: boolean }>(
                `notes/${this.parentNote.noteId}/board/column-id`,
                { groupBy: this.groupBy, value: column, id });
            if (settled && !settled.stored) {
                this.updateColumn(column, { id: settled.id });
            }

            return settled?.id ?? id;
        } catch (e) {
            // The link still works for as long as nothing else claims the column, and the board
            // writes the id out with the rest of the configuration as it draws.
            console.error("Failed to store the board column id:", e);
            this.updateColumn(column, { id });
            return id;
        }
    }

    /**
     * The link that opens this board on one of its columns, which the menu copies.
     *
     * Assigning an id to a column that has none is what makes the link outlive a rename, so
     * copying a reference writes to `board.json` where nothing has been stored for the column yet.
     */
    async getColumnReference(column: string) {
        // `getColumnLabel` reads the note from froca's cache, which the heading fills only after
        // the board is interactive. Load it first: the label is written into the link for good, so
        // a cache miss would title the column with its note id.
        if (this.isRelationMode && column !== INBOX_COLUMN) {
            await froca.getNote(column, true);
        }

        return columnReference(this.boardNotePath, await this.ensureColumnId(column),
            this.getColumnLabel(column));
    }

    /** The link that opens this board on one of its cards, which is named by its own note id. */
    getCardReference(noteId: string) {
        return cardReference(this.boardNotePath, noteId);
    }

    /** How a link names the board: the path the pane reached it by, or the board alone. */
    private get boardNotePath() {
        return this.noteContext?.notePath ?? this.parentNote.noteId;
    }

    /** Whether a column is archived, which the board shows only while archived notes are shown. */
    isColumnArchived(column: string) {
        return !!this.storedColumns.find(col => col.value === column)?.archived;
    }

    /**
     * Archives a column or brings it back. An archived one is shown only while the board is set to
     * show archived notes, and greyed out where it is.
     */
    async setColumnArchived(column: string, archived: boolean) {
        this.updateColumn(column, { archived });
    }

    /**
     * Everything a card could be made from, as the board read them.
     *
     * Held here so that a card made from somewhere other than the editor with the pill in it, an
     * insert beside another card above all, is made from the same template: the alternative is
     * handing every card on the board a list it would redraw for.
     */
    private availableTemplates: NoteTypeOption[] = [];

    setAvailableCardTemplates(templates: NoteTypeOption[]) {
        this.availableTemplates = templates;
    }

    /** What a card is made from now: the one last used, or the first the board offers. */
    getCurrentCardTemplate() {
        return currentNoteTypeOption(
            resolveNoteTypeOptions(this.getCardTemplateIds(), this.availableTemplates),
            this.getLastCardTemplateId());
    }

    /** The templates the board offers, or the stock set until the reader has picked for it. */
    getCardTemplateIds() {
        return offeredTemplateIds(this.viewConfig, DEFAULT_CARD_TEMPLATES);
    }

    /** Which of them a new card is made from, until another is picked. */
    getLastCardTemplateId() {
        return this.viewConfig?.template;
    }

    /** The order and what is hidden, as the view config holds it. */
    getStoredPromotedAttributes() {
        return this.viewConfig?.promotedAttributes;
    }

    /**
     * Returns the promoted attributes defined by the board note or its cards, in the stored order.
     * Includes the grouping attribute, so that Board Properties keeps its position for when the
     * board is grouped by another attribute.
     */
    getAllPromotedAttributes() {
        return resolvePromotedAttributes(
            this.parentNote, this.viewConfig?.promotedAttributes, [ this.statusAttribute ],
            this.getCardNotes());
    }

    /** Returns the note of every card, including the cards the filter hides. */
    getCardNotes() {
        return cardNotes(this.allByColumn ?? this.byColumn);
    }

    /** Those a card can show or a column sort by, which the columns themselves stand for. */
    getPromotedAttributes() {
        return this.getAllPromotedAttributes()
            .filter((attribute) => !attribute.drawnByCollection);
    }

    /** Which of them a card draws, in order. */
    getVisiblePromotedAttributeNames() {
        return visiblePromotedAttributeNames(this.getPromotedAttributes());
    }

    /**
     * Stores the order and what is hidden.
     *
     * The whole list is written, so an attribute the board no longer defines is dropped from the
     * config by the same call that arranges the rest.
     */
    async setPromotedAttributes(attributes: PromotedAttribute[]) {
        this.storeConfig({ promotedAttributes: storedPromotedAttributes(attributes) });
    }

    /**
     * Whether the api stored a config after the board drew `config`.
     *
     * A refresh resolves its columns from the config of the render that started it. Once this
     * returns `true`, those columns can be ones the api has since removed, so the refresh must not
     * write them.
     */
    hasStoredSince(config: BoardViewData | undefined) {
        return config !== this.viewConfigSource || this.viewConfig !== this.drawnConfig;
    }

    /**
     * Runs `deletion`, which deletes the attribute a grouping is made from, then empties the columns
     * stored for that grouping so that `syncColumnsToDefinition()` cannot write them back into a
     * new definition. The empty list keeps the grouping's key, without which
     * `adoptLegacyColumns()` reads the default grouping's `columns` as this grouping's.
     *
     * Counted in `pending.inFlight` while `deletion` runs. A refresh that resolves later still
     * holds the old config, and `hasStoredSince()` keeps it from writing.
     */
    async deleteGrouping(groupBy: string, deletion: () => Promise<void>) {
        this.pending.inFlight++;

        try {
            await deletion();
            // A board that still reads the deleted definition fills an empty list from its options.
            await ws.waitForMaxKnownEntityChangeId();
            if (readColumns(this.viewConfig, groupBy)) {
                this.viewConfig = writeColumns(this.viewConfig, groupBy, []);
                this.saveConfig(this.viewConfig);
            }
        } finally {
            this.pending.inFlight--;
        }
    }

    /** Sets what the board offers. An empty set would leave nothing to make a card from. */
    async setCardTemplateIds(templates: string[]) {
        if (!templates.length) {
            return;
        }

        this.storeConfig({ templates });
    }

    /** Stores the query the board is narrowed to, or clears it when given an empty one. */
    setFilterQuery(query: string) {
        if ((query || undefined) === this.viewConfig?.filterQuery) {
            return;
        }

        this.storeConfig({ filterQuery: query || undefined });
    }

    /** Remembers what the last card was made from, so the next one is made from it too. */
    async setLastCardTemplateId(template: string) {
        if (template === this.viewConfig?.template) {
            return;
        }

        this.storeConfig({ template });
    }

    /** Whether a column is stored as collapsed, which draws it as a strip without its cards. */
    isColumnCollapsed(column: string) {
        if (this.volatileCollapse) {
            return this.volatileCollapse.isCollapsed(column);
        }

        return !!this.storedColumns.find(col => col.value === column)?.collapsed;
    }

    /** Collapses a column to a strip, or opens it again. Not written while a filter is on. */
    async setColumnCollapsed(column: string, collapsed: boolean) {
        if (this.volatileCollapse) {
            this.volatileCollapse.setCollapsed(column, collapsed);
            return;
        }

        this.updateColumn(column, { collapsed });
    }

    /**
     * Collapses every column, or opens the ones that are not kept collapsed.
     *
     * One write for the board: a column resolved from the definition or from a value its cards
     * carry is drawn without ever having been stored, so this is also where it gets an entry.
     */
    async setAllColumnsCollapsed(collapsed: boolean) {
        if (this.volatileCollapse) {
            this.volatileCollapse.setCollapsed(null, collapsed);
            return;
        }

        const stored = new Map(this.storedColumns.map(col => [ col.value, col ]));
        const order = [ ...stored.keys() ];
        for (const derived of this.columns) {
            if (!stored.has(derived)) {
                order.push(derived);
            }
        }

        this.storeColumns(order.map(value => {
            const column = { ...(stored.get(value) ?? { value }) };
            if (collapsed) {
                column.collapsed = true;
            } else if (!column.keepCollapsed) {
                // A column kept collapsed keeps the flag: opening it is what the peek is for.
                delete column.collapsed;
            }

            return column;
        }));
    }

    /** Whether a column collapses again once it has been opened. Never while a filter is on. */
    isColumnKeptCollapsed(column: string) {
        return !this.volatileCollapse
            && !!this.storedColumns.find(col => col.value === column)?.keepCollapsed;
    }

    /**
     * Sets whether a column collapses again once it has been opened.
     *
     * Turning it on collapses the column as well, so that the entry does something the reader can
     * see rather than only deciding what happens the next time the column is opened.
     *
     * @param isOpen whether the column is drawn open. Turning the flag off then clears `collapsed`
     *               as well, so the column the reader is looking at stays open.
     */
    async setColumnKeepCollapsed(column: string, keepCollapsed: boolean, isOpen = false) {
        if (keepCollapsed) {
            this.updateColumn(column, { keepCollapsed: true, collapsed: true });
            return;
        }

        this.updateColumn(column,
            isOpen ? { keepCollapsed: false, collapsed: false } : { keepCollapsed: false });
    }

    /**
     * Writes properties onto a column, dropping each one given as nothing so that it goes back to
     * its default rather than being stored empty.
     *
     * The column may have no stored entry at all: one resolved from the definition or from a value
     * a note carries is shown without ever being written, so the first pick for it creates one.
     */
    private updateColumn(column: string, patch: Partial<BoardColumnData>) {
        this.storeColumns(this.withColumn(this.storedColumns, column, patch));
    }

    /** The same for several columns at once, written as one config. */
    private updateColumns(columns: string[], patch: Partial<BoardColumnData>) {
        let next = this.storedColumns;
        for (const column of columns) {
            next = this.withColumn(next, column, patch);
        }

        this.storeColumns(next);
    }

    /** The columns as they read with the patch applied to one of them. */
    private withColumn(
        columns: BoardColumnData[], column: string, patch: Partial<BoardColumnData>
    ): BoardColumnData[] {
        const patched = (stored: BoardColumnData): BoardColumnData => {
            const updated = { ...stored, ...patch };
            if (!updated.icon) delete updated.icon;
            if (!updated.color) delete updated.color;
            if (!updated.archived) delete updated.archived;
            if (!updated.collapsed) delete updated.collapsed;
            if (!updated.keepCollapsed) delete updated.keepCollapsed;
            if (!updated.displayName) delete updated.displayName;
            if (!updated.limit) delete updated.limit;
            if (!updated.orderBy) delete updated.orderBy;
            if (!updated.descendingOrder) delete updated.descendingOrder;
            return updated;
        };

        if (columns.some(col => col.value === column)) {
            return columns.map(col => col.value === column ? patched(col) : col);
        }

        // A column with no entry yet is written where the board draws it, after the last column
        // before it that has one. Appended, it would move to the end of the board the moment
        // anything was picked for it: the stored order is what the board reads first, and a column
        // with no entry keeps a place of its own only until it has one. The inbox is drawn at the
        // head without ever having been written, so collapsing it used to send it to the back.
        const drawn = this.columns.indexOf(column);
        const previous = drawn < 0 ? undefined : this.columns.slice(0, drawn).reverse()
            .find(value => columns.some(col => col.value === value));
        const at = drawn < 0
            ? columns.length
            : previous ? columns.findIndex(col => col.value === previous) + 1 : 0;

        const placed = [ ...columns ];
        placed.splice(at, 0, patched({ value: column }));
        return placed;
    }

    reorderColumn(fromIndex: number, toIndex: number) {
        if (!this.columns || fromIndex === toIndex) return;

        // The inbox leads whatever the board groups by, so neither carrying it off the front nor
        // placing a column before it can stand. Refused here rather than at each gesture: the
        // drag, the keyboard and the menu all reorder through this.
        const leadsWithInbox = this.columns[0] === INBOX_COLUMN;
        if (this.columns[fromIndex] === INBOX_COLUMN || (leadsWithInbox && toIndex === 0)) {
            return;
        }

        const newColumns = [...this.columns];
        const [movedColumn] = newColumns.splice(fromIndex, 1);

        // Adjust toIndex after removing the element
        // When moving forward (right), the removal shifts indices left
        let adjustedToIndex = toIndex;
        if (fromIndex < toIndex) {
            adjustedToIndex = toIndex - 1;
        }

        newColumns.splice(adjustedToIndex, 0, movedColumn);

        // `columns` is render state: it omits entries the view has yet to catch up with, and any
        // the board is hiding, such as a disabled inbox. Those are neither dropped nor appended at
        // the end.
        const stored = this.storedColumns;
        const byValue = new Map(stored.map(col => [ col.value, col ]));
        // Reordering only moves entries, so each keeps its stored icon instead of being rebuilt
        // from its name.
        const reordered: BoardColumnData[] =
            newColumns.map(value => byValue.get(value) ?? { value });

        // A hidden column goes back after the column it followed in the config, not at the index it
        // held there: the move has shifted the visible columns, so that index points elsewhere now.
        // Each one becomes the anchor for the next, which keeps a run of them in order.
        let anchor: string | undefined;
        for (const column of stored) {
            if (newColumns.includes(column.value)) {
                anchor = column.value;
                continue;
            }

            const at = anchor === undefined
                ? 0
                : reordered.findIndex(entry => entry.value === anchor) + 1;
            reordered.splice(at, 0, column);
            anchor = column.value;
        }

        this.storeColumns(reordered);

        return newColumns;
    }

    /**
     * Runs the write that moves a column, with the record of it in place from the start so that a
     * refresh in the middle reads the sources as they are about to be.
     *
     * Taken back out if the write does not land: left in, a rename nothing carries would keep the
     * column under the name it failed to take, and a deletion that failed would keep hiding one
     * that is still there, cards and all.
     */
    private async retiredWhile<T>(
        oldValue: string, newValue: string | undefined, write: () => Promise<T>
    ) {
        const undoRetirement = this.retireColumn(oldValue, newValue);
        this.pending.inFlight++;

        try {
            return await write();
        } catch (e) {
            undoRetirement();
            throw e;
        } finally {
            this.pending.inFlight--;
        }
    }

    /**
     * Records what a column became, so that `resolveBoardColumns` reads whichever of the notes, the
     * view config and the definition has not been written yet as though it already were. That must
     * be said outright: a value the board just renamed and one added from elsewhere look the same.
     * {@link getBoardData} clears the record once no source lists the old value.
     *
     * @param newValue the name that replaced it, or `undefined` where the column was deleted.
     * @returns a function taking back exactly the claims this call made, leaving those of any write
     *          still in flight to say what the column reads as.
     */
    private retireColumn(oldValue: string, newValue?: string) {
        const { renames, claims } = this.pending;
        const owner = {};
        const touched: string[] = [];

        // The last claim on a column is the one the board reads, so this runs after every claim
        // made and every claim taken back. A column no write claims any longer has no record.
        const restate = (key: string) => {
            const claim = claims.get(key)?.at(-1);
            if (claim?.records) {
                renames.set(key, claim.value);
            } else {
                renames.delete(key);
            }
        };

        const write = (key: string, value: string | undefined, records: boolean) => {
            claims.set(key, [ ...claims.get(key) ?? [], { owner, value, records } ]);
            touched.push(key);
            restate(key);
        };

        // A rename of a column whose own rename has not landed yet has to be followed through, or
        // the old value the stale sources still carry would resolve to a name that is itself gone.
        for (const [ from, to ] of renames) {
            if (to === oldValue) {
                write(from, newValue, true);
            }
        }

        write(oldValue, newValue, true);

        if (newValue) {
            // Covers a rename back to a name still pending, whose record the loop above just turned
            // into one mapping the name to itself.
            write(newValue, undefined, false);
        }

        return () => {
            for (const key of touched) {
                const stack = claims.get(key);
                const at = stack?.findIndex(claim => claim.owner === owner) ?? -1;
                if (!stack || at < 0) continue;

                stack.splice(at, 1);
                if (!stack.length) {
                    claims.delete(key);
                }
                restate(key);
            }
        };
    }

    /**
     * Persists a new column list, into the definition the board groups by as well as into the view
     * config — every column change funnels through here, so the two cannot drift apart.
     *
     * The config is always replaced with a fresh object instead of being edited in place: the board
     * re-renders off the identity of the config it was handed, so an in-place edit would be written
     * to disk but stay invisible until the view is re-entered.
     */
    /** Writes part of the board's own configuration, leaving the rest of it as it stands. */
    private storeConfig(patch: Partial<BoardViewData>) {
        this.viewConfig = { ...this.viewConfig, ...patch };
        this.saveConfig(this.viewConfig);
    }

    /** The columns stored for the grouping the board is on, empty where it has none yet. */
    private get storedColumns() {
        return readColumns(this.viewConfig, this.groupBy) ?? [];
    }

    private storeColumns(columns: BoardColumnData[]) {
        this.viewConfig = writeColumns(this.viewConfig, this.groupBy, columns);
        this.saveConfig(this.viewConfig);
        // Not awaited — every caller is the tail of a user gesture the board has already rendered —
        // so the failure is caught here rather than left to reject unhandled. The columns are still
        // in the view config, so the board is not wrong, only out of step with the definition.
        this.syncColumnsToDefinition(columns.map(({ value }) => value), this.groupBy)
            .catch((e) => {
                console.error("Failed to store the board columns in the attribute definition:", e);
                toast.showError(t("board_view.column-definition-save-error"));
            });
    }

    /**
     * Brings the board's own definition in line with the columns it shows, so that the same list is
     * what the promoted field offers, what the table view's dropdown offers, and what the board shows.
     *
     * Called both when the user changes a column and on every render, because a column can appear
     * without the board's column UI ever being used: a note given a new value from the table view, a
     * script or a synced instance shows up as a column here, and the definition has to learn about it
     * too. The render call is also what gives a newly created board its definition — nothing else
     * would, since migration 0240 only ever saw the boards that existed when it ran.
     *
     * Writing only on a real difference is what makes that safe to call every time: the write lands as
     * an entity change, which re-renders the board, which would write again.
     *
     * @param forGroupBy the grouping the columns were resolved for, with its prefix. The write is
     *                   dropped when the board has moved to another grouping since.
     */
    async syncColumnsToDefinition(columns: string[], forGroupBy: string) {
        // The caller resolved these columns for one grouping, and the board can have moved to
        // another since. Writing them would put one grouping's columns into another's definition.
        if (forGroupBy !== this.groupBy) {
            return;
        }

        if (this.isRelationMode || !canStoreColumnsInDefinition(this.statusDefinition)) {
            return;
        }

        // The definition lists the values a card can carry; the inbox has no value.
        columns = columns.filter(column => column !== INBOX_COLUMN);

        // A board showing nothing has no column list to describe and must not gain an empty
        // definition; one that already owns one is still emptied, since that is its last column going.
        if (!columns.length && !this.statusDefinition?.isOwned) {
            return;
        }

        const current = this.statusDefinition?.options ?? [];
        const isUpToDate = this.statusDefinition?.definition.labelType === "select"
            && current.length === columns.length
            && current.every((option, index) => option === columns[index]);
        if (isUpToDate) {
            return;
        }

        // What a board with no definition of its own is given. Promoted, because the column a card
        // sits in is the point of the board, and a field that is not promoted is one the card never
        // shows — the status would be reachable only by dragging the card. Named only where the name
        // is ours to give: a board grouping by anything else is named by its own label.
        const created: DefinitionObject = {
            isPromoted: true,
            promotedAlias: this.statusAttribute === DEFAULT_GROUP_BY ? t("board_view.status-alias") : undefined
        };

        // An existing definition is updated as it stands, so a board deliberately left unpromoted —
        // by the user, or by migration 0240 where it had no field to begin with — does not gain one.
        const definition = {
            ...(this.statusDefinition?.definition ?? created),
            labelType: "select" as const,
            selectOptions: columns
        };

        // Written by name rather than by attribute id, so that two syncs which overlap — a column
        // edit landing mid-refresh, or one refresh starting before the previous write is back —
        // converge on one row instead of each creating one. Addressing it by id cannot: both would
        // have read the same "no definition yet" state and both would ask for a new attribute. Only
        // the board's own attributes are matched, so a definition it merely inherits is still copied
        // into one of its own rather than edited where it lives.
        await attributes.setLabel(
            this.parentNote.noteId,
            `label:${this.statusAttribute}`,
            promotedAttributeDefinitionParser.serialize(definition, "label"),
            // A definition that is not inheritable would not reach the notes on the board at all.
            this.statusDefinition?.attribute.isInheritable ?? true
        );
    }

    /** Creates a card beside another one, which is what a field between two cards makes. */
    async insertRowAtPosition(
        column: string,
        relativeToBranchId: string,
        direction: "before" | "after",
        title: string,
        icon?: string,
        template: NoteTypeOption | undefined = this.getCurrentCardTemplate()) {
        const { note, branch } = await note_create.createNote(this.parentNote.noteId, {
            activate: false,
            targetBranchId: relativeToBranchId,
            target: direction,
            title,
            isProtected: this.parentNote.isProtected,
            ...(template?.options ?? {}),
            attributes: this.attributesFor(column, icon)
        });

        if (!note || !branch) {
            throw new Error("Failed to create note");
        }

        this.keepInView(note.noteId);
        return { note, branch };
    }

    openNote(noteIdOrPath: string) {
        if (this.onOpenNote) {
            this.onOpenNote(noteIdOrPath.split("/").at(-1) ?? noteIdOrPath);
            return;
        }
        appContext.triggerCommand("openInPopup", { noteIdOrPath });
    }

    /**
     * Answers the card's own open gesture, a click or Space.
     *
     * A card carrying `board:cardRedirectTo` stands in for the note that relation points at, so it
     * navigates there instead of opening an editor of its own. Quick edit calls `openNote` and
     * still opens the card's own editor.
     */
    openCard(note: FNote) {
        const target = note.getRelationValue(CARD_REDIRECT_RELATION)
            ?? note.getRelationValue(CARD_REDIRECT_RELATION_LEGACY);
        if (target && this.onOpenNote) {
            this.onOpenNote(target);
            return;
        }
        if (target) {
            const context = this.noteContext ?? appContext.tabManager?.getActiveContext();
            void context?.setNote(target);
            return;
        }

        this.openNote(note.noteId);
    }

    startEditing(branchId: string) {
        if (!this.isReadOnly) {
            this.setBranchIdToEdit(branchId);
        }
    }

    dismissEditingTitle() {
        this.setBranchIdToEdit(undefined);
    }

    renameCard(noteId: string, newTitle: string) {
        return server.put(`notes/${noteId}/title`, { title: newTitle.trim() });
    }

    /**
     * Copies a card into the board, the way the tree duplicates a note, and puts the copy straight
     * after the one it was made from.
     *
     * The copy carries the original's attributes, the grouping label among them, so it lands in the
     * same column without being told to. The wait is what makes the move possible: the branch is
     * named by the server and has to be in froca before it can be placed.
     */
    async duplicateItem(noteId: string, branchId: string) {
        const { note, branch } = await server.post<
            { note: { noteId: string }, branch: { branchId: string } }>(
                `notes/${noteId}/duplicate/${this.parentNote.noteId}`);

        this.keepInView(note?.noteId);
        await ws.waitForMaxKnownEntityChangeId();
        await branches.moveAfterBranch([ branch.branchId ], branchId);
    }

    /** Whether the grouping value comes from another note, such as a template or a parent. */
    private isInherited(note: FNote, type: "label" | "relation") {
        return note.getAttributes(type, this.statusAttribute)
            .some(attribute => attribute.noteId !== note.noteId);
    }

    /**
     * Whether the board draws the inbox column, which holds the cards with no grouping value.
     *
     * {@link removeFromBoard} clears that value, so a card lands in the inbox instead of leaving
     * the board, and one already there does not move at all.
     */
    get isInboxEnabled() {
        return !!this.parentNote?.isLabelTruthy("board:showInbox");
    }

    /**
     * Takes cards off the board, which leaves the notes where they are and only takes the grouping
     * value away. Written together, so a set does not leave a card at a time.
     */
    async removeFromBoard(noteIds: string[]) {
        await Promise.all(noteIds.map((noteId) => this.removeCardFromBoard(noteId)));
    }

    private removeCardFromBoard(noteId: string) {
        const note = froca.getNoteFromCache(noteId);
        if (!note) return;
        if (this.isRelationMode) {
            // A relation must point at a note, so an inherited one cannot be shadowed the way a
            // label is below. It can only be changed on the note that defines it.
            if (!note.getOwnedAttributes("relation", this.statusAttribute).length
                    && this.isInherited(note, "relation")) {
                toast.showMessage(t("board_view.inherited-column"), 3000);
                return;
            }

            return attributes.removeOwnedRelationByName(note, this.statusAttribute);
        }

        // An inherited value cannot be removed from the card, and removing the owned one would
        // only uncover it. An owned empty value shadows it instead, which counts as no value.
        if (this.isInherited(note, "label")) {
            return attributes.setLabel(noteId, this.statusAttribute, "");
        }

        return attributes.removeOwnedLabelByName(note, this.statusAttribute);
    }

    /** Whether a column orders its own cards rather than keeping the order the user set. */
    isColumnSorted(column: string) {
        return !!this.getEffectiveColumnSort(column).orderBy;
    }

    /**
     * Sends cards to the end of another column, where the ones the keyboard sends belong, keeping
     * the order they are given in.
     *
     * The grouping values go together rather than one after another, which is what keeps a set from
     * arriving a card at a time: each is a request of its own, and one at a time makes the wait the
     * sum of them. `moveAfterBranch` then places the whole set against one card, in order.
     */
    async moveToColumnEnd(cards: { noteId: string, branchId: string }[], targetColumn: string) {
        const arrived = cards.at(-1);
        if (!arrived) {
            return;
        }

        // What is already at the end, as far as this instance can know: nothing waits for the board
        // to redraw between two keystrokes, so the column map still shows the target as it was
        // before the cards the last press sent. Anything sent since is remembered here instead, and
        // the memory lasts exactly as long as the map it stands in for, both being rebuilt by the
        // refresh that catches up. Read before the writes below for the same reason.
        const last = this.sentToColumnEnd.get(targetColumn) ?? this.lastInColumn(targetColumn);

        await Promise.all(cards.map((card) => this.changeColumn(card.noteId, targetColumn)));

        // Only the grouping value is written for a sorted column: `sortColumnMap` decides where
        // its cards are drawn.
        if (this.isColumnSorted(targetColumn)) {
            return;
        }

        if (last && last !== arrived.branchId) {
            await branches.moveAfterBranch(cards.map((card) => card.branchId), last);
        }

        this.sentToColumnEnd.set(targetColumn, arrived.branchId);
    }

    /**
     * The notes a column draws, in the order it draws them.
     *
     * What a range selection is measured against, so a range covers only the cards the reader can
     * see and never reaches into another column.
     */
    getColumnNoteIds(column: string) {
        return (this.byColumn?.get(column) ?? []).map((item) => item.note.noteId);
    }

    /**
     * The cards named by `noteIds`, in the order the board draws them.
     *
     * A note the board is not drawing is left out, so a selection that has fallen behind a refresh
     * cannot make a command act on a card that is no longer there.
     */
    getCards(noteIds: ReadonlySet<string>) {
        const cards: ColumnItem[] = [];
        for (const items of this.byColumn?.values() ?? []) {
            for (const item of items) {
                if (noteIds.has(item.note.noteId)) {
                    cards.push(item);
                }
            }
        }

        return cards;
    }

    /** Which column a card stands in, or nothing where the board is not drawing the card. */
    getCardColumn(noteId: string) {
        for (const [ column, items ] of this.byColumn ?? []) {
            if (items.some((item) => item.note.noteId === noteId)) {
                return column;
            }
        }

        return undefined;
    }

    /**
     * Moves several cards into a column at one place, keeping the order they were drawn in.
     *
     * The grouping value is written for each card, then the branches are placed in one call:
     * `moveBeforeBranch` and `moveAfterBranch` both take the whole set and keep its order, so the
     * cards land together rather than each being placed against the one before it.
     */
    async moveWithinBoard(
        cards: { noteId: string, branchId: string }[], targetColumn: string, targetIndex: number
    ) {
        // A card the cache has never heard of is left out rather than written for.
        const moving = cards.filter((card) => froca.getNoteFromCache(card.noteId));
        if (!moving.length) {
            return;
        }

        // Read before the writes below: a redraw between them hands this instance the map with the
        // cards already moved.
        const targetItems = this.byColumn?.get(targetColumn) ?? [];
        const branchIds = moving.map((card) => card.branchId);
        const moved = new Set(branchIds);
        // The place is counted among the cards as they are drawn, which includes the ones being
        // moved. Each of those standing above it names one place that is about to close up.
        const above = targetItems.slice(0, targetIndex)
            .filter((item) => moved.has(item.branch.branchId)).length;
        const staying = targetItems.filter((item) => !moved.has(item.branch.branchId));
        const at = targetIndex - above;

        // The column as the board holds it, cards a filter hides included, which is what says
        // whether a card is arriving from elsewhere and whether this move changes anything.
        const whole = this.allByColumn?.get(targetColumn) ?? targetItems;
        const held = whole.map((item) => item.branch.branchId);

        // A move that leaves `targetItems` in the order it already holds writes nothing:
        // `moveBeforeBranch` places a card against a drawn neighbour, so under a filter it would
        // reorder the hidden cards instead.
        const standing = targetItems.map((item) => item.branch.branchId);
        const landing = [
            ...staying.slice(0, at).map((item) => item.branch.branchId),
            ...branchIds,
            ...staying.slice(at).map((item) => item.branch.branchId)
        ];
        if (landing.length === standing.length
                && landing.every((branchId, place) => branchId === standing[place])) {
            return;
        }

        // Only the cards arriving from elsewhere are written: one already under this column holds
        // the value already, and writing it again is a change the board has to redraw for.
        // Together rather than one after another, so a set does not arrive a card at a time.
        const arriving = moving.filter((card) => !held.includes(card.branchId));
        if (arriving.length) {
            await Promise.all(arriving.map((card) => this.changeColumn(card.noteId, targetColumn)));
        }

        // A sorted column places its own cards, so nothing is written against a card there.
        if (this.isColumnSorted(targetColumn)) {
            return;
        }

        const before = staying[at];
        if (before) {
            await branches.moveBeforeBranch(branchIds, before.branch.branchId);
            return;
        }

        // What the cards are placed after: the last one staying, or `lastInColumn`'s answer where
        // a filter draws none of them at all.
        const after = staying.at(-1)?.branch.branchId ?? this.lastInColumn(targetColumn);
        if (after && !moved.has(after)) {
            await branches.moveAfterBranch(branchIds, after);
        }
    }

    /** Whether a card stands at the head of its column, with nowhere left to be moved up to. */
    isFirstInColumn(branchId: string, column: string) {
        return this.byColumn?.get(column)?.[0]?.branch.branchId === branchId;
    }

    /**
     * The card a new or arriving one is placed after: the last one drawn, or `allByColumn`'s last
     * where a filter draws none. Placement follows the cards on screen wherever there are any.
     */
    private lastInColumn(column: string) {
        const shown = this.byColumn?.get(column) ?? [];
        const items = shown.length ? shown : this.allByColumn?.get(column) ?? [];
        return items.at(-1)?.branch.branchId;
    }

    /** The counterpart of {@link lastInColumn}, for a card made at the head of a column. */
    private firstInColumn(column: string) {
        const shown = this.byColumn?.get(column) ?? [];
        const items = shown.length ? shown : this.allByColumn?.get(column) ?? [];
        return items[0]?.branch.branchId;
    }

    /**
     * Moves a card to the head of the column it stands in, where Ctrl+Home also sends it.
     *
     * The card's own place is looked up here rather than asked of the caller: the menu is opened on
     * a card, which knows the column it is in but not where it stands among the others.
     */
    async moveToColumnStart(noteId: string, branchId: string, column: string) {
        if (this.isColumnSorted(column)) {
            return;
        }

        const items = this.byColumn?.get(column) ?? [];
        const at = items.findIndex(item => item.branch.branchId === branchId);
        if (at <= 0) {
            return;
        }

        await this.moveWithinBoard([ { noteId, branchId } ], column, 0);
    }

}

let bulkActions: Promise<typeof import("../../../services/bulk_action")> | undefined;

/** Loads the bulk action service once, whose dialogs a board has no use for until it edits. */
function loadBulkActions() {
    bulkActions ??= import("../../../services/bulk_action");
    return bulkActions;
}