sheetloom

sheetloom is an open-source Flutter package for shipping workbook-based experiences without rebuilding the full spreadsheet stack yourself.

It combines:

• workbook manifest and sheet models
• spreadsheet rendering with pinned headers and merged cells
• sparse cell patch editing
• REST-backed loading and saving
• Hive-backed offline cache and pending patch sync

The package is built around a prepared workbook JSON contract. It is not a raw .xlsx parser by itself. You can plug it into any backend that exposes:

• workbook manifest
• individual sheet payloads
• workbook state read/write endpoints

Core pieces

• WorkbookViewerScreen: the ready-to-use screen with loading, sheet switching, editing dialog, patch persistence, and error states
• SpreadsheetViewport: the low-level spreadsheet widget if you want custom screen composition
• CachedWorkbookRepository: orchestrates remote loading, Hive cache reads, offline fallback, and pending patch sync
• DioWorkbookRemoteDataSource: a default REST implementation using dio
• HiveWorkbookCacheStore: the package cache store with default box names

Getting started

Add the package:

dependencies:
  sheetloom: ^0.1.0

If you want the full offline flow, initialize Hive and open the workbook boxes:

await Hive.initFlutter();
final cacheStore = await HiveWorkbookCacheStore.open();

Usage

Minimal setup with dio:

final repository = CachedWorkbookRepository(
  remote: DioWorkbookRemoteDataSource(
    dio: dio,
    paths: const WorkbookApiPaths(),
  ),
  isConnected: () async => true,
  cacheStore: await HiveWorkbookCacheStore.open(),
);

MaterialApp(
  home: WorkbookViewerScreen(
    fileId: 9,
    fileName: 'Livestock planner',
    userId: '42',
    repository: repository,
  ),
);

API shape

The default DioWorkbookRemoteDataSource expects each endpoint to return either:

• a JSON map directly
• or an envelope with a top-level data object

The default paths are:

• GET /api/files/{id}/workbook-model
• GET /api/files/{id}/workbook-model/sheets/{sheetId}?user_id=...
• GET /api/files/{id}/workbook-state?user_id=...
• PUT /api/files/{id}/workbook-state?user_id=...

You can override all paths through WorkbookApiPaths.

Notes

• The viewer is optimized for prepared workbook payloads, not formula calculation from raw Excel files.
• If your app already has its own HTTP client or auth wrapper, you can keep it and implement WorkbookRemoteDataSource instead of using the built-in dio source.

Maintenance

• Follow semantic versioning.
• Add user-facing changes to CHANGELOG.md before release.
• Run flutter analyze, flutter test, and dart pub publish --dry-run before publishing.