react-native-terra-ui 0.11.17 → 0.12.0

package/src/components/accordion/hooks/use-accordion-core.ts

@@ -0,0 +1,51 @@
+import { useCallback, useState } from "react";
+
+import type { AccordionProps } from "../types";
+
+function toArray(value: string | string[] | null | undefined): string[] {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Owns which items are open. Both modes are stored as an array so the rest of
+ * the accordion never branches on `selectionMode`; the mode only decides what a
+ * toggle does and what shape `onValueChange` receives.
+ */
+export function useAccordionCore(props: AccordionProps) {
+  const isMultiple = props.selectionMode === "multiple";
+  const isControlled = props.value !== undefined;
+  const isCollapsible = isMultiple || props.isCollapsible !== false;
+
+  const [internal, setInternal] = useState<string[]>(() => toArray(props.defaultValue));
+  const expanded = isControlled ? toArray(props.value) : internal;
+
+  const { onValueChange } = props;
+
+  const toggle = useCallback(
+    (itemValue: string) => {
+      const isOpen = expanded.includes(itemValue);
+      let next: string[];
+
+      if (isMultiple) {
+        next = isOpen ? expanded.filter((v) => v !== itemValue) : [...expanded, itemValue];
+      } else if (isOpen) {
+        if (!isCollapsible) return;
+        next = [];
+      } else {
+        next = [itemValue];
+      }
+
+      if (!isControlled) setInternal(next);
+
+      if (isMultiple) {
+        (onValueChange as ((value: string[]) => void) | undefined)?.(next);
+      } else {
+        (onValueChange as ((value: string | null) => void) | undefined)?.(next[0] ?? null);
+      }
+    },
+    [expanded, isMultiple, isCollapsible, isControlled, onValueChange]
+  );
+
+  return { expanded, toggle };
+}

package/src/components/accordion/index.ts

@@ -0,0 +1,14 @@
+export { Accordion } from "./Accordion";
+export { useAccordionItem } from "./context";
+export type { AccordionContentProps } from "./parts/AccordionContent";
+export type { AccordionIndicatorProps } from "./parts/AccordionIndicator";
+export type { AccordionItemProps } from "./parts/AccordionItem";
+export type { AccordionTriggerProps } from "./parts/AccordionTrigger";
+export type {
+  AccordionItemState,
+  AccordionMultipleProps,
+  AccordionProps,
+  AccordionSelectionMode,
+  AccordionSingleProps,
+  AccordionVariant,
+} from "./types";

package/src/components/accordion/parts/AccordionContent.tsx

@@ -0,0 +1,96 @@
+import { Children, type ComponentRef, forwardRef, type ReactNode, useEffect, useState } from "react";
+import { type LayoutChangeEvent, View, type ViewProps } from "react-native";
+
+import Animated, { useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import { StyleSheet } from "react-native-unistyles";
+import { scheduleOnRN } from "react-native-worklets";
+
+import { Text } from "../../text";
+import { useAccordionItem } from "../context";
+import { ACCORDION_TIMING } from "../utils";
+
+export interface AccordionContentProps extends ViewProps {
+  /** The panel body. Strings and numbers are wrapped in body text. */
+  children?: ReactNode;
+}
+
+function renderBody(children: ReactNode): ReactNode {
+  return Children.map(children, (child) => {
+    if (typeof child === "string") {
+      return child.trim().length > 0 ? (
+        <Text variant="body-md" color="text.secondary">
+          {child}
+        </Text>
+      ) : null;
+    }
+    if (typeof child === "number") {
+      return (
+        <Text variant="body-md" color="text.secondary">
+          {child}
+        </Text>
+      );
+    }
+    return child;
+  });
+}
+
+export const AccordionContent = forwardRef<ComponentRef<typeof View>, AccordionContentProps>(
+  function AccordionContent({ children, style, onLayout: onLayoutProp, ...rest }, ref) {
+    const { isExpanded } = useAccordionItem();
+
+    // The body stays mounted while open and while the close animation runs,
+    // then unmounts so a long list of closed items costs nothing.
+    const [isMounted, setIsMounted] = useState(isExpanded);
+    const progress = useSharedValue(isExpanded ? 1 : 0);
+    // The body's natural height, read from its own layout. 0 until the first
+    // measurement lands.
+    const measured = useSharedValue(0);
+
+    useEffect(() => {
+      if (isExpanded) setIsMounted(true);
+      progress.value = withTiming(isExpanded ? 1 : 0, ACCORDION_TIMING, (finished) => {
+        if (finished && !isExpanded) scheduleOnRN(setIsMounted, false);
+      });
+    }, [isExpanded, progress]);
+
+    const onLayout = (event: LayoutChangeEvent) => {
+      measured.value = event.nativeEvent.layout.height;
+      onLayoutProp?.(event);
+    };
+
+    const clip = useAnimatedStyle(() => {
+      // Before the first measurement an item that starts open takes its auto
+      // height, and one that is just opening holds at 0 for the frame it takes
+      // to measure.
+      if (measured.value === 0) {
+        return { height: progress.value === 1 ? undefined : 0, opacity: progress.value };
+      }
+      return { height: measured.value * progress.value, opacity: progress.value };
+    });
+
+    if (!isMounted) return null;
+
+    return (
+      <Animated.View style={[styles.clip, clip]}>
+        {/* Not absolutely positioned: RN children do not shrink by default, so
+            this keeps its natural height inside the clipping parent and its
+            layout reports the height to animate towards. */}
+        <View ref={ref} {...rest} onLayout={onLayout} style={[styles.body, style]}>
+          {renderBody(children)}
+        </View>
+      </Animated.View>
+    );
+  }
+);
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create((theme) => ({
+  clip: {
+    overflow: "hidden",
+  },
+  body: {
+    gap: theme.spacing["2"],
+    paddingBottom: theme.spacing["4"],
+  },
+}));

package/src/components/accordion/parts/AccordionIndicator.tsx

@@ -0,0 +1,67 @@
+import { type ComponentRef, forwardRef, type ReactNode, useEffect } from "react";
+import type { View, ViewProps } from "react-native";
+
+import Animated, { useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import { StyleSheet } from "react-native-unistyles";
+
+import type { ColorToken } from "#theme/types";
+import { Icon } from "../../icon";
+import { useAccordionItem } from "../context";
+import { ACCORDION_TIMING } from "../utils";
+
+export interface AccordionIndicatorProps extends Omit<ViewProps, "children"> {
+  /** Chevron color. Ignored with custom `children`. Defaults to `'text.secondary'`. */
+  color?: ColorToken;
+  /** Chevron size in dp. Ignored with custom `children`. Defaults to `20`. */
+  size?: number;
+  /**
+   * Replaces the chevron. Custom content does not rotate — read `isExpanded`
+   * from the item's render function or `useAccordionItem()` to swap it instead.
+   */
+  children?: ReactNode;
+}
+
+export const AccordionIndicator = forwardRef<ComponentRef<typeof View>, AccordionIndicatorProps>(
+  function AccordionIndicator({ color = "text.secondary", size = 20, children, style, ...rest }, ref) {
+    const { isExpanded } = useAccordionItem();
+    // Seeded from the current state so an item that starts open shows its
+    // chevron already turned, with no animation on mount.
+    const progress = useSharedValue(isExpanded ? 1 : 0);
+
+    useEffect(() => {
+      progress.value = withTiming(isExpanded ? 1 : 0, ACCORDION_TIMING);
+    }, [isExpanded, progress]);
+
+    // `terra.chevron-right` is the chevron the library ships, so it is turned a
+    // quarter to point down when closed and a further half to point up when open.
+    const rotation = useAnimatedStyle(() => ({
+      transform: [{ rotate: `${90 + progress.value * 180}deg` }],
+    }));
+
+    const hasCustomContent = children !== undefined && children !== null;
+
+    return (
+      <Animated.View
+        ref={ref}
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+        style={[styles.indicator, hasCustomContent ? null : rotation, style]}
+        {...rest}
+      >
+        {hasCustomContent ? children : <Icon name="terra.chevron-right" color={color} size={size} />}
+      </Animated.View>
+    );
+  }
+);
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create(() => ({
+  // Pushes the indicator to the row's end even when the title is a custom node
+  // that does not take the free space itself.
+  indicator: {
+    marginStart: "auto",
+    alignItems: "center",
+    justifyContent: "center",
+  },
+}));

package/src/components/accordion/parts/AccordionItem.tsx

@@ -0,0 +1,55 @@
+import { type ComponentRef, forwardRef, type ReactNode, useCallback, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+
+import { StyleSheet } from "react-native-unistyles";
+
+import { AccordionItemContext, useAccordionContext } from "../context";
+import type { AccordionItemState } from "../types";
+
+export interface AccordionItemProps extends Omit<ViewProps, "children"> {
+  /** Identifies the item in the accordion's `value`. Unique within one accordion. */
+  value: string;
+  /** Disables this item only. Defaults to `false`. */
+  isDisabled?: boolean;
+  /**
+   * The item's trigger and content, or a function that receives the item's
+   * `{ isExpanded, isDisabled }` and returns them.
+   */
+  children?: ReactNode | ((state: AccordionItemState) => ReactNode);
+}
+
+export const AccordionItem = forwardRef<ComponentRef<typeof View>, AccordionItemProps>(function AccordionItem(
+  { value, isDisabled: isDisabledProp = false, children, style, ...rest },
+  ref
+) {
+  const { expanded, toggle: toggleValue, isDisabled: isAccordionDisabled } = useAccordionContext();
+
+  const isExpanded = expanded.includes(value);
+  const isDisabled = isAccordionDisabled || isDisabledProp;
+
+  const toggle = useCallback(() => {
+    if (!isDisabled) toggleValue(value);
+  }, [isDisabled, toggleValue, value]);
+
+  const context = useMemo(
+    () => ({ value, isExpanded, isDisabled, toggle }),
+    [value, isExpanded, isDisabled, toggle]
+  );
+
+  return (
+    <AccordionItemContext.Provider value={context}>
+      <View ref={ref} style={[styles.item, style]} {...rest}>
+        {typeof children === "function" ? children({ isExpanded, isDisabled }) : children}
+      </View>
+    </AccordionItemContext.Provider>
+  );
+});
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+// Present so the Unistyles Babel plugin rewrites the `View` above; a themed
+// style passed in through `style` would otherwise freeze at the theme it was
+// created under.
+const styles = StyleSheet.create(() => ({
+  item: {},
+}));

package/src/components/accordion/parts/AccordionTrigger.tsx

@@ -0,0 +1,88 @@
+import { Children, type ComponentRef, forwardRef, type ReactNode } from "react";
+import { type GestureResponderEvent, Pressable, type PressableProps } from "react-native";
+
+import { StyleSheet } from "react-native-unistyles";
+
+import { Text } from "../../text";
+import { useAccordionItem } from "../context";
+
+export interface AccordionTriggerProps extends Omit<PressableProps, "children" | "disabled"> {
+  /**
+   * The header row. Strings and numbers become the item's title; put an
+   * `Accordion.Indicator` last to show the open state.
+   */
+  children?: ReactNode;
+}
+
+function renderTitle(children: ReactNode): ReactNode {
+  return Children.map(children, (child) => {
+    if (typeof child === "string") {
+      return child.trim().length > 0 ? (
+        <Text variant="body-lg" weight="medium" style={styles.title}>
+          {child}
+        </Text>
+      ) : null;
+    }
+    if (typeof child === "number") {
+      return (
+        <Text variant="body-lg" weight="medium" style={styles.title}>
+          {child}
+        </Text>
+      );
+    }
+    return child;
+  });
+}
+
+export const AccordionTrigger = forwardRef<ComponentRef<typeof Pressable>, AccordionTriggerProps>(
+  function AccordionTrigger({ children, onPress, style, ...rest }, ref) {
+    const { isExpanded, isDisabled, toggle } = useAccordionItem();
+
+    const handlePress = (event: GestureResponderEvent) => {
+      onPress?.(event);
+      toggle();
+    };
+
+    return (
+      <Pressable
+        ref={ref}
+        accessibilityRole="button"
+        accessibilityState={{ expanded: isExpanded, disabled: isDisabled }}
+        disabled={isDisabled}
+        onPress={handlePress}
+        style={(state) => [
+          styles.trigger,
+          state.pressed && styles.pressed,
+          isDisabled && styles.disabled,
+          typeof style === "function" ? style(state) : style,
+        ]}
+        {...rest}
+      >
+        {renderTitle(children)}
+      </Pressable>
+    );
+  }
+);
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create((theme) => ({
+  trigger: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: theme.spacing["3"],
+    minHeight: 48,
+    paddingVertical: theme.spacing["4"],
+  },
+  pressed: {
+    opacity: theme.opacity.pressed,
+  },
+  disabled: {
+    opacity: theme.opacity.disabled,
+  },
+  // Takes the free space so an indicator after it sits at the row's end, and
+  // wraps a long title instead of pushing the indicator off.
+  title: {
+    flex: 1,
+  },
+}));

package/src/components/accordion/types.ts

@@ -0,0 +1,71 @@
+import type { ReactNode } from "react";
+import type { ViewProps } from "react-native";
+
+export type AccordionSelectionMode = "single" | "multiple";
+
+export type AccordionVariant = "plain" | "surface";
+
+interface AccordionBaseProps extends Omit<ViewProps, "children"> {
+  /**
+   * Visual treatment. `'plain'` draws the items straight onto whatever sits
+   * behind the accordion; `'surface'` puts them in a filled, rounded container.
+   * Defaults to `'plain'`.
+   */
+  variant?: AccordionVariant;
+  /** Draws a hairline rule between items. Defaults to `true`. */
+  divided?: boolean;
+  /** Disables every item. Defaults to `false`. */
+  isDisabled?: boolean;
+  /** `Accordion.Item` elements. */
+  children?: ReactNode;
+}
+
+export interface AccordionSingleProps extends AccordionBaseProps {
+  /**
+   * `'single'` keeps at most one item open; opening another closes the current
+   * one. Defaults to `'single'`.
+   */
+  selectionMode?: "single";
+  /**
+   * The open item, controlled. `null` means none is open — `undefined` leaves
+   * the accordion uncontrolled.
+   */
+  value?: string | null;
+  /** The item open on first render, uncontrolled. Defaults to `undefined`. */
+  defaultValue?: string;
+  /** Called with the newly open item, or `null` when the open item closes. */
+  onValueChange?: (value: string | null) => void;
+  /**
+   * Lets the open item close by pressing its trigger again. `false` keeps one
+   * item open at all times once any has been opened. Defaults to `true`.
+   */
+  isCollapsible?: boolean;
+}
+
+export interface AccordionMultipleProps extends AccordionBaseProps {
+  /** `'multiple'` lets any number of items be open at once. */
+  selectionMode: "multiple";
+  /** The open items, controlled. */
+  value?: string[];
+  /** The items open on first render, uncontrolled. Defaults to `[]`. */
+  defaultValue?: string[];
+  /** Called with every open item after one is toggled. */
+  onValueChange?: (value: string[]) => void;
+  /** Multiple mode can always close an item. */
+  isCollapsible?: never;
+}
+
+export type AccordionProps = AccordionSingleProps | AccordionMultipleProps;
+
+export interface AccordionItemState {
+  /** Whether the item's content is open. */
+  isExpanded: boolean;
+  /** Whether the item, or the whole accordion, is disabled. */
+  isDisabled: boolean;
+}
+
+export interface AccordionItemContextValue extends AccordionItemState {
+  value: string;
+  /** Opens or closes this item, following the accordion's selection rules. */
+  toggle: () => void;
+}

package/src/components/accordion/utils.ts

@@ -0,0 +1,12 @@
+import { Easing, ReduceMotion, type WithTimingConfig } from "react-native-reanimated";
+
+/**
+ * Shared by the content's height and the indicator's rotation so the chevron
+ * finishes turning as the panel finishes opening. Honours the system
+ * reduce-motion setting, which makes both jump straight to their end state.
+ */
+export const ACCORDION_TIMING: WithTimingConfig = {
+  duration: 250,
+  easing: Easing.bezier(0.25, 0.1, 0.25, 1),
+  reduceMotion: ReduceMotion.System,
+};