Skip to content

Build your personal knowledge base with Trilium Notes

17.6 KB
Raw Blame
import FBranch from "../../../entities/fbranch";
import FNote from "../../../entities/fnote";
import type LoadResults from "../../../services/load_results";
import type { PromotedAttribute } from "../promoted_attributes";
import {
    DEFAULT_SORT, parseStoredSortKey, sortedAttributeName, sortItems, type SortContext,
    type SortKey
} from "../sorting";
import { readColumns, writeColumns } from "./column_storage";
import { INBOX_COLUMN, resolveBoardColumns } from "./columns";
import { BoardColumnData, BoardViewData } from "./index";

export interface ColumnItem {
    branch: FBranch;
    note: FNote;
}

export type ColumnMap = Map<string, ColumnItem[]>;

/**
 * The columns as they stand once cards have moved, for drawing the outcome before the writes land.
 *
 * A card crossing columns is written twice, the value first and the branch after, and each lands a
 * redraw of its own. The first shows the card in its new column at whatever place its old branch
 * gives it, which is above every card already there.
 *
 * The cards keep the order `noteIds` lists them in, wherever they came from, and land together.
 * A card the board does not hold is left out; where that is all of them, the map is handed back as
 * it stands.
 *
 * @param index where the cards go, counting the target column as it stands at the moment of the
 *              drop, the cards being moved included where they do not leave that column.
 */
export function applyCardMoves(
    byColumn: ColumnMap, noteIds: string[], to: string, index: number
): ColumnMap {
    const moving = new Set(noteIds);
    const next: ColumnMap = new Map();
    const picked = new Map<string, ColumnItem>();

    for (const [ column, items ] of byColumn) {
        const kept: ColumnItem[] = [];
        for (const item of items) {
            if (moving.has(item.note.noteId)) {
                picked.set(item.note.noteId, item);
            } else {
                kept.push(item);
            }
        }

        next.set(column, kept);
    }

    if (!picked.size) {
        return byColumn;
    }

    // Taking the cards out shifts everything below them up, so a place counted with them still in
    // the column names one card earlier for each of them standing above it.
    const above = (byColumn.get(to) ?? []).slice(0, index)
        .filter((item) => moving.has(item.note.noteId)).length;
    const target = next.get(to) ?? [];
    target.splice(index - above, 0,
        ...noteIds.flatMap((noteId) => picked.get(noteId) ?? []));
    next.set(to, target);

    return next;
}

/**
 * The columns with only the cards in `shownNoteIds`, keeping their order relative to each other.
 * Every column is kept, since a filter narrows what is drawn and nothing else.
 */
export function filterColumnMap(
    byColumn: ColumnMap, shownNoteIds: Set<string> | null
): ColumnMap {
    if (!shownNoteIds) {
        return byColumn;
    }

    const filtered: ColumnMap = new Map();
    for (const [ column, items ] of byColumn) {
        filtered.set(column, items.filter(item => shownNoteIds.has(item.note.noteId)));
    }
    return filtered;
}

/** How one column orders its cards. */
export interface ColumnSort {
    orderBy: SortKey;
    isDescending: boolean;
}

/** What a sorted board reads, so it can be reloaded and watched for changes. */
export interface SortWatch {
    /** The cards in sorted columns, whose creation dates the tie-break reads. */
    noteIds: Set<string>;
    /** The relation targets whose titles a column sorts by. */
    targetNoteIds: Set<string>;
    /** The attribute names the columns sort by. */
    attributeNames: Set<string>;
}

/**
 * What each column sorts by, leaving out every column that keeps the manual order.
 *
 * @param defaultSort the order the board holds, which a column takes until it is given one of its
 *                    own. Such a column keeps the manual order while the board holds none.
 * @param drawnColumns every column the board shows, since one the config says nothing about takes
 *                     the board's order like the rest.
 */
export function resolveColumnSorts(
    columns: BoardColumnData[] | undefined, defaultSort?: ColumnSort, drawnColumns?: string[]
) {
    const sorts = new Map<string, ColumnSort>();
    const stored = new Map((columns ?? []).map(column => [ column.value, column ]));

    for (const value of new Set([ ...drawnColumns ?? [], ...stored.keys() ])) {
        const entry = stored.get(value);
        const key = parseStoredSortKey(entry?.orderBy);

        if (key === DEFAULT_SORT) {
            if (defaultSort) {
                sorts.set(value, defaultSort);
            }
        } else if (key) {
            sorts.set(value, { orderBy: key, isDescending: !!entry?.descendingOrder });
        }
    }

    return sorts;
}

/**
 * The columns with each sorted one in its own order.
 *
 * Returns the same map, and the same array per column, where nothing moves. `Column` reads a fresh
 * array as its cards having moved and re-measures every one of them, so the identities matter.
 */
export function sortColumnMap(
    byColumn: ColumnMap, sorts: ReadonlyMap<string, ColumnSort>, context: SortContext
): ColumnMap {
    let sorted: ColumnMap | undefined;

    for (const [ column, { orderBy, isDescending } ] of sorts) {
        const items = byColumn.get(column);
        if (!items) {
            continue;
        }

        const ordered = sortItems(items, orderBy, isDescending, context);
        if (ordered !== items) {
            sorted ??= new Map(byColumn);
            sorted.set(column, ordered);
        }
    }

    return sorted ?? byColumn;
}

/**
 * The notes a sorted board reads, and the attributes it reads off them.
 *
 * @param definitions the board's promoted attributes by name, which say which keys are relations.
 */
export function resolveSortWatch(
    byColumn: ColumnMap | undefined,
    sorts: ReadonlyMap<string, ColumnSort>,
    definitions: ReadonlyMap<string, PromotedAttribute>
): SortWatch {
    const noteIds = new Set<string>();
    const targetNoteIds = new Set<string>();
    const attributeNames = new Set<string>();

    for (const [ column, { orderBy } ] of sorts) {
        const name = sortedAttributeName(orderBy);
        const relation = name && definitions.get(name)?.type === "relation" ? name : undefined;
        if (name) {
            attributeNames.add(name);
        }

        for (const { note } of byColumn?.get(column) ?? []) {
            noteIds.add(note.noteId);

            const target = relation && note.getRelationValue(relation);
            if (target) {
                targetNoteIds.add(target);
            }
        }
    }

    return { noteIds, targetNoteIds, attributeNames };
}

/**
 * Whether a change can move a card in a sorted column.
 *
 * Deliberately broad: an autosave reports a note row just as a rename does, and
 * {@link sortColumnMap} returns the same arrays when nothing moves, so a needless re-sort renders
 * nothing.
 */
export function affectsSortOrder(loadResults: LoadResults, watch: SortWatch) {
    if (!watch.noteIds.size) {
        return false;
    }

    const isWatched = (noteId: string) =>
        watch.noteIds.has(noteId) || watch.targetNoteIds.has(noteId);
    if (loadResults.getNoteIds().some(isWatched)) {
        return true;
    }

    return loadResults.getAttributeRows().some(attr =>
        watch.attributeNames.has(attr.name ?? "") && watch.noteIds.has(attr.noteId ?? ""));
}

/**
 * Where a card dropped among the cards on screen goes in the full column.
 *
 * @param shown the target column as it is drawn, counting the moved card where it stays in place.
 * @param all the same column with every card it holds.
 * @param index where the card goes among the ones drawn.
 */
export function unfilteredCardIndex(shown: ColumnItem[], all: ColumnItem[], index: number) {
    const placeOf = (item: ColumnItem | undefined) => (item
        ? all.findIndex(other => other.branch.branchId === item.branch.branchId)
        : -1);

    const before = placeOf(shown[index]);
    if (before >= 0) {
        return before;
    }

    // Dropped past the last card on screen, which is what the move is written against; a hidden
    // card below it stays below.
    const after = placeOf(shown.at(-1));
    return after >= 0 ? after + 1 : all.length;
}

/**
 * @param definitionOptions the choices the board's group-by definition offers, empty when it has no
 *                          select definition of its own to lead the column order.
 * @param pendingRenames the columns the board is in the middle of renaming or deleting. Read
 *                       only: which of them have landed comes back as `settledRenames`, for the
 *                       caller to drop once it knows the answer is still about the board it asked
 *                       about.
 */
export async function getBoardData(
    parentNote: FNote,
    groupByColumn: string,
    persistedData: BoardViewData,
    includeArchived: boolean,
    definitionOptions: string[] = [],
    pendingRenames: ReadonlyMap<string, string | undefined> = new Map(),
    /** Whether the board keeps an inbox, which decides whether unassigned notes are collected. */
    inboxEnabled = false,
    /** How many levels below its children the board collects cards from, unlimited if absent. */
    maxDepth?: number
) {
    const byColumn: ColumnMap = new Map();
    const storedColumns = readColumns(persistedData, groupByColumn) ?? [];
    const storedColumnValues = storedColumns.map(c => c.value);
    // Turning the inbox on adds it to the board, at the front. After that the entry belongs to
    // the config: it keeps its icon, colour and position, and turning the inbox off leaves it in
    // place.
    const persistedColumns = inboxEnabled && !storedColumnValues.includes(INBOX_COLUMN)
        ? [ INBOX_COLUMN, ...storedColumnValues ]
        : storedColumnValues;

    // Only a board with an inbox has somewhere to put an unassigned note; on any other board such
    // a note is not shown at all, as before.
    const inbox = inboxEnabled
        ? { nested: !!storedColumns.find(col => col.value === INBOX_COLUMN)?.nested }
        : undefined;

    // First, scan all notes to find what columns actually exist
    await recursiveGroupBy(
        parentNote.getChildBranches(), byColumn, groupByColumn, includeArchived,
        new Set<string>(), inbox, 0, maxDepth);

    const discoveredValues = [ ...byColumn.keys() ];
    const columns = resolveBoardColumns(
        definitionOptions, persistedColumns, discoveredValues, pendingRenames);

    // A value no source lists any more has finished being renamed, and holding it back further
    // would only block a column created under the same name.
    const settledRenames = [ ...pendingRenames.keys() ].filter(oldValue =>
        ![ definitionOptions, persistedColumns, discoveredValues ]
            .some(source => source.includes(oldValue)));

    // A card the bulk action has not reached yet is still filed under the old value, and belongs to
    // the column that replaced it rather than to one `columns` no longer lists.
    regroupRenamedCards(byColumn, pendingRenames);

    // A column the notes have nothing in is still a column, so every resolved one gets an entry.
    for (const column of columns) {
        if (!byColumn.has(column)) {
            byColumn.set(column, []);
        }
    }

    // The attachment mirrors the resolved list, so a board whose columns now come from its definition
    // stays readable by anything still reading the attachment. Written only when it actually differs,
    // or every refresh would save.
    const hasChanges = storedColumnValues.length !== columns.length
        || storedColumnValues.some((value, index) => columns[index] !== value);
    const byResolvedName = indexColumnsByResolvedName(storedColumns, pendingRenames);

    return {
        byColumn,
        columns,
        settledRenames,
        newPersistedData: hasChanges
            ? writeColumns(persistedData, groupByColumn,
                columns.map(value => byResolvedName.get(value) ?? { value }))
            : undefined,
        isInRelationMode: groupByColumn.startsWith("~")
    };
}

/**
 * The stored column entries, each under the name it now resolves to.
 *
 * An entry holds more than the name, so rebuilding the config from the resolved names alone would
 * drop the icon of every column on any refresh that rewrites it. A rename carries the entry across
 * to the new name, the same substitution {@link resolveBoardColumns} makes.
 */
function indexColumnsByResolvedName(
    storedColumns: BoardColumnData[],
    pendingRenames: ReadonlyMap<string, string | undefined>
) {
    const byName = new Map<string, BoardColumnData>();

    for (const column of storedColumns) {
        const { value } = column;
        const name = pendingRenames.has(value) ? pendingRenames.get(value) : value;
        if (name !== undefined) {
            byName.set(name, { ...column, value: name });
        }
    }

    return byName;
}

/** Moves the cards of a renamed column over to its new name, keeping the order they were in. */
function regroupRenamedCards(
    byColumn: ColumnMap,
    pendingRenames: ReadonlyMap<string, string | undefined>
) {
    for (const [ oldValue, newValue ] of pendingRenames) {
        const items = byColumn.get(oldValue);
        if (!items || !newValue) continue;

        byColumn.delete(oldValue);
        byColumn.set(newValue, [ ...(byColumn.get(newValue) ?? []), ...items ]);
    }
}

/**
 * @param inbox where unassigned notes are collected, absent if the board has no inbox.
 * @param depth how deep below the board the branches are, the board's own children being 0.
 * @param maxDepth the deepest `depth` collected, unlimited if absent or negative.
 */
async function recursiveGroupBy(
    branches: FBranch[], byColumn: ColumnMap, groupByColumn: string, includeArchived: boolean,
    seenNoteIds: Set<string>, inbox: { nested: boolean } | undefined, depth: number,
    maxDepth: number | undefined
) {
    for (const branch of branches) {
        const note = await branch.getNote();
        if (!note || (!includeArchived && note.isArchived)) continue;

        // A template is what a card is made from, not a card. One made from the board's own
        // properties is filed under it, and the inbox would otherwise collect it as one.
        const isTemplate = note.hasLabel("template");

        const canDescend = maxDepth === undefined || maxDepth < 0 || depth < maxDepth;
        if (canDescend && note.type !== "search" && note.hasChildren()) {
            await recursiveGroupBy(
                note.getChildBranches(), byColumn, groupByColumn, includeArchived,
                seenNoteIds, inbox, depth + 1, maxDepth);
        }

        // A note with no value goes to the inbox, if the board has one and reaches this deep.
        // Anything below the board's own children is a card's child, collected only when nested.
        const value = note.getLabelOrRelation(groupByColumn);
        const group = value || (inbox && (depth === 0 || inbox.nested) ? INBOX_COLUMN : undefined);
        if (group === undefined || isTemplate || seenNoteIds.has(note.noteId)) {
            continue;
        }

        if (!byColumn.has(group)) {
            byColumn.set(group, []);
        }

        byColumn.get(group)!.push({
            branch,
            note
        });
        seenNoteIds.add(note.noteId);
    }
}

/**
 * The notes whose attributes can reach a card, split the way `attributes.isAffecting()` checks
 * them: `own` holds each card and its `~template` and `~inherit` targets, and `ancestors` also
 * holds every note above those, following templates, which only an inheritable attribute reaches
 * from.
 */
export interface DefinitionSources {
    own: Set<string>;
    ancestors: Set<string>;
}

/** Collects the {@link DefinitionSources} of `cards`, visiting each note once. */
export function definitionSources(cards: Iterable<FNote>): DefinitionSources {
    const own = new Set<string>();
    const ancestors = new Set<string>();
    const pending: FNote[] = [];

    for (const card of cards) {
        own.add(card.noteId);
        pending.push(card);
        for (const source of card.getNotesToInheritAttributesFrom()) {
            if (source) {
                own.add(source.noteId);
            }
        }
    }

    for (let note = pending.pop(); note; note = pending.pop()) {
        if (ancestors.has(note.noteId)) {
            continue;
        }
        ancestors.add(note.noteId);
        pending.push(...note.getNotesToInheritAttributesFrom().filter(Boolean),
            ...note.getParentNotes());
    }

    return { own, ancestors };
}

/**
 * Whether a change can alter the definitions that reach a card: a definition, or a `~template` or
 * `~inherit` relation, on a note in `sources`. Equivalent to `attributes.isAffecting()` against
 * every card, at the cost of one lookup per changed attribute.
 */
export function affectsCardDefinitions(loadResults: LoadResults, sources: DefinitionSources) {
    return loadResults.getAttributeRows().some((attr) => isDefinitionSource(attr.name)
        && !!attr.noteId
        && (sources.own.has(attr.noteId)
            || (!!attr.isInheritable && sources.ancestors.has(attr.noteId))));
}

/** Returns whether an attribute with this name can change a note's `getAttributeDefinitions()`. */
function isDefinitionSource(name: string | undefined) {
    return !!name && (name.startsWith("label:") || name.startsWith("relation:")
        || name === "template" || name === "inherit");
}

/** Returns the note of every card in `byColumn`, once per note. */
export function cardNotes(byColumn: ColumnMap | undefined): Set<FNote> {
    const notes = new Set<FNote>();
    for (const items of byColumn?.values() ?? []) {
        for (const { note } of items) {
            notes.add(note);
        }
    }
    return notes;
}