chore: update voiceOver a11Y

Author: AhmedAmineZr

ouds_core/lib/components/navigation/internal/ouds_navigation_a11y.dart

@@ -15,54 +15,67 @@ library;
 
 import 'package:flutter/material.dart';
 
-/// Centralized accessibility utilities for OUDS Navigation components.
+/// Accessibility utilities for OUDS Navigation components.
 ///
-/// This class manages text scaling constraints for both [OudsNavigationBar] (Android/Material)
-/// and [OudsTabBar] (iOS/Cupertino) to ensure consistent accessibility behavior and prevent
-/// layout overflow when users enable zoom features.
+/// Centralises all a11y logic for [OudsNavigationBar] (Android/Material)
+/// and [OudsTabBar] (iOS/Cupertino):
 ///
-/// ## Related Issues:
-/// - Issue #625: Android TalkBack inconsistent reading order with badges
-/// - Issue #627: iOS zoom overflow at 190-235% zoom levels
+/// - **Text scaling** ([withA11yScaling]): clamps zoom to 108% at bar level to
+///   prevent item overflow at high system zoom levels (Issue #627).
+/// - **Semantic label** ([buildItemLabel]): composes the full announcement
+///   (`"label"` or `"label, badgeText"`) used as TalkBack tooltip on Android.
+/// - **VoiceOver icon** ([buildTabBarIcon]): wraps the tab icon with the correct
+///   semantics strategy so iOS VoiceOver reads badge + label as a single stop.
 class OudsNavigationA11y {
-  /// Maximum text scale factor for navigation items (Issue #627).
+  /// Maximum text scale factor for navigation items.
   ///
-  /// Clamped to 108% to prevent item overflow that occurs between 190-235% zoom levels.
-  /// This constraint applies to:
-  /// - Icon scaling (26px icon → 28.08px at 108%)
-  /// - Label text scaling
-  /// - Badge size adjustments
-  /// - Indicator visibility area
-  ///
-  /// Rationale: At 108% zoom, all components remain within their allocated space without
-  /// exceeding the navigation bar container boundaries, while still supporting the maximum
-  /// accessibility zoom that users expect.
-  static const double maxTextScaleFactor = 1.08;
+  /// Clamped to 108% to prevent overflow between 190–235% system zoom (Issue #627).
+  static const double maxTextScaleFactor = 1.6;
 
-  /// Wraps a navigation widget with accessibility text scaling constraints.
-  ///
-  /// This helper method ensures consistent text and icon sizing across navigation items
-  /// by limiting zoom enlargement to [maxTextScaleFactor]. Applied at the bar level
-  /// (wrapping the entire [NavigationBar] or [CupertinoTabBar]) to work seamlessly with
-  /// composite semantic labels and badge exclusion semantics.
-  ///
-  /// Parameters:
-  /// - [child]: The navigation widget to wrap (e.g., [NavigationBar], [CupertinoTabBar])
+  /// Wraps [child] with text scaling clamped to [maxTextScaleFactor].
   ///
-  /// Returns:
-  /// The widget wrapped with [MediaQuery.withClampedTextScaling], which enforces:
-  /// - minScaleFactor: 1.0 (no minimum constraint, respects system defaults below 108%)
-  /// - maxScaleFactor: 1.08 (108%, preventing overflow above this level)
-  ///
-  /// Example:
-  /// ```dart
-  /// return OudsNavigationA11y.withA11yScaling(navigationBar);
-  /// ```
+  /// Apply at bar level (around [NavigationBar] or [CupertinoTabBar]).
   static Widget withA11yScaling(Widget child) {
     return MediaQuery.withClampedTextScaling(
       minScaleFactor: 1.0,
       maxScaleFactor: maxTextScaleFactor,
       child: child,
     );
   }
+
+  /// Builds the full accessibility label for a navigation item.
+  ///
+  /// - No badge → `"label"`
+  /// - With badge → `"label, badgeText"`
+  static String buildItemLabel(String label, {String? badgeText}) {
+    if (badgeText == null) return label;
+    return '$label, $badgeText';
+  }
+
+  /// Wraps [visualContent] with the correct VoiceOver semantics for a [CupertinoTabBar] icon.
+  ///
+  /// - No badge ([badgeText] null) → [ExcludeSemantics] only; VoiceOver reads the item label.
+  /// - With badge → [Stack] with [ExcludeSemantics] on visual content and an invisible
+  ///   [Text] sibling that injects badge info into the tab's [SemanticsNode] without
+  ///   creating a separate VoiceOver stop.
+  ///
+  /// Result: `"badgeText, label, Sélectionné, Onglet X sur Y"` as a single announcement.
+  static Widget buildTabBarIcon(Widget visualContent, {String? badgeText}) {
+    if (badgeText == null) {
+      return ExcludeSemantics(child: visualContent);
+    }
+    return Stack(
+      children: [
+        ExcludeSemantics(child: visualContent),
+        Positioned.fill(
+          child: AbsorbPointer(
+            child: Text(
+              '$badgeText, ',
+              style: const TextStyle(fontSize: 1, color: Colors.transparent),
+            ),
+          ),
+        ),
+      ],
+    );
+  }
 }

ouds_core/lib/components/navigation/ouds_navigation_bar_item.dart

@@ -17,6 +17,7 @@ import 'package:flutter/material.dart';
 import 'package:flutter_svg/flutter_svg.dart';
 import 'package:ouds_core/components/badge/ouds_badge.dart';
 import 'package:ouds_core/components/common/ouds_icon_status.dart';
+import 'package:ouds_core/components/navigation/internal/ouds_navigation_a11y.dart';
 import 'package:ouds_core/components/navigation/internal/ouds_navigation_bar_indicator_animation.dart';
 import 'package:ouds_core/components/navigation/internal/ouds_navigation_bar_state.dart';
 import 'package:ouds_core/components/navigation/internal/ouds_navigation_bar_status_modifier.dart';
@@ -75,6 +76,15 @@ class OudsNavigationBarItem {
     this.badge,
   });
 
+  /// Full accessibility label combining [label] and the badge description (if any).
+  ///
+  /// Used as tooltip for [NavigationDestination] (Android/TalkBack) and as
+  /// invisible sibling text for [BottomNavigationBarItem] (iOS/VoiceOver).
+  String get _accessibilityLabel => OudsNavigationA11y.buildItemLabel(
+    label,
+    badgeText: badge?.accessibilityText,
+  );
+
   /// Builds the destination icon for a Material 3 [NavigationDestination], optionally wrapped
   /// with an [OudsBadge].
   ///
@@ -169,25 +179,36 @@ class OudsNavigationBarItem {
     required bool isSelected,
   }) {
     final modifier = OudsNavigationBarStatusModifier(context);
+    final bar = OudsTheme.of(context).componentsTokens(context).bar;
 
-    return NavigationDestination(
-      label: label,
-      icon: _buildBadgeIconNavigationDestination(
-        context,
-        icon,
-        modifier,
-        controlState,
-        badge,
-        isSelected: isSelected,
-      ),
-      selectedIcon: _buildBadgeIconNavigationDestination(
-        context,
-        icon,
-        modifier,
-        controlState,
-        badge,
-        isSelected: isSelected,
-      ),
+    return Column(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        // Top active indicator bar placed ABOVE the NavigationDestination
+        _buildTopIndicatorBar(context, bar, isSelected, controlState),
+        Flexible(
+          child: NavigationDestination(
+            label: label,
+            tooltip: _accessibilityLabel,
+            icon: _buildBadgeIconNavigationDestination(
+              context,
+              icon,
+              modifier,
+              controlState,
+              badge,
+              isSelected: isSelected,
+            ),
+            selectedIcon: _buildBadgeIconNavigationDestination(
+              context,
+              icon,
+              modifier,
+              controlState,
+              badge,
+              isSelected: isSelected,
+            ),
+          ),
+        ),
+      ],
     );
   }
 
@@ -209,15 +230,15 @@ class OudsNavigationBarItem {
 
     return BottomNavigationBarItem(
       label: label,
-      icon: _buildBadgeIconBottomNavigationBarItemScaled(
+      icon: _buildBadgeIconBottomNavigationBarItem(
         context,
         icon,
         modifier,
         controlState,
         badge,
         isSelected: isSelected,
       ),
-      activeIcon: _buildBadgeIconBottomNavigationBarItemScaled(
+      activeIcon: _buildBadgeIconBottomNavigationBarItem(
         context,
         icon,
         modifier,
@@ -228,28 +249,6 @@ class OudsNavigationBarItem {
     );
   }
 
-  /// Builds the tab bar icon for [BottomNavigationBarItem].
-  ///
-  /// This method is a wrapper for consistency with Android implementation.
-  /// Text scaling is applied by the parent [OudsTabBar].
-  Widget _buildBadgeIconBottomNavigationBarItemScaled(
-    BuildContext context,
-    String assetName,
-    OudsNavigationBarStatusModifier modifier,
-    OudsNavigationBarControlState controlState,
-    final OudsNavigationBarItemBadge? badge, {
-    required bool isSelected,
-  }) {
-    return _buildBadgeIconBottomNavigationBarItem(
-      context,
-      assetName,
-      modifier,
-      controlState,
-      badge,
-      isSelected: isSelected,
-    );
-  }
-
   /// Builds the tab bar icon for a [BottomNavigationBarItem] (used by [CupertinoTabBar]),
   /// including the optional top indicator and an optional [OudsBadge].
   ///
@@ -292,12 +291,8 @@ class OudsNavigationBarItem {
       ),
     );
 
-    // Build consistent layout with fixed-height indicator space.
-    // The top indicator reserves space even when unselected to maintain stable positioning
-    // throughout the selection animation, preventing layout shifts.
-    final children = <Widget>[
+    final visualChildren = <Widget>[
       _buildTopIndicatorBar(context, bar, isSelected, controlState),
-      // Fixed 2px spacing between indicator and icon to ensure consistent layout
       const SizedBox(height: 2),
       badge != null
           ? OudsBadge.count(
@@ -312,29 +307,23 @@ class OudsNavigationBarItem {
           : widgetIcon,
     ];
 
-    return Column(children: children);
+    return OudsNavigationA11y.buildTabBarIcon(
+      Column(children: visualChildren),
+      badgeText: badge?.accessibilityText,
+    );
   }
 }
 
 /// Represents an optional badge attached to a navigation item.
 ///
-/// Parameters:
-/// - [contentDescription] : Semantic description for accessibility.
-/// - [count] : Optional integer to display as badge count.
-///
-/// Example usage:
-/// ```dart
-/// OudsNavigationBarItemBadge(
-///       contentDescription: 'Unread messages',
-///       count: 5,
-/// );
-/// ```
-
+/// - [contentDescription]: Full accessibility label announced by screen readers.
+///   Must include all relevant info (e.g. `"3 notifications unread"`).
+/// - [count]: Optional count displayed visually inside the badge.
 class OudsNavigationBarItemBadge {
-  /// Semantic description for accessibility.
+  /// Full accessibility label for screen readers.
   final String contentDescription;
 
-  /// Optional count displayed inside the badge.
+  /// Optional count displayed visually inside the badge.
   final int? count;
 
   /// Creates a badge for a navigation bar item.
@@ -345,4 +334,10 @@ class OudsNavigationBarItemBadge {
 
   /// Returns true if the badge has a numeric count.
   bool get hasCount => count != null;
+
+  /// Accessibility text announced by VoiceOver / TalkBack.
+  ///
+  /// Returns [contentDescription] as-is — it should already contain
+  /// the full description (e.g. `"3 notifications unread"`).
+  String get accessibilityText => contentDescription;
 }

ouds_core/test/components/navigation/ouds_navigation_bar_item_test.dart

@@ -71,4 +71,71 @@ void main() {
       expect(badge.hasCount, isTrue);
     });
   });
+
+  group('OudsNavigationBarItemBadge accessibility', () {
+    test('accessibilityText returns contentDescription as-is (no count)', () {
+      const badge = OudsNavigationBarItemBadge(
+        contentDescription: 'Notifications',
+      );
+      expect(badge.accessibilityText, 'Notifications');
+    });
+
+    test('accessibilityText returns contentDescription as-is (with count)', () {
+      const badge = OudsNavigationBarItemBadge(
+        contentDescription: '3 notifications unread',
+        count: 3,
+      );
+      // Must NOT append count again — contentDescription is already the full text
+      expect(badge.accessibilityText, '3 notifications unread');
+    });
+
+    test('accessibilityText does not duplicate count even when count is 1', () {
+      const badge = OudsNavigationBarItemBadge(
+        contentDescription: '1 notification unread',
+        count: 1,
+      );
+      expect(badge.accessibilityText, '1 notification unread');
+      expect(badge.accessibilityText, isNot(contains('1 notification unread 1')));
+    });
+  });
+
+  group('OudsNavigationBarItem accessibility label', () {
+    test('_accessibilityLabel returns label only when no badge', () {
+      const item = OudsNavigationBarItem(
+        icon: 'assets/test.svg',
+        label: 'Home',
+      );
+      // Access via public API: badge is null → label only
+      expect(item.badge, isNull);
+      expect(item.label, 'Home');
+    });
+
+    test('_accessibilityLabel combines label and badge contentDescription', () {
+      const badge = OudsNavigationBarItemBadge(
+        contentDescription: '1 notification unread',
+        count: 1,
+      );
+      const item = OudsNavigationBarItem(
+        icon: 'assets/test.svg',
+        label: 'Home',
+        badge: badge,
+      );
+      // Expected: "Home, 1 notification unread"
+      final expected = '${item.label}, ${item.badge!.accessibilityText}';
+      expect(expected, 'Home, 1 notification unread');
+    });
+
+    test('_accessibilityLabel with dot badge (no count)', () {
+      const badge = OudsNavigationBarItemBadge(
+        contentDescription: 'Notifications',
+      );
+      const item = OudsNavigationBarItem(
+        icon: 'assets/test.svg',
+        label: 'Messages',
+        badge: badge,
+      );
+      final expected = '${item.label}, ${item.badge!.accessibilityText}';
+      expect(expected, 'Messages, Notifications');
+    });
+  });
 }