@studio-piot/native-ui 0.2.5 → 0.17.0

package/src/components/Form/Form.tsx

@@ -1,55 +1,20 @@
-import { useRef, useState, type ReactNode } from "react";
-import {
-  StyleSheet,
-  Text,
-  View,
-  type LayoutChangeEvent,
-} from "react-native";
+import { useCallback, useRef, useState } from "react";
+import { Platform, StyleSheet, View, type LayoutChangeEvent } from "react-native";
 import {
   KeyboardAwareScrollView,
-  KeyboardStickyView,
   type KeyboardAwareScrollViewRef,
 } from "react-native-keyboard-controller";
-import {
-  ErrorBanner,
-  ErrorBannerProvider,
-  useErrorBanner,
-  useErrorBannerContext,
-  type FieldError,
-} from "../ErrorBanner";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { screenPaddingHorizontal } from "../../layout/screenPadding";
-import { Button } from "../Button/Button";
-import { FormCloseButton } from "./FormCloseButton";
+import { estimateHeaderHeight, formFieldScrollY } from "../../layout/headerInset";
+import { useThemeSpacing } from "../../theme/useThemeSpacing";
+import { ErrorBannerProvider, useErrorBanner } from "../ErrorBanner";
+import { ERROR_BANNER_SCROLL_GAP } from "../ErrorBanner/errorBannerCopy";
+import { FormErrorBanner } from "./FormErrorBanner";
+import { FormSubmitFooter } from "./FormSubmitFooter";
+import { FORM_THEME_ROLES } from "./formThemeRoles";
 import type { FormProps } from "./types";
 import { useResolvedThemeColor } from "./useResolvedThemeColor";
-import { withAlpha } from "./withAlpha";
 
-/** How far the header wash continues below the buttons. */
-const FADE_TAIL = 32;
-
-function FormErrorBanner({
-  open,
-  errors,
-  onDismiss,
-  onHeightChange,
-}: {
-  open: boolean;
-  errors: readonly FieldError[];
-  onDismiss: () => void;
-  onHeightChange: (height: number) => void;
-}) {
-  const ctx = useErrorBannerContext();
-  return (
-    <ErrorBanner
-      errors={errors}
-      onDismiss={onDismiss}
-      onHeightChange={onHeightChange}
-      onJump={(field) => ctx?.jump(field)}
-      open={open}
-    />
-  );
-}
 
 /** Space kept between the focused field and the top of the footer. */
 const FIELD_GAP = 12;
@@ -60,55 +25,79 @@ const FIELD_GAP = 12;
  */
 const FIELD_BELOW_CARET = 36;
 
+/**
+ * A full-screen form under the native stack header. Set the title and the
+ * close button in the screen's stack options. The scroll view is the
+ * screen's first child, so iOS insets it for the header (including a large
+ * title) and content scrolls behind the bar. Render `Form` as the screen's
+ * root element. For a wash behind a transparent header, use `HeaderWash` as
+ * the stack's `headerBackground`.
+ */
 export function Form({
-  title,
   children,
-  onClose,
   onSubmit,
   errors = [],
   submitLabel = "Save",
   submitting = false,
   submitDisabled = false,
-  closeButton,
   submitRadius = "lg",
-  paddingHorizontal = screenPaddingHorizontal,
+  headerHeight: headerHeightProp,
+  paddingHorizontal: paddingHorizontalProp,
   backgroundColor: backgroundColorProp,
-  titleColor: titleColorProp,
   footerBackgroundColor: footerBackgroundColorProp,
-  buttonBackgroundColor: buttonBackgroundColorProp,
-  buttonLabelColor: buttonLabelColorProp,
+  buttonBackgroundColor,
+  buttonLabelColor,
 }: FormProps) {
+  const spacing = useThemeSpacing();
   const insets = useSafeAreaInsets();
-  const background = useResolvedThemeColor(backgroundColorProp, "background");
-  const titleColor = useResolvedThemeColor(titleColorProp, "text");
+  const paddingHorizontal = paddingHorizontalProp ?? spacing.screen;
+  const background = useResolvedThemeColor(
+    backgroundColorProp,
+    FORM_THEME_ROLES.backgroundColor,
+  );
   const footerBackground = useResolvedThemeColor(
     footerBackgroundColorProp,
-    "surface",
-  );
-  const buttonBackground = useResolvedThemeColor(
-    buttonBackgroundColorProp,
-    "buttonBackground",
-  );
-  const buttonLabel = useResolvedThemeColor(
-    buttonLabelColorProp,
-    "buttonLabel",
+    FORM_THEME_ROLES.footerBackgroundColor,
   );
   const scrollRef = useRef<KeyboardAwareScrollViewRef>(null);
   const bannerHeightRef = useRef(0);
+  const scrollTopRef = useRef(0);
+  const headerHeight =
+    headerHeightProp ?? estimateHeaderHeight(Platform.OS, insets.top);
+  const headerHeightRef = useRef(headerHeight);
+  headerHeightRef.current = headerHeight;
   const banner = useErrorBanner(errors);
   const [footerHeight, setFooterHeight] = useState(0);
-  const [cancelWidth, setCancelWidth] = useState(0);
-  const [barHeight, setBarHeight] = useState(0);
-  const resolvedBar = barHeight || insets.top + 52;
 
   const onFooterLayout = (event: LayoutChangeEvent) => {
     const next = Math.round(event.nativeEvent.layout.height);
     setFooterHeight((current) => (current === next ? current : next));
   };
 
-  const resolvedClose: ReactNode = closeButton ?? (
-    <FormCloseButton onPress={onClose} />
-  );
+  // Window y of the scroll view: 0 under a transparent header, the header's
+  // bottom under an opaque one.
+  const onScrollLayout = (event: LayoutChangeEvent) => {
+    (event.currentTarget as unknown as View).measureInWindow((_x, y) => {
+      scrollTopRef.current = Math.round(y);
+    });
+  };
+
+  // A banner row scrolls its field clear of the header and the banner.
+  const scrollYForField = useCallback((fieldY: number) => {
+    const scrollTop = scrollTopRef.current;
+    const header = headerHeightRef.current;
+    // iOS draws the banner over the window top; Android inside the screen.
+    const bannerTop = Platform.OS === "ios" ? 0 : scrollTop;
+    return formFieldScrollY({
+      fieldY,
+      scrollTop,
+      visibleTop: Math.max(scrollTop, header),
+      bannerBottom: bannerTop + bannerHeightRef.current,
+      // Under a transparent header iOS rests the content at -(header).
+      minScrollY: Math.min(0, scrollTop - header),
+      gap: ERROR_BANNER_SCROLL_GAP,
+    });
+  }, []);
 
   return (
     <ErrorBannerProvider
@@ -116,96 +105,42 @@ export function Form({
       errors={errors}
       onDismiss={banner.dismiss}
       scrollRef={scrollRef}
+      scrollYForField={scrollYForField}
     >
-    <View style={[styles.screen, { backgroundColor: background }]}>
       <KeyboardAwareScrollView
         ref={scrollRef}
         automaticallyAdjustKeyboardInsets={false}
         bottomOffset={footerHeight + FIELD_GAP + FIELD_BELOW_CARET}
         contentContainerStyle={[
           styles.content,
-          {
-            paddingTop: resolvedBar + FADE_TAIL,
-            paddingHorizontal,
-          },
+          { paddingTop: spacing.pageTop, paddingHorizontal },
         ]}
-        contentInsetAdjustmentBehavior="never"
+        contentInsetAdjustmentBehavior="automatic"
         keyboardDismissMode="interactive"
         keyboardShouldPersistTaps="handled"
+        onLayout={onScrollLayout}
         showsVerticalScrollIndicator={false}
-        style={styles.scroll}
+        style={[styles.scroll, { backgroundColor: background }]}
       >
         {children}
       </KeyboardAwareScrollView>
 
-      <View
-        pointerEvents="box-none"
-        style={[
-          styles.fade,
-          {
-            height: resolvedBar + FADE_TAIL,
-            experimental_backgroundImage: `linear-gradient(to bottom, ${withAlpha(background, 0.98)} 0%, ${withAlpha(background, 0.92)} 55%, ${withAlpha(background, 0)} 100%)`,
-          },
-        ]}
-      >
-        <View
-          onLayout={(event) => {
-            const next = Math.round(event.nativeEvent.layout.height);
-            setBarHeight((current) => (current === next ? current : next));
-          }}
-          pointerEvents="box-none"
-          style={[
-            styles.header,
-            { paddingTop: insets.top, paddingHorizontal },
-          ]}
-        >
-          <View
-            onLayout={(event) => {
-              const next = Math.round(event.nativeEvent.layout.width);
-              setCancelWidth((current) => (current === next ? current : next));
-            }}
-          >
-            {resolvedClose}
-          </View>
-          <Text
-            accessibilityRole="header"
-            numberOfLines={1}
-            pointerEvents="none"
-            style={[styles.title, { flex: 1, color: titleColor }]}
-          >
-            {title}
-          </Text>
-          <View style={{ width: cancelWidth }} />
-        </View>
-      </View>
+      <FormSubmitFooter
+        backgroundColor={footerBackground}
+        buttonBackgroundColor={buttonBackgroundColor}
+        buttonLabelColor={buttonLabelColor}
+        disabled={submitDisabled}
+        label={submitLabel}
+        onLayout={onFooterLayout}
+        onPress={() => {
+          banner.present();
+          onSubmit();
+        }}
+        paddingHorizontal={paddingHorizontal}
+        radius={submitRadius}
+        submitting={submitting}
+      />
 
-      {/*
-        The spacer is the home-indicator clearance. `opened` equals that
-        spacer, so once the keyboard is up the spacer sits inside the
-        keyboard and the button rests on whatever height the keyboard is.
-      */}
-      <KeyboardStickyView offset={{ closed: 0, opened: insets.bottom }}>
-        <View style={[styles.footerShell, { backgroundColor: footerBackground }]}>
-          <View
-            onLayout={onFooterLayout}
-            style={[styles.footer, { paddingHorizontal }]}
-          >
-            <Button
-              backgroundColor={buttonBackground}
-              disabled={submitDisabled}
-              label={submitLabel}
-              labelColor={buttonLabel}
-              loading={submitting}
-              onPress={() => {
-                banner.present();
-                onSubmit();
-              }}
-              radius={submitRadius}
-            />
-          </View>
-          <View style={{ height: insets.bottom }} />
-        </View>
-      </KeyboardStickyView>
       <FormErrorBanner
         errors={errors}
         onDismiss={banner.dismiss}
@@ -214,46 +149,15 @@ export function Form({
         }}
         open={banner.open}
       />
-    </View>
     </ErrorBannerProvider>
   );
 }
 
 const styles = StyleSheet.create({
-  screen: {
-    flex: 1,
-  },
   scroll: {
     flex: 1,
   },
   content: {
-    paddingTop: 20,
     paddingBottom: 24,
   },
-  fade: {
-    position: "absolute",
-    top: 0,
-    left: 0,
-    right: 0,
-  },
-  header: {
-    flexDirection: "row",
-    alignItems: "center",
-  },
-  title: {
-    fontSize: 17,
-    fontWeight: "600",
-    textAlign: "center",
-  },
-  footerShell: {
-    // Cast upward so the sticky footer separates from the scroll body.
-    shadowColor: "#000",
-    shadowOffset: { width: 0, height: -4 },
-    shadowOpacity: 0.08,
-    shadowRadius: 12,
-    elevation: 8,
-  },
-  footer: {
-    paddingVertical: 12,
-  },
 });

package/src/components/Form/FormCloseButton.tsx

@@ -1,12 +1,20 @@
 import { Pressable, StyleSheet, Text } from "react-native";
-import { useThemeColor } from "../../theme/useThemeColor";
+import { useResolvedFieldColor } from "../Field/useResolvedFieldColor";
+import { FORM_THEME_ROLES } from "./formThemeRoles";
 
-export function FormCloseButton({ onPress }: { onPress: () => void }) {
-  const text = useThemeColor("text");
+export function FormCloseButton({
+  onPress,
+  color: colorProp,
+}: {
+  onPress: () => void;
+  /** Defaults to theme role `formClose`. */
+  color?: string;
+}) {
+  const color = useResolvedFieldColor(colorProp, FORM_THEME_ROLES.closeColor);
 
   return (
     <Pressable accessibilityRole="button" hitSlop={8} onPress={onPress}>
-      <Text style={[styles.label, { color: text }]}>Cancel</Text>
+      <Text style={[styles.label, { color }]}>Cancel</Text>
     </Pressable>
   );
 }

package/src/components/Form/FormErrorBanner.tsx

@@ -0,0 +1,57 @@
+import { Platform, StyleSheet, View } from "react-native";
+import { FullWindowOverlay } from "react-native-screens";
+import {
+  ErrorBanner,
+  useErrorBannerContext,
+  type FieldError,
+} from "../ErrorBanner";
+
+/**
+ * The screen banner wired to the nearest `ErrorBannerProvider`. Shared by
+ * `Form` and `FormSheet`. On iOS it renders in a native overlay window so it
+ * covers the native header. Android native headers do not overlap the
+ * screen, so there it sits `androidTop` below the screen top, under the header.
+ */
+export function FormErrorBanner({
+  open,
+  errors,
+  onDismiss,
+  onHeightChange,
+  androidTop = 0,
+}: {
+  open: boolean;
+  errors: readonly FieldError[];
+  onDismiss: () => void;
+  onHeightChange: (height: number) => void;
+  androidTop?: number;
+}) {
+  const ctx = useErrorBannerContext();
+  const banner = (
+    <ErrorBanner
+      errors={errors}
+      onDismiss={onDismiss}
+      onHeightChange={onHeightChange}
+      onJump={(field) => ctx?.jump(field)}
+      open={open}
+      safeAreaTop={Platform.OS === "ios" ? undefined : 0}
+    />
+  );
+
+  if (Platform.OS === "ios") {
+    return <FullWindowOverlay>{banner}</FullWindowOverlay>;
+  }
+  return (
+    <View pointerEvents="box-none" style={[styles.below, { top: androidTop }]}>
+      {banner}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  below: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    bottom: 0,
+  },
+});

package/src/components/Form/FormSubmitFooter.tsx

@@ -0,0 +1,70 @@
+import { StyleSheet, View, type LayoutChangeEvent } from "react-native";
+import { KeyboardStickyView } from "react-native-keyboard-controller";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { Button } from "../Button";
+import type { ButtonRadius } from "../Button/buttonRadius";
+
+/** Sticky submit footer shared by `Form` and `FormSheet`. */
+export function FormSubmitFooter({
+  label,
+  onPress,
+  submitting,
+  disabled,
+  radius,
+  paddingHorizontal,
+  backgroundColor,
+  buttonBackgroundColor,
+  buttonLabelColor,
+  onLayout,
+}: {
+  label: string;
+  onPress: () => void;
+  submitting: boolean;
+  disabled: boolean;
+  radius: ButtonRadius;
+  paddingHorizontal: number;
+  backgroundColor: string;
+  buttonBackgroundColor?: string;
+  buttonLabelColor?: string;
+  /** Height of the bar above the home indicator, for scroll clearance. */
+  onLayout?: (event: LayoutChangeEvent) => void;
+}) {
+  const insets = useSafeAreaInsets();
+
+  return (
+    // The spacer is the home-indicator clearance. `opened` equals that
+    // spacer, so once the keyboard is up the spacer sits inside the
+    // keyboard and the button rests on whatever height the keyboard is.
+    <KeyboardStickyView offset={{ closed: 0, opened: insets.bottom }}>
+      <View style={[styles.shell, { backgroundColor }]}>
+        <View onLayout={onLayout} style={[styles.bar, { paddingHorizontal }]}>
+          <Button
+            backgroundColor={buttonBackgroundColor}
+            disabled={disabled}
+            label={label}
+            labelColor={buttonLabelColor}
+            loading={submitting}
+            onPress={onPress}
+            radius={radius}
+          />
+        </View>
+        <View style={{ height: insets.bottom }} />
+      </View>
+    </KeyboardStickyView>
+  );
+}
+
+const styles = StyleSheet.create({
+  shell: {
+    zIndex: 2,
+    // Cast upward so the sticky footer separates from the scroll body.
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: -4 },
+    shadowOpacity: 0.08,
+    shadowRadius: 12,
+    elevation: 8,
+  },
+  bar: {
+    paddingVertical: 12,
+  },
+});

package/src/components/Form/formThemeRoles.test.ts

@@ -0,0 +1,13 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { FORM_THEME_ROLES } from "./formThemeRoles.ts";
+
+describe("FORM_THEME_ROLES", () => {
+  it("maps colour props to form-prefixed roles, not the app's own names", () => {
+    assert.deepEqual(FORM_THEME_ROLES, {
+      backgroundColor: "formBackground",
+      footerBackgroundColor: "formFooterBackground",
+      closeColor: "formClose",
+    });
+  });
+});

package/src/components/Form/formThemeRoles.ts

@@ -0,0 +1,7 @@
+export const FORM_THEME_ROLES = {
+  backgroundColor: "formBackground",
+  footerBackgroundColor: "formFooterBackground",
+  closeColor: "formClose",
+} as const;
+
+export type FormThemeColorProp = keyof typeof FORM_THEME_ROLES;

package/src/components/Form/index.ts

@@ -1,3 +1,4 @@
 export { Form } from "./Form";
 export { FormCloseButton } from "./FormCloseButton";
+export { FORM_THEME_ROLES, type FormThemeColorProp } from "./formThemeRoles";
 export type { FormProps } from "./types";

package/src/components/Form/types.ts

@@ -2,10 +2,12 @@ import type { ReactNode } from "react";
 import type { ButtonRadius } from "../Button/buttonRadius";
 import type { FieldError } from "../ErrorBanner/types";
 
+/**
+ * Set the title and close button in the screen's stack options
+ * (`title`, `headerLeft`), not here.
+ */
 export type FormProps = {
-  title: string;
   children: ReactNode;
-  onClose: () => void;
   onSubmit: () => void;
   /**
    * Field errors for the screen banner. Empty hides it.
@@ -16,19 +18,21 @@ export type FormProps = {
   submitLabel?: string;
   submitting?: boolean;
   submitDisabled?: boolean;
-  /** App-specific Cancel control. Defaults to a plain text Cancel. */
-  closeButton?: ReactNode;
   submitRadius?: ButtonRadius;
   /**
-   * Horizontal inset for header, scroll content, and footer.
-   * Defaults to 16. Pass a value to override.
+   * Native header height, from `useHeaderHeight()` in
+   * `expo-router/react-navigation`. Used to scroll an error's field clear of
+   * the header. Defaults to the status bar plus a standard bar.
+   */
+  headerHeight?: number;
+  /**
+   * Horizontal inset for the scroll content and footer.
+   * Defaults to theme `spacing.screen`. Pass a value to override.
    */
   paddingHorizontal?: number;
-  /** Defaults to theme role `background`. */
+  /** Defaults to theme role `formBackground`. */
   backgroundColor?: string;
-  /** Defaults to theme role `text`. */
-  titleColor?: string;
-  /** Defaults to theme role `surface`. Footer ground. */
+  /** Defaults to theme role `formFooterBackground`. Footer ground. */
   footerBackgroundColor?: string;
   /** Defaults to theme role `buttonBackground`. */
   buttonBackgroundColor?: string;