Skip to content

Build your personal knowledge base with Trilium Notes

24.6 KB
Raw Blame
import "../theme/collapsible_list_items.css";

import {
    Command,
    DomEventObserver,
    ListEditing,
    MouseObserver,
    Plugin,
    type Editor,
    type EnterCommand,
    type ListSplitCommand,
    type ModelElement,
    type ModelNode,
    type ModelPosition,
    type ModelWriter,
    type ViewDocumentDomEventData,
    type ViewDocumentEnterEvent,
    type ViewDocumentMouseDownEvent,
    type ViewDocumentMouseOutEvent,
    type ViewElement
} from "ckeditor5";

import FindReveal from "./find_reveal.js";

export const LIST_COLLAPSED_ATTRIBUTE = "listCollapsed";

const COLLAPSED_DATA_ATTRIBUTE = "data-trilium-collapsed";

/** Marks the item whose arrow the pointer is on, so the stylesheet can give it a filled circle. */
const ARROW_HOVERED_CLASS = "trilium-list-arrow-hovered";

/**
 * View-only class placed on a collapsed `<li>` whose hidden children are temporarily shown to
 * reveal a find-in-note match inside them. It only exists in the editing view (the hiding CSS
 * opts out when it is present), so the persisted `data-trilium-collapsed` state is never touched.
 */
const TEMPORARILY_EXPANDED_CLASS = "trilium-list-temporarily-expanded";

/**
 * Allows collapsing/expanding nested list items, similar to outliners such as Dynalist or Roam.
 *
 * The collapsed state is kept as a `listCollapsed` model attribute, persisted into the note
 * content as `data-trilium-collapsed="true"` on the `<li>`. Hiding the nested items is done by
 * CSS scoped to the editing view, so read-only and shared note rendering stay fully expanded.
 */
export default class CollapsibleListItems extends Plugin {

    private _hoveredArrowItem: ViewElement | null = null;
    /** Collapsed list items currently force-expanded (view-only) to reveal a find highlight. */
    private readonly _findRevealed = new Set<ModelElement>();
    /**
     * True only for the microtask in which find is closing. Closing drops the caret onto the match
     * (see find_in_text.findBoxClosed); without this, that caret landing inside a re-collapsed item
     * would make {@link _enableAutoExpand} permanently expand it. While set, the caret is moved to
     * the collapsed item's line instead — the way the collapsible <details> reveal leaves it.
     */
    private _findClosing = false;

    static get requires() {
        return [ ListEditing, FindReveal ] as const;
    }

    init() {
        const editor = this.editor;

        editor.model.schema.extend("$block", {allowAttributes: LIST_COLLAPSED_ATTRIBUTE});

        editor.commands.add("toggleListCollapse", new ToggleListCollapseCommand(editor));

        editor.plugins.get(ListEditing).registerDowncastStrategy({
            scope: "item",
            attributeName: LIST_COLLAPSED_ATTRIBUTE,
            setAttributeOnDowncast(writer, value, element) {
                if (value) {
                    writer.setAttribute(COLLAPSED_DATA_ATTRIBUTE, "true", element);
                } else {
                    writer.removeAttribute(COLLAPSED_DATA_ATTRIBUTE, element);
                }
            }
        });

        editor.conversion.for("upcast").attributeToAttribute({
            view: {name: "li", key: COLLAPSED_DATA_ATTRIBUTE},
            model: {
                key: LIST_COLLAPSED_ATTRIBUTE,
                value: (viewElement: ViewElement) => viewElement.getAttribute(COLLAPSED_DATA_ATTRIBUTE) === "true" ? true : null
            }
        });

        this._enableToggleOnGutterClick();
        this._enableArrowHoverFeedback();
        this._enableToggleOnKeystroke();
        this._enableEnterAfterCollapsedItem();
        this._enableAutoExpand();
        this._enableFindReveal();
    }

    /**
     * Temporarily reveals a collapsed item's hidden children while a find-in-note highlight sits
     * inside them, re-collapsing once the highlight moves away — the same treatment collapsible
     * `<details>` blocks get. Unlike {@link _enableAutoExpand} (which permanently drops the
     * collapsed state when the caret enters a hidden block), this is view-only and never touches
     * the persisted attribute: search must not rewrite the user's collapsed layout.
     */
    private _enableFindReveal() {
        const findReveal = this.editor.plugins.get(FindReveal);
        this.listenTo(findReveal, "change:position", (_evt, _name, position) => {
            this._syncFindReveal(position);
        });
    }

    /**
     * Reconcile {@link _findRevealed} with the collapsed items hiding `position`, the match the
     * find shows: reveal ancestors newly hiding it, re-collapse ones that no longer do. A `null`
     * position (search cleared) collapses everything.
     */
    private _syncFindReveal(position: ModelPosition | null) {
        const wanted = new Set<ModelElement>();
        const block = position?.parent;
        // getCollapsedAncestors tolerates any block (a non-list block has no collapsed ancestors),
        // so no list-specific guard is needed beyond narrowing the position parent to an element.
        if (block?.is("element")) {
            for (const ancestor of getCollapsedAncestors(block)) {
                wanted.add(ancestor);
            }
        }

        // A cleared position means find is closing (or moving off): flag the current microtask so
        // the caret it is about to drop on the match doesn't permanently expand the item that
        // {@link _enableAutoExpand} would otherwise open. Reset after the tick, so it only affects
        // that synchronous caret landing and never a later real navigation.
        if (!position) {
            this._findClosing = true;
            void Promise.resolve().then(() => {
                this._findClosing = false;
            });
        }

        for (const revealed of this._findRevealed) {
            if (!wanted.has(revealed)) {
                this._applyFindReveal(revealed, false);
                this._findRevealed.delete(revealed);
            }
        }
        for (const target of wanted) {
            if (!this._findRevealed.has(target)) {
                this._findRevealed.add(target);
                this._applyFindReveal(target, true);
            }
        }
    }

    /** Add or remove the view-only "temporarily expanded" class on the collapsed item's `<li>`. */
    private _applyFindReveal(block: ModelElement, reveal: boolean) {
        const viewItem = this.editor.editing.mapper.toViewElement(block)?.findAncestor("li");
        /* v8 ignore next 3 -- defensive: a rendered collapsed ancestor always maps to its <li>. */
        if (!viewItem) {
            return;
        }
        this.editor.editing.view.change((writer) => {
            if (reveal) {
                writer.addClass(TEMPORARILY_EXPANDED_CLASS, viewItem);
            } else {
                writer.removeClass(TEMPORARILY_EXPANDED_CLASS, viewItem);
            }
        });
    }

    /**
     * Toggles the collapsed state on Ctrl+Alt+Enter, uniformly for every list type. Ctrl+Enter is
     * deliberately avoided: it is already the native to-do "check item" shortcut (and a Trilium
     * global), so collapse gets its own conflict-free binding rather than fighting over it.
     */
    private _enableToggleOnKeystroke() {
        const editor = this.editor;

        editor.keystrokes.set("Ctrl+Alt+Enter", (_data, cancel) => {
            const command = editor.commands.get("toggleListCollapse");
            if (!command?.isEnabled) {
                return;
            }
            editor.execute("toggleListCollapse");
            cancel();
        });
    }

    /** Moves new list siblings after hidden descendants for both CKEditor Enter command paths. */
    private _enableEnterAfterCollapsedItem() {
        const editor = this.editor;
        const enterCommand = editor.commands.get("enter") as EnterCommand;
        const splitCommand = editor.commands.get("splitListItemBefore") as ListSplitCommand;
        let pendingEnterSplit: ModelElement | null = null;

        // ListEditing handles an empty final block with splitListItemBefore and stops the event,
        // so EnterCommand never runs on that path.
        this.listenTo<ViewDocumentEnterEvent>(
            editor.editing.view.document, "enter", (_evt, data) => {
                if (data.isSoft) {
                    pendingEnterSplit = null;
                    return;
                }
                const selectedBlock = getSelectedListBlock(editor);
                pendingEnterSplit = selectedBlock?.isEmpty
                    && selectedBlock.getAttribute(LIST_COLLAPSED_ATTRIBUTE) === true
                    && hasNestedItems(selectedBlock)
                    ? selectedBlock
                    : null;

                if (pendingEnterSplit) {
                    // The split command runs synchronously; clear state if another listener
                    // handles Enter.
                    void Promise.resolve().then(() => {
                        pendingEnterSplit = null;
                    });
                }
            }, { context: "li", priority: "high" }
        );

        this.listenTo(splitCommand, "afterExecute", () => {
            if (!pendingEnterSplit || pendingEnterSplit !== getSelectedListBlock(editor)) {
                return;
            }
            pendingEnterSplit = null;
            editor.model.change((writer) => this._moveItemAfterCollapsedDescendants(writer));
        });

        this.listenTo(enterCommand, "afterExecute", (_evt, data: { writer: ModelWriter }) => {
            this._moveItemAfterCollapsedDescendants(data.writer);
        });
    }

    /**
     * Moves the item Enter creates in a collapsed list item after that item's hidden descendants.
     */
    private _moveItemAfterCollapsedDescendants(writer: ModelWriter) {
        const block = getSelectedListBlock(this.editor);
        if (!block || !block.isEmpty) {
            return;
        }

        const previousBlock = block.previousSibling;
        if (!isListBlock(previousBlock)
            || previousBlock.getAttribute(LIST_COLLAPSED_ATTRIBUTE) !== true
            || previousBlock.getAttribute("listItemId") === block.getAttribute("listItemId")) {
            return;
        }

        const lastNestedBlock = getNestedBlocks(block).at(-1);
        if (!lastNestedBlock) {
            return;
        }
        writer.move(writer.createRangeOn(block), writer.createPositionAfter(lastNestedBlock));
    }

    /**
     * Toggles the collapsed state when the arrow rendered in the gutter next to a list item is
     * clicked.
     */
    private _enableToggleOnGutterClick() {
        const editor = this.editor;
        const view = editor.editing.view;

        view.addObserver(MouseObserver);

        this.listenTo<ViewDocumentMouseDownEvent>(view.document, "mousedown", (evt, data) => {
            const block = getArrowBlockAtPointer(editor, data);
            if (!block) {
                return;
            }

            // Keep the caret where it is instead of moving it to the clicked item.
            data.preventDefault();
            evt.stop();
            toggleCollapsed(editor, block);
        });
    }

    /**
     * Fills the arrow into a circle while the pointer rests on it. CSS cannot match a hovered
     * pseudo-element, so the item carries a class instead, set from the same gutter geometry the
     * click handler uses — pointer feedback and click target can therefore never drift apart.
     */
    private _enableArrowHoverFeedback() {
        const editor = this.editor;
        const view = editor.editing.view;

        view.addObserver(MouseMoveObserver);

        this.listenTo<ViewDocumentMouseMoveEvent>(view.document, "mousemove", (_evt, data) => {
            // A held button means a drag (selecting text); leave the view untouched until it ends.
            const onArrow = data.domEvent.buttons === 0 && !!getArrowBlockAtPointer(editor, data);
            this._setArrowHovered(onArrow ? data.target : null);
        });

        // Leaving the editable ends the stream of mouse moves, so the flag is dropped here
        // instead — otherwise an arrow the pointer left sideways would stay lit.
        this.listenTo<ViewDocumentMouseOutEvent>(view.document, "mouseout", (_evt, data) => {
            const domRoot = view.getDomRoot();
            const movedTo = data.domEvent.relatedTarget;
            if (!domRoot || !(movedTo instanceof Node) || !domRoot.contains(movedTo)) {
                this._setArrowHovered(null);
            }
        });
    }

    private _setArrowHovered(viewItem: ViewElement | null) {
        if (viewItem === this._hoveredArrowItem) {
            return;
        }

        const previousItem = this._hoveredArrowItem;
        this._hoveredArrowItem = viewItem;

        this.editor.editing.view.change((writer) => {
            if (previousItem) {
                writer.removeClass(ARROW_HOVERED_CLASS, previousItem);
            }
            if (viewItem) {
                writer.addClass(ARROW_HOVERED_CLASS, viewItem);
            }
        });
    }

    /**
     * Expands collapsed ancestors whenever content would otherwise become (or stay) invisible:
     * when the selection lands inside a hidden block (arrow keys, find & replace, a backspace
     * merge) and when blocks are placed under a collapsed parent (indent, paste, move).
     */
    private _enableAutoExpand() {
        const editor = this.editor;
        const model = editor.model;

        this.listenTo(model.document.selection, "change:range", () => {
            const block = model.document.selection.getFirstPosition()?.parent;
            if (!block || !block.is("element") || !block.hasAttribute("listItemId")) {
                return;
            }

            const collapsedAncestors = getCollapsedAncestors(block);
            if (collapsedAncestors.length === 0) {
                return;
            }

            if (this._findClosing) {
                // Find is closing and dropped the caret on the match inside a re-collapsed item.
                // Keep the saved layout collapsed: move the caret to the outermost collapsed
                // ancestor's line instead of expanding (mirrors the <details> reveal on close).
                const outermost = collapsedAncestors[collapsedAncestors.length - 1];
                model.enqueueChange({isUndoable: false}, (writer) => {
                    writer.setSelection(writer.createPositionAt(outermost, 0));
                });
                return;
            }

            model.enqueueChange({isUndoable: false}, (writer) => {
                for (const ancestor of collapsedAncestors) {
                    expandItem(writer, ancestor);
                }
            });
        });

        model.document.registerPostFixer((writer) => {
            const insertedNodes = new Set<ModelNode>();
            const changedBlocks = new Set<ModelElement>();

            for (const entry of model.document.differ.getChanges()) {
                if (entry.type === "insert") {
                    let node: ModelNode | null = entry.position.nodeAfter;
                    for (let i = 0; i < entry.length && node; i++, node = node.nextSibling) {
                        insertedNodes.add(node);
                        if (node.is("element") && node.hasAttribute("listItemId")) {
                            changedBlocks.add(node);
                        }
                    }
                } else if (entry.type === "attribute" && (entry.attributeKey === "listIndent" || entry.attributeKey === "listItemId")) {
                    const node = entry.range.start.nodeAfter;
                    /* v8 ignore next -- defensive: the differ always reports a list block-attribute change with the affected block as range.start.nodeAfter, so `node` is never null here (the falsy branch is unreachable from any model operation). */
                    if (node && node.is("element") && node.hasAttribute("listItemId")) {
                        changedBlocks.add(node);
                    }
                }
            }

            let changed = false;
            for (const block of changedBlocks) {
                for (const ancestor of getCollapsedAncestors(block)) {
                    // An ancestor inserted in the same change set arrived together with its
                    // hidden children (data load, paste of a collapsed subtree) — keep it.
                    if (insertedNodes.has(ancestor)) {
                        continue;
                    }
                    expandItem(writer, ancestor);
                    changed = true;
                }
                // Splitting a collapsed item (e.g. pressing Enter) copies the attribute onto the
                // new block; drop it again when the new item has nothing to collapse.
                if (block.getAttribute(LIST_COLLAPSED_ATTRIBUTE) && !hasNestedItems(block)) {
                    writer.removeAttribute(LIST_COLLAPSED_ATTRIBUTE, block);
                    changed = true;
                }
            }

            return changed;
        });
    }

}

/**
 * Toggles the collapsed state of the list item under the selection. Exposed as
 * `toggleListCollapse` for keyboard shortcuts and scripting.
 */
export class ToggleListCollapseCommand extends Command {

    declare public value: boolean;

    refresh() {
        const block = getSelectedListBlock(this.editor);
        this.isEnabled = !!block && hasNestedItems(block);
        this.value = !!block?.getAttribute(LIST_COLLAPSED_ATTRIBUTE);
    }

    execute() {
        const block = getSelectedListBlock(this.editor);
        if (block && hasNestedItems(block)) {
            toggleCollapsed(this.editor, block);
        }
    }

}

/** `MouseObserver` covers mousedown/up/over/out, but not the moves the hover feedback needs. */
class MouseMoveObserver extends DomEventObserver<"mousemove"> {

    public readonly domEventType = ["mousemove"] as const;

    public onDomEvent(domEvent: MouseEvent) {
        this.fire(domEvent.type, domEvent);
    }

}

type ViewDocumentMouseMoveEvent = {
    name: "mousemove";
    args: [data: ViewDocumentDomEventData<MouseEvent>];
};

/**
 * The collapsible list item whose arrow the pointer is on, if any.
 *
 * The arrow is the item's `::before` pseudo-element, laid out entirely outside the `<li>`'s
 * border box, so it is the only thing that can be hit at an x beyond the box while the event
 * still targets the `<li>` — whichever side the gutter is on (it follows the text direction).
 */
function getArrowBlockAtPointer(editor: Editor, data: ViewDocumentDomEventData<MouseEvent>): ModelElement | null {
    const viewItem = data.target;
    if (!viewItem || !viewItem.is("element", "li")) {
        return null;
    }

    const rect = (data.domTarget as HTMLElement).getBoundingClientRect();
    const { clientX } = data.domEvent;
    if (clientX >= rect.left && clientX <= rect.right) {
        return null;
    }

    const block = getListBlockFromViewListItem(editor, viewItem);
    return block && hasNestedItems(block) ? block : null;
}

function toggleCollapsed(editor: Editor, block: ModelElement): void {
    const collapse = !block.getAttribute(LIST_COLLAPSED_ATTRIBUTE);
    const itemBlocks = getItemBlocks(block);
    const nestedBlocks = getNestedBlocks(block);
    const hidesSelection = collapse && [ ...editor.model.document.selection.getSelectedBlocks() ]
        .some((selectedBlock) => nestedBlocks.includes(selectedBlock));

    editor.model.change((writer) => {
        for (const itemBlock of itemBlocks) {
            if (collapse) {
                writer.setAttribute(LIST_COLLAPSED_ATTRIBUTE, true, itemBlock);
            } else {
                writer.removeAttribute(LIST_COLLAPSED_ATTRIBUTE, itemBlock);
            }
        }

        if (hidesSelection) {
            const lastItemBlock = itemBlocks[itemBlocks.length - 1];
            writer.setSelection(writer.createPositionAt(lastItemBlock, "end"));
        }
    });
}

function expandItem(writer: ModelWriter, block: ModelElement): void {
    for (const itemBlock of getItemBlocks(block)) {
        writer.removeAttribute(LIST_COLLAPSED_ATTRIBUTE, itemBlock);
    }
}

function getSelectedListBlock(editor: Editor): ModelElement | null {
    const parent = editor.model.document.selection.getFirstPosition()?.parent;
    if (parent && parent.is("element") && parent.hasAttribute("listItemId")) {
        return parent;
    }
    return null;
}

/**
 * Maps the view `<li>` back to the first model block of the list item. The model keeps lists
 * flat (sibling blocks with `listIndent`/`listItemId` attributes).
 *
 * A view position at the `<li>`'s offset 0 maps *before* the item's first block for plain lists
 * (so the block is `nodeAfter`), but *inside* it for to-do lists — their `<li>` wraps content in
 * a `<span class="todo-list__label">`, so offset 0 sits before that wrapper and the mapped model
 * position lands within the block (whose `nodeAfter` is then a text node). Resolve from both the
 * node after the position and the position's own block ancestry to cover both shapes.
 */
function getListBlockFromViewListItem(editor: Editor, viewItem: ViewElement): ModelElement | null {
    const viewPosition = editor.editing.view.createPositionAt(viewItem, 0);
    const modelPosition = editor.editing.mapper.toModelPosition(viewPosition);

    if (isListBlock(modelPosition.nodeAfter)) {
        return modelPosition.nodeAfter;
    }
    // To-do case: the position landed inside the block; walk up to the enclosing list item. A
    // view <li> at offset 0 always maps either to a node-after that is a list block (handled
    // above) or to a model position whose parent is the list-item block itself (to-do lists), so
    // the very first iteration always finds `listItemId` and returns (the to-do tests exercise
    // this). The loop's continuation, its no-listItemId branch, and the trailing `return null` are
    // defensive only — kept in case CKEditor's view->model mapping ever changes shape — and are
    // unreachable from any current model/view state, so the whole walk is excluded from coverage.
    let ancestor: typeof modelPosition.parent | null = modelPosition.parent;
    /* v8 ignore start -- defensive walk-up; the first iteration always resolves the list item (see above). */
    while (ancestor && ancestor.is("element")) {
        if (ancestor.hasAttribute("listItemId")) {
            return ancestor;
        }
        ancestor = ancestor.parent;
    }
    return null;
    /* v8 ignore stop */
}

/** Whether the list item has nested (deeper-indented) items, i.e. there is anything to collapse. */
function hasNestedItems(block: ModelElement): boolean {
    const itemId = block.getAttribute("listItemId");
    for (let sibling = block.nextSibling; isListBlock(sibling); sibling = sibling.nextSibling) {
        if (sibling.getAttribute("listItemId") !== itemId) {
            return getIndent(sibling) > getIndent(block);
        }
    }
    return false;
}

/** Returns the list blocks hidden by collapsing `block`, including all descendant levels. */
function getNestedBlocks(block: ModelElement): ModelElement[] {
    const blocks: ModelElement[] = [];
    const indent = getIndent(block);
    const lastItemBlock = getItemBlocks(block).at(-1);

    for (
        let sibling = lastItemBlock?.nextSibling;
        isListBlock(sibling) && getIndent(sibling) > indent;
        sibling = sibling.nextSibling
    ) {
        blocks.push(sibling);
    }
    return blocks;
}

/** All consecutive blocks belonging to the same (possibly multi-block) list item. */
function getItemBlocks(block: ModelElement): ModelElement[] {
    const itemId = block.getAttribute("listItemId");
    const blocks = [block];
    for (let prev = block.previousSibling; isListBlock(prev) && prev.getAttribute("listItemId") === itemId; prev = prev.previousSibling) {
        blocks.unshift(prev);
    }
    for (let next = block.nextSibling; isListBlock(next) && next.getAttribute("listItemId") === itemId; next = next.nextSibling) {
        blocks.push(next);
    }
    return blocks;
}

/**
 * The collapsed ancestor items hiding this block, outermost last. Ancestors are the preceding
 * sibling blocks with a lower indent than any block in between.
 */
function getCollapsedAncestors(block: ModelElement): ModelElement[] {
    const ancestors: ModelElement[] = [];
    let minIndent = getIndent(block);

    for (let prev = block.previousSibling; isListBlock(prev) && minIndent > 0; prev = prev.previousSibling) {
        const indent = getIndent(prev);
        if (indent >= minIndent) {
            continue;
        }
        minIndent = indent;
        if (prev.getAttribute(LIST_COLLAPSED_ATTRIBUTE)) {
            ancestors.push(prev);
        }
    }

    return ancestors;
}

function isListBlock(node: ModelNode | null | undefined): node is ModelElement {
    return !!node && node.is("element") && node.hasAttribute("listItemId");
}

function getIndent(block: ModelElement): number {
    const indent = block.getAttribute("listIndent");
    return typeof indent === "number" ? indent : 0;
}