olivier
26a1a481ac
Right-clicking a calendar day now lists every configured date-prefixed note system. Journal notes are singletons; {title} formats support multiple notes per date, such as meetings.\n\nAdds default Journal and Meeting systems, configurable settings UI, safe filename/title handling, one shared dated-note creation path, and a compiled menu smoke test fixture in the test vault.
494 lines
29 KiB
Markdown
494 lines
29 KiB
Markdown
# 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; // firstDayOfWeek (0=Sun,1=Mon), showNoteIndicators
|
||
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; // dot on days with existing .md files
|
||
}
|
||
|
||
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`
|
||
|
||
```typescript
|
||
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
|
||
}
|
||
```
|
||
|
||
Configured systems live in `settings.dateSystems`, where array order is menu order. `DEFAULT_DATE_SYSTEM` (in `settings.ts`, typed `Omit<DateSystemSettings, 'id'>`) 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` | Notes per date |
|
||
|---|---|---|---|---|
|
||
| `journal` | Journal | `periodic/journal` | `YYYY-MM-DD - [Journal]` | one |
|
||
| `meetings` | Meeting | `periodic/meetings` | `YYYY-MM-DD - {title}` | many |
|
||
|
||
### 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
|
||
/** One existing note of a date system, with the label the menu should show. */
|
||
interface DateSystemNote {
|
||
file: TFile;
|
||
label: string; // free-text title for many-per-date systems, else the system name
|
||
}
|
||
|
||
/** A day-scoped system and the notes it already holds for one date. */
|
||
interface DateSystemNotes {
|
||
system: DateSystemSettings;
|
||
notes: DateSystemNote[]; // sorted by basename; empty when the date has no note
|
||
multiple: boolean; // nameFormat carries {title}, i.e. many notes per date
|
||
}
|
||
|
||
dateSystems(): DateSystemSettings[]
|
||
findDateSystemNotes(date: moment.Moment): DateSystemNotes[]
|
||
openDateSystemNote(
|
||
system: DateSystemSettings,
|
||
date: moment.Moment,
|
||
opts?: { title?: string; leaf?: WorkspaceLeaf },
|
||
): Promise<void>
|
||
```
|
||
|
||
**`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. Read the template at `system.templateFile` (the `.md` extension is appended when omitted). If it exists, the note is created with the template's contents.
|
||
2. With no template, the note is created with minimal frontmatter instead: `type: {system.typeProperty}` + `date: YYYY-MM-DD`.
|
||
|
||
---
|
||
|
||
## Period Note Creation (`openPeriodNote`)
|
||
|
||
```typescript
|
||
openPeriodNote(
|
||
period: 'day' | 'week' | 'month' | 'quarter' | 'year',
|
||
date: moment.Moment,
|
||
leaf?: WorkspaceLeaf,
|
||
): Promise<void>
|
||
```
|
||
|
||
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` dimmed. `.today` has accent border. `.has-note` gets a dot indicator, decided by the synchronous O(1) `plugin.hasNoteForDate(dateStr)` (a `Set` lookup — no per-cell vault scan).
|
||
- **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-primary`, `--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-section-header` — uppercase, muted, with bottom border.
|
||
- Calendar table — `table-layout: fixed`, `border-collapse: collapse`.
|
||
- `.waypoint-day.today` — accent color text + 1px accent border.
|
||
- `.waypoint-day.has-note::after` — 4px dot indicator.
|
||
- `.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.
|