WoltModalSheet

For more flexible or declarative navigation, you can use ValueNotifier to control the modal state.

Navigation by Page Index

Use a ValueNotifier<int> pageIndexNotifier to control which page is currently visible. This is ideal for simple state-driven transitions.

Declarative Page List Management

Use a ValueNotifier<WoltModalSheetPageListBuilder> pageListBuilderNotifier to manage the entire page stack dynamically. This is suitable for Navigator 2.0-style declarative navigation.

Note: Do not mix pageListBuilderNotifier with imperative navigation methods (like showNext()).

When using the dynamic path approach, use WoltModalSheet.showWithDynamicPath instead of the standard show method.

// 1. Navigation by Page Index
final pageIndexNotifier = ValueNotifier(0);

WoltModalSheet.show(
  context: context,
  pageListBuilder: (modalSheetContext) => [
    PageOne(onNextButtonPressed: () => pageIndexNotifier.value = 1),
    PageTwo(onBackButtonPressed: () => pageIndexNotifier.value = pageIndexNotifier.value - 1),
  ],
  pageIndexNotifier: pageIndexNotifier,
);

// 2. Dynamic Page List (Declarative)
final pageIndexNotifier = ValueNotifier(0);
final pageListBuilderNotifier = ValueNotifier((context) => [
  PageOne(onNextButtonPressed: () => pageIndexNotifier.value++),
  PageTwo(onBackButtonPressed: () => pageIndexNotifier.value--),
]);

WoltModalSheet.showWithDynamicPath(
  context: context,
  pageListBuilderNotifier: pageListBuilderNotifier,
  pageIndexNotifier: pageIndexNotifier,
);

WoltModalSheet organizes its UI elements across several layers on the z-axis to create a cohesive interactive experience. Understanding these layers is key to designing your modal content:

1. Navigation Bar Layer: The topmost transparent layer. It contains navigational widgets like the leading widget (typically a back button) and the trailing widget (typically a close button). The middle area is reserved for the top bar title.
2. Top Bar Layer: Sits below the navigation bar. It displays the topBarTitle and provides context. It can be configured to be sticky or hidden based on scroll position.
3. Sticky Action Bar (SAB) Layer: Positioned at the top of the z-axis (anchored to the bottom of the view). It guides users to the next step and often includes a subtle gradient to hint at scrollable content below.
4. Main Content Layer: The base layer containing the heroImage, pageTitle, and the scrollable mainContent.

WoltModalSheet uses the decorator pattern to allow dynamic addition of behavior to objects. You can apply decorations at two levels:

1. Modal Type Level: Applied to all modals of a specific type (e.g., all bottom sheets). This is achieved by extending a WoltModalType class and overriding decoratePageContent and decorateModal.
2. Modal Level: Applied specifically when calling WoltModalSheet.show. This is done using the pageContentDecorator and modalDecorator properties.

class MyCustomBottomSheetType extends WoltBottomSheetType {
  const MyCustomBottomSheetType() : super();

  @override
  Widget decoratePageContent(BuildContext context, Widget child, bool useSafeArea) {
    return Padding(
      padding: const EdgeInsets.all(16.0),
      child: child,
    );
  }

  @override
  Widget decorateModal(BuildContext context, Widget modal, bool useSafeArea) {
    return useSafeArea ? SafeArea(child: modal) : modal;
  }
}

You can customize built-in modal types in two ways:

1. Extending the class: Create a new class that extends a specific type (e.g., WoltBottomSheetType) to set permanent default properties like shapeBorder, showDragHandle, or barrierDismissible.
2. Using copyWith: Use the copyWith method on an existing modal type instance to override specific properties during the WoltModalSheet.show call.

// Option 1: Extending the class
class MyCustomBottomSheetType extends WoltBottomSheetType {
  const MyCustomBottomSheetType()
      : super(
          shapeBorder: const RoundedRectangleBorder(borderRadius: BorderRadius.all(Radius.circular(24))),
          showDragHandle: false,
          barrierDismissible: false,
        );
}

// Option 2: Using copyWith
WoltModalSheet.show(
  context: context,
  modalTypeBuilder: (_) => WoltModalType.bottomSheet().copyWith(barrierDismissible: false),
);