littlefish_icons 2.0.0

A littlefish package for standardising and centralising icons used across littlefish applications

Littlefish Icons

A dedicated abstraction layer for managing icons within the Littlefish POS ecosystem. This package decouples UI logic from specific asset implementations, allowing the application to dynamically switch visual icons (client-specific branding) based on the active injection.

🚀 Features

• White-Label Support: Seamlessly switch between different icon sets without changing UI code.
• Type Safety: Exposes all icons as standard IconData, ensuring compatibility with standard Flutter Icon() widgets.
• Platform Adaptation: Automatically adapts standard icons for iOS (Cupertino) and Android (Material) where applicable.
• Custom SVG Support: Converts custom SVG assets into a native font file (.ttf), allowing vector scaling and color tinting.

🛠 Usage

1. Initialization

The package relies on Dependency Injection (via littlefish_core) to determine which icon set to use.

In your app's dependency injection setup (e.g., icon_injector.dart), register the specific provider for the active client:

// Example: Injecting the FNB Provider
import 'package:littlefish_icons/providers/fnb_icon_provider.dart';

void injectIcons() {
  LittleFishCore.instance.registerLazyService<IconProvider>(
    () => FnbIconProvider()
  );
  
  // Initialize the static facade
  LittleFishIcons.init();
}

Note, in the merchant app, we use the littlefish CLI to manage the icon injection, similar to that of the PaymentInjector.

2. Consuming Icons

In your Flutter widgets, use the static LittleFishIcons facade. Do not use Icons.xyz or MdiIcons.xyz directly if the icon is meant to be themable. NEVER access specific providers directly, e.g. AbsaIconProvider, FnbIconProvider, etc. ALWAYS use LittleFishIcons.

import 'package:littlefish_icons/littlefish_icons.dart';

// ...

IconButton(
  // This will render a speedpoint icon for FNB, 
  // but a calculator icon for other clients automatically.
  icon: Icon(LittleFishIcons.quickSale), 
  onPressed: () {},
),

🎨 Adding Custom Icons

This package uses a generator to convert SVG files into a TrueType Font (TTF).

Step 1: Prepare the SVG

• Clean the SVG: Ensure the icon uses Filled Shapes, not Strokes/Lines. Fonts cannot render strokes. This website can be helpful if you find the resulting icon from an SVG does not look the same: https://iconly.io/tools/svg-convert-stroke-to-fill
• Naming: Name the file in snake_case (e.g., quick_sale_bold.svg).
• Location: Place the file in littlefish_icons/assets/svgs/.

Step 2: Generate the Font & Glyphs

You must run the generation script whenever you add, remove, or modify an SVG file in the assets/svgs/ directory. This script transforms the raw vector assets into a font file and auto-generates the Dart code required to access them.

How to run: Execute the shell script from the package root:

Bash

./tool/generate_icons.sh

Note: If you encounter a permission error, make the script executable by running: chmod +x tool/generate_icons.sh

What this script does:

Scans the assets/svgs/ directory for valid SVG files.

Compiles them into a single TrueType Font file at assets/fonts/LittlefishCustom.ttf.

Generates a Dart class at lib/src/generated/littlefish_custom_glyphs.dart that exposes each icon as a static IconData getter (e.g., LittlefishCustomGlyphs.speedpoint).

Step 3: Map the Icon

Open the relevant provider (e.g., lib/src/providers/fnb_icon_provider.dart) and map the abstract getter to the new generated glyph.

@override
IconData get quickSale => LittlefishCustomGlyphs.quick_sale_bold;

🏗 Architecture

• Core (lib/core/): Defines the IconProvider abstract interface. This is the contract all providers must adhere to.
• Providers (lib/providers/): Concrete implementations for each client (e.g., SbsaIconProvider, FnbIconProvider).
• Generated (lib/src/generated/): Auto-generated code mapping font characters to IconData.
• Facade (littlefish_icons.dart): The public entry point that delegates calls to the active provider.

⚠️ Troubleshooting

The icon shows as a box with an "X" or "?"

• This means the font family is not registered correctly in the consuming app.
• Ensure littlefish_icons is added to pubspec.yaml.
• Run flutter clean and flutter pub get in the main app, then uninstall and reinstall the app on the device.

The icon looks like a solid block/blob

• The SVG contains strokes (lines) instead of shapes. Fonts only support filled shapes.
• Use a tool like Iconly Stroke-to-Fill or "Outline Stroke" in Figma to fix the SVG, then regenerate.