sinomo-ui-widgets 0.1.0

Built-in widget library for SUI.
Documentation

SUI

SUI is a retained-mode UI toolkit for Rust. It combines a renderer-neutral scene model, a wgpu renderer, accessible built-in widgets, deterministic UI testing, and native Python and Node/Electron bindings in one workspace.

Release status: SUI is pre-release software. The Rust desktop API and testing stack are usable today, while browser, mobile, Python, JavaScript, and native HDR support have the limitations listed below. The crates and language packages have not been published yet, so API and package names may still change before the first stable release.

Quick start

SUI requires Rust 1.90 or newer and the system libraries normally needed by winit and wgpu on your platform.

Until the first crates.io release, add the repository dependency:

[dependencies]
sui = { package = "sinomo-ui", git = "https://github.com/sinomo-lab/sui" }

The package is named sinomo-ui because the sui registry namespace is occupied. Aliasing it as sui keeps application imports concise.

use sui::prelude::*;

fn main() -> Result<()> {
    App::new()
        .main_window("Hello SUI", Label::new("Ready"))
        .run()
}

From a workspace checkout, run the same program with:

cargo run -p sinomo-ui --example hello

Continue with the detailed first-application tutorial, then build an editable stateful form.

What is included

  • Retained widgets with explicit measure, arrange, event, paint, and semantics passes.
  • Common controls, form inputs, layout containers, composite application widgets, and the built-in Mesh light, dark, high-contrast, void/OLED, and touch themes.
  • Editable text, text areas, password fields, and local date/time fields with caret movement, selection, clipboard operations, and IME input.
  • A renderer-neutral scene representation and retained wgpu compositor.
  • AccessKit-backed accessibility plus an accessibility-tree generated TUI.
  • Headless automation, semantic locators, screenshots, and visual artifact generation.
  • Native Python and Node/Electron bindings for the shared high-level model.

The widget and layout reference lists the public building blocks and points to focused API guides.

Platform status

Surface Status Notes
Rust desktop Available winit + wgpu on Linux, macOS, and Windows
Headless/testing Available Deterministic runtime, semantics, rendering, and screenshots
Accessibility TUI Available Generated from the same semantic tree as assistive technologies
Rust browser Alpha WebAssembly demo through the web feature and Trunk
Rust Android Experimental Native-activity entry point through the mobile feature
Python Alpha Local PyO3/maturin build; packages are not published
Node/Electron Alpha Local napi-rs build; packages are not published
Browser JavaScript Planned No JavaScript/WASM package yet

Native HDR output is currently strongest on Windows. The renderer, color management, diagnostics, and SDR fallback paths are cross-platform; macOS EDR and broader Linux native-HDR integration remain roadmap work.

Learn by example

Example Run it Demonstrates
Hello cargo run -p sinomo-ui --example hello Minimal application and window
Quickstart cargo run -p sinomo-ui --example quickstart Layout, theming, and callbacks
Stateful form cargo run -p sinomo-ui --example stateful_form External state and editable inputs
Widget book cargo run -p sinomo-ui-demo Built-in widgets, themes, renderer settings, and demos
TUI cargo run -p sinomo-ui-demo -- --tui Keyboard-driven semantic-tree interface

See the complete examples catalog for Rust, testing, Python, and JavaScript examples.

Feature flags

The sinomo-ui package enables desktop and wgpu by default.

Feature Purpose
desktop Desktop event loop and window integration; also enables wgpu
web Browser platform integration; also enables wgpu
mobile Mobile platform integration; also enables wgpu
wgpu Public wgpu renderer facade
testing Reserved facade feature for test-oriented consumers

Custom embedders can disable default features and opt into the layers they need. Programs that call App::run() need a platform feature.

Documentation

The documentation index separates learning material, API reference, internals, and active roadmap work.

  • Tutorials — build a first app and a stateful form step by step.
  • API guide — application lifecycle, widgets, layout, inputs, resources, custom widgets, testing, and accessibility.
  • Examples — runnable Rust, Python, and JavaScript samples.
  • Testing — semantic automation, screenshots, and artifacts.
  • TUI — run and embed the accessibility-generated terminal UI.
  • Architecture — understand the retained runtime and frame pipeline.
  • Contributing — build, validate, document, and submit changes.
  • Security policy — report vulnerabilities privately and check the supported-version policy.

Generate local Rust API documentation with:

cargo doc -p sinomo-ui --no-deps --open

Repository development

Launch the desktop widget book:

cargo run -p sinomo-ui-demo

Run the standard validation suite:

cargo fmt --all -- --check
cargo test --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings

Generate the visual validation bundle explicitly:

cargo run -p sinomo-ui-demo --bin sui-demo-artifacts

Artifacts are written under target/ui-artifacts/sui-demo/widget-book. Ordinary tests do not generate this slower bundle.

For crate ownership and dependency boundaries, see the crate architecture. Contributors should read CONTRIBUTING.md before opening a change.

License

SUI is licensed under the MIT License. The bundled sinomo-ui-lucide crate retains its upstream ISC license.