oxiui-dioxus — Dioxus adapter for OxiUI

oxiui-dioxus is the Dioxus backend adapter for OxiUI. Dioxus is a reactive, component-based framework: components are functions that return Element via the rsx! macro. This adapter bridges that retained, reactive model onto OxiUI's immediate-mode UiCtx closure API via two pieces: DioxusCtx, a UiCtx implementation that collects each widget call into an ordered list, and run_dioxus, a driver that executes a content closure against that context with a supplied theme.

Dioxus is dual-licensed MIT OR Apache-2.0, so this adapter carries no copyleft obligations. The adapter is configured to use Dioxus's minimal feature set (macro, html, signals, hooks, launch) — all Pure Rust. The desktop feature (wry/tao/WebKit/Chromium) is intentionally excluded because it pulls in C/C++ system dependencies that violate the COOLJAPAN Pure-Rust policy. The crate is fully usable with default = [] (collection mode) and pulls in the dioxus crate only when you enable --features dioxus.

Milestone status: As of M5, run_dioxus executes the content closure in headless collection mode (no display, no Dioxus runtime) and returns Ok(()). Full native rendering — translating collected items into an rsx! element tree and launching via dioxus-native (the Pure-Rust Blitz/Vello renderer) — is deferred to M6.

Installation

[dependencies]
# Collection mode only — no Dioxus dependency
oxiui-dioxus = "0.1.2"

# Enable Dioxus rendering (minimal Pure-Rust feature set; no wry/tao/WebKit)
oxiui-dioxus = { version = "0.1.2", features = ["dioxus"] }

Quick Start

Collection mode (no dioxus feature, fully testable)

use oxiui_dioxus::DioxusCtx;
use oxiui_core::UiCtx;

let mut ctx = DioxusCtx::default();
ctx.heading("App Title");
ctx.label("Hello, Dioxus!");
let _resp = ctx.button("Click me");

assert_eq!(ctx.items.len(), 3);
assert_eq!(ctx.items[0], "heading:App Title");

Driving a content closure with a theme

use oxiui_dioxus::run_dioxus;
use oxiui_theme::cooljapan_dark;

run_dioxus(&*cooljapan_dark(), |ui| {
    ui.heading("Hello from Dioxus");
    ui.label("OxiUI + dioxus backend");
})
.expect("run_dioxus should be Ok");

API Overview

Types

Functions

DioxusCtx as a UiCtx

DioxusCtx implements the three required UiCtx methods. All other UiCtx widget methods (slider, checkbox, dropdown, text_input, …) fall back to their default trait implementations, which report supported == false so callers can detect non-support and degrade gracefully.

The items entries use the format "<kind>:<text>" (e.g. "label:Hello", "button:Quit"), letting headless tests assert on the exact widget sequence without a display server.

Feature Flags

Errors

run_dioxus returns Result<(), oxiui_core::UiError>. In M5 it is always Ok(()). From M6 onward it will return UiError::Backend if the Dioxus launch reports an error. UiError is #[non_exhaustive]; see oxiui-core for the full variant list.

Palette mapping note

Dioxus renders via CSS-in-Rust (inline style="" attributes). The palette argument to run_dioxus is available for downstream consumers who format style strings from the palette colours; it is not automatically injected in M5. A helper palette_to_css_vars() is planned for M6 to emit :root { --background: #rrggbb; … } global CSS.

Architecture note

Because Dioxus is reactive (not immediate-mode), the adapter operates in two phases:

1. Collection pass — the content closure is executed against a DioxusCtx, accumulating widget descriptions in items.
2. Render pass (M6) — those items are translated into a Dioxus rsx!/Element tree and handed to dioxus::launch() running on the Pure-Rust dioxus-native renderer.

In M5 only the collection pass is active, which is what makes the crate headless-testable and example-buildable without a display or any C/C++ dependencies.

Related Crates

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)