mirador 1.22.0

//! One settings struct per widget.
//!
//! These live together rather than beside their panels because they are the
//! *schema of the config file*: `serde` reads them all before any panel exists,
//! and a reader working out what a key does should find every key in one place.
//! They carry no behaviour beyond `Default`, and the closed sets of words
//! that some keys take, which `Config::validate` checks.
//!
//! Every one of them sets `deny_unknown_fields`. A silently ignored key is the
//! worst outcome a config can have — it makes a stale config look like stale
//! code — and the two theme structs that lacked it went unnoticed for four
//! releases. See `theme.rs`.

use std::path::PathBuf;

use serde::Deserialize;

/// World clock settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct ClocksConfig {
    /// Clocks to display, in order.
    pub zones: Vec<ClockZone>,
    /// `strftime`-style time format.
    pub time_format: String,
    /// `strftime`-style date format. Empty hides the date.
    pub date_format: String,
    /// Show each zone's offset relative to the primary clock.
    pub show_offset: bool,
    /// Include seconds in the large clock and the zone table. On by default —
    /// the block numerals are the panel's whole face, and a chronometer that
    /// visibly runs is the look the design is after; `s` turns them off at a
    /// keystroke for anyone who finds the tick draws the eye, and takes them
    /// out of the table's `time_format` too.
    pub show_seconds: bool,
    /// A 12-hour clock, with AM/PM set small beside the numerals. Off by
    /// default; `h` switches it and the choice is remembered. When on it
    /// governs the whole panel, converting the zone table's `time_format` to
    /// match (#265). When off, the hours in `time_format` are used as written,
    /// so a config that already asked for `%I:%M:%S %p` keeps its table.
    pub twelve_hour: bool,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for ClocksConfig {
    fn default() -> Self {
        Self {
            zones: vec![
                ClockZone {
                    label: "Local".into(),
                    timezone: "local".into(),
                },
                ClockZone {
                    label: "UTC".into(),
                    timezone: "UTC".into(),
                },
                ClockZone {
                    label: "London".into(),
                    timezone: "Europe/London".into(),
                },
                ClockZone {
                    label: "Tokyo".into(),
                    timezone: "Asia/Tokyo".into(),
                },
            ],
            time_format: "%H:%M:%S".into(),
            date_format: "%A %d %B".into(),
            show_offset: true,
            show_seconds: true,
            twelve_hour: false,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

/// A single clock.
///
/// `Serialize` because the live list lives in a data file the panel writes;
/// see [`crate::zones`].
#[derive(Debug, Clone, Deserialize, serde::Serialize, Default)]
#[serde(default, deny_unknown_fields)]
pub struct ClockZone {
    /// Display name.
    pub label: String,
    /// IANA timezone id, or the literal `local` for the system zone.
    pub timezone: String,
}

/// Weather settings. Data comes from Open-Meteo, which needs no API key.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct WeatherConfig {
    /// Place name, geocoded on startup when `latitude`/`longitude` are unset.
    pub location: String,
    /// Explicit latitude; skips geocoding.
    pub latitude: Option<f64>,
    /// Explicit longitude; skips geocoding.
    pub longitude: Option<f64>,
    /// `metric` (C, km/h) or `imperial` (F, mph).
    pub units: String,
    /// Forecast hours to show — a floor the panel is sized for, not a cap: a
    /// taller panel shows more, up to the 24 hours the fetch retrieves.
    pub forecast_hours: u8,
    /// Minutes between refreshes.
    pub refresh_minutes: u64,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for WeatherConfig {
    fn default() -> Self {
        Self {
            location: "Boston, Massachusetts".into(),
            latitude: None,
            longitude: None,
            units: "imperial".into(),
            forecast_hours: 8,
            refresh_minutes: 30,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

impl WeatherConfig {
    /// Every word `units` takes, spelt exactly so. The config and the state
    /// file are both checked against this one list, so a word added here is
    /// accepted from either.
    pub const UNITS: [&'static str; 2] = ["metric", "imperial"];
}

/// To-do list settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct TodoConfig {
    /// Path to the task file. `~` is expanded. Defaults to the data directory.
    pub file: Option<PathBuf>,
    /// Show completed tasks in the list.
    pub show_completed: bool,
    /// Initial sort: `smart`, `due`, `priority`, `created` or `title`.
    pub sort: String,
    /// Date format used in the list.
    pub date_format: String,
    /// Hide tasks whose due date is more than this many days out. 0 disables.
    pub horizon_days: u32,
    /// The list's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for TodoConfig {
    fn default() -> Self {
        Self {
            file: None,
            show_completed: false,
            sort: "smart".into(),
            date_format: "%a %d %b".into(),
            horizon_days: 0,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

/// Stock watchlist settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct StocksConfig {
    /// Symbols used to seed the watchlist on first run only. After that the
    /// watchlist file is the truth, so symbols added or removed in the UI stick.
    pub symbols: Vec<String>,
    /// Path to the watchlist file. `~` is expanded. Defaults to the data
    /// directory. Only symbols are stored; prices are never written to disk.
    pub file: Option<PathBuf>,
    /// Where quotes come from. See `[stocks].source` in the default config.
    pub source: String,
    /// Seconds between polls. Clamped to a minimum of 60: the sources are free
    /// and unauthenticated, and hammering them gets the address blocked.
    pub refresh_secs: u64,
    /// Milliseconds between individual symbol requests, so a watchlist goes out
    /// as a trickle rather than a burst.
    pub stagger_ms: u64,
    /// Draw the intraday sparkline when the panel is wide enough for it.
    pub show_sparkline: bool,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for StocksConfig {
    fn default() -> Self {
        Self {
            // The major US indexes first, then two ordinary stocks so the
            // panel shows both kinds on a first run. Kept identical to
            // `[stocks].symbols` in assets/default_config.toml.
            symbols: ["^GSPC", "^DJI", "^IXIC", "^RUT", "^NDX", "AAPL", "MSFT"]
                .iter()
                .map(|s| (*s).to_string())
                .collect(),
            file: None,
            source: "yahoo".to_string(),
            refresh_secs: 120,
            stagger_ms: 400,
            show_sparkline: true,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

/// Notes settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct NotesConfig {
    /// Path to the notes file. `~` is expanded. Defaults to the data directory.
    pub file: Option<PathBuf>,
    /// Date format used in the list.
    pub date_format: String,
    /// Where the note body sits: `below` the list, or `beside` it.
    ///
    /// Below by default. Beside splits a finite width between two things that
    /// both want it — the list loses room for titles and the body loses room
    /// for prose — where stacking gives each the full width and trades only
    /// height, which is the cheaper axis for both.
    pub preview: String,
    /// The list's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for NotesConfig {
    fn default() -> Self {
        Self {
            file: None,
            date_format: "%d %b".to_string(),
            preview: "below".to_string(),
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

impl NotesConfig {
    /// Every word `preview` takes, in any case, which is how the panel
    /// compares it.
    pub const PREVIEWS: [&'static str; 2] = ["below", "beside"];
}

/// Agenda settings: what is next, from a local `.ics` file.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct AgendaConfig {
    /// The `.ics` file to read. `~` is expanded.
    ///
    /// No default that guesses at a path. An agenda pointing somewhere the user
    /// did not choose is either empty, which looks broken, or somebody else's.
    pub file: Option<PathBuf>,
    /// How far ahead the window reaches, clamped to 1..=365. This one is a
    /// hard cutoff, not a floor: the parser never expands an event beyond it,
    /// so a taller panel shows the same window with less scrolling.
    pub days: u16,
    /// Show a location beside the summary, when the row has room for both.
    pub show_location: bool,
    /// Seconds between re-reads of the file.
    pub refresh_secs: u64,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for AgendaConfig {
    fn default() -> Self {
        Self {
            file: None,
            days: 7,
            show_location: true,
            // A local file, so this can be brisk: an export refreshed by cron
            // should appear without the user pressing anything, and a minute is
            // the granularity a calendar changes at anyway.
            refresh_secs: 60,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

/// Calendar settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct CalendarConfig {
    /// How many months across, starting with the current one — a floor, not a
    /// ceiling: a tall panel stacks further rows of months rather than leaving
    /// a void, up to twelve in view. Width the panel does not have comes off
    /// this count rather than truncating a grid.
    pub months: u8,
    /// `sunday` or `monday`.
    pub week_starts: String,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for CalendarConfig {
    fn default() -> Self {
        Self {
            months: 2,
            week_starts: "sunday".to_string(),
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

impl CalendarConfig {
    /// Every word `week_starts` takes, in any case, which is how the panel
    /// compares it.
    pub const WEEK_STARTS: [&'static str; 2] = ["sunday", "monday"];
}

/// Calculator settings.
///
/// Empty on purpose. Every key in this file is a promise that outlives the
/// release it ships in — removing or renaming one costs a major version now —
/// and no setting here has earned that yet. Thousands separators is the only
/// candidate, and it can wait until somebody asks. Adding a key later is not a
/// breaking change; taking one back is.
#[derive(Debug, Clone, Copy, Default, Deserialize, PartialEq, Eq)]
#[serde(default, deny_unknown_fields)]
pub struct CalculatorConfig {}

/// Pomodoro timer settings.
///
/// These are the *starting* values. `+` and `-` change the timer in the panel,
/// and those changes are remembered in the state file beside your tasks.
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
#[serde(default, deny_unknown_fields)]
pub struct PomodoroConfig {
    /// Length of a focus interval, in minutes.
    pub focus_minutes: u64,
    /// Length of the break after an ordinary focus interval.
    pub short_break_minutes: u64,
    /// Length of the break that closes a set.
    pub long_break_minutes: u64,
    /// Focus intervals per set, after which the long break falls due.
    pub rounds_before_long_break: u32,
    /// Begin the next phase the moment the current one ends, rather than
    /// waiting for a keypress.
    pub auto_start: bool,
    /// Sound a notification when a phase ends. Off by default: a dashboard you
    /// leave open all day has no business making noise you did not ask for.
    pub chime: bool,
    /// What to run for that notification, as a program and its arguments.
    ///
    /// Empty means the terminal bell, which costs nothing and lets your
    /// terminal and OS decide whether that is a sound, a flash, or nothing at
    /// all. Set it to play an actual file if you want a specific chime — see
    /// the commented examples in the default config.
    ///
    /// Run directly rather than through a shell, so there is no quoting to get
    /// wrong and no shell to inject into.
    pub chime_command: Vec<String>,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
    /// The three lengths above as `[pomodoro]` itself gives them — focus,
    /// short break, long break — kept by
    /// [`crate::config::Config::apply_state`] before a remembered length
    /// replaces them. Never read from the file.
    ///
    /// `+` climbs to [`crate::widgets::pomodoro::MAX_MINUTES`] or to the
    /// config's own length, whichever is longer, and the second needs this: a
    /// panel built from a remembered 239 cannot otherwise know the config says
    /// 240, so a phase shortened by one `-` could never be put back and the
    /// 239 would stay in the state file for ever (invariant 17). `None` when
    /// nothing has been laid over the config, and the panel reads the lengths
    /// it was built with.
    #[serde(skip)]
    pub as_configured: Option<[u64; 3]>,
}

impl Default for PomodoroConfig {
    fn default() -> Self {
        Self {
            focus_minutes: 25,
            short_break_minutes: 5,
            long_break_minutes: 15,
            rounds_before_long_break: 4,
            auto_start: false,
            chime: false,
            chime_command: Vec::new(),
            keys: crate::keymap::KeysConfig::default(),
            as_configured: None,
        }
    }
}

/// CPU chart settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct CpuConfig {
    /// Number of samples retained in the moving chart.
    pub history: usize,
    /// Seconds between samples.
    ///
    /// Two, not one. Since the redraw follows visible change rather than the
    /// tick, a fresh sample is a new number and every new number costs a
    /// repaint of the whole grid — so this panel and `network` set the floor on
    /// what an idle dashboard does.
    ///
    /// Measured at 400x100 on the default layout, redraws per idle minute:
    ///
    /// ```text
    ///                        sample_secs = 1    = 2
    ///   show_seconds = true          95          81
    ///   show_seconds = false         66          36
    /// ```
    ///
    /// The second row is the change; the first is what the clock costs. With
    /// seconds on, the clock alone asks for a repaint every second and swamps
    /// this, which is worth knowing before attributing an idle dashboard's cost
    /// to the graphs.
    ///
    /// It also buys a chart covering twice the wall-clock time for the same
    /// buffer — the span beside the figure is computed from the live sample
    /// count, so it says so.
    ///
    /// The cost is that the figure is a two-second average, so a brief spike
    /// reads slightly lower. Set it to 1 if you would rather watch it closely
    /// than leave it open all day; the floor is 1 either way.
    pub sample_secs: u64,
    /// Also draw a per-core breakdown when the panel is tall enough.
    pub show_per_core: bool,
    /// Accepted and not read. It promised a readout that turned the warning
    /// colour above this figure, and nothing ever did that: the readout takes
    /// its colour from the graph's ramp, so it warms with the load rather than
    /// switching at a line. Kept so a config that sets it still loads.
    pub warn_pct: f32,
    /// Accepted and not read, as `warn_pct` is, for the error colour.
    pub critical_pct: f32,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for CpuConfig {
    fn default() -> Self {
        Self {
            history: 120,
            sample_secs: 2,
            show_per_core: true,
            warn_pct: 70.0,
            critical_pct: 90.0,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

/// Memory chart settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct MemoryConfig {
    /// Number of samples retained in the moving chart — a floor, as for `cpu`.
    pub history: usize,
    /// Seconds between samples. See the note on `CpuConfig::sample_secs`.
    pub sample_secs: u64,
    /// Draw a swap row under the graph, when the machine has any.
    pub show_swap: bool,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for MemoryConfig {
    fn default() -> Self {
        Self {
            history: 120,
            sample_secs: 2,
            show_swap: true,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

/// Watch log settings. It has none of its own but its keys.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct WatchlogConfig {
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

/// Battery panel settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct BatteryConfig {
    /// Seconds between readings. A battery moves slowly; thirty is plenty.
    pub sample_secs: u64,
    /// Below this charge, running on the battery, the figure turns amber.
    pub warn_below_pct: u16,
    /// Below this charge, running on the battery, the figure turns red and the
    /// status bar carries an alert.
    pub alert_below_pct: u16,
}

impl Default for BatteryConfig {
    fn default() -> Self {
        Self {
            sample_secs: 30,
            warn_below_pct: 20,
            alert_below_pct: 10,
        }
    }
}

/// Temperature panel settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct TemperatureConfig {
    /// Samples to keep; a floor, since the buffer grows to the panel's width.
    pub history: usize,
    /// Seconds between readings.
    pub sample_secs: u64,
    /// `celsius` or `fahrenheit`; `u` toggles it in the panel.
    pub units: String,
    /// Above this, in Celsius, the hottest sensor is an alert. Zero disables.
    pub alert_above_c: u16,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for TemperatureConfig {
    fn default() -> Self {
        Self {
            history: 120,
            sample_secs: 5,
            units: "celsius".into(),
            alert_above_c: 95,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

impl TemperatureConfig {
    /// Every word `units` takes, spelt exactly so. The config and the state
    /// file are both checked against this one list, so a word added here is
    /// accepted from either.
    pub const UNITS: [&'static str; 2] = ["celsius", "fahrenheit"];
}

/// Disk panel settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct DiskConfig {
    /// Seconds between capacity readings. Disks fill by the hour; thirty is
    /// plenty, and each reading is a blocking call on a thread of its own.
    pub sample_secs: u64,
    /// Seconds between I/O readings, which feed the graphs.
    pub io_sample_secs: u64,
    /// Samples to keep per graph; a floor, since the buffer grows to the
    /// panel's width.
    pub history: usize,
    /// Draw the read and write graphs under each device. `i` toggles it.
    pub show_io: bool,
    /// At or above this percentage used, a volume's figures turn amber. Zero
    /// disables.
    pub warn_above_pct: u16,
    /// At or above this percentage used, a volume's figures turn red and the
    /// status bar says so. Zero disables.
    pub alert_above_pct: u16,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for DiskConfig {
    fn default() -> Self {
        Self {
            sample_secs: 30,
            io_sample_secs: 2,
            history: 120,
            show_io: true,
            warn_above_pct: 80,
            alert_above_pct: 95,
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}

/// Network chart settings.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct NetworkConfig {
    /// Interfaces to include. Empty means every non-loopback interface.
    pub interfaces: Vec<String>,
    /// Number of samples retained in the moving chart.
    pub history: usize,
    /// Seconds between samples. See [`CpuConfig::sample_secs`] for why it is 2.
    ///
    /// This one is also the more expensive of the pair: enumerating interfaces
    /// costs the better part of a millisecond a sample on macOS, against 60
    /// microseconds for reading CPU usage.
    pub sample_secs: u64,
}

impl Default for NetworkConfig {
    fn default() -> Self {
        Self {
            interfaces: Vec::new(),
            history: 120,
            sample_secs: 2,
        }
    }
}

/// A news feed the user subscribes to.
#[derive(Debug, Clone, Deserialize, Default)]
#[serde(default, deny_unknown_fields)]
pub struct NewsFeed {
    /// Shown above the headline, so `BBC WORLD` rather than the URL.
    pub name: String,
    pub url: String,
}

/// The news panel.
#[derive(Debug, Clone, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct NewsConfig {
    /// Feeds to read, in order. A topic *is* a feed here: RSS has no topic
    /// parameter, so subscribing to a science feed is how you ask for science.
    pub feeds: Vec<NewsFeed>,
    /// How often to re-read them. An hour is the floor as well as the default —
    /// news does not move faster than a dashboard should, and hammering
    /// somebody's feed from every mirador on earth would be rude.
    pub refresh_minutes: u64,
    /// Most stories to keep from any one feed, so a chatty outlet cannot crowd
    /// out a quiet one.
    pub per_feed: usize,
    /// What `Enter` runs on the selected story, with the link appended.
    ///
    /// **Empty by default, so mirador launches nothing it was not asked to.**
    /// The panel's own note is that no browser is opened for you — and the way
    /// that was settled for sound is the way it is settled here: mirador does
    /// not pick the program, you name it. Same shape as
    /// `[pomodoro].chime_command`, run directly rather than through a shell, so
    /// nothing in a URL can be taken as shell syntax.
    ///
    /// `["open"]` on macOS, `["xdg-open"]` on Linux,
    /// `["rundll32", "url.dll,FileProtocolHandler"]` on Windows — or name a
    /// specific browser. Never a shell: `cmd` and PowerShell read the link as
    /// a command line, and the news panel refuses to hand them one. Only
    /// `http` and `https` links are handed over, percent-encoded where needed.
    pub open_command: Vec<String>,
    /// The panel's keys, where the reader has moved them. See
    /// [`crate::keymap::PanelKeymap`].
    pub keys: crate::keymap::KeysConfig,
}

impl Default for NewsConfig {
    fn default() -> Self {
        let feed = |name: &str, url: &str| NewsFeed {
            name: name.into(),
            url: url.into(),
        };
        Self {
            // Science, space and technology only. Choosing outlets for general
            // or political news would be an editorial act this project has no
            // business making on somebody else's behalf — and the config is
            // commented so what you are subscribed to is never a mystery.
            feeds: vec![
                feed("NASA", "https://www.nasa.gov/news-release/feed/"),
                feed("PHYS.ORG", "https://phys.org/rss-feed/space-news/"),
                feed(
                    "ARS TECHNICA",
                    "https://feeds.arstechnica.com/arstechnica/index",
                ),
            ],
            refresh_minutes: 60,
            per_feed: 4,
            open_command: Vec::new(),
            keys: crate::keymap::KeysConfig::default(),
        }
    }
}