react-native-terra-ui 0.1.0

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

@@ -0,0 +1,208 @@
+import type { ViewStyle } from 'react-native';
+
+import type { SharedValue } from 'react-native-reanimated';
+
+/** Duration for a single-page `current` transition. */
+export const PAGE_INDICATOR_SINGLE_PAGE_DURATION = 600;
+
+/** Extra duration per additional page when jumping more than one step. */
+export const PAGE_INDICATOR_MULTI_PAGE_DURATION_STEP = 100;
+
+/** Upper bound for multi-page `current` transitions. */
+export const PAGE_INDICATOR_MULTI_PAGE_DURATION_MAX = 600;
+
+/** Default max dots visible before scrolling and edge scaling kick in. */
+export const DEFAULT_PAGE_INDICATOR_MAX_VISIBLE = 5;
+
+const EDGE_OUTWARD_SCALE = [1, 0.9, 0.9, 0.65, 0.5] as const;
+const CENTERED_SCALE = [1, 0.9, 0.65, 0.5] as const;
+const WINDOW_TAIL_SCALE = 0.5;
+
+/** Absolute page delta between two indices. */
+export function pageIndicatorPageJumpDistance(
+  from: number,
+  to: number
+): number {
+  return Math.abs(to - from);
+}
+
+/**
+ * Scales transition time for discrete `current` changes. Single-step jumps stay
+ * snappy; longer jumps get more time (capped) so the pill does not blur
+ * through intermediate dots.
+ */
+export function pageIndicatorPageJumpDuration(
+  from: number,
+  to: number
+): number {
+  const distance = pageIndicatorPageJumpDistance(from, to);
+  if (distance <= 1) return PAGE_INDICATOR_SINGLE_PAGE_DURATION;
+
+  return Math.min(
+    PAGE_INDICATOR_SINGLE_PAGE_DURATION +
+      PAGE_INDICATOR_MULTI_PAGE_DURATION_STEP * (distance - 1),
+    PAGE_INDICATOR_MULTI_PAGE_DURATION_MAX
+  );
+}
+
+export function isPageIndicatorSharedValue(
+  value: number | SharedValue<number>
+): value is SharedValue<number> {
+  return typeof value === 'object' && value !== null && 'value' in value;
+}
+
+/** Transform style for overflow track scrolling along the main axis. */
+export function pageIndicatorAxisTranslateStyle(
+  vertical: boolean,
+  translate: number
+) {
+  'worklet';
+  return {
+    transform: vertical
+      ? [{ translateY: translate }]
+      : [{ translateX: translate }],
+  };
+}
+
+/** Clips an overflowing track to the visible viewport along the main axis. */
+export function pageIndicatorViewportClipStyle(
+  vertical: boolean,
+  viewportMainSize: number,
+  crossSize?: number
+): ViewStyle {
+  if (vertical) {
+    return {
+      height: viewportMainSize,
+      ...(crossSize !== undefined ? { width: crossSize } : {}),
+      overflow: 'hidden',
+    };
+  }
+
+  return {
+    width: viewportMainSize,
+    ...(crossSize !== undefined ? { height: crossSize } : {}),
+    overflow: 'hidden',
+  };
+}
+
+function scaleCurveValue(
+  curve: readonly number[],
+  distance: number,
+  tailScale: number
+): number {
+  'worklet';
+  if (distance < curve.length) return curve[distance] ?? tailScale;
+  return tailScale;
+}
+
+/** Scale for a slot inside the window given the active slot. */
+export function pageIndicatorWindowSlotScale(
+  positionInWindow: number,
+  activeSlot: number,
+  maxVisible: number
+): number {
+  'worklet';
+  if (positionInWindow === activeSlot) return 1;
+
+  const dist = Math.abs(positionInWindow - activeSlot);
+
+  if (activeSlot === 0 || activeSlot === maxVisible - 1) {
+    return scaleCurveValue(EDGE_OUTWARD_SCALE, dist, WINDOW_TAIL_SCALE);
+  }
+
+  const centerSlot = Math.floor((maxVisible - 1) / 2);
+  if (activeSlot === centerSlot) {
+    return scaleCurveValue(CENTERED_SCALE, dist, WINDOW_TAIL_SCALE);
+  }
+
+  if (positionInWindow < activeSlot) {
+    if (activeSlot <= 1) {
+      return scaleCurveValue(EDGE_OUTWARD_SCALE, dist, WINDOW_TAIL_SCALE);
+    }
+    return scaleCurveValue(CENTERED_SCALE, dist, WINDOW_TAIL_SCALE);
+  }
+
+  if (activeSlot >= maxVisible - 2) {
+    return scaleCurveValue(EDGE_OUTWARD_SCALE, dist, WINDOW_TAIL_SCALE);
+  }
+
+  return scaleCurveValue(CENTERED_SCALE, dist, WINDOW_TAIL_SCALE);
+}
+
+export function pageIndicatorTrackMainSize(
+  count: number,
+  slot: number,
+  dotSize: number,
+  activeMainSize = dotSize
+): number {
+  return Math.max(dotSize, (count - 1) * slot + activeMainSize);
+}
+
+export function pageIndicatorViewportMainSize(
+  count: number,
+  slot: number,
+  dotSize: number,
+  maxVisible: number,
+  activeMainSize = dotSize
+): number {
+  const visible = Math.min(count, maxVisible);
+  return Math.max(dotSize, (visible - 1) * slot + activeMainSize);
+}
+
+export function computePageIndicatorWindowTranslate(
+  count: number,
+  progress: number,
+  slot: number,
+  dotSize: number,
+  maxVisible: number,
+  activeMainSize = dotSize
+): number {
+  'worklet';
+  if (count <= maxVisible) return 0;
+
+  const viewportMainSize = Math.max(
+    dotSize,
+    (maxVisible - 1) * slot + activeMainSize
+  );
+  const trackMainSize = Math.max(dotSize, (count - 1) * slot + activeMainSize);
+  const activeCenter = progress * slot + activeMainSize / 2;
+  const offset = Math.min(
+    Math.max(activeCenter - viewportMainSize / 2, 0),
+    trackMainSize - viewportMainSize
+  );
+
+  return -offset;
+}
+
+export function pageIndicatorWindowScale(
+  index: number,
+  displayProgress: number,
+  count: number,
+  slot: number,
+  dotSize: number,
+  maxVisible: number,
+  activeMainSize = dotSize
+): number {
+  'worklet';
+  if (count <= maxVisible) return 1;
+
+  const translate = computePageIndicatorWindowTranslate(
+    count,
+    displayProgress,
+    slot,
+    dotSize,
+    maxVisible,
+    activeMainSize
+  );
+  const visibleStart = -translate / slot;
+  const activeSlot = Math.min(
+    Math.max(Math.round(displayProgress - visibleStart), 0),
+    maxVisible - 1
+  );
+  const positionInWindow = Math.min(
+    Math.max(Math.round(index - visibleStart), 0),
+    maxVisible - 1
+  );
+
+  return pageIndicatorWindowSlotScale(positionInWindow, activeSlot, maxVisible);
+}

package/src/components/page-indicator/variants/DotIndicator/InactiveDot.tsx

@@ -0,0 +1,70 @@
+import Animated, {
+  type SharedValue,
+  useAnimatedStyle,
+} from 'react-native-reanimated';
+
+import { pageIndicatorWindowScale } from '../../utils';
+
+import { DOT_INDICATOR_GEOMETRY, pageIndicatorDotCenter } from './utils';
+
+interface InactiveDotProps {
+  color: string;
+  count: number;
+  index: number;
+  maxVisible: number;
+  opacity: number;
+  overflows: boolean;
+  progress: SharedValue<number>;
+  vertical: boolean;
+}
+
+export function InactiveDot({
+  color,
+  count,
+  index,
+  maxVisible,
+  opacity,
+  overflows,
+  progress,
+  vertical,
+}: InactiveDotProps) {
+  const { dotSize, slot, crossSize } = DOT_INDICATOR_GEOMETRY;
+  const crossOffset = (crossSize - dotSize) / 2;
+
+  const animatedStyle = useAnimatedStyle(() => {
+    const center = pageIndicatorDotCenter(index, slot, dotSize);
+    const windowScale = overflows
+      ? pageIndicatorWindowScale(
+          index,
+          progress.value,
+          count,
+          slot,
+          dotSize,
+          maxVisible
+        )
+      : 1;
+
+    return {
+      ...(vertical
+        ? { top: center - dotSize / 2, left: crossOffset }
+        : { left: center - dotSize / 2, top: crossOffset }),
+      transform: [{ scale: windowScale }],
+    };
+  });
+
+  return (
+    <Animated.View
+      style={[
+        {
+          position: 'absolute',
+          width: dotSize,
+          height: dotSize,
+          borderRadius: 999,
+          backgroundColor: color,
+          opacity,
+        },
+        animatedStyle,
+      ]}
+    />
+  );
+}

package/src/components/page-indicator/variants/DotIndicator/LoadingOrbit.tsx

@@ -0,0 +1,201 @@
+import { useEffect } from 'react';
+
+import Animated, {
+  Extrapolation,
+  interpolate,
+  type SharedValue,
+  useAnimatedProps,
+  useAnimatedStyle,
+  useFrameCallback,
+  useSharedValue,
+} from 'react-native-reanimated';
+import Svg, { Circle } from 'react-native-svg';
+
+import { DOT_INDICATOR_GEOMETRY, pageIndicatorDotCenter } from './utils';
+
+const ORBIT_ARCS = [
+  { id: 'arc-1', arcDegrees: 120, duration: 800, delay: 0 },
+  { id: 'arc-2', arcDegrees: 60, duration: 1200, delay: 50 },
+  { id: 'arc-3', arcDegrees: 30, duration: 1600, delay: 200 },
+] as const;
+
+const ORBIT_LOOP_DURATION = Math.max(
+  ...ORBIT_ARCS.map((arc) => arc.delay + arc.duration)
+);
+
+const ORBIT_SETTLE_THRESHOLD = 0.04;
+
+const AnimatedCircle = Animated.createAnimatedComponent(Circle);
+
+function computeSweepArcState(
+  clock: number,
+  delay: number,
+  duration: number,
+  arcDegrees: number
+) {
+  'worklet';
+  const elapsed = clock * ORBIT_LOOP_DURATION;
+  const localProgress = Math.min(Math.max((elapsed - delay) / duration, 0), 1);
+  const leadTravel = 360 + arcDegrees;
+  const lead = leadTravel * localProgress;
+  const tailVisible = Math.min(Math.max(lead - arcDegrees, 0), 360);
+  const headVisible = Math.min(Math.max(lead, 0), 360);
+  const visibleDegrees = Math.max(0, headVisible - tailVisible);
+
+  return { tailVisible, visibleDegrees };
+}
+
+interface SweepArcProps {
+  color: string;
+  arcDegrees: number;
+  duration: number;
+  delay: number;
+  clock: SharedValue<number>;
+}
+
+function SweepArc({
+  color,
+  arcDegrees,
+  duration,
+  delay,
+  clock,
+}: SweepArcProps) {
+  const { ringSize, ringStroke, ringRadius, ringCircumference } =
+    DOT_INDICATOR_GEOMETRY;
+
+  const containerStyle = useAnimatedStyle(() => {
+    const { tailVisible, visibleDegrees } = computeSweepArcState(
+      clock.value,
+      delay,
+      duration,
+      arcDegrees
+    );
+
+    return {
+      opacity: visibleDegrees > 0.01 ? 1 : 0,
+      transform: [{ rotate: `${90 + tailVisible}deg` }],
+    };
+  });
+
+  const animatedProps = useAnimatedProps(() => {
+    const { visibleDegrees } = computeSweepArcState(
+      clock.value,
+      delay,
+      duration,
+      arcDegrees
+    );
+    const dash = (ringCircumference * visibleDegrees) / 360;
+
+    return { strokeDasharray: [dash, ringCircumference] };
+  });
+
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[
+        { position: 'absolute', width: ringSize, height: ringSize },
+        containerStyle,
+      ]}
+    >
+      <Svg width={ringSize} height={ringSize}>
+        <AnimatedCircle
+          cx={ringSize / 2}
+          cy={ringSize / 2}
+          r={ringRadius}
+          stroke={color}
+          strokeWidth={ringStroke}
+          strokeLinecap="round"
+          fill="none"
+          animatedProps={animatedProps}
+        />
+      </Svg>
+    </Animated.View>
+  );
+}
+
+interface LoadingOrbitProps {
+  color: string;
+  count: number;
+  loading: boolean;
+  progress: SharedValue<number>;
+  vertical: boolean;
+}
+
+export function LoadingOrbit({
+  color,
+  count,
+  loading,
+  progress,
+  vertical,
+}: LoadingOrbitProps) {
+  const { dotSize, slot, crossSize, ringSize } = DOT_INDICATOR_GEOMETRY;
+  const crossOffset = (crossSize - ringSize) / 2;
+  const clock = useSharedValue(0);
+  const loadingActive = useSharedValue(loading);
+
+  useEffect(() => {
+    loadingActive.value = loading;
+  }, [loading, loadingActive]);
+
+  const frameCallback = useFrameCallback((frame) => {
+    if (!loadingActive.value) return;
+
+    const activeIndex = Math.min(
+      Math.max(Math.round(progress.value), 0),
+      count - 1
+    );
+    const settleDistance = Math.abs(progress.value - activeIndex);
+
+    if (settleDistance >= ORBIT_SETTLE_THRESHOLD) return;
+
+    const dt = frame.timeSincePreviousFrame ?? 0;
+    clock.value = (clock.value + dt / ORBIT_LOOP_DURATION) % 1;
+  });
+
+  useEffect(() => {
+    frameCallback.setActive(loading);
+  }, [frameCallback, loading]);
+
+  const containerStyle = useAnimatedStyle(() => {
+    const activeIndex = Math.min(
+      Math.max(Math.round(progress.value), 0),
+      count - 1
+    );
+    const settleDistance = Math.abs(progress.value - activeIndex);
+    const mainOffset =
+      pageIndicatorDotCenter(activeIndex, slot, dotSize) - ringSize / 2;
+
+    return {
+      ...(vertical ? { top: mainOffset } : { left: mainOffset }),
+      opacity: loadingActive.value
+        ? interpolate(settleDistance, [0, 0.12], [1, 0], Extrapolation.CLAMP)
+        : 0,
+    };
+  });
+
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[
+        {
+          position: 'absolute',
+          ...(vertical
+            ? { left: crossOffset, width: ringSize, height: ringSize }
+            : { top: crossOffset, width: ringSize, height: ringSize }),
+        },
+        containerStyle,
+      ]}
+    >
+      {ORBIT_ARCS.map((arc) => (
+        <SweepArc
+          key={arc.id}
+          color={color}
+          arcDegrees={arc.arcDegrees}
+          duration={arc.duration}
+          delay={arc.delay}
+          clock={clock}
+        />
+      ))}
+    </Animated.View>
+  );
+}

package/src/components/page-indicator/variants/DotIndicator/TravelingPill.tsx

@@ -0,0 +1,80 @@
+import Animated, {
+  Extrapolation,
+  interpolate,
+  type SharedValue,
+  useAnimatedStyle,
+} from 'react-native-reanimated';
+
+import { DOT_INDICATOR_GEOMETRY, pageIndicatorDotCenter } from './utils';
+
+interface TravelingPillProps {
+  activeColor: string;
+  count: number;
+  progress: SharedValue<number>;
+  vertical: boolean;
+}
+
+/**
+ * A single pill on top of the resting dots. As `progress` moves between pages
+ * its leading edge advances first (stretch), then its trailing edge catches up
+ * (collapse).
+ */
+export function TravelingPill({
+  activeColor,
+  count,
+  progress,
+  vertical,
+}: TravelingPillProps) {
+  const { dotSize, slot, crossSize } = DOT_INDICATOR_GEOMETRY;
+  const crossOffset = (crossSize - dotSize) / 2;
+
+  const animatedStyle = useAnimatedStyle(() => {
+    const maxSegment = Math.max(0, count - 2);
+    const segment = Math.min(
+      Math.max(Math.floor(progress.value), 0),
+      maxSegment
+    );
+    const frac = progress.value - segment;
+
+    const from = pageIndicatorDotCenter(segment, slot, dotSize);
+    const to = pageIndicatorDotCenter(segment + 1, slot, dotSize);
+
+    const leading = interpolate(
+      frac,
+      [0, 0.5, 1],
+      [from - dotSize / 2, from - dotSize / 2, to - dotSize / 2],
+      Extrapolation.CLAMP
+    );
+    const trailing = interpolate(
+      frac,
+      [0, 0.5, 1],
+      [from + dotSize / 2, to + dotSize / 2, to + dotSize / 2],
+      Extrapolation.CLAMP
+    );
+    const mainSize = Math.max(dotSize, trailing - leading);
+
+    if (vertical) {
+      return { top: leading, height: mainSize };
+    }
+
+    return { left: leading, width: mainSize };
+  });
+
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[
+        {
+          position: 'absolute',
+          ...(vertical
+            ? { left: crossOffset, width: dotSize }
+            : { top: crossOffset, height: dotSize }),
+          borderRadius: 999,
+          backgroundColor: activeColor,
+          zIndex: 2,
+        },
+        animatedStyle,
+      ]}
+    />
+  );
+}

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

@@ -0,0 +1,145 @@
+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 { InactiveDot } from './InactiveDot';
+import { LoadingOrbit } from './LoadingOrbit';
+import { TravelingPill } from './TravelingPill';
+import { DOT_INDICATOR_GEOMETRY } from './utils';
+
+export interface DotIndicatorProps {
+  /** 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 `250`. */
+  duration?: number;
+  /** Active page color token. */
+  activeColor?: ColorToken;
+  /** Inactive page color token. */
+  inactiveColor?: ColorToken;
+  /** Loading ring color token. */
+  loadingColor?: ColorToken;
+  /** Renders a ring around the active dot while loading. */
+  loading?: boolean;
+  /** Stack dots 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 DotIndicator({
+  count,
+  current = 0,
+  duration = PAGE_INDICATOR_SINGLE_PAGE_DURATION,
+  activeColor,
+  inactiveColor,
+  loadingColor,
+  loading = false,
+  vertical = false,
+  maxVisible = DEFAULT_PAGE_INDICATOR_MAX_VISIBLE,
+  style,
+}: DotIndicatorProps) {
+  const { colors, progress } = usePageIndicatorCore(
+    count,
+    current,
+    'dot',
+    duration,
+    { activeColor, inactiveColor, loadingColor }
+  );
+
+  const { dotSize, slot, crossSize, inactiveOpacity } = DOT_INDICATOR_GEOMETRY;
+  const viewportMainSize = pageIndicatorViewportMainSize(
+    count,
+    slot,
+    dotSize,
+    maxVisible
+  );
+  const fullTrackMainSize = pageIndicatorTrackMainSize(count, slot, dotSize);
+  const overflows = count > maxVisible;
+
+  const indices = useMemo(
+    () => Array.from({ length: count }, (_, index) => index),
+    [count]
+  );
+
+  const trackStyle = useAnimatedStyle(() => {
+    const translate = computePageIndicatorWindowTranslate(
+      count,
+      progress.value,
+      slot,
+      dotSize,
+      maxVisible
+    );
+
+    return pageIndicatorAxisTranslateStyle(vertical, translate);
+  });
+
+  return (
+    <PageIndicatorRoot
+      crossSize={crossSize}
+      overflows={overflows}
+      style={style}
+      vertical={vertical}
+      viewportMainSize={viewportMainSize}
+    >
+      <Animated.View
+        style={[
+          vertical
+            ? { width: crossSize, height: fullTrackMainSize }
+            : { width: fullTrackMainSize, height: crossSize },
+          overflows ? trackStyle : null,
+        ]}
+      >
+        {indices.map((index) => (
+          <InactiveDot
+            key={index}
+            color={colors.inactiveColor}
+            count={count}
+            index={index}
+            maxVisible={maxVisible}
+            opacity={inactiveOpacity}
+            overflows={overflows}
+            progress={progress}
+            vertical={vertical}
+          />
+        ))}
+        <TravelingPill
+          activeColor={colors.activeColor}
+          count={count}
+          progress={progress}
+          vertical={vertical}
+        />
+        <LoadingOrbit
+          color={colors.loadingColor}
+          count={count}
+          loading={loading}
+          progress={progress}
+          vertical={vertical}
+        />
+      </Animated.View>
+    </PageIndicatorRoot>
+  );
+}