# 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;
reusePeriodicNoteTabs: boolean; // defaults to false; all periodic-note openers reuse an open tab
weekly: PeriodNoteSettings;
monthly: PeriodNoteSettings;
quarterly: PeriodNoteSettings;
yearly: PeriodNoteSettings;
dateSystems: DateSystemSettings[]; // day-scoped systems beyond the daily note, in menu order
recentFiles: RecentFilesSettings; // maxItems, show, omittedPaths[], omittedTags[], showTypeFilter, types[]
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, per kind (opened / changed)
show: 'all' | 'opened' | 'changed'; // header switch, default 'all'
omittedPaths: string[]; // regex patterns (one per line)
omittedTags: string[]; // regex patterns for frontmatter/inline tags
showTypeFilter: boolean; // type pills above the list, default true
types: { type: string; icon: string }[]; // frontmatter types: row icon + pill order (empty = pills auto-detected)
}
```
Migration in `applySettings`: a saved `filterTags: string[]` becomes `types` with empty icons; the saved `updateOn` is dropped (both kinds are always tracked).
```typescript
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 five commands call `openPeriodNote(period, moment())` — opening or creating the current period's note. **Periodic Notes → Use existing tabs** defaults to off. When enabled, the shared opener focuses a Markdown tab for the exact configured file path, including in another pane or window, without reopening the file or resetting its editor position. This also applies to next/previous navigation and regular calendar clicks. With no matching tab, normal note creation/opening is unchanged. Explicit open-in-new-tab actions still win; existing duplicate tabs are not closed.
### 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 |
| `waypoint-open-date` | Open daily note for a date… — `DatePickerModal` (`src/modals/date-picker-modal.ts`, native ``), then `showDateInViews(date)` and `openPeriodNote('day', date)` |
---
## 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. Existing installs that silently persisted the pre-`systems` default of `any` are promoted to `systems` exactly once, on load, via a `data.json`-level `indicatorModeMigrated` flag; a value chosen after that flag is set (including `any`) is never touched again. Template file fields in both Periodic Notes and Date systems use `TemplateFileSuggest`, an `AbstractInputSuggest` (the same base class Templater's own template pickers use — Obsidian's native fuzzy-suggest popup, not an unstyled `