react-native-terra-ui 0.1.1 → 0.2.0

package/src/components/empty-state/index.ts

@@ -0,0 +1,3 @@
+export type { EmptyStateProps } from './EmptyState';
+export { EmptyState } from './EmptyState';
+export type { EmptyStateSize } from './types';

package/src/components/empty-state/types.ts

@@ -0,0 +1,5 @@
+/**
+ * Overall scale of an empty state — drives the icon size, the typography of the
+ * title/description, and the spacing between them.
+ */
+export type EmptyStateSize = 'sm' | 'md' | 'lg';

package/src/components/header/header-buttons.tsx

@@ -1,10 +1,34 @@
-import { Pressable } from 'react-native';
-
-import { StyleSheet, useUnistyles } from 'react-native-unistyles';
-
 import type { TerraSemanticIconName } from '#theme/types';
 
-import { Icon } from '../icon';
+import { Toolbar, type ToolbarButtonProps } from '../toolbar';
+
+/**
+ * @deprecated Use {@link Toolbar.Button}. `HeaderButton` is an alias kept for
+ * compatibility and renders identically; `Toolbar.Button` additionally goes
+ * transparent inside a `Toolbar.Group` so several actions can share one
+ * capsule.
+ */
+export type HeaderButtonProps = ToolbarButtonProps;
+
+/**
+ * @deprecated Use {@link Toolbar.Button}, which is the same component under a
+ * name that also covers toolbars outside a header.
+ *
+ * @example
+ * ```tsx
+ * <Header.Title
+ *   title="Inbox"
+ *   RightToolbar={
+ *     <Toolbar.Button
+ *       icon="status.info"
+ *       accessibilityLabel="Info"
+ *       onPress={showInfo}
+ *     />
+ *   }
+ * />
+ * ```
+ */
+export const HeaderButton = Toolbar.Button;
 
 export type HeaderDismissAction = 'back' | 'close' | 'none';
 
@@ -32,21 +56,11 @@ const getDismissIconName = (
 ): TerraSemanticIconName =>
   dismissAction === 'close' ? 'navigation.close' : 'navigation.back';
 
-const warnUnavailableDismiss = (dismissAction: HeaderDismissAction): void => {
-  if (__DEV__) {
-    console.warn(
-      `[react-native-terra-ui] Header.Title dismissAction="${dismissAction}" was pressed, but no dismiss handler or available navigation action was provided.`
-    );
-  }
-};
-
 export function HeaderDismissButton({
   dismissAction = 'none',
   navigation,
   onDismiss,
 }: HeaderDismissProps) {
-  const { theme } = useUnistyles();
-
   if (dismissAction === 'none') return null;
 
   const handlePress = () => {
@@ -64,40 +78,14 @@ export function HeaderDismissButton({
       navigation.goBack();
       return;
     }
-
-    warnUnavailableDismiss(dismissAction);
   };
 
   return (
-    <Pressable
+    <Toolbar.Button
+      icon={getDismissIconName(dismissAction)}
+      iconSize={24}
       accessibilityLabel={getDismissAccessibilityLabel(dismissAction)}
-      accessibilityRole="button"
-      hitSlop={8}
       onPress={handlePress}
-      style={({ pressed }) => [
-        styles.button,
-        pressed ? { opacity: theme.opacity.pressed } : null,
-      ]}
-    >
-      <Icon
-        size={26}
-        color="text.default"
-        name={getDismissIconName(dismissAction)}
-      />
-    </Pressable>
+    />
   );
 }
-
-const styles = StyleSheet.create((theme) => ({
-  button: {
-    width: 36,
-    height: 36,
-    borderRadius: theme.radius.full,
-    backgroundColor:
-      (theme.color as unknown as Record<string, string | undefined>)[
-        'surface.default'
-      ] ?? '',
-    alignItems: 'center',
-    justifyContent: 'center',
-  },
-}));

package/src/components/header/index.ts

@@ -1,5 +1,7 @@
 export { Header } from './Header';
 export {
+  HeaderButton,
+  type HeaderButtonProps,
   type HeaderDismissAction,
   HeaderDismissButton,
   type HeaderDismissNavigation,

package/src/components/header/parts/HeaderGradientOverlay.tsx

@@ -0,0 +1,29 @@
+import { useId } from 'react';
+import Svg, {
+  Defs,
+  Rect,
+  Stop,
+  LinearGradient as SvgLinearGradient,
+} from 'react-native-svg';
+
+export interface HeaderGradientOverlayProps {
+  /** Fill color, fading from fully opaque to 90% opacity along the gradient. */
+  color: string;
+}
+
+/** Vertical fade-out overlay behind header content, shared by header variants. */
+export function HeaderGradientOverlay({ color }: HeaderGradientOverlayProps) {
+  const gradientId = useId();
+
+  return (
+    <Svg height="100%" width="100%">
+      <Defs>
+        <SvgLinearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
+          <Stop offset="0" stopColor={color} stopOpacity="1" />
+          <Stop offset="1" stopColor={color} stopOpacity="0.9" />
+        </SvgLinearGradient>
+      </Defs>
+      <Rect width="100%" height="100%" fill={`url(#${gradientId})`} />
+    </Svg>
+  );
+}

package/src/components/header/variants/LargeTitleHeader/index.tsx

@@ -1,26 +1,24 @@
-import { useCallback, useEffect, useId } from 'react';
-import { type LayoutChangeEvent, Text, View } from 'react-native';
+import { useEffect } from 'react';
+import { Text, View } from 'react-native';
 
 import Animated, {
   interpolate,
   useAnimatedStyle,
   useSharedValue,
 } from 'react-native-reanimated';
-import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import Svg, {
-  Defs,
-  Rect,
-  Stop,
-  LinearGradient as SvgLinearGradient,
-} from 'react-native-svg';
 import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 
 import { resolveThemeColor } from '#utils/resolve-theme-color';
 import { FONT_WEIGHT_VALUE } from '#utils/typography';
 
-import { usePortal } from '../../../portal';
-import { useScreen } from '../../../screen/ScreenContext';
+import { Portal } from '../../../portal';
+import {
+  SCREEN_HEADER_PORTAL_HOST,
+  useScreen,
+} from '../../../screen/ScreenContext';
+import { Toolbar } from '../../../toolbar';
 import { HeaderDismissButton } from '../../header-buttons';
+import { HeaderGradientOverlay } from '../../parts/HeaderGradientOverlay';
 import type { TitleHeaderProps } from '../TitleHeader';
 
 const AnimatedText = Animated.createAnimatedComponent(Text);
@@ -40,15 +38,16 @@ export interface LargeTitleHeaderProps extends TitleHeaderProps {
 function LargeTitlePortalContent({
   title,
   caption,
-  onLayout,
-}: Pick<LargeTitleHeaderProps, 'title' | 'caption'> & {
-  onLayout: (event: LayoutChangeEvent) => void;
-}) {
+  titleAlignment = 'center',
+}: Pick<LargeTitleHeaderProps, 'title' | 'caption' | 'titleAlignment'>) {
   const { theme } = useUnistyles();
-  const { scrollY, headerCollapseHeight } = useScreen();
+  const { scrollY } = useScreen();
+  styles.useVariants({ titleAlignment });
+
+  const headerCollapseHeight = theme.layout.header.height;
 
   const largeTitleAnimatedStyle = useAnimatedStyle(() => {
-    const height = headerCollapseHeight.value;
+    const height = headerCollapseHeight;
     if (height <= 0) {
       return { opacity: 1, transform: [{ translateY: 0 }] };
     }
@@ -69,10 +68,7 @@ function LargeTitlePortalContent({
   });
 
   return (
-    <Animated.View
-      style={[styles.portalContent, largeTitleAnimatedStyle]}
-      onLayout={onLayout}
-    >
+    <Animated.View style={[styles.portalContent, largeTitleAnimatedStyle]}>
       <Text
         style={styles.largeTitle}
         maxFontSizeMultiplier={
@@ -114,8 +110,8 @@ function LargeTitlePortalContent({
 export function LargeTitleHeader({
   title,
   caption,
-  LeftComponent,
-  RightComponent,
+  LeftToolbar,
+  RightToolbar,
   dismissAction = 'none',
   navigation,
   onDismiss,
@@ -124,37 +120,27 @@ export function LargeTitleHeader({
   bg = 'surface.default',
 }: LargeTitleHeaderProps) {
   const { theme } = useUnistyles();
-  const { top } = useSafeAreaInsets();
-  const gradientId = useId();
+
   const bgColor =
     resolveThemeColor(bg, theme) ??
     (theme.color as unknown as Record<string, string | undefined>)[
       'surface.default'
     ] ??
     '';
+
   const isTransparent = bgColor === 'transparent';
   const gradientColor = isTransparent ? theme.color.background : bgColor;
-  const { scrollY, headerCollapseHeight, setHeaderCollapseHeight } =
-    useScreen();
-  const { registerContent, unregisterContent } = usePortal();
-  const portalId = useId();
+  const { scrollY } = useScreen();
   const isLargeTitleHiddenValue = useSharedValue(isLargeTitleHidden);
-
+  const headerCollapseHeight = theme.layout.header.height;
   styles.useVariants({ titleAlignment });
 
-  const handlePortalLayout = useCallback(
-    (event: LayoutChangeEvent) => {
-      setHeaderCollapseHeight(event.nativeEvent.layout.height);
-    },
-    [setHeaderCollapseHeight]
-  );
-
   // Animate the gradient overlay's opacity: 0 (expanded) → 1 (collapsed).
   const gradientOpacityStyle = useAnimatedStyle(() => {
     if (isLargeTitleHiddenValue.value) {
       return { opacity: 1 };
     }
-    const height = headerCollapseHeight.value;
+    const height = headerCollapseHeight;
     if (height <= 0) {
       return { opacity: 0 };
     }
@@ -168,7 +154,7 @@ export function LargeTitleHeader({
       return { opacity: 1, transform: [{ translateY: 0 }] };
     }
 
-    const height = headerCollapseHeight.value;
+    const height = headerCollapseHeight;
     if (height <= 0) {
       return {
         opacity: 0,
@@ -195,35 +181,10 @@ export function LargeTitleHeader({
     isLargeTitleHiddenValue.value = isLargeTitleHidden;
   }, [isLargeTitleHidden, isLargeTitleHiddenValue]);
 
-  useEffect(() => {
-    if (isLargeTitleHidden) {
-      setHeaderCollapseHeight(0);
-      unregisterContent(portalId);
-      return;
-    }
-
-    setHeaderCollapseHeight(0);
-
-    registerContent(
-      portalId,
-      <LargeTitlePortalContent
-        title={title}
-        caption={caption}
-        onLayout={handlePortalLayout}
-      />
-    );
-
-    return () => unregisterContent(portalId);
-  }, [
-    portalId,
-    title,
-    caption,
-    isLargeTitleHidden,
-    setHeaderCollapseHeight,
-    handlePortalLayout,
-    registerContent,
-    unregisterContent,
-  ]);
+  // // biome-ignore lint/correctness/useExhaustiveDependencies: reset stale collapse height whenever content that resizes the portal (title/caption/visibility) changes, ahead of remeasurement
+  // useEffect(() => {
+  //   setHeaderCollapseHeight(0);
+  // }, [title, caption, isLargeTitleHidden, setHeaderCollapseHeight]);
 
   const leading =
     dismissAction === 'back' ? (
@@ -233,16 +194,16 @@ export function LargeTitleHeader({
           navigation={navigation}
           onDismiss={onDismiss}
         />
-        {LeftComponent}
+        {LeftToolbar}
       </>
     ) : (
-      LeftComponent
+      LeftToolbar
     );
 
   const trailing =
     dismissAction === 'close' ? (
       <>
-        {RightComponent}
+        {RightToolbar}
         <HeaderDismissButton
           dismissAction={dismissAction}
           navigation={navigation}
@@ -250,33 +211,31 @@ export function LargeTitleHeader({
         />
       </>
     ) : (
-      RightComponent
+      RightToolbar
     );
 
   return (
-    <View style={styles.safeArea}>
+    <View style={styles.container}>
+      {!isLargeTitleHidden && (
+        <Portal hostName={SCREEN_HEADER_PORTAL_HOST}>
+          <LargeTitlePortalContent
+            title={title}
+            caption={caption}
+            titleAlignment={titleAlignment}
+          />
+        </Portal>
+      )}
       <Animated.View
-        style={[
-          { height: top, backgroundColor: gradientColor },
-          gradientOpacityStyle,
-        ]}
+        style={[styles.safeArea(gradientColor), gradientOpacityStyle]}
       />
       <View style={styles.bar}>
         <Animated.View
           style={[styles.gradient, gradientOpacityStyle]}
           pointerEvents="none"
         >
-          <Svg height="100%" width="100%">
-            <Defs>
-              <SvgLinearGradient id={gradientId} x1="0" y1="0" x2="0" y2="1">
-                <Stop offset="0" stopColor={gradientColor} stopOpacity="1" />
-                <Stop offset="1" stopColor={gradientColor} stopOpacity="0" />
-              </SvgLinearGradient>
-            </Defs>
-            <Rect width="100%" height="100%" fill={`url(#${gradientId})`} />
-          </Svg>
+          <HeaderGradientOverlay color={gradientColor} />
         </Animated.View>
-        {leading != null && <View style={styles.slot}>{leading}</View>}
+        {leading != null && <Toolbar>{leading}</Toolbar>}
         <Animated.View
           style={[styles.titleContainer, compactTitleAnimatedStyle]}
           pointerEvents="none"
@@ -290,20 +249,26 @@ export function LargeTitleHeader({
             {title}
           </AnimatedText>
         </Animated.View>
-        {trailing != null && <View style={styles.slotEnd}>{trailing}</View>}
+        {trailing != null && (
+          <Toolbar style={styles.trailing}>{trailing}</Toolbar>
+        )}
       </View>
     </View>
   );
 }
 
-const styles = StyleSheet.create((theme) => ({
-  safeArea: {
+const styles = StyleSheet.create((theme, runtime) => ({
+  container: {
     position: 'absolute',
     top: 0,
     left: 0,
     right: 0,
     zIndex: 1000,
   },
+  safeArea: (bgColor) => ({
+    height: runtime.insets.top,
+    backgroundColor: bgColor,
+  }),
   gradient: {
     position: 'absolute',
     top: 0,
@@ -315,24 +280,18 @@ const styles = StyleSheet.create((theme) => ({
     height: theme.layout.header.height,
     flexDirection: 'row',
     alignItems: 'center',
-    justifyContent: 'space-between',
     paddingHorizontal: theme.layout.screen.margin.x,
     gap: theme.spacing['3'],
+    justifyContent: 'space-between',
   },
-  slot: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: theme.spacing['2'],
-  },
-  slotEnd: {
-    flexDirection: 'row',
-    alignItems: 'center',
+  trailing: {
     justifyContent: 'flex-end',
-    gap: theme.spacing['2'],
   },
   portalContent: {
-    marginTop: theme.spacing['1'],
-    marginBottom: theme.spacing['3'],
+    minHeight: theme.layout.header.height,
+    // paddingTop: theme.spacing['1'],
+    paddingBottom: theme.spacing['3'],
+    paddingHorizontal: theme.layout.screen.margin.x,
   },
   largeTitle: {
     fontSize: theme.typography.variants['headline-lg'].fontSize,
@@ -353,6 +312,12 @@ const styles = StyleSheet.create((theme) => ({
       (theme.color as unknown as Record<string, string | undefined>)[
         'text.subtle'
       ] ?? '',
+    variants: {
+      titleAlignment: {
+        center: { textAlign: 'center' },
+        left: { textAlign: 'left' },
+      },
+    },
   },
   compactTitle: {
     fontSize: theme.typography.variants['title-md'].fontSize,
@@ -372,6 +337,7 @@ const styles = StyleSheet.create((theme) => ({
     },
   },
   titleContainer: {
+    flex: 1,
     variants: {
       titleAlignment: {
         center: {

package/src/components/header/variants/TitleHeader/index.tsx

@@ -1,30 +1,31 @@
-import { type ReactNode, useId } from 'react';
+import type { ReactNode } from 'react';
 import { Text, View } from 'react-native';
 
-import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import Svg, {
-  Defs,
-  Rect,
-  Stop,
-  LinearGradient as SvgLinearGradient,
-} from 'react-native-svg';
 import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 
 import type { ColorToken } from '#theme/types';
 import { resolveThemeColor } from '#utils/resolve-theme-color';
 import { FONT_WEIGHT_VALUE } from '#utils/typography';
 
+import { Toolbar } from '../../../toolbar';
 import {
   HeaderDismissButton,
   type HeaderDismissProps,
 } from '../../header-buttons';
+import { HeaderGradientOverlay } from '../../parts/HeaderGradientOverlay';
 
 export interface TitleHeaderProps extends HeaderDismissProps {
   title?: string;
-  /** Content on the leading side (e.g. a back button). */
-  LeftComponent?: ReactNode;
-  /** Content on the trailing side (e.g. an action). */
-  RightComponent?: ReactNode;
+  /**
+   * Leading-side actions, wrapped in a `Toolbar` row. Pass `Toolbar.Group` /
+   * `Toolbar.Button` children directly — no `Toolbar` of your own.
+   */
+  LeftToolbar?: ReactNode;
+  /**
+   * Trailing-side actions, wrapped in a `Toolbar` row. Pass `Toolbar.Group` /
+   * `Toolbar.Button` children directly — no `Toolbar` of your own.
+   */
+  RightToolbar?: ReactNode;
   /** Title placement within the bar. Defaults to `'center'`. */
   titleAlignment?: 'center' | 'left';
   /** Background color token. Defaults to `surface.default`. */
@@ -39,14 +40,19 @@ export interface TitleHeaderProps extends HeaderDismissProps {
  * @example
  * ```tsx
  * <Screen.Header>
- *   <Header.Title title="Stats" RightComponent={<Button>Edit</Button>} />
+ *   <Header.Title
+ *     title="Stats"
+ *     RightToolbar={
+ *       <Toolbar.Button icon="add" accessibilityLabel="Add" onPress={add} />
+ *     }
+ *   />
  * </Screen.Header>
  * ```
  */
 export function TitleHeader({
   title,
-  LeftComponent,
-  RightComponent,
+  LeftToolbar,
+  RightToolbar,
   dismissAction = 'none',
   navigation,
   onDismiss,
@@ -54,9 +60,13 @@ export function TitleHeader({
   bg = 'surface.default',
 }: TitleHeaderProps) {
   const { theme } = useUnistyles();
-  const { top } = useSafeAreaInsets();
-  const gradientId = useId();
-  const bgColor = resolveThemeColor(bg, theme) as string;
+
+  const bgColor =
+    resolveThemeColor(bg, theme) ??
+    (theme.color as unknown as Record<string, string | undefined>)[
+      'surface.default'
+    ] ??
+    '';
   const isTransparent = bgColor === 'transparent';
   const gradientColor = isTransparent
     ? theme.color['surface.default']
@@ -71,16 +81,16 @@ export function TitleHeader({
           navigation={navigation}
           onDismiss={onDismiss}
         />
-        {LeftComponent}
+        {LeftToolbar}
       </>
     ) : (
-      LeftComponent
+      LeftToolbar
     );
 
   const trailing =
     dismissAction === 'close' ? (
       <>
-        {RightComponent}
+        {RightToolbar}
         <HeaderDismissButton
           dismissAction={dismissAction}
           navigation={navigation}
@@ -88,50 +98,39 @@ export function TitleHeader({
         />
       </>
     ) : (
-      RightComponent
+      RightToolbar
     );
   return (
-    <View style={styles.safeArea}>
-      <View
-        style={{
-          height: top,
-          backgroundColor: isTransparent ? 'transparent' : bgColor,
-        }}
-      />
+    <View style={styles.container}>
+      <View style={styles.safeArea(isTransparent, bgColor)} />
       <View style={styles.bar}>
         <View style={styles.gradient} pointerEvents="none">
-          <Svg height="100%" width="100%">
-            <Defs>
-              <SvgLinearGradient id={gradientId} x1="0" y1="0.4" x2="0" y2="1">
-                <Stop offset="0" stopColor={gradientColor} stopOpacity="0.9" />
-                <Stop
-                  offset="0.9"
-                  stopColor={gradientColor}
-                  stopOpacity="0.1"
-                />
-              </SvgLinearGradient>
-            </Defs>
-            <Rect width="100%" height="100%" fill={`url(#${gradientId})`} />
-          </Svg>
+          <HeaderGradientOverlay color={gradientColor} />
         </View>
-        {leading != null && <View style={styles.slot}>{leading}</View>}
+        {leading != null && <Toolbar>{leading}</Toolbar>}
         <View style={styles.titleContainer} pointerEvents="none">
           {!!title && <Text style={styles.title}>{title}</Text>}
         </View>
-        {trailing != null && <View style={styles.slotEnd}>{trailing}</View>}
+        {trailing != null && (
+          <Toolbar style={styles.trailing}>{trailing}</Toolbar>
+        )}
       </View>
     </View>
   );
 }
 
-const styles = StyleSheet.create((theme) => ({
-  safeArea: {
+const styles = StyleSheet.create((theme, runtime) => ({
+  container: {
     position: 'absolute',
     top: 0,
     left: 0,
     right: 0,
     zIndex: 1000,
   },
+  safeArea: (isTransparent, bgColor) => ({
+    height: runtime.insets.top,
+    backgroundColor: isTransparent ? 'transparent' : bgColor,
+  }),
   gradient: {
     position: 'absolute',
     top: 0,
@@ -143,20 +142,12 @@ const styles = StyleSheet.create((theme) => ({
     height: theme.layout.header.height,
     flexDirection: 'row',
     alignItems: 'center',
-    justifyContent: 'space-between',
     paddingHorizontal: theme.layout.screen.margin.x,
     gap: theme.spacing['3'],
+    justifyContent: 'space-between',
   },
-  slot: {
-    flexDirection: 'row',
-    alignItems: 'center',
-    gap: theme.spacing['2'],
-  },
-  slotEnd: {
-    flexDirection: 'row',
-    alignItems: 'center',
+  trailing: {
     justifyContent: 'flex-end',
-    gap: theme.spacing['2'],
   },
   titleContainer: {
     variants: {