State and environment API

Declared by <huxerui/state.h> and <huxerui/environment.h>.

State<T>

Copyable handle to one observed value. Implicit conversion to const T&, operator->, and Get() read the value and subscribe the current scope. Prefer ordinary conversion and member access in application expressions; use Get() when an explicit reference or overload disambiguation is useful.

Assignment publishes a replacement value. Supported compound operators are +=, -=, *=, /=, %=, &=, |=, ^=, <<=, and >>= when the stored type supports them. Prefix and postfix increment and decrement are also available. Update(function) mutates the stored value and publishes one update, while IsValid() reports whether the handle is connected.

StateList<T>

Observable vector-like state for dynamic collections. It exposes validity, size/empty queries, indexed reads, snapshots and iterators, plus mutation operations for insertion, erasure, clearing, push/pop, replacement, and element update. Mutations invalidate subscribed scopes while preserving the cell identity.

State creation

• UseState(initial, source_location) creates State<decay_t<T>> in the current scope.
• UseStateList<T>(), range, and initializer-list overloads create StateList<T>.
• Identity is scope, source location, and occurrence at that location.

Environment

Typed hierarchical value. Set(value) installs an EnvironmentValue by its C++ type and returns the environment for chaining. An environment value must be copyable and provide static Default(). Parent lookup is established by ProvideEnvironment.

UseEnvironment<T> and ProvideEnvironment

UseEnvironment<T>() reads the nearest required value during composition. ProvideEnvironment(environment, factory, args...) or ProvideEnvironment(value, factory, args...) creates a subtree boundary.

Viewport environment

• ViewportClass: Compact, Medium, Expanded.
• ViewportBreakpoints: medium and expanded width thresholds.
• ViewportEnvironment: runtime-provided logical viewport size and its resolved class.
• UseViewportClass() reads the runtime-installed current width class.

The runtime updates subscribed responsive scopes when window metrics cross a configured breakpoint.

Complete controlled-state example

#include <huxerui/huxerui.h>

using namespace huxerui;

[[huxerui::scope]]
View CounterSettings() {
  auto count = UseState(0);
  auto enabled = UseState(true);

  return Column {
    Text::Format("Count: {}", count),
    Button("Increment").OnClick([count] {
      count += 1;
    }).With(Enabled(enabled)),
    Checkbox("Enable counter", enabled).OnChanged([enabled](bool next) {
      enabled = next;
    }),
  }.With(Spacing(12.0F));
}

State is passed by value to the control and event handlers; the application writes the next controlled value after the event.