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

package/src/components/switch/index.ts

@@ -0,0 +1,42 @@
+export { Switch, type SwitchProps } from "./switch";
+export { type SwitchContextValue, SwitchProvider, useSwitch, useSwitchContext } from "./switch.context";
+export type { SwitchContentProps } from "./switch.types";
+export {
+	hasThumbChild,
+	resolveSwitchAxes,
+	resolveSwitchContentTreatment,
+	resolveSwitchRelease,
+	resolveSwitchThumbTokens,
+	resolveSwitchTrackTokens,
+	SWITCH_COLORS,
+	SWITCH_CONTENT_ICON_STEP,
+	SWITCH_CONTENT_REST_TEXT_CLASS,
+	SWITCH_CONTENT_REST_TOKEN,
+	SWITCH_CONTENT_TEXT_CLASS,
+	SWITCH_DEFAULT_COLOR,
+	SWITCH_DEFAULT_SIZE,
+	SWITCH_FLING_VELOCITY,
+	SWITCH_INVALID_CONTENT_TEXT_CLASS,
+	SWITCH_INVALID_THUMB_TOKEN,
+	SWITCH_INVALID_TRACK_TOKEN,
+	SWITCH_PRESS_ANIMATION,
+	SWITCH_PRESS_SPRING,
+	SWITCH_SIZES,
+	SWITCH_TAP_SLOP,
+	SWITCH_THUMB_INSET,
+	SWITCH_THUMB_REST_TOKEN,
+	SWITCH_THUMB_SPRING,
+	SWITCH_THUMB_TOKEN,
+	SWITCH_TRACK_REST_TOKEN,
+	SWITCH_TRACK_TOKEN,
+	type SwitchAxes,
+	type SwitchColor,
+	type SwitchContentPlacement,
+	type SwitchFieldAxes,
+	type SwitchOwnAxes,
+	type SwitchSize,
+	type SwitchVariantProps,
+	switchTravel,
+	switchVariants,
+} from "./switch.variants";
+export type { SwitchThumbProps } from "./switch-thumb";

package/src/components/switch/switch-content.tsx

@@ -0,0 +1,111 @@
+import { Children, type ReactElement, type ReactNode, useMemo } from "react";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import { IconDefaultsProvider } from "../icon";
+import { Text } from "../text";
+import { TextClassProvider } from "../text/text.context";
+import { useSwitchPart } from "./switch.context";
+import type { SwitchContentProps } from "./switch.types";
+import { resolveSwitchContentTreatment, type SwitchContentPlacement, switchVariants } from "./switch.variants";
+
+/**
+ * The shared implementation behind `Switch.StartContent` and `.EndContent`.
+ *
+ * The two are the same box at opposite ends of the track — which end, and which
+ * way their opacity runs, are the only differences — so they share this leaf
+ * rather than duplicating {@link wrapTextChildren} and an animated style into
+ * two part files. `Input.Group`'s two decorators make the same trade.
+ *
+ * **The crossfade is the component's, not the caller's.** `StartContent` sits at
+ * the leading edge, which the thumb vacates as the switch turns **on**, so it
+ * fades in with `progress`; `EndContent` sits at the trailing edge and fades out
+ * with it. That is what lets both be written once with no conditionals — the
+ * thumb reads as uncovering the other end rather than as sliding over content
+ * that was always there.
+ *
+ * The layer is exactly the thumb's footprint at its own end, so a glyph is
+ * centred on the space the knob will vacate rather than beside it.
+ *
+ * Not a part itself: it takes the caller-facing name so the error thrown outside
+ * a switch names `Switch.StartContent` rather than something private.
+ */
+export function SwitchContent({
+	part,
+	placement,
+	className,
+	children,
+	...props
+}: SwitchContentProps & { part: string; placement: SwitchContentPlacement }): ReactElement {
+	const { color, size, isDisabled, isInvalid, progress } = useSwitchPart(part);
+	const slots = switchVariants({ isDisabled, size });
+
+	const treatment = resolveSwitchContentTreatment({ color, isInvalid, placement });
+	const glyphColor = useThemeColor(treatment.color);
+	const glyphClassName = slots.glyph();
+	const iconDefaults = useMemo(
+		() => ({ className: glyphClassName, color: glyphColor ?? "" }),
+		[glyphClassName, glyphColor]
+	);
+
+	const isStart = placement === "start";
+	const contentStyle = useAnimatedStyle(() => ({
+		opacity: isStart ? progress.value : 1 - progress.value,
+	}));
+
+	const textClassName = slots.contentText({ className: treatment.textClass });
+
+	return (
+		<Animated.View
+			className={isStart ? slots.startContent({ className }) : slots.endContent({ className })}
+			// Never the element a screen reader lands on. The switch announces itself
+			// as one control with a checked state, and a decorative glyph either side
+			// of the knob has nothing to add to that.
+			accessible={false}
+			importantForAccessibility="no-hide-descendants"
+			pointerEvents="none"
+			style={contentStyle}
+			{...props}
+		>
+			<IconDefaultsProvider value={iconDefaults}>
+				<TextClassProvider value={textClassName}>{wrapTextChildren(children)}</TextClassProvider>
+			</IconDefaultsProvider>
+		</Animated.View>
+	);
+}
+SwitchContent.displayName = "DelacourUI.Switch.Content";
+
+/**
+ * Wraps bare text children in a `Text`.
+ *
+ * A content layer renders a `View`, and React Native cannot render a string
+ * outside a `<Text>` — so `<Switch.EndContent>OFF</Switch.EndContent>`, which is
+ * the shortest thing anyone will write, would otherwise crash. Consecutive
+ * strings and numbers collapse into one `Text` rather than one each, the same
+ * rule and the same reason as `Input`'s decorators.
+ *
+ * The wrapped text needs no className: the layer has already published its
+ * treatment through `TextClassProvider`.
+ */
+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 key={`content-${output.length}`}>{run.join("")}</Text>);
+		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/switch/switch-end-content.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+import type { SwitchContentProps } from "./switch.types";
+import { SwitchContent } from "./switch-content";
+
+/**
+ * Content at the trailing edge of the track, behind the thumb.
+ *
+ * Revealed as the switch turns **off** — this is the end the knob vacates — so
+ * it is where the "off" mark goes: a cross, a moon, the word OFF. The fade is
+ * the component's, so write it once and unconditionally.
+ *
+ * It sits on the resting track rather than the coloured one, so its glyph takes
+ * a muted foreground rather than the switch's colour.
+ */
+export function SwitchEndContent(props: SwitchContentProps): ReactElement {
+	return <SwitchContent part="Switch.EndContent" placement="end" {...props} />;
+}
+SwitchEndContent.displayName = "DelacourUI.Switch.EndContent";

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

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import type { SwitchContentProps } from "./switch.types";
+import { SwitchContent } from "./switch-content";
+
+/**
+ * Content at the leading edge of the track, behind the thumb.
+ *
+ * Revealed as the switch turns **on** — this is the end the knob vacates — so it
+ * is where the "on" mark goes: a tick, a sun, the word ON. The fade is the
+ * component's, so write it once and unconditionally; there is no `isSelected &&`
+ * to remember.
+ *
+ * An `Icon` needs nothing said at the call site: it inherits the switch's glyph
+ * step and the foreground of the colour the track fades to. A bare string is
+ * wrapped in a `Text` that inherits the same treatment.
+ */
+export function SwitchStartContent(props: SwitchContentProps): ReactElement {
+	return <SwitchContent part="Switch.StartContent" placement="start" {...props} />;
+}
+SwitchStartContent.displayName = "DelacourUI.Switch.StartContent";

package/src/components/switch/switch-thumb.tsx

@@ -0,0 +1,102 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo } from "react";
+import type { LayoutChangeEvent, ViewProps } from "react-native";
+import Animated, { interpolateColor, useAnimatedStyle } from "react-native-reanimated";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import { IconDefaultsProvider } from "../icon";
+import { useSwitchPart } from "./switch.context";
+import {
+	resolveSwitchThumbTokens,
+	resolveSwitchTrackTokens,
+	SWITCH_THUMB_INSET,
+	switchTravel,
+	switchVariants,
+} from "./switch.variants";
+
+export type SwitchThumbProps = Omit<ViewProps, "children" | "style"> & {
+	className?: string;
+	/** Drawn inside the knob. An `Icon` needs nothing said at the call site. */
+	children?: ReactNode;
+};
+
+/**
+ * The knob that slides between the two ends of the track.
+ *
+ * Composed in automatically when the children hold none, so `<Switch />` is
+ * already a complete control — `Radio`'s rule for its indicator. Write it out by
+ * hand only to restyle it, or to put a glyph inside it.
+ *
+ * **It holds no gesture of its own.** One `Gesture.Pan()` on the root drives it,
+ * because a touch anywhere on the pill should move the knob it is about to
+ * move — and a gesture here would nest a descendant recogniser inside the root's,
+ * leaving two to negotiate for one drag. `Slider.Thumb` makes the same trade for
+ * the same reason.
+ *
+ * **One animated style, one node.** The position and the colour are entries in a
+ * single `useAnimatedStyle`, because two calls on one view fight for the same
+ * props and the later one silently wins — the rule `Radio.Indicator` states.
+ *
+ * **The colour is not a class.** It fades between two token *values* as the
+ * switch travels, and a colour being interpolated cannot be a class — the rule
+ * `Checkbox`'s border already follows. The `thumb` slot keeps `bg-background` as
+ * the resting appearance this style starts from, and nothing else names a
+ * background; two sources for one surface is how a class and a style end up
+ * disagreeing for a frame on every toggle.
+ *
+ * **It is invisible until both layouts have reported.** The travel is measured,
+ * not tabulated — `size-icon-xl` cannot be read from JavaScript — and a knob
+ * drawn before then sits at a garbage offset for a frame, which reads as a
+ * flicker on every mount.
+ *
+ * **It does not scale when grabbed, and the track does instead.** The track
+ * clips, so a scaled knob would be cut off by its own capsule — a bite taken out
+ * of the knob rather than an acknowledgement of the press. The outermost node is
+ * the one thing nothing can crop, so that is where the press feedback lives.
+ */
+export function SwitchThumb({ className, children, ...props }: SwitchThumbProps): ReactElement {
+	const { color, size, isInvalid, isDisabled, progress, trackWidth, thumbWidth } = useSwitchPart("Switch.Thumb");
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			thumbWidth.value = event.nativeEvent.layout.width;
+		},
+		[thumbWidth]
+	);
+
+	const tokens = resolveSwitchThumbTokens({ color, isInvalid });
+	const restColor = useThemeColor(tokens.rest) ?? "transparent";
+	const activeColor = useThemeColor(tokens.active) ?? "transparent";
+
+	const thumbStyle = useAnimatedStyle(() => {
+		const measured = trackWidth.value;
+		const travel = switchTravel({
+			inset: SWITCH_THUMB_INSET,
+			thumbWidth: thumbWidth.value,
+			trackWidth: measured,
+		});
+
+		return {
+			backgroundColor: interpolateColor(progress.value, [0, 1], [restColor, activeColor]),
+			opacity: measured > 0 ? 1 : 0,
+			transform: [{ translateX: progress.value * travel }],
+		};
+	});
+
+	// A glyph on the knob takes the *track*'s colour, not the knob's own: it is
+	// drawn on the knob, so it has to contrast with it, and the one value that
+	// reads at both ends is the colour the track fades to. Static rather than
+	// interpolated because an `Icon`'s colour is a prop, not a style.
+	const slots = switchVariants({ isDisabled, size });
+	const glyphColor = useThemeColor(resolveSwitchTrackTokens({ color, isInvalid }).active);
+	const glyphClassName = slots.glyph();
+	const iconDefaults = useMemo(
+		() => ({ className: glyphClassName, color: glyphColor ?? "" }),
+		[glyphClassName, glyphColor]
+	);
+
+	return (
+		<Animated.View className={slots.thumb({ className })} onLayout={handleLayout} style={thumbStyle} {...props}>
+			{children ? <IconDefaultsProvider value={iconDefaults}>{children}</IconDefaultsProvider> : null}
+		</Animated.View>
+	);
+}
+SwitchThumb.displayName = "DelacourUI.Switch.Thumb";

package/src/components/switch/switch.context.tsx

@@ -0,0 +1,79 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { SwitchColor, SwitchSize } from "./switch.variants";
+
+export type SwitchContextValue = {
+	color: SwitchColor;
+	size: SwitchSize;
+	/** Whether the switch is on, on the **JS thread** — what accessibility reads. */
+	isSelected: boolean;
+	isDisabled: boolean;
+	isInvalid: boolean;
+	/**
+	 * Where the thumb is, on the **UI thread**: `0` at the leading edge, `1` at
+	 * the trailing one.
+	 *
+	 * The one value every animated style on this control reads — the thumb's
+	 * position and colour, the track's colour, and both content layers' opacity.
+	 * One source rather than four, so they cannot drift out of step by a frame.
+	 *
+	 * It agrees with {@link SwitchContextValue.isSelected} at rest and disagrees
+	 * for the whole of a drag, which is the entire reason the drag never waits on
+	 * React.
+	 */
+	progress: SharedValue<number>;
+	/** The track's own width, from its `onLayout`. `0` until it has been measured. */
+	trackWidth: SharedValue<number>;
+	/** The thumb's width, from its `onLayout`. `0` until it has been measured. */
+	thumbWidth: SharedValue<number>;
+};
+
+const SwitchContext = createContext<SwitchContextValue | null>(null);
+
+/**
+ * Supplies one switch's settled state and shared values to its own parts.
+ *
+ * Lives in its own module, importing nothing but React and types, so a part can
+ * read it without importing `./switch`. That import would close a cycle, and
+ * Metro serves a partially initialised module for a cycle — leaving the context
+ * `undefined` at import time and red-boxing the app on a cold start.
+ */
+export function SwitchProvider({ value, children }: { value: SwitchContextValue; children: ReactNode }): ReactElement {
+	return <SwitchContext value={value}>{children}</SwitchContext>;
+}
+SwitchProvider.displayName = "DelacourUI.Switch.Provider";
+
+/** The enclosing switch's state, or null outside a `<Switch>`. */
+export function useSwitchContext(): SwitchContextValue | null {
+	return use(SwitchContext);
+}
+
+/**
+ * Reads the enclosing switch's settled state.
+ *
+ * Lets a custom child style itself to match without the switch having to pass
+ * props down through every slot. Throws outside a `<Switch>` — use
+ * {@link useSwitchContext} where the enclosing switch is optional.
+ */
+export function useSwitch(): SwitchContextValue {
+	const context = useSwitchContext();
+	if (!context) {
+		throw new Error("useSwitch must be called inside a <Switch>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing switch's state, for a compound part that cannot work without one.
+ *
+ * Internal: deliberately not re-exported from `index.ts`. A caller outside the
+ * library wants {@link useSwitch}, whose error message names the hook rather
+ * than a part.
+ */
+export function useSwitchPart(component: string): SwitchContextValue {
+	const context = useSwitchContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Switch>.`);
+	}
+	return context;
+}