@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/Avatar/Avatar.tokens.scss

@@ -0,0 +1,107 @@
+// Avatar.tokens.scss — Component-scoped tokens for <Avatar> and <AvatarGroup>. The name-hashed primitive palette --color-avatar-1..6 stays primitive (in tokens.scss) and the React-injected --avatar-bg inline var also stays as a runtime hook on .crop.
+:root {
+  // Surface / shape
+  --avatar-radius: var(--radius-full);
+  --avatar-fg: var(--color-avatar-fg);
+  --avatar-bg-fallback: var(--color-bg-sunken);
+  --avatar-font-weight: var(--font-weight-semibold);
+
+  // Size variants — square dimension + initials font-size per size
+  // `inline` is font-relative (#579): one text line tall, initials ~0.7 of
+  // the text (≈ the sm ratio of initials to diameter).
+  // 1.5em before `lh` support (Safari < 16.4, Firefox < 120) — the library's
+  // body line-height, so still about one line.
+  --avatar-size-inline: 1.5em;
+  --avatar-font-size-inline: 0.7em;
+
+  // Scales with larger text, but never below the sm dot: #506's presence
+  // shapes (filled/half/barred/hollow, 2px strokes) are the non-colour
+  // channel and were only checked down to --size-presence-sm (8px).
+  --avatar-presence-size-inline: max(var(--size-presence-sm), 0.5em);
+  --avatar-size-sm: var(--size-sm);
+  --avatar-size-md: var(--size-md);
+  --avatar-size-lg: var(--size-lg);
+  --avatar-size-xl: var(--size-xl);
+  --avatar-font-size-sm: var(--font-size-xs);
+  --avatar-font-size-md: var(--font-size-sm);
+  --avatar-font-size-lg: var(--font-size-md);
+
+  // Jumps two steps on the font scale (2xl, not lg/xl) — continues the decreasing size:font ratio (0.458 → 0.375 → 0.35 → 0.30) at 80px.
+  --avatar-font-size-xl: var(--font-size-2xl);
+
+  // Presence dot — ring + per-status fill
+  --avatar-presence-radius: var(--radius-full);
+  --avatar-presence-ring-width: var(--border-width-emphasis);
+  --avatar-presence-ring-color: var(--color-bg);
+  --avatar-presence-size-sm: var(--size-presence-sm);
+  --avatar-presence-size-md: var(--size-presence-md);
+  --avatar-presence-size-lg: var(--size-presence-lg);
+  --avatar-presence-size-xl: var(--size-presence-xl);
+  --avatar-presence-bg-online: var(--color-presence-online);
+  --avatar-presence-bg-busy: var(--color-presence-busy);
+  --avatar-presence-bg-away: var(--color-presence-away);
+  --avatar-presence-bg-offline: var(--color-presence-offline);
+
+  // #506. The SHAPE channel. Every cut in a dot is painted in the surface
+  // behind the avatar, so the dot reads as a silhouette rather than as two
+  // colours — which is what survives a greyscale print and every dichromacy.
+  --avatar-presence-glyph-color: var(--avatar-presence-ring-color);
+  --avatar-presence-hollow-width: var(--border-width-emphasis);
+  --avatar-presence-bar-height: var(--border-width-emphasis);
+
+  // AgentAvatar — neutral tile (never the name-hashed palette, so a brand mark
+  // is not recoloured), mark = a fraction of the tile, badge = the member.
+  --agent-avatar-bg: var(--color-bg-muted);
+  --agent-avatar-fg: var(--color-fg-muted);
+  --agent-avatar-mark-size-inline: calc(var(--avatar-size-inline) * 0.6);
+  --agent-avatar-mark-size-sm: calc(var(--avatar-size-sm) * 0.6);
+  --agent-avatar-mark-size-md: calc(var(--avatar-size-md) * 0.6);
+  --agent-avatar-mark-size-lg: calc(var(--avatar-size-lg) * 0.6);
+  --agent-avatar-mark-size-xl: calc(var(--avatar-size-xl) * 0.6);
+  --agent-avatar-badge-size-sm: calc(var(--avatar-size-sm) * 0.5);
+  --agent-avatar-badge-size-md: calc(var(--avatar-size-md) * 0.5);
+  --agent-avatar-badge-size-lg: calc(var(--avatar-size-lg) * 0.5);
+  --agent-avatar-badge-size-xl: calc(var(--avatar-size-xl) * 0.45);
+  --agent-avatar-badge-font-size: 0.4em;
+  --agent-avatar-badge-ring-width: var(--avatar-presence-ring-width);
+  --agent-avatar-badge-ring-color: var(--avatar-presence-ring-color);
+
+  // In-group ring (stacked siblings)
+  --avatar-in-group-ring-width: var(--border-width-emphasis);
+  --avatar-in-group-ring-color: var(--color-bg);
+
+  // AvatarGroup — overlap per size
+  --avatar-group-overlap-sm: var(--avatar-overlap-sm);
+  --avatar-group-overlap-md: var(--avatar-overlap-md);
+  --avatar-group-overlap-lg: var(--avatar-overlap-lg);
+  --avatar-group-overlap-xl: var(--avatar-overlap-xl);
+
+  // AvatarGroup — +N overflow chip
+  --avatar-overflow-gap: var(--space-1);
+  --avatar-overflow-padding-x: var(--space-2);
+  --avatar-overflow-bg: var(--color-bg-muted);
+  --avatar-overflow-fg: var(--color-fg-muted);
+  --avatar-overflow-radius: var(--radius-full);
+  --avatar-overflow-font-weight: var(--font-weight-semibold);
+  --avatar-overflow-ring-width: var(--border-width-emphasis);
+  --avatar-overflow-ring-color: var(--color-bg);
+  --avatar-overflow-bg-hover: var(--color-bg-muted-hover);
+  --avatar-overflow-fg-hover: var(--color-fg);
+  --avatar-overflow-ring-focus: var(--ring-accent);
+
+  // AvatarGroup — +N size per group size
+  --avatar-overflow-size-sm: var(--size-sm);
+  --avatar-overflow-size-md: var(--size-md);
+  --avatar-overflow-size-lg: var(--size-lg);
+  --avatar-overflow-size-xl: var(--size-xl);
+  --avatar-overflow-font-size-sm: var(--font-size-xs);
+  --avatar-overflow-font-size-md: var(--font-size-sm);
+  --avatar-overflow-font-size-lg: var(--font-size-md);
+  --avatar-overflow-font-size-xl: var(--font-size-2xl);
+}
+
+@supports (height: 1lh) {
+  :root {
+    --avatar-size-inline: 1lh;
+  }
+}

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,210 @@
+import { forwardRef, useState, type CSSProperties, type HTMLAttributes } from 'react';
+import clsx from 'clsx';
+import { Tooltip } from '../Tooltip';
+import { useTranslation } from '../../i18n';
+import { useAvatarGroup } from './AvatarGroupContext';
+import styles from './Avatar.module.scss';
+
+/**
+ * Diameter. Matches the shared `--size-*` scale so a Button next to an Avatar
+ * lines up — except `inline`, which is one text line tall (`1lh`).
+ */
+export type AvatarSize = 'inline' | 'sm' | 'md' | 'lg' | 'xl';
+
+/** Presence dot rendered in the bottom-right corner. Omit to render no dot. */
+export type AvatarStatus = 'online' | 'busy' | 'away' | 'offline';
+
+export interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * The person's name. Required — used as the `alt`/`aria-label`, as the
+   * source of the initials, and as the seed for the deterministic fallback
+   * color. The same name always renders the same color. When `tooltip` is
+   * true, also used as the tooltip body.
+   */
+  name: string;
+  /**
+   * Image URL. When provided, the `<img>` is rendered with `alt={name}`.
+   * Empty/whitespace strings are treated as missing. If the image fails to
+   * load (404, network), the component automatically falls back to initials.
+   */
+  src?: string;
+  /**
+   * Diameter.
+   * - `sm` (24px) — table rows, dense lists.
+   * - `md` (32px, default) — most uses.
+   * - `lg` (40px) — detail-page headers.
+   * - `xl` (80px) — member-card popovers / profile headers.
+   * - `inline` — one line of the surrounding text tall (`1lh`), initials
+   *   scaled to match, so an avatar in a text row (a `DefinitionList` value,
+   *   a table cell, a line of text) doesn't make it taller. Follows the text
+   *   size; no size decision per call site. Not available on `<AvatarGroup>`
+   *   — and don't set it per child inside one: the group's overlaps are
+   *   sized for its fixed steps.
+   *
+   * Inside `<AvatarGroup>`, defaults to the group's `size`.
+   */
+  size?: AvatarSize;
+  /**
+   * Presence dot in the bottom-right.
+   * - `'online'`  — green.
+   * - `'busy'`    — red.
+   * - `'away'`    — amber (the categorical amber, dark enough to read at dot size).
+   * - `'offline'` — gray.
+   * Omit to render no dot at all.
+   *
+   * Setting `status` changes the accessible name to `"{name}, {status}"`
+   * (localized), because colour alone cannot carry the status (WCAG 1.4.1);
+   * query with `getByRole('img', { name: 'Alex, online' })`. Each status also
+   * renders a distinct shape (filled / half / barred / hollow), so it survives
+   * colour-vision deficiency and greyscale; the dot stays `aria-hidden` so
+   * nothing is announced twice.
+   */
+  status?: AvatarStatus;
+  /**
+   * Whether to wrap the avatar in a `<Tooltip>` showing `name`. Defaults to
+   * `false` (back-compat — existing renders don't gain a hover affordance).
+   * Inside `<AvatarGroup>`, the group's `tooltip` prop becomes the default
+   * (which itself defaults to `true` for grouped avatars); explicit
+   * per-child still wins.
+   */
+  tooltip?: boolean;
+}
+
+const sizeClass: Record<AvatarSize, string> = {
+  inline: styles.inline,
+  sm: styles.sm,
+  md: styles.md,
+  lg: styles.lg,
+  xl: styles.xl,
+};
+
+function initials(name: string): string {
+  const parts = name.trim().split(/\s+/).slice(0, 2);
+  return parts.map((p) => p[0]?.toUpperCase() ?? '').join('') || '?';
+}
+
+/**
+ * Returns the avatar color slot (1-6) for a given name. The mapping is stable:
+ * the same name always returns the same slot. Useful for matching avatar
+ * colors elsewhere (e.g. a "ghost" item or a chart segment representing the
+ * same user).
+ *
+ * Each slot corresponds to a `--color-avatar-N` CSS custom property.
+ */
+export function avatarColorIndex(name: string): number {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) hash = (hash * 31 + name.charCodeAt(i)) | 0;
+  return (Math.abs(hash) % 6) + 1;
+}
+
+type StyleWithVars = CSSProperties & { [key: `--${string}`]: string | number };
+
+function hasOwnProps(obj: object | undefined): obj is object {
+  return obj !== undefined && Object.keys(obj).length > 0;
+}
+
+/**
+ * Profile circle. Renders an `<img>` when `src` is set, otherwise initials on a deterministic color.
+ * @see docs/components/Avatar.md
+ */
+export const Avatar = forwardRef<HTMLSpanElement, AvatarProps>(function Avatar(
+  { name, src, size, status, tooltip, className, style, ...props },
+  ref,
+) {
+  const t = useTranslation();
+  const group = useAvatarGroup();
+  const resolvedSize: AvatarSize = size ?? group?.size ?? 'md';
+  const resolvedTooltip: boolean = tooltip ?? group?.tooltip ?? false;
+
+  // Reset on src change during render, not in an effect: a mount-time effect
+  // undid an error that fired before it ran (#574).
+  const [imageBroken, setImageBroken] = useState(false);
+  const [prevSrc, setPrevSrc] = useState(src);
+  if (src !== prevSrc) {
+    setPrevSrc(src);
+    setImageBroken(false);
+  }
+
+  const hasImage = typeof src === 'string' && src.trim() !== '' && !imageBroken;
+  const trimmedName = name.trim();
+  const accessibleName = trimmedName === '' ? '?' : trimmedName;
+
+  // #506. Presence was colour-only: the dot is decorative, and `status` reached
+  // neither the accessible name nor the tooltip, so WCAG 1.4.1 applied and the
+  // library did not meet it. The OKLab separation the token gate measures is
+  // blind to dichromacy — under simulated protanopia light away/busy collapses
+  // by an order of magnitude while that gate reads 0.158 and passes.
+  //
+  // FOLDED INTO THE NAME rather than announced from the dot, for two reasons.
+  // Rule 10: presence is a property you ARRIVE at — an avatar sits in a list you
+  // browse minutes after it rendered — and arrived-at properties belong in the
+  // name. And mechanically, the no-image branch is `role="img"`, whose children
+  // ARIA prunes as presentational: a visually-hidden span inside it would be
+  // silent in exactly half the cases, which is the trap Rule 10 records for
+  // Lightbox. Folding works identically in both branches.
+  //
+  // The dot itself stays aria-hidden, so nothing is announced twice.
+  const statusLabel = status ? t(`avatar.presence.${status}` as const) : undefined;
+  const labelledName = statusLabel ? `${accessibleName}, ${statusLabel}` : accessibleName;
+
+  const fallbackStyle: StyleWithVars | undefined = hasImage
+    ? undefined
+    : { '--avatar-bg': `var(--color-avatar-${avatarColorIndex(accessibleName)})` };
+
+  const mergedStyle: StyleWithVars | undefined =
+    hasOwnProps(fallbackStyle) || hasOwnProps(style) ? { ...fallbackStyle, ...style } : undefined;
+
+  const wrapperClass = clsx(
+    styles.avatar,
+    sizeClass[resolvedSize],
+    group != null && styles.inGroup,
+    className,
+  );
+
+  // .crop clips the image/initials into a circle without clipping the
+  // .presence dot, which lives as a sibling outside .crop.
+  const cropInner = hasImage ? (
+    <span className={styles.crop}>
+      <img src={src} alt={labelledName} onError={() => setImageBroken(true)} />
+    </span>
+  ) : (
+    <span className={styles.crop}>
+      <span aria-hidden="true">{initials(name)}</span>
+    </span>
+  );
+
+  const presenceDot = status ? (
+    <span aria-hidden="true" className={styles.presence} data-status={status} />
+  ) : null;
+
+  // {...props} first so component-owned ARIA attributes (role, aria-label) win.
+  const inner = hasImage ? (
+    <span {...props} ref={ref} className={wrapperClass} style={mergedStyle}>
+      {cropInner}
+      {presenceDot}
+    </span>
+  ) : (
+    <span
+      {...props}
+      ref={ref}
+      role="img"
+      aria-label={labelledName}
+      className={wrapperClass}
+      style={mergedStyle}
+    >
+      {cropInner}
+      {presenceDot}
+    </span>
+  );
+
+  // Suppress the tooltip when we don't have a real name to show — the
+  // `?` fallback is for unnamed avatars and saying "?" in a tooltip
+  // would be noise. (Comparing trimmedName, not accessibleName, so a
+  // person legitimately named `?` still gets a tooltip.)
+  const hasRealName = trimmedName !== '';
+  if (resolvedTooltip && hasRealName) {
+    return <Tooltip content={accessibleName}>{inner}</Tooltip>;
+  }
+
+  return inner;
+});

package/src/components/Avatar/AvatarGroup.module.scss

@@ -0,0 +1,128 @@
+@use './Avatar.tokens';
+
+// AvatarGroup — horizontal row of stacked Avatars with optional +N overflow.
+// Rule 4 note: `.item:not(:first-child)` uses `margin-left` to overlap
+// siblings — intentional internal layout. The public component IS the
+// wrapper; consumers don't see the inner `.item` divs.
+.group {
+  display: inline-flex;
+  align-items: center;
+}
+
+.item {
+  position: relative;
+  display: inline-flex;
+}
+
+// Hovered (or keyboard-focused) item rises to the top of the stack so the
+// reader can see the full circle of the avatar they're inspecting. Without
+// this, deeper-in-the-stack avatars are clipped by their right neighbour.
+.item:hover,
+.item:focus-within {
+  z-index: 1;
+}
+
+// Per-size overlap. The group wrapper picks up a .groupSize-* class so
+// every direct .item child after the first slides left by the right amount.
+// stylelint-disable property-disallowed-list -- margin-left here is intentional
+// internal layout: .item divs are internal implementation detail, not exposed to
+// consumers. Negative margin is the only CSS mechanism that both overlaps elements
+// and reclaims space in the flow; gap and translate cannot produce negative spacing.
+.groupSize-sm > .item:not(:first-child, .overflowItem) {
+  margin-left: var(--avatar-group-overlap-sm);
+}
+
+.groupSize-md > .item:not(:first-child, .overflowItem) {
+  margin-left: var(--avatar-group-overlap-md);
+}
+
+.groupSize-lg > .item:not(:first-child, .overflowItem) {
+  margin-left: var(--avatar-group-overlap-lg);
+}
+
+.groupSize-xl > .item:not(:first-child, .overflowItem) {
+  margin-left: var(--avatar-group-overlap-xl);
+}
+
+// The +N item gets a small positive gap from its preceding sibling instead
+// of the negative overlap used between avatars. It's metadata, not a face,
+// so it should not pretend to be another stacked avatar — plus longer
+// counts (+33, +99) deserve breathing room.
+.groupSize-sm > .overflowItem,
+.groupSize-md > .overflowItem,
+.groupSize-lg > .overflowItem,
+.groupSize-xl > .overflowItem {
+  margin-left: var(--avatar-overflow-gap);
+}
+// stylelint-enable property-disallowed-list
+
+// +N overflow chip — same circular surface as Avatar, muted background.
+// The 2px ring matches the .inGroup ring on Avatar so the +N sits flush.
+.overflow {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+
+  // Height is fixed per size; width stretches for multi-digit counts (+33,
+  // +99) via min-width + horizontal padding. The pill keeps full radius so
+  // a single-digit +N still reads as a perfect circle.
+  padding: 0 var(--avatar-overflow-padding-x);
+  background: var(--avatar-overflow-bg);
+  color: var(--avatar-overflow-fg);
+  border: none;
+  border-radius: var(--avatar-overflow-radius);
+  font-family: inherit;
+  font-weight: var(--avatar-overflow-font-weight);
+  box-shadow: 0 0 0 var(--avatar-overflow-ring-width) var(--avatar-overflow-ring-color);
+  cursor: default;
+  user-select: none;
+
+  &:is(button) {
+    cursor: pointer;
+  }
+
+  &:is(button):hover {
+    background: var(--avatar-overflow-bg-hover);
+    color: var(--avatar-overflow-fg-hover);
+  }
+
+  // Stays a two-layer box-shadow rather than moving to the focus-ring mixin
+  // (#505). The inner layer is --color-bg and is doing the same job
+  // outline-offset does elsewhere — separating the ring from the chip — but it
+  // also has to sit between the chip and the OVERLAPPING avatars beside it,
+  // which an offset gap showing the real surface would not do, because the real
+  // surface there is another avatar. It picked up the opaque --ring-accent for
+  // free, so the conformance fix reached it anyway.
+  &:is(button):focus-visible {
+    outline: none;
+    box-shadow:
+      0 0 0 var(--avatar-overflow-ring-width) var(--avatar-overflow-ring-color),
+      0 0 0 calc(var(--avatar-overflow-ring-width) + var(--ring-width))
+        var(--avatar-overflow-ring-focus);
+  }
+}
+
+.overflowSize-sm {
+  min-width: var(--avatar-overflow-size-sm);
+  height: var(--avatar-overflow-size-sm);
+  font-size: var(--avatar-overflow-font-size-sm);
+}
+
+.overflowSize-md {
+  min-width: var(--avatar-overflow-size-md);
+  height: var(--avatar-overflow-size-md);
+  font-size: var(--avatar-overflow-font-size-md);
+}
+
+.overflowSize-lg {
+  min-width: var(--avatar-overflow-size-lg);
+  height: var(--avatar-overflow-size-lg);
+  font-size: var(--avatar-overflow-font-size-lg);
+}
+
+.overflowSize-xl {
+  min-width: var(--avatar-overflow-size-xl);
+  height: var(--avatar-overflow-size-xl);
+  font-size: var(--avatar-overflow-font-size-xl);
+}

package/src/components/Avatar/AvatarGroup.tsx

@@ -0,0 +1,119 @@
+import {
+  Children,
+  forwardRef,
+  isValidElement,
+  useMemo,
+  type HTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import type { AvatarSize } from './Avatar';
+import { AvatarGroupContext, type AvatarGroupContextValue } from './AvatarGroupContext';
+import styles from './AvatarGroup.module.scss';
+import { useTranslation } from '../../i18n/useTranslation';
+
+export interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
+  /** Avatar children. */
+  children: ReactNode;
+
+  /**
+   * Diameter default for child avatars. Defaults to `'md'`. Each child can
+   * still override via its own `size` prop (idiomatic React composition —
+   * explicit prop wins). For a strictly uniform group, don't set `size` on
+   * individual children.
+   * - `sm` (24px) — table rows, dense lists.
+   * - `md` (32px, default) — most uses.
+   * - `lg` (40px) — detail-page headers.
+   * - `xl` (80px) — member-card popovers / profile headers.
+   */
+  size?: Exclude<AvatarSize, 'inline'>;
+
+  /**
+   * Maximum number of visible avatars. Children beyond this count collapse
+   * into a single `+N` button at the tail. Defaults to `4`. The `+N` only
+   * appears when there are STRICTLY more children than `max`.
+   */
+  max?: number;
+
+  /**
+   * Whether to render a name tooltip on each child avatar. Defaults to `true`
+   * inside the group (a standalone `<Avatar tooltip>` is opt-in; group context
+   * flips that default). Set `false` on the group to suppress all tooltips;
+   * overridable per-child by setting `tooltip` on the Avatar.
+   */
+  tooltip?: boolean;
+
+  /**
+   * Fires when the user clicks the `+N` overflow button. The library does
+   * NOT render a popover — apps decide what happens (open a modal, navigate,
+   * etc.). When omitted, the `+N` is rendered as a non-interactive `<span>` (still labelled for AT).
+   *
+   * @param event The native click event.
+   * @param hiddenCount The number of children not visible in the strip.
+   */
+  onOverflowClick?: (event: MouseEvent<HTMLButtonElement>, hiddenCount: number) => void;
+}
+
+/**
+ * Horizontal stack of `<Avatar>`s with `+N` overflow when count exceeds `max`.
+ * @see docs/components/AvatarGroup.md
+ */
+export const AvatarGroup = forwardRef<HTMLDivElement, AvatarGroupProps>(function AvatarGroup(
+  { children, size = 'md', max = 4, tooltip = true, onOverflowClick, className, ...props },
+  ref,
+) {
+  const t = useTranslation();
+  const items = Children.toArray(children).filter(isValidElement);
+  const visible = items.slice(0, max);
+  const hiddenCount = Math.max(0, items.length - max);
+
+  const ctx: AvatarGroupContextValue = useMemo(() => ({ size, tooltip }), [size, tooltip]);
+
+  const overflowClass = clsx(styles.overflow, styles[`overflowSize-${size}`]);
+
+  const overflowNode =
+    hiddenCount > 0 ? (
+      onOverflowClick ? (
+        <button
+          type="button"
+          className={overflowClass}
+          aria-label={t('avatarGroup.overflow', { count: hiddenCount })}
+          onClick={(e) => onOverflowClick(e, hiddenCount)}
+        >
+          +{hiddenCount}
+        </button>
+      ) : (
+        <span
+          className={overflowClass}
+          role="img"
+          aria-label={t('avatarGroup.overflow', { count: hiddenCount })}
+        >
+          +{hiddenCount}
+        </span>
+      )
+    ) : null;
+
+  return (
+    // Pattern A — props last so consumer overrides win.
+    <AvatarGroupContext.Provider value={ctx}>
+      <div
+        ref={ref}
+        role="list"
+        className={clsx(styles.group, styles[`groupSize-${size}`], className)}
+        {...props}
+      >
+        {visible.map((child, i) => (
+          <div key={i} role="listitem" className={styles.item}>
+            {child}
+          </div>
+        ))}
+        {overflowNode && (
+          <div role="listitem" className={clsx(styles.item, styles.overflowItem)}>
+            {overflowNode}
+          </div>
+        )}
+      </div>
+    </AvatarGroupContext.Provider>
+  );
+});

package/src/components/Avatar/AvatarGroupContext.tsx

@@ -0,0 +1,20 @@
+import { createContext, useContext } from 'react';
+import type { AvatarSize } from './Avatar';
+
+export interface AvatarGroupContextValue {
+  /** Uniform size for every avatar in the group. */
+  size: Exclude<AvatarSize, 'inline'>;
+  /** Default tooltip behavior for child avatars. */
+  tooltip: boolean;
+}
+
+/**
+ * Internal context shared by `<AvatarGroup>` with its descendant `<Avatar>`s.
+ * `null` means the avatar is standalone (not inside a group).
+ */
+export const AvatarGroupContext = createContext<AvatarGroupContextValue | null>(null);
+
+/** Read the surrounding group context; `null` when standalone. */
+export function useAvatarGroup(): AvatarGroupContextValue | null {
+  return useContext(AvatarGroupContext);
+}

package/src/components/Avatar/index.ts

@@ -0,0 +1,6 @@
+export { Avatar, avatarColorIndex } from './Avatar';
+export type { AvatarProps, AvatarSize, AvatarStatus } from './Avatar';
+export { AgentAvatar } from './AgentAvatar';
+export type { AgentAvatarProps, AgentAvatarMember } from './AgentAvatar';
+export { AvatarGroup } from './AvatarGroup';
+export type { AvatarGroupProps } from './AvatarGroup';