ferro_json_ui/

action.rs

//! Action declarations for JSON-UI components.
//!
//! Actions map user interactions (button clicks, form submissions) to
//! backend Ferro handlers. Each action references a handler in
//! `"controller.method"` format and can include confirmation dialogs
//! and outcome behaviors.
//!
//! Handler resolution accepts two shapes (Phase 165 — F14):
//!
//! - **Literal:** a plain string — `"users.store"` or `"/users"`.
//! - **Binding:** a `{"$data": "/path"}` map resolving to a string in
//!   `spec.data` at render time. Inside `$each` templates, paths that
//!   start with the loop variable (`/{as}/...`) are inlined to the row
//!   value during expansion — see `resolve.rs::expand_each`.

use std::collections::HashMap;

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use crate::component::Tone;
use crate::spec::DataRef;

/// HTTP method for action requests.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "UPPERCASE")]
pub enum HttpMethod {
    Get,
    #[default]
    Post,
    Put,
    Patch,
    Delete,
}

/// Confirmation dialog shown before executing an action. `tone: destructive`
/// styles the dialog for dangerous actions; `neutral` (default) is the plain
/// confirmation look.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct ConfirmDialog {
    pub title: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,
    #[serde(default)]
    pub tone: Tone,
    /// Captures unrecognised JSON keys so that Stage 2b can detect retired
    /// prop names (e.g. `variant`) via `serde_json::to_value` + walk.
    #[serde(flatten)]
    pub(crate) unknown_fields: HashMap<String, serde_json::Value>,
}

/// Default tone for `ActionOutcome::Notify` — an absent `tone` stays
/// success-colored (a notify outcome usually reports a successful action).
fn default_notify_tone() -> Tone {
    Tone::Success
}

/// Outcome after an action completes (success or error).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ActionOutcome {
    Redirect {
        url: String,
    },
    ShowErrors,
    Refresh,
    Notify {
        message: String,
        #[serde(default = "default_notify_tone")]
        tone: Tone,
    },
}

/// Handler reference for an [`Action`].
///
/// Accepts a literal string (handler name like `"users.store"` or absolute
/// path like `"/users"`) or a `{"$data": "/path"}` binding resolved against
/// `spec.data` at render time. The untagged enum keeps the wire format
/// backward-compatible — existing literal handlers parse via `Literal`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(untagged)]
pub enum ActionHandler {
    /// Handler name or literal URL. `"users.store"` is looked up via the
    /// resolver; `"/users"` is passed through as the resolved URL.
    Literal(String),
    /// `{"$data": "/path"}` binding. Resolved against `spec.data` in
    /// `resolve_actions`. The resolved string is then treated as a literal
    /// handler (resolver lookup or pass-through for `/path` URLs).
    Binding(DataRef),
}

impl ActionHandler {
    /// Return the literal string when this handler is unbound.
    ///
    /// Returns `None` for `Binding` — callers that need the literal must
    /// either run [`crate::resolve::resolve_actions`] first or branch on
    /// the variant explicitly.
    pub fn as_literal(&self) -> Option<&str> {
        match self {
            ActionHandler::Literal(s) => Some(s.as_str()),
            ActionHandler::Binding(_) => None,
        }
    }

    /// Return the underlying string regardless of variant.
    ///
    /// For `Literal`, this is the handler name or URL. For `Binding`, this
    /// is the binding's `$data` JSON-pointer path — useful for diagnostic
    /// rendering when the action has not been resolved.
    pub fn as_str(&self) -> &str {
        match self {
            ActionHandler::Literal(s) => s.as_str(),
            ActionHandler::Binding(d) => d.data.as_str(),
        }
    }
}

impl std::fmt::Display for ActionHandler {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

impl Default for ActionHandler {
    fn default() -> Self {
        ActionHandler::Literal(String::new())
    }
}

impl From<String> for ActionHandler {
    fn from(s: String) -> Self {
        ActionHandler::Literal(s)
    }
}

impl From<&str> for ActionHandler {
    fn from(s: &str) -> Self {
        ActionHandler::Literal(s.to_string())
    }
}

/// An action declaration mapping a user interaction to a backend handler.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct Action {
    /// Handler reference — literal `"controller.method"` / absolute `/path`,
    /// or a `{"$data": "/path"}` binding resolved at render time.
    pub handler: ActionHandler,
    /// Resolved URL for this action. Populated by the resolver at render time.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    #[serde(default)]
    pub method: HttpMethod,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub confirm: Option<ConfirmDialog>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_success: Option<ActionOutcome>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub on_error: Option<ActionOutcome>,
    /// Anchor target for navigation (GET) actions — e.g. "_blank" to open
    /// in a new tab. When set, `rel="noopener noreferrer"` is added.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub target: Option<String>,
}

impl Action {
    /// Create an action with Post method (the default for form submissions).
    pub fn new(handler: impl Into<ActionHandler>) -> Self {
        Self {
            handler: handler.into(),
            url: None,
            method: HttpMethod::Post,
            confirm: None,
            on_success: None,
            on_error: None,
            target: None,
        }
    }

    /// Create a navigation action with Get method.
    pub fn get(handler: impl Into<ActionHandler>) -> Self {
        Self {
            method: HttpMethod::Get,
            ..Self::new(handler)
        }
    }

    /// Create a deletion action with Delete method.
    pub fn delete(handler: impl Into<ActionHandler>) -> Self {
        Self {
            method: HttpMethod::Delete,
            ..Self::new(handler)
        }
    }

    /// Override the HTTP method.
    pub fn method(mut self, method: HttpMethod) -> Self {
        self.method = method;
        self
    }

    /// Add a neutral confirmation dialog.
    pub fn confirm(mut self, title: impl Into<String>) -> Self {
        self.confirm = Some(ConfirmDialog {
            title: title.into(),
            message: None,
            tone: Tone::Neutral,
            unknown_fields: Default::default(),
        });
        self
    }

    /// Add a destructive confirmation dialog.
    pub fn confirm_danger(mut self, title: impl Into<String>) -> Self {
        self.confirm = Some(ConfirmDialog {
            title: title.into(),
            message: None,
            tone: Tone::Destructive,
            unknown_fields: Default::default(),
        });
        self
    }

    /// Set the success outcome.
    pub fn on_success(mut self, outcome: ActionOutcome) -> Self {
        self.on_success = Some(outcome);
        self
    }

    /// Set the error outcome.
    pub fn on_error(mut self, outcome: ActionOutcome) -> Self {
        self.on_error = Some(outcome);
        self
    }
}

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

    #[test]
    fn minimal_action_serializes() {
        let action = Action {
            handler: ActionHandler::Literal("users.store".to_string()),
            url: None,
            method: HttpMethod::Post,
            confirm: None,
            on_success: None,
            on_error: None,
            target: None,
        };
        let json = serde_json::to_value(&action).unwrap();
        assert_eq!(json["handler"], "users.store");
        assert_eq!(json["method"], "POST");
        assert!(json.get("confirm").is_none());
        assert!(json.get("on_success").is_none());
    }

    #[test]
    fn action_with_confirm_dialog() {
        let action = Action {
            handler: ActionHandler::Literal("users.destroy".to_string()),
            url: None,
            method: HttpMethod::Delete,
            confirm: Some(ConfirmDialog {
                title: "Delete user?".to_string(),
                message: Some("This cannot be undone.".to_string()),
                tone: Tone::Destructive,
                unknown_fields: Default::default(),
            }),
            on_success: Some(ActionOutcome::Redirect {
                url: "/users".to_string(),
            }),
            on_error: Some(ActionOutcome::ShowErrors),
            target: None,
        };
        let json = serde_json::to_string(&action).unwrap();
        let parsed: Action = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, action);
    }

    #[test]
    fn action_outcome_variants_serialize() {
        let redirect = ActionOutcome::Redirect {
            url: "/dashboard".to_string(),
        };
        let json = serde_json::to_value(&redirect).unwrap();
        assert_eq!(json["type"], "redirect");
        assert_eq!(json["url"], "/dashboard");

        let show_errors = ActionOutcome::ShowErrors;
        let json = serde_json::to_value(&show_errors).unwrap();
        assert_eq!(json["type"], "show_errors");

        let refresh = ActionOutcome::Refresh;
        let json = serde_json::to_value(&refresh).unwrap();
        assert_eq!(json["type"], "refresh");

        let notify = ActionOutcome::Notify {
            message: "Saved!".to_string(),
            tone: Tone::Success,
        };
        let json = serde_json::to_value(&notify).unwrap();
        assert_eq!(json["type"], "notify");
        assert_eq!(json["message"], "Saved!");
        assert_eq!(json["tone"], "success");
    }

    #[test]
    fn http_method_defaults_to_post() {
        let json = r#"{"handler": "posts.store"}"#;
        let action: Action = serde_json::from_str(json).unwrap();
        assert_eq!(action.method, HttpMethod::Post);
    }

    #[test]
    fn dialog_tone_defaults_to_neutral() {
        let json = r#"{"title": "Confirm?"}"#;
        let dialog: ConfirmDialog = serde_json::from_str(json).unwrap();
        assert_eq!(dialog.tone, Tone::Neutral);
    }

    #[test]
    fn notify_without_tone_defaults_to_success() {
        // A notify outcome with no tone stays success-colored — the serde
        // default fn preserves the pre-251 NotifyVariant::Success default.
        let json = r#"{"type": "notify", "message": "Saved!"}"#;
        let outcome: ActionOutcome = serde_json::from_str(json).unwrap();
        match outcome {
            ActionOutcome::Notify { tone, .. } => assert_eq!(tone, Tone::Success),
            other => panic!("expected Notify, got: {other:?}"),
        }
    }

    #[test]
    fn notify_with_retired_tone_value_fails() {
        // 'info'/'error' were NotifyVariant values; the shared Tone rejects them.
        let json = r#"{"type": "notify", "message": "x", "tone": "info"}"#;
        assert!(serde_json::from_str::<ActionOutcome>(json).is_err());
        let json = r#"{"type": "notify", "message": "x", "tone": "error"}"#;
        assert!(serde_json::from_str::<ActionOutcome>(json).is_err());
    }

    #[test]
    fn action_without_url_omits_url_field() {
        let action = Action {
            handler: ActionHandler::Literal("users.index".to_string()),
            url: None,
            method: HttpMethod::Get,
            confirm: None,
            on_success: None,
            on_error: None,
            target: None,
        };
        let json = serde_json::to_value(&action).unwrap();
        assert!(json.get("url").is_none(), "url should be omitted when None");
    }

    #[test]
    fn action_with_url_includes_url_field() {
        let action = Action {
            handler: ActionHandler::Literal("users.store".to_string()),
            url: Some("/users".to_string()),
            method: HttpMethod::Post,
            confirm: None,
            on_success: None,
            on_error: None,
            target: None,
        };
        let json = serde_json::to_value(&action).unwrap();
        assert_eq!(json["url"], "/users");
    }

    #[test]
    fn action_url_round_trips() {
        let action = Action {
            handler: ActionHandler::Literal("users.show".to_string()),
            url: Some("/users/42".to_string()),
            method: HttpMethod::Get,
            confirm: None,
            on_success: None,
            on_error: None,
            target: None,
        };
        let json = serde_json::to_string(&action).unwrap();
        let parsed: Action = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed.url, Some("/users/42".to_string()));
        assert_eq!(parsed, action);
    }

    // ── Builder method tests ──────────────────────────────────────────

    #[test]
    fn builder_new_creates_post_action() {
        let action = Action::new("users.store");
        assert_eq!(action.handler.as_str(), "users.store");
        assert_eq!(action.method, HttpMethod::Post);
        assert_eq!(action.url, None);
        assert_eq!(action.confirm, None);
        assert_eq!(action.on_success, None);
        assert_eq!(action.on_error, None);
    }

    #[test]
    fn builder_get_creates_get_action() {
        let action = Action::get("users.index");
        assert_eq!(action.handler.as_str(), "users.index");
        assert_eq!(action.method, HttpMethod::Get);
    }

    #[test]
    fn builder_delete_creates_delete_action() {
        let action = Action::delete("users.destroy");
        assert_eq!(action.handler.as_str(), "users.destroy");
        assert_eq!(action.method, HttpMethod::Delete);
    }

    // ── F14: ActionHandler binding tests ───────────────────────────────

    #[test]
    fn action_handler_literal_round_trips_as_string() {
        let json = r#"{"handler":"users.store"}"#;
        let action: Action = serde_json::from_str(json).unwrap();
        assert!(matches!(action.handler, ActionHandler::Literal(ref s) if s == "users.store"));
        let back = serde_json::to_string(&action).unwrap();
        assert!(back.contains(r#""handler":"users.store""#));
    }

    #[test]
    fn action_handler_binding_parses_data_ref() {
        let json = r#"{"handler":{"$data":"/cell/action_url"}}"#;
        let action: Action = serde_json::from_str(json).unwrap();
        assert!(matches!(
            action.handler,
            ActionHandler::Binding(ref d) if d.data == "/cell/action_url"
        ));
    }

    #[test]
    fn action_handler_binding_round_trips_via_serde() {
        let json = r#"{"handler":{"$data":"/path"},"method":"GET"}"#;
        let parsed: Action = serde_json::from_str(json).unwrap();
        let back = serde_json::to_string(&parsed).unwrap();
        assert!(back.contains(r#""handler":{"$data":"/path"}"#));
    }

    #[test]
    fn action_handler_as_str_returns_binding_path() {
        let action: Action = serde_json::from_str(r#"{"handler":{"$data":"/foo"}}"#).unwrap();
        assert_eq!(action.handler.as_str(), "/foo");
        assert!(action.handler.as_literal().is_none());
    }

    #[test]
    fn action_handler_display_uses_underlying_string() {
        let lit = ActionHandler::Literal("users.show".to_string());
        let bind = ActionHandler::Binding(DataRef {
            data: "/x".to_string(),
        });
        assert_eq!(format!("{lit}"), "users.show");
        assert_eq!(format!("{bind}"), "/x");
    }

    #[test]
    fn builder_confirm_adds_neutral_dialog() {
        let action = Action::new("users.store").confirm("Save changes?");
        let dialog = action.confirm.unwrap();
        assert_eq!(dialog.title, "Save changes?");
        assert_eq!(dialog.tone, Tone::Neutral);
        assert_eq!(dialog.message, None);
    }

    #[test]
    fn builder_confirm_danger_adds_destructive_dialog() {
        let action = Action::delete("users.destroy").confirm_danger("Delete user?");
        let dialog = action.confirm.unwrap();
        assert_eq!(dialog.title, "Delete user?");
        assert_eq!(dialog.tone, Tone::Destructive);
    }

    #[test]
    fn builder_on_success_sets_outcome() {
        let action = Action::new("users.store").on_success(ActionOutcome::Refresh);
        assert_eq!(action.on_success, Some(ActionOutcome::Refresh));
    }

    #[test]
    fn builder_on_error_sets_outcome() {
        let action = Action::new("users.store").on_error(ActionOutcome::ShowErrors);
        assert_eq!(action.on_error, Some(ActionOutcome::ShowErrors));
    }

    #[test]
    fn builder_chain_produces_expected_json() {
        let action = Action::delete("users.destroy")
            .confirm_danger("Delete user?")
            .on_success(ActionOutcome::Refresh);

        let json = serde_json::to_value(&action).unwrap();
        assert_eq!(json["handler"], "users.destroy");
        assert_eq!(json["method"], "DELETE");
        assert_eq!(json["confirm"]["title"], "Delete user?");
        assert_eq!(json["confirm"]["tone"], "destructive");
        assert_eq!(json["on_success"]["type"], "refresh");
    }

    #[test]
    fn builder_method_overrides() {
        let action = Action::new("users.update").method(HttpMethod::Put);
        assert_eq!(action.method, HttpMethod::Put);
    }

    /// ConfirmDialog and Notify share the canonical `Tone` — the strum↔serde
    /// wire-format guard for `Tone` lives in `component.rs::strum_tests`.
    /// Here we pin the action-level wire strings on the two dialog tones.
    #[test]
    fn confirm_dialog_tone_wire_format() {
        let neutral = ConfirmDialog {
            title: "t".into(),
            message: None,
            tone: Tone::Neutral,
            unknown_fields: Default::default(),
        };
        let destructive = ConfirmDialog {
            title: "t".into(),
            message: None,
            tone: Tone::Destructive,
            unknown_fields: Default::default(),
        };
        assert_eq!(serde_json::to_value(&neutral).unwrap()["tone"], "neutral");
        assert_eq!(
            serde_json::to_value(&destructive).unwrap()["tone"],
            "destructive"
        );
    }
}