@studio-piot/native-ui 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studio-piot/native-ui",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Shared React Native components for Studio Piot apps.",
   "homepage": "https://github.com/Studio-Piot/studio-native-ui#readme",
   "bugs": {
@@ -58,7 +58,8 @@
     "react-native-keyboard-controller": ">=1.14.0",
     "react-native-reanimated": "^4.5.1",
     "react-native-safe-area-context": ">=4.0.0",
-    "react-native-screens": ">=4.0.0"
+    "react-native-screens": ">=4.0.0",
+    "react-native-svg": ">=15.0.0"
   },
   "scripts": {
     "test": "node --experimental-strip-types --test 'src/**/*.test.ts'",
@@ -78,6 +79,7 @@
     "react-native-reanimated": "^4.5.1",
     "react-native-safe-area-context": "~5.7.0",
     "react-native-screens": "~4.26.0",
+    "react-native-svg": "^15.15.4",
     "typescript": "^5.9.3"
   }
 }

package/src/components/ErrorBanner/ErrorBanner.tsx

@@ -0,0 +1,232 @@
+import { useEffect, useRef, useState } from "react";
+import {
+  AccessibilityInfo,
+  Animated,
+  Easing,
+  Pressable,
+  StatusBar,
+  StyleSheet,
+  Text,
+  View,
+  type LayoutChangeEvent,
+} from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { buttonRadiusValue } from "../Button/buttonRadius";
+import { useResolvedFieldColor } from "../Field/useResolvedFieldColor";
+import { screenPaddingHorizontal } from "../../layout/screenPadding";
+import { errorBannerTitle } from "./errorBannerCopy";
+import { ERROR_BANNER_THEME_ROLES } from "./errorBannerThemeRoles";
+import { ArrowRight, Megaphone } from "./icons";
+import type { ErrorBannerProps } from "./types";
+
+const BOTTOM_RADIUS = buttonRadiusValue("xl");
+
+/**
+ * Screen-wide field-error banner. Mount it once and drive `open` so the
+ * exit animation can play. It is not tied to a form shell: pass `errors`,
+ * `onJump`, and `onDismiss`. `Form` does that by default.
+ */
+export function ErrorBanner({
+  open,
+  errors,
+  onJump,
+  onDismiss,
+  onHeightChange,
+  safeAreaTop,
+  paddingHorizontal = screenPaddingHorizontal,
+  backgroundColor: backgroundColorProp,
+  textColor: textColorProp,
+  secondaryColor: secondaryColorProp,
+  dividerColor: dividerColorProp,
+  accentColor: accentColorProp,
+}: ErrorBannerProps) {
+  const insets = useSafeAreaInsets();
+  const topInset = safeAreaTop ?? insets.top;
+  const backgroundColor = useResolvedFieldColor(
+    backgroundColorProp,
+    ERROR_BANNER_THEME_ROLES.backgroundColor,
+  );
+  const textColor = useResolvedFieldColor(
+    textColorProp,
+    ERROR_BANNER_THEME_ROLES.textColor,
+  );
+  const secondaryColor = useResolvedFieldColor(
+    secondaryColorProp,
+    ERROR_BANNER_THEME_ROLES.secondaryColor,
+  );
+  const dividerColor = useResolvedFieldColor(
+    dividerColorProp,
+    ERROR_BANNER_THEME_ROLES.dividerColor,
+  );
+  const accentColor = useResolvedFieldColor(
+    accentColorProp,
+    ERROR_BANNER_THEME_ROLES.accentColor,
+  );
+
+  const [height, setHeight] = useState(400);
+  const [reduceMotion, setReduceMotion] = useState(false);
+  const progress = useRef(new Animated.Value(0)).current;
+  const count = errors.length;
+  const title = errorBannerTitle(count);
+  const titleRef = useRef(title);
+  titleRef.current = title;
+
+  useEffect(() => {
+    AccessibilityInfo.isReduceMotionEnabled().then(setReduceMotion);
+  }, []);
+
+  useEffect(() => {
+    Animated.timing(progress, {
+      toValue: open ? 1 : 0,
+      duration: reduceMotion ? 120 : open ? 260 : 200,
+      easing: Easing.bezier(0.16, 1, 0.3, 1),
+      useNativeDriver: true,
+    }).start();
+    if (open) {
+      AccessibilityInfo.announceForAccessibility(titleRef.current);
+    }
+  }, [open, progress, reduceMotion]);
+
+  const motion = reduceMotion
+    ? { opacity: progress }
+    : {
+        transform: [
+          {
+            translateY: progress.interpolate({
+              inputRange: [0, 1],
+              outputRange: [-(height + 24), 0],
+            }),
+          },
+        ],
+      };
+
+  const onLayout = (event: LayoutChangeEvent) => {
+    const next = Math.round(event.nativeEvent.layout.height);
+    setHeight((current) => (current === next ? current : next));
+    onHeightChange?.(next);
+  };
+
+  return (
+    <>
+      {open ? <StatusBar animated barStyle="light-content" /> : null}
+      <Animated.View
+        accessibilityRole="alert"
+        accessibilityElementsHidden={!open}
+        importantForAccessibility={open ? "auto" : "no-hide-descendants"}
+        onLayout={onLayout}
+        pointerEvents={open ? "auto" : "none"}
+        style={[
+          styles.banner,
+          {
+            backgroundColor,
+            paddingTop: topInset + 8,
+            paddingHorizontal,
+            borderBottomLeftRadius: BOTTOM_RADIUS,
+            borderBottomRightRadius: BOTTOM_RADIUS,
+          },
+          motion,
+        ]}
+      >
+        <View style={styles.header}>
+          <View
+            accessibilityElementsHidden
+            importantForAccessibility="no-hide-descendants"
+            style={[styles.iconDisc, { backgroundColor: accentColor }]}
+          >
+            <Megaphone color={backgroundColor} />
+          </View>
+          <Text style={[styles.title, { color: textColor }]}>{title}</Text>
+          <Pressable
+            accessibilityLabel="Dismiss"
+            accessibilityRole="button"
+            hitSlop={12}
+            onPress={onDismiss}
+          >
+            <Text style={[styles.dismiss, { color: secondaryColor }]}>✕</Text>
+          </Pressable>
+        </View>
+        <View style={styles.rows}>
+          {errors.map((error) => (
+            <Pressable
+              key={error.field}
+              accessibilityLabel={`${error.short}. Go to field.`}
+              accessibilityRole="button"
+              hitSlop={{ top: 4, bottom: 4 }}
+              onPress={() => onJump(error.field)}
+              style={({ pressed }) => [
+                styles.row,
+                { borderTopColor: dividerColor },
+                pressed && styles.pressed,
+              ]}
+            >
+              <Text style={[styles.rowLabel, { color: textColor }]}>
+                {error.short}
+              </Text>
+              <View
+                accessibilityElementsHidden
+                importantForAccessibility="no-hide-descendants"
+              >
+                <ArrowRight color={secondaryColor} />
+              </View>
+            </Pressable>
+          ))}
+        </View>
+      </Animated.View>
+    </>
+  );
+}
+
+const styles = StyleSheet.create({
+  banner: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    zIndex: 100,
+    paddingBottom: 10,
+    shadowColor: "#22201D",
+    shadowOpacity: 0.25,
+    shadowRadius: 12,
+    shadowOffset: { width: 0, height: 8 },
+    elevation: 12,
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 10,
+  },
+  iconDisc: {
+    width: 28,
+    height: 28,
+    borderRadius: 14,
+    alignItems: "center",
+    justifyContent: "center",
+  },
+  title: {
+    flex: 1,
+    fontSize: 15,
+    lineHeight: 20,
+    fontWeight: "600",
+  },
+  dismiss: {
+    fontSize: 15,
+  },
+  rows: {
+    marginTop: 6,
+  },
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    minHeight: 36,
+    marginLeft: 38,
+    borderTopWidth: 1,
+  },
+  pressed: {
+    opacity: 0.6,
+  },
+  rowLabel: {
+    flex: 1,
+    fontSize: 15,
+    lineHeight: 20,
+  },
+});

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