nightshade-api 0.44.1

//! Retained UI: panels anchored to the window that stack their children,
//! themed buttons, and labels, with click and hover queries. These build on the
//! same retained UI tree as [`spawn_text`](crate::prelude::spawn_text).

use crate::text::ScreenAnchor;
use crate::text::ui_root;
use nightshade::ecs::ui::layout_types::FlowDirection;
use nightshade::ecs::ui::units::UiValue;
use nightshade::prelude::*;

/// Spawns an empty panel anchored to a window corner or the center, sized in
/// pixels. It has a themed translucent background and stacks whatever you add to
/// it from top to bottom. Fill it with [`panel_button`] and [`panel_label`].
pub fn spawn_panel(world: &mut World, anchor: ScreenAnchor, width: f32, height: f32) -> Entity {
    let root = ui_root(world);
    let (position, anchor_kind) = panel_anchor(anchor);
    let panel = {
        let mut tree = UiTreeBuilder::from_parent(world, root);
        tree.add_node()
            .window(position, Ab(vec2(width, height)), anchor_kind)
            .with_rect(8.0, 1.0, Vec4::new(1.0, 1.0, 1.0, 0.1))
            .color_raw::<UiBase>(Vec4::new(0.05, 0.05, 0.08, 0.85))
            .flow(FlowDirection::Vertical, 12.0, 8.0)
            .entity()
    };
    ui_mark_render_dirty(world);
    panel
}

/// Adds a themed button to a panel and returns it. Poll it every frame with
/// [`button_clicked`].
pub fn panel_button(world: &mut World, panel: Entity, text: &str) -> Entity {
    let button = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_button(text)
    };
    ui_mark_render_dirty(world);
    button
}

/// Adds a line of text to a panel and returns it. Update it with
/// [`set_text`](crate::prelude::set_text) and restyle it with
/// [`set_text_color`](crate::prelude::set_text_color) and
/// [`set_text_size`](crate::prelude::set_text_size).
pub fn panel_label(world: &mut World, panel: Entity, text: &str) -> Entity {
    let label = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_node()
            .flow_child(Rl(vec2(100.0, 0.0)) + Ab(vec2(0.0, 24.0)))
            .with_text(text, 18.0)
            .color_raw::<UiBase>(Vec4::new(1.0, 1.0, 1.0, 1.0))
            .entity()
    };
    ui_mark_render_dirty(world);
    label
}

/// Adds a labeled checkbox to a panel and returns it. Read it with
/// [`checkbox_value`].
pub fn panel_checkbox(world: &mut World, panel: Entity, label: &str, initial: bool) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_checkbox(label, initial)
    };
    ui_mark_render_dirty(world);
    entity
}

/// The checkbox's current on or off value.
#[inline]
pub fn checkbox_value(world: &World, checkbox: Entity) -> bool {
    ui_checkbox_value(world, checkbox).unwrap_or(false)
}

/// Adds a slider from `min` to `max` starting at `initial` to a panel. Read it
/// with [`slider_value`], set it with [`set_slider_value`].
pub fn panel_slider(world: &mut World, panel: Entity, min: f32, max: f32, initial: f32) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_slider(min, max, initial)
    };
    ui_mark_render_dirty(world);
    entity
}

/// The slider's current value.
#[inline]
pub fn slider_value(world: &World, slider: Entity) -> f32 {
    ui_slider_value(world, slider).unwrap_or(0.0)
}

/// Sets the slider's value.
pub fn set_slider_value(world: &mut World, slider: Entity, value: f32) {
    ui_slider_set_value(world, slider, value);
    ui_mark_render_dirty(world);
}

/// Adds a single line text input with grey `placeholder` text to a panel. Read
/// edits with [`text_input_changed`].
pub fn panel_text_input(world: &mut World, panel: Entity, placeholder: &str) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_text_input(placeholder)
    };
    ui_mark_render_dirty(world);
    entity
}

/// The input's new contents if it changed this frame, else `None`.
#[inline]
pub fn text_input_changed(world: &World, input: Entity) -> Option<String> {
    ui_text_input_changed(world, input).map(str::to_string)
}

/// Adds a dropdown of `options` with `initial` selected to a panel. Read it with
/// [`dropdown_selected`].
pub fn panel_dropdown(
    world: &mut World,
    panel: Entity,
    options: &[&str],
    initial: usize,
) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_dropdown(options, initial)
    };
    ui_mark_render_dirty(world);
    entity
}

/// The newly chosen index if the dropdown selection changed this frame.
#[inline]
pub fn dropdown_selected(world: &World, dropdown: Entity) -> Option<usize> {
    ui_dropdown_selected_changed(world, dropdown)
}

/// Adds a progress bar filled to `initial` (0.0 to 1.0) to a panel. Update it
/// with [`set_progress`].
pub fn panel_progress_bar(world: &mut World, panel: Entity, initial: f32) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_progress_bar(initial)
    };
    ui_mark_render_dirty(world);
    entity
}

/// Sets a progress bar's fill, 0.0 to 1.0.
pub fn set_progress(world: &mut World, bar: Entity, value: f32) {
    ui_progress_bar_set_value(world, bar, value);
    ui_mark_render_dirty(world);
}

/// Adds an on or off toggle starting at `initial` to a panel. Read it with
/// [`toggle_value`].
pub fn panel_toggle(world: &mut World, panel: Entity, initial: bool) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_toggle(initial)
    };
    ui_mark_render_dirty(world);
    entity
}

/// The toggle's current on or off value.
#[inline]
pub fn toggle_value(world: &World, toggle: Entity) -> bool {
    ui_toggle_value(world, toggle).unwrap_or(false)
}

/// Adds a radio button to a panel, one option of a group identified by
/// `group_id`. Radios sharing a group are mutually exclusive. Read the group's
/// choice with [`radio_selected`].
pub fn panel_radio(
    world: &mut World,
    panel: Entity,
    label: &str,
    group_id: u32,
    option_index: usize,
) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_radio(label, group_id, option_index)
    };
    ui_mark_render_dirty(world);
    entity
}

/// The selected option index of a radio group, if any option is selected.
#[inline]
pub fn radio_selected(world: &World, group_id: u32) -> Option<usize> {
    ui_radio_group_value(world, group_id)
}

/// Adds a dual-handle range slider to a panel, selecting a span from `low` to
/// `high` within `min` and `max`. Set both handles with [`set_range`].
pub fn panel_range_slider(
    world: &mut World,
    panel: Entity,
    min: f32,
    max: f32,
    low: f32,
    high: f32,
) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_range_slider(min, max, low, high)
    };
    ui_mark_render_dirty(world);
    entity
}

/// Sets both handles of a range slider.
pub fn set_range(world: &mut World, slider: Entity, low: f32, high: f32) {
    ui_range_slider_set_values(world, slider, low, high);
    ui_mark_render_dirty(world);
}

/// Adds a tab bar of `labels` to a panel with `initial` selected. Switch the
/// active tab with [`set_tab`].
pub fn panel_tabs(world: &mut World, panel: Entity, labels: &[&str], initial: usize) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_tab_bar(labels, initial)
    };
    ui_mark_render_dirty(world);
    entity
}

/// Selects a tab bar's active tab by index.
pub fn set_tab(world: &mut World, tabs: Entity, index: usize) {
    ui_tab_bar_set_value(world, tabs, index);
    ui_mark_render_dirty(world);
}

/// Adds a collapsing section titled `label` to a panel and returns its content
/// container. Add child widgets to the returned entity; they hide and show as
/// the header is toggled.
pub fn panel_collapsing(world: &mut World, panel: Entity, label: &str, open: bool) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_collapsing_header(label, open)
    };
    ui_mark_render_dirty(world);
    entity
}

/// Adds a color picker to a panel starting at `initial` linear RGBA. Read the
/// chosen color with [`color_value`].
pub fn panel_color_picker(world: &mut World, panel: Entity, initial: [f32; 4]) -> Entity {
    let entity = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_color_picker(Vec4::new(initial[0], initial[1], initial[2], initial[3]))
    };
    ui_mark_render_dirty(world);
    entity
}

/// The color picker's current color as linear RGBA.
pub fn color_value(world: &World, picker: Entity) -> [f32; 4] {
    ui_color_picker_color(world, picker)
        .map(|color| [color.x, color.y, color.z, color.w])
        .unwrap_or([1.0, 1.0, 1.0, 1.0])
}

/// Whether the button was clicked this frame, a press and release on the same
/// button. Poll this every frame.
#[inline]
pub fn button_clicked(world: &World, button: Entity) -> bool {
    ui_clicked(world, button)
}

/// Whether the pointer is currently over the button.
#[inline]
pub fn button_hovered(world: &World, button: Entity) -> bool {
    world
        .ui
        .get_ui_node_interaction(button)
        .is_some_and(|interaction| interaction.hovered)
}

/// Removes a panel and everything in it.
#[inline]
pub fn despawn_panel(world: &mut World, panel: Entity) {
    despawn_recursive_immediate(world, panel);
    ui_mark_render_dirty(world);
}

/// Adds a horizontal row to a panel and returns it. Widgets added to the row
/// lay out left to right instead of the panel's top to bottom stacking, which is
/// how you put a label next to a value or a run of buttons on one line.
pub fn panel_row(world: &mut World, panel: Entity, height: f32) -> Entity {
    let row = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_node()
            .flow_child(Rl(vec2(100.0, 0.0)) + Ab(vec2(0.0, height)))
            .flow(FlowDirection::Horizontal, 0.0, 8.0)
            .entity()
    };
    ui_mark_render_dirty(world);
    row
}

/// Adds a fixed-column grid to a panel and returns it. Children flow into
/// `columns` cells of `row_height`, wrapping to a new row as they fill, for
/// inventory grids, palettes, and icon sheets.
pub fn panel_grid(
    world: &mut World,
    panel: Entity,
    columns: usize,
    row_height: f32,
    height: f32,
) -> Entity {
    let grid = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        tree.add_node()
            .flow_child(Rl(vec2(100.0, 0.0)) + Ab(vec2(0.0, height)))
            .grid(columns, row_height, 0.0, 8.0, 8.0)
            .entity()
    };
    ui_mark_render_dirty(world);
    grid
}

/// Adds a scrollable region of the given pixel `height` to a panel and returns
/// its content container. Add widgets to the returned entity; when they exceed
/// the height the region scrolls with the mouse wheel and a draggable thumb.
/// This is what dense inventory and dialogue lists need.
pub fn panel_scroll(world: &mut World, panel: Entity, height: f32) -> Entity {
    let content = {
        let mut tree = UiTreeBuilder::from_parent(world, panel);
        let area = tree.add_scroll_area(vec2(0.0, height));
        widget::<UiScrollAreaData>(tree.world_mut(), area)
            .map(|data| data.content_entity)
            .unwrap_or(area)
    };
    ui_mark_render_dirty(world);
    content
}

/// Scrolls a [`panel_scroll`] region (pass the panel-scroll entity, not the
/// content) to a pixel offset from the top.
pub fn set_scroll_offset(world: &mut World, scroll_area: Entity, offset: f32) {
    ui_scroll_area_set_offset(world, scroll_area, offset);
    ui_mark_render_dirty(world);
}

/// Sets a widget's keyboard focus order. Widgets with a focus order participate
/// in Tab navigation, lowest order first. Use it to make a form's fields step
/// in a sensible sequence.
pub fn set_focus_order(world: &mut World, entity: Entity, order: i32) {
    if let Some(interaction) = world.ui.get_ui_node_interaction_mut(entity) {
        interaction.tab_index = Some(order);
    }
}

/// Gives keyboard focus to a widget immediately, as if the user had tabbed to
/// it. Useful to focus the first field when a form opens.
pub fn focus_widget(world: &mut World, entity: Entity) {
    world.resources.retained_ui.interaction.focused_entity = Some(entity);
}

fn panel_anchor(anchor: ScreenAnchor) -> (UiValue<Vec2>, Anchor) {
    match anchor {
        ScreenAnchor::TopLeft => (Ab(vec2(20.0, 20.0)).into(), Anchor::TopLeft),
        ScreenAnchor::TopCenter => (Rl(vec2(50.0, 0.0)) + Ab(vec2(0.0, 20.0)), Anchor::TopCenter),
        ScreenAnchor::TopRight => (
            Rl(vec2(100.0, 0.0)) + Ab(vec2(-20.0, 20.0)),
            Anchor::TopRight,
        ),
        ScreenAnchor::BottomLeft => (
            Rl(vec2(0.0, 100.0)) + Ab(vec2(20.0, -20.0)),
            Anchor::BottomLeft,
        ),
        ScreenAnchor::BottomCenter => (
            Rl(vec2(50.0, 100.0)) + Ab(vec2(0.0, -20.0)),
            Anchor::BottomCenter,
        ),
        ScreenAnchor::BottomRight => (
            Rl(vec2(100.0, 100.0)) + Ab(vec2(-20.0, -20.0)),
            Anchor::BottomRight,
        ),
        ScreenAnchor::Center => (Rl(vec2(50.0, 50.0)).into(), Anchor::Center),
    }
}

/// The anchor's relative base position (as a percentage for [`Rl`]) and engine
/// anchor, with no margin, so a caller can add its own pixel offset.
fn anchor_base(anchor: ScreenAnchor) -> (Vec2, Anchor) {
    match anchor {
        ScreenAnchor::TopLeft => (vec2(0.0, 0.0), Anchor::TopLeft),
        ScreenAnchor::TopCenter => (vec2(50.0, 0.0), Anchor::TopCenter),
        ScreenAnchor::TopRight => (vec2(100.0, 0.0), Anchor::TopRight),
        ScreenAnchor::BottomLeft => (vec2(0.0, 100.0), Anchor::BottomLeft),
        ScreenAnchor::BottomCenter => (vec2(50.0, 100.0), Anchor::BottomCenter),
        ScreenAnchor::BottomRight => (vec2(100.0, 100.0), Anchor::BottomRight),
        ScreenAnchor::Center => (vec2(50.0, 50.0), Anchor::Center),
    }
}

fn rgba(color: [f32; 4]) -> Vec4 {
    Vec4::new(color[0], color[1], color[2], color[3])
}

const PANEL_BORDER: Vec4 = Vec4::new(0.12, 0.14, 0.2, 0.7);
const PANEL_SHADOW: Vec4 = Vec4::new(0.0, 0.0, 0.0, 0.55);

/// Spawns a panel anchored to any of the nine screen positions at a pixel
/// `offset` from that anchor, `size` pixels large, filled with `color`. Unlike
/// [`spawn_panel`] this gives full control over placement, size, and color for a
/// custom HUD; fill it with absolutely positioned [`panel_text`], [`panel_box`],
/// and [`panel_button_at`] children. Returns the panel entity.
pub fn spawn_panel_at(
    world: &mut World,
    anchor: ScreenAnchor,
    offset: Vec2,
    size: Vec2,
    color: [f32; 4],
) -> Entity {
    let root = ui_root(world);
    let (base, anchor_kind) = anchor_base(anchor);
    let panel = {
        let mut tree = UiTreeBuilder::from_parent(world, root);
        tree.add_node()
            .window(Rl(base) + Ab(offset), Ab(size), anchor_kind)
            .with_rect(10.0, 1.5, PANEL_BORDER)
            .color_raw::<UiBase>(rgba(color))
            .with_shadow(PANEL_SHADOW, vec2(0.0, 6.0), 18.0, 0.0)
            .entity()
    };
    ui_mark_render_dirty(world);
    panel
}

/// Adds a text label to `parent` in the pixel rectangle `rect` (`[x, y, width,
/// height]` from the parent's top left), at `font_size` in `color` with the
/// given horizontal alignment. Returns the label entity; update it with
/// [`set_panel_text`] and recolor it with [`set_panel_text_color`].
pub fn panel_text(
    world: &mut World,
    parent: Entity,
    text: &str,
    rect: [f32; 4],
    font_size: f32,
    color: [f32; 4],
    align: TextAlignment,
) -> Entity {
    let label = {
        let mut tree = UiTreeBuilder::from_parent(world, parent);
        tree.add_node()
            .window(
                Ab(vec2(rect[0], rect[1])),
                Ab(vec2(rect[2], rect[3])),
                Anchor::TopLeft,
            )
            .with_text(text, font_size)
            .with_text_alignment(align, VerticalAlignment::Middle)
            .color_raw::<UiBase>(rgba(color))
            .without_pointer_events()
            .entity()
    };
    ui_mark_render_dirty(world);
    label
}

/// Adds a solid colored rectangle to `parent` at a pixel `offset`, sized `size`.
/// Use it for bars, swatches, and dividers. Resize it with [`set_panel_rect`]
/// and recolor it with [`set_panel_color`].
pub fn panel_box(
    world: &mut World,
    parent: Entity,
    offset: Vec2,
    size: Vec2,
    color: [f32; 4],
) -> Entity {
    let box_entity = {
        let mut tree = UiTreeBuilder::from_parent(world, parent);
        tree.add_node()
            .window(Ab(offset), Ab(size), Anchor::TopLeft)
            .with_rect(6.0, 0.0, Vec4::new(0.0, 0.0, 0.0, 0.0))
            .color_raw::<UiBase>(rgba(color))
            .without_pointer_events()
            .entity()
    };
    ui_mark_render_dirty(world);
    box_entity
}

/// Adds an interactive button to `parent` at a pixel `offset`, sized `size`,
/// with a centered `label` (pass `""` for none and add your own children). It
/// has themed hover and press states and a selected state for
/// [`set_panel_selected`]. Poll it with [`button_clicked`]. Returns the button.
pub fn panel_button_at(
    world: &mut World,
    parent: Entity,
    label: &str,
    offset: Vec2,
    size: Vec2,
) -> Entity {
    let button = {
        let mut tree = UiTreeBuilder::from_parent(world, parent);
        tree.add_node()
            .window(Ab(offset), Ab(size), Anchor::TopLeft)
            .with_rect(8.0, 1.5, PANEL_BORDER)
            .color_raw::<UiBase>(Vec4::new(0.05, 0.06, 0.09, 0.92))
            .color_raw::<UiHover>(Vec4::new(0.09, 0.11, 0.17, 0.95))
            .color_raw::<UiPressed>(Vec4::new(0.04, 0.05, 0.08, 1.0))
            .with_transition::<UiHover>(12.0, 6.0)
            .with_transition::<UiPressed>(18.0, 10.0)
            .with_transition::<UiSelected>(10.0, 5.0)
            .with_interaction()
            .entity()
    };
    if !label.is_empty() {
        let mut tree = UiTreeBuilder::from_parent(world, button);
        tree.add_node()
            .window(Rl(vec2(50.0, 50.0)), Ab(size), Anchor::Center)
            .with_text(label, 14.0)
            .with_text_alignment(TextAlignment::Center, VerticalAlignment::Middle)
            .color_raw::<UiBase>(Vec4::new(0.92, 0.94, 1.0, 1.0))
            .without_pointer_events()
            .entity();
    }
    ui_mark_render_dirty(world);
    button
}

/// Repositions and resizes a UI node within its parent, in pixels. Drives a bar
/// fill or any element that changes size at runtime.
pub fn set_panel_rect(world: &mut World, node: Entity, offset: Vec2, size: Vec2) {
    if let Some(layout) = world.ui.get_ui_layout_node_mut(node) {
        layout.base_layout = Some(UiLayoutType::Window(WindowLayout {
            position: Ab(offset).into(),
            size: Ab(size).into(),
            anchor: Anchor::TopLeft,
        }));
    }
    ui_mark_render_dirty(world);
}

/// Sets a UI node's background color (linear RGBA), for panels, boxes, and bars.
pub fn set_panel_color(world: &mut World, node: Entity, color: [f32; 4]) {
    if let Some(node_color) = world.ui.get_ui_node_color_mut(node) {
        node_color.colors[UiBase::INDEX] = Some(rgba(color));
    }
    ui_mark_render_dirty(world);
}

/// Replaces a [`panel_text`] label's content. Skips work when unchanged, so it
/// is fine to call every frame with a formatted string.
pub fn set_panel_text(world: &mut World, label: Entity, text: &str) {
    ui_set_text(world, label, text);
}

/// Recolors a [`panel_text`] label.
pub fn set_panel_text_color(world: &mut World, label: Entity, color: [f32; 4]) {
    set_panel_color(world, label, color);
}

/// Toggles a button's selected highlight, tinting it with `accent` while
/// selected. Use it to show the active choice in a row of options.
pub fn set_panel_selected(world: &mut World, button: Entity, selected: bool, accent: [f32; 4]) {
    if let Some(node_color) = world.ui.get_ui_node_color_mut(button) {
        node_color.colors[UiSelected::INDEX] = Some(rgba(accent));
    }
    ui_set_selected(world, button, selected);
    ui_mark_render_dirty(world);
}

/// Shows or hides a UI node and its children, for toggling overlays like a wave
/// banner or a game over panel.
pub fn set_panel_visible(world: &mut World, node: Entity, visible: bool) {
    ui_set_visible(world, node, visible);
    ui_mark_render_dirty(world);
}