@xsolla/xui-tabs 0.174.3 → 0.176.0

package/README.md

@@ -1,6 +1,81 @@
 # Tabs
 
 A cross-platform React tab list with two visual variants — `line` (default underlined) and `segmented` (button-group with sliding indicator on web). Implements the WAI-ARIA tablist pattern with full keyboard navigation.
+<!-- BEGIN:xui-mcp-instructions:tabs -->
+A horizontal navigation bar that divides related content into labelled sections. The user switches between sections by clicking a tab item; only one section is active at a time. Each tab can optionally carry a numeric counter badge. Tabs support 2 to 7 items, four sizes, and two alignment modes.
+
+### When to use
+
+To organise content that belongs to the same context into distinct, peer-level views — for example, *"Overview"*, *"Activity"*, *"Settings"* on a profile page
+
+When users need to switch between views without leaving the current page or losing their position in the layout
+
+When the number of views is small (2–7) and all labels fit horizontally without truncation
+
+### When not to use
+
+- When the sections represent a sequence or progression — use a Stepper instead
+- When there are more than 7 tabs — consider a a sidebar navigation, or collapsing less-used items into an overflow menu
+- When the content under each tab is very long and users will rarely switch between them — use anchored sections with a sticky sidebar nav instead
+- As the primary page-level navigation — use a Navigation bar or Sidebar for top-level routing
+
+### Content guidelines
+
+Tab labels — use short nouns or noun phrases: *"Overview"*, *"Activity"*, *"Members"*, *"Settings"*, *"Billing"*. Avoid verbs (*"Manage settings"*) and questions (*"What's new?"*).
+
+Label length — aim for 1–2 words per label. Three words is a maximum. Never truncate a tab label with an ellipsis — if the label is too long, shorten it.
+
+Consistency — all labels in the same Tabs instance should follow the same grammatical form and approximate length. Mixing a single-word label (*"Users"*) with a long phrase (*"Billing & Payments"*) in the same bar looks unbalanced.
+
+Counter values — show only counts that are directly actionable or informative. Avoid counters that show total records (e.g. *"1,452 transactions"*) — that belongs in the panel content, not the tab.
+
+Show the counter only when the number is meaningful — when it communicates something actionable (unread messages, pending approvals, new results)
+- Do not show a counter of 0 — hide the badge entirely when the count is zero
+- Cap the display at 99+. Display *"99+"* for values ≥ 100 rather than showing a 3-digit number
+- The counter palette should match the tab's contextual state: use Brand on the active tab, Default on inactive tabs
+- Badge rendered at the far right of the tab item. Enable with badge=true. Unlike the counter, it carries no number — it signals only that something new or unseen exists in that section.
+- Hide the counter entirely when the count is zero — do not show *"0"*
+
+### Behaviour guidelines
+
+Tab switching — clicking a Default tab immediately switches the active view: the clicked tab transitions to State=Active, the previously active tab returns to State=Default, and the associated content panel below is shown/hidden accordingly. There is no transition animation on the content unless the product design calls for it.
+
+Active state persistence — the active tab should be preserved across filter changes, searches, and other in-page interactions. Only navigate away from the active tab if the user explicitly clicks a different one.
+
+Disabled tabs — use State=Disable only when a section is temporarily inaccessible (e.g. insufficient permissions, feature not yet available). Always provide a tooltip or nearby explanation for why the tab is disabled. Never disable all tabs simultaneously.
+
+Counter updates — counter values should update in real time when new data arrives (e.g. a new message). Update the .counter-tab-item value without remounting the Tabs component. If the count drops to 0, remove the badge rather than showing *"0"*.
+
+Overflow handling — the Tabs component does not support horizontal scrolling or overflow menus natively. If the number of items exceeds 7 or the labels overflow their containers, this is a design problem — shorten the labels or reduce the item count rather than implementing a scroll container.
+
+URL routing — when tabs represent different routes or states that should be bookmarkable or shareable, reflect the active tab in the URL (query param or path segment). On page load, restore the active tab from the URL.
+
+Align left with dynamic content — when Align left=True and tab labels can change at runtime (e.g. localised strings of varying length), ensure the container has a minimum width and the tab bar does not collapse narrower than the shortest label.
+
+### Accessibility
+
+The Tabs container must use role=*"tablist"* with an aria-label describing the group (e.g. aria-label=*"Account sections"*).
+
+Each .tab-item must use role=*"tab"* with aria-selected=*"true"* for the active tab and aria-selected=*"false"* for all others. Disabled tabs must also have aria-disabled=*"true"*.
+
+Each tab must have aria-controls pointing to the id of its associated content panel. The content panel must have role=*"tabpanel"* and aria-labelledby pointing back to the tab's id.
+Keyboard navigation within the tab list:
+- ← / → arrows move focus between tabs (automatic activation or manual activation depending on product preference)
+- Home moves focus to the first tab; End moves focus to the last tab
+- Enter / Space activates the focused tab in manual-activation mode
+- Tab moves focus out of the tab list into the active panel's content
+
+← / → arrows move focus between tabs (automatic activation or manual activation depending on product preference)
+- Home moves focus to the first tab; End moves focus to the last tab
+- Enter / Space activates the focused tab in manual-activation mode
+- Tab moves focus out of the tab list into the active panel's content
+- When a counter is present, include its value in the tab's aria-label — e.g. aria-label=*"Activity, 5 unread"* — so screen readers announce the count without requiring navigation to the badge.
+- When a badge is present (dot only, no number), include a qualitative description in aria-label — e.g. aria-label=*"Messages, new"*.
+- Icon-only tabs (label=false) must have aria-label with the tab name — the icon alone is not sufficient for screen readers.
+- Decorative icons within a tab (when a label is also present) must have aria-hidden=*"true"* so they are not announced redundantly alongside the label.
+- Disabled tabs must remain focusable (do not use tabindex=*"-1"* on disabled tabs) so keyboard users can discover them. Announce the reason they are disabled via aria-describedby.
+- The active indicator underline must not be communicated by colour alone — the aria-selected attribute is the primary signal for assistive technology.
+<!-- END:xui-mcp-instructions:tabs -->
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-tabs",
-  "version": "0.174.3",
+  "version": "0.176.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -12,9 +12,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@xsolla/xui-badge": "0.174.3",
-    "@xsolla/xui-core": "0.174.3",
-    "@xsolla/xui-primitives-core": "0.174.3"
+    "@xsolla/xui-badge": "0.176.0",
+    "@xsolla/xui-core": "0.176.0",
+    "@xsolla/xui-primitives-core": "0.176.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",