@xsolla/xui-avatar 0.141.0 → 0.141.1

package/README.md

@@ -1,308 +0,0 @@
-# Avatar
-
-A cross-platform React avatar component that displays user images, icons, or text initials. Supports badges for notifications and can be grouped together.
-
-## Installation
-
-```bash
-npm install @xsolla/xui-avatar
-# or
-yarn add @xsolla/xui-avatar
-```
-
-## Demo
-
-### Basic Avatar
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-
-export default function BasicAvatar() {
-  return (
-    <div style={{ display: 'flex', gap: 16 }}>
-      <Avatar src="https://example.com/user.jpg" />
-      <Avatar text="JD" />
-      <Avatar /> {/* Default user icon */}
-    </div>
-  );
-}
-```
-
-### Avatar Sizes
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-
-export default function AvatarSizes() {
-  return (
-    <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
-      <Avatar size="xs" text="XS" />
-      <Avatar size="sm" text="S" />
-      <Avatar size="md" text="M" />
-      <Avatar size="lg" text="L" />
-      <Avatar size="xl" text="XL" />
-    </div>
-  );
-}
-```
-
-### Avatar with Badge
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-
-export default function AvatarWithBadge() {
-  return (
-    <div style={{ display: 'flex', gap: 24 }}>
-      <Avatar src="https://example.com/user.jpg" badge />
-      <Avatar src="https://example.com/user.jpg" badge badgeCount={5} />
-      <Avatar src="https://example.com/user.jpg" badge badgeCount={99} badgeTone="alert" />
-    </div>
-  );
-}
-```
-
-### Square Avatar
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-
-export default function SquareAvatar() {
-  return (
-    <div style={{ display: 'flex', gap: 16 }}>
-      <Avatar src="https://example.com/user.jpg" />
-      <Avatar src="https://example.com/user.jpg" square />
-    </div>
-  );
-}
-```
-
-## Anatomy
-
-Import the component and use it directly:
-
-```jsx
-import { Avatar } from '@xsolla/xui-avatar';
-
-<Avatar
-  src="image-url"            // Image source URL
-  text="AB"                  // Text/initials when no image
-  icon={<CustomIcon />}      // Custom icon when no image
-  size="md"                   // Size variant
-  square={false}             // Square vs circular
-  badge={false}              // Show notification badge
-  badgeCount={5}             // Badge count
-  badgeTone="brand"          // Badge color tone
-  stroke={false}             // Show border
-  backgroundColor="#color"   // Custom background
-  onClick={handleClick}      // Click handler
-/>
-```
-
-## Examples
-
-### Avatar with Background Color
-
-Use `backgroundColor` to set a custom background. You can pass any CSS color string, or use a theme token such as `theme.colors.background.brand.primary` for the standard brand color.
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-import { useDesignSystem } from '@xsolla/xui-core';
-
-export default function AvatarWithBackground() {
-  const { theme } = useDesignSystem();
-
-  return (
-    <div style={{ display: 'flex', gap: 16 }}>
-      {/* Using a theme token (recommended) */}
-      <Avatar backgroundColor={theme.colors.background.brand.primary} />
-      <Avatar backgroundColor={theme.colors.background.brand.primary} text="JD" />
-      <Avatar backgroundColor={theme.colors.background.brand.primary} square />
-
-      {/* Using custom hex colors */}
-      <Avatar backgroundColor="#FF8080" text="AB" />
-      <Avatar backgroundColor="#D580FF" text="RT" />
-    </div>
-  );
-}
-```
-
-### Avatar with Custom Icon
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-import { Building2, Briefcase, Star } from '@xsolla/xui-icons-base';
-
-export default function AvatarWithIcon() {
-  return (
-    <div style={{ display: 'flex', gap: 16 }}>
-      <Avatar icon={<Building2 />} backgroundColor="#4A90D9" />
-      <Avatar icon={<Briefcase />} backgroundColor="#9B59B6" />
-      <Avatar icon={<Star />} backgroundColor="#F39C12" />
-    </div>
-  );
-}
-```
-
-### Avatar with Stroke
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-
-export default function AvatarWithStroke() {
-  return (
-    <Avatar
-      src="https://example.com/user.jpg"
-      stroke
-      size="lg"
-    />
-  );
-}
-```
-
-### Clickable Avatar
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-
-export default function ClickableAvatar() {
-  return (
-    <Avatar
-      text="JD"
-      size="lg"
-      onClick={() => alert('Avatar clicked!')}
-      aria-label="View John Doe's profile"
-    />
-  );
-}
-```
-
-### Avatar Group
-
-```tsx
-import * as React from 'react';
-import { AvatarGroup } from '@xsolla/xui-avatar';
-
-export default function AvatarGroupExample() {
-  const users = [
-    { src: 'https://example.com/user1.jpg' },
-    { src: 'https://example.com/user2.jpg' },
-    { initials: 'JD' },
-    { initials: 'AB' },
-    { initials: 'CD' },
-    { initials: 'EF' },
-    { initials: 'GH' },
-  ];
-
-  return (
-    <AvatarGroup
-      list={users}
-      maxVisible={5}
-      size="md"
-    />
-  );
-}
-```
-
-### Badge Tones
-
-```tsx
-import * as React from 'react';
-import { Avatar } from '@xsolla/xui-avatar';
-
-export default function BadgeTones() {
-  return (
-    <div style={{ display: 'flex', gap: 24 }}>
-      <Avatar text="A" badge badgeCount={3} badgeTone="brand" />
-      <Avatar text="B" badge badgeCount={3} badgeTone="success" />
-      <Avatar text="C" badge badgeCount={3} badgeTone="warning" />
-      <Avatar text="D" badge badgeCount={3} badgeTone="alert" />
-    </div>
-  );
-}
-```
-
-## API Reference
-
-### Avatar
-
-An avatar component for displaying user representation.
-
-**Avatar Props:**
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| src | `string` | - | Image source URL. |
-| icon | `ReactNode` | - | Icon to display when no image. |
-| text | `string` | - | Text/initials when no image or icon. |
-| size | `"xl" \| "lg" \| "md" \| "sm" \| "xs"` | `"md"` | Size of the avatar. |
-| square | `boolean` | `false` | Square with border radius vs circular. |
-| badge | `boolean` | `false` | Show notification badge. |
-| badgeCount | `ReactNode` | - | Badge count or content. |
-| badgeTone | `"primary" \| "secondary" \| "brand" \| "brandExtra" \| "success" \| "warning" \| "alert" \| "neutral"` | - | Badge color tone. |
-| stroke | `boolean` | `false` | Show border around avatar. |
-| backgroundColor | `string` | - | Custom background color. |
-| disableHover | `boolean` | `false` | Disable hover effect. |
-| aria-label | `string` | - | Accessible label. |
-| alt | `string` | - | Alt text for image. |
-| onClick | `() => void` | - | Click handler. |
-
----
-
-### AvatarGroup
-
-A component for displaying multiple avatars with overlap.
-
-**AvatarGroup Props:**
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :------ | :---------- |
-| list | `AvatarGroupItem[]` | - | **Required.** Array of avatar items. |
-| size | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of avatars. |
-| maxVisible | `number` | `6` | Max avatars before "+N" counter. |
-| stroke | `boolean` | `true` | Show borders on avatars. |
-| avatarBackgroundMode | `"mixed" \| ToneString \| Function` | `"mixed"` | Background color mode. |
-| aria-label | `string` | - | Accessible label for the group. |
-
-**AvatarGroupItem:**
-
-```typescript
-interface AvatarGroupItem {
-  src?: string;         // Image URL
-  initials?: string;    // Text initials
-  onClick?: () => void; // Click handler
-  tooltip?: string;     // Tooltip on hover
-}
-```
-
-## Theming
-
-Avatar uses the design system theme for colors:
-
-```typescript
-// Colors accessed via theme
-theme.colors.background.secondary       // Default avatar background
-theme.colors.background.brand.primary   // Brand background (e.g. #80EAFF in dark)
-theme.colors.content.primary            // Text/icon color
-theme.colors.border.primary             // Stroke color
-```
-
-### Square Border Radius
-
-Square avatars use `radius.avatarLarge` (8px) for xl–sm sizes and `radius.avatarSmall` (4px) for xs.
-
-## Accessibility
-
-- Supports `aria-label` for screen readers
-- `alt` attribute for images
-- Keyboard accessible when clickable (Enter/Space)
-- Focus indicator follows WCAG guidelines
-- Badge count announced to assistive technology