feat(spark_css): add typed CssBackgroundImage and gradient support

- Added `CssBackgroundImage` sealed class with support for `url`, `linear-gradient`, `radial-gradient`, and `none`.
- Added supporting types: `CssGradientDirection`, `CssRadialShape`, `CssRadialSize`.
- Added `CssGradientStop` helper class.
- Added comprehensive tests in `packages/spark_css/test/css_background_image_test.dart`.
- NOTE: `CssGradientDirection.angle` currently accepts `String`; `CssAngle` will be integrated in a future PR.
- NOTE: Updated usage of `CssBackgroundPosition` to match the existing API in main (using `.parts()` instead of `.xy()`).

Author: kevin-sakemaer

packages/spark_css/lib/src/css_types/css_background_position.dart

@@ -1,58 +1,51 @@
-import 'css_length.dart';
 import 'css_value.dart';
 
-/// CSS background-position property.
+/// CSS background-position property values.
 sealed class CssBackgroundPosition implements CssValue {
   const CssBackgroundPosition._();
 
-  /// Center position (`center`).
-  static const CssBackgroundPosition center = _CssBackgroundPositionKeyword(
-    'center',
-  );
-
-  /// Top position (`top` - equivalent to `top center`).
-  static const CssBackgroundPosition top = _CssBackgroundPositionKeyword('top');
-
-  /// Bottom position (`bottom` - equivalent to `bottom center`).
-  static const CssBackgroundPosition bottom = _CssBackgroundPositionKeyword(
-    'bottom',
-  );
-
-  /// Left position (`left` - equivalent to `left center`).
+  // Keyword values
   static const CssBackgroundPosition left = _CssBackgroundPositionKeyword(
     'left',
   );
-
-  /// Right position (`right` - equivalent to `right center`).
+  static const CssBackgroundPosition center = _CssBackgroundPositionKeyword(
+    'center',
+  );
   static const CssBackgroundPosition right = _CssBackgroundPositionKeyword(
     'right',
   );
-
-  /// Top left position (`top left`).
-  static const CssBackgroundPosition topLeft = _CssBackgroundPositionKeyword(
-    'top left',
-  );
-
-  /// Top right position (`top right`).
-  static const CssBackgroundPosition topRight = _CssBackgroundPositionKeyword(
-    'top right',
-  );
-
-  /// Bottom left position (`bottom left`).
-  static const CssBackgroundPosition bottomLeft = _CssBackgroundPositionKeyword(
-    'bottom left',
+  static const CssBackgroundPosition top = _CssBackgroundPositionKeyword('top');
+  static const CssBackgroundPosition bottom = _CssBackgroundPositionKeyword(
+    'bottom',
   );
 
-  /// Bottom right position (`bottom right`).
-  static const CssBackgroundPosition bottomRight =
-      _CssBackgroundPositionKeyword('bottom right');
-
-  /// Position defined by x and y coordinates.
-  factory CssBackgroundPosition.xy(CssLength x, CssLength y) =
-      _CssBackgroundPositionXY;
-
-  /// Position defined by x coordinate (y defaults to center).
-  factory CssBackgroundPosition.x(CssLength x) = _CssBackgroundPositionX;
+  /// Creates a position from one to four values (keywords or lengths).
+  ///
+  /// Example:
+  /// ```dart
+  /// CssBackgroundPosition.parts([CssBackgroundPosition.left, CssLength.px(20)])
+  /// // Output: left 20px
+  /// ```
+  factory CssBackgroundPosition.parts(List<CssValue> values) =
+      _CssBackgroundPositionParts;
+
+  /// Multiple background positions (comma-separated).
+  ///
+  /// Example:
+  /// ```dart
+  /// CssBackgroundPosition.multiple([
+  ///   CssBackgroundPosition.parts([CssBackgroundPosition.left]),
+  ///   CssBackgroundPosition.parts([CssBackgroundPosition.right]),
+  /// ])
+  /// // Output: left, right
+  /// ```
+  factory CssBackgroundPosition.multiple(
+    List<CssBackgroundPosition> positions,
+  ) = _CssBackgroundPositionMultiple;
+
+  /// CSS variable reference.
+  factory CssBackgroundPosition.variable(String varName) =
+      _CssBackgroundPositionVariable;
 
   /// Raw CSS value escape hatch.
   factory CssBackgroundPosition.raw(String value) = _CssBackgroundPositionRaw;
@@ -70,21 +63,28 @@ final class _CssBackgroundPositionKeyword extends CssBackgroundPosition {
   String toCss() => keyword;
 }
 
-final class _CssBackgroundPositionXY extends CssBackgroundPosition {
-  final CssLength x;
-  final CssLength y;
-  const _CssBackgroundPositionXY(this.x, this.y) : super._();
+final class _CssBackgroundPositionParts extends CssBackgroundPosition {
+  final List<CssValue> values;
+  const _CssBackgroundPositionParts(this.values) : super._();
+
+  @override
+  String toCss() => values.map((v) => v.toCss()).join(' ');
+}
+
+final class _CssBackgroundPositionMultiple extends CssBackgroundPosition {
+  final List<CssBackgroundPosition> positions;
+  const _CssBackgroundPositionMultiple(this.positions) : super._();
 
   @override
-  String toCss() => '${x.toCss()} ${y.toCss()}';
+  String toCss() => positions.map((p) => p.toCss()).join(', ');
 }
 
-final class _CssBackgroundPositionX extends CssBackgroundPosition {
-  final CssLength x;
-  const _CssBackgroundPositionX(this.x) : super._();
+final class _CssBackgroundPositionVariable extends CssBackgroundPosition {
+  final String varName;
+  const _CssBackgroundPositionVariable(this.varName) : super._();
 
   @override
-  String toCss() => x.toCss();
+  String toCss() => 'var(--$varName)';
 }
 
 final class _CssBackgroundPositionRaw extends CssBackgroundPosition {

packages/spark_css/test/css_background_image_test.dart

@@ -148,7 +148,10 @@ void main() {
         final gradient = CssBackgroundImage.radialGradient(
           shape: CssRadialShape.circle,
           size: CssRadialSize.size(CssLength.px(50)),
-          position: CssBackgroundPosition.topLeft,
+          position: CssBackgroundPosition.parts([
+            CssBackgroundPosition.top,
+            CssBackgroundPosition.left,
+          ]),
           stops: [
             CssGradientStop(CssColor.red),
             CssGradientStop(CssColor.blue),
@@ -162,10 +165,10 @@ void main() {
 
       test('with position coordinates', () {
         final gradient = CssBackgroundImage.radialGradient(
-          position: CssBackgroundPosition.xy(
+          position: CssBackgroundPosition.parts([
             CssLength.percent(50),
             CssLength.percent(50),
-          ),
+          ]),
           stops: [
             CssGradientStop(CssColor.red),
             CssGradientStop(CssColor.blue),