rust_widgets 2.4.2

// SPDX-FileCopyrightText: Copyright (c) 2026 Mike Li/Mikewolfli/Wei Li(mikewolfli@163.com)
// SPDX-License-Identifier: MIT

//! Carrying [`Patch`]es onto the retained control tree.
//!
//! This is where the declarative half meets the retained half. `SetProperty` writes through
//! each control's **own** published property contract — the same path the JSON loader and
//! the C ABI use — so a property that a control refuses by name is refused here for the
//! same reason, with the same error. Nothing in this module knows what a `text` or a
//! `value` means.
//!
//! The reason to keep structural patches here rather than in the diff is *reversibility of
//! evidence* (BLUE18 rule #89): `apply` is the only thing that mutates, so a test can skip
//! it and show that the assertion it feeds really does depend on the patch having been
//! carried out.

use crate::core::ObjectId;
use crate::widget::capability::properties_trait::widget_property_set;
use crate::widget::capability::CapabilityValue;

use super::diff::Patch;
use super::node::Node;

/// Write one property on a mounted control through that control's own contract.
///
/// Going through `widget_property_set` (the same entry point the JSON loader and the C ABI
/// use) is what keeps this module ignorant of what any property means: a control that does
/// not publish the name refuses it here for exactly the same reason it would refuse it
/// anywhere else.
pub(crate) fn write_property(
    id: ObjectId,
    name: &str,
    value: CapabilityValue,
) -> Result<(), String> {
    match crate::widget::runtime::with_widget_mut(id, |widget| {
        widget_property_set(widget, name, value).map_err(|e| format!("{e:?}"))
    }) {
        Some(result) => result,
        None => Err("the control is not registered with the runtime".to_string()),
    }
}

/// Why a patch could not be carried out.
///
/// Reported per patch instead of aborting the batch: a panel that no longer exists should
/// not prevent the rest of the tree from reaching its declared state, and a caller needs
/// the specific reason to report it.
#[derive(Debug, Clone, PartialEq)]
pub enum ViewError {
    /// The control a patch named is not mounted.
    ///
    /// Distinguishable from "the property is wrong" because the caller's fix differs: a
    /// missing control means the diff's identity map was stale, while a refused property
    /// means the view asked for something the control does not publish.
    UnknownWidget {
        /// The id the patch named.
        id: ObjectId,
    },
    /// The control exists but refused the write.
    ///
    /// Carries the control's own error verbatim, so the property contract remains the
    /// single source of truth for why a write failed.
    PropertyRefused {
        /// The id the patch named.
        id: ObjectId,
        /// The property that was refused.
        name: String,
        /// The control's reason.
        reason: String,
    },
    /// A structural patch named a parent that is not mounted.
    UnknownParent {
        /// The parent the patch named.
        parent: ObjectId,
    },
    /// The node's widget type has no registered constructor.
    ///
    /// Not a silent skip: an unconstructible node means the view describes a control this
    /// build cannot make, which is a defect in the view or in the factory registration.
    UnknownWidgetType {
        /// The type name as declared.
        widget: String,
    },
}

impl core::fmt::Display for ViewError {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        match self {
            ViewError::UnknownWidget { id } => {
                write!(f, "patch targets widget {id}, which is not mounted")
            }
            ViewError::PropertyRefused { id, name, reason } => {
                write!(f, "widget {id} refused a write to '{name}': {reason}")
            }
            ViewError::UnknownParent { parent } => {
                write!(f, "patch targets parent {parent}, which is not mounted")
            }
            ViewError::UnknownWidgetType { widget } => {
                write!(f, "no constructor is registered for widget type '{widget}'")
            }
        }
    }
}

/// What [`apply`] did.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ApplyReport {
    /// Property writes that reached a control and were accepted.
    pub properties_written: usize,
    /// Controls created (including every node of an inserted subtree).
    pub widgets_created: usize,
    /// Controls removed, counting each removed subtree's nodes.
    pub widgets_removed: usize,
    /// Controls that were re-parented in place, keeping their id.
    pub widgets_moved: usize,
    /// Patches that could not be carried out, with reasons.
    pub errors: Vec<ViewError>,
}

impl ApplyReport {
    /// Whether every patch was carried out.
    pub fn is_clean(&self) -> bool {
        self.errors.is_empty()
    }

    /// Total controls destroyed by this batch, including subtree members.
    pub fn total_removed(&self) -> usize {
        self.widgets_removed
    }
}

/// Apply `patches` to the retained tree described by `layout`.
///
/// `create` constructs a live control for a declarative node and returns its id; it is
/// injected rather than called directly so that this function stays testable without a
/// window and so the caller decides how a name becomes a control (the JSON loader's factory
/// table, or a test's stub).
///
/// The layout is updated as patches land, so a batch that includes an `Insert` followed by a
/// `SetProperty` on the inserted subtree resolves — the identity map and the live tree move
/// together rather than one lagging the other.
///
/// # Structural patches
///
/// `Insert` / `Remove` / `Move` / `Replace` maintain both the widget tree and the
/// [`BoundJsonLayout`](crate::json::BoundJsonLayout) indexes, because a diff that leaves
/// those two disagreeing produces an identity map describing controls that no longer exist.
pub fn apply(
    layout: &mut crate::json::BoundJsonLayout,
    patches: &[Patch],
    create: &dyn Fn(&Node) -> Option<ObjectId>,
) -> ApplyReport {
    let mut report = ApplyReport::default();
    for patch in patches {
        apply_one(layout, patch, create, &mut report);
    }
    report
}

/// Carry out a single patch, recording the outcome in `report`.
fn apply_one(
    layout: &mut crate::json::BoundJsonLayout,
    patch: &Patch,
    create: &dyn Fn(&Node) -> Option<ObjectId>,
    report: &mut ApplyReport,
) {
    match patch {
        Patch::SetProperty { id, name, value } => {
            if !is_mounted(layout, *id) {
                report.errors.push(ViewError::UnknownWidget { id: *id });
                return;
            }
            match write_property(*id, name, value.clone()) {
                Ok(()) => report.properties_written += 1,
                Err(reason) => report.errors.push(ViewError::PropertyRefused {
                    id: *id,
                    name: name.clone(),
                    reason,
                }),
            }
        }
        Patch::Insert { parent, index, node } => {
            if !is_mounted(layout, *parent) {
                report.errors.push(ViewError::UnknownParent { parent: *parent });
                return;
            }
            let created = insert_subtree(layout, *parent, *index, node, create, report);
            report.widgets_created += created;
        }
        Patch::Remove { id } => {
            if !is_mounted(layout, *id) {
                report.errors.push(ViewError::UnknownWidget { id: *id });
                return;
            }
            report.widgets_removed += remove_subtree(layout, *id);
        }
        Patch::Move { id, parent, index } => {
            if !is_mounted(layout, *id) {
                report.errors.push(ViewError::UnknownWidget { id: *id });
                return;
            }
            if !is_mounted(layout, *parent) {
                report.errors.push(ViewError::UnknownParent { parent: *parent });
                return;
            }
            reparent(layout, *id, *parent, *index);
            report.widgets_moved += 1;
        }
        Patch::Replace { id, parent, index, node } => {
            if !is_mounted(layout, *id) {
                report.errors.push(ViewError::UnknownWidget { id: *id });
                return;
            }
            if !is_mounted(layout, *parent) {
                report.errors.push(ViewError::UnknownParent { parent: *parent });
                return;
            }
            report.widgets_removed += remove_subtree(layout, *id);
            let created = insert_subtree(layout, *parent, *index, node, create, report);
            report.widgets_created += created;
        }
    }
}

/// Whether `id` names a control the layout still knows about.
///
/// Structural knowledge is the authority rather than the platform's registry: a node the
/// layout has detached is exactly what "stale id" means here, and asking the platform would
/// answer about a different tree. The root is checked separately because a root has no
/// parent entry.
fn is_mounted(layout: &crate::json::BoundJsonLayout, id: ObjectId) -> bool {
    if id == 0 {
        return false;
    }
    layout.root() == Some(id) || layout.parent(id).is_some() || layout.widget_name(id).is_some()
}

/// Create `node` and its declared subtree under `parent`, returning how many nodes were made.
fn insert_subtree(
    layout: &mut crate::json::BoundJsonLayout,
    parent: ObjectId,
    index: usize,
    node: &Node,
    create: &dyn Fn(&Node) -> Option<ObjectId>,
    report: &mut ApplyReport,
) -> usize {
    let id = match create(node) {
        Some(id) if id != 0 => id,
        _ => {
            report.errors.push(ViewError::UnknownWidgetType { widget: node.widget.clone() });
            return 0;
        }
    };

    // Register before recursing: a child's `register_node` looks up its parent's child list
    // to append itself, so the parent must already exist in the index.
    let key = node.key.clone().unwrap_or_default();
    layout.register_node(id, node.widget.clone(), key, Some(parent));
    place_child_at(layout, parent, id, index);

    let mut count = 1usize;
    for (i, child) in node.children.iter().enumerate() {
        count += insert_subtree(layout, id, i, child, create, report);
    }
    // The subtree's declared properties go through the same property contract as a patch,
    // so a control that refuses one reports it here rather than at the next diff.
    for (name, value) in &node.props {
        match write_property(id, name, value.clone()) {
            Ok(()) => report.properties_written += 1,
            Err(reason) => {
                report.errors.push(ViewError::PropertyRefused { id, name: name.clone(), reason })
            }
        }
    }
    count
}

/// Remove `id` and its subtree from the layout, returning how many nodes disappeared.
fn remove_subtree(layout: &mut crate::json::BoundJsonLayout, id: ObjectId) -> usize {
    layout.detach(id).len()
}

/// Move `id` to position `index` under `parent`, keeping its `ObjectId`.
fn reparent(
    layout: &mut crate::json::BoundJsonLayout,
    id: ObjectId,
    parent: ObjectId,
    index: usize,
) {
    let key = layout.node_key(id).unwrap_or_default().to_string();
    let widget = layout.widget_name(id).unwrap_or_default().to_string();
    layout.register_node(id, widget, key, Some(parent));
    place_child_at(layout, parent, id, index);
}

/// Move `child` within `parent`'s child list to position `index`, clamping to the end.
fn place_child_at(
    layout: &mut crate::json::BoundJsonLayout,
    parent: ObjectId,
    child: ObjectId,
    index: usize,
) {
    layout.move_child_to(parent, child, index);
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::widget::capability::CapabilityValue;

    fn s(v: &str) -> CapabilityValue {
        CapabilityValue::String(v.to_string())
    }

    /// A stub backend: it never creates real controls, because these tests are about the
    /// layout's structural bookkeeping rather than about any control's appearance.
    struct StubBackend {
        next: std::cell::Cell<ObjectId>,
    }

    impl StubBackend {
        fn new() -> Self {
            Self { next: std::cell::Cell::new(100) }
        }

        /// The `create` closure handed to [`apply`].
        fn creator(&self) -> impl Fn(&Node) -> Option<ObjectId> + '_ {
            move |_node: &Node| {
                let id = self.next.get();
                self.next.set(id + 1);
                Some(id)
            }
        }
    }

    fn fixture_root() -> (crate::json::BoundJsonLayout, ObjectId) {
        let mut layout = crate::json::BoundJsonLayout::new();
        layout.register_node(1, "window", "main", None);
        (layout, 1)
    }

    #[test]
    fn insert_creates_the_whole_declared_subtree() {
        let (mut layout, root) = fixture_root();
        let backend = StubBackend::new();
        let node = Node::new("panel")
            .key("card")
            .child(Node::new("label").key("title"))
            .child(Node::new("button").key("ok"));
        let report = apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 0, node }],
            &backend.creator(),
        );
        assert!(report.is_clean(), "errors: {:?}", report.errors);
        assert_eq!(report.widgets_created, 3, "panel + label + button");
        assert_eq!(layout.children(root).len(), 1);
        let panel = layout.child_by_key(Some(root), "card").expect("panel must be indexed");
        assert_eq!(layout.children(panel).len(), 2);
        assert!(layout.child_by_key(Some(panel), "title").is_some());
    }

    #[test]
    fn insert_honours_the_declared_position() {
        let (mut layout, root) = fixture_root();
        let backend = StubBackend::new();
        let create = backend.creator();
        apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 0, node: Node::new("label").key("first") }],
            &create,
        );
        apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 1, node: Node::new("label").key("second") }],
            &create,
        );
        apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 0, node: Node::new("label").key("zeroth") }],
            &create,
        );
        let keys: Vec<Option<&str>> =
            layout.children(root).iter().map(|&id| layout.node_key(id)).collect();
        assert_eq!(keys, [Some("zeroth"), Some("first"), Some("second")]);
    }

    #[test]
    fn insert_with_an_index_past_the_end_appends() {
        let (mut layout, root) = fixture_root();
        let backend = StubBackend::new();
        let create = backend.creator();
        for key in ["a", "b"] {
            apply(
                &mut layout,
                &[Patch::Insert { parent: root, index: 99, node: Node::new("label").key(key) }],
                &create,
            );
        }
        let keys: Vec<Option<&str>> =
            layout.children(root).iter().map(|&id| layout.node_key(id)).collect();
        assert_eq!(keys, [Some("a"), Some("b")], "an out-of-range index appends, never panics");
    }

    #[test]
    fn removing_a_subtree_also_removes_its_descendants() {
        let (mut layout, root) = fixture_root();
        let backend = StubBackend::new();
        let create = backend.creator();
        apply(
            &mut layout,
            &[Patch::Insert {
                parent: root,
                index: 0,
                node: Node::new("panel").key("card").child(Node::new("label").key("title")),
            }],
            &create,
        );
        let panel = layout.child_by_key(Some(root), "card").expect("panel");
        let report = apply(&mut layout, &[Patch::Remove { id: panel }], &create);
        assert!(report.is_clean(), "errors: {:?}", report.errors);
        assert_eq!(report.widgets_removed, 2, "the panel and its label");
        assert!(layout.children(root).is_empty());
        assert_eq!(layout.id("title"), None, "the descendant's name must go too");
    }

    #[test]
    fn a_patch_naming_a_detached_control_is_reported_not_ignored() {
        // The whole reason `apply` keeps its own mount check: silently dropping the write
        // would make a stale diff look like a successful update.
        let (mut layout, _root) = fixture_root();
        let backend = StubBackend::new();
        let report = apply(&mut layout, &[Patch::Remove { id: 999 }], &backend.creator());
        assert!(!report.is_clean());
        assert_eq!(report.errors, [ViewError::UnknownWidget { id: 999 }]);
    }

    #[test]
    fn an_insert_under_an_unknown_parent_is_reported() {
        let (mut layout, _root) = fixture_root();
        let backend = StubBackend::new();
        let report = apply(
            &mut layout,
            &[Patch::Insert { parent: 999, index: 0, node: Node::new("label") }],
            &backend.creator(),
        );
        assert_eq!(report.errors, [ViewError::UnknownParent { parent: 999 }]);
        assert_eq!(report.widgets_created, 0, "nothing was created");
    }

    #[test]
    fn a_refused_constructor_is_reported_as_an_unknown_widget_type() {
        let (mut layout, root) = fixture_root();
        let report = apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 0, node: Node::new("no_such_control") }],
            &|_n: &Node| None,
        );
        assert_eq!(
            report.errors,
            [ViewError::UnknownWidgetType { widget: "no_such_control".to_string() }]
        );
    }

    #[test]
    fn move_keeps_the_controls_identity() {
        // BLUE18 rule #90 in miniature: the id survives, so focus and internal state would
        // survive a real move. A remove+insert would assign a fresh id instead.
        let (mut layout, root) = fixture_root();
        let backend = StubBackend::new();
        let create = backend.creator();
        apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 0, node: Node::new("panel").key("left") }],
            &create,
        );
        apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 1, node: Node::new("panel").key("right") }],
            &create,
        );
        let left = layout.child_by_key(Some(root), "left").expect("left");
        let right = layout.child_by_key(Some(root), "right").expect("right");

        let report =
            apply(&mut layout, &[Patch::Move { id: left, parent: right, index: 0 }], &create);
        assert!(report.is_clean(), "errors: {:?}", report.errors);
        assert_eq!(report.widgets_moved, 1);
        assert_eq!(report.widgets_created, 0, "a move must not create anything");
        assert_eq!(report.widgets_removed, 0, "a move must not destroy anything");
        assert_eq!(layout.children(root), &[right]);
        assert_eq!(layout.children(right), &[left]);
        assert_eq!(layout.parent(left), Some(right), "the same id, a new parent");
        assert_eq!(layout.node_key(left), Some("left"), "its identity is unchanged");
    }

    #[test]
    fn replace_destroys_one_subtree_and_builds_another() {
        let (mut layout, root) = fixture_root();
        let backend = StubBackend::new();
        let create = backend.creator();
        apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 0, node: Node::new("label").key("slot") }],
            &create,
        );
        let old = layout.child_by_key(Some(root), "slot").expect("slot");
        let report = apply(
            &mut layout,
            &[Patch::Replace {
                id: old,
                parent: root,
                index: 0,
                node: Node::new("button").key("slot"),
            }],
            &create,
        );
        assert!(report.is_clean(), "errors: {:?}", report.errors);
        assert_eq!(report.widgets_removed, 1);
        assert_eq!(report.widgets_created, 1);
        let fresh = layout.child_by_key(Some(root), "slot").expect("slot");
        assert_ne!(fresh, old, "a replace must not reuse the id");
        assert_eq!(layout.widget_name(fresh), Some("button"));
        assert_eq!(layout.children(root), &[fresh], "it takes the old position");
    }

    #[test]
    fn an_inserted_nodes_declared_properties_are_written() {
        let (mut layout, root) = fixture_root();
        let backend = StubBackend::new();
        let node = Node::new("label").key("t").prop("text", s("Hello"));
        let report = apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 0, node }],
            &backend.creator(),
        );
        // `label`'s `text` is a real published property, so the contract decides; a stub id
        // is not registered with the platform, so the write may be refused — either way the
        // call must have been *attempted* and the outcome reported, never silently skipped.
        assert_eq!(report.widgets_created, 1);
        assert!(
            report.properties_written + report.errors.len() >= 1,
            "the declared property must be attempted"
        );
    }

    #[test]
    fn apply_is_ordered_so_a_later_patch_can_address_an_earlier_insert() {
        // The batch the diff produces is ordered insert-then-update; if `apply` did not
        // register the new node first, the follow-up write would be reported as unknown.
        let (mut layout, root) = fixture_root();
        let backend = StubBackend::new();
        let create = backend.creator();
        apply(
            &mut layout,
            &[Patch::Insert { parent: root, index: 0, node: Node::new("panel").key("card") }],
            &create,
        );
        let card = layout.child_by_key(Some(root), "card").expect("card");
        let follow_up = apply(&mut layout, &[Patch::Remove { id: card }], &create);
        assert!(
            follow_up.is_clean(),
            "the inserted node must be addressable: {:?}",
            follow_up.errors
        );
    }

    #[test]
    fn an_empty_batch_reports_a_clean_no_op() {
        let (mut layout, _root) = fixture_root();
        let report = apply(&mut layout, &[], &|_n: &Node| Some(1));
        assert!(report.is_clean());
        assert_eq!(report.properties_written, 0);
        assert_eq!(report.widgets_created, 0);
        assert_eq!(report.widgets_removed, 0);
        assert_eq!(report.total_removed(), 0);
    }

    #[test]
    fn error_display_names_the_thing_that_went_wrong() {
        assert!(ViewError::UnknownWidget { id: 7 }.to_string().contains('7'));
        assert!(ViewError::UnknownWidgetType { widget: "widget_x".into() }
            .to_string()
            .contains("widget_x"));
        assert!(ViewError::PropertyRefused {
            id: 1,
            name: "text".into(),
            reason: "not writable".into()
        }
        .to_string()
        .contains("text"));
    }

    #[test]
    fn a_layout_with_no_structure_reports_a_missing_parent_rather_than_mounting() {
        // Guards the is_mounted rule: an empty binding must not treat every id as valid,
        // or a patch batch against a layout that was never populated would look clean.
        let mut layout = crate::json::BoundJsonLayout::new();
        layout.register_node(1, "window", "main", None);
        layout.detach(1);
        let report = apply(
            &mut layout,
            &[Patch::Insert { parent: 1, index: 0, node: Node::new("label") }],
            &|_n: &Node| Some(2),
        );
        assert!(!report.is_clean(), "an id that was detached must not be treated as mounted");
    }

    #[test]
    fn a_structure_free_layout_is_still_usable_by_a_caller_that_populates_it_first() {
        let mut layout = crate::json::BoundJsonLayout::new();
        layout.register_node(1, "window", "main", None);
        let report = apply(
            &mut layout,
            &[Patch::Insert {
                parent: 1,
                index: 0,
                node: Node::new("label").key("a").child(Node::new("icon").key("i")),
            }],
            &|n: &Node| Some(50 + n.node_count() as u64),
        );
        assert_eq!(report.widgets_created, 2);
        assert_eq!(layout.children(1).len(), 1);
        let outer = layout.children(1)[0];
        assert_eq!(layout.children(outer).len(), 1, "the nested child was attached too");
    }
}