react-native-terra-ui 0.1.0

package/src/components/screen/ScreenContext.tsx

@@ -0,0 +1,144 @@
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+} from 'react';
+
+import Animated, {
+  type AnimatedRef,
+  type ScrollHandlerProcessed,
+  type SharedValue,
+  useAnimatedRef,
+  useAnimatedScrollHandler,
+  useSharedValue,
+} from 'react-native-reanimated';
+
+export type ScreenScrollRef = AnimatedRef<Animated.ScrollView>;
+
+export interface ScreenContextValue {
+  /**
+   * Whether scroll containers apply `layout.screen.margin` padding.
+   * Overridable per `Screen.ScrollView` / `Screen.FlatList`.
+   */
+  margins: boolean;
+  /** Whether a `Screen.Header` is present. Used by scroll containers to add top inset. */
+  hasHeader: boolean;
+  /**
+   * Live vertical scroll offset of the screen's scroll container, driven by
+   * `Screen.ScrollView` / `Screen.FlatList`. Headers (and consumer UI) read it
+   * to animate on scroll.
+   */
+  scrollY: SharedValue<number>;
+  /**
+   * Scroll distance (px) over which the active header collapses — measured by
+   * the header (e.g. large-title portal height, parallax hero height). `0`
+   * disables snap and collapse-range animations (`Header.Title` screens).
+   */
+  headerCollapseHeight: SharedValue<number>;
+  /**
+   * Native `snapToOffsets` for the scroll container. `[0, height]` when a
+   * collapsible header is active; `undefined` otherwise.
+   */
+  headerSnapOffsets: number[] | undefined;
+  /** Updates collapse height for animations and native snap offsets. */
+  setHeaderCollapseHeight: (height: number) => void;
+  /** Shared scroll container ref — bound by `Screen.ScrollView` / `Screen.FlatList`. */
+  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;
+}
+
+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;
+  /** Whether a `Screen.Header` child is present. Default false. */
+  hasHeader?: boolean;
+}
+
+/**
+ * Owns the screen's shared scroll ref, offset, snap offsets, and header collapse
+ * metrics. Header variants call {@link ScreenContextValue.setHeaderCollapseHeight};
+ * scroll containers bind the ref via {@link useScreen}.
+ */
+export function ScreenScrollProvider({
+  children,
+  isInTabView,
+  margins = true,
+  hasHeader = false,
+}: ScreenScrollProviderProps) {
+  const scrollY = useSharedValue(0);
+  const headerCollapseHeight = useSharedValue(0);
+  const [headerSnapOffsets, setHeaderSnapOffsets] = useState<number[]>();
+  const scrollRef = useAnimatedRef<Animated.ScrollView>();
+
+  const setHeaderCollapseHeight = useCallback(
+    (height: number) => {
+      const rounded = Math.round(height);
+      headerCollapseHeight.value = rounded;
+      setHeaderSnapOffsets(rounded > 0 ? [0, rounded] : undefined);
+    },
+    [headerCollapseHeight]
+  );
+
+  const scrollHandler = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      scrollY.value = event.contentOffset.y;
+    },
+  });
+
+  const value = useMemo<ScreenContextValue>(
+    () => ({
+      margins,
+      hasHeader,
+      scrollY,
+      headerCollapseHeight,
+      headerSnapOffsets,
+      setHeaderCollapseHeight,
+      scrollRef,
+      scrollHandler,
+      isInTabView,
+    }),
+    [
+      margins,
+      hasHeader,
+      scrollY,
+      headerCollapseHeight,
+      headerSnapOffsets,
+      setHeaderCollapseHeight,
+      scrollRef,
+      scrollHandler,
+      isInTabView,
+    ]
+  );
+
+  return (
+    <ScreenContext.Provider value={value}>{children}</ScreenContext.Provider>
+  );
+}
+
+/**
+ * Access the enclosing `Screen`'s shared scroll state, ref, and snap offsets.
+ *
+ * @example
+ * ```tsx
+ * const { scrollY, scrollRef, headerSnapOffsets } = useScreen();
+ * ```
+ *
+ * @throws if called outside a `Screen`.
+ */
+export function useScreen(): ScreenContextValue {
+  const context = useContext(ScreenContext);
+  if (!context) {
+    throw new Error('useScreen must be used within a Screen component');
+  }
+  return context;
+}

package/src/components/screen/ScreenFlatList.tsx

@@ -0,0 +1,121 @@
+import {
+  createElement,
+  type FunctionComponent,
+  isValidElement,
+  type ReactElement,
+} from 'react';
+import {
+  type FlatListProps,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+  View,
+} from 'react-native';
+
+import Animated, {
+  type AnimatedRef,
+  useAnimatedScrollHandler,
+  useComposedEventHandler,
+} from 'react-native-reanimated';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useUnistyles } from 'react-native-unistyles';
+
+import { PortalHost } from '../portal';
+import { useScreen } from './ScreenContext';
+import { resolveScreenContentInsets } from './utils';
+
+export interface ScreenFlatListProps<T>
+  extends Omit<FlatListProps<T>, 'CellRendererComponent'> {
+  /**
+   * Apply `layout.screen.margin` padding. Defaults to the enclosing `Screen`'s
+   * `margins` value.
+   */
+  margins?: boolean;
+  /**
+   * Extra bottom padding on the list content — clearance for a tab bar or home
+   * indicator. Defaults to the `layout.screen.margin.y` token when margins are
+   * enabled, otherwise `0`.
+   */
+  bottomInset?: number;
+}
+
+function renderListHeader(
+  ListHeaderComponent: FlatListProps<unknown>['ListHeaderComponent']
+): ReactElement | null {
+  if (!ListHeaderComponent) return null;
+  if (isValidElement(ListHeaderComponent)) return ListHeaderComponent;
+  return createElement(ListHeaderComponent as FunctionComponent);
+}
+
+/**
+ * `FlatList` variant of `Screen.ScrollView`: binds the screen's shared scroll
+ * ref, mirrors offset into `scrollY`, hosts the portal target above the list,
+ * and applies token-driven content padding.
+ *
+ * @example
+ * ```tsx
+ * <Screen.FlatList data={items} renderItem={({ item }) => <Row item={item} />} />
+ * ```
+ */
+export function ScreenFlatList<T>({
+  style,
+  contentContainerStyle,
+  ListHeaderComponent,
+  margins,
+  bottomInset,
+  onScroll,
+  ...rest
+}: ScreenFlatListProps<T>) {
+  const { theme } = useUnistyles();
+  const { top } = useSafeAreaInsets();
+  const {
+    scrollRef,
+    scrollHandler,
+    headerSnapOffsets,
+    margins: screenMargins,
+    hasHeader,
+  } = useScreen();
+
+  const margin = theme.layout.screen.margin;
+  const marginsEnabled = margins ?? screenMargins;
+  const compactHeaderHeight = hasHeader ? top + theme.layout.header.height : 0;
+  const { contentPadding } = resolveScreenContentInsets(
+    margin,
+    marginsEnabled,
+    bottomInset,
+    compactHeaderHeight
+  );
+
+  const jsScrollHandler = useAnimatedScrollHandler(
+    (event) => {
+      if (onScroll)
+        onScroll(event as unknown as NativeSyntheticEvent<NativeScrollEvent>);
+    },
+    [onScroll]
+  );
+
+  const composedHandler = useComposedEventHandler([
+    scrollHandler,
+    jsScrollHandler,
+  ]);
+
+  const headerComponent = (
+    <View>
+      <PortalHost />
+      {renderListHeader(ListHeaderComponent)}
+    </View>
+  );
+
+  return (
+    <Animated.FlatList
+      ref={scrollRef as unknown as AnimatedRef<Animated.FlatList<T>>}
+      style={style}
+      contentContainerStyle={[contentPadding, contentContainerStyle]}
+      ListHeaderComponent={headerComponent}
+      showsVerticalScrollIndicator={false}
+      scrollEventThrottle={16}
+      snapToOffsets={headerSnapOffsets}
+      {...rest}
+      onScroll={composedHandler}
+    />
+  );
+}

package/src/components/screen/ScreenScrollView.tsx

@@ -0,0 +1,130 @@
+import type { ReactNode } from 'react';
+import {
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+  type ScrollViewProps,
+  View,
+} from 'react-native';
+
+import Animated, {
+  type ScrollHandlerProcessed,
+  useAnimatedScrollHandler,
+  useComposedEventHandler,
+} from 'react-native-reanimated';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useUnistyles } from 'react-native-unistyles';
+
+import { PortalHost } from '../portal';
+import { useScreen } from './ScreenContext';
+import { resolveScreenContentInsets } from './utils';
+
+export interface ScreenScrollViewProps extends ScrollViewProps {
+  children?: ReactNode;
+  /**
+   * Apply `layout.screen.margin` padding. Defaults to the enclosing `Screen`'s
+   * `margins` value.
+   */
+  hasMargins?: boolean;
+  /**
+   * Extra bottom padding on the scroll content — clearance for a tab bar or
+   * home indicator. Defaults to the `layout.screen.margin.y` token when margins
+   * are enabled, otherwise `0`.
+   */
+  bottomInset?: number;
+  /**
+   * Optional Reanimated scroll handler composed with the screen's own scroll
+   * tracking and any JS `onScroll` callback.
+   */
+  scrollHandler?: ScrollHandlerProcessed<Record<string, unknown>>;
+}
+
+/**
+ * Scrollable content container for a `Screen`. Binds the screen's shared scroll
+ * ref, mirrors offset into `scrollY`, hosts the portal target at the top (where
+ * header content is injected), and applies token-driven content padding.
+ *
+ * @example
+ * ```tsx
+ * <Screen.ScrollView>
+ *   <Text>Scrollable content</Text>
+ * </Screen.ScrollView>
+ * ```
+ */
+export function ScreenScrollView({
+  children,
+  style,
+  contentContainerStyle,
+  hasMargins,
+  bottomInset,
+  scrollHandler: externalScrollHandler,
+  onScroll: onScrollProp,
+  horizontal = false,
+  ...rest
+}: ScreenScrollViewProps) {
+  const { theme } = useUnistyles();
+  const { top } = useSafeAreaInsets();
+  const {
+    scrollRef,
+    scrollHandler: screenScrollHandler,
+    headerSnapOffsets,
+    margins: screenMargins,
+    hasHeader,
+  } = useScreen();
+
+  const jsScrollHandler = useAnimatedScrollHandler(
+    onScrollProp
+      ? {
+          onScroll: (event) => {
+            onScrollProp({
+              nativeEvent: event,
+            } as unknown as NativeSyntheticEvent<NativeScrollEvent>);
+          },
+        }
+      : {}
+  );
+
+  const handlers: ScrollHandlerProcessed<Record<string, unknown>>[] = [
+    screenScrollHandler,
+    ...(externalScrollHandler ? [externalScrollHandler] : []),
+    ...(onScrollProp ? [jsScrollHandler] : []),
+  ];
+
+  const composedHandler = useComposedEventHandler(handlers);
+
+  const margin = theme.layout.screen.margin;
+  const marginsEnabled = hasMargins ?? screenMargins;
+  const compactHeaderHeight = hasHeader ? top + theme.layout.header.height : 0;
+  const { contentPadding } = resolveScreenContentInsets(
+    margin,
+    marginsEnabled,
+    bottomInset,
+    compactHeaderHeight
+  );
+
+  return (
+    <Animated.ScrollView
+      ref={scrollRef}
+      style={style}
+      horizontal={horizontal}
+      showsVerticalScrollIndicator={false}
+      scrollEventThrottle={16}
+      contentContainerStyle={contentPadding}
+      snapToOffsets={headerSnapOffsets}
+      {...rest}
+      onScroll={composedHandler}
+    >
+      <View>
+        <PortalHost />
+      </View>
+      <View
+        style={[
+          contentContainerStyle,
+          { flexDirection: horizontal ? 'row' : 'column' },
+        ]}
+      >
+        {/* content spacing */}
+        {children}
+      </View>
+    </Animated.ScrollView>
+  );
+}

package/src/components/screen/index.ts

@@ -0,0 +1,8 @@
+export type { ScreenHeaderProps, ScreenProps } from './Screen';
+export { Screen } from './Screen';
+export type { ScreenContextValue } from './ScreenContext';
+export { useScreen } from './ScreenContext';
+export type { ScreenFlatListProps } from './ScreenFlatList';
+export { ScreenFlatList } from './ScreenFlatList';
+export type { ScreenScrollViewProps } from './ScreenScrollView';
+export { ScreenScrollView } from './ScreenScrollView';

package/src/components/screen/utils.ts

@@ -0,0 +1,17 @@
+import type { LayoutTokens } from '#theme/types';
+
+export function resolveScreenContentInsets(
+  margin: LayoutTokens['screen']['margin'],
+  margins: boolean,
+  bottomInset?: number,
+  topInset?: number
+) {
+  return {
+    contentPadding: {
+      flexGrow: 1 as const,
+      paddingTop: topInset ?? 0,
+      paddingHorizontal: margins ? margin.x : 0,
+      paddingBottom: bottomInset ?? (margins ? margin.y : 0),
+    },
+  };
+}

package/src/components/slot/Slot.tsx

@@ -0,0 +1,56 @@
+import {
+  cloneElement,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from 'react';
+
+import { composeRefs, mergeProps } from './utils';
+
+type AnyProps = Record<string, unknown>;
+
+export interface SlotProps {
+  /** Props (incl. pre-merged `style` and optional `ref`) to merge onto the child. */
+  slotProps: AnyProps;
+  /** Name used in dev warnings. */
+  ownerName?: string;
+  children: ReactNode;
+}
+
+/**
+ * Radix-style Slot: merges `slotProps` onto a single child element instead of
+ * rendering a wrapper. Composes `on*` handlers (child first), `style`
+ * (`[slotStyle, childStyle]`), and refs.
+ */
+export function Slot({
+  slotProps,
+  ownerName = 'Component',
+  children,
+}: SlotProps): ReactElement | null {
+  if (!isValidElement(children)) {
+    if (__DEV__ && children != null) {
+      console.error(
+        `[${ownerName}] \`asChild\` expects exactly one React element child.`
+      );
+    }
+    return null;
+  }
+
+  const child = children as ReactElement;
+  const childProps = (child.props ?? {}) as AnyProps;
+
+  const { ref: slotRef, ...restSlotProps } = slotProps;
+  const { ref: childRef, ...restChildProps } = childProps;
+
+  const merged = mergeProps(restSlotProps, restChildProps);
+  const composedRef = composeRefs(
+    slotRef as Ref<unknown> | undefined,
+    childRef as Ref<unknown> | undefined
+  );
+
+  return cloneElement(child, {
+    ...merged,
+    ref: composedRef,
+  } as Partial<unknown> & AnyProps);
+}

package/src/components/slot/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Low-level composition helpers for advanced use cases (custom primitives,
+ * `asChild` patterns). Most apps should use component APIs directly.
+ */
+
+export type { SlotProps } from './Slot';
+export { Slot } from './Slot';
+export { composeRefs, mergeProps } from './utils';

package/src/components/slot/utils.ts

@@ -0,0 +1,61 @@
+import type { MutableRefObject, Ref } from 'react';
+
+function assignRef<T>(ref: Ref<T> | undefined, value: T | null): void {
+  if (typeof ref === 'function') {
+    ref(value);
+  } else if (ref != null) {
+    (ref as MutableRefObject<T | null>).current = value;
+  }
+}
+
+/** Composes multiple refs so each receives the node. */
+export function composeRefs<T>(...refs: (Ref<T> | undefined)[]): Ref<T> {
+  return (node: T | null) => {
+    for (const ref of refs) {
+      assignRef(ref, node);
+    }
+  };
+}
+
+type AnyProps = Record<string, unknown>;
+
+const isEventHandler = (key: string): boolean => /^on[A-Z]/.test(key);
+
+/**
+ * Merges slot props with the child's own props (child wins), following the
+ * Radix Slot rules:
+ * - `on*` handlers are composed (child runs first, then slot),
+ * - `style` is merged as `[slotStyle, childStyle]`,
+ * - all other child props override slot props.
+ *
+ * `ref`/`style` are intentionally not handled here — the caller composes refs
+ * and passes a pre-merged `style` via `slotProps`.
+ */
+export function mergeProps(
+  slotProps: AnyProps,
+  childProps: AnyProps
+): AnyProps {
+  const merged: AnyProps = { ...slotProps };
+
+  for (const key of Object.keys(childProps)) {
+    const slotValue = slotProps[key];
+    const childValue = childProps[key];
+
+    if (isEventHandler(key)) {
+      if (typeof slotValue === 'function' && typeof childValue === 'function') {
+        merged[key] = (...args: unknown[]) => {
+          (childValue as (...a: unknown[]) => void)(...args);
+          (slotValue as (...a: unknown[]) => void)(...args);
+        };
+      } else {
+        merged[key] = childValue ?? slotValue;
+      }
+    } else if (key === 'style') {
+      merged.style = [slotValue, childValue].filter(Boolean);
+    } else {
+      merged[key] = childValue;
+    }
+  }
+
+  return merged;
+}

package/src/components/spinner/Spinner.tsx

@@ -0,0 +1,153 @@
+import { memo, useEffect, useId } from 'react';
+
+import Animated, {
+  cancelAnimation,
+  Easing,
+  useAnimatedStyle,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+} from 'react-native-reanimated';
+import Svg, { Defs, G, LinearGradient, Path, Stop } from 'react-native-svg';
+
+import { useUnistyles } from 'react-native-unistyles';
+
+import type { ColorToken } from '#theme/types';
+import { resolveThemeColor } from '#utils/resolve-theme-color';
+
+export type SpinnerSize = 'sm' | 'md' | 'lg';
+
+export interface SpinnerProps {
+  /** Spinner diameter preset. Defaults to `'md'`. */
+  size?: SpinnerSize;
+  /** Theme color token or raw CSS color. Defaults to the accent color. */
+  color?: ColorToken;
+}
+
+const DIMENSION: Record<SpinnerSize, number> = { sm: 16, md: 24, lg: 32 };
+
+const ROTATION_DURATION = 900;
+
+// HeroUI spinner arcs — two gradient-filled segments in a 24×24 viewBox.
+const LEFT_ARC =
+  'M8.749.021a1.5 1.5 0 0 1 .497 2.958A7.5 7.5 0 0 0 3 10.375a7.5 7.5 0 0 0 7.5 7.5v3c-5.799 0-10.5-4.7-10.5-10.5C0 5.23 3.726.865 8.749.021';
+const RIGHT_ARC =
+  'M15.392 2.673a1.5 1.5 0 0 1 2.119-.115A10.48 10.48 0 0 1 21 10.375c0 5.8-4.701 10.5-10.5 10.5v-3a7.5 7.5 0 0 0 5.007-13.084a1.5 1.5 0 0 1-.115-2.118';
+const ARC_TRANSFORM = 'translate(1.5 1.625)';
+
+interface SpinnerIconProps {
+  size: number;
+  color: string;
+  gradientId1: string;
+  gradientId2: string;
+}
+
+const SpinnerIcon = memo(function SpinnerIcon({
+  size,
+  color,
+  gradientId1,
+  gradientId2,
+}: SpinnerIconProps) {
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24">
+      <Defs>
+        <LinearGradient
+          id={gradientId1}
+          x1="50%"
+          x2="50%"
+          y1="5.271%"
+          y2="91.793%"
+        >
+          <Stop offset="0%" stopColor={color} />
+          <Stop offset="100%" stopColor={color} stopOpacity={0.55} />
+        </LinearGradient>
+        <LinearGradient
+          id={gradientId2}
+          x1="50%"
+          x2="50%"
+          y1="15.24%"
+          y2="87.15%"
+        >
+          <Stop offset="0%" stopColor={color} stopOpacity={0} />
+          <Stop offset="100%" stopColor={color} stopOpacity={0.55} />
+        </LinearGradient>
+      </Defs>
+      <G fill="none">
+        <Path
+          d={LEFT_ARC}
+          fill={`url(#${gradientId1})`}
+          transform={ARC_TRANSFORM}
+        />
+        <Path
+          d={RIGHT_ARC}
+          fill={`url(#${gradientId2})`}
+          transform={ARC_TRANSFORM}
+        />
+      </G>
+    </Svg>
+  );
+});
+
+/**
+ * Animated loading spinner. Used by `Button` when `isLoading` is set.
+ *
+ * @example
+ * ```tsx
+ * <Spinner size="md" color="content.accent" />
+ * ```
+ */
+export function Spinner({ size = 'md', color = 'text.accent' }: SpinnerProps) {
+  const { theme } = useUnistyles();
+  const id = useId();
+  const gradientId1 = `spinner-def-1-${id}`;
+  const gradientId2 = `spinner-def-2-${id}`;
+  const resolvedColor =
+    resolveThemeColor(color, theme) ??
+    (theme.color as unknown as Record<string, string | undefined>)[
+      'text.accent'
+    ] ??
+    '';
+
+  const dim = DIMENSION[size];
+  const rotation = useSharedValue(0);
+
+  useEffect(() => {
+    // Fast refresh can remount without running cleanup — cancel any stale loop first.
+    cancelAnimation(rotation);
+    rotation.value = 0;
+    rotation.value = withRepeat(
+      withTiming(360, {
+        duration: ROTATION_DURATION,
+        easing: Easing.linear,
+      }),
+      -1,
+      false
+    );
+
+    return () => {
+      cancelAnimation(rotation);
+      rotation.value = 0;
+    };
+  }, [rotation]);
+
+  const animStyle = useAnimatedStyle(() => ({
+    transform: [{ rotate: `${rotation.value}deg` }],
+  }));
+
+  return (
+    <Animated.View
+      accessible
+      accessibilityRole="progressbar"
+      accessibilityLabel="Loading"
+      collapsable={false}
+      style={[{ width: dim, height: dim }, animStyle]}
+    >
+      <SpinnerIcon
+        size={dim}
+        color={resolvedColor}
+        gradientId1={gradientId1}
+        gradientId2={gradientId2}
+      />
+    </Animated.View>
+  );
+}

package/src/components/spinner/index.ts

@@ -0,0 +1,2 @@
+export type { SpinnerProps, SpinnerSize } from './Spinner';
+export { Spinner } from './Spinner';