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

package/src/components/stack-card/stack-card-slot.tsx

@@ -0,0 +1,90 @@
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { StackCardSlotProvider, useStackCardPart } from "./stack-card.context";
+import { resolveBehindTransform, resolveDragProgress } from "./stack-card.variants";
+
+export type StackCardSlotProps = {
+	/** This card's index in the deck. */
+	cardIndex: number;
+	/** Whether this card is the top one, as React last rendered it. */
+	isTop: boolean;
+	/** The points the pile keeps clear below the cards, for the stack's step. */
+	inset: number;
+	children: ReactNode;
+};
+
+/**
+ * The animated box one card sits in. Internal — the deck renders one per
+ * mounted card.
+ *
+ * **Every slot reads the same two shared values**, the top card's `x` and `y`,
+ * and works out its own place from how far behind the UI thread's top it sits:
+ *
+ * - the top follows the drag, tilting `x / width · 12°`;
+ * - a card behind sits at `resolveBehindTransform`, interpolated toward the slot
+ *   ahead by the drag's progress, so it is already in place when a release
+ *   throws the top card;
+ * - a card ahead of the top — the one just thrown, kept mounted for undo — is
+ *   hidden.
+ *
+ * Nothing here re-renders during a drag, and the top moving is a shared value
+ * changing, so a throw lands without waiting on React. Under reduced motion the
+ * cards behind do not step during the drag: the pile swaps when the throw lands.
+ *
+ * Every transform pivots on the bottom centre, which is what makes `fan` fan,
+ * and makes a smaller `stack` card's lower edge peek out below the one in front.
+ * Only the top card takes touches or is visible to assistive technology.
+ */
+export function StackCardSlot({ cardIndex, isTop, inset, children }: StackCardSlotProps): ReactElement {
+	const { x, y, top, fade, width, height, threshold, layout, depth, isReducedMotion } =
+		useStackCardPart("StackCard.Card");
+
+	const animatedStyle = useAnimatedStyle(() => {
+		const position = cardIndex - top.value;
+		if (position < 0) {
+			return {
+				opacity: 0,
+				transform: [{ translateX: 0 }, { translateY: 0 }, { scale: 1 }, { rotate: "0deg" }],
+			};
+		}
+		if (position === 0) {
+			const rotate = width.value > 0 ? (x.value / width.value) * 12 : 0;
+			return {
+				opacity: fade.value,
+				transform: [{ translateX: x.value }, { translateY: y.value }, { scale: 1 }, { rotate: `${rotate}deg` }],
+			};
+		}
+		const progress = isReducedMotion
+			? 0
+			: resolveDragProgress({ height: height.value, threshold, width: width.value, x: x.value, y: y.value });
+		const behind = resolveBehindTransform({ depth, layout, position, progress });
+		return {
+			opacity: behind.opacity,
+			transform: [
+				{ translateX: 0 },
+				{ translateY: behind.translateY },
+				{ scale: behind.scale },
+				{ rotate: `${behind.rotate}deg` },
+			],
+		};
+	});
+
+	const slot = useMemo(() => ({ cardIndex, isTop }), [cardIndex, isTop]);
+
+	return (
+		<StackCardSlotProvider value={slot}>
+			<Animated.View
+				accessibilityElementsHidden={!isTop}
+				importantForAccessibility={isTop ? "auto" : "no-hide-descendants"}
+				pointerEvents={isTop ? "box-none" : "none"}
+				style={[
+					{ bottom: inset, left: 0, position: "absolute", right: 0, top: 0, transformOrigin: "50% 100%" },
+					animatedStyle,
+				]}
+			>
+				{children}
+			</Animated.View>
+		</StackCardSlotProvider>
+	);
+}
+StackCardSlot.displayName = "DelacourUI.StackCard.Slot";

package/src/components/stack-card/stack-card-stamp.tsx

@@ -0,0 +1,76 @@
+import type { ReactElement, ReactNode } from "react";
+import type { ViewProps } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { Text } from "../text";
+import { useStackCardPart } from "./stack-card.context";
+import {
+	resolveStampOpacity,
+	STACK_CARD_STAMP_ROTATION,
+	type StackCardDirection,
+	type StackCardStampColor,
+	stackCardVariants,
+} from "./stack-card.variants";
+
+export type StackCardStampProps = Omit<ViewProps, "children" | "style"> & {
+	/** The direction this stamp answers for. Defaults to `right`. */
+	direction?: StackCardDirection;
+	/** The stamp's colour — and the tint of the action button for the same direction. */
+	color?: StackCardStampColor;
+	/** The stamp's word. Bare text is wrapped in the stamp's label. */
+	children: ReactNode;
+	className?: string;
+	labelClassName?: string;
+};
+
+/**
+ * The answer a throw gives, printed on the top card as it is dragged.
+ *
+ * Declared once on the deck and drawn on whichever card is on top, on the side
+ * it answers for — a right-hand "yes" sits top-start, tilted the way a rubber
+ * stamp lands. It fades in with progress toward its direction and reaches full
+ * strength at the threshold, so a stamp at full strength means "let go and this
+ * is the answer". Hidden from assistive technology: the card's actions say the
+ * same thing in words.
+ */
+export function StackCardStamp({
+	direction = "right",
+	color = "primary",
+	children,
+	className,
+	labelClassName,
+	...props
+}: StackCardStampProps): ReactElement {
+	const { x, y, width, height, threshold } = useStackCardPart("StackCard.Stamp");
+	const rotation = STACK_CARD_STAMP_ROTATION[direction];
+	const slots = stackCardVariants({ color, direction });
+
+	const animatedStyle = useAnimatedStyle(() => ({
+		opacity: resolveStampOpacity({
+			direction,
+			height: height.value,
+			threshold,
+			width: width.value,
+			x: x.value,
+			y: y.value,
+		}),
+		transform: [{ rotate: `${rotation}deg` }],
+	}));
+
+	return (
+		<Animated.View
+			accessibilityElementsHidden
+			className={slots.stamp({ className })}
+			importantForAccessibility="no-hide-descendants"
+			pointerEvents="none"
+			style={animatedStyle}
+			{...props}
+		>
+			{typeof children === "string" || typeof children === "number" ? (
+				<Text className={slots.stampLabel({ className: labelClassName })}>{children}</Text>
+			) : (
+				children
+			)}
+		</Animated.View>
+	);
+}
+StackCardStamp.displayName = "DelacourUI.StackCard.Stamp";

package/src/components/stack-card/stack-card.context.tsx

@@ -0,0 +1,117 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { StackCardState } from "./stack-card.types";
+import type { StackCardDirection, StackCardLayout, StackCardStampColor } from "./stack-card.variants";
+
+export type StackCardContextValue = StackCardState & {
+	/** The directions the gesture throws in. */
+	directions: readonly StackCardDirection[];
+	/** What a screen reader and an action button call each direction. */
+	labelFor: (direction: StackCardDirection) => string;
+	/** The colour of the stamp answering for each direction, which tints its action. */
+	stampColors: Partial<Record<StackCardDirection, StackCardStampColor>>;
+	isDisabled: boolean;
+	layout: StackCardLayout;
+	/** Cards drawn behind the top, already clamped to 0..4. */
+	depth: number;
+	/** Fraction of the card's size a drag must cover to throw it. */
+	threshold: number;
+	/** The OS reduce-motion setting: cards fade rather than fly. */
+	isReducedMotion: boolean;
+	/**
+	 * The top card's offset, on the **UI thread** — the one value every part
+	 * animates from. A drag writes it and nothing re-renders.
+	 */
+	x: SharedValue<number>;
+	y: SharedValue<number>;
+	/**
+	 * The index of the top card on the UI thread. It moves the frame a throw
+	 * lands, ahead of React, so the card behind is the top before anything
+	 * re-renders.
+	 */
+	top: SharedValue<number>;
+	/** The top card's opacity — what a reduced-motion throw fades. */
+	fade: SharedValue<number>;
+	/** The pile's measured size. `0` until it has been laid out. */
+	width: SharedValue<number>;
+	height: SharedValue<number>;
+};
+
+const StackCardContext = createContext<StackCardContextValue | null>(null);
+
+/**
+ * Supplies the deck's state to its parts.
+ *
+ * In a leaf of its own, importing nothing but types, so a part can read it
+ * without importing `./stack-card` and closing a cycle (package AGENTS.md
+ * rule 3).
+ */
+export function StackCardProvider({
+	value,
+	children,
+}: {
+	value: StackCardContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <StackCardContext value={value}>{children}</StackCardContext>;
+}
+StackCardProvider.displayName = "DelacourUI.StackCard.Provider";
+
+/** The enclosing deck, or null outside a `<StackCard>`. */
+export function useStackCardContext(): StackCardContextValue | null {
+	return use(StackCardContext);
+}
+
+/**
+ * The enclosing deck's index, count and controls.
+ *
+ * For a custom control beside the pile — a counter, a "skip all" button. Throws
+ * outside a `<StackCard>`.
+ */
+export function useStackCard(): StackCardState {
+	const context = useStackCardContext();
+	if (!context) {
+		throw new Error("useStackCard must be called inside a <StackCard>.");
+	}
+	const { index, count, swipe, undo, canUndo } = context;
+	return { canUndo, count, index, swipe, undo };
+}
+
+/**
+ * The enclosing deck, for a part that cannot work without it.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useStackCardPart(component: string): StackCardContextValue {
+	const context = useStackCardContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <StackCard>.`);
+	}
+	return context;
+}
+
+export type StackCardSlotContextValue = {
+	/** This card's index in the deck. */
+	cardIndex: number;
+	/** Whether this card is the top one, as React last rendered it. */
+	isTop: boolean;
+};
+
+const StackCardSlotContext = createContext<StackCardSlotContextValue | null>(null);
+
+/** Tells a `StackCard.Card` which card it is. Internal. */
+export function StackCardSlotProvider({
+	value,
+	children,
+}: {
+	value: StackCardSlotContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <StackCardSlotContext value={value}>{children}</StackCardSlotContext>;
+}
+StackCardSlotProvider.displayName = "DelacourUI.StackCard.SlotProvider";
+
+/** Which card this is, or null for a `StackCard.Card` rendered outside a deck's pile. */
+export function useStackCardSlot(): StackCardSlotContextValue | null {
+	return use(StackCardSlotContext);
+}