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
//! Orbital Date Pickers product overview (DP-01).
use *;
use component_doc;
/// Hub for the Orbital Date Pickers plugin — component family, first picker setup, and common questions.
///
/// See the crate README for picker and field selection.
/// For resource scheduling (week grid or Gantt lanes), use **Scheduling** previews
/// (`SchedulerCalendar` / `SchedulerTimeline` in `orbital-scheduler`) — not form pickers.
///
/// # When to use
///
/// - Onboarding a new form or settings page that needs date, time, or range entry
/// - Answering setup questions before picking a specific picker component
///
/// # Usage
///
/// Wrap the tree in [`DatetimeLocale`] and bind [`OrbitalDateTime`] through a labeled [`Field`](orbital_core_components::Field)
/// or a picker component from this crate.
///
/// # Best Practices
///
/// ## Why OrbitalDateTime instead of unix seconds?
///
/// Public APIs bind `Option<OrbitalDateTime>` with explicit [`DatetimeTimezone`]. Convert at boundaries via
/// [`ToUnixSeconds`](orbital_base_components::ToUnixSeconds) or [`ToIso8601`](orbital_base_components::ToIso8601).
///
/// ## Do I need an adapter?
///
/// No. Use [`DatetimeLocale`] plus [`DatetimeFormat`](orbital_base_components::DatetimeFormat). Orbital does not ship
/// LocalizationProvider or dayjs adapters.
///
/// ## SSR and hydration
///
/// Wrap pickers in [`DatetimeLocale`] on server and client with matching timezone and format signals.
///
/// # Examples
///
/// ## Picker family
/// Core plugin fields and pickers sharing one [`OrbitalDateTime`] bind model.
/// <!-- preview -->
/// ```rust
/// use crate::preview::{PickerPreviewExample, PickerPreviewKnobs};
/// use orbital_core_components::{Flex, FlexGap, FlexWrap};
/// use crate::{DateCalendar, DateField, DateTimePicker, TimeField};
/// use orbital_base_components::OrbitalDateTime;
/// let date = RwSignal::new(None::<OrbitalDateTime>);
/// let time = RwSignal::new(None::<OrbitalDateTime>);
/// let datetime = RwSignal::new(None::<OrbitalDateTime>);
/// view! {
/// <PickerPreviewExample data_testid="date-pickers-overview-preview">
/// <PickerPreviewKnobs />
/// <Flex gap=FlexGap::Medium wrap=FlexWrap::Wrap>
/// <DateField bind=date />
/// <TimeField bind=time />
/// </Flex>
/// <DateCalendar bind=date />
/// <DateTimePicker bind=datetime />
/// </PickerPreviewExample>
/// }
/// ```
///
/// ## Minimal DatePicker
/// Wrap the tree in [`DatetimeLocale`] and bind [`OrbitalDateTime`] through a labeled [`Field`].
/// <!-- preview -->
/// ```rust
/// use crate::preview::{PickerPreviewExample, PickerPreviewKnobs};
/// use crate::DatetimeLocale;
/// use orbital_core_components::{DatePicker, DatePickerBind, Field};
/// use orbital_base_components::{DatetimeTimezone, OrbitalDateTime};
/// let value = RwSignal::new(None::<OrbitalDateTime>);
/// view! {
/// <PickerPreviewExample data_testid="date-pickers-overview-getting-started-preview">
/// <PickerPreviewKnobs />
/// <DatetimeLocale default_timezone=Signal::from(DatetimeTimezone::Local)>
/// <Field label="Event date" name="event_date">
/// <DatePicker bind=value />
/// </Field>
/// </DatetimeLocale>
/// </PickerPreviewExample>
/// }
/// ```