s_extensions 0.0.1

A powerful and playful extensions dependency for your flutter projects.

s_extensions

Lightweight, expressive extension methods for Flutter projects. This library adds convenient numeric and string helpers, plus a static context manager that enables property-based screen queries like 0.9.screenWidth without passing BuildContext around.

Works great for building responsive UIs — for example, Baghdad news headers, Mosul marketplace cards, or Erbil prayer time widgets.

Installation

Add to pubspec.yaml:

dependencies:
  s_extensions: ^0.0.1

Import what you need:

import 'package:s_extensions/s_extensions.dart';

// or import specific files
import 'package:s_extensions/extensions/number_ext.dart';
import 'package:s_extensions/extensions/string_ext.dart';
import 'package:s_extensions/extensions_context.dart';

Quick Start

Recommended initialization (supports hot reload and navigation changes):

MaterialApp(
  builder: (context, child) {
    FlutterExtensions.update(context); // keep stored view & media fresh
    return child!;
  },
  home: const MyHomePage(),
);

Usage examples:

// News header spanning 90% of the screen width
SizedBox(width: 0.9.screenWidth);
// or use: 0.9.screenWidth.horizontalSpace

// Marketplace card spacing
final spacing = 16.half; // 8.0

// Prayer reminder interval
final interval = 15.min; // Duration(minutes: 15)

// Button ripple timing
final ripple = 250.msec; // Duration(milliseconds: 250)

// List item padding
final padding = 80.quarter; // 20.0

// Daily refresh window
final refreshWindow = 2.hr; // Duration(hours: 2)

Features

Number extensions

• half, quarter — simple fractions as double.
• square, sqRoot — square and square root.
• misec, msec, sec, min, hr, day — Duration factories.
• screenWidth, screenHeight — property-based screen size queries using a static context manager.
• horizontalSpace, verticalSpace — quick SizedBox builders.
• fixed00, fixed0 — string representations with 2 and 1 decimal places.

String extensions

• firstLetterUpperCase — capitalize the first letter.
• isEmail, isPhoneNumber, isUrl — basic validation.
• toDouble, toInt — safe parsing with fallbacks.
• toDate — convert string to DateTime.

Static Context Manager

FlutterExtensions is a tiny singleton managing a FlutterView and a cached MediaQueryData. It powers property access like 0.9.screenWidth and 0.9.screenHeight without explicitly passing BuildContext.

Initialization patterns:

• Explicit (recommended): call FlutterExtensions.update(context) in MaterialApp.builder.
• Lazy: first use attempts WidgetsBinding.instance.platformDispatcher.views.first. This works after runApp; it throws if no view is available (e.g., too early in tests).

Key API:

• FlutterExtensions.init([context]) — initialize explicitly; optional BuildContext.
• FlutterExtensions.update(context) — refresh stored FlutterView and MediaQueryData on rebuilds/hot reload.
• FlutterExtensions.isInitialized — check readiness.
• FlutterExtensions.mediaQuery() — get the current MediaQueryData (attempts lazy init; may throw).
• FlutterExtensions.reset() — clear cached references (useful for tests).

Hot reload and metrics:

• Implements WidgetsBindingObserver.didChangeMetrics to refresh cached MediaQueryData on orientation or size changes.

Error Handling

• mediaQuery() may throw StateError if Flutter is not fully initialized or no FlutterView is available.
• Ensure your app has started (runApp) and prefer using FlutterExtensions.update(context) for determinism.

Testing

• Call WidgetsFlutterBinding.ensureInitialized() in tests.
• Use FlutterExtensions.reset() to clear cached state between tests.

Examples

• Headlines: SizedBox(width: 0.9.screenWidth) for responsive title bars.
• Marketplace grid: 8.verticalSpace and 8.horizontalSpace for compact spacing.
• Prayer times: 15.min intervals for notifications.
• UI animations: 250.msec ripple duration for buttons.
• List views: 80.quarter padding for neat item spacing.

Notes & Best Practices

• Prefer FlutterExtensions.update(context) at the app root to avoid edge cases.
• Values for screenWidth and screenHeight are typically between 0 and 1 for proportional sizing.
• Duration conversions truncate fractional values via toInt().

License

Licensed under the MIT License. See LICENSE for details.

Changelog

See CHANGELOG.md for release notes.