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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925063807",
+	"version": "0.1.0-alpha.20260925064429",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -34,10 +34,12 @@
 		"./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",
 		"./button": "./src/components/button/index.ts",
+		"./card": "./src/components/card/index.ts",
 		"./chart": "./src/components/chart/index.ts",
 		"./checkbox": "./src/components/checkbox/index.ts",
 		"./chip": "./src/components/chip/index.ts",
@@ -94,7 +96,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.20260925064429",
 		"@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 };