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 "./EmbeddedNotePane.css";
import clsx from "clsx";
import { ComponentChildren, RefObject } from "preact";
import { useContext, useEffect, useRef, useState } from "preact/hooks";
import appContext from "../components/app_context";
import Component from "../components/component";
import NoteContext, { openInCurrentNoteContext } from "../components/note_context";
import FNote from "../entities/fnote";
import NoteColorPicker from "../menus/custom-items/NoteColorPicker";
import linkContextMenu from "../menus/link_context_menu";
import { t } from "../services/i18n";
import link from "../services/link";
import { isMobile, randomString } from "../services/utils";
import TitleRow from "./layout/TitleRow";
import ActionButton from "./react/ActionButton";
import Dropdown, { DropdownPanel } from "./react/Dropdown";
import { FormListItem } from "./react/FormList";
import { useDetachedNoteContext, useLegacyComponentElement, useNoteColorClass, useNoteContext } from "./react/hooks";
import Modal from "./react/Modal";
import OverlayPanel, { OverlayPanelBody } from "./react/OverlayPanel";
import { NoteContextContext, ParentComponent } from "./react/react_utils";
/*
* A note embedded in a pane of its host view — the geo map's marker pane, the relation map's note
* pane, the calendar's detail dock: the note-context wiring such a pane needs to hold the real note
* widgets (TitleRow, PromotedAttributes, NoteDetail), and, in EmbeddedNotePane.css, the layout that
* fits them into a third of the width they are written for. `EmbeddedNoteSurface` is the panel
* (desktop) or dialog (mobile) that the geo map and the relation map show the note in. The host view
* positions it, decides when it opens and closes, and supplies the actions around the note.
*/
/**
* A note context of the pane's own, pointed at whichever note the pane stands for — the arrangement
* the quick editor makes, so that the icon and title widgets work and a rename saves the usual way.
*
* One context for the pane rather than one per note: moving between notes is a note switch within a
* standing pane, not a new pane. Its ntxId is `ntxIdPrefix` plus a random suffix, so that two panes
* of one kind (two maps in two splits) register two contexts with the tab manager.
*
* The returned component stands between the host view's component and the pane's contents. The
* context was built here rather than by the tab manager, so it has no parent to raise events
* through and is given one by hand — the pane's component, not the host's. Pointing a note context
* at a note announces a note switch, and an unbound `useNoteContext` rebinds to whatever context it
* hears named (see hooks.tsx). The quick editor gets away with announcing to its parent because it
* is a dialog at the root; the pane is inside its view, so the collection view around it would
* rebind to the pane's note and tear the view down. It still hangs off the host's component as a
* child, so app-wide events travel down into the pane — a component hanging off nothing would never
* hear that its note was edited elsewhere.
*/
export function useEmbeddedNoteContext(
note: FNote | undefined,
ntxIdPrefix: string,
{ floatingToolbar = true, skipRecentNotes = false }: EmbeddedNoteContextOptions = {}
) {
const parentComponent = useContext(ParentComponent);
const [ ntxId ] = useState(() => `${ntxIdPrefix}_${randomString(10)}`);
const [ noteContext ] = useState(() => new NoteContext(ntxId));
const [ component ] = useState(() => new Component());
useDetachedNoteContext(noteContext);
useEffect(() => {
if (!parentComponent) return;
parentComponent.child(component);
return () => parentComponent.removeChild(component);
}, [ parentComponent, component ]);
useEffect(() => {
noteContext.triggerEvent = (name, data) => component.handleEventInChildren(name, data);
}, [ noteContext, component ]);
useEffect(() => {
if (!note) return;
const notePath = note.getBestNotePathString(appContext.tabManager.getActiveContext()?.hoistedNoteId);
void noteContext.setNote(notePath, {
// Selecting a note in the pane is not the kind of navigation that should dismiss an
// open dialog.
keepActiveDialog: true,
skipRecentNotes,
viewScope: {
// A note held read-only only because of its size is editable here, as it is in the
// quick editor; one the reader has marked read-only stays that way.
readOnlyTemporarilyDisabled: !note.hasLabel("readOnly"),
// The pane has a third of a note's width, which is not a toolbar's worth: the
// editor's own follows the selection instead of standing in a bar (see link.ts).
floatingToolbar
}
});
}, [ noteContext, note?.noteId ]);
return { noteContext, component, ntxId };
}
interface EmbeddedNoteContextOptions {
/** Whether the editor shows its buttons in a toolbar that follows the selection. */
floatingToolbar?: boolean;
/** Whether the note stays out of the recent notes. */
skipRecentNotes?: boolean;
}
/**
* Announces that the pane's note context is going, giving whatever is being edited in it the chance
* to save. Closing a pane announces nothing on its own — the widgets are simply unmounted — so the
* event a note context is removed under is raised here in its place, which is what the editors are
* listening for (see the spaced updates in hooks.tsx). The contents must still be mounted when it
* is raised, or there is nobody left to hear it.
*
* Best not waited on: the save is under way by the time the call returns, and a request already in
* flight does not care that what started it has gone. Waiting would hold the pane open for a round
* trip to the server every time it was closed with something unsaved in it.
*/
export function announceEmbeddedNoteClosing(component: Component, ntxId: string) {
return component.handleEventInChildren("beforeNoteContextRemove", { ntxIds: [ ntxId ] });
}
/**
* What the pane's contents live under: the pane's own component and note context, so that the
* widgets inside read the embedded note rather than the host's, and answer to the pane's component
* rather than the host's.
*/
export function EmbeddedNoteScope({ component, noteContext, children }: {
component: Component;
noteContext: NoteContext;
children: ComponentChildren;
}) {
return (
<ParentComponent.Provider value={component}>
<NoteContextContext.Provider value={noteContext}>
{children}
</NoteContextContext.Provider>
</ParentComponent.Provider>
);
}
/**
* Puts the caret in the title with the whole of the stock name selected — how a pane opens on a
* note its host has just created, whose name is the one thing it still lacks. Rendered inside the
* pane's {@link EmbeddedNoteScope}, and only while the host says the note is new.
*
* A component rather than a call after `setNote`, because only rendering says when there is an
* input to focus: the title widget grows one as the switch's announcement works through it, over
* more than one render, and a dispatch fired after any fixed delay is a bet on how many. This
* hears the announcement the same way the title widget does, so by the time its effect runs, the
* commit that mounted the input is done. The widget matches the event on the pane's ntxId, as it
* matches the one note_create raises for a note created anywhere else.
*/
export function SelectTitleOnFirstOpen() {
const { note, ntxId } = useNoteContext();
const parentComponent = useContext(ParentComponent);
// Once per opening: the note being edited re-announces itself (a rename saving, say), and the
// caret must not jump back to the title mid-thought.
const done = useRef(false);
useEffect(() => {
if (!note || done.current || !parentComponent) return;
done.current = true;
void parentComponent.handleEventInChildren("focusAndSelectTitle", { isNewNote: true, ntxId });
}, [ note?.noteId, parentComponent ]);
return null;
}
/**
* Links followed within the pane. One that points at a note standing on the host view is the
* host's to answer — the pane switches to it, the view following along (the map pans, the
* calendar turns to its date) — instead of navigating the whole tab away from the view. Every
* other link keeps meaning what it means anywhere else, as does every way of asking for more than
* a plain navigation: a modified click wanting a new tab or window, a link saying how it wants to
* be opened — in a popup, at an attachment, at a bookmark or a block, in a named tab.
*
* `onFollowLink` is offered the link's note and answers whether the host took the navigation
* over; only then is the link stopped. Captured on the pane's own element, so it goes ahead of
* the document-level handler every link click otherwise lands in (see the delegated listeners in
* link.ts) — and of the editor's.
*/
export function useFollowLinksWithin(paneRef: RefObject<HTMLElement | null>, onFollowLink: (noteId: string) => boolean) {
useEffect(() => {
const pane = paneRef.current;
if (!pane) return;
const onClick = (e: MouseEvent) => {
// A modified click asks for a new tab or window, neither of which the pane answers.
if (e.button !== 0 || e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
const anchor = e.target instanceof Element ? e.target.closest("a") : null;
const href = anchor?.getAttribute("href") ?? anchor?.getAttribute("data-href");
if (!href) return;
// A link that says how it wants to be opened is left to say it; only the plain "go to
// this note" is the pane's to take, and only for a note the host can go to.
const { noteId, ntxId, viewScope, openInPopup } = link.parseNavigationStateFromUrl(href);
if (!noteId || ntxId || openInPopup || viewScope?.viewMode !== "default"
|| viewScope.attachmentId || viewScope.bookmark || viewScope.block
|| !onFollowLink(noteId)) return;
e.preventDefault();
e.stopPropagation();
};
pane.addEventListener("click", onClick, true);
return () => pane.removeEventListener("click", onClick, true);
}, [ paneRef, onFollowLink ]);
}
/**
* The row of actions at the head of the pane: the ways of opening the note, then whatever the host
* offers to change about it. Named by tooltips rather than labels, as every other row of actions in
* a panel is: labels would wrap a handful of buttons onto two lines at this width.
*/
export function EmbeddedNoteActions({ children }: { children: ComponentChildren }) {
return <div className="tn-embedded-note-actions">{children}</div>;
}
/**
* The ways of opening the pane's note. One stands out — into the tab the host view is in — and the
* rest are gathered behind the button beside it: spread across the row they read as unrelated
* things when they are one thing with several destinations, and the menu they are gathered into is
* the app's own, so the pane offers exactly what a link offers anywhere else rather than a
* hand-kept subset of it.
*
* The quick editor is in that menu but not in the row: it is what a click on the note's marker or
* chip used to raise, and the pane took that click over — offering it here would put a modal back
* over the pane that replaced it.
*/
export function OpenNoteActions({ note }: { note: FNote }) {
const hoistedNoteId = appContext.tabManager.getActiveContext()?.hoistedNoteId;
// A path rather than an id: a note may hang in several places, and each of these opens a path.
const notePath = note.getBestNotePathString(hoistedNoteId);
return (
<>
<ActionButton
icon="bx bx-log-in"
text={t("embedded_note.open-note")}
// Handed the event: `openInCurrentNoteContext` reads the target tab off the element
// clicked, which lands the note in the tab the host view is in.
onClick={(e) => notePath && openInCurrentNoteContext(e as MouseEvent, notePath)}
disabled={!notePath}
/>
{/* A dropdown and not the menu the note's own right-click raises — that one is shown at
a point and dismissed by the next press on the document, and the press that opened
it from inside the panel is that press. */}
<Dropdown
className="tn-embedded-note-more"
buttonClassName="bx bx-dots-horizontal-rounded"
title={t("embedded_note.more-ways-to-open")}
iconAction
hideToggleArrow
disabled={!notePath}
>
{OTHER_WAYS_TO_OPEN.map(({ command, icon, title }) => (
<FormListItem
key={command}
icon={icon}
onClick={(e) => notePath && linkContextMenu.handleLinkContextMenuItem(
command, e as MouseEvent, notePath, {}, hoistedNoteId ?? null)}
>
{title()}
</FormListItem>
))}
</Dropdown>
</>
);
}
/**
* The ways of opening a note other than in the tab one is already in, which the split hides behind
* its arrow. The same four a link offers anywhere in the app, and each is carried out by the app's
* own handler — only the naming of them is repeated here.
*
* Repeated because `linkContextMenu.getItems` asks for the event that raised it, which a menu drawn
* before anything is pressed does not have. What it wants the event for is one mobile-only wording,
* so the loss is a label rather than behaviour. The titles are thunks so they are translated when
* the menu is drawn rather than when this module loads.
*/
export const OTHER_WAYS_TO_OPEN = [
{ command: "openNoteInNewTab", icon: "bx bx-link-external", title: () => t("link_context_menu.open_note_in_new_tab") },
// The one worth having beside a collection view most of all: what the view shows stays on show
// while the note is read beside it.
{ command: "openNoteInNewSplit", icon: "bx bx-dock-right", title: () => t("link_context_menu.open_note_in_new_split") },
{ command: "openNoteInNewWindow", icon: "bx bx-window-open", title: () => t("link_context_menu.open_note_in_new_window") },
// The quick editor, which is what a click on the note used to raise before the pane took that
// click over. Kept because the note's own right-click menu offers it and the two should agree —
// it is a way of opening the note that happens to stand over the pane, not a rival to it.
{ command: "openNoteInPopup", icon: "bx bx-edit", title: () => t("link_context_menu.open_note_in_popup") }
] as const;
/**
* The button a pane is grown by, whatever growing means to the host: the quick editor for a pane
* that has no larger form of its own (see {@link MaximizeToQuickEditAction}), or the pane's own
* larger form where it has one — the calendar's event card, which grows in place so that what is
* being edited within it is never torn down (see EventPopover).
*
* Stands beside the header's X and is dressed as its neighbour is (see EmbeddedNotePane.css). Named
* by the host, there being no one word for it: what it does is the host's to say, and a card that
* can be put back down again says something different from one that hands over to another surface.
*/
export function MaximizeAction({ text, icon, onClick }: {
text: string;
/** The stock expand, unless the host has a way back and wants the arrows the other way about. */
icon?: string;
onClick(): void;
}) {
return (
<ActionButton
className="tn-embedded-note-maximize"
icon={icon ?? "bx bx-expand-alt"}
text={text}
onClick={onClick}
/>
);
}
/**
* The pane grown into the quick editor: the same note in the larger surface, taking the pane's
* place rather than standing over it — opened first and closed after, as the quick editor's own
* maximize hands over to a tab. Which is what earns it the place in the header that the quick-edit
* menu entry is denied in the row (see {@link OTHER_WAYS_TO_OPEN}): a maximize replaces the pane
* instead of putting a modal back over it, the close giving whatever is being edited the chance to
* save.
*
* For a pane with no larger form of its own — the geo map's, whose note has nothing of the map
* about it to be carried into a bigger card. A pane that has one grows into that instead, and keeps
* what is peculiar to it.
*
* A path rather than an id, as the menu passes one, so the two roads into the quick editor agree.
*/
export function MaximizeToQuickEditAction({ note, onClose }: { note: FNote; onClose(): void }) {
return (
<MaximizeAction
text={t("embedded_note.maximize")}
onClick={() => {
const notePath = note.getBestNotePathString(appContext.tabManager.getActiveContext()?.hoistedNoteId);
appContext.triggerCommand("openInPopup", { noteIdOrPath: notePath || note.noteId });
onClose();
}}
/>
);
}
/**
* The colour the note's marker, chip or card is drawn in, which the pane already wears in its title
* but would otherwise have no way of setting — the right-click menu was the only place it could be
* reached. Named by the host: what the colour dresses is the host's to say (a marker, an event).
*
* Sent to the body because a panel may clip what overflows it or carry a backdrop filter, either of
* which would be enough to cut the menu off or flatten its own frosting (see the Dropdown notes in
* CLAUDE.md).
*/
export function NoteColorAction({ note, title }: { note: FNote; title: string }) {
return (
<DropdownPanel
className="tn-embedded-note-color"
buttonClassName="bx bx-palette"
title={title}
iconAction
hideToggleArrow
>
<NoteColorPicker note={note} />
</DropdownPanel>
);
}
interface EmbeddedNoteSurfaceProps {
note: FNote;
/** Class of the desktop panel, which the host's CSS positions. */
panelClassName: string;
/** Class of the mobile dialog. */
sheetClassName: string;
/** Class of the element that holds the note, added next to `tn-embedded-note-pane`. */
bodyClassName: string;
/** Tooltip of the panel's close button. */
closeText: string;
/** Adds a button that expands the desktop panel over the host view. Not used on mobile, where
* the dialog fills the screen. */
maximize?: {
maximized: boolean;
onChange(maximized: boolean): void;
expandText: string;
restoreText: string;
};
onClose(): void;
/** See {@link useFollowLinksWithin}. */
onFollowLink(noteId: string): boolean;
/** Content of the pane, usually a row of actions, `PromotedAttributes` and `NoteDetail`. */
children: ComponentChildren;
}
/**
* Shows an embedded note in an {@link OverlayPanel} with the note's `TitleRow` as its header on
* desktop, or in a `Modal` on mobile, where a panel next to the host view does not fit. Render it
* inside the pane's {@link EmbeddedNoteScope}.
*/
export function EmbeddedNoteSurface(props: EmbeddedNoteSurfaceProps) {
return isMobile() ? <EmbeddedNoteSheet {...props} /> : <EmbeddedNotePanel {...props} />;
}
function EmbeddedNotePanel({ note, panelClassName, bodyClassName, closeText, maximize, onClose, onFollowLink, children }: EmbeddedNoteSurfaceProps) {
const paneRef = useRef<HTMLDivElement>(null);
// Applies the note's color class, so the panel does not inherit the color of the host's split.
const colorClass = useNoteColorClass(note);
// `appContext.getComponentByEl()` otherwise resolves the widget that contains the host view.
useLegacyComponentElement(paneRef);
useFollowLinksWithin(paneRef, onFollowLink);
const maximized = !!maximize?.maximized;
return (
<OverlayPanel
containerRef={paneRef}
className={clsx("tn-embedded-note-panel", panelClassName, colorClass)}
header={<TitleRow compact />}
maximized={maximized}
headerActions={maximize && (
<MaximizeAction
icon={maximized ? "bx bx-collapse-alt" : "bx bx-expand-alt"}
text={maximized ? maximize.restoreText : maximize.expandText}
onClick={() => maximize.onChange(!maximized)}
/>
)}
close={{ text: closeText, onClick: onClose }}
>
<OverlayPanelBody className={clsx("tn-embedded-note-pane", bodyClassName, maximized && "tn-embedded-note-pane-wide")}>
{children}
</OverlayPanelBody>
</OverlayPanel>
);
}
function EmbeddedNoteSheet({ note, sheetClassName, bodyClassName, onClose, onFollowLink, children }: EmbeddedNoteSurfaceProps) {
const modalRef = useRef<HTMLDivElement>(null);
const colorClass = useNoteColorClass(note);
useLegacyComponentElement(modalRef);
useFollowLinksWithin(modalRef, onFollowLink);
return (
<Modal
className={clsx("tn-embedded-note-sheet", sheetClassName, colorClass)}
size="lg"
title={<TitleRow />}
modalRef={modalRef}
show
onHidden={onClose}
>
<div className={clsx("tn-embedded-note-pane", bodyClassName)}>
{children}
</div>
</Modal>
);
}