iced-core-kora 0.15.0

//! Draw lines around containers.
use crate::{Color, Pixels, Size};

/// A border.
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct Border {
    /// The color of the border.
    pub color: Color,

    /// The uniform width of the border (used when `sides` is `None`).
    pub width: f32,

    /// The [`Radius`] of the border.
    pub radius: Radius,

    /// Per-side border widths \[top, right, bottom, left\].
    /// When `None` (default), all sides use `self.width`.
    /// When `Some`, each side uses its own value.
    pub sides: Option<[f32; 4]>,

    /// The dash pattern the line is drawn with. `None` (default) draws it solid.
    pub dash: Option<Dash>,
}

/// A dash pattern: `on` pixels of line, then `off` pixels of gap, repeated
/// along the border's outline.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Dash {
    /// The length of each dash.
    pub on: f32,
    /// The gap after each dash.
    pub off: f32,
}

impl Dash {
    /// What Chromium draws for a CSS `dashed` border of `width`: a line under
    /// a pixel paints as one, a thin line dashes three widths on and two off,
    /// a thick one two on and one off.
    pub fn css(width: impl Into<Pixels>) -> Self {
        let thickness = width.into().0.max(1.0);
        if thickness < 3.0 {
            Self {
                on: thickness * 3.0,
                off: thickness * 2.0,
            }
        } else {
            Self {
                on: thickness * 2.0,
                off: thickness,
            }
        }
    }

    /// The pattern's period.
    pub fn period(self) -> f32 {
        self.on + self.off
    }

    /// The pattern Chromium dashes a closed outline `length` long with: the
    /// gap stretched or squeezed so a whole number of dashes goes round it,
    /// whichever count leaves the gap nearer its own.
    pub fn fitted(self, length: f32) -> Self {
        if self.on <= 0.0 || length <= 0.0 {
            return self;
        }
        let fewer = (length / self.period()).floor();
        let gap = |dashes: f32| (length - dashes * self.on) / dashes;
        let more = gap(fewer + 1.0);
        let off = if fewer < 1.0 || more <= 0.0 {
            more.max(0.0)
        } else {
            let less = gap(fewer);
            if (less - self.off).abs() < (more - self.off).abs() {
                less
            } else {
                more
            }
        };
        Self { off, ..self }
    }

    /// [`fitted`](Self::fitted) to the centre line of a `width` border round a
    /// box of `size` with corner `radius` [tl, tr, br, bl], which is where
    /// Chromium strokes it.
    pub fn around(self, size: Size, radius: [f32; 4], width: f32) -> Self {
        let (w, h) = (size.width - width, size.height - width);
        let arcs: f32 = radius
            .iter()
            .map(|r| (r - width / 2.0).clamp(0.0, w.min(h) / 2.0))
            .sum();
        self.fitted(2.0 * (w + h) - 2.0 * arcs + std::f32::consts::FRAC_PI_2 * arcs)
    }
}

/// Creates a new [`Border`] with the given [`Radius`].
///
/// ```
/// # use iced_core::border::{self, Border};
/// #
/// assert_eq!(border::rounded(10), Border::default().rounded(10));
/// ```
pub fn rounded(radius: impl Into<Radius>) -> Border {
    Border::default().rounded(radius)
}

/// Creates a new [`Border`] with the given [`Color`].
///
/// ```
/// # use iced_core::border::{self, Border};
/// # use iced_core::Color;
/// #
/// assert_eq!(border::color(Color::BLACK), Border::default().color(Color::BLACK));
/// ```
pub fn color(color: impl Into<Color>) -> Border {
    Border::default().color(color)
}

/// Creates a new [`Border`] with the given `width`.
///
/// ```
/// # use iced_core::border::{self, Border};
/// # use iced_core::Color;
/// #
/// assert_eq!(border::width(10), Border::default().width(10));
/// ```
pub fn width(width: impl Into<Pixels>) -> Border {
    Border::default().width(width)
}

impl Border {
    /// Sets the [`Color`] of the [`Border`].
    pub fn color(self, color: impl Into<Color>) -> Self {
        Self {
            color: color.into(),
            ..self
        }
    }

    /// Sets the [`Radius`] of the [`Border`].
    pub fn rounded(self, radius: impl Into<Radius>) -> Self {
        Self {
            radius: radius.into(),
            ..self
        }
    }

    /// Sets the width of the [`Border`] uniformly on all sides.
    pub fn width(self, width: impl Into<Pixels>) -> Self {
        Self {
            width: width.into().0,
            sides: None,
            ..self
        }
    }

    /// Draws the [`Border`] as dashes of `on` pixels with `off`-pixel gaps.
    pub fn dashed(self, on: impl Into<Pixels>, off: impl Into<Pixels>) -> Self {
        Self {
            dash: Some(Dash {
                on: on.into().0,
                off: off.into().0,
            }),
            ..self
        }
    }

    /// Draws the [`Border`] the way CSS `dashed` would at its width.
    pub fn dashed_css(self) -> Self {
        Self {
            dash: Some(Dash::css(self.width)),
            ..self
        }
    }

    /// Sets the top border width.
    pub fn top(mut self, width: impl Into<Pixels>) -> Self {
        let sides = self.sides.get_or_insert([self.width; 4]);
        sides[0] = width.into().0;
        self
    }

    /// Sets the right border width.
    pub fn right(mut self, width: impl Into<Pixels>) -> Self {
        let sides = self.sides.get_or_insert([self.width; 4]);
        sides[1] = width.into().0;
        self
    }

    /// Sets the bottom border width.
    pub fn bottom(mut self, width: impl Into<Pixels>) -> Self {
        let sides = self.sides.get_or_insert([self.width; 4]);
        sides[2] = width.into().0;
        self
    }

    /// Sets the left border width.
    pub fn left(mut self, width: impl Into<Pixels>) -> Self {
        let sides = self.sides.get_or_insert([self.width; 4]);
        sides[3] = width.into().0;
        self
    }

    /// Returns the resolved per-side border widths [top, right, bottom, left].
    pub fn widths(&self) -> [f32; 4] {
        self.sides.unwrap_or([self.width; 4])
    }

    /// Linearly interpolates between two [`Border`]s by the given amount.
    ///
    /// A uniform border and a per-side one blend through their resolved
    /// [`widths`](Self::widths), so the result is per-side for as long as either
    /// end is — stepping straight to `other`'s sides instead would pop the border
    /// on and off mid-transition. Two uniform borders stay uniform.
    pub fn lerp(self, other: Self, amount: f32) -> Self {
        let lerp = |from: f32, to: f32| from + (to - from) * amount;

        let sides = if self.sides.is_none() && other.sides.is_none() {
            None
        } else {
            let (from, to) = (self.widths(), other.widths());
            Some(std::array::from_fn(|i| lerp(from[i], to[i])))
        };

        // A pattern is not a continuous quantity; it holds until the far end
        // has one of its own.
        let dash = match (self.dash, other.dash) {
            (Some(from), Some(to)) => Some(Dash {
                on: lerp(from.on, to.on),
                off: lerp(from.off, to.off),
            }),
            (from, to) => {
                if amount < 0.5 {
                    from
                } else {
                    to
                }
            }
        };

        Self {
            color: self.color.lerp(other.color, amount),
            width: lerp(self.width, other.width),
            radius: self.radius.lerp(other.radius, amount),
            sides,
            dash,
        }
    }
}

#[cfg(test)]
mod dash_tests {
    use super::*;

    #[test]
    fn a_css_dash_follows_the_browsers_thin_and_thick_rules() {
        // Measured off Chromium: 0.5px and 1px give 3 on / 2 off, 2px gives
        // 6 / 4, and from 3px the dash is two widths and the gap one.
        assert_eq!(Dash::css(0.5), Dash { on: 3.0, off: 2.0 });
        assert_eq!(Dash::css(1.0), Dash { on: 3.0, off: 2.0 });
        assert_eq!(Dash::css(2.0), Dash { on: 6.0, off: 4.0 });
        assert_eq!(Dash::css(3.0), Dash { on: 6.0, off: 3.0 });
    }

    #[test]
    fn a_closed_dash_fits_whole_dashes_round_the_outline() {
        // Measured off Chromium: a 600×275.4 box rounded 14 with a 1px border
        // has a centre line 1723.6 long, dashed 345 times with 1.996 gaps.
        let dash = Dash::css(1.0).around(Size::new(600.0, 275.4), [14.0; 4], 1.0);
        assert!((1723.62 / dash.period() - 345.0).abs() < 0.01, "{dash:?}");
        assert!((dash.off - 1.996).abs() < 0.001, "{dash:?}");
        // Fewer dashes when that leaves the gap nearer its own.
        assert_eq!(Dash { on: 3.0, off: 2.0 }.fitted(26.0).off, 2.2);
        // An outline shorter than a period still gets a dash.
        assert_eq!(Dash { on: 3.0, off: 2.0 }.fitted(4.0).off, 1.0);
    }

    #[test]
    fn a_border_stays_solid_until_it_is_asked_to_dash() {
        assert_eq!(Border::default().dash, None);
        let dashed = Border::default().width(1).dashed(4, 2);
        assert_eq!(dashed.dash, Some(Dash { on: 4.0, off: 2.0 }));
        assert_eq!(dashed.dash.map(Dash::period), Some(6.0));
    }

    #[test]
    fn a_tween_keeps_the_pattern_of_its_nearer_end() {
        let solid = Border::default();
        let dashed = Border::default().dashed(3, 3);
        assert_eq!(solid.lerp(dashed, 0.25).dash, None);
        assert_eq!(solid.lerp(dashed, 0.75).dash, dashed.dash);
    }
}

/// The border radii for the corners of a graphics primitive in the order:
/// top-left, top-right, bottom-right, bottom-left.
#[derive(Debug, Clone, Copy, PartialEq, Default)]
pub struct Radius {
    /// Top left radius
    pub top_left: f32,
    /// Top right radius
    pub top_right: f32,
    /// Bottom right radius
    pub bottom_right: f32,
    /// Bottom left radius
    pub bottom_left: f32,
}

/// Creates a new [`Radius`] with the same value for each corner.
pub fn radius(value: impl Into<Pixels>) -> Radius {
    Radius::new(value)
}

/// Creates a new [`Radius`] with the given top left value.
pub fn top_left(value: impl Into<Pixels>) -> Radius {
    Radius::default().top_left(value)
}

/// Creates a new [`Radius`] with the given top right value.
pub fn top_right(value: impl Into<Pixels>) -> Radius {
    Radius::default().top_right(value)
}

/// Creates a new [`Radius`] with the given bottom right value.
pub fn bottom_right(value: impl Into<Pixels>) -> Radius {
    Radius::default().bottom_right(value)
}

/// Creates a new [`Radius`] with the given bottom left value.
pub fn bottom_left(value: impl Into<Pixels>) -> Radius {
    Radius::default().bottom_left(value)
}

/// Creates a new [`Radius`] with the given value as top left and top right.
pub fn top(value: impl Into<Pixels>) -> Radius {
    Radius::default().top(value)
}

/// Creates a new [`Radius`] with the given value as bottom left and bottom right.
pub fn bottom(value: impl Into<Pixels>) -> Radius {
    Radius::default().bottom(value)
}

/// Creates a new [`Radius`] with the given value as top left and bottom left.
pub fn left(value: impl Into<Pixels>) -> Radius {
    Radius::default().left(value)
}

/// Creates a new [`Radius`] with the given value as top right and bottom right.
pub fn right(value: impl Into<Pixels>) -> Radius {
    Radius::default().right(value)
}

impl Radius {
    /// Creates a new [`Radius`] with the same value for each corner.
    pub fn new(value: impl Into<Pixels>) -> Self {
        let value = value.into().0;

        Self {
            top_left: value,
            top_right: value,
            bottom_right: value,
            bottom_left: value,
        }
    }

    /// Sets the top left value of the [`Radius`].
    pub fn top_left(self, value: impl Into<Pixels>) -> Self {
        Self {
            top_left: value.into().0,
            ..self
        }
    }

    /// Sets the top right value of the [`Radius`].
    pub fn top_right(self, value: impl Into<Pixels>) -> Self {
        Self {
            top_right: value.into().0,
            ..self
        }
    }

    /// Sets the bottom right value of the [`Radius`].
    pub fn bottom_right(self, value: impl Into<Pixels>) -> Self {
        Self {
            bottom_right: value.into().0,
            ..self
        }
    }

    /// Sets the bottom left value of the [`Radius`].
    pub fn bottom_left(self, value: impl Into<Pixels>) -> Self {
        Self {
            bottom_left: value.into().0,
            ..self
        }
    }

    /// Sets the top left and top right values of the [`Radius`].
    pub fn top(self, value: impl Into<Pixels>) -> Self {
        let value = value.into().0;

        Self {
            top_left: value,
            top_right: value,
            ..self
        }
    }

    /// Sets the bottom left and bottom right values of the [`Radius`].
    pub fn bottom(self, value: impl Into<Pixels>) -> Self {
        let value = value.into().0;

        Self {
            bottom_left: value,
            bottom_right: value,
            ..self
        }
    }

    /// Sets the top left and bottom left values of the [`Radius`].
    pub fn left(self, value: impl Into<Pixels>) -> Self {
        let value = value.into().0;

        Self {
            top_left: value,
            bottom_left: value,
            ..self
        }
    }

    /// Sets the top right and bottom right values of the [`Radius`].
    pub fn right(self, value: impl Into<Pixels>) -> Self {
        let value = value.into().0;

        Self {
            top_right: value,
            bottom_right: value,
            ..self
        }
    }

    /// Linearly interpolates between `self` and `other` by the given amount,
    /// corner by corner.
    ///
    /// At `amount = 0.0` returns `self`, at `amount = 1.0` returns `other`.
    pub const fn lerp(self, other: Self, amount: f32) -> Self {
        Self {
            top_left: self.top_left + (other.top_left - self.top_left) * amount,
            top_right: self.top_right + (other.top_right - self.top_right) * amount,
            bottom_right: self.bottom_right + (other.bottom_right - self.bottom_right) * amount,
            bottom_left: self.bottom_left + (other.bottom_left - self.bottom_left) * amount,
        }
    }
}

impl From<f32> for Radius {
    fn from(radius: f32) -> Self {
        Self {
            top_left: radius,
            top_right: radius,
            bottom_right: radius,
            bottom_left: radius,
        }
    }
}

impl From<u8> for Radius {
    fn from(w: u8) -> Self {
        Self::from(f32::from(w))
    }
}

impl From<u32> for Radius {
    fn from(w: u32) -> Self {
        Self::from(w as f32)
    }
}

impl From<i32> for Radius {
    fn from(w: i32) -> Self {
        Self::from(w as f32)
    }
}

impl From<Radius> for [f32; 4] {
    fn from(radi: Radius) -> Self {
        [
            radi.top_left,
            radi.top_right,
            radi.bottom_right,
            radi.bottom_left,
        ]
    }
}

impl std::ops::Mul<f32> for Radius {
    type Output = Self;

    fn mul(self, scale: f32) -> Self::Output {
        Self {
            top_left: self.top_left * scale,
            top_right: self.top_right * scale,
            bottom_right: self.bottom_right * scale,
            bottom_left: self.bottom_left * scale,
        }
    }
}

/// An outline drawn outside a widget's bounds (e.g. a focus ring).
///
/// Combines a [`Border`] (color, width, radius) with a `gap` that controls
/// the space between the widget edge and the inner edge of the outline.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Outline {
    /// The border styling of the outline (color, width, radius).
    pub border: Border,
    /// Gap in logical pixels between the widget bounds and the outline.
    pub gap: f32,
}

impl Outline {
    /// Creates a new [`Outline`] with the given [`Border`] and zero gap.
    pub fn new(border: Border) -> Self {
        Self { border, gap: 0.0 }
    }

    /// Sets the gap between the widget bounds and the outline.
    #[must_use]
    pub fn gap(self, gap: f32) -> Self {
        Self { gap, ..self }
    }
}