sheet_mapper 1.1.0

A Flutter package for mapping Excel/CSV/TSV/PSV files to Dart objects using annotations, with a beautiful drag-and-drop UI widget.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.1.0 - 2025-01-12

Added

• Auto-registration system: Simplified API with automatic parser registration
• SheetMapperRegistry: Central registry for managing sheet mappers
• Generated init functions: Auto-generated init<ModelName>SheetMapper() functions for easy initialization
• Cleaner widget API: Removed the need for parser parameter in SheetMapperWidget

Changed

• Breaking Change: SheetMapperWidget no longer requires a parser parameter
• Breaking Change: Models now use with $ModelSheetMapper instead of with _$ModelSheetMapper
• Simplified initialization process - just call generated init function once in main()
• Updated documentation with cleaner 4-step getting started guide

Migration Guide

From 1.0.0 to 1.1.0

1. Remove the parser parameter from SheetMapperWidget:

   // Before
   SheetMapperWidget<User>(
     parser: User.fromSheet,
     onResult: (users) => print(users),
     onError: (error) => print(error),
   )
   
   // After
   SheetMapperWidget<User>(
     onResult: (users) => print(users),
     onError: (error) => print(error),
   )
   

2. Update your model to use the new mixin name:

   // Before
   class User with _$UserSheetMapper { ... }
   
   // After
   class User with $UserSheetMapper { ... }
   

3. Add initialization in main():

   void main() {
     initUserSheetMapper(); // Add this line
     runApp(MyApp());
   }
   

4. Regenerate code:

   dart run build_runner build --delete-conflicting-outputs
   

1.0.0 - 2024-01-10

Added

• Initial release of sheet_mapper
• Support for Excel files (.xlsx, .xls, .xlsm) using the excel package
• Support for CSV, TSV, and PSV text-based formats
• Type-safe code generation using annotations (@SheetTable, @SheetColumn)
• Beautiful customizable drag-and-drop UI widget (SheetMapperWidget)
• Programmatic API for non-UI usage (SheetMapper.fromFile, fromBytes, fromString)
• Type conversions for String, int, double, bool, DateTime
• Support for nullable types
• Default value handling with customizable defaults
• Required field validation
• Multi-sheet Excel support
• Comprehensive error handling with user-friendly messages
• Full platform support (iOS, Android, Web, Desktop)

Features

• @SheetTable annotation: Mark classes for sheet mapping with options for sheet name, index, header row, and start row
• @SheetColumn annotation: Map fields to columns with custom names, default values, date formats, and validation
• SheetMapperWidget: Drag-and-drop file upload with customizable appearance and animations
• SheetMapper API: Parse files, bytes, or string content into typed objects
• SheetParser: Unified parsing for all supported file types
• ExcelParser: Specialized Excel file parsing
• CsvParser: Text-based file parsing with proper quote handling