echo-bar.el

;;; echo-bar.el --- Performant echo-area status display -*- lexical-binding: t -*-

;; Author: Anton Chen <mail@antonchen.ca>
;; Version: 0.1.0
;; Package-Requires: ((emacs "29.1"))
;; Keywords: frames, convenience
;; URL: https://github.com/chenanton/echo-bar
;; SPDX-License-Identifier: GPL-3.0-or-later
;; Copyright (C) 2026 Anton Chen

;;; Commentary:
;;
;; Display status information in the echo area instead of a modeline.
;; Saves one line of screen real estate.
;;
;; Key design: event-driven updates with coalescing, not timer-based polling.
;; Segments declare what triggers them (hooks, advice, timers).  When a
;; trigger fires, the segment is marked dirty and a single coalesced
;; update is scheduled via `run-at-time 0 nil'.  Only dirty segments
;; recompute.  Overlays are written only when the display string changes.
;;
;; Usage:
;;   (require 'echo-bar)
;;   (setq echo-bar-layout
;;     '(:center ("buffer-position" "buffer-name" "major-mode")
;;       :right  ("battery" "time" "project" "vcs")))
;;   (echo-bar-mode 1)

;;; Code:

(require 'echo-bar-faces)
(require 'echo-bar-segments)
(require 'echo-bar-render)
(require 'echo-bar-engine)

;; ──────────────────────────────────────────────────────────────────
;;; Customization
;; ──────────────────────────────────────────────────────────────────

(defgroup echo-bar nil
  "Echo-area status display."
  :group 'frames
  :prefix "echo-bar-")

(defcustom echo-bar-layout
  '(:right ("buffer-name" "buffer-position" "major-mode" "vcs"
            "project" "battery" "time"))
  "Plist mapping positions to segment name lists.
Supported keys: :left, :center, :right.  Segments not listed in
any group are not displayed.

Example layouts:
  \\=':center + :right  -- center group centered, right group right-aligned
  \\=':left + :right    -- left flush-left, right right-aligned
  \\=':right only       -- everything right-aligned (simplest)"
  :type '(plist :key-type symbol :value-type (repeat string))
  :group 'echo-bar)

(defcustom echo-bar-separator " "
  "String used to separate segments within a group."
  :type 'string
  :group 'echo-bar)

(defcustom echo-bar-left-padding 0
  "Characters of padding between the left edge and the first segment."
  :type 'integer
  :group 'echo-bar)

(defcustom echo-bar-right-padding 1
  "Characters of padding between the right group and the right edge."
  :type 'integer
  :group 'echo-bar)

(defcustom echo-bar-center-right-gap 4
  "Minimum character gap between center and right groups.
When they would overlap, the center group is pushed left."
  :type 'integer
  :group 'echo-bar)

(defcustom echo-bar-time-format "%a %b %-e %-I:%M %p"
  "Format string for the time segment.
Passed to `format-time-string'.  The default produces output like
\"Wed Mar 5 8:48 PM\"."
  :type 'string
  :group 'echo-bar)

(defcustom echo-bar-idle-fallback-interval 2.0
  "Seconds of idle time before a full refresh (safety net).
Set to nil to disable."
  :type '(choice number (const nil))
  :group 'echo-bar)

(defcustom echo-bar-message-max-width 30
  "Maximum character width for messages in the echo area.
Messages longer than this are truncated with an ellipsis before
being centered in the minibuffer."
  :type 'integer
  :group 'echo-bar)

;; ──────────────────────────────────────────────────────────────────
;;; Mode definition
;; ──────────────────────────────────────────────────────────────────

(defvar echo-bar--saved-mode-line-format nil
  "Saved `mode-line-format' to restore when disabling.")

;;;###autoload
(define-minor-mode echo-bar-mode
  "Display status information in the echo area instead of the mode line."
  :global t
  :group 'echo-bar
  (if echo-bar-mode
      (progn
        ;; Save and hide mode line
        (setq echo-bar--saved-mode-line-format
              (default-value 'mode-line-format))
        (setq-default mode-line-format nil)
        (dolist (buf (buffer-list))
          (with-current-buffer buf
            (setq mode-line-format nil)))
        ;; Setup
        (echo-bar--setup-overlays)
        (echo-bar--register-all-hooks)
        ;; Initial full render
        (echo-bar--mark-all-dirty)
        (echo-bar--do-update))
    ;; Teardown
    (echo-bar--remove-all-hooks)
    (echo-bar--remove-overlays)
    (setq echo-bar--update-pending nil
          echo-bar--last-display nil)
    ;; Restore mode line
    (setq-default mode-line-format echo-bar--saved-mode-line-format)
    (dolist (buf (buffer-list))
      (with-current-buffer buf
        (setq mode-line-format echo-bar--saved-mode-line-format)))))

(provide 'echo-bar)
;;; echo-bar.el ends here