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

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

@@ -0,0 +1,24 @@
+import type { ReactElement } from "react";
+import type { TextProps } from "react-native";
+import { Text } from "../text";
+import { useButtonPart } from "./button.context";
+import { buttonVariants } from "./button.variants";
+
+export type ButtonLabelProps = TextProps & { className?: string };
+
+/**
+ * The button's text.
+ *
+ * Carries its own colour and type scale, read from the button's context: a
+ * React Native `View` does not cascade colour to a `Text` descendant, so a
+ * colour set on the root would be lost.
+ *
+ * The class is passed rather than inherited even though the button publishes the
+ * same one through `TextClassProvider` — the two agree, and stating it here
+ * keeps the label correct if it is ever rendered somewhere the provider is not.
+ */
+export function ButtonLabel({ className, ...props }: ButtonLabelProps): ReactElement {
+	const { variant, size } = useButtonPart("Button.Label");
+	return <Text className={buttonVariants({ size, variant }).label({ className })} {...props} />;
+}
+ButtonLabel.displayName = "DelacourUI.Button.Label";

package/src/components/button/button-start-content.tsx

@@ -0,0 +1,15 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { ButtonSlotProps } from "./button.types";
+import { buttonVariants } from "./button.variants";
+
+/**
+ * A centred wrapper for leading content that is not an `Icon`.
+ *
+ * An `Icon` needs no wrapper — it inherits the button's icon size and its
+ * variant's colour from the root's `IconDefaultsProvider`.
+ */
+export function ButtonStartContent({ className, ...props }: ButtonSlotProps): ReactElement {
+	return <View className={buttonVariants().startContent({ className })} {...props} />;
+}
+ButtonStartContent.displayName = "DelacourUI.Button.StartContent";

package/src/components/button/button.context.tsx

@@ -0,0 +1,187 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { PressableFeedback } from "../pressable/pressable.variants";
+import type { ButtonGroupOrientation, ButtonGroupPosition, ButtonSize, ButtonVariant } from "./button.variants";
+
+export type ButtonContextValue = {
+	/** Size of the button. */
+	size: ButtonSize;
+	/** Visual variant of the button. */
+	variant: ButtonVariant;
+	/** Whether the button is disabled. */
+	isDisabled: boolean;
+	/** Whether the button has work in flight. */
+	isLoading: boolean;
+};
+
+const ButtonContext = createContext<ButtonContextValue | null>(null);
+
+/**
+ * Supplies the enclosing button's variant, size and state to its subtree.
+ *
+ * Lives in its own module, importing nothing but `button.variants`, so a
+ * component the button itself renders — `Spinner` — can read it without
+ * importing `../button`. That import would close a cycle through
+ * `button.tsx`, and Metro serves a partially initialised module for a cycle,
+ * leaving the context `undefined` at import time.
+ */
+export function ButtonProvider({ value, children }: { value: ButtonContextValue; children: ReactNode }): ReactElement {
+	return <ButtonContext value={value}>{children}</ButtonContext>;
+}
+ButtonProvider.displayName = "DelacourUI.Button.Provider";
+
+/** The enclosing button's context, or null outside a `<Button>`. */
+export function useButtonContext(): ButtonContextValue | null {
+	return use(ButtonContext);
+}
+
+/**
+ * Reads the enclosing button's variant, size and state.
+ *
+ * Lets a custom child style itself to match without the button having to pass
+ * props down through every slot. Throws outside a `<Button>` — use
+ * {@link useButtonContext} where the enclosing button is optional.
+ */
+export function useButton(): ButtonContextValue {
+	const context = useButtonContext();
+	if (!context) {
+		throw new Error("useButton must be called inside a <Button>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing button'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 useButton}, whose error message names the hook rather
+ * than a part.
+ */
+export function useButtonPart(component: string): ButtonContextValue {
+	const context = useButtonContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Button>.`);
+	}
+	return context;
+}
+
+export type ButtonGroupContextValue = {
+	/** Which way the group runs. Members square the pair of corners crossing it. */
+	orientation: ButtonGroupOrientation;
+	/** The group owns this outright — members of different heights do not join. */
+	size: ButtonSize;
+	/** A default a member may override. */
+	variant?: ButtonVariant;
+	/** A default a member may override, so one option can disable itself. */
+	isDisabled?: boolean;
+	/** Press treatment for members. Unset falls back to `fade` — see `resolveButtonFeedback`. */
+	feedback?: PressableFeedback;
+};
+
+export type ButtonGroupItemContextValue = ButtonGroupContextValue & {
+	/** Where this member sits among the group's members, separators skipped. */
+	position: ButtonGroupPosition;
+	/** Overlap the member before it, so the shared edge is drawn once. */
+	isSeamed: boolean;
+};
+
+const ButtonGroupContext = createContext<ButtonGroupContextValue | null>(null);
+
+const ButtonGroupItemContext = createContext<ButtonGroupItemContextValue | null>(null);
+
+/**
+ * Supplies the enclosing group's axes to everything inside it.
+ *
+ * A second context beside {@link ButtonGroupItemProvider} rather than a field on
+ * it, because `Button.Group.Separator` needs the orientation and is deliberately
+ * *not* a member — so it has no item context to read one from.
+ *
+ * The optional axes are published raw. `undefined` means "the group said
+ * nothing", which is what lets a member's `??` ladder see past a group that
+ * named none, and what lets one member disable itself inside a group that did
+ * not.
+ */
+export function ButtonGroupProvider({
+	value,
+	children,
+}: {
+	value: ButtonGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <ButtonGroupContext value={value}>{children}</ButtonGroupContext>;
+}
+ButtonGroupProvider.displayName = "DelacourUI.Button.Group.Provider";
+
+/** The enclosing group's axes, or null outside a `<Button.Group>`. */
+export function useButtonGroupContext(): ButtonGroupContextValue | null {
+	return use(ButtonGroupContext);
+}
+
+/**
+ * Reads the enclosing group's axes.
+ *
+ * Throws outside a `<Button.Group>` — use {@link useButtonGroupContext} where
+ * the enclosing group is optional, as a `Button` itself does.
+ */
+export function useButtonGroup(): ButtonGroupContextValue {
+	const context = useButtonGroupContext();
+	if (!context) {
+		throw new Error("useButtonGroup must be called inside a <Button.Group>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing group's axes, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useButtonGroup}, whose error message names the hook
+ * rather than a part.
+ */
+export function useButtonGroupPart(component: string): ButtonGroupContextValue {
+	const context = useButtonGroupContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Button.Group>.`);
+	}
+	return context;
+}
+
+/**
+ * Supplies one member its place in the group.
+ *
+ * The group wraps each member in one of these rather than cloning props onto it.
+ * A provider is not a host component, so no view is created and Yoga sees
+ * exactly the children the group's own `View` already had — while a cloned prop
+ * would reach only a direct child, and never one a caller wrapped in a `View` or
+ * produced from a helper.
+ */
+export function ButtonGroupItemProvider({
+	value,
+	children,
+}: {
+	value: ButtonGroupItemContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <ButtonGroupItemContext value={value}>{children}</ButtonGroupItemContext>;
+}
+ButtonGroupItemProvider.displayName = "DelacourUI.Button.Group.ItemProvider";
+
+/** This member's place in the group, or null for a control standing on its own. */
+export function useButtonGroupItemContext(): ButtonGroupItemContextValue | null {
+	return use(ButtonGroupItemContext);
+}
+
+/**
+ * Reads this member's place in the group.
+ *
+ * For a custom control that has to join a group the way a `Button` does. Throws
+ * outside one — use {@link useButtonGroupItemContext} where the group is
+ * optional, as the button itself does.
+ */
+export function useButtonGroupItem(): ButtonGroupItemContextValue {
+	const context = useButtonGroupItemContext();
+	if (!context) {
+		throw new Error("useButtonGroupItem must be called inside a <Button.Group>.");
+	}
+	return context;
+}

package/src/components/button/button.tsx

@@ -0,0 +1,273 @@
+import { Children, isValidElement, type ReactElement, type ReactNode, useMemo } from "react";
+import { Icon, IconDefaultsProvider } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { Spinner } from "../spinner";
+import { TextClassProvider } from "../text/text.context";
+import { type ButtonContextValue, ButtonProvider, useButtonGroupItemContext } from "./button.context";
+import {
+	BUTTON_FOREGROUND_TOKEN,
+	type ButtonLayout,
+	type ButtonSize,
+	type ButtonSpinnerPlacement,
+	type ButtonVariant,
+	buttonVariants,
+	resolveButtonFeedback,
+	resolveButtonLayout,
+	resolveGroupedButtonSize,
+	resolveSpinnerSwapIndex,
+} from "./button.variants";
+import { ButtonEndContent } from "./button-end-content";
+import { ButtonGroup } from "./button-group";
+import { ButtonLabel } from "./button-label";
+import { ButtonStartContent } from "./button-start-content";
+
+export type ButtonProps = Omit<PressableProps, "busy" | "children" | "disabled" | "pressedOpacity" | "pressedScale"> & {
+	variant?: ButtonVariant;
+	/** Height, label step, icon step, corner and padding on one axis. `icon-*` is a square. */
+	size?: ButtonSize;
+	isDisabled?: boolean;
+	/** Work is in flight: a spinner is composed in and presses are blocked. */
+	isLoading?: boolean;
+	/** Where the spinner sits. `only` replaces the content, keeping the footprint. */
+	spinnerPlacement?: ButtonSpinnerPlacement;
+	/** Fade the button while loading, the way `isDisabled` does. Off by default. */
+	isDimmedWhileLoading?: boolean;
+	children?: ReactNode;
+};
+
+function ButtonRoot({
+	variant,
+	size,
+	isDisabled,
+	isLoading = false,
+	isDimmedWhileLoading = false,
+	spinnerPlacement = "start",
+	feedback,
+	accessibilityLabel,
+	className,
+	children,
+	...props
+}: ButtonProps): ReactElement {
+	// Deliberately not defaulted in the destructure above: a default there would
+	// swallow the group before it was ever consulted. The group owns a member's
+	// *step* — controls of different heights do not join — but not its shape, so
+	// a square member keeps its width inside a run. `variant` and `isDisabled`
+	// are defaults it may override, so one member can disable itself inside a
+	// group that did not.
+	const item = useButtonGroupItemContext();
+	const resolvedSize = resolveGroupedButtonSize(size, item?.size);
+	const resolvedVariant = variant ?? item?.variant ?? "primary";
+	const resolvedIsDisabled = isDisabled ?? item?.isDisabled ?? false;
+
+	const context = useMemo<ButtonContextValue>(
+		() => ({ variant: resolvedVariant, size: resolvedSize, isDisabled: resolvedIsDisabled, isLoading }),
+		[resolvedVariant, resolvedSize, resolvedIsDisabled, isLoading]
+	);
+
+	const layout = useMemo(() => resolveButtonLayout({ isLoading, spinnerPlacement }), [isLoading, spinnerPlacement]);
+
+	const content = useMemo(() => composeContent(children, layout), [children, layout]);
+
+	const slots = buttonVariants({
+		groupPosition: item?.position ?? "none",
+		isDimmedWhileLoading,
+		isDisabled: resolvedIsDisabled,
+		isLoading,
+		isSeamed: item?.isSeamed ?? false,
+		orientation: item?.orientation ?? "horizontal",
+		size: resolvedSize,
+		variant: resolvedVariant,
+	});
+
+	// Icons and spinners composed into the button adopt these unless told otherwise.
+	const iconClassName = slots.icon();
+	const iconDefaults = useMemo(
+		() => ({ className: iconClassName, color: BUTTON_FOREGROUND_TOKEN[resolvedVariant] }),
+		[iconClassName, resolvedVariant]
+	);
+
+	const label = accessibilityLabel ?? (layout.isSpinnerOnly ? textOf(children) : undefined);
+
+	return (
+		<ButtonProvider value={context}>
+			<Pressable
+				accessibilityLabel={label}
+				accessibilityRole="button"
+				busy={isLoading}
+				className={slots.root({ className })}
+				disabled={resolvedIsDisabled}
+				feedback={resolveButtonFeedback(feedback, item?.feedback, item !== null)}
+				{...props}
+			>
+				<IconDefaultsProvider value={iconDefaults}>
+					<TextClassProvider value={slots.label()}>{content}</TextClassProvider>
+				</IconDefaultsProvider>
+			</Pressable>
+		</ButtonProvider>
+	);
+}
+
+/**
+ * Composes the spinner into the button's children.
+ *
+ * A loading button **replaces** its icon rather than showing both. Adding a
+ * spinner alongside would push the label sideways the moment work started and
+ * pull it back when it finished; swapping costs no layout at all, because the
+ * spinner and the icon are drawn at the same `size-icon-*` token — the button
+ * publishes one class and both read it.
+ *
+ * Only the icon at the named edge is swapped — the first child at `start`, the
+ * last at `end`. An icon on the other side stays where it is and the spinner is
+ * inserted at the edge instead, spaced off the label by the root's own `gap`:
+ * `spinnerPlacement` is where the caller wants the spinner, and a button
+ * holding one leading icon must not answer `end` by spinning at the start.
+ *
+ * `only` drops the children: the spinner stands in for the whole content, and
+ * the button keeps whatever footprint its `size` gave it.
+ *
+ * The spinner is emitted bare — it reads its size and colour from the button's
+ * context, so nothing is passed here.
+ */
+function composeContent(children: ReactNode, layout: ButtonLayout): ReactNode {
+	if (layout.isSpinnerOnly) return <Spinner />;
+	if (layout.spinnerSide === null) return wrapTextChildren(children);
+
+	const items = Children.toArray(wrapTextChildren(children));
+	const swapAt = resolveSpinnerSwapIndex(items.map(isIcon), layout.spinnerSide);
+
+	if (swapAt !== null) {
+		return items.map((child, index) => (index === swapAt ? <Spinner key="spinner" /> : child));
+	}
+
+	return layout.spinnerSide === "start" ? (
+		<>
+			<Spinner />
+			{items}
+		</>
+	) : (
+		<>
+			{items}
+			<Spinner />
+		</>
+	);
+}
+
+/**
+ * Whether a child is an `Icon` the spinner can stand in for.
+ *
+ * Only a bare `Icon` qualifies. A `Button.StartContent` wraps arbitrary content
+ * whose height the button does not know, so replacing one could resize the
+ * button — the thing this swap exists to avoid.
+ */
+function isIcon(child: ReactNode): boolean {
+	return isValidElement(child) && child.type === Icon;
+}
+
+/**
+ * The button's own text, for use as an accessibility label.
+ *
+ * `spinnerPlacement="only"` takes the label out of the tree, so the name a
+ * screen reader was reading has to be carried onto the root instead. Reaches
+ * one level into a `Button.Label`; anything more deeply nested needs an
+ * explicit `accessibilityLabel`.
+ */
+function textOf(children: ReactNode): string | undefined {
+	const parts: string[] = [];
+
+	for (const child of Children.toArray(children)) {
+		if (typeof child === "string" || typeof child === "number") {
+			parts.push(String(child));
+			continue;
+		}
+		if (!isValidElement(child) || child.type !== ButtonLabel) continue;
+		const nested = (child.props as { children?: ReactNode }).children;
+		if (typeof nested === "string" || typeof nested === "number") parts.push(String(nested));
+	}
+
+	return parts.length > 0 ? parts.join("") : undefined;
+}
+
+/**
+ * Wraps bare text children in a `Button.Label`.
+ *
+ * React Native cannot render a string outside a `<Text>`, so `<Button>Save</Button>`
+ * would otherwise crash. Consecutive strings and numbers are collected into a
+ * single label rather than one each — `Row {index}` is one piece of text, and
+ * wrapping the parts separately would space them apart by the button's 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(<ButtonLabel key={`label-${output.length}`}>{run.join("")}</ButtonLabel>);
+		run = [];
+	};
+
+	for (const child of items) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(child);
+			continue;
+		}
+		flushRun();
+		output.push(child);
+	}
+	flushRun();
+
+	return output;
+}
+
+/**
+ * A pressable action, composed from parts rather than configured by flags.
+ *
+ * `variant`, `size` and the button's state reach the sub-components through
+ * context, so `Button.Label` picks its own text colour. That indirection is not
+ * incidental: a React Native `View` does not cascade colour to a `Text`
+ * descendant the way a DOM element would, so a colour set on the root is lost.
+ *
+ * Plain string or number children are wrapped in a `Button.Label`
+ * automatically; pass the compound parts when a layout needs more control.
+ *
+ * Icons are composed in, not passed as props. Anything in the subtree inherits
+ * the button's icon size and its variant's colour, so an `Icon` needs nothing
+ * but the glyph — and a `Spinner` needs nothing at all.
+ *
+ * Text works the same way: the button publishes its label treatment through a
+ * `TextClassProvider`, so a bare `<Text>` composed in comes out at the label's
+ * colour and type scale without being told to.
+ *
+ * `isLoading` blocks presses and announces the button as busy, but does not dim
+ * it: a spinner already says the press landed. `isDimmedWhileLoading` opts into
+ * the faded treatment.
+ *
+ * A button is a `Pressable`, so `feedback`, `haptic` and the rest are inherited
+ * rather than restated here. Only the default differs: `scale`, the spring the
+ * rest of the library's controls press with.
+ *
+ * @example
+ * <Button haptic="selection" onPress={next}>
+ *   <Button.Label>Continue</Button.Label>
+ *   <Icon icon={IconArrowRight} />
+ * </Button>
+ *
+ * @example
+ * <Button isLoading={isSaving} onPress={save}>Save</Button>
+ *
+ * @example
+ * <Button accessibilityLabel="Favourite" size="icon-md" variant="ghost">
+ *   <Icon icon={IconHeart} />
+ * </Button>
+ */
+export const Button = Object.assign(ButtonRoot, {
+	/** The button's text. Picks its colour and type scale from the button's variant and size. */
+	Label: ButtonLabel,
+	/** A centred wrapper for leading content that is not an `Icon`. */
+	StartContent: ButtonStartContent,
+	/** A centred wrapper for trailing content that is not an `Icon`. */
+	EndContent: ButtonEndContent,
+	/** Several controls joined into one run, sharing a corner and a seam. */
+	Group: ButtonGroup,
+	displayName: "DelacourUI.Button",
+});

package/src/components/button/button.types.ts

@@ -0,0 +1,10 @@
+import type { ViewProps } from "react-native";
+
+/**
+ * The shape of a button's leading and trailing slots.
+ *
+ * Shared by `Button.StartContent` and `Button.EndContent`, which are identical
+ * apart from where the root places them, so it lives in a leaf rather than in
+ * one of the two files arbitrarily.
+ */
+export type ButtonSlotProps = ViewProps & { className?: string };