From 1e6febb74ee15dd253fd900697c993e4ae7c4c0f Mon Sep 17 00:00:00 2001 From: Nikolas Rimikis Date: Thu, 26 Oct 2023 08:15:19 +0200 Subject: [PATCH] docs(neon): document exported widgets Signed-off-by: Nikolas Rimikis --- .../neon/lib/src/widgets/account_tile.dart | 26 ++++++++++++++ .../neon/neon/lib/src/widgets/app_bar.dart | 6 ++++ .../src/widgets/app_implementation_icon.dart | 34 +++++++++++++++++++ .../neon/neon/lib/src/widgets/dialog.dart | 13 +++++++ .../neon/neon/lib/src/widgets/drawer.dart | 11 ++++++ .../widgets/linear_progress_indicator.dart | 11 ++++++ .../neon/lib/src/widgets/user_avatar.dart | 14 ++++++++ .../neon/lib/src/widgets/validation_tile.dart | 18 ++++++++++ 8 files changed, 133 insertions(+) diff --git a/packages/neon/neon/lib/src/widgets/account_tile.dart b/packages/neon/neon/lib/src/widgets/account_tile.dart index 20f0e185..3602f095 100644 --- a/packages/neon/neon/lib/src/widgets/account_tile.dart +++ b/packages/neon/neon/lib/src/widgets/account_tile.dart @@ -10,8 +10,10 @@ import 'package:neon/src/widgets/linear_progress_indicator.dart'; import 'package:neon/src/widgets/user_avatar.dart'; import 'package:nextcloud/provisioning_api.dart' as provisioning_api; +/// List tile to display account information. @internal class NeonAccountTile extends StatelessWidget { + /// Creates a new account list tile. const NeonAccountTile({ required this.account, this.trailing, @@ -20,9 +22,33 @@ class NeonAccountTile extends StatelessWidget { super.key, }); + /// {@template neon.AccountTile.account} + /// The account to display inside the tile. + /// {@endtemplate} final Account account; + + /// {@template neon.AccountTile.trailing} + /// A widget to display after the title. + /// + /// Typically an [Icon] widget. + /// + /// To show right-aligned metadata (assuming left-to-right reading order; + /// left-aligned for right-to-left reading order), consider using a [Row] with + /// [CrossAxisAlignment.baseline] alignment whose first item is [Expanded] and + /// whose second child is the metadata text, instead of using the [trailing] + /// property. + /// {@endtemplate} final Widget? trailing; + + /// {@template neon.AccountTile.onTap} + /// Called when the user taps this list tile. + /// {@endtemplate} final GestureTapCallback? onTap; + + /// Whether to also show the status on the avatar. + /// + /// See: + /// * [NeonUserAvatar.showStatus] final bool showStatus; @override diff --git a/packages/neon/neon/lib/src/widgets/app_bar.dart b/packages/neon/neon/lib/src/widgets/app_bar.dart index 9482beff..d5fccfd5 100644 --- a/packages/neon/neon/lib/src/widgets/app_bar.dart +++ b/packages/neon/neon/lib/src/widgets/app_bar.dart @@ -17,8 +17,10 @@ import 'package:neon/src/widgets/linear_progress_indicator.dart'; import 'package:provider/provider.dart'; import 'package:rxdart/rxdart.dart'; +/// Global app bar for the Neon app. @internal class NeonAppBar extends StatefulWidget implements PreferredSizeWidget { + /// Creates a new Neon app bar. const NeonAppBar({super.key}); @override @@ -149,8 +151,10 @@ class _NeonAppBarState extends State { ); } +/// Button opening the unified search page. @internal class SearchIconButton extends StatelessWidget { + /// Creates a new unified search button. const SearchIconButton({ super.key, }); @@ -167,8 +171,10 @@ class SearchIconButton extends StatelessWidget { ); } +/// Button opening the notifications page. @internal class NotificationIconButton extends StatefulWidget { + /// Creates a new notifications button. const NotificationIconButton({ super.key, }); diff --git a/packages/neon/neon/lib/src/widgets/app_implementation_icon.dart b/packages/neon/neon/lib/src/widgets/app_implementation_icon.dart index f8c83072..b4cb30e3 100644 --- a/packages/neon/neon/lib/src/widgets/app_implementation_icon.dart +++ b/packages/neon/neon/lib/src/widgets/app_implementation_icon.dart @@ -2,8 +2,10 @@ import 'package:flutter/material.dart'; import 'package:meta/meta.dart'; import 'package:neon/src/models/app_implementation.dart'; +/// An icon widget displaying the app icon of a client with an overlay displaying the [unreadCount]. @internal class NeonAppImplementationIcon extends StatelessWidget { + /// Creates a new app implementation icon. const NeonAppImplementationIcon({ required this.appImplementation, this.unreadCount, @@ -12,12 +14,44 @@ class NeonAppImplementationIcon extends StatelessWidget { super.key, }); + /// The client for which to build the icon. + /// + /// Uses [AppImplementation.buildIcon] for the icon data. final AppImplementation appImplementation; + /// The number of unread notifications. final int? unreadCount; + /// The color to use when drawing the icon. + /// + /// Defaults to the nearest [IconTheme]'s [IconThemeData.color]. + /// + /// The color (whether specified explicitly here or obtained from the + /// [IconTheme]) will be further adjusted by the nearest [IconTheme]'s + /// [IconThemeData.opacity]. + /// + /// {@tool snippet} + /// Typically, a Material Design color will be used, as follows: + /// + /// ```dart + /// Icon( + /// Icons.widgets, + /// color: Colors.blue.shade400, + /// ) + /// ``` + /// {@end-tool} final Color? color; + /// The size of the icon in logical pixels. + /// + /// Icons occupy a square with width and height equal to size. + /// + /// Defaults to the nearest [IconTheme]'s [IconThemeData.size]. + /// + /// If this [NeonAppImplementationIcon] is being placed inside an [IconButton], + /// then use [IconButton.iconSize] instead, so that the [IconButton] can make + /// the splash area the appropriate size as well. The [IconButton] uses an + /// [IconTheme] to pass down the size to the [NeonAppImplementationIcon]. final double? size; @override diff --git a/packages/neon/neon/lib/src/widgets/dialog.dart b/packages/neon/neon/lib/src/widgets/dialog.dart index 88dba87d..1c6be14a 100644 --- a/packages/neon/neon/lib/src/widgets/dialog.dart +++ b/packages/neon/neon/lib/src/widgets/dialog.dart @@ -1,13 +1,26 @@ import 'package:flutter/material.dart'; +/// A Neon material design dialog based on [SimpleDialog]. class NeonDialog extends StatelessWidget { + /// Creates a Neon dialog. + /// + /// Typically used in conjunction with [showDialog]. const NeonDialog({ this.title, this.children, super.key, }); + /// The (optional) title of the dialog is displayed in a large font at the top + /// of the dialog. + /// + /// Typically a [Text] widget. final Widget? title; + + /// The (optional) content of the dialog is displayed in a + /// [SingleChildScrollView] underneath the title. + /// + /// Typically a list of [SimpleDialogOption]s. final List? children; @override diff --git a/packages/neon/neon/lib/src/widgets/drawer.dart b/packages/neon/neon/lib/src/widgets/drawer.dart index a412a894..dae83a81 100644 --- a/packages/neon/neon/lib/src/widgets/drawer.dart +++ b/packages/neon/neon/lib/src/widgets/drawer.dart @@ -15,8 +15,13 @@ import 'package:neon/src/widgets/image.dart'; import 'package:neon/src/widgets/linear_progress_indicator.dart'; import 'package:nextcloud/core.dart' as core; +/// A custom pre populated [Drawer] side panel. +/// +/// Displays an entry for every registered and supported client and one for +/// the settings page. @internal class NeonDrawer extends StatelessWidget { + /// Created a new Neon drawer. const NeonDrawer({ super.key, }); @@ -112,8 +117,14 @@ class __NeonDrawerState extends State<_NeonDrawer> { } } +/// Custom styled [DrawerHeader] used inside a [Drawer] or [NeonDrawer]. +/// +/// The neon drawer will display the [core.ThemingPublicCapabilities_Theming.name] +/// and [core.ThemingPublicCapabilities_Theming.logo] and automatically rebuild +/// when the current theme changes. @internal class NeonDrawerHeader extends StatelessWidget { + /// Creates a new Neon drawer header. const NeonDrawerHeader({super.key}); @override diff --git a/packages/neon/neon/lib/src/widgets/linear_progress_indicator.dart b/packages/neon/neon/lib/src/widgets/linear_progress_indicator.dart index 60901b9b..e25d65c6 100644 --- a/packages/neon/neon/lib/src/widgets/linear_progress_indicator.dart +++ b/packages/neon/neon/lib/src/widgets/linear_progress_indicator.dart @@ -1,6 +1,10 @@ import 'package:flutter/material.dart'; +/// Wrapped [LinearProgressIndicator]. +/// +/// Adds default styling to the [LinearProgressIndicator]. class NeonLinearProgressIndicator extends StatelessWidget { + /// Creates a new Neon styled [LinearProgressIndicator]. const NeonLinearProgressIndicator({ this.visible = true, this.margin = const EdgeInsets.symmetric(horizontal: 10), @@ -9,9 +13,16 @@ class NeonLinearProgressIndicator extends StatelessWidget { super.key, }); + /// Whether the indicator is visible. final bool visible; + + /// Empty space to surround the indicator. final EdgeInsets? margin; + + /// {@macro flutter.progress_indicator.ProgressIndicator.color} final Color? color; + + /// {@macro flutter.material.LinearProgressIndicator.trackColor} final Color? backgroundColor; @override diff --git a/packages/neon/neon/lib/src/widgets/user_avatar.dart b/packages/neon/neon/lib/src/widgets/user_avatar.dart index 4f9ae7ef..63a4b827 100644 --- a/packages/neon/neon/lib/src/widgets/user_avatar.dart +++ b/packages/neon/neon/lib/src/widgets/user_avatar.dart @@ -12,7 +12,9 @@ import 'package:nextcloud/core.dart' as core; import 'package:nextcloud/user_status.dart' as user_status; import 'package:rxdart/rxdart.dart'; +/// A circle that contains the user profile image and status. class NeonUserAvatar extends StatefulWidget { + /// Creates a new Neon user avatar. NeonUserAvatar({ required this.account, final String? username, @@ -23,11 +25,23 @@ class NeonUserAvatar extends StatefulWidget { super.key, }) : username = username ?? account.username; + /// The account used to fetch the image. final Account account; + + /// The user profile to display final String username; + + /// Whether to show the status. final bool showStatus; + + /// The size of the avatar. final double? size; + + /// The color with which to fill the circle. Changing the background + /// color will cause the avatar to animate to the new color. final Color? backgroundColor; + + /// The color used to render the loading animation. final Color? foregroundColor; @override diff --git a/packages/neon/neon/lib/src/widgets/validation_tile.dart b/packages/neon/neon/lib/src/widgets/validation_tile.dart index 62616db1..543688fe 100644 --- a/packages/neon/neon/lib/src/widgets/validation_tile.dart +++ b/packages/neon/neon/lib/src/widgets/validation_tile.dart @@ -1,13 +1,23 @@ import 'package:flutter/material.dart'; +/// Validation list tile. +/// +/// A [ListTile] used to display the progress of a validation. +/// +/// See: +/// * [ValidationState] for the possible states class NeonValidationTile extends StatelessWidget { + /// Creates a new validation list tile. const NeonValidationTile({ required this.title, required this.state, super.key, }); + /// The title of this tile. final String title; + + /// The state to display. final ValidationState state; @override @@ -48,9 +58,17 @@ class NeonValidationTile extends StatelessWidget { } } +/// Validation states for [NeonValidationTile]. enum ValidationState { + /// Indicates a loading state. loading, + + /// Indicates an error. failure, + + /// Indicates the process has been canceled. canceled, + + /// Indicates a success state. success, }