Skip to content

Build your personal knowledge base with Trilium Notes

docs(client): rewrite the relation map and note card comments in plain register

Elian Doran3ed8308fdf6d
diff --git a/apps/client/src/widgets/EmbeddedNotePane.css b/apps/client/src/widgets/EmbeddedNotePane.css
index 4798823432..4e7e504a95 100644
--- a/apps/client/src/widgets/EmbeddedNotePane.css
+++ b/apps/client/src/widgets/EmbeddedNotePane.css
@@ -89,7 +89,7 @@
box-sizing: content-box;
padding-block: 9px;
padding-inline-start: 9px;
- /* Clear of the maximize and close buttons laid over the end of the row (OverlayPanel.css). */
+ /* Room for the maximize and close buttons at the end of the row (see OverlayPanel.css). */
padding-inline-end: 64px;
}
diff --git a/apps/client/src/widgets/EmbeddedNotePane.tsx b/apps/client/src/widgets/EmbeddedNotePane.tsx
index d8e39d05fb..3fb44f6de4 100644
--- a/apps/client/src/widgets/EmbeddedNotePane.tsx
+++ b/apps/client/src/widgets/EmbeddedNotePane.tsx
@@ -26,9 +26,9 @@ 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 or
- * phone dialog both maps show the note on; where it stands, when it opens and closes and what it
- * offers around the note stay with the view that owns it.
+ * 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.
*/
/**
@@ -363,15 +363,16 @@ export function NoteColorAction({ note, title }: { note: FNote; title: string })
interface EmbeddedNoteSurfaceProps {
note: FNote;
- /** The panel's class on desktop, which places it over the host view. */
+ /** Class of the desktop panel, which the host's CSS positions. */
panelClassName: string;
- /** The dialog's class on a phone. */
+ /** Class of the mobile dialog. */
sheetClassName: string;
- /** The class of the body that holds the note, next to the shared `tn-embedded-note-pane`. */
+ /** Class of the element that holds the note, added next to `tn-embedded-note-pane`. */
bodyClassName: string;
- /** The tooltip of the panel's close button. */
+ /** Tooltip of the panel's close button. */
closeText: string;
- /** Lets the desktop panel grow over the host view. A phone always shows the whole dialog. */
+ /** 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;
@@ -381,14 +382,14 @@ interface EmbeddedNoteSurfaceProps {
onClose(): void;
/** See {@link useFollowLinksWithin}. */
onFollowLink(noteId: string): boolean;
- /** The pane's contents, usually a row of actions, `PromotedAttributes` and `NoteDetail`. */
+ /** Content of the pane, usually a row of actions, `PromotedAttributes` and `NoteDetail`. */
children: ComponentChildren;
}
/**
- * The surface an embedded note is shown on: an {@link OverlayPanel} headed by the note's
- * `TitleRow` on desktop, or a `Modal` on a phone, which has no room for a panel beside the host
- * view. Render it inside the pane's {@link EmbeddedNoteScope}.
+ * 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} />;
@@ -396,10 +397,10 @@ export function EmbeddedNoteSurface(props: EmbeddedNoteSurfaceProps) {
function EmbeddedNotePanel({ note, panelClassName, bodyClassName, closeText, maximize, onClose, onFollowLink, children }: EmbeddedNoteSurfaceProps) {
const paneRef = useRef<HTMLDivElement>(null);
- // The note's own colour, not the hue of the split the host view stands in.
+ // Applies the note's color class, so the panel does not inherit the color of the host's split.
const colorClass = useNoteColorClass(note);
- // The text editor resolves its host component from the DOM. Without this mark it reaches the
- // widget around the host view, which does not answer calls such as `loadReferenceLinkTitle`.
+ // The text editor resolves its host component from the DOM. Without this, it resolves the widget
+ // that contains the host view, which does not implement calls such as `loadReferenceLinkTitle`.
useLegacyComponentElement(paneRef);
useFollowLinksWithin(paneRef, onFollowLink);
const maximized = !!maximize?.maximized;
diff --git a/apps/client/src/widgets/collections/board/index.css b/apps/client/src/widgets/collections/board/index.css
index 427dff935a..b49df5c0fe 100644
--- a/apps/client/src/widgets/collections/board/index.css
+++ b/apps/client/src/widgets/collections/board/index.css
@@ -62,12 +62,12 @@
than hiding what is behind it. */
--board-edit-backdrop: rgba(0, 0, 0, 0.15);
- /* What a column's heading writes its text in, standing as it does on the column rather than on a
- card (see note_card.css for the card's own). On a coloured column the pairs below replace them. */
+ /* Text colors of a column heading; the card text colors are in note_card.css. On a column with a
+ hue, colors composed from the values below replace these. */
--board-column-header-text-color: var(--main-text-color);
--board-column-header-muted-text-color: var(--muted-text-color);
- /* How each is composed where the column carries a hue. The colour lends its hue alone: the
- lightness is the theme's, so a coloured board reads as light as a plain one. */
+ /* Saturation and lightness of the heading colors on a column with a hue. Only the hue comes from
+ the note's color, and the theme sets the lightness, so a colored board is as light as a plain one. */
--board-column-header-text-saturation: 30%;
--board-column-header-text-lightness: 8%;
--board-column-header-muted-text-saturation: 20%;
@@ -449,7 +449,7 @@ body.mobile .board-view-container .board-add-column {
--board-item-hover-saturation: var(--board-item-hover-background-saturation);
}
-/* The colours are composed in note_card.css, from the hue set above. */
+/* note_card.css computes these colors from the hue set above. */
.board-view-container .board-note {
background-color: var(--note-card-background);
}
diff --git a/apps/client/src/widgets/note_card.css b/apps/client/src/widgets/note_card.css
index b4e96c203e..1e594cfea9 100644
--- a/apps/client/src/widgets/note_card.css
+++ b/apps/client/src/widgets/note_card.css
@@ -1,14 +1,14 @@
/*
- * The surface a note is drawn on as a card: an item of a board collection, a box on a relation
- * map. The tokens keep the board's names, which themes already set.
+ * Card styling shared by board collection items and relation map boxes. The variables keep their
+ * `--board-*` names because themes already set them.
*
- * A card is coloured by `--board-item-hue` and the two saturations: its own note's colour where it
- * has one (`with-hue`, from `FNote.getColorClass()`), otherwise grey. A host can set them from
- * something else as well, as the board does for the column a card stands in. The defaults below are
- * wrapped in `:where()` so that any host rule outweighs them.
+ * The card color comes from `--board-item-hue` and the two saturations. A card with the `with-hue`
+ * class (see `FNote.getColorClass()`) uses its note's hue; any other card is gray. A host can set
+ * these variables itself, as the board does to tint a card with its column's color. The defaults are
+ * wrapped in `:where()` so that any host rule overrides them.
*/
-/* Defaults for a theme that sets none of its own; the light values, the app's own default look. */
+/* Defaults for themes that do not set these variables. They match the light theme. */
:where(:root) {
--board-item-background-saturation: 100%;
--board-item-background-lightness: 96%;
@@ -16,20 +16,20 @@
--board-item-hover-background-saturation: 100%;
--board-item-hover-background-lightness: 98.5%;
- /* What a card at rest casts on what it stands on. */
+ /* Shadow of a card. */
--board-item-shadow: 1px 1px 4px rgba(0, 0, 0, 0.1);
- /* The lift a card takes under the pointer, named so that a picked-out card can carry its ring
- and this shadow together. */
+ /* Shadow of a hovered card. A variable of its own, so a selected card can combine it with the
+ selection ring. */
--board-item-hover-shadow: 2px 4px 8px rgba(0, 0, 0, 0.1);
- /* The ring a picked-out card carries. */
+ /* Selection ring of a selected card. */
--board-selected-ring-color: var(--link-color);
- /* What a card writes its text and icons in, and what it marks the quieter ones with. These are
- what a card without a hue paints; with one, the pairs below replace them. */
+ /* Text and muted text colors of a card without a hue. A card with a hue uses colors composed
+ from the values below instead. */
--board-text-color: var(--main-text-color);
--board-muted-text-color: var(--muted-text-color);
- /* How each is composed where the card carries a hue. The colour lends its hue alone: the
- lightness is the theme's, so a coloured card reads as light as a plain one. */
+ /* Saturation and lightness of the text colors of a card with a hue. Only the hue comes from the
+ note's color, and the theme sets the lightness, so a colored card is as readable as a plain one. */
--board-text-saturation: 30%;
--board-text-lightness: 8%;
--board-muted-text-saturation: 20%;
@@ -60,7 +60,7 @@
--board-muted-text-color: var(--note-card-muted-text-color);
}
-/* Composed on the card itself, so they read the hue the card ends up with. */
+/* Declared on the card element, so they use the hue set on the card, including a host's. */
.tn-note-card {
--note-card-background: hsl(
var(--board-item-hue),
diff --git a/apps/client/src/widgets/type_widgets/relation_map/MapToolbar.tsx b/apps/client/src/widgets/type_widgets/relation_map/MapToolbar.tsx
index 9156940bc4..9f07f911ed 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/MapToolbar.tsx
+++ b/apps/client/src/widgets/type_widgets/relation_map/MapToolbar.tsx
@@ -53,10 +53,9 @@ export default function MapToolbar({ panZoom, onCommand }: MapToolbarProps) {
interface EditToolbarProps {
/** The map may not be edited, which is every one of these buttons refused at once. */
isReadOnly: boolean;
- /** The map is armed for the next click to place a new note, which the button shows as pressed. */
+ /** Whether the map is in placement mode. The button is shown as pressed while it is. */
placing: boolean;
- /** Arms the map for a note to be placed, or disarms it (see `useNotePlacement` in
- * RelationMap.tsx). */
+ /** Turns placement mode on or off (see `useNotePlacement` in RelationMap.tsx). */
onTogglePlacement: () => void;
}
@@ -80,8 +79,8 @@ interface EditToolbarProps {
* note-and-plus in the icon set, and that leaves the mark unlike the + of the zoom step opposite.
*
* It stands on the map rather than in the note's own bar of actions, where it was: what it starts is
- * finished by a click on the map, so it belongs beside the canvas that answers it. While the map is
- * armed the button shows as pressed, and a second press disarms it.
+ * finished by a click on the map, so it belongs beside the canvas that answers it. In placement mode
+ * the button is shown as pressed, and pressing it again turns placement mode off.
*/
export function EditToolbar({ isReadOnly, placing, onTogglePlacement }: EditToolbarProps) {
return (
diff --git a/apps/client/src/widgets/type_widgets/relation_map/NoteBox.css b/apps/client/src/widgets/type_widgets/relation_map/NoteBox.css
index 56e429d6ec..d071fb4558 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/NoteBox.css
+++ b/apps/client/src/widgets/type_widgets/relation_map/NoteBox.css
@@ -7,7 +7,7 @@
box-sizing: border-box;
min-width: 150px;
max-width: 200px;
- /* Room at the end for the relation handle. */
+ /* Room at the end for the `.endpoint` relation handle. */
padding: 0.6em 1.8em 0.6em 0.6em;
font-size: 0.9em;
line-height: 1.2;
@@ -67,7 +67,7 @@
}
}
-/* The two ends of the relation under the pointer. */
+/* jsPlumb adds these classes to both boxes of the hovered relation. */
.note-detail-relation-map .note-box:is(.jtk-source-hover, .jtk-target-hover) {
background-color: var(--note-card-hover-background);
box-shadow: var(--board-item-hover-shadow);
diff --git a/apps/client/src/widgets/type_widgets/relation_map/NoteBox.tsx b/apps/client/src/widgets/type_widgets/relation_map/NoteBox.tsx
index e2b325b3e5..886cb01e1c 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/NoteBox.tsx
+++ b/apps/client/src/widgets/type_widgets/relation_map/NoteBox.tsx
@@ -76,9 +76,8 @@ export function NoteBox({ noteId, x, y, mapApiRef, selected }: NoteBoxProps) {
}
/**
- * The translucent box that follows the pointer while the map waits for a click to place a new
- * note. `RelationMap` moves it by writing `left`/`top` straight onto the element, so a pointer
- * moving across the map does not render on every event.
+ * Translucent box that follows the pointer while the map is in placement mode. `useNotePlacement`
+ * sets its `left`/`top` directly on the element, so moving the pointer does not re-render.
*/
export function GhostNoteBox({ elementRef }: { elementRef: RefObject<HTMLDivElement | null> }) {
return (
diff --git a/apps/client/src/widgets/type_widgets/relation_map/NotePane.css b/apps/client/src/widgets/type_widgets/relation_map/NotePane.css
index 9ca3a99883..e6dceebaa4 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/NotePane.css
+++ b/apps/client/src/widgets/type_widgets/relation_map/NotePane.css
@@ -11,7 +11,7 @@
.relation-map-wrapper .relation-map-note-pane {
position: absolute;
top: var(--relation-map-inset);
- /* Clear of the toolbars along the foot of the map. */
+ /* Room for the toolbars at the bottom of the map. */
bottom: calc(2 * var(--relation-map-inset) + var(--overlay-button-height, 28px));
inset-inline-end: var(--relation-map-inset);
width: var(--relation-map-pane-width);
diff --git a/apps/client/src/widgets/type_widgets/relation_map/NotePane.spec.tsx b/apps/client/src/widgets/type_widgets/relation_map/NotePane.spec.tsx
index 4f35d19c92..36afa272d7 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/NotePane.spec.tsx
+++ b/apps/client/src/widgets/type_widgets/relation_map/NotePane.spec.tsx
@@ -12,7 +12,7 @@ import { ParentComponent } from "../../react/react_utils";
import type RelationMapApi from "./api";
import NotePane, { type NotePaneHandle, type PaneSelection } from "./NotePane";
-/** Stands in for the note's editor, listening for what a real editor listens for. */
+/** Stub for the note's editor, listening for `beforeNoteContextRemove` as the real editor does. */
const editorAskedToSave = vi.fn();
vi.mock("../../NoteDetail", () => ({
default: () => {
@@ -30,7 +30,7 @@ vi.mock("../../../services/dialog", async (importOriginal) => ({
}
}));
-// A promoted text field asks the server for the values other notes hold under its name.
+// Promoted text fields request autocomplete values from the server.
server.get = (async () => []) as unknown as typeof server.get;
interface MountOptions {
@@ -76,7 +76,7 @@ describe("relation map NotePane", () => {
(appContext as unknown as { tabManager: unknown }).tabManager = undefined;
});
- /** Stands in for `RelationMap`, which owns the selection and the notes on the map. */
+ /** Stub for `RelationMap`, which owns the selection and the list of notes on the map. */
function Harness({ noteIdsOnMap, isReadOnly, initialSelection }: {
noteIdsOnMap: string[]; isReadOnly: boolean; initialSelection: PaneSelection | null;
}) {
diff --git a/apps/client/src/widgets/type_widgets/relation_map/NotePane.tsx b/apps/client/src/widgets/type_widgets/relation_map/NotePane.tsx
index 933cbb3c1b..a107173738 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/NotePane.tsx
+++ b/apps/client/src/widgets/type_widgets/relation_map/NotePane.tsx
@@ -13,10 +13,10 @@ import { useNote } from "../../react/hooks";
import RelationMapApi from "./api";
import { confirmRemoveFromMap } from "./context_menu";
-/** Which note the pane shows. Owned by the map, which opens the pane on a note it has just created. */
+/** The note shown in the pane. `RelationMap` owns it, so it can open the pane on a note it created. */
export interface PaneSelection {
noteId: string;
- /** The note was just created, so the pane opens with its stock title selected. */
+ /** The note was just created; the pane opens with its default title selected. */
isNew?: boolean;
}
@@ -26,15 +26,16 @@ export interface NotePaneHandle {
}
/**
- * The note pane standing against the trailing edge of a relation map while a box is selected: the
- * note's title, promoted attributes and content, editable in place.
+ * Panel at the trailing edge of a relation map that shows the selected note's title, promoted
+ * attributes and content for editing.
*/
export default function NotePane({ paneRef, noteIdsOnMap, mapApiRef, isReadOnly, selection, onSelect }: {
paneRef: RefObject<NotePaneHandle | null>;
- /** The notes the map shows, which keep the pane open and which a link inside it can switch to. */
+ /** IDs of the notes on the map. The pane closes when its note is not among them, and a link in
+ * the pane switches the pane only to a note among them. */
noteIdsOnMap: string[];
mapApiRef: RefObject<RelationMapApi | null>;
- /** The map cannot be edited, so the pane offers only the ways of opening the note. */
+ /** Hides the color and remove buttons, leaving only the buttons that open the note. */
isReadOnly: boolean;
/** The note the pane shows, or `null` while the pane is closed. */
selection: PaneSelection | null;
@@ -58,12 +59,12 @@ export default function NotePane({ paneRef, noteIdsOnMap, mapApiRef, isReadOnly,
return true;
}, [ noteIdsOnMap, onSelect ]);
- // The pane opens beside the map each time, however it was left.
+ // Resets the maximized state when the pane closes, so the pane reopens at its normal width.
useEffect(() => {
if (!selection) setMaximized(false);
}, [ selection ]);
- // A note taken off the map, or deleted, closes the pane.
+ // Closes the pane when its note is removed from the map or deleted.
const isOnMap = !!selection && noteIdsOnMap.includes(selection.noteId);
useEffect(() => {
if (selection && (!isOnMap || note === null)) {
@@ -71,14 +72,14 @@ export default function NotePane({ paneRef, noteIdsOnMap, mapApiRef, isReadOnly,
}
}, [ selection, isOnMap, note, closePane ]);
- // A phone's dialog answers Escape itself.
+ // On mobile, the `Modal` handles Escape itself.
useEffect(() => {
if (!selection || isMobile()) return;
const onKeyDown = (e: KeyboardEvent) => {
if (e.key === "Escape") closePane();
};
- // Captured, since `OverlayPanel` stops key presses made inside it from bubbling.
+ // Capture phase, because `OverlayPanel` stops key presses inside it from bubbling.
window.addEventListener("keydown", onKeyDown, true);
return () => window.removeEventListener("keydown", onKeyDown, true);
}, [ selection?.noteId, closePane ]);
@@ -86,8 +87,8 @@ export default function NotePane({ paneRef, noteIdsOnMap, mapApiRef, isReadOnly,
if (!note || !isOnMap) return null;
return (
- // `relation-map-note-pane-host` keeps the wheel, double clicks and touches made in the pane
- // from reaching `panzoom`, which listens on the whole map.
+ // Stops wheel, double-click and touch events in the pane from reaching `panzoom`, which
+ // listens on the whole map.
<div
className="relation-map-note-pane-host"
onWheel={stopPropagation}
diff --git a/apps/client/src/widgets/type_widgets/relation_map/RelationMap.spec.tsx b/apps/client/src/widgets/type_widgets/relation_map/RelationMap.spec.tsx
index d25329081e..ef9e89e954 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/RelationMap.spec.tsx
+++ b/apps/client/src/widgets/type_widgets/relation_map/RelationMap.spec.tsx
@@ -28,7 +28,7 @@ describe("relation map canvas clicks", () => {
}
});
- /** The wrapper, the panned canvas with a box on it, and a toolbar standing over the canvas. */
+ /** Renders the wrapper, the panned canvas with one box, and a toolbar over the canvas. */
function Harness({ placing }: { placing: boolean }) {
const containerRef = useRef<HTMLDivElement>(null);
const clickProps = useCanvasClicks({ containerRef, placing, onPlace, onSelectNote, onClickEmpty, onOpenNote });
@@ -149,7 +149,7 @@ describe("relation map revealing the selected box", () => {
);
}
- /** Lays the map out at 1200 × 800, which happy-dom does not do by itself. */
+ /** Gives the map a 1200 × 800 layout, which happy-dom does not compute. */
function mount(noteId: string | undefined) {
act(() => render(<Harness noteId={noteId} />, container as HTMLElement));
const wrapper = container?.querySelector<HTMLElement>(".wrapper");
@@ -189,7 +189,7 @@ describe("relation map revealing the selected box", () => {
expect(moveBy).toHaveBeenCalledTimes(1);
});
- /** The box is on the map before the note is selected, as for a box that is clicked. */
+ /** Adds the box before selecting its note, as when the user clicks an existing box. */
function addBoxBeforeMount(noteId: string, left: number) {
if (container) render(null, container);
mount(undefined);
diff --git a/apps/client/src/widgets/type_widgets/relation_map/RelationMap.tsx b/apps/client/src/widgets/type_widgets/relation_map/RelationMap.tsx
index 4160ba2d7d..2c5bdf85c8 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/RelationMap.tsx
+++ b/apps/client/src/widgets/type_widgets/relation_map/RelationMap.tsx
@@ -120,7 +120,7 @@ export default function RelationMap({ note, noteContext, ntxId, parentComponent
note,
ntxId,
mapApiRef,
- // The click that places the note has to reach the map, which the pane partly covers.
+ // Closes the pane, which covers part of the map where the note might be placed.
onArm: () => paneRef.current?.close(),
onCreated: (noteId) => setSelection({ noteId, isNew: true })
});
@@ -364,12 +364,12 @@ async function useRelationData(noteId: string, mapData: MapData | undefined, map
}
/**
- * Arms the map for the next click to place a new note, and creates the note where it lands.
+ * Puts the map in placement mode, where the next click creates a note at the clicked position.
*
- * Pressing the button again disarms the map, as Escape does. A translucent box follows the pointer
- * while the map is armed (see {@link GhostNoteBox}). The note is created without a title, so it takes
- * the name any new note takes (or the map's `#titleTemplate`), and the pane opens on it with that
- * name selected.
+ * Pressing the button again or Escape leaves placement mode. While it is on, a translucent box
+ * follows the pointer (see {@link GhostNoteBox}). The note is created without a title, so it gets
+ * the default title (or the map's `#titleTemplate`), and the pane opens on it with the title
+ * selected.
*/
function useNotePlacement({ ntxId, note, containerRef, mapApiRef, onArm, onCreated }: {
ntxId: string | null | undefined;
@@ -388,8 +388,8 @@ function useNotePlacement({ ntxId, note, containerRef, mapApiRef, onArm, onCreat
setPlacing(!placing);
});
- // Tied to the state rather than to what armed it, so the toast and the listener go on cancel,
- // on placement and on unmount alike.
+ // Depends on `placing` rather than on the code that turned placement mode on, so the toast and
+ // the listener are removed on cancel, after placement and on unmount.
useEffect(() => {
if (!placing) return;
@@ -420,7 +420,7 @@ function useNotePlacement({ ntxId, note, containerRef, mapApiRef, onArm, onCreat
const { x, y } = boxPositionAt(e, container);
ghost.style.left = `${x}px`;
ghost.style.top = `${y}px`;
- // Hidden over the toolbars, which a click does not place a note through.
+ // Hides the ghost over the toolbars, where a click does not place a note.
ghost.classList.toggle("visible", isOnCanvas(e, container));
}, [ containerRef ]);
@@ -430,7 +430,7 @@ function useNotePlacement({ ntxId, note, containerRef, mapApiRef, onArm, onCreat
const container = containerRef.current;
if (!container) return;
- // Disarmed first, so a failure to create the note does not leave the map armed.
+ // Leaves placement mode first, so the map does not stay in it if creating the note fails.
setPlacing(false);
const position = boxPositionAt(e, container);
@@ -450,11 +450,10 @@ function useNotePlacement({ ntxId, note, containerRef, mapApiRef, onArm, onCreat
}
/**
- * Routes a click on the map: it places a new note while the map is armed, selects the box it lands
- * on, or closes the pane when it lands on empty canvas. A modified or middle click on a box opens its
- * note the way a link would (a new tab, a new window). A click that ends a pan or a drag counts as
- * none of these, and clicks on whatever stands over the map (toolbars, the pane, the relation name
- * popover) are left alone.
+ * Handles clicks on the map. In placement mode, a click places a new note. Otherwise a click on a
+ * box selects it, and a click on empty canvas closes the pane. A Ctrl, Shift or middle click on a box
+ * opens its note as a link would (new tab or new window). Clicks that end a pan or a drag are
+ * ignored, as are clicks on elements over the map (toolbars, the pane, the relation name popover).
*/
export function useCanvasClicks({ containerRef, placing, onPlace, onSelectNote, onClickEmpty, onOpenNote }: {
containerRef: RefObject<HTMLDivElement | null>;
@@ -466,7 +465,8 @@ export function useCanvasClicks({ containerRef, placing, onPlace, onSelectNote,
}): Pick<HTMLAttributes<HTMLDivElement>, "onPointerDownCapture" | "onClickCapture" | "onAuxClickCapture"> {
const pressedAt = useRef<{ x: number; y: number }>(null);
- /** Whether the click happened on the map itself, without the pointer moving since the press. */
+ /** Whether the click targets the map canvas, with the pointer moved no more than
+ * `CLICK_TOLERANCE` since the press. */
const isPlainClickOnCanvas = (e: MouseEvent, container: HTMLDivElement) => {
const pressed = pressedAt.current;
return isOnCanvas(e, container)
@@ -516,12 +516,11 @@ export function useCanvasClicks({ containerRef, placing, onPlace, onSelectNote,
}
/**
- * Pans the map so the box of the selected note stands clear of the note pane and the edges of the
- * map (see {@link revealOffset}). A phone shows the note as a dialog over the whole screen, so the
- * map is left where it is there.
+ * Pans the map so that the note pane and the map's edges do not cover the selected note's box (see
+ * {@link revealOffset}). Does nothing on mobile, where the note opens in a full-screen dialog.
*
- * The box of a note placed a moment ago is not on the map yet: `NoteBox` renders it once the note
- * has loaded, so the pan waits for it to appear in the container.
+ * The box of a just-placed note is not in the DOM yet, because `NoteBox` renders only after the
+ * note loads, so the hook waits for it with a `MutationObserver`.
*/
export function useRevealSelectedBox({ wrapperRef, containerRef, panZoom, noteId }: {
wrapperRef: RefObject<HTMLDivElement | null>;
@@ -560,7 +559,7 @@ export function useRevealSelectedBox({ wrapperRef, containerRef, panZoom, noteId
}, [ wrapperRef, containerRef, panZoom, noteId ]);
}
-/** Where the pointer stands on a box being placed: the top centre of its title. */
+/** Offset of the pointer from the top-left corner of a box being placed, near the box's top center. */
const PLACEMENT_OFFSET = { x: 80, y: 15 };
/** How far, in pixels, the pointer can move between press and release for the click to count. */
@@ -582,7 +581,7 @@ function boxPositionAt(e: MouseEvent, container: HTMLDivElement) {
return { x: x - PLACEMENT_OFFSET.x, y: y - PLACEMENT_OFFSET.y };
}
-/** Whether the event happened on the map itself, rather than on something standing over it. */
+/** Whether the event target is the map canvas rather than an element over it. */
function isOnCanvas(e: MouseEvent, container: HTMLDivElement) {
return e.target === e.currentTarget || (e.target instanceof Node && container.contains(e.target));
}
diff --git a/apps/client/src/widgets/type_widgets/relation_map/context_menu.ts b/apps/client/src/widgets/type_widgets/relation_map/context_menu.ts
index 41254245bd..d8f3df2b8c 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/context_menu.ts
+++ b/apps/client/src/widgets/type_widgets/relation_map/context_menu.ts
@@ -57,13 +57,12 @@ export function buildNoteContextMenuHandler(note: FNote | null | undefined, mapA
}
/**
- * Asks whether to take the note off the map, and whether to delete it from the tree as well, then
- * does so. Serves the box's context menu and the note pane.
+ * Asks whether to remove the note from the map, and whether to also delete it from the tree, then
+ * does so. Used by the box's context menu and by the note pane.
*/
export async function confirmRemoveFromMap(note: FNote, mapApiRef: RefObject<RelationMapApi | null>) {
- // The branch is all the dialog is told: from it, it works out for itself whether ticking the
- // box would delete the note or merely unfile it here, and says so (see
- // confirmDeleteNoteBoxWithNote).
+ // `confirmDeleteNoteBoxWithNote` receives only the branch, and uses it to tell whether ticking
+ // the checkbox deletes the note or only removes it from this parent.
const result = await dialog.confirmDeleteNoteBoxWithNote(note.title, {
noteId: note.noteId,
branchId: mapApiRef.current?.branchIdFor(note.noteId)
diff --git a/apps/client/src/widgets/type_widgets/relation_map/utils.ts b/apps/client/src/widgets/type_widgets/relation_map/utils.ts
index afa1e949e7..c4d634a4ef 100644
--- a/apps/client/src/widgets/type_widgets/relation_map/utils.ts
+++ b/apps/client/src/widgets/type_widgets/relation_map/utils.ts
@@ -46,10 +46,11 @@ const PANE_REACH = PANE_WIDTH + MAP_INSET;
/** Must agree with the pane's `bottom` in NotePane.css, which clears the toolbars at the foot. */
const MAP_FOOT = 2 * MAP_INSET + 28;
-/** The room kept between a revealed box and whatever bounds the visible part of the map. */
+/** Minimum gap between a revealed box and the edges of the visible area. */
const AIR = 20;
-/** Below this much room beside the pane, the pane is treated as covering the whole map. */
+/** If the map leaves less than this width beside the pane, the pane is ignored and the box is only
+ * kept within the map. */
const MIN_UNCOVERED_WIDTH = 200;
interface Rect {
@@ -60,8 +61,8 @@ interface Rect {
}
/**
- * How far to pan the map so that `box` stands in the part of it the note pane leaves uncovered,
- * or `null` when it already does. Each axis on which the box does not fit is centred in that part;
+ * How far to pan the map so that `box` is in the part of the map not covered by the note pane, or
+ * `null` when it already is. Each axis on which the box does not fit is centred in that part;
* an axis on which it fits is left alone.
*
* Both rectangles are in page coordinates, as `getBoundingClientRect()` gives them, which is also