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

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

@@ -0,0 +1,59 @@
+import type { ReactElement, ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import Animated, { useAnimatedStyle } from "react-native-reanimated";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useScreenPart } from "./screen.context";
+import { resolveScreenViewPadding, screenVariants } from "./screen.variants";
+
+export type ScreenViewProps = ViewProps & {
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * A non-scrolling container that keeps its content clear of the screen's chrome.
+ *
+ * Two nested boxes, and the split is the whole point: the measured chrome
+ * clearance is an inline style on the OUTER one, the caller's `className` and
+ * `style` go on the inner one. On a single box they would not stack — uniwind
+ * puts a class's style first and the `style` prop second, and Yoga resolves a
+ * longhand `paddingTop` ahead of the `padding` a class compiles to — so
+ * `<Screen.View className="p-5">` kept its left and right padding and silently
+ * lost its top and bottom. Nested, they add, which is what a caller means.
+ *
+ * The padding is an animated style rather than a class because both numbers are
+ * measured at runtime — an overlay navbar and footer publish their heights into
+ * the screen context, and reading them on the UI thread means the padding lands
+ * in the same frame as the measurement instead of a re-render later.
+ *
+ * With nothing mounted on an edge it falls back to the raw safe-area inset, so
+ * a screen with no navbar still clears the notch. A `static` navbar or footer
+ * contributes nothing here: it already took its space in the flow.
+ *
+ * Use `Screen.ScrollArea` when the content can overflow — this one cannot
+ * scroll, so content taller than the viewport is simply clipped.
+ */
+export function ScreenView({ className, style, children, ...props }: ScreenViewProps): ReactElement {
+	const { navbar, footer } = useScreenPart("Screen.View");
+	const { top, bottom } = useSafeAreaInsets();
+
+	const animatedStyle = useAnimatedStyle(() => {
+		return resolveScreenViewPadding({
+			footerHeight: footer.height.value,
+			footerPlacement: footer.placement.value,
+			navbarHeight: navbar.height.value,
+			navbarPlacement: navbar.placement.value,
+			safeAreaBottom: bottom,
+			safeAreaTop: top,
+		});
+	}, [top, bottom]);
+
+	return (
+		<Animated.View className="flex-1" style={animatedStyle}>
+			<View className={screenVariants().view({ className })} style={style} {...props}>
+				{children}
+			</View>
+		</Animated.View>
+	);
+}
+ScreenView.displayName = "DelacourUI.Screen.View";

package/src/components/screen/screen.context.tsx

@@ -0,0 +1,167 @@
+import { createContext, type ReactElement, type ReactNode, use, useMemo } from "react";
+import { type SharedValue, useSharedValue } from "react-native-reanimated";
+import type { ScreenPlacement } from "./screen.variants";
+
+/** What a navbar publishes about itself, for anything that has to clear it. */
+export type ScreenNavbarMeasurements = {
+	/** Whether the navbar overlays the content or sits in the flow above it. */
+	placement: SharedValue<ScreenPlacement>;
+	/** Measured height including the safe-area band, or 0 with no navbar mounted. */
+	height: SharedValue<number>;
+};
+
+/** What a footer publishes about itself, for anything that has to clear it. */
+export type ScreenFooterMeasurements = {
+	/** Whether the footer overlays the content or sits in the flow below it. */
+	placement: SharedValue<ScreenPlacement>;
+	/** Content height only — excludes the footer's own padding and safe-area band. */
+	height: SharedValue<number>;
+	/**
+	 * First measured content height — the collapsed baseline; 0 until the footer
+	 * mounts. Lets a consumer split the live height into base plus growth.
+	 */
+	initialHeight: SharedValue<number>;
+	/**
+	 * Extra VISUAL height overlaying above the measured footer layout — a
+	 * composer pill that expands upward without changing its layout box, say.
+	 *
+	 * Driven as a pure UI-thread animation by the footer's own content (see
+	 * `useScreenFooterOverlayHeight`) so a scrollable can offset for it in the
+	 * same frame as the keyboard. Never measured via `onLayout`: a layout pass
+	 * lands a frame late, which reads as the list lagging the keyboard.
+	 *
+	 * The footer resets `height` and `initialHeight` when it unmounts but never
+	 * this — whoever drives it owns clearing it.
+	 */
+	overlayHeight: SharedValue<number>;
+};
+
+/** Everything a screen's parts share, all of it readable from the UI thread. */
+export type ScreenContextValue = {
+	navbar: ScreenNavbarMeasurements;
+	footer: ScreenFooterMeasurements;
+	/** Live scroll offset of whichever scrollable the screen holds. */
+	scrollY: SharedValue<number>;
+	/** Content height of that scrollable. */
+	contentHeight: SharedValue<number>;
+	/** Viewport height of that scrollable. */
+	layoutHeight: SharedValue<number>;
+	/** Paint the screen's layout layers in debug colours. */
+	debug: boolean;
+};
+
+const ScreenContext = createContext<ScreenContextValue | null>(null);
+
+export type ScreenProviderProps = {
+	/**
+	 * An enclosing screen's context. When present it is passed straight through
+	 * rather than shadowed, so a nested `<Screen>` — which `Screen.Loading` and
+	 * `Screen.Error` both produce — keeps reporting to the outer screen's navbar
+	 * and footer measurements instead of starting a second, unread set.
+	 */
+	parentContext?: ScreenContextValue | null;
+	/** Paint the screen's layout layers in debug colours. */
+	debug?: boolean;
+	children: ReactNode;
+};
+
+/**
+ * Creates the shared values a screen's parts measure themselves into.
+ *
+ * Every value is a Reanimated `SharedValue` rather than React state: a navbar's
+ * height reaching a scrollable's inset through a re-render would land a frame
+ * or two after the layout that produced it, and the content would visibly jump
+ * into place. On the UI thread the two happen together.
+ *
+ * Lives in its own module, importing nothing but `screen.variants`, so a part
+ * can read the context without importing `../screen` and closing a cycle
+ * through `screen.tsx`. See AGENTS.md rule 3.
+ */
+export function ScreenProvider({ parentContext = null, debug = false, children }: ScreenProviderProps): ReactElement {
+	const navbarPlacement = useSharedValue<ScreenPlacement>("overlay");
+	const navbarHeight = useSharedValue<number>(0);
+
+	const footerPlacement = useSharedValue<ScreenPlacement>("overlay");
+	const footerHeight = useSharedValue<number>(0);
+	const footerInitialHeight = useSharedValue<number>(0);
+	const footerOverlayHeight = useSharedValue<number>(0);
+
+	const scrollY = useSharedValue<number>(0);
+	const contentHeight = useSharedValue<number>(0);
+	const layoutHeight = useSharedValue<number>(0);
+
+	const value = useMemo<ScreenContextValue>(() => {
+		if (parentContext) return parentContext;
+
+		return {
+			navbar: { placement: navbarPlacement, height: navbarHeight },
+			footer: {
+				placement: footerPlacement,
+				height: footerHeight,
+				initialHeight: footerInitialHeight,
+				overlayHeight: footerOverlayHeight,
+			},
+			scrollY,
+			contentHeight,
+			layoutHeight,
+			debug,
+		};
+	}, [
+		parentContext,
+		navbarPlacement,
+		navbarHeight,
+		footerPlacement,
+		footerHeight,
+		footerInitialHeight,
+		footerOverlayHeight,
+		scrollY,
+		contentHeight,
+		layoutHeight,
+		debug,
+	]);
+
+	return <ScreenContext value={value}>{children}</ScreenContext>;
+}
+ScreenProvider.displayName = "DelacourUI.Screen.Provider";
+
+/** The enclosing screen's context, or null outside a `<Screen>`. */
+export function useScreenContext(): ScreenContextValue | null {
+	return use(ScreenContext);
+}
+
+/**
+ * Reads the enclosing screen's navbar and footer measurements.
+ *
+ * Lets a custom scrollable or a footer's own content clear the screen's chrome
+ * without the screen having to pass heights down through every slot. Throws
+ * outside a `<Screen>` — use {@link useScreenContext} where the enclosing
+ * screen is optional.
+ */
+export function useScreen(): ScreenContextValue {
+	const context = useScreenContext();
+	if (!context) {
+		throw new Error("useScreen must be called inside a <Screen>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing screen'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 useScreen}, whose error message names the hook rather
+ * than a part.
+ */
+export function useScreenPart(component: string): ScreenContextValue {
+	const context = useScreenContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Screen>.`);
+	}
+	return context;
+}
+
+/** Whether the enclosing screen has layout debugging turned on. */
+export function useScreenDebug(): boolean {
+	return useScreenContext()?.debug ?? false;
+}

package/src/components/screen/screen.tsx

@@ -0,0 +1,114 @@
+import { ScreenChatList } from "./screen-chat-list";
+import { ScreenContent } from "./screen-content";
+import { ScreenError } from "./screen-error";
+import { ScreenFlatList } from "./screen-flat-list";
+import { ScreenFooter } from "./screen-footer";
+import { ScreenHeader } from "./screen-header";
+import { ScreenLegendList } from "./screen-legend-list";
+import { ScreenLoading } from "./screen-loading";
+import { ScreenNavbar } from "./screen-navbar";
+import { ScreenRoot } from "./screen-root";
+import { ScreenScrollArea } from "./screen-scroll-area";
+import { ScreenScrollShadow } from "./screen-scroll-shadow";
+import { ScreenSectionList } from "./screen-section-list";
+import { ScreenView } from "./screen-view";
+
+/**
+ * A screen's frame: pinned chrome, a content region, and whatever scrolls
+ * between them.
+ *
+ * The problem it solves is that a navbar and a footer only know their own
+ * heights once they have laid out, and everything else on the screen has to
+ * clear them. Each publishes its measured height into a Reanimated context, and
+ * every scrollable reserves exactly that — so no screen carries a hand-tuned
+ * padding number that is right on one device and wrong on the next.
+ *
+ * Compose the parts in visual order. The navbar and footer default to
+ * `placement="overlay"`, floating above the content with the content insetting
+ * itself to match; `placement="static"` puts either in the flow instead.
+ *
+ * Requires `DelacourProvider` at the app's root — it mounts the safe-area
+ * provider, the keyboard provider and the `<KeyboardStateSync />` a screen
+ * depends on. Compose those by hand only in an app that already has a root
+ * stack of its own, and keep the state sync: without it a keyboard that
+ * vanishes without notice leaves every screen in the app believing it is still
+ * open.
+ *
+ * @example
+ * // Navbar, scrolling body and a footer action.
+ * <Screen>
+ *   <Screen.Navbar>
+ *     <Screen.Navbar.BackButton onPress={() => router.back()}>
+ *       <Screen.Navbar.Title>Settings</Screen.Navbar.Title>
+ *     </Screen.Navbar.BackButton>
+ *   </Screen.Navbar>
+ *   <Screen.ScrollArea contentContainerClassName="gap-4 px-5">
+ *     <Screen.Header>
+ *       <Text.Header>Notifications</Text.Header>
+ *     </Screen.Header>
+ *     {rows}
+ *   </Screen.ScrollArea>
+ *   <Screen.Footer>
+ *     <Button onPress={save}>Save</Button>
+ *   </Screen.Footer>
+ * </Screen>
+ *
+ * @example
+ * // A form: the focused field stays clear of the keyboard and the footer.
+ * <Screen>
+ *   <Screen.Navbar placement="static" center={<Screen.Navbar.Title>New customer</Screen.Navbar.Title>} />
+ *   <Screen.ScrollArea keyboardAware contentContainerClassName="gap-4 px-5">
+ *     <CustomerForm />
+ *   </Screen.ScrollArea>
+ * </Screen>
+ *
+ * @example
+ * // Static content, no scrolling — padded for whatever chrome is mounted.
+ * <Screen>
+ *   <Screen.Navbar />
+ *   <Screen.View className="items-center justify-center">
+ *     <Text>Nothing here yet</Text>
+ *   </Screen.View>
+ * </Screen>
+ *
+ * @example
+ * // A conversation: composer rides the keyboard, newest message stays clear of it.
+ * <Screen>
+ *   <Screen.Navbar placement="static" />
+ *   <Screen.Content textInputNativeID={SCREEN_CHAT_INPUT_NATIVE_ID}>
+ *     <Screen.ChatList composerBaseHeight={56} data={messages} renderItem={renderMessage} />
+ *   </Screen.Content>
+ *   <Screen.Footer sticky>
+ *     <MessageComposer textInputNativeID={SCREEN_CHAT_INPUT_NATIVE_ID} />
+ *   </Screen.Footer>
+ * </Screen>
+ */
+export const Screen = Object.assign(ScreenRoot, {
+	/** The bar pinned to the top, with its `Title`, `Subtitle` and `BackButton` slots. */
+	Navbar: ScreenNavbar,
+	/** The content region: keyboard gesture area, surface, and optional safe-area edges. */
+	Content: ScreenContent,
+	/** A non-scrolling body, padded for whatever chrome is mounted. */
+	View: ScreenView,
+	/** A titled block on the screen's own gutter, scrolling with the content. */
+	Header: ScreenHeader,
+	/** A pinned region at the bottom, optionally riding the keyboard. */
+	Footer: ScreenFooter,
+	/** A scrolling body that clears the chrome at both ends. */
+	ScrollArea: ScreenScrollArea,
+	/** A fade at each end of whichever body is mounted, for content that runs past it. */
+	ScrollShadow: ScreenScrollShadow,
+	/** A virtualised list that clears the chrome at both ends. */
+	FlatList: ScreenFlatList,
+	/** A sectioned virtualised list, with sticky section headers. */
+	SectionList: ScreenSectionList,
+	/** A recycling list, for a long or heterogeneous body. */
+	LegendList: ScreenLegendList,
+	/** A conversation list: composer clearance, keyboard lift and end anchoring. */
+	ChatList: ScreenChatList,
+	/** A whole screen showing a spinner, for a route whose data is in flight. */
+	Loading: ScreenLoading,
+	/** A whole screen explaining that something failed. */
+	Error: ScreenError,
+	displayName: "DelacourUI.Screen",
+});

package/src/components/screen/screen.types.ts

@@ -0,0 +1,66 @@
+import type { ReactNode } from "react";
+import type { ScrollView, ViewProps } from "react-native";
+import type { ScreenEdge, ScreenPlacement } from "./screen.variants";
+
+/**
+ * The instance `Screen.ScrollArea` hands back through its `ref`.
+ *
+ * Named rather than left inline because a caller needs to say it to declare the
+ * ref in the first place — `useAnimatedRef<ScreenScrollViewRef>()` for a scroll
+ * driven from the UI thread, `useRef<ScreenScrollViewRef>(null)` for one driven
+ * from JS. Both reach the same `scrollTo`.
+ *
+ * React Native's own `ScrollView` instance, which is what both engines actually
+ * hand back — `Animated.ScrollView` forwards to it, and
+ * `KeyboardAwareScrollViewRef` is defined as that same instance plus one method.
+ *
+ * Not `ComponentRef<typeof Animated.ScrollView>`: Reanimated's animated
+ * component types carry no `RefAttributes`, so that expression collapses to
+ * `never` — which still compiles everywhere, silently accepts any ref, and
+ * gives a caller a `.current` it can do nothing with.
+ */
+export type ScreenScrollViewRef = ScrollView;
+
+/**
+ * The shape of a container that can inset itself against the safe area.
+ *
+ * Shared by `Screen.Content` and `Screen.Header`, so it lives in a leaf rather
+ * than in one of them arbitrarily.
+ */
+export type ScreenInsetProps = ViewProps & {
+	/** Safe-area edges to pad against. None by default. */
+	insets?: readonly ScreenEdge[];
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The shape of a part that either overlays the content or sits in the flow.
+ *
+ * Shared by `Screen.Navbar` and `Screen.Footer` — the two parts a scrollable
+ * has to clear, and the reason `placement` is one axis rather than a boolean on
+ * each of them.
+ */
+export type ScreenPlacementProps = ViewProps & {
+	/**
+	 * `overlay` floats the part over the content, which then insets itself by
+	 * the measured height. `static` puts it in the flow, taking its own space.
+	 */
+	placement?: ScreenPlacement;
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * What every Screen scrollable accepts on top of its own list props.
+ *
+ * `header` is separate from a list's `ListHeaderComponent` on purpose: the
+ * screen composes its navbar spacer, this header and the caller's list header
+ * in that order, so a caller can use both without having to interleave them.
+ */
+export type ScreenScrollableProps = {
+	/** Rendered above the content, below the navbar spacer. */
+	header?: ReactNode;
+	className?: string;
+	contentContainerClassName?: string;
+};