SubmergeUI

SubmergeUI is a simple, flexible, and modular Rust UI library built on top of Bevy’s ECS framework. Designed for ease of use, it allows developers to create and style UI components using a Tailwind-like syntax. The goal of SubmergeUI is to make UI development straightforward and scalable in Rust.

Features

• Nested UI components: Create hierarchical UI layouts with ease by referencing components by ID, without the need for complex child nesting.
• Tailwind-like styling: Apply styles directly in a familiar, space-separated format for quick UI customization.
• Scalable design: Designed for both small and large projects, allowing for modular and customizable UI layouts.
• Custom utilities: Submerge comes with some custom styling utilities like predefined colors, text sizes, border radius, all based on tailwind css presets.

Getting Started

SubmergeUI provides an easy way to build and style nested UI components in Bevy. With minimal setup, you can start creating and styling components using intuitive syntax.

Installation

To add SubmergeUI to your project, include the following in your Cargo.toml:

[dependencies]
bevy = "0.14.2"
submergeui = "0.1"

Example: Creating and Styling a Button

Here’s how you can quickly set up a button with custom styles using SubmergeUI:

use bevy::prelude::*;
use submergeui::{SubmergeUIPlugin, SButtonBundle, ButtonStyleBundle};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(SubmergeUi)
        .add_systems(Startup, setup)
        .run();
}

fn setup_ui(mut commands: Commands) {
    // Creating a button with custom styles using Tailwind-like syntax
    let button_style = ButtonStyleBundle::apply_style(
        "border-5px justify_content-center align_items-center padding-15px border_color-white rounded-50% bg-red-100",
    );

    // Spawning a button with an ID for easy reference
    commands.spawn(SButtonBundle::new("play_button", button_style));
}

Creating Nested Components

SubmergeUI makes creating nested UI structures simple, using IDs to link components together:

fn setup_nested_ui(mut commands: Commands) {

	let text_style = TextStyle {
        font: asset_server.load("fonts/OpenSans-SemiBold.ttf"),
        font_size: SubmergeText::text(SubmergeText::LG),
        color: SubmergeColors::color(SubmergeColors::BLACK).into(),
    };

    // Create two buttons that will be children of the container
    let play_button_style = ButtonStyleBundle::apply_style(
        "border-5px justify_content-center align_items-center padding-15px border_color-white rounded-50% bg-red-100",
    );

    let another_play_button_style = ButtonStyleBundle::apply_style(
        "border-5px justify_content-center align_items-center padding-15px border_color-white rounded-50% bg-red-100",
    );

    commands.spawn(SButtonBundle::new("play_button", play_button_style).child("play_button_txt"));
    commands.spawn(
        SButtonBundle::new("another_play_button", another_play_button_style).child("another_play_button_txt"),
    );

    commands
        .spawn(STextBundle::from_section("First Button", text_style.clone()).id("play_button_txt"));
    commands.spawn(
        STextBundle::from_section("Another Button", text_style).id("another_play_button_txt"),
    );
}

Mixing and Matching with SubmergeUi styling and Bevy styling

SubmergeUI gives you the freedom of using both Submerge’s styling and Bevy’s standard styling to manipulate your UI(full code here):

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    let s_button_style: ButtonStyleBundle = ButtonStyleBundle {
        style: Style {
            border: UiRect::all(Val::Px(5.0)),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            padding: UiRect::all(Val::Px(15.0)),
            ..default()
        },
        border_color: BorderColor(Color::BLACK),
        border_radius: BorderRadius::all(SubmergeBR::radius(SubmergeBR::FULL)),
        background_color: SubmergeColors::color(SubmergeColors::RED100).into(),
        ..default()
    };

    let button_style = ButtonStyleBundle::apply_style(
        "border-5px justify_content-center align_items-center padding-15px border_color-white rounded-50% bg-red-100",
    );

    let text_style = TextStyle {
        font: asset_server.load("fonts/OpenSans-SemiBold.ttf"),
        font_size: SubmergeText::text(SubmergeText::LG),
        color: SubmergeColors::color(SubmergeColors::BLACK).into(),
    };

    let _container_style = ContainerStyleBundle {
        style: Style {
            width: Val::Percent(100.0),
            height: Val::Percent(100.0),
            align_items: AlignItems::Center,
            justify_content: JustifyContent::Center,
            ..default()
        },
        ..default()
    };

    // ui camera
    commands.spawn(Camera2dBundle::default());
    commands.spawn(
        SContainerBundle::new(
            "main_container",
            ContainerStyleBundle {
                style: Style {
                    width: Val::Percent(100.0),
                    height: Val::Percent(100.0),
                    align_items: AlignItems::Center,
                    justify_content: JustifyContent::Center,
                    ..default()
                },
                ..default()
            },
        )
        .children(["play_button", "another_play_button"]),
    );

    commands.spawn(SButtonBundle::new("play_button", button_style).child("play_button_txt"));
    commands.spawn(
        SButtonBundle::new("another_play_button", s_button_style).child("another_play_button_txt"),
    );

    commands
        .spawn(STextBundle::from_section("First Button", text_style.clone()).id("play_button_txt"));
    commands.spawn(
        STextBundle::from_section("Another Button", text_style).id("another_play_button_txt"),
    );
}

Styling with Tailwind-like Syntax

SubmergeUI allows you to style components easily with a Tailwind-inspired syntax. The style definitions are human-readable and allow quick customization without deep knowledge of Bevy's internal Style API:

let button_style = ButtonStyleBundle::apply_style(
    "border-2px padding-10px rounded-8px bg-yellow-200 text-center",
);

Utilities

Submerge provides a set of utility enums that simplify the styling of UI components. These include SubmergeText for font sizes, SubmergeColors for color definitions, and SubmergeBR for border radius settings. Each of these utilities follows the conventions used in Tailwind CSS, making them intuitive to use for developers familiar with that framework.

1. SubmergeText

The SubmergeText enum allows you to easily specify font sizes in your UI. Each variant represents a standard font size with an associated f32 value for size.

Enum Definition

pub enum SubmergeText {
    XS { size: f32 },
    SM { size: f32 },
    BASE { size: f32 },
    LG { size: f32 },
    XL { size: f32 },
    XL2 { size: f32 },
    XL3 { size: f32 },
    XL4 { size: f32 },
    XL5 { size: f32 },
    XL6 { size: f32 },
    XL7 { size: f32 },
    XL8 { size: f32 },
    XL9 { size: f32 },
}

Usage Example

let text_style = TextStyle {
    font: asset_server.load("fonts/OpenSans-SemiBold.ttf"),
    font_size: SubmergeText::text(SubmergeText::LG),
    color: SubmergeColors::color(SubmergeColors::BLACK).into(),
};

2. SubmergeColors

The SubmergeColors enum provides a range of color definitions based on the Tailwind CSS color palette. Each variant includes RGB values for the corresponding color.

Enum Definition

#[derive(Debug, Component)]
pub enum SubmergeColors {
    BLACK { r: f32, g: f32, b: f32 },
    WHITE { r: f32, g: f32, b: f32 },
    SLATE50 { r: f32, g: f32, b: f32 },
    SLATE100 { r: f32, g: f32, b: f32 },
    SLATE200 { r: f32, g: f32, b: f32 },
    SLATE300 { r: f32, g: f32, b: f32 },
    SLATE400 { r: f32, g: f32, b: f32 },
    // ... additional colors as needed
}

Usage Example

let s_button_style: ButtonStyleBundle = ButtonStyleBundle {
    style: Style {
        border: UiRect::all(Val::Px(5.0)),
        justify_content: JustifyContent::Center,
        align_items: AlignItems::Center,
        padding: UiRect::all(Val::Px(15.0)),
        ..default()
    },
    border_color: BorderColor(Color::BLACK),
    border_radius: BorderRadius::all(SubmergeBR::radius(SubmergeBR::FULL)),
    background_color: SubmergeColors::color(SubmergeColors::RED100).into(),
    ..default()
};

3. SubmergeBR

The SubmergeBR enum is designed for defining border radii, also based on Tailwind CSS presets. It offers various radius options for easy styling.

Enum Definition

#[derive(Debug)]
pub enum SubmergeBR {
    NONE { radius: f32 },
    SM { radius: f32 },
    DEFAULT { radius: f32 },
    MD { radius: f32 },
    LG { radius: f32 },
    XL { radius: f32 },
    XL2 { radius: f32 },
    XL3 { radius: f32 },
    FULL { radius: f32 },
}

Usage Example

let button_style: ButtonStyleBundle = ButtonStyleBundle {
    border_radius: BorderRadius::all(SubmergeBR::radius(SubmergeBR::FULL)),
    // Other styles...
};

These utilities provide a flexible and straightforward way to handle common styling tasks in your UI components, promoting consistency and ease of use. For further details and examples, please refer to the documentation or the source code.

Styling in SubmergeUI

The style definition uses a Tailwind-like system where each property or style is defined by a string and then applied to components. Here's a breakdown of the available style properties(check out the pest file for a more in-depth insight):

Documentation

For full API documentation, usage details, and more examples, refer to the SubmergeUI documentation.

License

This project is licensed under the MIT License.