herogpui-theme 0.14.0

//! Layout tokens — a faithful port of HeroUI v3's non-color custom properties
//! from `packages/styles/themes/default/variables.css`.
//!
//! v3 replaced v2's size-named tokens (`radius-small`, `box-shadow-medium`)
//! with a single `--radius` base plus calculated steps, and with
//! component-semantic shadows (`--surface-shadow`, `--overlay-shadow`,
//! `--field-shadow`).

use gpui::{point, px, BoxShadow, Pixels};

/// How a [`Skeleton`](../herogpui_components/struct.Skeleton.html) animates by
/// default (`--skeleton-animation`).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum SkeletonAnimation {
    #[default]
    /// Shimmer sweep (the default).
    Shimmer,
    /// Opacity pulse.
    Pulse,
    /// No animation.
    None,
}

/// Spacing, radius, border and shadow tokens shared by all components.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct LayoutTheme {
    /// `--spacing: 0.25rem`
    pub spacing: Pixels,

    /// `--radius: 0.5rem` — the base every other radius is calculated from.
    pub radius: Pixels,
    /// `--field-radius: calc(var(--radius) * 1.5)`
    pub field_radius: Pixels,

    /// `--border-width: 1px`
    pub border_width: Pixels,
    /// `--field-border-width: 0px`
    pub field_border_width: Pixels,

    /// `--disabled-opacity: 0.5`
    pub disabled_opacity: f32,
    /// `--ring-offset-width: 2px`
    pub ring_offset_width: Pixels,

    /// `--surface-shadow` — cards, accordions and other inline containers.
    pub surface_shadow: Vec<BoxShadow>,
    /// `--overlay-shadow` — tooltips, popovers, modals and menus.
    pub overlay_shadow: Vec<BoxShadow>,
    /// `--field-shadow` — inputs and other form controls.
    pub field_shadow: Vec<BoxShadow>,

    /// `--skeleton-animation`
    pub skeleton_animation: SkeletonAnimation,
    /// `--tooltip-delay: 1500ms`
    pub tooltip_delay_ms: u64,
    /// `--tooltip-close-delay: 500ms`
    pub tooltip_close_delay_ms: u64,
    /// The hairline a floating panel draws instead of a border.
    ///
    /// v3 gives its panels no border at all: light mode separates them with
    /// `--overlay-shadow`, and dark mode adds `0 0 1px 0 rgba(255,255,255,.3)
    /// **inset**` -- a one-pixel highlight just inside the edge. gpui has no
    /// inset shadow, so the closest reproduction is a one-pixel border in that
    /// colour, and in light mode there is none.
    pub overlay_hairline: Option<gpui::Hsla>,

    /// The cursor an interactive control shows while the pointer is over it.
    ///
    /// v3 gives every clickable control `cursor: pointer`, so the default is
    /// [`gpui::CursorStyle::PointingHand`] — the variant GPUI's own
    /// `Styled::cursor_pointer()` sets, which keeps stock rendering identical.
    /// A theme that wants the platform arrow everywhere sets
    /// [`gpui::CursorStyle::Arrow`] once here instead of restyling components.
    pub cursor_interactive: gpui::CursorStyle,

    /// The opacity a hovered `Tabs` item drops to.
    ///
    /// v3 hardcodes `opacity: 0.7` on an unselected `.tabs__tab:hover`; this
    /// port names it so a theme can soften or disable the dim. Not a v3 CSS
    /// variable, and not consumed by `Link`: its root hover draws an underline.
    pub tabs_hover_opacity: f32,

    /// The warm window after the pointer leaves a tooltip during which the
    /// next tip opens without its delay.
    ///
    /// The cooldown starts when the tooltip is dismissed (hover exit) and
    /// lasts `max(this, close_delay)`, so a per-tooltip close delay extends
    /// the window. React Aria uses the same 500 ms.
    pub tooltip_cooldown_ms: u64,

    /// How long a `DropdownTrigger::LongPress` waits before it opens.
    ///
    /// React Aria uses 500 ms.
    pub long_press_ms: u64,

    /// The background fade duration `anim::hover_fade` eases between two
    /// colors. The default is the button's own `100ms` (`anim::TRANSITION_MS`);
    /// zero resolves immediately, like reduced motion.
    pub hover_fade_ms: u64,
}

impl Default for LayoutTheme {
    fn default() -> Self {
        Self::light()
    }
}

impl LayoutTheme {
    /// The light-mode layout tokens, including the three-layer surface, overlay and field shadows.
    pub fn light() -> Self {
        Self {
            // `0 2px 4px 0 rgba(0,0,0,.04), 0 1px 2px 0 rgba(0,0,0,.06),
            //  0 0 1px 0 rgba(0,0,0,.06)`
            surface_shadow: vec![
                shadow(0., 2., 4., 0.04),
                shadow(0., 1., 2., 0.06),
                shadow(0., 0., 1., 0.06),
            ],
            // `0 2px 8px 0 rgba(0,0,0,.06), 0 -6px 12px 0 rgba(0,0,0,.03),
            //  0 14px 28px 0 rgba(0,0,0,.08)` -- three, and the middle one
            // throws its blur *upward*, which is what keeps a panel from
            // looking pasted onto the page.
            overlay_shadow: vec![
                shadow(0., 2., 8., 0.06),
                shadow(0., -6., 12., 0.03),
                shadow(0., 14., 28., 0.08),
            ],
            field_shadow: vec![
                shadow(0., 2., 4., 0.04),
                shadow(0., 1., 2., 0.06),
                shadow(0., 0., 1., 0.06),
            ],
            ..Self::common()
        }
    }

    /// The dark-mode layout tokens; v3 drops the surface, overlay and field drop shadows in dark mode.
    pub fn dark() -> Self {
        // Dark mode drops all three shadows in v3.
        Self {
            surface_shadow: Vec::new(),
            overlay_shadow: Vec::new(),
            field_shadow: Vec::new(),
            // `--overlay-shadow: 0 0 1px 0 rgba(255,255,255,.3) inset` is the
            // only shadow dark mode keeps, and it is what separates a panel from
            // the page now that both are the same colour.
            overlay_hairline: Some(gpui::hsla(0., 0., 1., 0.3)),
            ..Self::common()
        }
    }

    fn common() -> Self {
        let radius = px(8.0);
        Self {
            spacing: px(4.0),
            radius,
            field_radius: radius * 1.5,
            border_width: px(1.0),
            field_border_width: px(0.0),
            disabled_opacity: 0.5,
            ring_offset_width: px(2.0),
            surface_shadow: Vec::new(),
            overlay_shadow: Vec::new(),
            field_shadow: Vec::new(),
            skeleton_animation: SkeletonAnimation::Shimmer,
            tooltip_delay_ms: 1500,
            tooltip_close_delay_ms: 500,
            overlay_hairline: None,
            cursor_interactive: gpui::CursorStyle::PointingHand,
            tabs_hover_opacity: 0.7,
            tooltip_cooldown_ms: 500,
            long_press_ms: 500,
            hover_fade_ms: 100,
        }
    }

    /// `--radius-xs: calc(var(--radius) * 0.25)`
    pub fn radius_xs(&self) -> Pixels {
        self.radius * 0.25
    }
    /// `--radius-sm: calc(var(--radius) * 0.5)`
    pub fn radius_sm(&self) -> Pixels {
        self.radius * 0.5
    }
    /// `--radius-md: calc(var(--radius) * 0.75)`
    pub fn radius_md(&self) -> Pixels {
        self.radius * 0.75
    }
    /// `--radius-lg: calc(var(--radius) * 1)`
    pub fn radius_lg(&self) -> Pixels {
        self.radius
    }
    /// `--radius-xl: calc(var(--radius) * 1.5)`
    pub fn radius_xl(&self) -> Pixels {
        self.radius * 1.5
    }
    /// `--radius-2xl: calc(var(--radius) * 2)`
    pub fn radius_2xl(&self) -> Pixels {
        self.radius * 2.0
    }
    /// `--radius-3xl: calc(var(--radius) * 3)`
    pub fn radius_3xl(&self) -> Pixels {
        self.radius * 3.0
    }
    /// `--radius-4xl: calc(var(--radius) * 4)`
    pub fn radius_4xl(&self) -> Pixels {
        self.radius * 4.0
    }

    /// A radius capped the way v3 caps its own: `min(32px, ..)`.
    ///
    /// v3 wraps every `rounded-*` and `rounded-full` in `min()` so a theme with
    /// an oversized `--radius` cannot distort a component — the corner stops
    /// growing before it swallows the box.
    pub fn capped(&self, radius: Pixels) -> Pixels {
        radius.min(px(32.0))
    }
}

fn shadow(x: f32, y: f32, blur: f32, alpha: f32) -> BoxShadow {
    BoxShadow {
        inset: false,
        color: gpui::hsla(0.0, 0.0, 0.0, alpha),
        offset: point(px(x), px(y)),
        blur_radius: px(blur),
        spread_radius: px(0.),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use gpui::{div, Styled};

    /// The default must be *the same cursor GPUI's own `cursor_pointer()` sets*,
    /// not merely a hand-shaped variant: every component now reads this token
    /// instead of calling that method, so any divergence silently changes stock
    /// rendering. Comparing against the method's own output keeps the invariant
    /// true even if GPUI renames or repoints the variant.
    #[test]
    fn the_default_interactive_cursor_is_gpuis_own_pointer() {
        let mut probe = div().cursor_pointer();
        assert_eq!(
            Some(LayoutTheme::light().cursor_interactive),
            probe.style().mouse_cursor,
        );
        assert_eq!(
            LayoutTheme::dark().cursor_interactive,
            LayoutTheme::light().cursor_interactive,
            "light and dark share the token; only a custom theme changes it"
        );
    }

    /// Every new token starts on the literal it replaced, so a consumer that
    /// does not set one renders the stock pixels.
    #[test]
    fn customisation_tokens_default_to_the_literals_they_replace() {
        for layout in [LayoutTheme::light(), LayoutTheme::dark()] {
            assert!((layout.tabs_hover_opacity - 0.7).abs() < f32::EPSILON);
            assert_eq!(layout.tooltip_cooldown_ms, 500);
            assert_eq!(layout.long_press_ms, 500);
            assert_eq!(layout.hover_fade_ms, 100);
        }
    }
}