# SilkeImage

A versatile image component that handles standard images, avatars, icons, emoji, and shapes. Supports aspect ratio constraints and integrates with the SilkeBox layout system.

## Features

- **Standard images**: Display images with URL source
- **Avatar mode**: Circular profile pictures in various sizes
- **Icon support**: Display Silke icons in place of images
- **Emoji support**: Render emoji characters
- **Aspect ratios**: Constrain images to 16:9, 4:3, or 1:1
- **Background color**: Set fallback background color

## Basic Usage

```js
<SilkeImage src="https://picsum.photos/400/300" alt="Sample image" />
```

## Aspect Ratios

Constrain images to standard aspect ratios:

```js
<SilkeBox gap="m">
  <SilkeBox column gap="xs" style={{ width: 200 }}>
    <SilkeImage aspectRatio="16:9" src="https://picsum.photos/400/225" />
    <SilkeText size="s" color="neutral-60">16:9</SilkeText>
  </SilkeBox>
  <SilkeBox column gap="xs" style={{ width: 200 }}>
    <SilkeImage aspectRatio="4:3" src="https://picsum.photos/400/300" />
    <SilkeText size="s" color="neutral-60">4:3</SilkeText>
  </SilkeBox>
  <SilkeBox column gap="xs" style={{ width: 150 }}>
    <SilkeImage aspectRatio="1:1" src="https://picsum.photos/400/400" />
    <SilkeText size="s" color="neutral-60">1:1</SilkeText>
  </SilkeBox>
</SilkeBox>
```

## Avatar Mode

Use `avatar` for circular profile pictures:

```js
<SilkeBox gap="m" vAlign="end">
  <SilkeBox column gap="xs" vAlign="center">
    <SilkeImage avatar="xs" src="https://i.pravatar.cc/100?img=1" alt="User" />
    <SilkeText size="s">xs</SilkeText>
  </SilkeBox>
  <SilkeBox column gap="xs" vAlign="center">
    <SilkeImage avatar="s" src="https://i.pravatar.cc/100?img=2" alt="User" />
    <SilkeText size="s">s</SilkeText>
  </SilkeBox>
  <SilkeBox column gap="xs" vAlign="center">
    <SilkeImage avatar src="https://i.pravatar.cc/100?img=3" alt="User" />
    <SilkeText size="s">base</SilkeText>
  </SilkeBox>
  <SilkeBox column gap="xs" vAlign="center">
    <SilkeImage avatar="m" src="https://i.pravatar.cc/100?img=4" alt="User" />
    <SilkeText size="s">m</SilkeText>
  </SilkeBox>
  <SilkeBox column gap="xs" vAlign="center">
    <SilkeImage avatar="l" src="https://i.pravatar.cc/100?img=5" alt="User" />
    <SilkeText size="s">l</SilkeText>
  </SilkeBox>
  <SilkeBox column gap="xs" vAlign="center">
    <SilkeImage avatar="xl" src="https://i.pravatar.cc/100?img=6" alt="User" />
    <SilkeText size="s">xl</SilkeText>
  </SilkeBox>
</SilkeBox>
```

## With Icon

Display a Silke icon instead of an image:

```js
<SilkeBox gap="m">
  <SilkeImage avatar="m" icon="user" bgColor="var(--color-accent-20)" />
  <SilkeImage avatar="m" icon="star" bgColor="var(--color-warning-20)" />
  <SilkeImage avatar="m" icon="check" bgColor="var(--color-success-20)" />
  <SilkeImage avatar="m" icon="settings" bgColor="var(--color-neutral-20)" />
</SilkeBox>
```

## With Emoji

Display emoji characters:

```js
<SilkeBox gap="m">
  <SilkeImage avatar="m" icon={{ type: 0, value: '👋' }} bgColor="var(--color-accent-10)" />
  <SilkeImage avatar="m" icon={{ type: 0, value: '🎉' }} bgColor="var(--color-warning-10)" />
  <SilkeImage avatar="m" icon={{ type: 0, value: '🚀' }} bgColor="var(--color-success-10)" />
  <SilkeImage avatar="m" icon={{ type: 0, value: '💡' }} bgColor="var(--color-neutral-10)" />
</SilkeBox>
```

## Background Color

Set a background color for avatars or as a fallback:

```js
<SilkeBox gap="m">
  <SilkeImage avatar="m" bgColor="#6366f1" />
  <SilkeImage avatar="m" bgColor="#22c55e" />
  <SilkeImage avatar="m" bgColor="#f59e0b" />
  <SilkeImage avatar="m" bgColor="#ef4444" />
</SilkeBox>
```

## User List Example

```js
const users = [
  { name: 'Alice', avatar: 'https://i.pravatar.cc/100?img=1' },
  { name: 'Bob', avatar: 'https://i.pravatar.cc/100?img=2' },
  { name: 'Charlie', avatar: 'https://i.pravatar.cc/100?img=3' },
];

<SilkeBox column gap="s">
  {users.map((user) => (
    <SilkeBox key={user.name} gap="s" vAlign="center">
      <SilkeImage avatar="s" src={user.avatar} alt={user.name} />
      <SilkeText>{user.name}</SilkeText>
    </SilkeBox>
  ))}
</SilkeBox>;
```

## Card with Image

```js
<SilkeCard style={{ width: 300 }}>
  <SilkeImage aspectRatio="16:9" src="https://picsum.photos/600/338" />
  <SilkeBox column pad="m" gap="xs">
    <SilkeText weight="medium">Card Title</SilkeText>
    <SilkeText size="s" color="neutral-60">Card description goes here</SilkeText>
  </SilkeBox>
</SilkeCard>
```

## Fallback Avatar

Show initials or icon when no image is available:

```js
<SilkeBox gap="m">
  <SilkeImage avatar="m" icon="user" bgColor="var(--color-neutral-30)" />
  <SilkeImage avatar="m" icon={{ type: 0, value: 'JD' }} bgColor="var(--color-accent-40)" />
</SilkeBox>
```

## Props

| Prop          | Type                           | Default | Description                              |
| ------------- | ------------------------------ | ------- | ---------------------------------------- |
| `src`         | `string`                       | -       | Image URL                                |
| `alt`         | `string`                       | -       | Alt text for accessibility               |
| `avatar`      | `BoxSize \| true`              | -       | Enable circular avatar mode with size    |
| `icon`        | `IEmojiIcon \| SilkeIcons`     | -       | Display icon or emoji instead of image   |
| `bgColor`     | `string`                       | -       | Background color                         |
| `aspectRatio` | `'16:9' \| '4:3' \| '1:1'`     | -       | Constrain to aspect ratio                |
| `draggable`   | `boolean`                      | -       | Allow image to be dragged                |

Also accepts all `SilkeBox` props for layout control.

## Types

```typescript
type SilkeImageProps = {
  src?: string;
  icon?: IEmojiIcon | SilkeIcons;
  alt?: string;
  avatar?: BoxSize | true;
  bgColor?: string;
} & BoxProps;

// EmojiType values
enum EmojiType {
  emoji = 0,
  icon = 1,
  upload = 2,
}

interface IEmojiIcon {
  type: EmojiType;
  value: string | { url: string };
}
```

## Avatar Sizes

| Size   | Pixels |
| ------ | ------ |
| `xs`   | 16px   |
| `s`    | 24px   |
| `base` | 32px   |
| `m`    | 48px   |
| `l`    | 64px   |
| `xl`   | 96px   |
| `xxl`  | 128px  |