Skip to content

Build your personal knowledge base with Trilium Notes

8.6 KB
Raw Blame
/** The HTML attribute with the id of a block in a text note. */
export const BLOCK_ID_ATTRIBUTE = "data-trilium-block-id";

/** The class of a multicolumn layout, a `<div>` whose child elements are its columns. */
export const MULTICOLUMN_LAYOUT_CLASS = "trilium-multicolumn-layout";

/** The class of a column of a multicolumn layout. */
export const MULTICOLUMN_COLUMN_CLASS = "trilium-multicolumn-column";

/** The blocks that a block reference points at. `startId` equals `endId` for a single block. */
export interface BlockRange {
    startId: string;
    endId: string;
}

/** A node of an HTML tree. The browser DOM and `node-html-parser` both match it. */
export interface BlockNode {
    parentNode: BlockNode | null;
    childNodes: ArrayLike<BlockNode>;
    tagName?: string;
    textContent?: string | null;
    getAttribute?(name: string): string | null | undefined;
    setAttribute?(name: string, value: string): unknown;
    remove?(): unknown;
    replaceWith?(...nodes: unknown[]): unknown;
}

/** Sibling nodes, children of `parent`, from `first` to `last`. */
export interface BlockRun<T extends BlockNode> {
    parent: T;
    first: T;
    last: T;
}

/** Whether `id` can be a block id. An id can be any text without `:`, the range separator. */
export function isValidBlockId(id: string | null | undefined): id is string {
    return !!id && !id.includes(":");
}

/** Parses the value of the `block` link parameter, `id` or `startId:endId`. */
export function parseBlockRange(value: string | null | undefined): BlockRange | null {
    const ids = value?.split(":") ?? [];
    if (ids.length < 1 || ids.length > 2 || ids.some((id) => !id)) {
        return null;
    }

    return { startId: ids[0], endId: ids[1] ?? ids[0] };
}

/** Formats `range` as the value of the `block` link parameter. */
export function formatBlockRange({ startId, endId }: BlockRange) {
    return startId === endId ? startId : `${startId}:${endId}`;
}

/** URI-encodes the value of the `block` link parameter, keeping the `:` between the ids. */
export function encodeBlockParameter(value: string) {
    return value.split(":").map(encodeURIComponent).join(":");
}

/**
 * Finds the first and the last block of `range` under `root`, in document order. A block that is
 * not found is `null`.
 */
export function resolveBlockRange<T extends BlockNode>(root: BlockNode, range: BlockRange) {
    let start: T | null = null;
    let end: T | null = null;
    let isEndFirst = false;

    for (const node of walk(root)) {
        const id = node.getAttribute?.(BLOCK_ID_ATTRIBUTE);
        if (!start && id === range.startId) {
            start = node as T;
        }
        if (!end && id === range.endId) {
            end = node as T;
            isEndFirst = !start;
        }
        if (start && end) {
            break;
        }
    }

    if (start && end && isEndFirst) {
        return { start: end, end: start };
    }
    return { start, end };
}

/** Finds the blocks that `value`, a `block` link parameter, points at, as `resolveBlockRange()`. */
export function resolveBlockReference<T extends BlockNode>(root: BlockNode, value: string) {
    const range = parseBlockRange(value);
    return range ? resolveBlockRange<T>(root, range) : { start: null, end: null };
}

/**
 * Keeps in `root` only the blocks that `value`, a `block` link parameter, points at, inside their
 * ancestors. A multicolumn layout left with one column is replaced by the column's content.
 * Returns `false` and changes nothing when a block is missing.
 */
export function sliceToBlockReference(root: BlockNode, value: string) {
    const { start, end } = resolveBlockReference(root, value);
    if (!start || !end) {
        return false;
    }

    sliceToBlockRange(root, start, end);
    return true;
}

/**
 * The sibling nodes under `root` that hold exactly the blocks that `value`, a `block` link
 * parameter, points at, so that they can be edited apart from the rest. Blocks that fill a list
 * item are its item. `null` when a block is missing, or when an ancestor of the blocks also holds
 * other content, as a list item does for a paragraph before the first block.
 */
export function getEditableBlockRun<T extends BlockNode>(
    root: T,
    value: string
): BlockRun<T> | null {
    const { start, end } = resolveBlockReference<T>(root, value);
    if (!start || !end) {
        return null;
    }

    const startPath = getPath(start, root);
    const endPath = getPath(end, root);
    let depth = 0;
    while (depth < startPath.length && startPath[depth] === endPath[depth]) {
        depth++;
    }

    const isNested = depth === startPath.length;
    const first = isNested ? start : startPath[depth];
    const last = isNested ? start : endPath[depth];
    const parent = first.parentNode as T;
    if (!isAtEdge(start, first, "first") || !isAtEdge(end, last, "last")) {
        return null;
    }

    if (isTag(parent, "LI") && isAtEdge(first, parent, "first") && isAtEdge(last, parent, "last")) {
        return { parent: parent.parentNode as T, first: parent, last: parent };
    }
    const isContainer = parent === root || RUN_CONTAINERS.has(String(parent.tagName).toUpperCase());
    return isContainer ? { parent, first, last } : null;
}

/**
 * The number that the item at `index` of the ordered `list` shows, as the browser numbers it. A
 * negative `index` counts on before the first item.
 */
export function getListItemNumber(list: BlockNode, index: number) {
    const isReversed = typeof list.getAttribute?.("reversed") === "string";
    const start = Number.parseInt(list.getAttribute?.("start") ?? "", 10);
    const itemCount = Array.from(list.childNodes).filter((node) => isTag(node, "LI")).length;
    const first = Number.isNaN(start) ? (isReversed ? itemCount : 1) : start;
    return isReversed ? first - index : first + index;
}

const RUN_CONTAINERS = new Set([
    "ASIDE", "BLOCKQUOTE", "DETAILS", "DIV", "LI", "OL", "SECTION", "UL"
]);

function getPath<T extends BlockNode>(node: T, root: BlockNode) {
    const path: T[] = [];
    for (let current: BlockNode = node; current !== root;) {
        path.unshift(current as T);
        current = current.parentNode as BlockNode;
    }
    return path;
}

function isAtEdge(node: BlockNode, ancestor: BlockNode, edge: "first" | "last") {
    for (let current = node; current !== ancestor;) {
        const parent = current.parentNode as BlockNode;
        const siblings = Array.from(parent.childNodes).filter(isContent);
        if (siblings.at(edge === "first" ? 0 : -1) !== current) {
            return false;
        }
        current = parent;
    }
    return true;
}

/** Whether `node` has text, or is an element other than a label, such as a to-do checkbox. */
function isContent(node: BlockNode) {
    return !!node.textContent?.trim() || (!!node.tagName && !isTag(node, "LABEL"));
}

function sliceToBlockRange(root: BlockNode, start: BlockNode, end: BlockNode) {
    for (let node = start; node !== root && node.parentNode; node = node.parentNode) {
        const siblings = Array.from(node.parentNode.childNodes);
        const removed = siblings.slice(0, siblings.indexOf(node));
        keepListNumbering(node.parentNode, removed.filter((other) => isTag(other, "LI")).length);
        removeNodes(removed);
    }

    for (let node = end; node !== root && node.parentNode; node = node.parentNode) {
        const siblings = Array.from(node.parentNode.childNodes);
        removeNodes(siblings.slice(siblings.indexOf(node) + 1));
    }

    for (const node of new Set([ ...getPath(start, root), ...getPath(end, root) ])) {
        unwrapSingleColumnLayout(node);
    }
}

/** Replaces `node`, when it is a multicolumn layout with one column, by the column's content. */
function unwrapSingleColumnLayout(node: BlockNode) {
    const isLayout = node.getAttribute?.("class")?.split(/\s+/).includes(MULTICOLUMN_LAYOUT_CLASS);
    const columns = Array.from(node.childNodes).filter((child) => child.tagName);
    if (isLayout && columns.length === 1) {
        node.replaceWith?.(...Array.from(columns[0].childNodes));
    }
}

function* walk(node: BlockNode): Generator<BlockNode> {
    for (const child of Array.from(node.childNodes)) {
        yield child;
        yield* walk(child);
    }
}

function removeNodes(nodes: BlockNode[]) {
    for (const node of nodes) {
        node.remove?.();
    }
}

/** Sets the `start` of `list` so that its item at `index` keeps its number once it comes first. */
function keepListNumbering(list: BlockNode, index: number) {
    if (isTag(list, "OL")) {
        list.setAttribute?.("start", String(getListItemNumber(list, index)));
    }
}

function isTag(node: BlockNode, tagName: string) {
    return node.tagName?.toUpperCase() === tagName;
}