all: fixup doc config, use categories

dartdoc_options.yaml

@@ -7,16 +7,19 @@ dartdoc:
   warnings:
     - tool-error
   categories:
-    Flume:
-      markdown: doc/flume.md
-      name: Flume
     Foundation:
       markdown: doc/foundation.md
       name: Foundation
     Components:
       markdown: doc/components.md
       name: Components
-  categoryOrder: [Flume, Foundation, Components]
+    Ambiance:
+      markdown: doc/ambiance.md
+      name: Ambiance
+    Tools:
+      markdown: doc/tools.md
+      name: Tools
+  categoryOrder: [Foundation, Components, Ambiance, Tools]
   examplePathPrefix: example/
   showUndocumentedCategories: true
   favicon: assets/docs/favicon.ico

doc/components.md

@@ -1 +1,3 @@
 # Components
+
+The component library consists of various Flume component implementations as well as utilities and convenience tools for effectively implementing Flume in any Flutter application.

doc/tools.md

@@ -0,0 +1,5 @@
+# Tools
+
+Tools and utilities for streamlining development processes.
+
+Contains programs and scripts for e.g. fetching remote assets.

example/pubspec.lock

@@ -134,10 +134,10 @@ packages:
     dependency: transitive
     description:
       name: meta
-      sha256: "6c268b42ed578a53088d834796959e4a1814b5e9e164f147f580a386e5decf42"
+      sha256: "12307e7f0605ce3da64cf0db90e5fcab0869f3ca03f76be6bb2991ce0a55e82b"
       url: "https://pub.dev"
     source: hosted
-    version: "1.8.0"
+    version: "1.9.0"
   nested:
     dependency: transitive
     description:

lib/src/ambiance/algorithm/luminance.dart

@@ -5,7 +5,7 @@ const maxIter = 20;
 
 // In-memory cache of luminance values to avoid
 // expensive re-compute.
-final lumCache = <Color, Color>{};
+final _lumCache = <Color, Color>{};
 
 /// {@category Ambiance}
 /// Extension on [Color] to get luminance values.
@@ -42,7 +42,7 @@ extension LuminanceExtension on Color {
     final result = rgb.withOpacity(opacity);
 
     // Cache the result.
-    lumCache[this] = result;
+    _lumCache[this] = result;
 
     return result;
   }

lib/src/ambiance/extensions.dart

@@ -1,6 +1,8 @@
 import 'package:flume/src/ambiance.dart';
 import 'package:flutter/widgets.dart';
 
+/// {@category Ambiance}
+/// {@subCategory Extensions}
 extension AmbianceExtension on BuildContext {
   AmbianceState get ambiance => Ambiance.of(this);
 }

lib/src/ambiance/widgets/ambiance.dart

@@ -1,6 +1,9 @@
 import 'package:flume/flume.dart';
 import 'package:flutter/widgets.dart';
 
+/// {@category Ambiance}
+/// {@subCategory Widgets}
+/// A data class that holds the current [Ambiance] state.
 class AmbianceState {
   final AmbiancePalette palette;
   final Color color;
@@ -21,6 +24,9 @@ class AmbianceState {
   });
 }
 
+/// {@category Ambiance}
+/// {@subCategory Widgets}
+/// A widget that provides the current [AmbianceState] to its descendants.
 class Ambiance extends StatelessWidget {
   final Color? source;
   final Color? color;
@@ -81,7 +87,7 @@ class Ambiance extends StatelessWidget {
 
     return AmbianceProvider(
       state: state,
-      child: Proxy(
+      child: _Proxy(
         builder: (ctx) {
           return child ?? builder!(ctx, state);
         },
@@ -90,9 +96,9 @@ class Ambiance extends StatelessWidget {
   }
 }
 
-class Proxy extends StatelessWidget {
+class _Proxy extends StatelessWidget {
   final Widget Function(BuildContext) builder;
-  const Proxy({super.key, required this.builder});
+  const _Proxy({required this.builder});
 
   @override
   Widget build(BuildContext context) {
@@ -102,6 +108,9 @@ class Proxy extends StatelessWidget {
 
 Map<Color, AmbiancePalette> _computedPalettes = {};
 
+/// {@category Ambiance}
+/// {@subCategory Functions}
+/// A function that returns an [AmbiancePalette] from a given [Color].
 AmbiancePalette getPaletteFromColor(Color color) {
   if (_computedPalettes.containsKey(color)) {
     return _computedPalettes[color]!;
@@ -110,6 +119,10 @@ AmbiancePalette getPaletteFromColor(Color color) {
   }
 }
 
+/// {@category Ambiance}
+/// {@subCategory Functions}
+/// A function that returns a [Color] from the given [color]'s ambiance palette
+/// given the [elevation].
 Color getColorFromElevation(Color color, int elevation) {
   AmbiancePalette palette;
 

lib/src/ambiance/widgets/provider.dart

@@ -1,7 +1,14 @@
 import 'package:flume/src/ambiance.dart';
 import 'package:flutter/widgets.dart';
 
+/// {@category Ambiance}
+/// {@subCategory Types}
+/// A callback that returns a [Color].
 typedef ColorCallback = Color Function();
+
+/// {@category Ambiance}
+/// {@subCategory Types}
+/// A callback that takes an [int] argument and returns a [Color].
 typedef ColorCallbackWithArg = Color Function(int);
 
 /// {@category Foundation}

lib/src/components/buttons/button.dart

@@ -2,6 +2,8 @@ import 'package:flume/flume.dart';
 import 'package:flutter/gestures.dart';
 import 'package:flutter/material.dart';
 
+/// {@category Components}
+/// {@subCategory Buttons}
 class Button extends StatefulWidget {
   /// The size of the button.
   final ButtonSize size;

lib/src/components/buttons/flat_button.dart

@@ -2,6 +2,10 @@ import 'package:flume/flume.dart';
 import 'package:flutter/gestures.dart';
 import 'package:flutter/material.dart';
 
+/// {@category Components}
+/// {@subCategory Buttons}
+/// A flat button is a button that has a "flat" appearance, meaning it looks
+/// like regular text, but has some button states and capabilities.
 class FlatButton extends StatefulWidget {
   /// Optional state to override the default initial state.
   final ButtonState? state;

lib/src/components/buttons/icon_button.dart

@@ -3,6 +3,10 @@ import 'package:flutter/gestures.dart';
 import 'package:flutter/material.dart';
 
 // TODO: Rename. "SymbolButton" is just a placeholder name to avoid conflicts with Material's "IconButton".
+
+/// {@category Components}
+/// {@subCategory Buttons}
+/// A button that displays an icon.
 class SymbolButton extends StatefulWidget {
   /// The size of the button.
   final ButtonSize size;

lib/src/components/buttons/shared.dart

@@ -1,21 +1,33 @@
+/// {@category Components}
+/// {@subCategory Buttons}
+/// The size of a button.
 enum ButtonSize {
   medium,
   large,
   expand,
 }
 
+/// {@category Components}
+/// {@subCategory Buttons}
+/// The variant of a button.
 enum ButtonVariant {
   primary,
   tonal,
   signal,
   light,
 }
 
+/// {@category Components}
+/// {@subCategory Buttons}
+/// The variant of a [ToggleButton].
 enum ToggleButtonVariant {
   standard,
   tonal,
 }
 
+/// {@category Components}
+/// {@subCategory Buttons}
+/// The state of a button.
 enum ButtonState {
   normal,
   hover,
@@ -25,6 +37,9 @@ enum ButtonState {
   loading,
 }
 
+/// {@category Components}
+/// {@subCategory Buttons}
+/// The position of an icon in a button, relative to its child widget.
 enum IconPosition {
   left,
   right,

lib/src/components/buttons/toggle_button.dart

@@ -2,6 +2,9 @@ import 'package:flume/flume.dart';
 import 'package:flutter/gestures.dart';
 import 'package:flutter/material.dart';
 
+/// {@category Components}
+/// {@subCategory Buttons}
+/// A button that can be toggled on and off.
 class ToggleButton extends StatefulWidget {
   /// The variant of the button.
   final ToggleButtonVariant variant;

lib/src/components/extensions/context.dart

@@ -2,7 +2,7 @@ import 'package:flume/flume.dart';
 import 'package:flutter/material.dart';
 
 /// {@category Components}
-/// {@subCategory extensions}
+/// {@subCategory Extensions}
 /// Quality-of-life extensions on [BuildContext].
 extension FlumeContextExtension on BuildContext {
   /// If the current context brightness is [Brightness.light].

lib/src/components/icons.dart

@@ -14,6 +14,8 @@ class _FlumeIconsData extends IconData {
   final String name;
 }
 
+/// {@category Components}
+/// {@subCategory Icons}
 @immutable
 class FlumeIcons {
   const FlumeIcons._();

lib/src/components/input/form_group.dart

@@ -1,6 +1,9 @@
 import 'package:flume/flume.dart';
 import 'package:flutter/material.dart';
 
+/// {@category Components}
+/// {@subCategory Input}
+/// A widget that groups a [label] and [child] together.
 class FormGroup extends StatelessWidget {
   const FormGroup({
     super.key,

lib/src/components/input/input_field.dart

@@ -81,7 +81,9 @@ class InputField extends StatefulWidget {
   /// {@endtemplate}
   final VoidCallback? onEditingComplete;
 
-  /// {@macro flume.gestures.onTap}
+  /// {@template flume.gestures.onTap}
+  /// Callback function invoked when the widget has received a tap gesture.
+  /// {@endtemplate}
   final VoidCallback? onTap;
 
   /// {@template flume.components.input.controller}
@@ -99,7 +101,10 @@ class InputField extends StatefulWidget {
   /// the error text to display.
   final String? Function(String?)? validator;
 
-  /// {@macro flume.gestures.onChanged}
+  /// {@template flume.gestures.onChanged}
+  /// Callback function that is called when the [controller] text changes. Passes the
+  /// updated value as a parameter.
+  /// {@endtemplate}
   final Function(String)? onChanged;
 
   /// {@template flume.gestures.onFieldSubmitted}

lib/src/components/input/search_bar.dart

@@ -1,6 +1,9 @@
 import 'package:flume/flume.dart';
 import 'package:flutter/material.dart';
 
+/// {@category Components}
+/// {@subCategory Input}
+/// A widget that displays a search bar.
 class SearchBar extends StatefulWidget {
   const SearchBar({
     super.key,

lib/src/components/input/tonal_switch.dart

@@ -4,6 +4,10 @@ import 'package:flume/flume.dart';
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 
+/// {@category Components}
+/// {@subCategory Input}
+/// A widget that displays a switch that adapts to the current platform, and
+/// uses the current [Ambiance] to determine its colors.
 class TonalSwitch extends StatelessWidget {
   const TonalSwitch({super.key, required this.value, required this.onChanged});
 

lib/src/components/input/validation_message.dart

@@ -1,12 +1,18 @@
 import 'package:flume/flume.dart';
 import 'package:flutter/material.dart';
 
+/// {@category Components}
+/// {@subCategory Input}
+/// The state of a validation message.
 enum ValidationState {
   success,
   warning,
   error,
 }
 
+/// {@category Components}
+/// {@subCategory Input}
+/// A widget that displays a validation message.
 class ValidationMessage extends StatelessWidget {
   final ValidationState state;
   final Widget child;

lib/src/components/lists/cell.dart

@@ -2,7 +2,7 @@ import 'package:flume/flume.dart';
 import 'package:flutter/material.dart';
 
 /// {@category Components}
-/// {@subCategory List}
+/// {@subCategory Lists}
 /// A list cell from the Flume design system.
 class Cell extends StatefulWidget {
   /// A widget on the left-hand side of this [Cell]'s title.

lib/src/components/lists/extensions.dart

@@ -1,7 +1,7 @@
 import 'package:flutter/material.dart';
 
-/// {@category Spacing}
-/// {@macro flume.extension}
+/// {@category Components}
+/// {@subCategory Spacing}
 extension WidgetIterableExtension on Iterable<Widget> {
   List<Widget> spaced(double? space) {
     if (isEmpty) {