@delacour/react-native-ui 0.4.1-alpha.20261020200151 → 0.4.1-alpha.20261021071622

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.4.1-alpha.20261020200151",
+	"version": "0.4.1-alpha.20261021071622",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",

package/src/components/badge/AGENTS.md

@@ -90,4 +90,6 @@ A compact label for status, category or count. Compound root plus `Badge.Label`,
 - **`material="etched"` squares the capsule and tints.** The root and the close button take
   `rounded-sm`; `soft` status fills become `bg-<status>/8` in light and `/16` in dark, written out
   per colour because Tailwind's scanner cannot see a built class. The material rides the badge
-  context so the close button follows the root.
+  context so the close button follows the root. `BADGE_MATERIALS` and `BadgeMaterial` are exported
+  from the index beside the other three axes — a public prop whose type a caller cannot name is half
+  an API.

package/src/components/badge/index.ts

@@ -4,9 +4,11 @@ export type { BadgeSlotProps } from "./badge.types";
 export {
 	BADGE_COLORS,
 	BADGE_FOREGROUND_TOKEN,
+	BADGE_MATERIALS,
 	BADGE_SIZES,
 	BADGE_VARIANTS,
 	type BadgeColor,
+	type BadgeMaterial,
 	type BadgeSize,
 	type BadgeVariant,
 	type BadgeVariantProps,

package/src/components/button/AGENTS.md

@@ -254,4 +254,5 @@ for a chunk that says something rather than doing something. An
   inset top edge at 16%); `secondary`, `tertiary` and `outline` take the light/dark edge
   (`shadow-etched dark:shadow-etched-dark`); `ghost`, `destructive` and `destructive-soft` stay flat
   — a ghost has no surface to lift and a signal colour does not take a second highlight. The press
-  scale is already 0.97. The tokens live in `tokens.css`.
+  scale is already 0.97. The tokens live in `tokens.css`. `BUTTON_MATERIALS` and `ButtonMaterial`
+  are exported from the index like every other axis.

package/src/components/button/index.ts

@@ -23,6 +23,7 @@ export {
 	BUTTON_GROUP_SEPARATOR_ORIENTATION,
 	BUTTON_ICON_SIZES,
 	BUTTON_LABEL_SIZES,
+	BUTTON_MATERIALS,
 	BUTTON_SIZES,
 	BUTTON_SPINNER_PLACEMENTS,
 	BUTTON_VARIANTS,
@@ -33,6 +34,7 @@ export {
 	type ButtonIconSize,
 	type ButtonLabelSize,
 	type ButtonLayout,
+	type ButtonMaterial,
 	type ButtonSize,
 	type ButtonSpinnerPlacement,
 	type ButtonVariant,

package/src/components/pressable/AGENTS.md

@@ -12,8 +12,8 @@ and only `onPress` and `onLongPress` cross back to JS.
 | --- | --- |
 | `index.ts` | → `@delacour/react-native-ui/pressable` |
 | `pressable.tsx` | The Gesture API primitive |
-| `pressable.variants.ts` | Shared feedback vocabulary, no RN imports |
-| `pressable.variants.test.ts` | Feedback, rest opacity, accessibility state and activation matrices |
+| `pressable.variants.ts` | Shared feedback vocabulary and screen-reader activation routing, no RN imports |
+| `pressable.variants.test.ts` | Feedback, rest opacity, accessibility state, activation and action-dispatch matrices |
 
 ## Design
 
@@ -71,6 +71,19 @@ and only `onPress` and `onLongPress` cross back to JS.
   `ProgressButton` — owns it on both platforms and the pressable wires nothing;
   a caller's own `onAccessibilityTap` wins the same way. A caller's other
   actions and its `onAccessibilityAction` are merged in, never replaced.
+- **TalkBack's long press is wired to `onLongPress` the same way.**
+  Double-tap-and-hold performs `ACTION_LONG_CLICK`, which React Native routes
+  only to a listed `longpress` action and otherwise drops into an empty
+  `View.performLongClick` — so on Android the pressable appends `longpress`
+  whenever there is an `onLongPress`. iOS gets no entry: VoiceOver's
+  double-tap-and-hold passes a held touch through, which the long-press gesture
+  already recognises, and a `longpress` entry would only become a rotor custom
+  action. A caller that lists `longpress` itself — `SelectionMode.Item`,
+  `Attachment` — owns it, as with `activate`. The dispatch is two pure functions
+  in `pressable.variants.ts`: `dispatchPressableAccessibilityAction` maps an
+  action name to its handler, and `invokePressableHandler` is the
+  `isPressableInteractive` gate every screen-reader path calls exactly once.
+  A gated control consumes both actions and fires neither.
   `Button`, `ListGroup.Item`, `Screen.Navbar.BackButton`, `Dialog.Close`,
   `BottomSheet.Close` and every other `Pressable` consumer inherit it.
   Verified on an iOS simulator with `AXPress` through Simulator.app's

package/src/components/pressable/pressable.tsx

@@ -18,6 +18,8 @@ import { useResolveClassNames } from "uniwind";
 import { composeRefs } from "../../lib/compose-refs";
 import { mergeProps } from "../../lib/merge-props";
 import {
+	dispatchPressableAccessibilityAction,
+	invokePressableHandler,
 	isPressableInteractive,
 	type PressableFeedback,
 	resolvePressableAccessibilityState,
@@ -142,8 +144,9 @@ export type PressableProps = Omit<ViewProps, "style"> & {
  *
  * A gesture only ever sees touches, so a screen reader's activation is wired
  * to `onPress` separately — `onAccessibilityTap` on iOS, an `activate` action on
- * Android — behind the same `disabled` / `busy` guard. See
- * `resolvePressableActivation`.
+ * Android — and TalkBack's long press to `onLongPress` through a `longpress`
+ * action, all behind the same `disabled` / `busy` guard. See
+ * `resolvePressableActivation` and `dispatchPressableAccessibilityAction`.
  */
 export function Pressable({
 	children,
@@ -220,26 +223,33 @@ export function Pressable({
 	const activation = resolvePressableActivation({
 		accessibilityActions,
 		hasAccessibilityTap: onAccessibilityTap !== undefined,
+		hasLongPress: onLongPress !== undefined,
 		hasPress: onPress !== undefined,
 		platform: Platform.OS,
 	});
-	const activate = () => {
-		if (interactive) onPress?.();
-	};
 	// Built once and spread last at both render sites, after `{...props}`, so a
 	// caller's actions and handlers are merged in here rather than replacing the
-	// activation the pressable adds. `activate` is consumed only when the
-	// pressable added it; every other action reaches the caller's handler.
+	// activation the pressable adds. `activate` and `longpress` are consumed only
+	// when the pressable added them; every other action reaches the caller's
+	// handler. Both paths share the gesture's `disabled` / `busy` guard.
 	const accessibilityWiring = {
 		accessibilityActions: activation.accessibilityActions,
 		onAccessibilityAction: (event: AccessibilityActionEvent) => {
-			if (activation.routesActivate && event.nativeEvent.actionName === "activate") {
-				activate();
-				return;
-			}
-			onAccessibilityAction?.(event);
+			const consumed = dispatchPressableAccessibilityAction({
+				actionName: event.nativeEvent.actionName,
+				activation,
+				busy,
+				disabled,
+				onLongPress,
+				onPress,
+			});
+			if (!consumed) onAccessibilityAction?.(event);
 		},
-		onAccessibilityTap: activation.wiresAccessibilityTap ? activate : onAccessibilityTap,
+		onAccessibilityTap: activation.wiresAccessibilityTap
+			? () => {
+					invokePressableHandler(onPress, { busy, disabled });
+				}
+			: onAccessibilityTap,
 	};
 
 	const content = asChild ? (

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

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
+	dispatchPressableAccessibilityAction,
+	invokePressableHandler,
 	isPressableInteractive,
 	PRESSABLE_FEEDBACK,
 	PRESSABLE_FEEDBACK_FALLBACK,
@@ -187,6 +189,7 @@ describe("resolvePressableActivation", () => {
 		expect(resolvePressableActivation({ hasAccessibilityTap: false, hasPress: true, platform: "ios" })).toEqual({
 			accessibilityActions: undefined,
 			routesActivate: false,
+			routesLongPress: false,
 			wiresAccessibilityTap: true,
 		});
 	});
@@ -213,6 +216,7 @@ describe("resolvePressableActivation", () => {
 		expect(resolved).toEqual({
 			accessibilityActions: [{ label: "Remove", name: "remove" }, { name: "activate" }],
 			routesActivate: true,
+			routesLongPress: false,
 			wiresAccessibilityTap: false,
 		});
 	});
@@ -234,7 +238,12 @@ describe("resolvePressableActivation", () => {
 					hasPress: true,
 					platform,
 				})
-			).toEqual({ accessibilityActions: actions, routesActivate: false, wiresAccessibilityTap: false });
+			).toEqual({
+				accessibilityActions: actions,
+				routesActivate: false,
+				routesLongPress: false,
+				wiresAccessibilityTap: false,
+			});
 		}
 	});
 
@@ -249,6 +258,7 @@ describe("resolvePressableActivation", () => {
 			expect(resolvePressableActivation({ hasAccessibilityTap: false, hasPress: false, platform })).toEqual({
 				accessibilityActions: undefined,
 				routesActivate: false,
+				routesLongPress: false,
 				wiresAccessibilityTap: false,
 			});
 		}
@@ -258,7 +268,176 @@ describe("resolvePressableActivation", () => {
 		expect(resolvePressableActivation({ hasAccessibilityTap: false, hasPress: true, platform: "web" })).toEqual({
 			accessibilityActions: undefined,
 			routesActivate: false,
+			routesLongPress: false,
+			wiresAccessibilityTap: false,
+		});
+	});
+
+	test("Android appends 'longpress' when there is an onLongPress, and routes it", () => {
+		expect(
+			resolvePressableActivation({
+				hasAccessibilityTap: false,
+				hasLongPress: true,
+				hasPress: true,
+				platform: "android",
+			})
+		).toEqual({
+			accessibilityActions: [{ name: "activate" }, { name: "longpress" }],
+			routesActivate: true,
+			routesLongPress: true,
+			wiresAccessibilityTap: false,
+		});
+	});
+
+	test("Android routes 'longpress' alone for a long-press-only pressable", () => {
+		expect(
+			resolvePressableActivation({
+				hasAccessibilityTap: false,
+				hasLongPress: true,
+				hasPress: false,
+				platform: "android",
+			})
+		).toEqual({
+			accessibilityActions: [{ name: "longpress" }],
+			routesActivate: false,
+			routesLongPress: true,
+			wiresAccessibilityTap: false,
+		});
+	});
+
+	test("a caller that lists 'longpress' owns it, and still gets 'activate' added", () => {
+		const resolved = resolvePressableActivation({
+			accessibilityActions: [{ label: "Start selecting", name: "longpress" }],
+			hasAccessibilityTap: false,
+			hasLongPress: true,
+			hasPress: true,
+			platform: "android",
+		});
+		expect(resolved).toEqual({
+			accessibilityActions: [{ label: "Start selecting", name: "longpress" }, { name: "activate" }],
+			routesActivate: true,
+			routesLongPress: false,
 			wiresAccessibilityTap: false,
 		});
 	});
+
+	test("iOS adds no 'longpress' entry — VoiceOver's double-tap-and-hold is a held touch the gesture sees", () => {
+		expect(
+			resolvePressableActivation({ hasAccessibilityTap: false, hasLongPress: true, hasPress: true, platform: "ios" })
+		).toEqual({
+			accessibilityActions: undefined,
+			routesActivate: false,
+			routesLongPress: false,
+			wiresAccessibilityTap: true,
+		});
+	});
+});
+
+describe("invokePressableHandler", () => {
+	test("fires the handler exactly once when interactive", () => {
+		let calls = 0;
+		expect(invokePressableHandler(() => calls++, { busy: false, disabled: false })).toBe(true);
+		expect(calls).toBe(1);
+	});
+
+	test("never fires when disabled or busy", () => {
+		let calls = 0;
+		const handler = () => calls++;
+		expect(invokePressableHandler(handler, { busy: false, disabled: true })).toBe(false);
+		expect(invokePressableHandler(handler, { busy: true, disabled: false })).toBe(false);
+		expect(invokePressableHandler(handler, { busy: true, disabled: true })).toBe(false);
+		expect(calls).toBe(0);
+	});
+
+	test("a missing handler is a no-op", () => {
+		expect(invokePressableHandler(undefined, { busy: false, disabled: false })).toBe(false);
+	});
+});
+
+describe("dispatchPressableAccessibilityAction", () => {
+	const routed = { routesActivate: true, routesLongPress: true };
+
+	function counters() {
+		const calls = { longPress: 0, press: 0 };
+		return {
+			calls,
+			onLongPress: () => {
+				calls.longPress++;
+			},
+			onPress: () => {
+				calls.press++;
+			},
+		};
+	}
+
+	test("'activate' fires onPress once and is consumed", () => {
+		const { calls, onLongPress, onPress } = counters();
+		const consumed = dispatchPressableAccessibilityAction({
+			actionName: "activate",
+			activation: routed,
+			busy: false,
+			disabled: false,
+			onLongPress,
+			onPress,
+		});
+		expect(consumed).toBe(true);
+		expect(calls).toEqual({ longPress: 0, press: 1 });
+	});
+
+	test("'longpress' fires onLongPress once, never onPress", () => {
+		const { calls, onLongPress, onPress } = counters();
+		const consumed = dispatchPressableAccessibilityAction({
+			actionName: "longpress",
+			activation: routed,
+			busy: false,
+			disabled: false,
+			onLongPress,
+			onPress,
+		});
+		expect(consumed).toBe(true);
+		expect(calls).toEqual({ longPress: 1, press: 0 });
+	});
+
+	test("a disabled or busy control consumes both actions and fires nothing", () => {
+		const { calls, onLongPress, onPress } = counters();
+		for (const gate of [
+			{ busy: false, disabled: true },
+			{ busy: true, disabled: false },
+		]) {
+			for (const actionName of ["activate", "longpress"]) {
+				expect(
+					dispatchPressableAccessibilityAction({ actionName, activation: routed, ...gate, onLongPress, onPress })
+				).toBe(true);
+			}
+		}
+		expect(calls).toEqual({ longPress: 0, press: 0 });
+	});
+
+	test("an action the pressable does not route is forwarded, untouched", () => {
+		const { calls, onLongPress, onPress } = counters();
+		const unrouted = { routesActivate: false, routesLongPress: false };
+		for (const actionName of ["activate", "longpress", "increment"]) {
+			expect(
+				dispatchPressableAccessibilityAction({
+					actionName,
+					activation: unrouted,
+					busy: false,
+					disabled: false,
+					onLongPress,
+					onPress,
+				})
+			).toBe(false);
+		}
+		expect(
+			dispatchPressableAccessibilityAction({
+				actionName: "increment",
+				activation: routed,
+				busy: false,
+				disabled: false,
+				onLongPress,
+				onPress,
+			})
+		).toBe(false);
+		expect(calls).toEqual({ longPress: 0, press: 0 });
+	});
 });

package/src/components/pressable/pressable.variants.ts

@@ -125,16 +125,19 @@ export function isPressableInteractive({ busy, disabled }: { busy: boolean; disa
 type PressableAccessibilityAction = { name: string; label?: string };
 
 export type PressableActivation<A extends PressableAccessibilityAction> = {
-	/** What the view's `accessibilityActions` becomes — the caller's own, plus `activate` on Android. */
-	accessibilityActions: ReadonlyArray<A | { name: "activate" }> | undefined;
+	/** What the view's `accessibilityActions` becomes — the caller's own, plus `activate` / `longpress` on Android. */
+	accessibilityActions: ReadonlyArray<A | { name: "activate" } | { name: "longpress" }> | undefined;
 	/** The pressable consumes `activate` in `onAccessibilityAction` and calls `onPress` itself. */
 	routesActivate: boolean;
+	/** The pressable consumes `longpress` in `onAccessibilityAction` and calls `onLongPress` itself. */
+	routesLongPress: boolean;
 	/** The pressable sets `onAccessibilityTap`, which is what VoiceOver's double-tap reaches. */
 	wiresAccessibilityTap: boolean;
 };
 
 /**
- * How a screen reader's activation reaches `onPress`.
+ * How a screen reader's activation reaches `onPress`, and its long press
+ * `onLongPress`.
  *
  * The press is a Gesture Handler tap, which only ever sees touches. Each
  * platform's activation is something else:
@@ -146,40 +149,54 @@ export type PressableActivation<A extends PressableAccessibilityAction> = {
  *   call return `YES`, which also stops UIKit synthesising the touch: one
  *   activation, one `onPress`. An `activate` entry in `accessibilityActions` is
  *   no use here: Fabric lists every entry as a rotor custom action, so it would
- *   add a literal "activate" to every button's rotor.
+ *   add a literal "activate" to every button's rotor. The same is true of
+ *   `longpress`, and VoiceOver needs none: double-tap-and-hold passes a held
+ *   touch through to the view, which the long-press gesture recognises.
  * - **Android.** A TalkBack double-tap performs `ACTION_CLICK`, which React
  *   Native routes to `onAccessibilityAction` only when `activate` is listed.
  *   Without it the click falls to `View.performClick`, with no listener behind
- *   it. React Native ignores `onAccessibilityTap` on Android.
+ *   it. Double-tap-and-hold performs `ACTION_LONG_CLICK`, which reaches
+ *   `onAccessibilityAction` only when `longpress` is listed and otherwise falls
+ *   to an equally empty `View.performLongClick`. React Native ignores
+ *   `onAccessibilityTap` on Android.
  *
  * A caller that lists `activate` itself owns it on both platforms — a
  * `NumberInput` stepper, a `Message`, a `FlipCard` — and the pressable wires
- * nothing, so the press cannot fire twice. A caller's own `onAccessibilityTap`
- * wins the same way. With no `onPress` there is nothing to reach.
+ * nothing for it, so the press cannot fire twice. `longpress` is owned the same
+ * way, by `SelectionMode.Item` and `Attachment`. A caller's own
+ * `onAccessibilityTap` wins too. With no handler there is nothing to reach.
  *
  * The `disabled` / `busy` guard is not decided here: activation stays wired on
- * a gated control and the handler checks `isPressableInteractive`, so a gated
- * control's double-tap is consumed and does nothing rather than falling back
- * to a synthesised touch.
+ * a gated control and the handler goes through `invokePressableHandler`, so a
+ * gated control's double-tap is consumed and does nothing rather than falling
+ * back to a synthesised touch.
  */
 export function resolvePressableActivation<A extends PressableAccessibilityAction>({
 	accessibilityActions,
 	hasAccessibilityTap,
+	hasLongPress = false,
 	hasPress,
 	platform,
 }: {
 	accessibilityActions?: ReadonlyArray<A>;
 	hasAccessibilityTap: boolean;
+	hasLongPress?: boolean;
 	hasPress: boolean;
 	platform: string;
 }): PressableActivation<A> {
-	const ownedByCaller = accessibilityActions?.some((action) => action.name === "activate") === true;
-	const wires = hasPress && !ownedByCaller;
+	const owns = (name: string) => accessibilityActions?.some((action) => action.name === name) === true;
+	const wiresPress = hasPress && !owns("activate");
+	const wiresLongPress = hasLongPress && !owns("longpress");
 
-	if (wires && platform === "android") {
+	if (platform === "android" && (wiresPress || wiresLongPress)) {
 		return {
-			accessibilityActions: [...(accessibilityActions ?? []), { name: "activate" }],
-			routesActivate: true,
+			accessibilityActions: [
+				...(accessibilityActions ?? []),
+				...(wiresPress ? [{ name: "activate" as const }] : []),
+				...(wiresLongPress ? [{ name: "longpress" as const }] : []),
+			],
+			routesActivate: wiresPress,
+			routesLongPress: wiresLongPress,
 			wiresAccessibilityTap: false,
 		};
 	}
@@ -187,6 +204,55 @@ export function resolvePressableActivation<A extends PressableAccessibilityActio
 	return {
 		accessibilityActions,
 		routesActivate: false,
-		wiresAccessibilityTap: wires && platform === "ios" && !hasAccessibilityTap,
+		routesLongPress: false,
+		wiresAccessibilityTap: wiresPress && platform === "ios" && !hasAccessibilityTap,
 	};
 }
+
+/**
+ * Calls a pressable's handler behind `isPressableInteractive` — the one call
+ * every screen-reader path makes, so a disabled or busy control can never be
+ * reached by one. Returns whether the handler ran. Exactly one call per
+ * invocation: nothing here retries, queues or re-dispatches.
+ */
+export function invokePressableHandler(
+	handler: (() => void) | undefined,
+	gate: { busy: boolean; disabled: boolean }
+): boolean {
+	if (!handler || !isPressableInteractive(gate)) return false;
+	handler();
+	return true;
+}
+
+/**
+ * Routes one `onAccessibilityAction` event. `activate` and `longpress` are
+ * consumed only when `resolvePressableActivation` added them — returning `true`
+ * whether or not the gate let the handler run, so a gated control swallows the
+ * action. Anything else returns `false` and belongs to the caller's own
+ * `onAccessibilityAction`.
+ */
+export function dispatchPressableAccessibilityAction({
+	actionName,
+	activation,
+	busy,
+	disabled,
+	onLongPress,
+	onPress,
+}: {
+	actionName: string;
+	activation: { routesActivate: boolean; routesLongPress: boolean };
+	busy: boolean;
+	disabled: boolean;
+	onLongPress?: () => void;
+	onPress?: () => void;
+}): boolean {
+	if (activation.routesActivate && actionName === "activate") {
+		invokePressableHandler(onPress, { busy, disabled });
+		return true;
+	}
+	if (activation.routesLongPress && actionName === "longpress") {
+		invokePressableHandler(onLongPress, { busy, disabled });
+		return true;
+	}
+	return false;
+}

package/src/components/screen/AGENTS.md

@@ -25,7 +25,7 @@ whole-screen states.
 | `screen-header.tsx` | `Screen.Header` |
 | `screen-footer.tsx` | `Screen.Footer` |
 | `screen-footer-background.tsx` | The footer's backing and its top hairline — internal |
-| `screen-scroll-shadow.tsx` | `Screen.ScrollShadow`, and `SCROLL_SHADOW_EDGES` |
+| `screen-scroll-shadow.tsx` | `Screen.ScrollShadow`, and its two axes — `SCROLL_SHADOW_EDGES` and `SCROLL_SHADOW_ANCHORS` |
 | `screen-scroll-area.tsx` | `Screen.ScrollArea` |
 | `screen-flat-list.tsx` | `Screen.FlatList` |
 | `screen-section-list.tsx` | `Screen.SectionList` |

package/src/components/screen/index.ts

@@ -65,8 +65,10 @@ export type { ScreenNavbarTitleProps } from "./screen-navbar-title";
 export type { ScreenRootProps } from "./screen-root";
 export type { ScreenScrollAreaProps } from "./screen-scroll-area";
 export {
+	SCROLL_SHADOW_ANCHORS,
 	SCROLL_SHADOW_EDGES,
 	ScreenScrollShadow,
+	type ScreenScrollShadowAnchor,
 	type ScreenScrollShadowEdge,
 	type ScreenScrollShadowProps,
 } from "./screen-scroll-shadow";

package/src/components/surface/AGENTS.md

@@ -80,3 +80,4 @@ components built on it (`Card`, `Alert`) can read the plane they sit on.
   down; `SurfaceContext.material` is how that panel knows to take `rounded-xl`, one step under the
   tray's corner. A single `shadow-*` utility sets one `box-shadow`, which is why light and dark are
   two tokens joined by `dark:` and not one composed class. Opt-in: nothing in the default look uses it.
+  `SURFACE_MATERIALS` and `SurfaceMaterial` are exported from the index like every other axis.

package/src/components/surface/index.ts

@@ -5,8 +5,10 @@ export {
 	resolveSurfaceVariant,
 	SURFACE_FILLED_VARIANTS,
 	SURFACE_FOREGROUND_TOKENS,
+	SURFACE_MATERIALS,
 	SURFACE_PADDINGS,
 	SURFACE_VARIANTS,
+	type SurfaceMaterial,
 	type SurfacePadding,
 	type SurfacePlane,
 	type SurfaceVariant,

package/src/components/text-animation/AGENTS.md

@@ -22,7 +22,7 @@ scope — it is an input, not a text effect.
 | `text-animation-caret.tsx` | Internal leaf: the typing caret |
 | `text-animation-clock.ts` | `useTextAnimationClock` — a frame-callback elapsed-ms shared value, pausable, keyed by run |
 | `text-animation.types.ts` | `TextAnimationBase`, the props every part shares |
-| `text-animation.variants.ts` | The slotted `tv()` + every pure resolver: splitting, stagger, effect frames, typing timeline, number format, roll targets |
+| `text-animation.variants.ts` | The slotted `tv()` + every pure resolver: splitting, stagger, effect frames, typing timeline, number format, roll targets — and the five axes (`TEXT_ANIMATION_UNITS`, `_ORDERS`, `_EFFECT_KINDS`, `_CARET_KINDS`, `_SLIDE_DIRECTIONS`), each exported with its union |
 | `text-animation.variants.test.ts` | |
 
 ## The root is Reveal

package/src/components/text-animation/index.ts

@@ -19,11 +19,15 @@ export {
 	TEXT_ANIMATION_CARET_KINDS,
 	TEXT_ANIMATION_EFFECT_KINDS,
 	TEXT_ANIMATION_ORDERS,
+	TEXT_ANIMATION_SLIDE_DIRECTIONS,
 	TEXT_ANIMATION_UNITS,
 	type TextAnimationCaret,
+	type TextAnimationCaretKind,
 	type TextAnimationEffect,
+	type TextAnimationEffectKind,
 	type TextAnimationNumberFormat,
 	type TextAnimationOrder,
+	type TextAnimationSlideFrom,
 	type TextAnimationTransition,
 	type TextAnimationUnit,
 	textAnimationVariants,

package/src/components/text-animation/text-animation.variants.test.ts

@@ -23,6 +23,7 @@ import {
 	splitText,
 	TEXT_ANIMATION_CARET_KINDS,
 	TEXT_ANIMATION_ORDERS,
+	TEXT_ANIMATION_SLIDE_DIRECTIONS,
 	TEXT_ANIMATION_UNITS,
 	textAnimationVariants,
 } from "./text-animation.variants";
@@ -205,6 +206,14 @@ describe("resolveEffectFrame", () => {
 		expect(resolveEffectFrame({ kind: "fade" }, 0)).toEqual({ opacity: 0, translateX: 0, translateY: 0, scale: 1 });
 	});
 
+	// The array is the public list of `from` values, so every entry must move the unit.
+	test("every slide direction starts off its rest position", () => {
+		for (const from of TEXT_ANIMATION_SLIDE_DIRECTIONS) {
+			const frame = resolveEffectFrame({ kind: "slide", from }, 0);
+			expect(Math.abs(frame.translateX) + Math.abs(frame.translateY)).toBe(12);
+		}
+	});
+
 	test("slide starts its distance away on the side it comes from", () => {
 		expect(resolveEffectFrame({ kind: "slide", from: "up" }, 0).translateY).toBe(-12);
 		expect(resolveEffectFrame({ kind: "slide", from: "down" }, 0).translateY).toBe(12);

package/src/components/text-animation/text-animation.variants.ts

@@ -5,6 +5,7 @@ export const TEXT_ANIMATION_UNITS = ["character", "word", "line"] as const;
 export const TEXT_ANIMATION_ORDERS = ["forward", "reverse", "center", "random"] as const;
 export const TEXT_ANIMATION_EFFECT_KINDS = ["fade", "slide", "scale"] as const;
 export const TEXT_ANIMATION_CARET_KINDS = ["none", "bar", "block"] as const;
+export const TEXT_ANIMATION_SLIDE_DIRECTIONS = ["up", "down", "left", "right"] as const;
 
 /** What one entering piece of a `Reveal` is. */
 export type TextAnimationUnit = (typeof TEXT_ANIMATION_UNITS)[number];
@@ -12,7 +13,8 @@ export type TextAnimationUnit = (typeof TEXT_ANIMATION_UNITS)[number];
 export type TextAnimationOrder = (typeof TEXT_ANIMATION_ORDERS)[number];
 export type TextAnimationEffectKind = (typeof TEXT_ANIMATION_EFFECT_KINDS)[number];
 export type TextAnimationCaretKind = (typeof TEXT_ANIMATION_CARET_KINDS)[number];
-export type TextAnimationSlideFrom = "up" | "down" | "left" | "right";
+/** Where a `slide` effect enters from. */
+export type TextAnimationSlideFrom = (typeof TEXT_ANIMATION_SLIDE_DIRECTIONS)[number];
 
 /** How a unit arrives. Every kind fades in; `slide` and `scale` add a transform on top. */
 export type TextAnimationEffect =

package/src/variant-axes.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const COMPONENTS = join(import.meta.dirname, "components");
+
+/**
+ * Every variant axis a component declares must reach its public entry point.
+ *
+ * An axis is a `const` array and the union read off it —
+ * `BADGE_MATERIALS` and `BadgeMaterial`. The union types a prop; the array is how
+ * a caller iterates the values, builds a picker or a story, or narrows a string
+ * from outside. `Badge`, `Button` and `Surface` each grew a public `material`
+ * prop whose pair stayed behind `index.ts`, so a caller could pass the prop but
+ * not name its type without reaching into a file the package does not export.
+ *
+ * Like `docs.test.ts`, this reads the tree as **text** and imports nothing from
+ * it: an axis is recognised by its declaration,
+ * `export type Name = (typeof NAME)[number]`, and both names must appear in the
+ * folder's `index.ts` export lists. Declaring an axis that way is declaring it
+ * public — an internal union is a plain string-literal type and is not checked.
+ */
+
+type Axis = { file: string; type: string; values: string };
+
+const AXIS = /^export type ([A-Za-z0-9_]+) = \(typeof ([A-Z0-9_]+)\)\[number\];/gm;
+
+/** Every component folder's non-test modules, as relative path → source. */
+function modules(folder: string): Map<string, string> {
+	const found = new Map<string, string>();
+	for (const entry of readdirSync(join(COMPONENTS, folder), { withFileTypes: true })) {
+		if (!entry.isFile() || !/\.tsx?$/.test(entry.name) || entry.name.includes(".test.")) continue;
+		if (entry.name === "index.ts") continue;
+		found.set(`${folder}/${entry.name}`, readFileSync(join(COMPONENTS, folder, entry.name), "utf-8"));
+	}
+	return found;
+}
+
+/** The axes one module declares. */
+function axesIn(file: string, source: string): Axis[] {
+	return [...source.matchAll(AXIS)].map(([, type, values]) => ({ file, type, values }));
+}
+
+/** Every name inside an `export { … }` or `export type { … }` list of an index. */
+function exportedNames(index: string): Set<string> {
+	const names = new Set<string>();
+	for (const [, list] of index.matchAll(/export (?:type )?\{([^}]*)\}/g)) {
+		for (const raw of list.split(",")) {
+			const name = raw
+				.trim()
+				.replace(/^type\s+/, "")
+				.split(/\s+as\s+/)
+				.pop();
+			if (name) names.add(name);
+		}
+	}
+	return names;
+}
+
+const FOLDERS = readdirSync(COMPONENTS, { withFileTypes: true })
+	.filter((entry) => entry.isDirectory())
+	.map((entry) => entry.name)
+	.sort();
+
+const AXES = FOLDERS.flatMap((folder) => {
+	const exported = exportedNames(readFileSync(join(COMPONENTS, folder, "index.ts"), "utf-8"));
+	return [...modules(folder)].flatMap(([file, source]) => axesIn(file, source).map((axis) => ({ ...axis, exported })));
+});
+
+describe("variant axes", () => {
+	// A matcher that found nothing would pass every assertion below on an empty set.
+	test("finds the axes", () => {
+		expect(AXES.length).toBeGreaterThan(50);
+	});
+
+	test("every axis union is exported from its component's index", () => {
+		const missing = AXES.filter((axis) => !axis.exported.has(axis.type)).map((axis) => `${axis.file}: ${axis.type}`);
+		expect(missing).toEqual([]);
+	});
+
+	test("every axis array is exported from its component's index", () => {
+		const missing = AXES.filter((axis) => !axis.exported.has(axis.values)).map(
+			(axis) => `${axis.file}: ${axis.values}`
+		);
+		expect(missing).toEqual([]);
+	});
+});