orbital-date-pickers 0.1.1

Date and time picker components for Orbital
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

//! Custom day and month renderers (DP-29).

use chrono::Datelike;
use leptos::prelude::*;
use orbital_core_components::{
    default_calendar_day, default_calendar_month_button, CalendarDayProps, CalendarMonthButtonProps,
};
use orbital_macros::component_doc;

pub fn weekend_day(props: CalendarDayProps) -> AnyView {
    let is_weekend = matches!(
        props.date.weekday(),
        chrono::Weekday::Sat | chrono::Weekday::Sun
    );
    if is_weekend {
        view! {
            <div class="orb-picker-custom-day orb-picker-custom-day--weekend">
                {default_calendar_day(props)}
            </div>
        }
        .into_any()
    } else {
        default_calendar_day(props).into_any()
    }
}

fn short_month_button(props: CalendarMonthButtonProps) -> impl IntoView {
    view! {
        <div class="orb-picker-custom-month">
            {default_calendar_month_button(CalendarMonthButtonProps {
                label: props.label.chars().next().unwrap_or('?').to_string(),
                ..props
            })}
        </div>
    }
}

/// Customize calendar day cells and month navigation buttons with renderer callbacks.
///
/// Pass an [`Arc`] renderer to `appearance.day` on [`DateCalendar`](crate::DateCalendar) or
/// popover [`DatePicker`](orbital_core_components::DatePicker) surfaces. Start from
/// [`default_calendar_day`] and [`default_calendar_month_button`] to preserve keyboard
/// behavior and selection styling, then wrap or extend the default output.
///
/// # When to use
///
/// - Highlighting weekends, holidays, or blackout dates in the grid
/// - Compact month/year pickers with abbreviated labels
/// - Product-specific day badges (dots, counts) on calendar cells
///
/// # Usage
///
/// 1. Define a function matching [`CalendarDayRenderer`](orbital_core_components::CalendarDayRenderer) (or month button equivalent).
/// 2. Delegate to the default renderer for baseline interaction, then wrap with extra markup or classes.
/// 3. Assign `Some(Arc::new(your_renderer))` to `appearance.day` on the calendar or date picker.
///
/// # Best Practices
///
/// ## Do's
///
/// * Call [`default_calendar_day`] inside custom renderers so click and aria behavior stays intact
/// * Keep custom markup inside the cell boundary — avoid overlapping adjacent days
/// * Use CSS classes on wrappers rather than inline styles for theme compatibility
///
/// ## Don'ts
///
/// * Do not replace grid cells with non-interactive elements that block day selection
/// * Do not fork keyboard navigation — extend defaults instead of reimplementing cells
///
/// # Renderer reference
///
/// | Hook | Description |
/// |------|-------------|
/// | `appearance.day` | Custom day cell renderer on [`DateCalendar`](crate::DateCalendar) |
/// | [`default_calendar_day`] | Baseline day button with selection and disabled states |
/// | [`default_calendar_month_button`] | Baseline month/year navigation control |
///
/// # Examples
///
/// ## Custom day cell
/// Highlight weekend days with a custom day renderer on [`DateCalendar`].
/// <!-- preview -->
/// ```rust
/// use std::sync::Arc;
/// use orbital_core_components::CalendarDayRenderer;
/// use crate::preview::{PickerPreviewExample, PickerPreviewKnobs};
/// use crate::{DateCalendar, DateCalendarAppearance, DateCalendarBind};
/// use orbital_base_components::OrbitalDateTime;
/// let value = RwSignal::new(None::<OrbitalDateTime>);
/// let day: CalendarDayRenderer = Arc::new(crate::weekend_day);
/// view! {
///     <PickerPreviewExample data_testid="date-pickers-custom-components-preview">
///         <PickerPreviewKnobs />
///         <DateCalendar
///             bind=value
///             appearance=DateCalendarAppearance { day: Some(day), ..Default::default() }
///         />
///     </PickerPreviewExample>
/// }
/// ```
#[component_doc(
    category = "Calendar & Time",
    preview_slug = "date-pickers-custom-components",
    preview_label = "Custom Components",
    preview_icon = icondata::AiCalendarOutlined,
)]
#[component]
pub fn DatePickersCustomComponentsGuide() -> impl IntoView {
    view! { () }
}