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
client/collections/board: improve comments
Adorian Doran2dc25cc7493b
diff --git a/apps/client/src/menus/context_menu.ts b/apps/client/src/menus/context_menu.tsindex 06ac965e6d..e5b4e0291a 100644--- a/apps/client/src/menus/context_menu.ts+++ b/apps/client/src/menus/context_menu.ts@@ -330,9 +330,8 @@ class ContextMenu {const $link = $("<span>").append($icon)- // An element rather than spaces: a row is a flex line, so text between the icon and the- // title merges with a plain title but is trimmed before a title boxed by `menuName()`,- // leaving the two kinds of row indented differently.+ // An element, not spaces: in a flex row, text merges with a plain title but is+ // trimmed before one boxed by `menuName()`, indenting the two kinds of row apart..append($("<span>").addClass("tn-menu-gap")).append(item.title);diff --git a/apps/client/src/widgets/collections/board/api.ts b/apps/client/src/widgets/collections/board/api.tsindex dfcb7a8534..59cdc4a5dd 100644--- a/apps/client/src/widgets/collections/board/api.ts+++ b/apps/client/src/widgets/collections/board/api.ts@@ -586,9 +586,8 @@ export default class BoardApi {/*** Whether a column other than `except` already uses a name.*- * Checks the columns on the board and the stored ones, so an empty column counts too. Titles- * are compared as well as values: the inbox is named by `displayName`, which reads as the same- * name to the user.+ * Compares titles as well as values, since the inbox is named by `displayName`, and covers the+ * stored columns so that an empty one counts.*/private isColumnNameTaken(name: string, except: string) {const values = new Set([ ...this.columns, ...this.storedColumns.map(col => col.value) ]);@@ -602,11 +601,10 @@ export default class BoardApi {}/**- * The columns as something outside the board lists them: what each is called, the icon it- * shows and how many cards it holds. The right pane's outline is drawn from this.+ * What each column is called, the icon it shows and how many cards it holds, which the right+ * pane's outline is drawn from.*- * A relation board keys its columns by note id and names them with the note's own title, which- * is what its headings show; the id says nothing to a reader on its own.+ * A relation board keys its columns by note id, so each one is named from the note's title.*/getColumnOutline(columns: string[]) {return columns.map(column => ({@@ -686,9 +684,9 @@ export default class BoardApi {/*** Sets how wide the columns are drawn.*- * The default takes the label off the board note, which keeps it tidy. A board that inherits a- * width from a template or a parent writes the default out instead: dropping its own label- * there would hand the board the inherited width back.+ * Picking the default removes the label, to keep the note tidy. Where a template or a parent+ * sets the label, the default is written out instead: `removeOwnedLabelByName` would leave the+ * inherited value in force.*/async setColumnWidth(width: ColumnWidth) {const note = this.parentNote;diff --git a/apps/client/src/widgets/collections/board/board_drag.spec.tsx b/apps/client/src/widgets/collections/board/board_drag.spec.tsxindex 4cf0af9d78..bebf248764 100644--- a/apps/client/src/widgets/collections/board/board_drag.spec.tsx+++ b/apps/client/src/widgets/collections/board/board_drag.spec.tsx@@ -829,8 +829,8 @@ describe("useBoardDrag, carrying a card", () => {Number(preview()?.style.transform.match(/translate3d\([^,]+,\s*(-?[\d.]+)px/)?.[1]);const showing = parseFloat(getComputedStyle(card("c3")).fontSize) * 1.5;- // A card of its own height, carried above the board's head. Above the page here, as- // the board's own head is below the window's in the app.+ // A card of its own height, carried above the board's head. Negative here: in the app+ // the board's head sits below the window's.takeHold();move(50, -60);act(() => { vi.advanceTimersByTime(20); });diff --git a/apps/client/src/widgets/collections/board/board_drag.ts b/apps/client/src/widgets/collections/board/board_drag.tsindex 36a2507323..a4060c9609 100644--- a/apps/client/src/widgets/collections/board/board_drag.ts+++ b/apps/client/src/widgets/collections/board/board_drag.ts@@ -260,9 +260,8 @@ export function useBoardDrag(markEnd(held, end, column);- // A collapsed column draws no card area and holds no cards on screen, so a card- // carried over it goes to the front of whatever it holds. Either of its ends can still- // be asked for, which is what saves opening it to place a card there.+ // A collapsed column draws no card area, so a card carried over it goes to the front.+ // Either end can still be asked for, placing a card there without opening the column.const position = column? {column: column.value,@@ -334,10 +333,8 @@ export function useBoardDrag(const drawn = grab.height * DRAG_SCALE / 2;const top = Math.max(middle - drawn, view.top);const bottom = Math.min(middle + drawn, view.bottom);- // How much of the copy the board still shows, of what it can show at all: it stops- // with a sliver of itself in view, so that sliver is where the fade ends rather than- // nothing at all. One while the copy is wholly in view, zero once it is against the- // edge, whatever the card's height.+ // How much of the copy is in view, measured against the least it can show rather than+ // against nothing: 1 while wholly in view, 0 once it is against the edge.const height = drawn * 2;const least = height > 0 ? Math.min(1, (held.showing ?? 0) / height) : 1;const shown = height > 0 ? Math.max(0, Math.min(1, (bottom - top) / height)) : 1;@@ -354,13 +351,9 @@ export function useBoardDrag(/** Says where the card would land, and whether it has come to rest on that column. *//**- * How far the copy stands back from the pointer while an end is being asked for: it follows- * the pointer out of the board only until {@link EDGE_SHOWING} of it is left in view, and- * goes no further however far past that the pointer goes.- *- * The far edge is the one left showing: the copy's foot at the board's head, its head at- * the board's foot. Nothing to stand back while no end is being asked for, where the copy- * follows the pointer wherever it goes.+ * How far back from the pointer the copy is drawn while an end is being asked for, so that+ * it leaves the board only until {@link EDGE_SHOWING} of it is still in view. Returns 0+ * while no end is being asked for, where the copy follows the pointer exactly.*/const holdBack = (held: Gesture) => {const grab = held.grab;@@ -460,8 +453,7 @@ export function useBoardDrag(held.frame = undefined;if (!gesture.current || !held.preview) return;- // Resolved first: where the copy stands depends on whether an end is being- // asked for, which is what this works out.+ // Resolved first: where the copy stands depends on the end being asked for.resolve(held);const dx = held.lastX - held.startX;@@ -830,8 +822,8 @@ function lift(held: Gesture, container: HTMLElement) {preview.style.setProperty("--board-column-custom-hue", hue);}- // A colour of the card's own, which the overlay takes before the hue of whatever column it is- // held over, and the card's own em. Read here rather than on every move: both take a page read.+ // The card's own colour and its em, read here rather than on every move: both cost a page+ // read.const style = getComputedStyle(held.element);const ownHue = held.element.classList.contains("with-hue")? style.getPropertyValue("--custom-color-hue").trim()diff --git a/apps/client/src/widgets/collections/board/index.css b/apps/client/src/widgets/collections/board/index.cssindex 285b055e6e..ed1fd42926 100644--- a/apps/client/src/widgets/collections/board/index.css+++ b/apps/client/src/widgets/collections/board/index.css@@ -612,8 +612,7 @@ body.mobile .board-view-container .board-add-column {justify-content: center;border-radius: inherit;padding: var(--card-padding);- /* Drained of colour until a hue is named, so a card with none of its own held over a plain- column reads as grey rather than red. */+ /* No saturation until `hint-tinted` sets it, so an unnamed hue paints grey rather than red. */background-color: hsl(var(--board-drop-hint-hue, 0),0%,@@ -634,9 +633,8 @@ body.mobile .board-view-container .board-add-column {);}-/* The focus ring the copy carries would stand around the overlay, which reads on its own. The copy- fades as it leaves the board, `--board-drag-visible` running from one while it is wholly in view- to zero once it stands against the edge. */+/* No focus ring while the overlay is up: it would outline the overlay rather than the card. The+ opacity follows `--board-drag-visible`, 1 while the copy is in view and 0 against the edge. */.board-view-container .board-drag-preview.showing-drop-hint {outline: none;opacity: calc(