Integrate Clay layout engine for flexbox-like responsive layouts

[jserv]

Summary

This issue proposes evaluating the integration of Clay as an optional layout backend for libIUI, with the goal of enabling flexbox-like responsive layouts, robust text wrapping, scrollable containers, and aspect-ratio constrained elements.

The intent is not to replace libiui’s immediate-mode UI or MD3 component model, but to strengthen its layout capabilities for complex, resizable, and content-heavy interfaces.

Motivation

libiui targets Material Design 3 (MD3) and emphasizes:

• immediate-mode UI
• renderer agnosticism
• zero-heap / user-supplied buffers
• predictable runtime behavior

As UI complexity grows (responsive windows, dense text, media cards, multi-pane layouts), ad-hoc layout logic becomes increasingly fragile. A dedicated layout engine could reduce complexity while preserving libiui’s design principles.

Clay is a small, dependency-free C library that provides:

• flexbox-inspired layout model
• intrinsic text wrapping
• scrollable containers with explicit state updates
• aspect-ratio constraints
• arena-based memory model
• permissive (zlib) license

This makes it a strong candidate for evaluation.

Proposed Scope

This evaluation focuses on layout only, not UI composition or styling.

Possible integration model:

1. libiui widgets emit layout constraints into Clay
2. Clay computes final rectangles per frame
3. libiui renders widgets using its existing renderer paths
4. Clay render commands are optional and may be ignored initially

Expected Benefits

• Cleaner implementation of responsive layouts
• First-class text wrapping behavior
• Standardized scrolling container behavior
• Easier implementation of MD3 patterns such as cards, lists, media containers, and adaptive panes
• Improved scalability from embedded to desktop-sized UIs

References

• Clay