Add variable font support for text rendering

Introduces FontVariation type and modifiers for controlling variable font
axes like weight, width, slant, italic, and optical size. Integrates with
Apus 0.1.1's variable font API.

Author: tomasf

Package.resolved

@@ -10,7 +10,7 @@ let package = Package(
     dependencies: [
         .package(url: "https://github.com/tomasf/manifold-swift.git", .upToNextMinor(from: "0.2.3")),
         .package(url: "https://github.com/tomasf/ThreeMF.git", .upToNextMinor(from: "0.2.0")),
-        .package(url: "https://github.com/tomasf/Apus.git", .upToNextMinor(from: "0.1.0")),
+        .package(url: "https://github.com/tomasf/Apus.git", .upToNextMinor(from: "0.1.1")),
     ],
     targets: [
         .target(

Package.swift

@@ -0,0 +1,103 @@
+import Foundation
+internal import Apus
+
+/// A variation axis value to apply to a variable font.
+///
+/// Variable fonts allow continuous variation along design axes such as weight,
+/// width, and slant. Use `FontVariation` to specify custom axis values when
+/// rendering text.
+///
+/// ```swift
+/// Text("Semibold Condensed")
+///     .withFontVariations([.weight(600), .width(85)])
+/// ```
+///
+/// Common axes have convenience factory methods:
+/// - ``weight(_:)`` - Font weight (typically 100-900)
+/// - ``width(_:)`` - Font width as percentage (typically 50-200)
+/// - ``slant(_:)`` - Slant angle in degrees
+/// - ``italic(_:)`` - Italic axis (0 = roman, 1 = italic)
+/// - ``opticalSize(_:)`` - Optical size in points
+///
+/// For custom axes, use ``init(tag:value:)``:
+/// ```swift
+/// FontVariation(tag: "GRAD", value: 50)  // Grade axis
+/// ```
+///
+public struct FontVariation: Sendable, Hashable, Codable {
+    /// The 4-character OpenType axis tag (e.g., "wght", "wdth").
+    public let tag: String
+
+    /// The axis value in design space coordinates.
+    public let value: Double
+
+    /// Creates a variation with a custom axis tag and value.
+    ///
+    /// - Parameters:
+    ///   - tag: A 4-character OpenType axis tag.
+    ///   - value: The axis value in design space coordinates.
+    public init(tag: String, value: Double) {
+        precondition(tag.count == 4, "Axis tag must be exactly 4 characters")
+        self.tag = tag
+        self.value = value
+    }
+
+    // MARK: - Common Axes
+
+    /// Weight axis (wght). Common range: 100-900.
+    ///
+    /// Standard weight values:
+    /// - 100: Thin
+    /// - 200: Extra Light
+    /// - 300: Light
+    /// - 400: Regular
+    /// - 500: Medium
+    /// - 600: Semibold
+    /// - 700: Bold
+    /// - 800: Extra Bold
+    /// - 900: Black
+    ///
+    public static func weight(_ value: Double) -> FontVariation {
+        FontVariation(tag: Apus.FontVariation.weightTag, value: value)
+    }
+
+    /// Width axis (wdth). Common range: 50-200, where 100 is normal.
+    ///
+    /// Values below 100 produce condensed text, values above produce expanded text.
+    ///
+    public static func width(_ value: Double) -> FontVariation {
+        FontVariation(tag: Apus.FontVariation.widthTag, value: value)
+    }
+
+    /// Slant axis (slnt). Typically in degrees, negative for rightward slant.
+    ///
+    /// Common range: -12 to 0, where 0 is upright.
+    ///
+    public static func slant(_ value: Double) -> FontVariation {
+        FontVariation(tag: Apus.FontVariation.slantTag, value: value)
+    }
+
+    /// Italic axis (ital). Typically 0 (roman) or 1 (italic).
+    ///
+    public static func italic(_ value: Double) -> FontVariation {
+        FontVariation(tag: Apus.FontVariation.italicTag, value: value)
+    }
+
+    /// Optical size axis (opsz). Typically matches the point size.
+    ///
+    /// Fonts with optical size axes adjust their design based on the
+    /// intended display size.
+    ///
+    public static func opticalSize(_ value: Double) -> FontVariation {
+        FontVariation(tag: Apus.FontVariation.opticalSizeTag, value: value)
+    }
+}
+
+internal extension Array where Element == FontVariation {
+    /// Returns a new array with the given variation replacing any existing variation for the same axis.
+    func replacingVariation(_ variation: FontVariation) -> [FontVariation] {
+        var result = self.filter { $0.tag != variation.tag }
+        result.append(variation)
+        return result
+    }
+}

Sources/Cadova/Abstract Layer/2D/Text/FontVariation.swift

@@ -13,15 +13,17 @@ internal struct TextAttributes: Sendable, Hashable, Codable {
     var fontFace: FontFace?
     var fontSize: Double?
     var fontFile: URL?
+    var fontVariations: [FontVariation]?
     var horizontalAlignment: HorizontalTextAlignment?
     var verticalAlignment: VerticalTextAlignment?
     var lineSpacingAdjustment: Double?
     var tracking: Double?
 
-    init(fontFace: FontFace? = nil, fontSize: Double? = nil, fontFile: URL? = nil, horizontalAlignment: HorizontalTextAlignment? = nil, verticalAlignment: VerticalTextAlignment? = nil, lineSpacingAdjustment: Double? = nil, tracking: Double? = nil) {
+    init(fontFace: FontFace? = nil, fontSize: Double? = nil, fontFile: URL? = nil, fontVariations: [FontVariation]? = nil, horizontalAlignment: HorizontalTextAlignment? = nil, verticalAlignment: VerticalTextAlignment? = nil, lineSpacingAdjustment: Double? = nil, tracking: Double? = nil) {
         self.fontFace = fontFace
         self.fontSize = fontSize
         self.fontFile = fontFile
+        self.fontVariations = fontVariations
         self.horizontalAlignment = horizontalAlignment
         self.verticalAlignment = verticalAlignment
         self.lineSpacingAdjustment = lineSpacingAdjustment
@@ -33,6 +35,7 @@ internal struct TextAttributes: Sendable, Hashable, Codable {
             fontFace: fontFace ?? .default,
             fontSize: fontSize ?? 12,
             fontFile: fontFile,
+            fontVariations: fontVariations ?? [],
             horizontalAlignment: horizontalAlignment ?? .left,
             verticalAlignment: verticalAlignment ?? .lastBaseline,
             lineSpacingAdjustment: lineSpacingAdjustment ?? 0,

Sources/Cadova/Abstract Layer/2D/Text/TextAttributes.swift

@@ -12,14 +12,19 @@ extension TextAttributes {
             preconditionFailure("render(text:) called on unresolved TextAttributes")
         }
 
+        // Convert Cadova FontVariation to Apus FontVariation
+        let apusVariations = (fontVariations ?? []).map { variation in
+            Apus.FontVariation(tag: variation.tag, value: variation.value)
+        }
+
         // Load font using Apus
         let font: Font
         if let fontFile {
             let fontData = try Data(contentsOf: fontFile)
-            font = try Font(data: fontData, family: family, style: fontFace?.style)
+            font = try Font(data: fontData, family: family, style: fontFace?.style, variations: apusVariations)
         } else {
             do {
-                font = try Font(family: family, style: fontFace?.style)
+                font = try Font(family: family, style: fontFace?.style, variations: apusVariations)
             } catch Font.FontError.fontNotFound {
                 throw TextError.fontNotFound(family: family, style: fontFace?.style)
             }

Sources/Cadova/Abstract Layer/2D/Text/TextRendering.swift

@@ -145,6 +145,28 @@ public extension EnvironmentValues {
         get { textAttributes.tracking ?? 0 }
         set { textAttributes.tracking = newValue }
     }
+
+    /// The font variations to apply to variable fonts.
+    ///
+    /// Font variations control axes like weight, width, and slant for variable fonts.
+    /// If the font is not a variable font, variations are ignored.
+    ///
+    /// Use `.withFontVariations([...])` or specific modifiers like `.withFontWeight(_:)`
+    /// to set variations on geometry.
+    ///
+    /// ```swift
+    /// Text("Semibold")
+    ///     .withFontWeight(600)
+    ///
+    /// Text("Condensed Bold")
+    ///     .withFontVariations([.weight(700), .width(75)])
+    /// ```
+    ///
+    /// - SeeAlso: `fontFamily`
+    var fontVariations: [FontVariation] {
+        get { textAttributes.fontVariations ?? [] }
+        set { textAttributes.fontVariations = newValue }
+    }
 }
 
 public extension Geometry {
@@ -235,6 +257,76 @@ public extension Geometry {
             $0.tracking = adjustment
         }
     }
+
+    /// Applies font variations to variable fonts for text rendering.
+    ///
+    /// This replaces any existing font variations. For variable fonts, these
+    /// variations control design axes like weight, width, slant, etc.
+    ///
+    /// ```swift
+    /// Text("Custom Style")
+    ///     .withFontVariations([.weight(600), .width(85), .slant(-6)])
+    /// ```
+    ///
+    /// - Parameter variations: The variations to apply.
+    /// - Returns: A new geometry with the specified font variations.
+    func withFontVariations(_ variations: [FontVariation]) -> D.Geometry {
+        withEnvironment {
+            $0.fontVariations = variations
+        }
+    }
+
+    /// Sets common font variation axes for variable fonts.
+    ///
+    /// This modifier updates the specified axes while preserving other existing variations.
+    /// Only non-nil parameters are applied.
+    ///
+    /// ```swift
+    /// Text("Bold Condensed")
+    ///     .withFontVariations(weight: 700, width: 75)
+    ///
+    /// Text("Oblique")
+    ///     .withFontVariations(slant: -12)
+    /// ```
+    ///
+    /// - Parameters:
+    ///   - weight: The weight value (typically 100-900). Common values: 100 Thin, 300 Light,
+    ///     400 Regular, 500 Medium, 600 Semibold, 700 Bold, 900 Black.
+    ///   - width: The width as a percentage (typically 50-200). 100 is normal,
+    ///     below 100 is condensed, above 100 is expanded.
+    ///   - slant: The slant angle in degrees (typically -12 to 0). Negative values
+    ///     produce a rightward slant.
+    ///   - italic: The italic axis value (typically 0 for roman, 1 for italic).
+    ///   - opticalSize: The optical size in points. Fonts with this axis adjust
+    ///     their design based on the intended display size.
+    /// - Returns: A new geometry with the specified font variations.
+    func withFontVariations(
+        weight: Double? = nil,
+        width: Double? = nil,
+        slant: Double? = nil,
+        italic: Double? = nil,
+        opticalSize: Double? = nil
+    ) -> D.Geometry {
+        withEnvironment {
+            var variations = $0.fontVariations
+            if let weight {
+                variations = variations.replacingVariation(.weight(weight))
+            }
+            if let width {
+                variations = variations.replacingVariation(.width(width))
+            }
+            if let slant {
+                variations = variations.replacingVariation(.slant(slant))
+            }
+            if let italic {
+                variations = variations.replacingVariation(.italic(italic))
+            }
+            if let opticalSize {
+                variations = variations.replacingVariation(.opticalSize(opticalSize))
+            }
+            $0.fontVariations = variations
+        }
+    }
 }
 
 /// Horizontal alignment options for text relative to the origin.