bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbAvatar.md

@@ -1,199 +1,475 @@
 # BbAvatar
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Data Display**
+- Description: Displays an avatar and has a fallback content slot.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbAvatar.md](./source/BbAvatar.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbAvatar` wherever a person or entity needs a visual identity — member
+lists, comment threads, assignee cells, account menus. It is display-only: it
+has no events and never becomes interactive by itself. For a status or count
+riding on it, anchor a floating `BbIndicator`; for a clickable avatar (account
+menu, profile link) put it _inside_ the interactive component — a `BbBaseButton`'s
+default slot, a `BbDropdown` trigger — and for a selectable person, put the
+avatar inside the control (e.g. a `BbSelect` option slot), not the other way
+around.
+
+### The fallback chain
+
+The avatar resolves what to show in a fixed order:
+
+1. **Image** — when `src` (or `srcset`) is set and loads correctly.
+2. **Default slot** — when there is no source or the image fails: put initials
+   (or any markup) here.
+3. **Built-in user icon** — when you supply no slot either.
+
+A failed load flips to the fallback automatically, and changing `src`/`srcset`
+resets the attempt — so swapping users in place retries the new photo. Always
+set `alt`: it labels the photo, and for a fallback it becomes the avatar's
+accessible name.
+
+**Photo, initials, and the built-in fallback**
+
+```vue
+<div class="flex items-center gap-3">
+	<BbAvatar size="xl" src="https://i.pravatar.cc/128?img=47" alt="Ada Lovelace" />
+	<BbAvatar size="xl" alt="Grace Hopper">GH</BbAvatar>
+	<BbAvatar size="xl" alt="Unknown user" />
+</div>
+```
+
+### Responsive images
+
+`srcset` + `sizes` pass straight through to the underlying `<img>`, so
+high-density screens can pull a sharper asset while everyone else gets the
+small one. The image is center-cropped (`object-fit: cover`) into a circle —
+sources don't need to be pre-cropped square.
+
+**Density-aware avatar**
+
+```vue
+<BbAvatar
+	size="xl"
+	srcset="https://i.pravatar.cc/64?img=32 64w, https://i.pravatar.cc/128?img=32 128w"
+	sizes="36px"
+	alt="Margaret Hamilton"
+/>
+```
+
+### Sizing and the fallback surface
+
+`size` follows the icon scale (`xs–2xl`, 12–40 px by default — remapped
+library-wide by the `iconDefaultSizes` plugin option), a number (px), a CSS
+dimension string (`"3rem"`), or a percentage (`"100%"` fills a square parent).
+The built-in fallback icon scales with the avatar automatically.
+
+The fallback surface is **always painted with the primary design token** —
+`--bb-primary` behind, `--bb-primary-fg` for the initials/icon, the same
+pairing as a primary button — so initials stay legible in light and dark and
+every avatar matches your theme automatically. There is no per-avatar tinting
+API: theming happens through the tokens, not a prop.
+
+**The size scale**
+
+```vue
+<div class="flex items-end gap-3">
+	<BbAvatar size="sm" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
+	<BbAvatar size="md" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
+	<BbAvatar size="lg" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
+	<BbAvatar size="xl" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
+	<BbAvatar size="2xl" src="https://i.pravatar.cc/128?img=5" alt="Joan Clarke" />
+</div>
+```
+
+### Presence with a floating dot
+
+Wrap an avatar in [`BbIndicator`](../BbIndicator.md) with `dot` to show status —
+`BbIndicator` positions and clips the marker for you, so you never hand-place an
+absolutely-positioned dot. Prefer a status `variant` (`success` for online);
+for offline / away override `--bg` with a muted token. Convey the state in text
+too, since the dot alone is not announced.
+
+**Online and offline presence**
+
+```vue
+<div class="flex items-center gap-3">
+	<BbIndicator bottom dot variant="success">
+		<BbAvatar size="md" src="https://i.pravatar.cc/128?img=12" alt="Ada Lovelace — online" />
+	</BbIndicator>
+	<BbIndicator bottom dot :style="{ '--bg': 'var(--bb-text-muted)' }">
+		<BbAvatar size="md" alt="Grace Hopper — away">GH</BbAvatar>
+	</BbIndicator>
+</div>
+```
+
+### Avatar stacks
+
+An overlapping stack summarizes a group (reviewers, assignees, attendees); the
+overflow count is just another avatar with the count in its slot. Stacking is
+the one place where overriding avatar internals is warranted — the example's
+scoped CSS pulls each avatar over the previous one with a negative margin and
+separates them with a panel-colored ring (an explicit override of the
+`.bb-avatar` root; keep it in one reusable class).
+
+**Reviewers stack with overflow**
 
 ```vue
 <template>
-	<span v-bind="attributes">
-		<img
-			v-if="(src || srcset) && !imageErrored"
-			ref="image"
-			:alt="alt"
-			class="bb-avatar__img"
-			:sizes="sizes"
-			:src="src"
-			:srcset="srcset"
-			@error="onError"
-			@load="onLoad"
-		/>
-		<span v-else class="bb-avatar__fallback">
-			<slot></slot>
-		</span>
-	</span>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3 text-sm"
+	>
+		<div class="flex items-center justify-between gap-2">
+			<div class="flex flex-col gap-0.5">
+				<span class="font-medium">Design review</span>
+				<span class="text-xs text-gray-500">
+					PR #842 · {{ reviewers.length }} reviewers
+				</span>
+			</div>
+			<BbButton size="sm" variant="ghost" @click="expanded = !expanded">
+				{{ expanded ? 'Collapse' : 'Show all' }}
+			</BbButton>
+		</div>
+
+		<div class="stack">
+			<BbAvatar
+				v-for="reviewer in visible"
+				:key="reviewer.name"
+				:alt="reviewer.name"
+				size="sm"
+				:src="reviewer.src"
+			>
+				{{ reviewer.initials }}
+			</BbAvatar>
+			<BbAvatar
+				v-if="!expanded && hiddenCount > 0"
+				:alt="`${hiddenCount} more reviewers`"
+				size="sm"
+			>
+				+{{ hiddenCount }}
+			</BbAvatar>
+		</div>
+	</div>
 </template>
 
 <script setup lang="ts">
-import { computed, ref, onMounted } from 'vue';
-import { isCssColor } from '@/utilities/functions/isCssColor';
-import type { Classes } from '@/types/Classes';
-import { wait } from '@/utilities/functions/wait';
-import type { BbAvatarProps, BbAvatarSlots, Size } from './types';
-
-const props = withDefaults(defineProps<BbAvatarProps>(), {
-	timeout: 400,
-});
-
-defineSlots<BbAvatarSlots>();
-
-const sizeMap: Size = {
-	xs: 24,
-	sm: 32,
-	md: 40,
-	lg: 56,
-	xl: 80,
-	xxl: 104,
-};
+import { computed, ref } from 'vue';
+import { BbAvatar, BbButton } from 'bitboss-ui';
 
-const attributes = computed(() => {
-	const classes: Classes = {
-		'bb-avatar': true,
-	};
-	let dimension: any;
-	if (props.size) {
-		if (typeof props.size === 'string') {
-			dimension = sizeMap[props.size as keyof Size] ?? parseInt(props.size, 10);
-		} else {
-			dimension = props.size;
-		}
-		dimension += `px`;
-	}
-
-	let style: { [key: string]: any } = {
-		width: dimension,
-		height: dimension,
-	};
-	if (props.color) {
-		if (isCssColor(props.color)) {
-			style.backgroundColor = props.color;
-		} else {
-			classes[`bb-avatar--${props.color}`] = true;
-		}
-	}
-	return {
-		class: classes,
-		style,
-	};
-});
-
-const imageHasLoadedCorrectly = (img: HTMLImageElement) => {
-	if (!img) return false;
-	// During the onload event, IE correctly identifies any images that
-	// weren’t downloaded as not complete. Others should too. Gecko-based
-	// browsers act like NS4 in that they report this incorrectly.
-	if (!img.complete) {
-		return false;
-	}
-
-	// However, they do have two very useful properties: naturalWidth and
-	// naturalHeight. These give the true size of the image. If it failed
-	// to load, either of these should be zero.
-	if (img.naturalWidth === 0) {
-		return false;
-	}
-
-	// No other way of checking: assume it’s ok.
-	return true;
+type Reviewer = {
+	name: string;
+	src?: string;
+	initials?: string;
 };
 
-const image = ref<HTMLImageElement | null>();
-const imageLoaded = ref(false);
-const imageErrored = ref(false);
-
-onMounted(async () => {
-	// Only run when events don't fire (when the page is SSR)
-	if (!imageErrored.value && !imageLoaded.value) {
-		if (image.value) {
-			await wait(props.timeout);
-			imageErrored.value = !imageHasLoadedCorrectly(image.value);
-		}
-	}
-});
-const onLoad = () => {
-	imageLoaded.value = true;
-};
-const onError = () => {
-	imageErrored.value = true;
-};
+// The overflow indicator is just another avatar with the count in its slot —
+// same size, same ring, no special markup.
+const reviewers: Reviewer[] = [
+	{ name: 'Ada Lovelace', src: 'https://i.pravatar.cc/96?img=47' },
+	{ name: 'Grace Hopper', initials: 'GH' },
+	{ name: 'Alan Turing', src: 'https://i.pravatar.cc/96?img=13' },
+	{ name: 'Katherine Johnson', initials: 'KJ' },
+	{ name: 'Margaret Hamilton', src: 'https://i.pravatar.cc/96?img=32' },
+];
+const maxVisible = 3;
+
+const expanded = ref(false);
+const visible = computed(() =>
+	expanded.value ? reviewers : reviewers.slice(0, maxVisible)
+);
+const hiddenCount = computed(() => reviewers.length - maxVisible);
 </script>
 
-<style lang="postcss">
-@import './index.css';
+<style scoped>
+/*
+ * Deliberate override of the avatar root: stacking needs the negative margin,
+ * and the panel-colored ring keeps overlapped edges readable. Keep this in one
+ * reusable class — never per-avatar inline styles.
+ */
+.stack {
+	display: flex;
+}
+
+.stack :deep(.bb-avatar) {
+	box-shadow: 0 0 0 1px var(--bb-panel);
+}
+
+.stack :deep(.bb-avatar + .bb-avatar) {
+	margin-left: -6px;
+}
 </style>
 ```
 
-## Types
-
-```ts
-import type { ImgHTMLAttributes } from 'vue';
-import type { CommonProps } from '@/types/CommonProps';
-import type { BbIconProps, Size } from '../BbIcon/types';
-
-export type BbAvatarProps = Pick<CommonProps, 'color'> &
-	Pick<BbIconProps, 'size'> & {
-		/**
-		 * Alternative text for the image, used for accessibility.
-		 */
-		alt?: ImgHTMLAttributes['alt'];
-		/**
-		 * Source URL of the avatar image.
-		 */
-		src?: ImgHTMLAttributes['src'];
-		/**
-		 * Responsive image source set.
-		 */
-		srcset?: ImgHTMLAttributes['srcset'];
-		/**
-		 * Sizes attribute for the image, used with `srcset`.
-		 */
-		sizes?: ImgHTMLAttributes['sizes'];
-		/**
-		 * Milliseconds to wait after mount before checking whether the image loaded correctly (SSR fallback).
-		 * @defaultValue `400`
-		 */
-		timeout?: number;
-	};
-
-export type BbAvatarSlots = {
-	/**
-	 * Fallback content shown when no image source is provided or when the image fails to load.
-	 * Typically used to render initials or a placeholder icon.
-	 */
-	default?: (props: object) => any;
+### Team lists
+
+Avatars, presence, initials fallback and filtering compose into a typical member
+list — the row markup stays identical whether a member has a photo or not.
+
+**A filterable team roster**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3 text-sm"
+	>
+		<div class="flex items-center justify-between gap-2">
+			<div class="flex flex-col gap-0.5">
+				<span class="font-medium">Team</span>
+				<span class="text-xs text-gray-500">
+					{{ visible.length }} of {{ members.length }} members
+				</span>
+			</div>
+			<BbButton size="sm" variant="outline" @click="onlineOnly = !onlineOnly">
+				{{ onlineOnly ? 'Show all' : 'Online only' }}
+			</BbButton>
+		</div>
+
+		<ul class="flex flex-col gap-2">
+			<li
+				v-for="member in visible"
+				:key="member.name"
+				class="flex items-center gap-2"
+			>
+				<BbIndicator
+					bottom
+					dot
+					:style="
+						member.online ? undefined : { '--bg': 'var(--bb-text-muted)' }
+					"
+					:variant="member.online ? 'success' : 'default'"
+				>
+					<BbAvatar :alt="member.name" size="sm" :src="member.src">
+						{{ member.initials }}
+					</BbAvatar>
+				</BbIndicator>
+				<span class="flex min-w-0 flex-1 flex-col">
+					<span class="truncate font-medium">{{ member.name }}</span>
+					<span class="truncate text-xs text-gray-500">
+						{{ member.role }} · {{ member.online ? 'Online' : 'Away' }}
+					</span>
+				</span>
+			</li>
+		</ul>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbAvatar, BbIndicator, BbButton } from 'bitboss-ui';
+
+type Member = {
+	name: string;
+	role: string;
+	online: boolean;
+	src?: string;
+	initials?: string;
 };
 
-export type { Size };
+// Some members have a photo; others fall back to initials on the
+// primary-token surface — both flow through the same row markup.
+const members: Member[] = [
+	{
+		name: 'Ada Lovelace',
+		role: 'Engineering',
+		online: true,
+		src: 'https://i.pravatar.cc/96?img=47',
+	},
+	{
+		name: 'Grace Hopper',
+		role: 'Design',
+		online: true,
+		initials: 'GH',
+	},
+	{
+		name: 'Alan Turing',
+		role: 'Research',
+		online: false,
+		src: 'https://i.pravatar.cc/96?img=13',
+	},
+	{
+		name: 'Katherine Johnson',
+		role: 'Data',
+		online: true,
+		initials: 'KJ',
+	},
+	{
+		name: 'Linus Torvalds',
+		role: 'Platform',
+		online: false,
+		initials: 'LT',
+	},
+];
+
+const onlineOnly = ref(false);
+const visible = computed(() =>
+	onlineOnly.value ? members.filter((member) => member.online) : members
+);
+</script>
 ```
 
-## Styles
-
-```css
-.bb-avatar {
-	aspect-ratio: 1 / 1;
-	border-radius: 50%;
-	display: grid;
-	grid-template-columns: 1fr;
-	overflow: hidden;
-
-	.bb-avatar__img {
-		aspect-ratio: 1 / 1;
-		grid-column: 1 / span 1;
-		grid-row: 1 / span 1;
-		height: 100%;
-		object-fit: cover;
-		object-position: center;
-		width: 100%;
-	}
-
-	.bb-avatar__fallback {
-		align-items: stretch;
-		display: grid;
-		grid-column: 1 / span 1;
-		grid-row: 1 / span 1;
-
-		> * {
-			display: grid;
-			place-items: center;
-		}
-	}
-}
+### Bots and brand marks
+
+Not every actor has a photo. Service accounts, integrations and in-product
+assistants get a **brand mark** instead: put a [`BbIcon`](../BbIcon.md) in the
+fallback slot. Hand-placing `BbIcon` is sanctioned here — `BbAvatar` has no
+icon prop — and `BbIcon`'s `icon` prop accepts a raw `<svg>` string (import
+the asset with `?raw`), so one-off brand art needs no icon collection. The
+mark paints in `currentColor`, inheriting the fallback surface's
+`--bb-primary-fg`, so it stays legible in both themes. Keep the icon
+unlabeled and put the actor's name in `alt` as usual — the fallback announces
+it for you.
+
+**A release feed with a bot actor**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3 text-sm"
+	>
+		<div class="flex items-center justify-between gap-2">
+			<span class="font-medium">Release activity</span>
+			<span class="text-xs text-gray-500">main · production</span>
+		</div>
+
+		<ul class="flex flex-col gap-2">
+			<li v-for="entry in feed" :key="entry.id" class="flex items-center gap-2">
+				<BbAvatar :alt="entry.actor" size="sm" :src="entry.src">
+					<BbIcon v-if="entry.bot" :icon="releaseBotMark" size="xs" />
+					<template v-else>{{ entry.initials }}</template>
+				</BbAvatar>
+				<span class="flex min-w-0 flex-1 flex-col">
+					<span class="truncate">
+						<span class="font-medium">{{ entry.actor }}</span>
+						{{ entry.action }}
+					</span>
+					<span class="text-xs text-gray-500">{{ entry.time }}</span>
+				</span>
+			</li>
+		</ul>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbAvatar, BbIcon } from 'bitboss-ui';
+// A raw `<svg>` string is a valid `icon` for BbIcon — the escape hatch for
+// brand art that lives in no icon collection. It paints in `currentColor`,
+// so on the avatar's fallback surface it inherits `--bb-primary-fg`.
+import releaseBotMark from '@/assets/icons/sparkles.svg?raw';
+
+type FeedEntry = {
+	id: number;
+	actor: string;
+	action: string;
+	time: string;
+	bot?: boolean;
+	src?: string;
+	initials?: string;
+};
+
+// The bot row hand-places a BbIcon in the fallback slot — sanctioned here,
+// because BbAvatar has no icon prop. Human rows keep the exact same markup.
+const feed: FeedEntry[] = [
+	{
+		id: 1,
+		actor: 'Acme Releases',
+		action: 'deployed v2.14.0 to production',
+		time: '2 minutes ago',
+		bot: true,
+	},
+	{
+		id: 2,
+		actor: 'Ada Lovelace',
+		action: 'approved the release',
+		time: '14 minutes ago',
+		src: 'https://i.pravatar.cc/96?img=47',
+		initials: 'AL',
+	},
+	{
+		id: 3,
+		actor: 'Grace Hopper',
+		action: 'tagged v2.14.0',
+		time: '25 minutes ago',
+		initials: 'GH',
+	},
+];
+</script>
 ```
+
+### Slow networks, SSR and the timeout prop
+
+Load failures are normally caught by the image's `error` event. As a safety
+net — mainly for SSR/hydrated pages where the events fired before hydration —
+the component also checks the image `timeout` ms after mount (default `400`)
+and switches to the fallback if it hasn't loaded correctly by then. This makes
+`timeout` an effective **deadline**: an image slower than `timeout` falls back
+and stays on the fallback until `src` changes. If your avatars come from a
+slow origin, raise `timeout` rather than accepting spurious fallbacks.
+
+Platform notes: the component is SSR-safe (Nuxt/Inertia) with no client-only
+markup; the only global config it reads is `iconDefaultSizes` for the size
+keys.
+
+### Works well with
+
+- [`BbIndicator`](../BbIndicator.md) — floating presence dots and counts (see above).
+- `BbTable` — avatar cells pair with the built-in loading skeleton styles
+  `skeleton="avatar"` / `"avatar-text"`.
+- `BbDropdown` / `BbButton` — wrap the avatar in these for account menus and
+  profile links; the avatar itself never handles clicks.
+- `BbSelect` — render avatars in option slots for people pickers.
+- [`BbIcon`](../BbIcon.md) — brand marks for bots and integrations in the
+  fallback slot, including raw `?raw` SVG imports (see above).
+
+### Gotchas & anti-patterns
+
+- **There is no `color` prop.** The fallback is always primary-token colored;
+  don't reach for per-avatar inline backgrounds. Use variants and target the generated `bb-avatar--{{variant}}` or retheme `--bb-primary` /
+  `--bb-primary-fg` if the palette is wrong.
+- **Default `timeout` can false-fallback slow images** (see above) — tune it,
+  don't reimplement image loading around the component.
+- Don't hand-position presence dots with absolute CSS — `BbIndicator dot`
+  exists for that.
+- Don't wrap the avatar in a raw `<span @click>` for menus — put it inside
+  `BbBaseButton`/`BbDropdown` so focus and keyboard behavior come for free.
+- Don't pre-crop sources to circles — the component center-crops; ship square
+  or larger originals.
+- Don't leave `alt` empty for meaningful avatars: fallbacks lose their
+  accessible name entirely.
+
+### Accessibility
+
+Always set `alt`. With an image it labels the photo; with a fallback the
+component adds `role="img"` + `aria-label` (from `alt`) to the fallback, so
+assistive tech announces the person, not the raw initials. If `alt` is empty,
+the fallback renders with no role and no name — acceptable only for purely
+decorative avatars. A presence dot is decorative — make the same status
+available in visible text or an adjacent label.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `alt` | `string \| undefined` | `""` |  | Alternative text for the image, used for accessibility. |
+| `size` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"md"` |  | Defines the component size. Accepted values: - A key from the provided size map (`keyof T`), e.g. `'sm' \| 'md' \| 'lg'` - A custom CSS size string (e.g. `'20px'`, `'1.5rem'`, `'2em'`) - A number, typically interpreted as pixels by size par… |
+| `sizes` | `string \| undefined` |  |  | Sizes attribute for the image, used with `srcset`. |
+| `src` | `string \| undefined` |  |  | Source URL of the avatar image. |
+| `srcset` | `string \| undefined` |  |  | Responsive image source set. |
+| `timeout` | `number \| undefined` | `400` |  | Milliseconds to wait after mount before checking whether the image loaded correctly (SSR fallback). |
+
+## Events
+
+- None.
+
+## Slots
+
+- `default` — scope: `Record<string, never>` — Fallback content shown when no image source is provided or when the image fails to load. Typically used to render initials or a placeholder icon.
+
+## See Also
+
+- [BbBadge](./BbBadge.md) — Displays compact status counters or labels, the floating mode acts as notification dot.