damascene-core 0.4.4

Damascene — backend-agnostic UI library core
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

//! Pagination anatomy — compact page-navigation controls.

// Lock in full per-item documentation for this module (issue #73).
#![warn(missing_docs)]

use std::panic::Location;

use crate::metrics::MetricsRole;
use crate::tokens;
use crate::tree::*;
use crate::widgets::button::{button, button_with_icon};
use crate::widgets::text::text;

/// Outer pagination container — a hug-sized centered row, mirroring
/// shadcn's `Pagination` root.
#[track_caller]
pub fn pagination<I, E>(children: I) -> El
where
    I: IntoIterator<Item = E>,
    E: Into<El>,
{
    row(children)
        .at_loc(Location::caller())
        .width(Size::Hug)
        .height(Size::Hug)
        .gap(tokens::SPACE_1)
        .align(Align::Center)
}

/// Row holding the page controls ([`pagination_item`]s), mirroring
/// shadcn's `PaginationContent`.
#[track_caller]
pub fn pagination_content<I, E>(children: I) -> El
where
    I: IntoIterator<Item = E>,
    E: Into<El>,
{
    row(children)
        .at_loc(Location::caller())
        .width(Size::Hug)
        .height(Size::Hug)
        .gap(tokens::SPACE_1)
        .align(Align::Center)
}

/// Wrapper around a single control (link, ellipsis, previous/next),
/// mirroring shadcn's `PaginationItem`.
#[track_caller]
pub fn pagination_item(child: impl Into<El>) -> El {
    row([child.into()])
        .at_loc(Location::caller())
        .width(Size::Hug)
        .height(Size::Hug)
        .align(Align::Center)
}

/// Square page-number button. `current: true` renders the secondary
/// (selected) treatment; other pages render ghost. Add `.key(...)` to
/// make it route events.
#[track_caller]
pub fn pagination_link(label: impl Into<String>, current: bool) -> El {
    let link = button(label)
        .at_loc(Location::caller())
        .metrics_role(MetricsRole::Button)
        .width(Size::Fixed(tokens::CONTROL_HEIGHT))
        .height(Size::Fixed(tokens::CONTROL_HEIGHT));
    if current {
        link.secondary()
    } else {
        link.ghost()
    }
}

/// Ghost "Previous" button with a leading chevron-left icon.
#[track_caller]
pub fn pagination_previous() -> El {
    button_with_icon("chevron-left", "Previous")
        .at_loc(Location::caller())
        .ghost()
}

/// Ghost "Next" button with a chevron-right icon.
#[track_caller]
pub fn pagination_next() -> El {
    button_with_icon("chevron-right", "Next")
        .at_loc(Location::caller())
        .ghost()
}

/// Non-interactive "..." placeholder for elided page ranges.
#[track_caller]
pub fn pagination_ellipsis() -> El {
    text("...")
        .at_loc(Location::caller())
        .muted()
        .width(Size::Fixed(tokens::CONTROL_HEIGHT))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn pagination_content_centers_items() {
        let pages = pagination_content([
            pagination_item(pagination_previous()),
            pagination_item(pagination_link("1", true)),
            pagination_item(pagination_ellipsis()),
            pagination_item(pagination_next()),
        ]);

        assert_eq!(pages.axis, Axis::Row);
        assert_eq!(pages.align, Align::Center);
        assert_eq!(pages.gap, tokens::SPACE_1);
        assert_eq!(pages.children.len(), 4);
    }

    #[test]
    fn pagination_link_has_fixed_square_box() {
        let current = pagination_link("2", true);

        assert_eq!(current.width, Size::Fixed(tokens::CONTROL_HEIGHT));
        assert_eq!(current.height, Size::Fixed(tokens::CONTROL_HEIGHT));
        assert_eq!(current.metrics_role, Some(MetricsRole::Button));
    }
}