react-native-terra-ui 0.11.4 → 0.11.6

package/src/components/input/parts/InputField.tsx

@@ -0,0 +1,138 @@
+import { type ComponentRef, forwardRef, useCallback, useState } from "react";
+import { TextInput, View } from "react-native";
+
+import { StyleSheet, useUnistyles } from "react-native-unistyles";
+
+import type { ColorToken, RadiusKey } from "#theme/types";
+import { resolveThemeColor } from "#utils/resolve-theme-color";
+import { FONT_WEIGHT_VALUE } from "#utils/typography";
+import type { InputBaseProps, InputSize } from "../types";
+
+/** Typographic role of the text, per size. */
+const TEXT_VARIANT: Record<InputSize, "body-sm" | "body-md" | "body-lg"> = {
+  sm: "body-sm",
+  md: "body-md",
+  lg: "body-lg",
+};
+
+/**
+ * The field every input in the family renders: a themed container with optional
+ * leading and trailing slots around a native `TextInput`. Internal — consumers
+ * reach it through `Input` or one of its variants.
+ */
+export const InputField = forwardRef<ComponentRef<typeof TextInput>, InputBaseProps>(function InputField(
+  {
+    size = "md",
+    isDisabled = false,
+    isInvalid = false,
+    leading,
+    trailing,
+    background = "surface.sunken",
+    radius = "lg",
+    style,
+    onFocus,
+    onBlur,
+    ...rest
+  },
+  ref
+) {
+  // The focus ring is a style decision, so it stays a variant; only the
+  // placeholder colour has to leave the stylesheet, because `TextInput` takes it
+  // as a prop rather than as a style.
+  const [isFocused, setIsFocused] = useState(false);
+  const { theme } = useUnistyles();
+
+  const handleFocus = useCallback<NonNullable<InputBaseProps["onFocus"]>>(
+    (event) => {
+      setIsFocused(true);
+      onFocus?.(event);
+    },
+    [onFocus]
+  );
+
+  const handleBlur = useCallback<NonNullable<InputBaseProps["onBlur"]>>(
+    (event) => {
+      setIsFocused(false);
+      onBlur?.(event);
+    },
+    [onBlur]
+  );
+
+  styles.useVariants({ size, disabled: isDisabled, invalid: isInvalid, focused: isFocused && !isDisabled });
+
+  return (
+    <View style={[styles.container, styles.fill(background, radius), style]}>
+      {leading}
+      <TextInput
+        ref={ref}
+        editable={!isDisabled}
+        placeholderTextColor={theme.color["text.tertiary"]}
+        style={styles.input}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        {...rest}
+      />
+      {trailing}
+    </View>
+  );
+});
+
+const styles = StyleSheet.create((theme) => ({
+  container: {
+    flexDirection: "row",
+    alignItems: "center",
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: theme.color["border.subtle"],
+    variants: {
+      size: {
+        sm: { height: 36, paddingHorizontal: theme.spacing["4"], gap: 6 },
+        md: { height: 44, paddingHorizontal: theme.spacing["4"], gap: 6 },
+        lg: { height: 52, paddingHorizontal: theme.spacing["4"], gap: 6 },
+      },
+      focused: {
+        true: { borderColor: theme.color["accent.border"] },
+        false: {},
+      },
+      invalid: {
+        true: { borderColor: theme.color["danger.text"] },
+        false: {},
+      },
+      disabled: {
+        true: { opacity: theme.opacity.disabled },
+        false: {},
+      },
+    },
+  },
+  // `background` is an open `ColorToken` and `radius` an eight-step scale, so
+  // both resolve in a dynamic function rather than enumerating as variants.
+  fill: (background: ColorToken, radius: RadiusKey) => ({
+    backgroundColor: resolveThemeColor(background, theme),
+    borderRadius: theme.radius[radius],
+  }),
+  input: {
+    flex: 1,
+    // Android centres text in a taller box by default; zeroing the padding lets
+    // the container's own height own the geometry on both platforms.
+    paddingVertical: 0,
+    color: theme.color["text.primary"],
+    variants: {
+      size: {
+        sm: {
+          fontSize: theme.typography.variants[TEXT_VARIANT.sm].fontSize,
+          fontWeight: FONT_WEIGHT_VALUE[theme.typography.variants[TEXT_VARIANT.sm].fontWeight],
+        },
+        md: {
+          fontSize: theme.typography.variants[TEXT_VARIANT.md].fontSize,
+          fontWeight: FONT_WEIGHT_VALUE[theme.typography.variants[TEXT_VARIANT.md].fontWeight],
+        },
+        lg: {
+          fontSize: theme.typography.variants[TEXT_VARIANT.lg].fontSize,
+          fontWeight: FONT_WEIGHT_VALUE[theme.typography.variants[TEXT_VARIANT.lg].fontWeight],
+        },
+      },
+      focused: { true: {}, false: {} },
+      invalid: { true: {}, false: {} },
+      disabled: { true: {}, false: {} },
+    },
+  },
+}));

package/src/components/input/types.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from "react";
+import type { StyleProp, TextInputProps, ViewStyle } from "react-native";
+
+import type { ColorToken, RadiusKey } from "#theme/types";
+
+/** Field height and typography step. */
+export type InputSize = "sm" | "md" | "lg";
+
+/**
+ * Props shared by every input in the family. `style` reaches the field's
+ * container rather than the native `TextInput`, matching the rest of the
+ * library — the text itself is themed from `size`.
+ */
+export interface InputBaseProps extends Omit<TextInputProps, "style" | "editable"> {
+  /** Field height and text step. Defaults to `'md'`. */
+  size?: InputSize;
+  /** Blocks typing and dims the field. Defaults to `false`. */
+  isDisabled?: boolean;
+  /** Paints the border in the danger tone. Defaults to `false`. */
+  isInvalid?: boolean;
+  /** Content pinned before the text, e.g. an `Icon`. */
+  leading?: ReactNode;
+  /** Content pinned after the text, e.g. a unit or a button. */
+  trailing?: ReactNode;
+  /** Fill token. Defaults to `'surface.sunken'`. */
+  background?: ColorToken;
+  /** Corner radius. Defaults to `'md'`. */
+  radius?: RadiusKey;
+  /** Merged over the container's own style. */
+  style?: StyleProp<ViewStyle>;
+}

package/src/components/input/variants/SearchInput/index.tsx

@@ -0,0 +1,118 @@
+import { type ComponentRef, forwardRef, useCallback, useState } from "react";
+import { Pressable, type TextInput } from "react-native";
+
+import { StyleSheet } from "react-native-unistyles";
+
+import { Icon } from "../../../icon";
+import { InputField } from "../../parts/InputField";
+import type { InputBaseProps } from "../../types";
+
+/** Glyph size per field size, in dp. */
+const ICON_SIZE = { sm: 16, md: 18, lg: 20 } as const;
+
+/** Touch expansion around the clear button, in dp — it is smaller than a cell. */
+const CLEAR_HIT_SLOP = 8;
+
+export interface SearchInputProps extends Omit<InputBaseProps, "leading" | "trailing"> {
+  /**
+   * Called after the clear button empties the field. `onChangeText` fires with
+   * an empty string first, so a controlled field needs no extra wiring.
+   */
+  onClear?: () => void;
+  /** Show the clear button once there is text. Defaults to `true`. */
+  isClearable?: boolean;
+  /** Accessible name of the clear button. Defaults to `'Clear search'`. */
+  clearAccessibilityLabel?: string;
+}
+
+/**
+ * A search field: a leading magnifier, and a clear button that appears as soon
+ * as there is text. Controlled through `value` or left to manage its own, and
+ * it defaults to the search return key so the keyboard reads correctly.
+ *
+ * @example
+ * ```tsx
+ * <Input.Search value={query} onChangeText={setQuery} onSubmitEditing={run} />
+ * ```
+ */
+export const SearchInput = forwardRef<ComponentRef<typeof TextInput>, SearchInputProps>(function SearchInput(
+  {
+    value,
+    defaultValue,
+    onChangeText,
+    onClear,
+    isClearable = true,
+    clearAccessibilityLabel = "Clear search",
+    placeholder = "Search",
+    isDisabled = false,
+    size = "md",
+    radius = "full",
+    returnKeyType = "search",
+    clearButtonMode = "never",
+    ...rest
+  },
+  ref
+) {
+  // The clear button only exists while there is text, so an uncontrolled field
+  // still has to be tracked. That state also has to drive the native input:
+  // resetting it alone would hide the button while the text stayed on screen,
+  // so `TextInput` is always handed a `value`, seeded from `defaultValue` when
+  // the caller does not own one.
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? "");
+  const isControlled = value !== undefined;
+  const text = isControlled ? value : uncontrolledValue;
+
+  const handleChangeText = useCallback(
+    (next: string) => {
+      if (!isControlled) setUncontrolledValue(next);
+      onChangeText?.(next);
+    },
+    [isControlled, onChangeText]
+  );
+
+  const handleClear = useCallback(() => {
+    if (!isControlled) setUncontrolledValue("");
+    onChangeText?.("");
+    onClear?.();
+  }, [isControlled, onChangeText, onClear]);
+
+  const hasText = text.length > 0;
+
+  return (
+    <InputField
+      ref={ref}
+      size={size}
+      radius={radius}
+      isDisabled={isDisabled}
+      placeholder={placeholder}
+      returnKeyType={returnKeyType}
+      // iOS's native clear button would sit beside ours; ours is the
+      // cross-platform one, so the native affordance stays off by default.
+      clearButtonMode={clearButtonMode}
+      value={text}
+      onChangeText={handleChangeText}
+      leading={<Icon name="terra.search" size={ICON_SIZE[size]} color="text.tertiary" />}
+      trailing={
+        isClearable && hasText && !isDisabled ? (
+          <Pressable
+            accessibilityLabel={clearAccessibilityLabel}
+            accessibilityRole="button"
+            hitSlop={CLEAR_HIT_SLOP}
+            onPress={handleClear}
+            style={styles.clear}
+          >
+            <Icon name="terra.x" size={ICON_SIZE[size]} color="text.tertiary" />
+          </Pressable>
+        ) : undefined
+      }
+      {...rest}
+    />
+  );
+});
+
+const styles = StyleSheet.create(() => ({
+  clear: {
+    alignItems: "center",
+    justifyContent: "center",
+  },
+}));

package/src/components/screen/ScreenContext.tsx

@@ -63,6 +63,21 @@ export interface ScreenContextValue {
   margins: ScreenContentPadding;
   /** Whether a `Screen.Header` is present. Used by scroll containers to add top inset. */
   hasHeader: boolean;
+  /**
+   * Measured height (dp) of the pinned accessory a header renders below its bar
+   * — a search field, a tab strip. Zero when there is none.
+   *
+   * The theme header height covers the bar alone, and an accessory is whatever
+   * the caller put there, so scroll containers reserve this on top of it. That
+   * is why it is measured rather than declared: only the accessory knows how
+   * tall it is, and it can change with Dynamic Type or its own content.
+   */
+  headerAccessoryHeight: number;
+  /**
+   * Reports the measured accessory height. Called by the header that owns the
+   * accessory; zero releases the reserved space.
+   */
+  setHeaderAccessoryHeight: (height: number) => void;
   /** Vertical scroll offset, updated on the UI thread for header animations. */
   scrollY: SharedValue<number>;
   /**
@@ -126,6 +141,7 @@ export function ScreenScrollProvider({
   hasHeader = false,
 }: ScreenScrollProviderProps) {
   const scrollY = useSharedValue(0);
+  const [headerAccessoryHeight, setAccessoryHeight] = useState(0);
   const headerCollapseHeight = useSharedValue(0);
   const [headerSnapOffsets, setHeaderSnapOffsets] = useState<number[]>();
   const scrollRef = useAnimatedRef<Animated.ScrollView>();
@@ -139,6 +155,12 @@ export function ScreenScrollProvider({
     [headerCollapseHeight]
   );
 
+  // Rounded so a subpixel layout measurement cannot loop the content padding
+  // against the layout that produced it.
+  const setHeaderAccessoryHeight = useCallback((height: number) => {
+    setAccessoryHeight(Math.max(0, Math.round(height)));
+  }, []);
+
   const scrollHandler = useAnimatedScrollHandler({
     onScroll: (event) => {
       scrollY.value = event.contentOffset.y;
@@ -155,6 +177,8 @@ export function ScreenScrollProvider({
       platformInsetsEligible,
       margins: contentPadding,
       hasHeader,
+      headerAccessoryHeight,
+      setHeaderAccessoryHeight,
       scrollY,
       headerCollapseHeight,
       headerSnapOffsets,
@@ -170,6 +194,8 @@ export function ScreenScrollProvider({
       platformAdjustsInsets,
       platformInsetsEligible,
       hasHeader,
+      headerAccessoryHeight,
+      setHeaderAccessoryHeight,
       scrollY,
       headerCollapseHeight,
       headerSnapOffsets,

package/src/components/screen/ScreenList.tsx

@@ -174,6 +174,7 @@ const ScreenListBase = forwardRef(function ScreenList(
     headerSnapOffsets,
     contentPadding: screenPadding,
     hasHeader,
+    headerAccessoryHeight,
     contentOwnsBottomInset,
     platformAdjustsInsets,
   } = useScreen();
@@ -224,7 +225,7 @@ const ScreenListBase = forwardRef(function ScreenList(
       automaticallyAdjustContentInsets={false}
       automaticallyAdjustsScrollIndicatorInsets={false}
       contentContainerStyle={[
-        styles.content(resolvedPadding, hasHeader, bottomInset, extraBottomPadding),
+        styles.content(resolvedPadding, hasHeader, bottomInset, extraBottomPadding, headerAccessoryHeight),
         contentContainerStyle,
       ]}
       ListHeaderComponent={header}
@@ -265,12 +266,16 @@ const styles = StyleSheet.create((theme, runtime) => ({
     padding: ScreenContentPadding,
     hasHeader: boolean,
     bottomInset: number | undefined,
-    extraBottomPadding: number
+    extraBottomPadding: number,
+    accessoryHeight: number
   ) => {
     const { x, y } = resolveScreenPadding(theme, runtime.breakpoint);
     return {
       flexGrow: 1,
-      paddingTop: (hasHeader ? theme.layout.header.height : 0) + (hasVerticalPadding(padding) ? y : 0),
+      // The theme height covers the bar; an accessory pinned under it is extra.
+      paddingTop:
+        (hasHeader ? theme.layout.header.height + accessoryHeight : 0) +
+        (hasVerticalPadding(padding) ? y : 0),
       paddingHorizontal: hasHorizontalPadding(padding) ? x : 0,
       paddingBottom: (bottomInset ?? (hasVerticalPadding(padding) ? y : 0)) + extraBottomPadding,
     };

package/src/components/screen/ScreenScrollView.tsx

@@ -71,6 +71,7 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
       scrollHandler,
       contentPadding: screenPadding,
       hasHeader,
+      headerAccessoryHeight,
       background,
       contentOwnsBottomInset,
       platformAdjustsInsets,
@@ -105,7 +106,7 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
         showsVerticalScrollIndicator={false}
         scrollEventThrottle={16}
         contentContainerStyle={[
-          styles.scrollContent(hasHeader, resolvedPadding, extraBottomPadding),
+          styles.scrollContent(hasHeader, resolvedPadding, extraBottomPadding, headerAccessoryHeight),
           contentContainerStyle,
         ]}
         {...rest}
@@ -124,11 +125,19 @@ export const ScreenScrollView = forwardRef<ComponentRef<typeof ScrollView>, Scre
 ScreenScrollView.displayName = "Screen.ScrollView";
 
 const styles = StyleSheet.create((theme, runtime) => ({
-  scrollContent: (hasHeader: boolean, padding: ScreenContentPadding, extraBottomPadding: number) => {
+  scrollContent: (
+    hasHeader: boolean,
+    padding: ScreenContentPadding,
+    extraBottomPadding: number,
+    accessoryHeight: number
+  ) => {
     const { x, y } = resolveScreenPadding(theme, runtime.breakpoint);
     return {
       flexGrow: 1,
-      paddingTop: (hasHeader ? theme.layout.header.height : 0) + (hasVerticalPadding(padding) ? y : 0),
+      // The theme height covers the bar; an accessory pinned under it is extra.
+      paddingTop:
+        (hasHeader ? theme.layout.header.height + accessoryHeight : 0) +
+        (hasVerticalPadding(padding) ? y : 0),
       paddingHorizontal: hasHorizontalPadding(padding) ? x : 0,
       paddingBottom: (hasVerticalPadding(padding) ? y : 0) + extraBottomPadding,
     };

package/src/components/toolbar/Toolbar.tsx

@@ -87,16 +87,21 @@ const LABEL_VARIANT = "label-md";
 
 // ─── Button ───────────────────────────────────────────────────────────────────
 
-interface ToolbarButtonBaseProps extends Omit<PressableProps, "children" | "style"> {
+interface ToolbarButtonBaseProps extends Omit<PressableProps, "children" | "style" | "disabled"> {
   /** Icon to render, before the label when both are given. */
   icon?: TerraIconName;
   /** Icon size in density-independent pixels. Defaults to `20`. */
   iconSize?: number;
   /**
    * Foreground token for the icon and label. Defaults to the group's `tint`,
-   * or `text.primary` outside a group.
+   * or `text.primary` outside a group. Ignored while `isDisabled`.
    */
   tint?: ColorToken;
+  /**
+   * Blocks presses and dims the cell, repainting the icon and label in
+   * `text.tertiary`. Defaults to `false`.
+   */
+  isDisabled?: boolean;
   /**
    * Fill. Defaults to `surface.default` standalone, and to `transparent`
    * inside a {@link ToolbarGroup}, which paints the shared capsule instead.
@@ -146,6 +151,7 @@ export function ToolbarButton({
   children,
   accessibilityLabel,
   onPress,
+  isDisabled = false,
   hitSlop = HIT_SLOP,
   style,
   ...rest
@@ -154,7 +160,9 @@ export function ToolbarButton({
 
   // Tokens, not resolved values: `Icon` and `Text` each resolve against the
   // live theme, so they keep their own subscriptions.
-  const fg = tint ?? groupTint;
+  // A disabled cell drops to the muted foreground, so an explicit `tint` — or a
+  // group's — cannot paint it as though it were still actionable.
+  const fg = isDisabled ? "text.tertiary" : (tint ?? groupTint);
   const bg = background ?? groupBackground;
   const shape = Children.count(children) > 0 ? "label" : "icon";
   // A grouped cell normally shrinks to its glyph, which is invisible while it is
@@ -177,12 +185,14 @@ export function ToolbarButton({
     <Pressable
       accessibilityLabel={accessibilityLabel}
       accessibilityRole="button"
+      accessibilityState={{ disabled: isDisabled }}
+      disabled={isDisabled}
       hitSlop={hitSlop}
-      onPress={onPress}
+      onPress={isDisabled ? undefined : onPress}
       {...rest}
       style={(state) => [
         cell,
-        styles.fill(bg, state.pressed),
+        styles.fill(bg, state.pressed, isDisabled),
         typeof style === "function" ? style(state) : style,
       ]}
     >
@@ -393,8 +403,8 @@ const styles = StyleSheet.create((theme) => ({
   },
   // Split from `button` so the open-ended fill and the press state stay in the
   // stylesheet without turning the geometry into a dynamic function too.
-  fill: (background: ColorToken, pressed: boolean) => ({
+  fill: (background: ColorToken, pressed: boolean, isDisabled: boolean) => ({
     backgroundColor: resolveThemeColor(background, theme),
-    opacity: pressed ? theme.opacity.pressed : 1,
+    opacity: isDisabled ? theme.opacity.disabled : pressed ? theme.opacity.pressed : 1,
   }),
 }));

package/src/theme/defaults/icons.tsx

@@ -126,12 +126,25 @@ export const PersonIcon: TerraIconComponent = (props) => {
   );
 };
 
+const SearchIcon: TerraIconComponent = (props) => {
+  const { color, size, strokeWidth } = resolveIconProps(props);
+  const stroke = strokeProps(color, strokeWidth);
+
+  return (
+    <SvgIcon size={size}>
+      <Circle cx={11} cy={11} r={7} {...stroke} />
+      <Path d="m20 20-3.9-3.9" {...stroke} />
+    </SvgIcon>
+  );
+};
+
 export const defaultIcons: Record<TerraSemanticIconName, TerraIconComponent> = {
   "terra.chevron-left": ChevronLeftIcon,
   "terra.chevron-right": ChevronRightIcon,
   "terra.x": XIcon,
   "terra.check": CheckIcon,
   "terra.person": PersonIcon,
+  "terra.search": SearchIcon,
   "status.info": InfoIcon,
   "status.success": SuccessIcon,
   "status.warning": WarningIcon,

package/src/theme/types.ts

@@ -393,6 +393,7 @@ export type TerraSemanticIconName =
   | "terra.x"
   | "terra.check"
   | "terra.person"
+  | "terra.search"
   | "status.info"
   | "status.success"
   | "status.warning"