supreme_hook_config/

ui.rs

//! The optional `ui` section of a mod's `mod.json`, the launcher-UI
//! schema the Mods page renders generically: buttons shown for the mod,
//! and the popups those buttons open. See
//! [`crate::mod_config::ModConfig::ui`], which holds this as an
//! [`Option`], a mod without a `ui` section (e.g. the existing
//! practice-as-race mod) stays fully valid and simply gets no buttons.
//!
//! Wire shape (per the tournament design contract):
//!
//! ```json
//! "ui": { "buttons": [ { "id": "create_room", "label": "Create",
//!                        "action": "tournament.create", "popup": "create_room" } ],
//!         "popups": { "create_room": { "title": "Create Tournament Room",
//!                                      "kind": "form", "fields": [ ... ] } } }
//! ```
//!
//! Design notes:
//! - **Parse liberally, validate strictly.** Every field has a serde
//!   default, so a partial `ui` section (buttons without popups, a popup
//!   without fields, …) still *parses*; structural problems surface as
//!   per-mod validation errors from [`ModUi::validate`], collected by
//!   [`crate::mod_config::ModConfig::validate`] exactly like parameter
//!   and rule problems, a broken mod shows up in the launcher's mod list
//!   as broken rather than failing to parse outright.
//! - **Forward compatible.** Unknown extra keys are ignored by serde (and
//!   reported as non-fatal warnings by
//!   [`crate::mod_config::ModConfig::load_from_path_with_warnings`]).
//!   Unknown *kind* strings (e.g. a `"kind": "datepicker"` field written
//!   by a newer launcher) round-trip through the [`UiFieldKind::Unknown`]
//!   / [`UiPopupKind::Unknown`] catch-all variants instead of failing to
//!   parse, and are then rejected by [`ModUi::validate`] with a clear
//!   message, same mechanism, at the right layer.
//! - `button.label` is displayed verbatim; `{placeholder}` tokens inside
//!   it (e.g. `"Join ({room_count})"`) are filled in live by the launcher
//!   (from its current `room_list` response), never interpolated here.
//! - `button.action` strings in the `tournament.*` namespace are
//!   handled by launcher logic; other actions are free-form for future
//!   use. This crate stores them opaquely.

use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

/// A mod's authored launcher-UI schema: which buttons to show for the
/// mod, and which popups they open. `popups` is a map keyed by popup id
/// so buttons can reference popups by name, and validation can catch a
/// button pointing at a popup that doesn't exist
/// (see [`ModUi::validate`]).
#[derive(Serialize, Deserialize, Debug, Clone, Default, PartialEq)]
pub struct ModUi {
    /// Buttons rendered for this mod, in authored order.
    #[serde(default)]
    pub buttons: Vec<UiButton>,
    /// Popups buttons can open, keyed by popup id. May be empty even
    /// when buttons exist (e.g. action-only buttons that don't open a
    /// popup).
    #[serde(default)]
    pub popups: BTreeMap<String, UiPopup>,
}

impl ModUi {
    /// Structural validation of the whole `ui` section:
    ///
    /// - button ids must be unique and non-empty;
    /// - every button's `action` must be non-empty;
    /// - every button's `popup` reference (if any) must name an entry in
    ///   [`ModUi::popups`], no dangling refs;
    /// - a `select` field must offer at least one option;
    /// - unknown popup/field kind strings are rejected (they parse via
    ///   the `Unknown` catch-alls precisely so this check can describe
    ///   them instead of a raw serde error).
    ///
    /// # Errors
    ///
    /// Returns every problem found (not just the first), matching
    /// [`crate::mod_config::ModConfig::validate`]'s collect-everything
    /// convention.
    pub fn validate(&self) -> Result<(), Vec<String>> {
        let mut errors = Vec::new();

        let mut seen_button_ids = std::collections::HashSet::new();
        for (index, button) in self.buttons.iter().enumerate() {
            if button.id.trim().is_empty() {
                errors.push(format!("ui: buttons[{index}] has an empty id"));
            } else if !seen_button_ids.insert(button.id.as_str()) {
                errors.push(format!(
                    "ui: duplicate button id `{}`; every button id must be unique",
                    button.id
                ));
            }

            if button.action.trim().is_empty() {
                errors.push(format!("ui: button `{}` has an empty action", button.id));
            }

            if let Some(popup) = &button.popup
                && !self.popups.contains_key(popup)
            {
                errors.push(format!(
                    "ui: button `{}` references popup `{popup}`, which is not defined in `popups`",
                    button.id
                ));
            }
        }

        for (popup_id, popup) in &self.popups {
            if let UiPopupKind::Unknown(kind) = &popup.kind {
                errors.push(format!(
                    "ui: popup `{popup_id}` has unknown kind `{kind}` (expected `form` or `room_list`)"
                ));
            }

            for (index, field) in popup.fields.iter().enumerate() {
                if let UiFieldKind::Unknown(kind) = &field.kind {
                    errors.push(format!(
                        "ui: popup `{popup_id}` fields[{index}] has unknown kind `{kind}` \
                         (expected `text`, `select`, `number`, `duration`, or `datetime`)"
                    ));
                }

                if field.kind == UiFieldKind::Select && field.options.is_empty() {
                    errors.push(format!(
                        "ui: popup `{popup_id}` select field `{}` needs at least one option",
                        field.id
                    ));
                }

                if let Some(tag) = &field.validation {
                    if !crate::validation::is_known_tag(tag) {
                        errors.push(format!(
                            "ui: popup `{popup_id}` field `{}` has unknown validation tag \
                             `{tag}` (expected one of: {})",
                            field.id,
                            crate::validation::KNOWN_TAGS.join(", ")
                        ));
                    } else if field.kind != UiFieldKind::Text {
                        errors.push(format!(
                            "ui: popup `{popup_id}` field `{}` carries a validation tag, \
                             which only text fields enforce",
                            field.id
                        ));
                    }
                }
            }
        }

        if errors.is_empty() {
            Ok(())
        } else {
            Err(errors)
        }
    }
}

/// One button rendered for a mod on the Mods page. Clicking it performs
/// `action` (launcher-handled, e.g. `tournament.create`), optionally
/// opening the popup named by `popup` first to collect input.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct UiButton {
    /// Stable identifier for this button within the mod's `ui` section.
    /// Must be unique, see [`ModUi::validate`].
    #[serde(default)]
    pub id: String,
    /// Button caption. May contain `{placeholder}` tokens the launcher
    /// fills in live (e.g. `"Join ({room_count})"`); stored verbatim.
    #[serde(default)]
    pub label: String,
    /// Launcher-handled action name (e.g. `tournament.create`). Must
    /// be non-empty, see [`ModUi::validate`].
    #[serde(default)]
    pub action: String,
    /// Optional popup id (a key into [`ModUi::popups`]) opened when the
    /// button is pressed, to collect input before the action runs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub popup: Option<String>,
}

/// One popup a [`UiButton`] can open: a titled window that is either an
/// input form ([`UiPopupKind::Form`]) or a live room list
/// ([`UiPopupKind::RoomList`]).
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct UiPopup {
    /// Window title.
    #[serde(default)]
    pub title: String,
    /// What kind of popup this is, defaults to [`UiPopupKind::Form`]
    /// when omitted, since a fields-only popup (the common shape) is a
    /// form.
    #[serde(default)]
    pub kind: UiPopupKind,
    /// Input fields, meaningful for [`UiPopupKind::Form`] popups;
    /// empty for [`UiPopupKind::RoomList`] popups (their content comes
    /// from the launcher's live room data, not the mod's authoring).
    #[serde(default)]
    pub fields: Vec<UiField>,
}

/// What kind of popup a [`UiPopup`] is. Unknown kind strings from a
/// newer launcher round-trip through [`UiPopupKind::Unknown`] so they
/// fail *validation* (with the raw string in the message) instead of
/// failing to parse.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub enum UiPopupKind {
    /// An input form built from [`UiPopup::fields`].
    #[default]
    Form,
    /// A live list of joinable rooms fetched by the launcher.
    RoomList,
    /// A kind string this launcher version doesn't know, always
    /// rejected by [`ModUi::validate`].
    Unknown(String),
}

impl UiPopupKind {
    /// The wire string this kind serializes to, the known kinds' snake
    /// case names, or the raw unknown string verbatim.
    #[must_use]
    pub fn as_str(&self) -> &str {
        match self {
            Self::Form => "form",
            Self::RoomList => "room_list",
            Self::Unknown(kind) => kind.as_str(),
        }
    }
}

impl Serialize for UiPopupKind {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for UiPopupKind {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let kind = String::deserialize(deserializer)?;
        Ok(match kind.as_str() {
            "form" => Self::Form,
            "room_list" => Self::RoomList,
            other => Self::Unknown(other.to_string()),
        })
    }
}

/// One input field inside a [`UiPopupKind::Form`] popup.
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub struct UiField {
    /// Stable identifier for the collected value (what the launcher
    /// hands to the button's `action` handling).
    #[serde(default)]
    pub id: String,
    /// What kind of control to render, defaults to
    /// [`UiFieldKind::Text`] when omitted.
    #[serde(default)]
    pub kind: UiFieldKind,
    /// Human-readable label shown next to the control.
    #[serde(default)]
    pub label: String,
    /// Choices for [`UiFieldKind::Select`] fields; empty for every
    /// other kind (and required non-empty for selects, see
    /// [`ModUi::validate`]).
    #[serde(default)]
    pub options: Vec<String>,
    /// short hint text rendered inside the control itself (egui's
    /// `hint_text` on text fields), the "(optional)" style note a mod can
    /// attach without bloating the label. `None` = no hint.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hint: Option<String>,
    /// Optional name of a shared validation rule set (see
    /// [`crate::validation`]) the launcher enforces live on this field:
    /// invalid input renders an error stroke and a warning icon whose
    /// hover carries the reason, and the popup's confirm button stays
    /// disabled while the value is invalid. Known tags: `player_name`,
    /// `room_name`; unknown tags fail [`ModUi::validate`] so a newer mod
    /// on an older launcher reports itself. Only meaningful on text
    /// fields.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub validation: Option<String>,
}

/// What kind of control a [`UiField`] renders. Unknown kind strings
/// round-trip through [`UiFieldKind::Unknown`] so they fail *validation*
/// (with the raw string in the message) instead of failing to parse.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub enum UiFieldKind {
    /// Free-text input.
    #[default]
    Text,
    /// A choice among [`UiField::options`], must be non-empty.
    Select,
    /// Numeric input.
    Number,
    /// A duration picker (values like `"1h"`, `"6h"`, `"24h"`).
    Duration,
    /// A date+time picker (room planning windows). The collected
    /// value is a UTC epoch-seconds string; the launcher renders it with
    /// egui's `DatePickerButton` plus hour/minute steppers. Defaults (now /
    /// tomorrow) are applied by the launcher when the popup opens.
    DateTime,
    /// A kind string this launcher version doesn't know, always
    /// rejected by [`ModUi::validate`].
    Unknown(String),
}

impl UiFieldKind {
    /// The wire string this kind serializes to, the known kinds' snake
    /// case names, or the raw unknown string verbatim.
    #[must_use]
    pub fn as_str(&self) -> &str {
        match self {
            Self::Text => "text",
            Self::Select => "select",
            Self::Number => "number",
            Self::Duration => "duration",
            Self::DateTime => "datetime",
            Self::Unknown(kind) => kind.as_str(),
        }
    }
}

impl Serialize for UiFieldKind {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for UiFieldKind {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let kind = String::deserialize(deserializer)?;
        Ok(match kind.as_str() {
            "text" => Self::Text,
            "select" => Self::Select,
            "number" => Self::Number,
            "duration" => Self::Duration,
            "datetime" => Self::DateTime,
            other => Self::Unknown(other.to_string()),
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn empty_ui_validates() {
        assert!(ModUi::default().validate().is_ok());
    }

    #[test]
    fn unknown_kinds_serialize_round_trip_verbatim() {
        let ui: ModUi = serde_json::from_str(
            r#"{"buttons":[],"popups":{"p":{"title":"t","kind":"calendar",
               "fields":[{"id":"f","kind":"datepicker","label":"l"}]}}}"#,
        )
        .unwrap();
        assert_eq!(ui.popups["p"].kind, UiPopupKind::Unknown("calendar".into()));
        assert_eq!(
            ui.popups["p"].fields[0].kind,
            UiFieldKind::Unknown("datepicker".into())
        );

        let json = serde_json::to_string(&ui).unwrap();
        assert!(json.contains(r#""kind":"calendar""#));
        assert!(json.contains(r#""kind":"datepicker""#));
    }

    #[test]
    fn field_kind_defaults_to_text_when_omitted() {
        let field: UiField = serde_json::from_str(r#"{"id":"x","label":"X"}"#).unwrap();
        assert_eq!(field.kind, UiFieldKind::Text);
    }

    #[test]
    fn field_hint_parses_and_round_trips() {
        // the hint is optional, survives the round trip, and is
        // OMITTED from the serialization when absent (mod.jsons written by
        // older launchers stay byte-stable apart from the new field).
        let field: UiField =
            serde_json::from_str(r#"{"id":"name","label":"Room name","hint":"(optional)"}"#)
                .unwrap();
        assert_eq!(field.hint.as_deref(), Some("(optional)"));

        let bare: UiField = serde_json::from_str(r#"{"id":"x","label":"X"}"#).unwrap();
        assert_eq!(bare.hint, None);
        assert!(!serde_json::to_string(&bare).unwrap().contains("hint"));

        let hinted = serde_json::to_string(&field).unwrap();
        assert!(hinted.contains(r#""hint":"(optional)""#));
    }

    #[test]
    fn popup_kind_defaults_to_form_when_omitted() {
        let popup: UiPopup = serde_json::from_str(r#"{"title":"t","fields":[]}"#).unwrap();
        assert_eq!(popup.kind, UiPopupKind::Form);
    }

    #[test]
    fn field_validation_tag_round_trips_and_unknown_tags_are_rejected() {
        // The tag is optional, survives the round trip, and is OMITTED
        // from the serialization when absent (mod.jsons written by older
        // launchers stay byte-stable apart from the new key).
        let bare: UiField = serde_json::from_str(r#"{"id":"x","label":"X"}"#).unwrap();
        assert_eq!(bare.validation, None);
        assert!(!serde_json::to_string(&bare).unwrap().contains("validation"));

        let tagged: UiField =
            serde_json::from_str(r#"{"id":"name","label":"Room name","validation":"room_name"}"#)
                .unwrap();
        assert_eq!(tagged.validation.as_deref(), Some("room_name"));
        assert!(
            serde_json::to_string(&tagged)
                .unwrap()
                .contains(r#""validation":"room_name""#)
        );

        // Unknown tags parse but fail validation, naming the tag.
        let ui: ModUi = serde_json::from_str(
            r#"{"buttons":[],"popups":{"p":{"title":"t",
               "fields":[{"id":"f","kind":"text","label":"l","validation":"numeric"}]}}}"#,
        )
        .unwrap();
        let errors = ui.validate().unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("unknown validation tag `numeric`")),
            "errors: {errors:?}"
        );

        // A tag on a non-text field is meaningless, rejected too.
        let ui: ModUi = serde_json::from_str(
            r#"{"buttons":[],"popups":{"p":{"title":"t",
               "fields":[{"id":"f","kind":"number","label":"l","validation":"room_name"}]}}}"#,
        )
        .unwrap();
        let errors = ui.validate().unwrap_err();
        assert!(
            errors
                .iter()
                .any(|e| e.contains("only text fields enforce")),
            "errors: {errors:?}"
        );
    }
}