orbital_date_pickers/guides/
custom_layout.rs

1//! Custom picker layout slots (DP-30).
2
3use leptos::prelude::*;
4use orbital_macros::component_doc;
5
6/// Reorder picker panel sections and inject custom action bars with layout slots.
7///
8/// Popover and inline calendar pickers expose slot components such as
9/// [`PickerLayoutActionBarSlot`](crate::PickerLayoutActionBarSlot) so product teams can
10/// place shortcuts, calendars, and custom actions in a consistent vertical stack without
11/// forking the picker implementation.
12///
13/// # When to use
14///
15/// - Calendars that need a clear action below the grid (Clear, Apply, Cancel)
16/// - Layouts where shortcut chips must stay above the month grid but actions sit below
17/// - Branded picker panels that add secondary controls without replacing core surfaces
18///
19/// # Usage
20///
21/// 1. Choose a picker that supports layout slots (for example [`DateCalendar`](crate::DateCalendar)).
22/// 2. Pass shortcut presets through `appearance.shortcuts` when needed.
23/// 3. Provide child content inside [`PickerLayoutActionBarSlot`] for buttons or links below the grid.
24/// 4. Use Orbital [`Button`](orbital_core_components::Button) for actions — not raw HTML buttons.
25///
26/// # Best Practices
27///
28/// ## Do's
29///
30/// * Keep action bars to one primary action plus optional secondary actions
31/// * Wire clear/reset handlers to the same bind signal the calendar uses
32/// * Match shortcut timezone to `appearance.timezone`
33///
34/// ## Don'ts
35///
36/// * Do not replace the entire picker when you only need an extra row — use layout slots
37/// * Do not stack so many sections that the popover exceeds the viewport on compact density
38///
39/// # Layout slots reference
40///
41/// | Slot | Description |
42/// |------|-------------|
43/// | [`PickerLayoutActionBarSlot`](crate::PickerLayoutActionBarSlot) | Row below the calendar grid for actions |
44///
45/// # Examples
46///
47/// ## Action bar below calendar
48/// Shortcut presets stay above the grid; a custom action bar clears the selection below.
49/// <!-- preview -->
50/// ```rust
51/// use leptos::prelude::*;
52/// use crate::preview::{PickerPreviewExample, PickerPreviewKnobs};
53/// use crate::{today_and_yesterday_shortcuts, DateCalendar, DateCalendarAppearance, DateCalendarBind, PickerLayoutActionBarSlot, DateTimeRange};
54/// use orbital_base_components::{DatetimeTimezone, OrbitalDateTime};
55/// use orbital_core_components::{Button, ButtonAppearance};
56/// let value = RwSignal::new(None::<OrbitalDateTime>);
57/// let tz = DatetimeTimezone::Local;
58/// view! {
59///     <PickerPreviewExample data_testid="date-pickers-custom-layout-preview">
60///         <PickerPreviewKnobs />
61///         <DateCalendar
62///             bind=value
63///             appearance=DateCalendarAppearance {
64///                 timezone: Signal::from(tz),
65///                 shortcuts: Signal::from(today_and_yesterday_shortcuts(tz)),
66///                 ..Default::default()
67///             }
68///         >
69///             <PickerLayoutActionBarSlot slot>
70///                 <span data-testid="date-pickers-custom-layout-clear">
71///                     <Button appearance=ButtonAppearance::Secondary on_click=Callback::new(move |_| value.set(None))>"Clear selection"</Button>
72///                 </span>
73///             </PickerLayoutActionBarSlot>
74///         </DateCalendar>
75///     </PickerPreviewExample>
76/// }
77/// ```
78#[component_doc(
79    category = "Calendar & Time",
80    preview_slug = "date-pickers-custom-layout",
81    preview_label = "Custom Layout",
82    preview_icon = icondata::AiLayoutOutlined,
83)]
84#[component]
85pub fn DatePickersCustomLayoutGuide() -> impl IntoView {
86    view! { () }
87}
orbital_date_pickers/guides/custom_layout.rs

orbital_date_pickers/guides/
custom_layout.rs
