feat: reload indicator (#105)

* feat: add reload indicator timer service

* feat: add reload indicator setting and status bar item

* feat: integrate reload indicator into render flow

* docs: explain reload indicator options

Author: fdcote

docs/config.md

@@ -32,7 +32,8 @@ Below is an example configuration file that replicates the default settings. You
   },
   "FileMonitor": {
     "enabled": true,
-    "latency": 0.1
+    "latency": 0.1,
+    "reload_indicator_duration": 1.0
   },
   "General": {
     "colorize": false,
@@ -52,7 +53,9 @@ Below is an example configuration file that replicates the default settings. You
     "items": [
       " ",
       { "view": { "text": "VIS" }, "command": { "text": "CMD" } },
-      "   <path><separator><page>:<total_pages> "
+      "   <path> ",
+      { "idle": { "text": " " }, "reload": { "text": "*" } }, 
+      "<separator><page>:<total_pages> "
     ]
   },
   "Cache": {
@@ -80,6 +83,7 @@ The rest of this reference provides detailed explanations for each configuration
     - [Plain Items](#plain-items)
     - [Styled Items](#styled-items)
     - [Mode-aware Items](#mode-aware-items)
+     - [Reload-aware Items](#reload-aware-items)
 - [Cache](#cache)
 
 ---
@@ -165,6 +169,7 @@ The `FileMonitor` section controls the automatic reloading feature, useful for l
 | :--- | :--- | :--- |
 | `enabled` | Boolean | Enables file change detection and automatic reloading |
 | `latency` | Float (seconds) | The time interval between checking for changes |
+| `reload_indicator_duration` | Float (seconds) | How long the reload indicator remains visible (`0.0` disables it) |
 
 ---
 
@@ -207,7 +212,7 @@ The `StatusBar` section controls the information shown at the bottom of the wind
 | :--- | :--- |  :--- |
 | `enabled` | Boolean | Enables the status bar |
 | `style` | [Style](#style) | Default appearance of the entire status bar |
-| `items` | [Items](#items) | Each item is a part of the status bar |
+| `items` | [Items](#items) | Status bar items |
 
 ### Style
 
@@ -240,12 +245,12 @@ The `ul_style` property can be set to one of the following styles:
 
 ### Items
 
-There are three kinds of items:
+The `items` property can be set to an array of status bar items, which include:
 
 * **[plain items](#plain-items)**: text with default styling
 * **[styled items](#styled-items)**: text with custom [styling](#style)
 * **[mode-aware items](#mode-aware-items)**: styled items to be displayed depending on the current mode
-
+* **[reload-aware items](#reload-aware-items)**: styled items to be displayed depending on the current reload indicator state
 #### Plain Items
 
 Plain items are just strings that may include placeholders (e.g., `<page>:<total_pages>`). These placeholders are replaced with dynamic content at runtime.
@@ -292,8 +297,17 @@ Mode-aware items switch their content based on the current mode. Each item must
 }
 ```
 
+#### Reload-aware Items
+
+Reload-aware items switch their content based on the reload indicator state. Each item must include at least one of:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `idle` | [Styled item](#styled-items) | Item to display when the reload indicator is off |
+| `reload` | [Styled item](#styled-items) | Item to display when the reload indicator is on |
+
 >[!TIP]
->Try using placeholders in mode-aware items to enhance feedback!
+>Try using placeholders in mode- and reload-aware items to enhance feedback!
 
 ---
 

src/Context.zig

@@ -6,18 +6,21 @@ const fzwatch = @import("fzwatch");
 const Config = @import("config/Config.zig");
 const DocumentHandler = @import("handlers/DocumentHandler.zig");
 const Cache = @import("./Cache.zig");
+const ReloadIndicatorTimer = @import("services/ReloadIndicatorTimer.zig");
 
 pub const panic = vaxis.panic_handler;
 
-const Event = union(enum) {
+pub const Event = union(enum) {
     key_press: vaxis.Key,
     mouse: vaxis.Mouse,
     winsize: vaxis.Winsize,
     file_changed,
+    reload_done: usize,
 };
 
 pub const ModeType = enum { view, command };
 pub const Mode = union(ModeType) { view: ViewMode, command: CommandMode };
+pub const ReloadIndicatorState = enum { idle, reload };
 
 pub const Context = struct {
     const Self = @This();
@@ -38,6 +41,8 @@ pub const Context = struct {
     reload_page: bool,
     cache: Cache,
     should_check_cache: bool,
+    reload_indicator_timer: ReloadIndicatorTimer,
+    current_reload_indicator_state: ReloadIndicatorState,
     buf: []u8,
 
     pub fn init(allocator: std.mem.Allocator, args: [][:0]u8) !Self {
@@ -64,6 +69,7 @@ pub const Context = struct {
         const vx = try vaxis.init(allocator, .{});
         const buf = try allocator.alloc(u8, 4096);
         const tty = try vaxis.Tty.init(buf);
+        const reload_indicator_timer = ReloadIndicatorTimer.init(config);
 
         return .{
             .allocator = allocator,
@@ -82,6 +88,8 @@ pub const Context = struct {
             .reload_page = true,
             .cache = Cache.init(allocator, config, vx, &tty),
             .should_check_cache = config.cache.enabled,
+            .reload_indicator_timer = reload_indicator_timer,
+            .current_reload_indicator_state = .idle,
             .buf = buf,
         };
     }
@@ -102,6 +110,7 @@ pub const Context = struct {
         self.config.deinit();
         self.allocator.destroy(self.config);
         self.arena.deinit();
+        self.reload_indicator_timer.deinit();
         self.cache.deinit();
         self.document_handler.deinit();
         self.vx.deinit(self.allocator, self.tty.writer());
@@ -142,6 +151,9 @@ pub const Context = struct {
                 w.setCallback(callback, &loop);
                 self.watcher_thread = try std.Thread.spawn(.{}, watcherWorker, .{ self, w });
             }
+            if (self.config.status_bar.enabled and self.config.file_monitor.reload_indicator_duration > 0) {
+                try self.reload_indicator_timer.start(&loop);
+            }
         }
 
         while (!self.should_quit) {
@@ -204,6 +216,13 @@ pub const Context = struct {
                 try self.document_handler.reloadDocument();
                 self.cache.clear();
                 self.reload_page = true;
+                if (self.config.status_bar.enabled and self.config.file_monitor.reload_indicator_duration > 0) {
+                    self.current_reload_indicator_state = .reload;
+                    self.reload_indicator_timer.notifyChange();
+                }
+            },
+            .reload_done => {
+                self.current_reload_indicator_state = .idle;
             },
         }
     }
@@ -318,6 +337,12 @@ pub const Context = struct {
                         .command => try expandPlaceholders(&expanded_items, mode_aware.command),
                     }
                 },
+                .reload_aware => |reload_aware| {
+                    switch (self.current_reload_indicator_state) {
+                        .reload => try expandPlaceholders(&expanded_items, reload_aware.reload),
+                        .idle => try expandPlaceholders(&expanded_items, reload_aware.idle),
+                    }
+                },
             }
         }
 
@@ -393,7 +418,7 @@ pub const Context = struct {
             if (std.mem.startsWith(u8, full_path, cwd)) {
                 var path = full_path[cwd.len..];
                 if (path.len > 0 and path[0] == '/') path = path[1..];
-                text = try std.fmt.allocPrint(allocator, "./{s}", .{path});
+                text = try std.fmt.allocPrint(allocator, "{s}", .{path}); // trim cwd
             } else if (std.posix.getenv("HOME")) |home| {
                 if (std.mem.startsWith(u8, full_path, home)) {
                     var path = full_path[home.len..];

src/config/Config.zig

@@ -34,13 +34,15 @@ pub const FileMonitor = struct {
     enabled: bool = true,
     // Amount of time in seconds to wait in between polling for file changes
     latency: f16 = 0.1,
+    reload_indicator_duration: f16 = 1.0,
 
     pub fn parse(val: std.json.Value, allocator: std.mem.Allocator) FileMonitor {
         var file_monitor = FileMonitor{};
         if (val != .object) return file_monitor;
 
         file_monitor.enabled = parseType(bool, val.object, "enabled", allocator, file_monitor.enabled);
         file_monitor.latency = parseType(f16, val.object, "latency", allocator, file_monitor.latency);
+        file_monitor.reload_indicator_duration = parseType(f16, val.object, "reload_indicator_duration", allocator, file_monitor.reload_indicator_duration);
 
         return file_monitor;
     }
@@ -102,9 +104,14 @@ pub const StatusBar = struct {
         view: StyledItem,
         command: StyledItem,
     };
+    pub const ReloadAwareItem = struct {
+        idle: StyledItem,
+        reload: StyledItem,
+    };
     pub const Item = union(enum) {
         styled: StyledItem,
         mode_aware: ModeAwareItem,
+        reload_aware: ReloadAwareItem,
     };
 
     const default_style = vaxis.Cell.Style{
@@ -126,6 +133,10 @@ pub const StatusBar = struct {
         .{ .styled = .{ .text = "   ", .style = default_style } },
         .{ .styled = .{ .text = PATH, .style = default_style } },
         .{ .styled = .{ .text = " ", .style = default_style } },
+        .{ .reload_aware = .{
+            .idle = .{ .text = " ", .style = default_style },
+            .reload = .{ .text = "*", .style = default_style },
+        } },
         .{ .styled = .{ .text = SEPARATOR, .style = default_style } },
         .{ .styled = .{ .text = PAGE, .style = default_style } },
         .{ .styled = .{ .text = ":", .style = default_style } },
@@ -325,6 +336,10 @@ fn applyStyle(item: StatusBar.Item, style: vaxis.Cell.Style, allocator: std.mem.
         .view = StatusBar.StyledItem{ .text = "", .style = style },
         .command = StatusBar.StyledItem{ .text = "", .style = style },
     } };
+    var reload_aware_item: StatusBar.Item = .{ .reload_aware = StatusBar.ReloadAwareItem{
+        .idle = StatusBar.StyledItem{ .text = "", .style = style },
+        .reload = StatusBar.StyledItem{ .text = "", .style = style },
+    } };
 
     switch (item) {
         .styled => |styled| {
@@ -336,6 +351,11 @@ fn applyStyle(item: StatusBar.Item, style: vaxis.Cell.Style, allocator: std.mem.
             mode_aware_item.mode_aware.command.text = allocator.dupe(u8, mode_aware.command.text) catch mode_aware_item.mode_aware.command.text;
             return mode_aware_item;
         },
+        .reload_aware => |reload_aware| {
+            reload_aware_item.reload_aware.reload.text = allocator.dupe(u8, reload_aware.reload.text) catch reload_aware_item.reload_aware.reload.text;
+            reload_aware_item.reload_aware.idle.text = allocator.dupe(u8, reload_aware.idle.text) catch reload_aware_item.reload_aware.idle.text;
+            return reload_aware_item;
+        },
     }
 }
 
@@ -345,6 +365,10 @@ fn parseItem(val: std.json.Value, allocator: std.mem.Allocator, fallback_style:
         .view = StatusBar.StyledItem{ .text = "", .style = fallback_style },
         .command = StatusBar.StyledItem{ .text = "", .style = fallback_style },
     } };
+    var reload_aware_item: StatusBar.Item = .{ .reload_aware = StatusBar.ReloadAwareItem{
+        .idle = StatusBar.StyledItem{ .text = "", .style = fallback_style },
+        .reload = StatusBar.StyledItem{ .text = "", .style = fallback_style },
+    } };
 
     switch (val) {
         .string => |str| {
@@ -358,6 +382,11 @@ fn parseItem(val: std.json.Value, allocator: std.mem.Allocator, fallback_style:
                 mode_aware_item.mode_aware.command = parseStyledItem(obj.get("command"), allocator, mode_aware_item.mode_aware.command);
                 return mode_aware_item;
             }
+            if (obj.contains("reload") or obj.contains("idle")) {
+                reload_aware_item.reload_aware.idle = parseStyledItem(obj.get("idle"), allocator, reload_aware_item.reload_aware.idle);
+                reload_aware_item.reload_aware.reload = parseStyledItem(obj.get("reload"), allocator, reload_aware_item.reload_aware.reload);
+                return reload_aware_item;
+            }
 
             styled_item.styled = parseStyledItem(val, allocator, styled_item.styled);
             return styled_item;

src/services/ReloadIndicatorTimer.zig

@@ -0,0 +1,100 @@
+const Self = @This();
+const std = @import("std");
+const vaxis = @import("vaxis");
+const Config = @import("../config/Config.zig");
+const Event = @import("../Context.zig").Event;
+
+const Timer = std.time.Timer;
+
+mutex: std.Thread.Mutex,
+condition: std.Thread.Condition,
+thread: ?std.Thread,
+should_quit: bool,
+loop: ?*vaxis.Loop(Event),
+reload_indicator_duration_ns: u64,
+reload_timer: ?Timer,
+generation: usize,
+pending: bool,
+config: *Config,
+
+pub fn init(config: *Config) Self {
+    return .{
+        .mutex = std.Thread.Mutex{},
+        .condition = std.Thread.Condition{},
+        .thread = null,
+        .should_quit = false,
+        .loop = null,
+        .reload_indicator_duration_ns = 0,
+        .reload_timer = null,
+        .generation = 0,
+        .pending = false,
+        .config = config,
+    };
+}
+
+pub fn deinit(self: *Self) void {
+    self.mutex.lock();
+    self.should_quit = true;
+    self.condition.signal();
+    self.mutex.unlock();
+
+    if (self.thread) |thread| {
+        thread.join();
+        self.thread = null;
+    }
+}
+
+pub fn start(self: *Self, loop: ?*vaxis.Loop(Event)) !void {
+    self.mutex.lock();
+    self.reload_indicator_duration_ns = @as(u64, @intFromFloat(@as(f32, self.config.file_monitor.reload_indicator_duration) * std.time.ns_per_s));
+    self.loop = loop;
+    self.reload_timer = try Timer.start();
+    self.pending = false;
+    self.mutex.unlock();
+
+    if (self.thread == null) {
+        self.thread = try std.Thread.spawn(.{}, run, .{self});
+    }
+}
+
+fn run(self: *Self) void {
+    const check_interval_ns = self.reload_indicator_duration_ns / 4;
+
+    while (true) {
+        self.mutex.lock();
+
+        if (self.should_quit) {
+            self.mutex.unlock();
+            break;
+        }
+
+        _ = self.condition.timedWait(&self.mutex, check_interval_ns) catch {};
+
+        const current_loop = self.loop;
+        const generation = self.generation;
+        const pending = self.pending;
+
+        var elapsed_ns: u64 = 0;
+        if (self.reload_timer) |*timer| elapsed_ns = timer.read();
+
+        self.mutex.unlock();
+
+        if (pending and (elapsed_ns >= self.reload_indicator_duration_ns)) {
+            if (current_loop) |loop| loop.postEvent(.{ .reload_done = generation });
+
+            self.mutex.lock();
+            self.pending = false;
+            if (self.reload_timer) |*timer| timer.reset();
+            self.mutex.unlock();
+        }
+    }
+}
+
+pub fn notifyChange(self: *Self) void {
+    self.mutex.lock();
+    self.generation += 1;
+    if (self.reload_timer) |*timer| timer.reset();
+    self.pending = true;
+    self.condition.signal();
+    self.mutex.unlock();
+}