Skip to main content

leptos_css/
value.rs

1use std::fmt;
2
3use crate::checked_value::impl_checked_value;
4use crate::{
5    CssAngle, CssColor, CssLength, CssTime, FiniteF64, GlobalKeyword, InvalidCssNumber,
6    NonNegativeFiniteF64,
7    number::{assert_finite, try_finite},
8    serialization::CssWriteTo,
9};
10
11/// A closed union of typed CSS component values.
12///
13/// This type is useful for storing heterogeneous primitives. It is not a declaration grammar:
14/// property-specific APIs accept narrower types and are the only values that integrate directly
15/// with Leptos style attributes.
16///
17/// # Ergonomics
18///
19/// Use the free convenience functions for common values:
20/// ```rust
21/// use leptos_css::{px, em, rem, pct, deg};
22///
23/// let width = px(100);
24/// let margin = em(0.6);
25/// let offset = pct(50);
26/// let rotation = deg(45);
27/// ```
28///
29/// Arbitrary strings and unchecked function bodies are intentionally absent. Unsupported CSS
30/// must be written outside this typed API until its grammar is modeled.
31#[derive(Clone, Debug, PartialEq)]
32#[non_exhaustive]
33pub enum CssValue {
34    /// A bare floating-point number (e.g., opacity, flex-grow).
35    Number(FiniteF64),
36    /// A bare integer (e.g., z-index, order).
37    Integer(i32),
38    /// A CSS length value (px, em, rem, vh, vw, etc.).
39    Length(CssLength),
40    /// A percentage value.
41    Percent(FiniteF64),
42    /// A CSS angle value (deg, rad, turn, grad).
43    Angle(CssAngle),
44    /// A CSS time value (s, ms).
45    Time(CssTime),
46    /// A CSS color value (rgb, rgba, hsl, hsla, named).
47    Color(CssColor),
48    /// Fractional units for CSS Grid (e.g., `1fr`).
49    Fr(NonNegativeFiniteF64),
50    /// The CSS `auto` keyword.
51    Auto,
52    /// Zero with unit for `calc()` compatibility. Renders as `"0px"`.
53    Zero,
54    /// The CSS `inherit` keyword.
55    Inherit,
56    /// The CSS `initial` keyword.
57    Initial,
58    /// The CSS `unset` keyword.
59    Unset,
60    /// The CSS `revert` keyword.
61    Revert,
62    /// The CSS `revert-layer` keyword.
63    RevertLayer,
64}
65
66impl CssWriteTo for CssValue {
67    fn css_fmt<W: fmt::Write>(&self, w: &mut W) -> fmt::Result {
68        match self {
69            Self::Number(v) => write!(w, "{v}"),
70            Self::Integer(v) => write!(w, "{v}"),
71            Self::Length(l) => l.css_fmt(w),
72            Self::Percent(v) => write!(w, "{v}%"),
73            Self::Angle(a) => a.css_fmt(w),
74            Self::Time(t) => t.css_fmt(w),
75            Self::Color(c) => c.css_fmt(w),
76            Self::Fr(v) => write!(w, "{v}fr"),
77            Self::Auto => w.write_str("auto"),
78            Self::Zero => w.write_str("0px"),
79            Self::Inherit => w.write_str("inherit"),
80            Self::Initial => w.write_str("initial"),
81            Self::Unset => w.write_str("unset"),
82            Self::Revert => w.write_str("revert"),
83            Self::RevertLayer => w.write_str("revert-layer"),
84        }
85    }
86}
87
88// --- From impls for CssValue ---
89
90impl From<CssLength> for CssValue {
91    fn from(l: CssLength) -> Self {
92        Self::Length(l)
93    }
94}
95
96impl From<CssAngle> for CssValue {
97    fn from(a: CssAngle) -> Self {
98        Self::Angle(a)
99    }
100}
101
102impl From<CssTime> for CssValue {
103    fn from(t: CssTime) -> Self {
104        Self::Time(t)
105    }
106}
107
108impl From<CssColor> for CssValue {
109    fn from(c: CssColor) -> Self {
110        Self::Color(c)
111    }
112}
113
114impl From<i32> for CssValue {
115    fn from(v: i32) -> Self {
116        Self::Integer(v)
117    }
118}
119
120impl From<FiniteF64> for CssValue {
121    fn from(v: FiniteF64) -> Self {
122        Self::Number(v)
123    }
124}
125
126impl From<GlobalKeyword> for CssValue {
127    fn from(keyword: GlobalKeyword) -> Self {
128        match keyword {
129            GlobalKeyword::Inherit => Self::Inherit,
130            GlobalKeyword::Initial => Self::Initial,
131            GlobalKeyword::Unset => Self::Unset,
132            GlobalKeyword::Revert => Self::Revert,
133            GlobalKeyword::RevertLayer => Self::RevertLayer,
134        }
135    }
136}
137
138impl TryFrom<f64> for CssValue {
139    type Error = InvalidCssNumber;
140
141    fn try_from(v: f64) -> Result<Self, Self::Error> {
142        FiniteF64::try_new(v).map(Self::Number)
143    }
144}
145
146impl From<CssValue> for String {
147    fn from(value: CssValue) -> Self {
148        let mut s = Self::new();
149        value.write_to(&mut s);
150        s
151    }
152}
153
154impl From<CssValue> for std::borrow::Cow<'static, str> {
155    fn from(value: CssValue) -> Self {
156        Self::Owned(String::from(value))
157    }
158}
159
160/// Create a bare CSS number.
161///
162/// # Panics
163///
164/// Panics if `v` is `NaN` or infinite. Use [`try_number`] for runtime-derived values.
165#[track_caller]
166pub fn number(v: impl Into<f64>) -> CssValue {
167    CssValue::Number(assert_finite(v.into(), "number"))
168}
169
170/// Attempt to create a finite bare CSS number.
171///
172/// # Errors
173///
174/// Returns [`InvalidCssNumber::NonFinite`] if `v` is `NaN` or infinite.
175pub fn try_number(v: impl Into<f64>) -> Result<CssValue, InvalidCssNumber> {
176    try_finite(v.into(), "number").map(CssValue::Number)
177}
178
179/// Create a CSS degree angle value.
180///
181/// # Panics
182///
183/// Panics if `v` is `NaN` or infinite.
184pub fn deg(v: impl Into<f64>) -> CssValue {
185    CssValue::Angle(CssAngle::Deg(assert_finite(v.into(), "deg")))
186}
187
188/// Attempt to create a finite CSS degree angle.
189///
190/// # Errors
191///
192/// Returns [`InvalidCssNumber::NonFinite`] if `v` is `NaN` or infinite.
193pub fn try_deg(v: impl Into<f64>) -> Result<CssValue, InvalidCssNumber> {
194    try_finite(v.into(), "deg").map(|v| CssValue::Angle(CssAngle::Deg(v)))
195}
196
197/// Create a CSS radian angle value.
198///
199/// # Panics
200///
201/// Panics if `v` is `NaN` or infinite.
202pub fn rad(v: impl Into<f64>) -> CssValue {
203    CssValue::Angle(CssAngle::Rad(assert_finite(v.into(), "rad")))
204}
205
206/// Attempt to create a finite CSS radian angle.
207///
208/// # Errors
209///
210/// Returns [`InvalidCssNumber::NonFinite`] if `v` is `NaN` or infinite.
211pub fn try_rad(v: impl Into<f64>) -> Result<CssValue, InvalidCssNumber> {
212    try_finite(v.into(), "rad").map(|v| CssValue::Angle(CssAngle::Rad(v)))
213}
214
215/// Create a CSS turn angle value.
216///
217/// # Panics
218///
219/// Panics if `v` is `NaN` or infinite.
220pub fn turn(v: impl Into<f64>) -> CssValue {
221    CssValue::Angle(CssAngle::Turn(assert_finite(v.into(), "turn")))
222}
223
224/// Attempt to create a finite CSS turn angle.
225///
226/// # Errors
227///
228/// Returns [`InvalidCssNumber::NonFinite`] if `v` is `NaN` or infinite.
229pub fn try_turn(v: impl Into<f64>) -> Result<CssValue, InvalidCssNumber> {
230    try_finite(v.into(), "turn").map(|v| CssValue::Angle(CssAngle::Turn(v)))
231}
232
233/// Create a CSS gradian angle value.
234///
235/// # Panics
236///
237/// Panics if `v` is `NaN` or infinite.
238pub fn grad(v: impl Into<f64>) -> CssValue {
239    CssValue::Angle(CssAngle::Grad(assert_finite(v.into(), "grad")))
240}
241
242/// Attempt to create a finite CSS gradian angle.
243///
244/// # Errors
245///
246/// Returns [`InvalidCssNumber::NonFinite`] if `v` is `NaN` or infinite.
247pub fn try_grad(v: impl Into<f64>) -> Result<CssValue, InvalidCssNumber> {
248    try_finite(v.into(), "grad").map(|v| CssValue::Angle(CssAngle::Grad(v)))
249}
250
251/// Create a CSS seconds time value.
252///
253/// # Panics
254///
255/// Panics if `v` is `NaN` or infinite.
256pub fn s(v: impl Into<f64>) -> CssValue {
257    CssValue::Time(CssTime::S(assert_finite(v.into(), "s")))
258}
259
260/// Attempt to create a finite CSS seconds value.
261///
262/// # Errors
263///
264/// Returns [`InvalidCssNumber::NonFinite`] if `v` is `NaN` or infinite.
265pub fn try_s(v: impl Into<f64>) -> Result<CssValue, InvalidCssNumber> {
266    try_finite(v.into(), "s").map(|v| CssValue::Time(CssTime::S(v)))
267}
268
269/// Create a CSS milliseconds time value.
270///
271/// # Panics
272///
273/// Panics if `v` is `NaN` or infinite.
274pub fn ms(v: impl Into<f64>) -> CssValue {
275    CssValue::Time(CssTime::Ms(assert_finite(v.into(), "ms")))
276}
277
278/// Attempt to create a finite CSS milliseconds value.
279///
280/// # Errors
281///
282/// Returns [`InvalidCssNumber::NonFinite`] if `v` is `NaN` or infinite.
283pub fn try_ms(v: impl Into<f64>) -> Result<CssValue, InvalidCssNumber> {
284    try_finite(v.into(), "ms").map(|v| CssValue::Time(CssTime::Ms(v)))
285}
286
287/// Create a CSS fractional unit value (for CSS Grid).
288///
289/// # Panics
290///
291/// Panics if `v` is `NaN`, infinite, or negative.
292pub fn fr(v: impl Into<f64>) -> CssValue {
293    CssValue::Fr(NonNegativeFiniteF64::new(v.into()))
294}
295
296/// Attempt to create a finite, non-negative CSS fractional unit value.
297///
298/// # Errors
299///
300/// Returns an error if `v` is `NaN`, infinite, or negative.
301pub fn try_fr(v: impl Into<f64>) -> Result<CssValue, InvalidCssNumber> {
302    NonNegativeFiniteF64::try_new(v.into()).map(CssValue::Fr)
303}
304
305impl_checked_value!(CssValue);