# Waypoint Sidebar — Technical Documentation > Obsidian plugin (id: `waypoint-sidebar`) providing a unified sidebar with calendar, recent files, and custom bookmarks. Replaces separate Calendar and Bookmarks core plugins. --- ## Architecture Overview ``` src/ ├── main.ts Plugin entry — lifecycle, commands, events, data persistence ├── settings.ts Interface definitions + DEFAULT_SETTINGS / DEFAULT_DATE_SYSTEM constants ├── settings-tab.ts PluginSettingTab UI — calendar, periodic, date systems, recent, display, about ├── models/ │ └── bookmark.ts BookmarkItem + WaypointData interfaces ├── utils/ │ ├── date-utils.ts Moment.js helpers: period formatting, month grid, navigation │ ├── date-systems.ts Pure date-system filename helpers (no `obsidian` import, unit-testable) │ └── path-utils.ts Pure path helper: rename remapping (no `obsidian` import, unit-testable) └── views/ └── waypoint-view.ts ItemView subclass — full sidebar rendering + interaction ``` **Build:** `npm run build` runs `tsc --noEmit` first, then esbuild bundles `src/main.ts` → `main.js`. The typecheck is a real gate — esbuild strips types without checking them, so without it type errors would ship. `npm run typecheck` runs the check alone; `npm run dev` (watch) stays ungated for speed. TypeScript strict-null + `noImplicitAny`, ESNext modules, ES6 target, `lib` floor at ES2017. **Data persistence:** Single `data.json` via Obsidian `Plugin.loadData()/saveData()`. Top-level keys: `settings` (merged with `DEFAULT_SETTINGS`), `waypointData` (bookmark tree **and** recent files). Recent files are persisted under `waypointData.recentFiles` and reloaded on startup; writes are debounced 300ms so rapid file opens collapse into one save. --- ## Plugin Lifecycle ### `onload()` 1. **Load data** — reads `data.json` exactly once, then `applySettings(saved)` and `applyWaypointData(saved)` merge its partial data over defaults. 2. **Register view** — `WAYPOINT_VIEW_TYPE = "waypoint-view"` maps to `WaypointView` factory `(leaf) => new WaypointView(leaf, this)`. 3. **Settings tab** — `WaypointSettingTab` receives the live `settings` object + `() => this.redrawAll()` callback for live preview. 4. **Register commands** (see Commands section below). 5. **Register events** — `file-open`, `vault:create`, `vault:delete`, `vault:rename`, `vault:modify`. 6. **Auto-open** — On `onLayoutReady`, if no existing leaves of the view type, opens one in the left sidebar. 7. **Midnight refresh** — 10-minute `setInterval` checks if `new Date().toDateString()` changed; if so, calls `redrawAll()` (calendar day indicators refresh). ### `onunload()` Detaches all leaves of `WAYPOINT_VIEW_TYPE`. --- ## Data Models ### WaypointSettings ```typescript interface WaypointSettings { calendar: CalendarSettings; // week start, indicator visibility/style, daily indicator colour daily: PeriodNoteSettings; weekly: PeriodNoteSettings; monthly: PeriodNoteSettings; quarterly: PeriodNoteSettings; yearly: PeriodNoteSettings; dateSystems: DateSystemSettings[]; // day-scoped systems beyond the daily note, in menu order recentFiles: RecentFilesSettings; // maxItems, updateOn, omittedPaths[], omittedTags[], filterTags[] display: DisplaySettings; // px sizing for bookmark rows, fonts, icons, calendar cells } interface PeriodNoteSettings { folder: string; // e.g. "periodic/daily" templateFile: string; // path without .md, e.g. "Templates/Daily note" nameFormat: string; // moment.js format string typeProperty: string; // frontmatter type value, e.g. "daily-note" } interface CalendarSettings { firstDayOfWeek: number; // 0 = Sunday, 1 = Monday showNoteIndicators: boolean; // show or hide all calendar markers indicatorMode: 'any' | 'systems'; // defaults to systems; one neutral dot or one per date system dailyIndicatorColor: string; // daily's colour in systems mode } interface RecentFilesSettings { maxItems: number; // default 50 updateOn: 'file-open' | 'file-edit'; // trigger mode omittedPaths: string[]; // regex patterns (one per line) omittedTags: string[]; // regex patterns for frontmatter/inline tags filterTags: string[]; // tags shown as filter pills (empty = auto-detect from frontmatter) } interface DisplaySettings { rowSize: number; // px, base height of bookmark items (18–40) rowSpacing: number; // px, gap between items (0–12) indentSize: number; // px, indent per depth level (8–32) fontSize: number; // px, font size for bookmark labels (10–18) iconSize: number; // px, icon size (12–24) calendarCellSize: number; // px, calendar day cell height (20–48) } ``` `dateSystems` holds the user's configured date systems in menu order — see the Date Systems section for the `DateSystemSettings` shape and the two systems shipped by default. ### BookmarkItem (recursive tree) ```typescript interface BookmarkItem { id: string; // "bm-{timestamp}-{random4}" type: 'file' | 'group' | 'separator' | 'spacer'; label: string; // display text (empty for separator/spacer) filePath: string; // vault-relative path (empty for non-file types) icon: string; // Lucide icon name children: BookmarkItem[]; // nested items (groups contain children) collapsed: boolean; // group collapse state indent: number; // depth level (0 = root) } interface WaypointData { bookmarks: BookmarkItem[]; recentFiles: { path: string; basename: string }[]; } ``` The bookmark tree is stored under `waypointData.bookmarks` and rendered recursively. Groups contain children; files/separators/spacers are leaf nodes. `waypointData.recentFiles` holds the persisted recent-files list (mirrored into the live `plugin.recentFiles` array on load). --- ## Commands ### Period note navigation (with default hotkeys) | ID | Name | Hotkey | |---|---|---| | `waypoint-go-to-daily` | Go to daily note | `Mod+Shift+Alt+D` | | `waypoint-go-to-weekly` | Go to weekly note | `Mod+Shift+Alt+W` | | `waypoint-go-to-monthly` | Go to monthly note | `Mod+Shift+Alt+M` | | `waypoint-go-to-quarterly` | Go to quarterly note | `Mod+Shift+Alt+Q` | | `waypoint-go-to-yearly` | Go to yearly note | `Mod+Shift+Alt+Y` | All call `openPeriodNote(period, moment())` — opens or creates the current period's note. ### Next/Previous period (no default hotkeys) 10 commands generated in a loop: `waypoint-go-to-{next|prev}-{daily|weekly|monthly|quarterly|yearly}`. These call `navigatePeriodNote(direction)` which: 1. Gets the active file's basename. 2. Calls `detectPeriodType(basename)` — **settings-driven**, not hardcoded regexes. It reads `settings.{daily,weekly,monthly,quarterly,yearly}.nameFormat` and tries `moment(basename, nameFormat, true).isValid()` (strict parsing) in order day → week → month → quarter → year, returning the first match as `{ period, date }`. Periods with an empty `nameFormat` are skipped; returns `null` if nothing matches. Changing a name format in settings therefore keeps next/prev navigation working. 3. Adds ±1 period (quarters add ±3 months). 4. Calls `openPeriodNote` for the new date. ### Other commands | ID | Name | |---|---| | `waypoint-open-view` | Open Waypoint sidebar | | `waypoint-add-bookmark` | Add current file as Waypoint bookmark | --- ## Date Systems A **date system** is a folder of notes whose filenames begin with a date. Daily notes, a journal and meeting notes are all the same shape, so they share one settings model, one discovery pass and one creation path. ### `DateSystemSettings` interface DateSystemSettings { id: string; // stable across edits + reordering, so settings rows can key on it name: string; // menu label, e.g. "Journal" folder: string; // e.g. "periodic/journal" nameFormat: string; // moment format string; may contain "{title}" templateFile: string; // may omit the .md extension typeProperty: string; // fallback frontmatter `type:` value icon: string; // Lucide icon name for the menu item indicatorColor: string; // calendar dot colour in systems mode } ``` Configured systems live in `settings.dateSystems`, where array order is menu order. `DEFAULT_DATE_SYSTEM` (in `settings.ts`, typed `Omit`) supplies the field defaults for a newly added row **and** the merge base for saved ones, so a system persisted before a field existed still loads with that field defined. `DEFAULT_SETTINGS.dateSystems` ships two: | `id` | `name` | Folder | `nameFormat` | Indicator colour | Notes per date | |---|---|---|---|---|---| | `journal` | Journal | `periodic/journal` | `YYYY-MM-DD - [Journal]` | green (`#22c55e`) | one | | `meetings` | Meeting | `periodic/meetings` | `YYYY-MM-DD - {title}` | violet (`#a855f7`) | many | The default calendar mode is `systems`, while `any` preserves the older one-neutral-dot behaviour. Template file fields in both Periodic Notes and Date systems use a native `datalist` populated from every Markdown path in the vault (without the optional `.md` extension), so templates stored outside a conventional `Templates/` folder remain discoverable. ### Templater folder triggers Waypoint deliberately does not evaluate Templater syntax. For an interactive Templater template, configure Templater's **Trigger Templater on new file creation** mode for the relevant folder, then leave that date system's `templateFile` blank in Waypoint. Waypoint creates a safe fallback note from `typeProperty` and the selected `YYYY-MM-DD` date; Templater's folder trigger owns the rendered content, prompts, scripts, and cursor placement. The target filename is the contract between them. A calendar-created journal note is already named `YYYY-MM-DD - Journal`; a meeting is already `YYYY-MM-DD - {title}`. Templates must extract the date from `tp.file.title`, not `tp.date` or `tp.file.creation_date()`, because those refer to when Templater runs rather than the date selected in the calendar. The journal template may retain a manual fallback: only prompt for a date and rename when `tp.file.title` does **not** match the date-system filename. That preserves manual note creation without a prompt or rename race on calendar creation. ### The `{title}` convention `nameFormat` is a moment format string, so literal text needs bracket escaping — `YYYY-MM-DD - [Journal]` — the same convention the periodic formats `GGGG-[W]WW` and `YYYY-[Q]Q` already use. When the format contains `{title}`, the system holds **many** notes per date: the text before the token is the date prefix used to discover them, and the token marks where a typed free-text title goes on creation. Without the token, a date maps to **exactly one** filename. **Why the token is split out before moment sees the string:** `t`, `i`, `l` and `e` are all live moment format tokens — `l` on its own expands to an entire localized date. Passing `{title}` through `date.format()` would expand those letters and destroy the placeholder, with no way to recover it afterwards. `splitNameFormat()` therefore cuts the format at the token *first*, and callers format `before` and `after` separately, then join the two results around the title. It is also why discovery matches on formatted affixes instead of on a regex derived from the raw format. ### Helpers (`src/utils/date-systems.ts`) Imports nothing from `'obsidian'` — callers make every moment call and pass the resulting strings in, which keeps the module unit-testable in plain node (same rationale as `path-utils.ts`). | Export | Signature | Purpose | |---|---|---| | `TITLE_TOKEN` | `'{title}'` | The literal placeholder. | | `splitNameFormat(nameFormat)` | `string → NameFormatParts` | `{ before, after, hasTitle }` — the format cut around the token. | | `isInFolder(path, folder)` | `string, string → boolean` | Path sits in `folder` or any subfolder. An empty folder means the vault root, so everything matches. | | `matchesSystemName(basename, before, after, hasTitle)` | `string, string, string, boolean → boolean` | One-per-date: the basename must equal `before + after`. Many-per-date: prefix/suffix match, since the middle is free text. | | `titleFromBasename(basename, before, after)` | `string, string, string → string` | Strips the affixes to recover the menu label; falls back to the whole basename when they do not line up. | | `sanitizeTitle(title)` | `string → string` | Collapses filename-illegal and link-syntax characters (`\ / : * ? " < > \| # ^ [ ]`) to `-`, squeezes runs of whitespace, trims — so a typed "Meeting w/ Mark" still yields a creatable filename. | | `formatHasDateToken(nameFormat)` | `string → boolean` | Strips bracket-escaped literals out of `before`, then looks for any moment date token. Drives the settings warning. | `matchesSystemName` deliberately returns `false` for a many-per-date format whose `before` is empty (a format of just `{title}`): an empty date prefix would otherwise claim every file in the folder for every date. The settings tab flags formats with no date token, and `findDateSystemNotes()` excludes them from the menu; `openDateSystemNote()` also refuses them. An unfinished or invalid row therefore cannot create `.md` or a static filename. ### Plugin API (`main.ts`) ```typescript interface DateSystemNote { file: TFile; label: string; // free-text title for many-per-date systems, else the system name } interface DateSystemNotes { system: DateSystemSettings; notes: DateSystemNote[]; multiple: boolean; // nameFormat carries {title} } interface DateSystemIndicator { id: string; name: string; color: string; } dateSystems(): DateSystemSettings[] findDateSystemNotes(date: moment.Moment): DateSystemNotes[] getDateSystemIndicators(dates: moment.Moment[]): Map openDateSystemNote( system: DateSystemSettings, date: moment.Moment, opts?: { title?: string; leaf?: WorkspaceLeaf }, ): Promise ``` **`getDateSystemIndicators(dates)`** — returns one `{ id, name, color }` marker per configured system with one or more notes on a requested day. The calendar calls it once for the visible month only in `indicatorMode: 'systems'`. It makes one vault pass, caches the result by displayed dates and date-system settings, and invalidates it on markdown create/delete/rename or any Settings change. It does not run on ordinary markdown edits: content edits cannot change a filename-derived indicator. **`dateSystems()`** — every day-scoped system in menu order: the daily periodic note, synthesized into a `DateSystemSettings` from `settings.daily`, followed by `settings.dateSystems`. The daily note is therefore not a special case in any consumer. **`findDateSystemNotes(date)`** — **one** vault scan per call, not one per system. It formats each usable system's `before`/`after` affixes for `date` once, then walks the markdown file list a single time, bucketing each file into the system that claims it (`isInFolder` + `matchesSystemName`). Systems whose formats have no date token are omitted rather than offering an unsafe create action. It returns the remaining `DateSystemNotes` in `dateSystems()` order, each bucket sorted by basename. The calendar's day context menu is built from exactly one of these calls per right-click. **`openDateSystemNote(system, date, opts)`** — the single opener for every dated note: 1. **Filename** — `splitNameFormat(system.nameFormat)`, format `before` and `after` against `date`, and for a many-per-date system join `sanitizeTitle(opts.title)` between them. Append `.md`; prepend `system.folder` when it is set. 2. **Existing note** — a `vault.getFileByPath()` hit is opened as-is, never overwritten. A date that already has notes can still gain another in a many-per-date system, because the title makes the filename unique. 3. **Missing note** — created via `createDatedNote`, then opened. 4. **Leaf** — `opts.leaf` when supplied (middle-click and Ctrl/Cmd-click pass an explicit tab leaf), otherwise `workspace.getLeaf(false)`. ### Note creation (`createDatedNote`) A single creation path shared by periodic notes and date systems; it replaced the period-only `createPeriodNote`. 1. With a non-empty `system.templateFile`, reads it (appending `.md` when omitted) and creates the note with its raw contents. This is for plain, non-Templater templates. 2. With no template, the note is created with minimal frontmatter instead: `type: {system.typeProperty}` + `date: YYYY-MM-DD`. Use this mode with a Templater folder trigger, which replaces that fallback content with its rendered template. --- ## Period Note Creation (`openPeriodNote`) ```typescript openPeriodNote( period: 'day' | 'week' | 'month' | 'quarter' | 'year', date: moment.Moment, leaf?: WorkspaceLeaf, ): Promise ``` Single unified opener — there is no separate `openPeriodNoteInLeaf`, and since the date-systems refactor there is no separate creation path either. `openPeriodNote` synthesizes the period's `PeriodNoteSettings` into a `DateSystemSettings` (`folder`, `nameFormat`, `templateFile` and `typeProperty` carry over verbatim; a period format never contains `{title}`, so a period maps to exactly one filename) and delegates to `openDateSystemNote(system, date, { leaf })`. Filename building, the existence check, template-or-frontmatter creation and leaf selection are therefore documented once, under Date Systems above. Middle-click handlers in the view pass an explicit tab leaf: `openPeriodNote(period, date, this.app.workspace.getLeaf('tab'))`. --- ## Event Handling ### `file-open` Tracks the opened file into recent files **only** when `settings.recentFiles.updateOn === 'file-open'`. ### `vault:modify` Tracks the modified file (guarded to `TFile`) into recent files **only** when `updateOn === 'file-edit'`. Exactly one of the two modes is active at a time, so `'file-edit'` is a working mode rather than a no-op. ### `vault:create` / `vault:delete` Both update the markdown-basename set used for calendar note indicators, then trigger `broadcastRedraw()` — telling all WaypointView instances to re-render (needed for the indicators and for stale recent file references). ### `vault:rename` 1. Updates the markdown-basename set (old basename out, new basename in). 2. Remaps the `recentFiles` entry through `remapRenamedPath(entry.path, oldPath, newPath)`. 3. Remaps every bookmark `filePath` through the same helper. `remapRenamedPath(path, oldPath, newPath)` (in `src/utils/path-utils.ts`) returns the updated path when `path` **is** `oldPath` (a plain file rename) *or* is nested under it (`path.startsWith(oldPath + '/')`, i.e. a folder rename/move), and `null` when the path is unaffected. This is why moving a folder no longer orphans the bookmarks inside it. The helper deliberately imports nothing from `'obsidian'` so it stays pure and unit-testable in plain node. --- ## Recent Files (persisted) ```typescript recentFiles: { path: string; basename: string }[] ``` Backed by `waypointData.recentFiles` in `data.json`, so the list survives vault reload. `applyWaypointData(saved)` restores it and re-applies the current `maxItems` limit (in case the setting shrank since the last save). **Update flow:** 1. `addToRecentFiles(file)` — omission check, then dedupes (removes existing entry), prepends to front, truncates to `maxItems`. 2. `persistRecentFiles()` — mirrors the array into `waypointData.recentFiles` and schedules a debounced (300ms) `saveWaypointData()`. 3. Calls `broadcastRedraw()`. **Omitted paths/tags:** Both filters are applied in `addToRecentFiles`. `omittedPaths` entries are treated as regexes tested against `file.path`; `omittedTags` entries are regexes tested against the file's tags, read via `getAllTags(metadataCache.getFileCache(file))` with the leading `#` stripped. An invalid regex is skipped rather than throwing. **`enforceRecentFilesLimit()`:** Called from the settings-change callback — trims the list when `maxItems` is lowered and persists the result. **On file not found:** When clicking a recent file that no longer exists, `focusFile()` shows a Notice and removes the stale entry from `recentFiles`. --- ## Sidebar View (`WaypointView`) Extends `ItemView`. View type: `"waypoint-view"`, icon: `compass`. ### Rendering (`redraw`) Called on every change. Full DOM rebuild — `contentEl.empty()` then three sections in order: 1. **Favorites** (`renderFavorites`) — bookmark tree 2. **Recent Files** (`renderRecentFiles`) — flat list 3. **Calendar** (`renderCalendar`) — month grid The last section (`waypoint-section:last-child`) gets `margin-top: auto`, pushing it to the bottom of the sidebar. ### Calendar Panel **State:** `currentDisplayMonth` (0-indexed), `currentDisplayYear` — allows navigating months independently of today. **Layout:** ``` ┌────────────────────────────────────┐ │ Q2 June 2026 ◀ Today ▶ │ ← breadcrumb (clickable) + nav ├──┬───┬───┬───┬───┬───┬───┬───┤ │24│sun│mon│tue│wed│thu│fri│sat│ ← header row + week# col ├──┼───┼───┼───┼───┼───┼───┼───┤ │25│ 1 │ 2 │ 3 │... ← day cells (clickable) └──┴───┴───┴───┴───┴───┴───┴───┘ ``` - **Breadcrumb:** Q-label, month name, year — each clickable to open that period note. - **Nav buttons:** ◀/▶ shift month ±1. "Today" resets to current month. - **Week number column:** Clicking a week number opens the weekly note for that week's Monday; middle-clicking opens it in a new tab. - **Day cells:** Left-click opens the daily note, middle-click opens it in a new tab, right-click opens the day context menu (below). `.other-month` is muted; `.today` has an inset accent ring; hover receives a quiet fill. With `indicatorMode: 'any'`, `.has-note` shows the existing single neutral dot through the O(1) `plugin.hasNoteForDate(dateStr)` lookup. With `indicatorMode: 'systems'`, the view calls `getDateSystemIndicators()` once for the month and renders one tooltip-labelled coloured dot per matching daily/journal/meeting/custom system. - **Grid generation:** `getMonthGrid(year, month, firstDayOfWeek)` in `date-utils.ts` produces up to 6 weeks, each with 7 `CalendarDay` objects containing `moment`, `dayOfMonth`, `isToday`, `isCurrentMonth`, `isoWeekNumber`. **Day context menu (right-click):** Built from a single `plugin.findDateSystemNotes(day.date)` call. The first entry is a non-clickable header showing the full date. Then, per system in `dateSystems()` order: - Each existing note, labelled with its `DateSystemNote.label` and the system's `icon`. Click opens it in the current leaf; Ctrl/Cmd-click opens it in a new tab. - A create entry (icon `plus`) labelled `New {lowercased system name} note`. Many-per-date systems always show one, with a trailing ellipsis because it first opens a `PromptModal` for the title (`New meeting note…`). A one-per-date system shows one without the ellipsis only while its note is missing (`New journal note`); once the note exists, the existing-note entry is all it gets. Every label is derived from `system.name`, so a renamed or newly added system needs no view changes. Left-click and middle-click on the cell are untouched. ### Recent Files Panel Renders `plugin.recentFiles` as Obsidian-native `nav-file` elements using the file explorer's CSS classes (`tree-item`, `nav-file-title`, `nav-file-title-content`). **Per-file features:** - **Active indicator:** `.is-active` class if path matches `workspace.getActiveFile()`. - **Remove button:** × icon, appears on hover (`.waypoint-recent-remove`), drops the entry from `plugin.recentFiles`, calls `persistRecentFiles()`, then redraws. - **Drag:** Uses `app.dragManager.dragFile()` for native Obsidian drag. - **Hover preview:** Triggers `hover-link` event for Obsidian's page preview popup. - **Context menu:** "Open in new tab" + Obsidian's native `file-menu` event. - **Click:** `Keymap.isModEvent(event)` determines if opening in new leaf; otherwise same leaf. - **Middle click:** Opens in new tab. ### Bookmarks/Favorites Panel **Empty state:** Right-click on "Waypoint Bookmarks" header shows add menu: - Add current file → `addBookmark(path, basename, 'file')` - New group → `addBookmark('', 'New Group', 'group', 'folder')` - Add separator → `addBookmark('', '', 'separator')` - Add spacer → `addBookmark('', '', 'spacer')` **Rendering:** `renderBookmarkList(container, items, depth)` recursively renders items with `paddingLeft: 8 + depth * 16px` for indentation. **Item types:** | Type | Render | Behavior | |---|---|---| | `file` | icon + label | Click opens file. Tooltip = filePath. | | `group` | chevron + icon + label | Click toggles `collapsed`. Children rendered in nested `waypoint-bookmark-children` div (hidden when collapsed). | | `separator` | horizontal line (::after pseudo-element) | No click handler. Context menu for delete. | | `spacer` | 14px empty div | No click handler. Context menu for delete. | **Drag-and-drop:** All bookmark items are draggable. Drop indicators show a 3px accent border above/below the target. On drop: 1. Remove dragged item from its current position (recursive search). 2. Insert at the target position (before or after based on cursor Y position relative to target midY). 3. If target not found (edge case), push to root. 4. Save + redraw. **Context menu (right-click):** - File items: "Open in new tab" - File/Group items: "Rename" (opens `PromptModal`), "Change icon" (opens `IconSuggestModal`) - "Move to group" submenu: Lists all available groups (excluding self + descendants) + "(Root)" for ungrouping - Group items: "Expand/Collapse", "Add bookmark here", "New sub-group" - All items: "Insert separator above/below", "Insert spacer above/below", "Remove" **Move to group (`moveBookmarkToGroup`):** 1. Remove item from current position. 2. If targetGroupId: find group, set `item.indent = group.indent + 1`, push to group's children. 3. If null (root): set `item.indent = 0`, push to `waypointData.bookmarks`. **Prompt modal (`PromptModal`):** Simple Modal with a text input plus Cancel and CTA buttons. Enter key submits. Constructed as `new PromptModal(app, options, onSubmit)`, where `options` is `{ title, placeholder?, initialValue?, cta? }` and `cta` (the submit button label) defaults to `Save`. Generalized from the old rename-only `RenameModal` so the calendar's day context menu can reuse it to prompt for a note title. **Icon picker (`IconSuggestModal`):** Modal with: - Live preview of selected icon. - Search input with 60ms debounce. - Grid of matching icons (max 80 shown), loaded from `https://cdn.jsdelivr.net/npm/lucide-static@0.517.0/tags.json` with fallback to `https://lucide.dev/api/tags` and a hardcoded `FALLBACK_ICONS` object (~300 icons). The fetch result is cached for the session, so at most one network round-trip happens no matter how often the picker is opened. - Click to select, **No icon** button to clear, Save/Cancel buttons. --- ## CSS Architecture (`styles.css`) All classes prefixed with `waypoint-`. Uses Obsidian CSS variables throughout: - `--font-ui-small`, `--font-ui-medium`, `--font-semibold`, `--font-medium`, `--font-light` - `--text-muted`, `--text-faint`, `--text-accent`, `--text-on-accent`, `--text-error` - `--background-modifier-border`, `--background-modifier-active-hover`, `--background-modifier-hover`, `--background-primary`, `--background-primary-alt`, `--background-secondary` - `--interactive-accent` - `--cursor-link` (pointer cursor, with a `pointer` fallback) Key layout: - `.waypoint-view` — flex column, `overflow-y: auto`, 8px padding. - `.waypoint-section` — `flex-shrink: 0`, 16px bottom margin. Last section gets `margin-top: auto` (pins calendar to bottom). - `.waypoint-calendar` — padded, bordered surface with separated day cells for clear scan lines. - Calendar table — `table-layout: fixed`, `border-collapse: separate`, 2px horizontal / 3px vertical cell spacing. - `.waypoint-day.today` — accent text with an inset accent ring, avoiding layout shifts. - `.waypoint-day.has-note::after` — neutral single-dot indicator. - `.waypoint-day-indicators` / `.waypoint-day-indicator` — compact ordered dot row; `--waypoint-indicator-color` carries each configured system colour. - `.waypoint-bm-chevron` — `rotate(-90deg)` on collapsed groups. - `.waypoint-bm-drop-line` / `.waypoint-bm-drop-below` — 3px accent border for drag indicators. --- ## Date Utilities (`date-utils.ts`) All use Obsidian's bundled `moment` (not the npm package). | Function | Signature | Returns | |---|---|---| | `getPeriodInfo(date)` | `Moment → PeriodInfo` | `{day, week, month, quarter, year}` strings for the date | | `getQuarterString(date)` | `Moment → string` | e.g. `"2026-Q3"` | | `getTodayPeriod()` | `() → PeriodInfo` | Current date's period info | | `getMonthGrid(year, month, firstDayOfWeek)` | `number, number, number → CalendarWeek[]` | Up to 6 weeks, each with 7 `CalendarDay` objects | | `formatDateLabel(date)` | `Moment → string` | `"June 1st, 2026"` | | `formatMonthLabel(date)` | `Moment → string` | `"June 2026"` | | `formatQuarterLabel(date)` | `Moment → string` | `"Q3 2026"` | | `navigateDate(date, period, delta)` | `Moment, period, number → Moment` | Clones + adds delta (quarters: delta×3 months) | | `formatPeriodName(date, format)` | `Moment, string → string` | `date.format(format)` wrapper | | `getISOWeek(date)` | `Moment → number` | `date.isoWeek()` | **`getMonthGrid` algorithm:** 1. Find the first day to display by subtracting `(firstOfMonth.day() - firstDayOfWeek + 7) % 7` days from the 1st. 2. Iterate day-by-day, building 7-day weeks. 3. Each `CalendarDay` tracks: `date` (Moment), `dayOfMonth`, `isToday`, `isCurrentMonth`, `isoWeekNumber`. 4. Week's `weekNumber` = first day's ISO week number. 5. Safety break after 6 weeks. --- ## Settings Persistence Settings and waypoint data share a single `data.json` via Obsidian's `Plugin.loadData()/saveData()`: ```typescript // loadData() returns: { settings: { calendar: {...}, daily: {...}, ... }, waypointData: { bookmarks: [...] } } ``` `onload()` reads `data.json` once, then `applySettings(saved)` and `applyWaypointData(saved)` merge partial persisted values over defaults. `persistAll()` writes both in-memory keys through one promise chain; it never re-reads stale disk state. Recent-file writes additionally go through the 300ms debounce in `persistRecentFiles()`. --- ## Redraw Mechanism `broadcastRedraw()` iterates all leaves of `WAYPOINT_VIEW_TYPE` and calls `view.redraw()` on each. `redraw()` is a full DOM rebuild (no virtual DOM, no diffing). This is triggered by: - File open/create/delete/rename/modify events - Bookmark add/remove/update - Period navigation - Settings changes (via `onSettingsChange` callback) - Midnight detection (10-min interval) The sidebar is re-rendered from scratch on every change. For a small sidebar this is acceptable; for larger bookmark lists it may cause flicker. --- ## Known Limitations / Gaps 1. **No virtual DOM** — Full rebuild on every redraw. Bookmark drag/drop, rename, and any change tears down and rebuilds the entire sidebar. For a small sidebar this is acceptable; for larger bookmark lists it may cause flicker. 2. **IconSuggestModal fetches from CDN** — Network dependency for the Lucide tag list. The fetch happens at most once per session (the result is cached) and falls back to the hardcoded `FALLBACK_ICONS` list on failure, but a first-open with no network still degrades to that reduced list.