@delacour/react-native-ui 0.1.0-alpha.20260925055848 → 0.1.0-alpha.20260925060251

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260925055848",
+	"version": "0.1.0-alpha.20260925060251",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -42,6 +42,7 @@
 		"./field": "./src/components/field/index.ts",
 		"./icon": "./src/components/icon/index.ts",
 		"./input": "./src/components/input/index.ts",
+		"./label": "./src/components/label/index.ts",
 		"./list-group": "./src/components/list-group/index.ts",
 		"./meter": "./src/components/meter/index.ts",
 		"./pressable": "./src/components/pressable/index.ts",
@@ -84,7 +85,7 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260925055848",
+		"@delacour/react-native-charts": "0.1.0-alpha.20260925060251",
 		"@gorhom/bottom-sheet": "^5.2.8",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",

package/src/components/field/AGENTS.md

@@ -103,6 +103,13 @@ A form field's layout, and the one place its state is written down. Root plus
 - **`Field.Group` inserts no dividers**, unlike [`ListGroup`](../list-group/AGENTS.md). A list of rows
   without lines is a wall of text; fields are already held apart by whitespace,
   and a rule between every one is noise.
+- **`Field.Label` is not built on [`Label`](../label/AGENTS.md)**, the standalone
+  primitive. `Label` narrows `children` from `Text`'s and reports
+  `accessibilityState.disabled`, so wrapping it would change this part's public
+  surface. The two colour and fade identically instead, and
+  `label.variants.test.ts` holds them to it against `fieldVariants`' label slot
+  and `resolveFieldTextColor`. A required field uses `Label` directly, since
+  `Field.Label` has no `isRequired`.
 - **There is no `Field.Title`.** On the web it exists because a `<div>` is not a
   `<label>` — label-styled text with nothing to point `htmlFor` at. React Native
   has neither element nor association, so it and `Field.Label` would render the

package/src/components/label/AGENTS.md

@@ -0,0 +1,89 @@
+# Label
+
+The name of a form control, with required, invalid and disabled states. One
+component, no parts.
+
+`import { Label } from "@delacour/react-native-ui/label";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/label` |
+| `label.tsx` | `Label` |
+| `label.variants.ts` | Pure `tv()` slots + resolvers, no RN imports |
+| `label.variants.test.ts` | |
+
+## Design
+
+- **States**: `isRequired`, `isInvalid`, `isDisabled`. All default `false`, all
+  independent — a required field that is also wrong shows both.
+- **It *is* `Text.Label`, and passes a colour, never a scale.** The same move
+  [`Field`](../field/AGENTS.md)'s text parts make: a `text-sm font-medium` in a
+  slot here would be a second definition of [`Text.Label`](../text/AGENTS.md)
+  that could drift from it. `resolveLabelColor` returns `destructive` when
+  invalid and `undefined` otherwise, and `undefined` means "leave the preset's
+  own colour alone". A caller's `color` beats it; `size` and `weight` are
+  `Text`'s own axes and work unchanged. A test asserts neither slot carries a
+  size, weight or colour.
+- **The required mark is a nested `Text`, not a sibling.** A row of two `Text`s
+  would put the asterisk beside the label's **box**: a label long enough to wrap
+  would carry it in a column of its own at the right edge of the first line. As a
+  nested run it flows with the text and lands after the last word — and a
+  no-break space in front of it (` *`) keeps it from wrapping onto a line by
+  itself. It inherits the label's size and weight through `Text`'s own nesting,
+  so there is nothing to keep in step.
+- **The mark is destructive in every state.** Required is a warning about what
+  the form will refuse, so it wears the colour of that refusal whether or not the
+  value is wrong yet. `LABEL_REQUIRED_MARK_COLOR` is the constant;
+  `requiredMarkClassName` restyles it.
+- **Only the root fades when disabled.** The mark is a run inside the root's own
+  text, so the root's `opacity-50` already reaches it. Fading it again would
+  square the fade. A disabled label also reports `accessibilityState.disabled`,
+  so a screen reader says "dimmed" rather than leaving the fade visual-only.
+- **A required label is announced as "Email, required", not "Email, star".**
+  React Native reads a `Text` and its nested runs as one string, so without an
+  `accessibilityLabel` VoiceOver speaks the punctuation. `resolveLabelAccessibilityLabel`
+  builds one when the children are plain text — `labelText` reads strings,
+  numbers and arrays of them, and gives up on anything else rather than guessing
+  at an element's words. A caller's own `accessibilityLabel` always wins, and is
+  the answer when the children are not text.
+- **`children` and `accessibilityLabel` are narrowed from `Text`'s.** `Text`
+  renders `Animated.Text`, whose props also accept Reanimated `SharedValue`s. A
+  label has to append its mark to its children and read them as text, and a
+  shared value supports neither, so the narrower type is the honest one — the
+  reason [`Field.Error`](../field/AGENTS.md) narrows its own children.
+- **It reads no context.** A standalone primitive is whatever it is told, which
+  is what makes it usable outside a `Field` — above a `Slider`, beside a
+  `Switch`, in a settings row — without a layout it does not need.
+  `Field.Label` stays the field-aware counterpart: it reads the enclosing
+  field's state, and it is **not** built on `Label`, because doing so would
+  change its public surface — `Label` narrows `children`, and a disabled `Label`
+  reports `accessibilityState.disabled`, which `Field.Label` does not. The two
+  must still read as one component, so `label.variants.test.ts` pins
+  `resolveLabelColor` and the disabled fade to `fieldVariants`' label slot and
+  `resolveFieldTextColor("label", …)`. Change one and the test names the other.
+- **Inside a `Field`, `Label` is the way to say "required".** `Field.Label` has
+  no `isRequired`. Pass the field's state yourself —
+  `<Label isInvalid={isInvalid} isRequired>Email</Label>` — or read it in a
+  custom part with `useField()`.
+- **There is no `htmlFor`.** React Native has no `<label>` element and no
+  label-for-control association. On Android, give the label a `nativeID` and the
+  control `accessibilityLabelledBy` with the same string; iOS has no equivalent,
+  which is why a control's own `accessibilityLabel` matters more than the label
+  beside it.
+- **There is no `Label.Text` part.** The label is already text; a `View` root
+  holding a text part would be the row of two boxes the nested mark exists to
+  avoid, and would take `ViewProps` where every caller wants `Text`'s `size`,
+  `weight` and `numberOfLines`.
+- **No `onPress` wiring.** `Text` already takes `onPress`, so a label that should
+  focus its control passes one — the same thing `Field`'s whole-row press does
+  for a checkbox. Mounting a gesture detector under every label in a form would
+  announce static text as something to activate, which
+  [`Badge`](../badge/AGENTS.md) refuses for the same reason. A `Text` with `onPress` is exposed to VoiceOver as a **link**, and
+  `accessible={false}` does not change that on iOS — checked on a simulator,
+  where it still read as `AXLink`. A caller wiring one should pass
+  `accessibilityElementsHidden` and `importantForAccessibility="no-hide-descendants"`,
+  and let the control, which carries its own `accessibilityLabel`, be the element
+  a screen reader lands on — the move `Field`'s row makes. The playground's
+  `/label` "Beside a switch" demo shows it.

package/src/components/label/index.ts

@@ -0,0 +1,10 @@
+export { Label, type LabelProps } from "./label";
+export {
+	LABEL_REQUIRED_MARK,
+	LABEL_REQUIRED_MARK_COLOR,
+	type LabelVariantProps,
+	labelText,
+	labelVariants,
+	resolveLabelAccessibilityLabel,
+	resolveLabelColor,
+} from "./label.variants";

package/src/components/label/label.tsx

@@ -0,0 +1,97 @@
+import type { ReactElement, ReactNode } from "react";
+import { Text, type TextProps } from "../text";
+import {
+	LABEL_REQUIRED_MARK,
+	LABEL_REQUIRED_MARK_COLOR,
+	labelVariants,
+	resolveLabelAccessibilityLabel,
+	resolveLabelColor,
+} from "./label.variants";
+
+/**
+ * `Text`'s props minus the role it already is, with two narrowed.
+ *
+ * `Text` renders `Animated.Text`, so its `children` and `accessibilityLabel` may
+ * also be Reanimated `SharedValue`s. A label has to append its required mark to
+ * its children and read them as text for a screen reader, and neither can be
+ * done to a shared value, so the narrower type is the honest one — the move
+ * `Field.Error` makes for the same reason.
+ */
+export type LabelProps = Omit<TextProps, "variant" | "children" | "accessibilityLabel"> & {
+	children?: ReactNode;
+	/** What a screen reader announces. Defaults to "Email, required" for a required label of plain text. */
+	accessibilityLabel?: string;
+	/** Appends a destructive asterisk, and announces the label as required. */
+	isRequired?: boolean;
+	/** Turns the label destructive, to match a control whose value is wrong. */
+	isInvalid?: boolean;
+	/** Fades the label, to match a control that is unavailable. */
+	isDisabled?: boolean;
+	/** Merged into the required mark's class. */
+	requiredMarkClassName?: string;
+};
+
+/**
+ * The name of a form control.
+ *
+ * Renders `Text.Label` and passes it a colour, never a size or a weight, so the
+ * type scale stays the preset's. `isInvalid` turns it destructive and
+ * `isDisabled` fades it, to read as one state with the control beside it.
+ *
+ * `isRequired` appends an asterisk as a **nested** `Text` rather than a sibling,
+ * with a no-break space in front of it, so a label long enough to wrap carries
+ * the mark on its last line, glued to its last word, instead of in a column of
+ * its own. A nested run is read as part of the label's text, so a required label
+ * whose children are text is announced as "Email, required" rather than
+ * "Email, star". Pass `accessibilityLabel` when the children are not text.
+ *
+ * A standalone primitive: it reads no context, so its state is whatever it is
+ * told. `Field.Label` is the field-aware counterpart — it reads a `Field`'s
+ * state for itself, and colours and fades exactly as this does, which a test
+ * holds. Reach for this one outside a `Field`, or inside one when the label has
+ * to say "required", which `Field.Label` does not.
+ *
+ * There is no `htmlFor`: React Native has no label-for-control association. On
+ * Android, give the label a `nativeID` and the control
+ * `accessibilityLabelledBy` with the same string.
+ *
+ * @example
+ * <Label isRequired>Email</Label>
+ *
+ * @example
+ * <Label isInvalid={!isValid} isRequired>
+ *   Email
+ * </Label>
+ */
+export function Label({
+	accessibilityLabel,
+	accessibilityState,
+	children,
+	className,
+	color,
+	isDisabled = false,
+	isInvalid = false,
+	isRequired = false,
+	requiredMarkClassName,
+	...props
+}: LabelProps): ReactElement {
+	const slots = labelVariants({ isDisabled, isInvalid });
+
+	return (
+		<Text.Label
+			accessibilityLabel={resolveLabelAccessibilityLabel({ accessibilityLabel, children, isRequired })}
+			accessibilityState={isDisabled ? { ...accessibilityState, disabled: true } : accessibilityState}
+			className={slots.root({ className })}
+			color={color ?? resolveLabelColor(isInvalid)}
+			{...props}
+		>
+			{children}
+			{isRequired ? (
+				<Text className={slots.requiredMark({ className: requiredMarkClassName })} color={LABEL_REQUIRED_MARK_COLOR}>
+					{` ${LABEL_REQUIRED_MARK}`}
+				</Text>
+			) : null}
+		</Text.Label>
+	);
+}
+Label.displayName = "DelacourUI.Label";

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

@@ -0,0 +1,176 @@
+import { describe, expect, test } from "bun:test";
+import { fieldVariants, resolveFieldTextColor } from "../field/field.variants";
+import { TEXT_COLORS } from "../text/text.variants";
+import {
+	LABEL_REQUIRED_MARK,
+	LABEL_REQUIRED_MARK_COLOR,
+	labelText,
+	labelVariants,
+	resolveLabelAccessibilityLabel,
+	resolveLabelColor,
+} from "./label.variants";
+
+/**
+ * A slot's class string, with `tv`'s empty-slot `undefined` flattened.
+ *
+ * Both slots are handed to a `Text` and carry state only, so they are empty most
+ * of the time — and a bare `not.toMatch()` throws on `undefined` rather than
+ * passing.
+ */
+function cls(value: string | undefined): string {
+	return value ?? "";
+}
+
+const SLOTS = ["root", "requiredMark"] as const;
+
+describe("the slots", () => {
+	// The type scale belongs to `Text.Label`. A size or a weight here would be a
+	// second definition of it that could drift from the preset.
+	test("restate no type scale in any state", () => {
+		for (const isDisabled of [false, true]) {
+			for (const isInvalid of [false, true]) {
+				const slots = labelVariants({ isDisabled, isInvalid });
+				for (const slot of SLOTS) {
+					expect(cls(slots[slot]())).not.toMatch(/\btext-(xs|sm|base|lg|xl|2xl|3xl)\b/);
+					expect(cls(slots[slot]())).not.toMatch(/\bfont-(normal|medium|semibold|bold)\b/);
+				}
+			}
+		}
+	});
+
+	// Colour rides `Text`'s own axis, so a caller's `color` beats it through the
+	// same channel rather than through a tailwind-merge race.
+	test("carry no colour, since that rides the preset's own axis", () => {
+		for (const isInvalid of [false, true]) {
+			const slots = labelVariants({ isInvalid });
+			for (const slot of SLOTS) {
+				expect(cls(slots[slot]())).not.toMatch(/\btext-\w+-?\w*\b/);
+			}
+		}
+	});
+
+	test("merge an incoming className last", () => {
+		expect(labelVariants({ isDisabled: true }).root({ className: "opacity-80" })).toContain("opacity-80");
+		expect(labelVariants({ isDisabled: true }).root({ className: "opacity-80" })).not.toContain("opacity-50");
+		expect(labelVariants().requiredMark({ className: "ml-1" })).toContain("ml-1");
+	});
+});
+
+describe("a disabled label", () => {
+	test("fades", () => {
+		expect(cls(labelVariants({ isDisabled: true }).root())).toContain("opacity-50");
+		expect(cls(labelVariants({ isDisabled: false }).root())).not.toContain("opacity-50");
+	});
+
+	// The mark is a nested run inside the label's own text, so the root's opacity
+	// already reaches it. Fading it again would square the fade.
+	test("does not fade the required mark a second time", () => {
+		expect(cls(labelVariants({ isDisabled: true }).requiredMark())).not.toContain("opacity");
+	});
+
+	test("is enabled by default", () => {
+		expect(labelVariants().root()).toBe(labelVariants({ isDisabled: false }).root());
+	});
+});
+
+describe("resolveLabelColor", () => {
+	test("turns destructive only while invalid", () => {
+		expect(resolveLabelColor(true)).toBe("destructive");
+		expect(resolveLabelColor(false)).toBeUndefined();
+	});
+
+	// `undefined` means "leave the preset's own colour alone" — `Text`'s colour
+	// axis emits nothing when it is not named.
+	test("names a colour Text actually has", () => {
+		expect(TEXT_COLORS).toContain(resolveLabelColor(true) ?? "default");
+	});
+});
+
+describe("the required mark", () => {
+	test("is an asterisk", () => {
+		expect(LABEL_REQUIRED_MARK).toBe("*");
+	});
+
+	// Required is a warning about what the form will refuse, so it is drawn in
+	// the colour of the refusal whether or not the field is currently wrong.
+	test("is destructive, and a colour Text has", () => {
+		expect(LABEL_REQUIRED_MARK_COLOR).toBe("destructive");
+		expect(TEXT_COLORS).toContain(LABEL_REQUIRED_MARK_COLOR);
+	});
+});
+
+describe("labelText", () => {
+	test("reads a string or a number", () => {
+		expect(labelText("Email")).toBe("Email");
+		expect(labelText(42)).toBe("42");
+	});
+
+	test("joins an array of strings, the shape `{name} address` compiles to", () => {
+		expect(labelText(["Work", " ", "email"])).toBe("Work email");
+		expect(labelText(["Line ", 2])).toBe("Line 2");
+	});
+
+	// The holes a conditional child leaves behind are not text.
+	test("skips null, undefined and booleans inside an array", () => {
+		expect(labelText(["Email", null, undefined, false, true])).toBe("Email");
+	});
+
+	// An element could be anything — an icon, a link — and guessing at its text
+	// would put words in a screen reader's mouth the caller never wrote.
+	test("gives up on anything it cannot read as text", () => {
+		expect(labelText({ type: "Icon" })).toBeUndefined();
+		expect(labelText(["Email", { type: "Icon" }])).toBeUndefined();
+		expect(labelText(undefined)).toBeUndefined();
+		expect(labelText(null)).toBeUndefined();
+	});
+
+	test("treats empty text as nothing to read", () => {
+		expect(labelText("")).toBeUndefined();
+		expect(labelText(["", null])).toBeUndefined();
+	});
+});
+
+describe("resolveLabelAccessibilityLabel", () => {
+	// A nested asterisk reads as "star" — so a required label is announced by
+	// what it means instead of by its punctuation.
+	test("reads a required label as required, not as an asterisk", () => {
+		expect(resolveLabelAccessibilityLabel({ children: "Email", isRequired: true })).toBe("Email, required");
+	});
+
+	test("leaves an optional label to the text itself", () => {
+		expect(resolveLabelAccessibilityLabel({ children: "Email", isRequired: false })).toBeUndefined();
+	});
+
+	test("lets the caller's own label win", () => {
+		expect(
+			resolveLabelAccessibilityLabel({ accessibilityLabel: "Work email", children: "Email", isRequired: true })
+		).toBe("Work email");
+		expect(
+			resolveLabelAccessibilityLabel({ accessibilityLabel: "Work email", children: "Email", isRequired: false })
+		).toBe("Work email");
+	});
+
+	// With children it cannot read, the text stays whatever the platform makes
+	// of it rather than becoming a bare "required" with the name dropped.
+	test("says nothing when it cannot read the children", () => {
+		expect(resolveLabelAccessibilityLabel({ children: { type: "Icon" }, isRequired: true })).toBeUndefined();
+	});
+});
+
+// `Field.Label` is the field-aware counterpart of `Label`, styled from
+// `fieldVariants`. A label in a field and a label outside one must not read as
+// two different components, so the decision written twice is held together by a
+// test rather than by a comment hoping it stays so.
+describe("parity with Field", () => {
+	test("colours the label the way Field's resolver does", () => {
+		for (const isInvalid of [false, true]) {
+			expect(resolveLabelColor(isInvalid)).toBe(resolveFieldTextColor("label", isInvalid));
+		}
+	});
+
+	test("fades the label the way Field's slot does", () => {
+		for (const isDisabled of [false, true]) {
+			expect(cls(labelVariants({ isDisabled }).root())).toBe(cls(fieldVariants({ isDisabled }).label()));
+		}
+	});
+});

package/src/components/label/label.variants.ts

@@ -0,0 +1,123 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { TextColor } from "../text/text.variants";
+
+/** What a required label appends. */
+export const LABEL_REQUIRED_MARK = "*";
+
+/**
+ * The required mark's colour, in every state.
+ *
+ * Required is a warning about what the form will refuse, so it is drawn in the
+ * colour of that refusal whether or not the value is wrong right now.
+ */
+export const LABEL_REQUIRED_MARK_COLOR: TextColor = "destructive";
+
+/**
+ * State for a form label and the required mark inside it.
+ *
+ * Two slots because the mark is a second `Text` nested in the label's own, not
+ * because either carries a style of its own: **no slot here holds a type scale
+ * or a colour.** The label renders `Text.Label` and passes a colour through
+ * {@link resolveLabelColor}, so the scale lives in exactly one place — a
+ * `text-sm font-medium` written here would be a second definition of
+ * `Text.Label` that could drift from it. The mark inherits that scale by
+ * nesting.
+ *
+ * Only the root fades. The mark is a run inside the root's text, so the root's
+ * opacity already reaches it; fading it again would square the fade.
+ *
+ * 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 labelVariants = tv({
+	slots: {
+		root: "",
+		requiredMark: "",
+	},
+	variants: {
+		// The empty `false` branches are load-bearing typing, not placeholders.
+		// `tv` derives the prop type from the declared keys, so a map with only
+		// `true` types the prop as `true` rather than `boolean`. See the note in
+		// button.variants.ts.
+		isInvalid: { true: {}, false: {} },
+		isDisabled: { true: { root: "opacity-50" }, false: {} },
+	},
+	defaultVariants: {
+		isInvalid: false,
+		isDisabled: false,
+	},
+});
+
+/**
+ * The `Text` colour a label takes.
+ *
+ * Returning `undefined` is meaningful rather than lazy: `Text`'s `color` axis
+ * emits nothing when it is not named, so the label falls through to
+ * `Text.Label`'s own `text-foreground` without this module knowing which token
+ * the preset chose.
+ *
+ * Pure, so the matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveLabelColor(isInvalid: boolean): TextColor | undefined {
+	return isInvalid ? "destructive" : undefined;
+}
+
+/**
+ * The plain text a label's children spell, or `undefined` when they are
+ * anything but text.
+ *
+ * Strings and numbers are read, and an array of them is joined — that is what
+ * `{name} address` compiles to. The `null`, `undefined` and booleans a
+ * conditional child leaves behind are skipped. An element is not guessed at: it
+ * could be an icon or a link, and inventing its words would put something in a
+ * screen reader's mouth the caller never wrote.
+ *
+ * Typed on `unknown` rather than `ReactNode` so this module takes not even a
+ * type import from React, which is what keeps it reachable from `bun test`.
+ */
+export function labelText(children: unknown): string | undefined {
+	const parts = Array.isArray(children) ? children : [children];
+	let text = "";
+
+	for (const part of parts) {
+		if (part === null || part === undefined || typeof part === "boolean") continue;
+		if (typeof part === "string" || typeof part === "number") {
+			text += String(part);
+			continue;
+		}
+		return undefined;
+	}
+
+	return text === "" ? undefined : text;
+}
+
+/**
+ * What a screen reader announces for a label.
+ *
+ * The caller's own `accessibilityLabel` always wins. Otherwise a required label
+ * whose children are text is announced as `"Email, required"`: the mark is a
+ * nested `Text`, and React Native reads a `Text` and its nested runs as one
+ * string, so without this VoiceOver says "Email, star". An optional label, or
+ * one whose children cannot be read as text, returns `undefined` and is left to
+ * the platform.
+ *
+ * Pure, so the matrix is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveLabelAccessibilityLabel({
+	accessibilityLabel,
+	children,
+	isRequired,
+}: {
+	accessibilityLabel?: string;
+	children: unknown;
+	isRequired: boolean;
+}): string | undefined {
+	if (accessibilityLabel !== undefined) return accessibilityLabel;
+	if (!isRequired) return undefined;
+
+	const text = labelText(children);
+	return text === undefined ? undefined : `${text}, required`;
+}
+
+export type LabelVariantProps = VariantProps<typeof labelVariants>;