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 type { CKTextEditor } from "@triliumnext/ckeditor5";
import type CodeMirror from "@triliumnext/codemirror";
import type FNote from "../entities/fnote.js";
import { closeActiveDialog } from "../services/dialog.js";
import froca from "../services/froca.js";
import hoistedNoteService from "../services/hoisted_note.js";
import type { ViewScope } from "../services/link.js";
import options from "../services/options.js";
import protectedSessionHolder from "../services/protected_session_holder.js";
import server from "../services/server.js";
import { shouldRedirectPinnedNavigation } from "../services/tab_pinning.js";
import treeService from "../services/tree.js";
import utils from "../services/utils.js";
import { ReactWrappedWidget } from "../widgets/basic_widget.js";
import type { HighlightContext } from "../widgets/sidebar/HighlightsList.js";
import type { HeadingContext } from "../widgets/sidebar/TableOfContents.js";
import type { ChatHighlightsContext } from "../widgets/type_widgets/llm_chat/chat_highlights.js";
import appContext, { type EventData, type EventListener } from "./app_context.js";
import Component from "./component.js";
import type { HistoryEntry } from "./tab_manager.js";
export interface SetNoteOpts {
triggerSwitchEvent?: unknown;
viewScope?: ViewScope;
/** If true, skip closing the currently active dialog. Used when opening a note into a stackable popup (e.g. quick-edit) that must not dismiss the dialog it was launched from. */
keepActiveDialog?: boolean;
/** If true, the note is not added to the recent notes, as for an included note being edited. */
skipRecentNotes?: boolean;
/** The `switchToHistoryEntry()` call that shows the note. Pinned tabs pass it on. */
historyEntry?: HistoryEntry;
/** If true, the mobile layout stays on the screen it shows instead of switching to the note. */
keepScreen?: boolean;
}
export type GetTextEditorCallback = (editor: CKTextEditor) => void;
export type SaveState = "saved" | "saving" | "unsaved" | "error";
const READ_ONLY_CAPABLE_TYPES: string[] = [
"text",
"code",
"mermaid",
"canvas",
"mindMap",
"spreadsheet",
"noteMap",
"relationMap",
"render"
];
/**
* Collection view types that honour `#readOnly`, making a `book` note read-only capable.
*
* Listed by view type rather than by note type because the other views ignore the label: reporting
* a list or a grid as read-only would put a badge over a collection that can still be edited.
*/
const READ_ONLY_CAPABLE_VIEW_TYPES: string[] = [
"board",
"calendar",
"dashboard",
"geoMap",
"presentation",
"table"
];
/** View scope keys that hold the context's own state rather than what a navigation asks for. */
const VIEW_STATE_KEYS: string[] = [ "isReadOnly", "readOnlyTemporarilyDisabled" ];
export interface NoteContextDataMap {
toc: HeadingContext;
highlights: HighlightContext;
chatHighlights: ChatHighlightsContext;
pdfPages: {
totalPages: number;
currentPage: number;
scrollToPage(page: number): void;
requestThumbnail(page: number): void;
/** Copies a reference that opens the PDF at `page`. */
copyReference(page: number): void;
};
pdfAttachments: {
attachments: PdfAttachment[];
downloadAttachment(id: string): void;
};
pdfLayers: {
layers: PdfLayer[];
toggleLayer(layerId: string, visible: boolean): void;
};
pdfAnnotations: {
annotations: PdfAnnotationInfo[];
scrollToAnnotation(annotationId: string, pageNumber: number): void;
/** Copies a reference that opens the PDF at the annotation. */
copyReference(annotationId: string, pageNumber: number): void;
};
/** Published by a board, so the right pane can list its columns and scroll the board to one. */
boardColumns: {
/** The columns in the order the board draws them. */
columns: {
/** What identifies the column, which is the value its cards carry. */
value: string;
title: string;
icon: string;
/** How many cards it holds, counting what an active filter leaves in. */
count: number;
}[];
scrollToColumn(column: string): void;
};
saveState: {
state: SaveState;
};
/** Published by the code editor of the note, so the status bar can show the cursor position. */
codeEditor: CodeMirror;
/** Published by content widgets (via `useNoteBlob`) while the note's content is being fetched,
* so the note detail can show a loading state instead of the previous note's content. */
contentLoad: {
state: "loading" | "loaded" | "error";
/** Re-attempts the content fetch (e.g. from a "Retry" button after an error). */
retry: () => void;
};
}
type ContextDataKey = keyof NoteContextDataMap;
class NoteContext extends Component implements EventListener<"entitiesReloaded"> {
ntxId: string | null;
hoistedNoteId: string;
mainNtxId: string | null;
/** When true, this tab stays on its current note: navigations to a different note open a new tab instead. Only meaningful on a main context. */
pinned = false;
/** ntxId of the split most recently focused within this tab; re-activating the tab restores it. Only meaningful on a main context. */
lastActiveNtxId?: string | null;
notePath?: string | null;
noteId?: string | null;
parentNoteId?: string | null;
viewScope?: ViewScope;
/**
* Metadata storage for UI components (e.g., table of contents, PDF page list, code outline).
* This allows type widgets to publish data that sidebar/toolbar components can consume.
* Data is automatically cleared when navigating to a different note.
*/
private contextData: Map<string, unknown> = new Map();
constructor(ntxId: string | null = null, hoistedNoteId: string = "root", mainNtxId: string | null = null) {
super();
this.ntxId = ntxId || NoteContext.generateNtxId();
this.hoistedNoteId = hoistedNoteId;
this.mainNtxId = mainNtxId;
this.resetViewScope();
}
static generateNtxId() {
return utils.randomString(6);
}
setEmpty() {
this.notePath = null;
this.noteId = null;
this.parentNoteId = null;
// hoisted note is kept intentionally
this.triggerEvent("noteSwitched", {
noteContext: this,
notePath: this.notePath
});
this.resetViewScope();
}
isEmpty() {
return !this.noteId;
}
/** @returns the note context that ended up showing the note: usually `this`, or a new tab when a pinned tab redirected the navigation. `undefined` if nothing was navigated. */
async setNote(inputNotePath: string | undefined, opts: SetNoteOpts = {}): Promise<NoteContext | undefined> {
opts.triggerSwitchEvent = opts.triggerSwitchEvent !== undefined ? opts.triggerSwitchEvent : true;
// Readers like `revealBlockReference()` change the scope, so the context keeps a copy.
const viewScope: ViewScope = {
...opts.viewScope,
viewMode: opts.viewScope?.viewMode || "default"
};
if (!inputNotePath) {
return;
}
const resolvedNotePath = await this.getResolvedNotePath(inputNotePath);
if (!resolvedNotePath) {
return;
}
if (this.notePath === resolvedNotePath && isSameViewScope(this.viewScope, viewScope)) {
return this;
}
// Pinned tabs stay on the note they were pinned to — redirect navigation to a new tab instead.
const { noteId: targetNoteId } = treeService.getNoteIdAndParentIdFromUrl(resolvedNotePath);
if (shouldRedirectPinnedNavigation(this.pinned, this.noteId, targetNoteId)) {
return appContext.tabManager.openContextWithNote(resolvedNotePath, {
activate: true,
viewScope,
hoistedNoteId: this.hoistedNoteId,
historyEntry: opts.historyEntry
});
}
await this.triggerEvent("beforeNoteSwitch", { noteContext: this });
if (!opts.keepActiveDialog) {
closeActiveDialog();
}
const previousNoteId = this.noteId;
this.notePath = resolvedNotePath;
this.viewScope = viewScope;
({ noteId: this.noteId, parentNoteId: this.parentNoteId } = treeService.getNoteIdAndParentIdFromUrl(resolvedNotePath));
// Clear context data only when actually switching to a different note.
// Context data (e.g. ToC headings) is tied to the note content, so it
// remains valid when only the viewScope changes for the same note.
if (this.noteId !== previousNoteId) {
const oldKeys = Array.from(this.contextData.keys());
this.contextData.clear();
for (const key of oldKeys) {
this.triggerEvent("contextDataChanged", {
noteContext: this,
key,
value: undefined
});
}
}
if (!opts.skipRecentNotes) {
this.saveToRecentNotes(resolvedNotePath);
}
protectedSessionHolder.touchProtectedSessionIfNecessary(this.note);
if (opts.triggerSwitchEvent) {
await this.triggerEvent("noteSwitched", {
noteContext: this,
notePath: this.notePath
});
}
await this.setHoistedNoteIfNeeded();
if (utils.isMobile() && !opts.keepScreen) {
this.triggerCommand("setActiveScreen", { screen: "detail" });
}
return this;
}
async setHoistedNoteIfNeeded() {
if (this.hoistedNoteId === "root" && this.notePath?.startsWith("root/_hidden") && !this.note?.isLabelTruthy("keepCurrentHoisting")) {
// hidden subtree displays only when hoisted, so it doesn't make sense to keep root as hoisted note
let hoistedNoteId = "_hidden";
if (this.note?.isLaunchBarConfig()) {
hoistedNoteId = "_lbRoot";
} else if (this.note?.isOptions()) {
hoistedNoteId = "_options";
}
await this.setHoistedNoteId(hoistedNoteId);
}
}
getSubContexts() {
return appContext.tabManager.noteContexts.filter((nc) => nc.ntxId === this.ntxId || nc.mainNtxId === this.ntxId);
}
/**
* A main context represents a tab and also the first split. Further splits are the children contexts of the main context.
* Imagine you have a tab with 3 splits, each showing notes A, B, C (in this order).
* In such a scenario, A context is the main context (also representing the tab as a whole), and B, C are the children
* of context A.
*
* @returns {boolean} true if the context is main (= tab)
*/
isMainContext() {
// if null, then this is a main context
return !this.mainNtxId;
}
/**
* See docs for isMainContext() for better explanation.
*
* @returns {NoteContext}
*/
getMainContext() {
if (this.mainNtxId) {
try {
return appContext.tabManager.getNoteContextById(this.mainNtxId);
} catch (e) {
this.mainNtxId = null;
return this;
}
} else {
return this;
}
}
saveToRecentNotes(resolvedNotePath: string) {
if (options.is("databaseReadonly")) {
return;
}
setTimeout(async () => {
// we include the note in the recent list only if the user stayed on the note at least 5 seconds
if (resolvedNotePath && resolvedNotePath === this.notePath) {
await server.post("recent-notes", {
noteId: this.note?.noteId,
notePath: this.notePath
});
utils.reloadTray();
}
}, 5000);
}
async getResolvedNotePath(inputNotePath: string) {
const resolvedNotePath = await treeService.resolveNotePath(inputNotePath, this.hoistedNoteId);
if (!resolvedNotePath) {
logError(`Cannot resolve note path ${inputNotePath}`);
return;
}
if ((await hoistedNoteService.checkNoteAccess(resolvedNotePath, this)) === false) {
return; // note is outside of hoisted subtree and user chose not to unhoist
}
return resolvedNotePath;
}
get note(): FNote | null {
if (!this.noteId || !(this.noteId in froca.notes)) {
return null;
}
return froca.notes[this.noteId];
}
/** @returns {string[]} */
get notePathArray() {
return this.notePath ? this.notePath.split("/") : [];
}
isActive() {
return appContext.tabManager.activeNtxId === this.ntxId;
}
/** Whether a command with the given `ntxId` targets this context: `ntxId` is this context's, or is empty while this context is active. */
isCommandTarget(ntxId: string | null | undefined) {
return ntxId ? ntxId === this.ntxId : this.isActive();
}
getPojoState() {
if (this.hoistedNoteId !== "root") {
// keeping empty hoisted tab is esp. important for mobile (e.g. opened launcher config)
if (!this.notePath && this.getSubContexts().length === 0) {
return null;
}
}
return {
ntxId: this.ntxId,
mainNtxId: this.mainNtxId,
notePath: this.notePath,
hoistedNoteId: this.hoistedNoteId,
active: this.isActive(),
viewScope: this.viewScope,
pinned: this.pinned,
lastActiveNtxId: this.lastActiveNtxId
};
}
async unhoist() {
await this.setHoistedNoteId("root");
}
async setHoistedNoteId(noteIdToHoist: string) {
if (this.hoistedNoteId === noteIdToHoist) {
return;
}
this.hoistedNoteId = noteIdToHoist;
// The hoisted note replaces one outside it without being opened on purpose, so a phone
// showing the tree keeps showing it.
if (!this.notePathArray?.includes(noteIdToHoist)) {
await this.setNote(noteIdToHoist, { keepScreen: true });
}
await this.triggerEvent("hoistedNoteChanged", {
noteId: noteIdToHoist,
ntxId: this.ntxId
});
}
/** @returns {Promise<boolean>} */
async isReadOnly() {
if (this?.viewScope?.readOnlyTemporarilyDisabled && this.note?.isContentWritable !== false) {
return false;
}
if (!this.note) {
return false;
}
// What supports a read-only state at all, via the #readOnly label, the source view or
// auto-readonly.
const isPdf = this.note.type === "file" && this.note.mime === "application/pdf";
const isReadOnlyCapableCollection = this.note.type === "book"
&& READ_ONLY_CAPABLE_VIEW_TYPES.includes(this.note.getLabelValue("viewType") ?? "");
if (!isPdf && !isReadOnlyCapableCollection
&& !READ_ONLY_CAPABLE_TYPES.includes(this.note.type)) {
return false;
}
if (options.is("databaseReadonly") || !this.note.isContentWritable) {
return true;
}
if (this.note.isLabelTruthy("readOnly")) {
return true;
}
if (this.viewScope?.viewMode === "source") {
return true;
}
// Auto read-only based on content size is only configurable for text/code.
if (this.note.type !== "text" && this.note.type !== "code") {
return false;
}
// Store the initial decision about read-only status in the viewScope
// This will be "remembered" until the viewScope is refreshed
if (!this.viewScope) {
this.resetViewScope();
}
const viewScope = this.viewScope!;
if (viewScope.isReadOnly === undefined) {
const blob = await this.note.getBlob();
if (!blob) {
viewScope.isReadOnly = false;
return false;
}
const sizeLimit = this.note.type === "text"
? options.getInt("autoReadonlySizeText")
: options.getInt("autoReadonlySizeCode");
viewScope.isReadOnly = Boolean(sizeLimit &&
blob.contentLength > sizeLimit &&
!this.note.isLabelTruthy("autoReadOnlyDisabled"));
}
// Return the cached decision, which won't change until viewScope is reset
return viewScope.isReadOnly || false;
}
async entitiesReloadedEvent({ loadResults }: EventData<"entitiesReloaded">) {
if (this.noteId && loadResults.isNoteReloaded(this.noteId)) {
const noteRow = loadResults.getEntityRow("notes", this.noteId);
if (noteRow.isDeleted) {
this.clearRemovedNote();
}
}
}
frocaReloadedEvent() {
if (this.noteId && !(this.noteId in froca.notes)) {
this.clearRemovedNote();
}
}
private clearRemovedNote() {
this.noteId = null;
this.notePath = null;
this.triggerEvent("noteSwitched", {
noteContext: this,
notePath: this.notePath
});
}
hasNoteList() {
const note = this.note;
if (!note) {
return false;
}
if (note.type === "search") {
return false;
}
if (!["default", "contextual-help"].includes(this.viewScope?.viewMode ?? "")) {
return false;
}
// Collections must always display a note list, even if no children.
if (note.type === "book") {
if (note.isProtected && !protectedSessionHolder.isProtectedSessionAvailable()) {
return false;
}
const viewType = note.getLabelValue("viewType") ?? "grid";
if (!["list", "grid"].includes(viewType)) {
return true;
}
}
if (!note.hasChildren()) {
return false;
}
if (!["book", "text", "code"].includes(note.type)) {
return false;
}
if (note.mime === "text/x-sqlite;schema=trilium") {
return false;
}
// Icon packs render their glyph-grid preview across the whole pane; a children overview below it
// would be out of place.
if (note.isIconPack()) {
return false;
}
if (note.isLabelTruthy("hideChildrenOverview")) {
return false;
}
return true;
}
async getTextEditor(callback?: GetTextEditorCallback) {
return this.timeout<CKTextEditor>(
new Promise((resolve) =>
appContext.triggerCommand("executeWithTextEditor", {
callback,
resolve,
ntxId: this.ntxId
})
)
);
}
async getCodeEditor() {
return this.timeout(
new Promise<CodeMirror>((resolve) =>
appContext.triggerCommand("executeWithCodeEditor", {
resolve,
ntxId: this.ntxId
})
)
);
}
/**
* Returns a promise which will retrieve the JQuery element of the content of this note context.
*
* Do note that retrieving the content element needs to be handled by the type widget, which is the one which
* provides the content element by listening to the `executeWithContentElement` event. Not all note types support
* this.
*
* If no content could be determined `null` is returned instead.
*/
async getContentElement() {
return this.timeout<JQuery<HTMLElement> | null>(
new Promise((resolve) =>
appContext.triggerCommand("executeWithContentElement", {
resolve,
ntxId: this.ntxId
})
)
);
}
async getTypeWidget() {
return this.timeout(
new Promise<ReactWrappedWidget | null>((resolve) =>
appContext.triggerCommand("executeWithTypeWidget", {
resolve,
ntxId: this.ntxId
})
)
);
}
timeout<T>(promise: Promise<T | null>) {
return Promise.race([promise, new Promise((res) => setTimeout(() => res(null), 200))]) as Promise<T>;
}
resetViewScope() {
// view scope contains data specific to one note context and one "view".
// it is used to e.g., make read-only note temporarily editable or to hide TOC
// this is reset after navigating to a different note
this.viewScope = {};
}
async getNavigationTitle() {
if (!this.note) {
return null;
}
const { note, viewScope } = this;
const isNormalView = (viewScope?.viewMode === "default" || viewScope?.viewMode === "contextual-help");
let title = (isNormalView ? note.title : `${note.title}: ${viewScope?.viewMode}`);
if (viewScope?.attachmentId) {
// assuming the attachment has been already loaded
const attachment = await note.getAttachmentById(viewScope.attachmentId);
if (attachment) {
title += `: ${attachment.title}`;
}
}
return title;
}
/**
* Set metadata for this note context (e.g., table of contents, PDF pages, code outline).
* This data can be consumed by sidebar/toolbar components.
*
* @param key - Unique identifier for the data type (e.g., "toc", "pdfPages", "codeOutline")
* @param value - The data to store (will be cleared when switching notes)
*/
setContextData<K extends ContextDataKey>(key: K, value: NoteContextDataMap[K]): void {
this.contextData.set(key, value);
// Trigger event so subscribers can react
this.triggerEvent("contextDataChanged", {
noteContext: this,
key,
value
});
}
/**
* Get metadata for this note context.
*
* @param key - The data key to retrieve
* @returns The stored data, or undefined if not found
*/
getContextData<K extends ContextDataKey>(key: K): NoteContextDataMap[K] | undefined {
return this.contextData.get(key) as NoteContextDataMap[K] | undefined;
}
/**
* Check if context data exists for a given key.
*/
hasContextData(key: ContextDataKey): boolean {
return this.contextData.has(key);
}
/**
* Clear specific context data.
*/
clearContextData(key: ContextDataKey): void {
this.contextData.delete(key);
this.triggerEvent("contextDataChanged", {
noteContext: this,
key,
value: undefined
});
}
}
export function openInCurrentNoteContext(evt: MouseEvent | JQuery.ClickEvent | JQuery.MouseDownEvent | React.PointerEvent<HTMLCanvasElement> | null, notePath: string, viewScope?: ViewScope) {
const ntxId = $(evt?.target as Element)
.closest("[data-ntx-id]")
.attr("data-ntx-id");
const noteContext = ntxId ? appContext.tabManager.getNoteContextById(ntxId) : appContext.tabManager.getActiveContext();
if (noteContext) {
noteContext.setNote(notePath, { viewScope }).then((resultContext) => {
// setNote may have redirected to a new tab (e.g. when this context is pinned), which is
// already activated — focus whichever context actually ended up showing the note.
const target = resultContext ?? noteContext;
if (target !== appContext.tabManager.getActiveContext()) {
appContext.tabManager.activateNoteContext(target.ntxId);
}
});
} else {
appContext.tabManager.openContextWithNote(notePath, { viewScope, activate: true });
}
}
/**
* Whether navigating with `requested` shows what `current` already shows. Ignores the
* `VIEW_STATE_KEYS` and the keys a reader such as `consumeBookmark()` set to `undefined`.
*/
function isSameViewScope(current: ViewScope | undefined, requested: ViewScope) {
return utils.areObjectsEqual(
getNavigationTarget(current ?? {}), getNavigationTarget(requested));
}
function getNavigationTarget(viewScope: ViewScope) {
return Object.fromEntries(Object.entries(viewScope).filter(([ key, value ]) =>
value !== undefined && !VIEW_STATE_KEYS.includes(key)));
}
export default NoteContext;