feat: add letter_spacing support to text rendering

Add optional letter_spacing field to Text, Span, and Paragraph types.
Default to 0.25px when unspecified via to_attributes_with_spacing().
Converts pixel values to EM units for cosmic_text compatibility.

Author: Ericky Dos Santos

core/src/text.rs

@@ -44,6 +44,12 @@ pub struct Text<Content = String, Font = crate::Font> {
 
     /// The [`Wrapping`] strategy of the [`Text`].
     pub wrapping: Wrapping,
+
+    /// The letter spacing of the [`Text`] in pixels.
+    ///
+    /// Extra horizontal space added between each character glyph.
+    /// If `None`, no extra spacing is applied.
+    pub letter_spacing: Option<f32>,
 }
 
 /// The shaping strategy of some text.
@@ -274,6 +280,10 @@ pub struct Span<'a, Link = (), Font = crate::Font> {
     pub underline: bool,
     /// Whether the [`Span`] should be struck through or not.
     pub strikethrough: bool,
+    /// The letter spacing of the [`Span`] in pixels.
+    ///
+    /// Per-span override; falls back to paragraph default if `None`.
+    pub letter_spacing: Option<f32>,
 }
 
 /// A text highlight.
@@ -299,6 +309,7 @@ impl<'a, Link, Font> Span<'a, Link, Font> {
             padding: Padding::ZERO,
             underline: false,
             strikethrough: false,
+            letter_spacing: None,
         }
     }
 
@@ -429,6 +440,12 @@ impl<'a, Link, Font> Span<'a, Link, Font> {
         self
     }
 
+    /// Sets the letter spacing of the [`Span`] in pixels.
+    pub fn letter_spacing(mut self, letter_spacing: f32) -> Self {
+        self.letter_spacing = Some(letter_spacing);
+        self
+    }
+
     /// Turns the [`Span`] into a static one.
     pub fn to_static(self) -> Span<'static, Link, Font> {
         Span {
@@ -442,6 +459,7 @@ impl<'a, Link, Font> Span<'a, Link, Font> {
             padding: self.padding,
             underline: self.underline,
             strikethrough: self.strikethrough,
+            letter_spacing: self.letter_spacing,
         }
     }
 }

core/src/text/paragraph.rs

@@ -96,6 +96,7 @@ impl<P: Paragraph> Plain<P> {
             vertical_alignment: text.vertical_alignment,
             shaping: text.shaping,
             wrapping: text.wrapping,
+            letter_spacing: text.letter_spacing,
         }) {
             Difference::None => {}
             Difference::Bounds => {

core/src/widget/text.rs

@@ -74,6 +74,7 @@ where
     shaping: Shaping,
     wrapping: Wrapping,
     class: Theme::Class<'a>,
+    letter_spacing: Option<f32>,
 }
 
 impl<'a, Theme, Renderer> Text<'a, Theme, Renderer>
@@ -96,6 +97,7 @@ where
             shaping: Shaping::default(),
             wrapping: Wrapping::default(),
             class: Theme::default(),
+            letter_spacing: None,
         }
     }
 
@@ -167,6 +169,14 @@ where
         self
     }
 
+    /// Sets the letter spacing of the [`Text`] in pixels.
+    ///
+    /// Extra horizontal space added between each character glyph.
+    pub fn letter_spacing(mut self, letter_spacing: f32) -> Self {
+        self.letter_spacing = Some(letter_spacing);
+        self
+    }
+
     /// Sets the style of the [`Text`].
     #[must_use]
     pub fn style(mut self, style: impl Fn(&Theme) -> Style + 'a) -> Self
@@ -251,6 +261,7 @@ where
             self.vertical_alignment,
             self.shaping,
             self.wrapping,
+            self.letter_spacing,
         )
     }
 
@@ -330,6 +341,7 @@ pub fn layout<Renderer>(
     vertical_alignment: alignment::Vertical,
     shaping: Shaping,
     wrapping: Wrapping,
+    letter_spacing: Option<f32>,
 ) -> layout::Node
 where
     Renderer: text::Renderer,
@@ -352,6 +364,7 @@ where
             vertical_alignment,
             shaping,
             wrapping,
+            letter_spacing,
         });
 
         paragraph.min_bounds()

graphics/src/text.rs

@@ -258,6 +258,24 @@ pub fn to_attributes(font: Font) -> cosmic_text::Attrs<'static> {
         .style(to_style(font.style))
 }
 
+/// Returns the attributes of the given [`Font`] with optional letter spacing.
+///
+/// Letter spacing is specified in pixels and will be converted to EM units
+/// (relative to font size) for the underlying text engine.
+pub fn to_attributes_with_spacing(
+    font: Font,
+    letter_spacing_px: Option<f32>,
+    font_size: f32,
+) -> cosmic_text::Attrs<'static> {
+    let attrs = to_attributes(font);
+    let px = letter_spacing_px.unwrap_or(0.25);
+    if px != 0.0 && font_size > 0.0 {
+        attrs.letter_spacing(px / font_size)
+    } else {
+        attrs
+    }
+}
+
 fn to_family(family: font::Family) -> cosmic_text::Family<'static> {
     match family {
         font::Family::Name(name) => cosmic_text::Family::Name(name),

graphics/src/text/paragraph.rs

@@ -23,6 +23,7 @@ struct Internal {
     bounds: Size,
     min_bounds: Size,
     version: text::Version,
+    letter_spacing: Option<f32>,
 }
 
 impl Paragraph {
@@ -85,7 +86,7 @@ impl core::text::Paragraph for Paragraph {
         buffer.set_text(
             font_system.raw(),
             text.content,
-            &text::to_attributes(text.font),
+            &text::to_attributes_with_spacing(text.font, text.letter_spacing, f32::from(text.size)),
             text::to_shaping(text.shaping),
             None,
         );
@@ -102,6 +103,7 @@ impl core::text::Paragraph for Paragraph {
             bounds: text.bounds,
             min_bounds,
             version: font_system.version(),
+            letter_spacing: text.letter_spacing,
         }))
     }
 
@@ -128,7 +130,14 @@ impl core::text::Paragraph for Paragraph {
         buffer.set_rich_text(
             font_system.raw(),
             text.content.iter().enumerate().map(|(i, span)| {
-                let attrs = text::to_attributes(span.font.unwrap_or(text.font));
+                let span_font = span.font.unwrap_or(text.font);
+                let span_size = span.size.unwrap_or(text.size);
+                let span_letter_spacing = span.letter_spacing.or(text.letter_spacing);
+                let attrs = text::to_attributes_with_spacing(
+                    span_font,
+                    span_letter_spacing,
+                    f32::from(span_size),
+                );
 
                 let attrs = match (span.size, span.line_height) {
                     (None, None) => attrs,
@@ -174,6 +183,7 @@ impl core::text::Paragraph for Paragraph {
             bounds: text.bounds,
             min_bounds,
             version: font_system.version(),
+            letter_spacing: text.letter_spacing,
         }))
     }
 
@@ -206,6 +216,7 @@ impl core::text::Paragraph for Paragraph {
             || paragraph.wrapping != text.wrapping
             || paragraph.horizontal_alignment != text.horizontal_alignment
             || paragraph.vertical_alignment != text.vertical_alignment
+            || paragraph.letter_spacing != text.letter_spacing
         {
             core::text::Difference::Shape
         } else if paragraph.bounds != text.bounds {
@@ -405,6 +416,7 @@ impl Default for Internal {
             bounds: Size::ZERO,
             min_bounds: Size::ZERO,
             version: text::Version::default(),
+            letter_spacing: None,
         }
     }
 }

wgpu/src/lib.rs

@@ -410,6 +410,7 @@ impl Renderer {
                         vertical_alignment: alignment::Vertical::Top,
                         shaping: core::text::Shaping::Advanced,
                         wrapping: core::text::Wrapping::Word,
+                        letter_spacing: None,
                     };
 
                     renderer.fill_text(

widget/src/checkbox.rs

@@ -340,6 +340,7 @@ where
                     alignment::Vertical::Top,
                     self.text_shaping,
                     self.text_wrapping,
+                    None,
                 )
             },
         )
@@ -450,6 +451,7 @@ where
                         vertical_alignment: alignment::Vertical::Center,
                         shaping: *shaping,
                         wrapping: text::Wrapping::default(),
+                        letter_spacing: None,
                     },
                     bounds.center(),
                     style.icon_color,

widget/src/overlay/menu.rs

@@ -544,6 +544,7 @@ where
                     vertical_alignment: alignment::Vertical::Center,
                     shaping: self.text_shaping,
                     wrapping: text::Wrapping::default(),
+                    letter_spacing: None,
                 },
                 Point::new(bounds.x + self.padding.left, bounds.center_y()),
                 if is_selected {

widget/src/pick_list.rs

@@ -383,6 +383,7 @@ where
             vertical_alignment: alignment::Vertical::Center,
             shaping: self.text_shaping,
             wrapping: self.text_wrap,
+            letter_spacing: None,
         };
 
         for (option, paragraph) in options.iter().zip(state.options.iter_mut())
@@ -657,6 +658,7 @@ where
                     vertical_alignment: alignment::Vertical::Center,
                     shaping,
                     wrapping: wrap,
+                    letter_spacing: None,
                 },
                 Point::new(
                     bounds.x + bounds.width - self.padding.right,
@@ -687,6 +689,7 @@ where
                     vertical_alignment: alignment::Vertical::Center,
                     shaping: self.text_shaping,
                     wrapping: self.text_wrap,
+                    letter_spacing: None,
                 },
                 Point::new(bounds.x + self.padding.left, bounds.center_y()),
                 if is_selected {

widget/src/radio.rs

@@ -316,6 +316,7 @@ where
                     alignment::Vertical::Top,
                     self.text_shaping,
                     self.text_wrapping,
+                    None,
                 )
             },
         )