@xsolla/xui-svg-themed 0.149.1 → 0.151.0

package/README.md

@@ -1,82 +1,75 @@
-# SVG Themed
+# SvgThemed
 
-A React component that wraps SVG content and automatically resolves theme tokens (like `$colors_core_text_primary`) to actual theme values, enabling theme-aware custom SVG graphics.
+A React SVG wrapper that resolves `$`-prefixed token strings on `fill`, `stroke`, `stopColor`, and `color` attributes to live theme values. Any standard SVG attribute (`width`, `height`, `viewBox`, etc.) is accepted via `SVGProps<SVGSVGElement>`.
 
 ## Installation
 
 ```bash
 npm install @xsolla/xui-svg-themed
-# or
-yarn add @xsolla/xui-svg-themed
 ```
 
-## Demo
+## Imports
 
-### Basic Usage
+```tsx
+import { SvgThemed, type SvgThemedProps } from '@xsolla/xui-svg-themed';
+```
+
+## Quick start
 
 ```tsx
 import * as React from 'react';
 import { SvgThemed } from '@xsolla/xui-svg-themed';
 
-export default function BasicSvg() {
+export default function QuickStart() {
   return (
     <SvgThemed width={24} height={24} viewBox="0 0 24 24">
-      <circle
-        cx={12}
-        cy={12}
-        r={10}
-        fill="$colors_core_text_primary"
-      />
+      <circle cx={12} cy={12} r={10} fill="$colors_core_text_primary" />
     </SvgThemed>
   );
 }
 ```
 
-### With Theme Tokens
+## API Reference
 
-```tsx
-import * as React from 'react';
-import { SvgThemed } from '@xsolla/xui-svg-themed';
+### `<SvgThemed>`
 
-export default function ThemedIcon() {
-  return (
-    <SvgThemed width={32} height={32} viewBox="0 0 32 32">
-      <rect
-        x={4}
-        y={4}
-        width={24}
-        height={24}
-        rx={4}
-        fill="$colors_control_faint_bg"
-      />
-      <path
-        d="M16 8L20 16H12L16 8Z"
-        fill="$colors_core_text_brand"
-      />
-    </SvgThemed>
-  );
-}
-```
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | SVG content. Themed token strings are resolved recursively. |
+| `data-testid` | `string` | — | Test identifier. |
 
-## Anatomy
+Standard SVG attributes (`width`, `height`, `viewBox`, `xmlns`, `role`, `fill`, `stroke`, etc.) come from `SVGProps<SVGSVGElement>` and are forwarded to the underlying `<svg>` element — they are not enumerated as explicit props.
 
-```jsx
-import { SvgThemed } from '@xsolla/xui-svg-themed';
+Inherits `ThemeOverrideProps` (`themeMode`, `themeProductContext`).
 
-<SvgThemed
-  width={24}
-  height={24}
-  viewBox="0 0 24 24"
-  // All standard SVG props
->
-  <path fill="$colors_core_text_primary" d="..." />
-  <circle stroke="$colors_core_text_brand" />
-</SvgThemed>
-```
+### Themeable attributes
+
+The following descendant attributes are scanned recursively and replaced when their string value starts with `$`:
+
+- `fill`
+- `stroke`
+- `stopColor`
+- `color`
+
+## Theming
+
+Token strings start with `$` and map to theme paths. Tokens not in the map are passed through unchanged.
+
+| Token | Theme path |
+| --- | --- |
+| `$colors_core_text_primary` | `content.primary` |
+| `$colors_core_text_secondary` | `content.secondary` |
+| `$colors_core_text_tertiary` | `content.tertiary` |
+| `$colors_core_text_brand` | `content.brand.primary` |
+| `$colors_core_text_success` | `content.success.primary` |
+| `$colors_core_text_warning` | `content.warning.primary` |
+| `$colors_core_text_alert` | `content.alert.primary` |
+| `$colors_core_text_neutral` | `content.neutral.primary` |
+| `$colors_control_faint_bg` | `control.mono.secondary.bg` |
 
 ## Examples
 
-### Custom Status Icon
+### Themed status icon
 
 ```tsx
 import * as React from 'react';
@@ -85,12 +78,7 @@ import { SvgThemed } from '@xsolla/xui-svg-themed';
 export default function StatusIcon() {
   return (
     <SvgThemed width={24} height={24} viewBox="0 0 24 24">
-      <circle
-        cx={12}
-        cy={12}
-        r={10}
-        fill="$colors_core_text_success"
-      />
+      <circle cx={12} cy={12} r={10} fill="$colors_core_text_success" />
       <path
         d="M8 12L11 15L16 9"
         stroke="#fff"
@@ -104,7 +92,7 @@ export default function StatusIcon() {
 }
 ```
 
-### Illustration with Multiple Colors
+### Multi-colour illustration
 
 ```tsx
 import * as React from 'react';
@@ -113,35 +101,15 @@ import { SvgThemed } from '@xsolla/xui-svg-themed';
 export default function Illustration() {
   return (
     <SvgThemed width={100} height={100} viewBox="0 0 100 100">
-      {/* Background */}
-      <rect
-        width={100}
-        height={100}
-        rx={12}
-        fill="$colors_control_faint_bg"
-      />
-      {/* Primary shape */}
-      <circle
-        cx={50}
-        cy={40}
-        r={20}
-        fill="$colors_core_text_brand"
-      />
-      {/* Secondary shape */}
-      <rect
-        x={30}
-        y={65}
-        width={40}
-        height={20}
-        rx={4}
-        fill="$colors_core_text_secondary"
-      />
+      <rect width={100} height={100} rx={12} fill="$colors_control_faint_bg" />
+      <circle cx={50} cy={40} r={20} fill="$colors_core_text_brand" />
+      <rect x={30} y={65} width={40} height={20} rx={4} fill="$colors_core_text_secondary" />
     </SvgThemed>
   );
 }
 ```
 
-### Badge with Gradient
+### Gradient with token stops
 
 ```tsx
 import * as React from 'react';
@@ -157,74 +125,12 @@ export default function GradientBadge() {
         </linearGradient>
       </defs>
       <circle cx={24} cy={24} r={20} fill="url(#grad)" />
-      <text
-        x={24}
-        y={24}
-        textAnchor="middle"
-        dominantBaseline="central"
-        fill="#fff"
-        fontSize={16}
-        fontWeight="bold"
-      >
-        XP
-      </text>
     </SvgThemed>
   );
 }
 ```
 
-## API Reference
-
-### SvgThemed
-
-**SvgThemedProps:**
-
-Extends all standard SVG element attributes plus:
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| children | `ReactNode` | - | SVG content with theme tokens. |
-| width | `number \| string` | - | SVG width. |
-| height | `number \| string` | - | SVG height. |
-| viewBox | `string` | - | SVG viewBox attribute. |
-
-## Supported Theme Tokens
-
-Use these token strings prefixed with `$` for theme-aware colors:
-
-| Token | Theme Path |
-| :---- | :--------- |
-| `$colors_core_text_primary` | `content.primary` |
-| `$colors_core_text_secondary` | `content.secondary` |
-| `$colors_core_text_tertiary` | `content.tertiary` |
-| `$colors_core_text_brand` | `content.brand.primary` |
-| `$colors_core_text_success` | `content.success.primary` |
-| `$colors_core_text_warning` | `content.warning.primary` |
-| `$colors_core_text_alert` | `content.alert.primary` |
-| `$colors_core_text_neutral` | `content.neutral.primary` |
-| `$colors_control_faint_bg` | `control.mono.secondary.bg` |
-
-## Themeable Properties
-
-The following SVG properties are automatically resolved:
-
-- `fill`
-- `stroke`
-- `stopColor`
-- `color`
-
-## Use Cases
-
-- Custom icons not available in icon packages
-- Theme-aware illustrations
-- Dynamic SVG graphics that adapt to light/dark modes
-- Brand-specific visual elements
-- Decorative graphics with theme integration
-
-## How It Works
+## Accessibility
 
-1. SvgThemed wraps your SVG content
-2. It recursively processes all child elements
-3. Properties starting with `$` are matched against token map
-4. Tokens are replaced with actual theme color values
-5. Result is a fully themed SVG that updates with theme changes
+- Pass `role="img"` and an `aria-label` (or `<title>` element) when the SVG conveys meaning.
+- Set `aria-hidden="true"` for decorative graphics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xsolla/xui-svg-themed",
-  "version": "0.149.1",
+  "version": "0.151.0",
   "main": "./web/index.js",
   "module": "./web/index.mjs",
   "types": "./web/index.d.ts",
@@ -10,8 +10,8 @@
     "build:native": "PLATFORM=native tsup"
   },
   "dependencies": {
-    "@xsolla/xui-core": "0.149.1",
-    "@xsolla/xui-primitives-core": "0.149.1"
+    "@xsolla/xui-core": "0.151.0",
+    "@xsolla/xui-primitives-core": "0.151.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0",