@delacour/react-native-ui 0.1.0-alpha.20260925063807 → 0.1.0-alpha.20260925064136

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925063807",
+	"version": "0.1.0-alpha.20260925064136",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -34,6 +34,7 @@
 		"./styles/tokens": "./src/styles/tokens.css",
 		"./styles/theme": "./src/styles/theme.css",
 		"./accordion": "./src/components/accordion/index.ts",
+		"./alert": "./src/components/alert/index.ts",
 		"./avatar": "./src/components/avatar/index.ts",
 		"./badge": "./src/components/badge/index.ts",
 		"./bottom-sheet": "./src/components/bottom-sheet/index.ts",
@@ -94,7 +95,7 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260925063807",
+		"@delacour/react-native-charts": "0.1.0-alpha.20260925064136",
 		"@gorhom/bottom-sheet": "^5.2.8",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",

package/src/components/alert/AGENTS.md

@@ -0,0 +1,96 @@
+# Alert
+
+A status message on a `Surface`: a glyph picked from its status, a title, a
+description and, optionally, an action row and a dismiss control. Compound root
+plus `Alert.Indicator`, `Alert.Content`, `Alert.Title`, `Alert.Description`,
+`Alert.Action` and `Alert.CloseButton`.
+
+`import { Alert } from "@delacour/react-native-ui/alert";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/alert` |
+| `alert.tsx` | Root + the `Object.assign` compound surface |
+| `alert-indicator.tsx` | `Alert.Indicator`, and the status → glyph map |
+| `alert-content.tsx` | `Alert.Content` |
+| `alert-title.tsx` | `Alert.Title` |
+| `alert-description.tsx` | `Alert.Description` |
+| `alert-action.tsx` | `Alert.Action` |
+| `alert-close-button.tsx` | `Alert.CloseButton`, the dismiss pressable |
+| `alert.context.tsx` | `AlertProvider`, `useAlert()`, `useAlertContext()`, `useAlertPart()` |
+| `alert.types.ts` | `AlertSlotProps`, shared by `Content` and `Action` |
+| `alert.variants.ts` | The slotted `tv()`, `ALERT_FOREGROUND_TOKEN`, `ALERT_SURFACE_PADDING` and three pure resolvers — no RN imports |
+| `alert.variants.test.ts` | |
+
+## Design
+
+- **Two axes: `status` and `variant`.** `status` says what the message means —
+  `default`, `info`, `success`, `warning`, `destructive` — and `variant` says
+  how loudly: `soft` (the default) washes the surface in the status's `-soft`
+  fill, `surface` keeps a neutral fill and lets the glyph and title carry the
+  colour. **Sizes**: `sm`, `md`, `lg`, which move padding, gap, type and glyph
+  together. `destructive` rather than `danger`, per the package's token rule.
+- **It is built on `Surface`, and it adds only what a surface lacks.** The
+  corner, the continuous curve, the padding (`ALERT_SURFACE_PADDING` maps each
+  size onto the surface's own step) and the neutral fill all come from
+  [Surface](../surface/AGENTS.md). `alertVariants`' root carries the row and the
+  tint, and a test asserts it sets no padding of its own — a second one would
+  fight the surface's through the merge.
+- **Only a tinted alert names a fill.** `resolveAlertTinted` is true for `soft`
+  plus a status, and those four cells swap `bg-card` for `bg-X-soft` and clear
+  the card's hairline: a grey rule around a red wash reads as two components
+  stacked. Every other alert leaves the surface's `variant` undefined
+  (`resolveAlertSurfaceVariant`), so it steps from the plane it sits on — an
+  alert inside a card lands on `secondary` rather than vanishing into the card.
+  A tinted alert pins the surface to `default` instead, so what nests in it
+  steps from a card like anything else.
+- **One colour token per status, not per status and variant.**
+  `ALERT_FOREGROUND_TOKEN` names `X-soft-foreground` for each status and the
+  page's `foreground` for `default`; those are tuned to read on the soft fill
+  and on the neutral fills alike. The title slot emits the same token as a
+  class and the root publishes it through `IconDefaultsProvider`, so the glyph
+  and the title are always one shade. A test pins the pair and asserts every
+  token exists in both themes. The classes are written out literally —
+  Tailwind's scanner is static, so a class assembled from the map at runtime
+  would never be compiled.
+- **The description is always muted.** A long explanation under a red title
+  must not shout; the title carries the status.
+- **`items-start`, and the indicator is as tall as the title's line.** A
+  description that wraps to four lines must not drag the glyph to its middle.
+  The indicator's height is the title's line height at each size (`h-5`/`h-6`/
+  `h-7` against `text-sm`/`base`/`lg`), and it centres the glyph in that box, so
+  the glyph sits level with the first line. Nothing else is a fixed height:
+  `Text` respects OS font scaling, and a fixed box would clip a wrapped title.
+- **Glyphs differ in shape, not just colour.** `warning` is a triangle and
+  `destructive` a circle, so the two stay apart for anyone who cannot tell amber
+  from red. `default` shares `info`'s circle. The map lives in
+  `alert-indicator.tsx` because the glyphs are RN SVG components and
+  `alert.variants.ts` must stay importable from `bun test`.
+- **The indicator is hidden from assistive technology.** The title says what
+  happened; "image" announced before it adds nothing. Children replace the
+  glyph and inherit the alert's icon size and colour — a `Spinner` for a
+  pending state needs nothing else.
+- **Announced as an `alert`, and as a live region on Android.**
+  `resolveAlertLiveRegion` makes a `warning` or `destructive` alert assertive
+  and anything else polite. The root is not made `accessible`: grouping it
+  would swallow the close control and any action into one element.
+- **Dismissal is controllable.** `isDismissible` composes an
+  `Alert.CloseButton` in at the end. Uncontrolled, the alert hides itself when
+  dismissed (`defaultOpen`); pass `isOpen` with `onOpenChange` to own it.
+  `useAlert().dismiss` is on the context so an action ("Got it") can close the
+  alert without the caller threading a setter down. A dismissed alert fades out
+  over 150 ms rather than vanishing — the one `Animated.View` wrapper exists for
+  that `exiting`, and a caller's `className` still reaches the surface.
+- **The close glyph is muted, not the status colour.** The control is about the
+  alert rather than part of what it says, and a red cross beside a red title
+  reads as a second warning. It presses with `fade` — a spring on a glyph that
+  small is a jitter — and carries `hitSlop={10}` to reach the 44-point target.
+- **Actions are the caller's.** `Alert.Action` is a wrapping row and styles
+  nothing in it; a `Button` in there is sized and painted however the caller
+  says. It wraps rather than overflowing, because two buttons and a long label
+  outgrow a phone's width.
+- **Parts are composed, not configured.** There is no `title` or `icon` prop:
+  omit `Alert.Indicator` for a text-only alert, omit `Alert.Description` for a
+  one-liner. The same reason `Button` and `Badge` compose their icons.

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

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { AlertSlotProps } from "./alert.types";
+import { alertVariants } from "./alert.variants";
+
+/**
+ * A wrapping row for the alert's buttons, placed under the description inside
+ * `Alert.Content`.
+ *
+ * Takes any children — a `Button`, a `Text.Link` — and styles none of them: an
+ * action is the caller's control, sized and painted the way they want it. Read
+ * `useAlert().dismiss` from inside to close the alert from an action.
+ */
+export function AlertAction({ className, ...props }: AlertSlotProps): ReactElement {
+	return <View className={alertVariants().action({ className })} {...props} />;
+}
+AlertAction.displayName = "DelacourUI.Alert.Action";

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-indicator.tsx

@@ -0,0 +1,59 @@
+import type { ReactElement, ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import { IconCircleCheck, IconCircleInfo, IconExclamationCircle, IconExclamationTriangle } from "../../icons/central";
+import { Icon, type IconComponent } from "../icon";
+import { useAlertPart } from "./alert.context";
+import { type AlertStatus, alertVariants } 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.
+ *
+ * Lives here rather than in `alert.variants.ts` because the glyphs are React
+ * Native SVG components, and that file must stay importable from `bun test`.
+ */
+const ALERT_GLYPHS: Record<AlertStatus, IconComponent> = {
+	default: IconCircleInfo,
+	info: IconCircleInfo,
+	success: IconCircleCheck,
+	warning: IconExclamationTriangle,
+	destructive: IconExclamationCircle,
+};
+
+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,155 @@
+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;
+	children?: ReactNode;
+};
+
+function AlertRoot({
+	status = "default",
+	variant = "soft",
+	size = "md",
+	isDismissible = false,
+	isOpen,
+	defaultOpen = true,
+	onOpenChange,
+	closeAccessibilityLabel,
+	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} /> : 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");
+	});
+});

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";