react-native-terra-ui 0.9.0 → 0.10.0

package/src/components/screen/ScreenContext.tsx

@@ -37,6 +37,28 @@ export interface ScreenContextValue {
    * or a horizontal container needs.
    */
   contentOwnsBottomInset: boolean;
+  /**
+   * Whether the platform's own content-inset adjustment pays the vertical insets.
+   *
+   * True on an iOS screen with no `Screen.Header`: the navigation bar above such a
+   * screen is UIKit's, and only UIKit can inset a scroll view for one — a native
+   * large title resizes on every frame of its collapse, and it refuses to collapse
+   * at all for a scroll view that does not fill the screen. The frame therefore
+   * keeps no vertical edge, the container asks for
+   * `contentInsetAdjustmentBehavior: "automatic"` rather than `"never"`, and
+   * `contentOwnsBottomInset` stays false because UIKit pays that edge too.
+   */
+  platformAdjustsInsets: boolean;
+  /**
+   * Whether this screen *would* hand its vertical insets to the platform, if it
+   * found a vertical scroll container among its children.
+   *
+   * Everything `platformAdjustsInsets` needs except the container itself. The two
+   * differ only when the container is nested inside another component, where the
+   * root cannot see it — which is a mistake on such a screen, and the difference
+   * is how a mounting container detects that it was the one missed.
+   */
+  platformInsetsEligible: boolean;
   /** @deprecated Use contentPadding. */
   margins: ScreenContentPadding;
   /** Whether a `Screen.Header` is present. Used by scroll containers to add top inset. */
@@ -78,6 +100,10 @@ export interface ScreenScrollProviderProps {
   safeArea?: ScreenSafeArea;
   /** Whether the primary scroll container pads the bottom safe area. Default false. */
   contentOwnsBottomInset?: boolean;
+  /** Whether the platform adjusts the scroll container's vertical insets. Default false. */
+  platformAdjustsInsets?: boolean;
+  /** Whether the screen qualifies for that, container aside. Default false. */
+  platformInsetsEligible?: boolean;
   /** Whether a `Screen.Header` child is present. Default false. */
   hasHeader?: boolean;
 
@@ -95,6 +121,8 @@ export function ScreenScrollProvider({
   contentPadding = "all",
   safeArea = "auto",
   contentOwnsBottomInset = false,
+  platformAdjustsInsets = false,
+  platformInsetsEligible = false,
   hasHeader = false,
 }: ScreenScrollProviderProps) {
   const scrollY = useSharedValue(0);
@@ -123,6 +151,8 @@ export function ScreenScrollProvider({
       contentPadding,
       safeArea,
       contentOwnsBottomInset,
+      platformAdjustsInsets,
+      platformInsetsEligible,
       margins: contentPadding,
       hasHeader,
       scrollY,
@@ -137,6 +167,8 @@ export function ScreenScrollProvider({
       contentPadding,
       safeArea,
       contentOwnsBottomInset,
+      platformAdjustsInsets,
+      platformInsetsEligible,
       hasHeader,
       scrollY,
       headerCollapseHeight,

package/src/components/screen/ScreenList.tsx

@@ -16,6 +16,7 @@ import { StyleSheet } from "react-native-unistyles";
 
 import { resolveScreenPadding } from "#theme/screen-padding";
 import { PortalHost } from "../portal";
+import { useNestedContainerWarning } from "./hooks/use-nested-container-warning";
 import { useScreenRef } from "./hooks/use-screen-ref";
 import { useScreenScrollHandler } from "./hooks/use-screen-scroll-handler";
 import { ScreenBottomInset } from "./parts/ScreenBottomInset";
@@ -174,10 +175,12 @@ const ScreenListBase = forwardRef(function ScreenList(
     contentPadding: screenPadding,
     hasHeader,
     contentOwnsBottomInset,
+    platformAdjustsInsets,
   } = useScreen();
   // The root yields the bottom edge only to a vertical container, so a horizontal
   // one here is a secondary container and must not pay the inset a second time.
   const ownsBottomInset = contentOwnsBottomInset && !horizontal;
+  useNestedContainerWarning("Screen.List", horizontal);
   const mergedRef = useScreenRef(isDefaultFlatList ? scrollRef : undefined, ref);
   const resolvedPadding = contentPadding ?? margins ?? screenPadding;
   const resolvedLoading = isLoading ?? loading;
@@ -212,7 +215,12 @@ const ScreenListBase = forwardRef(function ScreenList(
       renderItem={renderItem}
       style={[{ backgroundColor: background }, style]}
       horizontal={horizontal}
-      contentInsetAdjustmentBehavior="never"
+      /*
+        UIKit owns the vertical insets on a header-less iOS screen — see
+        `platformAdjustsInsets`. Everywhere else the frame has already paid them,
+        so a second adjustment here would count them twice.
+      */
+      contentInsetAdjustmentBehavior={platformAdjustsInsets ? "automatic" : "never"}
       automaticallyAdjustContentInsets={false}
       automaticallyAdjustsScrollIndicatorInsets={false}
       contentContainerStyle={[

package/src/components/screen/ScreenScrollView.tsx

@@ -6,6 +6,7 @@ import { StyleSheet } from "react-native-unistyles";
 
 import { resolveScreenPadding } from "#theme/screen-padding";
 import { PortalHost } from "../portal";
+import { useNestedContainerWarning } from "./hooks/use-nested-container-warning";
 import { useScreenRef } from "./hooks/use-screen-ref";
 import { useScreenScrollHandler } from "./hooks/use-screen-scroll-handler";
 import { ScreenBottomInset } from "./parts/ScreenBottomInset";
@@ -72,10 +73,12 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
       hasHeader,
       background,
       contentOwnsBottomInset,
+      platformAdjustsInsets,
     } = useScreen();
     // The root yields the bottom edge only to a vertical container, so a horizontal
     // one here is a secondary container and must not pay the inset a second time.
     const ownsBottomInset = contentOwnsBottomInset && !horizontal;
+    useNestedContainerWarning("Screen.ScrollView", horizontal);
     const resolvedPadding = contentPadding ?? margins ?? screenPadding;
     const mergedRef = useScreenRef(scrollRef, ref);
     const placeholder = renderScreenPlaceholder({
@@ -91,7 +94,12 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
         ref={mergedRef}
         style={[{ backgroundColor: background }, style]}
         horizontal={horizontal}
-        contentInsetAdjustmentBehavior="never"
+        /*
+          UIKit owns the vertical insets on a header-less iOS screen — see
+          `platformAdjustsInsets`. Everywhere else the frame has already paid
+          them, so a second adjustment here would count them twice.
+        */
+        contentInsetAdjustmentBehavior={platformAdjustsInsets ? "automatic" : "never"}
         automaticallyAdjustContentInsets={false}
         automaticallyAdjustsScrollIndicatorInsets={false}
         showsVerticalScrollIndicator={false}

package/src/components/screen/hooks/use-nested-container-warning.ts

@@ -0,0 +1,40 @@
+import { useEffect } from "react";
+
+import { useScreen } from "../ScreenContext";
+
+/**
+ * Warns, in development, when this container is the one the screen root failed
+ * to find.
+ *
+ * The root inspects its own children and fragments but does not execute
+ * component children, so a container rendered inside one is invisible to it (see
+ * `hasScrollContainerOwningBottom`). On a header-less iOS screen that changes
+ * behaviour rather than just bookkeeping: the frame pads the top edge, the scroll
+ * view no longer fills the screen, and UIKit stops collapsing the native large
+ * title — silently, with the screen otherwise looking correct.
+ *
+ * The container is the only place that can tell. `platformInsetsEligible` says
+ * the screen qualified; a container mounting while `platformAdjustsInsets` is
+ * false says the root never saw it. Both true together mean exactly this mistake,
+ * so there is nothing here to false-positive on: a screen with no scroll
+ * container at all never runs this hook, and a deliberate `safeArea` opt-out is
+ * not eligible in the first place.
+ *
+ * @param container Name to report, e.g. `"Screen.List"`.
+ * @param horizontal Whether this container scrolls horizontally; those are never
+ *   candidates for the vertical insets and never warn.
+ */
+export function useNestedContainerWarning(container: string, horizontal: boolean): void {
+  const { platformAdjustsInsets, platformInsetsEligible } = useScreen();
+  const isNested = platformInsetsEligible && !platformAdjustsInsets && !horizontal;
+
+  useEffect(() => {
+    if (!__DEV__ || !isNested) return;
+    console.warn(
+      `[react-native-terra-ui] ${container} is nested inside another component, so its Screen could not find it. ` +
+        "On iOS a Screen with no Screen.Header hands its vertical insets to UIKit, but only when the scroll " +
+        "container is among its own children — nested, the frame pads the top instead and a native large title " +
+        `will not collapse. Render ${container} as a direct child of Screen; fragments are fine.`
+    );
+  }, [container, isNested]);
+}

package/src/components/screen/parts/ScreenFrame.tsx

@@ -19,7 +19,14 @@ export function ScreenFrame({ children, edges }: PropsWithChildren<{ edges: Scre
   return (
     <>
       <ScreenSafeArea edges={edges}>
-        <View style={styles.content} onLayout={onLayout}>
+        {/*
+          `collapsable={false}` for the same reason as the `Screen` root: whatever
+          Fabric decides about this view, its children have to stay inside it.
+          UIKit finds a screen's scroll view by walking first subviews down from
+          the view controller, and a mounted-but-childless view in that chain is a
+          dead end — the large title then never collapses.
+        */}
+        <View collapsable={false} style={styles.content} onLayout={onLayout}>
           {children}
         </View>
       </ScreenSafeArea>

package/src/components/toast/Toast.tsx

@@ -300,7 +300,7 @@ const ToastClose = forwardRef<ComponentRef<typeof Button>, ToastCloseProps>(func
     >
       {children ?? (
         <Icon
-          name="navigation.close"
+          name="terra.x"
           size={iconProps?.size ?? 20}
           color={iconProps?.color ?? colors.icon}
           strokeWidth={iconProps?.strokeWidth}

package/src/theme/defaults/icons.tsx

@@ -19,6 +19,11 @@ const strokeProps = (color: string, strokeWidth: number) => ({
   strokeLinejoin: "round" as const,
 });
 
+// Every registry icon draws through this: one 24×24 viewBox rendered at exactly
+// the requested `size`, so `<Icon size={24} />` is the same optical weight
+// whichever name it resolves to. A glyph that needs to sit smaller than its box
+// (Avatar's person fallback) asks for a smaller `size` — it must not shrink
+// itself here, or it would scale differently from every other icon.
 const SvgIcon = ({ size, children }: { size: number; children: React.ReactNode }) => (
   <Svg width={size} height={size} viewBox="0 0 24 24" fill="none">
     {children}
@@ -36,25 +41,25 @@ const PathIcon = ({ d, ...props }: TerraIconProps & { d: string }) => {
 };
 
 // Lucide chevron geometry scaled 20% from the 24×24 viewBox center (45° arms unchanged).
-const NAV_CENTER = 12;
-const NAV_CHEVRON_OPEN = 3 * 1.2;
-const NAV_CHEVRON_ARM = 6 * 1.2;
+const CHEVRON_CENTER = 12;
+const CHEVRON_OPEN = 3 * 1.2;
+const CHEVRON_ARM = 6 * 1.2;
 
-const BackIcon: TerraIconComponent = (props) => (
+const ChevronLeftIcon: TerraIconComponent = (props) => (
   <PathIcon
-    d={`M${NAV_CENTER + NAV_CHEVRON_OPEN} ${NAV_CENTER + NAV_CHEVRON_ARM}L${NAV_CENTER - NAV_CHEVRON_OPEN} ${NAV_CENTER} ${NAV_CENTER + NAV_CHEVRON_OPEN} ${NAV_CENTER - NAV_CHEVRON_ARM}`}
+    d={`M${CHEVRON_CENTER + CHEVRON_OPEN} ${CHEVRON_CENTER + CHEVRON_ARM}L${CHEVRON_CENTER - CHEVRON_OPEN} ${CHEVRON_CENTER} ${CHEVRON_CENTER + CHEVRON_OPEN} ${CHEVRON_CENTER - CHEVRON_ARM}`}
     {...props}
   />
 );
 
-const ForwardIcon: TerraIconComponent = (props) => (
+const ChevronRightIcon: TerraIconComponent = (props) => (
   <PathIcon
-    d={`M${NAV_CENTER - NAV_CHEVRON_OPEN} ${NAV_CENTER + NAV_CHEVRON_ARM}L${NAV_CENTER + NAV_CHEVRON_OPEN} ${NAV_CENTER} ${NAV_CENTER - NAV_CHEVRON_OPEN} ${NAV_CENTER - NAV_CHEVRON_ARM}`}
+    d={`M${CHEVRON_CENTER - CHEVRON_OPEN} ${CHEVRON_CENTER + CHEVRON_ARM}L${CHEVRON_CENTER + CHEVRON_OPEN} ${CHEVRON_CENTER} ${CHEVRON_CENTER - CHEVRON_OPEN} ${CHEVRON_CENTER - CHEVRON_ARM}`}
     {...props}
   />
 );
 
-const CloseIcon: TerraIconComponent = (props) => <PathIcon d="M18 6L6 18M6 6l12 12" {...props} />;
+const XIcon: TerraIconComponent = (props) => <PathIcon d="M18 6L6 18M6 6l12 12" {...props} />;
 
 const InfoIcon: TerraIconComponent = (props) => {
   const { color, size, strokeWidth } = resolveIconProps(props);
@@ -107,26 +112,28 @@ const DangerIcon: TerraIconComponent = (props) => {
   );
 };
 
+const CheckIcon: TerraIconComponent = (props) => <PathIcon d="M20 6 9 17l-5-5" {...props} />;
+
 export const PersonIcon: TerraIconComponent = (props) => {
   const { color, size, strokeWidth } = resolveIconProps(props);
   const stroke = strokeProps(color, strokeWidth);
-  const iconSize = size * 0.55;
 
   return (
-    <Svg width={iconSize} height={iconSize} viewBox="0 0 24 24" fill="none">
+    <SvgIcon size={size}>
       <Circle cx={12} cy={8} r={4} {...stroke} />
       <Path d="M4 20c0-4 3.582-7 8-7s8 3 8 7" {...stroke} />
-    </Svg>
+    </SvgIcon>
   );
 };
 
 export const defaultIcons: Record<TerraSemanticIconName, TerraIconComponent> = {
-  "navigation.back": BackIcon,
-  "navigation.forward": ForwardIcon,
-  "navigation.close": CloseIcon,
+  "terra.chevron-left": ChevronLeftIcon,
+  "terra.chevron-right": ChevronRightIcon,
+  "terra.x": XIcon,
+  "terra.check": CheckIcon,
+  "terra.person": PersonIcon,
   "status.info": InfoIcon,
   "status.success": SuccessIcon,
   "status.warning": WarningIcon,
   "status.danger": DangerIcon,
-  person: PersonIcon,
 };

package/src/theme/types.ts

@@ -412,14 +412,15 @@ declare global {
 export interface TerraIconRegistry extends TerraUI.IconRegistry {}
 
 export type TerraSemanticIconName =
-  | "navigation.back"
-  | "navigation.forward"
-  | "navigation.close"
+  | "terra.chevron-left"
+  | "terra.chevron-right"
+  | "terra.x"
+  | "terra.check"
+  | "terra.person"
   | "status.info"
   | "status.success"
   | "status.warning"
-  | "status.danger"
-  | "person";
+  | "status.danger";
 
 export type TerraConfiguredIconName = keyof TerraIconRegistry & string;