orbital_date_pickers/guides/
overview.rs

1//! Orbital Date Pickers product overview (DP-01).
2
3use leptos::prelude::*;
4use orbital_macros::component_doc;
5
6/// Hub for the Orbital Date Pickers plugin — component family, first picker setup, and common questions.
7///
8/// See the crate README for picker and field selection.
9/// For resource scheduling (week grid or Gantt lanes), use **Scheduling** previews
10/// (`SchedulerCalendar` / `SchedulerTimeline` in `orbital-scheduler`) — not form pickers.
11///
12/// # When to use
13///
14/// - Onboarding a new form or settings page that needs date, time, or range entry
15/// - Answering setup questions before picking a specific picker component
16///
17/// # Usage
18///
19/// Wrap the tree in [`DatetimeLocale`] and bind [`OrbitalDateTime`] through a labeled [`Field`](orbital_core_components::Field)
20/// or a picker component from this crate.
21///
22/// # Best Practices
23///
24/// ## Why OrbitalDateTime instead of unix seconds?
25///
26/// Public APIs bind `Option<OrbitalDateTime>` with explicit [`DatetimeTimezone`]. Convert at boundaries via
27/// [`ToUnixSeconds`](orbital_base_components::ToUnixSeconds) or [`ToIso8601`](orbital_base_components::ToIso8601).
28///
29/// ## Do I need an adapter?
30///
31/// No. Use [`DatetimeLocale`] plus [`DatetimeFormat`](orbital_base_components::DatetimeFormat). Orbital does not ship
32/// LocalizationProvider or dayjs adapters.
33///
34/// ## SSR and hydration
35///
36/// Wrap pickers in [`DatetimeLocale`] on server and client with matching timezone and format signals.
37///
38/// # Examples
39///
40/// ## Picker family
41/// Core plugin fields and pickers sharing one [`OrbitalDateTime`] bind model.
42/// <!-- preview -->
43/// ```rust
44/// use crate::preview::{PickerPreviewExample, PickerPreviewKnobs};
45/// use orbital_core_components::{Flex, FlexGap, FlexWrap};
46/// use crate::{DateCalendar, DateField, DateTimePicker, TimeField};
47/// use orbital_base_components::OrbitalDateTime;
48/// let date = RwSignal::new(None::<OrbitalDateTime>);
49/// let time = RwSignal::new(None::<OrbitalDateTime>);
50/// let datetime = RwSignal::new(None::<OrbitalDateTime>);
51/// view! {
52///     <PickerPreviewExample data_testid="date-pickers-overview-preview">
53///         <PickerPreviewKnobs />
54///         <Flex gap=FlexGap::Medium wrap=FlexWrap::Wrap>
55///             <DateField bind=date />
56///             <TimeField bind=time />
57///         </Flex>
58///         <DateCalendar bind=date />
59///         <DateTimePicker bind=datetime />
60///     </PickerPreviewExample>
61/// }
62/// ```
63///
64/// ## Minimal DatePicker
65/// Wrap the tree in [`DatetimeLocale`] and bind [`OrbitalDateTime`] through a labeled [`Field`].
66/// <!-- preview -->
67/// ```rust
68/// use crate::preview::{PickerPreviewExample, PickerPreviewKnobs};
69/// use crate::DatetimeLocale;
70/// use orbital_core_components::{DatePicker, DatePickerBind, Field};
71/// use orbital_base_components::{DatetimeTimezone, OrbitalDateTime};
72/// let value = RwSignal::new(None::<OrbitalDateTime>);
73/// view! {
74///     <PickerPreviewExample data_testid="date-pickers-overview-getting-started-preview">
75///         <PickerPreviewKnobs />
76///         <DatetimeLocale default_timezone=Signal::from(DatetimeTimezone::Local)>
77///             <Field label="Event date" name="event_date">
78///                 <DatePicker bind=value />
79///             </Field>
80///         </DatetimeLocale>
81///     </PickerPreviewExample>
82/// }
83/// ```
84#[component_doc(
85    category = "Calendar & Time",
86    preview_slug = "date-pickers-overview",
87    preview_label = "Overview",
88    preview_icon = icondata::AiCalendarOutlined,
89)]
90#[component]
91pub fn DatePickersOverviewGuide() -> impl IntoView {
92    view! { () }
93}
orbital_date_pickers/guides/overview.rs

orbital_date_pickers/guides/
overview.rs
