lumen_primitives/

state_style.rs

//! State-driven text-color / opacity / box-shadow / background swaps.
//!
//! The CSS parser routes `:hover` / `:focus` / `:active` / `:disabled`
//! declarations for `text-color`, `opacity`, and `box-shadow` (plus
//! `bg` for `:disabled`) into a [`StateVisuals`] component (one
//! [`StatePatch`] per state); this module's [`apply_state_visuals`]
//! system swaps the live [`TextStyle`] / [`Opacity`] /
//! [`Visuals::shadows`] / [`Visuals::fill`] values as the interaction
//! markers come and go, holding them in
//! [`StyleOverrides`](lumen_core::style_overrides::StyleOverrides) and
//! letting go onto the element's own styles when every state ends. Swaps
//! snap (no tween), matching CSS state rules without a `transition` -
//! exactly like the border swap in [`crate::hover::apply_state_borders`].
//!
//! `:disabled` reacts to the
//! [`Disabled`](lumen_core::components::Disabled) marker at runtime
//! (Wave 3: `bind-disabled` can add / remove it live). Statically
//! disabled markup without a binding takes its `:disabled` styles as its
//! own computed style (`lumen_scene::computed`); the patch here drives
//! every dynamic case.
//! [`eject_interaction_on_disable`] strips `Hovered` / `Pressed` /
//! focus the moment an entity becomes disabled (moving keyboard focus
//! to the next focusable) so no interaction state lingers on a
//! greyed-out widget.

use bevy_ecs::prelude::*;
use lumen_core::components::{
    Color, Disabled, DocumentOrder, DropHovered, Fill, Opacity, ShadowSpec, TextStyle, Visuals,
};
use lumen_core::input::FocusVisible;
use lumen_core::prelude::*;
use lumen_core::style_overrides::{Live, StyleOverrides, StyleOwner, StyleValues};

/// One state's property patch. Only authored fields swap; the rest keep
/// the idle value.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct StatePatch {
    /// `:state { text-color: ... }`.
    pub text_color: Option<Color>,
    /// `:state { opacity: ... }`.
    pub opacity: Option<f32>,
    /// `:state { box-shadow: ... }` (full stack replacement).
    pub shadows: Option<Vec<ShadowSpec>>,
    /// `:state { bg: ... }` (solid fill replacement). Routed for
    /// `:disabled` today - hover / press backgrounds keep going through
    /// the tweened [`crate::hover::Interaction`] path.
    pub bg: Option<Color>,
}

impl StatePatch {
    /// `true` when no field is authored.
    pub fn is_empty(&self) -> bool {
        self.text_color.is_none()
            && self.opacity.is_none()
            && self.shadows.is_none()
            && self.bg.is_none()
    }
}

/// Author-set per-state style patches. Pressed wins over focused wins
/// over hovered on a per-field basis (mirrors the cascade order skins
/// author these rules in); disabled stamps over everything.
#[derive(Component, Clone, Debug, Default, PartialEq)]
#[require(StyleOverrides)]
pub struct StateVisuals {
    /// `:hover` patch.
    pub hover: StatePatch,
    /// `:focus` patch (any focus source).
    pub focus: StatePatch,
    /// `:focus-visible` patch - applies only while the `FocusVisible`
    /// marker is present (keyboard-driven focus). Wins over
    /// [`Self::focus`] per field.
    pub focus_visible: StatePatch,
    /// `:active` patch.
    pub active: StatePatch,
    /// `:drag-over` patch - applies while the entity carries the
    /// [`DropHovered`] marker (an acceptable in-app drag is hovering this
    /// drop target). HTML5 `dragover` parity.
    pub drag_over: StatePatch,
    /// `:disabled` patch - applies while the entity carries the
    /// [`Disabled`] marker. Wins over every other state (a disabled
    /// widget has no live interaction states anyway; see
    /// [`eject_interaction_on_disable`]).
    pub disabled: StatePatch,
}

impl StateVisuals {
    /// `true` when every state patch is empty (component not needed).
    pub fn is_empty(&self) -> bool {
        self.hover.is_empty()
            && self.focus.is_empty()
            && self.focus_visible.is_empty()
            && self.active.is_empty()
            && self.drag_over.is_empty()
            && self.disabled.is_empty()
    }
}

/// Marks an element whose state patch [`apply_state_visuals`] holds, and
/// names its layer in [`StyleOverrides`].
#[derive(Component, Clone, Copy, Debug, Default)]
pub struct StatePatched;

impl StyleOwner for StatePatched {
    const RANK: u8 = 30;
}

/// Plugin: registers [`eject_interaction_on_disable`] then
/// [`apply_state_visuals`].
pub struct StateStylePlugin;

impl Plugin for StateStylePlugin {
    fn build(self, app: &mut App) {
        // Ejection runs first (with a sync point in between) so the
        // `:disabled` swap on the disable tick lands on the true idle
        // style, not a half-faded hover tint.
        app.add_systems(
            TickStage::Systems,
            eject_interaction_on_disable.before(apply_state_visuals),
        );
        // `.after(dispatch_clicks)` (=> after `hit_test` too): flush the
        // Hovered / Pressed marker commands before the swap so `:hover`
        // / `:active` / `:disabled` styling reflects this tick's input.
        // No-op when `lumen-input` isn't installed.
        app.add_systems(
            TickStage::Systems,
            apply_state_visuals.after(lumen_input::dispatch_clicks),
        );
    }
}

/// Swap text color / opacity / shadows / background per interaction
/// state, and let them go when every state ends.
///
/// The swapped values are held in [`StyleOverrides`], so a restyle while a
/// state is on keeps them, and letting go lands on what the element's
/// styles say by then. Only the fields some active state authors are held;
/// the rest stay the element's own.
///
/// Every component this system attaches goes through `try_insert`. The
/// entity under the pointer is the one most likely to leave the tree on this
/// very tick: a click on a nav link runs the handler that swaps the page,
/// and the `<if>` reconciler despawns the outgoing tree in this same stage
/// with nothing ordering it against this system. A plain `insert` against an
/// element the swap already took away fails the whole command buffer rather
/// than just itself.
#[allow(clippy::type_complexity)]
pub fn apply_state_visuals(
    mut commands: Commands,
    pointer: Option<Res<PointerState>>,
    mut active: Query<
        (
            Entity,
            &StateVisuals,
            Option<&mut TextStyle>,
            Option<&mut Visuals>,
            Option<&Opacity>,
            &mut StyleOverrides,
            Has<StatePatched>,
            Option<&Hovered>,
            Option<&Focused>,
            Option<&lumen_core::input::FocusVisible>,
            Option<&Pressed>,
            Has<Disabled>,
            Has<DropHovered>,
        ),
        Or<(
            With<Hovered>,
            With<Focused>,
            With<Pressed>,
            With<Disabled>,
            With<DropHovered>,
        )>,
    >,
    mut idle: Query<
        (
            Entity,
            Option<&mut TextStyle>,
            Option<&mut Visuals>,
            Option<&Opacity>,
            &mut StyleOverrides,
        ),
        (
            With<StatePatched>,
            With<StateVisuals>,
            Without<Hovered>,
            Without<Focused>,
            Without<Pressed>,
            Without<Disabled>,
            Without<DropHovered>,
        ),
    >,
    mut orphaned: Query<
        (
            Entity,
            Option<&mut TextStyle>,
            Option<&mut Visuals>,
            Option<&Opacity>,
            &mut StyleOverrides,
        ),
        (With<StatePatched>, Without<StateVisuals>),
    >,
) {
    let primary_down = pointer.map(|p| p.primary_down).unwrap_or(false);
    for (
        entity,
        sv,
        text,
        vis,
        opacity,
        mut overrides,
        patched,
        hovered,
        focused,
        focus_visible,
        pressed,
        disabled,
        drag_over,
    ) in &mut active
    {
        // `:active` mirrors the press-tint contract (spec section 0 rule 3):
        // a pointer press dragged off the captured widget presents
        // un-pressed even though `Pressed` (the capture marker) stays.
        // Keyboard presses (pointer up) present pressed without hover.
        let active_on = pressed.is_some() && (hovered.is_some() || !primary_down);
        // Field-wise merge: hover < focus < focus-visible < active <
        // disabled (disabled stamps last).
        let mut patch = StatePatch::default();
        for (marker_on, p) in [
            (hovered.is_some(), &sv.hover),
            (focused.is_some(), &sv.focus),
            (
                focused.is_some() && focus_visible.is_some(),
                &sv.focus_visible,
            ),
            (active_on, &sv.active),
            (drag_over, &sv.drag_over),
            (disabled, &sv.disabled),
        ] {
            if !marker_on {
                continue;
            }
            if p.text_color.is_some() {
                patch.text_color = p.text_color;
            }
            if p.opacity.is_some() {
                patch.opacity = p.opacity;
            }
            if p.shadows.is_some() {
                patch.shadows = p.shadows.clone();
            }
            if p.bg.is_some() {
                patch.bg = p.bg;
            }
        }
        let values = StyleValues {
            text_color: patch.text_color.filter(|_| text.is_some()),
            opacity: patch.opacity.map(Some),
            shadows: patch.shadows.filter(|_| vis.is_some()),
            fill: patch
                .bg
                .filter(|_| vis.is_some())
                .map(|c| Some(Fill::Solid(c))),
            ..StyleValues::default()
        };
        let out = if values.fields().is_empty() {
            // Nothing to apply (an active marker whose patches are all
            // authored for other states - e.g. `Disabled` present but only
            // `:hover` styled).
            if !patched {
                continue;
            }
            commands.entity(entity).remove::<StatePatched>();
            overrides.release::<StatePatched>()
        } else {
            if overrides.held_by::<StatePatched>() == Some(&values) {
                continue;
            }
            if !patched {
                commands.entity(entity).try_insert(StatePatched);
            }
            let live = Live {
                style: None,
                visuals: vis.as_deref(),
                text: text.as_deref(),
                opacity,
            };
            overrides.hold::<StatePatched>(values, &live)
        };
        write_out(&mut commands, entity, &out, text, vis, opacity);
    }
    // Idle, or a restyle took the state patches away.
    for (entity, text, vis, opacity, mut overrides) in idle.iter_mut().chain(orphaned.iter_mut()) {
        let out = overrides.release::<StatePatched>();
        write_out(&mut commands, entity, &out, text, vis, opacity);
        commands.entity(entity).remove::<StatePatched>();
    }
}

/// Write `out` onto the element's text, paint and opacity.
fn write_out(
    commands: &mut Commands,
    entity: Entity,
    out: &StyleValues,
    text: Option<Mut<TextStyle>>,
    vis: Option<Mut<Visuals>>,
    opacity: Option<&Opacity>,
) {
    if let Some(mut t) = text {
        out.write_text(&mut t);
    }
    if let Some(mut v) = vis {
        out.write_visuals(&mut v);
    }
    match out.opacity_change(opacity) {
        Some(Some(o)) => {
            commands.entity(entity).try_insert(o);
        }
        Some(None) => {
            commands.entity(entity).remove::<Opacity>();
        }
        None => {}
    }
}

/// The moment an entity gains [`Disabled`] (spec section 0: runtime
/// enable/disable via `bind-disabled`), strip every live interaction
/// state from it:
///
/// * `Hovered` / `Pressed` are removed (with their transient tween
///   components) - the hover tint / press tint end immediately, and a
///   pending release will not click (`dispatch_clicks` requires
///   `Pressed`). The tinted fill is let go of at once, so the
///   `:disabled` swap lands on the true idle style.
/// * Keyboard focus moves to the next focusable in tab order (same
///   `(TabIndex, DocumentOrder)` ordering `cycle_focus_on_tab` uses,
///   wrapping; hidden and disabled entities skipped), or clears when
///   the disabled entity was the only focusable. The `FocusVisible`
///   marker travels with the focus if it was present.
#[allow(clippy::type_complexity, clippy::too_many_arguments)]
pub fn eject_interaction_on_disable(
    mut commands: Commands,
    newly_disabled: Query<Entity, Added<Disabled>>,
    mut tracker: ResMut<FocusTracker>,
    mut tinted: Query<(&mut Visuals, &mut StyleOverrides)>,
    focus_visibles: Query<(), With<FocusVisible>>,
    focusables: Query<(Entity, &TabIndex, Option<&DocumentOrder>), Without<Disabled>>,
    tab_info: Query<(&TabIndex, Option<&DocumentOrder>)>,
    parents: Query<&ChildOf>,
    visibles: Query<&lumen_core::components::Visible>,
    styles: Query<&lumen_core::components::Style>,
) {
    for entity in &newly_disabled {
        if let Ok((mut vis, mut overrides)) = tinted.get_mut(entity) {
            overrides
                .release::<crate::hover::HoverTween>()
                .write_visuals(&mut vis);
            overrides
                .release::<crate::hover::PressTween>()
                .write_visuals(&mut vis);
        }
        commands.entity(entity).remove::<(
            Hovered,
            Pressed,
            Focused,
            FocusVisible,
            crate::hover::HoverTween,
            crate::hover::PressTween,
        )>();

        if tracker.0 != Some(entity) {
            continue;
        }
        // Focus ejection: pick the next focusable after the disabled
        // entity in (TabIndex, DocumentOrder, Entity) order, wrapping.
        let mut sorted: Vec<(i32, u32, Entity)> = focusables
            .iter()
            .filter(|(e, t, _)| t.0 >= 0 && !hidden_via_ancestors(*e, &parents, &visibles, &styles))
            .map(|(e, t, doc)| (t.0, doc.map(|d| d.0).unwrap_or(u32::MAX), e))
            .collect();
        sorted.sort();
        let next = if sorted.is_empty() {
            None
        } else {
            let own_key = tab_info
                .get(entity)
                .map(|(t, doc)| (t.0, doc.map(|d| d.0).unwrap_or(u32::MAX), entity))
                .unwrap_or((i32::MIN, 0, entity));
            sorted
                .iter()
                .find(|k| **k > own_key)
                .or_else(|| sorted.first())
                .copied()
        };
        let had_visible = focus_visibles.contains(entity);
        match next {
            Some((_, _, next_e)) => {
                if had_visible {
                    commands.entity(next_e).insert((Focused, FocusVisible));
                } else {
                    commands.entity(next_e).insert(Focused);
                }
                tracker.0 = Some(next_e);
            }
            None => {
                tracker.0 = None;
            }
        }
    }
}

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

    fn shadow(blur: f32) -> ShadowSpec {
        ShadowSpec {
            offset_x: 0.0,
            offset_y: 1.0,
            blur,
            spread: 0.0,
            color: Color::rgb(0.0, 0.0, 0.0),
            inner: false,
        }
    }

    fn run(world: &mut World) {
        let mut schedule = bevy_ecs::schedule::Schedule::default();
        schedule.add_systems(apply_state_visuals);
        schedule.run(world);
        // Two passes: the first tick captures the base + queues the
        // command-applied writes.
        let mut schedule2 = bevy_ecs::schedule::Schedule::default();
        schedule2.add_systems(apply_state_visuals);
        schedule2.run(world);
    }

    /// Hover swaps text color + shadows in; un-hover restores; pressed
    /// wins over hover per field.
    #[test]
    fn state_text_color_opacity_shadow_swap_and_restore() {
        let mut world = World::new();
        let red = Color::rgb(1.0, 0.0, 0.0);
        let green = Color::rgb(0.0, 1.0, 0.0);
        let idle = Color::rgb(0.5, 0.5, 0.5);
        let e = world
            .spawn((
                StateVisuals {
                    hover: StatePatch {
                        text_color: Some(red),
                        opacity: Some(0.8),
                        shadows: Some(vec![shadow(4.0)]),
                        ..Default::default()
                    },
                    active: StatePatch {
                        text_color: Some(green),
                        ..Default::default()
                    },
                    ..Default::default()
                },
                TextStyle {
                    color: idle,
                    ..Default::default()
                },
                Visuals::default(),
            ))
            .id();

        // Hover -> patch applied.
        world.entity_mut(e).insert(Hovered);
        run(&mut world);
        assert_eq!(world.get::<TextStyle>(e).unwrap().color, red);
        assert_eq!(world.get::<Opacity>(e).map(|o| o.0), Some(0.8));
        assert_eq!(world.get::<Visuals>(e).unwrap().shadows, vec![shadow(4.0)]);

        // Hover + press -> active text color wins; hover opacity stays.
        world.entity_mut(e).insert(Pressed);
        run(&mut world);
        assert_eq!(world.get::<TextStyle>(e).unwrap().color, green);
        assert_eq!(world.get::<Opacity>(e).map(|o| o.0), Some(0.8));

        // All states end -> baseline restored, capture removed.
        world.entity_mut(e).remove::<Hovered>();
        world.entity_mut(e).remove::<Pressed>();
        run(&mut world);
        assert_eq!(world.get::<TextStyle>(e).unwrap().color, idle);
        assert!(world.get::<Opacity>(e).is_none(), "idle Opacity was absent");
        assert!(world.get::<Visuals>(e).unwrap().shadows.is_empty());
        assert!(world.get::<StatePatched>(e).is_none());
    }

    /// Focus ring: an `input:focus { box-shadow: ... }` rule (routed into
    /// `StateVisuals.focus.shadows`) swaps a real ring in when the input
    /// gains `Focused` and restores the idle stack on blur. The ring
    /// color/width comes entirely from the authored CSS shadow - no
    /// hardcoded Rust color - so a skin can drive it from a
    /// `--lumen-focus-ring` token. This is deliverable J's "focus ring
    /// driven by `:focus` tokens, not a hardcoded color".
    #[test]
    fn focus_ring_box_shadow_swaps_on_focus_and_restores_on_blur() {
        let mut world = World::new();
        let ring = ShadowSpec {
            offset_x: 0.0,
            offset_y: 0.0,
            blur: 0.0,
            spread: 2.0,
            // Token-sourced color - the CSS parser fills this from
            // `var(--lumen-focus-ring)`; the test just proves the swap.
            color: Color::rgba(0.2, 0.5, 1.0, 0.9),
            inner: false,
        };
        let e = world
            .spawn((
                StateVisuals {
                    focus: StatePatch {
                        shadows: Some(vec![ring]),
                        ..Default::default()
                    },
                    ..Default::default()
                },
                TextInput::default(),
                Visuals::default(),
            ))
            .id();

        // Focus -> ring shadow applied.
        world.entity_mut(e).insert(Focused);
        run(&mut world);
        assert_eq!(
            world.get::<Visuals>(e).unwrap().shadows,
            vec![ring],
            ":focus ring must swap in on Focused"
        );

        // Blur -> idle (empty) shadow stack restored.
        world.entity_mut(e).remove::<Focused>();
        run(&mut world);
        assert!(
            world.get::<Visuals>(e).unwrap().shadows.is_empty(),
            "focus ring must clear on blur"
        );
    }

    /// `:disabled` swaps bg + opacity in when the `Disabled` marker
    /// lands at runtime, and restores the exact idle values when the
    /// marker is removed (bind-disabled re-enable).
    #[test]
    fn disabled_patch_swaps_on_marker_add_and_restores_on_remove() {
        let mut world = World::new();
        let idle_bg = Color::rgb(0.1, 0.4, 0.9);
        let disabled_bg = Color::rgb(0.3, 0.3, 0.3);
        let e = world
            .spawn((
                StateVisuals {
                    disabled: StatePatch {
                        opacity: Some(0.5),
                        bg: Some(disabled_bg),
                        ..Default::default()
                    },
                    ..Default::default()
                },
                Visuals {
                    fill: Some(Fill::Solid(idle_bg)),
                    ..Default::default()
                },
            ))
            .id();

        // Disable -> bg + opacity swap in.
        world.entity_mut(e).insert(Disabled);
        run(&mut world);
        assert_eq!(
            world.get::<Visuals>(e).unwrap().fill,
            Some(Fill::Solid(disabled_bg)),
            ":disabled bg applied on marker add"
        );
        assert_eq!(world.get::<Opacity>(e).map(|o| o.0), Some(0.5));

        // Re-enable -> exact idle restored, capture removed.
        world.entity_mut(e).remove::<Disabled>();
        run(&mut world);
        assert_eq!(
            world.get::<Visuals>(e).unwrap().fill,
            Some(Fill::Solid(idle_bg)),
            "idle bg restored on marker remove"
        );
        assert!(world.get::<Opacity>(e).is_none());
        assert!(world.get::<StatePatched>(e).is_none());
    }

    /// Disabled wins over hover/press patches when markers coexist for
    /// a tick (before ejection strips them).
    #[test]
    fn disabled_patch_wins_over_hover() {
        let mut world = World::new();
        let red = Color::rgb(1.0, 0.0, 0.0);
        let grey = Color::rgb(0.4, 0.4, 0.4);
        let e = world
            .spawn((
                StateVisuals {
                    hover: StatePatch {
                        text_color: Some(red),
                        ..Default::default()
                    },
                    disabled: StatePatch {
                        text_color: Some(grey),
                        ..Default::default()
                    },
                    ..Default::default()
                },
                TextStyle::default(),
            ))
            .id();
        world.entity_mut(e).insert((Hovered, Disabled));
        run(&mut world);
        assert_eq!(world.get::<TextStyle>(e).unwrap().color, grey);
    }
}

#[cfg(test)]
mod eject_tests {
    //! `eject_interaction_on_disable` - becoming disabled strips
    //! `Hovered` / `Pressed` / focus and moves keyboard focus to the
    //! next focusable in tab order.
    use super::*;

    fn run(world: &mut World) {
        let mut schedule = bevy_ecs::schedule::Schedule::default();
        schedule.add_systems(eject_interaction_on_disable);
        schedule.run(world);
    }

    #[test]
    fn disable_strips_hover_press_and_moves_focus_forward() {
        let mut world = World::new();
        let a = world.spawn((TabIndex(0), DocumentOrder(0))).id();
        let b = world.spawn((TabIndex(0), DocumentOrder(1))).id();
        let c = world.spawn((TabIndex(0), DocumentOrder(2))).id();
        world.insert_resource(FocusTracker(Some(b)));
        world
            .entity_mut(b)
            .insert((Hovered, Pressed, Focused, FocusVisible, Disabled));

        run(&mut world);
        assert!(world.get::<Hovered>(b).is_none(), "hover stripped");
        assert!(world.get::<Pressed>(b).is_none(), "press stripped");
        assert!(world.get::<Focused>(b).is_none(), "focus stripped");
        assert_eq!(
            world.resource::<FocusTracker>().0,
            Some(c),
            "focus moved to the next focusable in document order"
        );
        assert!(world.get::<Focused>(c).is_some());
        assert!(
            world.get::<FocusVisible>(c).is_some(),
            "keyboard-visible focus travels with the ejection"
        );
        let _ = a;
    }

    #[test]
    fn disable_of_last_focusable_wraps_to_first() {
        let mut world = World::new();
        let a = world.spawn((TabIndex(0), DocumentOrder(0))).id();
        let b = world.spawn((TabIndex(0), DocumentOrder(1))).id();
        world.insert_resource(FocusTracker(Some(b)));
        world.entity_mut(b).insert((Focused, Disabled));
        run(&mut world);
        assert_eq!(world.resource::<FocusTracker>().0, Some(a), "wraps");
    }

    #[test]
    fn disable_of_only_focusable_clears_focus() {
        let mut world = World::new();
        let a = world.spawn((TabIndex(0), DocumentOrder(0))).id();
        world.insert_resource(FocusTracker(Some(a)));
        world.entity_mut(a).insert((Focused, Disabled));
        run(&mut world);
        assert_eq!(world.resource::<FocusTracker>().0, None);
    }

    #[test]
    fn disable_without_focus_leaves_tracker_alone() {
        let mut world = World::new();
        let a = world.spawn((TabIndex(0), DocumentOrder(0))).id();
        let b = world.spawn((TabIndex(0), DocumentOrder(1), Hovered)).id();
        world.insert_resource(FocusTracker(Some(a)));
        world.entity_mut(b).insert(Disabled);
        run(&mut world);
        assert_eq!(world.resource::<FocusTracker>().0, Some(a));
        assert!(world.get::<Hovered>(b).is_none());
    }
}