lurq 0.65.1

A Rust UI toolkit with typed components, retained state, reactive signals, GPU rendering, and DevTools.
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
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
//! A banner: a message across the full width of what holds it, at the top of
//! a window or a page, that the app shows and takes away.

use std::sync::Arc;

use super::{
  AlertVariant, Link, LinkPart,
  alert::{IconChoice, close_control, close_style, shown_icon, wrapping},
  icons, names,
  part_style::{Length, PartAnimation},
  recipe::{Case, Interaction, Name, Recipe, ResolvedPart, ResolvedRecipe},
  shared::{FADE_IN, FADE_OUT, glyph},
  theme::{Themed, current_breakpoint, current_theme},
};
use crate::{
  app::theme::{IconSize, MotionDuration, MotionEasing, PaletteColor, RadiusSize, Theme, TypographyStyle},
  components::{self, Column, Row},
  layout::{
    Alignment,
    layout_kind::{Justify, Sticky},
    text_style::FontWeight,
  },
  node::{Element, dimension::Dimension},
};

/// The parts of a banner a recipe styles.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum BannerPart {
  /// What stands in the flow of the page as wide as the room it is given,
  /// shown or not: what sticks to the top where the page scrolls.
  Root,
  /// The bar: its fill, its corners, the room inside it, and how it comes in
  /// and leaves (`enter`, `exit`).
  Panel,
  /// The icon of its variant, at the start.
  Icon,
  /// What it says.
  Label,
  /// What holds the action, after the text.
  Action,
  /// A link given as the action, in the variant's color: what the board's
  /// "Update now" is.
  Link,
  /// What closes it, at the end.
  Close,
}

names!(BannerPart {
  Root => "root",
  Panel => "panel",
  Icon => "icon",
  Label => "label",
  Action => "action",
  Link => "link",
  Close => "close",
});

/// The states of a banner a recipe styles, besides what the pointer and the
/// keyboard do to its close control.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum BannerState {
  /// What is in it stands in its middle, the text as wide as it is.
  Centered,
  /// It sticks to the top of what scrolls it.
  Sticky,
}

names!(BannerState {
  Centered => "centered",
  Sticky => "sticky",
});

/// What a banner's action is: an element of the app's, or a link it gives the
/// variant's color.
enum BannerAction {
  Element(Element),
  Link(Link),
}

/// What builds a banner's nodes: a theme's in place of the default one.
pub type BannerRenderer = Arc<dyn Fn(BannerView) -> Element + Send + Sync>;

/// A banner: a message across the full width of what holds it, one line
/// where it fits, at the top of a window or a page. A new version, a
/// connection lost, a trial that ends.
///
/// ```
/// use lurq::ui::{AlertVariant, Banner, Link};
///
/// let update = Banner::new("lurq 0.61 is available with faster text shaping.")
///   .variant(AlertVariant::Info)
///   .link(Link::new("Update now").on_click(|_| println!("update")))
///   .on_close(|| println!("dismissed"));
/// ```
///
/// The app shows it and takes it away: [`Banner::open`] with what the app
/// keeps, false once its close control is pressed. It stays in the tree
/// either way, so it fades in as it is shown and out as it is taken away,
/// and the page under it moves up when it is gone. Where the page scrolls,
/// [`Banner::sticky`] keeps it at the top. It has a close control once it is
/// given [`on_close`](Banner::on_close), and none until then.
pub struct Banner {
  text: Arc<str>,
  variant: Name,
  icon: Option<IconChoice>,
  action: Option<BannerAction>,
  open: bool,
  centered: bool,
  sticky: bool,
  role: Option<Arc<str>>,
  label: Option<Arc<str>>,
  states: Vec<Name>,
  rules: Recipe,
  forced: Option<Interaction>,
  on_close: Vec<Arc<dyn Fn() + Send + Sync>>,
  id: Option<Arc<str>>,
  key: Option<Arc<str>>,
}

impl Banner {
  /// A banner that says `text`.
  pub fn new(text: &str) -> Self {
    Self {
      text: Arc::from(text),
      variant: AlertVariant::Neutral.into(),
      icon: None,
      action: None,
      open: true,
      centered: false,
      sticky: false,
      role: None,
      label: None,
      states: Vec::new(),
      rules: Recipe::new(),
      forced: None,
      on_close: Vec::new(),
      id: None,
      key: None,
    }
  }

  /// Its tone: an [`AlertVariant`], or a variant a theme adds, which has the
  /// neutral one's icon and role.
  pub fn variant(mut self, variant: impl Into<Name>) -> Self {
    self.variant = variant.into();
    self
  }

  /// An icon of the theme's set in place of the variant's, or none: `icon(None)`.
  pub fn icon(mut self, icon: impl Into<IconChoice>) -> Self {
    self.icon = Some(icon.into());
    self
  }

  /// What can be done about it, after the text: a button, or any element. It
  /// is the one action: a second, or a [`link`](Self::link), takes its place.
  pub fn action(mut self, action: impl Into<Element>) -> Self {
    self.action = Some(BannerAction::Element(action.into()));
    self
  }

  /// A link as the action, after the text, in the variant's color and
  /// semibold: "Update now". It takes the place of an action given before.
  pub fn link(mut self, link: Link) -> Self {
    self.action = Some(BannerAction::Link(link));
    self
  }

  /// Whether it is shown: the app's to say, which a press of the close
  /// control does not change. It is unless it says; taken away it fades out.
  pub fn open(mut self, open: bool) -> Self {
    self.open = open;
    self
  }

  /// Whether what is in it stands in its middle, as a bar at the top of a
  /// window has it, rather than from its start.
  pub fn centered(mut self, centered: bool) -> Self {
    self.centered = centered;
    self
  }

  /// Whether it sticks to the top of what scrolls the page it is on.
  pub fn sticky(mut self, sticky: bool) -> Self {
    self.sticky = sticky;
    self
  }

  /// What it is called to tooling that reads the tree, in place of its text.
  pub fn label(mut self, label: &str) -> Self {
    self.label = Some(Arc::from(label));
    self
  }

  /// What it is to tooling that reads the tree, in place of its variant's.
  pub fn role(mut self, role: &str) -> Self {
    self.role = Some(Arc::from(role));
    self
  }

  /// Puts the banner in a state the theme's recipe names, or takes it out.
  pub fn state(mut self, state: impl Into<Name>, on: bool) -> Self {
    let state = state.into();
    self.states.retain(|held| *held != state);
    if on {
      self.states.push(state);
    }
    self
  }

  /// Called on a press of its close control, which it has once it is given
  /// one: a banner with no `on_close` has no close control. The app takes the
  /// banner away: `open(false)`. A second handler is called after the first.
  pub fn on_close(mut self, handler: impl Fn() + Send + Sync + 'static) -> Self {
    self.on_close.push(Arc::new(handler));
    self
  }

  /// Styles one part of this banner over what the theme gives it.
  pub fn style(mut self, part: impl Into<Name>, style: impl FnOnce(super::PartStyle) -> super::PartStyle) -> Self {
    self.rules = self.rules.base(part, style);
    self
  }

  /// Lays rules over the theme's recipe for this banner.
  pub fn rules(mut self, rules: &Recipe) -> Self {
    self.rules = self.rules.extend(rules);
    self
  }

  /// Draws the close control as it is under the pointer, held down or
  /// focused from the keyboard, with nothing pointing at it: for a gallery
  /// or a test.
  pub fn force(mut self, interaction: Option<Interaction>) -> Self {
    self.forced = interaction;
    self
  }

  /// The id of the bar.
  pub fn id(mut self, id: impl Into<Arc<str>>) -> Self {
    self.id = Some(id.into());
    self
  }

  /// The key of what stands in the flow of the page.
  pub fn key(mut self, key: impl Into<Arc<str>>) -> Self {
    self.key = Some(key.into());
    self
  }

  /// Builds the banner in `theme`. Converting a banner into an element does
  /// this in the theme of what is being rendered.
  pub fn build(self, theme: &Theme) -> Element {
    // A variant a theme adds has the neutral one's icon and role.
    let tone = AlertVariant::named(self.variant).unwrap_or_default();
    let case = Case {
      variant: Some(self.variant),
      size: None,
      density: None,
      breakpoint: current_breakpoint(),
      states: self.states.clone(),
    }
    .state(BannerState::Centered, self.centered)
    .state(BannerState::Sticky, self.sticky);
    // The board's banner announces: a neutral and an informative one have the megaphone.
    let default_icon = match tone {
      AlertVariant::Neutral | AlertVariant::Info => icons::MEGAPHONE,
      tone => tone.icon(),
    };
    let view = BannerView {
      text: self.text,
      variant: self.variant,
      icon: shown_icon(self.icon, default_icon),
      action: self.action,
      open: self.open,
      centered: self.centered,
      sticky: self.sticky,
      role: self.role.unwrap_or_else(|| Arc::from(tone.role())),
      label: self.label,
      close_button: !self.on_close.is_empty(),
      recipe: theme
        .resolve::<Banner>(&case, Some(&self.rules))
        .owned_by(self.id.as_ref()),
      forced: self.forced,
      on_close: self.on_close,
      id: self.id,
      key: self.key,
    };
    match theme.renderer::<Banner>() {
      Some(renderer) => renderer(view),
      None => view.render(),
    }
  }
}

impl From<Banner> for Element {
  fn from(banner: Banner) -> Self {
    banner.build(&current_theme())
  }
}

/// A banner as a renderer sees it: what it was given, the style of its
/// parts, and its behavior ready to be dressed.
pub struct BannerView {
  pub text: Arc<str>,
  /// Its tone: an [`AlertVariant`]'s name, or a theme's.
  pub variant: Name,
  /// The icon it shows, by its name in the theme's set: the variant's, the one it was given, or none.
  pub icon: Option<Name>,
  action: Option<BannerAction>,
  /// Whether it is shown.
  pub open: bool,
  pub centered: bool,
  pub sticky: bool,
  /// What it is to tooling that reads the tree: `alert` or `status`, or what the app said.
  pub role: Arc<str>,
  /// What it is called to tooling, where that is not its text.
  pub label: Option<Arc<str>>,
  /// Whether it has a close control: it was given a handler for it.
  pub close_button: bool,
  /// The style of each part of this banner.
  pub recipe: ResolvedRecipe,
  forced: Option<Interaction>,
  on_close: Vec<Arc<dyn Fn() + Send + Sync>>,
  id: Option<Arc<str>>,
  key: Option<Arc<str>>,
}

impl BannerView {
  /// The style of a part, as this banner is to be drawn.
  pub fn part(&self, part: impl Into<Name>) -> ResolvedPart {
    self.recipe.part(part).forced(self.forced)
  }

  pub fn theme(&self) -> &Theme {
    self.recipe.theme()
  }

  /// The icon in the style of its part, if the banner has one.
  pub fn icon(&self) -> Option<Element> {
    self.icon.map(|icon| glyph(&self.part(BannerPart::Icon), icon, false))
  }

  /// What it says: as wide as the room the rest leaves it, going on to the
  /// next line where it does not fit in one; centered, as wide as it is and
  /// no wider than that room.
  pub fn text(&self) -> Column {
    let part = self.part(BannerPart::Label);
    if self.centered {
      Column::new()
        .flex_full(0.0, 1.0, None)
        .min_width(Dimension::Px(0.0))
        .part(&part)
        .child(part.text(&self.text))
    } else {
      wrapping(&part, &self.text).flex(1.0).min_width(Dimension::Px(0.0))
    }
  }

  /// The action, in the style of its part: a link given as one in the style
  /// of the `Link` part over the theme's for a link.
  pub fn action(&mut self) -> Option<Row> {
    let action = match self.action.take()? {
      BannerAction::Element(element) => element,
      BannerAction::Link(link) => {
        let style = self.part(BannerPart::Link).rest();
        let (color, text) = (style.foreground.clone(), style.text.clone());
        link
          .style(LinkPart::Root, move |mut s| {
            s.foreground = color;
            s
          })
          .style(LinkPart::Label, move |mut s| {
            s.text = text;
            s
          })
          .into()
      }
    };
    Some(
      Row::new()
        .align_items(Alignment::Center)
        .part(&self.part(BannerPart::Action))
        .child(action),
    )
  }

  /// What closes it: a press of it tells every handler of `on_close`.
  pub fn close(&self) -> components::Button {
    close_control(&self.part(BannerPart::Close), &self.on_close)
  }

  /// The bar: its icon, its text, its action and its close control side by
  /// side. It is what its role says to what reads the tree, called by its
  /// label or its text. It has a key, so that what holds it keeps it while it fades out.
  pub fn panel(&mut self) -> Row {
    let mut panel = Row::new()
      .key("banner")
      .align_items(Alignment::Center)
      .justify(if self.centered { Justify::Center } else { Justify::Start })
      .part(&self.part(BannerPart::Panel))
      .describe("a11y_role", self.role.clone())
      .describe("a11y_name", self.label.clone().unwrap_or_else(|| self.text.clone()));
    if let Some(icon) = self.icon() {
      panel = panel.child(icon);
    }
    panel = panel.child(self.text());
    if let Some(action) = self.action() {
      panel = panel.child(action);
    }
    if self.close_button {
      panel = panel.child(self.close());
    }
    if let Some(id) = &self.id {
      panel = panel.id(id.clone());
    }
    panel
  }

  /// How the default renderer builds a banner: what stands in the flow of
  /// the page, as wide as the room it is given, and in it the bar while it
  /// is shown. What stands keeps the bar while it leaves.
  pub fn render(mut self) -> Element {
    let mut root = Column::new().presence().part(&self.part(BannerPart::Root));
    if self.sticky {
      root = root.sticky(Sticky::top(0.0));
    }
    if self.open {
      root = root.child(self.panel());
    }
    if let Some(key) = &self.key {
      root = root.key(key.clone());
    }
    root.into()
  }
}

impl crate::ui::Styled for Banner {
  type Component = Self;

  fn rules(self, rules: &crate::ui::Recipe) -> Self {
    Self::rules(self, rules)
  }

  fn state(self, state: impl Into<crate::ui::Name>, on: bool) -> Self {
    Self::state(self, state, on)
  }
}

impl Themed for Banner {
  const NAME: &'static str = "banner";
  type Renderer = BannerRenderer;

  fn parts() -> crate::ui::Declared {
    BannerPart::declared()
  }

  fn states() -> crate::ui::Declared {
    BannerState::declared()
  }

  /// The design's banner (`pencil/lurq-design-system.pen`, Banner): a bar as
  /// wide as the room it is given in the muted form of the variant's color
  /// (the muted fill for a neutral one), with corners of `radius-md`, padded
  /// 10 and 16. In it, 12 apart and centered on a line, the icon of 16 in the
  /// variant's color, the text of 13 in the foreground's, a link in the
  /// variant's color, semibold, and the close control of 16. It fades in
  /// over the theme's base duration as it is shown and out over its fast
  /// one as it is taken away.
  fn recipe() -> Recipe {
    use BannerPart as P;
    let mut recipe = Recipe::new()
      .base(P::Root, |s| s.width(Length::Fill))
      .base(P::Panel, |s| {
        s.width(Length::Fill)
          .background(PaletteColor::Muted)
          .foreground(PaletteColor::Foreground)
          .radius(RadiusSize::Md)
          .padding_x(16.0)
          .padding_y(10.0)
          .gap(12.0)
          .enter(PartAnimation::new(FADE_IN, MotionDuration::Base, MotionEasing::Enter))
          .exit(PartAnimation::new(FADE_OUT, MotionDuration::Fast, MotionEasing::Exit))
      })
      .base(P::Icon, |s| {
        s.square(Length::Icon(IconSize::Md))
          .foreground(PaletteColor::Foreground)
      })
      .base(P::Label, |s| {
        s.typography(TypographyStyle::Body)
          .font_size(13.0)
          .foreground(PaletteColor::Foreground)
      })
      .base(P::Action, |s| s.gap(8.0))
      .base(P::Link, |s| {
        s.typography(TypographyStyle::Body)
          .font_size(13.0)
          .weight(FontWeight::SemiBold)
          .foreground(PaletteColor::Foreground)
      });
    recipe = close_style(recipe, P::Close).base(P::Close, |s| s.foreground(PaletteColor::Foreground));
    for variant in AlertVariant::all().iter().copied() {
      recipe = recipe
        .variant(variant, P::Panel, |s| s.background(variant.tint()))
        .variant(variant, P::Icon, |s| s.foreground(variant.accent()))
        .variant(variant, P::Link, |s| s.foreground(variant.accent()));
    }
    recipe
  }
}