serez-ui

React-style UI library for Serez Code. Components, a transparent Virtual DOM, and hooks — the same code runs in the terminal (TUI) or in a real native window (GUI).

Install

sz install serez-ui

The model

You write screens as classes that extend Window (the root interface) and reusable pieces that extend Component — both return JSX from render(). State lives inthis fields; mutating it inside an event handler triggers a re-render through the Virtual DOM. JSX is written in .szx files and translated to plain .sz before running.

Quick start

A counter, rendered in a real native window:

import "serez-ui"

class Counter:Window {
    public Counter() {
        super()
        this.count = 0
    }

    public render() {
        return (
            <div>
                <h1>Counter</h1>
                <hr />
                <h2>{this.count}</h2>
                <Button onClick={() => { this.count = this.count + 1 }}>Increment</Button>
                <Button onClick={() => { this.count = 0 }}>Reset</Button>
            </div>
        )
    }
}

let app = new Counter()
app.runGui("Counter", 520, 420)   // native window — quit with Esc or the close button

Building .szx files

JSX lives in .szx files. Run them directly — the runtime translates the JSX to .sz and runs it (and opens the UI) in one step:

sz apps/counter.szx

The primitive form: h()

JSX is sugar. The translator turns every tag into a call to one primitive function, h(tag, props, children) — "hyperscript". So <div class="box">hi</div> becomes h("div", [["class", "box"]], ["hi"]): a tag string, a list of [name, value] prop pairs, and a list of children.

You can write that form by hand — it is valid. The counter above builds the same tree with no JSX at all:

public any render() {
    return h("div", [], [
        h("h1", [], ["Count: " + this.count]),
        h("Button", [["onClick", () => { this.count = this.count + 1 }]], ["+1"])
    ])
}

Built-in components

Structure uses primitive HTML-like tags the renderer draws directly (div, h1, h2, h3, p, span, hr, ul, li, section, form). Block text (h1/h2/h3/p/span/li/Label) word-wraps to the available width and reflows on resize. For layout, Row places its children side by side (each at its content width, with a gap) — and stacks them vertically when they no longer fit (set wrap={false} to force a single row) — while Col stacks them vertically. For interaction, serez-ui ships 24 built-in components:

<Input value={this.name} placeholder="your name" onChange={(v) => { this.name = v }} />
<Textarea value={this.bio} rows={4} onChange={(v) => { this.bio = v }} />
<Select value={this.mode} options={["fast", "normal", "slow"]} onChange={(v) => { this.mode = v }} />
<Dropdown value={this.lang} options={["es", "en", "fr"]} onChange={(v) => { this.lang = v }} />
<Checkbox checked={this.agreed} label="I agree" onChange={(b) => { this.agreed = b }} />
<RadioGroup value={this.size} options={["S", "M", "L"]} onChange={(v) => { this.size = v }} />
<Slider value={this.vol} min={0} max={100} step={5} onChange={(v) => { this.vol = v }} />
<ProgressBar value={this.vol} max={100} label="level" />
<Switch checked={this.dark} label="Dark mode" onChange={(b) => { this.dark = b }} />
<Chart data={[3, 7, 4, 9, 6, 11, 8]} type="area" height={140} dots={true} />
<Row>
    <Button onClick={save} disabled={!this.canSave}>Save</Button>
    <Button onClick={clear}>Clear</Button>
</Row>

// Tabs draw the strip; you render the panel for the active index:
<Tabs tabs={["Info", "Config", "Logs"]} active={this.tab} onChange={(i) => { this.tab = i }} />
{ this.tab == 0 ? <Info /> : this.tab == 1 ? <Config /> : <Logs /> }

// Collapsible: a header that shows/hides its children (stack a few for an accordion):
<Collapsible title="Details" open={this.open} onToggle={(o) => { this.open = o }}>
    <p>Hidden until expanded.</p>
</Collapsible>

// Files (both need the File permission to read the paths):
<FileInput exts="json" filterName="JSON" onChange={(p) => { this.path = p }} />
<DropZone label="Drop files here" onDrop={(paths) => { this.files = paths }} />

Focus & keyboard (GUI)

Every interactive component is focusable and gets a focus index in render order. The focused element shows a ring (text fields highlight their border and draw the caret). This navigation is built in — you do not wire it up:

Text is drawn with real glyphs on a monospace grid, and typing goes through your OS keyboard layout and IME — so accents, ñ and Unicode type straight into an Input or Textarea. A CJK IME composition in progress is drawn underlined at the caret, and when the window loses OS focus the caret stops blinking (a background window costs ~0 CPU).

OS events (drag-drop, gestures)

The GUI surfaces a few window-level OS events as optional Window overrides (all default to no-op; return true to request a redraw). The DropZone and FileInput components cover the common cases, but you can also handle them directly:

public bool onFilesDropped(any paths) {   // files dropped on the window (needs File perm to read)
    this.attached = paths
    return true
}
public bool onFilesHovered(any paths) { ... }   // files dragged over the window (before dropping)
public bool onPinch(any delta)        { ... }   // trackpad pinch/zoom (delta > 0 in, < 0 out)
public bool onTouch(any touches)      { ... }   // touchscreen points: flat [id, phase, x, y, ...]

app.hoveredFiles() returns the paths currently being dragged over the window (or []), so a component can read it from render() to highlight a drop target — which is what DropZone does.

Reusable components

Beyond Window (the root interface), extend Component to build your own reusable pieces. A component receives props (data passed to it) and children (content between its tags) — read them with plain dot access:

class TaskRow:Component {
    public TaskRow() { super() }

    public render() {
        let mark = "[ ] "
        if (this.props.done) { mark = "[x] " }
        return (
            <li>{mark + this.props.text}</li>
        )
    }
}

// use it like any tag — props are attributes, children is the content:
<TaskRow text="buy milk" done={true} />

Lists with .map()

Render a list by mapping an array to nodes — no manual loops, no h(...) calls. The callback can return any tag: an HTML element, a fragment <>...</>, or another component:

public render() {
    let tasks = this.props.tasks
    return (
        <ul>
        {
            tasks.map(fn (t) {
                return (
                    <TaskRow text={t} done={false} />
                )
            })
        }
        </ul>
    )
}

Fragments group children without adding a wrapper element — handy when the callback returns bare values:

items.map(fn (x) {
    return (
        <>{x}</>
    )
})

TUI vs GUI

The same component runs in two renderers, but they are not interchangeable for input — each has its own event loop, serez.json permission, and interaction model:

// The same component runs itself in either target — the event loop is a
// method on your component (app is your top-level variable):

// Terminal (TUI) — needs "Terminal" permission; onKey drives navigation
app.runTui()                       // quit with q

// Native window (GUI) — needs "Gui" permission; interact via Buttons/Inputs
app.runGui("My App", 560, 460)     // quit with Esc or the close button

For a full worked example of each, see the Build a UI (TUI / GUI) tutorial.

Resizing & width bounds

The GUI reflows on window resize (autosize): full-width controls (Input, Select, Textarea, Dropdown, Slider, ProgressBar, hr) stretch and shrink to the window, while buttons and labels keep their content size. A Row whose children no longer fit stacks them vertically on its own (no config), and content taller than the window scrolls with the mouse wheel (a scrollbar appears on the right). Bound the content width — and the layout centers itself when the max-width is narrower than the window:

app.setMaxWidth(720)   // content never wider than 720px (centered on big screens)
app.setMinWidth(360)   // ...and never narrower than 360px
app.runGui("My App", 900, 600)

Pass 0 (the default) for no limit. For width-driven styling and layout — including stacking a Row when narrow — see CSS media queries below.

Breakpoints in render()

For structure that changes with size — not just styling — read this.viewportWidth() (live px) or this.breakpoint() ("sm" / "md" / "lg") inside render(). The GUI re-runs render() on resize, so you can return a different tree per breakpoint:

public any render() {
    if (this.breakpoint() == "sm") {
        return <Button>Menu</Button>          // phone: a single button
    }
    return (                                   // desktop: a row of links
        <Row>
            <Button>Home</Button>
            <Button>Profile</Button>
            <Button>Settings</Button>
        </Row>
    )
}

Thresholds default to 600 / 960; change them with app.setBreakpoints(smMax, mdMax) before runGui.

CSS with logic (.szs)

Style with a CSS dialect that supports reactive conditions. A selector can carry a condition evaluated against the state exposed by styleVars(). This is a quick tour — see the full .szs reference for every property, condition and the responsive variables:

/* counter.szs */
:import {
    count: count;
}

body (count == 0) { background-color: #0f172a; }
body (count != 0) { background-color: #14532d; }

h1     { color: #ffd166; }
Button { background-color: #2563eb; color: #ffffff; }

Attach the stylesheet to your component before starting:

app.useStylesheet(parseCss(File.read("apps/counter.szs")))
app.runGui("Counter", 520, 420)

Responsive — media queries

The current width and height (px) are always available as condition variables (no :import needed), so a stylesheet can adapt the UI to the window size — and it reflows live on resize:

body (width < 600)  { background-color: #1e1b4b; }   /* phone-ish */
body (width >= 600) { background-color: #0f172a; }

Row (width < 600)   { direction: column; }            /* stack the row when narrow */

h1  (width < 600)   { font-scale: 2; }                /* smaller heading when small */
h1  (width >= 960)  { font-scale: 4; }

Beyond colors, the sheet understands direction: column (lay a Row out vertically), font-scale: N (integer text-size multiplier for h1/h2/h3/p/span/li) and white-space: nowrap(keep a tag's text on one line — it may clip — instead of word-wrapping).

Secondary Windows (Panels)

Since serez-ui 2.3.0, the GUI renderer runs on top of a retained-mode scene graph, drastically reducing CPU usage. It also adds native support for opening and managing secondary OS windows (referred to as panels).

To use panels, open them using this.openPanel(title, w, h) from within your main application window, and override the renderPanel(id) method in your class to define the UI tree of each panel:

import "serez-ui"

class MyApp:Window {
    public MyApp() {
        super()
        this.message = "Hello from panel"
        this.secondaryWindowId = -1
    }

    public render() {
        return (
            <div>
                <h1>Main Window</h1>
                <Button onClick={() => {
                    if (this.secondaryWindowId == -1) {
                        this.secondaryWindowId = this.openPanel("Controls", 300, 200)
                    }
                }}>Open Secondary Panel</Button>
            </div>
        )
    }

    // Override renderPanel to draw the secondary window's tree
    public renderPanel(int id) {
        if (id == this.secondaryWindowId) {
            return (
                <div>
                    <h2>Panel Controls</h2>
                    <p>{this.message}</p>
                    <Button onClick={() => {
                        this.message = "Button clicked in Panel!"
                    }}>Update Main State</Button>
                    <Button onClick={() => {
                        this.closePanel(this.secondaryWindowId)
                        this.secondaryWindowId = -1
                    }}>Close Panel</Button>
                </div>
            )
        }
        return null
    }
}

let app = new MyApp()
app.runGui("Main App", 600, 400)

Preserved State Identity:click handlers inside a panel's VDOM can directly access and modify the properties of the parent Window class. A click in a secondary panel that updates state automatically re-renders the main window.

Native renderer (experimental)

serez-ui 4.3.0 can hand style resolution, layout and painting to the core's primitives engine (Gui.renderTree, requires core ≥ 9.2): every component is lowered to HTML-like primitives and the whole layout + CSS walk runs in Rust instead of interpreted code — measured ~1000× faster on that phase for app-sized trees. All 24 built-in components work under this path (clicks, focus order, overlays and text editing included), and your app code does not change:

let app = new MyApp()
app.useNativeRenderer(true)   // opt-in — call before runGui()
app.runGui("My App", 800, 600)

API surface

Packaging

Ship a serez-ui app as a self-contained installer (the runtime travels inside, no Serez Code needed on the target) with serez-pack.