feat(tabbar): add indexed tab mode with on-demand tab building and caching

Author: Muhammad Usman

modules/ensemble/lib/layout/tab/tab_bar_controller.dart

@@ -30,6 +30,7 @@ class TabBarController extends BoxController {
   TabBarAction? tabBarAction;
 
   int selectedIndex = 0;
+  bool useIndexedTab = false;
 
   List<TabItem> _originalItems = [];
   List<TabItem> _visibleItems = [];
@@ -65,6 +66,8 @@ class TabBarController extends BoxController {
     var setters = super.getBaseSetters();
     setters.addAll({
       'items': (values) => items = values,
+      'useIndexedTab': (value) =>
+      useIndexedTab = Utils.getBool(value, fallback: false),
     });
     return setters;
   }
@@ -80,10 +83,10 @@ class TabBarController extends BoxController {
 class TabItem {
   TabItem(
       {this.icon,
-      this.label,
-      this.tabWidget,
-      this.bodyWidget,
-      this.isVisible}) {
+        this.label,
+        this.tabWidget,
+        this.bodyWidget,
+        this.isVisible}) {
     if (icon == null && label == null && tabWidget == null) {
       throw LanguageError(
           "Each tab requires either an icon, a label, or a custom tabWidget");

modules/ensemble/lib/layout/tab_bar.dart

@@ -90,20 +90,29 @@ abstract class BaseTabBar extends StatefulWidget
           EnsembleAction.from(action, initiator: this),
       'onTabSelectionHaptic': (value) =>
           _controller.onTabSelectionHaptic = Utils.optionalString(value),
+      'useIndexedTab': (value) =>
+          _controller.useIndexedTab = Utils.getBool(value, fallback: false),
     };
   }
 }
 
 class TabBarState extends BaseTabBarState {
+  // Cache for indexed tab building mode
+  late List<Widget?> _cache;
+
   @override
   void initState() {
     super.initState();
     _initializeTabController();
   }
 
   void _initializeTabController() {
+    final safeIndex = _getValidInitialIndex();
+    if (widget.controller.useIndexedTab) {
+      _cache = List<Widget?>.filled(widget.controller.items.length, null);
+    }
     tabController = TabController(
-      initialIndex: _getValidInitialIndex(),
+      initialIndex: safeIndex,
       length: widget.controller.items.length,
       vsync: this,
     );
@@ -200,6 +209,12 @@ class TabBarState extends BaseTabBarState {
   void _reinitializeTabController() {
     tabController.removeListener(notifyListener);
     tabController.dispose();
+    // If a tab became hidden and the previously-selected index is now out of
+    // bounds, reset it before recreating the TabController and rebuilding,
+    // otherwise buildSelectedTab() will throw a RangeError.
+    if (widget._controller.selectedIndex >= widget._controller.items.length) {
+      widget._controller.selectedIndex = 0;
+    }
     _initializeTabController();
   }
 
@@ -216,6 +231,20 @@ class TabBarState extends BaseTabBarState {
     if (widget.controller.selectedIndex == index) {
       return;
     }
+
+    // If using indexed tab mode, build the tab on-demand before switching
+    if (widget.controller.useIndexedTab) {
+      final scopeManager = DataScopeWidget.getScope(context);
+      if (scopeManager != null &&
+          index < _cache.length &&
+          _cache[index] == null) {
+        final items = widget.controller.items;
+        if (index < items.length) {
+          _cache[index] = _buildTabAt(scopeManager, items[index]);
+        }
+      }
+    }
+
     setState(() {
       widget.controller.selectedIndex = index;
     });
@@ -264,13 +293,13 @@ class TabBarState extends BaseTabBarState {
     else {
       bool isExpanded = widget._controller.expanded;
 
-      // if Expanded is set, our content needs to stretch to the left-over height
-      // Note we make each Builder unique, as it tends to re-use
-      // the states (down the tree) from the previous Builder
-      // https://stackoverflow.com/questions/55425804/using-builder-instead-of-statelesswidget
-      Widget tabContent = Builder(
-          key: UniqueKey(),
-          builder: (BuildContext context) => buildSelectedTab());
+      // Use indexed tab building if enabled, otherwise use classic single-tab rendering
+      Widget tabContent = widget._controller.useIndexedTab
+          ? _buildTabBodies(context)
+          : Builder(
+              key: ValueKey(widget._controller.selectedIndex),
+              builder: (BuildContext context) => buildSelectedTab());
+
       if (isExpanded) {
         tabContent = Expanded(child: tabContent);
       }
@@ -279,16 +308,7 @@ class TabBarState extends BaseTabBarState {
         crossAxisAlignment: CrossAxisAlignment.stretch,
         children: [
           buildTabBar(),
-          // builder gives us dynamic height control vs TabBarView, but
-          // is sub-optimal since it recreates the tab content on each pass.
-          // This means onLoad API may be called multiple times in debug mode
-          tabContent
-
-          // This cause Expanded child to fail
-          // Padding(
-          //     padding: const EdgeInsets.only(left: 0),
-          //     child: Builder(builder: (BuildContext context) => buildSelectedTab())
-          // )
+          tabContent,
         ],
       );
       // if Expanded is set, stretch our column to left-over height
@@ -320,4 +340,54 @@ class TabBarState extends BaseTabBarState {
     }
     return const Text("Unknown widget for this Tab");
   }
-}
+
+  /// Builds tabs on-demand with caching (used when useIndexedTab is true).
+  /// - Non-expanded: Column + Offstage for hidden tabs (zero-height)
+  /// - Expanded: IndexedStack (bounded height)
+  Widget _buildTabBodies(BuildContext context) {
+    final scopeManager = DataScopeWidget.getScope(context);
+    if (scopeManager == null) return const Text('Unknown widget for this Tab');
+
+    final items = widget._controller.items;
+    final selectedIndex = widget._controller.selectedIndex;
+
+    // Ensure cache size matches current item count
+    if (_cache.length != items.length) {
+      _cache = List<Widget?>.filled(items.length, null);
+    }
+
+    // Build the selected tab now if not already cached
+    _cache[selectedIndex] ??= _buildTabAt(scopeManager, items[selectedIndex]);
+
+    // Non-expanded: lives in unconstrained scroll context
+    // Use Column + Offstage to zero-out hidden tabs
+    if (!widget._controller.expanded) {
+      return Column(
+        mainAxisSize: MainAxisSize.min,
+        crossAxisAlignment: CrossAxisAlignment.stretch,
+        children: List.generate(items.length, (i) {
+          return Offstage(
+            offstage: i != selectedIndex,
+            child: _cache[i] ?? const SizedBox.shrink(),
+          );
+        }),
+      );
+    }
+
+    // Expanded: bounded height is provided by Expanded wrapper
+    // IndexedStack is safe here and stacks children in bounded space
+    return IndexedStack(
+      index: selectedIndex,
+      children: List.generate(
+        items.length,
+        (i) => _cache[i] ?? const SizedBox.shrink(),
+      ),
+    );
+  }
+
+  /// Build a single tab at given index
+  Widget _buildTabAt(ScopeManager scopeManager, TabItem tab) {
+    if (tab.bodyWidget == null) return const SizedBox.shrink();
+    return scopeManager.buildWidgetFromDefinition(tab.bodyWidget);
+  }
+}