RIVE-based responsive layouts

[mchagneux]

This follows a discussion on Discord. The idea would be to support a particular approach to UI design & development that uses the Rive Layout system for positioning of components relative to each other. Roughly, the user could:

1. Design a wireframe for their app in Rive, using Rive layouts. They'd be able to visualize directly in the editor how the UI responds to resizes, and position everything as they want by eye. This notably allows special animations when resizing because I think state machine transitions can be hooked to resizes via special Rive listeners.
2. Export that wireframe Rive project as a .riv file.
3. Load that file as the base component for a YUP app / plugin, query its parts by name.
4. Attach YUP components to parts of this main Artboard. Their setBounds methods etc get called whenever Rive reflows.

[kunitoki]

The idea is to have the ability to attach a listener to an artboard to be notified of a rive Node being updated position and dimensions after a reflow of the layout (and the caller will update any component affected, offering better flexibility at the expense of more code to handle it), or to allow to attach child Component directly to the artboard as node replacements (which will be less code but less flexibility).

[kunitoki]

This is a draft spec for the idea i had in mind (we could support both):

RIVE-based Responsive Layouts Design Spec

---

Context

Rive's editor supports Rive Layouts: a Flex-based layout system that positions components relative to each other and reflows them as the artboard resizes. Designers can wireframe an entire UI in Rive, watch it respond to resizes in the editor, hook state machine transitions to resizes for layout animations, and export a .riv file.

Today yup::Artboard (in yup_gui) displays a .riv file as a Component and forwards input, but the file's nodes are opaque: there is no way to name-lookup a node, read its bounds, or react when a layout reflow moves or resizes it. This spec adds that bridge so a Rive wireframe can act as the base component of a YUP app/plugin, with real YUP components attached to its parts.

The vendored Rive runtime (v0.1.155) is built with WITH_RIVE_LAYOUT=1 WITH_RIVE_YOGA=1, so the layout engine is already active and rive::Artboard::find<T>(name) provides name-based lookup. The runtime's onLayoutChanged/onLayoutDirty callbacks are gated behind WITH_RIVE_TOOLS, which YUP does not enable, so reflow detection must be implemented on the YUP side.

---

Decisions Summary

Question	Decision
Integration models	Support both: per-node bounds listeners (flexible, more code) and attachable child components (ergonomic, less code)
Reflow detection	Diff each registered node's world transform against its cached value after every update pass (advanceAndApply, resized); no new build defines required
Bounds space	Rectangle<float> in component coordinates, mapped through the existing viewTransform
Model B implementation	Sugar on top of Model A — an internal bounds listener calls setBounds(); no duplicated reflow logic
Required fit mode	Responsive reflow requires Layout::layout (or Layout::fill); document this
WITH_RIVE_TOOLS callbacks	Noted as a future optimization; out of scope for v1
Tests	Extend tests/yup_gui/yup_Artboard.cpp

---

Architecture

Modified files

modules/yup_gui/artboard/yup_Artboard.h   — public API + private members
modules/yup_gui/artboard/yup_Artboard.cpp — implementation
tests/yup_gui/yup_Artboard.cpp            — new tests

No new files; yup_gui.h/yup_gui.cpp includes are unchanged. This extends the existing yup::Artboard : Component class.

Model A — node bounds listeners

The caller registers a callback per named node. After every update pass the Artboard recomputes each registered node's bounds in component space; if a bound changed (beyond an epsilon), the callback fires with the new Rectangle<float>. The caller is free to move any component it wants — maximum flexibility.

Model B — node replacement

The caller attaches a Component* to a named node. Artboard internally registers a Model A listener for that node and calls setBounds() on the attached component whenever the reflow changes the node's bounds. Component lifetime stays with the caller; Artboard never creates or destroys components.

Reflow detection (shared)

Layout recalculation happens inside rive::Artboard::update() (syncStyleChanges → calculateLayout → updateLayoutBounds(animation=true)), which runs whenever markLayoutDirty() populated the dirty set. Because updateLayoutBounds(animation=true) animates over multiple frames, diffing every update pass naturally emits intermediate bounds during layout animations — this is what enables resize animations in YUP.

Detection points in yup_Artboard.cpp:

• end of advanceAndApply() (after scene->advanceAndApply(...))
• resized() (after updateViewTransform())
• contentScaleChanged(), setFile(), updateSceneFromFile() (initial state)

Bounds computation

// artboard-space rect for a node
auto* node = artboard->find<rive::Component> (name.toStdString());

// layout nodes report real size; others fall back to a unit rect
float w = node->is<rive::LayoutComponent>() ? node->as<rive::LayoutComponent>()->layoutWidth()  : 1.0f;
float h = node->is<rive::LayoutComponent>() ? node->as<rive::LayoutComponent>()->layoutHeight() : 1.0f;

// world transform in artboard coords, then map through viewTransform into component coords

Node world transform is read from rive::TransformComponent::worldTransform() (a Mat2D); the result is mapped through the same artboard↔component transform used by painting and transformPoint(), yielding a Rectangle<float> in component space. Unknown names return Rectangle<float>().

---

API

class YUP_API Artboard : public Component
{
public:
    //==============================================================================
    /** Callback invoked when a named node's bounds change after a layout reflow.

        @param artboard The artboard that emitted the change.
        @param nodeName The name of the node whose bounds changed.
        @param bounds  The new node bounds in component coordinates.
    */
    using NodeBoundsCallback = std::function<void (Artboard& artboard, const String& nodeName, const Rectangle<float>& bounds)>;

    //==============================================================================
    /** Registers a listener for a named artboard node.

        The callback is invoked whenever a layout reflow changes the node's bounds
        (component coordinates). Pass an empty callback to remove the listener.

        @param nodeName The name of the node in the .riv file.
        @param callback The callback to invoke on bounds changes.
    */
    void setNodeBoundsListener (StringRef nodeName, NodeBoundsCallback callback);

    /** Removes the listener registered for the given node. */
    void clearNodeBoundsListener (StringRef nodeName);

    /** Removes all node bounds listeners. */
    void clearAllNodeBoundsListeners();

    /** Returns the current bounds of a named node in component coordinates.

        @param nodeName The name of the node in the .riv file.
        @return The node bounds, or an empty rectangle if the node is unknown.
    */
    Rectangle<float> getNodeBounds (StringRef nodeName) const;

    //==============================================================================
    /** Attaches a component to a named artboard node.

        The component's bounds are driven by the node's layout: whenever a reflow
        changes the node's bounds, the artboard calls setBounds() on the component.
        Ownership of the component remains with the caller.

        @param nodeName   The name of the node in the .riv file.
        @param component  The component to attach; must outlive the attachment.
        @return True if the node exists and the component was attached.
    */
    bool attachComponentToNode (StringRef nodeName, Component* component);

    /** Detaches a component from a named node, stopping bounds updates. */
    bool detachComponentFromNode (StringRef nodeName, Component* component);

    /** Detaches every attached component. */
    void detachAllComponents();

private:
    void notifyNodeBoundsChanged();
    Rectangle<float> computeNodeBounds (rive::Component* node) const;

    HashMap<String, NodeBoundsCallback>    nodeBoundsListeners;
    HashMap<String, Component*>            attachedComponents;
    HashMap<String, Rectangle<float>>      lastNodeBounds;
};

Note: responsive behavior requires the artboard fit mode that lets Rive own the size — use setLayout (Artboard::Layout::layout) (or fill). With fit modes like contain, reflow still runs but bounds are computed in the letterboxed artboard space.

---

Example

// Wireframe designed in Rive with Rive Layouts, exported as ui.riv
auto file = ArtboardFile::load (File ("ui.riv"), *getFactory());
auto artboard = std::make_unique<Artboard> ("root", file);
artboard->setLayout (Artboard::Layout::layout);

// Model B: drop a real YUP component onto the "knob-panel" node
artboard->attachComponentToNode ("knob-panel", knobPanel.get());

// Model A: fine-grained control over a header that repositions on resize
artboard->setNodeBoundsListener ("header", [] (Artboard&, const String&, const Rectangle<float>& bounds)
{
    // e.g. move the header, or fire an animation tied to the reflow
});

addAndMakeVisible (*artboard);

[mchagneux]

Great!