@xsolla/xui-core 0.128.0 → 0.129.0

package/README.md

@@ -27,31 +27,92 @@ function MyComponent() {
 }
 ```
 
+Per-component theme overrides with `useResolvedTheme`:
+
+```tsx
+import { useResolvedTheme, ThemeOverrideProps } from '@xsolla/xui-core';
+
+type MyWidgetProps = ThemeOverrideProps & { label: string };
+
+function MyWidget({ label, themeMode, themeProductContext }: MyWidgetProps) {
+  const { theme, mode } = useResolvedTheme({ themeMode, themeProductContext });
+  return <div style={{ color: theme.colors.content.primary }}>{label}</div>;
+}
+
+// Usage — override theme per-instance without nesting providers
+<MyWidget label="Global theme" />
+<MyWidget label="Light override" themeMode="light" />
+```
+
 ## Available Theme Modes
 
 | Mode | Theme |
 |------|-------|
-| `"light"` | Pentagram Light (default) |
 | `"dark"` | Pentagram Dark (default) |
-| `"xsollaLight"` | Xsolla Light |
-| `"xsollaDark"` | Xsolla Dark |
+| `"light"` | Pentagram Light |
 | `"ltg-dark"` | LTG Dark |
 
-Aliases: `"pentagram-light"`, `"pentagram-dark"`, `"xsolla-light"`, `"xsolla-dark"`
+## Per-Component Overrides
+
+Every component accepts `themeMode` and `themeProductContext` props to override the global provider:
+
+```tsx
+<Button themeMode="light" themeProductContext="b2c">Override Both</Button>
+```
+
+For custom components, use `useResolvedTheme` instead of `useDesignSystem`.
 
 ## Exports
 
 - `XUIProvider` — Root context provider; accepts `initialMode` (see theme modes above)
 - `useDesignSystem` — Hook returning `{ theme, mode, setMode }`; falls back to dark theme if no provider
+- `useResolvedTheme` — Hook returning resolved theme with per-component overrides applied; same return shape as `useDesignSystem`
+- `ThemeOverrideProps` — Type: `{ themeMode?: ThemeMode; themeProductContext?: ProductContext }`
 - `themeConfig` — Function returning the full theme object for a given `ThemeMode`
 - `useId` — Stable unique ID hook; polyfills `React.useId` for React < 18
 - `ModalIdContext` — Context holding the current modal's ID for portal-based components
 - `useModalId` — Hook returning the current modal ID, or `null` if outside a modal
-- `ThemeMode` — Type: `"dark"` | `"light"` | `"xsollaLight"` | `"xsollaDark"` | `"ltg-dark"` | aliases
+- `ThemeMode` — Type: `"dark"` | `"light"` | `"ltg-dark"`
 - `ThemeColors` — Type of the colour token object
 - `colors` — Raw colour tokens for all themes
 - `spacing` — Spacing scale (`xs`, `s`, `m`, `l`, `xl`)
 - `radius` — Border-radius tokens (button, card, input, tag, avatar variants)
 - `shadow` — Shadow tokens
 - `fonts` — Font-family definitions
+- `useResolvedTheme` — Hook that merges per-component `themeMode`/`themeProductContext` overrides with global context; returns same shape as `useDesignSystem`
+- `ThemeOverrideProps` — Interface adding optional `themeMode` and `themeProductContext` to component props
 - `isWeb` / `isNative` / `isIOS` / `isAndroid` — Platform detection booleans
+
+## Per-Component Theme Override
+
+Every component accepts optional `themeMode` and `themeProductContext` props to override the global theme on a per-instance basis, without nesting additional providers.
+
+`useResolvedTheme` is the hook that powers this. It accepts an optional overrides object and returns the same `{ theme, mode, productContext }` shape as `useDesignSystem`:
+
+```tsx
+import { useResolvedTheme, ThemeOverrideProps } from '@xsolla/xui-core';
+import { Box, Text } from '@xsolla/xui-primitives';
+
+type CardProps = ThemeOverrideProps & { title: string };
+
+export const Card = ({ title, themeMode, themeProductContext }: CardProps) => {
+  const { theme } = useResolvedTheme({ themeMode, themeProductContext });
+
+  return (
+    <Box backgroundColor={theme.colors.surface.primary}>
+      <Text color={theme.colors.content.primary}>{title}</Text>
+    </Box>
+  );
+};
+```
+
+```tsx
+// Consumer usage
+<XUIProvider initialMode="dark">
+  <Card title="Dark card" />
+  <Card title="Light card" themeMode="light" />
+  <Card title="Paystation card" themeMode="light" themeProductContext="paystation" />
+</XUIProvider>
+```
+
+When no overrides are passed, `useResolvedTheme` returns the global theme object by reference — zero overhead compared to `useDesignSystem`.