Skip to content

Build your personal knowledge base with Trilium Notes

client/collections/board: improve comments

Adorian Doran2dc25cc7493b
diff --git a/apps/client/src/menus/context_menu.ts b/apps/client/src/menus/context_menu.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.css
index 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(