feat: add stacSliverVisibility widget, parser,example and documentation

docs/docs.json

@@ -125,6 +125,7 @@
                             "widgets/single_child_scroll_view",
                             "widgets/slider",
                             "widgets/sliver_app_bar",
+                            "widgets/sliver_visibility",
                             "widgets/sliver_opacity",
                             "widgets/sliver_safe_area",
                             "widgets/switch",

docs/widgets/sliver_visibility.mdx

@@ -0,0 +1,50 @@
+---
+title: "SliverVisibility"
+description: "Documentation for SliverVisibility"
+---
+
+The Stac SliverVisibility allows you to conditionally show or hide a sliver
+inside a `CustomScrollView`.
+
+When the sliver is not visible, it can either be completely removed from the
+scroll layout or replaced with another sliver, depending on the configuration.
+
+To know more about the SliverVisibility widget in Flutter, refer to
+the [official documentation](https://api.flutter.dev/flutter/widgets/SliverVisibility-class.html).
+
+## Properties
+
+| Property                 | Type                    | Description                                                                 |
+|--------------------------|-------------------------|-----------------------------------------------------------------------------|
+| sliver                   | `Map<String, dynamic>`  | The sliver widget whose visibility is controlled.                          |
+| replacementSliver        | `Map<String, dynamic>?` | The sliver to display when `visible` is `false`. Defaults to an empty sliver. |
+| visible                  | `bool`                  | Whether the sliver is visible. Defaults to `true`.                          |
+| maintainState            | `bool`                  | Whether to maintain the state of the sliver when hidden.                   |
+| maintainAnimation        | `bool`                  | Whether to maintain animations when the sliver is hidden.                  |
+| maintainSize             | `bool`                  | Whether to maintain layout space when the sliver is hidden.                |
+| maintainSemantics        | `bool`                  | Whether to maintain semantics when the sliver is hidden.                   |
+| maintainInteractivity    | `bool`                  | Whether to maintain interactivity when the sliver is hidden.               |
+
+## Example JSON
+
+```json
+{
+  "type": "sliverVisibility",
+  "visible": false,
+  "sliver": {
+    "type": "sliverToBoxAdapter",
+    "child": {
+      "type": "container",
+      "height": 180,
+      "color": "warning",
+      "child": {
+        "type": "center",
+        "child": {
+          "type": "text",
+          "data": "This sliver is hidden"
+        }
+      }
+    }
+  }
+}
+```

examples/stac_gallery/assets/json/home_screen.json

@@ -1332,6 +1332,30 @@
       }
     }
   },
+  {
+    "type": "listTile",
+    "leading": {
+      "type": "icon",
+      "iconType": "cupertino",
+      "icon": "app_fill"
+    },
+    "title": {
+      "type": "text",
+      "data": "Stac Sliver Visibility"
+    },
+    "subtitle": {
+      "type": "text",
+      "data": "A Sliver Visibility widget"
+    },
+    "style": "list",
+    "onTap": {
+      "actionType": "navigate",
+      "widgetJson": {
+        "type": "exampleScreen",
+        "assetPath": "assets/json/sliver_visibility_example.json"
+      }
+    }
+  },
   {
     "type": "listTile",
     "leading": {

examples/stac_gallery/assets/json/sliver_visibility_example.json

@@ -0,0 +1,34 @@
+{
+    "type": "scaffold",
+    "appBar": {
+        "type": "appBar",
+        "title": {
+            "type": "text",
+            "data": "Sliver Visibility"
+        }
+    },
+    "body": {
+        "type": "customScrollView",
+        "slivers": [
+            {
+                "type": "sliverVisibility",
+                "visible": true,
+                "sliver": {
+                    "type": "sliverToBoxAdapter",
+                    "child": {
+                        "type": "container",
+                        "height": 200,
+                        "color": "secondary",
+                        "child": {
+                            "type": "center",
+                            "child": {
+                                "type": "text",
+                                "data": "This sliver is conditionally visible"
+                            }
+                        }
+                    }
+                }
+            }
+        ]
+    }
+}

packages/stac/lib/src/framework/stac_service.dart

@@ -114,6 +114,7 @@ class StacService {
     const StacRadioGroupParser(),
     const StacSliderParser(),
     const StacSliverAppBarParser(),
+    const StacSliverVisibilityParser(),
     const StacSliverOpacityParser(),
     const StacSliverSafeAreaParser(),
     const StacSliverPaddingParser(),

packages/stac/lib/src/parsers/widgets/stac_sliver_visibility/stac_sliver_visibility_parser.dart

@@ -0,0 +1,31 @@
+import 'package:flutter/material.dart';
+import 'package:stac/src/parsers/core/stac_widget_parser.dart';
+
+import 'package:stac_core/stac_core.dart';
+import 'package:stac_framework/stac_framework.dart';
+
+class StacSliverVisibilityParser extends StacParser<StacSliverVisibility> {
+  const StacSliverVisibilityParser();
+
+  @override
+  String get type => WidgetType.sliverVisibility.name;
+
+  @override
+  StacSliverVisibility getModel(Map<String, dynamic> json) =>
+      StacSliverVisibility.fromJson(json);
+
+  @override
+  Widget parse(BuildContext context, StacSliverVisibility model) {
+    return SliverVisibility(
+      visible: model.visible ?? true,
+      maintainState: model.maintainState ?? false,
+      maintainAnimation: model.maintainAnimation ?? false,
+      maintainSize: model.maintainSize ?? false,
+      maintainSemantics: model.maintainSemantics ?? false,
+      maintainInteractivity: model.maintainInteractivity ?? false,
+      sliver: model.sliver.parse(context) ?? const SliverToBoxAdapter(),
+      replacementSliver:
+          model.replacementSliver?.parse(context) ?? const SliverToBoxAdapter(),
+    );
+  }
+}

packages/stac/lib/src/parsers/widgets/widgets.dart

@@ -63,6 +63,7 @@ export 'package:stac/src/parsers/widgets/stac_single_child_scroll_view/stac_sing
 export 'package:stac/src/parsers/widgets/stac_sized_box/stac_sized_box_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_slider/stac_slider_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_sliver_app_bar/stac_sliver_app_bar_parser.dart';
+export 'package:stac/src/parsers/widgets/stac_sliver_visibility/stac_sliver_visibility_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_sliver_opacity/stac_sliver_opacity_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_sliver_safe_area/stac_sliver_safe_area_parser.dart';
 export 'package:stac/src/parsers/widgets/stac_sliver_padding/stac_sliver_padding_parser.dart';

packages/stac_core/lib/foundation/specifications/widget_type.dart

@@ -207,6 +207,9 @@ enum WidgetType {
   /// Sliver app bar widget
   sliverAppBar,
 
+  /// Sliver visibility widget
+  sliverVisibility,
+
   /// Sliver opacity widget
   sliverOpacity,
 

packages/stac_core/lib/widgets/sliver_visibility/stac_sliver_visibility.dart

@@ -0,0 +1,92 @@
+import 'package:json_annotation/json_annotation.dart';
+import 'package:stac_core/core/stac_widget.dart';
+import 'package:stac_core/foundation/foundation.dart';
+
+part 'stac_sliver_visibility.g.dart';
+
+/// A Stac model representing Flutter's [SliverVisibility] widget.
+///
+/// Controls whether a sliver is visible in a [CustomScrollView].
+/// When not visible, the sliver can optionally preserve layout,
+/// state, animation, semantics, or interactivity.
+///
+/// {@tool snippet}
+/// Dart Example:
+/// ```dart
+/// const StacSliverVisibility(
+///   visible: false,
+///   sliver: StacSliverToBoxAdapter(
+///     child: StacText(data: 'Hidden content'),
+///   ),
+/// )
+/// ```
+/// {@end-tool}
+///
+/// {@tool snippet}
+/// JSON Example:
+/// ```json
+/// {
+///   "type": "sliverVisibility",
+///   "visible": false,
+///   "sliver": {
+///     "type": "sliverToBoxAdapter",
+///     "child": {
+///       "type": "text",
+///       "data": "Hidden content"
+///     }
+///   }
+/// }
+/// ```
+/// {@end-tool}
+///
+/// See also:
+///  * Flutter's [SliverVisibility documentation](https://api.flutter.dev/flutter/widgets/SliverVisibility-class.html)
+@JsonSerializable()
+class StacSliverVisibility extends StacWidget {
+  /// Creates a [StacSliverVisibility].
+  const StacSliverVisibility({
+    required this.sliver,
+    this.replacementSliver,
+    this.visible,
+    this.maintainState,
+    this.maintainAnimation,
+    this.maintainSize,
+    this.maintainSemantics,
+    this.maintainInteractivity,
+  });
+
+  /// The sliver whose visibility is controlled.
+  final StacWidget sliver;
+
+  /// The sliver to display when [visible] is false.
+  final StacWidget? replacementSliver;
+
+  /// Whether the sliver is visible.
+  ///
+  /// Defaults to `true`.
+  final bool? visible;
+
+  /// Whether to maintain the state of the sliver when hidden.
+  final bool? maintainState;
+
+  /// Whether to maintain animations when the sliver is hidden.
+  final bool? maintainAnimation;
+
+  /// Whether to maintain layout space when the sliver is hidden.
+  final bool? maintainSize;
+
+  /// Whether to maintain semantics when the sliver is hidden.
+  final bool? maintainSemantics;
+
+  /// Whether to maintain interactivity when the sliver is hidden.
+  final bool? maintainInteractivity;
+
+  @override
+  String get type => WidgetType.sliverVisibility.name;
+
+  factory StacSliverVisibility.fromJson(Map<String, dynamic> json) =>
+      _$StacSliverVisibilityFromJson(json);
+
+  @override
+  Map<String, dynamic> toJson() => _$StacSliverVisibilityToJson(this);
+}

packages/stac_core/lib/widgets/widgets.dart

@@ -67,6 +67,7 @@ export 'single_child_scroll_view/stac_single_child_scroll_view.dart';
 export 'sized_box/stac_sized_box.dart';
 export 'slider/stac_slider.dart';
 export 'sliver_app_bar/stac_sliver_app_bar.dart';
+export 'sliver_visibility/stac_sliver_visibility.dart';
 export 'sliver_opacity/stac_sliver_opacity.dart';
 export 'sliver_safe_area/stac_sliver_safe_area.dart';
 export 'sliver_padding/stac_sliver_padding.dart';