Enhance documentation for Naked UI components: add detailed descriptions, usage examples, and references for better clarity and usability; remove unused overlay content menu.

Author: leoafarias

lib/src/naked_accordion.dart

@@ -9,6 +9,10 @@ import 'package:flutter/widgets.dart';
 /// - `min` prevents closing below a floor when toggling/closing individual items.
 /// - `max` caps the number of expanded items; when exceeded, the *oldest* is closed.
 /// - All operations are idempotent (no redundant notifications).
+///
+/// See also:
+/// - [NakedAccordion], the headless accordion that uses this controller.
+/// - [NakedAccordionItem], the item widget that toggles values via this controller.
 class NakedAccordionController<T> with ChangeNotifier {
   /// Minimum number of expanded items allowed when *closing* via user actions.
   final int min;
@@ -145,6 +149,11 @@ class NakedAccordionScope<T> extends InheritedWidget {
 ///
 /// The [children] should be [NakedAccordionItem<T>] widgets.
 /// State is managed by [NakedAccordionController<T>].
+///
+/// See also:
+/// - [NakedAccordionController], which stores expanded values and enforces
+///   min/max constraints.
+/// - [NakedAccordionItem], which renders the trigger and panel.
 class NakedAccordion<T> extends StatefulWidget {
   const NakedAccordion({
     super.key,
@@ -213,6 +222,10 @@ typedef NakedAccordionTriggerBuilder =
 /// Headless: you provide the trigger visuals and the panel content.
 /// Keyboard: Enter/Space toggle the header (via ActivateIntent).
 /// Semantics: the header is exposed as a "button" with `expanded` state.
+///
+/// See also:
+/// - [NakedAccordion], the container that hosts items and provides traversal.
+/// - [NakedAccordionController], which stores and updates expanded values.
 class NakedAccordionItem<T> extends StatelessWidget {
   const NakedAccordionItem({
     super.key,
@@ -245,8 +258,11 @@ class NakedAccordionItem<T> extends StatelessWidget {
   final T value;
 
   // Interaction hooks (headless state reporting).
+  /// Notifies when header focus changes.
   final ValueChanged<bool>? onFocusChange;
+  /// Notifies when header hover changes.
   final ValueChanged<bool>? onHoverChange;
+  /// Notifies when header pressed (highlight) changes.
   final ValueChanged<bool>? onPressChange;
 
   /// Accessibility label for the header.
@@ -258,7 +274,10 @@ class NakedAccordionItem<T> extends StatelessWidget {
   final bool enableFeedback;
 
   /// Focus configuration for the header.
+  ///
+  /// When [autofocus] is true, the header will request focus on build.
   final bool autofocus;
+  /// External [FocusNode] to control header focus.
   final FocusNode? focusNode;
 
   void _toggle(NakedAccordionController<T> controller) =>

lib/src/naked_button.dart

@@ -1,13 +1,23 @@
 import 'dart:async';
 
-import 'package:flutter/material.dart';
+import 'package:flutter/widgets.dart';
 import 'package:flutter/services.dart';
 
-import 'mixins/naked_mixins.dart'; // your WidgetStatesMixin, etc.
+import 'mixins/naked_mixins.dart'; // WidgetStatesMixin, FocusableMixin
 
-/// Provides button interaction behavior without visual styling.
+/// A headless, focusable button that exposes interaction states.
 ///
-/// Users control presentation and semantics through the child or builder parameter.
+/// - No visuals are provided; pass a [child] or a [builder] to render UI.
+/// - Keyboard: Enter/Space activate the button. Optional [focusOnPress].
+/// - Semantics: exposes a "button" role and supports [tooltip]/[semanticLabel].
+/// - States: when using [builder], you receive a `Set<WidgetState>` that
+///   reflects the current hovered/pressed/focused/disabled states.
+///
+/// See also:
+/// - [NakedMenuItem], which composes a menu item from [NakedButton].
+/// - [FocusableActionDetector], the underlying keyboard/hover integration.
+/// - [TextButton], [ElevatedButton], and [FilledButton] for Material-styled
+///   buttons when you don’t need a headless control.
 class NakedButton extends StatefulWidget {
   const NakedButton({
     super.key,
@@ -32,28 +42,60 @@ class NakedButton extends StatefulWidget {
          'Either child or builder must be provided',
        );
 
+  /// Visual contents of the button when not using [builder].
   final Widget? child;
+
+  /// Called when the button is activated (tap, Enter/Space).
   final VoidCallback? onPressed;
+
+  /// Called when the button is long-pressed.
   final VoidCallback? onLongPress;
+
+  /// Called when the button is double-tapped.
   final VoidCallback? onDoubleTap;
 
+  /// Notifies when focus changes. Receives `true` when focused.
   final ValueChanged<bool>? onFocusChange;
+
+  /// Notifies when hover changes. Receives `true` when hovered.
   final ValueChanged<bool>? onHoverChange;
+
+  /// Notifies when pressed (highlight) changes. Receives `true` when down.
   final ValueChanged<bool>? onPressChange;
 
+  /// Builder that receives the current interaction [WidgetState]s.
+  ///
+  /// The signature is `(BuildContext, Set<WidgetState>, Widget? child)`.
+  /// Use this to render custom visuals based on button state.
   final ValueWidgetBuilder<Set<WidgetState>>? builder;
 
+  /// Whether the button is enabled.
+  ///
+  /// The button is effectively enabled only if [enabled] is true and at least
+  /// one handler among [onPressed], [onLongPress], or [onDoubleTap] is set.
   final bool enabled;
+
+  /// Mouse cursor when the button is enabled.
   final MouseCursor mouseCursor;
+
+  /// Whether to provide platform haptic/aural feedback on activation.
   final bool enableFeedback;
 
+  /// Optional external [FocusNode] to control focus ownership.
   final FocusNode? focusNode;
+
+  /// Whether to autofocus this button on build.
   final bool autofocus;
 
-  /// When true, pressing requests focus in addition to activating.
+  /// Whether pressing requests focus in addition to activating.
   final bool focusOnPress;
 
+  /// Optional tooltip exposed to assistive technologies.
+  ///
+  /// Consider providing concise text; long labels are read verbosely.
   final String? tooltip;
+
+  /// Optional semantic label announced by screen readers.
   final String? semanticLabel;
 
   // Consider button interactive if any handler is provided.

lib/src/naked_checkbox.dart

@@ -1,9 +1,12 @@
-import 'package:flutter/material.dart';
+import 'package:flutter/widgets.dart';
 import 'package:flutter/services.dart';
 
 import 'mixins/naked_mixins.dart';
 
-/// Headless checkbox built with mixins for proper semantics and callbacks.
+/// A headless checkbox: no visuals, exposes states and proper semantics.
+///
+/// See also:
+/// - [Checkbox], the Material-styled checkbox for typical apps.
 class NakedCheckbox extends StatefulWidget {
   const NakedCheckbox({
     super.key,
@@ -78,7 +81,10 @@ class NakedCheckbox extends StatefulWidget {
   /// Whether to autofocus when created.
   final bool autofocus;
 
-  /// Optional builder that receives the current states for visuals.
+  /// Builder that receives the current interaction [WidgetState]s.
+  ///
+  /// States include at least: disabled, focused, hovered, pressed, selected.
+  /// The `selected` state reflects `value == true`.
   final ValueWidgetBuilder<Set<WidgetState>>? builder;
 
   /// Semantic label for accessibility.

lib/src/naked_dialog.dart

@@ -1,4 +1,4 @@
-import 'package:flutter/material.dart';
+import 'package:flutter/widgets.dart';
 
 /// Provides dialog functionality without default styling.
 ///

lib/src/naked_menu.dart

@@ -1,10 +1,10 @@
-import 'package:flutter/material.dart';
+import 'package:flutter/widgets.dart';
 import 'package:flutter/services.dart';
 
 import 'naked_button.dart';
 import 'utilities/utilities.dart';
 
-/// Provides dropdown menu behavior without visual styling.
+/// A headless dropdown menu without default styling.
 ///
 /// Uses Flutter's RawMenuAnchor to render menu content in the app overlay,
 /// ensuring proper z-index and context inheritance.
@@ -51,6 +51,11 @@ import 'utilities/utilities.dart';
 ///
 /// Menu items use [NakedMenuItem] and automatically close the menu when selected
 /// unless [NakedMenuItem.closeOnSelect] is set to false.
+///
+/// See also:
+/// - [NakedMenuAnchor], which handles overlay placement, focus, and keyboard
+///   traversal for this menu.
+/// - [NakedButton], often used to build the trigger and items.
 class NakedMenu extends StatelessWidget {
   /// Creates a naked menu.
   ///
@@ -119,6 +124,10 @@ class NakedMenu extends StatelessWidget {
 ///
 /// Provides interaction states and accessibility features.
 /// Handles keyboard navigation and screen reader support.
+///
+/// See also:
+/// - [NakedMenu], the container that provides the overlay and positioning.
+/// - [NakedButton], the headless activator used to implement this item.
 class NakedMenuItem extends StatelessWidget {
   /// Creates a naked menu item.
   ///
@@ -183,7 +192,7 @@ class NakedMenuItem extends StatelessWidget {
   /// Whether to automatically focus when created.
   final bool autofocus;
 
-  /// Semantic label for accessibility.
+  /// Semantic label for accessibility (forwarded as a tooltip on the trigger).
   final String? semanticLabel;
 
   void _handlePress(MenuController? controller) {

lib/src/naked_radio.dart

@@ -2,10 +2,31 @@ import 'package:flutter/material.dart';
 
 import 'mixins/naked_mixins.dart';
 
-/// Radio button built with simplified architecture.
+/// A headless radio that participates in a [RadioGroup] without default visuals.
 ///
-/// Provides radio functionality while letting users control presentation
-/// and semantics through the child or builder parameter.
+/// - Must be placed under a [RadioGroup] (or provide a custom [groupRegistry]).
+/// - No visuals are provided; pass a [child] or [builder] to render UI.
+/// - States are exposed to [builder] as a `Set<WidgetState>` including
+///   at least hovered/pressed/focused/selected/disabled.
+/// - Keyboard: focus + Enter/Space select; semantics exposed as a radio.
+///
+/// Example:
+/// ```dart
+/// RadioGroup<int>(
+///   value: selected,
+///   onChanged: (v) => setState(() => selected = v),
+///   child: Row(children: [
+///     NakedRadio<int>(value: 1, child: const Text('One')),
+///     NakedRadio<int>(value: 2, child: const Text('Two')),
+///   ]),
+/// )
+/// ```
+///
+/// See also:
+/// - [RawRadio], the underlying primitive widget used to implement radio
+///   interaction and semantics.
+/// - [RadioGroup], which manages the selected value and provides the grouping
+///   context for radios.
 class NakedRadio<T> extends StatefulWidget {
   const NakedRadio({
     super.key,
@@ -26,24 +47,49 @@ class NakedRadio<T> extends StatefulWidget {
          'Either child or builder must be provided',
        );
 
+  /// Value represented by this radio.
   final T value;
+
+  /// Visual contents when not using [builder].
   final Widget? child;
+
+  /// Whether this radio is enabled.
   final bool enabled;
+
+  /// Mouse cursor when enabled.
+  ///
+  /// Defaults to [SystemMouseCursors.click] when interactive and
+  /// [SystemMouseCursors.basic] when disabled.
   final MouseCursor? mouseCursor;
+
+  /// External [FocusNode] to control focus ownership.
   final FocusNode? focusNode;
+
+  /// Whether to autofocus when built.
   final bool autofocus;
+
+  /// Whether tapping the selected radio clears the selection (nullable group).
   final bool toggleable;
 
   // State change callbacks
+  /// Notifies when focus changes.
   final ValueChanged<bool>? onFocusChange;
+
+  /// Notifies when hover changes.
   final ValueChanged<bool>? onHoverChange;
 
-  /// Called when pressed state changes.
+  /// Notifies when pressed (highlight) changes.
   final ValueChanged<bool>? onPressChange;
+
+  /// Builder that receives the current interaction [WidgetState]s.
+  ///
+  /// Includes the `selected` state when this radio's [value] matches the
+  /// group's selected value.
   final ValueWidgetBuilder<Set<WidgetState>>? builder;
 
-  /// Optional registry override for advanced usage and testing.
-  /// When null, the nearest RadioGroup<T> ancestor is used.
+  /// Registry override for advanced usage and testing.
+  ///
+  /// When null, the nearest [RadioGroup] ancestor is used.
   final RadioGroupRegistry<T>? groupRegistry;
 
   @override