tessl/npm-shopify--polaris

Shopify's comprehensive admin product component library for React applications with TypeScript support and accessibility features.

—

Pending

Overview

Eval results

Files

Types & Interfaces

Name: tessl/npm-shopify--polaris
Author: tessl

Complete TypeScript type definitions, interfaces, and enums for type-safe development with Polaris components. These types ensure proper component usage, provide IntelliSense support, and maintain consistency across the design system.

Capabilities

Core Primitive Types

Fundamental types used throughout the Polaris component library for consistent typing and functionality.

/** Icon source union type supporting React components, placeholders, and strings */
type IconSource = React.ComponentType<any> | 'placeholder' | string;

/** HTML heading element types for semantic markup */
type HeadingTagName = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';

/** Error content union type for flexible error messaging */
type Error = string | React.ReactNode | (string | React.ReactNode)[];

/** Link target values for navigation and external links */
type Target = '_blank' | '_self' | '_parent' | '_top';

Action Type Hierarchy

Comprehensive action type system supporting various interaction patterns and component needs.

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

/** Base button interface with comprehensive interaction properties */
interface BaseButton {
  /** Button ID attribute */
  id?: string;
  /** Navigation URL */
  url?: string;
  /** External link indicator */
  external?: boolean;
  /** Download attribute */
  download?: string | boolean;
  /** Submit button type */
  submit?: boolean;
  /** Disabled state */
  disabled?: boolean;
  /** Loading state */
  loading?: boolean;
  /** Accessibility label */
  accessibilityLabel?: string;
  /** ARIA describedby attribute */
  ariaDescribedBy?: string;
  /** ARIA expanded state */
  ariaExpanded?: boolean;
  /** ARIA controls attribute */
  ariaControls?: string;
  /** ARIA pressed state */
  ariaPressed?: boolean;
  /** Button role override */
  role?: string;
  /** Tab index */
  tabIndex?: number;
  /** Click handler */
  onClick?(): void;
  /** Focus handler */
  onFocus?(): void;
  /** Blur handler */
  onBlur?(): void;
  /** Key down handler */
  onKeyDown?(event: React.KeyboardEvent): void;
  /** Key press handler */
  onKeyPress?(event: React.KeyboardEvent): void;
  /** Key up handler */
  onKeyUp?(event: React.KeyboardEvent): void;
  /** Mouse enter handler */
  onMouseEnter?(): void;
  /** Touch start handler */
  onTouchStart?(): void;
}

/** Link action interface requiring URL */
interface LinkAction extends Action {
  /** Required URL for link actions */
  url: string;
}

/** Badge action interface with optional badge configuration */
interface BadgeAction extends Action {
  /** Badge content or configuration */
  badge?: string | {
    tone?: string;
    progress?: string;
  };
}

/** Base callback action requiring onAction handler */
interface BaseCallbackAction extends Action {
  /** Required action callback */
  onAction(): void;
}

/** Callback action extending base callback action */
interface CallbackAction extends BaseCallbackAction {}

/** Disableable action interface */
interface DisableableAction extends Action {
  /** Disabled state */
  disabled?: boolean;
}

/** Destructable action interface for dangerous actions */
interface DestructableAction extends Action {
  /** Destructive styling indicator */
  destructive?: boolean;
}

/** Iconable action interface with icon support */
interface IconableAction extends Action {
  /** Action icon */
  icon?: IconSource;
}

/** Loadable action interface with loading state */
interface LoadableAction extends Action {
  /** Loading state indicator */
  loading?: boolean;
}

/** Outlineable action interface for outline styling */
interface OutlineableAction extends Action {
  /** Outline styling variant */
  outline?: boolean;
}

/** Plain action interface for minimal styling */
interface PlainAction extends Action {
  /** Plain styling variant */
  plain?: boolean;
}

/** Tooltip action interface with help text */
interface TooltipAction extends Action {
  /** Help text content */
  helpText?: React.ReactNode;
}

/** Complex action combining multiple action interfaces */
interface ComplexAction extends 
  DisableableAction,
  DestructableAction,
  IconableAction,
  LoadableAction,
  OutlineableAction,
  PlainAction,
  TooltipAction {
  /** Action ID */
  id?: string;
  /** Primary action styling */
  primary?: boolean;
  /** Size variant */
  size?: 'slim' | 'medium' | 'large';
  /** Submit button type */
  submit?: boolean;
  /** Link target */
  target?: Target;
  /** Remove underline */
  removeUnderline?: boolean;
}

/** Menu action descriptor with tooltip and positioning */
interface MenuActionDescriptor extends ActionListItemDescriptor {
  /** Help text tooltip */
  helpText?: string;
  /** Action index for menu positioning */
  index?: number;
}

/** Menu group descriptor for organizing related actions */
interface MenuGroupDescriptor {
  /** Group title */
  title?: string;
  /** Actions in the group */
  actions: MenuActionDescriptor[];
  /** Group icon */
  icon?: IconSource;
  /** Group details content */
  details?: React.ReactNode;
  /** Disabled state */
  disabled?: boolean;
}

Option and Selection Types

Types for managing options, selections, and descriptive content in lists and menus.

/** Option descriptor for select and choice components */
interface OptionDescriptor {
  /** Option value */
  value: string;
  /** Option display label */
  label: string;
  /** Disabled option state */
  disabled?: boolean;
  /** Option media content */
  media?: React.ReactNode;
  /** Additional details */
  details?: React.ReactNode;
}

/** Section descriptor for grouped options */
interface SectionDescriptor {
  /** Section title */
  title: string;
  /** Options in the section */
  options: OptionDescriptor[];
}

/** Descriptor union type for options and sections */
type Descriptor = SectionDescriptor | OptionDescriptor;

/** Action list item descriptor for menu items */
interface ActionListItemDescriptor {
  /** Item content */
  content?: React.ReactNode;
  /** Action callback */
  onAction?(): void;
  /** Navigation URL */
  url?: string;
  /** External link */
  external?: boolean;
  /** Item icon */
  icon?: IconSource;
  /** Item image */
  image?: string;
  /** Prefix content */
  prefix?: React.ReactNode;
  /** Suffix content */
  suffix?: React.ReactNode;
  /** Help text */
  helpText?: React.ReactNode;
  /** Accessibility label */
  accessibilityLabel?: string;
  /** Disabled state */
  disabled?: boolean;
  /** Destructive action */
  destructive?: boolean;
  /** Ellipsis truncation */
  ellipsis?: boolean;
  /** Active state */
  active?: boolean;
  /** Badge content */
  badge?: any;
  /** Role override */
  role?: string;
  /** Truncate text */
  truncate?: boolean;
  /** Item variant */
  variant?: 'default' | 'indented' | 'menu';
}

/** Action list section for grouping items */
interface ActionListSection {
  /** Section title */
  title?: string;
  /** Section items */
  items: ActionListItemDescriptor[];
  /** Fill available space */
  fill?: boolean;
}

Filter and Search Types

Types for filtering, searching, and data management functionality.

/** Applied filter interface for active filters */
interface AppliedFilterInterface {
  /** Filter key identifier */
  key: string;
  /** Filter display label */
  label: string;
  /** Filter removal callback */
  onRemove(key: string): void;
}

/** Filter interface for filter definitions */
interface FilterInterface {
  /** Filter key identifier */
  key: string;
  /** Filter label */
  label: string;
  /** Filter content */
  filter: React.ReactNode;
  /** Filter shortcuts */
  shortcuts?: FilterShortcut[];
  /** Disabled state */
  disabled?: boolean;
}

/** Filter shortcut interface */
interface FilterShortcut {
  /** Shortcut key */
  key: string;
  /** Shortcut label */
  label: string;
  /** Shortcut value */
  value: string;
}

Utility Type Helpers

Advanced TypeScript utility types for enhanced type safety and developer experience.

/** Checkbox component handle interface for imperative control */
interface CheckboxHandles {
  /** Focus the checkbox programmatically */
  focus(): void;
}

/** Non-empty array type ensuring at least one element */
type NonEmptyArray<T> = [T, ...T[]];

/** Extract element type from array type */
type ArrayElement<T extends ReadonlyArray<unknown>> = 
  T extends ReadonlyArray<infer ElementType> ? ElementType : never;

/** Never type for mutually exclusive props */
type Never<T> = { [P in keyof T]?: never };

/** Key-value pair entry type */
type Entry<T> = [keyof T, T[keyof T]];

/** Array of key-value pair entries */
type Entries<T> = Entry<T>[];

/** Experimental feature naming convention */
type Experimental<T> = `Unstable${T}` | `Alpha${T}` | `Beta${T}`;

Keyboard and Interaction Types

Enums and types for keyboard interaction and event handling.

/** Keyboard key enumeration for consistent key handling */
enum Key {
  // Letter keys
  A = 'KeyA',
  B = 'KeyB',
  C = 'KeyC',
  D = 'KeyD',
  E = 'KeyE',
  F = 'KeyF',
  G = 'KeyG',
  H = 'KeyH',
  I = 'KeyI',
  J = 'KeyJ',
  K = 'KeyK',
  L = 'KeyL',
  M = 'KeyM',
  N = 'KeyN',
  O = 'KeyO',
  P = 'KeyP',
  Q = 'KeyQ',
  R = 'KeyR',
  S = 'KeyS',
  T = 'KeyT',
  U = 'KeyU',
  V = 'KeyV',
  W = 'KeyW',
  X = 'KeyX',
  Y = 'KeyY',
  Z = 'KeyZ',
  
  // Number keys
  Zero = 'Digit0',
  One = 'Digit1',
  Two = 'Digit2',
  Three = 'Digit3',
  Four = 'Digit4',
  Five = 'Digit5',
  Six = 'Digit6',
  Seven = 'Digit7',
  Eight = 'Digit8',
  Nine = 'Digit9',
  
  // Special keys
  Backspace = 'Backspace',
  Tab = 'Tab',
  Enter = 'Enter',
  Shift = 'Shift',
  Control = 'Control',
  Alt = 'Alt',
  Escape = 'Escape',
  Space = ' ',
  PageUp = 'PageUp',
  PageDown = 'PageDown',
  End = 'End',
  Home = 'Home',
  
  // Arrow keys
  LeftArrow = 'ArrowLeft',
  UpArrow = 'ArrowUp',
  RightArrow = 'ArrowRight',
  DownArrow = 'ArrowDown',
  
  // Function keys
  F1 = 'F1',
  F2 = 'F2',
  F3 = 'F3',
  F4 = 'F4',
  F5 = 'F5',
  F6 = 'F6',
  F7 = 'F7',
  F8 = 'F8',
  F9 = 'F9',
  F10 = 'F10',
  F11 = 'F11',
  F12 = 'F12',
  
  Delete = 'Delete',
}

Component Reference Types

Reference interfaces for imperative component control and advanced interactions.

/** Banner component handle interface */
interface BannerHandles {
  /** Focus the banner programmatically */
  focus(): void;
}

/** Popover public API for programmatic control */
interface PopoverPublicAPI {
  /** Close the popover with optional source tracking */
  close(source?: PopoverCloseSource): void;
  /** Force update popover position */
  forceUpdatePosition(): void;
}

/** Popover close source enumeration */
enum PopoverCloseSource {
  Click = 'click',
  EscapeKeypress = 'escape-keypress',
  FocusOut = 'focus-out',
  ScrollOut = 'scroll-out',
}

/** Popover autofocus target options */
enum PopoverAutofocusTarget {
  Container = 'container',
  FirstNode = 'first-node',
  None = 'none',
}

/** Scrollable component reference interface */
interface ScrollableRef {
  /** Scroll to top of container */
  scrollToTop(): void;
  /** Scroll to bottom of container */
  scrollToBottom(): void;
  /** Get current scroll position */
  getScrollTop(): number;
}

Testing and Development Types

Types for testing environments and development tools integration.

/** Polaris test provider options for testing environments */
interface WithPolarisTestProviderOptions {
  /** Mock theme configuration */
  theme?: any;
  /** Mock i18n configuration */
  i18n?: any;
  /** Mock features configuration */
  features?: any;
  /** Strict mode for development */
  strict?: boolean;
}

/** Theme provider props for custom theming */
interface ThemeProviderProps {
  /** Theme configuration */
  theme: any;
  /** Provider children */
  children: React.ReactNode;
}

Experimental Component Types

Types for alpha and experimental components with unstable APIs.

/** Alpha picker component props (experimental) */
interface AlphaPickerProps {
  /** Picker value */
  value?: any;
  /** Change handler */
  onChange?(value: any): void;
  /** Disabled state */
  disabled?: boolean;
  /** Picker label */
  label?: string;
}

/** Unstable bulk actions props (experimental) */
interface UnstableBulkActionsProps {
  /** Bulk actions array */
  actions: any[];
  /** Selected items count */
  selectedItemsCount: number;
  /** Selection change handler */
  onSelectionChange?(selection: any): void;
}

/** Select all actions props */
interface SelectAllActionsProps {
  /** Select all label */
  label: string;
  /** Selected state */
  selected: boolean | 'indeterminate';
  /** Selection change handler */
  onToggleAll?(selected: boolean): void;
}

/** Indicator component props for visual indicators */
interface IndicatorProps {
  /** Pulse animation */
  pulse?: boolean;
}

Usage Example:

import React from 'react';
import type {
  Action,
  ComplexAction,
  NonEmptyArray,
  CheckboxHandles,
  Key,
  IconSource,
  Error
} from '@shopify/polaris';

// Using action types
const primaryAction: ComplexAction = {
  content: 'Save product',
  primary: true,
  loading: false,
  onAction: () => console.log('Save clicked'),
};

const secondaryActions: NonEmptyArray<Action> = [
  {
    content: 'Cancel',
    onAction: () => console.log('Cancel clicked'),
  },
];

// Using utility types
const handleKeyPress = (event: React.KeyboardEvent) => {
  if (event.code === Key.Enter) {
    console.log('Enter pressed');
  }
};

// Using error types
const formErrors: { [key: string]: Error } = {
  name: 'Name is required',
  email: ['Email is required', 'Must be a valid email'],
};

// Using icon source
const searchIcon: IconSource = 'search'; // or SearchIcon component

// Using checkbox ref
const checkboxRef = React.useRef<CheckboxHandles>(null);

const focusCheckbox = () => {
  checkboxRef.current?.focus();
};

Type Exports Summary

// Core primitive exports
export type { IconSource, HeadingTagName, Error, Target };

// Action type hierarchy exports  
export type {
  Action,
  BaseButton,
  LinkAction,
  BadgeAction,
  BaseCallbackAction,
  CallbackAction,
  DisableableAction,
  DestructableAction,
  IconableAction,
  LoadableAction,
  OutlineableAction,
  PlainAction,
  TooltipAction,
  ComplexAction,
  MenuActionDescriptor,
  MenuGroupDescriptor,
};

// Option and selection exports
export type {
  OptionDescriptor,
  SectionDescriptor,
  Descriptor,
  ActionListItemDescriptor,
  ActionListSection,
};

// Filter and search exports
export type {
  AppliedFilterInterface,
  FilterInterface,
};

// Utility type exports
export type {
  CheckboxHandles,
  NonEmptyArray,
  ArrayElement,
  Never,
  Entry,
  Entries,
  Experimental,
};

// Keyboard and interaction exports
export { Key };
export type {
  BannerHandles,
  PopoverPublicAPI,
  ScrollableRef,
};

// Enum exports
export { 
  PopoverCloseSource,
  PopoverAutofocusTarget,
};

// Testing and development exports
export type {
  WithPolarisTestProviderOptions,
  ThemeProviderProps,
};

// Experimental component exports
export type {
  AlphaPickerProps,
  UnstableBulkActionsProps,
  SelectAllActionsProps,
  IndicatorProps,
};

Install with Tessl CLI