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

package/src/components/avatar/avatar.tsx

@@ -0,0 +1,201 @@
+import { type ReactElement, type ReactNode, useMemo, useState } from "react";
+import {
+	Image,
+	type ImageErrorEventData,
+	type ImageProps,
+	type ImageSourcePropType,
+	type NativeSyntheticEvent,
+	View,
+} from "react-native";
+import { IconPeople } from "../../icons/central";
+import { cn } from "../../lib/cn";
+import { Icon } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { Text } from "../text";
+import { type AvatarContextValue, AvatarProvider, useAvatarGroupContext } from "./avatar.context";
+import {
+	resolveAvatarAccessibilityLabel,
+	resolveAvatarInitials,
+	resolveAvatarShowsImage,
+	resolveAvatarSourceKey,
+} from "./avatar.utils";
+import {
+	AVATAR_FOREGROUND_TOKEN,
+	type AvatarColor,
+	type AvatarSize,
+	type AvatarVariant,
+	avatarVariants,
+	resolveAvatarInteractive,
+	resolveAvatarSize,
+} from "./avatar.variants";
+import { AvatarBadge } from "./avatar-badge";
+import { AvatarGroup } from "./avatar-group";
+
+export type AvatarProps = Omit<PressableProps, "asChild" | "busy" | "children" | "disabled"> & {
+	/** The picture. The fallback shows while it loads, and in its place if it fails. */
+	source?: ImageSourcePropType;
+	/** The person's name. Read by screen readers, and its initials are the default fallback. */
+	name?: string;
+	/** Fallback text, when the initials of `name` are not what should show. */
+	fallback?: string;
+	/** How the fallback surface is painted. */
+	variant?: AvatarVariant;
+	/** What the fallback surface means. */
+	color?: AvatarColor;
+	/** Default `md`, or the enclosing group's size. */
+	size?: AvatarSize;
+	isDisabled?: boolean;
+	/** Passed to the `Image`. `onError` still fires, after the fallback has taken over. */
+	imageProps?: Omit<ImageProps, "source">;
+	/** Overlays — an `Avatar.Badge`. */
+	children?: ReactNode;
+};
+
+function AvatarRoot({
+	source,
+	name,
+	fallback,
+	variant = "soft",
+	color = "default",
+	size: sizeProp,
+	isDisabled = false,
+	imageProps,
+	accessibilityLabel,
+	onPress,
+	onLongPress,
+	haptic,
+	feedback = "scale",
+	pressedScale,
+	pressedOpacity,
+	className,
+	children,
+	...props
+}: AvatarProps): ReactElement {
+	const group = useAvatarGroupContext();
+	const size = resolveAvatarSize({ size: sizeProp, groupSize: group?.size });
+	const context = useMemo<AvatarContextValue>(
+		() => ({ size, variant, color, isDisabled }),
+		[size, variant, color, isDisabled]
+	);
+
+	// Remembered by key, not by object: an inline `source={{ uri }}` is a new
+	// object every render, and a new URI has to retry on its own.
+	const sourceKey = resolveAvatarSourceKey(source);
+	const [failedKey, setFailedKey] = useState<string | null>(null);
+	const showsImage = resolveAvatarShowsImage({ sourceKey, failedKey });
+	const slots = avatarVariants({ size, variant, color, isDisabled, hasImage: showsImage });
+
+	const initials = fallback?.trim() || resolveAvatarInitials(name);
+	const label = resolveAvatarAccessibilityLabel({ accessibilityLabel, name, fallback });
+
+	const onImageError = (event: NativeSyntheticEvent<ImageErrorEventData>) => {
+		setFailedKey(sourceKey);
+		imageProps?.onError?.(event);
+	};
+
+	// The fallback is always painted and the image goes over it, so the circle is
+	// never empty while a picture loads or after it fails.
+	const face = (
+		<View className={slots.face()}>
+			{initials ? (
+				<Text allowFontScaling={false} className={slots.fallbackLabel()} numberOfLines={1}>
+					{initials}
+				</Text>
+			) : (
+				<Icon className={slots.icon()} color={AVATAR_FOREGROUND_TOKEN[variant][color]} icon={IconPeople} />
+			)}
+			{showsImage && source !== undefined ? (
+				<Image
+					accessibilityIgnoresInvertColors
+					{...imageProps}
+					className={cn(slots.image(), imageProps?.className)}
+					onError={onImageError}
+					source={source}
+				/>
+			) : null}
+		</View>
+	);
+
+	if (!resolveAvatarInteractive({ onPress, onLongPress })) {
+		return (
+			<AvatarProvider value={context}>
+				<View
+					accessibilityLabel={label}
+					accessibilityRole={label ? "image" : undefined}
+					accessible={label !== undefined}
+					className={slots.root({ className })}
+					{...props}
+				>
+					{face}
+					{children}
+				</View>
+			</AvatarProvider>
+		);
+	}
+
+	return (
+		<AvatarProvider value={context}>
+			<Pressable
+				accessibilityLabel={label}
+				accessibilityRole="button"
+				className={slots.root({ className })}
+				disabled={isDisabled}
+				feedback={feedback}
+				haptic={haptic}
+				onLongPress={onLongPress}
+				onPress={onPress}
+				pressedOpacity={pressedOpacity}
+				pressedScale={pressedScale}
+				{...props}
+			>
+				{face}
+				{children}
+			</Pressable>
+		</AvatarProvider>
+	);
+}
+
+/**
+ * A person, as a picture — with their initials underneath for when there is no
+ * picture, it is still loading, or it failed.
+ *
+ * **The fallback is always there.** It is painted first and the image goes on
+ * top, so a slow or dead URL never leaves an empty circle. A failure is
+ * remembered for that source only: change the URI or its headers and the image
+ * is tried again. With no `fallback` and no `name` the fallback is a person glyph.
+ *
+ * `name` is what a screen reader reads, and its initials — first and last word,
+ * `Anahera Rose Tui` → `AT` — are the default fallback. `fallback` overrides the
+ * drawn text only.
+ *
+ * `variant` and `color` paint the fallback surface, on the same six colours a
+ * `Badge` takes. A size is a fixed edge: faces line up against each other, and a
+ * circle cannot grow with OS font scaling the way a label can.
+ *
+ * **An avatar is content until it is given something to do.** With no `onPress`
+ * or `onLongPress` it is a plain `View` announced as an image; supply either and
+ * it becomes a `Pressable` announced as a button.
+ *
+ * Children are overlays: `Avatar.Badge` pins a count or a presence dot to a
+ * corner, outside the clipped circle so it is never cut in half.
+ *
+ * @example
+ * <Avatar name="Aria Whitlock" source={{ uri: user.avatarUrl }} />
+ *
+ * @example
+ * <Avatar accessibilityLabel="Aria Whitlock, online" name="Aria Whitlock">
+ *   <Avatar.Badge placement="bottom-right" />
+ * </Avatar>
+ *
+ * @example
+ * <Avatar.Group max={3} total={team.length}>
+ *   {team.map((person) => <Avatar key={person.id} name={person.name} source={person.photo} />)}
+ * </Avatar.Group>
+ */
+export const Avatar = Object.assign(AvatarRoot, {
+	/** An overlay pinned to a corner — a count, or a presence dot when empty. */
+	Badge: AvatarBadge,
+	/** A row of overlapping avatars, with the people who did not fit counted at the end. */
+	Group: AvatarGroup,
+	displayName: "DelacourUI.Avatar",
+});

package/src/components/avatar/avatar.utils.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, test } from "bun:test";
+import {
+	resolveAvatarAccessibilityLabel,
+	resolveAvatarGroup,
+	resolveAvatarInitials,
+	resolveAvatarOverflowLabel,
+	resolveAvatarShowsImage,
+	resolveAvatarSourceKey,
+} from "./avatar.utils";
+
+describe("resolveAvatarInitials", () => {
+	test("takes the first letter of the first and last words", () => {
+		expect(resolveAvatarInitials("Aria Whitlock")).toBe("AW");
+		expect(resolveAvatarInitials("Anahera Rose Tui")).toBe("AT");
+	});
+
+	test("a single word gives a single letter", () => {
+		expect(resolveAvatarInitials("Mihi")).toBe("M");
+	});
+
+	test("uppercases, and ignores surrounding and repeated whitespace", () => {
+		expect(resolveAvatarInitials("  rawiri   kemp ")).toBe("RK");
+		expect(resolveAvatarInitials("lena\tvarga")).toBe("LV");
+	});
+
+	test("is empty for an empty, blank or missing name", () => {
+		expect(resolveAvatarInitials("")).toBe("");
+		expect(resolveAvatarInitials("   ")).toBe("");
+		expect(resolveAvatarInitials(undefined)).toBe("");
+	});
+
+	test("never splits a letter outside the basic plane", () => {
+		// A naive `word[0]` would take half of a surrogate pair and draw a box.
+		expect(resolveAvatarInitials("𝒜ria 𝒲hitlock")).toBe("𝒜𝒲");
+	});
+
+	test("keeps letters in scripts with no case", () => {
+		expect(resolveAvatarInitials("森山 健二")).toBe("森健");
+	});
+
+	test("skips a leading punctuation mark in a word", () => {
+		expect(resolveAvatarInitials("(Aria) 'Whitlock'")).toBe("AW");
+	});
+});
+
+describe("resolveAvatarSourceKey", () => {
+	test("is null for no source", () => {
+		expect(resolveAvatarSourceKey(undefined)).toBeNull();
+		expect(resolveAvatarSourceKey(null)).toBeNull();
+	});
+
+	test("is null for a uri that is empty", () => {
+		expect(resolveAvatarSourceKey({ uri: "" })).toBeNull();
+		expect(resolveAvatarSourceKey({})).toBeNull();
+	});
+
+	test("names a bundled asset by its module id", () => {
+		expect(resolveAvatarSourceKey(12)).toBe("asset:12");
+	});
+
+	test("changes when the uri changes", () => {
+		expect(resolveAvatarSourceKey({ uri: "https://a.test/1.png" })).not.toBe(
+			resolveAvatarSourceKey({ uri: "https://a.test/2.png" })
+		);
+	});
+
+	test("changes when only the request headers change", () => {
+		// A token refresh is a retry, so it has to clear an earlier failure.
+		expect(resolveAvatarSourceKey({ uri: "https://a.test/1.png", headers: { Authorization: "a" } })).not.toBe(
+			resolveAvatarSourceKey({ uri: "https://a.test/1.png", headers: { Authorization: "b" } })
+		);
+	});
+
+	test("is stable across renders for an equal source", () => {
+		expect(resolveAvatarSourceKey({ uri: "https://a.test/1.png", headers: { a: "1", b: "2" } })).toBe(
+			resolveAvatarSourceKey({ uri: "https://a.test/1.png", headers: { b: "2", a: "1" } })
+		);
+	});
+
+	test("reads every entry of a multi-resolution list", () => {
+		expect(resolveAvatarSourceKey([{ uri: "https://a.test/1x.png" }, { uri: "https://a.test/2x.png" }])).toBe(
+			"uri:https://a.test/1x.png|uri:https://a.test/2x.png"
+		);
+		expect(resolveAvatarSourceKey([])).toBeNull();
+	});
+});
+
+describe("resolveAvatarShowsImage", () => {
+	test("shows an image that has not failed", () => {
+		expect(resolveAvatarShowsImage({ sourceKey: "uri:a", failedKey: null })).toBe(true);
+	});
+
+	test("hides one that failed", () => {
+		expect(resolveAvatarShowsImage({ sourceKey: "uri:a", failedKey: "uri:a" })).toBe(false);
+	});
+
+	test("retries a new source after an earlier one failed", () => {
+		expect(resolveAvatarShowsImage({ sourceKey: "uri:b", failedKey: "uri:a" })).toBe(true);
+	});
+
+	test("never shows an image with no source", () => {
+		expect(resolveAvatarShowsImage({ sourceKey: null, failedKey: null })).toBe(false);
+	});
+});
+
+describe("resolveAvatarGroup", () => {
+	test("shows every child when nothing caps it", () => {
+		expect(resolveAvatarGroup({ count: 4 })).toEqual({ visible: 4, overflow: 0 });
+	});
+
+	test("max caps the faces, not the row", () => {
+		expect(resolveAvatarGroup({ count: 5, max: 3 })).toEqual({ visible: 3, overflow: 2 });
+	});
+
+	test("a max at or above the count adds no overflow", () => {
+		expect(resolveAvatarGroup({ count: 3, max: 3 })).toEqual({ visible: 3, overflow: 0 });
+		expect(resolveAvatarGroup({ count: 3, max: 10 })).toEqual({ visible: 3, overflow: 0 });
+	});
+
+	test("total counts the people who were never passed as children", () => {
+		expect(resolveAvatarGroup({ count: 3, total: 40 })).toEqual({ visible: 3, overflow: 37 });
+	});
+
+	test("max and total compose", () => {
+		expect(resolveAvatarGroup({ count: 5, max: 3, total: 40 })).toEqual({ visible: 3, overflow: 37 });
+	});
+
+	test("a total below the count is ignored rather than going negative", () => {
+		expect(resolveAvatarGroup({ count: 5, total: 2 })).toEqual({ visible: 5, overflow: 0 });
+	});
+
+	test("a negative, fractional or non-finite max is clamped", () => {
+		expect(resolveAvatarGroup({ count: 5, max: -1 })).toEqual({ visible: 0, overflow: 5 });
+		expect(resolveAvatarGroup({ count: 5, max: 2.7 })).toEqual({ visible: 2, overflow: 3 });
+		expect(resolveAvatarGroup({ count: 5, max: Number.NaN })).toEqual({ visible: 5, overflow: 0 });
+	});
+
+	test("a non-finite total is ignored", () => {
+		expect(resolveAvatarGroup({ count: 2, total: Number.POSITIVE_INFINITY })).toEqual({ visible: 2, overflow: 0 });
+	});
+
+	test("an empty group is empty", () => {
+		expect(resolveAvatarGroup({ count: 0 })).toEqual({ visible: 0, overflow: 0 });
+	});
+});
+
+describe("resolveAvatarOverflowLabel", () => {
+	test("draws a plus and the count", () => {
+		expect(resolveAvatarOverflowLabel(2)).toEqual({ text: "+2", accessibilityLabel: "2 more" });
+	});
+
+	test("caps what is drawn at 99, never what is read", () => {
+		expect(resolveAvatarOverflowLabel(1234)).toEqual({ text: "99+", accessibilityLabel: "1234 more" });
+	});
+});
+
+describe("resolveAvatarAccessibilityLabel", () => {
+	test("prefers the name", () => {
+		expect(resolveAvatarAccessibilityLabel({ name: "Aria Whitlock", fallback: "AW" })).toBe("Aria Whitlock");
+	});
+
+	test("falls back to the fallback text", () => {
+		expect(resolveAvatarAccessibilityLabel({ fallback: "AW" })).toBe("AW");
+	});
+
+	test("is undefined when there is nothing to read", () => {
+		expect(resolveAvatarAccessibilityLabel({ name: "  " })).toBeUndefined();
+		expect(resolveAvatarAccessibilityLabel({})).toBeUndefined();
+	});
+
+	test("an explicit label wins over both", () => {
+		expect(resolveAvatarAccessibilityLabel({ accessibilityLabel: "You", name: "Aria Whitlock" })).toBe("You");
+	});
+});

package/src/components/avatar/avatar.utils.ts

@@ -0,0 +1,141 @@
+/**
+ * The avatar's pure decisions — initials, image retry, group overflow and the
+ * name a screen reader reads.
+ *
+ * Free of React Native imports so `bun test` reaches every one of them. The
+ * source type is restated structurally rather than imported as
+ * `ImageSourcePropType` for the same reason. See AGENTS.md.
+ */
+
+/** One entry of an image source, as `Image` accepts it — a URI request or a bundled asset's module id. */
+export type AvatarSourceEntry = number | { uri?: string; headers?: Record<string, string> };
+
+/** Anything `Image`'s `source` accepts: one entry or a list of resolutions. */
+export type AvatarSource = AvatarSourceEntry | readonly AvatarSourceEntry[];
+
+/** A letter or number in any script, which is what an initial has to start with. */
+const INITIAL = /[\p{L}\p{N}]/u;
+
+/** The first letter or number of a word, whole — never half a surrogate pair. */
+function initialOf(word: string): string {
+	return Array.from(word).find((char) => INITIAL.test(char)) ?? "";
+}
+
+/**
+ * Up to two initials from a name: the first letter of the first word and of the
+ * last. `Anahera Rose Tui` reads `AT`, which is how a person signs rather than
+ * how a form abbreviates them. A single word gives a single letter.
+ *
+ * Walks code points rather than UTF-16 units, so a letter outside the basic
+ * plane is kept whole instead of drawn as a replacement box, and skips leading
+ * punctuation so a quoted nickname still gives a letter.
+ */
+export function resolveAvatarInitials(name: string | undefined): string {
+	const words = (name ?? "").trim().split(/\s+/).filter(Boolean);
+	if (words.length === 0) return "";
+	const first = initialOf(words[0] ?? "");
+	const last = words.length > 1 ? initialOf(words[words.length - 1] ?? "") : "";
+	return `${first}${last}`.toUpperCase();
+}
+
+function entryKey(entry: AvatarSourceEntry): string | null {
+	if (typeof entry === "number") return `asset:${entry}`;
+	if (!entry.uri) return null;
+	if (!entry.headers) return `uri:${entry.uri}`;
+	const headers = Object.keys(entry.headers)
+		.sort()
+		.map((name) => `${name}=${entry.headers?.[name]}`)
+		.join("&");
+	return `uri:${entry.uri}#${headers}`;
+}
+
+/**
+ * A string that changes exactly when the image request changes.
+ *
+ * The avatar remembers which source failed by this key rather than by object
+ * identity, because an inline `source={{ uri }}` is a new object every render —
+ * keyed by identity, a failed image would retry forever. Keyed by URI alone, a
+ * token refresh in the headers would never retry at all. Header order is
+ * normalised so an equal request is an equal key.
+ *
+ * `null` means there is nothing to load.
+ */
+export function resolveAvatarSourceKey(source: AvatarSource | null | undefined): string | null {
+	if (source === null || source === undefined) return null;
+	const entries: readonly AvatarSourceEntry[] = Array.isArray(source) ? source : [source as AvatarSourceEntry];
+	const keys = entries.map(entryKey).filter((key): key is string => key !== null);
+	return keys.length === 0 ? null : keys.join("|");
+}
+
+/**
+ * Whether the image layer is mounted.
+ *
+ * The fallback is always underneath, so this is only ever a question of whether
+ * the image goes on top. A failure is remembered for the key that failed, which
+ * is what makes a new URI retry on its own.
+ */
+export function resolveAvatarShowsImage({
+	sourceKey,
+	failedKey,
+}: {
+	sourceKey: string | null;
+	failedKey: string | null;
+}): boolean {
+	return sourceKey !== null && sourceKey !== failedKey;
+}
+
+/**
+ * How many faces a group draws, and how many people the trailing tile counts.
+ *
+ * `max` caps the faces, not the row: five people at `max={3}` is three faces and
+ * `+2`. `total` is the number of people when the children are only the first
+ * few of them, so three children out of forty reads `+37`. A `total` below the
+ * number of children is ignored rather than allowed to go negative, and a
+ * nonsensical `max` is clamped rather than trusted.
+ */
+export function resolveAvatarGroup({ count, max, total }: { count: number; max?: number; total?: number }): {
+	visible: number;
+	overflow: number;
+} {
+	const cap = max === undefined || Number.isNaN(max) ? count : Math.max(0, Math.floor(max));
+	const visible = Math.min(count, cap);
+	const people = total !== undefined && Number.isFinite(total) ? Math.max(count, Math.floor(total)) : count;
+	return { visible, overflow: people - visible };
+}
+
+/** The most the overflow tile draws before it reads `99+`. Three digits do not fit a small circle. */
+export const AVATAR_OVERFLOW_DISPLAY_MAX = 99;
+
+/**
+ * What the overflow tile draws and what it reads.
+ *
+ * The drawn count stops at {@link AVATAR_OVERFLOW_DISPLAY_MAX}; the spoken one
+ * never does, because a screen reader has room for the real number.
+ */
+export function resolveAvatarOverflowLabel(overflow: number): { text: string; accessibilityLabel: string } {
+	return {
+		text: overflow > AVATAR_OVERFLOW_DISPLAY_MAX ? `${AVATAR_OVERFLOW_DISPLAY_MAX}+` : `+${overflow}`,
+		accessibilityLabel: `${overflow} more`,
+	};
+}
+
+/**
+ * The name a screen reader gives the avatar: an explicit label, else the
+ * person's name, else the fallback text. Blank strings count as absent, so an
+ * avatar with nothing to say is not announced as an empty image.
+ */
+export function resolveAvatarAccessibilityLabel({
+	accessibilityLabel,
+	name,
+	fallback,
+}: {
+	accessibilityLabel?: string;
+	name?: string;
+	fallback?: string;
+}): string | undefined {
+	for (const candidate of [accessibilityLabel, name, fallback]) {
+		const trimmed = candidate?.trim();
+		if (trimmed) return trimmed;
+	}
+	return undefined;
+}