@xsolla/xui-tab-bar 0.149.1 → 0.151.0

package/README.md

@@ -1,26 +1,27 @@
-# Tab Bar
+# TabBar
 
-A cross-platform React tab bar component implementing mobile-style bottom navigation, typically used with React Navigation. Follows WAI-ARIA Tabs pattern with proper keyboard navigation.
+A pill-shaped, segmented-style tab bar that adapts the React Navigation bottom-tab API. Implements the WAI-ARIA Tabs pattern with roving tab index and arrow-key navigation.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-tab-bar
-# or
-yarn add @xsolla/xui-tab-bar
 ```
 
-## Demo
+## Imports
 
-### Basic Tab Bar
+```tsx
+import { TabBar, TabBarItem } from '@xsolla/xui-tab-bar';
+```
+
+## Quick start
 
 ```tsx
 import * as React from 'react';
 import { TabBar } from '@xsolla/xui-tab-bar';
 import { Home, Search, User, Settings } from '@xsolla/xui-icons-base';
 
-export default function BasicTabBar() {
-  // Simulated React Navigation state
+export default function Example() {
   const state = {
     index: 0,
     routes: [
@@ -43,31 +44,50 @@ export default function BasicTabBar() {
       state={state}
       descriptors={descriptors}
       navigation={{ emit: () => ({}), navigate: () => {} }}
+      aria-label="Main navigation"
     />
   );
 }
 ```
 
-## Anatomy
+## API Reference
 
-```jsx
-import { TabBar } from '@xsolla/xui-tab-bar';
+### `<TabBar>`
 
-<TabBar
-  state={navigationState}         // React Navigation state
-  descriptors={descriptors}        // Route descriptors
-  navigation={navigation}          // Navigation object
-  labelPosition="below-icon"       // below-icon or beside-icon
-  backgroundColor={color}          // Custom background
-  activateOnFocus={true}           // Activate tab on focus
-  aria-label="Main navigation"     // Accessible label
-  id="main-tabs"                   // Element ID
-/>
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `state` | `{ index: number; routes: { key: string; name: string; params?: object }[] }` | - | React Navigation state. Required. |
+| `descriptors` | `Record<string, { options: TabBarRouteOptions }>` | - | Per-route options keyed by `route.key`. Required. |
+| `navigation` | `{ navigate: (name, params?) => void; emit: (opts) => any }` | - | React Navigation navigation object. Required. |
+| `labelPosition` | `'below-icon' \| 'beside-icon'` | `'below-icon'` | Label position relative to icon. |
+| `backgroundColor` | `string` | segmented-control bg token | Container background colour. |
+| `activateOnFocus` | `boolean` | `true` | Activate a tab as soon as it receives keyboard focus. When `false`, arrow keys only move focus and Enter/Space activates. |
+| `aria-label` | `string` | `'Tab navigation'` | Accessible label for the tablist. |
+| `aria-labelledby` | `string` | - | ID of an external labelling element. |
+| `id` | `string` | - | Container ID; used to derive per-tab IDs. |
+| `testID` | `string` | `'tab-bar-container'` | Test identifier. |
+
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
+
+#### Route options (per descriptor)
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `tabBarIcon` | `(props: { focused, color, size }) => ReactNode` | Icon render function. Called with `size={24}`. |
+| `tabBarLabel` | `string \| ((props: { focused, color, position }) => ReactNode)` | Label override. |
+| `title` | `string` | Fallback label when `tabBarLabel` is unset. |
+| `tabBarBadge` | `string \| number` | Badge content rendered top-right of the icon. |
+| `tabBarShowLabel` | `boolean` | Set `false` to hide the label. |
+| `tabBarAccessibilityLabel` | `string` | Override per-tab accessible label. |
+| `tabBarTestID` | `string` | Per-tab test identifier. |
+
+### `<TabBarItem>`
+
+Lower-level item; usually rendered for you by `<TabBar>`. Exported for custom layouts. Accepts `label`, `icon`, `badge`, `focused`, `onPress`, `onLongPress`, `labelPosition`, `accessibilityLabel`, `index`, `tabCount`, plus refs and `testID`. Inherits `ThemeOverrideProps`.
 
 ## Examples
 
-### With React Navigation
+### React Navigation integration
 
 ```tsx
 import * as React from 'react';
@@ -79,43 +99,35 @@ const Tab = createBottomTabNavigator();
 
 export default function AppNavigator() {
   return (
-    <Tab.Navigator
-      tabBar={(props) => <TabBar {...props} />}
-    >
+    <Tab.Navigator tabBar={(props) => <TabBar {...props} aria-label="Main" />}>
       <Tab.Screen
         name="Home"
         component={HomeScreen}
-        options={{
-          tabBarIcon: ({ size, color }) => <Home size={size} color={color} />,
-        }}
+        options={{ tabBarIcon: ({ size, color }) => <Home size={size} color={color} /> }}
       />
       <Tab.Screen
         name="Profile"
         component={ProfileScreen}
-        options={{
-          tabBarIcon: ({ size, color }) => <User size={size} color={color} />,
-        }}
+        options={{ tabBarIcon: ({ size, color }) => <User size={size} color={color} /> }}
       />
       <Tab.Screen
         name="Settings"
         component={SettingsScreen}
-        options={{
-          tabBarIcon: ({ size, color }) => <Settings size={size} color={color} />,
-        }}
+        options={{ tabBarIcon: ({ size, color }) => <Settings size={size} color={color} /> }}
       />
     </Tab.Navigator>
   );
 }
 ```
 
-### With Badges
+### With badges
 
 ```tsx
 import * as React from 'react';
 import { TabBar } from '@xsolla/xui-tab-bar';
 import { Home, Bell, ShoppingCart, User } from '@xsolla/xui-icons-base';
 
-export default function TabBarWithBadges() {
+export default function Example() {
   const state = {
     index: 0,
     routes: [
@@ -132,14 +144,14 @@ export default function TabBarWithBadges() {
       options: {
         tabBarIcon: ({ size }) => <Bell size={size} />,
         title: 'Notifications',
-        tabBarBadge: 3, // Shows badge with count
+        tabBarBadge: 3,
       },
     },
     cart: {
       options: {
         tabBarIcon: ({ size }) => <ShoppingCart size={size} />,
         title: 'Cart',
-        tabBarBadge: '!', // Shows badge with text
+        tabBarBadge: '!',
       },
     },
     profile: { options: { tabBarIcon: ({ size }) => <User size={size} />, title: 'Profile' } },
@@ -155,97 +167,31 @@ export default function TabBarWithBadges() {
 }
 ```
 
-### Custom Styling
+### Manual focus activation
+
+Set `activateOnFocus={false}` to require Enter or Space to commit a selection — useful when activation has side effects.
 
 ```tsx
 import * as React from 'react';
 import { TabBar } from '@xsolla/xui-tab-bar';
-import { Home, Search, User } from '@xsolla/xui-icons-base';
-
-export default function CustomStyledTabBar() {
-  const state = {
-    index: 0,
-    routes: [
-      { key: 'home', name: 'Home' },
-      { key: 'search', name: 'Search' },
-      { key: 'profile', name: 'Profile' },
-    ],
-  };
-
-  const descriptors = {
-    home: { options: { tabBarIcon: ({ size }) => <Home size={size} />, title: 'Home' } },
-    search: { options: { tabBarIcon: ({ size }) => <Search size={size} />, title: 'Search' } },
-    profile: { options: { tabBarIcon: ({ size }) => <User size={size} />, title: 'Profile' } },
-  };
 
+export default function Example({ state, descriptors, navigation }) {
   return (
     <TabBar
       state={state}
       descriptors={descriptors}
-      navigation={{ emit: () => ({}), navigate: () => {} }}
-      backgroundColor="#1a1a1a"
-      labelPosition="below-icon"
+      navigation={navigation}
+      activateOnFocus={false}
+      aria-label="Settings sections"
     />
   );
 }
 ```
 
-## API Reference
-
-### TabBar
-
-**TabBarProps:**
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| state | `NavigationState` | - | React Navigation state object. |
-| descriptors | `Descriptors` | - | Route descriptor objects. |
-| navigation | `Navigation` | - | Navigation object with emit/navigate. |
-| labelPosition | `"below-icon" \| "beside-icon"` | `"below-icon"` | Label position relative to icon. |
-| backgroundColor | `string` | theme background | Custom background color. |
-| activateOnFocus | `boolean` | `true` | Navigate on focus (keyboard). |
-| aria-label | `string` | `"Tab navigation"` | Accessible label. |
-| aria-labelledby | `string` | - | ID of labelling element. |
-| id | `string` | - | Element ID for accessibility. |
-| testID | `string` | - | Test identifier. |
-
-### Route Options
-
-Each route in descriptors can have these options:
-
-| Option | Type | Description |
-| :----- | :--- | :---------- |
-| tabBarIcon | `(props) => ReactNode` | Icon render function. |
-| tabBarLabel | `string \| (props) => ReactNode` | Tab label. |
-| title | `string` | Fallback label if tabBarLabel not set. |
-| tabBarBadge | `string \| number` | Badge content. |
-| tabBarShowLabel | `boolean` | Show/hide label. |
-| tabBarAccessibilityLabel | `string` | Custom accessible label. |
-| tabBarTestID | `string` | Test ID for individual tab. |
-
-## Keyboard Navigation
-
-| Key | Action |
-| :-- | :----- |
-| `ArrowRight` / `ArrowDown` | Move to next tab |
-| `ArrowLeft` / `ArrowUp` | Move to previous tab |
-| `Home` | Jump to first tab |
-| `End` | Jump to last tab |
-| `Enter` / `Space` | Activate focused tab |
-
-## Specifications
-
-| Property | Value |
-| :------- | :---- |
-| Height | 60px |
-| Width | 100% |
-| Border | 1px top border |
-
 ## Accessibility
 
-- Uses `role="tablist"` with `aria-orientation="horizontal"`
-- Individual tabs have `role="tab"` with proper `aria-selected`
-- Keyboard navigation follows WAI-ARIA Tabs pattern
-- Focus management between tabs
-- Badge content is announced to screen readers
-- Custom accessibility labels supported per tab
+- Container is `<nav role="tablist" aria-orientation="horizontal">`; each tab is `role="tab"` with `aria-selected`.
+- Roving tab index: only the active tab is in the tab order.
+- Keyboard: `ArrowRight`/`ArrowDown` next, `ArrowLeft`/`ArrowUp` previous (both wrap), `Home`/`End` jump to ends, `Enter`/`Space` activates.
+- The animated selection indicator is `aria-hidden` (web only).
+- Provide `aria-label` or `aria-labelledby` so screen readers can name the tablist.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-tab-bar",
-  "version": "0.149.1",
+  "version": "0.151.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -13,9 +13,9 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@xsolla/xui-badge": "0.149.1",
-    "@xsolla/xui-core": "0.149.1",
-    "@xsolla/xui-primitives-core": "0.149.1"
+    "@xsolla/xui-badge": "0.151.0",
+    "@xsolla/xui-core": "0.151.0",
+    "@xsolla/xui-primitives-core": "0.151.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0"