Render-time focus context callbacks for interactable nodes

[tensor-r]

Context

Building interactive TUI apps with Rezi means constantly reacting to focus state — highlighting the active row, changing a button's label, dimming an inactive panel. Today this requires boilerplate: tracking focus IDs in app state, comparing them manually during render, and wiring up blur/focus callbacks just to change a style or a string.

Focus and focus zones (ui.focusZone) are already part of the core framework. It makes sense for the framework to also pass that state back as optional render-time context, so building highly interactive apps is fun and easy rather than tedious.

This is a pattern I've used across multiple apps I've built with custom focus engines, and it's by far the most common thing I reach for. I believe it would be a very likely and commonly used feature for anyone building interactive Rezi apps.

Idea

Allow children and labels of interactable nodes to optionally be callbacks that receive focus context at render time.

Button label as callback

// Static (current)
ui.button("save", "Save")

// Dynamic (optional) — label changes based on focus state boolean, zero state management
ui.button("save", ({ focused }) => focused ? "▸ Save" : "  Save")

FocusZone children as callback

// Static (current)
ui.focusZone({ id: "list" }, [children])

// Dynamic (optional) — children receive if current zone is focused as boolean
ui.focusZone({ id: "list" }, ({ zoneFocused }) => [
  renderItems(zoneFocused)  // e.g. change row background when zone loses focus
])

Real-world usage

I've been using this pattern in my project via a patched @rezi-ui/core. Here's how it plays out in practice:

1. Header buttons show a focus indicator

Each column header shows a ▸ arrow only when focused — all columns update reactively with no imperative state:

ui.button(buttonId, ({ focused }) => (focused ? "▸ " : "  ") + col.header, { px: 0, style })

2. Virtual list rows respond to zone focus

Rows change background color depending on whether their parent zone is active — passed declaratively through zoneFocused:

actionZone({ id: "list" }, ({ zoneFocused }) => [
  ui.virtualList({
    renderItem: (item, idx) => Row(item, columns, ..., zoneFocused),
  }),
])

Inside the Row component:

const bg = rowFocused
  ? { bg: zoneFocused ? FOCUSED_BG : UNFOCUSED_BG }
  : {};

3. Context-aware status bar

Help text in the status bar changes based on which zone id is focused (as string), with no manual subscriptions:

{ label: "tab", render: ({ focusedZoneId }) => ui.text(
  focusedZoneId === "list" ? "edit columns" : "select list",
  { dim: true }
)}

4. Higher-level action zones

The pattern composes naturally into ui.focusTrap and ui.focusZone abstractions — with new ui.actionZone (or ui.keyZone) keybindings are automatically registered/unregistered based on zone focus.

export function actionZone(opts, children) {
  return ui.focusZone({ id: opts.id }, ({ zoneFocused }) => {
    if (zoneFocused) registerActionKeys(opts.actions); // this calls app.keys(...) in the core
    return children({ zoneFocused });
  });
}

How it could work

All changes below are quite straight forward and easy.

• Set activeZoneId and focusedId synchronously before each viewFn(snapshot) call in widgetRenderer
• button() checks if its label is a function — if so, calls it with { focused: boolean }
• focusZone() checks if its children is a function — if so, calls it with { zoneFocused: boolean }
• widgetRenderer.ts — routeEngineEvent computes needsCommit = didZoneChange || didFocusChange and returns it alongside needsRender in every return path
• createApp.ts — checks if (routed.needsCommit) markDirty(DIRTY_VIEW) right after the existing needsRender check
• Fully backward-compatible — strings and arrays continue to work as before

Performance

The proposed changes add zero overhead for the following reasons:

1. Focus changes do trigger at most a single commit/render pass (so the view function re-runs and callbacks resolve with updated state), but this is expected and acceptable — in practice it will almost always overlap with a commit pass that was already going to happen from the event that caused the focus change.
2. The callback is an optional synchronous lambda invoked inline during the existing render pass — no extra traversals, no subscriptions, no diffing. When a plain string or array is passed, the code path is a single typeof check. When a callback is passed, it's one immediate function call that resolves to the same string or array the framework already expects.

Thoughts / Other considerations

I am aware the current state of app quite unstable and rapidly changing, therefore I am not pushing for this to be implemented immediately. Rather I would only like to hear thoughts and keep this as a proposal for a future release.

Happy to contribute a PR if there's interest. I have been experimenting with these changes successfully in my app (by patching the core) and they work perfectly without any issues. This makes my app UI app in Rezi very intractable and more fun to build :)

[tensor-r]

@RtlZeroMemory Take your time to review. I'd like to hear your thoughts, if perhaps my real-world usage are already possible and maybe I've missed how. I'd also like to know if I am thinking in the right abstractions and similar direction as your vision.