ailloli_ui_widgets/controls/
card.rs

1//! Theme-aware containers for grouping a single child as a card.
2
3use ailloli_ui_core::style::{Border, BoxShadow, FlexItemStyle, LayoutStyle, Radius};
4use ailloli_ui_core::{Color, Theme};
5use ailloli_ui_runtime::component::{IntoView, View};
6
7use crate::layout::Container;
8
9#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
10/// Built-in visual treatments for a [`Card`].
11///
12/// # Examples
13///
14/// ```
15/// use ailloli_ui_widgets::controls::CardVariant;
16/// assert_eq!(CardVariant::default(), CardVariant::Surface);
17/// ```
18pub enum CardVariant {
19    /// Opaque panel surface with a border and no shadow.
20    #[default]
21    Surface,
22    /// Elevated surface with the theme's medium shadow.
23    Elevated,
24    /// Transparent surface with a standard border.
25    Outline,
26    /// Accent-tinted surface, border, and glow.
27    Accent,
28}
29
30#[derive(Clone, Debug, PartialEq)]
31/// Fully resolved visual style for a [`Card`].
32///
33/// Dimensions are logical pixels. Only the top border width/color and top-left
34/// radius are currently forwarded to the underlying uniform container; callers
35/// should therefore use uniform borders and radii for predictable rendering.
36///
37/// # Examples
38///
39/// ```
40/// use ailloli_ui_core::Theme;
41/// use ailloli_ui_widgets::controls::{CardStyle, CardVariant};
42/// let style = CardStyle::from_theme(Theme::dark(), CardVariant::Elevated);
43/// assert_eq!(style.shadows.len(), 1);
44/// assert!(style.padding >= 0.0);
45/// ```
46pub struct CardStyle {
47    /// Card fill color.
48    pub background: Color,
49    /// Card border; use uniform widths and colors.
50    pub border: Border,
51    /// Card corner radii; use a uniform value for current rendering.
52    pub radius: Radius,
53    /// Shadows painted in vector order by the backing container.
54    pub shadows: Vec<BoxShadow>,
55    /// Inner padding on every edge, in logical pixels.
56    pub padding: f32,
57}
58
59impl Default for CardStyle {
60    fn default() -> Self {
61        Self::from_theme(Theme::default(), CardVariant::Surface)
62    }
63}
64
65impl CardStyle {
66    /// Resolves `variant` against `theme` into concrete colors and metrics.
67    ///
68    /// `Surface` and `Outline` have no shadows, `Elevated` has one medium
69    /// shadow, and `Accent` has one accent-colored glow.
70    ///
71    /// # Examples
72    ///
73    /// ```
74    /// use ailloli_ui_core::{Color, Theme};
75    /// use ailloli_ui_widgets::controls::{CardStyle, CardVariant};
76    /// let style = CardStyle::from_theme(Theme::dark(), CardVariant::Outline);
77    /// assert_eq!(style.background, Color::TRANSPARENT);
78    /// assert!(style.shadows.is_empty());
79    /// ```
80    pub fn from_theme(theme: Theme, variant: CardVariant) -> Self {
81        let palette = theme.palette();
82        let radius = theme.radius().panel();
83        match variant {
84            CardVariant::Surface => Self {
85                background: palette.surface,
86                border: Border::new(1.0, palette.border),
87                radius,
88                shadows: Vec::new(),
89                padding: theme.spacing().md,
90            },
91            CardVariant::Elevated => Self {
92                background: palette.surface_elevated,
93                border: Border::new(1.0, palette.border),
94                radius,
95                shadows: vec![theme.shadows().md],
96                padding: theme.spacing().md,
97            },
98            CardVariant::Outline => Self {
99                background: Color::TRANSPARENT,
100                border: Border::new(1.0, palette.border),
101                radius,
102                shadows: Vec::new(),
103                padding: theme.spacing().md,
104            },
105            CardVariant::Accent => Self {
106                background: palette.accent.with_alpha(0.12),
107                border: Border::new(1.0, palette.accent.with_alpha(0.55)),
108                radius,
109                shadows: vec![BoxShadow::glow(palette.accent.with_alpha(0.22))],
110                padding: theme.spacing().md,
111            },
112        }
113    }
114}
115
116/// A themed, single-child panel with configurable layout.
117///
118/// Adding a second child replaces the first. The generic parameter is the
119/// action type emitted by descendants.
120///
121/// # Examples
122///
123/// ```
124/// use ailloli_ui_widgets::controls::Card;
125/// let card: Card<()> = Card::new();
126/// let _ = card;
127/// ```
128pub struct Card<A = ()> {
129    /// Layout applied to the backing container.
130    pub(crate) layout: LayoutStyle,
131    /// Flex-item behavior applied when this card is a child.
132    pub(crate) flex_item: FlexItemStyle,
133    /// Resolved paint and padding configuration.
134    style: CardStyle,
135    /// The optional sole child; a later [`Card::child`] call replaces it.
136    child: Option<View<A>>,
137}
138
139crate::impl_layout_builders!(Card);
140
141impl<A: 'static> Default for Card<A> {
142    fn default() -> Self {
143        Self::new()
144    }
145}
146
147impl<A: 'static> Card<A> {
148    /// Creates an empty surface card using the default theme.
149    ///
150    /// Its layout padding is initialized from [`CardStyle::default`].
151    ///
152    /// # Examples
153    ///
154    /// ```
155    /// use ailloli_ui_widgets::controls::Card;
156    /// let card: Card<()> = Card::new();
157    /// let _ = card;
158    /// ```
159    pub fn new() -> Self {
160        let style = CardStyle::default();
161        Self {
162            layout: LayoutStyle::default().padding(style.padding),
163            flex_item: FlexItemStyle::default(),
164            style,
165            child: None,
166        }
167    }
168
169    /// Creates an empty [`CardVariant::Surface`] card.
170    ///
171    /// # Examples
172    ///
173    /// ```
174    /// use ailloli_ui_widgets::controls::Card;
175    /// let card: Card<()> = Card::surface();
176    /// let _ = card;
177    /// ```
178    pub fn surface() -> Self {
179        Self::new().variant(CardVariant::Surface)
180    }
181
182    /// Creates an empty [`CardVariant::Elevated`] card.
183    ///
184    /// # Examples
185    ///
186    /// ```
187    /// use ailloli_ui_widgets::controls::Card;
188    /// let card: Card<()> = Card::elevated();
189    /// let _ = card;
190    /// ```
191    pub fn elevated() -> Self {
192        Self::new().variant(CardVariant::Elevated)
193    }
194
195    /// Replaces the visual style with the default-theme form of `variant`.
196    ///
197    /// This also replaces all four layout padding edges with the variant's
198    /// resolved padding. Call layout padding builders after this method when
199    /// an override is required.
200    ///
201    /// # Examples
202    ///
203    /// ```
204    /// use ailloli_ui_widgets::controls::{Card, CardVariant};
205    /// let card: Card<()> = Card::new().variant(CardVariant::Accent);
206    /// let _ = card;
207    /// ```
208    pub fn variant(mut self, variant: CardVariant) -> Self {
209        self.style = CardStyle::from_theme(Theme::default(), variant);
210        self.layout = self.layout.padding(self.style.padding);
211        self
212    }
213
214    /// Replaces the resolved card style and synchronizes layout padding.
215    ///
216    /// Style values, including negative padding, are accepted as-is.
217    ///
218    /// # Examples
219    ///
220    /// ```
221    /// use ailloli_ui_core::Theme;
222    /// use ailloli_ui_widgets::controls::{Card, CardStyle, CardVariant};
223    /// let style = CardStyle::from_theme(Theme::dark(), CardVariant::Outline);
224    /// let card: Card<()> = Card::new().card_style(style);
225    /// let _ = card;
226    /// ```
227    pub fn card_style(mut self, style: CardStyle) -> Self {
228        self.layout = self.layout.padding(style.padding);
229        self.style = style;
230        self
231    }
232
233    /// Sets the card's sole child, replacing any child set earlier.
234    ///
235    /// # Examples
236    ///
237    /// ```
238    /// use ailloli_ui_widgets::controls::Card;
239    /// use ailloli_ui_widgets::text::Text;
240    /// let card = Card::<()>::new().child(Text::new("Details"));
241    /// let _ = card;
242    /// ```
243    pub fn child(mut self, child: impl IntoView<A>) -> Self {
244        self.child = Some(child.into_view());
245        self
246    }
247}
248
249impl<A: 'static> IntoView<A> for Card<A> {
250    fn into_view(self) -> View<A> {
251        let mut container = Container::<A>::new()
252            .background(self.style.background)
253            .radius(self.style.radius.tl)
254            .border(self.style.border.widths.top, self.style.border.colors.top);
255        container.layout = self.layout;
256        container.flex_item = self.flex_item;
257        for shadow in self.style.shadows {
258            container = container.shadow(shadow);
259        }
260        if let Some(child) = self.child {
261            container = container.child(child);
262        }
263        container.into_view()
264    }
265}