@studio-piot/native-ui 0.2.4 → 0.16.0

package/src/components/ErrorBanner/errorBannerContext.tsx

@@ -8,10 +8,15 @@ import {
   type ReactNode,
   type RefObject,
 } from "react";
-import { View, type ReactNativeElement, type ScrollView } from "react-native";
+import { View, type ReactNativeElement } from "react-native";
 import { fieldScrollY } from "./errorBannerCopy";
 import type { FieldError } from "./types";
 
+/** Anything that scrolls: a ScrollView, a KeyboardAwareScrollView, a BottomSheetScrollView. */
+export type ErrorBannerScrollTarget = {
+  scrollTo(options: { y: number; animated?: boolean }): void;
+};
+
 export type ErrorBannerAnchor = {
   view: View;
   focus?: () => void;
@@ -76,12 +81,28 @@ export function ErrorBannerProvider({
   errors,
   onDismiss,
   bannerHeightRef,
+  measureRef,
+  onBeforeJump,
+  scrollYForField,
 }: {
   children: ReactNode;
-  scrollRef: RefObject<ScrollView | null>;
+  scrollRef: RefObject<ErrorBannerScrollTarget | null>;
   errors: readonly FieldError[];
   onDismiss: () => void;
+  /** How far the banner covers the top of the scroll area. */
   bannerHeightRef: RefObject<number>;
+  /**
+   * View that field positions are measured against: the scroll content's
+   * top. Defaults to `scrollRef`, which works for a plain ScrollView.
+   */
+  measureRef?: RefObject<View | null>;
+  /** Runs before scrolling to a field, e.g. to expand a sheet. */
+  onBeforeJump?: () => void;
+  /**
+   * Scroll offset for a field at content y `fieldY`. Defaults to clearing
+   * `bannerHeightRef` from the top of the scroll area.
+   */
+  scrollYForField?: (fieldY: number) => number;
 }) {
   const anchors = useRef(new Map<string, ErrorBannerAnchor>());
 
@@ -96,21 +117,25 @@ export function ErrorBannerProvider({
   const jump = useCallback((field: string) => {
     const anchor = anchors.current.get(field);
     const scroll = scrollRef.current;
-    if (!anchor || !scroll) {
+    const relativeTo = measureRef?.current ?? scroll;
+    if (!anchor || !scroll || !relativeTo) {
       return;
     }
+    onBeforeJump?.();
     anchor.view.measureLayout(
-      scroll as unknown as ReactNativeElement,
+      relativeTo as unknown as ReactNativeElement,
       (_x, y) => {
         scroll.scrollTo({
-          y: fieldScrollY(y, bannerHeightRef.current ?? 0),
+          y: scrollYForField
+            ? scrollYForField(y)
+            : fieldScrollY(y, bannerHeightRef.current ?? 0),
           animated: true,
         });
         anchor.focus?.();
       },
       () => undefined,
     );
-  }, [bannerHeightRef, scrollRef]);
+  }, [bannerHeightRef, measureRef, onBeforeJump, scrollRef, scrollYForField]);
 
   const value = useMemo(
     () => ({ errors, register, dismiss: onDismiss, jump }),

package/src/components/ErrorBanner/errorBannerLayout.test.ts

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  ERROR_BANNER_DISC_SIZE,
+  ERROR_BANNER_FONT_SIZE,
+  ERROR_BANNER_HEADER_GAP,
+  ERROR_BANNER_ROW_INSET,
+  ERROR_BANNER_ROW_MIN_HEIGHT,
+  errorBannerBarStyle,
+} from "./errorBannerLayout.ts";
+
+describe("errorBannerBarStyle", () => {
+  it("uses light status bar text on a dark banner", () => {
+    assert.equal(errorBannerBarStyle("#1F2937"), "light-content");
+    assert.equal(errorBannerBarStyle("#000"), "light-content");
+  });
+
+  it("uses dark status bar text on a light banner", () => {
+    assert.equal(errorBannerBarStyle("#F9FAFB"), "dark-content");
+    assert.equal(errorBannerBarStyle("#fff"), "dark-content");
+  });
+
+  it("reads rgb() and 8-digit hex colours", () => {
+    assert.equal(errorBannerBarStyle("rgb(255, 255, 255)"), "dark-content");
+    assert.equal(errorBannerBarStyle("rgba(31, 41, 55, 0.9)"), "light-content");
+    assert.equal(errorBannerBarStyle("#FFFFFFCC"), "dark-content");
+  });
+
+  it("falls back to the system default when the colour cannot be read", () => {
+    assert.equal(errorBannerBarStyle("red"), "default");
+  });
+});
+
+describe("error banner sizes", () => {
+  it("matches the 17pt body text used by the other components", () => {
+    assert.equal(ERROR_BANNER_FONT_SIZE, 17);
+  });
+
+  it("gives each row the 44pt minimum tap target", () => {
+    assert.ok(ERROR_BANNER_ROW_MIN_HEIGHT >= 44);
+  });
+
+  it("lines rows up with the title, after the disc and gap", () => {
+    assert.equal(
+      ERROR_BANNER_ROW_INSET,
+      ERROR_BANNER_DISC_SIZE + ERROR_BANNER_HEADER_GAP,
+    );
+  });
+});

package/src/components/ErrorBanner/errorBannerLayout.ts

@@ -0,0 +1,59 @@
+/** Title and rows, matching the 17pt body text of Button, Field and Select. */
+export const ERROR_BANNER_FONT_SIZE = 17;
+export const ERROR_BANNER_LINE_HEIGHT = 22;
+export const ERROR_BANNER_DISC_SIZE = 32;
+export const ERROR_BANNER_MEGAPHONE_SIZE = 18;
+export const ERROR_BANNER_ARROW_SIZE = 20;
+export const ERROR_BANNER_DISMISS_SIZE = 18;
+export const ERROR_BANNER_HEADER_GAP = 12;
+export const ERROR_BANNER_ROW_MIN_HEIGHT = 44;
+/** Rows start under the title, past the disc and gap. */
+export const ERROR_BANNER_ROW_INSET =
+  ERROR_BANNER_DISC_SIZE + ERROR_BANNER_HEADER_GAP;
+
+export type ErrorBannerBarStyle = "light-content" | "dark-content" | "default";
+
+function parseRgb(color: string): [number, number, number] | null {
+  const value = color.trim();
+  const hex = /^#([0-9a-f]{3,8})$/i.exec(value)?.[1];
+  if (hex) {
+    const full =
+      hex.length === 3 || hex.length === 4
+        ? hex
+            .slice(0, 3)
+            .split("")
+            .map((c) => c + c)
+            .join("")
+        : hex.slice(0, 6);
+    if (full.length !== 6) {
+      return null;
+    }
+    return [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16)) as [
+      number,
+      number,
+      number,
+    ];
+  }
+  const rgb = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i.exec(value);
+  if (rgb) {
+    return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+  }
+  return null;
+}
+
+/**
+ * Status bar text that stays readable over the banner fill: light text on a
+ * dark banner, dark text on a light one. Pure so it can be unit-tested.
+ */
+export function errorBannerBarStyle(backgroundColor: string): ErrorBannerBarStyle {
+  const rgb = parseRgb(backgroundColor);
+  if (!rgb) {
+    return "default";
+  }
+  const [r, g, b] = rgb.map((c) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  });
+  const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  return luminance > 0.179 ? "dark-content" : "light-content";
+}

package/src/components/ErrorBanner/icons.tsx

@@ -1,10 +1,12 @@
 import Svg, { Line, Path, Polyline } from "react-native-svg";
 
-export function Megaphone({ color }: { color: string }) {
+type IconProps = { color: string; size: number };
+
+export function Megaphone({ color, size }: IconProps) {
   return (
     <Svg
-      width={16}
-      height={16}
+      width={size}
+      height={size}
       viewBox="0 0 24 24"
       fill="none"
       stroke={color}
@@ -19,11 +21,11 @@ export function Megaphone({ color }: { color: string }) {
   );
 }
 
-export function ArrowRight({ color }: { color: string }) {
+export function ArrowRight({ color, size }: IconProps) {
   return (
     <Svg
-      width={18}
-      height={18}
+      width={size}
+      height={size}
       viewBox="0 0 24 24"
       fill="none"
       stroke={color}
@@ -36,3 +38,20 @@ export function ArrowRight({ color }: { color: string }) {
     </Svg>
   );
 }
+
+export function Cross({ color, size }: IconProps) {
+  return (
+    <Svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      strokeWidth={2.25}
+      strokeLinecap="round"
+    >
+      <Line x1={6} y1={6} x2={18} y2={18} />
+      <Line x1={18} y1={6} x2={6} y2={18} />
+    </Svg>
+  );
+}

package/src/components/ErrorBanner/index.ts

@@ -5,6 +5,7 @@ export {
   useErrorBannerContext,
   useErrorBannerDismiss,
   useErrorBannerField,
+  type ErrorBannerScrollTarget,
 } from "./errorBannerContext";
 export {
   ERROR_BANNER_THEME_ROLES,

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,
+  },
+});