flutter_fa_davi_table 1.0.3

A high-performance data table wrapper built on top of Davi. Optimized for lazy loading, infinite scrolling, and smart O(1) multi-platform grid rendering.

flutter_fa_davi_table

A production-ready, high-performance reactive data table grid wrapper engineered for the FlutterArtist ecosystem. Built on top of the powerful architecture of davi: 4.0.1, version 1.0.0 introduces a complete Identity-Based State Engine and a Unified State-Color Theme Matrix.

It eliminates common virtualized spreadsheet rendering glitches, offering seamless synchronization for complex row states (Current, Selected, Checked) during real-time sorting and filtering operations without row de-synchronization.

---

 Architectural Breakthroughs in v1.0.0

Unlike legacy data grids that depend on volatile, index-based row indexing to apply conditional styles, flutter_fa_davi_table tracks state changes using strict item identity configurations:

• Identity-Based State Matrix: Row selection, current focus targets, and custom checkboxes are tracked strictly via unique entity keys (Set<ID>). Your row backgrounds remain 100% accurate even if internal sorting shifts positions.
• Centralized State-Color Theme Engine: Eliminates messy, inline row-color configurations inside table initialization scripts. Styles are entirely unified within a single, descriptive theme controller mapping layout properties directly to dynamic row states.
• Shallow Reference Caching: Leverages efficient address pointer scanning (_isSameList) across collection boundaries to suppress redundant element tree layout calculations and costly re-renders.
• O(1) View-Side Sorting Transforms: Utilizes lightning-fast index lookup tables instead of executing heavy linear transformations when matching local UI layers with business block components.

---

 Standalone Usage (100% Framework Decoupled)

flutter_fa_davi_table is a completely modular layout component. It operates independently of any monolithic architectural ecosystem and can be deployed directly into any standard, standalone cross-platform Flutter layout workspace.

import 'package:flutter/material.dart';
import 'package:davi/davi.dart';
import 'package:flutter_fa_davi_table/flutter_fa_davi_table.dart';

// 1. Declare your raw data entity structure
class InventoryAsset {
  final int id;
  final String title;
  final double valuation;

  InventoryAsset({required this.id, required this.title, required this.valuation});
}

class CompactInventoryWorkspace extends StatefulWidget {
  const CompactInventoryWorkspace({super.key});

  @override
  State<CompactInventoryWorkspace> createState() => _CompactInventoryWorkspaceState();
}

class _CompactInventoryWorkspaceState extends State<CompactInventoryWorkspace> {
  // 2. Define standard table column structural manifests using DAVI 4.0.1 syntax
  late final FaDaviTableModelSettings<InventoryAsset> _tableSettings;

  @override
  void initState() {
    super.initState();
    _tableSettings = FaDaviTableModelSettings(
      columns: [
        DaviColumn<InventoryAsset>(
          name: 'ID',
          cellValue: (param) => param.data.id, 
          width: 80,
        ),
        DaviColumn<InventoryAsset>(
          name: 'Asset Title',
          cellValue: (param) => param.data.title, 
          grow: 1,
        ),
        DaviColumn<InventoryAsset>(
          name: 'Value',
          cellValue: (param) => param.data.valuation, 
          width: 120,
        ),
      ],
    );
  }

  // 3. Track row states using unique entity keys (Identity-based selection)
  int? _currentFocusedId;
  final Set<int> _selectedIds = {};
  final Set<int> _checkedIds = {};

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: FaDaviTable<int, InventoryAsset>(
        items: _activeAssets,
        getItemId: (item) => item.id, // Single identity tracking definition
        sortRuleSide: SortRuleSide.viewSide,
        columnWidthBehavior: ColumnWidthBehavior.scrollable,
        visibleRowsCount: 10,
        
        // Pass business state trackers directly to the table layer
        currentItemId: _currentFocusedId,
        selectedItemIds: _selectedIds,
        checkedItemIds: _checkedIds,
        
        // Setup highly custom state colors matching your product layout specifications
        themeData: FaDaviTableThemeData<InventoryAsset>(
          rowColorBuilder: (item, {required isCurrent, required isSelected, required isChecked, required isHovered}) {
            if (isHovered) return Colors.grey.shade100;
            if (isCurrent) return Colors.blue.shade50;
            if (isSelected) return Colors.blue.shade100;
            if (isChecked) return Colors.green.shade50; // Distinct background rendering for checked tracks
            return Colors.white;
          },
        ),
        modelSettings: _tableSettings,
        placeholderWidget: const Center(child: Text("No records available")),
        onRowTap: (item) {
          setState(() {
            _currentFocusedId = item.id;
          });
        },
        onLastVisibleRow: (lastRowIndex) {
          _fetchNextDatabaseBatch();
        },
      ),
    );
  }

  List<InventoryAsset> _activeAssets = [
    InventoryAsset(id: 101, title: 'Enterprise Token Core', valuation: 2500.0),
    InventoryAsset(id: 102, title: 'Styles Router Adapter', valuation: 1800.5),
  ];

  void _fetchNextDatabaseBatch() {
    setState(() {
      _activeAssets = [
        ..._activeAssets,
        InventoryAsset(id: 103, title: 'Overlay Network Mask', valuation: 950.0),
      ];
    });
  }
}

---

⚡ Integration with the FlutterArtist Ecosystem

When paired with the official design language primitives (flutter_artist_styles) and state management blocks, FaDaviTable hooks seamlessly into central layout design tokens.

Feeding Design Tokens into Central Theme Maps

Instead of declaring ad-hoc design parameters everywhere, centralize the spreadsheet presentation layout via the unified token matrix:

FaDaviTableThemeData<SystemLogInfo> getGlobalTableTheme(BuildContext context) {
  return FaDaviTableThemeData<SystemLogInfo>(
    columnDividerThickness: 0.4,
    columnDividerFillHeight: true,
    decoration: BoxDecoration(
      border: Border.all(width: 0.2, color: context.faColors.divider.subtle),
      color: context.faColors.surface.ground,
    ),
    header: HeaderThemeData(
      color: context.faColors.bar.standard,
      bottomBorderColor: context.faColors.divider.subtle,
    ),
    rowDividerColor: context.faColors.divider.subtle,
    rowFillHeight: true,
    
    // Central coloring matrix processing element state vectors cleanly
    rowColorBuilder: (item, {required isCurrent, required isSelected, required isChecked, required isHovered}) {
      if (isHovered) return context.faColors.surface.row.hover;
      if (isCurrent) return context.faColors.surface.row.current;
      if (isSelected) return context.faColors.surface.row.selected;
      if (isChecked) return context.faColors.surface.row.checked;
      return context.faColors.surface.row;
    },
  );
}

Then simply inject this configuration directly into your view structure:

FaDaviTable<int, SystemLogInfo>(
  items: block.items,
  getItemId: (item) => item.id,
  currentItemId: block.currentItem?.id,
  selectedItemIds: block.selectedItemIds,
  checkedItemIds: block.checkedItemIds,
  themeData: getGlobalTableTheme(context),
  sortRuleSide: SortRuleSide.blockSide,
  modelSettings: FaDaviTableModelSettings(columns: tableColumnsConfig),
)

---

 Installation Manifest

Add the following dependency block to your standard cross-platform project pubspec.yaml manifest:

dependencies:
  flutter:
    sdk: flutter
  davi: 4.0.1 # Explicitly locked to match the core ecosystem requirements
  flutter_fa_davi_table: ^1.0.0