@studio-piot/native-ui 0.2.4 → 0.16.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;

package/src/components/FormSheet/FormSheet.tsx

@@ -0,0 +1,279 @@
+import BottomSheet, {
+  BottomSheetHandle,
+  BottomSheetScrollView,
+  type BottomSheetHandleProps,
+  type BottomSheetScrollViewMethods,
+} from "@gorhom/bottom-sheet";
+import { useCallback, useMemo, useRef, useState } from "react";
+import {
+  Platform,
+  StyleSheet,
+  Text,
+  useWindowDimensions,
+  View,
+  type LayoutChangeEvent,
+} from "react-native";
+import { useKeyboardState } from "react-native-keyboard-controller";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { estimateHeaderHeight } from "../../layout/headerInset";
+import { SHEET_TOP_RADIUS } from "../../layout/sheet";
+import { useThemeSpacing } from "../../theme/useThemeSpacing";
+import {
+  ErrorBannerProvider,
+  useErrorBanner,
+} from "../ErrorBanner";
+import { useResolvedFieldColor } from "../Field/useResolvedFieldColor";
+import { FormErrorBanner } from "../Form/FormErrorBanner";
+import { FormSubmitFooter } from "../Form/FormSubmitFooter";
+import {
+  formSheetHandleFallback,
+  formSheetSnapPoints,
+  sheetBannerOverlap,
+} from "./formSheetLayout";
+import { FORM_SHEET_THEME_ROLES } from "./formSheetThemeRoles";
+import type { FormSheetInset, FormSheetProps, FormSheetSnapIndex } from "./types";
+
+const EXPANDED: FormSheetSnapIndex = 2;
+
+function useMeasuredHeight(initial = 0) {
+  const [height, setHeight] = useState(initial);
+  const onLayout = useCallback((event: LayoutChangeEvent) => {
+    const next = Math.round(event.nativeEvent.layout.height);
+    setHeight((current) => (current === next ? current : next));
+  }, []);
+  return [height, onLayout] as const;
+}
+
+/**
+ * A form in a draggable sheet over a full-screen background, usually a map.
+ * Three stops: the handle and title, half the screen, and up to the native
+ * header. The submit button stays above the keyboard. Set the close button
+ * in the screen's stack options, with `headerTransparent: true` so the
+ * background shows behind the header.
+ */
+export function FormSheet({
+  title,
+  children,
+  background,
+  onSubmit,
+  errors = [],
+  submitLabel = "Save",
+  submitting = false,
+  submitDisabled = false,
+  submitRadius = "lg",
+  initialIndex = 0,
+  headerHeight: headerHeightProp,
+  paddingHorizontal: paddingHorizontalProp,
+  backgroundColor: backgroundColorProp,
+  titleColor: titleColorProp,
+  footerBackgroundColor: footerBackgroundColorProp,
+  handleColor: handleColorProp,
+  buttonBackgroundColor,
+  buttonLabelColor,
+}: FormSheetProps) {
+  const insets = useSafeAreaInsets();
+  const spacing = useThemeSpacing();
+  const paddingHorizontal = paddingHorizontalProp ?? spacing.screen;
+  const { height: windowHeight } = useWindowDimensions();
+  const backgroundColor = useResolvedFieldColor(
+    backgroundColorProp,
+    FORM_SHEET_THEME_ROLES.backgroundColor,
+  );
+  const titleColor = useResolvedFieldColor(
+    titleColorProp,
+    FORM_SHEET_THEME_ROLES.titleColor,
+  );
+  const footerBackground = useResolvedFieldColor(
+    footerBackgroundColorProp,
+    FORM_SHEET_THEME_ROLES.footerBackgroundColor,
+  );
+  const handleColor = useResolvedFieldColor(
+    handleColorProp,
+    FORM_SHEET_THEME_ROLES.handleColor,
+  );
+
+  const keyboardHeight = useKeyboardState((state) => state.height);
+  const keyboardLift = Math.max(0, keyboardHeight - insets.bottom);
+
+  const [footerHeight, onFooterLayout] = useMeasuredHeight();
+  const [handleHeight, onHandleLayout] = useMeasuredHeight(
+    formSheetHandleFallback(Boolean(title)),
+  );
+  const [sheetAreaHeight, onSheetAreaLayout] = useMeasuredHeight();
+  const [snapIndex, setSnapIndex] = useState<FormSheetSnapIndex>(initialIndex);
+
+  // Estimates until the first layout pass reports real sizes.
+  const resolvedHeader =
+    headerHeightProp ?? estimateHeaderHeight(Platform.OS, insets.top);
+  const resolvedFooter = footerHeight || insets.bottom + 76;
+  const resolvedArea =
+    sheetAreaHeight || Math.max(0, windowHeight - resolvedFooter - keyboardLift);
+
+  const snapPoints = useMemo(
+    () =>
+      formSheetSnapPoints({
+        windowHeight,
+        sheetAreaHeight: resolvedArea,
+        headerHeight: resolvedHeader,
+        handleHeight,
+      }),
+    [handleHeight, resolvedArea, resolvedHeader, windowHeight],
+  );
+
+  const sheetRef = useRef<BottomSheet>(null);
+  const scrollRef = useRef<BottomSheetScrollViewMethods>(null);
+  const contentRef = useRef<View>(null);
+  const bannerRawHeightRef = useRef(0);
+  const bannerOverlapRef = useRef(0);
+  const scrollTopRef = useRef(0);
+  scrollTopRef.current = resolvedHeader + handleHeight;
+  const banner = useErrorBanner(errors);
+
+  // A banner row expands the sheet first, so the field has room to show.
+  const expandForJump = useCallback(() => {
+    sheetRef.current?.snapToIndex(EXPANDED);
+    bannerOverlapRef.current = sheetBannerOverlap(
+      bannerRawHeightRef.current,
+      scrollTopRef.current,
+    );
+  }, []);
+
+  const renderHandle = useCallback(
+    (props: BottomSheetHandleProps) => (
+      <View
+        onLayout={onHandleLayout}
+        style={[styles.handle, { backgroundColor, paddingHorizontal }]}
+      >
+        <BottomSheetHandle
+          {...props}
+          indicatorStyle={{ backgroundColor: handleColor }}
+        />
+        {title ? (
+          <Text
+            accessibilityRole="header"
+            numberOfLines={1}
+            style={[styles.title, { color: titleColor }]}
+          >
+            {title}
+          </Text>
+        ) : null}
+      </View>
+    ),
+    [backgroundColor, handleColor, onHandleLayout, paddingHorizontal, title, titleColor],
+  );
+
+  const inset: FormSheetInset = {
+    top: resolvedHeader,
+    bottom: resolvedFooter + snapPoints[snapIndex],
+    bottomAtHalf: resolvedFooter + snapPoints[1],
+  };
+
+  return (
+    <ErrorBannerProvider
+      bannerHeightRef={bannerOverlapRef}
+      errors={errors}
+      measureRef={contentRef}
+      onBeforeJump={expandForJump}
+      onDismiss={banner.dismiss}
+      scrollRef={scrollRef}
+    >
+      <View style={[styles.screen, { backgroundColor }]}>
+        <View pointerEvents="box-none" style={StyleSheet.absoluteFill}>
+          {background(inset)}
+        </View>
+
+        <View
+          onLayout={onSheetAreaLayout}
+          pointerEvents="box-none"
+          style={[styles.sheetArea, { marginBottom: keyboardLift }]}
+        >
+          <BottomSheet
+            ref={sheetRef}
+            animateOnMount={false}
+            index={initialIndex}
+            backgroundStyle={[styles.sheet, { backgroundColor }]}
+            enableContentPanningGesture
+            enableDynamicSizing={false}
+            keyboardBehavior="extend"
+            enablePanDownToClose={false}
+            handleComponent={renderHandle}
+            onChange={(next: number) => {
+              // -1 is closed; the sheet only has three stops.
+              if (next === 0 || next === 1 || next === 2) {
+                setSnapIndex(next);
+              }
+            }}
+            snapPoints={snapPoints}
+          >
+            <BottomSheetScrollView
+              ref={scrollRef}
+              contentContainerStyle={[styles.content, { paddingHorizontal }]}
+              keyboardShouldPersistTaps="handled"
+            >
+              {/* Field positions are measured from here: the top of the content. */}
+              <View ref={contentRef} collapsable={false} style={styles.contentTop}>
+                {children}
+              </View>
+            </BottomSheetScrollView>
+          </BottomSheet>
+        </View>
+
+        <FormSubmitFooter
+          backgroundColor={footerBackground}
+          buttonBackgroundColor={buttonBackgroundColor}
+          buttonLabelColor={buttonLabelColor}
+          disabled={submitDisabled}
+          label={submitLabel}
+          onLayout={onFooterLayout}
+          onPress={() => {
+            banner.present();
+            onSubmit();
+          }}
+          paddingHorizontal={paddingHorizontal}
+          radius={submitRadius}
+          submitting={submitting}
+        />
+
+        <FormErrorBanner
+          androidTop={resolvedHeader}
+          errors={errors}
+          onDismiss={banner.dismiss}
+          onHeightChange={(height) => {
+            bannerRawHeightRef.current = height;
+          }}
+          open={banner.open}
+        />
+      </View>
+    </ErrorBannerProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: {
+    flex: 1,
+  },
+  sheetArea: {
+    flex: 1,
+  },
+  sheet: {
+    borderTopLeftRadius: SHEET_TOP_RADIUS,
+    borderTopRightRadius: SHEET_TOP_RADIUS,
+  },
+  handle: {
+    alignItems: "center",
+    paddingBottom: 12,
+    borderTopLeftRadius: SHEET_TOP_RADIUS,
+    borderTopRightRadius: SHEET_TOP_RADIUS,
+  },
+  title: {
+    fontSize: 17,
+    fontWeight: "600",
+    textAlign: "center",
+  },
+  content: {
+    paddingBottom: 24,
+  },
+  contentTop: {
+    paddingTop: 8,
+  },
+});

package/src/components/FormSheet/formSheetLayout.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  FORM_SHEET_HANDLE_FALLBACK,
+  formSheetHandleFallback,
+  formSheetSnapPoints,
+  sheetBannerOverlap,
+} from "./formSheetLayout.ts";
+
+describe("formSheetSnapPoints", () => {
+  it("returns the handle, half the screen, and up to the header", () => {
+    const [collapsed, half, full] = formSheetSnapPoints({
+      windowHeight: 800,
+      sheetAreaHeight: 720,
+      headerHeight: 100,
+      handleHeight: 72,
+    });
+    assert.equal(collapsed, 72);
+    assert.equal(half, 320);
+    assert.equal(full, 620);
+  });
+
+  it("keeps half between the handle and the header when space is tight", () => {
+    const [collapsed, half, full] = formSheetSnapPoints({
+      windowHeight: 800,
+      sheetAreaHeight: 420,
+      headerHeight: 100,
+      handleHeight: 72,
+    });
+    assert.equal(collapsed, 72);
+    assert.ok(half > collapsed);
+    assert.ok(half < full);
+    assert.equal(full, 320);
+  });
+
+  it("always returns three increasing heights, even with no room", () => {
+    const [collapsed, half, full] = formSheetSnapPoints({
+      windowHeight: 800,
+      sheetAreaHeight: 80,
+      headerHeight: 100,
+      handleHeight: 72,
+    });
+    assert.ok(collapsed < half && half < full);
+  });
+});
+
+describe("sheetBannerOverlap", () => {
+  it("is how far the banner reaches into the expanded sheet's scroll area", () => {
+    assert.equal(sheetBannerOverlap(180, 150), 30);
+  });
+
+  it("is zero when the banner ends above the scroll area", () => {
+    assert.equal(sheetBannerOverlap(120, 150), 0);
+  });
+});
+
+describe("formSheetHandleFallback", () => {
+  it("leaves room for the title line before the handle is measured", () => {
+    assert.equal(formSheetHandleFallback(true), FORM_SHEET_HANDLE_FALLBACK.withTitle);
+    assert.ok(FORM_SHEET_HANDLE_FALLBACK.withTitle > FORM_SHEET_HANDLE_FALLBACK.indicatorOnly);
+  });
+
+  it("is just the indicator without a title", () => {
+    assert.equal(formSheetHandleFallback(false), FORM_SHEET_HANDLE_FALLBACK.indicatorOnly);
+  });
+});

package/src/components/FormSheet/formSheetLayout.ts

@@ -0,0 +1,55 @@
+export type FormSheetSnapInput = {
+  /** Full window height, used to place the middle stop at half the screen. */
+  windowHeight: number;
+  /** Height of the sheet's parent: the screen above the footer and keyboard. */
+  sheetAreaHeight: number;
+  /** Header block the expanded sheet stops beneath. */
+  headerHeight: number;
+  /** Collapsed sheet: drag handle plus title. */
+  handleHeight: number;
+};
+
+/**
+ * Three sheet heights, shortest first. Minimum is the handle. Middle puts the
+ * sheet top at half the screen. Maximum stops at the bottom of the header.
+ * Pure so it can be unit-tested.
+ */
+export function formSheetSnapPoints({
+  windowHeight,
+  sheetAreaHeight,
+  headerHeight,
+  handleHeight,
+}: FormSheetSnapInput): [number, number, number] {
+  const collapsed = Math.max(1, Math.round(handleHeight));
+  const full = Math.max(collapsed, Math.round(sheetAreaHeight - headerHeight));
+  const halfRaw = Math.round(sheetAreaHeight - windowHeight / 2);
+  // The sheet needs three distinct, increasing stops even when there is
+  // almost no room, so nudge each one above the last.
+  const half = Math.max(collapsed + 1, Math.min(full, halfRaw));
+  const top = Math.max(half + 1, full);
+  return [collapsed, half, top];
+}
+
+/**
+ * How far the error banner reaches into the expanded sheet's scroll area,
+ * whose top sits `scrollTop` below the screen top (header plus handle).
+ * A banner row scrolls its field this much further so it is not hidden.
+ */
+export function sheetBannerOverlap(bannerHeight: number, scrollTop: number): number {
+  return Math.max(0, bannerHeight - scrollTop);
+}
+
+/** Handle heights before the first layout pass measures the real one. */
+export const FORM_SHEET_HANDLE_FALLBACK = {
+  /** Drag indicator and padding. */
+  indicatorOnly: 36,
+  /** Indicator plus one title line. */
+  withTitle: 64,
+} as const;
+
+/** The collapsed stop is the handle, so it must fit the title when there is one. */
+export function formSheetHandleFallback(hasTitle: boolean): number {
+  return hasTitle
+    ? FORM_SHEET_HANDLE_FALLBACK.withTitle
+    : FORM_SHEET_HANDLE_FALLBACK.indicatorOnly;
+}

package/src/components/FormSheet/formSheetThemeRoles.test.ts

@@ -0,0 +1,14 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { FORM_SHEET_THEME_ROLES } from "./formSheetThemeRoles.ts";
+
+describe("FORM_SHEET_THEME_ROLES", () => {
+  it("maps colour props to formSheet-prefixed roles", () => {
+    assert.deepEqual(FORM_SHEET_THEME_ROLES, {
+      backgroundColor: "formSheetBackground",
+      titleColor: "formSheetTitle",
+      footerBackgroundColor: "formSheetFooterBackground",
+      handleColor: "formSheetHandle",
+    });
+  });
+});

package/src/components/FormSheet/formSheetThemeRoles.ts

@@ -0,0 +1,8 @@
+export const FORM_SHEET_THEME_ROLES = {
+  backgroundColor: "formSheetBackground",
+  titleColor: "formSheetTitle",
+  footerBackgroundColor: "formSheetFooterBackground",
+  handleColor: "formSheetHandle",
+} as const;
+
+export type FormSheetThemeColorProp = keyof typeof FORM_SHEET_THEME_ROLES;

package/src/components/FormSheet/index.ts

@@ -0,0 +1,7 @@
+export { FormSheet } from "./FormSheet";
+export { formSheetSnapPoints, type FormSheetSnapInput } from "./formSheetLayout";
+export {
+  FORM_SHEET_THEME_ROLES,
+  type FormSheetThemeColorProp,
+} from "./formSheetThemeRoles";
+export type { FormSheetInset, FormSheetProps, FormSheetSnapIndex } from "./types";

package/src/components/FormSheet/types.ts

@@ -0,0 +1,66 @@
+import type { ReactNode } from "react";
+import type { ButtonRadius } from "../Button/buttonRadius";
+import type { FieldError } from "../ErrorBanner/types";
+
+/** Where the chrome sits over the background layer, in points from the screen edges. */
+export type FormSheetInset = {
+  /** Bottom of the native header. */
+  top: number;
+  /** Top of the sheet at its current stop, measured from the screen bottom. */
+  bottom: number;
+  /** Top of the sheet at its middle stop. Steady while dragging, e.g. for map camera padding. */
+  bottomAtHalf: number;
+};
+
+export type FormSheetSnapIndex = 0 | 1 | 2;
+
+/**
+ * Set the close button in the screen's stack options (`headerLeft`), with
+ * `headerTransparent: true`. The form's title lives on the sheet (`title`).
+ */
+export type FormSheetProps = {
+  /**
+   * Shown at the top of the sheet, under the drag indicator. The lowest stop
+   * always shows it.
+   */
+  title?: string;
+  children: ReactNode;
+  /**
+   * Full-screen layer behind the sheet, usually a map. Receives the chrome
+   * insets so it can keep its own controls clear of the header and sheet.
+   */
+  background: (inset: FormSheetInset) => ReactNode;
+  onSubmit: () => void;
+  /**
+   * Field errors for the screen banner. Empty hides it. A banner row
+   * expands the sheet and scrolls to the field. Editing a field dismisses
+   * the banner; the next submit shows it again.
+   */
+  errors?: readonly FieldError[];
+  submitLabel?: string;
+  submitting?: boolean;
+  submitDisabled?: boolean;
+  submitRadius?: ButtonRadius;
+  /** Stop on first paint: `0` the handle and title, `1` half the screen, `2` up to the header. Default `0`. */
+  initialIndex?: FormSheetSnapIndex;
+  /**
+   * Native header height, from `useHeaderHeight()` in
+   * `expo-router/react-navigation`. The top stop ends here. Defaults to the
+   * status bar plus a standard bar.
+   */
+  headerHeight?: number;
+  /** Side inset for the sheet content and footer. Defaults to theme `spacing.screen`. */
+  paddingHorizontal?: number;
+  /** Sheet fill. Defaults to theme role `formSheetBackground`. */
+  backgroundColor?: string;
+  /** Sheet title. Defaults to theme role `formSheetTitle`. */
+  titleColor?: string;
+  /** Footer ground. Defaults to theme role `formSheetFooterBackground`. */
+  footerBackgroundColor?: string;
+  /** Drag indicator. Defaults to theme role `formSheetHandle`. */
+  handleColor?: string;
+  /** Defaults to theme role `buttonBackground`. */
+  buttonBackgroundColor?: string;
+  /** Defaults to theme role `buttonLabel`. */
+  buttonLabelColor?: string;
+};