HUD Widget Blocks

[!NOTE] Safe & Non-Destructive: This plugin operates strictly in read-only mode. It never modifies, edits, alters, or writes to any of your existing notes in your vault (with the sole exception of the Live Session Tracker widget, which creates and updates session log notes only when you explicitly start or end a session).

Modular and customisable sci-fi HUD widgets and dashboards for your notes.

---

✨ Features

• Modular Widgets: Quick Actions, Live Session Tracker, Vault Navigator, Activity Heatmap, Vault Stats, Metrics Dashboard, Activity Timeline, and Completion Trends.
• Clean 2-Line Codeblocks: No need to paste 1,000+ lines of raw JavaScript into your notes.
• Updates from GitHub: Update widgets directly from GitHub within Obsidian settings.
• Automatic Note-Based Profiles: Zero configuration required — each note automatically creates and remembers its own settings.
• Zero External Plugin Dependencies: When the HUD Widget Blocks plugin is installed, all 8 widgets work 100% natively out of the box — you do NOT need Dataview or any other plugin installed!
• Standalone DataviewJS Compatible: Don't want to install this plugin? You can still run any of the .js files standalone, provided you have the Dataview plugin installed (with "Enable JavaScript Queries" turned ON).

---

🚀 Installation

From Obsidian Community Plugins (Recommended)

1. In Obsidian, navigate to Settings → Community plugins.
2. Turn off Restricted mode if prompted.
3. Click Browse and search for HUD Widget Blocks.
4. Click Install, then click Enable.

Manual Installation

1. Download the hud-blocks release files (main.js, manifest.json, styles.css, catalog.json, and widgets/) from the Latest Release.
2. Inside your Obsidian vault, navigate to .obsidian/plugins/.
3. Create a folder named hud-blocks and copy the downloaded files into it.
4. Go to Settings → Community plugins, click Reload plugins, and enable HUD Widget Blocks.

---

⚡ Quick Start

1. Standard Syntax

In any markdown note, add a hud codeblock with widget: <id or alias>:

```hud
widget: activity-heatmap
```

2. Convenience Tag Syntax

You can also use the direct tag for any widget:

```hud-heatmap
```

3. Quick Insert Command

Open the Command Palette (Ctrl+P or Cmd+P) and type:

HUD Blocks: Insert HUD Widget...

Select any widget from the fuzzy-search list to insert it at your cursor.

4. Widget Catalog & Syntax

#	Widget Name	Primary ID	Aliases	Direct Codeblock Tag
01	Quick Actions	quick-actions	1	```hud-quick-actions
02	Live Session Tracker	live-session-tracker	2	```hud-live-tracker
03	Vault Navigator	vault-navigator	3	```hud-vault-navigator
04	Activity Heatmap	activity-heatmap	4	```hud-heatmap
05	Vault Stats	vault-stats	5	```hud-vault-stats
06	Metrics Dashboard	metrics-dashboard	6	```hud-metrics
07	Activity Timeline	activity-timeline	7	```hud-timeline
08	Completion Trends	completion-trends	8	```hud-completion-trends

5. Handling Multiple Blocks on the Same Page

• Different Widgets on the Same Page: Place as many different widgets as you like on a single page. Each widget runs in its own isolated DOM container and manages its own independent configuration file on disk.
• Multiple Instances of the Same Widget: If you want two instances of the same widget on a single note (e.g., two Quick Actions panels), add the optional profile: parameter to give each block an independent identity:

### Daily Tasks
```hud
widget: quick-actions
profile: daily_shortcuts
```

### Project Actions
```hud
widget: quick-actions
profile: project_actions
```

---

📖 6. Widget Setup & User Manual

[!TIP] Interactive In-Widget Settings (⚙️): Every widget has a ⚙️ Settings button in its top-right corner. Because HUD Widget Blocks does not hardcode any personal folder or property names, all folder and YAML property fields start blank by default so you can connect them to your own vault structure in seconds.

Widget	Requires YAML Frontmatter?	YAML Properties Used (Configured in ⚙️ Settings)
01. Quick Actions	❌ No	None — configured 100% visually in ⚙️ Settings
02. Live Session Tracker	✅ Yes (Auto-created)	Start Time, End Time, and Tracked Item properties
03. Vault Navigator	⚡ Optional	banner (strictly lowercase) for card cover images + optional YAML Filter
04. Activity Heatmap	❌ No	None — automatically reads file creation (ctime) & modification (mtime) dates
05. Vault Stats	✅ Yes (for grouping)	Base Properties (comma-separated YAML keys linking notes to .base files/categories)
06. Metrics Dashboard	✅ Yes	Start Time, End Time, Completion Date, and Year properties
07. Activity Timeline	✅ Yes	Start Time, End Time, and Item / Activity properties
08. Completion Trends	✅ Yes	Completion Date property (also detects /YYYY/ year subfolders)

---

🔹 01. Quick Actions (quick-actions)

• Zero YAML Setup Needed: Click the ⚙️ icon in the widget header to add custom buttons, choose Emoji or Lucide icons, and link each button to:
  • Obsidian Commands (triggers any core or community plugin command)
  • Vault Notes / .base Files (opens any file in your vault)
  • External URLs (opens web links or obsidian:// URIs)

---

🔹 02. Live Session Tracker (live-session-tracker)

• Works 100% Natively (No External Plugins Required): Automatically creates a new session log note when you click Start and writes the end timestamp when you click End.
• Required First-Time ⚙️ Setup: Open ⚙️ Settings and fill in:
  1. Sessions Folder: The folder where new session log notes will be saved (e.g. Logs/Sessions).
  2. Items Folder: The folder containing the notes/projects/activities you want to pick from the dropdown (or link a .base file).
  3. YAML Property Names: Enter the property names to write into each session note:
     • Start Time Property (e.g. start-time)
     • End Time Property (e.g. end-time)
     • Tracked Item Property (e.g. activity or project)
• Optional QuickAdd Plugin Integration: If you prefer custom macros via the QuickAdd community plugin, you can optionally select your QuickAdd start/end commands in ⚙️ Settings.

---

🔹 03. Vault Navigator (vault-navigator) — & Card Banner Image Previews

• Navigation Modes & Filters: In the ⚙️ Settings drawer, switch between Manual Selection Mode (pin specific notes or .base files) and Recent Notes Mode (automatically show recently edited notes). You can also narrow down results using the YAML Filter (by property key & value) or Folder Filter.

[!IMPORTANT] 🖼️ How to Show Banner Image Previews on Cards (No Banner Plugin Needed!)

You do NOT need the Banners plugin (or any other community plugin) installed to display cover images on Vault Navigator cards!

Simply add a YAML frontmatter property named banner (strictly lowercase banner, not Banner) to any linked note and point it to an image in your vault or a web URL:

---
banner: "[[my-cover-image.png]]"
# You can also use a relative vault path or an external web URL:
# banner: "Attachments/cover-image.jpg"
# banner: "https://example.com/banner.jpg"
---

---

🔹 04. Activity Heatmap (activity-heatmap)

• Zero YAML Setup Needed (Works Out of the Box): Automatically scans .md and .base files across your vault and plots daily activity intensity using file creation (ctime) and modification (mtime) dates.
• In-Widget Controls & ⚙️ Settings: Switch between Yearly and 365-Day Rolling views or pick color themes directly in the header. Open ⚙️ Settings to customize the Widget Heading (supports {MODE} token) or add Excluded Folders (comma-separated folders to ignore).

---

🔹 05. Vault Stats (vault-stats)

• Categories, .base Files & Radar Distribution: Automatically discovers .base files in your vault (as well as notes with type: base in YAML) and displays a Vault Categories & Bases list on the left alongside an interactive Radar Distribution Chart & Recent Modifications feed on the right.
• Required ⚙️ Setup for Note Grouping: Open ⚙️ Settings and configure:
  • Base Properties: Enter the comma-separated YAML frontmatter property names your notes use to link to a .base file or category (e.g. base, database, category, type). Notes without these properties are grouped under NOT LINKED TO BASE.
  • Excluded Folders & Top Categories Limit: Optionally exclude specific folders from indexing or set the max number of categories shown on the radar chart before grouping the rest into OTHER BASES.

---

🔹 06. Metrics Dashboard (metrics-dashboard)

• Combined Session & Completion Telemetry: Combines three panels — Overview System Metrics, Weekly Load Distribution, and a bottom Completion Telemetry chart.
• Required First-Time ⚙️ Setup: Open ⚙️ Settings and configure its two data sources:
  1. Session Logs (Top Panels): Set your Sessions Folder, Start Time Property, and End Time Property (the same folder and timestamp properties used in Widget 02) to calculate total hours, session counts, active days, and weekly load.
  2. Completed Items (Bottom Chart & Counter): Set your Target / Items Folder, Completion Date Property, and Year Property to track completed items and plot them across Yearly, Monthly, and Recent 12M views.

---

🔹 07. Activity Timeline (activity-timeline)

• Daily Session Trace & Activity Breakdown: Plots an interactive daily session bar chart with date-range presets (7D, 30D, 90D, ALL) and a per-activity hours breakdown.
• Required First-Time ⚙️ Setup: Open ⚙️ Settings and enter your Sessions Folder, Start Time Property, End Time Property, and Item / Activity Property (matching the exact properties configured in Widget 02).

---

🔹 08. Completion Trends (completion-trends)

• Yearly, Monthly & Recent 12M Completion Line Chart: Scans your completed notes and plots completion trends with a multi-year filter dropdown.
• Required First-Time ⚙️ Setup: Open ⚙️ Settings and configure:
  1. Target / Items Folder: Select the vault folder containing your completed notes (e.g. Archive, Projects, Completed — or leave blank to scan the entire vault).
  2. Completion Date Property: Enter the frontmatter property name that stores the completion date on those notes (e.g. completedDate, date-watched, finish-date in YYYY-MM-DD format).

---

⚙️ Settings

Zero-Configuration Note Binding

You never need to configure a profile name manually:

1. When you add a widget to Dashboard.md, the widget automatically detects the note name.
2. It generates a unique profile key: Dashboard.
3. When you click the ⚙️ gear icon and save changes, settings are saved to .obsidian/HUD Config/<widget>--Dashboard.json.
4. Re-opening the note automatically restores your exact configuration.

Shared Profiles (Mirroring)

If you want Project A.md and Project B.md to share identical settings:

1. Open the ⚙️ modal in Project B.md.
2. Select Project A from the Profile dropdown.
3. Click Save Settings. Project B will now automatically mirror Project A!

Updates from GitHub

The plugin features a modular updater:

1. Open Obsidian Settings → HUD Blocks.
2. Click 🔄 Check for Updates.
3. Update individual widgets via [ ⬆️ Update to vX.X.X ], or click [ ⚡ Update All ].
4. The downloaded file immediately overwrites the local script in .obsidian/plugins/hud-blocks/widgets/.
5. Open notes re-render the updated widget instantly without needing an Obsidian restart!
6. Your saved settings, buttons, and custom colors are 100% safe in .obsidian/HUD Config/ and are never overwritten during widget updates.

Standalone Usage (Without Plugin)

[!IMPORTANT]

• If you install the HUD Widget Blocks plugin: All 8 widgets work 100% natively out of the box — you do NOT need Dataview installed.
• If you do NOT install the HUD Widget Blocks plugin: None of the raw .js widget scripts can run in vanilla Obsidian on their own. You MUST install and enable the Dataview community plugin (with "Enable JavaScript Queries" turned ON) to run them.

To run any widget without installing the HUD Widget Blocks plugin:

1. Install and enable the Dataview community plugin (with "Enable JavaScript Queries" turned ON).
2. Copy the code from any file in the widgets/ folder (e.g. 04 - Activity Heatmap.js).
3. Paste it inside a dataviewjs codeblock:

   ```dataviewjs
   // Paste widget code here
   ```
   

The widget UI, animations, and settings modal will function identically.

---

Development

To build the plugin from source:

npm install
npm run build

---

📄 License

This project is licensed under the MIT License.

Developed by Vishwas Upponi.