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 ForceGraph from "force-graph";
import type FNote from "../../entities/fnote";
import type { IconGlyph } from "../../services/icon_glyphs";
import { escapeHtml } from "../../services/utils";
import { NoteMapLinkObject, NoteMapNodeObject, NotesAndRelationsData } from "./data";
import { getFitPadding, getHopDistances, isRootedAtCurrentNote, mixColors, NoteMapWidgetMode, withAlpha } from "./utils";
/** Roughly a second of simulation at 60 fps — see {@link setupFraming}. */
const TICKS_UNTIL_DAMPED = 60;
/** What a map of a single note is shown at, there being no extent to fit — see {@link setupFraming}. */
const LONE_NOTE_ZOOM = 4;
/** How long a zoom step or a fit to the view takes to play out. */
const ZOOM_ANIMATION_MS = 250;
/** How large a note's dot has to come out on screen, in pixels, before its icon is drawn inside it. */
const MIN_ICON_RADIUS = 7;
/**
* How wide a note's dot is drawn, as a part of the size the graph holds it at. The graph measures the
* room a note takes up by that size, and the dot is drawn a little inside it so that the notes of a
* crowded map are not laid edge to edge.
*/
const NODE_RADIUS_RATIO = 0.8;
/** Above how many framed notes a map is left to settle at its own pace — see {@link setupFraming}. */
const DAMPING_MAX_NOTES = 30;
/** How thick the ring around the note the map is drawn around is on screen. */
const ANCHOR_RING_PX = 2;
/** How much is left of what the pointer is not resting on, while it rests on a note of the map. */
const DIMMED_ALPHA = 0.15;
/** How long the map takes to answer the pointer coming to rest on a note, or leaving one. */
const HOVER_FADE_MS = 160;
/** What a relation is drawn with, and what one of the hovered note's own grows to. */
const LINK_WIDTH = 0.4;
const HIGHLIGHT_LINK_WIDTH = 3;
/** How long a relation's arrowhead is drawn on screen — see {@link paintArrow} for the shape of it. */
const ARROW_LENGTH_PX = 10;
/** How wide it is across the tail, as a part of that length. */
const ARROW_WIDTH_RATIO = 0.72;
/** How far the middle of its tail is swept back in, as a part of that length. */
const ARROW_SWEEP = 0.28;
/**
* How much of that length each of its corners is rounded off by. Kept well under a quarter: a corner
* as sharp as the tip reaches back along both its edges by several times this, and rounding one by
* more than the edges leading to it can give takes the shape apart.
*/
const ARROW_ROUNDING = 0.12;
/** How large a note's label is drawn on screen where the map is neither zoomed in nor out. */
const LABEL_FONT_PX = 11;
/** The same, for the name of a relation, which is read of a map already zoomed into. */
const LINK_LABEL_FONT_PX = 8;
/**
* How much of the zoom a label takes on. None of it holds every label to the same size on screen; all
* of it is the graph's own units, where a title grows without bound as the map is zoomed into. A
* quarter of it carries a label from 11px to about 18px across the whole range of zooms the map
* allows, so that zooming in brings the titles closer without letting them take the map over.
*/
const LABEL_ZOOM_SHARE = 0.25;
/** How wide a label may be, in multiples of its own font size, before what is left of the title is cut. */
const MAX_LABEL_WIDTH_EMS = 12;
/**
* What is laid under a label so that it is read off whatever it crosses — a relation, another note,
* another label — rather than out of it, the way a subtitle is read off the picture behind it.
*
* Neither the spread nor the drop is in the graph's units: a canvas draws a shadow the same whatever
* it has been scaled to, so these hold as the map is zoomed rather than growing with it.
*/
const LABEL_SHADOW = { blur: 4, drop: 1 };
export interface CssData {
fontFamily: string;
textColor: string;
mutedTextColor: string;
/**
* What the map is drawn on: the notes are faded towards it the further they are from the one the
* map is rooted at, and their icons are cut out of them in it.
*/
backgroundColor: string;
/**
* What a note's icon is drawn on and in beside the title of the note being read, which the map
* draws the very same note in — so that the middle of the map and the note it is about are
* plainly one thing. The second doubles as the ring that picks it out: on a dark theme the badge
* is a dark circle, which a map of light notes would otherwise swallow.
*/
anchorColor: string;
anchorIconColor: string;
}
interface RenderData {
note: FNote;
noteIdToSizeMap: Record<string, number>;
cssData: CssData;
/**
* The note the map is drawn around — the one being read, where the map follows it, and otherwise
* the one it has been pointed at. Everything else is coloured by how far it is from this one.
*/
mapRootId: string;
themeStyle: "light" | "dark";
widgetMode: NoteMapWidgetMode;
notesAndRelations: NotesAndRelationsData;
/** The element the graph's canvas lives in, watched for the user taking the view over. */
container: HTMLElement;
/** What each note's icon class resolves to, as the icon pack draws it — see icon_glyphs.ts. */
iconGlyphs: Map<string, IconGlyph>;
/** Called with the scale of the view after every zoom, for controls that depend on it. */
onZoom?: (scale: number) => void;
}
/** What the map's controls drive the drawn graph through. */
export interface MapRendering {
/** Fits the view to the notes the map is framed on as it loads, and stops following the layout. */
fitToView(): void;
/** Zooms the view by `factor` around its middle, and stops following the layout. */
zoomBy(factor: number): void;
/** Undoes the setup, to call when the graph is discarded. */
teardown(): void;
}
export function setupRendering(graph: ForceGraph<NoteMapNodeObject, NoteMapLinkObject>, { note, mapRootId, themeStyle, widgetMode, noteIdToSizeMap, notesAndRelations, cssData, container, iconGlyphs, onZoom }: RenderData): MapRendering {
// What the map is showing of the note under the pointer: the note itself, the notes a relation
// runs between it and, and those relations. Worked out once when the hover changes rather than
// while painting, so that every note of a frame is painted knowing the same thing.
let hoverNode: NoteMapNodeObject | null = null;
let neighbours = new Set<NoteMapNodeObject>();
let highlightLinks = new Set<NoteMapLinkObject>();
let zoomLevel: number;
/** Titles as they are drawn, cut to the width a label is allowed — see {@link getLabel}. */
const labelsByNoteId = new Map<string, string>();
/** How many relations lie between each note and the one the map is rooted at — see {@link setupFraming}. */
const hopDistances = getHopDistances(mapRootId, notesAndRelations.links);
/**
* What the hovered note's own relations are drawn in. Remembered rather than asked of the hovered
* note as it is drawn, so that they have a colour to fade back from once the pointer has left.
*/
let highlightColor = cssData.textColor;
/**
* Where each note and each relation stands between the two things a hover asks of it: -1 faded
* back behind what is hovered, 0 as the map stands with nothing hovered, 1 lit as one of its own.
*/
const nodeFocus = createFade(notesAndRelations.nodes, (node) => (hoverNode && !isInHoveredNeighbourhood(node) ? -1 : 0));
const linkFocus = createFade<NoteMapLinkObject>(notesAndRelations.links, (link) => {
if (!hoverNode) {
return 0;
}
return highlightLinks.has(link) ? 1 : -1;
});
let fadeTimer: ReturnType<typeof setTimeout> | undefined;
/** A canvas of no consequence, kept for what it makes of a colour — see {@link normalizeColor}. */
const colorResolver = document.createElement("canvas").getContext("2d");
/**
* Takes note of what is hovered and of what the map is to show of it: the notes a relation runs
* between it and, and the relations themselves.
*/
function setHoveredNode(node: NoteMapNodeObject | null) {
// Where everything stands is taken down before any of it changes, that being what the fade
// about to start reads from.
nodeFocus.restart();
linkFocus.restart();
keepPaintingThroughFade();
hoverNode = node;
if (!hoverNode) {
neighbours = new Set();
highlightLinks = new Set();
return;
}
highlightColor = normalizeColor(getNodeColors(hoverNode, cssData).fill);
({ neighbours, highlightLinks } = getHoveredNeighbourhood(hoverNode, notesAndRelations.links));
}
/** Whether the note is the hovered one or one a relation runs between it and — all of them, while nothing is hovered. */
function isInHoveredNeighbourhood(node: NoteMapNodeObject) {
return !hoverNode || node === hoverNode || neighbours.has(node);
}
/**
* What a relation is drawn in, where it stands between the map's own muted colour and the colour
* of the note being hovered — so that what leads to and from that note is read as belonging to it,
* arrowheads included, which take the colour of the line they end. The rest of the map's relations
* fade back with the notes they run between.
*
* A relation cannot be faded the way a note is, the graph being handed its colour rather than
* drawing it, so what it is faded by is asked for as part of the colour.
*/
function getLinkColor(link: NoteMapLinkObject) {
const focus = linkFocus.get(link);
const lit = Math.max(0, focus);
const color = lit <= 0 ? cssData.mutedTextColor
: lit >= 1 ? highlightColor
: mixColors(cssData.mutedTextColor, highlightColor, lit);
return withAlpha(color, getFadedAlpha(focus));
}
/**
* The colour as a canvas keeps it — `#rrggbb` — whatever it was written as, a note being free to
* ask for any colour CSS knows by name. Only that form can be faded or mixed with another.
*/
function normalizeColor(color: string) {
if (!colorResolver) {
return color;
}
colorResolver.fillStyle = "#000000";
colorResolver.fillStyle = color;
return typeof colorResolver.fillStyle === "string" ? colorResolver.fillStyle : color;
}
/**
* Keeps the canvas painting for as long as a fade runs. It is otherwise only repainted once
* something has changed — and a fade is not a change, it is what follows one.
*/
function keepPaintingThroughFade() {
graph.autoPauseRedraw(false);
clearTimeout(fadeTimer);
fadeTimer = setTimeout(() => graph.autoPauseRedraw(true), HOVER_FADE_MS + 100);
}
/**
* The note's title, for the tooltip that stands over it while it is hovered — or nothing at all
* where the map is already showing the title in full under the note, the tooltip then being a
* second copy of what the pointer is resting on.
*
* A title cut down to the width a label is allowed still earns one, since the rest of it is what
* the reader is missing. So does one whose label the map is not drawing at all — a note with no
* entry in the map has never had its label drawn, and cannot have it in full.
*/
function getTooltip(node: NoteMapNodeObject) {
const shownInFull = isLabelDrawn(noteIdToSizeMap[node.id], zoomLevel) && labelsByNoteId.get(node.id) === node.name;
return shownInFull ? "" : escapeHtml(node.name);
}
function paintNode(node: NoteMapNodeObject, color: string, ctx: CanvasRenderingContext2D) {
const { x, y } = node;
// A coordinate of exactly 0 is a position like any other, and a common one: d3 lays the
// first node out at an angle of 0, so its y is 0 — and in a one-node map nothing ever moves
// it off that axis, which used to leave the map permanently blank.
if (x === undefined || y === undefined) {
return;
}
const size = noteIdToSizeMap[node.id];
const radius = size * NODE_RADIUS_RATIO;
ctx.fillStyle = color;
ctx.beginPath();
ctx.arc(x, y, radius, 0, 2 * Math.PI, false);
ctx.fill();
// The note the map is drawn around wears a ring, which is what picks it out of the notes
// around it: it is drawn as its icon is drawn beside its title, and on a dark theme that is a
// dark circle — the quietest thing on a map whose notes are the light ones. The ring is in
// the colour of the icon within it, so it is of the badge rather than something laid over it.
if (node.id === mapRootId) {
const width = ANCHOR_RING_PX / zoomLevel;
ctx.strokeStyle = cssData.anchorIconColor;
ctx.lineWidth = width;
ctx.beginPath();
ctx.arc(x, y, radius + width / 2, 0, 2 * Math.PI, false);
ctx.stroke();
}
paintNodeIcon(node, size, x, y, ctx);
if (!isLabelDrawn(size, zoomLevel)) {
return;
}
const fontSize = getLabelFontSize(LABEL_FONT_PX, zoomLevel);
ctx.save();
castLabelShadow(ctx);
ctx.fillStyle = cssData.textColor;
ctx.font = `${fontSize}px ${cssData.fontFamily}`;
ctx.textAlign = "center";
ctx.textBaseline = "middle";
ctx.fillText(getLabel(node, ctx, fontSize), x, y + radius + fontSize);
ctx.restore();
}
/**
* Lays a shadow of the map's own background under the text drawn next, so that it is read off
* whatever it crosses rather than out of it — a note's title has the whole map to cross.
*
* The background is taken from the theme rather than read off the map: the map's own element is
* see-through, so what is behind a label is whatever is behind the map.
*/
function castLabelShadow(ctx: CanvasRenderingContext2D) {
ctx.shadowColor = themeStyle === "dark" ? "rgba(0, 0, 0, 0.85)" : "rgba(255, 255, 255, 0.9)";
ctx.shadowBlur = LABEL_SHADOW.blur;
ctx.shadowOffsetY = LABEL_SHADOW.drop;
}
/**
* The note's title, cut down to what a label is allowed to be wide.
*
* Measured rather than counted: a count of characters cuts a title of wide ones halfway across the
* map and one of narrow ones long before it had to. The width allowed is in multiples of the font
* size and the measuring is in the graph's units, so the zoom is on both sides of the comparison
* and cancels out — what fits at one zoom fits at every other, and is worked out once per note.
*/
function getLabel(node: NoteMapNodeObject, ctx: CanvasRenderingContext2D, fontSize: number) {
const cached = labelsByNoteId.get(node.id);
if (cached !== undefined) {
return cached;
}
const label = truncateLabel(node.name, fontSize, (text) => ctx.measureText(text).width);
labelsByNoteId.set(node.id, label);
return label;
}
/**
* The note's own icon, cut out of the dot standing for it — the same one the tree and the tabs
* draw it with, so a note is recognised in the map by what it is recognised by everywhere else.
*
* Drawn as it is drawn beside a title, in the colour that goes with the badge under it.
*
* A note that asks for a colour of its own has no such pairing to draw on, so its icon is cut out
* of it in the colour of what the map is laid on: whatever the note asks to be drawn in, the page
* behind it is something else.
*
* Only where the dot is drawn large enough on screen to hold it: below that the glyph is a smudge
* over the colour, and the colour alone says more.
*/
function paintNodeIcon(node: NoteMapNodeObject, size: number, x: number, y: number, ctx: CanvasRenderingContext2D) {
const glyph = iconGlyphs.get(node.icon);
if (!glyph || !isIconDrawn(size, zoomLevel)) {
return;
}
ctx.fillStyle = getNodeColors(node, cssData).icon;
// The pack's own font rather than one font for the map: a note may wear an icon from a pack
// the user brought along, whose characters are numbered as the built-in one's are.
ctx.font = `${size}px ${glyph.fontFamily}`;
ctx.textAlign = "center";
ctx.textBaseline = "middle";
ctx.fillText(glyph.content, x, y);
}
/**
* The arrowhead that says which way a relation runs, drawn where the line meets the note it points
* at — a swept chevron with every corner rounded off, rather than the hard little wedge the graph
* draws of its own accord.
*
* Held to a size on screen the way the labels are, so that it neither disappears on a map zoomed
* out nor grows into a spearhead on one zoomed in. It is also placed against the dot as the map
* actually draws it: the graph sizes every note the same for this, which buries the arrowhead
* inside the larger ones.
*/
function paintArrow(link: NoteMapLinkObject, source: NoteMapNodeObject, target: NoteMapNodeObject, ctx: CanvasRenderingContext2D) {
const length = getLabelFontSize(ARROW_LENGTH_PX, zoomLevel);
const outline = getArrowOutline(
{ x: source.x ?? 0, y: source.y ?? 0 },
{ x: target.x ?? 0, y: target.y ?? 0 },
noteIdToSizeMap[target.id] * NODE_RADIUS_RATIO,
length
);
if (!outline) {
return;
}
ctx.save();
// The corners are rounded into the outline itself rather than stroked round afterwards: a
// stroke over a fill is drawn twice where the two meet, which tells on an arrowhead faded
// back behind a hover as a rim darker than the rest of it.
traceRoundedPath(ctx, outline, length * ARROW_ROUNDING);
ctx.fillStyle = getLinkColor(link);
ctx.fill();
ctx.restore();
}
function paintLink(link: NoteMapLinkObject, ctx: CanvasRenderingContext2D) {
const { source, target } = link;
if (typeof source !== "object" || typeof target !== "object") {
return;
}
if (source.x !== undefined && source.y !== undefined && target.x !== undefined && target.y !== undefined) {
paintArrow(link, source, target, ctx);
}
if (zoomLevel < 5) {
return;
}
// Held to a size the same way a note's label is, from a smaller one: the name of a relation
// is there to be read of a map already zoomed into, not to stand alongside the names of the
// notes it runs between.
const fontSize = getLabelFontSize(LINK_LABEL_FONT_PX, zoomLevel);
ctx.font = `${fontSize}px ${cssData.fontFamily}`;
ctx.textAlign = "center";
ctx.textBaseline = "middle";
ctx.fillStyle = cssData.mutedTextColor;
if (source.x !== undefined && source.y !== undefined && target.x !== undefined && target.y !== undefined) {
const x = (source.x + target.x) / 2;
const y = (source.y + target.y) / 2;
ctx.save();
ctx.translate(x, y);
const deltaY = source.y - target.y;
const deltaX = source.x - target.x;
let angle = Math.atan2(deltaY, deltaX);
// Riding just off the line rather than sitting across it, by a distance of its own text's
// making — a fixed one would ride further off it the smaller the text is drawn.
let moveY = fontSize * 0.7;
if (angle < -Math.PI / 2 || angle > Math.PI / 2) {
angle += Math.PI;
moveY = -moveY;
}
castLabelShadow(ctx);
ctx.rotate(angle);
ctx.fillText(link.name, 0, moveY);
// Restored within the turn that saved it: the canvas is left as it was found either way,
// rather than being handed back a state that was never put on for a relation drawn with
// an end still to be placed.
ctx.restore();
}
}
graph
.d3AlphaDecay(0.01)
.d3VelocityDecay(0.08)
.maxZoom(7)
.warmupTicks(30)
.nodeCanvasObject((node, ctx) => {
// Every note keeps its own colour while one of them is hovered; what tells the note's
// own from the rest of the map is that the rest of it is faded back behind them.
ctx.save();
// Every note is drawn whole; the only thing that steps one back is the pointer resting on
// another note than it.
ctx.globalAlpha = getFadedAlpha(nodeFocus.get(node));
paintNode(node, getNodeColors(node, cssData).fill, ctx);
ctx.restore();
})
.onNodeHover((node) => setHoveredNode(node ?? null))
.nodePointerAreaPaint((node, color, ctx) => {
if (!node.id) {
return;
}
ctx.fillStyle = color;
ctx.beginPath();
if (node.x !== undefined && node.y !== undefined) {
ctx.arc(node.x, node.y, noteIdToSizeMap[node.id], 0, 2 * Math.PI, false);
}
ctx.fill();
})
.nodeLabel((node) => getTooltip(node))
.onZoom((zoom) => {
zoomLevel = zoom.k;
onZoom?.(zoom.k);
});
graph
.linkWidth((link) => LINK_WIDTH + (HIGHLIGHT_LINK_WIDTH - LINK_WIDTH) * Math.max(0, linkFocus.get(link)))
.linkColor((link) => getLinkColor(link))
// The arrowheads are drawn along with the relations themselves (see paintArrow); the graph's
// own are left off entirely rather than drawn under them.
.linkDirectionalArrowLength(0);
graph
.linkLabel((link) => {
const { source, target } = link;
if (typeof source !== "object" || typeof target !== "object") return escapeHtml(link.name);
return `${escapeHtml(source.name)} - <strong>${escapeHtml(link.name)}</strong> - ${escapeHtml(target.name)}`;
})
// Drawn after the relation itself rather than in place of it: the line is the graph's to draw,
// the arrowhead at the end of it and the name along it are this map's.
.linkCanvasObject((link, ctx) => paintLink(link, ctx))
.linkCanvasObjectMode(() => "after");
// Forces
const nodeLinkRatio = notesAndRelations.nodes.length / notesAndRelations.links.length;
const magnifiedRatio = Math.pow(nodeLinkRatio, 1.5);
const charge = -20 / magnifiedRatio;
const boundedCharge = Math.min(-3, charge);
graph.d3Force("center")?.strength(0.2);
graph.d3Force("charge")?.strength(boundedCharge);
graph.d3Force("charge")?.distanceMax(1000);
const framing = setupFraming(graph, container, { note, widgetMode, notesAndRelations, hopDistances });
return {
fitToView() {
framing.release();
framing.fit(ZOOM_ANIMATION_MS);
},
zoomBy(factor) {
framing.release();
graph.zoom(graph.zoom() * factor, ZOOM_ANIMATION_MS);
},
teardown() {
clearTimeout(fadeTimer);
framing.stop();
}
};
}
/**
* What the map is to show of the note under the pointer: the notes a relation runs between it and,
* and the relations themselves. Which way round a relation runs is not what this asks — a note is as
* much a neighbour for being pointed at as for pointing.
*
* Worked out once when the hover changes rather than while painting, so that every note of a frame is
* painted knowing the same thing.
*/
export function getHoveredNeighbourhood(hoverNode: NoteMapNodeObject, links: NoteMapLinkObject[]) {
const neighbours = new Set<NoteMapNodeObject>();
const highlightLinks = new Set<NoteMapLinkObject>();
for (const link of links) {
const { source, target } = link;
// Both ends are notes of the map by the time it is drawn, the graph having looked up what the
// data carries as ids.
if (typeof source !== "object" || typeof target !== "object") {
continue;
}
if (source.id === hoverNode.id) {
neighbours.add(target);
highlightLinks.add(link);
} else if (target.id === hoverNode.id) {
neighbours.add(source);
highlightLinks.add(link);
}
}
return { neighbours, highlightLinks };
}
/** How much of a note or a relation is drawn, from all of it to {@link DIMMED_ALPHA} faded back. */
export function getFadedAlpha(focus: number) {
return DIMMED_ALPHA + (1 - DIMMED_ALPHA) * Math.min(1, 1 + focus);
}
/**
* What a note is drawn in, and what its icon is cut out of it in.
*
* The badge its icon is shown in beside a title, wherever a note is shown at a size. Every note of the
* map wears it, whole — which of them the map is drawn around is said by the ring, and what kind of
* note each is by the icon within it.
*
* A note that asks for a colour of its own is given it: that is the reader's own doing, and it says
* something no map should talk over. It has no badge pairing to draw its icon in, though, so the icon
* is cut out of it in the colour of what the map is laid on — whatever the note asks to be drawn in,
* the page behind it is something else.
*/
export function getNodeColors(node: Pick<NoteMapNodeObject, "color">, cssData: CssData) {
return {
fill: node.color || cssData.anchorColor,
icon: node.color ? cssData.backgroundColor : cssData.anchorIconColor
};
}
/**
* The size to draw text at in the graph's own units, for a size on screen.
*
* The canvas is scaled by the zoom, so text measured in the graph's units is drawn as large as the map
* is zoomed in — which is how a title once came to stand taller than the note it belonged to. Dividing
* the size on screen back out by the zoom holds it to a size of its own, and the share of the zoom it
* is given back (see {@link LABEL_ZOOM_SHARE}) is what still lets it grow.
*/
export function getLabelFontSize(screenPx: number, zoomLevel: number) {
return screenPx * zoomLevel ** LABEL_ZOOM_SHARE / zoomLevel;
}
/**
* Whether a note of the given size has its label drawn under it as the map stands: the smaller the
* note, the further in the map has to be zoomed before its name is worth the clutter.
*/
export function isLabelDrawn(size: number, zoomLevel: number) {
return zoomLevel > 2 || (zoomLevel > 1 && size > 6) || (zoomLevel > 0.3 && size > 10);
}
/**
* Whether the note's dot comes out large enough on screen to hold its icon. Below that the glyph is a
* smudge over the colour, and the colour alone says more.
*/
export function isIconDrawn(size: number, zoomLevel: number) {
return size * NODE_RADIUS_RATIO * zoomLevel >= MIN_ICON_RADIUS;
}
/**
* The title cut down to what a label is allowed to be wide, with an ellipsis for what is left off.
*
* Measured rather than counted: a count of characters cuts a title of wide ones halfway across the map
* and one of narrow ones long before it had to. The width allowed is in multiples of the font size and
* the measuring is in the graph's units, so the zoom is on both sides of the comparison and cancels
* out — what fits at one zoom fits at every other.
*
* @param measureWidth how wide the text comes out, as the canvas it is to be drawn on measures it.
*/
export function truncateLabel(title: string, fontSize: number, measureWidth: (text: string) => number) {
const maxWidth = MAX_LABEL_WIDTH_EMS * fontSize;
if (measureWidth(title) <= maxWidth) {
return title;
}
let label = title;
// The ellipsis is part of what has to fit, so it is measured along with what is left of the title.
while (label.length > 1 && measureWidth(`${label}…`) > maxWidth) {
label = label.slice(0, -1);
}
return `${label}…`;
}
/**
* The corners of the arrowhead that says which way a relation runs — a swept chevron, drawn where the
* line meets the note it points at, rather than the hard little wedge the graph draws of its own
* accord. Rounded off by whoever traces it (see {@link traceRoundedPath}).
*
* Nothing at all where the two notes are so close together that there is nowhere to put it that is not
* inside one of them, where it would be drawn pointing back the way it came.
*
* @param targetRadius the dot the arrowhead stops at, as the map actually draws it: the graph sizes
* every note the same for this, which buries the arrowhead inside the larger ones.
* @param length how long the arrowhead is, in the graph's units.
*/
export function getArrowOutline(source: { x: number, y: number }, target: { x: number, y: number }, targetRadius: number, length: number) {
const lineLength = Math.hypot(target.x - source.x, target.y - source.y);
if (lineLength < targetRadius + length) {
return null;
}
const alongX = (target.x - source.x) / lineLength;
const alongY = (target.y - source.y) / lineLength;
const tipX = target.x - alongX * targetRadius;
const tipY = target.y - alongY * targetRadius;
const baseX = tipX - alongX * length;
const baseY = tipY - alongY * length;
const halfWidth = length * ARROW_WIDTH_RATIO / 2;
// The notch the tail is swept back to, which is what keeps it an arrowhead rather than a triangle
// sitting on the line.
const notchX = baseX + alongX * length * ARROW_SWEEP;
const notchY = baseY + alongY * length * ARROW_SWEEP;
return [
[ tipX, tipY ],
[ baseX - alongY * halfWidth, baseY + alongX * halfWidth ],
[ notchX, notchY ],
[ baseX + alongY * halfWidth, baseY - alongX * halfWidth ]
] satisfies [ number, number ][];
}
/**
* Lays out a shape whose every corner is rounded off, ready to be filled.
*
* Each corner is drawn as an arc between the middles of the two edges that meet at it, which is what
* lets one call round all of them however sharp each turns out to be — the tip of an arrowhead being
* a good deal sharper than its tail.
*
* @param radius how much of each corner to round off, in the units the points are given in.
*/
export function traceRoundedPath(ctx: CanvasRenderingContext2D, points: [ number, number ][], radius: number) {
const middleOf = (from: [ number, number ], to: [ number, number ]) => [ (from[0] + to[0]) / 2, (from[1] + to[1]) / 2 ] as const;
const [ startX, startY ] = middleOf(points[points.length - 1], points[0]);
ctx.beginPath();
ctx.moveTo(startX, startY);
for (let i = 0; i < points.length; i++) {
const corner = points[i];
const [ towardsX, towardsY ] = middleOf(corner, points[(i + 1) % points.length]);
ctx.arcTo(corner[0], corner[1], towardsX, towardsY, radius);
}
ctx.closePath();
}
/**
* Values that make their way to where a change puts them over {@link HOVER_FADE_MS}, rather than
* being there the moment it is made.
*
* Each is read from where it stood when the change was made and where it is to end up, so a pointer
* carried straight from one note to another takes each of them from wherever the last change had left
* it — rather than from where a fade of the whole map would have them all start together.
*
* @param getTarget where the value should end up, as things stand now.
*/
export function createFade<T>(elements: T[], getTarget: (element: T) => number) {
const startingPoints = new Map<T, number>();
let startedAt = 0;
function get(element: T) {
const target = getTarget(element);
const from = startingPoints.get(element) ?? target;
const progress = Math.min(1, (performance.now() - startedAt) / HOVER_FADE_MS);
return from + (target - from) * progress;
}
return {
get,
/** Takes down where every value stands, for the fade the caller is about to bring about to start from. */
restart() {
for (const element of elements) {
startingPoints.set(element, get(element));
}
startedAt = performance.now();
}
};
}
/**
* Keeps the view framed on the interesting part of the graph — the notes reachable from the current
* note in the maps rooted at it, the linked notes elsewhere — while the layout settles.
*
* The fit runs on every tick of the simulation rather than once after a fixed delay: the layout
* keeps expanding for seconds after the data lands, so a single delayed fit leaves the map at
* force-graph's default zoom meanwhile (a few nodes around the origin, the rest already spread out
* of sight) and then jumps to the real framing when it finally fires.
*
* @returns `fit()`, which frames the view as the map does while it settles, `release()`, which stops
* the framing, and `stop()`, to call when the graph is discarded.
*/
function setupFraming(graph: ForceGraph<NoteMapNodeObject, NoteMapLinkObject>, container: HTMLElement, { note, widgetMode, notesAndRelations, hopDistances }: Pick<RenderData, "note" | "widgetMode" | "notesAndRelations"> & { hopDistances: Map<string, number> }) {
const { framedNoteIds, framesSubset, padding, fittedNoteCount } = planFraming({ widgetMode, noteType: note?.type, notesAndRelations, hopDistances });
const nodeFilter = framesSubset
? (node: NoteMapNodeObject) => framedNoteIds.has(node.id)
: undefined;
// Panning or zooming hands the view over to the user for good — re-fitting under their fingers
// would make the map impossible to explore while it is still settling.
//
// Listened for while the event is still on its way down: d3-zoom, which force-graph binds to the
// canvas within this element, calls stopImmediatePropagation() on the wheel events it acts on, so
// a listener waiting for them to come back up is never told about a zoom at all. It would then
// re-fit over every notch of the wheel until the simulation came to rest — the map answering the
// wheel by snapping back for as long as a quarter of a minute.
const listenerOptions = { capture: true, passive: true };
let framing = true;
const releaseFraming = () => framing = false;
container.addEventListener("wheel", releaseFraming, listenerOptions);
container.addEventListener("pointerdown", releaseFraming, listenerOptions);
// Fitting is what centres the view on the note, whether or not its zoom is kept.
const fit = (duration: number) => {
graph.zoomToFit(duration, padding, nodeFilter);
if (fittedNoteCount <= 1) {
graph.zoom(LONE_NOTE_ZOOM, duration);
}
};
let ticks = 0;
graph.onEngineTick(() => {
if (framing) {
fit(0);
}
// Damping, once the graph has had the room to spread out, so that a small map comes to rest
// instead of drifting for the whole cooldown.
if (++ticks === TICKS_UNTIL_DAMPED && framedNoteIds.size < DAMPING_MAX_NOTES) {
graph.d3VelocityDecay(0.4);
}
});
return {
fit,
release: releaseFraming,
stop() {
container.removeEventListener("wheel", releaseFraming, listenerOptions);
container.removeEventListener("pointerdown", releaseFraming, listenerOptions);
}
};
}
/**
* What the view is to be framed on, worked out once from the map's data — see {@link setupFraming} for
* what is done with it.
*/
export function planFraming({ widgetMode, noteType, notesAndRelations, hopDistances }: {
widgetMode: NoteMapWidgetMode;
/** Of the note the map is drawn for, a search note being no part of its own results. */
noteType: string | undefined;
notesAndRelations: NotesAndRelationsData;
hopDistances: Map<string, number>;
}) {
// The notes that can be reached from the one the map is rooted at, which is what the distances
// drawn on are a walk of already.
const framedNoteIds: Set<string | number> = (isRootedAtCurrentNote(widgetMode) && noteType !== "search")
? new Set(hopDistances.keys())
: getNoteIdsWithLinks(notesAndRelations);
// A lone note has no extent to fit and would just be blown up to the maximum zoom, hiding the
// rest of the map; the whole graph is the more useful thing to look at then.
const framesSubset = framedNoteIds.size > 1;
return {
framedNoteIds,
framesSubset,
padding: getFitPadding(widgetMode, framedNoteIds.size),
/**
* What the fit is measured on: the framed notes, or the whole graph where those are no more
* than the one note. A note whose map is only itself has no extent to fit at all — the fit
* then asks for a zoom of hundreds and gets the highest allowed, which fills the card with a
* single circle and the beginning of a title. It is shown at a size it can be read at instead.
*/
fittedNoteCount: framesSubset ? framedNoteIds.size : notesAndRelations.nodes.length
};
}
function getNoteIdsWithLinks(data: NotesAndRelationsData) {
const noteIds = new Set<string | number>();
for (const link of data.links) {
if (typeof link.source === "object" && link.source.id) {
noteIds.add(link.source.id);
}
if (typeof link.target === "object" && link.target.id) {
noteIds.add(link.target.id);
}
}
return noteIds;
}