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

package/src/components/screen/screen-flat-list.tsx

@@ -0,0 +1,88 @@
+import { type ForwardedRef, forwardRef, type ReactElement, type RefAttributes, useMemo } from "react";
+import { FlatList, type FlatListProps, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { cn } from "../../lib/cn";
+import type { ScreenScrollableProps } from "./screen.types";
+import { screenVariants } from "./screen.variants";
+import { resolveListComponent } from "./screen-list-component";
+import { useScreenScrollInsets } from "./use-screen-scroll-insets";
+
+// `Animated.createAnimatedComponent` erases the generic parameters; the recast
+// puts them back so `data` and `renderItem` still check against each other.
+const AnimatedFlatList = Animated.createAnimatedComponent(FlatList) as unknown as typeof FlatList;
+
+export type ScreenFlatListProps<ItemT> = Omit<FlatListProps<ItemT>, "children"> & ScreenScrollableProps;
+
+/**
+ * The component's own type, restated so `<ItemT>` survives `forwardRef`.
+ *
+ * `forwardRef` erases type parameters — its result is a
+ * `ForwardRefExoticComponent` over one concrete instantiation — so `data` and
+ * `renderItem` would check against `unknown` and stop constraining each other.
+ * Writing the signature out is the same move `StyledAnimatedLegendListComponent`
+ * makes for `withUniwind` in `screen-legend-list`, and the `displayName` member
+ * is what keeps the trailing assignment legal after the cast.
+ */
+type ScreenFlatListComponent = (<ItemT>(
+	props: ScreenFlatListProps<ItemT> & RefAttributes<FlatList<ItemT>>
+) => ReactElement) & { displayName?: string };
+
+/**
+ * A virtualised list that keeps its content clear of the screen's chrome.
+ *
+ * The reserves ride on `ListHeaderComponent` / `ListFooterComponent` rather
+ * than on the content container's padding, because a virtualised list measures
+ * its own content and a padded container would put the spacer outside what it
+ * measures.
+ *
+ * A caller's own header and footer components still render — they are composed
+ * inside the screen's, not replaced by them.
+ *
+ * The ref is the list itself, for `scrollToIndex`, `scrollToOffset` and the rest.
+ */
+export const ScreenFlatList = forwardRef(function ScreenFlatListRender<ItemT>(
+	{
+		header,
+		contentContainerClassName,
+		ListHeaderComponent: ListHeaderComponentProp,
+		ListFooterComponent: ListFooterComponentProp,
+		...props
+	}: ScreenFlatListProps<ItemT>,
+	ref: ForwardedRef<FlatList<ItemT>>
+): ReactElement {
+	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets("standard");
+
+	const ListHeaderComponent = useMemo<ReactElement>(
+		() => (
+			<>
+				<Animated.View style={insetTopAnimatedStyle} />
+				{header}
+				{resolveListComponent(ListHeaderComponentProp)}
+			</>
+		),
+		[header, ListHeaderComponentProp, insetTopAnimatedStyle]
+	);
+
+	const ListFooterComponent = useMemo<ReactElement>(
+		() => (
+			<View>
+				{resolveListComponent(ListFooterComponentProp)}
+				<Animated.View style={insetBottomAnimatedStyle} />
+			</View>
+		),
+		[ListFooterComponentProp, insetBottomAnimatedStyle]
+	);
+
+	return (
+		<AnimatedFlatList
+			showsVerticalScrollIndicator={false}
+			{...props}
+			contentContainerClassName={cn(screenVariants().scrollContent(), contentContainerClassName)}
+			ListFooterComponent={ListFooterComponent}
+			ListHeaderComponent={ListHeaderComponent}
+			onScroll={scrollHandler}
+			ref={ref}
+		/>
+	);
+}) as unknown as ScreenFlatListComponent;
+ScreenFlatList.displayName = "DelacourUI.Screen.FlatList";

package/src/components/screen/screen-footer-background.tsx

@@ -0,0 +1,60 @@
+import { memo, type ReactElement } from "react";
+import { View } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { useScreenDebug, useScreenPart } from "./screen.context";
+import { resolveFooterBorderOpacity, type ScreenPlacement, screenVariants } from "./screen.variants";
+import { SCREEN_DEBUG_COLORS } from "./screen-debug";
+
+export type ScreenFooterBackgroundProps = {
+	placement: ScreenPlacement;
+	/** Fade the top hairline out as the content runs out, instead of drawing it at rest. */
+	fadeOnScroll?: boolean;
+};
+
+/**
+ * The footer's backing and its top hairline.
+ *
+ * Both are opaque only when the footer is `static`. A static footer is chrome:
+ * it takes its own space, and the content above must not show through when the
+ * keyboard lifts it. An `overlay` footer floats over content that deliberately
+ * scrolls under it, so it gets neither.
+ *
+ * Rendered INSIDE `KeyboardStickyView` so it travels with the translation. On
+ * the positioned outer view it would stay behind while the buttons moved.
+ *
+ * Separated from the footer itself because it reads `scrollY`, which changes
+ * every frame: memoised and isolated, the animated style re-runs on the UI
+ * thread without the footer's children re-rendering with it — the same reason
+ * `ScreenNavbarBackground` is its own component.
+ */
+export const ScreenFooterBackground = memo(function ScreenFooterBackground({
+	placement,
+	fadeOnScroll = false,
+}: ScreenFooterBackgroundProps): ReactElement {
+	const { scrollY, contentHeight, layoutHeight } = useScreenPart("Screen.Footer");
+	const debug = useScreenDebug();
+	const slots = screenVariants({ placement });
+
+	const borderStyle = useAnimatedStyle(
+		() => ({
+			opacity: resolveFooterBorderOpacity({
+				contentHeight: contentHeight.value,
+				fadeOnScroll,
+				layoutHeight: layoutHeight.value,
+				scrollY: scrollY.value,
+			}),
+		}),
+		[fadeOnScroll]
+	);
+
+	return (
+		<View
+			className={slots.footerBackground()}
+			pointerEvents="none"
+			style={debug ? { backgroundColor: SCREEN_DEBUG_COLORS.footerSticky } : undefined}
+		>
+			<Animated.View className={slots.footerBorder()} style={borderStyle} />
+		</View>
+	);
+});
+ScreenFooterBackground.displayName = "DelacourUI.Screen.Footer.Background";

package/src/components/screen/screen-footer.tsx

@@ -0,0 +1,170 @@
+import { type ReactElement, useCallback, useEffect, useRef, useState } from "react";
+import { type LayoutChangeEvent, View } from "react-native";
+import { KeyboardStickyView, useKeyboardState } from "react-native-keyboard-controller";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useKeyboardAnimationGuard } from "../../hooks/use-keyboard-state-sync";
+import { useScreenDebug, useScreenPart } from "./screen.context";
+import type { ScreenPlacementProps } from "./screen.types";
+import { SCREEN_FLOATING_BOTTOM_GAP, SCREEN_FOOTER_PADDING, screenVariants } from "./screen.variants";
+import { SCREEN_DEBUG_COLORS } from "./screen-debug";
+import { ScreenFooterBackground } from "./screen-footer-background";
+
+export type ScreenFooterProps = ScreenPlacementProps & {
+	/**
+	 * Ride the keyboard, so the footer stays directly above it. Off by default —
+	 * a footer holding a submit button wants to stay put, while one holding a
+	 * composer does not.
+	 */
+	sticky?: boolean;
+	/**
+	 * Fade the top hairline out as the content runs out, instead of drawing it at
+	 * rest.
+	 *
+	 * The mirror of `Screen.Navbar`'s `fadeBorderOnScroll`, and off by default
+	 * for the same reason: the line separates chrome from content, and content
+	 * sitting right against the footer wants it from the first frame. Turn it on
+	 * for a footer that should read as joined to the content once there is
+	 * nothing left to scroll to.
+	 *
+	 * Only applies to a `static` footer — an overlay one draws no hairline.
+	 *
+	 * @default false
+	 */
+	fadeBorderOnScroll?: boolean;
+	/**
+	 * Whether the enclosing screen is the focused one. Defaults to `true`.
+	 *
+	 * A sticky footer on a backgrounded screen would otherwise follow a keyboard
+	 * opened on the screen in front of it. This library takes no navigation
+	 * dependency, so an app that has one passes its own signal — expo-router and
+	 * React Navigation both expose `useIsFocused()`.
+	 */
+	isFocused?: boolean;
+};
+
+/**
+ * A pinned region at the bottom of a screen, optionally riding the keyboard.
+ *
+ * Measures its CONTENT height — excluding its own padding and the safe-area
+ * band — into the screen context, so a scrollable can reserve exactly what the
+ * footer covers. `footerOccupancy` in `screen.variants` adds the rest back; the
+ * two must agree, which is why the padding is applied from the same constants
+ * rather than as a class.
+ *
+ * The VERTICAL padding is a style rather than a class for that reason alone. A
+ * class is unreadable from JS, so the reserve would have to restate the number
+ * and the two could drift — the failure being a list whose last row hides under the
+ * footer only on some devices.
+ *
+ * Four nested boxes, each with one job:
+ * 1. the positioned outer view, which the caller's `className` reaches;
+ * 2. `KeyboardStickyView`, which translates and carries the footer's padding;
+ * 3. the backing and its top hairline, filling the sticky view behind the rest;
+ * 4. the measured content box, whose height reaches the screen context.
+ *
+ * The backing lives INSIDE the sticky view, not on the positioned outer one, so
+ * it travels with the translation. A static footer lifted over the content by
+ * the keyboard would otherwise let that content show straight through it — the
+ * buttons legible only where they happened to overlap blank space.
+ *
+ * The sticky view sits *inside* the positioned view rather than being it, so
+ * this file needs no `withUniwind` wrapper — it takes a `style` and never a
+ * `className`. See AGENTS.md rule 6.
+ *
+ * @example
+ * <Screen.Footer>
+ *   <Button onPress={save}>Save</Button>
+ * </Screen.Footer>
+ *
+ * @example
+ * <Screen.Footer sticky>
+ *   <MessageComposer />
+ * </Screen.Footer>
+ */
+export function ScreenFooter({
+	placement = "overlay",
+	sticky = false,
+	fadeBorderOnScroll = false,
+	isFocused = true,
+	className,
+	children,
+	style,
+	...props
+}: ScreenFooterProps): ReactElement {
+	const { footer } = useScreenPart("Screen.Footer");
+	const slots = screenVariants({ placement });
+	const { bottom } = useSafeAreaInsets();
+	const keyboardState = useKeyboardState();
+	const debug = useScreenDebug();
+	// The shared keyboard values are a global with no per-screen reset, so a
+	// footer can mount into a state left "open" by a keyboard that vanished
+	// without a `keyboardWillHide` — and then float a keyboard-height off the
+	// bottom of a screen with no keyboard on it. Repair on mount; a no-op
+	// whenever an input is genuinely focused, which is what keeps the
+	// `isKeyboardOpen` hand-off below working.
+	useKeyboardAnimationGuard();
+
+	// Sticking before the first measure would translate a zero-height box.
+	const [hasMeasured, setHasMeasured] = useState(false);
+	// A JS ref, never a SharedValue read in a memoized closure: React Compiler
+	// hoists such loads into memo-cache comparisons that run during render,
+	// which is a Reanimated strict-mode violation.
+	const hasCapturedBaselineRef = useRef(false);
+
+	// A screen navigated away from while its keyboard is still up has to keep
+	// reacting, or its footer snaps down behind the outgoing transition.
+	const isEnabled = sticky && hasMeasured && (isFocused || keyboardState.isVisible);
+
+	const handleContentLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const { height } = event.nativeEvent.layout;
+			setHasMeasured(true);
+			footer.height.value = height;
+			if (!hasCapturedBaselineRef.current) {
+				hasCapturedBaselineRef.current = true;
+				footer.initialHeight.value = height;
+			}
+		},
+		[footer]
+	);
+
+	useEffect(() => {
+		footer.placement.value = placement;
+	}, [placement, footer.placement]);
+
+	useEffect(() => {
+		return () => {
+			footer.height.value = 0;
+			footer.initialHeight.value = 0;
+			hasCapturedBaselineRef.current = false;
+		};
+	}, [footer.height, footer.initialHeight]);
+
+	return (
+		<View className={slots.footer({ className })} style={style} {...props}>
+			<KeyboardStickyView
+				enabled={isEnabled}
+				// Shift by the inset rather than animating the padding away: the
+				// footer's safe-area band is meaningless once the keyboard covers it,
+				// and animating padding leaves a visible gap between the two
+				// mid-transition.
+				offset={{ closed: 0, opened: bottom }}
+				style={{ paddingBottom: SCREEN_FLOATING_BOTTOM_GAP, paddingTop: SCREEN_FOOTER_PADDING }}
+			>
+				<ScreenFooterBackground fadeOnScroll={fadeBorderOnScroll} placement={placement} />
+				<View
+					style={[{ paddingBottom: bottom }, debug ? { backgroundColor: SCREEN_DEBUG_COLORS.footerSafeArea } : null]}
+				>
+					<View
+						className={slots.footerContent()}
+						onLayout={handleContentLayout}
+						style={debug ? { backgroundColor: SCREEN_DEBUG_COLORS.footerContent } : undefined}
+					>
+						{children}
+					</View>
+				</View>
+			</KeyboardStickyView>
+		</View>
+	);
+}
+ScreenFooter.displayName = "DelacourUI.Screen.Footer";

package/src/components/screen/screen-header.tsx

@@ -0,0 +1,36 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import type { ScreenInsetProps } from "./screen.types";
+import { resolveScreenEdgePadding, screenVariants } from "./screen.variants";
+
+export type ScreenHeaderProps = ScreenInsetProps;
+
+/**
+ * A titled block at the top of a screen's content.
+ *
+ * Carries no gutter and no vertical padding: the scrollable it sits in already
+ * has both, and a header adding its own would double them at every call site.
+ * What is left is a semantic block with its own `gap-1` and optional safe-area
+ * insets.
+ *
+ * Two nested views rather than one: the safe-area padding and anything the
+ * caller adds are different concerns, and collapsing them would make
+ * `insets={["top"]}` silently replace that padding instead of adding to it —
+ * the failure the rest of this component was fixed for.
+ *
+ * Scrolls with the content — it is passed to a scrollable's `header` prop, not
+ * pinned. `Screen.Navbar` is the pinned one.
+ */
+export function ScreenHeader({ insets, className, children, style, ...props }: ScreenHeaderProps): ReactElement {
+	const safeArea = useSafeAreaInsets();
+
+	return (
+		<View style={resolveScreenEdgePadding(insets, safeArea)}>
+			<View className={screenVariants().header({ className })} style={style} {...props}>
+				{children}
+			</View>
+		</View>
+	);
+}
+ScreenHeader.displayName = "DelacourUI.Screen.Header";

package/src/components/screen/screen-legend-list.tsx

@@ -0,0 +1,105 @@
+import type { LegendListRef } from "@legendapp/list/react-native";
+import { AnimatedLegendList, type AnimatedLegendListProps } from "@legendapp/list/reanimated";
+import { type ForwardedRef, forwardRef, type ReactElement, type Ref, type RefAttributes, useMemo } from "react";
+import { View } from "react-native";
+import Animated from "react-native-reanimated";
+import { withUniwind } from "uniwind";
+import { cn } from "../../lib/cn";
+import type { ScreenScrollableProps } from "./screen.types";
+import { screenVariants } from "./screen.variants";
+import { resolveListComponent } from "./screen-list-component";
+import { useScreenScrollInsets } from "./use-screen-scroll-insets";
+
+/**
+ * The class props `withUniwind` adds, restated so the generic survives.
+ *
+ * `withUniwind`'s own return type maps over a component's props and collapses
+ * `<ItemT>` in the process, which would leave `data` and `renderItem` checking
+ * against `unknown`. Writing the signature out keeps inference and still
+ * declares exactly the two props the wrapper adds.
+ */
+type StyledAnimatedLegendListComponent = <ItemT>(
+	props: AnimatedLegendListProps<ItemT> & {
+		ref?: Ref<LegendListRef>;
+		className?: string;
+		contentContainerClassName?: string;
+	}
+) => ReactElement | null;
+
+// Third-party, so `className` needs the wrapper — and it has to be built at
+// module scope or every render mints a new component type and remounts the list.
+const StyledAnimatedLegendList = withUniwind(AnimatedLegendList) as unknown as StyledAnimatedLegendListComponent;
+
+export type ScreenLegendListProps<ItemT> = Omit<AnimatedLegendListProps<ItemT>, "renderScrollComponent"> &
+	ScreenScrollableProps;
+
+/**
+ * The component's own type, restated so `<ItemT>` survives `forwardRef`.
+ *
+ * Same reasoning as `StyledAnimatedLegendListComponent` above, one layer out:
+ * `forwardRef` erases type parameters, so `data` and `renderItem` would check
+ * against `unknown`.
+ */
+type ScreenLegendListComponent = (<ItemT>(
+	props: ScreenLegendListProps<ItemT> & RefAttributes<LegendListRef>
+) => ReactElement) & { displayName?: string };
+
+/**
+ * A recycling list that keeps its content clear of the screen's chrome.
+ *
+ * `Screen.FlatList`'s behaviour on LegendList's recycling engine, for a long or
+ * heterogeneous list. Same navbar, footer and keyboard reserves — they come
+ * from the shared `useScreenScrollInsets`, so the three lists cannot drift.
+ *
+ * For a chat, reach for `Screen.ChatList` instead: it adds the composer
+ * clearance and the keyboard lift that a conversation needs and this one has no
+ * opinion about.
+ *
+ * The ref is a `LegendListRef`.
+ */
+export const ScreenLegendList = forwardRef(function ScreenLegendListRender<ItemT>(
+	{
+		header,
+		contentContainerClassName,
+		ListHeaderComponent: ListHeaderComponentProp,
+		ListFooterComponent: ListFooterComponentProp,
+		...props
+	}: ScreenLegendListProps<ItemT>,
+	ref: ForwardedRef<LegendListRef>
+): ReactElement {
+	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets("standard");
+
+	const ListHeaderComponent = useMemo<ReactElement>(
+		() => (
+			<>
+				<Animated.View style={insetTopAnimatedStyle} />
+				{header}
+				{resolveListComponent(ListHeaderComponentProp)}
+			</>
+		),
+		[header, ListHeaderComponentProp, insetTopAnimatedStyle]
+	);
+
+	const ListFooterComponent = useMemo<ReactElement>(
+		() => (
+			<View>
+				{resolveListComponent(ListFooterComponentProp)}
+				<Animated.View style={insetBottomAnimatedStyle} />
+			</View>
+		),
+		[ListFooterComponentProp, insetBottomAnimatedStyle]
+	);
+
+	return (
+		<StyledAnimatedLegendList
+			showsVerticalScrollIndicator={false}
+			{...(props as AnimatedLegendListProps<ItemT>)}
+			contentContainerClassName={cn(screenVariants().scrollContent(), contentContainerClassName)}
+			ListFooterComponent={ListFooterComponent}
+			ListHeaderComponent={ListHeaderComponent}
+			onScroll={scrollHandler}
+			ref={ref}
+		/>
+	);
+}) as unknown as ScreenLegendListComponent;
+ScreenLegendList.displayName = "DelacourUI.Screen.LegendList";

package/src/components/screen/screen-list-component.tsx

@@ -0,0 +1,23 @@
+import { type ComponentType, isValidElement, type ReactElement, type ReactNode } from "react";
+
+/** What React Native's lists accept for `ListHeaderComponent` / `ListFooterComponent`. */
+export type ListComponent = ComponentType<unknown> | ReactElement | null | undefined;
+
+/**
+ * Renders a list's header or footer prop as a node, whichever form it took.
+ *
+ * React Native accepts a component type *or* an element for these props, and a
+ * Screen scrollable has to compose the caller's into its own spacers — which
+ * only works with a node. Calling a component type as a function would break
+ * its hooks, so it is rendered as an element instead.
+ *
+ * Shared by every Screen list, so it lives in a leaf of its own rather than in
+ * whichever list happened to need it first.
+ */
+export function resolveListComponent(component: ListComponent): ReactNode {
+	if (component == null) return null;
+	if (isValidElement(component)) return component;
+
+	const Component = component as ComponentType<unknown>;
+	return <Component />;
+}

package/src/components/screen/screen-loading.tsx

@@ -0,0 +1,50 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import { Spinner } from "../spinner";
+import { screenVariants } from "./screen.variants";
+import { ScreenContent } from "./screen-content";
+import { ScreenNavbar } from "./screen-navbar";
+import { ScreenRoot } from "./screen-root";
+
+export type ScreenLoadingProps = {
+	/** Title for the navbar, if the screen shows one. */
+	title?: string;
+	/** Back handler. Omit it and the navbar renders without a back control. */
+	onBack?: () => void;
+	/** Show the navbar at all. On by default, so the frame does not shift when the content arrives. */
+	showNavbar?: boolean;
+};
+
+/**
+ * A whole screen showing a spinner — the placeholder a route renders while its
+ * data is in flight.
+ *
+ * Keeps the navbar by default so the frame does not jump when the real content
+ * replaces it, and so the user can still go back out of a slow load.
+ *
+ * @example
+ * if (isPending) return <Screen.Loading onBack={() => router.back()} title="Settings" />;
+ */
+export function ScreenLoading({ title, onBack, showNavbar = true }: ScreenLoadingProps): ReactElement {
+	return (
+		<ScreenRoot>
+			{showNavbar ? (
+				<ScreenNavbar>
+					{onBack ? (
+						<ScreenNavbar.BackButton onPress={onBack}>
+							{title ? <ScreenNavbar.Title>{title}</ScreenNavbar.Title> : null}
+						</ScreenNavbar.BackButton>
+					) : title ? (
+						<ScreenNavbar.Title>{title}</ScreenNavbar.Title>
+					) : null}
+				</ScreenNavbar>
+			) : null}
+			<ScreenContent>
+				<View className={screenVariants().loading()}>
+					<Spinner size="xl" />
+				</View>
+			</ScreenContent>
+		</ScreenRoot>
+	);
+}
+ScreenLoading.displayName = "DelacourUI.Screen.Loading";

package/src/components/screen/screen-navbar-back-button.tsx

@@ -0,0 +1,79 @@
+import type { ReactElement } from "react";
+import { IconChevronLeft, IconCrossSmall } from "../../icons/central";
+import { Icon, IconDefaultsProvider } from "../icon";
+import { Pressable, type PressableProps } from "../pressable";
+import { screenVariants } from "./screen.variants";
+
+/** Which affordance the control reads as: going back, or closing a modal. */
+export const SCREEN_BACK_BUTTON_GLYPHS = ["chevron", "close"] as const;
+
+export type ScreenBackButtonGlyph = (typeof SCREEN_BACK_BUTTON_GLYPHS)[number];
+
+export type ScreenNavbarBackButtonProps = Omit<PressableProps, "onPress"> & {
+	/** `chevron` for a push, `close` for a modal. */
+	glyph?: ScreenBackButtonGlyph;
+	/**
+	 * What going back does. Required: this library takes no navigation
+	 * dependency, so the screen wires its own router — `() => router.back()`.
+	 */
+	onPress: () => void;
+	/**
+	 * Runs before `onPress`. Returning `false` cancels the navigation, for an
+	 * unsaved-changes prompt.
+	 */
+	onBeforeBack?: () => boolean;
+};
+
+const GLYPH: Record<ScreenBackButtonGlyph, typeof IconChevronLeft> = {
+	chevron: IconChevronLeft,
+	close: IconCrossSmall,
+};
+
+/**
+ * The navbar's leading control.
+ *
+ * Takes an `onPress` rather than calling a router itself. `native-ui` has no
+ * navigation dependency and should not gain one for a chevron — the screen
+ * already knows how it was pushed, and an app on a different router still gets
+ * to use this.
+ *
+ * Children render beside the glyph, so a title can share the control's tap
+ * target — which is what makes the whole "‹ Settings" row pressable rather than
+ * just the chevron.
+ *
+ * @example
+ * <Screen.Navbar.BackButton onPress={() => router.back()}>
+ *   <Screen.Navbar.Title>Settings</Screen.Navbar.Title>
+ * </Screen.Navbar.BackButton>
+ */
+export function ScreenNavbarBackButton({
+	glyph = "chevron",
+	onPress,
+	onBeforeBack,
+	className,
+	children,
+	accessibilityLabel = "Back",
+	...props
+}: ScreenNavbarBackButtonProps): ReactElement {
+	function handlePress(): void {
+		if (onBeforeBack && !onBeforeBack()) return;
+		onPress();
+	}
+
+	return (
+		<Pressable
+			accessibilityLabel={accessibilityLabel}
+			accessibilityRole="button"
+			className={screenVariants().backButton({ className })}
+			feedback="fade"
+			onPress={handlePress}
+			{...props}
+		>
+			<IconDefaultsProvider value={{ className: "size-icon-lg", color: "foreground" }}>
+				<Icon icon={GLYPH[glyph]} />
+				{children}
+			</IconDefaultsProvider>
+		</Pressable>
+	);
+}
+ScreenNavbarBackButton.displayName = "DelacourUI.Screen.Navbar.BackButton";

package/src/components/screen/screen-navbar-background.tsx

@@ -0,0 +1,45 @@
+import { memo, type ReactElement } from "react";
+import { View } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { useScreenPart } from "./screen.context";
+import { resolveNavbarBorderOpacity, screenVariants } from "./screen.variants";
+
+export type ScreenNavbarBackgroundProps = {
+	className?: string;
+	/** Ramp the hairline in as the screen scrolls instead of drawing it at rest. */
+	fadeOnScroll?: boolean;
+};
+
+/**
+ * The navbar's opaque backing, and its bottom hairline.
+ *
+ * Separated from the navbar itself because it reads `scrollY`, which changes
+ * every frame: memoised and isolated, the animated style re-runs on the UI
+ * thread without the navbar's children re-rendering with it.
+ *
+ * The line is drawn at rest by default. `fadeOnScroll` ramps it in over the
+ * first {@link SCREEN_BORDER_FADE_DISTANCE} points instead, for a header
+ * that should read as undivided until the content moves.
+ *
+ * The fill is a CLASS rather than an inline style. An inline `backgroundColor`
+ * beats the style uniwind resolves from a className, which is what would make a
+ * caller's `backgroundClassName` silently inert.
+ */
+export const ScreenNavbarBackground = memo(function ScreenNavbarBackground({
+	className,
+	fadeOnScroll = false,
+}: ScreenNavbarBackgroundProps): ReactElement {
+	const { scrollY } = useScreenPart("Screen.Navbar");
+
+	const borderStyle = useAnimatedStyle(
+		() => ({ opacity: resolveNavbarBorderOpacity(scrollY.value, fadeOnScroll) }),
+		[fadeOnScroll]
+	);
+
+	return (
+		<View className={screenVariants().navbarBackground({ className })} pointerEvents="none">
+			<Animated.View className={screenVariants().navbarBorder()} style={borderStyle} />
+		</View>
+	);
+});
+ScreenNavbarBackground.displayName = "DelacourUI.Screen.Navbar.Background";