react-native-terra-ui 0.1.0 → 0.2.0

package/src/components/icon/Icon.tsx

@@ -2,9 +2,9 @@ import type { ComponentRef } from 'react';
 import { forwardRef } from 'react';
 import { View, type ViewProps } from 'react-native';
 
-import { useUnistyles } from 'react-native-unistyles';
+import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 
-import { getIcon } from '#theme/configure';
+import { getIcon } from '#theme/registry';
 import type { ColorToken, TerraIconName } from '#theme/types';
 import { resolveThemeColor } from '#utils/resolve-theme-color';
 
@@ -50,19 +50,7 @@ export const Icon = forwardRef<ComponentRef<typeof View>, IconProps>(
       '';
 
     return (
-      <View
-        ref={ref}
-        style={[
-          {
-            width: size,
-            height: size,
-            alignItems: 'center',
-            justifyContent: 'center',
-          },
-          style,
-        ]}
-        {...rest}
-      >
+      <View ref={ref} style={[styles.container(size), style]} {...rest}>
         <IconComponent
           color={resolvedColor}
           size={size}
@@ -72,3 +60,20 @@ export const Icon = forwardRef<ComponentRef<typeof View>, IconProps>(
     );
   }
 );
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+//
+// This stylesheet is also what makes the Unistyles Babel plugin swap the `View`
+// imported above for its Unistyles-aware counterpart, which registers the
+// ShadowNode natively. Without it, a Unistyles style passed in through `style`
+// would freeze at whichever theme was active when it was created — `Icon` does
+// not re-render on theme change unless something it reads from the theme
+// happens to change.
+const styles = StyleSheet.create(() => ({
+  container: (size: number) => ({
+    width: size,
+    height: size,
+    alignItems: 'center',
+    justifyContent: 'center',
+  }),
+}));

package/src/components/image/Image.tsx

@@ -0,0 +1,48 @@
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { getImageComponent } from '#theme/registry';
+import type { RadiusKey } from '#theme/types.js';
+import type { ImageProps } from './types';
+
+/**
+ * Renders the image implementation configured via
+ * `configureTerraUI({ image })` (defaults to React Native's `Image`).
+ *
+ * @example
+ * ```tsx
+ * <Image
+ *   source={{ uri: 'https://example.com/photo.jpg' }}
+ *   contentFit="cover"
+ *   style={{ width: 40, height: 40 }}
+ * />
+ * ```
+ */
+export function Image({
+  contentFit = 'cover',
+  width,
+  height,
+  radius = 'none',
+  style,
+  ...rest
+}: ImageProps) {
+  const ImageComponent = getImageComponent();
+
+  return (
+    <View style={[styles.container(width, height, radius), style]}>
+      <ImageComponent contentFit={contentFit} style={styles.image} {...rest} />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create((_theme) => ({
+  container: (w: number | undefined, h: number | undefined, r: RadiusKey) => ({
+    ...(w ? { width: w } : {}),
+    ...(h ? { height: h } : {}),
+    borderRadius: _theme.radius[r],
+    overflow: 'hidden',
+  }),
+  image: {
+    width: '100%',
+    height: '100%',
+  },
+}));

package/src/components/image/index.ts

@@ -0,0 +1,2 @@
+export { Image } from './Image';
+export type { ImageProps } from './types';

package/src/components/image/types.ts

@@ -0,0 +1,7 @@
+import type { RadiusKey, TerraImageProps } from '#theme/types';
+
+export interface ImageProps extends TerraImageProps {
+  width?: number;
+  height?: number;
+  radius?: RadiusKey;
+}

package/src/components/index.ts

@@ -1,8 +1,11 @@
 export * from './avatar';
 export * from './box';
 export * from './button';
+export * from './chip';
+export * from './empty-state';
 export * from './header';
 export * from './icon';
+export * from './image';
 export * from './page-indicator';
 export * from './portal';
 export * from './screen';
@@ -11,3 +14,4 @@ export * from './spinner';
 export * from './surface';
 export * from './text';
 export * from './toast';
+export * from './toolbar';

package/src/components/portal/Portal.tsx

@@ -0,0 +1,55 @@
+import { type FC, type ReactNode, useContext, useEffect, useRef } from 'react';
+
+import { PortalContext } from './PortalContext';
+import { PortalHost, type PortalHostProps } from './PortalHost';
+import { PortalProvider, type PortalProviderProps } from './PortalProvider';
+
+let nextPortalKey = 1;
+
+export interface PortalProps {
+  /** Name of the `PortalHost` to teleport `children` into. */
+  hostName: string;
+  children?: ReactNode;
+}
+
+const PortalComponent: FC<PortalProps> = ({ hostName, children }) => {
+  const context = useContext(PortalContext);
+  const upsertPortal = context?.upsertPortal;
+  const removePortal = context?.removePortal;
+  const portalKeyRef = useRef<number>(nextPortalKey++);
+
+  useEffect(() => {
+    if (!upsertPortal || !removePortal) {
+      return;
+    }
+
+    upsertPortal(hostName, portalKeyRef.current, children ?? null);
+
+    return () => {
+      removePortal(hostName, portalKeyRef.current);
+    };
+  }, [children, hostName, removePortal, upsertPortal]);
+
+  return null;
+};
+
+type PortalWithCompatApi = FC<PortalProps> & {
+  Provider: FC<PortalProviderProps>;
+  Host: FC<PortalHostProps>;
+};
+
+/**
+ * Declaratively teleports `children` into the `PortalHost` named `hostName`,
+ * for as long as this component stays mounted.
+ *
+ * @example
+ * ```tsx
+ * <Portal hostName="screen-header">
+ *   <LargeTitle />
+ * </Portal>
+ * ```
+ */
+export const Portal = Object.assign(PortalComponent, {
+  Provider: PortalProvider,
+  Host: PortalHost,
+}) as PortalWithCompatApi;

package/src/components/portal/PortalContext.tsx

@@ -1,27 +1,19 @@
-import { createContext, type ReactNode, useContext } from 'react';
+import { createContext, type ReactNode } from 'react';
 
-export interface PortalContextValue {
-  /** Register (or replace) portal content under a stable id. */
-  registerContent: (id: string, content: ReactNode) => void;
-  /** Remove the content previously registered under `id`. */
-  unregisterContent: (id: string) => void;
-  /** Currently registered content, keyed by id, rendered by `PortalHost`. */
-  contents: Map<string, ReactNode>;
+export interface PortalEntry {
+  key: number;
+  node: ReactNode;
 }
 
-export const PortalContext = createContext<PortalContextValue | null>(null);
+export type PortalStore = Record<string, PortalEntry[]>;
 
-/**
- * Access the nearest {@link PortalProvider}. Used by components that need to
- * teleport content into a `PortalHost` rendered elsewhere in the tree (e.g. the
- * large-title header injecting its title into the scroll content).
- *
- * @throws if called outside a `PortalProvider`.
- */
-export function usePortal(): PortalContextValue {
-  const context = useContext(PortalContext);
-  if (!context) {
-    throw new Error('usePortal must be used within a PortalProvider');
-  }
-  return context;
+export interface PortalContextValue {
+  /** Portal entries currently registered, keyed by host name. */
+  portals: PortalStore;
+  /** Register (or replace) the entry `key` under `hostName`. */
+  upsertPortal: (hostName: string, key: number, node: ReactNode) => void;
+  /** Remove the entry `key` previously registered under `hostName`. */
+  removePortal: (hostName: string, key: number) => void;
 }
+
+export const PortalContext = createContext<PortalContextValue | null>(null);

package/src/components/portal/PortalHost.tsx

@@ -1,19 +1,26 @@
-import { View } from 'react-native';
+import { Fragment, useContext } from 'react';
+import { View, type ViewProps } from 'react-native';
 
-import { usePortal } from './PortalContext';
+import { PortalContext } from './PortalContext';
+
+export type PortalHostProps = Omit<ViewProps, 'children'> & {
+  /** Renders every `Portal` registered under this host name, in insertion order. */
+  name: string;
+};
 
 /**
- * Renders every node currently registered with the nearest
- * {@link PortalProvider}, in insertion order. Place it where teleported content
- * should appear (e.g. at the top of a `Screen.ScrollView`).
+ * Renders every entry currently registered under `name` on the nearest
+ * {@link PortalProvider}. Place it where teleported content should appear
+ * (e.g. at the top of a `Screen.ScrollView`).
  */
-export function PortalHost() {
-  const { contents } = usePortal();
+export function PortalHost({ name, ...viewProps }: PortalHostProps) {
+  const context = useContext(PortalContext);
+  const hostPortals = context?.portals[name] ?? [];
 
   return (
-    <View collapsable={false}>
-      {Array.from(contents.entries()).map(([id, content]) => (
-        <View key={id}>{content}</View>
+    <View {...viewProps}>
+      {hostPortals.map((entry) => (
+        <Fragment key={entry.key}>{entry.node}</Fragment>
       ))}
     </View>
   );

package/src/components/portal/PortalProvider.tsx

@@ -1,41 +1,78 @@
 import { type ReactNode, useCallback, useMemo, useState } from 'react';
 
-import { PortalContext, type PortalContextValue } from './PortalContext';
+import {
+  PortalContext,
+  type PortalContextValue,
+  type PortalStore,
+} from './PortalContext';
 
 export interface PortalProviderProps {
   children: ReactNode;
 }
 
 /**
- * Holds a registry of teleported content. Children register/unregister nodes by
- * id (see {@link usePortal}); a `PortalHost` placed anywhere below renders them.
- * Context-only — no animation dependency.
+ * Holds a registry of teleported content, keyed by host name. Descendant
+ * `Portal` components register/unregister entries; a `PortalHost` placed
+ * anywhere below renders the entries for its `name`.
  */
 export function PortalProvider({ children }: PortalProviderProps) {
-  const [contents, setContents] = useState<Map<string, ReactNode>>(
-    () => new Map()
+  const [portals, setPortals] = useState<PortalStore>({});
+
+  const upsertPortal = useCallback(
+    (hostName: string, key: number, node: ReactNode) => {
+      setPortals((prev) => {
+        const hostPortals = prev[hostName] ?? [];
+        const existingIndex = hostPortals.findIndex(
+          (entry) => entry.key === key
+        );
+
+        if (existingIndex === -1) {
+          return {
+            ...prev,
+            [hostName]: [...hostPortals, { key, node }],
+          };
+        }
+
+        if (hostPortals[existingIndex]?.node === node) {
+          return prev;
+        }
+
+        const nextHostPortals = [...hostPortals];
+        nextHostPortals[existingIndex] = { key, node };
+
+        return {
+          ...prev,
+          [hostName]: nextHostPortals,
+        };
+      });
+    },
+    []
   );
 
-  const registerContent = useCallback((id: string, content: ReactNode) => {
-    setContents((prev) => {
-      const next = new Map(prev);
-      next.set(id, content);
-      return next;
-    });
-  }, []);
+  const removePortal = useCallback((hostName: string, key: number) => {
+    setPortals((prev) => {
+      const hostPortals = prev[hostName] ?? [];
+      const nextHostPortals = hostPortals.filter((entry) => entry.key !== key);
+
+      if (nextHostPortals.length === hostPortals.length) {
+        return prev;
+      }
+
+      if (nextHostPortals.length === 0) {
+        const { [hostName]: _removed, ...rest } = prev;
+        return rest;
+      }
 
-  const unregisterContent = useCallback((id: string) => {
-    setContents((prev) => {
-      if (!prev.has(id)) return prev;
-      const next = new Map(prev);
-      next.delete(id);
-      return next;
+      return {
+        ...prev,
+        [hostName]: nextHostPortals,
+      };
     });
   }, []);
 
   const value = useMemo<PortalContextValue>(
-    () => ({ registerContent, unregisterContent, contents }),
-    [registerContent, unregisterContent, contents]
+    () => ({ portals, upsertPortal, removePortal }),
+    [portals, removePortal, upsertPortal]
   );
 
   return (

package/src/components/portal/index.ts

@@ -1,5 +1,7 @@
-export type { PortalContextValue } from './PortalContext';
-export { usePortal } from './PortalContext';
+export type { PortalProps } from './Portal';
+export { Portal } from './Portal';
+export type { PortalContextValue, PortalEntry } from './PortalContext';
+export type { PortalHostProps } from './PortalHost';
 export { PortalHost } from './PortalHost';
 export type { PortalProviderProps } from './PortalProvider';
 export { PortalProvider } from './PortalProvider';

package/src/components/screen/Screen.tsx

@@ -10,20 +10,17 @@ import {
   type ReactNode,
   useMemo,
 } from 'react';
-import {
-  type Edge,
-  SafeAreaView,
-  type SafeAreaViewProps,
-} from 'react-native-safe-area-context';
-import { useUnistyles } from 'react-native-unistyles';
-
+import { View } from 'react-native';
+import type { ViewProps } from 'react-native-svg/lib/typescript/fabric/utils';
+import { StyleSheet, useUnistyles } from 'react-native-unistyles';
 import type { ColorToken } from '#theme/types';
 import { resolveThemeColor } from '#utils/resolve-theme-color';
-
 import { PortalProvider } from '../portal';
 import { ScreenScrollProvider } from './ScreenContext';
+import { ScreenFlashList } from './ScreenFlashList';
 import { ScreenFlatList } from './ScreenFlatList';
 import { ScreenScrollView } from './ScreenScrollView';
+import type { ScreenMargins } from './types';
 
 export type ScreenHeaderProps<T extends ElementType = typeof Fragment> =
   PropsWithChildren<
@@ -57,43 +54,48 @@ function ScreenHeader<T extends ElementType = typeof Fragment>({
   const Component = as ?? Fragment;
   return <Component {...rest}>{children}</Component>;
 }
+ScreenHeader.displayName = 'Screen.Header';
 
 /** True if `children` directly contains a `Screen.Header`. */
 function hasScreenHeader(children: ReactNode): boolean {
   let found = false;
   Children.forEach(children, (child) => {
     if (found) return;
-    if (isValidElement(child) && child.type === ScreenHeader) found = true;
+    if (
+      isValidElement(child) &&
+      typeof child.type !== 'string' &&
+      (child.type as { displayName?: string }).displayName === 'Screen.Header'
+    )
+      found = true;
   });
   return found;
 }
 
-export interface ScreenProps extends Omit<SafeAreaViewProps, 'edges'> {
+export interface ScreenProps extends ViewProps {
   children: ReactNode;
   /** Background color token. Defaults to the `background` token. */
   bg?: ColorToken;
-  /**
-   * Safe-area edges to inset. Defaults are header-aware: `[]` when a
-   * `Screen.Header` is present (the header owns the top inset), otherwise
-   * `['top', 'bottom']`. An explicit value is respected, except `top` is
-   * dropped when a header is present.
-   */
-  edges?: Edge[];
   /** Hosted inside a tab navigator? Exposed via `useScreen()`. Default false. */
   inTabView?: boolean;
   /**
-   * Apply `layout.screen.margin` padding on `Screen.ScrollView` /
-   * `Screen.FlatList`. Default true. Overridable per scroll container.
+   * Which axes of `layout.screen.margin` the scroll containers pad their
+   * content with. Default `'all'`. Overridable per scroll container.
+   */
+  margins?: ScreenMargins;
+  /**
+   * @deprecated Use `margins` — `false` maps to `margins="none"`. Ignored when
+   * `margins` is set.
    */
-  margins?: boolean;
+  hasMargins?: boolean;
 }
 
 type ScreenComponent = ReturnType<
-  typeof forwardRef<ComponentRef<typeof SafeAreaView>, ScreenProps>
+  typeof forwardRef<ComponentRef<typeof View>, ScreenProps>
 > & {
   Header: typeof ScreenHeader;
   ScrollView: typeof ScreenScrollView;
   FlatList: typeof ScreenFlatList;
+  FlashList: typeof ScreenFlashList;
 };
 
 /**
@@ -109,49 +111,26 @@ type ScreenComponent = ReturnType<
  * </Screen>
  * ```
  */
-const ScreenBase = forwardRef<ComponentRef<typeof SafeAreaView>, ScreenProps>(
+const ScreenBase = forwardRef<ComponentRef<typeof View>, ScreenProps>(
   function Screen(
-    {
-      children,
-      bg = 'background',
-      edges,
-      inTabView = false,
-      margins = true,
-      style,
-      ...rest
-    },
-    ref
+    { children, bg = 'background', margins, hasMargins, style, ...rest },
+    _ref
   ) {
-    const { theme } = useUnistyles();
-    const backgroundColor =
-      resolveThemeColor(bg, theme) ?? theme.color.background;
-
     const hasHeader = useMemo(() => hasScreenHeader(children), [children]);
-
-    const safeEdges = useMemo<Edge[]>(() => {
-      if (edges) {
-        return hasHeader ? edges.filter((edge) => edge !== 'top') : edges;
-      }
-      return hasHeader ? [] : ['top', 'bottom'];
-    }, [edges, hasHeader]);
+    const resolvedMargins = margins ?? (hasMargins === false ? 'none' : 'all');
+    const { theme } = useUnistyles();
+    const resolvedBg = resolveThemeColor(bg, theme) ?? theme.color.background;
 
     return (
-      <ScreenScrollProvider
-        isInTabView={inTabView}
-        margins={margins}
-        hasHeader={hasHeader}
-      >
-        <PortalProvider>
-          <SafeAreaView
-            ref={ref}
-            edges={safeEdges}
-            style={[{ flex: 1, backgroundColor }, style]}
-            {...rest}
-          >
-            {children}
-          </SafeAreaView>
-        </PortalProvider>
-      </ScreenScrollProvider>
+      <View style={[styles.container, style]} {...rest}>
+        <ScreenScrollProvider
+          background={resolvedBg}
+          margins={resolvedMargins}
+          hasHeader={hasHeader}
+        >
+          <PortalProvider>{children}</PortalProvider>
+        </ScreenScrollProvider>
+      </View>
     );
   }
 ) as ScreenComponent;
@@ -159,5 +138,12 @@ const ScreenBase = forwardRef<ComponentRef<typeof SafeAreaView>, ScreenProps>(
 ScreenBase.Header = ScreenHeader;
 ScreenBase.ScrollView = ScreenScrollView;
 ScreenBase.FlatList = ScreenFlatList;
+ScreenBase.FlashList = ScreenFlashList;
 
 export const Screen = ScreenBase;
+
+const styles = StyleSheet.create((_theme, _runtime) => ({
+  container: {
+    flex: 1,
+  },
+}));

package/src/components/screen/ScreenContext.tsx

@@ -16,14 +16,20 @@ import Animated, {
   useSharedValue,
 } from 'react-native-reanimated';
 
+import type { ScreenMargins } from './types';
+
 export type ScreenScrollRef = AnimatedRef<Animated.ScrollView>;
 
+/** `PortalHost` name shared by `Screen.ScrollView` / `Screen.FlatList` and header variants that portal content into them. */
+export const SCREEN_HEADER_PORTAL_HOST = 'screen-header';
+
 export interface ScreenContextValue {
   /**
-   * Whether scroll containers apply `layout.screen.margin` padding.
-   * Overridable per `Screen.ScrollView` / `Screen.FlatList`.
+   * Which axes scroll containers pad with `layout.screen.margin`.
+   * Overridable per `Screen.ScrollView` / `Screen.FlatList` /
+   * `Screen.FlashList` via their own `margins` prop.
    */
-  margins: boolean;
+  margins: ScreenMargins;
   /** Whether a `Screen.Header` is present. Used by scroll containers to add top inset. */
   hasHeader: boolean;
   /**
@@ -49,19 +55,20 @@ export interface ScreenContextValue {
   scrollRef: ScreenScrollRef;
   /** Scroll handler that mirrors offset into `scrollY`. */
   scrollHandler: ScrollHandlerProcessed<Record<string, unknown>>;
-  /** Whether the screen is hosted inside a tab navigator (affects edges). */
-  isInTabView: boolean;
+
+  background?: string;
 }
 
 export const ScreenContext = createContext<ScreenContextValue | null>(null);
 
 export interface ScreenScrollProviderProps {
   children: ReactNode;
-  isInTabView: boolean;
-  /** Apply `layout.screen.margin` to scroll containers. Default true. */
-  margins?: boolean;
+  /** Which axes scroll containers pad with `layout.screen.margin`. Default `'all'`. */
+  margins?: ScreenMargins;
   /** Whether a `Screen.Header` child is present. Default false. */
   hasHeader?: boolean;
+
+  background?: string;
 }
 
 /**
@@ -70,9 +77,9 @@ export interface ScreenScrollProviderProps {
  * scroll containers bind the ref via {@link useScreen}.
  */
 export function ScreenScrollProvider({
+  background = 'transparent',
   children,
-  isInTabView,
-  margins = true,
+  margins = 'all',
   hasHeader = false,
 }: ScreenScrollProviderProps) {
   const scrollY = useSharedValue(0);
@@ -97,6 +104,7 @@ export function ScreenScrollProvider({
 
   const value = useMemo<ScreenContextValue>(
     () => ({
+      background,
       margins,
       hasHeader,
       scrollY,
@@ -105,9 +113,9 @@ export function ScreenScrollProvider({
       setHeaderCollapseHeight,
       scrollRef,
       scrollHandler,
-      isInTabView,
     }),
     [
+      background,
       margins,
       hasHeader,
       scrollY,
@@ -116,7 +124,6 @@ export function ScreenScrollProvider({
       setHeaderCollapseHeight,
       scrollRef,
       scrollHandler,
-      isInTabView,
     ]
   );