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

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

@@ -0,0 +1,106 @@
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import Animated, { ZoomIn } from "react-native-reanimated";
+import { IconCheckmark1Small, IconCrossSmall } from "../../icons/central";
+import { Icon, IconDefaultsProvider } from "../icon";
+import { Spinner } from "../spinner";
+import { Text } from "../text";
+import { type StepsItemContextValue, useStepsItemPart } from "./steps.context";
+import { resolveIndicatorForeground, resolveIndicatorGlyph, stepsVariants } from "./steps.variants";
+
+export type StepsIndicatorChildrenProps = Pick<
+	StepsItemContextValue,
+	"step" | "status" | "isCurrent" | "isInvalid" | "isLoading" | "size" | "variant"
+>;
+
+export type StepsIndicatorProps = Omit<ViewProps, "children"> & {
+	className?: string;
+	/**
+	 * Replaces what the circle draws. The circle, its size and its colours are
+	 * still the step's, and an `Icon` inside inherits the glyph size and colour.
+	 */
+	children?: ReactNode | ((props: StepsIndicatorChildrenProps) => ReactNode);
+};
+
+/**
+ * The glyph's entrance. Short and un-sprung: a check lands, it does not bounce.
+ * Reduce motion is Reanimated's default `System`, which snaps it in — the state
+ * is carried by the glyph's presence, not by its motion.
+ */
+const GLYPH_ENTERING = ZoomIn.duration(180);
+
+/**
+ * The circle: a spinner while loading, a cross while invalid, a check once
+ * completed, and otherwise the step's one-based number.
+ *
+ * Composed in automatically, so write it out only to restyle it or to draw
+ * something of your own inside the circle — an icon per step, say. Wherever it
+ * is written among a step's children, the step lifts it into the track between
+ * the connector halves; it never lands in the text column.
+ *
+ * **The circle is hidden from assistive technology.** The trigger merges its
+ * children into one element, and the numeral would otherwise lead the name —
+ * "2, Shipping" — restating the position the accessibility value already reads.
+ *
+ * **The number does not scale with the OS text size.** The circle is a fixed
+ * edge, so a scaled numeral would spill out of it, and the position it shows is
+ * already announced in the step's accessibility value — scaling would buy the
+ * reader nothing the screen reader has not said.
+ *
+ * The check and cross are Central Icons and the spinner is `Spinner`; all three
+ * take their size and colour from one `IconDefaultsProvider`, whose token
+ * {@link resolveIndicatorForeground} keeps equal to the number's class.
+ */
+export function StepsIndicator({ className, children, ...props }: StepsIndicatorProps): ReactElement {
+	const item = useStepsItemPart("Steps.Indicator");
+	const { step, status, isCurrent, isInvalid, isLoading, isDisabled, size, variant } = item;
+
+	const slots = stepsVariants({ isDisabled, isInvalid, size, status, variant });
+	const glyphClass = slots.glyph();
+	const labelClass = slots.indicatorLabel();
+	const color = resolveIndicatorForeground({ isInvalid, status, variant });
+	const iconDefaults = useMemo(() => ({ className: glyphClass ?? "", color }), [glyphClass, color]);
+
+	const renderGlyph = (): ReactNode => {
+		if (typeof children === "function") {
+			return children({ isCurrent, isInvalid, isLoading, size, status, step, variant });
+		}
+		if (children) return children;
+
+		const glyph = resolveIndicatorGlyph({ isInvalid, isLoading, status, step });
+		switch (glyph.kind) {
+			case "spinner":
+				return <Spinner />;
+			case "alert":
+				return (
+					<Animated.View entering={GLYPH_ENTERING} key="alert">
+						<Icon icon={IconCrossSmall} />
+					</Animated.View>
+				);
+			case "check":
+				return (
+					<Animated.View entering={GLYPH_ENTERING} key="check">
+						<Icon icon={IconCheckmark1Small} />
+					</Animated.View>
+				);
+			case "number":
+				return (
+					<Text allowFontScaling={false} className={labelClass}>
+						{glyph.label}
+					</Text>
+				);
+		}
+	};
+
+	return (
+		<View
+			accessibilityElementsHidden
+			className={slots.indicator({ className })}
+			importantForAccessibility="no-hide-descendants"
+			{...props}
+		>
+			<IconDefaultsProvider value={iconDefaults}>{renderGlyph()}</IconDefaultsProvider>
+		</View>
+	);
+}
+StepsIndicator.displayName = "DelacourUI.Steps.Indicator";

package/src/components/steps/steps-item.tsx

@@ -0,0 +1,225 @@
+import { Children, isValidElement, type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import { View } from "react-native";
+import { Pressable, type PressableProps } from "../pressable";
+import { type StepsItemContextValue, StepsItemProvider, useStepsPart } from "./steps.context";
+import {
+	resolveStepAccessibilityValue,
+	resolveStepInteraction,
+	resolveStepStatus,
+	stepsVariants,
+} from "./steps.variants";
+import { StepsIndicator } from "./steps-indicator";
+import { StepsPanel } from "./steps-panel";
+import { StepsTitle } from "./steps-title";
+import { StepsRail, StepsTrack } from "./steps-track";
+
+export type StepsItemProps = Omit<PressableProps, "asChild" | "busy" | "children" | "disabled" | "ref"> & {
+	/** This step's index, zero-based. The indicator draws it one-based. */
+	step: number;
+	/**
+	 * Overrides whether the step reads as done. `true` completes it wherever it
+	 * sits — a finished flow's last step. `false` leaves a passed step looking
+	 * unfinished — a skipped optional one. Never demotes the current step.
+	 */
+	completed?: boolean;
+	/** The step cannot be pressed, and fades. A stepper that names `isDisabled` wins over this. */
+	isDisabled?: boolean;
+	/** The step has an error: a cross in the indicator and a destructive title. */
+	isInvalid?: boolean;
+	/** A spinner in the indicator. The step is announced busy and cannot be pressed. */
+	isLoading?: boolean;
+	children?: ReactNode;
+};
+
+/**
+ * One step: its indicator, the connector halves either side of it, its title and
+ * description, and any `Steps.Panel`.
+ *
+ * The trigger is the control — the circle, the title and the space between them
+ * are one tap target and one accessibility element, whose name is the title and
+ * whose value is "Step 2 of 3, completed". It renders a `Pressable` when the
+ * stepper takes presses and a plain `View` when it is read-only, so a progress
+ * display is never announced as a row of buttons. A panel renders after the
+ * trigger, outside both.
+ *
+ * `className` styles the step's outer box; every other prop — `testID`,
+ * `onPress`, `haptic`, the accessibility props — reaches the trigger.
+ *
+ * Bare text is wrapped in a `Steps.Title`, and a `Steps.Indicator` is composed
+ * in when the children hold none — the shortest step that works is
+ * `<Steps.Item step={0}>Account</Steps.Item>`.
+ */
+export function StepsItem({
+	step,
+	completed,
+	isDisabled,
+	isInvalid = false,
+	isLoading = false,
+	feedback = "fade",
+	haptic,
+	onLongPress,
+	pressedOpacity,
+	pressedScale,
+	accessibilityState,
+	className,
+	children,
+	onPress,
+	...props
+}: StepsItemProps): ReactElement {
+	const root = useStepsPart("Steps.Item");
+	const { value, count, orientation, size, variant, select } = root;
+
+	const status = resolveStepStatus({ completed, step, value });
+	const isCurrent = step === value;
+	const resolvedIsDisabled = root.isDisabled ?? isDisabled ?? false;
+	const isLast = step >= count - 1;
+
+	if (process.env.NODE_ENV !== "production" && count > 0 && (step < 0 || step >= count)) {
+		console.warn(`Steps.Item: step ${step} is outside the ${count} steps the root counted. Steps are zero-based.`);
+	}
+
+	const interaction = resolveStepInteraction({
+		isDisabled: resolvedIsDisabled,
+		isLinear: root.isLinear,
+		isLoading,
+		isReadOnly: root.isReadOnly,
+		step,
+		value,
+	});
+
+	const context = useMemo<StepsItemContextValue>(
+		() => ({
+			isCurrent,
+			isDisabled: resolvedIsDisabled,
+			isInvalid,
+			isLast,
+			isLoading,
+			orientation,
+			size,
+			status,
+			step,
+			variant,
+		}),
+		[isCurrent, resolvedIsDisabled, isInvalid, isLast, isLoading, orientation, size, status, step, variant]
+	);
+
+	const handlePress = useCallback(() => {
+		select(step);
+		onPress?.();
+	}, [onPress, select, step]);
+
+	const { indicator, content, panels } = useMemo(() => splitChildren(children), [children]);
+	const hasPanel = panels.length > 0;
+	const slots = stepsVariants({ hasPanel, isDisabled: resolvedIsDisabled, isLast, orientation, size });
+
+	const trigger = (
+		<>
+			<StepsTrack indicator={indicator} />
+			{content.length > 0 ? <View className={slots.content()}>{content}</View> : null}
+		</>
+	);
+
+	// A vertical panel sits beside a rail that carries the line on past it; a
+	// horizontal one simply follows the trigger.
+	const panelRow =
+		hasPanel && orientation === "vertical" ? (
+			<View className={slots.panelRow()}>
+				<StepsRail />
+				{panels}
+			</View>
+		) : (
+			panels
+		);
+
+	const accessibilityValue = {
+		text: resolveStepAccessibilityValue({ count, isInvalid, isLoading, status, step }),
+	};
+	const state = { ...accessibilityState, selected: isCurrent };
+
+	return (
+		<StepsItemProvider value={context}>
+			<View className={slots.item({ className })}>
+				{interaction === "static" ? (
+					<View
+						accessibilityState={state}
+						accessibilityValue={accessibilityValue}
+						accessible
+						className={slots.trigger()}
+						{...props}
+					>
+						{trigger}
+					</View>
+				) : (
+					<Pressable
+						accessibilityState={state}
+						accessibilityValue={accessibilityValue}
+						busy={isLoading}
+						className={slots.trigger()}
+						disabled={interaction === "blocked" && !isLoading}
+						feedback={feedback}
+						haptic={haptic}
+						onLongPress={onLongPress}
+						onPress={handlePress}
+						pressedOpacity={pressedOpacity}
+						pressedScale={pressedScale}
+						{...props}
+					>
+						{trigger}
+					</Pressable>
+				)}
+				{panelRow}
+			</View>
+		</StepsItemProvider>
+	);
+}
+StepsItem.displayName = "DelacourUI.Steps.Item";
+
+/**
+ * Lifts a `Steps.Indicator` and any `Steps.Panel` out of a step's children, and
+ * wraps bare text in a `Steps.Title`.
+ *
+ * Both places are structural — the indicator between the connector halves, a
+ * panel after the trigger — so each is pulled out wherever it was written rather
+ * than rendered in the text column.
+ * Consecutive strings and numbers collapse into one title, as `Radio` does, so
+ * `Step {n}` is one piece of text rather than two spaced apart.
+ *
+ * Lives here rather than in the root: it is the item that wraps its own
+ * children, and a helper in the root file would close a cycle. See AGENTS.md.
+ */
+function splitChildren(children: ReactNode): {
+	indicator: ReactNode | null;
+	content: ReactNode[];
+	panels: ReactNode[];
+} {
+	let indicator: ReactNode | null = null;
+	const content: ReactNode[] = [];
+	const panels: ReactNode[] = [];
+	let run: (string | number)[] = [];
+
+	const flushRun = () => {
+		if (run.length === 0) return;
+		content.push(<StepsTitle key={`title-${content.length}`}>{run.join("")}</StepsTitle>);
+		run = [];
+	};
+
+	for (const child of Children.toArray(children)) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(child);
+			continue;
+		}
+		flushRun();
+		if (indicator === null && isValidElement(child) && child.type === StepsIndicator) {
+			indicator = child;
+			continue;
+		}
+		if (isValidElement(child) && child.type === StepsPanel) {
+			panels.push(child);
+			continue;
+		}
+		content.push(child);
+	}
+	flushRun();
+
+	return { content, indicator, panels };
+}

package/src/components/steps/steps-panel.tsx

@@ -0,0 +1,41 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { useStepsItemPart } from "./steps.context";
+import { stepsVariants } from "./steps.variants";
+
+export type StepsPanelProps = ViewProps & { className?: string };
+
+/**
+ * Content for a step that sits below its title but outside its tap target — a
+ * form for the current step, a summary of a finished one.
+ *
+ * **It exists because the trigger is one accessibility element.** The trigger
+ * merges its indicator, title and description into a single stop, so a text
+ * field or a button inside it would be unreachable by VoiceOver, and its own
+ * tap gesture would sit inside the step's. The panel renders beside the
+ * trigger instead: every control in it is its own element, and a press on it
+ * never moves the stepper.
+ *
+ * Wherever it is written among a step's children, the step lifts it out and
+ * renders it after the trigger. In a vertical stepper the line carries on down
+ * a rail beside it, so the panel reads as part of its step. Show it
+ * conditionally — `{value === 1 ? <Steps.Panel>…</Steps.Panel> : null}` — there
+ * is no built-in "only while current", because a finished step's summary is as
+ * common a panel as the current step's form.
+ */
+export function StepsPanel({ className, ...props }: StepsPanelProps): ReactElement {
+	const item = useStepsItemPart("Steps.Panel");
+
+	return (
+		<View
+			className={stepsVariants({
+				hasPanel: true,
+				isLast: item.isLast,
+				orientation: item.orientation,
+				size: item.size,
+			}).panel({ className })}
+			{...props}
+		/>
+	);
+}
+StepsPanel.displayName = "DelacourUI.Steps.Panel";

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

@@ -0,0 +1,32 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useStepsItemPart } from "./steps.context";
+import { STEPS_TITLE_TEXT_SIZE, stepsVariants } from "./steps.variants";
+
+export type StepsTitleProps = TextPresetProps;
+
+/**
+ * The step's name — and, because the step is one accessibility element, its
+ * accessible name too.
+ *
+ * Renders `Text.Label` at the step's own size step rather than a scale of its
+ * own, the rule `Radio.Label` follows. Its colour follows the step: muted ahead
+ * of the value, destructive while invalid. Bare text inside a `Steps.Item` is
+ * wrapped in one automatically.
+ */
+export function StepsTitle({ className, size, ...props }: StepsTitleProps): ReactElement {
+	const item = useStepsItemPart("Steps.Title");
+
+	return (
+		<Text.Label
+			className={stepsVariants({
+				isInvalid: item.isInvalid,
+				orientation: item.orientation,
+				status: item.status,
+			}).title({ className })}
+			size={size ?? STEPS_TITLE_TEXT_SIZE[item.size]}
+			{...props}
+		/>
+	);
+}
+StepsTitle.displayName = "DelacourUI.Steps.Title";

package/src/components/steps/steps-track.tsx

@@ -0,0 +1,59 @@
+import type { ReactElement, ReactNode } from "react";
+import { View } from "react-native";
+import { useStepsItemPart, useStepsPart } from "./steps.context";
+import { isConnectorComplete, resolveStepConnectors, stepsVariants } from "./steps.variants";
+import { StepsConnector } from "./steps-connector";
+import { StepsIndicator } from "./steps-indicator";
+
+/**
+ * A step's track: `[leading] [indicator] [trailing]`. Internal.
+ *
+ * The leading half joins the previous step, so it fills off that step's index
+ * rather than this one's — the two halves of one line must agree, and the value
+ * is the only thing both can see. See `isConnectorComplete`.
+ */
+export function StepsTrack({ indicator }: { indicator: ReactNode | null }): ReactElement {
+	const { value, count } = useStepsPart("Steps.Item");
+	const { step, orientation, size, isLast } = useStepsItemPart("Steps.Item");
+	const connectors = resolveStepConnectors({ count, orientation, step });
+
+	return (
+		<View className={stepsVariants({ isLast, orientation, size }).track()}>
+			{connectors.leading === "none" ? null : (
+				<StepsConnector
+					isComplete={isConnectorComplete(step - 1, value)}
+					orientation={orientation}
+					slot={connectors.leading}
+				/>
+			)}
+			{indicator ?? <StepsIndicator />}
+			{connectors.trailing === "none" ? null : (
+				<StepsConnector
+					isComplete={isConnectorComplete(step, value)}
+					orientation={orientation}
+					slot={connectors.trailing}
+				/>
+			)}
+		</View>
+	);
+}
+StepsTrack.displayName = "DelacourUI.Steps.Item.Track";
+
+/**
+ * The column beside a vertical `Steps.Panel`, as wide as the indicator, that
+ * carries the trailing line on past the panel. Internal.
+ */
+export function StepsRail(): ReactElement {
+	const { value, count } = useStepsPart("Steps.Item");
+	const { step, orientation, size, isLast } = useStepsItemPart("Steps.Item");
+	const { trailing } = resolveStepConnectors({ count, orientation, step });
+
+	return (
+		<View className={stepsVariants({ hasPanel: true, isLast, orientation, size }).rail()}>
+			{trailing === "line" ? (
+				<StepsConnector isComplete={isConnectorComplete(step, value)} orientation={orientation} slot="line" />
+			) : null}
+		</View>
+	);
+}
+StepsRail.displayName = "DelacourUI.Steps.Item.Rail";

package/src/components/steps/steps.context.tsx

@@ -0,0 +1,123 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { StepStatus, StepsOrientation, StepsSize, StepsVariant } from "./steps.variants";
+
+export type StepsContextValue = {
+	/** The current step, zero-based. */
+	value: number;
+	/** How many `Steps.Item`s the root found among its direct children. `0` when it could not count them. */
+	count: number;
+	/** What a step calls on press. Stays quiet when the step is already current. */
+	select: (step: number) => void;
+	orientation: StepsOrientation;
+	size: StepsSize;
+	variant: StepsVariant;
+	/** Steps render as plain views and take no presses. */
+	isReadOnly: boolean;
+	/** Steps ahead of the value cannot be pressed. */
+	isLinear: boolean;
+	/** Raw rather than resolved, so one step can still disable itself — see `RadioGroupContextValue`. */
+	isDisabled?: boolean;
+};
+
+export type StepsItemContextValue = {
+	/** This step's index, zero-based. */
+	step: number;
+	status: StepStatus;
+	/** Whether this step is the value — true even when `completed` paints it done. */
+	isCurrent: boolean;
+	isInvalid: boolean;
+	isLoading: boolean;
+	isDisabled: boolean;
+	isLast: boolean;
+	orientation: StepsOrientation;
+	size: StepsSize;
+	variant: StepsVariant;
+};
+
+const StepsContext = createContext<StepsContextValue | null>(null);
+const StepsItemContext = createContext<StepsItemContextValue | null>(null);
+
+/**
+ * Supplies the stepper's value and axes to its steps.
+ *
+ * Lives in its own module, importing nothing but React and types, so a part can
+ * read it without importing `./steps` — which would close a cycle and leave the
+ * context `undefined` on a cold start. See AGENTS.md rule 3.
+ */
+export function StepsProvider({ value, children }: { value: StepsContextValue; children: ReactNode }): ReactElement {
+	return <StepsContext value={value}>{children}</StepsContext>;
+}
+StepsProvider.displayName = "DelacourUI.Steps.Provider";
+
+/** Supplies one step's settled state to its indicator, title and description. */
+export function StepsItemProvider({
+	value,
+	children,
+}: {
+	value: StepsItemContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <StepsItemContext value={value}>{children}</StepsItemContext>;
+}
+StepsItemProvider.displayName = "DelacourUI.Steps.Item.Provider";
+
+/** The enclosing stepper's context, or null outside a `<Steps>`. */
+export function useStepsContext(): StepsContextValue | null {
+	return use(StepsContext);
+}
+
+/**
+ * Reads the enclosing stepper's value and axes.
+ *
+ * For a custom control — a Continue button, a progress caption — that has to
+ * follow the stepper it sits beside. Throws outside one.
+ */
+export function useSteps(): StepsContextValue {
+	const context = useStepsContext();
+	if (!context) {
+		throw new Error("useSteps must be called inside a <Steps>.");
+	}
+	return context;
+}
+
+/** The enclosing step's settled state, or null outside a `<Steps.Item>`. */
+export function useStepsItemContext(): StepsItemContextValue | null {
+	return use(StepsItemContext);
+}
+
+/**
+ * Reads the enclosing step's settled state.
+ *
+ * Lets a custom child — an indicator of your own, a status badge — style itself
+ * to match. Throws outside a `<Steps.Item>`.
+ */
+export function useStepsItem(): StepsItemContextValue {
+	const context = useStepsItemContext();
+	if (!context) {
+		throw new Error("useStepsItem must be called inside a <Steps.Item>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing stepper, for a part that cannot work without one.
+ *
+ * Internal: not re-exported from `index.ts`. A caller wants {@link useSteps},
+ * whose error names the hook rather than a part.
+ */
+export function useStepsPart(component: string): StepsContextValue {
+	const context = useStepsContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Steps>.`);
+	}
+	return context;
+}
+
+/** The enclosing step, for a part that cannot work without one. Internal. */
+export function useStepsItemPart(component: string): StepsItemContextValue {
+	const context = useStepsItemContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Steps.Item>.`);
+	}
+	return context;
+}