orbital-core-components 0.1.1

Themed Orbital UI components for Leptos applications
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

use leptos::prelude::*;
use orbital_macros::component_doc;
use orbital_style::inject_style;

use crate::{Popover, PopoverPosition, PopoverSize, PopoverTrigger, PopoverTriggerType};

use crate::navigation::popover::popover_styles;

use super::anatomy::spotlight_anatomy;
use super::slots_to_views::anatomy_from_slots;
use super::styles::spotlight_styles;
use super::types::{
    SpotlightActions, SpotlightBody, SpotlightFooter, SpotlightHeader, SpotlightMedia,
    SpotlightTrigger,
};

/// `SpotlightPopover` opens a structured coaching panel from a trigger click — title, body,
/// optional media, actions, and footer slots for onboarding. Use it when the user initiates
/// help from a control; use [`SpotlightTip`](super::tip::SpotlightTip) or
/// [`SpotlightTour`](super::tour::tour::SpotlightTour) when the app drives visibility and anchoring.
///
/// # Spotlight coaching
///
/// - **User opens help from a button** — `SpotlightPopover` (this component)
/// - **App drives visibility by element `id`** — [`SpotlightTip`](super::tip::SpotlightTip)
/// - **Multi-step walkthrough** — [`SpotlightTour`](super::tour::tour::SpotlightTour)
///
/// # Examples
///
/// ## Default trigger
/// Click the trigger to open a spotlight panel with header, body, and actions.
/// <!-- preview -->
/// ```rust
/// use crate::{
///     Button, ButtonAppearance, SpotlightActions, SpotlightBody, SpotlightHeader,
///     SpotlightPopover, SpotlightTrigger,
/// };
/// view! {
///     <div data-testid="spotlight-popover-preview">
///         <SpotlightPopover>
///             <SpotlightTrigger slot>
///                 <Button>"Show tip"</Button>
///             </SpotlightTrigger>
///             <SpotlightHeader slot>"Welcome"</SpotlightHeader>
///             <SpotlightBody slot>"Use this panel to discover new features."</SpotlightBody>
///             <SpotlightActions slot>
///                 <Button appearance=ButtonAppearance::Primary>"Got it"</Button>
///             </SpotlightActions>
///         </SpotlightPopover>
///     </div>
/// }
/// ```
///
/// ## Media and footer
/// Illustration plus a step indicator in the footer.
/// <!-- preview -->
/// ```rust
/// use crate::{
///     Button, SpotlightBody, SpotlightFooter, SpotlightHeader, SpotlightMedia,
///     SpotlightPopover, SpotlightTrigger,
/// };
/// view! {
///     <div data-testid="spotlight-popover-media">
///         <SpotlightPopover>
///             <SpotlightTrigger slot>
///                 <Button>"Tour"</Button>
///             </SpotlightTrigger>
///             <SpotlightHeader slot>"Step 1"</SpotlightHeader>
///             <SpotlightMedia slot>
///                 <div style="height: 80px; background: var(--orb-color-surface-subtle);">"Media"</div>
///             </SpotlightMedia>
///             <SpotlightBody slot>"Filter events from the toolbar."</SpotlightBody>
///             <SpotlightFooter slot>"1 of 3"</SpotlightFooter>
///         </SpotlightPopover>
///     </div>
/// }
/// ```
#[component_doc(
    category = "Spotlight",
    preview_slug = "spotlight-popover",
    preview_label = "Spotlight Popover",
    preview_icon = icondata::AiReadOutlined,
)]
#[component]
pub fn SpotlightPopover(
    #[prop(optional, into)] class: MaybeProp<String>,
    #[prop(optional)] position: PopoverPosition,
    #[prop(optional, into)] size: Signal<PopoverSize>,
    spotlight_trigger: SpotlightTrigger,
    #[prop(optional)] spotlight_header: Option<SpotlightHeader>,
    #[prop(optional)] spotlight_body: Option<SpotlightBody>,
    #[prop(optional)] spotlight_media: Option<SpotlightMedia>,
    #[prop(optional)] spotlight_actions: Option<SpotlightActions>,
    #[prop(optional)] spotlight_footer: Option<SpotlightFooter>,
) -> impl IntoView {
    inject_style("orbital-spotlight", spotlight_styles());
    inject_style("orbital-popover", popover_styles());

    let surface_class = Signal::derive(move || {
        let mut parts = vec!["orbital-spotlight".to_string()];
        if let Some(extra) = class.get() {
            if !extra.is_empty() {
                parts.push(extra);
            }
        }
        parts.join(" ")
    });

    let anatomy = anatomy_from_slots(
        spotlight_header,
        spotlight_body,
        spotlight_media,
        spotlight_actions,
        spotlight_footer,
    );

    view! {
        <Popover
            class=surface_class
            trigger_type=PopoverTriggerType::Click
            position=position
            size=size
        >
            <PopoverTrigger slot>
                {(spotlight_trigger.children)()}
            </PopoverTrigger>
            {spotlight_anatomy(anatomy)}
        </Popover>
    }
}