cranpose_ui/modifier/

mod.rs

//! Modifier system for Cranpose
//!
//! This module now acts as a thin builder around modifier elements. Each
//! [`Modifier`] stores the element chain required by the modifier node system
//! together with inspector metadata while resolved state is computed directly
//! from the modifier nodes.

use std::{fmt, rc::Rc};

use cranpose_core::ProvidedValue;
use smallvec::SmallVec;

mod alignment;
mod background;
mod blur;
mod border;
mod chain;
mod clickable;
mod coordinator_rect;
mod drag_and_drop;
mod draw_cache;
mod fill;
pub(crate) mod focus;
mod focus_ring;
mod graphics_layer;
mod key_input;
mod layout_data;
mod local;
mod long_press;
mod minimum_interactive;
mod offset;
mod padding;
mod pointer_icon;
pub(crate) mod pointer_input;
mod pointer_opaque;
mod resolved_modifiers;
mod rotary_input;
mod scroll;
mod selectable;
mod semantics;
mod shadow;
mod size;
mod slices;
mod toggleable;
mod weight;
mod window_root;
mod wrap_content;
mod z_index;

pub(crate) use chain::{
    InPlaceReach, InPlaceUpdate, ModifierChainHandle, ModifierChainInspectorNode,
    ModifierLocalsHandle,
};
pub(crate) use coordinator_rect::CoordinatorRect;
use cranpose_foundation::{
    DynModifierElement, ModifierNodeElement, NodeCapabilities, ProgressBarRangeInfo,
    SemanticsConfiguration, modifier_element,
};
pub use cranpose_foundation::{
    PointerButton, PointerButtons, PointerEvent, PointerEventKind, PointerSource, RotaryScrollEvent,
};
pub use cranpose_ui_graphics::{
    BlendMode, Brush, Color, CompositingStrategy, CornerRadii, DpOffset, EdgeInsets, GraphicsLayer,
    LayerShape, Point, Rect, RenderEffect, RoundedCornerShape, RuntimeShader, Shadow, ShadowScope,
    Size, TransformOrigin,
};
use cranpose_ui_layout::{Alignment, HorizontalAlignment, VerticalAlignment};
pub use drag_and_drop::{
    DragAndDropEvent, DragAndDropOutcome, DragAndDropPayload, DragAndDropPoint, DragAndDropSource,
    DragAndDropSourceElement, DragAndDropSourceNode, DragAndDropState, DragAndDropTarget,
    DragAndDropTargetElement, DragAndDropTargetNode,
};
#[cfg(test)]
pub(crate) use focus::FocusRequesterElement;
pub use focus::{FocusDirection, FocusRequestError, FocusRequester};
pub use graphics_layer::GlassMaterial;
pub use key_input::KeyEventRoute;
pub(crate) use local::{
    ModifierLocalAncestorResolver, ModifierLocalSource, ModifierLocalToken, ResolvedModifierLocal,
};
use local::{ModifierLocalConsumerElement, ModifierLocalProviderElement};
pub use local::{ModifierLocalKey, ModifierLocalReadScope};
pub use pointer_input::PointerInputScope;
pub(crate) use resolved_modifiers::{DimensionConstraint, LayoutProperties, LayoutWeight};
pub use resolved_modifiers::{ResolvedBackground, ResolvedModifiers};
pub use rotary_input::RotaryInputModifierNode;
#[cfg(feature = "test-helpers")]
pub use scroll::{last_fling_velocity, reset_last_fling_velocity};
use semantics::SemanticsElement;
pub use semantics::{SemanticsRequester, collect_semantics_from_modifier};
pub(crate) use semantics::{
    SemanticsRequesterElement, collect_semantics_from_chain, semantics_reach_of_chain,
};
pub(crate) use slices::SlicesSnapshot;
pub use slices::{
    ModifierNodeSlices, ModifierNodeSlicesDebugStats, SliceTextRef, collect_modifier_slices,
    collect_slices_from_modifier,
};
pub use window_root::{
    WindowRootDescriptor, WindowRootElement, WindowRootEntry, WindowRootNode, WindowRootRegistry,
    WindowRootRoutingScratch, is_window_root, nearest_window_root, nearest_window_roots,
    nearest_window_roots_into, window_roots, window_roots_revision,
};
pub use z_index::{z_index_in_use, z_index_modifier_in_use};

pub(crate) use crate::draw::{DrawCacheBuilder, DrawCommand};
use crate::modifier_nodes::ClipToBoundsElement;

#[derive(Clone, Debug, Default)]
pub(crate) struct InspectorInfo {
    properties: Vec<InspectorProperty>,
}

impl InspectorInfo {
    pub(crate) fn new() -> Self {
        Self::default()
    }

    pub(crate) fn add_property<V: Into<String>>(&mut self, name: &'static str, value: V) {
        self.properties.push(InspectorProperty {
            name,
            value: value.into(),
        });
    }

    pub(crate) fn properties(&self) -> &[InspectorProperty] {
        &self.properties
    }

    pub(crate) fn is_empty(&self) -> bool {
        self.properties.is_empty()
    }

    pub(crate) fn add_dimension(&mut self, name: &'static str, constraint: DimensionConstraint) {
        self.add_property(name, describe_dimension(constraint));
    }

    pub(crate) fn add_offset_components(
        &mut self,
        x_name: &'static str,
        y_name: &'static str,
        offset: Point,
    ) {
        self.add_property(x_name, offset.x.to_string());
        self.add_property(y_name, offset.y.to_string());
    }

    pub(crate) fn add_alignment<A>(&mut self, name: &'static str, alignment: A)
    where
        A: fmt::Debug,
    {
        self.add_property(name, format!("{alignment:?}"));
    }
}

#[derive(Clone, Debug, PartialEq)]
pub struct InspectorProperty {
    pub name: &'static str,
    pub value: String,
}

#[derive(Clone, Debug, PartialEq)]
pub struct ModifierInspectorRecord {
    pub name: &'static str,
    pub properties: Vec<InspectorProperty>,
}

#[derive(Clone, Debug)]
pub(crate) struct InspectorMetadata {
    name: &'static str,
    info: InspectorInfo,
}

impl InspectorMetadata {
    pub(crate) fn new<F>(name: &'static str, recorder: F) -> Self
    where
        F: FnOnce(&mut InspectorInfo),
    {
        let mut info = InspectorInfo::new();
        recorder(&mut info);
        Self { name, info }
    }

    fn is_empty(&self) -> bool {
        self.info.is_empty()
    }

    fn to_record(&self) -> ModifierInspectorRecord {
        ModifierInspectorRecord {
            name: self.name,
            properties: self.info.properties().to_vec(),
        }
    }
}

fn describe_dimension(constraint: DimensionConstraint) -> String {
    match constraint {
        DimensionConstraint::Unspecified => "unspecified".to_string(),
        DimensionConstraint::Points(value) => value.to_string(),
        DimensionConstraint::Fraction(value) => format!("fraction({value})"),
        DimensionConstraint::Intrinsic(size) => format!("intrinsic({size:?})"),
    }
}

fn inspector_slice(inspector: &Option<Rc<[InspectorMetadata]>>) -> &[InspectorMetadata] {
    inspector.as_deref().unwrap_or(&[])
}

/// The inspector metadata of two modifiers joined, first `first`'s, or
/// `None` when neither has any.
fn merged_inspector(
    first: &[InspectorMetadata],
    second: &[InspectorMetadata],
) -> Option<Rc<[InspectorMetadata]>> {
    if first.is_empty() && second.is_empty() {
        return None;
    }
    Some(first.iter().chain(second).cloned().collect())
}

/// Whether `a` and `b` are equal elements: one element, as a kept chain
/// shares them, or two that compare equal.
fn same_element(a: &DynModifierElement, b: &DynModifierElement) -> bool {
    Rc::ptr_eq(a, b) || a.equals_element(&**b)
}

pub(crate) fn inspector_metadata<F>(name: &'static str, recorder: F) -> InspectorMetadata
where
    F: FnOnce(&mut InspectorInfo),
{
    if !inspector_metadata_enabled() {
        return InspectorMetadata::new(name, |_| {});
    }
    InspectorMetadata::new(name, recorder)
}

pub(crate) fn modifier_debug_enabled() -> bool {
    #[cfg(not(target_arch = "wasm32"))]
    {
        cranpose_core::DIAGNOSTICS.compose_debug_modifiers.is_set()
    }
    #[cfg(target_arch = "wasm32")]
    {
        false
    }
}

fn inspector_metadata_enabled() -> bool {
    cfg!(any(test, feature = "inspection")) || modifier_debug_enabled()
}

/// A modifier's elements: a chain of up to four lives inline in its one
/// shared allocation.
type ModifierElements = SmallVec<[DynModifierElement; 4]>;

/// The elements of a non-empty modifier. A lone element, as each link of a
/// builder chain starts out, is held as it is; joining it to more moves the
/// chain into one shared allocation, which the chain's later links extend
/// in place while it is the only owner.
#[derive(Clone)]
enum Elements {
    One(DynModifierElement),
    Many(Rc<ModifierElements>),
}

impl Elements {
    /// These elements followed by `more`. Elements move into the joined
    /// chain; only those another modifier also holds are copied.
    fn joined(self, more: Self) -> Self {
        let mut chain = match self {
            Self::One(first) => {
                let mut chain = ModifierElements::new();
                chain.push(first);
                Rc::new(chain)
            }
            Self::Many(chain) => chain,
        };
        match Rc::get_mut(&mut chain) {
            Some(owned) => more.move_into(owned),
            None => {
                let mut copy: ModifierElements = chain.iter().cloned().collect();
                more.move_into(&mut copy);
                chain = Rc::new(copy);
            }
        }
        Self::Many(chain)
    }

    fn move_into(self, chain: &mut ModifierElements) {
        match self {
            Self::One(element) => chain.push(element),
            Self::Many(shared) => match Rc::try_unwrap(shared) {
                Ok(owned) => chain.extend(owned),
                Err(shared) => chain.extend(shared.iter().cloned()),
            },
        }
    }

    /// Whether both are the same storage, so equal without comparing.
    fn shares_storage(&self, other: &Self) -> bool {
        match (self, other) {
            (Self::One(a), Self::One(b)) => Rc::ptr_eq(a, b),
            (Self::Many(a), Self::Many(b)) => Rc::ptr_eq(a, b),
            _ => false,
        }
    }
}

impl std::ops::Deref for Elements {
    type Target = [DynModifierElement];

    fn deref(&self) -> &[DynModifierElement] {
        match self {
            Self::One(element) => std::slice::from_ref(element),
            Self::Many(elements) => elements.as_slice(),
        }
    }
}

#[derive(Clone)]
enum ModifierKind {
    Empty,
    Single {
        elements: Elements,
        /// `None` when no element records inspector metadata, which is
        /// always outside tests and modifier debugging: no allocation.
        inspector: Option<Rc<[InspectorMetadata]>>,
    },
}

pub(crate) struct ModifierElementIterator<'a> {
    inner: std::slice::Iter<'a, DynModifierElement>,
}

impl<'a> Iterator for ModifierElementIterator<'a> {
    type Item = &'a DynModifierElement;

    #[inline]
    fn next(&mut self) -> Option<Self::Item> {
        self.inner.next()
    }

    #[inline]
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

impl ExactSizeIterator for ModifierElementIterator<'_> {}

pub(crate) struct ModifierInspectorIterator<'a> {
    inner: std::slice::Iter<'a, InspectorMetadata>,
}

impl<'a> Iterator for ModifierInspectorIterator<'a> {
    type Item = &'a InspectorMetadata;

    #[inline]
    fn next(&mut self) -> Option<Self::Item> {
        self.inner.next()
    }

    #[inline]
    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}

impl ExactSizeIterator for ModifierInspectorIterator<'_> {}

/// A modifier chain that can be applied to composable elements.
///
/// Modifiers allow you to decorate or augment a composable. Common operations include:
/// - Adjusting layout (e.g., `padding`, `fill_max_size`)
/// - Adding behavior (e.g., `clickable`, `scrollable`)
/// - Drawing (e.g., `background`, `border`)
///
/// Modifiers are immutable and form a chain using the builder pattern.
/// The order of modifiers matters: previous modifiers wrap subsequent ones.
///
/// # Example
///
/// ```rust,ignore
/// Modifier::padding(16.0)     // Applied first (outer)
///     .background(Color::Red) // Applied second
///     .clickable(|| println!("Clicked")) // Applied last (inner)
/// ```
#[derive(Clone)]
#[must_use = "a modifier does nothing until a composable receives it"]
pub struct Modifier {
    kind: ModifierKind,
    element_count: usize,
    provides_composition_locals: bool,
}

impl Default for Modifier {
    fn default() -> Self {
        Self {
            kind: ModifierKind::Empty,
            element_count: 0,
            provides_composition_locals: false,
        }
    }
}

impl Modifier {
    /// Returns a modifier that changes nothing.
    pub fn empty() -> Self {
        Self::default()
    }

    /// Creates a modifier from a custom modifier node element.
    pub fn from_element<E>(element: E) -> Self
    where
        E: ModifierNodeElement,
    {
        Self::with_element(element)
    }

    /// Clip the content to the bounds of this modifier.
    ///
    /// Example: `Modifier::empty().clip_to_bounds()`
    pub fn clip_to_bounds(self) -> Self {
        let modifier = crate::thread_state::with(|state| {
            state
                .clip_to_bounds
                .get_or_init(|| Self::with_element(ClipToBoundsElement::new()))
                .clone()
        });
        let modifier =
            modifier.with_inspector_metadata(inspector_metadata("clipToBounds", |info| {
                info.add_property("clipToBounds", "true");
            }));
        self.then(modifier)
    }

    /// Provides the value that `value` returns for `key` to later modifiers in this chain and to
    /// nodes below. Compose's `Modifier.modifierLocalProvider`.
    pub fn modifier_local_provider<T, F>(self, key: ModifierLocalKey<T>, value: F) -> Self
    where
        T: 'static,
        F: Fn() -> T + 'static,
    {
        let element = ModifierLocalProviderElement::new(key, value);
        let modifier = Self::from_dyn_element(modifier_element(element));
        self.then(modifier)
    }

    /// Calls `consumer` to read modifier local values through a [`ModifierLocalReadScope`]. It runs
    /// again when a value it read changes. Compose's `Modifier.modifierLocalConsumer`.
    pub fn modifier_local_consumer<F>(self, consumer: F) -> Self
    where
        F: for<'scope> Fn(&mut ModifierLocalReadScope<'scope>) + 'static,
    {
        let element = ModifierLocalConsumerElement::new(consumer);
        let modifier = Self::from_dyn_element(modifier_element(element));
        self.then(modifier)
    }

    /// Says what a screen reader reads for this node, as one spec value.
    ///
    /// This is [`Modifier::semantics`] with a value in place of a closure.
    /// Compose has only the closure form, because Kotlin's receiver lambda
    /// makes `semantics { contentDescription = "Save" }` read well; Rust has
    /// none, so a spec value reads better, costs one chain element rather
    /// than one per property, and can be compared with another.
    ///
    /// Example:
    /// `Modifier::empty().semantics_spec(SemanticsSpec::new().content_description("Amount").error("needs a number"))`
    pub fn semantics_spec(self, spec: cranpose_foundation::SemanticsSpec) -> Self {
        self.stable_semantics(move |config: &mut SemanticsConfiguration| config.merge(&spec))
    }

    /// Records what a screen reader reads for this node. The recorder may
    /// read live state, so every semantics update runs it again; one whose
    /// answer changes without the node changing can say so with a
    /// [`SemanticsRequester`](crate::SemanticsRequester).
    pub fn semantics<F>(self, recorder: F) -> Self
    where
        F: Fn(&mut SemanticsConfiguration) + 'static,
    {
        self.semantics_recorder(Rc::new(recorder), true)
    }

    /// [`Modifier::semantics`] for a recorder that reads nothing but what it
    /// captured. Its answer changes only when the modifier is set again, which
    /// invalidates the node's semantics, so a semantics update keeps what it
    /// reported instead of running it.
    ///
    /// Example: `Modifier::empty().stable_semantics(move |config| config.content_description = Some(label.clone()))`
    pub fn stable_semantics<F>(self, recorder: F) -> Self
    where
        F: Fn(&mut SemanticsConfiguration) + 'static,
    {
        self.semantics_recorder(Rc::new(recorder), false)
    }

    fn semantics_recorder(
        self,
        recorder: Rc<dyn Fn(&mut SemanticsConfiguration)>,
        reads_live_state: bool,
    ) -> Self {
        let metadata = if inspector_metadata_enabled() {
            let mut preview = SemanticsConfiguration::default();
            recorder(&mut preview);
            let description = preview.content_description.clone();
            let state_description = preview.state_description.clone();
            let role = preview.role;
            let is_clickable = preview.is_activatable();
            let canvas_children = preview.canvas_children.len();
            inspector_metadata("semantics", move |info| {
                if let Some(desc) = &description {
                    info.add_property("contentDescription", desc.clone());
                }
                if let Some(state) = &state_description {
                    info.add_property("stateDescription", state.clone());
                }
                if let Some(role) = role {
                    info.add_property("role", format!("{role:?}"));
                }
                if is_clickable {
                    info.add_property("isClickable", "true");
                }
                if canvas_children > 0 {
                    info.add_property("canvasSemanticsChildren", canvas_children.to_string());
                }
            })
        } else {
            inspector_metadata("semantics", |_| {})
        };
        let element = SemanticsElement::new(recorder, reads_live_state);
        let modifier =
            Self::from_dyn_element(modifier_element(element)).with_inspector_metadata(metadata);
        self.then(modifier)
    }

    /// Tells a screen reader the value this control holds inside a range, so
    /// it reads the value and offers its own way to change it.
    ///
    /// This is Compose's `Modifier.progressSemantics(value, valueRange,
    /// steps)`. Without it a slider reads as text and a person who cannot see
    /// the screen has no way to move it.
    ///
    /// Example: `Modifier::empty().progress_semantics(0.35, 0.0, 1.0, 0)`
    pub fn progress_semantics(self, current: f32, start: f32, end: f32, steps: u32) -> Self {
        let info = ProgressBarRangeInfo::new(current, start, end, steps);
        self.stable_semantics(move |config| config.progress = Some(info))
    }

    /// Marks this control as one that opens a list of choices, so a reader
    /// says "combo box" rather than "button" and knows to look for the
    /// choice it holds. Compose's `Role.DropdownList`.
    pub fn dropdown_list(self) -> Self {
        self.role(cranpose_foundation::SemanticsWidgetRole::DropdownList)
    }

    /// Marks this control as one that holds one value out of an ordered set,
    /// so a reader steps through them. Compose's `Role.ValuePicker`.
    pub fn value_picker(self) -> Self {
        self.role(cranpose_foundation::SemanticsWidgetRole::ValuePicker)
    }

    /// Says what this control does when a screen reader asks it to open, and
    /// marks it as closed right now: a reader offers "expand" and says the
    /// control is collapsed. Compose's
    /// `Modifier.semantics { expand { … } }`.
    pub fn expand(self, action: impl Fn() -> bool + 'static) -> Self {
        let action = cranpose_foundation::SemanticsExpand::new(action);
        self.stable_semantics(move |config| config.expand = Some(action.clone()))
    }

    /// Says what a long press on this control does, so a screen reader can
    /// ask for it and read the label out first: "Remove receipt". Compose's
    /// `Modifier.semantics { onLongClick("Remove receipt") { … } }`, which
    /// `Modifier.combinedClickable(onLongClickLabel = …)` fills in for a
    /// control that takes a long press from a finger too.
    ///
    /// The label is asked for, not optional as in Compose: Android is the one
    /// platform of the four with a long press of its own, and the other three
    /// list the action by name, so a nameless one reads as nothing.
    pub fn on_long_click(
        self,
        label: impl Into<String>,
        action: impl Fn() -> bool + 'static,
    ) -> Self {
        let label = label.into();
        let action = cranpose_foundation::SemanticsLongClick::new(action);
        self.stable_semantics(move |config| {
            config.on_long_click_label = Some(label.clone());
            config.on_long_click = Some(action.clone());
        })
    }

    /// Says what this control does on VoiceOver's magic tap, the two finger
    /// double tap for the main action of a screen, and the verb phrase the
    /// other platforms list it under: "Take the photo". SwiftUI's
    /// `accessibilityAction(.magicTap)`.
    pub fn on_magic_tap(
        self,
        label: impl Into<String>,
        action: impl Fn() -> bool + 'static,
    ) -> Self {
        let label = label.into();
        let action = cranpose_foundation::SemanticsMagicTap::new(action);
        self.stable_semantics(move |config| {
            config.on_magic_tap_label = Some(label.clone());
            config.on_magic_tap = Some(action.clone());
        })
    }

    /// The short names a person says to Voice Control to reach this control,
    /// when the name a reader hears is too long to say. SwiftUI's
    /// `accessibilityInputLabels`.
    pub fn input_labels<S: Into<String>>(self, labels: impl IntoIterator<Item = S>) -> Self {
        let labels: Vec<String> = labels.into_iter().map(Into::into).collect();
        self.stable_semantics(move |config| config.input_labels.clone_from(&labels))
    }

    /// The language of this control's text, as a BCP 47 tag such as "de" or
    /// "pt-BR", so a reader picks the right voice. SwiftUI's
    /// `accessibilityLanguage`, ARIA's `lang`.
    pub fn language(self, tag: impl Into<String>) -> Self {
        let tag = tag.into();
        self.stable_semantics(move |config| config.language = Some(tag.clone()))
    }

    /// Says what this control does when a screen reader asks it to close, and
    /// marks it as open right now. Compose's
    /// `Modifier.semantics { collapse { … } }`.
    pub fn collapse(self, action: impl Fn() -> bool + 'static) -> Self {
        let action = cranpose_foundation::SemanticsExpand::new(action);
        self.stable_semantics(move |config| config.collapse = Some(action.clone()))
    }

    /// Says what this control does when a screen reader asks to send it away:
    /// a row a sighted person swipes off, a sheet a sighted person taps
    /// outside of. A reader that cannot make the gesture gets the same way
    /// out. Compose's `Modifier.semantics { dismiss { … } }`.
    pub fn dismiss(self, action: impl Fn() -> bool + 'static) -> Self {
        let action = cranpose_foundation::SemanticsDismiss::new(action);
        self.stable_semantics(move |config| config.dismiss = Some(action.clone()))
    }

    /// Says what this list does when a screen reader asks for the row at an
    /// index, so a reader reaches row 300 of a long list at once instead of
    /// paging to it. The index counts rows from zero and the answer says
    /// whether the list moved. `LazyColumn` and `LazyRow` declare it on their
    /// own. Compose's `Modifier.semantics { scrollToIndex { … } }`.
    pub fn scroll_to_index(self, action: impl Fn(usize) -> bool + 'static) -> Self {
        let action = cranpose_foundation::SemanticsScrollToIndex::new(action);
        self.stable_semantics(move |config| config.scroll_to_index = Some(action.clone()))
    }

    /// Moves this node in the order a screen reader visits the nodes beside
    /// it: a smaller number comes first, and a node left alone keeps the
    /// order the app laid it out in. A search field drawn last but meant to
    /// be read first takes a negative number. Compose's
    /// `Modifier.semantics { traversalIndex = -1f }`.
    pub fn traversal_index(self, index: f32) -> Self {
        self.stable_semantics(move |config| config.traversal_index = index)
    }

    /// Marks a field as one that holds a secret, so no screen reader reads
    /// its text out: a reader hears the name the app gave the field, and
    /// "password" in place of the text. Compose's
    /// `Modifier.semantics { password() }`.
    pub fn password(self) -> Self {
        self.stable_semantics(|config| config.password = true)
    }

    /// Says why the control's content is wrong, so a screen reader reads
    /// "invalid, the amount needs a number" after the control's state.
    /// Compose's `Modifier.semantics { error("...") }`.
    pub fn error(self, message: impl Into<String>) -> Self {
        let message = message.into();
        self.stable_semantics(move |config| config.error = Some(message.clone()))
    }

    /// Tells a screen reader what using the control does or what it wants,
    /// read after its other words: "double tap to choose a color", "a name of
    /// up to 20 letters". Compose's `Modifier.semantics { hintText = "..." }`.
    pub fn hint_text(self, hint: impl Into<String>) -> Self {
        let hint = hint.into();
        self.stable_semantics(move |config| config.hint_text = Some(hint.clone()))
    }

    /// Names the screen or pane this node is the root of, so a screen reader
    /// hears where it is when the app moves on: "Library" as the library
    /// opens. Compose's `Modifier.semantics { paneTitle = "..." }`.
    pub fn pane_title(self, title: impl Into<String>) -> Self {
        let title = title.into();
        self.stable_semantics(move |config| config.pane_title = Some(title.clone()))
    }

    /// Makes the selectable controls under this node one group, so a screen
    /// reader says which of how many a tab or a radio button is: "Library,
    /// tab, 2 of 5". `LiquidTabBar` declares it on its own. Compose's
    /// `Modifier.selectableGroup()`.
    pub fn selectable_group(self) -> Self {
        self.stable_semantics(|config| config.selectable_group = true)
    }

    /// Makes a screen reader take this node and the text under it as one
    /// stop, the way it does for a button: a row whose name, count and price
    /// belong together reads as "Milk, 2, 3.40" and not as three stops.
    /// Compose's `Modifier.semantics(mergeDescendants = true) {}`.
    pub fn merge_descendants(self) -> Self {
        self.stable_semantics(|config| config.merge_descendants = true)
    }

    /// Takes this node and everything under it out of what a screen reader
    /// sees: a decorative image, or a placeholder drawn under a field that
    /// carries the same words as its name. Compose's
    /// `semantics { hideFromAccessibility() }`.
    pub fn hide_from_accessibility(self) -> Self {
        self.stable_semantics(|config| config.hidden = true)
    }

    /// Marks this component as a heading, so a screen reader lists it among
    /// the headings of the screen and a person can jump between them.
    ///
    /// This is Compose's `Modifier.semantics { heading() }`.
    pub fn heading(self) -> Self {
        self.role(cranpose_foundation::SemanticsWidgetRole::Header)
    }

    /// Tells a screen reader what kind of control this is, when the widget
    /// does not say so on its own.
    ///
    /// This is Compose's `Modifier.semantics { role = Role.Button }`.
    pub fn role(self, role: cranpose_foundation::SemanticsWidgetRole) -> Self {
        self.stable_semantics(move |config| config.role = Some(role))
    }

    /// Makes a screen reader read this component's text out whenever it
    /// changes, without the reader's cursor on it: a status line, a toast, a
    /// count that moves.
    ///
    /// This is Compose's `Modifier.semantics { liveRegion = LiveRegionMode.Polite }`.
    pub fn live_region(self, mode: cranpose_foundation::LiveRegionMode) -> Self {
        self.stable_semantics(move |config| config.live_region = Some(mode))
    }

    /// Gives this component the text a screen reader reads for it, for a
    /// drawing, an icon or a control with no text of its own.
    ///
    /// This is Compose's `Modifier.semantics { contentDescription = "..." }`.
    pub fn content_description(self, description: impl Into<String>) -> Self {
        let description = description.into();
        self.stable_semantics(move |config| config.content_description = Some(description.clone()))
    }

    /// Names this component for tests, which find it by the name instead of
    /// its text or position. Screen readers never receive the name.
    ///
    /// This is Compose's `Modifier.testTag(tag)`.
    pub fn test_tag(self, tag: impl Into<String>) -> Self {
        let tag = tag.into();
        self.stable_semantics(move |config| config.test_tag = Some(tag.clone()))
    }

    /// Binds a [`SemanticsRequester`] to this node, so an app can mark the
    /// node's semantics for re-collection without recomposing or laying out.
    ///
    /// Pair it with [`semantics`](Self::semantics) on the same node when the
    /// recorder reads state the composition does not observe — app state behind
    /// a `RefCell`, a game's own model — which is the case a recorder cannot
    /// signal for itself.
    pub fn semantics_requester(self, requester: &SemanticsRequester) -> Self {
        let element = SemanticsRequesterElement::new(requester.clone());
        let modifier = Self::from_dyn_element(modifier_element(element));
        self.then(modifier)
    }

    /// Enables debug logging for this modifier chain.
    ///
    /// When enabled, logs the entire modifier chain structure including:
    /// - Element types and their properties
    /// - Inspector metadata
    /// - Capability flags
    ///
    /// This is useful for debugging modifier composition issues and understanding
    /// how the modifier chain is structured at runtime.
    ///
    /// Example:
    /// ```text
    /// Modifier::empty()
    ///     .padding(8.0)
    ///     .background(Color(1.0, 0.0, 0.0, 1.0))
    ///     .debug_chain("MyWidget")
    /// ```
    pub fn debug_chain(self, tag: &'static str) -> Self {
        use cranpose_foundation::{ModifierNode, ModifierNodeContext, NodeCapabilities, NodeState};

        #[derive(Clone)]
        struct DebugChainElement {
            tag: &'static str,
        }

        impl fmt::Debug for DebugChainElement {
            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                f.debug_struct("DebugChainElement")
                    .field("tag", &self.tag)
                    .finish()
            }
        }

        impl PartialEq for DebugChainElement {
            fn eq(&self, other: &Self) -> bool {
                self.tag == other.tag
            }
        }

        impl Eq for DebugChainElement {}

        impl std::hash::Hash for DebugChainElement {
            fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
                self.tag.hash(state);
            }
        }

        impl ModifierNodeElement for DebugChainElement {
            type Node = DebugChainNode;

            fn create(&self) -> Self::Node {
                DebugChainNode::new(self.tag)
            }

            fn update(&self, node: &mut Self::Node) {
                node.tag = self.tag;
            }

            fn capabilities(&self) -> NodeCapabilities {
                NodeCapabilities::empty()
            }
        }

        struct DebugChainNode {
            tag: &'static str,
            state: NodeState,
        }

        impl DebugChainNode {
            fn new(tag: &'static str) -> Self {
                Self {
                    tag,
                    state: NodeState::new(),
                }
            }
        }

        #[expect(clippy::print_stderr, reason = "debug_chain prints its lifecycle")]
        impl ModifierNode for DebugChainNode {
            fn on_attach(&mut self, _context: &mut dyn ModifierNodeContext) {
                eprintln!("[debug_chain:{}] Modifier chain attached", self.tag);
            }

            fn on_detach(&mut self) {
                eprintln!("[debug_chain:{}] Modifier chain detached", self.tag);
            }

            fn on_reset(&mut self) {
                eprintln!("[debug_chain:{}] Modifier chain reset", self.tag);
            }
        }

        impl cranpose_foundation::DelegatableNode for DebugChainNode {
            fn node_state(&self) -> &NodeState {
                &self.state
            }
        }

        let element = DebugChainElement { tag };
        let modifier = Self::from_dyn_element(modifier_element(element));
        self.then(modifier)
            .with_inspector_metadata(inspector_metadata("debugChain", move |info| {
                info.add_property("tag", tag);
            }))
    }

    /// This modifier followed by `next`.
    ///
    /// It takes `self`: a modifier built link by link owns its elements
    /// alone, so each link joins them in place instead of copying the chain.
    /// Clone a modifier first to keep using it; the join then copies it.
    pub fn then(self, next: Self) -> Self {
        let ModifierKind::Single {
            elements,
            inspector,
        } = self.kind
        else {
            return next;
        };
        let ModifierKind::Single {
            elements: next_elements,
            inspector: next_inspector,
        } = next.kind
        else {
            return Self {
                kind: ModifierKind::Single {
                    elements,
                    inspector,
                },
                ..self
            };
        };

        let inspector = if next_inspector.is_none() {
            inspector
        } else {
            merged_inspector(
                inspector_slice(&inspector),
                inspector_slice(&next_inspector),
            )
        };
        Self {
            kind: ModifierKind::Single {
                elements: elements.joined(next_elements),
                inspector,
            },
            element_count: self.element_count + next.element_count,
            provides_composition_locals: self.provides_composition_locals
                || next.provides_composition_locals,
        }
    }

    /// How many elements the modifier holds.
    pub(crate) fn element_count(&self) -> usize {
        self.element_count
    }

    pub(crate) fn iter_elements(&self) -> ModifierElementIterator<'_> {
        match &self.kind {
            ModifierKind::Empty => ModifierElementIterator { inner: [].iter() },
            ModifierKind::Single { elements, .. } => ModifierElementIterator {
                inner: elements.iter(),
            },
        }
    }

    pub(crate) fn provided_composition_locals(&self) -> Vec<ProvidedValue> {
        if !self.provides_composition_locals {
            return Vec::new();
        }
        self.iter_elements()
            .flat_map(|element| element.provided_composition_locals())
            .collect()
    }

    pub(crate) fn iter_inspector_metadata(&self) -> ModifierInspectorIterator<'_> {
        match &self.kind {
            ModifierKind::Empty => ModifierInspectorIterator { inner: [].iter() },
            ModifierKind::Single { inspector, .. } => ModifierInspectorIterator {
                inner: inspector_slice(inspector).iter(),
            },
        }
    }

    #[cfg(test)]
    pub(crate) fn elements(&self) -> Vec<DynModifierElement> {
        match &self.kind {
            ModifierKind::Empty => Vec::new(),
            ModifierKind::Single { elements, .. } => elements.to_vec(),
        }
    }

    pub(crate) fn inspector_metadata(&self) -> Vec<InspectorMetadata> {
        match &self.kind {
            ModifierKind::Empty => Vec::new(),
            ModifierKind::Single { inspector, .. } => {
                inspector.as_deref().map(<[_]>::to_vec).unwrap_or_default()
            }
        }
    }

    /// Returns the largest of the four edge paddings, in logical pixels.
    pub fn total_padding(&self) -> f32 {
        let padding = self.padding_values();
        padding
            .left
            .max(padding.right)
            .max(padding.top)
            .max(padding.bottom)
    }

    /// Returns the size when both width and height are fixed lengths in logical pixels, or `None`
    /// otherwise.
    pub fn explicit_size(&self) -> Option<Size> {
        let props = self.layout_properties();
        match (props.width, props.height) {
            (DimensionConstraint::Points(width), DimensionConstraint::Points(height)) => {
                Some(Size { width, height })
            }
            _ => None,
        }
    }

    /// Returns the padding on each edge that the chain adds, in logical pixels.
    pub fn padding_values(&self) -> EdgeInsets {
        self.resolved_modifiers().padding()
    }

    pub(crate) fn layout_properties(&self) -> LayoutProperties {
        self.resolved_modifiers().layout_properties()
    }

    /// Returns the alignment set by [`Self::align`] for a `Box` parent, or `None` when none is set.
    pub fn box_alignment(&self) -> Option<Alignment> {
        self.layout_properties().box_alignment()
    }

    /// Returns the horizontal alignment set for a `Column` parent, or `None` when none is set.
    pub fn column_alignment(&self) -> Option<HorizontalAlignment> {
        self.layout_properties().column_alignment()
    }

    /// Returns the vertical alignment set for a `Row` parent, or `None` when none is set.
    pub fn row_alignment(&self) -> Option<VerticalAlignment> {
        self.layout_properties().row_alignment()
    }

    /// Returns the draw commands of the chain in the order they draw.
    pub fn draw_commands(&self) -> Vec<DrawCommand> {
        collect_slices_from_modifier(self).draw_commands().to_vec()
    }

    /// Returns whether the chain clips content to the node's bounds.
    pub fn clips_to_bounds(&self) -> bool {
        collect_slices_from_modifier(self).clip_to_bounds()
    }

    /// Returns structured inspector records for each modifier element.
    pub fn collect_inspector_records(&self) -> Vec<ModifierInspectorRecord> {
        self.inspector_metadata()
            .iter()
            .map(InspectorMetadata::to_record)
            .collect()
    }

    /// Resolves the chain into its padding, layout properties and offset.
    pub fn resolved_modifiers(&self) -> ResolvedModifiers {
        let mut handle = ModifierChainHandle::new();
        let _ = handle.update(self);
        handle.resolved_modifiers()
    }

    /// A modifier of the one `element`. Platform crates build their own
    /// modifiers on it, the way [`Modifier::window_root`] is built.
    pub fn with_element<E>(element: E) -> Self
    where
        E: ModifierNodeElement,
    {
        Self::from_dyn_element(modifier_element(element))
    }

    /// A modifier of the one `element`.
    pub(crate) fn from_dyn_element(element: DynModifierElement) -> Self {
        Self {
            provides_composition_locals: element.provides_composition_locals(),
            kind: ModifierKind::Single {
                elements: Elements::One(element),
                inspector: None,
            },
            element_count: 1,
        }
    }

    pub(crate) fn with_inspector_metadata(self, metadata: InspectorMetadata) -> Self {
        if metadata.is_empty() {
            return self;
        }
        match self.kind {
            ModifierKind::Empty => self,
            ModifierKind::Single {
                elements,
                inspector,
            } => {
                let new_inspector = inspector_slice(&inspector)
                    .iter()
                    .cloned()
                    .chain(std::iter::once(metadata))
                    .collect();
                Self {
                    kind: ModifierKind::Single {
                        elements,
                        inspector: Some(new_inspector),
                    },
                    element_count: self.element_count,
                    provides_composition_locals: self.provides_composition_locals,
                }
            }
        }
    }

    /// Checks whether two modifiers are structurally equivalent for layout decisions.
    ///
    /// This ignores identity-sensitive modifier elements (e.g., draw closures) so
    /// draw-only updates do not force measure/layout invalidation.
    pub fn structural_eq(&self, other: &Self) -> bool {
        self.eq_internal(other, false)
    }

    /// The update in place to `other`, when `other` has this modifier's
    /// elements in the same order, equal except elements that
    /// [`InPlaceReach::of`] accepts: how far it reaches, and the elements it
    /// updates. `None` when another element differs, or the chain is too
    /// long to name its elements; an element that asks for an update on
    /// every set counts as different.
    pub(crate) fn in_place_update(&self, other: &Self) -> Option<InPlaceUpdate> {
        if self.element_count != other.element_count || self.element_count > u64::BITS as usize {
            return None;
        }
        let mut update = InPlaceUpdate {
            reach: InPlaceReach::Node,
            elements: 0,
        };
        for (index, (a, b)) in self.iter_elements().zip(other.iter_elements()).enumerate() {
            if a.requires_update() || b.requires_update() {
                return None;
            }
            let element_type = a.element_type();
            match InPlaceReach::of(element_type) {
                // A text updates in place whether it changed or not.
                Some(InPlaceReach::Node) if b.element_type() == element_type => {
                    update.elements |= 1 << index;
                }
                Some(InPlaceReach::Resolved) if b.element_type() == element_type => {
                    if !same_element(a, b) {
                        update.reach = InPlaceReach::Resolved;
                        update.elements |= 1 << index;
                    }
                }
                _ => {
                    if !same_element(a, b) {
                        return None;
                    }
                }
            }
        }
        Some(update)
    }

    fn eq_internal(&self, other: &Self, consider_always_update: bool) -> bool {
        if self.element_count != other.element_count {
            return false;
        }

        match (&self.kind, &other.kind) {
            (ModifierKind::Empty, ModifierKind::Empty) => true,
            (
                ModifierKind::Single {
                    elements: e1,
                    inspector: _,
                },
                ModifierKind::Single {
                    elements: e2,
                    inspector: _,
                },
            ) => {
                if e1.shares_storage(e2) {
                    return true;
                }

                if e1.len() != e2.len() {
                    return false;
                }

                for (a, b) in e1.iter().zip(e2.iter()) {
                    // One element in both, as a kept chain shares them.
                    if Rc::ptr_eq(a, b) {
                        continue;
                    }
                    if !consider_always_update
                        && a.element_type() == b.element_type()
                        && a.capabilities() == NodeCapabilities::DRAW
                        && b.capabilities() == NodeCapabilities::DRAW
                    {
                        continue;
                    }

                    if consider_always_update && (a.requires_update() || b.requires_update()) {
                        if !Rc::ptr_eq(a, b) {
                            return false;
                        }
                        continue;
                    }

                    if !a.equals_element(&**b) {
                        return false;
                    }
                }

                true
            }
            _ => false,
        }
    }
}

impl PartialEq for Modifier {
    fn eq(&self, other: &Self) -> bool {
        self.eq_internal(other, true)
    }
}

impl Eq for Modifier {}

impl fmt::Display for Modifier {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match &self.kind {
            ModifierKind::Empty => write!(f, "Modifier.empty"),
            ModifierKind::Single { elements, .. } => {
                if elements.is_empty() {
                    return write!(f, "Modifier.empty");
                }
                write!(f, "Modifier[")?;
                for (index, element) in elements.iter().enumerate() {
                    if index > 0 {
                        write!(f, ", ")?;
                    }
                    let name = element.inspector_name();
                    let mut properties = Vec::new();
                    element.record_inspector_properties(&mut |prop, value| {
                        properties.push(format!("{prop}={value}"));
                    });
                    if properties.is_empty() {
                        write!(f, "{name}")?;
                    } else {
                        write!(f, "{name}({})", properties.join(", "))?;
                    }
                }
                write!(f, "]")
            }
        }
    }
}

impl fmt::Debug for Modifier {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self, f)
    }
}

#[cfg(test)]
#[path = "tests/modifier_tests.rs"]
mod tests;