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: update comments
Adorian Doranadcfeedbe989
diff --git a/apps/client/src/widgets/collections/board/api.ts b/apps/client/src/widgets/collections/board/api.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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.tsxindex 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): booleanreturn !("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 (<>