CCCI Utility

A single Flutter package for common app foundations: networking, repository layer, secure storage, UI components, helpers, and theme utilities.

Table of Contents

  1. Highlights
  2. Requirements
  3. Installation
  4. Quick Start
  5. Configuration
  6. Module Reference
  7. Widget Catalog
  8. Re-exports
  9. Notes

Highlights

  • Opinionated API/repository stack with Dio + Riverpod
  • Secure token/session/theme persistence via FlutterSecureStorage
  • Reusable widgets for forms, lists, feedback, and overlays
  • Rich utility layer (formatters, validators, encryption, navigation)
  • Light/dark theme building blocks with overridable palettes

Requirements

  • Dart SDK: ^3.2.0
  • Flutter: >=1.17.0

Installation

dependencies:
  ccci_utility: ^1.1.132

import 'package:ccci_utility/ccci_utility.dart';

Quick Start

1) Load environment (app side)

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await dotenv.load(fileName: '.env');
  runApp(const MyApp());
}

2) Get Dio client from Riverpod provider

final dio = ref.watch(dioInstanceProvider);
final client = ref.watch(dioClientProvider); // with DioInterceptor

3) Create API + repository

class ProfilesApi extends BaseApi {
  ProfilesApi(DioClient client) : super('/university/v1.0/profiles', client);
}

class ProfileRepository extends BaseRepository<ProfileModel> {
  ProfileRepository(super.api, super.fromJson);
}

final rows = await repo.get(queryParameters: {'limit': 10});

4) Use UI primitives

CButton(
  label: 'Save',
  onPressed: () {},
);

CInput(
  hintText: 'Email',
  validator: (v) => isValidEmail(v ?? '') ? null : 'Invalid email',
);

Configuration

DioClient resolves baseUrl in this order:

Priority Source Key/Path
1 Secure storage baseUrl via BaseStore().getBaseUrl()
2 Env var .env key BASE_URL
3 Asset fallback assets/config.json with current: true entry

.env example

BASE_URL=https://api.example.com

assets/config.json example

{
  "development": {
    "current": true,
    "baseUrl": "https://dev.example.com"
  },
  "production": {
    "current": false,
    "baseUrl": "https://api.example.com"
  }
}

Module Reference

Base & Network

Component Purpose Key APIs
BaseApi Route-based HTTP wrapper getById, get, post, put, delete
BaseRepository<T> Generic data mapping layer get, getById, post, put, getWithCount, postWithCount
BaseResponseModel<T> Count + rows response model count, rows, isEmpty, isNotEmpty
DioClient Low-level HTTP client wrapper get, post, put, delete
DioInterceptor Auto bearer token header uses BaseStore().getToken()
DioExceptions Human-friendly Dio errors DioExceptions.fromDioError(...)
createErrorResponse Normalized error message helper from return_handling.dart
dioInstanceProvider / dioClientProvider Riverpod providers Provider<Dio>, Provider<DioClient>

Storage & Service Base

Component Purpose Key APIs
BaseStore Secure storage abstraction setToken, getToken, hasExpired, isLoggedIn, clearStorage, theme methods
baseStore Global store instance shared BaseStore()
BaseServiceProvider Abstract service base for Riverpod BaseServiceProvider(ProviderRef ref)

Helpers

Area Exports
Logging AppLogger.debug/info/warning/error/verbose and API log helpers
Navigation RouteHandler.push, replace, pop, popUntil, pushAndRemoveUntil
Encryption encryptData, decryptData, deriveKeyAndIV, genRandomWithNonZero
Date/Time formatDate, formatTime, dateRangeFormatter, relativeTimeFormatter, formatCountdown, weekOfYear
String/Text initialsFormatter, toTitleCase, toCamelCase, toSnakeCase, toKebabCase, truncateString, stripHtmlTags
Numeric formatCurrency, formatCompactCurrency, formatFileSize, formatOrdinal, formatPercentage
Validators isValidEmail, isValidUrl, hasOnlyNumbers, isValidCreditCard, isValidIPv4, validatePasswordStrength

Utility Services

Component Purpose Key APIs
Geolocation Permission, location, reverse geocoding, stream checkPermission, getLocation, getISOCode, getAddress, streamListener, stopStreamListener
LocalAuthService Device biometric auth wrapper isDeviceSupported, hasBiometrics, authenticate, cancelAuthentication

Styles, Models, and Enums

Group Exports
Theme AppTheme.themeData, AppTheme.darkTheme, themesProvider, ThemesProvider
Colors/Typography AppColors, SemanticColors, AppText, TextStyle.theme(context, ...)
Models AttachmentMetadataTypeModel, MinioAttachmentTypeModel, MenuPage, DrawerMenu, FieldData
Enums LOADING_STATE, DateFormatType, TimeFormatType, TimeHourCycle

Widget Catalog

Widget/Function Purpose
CAvatar Circular avatar with network/local image fallback
CAvatarStack Overlapped avatar stack with overflow indicator
CButton Configurable button with loading/icon/svg/reverse ordering
CCard Styled container card with optional tap handling
CImage Local or cached-network image renderer
CInput Flexible TextFormField wrapper
CLoader Lottie-based loading indicator
CLoaderDialog(...) Imperative loading dialog helper
CReadMoreText Expandable/collapsible rich text with annotations
CRefresh Pull-to-refresh wrapper with custom indicator
CTile Reusable list tile with optional avatar/actions
CError Centered error UI block
CSliverAppBarDelegate Persistent sliver header delegate
CBottomSheet(...) Themed modal bottom sheet helper
CConfirmationDialog(...) Platform-adaptive confirmation dialog

Re-exports

ccci_utility.dart re-exports commonly used dependencies:

  • dio
  • flutter_riverpod
  • go_router
  • flutter_dotenv
  • freezed_annotation
  • jwt_decoder
  • flutter_lucide
  • geocoding
  • geolocator
  • syncfusion_flutter_maps
  • web_socket_channel
  • flutter/services.dart

Notes

  • DioClient does not load .env automatically; call dotenv.load(...) in app startup.
  • If using fallback config, ensure your app includes assets/config.json in assets.
  • DioInterceptor expects token from secure storage key used by BaseStore.

Libraries

ccci_utility
test_api