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

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

@@ -0,0 +1,50 @@
+import type { ReactElement } from "react";
+import { IconCrossSmall } from "../../icons/central";
+import { Icon } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { useAlertPart } from "./alert.context";
+import { alertVariants } from "./alert.variants";
+
+export type AlertCloseButtonProps = Omit<PressableProps, "asChild" | "busy" | "children">;
+
+/**
+ * The alert's trailing dismiss control.
+ *
+ * The root composes one in whenever `isDismissible` is set, so reach for this
+ * by hand only to place it somewhere else. Pressing it calls the alert's
+ * `dismiss` and then the caller's own `onPress`.
+ *
+ * The glyph is drawn in `muted-foreground` rather than the status colour: the
+ * control is about the alert, not part of what it says, and a red cross beside
+ * a red title reads as a second warning. `fade` rather than `scale` — a spring
+ * on a glyph this small reads as a jitter. `hitSlop` lifts the target to the
+ * 44-point minimum the glyph alone falls short of.
+ */
+export function AlertCloseButton({
+	accessibilityLabel = "Dismiss",
+	className,
+	feedback = "fade",
+	hitSlop = 10,
+	onPress,
+	...props
+}: AlertCloseButtonProps): ReactElement {
+	const { size, dismiss } = useAlertPart("Alert.CloseButton");
+
+	return (
+		<Pressable
+			accessibilityLabel={accessibilityLabel}
+			accessibilityRole="button"
+			className={alertVariants({ size }).closeButton({ className })}
+			feedback={feedback}
+			hitSlop={hitSlop}
+			onPress={() => {
+				dismiss();
+				onPress?.();
+			}}
+			{...props}
+		>
+			<Icon color="muted-foreground" icon={IconCrossSmall} />
+		</Pressable>
+	);
+}
+AlertCloseButton.displayName = "DelacourUI.Alert.CloseButton";

package/src/components/alert/alert-content.tsx

@@ -0,0 +1,15 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { AlertSlotProps } from "./alert.types";
+import { alertVariants } from "./alert.variants";
+
+/**
+ * The column holding the title, the description and any action.
+ *
+ * `flex-1` with `min-w-0` is what keeps a long description wrapping inside the
+ * alert instead of pushing the close control off its edge.
+ */
+export function AlertContent({ className, ...props }: AlertSlotProps): ReactElement {
+	return <View className={alertVariants().content({ className })} {...props} />;
+}
+AlertContent.displayName = "DelacourUI.Alert.Content";

package/src/components/alert/alert-description.tsx

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useAlertPart } from "./alert.context";
+import { alertVariants } from "./alert.variants";
+
+export type AlertDescriptionProps = TextPresetProps;
+
+/**
+ * The alert's body text — always muted, whatever the status, so a long
+ * explanation under a red title never shouts.
+ */
+export function AlertDescription({ className, ...props }: AlertDescriptionProps): ReactElement {
+	const { size } = useAlertPart("Alert.Description");
+	return <Text className={alertVariants({ size }).description({ className })} {...props} />;
+}
+AlertDescription.displayName = "DelacourUI.Alert.Description";

package/src/components/alert/alert-glyphs.ts

@@ -0,0 +1,25 @@
+import { IconCircleCheck, IconCircleInfo, IconExclamationCircle, IconExclamationTriangle } from "../../icons/central";
+import type { IconComponent } from "../icon";
+import type { AlertStatus } from "./alert.variants";
+
+/**
+ * The glyph each status draws.
+ *
+ * `warning` and `destructive` differ in shape as well as colour — a triangle
+ * against a circle — so the two stay distinguishable to anyone who cannot tell
+ * amber from red. `default` shares `info`'s glyph: a neutral note is still a
+ * note, and a status of its own would need a meaning it does not have.
+ *
+ * A leaf of its own rather than a constant in `alert-indicator.tsx`: `Toast`
+ * draws the same glyph per status, so the two read as one family, and it may
+ * import a leaf across folders where it may not import a part (package rule 3).
+ * Not in `alert.variants.ts` because the glyphs are React Native SVG components,
+ * and that file must stay importable from `bun test`.
+ */
+export const ALERT_GLYPHS: Record<AlertStatus, IconComponent> = {
+	default: IconCircleInfo,
+	info: IconCircleInfo,
+	success: IconCircleCheck,
+	warning: IconExclamationTriangle,
+	destructive: IconExclamationCircle,
+};

package/src/components/alert/alert-indicator.tsx

@@ -0,0 +1,40 @@
+import type { ReactElement, ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import { Icon } from "../icon";
+import { useAlertPart } from "./alert.context";
+import { alertVariants } from "./alert.variants";
+import { ALERT_GLYPHS } from "./alert-glyphs";
+
+export type AlertIndicatorProps = ViewProps & {
+	className?: string;
+	/** Replaces the status glyph — a `Spinner`, an `Icon` of your own. It inherits the alert's icon size and colour. */
+	children?: ReactNode;
+};
+
+/**
+ * The alert's leading glyph, picked from its status.
+ *
+ * Carries the title's line height as its own height and centres the glyph in
+ * it, so the glyph sits level with the title's first line however far the
+ * description wraps.
+ *
+ * Hidden from assistive technology. The title says what happened, and a screen
+ * reader announcing "image" before it adds nothing. Children replace the glyph
+ * and inherit the alert's icon size and colour, so `<Spinner />` or
+ * `<Icon icon={IconCloud} />` needs nothing else.
+ */
+export function AlertIndicator({ className, children, ...props }: AlertIndicatorProps): ReactElement {
+	const { status, size } = useAlertPart("Alert.Indicator");
+
+	return (
+		<View
+			accessibilityElementsHidden
+			className={alertVariants({ size }).indicator({ className })}
+			importantForAccessibility="no-hide-descendants"
+			{...props}
+		>
+			{children ?? <Icon icon={ALERT_GLYPHS[status]} />}
+		</View>
+	);
+}
+AlertIndicator.displayName = "DelacourUI.Alert.Indicator";

package/src/components/alert/alert-title.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useAlertPart } from "./alert.context";
+import { alertVariants } from "./alert.variants";
+
+export type AlertTitleProps = TextPresetProps;
+
+/**
+ * The alert's heading, coloured by its status.
+ *
+ * The colour is the same token the indicator's glyph reads, so the two are
+ * always one shade — a test pins the pair.
+ */
+export function AlertTitle({ className, ...props }: AlertTitleProps): ReactElement {
+	const { status, size } = useAlertPart("Alert.Title");
+	return <Text className={alertVariants({ size, status }).title({ className })} {...props} />;
+}
+AlertTitle.displayName = "DelacourUI.Alert.Title";

package/src/components/alert/alert.context.tsx

@@ -0,0 +1,69 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { AlertSize, AlertStatus, AlertVariant } from "./alert.variants";
+
+export type AlertContextValue = {
+	/** What the alert says about the thing it describes. */
+	status: AlertStatus;
+	/** How the alert's surface is painted. */
+	variant: AlertVariant;
+	/** Size of the alert. */
+	size: AlertSize;
+	/**
+	 * Closes the alert — hides it when uncontrolled, and reports `false` through
+	 * `onOpenChange` either way. Lets an action inside the alert ("Got it")
+	 * dismiss it without the caller threading a setter down.
+	 */
+	dismiss: () => void;
+};
+
+const AlertContext = createContext<AlertContextValue | null>(null);
+
+/**
+ * Supplies the enclosing alert's status, variant, size and `dismiss` to its
+ * subtree.
+ *
+ * Lives in its own module, importing nothing but `alert.variants`, so a part
+ * can read it without importing `./alert`. 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 AlertProvider({ value, children }: { value: AlertContextValue; children: ReactNode }): ReactElement {
+	return <AlertContext value={value}>{children}</AlertContext>;
+}
+AlertProvider.displayName = "DelacourUI.Alert.Provider";
+
+/** The enclosing alert's context, or null outside an `<Alert>`. */
+export function useAlertContext(): AlertContextValue | null {
+	return use(AlertContext);
+}
+
+/**
+ * Reads the enclosing alert's status, variant, size and `dismiss`.
+ *
+ * Lets a custom child match the alert — or close it — without the alert passing
+ * props down. Throws outside an `<Alert>`; use {@link useAlertContext} where the
+ * enclosing alert is optional.
+ */
+export function useAlert(): AlertContextValue {
+	const context = useAlertContext();
+	if (!context) {
+		throw new Error("useAlert must be called inside an <Alert>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing alert'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 useAlert}, whose error message names the hook rather than
+ * a part.
+ */
+export function useAlertPart(component: string): AlertContextValue {
+	const context = useAlertContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside an <Alert>.`);
+	}
+	return context;
+}

package/src/components/alert/alert.tsx

@@ -0,0 +1,160 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import Animated, { FadeOut } from "react-native-reanimated";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { IconDefaultsProvider } from "../icon";
+import { Surface, type SurfaceProps } from "../surface";
+import { type AlertContextValue, AlertProvider } from "./alert.context";
+import {
+	ALERT_FOREGROUND_TOKEN,
+	ALERT_SURFACE_PADDING,
+	type AlertSize,
+	type AlertStatus,
+	type AlertVariant,
+	alertVariants,
+	resolveAlertLiveRegion,
+	resolveAlertSurfaceVariant,
+} from "./alert.variants";
+import { AlertAction } from "./alert-action";
+import { AlertCloseButton } from "./alert-close-button";
+import { AlertContent } from "./alert-content";
+import { AlertDescription } from "./alert-description";
+import { AlertIndicator } from "./alert-indicator";
+import { AlertTitle } from "./alert-title";
+
+/** A dismissed alert fades rather than vanishing, so the layout below it has a beat to follow. */
+const EXITING = FadeOut.duration(150);
+
+export type AlertProps = Omit<SurfaceProps, "variant" | "padding"> & {
+	/** What the alert says: `default`, `info`, `success`, `warning` or `destructive`. Picks the glyph and the colour. */
+	status?: AlertStatus;
+	/** `soft` washes the surface in the status's colour; `surface` keeps the neutral fill and colours only the glyph and title. */
+	variant?: AlertVariant;
+	/** Padding, gap, type scale and glyph size together. */
+	size?: AlertSize;
+	/** Composes a trailing dismiss control in. */
+	isDismissible?: boolean;
+	/** Whether the alert is shown. Pass it to control the alert; omit it and the alert hides itself when dismissed. */
+	isOpen?: boolean;
+	/** Whether an uncontrolled alert starts shown. */
+	defaultOpen?: boolean;
+	/** Called with `false` when the alert is dismissed, controlled or not. */
+	onOpenChange?: (isOpen: boolean) => void;
+	/** Name a screen reader gives the dismiss control. Defaults to `Dismiss`. */
+	closeAccessibilityLabel?: string;
+	/** `testID` for the dismiss control, so a test or automation can press it. */
+	closeTestID?: string;
+	children?: ReactNode;
+};
+
+function AlertRoot({
+	status = "default",
+	variant = "soft",
+	size = "md",
+	isDismissible = false,
+	isOpen,
+	defaultOpen = true,
+	onOpenChange,
+	closeAccessibilityLabel,
+	closeTestID,
+	className,
+	children,
+	...props
+}: AlertProps): ReactElement | null {
+	const [open, setOpen] = useControllableState({ defaultValue: defaultOpen, onChange: onOpenChange, value: isOpen });
+	const dismiss = useCallback(() => setOpen(false), [setOpen]);
+
+	const context = useMemo<AlertContextValue>(
+		() => ({ dismiss, size, status, variant }),
+		[dismiss, size, status, variant]
+	);
+
+	const slots = alertVariants({ size, status, variant });
+
+	// A glyph composed anywhere inside — the indicator's own, a `Spinner`, an
+	// `Icon` in an action — adopts the alert's step and its status's colour.
+	const iconClassName = slots.icon();
+	const iconColor = ALERT_FOREGROUND_TOKEN[status];
+	const iconDefaults = useMemo(() => ({ className: iconClassName, color: iconColor }), [iconClassName, iconColor]);
+
+	if (!open) {
+		return null;
+	}
+
+	return (
+		<AlertProvider value={context}>
+			<Animated.View exiting={EXITING}>
+				<Surface
+					accessibilityLiveRegion={resolveAlertLiveRegion(status)}
+					accessibilityRole="alert"
+					className={slots.root({ className })}
+					padding={ALERT_SURFACE_PADDING[size]}
+					variant={resolveAlertSurfaceVariant({ status, variant })}
+					{...props}
+				>
+					<IconDefaultsProvider value={iconDefaults}>
+						{children}
+						{isDismissible ? (
+							<AlertCloseButton accessibilityLabel={closeAccessibilityLabel} testID={closeTestID} />
+						) : null}
+					</IconDefaultsProvider>
+				</Surface>
+			</Animated.View>
+		</AlertProvider>
+	);
+}
+
+/**
+ * A status message — a glyph, a title, a description and, optionally, an
+ * action — drawn on a `Surface`.
+ *
+ * `status` says what the message means: `default`, `info`, `success`,
+ * `warning` or `destructive`. It picks the indicator's glyph and colours the
+ * glyph and the title from one token; the description stays muted whatever the
+ * status. `variant` says how loudly: `soft` washes the surface in the status's
+ * soft fill, `surface` keeps the neutral fill and lets the glyph and title carry
+ * the colour. A neutral or `surface` alert takes its fill from the surface
+ * ladder, so one inside a card steps off the card instead of vanishing into it.
+ *
+ * `isDismissible` composes a close control in. Uncontrolled, the alert hides
+ * itself when dismissed; pass `isOpen` and `onOpenChange` to own that state.
+ * `useAlert().dismiss` closes it from inside, for a "Got it" action.
+ *
+ * Announced as an `alert`, and as a live region on Android — assertive for a
+ * warning or a failure, polite for anything else.
+ *
+ * @example
+ * <Alert status="warning">
+ *   <Alert.Indicator />
+ *   <Alert.Content>
+ *     <Alert.Title>Card expiring</Alert.Title>
+ *     <Alert.Description>The card ending 4242 expires next month.</Alert.Description>
+ *   </Alert.Content>
+ * </Alert>
+ *
+ * @example
+ * <Alert isDismissible status="destructive">
+ *   <Alert.Indicator />
+ *   <Alert.Content>
+ *     <Alert.Title>Payment failed</Alert.Title>
+ *     <Alert.Description>Your bank declined the charge.</Alert.Description>
+ *     <Alert.Action>
+ *       <Button onPress={retry} size="sm">Try again</Button>
+ *     </Alert.Action>
+ *   </Alert.Content>
+ * </Alert>
+ */
+export const Alert = Object.assign(AlertRoot, {
+	/** The leading status glyph, picked from `status`. Children replace it. */
+	Indicator: AlertIndicator,
+	/** The column holding the title, description and action; takes the remaining width. */
+	Content: AlertContent,
+	/** The heading, coloured by the status. */
+	Title: AlertTitle,
+	/** The body text, always muted. */
+	Description: AlertDescription,
+	/** A wrapping row of buttons under the description. */
+	Action: AlertAction,
+	/** The trailing dismiss control. Composed in automatically whenever `isDismissible` is set. */
+	CloseButton: AlertCloseButton,
+	displayName: "DelacourUI.Alert",
+});

package/src/components/alert/alert.types.ts

@@ -0,0 +1,10 @@
+import type { ViewProps } from "react-native";
+
+/**
+ * The shape of an alert's layout parts.
+ *
+ * Shared by `Alert.Content` and `Alert.Action`, which are both a styled `View`
+ * and nothing else, so it lives in a leaf rather than in one of the two files
+ * arbitrarily.
+ */
+export type AlertSlotProps = ViewProps & { className?: string };

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

@@ -0,0 +1,218 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	ALERT_FOREGROUND_TOKEN,
+	ALERT_SIZES,
+	ALERT_STATUSES,
+	ALERT_SURFACE_PADDING,
+	ALERT_TINTED_STATUSES,
+	ALERT_VARIANTS,
+	alertVariants,
+	resolveAlertLiveRegion,
+	resolveAlertSurfaceVariant,
+	resolveAlertTinted,
+} from "./alert.variants";
+
+/** Every root class string the variant function can produce, one per combination. */
+function everyRoot(): string[] {
+	return ALERT_VARIANTS.flatMap((variant) =>
+		ALERT_STATUSES.flatMap((status) => ALERT_SIZES.map((size) => alertVariants({ size, status, variant }).root()))
+	);
+}
+
+describe("alertVariants root slot", () => {
+	test("lays the indicator, content and close control out in a row, aligned to the top", () => {
+		for (const cls of everyRoot()) {
+			expect(cls).toContain("flex-row");
+			expect(cls).toContain("items-start");
+		}
+	});
+
+	test("tints a soft alert with its status's soft fill", () => {
+		expect(alertVariants({ status: "info", variant: "soft" }).root()).toContain("bg-info-soft");
+		expect(alertVariants({ status: "success", variant: "soft" }).root()).toContain("bg-success-soft");
+		expect(alertVariants({ status: "warning", variant: "soft" }).root()).toContain("bg-warning-soft");
+		expect(alertVariants({ status: "destructive", variant: "soft" }).root()).toContain("bg-destructive-soft");
+	});
+
+	// A tinted fill is its own edge. A grey card hairline around a red wash
+	// reads as two components stacked, not one.
+	test("a tinted alert hides the surface's hairline", () => {
+		for (const status of ALERT_TINTED_STATUSES) {
+			expect(alertVariants({ status, variant: "soft" }).root()).toContain("border-transparent");
+		}
+	});
+
+	// The fill is the Surface's: a neutral alert, or any alert on the surface
+	// variant, names no background of its own, so the ladder decides it.
+	test("paints no fill of its own where the surface ladder decides", () => {
+		for (const status of ALERT_STATUSES) {
+			expect(alertVariants({ status, variant: "surface" }).root()).not.toMatch(/\bbg-/);
+		}
+		expect(alertVariants({ status: "default", variant: "soft" }).root()).not.toMatch(/\bbg-/);
+	});
+
+	test("gives every tinted status a distinct surface", () => {
+		const seen = new Set(ALERT_TINTED_STATUSES.map((status) => alertVariants({ status, variant: "soft" }).root()));
+		expect(seen.size).toBe(ALERT_TINTED_STATUSES.length);
+	});
+
+	test("steps its gap up with size", () => {
+		expect(alertVariants({ size: "sm" }).root()).toContain("gap-2");
+		expect(alertVariants({ size: "md" }).root()).toContain("gap-3");
+		expect(alertVariants({ size: "lg" }).root()).toContain("gap-3.5");
+	});
+
+	// Rule 1: a React Native View does not cascade colour to a Text descendant.
+	test("carries no text colour on the root", () => {
+		for (const cls of everyRoot()) {
+			expect(cls).not.toMatch(/\btext-/);
+		}
+	});
+
+	// Surface owns the padding; a second one here would fight it through the merge.
+	test("sets no padding of its own", () => {
+		for (const cls of everyRoot()) {
+			expect(cls).not.toMatch(/(^|\s)p[xy]?-/);
+		}
+	});
+
+	test("merges an incoming className last", () => {
+		expect(alertVariants().root({ className: "mt-4" })).toContain("mt-4");
+		expect(alertVariants({ status: "info" }).root({ className: "bg-card" })).not.toContain("bg-info-soft");
+	});
+});
+
+describe("alertVariants text slots", () => {
+	test("the title is coloured by the status, from the same token the icon reads", () => {
+		for (const status of ALERT_STATUSES) {
+			expect(alertVariants({ status }).title()).toContain(`text-${ALERT_FOREGROUND_TOKEN[status]}`);
+		}
+	});
+
+	test("the description is always muted", () => {
+		for (const status of ALERT_STATUSES) {
+			expect(alertVariants({ status }).description()).toContain("text-muted-foreground");
+		}
+	});
+
+	test("the title is heavier than the description", () => {
+		expect(alertVariants().title()).toContain("font-semibold");
+		expect(alertVariants().description()).not.toContain("font-semibold");
+	});
+
+	test("steps both text sizes up with the alert", () => {
+		expect(alertVariants({ size: "sm" }).title()).toContain("text-sm");
+		expect(alertVariants({ size: "md" }).title()).toContain("text-base");
+		expect(alertVariants({ size: "lg" }).title()).toContain("text-lg");
+		expect(alertVariants({ size: "sm" }).description()).toContain("text-xs");
+		expect(alertVariants({ size: "md" }).description()).toContain("text-sm");
+		expect(alertVariants({ size: "lg" }).description()).toContain("text-base");
+	});
+
+	// A fixed height clips wrapped text at a large accessibility step.
+	test("no slot carries a fixed height", () => {
+		for (const size of ALERT_SIZES) {
+			const slots = alertVariants({ size });
+			for (const cls of [slots.root(), slots.content(), slots.title(), slots.description(), slots.action()]) {
+				expect(cls).not.toMatch(/(^|\s)h-/);
+			}
+		}
+	});
+});
+
+describe("alertVariants layout slots", () => {
+	// Without flex-1 a long description pushes the close control off the edge.
+	test("the content takes the remaining width", () => {
+		expect(alertVariants().content()).toContain("flex-1");
+	});
+
+	test("the action row wraps rather than overflowing", () => {
+		expect(alertVariants().action()).toContain("flex-row");
+		expect(alertVariants().action()).toContain("flex-wrap");
+	});
+
+	test("the icon indexes the shared icon scale at every size", () => {
+		expect(alertVariants({ size: "sm" }).icon()).toBe("size-icon-sm");
+		expect(alertVariants({ size: "md" }).icon()).toBe("size-icon-md");
+		expect(alertVariants({ size: "lg" }).icon()).toBe("size-icon-lg");
+	});
+
+	// The glyph sits level with the title's first line rather than with the top
+	// of the box, so the indicator carries the line height as its own height.
+	test("the indicator is as tall as the title's first line", () => {
+		expect(alertVariants({ size: "sm" }).indicator()).toContain("h-5");
+		expect(alertVariants({ size: "md" }).indicator()).toContain("h-6");
+		expect(alertVariants({ size: "lg" }).indicator()).toContain("h-7");
+	});
+});
+
+describe("ALERT_FOREGROUND_TOKEN", () => {
+	test("a status names its soft foreground; the neutral alert names the page's", () => {
+		expect(ALERT_FOREGROUND_TOKEN).toEqual({
+			default: "foreground",
+			info: "info-soft-foreground",
+			success: "success-soft-foreground",
+			warning: "warning-soft-foreground",
+			destructive: "destructive-soft-foreground",
+		});
+	});
+
+	// A token no theme declares compiles to nothing and the icon falls back to
+	// whatever colour it inherited.
+	test("every token is declared in both themes and aliased", () => {
+		const css = readFileSync(join(import.meta.dir, "../../styles/theme.css"), "utf8");
+		for (const token of Object.values(ALERT_FOREGROUND_TOKEN)) {
+			expect(css).toContain(`--color-${token}: var(--${token})`);
+			expect(css.split(`--${token}:`).length - 1).toBeGreaterThanOrEqual(2);
+		}
+	});
+});
+
+describe("ALERT_SURFACE_PADDING", () => {
+	test("maps each size onto the surface's own padding step", () => {
+		expect(ALERT_SURFACE_PADDING).toEqual({ sm: "sm", md: "md", lg: "lg" });
+	});
+});
+
+describe("resolveAlertTinted", () => {
+	test("only a soft alert with a status is tinted", () => {
+		for (const status of ALERT_TINTED_STATUSES) {
+			expect(resolveAlertTinted({ status, variant: "soft" })).toBe(true);
+			expect(resolveAlertTinted({ status, variant: "surface" })).toBe(false);
+		}
+		expect(resolveAlertTinted({ status: "default", variant: "soft" })).toBe(false);
+	});
+});
+
+describe("resolveAlertSurfaceVariant", () => {
+	// A tinted alert paints over a card-shaped surface, so what nests in it
+	// steps from `default` like anything else on a card.
+	test("a tinted alert pins the surface to the card", () => {
+		for (const status of ALERT_TINTED_STATUSES) {
+			expect(resolveAlertSurfaceVariant({ status, variant: "soft" })).toBe("default");
+		}
+	});
+
+	// Left undefined, the surface steps from whatever it sits in, so an alert
+	// inside a card never vanishes into the card.
+	test("an untinted alert leaves the fill to the ladder", () => {
+		expect(resolveAlertSurfaceVariant({ status: "default", variant: "soft" })).toBeUndefined();
+		for (const status of ALERT_STATUSES) {
+			expect(resolveAlertSurfaceVariant({ status, variant: "surface" })).toBeUndefined();
+		}
+	});
+});
+
+describe("resolveAlertLiveRegion", () => {
+	// Android announces a live region when its content changes. A failure
+	// interrupts; news waits its turn.
+	test("a warning or a failure interrupts, anything else waits", () => {
+		expect(resolveAlertLiveRegion("destructive")).toBe("assertive");
+		expect(resolveAlertLiveRegion("warning")).toBe("assertive");
+		expect(resolveAlertLiveRegion("default")).toBe("polite");
+		expect(resolveAlertLiveRegion("info")).toBe("polite");
+		expect(resolveAlertLiveRegion("success")).toBe("polite");
+	});
+});