Utilities & Hooks

/**
 * Access Frame context and utilities for frame-related functionality
 * @returns Frame context object with utilities and state
 */
function useFrame(): FrameContext;

interface FrameContext {
  /** Show toast notification */
  showToast(toast: ToastProps): void;
  /** Hide toast notification */
  hideToast(id: string): void;
  /** Set context bar content */
  setContextualSaveBar(contextualSaveBar: React.ReactNode): void;
  /** Remove context bar */
  removeContextualSaveBar(): void;
  /** Start loading state */
  startLoading(): void;
  /** Stop loading state */
  stopLoading(): void;
  /** Navigation state */
  navigationOpen: boolean;
  /** Toggle navigation */
  toggleNavigation(): void;
}

/**
 * Access current theme configuration and design tokens
 * @returns Current theme object with tokens and configuration
 */
function useTheme(): Theme;

interface Theme {
  /** Color tokens */
  colors: ThemeColors;
  /** Spacing tokens */
  space: ThemeSpace;
  /** Typography tokens */
  font: ThemeFont;
  /** Border radius tokens */
  borderRadius: ThemeBorderRadius;
  /** Shadow tokens */
  shadows: ThemeShadows;
  /** Z-index tokens */
  zIndex: ThemeZIndex;
}

/**
 * Responsive breakpoint matching hook with SSR support
 * @param options - Configuration options for defaults
 * @returns Object with boolean values for each breakpoint
 */
function useBreakpoints(options?: UseBreakpointsOptions): BreakpointsMatches;

interface UseBreakpointsOptions {
  /** Default values for SSR */
  defaults?: Partial<BreakpointsMatches>;
}

interface BreakpointsMatches {
  /** Extra small screen and up */
  xsUp: boolean;
  /** Small screen and up */
  smUp: boolean;
  /** Medium screen and up */
  mdUp: boolean;
  /** Large screen and up */
  lgUp: boolean;
  /** Extra large screen and up */
  xlUp: boolean;
  /** Extra small screen only */
  xsOnly: boolean;
  /** Small screen only */
  smOnly: boolean;
  /** Medium screen only */
  mdOnly: boolean;
  /** Large screen only */
  lgOnly: boolean;
  /** Extra small screen and down */
  xsDown: boolean;
  /** Small screen and down */
  smDown: boolean;
  /** Medium screen and down */
  mdDown: boolean;
  /** Large screen and down */
  lgDown: boolean;
}

/**
 * Media query matching hook for custom queries
 * @param query - CSS media query string
 * @returns Boolean indicating if query matches
 */
function useMediaQuery(query: string): boolean;

/**
 * Resource selection state management for IndexTable and ResourceList
 * @param resources - Array of resources to manage
 * @param options - Configuration options
 * @returns Resource state management object
 */
function useIndexResourceState<T>(
  resources: T[],
  options?: IndexResourceStateOptions<T>
): IndexResourceState<T>;

interface IndexResourceStateOptions<T> {
  /** Function to extract unique ID from resource */
  resourceIDResolver?: (resource: T) => string;
  /** Initial resource filter */
  resourceFilter?: (resource: T) => boolean;
}

interface IndexResourceState<T> {
  /** Currently selected resource IDs */
  selectedResources: string[];
  /** All resources selected state */
  allResourcesSelected: boolean;
  /** Handle selection change */
  handleSelectionChange: (
    selectionType: SelectionType,
    isSelecting: boolean,
    selection?: string | string[]
  ) => void;
  /** Clear all selections */
  clearSelection: () => void;
  /** Remove specific resources from selection */
  removeSelectedResources: (removeResources: string[]) => void;
}

enum SelectionType {
  All = 'all',
  Page = 'page', 
  Range = 'range',
  Single = 'single',
}

/**
 * Hook for managing IndexTable row hover state
 * @returns Object with hover state and handlers
 */
function useIndexTableRowHovered(): {
  hoveredRowIndex: number | undefined;
  onRowHover: (index: number) => void;
  onRowOut: () => void;
};

/**
 * Hook for managing IndexTable row selection state
 * @returns Object with selection state and handlers
 */
function useIndexTableRowSelected(): {
  selectedRowIndex: number | undefined;
  onRowSelect: (index: number) => void;
  onRowDeselect: () => void;
};

/**
 * Hook for managing IndexTable container scroll behavior
 * @returns Object with scroll state and utilities
 */
function useIndexTableContainerScroll(): {
  scrollableContainer: React.RefObject<HTMLDivElement>;
  canScrollLeft: boolean;
  canScrollRight: boolean;
  scrollLeft: () => void;
  scrollRight: () => void;
};

/**
 * Event listener lifecycle management hook
 * @param event - Event type to listen for
 * @param handler - Event handler function
 * @param target - Event target (defaults to window)
 * @param options - Event listener options
 */
function useEventListener<K extends keyof WindowEventMap>(
  event: K,
  handler: (event: WindowEventMap[K]) => void,
  target?: EventTarget,
  options?: AddEventListenerOptions
): void;

/**
 * Focus state management hook
 * @returns Object with focus state and utilities
 */
function useFocus(): {
  focused: boolean;
  onFocus: () => void;
  onBlur: () => void;
};

/**
 * Focus-in event handling hook for tracking focus within containers
 * @param onFocusIn - Callback when focus enters container
 * @param onFocusOut - Callback when focus leaves container
 * @returns Ref object to attach to container
 */
function useFocusIn(
  onFocusIn?: () => void,
  onFocusOut?: () => void
): React.RefObject<HTMLElement>;

/**
 * Hover state management hook
 * @returns Object with hover state and handlers
 */
function useHover(): {
  hovered: boolean;
  onMouseEnter: () => void;
  onMouseLeave: () => void;
  onMouseOver: () => void;
  onMouseOut: () => void;
};

/**
 * Clipboard copy functionality hook
 * @returns Copy function that returns success boolean
 */
function useCopyToClipboard(): (text: string) => Promise<boolean>;

/**
 * Ephemeral presence manager hook for tracking focus and presence state
 * @returns Read-only ephemeral presence manager instance
 */
function useEphemeralPresenceManager(): EphemeralPresenceManager;

interface EphemeralPresenceManager {
  /** Add presence listener */
  addPresenceListener(handler: PresenceHandler): void;
  /** Remove presence listener */
  removePresenceListener(handler: PresenceHandler): void;
}

type PresenceHandler = (isPresent: boolean) => void;

/**
 * Hook for managing IndexFilters mode state
 * @param initialMode - Initial filter mode
 * @returns Filter mode state and setter
 */
function useSetIndexFiltersMode(
  initialMode?: IndexFiltersMode
): [IndexFiltersMode, (mode: IndexFiltersMode) => void];

enum IndexFiltersMode {
  Default = 'default',
  Filtering = 'filtering',
  Disabled = 'disabled',
}

/**
 * Convert RGB color to hexadecimal string
 * @param color - RGB color object
 * @returns Hexadecimal color string (e.g., "#FF0000")
 */
function rgbToHex(color: RGBColor): string;

/**
 * Convert RGB color to HSB color space
 * @param color - RGB color object
 * @returns HSB color object
 */
function rgbToHsb(color: RGBColor): HSBColor;

/**
 * Convert RGB color to HSL color space
 * @param color - RGB color object
 * @returns HSL color object
 */
function rgbToHsl(color: RGBColor): HSLColor;

/**
 * Convert HSB color to RGB color space
 * @param color - HSB color object
 * @returns RGB color object
 */
function hsbToRgb(color: HSBColor): RGBColor;

/**
 * Convert HSB color to hexadecimal string
 * @param color - HSB color object
 * @returns Hexadecimal color string
 */
function hsbToHex(color: HSBColor): string;

/**
 * Convert HSL color to RGB color space
 * @param color - HSL color object
 * @returns RGB color object
 */
function hslToRgb(color: HSLColor): RGBColor;

/**
 * Convert RGB/RGBA color to CSS color string
 * @param color - RGB or RGBA color object
 * @returns CSS color string (e.g., "rgb(255, 0, 0)" or "rgba(255, 0, 0, 0.5)")
 */
function rgbString(color: RGBColor | RGBAColor): string;

/**
 * Alias for rgbString function
 * @param color - RGBA color object
 * @returns CSS rgba color string
 */
function rgbaString(color: RGBAColor): string;

/**
 * Convert hexadecimal color string to RGB color
 * @param hex - Hexadecimal color string
 * @returns RGB color object or null if invalid
 */
function hexToRgb(hex: string): RGBColor | null;

/** RGB color interface */
interface RGBColor {
  /** Red component (0-255) */
  red: number;
  /** Green component (0-255) */
  green: number;
  /** Blue component (0-255) */
  blue: number;
}

/** RGBA color interface extending RGB with alpha */
interface RGBAColor extends RGBColor {
  /** Alpha component (0-1) */
  alpha: number;
}

/** HSB color interface */
interface HSBColor {
  /** Hue component (0-360) */
  hue: number;
  /** Saturation component (0-1) */
  saturation: number;
  /** Brightness component (0-1) */
  brightness: number;
}

/** HSBA color interface extending HSB with alpha */
interface HSBAColor extends HSBColor {
  /** Alpha component (0-1) */
  alpha: number;
}

/** HSL color interface */
interface HSLColor {
  /** Hue component (0-360) */
  hue: number;
  /** Saturation component (0-1) */
  saturation: number;
  /** Lightness component (0-1) */
  lightness: number;
}

/** HSLA color interface extending HSL with alpha */
interface HSLAColor extends HSLColor {
  /** Alpha component (0-1) */
  alpha: number;
}

/** Combined HSBA and HSLA color type */
type HSBLAColor = HSBAColor | HSLAColor;

/**
 * Get breakpoint query entries for responsive behavior
 * @param breakpoints - Breakpoint configuration
 * @returns Array of media query entries
 */
function getBreakpointsQueryEntries(
  breakpoints: BreakpointsConfig
): Array<[string, string]>;

/**
 * Get media query for collapsed navigation state
 * @returns CSS media query string
 */
function navigationBarCollapsed(): string;

/**
 * Get media query for stacked content layout
 * @returns CSS media query string
 */
function stackedContent(): string;

interface BreakpointsConfig {
  /** Extra small breakpoint */
  xs: string;
  /** Small breakpoint */
  sm: string;
  /** Medium breakpoint */
  md: string;
  /** Large breakpoint */
  lg: string;
  /** Extra large breakpoint */
  xl: string;
}

/** Directional breakpoint aliases */
type BreakpointsDirectionAlias = 
  | 'xsUp' | 'smUp' | 'mdUp' | 'lgUp' | 'xlUp'
  | 'xsDown' | 'smDown' | 'mdDown' | 'lgDown'
  | 'xsOnly' | 'smOnly' | 'mdOnly' | 'lgOnly';

/** Default locale for Polaris applications */
const DEFAULT_LOCALE: string = 'en';

/** Array of supported locale codes */
const SUPPORTED_LOCALES: string[] = [
  'cs', 'da', 'de', 'en', 'es', 'fi', 'fr', 'it', 'ja', 'ko',
  'nb', 'nl', 'pl', 'pt-BR', 'pt-PT', 'sv', 'th', 'tr', 'vi', 
  'zh-CN', 'zh-TW'
];

/**
 * Internal scroll lock management context (read-only)
 * @internal
 */
const _SECRET_INTERNAL_SCROLL_LOCK_MANAGER_CONTEXT: React.Context<any>;

/**
 * Internal content context for nested components (read-only)
 * @internal  
 */
const _SECRET_INTERNAL_WITHIN_CONTENT_CONTEXT: React.Context<boolean>;

/**
 * Ephemeral presence manager hook for temporary UI states (read-only)
 * @returns Presence manager utilities
 */
function useEphemeralPresenceManager(): EphemeralPresenceManager;

interface EphemeralPresenceManager {
  /** Add ephemeral presence */
  addPresence(id: string, presence: any): void;
  /** Remove ephemeral presence */
  removePresence(id: string): void;
  /** Check if presence exists */
  hasPresence(id: string): boolean;
}

/** Shared data attribute constants for component coordination */
const DATA_ATTRIBUTE: {
  /** Portal container data attribute */
  Portal: string;
  /** Overlay data attribute */
  Overlay: string;
  /** Popover data attribute */
  Popover: string;
  /** Modal data attribute */
  Modal: string;
  /** Sheet data attribute */
  Sheet: string;
};

import React, { useState } from 'react';
import { 
  useBreakpoints, 
  useFrame, 
  useTheme, 
  useIndexResourceState,
  rgbToHex,
  hexToRgb
} from '@shopify/polaris';

function UtilitiesExample() {
  const breakpoints = useBreakpoints();
  const frame = useFrame();
  const theme = useTheme();
  
  const [resources] = useState([
    { id: '1', name: 'Product A' },
    { id: '2', name: 'Product B' },
    { id: '3', name: 'Product C' },
  ]);
  
  const {
    selectedResources,
    handleSelectionChange,
    clearSelection
  } = useIndexResourceState(resources, {
    resourceIDResolver: (resource) => resource.id
  });

  // Color transformations
  const primaryColor = hexToRgb(theme.colors.primary);
  const hexColor = primaryColor ? rgbToHex(primaryColor) : '#000000';

  const showToast = () => {
    frame.showToast({
      content: `Selected ${selectedResources.length} items`,
      onDismiss: () => {},
    });
  };

  return (
    <div>
      {/* Responsive behavior */}
      {breakpoints.smUp ? (
        <p>Desktop layout</p>
      ) : (
        <p>Mobile layout</p>
      )}
      
      {/* Selection management */}
      <button onClick={clearSelection}>
        Clear Selection ({selectedResources.length})
      </button>
      
      <button onClick={showToast}>
        Show Toast
      </button>
      
      {/* Color information */}
      <div style={{ color: hexColor }}>
        Primary color: {hexColor}
      </div>
    </div>
  );
}

/**
 * Comprehensive filtering system for index pages
 * @param sortOptions - Available sorting options
 * @param sortSelected - Currently selected sort option
 * @param queryValue - Current search query
 * @param filters - Available filter options
 * @returns JSX element with index filtering interface
 */
function IndexFilters(props: IndexFiltersProps): JSX.Element;

interface IndexFiltersProps {
  /** The sort options for the index */
  sortOptions: SortButtonChoice[];
  /** The selected sort option */
  sortSelected: number;
  /** The query value */
  queryValue?: string;
  /** Placeholder text for the query field */
  queryPlaceholder?: string;
  /** Available filters */
  filters: FilterInterface[];
  /** Applied filters */
  appliedFilters?: AppliedFilterInterface[];
  /** Mode of the index filters */
  mode: IndexFiltersMode;
  /** Whether the cancel button is disabled */
  canCreateNewView?: boolean;
  /** The tabs for the index */
  tabs?: Tab[];
  /** The selected tab */
  selected?: number;
  /** Callback when the query is changed */
  onQueryChange?(queryValue: string): void;
  /** Callback when the query is cleared */
  onQueryClear?(): void;
  /** Callback when the sort is changed */
  onSort?(sortSelected: string): void;
  /** Callback when filters are changed */
  onFiltersChange?(appliedFilters: AppliedFilterInterface[]): void;
  /** Callback when the view is created */
  onCreateNewView?(name: string): void;
  /** Callback when filters are cleared */
  onClearAll?(): void;
}

interface SortButtonChoice {
  /** Unique identifier for the sort option */
  label: string;
  /** Sort direction */
  value: string;
  /** Sort direction ascending/descending */
  directionLabel: string;
}

enum IndexFiltersMode {
  Filtering = 'FILTERING',
  Default = 'DEFAULT',
}

/**
 * Hook for managing IndexFilters mode state
 * @returns Mode management utilities
 */
function useSetIndexFiltersMode(): {
  mode: IndexFiltersMode;
  setMode: (mode: IndexFiltersMode) => void;
};