fret-ui 0.1.0

Mechanism-layer UI engine for Fret with tree, layout, focus, routing, and interaction contracts.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

use std::any::TypeId;

use fret_core::{AppWindowId, NodeId, Rect, UiServices};
use fret_runtime::ModelId;

use crate::element::AnyElement;
use crate::elements::ElementContext;
use crate::{UiHost, UiTree, declarative};

/// Apply all "external" changes that affect the UI tree for the current frame.
///
/// Contract:
/// - Call this before `declarative::render_root` for a given window/frame.
/// - Use the same `changed_*` lists drained from the host/runtime for that frame.
///
/// Rationale:
/// - View-cache subtree reuse relies on correct invalidation flags being set before mount.
/// - This helper makes call sites less error-prone by enforcing a single ordering point.
pub fn propagate_changes<H: UiHost>(
    ui: &mut UiTree<H>,
    app: &mut H,
    changed_models: &[ModelId],
    changed_globals: &[TypeId],
) -> bool {
    let mut did_work = false;
    if !changed_models.is_empty() {
        did_work |= ui.propagate_model_changes(app, changed_models);
    }
    if !changed_globals.is_empty() {
        did_work |= ui.propagate_global_changes(app, changed_globals);
    }
    did_work
}

/// Render a declarative root after applying the provided per-frame change lists.
///
/// This helper exists to make the "propagate changes before mount" ordering hard to get wrong in
/// runner/driver code.
#[allow(clippy::too_many_arguments)]
pub fn render_root_with_changes<H, I>(
    ui: &mut UiTree<H>,
    app: &mut H,
    services: &mut dyn UiServices,
    window: AppWindowId,
    bounds: Rect,
    root_name: &str,
    changed_models: &[ModelId],
    changed_globals: &[TypeId],
    render: impl FnOnce(&mut ElementContext<'_, H>) -> I,
) -> NodeId
where
    H: UiHost + 'static,
    I: IntoIterator<Item = AnyElement>,
{
    let _ = propagate_changes(ui, app, changed_models, changed_globals);
    declarative::render_root(ui, app, services, window, bounds, root_name, render)
}

/// Convenience wrapper around [`render_root_with_changes`] for base-layer roots.
#[allow(clippy::too_many_arguments)]
pub fn render_base_root_with_changes<H, I>(
    ui: &mut UiTree<H>,
    app: &mut H,
    services: &mut dyn UiServices,
    window: AppWindowId,
    bounds: Rect,
    root_name: &str,
    changed_models: &[ModelId],
    changed_globals: &[TypeId],
    render: impl FnOnce(&mut ElementContext<'_, H>) -> I,
) -> NodeId
where
    H: UiHost + 'static,
    I: IntoIterator<Item = AnyElement>,
{
    let root = render_root_with_changes(
        ui,
        app,
        services,
        window,
        bounds,
        root_name,
        changed_models,
        changed_globals,
        render,
    );
    ui.set_root(root);
    root
}