Media & Icon Components

/**
 * Icon display component with color and size options
 * @param source - Icon source (component, placeholder, or string)
 * @param tone - Icon color tone
 * @param accessibilityLabel - Screen reader label
 * @returns JSX element with icon
 */
function Icon(props: IconProps): JSX.Element;

interface IconProps {
  /** Icon source */
  source: IconSource;
  /** Icon color tone */
  tone?: 'base' | 'disabled' | 'inherit' | 'emphasized' | 'caution' | 'warning' | 'critical' | 'success' | 'info' | 'magic';
  /** Accessibility label for screen readers */
  accessibilityLabel?: string;
}

/** Icon source type supporting multiple formats */
type IconSource = React.ComponentType<any> | 'placeholder' | string;

import React from 'react';
import { Icon, InlineStack, Text } from '@shopify/polaris';
import { 
  CheckIcon, 
  AlertIcon, 
  InfoIcon, 
  XIcon 
} from '@shopify/polaris-icons';

function IconExamples() {
  return (
    <InlineStack gap="400" align="center">
      <InlineStack gap="200" align="center">
        <Icon source={CheckIcon} tone="success" />
        <Text>Success</Text>
      </InlineStack>
      
      <InlineStack gap="200" align="center">
        <Icon source={AlertIcon} tone="warning" />
        <Text>Warning</Text>
      </InlineStack>
      
      <InlineStack gap="200" align="center">
        <Icon source={InfoIcon} tone="info" />
        <Text>Information</Text>
      </InlineStack>
      
      <InlineStack gap="200" align="center">
        <Icon source={XIcon} tone="critical" />
        <Text>Error</Text>
      </InlineStack>
    </InlineStack>
  );
}

/**
 * User avatar with image, initials, and sizing options
 * @param size - Avatar size
 * @param name - User name for initials fallback
 * @param source - Avatar image source
 * @param customer - Customer avatar styling
 * @returns JSX element with avatar
 */
function Avatar(props: AvatarProps): JSX.Element;

interface AvatarProps {
  /** Avatar size */
  size?: 'extraSmall' | 'small' | 'medium' | 'large';
  /** Customer avatar indicator */
  customer?: boolean;
  /** User name for initials */
  name?: string;
  /** Avatar image source URL */
  source?: string;
  /** Accessibility label */
  accessibilityLabel?: string;
  /** Initial letters override */
  initials?: string;
  /** Shape variant */
  shape?: 'round' | 'square';
}

import React from 'react';
import { Avatar, InlineStack, Text, BlockStack } from '@shopify/polaris';

function AvatarExamples() {
  return (
    <BlockStack gap="400">
      <InlineStack gap="400" align="center">
        <Avatar
          customer
          name="Farrah"
          source="https://avatars.githubusercontent.com/u/12345"
        />
        <Text>Customer avatar with image</Text>
      </InlineStack>
      
      <InlineStack gap="400" align="center">
        <Avatar name="John Smith" size="large" />
        <Text>Avatar with initials</Text>
      </InlineStack>
      
      <InlineStack gap="400" align="center">
        <Avatar size="small" />
        <Text>Default avatar</Text>
      </InlineStack>
    </BlockStack>
  );
}

/**
 * Responsive image with loading states and accessibility
 * @param source - Image source URL
 * @param alt - Alternative text for accessibility
 * @returns JSX element with responsive image
 */
function Image(props: ImageProps): JSX.Element;

interface ImageProps {
  /** Image source URL */
  source: string;
  /** Alternative text */
  alt: string;
  /** Image width */
  width?: number;
  /** Image height */
  height?: number;
  /** Cross-origin attribute */
  crossOrigin?: 'anonymous' | 'use-credentials';
  /** Loading behavior */
  loading?: 'eager' | 'lazy';
  /** Decode behavior */
  decoding?: 'async' | 'sync' | 'auto';
  /** Image loading error handler */
  onError?: () => void;
  /** Image load handler */
  onLoad?: () => void;
  /** Additional CSS classes */
  className?: string;
  /** Draggable image */
  draggable?: boolean;
  /** Role override */
  role?: string;
  /** Tab index */
  tabIndex?: number;
}

/**
 * Small preview image for media thumbnails
 * @param source - Thumbnail image source
 * @param alt - Alternative text
 * @param size - Thumbnail size
 * @returns JSX element with thumbnail image
 */
function Thumbnail(props: ThumbnailProps): JSX.Element;

interface ThumbnailProps {
  /** Thumbnail image source */
  source: string;
  /** Alternative text */
  alt: string;
  /** Thumbnail size */
  size?: 'extraSmall' | 'small' | 'medium' | 'large';
  /** Transparent background */
  transparent?: boolean;
}

/**
 * Video preview thumbnail with play indicator
 * @param videoLength - Video duration display
 * @param thumbnailUrl - Video thumbnail image
 * @param onClick - Thumbnail click handler
 * @returns JSX element with video thumbnail
 */
function VideoThumbnail(props: VideoThumbnailProps): JSX.Element;

interface VideoThumbnailProps {
  /** Video duration in seconds */
  videoLength?: number;
  /** Video thumbnail image URL */
  thumbnailUrl: string;
  /** Video title for accessibility */
  accessibilityLabel?: string;
  /** Play button click handler */
  onClick?: () => void;
  /** Show video duration */
  showVideoLength?: boolean;
  /** Video progress percentage */
  videoProgress?: number;
}

/**
 * Text content component with typography controls
 * @param children - Text content
 * @param variant - Typography variant
 * @param as - HTML element type
 * @returns JSX element with styled text
 */
function Text(props: TextProps): JSX.Element;

interface TextProps {
  /** Text content */
  children?: React.ReactNode;
  /** Typography variant */
  variant?: 
    | 'displayLarge' | 'displayMedium' | 'displaySmall' 
    | 'headingXl' | 'headingLg' | 'headingMd' | 'headingSm' | 'headingXs'
    | 'bodyLg' | 'bodyMd' | 'bodySm' | 'bodyXs'
    | 'captionLg' | 'captionMd' | 'captionSm';
  /** HTML element to render */
  as?: 'dt' | 'dd' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'strong' | 'em' | 'legend';
  /** Text alignment */
  alignment?: 'start' | 'center' | 'end' | 'justify';
  /** Font weight */
  fontWeight?: 'regular' | 'medium' | 'semibold' | 'bold';
  /** Text color */
  tone?: 'default' | 'subdued' | 'success' | 'critical' | 'warning' | 'highlight' | 'info';
  /** Text decoration */
  textDecorationLine?: 'line-through';
  /** Truncate text */
  truncate?: boolean;
  /** Breakword behavior */
  breakWord?: boolean;
  /** Numeric character variant */
  numeric?: boolean;
  /** Visuall hidden text */
  visuallyHidden?: boolean;
  /** Text ID */
  id?: string;
}

/**
 * Text container for spacing and typography hierarchy
 * @param children - Text content
 * @param spacing - Spacing between text elements
 * @returns JSX element with text container
 */
function TextContainer(props: TextContainerProps): JSX.Element;

interface TextContainerProps {
  /** Text content */
  children?: React.ReactNode;
  /** Spacing between elements */
  spacing?: 'tight' | 'loose';
}

/**
 * Inline code formatting component
 * @param children - Code content
 * @returns JSX element with inline code styling
 */
function InlineCode(props: InlineCodeProps): JSX.Element;

interface InlineCodeProps {
  /** Code content */
  children?: React.ReactNode;
}

/**
 * Text truncation component with expand/collapse
 * @param children - Content to truncate
 * @param width - Truncation width
 * @returns JSX element with truncation controls
 */
function Truncate(props: TruncateProps): JSX.Element;

interface TruncateProps {
  /** Content to truncate */
  children?: React.ReactNode;
  /** Truncation width */
  width?: string;
}

/**
 * Keyboard key display component
 * @param children - Key content
 * @param size - Key size
 * @returns JSX element styled as keyboard key
 */
function KeyboardKey(props: KeyboardKeyProps): JSX.Element;

interface KeyboardKeyProps {
  /** Key content */
  children?: React.ReactNode;
  /** Key size */
  size?: 'small' | 'medium' | 'large';
}

import React from 'react';
import { 
  Text, 
  TextContainer, 
  InlineCode, 
  KeyboardKey, 
  BlockStack,
  Image,
  Thumbnail
} from '@shopify/polaris';

function MediaTextExample() {
  return (
    <BlockStack gap="400">
      {/* Text examples */}
      <TextContainer>
        <Text variant="headingLg" as="h1">
          Product Documentation
        </Text>
        <Text variant="bodyMd" tone="subdued">
          Learn how to configure your product settings using the{' '}
          <InlineCode>product.config.js</InlineCode> file.
        </Text>
        <Text variant="bodySm">
          Press <KeyboardKey>⌘</KeyboardKey> + <KeyboardKey>S</KeyboardKey> to save.
        </Text>
      </TextContainer>

      {/* Image and thumbnail examples */}
      <BlockStack gap="200">
        <Image
          source="https://example.com/product-hero.jpg"
          alt="Product hero image"
          width={400}
          height={200}
        />
        
        <Thumbnail
          source="https://example.com/product-thumb.jpg"
          alt="Product thumbnail"
          size="large"
        />
      </BlockStack>
    </BlockStack>
  );
}

/**
 * Status and labeling component for brief information
 * @param children - Badge content
 * @param tone - Badge color theme
 * @param progress - Badge progress state
 * @returns JSX element with badge
 */
function Badge(props: BadgeProps): JSX.Element;

interface BadgeProps {
  /** Badge content */
  children?: React.ReactNode;
  /** Badge color tone */
  tone?: 'default' | 'success' | 'info' | 'attention' | 'warning' | 'critical';
  /** Badge progress state */
  progress?: 'incomplete' | 'partiallyComplete' | 'complete';
  /** Badge size */
  size?: 'small' | 'medium';
  /** Status value for tone */
  status?: ToneValue;
}

/** Tone value enum for badge status */
enum ToneValue {
  Default = 'default',
  Success = 'success',
  Info = 'info',
  Attention = 'attention', 
  Warning = 'warning',
  Critical = 'critical',
}

/** Progress value enum for badge progress */
enum ProgressValue {
  Incomplete = 'incomplete',
  PartiallyComplete = 'partiallyComplete',
  Complete = 'complete',
}

/**
 * Page skeleton for loading states
 * @param title - Show title skeleton
 * @param breadcrumbs - Show breadcrumbs skeleton
 * @param primaryAction - Show primary action skeleton
 * @returns JSX element with page skeleton
 */
function SkeletonPage(props: SkeletonPageProps): JSX.Element;

interface SkeletonPageProps {
  /** Show title skeleton */
  title?: boolean;
  /** Show breadcrumbs skeleton */
  breadcrumbs?: boolean;
  /** Show primary action skeleton */
  primaryAction?: boolean;
  /** Show secondary actions skeleton */
  secondaryActions?: number;
  /** Page content */
  children?: React.ReactNode;
}

/**
 * Body text skeleton for loading content
 * @param lines - Number of text lines
 * @returns JSX element with text skeleton
 */
function SkeletonBodyText(props: SkeletonBodyTextProps): JSX.Element;

interface SkeletonBodyTextProps {
  /** Number of skeleton lines */
  lines?: number;
}

/**
 * Display text skeleton for headings
 * @param size - Display text size
 * @returns JSX element with display text skeleton
 */
function SkeletonDisplayText(props: SkeletonDisplayTextProps): JSX.Element;

interface SkeletonDisplayTextProps {
  /** Display text size */
  size?: 'small' | 'medium' | 'large' | 'extraLarge';
}

/**
 * Thumbnail skeleton for media placeholders
 * @param size - Thumbnail size
 * @returns JSX element with thumbnail skeleton
 */
function SkeletonThumbnail(props: SkeletonThumbnailProps): JSX.Element;

interface SkeletonThumbnailProps {
  /** Thumbnail size */
  size?: 'small' | 'medium' | 'large';
}

/**
 * Tabs skeleton for navigation placeholders
 * @param count - Number of tab skeletons
 * @returns JSX element with tabs skeleton
 */
function SkeletonTabs(props: SkeletonTabsProps): JSX.Element;

interface SkeletonTabsProps {
  /** Number of tab skeletons */
  count?: number;
}

/**
 * Legacy media card for displaying media content
 * @param title - Card title
 * @param primaryAction - Main action for the card
 * @param description - Media description
 * @returns JSX element with media card display
 */
function MediaCard(props: { 
  title: string; 
  primaryAction: ComplexAction; 
  description: string; 
  popoverActions?: ComplexAction[]; 
  portrait?: boolean; 
  size?: 'small' | 'medium';
}): JSX.Element;

/**
 * Visual indicator for status and notifications
 * @param pulse - Whether to show pulsing animation
 * @returns JSX element with indicator
 */
function Indicator(props: IndicatorProps): JSX.Element;

interface IndicatorProps {
  /** Whether to pulse the indicator */
  pulse?: boolean;
}

/**
 * Removable tag for labels and categories
 * @param children - Tag content
 * @param disabled - Whether tag is disabled
 * @param onRemove - Remove handler
 * @returns JSX element with tag display
 */
function Tag(props: TagProps): JSX.Element;

interface TagProps {
  /** Content to display in the tag */
  children?: React.ReactNode;
  /** Whether the tag is disabled */
  disabled?: boolean;
  /** Callback when the tag is removed */
  onRemove?(): void;
  /** Additional action for the tag */
  onClick?(): void;
  /** URL for the tag */
  url?: string;
  /** Accessibility label for the tag */
  accessibilityLabel?: string;
}

/** Heading tag name type for text elements */
type HeadingTagName = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';

/** Icon source supporting various formats */
type IconSource = React.ComponentType<any> | 'placeholder' | string;

/** Image loading states */
type ImageLoadingState = 'loading' | 'loaded' | 'error';

/** Media query configuration for responsive behavior */
interface MediaQueryConfig {
  /** Small screen breakpoint */
  small: string;
  /** Medium screen breakpoint */
  medium: string;
  /** Large screen breakpoint */
  large: string;
}