@delacour/react-native-ui 0.1.0-alpha.4 → 0.2.0-alpha.20261010061731

package/src/components/alert/alert.variants.ts

@@ -0,0 +1,180 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { SurfacePadding, SurfaceVariant } from "../surface/surface.variants";
+
+/** What the alert says about the thing it describes. */
+export const ALERT_STATUSES = ["default", "info", "success", "warning", "destructive"] as const;
+
+/** The statuses that carry a colour — every one but `default`. */
+export const ALERT_TINTED_STATUSES = ["info", "success", "warning", "destructive"] as const;
+
+/**
+ * How the surface is painted. `soft` washes it in the status's soft fill;
+ * `surface` keeps the neutral fill the surface ladder gives it and colours only
+ * the indicator and the title.
+ */
+export const ALERT_VARIANTS = ["soft", "surface"] as const;
+
+export const ALERT_SIZES = ["sm", "md", "lg"] as const;
+
+export type AlertStatus = (typeof ALERT_STATUSES)[number];
+export type AlertVariant = (typeof ALERT_VARIANTS)[number];
+export type AlertSize = (typeof ALERT_SIZES)[number];
+
+/**
+ * Theme token for the indicator's glyph and the title's colour.
+ *
+ * One token per status, not per status and variant: `X-soft-foreground` is
+ * tuned to read on `X-soft` and on the neutral fills alike, so the same shade
+ * holds on both variants. A test pins each entry to the class the `title` slot
+ * emits, so the glyph and the words beside it cannot drift apart.
+ */
+export const ALERT_FOREGROUND_TOKEN = {
+	default: "foreground",
+	info: "info-soft-foreground",
+	success: "success-soft-foreground",
+	warning: "warning-soft-foreground",
+	destructive: "destructive-soft-foreground",
+} as const satisfies Record<AlertStatus, string>;
+
+/** The surface's padding step for each alert size. */
+export const ALERT_SURFACE_PADDING = {
+	sm: "sm",
+	md: "md",
+	lg: "lg",
+} as const satisfies Record<AlertSize, SurfacePadding>;
+
+/**
+ * Styling for every part of an alert.
+ *
+ * The root is laid over a `Surface`, which owns the corner, the padding and —
+ * unless the alert is tinted — the fill. This `tv()` adds only what an alert
+ * has and a surface does not: the row, the tint and the text treatment.
+ *
+ * A tinted alert (`soft`, with a status) swaps the card's fill for the status's
+ * soft fill and clears the card's hairline. A grey hairline around a red wash
+ * reads as two components stacked; the wash is its own edge. Everything else
+ * names no background, so the surface ladder picks one and an alert inside a
+ * card steps off the card rather than vanishing into it.
+ *
+ * `items-start`, not `items-center`: a description that wraps to four lines
+ * must not drag the glyph down to its middle. The indicator instead carries the
+ * title's line height as its own height and centres the glyph in it, which
+ * puts the glyph level with the first line at every size.
+ *
+ * No slot carries a fixed height apart from that indicator — `Text` respects OS
+ * font scaling, and a fixed box would clip a wrapped title.
+ *
+ * The root holds no `text-*` (rule 1). The title takes its status's colour,
+ * the description is always muted, so a long explanation never shouts.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot
+ * parse React Native's Flow-typed source. See AGENTS.md.
+ */
+export const alertVariants = tv({
+	slots: {
+		root: "flex-row items-start",
+		indicator: "items-center justify-center",
+		content: "min-w-0 flex-1 gap-1",
+		title: "font-semibold",
+		description: "text-muted-foreground",
+		action: "mt-2 flex-row flex-wrap items-center gap-2",
+		closeButton: "items-center justify-center rounded-full",
+		/** Edge length an `Icon` composed into the alert inherits. */
+		icon: "",
+	},
+	variants: {
+		variant: {
+			soft: {},
+			surface: {},
+		},
+		// Written out rather than built from `ALERT_FOREGROUND_TOKEN`: Tailwind's
+		// scanner is static, and a class assembled at runtime is never compiled.
+		status: {
+			default: { title: "text-foreground" },
+			info: { title: "text-info-soft-foreground" },
+			success: { title: "text-success-soft-foreground" },
+			warning: { title: "text-warning-soft-foreground" },
+			destructive: { title: "text-destructive-soft-foreground" },
+		},
+		size: {
+			sm: {
+				root: "gap-2",
+				indicator: "h-5",
+				title: "text-sm",
+				description: "text-xs",
+				closeButton: "size-5",
+				icon: "size-icon-sm",
+			},
+			md: {
+				root: "gap-3",
+				indicator: "h-6",
+				title: "text-base",
+				description: "text-sm",
+				closeButton: "size-6",
+				icon: "size-icon-md",
+			},
+			lg: {
+				root: "gap-3.5",
+				indicator: "h-7",
+				title: "text-lg",
+				description: "text-base",
+				closeButton: "size-7",
+				icon: "size-icon-lg",
+			},
+		},
+	},
+	compoundVariants: [
+		{ variant: "soft", status: "info", class: { root: "border-transparent bg-info-soft" } },
+		{ variant: "soft", status: "success", class: { root: "border-transparent bg-success-soft" } },
+		{ variant: "soft", status: "warning", class: { root: "border-transparent bg-warning-soft" } },
+		{ variant: "soft", status: "destructive", class: { root: "border-transparent bg-destructive-soft" } },
+	],
+	defaultVariants: {
+		variant: "soft",
+		status: "default",
+		size: "md",
+	},
+});
+
+export type AlertVariantProps = VariantProps<typeof alertVariants>;
+
+/**
+ * Whether the alert paints its status's soft fill over the surface.
+ *
+ * Only a `soft` alert with a status is: a neutral alert has no tint to paint,
+ * and a `surface` alert keeps the ladder's fill on purpose.
+ */
+export function resolveAlertTinted({ status, variant }: { status: AlertStatus; variant: AlertVariant }): boolean {
+	return variant === "soft" && status !== "default";
+}
+
+/**
+ * The `variant` the alert hands its `Surface`.
+ *
+ * A tinted alert pins it to `default`: the tint replaces the fill, and what
+ * nests inside then steps from the card like anything else on one. Every other
+ * alert leaves it `undefined`, so the surface reads the plane it sits on and
+ * steps to the next fill — an alert inside a card is told apart from the card
+ * with nothing said at the call site.
+ */
+export function resolveAlertSurfaceVariant({
+	status,
+	variant,
+}: {
+	status: AlertStatus;
+	variant: AlertVariant;
+}): SurfaceVariant | undefined {
+	return resolveAlertTinted({ status, variant }) ? "default" : undefined;
+}
+
+/**
+ * How urgently Android's TalkBack announces a change inside the alert.
+ *
+ * A warning or a failure interrupts whatever is being read; anything else waits
+ * its turn. iOS has no live regions — the root's `alert` role is what VoiceOver
+ * reads there.
+ */
+export function resolveAlertLiveRegion(status: AlertStatus): "polite" | "assertive" {
+	return status === "destructive" || status === "warning" ? "assertive" : "polite";
+}

package/src/components/alert/index.ts

@@ -0,0 +1,23 @@
+export { Alert, type AlertProps } from "./alert";
+export { type AlertContextValue, AlertProvider, useAlert, useAlertContext } from "./alert.context";
+export type { AlertSlotProps } from "./alert.types";
+export {
+	ALERT_FOREGROUND_TOKEN,
+	ALERT_SIZES,
+	ALERT_STATUSES,
+	ALERT_SURFACE_PADDING,
+	ALERT_TINTED_STATUSES,
+	ALERT_VARIANTS,
+	type AlertSize,
+	type AlertStatus,
+	type AlertVariant,
+	type AlertVariantProps,
+	alertVariants,
+	resolveAlertLiveRegion,
+	resolveAlertSurfaceVariant,
+	resolveAlertTinted,
+} from "./alert.variants";
+export type { AlertCloseButtonProps } from "./alert-close-button";
+export type { AlertDescriptionProps } from "./alert-description";
+export type { AlertIndicatorProps } from "./alert-indicator";
+export type { AlertTitleProps } from "./alert-title";

package/src/components/avatar/AGENTS.md

@@ -0,0 +1,106 @@
+# Avatar
+
+A person, as a picture — with an initials fallback, an overlay slot for a count
+or a presence dot, and a group that stacks several faces and counts the rest.
+Compound root plus `Avatar.Badge` and `Avatar.Group`.
+
+`import { Avatar } from "@delacour/react-native-ui/avatar";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/avatar` |
+| `avatar.tsx` | Root + the `Object.assign` compound surface |
+| `avatar-badge.tsx` | `Avatar.Badge` — the corner overlay, a presence dot when empty |
+| `avatar-group.tsx` | `Avatar.Group`, plus its internal `Item` and `Overflow` leaves |
+| `avatar.context.tsx` | `AvatarProvider`, `AvatarGroupProvider`, `useAvatar()`, `useAvatarContext()`, `useAvatarGroupContext()`, `useAvatarPart()` |
+| `avatar.variants.ts` | Pure `tv()` slots, `AVATAR_SIZE_POINTS`, `resolveAvatarSize`, `resolveAvatarOverlap`, `resolveAvatarInteractive` |
+| `avatar.variants.test.ts` | |
+| `avatar.utils.ts` | Pure non-styling logic — initials, the image-retry key, group overflow maths, the spoken label |
+| `avatar.utils.test.ts` | |
+
+## Design
+
+- **The fallback is always painted; the image goes on top.** The face renders
+  its initials (or a person glyph) first and mounts the `Image` absolutely over
+  them. A picture that is still loading, or that never loads, leaves the fallback
+  showing rather than an empty circle — there is no loading state to manage
+  because there is nothing to swap.
+- **A failure is remembered by key, not by object.** `resolveAvatarSourceKey`
+  turns the source into a string — URI plus sorted headers, or the asset's module
+  id — and `onError` stores the key that failed. Keyed by object identity, an
+  inline `source={{ uri }}` is new every render and a dead URL would retry
+  forever; keyed by URI alone, a token refresh in the headers would never retry.
+  A consumer's `imageProps.onError` fires after the fallback has taken over.
+- **The root carries the edge; there is no `self-start`.** A fixed width and
+  height is something a column's `stretch` never overrides, so the avatar keeps
+  its size without the `self-start` a [`Badge`](../badge/AGENTS.md) needs — and
+  it leaves the parent's alignment alone. With `self-start`, every avatar in an
+  `items-end` or `items-center` row was pinned to the row's top: mixed sizes lost
+  their baseline and a list row's avatar sat above its title. Found on the
+  simulator; a test now forbids any `self-*` on the root or the group.
+- **Two boxes, not one.** `root` is unclipped and holds the overlays; `face` is
+  the clipped circle. An `Avatar.Badge` hangs over the circle's edge, and a
+  single clipped box would cut it in half. A test asserts `overflow-hidden` is on
+  `face` and never on `root`.
+- **Initials are the first letter of the first and last word.** `Anahera Rose
+  Tui` is `AT`, the way a person signs, and `Mihi` is `M`.
+  `resolveAvatarInitials` walks code points rather than UTF-16 units, so a letter
+  outside the basic plane is never split into a replacement box, and skips
+  leading punctuation so `"(Aria)"` still gives `A`. `fallback` overrides the
+  drawn text only; `name` is still what a screen reader reads.
+- **Two axes paint the fallback, on `Badge`'s six colours.** `variant` is `soft`
+  or `solid`, `color` is `default` … `info`, and the twelve cells live in
+  `compoundVariants` with the same fills `Badge` uses, so an avatar and a badge
+  of one colour read as one family. `AVATAR_FOREGROUND_TOKEN` gives the person
+  glyph the same shade as the initials; a test pins each entry to the token the
+  `fallbackLabel` slot resolves to, and checks every token exists in both themes.
+- **A neutral face has a hairline edge; a photo does not.** `muted` and
+  `secondary` sit a percent or two from the page in light — on the simulator a
+  `default` fallback and the `+N` tile all but vanished. They draw
+  `border-border` inside the box, so nothing moves, and the edge goes while a
+  photo is mounted (`hasImage`), since a grey line around a face reads as a
+  frame. The coloured fallbacks have fill enough without one.
+- **A size is a fixed edge, unlike a badge.** `sm`/`md`/`lg`/`xl` are
+  32/40/48/64 points. Faces line up against each other and against list rows, and
+  a circle that grew with OS font scaling would break the stack; the initials
+  therefore set `allowFontScaling={false}` and are sized to fit the smallest
+  step. `AVATAR_SIZE_POINTS` restates the scale as numbers because the group's
+  overlap is a runtime margin and cannot be a class; a test pins the two
+  together.
+- **An avatar is content until it is given something to do** — the rule
+  [`Badge`](../badge/AGENTS.md) follows. With no `onPress` or `onLongPress` it
+  is a plain `View` announced as an image (or not announced at all when it has
+  no name); supply either and it becomes a [`Pressable`](../pressable/AGENTS.md)
+  announced as a button. `resolveAvatarInteractive` is that decision.
+- **The avatar is one element to assistive technology.** The root is
+  `accessible`, so an `Avatar.Badge` inside it is never focused on its own. A
+  presence dot has no words; put the status into the avatar's
+  `accessibilityLabel` (`"Aria Whitlock, online"`).
+- **`Avatar.Badge` is a pin, and a dot only when empty.** Given children — a
+  `Badge` with a count, an `Icon` — it positions them and adds nothing else, so a
+  count keeps the look it has everywhere else. Empty, it draws a dot sized to
+  the face and ringed in `border-background`, which separates it from the photo
+  underneath. `placement` is `top-right` or `bottom-right`.
+- **The group's ring belongs to the slot, not the face.** Each child is wrapped
+  in an item with `border-2 border-background`, so a face in a group keeps the
+  same edge it has alone, and the stack reads as separate people on any surface.
+  The `+N` tile sits in the same wrapper, so it lines up with the faces.
+- **The first face is on top, and the list still reads first to last.**
+  `zIndex` counts down across the items instead of the children being reversed,
+  and the overlap is a negative `marginStart`, so the order in the tree — and
+  therefore the order a screen reader walks — is the written order in both
+  writing directions. The group is `role="list"` and each item `listitem`.
+- **`max` caps the faces, not the row; `total` counts people never passed.**
+  Five children at `max={3}` is three faces and `+2`; three children with
+  `total={40}` is `+37`, without forty elements in the tree.
+  `resolveAvatarGroup` clamps a negative or fractional `max` and ignores a
+  `total` below the child count rather than drawing `+-2`.
+- **The overflow tile draws at most `99+` and reads the real number.** Three
+  digits do not fit a small circle; a screen reader has room for `1234 more`.
+  `onOverflowPress` turns the tile into a button — to open the full list.
+- **The overlap defaults to a third of the edge and is clamped.**
+  `resolveAvatarOverlap` never slides a face further than a whole face nor
+  backwards, and `overlap={0}` closes the stack into a plain row. A child's own
+  `size` still beats the group's, but the overlap is computed from the group's.

package/src/components/avatar/avatar-badge.tsx

@@ -0,0 +1,51 @@
+import type { ReactElement, ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import { cn } from "../../lib/cn";
+import { useAvatarPart } from "./avatar.context";
+import { type AvatarBadgePlacement, type AvatarColor, avatarVariants } from "./avatar.variants";
+
+export type AvatarBadgeProps = ViewProps & {
+	/** Which corner the overlay is pinned to. Default `top-right`. */
+	placement?: AvatarBadgePlacement;
+	/** The presence dot's colour, when there are no children. Default `success`. */
+	color?: AvatarColor;
+	className?: string;
+	/** What to pin — a `Badge` with a count, an `Icon`. Leave empty for a presence dot. */
+	children?: ReactNode;
+};
+
+/**
+ * An overlay pinned to a corner of the avatar — an unread count, a presence dot.
+ *
+ * **Empty, it is a presence dot** sized to the face it sits on and ringed in the
+ * page background, so it reads as separate from the photo underneath. Given
+ * children, it is only the pin: a `Badge` or an `Icon` dropped in keeps its own
+ * look, which is what lets a count and a dot share one part.
+ *
+ * It sits in the avatar's unclipped root, never inside the circle, so it can
+ * hang over the edge without being cut in half.
+ *
+ * A dot says nothing to a screen reader on its own: the avatar is one element to
+ * assistive technology, so put the status into its `accessibilityLabel`.
+ */
+export function AvatarBadge({
+	placement = "top-right",
+	color = "success",
+	className,
+	children,
+	...props
+}: AvatarBadgeProps): ReactElement {
+	const { size } = useAvatarPart("Avatar.Badge");
+	const slots = avatarVariants({ size, placement, color });
+
+	if (children === undefined || children === null || children === false) {
+		return <View className={cn(slots.badge(), slots.dot(), className)} pointerEvents="none" {...props} />;
+	}
+
+	return (
+		<View className={slots.badge({ className })} pointerEvents="box-none" {...props}>
+			{children}
+		</View>
+	);
+}
+AvatarBadge.displayName = "DelacourUI.Avatar.Badge";

package/src/components/avatar/avatar-group.tsx

@@ -0,0 +1,139 @@
+import { Children, isValidElement, type ReactElement, type ReactNode, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { Pressable } from "../pressable";
+import { Text } from "../text";
+import { type AvatarGroupContextValue, AvatarGroupProvider } from "./avatar.context";
+import { resolveAvatarGroup, resolveAvatarOverflowLabel } from "./avatar.utils";
+import { type AvatarSize, avatarVariants, resolveAvatarOverlap } from "./avatar.variants";
+
+export type AvatarGroupProps = ViewProps & {
+	/** Size for every avatar in the stack. A child's own `size` still wins. Default `md`. */
+	size?: AvatarSize;
+	/** How many faces to show; the rest are counted into a trailing `+N`. Caps the faces, not the row. */
+	max?: number;
+	/** How many people there are, when the children are only the first few of them. */
+	total?: number;
+	/** Points each face slides under the one before it. Default a third of the size; `0` makes a plain row. */
+	overlap?: number;
+	/** Makes the `+N` tile a button — to open the full list, say. */
+	onOverflowPress?: () => void;
+	className?: string;
+	children?: ReactNode;
+};
+
+type AvatarGroupItemProps = {
+	/** Position in the stack, first face first. */
+	index: number;
+	/** How many items the stack holds, overflow tile included. */
+	count: number;
+	/** The overlap, in points. */
+	shift: number;
+	children: ReactNode;
+};
+
+/**
+ * One slot in the stack: the ring, the overlap and the stacking order.
+ *
+ * The ring is here rather than on the face so a face in a group is the same edge
+ * as one outside it. `zIndex` counts down so the first face sits on top without
+ * reversing the order a screen reader walks — the list is still read first to
+ * last, in both writing directions, because the overlap is a `marginStart`.
+ */
+function AvatarGroupItem({ index, count, shift, children }: AvatarGroupItemProps): ReactElement {
+	return (
+		<View
+			className={avatarVariants().groupItem()}
+			role="listitem"
+			style={{ marginStart: index === 0 ? 0 : -shift, zIndex: count - index }}
+		>
+			{children}
+		</View>
+	);
+}
+AvatarGroupItem.displayName = "DelacourUI.Avatar.Group.Item";
+
+type AvatarGroupOverflowProps = {
+	size: AvatarSize;
+	overflow: number;
+	onPress?: () => void;
+};
+
+/**
+ * The trailing `+N` tile, the same edge as a face.
+ *
+ * It draws at most `99+` and reads the real number, because three digits do not
+ * fit a small circle and a screen reader has room for all of them.
+ */
+function AvatarGroupOverflow({ size, overflow, onPress }: AvatarGroupOverflowProps): ReactElement {
+	const slots = avatarVariants({ size });
+	const { text, accessibilityLabel } = resolveAvatarOverflowLabel(overflow);
+	const label = (
+		<Text allowFontScaling={false} className={slots.overflowLabel()} numberOfLines={1}>
+			{text}
+		</Text>
+	);
+
+	if (onPress) {
+		return (
+			<Pressable
+				accessibilityLabel={accessibilityLabel}
+				accessibilityRole="button"
+				className={slots.overflow()}
+				feedback="scale"
+				onPress={onPress}
+			>
+				{label}
+			</Pressable>
+		);
+	}
+
+	return (
+		<View accessibilityLabel={accessibilityLabel} accessible className={slots.overflow()}>
+			{label}
+		</View>
+	);
+}
+AvatarGroupOverflow.displayName = "DelacourUI.Avatar.Group.Overflow";
+
+/**
+ * A row of avatars, each overlapping the one after it, with the people who did
+ * not fit counted at the end.
+ *
+ * Children are kept in the order they were written. `max` caps the faces and
+ * `total` says how many people there really are, so three children out of forty
+ * reads `+37` without forty elements in the tree.
+ */
+export function AvatarGroup({
+	size,
+	max,
+	total,
+	overlap,
+	onOverflowPress,
+	className,
+	children,
+	...props
+}: AvatarGroupProps): ReactElement {
+	const items = Children.toArray(children).filter(isValidElement);
+	const { visible, overflow } = resolveAvatarGroup({ count: items.length, max, total });
+	const shift = resolveAvatarOverlap({ size: size ?? "md", overlap });
+	const count = visible + (overflow > 0 ? 1 : 0);
+	const context = useMemo<AvatarGroupContextValue>(() => ({ size }), [size]);
+
+	return (
+		<AvatarGroupProvider value={context}>
+			<View className={avatarVariants().group({ className })} role="list" {...props}>
+				{items.slice(0, visible).map((child, index) => (
+					<AvatarGroupItem count={count} index={index} key={child.key ?? index} shift={shift}>
+						{child}
+					</AvatarGroupItem>
+				))}
+				{overflow > 0 ? (
+					<AvatarGroupItem count={count} index={visible} shift={shift}>
+						<AvatarGroupOverflow onPress={onOverflowPress} overflow={overflow} size={size ?? "md"} />
+					</AvatarGroupItem>
+				) : null}
+			</View>
+		</AvatarGroupProvider>
+	);
+}
+AvatarGroup.displayName = "DelacourUI.Avatar.Group";

package/src/components/avatar/avatar.context.tsx

@@ -0,0 +1,93 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { AvatarColor, AvatarSize, AvatarVariant } from "./avatar.variants";
+
+export type AvatarContextValue = {
+	/** The avatar's resolved size — its own, else its group's, else `md`. */
+	size: AvatarSize;
+	/** How the fallback surface is painted. */
+	variant: AvatarVariant;
+	/** What the fallback surface means. */
+	color: AvatarColor;
+	/** Whether the avatar is disabled. */
+	isDisabled: boolean;
+};
+
+export type AvatarGroupContextValue = {
+	/** The size every avatar in the group takes unless it states its own. */
+	size?: AvatarSize;
+};
+
+const AvatarContext = createContext<AvatarContextValue | null>(null);
+const AvatarGroupContext = createContext<AvatarGroupContextValue | null>(null);
+
+/**
+ * Supplies the enclosing avatar's size, paint and state to its subtree.
+ *
+ * Lives in its own module, importing nothing but `avatar.variants`, so a part
+ * can read it without importing `./avatar`. That import would close a cycle, and
+ * Metro serves a partially initialised module for a cycle — leaving the context
+ * `undefined` at import time and red-boxing the app on a cold start.
+ */
+export function AvatarProvider({ value, children }: { value: AvatarContextValue; children: ReactNode }): ReactElement {
+	return <AvatarContext value={value}>{children}</AvatarContext>;
+}
+AvatarProvider.displayName = "DelacourUI.Avatar.Provider";
+
+/**
+ * Supplies a group's size to every avatar inside it.
+ *
+ * Separate from {@link AvatarProvider} because the two nest the other way round:
+ * a group holds avatars, and an avatar must not read a size its group never set
+ * as though it had been told one.
+ */
+export function AvatarGroupProvider({
+	value,
+	children,
+}: {
+	value: AvatarGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <AvatarGroupContext value={value}>{children}</AvatarGroupContext>;
+}
+AvatarGroupProvider.displayName = "DelacourUI.Avatar.Group.Provider";
+
+/** The enclosing avatar's context, or null outside an `<Avatar>`. */
+export function useAvatarContext(): AvatarContextValue | null {
+	return use(AvatarContext);
+}
+
+/** The enclosing group's context, or null outside an `<Avatar.Group>`. */
+export function useAvatarGroupContext(): AvatarGroupContextValue | null {
+	return use(AvatarGroupContext);
+}
+
+/**
+ * Reads the enclosing avatar's size, paint and state.
+ *
+ * Lets a custom overlay size itself to the face it sits on without the avatar
+ * passing props down. Throws outside an `<Avatar>` — use
+ * {@link useAvatarContext} where the enclosing avatar is optional.
+ */
+export function useAvatar(): AvatarContextValue {
+	const context = useAvatarContext();
+	if (!context) {
+		throw new Error("useAvatar must be called inside an <Avatar>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing avatar's context, for a compound part that cannot work without
+ * one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useAvatar}, whose error message names the hook rather
+ * than a part.
+ */
+export function useAvatarPart(component: string): AvatarContextValue {
+	const context = useAvatarContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside an <Avatar>.`);
+	}
+	return context;
+}