react-native-terra-ui 0.1.0

package/src/components/page-indicator/variants/DotIndicator/utils.ts

@@ -0,0 +1,28 @@
+/** Fixed geometry for the dot indicator variant. */
+const DOT_SIZE = 8;
+const GAP = 8;
+const RING_SIZE = 14;
+const RING_STROKE = 1.5;
+const RING_RADIUS = (RING_SIZE - RING_STROKE) / 2;
+
+/** Precomputed geometry shared by DotIndicator sub-components. */
+export const DOT_INDICATOR_GEOMETRY = {
+  dotSize: DOT_SIZE,
+  slot: DOT_SIZE + GAP,
+  crossSize: Math.max(RING_SIZE, DOT_SIZE),
+  ringSize: RING_SIZE,
+  ringStroke: RING_STROKE,
+  ringRadius: RING_RADIUS,
+  ringCircumference: 2 * Math.PI * RING_RADIUS,
+  inactiveOpacity: 0.42,
+} as const;
+
+/** Main-axis center of dot `index` within the track. */
+export function pageIndicatorDotCenter(
+  index: number,
+  slot: number,
+  dotSize: number
+): number {
+  'worklet';
+  return index * slot + dotSize / 2;
+}

package/src/components/page-indicator/variants/PillIndicator/PillIndicatorDot.tsx

@@ -0,0 +1,107 @@
+import Animated, {
+  Extrapolation,
+  interpolate,
+  interpolateColor,
+  type SharedValue,
+  useAnimatedStyle,
+} from 'react-native-reanimated';
+
+import type { PillJumpState } from '../../hooks/use-page-indicator-progress';
+import { pageIndicatorWindowScale } from '../../utils';
+
+import {
+  PILL_INDICATOR_GEOMETRY,
+  pillIndicatorDotDistance,
+  pillIndicatorJumpDisplayProgress,
+  readPillJumpState,
+} from './utils';
+
+interface PillIndicatorDotProps {
+  activeColor: string;
+  inactiveColor: string;
+  count: number;
+  index: number;
+  maxVisible: number;
+  overflows: boolean;
+  pillJump: PillJumpState;
+  progress: SharedValue<number>;
+  vertical: boolean;
+}
+
+export function PillIndicatorDot({
+  activeColor,
+  inactiveColor,
+  count,
+  index,
+  maxVisible,
+  overflows,
+  pillJump,
+  progress,
+  vertical,
+}: PillIndicatorDotProps) {
+  const { dotSize, activeWidth, inactiveOpacity, inactiveScale, slot } =
+    PILL_INDICATOR_GEOMETRY;
+
+  const animatedStyle = useAnimatedStyle(() => {
+    const jump = readPillJumpState(pillJump);
+    const displayProgress = pillIndicatorJumpDisplayProgress(
+      progress.value,
+      jump.active,
+      jump.from,
+      jump.to,
+      jump.t
+    );
+    const distance = pillIndicatorDotDistance(
+      index,
+      progress.value,
+      jump.active,
+      jump.from,
+      jump.to,
+      jump.t
+    );
+
+    const mainSize = interpolate(
+      distance,
+      [0, 1],
+      [activeWidth, dotSize],
+      Extrapolation.CLAMP
+    );
+    const activeScale = interpolate(
+      distance,
+      [0, 1],
+      [1, inactiveScale],
+      Extrapolation.CLAMP
+    );
+    const edgeScale = overflows
+      ? pageIndicatorWindowScale(
+          index,
+          displayProgress,
+          count,
+          slot,
+          dotSize,
+          maxVisible,
+          activeWidth
+        )
+      : 1;
+
+    return {
+      ...(vertical
+        ? { width: dotSize, height: mainSize }
+        : { width: mainSize, height: dotSize }),
+      opacity: interpolate(
+        distance,
+        [0, 1],
+        [1, inactiveOpacity],
+        Extrapolation.CLAMP
+      ),
+      transform: [{ scale: activeScale * edgeScale }],
+      backgroundColor: interpolateColor(
+        distance,
+        [0, 1],
+        [activeColor, inactiveColor]
+      ),
+    };
+  });
+
+  return <Animated.View style={[{ borderRadius: 999 }, animatedStyle]} />;
+}

package/src/components/page-indicator/variants/PillIndicator/index.tsx

@@ -0,0 +1,149 @@
+import { useMemo } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { SharedValue } from 'react-native-reanimated';
+import Animated, { useAnimatedStyle } from 'react-native-reanimated';
+
+import type { ColorToken } from '#theme/types';
+
+import { usePageIndicatorCore } from '../../hooks/use-page-indicator-core';
+import { PageIndicatorRoot } from '../../PageIndicatorRoot';
+import {
+  computePageIndicatorWindowTranslate,
+  DEFAULT_PAGE_INDICATOR_MAX_VISIBLE,
+  PAGE_INDICATOR_SINGLE_PAGE_DURATION,
+  pageIndicatorAxisTranslateStyle,
+  pageIndicatorTrackMainSize,
+  pageIndicatorViewportMainSize,
+} from '../../utils';
+
+import { PillIndicatorDot } from './PillIndicatorDot';
+import {
+  PILL_INDICATOR_GEOMETRY,
+  pillIndicatorJumpDisplayProgress,
+} from './utils';
+
+export interface PillIndicatorProps {
+  /** Number of pages represented by the indicator. */
+  count: number;
+  /**
+   * Active page index, or a shared value for scroll-linked motion.
+   * Index `0` is the first page; fractional values animate between pages.
+   */
+  current?: number | SharedValue<number>;
+  /** Duration for discrete `current` changes. Defaults to `600`. */
+  duration?: number;
+  /** Active page color token. */
+  activeColor?: ColorToken;
+  /** Inactive page color token. */
+  inactiveColor?: ColorToken;
+  /** Stack pills vertically instead of horizontally. */
+  vertical?: boolean;
+  /**
+   * Maximum dots visible before the track scrolls and edge-scales.
+   * Defaults to `5`. Overflow scrolling is off when `count <= maxVisible`.
+   */
+  maxVisible?: number;
+  style?: StyleProp<ViewStyle>;
+}
+
+export function PillIndicator({
+  count,
+  current = 0,
+  duration = PAGE_INDICATOR_SINGLE_PAGE_DURATION,
+  activeColor,
+  inactiveColor,
+  vertical = false,
+  maxVisible = DEFAULT_PAGE_INDICATOR_MAX_VISIBLE,
+  style,
+}: PillIndicatorProps) {
+  const { colors, pillJump, progress } = usePageIndicatorCore(
+    count,
+    current,
+    'pill',
+    duration,
+    { activeColor, inactiveColor }
+  );
+
+  const { dotSize, gap, slot, activeWidth } = PILL_INDICATOR_GEOMETRY;
+  const viewportMainSize = pageIndicatorViewportMainSize(
+    count,
+    slot,
+    dotSize,
+    maxVisible,
+    activeWidth
+  );
+  const fullTrackMainSize = pageIndicatorTrackMainSize(
+    count,
+    slot,
+    dotSize,
+    activeWidth
+  );
+  const overflows = count > maxVisible;
+
+  const indices = useMemo(
+    () => Array.from({ length: count }, (_, index) => index),
+    [count]
+  );
+
+  const trackStyle = useAnimatedStyle(() => {
+    const displayProgress = pillIndicatorJumpDisplayProgress(
+      progress.value,
+      pillJump.active.value,
+      pillJump.from.value,
+      pillJump.to.value,
+      pillJump.t.value
+    );
+
+    const translate = computePageIndicatorWindowTranslate(
+      count,
+      displayProgress,
+      slot,
+      dotSize,
+      maxVisible,
+      activeWidth
+    );
+
+    return pageIndicatorAxisTranslateStyle(vertical, translate);
+  });
+
+  return (
+    <PageIndicatorRoot
+      style={style}
+      vertical={vertical}
+      viewportMainSize={viewportMainSize}
+      overflows={overflows}
+    >
+      <Animated.View
+        style={[
+          {
+            flexDirection: vertical ? 'column' : 'row',
+            alignItems: 'center',
+            gap,
+            ...(overflows
+              ? vertical
+                ? { height: fullTrackMainSize }
+                : { width: fullTrackMainSize }
+              : undefined),
+          },
+          overflows ? trackStyle : null,
+        ]}
+      >
+        {indices.map((index) => (
+          <PillIndicatorDot
+            key={index}
+            activeColor={colors.activeColor}
+            inactiveColor={colors.inactiveColor}
+            count={count}
+            index={index}
+            pillJump={pillJump}
+            progress={progress}
+            vertical={vertical}
+            overflows={overflows}
+            maxVisible={maxVisible}
+          />
+        ))}
+      </Animated.View>
+    </PageIndicatorRoot>
+  );
+}

package/src/components/page-indicator/variants/PillIndicator/utils.ts

@@ -0,0 +1,63 @@
+import type { PillJumpState } from '../../hooks/use-page-indicator-progress';
+
+const DOT_SIZE = 8;
+const GAP = 8;
+
+/** Precomputed geometry shared by PillIndicator sub-components. */
+export const PILL_INDICATOR_GEOMETRY = {
+  dotSize: DOT_SIZE,
+  gap: GAP,
+  slot: DOT_SIZE + GAP,
+  activeWidth: 24,
+  inactiveOpacity: 0.42,
+  inactiveScale: 0.9,
+} as const;
+
+export type PillIndicatorGeometry = typeof PILL_INDICATOR_GEOMETRY;
+
+export function readPillJumpState(jump: PillJumpState) {
+  'worklet';
+  return {
+    active: jump.active.value,
+    from: jump.from.value,
+    to: jump.to.value,
+    t: jump.t.value,
+  };
+}
+
+export function pillIndicatorDotDistance(
+  index: number,
+  progress: number,
+  jumpActive: boolean,
+  jumpFrom: number,
+  jumpTo: number,
+  jumpT: number
+): number {
+  'worklet';
+  if (!jumpActive) {
+    return Math.min(Math.abs(progress - index), 1);
+  }
+
+  if (index === jumpFrom) {
+    return jumpT;
+  }
+
+  if (index === jumpTo) {
+    return 1 - jumpT;
+  }
+
+  return 1;
+}
+
+/** Progress for window translation during a multi-page pill jump. */
+export function pillIndicatorJumpDisplayProgress(
+  progress: number,
+  jumpActive: boolean,
+  jumpFrom: number,
+  jumpTo: number,
+  jumpT: number
+): number {
+  'worklet';
+  if (!jumpActive) return progress;
+  return jumpFrom + jumpT * (jumpTo - jumpFrom);
+}

package/src/components/portal/PortalContext.tsx

@@ -0,0 +1,27 @@
+import { createContext, type ReactNode, useContext } 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 const PortalContext = createContext<PortalContextValue | null>(null);
+
+/**
+ * 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;
+}

package/src/components/portal/PortalHost.tsx

@@ -0,0 +1,20 @@
+import { View } from 'react-native';
+
+import { usePortal } from './PortalContext';
+
+/**
+ * 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`).
+ */
+export function PortalHost() {
+  const { contents } = usePortal();
+
+  return (
+    <View collapsable={false}>
+      {Array.from(contents.entries()).map(([id, content]) => (
+        <View key={id}>{content}</View>
+      ))}
+    </View>
+  );
+}

package/src/components/portal/PortalProvider.tsx

@@ -0,0 +1,44 @@
+import { type ReactNode, useCallback, useMemo, useState } from 'react';
+
+import { PortalContext, type PortalContextValue } 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.
+ */
+export function PortalProvider({ children }: PortalProviderProps) {
+  const [contents, setContents] = useState<Map<string, ReactNode>>(
+    () => new Map()
+  );
+
+  const registerContent = useCallback((id: string, content: ReactNode) => {
+    setContents((prev) => {
+      const next = new Map(prev);
+      next.set(id, content);
+      return next;
+    });
+  }, []);
+
+  const unregisterContent = useCallback((id: string) => {
+    setContents((prev) => {
+      if (!prev.has(id)) return prev;
+      const next = new Map(prev);
+      next.delete(id);
+      return next;
+    });
+  }, []);
+
+  const value = useMemo<PortalContextValue>(
+    () => ({ registerContent, unregisterContent, contents }),
+    [registerContent, unregisterContent, contents]
+  );
+
+  return (
+    <PortalContext.Provider value={value}>{children}</PortalContext.Provider>
+  );
+}

package/src/components/portal/index.ts

@@ -0,0 +1,5 @@
+export type { PortalContextValue } from './PortalContext';
+export { usePortal } from './PortalContext';
+export { PortalHost } from './PortalHost';
+export type { PortalProviderProps } from './PortalProvider';
+export { PortalProvider } from './PortalProvider';

package/src/components/screen/Screen.tsx

@@ -0,0 +1,163 @@
+import {
+  Children,
+  type ComponentPropsWithoutRef,
+  type ComponentRef,
+  type ElementType,
+  Fragment,
+  forwardRef,
+  isValidElement,
+  type PropsWithChildren,
+  type ReactNode,
+  useMemo,
+} from 'react';
+import {
+  type Edge,
+  SafeAreaView,
+  type SafeAreaViewProps,
+} from 'react-native-safe-area-context';
+import { 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 { ScreenFlatList } from './ScreenFlatList';
+import { ScreenScrollView } from './ScreenScrollView';
+
+export type ScreenHeaderProps<T extends ElementType = typeof Fragment> =
+  PropsWithChildren<
+    {
+      /**
+       * Component to render the header as. Defaults to `Fragment` (no
+       * wrapper). Use this to cast the header to a different container,
+       * e.g. `as={View}` — any extra props are forwarded to it.
+       */
+      as?: T;
+    } & Omit<ComponentPropsWithoutRef<T>, 'children'>
+  >;
+
+/**
+ * Marker slot identifying the screen's header — its purpose is to let
+ * `Screen` detect a header synchronously and drop the `top` safe-area edge
+ * (the header manages its own top inset).
+ *
+ * Place a `Header.Title` / `Header.LargeTitle` (or any custom header) inside it.
+ *
+ * @example
+ * ```tsx
+ * <Screen.Header as={Header.Title} title="Meditate" />
+ * ```
+ */
+function ScreenHeader<T extends ElementType = typeof Fragment>({
+  children,
+  as,
+  ...rest
+}: ScreenHeaderProps<T>) {
+  const Component = as ?? Fragment;
+  return <Component {...rest}>{children}</Component>;
+}
+
+/** 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;
+  });
+  return found;
+}
+
+export interface ScreenProps extends Omit<SafeAreaViewProps, 'edges'> {
+  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.
+   */
+  margins?: boolean;
+}
+
+type ScreenComponent = ReturnType<
+  typeof forwardRef<ComponentRef<typeof SafeAreaView>, ScreenProps>
+> & {
+  Header: typeof ScreenHeader;
+  ScrollView: typeof ScreenScrollView;
+  FlatList: typeof ScreenFlatList;
+};
+
+/**
+ * Themed page container: solid themed background, safe-area handling, and a
+ * shared scroll context for headers. Pair with `Screen.ScrollView` /
+ * `Screen.FlatList` and a `Header.LargeTitle` / `Header.Title`.
+ *
+ * @example
+ * ```tsx
+ * <Screen>
+ *   <Screen.Header as={Header.LargeTitle} title="Meditate" />
+ *   <Screen.ScrollView>{content}</Screen.ScrollView>
+ * </Screen>
+ * ```
+ */
+const ScreenBase = forwardRef<ComponentRef<typeof SafeAreaView>, ScreenProps>(
+  function Screen(
+    {
+      children,
+      bg = 'background',
+      edges,
+      inTabView = false,
+      margins = true,
+      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]);
+
+    return (
+      <ScreenScrollProvider
+        isInTabView={inTabView}
+        margins={margins}
+        hasHeader={hasHeader}
+      >
+        <PortalProvider>
+          <SafeAreaView
+            ref={ref}
+            edges={safeEdges}
+            style={[{ flex: 1, backgroundColor }, style]}
+            {...rest}
+          >
+            {children}
+          </SafeAreaView>
+        </PortalProvider>
+      </ScreenScrollProvider>
+    );
+  }
+) as ScreenComponent;
+
+ScreenBase.Header = ScreenHeader;
+ScreenBase.ScrollView = ScreenScrollView;
+ScreenBase.FlatList = ScreenFlatList;
+
+export const Screen = ScreenBase;