mtk-rs 0.1.0-beta.3

//! Declarative, reactive view hierarchy and event dispatch system for MTK.
//!
//! This module defines the core [`View`] trait, [`ViewSequence`] container composition,
//! state lenses, adapters, and input events ([`Event`]) used to compose user interfaces.

use crate::{Context, Node, ui::event::EventResult, windowing::WindowDimension};

pub mod adapter;
pub mod boxed;
pub mod either;
pub mod event;
pub mod focus;
pub mod keyed;
pub mod kinetic;
pub mod layer;
pub mod lens;
pub mod memoize;
pub mod morph;
pub mod presence;
pub mod router;
pub mod style;
pub mod transition;
pub mod widgets;

pub use crate::switch;
pub use adapter::{ViewAdaptExt, adapt};
pub use boxed::{BoxedElement, BoxedView, BoxedViewExt, boxed};
pub use either::{Either, ViewEitherExt, either};
pub use event::{
    DragContext, DragElement, DragHandler, DragPhase, EventKind, KeyActionKind, KeyEventContext,
    KeyHandler, KeyScope, ScrollContext, ScrollHandler, ScrollSource, ThumbScrollContext,
    ThumbScrollHandler, TickHandler, ViewEventExt,
};
pub use focus::{Focusable, FocusableExt};
pub use keyed::{Keyed, KeyedViewSequence, keyed, keyed_sequence};
pub use kinetic::KineticTracker;
pub use layer::{Layer, ViewLayerExt, layer};
pub use lens::Lens;
pub use morph::{MorphId, MorphTransition, MorphViewExt, Morphable, morphable};
pub use presence::{Presence, PresenceViewExt, presence};
pub use router::{Router, router};
pub use style::ViewStyleExt;
pub use transition::{Motion, MotionOffset, PageTransition, Transition, TransitionOrder};

/// Represents user interaction, layout lifecycle, and system input events dispatched down the view tree.
#[derive(Clone, Debug)]
pub enum Event {
    /// Dispatched when the mouse cursor moves across the viewport.
    CursorMoved {
        /// Absolute horizontal pixel position.
        x: f32,
        /// Absolute vertical pixel position.
        y: f32,
        /// Incremental horizontal pixel displacement since previous move.
        delta_x: f32,
        /// Incremental vertical pixel displacement since previous move.
        delta_y: f32,
        /// Ordered list of layout nodes hit-tested under the cursor.
        hit_nodes: Vec<Node>,
    },
    /// Dispatched when a mouse button press or release action occurs.
    MouseInput {
        /// Mouse button associated with this input event.
        button: winit::event::MouseButton,
        /// `true` if button was pressed down; `false` if released.
        pressed: bool,
        /// Absolute horizontal pixel position.
        x: f32,
        /// Absolute vertical pixel position.
        y: f32,
        /// Ordered list of layout nodes hit-tested under the cursor.
        hit_nodes: Vec<Node>,
    },
    /// Dispatched when a graphics tablet stylus interaction occurs (pressure, tilt, tool proximity).
    StylusInput {
        /// Absolute horizontal pixel position.
        x: f32,
        /// Absolute vertical pixel position.
        y: f32,
        /// Normalized pressure (0.0 to 1.0).
        pressure: f32,
        /// 2-axis tilt in degrees (x, y), if supported by hardware.
        tilt: Option<(f32, f32)>,
        /// `true` if the tool is an eraser.
        is_eraser: bool,
        /// `true` if tool tip is in contact with the tablet surface.
        pressed: bool,
        /// Ordered list of layout nodes hit-tested under the stylus.
        hit_nodes: Vec<Node>,
    },
    /// Dispatched when mouse scroll wheel or touchpad scroll gestures are detected.
    MouseWheel {
        /// Horizontal scroll displacement.
        delta_x: f32,
        /// Vertical scroll displacement.
        delta_y: f32,
        /// `true` if scrolling originated from a continuous touchpad surface.
        is_touchpad: bool,
        /// Touch phase state associated with gesture scrolling.
        phase: winit::event::TouchPhase,
        /// Ordered list of layout nodes hit-tested under the cursor.
        hit_nodes: Vec<Node>,
    },
    /// Dispatched when a physical or virtual keyboard key is pressed or released.
    KeyboardInput {
        /// Key event payload.
        event: KeyEvent,
        /// `true` if generated synthetically by MTK event repeat logic.
        is_synthetic: bool,
    },
    /// Dispatched when an OS Input Method Editor (IME) updates preedit or commits text.
    Ime(winit::event::Ime),
    /// Dispatched once per frame tick to drive animations and physics interpolation.
    Tick {
        /// Elapsed time delta in seconds since the previous frame tick.
        dt: f32,
    },
    /// Dispatched when the parent application window size changes.
    WindowResized(WindowDimension),
    /// Dispatched when a scrollbar thumb is dragged or scrubbed.
    ThumbScroll {
        /// The scroll container node whose thumb moved.
        node: Node,
        /// Geometry and state of the thumb.
        context: ThumbScrollContext,
    },
    /// Dispatched when a scrollable container view is scrolled via mouse wheel, touchpad gesture, scrollbar thumb, or kinetic decay.
    Scroll {
        /// The scroll container node whose scroll offset changed.
        node: Node,
        /// Contextual layout metrics, scroll percentages, deltas, and origin source.
        context: ScrollContext,
    },
    /// Dispatched when a previously focused node loses focus (e.g. on click outside or blur).
    FocusLost {
        /// The node that lost focus.
        node: Node,
    },
    /// Dispatched when an OS assistive technology (screen reader / accessibility client) requests an action.
    Action {
        /// The target layout node of the action.
        node: Node,
        /// The accessibility action requested.
        action: accesskit::Action,
        /// Optional action data payload (e.g. string value for SetValue).
        data: Option<accesskit::ActionData>,
    },
}

/// Describes a keyboard input targeting a window or UI node.
#[derive(Debug, Clone, Eq, PartialEq, Hash)]
pub struct KeyEvent {
    /// Position of the key independent of active keyboard layout (scancode).
    pub physical_key: winit::keyboard::PhysicalKey,
    /// Resolved logical representation of the key.
    pub logical_key: winit::keyboard::Key,
    /// UTF-8 text generated by this keypress, if any.
    pub text: Option<winit::keyboard::SmolStr>,
    /// Location of this key on the keyboard.
    pub location: winit::keyboard::KeyLocation,
    /// Key state: pressed or released.
    pub state: winit::event::ElementState,
    /// Whether this is an OS key repeat event.
    pub repeat: bool,
}

impl KeyEvent {
    /// Creates a new `KeyEvent` with standard defaults for location and repeat.
    pub fn new(logical_key: winit::keyboard::Key, state: winit::event::ElementState) -> Self {
        Self {
            physical_key: winit::keyboard::PhysicalKey::Unidentified(
                winit::keyboard::NativeKeyCode::Unidentified,
            ),
            logical_key,
            text: None,
            location: winit::keyboard::KeyLocation::Standard,
            state,
            repeat: false,
        }
    }
}

impl From<winit::event::KeyEvent> for KeyEvent {
    fn from(ev: winit::event::KeyEvent) -> Self {
        Self {
            physical_key: ev.physical_key,
            logical_key: ev.logical_key,
            text: ev.text,
            location: ev.location,
            state: ev.state,
            repeat: ev.repeat,
        }
    }
}

/// The foundational trait for all declarative, reactive UI components in MTK.
///
/// A `View` represents a lightweight blueprint for constructing and updating underlying
/// layout nodes ([`Node`]) bound to an application state (`State`).
pub trait View<State> {
    /// The persistent DOM-like element state maintained between render frames.
    type Element;
    /// The message type emitted by this view upon user interaction.
    type Message;

    /// Instantiates initial layout nodes and state primitives for this view.
    fn build(&self, ctx: &mut Context) -> Self::Element;

    /// Diffs and updates persistent element nodes when application state or properties change.
    fn rebuild(&self, prev: &Self, ctx: &mut Context, element: &mut Self::Element);

    /// Diffs and updates persistent element nodes, providing access to the parent container node for insertion.
    fn rebuild_with_parent(
        &self,
        prev: &Self,
        ctx: &mut Context,
        element: &mut Self::Element,
        _parent: Node,
        _next_sibling: Option<Node>,
    ) {
        self.rebuild(prev, ctx, element);
    }

    /// Destroys persistent layout nodes and frees resources associated with `element`.
    fn teardown(&self, ctx: &mut Context, element: &mut Self::Element);

    /// Returns the root layout node handle representing this view.
    fn get_node(&self, element: &Self::Element) -> Node;

    /// Handles incoming user interaction events, returning event consumption status and optional domain messages.
    fn handle_event(
        &self,
        element: &mut Self::Element,
        state: &State,
        event: Event,
        ctx: &mut Context,
    ) -> (EventResult, Option<Self::Message>);
}

/// Defines container composition for sequential views, such as tuples `(ViewA, ViewB)` or `Vec<V>`.
pub trait ViewSequence<State> {
    /// The persistent element tuple or collection corresponding to child views.
    type Elements;
    /// The common message type emitted by child views in this sequence.
    type Message;

    /// Instantiates initial layout nodes for all items in the sequence and appends them to `parent`.
    fn build(&self, ctx: &mut Context, parent: Node) -> Self::Elements;

    /// Diffs and updates layout nodes for all items in the sequence.
    fn rebuild(&self, prev: &Self, ctx: &mut Context, elements: &mut Self::Elements, parent: Node);

    /// Destroys layout nodes and cleans up resources for all items in the sequence.
    fn teardown(&self, ctx: &mut Context, elements: &mut Self::Elements);

    /// Routes events through items in the sequence sequentially until consumed.
    fn handle_event(
        &self,
        elements: &mut Self::Elements,
        state: &State,
        event: Event,
        ctx: &mut Context,
    ) -> (EventResult, Option<Self::Message>);
}

macro_rules! impl_view_tuple {
    ( $($idx:tt => $t:ident),* ) => {
        impl<State, Msg, $($t),*> ViewSequence<State> for ($($t,)*)
        where
            $($t: View<State, Message = Msg>),*
        {
            type Elements = ($($t::Element,)*);
            type Message = Msg;

            fn build(&self, ctx: &mut Context, parent: Node) -> Self::Elements {
                (
                    $({
                        let child_element = self.$idx.build(ctx);
                        parent.append(ctx, self.$idx.get_node(&child_element));
                        child_element
                    },)*
                )
            }

            fn rebuild(&self, prev: &Self, ctx: &mut Context, elements: &mut Self::Elements, parent: Node) {
                let mut nodes = [
                    $(self.$idx.get_node(&elements.$idx),)*
                ];

                #[allow(unused_assignments)]
                {
                    $(
                        let next_sibling = nodes[($idx + 1)..].iter().copied().find(|n| n.is_valid());
                        self.$idx.rebuild_with_parent(&prev.$idx, ctx, &mut elements.$idx, parent, next_sibling);
                        nodes[$idx] = self.$idx.get_node(&elements.$idx);
                    )*
                }
            }

            fn teardown(&self, ctx: &mut Context, elements: &mut Self::Elements) {
                $(
                    self.$idx.teardown(ctx, &mut elements.$idx);
                )*
            }

            fn handle_event(
                &self,
                elements: &mut Self::Elements,
                state: &State,
                event: Event,
                ctx: &mut Context,
            ) -> (EventResult, Option<Self::Message>) {
                let is_tick = matches!(event, Event::Tick { .. });
                let mut handled = EventResult::Ignored;
                let mut emitted_msg = None;

                $(
                    if (is_tick || handled == EventResult::Ignored) && emitted_msg.is_none() {
                        let (res, msg) = self.$idx.handle_event(
                            &mut elements.$idx,
                            state,
                            event.clone(),
                            ctx
                        );
                        handled = handled.or(res);
                        if msg.is_some() {
                            emitted_msg = msg;
                        }
                    }
                )*

                (handled, emitted_msg)
            }
        }
    };
}

// Generate implementations for tuples up to 10 elements
impl_view_tuple!(0 => A);
impl_view_tuple!(0 => A, 1 => B);
impl_view_tuple!(0 => A, 1 => B, 2 => C);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E, 5 => F);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E, 5 => F, 6 => G);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E, 5 => F, 6 => G, 7 => H);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E, 5 => F, 6 => G, 7 => H, 8 => I);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E, 5 => F, 6 => G, 7 => H, 8 => I, 9 => J);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E, 5 => F, 6 => G, 7 => H, 8 => I, 9 => J, 10 => K);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E, 5 => F, 6 => G, 7 => H, 8 => I, 9 => J, 10 => K, 11 => L);
impl_view_tuple!(0 => A, 1 => B, 2 => C, 3 => D, 4 => E, 5 => F, 6 => G, 7 => H, 8 => I, 9 => J, 10 => K, 11 => L, 12 => M);

// Implement ViewSequence for Vec<V> to support dynamic lists
impl<State, Msg, V> ViewSequence<State> for Vec<V>
where
    V: View<State, Message = Msg>,
{
    type Elements = Vec<V::Element>;
    type Message = Msg;

    fn build(&self, ctx: &mut Context, parent: Node) -> Self::Elements {
        let mut elements = Vec::with_capacity(self.len());
        for view in self {
            let el = view.build(ctx);
            parent.append(ctx, view.get_node(&el));
            elements.push(el);
        }
        elements
    }

    fn rebuild(&self, prev: &Self, ctx: &mut Context, elements: &mut Self::Elements, parent: Node) {
        let min_len = self.len().min(prev.len());

        for i in 0..min_len {
            self[i].rebuild(&prev[i], ctx, &mut elements[i]);
        }

        for i in min_len..self.len() {
            let el = self[i].build(ctx);
            parent.append(ctx, self[i].get_node(&el));
            elements.push(el);
        }

        if self.len() < prev.len() {
            for i in min_len..prev.len() {
                prev[i].teardown(ctx, &mut elements[i]);
            }
            elements.truncate(self.len());
        }
    }

    fn teardown(&self, ctx: &mut Context, elements: &mut Self::Elements) {
        for (view, el) in self.iter().zip(elements.iter_mut()) {
            view.teardown(ctx, el);
        }
    }

    fn handle_event(
        &self,
        elements: &mut Self::Elements,
        state: &State,
        event: Event,
        ctx: &mut Context,
    ) -> (EventResult, Option<Self::Message>) {
        let is_tick = matches!(event, Event::Tick { .. });
        let mut handled = EventResult::Ignored;
        let mut emitted_msg = None;

        for (v, el) in self.iter().zip(elements.iter_mut()) {
            if (is_tick || handled == EventResult::Ignored) && emitted_msg.is_none() {
                let (res, msg) = v.handle_event(el, state, event.clone(), ctx);
                handled = handled.or(res);
                if msg.is_some() {
                    emitted_msg = msg;
                }
            }
        }

        (handled, emitted_msg)
    }
}

// Implement View for Option<V> to support conditional rendering as a standalone View
impl<State, V> View<State> for Option<V>
where
    V: View<State>,
{
    type Element = Option<V::Element>;
    type Message = V::Message;

    fn build(&self, ctx: &mut Context) -> Self::Element {
        self.as_ref().map(|v| v.build(ctx))
    }

    fn rebuild_with_parent(
        &self,
        prev: &Self,
        ctx: &mut Context,
        element: &mut Self::Element,
        parent: Node,
        next_sibling: Option<Node>,
    ) {
        match (self, prev, element) {
            (Some(new_view), Some(old_view), Some(el)) => {
                new_view.rebuild_with_parent(old_view, ctx, el, parent, next_sibling);
            }
            (Some(new_view), _, el_slot @ None) => {
                let el = new_view.build(ctx);
                let node = new_view.get_node(&el);
                if let Some(sibling) = next_sibling {
                    node.put_before(ctx, sibling);
                } else {
                    parent.append(ctx, node);
                }
                *el_slot = Some(el);
            }
            (None, Some(old_view), el_slot @ Some(_)) => {
                if let Some(mut el) = el_slot.take() {
                    let node = old_view.get_node(&el);
                    node.remove(ctx);
                    old_view.teardown(ctx, &mut el);
                }
            }
            _ => {}
        }
    }

    fn rebuild(&self, prev: &Self, ctx: &mut Context, element: &mut Self::Element) {
        match (self, prev, element) {
            (Some(new_view), Some(old_view), Some(el)) => {
                new_view.rebuild(old_view, ctx, el);
            }
            (Some(new_view), _, el_slot @ None) => {
                *el_slot = Some(new_view.build(ctx));
            }
            (None, Some(old_view), el_slot @ Some(_)) => {
                if let Some(mut el) = el_slot.take() {
                    let node = old_view.get_node(&el);
                    node.remove(ctx);
                    old_view.teardown(ctx, &mut el);
                }
            }
            _ => {}
        }
    }

    fn teardown(&self, ctx: &mut Context, element: &mut Self::Element) {
        if let (Some(view), Some(el)) = (self.as_ref(), element) {
            view.teardown(ctx, el);
        }
    }

    fn get_node(&self, element: &Self::Element) -> Node {
        if let (Some(view), Some(el)) = (self.as_ref(), element) {
            view.get_node(el)
        } else {
            Node::get_invalid()
        }
    }

    fn handle_event(
        &self,
        element: &mut Self::Element,
        state: &State,
        event: Event,
        ctx: &mut Context,
    ) -> (EventResult, Option<Self::Message>) {
        if let (Some(view), Some(el)) = (self.as_ref(), element) {
            view.handle_event(el, state, event, ctx)
        } else {
            (EventResult::Ignored, None)
        }
    }
}

// Implement ViewSequence for Option<V> to support conditional rendering
impl<State, V> ViewSequence<State> for Option<V>
where
    V: View<State>,
{
    type Elements = Option<V::Element>;
    type Message = V::Message;

    fn build(&self, ctx: &mut Context, parent: Node) -> Self::Elements {
        if let Some(view) = self {
            let el = view.build(ctx);
            parent.append(ctx, view.get_node(&el));
            Some(el)
        } else {
            None
        }
    }

    fn rebuild(&self, prev: &Self, ctx: &mut Context, elements: &mut Self::Elements, parent: Node) {
        match (self, prev, elements) {
            (Some(new_view), Some(old_view), Some(el)) => {
                new_view.rebuild_with_parent(old_view, ctx, el, parent, None);
            }
            (Some(new_view), _, el_slot @ None) => {
                let el = new_view.build(ctx);
                parent.append(ctx, new_view.get_node(&el));
                *el_slot = Some(el);
            }
            (None, Some(old_view), el_slot @ Some(_)) => {
                if let Some(mut el) = el_slot.take() {
                    let node = old_view.get_node(&el);
                    node.remove(ctx);
                    old_view.teardown(ctx, &mut el);
                }
            }
            _ => {}
        }
    }

    fn teardown(&self, ctx: &mut Context, elements: &mut Self::Elements) {
        if let (Some(view), Some(el)) = (self, elements) {
            view.teardown(ctx, el);
        }
    }

    fn handle_event(
        &self,
        elements: &mut Self::Elements,
        state: &State,
        event: Event,
        ctx: &mut Context,
    ) -> (EventResult, Option<Self::Message>) {
        if let (Some(view), Some(el)) = (self, elements) {
            view.handle_event(el, state, event, ctx)
        } else {
            (EventResult::Ignored, None)
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::ui::widgets::{button, row};

    #[test]
    fn test_vec_view_sequence_grow_and_shrink() {
        let mut ctx = Context::new();
        let list5: Vec<_> = (0..5).map(|i| button::<_, ()>(format!("{i}"))).collect();
        let list6: Vec<_> = (0..6).map(|i| button::<_, ()>(format!("{i}"))).collect();

        let row_view5 = row(list5);
        let row_view6 = row(list6);

        let mut el = View::<()>::build(&row_view5, &mut ctx);
        View::<()>::rebuild(&row_view6, &row_view5, &mut ctx, &mut el);
        View::<()>::teardown(&row_view6, &mut ctx, &mut el);
    }

    #[test]
    fn test_option_view_sequence_sibling_ordering() {
        use crate::ui::widgets::{Text, column, text};

        type OptText = Option<Text<()>>;

        let mut ctx = Context::new();

        // 1. Initial: Slot 0 (BANNER), Slot 1 (music_dir), Slot 2 (None), Slot 3 (None), Slot 4 (log)
        let view_1 = column((
            text::<_, ()>("BANNER"),
            Some(text::<_, ()>("music_dir")),
            None as OptText,
            None as OptText,
            text::<_, ()>("log"),
        ));

        let mut el = View::<()>::build(&view_1, &mut ctx);
        let parent_node = View::<()>::get_node(&view_1, &el);

        let initial_children = parent_node.children(&ctx);
        assert_eq!(initial_children.len(), 3);
        let banner_node = initial_children[0];
        let music_node = initial_children[1];
        let log_node = initial_children[2];

        // 2. Rebuild: Slot 1 becomes None, Slot 2 becomes Some("progress_bar")
        let view_2 = column((
            text::<_, ()>("BANNER"),
            None as OptText,
            Some(text::<_, ()>("progress_bar")),
            None as OptText,
            text::<_, ()>("log"),
        ));

        View::<()>::rebuild(&view_2, &view_1, &mut ctx, &mut el);

        let updated_children = parent_node.children(&ctx);
        assert_eq!(updated_children.len(), 3);
        assert_eq!(updated_children[0], banner_node);
        // Progress bar MUST be inserted before log, preserving declaration order!
        let progress_node = updated_children[1];
        assert_ne!(progress_node, music_node);
        assert_eq!(updated_children[2], log_node);

        View::<()>::teardown(&view_2, &mut ctx, &mut el);
    }
}