herogpui_theme/layout.rs
1//! Layout tokens — a faithful port of HeroUI v3's non-color custom properties
2//! from `packages/styles/themes/default/variables.css`.
3//!
4//! v3 replaced v2's size-named tokens (`radius-small`, `box-shadow-medium`)
5//! with a single `--radius` base plus calculated steps, and with
6//! component-semantic shadows (`--surface-shadow`, `--overlay-shadow`,
7//! `--field-shadow`).
8
9use gpui::{point, px, BoxShadow, Pixels};
10
11/// How a [`Skeleton`](../herogpui_components/struct.Skeleton.html) animates by
12/// default (`--skeleton-animation`).
13#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
14pub enum SkeletonAnimation {
15 #[default]
16 Shimmer,
17 Pulse,
18 None,
19}
20
21/// Spacing, radius, border and shadow tokens shared by all components.
22#[derive(Clone, Debug)]
23pub struct LayoutTheme {
24 /// `--spacing: 0.25rem`
25 pub spacing: Pixels,
26
27 /// `--radius: 0.5rem` — the base every other radius is calculated from.
28 pub radius: Pixels,
29 /// `--field-radius: calc(var(--radius) * 1.5)`
30 pub field_radius: Pixels,
31
32 /// `--border-width: 1px`
33 pub border_width: Pixels,
34 /// `--field-border-width: 0px`
35 pub field_border_width: Pixels,
36
37 /// `--disabled-opacity: 0.5`
38 pub disabled_opacity: f32,
39 /// `--ring-offset-width: 2px`
40 pub ring_offset_width: Pixels,
41
42 /// `--surface-shadow` — cards, accordions and other inline containers.
43 pub surface_shadow: Vec<BoxShadow>,
44 /// `--overlay-shadow` — tooltips, popovers, modals and menus.
45 pub overlay_shadow: Vec<BoxShadow>,
46 /// `--field-shadow` — inputs and other form controls.
47 pub field_shadow: Vec<BoxShadow>,
48
49 /// `--skeleton-animation`
50 pub skeleton_animation: SkeletonAnimation,
51 /// `--tooltip-delay: 1500ms`
52 pub tooltip_delay_ms: u64,
53 /// `--tooltip-close-delay: 500ms`
54 pub tooltip_close_delay_ms: u64,
55 /// The hairline a floating panel draws instead of a border.
56 ///
57 /// v3 gives its panels no border at all: light mode separates them with
58 /// `--overlay-shadow`, and dark mode adds `0 0 1px 0 rgba(255,255,255,.3)
59 /// **inset**` -- a one-pixel highlight just inside the edge. gpui has no
60 /// inset shadow, so the closest reproduction is a one-pixel border in that
61 /// colour, and in light mode there is none.
62 pub overlay_hairline: Option<gpui::Hsla>,
63
64 /// The cursor an interactive control shows while the pointer is over it.
65 ///
66 /// v3 gives every clickable control `cursor: pointer`, so the default is
67 /// [`gpui::CursorStyle::PointingHand`] — the variant GPUI's own
68 /// `Styled::cursor_pointer()` sets, which keeps stock rendering identical.
69 /// A theme that wants the platform arrow everywhere sets
70 /// [`gpui::CursorStyle::Arrow`] once here instead of restyling components.
71 pub cursor_interactive: gpui::CursorStyle,
72
73 /// The opacity a hovered `Tabs` item drops to.
74 ///
75 /// v3 hardcodes `opacity: 0.7` on an unselected `.tabs__tab:hover`; this
76 /// port names it so a theme can soften or disable the dim. Not a v3 CSS
77 /// variable, and not consumed by `Link`: its root hover draws an underline.
78 pub tabs_hover_opacity: f32,
79
80 /// The warm window after the pointer leaves a tooltip during which the
81 /// next tip opens without its delay.
82 ///
83 /// The cooldown starts when the tooltip is dismissed (hover exit) and
84 /// lasts `max(this, close_delay)`, so a per-tooltip close delay extends
85 /// the window. React Aria uses the same 500 ms.
86 pub tooltip_cooldown_ms: u64,
87
88 /// How long a `DropdownTrigger::LongPress` waits before it opens.
89 ///
90 /// React Aria uses 500 ms.
91 pub long_press_ms: u64,
92
93 /// The background fade duration `anim::hover_fade` eases between two
94 /// colors. The default is the button's own `100ms` (`anim::TRANSITION_MS`);
95 /// zero resolves immediately, like reduced motion.
96 pub hover_fade_ms: u64,
97}
98
99impl Default for LayoutTheme {
100 fn default() -> Self {
101 Self::light()
102 }
103}
104
105impl LayoutTheme {
106 pub fn light() -> Self {
107 Self {
108 // `0 2px 4px 0 rgba(0,0,0,.04), 0 1px 2px 0 rgba(0,0,0,.06),
109 // 0 0 1px 0 rgba(0,0,0,.06)`
110 surface_shadow: vec![
111 shadow(0., 2., 4., 0.04),
112 shadow(0., 1., 2., 0.06),
113 shadow(0., 0., 1., 0.06),
114 ],
115 // `0 2px 8px 0 rgba(0,0,0,.06), 0 -6px 12px 0 rgba(0,0,0,.03),
116 // 0 14px 28px 0 rgba(0,0,0,.08)` -- three, and the middle one
117 // throws its blur *upward*, which is what keeps a panel from
118 // looking pasted onto the page.
119 overlay_shadow: vec![
120 shadow(0., 2., 8., 0.06),
121 shadow(0., -6., 12., 0.03),
122 shadow(0., 14., 28., 0.08),
123 ],
124 field_shadow: vec![
125 shadow(0., 2., 4., 0.04),
126 shadow(0., 1., 2., 0.06),
127 shadow(0., 0., 1., 0.06),
128 ],
129 ..Self::common()
130 }
131 }
132
133 pub fn dark() -> Self {
134 // Dark mode drops all three shadows in v3.
135 Self {
136 surface_shadow: Vec::new(),
137 overlay_shadow: Vec::new(),
138 field_shadow: Vec::new(),
139 // `--overlay-shadow: 0 0 1px 0 rgba(255,255,255,.3) inset` is the
140 // only shadow dark mode keeps, and it is what separates a panel from
141 // the page now that both are the same colour.
142 overlay_hairline: Some(gpui::hsla(0., 0., 1., 0.3)),
143 ..Self::common()
144 }
145 }
146
147 fn common() -> Self {
148 let radius = px(8.0);
149 Self {
150 spacing: px(4.0),
151 radius,
152 field_radius: radius * 1.5,
153 border_width: px(1.0),
154 field_border_width: px(0.0),
155 disabled_opacity: 0.5,
156 ring_offset_width: px(2.0),
157 surface_shadow: Vec::new(),
158 overlay_shadow: Vec::new(),
159 field_shadow: Vec::new(),
160 skeleton_animation: SkeletonAnimation::Shimmer,
161 tooltip_delay_ms: 1500,
162 tooltip_close_delay_ms: 500,
163 overlay_hairline: None,
164 cursor_interactive: gpui::CursorStyle::PointingHand,
165 tabs_hover_opacity: 0.7,
166 tooltip_cooldown_ms: 500,
167 long_press_ms: 500,
168 hover_fade_ms: 100,
169 }
170 }
171
172 /// `--radius-xs: calc(var(--radius) * 0.25)`
173 pub fn radius_xs(&self) -> Pixels {
174 self.radius * 0.25
175 }
176 /// `--radius-sm: calc(var(--radius) * 0.5)`
177 pub fn radius_sm(&self) -> Pixels {
178 self.radius * 0.5
179 }
180 /// `--radius-md: calc(var(--radius) * 0.75)`
181 pub fn radius_md(&self) -> Pixels {
182 self.radius * 0.75
183 }
184 /// `--radius-lg: calc(var(--radius) * 1)`
185 pub fn radius_lg(&self) -> Pixels {
186 self.radius
187 }
188 /// `--radius-xl: calc(var(--radius) * 1.5)`
189 pub fn radius_xl(&self) -> Pixels {
190 self.radius * 1.5
191 }
192 /// `--radius-2xl: calc(var(--radius) * 2)`
193 pub fn radius_2xl(&self) -> Pixels {
194 self.radius * 2.0
195 }
196 /// `--radius-3xl: calc(var(--radius) * 3)`
197 pub fn radius_3xl(&self) -> Pixels {
198 self.radius * 3.0
199 }
200 /// `--radius-4xl: calc(var(--radius) * 4)`
201 pub fn radius_4xl(&self) -> Pixels {
202 self.radius * 4.0
203 }
204
205 /// A radius capped the way v3 caps its own: `min(32px, ..)`.
206 ///
207 /// v3 wraps every `rounded-*` and `rounded-full` in `min()` so a theme with
208 /// an oversized `--radius` cannot distort a component — the corner stops
209 /// growing before it swallows the box.
210 pub fn capped(&self, radius: Pixels) -> Pixels {
211 radius.min(px(32.0))
212 }
213}
214
215fn shadow(x: f32, y: f32, blur: f32, alpha: f32) -> BoxShadow {
216 BoxShadow {
217 inset: false,
218 color: gpui::hsla(0.0, 0.0, 0.0, alpha),
219 offset: point(px(x), px(y)),
220 blur_radius: px(blur),
221 spread_radius: px(0.),
222 }
223}
224
225#[cfg(test)]
226mod tests {
227 use super::*;
228 use gpui::{div, Styled};
229
230 /// The default must be *the same cursor GPUI's own `cursor_pointer()` sets*,
231 /// not merely a hand-shaped variant: every component now reads this token
232 /// instead of calling that method, so any divergence silently changes stock
233 /// rendering. Comparing against the method's own output keeps the invariant
234 /// true even if GPUI renames or repoints the variant.
235 #[test]
236 fn the_default_interactive_cursor_is_gpuis_own_pointer() {
237 let mut probe = div().cursor_pointer();
238 assert_eq!(
239 Some(LayoutTheme::light().cursor_interactive),
240 probe.style().mouse_cursor,
241 );
242 assert_eq!(
243 LayoutTheme::dark().cursor_interactive,
244 LayoutTheme::light().cursor_interactive,
245 "light and dark share the token; only a custom theme changes it"
246 );
247 }
248
249 /// Every new token starts on the literal it replaced, so a consumer that
250 /// does not set one renders the stock pixels.
251 #[test]
252 fn customisation_tokens_default_to_the_literals_they_replace() {
253 for layout in [LayoutTheme::light(), LayoutTheme::dark()] {
254 assert!((layout.tabs_hover_opacity - 0.7).abs() < f32::EPSILON);
255 assert_eq!(layout.tooltip_cooldown_ms, 500);
256 assert_eq!(layout.long_press_ms, 500);
257 assert_eq!(layout.hover_fade_ms, 100);
258 }
259 }
260}