Merge pull request #1032 from nextcloud/doc/neon_widgets

docs(neon): document exported widgets

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

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<NeonAppBar> {
       );
 }
 
+/// 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,
   });

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

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<Widget>? children;
 
   @override

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

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

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

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,
 }