oxiui-core — Core traits and types for OxiUI

oxiui-core defines the public API surface that every OxiUI backend, adapter, and widget crate builds upon. It is the foundation of the COOLJAPAN Pure-Rust GUI toolkit: the immediate-mode trait surface (UiCtx, Widget, Theme), the geometry and event primitives, a retained widget tree, a flexbox/grid layout engine, a Cassowary constraint solver, a draw-command/paint layer, a reactive signal runtime, animation primitives, and the colour-space utilities consumed across the stack.

The crate is #![forbid(unsafe_code)] and has zero mandatory external dependencies (only an optional serde integration). Concrete adapters — oxiui-egui, oxiui-iced, oxiui-slint, oxiui-dioxus, oxiui-render-soft, oxiui-render-wgpu — implement the traits declared here; the oxiui facade wires them together. Themes live in oxiui-theme, rich text in oxiui-text, tables in oxiui-table, and the accessibility tree in oxiui-accessibility. 100% Pure Rust.

Installation

[dependencies]
oxiui-core = "0.1.0"

# Enable serde on UiEvent and its nested event types:
oxiui-core = { version = "0.1.0", features = ["serde"] }

Quick Start

Implement [UiCtx] in an adapter, override the three required widget methods, and let every extended widget degrade visibly via the supported flag:

use oxiui_core::{UiCtx, ButtonResponse, TextStyle};
use oxiui_core::response::WidgetResponse;

struct ConsoleUi;

impl UiCtx for ConsoleUi {
    fn heading(&mut self, text: &str) {
        println!("# {text}");
    }
    fn label(&mut self, text: &str) {
        println!("{text}");
    }
    fn button(&mut self, label: &str) -> ButtonResponse {
        println!("[ {label} ]");
        ButtonResponse::default()
    }
}

let mut ui = ConsoleUi;
ui.heading("Welcome");
ui.label("Pure-Rust UI core");
let r = ui.button("OK");
assert!(!r.clicked);

// Extended widgets that the adapter has *not* overridden report
// `supported == false` instead of silently rendering nothing.
let slider = ui.slider(0.5, 0.0..=1.0);
assert!(!slider.supported);

Geometry, layout and paint

use oxiui_core::{Constraints, Point, Rect, Size};
use oxiui_core::{FlexLayout, FlexItem, JustifyContent};
use oxiui_core::{Color, DrawList};

// Box constraints clamp a size into a [min, max] range.
let c = Constraints::new(Size::new(10.0, 10.0), Size::new(100.0, 100.0));
assert_eq!(c.constrain(Size::new(5.0, 200.0)), Size::new(10.0, 100.0));

// Hit testing on rectangles is inclusive of top/left, exclusive of bottom/right.
let r = Rect::new(10.0, 20.0, 100.0, 50.0);
assert!(r.contains(Point::new(10.0, 20.0)));

// Build a backend-agnostic draw list.
let mut dl = DrawList::new();
dl.push_rect(Rect::new(0.0, 0.0, 64.0, 64.0), Color(122, 162, 247, 255));
assert_eq!(dl.len(), 1);

API Overview

Core widget traits

UiCtx extended widget methods

All return a *Response whose supported field is false by default; container methods do not invoke their content closure when unsupported, so callers can detect non-support before side effects run.

Core types (crate root)

response module

Response structs returned by the extended UiCtx widgets. Each carries a supported flag, a zeroed/identity payload, and unsupported() / supported(…) constructors.

geometry module

All coordinates are f32 logical pixels with the origin top-left.

style module

text_style module

TextStyle — builder-pattern typography intent (size, weight, italic, colour, line-height, letter-spacing, underline, strikethrough). Presets: bold(), italic(), heading(), body(), caption(); builders with_size, with_weight, with_color, with_line_height, with_letter_spacing, with_underline, with_strikethrough.

events module

paint module

The canonical paint layer: build a DrawList, hand it to a RenderBackend.

tree module — retained widget tree

layout module — flexbox engine

FlexLayout (single- and multi-line/wrapping) with FlexItem (basis + grow). Enums: FlexDirection (Row/Column), JustifyContent, AlignItems, FlexWrap (NoWrap/Wrap/WrapReverse), AlignContent. Constructors row()/column() plus with_justify/with_align builders.

grid module — CSS grid

compute_grid(template, items, available) -> Vec<Rect>. Types: GridTemplate, GridItem, GridPlacement (auto/at/span), GridLine, GridSpan, TrackSizing.

solver module — Cassowary constraint solver

A linear-arithmetic constraint solver for advanced layout. Solver (add_constraint, remove_constraint, add_edit_variable, suggest_value, update_variables, value_of, reset), plus Variable, Term, Expression, Constraint, RelOp, Strength, and SolverError.

reactive module — signal runtime

ReactiveRuntime creates Signal<T> (get/set) and Computed<T> (derived, get() -> Result<T, ReactiveError>) values for fine-grained reactivity. ReactiveError reports cycles / poisoned state.

anim module — animation primitives

scheduler module — timers

Scheduler (after, every, request_frame, cancel, tick(dt)) with TimerId, plus Debounce and Throttle rate-limiters.

dispatch module — event capture/bubble

EventDispatcher runs a capture/bubble pipeline over a WidgetTree. Types: DispatchEvent, Phase, EventHandler (trait), HandlerCtx.

focus module

FocusManager — focus traversal over a WidgetTree: focus, blur, focus_next, focus_prev, push_trap/pop_trap (focus traps), autofocus, reconcile.

cache module

LayoutCache — memoises computed rectangles keyed by (WidgetId, available size, content hash); get, put, invalidate, hit_rate, is_dirty.

diff module — tree reconciliation

diff(old, new) -> Vec<DiffOp> computes a minimal Insert/Remove/Update/Move op set (LCS-based) to reconcile two WidgetTrees.

color_space module

widget_ext module — combinators

WidgetExt blanket-implemented for every Widget, adding chainable wrappers: padding, margin, background, border, on_click, on_hover (yielding Padded, Margined, Backgrounded, Bordered, OnClick, OnHover). Also: ClipboardProvider trait, DragSource/DropTarget traits, DragData, DropEffect.

Feature Flags

Error variants — UiError

#[non_exhaustive]; downstream match must include a catch-all.

Related crates

oxiui-core is the foundation of the OxiUI workspace:

• oxiui — the top-level facade that wires adapters together
• oxiui-theme — COOLJAPAN themes (Tokyo Night) built on Palette/FontSpec/Theme
• oxiui-text — rich text layer over oxitext, consuming TextStyle and RichTextSpan
• oxiui-table — virtualized table widget
• oxiui-accessibility — AccessKit a11y tree built from the widget graph
• oxiui-render-soft, oxiui-render-wgpu — RenderBackend implementations
• oxiui-egui, oxiui-iced, oxiui-slint, oxiui-dioxus, oxiui-web — UiCtx adapters

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)