Skip to main content

day_geometry/
lib.rs

1// Copyright © The Daybrite Project
2// SPDX-License-Identifier: MPL-2.0
3
4//! day-geometry: plain `Copy` value types shared by layout, canvas, and the toolkit spec.
5//! Everything is in points (density-independent); backends convert to device pixels (§7.9).
6
7#[derive(Clone, Copy, Debug, Default, PartialEq)]
8pub struct Point {
9    pub x: f64,
10    pub y: f64,
11}
12
13impl Point {
14    pub const ZERO: Point = Point { x: 0.0, y: 0.0 };
15    #[inline]
16    pub const fn new(x: f64, y: f64) -> Self {
17        Point { x, y }
18    }
19    #[inline]
20    #[must_use]
21    pub fn offset(self, dx: f64, dy: f64) -> Self {
22        Point::new(self.x + dx, self.y + dy)
23    }
24}
25
26#[derive(Clone, Copy, Debug, Default, PartialEq)]
27pub struct Size {
28    pub width: f64,
29    pub height: f64,
30}
31
32impl Size {
33    pub const ZERO: Size = Size {
34        width: 0.0,
35        height: 0.0,
36    };
37    #[inline]
38    pub const fn new(width: f64, height: f64) -> Self {
39        Size { width, height }
40    }
41    #[inline]
42    #[must_use]
43    pub fn max(self, other: Size) -> Size {
44        Size::new(self.width.max(other.width), self.height.max(other.height))
45    }
46    /// Approximate equality on the half-pixel epsilon used by frame diffing (§7.9).
47    #[inline]
48    #[must_use]
49    pub fn approx_eq(self, other: Size, eps: f64) -> bool {
50        (self.width - other.width).abs() <= eps && (self.height - other.height).abs() <= eps
51    }
52}
53
54#[derive(Clone, Copy, Debug, Default, PartialEq)]
55pub struct Rect {
56    pub origin: Point,
57    pub size: Size,
58}
59
60impl Rect {
61    pub const ZERO: Rect = Rect {
62        origin: Point::ZERO,
63        size: Size::ZERO,
64    };
65    #[inline]
66    pub const fn new(x: f64, y: f64, width: f64, height: f64) -> Self {
67        Rect {
68            origin: Point::new(x, y),
69            size: Size::new(width, height),
70        }
71    }
72    #[inline]
73    pub fn from_size(size: Size) -> Self {
74        Rect {
75            origin: Point::ZERO,
76            size,
77        }
78    }
79    #[inline]
80    #[must_use]
81    pub fn min_x(&self) -> f64 {
82        self.origin.x
83    }
84    #[inline]
85    #[must_use]
86    pub fn min_y(&self) -> f64 {
87        self.origin.y
88    }
89    #[inline]
90    #[must_use]
91    pub fn max_x(&self) -> f64 {
92        self.origin.x + self.size.width
93    }
94    #[inline]
95    #[must_use]
96    pub fn max_y(&self) -> f64 {
97        self.origin.y + self.size.height
98    }
99    #[inline]
100    pub fn center(&self) -> Point {
101        Point::new(
102            self.origin.x + self.size.width / 2.0,
103            self.origin.y + self.size.height / 2.0,
104        )
105    }
106    #[inline]
107    #[must_use]
108    pub fn inset(&self, d: f64) -> Rect {
109        self.inset_by(Insets::all(d))
110    }
111    #[must_use]
112    pub fn inset_by(&self, i: Insets) -> Rect {
113        Rect::new(
114            self.origin.x + i.leading,
115            self.origin.y + i.top,
116            (self.size.width - i.leading - i.trailing).max(0.0),
117            (self.size.height - i.top - i.bottom).max(0.0),
118        )
119    }
120    #[must_use]
121    pub fn intersects(&self, other: &Rect) -> bool {
122        self.min_x() < other.max_x()
123            && other.min_x() < self.max_x()
124            && self.min_y() < other.max_y()
125            && other.min_y() < self.max_y()
126    }
127    /// Approximate equality on the half-pixel epsilon used by frame diffing (§7.9).
128    #[must_use]
129    pub fn approx_eq(&self, other: &Rect, eps: f64) -> bool {
130        (self.origin.x - other.origin.x).abs() <= eps
131            && (self.origin.y - other.origin.y).abs() <= eps
132            && self.size.approx_eq(other.size, eps)
133    }
134}
135
136/// A 2-D affine transform (CoreGraphics row-vector convention): a point `p` maps to
137/// `(a·p.x + c·p.y + tx, b·p.x + d·p.y + ty)`. Used by canvas transform ops for shape
138/// rotate/scale/offset; every native 2-D context concatenates it onto its CTM identically.
139#[derive(Clone, Copy, Debug, PartialEq)]
140pub struct Affine {
141    pub a: f64,
142    pub b: f64,
143    pub c: f64,
144    pub d: f64,
145    pub tx: f64,
146    pub ty: f64,
147}
148
149impl Affine {
150    pub const IDENTITY: Affine = Affine {
151        a: 1.0,
152        b: 0.0,
153        c: 0.0,
154        d: 1.0,
155        tx: 0.0,
156        ty: 0.0,
157    };
158
159    #[inline]
160    pub const fn translate(x: f64, y: f64) -> Affine {
161        Affine {
162            a: 1.0,
163            b: 0.0,
164            c: 0.0,
165            d: 1.0,
166            tx: x,
167            ty: y,
168        }
169    }
170    #[inline]
171    pub const fn scale(sx: f64, sy: f64) -> Affine {
172        Affine {
173            a: sx,
174            b: 0.0,
175            c: 0.0,
176            d: sy,
177            tx: 0.0,
178            ty: 0.0,
179        }
180    }
181    /// Rotation by `angle` (counter-clockwise in a y-up space; clockwise on y-down screens).
182    #[inline]
183    pub fn rotate(angle: Angle) -> Affine {
184        let (s, cos) = angle.radians().sin_cos();
185        Affine {
186            a: cos,
187            b: s,
188            c: -s,
189            d: cos,
190            tx: 0.0,
191            ty: 0.0,
192        }
193    }
194    /// `self` applied first, then `other` (row-vector product `self · other`).
195    #[inline]
196    #[must_use]
197    pub fn then(self, o: Affine) -> Affine {
198        Affine {
199            a: self.a * o.a + self.b * o.c,
200            b: self.a * o.b + self.b * o.d,
201            c: self.c * o.a + self.d * o.c,
202            d: self.c * o.b + self.d * o.d,
203            tx: self.tx * o.a + self.ty * o.c + o.tx,
204            ty: self.tx * o.b + self.ty * o.d + o.ty,
205        }
206    }
207    #[inline]
208    pub fn apply(&self, p: Point) -> Point {
209        Point::new(
210            self.a * p.x + self.c * p.y + self.tx,
211            self.b * p.x + self.d * p.y + self.ty,
212        )
213    }
214    /// Map a point back through the inverse (for hit-testing a transformed shape). None if singular.
215    #[must_use]
216    pub fn invert_apply(&self, p: Point) -> Option<Point> {
217        let det = self.a * self.d - self.b * self.c;
218        if det.abs() < 1e-12 {
219            return None;
220        }
221        let inv = 1.0 / det;
222        let x = p.x - self.tx;
223        let y = p.y - self.ty;
224        Some(Point::new(
225            (x * self.d - y * self.c) * inv,
226            (y * self.a - x * self.b) * inv,
227        ))
228    }
229    #[inline]
230    #[must_use]
231    pub fn is_identity(&self) -> bool {
232        *self == Affine::IDENTITY
233    }
234    #[inline]
235    #[must_use]
236    pub fn as_array(&self) -> [f64; 6] {
237        [self.a, self.b, self.c, self.d, self.tx, self.ty]
238    }
239    #[inline]
240    pub fn from_array(m: [f64; 6]) -> Affine {
241        Affine {
242            a: m[0],
243            b: m[1],
244            c: m[2],
245            d: m[3],
246            tx: m[4],
247            ty: m[5],
248        }
249    }
250}
251
252/// Logical insets: `leading`/`trailing` resolve against the layout direction at place time (§7.8).
253#[derive(Clone, Copy, Debug, Default, PartialEq)]
254pub struct Insets {
255    pub top: f64,
256    pub leading: f64,
257    pub bottom: f64,
258    pub trailing: f64,
259}
260
261impl Insets {
262    pub const ZERO: Insets = Insets {
263        top: 0.0,
264        leading: 0.0,
265        bottom: 0.0,
266        trailing: 0.0,
267    };
268    /// Four explicit edges, in the order they are named.
269    #[inline]
270    #[must_use]
271    pub const fn new(top: f64, leading: f64, bottom: f64, trailing: f64) -> Self {
272        Insets {
273            top,
274            leading,
275            bottom,
276            trailing,
277        }
278    }
279    #[inline]
280    #[must_use]
281    pub const fn all(d: f64) -> Self {
282        Insets {
283            top: d,
284            leading: d,
285            bottom: d,
286            trailing: d,
287        }
288    }
289    #[inline]
290    #[must_use]
291    pub const fn symmetric(horizontal: f64, vertical: f64) -> Self {
292        Insets {
293            top: vertical,
294            leading: horizontal,
295            bottom: vertical,
296            trailing: horizontal,
297        }
298    }
299    /// `d` on the leading and trailing edges, nothing above or below.
300    #[inline]
301    #[must_use]
302    pub const fn horizontal(d: f64) -> Self {
303        Insets::symmetric(d, 0.0)
304    }
305    /// `d` above and below, nothing on the sides.
306    #[inline]
307    #[must_use]
308    pub const fn vertical(d: f64) -> Self {
309        Insets::symmetric(0.0, d)
310    }
311    /// `d` above, nothing elsewhere.
312    #[inline]
313    #[must_use]
314    pub const fn top(d: f64) -> Self {
315        Insets {
316            top: d,
317            ..Insets::ZERO
318        }
319    }
320    /// `d` below, nothing elsewhere.
321    #[inline]
322    #[must_use]
323    pub const fn bottom(d: f64) -> Self {
324        Insets {
325            bottom: d,
326            ..Insets::ZERO
327        }
328    }
329    /// `d` on the leading edge, nothing elsewhere.
330    #[inline]
331    #[must_use]
332    pub const fn leading(d: f64) -> Self {
333        Insets {
334            leading: d,
335            ..Insets::ZERO
336        }
337    }
338    /// `d` on the trailing edge, nothing elsewhere.
339    #[inline]
340    #[must_use]
341    pub const fn trailing(d: f64) -> Self {
342        Insets {
343            trailing: d,
344            ..Insets::ZERO
345        }
346    }
347    /// The width the insets take: leading plus trailing.
348    #[inline]
349    #[must_use]
350    pub fn horizontal_total(&self) -> f64 {
351        self.leading + self.trailing
352    }
353    /// The height the insets take: top plus bottom.
354    #[inline]
355    #[must_use]
356    pub fn vertical_total(&self) -> f64 {
357        self.top + self.bottom
358    }
359}
360
361/// The same inset on all four sides: what a bare number means wherever insets are taken
362/// (`.padding(8.0)`).
363impl From<f64> for Insets {
364    fn from(d: f64) -> Self {
365        Insets::all(d)
366    }
367}
368
369/// sRGB color, 0.0–1.0 components. Semantic theme tokens (§6.3) resolve to these in the backend.
370#[derive(Clone, Copy, Debug, PartialEq)]
371pub struct Color {
372    pub r: f64,
373    pub g: f64,
374    pub b: f64,
375    pub a: f64,
376}
377
378impl Color {
379    pub const fn rgba(r: f64, g: f64, b: f64, a: f64) -> Self {
380        Color { r, g, b, a }
381    }
382    pub const fn rgb(r: f64, g: f64, b: f64) -> Self {
383        Color::rgba(r, g, b, 1.0)
384    }
385    pub const BLACK: Color = Color::rgb(0.0, 0.0, 0.0);
386    pub const WHITE: Color = Color::rgb(1.0, 1.0, 1.0);
387    pub const CLEAR: Color = Color::rgba(0.0, 0.0, 0.0, 0.0);
388    /// 0xRRGGBB
389    pub const fn hex(v: u32) -> Self {
390        Color::rgb(
391            ((v >> 16) & 0xff) as f64 / 255.0,
392            ((v >> 8) & 0xff) as f64 / 255.0,
393            (v & 0xff) as f64 / 255.0,
394        )
395    }
396
397    /// From HSL: `h` in degrees (wraps mod 360), `s`/`l` in `0.0..=1.0`. `Color` is the one color
398    /// type every parameter accepts, so this makes HSL usable everywhere a color is.
399    pub fn hsl(h: f64, s: f64, l: f64) -> Self {
400        Color::hsla(h, s, l, 1.0)
401    }
402    pub fn hsla(h: f64, s: f64, l: f64, a: f64) -> Self {
403        let (s, l) = (s.clamp(0.0, 1.0), l.clamp(0.0, 1.0));
404        if s == 0.0 {
405            return Color::rgba(l, l, l, a);
406        }
407        let hk = h.rem_euclid(360.0) / 360.0;
408        let q = if l < 0.5 {
409            l * (1.0 + s)
410        } else {
411            l + s - l * s
412        };
413        let p = 2.0 * l - q;
414        Color::rgba(
415            hue2rgb(p, q, hk + 1.0 / 3.0),
416            hue2rgb(p, q, hk),
417            hue2rgb(p, q, hk - 1.0 / 3.0),
418            a,
419        )
420    }
421
422    /// From HSV/HSB: `h` degrees (wraps), `s`/`v` in `0.0..=1.0`.
423    pub fn hsv(h: f64, s: f64, v: f64) -> Self {
424        Color::hsva(h, s, v, 1.0)
425    }
426    pub fn hsva(h: f64, s: f64, v: f64, a: f64) -> Self {
427        let (s, v) = (s.clamp(0.0, 1.0), v.clamp(0.0, 1.0));
428        let hh = h.rem_euclid(360.0) / 60.0;
429        let c = v * s;
430        let x = c * (1.0 - (hh % 2.0 - 1.0).abs());
431        let m = v - c;
432        let (r, g, b) = match hh as i32 {
433            0 => (c, x, 0.0),
434            1 => (x, c, 0.0),
435            2 => (0.0, c, x),
436            3 => (0.0, x, c),
437            4 => (x, 0.0, c),
438            _ => (c, 0.0, x),
439        };
440        Color::rgba(r + m, g + m, b + m, a)
441    }
442
443    /// Decompose to `(hue°, saturation, lightness)` (HSL). Hue is `0.0` for grays.
444    #[must_use]
445    #[expect(
446        clippy::float_cmp,
447        reason = "`max` is a copy of one of the three channels, so equality is exact"
448    )]
449    pub fn to_hsl(&self) -> (f64, f64, f64) {
450        let (r, g, b) = (self.r, self.g, self.b);
451        let max = r.max(g).max(b);
452        let min = r.min(g).min(b);
453        let l = f64::midpoint(max, min);
454        let d = max - min;
455        if d.abs() < 1e-9 {
456            return (0.0, 0.0, l);
457        }
458        let s = d / (1.0 - (2.0 * l - 1.0).abs());
459        let h = if max == r {
460            60.0 * (((g - b) / d).rem_euclid(6.0))
461        } else if max == g {
462            60.0 * ((b - r) / d + 2.0)
463        } else {
464            60.0 * ((r - g) / d + 4.0)
465        };
466        (h.rem_euclid(360.0), s.clamp(0.0, 1.0), l)
467    }
468
469    /// Decompose to `(hue°, saturation, value)` (HSV/HSB), the model every native color picker's
470    /// spectrum tab is built on, so this is what a renderer seeds its sliders from. Hue is `0.0`
471    /// for grays. Inverse of [`Color::hsv`].
472    #[must_use]
473    #[expect(
474        clippy::float_cmp,
475        reason = "`max` is a copy of one of the three channels, so equality is exact"
476    )]
477    pub fn to_hsv(&self) -> (f64, f64, f64) {
478        let (r, g, b) = (self.r, self.g, self.b);
479        let max = r.max(g).max(b);
480        let min = r.min(g).min(b);
481        let d = max - min;
482        if d.abs() < 1e-9 {
483            return (0.0, 0.0, max);
484        }
485        let h = if max == r {
486            60.0 * (((g - b) / d).rem_euclid(6.0))
487        } else if max == g {
488            60.0 * ((b - r) / d + 2.0)
489        } else {
490            60.0 * ((r - g) / d + 4.0)
491        };
492        (h.rem_euclid(360.0), d / max, max)
493    }
494
495    /// The same color at a different opacity: what a picker's alpha slider produces, and what
496    /// tinting a surface down to a wash needs (`palette.with_alpha(0.14)`).
497    #[must_use]
498    pub fn with_alpha(self, a: f64) -> Color {
499        Color { a, ..self }
500    }
501
502    /// `#rrggbb`, or `#rrggbbaa` when the color is not fully opaque. The 8-bit form every
503    /// platform's own color field speaks, and what [`Color::parse`] round-trips.
504    #[must_use]
505    pub fn to_hex_string(&self) -> String {
506        let q = |v: f64| (v.clamp(0.0, 1.0) * 255.0).round() as u8;
507        if self.a >= 1.0 {
508            format!("#{:02x}{:02x}{:02x}", q(self.r), q(self.g), q(self.b))
509        } else {
510            format!(
511                "#{:02x}{:02x}{:02x}{:02x}",
512                q(self.r),
513                q(self.g),
514                q(self.b),
515                q(self.a)
516            )
517        }
518    }
519
520    /// Parse a color from either interchange form:
521    ///
522    /// - **hex**: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` (the leading `#` optional). What a
523    ///   person types, and what an 8-bit platform field (`<input type="color">`, `Windows.UI.Color`,
524    ///   `android.graphics.Color`) hands back.
525    /// - **components**: 3 or 4 space-separated floats in `0.0..=1.0`, `"r g b"` / `"r g b a"`.
526    ///   The lossless form, for the toolkits whose picker really is float-precision (`NSColor`,
527    ///   `GdkRGBA`, `QColor::getRgbF`).
528    ///
529    /// `None` on anything else. See [docs/color.md](https://daybrite.dev/docs/reference/color) for
530    /// why the currency stays sRGB for now and what a wider one would carry.
531    #[must_use]
532    pub fn parse(s: &str) -> Option<Color> {
533        let s = s.trim();
534        let hex = s.strip_prefix('#').unwrap_or(s);
535        if !hex.is_empty() && hex.bytes().all(|b| b.is_ascii_hexdigit()) {
536            let nib = |i: usize| u8::from_str_radix(&hex[i..=i], 16).ok().map(f64::from);
537            let byte = |i: usize| {
538                u8::from_str_radix(&hex[i * 2..i * 2 + 2], 16)
539                    .ok()
540                    .map(f64::from)
541            };
542            return match hex.len() {
543                3 | 4 => Some(Color::rgba(
544                    nib(0)? / 15.0,
545                    nib(1)? / 15.0,
546                    nib(2)? / 15.0,
547                    if hex.len() == 4 { nib(3)? / 15.0 } else { 1.0 },
548                )),
549                6 | 8 => Some(Color::rgba(
550                    byte(0)? / 255.0,
551                    byte(1)? / 255.0,
552                    byte(2)? / 255.0,
553                    if hex.len() == 8 {
554                        byte(3)? / 255.0
555                    } else {
556                        1.0
557                    },
558                )),
559                _ => None,
560            };
561        }
562        let mut it = s.split_whitespace();
563        let (r, g, b) = (
564            it.next()?.parse::<f64>().ok()?,
565            it.next()?.parse::<f64>().ok()?,
566            it.next()?.parse::<f64>().ok()?,
567        );
568        let a = match it.next() {
569            Some(a) => a.parse::<f64>().ok()?,
570            None => 1.0,
571        };
572        if it.next().is_some() {
573            return None;
574        }
575        Some(Color::rgba(
576            r.clamp(0.0, 1.0),
577            g.clamp(0.0, 1.0),
578            b.clamp(0.0, 1.0),
579            a.clamp(0.0, 1.0),
580        ))
581    }
582
583    /// Interpolate toward `to` in HSL space, taking the shortest hue arc (`t` in `0.0..=1.0`). A
584    /// hue-space blend (red→green sweeps through yellow) rather than the muddy RGB straight line,
585    /// used by the canvas / self-driven animation path (native widget color animation interpolates
586    /// in the toolkit's own space).
587    #[must_use]
588    pub fn lerp_hsl(self, to: Color, t: f64) -> Color {
589        let (h0, s0, l0) = self.to_hsl();
590        let (h1, s1, l1) = to.to_hsl();
591        let mut dh = (h1 - h0).rem_euclid(360.0);
592        if dh > 180.0 {
593            dh -= 360.0;
594        }
595        let lerp = |a: f64, b: f64| a + (b - a) * t;
596        Color::hsla(h0 + dh * t, lerp(s0, s1), lerp(l0, l1), lerp(self.a, to.a))
597    }
598}
599
600/// The lossless interchange form: four space-separated components, exactly what
601/// [`Color::parse`] reads back. This is what crosses a JNI / C-ABI / JS boundary when a native
602/// color picker reports a pick, so the float precision `NSColor` and `GdkRGBA` really carry is
603/// not rounded to 8 bits on the way. For the form a person reads (and types into a dayscript
604/// step) use [`Color::to_hex_string`].
605impl std::fmt::Display for Color {
606    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
607        write!(f, "{} {} {} {}", self.r, self.g, self.b, self.a)
608    }
609}
610
611/// HSL hue channel → RGB component (helper for [`Color::hsla`]).
612fn hue2rgb(p: f64, q: f64, t: f64) -> f64 {
613    let t = t.rem_euclid(1.0);
614    if t < 1.0 / 6.0 {
615        p + (q - p) * 6.0 * t
616    } else if t < 1.0 / 2.0 {
617        q
618    } else if t < 2.0 / 3.0 {
619        p + (q - p) * (2.0 / 3.0 - t) * 6.0
620    } else {
621        p
622    }
623}
624
625/// An angle: one type for every rotation, arc, sweep and gradient start in Day, so a call site
626/// says its unit (`Angle::deg(90.0)`, `Angle::rad(PI / 2.0)`) and no parameter can be read in
627/// the wrong one. Nothing converts into an `Angle` implicitly.
628///
629/// Day's angles are screen angles: `0` points along +x and positive turns clockwise, because
630/// y grows downward. The value is kept in degrees, so `Angle::deg(d).degrees()` returns `d`
631/// exactly; [`Angle::radians`] converts.
632#[derive(Clone, Copy, Debug, Default, PartialEq, PartialOrd)]
633pub struct Angle(f64);
634
635impl Angle {
636    /// No rotation.
637    pub const ZERO: Angle = Angle(0.0);
638    /// A quarter turn, 90 degrees.
639    pub const QUARTER: Angle = Angle(90.0);
640    /// A half turn, 180 degrees.
641    pub const HALF: Angle = Angle(180.0);
642    /// A full turn, 360 degrees.
643    pub const FULL: Angle = Angle(360.0);
644
645    /// An angle of `degrees` degrees.
646    #[inline]
647    #[must_use]
648    pub const fn deg(degrees: f64) -> Angle {
649        Angle(degrees)
650    }
651    /// An angle of `radians` radians.
652    #[inline]
653    #[must_use]
654    pub const fn rad(radians: f64) -> Angle {
655        Angle(radians * (180.0 / std::f64::consts::PI))
656    }
657    /// An angle of `turns` full turns: `0.25` is a quarter turn.
658    #[inline]
659    #[must_use]
660    pub const fn turns(turns: f64) -> Angle {
661        Angle(turns * 360.0)
662    }
663    /// The angle in degrees.
664    #[inline]
665    #[must_use]
666    pub const fn degrees(self) -> f64 {
667        self.0
668    }
669    /// The angle in radians.
670    #[inline]
671    #[must_use]
672    pub const fn radians(self) -> f64 {
673        self.0 * (std::f64::consts::PI / 180.0)
674    }
675    /// The same direction, normalized to `0..360` degrees.
676    #[must_use]
677    pub fn normalized(self) -> Angle {
678        Angle(self.0.rem_euclid(360.0))
679    }
680    /// Sine and cosine of the angle.
681    #[must_use]
682    pub fn sin_cos(self) -> (f64, f64) {
683        self.radians().sin_cos()
684    }
685}
686
687impl std::ops::Add for Angle {
688    type Output = Angle;
689    fn add(self, rhs: Angle) -> Angle {
690        Angle(self.0 + rhs.0)
691    }
692}
693impl std::ops::Sub for Angle {
694    type Output = Angle;
695    fn sub(self, rhs: Angle) -> Angle {
696        Angle(self.0 - rhs.0)
697    }
698}
699impl std::ops::Neg for Angle {
700    type Output = Angle;
701    fn neg(self) -> Angle {
702        Angle(-self.0)
703    }
704}
705impl std::ops::Mul<f64> for Angle {
706    type Output = Angle;
707    fn mul(self, rhs: f64) -> Angle {
708        Angle(self.0 * rhs)
709    }
710}
711impl std::ops::Div<f64> for Angle {
712    type Output = Angle;
713    fn div(self, rhs: f64) -> Angle {
714        Angle(self.0 / rhs)
715    }
716}
717impl std::ops::AddAssign for Angle {
718    fn add_assign(&mut self, rhs: Angle) {
719        self.0 += rhs.0;
720    }
721}
722impl std::ops::SubAssign for Angle {
723    fn sub_assign(&mut self, rhs: Angle) {
724        self.0 -= rhs.0;
725    }
726}
727
728/// The layout proposal: `None` = unconstrained on that axis (§7.2).
729#[derive(Clone, Copy, Debug, Default, PartialEq)]
730pub struct Proposal {
731    pub width: Option<f64>,
732    pub height: Option<f64>,
733}
734
735impl Proposal {
736    pub const UNCONSTRAINED: Proposal = Proposal {
737        width: None,
738        height: None,
739    };
740    #[inline]
741    #[must_use]
742    pub const fn new(width: Option<f64>, height: Option<f64>) -> Self {
743        Proposal { width, height }
744    }
745    #[inline]
746    #[must_use]
747    pub const fn exact(size: Size) -> Self {
748        Proposal {
749            width: Some(size.width),
750            height: Some(size.height),
751        }
752    }
753    /// Quantized key for the measurement cache (§7.4): tenth-of-a-point buckets.
754    #[must_use]
755    pub fn cache_key(&self) -> (u64, u64) {
756        #[inline]
757        fn q(v: Option<f64>) -> u64 {
758            match v {
759                None => u64::MAX,
760                Some(f) => (f * 10.0).round().max(0.0) as u64,
761            }
762        }
763        (q(self.width), q(self.height))
764    }
765}
766
767#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
768pub enum LayoutDirection {
769    #[default]
770    Ltr,
771    Rtl,
772}
773
774/// A cheap per-node visual transform (§8.4 animation): translation, uniform/non-uniform scale, and
775/// rotation about a unit anchor (`0.0..1.0` within the node's bounds; default center). Distinct
776/// from the layout frame: animating a `Transform` never triggers relayout, so it is the vehicle
777/// for movement/scaling animation. Each backend composes it onto the node's laid-out frame via its
778/// native transform channel (`CALayer/GskTransform/RenderTransform/NODE_TRANSFORM`/…).
779#[derive(Clone, Copy, Debug, PartialEq)]
780pub struct Transform {
781    pub tx: f64,
782    pub ty: f64,
783    pub sx: f64,
784    pub sy: f64,
785    /// Rotation about the anchor, positive clockwise on screen.
786    pub rotation: Angle,
787    /// Anchor for scale/rotation as a unit fraction of the node's bounds (`0.5,0.5` = center).
788    pub anchor_x: f64,
789    pub anchor_y: f64,
790}
791
792impl Default for Transform {
793    fn default() -> Self {
794        Transform::IDENTITY
795    }
796}
797
798impl Transform {
799    pub const IDENTITY: Transform = Transform {
800        tx: 0.0,
801        ty: 0.0,
802        sx: 1.0,
803        sy: 1.0,
804        rotation: Angle::ZERO,
805        anchor_x: 0.5,
806        anchor_y: 0.5,
807    };
808
809    #[inline]
810    #[must_use]
811    pub const fn translate(tx: f64, ty: f64) -> Transform {
812        Transform {
813            tx,
814            ty,
815            ..Transform::IDENTITY
816        }
817    }
818    #[inline]
819    #[must_use]
820    pub const fn scale(sx: f64, sy: f64) -> Transform {
821        Transform {
822            sx,
823            sy,
824            ..Transform::IDENTITY
825        }
826    }
827    #[inline]
828    #[must_use]
829    pub const fn rotate(angle: Angle) -> Transform {
830        Transform {
831            rotation: angle,
832            ..Transform::IDENTITY
833        }
834    }
835    /// Whether this transform has no visual effect; backends skip applying it.
836    #[inline]
837    #[must_use]
838    pub fn is_identity(&self) -> bool {
839        *self == Transform::IDENTITY
840    }
841}
842
843/// Linear interpolation of animatable values (`t` in `0.0..1.0`). This drives the **canvas /
844/// self-driven** animation path (docs/shapes.md §5) and Qt's sampled spring; native-widget
845/// animation does not use it; the toolkit interpolates on its own compositor.
846pub trait Animatable: Copy {
847    #[must_use]
848    fn lerp(self, to: Self, t: f64) -> Self;
849}
850
851#[inline]
852fn flerp(a: f64, b: f64, t: f64) -> f64 {
853    a + (b - a) * t
854}
855
856impl Animatable for f64 {
857    #[inline]
858    fn lerp(self, to: f64, t: f64) -> f64 {
859        flerp(self, to, t)
860    }
861}
862impl Animatable for Point {
863    #[inline]
864    fn lerp(self, to: Point, t: f64) -> Point {
865        Point::new(flerp(self.x, to.x, t), flerp(self.y, to.y, t))
866    }
867}
868impl Animatable for Size {
869    #[inline]
870    fn lerp(self, to: Size, t: f64) -> Size {
871        Size::new(
872            flerp(self.width, to.width, t),
873            flerp(self.height, to.height, t),
874        )
875    }
876}
877impl Animatable for Rect {
878    #[inline]
879    fn lerp(self, to: Rect, t: f64) -> Rect {
880        Rect {
881            origin: self.origin.lerp(to.origin, t),
882            size: self.size.lerp(to.size, t),
883        }
884    }
885}
886impl Animatable for Color {
887    #[inline]
888    fn lerp(self, to: Color, t: f64) -> Color {
889        Color::rgba(
890            flerp(self.r, to.r, t),
891            flerp(self.g, to.g, t),
892            flerp(self.b, to.b, t),
893            flerp(self.a, to.a, t),
894        )
895    }
896}
897impl Animatable for Angle {
898    #[inline]
899    fn lerp(self, to: Angle, t: f64) -> Angle {
900        Angle(flerp(self.0, to.0, t))
901    }
902}
903impl Animatable for Transform {
904    #[inline]
905    fn lerp(self, to: Transform, t: f64) -> Transform {
906        // Anchor snaps to the destination's (it's a coordinate frame, not a visual value).
907        Transform {
908            tx: flerp(self.tx, to.tx, t),
909            ty: flerp(self.ty, to.ty, t),
910            sx: flerp(self.sx, to.sx, t),
911            sy: flerp(self.sy, to.sy, t),
912            rotation: self.rotation.lerp(to.rotation, t),
913            anchor_x: to.anchor_x,
914            anchor_y: to.anchor_y,
915        }
916    }
917}
918
919#[cfg(test)]
920mod tests {
921    use super::*;
922
923    #[test]
924    fn rect_insets() {
925        let r = Rect::new(10.0, 10.0, 100.0, 50.0).inset_by(Insets::symmetric(4.0, 2.0));
926        assert_eq!(r, Rect::new(14.0, 12.0, 92.0, 46.0));
927    }
928
929    #[test]
930    fn hsl_primaries_and_roundtrip() {
931        let approx = |a: Color, b: Color| {
932            (a.r - b.r).abs() < 1e-6 && (a.g - b.g).abs() < 1e-6 && (a.b - b.b).abs() < 1e-6
933        };
934        assert!(approx(Color::hsl(0.0, 1.0, 0.5), Color::rgb(1.0, 0.0, 0.0))); // red
935        assert!(approx(
936            Color::hsl(120.0, 1.0, 0.5),
937            Color::rgb(0.0, 1.0, 0.0)
938        )); // green
939        assert!(approx(
940            Color::hsl(240.0, 1.0, 0.5),
941            Color::rgb(0.0, 0.0, 1.0)
942        )); // blue
943        assert!(approx(Color::hsl(0.0, 0.0, 0.5), Color::rgb(0.5, 0.5, 0.5))); // gray
944        assert!(approx(Color::hsv(0.0, 1.0, 1.0), Color::rgb(1.0, 0.0, 0.0))); // hsv red
945        // Hue wraps, and to_hsl inverts hsl.
946        let (h, s, l) = Color::hsl(370.0, 0.6, 0.4).to_hsl();
947        assert!((h - 10.0).abs() < 1e-3 && (s - 0.6).abs() < 1e-3 && (l - 0.4).abs() < 1e-3);
948        // Shortest-arc hue lerp red→(hue 300, magenta) goes the short way (down through 330), not
949        // through green; midpoint hue ≈ 330.
950        let mid = Color::hsl(0.0, 1.0, 0.5).lerp_hsl(Color::hsl(300.0, 1.0, 0.5), 0.5);
951        assert!((mid.to_hsl().0 - 330.0).abs() < 1.0);
952    }
953
954    #[test]
955    fn hsv_roundtrip_and_gray_hue() {
956        let c = Color::rgb(0.2, 0.7, 0.45);
957        let (h, s, v) = c.to_hsv();
958        let back = Color::hsv(h, s, v);
959        assert!((back.r - c.r).abs() < 1e-6 && (back.g - c.g).abs() < 1e-6);
960        assert!((back.b - c.b).abs() < 1e-6);
961        // A gray has no hue to report; saturation 0 is what the sliders need to show.
962        assert_eq!(Color::rgb(0.4, 0.4, 0.4).to_hsv(), (0.0, 0.0, 0.4));
963    }
964
965    #[test]
966    fn color_hex_and_component_parsing() {
967        // Every hex width, with and without the `#`.
968        let coral = Color::hex(0x00E8_6A3C);
969        for s in ["#e86a3c", "E86A3C", "#e86a3cff"] {
970            let p = Color::parse(s).unwrap();
971            assert!((p.r - coral.r).abs() < 1e-9, "{s}");
972            assert!(
973                (p.g - coral.g).abs() < 1e-9 && (p.b - coral.b).abs() < 1e-9,
974                "{s}"
975            );
976            assert_eq!(p.a, 1.0, "{s}");
977        }
978        assert_eq!(Color::parse("#f00").unwrap(), Color::rgb(1.0, 0.0, 0.0));
979        assert_eq!(
980            Color::parse("#0000").unwrap(),
981            Color::rgba(0.0, 0.0, 0.0, 0.0)
982        );
983        assert_eq!(Color::parse("#00000080").unwrap().a, 128.0 / 255.0);
984        // The lossless component form, what a native pick crosses a boundary as.
985        assert_eq!(Color::parse("1 0 0").unwrap(), Color::rgb(1.0, 0.0, 0.0));
986        let c = Color::rgba(0.937_254_901, 0.4, 0.298, 0.6);
987        assert_eq!(
988            Color::parse(&c.to_string()).unwrap(),
989            c,
990            "Display round-trips"
991        );
992        // 8-bit round trip through the human form.
993        assert_eq!(Color::parse(&coral.to_hex_string()).unwrap(), coral);
994        assert_eq!(
995            Color::rgba(0.0, 0.0, 0.0, 0.5).to_hex_string(),
996            "#00000080",
997            "alpha appears only when it is not opaque"
998        );
999        for bad in ["", "#12345", "not-a-color", "1 0", "1 0 0 0 0", "#gg0000"] {
1000            assert!(Color::parse(bad).is_none(), "{bad:?} rejected");
1001        }
1002    }
1003
1004    #[test]
1005    fn angle_units_round_trip() {
1006        assert_eq!(Angle::deg(90.0).degrees(), 90.0);
1007        assert!((Angle::deg(90.0).radians() - std::f64::consts::FRAC_PI_2).abs() < 1e-12);
1008        assert!((Angle::rad(std::f64::consts::PI).degrees() - 180.0).abs() < 1e-12);
1009        assert_eq!(Angle::turns(0.25), Angle::QUARTER);
1010        assert_eq!(Angle::deg(30.0) + Angle::deg(60.0), Angle::QUARTER);
1011        assert_eq!(Angle::deg(-90.0).normalized(), Angle::deg(270.0));
1012        assert_eq!(
1013            (Angle::deg(10.0) * 3.0 - Angle::deg(30.0)) / 2.0,
1014            Angle::ZERO
1015        );
1016        let p = Affine::rotate(Angle::QUARTER).apply(Point::new(1.0, 0.0));
1017        assert!(
1018            p.x.abs() < 1e-12 && (p.y - 1.0).abs() < 1e-12,
1019            "clockwise on screen"
1020        );
1021    }
1022
1023    #[test]
1024    fn proposal_cache_key_quantizes() {
1025        assert_eq!(
1026            Proposal::new(Some(100.02), None).cache_key(),
1027            Proposal::new(Some(100.04), None).cache_key()
1028        );
1029        assert_ne!(
1030            Proposal::new(Some(100.0), None).cache_key(),
1031            Proposal::UNCONSTRAINED.cache_key()
1032        );
1033    }
1034}