@delacour/react-native-ui 0.1.0-alpha.20260925053522

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

@@ -0,0 +1,29 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import { useFieldContext } from "./field.context";
+import type { FieldTextProps } from "./field.types";
+import { fieldVariants, resolveFieldTextColor } from "./field.variants";
+
+/**
+ * Supporting copy for the control — what the value is for, or what shape it
+ * takes.
+ *
+ * Stays on the muted token whether the field is valid or not, so an appearing
+ * `Field.Error` is the one line that changed. It does not fade with a disabled
+ * field either: the control already dims itself, and a dimmed explanation on top
+ * of a dimmed control reads as two problems rather than one state.
+ */
+export function FieldDescription({ className, color, ...props }: FieldTextProps): ReactElement {
+	const field = useFieldContext();
+	const isInvalid = field?.isInvalid ?? false;
+	const isDisabled = field?.isDisabled ?? false;
+
+	return (
+		<Text.Caption
+			className={fieldVariants({ isDisabled, isInvalid }).description({ className })}
+			color={color ?? resolveFieldTextColor("description", isInvalid)}
+			{...props}
+		/>
+	);
+}
+FieldDescription.displayName = "DelacourUI.Field.Description";

package/src/components/field/field-error.tsx

@@ -0,0 +1,61 @@
+import { Children, type ReactElement, type ReactNode } from "react";
+import { Text } from "../text";
+import { useFieldContext } from "./field.context";
+import type { FieldTextProps } from "./field.types";
+import { fieldVariants, resolveFieldTextColor } from "./field.variants";
+
+/**
+ * `Text` renders `Animated.Text`, so its `children` may also be a Reanimated
+ * `SharedValue<ReactNode>`. An error message is a string, and this part has to
+ * count its children to know whether to render at all, so the narrower type is
+ * both the honest one and the one that can be counted.
+ */
+export type FieldErrorProps = Omit<FieldTextProps, "children"> & { children?: ReactNode };
+
+/**
+ * What is wrong with the value.
+ *
+ * Renders nothing when it has no children, so
+ * `<Field.Error>{errors.email}</Field.Error>` disappears on its own once the
+ * value is fixed and needs no conditional at the call site.
+ *
+ * Deliberately **not** gated on the field's `isInvalid`. A part that swallowed
+ * the children a caller actually wrote, because of a prop on a sibling, would be
+ * a part whose absence is unexplainable from the call site — and pairing the two
+ * is the caller's own `isInvalid={!!error}`, which is one expression, in view.
+ *
+ * Always destructive, in a valid field as much as an invalid one: an error message is
+ * never the calm case.
+ */
+export function FieldError({ className, color, children, ...props }: FieldErrorProps): ReactElement | null {
+	const field = useFieldContext();
+	const isInvalid = field?.isInvalid ?? false;
+	const isDisabled = field?.isDisabled ?? false;
+
+	if (!hasContent(children)) return null;
+
+	return (
+		<Text.Caption
+			accessibilityLiveRegion="polite"
+			className={fieldVariants({ isDisabled, isInvalid }).error({ className })}
+			color={color ?? resolveFieldTextColor("error", isInvalid)}
+			role="alert"
+			{...props}
+		>
+			{children}
+		</Text.Caption>
+	);
+}
+FieldError.displayName = "DelacourUI.Field.Error";
+
+/**
+ * Whether there is anything worth drawing a line of destructive text for.
+ *
+ * `Children.toArray` drops the `null`, `undefined` and booleans a conditional
+ * child leaves behind, so `{error && <Text>{error}</Text>}` counts as empty
+ * rather than as one child. An empty string is dropped too — it is what a
+ * cleared validation message usually is.
+ */
+function hasContent(children: ReactNode): boolean {
+	return Children.toArray(children).some((child) => child !== "");
+}

package/src/components/field/field-group.tsx

@@ -0,0 +1,22 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { fieldVariants } from "./field.variants";
+
+export type FieldGroupProps = ViewProps & { className?: string };
+
+/**
+ * A stack of fields, spaced so that two fields never read as one.
+ *
+ * Its gap is the loosest step in the ladder — looser than the gap inside a
+ * field — which is the whole mechanism by which a label attaches to the control
+ * under it rather than to the one above.
+ *
+ * **Inserts no dividers**, unlike `ListGroup`. A list of rows without lines is a
+ * wall of text, but fields are already separated by whitespace and a rule
+ * between every one of them is noise. Place a `Field.Separator` where a form
+ * genuinely changes subject.
+ */
+export function FieldGroup({ className, ...props }: FieldGroupProps): ReactElement {
+	return <View className={fieldVariants().group({ className })} {...props} />;
+}
+FieldGroup.displayName = "DelacourUI.Field.Group";

package/src/components/field/field-label.tsx

@@ -0,0 +1,47 @@
+import { type ReactElement, useEffect } from "react";
+import { Text } from "../text";
+import { useFieldContext } from "./field.context";
+import type { FieldTextProps } from "./field.types";
+import { fieldVariants, resolveFieldLabelText, resolveFieldTextColor } from "./field.variants";
+
+/**
+ * The name of the control this field holds.
+ *
+ * Renders `Text.Label` and passes it a colour, never a size or a weight — the
+ * type scale belongs to the preset, and restating it here would be a second
+ * definition of `Text.Label` that could drift from it. It turns destructive with the
+ * control when the field is invalid, so the pair reads as one state.
+ *
+ * There is no `htmlFor`. React Native has no `<label>` element and no
+ * label-for-control association, which is also why there is no `Field.Title`:
+ * on the web that part exists only because a `<div>` is not a `<label>`, and
+ * here both would be the same `Text`. **The association is made by hand
+ * instead**: a string label hands its text to the field's context, and a control
+ * inside with no text of its own — a `Slider.Thumb` — reads it as its accessible
+ * name. `resolveFieldLabelText` decides what qualifies.
+ */
+export function FieldLabel({ className, color, children, ...props }: FieldTextProps): ReactElement {
+	const field = useFieldContext();
+	const isInvalid = field?.isInvalid ?? false;
+	const isDisabled = field?.isDisabled ?? false;
+
+	const registerLabel = field?.registerLabel;
+	const labelText = resolveFieldLabelText(children);
+
+	useEffect(() => {
+		if (!registerLabel) return;
+		registerLabel(labelText);
+		return () => registerLabel(null);
+	}, [labelText, registerLabel]);
+
+	return (
+		<Text.Label
+			className={fieldVariants({ isDisabled, isInvalid }).label({ className })}
+			color={color ?? resolveFieldTextColor("label", isInvalid)}
+			{...props}
+		>
+			{children}
+		</Text.Label>
+	);
+}
+FieldLabel.displayName = "DelacourUI.Field.Label";

package/src/components/field/field-legend.tsx

@@ -0,0 +1,34 @@
+import type { ReactElement } from "react";
+import { Text } from "../text";
+import type { FieldTextProps } from "./field.types";
+import { type FieldLegendVariant, fieldVariants } from "./field.variants";
+
+export type FieldLegendProps = FieldTextProps & {
+	/** `legend` titles a set; `label` matches the fields under it. */
+	variant?: FieldLegendVariant;
+};
+
+/**
+ * The title of a `Field.Set`.
+ *
+ * Two sizes, chosen by picking a `Text` preset rather than by naming a scale:
+ * `legend` renders `Text.Paragraph` with a medium weight — a heading for a
+ * section of a form — and `label` renders `Text.Label`, which is the treatment
+ * the fields below it already use. Reach for `label` when the set is nested
+ * inside another, where a second full-size heading would compete with the first.
+ *
+ * Reads no context: a legend titles a set, and a set holds no state of its own —
+ * invalid and disabled belong to each `Field` inside it. That is also why it
+ * takes no `isInvalid`; a whole section turning destructive says less than the one
+ * field that is wrong.
+ */
+export function FieldLegend({ className, variant = "legend", ...props }: FieldLegendProps): ReactElement {
+	const legendClassName = fieldVariants({ variant }).legend({ className });
+
+	if (variant === "label") {
+		return <Text.Label className={legendClassName} {...props} />;
+	}
+
+	return <Text.Paragraph className={legendClassName} {...props} />;
+}
+FieldLegend.displayName = "DelacourUI.Field.Legend";

package/src/components/field/field-separator.tsx

@@ -0,0 +1,81 @@
+import { Children, type ReactElement, type ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import { Separator } from "../separator";
+import { Text } from "../text";
+import { TextClassProvider } from "../text/text.context";
+import { fieldVariants } from "./field.variants";
+
+export type FieldSeparatorProps = Omit<ViewProps, "children"> & {
+	className?: string;
+	/** Optional label, drawn between two rules rather than on top of one. */
+	children?: ReactNode;
+};
+
+/**
+ * A rule between two sections of a form, optionally labelled.
+ *
+ * With children it draws **two rules with the label between them**, not one rule
+ * with the label sitting on top. The web version absolutely-positions a single
+ * rule and punches a hole in it with an opaque `bg-background` label, which is
+ * only invisible while the separator sits on exactly that colour — put it on a
+ * card, a sheet or a tinted section and the hole shows as a block of the wrong
+ * shade. Two rules and a gap assume nothing about what is behind them.
+ *
+ * Hidden from assistive technology when it is unlabelled, for the reason
+ * `Separator` itself is: a bare line carries nothing a screen reader can use. A
+ * labelled one keeps its text, which is the part worth announcing.
+ */
+export function FieldSeparator({ className, children, ...props }: FieldSeparatorProps): ReactElement {
+	const slots = fieldVariants();
+	const lineClassName = slots.separatorLine();
+
+	if (!hasContent(children)) {
+		return <Separator className={className} {...props} />;
+	}
+
+	return (
+		<View className={slots.separator({ className })} {...props}>
+			<Separator className={lineClassName} />
+			<TextClassProvider value={undefined}>{wrapTextChildren(children)}</TextClassProvider>
+			<Separator className={lineClassName} />
+		</View>
+	);
+}
+FieldSeparator.displayName = "DelacourUI.Field.Separator";
+
+/** Whether there is a label to make room for between the rules. */
+function hasContent(children: ReactNode): boolean {
+	return Children.toArray(children).some((child) => child !== "");
+}
+
+/**
+ * Wraps a bare string label in a `Text.Caption`.
+ *
+ * React Native cannot render a string outside a `<Text>`, and
+ * `<Field.Separator>Or</Field.Separator>` is the shortest thing anyone will
+ * write. Consecutive strings collapse into one, so an interpolated label is a
+ * single run rather than several spaced apart by the row's own gap.
+ */
+function wrapTextChildren(children: ReactNode): ReactNode {
+	const items = Children.toArray(children);
+	const output: ReactNode[] = [];
+	let run: (string | number)[] = [];
+
+	const flushRun = () => {
+		if (run.length === 0) return;
+		output.push(<Text.Caption key={`label-${output.length}`}>{run.join("")}</Text.Caption>);
+		run = [];
+	};
+
+	for (const child of items) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(child);
+			continue;
+		}
+		flushRun();
+		output.push(child);
+	}
+	flushRun();
+
+	return output;
+}

package/src/components/field/field-set.tsx

@@ -0,0 +1,22 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { fieldVariants } from "./field.variants";
+
+export type FieldSetProps = ViewProps & { className?: string };
+
+/**
+ * A named section of a form — a legend, an optional description, and the fields
+ * under them.
+ *
+ * The step above `Field.Group`: a group is spacing and a set is meaning. Reach
+ * for a set when the fields share a heading a reader needs, and for a bare group
+ * when they are simply a list.
+ *
+ * Holds no state. Invalid and disabled belong to each `Field`, because a section
+ * that turned destructive as a whole would say less than the one field that is
+ * actually wrong.
+ */
+export function FieldSet({ className, ...props }: FieldSetProps): ReactElement {
+	return <View className={fieldVariants().set({ className })} {...props} />;
+}
+FieldSet.displayName = "DelacourUI.Field.Set";

package/src/components/field/field.context.tsx

@@ -0,0 +1,95 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { FieldOrientation } from "./field.variants";
+
+export type FieldContextValue = {
+	/** Whether the field reports an invalid value. */
+	isInvalid: boolean;
+	/** Whether the field's control is unavailable. */
+	isDisabled: boolean;
+	/** Which way the field's parts are laid out. */
+	orientation: FieldOrientation;
+	/**
+	 * A control inside offers its press here, so the whole row can drive it.
+	 *
+	 * The counterpart of `isInvalid` travelling the other way: state cascades
+	 * down, and the one thing a control can hand back up is "tapping my label
+	 * should do this". Pass `null` on unmount. A field holds one control, so a
+	 * second registration replaces the first.
+	 */
+	registerPress: (press: (() => void) | null) => void;
+	/**
+	 * The text of the `Field.Label` inside, or `null` while there is none.
+	 *
+	 * What a control reads for its accessible name when it holds no text of its
+	 * own — a `Slider.Thumb` is a capsule, and a `Switch` is a pill. React Native
+	 * has no `<label for>`; this is that association, carried by the same context
+	 * the state cascades down.
+	 */
+	label: string | null;
+	/**
+	 * A `Field.Label` offers its text here. Pass `null` on unmount.
+	 *
+	 * The counterpart of {@link FieldContextValue.registerPress} going the same
+	 * way: a control hands its press up, a label hands its name down. A field
+	 * holds one label, so a second registration replaces the first.
+	 */
+	registerLabel: (label: string | null) => void;
+};
+
+const FieldContext = createContext<FieldContextValue | null>(null);
+
+/**
+ * Supplies the enclosing field's state to its subtree.
+ *
+ * This is the whole reason `Field` has a context rather than a set of classes.
+ * On the web, shadcn cascades a field's invalid state to its control with
+ * `group-data-[invalid=true]/field:` — a parent-scoped selector. Uniwind has no
+ * equivalent: its compiler reads `data-*` off a single flat selector and its
+ * runtime matches them against the props of **the same component**, so a class
+ * on a `Field` cannot reach the `Input` inside it. A context can.
+ *
+ * So `<Field isInvalid>` turns the control inside it destructive with nothing said at
+ * the control, and the same channel will serve `Checkbox` and `Radio` when they
+ * land. An explicit prop on the control still wins — see `Input`'s ladder.
+ *
+ * Lives in its own module, importing nothing but React and a type, so a
+ * component in another folder can read it without importing `../field` and
+ * closing a cycle. See AGENTS.md rule 3.
+ *
+ * **There is no `useFieldPart` here**, unlike every other compound in this
+ * package, because no part of this one needs a `Field` to work. A description
+ * under a `Field.Set` describes the whole set, and a label under one is a
+ * section heading — both are compositions the web kit documents, and a hook that
+ * threw would turn them into a red box. Every part reads
+ * {@link useFieldContext} and falls back to "not invalid, not disabled", so
+ * state applies where there is a field and nothing happens where there is not.
+ */
+export function FieldProvider({ value, children }: { value: FieldContextValue; children: ReactNode }): ReactElement {
+	return <FieldContext value={value}>{children}</FieldContext>;
+}
+FieldProvider.displayName = "DelacourUI.Field.Provider";
+
+/**
+ * The enclosing field's state, or null outside a `<Field>`.
+ *
+ * This is the export a control reads. It is nullable because a control has to
+ * work perfectly well on its own — a `Field` is a layout a caller opts into, not
+ * a wrapper anything requires.
+ */
+export function useFieldContext(): FieldContextValue | null {
+	return use(FieldContext);
+}
+
+/**
+ * Reads the enclosing field's state.
+ *
+ * For a custom part that has to match the field it sits in. Throws outside one —
+ * use {@link useFieldContext} where the field is optional, as every control does.
+ */
+export function useField(): FieldContextValue {
+	const context = useFieldContext();
+	if (!context) {
+		throw new Error("useField must be called inside a <Field>.");
+	}
+	return context;
+}

package/src/components/field/field.tsx

@@ -0,0 +1,157 @@
+import { type ReactElement, useCallback, useMemo, useState } from "react";
+import { View, type ViewProps } from "react-native";
+import { Pressable } from "../pressable";
+import { type FieldContextValue, FieldProvider } from "./field.context";
+import { type FieldOrientation, fieldVariants, resolveFieldInteractive } from "./field.variants";
+import { FieldContent } from "./field-content";
+import { FieldDescription } from "./field-description";
+import { FieldError } from "./field-error";
+import { FieldGroup } from "./field-group";
+import { FieldLabel } from "./field-label";
+import { FieldLegend } from "./field-legend";
+import { FieldSeparator } from "./field-separator";
+import { FieldSet } from "./field-set";
+
+export type FieldProps = ViewProps & {
+	/** `vertical` stacks label over control; `horizontal` puts them side by side. */
+	orientation?: FieldOrientation;
+	/** Reports an invalid value. The label and the control inside both turn destructive. */
+	isInvalid?: boolean;
+	/** The control inside is unavailable. Fades the label and disables the control. */
+	isDisabled?: boolean;
+	className?: string;
+};
+
+function FieldRoot({
+	orientation = "vertical",
+	isInvalid = false,
+	isDisabled = false,
+	className,
+	...props
+}: FieldProps): ReactElement {
+	// State rather than a ref, because the answer changes what the row renders
+	// as. A control registers in an effect, so this costs one extra render on
+	// mount and none afterwards — the registered callback is stable.
+	const [controlPress, setControlPress] = useState<(() => void) | null>(null);
+
+	// The updater form would call `press` instead of storing it.
+	const registerPress = useCallback((press: (() => void) | null) => setControlPress(() => press), []);
+
+	// The label's text, for a control inside to read as its accessible name.
+	// State for the same reason as the press: a control renders differently for
+	// it, and the label registers in an effect, so it costs one render on mount.
+	const [label, setLabel] = useState<string | null>(null);
+	const registerLabel = useCallback((next: string | null) => setLabel(next), []);
+
+	const context = useMemo<FieldContextValue>(
+		() => ({ isDisabled, isInvalid, label, orientation, registerLabel, registerPress }),
+		[isDisabled, isInvalid, label, orientation, registerLabel, registerPress]
+	);
+
+	const rootClassName = fieldVariants({ isDisabled, isInvalid, orientation }).root({ className });
+
+	// A field is layout until a control asks for the row — see `resolveFieldInteractive`.
+	if (!resolveFieldInteractive(controlPress)) {
+		return (
+			<FieldProvider value={context}>
+				<View accessibilityRole="none" className={rootClassName} {...props} />
+			</FieldProvider>
+		);
+	}
+
+	return (
+		<FieldProvider value={context}>
+			<Pressable
+				// The control inside is the accessibility element, not this row.
+				// Without it a screen reader would announce the label twice and
+				// offer a wrapper with no state of its own.
+				accessible={false}
+				className={rootClassName}
+				disabled={isDisabled}
+				feedback="none"
+				onPress={controlPress}
+				{...props}
+			/>
+		</FieldProvider>
+	);
+}
+
+/**
+ * One control, with its label, its description and its error.
+ *
+ * The layout every form in this library repeats, done once — and the one place a
+ * field's state is written down. `<Field isInvalid>` turns the label destructive
+ * **and the control inside it too**, with nothing said at the control: `Input`
+ * and `Checkbox` both read this field's context, and `Radio` will read the same one.
+ *
+ * That cascade is a React context rather than a class because it has to be.
+ * Uniwind's data selectors match against the props of the component carrying the
+ * class, so there is no parent-scoped `group-data-*` for a `Field` to style its
+ * control with. See `field.context.tsx`.
+ *
+ * A control's own prop still wins, so one field inside an invalid group can opt
+ * out with `<Input isInvalid={false} />`.
+ *
+ * **The label names the control, too.** `Field.Label` hands its text down the
+ * same context, so a control with no text of its own — a `Slider.Thumb`, a
+ * `Switch` — reads "Volume" to a screen reader rather than a bare number. React
+ * Native has no `<label for>`; this is that association. Only a plain string or
+ * number label is lent, since a label built from elements has no text to read
+ * before it renders.
+ *
+ * **The whole row drives the control**, once one offers a press through the same
+ * context — so tapping "Accept the terms", or the description under it, ticks
+ * the `Checkbox` beside it. A checkbox in a form is a small square next to a
+ * sentence, and the sentence is the part people aim at. The row is a `Pressable`
+ * with `feedback="none"` only while a control has registered; a field of static
+ * text mounts no gesture detector at all.
+ *
+ * The text parts render the `Text` presets and pass a colour, never a size —
+ * `Field.Label` *is* `Text.Label`. There is no `Field.Title`: on the web it
+ * exists because a `<div>` is not a `<label>`, and React Native has neither.
+ *
+ * @example
+ * <Field>
+ *   <Field.Label>Full name</Field.Label>
+ *   <Input placeholder="Ada Lovelace" />
+ *   <Field.Description>This appears on invoices.</Field.Description>
+ * </Field>
+ *
+ * @example
+ * <Field isInvalid={!isValid}>
+ *   <Field.Label>Email</Field.Label>
+ *   <Input inputMode="email" onChangeText={setEmail} value={email} />
+ *   <Field.Error>{error}</Field.Error>
+ * </Field>
+ *
+ * @example
+ * <Field.Set>
+ *   <Field.Legend>Profile</Field.Legend>
+ *   <Field.Description>Shown on invoices and emails.</Field.Description>
+ *   <Field.Group>
+ *     <Field>
+ *       <Field.Label>Username</Field.Label>
+ *       <Input autoCapitalize="none" />
+ *     </Field>
+ *   </Field.Group>
+ * </Field.Set>
+ */
+export const Field = Object.assign(FieldRoot, {
+	/** A named section of a form — a legend, a description, and the fields under them. */
+	Set: FieldSet,
+	/** The title of a `Field.Set`. `variant="label"` for a nested one. */
+	Legend: FieldLegend,
+	/** A stack of fields, spaced so two never read as one. Inserts no dividers. */
+	Group: FieldGroup,
+	/** The control's name. Turns destructive with the control when the field is invalid. */
+	Label: FieldLabel,
+	/** Supporting copy. Stays muted in every state, so an error is the line that changed. */
+	Description: FieldDescription,
+	/** What is wrong with the value. Renders nothing when it has no children. */
+	Error: FieldError,
+	/** A label and its description as one block, for a horizontal field. */
+	Content: FieldContent,
+	/** A rule between sections, optionally labelled between two rules. */
+	Separator: FieldSeparator,
+	displayName: "DelacourUI.Field",
+});

package/src/components/field/field.types.ts

@@ -0,0 +1,15 @@
+import type { TextProps } from "../text";
+
+/**
+ * The shape of a field's text parts.
+ *
+ * Shared by `Field.Label`, `Field.Description`, `Field.Error` and
+ * `Field.Legend`, which differ only in the preset they render and the colour
+ * they resolve, so it lives in a leaf rather than in one of the four files
+ * arbitrarily.
+ *
+ * `variant` is omitted because each part already is one — naming a second would
+ * let a caller turn a description into a heading and lose the type scale the
+ * component exists to keep.
+ */
+export type FieldTextProps = Omit<TextProps, "variant">;