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

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

@@ -0,0 +1,251 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens } from "../../styles/theme-tokens.test";
+import { ICON_SIZE_TOKENS } from "../../styles/tokens";
+import {
+	AVATAR_BADGE_PLACEMENTS,
+	AVATAR_COLORS,
+	AVATAR_FOREGROUND_TOKEN,
+	AVATAR_SIZE_POINTS,
+	AVATAR_SIZES,
+	AVATAR_VARIANTS,
+	avatarVariants,
+	resolveAvatarInteractive,
+	resolveAvatarOverlap,
+	resolveAvatarSize,
+} from "./avatar.variants";
+
+const LIGHT = declaredTokens("light");
+const DARK = declaredTokens("dark");
+
+/** The `size-N` step a class string sets its edge from, in points (Tailwind's 4pt spacing unit). */
+function edgeOf(cls: string): number {
+	return Number(cls.match(/\bsize-(\d+)\b/)?.[1]) * 4;
+}
+
+/** The `text-*` colour token a class string resolves to, minus the prefix. */
+function colorToken(cls: string): string | undefined {
+	return cls.match(/\btext-((?:[a-z]+-)*(?:foreground|background))\b/)?.[1];
+}
+
+/** The `bg-*` token a class string fills with, minus the prefix. */
+function fillToken(cls: string): string | undefined {
+	return cls.match(/\bbg-([a-z-]+)\b/)?.[1];
+}
+
+/** Position of a slot's `size-icon-*` token on the shared icon scale. */
+function iconStep(cls: string): number {
+	const token = cls.match(/\bsize-(icon-[\w-]+)\b/)?.[1];
+	return ICON_SIZE_TOKENS.indexOf(token as (typeof ICON_SIZE_TOKENS)[number]);
+}
+
+const TEXT_SCALE = ["text-xs", "text-sm", "text-base", "text-lg", "text-xl", "text-2xl"] as const;
+function textStep(cls: string): number {
+	return TEXT_SCALE.findIndex((step) => new RegExp(`\\b${step}\\b`).test(cls));
+}
+
+describe("sizes", () => {
+	test("the face's class and AVATAR_SIZE_POINTS agree at every size", () => {
+		// The group computes its overlap in points; a class that drifted from the
+		// number would slide faces too far or not far enough.
+		for (const size of AVATAR_SIZES) {
+			expect(edgeOf(avatarVariants({ size }).root())).toBe(AVATAR_SIZE_POINTS[size]);
+		}
+	});
+
+	test("the scale ascends", () => {
+		const points = AVATAR_SIZES.map((size) => AVATAR_SIZE_POINTS[size]);
+		expect([...points].sort((a, b) => a - b)).toEqual(points);
+		expect(new Set(points).size).toBe(points.length);
+	});
+
+	test("the fallback text and glyph grow with the face", () => {
+		const text = AVATAR_SIZES.map((size) => textStep(avatarVariants({ size }).fallbackLabel()));
+		const icons = AVATAR_SIZES.map((size) => iconStep(avatarVariants({ size }).icon()));
+		for (const step of [...text, ...icons]) expect(step).toBeGreaterThanOrEqual(0);
+		expect([...text].sort((a, b) => a - b)).toEqual(text);
+		expect([...icons].sort((a, b) => a - b)).toEqual(icons);
+	});
+
+	test("the overflow tile is the same edge as a face", () => {
+		for (const size of AVATAR_SIZES) {
+			const slots = avatarVariants({ size });
+			expect(edgeOf(slots.overflow())).toBe(edgeOf(slots.root()));
+		}
+	});
+});
+
+describe("colour matrix", () => {
+	test("every variant × colour cell is distinct", () => {
+		const seen = new Set<string>();
+		for (const variant of AVATAR_VARIANTS) {
+			for (const color of AVATAR_COLORS) {
+				const slots = avatarVariants({ variant, color });
+				seen.add(`${slots.face()}|${slots.fallbackLabel()}`);
+			}
+		}
+		expect(seen.size).toBe(AVATAR_VARIANTS.length * AVATAR_COLORS.length);
+	});
+
+	test("every cell fills its face and colours its label", () => {
+		for (const variant of AVATAR_VARIANTS) {
+			for (const color of AVATAR_COLORS) {
+				const slots = avatarVariants({ variant, color });
+				expect(fillToken(slots.face())).toBeDefined();
+				expect(colorToken(slots.fallbackLabel())).toBeDefined();
+			}
+		}
+	});
+
+	test("AVATAR_FOREGROUND_TOKEN names the token the label resolves to", () => {
+		// A glyph fallback and a text fallback must be the same shade.
+		for (const variant of AVATAR_VARIANTS) {
+			for (const color of AVATAR_COLORS) {
+				expect(AVATAR_FOREGROUND_TOKEN[variant][color]).toBe(
+					colorToken(avatarVariants({ variant, color }).fallbackLabel()) ?? ""
+				);
+			}
+		}
+	});
+
+	test("every token the matrix names is declared in both themes", () => {
+		for (const variant of AVATAR_VARIANTS) {
+			for (const color of AVATAR_COLORS) {
+				const slots = avatarVariants({ variant, color });
+				for (const token of [fillToken(slots.face()), colorToken(slots.fallbackLabel())]) {
+					expect(LIGHT.has(token ?? "")).toBe(true);
+					expect(DARK.has(token ?? "")).toBe(true);
+				}
+			}
+		}
+	});
+});
+
+describe("structure", () => {
+	test("the face clips and the root does not", () => {
+		// A badge pinned to the corner hangs outside the circle; clipping the root
+		// would cut it in half.
+		const slots = avatarVariants();
+		expect(slots.face()).toContain("overflow-hidden");
+		expect(slots.face()).toContain("rounded-full");
+		expect(slots.root()).not.toContain("overflow-hidden");
+	});
+
+	test("the root holds a fixed edge and never overrides its parent's alignment", () => {
+		// `self-start` pinned every avatar in an `items-end` or `items-center` row
+		// to its top. A fixed size is what keeps a column from stretching it.
+		for (const size of AVATAR_SIZES) {
+			const slots = avatarVariants({ size });
+			expect(slots.root()).not.toMatch(/\bself-/);
+			expect(slots.face()).toContain("size-full");
+		}
+		expect(avatarVariants().group()).not.toMatch(/\bself-/);
+	});
+
+	test("no view slot carries a text colour", () => {
+		// A React Native View does not cascade colour to a Text descendant.
+		const slots = avatarVariants();
+		for (const slot of [slots.root(), slots.face(), slots.badge(), slots.group(), slots.groupItem()]) {
+			expect(colorToken(slot)).toBeUndefined();
+		}
+	});
+
+	test("a disabled avatar fades", () => {
+		expect(avatarVariants({ isDisabled: true }).root()).toContain("opacity-50");
+		expect(avatarVariants({ isDisabled: false }).root()).not.toContain("opacity-50");
+	});
+
+	test("a group ring is the page background, so it reads on any surface", () => {
+		// The overflow tile is wrapped in the same item, so it wears the same ring
+		// and lines up with the faces rather than sitting four points smaller.
+		expect(avatarVariants().groupItem()).toContain("border-background");
+		expect(avatarVariants().overflow()).not.toContain("border-background");
+	});
+
+	test("every badge placement pins to a different corner", () => {
+		const classes = AVATAR_BADGE_PLACEMENTS.map((placement) => avatarVariants({ placement }).badge());
+		expect(new Set(classes).size).toBe(AVATAR_BADGE_PLACEMENTS.length);
+		for (const cls of classes) expect(cls).toContain("absolute");
+	});
+
+	test("the presence dot grows with the face", () => {
+		const dots = AVATAR_SIZES.map((size) =>
+			Number(
+				avatarVariants({ size })
+					.dot()
+					.match(/\bsize-([\d.]+)\b/)?.[1]
+			)
+		);
+		for (const dot of dots) expect(Number.isFinite(dot)).toBe(true);
+		expect([...dots].sort((a, b) => a - b)).toEqual(dots);
+	});
+});
+
+describe("the neutral edge", () => {
+	test("a default-colour fallback carries a hairline border in both variants", () => {
+		// Its fill sits a percent or two from the page in light, so without an
+		// edge a neutral face vanishes into the background.
+		for (const variant of AVATAR_VARIANTS) {
+			expect(avatarVariants({ variant, color: "default", hasImage: false }).face()).toContain("border-border");
+		}
+	});
+
+	test("the border goes once a photo is on top", () => {
+		for (const variant of AVATAR_VARIANTS) {
+			expect(avatarVariants({ variant, color: "default", hasImage: true }).face()).not.toMatch(/\bborder\b/);
+		}
+	});
+
+	test("a coloured fallback needs no edge", () => {
+		for (const color of AVATAR_COLORS.filter((value) => value !== "default")) {
+			expect(avatarVariants({ color, hasImage: false }).face()).not.toMatch(/\bborder\b/);
+		}
+	});
+
+	test("the overflow tile carries it too", () => {
+		expect(avatarVariants().overflow()).toContain("border-border");
+	});
+});
+
+describe("resolveAvatarSize", () => {
+	test("the avatar's own size wins", () => {
+		expect(resolveAvatarSize({ size: "sm", groupSize: "xl" })).toBe("sm");
+	});
+
+	test("then the enclosing group's", () => {
+		expect(resolveAvatarSize({ groupSize: "lg" })).toBe("lg");
+	});
+
+	test("then md", () => {
+		expect(resolveAvatarSize({})).toBe("md");
+	});
+});
+
+describe("resolveAvatarOverlap", () => {
+	test("defaults to a third of the face, rounded", () => {
+		for (const size of AVATAR_SIZES) {
+			expect(resolveAvatarOverlap({ size })).toBe(Math.round(AVATAR_SIZE_POINTS[size] / 3));
+		}
+	});
+
+	test("an explicit overlap wins, and 0 closes the stack into a row", () => {
+		expect(resolveAvatarOverlap({ size: "md", overlap: 6 })).toBe(6);
+		expect(resolveAvatarOverlap({ size: "md", overlap: 0 })).toBe(0);
+	});
+
+	test("never slides a face further than its own edge, nor backwards", () => {
+		expect(resolveAvatarOverlap({ size: "md", overlap: 999 })).toBe(AVATAR_SIZE_POINTS.md);
+		expect(resolveAvatarOverlap({ size: "md", overlap: -4 })).toBe(0);
+		expect(resolveAvatarOverlap({ size: "md", overlap: Number.NaN })).toBe(Math.round(AVATAR_SIZE_POINTS.md / 3));
+	});
+});
+
+describe("resolveAvatarInteractive", () => {
+	test("is inert with no handler", () => {
+		expect(resolveAvatarInteractive({})).toBe(false);
+	});
+
+	test("becomes pressable with either handler", () => {
+		expect(resolveAvatarInteractive({ onPress: () => {} })).toBe(true);
+		expect(resolveAvatarInteractive({ onLongPress: () => {} })).toBe(true);
+	});
+});

package/src/components/avatar/avatar.variants.ts

@@ -0,0 +1,270 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/** How the fallback surface is painted. Orthogonal to {@link AVATAR_COLORS}. */
+export const AVATAR_VARIANTS = ["soft", "solid"] as const;
+
+/** What the fallback surface means. The same six a `Badge` takes, so the two pair. */
+export const AVATAR_COLORS = ["default", "primary", "success", "warning", "destructive", "info"] as const;
+
+export const AVATAR_SIZES = ["sm", "md", "lg", "xl"] as const;
+
+/** Where an `Avatar.Badge` is pinned. */
+export const AVATAR_BADGE_PLACEMENTS = ["top-right", "bottom-right"] as const;
+
+export type AvatarVariant = (typeof AVATAR_VARIANTS)[number];
+export type AvatarColor = (typeof AVATAR_COLORS)[number];
+export type AvatarSize = (typeof AVATAR_SIZES)[number];
+export type AvatarBadgePlacement = (typeof AVATAR_BADGE_PLACEMENTS)[number];
+
+/**
+ * A face's edge in points, at each size.
+ *
+ * The one place a size is a number rather than a class, and it exists because
+ * `Avatar.Group` has to compute an overlap: a negative margin set at runtime
+ * cannot be a class (Tailwind's scanner is static). A test pins every entry to
+ * the `size-*` class the `face` slot resolves to, so the two cannot drift.
+ */
+export const AVATAR_SIZE_POINTS: Record<AvatarSize, number> = {
+	sm: 32,
+	md: 40,
+	lg: 48,
+	xl: 64,
+};
+
+/**
+ * Theme token that gives the fallback glyph its colour.
+ *
+ * The avatar's counterpart to `BADGE_FOREGROUND_TOKEN`: a colour that has to
+ * reach an SVG paint prop cannot be a class. Every entry names the token the
+ * `fallbackLabel` slot resolves to, so initials and the glyph that stands in for
+ * them are the same shade — a test asserts the pair.
+ */
+export const AVATAR_FOREGROUND_TOKEN: Record<AvatarVariant, Record<AvatarColor, string>> = {
+	soft: {
+		default: "muted-foreground",
+		primary: "tertiary-foreground",
+		success: "success-soft-foreground",
+		warning: "warning-soft-foreground",
+		destructive: "destructive-soft-foreground",
+		info: "info-soft-foreground",
+	},
+	solid: {
+		default: "secondary-foreground",
+		primary: "primary-foreground",
+		success: "success-foreground",
+		warning: "warning-foreground",
+		destructive: "destructive-foreground",
+		info: "info-foreground",
+	},
+};
+
+/**
+ * Styling for every part of an avatar, and of a group of them.
+ *
+ * **The root carries the edge, not `self-start`.** A fixed width and height is
+ * something Yoga's `stretch` never overrides, so an avatar in a column keeps its
+ * size without the escape hatch `Badge` needs — and, unlike `self-start`, it
+ * leaves the parent's own alignment alone. `self-start` pinned every avatar in
+ * an `items-end` or `items-center` row to the top of it: mixed sizes lost their
+ * baseline and a list row's avatar sat above its text. The face fills the root.
+ *
+ * **Two boxes, not one.** `root` is unclipped and `face` is the clipped circle
+ * inside it. 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 the
+ * face and never on the root.
+ *
+ * **The fallback is always painted; the image goes on top.** So the fill and
+ * the initials show while the image loads and after it fails, and a slow or dead
+ * URL never leaves an empty circle.
+ *
+ * **A size is an edge, and it is a fixed one** — unlike a badge, whose size is
+ * padding. A face lines up against other faces in a group and against rows in a
+ * list, and must not grow with OS font scaling; the initials are one or two
+ * glyphs and are sized to fit the smallest step. {@link AVATAR_SIZE_POINTS} is
+ * the same scale as a number, for the group's overlap.
+ *
+ * **The ring in a group is the page background** — `border-background` on the
+ * wrapper around each face, never on the face itself, so a face in a group is the
+ * same edge as one outside it and the stack reads as separate people on any
+ * surface. The overflow tile sits in the same wrapper for the same reason.
+ *
+ * **A neutral face has an edge.** `muted` and `secondary` sit a percent or two
+ * from the page in light, so a `default` fallback and the `+N` tile draw a
+ * hairline `border-border` — inside the box, so no size moves. It goes while a
+ * photo is mounted (`hasImage`), because a photo carries its own edge and a
+ * grey line around a face reads as a frame.
+ *
+ * The neutral end of the colour matrix reuses the fills `Badge` does — `muted`
+ * and `tertiary` for `soft`, `secondary` for a `solid` default — so an avatar
+ * beside a badge of the same colour reads as one family.
+ *
+ * No view slot holds a `text-*` utility: a React Native `View` does not cascade
+ * colour to a `Text` descendant.
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const avatarVariants = tv({
+	slots: {
+		root: "relative",
+		face: "size-full items-center justify-center overflow-hidden rounded-full",
+		image: "absolute inset-0",
+		fallbackLabel: "text-center font-medium",
+		/** Edge length the fallback glyph inherits. */
+		icon: "",
+		badge: "absolute items-center justify-center",
+		dot: "rounded-full border-2 border-background",
+		group: "flex-row items-center",
+		groupItem: "rounded-full border-2 border-background",
+		overflow: "items-center justify-center overflow-hidden rounded-full border border-border bg-muted",
+		overflowLabel: "text-center font-medium text-muted-foreground",
+	},
+	variants: {
+		variant: {
+			soft: {},
+			solid: {},
+		},
+		// `color` alone paints only the presence dot; the face needs `variant`
+		// too, so its twelve cells live in `compoundVariants`.
+		color: {
+			default: { dot: "bg-muted-foreground" },
+			primary: { dot: "bg-primary" },
+			success: { dot: "bg-success" },
+			warning: { dot: "bg-warning" },
+			destructive: { dot: "bg-destructive" },
+			info: { dot: "bg-info" },
+		},
+		size: {
+			sm: {
+				root: "size-8",
+				fallbackLabel: "text-xs",
+				icon: "size-icon-sm",
+				dot: "size-2.5",
+				overflow: "size-8",
+				overflowLabel: "text-xs",
+			},
+			md: {
+				root: "size-10",
+				fallbackLabel: "text-sm",
+				icon: "size-icon-lg",
+				dot: "size-3",
+				overflow: "size-10",
+				overflowLabel: "text-sm",
+			},
+			lg: {
+				root: "size-12",
+				fallbackLabel: "text-base",
+				icon: "size-icon-xl",
+				dot: "size-3.5",
+				overflow: "size-12",
+				overflowLabel: "text-base",
+			},
+			xl: {
+				root: "size-16",
+				fallbackLabel: "text-xl",
+				icon: "size-icon-2xl",
+				dot: "size-4",
+				overflow: "size-16",
+				overflowLabel: "text-xl",
+			},
+		},
+		placement: {
+			"top-right": { badge: "-top-1 -right-1" },
+			"bottom-right": { badge: "-bottom-0.5 -right-0.5" },
+		},
+		// Whether a photo is mounted over the fallback. Read only by the neutral
+		// edge below — a photo carries its own edge.
+		hasImage: { true: {}, false: {} },
+		// The empty `false` branch is load-bearing typing, not a placeholder.
+		// See the note in button.variants.ts.
+		isDisabled: { true: { root: "opacity-50" }, false: {} },
+	},
+	compoundVariants: [
+		{ variant: "soft", color: "default", class: { face: "bg-muted", fallbackLabel: "text-muted-foreground" } },
+		{ variant: "soft", color: "primary", class: { face: "bg-tertiary", fallbackLabel: "text-tertiary-foreground" } },
+		{
+			variant: "soft",
+			color: "success",
+			class: { face: "bg-success-soft", fallbackLabel: "text-success-soft-foreground" },
+		},
+		{
+			variant: "soft",
+			color: "warning",
+			class: { face: "bg-warning-soft", fallbackLabel: "text-warning-soft-foreground" },
+		},
+		{
+			variant: "soft",
+			color: "destructive",
+			class: { face: "bg-destructive-soft", fallbackLabel: "text-destructive-soft-foreground" },
+		},
+		{ variant: "soft", color: "info", class: { face: "bg-info-soft", fallbackLabel: "text-info-soft-foreground" } },
+
+		{
+			variant: "solid",
+			color: "default",
+			class: { face: "bg-secondary", fallbackLabel: "text-secondary-foreground" },
+		},
+		{ variant: "solid", color: "primary", class: { face: "bg-primary", fallbackLabel: "text-primary-foreground" } },
+		{ variant: "solid", color: "success", class: { face: "bg-success", fallbackLabel: "text-success-foreground" } },
+		{ variant: "solid", color: "warning", class: { face: "bg-warning", fallbackLabel: "text-warning-foreground" } },
+		{
+			variant: "solid",
+			color: "destructive",
+			class: { face: "bg-destructive", fallbackLabel: "text-destructive-foreground" },
+		},
+		{ variant: "solid", color: "info", class: { face: "bg-info", fallbackLabel: "text-info-foreground" } },
+
+		{ color: "default", hasImage: false, class: { face: "border border-border" } },
+	],
+	defaultVariants: {
+		variant: "soft",
+		color: "default",
+		size: "md",
+		placement: "top-right",
+		hasImage: false,
+		isDisabled: false,
+	},
+});
+
+/**
+ * An avatar's size: its own, else its group's, else `md`.
+ *
+ * A group sets the size for every face in it, and a child that states its own
+ * still wins — the order a caller reading the JSX would expect.
+ */
+export function resolveAvatarSize({ size, groupSize }: { size?: AvatarSize; groupSize?: AvatarSize }): AvatarSize {
+	return size ?? groupSize ?? "md";
+}
+
+/**
+ * Points each face in a group slides under the one before it.
+ *
+ * Defaults to a third of the face's edge, which leaves enough of each face to
+ * recognise. An explicit value wins — `0` closes the stack into a plain row —
+ * and is clamped between nothing and a whole face, so a typo cannot stack every
+ * face on the first or push them apart.
+ */
+export function resolveAvatarOverlap({ size, overlap }: { size: AvatarSize; overlap?: number }): number {
+	const edge = AVATAR_SIZE_POINTS[size];
+	if (overlap === undefined || Number.isNaN(overlap)) return Math.round(edge / 3);
+	return Math.min(edge, Math.max(0, overlap));
+}
+
+/**
+ * Whether the root should render as a `Pressable` rather than a plain `View`.
+ *
+ * The rule `Badge` follows, for the reason it does: an avatar is content until a
+ * caller gives it something to do, and a list of fifty should not mount fifty
+ * gesture detectors or announce fifty buttons with no action.
+ */
+export function resolveAvatarInteractive({
+	onPress,
+	onLongPress,
+}: {
+	onPress?: () => void;
+	onLongPress?: () => void;
+}): boolean {
+	return onPress !== undefined || onLongPress !== undefined;
+}
+
+export type AvatarVariantProps = VariantProps<typeof avatarVariants>;

package/src/components/avatar/index.ts

@@ -0,0 +1,39 @@
+export { Avatar, type AvatarProps } from "./avatar";
+export {
+	type AvatarContextValue,
+	type AvatarGroupContextValue,
+	AvatarProvider,
+	useAvatar,
+	useAvatarContext,
+	useAvatarGroupContext,
+} from "./avatar.context";
+export {
+	AVATAR_OVERFLOW_DISPLAY_MAX,
+	type AvatarSource,
+	type AvatarSourceEntry,
+	resolveAvatarAccessibilityLabel,
+	resolveAvatarGroup,
+	resolveAvatarInitials,
+	resolveAvatarOverflowLabel,
+	resolveAvatarShowsImage,
+	resolveAvatarSourceKey,
+} from "./avatar.utils";
+export {
+	AVATAR_BADGE_PLACEMENTS,
+	AVATAR_COLORS,
+	AVATAR_FOREGROUND_TOKEN,
+	AVATAR_SIZE_POINTS,
+	AVATAR_SIZES,
+	AVATAR_VARIANTS,
+	type AvatarBadgePlacement,
+	type AvatarColor,
+	type AvatarSize,
+	type AvatarVariant,
+	type AvatarVariantProps,
+	avatarVariants,
+	resolveAvatarInteractive,
+	resolveAvatarOverlap,
+	resolveAvatarSize,
+} from "./avatar.variants";
+export type { AvatarBadgeProps } from "./avatar-badge";
+export type { AvatarGroupProps } from "./avatar-group";

package/src/components/badge/AGENTS.md

@@ -46,6 +46,11 @@ A compact label for status, category or count. Compound root plus `Badge.Label`,
   with `fade` rather than the root's `scale` — a spring on a glyph that small
   reads as a jitter. Reach for the part by hand only to place it somewhere other
   than last.
+- **`closeTestID` reaches the composed close control.** The root's own `testID`
+  names the badge; the close part is a separate pressable with no id of its own
+  unless the root forwards one, so a flow or test could only find it by its label.
+  `closeTestID` is named like `closeAccessibilityLabel`, the other prop the root
+  passes through to it.
 - **A size is padding, never a height.** `Text` respects OS font scaling, so a
   fixed height clips the label at a large accessibility step instead of growing
   with it — and unlike `h-button-*` or `h-navbar-row`, a badge lines up against
@@ -81,3 +86,8 @@ A compact label for status, category or count. Compound root plus `Badge.Label`,
 - **String children** are wrapped in a `Badge.Label` automatically, consecutive
   strings collapsing into one — the same rule, and the same reason, as
   [`Button`](../button/AGENTS.md).
+
+- **`material="etched"` squares the capsule and tints.** The root and the close button take
+  `rounded-sm`; `soft` status fills become `bg-<status>/8` in light and `/16` in dark, written out
+  per colour because Tailwind's scanner cannot see a built class. The material rides the badge
+  context so the close button follows the root.

package/src/components/badge/badge-close-button.tsx

@@ -30,13 +30,13 @@ export function BadgeCloseButton({
 	feedback = "fade",
 	...props
 }: BadgeCloseButtonProps): ReactElement {
-	const { size, isDisabled } = useBadgePart("Badge.CloseButton");
+	const { size, isDisabled, material } = useBadgePart("Badge.CloseButton");
 
 	return (
 		<Pressable
 			accessibilityLabel={accessibilityLabel}
 			accessibilityRole="button"
-			className={badgeVariants({ size }).closeButton({ className })}
+			className={badgeVariants({ material, size }).closeButton({ className })}
 			disabled={isDisabled}
 			feedback={feedback}
 			{...props}

package/src/components/badge/badge.context.tsx

@@ -1,5 +1,5 @@
 import { createContext, type ReactElement, type ReactNode, use } from "react";
-import type { BadgeColor, BadgeSize, BadgeVariant } from "./badge.variants";
+import type { BadgeColor, BadgeMaterial, BadgeSize, BadgeVariant } from "./badge.variants";
 
 export type BadgeContextValue = {
 	/** Size of the badge. */
@@ -10,6 +10,7 @@ export type BadgeContextValue = {
 	color: BadgeColor;
 	/** Whether the badge is disabled. */
 	isDisabled: boolean;
+	material: BadgeMaterial;
 };
 
 const BadgeContext = createContext<BadgeContextValue | null>(null);

package/src/components/badge/badge.tsx

@@ -7,6 +7,7 @@ import { type BadgeContextValue, BadgeProvider } from "./badge.context";
 import {
 	BADGE_FOREGROUND_TOKEN,
 	type BadgeColor,
+	type BadgeMaterial,
 	type BadgeSize,
 	type BadgeVariant,
 	badgeVariants,
@@ -23,21 +24,27 @@ export type BadgeProps = Omit<PressableProps, "asChild" | "busy" | "children" |
 	/** What the surface means. */
 	color?: BadgeColor;
 	size?: BadgeSize;
+	/** `flat` by default, a capsule. `etched` squares the corner and tints soft status fills as an alpha. */
+	material?: BadgeMaterial;
 	isDisabled?: boolean;
 	/** Composes a trailing dismiss control in. Its press never reaches `onPress`. */
 	onClose?: () => void;
 	/** Name a screen reader gives the dismiss control. Defaults to `Remove`. */
 	closeAccessibilityLabel?: string;
+	/** `testID` for the dismiss control, so a test or automation can press it. */
+	closeTestID?: string;
 	children?: ReactNode;
 };
 
 function BadgeRoot({
 	variant = "solid",
 	color = "default",
+	material = "flat",
 	size = "md",
 	isDisabled = false,
 	onClose,
 	closeAccessibilityLabel,
+	closeTestID,
 	onPress,
 	onLongPress,
 	haptic,
@@ -49,11 +56,11 @@ function BadgeRoot({
 	...props
 }: BadgeProps): ReactElement {
 	const context = useMemo<BadgeContextValue>(
-		() => ({ variant, color, size, isDisabled }),
-		[variant, color, size, isDisabled]
+		() => ({ variant, color, size, isDisabled, material }),
+		[variant, color, size, isDisabled, material]
 	);
 
-	const slots = badgeVariants({ color, isDisabled, size, variant });
+	const slots = badgeVariants({ color, isDisabled, material, size, variant });
 
 	// Icons composed into the badge adopt these unless told otherwise.
 	const iconClassName = slots.icon();
@@ -70,7 +77,9 @@ function BadgeRoot({
 		<IconDefaultsProvider value={iconDefaults}>
 			<TextClassProvider value={slots.label()}>
 				{content}
-				{onClose ? <BadgeCloseButton accessibilityLabel={closeAccessibilityLabel} onPress={onClose} /> : null}
+				{onClose ? (
+					<BadgeCloseButton accessibilityLabel={closeAccessibilityLabel} onPress={onClose} testID={closeTestID} />
+				) : null}
 			</TextClassProvider>
 		</IconDefaultsProvider>
 	);