lingxia-surface 0.11.1

//! Surface node data model (§1.1 of the Adaptive Surface Layout spec).
//!
//! A `Surface` is one content unit in the graph. Its `role` expresses the
//! relationship to the main content; `content` is what it shows; `owner`
//! drives lifecycle; `placement` is a non-authoritative hint.

use serde::{Deserialize, Serialize};

/// Stable identifier of a surface within a graph.
pub type SurfaceId = String;

/// Relationship of a surface to the main content. The single core abstraction
/// behind every platform skin (window / panel / sheet / tab …).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Role {
    /// Switchable top-level content. Only one is the active `primary` at a time.
    Main,
    /// Companion shown beside the main content (split axis).
    Aside,
    /// Floats above, never occupies the main layout.
    Float,
}

/// Which edge a surface docks to (asides) or anchors from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Edge {
    Left,
    Right,
    Top,
    Bottom,
}

/// What a surface shows. Only two kinds: a declared catalog `entry`
/// (resolved by the host from `lingxia.toml`) or an ad-hoc `web` page.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "lowercase")]
pub enum SurfaceContent {
    /// A `lingxia.toml`-declared app / system feature, opened by id.
    Entry {
        id: String,
        /// Initial route only; subsequent navigation goes through `lx.navigator`.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        path: Option<String>,
    },
    /// An ad-hoc web page / PDF rendered by the in-app chromed browser. Whether
    /// it presents as a main browser tab or a docked browser aside is decided by
    /// `role`, not by the content — the browser always carries its own chrome.
    Web {
        url: String,
        /// Reopening the same URL normally focuses the existing browser aside.
        /// Callback surfaces opt out because their navigation and data-store
        /// policy must never inherit an ordinary tab's WebView.
        #[serde(
            default = "default_reuse_by_url",
            skip_serializing_if = "is_reuse_by_url"
        )]
        reuse_by_url: bool,
    },
}

const fn default_reuse_by_url() -> bool {
    true
}

fn is_reuse_by_url(value: &bool) -> bool {
    *value
}

/// Aside slot grouping: the aside area holds at most one region per render
/// engine — lxapp, browser, native — and multiple contents of one kind live
/// inside that region as tabs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum SlotKind {
    Lxapp,
    Browser,
    Native,
}

impl SurfaceContent {
    /// The aside slot this content belongs to. The built-in terminal is the
    /// only native capability today; native contents get a first-class marker
    /// when a second capability lands.
    pub fn slot_kind(&self) -> SlotKind {
        match self {
            SurfaceContent::Web { .. } => SlotKind::Browser,
            SurfaceContent::Entry { id, .. } if id == "terminal" => SlotKind::Native,
            SurfaceContent::Entry { .. } => SlotKind::Lxapp,
        }
    }
}

/// Owner scope: decides when the surface is closed (§5).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "scope", rename_all = "camelCase")]
pub enum SurfaceOwner {
    Page { page_instance_id: String },
    Lxapp { app_id: String },
    Host,
}

/// Placement hint (input). Authoritative layout is the `LayoutTree` (output).
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Placement {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub edge: Option<Edge>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub preferred_size: Option<f64>,
}

/// Runtime state of a surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum SurfaceState {
    Mounted,
    Hidden,
    Minimized,
}

/// How a `float` surface anchors.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "to", rename_all = "lowercase")]
pub enum FloatAnchor {
    Screen,
    Surface { surface_id: SurfaceId },
}

/// How a `float` surface is dismissed.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum FloatDismiss {
    TapOutside,
    Manual,
}

/// User interaction contract for a dynamically presented surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SurfaceInteraction {
    pub close_button: bool,
    pub dismiss: FloatDismiss,
    pub modal: bool,
}

impl SurfaceInteraction {
    pub const fn standard() -> Self {
        Self {
            close_button: false,
            dismiss: FloatDismiss::TapOutside,
            modal: false,
        }
    }

    pub const fn url_callback() -> Self {
        Self {
            close_button: true,
            dismiss: FloatDismiss::Manual,
            modal: true,
        }
    }

    pub const fn window() -> Self {
        Self {
            close_button: false,
            dismiss: FloatDismiss::Manual,
            modal: false,
        }
    }
}

impl Default for SurfaceInteraction {
    fn default() -> Self {
        Self::standard()
    }
}

/// Minimal semantics carried only by `float` surfaces (§1.1).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct FloatSpec {
    pub anchor: FloatAnchor,
    pub dismiss: FloatDismiss,
    /// Whether it blocks input to layers below (drives focus-restore, §1.5).
    pub modal: bool,
    /// Whether the platform renders the standard circular close control.
    pub close_button: bool,
}

impl Default for FloatSpec {
    fn default() -> Self {
        Self {
            anchor: FloatAnchor::Screen,
            dismiss: FloatDismiss::TapOutside,
            modal: false,
            close_button: false,
        }
    }
}

/// One node in the Surface Graph.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Surface {
    pub id: SurfaceId,
    pub role: Role,
    pub content: SurfaceContent,
    pub owner: SurfaceOwner,
    #[serde(default)]
    pub placement: Placement,
    pub state: SurfaceState,
    /// Present only for `role == Float`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub float: Option<FloatSpec>,
}

impl Surface {
    /// Convenience constructor for an entry-backed surface.
    pub fn entry(id: impl Into<SurfaceId>, role: Role, entry_id: impl Into<String>) -> Self {
        Self {
            id: id.into(),
            role,
            content: SurfaceContent::Entry {
                id: entry_id.into(),
                path: None,
            },
            owner: SurfaceOwner::Host,
            placement: Placement::default(),
            state: SurfaceState::Mounted,
            float: if role == Role::Float {
                Some(FloatSpec::default())
            } else {
                None
            },
        }
    }

    pub fn is_modal_float(&self) -> bool {
        self.role == Role::Float && self.float.as_ref().is_some_and(|f| f.modal)
    }
}