nets_core 0.1.14

Core UI components, networking, secure storage, push notifications, and utilities shared across Nets Flutter projects.

nets_core

A Flutter package that provides a set of core UI components, services, and utilities shared across Nets projects. It standardizes navigation, network communication, secure storage, push notifications, and common UI patterns so every app in the Nets ecosystem starts from a solid, consistent foundation.

---

Features

🧭 Navigation & App Shell

• AppStack – a ConsumerStatefulWidget that wraps the whole app with a convex bottom navigation bar (powered by convex_bottom_bar) and integrates with go_router. Supports custom active/inactive colours, gradients, an optional AppBar, and a reactive listener callback.
• AppStackMenuItem – model class for each navigation item (icon, label, route location, optional badge and custom item builder).

🗂 Layouts

• FullscreenLayout – simple full-screen container.
• HeaderBodyScrollLayout – sticky header with a scrollable body.
• PageStepper – multi-step page flow.
• ProgressStepLayout – step-based progress indicator layout.

🧱 UI Components

• WideButton – full-width ElevatedButton with icon support, configurable colours, and automatic text capitalisation.
• ProfileAvatar – user avatar widget with network image caching via cached_network_image.
• ListDecorated, OptionsList, OptionsListItem – pre-styled list containers and option row widgets.
• SliverHeader / SliverHeaderGeneric – customisable sliver headers for CustomScrollView.
• GradientShader – applies a gradient shader to any child widget.
• MenuItem – standard navigation menu item.
• WebViewScreen – in-app WebView screen backed by webview_flutter.
• LoadingScreen – full-screen loading placeholder.

📸 Camera

• TakePictureScreen – ready-to-use camera screen built with the camera plugin. Accepts a CameraDescription and an onPictureTaken(File) callback.

📝 Forms

• FormBuilder – declarative form container.
• TextFormInput – styled text input field with built-in validation helpers.

🌐 Networking — ApiService

• Dot-notation URL resolution via ApiUrls (production and development base URLs, media URLs, and nested route trees).
• Automatic Authorization header injection with OAuth2 client_credentials token refresh.
• Secure cookie handling.
• GET, POST, PATCH, DELETE, and multipart file-upload support.
• Configurable self-signed certificate trust for development environments.

💾 Secure Storage — StorageService

• Thin wrapper around flutter_secure_storage with Android EncryptedSharedPreferences.
• CRUD helpers: writeSecureData, readSecureData, deleteSecureData, readAllSecureData, deleteAllSecureData, containsKeyInSecureData.

🔔 Push Notifications — NotificationsService

• Local notifications via flutter_local_notifications.
• Firebase Cloud Messaging integration via firebase_messaging.
• NotificationChannel, NotificationMessage, and NotificationAction model classes for composing rich notifications.

🗃 State Management — NetsCoreProvider

• StateNotifier (Riverpod) that holds global app state (NetsCoreState) including version, sync status, and an arbitrary key-value data map with configurable persistence.
• Automatically persists selected keys to secure storage on every state change.

🛠 Utilities

• StringExtension – capitalize, capitalizeFirstofEach, capitalizeFirstofEachWord, capitalizeFirstofEachSentence, and more.
• DeviceUtils – device information helpers via device_info_plus.
• CountryUtils – country picker helpers via country_picker.

🌍 Localisation

• Ships with English ARB strings (app_en.arb) and generated AppLocalizations.
• Exposes NetsLocalizationsDelegate so host apps can merge nets_core strings with their own.

---

Getting started

Requirements

Tool	Minimum version
Dart SDK	^3.5.0
Flutter	>=3.24.0

1. Add the dependency

dependencies:
  nets_core: ^0.1.13

Then run:

flutter pub get

2. Firebase setup

nets_core depends on firebase_core and firebase_messaging. Make sure your host app already has Firebase initialised:

await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);

3. Platform permissions

Android (AndroidManifest.xml):

<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

iOS (Info.plist):

<key>NSCameraUsageDescription</key>
<string>Required for taking profile pictures.</string>

---

Usage

AppStack — main scaffold with bottom navigation

AppStack(
  title: 'My App',
  menu: [
    AppStackMenuItem(label: 'Home',    icon: Icons.home,    location: '/home'),
    AppStackMenuItem(label: 'Profile', icon: Icons.person,  location: '/profile'),
  ],
  child: child, // provided by go_router ShellRoute
)

ApiService — HTTP client

final apiUrls = ApiUrls(
  baseUrl:        'https://api.example.com',
  baseUrlDev:     'https://dev.api.example.com',
  baseMediaUrl:   'https://media.example.com',
  baseMediaUrlDev:'https://dev.media.example.com',
  urls: [
    BaseUrl(name: 'users', path: '/api/users/', items: [
      BaseUrl(name: 'detail', path: '/api/users/{id}/'),
    ]),
  ],
);

final api = ApiService(
  urls:         apiUrls,
  clientId:     'my-client-id',
  clientSecret: 'my-client-secret',
);

final response = await api.get('users', {});

StorageService — secure key-value storage

final storage = StorageService();
await storage.writeSecureData('token', 'abc123');
final token = await storage.readSecureData('token');

TakePictureScreen — camera

final cameras = await availableCameras();
Navigator.push(context, MaterialPageRoute(
  builder: (_) => TakePictureScreen(
    camera: cameras.first,
    title: 'Profile photo',
    onPictureTaken: (file) {
      // handle the captured File
    },
  ),
));

StringExtension

'hello world'.capitalize;               // 'Hello world'
'hello world'.capitalizeFirstofEach;   // 'Hello World'

---

Additional information

• Issues & contributions: open an issue or pull request on the GitHub repository.
• Licence: see the LICENSE file.
• Versioning: this package follows Semantic Versioning. Breaking changes increment the major version.

Automated releases (GitHub Actions)

This repository includes automation for quality checks and publishing:

• CI workflow (.github/workflows/ci.yml): runs analysis and tests on push/PR.
• Publish workflow (.github/workflows/publish_pubdev.yml): publishes to pub.dev when a tag like v0.1.14 is pushed.

One-time setup

1. Generate your pub.dev credentials on a trusted machine (if you do not have them yet):

dart pub token add https://pub.dev
cat ~/.pub-cache/credentials.json

2. In GitHub repository settings, add a secret:

• Name: PUB_CREDENTIALS_JSON
• Value: full JSON content of ~/.pub-cache/credentials.json

Release flow

1. Update pubspec.yaml version and CHANGELOG.md.
2. Merge to master.
3. Create and push a matching tag:

git tag v0.1.14
git push origin v0.1.14

The publish workflow validates that the tag and pubspec.yaml version match before uploading.