Core Application Components

/**
 * Root provider component that wraps the entire Polaris application
 * @param theme - Theme name configuration ('light', 'dark', etc.)
 * @param i18n - Internationalization configuration (REQUIRED)
 * @param linkComponent - Custom component for all links
 * @param features - Feature flags and experimental features
 * @param children - Inner content of the application
 * @returns JSX element wrapping children with Polaris context
 */
function AppProvider(props: AppProviderProps): JSX.Element;

interface AppProviderProps {
  /** Theme name selection */
  theme?: ThemeName;
  /** A locale object or array of locale objects that overrides default translations. If specifying an array then your primary language dictionary should come first, followed by your fallback language dictionaries */
  i18n: ConstructorParameters<typeof I18n>[0];
  /** A custom component to use for all links used by Polaris components */
  linkComponent?: LinkLikeComponent;
  /** For toggling features */
  features?: FeaturesConfig;
  /** Inner content of the application */
  children?: React.ReactNode;
}

type ThemeName = 'light' | 'dark' | 'light-mobile' | 'light-high-contrast' | string;

type LinkLikeComponent = React.ComponentType<{
  children?: React.ReactNode;
  url: string;
  external?: boolean;
  [key: string]: any;
}>;

import React from 'react';
import { AppProvider, Page } from '@shopify/polaris';

function App() {
  // i18n configuration - REQUIRED parameter
  const i18n = {
    locale: 'en',
    translate: (id: string, options?: any) => id,
  };

  return (
    <AppProvider theme="light" i18n={i18n}>
      <Page title="My Application">
        {/* Your app content */}
      </Page>
    </AppProvider>
  );
}

/**
 * Main application frame providing structural layout
 * @param children - Content to display in the main area
 * @param navigation - Navigation component or configuration
 * @param topBar - Top bar component or configuration
 * @param logo - Logo configuration for the frame
 * @returns JSX element with frame structure
 */
function Frame(props: FrameProps): JSX.Element;

interface FrameProps {
  /** Content to display in the main content area */
  children: React.ReactNode;
  /** Navigation component for the sidebar */
  navigation?: React.ReactNode;
  /** Top bar component for the header */
  topBar?: React.ReactNode;
  /** Logo configuration */
  logo?: LogoProps;
  /** Skip to content link configuration */
  skipToContentTarget?: React.RefObject<HTMLElement>;
  /** Callback when navigation is dismissed on mobile */
  onNavigationDismiss?: () => void;
}

interface LogoProps {
  /** Logo image source */
  source: string;
  /** Logo width */
  width?: number;
  /** Logo accessibility label */
  accessibilityLabel?: string;
  /** Logo click handler */
  onClick?: () => void;
}

/**
 * Page container with headers, breadcrumbs, and actions
 * @param title - Page title text
 * @param subtitle - Optional subtitle text
 * @param children - Page content
 * @param breadcrumbs - Breadcrumb navigation items
 * @param primaryAction - Primary page action button
 * @param secondaryActions - Secondary action buttons
 * @returns JSX element with page structure
 */
function Page(props: PageProps): JSX.Element;

interface PageProps extends HeaderProps {
  /** The contents of the page */
  children?: React.ReactNode;
  /** Remove the normal max-width on the page */
  fullWidth?: boolean;
  /** Decreases the maximum layout width. Intended for single-column layouts */
  narrowWidth?: boolean;
}

interface HeaderProps extends TitleProps {
  /** Visually hide the title */
  titleHidden?: boolean;
  /** A label to use for the page when the page is ready, used by screen readers. Will override the title prop if present */
  pageReadyAccessibilityLabel?: string;
  /** Enables filtering action list items */
  filterActions?: boolean;
  /** Primary page-level action */
  primaryAction?: PrimaryAction | React.ReactNode;
  /** Page-level pagination */
  pagination?: PaginationProps;
  /** A back action link */
  backAction?: BreadcrumbsProps['backAction'];
  /** Collection of secondary page-level actions */
  secondaryActions?: MenuActionDescriptor[] | React.ReactNode;
  /** Collection of page-level groups of secondary actions */
  actionGroups?: MenuGroupDescriptor[];
  /** Additional meta data */
  additionalMetadata?: React.ReactNode | string;
  /** Callback that returns true when secondary actions are rolled up into action groups, and false when not */
  onActionRollup?(hasRolledUp: boolean): void;
}

interface TitleProps {
  /** Page title, in large type */
  title?: string;
  /** Page subtitle, in regular type */
  subtitle?: string;
  /** Important status information shown immediately after the title */
  titleMetadata?: React.ReactNode;
  /** Removes spacing between title and subtitle */
  compactTitle?: boolean;
}

interface PrimaryAction extends DestructableAction, DisableableAction, LoadableAction, IconableAction, TooltipAction {
  /** Provides extra visual weight and identifies the primary action in a set of buttons */
  primary?: boolean;
}

import React from 'react';
import { Page, Card, Button } from '@shopify/polaris';

function ProductPage() {
  const breadcrumbs = [
    { content: 'Products', url: '/products' }
  ];

  const primaryAction = {
    content: 'Save product',
    onAction: () => console.log('Product saved'),
  };

  const secondaryActions = [
    {
      content: 'Duplicate',
      onAction: () => console.log('Product duplicated'),
    },
    {
      content: 'Delete',
      destructive: true,
      onAction: () => console.log('Product deleted'),
    },
  ];

  return (
    <Page
      title="New Product"
      subtitle="Add a new product to your store"
      breadcrumbs={breadcrumbs}
      primaryAction={primaryAction}
      secondaryActions={secondaryActions}
    >
      <Card>
        {/* Page content */}
      </Card>
    </Page>
  );
}

/**
 * Responsive layout component for organizing content
 * @param children - Layout sections
 * @param sectioned - Whether content is automatically sectioned
 * @returns JSX element with layout structure
 */
function Layout(props: LayoutProps): JSX.Element;

interface LayoutProps {
  /** Layout sections or content */
  children: React.ReactNode;
  /** Automatically wrap content in sections */
  sectioned?: boolean;
}

/**
 * Individual layout section component
 * @param children - Section content
 * @param secondary - Whether section is secondary (smaller width)
 * @param oneHalf - Whether section takes half width
 * @param oneThird - Whether section takes one-third width
 * @returns JSX element with section structure
 */
function LayoutSection(props: LayoutSectionProps): JSX.Element;

interface LayoutSectionProps {
  /** Section content */
  children?: React.ReactNode;
  /** Secondary section with reduced width */
  secondary?: boolean;
  /** Section takes half width */
  oneHalf?: boolean;
  /** Section takes one-third width */
  oneThird?: boolean;
  /** Full width section */
  fullWidth?: boolean;
}

import React from 'react';
import { Layout, Card, Text } from '@shopify/polaris';

function MyPage() {
  return (
    <Layout>
      <Layout.Section>
        <Card>
          <Text variant="bodyMd">Main content area</Text>
        </Card>
      </Layout.Section>
      <Layout.Section secondary>
        <Card>
          <Text variant="bodyMd">Secondary content area</Text>
        </Card>
      </Layout.Section>
    </Layout>
  );
}

/** Default duration for toast notifications in milliseconds */
const DEFAULT_TOAST_DURATION: number = 5000;

/** Default duration for toast notifications with actions in milliseconds */
const DEFAULT_TOAST_DURATION_WITH_ACTION: number = 10000;

interface Action {
  /** Action content/label */
  content?: string;
  /** Accessibility label for screen readers */
  accessibilityLabel?: string;
  /** URL for link actions */
  url?: string;
  /** External link indicator */
  external?: boolean;
  /** Action callback function */
  onAction?(): void;
  /** Mouse enter handler */
  onMouseEnter?(): void;
  /** Touch start handler */
  onTouchStart?(): void;
}

interface TranslateOptions {
  /** Variables to interpolate into translation */
  [key: string]: string | number;
}

interface NumberFormatOptions {
  /** Currency code for currency formatting */
  currency?: string;
  /** Number formatting style */
  style?: 'decimal' | 'currency' | 'percent';
}

interface DateFormatOptions {
  /** Date formatting style */
  dateStyle?: 'full' | 'long' | 'medium' | 'short';
  /** Time formatting style */
  timeStyle?: 'full' | 'long' | 'medium' | 'short';
}

/**
 * Theme configuration provider for custom theming
 * @param theme - Theme configuration object
 * @param children - Components that will receive theme context
 * @returns JSX element with theme context
 */
function ThemeProvider(props: ThemeProviderProps): JSX.Element;

interface ThemeProviderProps {
  /** Custom theme configuration */
  theme?: Theme;
  /** The content to wrap with theme context */
  children?: React.ReactNode;
}

/**
 * Test provider for Polaris components in testing environments
 * @param children - Components to test
 * @param options - Test configuration options
 * @returns JSX element with test context
 */
function PolarisTestProvider(props: PolarisTestProviderProps): JSX.Element;

interface PolarisTestProviderProps {
  /** The content to wrap with test context */
  children?: React.ReactNode;
  /** Test configuration options */
  options?: WithPolarisTestProviderOptions;
}

interface WithPolarisTestProviderOptions {
  /** Mock features configuration */
  features?: Partial<FeaturesConfig>;
  /** Mock theme configuration */
  theme?: Partial<Theme>;
  /** Mock i18n configuration */
  i18n?: Partial<I18nContext>;
  /** Media query mocks */
  mediaQuery?: {
    isNavigationCollapsed?: boolean;
  };
}

/**
 * Account connection component for external service integration
 * @param accountName - Name of the connected account
 * @param connected - Whether account is connected
 * @param action - Connection/disconnection action
 * @returns JSX element with account connection interface
 */
function AccountConnection(props: AccountConnectionProps): JSX.Element;

interface AccountConnectionProps {
  /** The name of the service */
  accountName?: string;
  /** The name of the connected account */
  connected: boolean;
  /** The title of the connection */
  title: React.ReactNode;
  /** Additional details about the connection */
  details?: React.ReactNode;
  /** Terms of service for the connection */
  termsOfService?: React.ReactNode;
  /** The action to connect or disconnect */
  action?: ComplexAction;
  /** URL to avatar image */
  avatarUrl?: string;
}