Tessera UI

https://tessera-ui.github.io/guide/
Admin
Tessera UI is a Rust UI framework that provides a comprehensive set of components for building user...
Tokens:4,980
Snippets:33
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setting up Router Root Component (Rust)

Source: https://tessera-ui.github.io/guide/shard

Provides an example of using the 'router_root' component to render the current navigation destination. It shows how to initialize the application with a starting destination like 'HomePageDestination'.

```rust
pub fn router_root(root_dest: impl RouterDestination + 'static)

Renderer::run_with_config(
    || router_root(HomePageDestination { num: 0 }),
    |app| {
        tessera_ui_basic_components::pipelines::register_pipelines(app);
    },
    config,
)
.unwrap();
```

--------------------------------

### Initialize Tessera Renderer in Rust

Source: https://tessera-ui.github.io/guide/getting-started

Sets up the main entry point for a Tessera application by creating and running a `Renderer`. It configures window properties and registers necessary pipelines.

```rust
use tessera_ui::{Renderer, renderer::TesseraConfig};

fn main() {
    // Configure the renderer here
    let config = TesseraConfig {
        window_title: "Tessera Example".to_string(), // Window title
        ..Default::default()                         // Use default values for other settings
    };
    Renderer::run_with_config(
        || {}, // UI entry function—implemented in the next step; pass an empty closure for now
        |app| {
            tessera_ui_basic_components::pipelines::register_pipelines(app); // Register pipelines required by tessera-ui-basic-components
        },
        config,
    )
    .unwrap();
}
```

--------------------------------

### Create New Rust Project with Cargo

Source: https://tessera-ui.github.io/guide/getting-started

Initializes a new Rust project using Cargo, the Rust package manager. This sets up the basic directory structure for a new application.

```bash
cargo new my-tessera-app
cd my-tessera-app
```

--------------------------------

### Add Tessera UI Dependencies with Cargo

Source: https://tessera-ui.github.io/guide/getting-started

Adds the `tessera-ui` and `tessera-ui-basic-components` crates to the project's dependencies using Cargo. These are essential for building a Tessera UI application.

```bash
cargo add tessera-ui
cargo add tessera-ui-basic-components
```

--------------------------------

### Manual Navigation Example (Rust)

Source: https://tessera-ui.github.io/guide/shard

Demonstrates a basic, albeit verbose, approach to switching between pages using a match statement on the current page state. This method is prone to errors and lacks advanced navigation features.

```rust
match current_page {
    Page::Home => home_page(page_state),
    Page::About => about_page(page_state),
    Page::Settings => settings_page(page_state),
}
```

--------------------------------

### Defining a Component with Parameters

Source: https://tessera-ui.github.io/guide/component

Demonstrates how to create components that accept parameters, allowing for dynamic UI elements.

```APIDOC
## Defining a Component with Parameters

### Description
Component functions can accept parameters like regular Rust functions. These parameters can be used to customize the component's behavior or appearance.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
N/A

```rust
use tessera_ui::tessera;
use tessera_ui_basic_components::text::text;

#[tessera]
fn component(name: String, age: u32) {
    text(format!("Hello, {}! You are {} years old.", name, age));
}
```
```

--------------------------------

### Add Text Component in Rust

Source: https://tessera-ui.github.io/guide/getting-started

This Rust code snippet shows how to add a text component displaying 'Hello, World!' to a Tessera UI application. It includes setting up the renderer with a window title and registering necessary pipelines from tessera-ui-basic-components. The `app` function defines a white background surface that contains the 'Hello, World!' text.

```rust
use tessera_ui::{Color, DimensionValue, Renderer, renderer::TesseraConfig, tessera};
use tessera_ui_basic_components::{surface::{surface, SurfaceArgsBuilder}, text::text};

fn main() {
    // Configure the renderer here
    let config = TesseraConfig {
        window_title: "Tessera Example".to_string(), // Window title
        ..Default::default()                         // Use default values for other settings
    };
    Renderer::run_with_config(
        || app(), // UI entry function is placed in app below; you can also write it inline
        |app| {
            tessera_ui_basic_components::pipelines::register_pipelines(app); // Register pipelines required by tessera-ui-basic-components
        },
        config,
    )
    .unwrap();
}

#[tessera]
fn app() {
    surface(
        SurfaceArgsBuilder::default()
            .color(Color::WHITE) // Background color
            .width(DimensionValue::FILLED) // Fill parent width
            .height(DimensionValue::FILLED) // Fill parent height
            .build()
            .unwrap(),
        None, // Ripple state for click animations; None for background surface
        || {
            text("Hello, World!") // HELLO THERE :)
        },
    );
}
```

--------------------------------

### Create a White Background Tessera Component in Rust

Source: https://tessera-ui.github.io/guide/getting-started

Defines a simple `tessera` component named `app` that renders a maximized white surface as the application's background. It uses `SurfaceArgsBuilder` to configure the surface's color and dimensions.

```rust
use tessera_ui::{Color, DimensionValue, Renderer, renderer::TesseraConfig, tessera};
use tessera_ui_basic_components::surface::{SurfaceArgsBuilder, surface};

fn main() {
    // Configure the renderer here
    let config = TesseraConfig {
        window_title: "Tessera Example".to_string(), // Window title
        ..Default::default()                         // Use default values for other settings
    };
    Renderer::run_with_config(
        || app(), // UI entry function; app is the top-level tessera
        |app| {
            tessera_ui_basic_components::pipelines::register_pipelines(app); // Register pipelines required by tessera-ui-basic-components
        },
        config,
    )
    .unwrap();
}

#[tessera]
fn app() {
    surface(
        SurfaceArgsBuilder::default()
            .color(Color::WHITE) // Background color
            .width(DimensionValue::FILLED) // Fill parent width
            .height(DimensionValue::FILLED) // Fill parent height
            .build()
            .unwrap(),
        None, // Ripple state for click animations; None for background surface
        || {
            // surface is a container; place child content here; empty for now
        },
    );
}
```

--------------------------------

### Defining a Basic Component

Source: https://tessera-ui.github.io/guide/component

This section explains how to define a fundamental UI component in Tessera using the `#[tessera]` macro.

```APIDOC
## Defining a Basic Component

### Description
Components are the core building blocks of the UI in Tessera. You define a component by creating a Rust function and annotating it with the `#[tessera]` macro.

### Method
N/A (This is a code definition, not an API endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```rust
use tessera_ui::tessera;

#[tessera]
fn component() {
    // Component implementation
}
```
```

--------------------------------

### Measure and place child components

Source: https://tessera-ui.github.io/guide/component

Provides an example of a custom layout logic within a Tessera component. It measures a child's size, places it at a specific position, and returns the component's own size.

```rust
#[tessera]
fn component(child: impl FnOnce()) {
    child(); // compose child component
    measure(Box::new(|input| {
        let child_node_id = input.children_ids[0];
        let child_size = input.measure_child(child_node_id, input.parent_constraint)?;
        input.place_child(child_node_id, PxPosition::new(Px(0), Px(0)));
        Ok(
            ComputedData {
                width: child_size.width + Px(10),
                height: child_size.height + Px(10),
            }
        )
    }))
}
```

--------------------------------

### Component Composition

Source: https://tessera-ui.github.io/guide/component

Explains how to build complex UIs by nesting or calling one component from within another.

```APIDOC
## Component Composition

### Description
Composition is achieved by calling one component function from another. This allows for building complex UIs by combining simpler components.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```rust
use tessera_ui::tessera;

#[tessera]
fn parent_component() {
    child_component(); // Calling another component
}

#[tessera]
fn child_component() {
    // Child component content
}
```
By default, composed components are rendered at the top-left corner. For custom layouts, refer to the measure-place system.
```

--------------------------------

### Define a basic Tessera component

Source: https://tessera-ui.github.io/guide/component

Demonstrates the simplest way to define a Tessera component by marking a Rust function with the `#[tessera]` macro.

```rust
use tessera_ui::tessera;

#[tessera]
fn component() {

}
```

--------------------------------

### Handle input events with input_handler

Source: https://tessera-ui.github.io/guide/component

Shows how to use the `input_handler` function, injected by the `#[tessera]` macro, to manage external input events. This example blocks mouse events from propagating to components below the current one.

```rust
#[tessera]
fn component() {
    input_handler(Box::new(|mut input | {
        input.block_cursor();
    }))
}
```

--------------------------------

### Programmatic Navigation with Router (Rust)

Source: https://tessera-ui.github.io/guide/shard

Shows how to programmatically navigate to different destinations using the global Router. It demonstrates pushing a 'HomePageDestination' with a parameter onto the navigation stack.

```rust
// Router is a global singleton, accessible via Router::with_mut / Router::with
Router::with_mut(|router| {
    router.push(HomePageDestination { num: 42 });
});
```

--------------------------------

### Input Handling with `input_handler`

Source: https://tessera-ui.github.io/guide/component

Shows how to handle external input events, such as mouse or keyboard interactions, within a component.

```APIDOC
## Input Handling with `input_handler`

### Description
The `#[tessera]` macro injects an `input_handler` function, allowing components to respond to user input events. This can be used for interactivity or to control event propagation.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```rust
#[tessera]
fn component() {
    input_handler(Box::new(|mut input| {
        // Input handling logic, e.g., blocking cursor events
        input.block_cursor();
    }))
}
```
```

--------------------------------

### Define a component with parameters

Source: https://tessera-ui.github.io/guide/component

Shows how to define a Tessera component that accepts parameters. These parameters can be of any Rust type and are used within the component's logic.

```rust
use tessera_ui::tessera;
use tessera_ui_basic_components::text::text;

#[tessera]
fn component(name: String, age: u32) {
    text(format!("Hello, {}! You are {} years old.", name, age));
}
```

--------------------------------

### Create a container component

Source: https://tessera-ui.github.io/guide/component

Explains how to create container components in Tessera UI that accept child components as closures. This is useful when the child component is not known at compile time.

```rust
use tessera_ui::tessera;

#[tessera]
fn parent_component(child: impl FnOnce()) {
    child();
}

#[tessera]
fn child_component() {
    // child component content
}

fn app() {
    parent_component(|| {
        child_component();
    });
}
```

--------------------------------

### Custom Layout with Measure-Place

Source: https://tessera-ui.github.io/guide/component

Explains how to override default layout behavior using the measure-place system for custom sizing and positioning.

```APIDOC
## Custom Layout with Measure-Place

### Description
Tessera's layout system involves two phases: measure (determining size) and place (determining position). You can customize this by calling `measure` within your component.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```rust
use tessera_ui::tessera;

#[tessera]
fn component() {
    // Call measure with a closure for custom measurement and placement
    measure(Box::new(|input| {
        // Measurement and placement logic here
        // For example, measure a child and place it
        let child_node_id = input.children_ids[0];
        let child_size = input.measure_child(child_node_id, input.parent_constraint)?;
        input.place_child(child_node_id, PxPosition::new(Px(0), Px(0)));
        Ok(ComputedData {
            width: child_size.width + Px(10),
            height: child_size.height + Px(10),
        })
    }))
}
```
**Important:** Ensure that you measure children before placing them and that you place all measured children. Failure to do so can lead to runtime panics. Components without explicit layout logic use default top-left placement.
```

--------------------------------

### Container Components

Source: https://tessera-ui.github.io/guide/component

Details how to create container components that accept child components as closures, useful when the child is not known beforehand.

```APIDOC
## Container Components

### Description
Container components accept child components as closures. This pattern is useful when the specific child component is determined at runtime or passed as an argument.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

```rust
use tessera_ui::tessera;

#[tessera]
fn parent_component(child: impl FnOnce()) {
    child(); // Executes the passed child component closure
}

#[tessera]
fn child_component() {
    // Child component content
}

fn app() {
    parent_component(|| {
        child_component();
    });
}
```
```

--------------------------------

### Compose components by calling functions

Source: https://tessera-ui.github.io/guide/component

Illustrates how to compose components in Tessera UI by simply calling one component function from within another. This is the primary method for building complex UIs from smaller parts.

```rust
use tessera_ui::tessera;

#[tessera]
fn parent_component() {
    child_component();
}

#[tessera]
fn child_component() {
    // child component content
}
```

--------------------------------

### Marking a Component as a Shard

Source: https://tessera-ui.github.io/guide/shard

Demonstrates how to use the `#[shard]` and `#[tessera]` macros to designate a Rust function as a shard, which is a page-like component in Tessera UI. This is the fundamental step for enabling shard functionalities.

```rust
#[shard]
#[tessera]
fn about_page() {
    // page content...
}
```

--------------------------------

### Register Window Close Callback in Rust

Source: https://tessera-ui.github.io/guide/component

Registers a callback function to be executed when the window close event is triggered. The callback takes no arguments. Requires the `tessera` crate.

```rust
use tessera::Tessera;

fn main() {
    Tessera::new();
    tessera::on_close(Box::new(|| {
        println!("Window close requested.");
    }));
}
```

--------------------------------

### Using #[shard] for Navigation and Destination Types (Rust)

Source: https://tessera-ui.github.io/guide/shard

Illustrates how the #[shard] macro simplifies navigation by automatically generating type-safe destination types. It shows defining shards like 'about_page' and 'home_page' and the resulting destination structs with parameters.

```rust
#[shard]
#[tessera]
fn about_page(#[state] state: AboutPageState) {
    // page content...
}

#[shard]
#[tessera]
fn home_page(num: i32) {
    // page content...
}
```

```rust
struct AboutPageDestination;
struct HomePageDestination {
    num: i32,
}
```

--------------------------------

### Implement custom component measurement

Source: https://tessera-ui.github.io/guide/component

Demonstrates how to override the default measurement behavior of a component by providing a custom `measure` closure. This closure defines how the component calculates its size based on its children and parent constraints.

```rust
use tessera_ui::tessera;

#[tessera]
fn component() {
    measure(Box::new(|input| {
        // measurement logic here
    }))
}
```

--------------------------------

### Register Window Minimize Callback in Rust

Source: https://tessera-ui.github.io/guide/component

Registers a callback function to be executed when the window's minimize state changes. The callback receives a boolean indicating whether the window is minimized. Requires the `tessera` crate.

```rust
use tessera::Tessera;

fn main() {
    Tessera::new();
    tessera::on_minimize(Box::new(|is_minimized: bool| {
        println!("Window minimized: {}", is_minimized);
    }));
}
```

--------------------------------

### State Lifetime: 'shard' (Rust)

Source: https://tessera-ui.github.io/guide/shard

Demonstrates setting the lifetime of injected state to 'shard' using the #[state(shard)] attribute. This ensures the state is destroyed when the associated shard is popped from the navigation stack.

```rust
#[shard]
#[tessera]
fn about_page(#[state(shard)] state: AboutPageState) {
    // page content...
}
```

--------------------------------

### Injecting State into a Shard

Source: https://tessera-ui.github.io/guide/shard

Illustrates how to define a state structure for a shard and inject it into the component using the `#[state]` attribute. This allows the shard to manage its own state without explicit passing from the caller, simplifying state management as the number of pages grows.

```rust
struct AboutPageState {
    last_visited: Instant,
}

#[shard]
#[tessera]
fn about_page(#[state] state: AboutPageState) {
    // page content...
}
```

--------------------------------

### State Lifetime: 'app' (Rust)

Source: https://tessera-ui.github.io/guide/shard

Illustrates setting the lifetime of injected state to 'app' using the #[state(app)] attribute. This makes the state persist for the entire application lifetime, regardless of navigation stack changes.

```rust
#[shard]
#[tessera]
fn about_page(#[state(app)] state: AboutPageState) {
    // page content...
}
```

--------------------------------

### Calling a Shard with Injected State

Source: https://tessera-ui.github.io/guide/shard

Shows the simplified way to call a shard component after state injection has been configured. The `#[shard]` macro handles the state management, allowing the component to be called directly without passing the state parameter.

```rust
about_page();
```

--------------------------------

### Shard State Access within Component

Source: https://tessera-ui.github.io/guide/shard

Explains how the state injected into a shard component is accessed. The state parameter is automatically wrapped in `std::sync::Arc` to handle concurrency, requiring interior mutability wrappers like `Mutex` or `RwLock` for modifications.

```rust
// From outside the component:
#[tessera]
fn about_page();
// From inside the component:
#[tessera]
fn about_page(state: std::sync::Arc<AboutPageState>);

```

--------------------------------

### Tessera App with State and Button

Source: https://tessera-ui.github.io/guide/what-is-tessera

Illustrates a Tessera application that initializes the framework, registers pipelines, and runs an app component. The app component features a button that prints a message when clicked and uses `RippleState` for potential animation, showcasing one-way data flow.

```rust
fn main() {
    let config = TesseraConfig {
        window_title: "Tessera Example".to_string(),
        ..Default::default()
    };
    let ripple_state = Arc::new(RippleState::new());
    Renderer::run_with_config(
        || app(ripple_state.clone()),
        |app| {
            tessera_ui_basic_components::pipelines::register_pipelines(app);
        },
        config,
    )
    .unwrap();
}

#[tessera]
fn app(ripple_state: Arc<RippleState>) {
    surface(
        SurfaceArgsBuilder::default()
            .color(Color::WHITE)
            .width(DimensionValue::FILLED)
            .height(DimensionValue::FILLED)
            .build()
            .unwrap(),
        None,
        || {
            boxed(
                BoxedArgs {
                    width: DimensionValue::FILLED,
                    height: DimensionValue::FILLED,
                    alignment: Alignment::Center,
                },
                |scope| {
                    scope.child(|| button(
                            ButtonArgsBuilder::default()
                                .on_click(Arc::new(|| println!("HI!")))
                                .build()
                                .unwrap(),
                            ripple_state,
                            || text("Click me!"),
                        )
                    )
                }
            )
        },
    );
}
```

--------------------------------

### Simple Tessera App Component

Source: https://tessera-ui.github.io/guide/what-is-tessera

Demonstrates a basic Tessera application component using the `#[tessera]` macro. It defines a surface with a white background and fills the available space, containing centered text that reads 'Hello, Tessera!'.

```rust
#[tessera]
fn app() {
    surface(
        SurfaceArgsBuilder::default()
            .color(Color::WHITE)
            .width(DimensionValue::FILLED)
            .height(DimensionValue::FILLED)
            .build()
            .unwrap(),
        None,
        || {
            boxed!(
                BoxedArgs {
                    width: DimensionValue::FILLED,
                    height: DimensionValue::FILLED,
                    alignment: Alignment::Center,
                },
                |scope| {
                    scope.child(|| text("Hello, Tessera!"));
                }
            )
        },
    );
}
```

--------------------------------

### Rust: Fluid Glass Component Declaration

Source: https://tessera-ui.github.io/guide/what-is-tessera

This Rust code snippet shows a portion of the `fluid_glass` component declaration in Tessera. It demonstrates how to define arguments, handle optional state, and integrate custom render commands like blur and contrast effects using WGPU pipelines.

```rust
#[tessera]
pub fn fluid_glass(
    mut args: FluidGlassArgs,
    ripple_state: Option<Arc<RippleState>>,
    child: impl FnOnce(),
) {
    measure(Box::new(|input| {
        // ...

        if args.blur_radius > 0.0 {
            let blur_command = BlurCommand {
                radius: args.blur_radius,
                direction: (1.0, 0.0), // Horizontal
            };
            let blur_command2 = BlurCommand {
                radius: args.blur_radius,
                direction: (0.0, 1.0), // Vertical
            };
            let mut metadata = input.metadata_mut();
            metadata.push_compute_command(blur_command);
            metadata.push_compute_command(blur_command2);
        }

        if let Some(contrast_value) = args.contrast {
            let mean_command = 
                MeanCommand::new(input.gpu, &mut input.compute_resource_manager.write());
            let contrast_command = 
                ContrastCommand::new(contrast_value, mean_command.result_buffer_ref());
            let mut metadata = input.metadata_mut();
            metadata.push_compute_command(mean_command);
            metadata.push_compute_command(contrast_command);
        }

        let drawable = FluidGlassCommand {
            args: args_measure_clone.clone(),
        };

        input.metadata_mut().push_draw_command(drawable);

        // ...
    }));

    // ...
}
```
Tokens:
Raw