chore: update voiceOver a11Y

Author: AhmedAmineZr

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

@@ -15,49 +15,19 @@ 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.
-///
-/// ## Related Issues:
-/// - Issue #625: Android TalkBack inconsistent reading order with badges
-/// - Issue #627: iOS zoom overflow at 190-235% zoom levels
+/// Manages text scaling constraints for [OudsNavigationBar] (Android/Material)
+/// and [OudsTabBar] (iOS/Cupertino) to prevent layout overflow at high zoom levels.
 class OudsNavigationA11y {
-  /// Maximum text scale factor for navigation items (Issue #627).
-  ///
-  /// 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
+  /// Maximum text scale factor for navigation items.
   ///
-  /// 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.
+  /// Clamped to 108% to prevent overflow between 190–235% system zoom (Issue #627).
   static const double maxTextScaleFactor = 1.08;
 
-  /// 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])
-  ///
-  /// 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)
+  /// Wraps [child] with text scaling clamped to [maxTextScaleFactor].
   ///
-  /// 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,

ouds_core/lib/components/navigation/ouds_navigation_bar_item.dart

@@ -75,6 +75,13 @@ 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 =>
+      badge != null ? '$label, ${badge!.accessibilityText}' : label;
+
   /// Builds the destination icon for a Material 3 [NavigationDestination], optionally wrapped
   /// with an [OudsBadge].
   ///
@@ -172,6 +179,9 @@ class OudsNavigationBarItem {
 
     return NavigationDestination(
       label: label,
+      // tooltip is used by NavigationDestination as the semantics hint for TalkBack.
+      // Overridden to include badge info when present.
+      tooltip: _accessibilityLabel,
       icon: _buildBadgeIconNavigationDestination(
         context,
         icon,
@@ -292,49 +302,56 @@ 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(
-              semanticsLabel: badge.contentDescription,
-              label: badge.count.toString(),
-              status: Negative(),
-              size: badge.hasCount
-                  ? OudsBadgeSize.medium
-                  : OudsBadgeSize.xsmall,
-              child: widgetIcon,
+          ? ExcludeSemantics(
+              child: OudsBadge.count(
+                semanticsLabel: badge.contentDescription,
+                label: badge.count.toString(),
+                status: Negative(),
+                size: badge.hasCount
+                    ? OudsBadgeSize.medium
+                    : OudsBadgeSize.xsmall,
+                child: widgetIcon,
+              ),
             )
           : widgetIcon,
     ];
 
-    return Column(children: children);
+    if (badge == null) {
+      return ExcludeSemantics(child: Column(children: visualChildren));
+    }
+
+    return Stack(
+      children: [
+        ExcludeSemantics(child: Column(children: visualChildren)),
+        // Invisible text: merges badge info into CupertinoTabBar's SemanticsNode
+        // without creating a separate VoiceOver stop.
+        Positioned.fill(
+          child: AbsorbPointer(
+            child: Text(
+              '${badge.accessibilityText}, ',
+              style: const TextStyle(fontSize: 1, color: Colors.transparent),
+            ),
+          ),
+        ),
+      ],
+    );
   }
 }
 
 /// 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 +362,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;
 }