From d18b662c9cc11c9e4b3636bd6aba545e8e1e5e6f Mon Sep 17 00:00:00 2001 From: Vick Top Date: Mon, 26 Feb 2024 15:31:27 +0100 Subject: [PATCH] doc: create documentation for files --- CONTRIBUTING.md | 194 ++++++++++++++++++ README.md | 2 +- lib/src/models/date_constraint.dart | 20 ++ lib/src/overlay_date_time_picker.dart | 3 + lib/src/utils/date_time_picker_config.dart | 3 + .../utils/date_time_picker_controller.dart | 49 +++-- .../utils/locking_page_scroll_physics.dart | 5 + lib/src/widgets/marked_icon.dart | 9 + .../month_date_time_picker.dart | 12 +- .../month_date_time_picker_sheet.dart | 55 +++-- .../overlay_date_time_picker/date_picker.dart | 18 ++ .../overlay_date_time_picker/overlay.dart | 24 +++ .../pickable_date.dart | 14 ++ .../week_date_time_picker.dart | 10 + .../week_date_time_picker_sheet.dart | 10 + 15 files changed, 382 insertions(+), 46 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..840680a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,194 @@ +# Contributing +First off, thanks for taking the time to contribute! ❤️ + +All types of contributions are encouraged and valued. +See the [Table of Contents](#table-of-contents) for different ways to help and details about how we handle them. +Please make sure to read the relevant section before making your contribution. +It will make it a lot easier for us maintainers and smooth out the experience for all involved. +Iconica looks forward to your contributions. 🎉 + +## Table of contents + - [Code of conduct](#code-of-conduct) + - [I Have a Question](#i-have-a-question) + - [I Want To Contribute](#i-want-to-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Contributing code](#contributing-code) + +## Code of conduct + +### Legal notice +When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. +All accepted pull requests and other additions to this project will be considered intellectual property of Iconica. + +All repositories should be kept clean of jokes, easter eggs and other unnecessary additions. + +## I have a question + +If you want to ask a question, we assume that you have read the available documentation found within the code. +Before you ask a question, it is best to search for existing issues that might help you. +In case you have found a suitable issue but still need clarification, you can ask your question +It is also advisable to search the internet for answers first. + +If you then still feel the need to ask a question and need clarification, we recommend the following: + +- Open an issue. +- Provide as much context as you can about what you're running into. + +We will then take care of the issue as soon as possible. + +## I want to contribute + +### Reporting bugs + + +**Before submitting a bug report** + +A good bug report shouldn't leave others needing to chase you up for more information. +Therefore, we ask you to investigate carefully, collect information and describe the issue in detail in your report. +Please complete the following steps in advance to help us fix any potential bug as fast as possible. + +- Make sure that you are using the latest version. +- Determine if your bug is really a bug and not an error on your side e.g. using incompatible environment components/versions (If you are looking for support, you might want to check [this section](#i-have-a-question)). +- To see if other users have experienced (and potentially already solved) the same issue you are having, check if there is not already a bug report existing for your bug or error. +- Also make sure to search the internet (including Stack Overflow) to see if users outside of Iconica have discussed the issue. +- Collect information about the bug: +- Stack trace (Traceback) +- OS, Platform and Version (Windows, Linux, macOS, x86, ARM) +- Version of the interpreter, compiler, SDK, runtime environment, package manager, depending on what seems relevant. +- Time and date of occurance +- Describe the expected result and actual result +- Can you reliably reproduce the issue? And can you also reproduce it with older versions? Describe all steps that lead to the bug. + +Once it's filed: + +- The project team will label the issue accordingly. +- A team member will try to reproduce the issue with your provided steps. + If there are no reproduction steps or no obvious way to reproduce the issue, the team will ask you for additional information. +- If the team is able to reproduce the issue, it will be moved into the backlog, as well as marked with a priority, and the issue will be left to be [implemented by someone](#contributing-code). + +### Contributing code + +When you start working on your contribution, make sure you are aware of the relevant documentation and the functionality of the component you are working on. + +When writing code, follow the style guidelines set by Dart: [Effective Dart](https://Dart.dev/guides/language/effective-Dart). This contains most information you will need to write clean Dart code that is well documented. + +**Documentation** + +As Effective Dart indicates, documenting your public methods with Dart doc comments is recommended. +Aside from Effective Dart, we require specific information in the documentation of a method: + +At the very least, your documentation should first name what the code does, then followed below by requirements for calling the method, the result of the method. +Any references to internal variables or other methods should be done through [var] to indicate a reference. + +If the method or class is complex enough (determined by the reviewers) an example is required. +If unsure, add an example in the docs using code blocks. + +For classes and methods, document the individual parameters with their implications. + +> Tip: Remember that the shortest documentation can be written by having good descriptive names in the first place. + +An example: +```Dart +library iconica_utilities.bidirectional_sorter; + +part 'sorter.Dart'; +part 'enum.Dart'; + +/// Generic sort method, allow sorting of list with primitives or complex types. +/// Uses [SortDirection] to determine the direction, either Ascending or Descending, +/// Gets called on [List] toSort of type [T] which cannot be shorter than 2. +/// Optionally for complex types a [Comparable] [Function] can be given to compare complex types. +/// ``` +/// List objects = []; +/// for (int i = 0; i < 10; i++) { +/// objects.add(TestObject(name: "name", id: i)); +/// } +/// +/// sort( +/// SortDirection.descending, objects, (object) => object.id); +/// +/// ``` +/// In the above example a list of TestObjects is created, and then sorted in descending order. +/// If the implementation of TestObject is as following: +/// ``` +/// class TestObject { +/// final String name; +/// final int id; +/// +/// TestObject({required this.name, required this.id}); +/// } +/// ``` +/// And the list is logged to the console, the following will appear: +/// ``` +/// [name9, name8, name7, name6, name5, name4, name3, name2, name1, name0] +/// ``` + +void sort( + /// Determines the sorting direction, can be either Ascending or Descending + SortDirection sortDirection, + + /// Incoming list, which gets sorted + List toSort, [ + + /// Optional comparable, which is only necessary for complex types + SortFieldGetter? sortValueCallback, +]) { + if (toSort.length < 2) return; + assert( + toSort.whereType().isNotEmpty || sortValueCallback != null); + BidirectionalSorter( + sortInstructions: >[ + SortInstruction( + sortValueCallback ?? (t) => t as Comparable, sortDirection), + ], + ).sort(toSort); +} + +/// same functionality as [sort] but with the added functionality +/// of sorting multiple values +void sortMulti( + /// Incoming list, which gets sorted + List toSort, + + /// list of comparables to sort multiple values at once, + /// priority based on index + List> sortValueCallbacks, +) { + if (toSort.length < 2) return; + assert(sortValueCallbacks.isNotEmpty); + BidirectionalSorter( + sortInstructions: sortValueCallbacks, + ).sort(toSort); +} + +``` + + + +**Tests** + +For each public method that was created, excluding widgets, which contains any form of logic (e.g. Calculations, predicates or major side-effects) tests are required. + +A set of tests is written for each method, covering at least each path within the method. For example: + +```Dart +void foo() { + try { + var bar = doSomething(); + if (bar) { + doSomethingElse(); + } else { + doSomethingCool(); + } + } catch (_) { + displayError(); + } +} +``` +The method above should result in 3 tests: + +1. A test for the path leading to displayError by the cause of an exception +2. A test for if bar is true, resulting in doSomethingElse() +3. A test for if bar is false, resulting in the doSomethingCool() method being called. + +This means that we require 100% coverage of each method you test. diff --git a/README.md b/README.md index dee9f42..977ab5e 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Please file any issues, bugs or feature request as an issue on our [GitHub](http ## Want to contribute -If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our [contribution guide](../CONTRIBUTING.md) and send us your [pull request](https://github.com/Iconica-Development/flutter_date_time_picker/pulls). +If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our [contribution guide](./CONTRIBUTING.md) and send us your [pull request](https://github.com/Iconica-Development/flutter_date_time_picker/pulls). ## Author diff --git a/lib/src/models/date_constraint.dart b/lib/src/models/date_constraint.dart index 3ca8783..095a3c0 100644 --- a/lib/src/models/date_constraint.dart +++ b/lib/src/models/date_constraint.dart @@ -2,15 +2,21 @@ // // SPDX-License-Identifier: BSD-3-Clause +/// Class representing date constraints for DateTime values. class DateTimeConstraint { + /// Minimum date constraint. final DateConstraint min; + + /// Maximum date constraint. final DateConstraint max; + /// Constructs a DateTimeConstraint instance. const DateTimeConstraint({ this.min = DateConstraint.infinity, this.max = DateConstraint.infinity, }); + /// Checks if the given date is within the range specified by min and max constraints. bool inRange(DateTime date) { return _checkDate( min, @@ -22,6 +28,7 @@ class DateTimeConstraint { ); } + /// Checks if the given date is within the date range (ignoring time) specified by min and max constraints. bool inDateRange(DateTime date) { return _checkDate( min, @@ -33,6 +40,7 @@ class DateTimeConstraint { ); } + /// Checks if the given date is within the month range specified by min and max constraints. bool inMonthRange(DateTime date) { return _checkDate( min, @@ -46,6 +54,7 @@ class DateTimeConstraint { ); } + /// Checks if the given date is within the year range specified by min and max constraints. bool inYearRange(DateTime date) { return _checkDate( min, @@ -57,6 +66,7 @@ class DateTimeConstraint { ); } + /// Strips the given date to date only (no time information). DateTime _stripToDateOnly(DateTime date) { return DateTime( date.year, @@ -65,6 +75,7 @@ class DateTimeConstraint { ); } + /// Strips the given date to month only. DateTime _stripToMonthsOnly(DateTime date) { return DateTime( date.year, @@ -73,6 +84,7 @@ class DateTimeConstraint { ); } + /// Strips the given date to year only. DateTime _stripToYearsOnly(DateTime date) { return DateTime( date.year, @@ -81,6 +93,7 @@ class DateTimeConstraint { ); } + /// Checks if the date constraint is met. bool _checkDate(DateConstraint constraint, bool Function() checker) { if (!constraint.isInfinite) { return checker(); @@ -89,12 +102,19 @@ class DateTimeConstraint { } } +/// Class representing a date constraint. class DateConstraint { + /// Date constraint representing infinity. static const DateConstraint infinity = DateConstraint(date: null, isInfinite: true); + + /// The date associated with the constraint. final DateTime? date; + + /// Indicates if the constraint is infinite. final bool isInfinite; + /// Constructs a DateConstraint instance. const DateConstraint({this.date, this.isInfinite = false}) : assert( !(date != null && isInfinite), diff --git a/lib/src/overlay_date_time_picker.dart b/lib/src/overlay_date_time_picker.dart index 27c0369..835baf3 100644 --- a/lib/src/overlay_date_time_picker.dart +++ b/lib/src/overlay_date_time_picker.dart @@ -10,7 +10,10 @@ import 'package:flutter_date_time_picker/src/models/date_constraint.dart'; import 'package:flutter_date_time_picker/src/widgets/overlay_date_time_picker/overlay.dart'; import 'package:intl/date_symbol_data_local.dart'; +/// `OverlayDateTimePicker` is a StatefulWidget that represents a date time picker overlay. +/// It provides a way to select a date and time from an overlay that can be positioned relative to other widgets. class OverlayDateTimePicker extends StatefulWidget { + /// Creates a new instance of `OverlayDateTimePicker`. const OverlayDateTimePicker({ this.theme = const DateTimePickerTheme(), this.textStyle = const TextStyle(), diff --git a/lib/src/utils/date_time_picker_config.dart b/lib/src/utils/date_time_picker_config.dart index 0866b38..bde7294 100644 --- a/lib/src/utils/date_time_picker_config.dart +++ b/lib/src/utils/date_time_picker_config.dart @@ -5,7 +5,10 @@ import 'package:flutter/material.dart'; import 'package:flutter_date_time_picker/flutter_date_time_picker.dart'; +/// `DateTimePickerConfiguration` is a class that holds the configuration for a DateTimePicker. +/// It provides various options to customize the behavior and appearance of the DateTimePicker. class DateTimePickerConfiguration { + /// Creates a new instance of `DateTimePickerConfiguration`. DateTimePickerConfiguration({ required this.theme, this.pickTime = false, diff --git a/lib/src/utils/date_time_picker_controller.dart b/lib/src/utils/date_time_picker_controller.dart index 0bd3055..1bbaf6e 100644 --- a/lib/src/utils/date_time_picker_controller.dart +++ b/lib/src/utils/date_time_picker_controller.dart @@ -4,51 +4,56 @@ import 'package:flutter/material.dart'; +/// Controller for managing date and time selection. class DateTimePickerController extends ChangeNotifier { + /// Callback that provides the date tapped on as a [DateTime] object. + final Function(DateTime)? onTapDayCallBack; + + /// Callback triggered when the date scrolls to the border. + final Function(DateTime)? onBorderScrollCallback; + + /// Initial date. + final DateTime initialDate; + + /// Page controller for managing the date selection. + final PageController _pageController = PageController(initialPage: 1); + + /// The currently browsed date. + late DateTime browsingDate = initialDate; + + /// The selected date. + late DateTime selectedDate = initialDate; + + /// Constructs a DateTimePickerController. DateTimePickerController({ required this.initialDate, this.onTapDayCallBack, this.onBorderScrollCallback, }); - /// Callback that provides the date tapped on as a [DateTime] object. - final Function(DateTime)? onTapDayCallBack; - - /// Callback that provides the new date which is scroll to. If this is null the scroll feature is disabled. - final Function(DateTime)? onBorderScrollCallback; - - final DateTime initialDate; - - final PageController _pageController = PageController(initialPage: 1); - - late DateTime browsingDate = initialDate; - late DateTime selectedDate = initialDate; - @override void dispose() { _pageController.dispose(); super.dispose(); } + /// Callback for page change. void onPageChanged(DateTime date) { Future.delayed( const Duration(milliseconds: 250), () { browsingDate = date; - notifyListeners(); - _pageController.jumpToPage(1); }, ); } + /// Callback for tapping a day. void onTapDay(DateTime date) { browsingDate = date; selectedDate = date; - notifyListeners(); - if (onTapDayCallBack != null) { onTapDayCallBack!.call( date, @@ -56,24 +61,24 @@ class DateTimePickerController extends ChangeNotifier { } } + /// Callback for scrolling to the border. void onBorderScroll(DateTime date) { browsingDate = date; selectedDate = date; - notifyListeners(); - - onBorderScrollCallback?.call( - date, - ); + onBorderScrollCallback?.call(date); } + /// Retrieves the page controller. PageController get pageController => _pageController; + /// Sets the browsing date. void setBrowsingDate(DateTime date) { browsingDate = date; notifyListeners(); } + /// Sets the selected date. void setSelectedDate(DateTime date) { selectedDate = date; notifyListeners(); diff --git a/lib/src/utils/locking_page_scroll_physics.dart b/lib/src/utils/locking_page_scroll_physics.dart index b21503a..9ee5a7f 100644 --- a/lib/src/utils/locking_page_scroll_physics.dart +++ b/lib/src/utils/locking_page_scroll_physics.dart @@ -4,10 +4,15 @@ import 'package:flutter/material.dart'; +/// Custom scroll physics for locking page scroll. class LockingPageScrollPhysics extends ScrollPhysics { + /// Function to determine if scrolling to the next page is allowed. final bool Function() allowedNextPage; + + /// Function to determine if scrolling to the previous page is allowed. final bool Function() allowedPreviousPage; + /// Constructs LockingPageScrollPhysics. const LockingPageScrollPhysics({ required this.allowedNextPage, required this.allowedPreviousPage, diff --git a/lib/src/widgets/marked_icon.dart b/lib/src/widgets/marked_icon.dart index a00a763..7277d90 100644 --- a/lib/src/widgets/marked_icon.dart +++ b/lib/src/widgets/marked_icon.dart @@ -1,6 +1,15 @@ import 'package:flutter/material.dart'; +/// `MarkedIcon` is a StatelessWidget that represents a marked icon. +/// It provides a colored circular icon that can be used to indicate a marked state. class MarkedIcon extends StatelessWidget { + /// Creates a new instance of `MarkedIcon`. + /// + /// The [width] and [height] parameters must not be null. + /// + /// * [width]: The width of the icon. + /// * [height]: The height of the icon. + /// * [color]: The color of the icon. If null, the indicator color from the current theme is used. const MarkedIcon({ super.key, this.color, diff --git a/lib/src/widgets/month_date_time_picker/month_date_time_picker.dart b/lib/src/widgets/month_date_time_picker/month_date_time_picker.dart index c7f5698..9406190 100644 --- a/lib/src/widgets/month_date_time_picker/month_date_time_picker.dart +++ b/lib/src/widgets/month_date_time_picker/month_date_time_picker.dart @@ -13,7 +13,10 @@ import 'package:flutter_date_time_picker/src/utils/date_time_picker_controller.d import 'package:flutter_date_time_picker/src/widgets/marked_icon.dart'; import 'package:intl/intl.dart'; +/// `MonthDateTimePicker` is a StatelessWidget that represents a picker for a date within a month. +/// It provides a grid of dates for the month and allows the user to select a date. class MonthDateTimePicker extends StatelessWidget { + /// Creates a new instance of `MonthDateTimePicker`. const MonthDateTimePicker({ required this.date, required this.dateTimePickerController, @@ -22,11 +25,18 @@ class MonthDateTimePicker extends StatelessWidget { Key? key, }) : super(key: key); + /// The date of the month to display. final DateTime date; + + /// The controller for managing date and time selection. final DateTimePickerController dateTimePickerController; - final DateTimePickerConfiguration dateTimePickerConfiguration; + + /// The size of each date box in the month grid. final double monthDateBoxSize; + /// The configuration for the date and time picker. + final DateTimePickerConfiguration dateTimePickerConfiguration; + @override Widget build(BuildContext context) { int daysToSkip = DateTime( diff --git a/lib/src/widgets/month_date_time_picker/month_date_time_picker_sheet.dart b/lib/src/widgets/month_date_time_picker/month_date_time_picker_sheet.dart index a0bca2b..ba815ec 100644 --- a/lib/src/widgets/month_date_time_picker/month_date_time_picker_sheet.dart +++ b/lib/src/widgets/month_date_time_picker/month_date_time_picker_sheet.dart @@ -9,7 +9,10 @@ import 'package:flutter_date_time_picker/src/utils/date_time_picker_controller.d import 'package:flutter_date_time_picker/src/widgets/month_date_time_picker/month_date_time_picker.dart'; import 'package:intl/intl.dart'; +/// `MonthDateTimePickerSheet` is a StatelessWidget that represents a sheet for picking a date within a month. +/// It provides a grid of dates for the month and allows the user to select a date. class MonthDateTimePickerSheet extends StatelessWidget { + /// Creates a new instance of `MonthDateTimePickerSheet`. const MonthDateTimePickerSheet({ required this.dateTimePickerController, required this.dateTimePickerConfiguration, @@ -18,9 +21,16 @@ class MonthDateTimePickerSheet extends StatelessWidget { super.key, }); + /// The controller for managing date and time selection. final DateTimePickerController dateTimePickerController; + + /// The configuration for the date and time picker. final DateTimePickerConfiguration dateTimePickerConfiguration; + + /// The size of the month date box. final double monthDateBoxSize; + + /// The padding around the month date. final EdgeInsetsGeometry monthDatePadding; @override @@ -40,9 +50,8 @@ class MonthDateTimePickerSheet extends StatelessWidget { padding: monthDatePadding, child: Text( // use localization to get the month name - DateFormat.yMMMM(Localizations.localeOf(context).toString()).format( - dateTimePickerController.browsingDate, - ), + DateFormat.yMMMM(Localizations.localeOf(context).toString()) + .format(dateTimePickerController.browsingDate), style: theme.baseTheme.textStyle!.copyWith(fontSize: 25), ), ), @@ -87,26 +96,28 @@ class MonthDateTimePickerSheet extends StatelessWidget { dateTimePickerConfiguration: dateTimePickerConfiguration, ), MonthDateTimePicker( - date: DateTime( - dateTimePickerController.browsingDate.year, - dateTimePickerController.browsingDate.month, - 1, - ), - dateTimePickerController: dateTimePickerController, - dateTimePickerConfiguration: dateTimePickerConfiguration, - monthDateBoxSize: monthDateBoxSize), + date: DateTime( + dateTimePickerController.browsingDate.year, + dateTimePickerController.browsingDate.month, + 1, + ), + dateTimePickerController: dateTimePickerController, + dateTimePickerConfiguration: dateTimePickerConfiguration, + monthDateBoxSize: monthDateBoxSize, + ), MonthDateTimePicker( - date: dateTimePickerController.browsingDate.month == 12 - ? DateTime( - dateTimePickerController.browsingDate.year + 1, - 1, - 1, - ) - : DateTime(dateTimePickerController.browsingDate.year, - dateTimePickerController.browsingDate.month + 1, 1), - dateTimePickerController: dateTimePickerController, - dateTimePickerConfiguration: dateTimePickerConfiguration, - monthDateBoxSize: monthDateBoxSize), + date: dateTimePickerController.browsingDate.month == 12 + ? DateTime( + dateTimePickerController.browsingDate.year + 1, + 1, + 1, + ) + : DateTime(dateTimePickerController.browsingDate.year, + dateTimePickerController.browsingDate.month + 1, 1), + dateTimePickerController: dateTimePickerController, + dateTimePickerConfiguration: dateTimePickerConfiguration, + monthDateBoxSize: monthDateBoxSize, + ), ], ), ), diff --git a/lib/src/widgets/overlay_date_time_picker/date_picker.dart b/lib/src/widgets/overlay_date_time_picker/date_picker.dart index add7b0a..269fea1 100644 --- a/lib/src/widgets/overlay_date_time_picker/date_picker.dart +++ b/lib/src/widgets/overlay_date_time_picker/date_picker.dart @@ -8,7 +8,10 @@ import 'package:flutter_date_time_picker/src/extensions/date_time.dart'; import 'package:flutter_date_time_picker/src/widgets/overlay_date_time_picker/pickable_date.dart'; import 'package:intl/intl.dart'; +/// `DatePicker` is a StatelessWidget that represents a date picker. +/// It provides a way to select a date from a calendar-like interface. class DatePicker extends StatelessWidget { + /// Creates a new instance of `DatePicker`. const DatePicker({ super.key, required this.controller, @@ -21,13 +24,28 @@ class DatePicker extends StatelessWidget { required this.dateTimeConstraint, }); + /// The controller for managing date selection. final DateTimePickerController controller; + + /// The configuration for the date picker. final DateTimePickerConfiguration configuration; + + /// The theme for the date picker. final DateTimePickerTheme theme; + + /// The text style for displaying the weekday names. final TextStyle weekdayTextStyle; + + /// Callback function invoked when a date is selected. final void Function(DateTime date) onSelectDate; + + /// The date to display in the picker. final DateTime date; + + /// Whether to show the weekday names. final bool showWeekDays; + + /// The constraint for selecting dates. final DateTimeConstraint dateTimeConstraint; @override diff --git a/lib/src/widgets/overlay_date_time_picker/overlay.dart b/lib/src/widgets/overlay_date_time_picker/overlay.dart index 3c7c3b8..57e5608 100644 --- a/lib/src/widgets/overlay_date_time_picker/overlay.dart +++ b/lib/src/widgets/overlay_date_time_picker/overlay.dart @@ -11,7 +11,10 @@ import 'package:flutter_date_time_picker/src/widgets/overlay_date_time_picker/da import 'package:flutter_date_time_picker/src/models/date_constraint.dart'; import 'package:intl/intl.dart'; +/// `OverlayDateTimeContent` is a StatefulWidget that represents the content of a date time overlay. +/// It provides a way to select a date and navigate between dates within the overlay. class OverlayDateTimeContent extends StatefulWidget { + /// Creates a new instance of `OverlayDateTimeContent`. const OverlayDateTimeContent({ super.key, required this.theme, @@ -28,19 +31,40 @@ class OverlayDateTimeContent extends StatefulWidget { this.extraWidgetBuilder, }); + /// The theme for the date time picker. final DateTimePickerTheme theme; + + /// The text style for displaying the weekday names. final TextStyle weekdayTextStyle; + + /// The size of the content. final Size size; + + /// The controller for managing date selection. final DateTimePickerController controller; + + /// The configuration for the date time picker. final DateTimePickerConfiguration configuration; + + /// Whether to show the weekday names. final bool showWeekDays; + + /// The constraint for selecting dates. final DateTimeConstraint dateTimeConstraint; + /// A widget builder for adding an extra widget. final Widget? extraWidgetBuilder; + + /// A function to provide the next page button. final Widget Function(void Function()? onPressed)? onNextPageButtonChild; + + /// A function to provide the previous page button. final Widget Function(void Function()? onPressed)? onPreviousPageButtonChild; + /// Callback function invoked when moving to the next date. final void Function() onNextDate; + + /// Callback function invoked when moving to the previous date. final void Function() onPreviousDate; @override diff --git a/lib/src/widgets/overlay_date_time_picker/pickable_date.dart b/lib/src/widgets/overlay_date_time_picker/pickable_date.dart index bd51b37..186af7c 100644 --- a/lib/src/widgets/overlay_date_time_picker/pickable_date.dart +++ b/lib/src/widgets/overlay_date_time_picker/pickable_date.dart @@ -6,7 +6,21 @@ import 'package:flutter/material.dart'; import 'package:flutter_date_time_picker/flutter_date_time_picker.dart'; import 'package:flutter_date_time_picker/src/widgets/marked_icon.dart'; +/// `PickableDate` is a StatelessWidget that represents a selectable date. +/// It provides visual feedback based on its state (marked, selected, disabled, etc.). class PickableDate extends StatelessWidget { + /// Creates a new instance of `PickableDate`. + /// + /// The [isMarked], [isSelected], [isDisabled], [isToday], [isOffMonth], [date], [theme], and [onPressed] parameters must not be null. + /// + /// * [isMarked]: Indicates whether the date is marked. + /// * [isSelected]: Indicates whether the date is selected. + /// * [isDisabled]: Indicates whether the date is disabled. + /// * [isToday]: Indicates whether the date is the current date. + /// * [isOffMonth]: Indicates whether the date is in the off-month. + /// * [date]: The date that this widget represents. + /// * [theme]: The theme used for styling the widget. + /// * [onPressed]: The callback that is called when the date is pressed. const PickableDate({ super.key, required this.isMarked, diff --git a/lib/src/widgets/week_date_time_picker/week_date_time_picker.dart b/lib/src/widgets/week_date_time_picker/week_date_time_picker.dart index bc52789..d504bb1 100644 --- a/lib/src/widgets/week_date_time_picker/week_date_time_picker.dart +++ b/lib/src/widgets/week_date_time_picker/week_date_time_picker.dart @@ -10,7 +10,17 @@ import 'package:flutter_date_time_picker/src/models/date_box_current_theme.dart' import 'package:flutter_date_time_picker/src/widgets/marked_icon.dart'; import 'package:intl/intl.dart'; +/// `WeekDateTimePicker` is a StatelessWidget that represents a picker for a date within a week. +/// It provides a row of dates for the week and allows the user to select a date. class WeekDateTimePicker extends StatelessWidget { + /// Creates a new instance of `WeekDateTimePicker`. + /// + /// The [dateTimePickerController], [dateTimePickerConfiguration], [date], and [weekDateBoxSize] parameters must not be null. + /// + /// * [dateTimePickerController]: The controller for the date time picker. + /// * [dateTimePickerConfiguration]: The configuration for the date time picker. + /// * [date]: The date that this widget represents. + /// * [weekDateBoxSize]: The size of the box for each date in the week. const WeekDateTimePicker({ required this.dateTimePickerController, required this.dateTimePickerConfiguration, diff --git a/lib/src/widgets/week_date_time_picker/week_date_time_picker_sheet.dart b/lib/src/widgets/week_date_time_picker/week_date_time_picker_sheet.dart index c1d7538..b7f5661 100644 --- a/lib/src/widgets/week_date_time_picker/week_date_time_picker_sheet.dart +++ b/lib/src/widgets/week_date_time_picker/week_date_time_picker_sheet.dart @@ -9,7 +9,17 @@ import 'package:flutter_date_time_picker/src/utils/date_time_picker_controller.d import 'package:flutter_date_time_picker/src/widgets/week_date_time_picker/week_date_time_picker.dart'; import 'package:intl/intl.dart'; +/// `WeekDateTimePickerSheet` is a StatelessWidget that represents a sheet for picking a date within a week. +/// It provides a header showing the date range for the current week and a PageView of `WeekDateTimePicker` widgets for the previous, current, and next week. class WeekDateTimePickerSheet extends StatelessWidget { + /// Creates a new instance of `WeekDateTimePickerSheet`. + /// + /// The [dateTimePickerController], [dateTimePickerConfiguration], and [weekDateBoxSize] parameters must not be null. + /// + /// * [dateTimePickerController]: The controller for the date time picker. + /// * [dateTimePickerConfiguration]: The configuration for the date time picker. + /// * [weekDateBoxSize]: The size of the box for each date in the week. + /// * [showHeader]: Whether to show the header with the date range for the current week. Defaults to false. const WeekDateTimePickerSheet({ required this.dateTimePickerController, required this.dateTimePickerConfiguration,