{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "avatar",
  "title": "Avatar",
  "description": "A person's picture, or their initials until it loads or when it fails, in a color picked from the name.",
  "registryDependencies": [
    "@ouro/lib-appearance-hints",
    "@ouro/lib-class-name-check",
    "@ouro/lib-cn",
    "@ouro/lib-env",
    "@ouro/lib-use-dev-messages",
    "@ouro/skeleton"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/avatar/avatar.tsx",
      "content": "\"use client\";\n\nimport { Children, createContext, isValidElement, useContext, useLayoutEffect, useState, useSyncExternalStore } from \"react\";\nimport type { HTMLAttributes, JSX, ReactNode, Ref } from \"react\";\nimport { sizeFor } from \"@/registry/ouro/lib/ouro/appearance-hints\";\nimport { useAppearanceClassNameCheck } from \"@/registry/ouro/lib/ouro/class-name-check\";\nimport { cn } from \"@/registry/ouro/lib/ouro/cn\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\nimport { Skeleton } from \"@/registry/ouro/components/ouro/skeleton/skeleton\";\n\n/**\n * Avatar sizes: 24, 32, 40, 48, 64, 72 and 112px.\n *\n * @claim \"Avatar sizes: 24, 32, 40, 48\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > comes in sizes that grow in order, as circles)\n * @claim \"Avatar sizes: 24, 32, 40, 48\" registry/ouro/components/ouro/avatar/avatar.tsx verify:fileLine(registry/ouro/components/ouro/avatar/avatar.tsx, /\"3xl\": \"size-28/)\n */\nexport type AvatarSize = \"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\" | \"2xl\" | \"3xl\";\n\n/**\n * A person's presence, drawn as a dot with its own shape: a check (available), a solid\n * dot (busy), a bar (do not disturb), a clock (away), a ring with a cross (offline) and a\n * ring with an arrow (out of office), so it never relies on color alone.\n * @claim \"A person's presence, drawn as a dot\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar presence > draws each state in its own shape and tone)\n */\nexport type AvatarPresence = \"available\" | \"busy\" | \"away\" | \"do-not-disturb\" | \"offline\" | \"out-of-office\";\n\n/**\n * Avatar's shapes: a squircle for a person, a squircle with a second edge behind it for a team,\n * a channel, an app or a bot, and a less-rounded app tile for an AI agent.\n */\nexport type AvatarShape = \"circle\" | \"square\" | \"agent\";\n\n/** Where the initials' colors come from: a hue picked from the name, the theme's primary, or the neutral surface. */\nexport type AvatarColor = \"colorful\" | \"brand\" | \"neutral\";\n\n/** The props Avatar adds to the `<span>` attributes it passes through. */\nexport interface AvatarOwnProps {\n  /**\n   * The person's or thing's name. Screen readers hear it, and the initials come from it\n   * (the first letters of the first and last words) until the image loads, or when it\n   * fails. Required, so no avatar is silent. Pass `null` while the name is still loading: the\n   * avatar keeps its size and shape and shimmers as a Skeleton, and screen readers hear\n   * `nameLoadingLabel`.\n   * @claim \"Required, so no avatar is silent\" registry/ouro/components/ouro/avatar/avatar.test-d.ts verify:fileLine(registry/ouro/components/ouro/avatar/avatar.test-d.ts, /expectTypeOf<\\{\\ssrc:\\s\"\\/ana\\.jpg\"\\s\\}>\\(\\)\\.not\\.toExtend<AvatarProps>/)\n   * @claim \"Pass `null` while the name is\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > shimmers in its own size and shape while the name loads, and says so)\n   */\n  name: string | null;\n  /** What screen readers hear while `name` is `null`, for other languages. @default \"Name loading\" */\n  nameLoadingLabel?: string | undefined;\n  /** The image URL. Until it loads, and if it fails, the initials show. */\n  src?: string | undefined;\n  /**\n   * What screen readers hear, when it should differ from `name`. Pass `alt=\"\"` when the\n   * name is already written next to the avatar, so it isn't read twice.\n   */\n  alt?: string | undefined;\n  /**\n   * The letters to show instead of the ones taken from `name`, such as \"AnL\". Like the initials\n   * taken from `name`, they are drawn (CSS generated content), not written as text.\n   */\n  initials?: string | undefined;\n  /**\n   * An icon to show in place of the initials, such as a calendar for a meeting or a note for\n   * notes to self. It is decorative: the avatar's label stays `name`.\n   */\n  icon?: ReactNode | undefined;\n  /**\n   * `\"circle\"` for a person (a squircle), `\"square\"` for a team, a channel, an app or a bot (a\n   * squircle with a second edge peeking out behind it, and no presence dot), `\"agent\"` for an AI\n   * agent (a less-rounded tile, white in light mode, with the glyph in its own color and a\n   * presence dot). The initials, icon or picture fill the shape, centered. @default \"circle\"\n   * @claim \"a presence dot\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar shapes and icons > shows no presence on a square, and names the fix)\n   */\n  shape?: AvatarShape | (string & { 'Use \"circle\", \"square\" or \"agent\"; rounded is \"square\", hexagon is \"agent\"': never }) | undefined;\n  /**\n   * How the initials are colored. `\"colorful\"` picks one of eight hues from `idForColor`\n   * (else `name`), so the same person always gets the same one, and the initials keep at\n   * least 4.5:1 against it in light and dark. `\"brand\"` tints with the theme's primary;\n   * `\"neutral\"` is the plain secondary surface. The hues are the theme tokens `--avatar-1`\n   * to `--avatar-8` (`ouro-base`). @default \"colorful\"\n   * @claim \"picks one of eight hues from\" registry/ouro/theme/ouro-base.css verify:fileLine(registry/ouro/theme/ouro-base.css, /--avatar-8:/)\n   * @claim \"picks one of eight hues from\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar colors > picks the same hue for the same name, and spreads names across the hues)\n   * @claim \"picks one of eight hues from\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar colors > keeps the initials at least 4.5:1 on every hue and on brand (%s))\n   */\n  color?: AvatarColor | (string & { 'Use \"colorful\", \"brand\" or \"neutral\"': never }) | undefined;\n  /**\n   * What `color=\"colorful\"` picks the hue from, when it should not be `name`: a stable id,\n   * so people who share a name can differ and a rename keeps the color.\n   * @claim \"so people who share a name\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar colors > picks the hue from idForColor when given, so one name can take two colors)\n   */\n  idForColor?: string | undefined;\n  /**\n   * 24, 32, 40, 48, 64, 72 or 112px (`2xl` and `3xl` for profile pages); the initials and\n   * the presence dot grow with it. Inside an `AvatarGroup`, the group's size applies.\n   * @default \"md\"\n   * @claim \"24, 32, 40, 48, 64, 72\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > shows initials from the name, and the name to screen readers)\n   * @claim \"the presence dot grow with it\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar presence > sits on the lower end corner at every size, with the avatar cut away round it)\n   * @claim \"24, 32, 40, 48, 64, 72\" registry/ouro/components/ouro/avatar/avatar.tsx verify:fileLine(registry/ouro/components/ouro/avatar/avatar.tsx, /\"3xl\": \"size-28/)\n   */\n  size?: AvatarSize | (string & { 'Use \"xs\", \"sm\", \"md\", \"lg\", \"xl\", \"2xl\" or \"3xl\"': never }) | undefined;\n  /** Layout only: margins, grid placement (`ms-2`). Appearance classes warn in development; use `size`. */\n  className?: string | undefined;\n  ref?: Ref<HTMLSpanElement> | undefined;\n\n  /** Not a prop. The initials come from `name`, or pass `initials`: `<Avatar name=\"Ana Lind\" initials=\"AL\" />`. */\n  children?: { 'Use <Avatar name=\"Ana Lind\" initials=\"AL\" />': never };\n  /** Not a prop. The initials come from `name`, or pass `initials`: `<Avatar name=\"Ana Lind\" initials=\"AL\" />`. */\n  fallback?: { 'Use <Avatar name=\"Ana Lind\" initials=\"AL\" />': never };\n}\n\n/** An Avatar with a presence dot and the words it says. */\nexport interface AvatarPresenceProps {\n  /**\n   * The person's presence, as a dot on the lower end corner. Each state has its own shape\n   * and a named tone (available: success; busy and do not disturb: destructive; away:\n   * warning; offline: muted; out of office: primary). The avatar is cut away in a\n   * circle round the dot (a bite), so whatever lies behind the avatar, a photo or a gradient\n   * too, shows through the gap. The dot lies over the corner and takes no room, so\n   * the initials, icon or picture stay in the middle with or without it, and the dot stays\n   * below the letters at every size.\n   * @claim \"The dot lies over the corner\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar presence > keeps the initials in the middle with or without a dot, and the dot off them (%s))\n   * @claim \"The dot lies over the corner\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar presence > keeps an icon and a picture in the middle with a dot, as without one)\n   * @claim \"Each state has its own shape\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar presence > draws each state in its own shape and tone)\n   */\n  presence: AvatarPresence | (string & { 'dnd is \"do-not-disturb\"; ooo is \"out-of-office\"': never });\n  /**\n   * What the dot says, such as \"Busy\" or \"In a meeting\": screen readers hear it after the\n   * name (\"Ana Lind, Busy\"). Required with `presence`, so no dot is silent.\n   * @claim \"Required with `presence`, so no dot\" registry/ouro/components/ouro/avatar/avatar.test-d.ts verify:fileLine(registry/ouro/components/ouro/avatar/avatar.test-d.ts, /presence:\\s\"busy\"\\s\\}>\\(\\)\\.not\\.toExtend<AvatarProps>/)\n   */\n  presenceLabel: string;\n}\n\n/** An Avatar without a presence dot. */\nexport interface AvatarNoPresenceProps {\n  /** Leave it out for no dot; pass it with `presenceLabel` to show one. */\n  presence?: undefined;\n  /** Read only with `presence`. */\n  presenceLabel?: string | undefined;\n}\n\n/**\n * Props for {@link Avatar}: its own props, `presence` with `presenceLabel` or neither, and\n * the `<span>` attributes it passes through.\n */\nexport type AvatarProps = Omit<HTMLAttributes<HTMLSpanElement>, keyof AvatarOwnProps | \"presence\" | \"presenceLabel\" | \"role\"> &\n  AvatarOwnProps &\n  (AvatarPresenceProps | AvatarNoPresenceProps);\n\n/** The props AvatarGroup adds to the `<div>` attributes it passes through. */\nexport interface AvatarGroupOwnProps {\n  /** What the group is, for screen readers: \"Cooks on this recipe\". Required, so the group has a name. */\n  label: string;\n  /** The `Avatar`s, in order. */\n  children: ReactNode;\n  /** Shows at most this many avatars, then a \"+N\" count for the rest. @default unlimited */\n  max?: number | undefined;\n  /**\n   * How many there are in all, when you pass only the first few avatars (a recipe with\n   * 120 cooks). The \"+N\" count is `total` minus the avatars shown.\n   * @claim \"How many there are in all\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::AvatarGroup > counts from total when more people exist than avatars passed)\n   */\n  total?: number | undefined;\n  /** What screen readers hear for the \"+N\" count, for other languages. @default (count) => `${count} more` */\n  moreLabel?: ((count: number) => string) | undefined;\n  /**\n   * The size of every avatar in the group, and of the count. @default \"md\"\n   *\n   * @claim \"The size of every avatar in\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::AvatarGroup > passes its size to every avatar and the count)\n   */\n  size?: AvatarSize | (string & { 'Use \"xs\", \"sm\", \"md\", \"lg\", \"xl\", \"2xl\" or \"3xl\"': never }) | undefined;\n  /** Layout only: margins, grid placement (`mt-4`). Appearance classes warn in development. */\n  className?: string | undefined;\n  ref?: Ref<HTMLDivElement> | undefined;\n}\n\n/** Props for {@link AvatarGroup}: its own props and the `<div>` attributes it passes through. */\nexport type AvatarGroupProps = Omit<HTMLAttributes<HTMLDivElement>, keyof AvatarGroupOwnProps | \"role\"> & AvatarGroupOwnProps;\n\n// Each size sets the box and the initials' type size together.\nconst sizes = {\n  xs: \"size-6 [--ouro-edge:0.105rem] text-[0.625rem]\",\n  sm: \"size-8 [--ouro-edge:0.14rem] text-xs\",\n  md: \"size-10 [--ouro-edge:0.175rem] text-sm\",\n  lg: \"size-12 [--ouro-edge:0.21rem] text-base\",\n  xl: \"size-16 [--ouro-edge:0.28rem] text-xl\",\n  \"2xl\": \"size-18 [--ouro-edge:0.315rem] text-2xl\",\n  \"3xl\": \"size-28 [--ouro-edge:0.49rem] text-4xl\",\n} as const;\n\nconst sizeNames = Object.keys(sizes).map((name) => `\"${name}\"`).join(\", \");\n\n// A team's second edge peeks out behind it, up and to the end, cut off by a gap in the\n// surface's color. An agent's tile is white in light mode and a slightly lighter surface in\n// dark, with a hairline over its art.\nconst squareEdgeClass =\n  \"[--ouro-edge-color:color-mix(in_oklab,var(--foreground)_20%,transparent)] dark:[--ouro-edge-color:color-mix(in_oklab,var(--foreground)_30%,transparent)] shadow-[0_0_0_1.4px_var(--ouro-avatar-ring,var(--background)),var(--ouro-edge-x,var(--ouro-edge))_calc(var(--ouro-edge)*-1)_0_0_var(--ouro-edge-color)] rtl:[--ouro-edge-x:calc(var(--ouro-edge)*-1)]\";\nconst agentTileClass =\n  \"bg-white dark:bg-[color-mix(in_oklab,white_14%,var(--background))] after:pointer-events-none after:absolute after:inset-0 after:rounded-[inherit] after:border after:border-black/7 after:content-[''] dark:after:border-white/12 forced-colors:after:border-[CanvasText]\";\n\n// The presence dot: its whole size, the ring (padding in the surface's color) and where its\n// center falls, near the circle's edge at the lower end corner.\nconst presenceSizes = {\n  xs: \"size-[8px] -end-[2.1px] -bottom-[2.1px]\",\n  sm: \"size-[9px] -end-[2px] -bottom-[2px]\",\n  md: \"size-[11px] -end-[2.3px] -bottom-[2.3px]\",\n  lg: \"size-[13px] -end-[2.7px] -bottom-[2.7px]\",\n  xl: \"size-[18px] -end-[3.9px] -bottom-[3.9px]\",\n  \"2xl\": \"size-[20px] -end-[4.3px] -bottom-[4.3px]\",\n  \"3xl\": \"size-[31px] -end-[6.6px] -bottom-[6.6px]\",\n} as const;\n\n// Where the dot's center falls (--ouro-bite-c, from the lower end corner) and the radius of\n// its ring (--ouro-bite-r): the avatar's surface is cut away there, so what lies behind the\n// avatar shows through the gap, as a ring in the surface's color could not.\nconst biteSizes = {\n  xs: \"[--ouro-bite-c:1.9px] [--ouro-bite-r:5.5px]\",\n  sm: \"[--ouro-bite-c:2.5px] [--ouro-bite-r:6.1px]\",\n  md: \"[--ouro-bite-c:3.2px] [--ouro-bite-r:7.5px]\",\n  lg: \"[--ouro-bite-c:3.8px] [--ouro-bite-r:8.9px]\",\n  xl: \"[--ouro-bite-c:5.1px] [--ouro-bite-r:12.2px]\",\n  \"2xl\": \"[--ouro-bite-c:5.7px] [--ouro-bite-r:13.6px]\",\n  \"3xl\": \"[--ouro-bite-c:8.9px] [--ouro-bite-r:21.1px]\",\n} as const;\n// Below 40px a glyph cannot be read, so the dot is a plain colour; from 40px up it carries its glyph.\nconst plainSizes: readonly AvatarSize[] = [\"xs\", \"sm\"];\nconst biteClass =\n  \"[mask-image:radial-gradient(circle_at_calc(100%_-_var(--ouro-bite-c))_calc(100%_-_var(--ouro-bite-c)),transparent_var(--ouro-bite-r),#000_calc(var(--ouro-bite-r)+0.5px))] \" + // fade-ok: a bite cut out of the avatar for its presence dot, not a fade\n  \"rtl:[mask-image:radial-gradient(circle_at_var(--ouro-bite-c)_calc(100%_-_var(--ouro-bite-c)),transparent_var(--ouro-bite-r),#000_calc(var(--ouro-bite-r)+0.5px))]\"; // fade-ok: the same bite, mirrored for right to left\n\n// Each hue tints the surface and colors the initials, mixed toward the theme's background and\n// foreground so the pair keeps at least 4.5:1 in light and dark.\nconst hues = [\n  \"bg-[color-mix(in_oklab,var(--avatar-1)_18%,var(--background))] text-[color-mix(in_oklab,var(--avatar-1)_70%,var(--foreground))]\",\n  \"bg-[color-mix(in_oklab,var(--avatar-2)_18%,var(--background))] text-[color-mix(in_oklab,var(--avatar-2)_70%,var(--foreground))]\",\n  \"bg-[color-mix(in_oklab,var(--avatar-3)_18%,var(--background))] text-[color-mix(in_oklab,var(--avatar-3)_70%,var(--foreground))]\",\n  \"bg-[color-mix(in_oklab,var(--avatar-4)_18%,var(--background))] text-[color-mix(in_oklab,var(--avatar-4)_70%,var(--foreground))]\",\n  \"bg-[color-mix(in_oklab,var(--avatar-5)_18%,var(--background))] text-[color-mix(in_oklab,var(--avatar-5)_70%,var(--foreground))]\",\n  \"bg-[color-mix(in_oklab,var(--avatar-6)_18%,var(--background))] text-[color-mix(in_oklab,var(--avatar-6)_70%,var(--foreground))]\",\n  \"bg-[color-mix(in_oklab,var(--avatar-7)_18%,var(--background))] text-[color-mix(in_oklab,var(--avatar-7)_70%,var(--foreground))]\",\n  \"bg-[color-mix(in_oklab,var(--avatar-8)_18%,var(--background))] text-[color-mix(in_oklab,var(--avatar-8)_70%,var(--foreground))]\",\n] as const;\nconst brand = \"bg-[color-mix(in_oklab,var(--primary)_18%,var(--background))] text-[color-mix(in_oklab,var(--primary)_70%,var(--foreground))]\";\nconst neutral = \"bg-secondary text-secondary-foreground\";\n\nconst shapes = [\"circle\", \"square\", \"agent\"] as const;\n\nconst colors = [\"colorful\", \"brand\", \"neutral\"] as const;\nconst presences = [\"available\", \"busy\", \"away\", \"do-not-disturb\", \"offline\", \"out-of-office\"] as const;\n\n/** The group's size, which its avatars take. */\nconst GroupSize = createContext<AvatarSize | undefined>(undefined);\n\n/**\n * The picture's status: `idle` without one, `loading` while the browser fetches it, then `loaded`\n * or `error`. The picture is drawn once it has loaded, so the initials show until then and after a\n * failure. A picture the browser has already shows on the first paint.\n */\n// Pictures an avatar on this page has loaded, each held by an image so the browser keeps it ready: an avatar\n// of one draws it in its first render, with no second render to swap the initials for it. The oldest go\n// past a few hundred.\nconst readyPictures = new Map<string, HTMLImageElement>();\nconst READY_PICTURES = 256;\n// Stryker disable next-line ArrowFunction: React only calls the cleanup, so one that returns undefined behaves the same.\nconst subscribeNever = () => () => {};\n\nfunction useImageStatus(src: string | undefined): \"idle\" | \"loading\" | \"loaded\" | \"error\" {\n  // In server HTML and while it hydrates, no picture is ready: the initials, as the server drew them.\n  const ready = useSyncExternalStore(\n    subscribeNever,\n    () => readyPictures.has(src as string),\n    // Stryker disable next-line ArrowFunction: undefined reads as false where ready is read.\n    () => false,\n  );\n  // The status of the picture last asked for: an avatar with no picture never sets state, so it never draws twice.\n  const [fetched, setFetched] = useState<{ src: string; status: \"loading\" | \"loaded\" | \"error\" } | null>(null);\n  useLayoutEffect(() => {\n    if (!src || ready) return;\n    let current = true;\n    let shown: \"loading\" | \"loaded\" | \"error\" | undefined;\n    // A status the avatar already shows sets no state, so a cached picture's late load event draws nothing again.\n    const settle = (status: \"loading\" | \"loaded\" | \"error\") => {\n      if (!current || status === shown) return;\n      shown = status;\n      setFetched({ src, status });\n    };\n    const image = new window.Image();\n    image.onload = () => {\n      readyPictures.set(src, image);\n      if (readyPictures.size > READY_PICTURES) readyPictures.delete(readyPictures.keys().next().value!);\n      settle(\"loaded\");\n    };\n    image.onerror = () => settle(\"error\");\n    image.src = src;\n    // Before paint, so a picture already in the browser's cache is there on the avatar's first frame.\n    // An image is complete as its address is set only when the browser holds that picture ready.\n    settle(image.complete ? \"loaded\" : \"loading\");\n    return () => {\n      current = false;\n    };\n  }, [src, ready]);\n  if (src === undefined) return \"idle\";\n  if (!src) return \"error\";\n  if (fetched?.src === src) return fetched.status;\n  return ready ? \"loaded\" : \"idle\";\n}\n\n/** The first letters of the first and last words, by code point so emoji stay whole. */\n// An agent with no icon or picture shows this sparkle in its hue, not an initial.\nfunction AgentGlyph(): ReactNode {\n  return (\n    <svg viewBox=\"0 0 24 24\" fill=\"currentColor\" aria-hidden=\"true\" data-ouro-avatar-glyph=\"\">\n      <path d=\"M12 2l2.4 6.6L21 11l-6.6 2.4L12 20l-2.4-6.6L3 11l6.6-2.4z\" />\n      <path d=\"M19 16l.9 2.1L22 19l-2.1.9L19 22l-.9-2.1L16 19l2.1-.9z\" />\n    </svg>\n  );\n}\n\nfunction initialsOf(name: string): string {\n  const words = name.trim().split(/\\s+/).filter(Boolean);\n  const first = (word: string | undefined) => (word ? Array.from(word)[0]!.toUpperCase() : \"\");\n  return first(words[0]) + (words.length > 1 ? first(words.at(-1)) : \"\");\n}\n\n/**\n * One of the hues for a key, the same on the server and in the browser: an FNV hash, mixed by\n * MurmurHash3's finalizer and scaled from its top bits. Without the mix, keys that differ only\n * in their last character (sequential ids) barely move the top bits, and all take one hue.\n * @claim \"an FNV hash, mixed by MurmurHash3's\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar colors > maps each name to its hue, the same in every browser and on the server)\n * @claim \"Without the mix, keys that differ\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar colors > spreads ids that differ only in their last character across the hues)\n */\nfunction hueOf(key: string): string {\n  let hash = 0x811c9dc5;\n  for (const char of key.trim().toLowerCase()) {\n    hash ^= char.codePointAt(0)!;\n    hash = Math.imul(hash, 0x01000193);\n  }\n  hash ^= hash >>> 16;\n  hash = Math.imul(hash, 0x85ebca6b);\n  hash ^= hash >>> 13;\n  hash = Math.imul(hash, 0xc2b2ae35);\n  hash ^= hash >>> 16;\n  return hues[Math.floor(((hash >>> 0) / 2 ** 32) * hues.length)]!;\n}\n\nfunction checkSize(size: unknown): AvatarSize | undefined {\n  return typeof size === \"string\" && Object.hasOwn(sizes, size) ? (size as AvatarSize) : undefined;\n}\n\nfunction oneOf<T extends string>(values: readonly T[], value: unknown): T | undefined {\n  return (values as readonly unknown[]).includes(value) ? (value as T) : undefined;\n}\n\n/** The dev message for a size that is not one of Ouro UI's. */\nfunction sizeWarning(component: string, size: unknown): readonly [string, string] {\n  const written = typeof size === \"string\" ? `size=\"${size}\"` : `size={${String(size)}}`;\n  const fix = typeof size === \"string\" ? (sizeFor(`text-${size}`, [\"xs\", \"sm\", \"md\", \"lg\", \"xl\", \"2xl\", \"3xl\"]) ?? \"md\") : \"md\";\n  return [`${written} is not a size; use ${sizeNames}`, `<${component} size=\"${fix}\">`];\n}\n\nfunction avatarHint(token: string): string {\n  if (token.startsWith(\"rounded\")) return 'shape=\"square\"';\n  const size = sizeFor(token, [\"xs\", \"sm\", \"md\", \"lg\", \"xl\", \"2xl\", \"3xl\"]);\n  if (size) return `size=\"${size}\"`;\n  return `remove \"${token}\"; Avatar colors its initials from the name, or pass color=\"neutral\"`;\n}\n\n/** The presence dot's glyph: a shape per state, so color is not the only cue. */\nfunction PresenceGlyph({ presence, plain }: { presence: AvatarPresence; plain: boolean }): JSX.Element {\n  const line = { fill: \"none\", strokeWidth: 1.75, strokeLinecap: \"round\", strokeLinejoin: \"round\" } as const;\n  return (\n    <svg viewBox=\"0 0 16 16\" aria-hidden=\"true\" focusable=\"false\" className=\"block size-full\">\n      {presence === \"available\" && (\n        <>\n          <circle cx=\"8\" cy=\"8\" r=\"8\" className=\"fill-success\" />\n          {!plain && <path d=\"M4.75 8.25 7 10.5l4.25-4.5\" {...line} className=\"stroke-success-foreground\" />}\n        </>\n      )}\n      {presence === \"busy\" && <circle cx=\"8\" cy=\"8\" r=\"8\" className=\"fill-destructive\" />}\n      {presence === \"do-not-disturb\" && (\n        <>\n          <circle cx=\"8\" cy=\"8\" r=\"8\" className=\"fill-destructive\" />\n          {!plain && <path d=\"M4.5 8h7\" {...line} className=\"stroke-destructive-foreground\" />}\n        </>\n      )}\n      {presence === \"away\" && (\n        <>\n          <circle cx=\"8\" cy=\"8\" r=\"8\" className=\"fill-warning\" />\n          {!plain && <path d=\"M8 4.5v3.75l2.5 1.5\" {...line} className=\"stroke-warning-foreground\" />}\n        </>\n      )}\n      {presence === \"offline\" && (\n        <>\n          <circle cx=\"8\" cy=\"8\" r=\"7\" {...line} strokeWidth={2} className=\"stroke-muted-foreground\" />\n          {!plain && <path d=\"m5.75 5.75 4.5 4.5m0-4.5-4.5 4.5\" {...line} className=\"stroke-muted-foreground\" />}\n        </>\n      )}\n      {presence === \"out-of-office\" && (\n        <>\n          <circle cx=\"8\" cy=\"8\" r=\"7\" {...line} strokeWidth={2} className=\"stroke-primary\" />\n          {!plain && <path d=\"M11 8H5.25M7.5 5.5 5 8l2.5 2.5\" {...line} className=\"stroke-primary\" />}\n        </>\n      )}\n    </svg>\n  );\n}\n\n/**\n * A person's picture, or their initials until it loads or when it fails, in a color picked\n * from the name. `name` is required: screen readers hear it, and the initials come from it.\n * `presence` adds a status dot that says what it shows (`presenceLabel`), and\n * `shape=\"square\"` marks a team, a channel, an app or a bot, and `shape=\"agent\"` an AI\n * agent. Server HTML holds the initials, and the picture replaces\n * them at full strength the moment it loads, with no fade: a picture already in the browser's\n * cache is there on the avatar's first frame.\n *\n * The initials are drawn, not written: CSS generated content from a data attribute, which\n * paints exactly as text did but is no text in the page. So a link or button that wraps the\n * avatar and names itself (`<a aria-label=\"Ana Lind's profile\">`) shows no visible text its\n * name must hold, and passes axe's `label-content-name-mismatch` (WCAG 2.5.3, Label in Name);\n * without a name of its own, it takes the avatar's: the person's name, never the letters. In a\n * test, find an avatar by its role and name (`getByRole(\"img\", { name: \"Ana Lind\" })`), not by\n * its letters.\n *\n * Use `AvatarGroup` instead to stack several, and `Badge` for a status label that isn't a person.\n *\n * @claim \"with no fade\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > draws a picture already in the cache at full strength on its first frame, with no fade)\n * @group Display\n * @see https://ui.ouroboros.bot/docs/avatar\n *\n * @example\n * <Avatar name=\"Ana Lind\" src={user.photoUrl} presence=\"busy\" presenceLabel=\"In a meeting\" />\n * <Avatar name=\"Grace Hopper\" size=\"lg\" idForColor={user.id} />\n * <Avatar name=\"Design reviews\" shape=\"square\" />\n * <Avatar name=\"Halden\" shape=\"agent\" src={agent.photoUrl} />\n * <span className=\"flex items-center gap-2\"><Avatar name={user.name} alt=\"\" size=\"sm\" />{user.name}</span>\n * @claim \"in a color picked from the name\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar colors > picks the same hue for the same name, and spreads names across the hues)\n * @claim \"which paints exactly as text did\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar's drawn letters > look exactly as written text did, in every size, shape, color and the group's count (%s))\n * @claim \"and passes axe's `label-content-name-mismatch`\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar inside a link or button that has its own name > a link named \"Ana Lind's profile\" around %s has no label-content-name-mismatch) verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar inside a link or button that has its own name > the same link around initials written as text fails the rule, so the check can fail)\n * @claim \"without a name of its own\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar inside a link or button that has its own name > names a link with no label of its own by the person's name, not the letters)\n */\nexport function Avatar(props: AvatarProps): JSX.Element {\n  const {\n    name: nameProp,\n    nameLoadingLabel = \"Name loading\",\n    src,\n    alt,\n    initials,\n    icon,\n    shape: shapeProp,\n    color: colorProp,\n    idForColor,\n    presence: presenceProp,\n    presenceLabel,\n    size: sizeProp,\n    className,\n    // Guard props (hint types), dropped here so they never reach the DOM.\n    children,\n    fallback,\n    ...rest\n  } = props;\n  const name = nameProp ?? \"\";\n  const nameLoading = nameProp === null;\n  const groupSize = useContext(GroupSize);\n  // A size, shape, color or presence that is not one of Ouro UI's (a type error) warns and renders the default.\n  const size = groupSize ?? checkSize(sizeProp) ?? \"md\";\n  const shape = oneOf(shapes, shapeProp) ?? \"circle\";\n  const color = oneOf(colors, colorProp);\n  // A team has no presence: a square draws no dot and says none.\n  const presence = shape === \"square\" ? undefined : oneOf(presences, presenceProp);\n  const image = useImageStatus(src);\n  useAppearanceClassNameCheck(\n    \"Avatar\",\n    className,\n    process.env.NODE_ENV !== \"production\" ? avatarHint : /* istanbul ignore next @preserve -- production only */ \"\",\n  );\n  useDevWarnings(\n    \"Avatar\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          nameProp === undefined && [\"name is missing, so screen readers hear nothing\", '<Avatar name=\"Ana Lind\" src={url} />'],\n          !groupSize && sizeProp !== undefined && !checkSize(sizeProp) && sizeWarning(\"Avatar\", sizeProp),\n          shapeProp !== undefined &&\n            !oneOf(shapes, shapeProp) && [\n              `shape=\"${String(shapeProp)}\" is not a shape; use \"circle\", \"square\", \"agent\"`,\n              `<Avatar shape=\"${/agent|hex/i.test(String(shapeProp)) ? \"agent\" : \"square\"}\">`,\n            ],\n          shape === \"square\" &&\n            presenceProp !== undefined && [\"a team shows no presence, so a square draws no dot\", `<Avatar name=\"${name}\" shape=\"square\" />`],\n          colorProp !== undefined &&\n            !oneOf(colors, colorProp) && [`color=\"${String(colorProp)}\" is not a color; use \"colorful\", \"brand\", \"neutral\"`, '<Avatar color=\"colorful\">'],\n          presenceProp !== undefined &&\n            shape !== \"square\" &&\n            !presence && [\n              `presence=\"${String(presenceProp)}\" is not a presence; use ${presences.map((value) => `\"${value}\"`).join(\", \")}`,\n              '<Avatar presence=\"do-not-disturb\" presenceLabel=\"Do not disturb\">',\n            ],\n          presence &&\n            !presenceLabel && [\n              \"presenceLabel is missing, so screen readers hear no presence\",\n              `<Avatar presence=\"${presence}\" presenceLabel=\"${presence[0]!.toUpperCase()}${presence.slice(1).replaceAll(\"-\", \" \")}\">`,\n            ],\n          children !== undefined && [\"Avatar takes name and initials, not children\", '<Avatar name=\"Ana Lind\" initials=\"AL\" />'],\n          fallback !== undefined && [\"fallback is not a prop\", '<Avatar name=\"Ana Lind\" initials=\"AL\" />'],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n  // A presence's words follow the name, so a screen reader hears \"Ana Lind, Busy\"; with\n  // alt=\"\" (the name written beside it) only the presence is read.\n  const spoken = presence ? presenceLabel || presence.replaceAll(\"-\", \" \") : \"\";\n  const label = [alt ?? (nameLoading ? nameLoadingLabel : name), spoken].filter(Boolean).join(\", \");\n  const glyph = icon !== undefined && icon !== null ? icon : shape === \"agent\" ? <AgentGlyph /> : undefined;\n  const iconShown = glyph !== undefined;\n  const tint = color === \"neutral\" ? neutral : color === \"brand\" ? brand : hueOf(idForColor ?? name);\n  const [fill, ink] = tint.split(\" \") as [string, string];\n  return (\n    <span\n      {...rest}\n      {...(label ? { role: \"img\", \"aria-label\": label } : { \"aria-hidden\": true })}\n      data-ouro=\"avatar\"\n      data-image={image}\n      data-shape={shape}\n      data-presence={presence}\n      data-name-loading={nameLoading ? \"\" : undefined}\n      className={cn(\n        \"relative box-border inline-flex shrink-0 items-center justify-center align-middle\",\n        \"font-medium leading-none select-none\",\n        shape === \"circle\" ? \"rounded-[44%]\" : \"rounded-[24%]\",\n        shape === \"square\" && squareEdgeClass,\n        !nameLoading && ink,\n        presence && biteSizes[size],\n        sizes[size],\n        className,\n      )}\n    >\n      <span\n        data-ouro-avatar-surface=\"\"\n        className={cn(\n          \"absolute inset-0 flex items-center justify-center rounded-[inherit]\",\n          shape === \"circle\" ? \"[--ouro-sq-r:44%]\" : \"[--ouro-sq-r:24%]\",\n          shape === \"agent\" ? agentTileClass : !nameLoading && fill,\n          presence && biteClass,\n          image !== \"loaded\" && iconShown && !nameLoading && \"*:size-[55%]\",\n          nameLoading && \"overflow-hidden\",\n        )}\n      >\n        {image === \"loaded\" ? (\n          <img src={src} alt=\"\" className=\"size-full rounded-[inherit] object-cover\" />\n        ) : nameLoading ? (\n          // The avatar's own box and corners, so it is the avatar's exact shape; the presence dot stays whole outside it.\n          <Skeleton className=\"size-full [border-radius:inherit]\" />\n        ) : iconShown ? (\n          glyph\n        ) : (\n          // Drawn from the attribute, not written as text, so a control that wraps the avatar has no\n          // visible text its name must contain (WCAG 2.5.3); the avatar's name is its aria-label.\n          // Trimmed to the letters' cap height and baseline, so the letters themselves sit in the\n          // middle, not their line with its room for accents and descenders.\n          <span\n            data-ouro-avatar-initials={initials ?? initialsOf(name)}\n            className=\"block whitespace-nowrap [text-box:trim-both_cap_alphabetic] before:content-[attr(data-ouro-avatar-initials)]\"\n          />\n        )}\n      </span>\n      {presence && (\n        <span\n          data-ouro-avatar-presence=\"\"\n          className={cn(\"pointer-events-none absolute box-border flex [--corner-shape:round] [corner-shape:round] rounded-full\", presenceSizes[size])}\n        >\n          <PresenceGlyph presence={presence} plain={plainSizes.includes(size)} />\n        </span>\n      )}\n    </span>\n  );\n}\n\n/**\n * Avatars stacked with a slight overlap, such as the cooks on a recipe, with a \"+N\"\n * count after `max`. Its `label` names the group for screen readers, and its `size`\n * applies to every avatar in it.\n *\n * Use a list of `Avatar`s with names beside them instead when readers need to see who\n * each person is.\n *\n * The \"+N\" count is drawn like Avatar's initials, not written, and screen readers hear\n * `moreLabel`, so a button that wraps the group and names itself shows no text its name must hold.\n *\n * @group Display\n * @see https://ui.ouroboros.bot/docs/avatar\n *\n * @example\n * <AvatarGroup label=\"Cooks\" max={3} size=\"sm\">\n *   {cooks.map((cook) => <Avatar key={cook.id} name={cook.name} src={cook.photoUrl} />)}\n * </AvatarGroup>\n * @claim \"Its `label` names the group for\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar > shows initials from the name, and the name to screen readers)\n * @claim \"Its `label` names the group for\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::AvatarGroup > stacks avatars in a labeled group, overlapping)\n * @claim \"count is drawn like Avatar's initials\" registry/ouro/components/ouro/avatar/avatar.test.tsx verify:testExists(registry/ouro/components/ouro/avatar/avatar.test.tsx::Avatar inside a link or button that has its own name > a button named for the group around an AvatarGroup and its +N count has no label-content-name-mismatch)\n */\nexport function AvatarGroup(props: AvatarGroupProps): JSX.Element {\n  const { label, children, max, total, moreLabel = (count: number) => `${count} more`, size: sizeProp, className, ...rest } = props;\n  const size = checkSize(sizeProp) ?? \"md\";\n  const avatars = Children.toArray(children);\n  const shown = max !== undefined && max >= 1 ? avatars.slice(0, max) : avatars;\n  const more = Math.max(total ?? 0, avatars.length) - shown.length;\n  useAppearanceClassNameCheck(\n    \"AvatarGroup\",\n    className,\n    process.env.NODE_ENV !== \"production\"\n      ? (token: string) => `<div className=\"${token}\"><AvatarGroup /></div>`\n      : /* istanbul ignore next @preserve -- production only */ \"\",\n  );\n  useDevWarnings(\n    \"AvatarGroup\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          max !== undefined && max < 1 && [`max={${max}} hides every avatar`, \"<AvatarGroup max={3}>\"],\n          total !== undefined &&\n            total < avatars.length && [`total={${total}} is less than the ${avatars.length} avatars passed`, `<AvatarGroup total={${avatars.length}}>`],\n          sizeProp !== undefined && !checkSize(sizeProp) && sizeWarning(\"AvatarGroup\", sizeProp),\n          avatars.some((child) => !isValidElement(child)) && [\n            \"AvatarGroup holds Avatars\",\n            '<AvatarGroup label=\"Cooks\"><Avatar name=\"Ana Lind\" /></AvatarGroup>',\n          ],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n  // Each avatar after the first overlaps the one before; a ring in the surface's color\n  // (--ouro-avatar-ring, else the page's background) keeps them apart.\n  return (\n    <div\n      {...rest}\n      role=\"group\"\n      aria-label={label}\n      data-ouro=\"avatar-group\"\n      className={cn(\"flex items-center *:shadow-[0_0_0_2px_var(--ouro-avatar-ring,var(--background))] *:not-first:-ms-2\", className)}\n    >\n      <GroupSize value={size}>{shown}</GroupSize>\n      {more > 0 && (\n        <span\n          data-ouro-avatar-more=\"\"\n          className={cn(\n            \"relative box-border inline-flex shrink-0 items-center justify-center rounded-[44%] bg-muted font-medium leading-none text-foreground\",\n            sizes[size],\n          )}\n        >\n          <span aria-hidden=\"true\" data-ouro-avatar-count={`+${more}`} className=\"before:content-[attr(data-ouro-avatar-count)]\" />\n          <span className=\"sr-only\">{moreLabel(more)}</span>\n        </span>\n      )}\n    </div>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/avatar/avatar.tsx"
    }
  ],
  "docs": "A person's picture, or their initials until it loads or when it fails, in a color picked from the name. Import: import { Avatar } from \"@/components/ouro/avatar/avatar\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: skeleton, the helpers they import in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/avatar.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}