376 lines
17 KiB
Markdown
376 lines
17 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 constant
|
||
├── settings-tab.ts PluginSettingTab UI (calendar, periodic paths, recent files)
|
||
├── models/
|
||
│ └── bookmark.ts BookmarkItem + WaypointData interfaces
|
||
├── utils/
|
||
│ └── date-utils.ts Moment.js helpers: period formatting, month grid, navigation
|
||
└── views/
|
||
└── waypoint-view.ts ItemView subclass — full sidebar rendering + interaction
|
||
```
|
||
|
||
**Build:** esbuild bundles `src/main.ts` → `main.js`. TypeScript strict, ESNext target.
|
||
|
||
**Data persistence:** Single `data.json` via Obsidian `Plugin.loadData()/saveData()`. Top-level keys: `settings` (merged with `DEFAULT_SETTINGS`), `waypointData` (bookmark tree). Recent files are in-memory only (lost on vault close).
|
||
|
||
---
|
||
|
||
## Plugin Lifecycle
|
||
|
||
### `onload()`
|
||
|
||
1. **Load data** — `loadSettings()` then `loadWaypointData()`, both merge saved partials over defaults via `Object.assign({}, DEFAULT, partial)`.
|
||
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`.
|
||
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;
|
||
recentFiles: RecentFilesSettings; // maxItems, updateOn, omittedPaths[], omittedTags[]
|
||
}
|
||
|
||
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 tags
|
||
}
|
||
```
|
||
|
||
### 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[];
|
||
}
|
||
```
|
||
|
||
The bookmark tree is stored flat in `data.json` under `waypointData.bookmarks` but rendered recursively. Groups contain children; files/separators/spacers are leaf nodes.
|
||
|
||
---
|
||
|
||
## 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)` — regex matching:
|
||
- `^\d{4}-\d{2}-\d{2}$` → daily
|
||
- `^\d{4}-W\d{2}$` → weekly
|
||
- `^\d{4}-\d{2}$` → monthly
|
||
- `^\d{4}-Q[1-4]$` → quarterly
|
||
- `^\d{4}$` → yearly
|
||
3. Parses date via `moment(basename, format)`.
|
||
4. Adds ±1 period (quarters add ±3 months).
|
||
5. 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 |
|
||
|
||
---
|
||
|
||
## Period Note Creation (`openPeriodNote`)
|
||
|
||
For a given period + moment date:
|
||
|
||
1. **Build filename:** `date.format(periodSettings.nameFormat) + ".md"`.
|
||
2. **Build full path:** If `periodSettings.folder` is set, prepend it; otherwise root.
|
||
3. **Check existence:** `vault.getFileByPath(fullPath)`.
|
||
4. **If not found, create:**
|
||
- Try to read template at `periodSettings.templateFile + ".md"`.
|
||
- If template exists → `vault.create(fullPath, templateContent)`.
|
||
- If no template → `vault.create(fullPath, minimalFrontmatter)` where frontmatter is `type: {typeProperty}` + `date: YYYY-MM-DD`.
|
||
5. **Open in new leaf:** `workspace.getLeaf(false).openFile(file)`.
|
||
|
||
---
|
||
|
||
## Event Handling
|
||
|
||
### `file-open`
|
||
|
||
If `settings.recentFiles.updateOn === 'file-open'` → calls `addToRecentFiles(file)`.
|
||
|
||
If `updateOn === 'file-edit'` → currently skipped (placeholder for future edit-detection).
|
||
|
||
### `vault:create` / `vault:delete`
|
||
|
||
Both trigger `broadcastRedraw()` — tells all WaypointView instances to re-render (needed for calendar note indicators and stale recent file references).
|
||
|
||
### `vault:rename`
|
||
|
||
1. Updates `recentFiles` entry if path matches `oldPath`.
|
||
2. Calls `updateBookmarkPath(oldPath, newPath)` — recursively scans `waypointData.bookmarks` and updates any `filePath` matching `oldPath`.
|
||
|
||
---
|
||
|
||
## Recent Files (in-memory)
|
||
|
||
```typescript
|
||
recentFiles: { path: string; basename: string }[]
|
||
```
|
||
|
||
**Update flow:**
|
||
1. `addToRecentFiles(file)` — dedupes (removes existing entry), prepends to front, truncates to `maxItems`.
|
||
2. Calls `broadcastRedraw()`.
|
||
|
||
**Omitted paths/tags:** Settings store regex patterns but the current `addToRecentFiles` does **not** filter by them — these are only exposed in the settings UI. The filtering is not yet wired up in the add logic.
|
||
|
||
**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.
|
||
- **Day cells:** Click opens daily note. `.other-month` dimmed. `.today` has accent border. `.has-note` gets a dot indicator (checked via `vault.getFiles().some(f => f.basename === dateStr)`).
|
||
- **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`.
|
||
|
||
### 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`), removes entry from array + saves settings + 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 `RenameModal`), "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`.
|
||
|
||
**Rename modal (`RenameModal`):** Simple Modal with text input + Cancel/Save buttons. Enter key submits.
|
||
|
||
**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).
|
||
- Click to select, "No icon" link 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`
|
||
- `--background-modifier-border`, `--background-modifier-active-hover`, `--background-primary`, `--background-secondary`
|
||
- `--interactive-accent`
|
||
- `--cursor` (for custom cursor support)
|
||
|
||
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: [...] }
|
||
}
|
||
```
|
||
|
||
Both `loadSettings()` and `loadWaypointData()` read from the same file, merging partials over defaults. `saveSettings()` and `saveWaypointData()` each re-read the full data, update their key, and write back. This means they must not run concurrently (no locking — relies on Obsidian's synchronous save behavior).
|
||
|
||
---
|
||
|
||
## 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 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. **Recent files omittedPaths/omittedTags** — Settings UI exposes these regex filters, but `addToRecentFiles()` does not apply them. Files are never filtered out.
|
||
2. **`updateOn: 'file-edit'`** — The `file-open` handler returns early for this mode, but no edit-detection event is registered. Recent files never update in edit mode.
|
||
3. **No virtual DOM** — Full rebuild on every redraw. Bookmark drag/drop, rename, and any change tears down and rebuilds the entire sidebar.
|
||
4. **Concurrent saves** — `saveSettings()` and `saveWaypointData()` both re-read then write `data.json`. Rapid sequential calls could race.
|
||
5. **Recent files not persisted** — Cleared on vault reload. Only bookmarks survive restarts.
|
||
6. **Note indicators scan all vault files** — `hasNoteForDate()` iterates `vault.getFiles()` on every calendar render (called per day cell). For large vaults, this is O(days × files). Not cached.
|
||
7. **`detectPeriodType` uses hardcoded formats** — The regex patterns in `main.ts` don't read from `settings.*.nameFormat`. If a user changes the name format to something non-standard, next/prev navigation breaks.
|
||
8. **IconSuggestModal fetches from CDN** — Network dependency on first icon picker open. Falls back to hardcoded list on failure.
|