@xsolla/xui-tag-label 0.189.2 → 0.190.0

package/README.md

@@ -3,7 +3,65 @@
 A specialised cross-platform identification and categorisation tag composed of optional segments — entity, subentity, ID, label, rarity, status, and a custom slot.
 
 <!-- BEGIN:xui-mcp-instructions:tag-label -->
-This is a core narrative element within the Xsolla brand. They represent the identification and categorisation of items — so that whenever they are seen within brand outputs, the audience recognises that they are engaging with something that is part of a much larger collection.
+A composite identification label that encodes the full semantic identity of an entity in the Xsolla Archive — its type, sub-type, unique ID, name, rarity, and status — as a horizontal sequence of joined chip modules. Each module contains either text or an icon displayed on a single line with no line breaks. The modules are joined together with no gaps between them, forming a continuous visual strip. Each slot is independently shown or hidden depending on context.
+
+TagLabel is part of Xsolla's Functional Labels system — a branded language for categorising and communicating the attributes of every unique object within the Xsolla Archive. Functional labels have standardised colour profiles for both Light mode and Dark mode; status symbols are shared between both profiles and do not change.
+
+### When to use
+- To identify a game item, product, or account entity with structured metadata in one line
+- In admin panels, CMS interfaces, and back-office tools where operators work with entities across multiple entity types simultaneously
+- In search results, filter outputs, and lookup fields where multiple entity attributes must be visible at once
+- When the difference between entity types (Item vs Product vs Account) must be immediately scannable
+
+### When not to use
+- For simple status labels — use a Badge or StatusDropdown
+- When only the entity name needs to be shown — use a plain text label
+- For public-facing storefronts where internal entity taxonomy is not relevant to the end user
+- When only one attribute needs to be communicated — use a single appropriate chip rather than a full TagLabel
+
+### Brand context: Xsolla Archive
+- Functional Labels are the visual language of the Xsolla Archive — the internal catalogue of all items, products, and accounts in the Xsolla platform. The three core pillars of the Archive are Items, Products, and Accounts. Every TagLabel begins with an icon that identifies which pillar the entity belongs to; subsequent modules provide pillar-specific information.
+- The Archive narrative is reinforced by the visual presence of the ID module: even when other modules are removed for space reasons, the ID number is the most visually representative element of the brand's Archive identity and should be preserved wherever possible.
+
+### Content guidelines
+- Entity and Subentity labels — use the canonical taxonomy names exactly as defined in the system. Do not create custom entity or subentity labels — they must match the platform's entity model.
+- ID chip — always show the full entity ID. Never abbreviate or truncate the ID value — it is the primary machine-readable identifier and must be copy-able.
+- Name chip — use the entity's display name as stored in the system. If the name is very long, truncate with an ellipsis and show the full name in a tooltip.
+- Rarity chip — the colour of the rarity icon is determined by the entity's rarity tier in the system. Do not override the colour manually.
+- Custom slot — keep custom slot content to a single short value (a number, a price, a version string). Do not place multi-word labels in the custom slot.
+
+### Behaviour guidelines
+- Read-only by default — TagLabel is a display component. It has no interactive states (hover, press, focus). If a TagLabel must be clickable (e.g. to navigate to the entity's detail page), wrap it in a Link or a clickable container at the product level.
+- Slot visibility — show only the slots that are relevant and available for the entity being displayed. Do not show a Rarity slot for an Account entity. Do not show a Status slot if the entity has no applicable status.
+- ID format — the ID chip always displays the entity's unique identifier with the prefix format used by the system (e.g. x00000001). Do not display raw UUIDs directly — use the system-formatted ID.
+- Custom slot usage — the custom slot at position ⑦ is for supplementary values that do not fit the standard taxonomy. Examples: a version number (v2.3), a price ($9.99), a quantity (×3), or an internal flag. Do not duplicate information already present in another slot.
+- Compact view consistency — apply the same Compact view setting to all TagLabel instances in the same list, table, or card group. Mixing compact and full view labels in the same context breaks visual rhythm.
+- Max width — the full-view TagLabel at its maximum slot configuration is ~403 px wide. Ensure the containing element has enough horizontal space. Do not truncate individual chip text — if space is tight, switch to Compact view=True.
+- ID preservation — the ID module is the most brand-representative element of the Archive narrative. Even when other modules are removed for space reasons, keep the ID visible wherever possible. Remove it only as a last resort.
+
+### Accessibility
+- TagLabel as a whole is a read-only display element. The containing element must have an aria-label that summarises the entity for screen readers — e.g. aria-label=*"Item: Skin, ID x00000001, Dragon Scale, On sale"*.
+- Individual sub-components are decorative within the TagLabel's context — do not expose them as separate focusable or announced elements. Use a single accessible description on the container.
+- Rarity and Status icon chips must not rely on colour alone to communicate meaning (WCAG 1.4.1). Ensure each icon has a distinct shape in addition to colour. Provide a legend or tooltip in the surrounding UI.
+- If the TagLabel is placed inside a clickable container (e.g. a table row that navigates to the entity detail page), the accessible name of the link or button must include the entity's key identifying information — typically the entity type + name + ID.
+- In compact view, icon-only chips must have aria-label or title attributes describing the entity type and subentity type they represent.
+
+### Platform brand guidelines
+- Each platform has its own official badge usage rules. Key general requirements:
+- Do not alter the badge colours, proportions, text, or logo
+- Minimum size — most platforms specify a minimum badge height (commonly 40px, which corresponds to Size=S)
+- Clear space — maintain a minimum clear space around the badge equal to the badge's height or a specified fixed padding (varies by platform)
+- Background contrast — use Palette=Dark on light backgrounds and Palette=Light on dark backgrounds to meet contrast requirements
+- Always check the official brand guidelines page for the specific platforms you are using, as requirements may be updated by the platform.
+
+### Truncation
+- The full set of modules should not — and often cannot — be displayed in every context. The visible content is adjusted to present the most relevant information for each application. There are three truncation strategies:
+- Remove the Name module when the entity can be identified by its ID alone (e.g. in a system log or a data export). The ID is the unique machine-readable identifier and sufficient for lookup.
+- Remove entire modules that are not relevant in the current context — for example, hiding the Subentity module in a filtered list where all entities share the same sub-type, or hiding Rarity for Product and Account entities where rarity is not applicable.
+- Text box truncation (Compact view)
+- Switch .tag-label-entity and .tag-label-subentity to icon-only mode (Compact view=True) when horizontal space is limited. The icon conveys the pillar and sub-type without text.
+
+ID preservation — the ID module is the most visually representative element of the Archive narrative. Even when other modules are removed, try to keep the ID module visible in most applications. Remove it only as a last resort when space is critically constrained.
 <!-- END:xui-mcp-instructions:tag-label -->
 
 ## Installation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-tag-label",
-  "version": "0.189.2",
+  "version": "0.190.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -10,9 +10,9 @@
     "build:native": "PLATFORM=native tsup"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.189.2",
-    "@xsolla/xui-icons": "0.189.2",
-    "@xsolla/xui-primitives-core": "0.189.2"
+    "@xsolla/xui-core": "0.190.0",
+    "@xsolla/xui-icons": "0.190.0",
+    "@xsolla/xui-primitives-core": "0.190.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",