Skip to content

Build your personal knowledge base with Trilium Notes

client/collections/board: update comments

Adorian Doranadcfeedbe989
diff --git a/apps/client/src/widgets/collections/board/api.ts b/apps/client/src/widgets/collections/board/api.ts
index 21b6bce6ca..d35c57157a 100644
--- a/apps/client/src/widgets/collections/board/api.ts
+++ b/apps/client/src/widgets/collections/board/api.ts
@@ -179,12 +179,11 @@ export default class BoardApi {
}
/**
- * Files a card under the inbox, which is to say leaves it carrying no value at all.
+ * Files a card under the inbox, which means leaving it with no grouping value at all.
*
- * Told apart from {@link removeFromBoard}, which takes away what the card owns and is content
- * to uncover whatever that was covering. Landing in the inbox is a stronger thing to ask: a
- * relation the card takes from elsewhere would still be pointing somewhere afterwards, and the
- * card would arrive in that column instead of the one it was aimed at.
+ * Different from {@link removeFromBoard}, which removes only the value the card owns and may
+ * uncover an inherited one. Reaching the inbox is stricter: an inherited relation would still
+ * point somewhere, so the card would end up in that column instead.
*/
private moveToInbox(noteId: string) {
const note = froca.getNoteFromCache(noteId);
@@ -287,9 +286,8 @@ export default class BoardApi {
}
async renameColumn(oldValue: string, newValue: string) {
- // A column is known by the value its cards carry, so a blank name is not a name: it would
- // write an empty label over every card in the column and leave nothing to group them by.
- // The editor is simply left as it was.
+ // A column is identified by the value its cards carry, so a blank name would write an
+ // empty label over every card and leave nothing to group by. The old name is kept.
if (!newValue.trim()) {
return;
}
@@ -319,8 +317,8 @@ export default class BoardApi {
}
/**
- * What a column is called on screen, which is the value its cards carry everywhere but the
- * inbox: that one stands for the cards carrying no value, so it has a name of its own.
+ * The title shown for a column. For most columns this is the grouping value itself; the
+ * inbox has no value, so it uses a name stored in the config.
*/
getColumnTitle(column: string) {
const named = this.viewConfig?.columns?.find(col => col.value === column)?.displayName;
@@ -330,9 +328,9 @@ export default class BoardApi {
/**
* Renames a column however that column is named.
*
- * A column is ordinarily known by the value its cards carry, so renaming it writes that value
- * across them. The inbox stands for the cards carrying none, so it holds a name of its own
- * instead and the cards are left alone.
+ * Most columns are identified by the value their cards carry, so renaming writes that value
+ * to every card in the column. The inbox has no value, so it stores a display name instead and
+ * its cards are left untouched.
*/
async setColumnTitle(column: string, title: string) {
if (!title.trim()) {
@@ -383,9 +381,8 @@ export default class BoardApi {
}
/**
- * Puts the inbox column away, which is a matter of the board's own setting rather than of the
- * column: the stored entry stays where it is, so its icon, colour and place are waiting when it
- * is switched back on.
+ * Hides the inbox column by turning off the board's setting. The stored entry is kept, so
+ * its icon, colour and position are restored when it is switched back on.
*/
async disableInbox() {
await attributes.setBooleanWithInheritance(this.parentNote, "enableInboxColumn", false);
@@ -401,7 +398,7 @@ export default class BoardApi {
await this.updateColumn(column, { limit });
}
- /** Whether the inbox reaches past the board's own children, down to the children of cards. */
+ /** Whether the inbox also collects notes deeper than the board's direct children. */
async setInboxNested(nested: boolean) {
await this.updateColumn(INBOX_COLUMN, { nested });
}
@@ -458,12 +455,12 @@ export default class BoardApi {
newColumns.splice(adjustedToIndex, 0, movedColumn);
- // `columns` is derived render state and carries neither what it has yet to catch up with
- // nor what the board is not showing, an inbox switched off among it. Each of those keeps
- // the place it holds in the config rather than being herded to the end or dropped.
+ // `columns` is render state: it omits entries the view has yet to catch up with, and any
+ // the board is hiding, such as a disabled inbox. Each keeps its index in the config
+ // instead of being appended at the end or dropped.
const stored = this.viewConfig?.columns ?? [];
const storedColumns = new Map(stored.map(col => [ col.value, col ]));
- // Reordering moves the entries, so each keeps the icon it holds rather than being rebuilt
+ // Reordering only moves entries, so each keeps its stored icon instead of being rebuilt
// from its name.
const reordered: BoardColumnData[] =
newColumns.map(value => storedColumns.get(value) ?? { value });
@@ -605,7 +602,7 @@ export default class BoardApi {
return;
}
- // The definition lists the values a card can carry, and the inbox stands for carrying none.
+ // The definition lists the values a card can carry; the inbox has no value.
columns = columns.filter(column => column !== INBOX_COLUMN);
// A board showing nothing has no column list to describe and must not gain an empty
@@ -708,7 +705,7 @@ export default class BoardApi {
await branches.moveAfterBranch([ branch.branchId ], branchId);
}
- /** Whether the value the card is grouped by stands on another note: a template or a parent. */
+ /** Whether the grouping value comes from another note, such as a template or a parent. */
private isInherited(note: FNote, type: "label" | "relation") {
return note.getAttributes(type, this.statusAttribute)
.some(attribute => attribute.noteId !== note.noteId);
@@ -718,9 +715,8 @@ export default class BoardApi {
const note = froca.getNoteFromCache(noteId);
if (!note) return;
if (this.isRelationMode) {
- // A relation points at a note, so there is no empty one to cover an inherited value
- // with the way a label is covered below. Where the card takes its column from a
- // template or an ancestor, that is the only place it can be changed.
+ // A relation must point at a note, so an inherited one cannot be shadowed the way a
+ // label is below. It can only be changed on the note that defines it.
if (!note.getOwnedAttributes("relation", this.statusAttribute).length
&& this.isInherited(note, "relation")) {
toast.showMessage(t("board_view.inherited-column"), 3000);
@@ -730,9 +726,8 @@ export default class BoardApi {
return attributes.removeOwnedRelationByName(note, this.statusAttribute);
}
- // A value the card takes from a template or an ancestor is not the card's to remove, and
- // taking away the one it owns would only uncover what that was covering. An empty value of
- // its own covers it instead, which reads as carrying none.
+ // An inherited value cannot be removed from the card, and removing the owned one would
+ // only uncover it. An owned empty value shadows it instead, which counts as no value.
if (this.isInherited(note, "label")) {
return attributes.setLabel(noteId, this.statusAttribute, "");
}
diff --git a/apps/client/src/widgets/collections/board/column.tsx b/apps/client/src/widgets/collections/board/column.tsx
index 22b86dff68..bdd539877a 100644
--- a/apps/client/src/widgets/collections/board/column.tsx
+++ b/apps/client/src/widgets/collections/board/column.tsx
@@ -57,7 +57,7 @@ export default function Column({
color?: string,
/** Whether the column is archived. Only ever rendered while archived notes are shown. */
archived?: boolean,
- /** Whether the inbox reaches past the board's own children. Meaningless on any other column. */
+ /** Whether the inbox also collects notes deeper than the board's direct children. */
nested?: boolean,
/** The note limit, absent if disabled. */
limit?: number,
@@ -223,8 +223,8 @@ export default function Column({
currentValue={api.getColumnTitle(column)}
save={newTitle => api.setColumnTitle(column, newTitle)}
dismiss={() => setColumnNameToEdit(undefined)}
- // The inbox is named in words even on a board grouped by a relation, where
- // every other column is named by the note it stands for.
+ // The inbox is renamed as text even on a relation board, where every
+ // other column is renamed by picking a note.
mode={isInRelationMode && column !== INBOX_COLUMN ? "relation" : "normal"}
/>
)}
@@ -275,15 +275,15 @@ export default function Column({
* state is the column's rather than this component's, since the menu is raised from the header.
*/
/**
- * How many cards a column holds, and what they are when hovered.
+ * How many cards a column holds, with a breakdown on hover.
*
- * The archived ones are among them only while the board is showing archived notes; where it is not,
- * there are none to count and the badge says how many cards there are and no more.
+ * Archived cards are only included while the board is showing archived notes. Otherwise there are
+ * none to count and the badge reports the total alone.
*/
function CountBadge({ items, limit, isOver }: {
items?: { note: FNote }[],
limit?: number,
- /** Whether the column is over its limit. The column body shows this too. */
+ /** Whether the column is over its limit. The column body is outlined as well. */
isOver?: boolean
}) {
const badgeRef = useRef<HTMLSpanElement>(null);
diff --git a/apps/client/src/widgets/collections/board/column_limit.tsx b/apps/client/src/widgets/collections/board/column_limit.tsx
index 92a523fb12..f1805d79aa 100644
--- a/apps/client/src/widgets/collections/board/column_limit.tsx
+++ b/apps/client/src/widgets/collections/board/column_limit.tsx
@@ -51,7 +51,11 @@ export default function ColumnLimitDialog({ api, column, onClose }: {
onHidden={onClose}
footer={<>
<Button text={t("modal.cancel")} onClick={onClose} />
- <Button text={t("board_view.set-limit-ok")} keyboardShortcut="Enter" kind="primary" />
+ <Button
+ text={t("board_view.set-limit-ok")}
+ keyboardShortcut="Enter"
+ kind="primary"
+ />
</>}
>
<div className="board-column-limit-fields">
diff --git a/apps/client/src/widgets/collections/board/columns.ts b/apps/client/src/widgets/collections/board/columns.ts
index 0f94f440d0..2b2b7d2c65 100644
--- a/apps/client/src/widgets/collections/board/columns.ts
+++ b/apps/client/src/widgets/collections/board/columns.ts
@@ -18,15 +18,15 @@ export const DEFAULT_GROUP_BY = "status";
export const DEFAULT_COLUMN_ICON = "bx bx-circle";
/**
- * The value the inbox column is known by: the one a card carries when it carries none.
+ * The value identifying the inbox column: the empty string, which is what a card with no
+ * grouping value has.
*
- * A column is its grouping value everywhere on the board, and what the inbox gathers is the notes
- * with no value at all, so the empty string is the value it stands for. It is told apart from a
- * column being deleted, which is recorded as `undefined` rather than as an empty name.
+ * Columns are identified by their grouping value throughout the board, and the inbox collects the
+ * cards that have none. A deleted column is recorded as `undefined`, which is distinct from this.
*/
export const INBOX_COLUMN = "";
-/** What the inbox column wears until one is picked for it, in place of the stock column icon. */
+/** Default icon for the inbox column, used instead of the standard one until another is picked. */
export const INBOX_COLUMN_ICON = "bx bxs-inbox";
export interface BoardStatusDefinition {
@@ -85,7 +85,7 @@ export function getStatusDefinition(parentNote: FNote, groupBy: string): BoardSt
* Having none at all is the ordinary case for a board created now, and the answer is yes: the
* definition the board writes is its own from the start.
*/
-/** Whether a value names a column of its own, as against standing for the notes carrying none. */
+/** Whether a value identifies a column of its own, rather than the absence of one. */
function named(value: string) {
return value.trim() !== INBOX_COLUMN;
}
@@ -143,7 +143,7 @@ export function resolveBoardColumns(
for (const candidate of candidates) {
const trimmed = candidate.trim();
const value = pendingRenames.has(trimmed) ? pendingRenames.get(trimmed) : trimmed;
- // `undefined` is a column being deleted, which is not the same as the inbox's own name.
+ // `undefined` means a column is being deleted, which is not the inbox value.
if (value === undefined || seen.has(value)) continue;
seen.add(value);
columns.push(value);
@@ -152,9 +152,9 @@ export function resolveBoardColumns(
return columns;
};
- // The board's own list is the only source that can bring the inbox: a note carrying no value is
- // what the inbox gathers rather than a column to make, and a definition written with a gap in
- // it (`options=To Do;;Done`) names nothing.
+ // Only the board's own list can introduce the inbox: an unassigned note is what the inbox
+ // collects rather than a column to create, and a definition with a gap in it
+ // (`options=To Do;;Done`) defines nothing.
const columns = resolve([
...definitionOptions.filter(named),
...persistedColumns,
diff --git a/apps/client/src/widgets/collections/board/context_menu.ts b/apps/client/src/widgets/collections/board/context_menu.ts
index 6ddd02ddb8..89ba359bd7 100644
--- a/apps/client/src/widgets/collections/board/context_menu.ts
+++ b/apps/client/src/widgets/collections/board/context_menu.ts
@@ -23,7 +23,7 @@ interface ColumnMenuTarget {
index: number;
color?: string;
archived?: boolean;
- /** Whether the inbox reaches past the board's own children. Meaningless on any other column. */
+ /** Whether the inbox also collects notes deeper than the board's direct children. */
nested?: boolean;
/** Puts the title into its inline editor, the menu being the only way there besides F2. */
onEditTitle: () => void;
@@ -33,7 +33,7 @@ interface ColumnMenuTarget {
onAddColumn: (direction: "before" | "after") => void;
/** Moves this column to sit before the given position among the columns as drawn. */
onMoveColumn: (toIndex: number) => void;
- /** Asks how many cards the column is meant to hold. */
+ /** Opens the dialog that sets the column's note limit. */
onSetLimit: () => void;
}
diff --git a/apps/client/src/widgets/collections/board/data.ts b/apps/client/src/widgets/collections/board/data.ts
index 3a9446085e..14b88c9dcf 100644
--- a/apps/client/src/widgets/collections/board/data.ts
+++ b/apps/client/src/widgets/collections/board/data.ts
@@ -23,20 +23,20 @@ export async function getBoardData(
includeArchived: boolean,
definitionOptions: string[] = [],
pendingRenames: ReadonlyMap<string, string | undefined> = new Map(),
- /** Whether the board is set to keep an inbox, which is what decides if one gathers anything. */
+ /** Whether the board keeps an inbox, which decides whether unassigned notes are collected. */
inboxEnabled = false
) {
const byColumn: ColumnMap = new Map();
const storedColumnValues = (persistedData.columns ?? []).map(c => c.value);
- // Switching the inbox on is what puts it on the board, at the head of it. From then on the
- // entry is the board's own: it keeps whatever icon, colour and place it is given, and switching
- // the inbox off leaves it there rather than taking it away.
+ // Turning the inbox on adds it to the board, at the front. After that the entry belongs to
+ // the config: it keeps its icon, colour and position, and turning the inbox off leaves it in
+ // place.
const persistedColumns = inboxEnabled && !storedColumnValues.includes(INBOX_COLUMN)
? [ INBOX_COLUMN, ...storedColumnValues ]
: storedColumnValues;
- // Only a board that keeps an inbox has anywhere to put a note carrying no value; on any other
- // one such a note is not on the board at all, as it has always been.
+ // Only a board with an inbox has somewhere to put an unassigned note; on any other board such
+ // a note is not shown at all, as before.
const inbox = inboxEnabled
? { nested: !!persistedData.columns?.find(col => col.value === INBOX_COLUMN)?.nested }
: undefined;
@@ -127,8 +127,8 @@ function regroupRenamedCards(
}
/**
- * @param inbox where the board keeps the notes carrying no value, absent where it keeps none.
- * @param depth how far below the board the branches stand, the board's own children being 0.
+ * @param inbox where unassigned notes are collected, absent if the board has no inbox.
+ * @param depth how deep below the board the branches are, the board's own children being 0.
*/
async function recursiveGroupBy(
branches: FBranch[], byColumn: ColumnMap, groupByColumn: string, includeArchived: boolean,
@@ -144,9 +144,8 @@ async function recursiveGroupBy(
seenNoteIds, inbox, depth + 1);
}
- // A note carrying no value goes to the inbox, where the board keeps one and is set to reach
- // this far down. Anything deeper than the board's own children is a card's child, which the
- // inbox gathers only when it is told to.
+ // A note with no value goes to the inbox, if the board has one and reaches this deep.
+ // Anything below the board's own children is a card's child, collected only when nested.
const value = note.getLabelOrRelation(groupByColumn);
const group = value || (inbox && (depth === 0 || inbox.nested) ? INBOX_COLUMN : undefined);
if (group === undefined || seenNoteIds.has(note.noteId)) {
diff --git a/apps/client/src/widgets/collections/board/index.tsx b/apps/client/src/widgets/collections/board/index.tsx
index b33f359e93..468e0ded54 100644
--- a/apps/client/src/widgets/collections/board/index.tsx
+++ b/apps/client/src/widgets/collections/board/index.tsx
@@ -43,13 +43,13 @@ export interface BoardColumnData {
/** Whether the column is archived, absent while it is not. */
archived?: boolean;
/**
- * Whether the inbox column gathers notes below the board's own children as well. Meaningless on
- * any other column, which stands for a value a note carries wherever it stands.
+ * Whether the inbox column also collects notes below the board's direct children. Has no
+ * meaning on any other column, which is defined by a grouping value instead.
*/
nested?: boolean;
/**
- * What the column is called, for one that is not named by the value its cards carry. Renaming
- * any other column writes the value itself, so it needs none.
+ * The column's display name, used only by columns that are not identified by a grouping
+ * value. Renaming any other column writes the value itself, so it needs none.
*/
displayName?: string;
/** The note limit, absent if disabled. */
@@ -215,9 +215,9 @@ export default function BoardView({ note: parentNote, noteIds, viewConfig, saveC
};
refreshSeqRef.current++;
}
- // Resolution keeps the inbox on the strength of the config alone, so its icon, colour and place
- // survive the toggle being off; what the toggle decides is whether the board shows it and
- // offers it. Rewriting the attachment without it would be what loses those settings.
+ // The inbox is resolved from the config alone, so its icon, colour and position survive the
+ // toggle being off. The toggle only decides whether the board shows and offers it: dropping it
+ // during resolution would rewrite the attachment without it and lose those settings.
const usableColumns = useMemo(
() => (columns ?? []).filter(column => column !== INBOX_COLUMN || inboxEnabled),
[ columns, inboxEnabled ]);
@@ -323,8 +323,8 @@ export default function BoardView({ note: parentNote, noteIds, viewConfig, saveC
// landed among them all once some are archived and hidden. Translated here so a reorder leaves
// every hidden column where it was rather than herding them to the end.
const handleColumnDrop = useCallback((fromIndex: number, toIndex: number) => {
- // The list the api holds, which is the one it reorders: a column the board is not showing
- // at all is in neither, so counting in `columns` would leave the two a place apart.
+ // The list the api holds, which is also the one it reorders. A column the board is not
+ // showing is in neither, so indexing into `columns` would be off by one.
const allColumns = api.columns;
const dropBefore = shownColumns[toIndex];
const newColumns = api.reorderColumn(
diff --git a/apps/client/src/widgets/react/FormList.tsx b/apps/client/src/widgets/react/FormList.tsx
index 15f02c1040..4608e045c3 100644
--- a/apps/client/src/widgets/react/FormList.tsx
+++ b/apps/client/src/widgets/react/FormList.tsx
@@ -174,7 +174,7 @@ export function FormListToggleableItem({
title: string;
currentValue: boolean;
helpPage?: string;
- /** What the setting does, shown on hover. Unlike {@link helpPage} it opens nothing. */
+ /** What the setting does, shown on hover. Unlike {@link helpPage}, it opens nothing. */
helpTooltip?: string;
onChange(newValue: boolean): void | Promise<void>;
}) {
diff --git a/apps/client/src/widgets/react/NotePropertyMenu.tsx b/apps/client/src/widgets/react/NotePropertyMenu.tsx
index f36380a141..7b31152deb 100644
--- a/apps/client/src/widgets/react/NotePropertyMenu.tsx
+++ b/apps/client/src/widgets/react/NotePropertyMenu.tsx
@@ -16,7 +16,7 @@ export interface ClickContext {
triggerCommand: NoteContextAwareWidget["triggerCommand"];
}
-/** Carried by a property of any kind, for one whose label does not say enough on its own. */
+/** Available on a property of any kind, for one whose label needs explaining. */
export interface PropertyHelp {
/** What the property does, shown on hover beside its label. */
helpTooltip?: string;
@@ -114,7 +114,7 @@ export function isPropertyVisible(property: BookProperty, note: FNote): boolean
return !("isVisible" in property) || (property.isVisible?.(note) ?? true);
}
-/** A property's label, and beside it the explanation the property carries, where it carries one. */
+/** A property's label, followed by its explanation when it has one. */
function PropertyLabel({ property }: { property: BookProperty & { label: string } }) {
return (
<>