# Avatar Status Dot

## Usage

Status indicator dot for `Avatar`. Put one in the avatar's `status` slot and it sits on the bottom-right corner, showing whether someone is online, away, or busy. `variant` picks the status.

Each variant pairs a colour with its own shape, so the state never rests on colour alone: `success` is a filled dot, `neutral` is a hollow ring, and `error` is a dot with a minus bar across it. The dot also reads the avatar's size, so a 128px avatar gets a 32px dot and a 32px avatar gets a small one.

Colour on its own does not reach everyone, so always pass `label` with the status words. Inside an avatar the label is composed into the avatar's own name, so a screen reader announces "Jane Doe, Online" instead of stopping at the name; on a standalone dot it becomes the dot's own image name. Without `label` the dot is hidden from assistive technology, which is the right choice only when the same status is already written out next to the avatar.

```ts
import { AvatarStatusDot } from '@astryx-vue/core/Avatar'
```

## Examples

Common configurations, variations, and states.

### Variants

Presence dots on Avatars using the success, neutral, and error variants. Pass an AvatarStatusDot to the Avatar status slot; the dot sits on the bottom-right corner of the avatar and sizes itself to match it.

```vue
<script setup lang="ts">
import { Avatar, AvatarStatusDot } from '@astryx-vue/core/Avatar'
import { HStack } from '@astryx-vue/core/Stack'
</script>

<template>
  <HStack align="center" :gap="4">
    <Avatar name="Ana Silva" size="xl">
      <template #status>
        <AvatarStatusDot variant="success" label="Online" />
      </template>
    </Avatar>
    <Avatar name="Ben Okafor" size="xl">
      <template #status>
        <AvatarStatusDot variant="neutral" label="Away" />
      </template>
    </Avatar>
    <Avatar name="Cleo Marsh" size="xl">
      <template #status>
        <AvatarStatusDot variant="error" label="Do not disturb" />
      </template>
    </Avatar>
  </HStack>
</template>
```

### Icons

Put an icon in the icon slot to replace the built-in shape when the status has a sharper symbol than filled, hollow, or barred. Icons are dropped on the smallest avatar sizes, where the built-in shapes take over.

```vue
<script setup lang="ts">
import { Avatar, AvatarStatusDot } from '@astryx-vue/core/Avatar'
import { Icon } from '@astryx-vue/core/Icon'
import { HStack } from '@astryx-vue/core/Stack'
</script>

<template>
  <HStack align="center" :gap="4">
    <Avatar name="Ana Silva" size="xl">
      <template #status>
        <AvatarStatusDot label="Approved">
          <template #icon>
            <Icon icon="i-carbon-checkmark-filled" />
          </template>
        </AvatarStatusDot>
      </template>
    </Avatar>
    <Avatar name="Ben Okafor" size="xl">
      <template #status>
        <AvatarStatusDot variant="neutral" label="Paused">
          <template #icon>
            <Icon icon="i-carbon-pause-filled" />
          </template>
        </AvatarStatusDot>
      </template>
    </Avatar>
    <Avatar name="Cleo Marsh" size="xl">
      <template #status>
        <AvatarStatusDot variant="error" label="Blocked">
          <template #icon>
            <Icon icon="i-carbon-close-filled" />
          </template>
        </AvatarStatusDot>
      </template>
    </Avatar>
  </HStack>
</template>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'success' \| 'neutral' \| 'error'` | `'success'` | Semantic status, where colour comes with its own shape so the state never rests on colour alone: `success` is a filled dot, `neutral` is a hollow ring, and `error` is a dot with a minus bar across it. The older names `info` and `warning` are still accepted and draw as `success` and `error`. |
| `label` | `string` | — | Accessible name for the status, such as `Online`. Inside an Avatar it is composed into the avatar's own name (`Jane Doe, Online`); a standalone dot exposes `role="img"` with this name. When omitted the dot is `aria-hidden`, so it is invisible to assistive technology. |

## Size

The dot reads the size of the enclosing Avatar and picks one of three tiers, so it stays legible at every avatar size instead of shrinking without limit. Outside an Avatar it uses the default `md` size (36px).

| Avatar size | Dot | Border | Icon |
| --- | --- | --- | --- |
| 36px and under | 10px | 1px | not shown |
| 37px to 72px | 20px | 2px | 12px |
| 73px and over | 32px | 4px | 18px |

## Slots

- `icon`: an icon drawn in the middle of the dot. A rendered icon replaces the built-in shape glyph, so use a different icon per status. Icons are not drawn at the smallest tier, where there is no room for them to be legible.

## Theming

```css
.my-avatar-status-dot {
  --astryx-avatar-status-dot-size: 12px;
  --astryx-avatar-status-dot-border-width: 2px;
  --astryx-avatar-status-dot-border-color: #ffffff;
  --astryx-avatar-status-dot-success-background: #198100;
  --astryx-avatar-status-dot-success-foreground: #ffffff;
  --astryx-avatar-status-dot-neutral-background: #ffffff;
  --astryx-avatar-status-dot-neutral-foreground: #525252;
  --astryx-avatar-status-dot-error-background: #e33f4a;
  --astryx-avatar-status-dot-error-foreground: #ffffff;
}
```

`size` overrides the size the dot derived from the avatar; the shape drawn inside keeps the size it was computed at.