Yororen UI

The Notification Center provides a unified system for managing toast-like notifications with the following capabilities:

• Queue management: Limits the number of active notifications (default max_queue_len = 5).
• Persistence: Supports sticky notifications that survive state restores.
• Callbacks: Supports both click and dismiss callbacks.
• Dismiss strategies: Supports both manual and auto-dismiss behaviors.

Every headless factory provides different ways to render components depending on how much visual control you need:

1. .render(cx) (Default/Fastest): Uses the registered renderer to paint background, borders, padding, radius, and hover/active states from the theme. Use this for standard UI.
2. .apply(div) (Caller-controlled visuals): Returns a Stateful<Div> that sets up id, track_focus, and on_click, but provides no visual feedback. Use this when you want to provide your own div() and only want the component to contribute accessibility and click logic.
3. Hand-rolled (Bespoke): Implement a custom gpui::Element for unique brand identities or animations, then use .apply(...) to retain focus and click wiring.

Yororen UI uses gpui's Entity<T> for all application state. This allows the render layer to track which entities were read, enabling efficient invalidation via cx.notify().

Key Rules:

1. Cloning: Every move closure that touches state needs its own Entity<T> clone (e.g., let inc = state.counter.clone();).
2. Mutation: Mutate the data inside an update block, then call cx.notify() to trigger a re-render, as gpui-ce 0.3 does not auto-notify on entity updates.

// Inside a render implementation
let state = cx.global::<AppState>();
let count = state.counter.read(cx).value;
let inc = state.counter.clone(); // Clone for the closure

// In a click handler
inc.update(cx, |c, cx| {
    c.value += 1;
    cx.notify(); // Required to trigger re-render
});

To prevent modals and toasts from being clipped by scrollable containers and to ensure they receive keyboard events (like Escape) reliably, do not render them inside a scrollable section.

Instead, build the scroll root and add the modal and toast host as siblings at the top level. Wrap the modal and toast in gpui::deferred(...).with_priority(N) to manage z-index and rendering priority.

// Correct structure at the scroll root:
.child(content)
.child(modal)
.child(toast_host)

To ensure stateful children (like inputs in a list or virtualized views) maintain their state during reordering or updates, you must provide a unique, stable ID using .id(...).

• For append-only data: Use the row index as the ID.
• For mutable data: Use the data's primary key.

Failure to provide stable IDs will cause components to lose focus or state when the list reorders.

// Example: Using row index for a virtual list
text_input(format!("row-email-{ix}"))

// Example: Using a unique row ID for stable scope
format!("email-{row_id}")

The cargo public-api tool defines the public surface based on the following rules:

Included in the baseline:

• Every pub fn, pub struct, pub enum, pub trait, pub type, and pub const re-exported from the crate root.
• Re-exports (e.g., pub use foo::Bar).

Excluded from the baseline:

• Items within #[cfg(test)] modules.
• Items gated behind non-default feature flags (the tool runs with default features only).
• Items marked with #[doc(hidden)].
• Trait implementations (these are considered implicit and are not listed separately).

Limitations to note:

• Because --simplified does not surface trait implementations separately, a breaking change where a type no longer implements a specific trait will not be caught by a baseline diff. Use downstream smoke tests for this coverage.

Yororen UI separates interaction state from business state to prevent feedback loops:

• Component (Interaction State): Managed internally by the component. Includes things like caret position, selection, scroll, blink epoch, IME composition, or whether a Select is currently open or which index is highlighted. This is not in your app state.
• Your App (Business State): Managed by you. Includes the actual text content, the selected value, validation errors, or form submission status.

Communication happens via callbacks like on_change, on_pick, on_close, or on_toggle, which you use to write updates back into your Entity<MyState>.

In gpui, overlays like popovers, modals, and toasts do not automatically float on the z-axis. Using .absolute() only removes an element from the layout flow; the paint order remains determined by DOM order.

To ensure deterministic paint order (where higher priority elements are painted on top of lower ones), wrap your overlay elements in gpui::deferred(child).with_priority(N). This defers the element's paint until the end of the parent's prepaint, allowing it to sit above other elements regardless of nesting depth.

// Example of wrapping an element to ensure it paints on top
let my_overlay = gpui::deferred(overlay_element).with_priority(2);

Render closures must remain pure relative to the gpui redraw cycle. Do not perform any of the following inside a Render::render implementation:

• Spawning tasks (cx.spawn)
• Performing File I/O
• Any other side effects that trigger state changes

All side effects and asynchronous operations should be moved to event handlers.

For complex components like Select, Modal, or Popover, the renderer's compose method receives an Entity<XxxState> inside the XxxProps.

Responsibilities of a Composite Renderer:

1. Read State: Use props.state.read(cx) to access properties like .is_open(), .is_visible(), .value(), or .highlighted_index() to determine the visual state.
2. Handle Interactions: The renderer's render closure must register mouse/keyboard handlers that update the state. For example, a trigger should call state.update(cx, |s, _| s.toggle()), and an option row should call state.update(cx, |s, cx| s.pick(value, w, &mut *cx)).

// Example signature for a composite renderer
pub trait SelectRenderer: 'static {
    fn compose(
        &self,
        props: &SelectProps, // contains Entity<SelectState>
        cx: &App,
    ) -> Stateful<Div>;
}