Link Components

/**
 * Component to render link to another screen using a path.
 * Uses an anchor tag on the web.
 */
function Link<ParamList extends ReactNavigation.RootParamList>(
  props: LinkProps<ParamList> & Omit<TextProps, 'disabled'> & {
    /** Target attribute for web links (e.g., '_blank') */
    target?: string;
    /** Custom press handler called before navigation */
    onPress?: (
      e: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
    ) => void;
    /** Whether the link is disabled */
    disabled?: boolean | null;
    /** Content to render inside the link */
    children: React.ReactNode;
  }
): React.ReactElement;

type LinkProps<
  ParamList extends ReactNavigation.RootParamList,
  RouteName extends keyof ParamList = keyof ParamList
> =
  | ({
      /** Optional absolute path to use for href (e.g., '/feeds/hot') */
      href?: string;
      /** Optional action to use for in-page navigation */
      action?: NavigationAction;
    } & (RouteName extends unknown
      ? undefined extends ParamList[RouteName]
        ? { screen: RouteName; params?: ParamList[RouteName] }
        : { screen: RouteName; params: ParamList[RouteName] }
      : never))
  | {
      /** Optional absolute path to use for href */
      href?: string;
      /** Navigation action to dispatch */
      action: NavigationAction;
      screen?: undefined;
      params?: undefined;
    };

import { Link } from '@react-navigation/native';
import { StyleSheet } from 'react-native';

// Navigate to a screen by name
function HomeScreen() {
  return (
    <Link screen="Profile" params={{ userId: '123' }}>
      View Profile
    </Link>
  );
}

// Navigate using href path
function NavMenu() {
  return (
    <Link href="/profile/123" style={styles.menuLink}>
      User Profile
    </Link>
  );
}

// With custom styling
function StyledLink() {
  return (
    <Link 
      screen="Settings"
      style={[styles.link, styles.primaryLink]}
      disabled={!userLoggedIn}
    >
      Settings
    </Link>
  );
}

// With custom press handler
function CustomLink() {
  const handlePress = (e: any) => {
    // Custom logic before navigation
    console.log('Link pressed');
    // Don't prevent default - navigation will still occur
  };

  return (
    <Link 
      screen="Details" 
      params={{ id: itemId }}
      onPress={handlePress}
    >
      View Details
    </Link>
  );
}

// Web-specific target attribute
function ExternalStyleLink() {
  return (
    <Link 
      href="/external-page"
      target="_blank"
      style={styles.externalLink}
    >
      Open in New Tab
    </Link>
  );
}

const styles = StyleSheet.create({
  link: {
    color: '#007AFF',
    textDecorationLine: 'underline',
  },
  primaryLink: {
    fontWeight: 'bold',
  },
  menuLink: {
    fontSize: 16,
    padding: 12,
  },
  externalLink: {
    color: '#34C759',
  },
});

/**
 * Hook to get props for an anchor tag so it can work with in page navigation.
 * Useful for creating custom link components.
 */
function useLinkProps<ParamList extends ReactNavigation.RootParamList>(
  props: LinkProps<ParamList>
): {
  /** Generated href for web links */
  href?: string;
  /** Accessibility role */
  role: 'link';
  /** Press handler that performs navigation */
  onPress: (
    e?: React.MouseEvent<HTMLAnchorElement, MouseEvent> | GestureResponderEvent
  ) => void;
};

import { useLinkProps } from '@react-navigation/native';
import { Pressable, Text } from 'react-native';

// Custom link component using useLinkProps
function CustomLinkButton({ screen, params, children, ...props }) {
  const { href, onPress, ...linkProps } = useLinkProps({ screen, params });

  return (
    <Pressable 
      {...linkProps}
      {...props}
      onPress={onPress}
      style={({ pressed }) => [
        styles.linkButton,
        pressed && styles.pressed,
      ]}
    >
      <Text style={styles.linkText}>{children}</Text>
    </Pressable>
  );
}

// Custom touchable link
function TouchableLink({ screen, params, style, children }) {
  const { onPress } = useLinkProps({ screen, params });

  return (
    <TouchableOpacity onPress={onPress} style={style}>
      {children}
    </TouchableOpacity>
  );
}

// Link with icon
function IconLink({ screen, params, icon, children }) {
  const { onPress } = useLinkProps({ screen, params });

  return (
    <Pressable onPress={onPress} style={styles.iconLink}>
      <Image source={icon} style={styles.icon} />
      <Text style={styles.linkText}>{children}</Text>
    </Pressable>
  );
}

type LinkProps<
  ParamList extends ReactNavigation.RootParamList,
  RouteName extends keyof ParamList = keyof ParamList
> =
  // Screen-based navigation with optional href and action
  | ({
      href?: string;
      action?: NavigationAction;
    } & (RouteName extends unknown
      ? undefined extends ParamList[RouteName]
        ? { screen: RouteName; params?: ParamList[RouteName] }
        : { screen: RouteName; params: ParamList[RouteName] }
      : never))
  // Action-based navigation
  | {
      href?: string;
      action: NavigationAction;
      screen?: undefined;
      params?: undefined;
    };

// Example param list type for type safety
type RootParamList = {
  Home: undefined;
  Profile: { userId: string };
  Settings: undefined;
  Article: { id: number; slug?: string };
};

// Type-safe link usage
function TypeSafeLinks() {
  return (
    <>
      {/* ✅ Valid - Profile requires userId param */}
      <Link screen="Profile" params={{ userId: '123' }}>
        Profile
      </Link>
      
      {/* ✅ Valid - Home has no params */}
      <Link screen="Home">
        Home
      </Link>
      
      {/* ✅ Valid - Article with required id */}
      <Link screen="Article" params={{ id: 1, slug: 'my-article' }}>
        Article
      </Link>
      
      {/* ❌ TypeScript error - missing required userId */}
      <Link screen="Profile">
        Profile
      </Link>
      
      {/* ❌ TypeScript error - invalid param */}
      <Link screen="Home" params={{ invalid: true }}>
        Home
      </Link>
    </>
  );
}

// Platform-specific rendering and behavior
interface PlatformBehavior {
  /** Web: Renders as <a> tag with proper href */
  web: {
    element: 'anchor';
    attributes: ['href', 'target', 'onClick'];
    behavior: 'standard web link semantics';
  };
  
  /** Native: Renders as Text component with onPress */
  native: {
    element: 'Text';
    attributes: ['onPress'];
    behavior: 'touch-based navigation';
  };
}

// The Link component automatically handles platform differences
function PlatformAwareLink() {
  return (
    <Link screen="Profile" params={{ userId: '123' }}>
      {/* On web: <a href="/profile/123">View Profile</a> */}
      {/* On native: <Text onPress={...}>View Profile</Text> */}
      View Profile
    </Link>
  );
}

// Manual platform handling if needed
import { Platform } from 'react-native';

function ManualPlatformLink() {
  const linkProps = useLinkProps({ screen: 'Profile', params: { userId: '123' } });
  
  if (Platform.OS === 'web') {
    return (
      <a {...linkProps} className="custom-link">
        View Profile
      </a>
    );
  }
  
  return (
    <Text {...linkProps} style={styles.nativeLink}>
      View Profile
    </Text>
  );
}

// Accessibility attributes are automatically applied
interface AccessibilitySupport {
  role: 'link';
  accessible: true;
  accessibilityRole: 'link';
}

// Links automatically get proper accessibility attributes
function AccessibleLink() {
  return (
    <Link 
      screen="Help" 
      accessibilityLabel="Open help documentation"
      accessibilityHint="Navigates to the help screen"
    >
      Help
    </Link>
  );
}

// Custom accessibility for complex links
function ComplexAccessibleLink() {
  return (
    <Link 
      screen="Product" 
      params={{ id: product.id }}
      accessibilityLabel={`View ${product.name} details`}
      accessibilityRole="link"
      accessible={true}
    >
      <Text style={styles.productName}>{product.name}</Text>
      <Text style={styles.productPrice}>${product.price}</Text>
    </Link>
  );
}