Skip to content

Commit bd4f8c7

Browse files
actions-useractions-user
committed
doc: deploy PR #761 preview
1 parent 44fbb7b commit bd4f8c7

35 files changed

Lines changed: 244 additions & 1222 deletions

‎docs/prPreview/761/components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem-class.html‎

Lines changed: 11 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -54,33 +54,17 @@ <h1><span class="kind-class">OudsNavigationBarItem</span> class
5454

5555

5656
<section class="desc markdown">
57-
<p>An OUDS navigation bar item.</p>
58-
<p>An <a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem-class.html">OudsNavigationBarItem</a> represents a single destination displayed in an
59-
OUDS bottom navigation component (e.g. <a href="../components_navigation_ouds_navigation_bar/OudsNavigationBar-class.html">OudsNavigationBar</a> on Material, or
60-
<a href="../components_navigation_ouds_tab_bar/OudsTabBar-class.html">OudsTabBar</a> on iOS).</p>
61-
<p>Each item consists of an icon, a label, and optionally a badge.
62-
Visual appearance can vary depending on selection and the resolved
63-
<code>OudsNavigationBarControlState</code> (enabled/hovered/pressed/focused).</p>
64-
<h3 id="parameters">Parameters:</h3>
65-
<ul>
66-
<li><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/icon.html">icon</a>: Asset path of the SVG icon to display.</li>
67-
<li><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/label.html">label</a>: Text label of the item.</li>
68-
<li><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/badge.html">badge</a>: Optional <a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItemBadge-class.html">OudsNavigationBarItemBadge</a> displayed over the icon.</li>
69-
</ul>
70-
<h3 id="example-usage">Example usage:</h3>
71-
<pre class="language-dart"><code class="language-dart">OudsNavigationBarItem(
57+
<p>A single destination in an OUDS bottom navigation component.</p>
58+
<p>Used by <a href="../components_navigation_ouds_navigation_bar/OudsNavigationBar-class.html">OudsNavigationBar</a> (Material/Android) and <a href="../components_navigation_ouds_tab_bar/OudsTabBar-class.html">OudsTabBar</a> (iOS).
59+
Each item has an icon, a label, and an optional badge. Visual appearance
60+
adapts to the <code>OudsNavigationBarControlState</code> (enabled/hovered/pressed/focused).</p>
61+
<pre class="language-dart"><code class="language-dart">OudsNavigationBarItem(icon: 'assets/home.svg', label: 'Home');
62+
63+
// With badge:
64+
OudsNavigationBarItem(
7265
icon: 'assets/home.svg',
7366
label: 'Home',
74-
);
75-
</code></pre>
76-
<p>With a badge:</p>
77-
<pre class="language-dart"><code class="language-dart">OudsNavigationBarItem(
78-
icon: 'assets/home.svg',
79-
label: 'Home',
80-
badge: OudsNavigationBarItemBadge(
81-
contentDescription: 'Notifications',
82-
count: 3,
83-
),
67+
badge: OudsNavigationBarItemBadge(contentDescription: 'Notifications', count: 3),
8468
);
8569
</code></pre>
8670
</section>
@@ -189,7 +173,7 @@ <h2>Methods</h2>
189173
</dd>
190174

191175
<dt id="toBottomNavigationBarItem" class="callable">
192-
<span class="name"><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/toBottomNavigationBarItem.html">toBottomNavigationBarItem</a></span><span class="signature">(<wbr><span class="parameter" id="toBottomNavigationBarItem-param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span><span class="parameter" id="toBottomNavigationBarItem-param-controlState"><span class="type-annotation">OudsNavigationBarControlState</span> <span class="parameter-name">controlState</span>, {</span><span class="parameter" id="toBottomNavigationBarItem-param-isSelected"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/bool-class.html">bool</a></span> <span class="parameter-name">isSelected</span></span>})
176+
<span class="name"><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/toBottomNavigationBarItem.html">toBottomNavigationBarItem</a></span><span class="signature">(<wbr><span class="parameter" id="toBottomNavigationBarItem-param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span><span class="parameter" id="toBottomNavigationBarItem-param-controlState"><span class="type-annotation">OudsNavigationBarControlState</span> <span class="parameter-name">controlState</span>, {</span><span class="parameter" id="toBottomNavigationBarItem-param-isSelected"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/bool-class.html">bool</a></span> <span class="parameter-name">isSelected</span>, </span><span class="parameter" id="toBottomNavigationBarItem-param-index"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/int-class.html">int</a></span> <span class="parameter-name">index</span>, </span><span class="parameter" id="toBottomNavigationBarItem-param-externalController"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/animation/AnimationController-class.html">AnimationController</a>?</span> <span class="parameter-name">externalController</span></span>})
193177
<span class="returntype parameter">&#8594; <a href="https://api.flutter.dev/flutter/widgets/BottomNavigationBarItem-class.html">BottomNavigationBarItem</a></span>
194178
</span>
195179

@@ -202,7 +186,7 @@ <h2>Methods</h2>
202186
</dd>
203187

204188
<dt id="toNavigationDestination" class="callable">
205-
<span class="name"><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/toNavigationDestination.html">toNavigationDestination</a></span><span class="signature">(<wbr><span class="parameter" id="toNavigationDestination-param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span><span class="parameter" id="toNavigationDestination-param-controlState"><span class="type-annotation">OudsNavigationBarControlState</span> <span class="parameter-name">controlState</span>, {</span><span class="parameter" id="toNavigationDestination-param-isSelected"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/bool-class.html">bool</a></span> <span class="parameter-name">isSelected</span></span>})
189+
<span class="name"><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/toNavigationDestination.html">toNavigationDestination</a></span><span class="signature">(<wbr><span class="parameter" id="toNavigationDestination-param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span><span class="parameter" id="toNavigationDestination-param-controlState"><span class="type-annotation">OudsNavigationBarControlState</span> <span class="parameter-name">controlState</span>, {</span><span class="parameter" id="toNavigationDestination-param-isSelected"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/bool-class.html">bool</a></span> <span class="parameter-name">isSelected</span>, </span><span class="parameter" id="toNavigationDestination-param-index"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/int-class.html">int</a></span> <span class="parameter-name">index</span>, </span><span class="parameter" id="toNavigationDestination-param-total"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/int-class.html">int</a></span> <span class="parameter-name">total</span>, </span><span class="parameter" id="toNavigationDestination-param-onTap"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-ui/VoidCallback.html">VoidCallback</a>?</span> <span class="parameter-name">onTap</span></span>})
206190
<span class="returntype parameter">&#8594; <a href="https://api.flutter.dev/flutter/widgets/Column-class.html">Column</a></span>
207191
</span>
208192

‎docs/prPreview/761/components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/toBottomNavigationBarItem.html‎

Lines changed: 28 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ <h1><span class="kind-method">toBottomNavigationBarItem</span> method
5858
<span class="name ">toBottomNavigationBarItem</span>(<wbr><ol class="parameter-list"> <li><span class="parameter" id="toBottomNavigationBarItem-param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span></li>
5959
<li><span class="parameter" id="toBottomNavigationBarItem-param-controlState"><span class="type-annotation">OudsNavigationBarControlState</span> <span class="parameter-name">controlState</span>, {</span></li>
6060
<li><span class="parameter" id="toBottomNavigationBarItem-param-isSelected"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/bool-class.html">bool</a></span> <span class="parameter-name">isSelected</span>, </span></li>
61+
<li><span class="parameter" id="toBottomNavigationBarItem-param-index"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/int-class.html">int</a></span> <span class="parameter-name">index</span>, </span></li>
62+
<li><span class="parameter" id="toBottomNavigationBarItem-param-externalController"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/animation/AnimationController-class.html">AnimationController</a>?</span> <span class="parameter-name">externalController</span>, </span></li>
6163
</ol>})
6264

6365

@@ -69,10 +71,18 @@ <h1><span class="kind-method">toBottomNavigationBarItem</span> method
6971
<p>This is intended to be used by <a href="../../components_navigation_ouds_tab_bar/OudsTabBar-class.html">OudsTabBar</a>, which is backed by Cupertino's
7072
<a href="https://api.flutter.dev/flutter/cupertino/CupertinoTabBar-class.html">CupertinoTabBar</a> (iOS-style tab bar) and therefore expects a list of
7173
<a href="https://api.flutter.dev/flutter/widgets/BottomNavigationBarItem-class.html">BottomNavigationBarItem</a>.</p>
74+
<p>Semantics for VoiceOver are intentionally <strong>not</strong> set here.
75+
They are managed at the <a href="../../components_navigation_ouds_tab_bar/OudsTabBar-class.html">OudsTabBar</a> level via a <a href="https://api.flutter.dev/flutter/widgets/Stack-class.html">Stack</a> overlay of
76+
transparent <a href="https://api.flutter.dev/flutter/widgets/Semantics-class.html">Semantics</a> widgets positioned over each tab item, so that
77+
VoiceOver sees exactly one node per tab announcing:
78+
"Label<code>, badge</code>, Tab X of Y".</p>
7279
<ul>
7380
<li><code>context</code> : BuildContext to access theme and layout.</li>
74-
<li><code>controlState</code> to drive icon/top-indicator colors,</li>
81+
<li><code>controlState</code> to drive icon/top-indicator colors.</li>
7582
<li><code>isSelected</code> for the destination selection state.</li>
83+
<li><code>index</code> zero-based position of this item in the tab bar.</li>
84+
<li><code>externalController</code> optional <a href="https://api.flutter.dev/flutter/animation/AnimationController-class.html">AnimationController</a> managed by the
85+
parent <a href="../../components_navigation_ouds_tab_bar/OudsTabBar-class.html">OudsTabBar</a> to survive tab rebuilds on iOS.</li>
7686
</ul>
7787
</section>
7888

@@ -84,28 +94,34 @@ <h2><span>Implementation</span></h2>
8494
BuildContext context,
8595
OudsNavigationBarControlState controlState, {
8696
required bool isSelected,
97+
required int index,
98+
AnimationController? externalController,
8799
}) {
88100
final modifier = OudsNavigationBarStatusModifier(context);
89101

90-
return BottomNavigationBarItem(
91-
label: label,
92-
icon: _buildBadgeIconBottomNavigationBarItem(
93-
context,
94-
icon,
95-
modifier,
96-
controlState,
97-
badge,
98-
isSelected: isSelected,
99-
),
100-
activeIcon: _buildBadgeIconBottomNavigationBarItem(
102+
&#47;&#47; Build the raw icon widget.
103+
&#47;&#47; All semantics are suppressed here — VoiceOver nodes are managed by
104+
&#47;&#47; the OudsTabBar Stack overlay to guarantee a single node per tab.
105+
final iconWidget = ExcludeSemantics(
106+
child: _buildBadgeIconBottomNavigationBarItem(
101107
context,
102108
icon,
103109
modifier,
104110
controlState,
105111
badge,
106112
isSelected: isSelected,
113+
index: index,
114+
externalController: externalController,
107115
),
108116
);
117+
118+
return BottomNavigationBarItem(
119+
&#47;&#47; Keep the real label for visual display under the icon.
120+
label: label,
121+
&#47;&#47; All semantics suppressed — managed by OudsTabBar Stack overlay.
122+
icon: iconWidget,
123+
activeIcon: iconWidget,
124+
);
109125
}</code></pre>
110126
</section>
111127

‎docs/prPreview/761/components_navigation_ouds_navigation_bar_item/OudsNavigationBarItem/toNavigationDestination.html‎

Lines changed: 48 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,9 @@ <h1><span class="kind-method">toNavigationDestination</span> method
5858
<span class="name ">toNavigationDestination</span>(<wbr><ol class="parameter-list"> <li><span class="parameter" id="toNavigationDestination-param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span></li>
5959
<li><span class="parameter" id="toNavigationDestination-param-controlState"><span class="type-annotation">OudsNavigationBarControlState</span> <span class="parameter-name">controlState</span>, {</span></li>
6060
<li><span class="parameter" id="toNavigationDestination-param-isSelected"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/bool-class.html">bool</a></span> <span class="parameter-name">isSelected</span>, </span></li>
61+
<li><span class="parameter" id="toNavigationDestination-param-index"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/int-class.html">int</a></span> <span class="parameter-name">index</span>, </span></li>
62+
<li><span class="parameter" id="toNavigationDestination-param-total"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/int-class.html">int</a></span> <span class="parameter-name">total</span>, </span></li>
63+
<li><span class="parameter" id="toNavigationDestination-param-onTap"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-ui/VoidCallback.html">VoidCallback</a>?</span> <span class="parameter-name">onTap</span>, </span></li>
6164
</ol>})
6265

6366

@@ -74,6 +77,8 @@ <h1><span class="kind-method">toNavigationDestination</span> method
7477
<li><code>controlState</code> drives icon/top-indicator colors according to the current
7578
OUDS navigation control state.</li>
7679
<li><code>isSelected</code> indicates whether this destination is currently selected.</li>
80+
<li><code>index</code> zero-based position of this item in the navigation bar.</li>
81+
<li><code>total</code> total number of destinations in the navigation bar.</li>
7782
</ul>
7883
</section>
7984

@@ -85,33 +90,57 @@ <h2><span>Implementation</span></h2>
8590
BuildContext context,
8691
OudsNavigationBarControlState controlState, {
8792
required bool isSelected,
93+
required int index,
94+
required int total,
95+
VoidCallback? onTap,
8896
}) {
8997
final modifier = OudsNavigationBarStatusModifier(context);
9098
final bar = OudsTheme.of(context).componentsTokens(context).bar;
9199

100+
&#47;&#47; Builds the full TalkBack label: &quot;Label[, badge], Tab X of Y&quot;
101+
final localizations = MaterialLocalizations.of(context);
102+
final contentLabel = OudsNavigationBarA11y.buildTabSemanticLabel(
103+
label,
104+
badge,
105+
);
106+
final fullSemanticLabel =
107+
&#39;$contentLabel, ${localizations.tabLabel(tabIndex: index + 1, tabCount: total)}&#39;;
108+
92109
return Column(
93110
mainAxisSize: MainAxisSize.min,
94111
children: [
95-
&#47;&#47; Top active indicator bar (optional visual indicator for selection)
96-
_buildTopIndicatorBar(context, bar, isSelected, controlState),
112+
&#47;&#47; Android: no external controller, uses internal animation
113+
_buildTopIndicatorBar(context, bar, isSelected, controlState, index),
97114
Flexible(
98-
child: NavigationDestination(
99-
label: label,
100-
icon: _buildBadgeIconNavigationDestination(
101-
context,
102-
icon,
103-
modifier,
104-
controlState,
105-
badge,
106-
isSelected: isSelected,
107-
),
108-
selectedIcon: _buildBadgeIconNavigationDestination(
109-
context,
110-
icon,
111-
modifier,
112-
controlState,
113-
badge,
114-
isSelected: isSelected,
115+
child: Semantics(
116+
&#47;&#47; Override NavigationDestination&#39;s internal semantics to enforce
117+
&#47;&#47; the correct reading order: &quot;Label[, badge], Tab X of Y&quot;.
118+
&#47;&#47; onTap restores the activation action lost by ExcludeSemantics.
119+
label: fullSemanticLabel,
120+
selected: isSelected,
121+
onTap: onTap,
122+
child: ExcludeSemantics(
123+
&#47;&#47; Suppresses NavigationDestination&#39;s own semantic nodes,
124+
&#47;&#47; which would otherwise produce a wrong TalkBack reading order.
125+
child: NavigationDestination(
126+
label: label,
127+
icon: _buildBadgeIconNavigationDestination(
128+
context,
129+
icon,
130+
modifier,
131+
controlState,
132+
badge,
133+
isSelected: isSelected,
134+
),
135+
selectedIcon: _buildBadgeIconNavigationDestination(
136+
context,
137+
icon,
138+
modifier,
139+
controlState,
140+
badge,
141+
isSelected: isSelected,
142+
),
143+
),
115144
),
116145
),
117146
),

‎docs/prPreview/761/components_navigation_ouds_navigation_bar_item/OudsNavigationBarItemBadge-class.html‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -54,17 +54,10 @@ <h1><span class="kind-class">OudsNavigationBarItemBadge</span> class
5454

5555

5656
<section class="desc markdown">
57-
<p>Represents an optional badge attached to a navigation item.</p>
58-
<p>Parameters:</p>
59-
<ul>
60-
<li><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItemBadge/contentDescription.html">contentDescription</a> : Semantic description for accessibility.</li>
61-
<li><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItemBadge/count.html">count</a> : Optional integer to display as badge count.</li>
62-
</ul>
63-
<p>Example usage:</p>
64-
<pre class="language-dart"><code class="language-dart">OudsNavigationBarItemBadge(
65-
contentDescription: 'Unread messages',
66-
count: 5,
67-
);
57+
<p>An optional badge attached to a navigation item.</p>
58+
<p><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItemBadge/contentDescription.html">contentDescription</a> is the semantic text announced by screen readers.
59+
<a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItemBadge/count.html">count</a> is the optional numeric value displayed inside the badge.</p>
60+
<pre class="language-dart"><code class="language-dart">OudsNavigationBarItemBadge(contentDescription: 'Unread messages', count: 5);
6861
</code></pre>
6962
</section>
7063

‎docs/prPreview/761/components_navigation_ouds_navigation_bar_item/index.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,15 +69,15 @@ <h2>Classes</h2>
6969

7070
</dt>
7171
<dd>
72-
An OUDS navigation bar item.
72+
A single destination in an OUDS bottom navigation component.
7373
</dd>
7474

7575
<dt id="OudsNavigationBarItemBadge">
7676
<span class="name "><a href="../components_navigation_ouds_navigation_bar_item/OudsNavigationBarItemBadge-class.html">OudsNavigationBarItemBadge</a></span>
7777

7878
</dt>
7979
<dd>
80-
Represents an optional badge attached to a navigation item.
80+
An optional badge attached to a navigation item.
8181
</dd>
8282

8383
</dl>

0 commit comments

Comments
 (0)