@studio-piot/native-ui 0.2.3 → 0.2.4

package/src/components/ErrorBanner/errorBannerContext.tsx

@@ -0,0 +1,140 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import { View, type ReactNativeElement, type ScrollView } from "react-native";
+import { fieldScrollY } from "./errorBannerCopy";
+import type { FieldError } from "./types";
+
+export type ErrorBannerAnchor = {
+  view: View;
+  focus?: () => void;
+};
+
+type ErrorBannerContextValue = {
+  errors: readonly FieldError[];
+  register: (field: string, anchor: ErrorBannerAnchor | null) => void;
+  dismiss: () => void;
+  jump: (field: string) => void;
+};
+
+const ErrorBannerContext = createContext<ErrorBannerContextValue | null>(null);
+
+export function useErrorBannerContext(): ErrorBannerContextValue | null {
+  return useContext(ErrorBannerContext);
+}
+
+export function useErrorBannerDismiss(): () => void {
+  const ctx = useContext(ErrorBannerContext);
+  return ctx?.dismiss ?? (() => undefined);
+}
+
+/**
+ * Registers a field so a banner row can scroll it into view.
+ * No-ops outside `ErrorBannerProvider` (and `Form`, which provides one).
+ */
+export function useErrorBannerField(
+  name: string | undefined,
+  focus?: () => void,
+) {
+  const ctx = useContext(ErrorBannerContext);
+  const viewRef = useRef<View>(null);
+  const focusRef = useRef(focus);
+  focusRef.current = focus;
+
+  useEffect(() => {
+    if (!name || !ctx) {
+      return;
+    }
+    const view = viewRef.current;
+    if (!view) {
+      return;
+    }
+    ctx.register(name, {
+      view,
+      focus: () => focusRef.current?.(),
+    });
+    return () => ctx.register(name, null);
+  }, [ctx, name]);
+
+  const listed = name
+    ? ctx?.errors.find((error) => error.field === name)
+    : undefined;
+
+  return { viewRef, listed };
+}
+
+export function ErrorBannerProvider({
+  children,
+  scrollRef,
+  errors,
+  onDismiss,
+  bannerHeightRef,
+}: {
+  children: ReactNode;
+  scrollRef: RefObject<ScrollView | null>;
+  errors: readonly FieldError[];
+  onDismiss: () => void;
+  bannerHeightRef: RefObject<number>;
+}) {
+  const anchors = useRef(new Map<string, ErrorBannerAnchor>());
+
+  const register = useCallback((field: string, anchor: ErrorBannerAnchor | null) => {
+    if (!anchor) {
+      anchors.current.delete(field);
+      return;
+    }
+    anchors.current.set(field, anchor);
+  }, []);
+
+  const jump = useCallback((field: string) => {
+    const anchor = anchors.current.get(field);
+    const scroll = scrollRef.current;
+    if (!anchor || !scroll) {
+      return;
+    }
+    anchor.view.measureLayout(
+      scroll as unknown as ReactNativeElement,
+      (_x, y) => {
+        scroll.scrollTo({
+          y: fieldScrollY(y, bannerHeightRef.current ?? 0),
+          animated: true,
+        });
+        anchor.focus?.();
+      },
+      () => undefined,
+    );
+  }, [bannerHeightRef, scrollRef]);
+
+  const value = useMemo(
+    () => ({ errors, register, dismiss: onDismiss, jump }),
+    [errors, jump, onDismiss, register],
+  );
+
+  return (
+    <ErrorBannerContext.Provider value={value}>
+      {children}
+    </ErrorBannerContext.Provider>
+  );
+}
+
+export function ErrorBannerField({
+  name,
+  children,
+}: {
+  name: string;
+  children: ReactNode;
+}) {
+  const { viewRef } = useErrorBannerField(name);
+  return (
+    <View ref={viewRef} collapsable={false}>
+      {children}
+    </View>
+  );
+}

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

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  errorBannerOpen,
+  errorBannerTitle,
+  fieldScrollY,
+} from "./errorBannerCopy.ts";
+
+describe("errorBannerTitle", () => {
+  it("uses the singular line for one error", () => {
+    assert.equal(errorBannerTitle(1), "Nearly there. One thing to review");
+  });
+
+  it("counts several errors", () => {
+    assert.equal(errorBannerTitle(3), "Nearly there. 3 things to review");
+  });
+});
+
+describe("errorBannerOpen", () => {
+  it("stays closed with no errors", () => {
+    assert.equal(errorBannerOpen(0, false), false);
+  });
+
+  it("opens while errors remain and the runner has not dismissed it", () => {
+    assert.equal(errorBannerOpen(2, false), true);
+  });
+
+  it("closes when dismissed even if errors remain", () => {
+    assert.equal(errorBannerOpen(2, true), false);
+  });
+});
+
+describe("fieldScrollY", () => {
+  it("places the field below the banner", () => {
+    assert.equal(fieldScrollY(400, 120), 264);
+  });
+
+  it("does not scroll above the content", () => {
+    assert.equal(fieldScrollY(20, 120), 0);
+  });
+});

package/src/components/ErrorBanner/errorBannerCopy.ts

@@ -0,0 +1,22 @@
+/** Gap kept between the banner and a field scrolled into view. */
+export const ERROR_BANNER_SCROLL_GAP = 16;
+
+export function errorBannerTitle(count: number): string {
+  if (count === 1) {
+    return "Nearly there. One thing to review";
+  }
+  return `Nearly there. ${count} things to review`;
+}
+
+export function errorBannerOpen(errorCount: number, dismissed: boolean): boolean {
+  return errorCount > 0 && !dismissed;
+}
+
+/** Content y that places the field just below the banner. */
+export function fieldScrollY(
+  fieldY: number,
+  bannerHeight: number,
+  gap = ERROR_BANNER_SCROLL_GAP,
+): number {
+  return Math.max(0, fieldY - bannerHeight - gap);
+}

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

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { ERROR_BANNER_THEME_ROLES } from "./errorBannerThemeRoles.ts";
+
+describe("ERROR_BANNER_THEME_ROLES", () => {
+  it("maps colour props to banner roles", () => {
+    assert.equal(
+      ERROR_BANNER_THEME_ROLES.backgroundColor,
+      "errorBannerBackground",
+    );
+    assert.equal(ERROR_BANNER_THEME_ROLES.textColor, "errorBannerText");
+    assert.equal(
+      ERROR_BANNER_THEME_ROLES.secondaryColor,
+      "errorBannerSecondary",
+    );
+    assert.equal(ERROR_BANNER_THEME_ROLES.dividerColor, "errorBannerDivider");
+    assert.equal(ERROR_BANNER_THEME_ROLES.accentColor, "errorBannerAccent");
+  });
+});

package/src/components/ErrorBanner/errorBannerThemeRoles.ts

@@ -0,0 +1,9 @@
+export const ERROR_BANNER_THEME_ROLES = {
+  backgroundColor: "errorBannerBackground",
+  textColor: "errorBannerText",
+  secondaryColor: "errorBannerSecondary",
+  dividerColor: "errorBannerDivider",
+  accentColor: "errorBannerAccent",
+} as const;
+
+export type ErrorBannerThemeColorProp = keyof typeof ERROR_BANNER_THEME_ROLES;

package/src/components/ErrorBanner/icons.tsx

@@ -0,0 +1,38 @@
+import Svg, { Line, Path, Polyline } from "react-native-svg";
+
+export function Megaphone({ color }: { color: string }) {
+  return (
+    <Svg
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      strokeWidth={1.8}
+    >
+      <Path
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        d="M10.34 15.84c-.688-.06-1.386-.09-2.09-.09H7.5a4.5 4.5 0 1 1 0-9h.75c.704 0 1.402-.03 2.09-.09m0 9.18c.253.962.584 1.892.985 2.783.247.55.06 1.21-.463 1.511l-.657.38c-.551.318-1.26.117-1.527-.461a20.845 20.845 0 0 1-1.44-4.282m3.102.069a18.03 18.03 0 0 1-.59-4.59c0-1.586.205-3.124.59-4.59m0 9.18a23.848 23.848 0 0 1 8.835 2.535M10.34 6.66a23.847 23.847 0 0 0 8.835-2.535m0 0A23.74 23.74 0 0 0 18.795 3m.38 1.125a23.91 23.91 0 0 1 1.014 5.395m-1.014 8.855c-.118.38-.245.754-.38 1.125m.38-1.125a23.91 23.91 0 0 0 1.014-5.395m0-3.46c.495.413.811 1.035.811 1.73 0 .695-.316 1.317-.811 1.73m0-3.46a24.347 24.347 0 0 1 0 3.46"
+      />
+    </Svg>
+  );
+}
+
+export function ArrowRight({ color }: { color: string }) {
+  return (
+    <Svg
+      width={18}
+      height={18}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke={color}
+      strokeWidth={2.25}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <Line x1={5} y1={12} x2={19} y2={12} />
+      <Polyline points="13 6 19 12 13 18" />
+    </Svg>
+  );
+}

package/src/components/ErrorBanner/index.ts

@@ -0,0 +1,14 @@
+export { ErrorBanner } from "./ErrorBanner";
+export {
+  ErrorBannerField,
+  ErrorBannerProvider,
+  useErrorBannerContext,
+  useErrorBannerDismiss,
+  useErrorBannerField,
+} from "./errorBannerContext";
+export {
+  ERROR_BANNER_THEME_ROLES,
+  type ErrorBannerThemeColorProp,
+} from "./errorBannerThemeRoles";
+export { useErrorBanner } from "./useErrorBanner";
+export type { ErrorBannerProps, FieldError } from "./types";

package/src/components/ErrorBanner/types.ts

@@ -0,0 +1,31 @@
+export type FieldError = {
+  /** Matches the field `name`. */
+  field: string;
+  /** Banner row, about 40 characters. */
+  short: string;
+  /** Fuller sentence for the field's accessibility hint. */
+  message: string;
+};
+
+export type ErrorBannerProps = {
+  open: boolean;
+  errors: readonly FieldError[];
+  /** Scroll the field into view. The banner stays open until dismiss or an edit. */
+  onJump: (field: string) => void;
+  onDismiss: () => void;
+  /** Reported so the host can scroll the field clear of the banner. */
+  onHeightChange?: (height: number) => void;
+  /** Override `useSafeAreaInsets().top`. */
+  safeAreaTop?: number;
+  paddingHorizontal?: number;
+  /** Defaults to theme role `errorBannerBackground`. */
+  backgroundColor?: string;
+  /** Defaults to theme role `errorBannerText`. */
+  textColor?: string;
+  /** Defaults to theme role `errorBannerSecondary`. Dismiss and arrows. */
+  secondaryColor?: string;
+  /** Defaults to theme role `errorBannerDivider`. */
+  dividerColor?: string;
+  /** Defaults to theme role `errorBannerAccent`. Megaphone disc. */
+  accentColor?: string;
+};

package/src/components/ErrorBanner/useErrorBanner.ts

@@ -0,0 +1,33 @@
+import { useCallback, useEffect, useState } from "react";
+import { errorBannerOpen } from "./errorBannerCopy";
+import type { FieldError } from "./types";
+
+/**
+ * Open / dismiss state for a field-error banner.
+ * Call `present` when the runner submits. Call `dismiss` when they close it
+ * or edit the form. A cleared error list resets dismiss so the next failure
+ * can show the banner again.
+ */
+export function useErrorBanner(errors: readonly FieldError[]) {
+  const [dismissed, setDismissed] = useState(false);
+
+  useEffect(() => {
+    if (errors.length === 0) {
+      setDismissed(false);
+    }
+  }, [errors.length]);
+
+  const dismiss = useCallback(() => {
+    setDismissed(true);
+  }, []);
+
+  const present = useCallback(() => {
+    setDismissed(false);
+  }, []);
+
+  return {
+    open: errorBannerOpen(errors.length, dismissed),
+    dismiss,
+    present,
+  };
+}

package/src/components/Field/fieldChrome.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useRef, useState } from "react";
 import {
   StyleSheet,
   Text,
@@ -8,6 +8,10 @@ import {
   type TextInputProps,
 } from "react-native";
 import { buttonRadiusValue } from "../Button/buttonRadius";
+import {
+  useErrorBannerDismiss,
+  useErrorBannerField,
+} from "../ErrorBanner";
 import { FIELD_THEME_ROLES } from "./fieldThemeRoles";
 import {
   resolveFieldBorder,
@@ -24,6 +28,7 @@ export type FieldChromeProps = FieldSharedProps & {
 };
 
 export function FieldChrome({
+  name,
   value,
   onChangeText,
   borderColor: borderColorProp,
@@ -89,8 +94,14 @@ export function FieldChrome({
     FIELD_THEME_ROLES.descriptionColor,
   );
 
+  const inputRef = useRef<TextInput>(null);
+  const dismissBanner = useErrorBannerDismiss();
+  const { viewRef, listed } = useErrorBannerField(name, () =>
+    inputRef.current?.focus(),
+  );
   const [isFocused, setIsFocused] = useState(false);
-  const hasError = Boolean(error);
+  const hasError = Boolean(error) || Boolean(listed);
+  const inlineError = listed ? undefined : error;
   const showClear = shouldShowFieldClear(value, clearIcon != null, editable);
   const border = resolveFieldBorder({
     isFocused,
@@ -107,15 +118,29 @@ export function FieldChrome({
   };
 
   return (
-    <View style={[styles.column, !editable && styles.blocked, style]}>
+    <View
+      ref={viewRef}
+      collapsable={false}
+      style={[styles.column, !editable && styles.blocked, style]}
+    >
       {label ? (
         <Text style={[styles.label, { color: labelColor }]}>{label}</Text>
       ) : null}
       <View style={styles.inputWrapper}>
         <TextInput
-          ref={ref}
+          ref={(node) => {
+            inputRef.current = node;
+            if (typeof ref === "function") {
+              ref(node);
+            } else if (ref) {
+              ref.current = node;
+            }
+          }}
           value={value}
-          onChangeText={onChangeText}
+          onChangeText={(text) => {
+            onChangeText(text);
+            dismissBanner();
+          }}
           placeholder={placeholder}
           placeholderTextColor={placeholderColor}
           editable={editable}
@@ -127,6 +152,7 @@ export function FieldChrome({
           autoCapitalize={autoCapitalize}
           autoComplete={autoComplete}
           textContentType={textContentType}
+          accessibilityHint={listed?.message}
           accessibilityLabel={label}
           accessibilityState={{ disabled: !editable }}
           onFocus={(e) => {
@@ -167,8 +193,8 @@ export function FieldChrome({
           </TouchableOpacity>
         ) : null}
       </View>
-      {error ? (
-        <Text style={[styles.helper, { color: errorColor }]}>{error}</Text>
+      {inlineError ? (
+        <Text style={[styles.helper, { color: errorColor }]}>{inlineError}</Text>
       ) : description ? (
         <Text style={[styles.helper, { color: descriptionColor }]}>
           {description}

package/src/components/Field/types.ts

@@ -8,6 +8,8 @@ import type {
 import type { ButtonRadius } from "../Button/buttonRadius";
 
 export type FieldSharedProps = {
+  /** Registers the field with `Form` / `ErrorBannerProvider` for banner rows. */
+  name?: string;
   value: string;
   onChangeText: (text: string) => void;
   /** Defaults to theme role `fieldBorder`. */

package/src/components/Form/Form.tsx

@@ -1,4 +1,4 @@
-import { useState, type ReactNode } from "react";
+import { useRef, useState, type ReactNode } from "react";
 import {
   StyleSheet,
   Text,
@@ -8,7 +8,15 @@ import {
 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";
@@ -20,6 +28,29 @@ 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;
 
@@ -34,6 +65,7 @@ export function Form({
   children,
   onClose,
   onSubmit,
+  errors = [],
   submitLabel = "Save",
   submitting = false,
   submitDisabled = false,
@@ -61,6 +93,9 @@ export function Form({
     buttonLabelColorProp,
     "buttonLabel",
   );
+  const scrollRef = useRef<KeyboardAwareScrollViewRef>(null);
+  const bannerHeightRef = useRef(0);
+  const banner = useErrorBanner(errors);
   const [footerHeight, setFooterHeight] = useState(0);
   const [cancelWidth, setCancelWidth] = useState(0);
   const [barHeight, setBarHeight] = useState(0);
@@ -76,8 +111,15 @@ export function Form({
   );
 
   return (
+    <ErrorBannerProvider
+      bannerHeightRef={bannerHeightRef}
+      errors={errors}
+      onDismiss={banner.dismiss}
+      scrollRef={scrollRef}
+    >
     <View style={[styles.screen, { backgroundColor: background }]}>
       <KeyboardAwareScrollView
+        ref={scrollRef}
         automaticallyAdjustKeyboardInsets={false}
         bottomOffset={footerHeight + FIELD_GAP + FIELD_BELOW_CARET}
         contentContainerStyle={[
@@ -154,14 +196,26 @@ export function Form({
               label={submitLabel}
               labelColor={buttonLabel}
               loading={submitting}
-              onPress={onSubmit}
+              onPress={() => {
+                banner.present();
+                onSubmit();
+              }}
               radius={submitRadius}
             />
           </View>
           <View style={{ height: insets.bottom }} />
         </View>
       </KeyboardStickyView>
+      <FormErrorBanner
+        errors={errors}
+        onDismiss={banner.dismiss}
+        onHeightChange={(height) => {
+          bannerHeightRef.current = height;
+        }}
+        open={banner.open}
+      />
     </View>
+    </ErrorBannerProvider>
   );
 }
 

package/src/components/Form/types.ts

@@ -1,11 +1,18 @@
 import type { ReactNode } from "react";
 import type { ButtonRadius } from "../Button/buttonRadius";
+import type { FieldError } from "../ErrorBanner/types";
 
 export type FormProps = {
   title: string;
   children: ReactNode;
   onClose: () => void;
   onSubmit: () => void;
+  /**
+   * Field errors for the screen banner. Empty hides it.
+   * Set these when submit fails. Editing a field dismisses the banner;
+   * the next submit shows it again.
+   */
+  errors?: readonly FieldError[];
   submitLabel?: string;
   submitting?: boolean;
   submitDisabled?: boolean;

package/src/components/RadioField/RadioField.tsx

@@ -5,6 +5,7 @@ import {
   View,
 } from "react-native";
 import { buttonRadiusValue } from "../Button/buttonRadius";
+import { useErrorBannerDismiss } from "../ErrorBanner";
 import { useResolvedFieldColor } from "../Field/useResolvedFieldColor";
 import { RadioMark } from "./RadioMark";
 import { RADIO_THEME_ROLES } from "./radioThemeRoles";
@@ -55,6 +56,7 @@ export function RadioField<T extends string = string>({
     titleColorProp,
     RADIO_THEME_ROLES.titleColor,
   );
+  const dismissBanner = useErrorBannerDismiss();
   const borderRadius = buttonRadiusValue(radius);
 
   if (options.length === 0) {
@@ -97,7 +99,10 @@ export function RadioField<T extends string = string>({
                 }}
                 activeOpacity={0.75}
                 disabled={option.disabled}
-                onPress={() => onChange(option.value)}
+                onPress={() => {
+                  onChange(option.value);
+                  dismissBanner();
+                }}
                 style={[styles.row, option.disabled && styles.blocked]}
               >
                 <View style={styles.textCol}>

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -7,6 +7,7 @@ import Animated, {
   withTiming,
 } from "react-native-reanimated";
 import { buttonRadiusValue } from "../Button/buttonRadius";
+import { useErrorBannerDismiss } from "../ErrorBanner";
 import { useResolvedFieldColor } from "../Field/useResolvedFieldColor";
 import {
   resolveSegmentIndex,
@@ -26,7 +27,6 @@ export function SegmentedControl<T extends string = string>({
   radius = "lg",
   disabled = false,
   backgroundColor: backgroundColorProp,
-  borderColor: borderColorProp,
   selectedBackgroundColor: selectedBackgroundColorProp,
   labelColor: labelColorProp,
   selectedLabelColor: selectedLabelColorProp,
@@ -37,10 +37,6 @@ export function SegmentedControl<T extends string = string>({
     backgroundColorProp,
     SEGMENTED_THEME_ROLES.backgroundColor,
   );
-  const borderColor = useResolvedFieldColor(
-    borderColorProp,
-    SEGMENTED_THEME_ROLES.borderColor,
-  );
   const selectedBackgroundColor = useResolvedFieldColor(
     selectedBackgroundColorProp,
     SEGMENTED_THEME_ROLES.selectedBackgroundColor,
@@ -65,6 +61,7 @@ export function SegmentedControl<T extends string = string>({
   const widthSV = useSharedValue(0);
   const opacitySV = useSharedValue(0);
 
+  const dismissBanner = useErrorBannerDismiss();
   const borderRadius = buttonRadiusValue(radius);
   const pillRadius = Math.max(0, borderRadius - SEGMENT_INSET);
 
@@ -113,10 +110,7 @@ export function SegmentedControl<T extends string = string>({
       <View
         accessibilityLabel={label}
         accessibilityRole="radiogroup"
-        style={[
-          styles.track,
-          { backgroundColor, borderColor, borderRadius },
-        ]}
+        style={[styles.track, { backgroundColor, borderRadius }]}
       >
         <Animated.View
           pointerEvents="none"
@@ -158,7 +152,10 @@ export function SegmentedControl<T extends string = string>({
                   disabled: blocked,
                 }}
                 disabled={blocked}
-                onPress={() => onChange(option.value)}
+                onPress={() => {
+                  onChange(option.value);
+                  dismissBanner();
+                }}
                 style={({ pressed }) => [
                   styles.segment,
                   pressed && !blocked && styles.pressed,
@@ -200,7 +197,6 @@ const styles = StyleSheet.create({
   },
   track: {
     width: "100%",
-    borderWidth: 1,
     padding: SEGMENT_INSET,
     overflow: "hidden",
   },