masterfabric_core

A comprehensive Flutter package providing core utilities, base classes, and shared logic for building scalable Flutter applications. MasterFabric Core serves as the foundational layer for MasterFabric projects, offering a complete architecture with state management, navigation, dependency injection, and pre-built views.

Features

🏗️ Architecture & State Management

Base View Classes: BaseViewBloc, BaseViewCubit, BaseViewHydratedCubit for different state management needs
Master View System: Unified view management with MasterView, MasterViewCubit, and MasterViewHydratedCubit
State Persistence: Hydrated BLoC support for state persistence across app restarts
View Models: Base classes for business logic separation

GoRouter Integration: Pre-configured routing with AppRoutes
Route Management: Centralized route definitions and navigation helpers

🎨 Pre-built Views

SplashView: App launch screen with loading logic
OnboardingView: User onboarding flow
AuthView: Authentication screen with Sign In/Sign Up tabs
AccountView: User account management screen
PermissionsView: Runtime permission request screens
ErrorHandlingView: Error display and recovery
LoadingView: Loading state views
EmptyView: Empty state views
InfoBottomSheetView: Information bottom sheets
ImageDetailView: Image detail viewer
SearchView: Search functionality interface

🛠️ Helper Utilities

LocalStorageHelper: Multi-backend local storage with SharedPreferences and HiveCE support
- Storage type switching via LocalStorageType enum
- Automatic storage type configuration from app_config.json
- Backward compatible with existing SharedPreferences implementation
HiveCeStorageHelper: HiveCE storage implementation for high-performance data persistence
AuthStorageHelper: Authentication data persistence
PermissionHandlerHelper: Runtime permissions management
LocalNotificationHelper: Local push notifications
FileDownloadHelper: File downloads with progress tracking
DateTimeHelper: Date and time operations and formatting
UrlLauncherHelper: External URL and app launching
ApplicationShareHelper: Content sharing functionality
DeviceInfoHelper: Device information retrieval
AssetConfigHelper: JSON config management from assets
GridHelper: Grid layout calculation utilities
SpacerHelper: UI spacing utilities
CommonLoggerHelper: Logging utilities
SvgHelper: SVG rendering from assets, network, string, and file sources
- Color tinting and theming support
- Reusable configurations with SvgConfig
- Placeholder and error widget support for network SVGs
PushNotificationHelper: Multi-provider push notification management
- OneSignal and Firebase FCM support
- Topic subscriptions and user targeting
- Permission handling and token management
WebViewerHelper: HTML and WebView rendering
- Sanitized HTML rendering
- Custom styling support
- Full WebView for URLs
ForceUpdateHelper: App version checking and update prompts
- Multiple version providers (config file, API, Remote Config)
- Multiple UI styles (dialog, bottom sheet, full screen)
- Semantic version comparison
- Store redirects (App Store, Play Store, custom URLs)
- Customizable strings for localization
SkeletonHelper: Comprehensive skeleton loading placeholders
- 10 animation styles: shimmer, pulse, wave, glow, slide, bounce, breathe, gradientFlow, sparkle, none
- Shape widgets: rectangle, circle, rounded, text, avatar, custom
- Preset widgets: list item, card, profile, article, product, social post, story
- Theme support with SkeletonTheme and SkeletonConfig
- Custom shapes with DiamondClipper, HexagonClipper, StarClipper
AppTrackingTransparencyHelper: iOS App Tracking Transparency (ATT) support
- Native iOS implementation via platform channels (no external packages required)
- Request tracking authorization with system dialog
- Check current tracking status without prompting
- Platform-safe: automatically returns true on non-iOS platforms
- Integrated into MasterApp.runBefore() for easy initialization
NetworkInfoHelper: Comprehensive network information helper
- WiFi details: SSID, BSSID, IP, IPv6, submask, broadcast, gateway via network_info_plus
- Connectivity: connection type, connected status, WiFi/mobile checks via connectivity_plus
- Cloudflare Trace: public IP, country location, datacenter, TLS, HTTP, WARP via cloudflare.com/cdn-cgi/trace
- Public IP lookup via ipify API
- DNS resolution via dart:io
- Host reachability check via TCP socket
- Download speed estimation
- Network interface listing
- Platform-safe: all methods return safe defaults on web
NetworkInitFeature: Enum-based network initialization for MasterApp.runBefore()
- cloudflareTrace - IP, location, datacenter persisted to local storage
- publicIP - External IP persisted to local storage
- connectivity - Connection type and status persisted to local storage
- wifiInfo - WiFi details persisted to local storage

📐 Layout System

Grid: Responsive grid layout system
Spacer: Consistent spacing utilities

🔌 Dependency Injection

Injectable Integration: Pre-configured dependency injection setup
GetIt Integration: Service locator pattern support

🌍 Localization

Slang Integration: i18n support with Slang
Translation Support: English translation file structure

Installation

From pub.dev (Recommended)

Add this to your package's pubspec.yaml file:

dependencies:
  masterfabric_core: ^0.0.15

Then run:

flutter pub get

From Git (Development)

For the latest development version, you can use:

dependencies:
  masterfabric_core:
    git:
      url: https://github.com/gurkanfikretgunak/masterfabric_core.git
      ref: dev  # or use a specific tag/commit

Then run:

flutter pub get

Quick Start

1. Setup Your App with MasterApp

import 'package:flutter/material.dart';
import 'package:masterfabric_core/masterfabric_core.dart';
import 'package:go_router/go_router.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize MasterApp components (loads config and sets storage type)
  await MasterApp.runBefore(
    assetConfigPath: 'assets/app_config.json',
    hydrated: true, // Enable state persistence
    requestTrackingTransparency: true, // Request iOS ATT authorization (iOS 14+)
    networkFeatures: {
      NetworkInitFeature.cloudflareTrace, // IP, location, datacenter
      NetworkInitFeature.connectivity,     // WiFi/mobile/none status
    },
  );
  
  // Create your router
  final router = GoRouter(
    routes: [
      // Your routes here
    ],
  );
  
  runApp(MyApp(router: router));
}

class MyApp extends StatelessWidget {
  final GoRouter router;
  
  const MyApp({super.key, required this.router});
  
  @override
  Widget build(BuildContext context) {
    return MasterApp(
      router: router,
      shouldSetOrientation: true,
      preferredOrientations: [
        DeviceOrientation.portraitUp,
        DeviceOrientation.portraitDown,
      ],
      showPerformanceOverlay: false,
      textDirection: TextDirection.ltr,
      fontScale: 1.0,
    );
  }
}

2. Create a View with MasterView

import 'package:masterfabric_core/masterfabric_core.dart';

class ProductsView extends MasterView<ProductsCubit, ProductsState> {
  ProductsView({super.key}) : super(currentView: MasterViewTypes.content);

  @override
  void initialContent(ProductsCubit cubit, BuildContext context) {
    cubit.loadProducts();
  }

  @override
  Widget viewContent(BuildContext context, ProductsCubit cubit, ProductsState state) {
    if (state.isLoading) {
      return LoadingView();
    }
    
    if (state.hasError) {
      return ErrorHandlingView(error: state.error);
    }
    
    return ListView.builder(
      itemCount: state.products.length,
      itemBuilder: (context, index) {
        return ProductItem(product: state.products[index]);
      },
    );
  }
}

3. Use Pre-built Views

import 'package:masterfabric_core/masterfabric_core.dart';
import 'package:go_router/go_router.dart';

// In your router configuration
GoRoute(
  path: '/auth',
  builder: (context, state) => AuthView(
    goRoute: (path) => context.go(path),
    arguments: state.uri.queryParameters,
  ),
),

GoRoute(
  path: '/onboarding',
  builder: (context, state) => OnboardingView(
    config: onboardingConfig,
    goRoute: (path) => context.go(path),
    arguments: state.uri.queryParameters,
  ),
),

4. Configure Storage Backend

Storage backend can be configured in app_config.json:

{
  "storageConfiguration": {
    "localStorageType": "hiveCe",
    "enableEncryption": false,
    "cacheDurationDays": 7,
    "maxCacheSizeMb": 100
  }
}

Supported values for localStorageType:

"sharedPreferences" - Default, uses SharedPreferences (backward compatible)
"hiveCe" - Uses HiveCE for high-performance storage

4b. iOS App Tracking Transparency Setup

For iOS apps, you need to add the NSUserTrackingUsageDescription key to your Info.plist:

<key>NSUserTrackingUsageDescription</key>
<string>We would like to use your data to deliver personalized content and improve your app experience.</string>

Then enable ATT in your app initialization:

await MasterApp.runBefore(
  assetConfigPath: 'assets/app_config.json',
  hydrated: true,
  requestTrackingTransparency: true, // Shows ATT dialog on iOS 14+
);

The authorization result is automatically stored in LocalStorageHelper as osmea_tracking_authorized (boolean).

Note: The ATT dialog only appears on real iOS devices (iOS 14+). On simulators, it will return false by default. On Android and other platforms, the helper automatically returns true since ATT is iOS-only.

4c. Network Features at Startup

Use NetworkInitFeature enum to pre-fetch and persist network data during initialization:

await MasterApp.runBefore(
  assetConfigPath: 'assets/app_config.json',
  hydrated: true,
  networkFeatures: {
    NetworkInitFeature.cloudflareTrace, // IP, location, datacenter via Cloudflare
    NetworkInitFeature.publicIP,        // External IP via ipify
    NetworkInitFeature.connectivity,    // WiFi/mobile/none status
    NetworkInitFeature.wifiInfo,        // WiFi SSID, IP, gateway
  },
);

Each feature stores its result in LocalStorageHelper with osmea_ prefix keys:

Feature	Storage Keys
`cloudflareTrace`	`osmea_cf_ip`, `osmea_cf_location`, `osmea_cf_colo`, `osmea_cf_tls`, `osmea_cf_http`, `osmea_cf_warp`
`publicIP`	`osmea_public_ip`
`connectivity`	`osmea_connection_type`, `osmea_is_connected`
`wifiInfo`	`osmea_wifi_name`, `osmea_wifi_ip`, `osmea_wifi_gateway`

Note: Network features are platform-safe. On web, methods return safe defaults. WiFi details require platform permissions on some devices.

4d. Configure Force Update

Force update configuration in app_config.json:

{
  "forceUpdateConfiguration": {
    "latestVersion": "2.0.0",
    "minimumVersion": "1.0.0",
    "releaseNotes": "Bug fixes and new features",
    "features": ["New feature 1", "Performance improvements"],
    "storeUrl": {
      "ios": "https://apps.apple.com/app/id123456789",
      "android": "https://play.google.com/store/apps/details?id=com.example.app"
    }
  }
}

Update types:

Force: Current version < minimumVersion (blocking, user must update)
Recommended: Current version < latestVersion with minimumVersion set
Optional: Current version < latestVersion without minimumVersion

5. Use Helper Utilities

import 'package:masterfabric_core/masterfabric_core.dart';

// Local Storage
// Storage type is automatically configured from app_config.json
// Or set manually:
LocalStorageHelper.setStorageType(LocalStorageType.hiveCe); // or LocalStorageType.sharedPreferences

await LocalStorageHelper.setString('key', 'value');
final value = LocalStorageHelper.getString('key');

// Get value by key (supports any type, async)
final dynamicValue = await LocalStorageHelper.getByKey('key');

// Get all items from database
final allItems = await LocalStorageHelper.getAllItems();

// Check if key exists
final exists = LocalStorageHelper.hasKey('key');

// Permissions
final permissionHelper = PermissionHandlerHelper();
final granted = await permissionHelper.requestPermission(Permission.camera);

// Date Formatting
final formatted = DateTimeHelper.formatDate(DateTime.now(), 'yyyy-MM-dd');

// URL Launcher
await UrlLauncherHelper.launchUrl('https://example.com');

// Device Info
final deviceInfo = DeviceInfoHelper();
final platform = await deviceInfo.getPlatform();

// SVG Helper
SvgHelper.fromAsset('assets/icons/home.svg', width: 24, height: 24, color: Colors.blue);
SvgHelper.fromNetwork('https://example.com/logo.svg', placeholder: CircularProgressIndicator());
SvgHelper.themedIcon(context, 'assets/icons/star.svg'); // Auto-colored from IconTheme

// Force Update Helper
await ForceUpdateHelper.instance.initialize(
  ForceUpdateConfig(
    providerType: VersionProviderType.configFile,
    storeConfig: StoreConfig(
      appStoreId: '123456789',
      playStorePackage: 'com.example.app',
    ),
  ),
);

final updateInfo = await ForceUpdateHelper.instance.checkForUpdate();
if (updateInfo.hasUpdate) {
  await ForceUpdateHelper.instance.showUpdateUI(context, updateInfo);
}

// Skeleton Helper
// Simple shapes
SkeletonHelper.rectangle(width: 200, height: 40);
SkeletonHelper.circle(size: 48);
SkeletonHelper.text(lines: 3);

// Presets
SkeletonHelper.listItem(lines: 2);
SkeletonHelper.card(imageHeight: 150);
SkeletonHelper.socialPost(showImage: true);

// With animation type
SkeletonTheme(
  config: SkeletonConfig(
    animationType: SkeletonAnimationType.pulse,
    baseColor: Colors.grey[300]!,
    highlightColor: Colors.grey[100]!,
  ),
  child: SkeletonHelper.productGrid(itemCount: 4),
);

// Dark theme
SkeletonTheme(
  config: SkeletonConfig.dark(),
  child: Column(
    children: [
      SkeletonHelper.listItem(),
      SkeletonHelper.listItem(),
    ],
  ),
);

// App Tracking Transparency (iOS)
// Request tracking authorization (shows iOS system dialog)
final bool authorized = await AppTrackingTransparencyHelper.instance
    .requestTrackingAuthorization();

// Check current status without prompting
final TrackingStatus status = await AppTrackingTransparencyHelper.instance
    .getTrackingAuthorizationStatus();

// Status values: TrackingStatus.notDetermined, .restricted, .denied, .authorized

// Result is automatically stored in LocalStorageHelper when used via MasterApp.runBefore()
final storedResult = await LocalStorageHelper.getItem('osmea_tracking_authorized');

// Network Info Helper
// Cloudflare Trace (IP, location, datacenter, TLS)
final trace = await NetworkInfoHelper.instance.getCloudflareTrace();
print('IP: ${trace?.ip}, Country: ${trace?.loc}, DC: ${trace?.colo}');

// WiFi information
final wifi = await NetworkInfoHelper.instance.getAllWifiInfo();
print('WiFi: ${wifi.wifiName}, IP: ${wifi.wifiIP}');

// Connectivity
final connected = await NetworkInfoHelper.instance.isConnected();
final type = await NetworkInfoHelper.instance.getConnectionType();

// Public IP
final publicIP = await NetworkInfoHelper.instance.getPublicIP();

// DNS Lookup
final ips = await NetworkInfoHelper.instance.dnsLookup('google.com');

// Host Reachability
final result = await NetworkInfoHelper.instance.isHostReachable('google.com');
print('Reachable: ${result.isReachable}, Latency: ${result.latencyMs}ms');

// Download Speed Estimation
final speed = await NetworkInfoHelper.instance.estimateDownloadSpeed();
print('Speed: ${speed.downloadSpeedMbps.toStringAsFixed(2)} Mbps');

// Network Interfaces
final interfaces = await NetworkInfoHelper.instance.getNetworkInterfaces();

// Network features are persisted to local storage when using MasterApp.runBefore()
final cfIP = await LocalStorageHelper.getItem('osmea_cf_ip');
final cfLocation = await LocalStorageHelper.getItem('osmea_cf_location');

Package Structure

lib/
├── masterfabric_core.dart          # Main library export
└── src/
    ├── base/                       # Base classes and architecture
    │   ├── base_view_*.dart        # Base view classes
    │   ├── master_view/            # Master view system
    │   └── widgets/                # Base widgets
    ├── helper/                     # Utility helpers (incl. NetworkInfoHelper, NetworkInitFeature)
    ├── views/                      # Pre-built views
    ├── models/                     # Data models
    ├── layout/                     # Layout utilities
    ├── resources/                  # Generated resources
    └── di/                         # Dependency injection
ios/
├── Classes/
│   └── MasterfabricCorePlugin.swift  # Native iOS plugin (ATT support)
└── masterfabric_core.podspec       # CocoaPods specification

Requirements

Dart SDK: ^3.9.2
Flutter: >=1.17.0

Dependencies

Core Dependencies

flutter_bloc: ^9.1.0 - State management
hydrated_bloc: ^10.1.1 - State persistence
go_router: ^15.1.1 - Navigation
injectable: ^2.7.1 - Dependency injection
slang: ^4.11.1 - Localization
hive_ce: ^2.16.0 - High-performance NoSQL database (optional storage backend)
flutter_svg: ^2.2.3 - SVG rendering support
network_info_plus: ^7.0.0 - WiFi network information
connectivity_plus: ^6.1.4 - Network connectivity status

See `pubspec.yaml` for complete dependency list

Documentation

For detailed documentation, see:

CHANGELOG.md - Version history and changes
doc/analysis.md - Architecture analysis

Package Information

Pub.dev: https://pub.dev/packages/masterfabric_core
GitHub: https://github.com/gurkanfikretgunak/masterfabric_core
Version: 0.0.15
License: AGPL-3.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GNU AGPL v3.0 License - see the LICENSE file for details.

osmea_components - UI component library

Support

For issues, questions, or contributions, please visit the GitHub repository.

Publishing

This package is published on pub.dev. You can install it directly using:

flutter pub add masterfabric_core

Or add it manually to your pubspec.yaml:

dependencies:
  masterfabric_core: ^0.0.15

Published Package: This package is available on pub.dev. For the latest stable version, use the pub.dev installation method above.

masterfabric_core

Features

🏗️ Architecture & State Management

🧭 Navigation & Routing

🎨 Pre-built Views

🛠️ Helper Utilities

📐 Layout System

🔌 Dependency Injection

🌍 Localization

Installation

From pub.dev (Recommended)

From Git (Development)

Quick Start

1. Setup Your App with MasterApp

2. Create a View with MasterView

3. Use Pre-built Views

4. Configure Storage Backend

4b. iOS App Tracking Transparency Setup

4c. Network Features at Startup

4d. Configure Force Update

5. Use Helper Utilities

Package Structure

Requirements

Dependencies

Core Dependencies

See `pubspec.yaml` for complete dependency list

Documentation

Package Information

Contributing

License

Support

Publishing

Libraries

masterfabric_core package

masterfabric_core

Features

🏗️ Architecture & State Management

🧭 Navigation & Routing

🎨 Pre-built Views

🛠️ Helper Utilities

📐 Layout System

🔌 Dependency Injection

🌍 Localization

Installation

From pub.dev (Recommended)

From Git (Development)

Quick Start

1. Setup Your App with MasterApp

2. Create a View with MasterView

3. Use Pre-built Views

4. Configure Storage Backend

4b. iOS App Tracking Transparency Setup

4c. Network Features at Startup

4d. Configure Force Update

5. Use Helper Utilities

Package Structure

Requirements

Dependencies

Core Dependencies

See pubspec.yaml for complete dependency list

Documentation

Package Information

Contributing

License

Related Packages

Support

Publishing

Libraries

masterfabric_core package

See `pubspec.yaml` for complete dependency list