Merge pull request #1203 from telerik/didi/bottomsheet

Add first part of bottom sheet docs

Author: didiyordanova

_config.yml

@@ -118,6 +118,10 @@ navigation:
     controls/border:
         title: "Border"
     ## End Border
+    ## BottomSheet
+    controls/bottomsheet:
+        title: "BottomSheet"
+    ## End BottomSheet
     ## BusyIndicator
     controls/busyindicator:
         title: "BusyIndicator"
@@ -727,6 +731,7 @@ intro_columns:
     title: "Navigation & Layouts"
     items:
         "Accordion": "accordion-overview"
+        "BottomSheet": "bottomsheet-overview"
         "DockLayout": "docklayout-overview"
         "Expander": "expander-overview"
         "NavigationView": "navigationview-overview"

controls/accordion/animation.md

@@ -10,14 +10,14 @@ slug: accordion-animation
 
 Telerik .NET MAUI Accordion provides an option to set the animation when expanding/collapsing an accordion item.
 
-## Animation while expanding/collapsing
+## Animation while Expanding/Collapsing
 
-To enable or disable the animation you need to use the `IsAnimationEnabled` property of `RadAccordion`. By default, the Animation is enabled.
+To enable or disable the animation, use the `IsAnimationEnabled` (`bool`) property of `RadAccordion`. By default, the Animation is enabled.
 
 You can also customize the duration and easing through `AnimationDuration` and `AnimationEasing` properties.
 
-* `AnimationDuration`(`int`)—Defines the duration of the animation while expanding/collapsing the AccordionItem. The default value is 500.
-* `AnimationEasing`(`Microsoft.Maui.Easing`)—Specifies animation acceleration over time. The default value is Easing.Linear.
+* `AnimationDuration`(`int`)—Defines the duration of the animation while expanding/collapsing the `AccordionItem`. The default value is `500`.
+* `AnimationEasing`(`Microsoft.Maui.Easing`)—Specifies animation acceleration over time. The default value is `Easing.Linear`.
 
 ## Example
 

controls/bottomsheet/animation.md

@@ -0,0 +1,32 @@
+---
+title: Animation
+page_title: .NET MAUI BottomSheet Documentation - Animation
+description: Learn how to configure animation settings for the Telerik BottomSheet for .NET MAUI, including duration, easing, and enable/disable options.
+position: 5
+slug: bottomsheet-animation
+---
+
+# .NET MAUI BottomSheet Animation
+
+Adding animation to the BottomSheet provides visual continuity and makes the interface feel more responsive and polished. Smooth transitions help users understand the relationship between different states and create a more engaging user experience.
+
+The Telerik .NET MAUI BottomSheet provides comprehensive animation options for opening, closing, and state transitions, whether triggered programmatically or through user interactions like swipe gestures.
+
+The following properties control the animation behavior of the BottomSheet:
+
+To enable or disable the animation, use the `IsAnimationEnabled` (`bool`) property of `RadBottomSheet`. By default, the animation is enabled.
+
+You can also customize the animation's duration and easing by using the following properties.
+
+* `AnimationDuration`(`uint`)—Defines the duration of the animation while opening/closing the bottom view. The default value is `1000` milliseconds.
+* `AnimationEasing`(`Microsoft.Maui.Easing`)—Specifies animation acceleration over time. The default value is `Easing.CubicOut`.
+
+> For a runnable example with the BottomSheet Animation scenario, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to **BottomSheet > Features** category.
+
+## See Also
+
+- [Swipe Gesture]({%slug bottomsheet-swipe-gesture%})
+- [Configure the BottomSheet]({%slug bottomsheet-configuration%})
+- [Style the BottomSheet]({%slug bottomsheet-styling%})
+- [Events]({%slug bottomsheet-events%})
+- [Methods]({%slug bottomsheet-methods%})

controls/bottomsheet/configuration.md

@@ -0,0 +1,127 @@
+---
+title: Configuration
+page_title: .NET MAUI BottomSheet Documentation - Configuration
+description: Learn more about how to configure the Telerik UI for .NET MAUI BottomSheet control.
+position: 3
+slug: bottomsheet-configuration
+---
+
+# .NET MAUI BottomSheet Configuration
+
+The Telerik UI for .NET MAUI BottomSheet control offers flexible configuration options for states, dimensions, and visual elements. You can define custom states with specific heights, control the sheet's dimensions using absolute or percentage values, and customize the draggable handle to match your application's design.
+
+## States
+
+The BottomSheet control provides a flexible state system that determines how much of the screen the component occupies. You can use predefined states or create custom ones to present content at different visibility levels.
+
+### Predefined States
+
+The control includes four built-in states with predefined heights:
+
+* `Hidden` (default)—Represents a completely hidden bottom sheet.
+* `Minimal`—Represents a minimal bottom sheet state with height `25%`.
+* `Partial`—Represents a partial bottom sheet state with height `50%`.
+* `Full`—Represents a full bottom sheet state with height `90%`.
+
+### Setting States
+
+You can specify the current state using the `State` property of type `BottomSheetState`:
+
+```xaml
+<telerik:RadBottomSheet x:Name="bottomSheet" 
+                        State="Partial">
+    <!-- Content -->
+</telerik:RadBottomSheet>
+```
+
+### Custom States
+
+You can control the generation of default states using the `AutoGenerateStates` (`bool`) property. The default value is `true`, which means the four predefined states are populated in the `States` collection.
+
+```xaml
+<telerik:RadBottomSheet AutoGenerateStates="False" />
+```
+
+Create custom states using the `BottomSheetState` class constructors:
+
+* Using `BottomSheetLength`
+
+```csharp
+public BottomSheetState(string name, BottomSheetLength height)
+```
+
+* Using `double` value
+
+```csharp
+public BottomSheetState(string name, double size, bool isPercentage = false)
+```
+
+Example of creating custom states:
+
+```csharp
+// Custom state with 30% height
+var customState = new BottomSheetState("Custom", 30, true);
+
+// Custom state with absolute height = 200
+var fixedState = new BottomSheetState("Fixed", 200, false);
+```
+
+### Programmatic State Changes
+
+Use the [`GoToBottomSheetState(string name)` method]({%slug bottomsheet-methods%}) to programmatically change states:
+
+Here is an example setting the predefined name of the state inside the `GoToBottomSheetState(string name)` method:
+
+<snippet id='open-bottomsheet-view' />
+
+Here is an example setting a custom state:
+
+```csharp
+// Navigate to custom states
+var customState = new BottomSheetState("Custom", 30, true);
+bottomSheet.GoToBottomSheetState("Custom");
+```
+
+### States Collection
+
+The BottomSheet provides a read-only `States` collection of type `ObservableCollection<BottomSheetState>` that contains all available states for the bottom sheet, including both predefined and custom states.
+
+> For a runnable example with setting the BottomSheet States, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to **BottomSheet > Features** category.
+
+## Width
+
+You can specify the width for the bottom sheet content using the `BottomSheetContentWidth` property of type `BottomSheetLength`. The `BottomSheetLength` structure supports both absolute and percentage values:
+
+```xaml
+<!-- Percentage width -->
+<telerik:RadBottomSheet BottomSheetContentWidth="80%">
+    <!-- Content -->
+</telerik:RadBottomSheet>
+
+<!-- Absolute width -->
+<telerik:RadBottomSheet BottomSheetContentWidth="300">
+    <!-- Content -->
+</telerik:RadBottomSheet>
+```
+```csharp
+// Using percentage
+bottomSheet.BottomSheetContentWidth = new BottomSheetLength(80, true);
+
+// Using absolute value
+bottomSheet.BottomSheetContentWidth = new BottomSheetLength(300, false);
+```
+
+> For a runnable example with setting the BottomSheet Width, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to **BottomSheet > Features** category.
+
+## Handle
+
+The BottomSheet exposes a visual cue which indicates the control can be dragged. You can customize the handle by using the `HandleStyle` (`Style` with target type `BottomSheetHandle`) property.
+
+For more details, review the [BottomSheet Handle Styling]({%slug bottomsheet-styling%}#handle-styling) article.
+
+## See Also
+
+- [Animation when opening and closing the bottom sheet]({%slug bottomsheet-animation%})
+- [Style the BottomSheet]({%slug bottomsheet-styling%})
+- [Events]({%slug bottomsheet-events%})
+- [Methods]({%slug bottomsheet-methods%})

controls/bottomsheet/content.md

@@ -0,0 +1,61 @@
+---
+title: Content
+page_title: .NET MAUI BottomSheet Documentation - Content
+description: Learn more about how to set content inside the Telerik UI for .NET MAUI BottomSheet control.
+position: 3
+slug: bottomsheet-content
+---
+
+# .NET MAUI BottomSheet Content
+
+The BottomSheet control has two distinct content areas: the _main content_ that serves as the background layer, and the _bottom sheet content_ that slides up to overlay additional information or functionality. You set the main content as the primary child of the control, while the `BottomSheetContent` (`View`) property defines what appears in the sliding panel.
+
+Here is a sample scenario when using the Telerik .NET MAUI [`RadCollectionView`]({%slug collectionview-overview%}) in the main content of the BottomSheet and a detailed view in the `BottomSheetContent`.
+
+**1.** Define the sample data model:
+
+<snippet id='bottomsheet-data-model' />
+
+**2.** Define the `ViewModel`:
+
+<snippet id='bottomsheet-view-model' />
+
+**3.** Define the BottomSheet in XAML with `RadCollectionView`:
+
+<snippet id='bottomsheet-animation-swipe' />
+
+**4.** Add the `telerik` namespace:
+
+```XAML
+xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
+```
+
+**5.** Add the following code for the `RadCollectionView.ItemTapped` event handler:
+
+<snippet id='bottomsheet-content-tapped-event' />
+
+This is the result on Android:
+
+![.NET MAUI BottomSheet Content](images/bottomsheet-content.png)
+
+> For a runnable example with the BottomSheet Content scenario, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and review all **BottomSheet** example.
+
+## Setting Custom Control Template
+
+> If you want to review the default BottomSheet templates, add the [TelerikTheming]({%slug themes-overview%}) to the project and go to `TelerikTheming/Styles/Platform/BottomSheet.xaml` file.
+
+
+Here is an example setting custom `ControlTemplate`.
+
+<snippet id='bottomsheet-custom-control-template' />
+
+This is the result on Android:
+
+![.NET MAUI BottomSheet Control Template](images/bottomsheet-control-template.png)
+
+## See Also
+
+- [Animation when opening and closing the bottom sheet]({%slug bottomsheet-animation%})
+- [Style the BottomSheet]({%slug bottomsheet-styling%})
+- [Events]({%slug bottomsheet-events%})
+- [Methods]({%slug bottomsheet-methods%})

controls/bottomsheet/events.md

@@ -0,0 +1,21 @@
+---
+title: Events
+page_title: .NET MAUI BottomSheet Documentation - Events
+description: Learn about the PositionChanged event in Telerik UI for .NET MAUI BottomSheet and how to handle position changes when the bottom sheet is dragged or programmatically moved.
+position: 9
+slug: bottomsheet-events
+---
+
+# .NET MAUI BottomSheet Events
+
+The BottomSheet `StateChanging` event is useful for tracking user interactions and responding to sheet movements. Use this event to update UI elements based on the sheet's state, implement custom animations, or trigger actions when the sheet reaches specific state during drag gestures or programmatic state changes.
+The `StateChanging` event handler receives two parameters: 
+* The `sender` argument, which is of type `object`, but can be cast to the `RadBottomSheet` type.
+* The `BottomSheetStateChangingEventArgs` object, which has a reference to the new position of the bottom sheet through its `Position` property (of type `double`).
+
+## See Also
+
+- [Configure the BottomSheet]({%slug bottomsheet-configuration%})
+- [Animation when opening and closing the bottom sheet]({%slug bottomsheet-animation%})
+- [Style the BottomSheet]({%slug bottomsheet-styling%})
+- [Methods]({%slug bottomsheet-methods%})

controls/bottomsheet/getting-started.md

@@ -0,0 +1,89 @@
+---
+title: Getting Started
+page_title: .NET MAUI BottomSheet Documentation - Getting Started
+description: Get started with the Telerik UI for .NET MAUI BottomSheet control and learn how to add the control to your .NET MAUI application.
+position: 2
+slug: bottomsheet-getting-started
+---
+
+# Getting Started with the .NET MAUI BottomSheet
+
+This guide provides the information you need to start using the Telerik UI for .NET MAUI BottomSheet by adding the control to your project.
+
+At the end, you will achieve the following result.
+
+![BottomSheet Getting Started](images/bottomsheet-getting-started.png)
+
+## Prerequisites
+
+Before adding the BottomSheet, you need to:
+
+1. [Set up your .NET MAUI application]({%slug maui-getting-started %}#step-1-set-up-your-net-maui-application).
+
+1. [Download Telerik UI for .NET MAUI]({% slug maui-getting-started %}#step-2-download-telerik-ui-for-net-maui).
+
+1. [Install Telerik UI for .NET MAUI]({%slug maui-getting-started %}#step-3-install-telerik-ui-for-net-maui).
+
+## Define the Control
+
+**1.** When your .NET MAUI application is set up, you are ready to add the BottomSheet control to your page.
+
+<snippet id='bottomsheet-getting-started-xaml' />
+<snippet id='bottomsheet-getting-started-csharp' />
+
+**2.** Add the `telerik` namespace:
+
+```XAML
+xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
+```
+```C#
+using Telerik.Maui.Controls;
+```
+
+**3.** Add the code for opening the BottomSheet view:
+
+<snippet id='open-bottomsheet-view' />
+
+**4.** Add the code for closing the BottomSheet view:
+
+<snippet id='close-bottomsheet-view' />
+
+**5.** Register the Telerik controls through the `Telerik.Maui.Controls.Compatibility.UseTelerik` extension method called inside the `CreateMauiApp` method of the `MauiProgram.cs` file of your project:
+
+```C#
+using Telerik.Maui.Controls.Compatibility;
+
+public static class MauiProgram
+{
+	public static MauiApp CreateMauiApp()
+	{
+		var builder = MauiApp.CreateBuilder();
+		builder
+			.UseTelerik()
+			.UseMauiApp<App>()
+			.ConfigureFonts(fonts =>
+			{
+				fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
+			});
+
+		return builder.Build();
+	}
+}
+```
+
+> For a runnable example with the BottomSheet Getting Started scenario, see the [SDKBrowser Demo Application]({%slug sdkbrowser-app%}) and go to **BottomSheet > Getting Started**.
+
+## Additional Resources
+
+- [.NET MAUI BottomSheet Product Page](https://www.telerik.com/maui-ui/bottomsheet)
+- [.NET MAUI BottomSheet Forum Page](https://www.telerik.com/forums/maui?tagId=1763)
+- [Telerik .NET MAUI Blogs](https://www.telerik.com/blogs/mobile-net-maui)
+- [Telerik .NET MAUI Roadmap](https://www.telerik.com/support/whats-new/maui-ui/roadmap)
+
+## See Also
+
+- [Configure the BottomSheet]({%slug bottomsheet-configuration%})
+- [Animation when opening and closing the bottom sheet]({%slug bottomsheet-animation%})
+- [Style the BottomSheet]({%slug bottomsheet-styling%})
+- [Events]({%slug bottomsheet-events%})
+- [Methods]({%slug bottomsheet-methods%})