Interactive Components

/**
 * Themed button component with navigation integration
 * @param props - Button configuration, content, and navigation options
 * @returns React element representing a styled button
 */
// Basic button with onPress handler
function Button(props: ButtonBaseProps): React.ReactElement;

// Navigation button with screen/action routing
function Button<ParamList extends ReactNavigation.RootParamList>(
  props: ButtonLinkProps<ParamList>
): React.ReactElement;

interface ButtonBaseProps {
  /** Visual style variant */
  variant?: 'plain' | 'tinted' | 'filled';
  /** Custom button color (defaults to theme primary) */
  color?: string;
  /** Button text content (required) */
  children: string | string[];
  /** Callback when button is pressed */
  onPress?: () => void;
  /** Whether button is disabled */
  disabled?: boolean;
  /** Screen reader accessibility label */
  accessibilityLabel?: string;
  /** Test identifier for automated testing */
  testID?: string;
  /** Web anchor href for link behavior */
  href?: string;
  /** Custom button styling */
  style?: StyleProp<ViewStyle>;
  /** Android material ripple color */
  pressColor?: string;
  /** Press opacity when ripple not supported */
  pressOpacity?: number;
}

interface ButtonLinkProps<ParamList extends ReactNavigation.RootParamList> {
  /** Visual style variant */
  variant?: 'plain' | 'tinted' | 'filled';
  /** Custom button color (defaults to theme primary) */
  color?: string;
  /** Button text content (required) */
  children: string | string[];
  /** Target screen name for navigation */
  screen: keyof ParamList;
  /** Parameters to pass to target screen */
  params?: ParamList[keyof ParamList];
  /** Navigation action to dispatch */
  action?: NavigationAction;
  /** Web anchor href for link behavior */
  href?: string;
  /** Whether button is disabled */
  disabled?: boolean;
  /** Screen reader accessibility label */
  accessibilityLabel?: string;
  /** Test identifier for automated testing */
  testID?: string;
  /** Custom button styling */
  style?: StyleProp<ViewStyle>;
  /** Android material ripple color */
  pressColor?: string;
  /** Press opacity when ripple not supported */
  pressOpacity?: number;
}

import { Button } from "@react-navigation/elements";

// Basic button
<Button onPress={() => console.log('Pressed')}>
  Press me
</Button>

// Styled button variants
<Button variant="filled" color="#007AFF">
  Filled Button
</Button>

<Button variant="tinted" color="#34C759">
  Tinted Button  
</Button>

<Button variant="plain">
  Plain Button
</Button>

// Navigation button
<Button 
  screen="Profile" 
  params={{ userId: 123 }}
  variant="filled"
>
  Go to Profile
</Button>

// Disabled button
<Button 
  onPress={handleSubmit}
  disabled={!isFormValid}
  variant="filled"
>
  Submit Form
</Button>

// Custom styled button
<Button 
  onPress={handleAction}
  variant="tinted"
  style={{ marginTop: 20, paddingHorizontal: 30 }}
  accessibilityLabel="Perform important action"
>
  Custom Action
</Button>

/**
 * Cross-platform pressable component with platform-specific optimizations
 * @param props - Pressable configuration and content
 * @returns React element representing a platform-optimized pressable area
 */
const PlatformPressable: React.ForwardRefExoticComponent<{
  /** Web anchor href for link behavior */
  href?: string;
  /** Android material ripple color (Android >= 5.0) */
  pressColor?: string;
  /** Press opacity fallback when ripple not supported */
  pressOpacity?: number;
  /** Web hover effect configuration */
  hoverEffect?: HoverEffectProps;
  /** Custom pressable styling */
  style?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
  /** Press event callback */
  onPress?: (e: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent) => void;
  /** Pressable content (required) */
  children: React.ReactNode;
} & Omit<PressableProps, 'style' | 'onPress'>>;

interface HoverEffectProps {
  /** Hover background color */
  color?: string;
  /** Opacity on hover */
  hoverOpacity?: number;
  /** Opacity when active/pressed */
  activeOpacity?: number;
}

import { PlatformPressable } from "@react-navigation/elements";

// Basic pressable
<PlatformPressable onPress={() => console.log('Pressed')}>
  <View style={{ padding: 16 }}>
    <Text>Tap me</Text>
  </View>
</PlatformPressable>

// With custom press effects
<PlatformPressable 
  onPress={handlePress}
  pressColor="#e3f2fd"
  pressOpacity={0.7}
>
  <View style={styles.pressableContent}>
    <Icon name="star" />
    <Text>Star this item</Text>
  </View>
</PlatformPressable>

// Web hover effects
<PlatformPressable 
  onPress={handlePress}
  hoverEffect={{
    color: '#f0f0f0',
    hoverOpacity: 0.8,
    activeOpacity: 0.6
  }}
>
  <View style={styles.hoverableItem}>
    <Text>Hover over me (web only)</Text>
  </View>
</PlatformPressable>

// Link behavior
<PlatformPressable 
  href="https://reactnavigation.org"
  style={styles.linkButton}
>
  <Text style={styles.linkText}>Visit React Navigation</Text>
</PlatformPressable>

// With ref forwarding
function MyComponent() {
  const pressableRef = useRef(null);
  
  return (
    <PlatformPressable 
      ref={pressableRef}
      onPress={() => {
        // Access pressable methods if needed
        console.log('Pressed:', pressableRef.current);
      }}
    >
      <Text>Pressable with ref</Text>
    </PlatformPressable>
  );
}

// Complex interactive element
<PlatformPressable 
  onPress={() => setExpanded(!expanded)}
  accessibilityRole="button"
  accessibilityState={{ expanded }}
  style={[
    styles.expandableItem,
    expanded && styles.expandedItem
  ]}
>
  <View style={styles.itemHeader}>
    <Text style={styles.itemTitle}>Expandable Item</Text>
    <Icon name={expanded ? "chevron-up" : "chevron-down"} />
  </View>
  {expanded && (
    <View style={styles.itemContent}>
      <Text>Additional content when expanded</Text>
    </View>
  )}
</PlatformPressable>

// Navigate to screen
<Button screen="Details" params={{ id: 123 }}>
  View Details
</Button>

// Navigate with custom action
<Button 
  action={NavigationActions.reset({
    index: 0,
    routes: [{ name: 'Home' }]
  })}
>
  Reset to Home
</Button>

// External link
<Button href="https://example.com">
  Open External Link
</Button>

// Accessibility best practices
<Button 
  onPress={handleSubmit}
  disabled={!isValid}
  accessibilityLabel="Submit registration form"
  accessibilityHint="Double tap to submit your registration"
>
  Submit
</Button>

<PlatformPressable 
  onPress={toggleFavorite}
  accessibilityRole="button"
  accessibilityState={{ selected: isFavorite }}
  accessibilityLabel={isFavorite ? "Remove from favorites" : "Add to favorites"}
>
  <Icon name={isFavorite ? "heart-filled" : "heart-outline"} />
</PlatformPressable>