Reorganize documentation into docs/ directory to improve README readability

docs/README.md

@@ -0,0 +1,48 @@
+# 📚 Documentation
+
+Welcome to the comprehensive documentation for **mayr_extensions**!
+
+This directory contains detailed guides for all available extensions.
+
+## 📖 Extension Guides
+
+### Core Extensions
+- [🧱 BuildContext Extensions](./build_context_extensions.md) - Navigation, media query, scaffold, and more
+- [✅ Bool Extensions](./bool_extensions.md) - Boolean utilities and transformations
+- [🗓️ DateTime Extensions](./datetime_extensions.md) - Date manipulation, formatting, and utilities
+- [⏳ Duration Extensions](./duration_extensions.md) - Duration helpers and formatting
+- [🔷 Object Extensions](./object_extensions.md) - Object transformation utilities
+- [🌀 Dynamic Extensions](./dynamic_extensions.md) - Nullable and debug utilities
+
+### Type Extensions
+- [🔢 Number Extensions](./number_extensions.md) - Numeric utilities, formatting, and conversions
+- [🔤 String Extensions](./string_extensions.md) - String manipulation, parsing, and formatting
+- [🧩 Iterable/List Extensions](./list_extensions.md) - List operations and utilities
+- [🗺️ Map Extensions](./map_extensions.md) - Map transformations and utilities
+- [🔢 Set Extensions](./set_extensions.md) - Set operations
+
+### UI Extensions
+- [🖼️ Image Extensions](./image_extensions.md) - Image widget helpers
+- [🧩 Widget Extensions](./widget_extensions.md) - Widget transformations and utilities
+
+### Other Extensions
+- [🎯 Humanize Extensions](./humanize_extensions.md) - Human-readable formatting
+- [📜 DateTimeFormat](./datetime_format.md) - Pre-defined date/time formats
+
+## 🚀 Quick Links
+
+- [Installation & Setup](../README.md#-installation--setup)
+- [Usage Examples](../README.md#usage)
+- [Contributing Guidelines](../README.md#-contributing)
+- [Changelog](../CHANGELOG.md)
+
+## 💡 Need Help?
+
+If you can't find what you're looking for:
+- Check the [main README](../README.md) for a quick overview
+- Browse the individual extension documentation files above
+- [Open an issue](https://github.com/YoungMayor/flutter_utils_extensions/issues) if you have questions
+
+---
+
+**Made with ❤️ by the mayr_extensions community**

docs/bool_extensions.md

@@ -0,0 +1,33 @@
+# ✅ Bool Extensions
+
+Utilities for working with boolean values.
+
+## Methods
+
+- `choose(trueValue, falseValue)` – Returns `trueValue` if the boolean is true, otherwise returns `falseValue`
+- `toInt()` – Converts the boolean to an integer (1 for true, 0 for false)
+- `toYesNo({trueString, falseString})` – Converts to a string representation with customizable values
+- `not` – Returns the negation of the boolean (equivalent to `!this`)
+
+## Examples
+
+```dart
+// Choose between values
+true.choose('Active', 'Inactive'); // 'Active'
+false.choose('Active', 'Inactive'); // 'Inactive'
+
+// Convert to integer
+true.toInt(); // 1
+false.toInt(); // 0
+
+// Convert to Yes/No strings
+true.toYesNo(); // 'Yes'
+false.toYesNo(trueString: 'On', falseString: 'Off'); // 'Off'
+
+// Negation
+true.not; // false
+```
+
+## Back to Documentation
+
+[← Back to main documentation](./README.md)

docs/build_context_extensions.md

@@ -0,0 +1,42 @@
+# 🧱 BuildContext Extensions
+
+Extensions that make working with `BuildContext` easier and more expressive.
+
+## Quick Access Properties
+
+### Form & Navigation
+
+- `form` – Easily access the nearest `FormState` using `context.form`
+- `navigator` – Shorthand for `Navigator.of(context)`
+- `overlay` – Access the current `OverlayState` from the context
+- `scaffold` – Retrieve the nearest `ScaffoldState` with `context.scaffold`
+
+## ScaffoldMessenger
+
+- `scaffoldMessenger` – Quickly get the `ScaffoldMessengerState` for showing snackbars and more
+- `void showSnackBar(String content, {Duration? duration, SnackBarBehavior behavior = SnackBarBehavior.fixed})` - Quickly show a SnackBar without manually accessing ScaffoldMessenger
+
+## Media Query
+
+Access media query information with ease:
+
+- `mediaQuery` – Access `MediaQueryData` from context
+- `platformBrightness` – Get the system's brightness setting (`Brightness.dark` or `Brightness.light`)
+- `platformInDarkMode` | `platformInLightMode` – Returns `true` based on the app's current brightness mode
+- `widgetSize` – Get the rendered size of the widget associated with the context
+- `widgetHeight` – Convenience getter for just the height of the widget
+- `widgetWidth` – Convenience getter for just the width
+
+## Media Query Orientation
+
+- `orientation` – Access the current screen orientation (`portrait` or `landscape`)
+- `isLandscape` / `isPortrait` – Easy checks for current orientation
+- `widgetShortestSide` – Useful for responsive layouts based on the device's shortest screen edge
+- `isPhone` – Returns `true` if the device is considered a phone
+- `isSmallTablet`, `isLargeTablet` – Classify tablets based on width
+- `isTablet` – Shortcut combining both small and large tablets
+- `isDesktop` – Detects larger screens, typically desktops
+
+## Back to Documentation
+
+[← Back to main documentation](./README.md)

docs/datetime_extensions.md

@@ -0,0 +1,58 @@
+# 🗓️ DateTime Extensions
+
+Comprehensive utilities for working with dates and times.
+
+## ✅ Checkers
+
+- `isAfternoon` – Checks if the time is between 12:00 PM and 5:59 PM
+- `isMorning` – Checks if the time is before 12:00 PM
+- `isEvening` – Checks if the time is between 6:00 PM and 11:59 PM
+- `isNight` – Checks if the time is between midnight and 5:59 AM
+- `isToday` / `isTomorrow` / `isYesterday` – Quickly check the relation to the current day
+- `isSameDay(DateTime other)` – Returns `true` if the date is the same calendar day as `other`
+- `isInPast` / `isInFuture` – Check if the datetime is before or after now
+
+## 🔧 Utilities
+
+- `startOfDay()` – Returns the start of the day (midnight) for the datetime
+
+## 🔧 Manipulators
+
+### Adding Time
+
+- `addDays(int)` / `addMonths(int)` / `addYears(int)` – Add to the datetime
+- `addHours(int)` / `addMinutes(int)` / `addSeconds(int)` – Add smaller units
+
+### Subtracting Time
+
+- `subDays(int)` / `subMonths(int)` / `subYears(int)` – Subtract from the datetime
+- `subHours(int)` / `subMinutes(int)` / `subSeconds(int)` – Subtract smaller units
+
+## 🔢 Age
+
+- `toAge()` – Convert the date to an age in years
+- `isAgeOlder(age)` / `isAgeYounger(age)` / `isAgeEqualTo(age)` – Check against an age
+- `isAgeBetween(min, max)` – Check if the age is within a given range
+
+## 🧠 Time to String
+
+- `format(String format)` – Fully custom format using `intl`
+
+  > Popular date and time formats included in the [MayrDateTimeFormats] class.
+  >
+  > Currently includes:
+  > - `MayrDateTimeFormats.ukDate` - dd/MM/yyyy
+  > - `MayrDateTimeFormats.ukDateTime` - dd/MM/yyyy HH:mm:ss
+  > - `MayrDateTimeFormats.usDate` - yyyy-MM-dd
+  > - `MayrDateTimeFormats.usDateTime` - yyyy-MM-dd HH:mm:ss
+  > - `MayrDateTimeFormats.time` - HH:mm:ss
+  > - `MayrDateTimeFormats.timeNoSecs` - HH:mm
+
+- `toDayOrdinal()` – Get the day of the month with ordinal (e.g. `1st`, `22nd`, `31st`)
+- `toTimeAgoString()` – Human-readable "time ago" format (e.g. "2 days ago")
+- `toTimeString()` – Convert to time only (e.g. `14:35` or `14:35:59`)
+- `toShortDate()` – Returns a short formatted date string (e.g. `Wed 15th Jan`)
+
+## Back to Documentation
+
+[← Back to main documentation](./README.md)

docs/datetime_format.md

@@ -0,0 +1,34 @@
+# 📜 DateTimeFormat
+
+Pre-defined date and time format strings for common use cases.
+
+This package includes some common date time formats that you can use with the `format()` extension method on `DateTime` objects.
+
+## Available Formats
+
+- `MayrDateTimeFormats.ukDate` - **dd/MM/yyyy** (e.g., 15/01/2025)
+- `MayrDateTimeFormats.ukDateTime` - **dd/MM/yyyy HH:mm:ss** (e.g., 15/01/2025 14:30:45)
+- `MayrDateTimeFormats.usDate` - **yyyy-MM-dd** (e.g., 2025-01-15)
+- `MayrDateTimeFormats.usDateTime` - **yyyy-MM-dd HH:mm:ss** (e.g., 2025-01-15 14:30:45)
+- `MayrDateTimeFormats.time` - **HH:mm:ss** (e.g., 14:30:45)
+- `MayrDateTimeFormats.timeNoSecs` - **HH:mm** (e.g., 14:30)
+
+## Usage
+
+```dart
+import 'package:mayr_extensions/mayr_extensions.dart';
+
+final now = DateTime.now();
+
+// Use pre-defined formats
+print(now.format(MayrDateTimeFormats.ukDate)); // 15/01/2025
+print(now.format(MayrDateTimeFormats.usDateTime)); // 2025-01-15 14:30:45
+print(now.format(MayrDateTimeFormats.time)); // 14:30:45
+
+// Or use custom formats
+print(now.format('EEEE, MMMM d, yyyy')); // Wednesday, January 15, 2025
+```
+
+## Back to Documentation
+
+[← Back to main documentation](./README.md)

docs/duration_extensions.md

@@ -0,0 +1,31 @@
+# ⏳ Duration Extensions
+
+Extensions for working with `Duration` objects.
+
+## Methods
+
+- `delay([callback])` – Delays execution for the given duration. Optionally accepts a callback to run after the delay
+- `toReadableString()` – Returns a human-readable string representation (e.g., '2h 30m', '1d 5h 30m')
+- `isLongerThan(other)` – Checks if this duration is longer than another duration
+- `isShorterThan(other)` – Checks if this duration is shorter than another duration
+
+## Examples
+
+```dart
+// Delay execution
+await 2.seconds.delay(() {
+  print('Delayed by 2 seconds');
+});
+
+// Human-readable string
+final duration = Duration(hours: 2, minutes: 30);
+print(duration.toReadableString()); // '2h 30m'
+
+// Compare durations
+5.seconds.isLongerThan(3.seconds); // true
+3.seconds.isShorterThan(5.seconds); // true
+```
+
+## Back to Documentation
+
+[← Back to main documentation](./README.md)

docs/dynamic_extensions.md

@@ -0,0 +1,26 @@
+# 🌀 Dynamic Extensions
+
+Extensions for nullable types and debug utilities.
+
+## Methods
+
+- `nullOnDebug<T>()` – Returns `null` **only in debug mode**; retains value in release/profile. Useful for testing nullable flows
+- `onlyOnDebug<T>()` – Returns the value **only in debug mode**, otherwise `null`
+- `maybe<T>({double probability = 0.5})` – Randomly returns `null` based on the given probability (between 0.0 and 1.0). Great for simulating unreliable data in tests or dev mode
+- `orDefault(T fallback)` - Returns the fallback value if the provided value is null
+
+## Examples
+
+```dart
+// Simulate unreliable data
+final value = 'Simulate me'.maybe(probability: 0.3);
+// Has a 30% chance of being null
+
+// Provide fallback values
+String? name = null;
+print(name.orDefault('Anonymous')); // 'Anonymous'
+```
+
+## Back to Documentation
+
+[← Back to main documentation](./README.md)

docs/humanize_extensions.md

@@ -0,0 +1,55 @@
+# 🎯 Humanize Extensions
+
+Convert technical or numeric values into readable, natural, human-friendly strings.
+
+> Where computers speak in seconds, bytes, and counts, `humanize` translates them into something that sounds like it came from a person.
+
+## Durations
+
+- `.humanize(locale)` → "2 hours, 3 minutes"
+
+### Examples
+
+```dart
+Duration(hours: 2, minutes: 3).humanize(); // '2 hours, 3 minutes'
+Duration(days: 1).humanize(); // '1 day'
+Duration(seconds: 45).humanize(); // '45 seconds'
+```
+
+## Time (DateTime)
+
+- `.humanize(locale)` → "just now", "3 hours ago", "yesterday", "last week", "3 days from now", "2 weeks ago"
+
+### Examples
+
+```dart
+DateTime.now().humanize(); // 'just now'
+DateTime.now().subtract(Duration(hours: 3)).humanize(); // '3 hours ago'
+DateTime.now().subtract(Duration(days: 1)).humanize(); // 'yesterday'
+DateTime.now().add(Duration(days: 2)).humanize(); // 'in 2 days'
+```
+
+## Numbers
+
+- `humanizeNumber()` → "15.3k", "1.5M"
+- `humanizeOrdinal()` → "1st", "2nd", "3rd"
+- `humanizeCount('item')` → "1 item" / "3 items"
+- `humanizePercentage(max, min)` → "74%"
+- `humanizeFileSize()` → "1.0 MB", "520.3 KB"
+
+### Examples
+
+```dart
+1234.humanizeNumber(); // '1.2k'
+1500000.humanizeNumber(); // '1.5M'
+1.humanizeOrdinal(); // '1st'
+21.humanizeOrdinal(); // '21st'
+3.humanizeCount('item'); // '3 items'
+0.75.humanizePercentage(); // '75%'
+1024.humanizeFileSize(); // '1.0 KB'
+520300.humanizeFileSize(); // '508.1 KB'
+```
+
+## Back to Documentation
+
+[← Back to main documentation](./README.md)

docs/image_extensions.md

@@ -0,0 +1,26 @@
+# 🖼️ Image Extensions
+
+Extensions for working with `ImageProvider` objects.
+
+## Methods
+
+- `circleAvatar({ ... })` – Quickly convert an `ImageProvider` to a `CircleAvatar` widget with full customisation options
+
+## Parameters
+
+- `backgroundColor` – Background colour of the avatar (default is transparent)
+- `radius` – Sets the circular radius of the avatar
+- `minRadius` / `maxRadius` – Optional constraints
+- `foregroundColor` – Colour for the foreground image
+- `onBackgroundImageError` / `onForegroundImageError` – Handle image load failures
+
+## Examples
+
+```dart
+// Create a circle avatar from a network image
+NetworkImage('https://example.com/pic.jpg').circleAvatar(radius: 40);
+```
+
+## Back to Documentation
+
+[← Back to main documentation](./README.md)