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

package/src/components/text/AGENTS.md

@@ -0,0 +1,95 @@
+# Text
+
+The library's type scale, and the one component that reproduces React Native's
+own text inheritance through classNames. Compound root plus twelve presets:
+`Display`, `Title`, `Header`, `Subheader`, `Paragraph`, `Label`, `Caption`,
+`Overline`, and the four inline ones — `Strong`, `Emphasis`, `Link`, `Code`.
+
+`import { Text } from "@delacour/react-native-ui/text";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/text` |
+| `text.tsx` | Root, all twelve presets, the `Object.assign` surface — the pure-preset carve-out to one file per part, see [Compound component layout](../../../AGENTS.md#compound-component-layout) |
+| `text.context.tsx` | `TextClassProvider`, `useTextClass()` |
+| `text.variants.ts` | Pure `tv()` + `resolveTextClass`, no RN imports |
+| `text.variants.test.ts` | |
+
+## Design
+
+- **Every `Text` publishes its resolved class to its subtree**, and merges the
+  one it inherited. Natively a nested `<Text>` inherits the parent's *style
+  object* and overrides only the keys it sets; Uniwind compiles each `className`
+  independently, so the parent's resolved class has to be threaded through and
+  beaten per-axis instead. `resolveTextClass` is that chain, weakest first:
+  `TEXT_BASE_CLASS`, the inherited class, this text's named axes, the caller's
+  `className`. It is the ladder `resolveIconSizeClass` already follows.
+- **`textVariants` has no `defaultVariants`, and must not gain any.** An axis the
+  caller did not name has to emit *nothing* so it falls through to the enclosing
+  text's class — that fall-through is the whole feature. A default would emit
+  from inside the same call, ahead of the inherited class in the merge, and every
+  nested `Text` would snap back to it. `iconVariants` carries the same rule for
+  the same reason. The fallback lives in `TEXT_BASE_CLASS` instead.
+- **`TEXT_BASE_CLASS` is applied unconditionally**, never guarded behind "am I
+  nested". Under true nesting it is a no-op — the parent's string already names
+  every axis, so tailwind-merge drops it. It only does work under a *partial*
+  provider, a [`Button`](../button/AGENTS.md) publishing nothing but `text-primary-foreground`, where
+  guarding it would leave a nested `Text` with a colour and no size at all,
+  collapsing to React Native's own 14pt default.
+- **The correctness property is a fixpoint**: for every class this resolver can
+  produce, a nested `Text` with no props of its own resolves to *exactly* its
+  parent's string, at any depth. The tests assert it across the matrix. Anything
+  that breaks it makes inheritance lossy in a way only a screen would reveal.
+- **A variant names type, never a line height.** tailwind-merge lists `leading`
+  among `font-size`'s conflicting groups, so a `text-lg` from the `size` axis
+  silently deletes a `leading-6` written beside a `text-base` — no error, just a
+  paragraph that loses its leading when someone resizes it. Tailwind v4's
+  `--text-*--line-height` companions survive `tokens.css`'s size-only overrides,
+  so every step already carries a paired leading. Prose needing its own gets a
+  `--text-paragraph` / `--text-paragraph--line-height` **pair**, registered in
+  `tokens.ts` — one utility carrying both.
+- **`color` is page-level only — no `-foreground` family.** `X-foreground` means
+  "content drawn on an `X` surface" (rule 10), and mapping a surface variant to
+  its foreground is already each surface component's job
+  (`BUTTON_FOREGROUND_TOKEN`, `LIST_GROUP_FOREGROUND_TOKEN`). A second copy of
+  that map here could drift from it. Text on a coloured surface writes the
+  utility in a `className`.
+- **`align` is `left`/`center`/`right`, never `start`/`end`.** React Native's
+  `textAlign` accepts `auto | left | right | center | justify` and nothing else,
+  so Tailwind v4's logical-property utilities resolve to a value RN rejects.
+  `transform: "none"` emits `normal-case` rather than an empty string, so it can
+  actually clear an `Overline`'s `uppercase`.
+- **A nested `Text.Code` cannot be padded.** A nested `<Text>` is laid out by the
+  platform's text engine — an `NSAttributedString` run on iOS, a `Span` on
+  Android — and both ignore padding, margin and border radius on an inner
+  `<Text>`. Only the background survives. The compound variant applies the pill
+  treatment to the standalone case only; a code *block* is a `View` the caller
+  wraps around it.
+- **Anything can publish into the cascade, not just a `Text`.** [`Button`](../button/AGENTS.md) wraps
+  its children in a `TextClassProvider` carrying the label's treatment beside the
+  `IconDefaultsProvider` it already renders, so a bare `<Text>` composed into one
+  needs nothing at the call site — the payoff [`Icon`](../icon/AGENTS.md) already had. Publish a
+  treatment only where **one** covers the whole subtree: a [`ListGroup`](../list-group/AGENTS.md) row
+  (title + description), a navbar (title + subtitle) and [`Screen.Error`](../screen/AGENTS.md) (title +
+  message) each carry two, and one provider cannot serve both, so their parts
+  keep per-part classes.
+- **It renders `Animated.Text`.** Animated text styles work anywhere with no
+  opt-in, at the cost of a Reanimated wrapper per text node. If a long list ever
+  profiles badly, the escape hatch is to base the root on RN's `Text` and let app
+  code write `<Animated.Text className={useTextClass()} style={…} />` — the
+  cascade is on context, so that inherits correctly. Measure first.
+- **OS font scaling is respected and capped.** `allowFontScaling` is left at
+  React Native's default; `maxFontSizeMultiplier` defaults to
+  `TEXT_MAX_FONT_SIZE_MULTIPLIER`. The cap exists for the fixed-height chrome —
+  `h-button-*` and `h-navbar-row` cannot grow, so an uncapped multiplier clips a
+  label rather than enlarging it. Both stay overridable per call site.
+- **No `asChild`.** `Slot` throws on a non-element child and a `Text`'s child is
+  usually a string, so it would be unusable in the shape people would reach for.
+  There is also nothing to donate: `useTextClass()` hands the class over directly.
+- **`TEXT_VARIANTS` is ordered — block presets first, largest first.** The tests
+  read that order to assert the type scale descends, so a new block role goes in
+  at its step rather than on the end; appended, it would pass a suite that is no
+  longer checking anything. `TEXT_INLINE_VARIANTS` is the tail of the same list
+  and carries no scale, so it has no such constraint.

package/src/components/text/index.ts

@@ -0,0 +1,25 @@
+export { Text, type TextPresetProps, type TextProps } from "./text";
+export { TextClassProvider, useTextClass } from "./text.context";
+export {
+	canNestText,
+	isInlineTextVariant,
+	resolveTextClass,
+	TEXT_ALIGNS,
+	TEXT_BASE_CLASS,
+	TEXT_COLORS,
+	TEXT_INLINE_VARIANTS,
+	TEXT_MAX_FONT_SIZE_MULTIPLIER,
+	TEXT_SIZES,
+	TEXT_TRANSFORMS,
+	TEXT_VARIANTS,
+	TEXT_WEIGHTS,
+	type TextAlign,
+	type TextColor,
+	type TextInlineVariant,
+	type TextSize,
+	type TextTransform,
+	type TextVariant,
+	type TextVariantProps,
+	type TextWeight,
+	textVariants,
+} from "./text.variants";

package/src/components/text/text.context.tsx

@@ -0,0 +1,60 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+
+const TextClassContext = createContext<string | undefined>(undefined);
+
+/**
+ * Supplies the classes a `Text` in this subtree inherits.
+ *
+ * Two things publish through it, and one context rather than two is the point.
+ * A `Text` publishes its own resolved class, which is what makes a nested
+ * `<Text>` behave the way React Native's native text inheritance does — the
+ * child adopts the parent's treatment and overrides only the axes it names. And
+ * any component can publish a class of its own, which is what lets a text style
+ * be *composed into* a component rather than passed as a prop: a bare `<Text>`
+ * inside a `<Button>` comes out at the button's label colour and type scale
+ * with nothing said at the call site.
+ *
+ * That is the same cascade `IconDefaultsProvider` gives icons, and deliberately
+ * the same *single* path. `Spinner` once read two contexts to recompute one
+ * value; see AGENTS.md rule 3.
+ *
+ * The value is a class string rather than an object because a `Text`'s colour
+ * *is* a class — the asymmetry that forces `IconDefaults` to carry a colour
+ * token alongside its className does not exist here. Its being a primitive is
+ * also why nothing has to memoise it: React compares context by value, so an
+ * unchanged string re-renders no consumer. That matters when every `Text` in
+ * the tree renders one of these.
+ *
+ * `undefined` resets the cascade — wrap a subtree that must not inherit an
+ * enclosing `Text`'s treatment in `<TextClassProvider value={undefined}>`.
+ *
+ * Lives in its own module, importing nothing but React, so a component in
+ * another folder can publish into it without closing a cycle. See AGENTS.md
+ * rule 3.
+ */
+export function TextClassProvider({
+	value,
+	children,
+}: {
+	value: string | undefined;
+	children: ReactNode;
+}): ReactElement {
+	return <TextClassContext value={value}>{children}</TextClassContext>;
+}
+TextClassProvider.displayName = "DelacourUI.Text.ClassProvider";
+
+/**
+ * The classes the nearest enclosing `Text` or `TextClassProvider` published, or
+ * `undefined` outside one.
+ *
+ * Public, so a component this library does not own can join the cascade — an
+ * animated label is `<Animated.Text className={useTextClass()} style={…} />`
+ * and inherits correctly with nothing else wired up.
+ *
+ * `undefined` rather than a `null` sentinel: there is no difference worth
+ * modelling between "no provider" and "a provider with nothing to say", and
+ * `cn` already treats `undefined` as an absent link in the chain.
+ */
+export function useTextClass(): string | undefined {
+	return use(TextClassContext);
+}

package/src/components/text/text.tsx

@@ -0,0 +1,251 @@
+import type { ComponentProps, ReactElement } from "react";
+import Animated from "react-native-reanimated";
+import { TextClassProvider, useTextClass } from "./text.context";
+import {
+	canNestText,
+	resolveTextClass,
+	TEXT_MAX_FONT_SIZE_MULTIPLIER,
+	type TextAlign,
+	type TextColor,
+	type TextSize,
+	type TextTransform,
+	type TextVariant,
+	type TextWeight,
+} from "./text.variants";
+
+export type TextProps = Omit<ComponentProps<typeof Animated.Text>, "className"> & {
+	/** The named role. Omit it and the text inherits, falling back to the base treatment. */
+	variant?: TextVariant;
+	/** A step on the type scale. Beats the variant's own size. */
+	size?: TextSize;
+	weight?: TextWeight;
+	/**
+	 * A page-level text colour. For text drawn on a coloured surface — a button,
+	 * a badge — use a `className`: that mapping belongs to the surface.
+	 */
+	color?: TextColor;
+	align?: TextAlign;
+	transform?: TextTransform;
+	/**
+	 * Merged last, so it beats every named axis and anything inherited.
+	 *
+	 * An arbitrary font size has to be written as a length — `text-[17px]` or
+	 * `text-(length:--x)`. A bare `text-[var(--x)]` is ambiguous to
+	 * tailwind-merge, which files it under colour, so it will not override the
+	 * inherited size.
+	 */
+	className?: string;
+};
+
+/** A preset's props: every axis except the role it already is. */
+export type TextPresetProps = Omit<TextProps, "variant">;
+
+function TextRoot({
+	align,
+	children,
+	className,
+	color,
+	maxFontSizeMultiplier = TEXT_MAX_FONT_SIZE_MULTIPLIER,
+	size,
+	transform,
+	variant,
+	weight,
+	...props
+}: TextProps): ReactElement {
+	const inherited = useTextClass();
+
+	const resolved = resolveTextClass({
+		align,
+		className,
+		color,
+		inherited,
+		isNested: inherited !== undefined,
+		size,
+		transform,
+		variant,
+		weight,
+	});
+
+	const element = (
+		<Animated.Text className={resolved} maxFontSizeMultiplier={maxFontSizeMultiplier} {...props}>
+			{children}
+		</Animated.Text>
+	);
+
+	// A string or number child has no descendant that could read the context, so
+	// the provider is skipped rather than rendered once per label. `Text` is the
+	// most-instantiated component in an app; this is the common case.
+	return canNestText(children) ? <TextClassProvider value={resolved}>{element}</TextClassProvider> : element;
+}
+
+/**
+ * A screen's one hero line — 30pt bold.
+ *
+ * Announced as a heading, so a screen reader's rotor stops on it rather than
+ * reading it as one more line of body copy.
+ */
+function TextDisplay(props: TextPresetProps): ReactElement {
+	return <TextRoot accessibilityRole="header" variant="display" {...props} />;
+}
+TextDisplay.displayName = "DelacourUI.Text.Display";
+
+/** A screen or card title — 24pt bold. Announced as a heading. */
+function TextTitle(props: TextPresetProps): ReactElement {
+	return <TextRoot accessibilityRole="header" variant="title" {...props} />;
+}
+TextTitle.displayName = "DelacourUI.Text.Title";
+
+/** A section heading — 20pt semibold. Announced as a heading. */
+function TextHeader(props: TextPresetProps): ReactElement {
+	return <TextRoot accessibilityRole="header" variant="header" {...props} />;
+}
+TextHeader.displayName = "DelacourUI.Text.Header";
+
+/**
+ * The secondary line under a title — 18pt on the muted token.
+ *
+ * Deliberately not a fourth heading level, and deliberately not announced as
+ * one: it restates the title rather than introducing a new section.
+ */
+function TextSubheader(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="subheader" {...props} />;
+}
+TextSubheader.displayName = "DelacourUI.Text.Subheader";
+
+/**
+ * A block of prose — 16pt on the foreground token.
+ *
+ * The same treatment a bare `<Text>` already renders. It exists so a paragraph
+ * *reads* as one at the call site, the way `Button.Label` exists even though a
+ * bare string child already produces one.
+ */
+function TextParagraph(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="paragraph" {...props} />;
+}
+TextParagraph.displayName = "DelacourUI.Text.Paragraph";
+
+/** A control label or compact UI string — 14pt medium. */
+function TextLabel(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="label" {...props} />;
+}
+TextLabel.displayName = "DelacourUI.Text.Label";
+
+/** Supporting copy under a label or a title — 14pt on the muted token. */
+function TextCaption(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="caption" {...props} />;
+}
+TextCaption.displayName = "DelacourUI.Text.Caption";
+
+/** An eyebrow above a section — 12pt semibold, uppercase, muted. */
+function TextOverline(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="overline" {...props} />;
+}
+TextOverline.displayName = "DelacourUI.Text.Overline";
+
+/**
+ * Inline emphasis by weight.
+ *
+ * Emits `font-semibold` and nothing else, so mid-paragraph it comes out at the
+ * surrounding text's size and colour. Standing on its own it falls back to the
+ * base treatment — React Native's own default colour does not follow the theme.
+ */
+function TextStrong(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="strong" {...props} />;
+}
+TextStrong.displayName = "DelacourUI.Text.Strong";
+
+/** Inline emphasis by slant. Inherits size, weight and colour from the text around it. */
+function TextEmphasis(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="emphasis" {...props} />;
+}
+TextEmphasis.displayName = "DelacourUI.Text.Emphasis";
+
+/**
+ * A tappable run of text. `onPress` rides through from React Native's own
+ * `TextProps` and works on a nested `<Text>` on both platforms.
+ *
+ * Painted with `info`, not `primary`: `--primary` is the primary surface
+ * colour and sits within a shade of `foreground` in both themes.
+ */
+function TextLink(props: TextPresetProps): ReactElement {
+	return <TextRoot accessibilityRole="link" variant="link" {...props} />;
+}
+TextLink.displayName = "DelacourUI.Text.Link";
+
+/**
+ * Inline code, monospaced on a muted background.
+ *
+ * Padded and rounded only when it stands alone. A nested `<Text>` is laid out
+ * by the platform's text engine rather than by Yoga — an `NSAttributedString`
+ * run on iOS, a `Span` on Android — and both ignore padding, margin and border
+ * radius outright, so only the background survives. For a code *block*, wrap it:
+ *
+ * @example
+ * <View className="rounded-lg bg-muted p-3">
+ *   <Text.Code className="bg-transparent" size="sm">bun run gen-exports</Text.Code>
+ * </View>
+ */
+function TextCode(props: TextPresetProps): ReactElement {
+	return <TextRoot variant="code" {...props} />;
+}
+TextCode.displayName = "DelacourUI.Text.Code";
+
+/**
+ * A piece of text, and the type scale the whole library draws from.
+ *
+ * Every `Text` publishes its own resolved classes to its subtree, so a nested
+ * `<Text>` inherits the treatment around it and overrides only the axes it
+ * names — which is what React Native does natively with a nested `<Text>`'s
+ * style, and what Uniwind breaks by compiling each `className` independently.
+ *
+ * Precedence, weakest first: the base treatment, the inherited class, this
+ * text's own named axes, then its `className`.
+ *
+ * Anything can publish into that cascade, not just a `Text` — `Button` wraps its
+ * children in a `TextClassProvider` carrying the label's treatment, so a bare
+ * `<Text>` composed into one needs nothing at the call site. The same idea as
+ * `IconDefaultsProvider`, and the same single path.
+ *
+ * OS font scaling is respected and capped at {@link TEXT_MAX_FONT_SIZE_MULTIPLIER};
+ * both `allowFontScaling` and `maxFontSizeMultiplier` remain overridable.
+ *
+ * @example
+ * <Text.Title>Total <Text color="muted">USD</Text></Text.Title>
+ *
+ * @example
+ * <Text.Paragraph>
+ *   Run <Text.Code>bun test</Text.Code> before you <Text.Strong>commit</Text.Strong>.
+ * </Text.Paragraph>
+ *
+ * @example
+ * // No `asChild`: a Text's child is usually a string, which `Slot` cannot take
+ * // props. Read the cascade directly instead.
+ * <Animated.Text className={useTextClass()} style={fadeStyle} />
+ */
+export const Text = Object.assign(TextRoot, {
+	/** A screen's one hero line — 30pt bold. Announced as a heading. */
+	Display: TextDisplay,
+	/** A screen or card title — 24pt bold. Announced as a heading. */
+	Title: TextTitle,
+	/** A section heading — 20pt semibold. Announced as a heading. */
+	Header: TextHeader,
+	/** The secondary line under a title — 18pt muted. Not a fourth heading level. */
+	Subheader: TextSubheader,
+	/** A block of prose — 16pt. The same treatment a bare `<Text>` renders. */
+	Paragraph: TextParagraph,
+	/** A control label or compact UI string — 14pt medium. */
+	Label: TextLabel,
+	/** Supporting copy — 14pt on the muted token. */
+	Caption: TextCaption,
+	/** An eyebrow above a section — 12pt semibold, uppercase, muted. */
+	Overline: TextOverline,
+	/** Inline emphasis by weight. Inherits size and colour from the text around it. */
+	Strong: TextStrong,
+	/** Inline emphasis by slant. Inherits size, weight and colour from the text around it. */
+	Emphasis: TextEmphasis,
+	/** A tappable run of text, on the `info` token. Takes `onPress`. */
+	Link: TextLink,
+	/** Inline code, monospaced. Padded only when it stands alone. */
+	Code: TextCode,
+	displayName: "DelacourUI.Text",
+});