Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import "./TableOfContents.css";
import type { CKTextEditor, ModelElement, ModelNode } from "@triliumnext/ckeditor5";
import clsx from "clsx";
import { useCallback, useContext, useEffect, useRef, useState } from "preact/hooks";
import { revealElement } from "../../services/collapsible";
import { t } from "../../services/i18n";
import { randomString } from "../../services/utils";
import { useActiveNoteContext, useContentElement, useGetContextData, useIsNoteReadOnly, useMathRendering, useNoteProperty, useTextEditor } from "../react/hooks";
import Icon from "../react/Icon";
import { getEditorNoteId } from "../react/NoteStore";
import RawHtml from "../react/RawHtml";
import RightPanelWidget, { NavigatedInNote } from "./RightPanelWidget";
//#region Generic impl.
interface RawHeading {
id: string;
level: number;
text: string;
}
interface HeadingsWithNesting extends RawHeading {
children: HeadingsWithNesting[];
}
export interface HeadingContext {
scrollToHeading(heading: RawHeading): void;
headings: RawHeading[];
activeHeadingId?: string | null;
}
export default function TableOfContents() {
const { note, noteContext } = useActiveNoteContext();
const noteType = useNoteProperty(note, "type");
const noteMime = useNoteProperty(note, "mime");
const { isReadOnly } = useIsNoteReadOnly(note, noteContext);
return (
<RightPanelWidget id="toc" title={t("toc.table_of_contents")} grow>
{noteType === "text" && isReadOnly && <ReadOnlyTextTableOfContents />}
{noteType === "text" && !isReadOnly && <EditableTextTableOfContents />}
{noteType === "file" && noteMime === "application/pdf" && <ContextDataTableOfContents />}
{noteType === "llmChat" && <ContextDataTableOfContents />}
{note?.isMarkdown() && <ContextDataTableOfContents />}
</RightPanelWidget>
);
}
function ContextDataTableOfContents() {
const data = useGetContextData("toc");
return (
<AbstractTableOfContents
headings={data?.headings || []}
scrollToHeading={data?.scrollToHeading || (() => {})}
activeHeadingId={data?.activeHeadingId}
/>
);
}
function AbstractTableOfContents<T extends RawHeading>({ headings, scrollToHeading, activeHeadingId }: {
headings: T[];
scrollToHeading(heading: T): void;
activeHeadingId?: string | null;
}) {
const tocRef = useRef<HTMLSpanElement>(null);
const nestedHeadings = buildHeadingTree(headings);
useEffect(() => {
tocRef.current?.querySelector("li.active")?.scrollIntoView({
block: "nearest",
behavior: "smooth"
});
}, [activeHeadingId]);
return (
<span ref={tocRef} className="toc">
{nestedHeadings.length > 0 ? (
<ol>
{nestedHeadings.map(heading => <TableOfContentsHeading key={heading.id} heading={heading} scrollToHeading={scrollToHeading} activeHeadingId={activeHeadingId} />)}
</ol>
) : (
<div className="no-headings">{t("toc.no_headings")}</div>
)}
</span>
);
}
function TableOfContentsHeading({ heading, scrollToHeading, activeHeadingId }: {
heading: HeadingsWithNesting;
scrollToHeading(heading: RawHeading): void;
activeHeadingId?: string | null;
}) {
const [ collapsed, setCollapsed ] = useState(false);
const onNavigated = useContext(NavigatedInNote);
const isActive = heading.id === activeHeadingId;
const contentRef = useRef<HTMLElement>(null);
useMathRendering(contentRef, [heading.text]);
return (
<>
<li className={clsx(collapsed && "collapsed", isActive && "active")}>
{heading.children.length > 0 && (
<Icon
className="collapse-button"
icon="bx bx-chevron-down"
onClick={() => setCollapsed(!collapsed)}
/>
)}
<RawHtml
containerRef={contentRef}
className="item-content"
onClick={() => {
scrollToHeading(heading);
onNavigated?.();
}}
html={heading.text}
/>
</li>
{heading.children.length > 0 && (
<ol>
{heading.children.map(heading => <TableOfContentsHeading key={heading.id} heading={heading} scrollToHeading={scrollToHeading} activeHeadingId={activeHeadingId} />)}
</ol>
)}
</>
);
}
function buildHeadingTree(headings: RawHeading[]): HeadingsWithNesting[] {
const root: HeadingsWithNesting = { level: 0, text: "", children: [], id: "_root" };
const stack: HeadingsWithNesting[] = [root];
for (const h of headings) {
const node: HeadingsWithNesting = { ...h, children: [] };
// Pop until we find a parent with lower level
while (stack.length > 1 && stack[stack.length - 1].level >= h.level) {
stack.pop();
}
// Attach to current parent
stack[stack.length - 1].children.push(node);
// This node becomes the new parent
stack.push(node);
}
return root.children;
}
export function useActiveHeading<T extends RawHeading>({ headings, scrollingContainer, getHeadingElement }: {
headings: T[];
scrollingContainer: HTMLElement | null;
getHeadingElement: (heading: T) => HTMLElement | null
}) {
const headingsRef = useRef(headings);
const [activeHeadingId, setActiveHeadingId] = useState<string | null>(null);
useEffect(() => {
headingsRef.current = headings;
}, [headings]);
useEffect(() => {
if (!scrollingContainer) {
setActiveHeadingId(null);
return;
}
const activeLineY = scrollingContainer.getBoundingClientRect().top + 100;
let timeoutId: number | undefined;
function updateActiveHeading() {
let activeHeading: T | null = null;
for (const heading of headingsRef.current) {
const headingEl = getHeadingElement(heading);
if (headingEl && headingEl.getBoundingClientRect().top <= activeLineY) {
activeHeading = heading;
} else {
break;
}
}
setActiveHeadingId(prev =>
prev === activeHeading?.id ? prev : activeHeading?.id ?? null
);
}
function handleScroll() {
window.clearTimeout(timeoutId);
timeoutId = window.setTimeout(updateActiveHeading, 100);
}
scrollingContainer.addEventListener("scroll", handleScroll);
updateActiveHeading();
return () => {
window.clearTimeout(timeoutId);
scrollingContainer.removeEventListener("scroll", handleScroll);
};
// getHeadingElement must re-subscribe the listener: when a rebuild replaces the editor,
// .scrolling-container is an ancestor of the editor root and stays the same element, so
// scrollingContainer alone would keep the listener mapping through the destroyed editor.
}, [scrollingContainer, getHeadingElement]);
return activeHeadingId;
}
//#endregion
//#region Editable text (CKEditor)
/** The id of each heading element, outside the model: reading the headings must not edit the note. */
const headingIds = new WeakMap<ModelElement, string>();
interface CKHeading extends RawHeading {
element: ModelElement;
}
function EditableTextTableOfContents() {
const { note, noteContext } = useActiveNoteContext();
const textEditor = useTextEditor(noteContext);
const [ headings, setHeadings ] = useState<CKHeading[]>([]);
const [ scrollingContainer, setScrollingContainer ] = useState<HTMLElement | null>(null);
// The CKEditor instance is reused across note switches within a tab and across the
// read-only ↔ editable switch: the note detail keeps it mounted behind the read-only view
// and swaps content in with `editor.setData()`, which emits `change:data`. So the editor
// this runs against can still hold the note the user edited before, and does until this
// note's blob arrives — a wait the auto-readonly threshold makes a long one.
useEffect(() => {
if (!textEditor) return;
// `getEditorNoteId()` says whose content is in the editor. Extracting from another note's
// would put its headings in the sidebar; the listener below picks this note's up as soon
// as `setData()` lands.
if (getEditorNoteId(textEditor) === note?.noteId) {
setHeadings(extractTocFromTextEditor(textEditor));
}
// Attached synchronously so no `setData()` can slip past it. Only the attribute check
// waits on the CKEditor bundle, which is statically heavy but guaranteed to be loaded by
// now (a text editor instance exists); until it resolves, inserts and removals — which is
// what `setData()` produces — still come through.
let affectsHeading: typeof import("@triliumnext/ckeditor5").attributeChangeAffectsHeading | undefined;
void import("@triliumnext/ckeditor5").then(({ attributeChangeAffectsHeading }) => {
affectsHeading = attributeChangeAffectsHeading;
});
// One extraction per frame, however many changes arrive in it.
let frame: number | undefined;
const changeCallback = () => {
const changes = textEditor.model.document.differ.getChanges();
const affectsHeadings = changes.some( change => {
return (
change.type === 'insert' || change.type === 'remove' ||
(change.type === 'attribute' && (affectsHeading?.(change, textEditor) ?? false))
);
});
if (affectsHeadings && frame === undefined) {
frame = requestAnimationFrame(() => {
frame = undefined;
setHeadings(extractTocFromTextEditor(textEditor));
});
}
};
textEditor.model.document.on("change:data", changeCallback);
return () => {
textEditor.model.document.off("change:data", changeCallback);
if (frame !== undefined) {
cancelAnimationFrame(frame);
}
};
}, [ textEditor, note?.noteId ]);
useEffect(() => {
if (!textEditor) {
setScrollingContainer(null);
return;
}
const container = textEditor.editing.view.getDomRoot()?.closest(".scrolling-container") as HTMLElement | null;
setScrollingContainer(container);
}, [textEditor]);
const getHeadingElement = useCallback((heading: CKHeading) => {
if (!textEditor) return null;
const viewEl = textEditor.editing.mapper.toViewElement(heading.element);
if (!viewEl) return null;
const domEl = textEditor.editing.view.domConverter.mapViewToDom(viewEl);
return domEl ?? null;
}, [textEditor]);
const activeHeadingId = useActiveHeading({ headings, scrollingContainer, getHeadingElement });
const scrollToHeading = useCallback((heading: CKHeading) => {
if (!textEditor) return;
const viewEl = textEditor.editing.mapper.toViewElement(heading.element);
if (!viewEl) return;
const domEl = textEditor.editing.view.domConverter.mapViewToDom(viewEl);
if (domEl) {
revealElement(domEl);
domEl.scrollIntoView();
}
}, [ textEditor ]);
return <AbstractTableOfContents
headings={headings}
scrollToHeading={scrollToHeading}
activeHeadingId={activeHeadingId}
/>;
}
function extractTocFromTextEditor(editor: CKTextEditor) {
const headings: CKHeading[] = [];
const root = editor.model.document.getRoot();
if (!root) return [];
for (const { type, item } of editor.model.createRangeIn(root).getWalker()) {
if (type !== "elementStart" || !item.is('element') || !item.name.startsWith('heading')) continue;
const level = Number(item.name.replace( 'heading', '' ));
// Convert model element to view, then to DOM to get HTML.
// Math UIElements render their KaTeX content asynchronously, so
// ck-math-tex spans may be empty at read time. Replace them with
// math-tex spans (the data format) using the equation from the model,
// so useMathRendering can render them synchronously in the sidebar.
const viewEl = editor.editing.mapper.toViewElement(item);
let text = '';
if (viewEl) {
const domEl = editor.editing.view.domConverter.mapViewToDom(viewEl);
if (domEl instanceof HTMLElement) {
const clone = domEl.cloneNode(true) as HTMLElement;
const ckMathSpans = clone.querySelectorAll('.ck-math-tex');
let mathIdx = 0;
for (const child of item.getChildren()) {
if (!child.is('element', 'mathtex-inline')) continue;
if (mathIdx >= ckMathSpans.length) break;
const equation = String(child.getAttribute('equation') ?? '');
const span = document.createElement('span');
span.className = 'math-tex';
span.textContent = `\\(${equation}\\)`;
ckMathSpans[mathIdx].replaceWith(span);
mathIdx++;
}
text = clone.innerHTML;
}
}
// Fallback to plain text if DOM conversion fails
if (!text) {
text = Array.from( item.getChildren() )
.map( (c: ModelNode) => c.is( '$text' ) ? c.data : '' )
.join( '' );
}
let id = headingIds.get(item);
if (!id) {
id = randomString();
headingIds.set(item, id);
}
headings.push({ level, text, element: item, id });
}
return headings;
}
//#endregion
//#region Read-only text
interface DomHeading extends RawHeading {
element: HTMLHeadingElement;
}
function ReadOnlyTextTableOfContents() {
const { noteContext } = useActiveNoteContext();
const contentEl = useContentElement(noteContext);
const [ headings, setHeadings ] = useState<DomHeading[]>([]);
const [ scrollingContainer, setScrollingContainer ] = useState<HTMLElement | null>(null);
useEffect(() => {
if (!contentEl) return;
setHeadings(extractTocFromStaticHtml(contentEl));
const observer = new MutationObserver(() => {
setHeadings(extractTocFromStaticHtml(contentEl));
});
observer.observe(contentEl, { childList: true });
return () => observer.disconnect();
}, [contentEl]);
const scrollToHeading = useCallback((heading: DomHeading) => {
revealElement(heading.element);
heading.element.scrollIntoView();
}, []);
useEffect(() => {
if (!contentEl) {
setScrollingContainer(null);
return;
}
const container = contentEl.closest(".scrolling-container") as HTMLElement;
setScrollingContainer(container);
}, [contentEl]);
const getHeadingElement = useCallback((heading: DomHeading) => heading.element, []);
const activeHeadingId = useActiveHeading({ headings, scrollingContainer, getHeadingElement });
return <AbstractTableOfContents
headings={headings}
scrollToHeading={scrollToHeading}
activeHeadingId={activeHeadingId}
/>;
}
function extractTocFromStaticHtml(el: HTMLElement | null) {
if (!el) return [];
const headings: DomHeading[] = [];
for (const headingEl of el.querySelectorAll<HTMLHeadingElement>("h1,h2,h3,h4,h5,h6")) {
if (headingEl.closest(".include-note")) continue;
headings.push({
id: randomString(),
level: parseInt(headingEl.tagName.substring(1), 10),
text: headingEl.innerHTML,
element: headingEl
});
}
return headings;
}
//#endregion