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

Navigation Components

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

Navigation and linking components for building consistent user flows, site structure, and wayfinding experiences. These components provide accessible navigation patterns with proper ARIA support and keyboard interaction.

Capabilities

Navigation

Main navigation component for sidebar navigation with hierarchical structure, user information, and contextual actions.

/**
 * Main navigation component for sidebar navigation
 * @param location - Current location/URL for active state
 * @param children - Navigation items and sections
 * @param contextControl - Context-specific controls
 * @returns JSX element with navigation sidebar
 */
function Navigation(props: NavigationProps): JSX.Element;

interface NavigationProps {
  /** Current location for determining active items */
  location: string;
  /** Navigation items and content */
  children?: React.ReactNode;
  /** Context control component */
  contextControl?: React.ReactNode;
  /** Navigation dismissal handler (mobile) */
  onDismiss?: () => void;
  /** ARIA label for navigation */
  ariaLabelledBy?: string;
}

/**
 * Navigation section for grouping related items
 * @param title - Section title
 * @param items - Navigation items in section
 * @param action - Section-level action
 * @returns JSX element with navigation section
 */
function NavigationSection(props: NavigationSectionProps): JSX.Element;

interface NavigationSectionProps {
  /** Section title */
  title?: string;
  /** Navigation items */
  items: NavigationItemProps[];
  /** Section action */
  action?: NavigationSectionAction;
  /** Section separator */
  separator?: boolean;
  /** Fill available space */
  fill?: boolean;
  /** Rollup configuration */
  rollup?: NavigationRollup;
}

/**
 * Individual navigation item
 * @param label - Item label text
 * @param url - Navigation URL
 * @param icon - Item icon
 * @param badge - Item badge content
 * @returns JSX element with navigation item
 */
function NavigationItem(props: NavigationItemProps): JSX.Element;

interface NavigationItemProps {
  /** Item label */
  label: string;
  /** Navigation URL */
  url?: string;
  /** Item icon */
  icon?: IconSource;
  /** Badge content */
  badge?: string | React.ReactNode;
  /** Sub-navigation items */
  subNavigationItems?: SubNavigationItem[];
  /** Secondary action */
  secondaryAction?: SecondaryAction;
  /** Disabled state */
  disabled?: boolean;
  /** New indicator */
  new?: boolean;
  /** Click handler */
  onClick?: () => void;
  /** Match paths exactly */
  exactMatch?: boolean;
  /** External link */
  external?: boolean;
  /** Selected state */
  selected?: boolean;
  /** Display name for screen readers */
  displayName?: string;
  /** Additional accessibility label */
  accessibilityLabel?: string;
}

interface SubNavigationItem {
  /** Sub-item label */
  label: string;
  /** Sub-item URL */
  url: string;
  /** Disabled state */
  disabled?: boolean;
  /** New indicator */
  new?: boolean;
  /** Click handler */
  onClick?: () => void;
}

interface NavigationSectionAction {
  /** Action icon */
  icon: IconSource;
  /** Accessibility label */
  accessibilityLabel: string;
  /** Action handler */
  onClick: () => void;
}

interface NavigationRollup {
  /** Rollup after count */
  after: number;
  /** View action label */
  view: string;
  /** Hide action label */
  hide: string;
  /** Rollup action handler */
  activePath: string;
}

interface SecondaryAction {
  /** Action URL */
  url?: string;
  /** Action accessibility label */
  accessibilityLabel: string;
  /** Action icon */
  icon: IconSource;
  /** Action tooltip */
  tooltip?: string;
  /** Action handler */
  onClick?: () => void;
}

Usage Example:

import React from 'react';
import { Navigation, Icon } from '@shopify/polaris';
import { HomeIcon, ProductIcon, OrderIcon } from '@shopify/polaris-icons';

function AppNavigation() {
  const navigationItems = [
    {
      label: 'Home',
      icon: HomeIcon,
      url: '/home',
    },
    {
      label: 'Products',
      icon: ProductIcon,
      url: '/products',
      badge: 'New',
      subNavigationItems: [
        { label: 'All products', url: '/products' },
        { label: 'Inventory', url: '/products/inventory' },
        { label: 'Collections', url: '/products/collections' },
      ],
    },
    {
      label: 'Orders',
      icon: OrderIcon,
      url: '/orders',
      badge: '15',
    },
  ];

  return (
    <Navigation location="/products">
      <Navigation.Section
        items={navigationItems}
      />
    </Navigation>
  );
}

Navigation Utilities

Utility function for determining active navigation items based on current location.

/**
 * Determine if a navigation item should be marked as active
 * @param item - Navigation item to check
 * @param currentPath - Current path/location
 * @returns Whether item should be active
 */
function isNavigationItemActive(
  item: NavigationItemProps,
  currentPath: string
): boolean;

Link

Basic link component with support for external links, accessibility features, and consistent styling.

/**
 * Basic link component with accessibility and styling
 * @param children - Link content
 * @param url - Link destination URL
 * @param external - External link indicator
 * @returns JSX element with link
 */
function Link(props: LinkProps): JSX.Element;

interface LinkProps {
  /** Link content */
  children?: React.ReactNode;
  /** Link URL */
  url?: string;
  /** External link */
  external?: boolean;
  /** Link ID */
  id?: string;
  /** Link role */
  role?: string;
  /** ARIA describedby */
  ariaDescribedBy?: string;
  /** Click handler */
  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
  /** Remove underline */
  removeUnderline?: boolean;
  /** Monospace font */
  monochrome?: boolean;
  /** Data attributes */
  dataPolarisUnstyled?: boolean;
}

UnstyledLink

Unstyled link component providing basic link functionality without Polaris styling.

/**
 * Unstyled link component without Polaris styling
 * @param children - Link content
 * @param url - Link destination
 * @param external - External link indicator
 * @returns JSX element with basic link
 */
function UnstyledLink(props: UnstyledLinkProps): JSX.Element;

interface UnstyledLinkProps {
  /** Link content */
  children?: React.ReactNode;
  /** Link URL */
  url?: string;
  /** External link */
  external?: boolean;
  /** Link ID */
  id?: string;
  /** Click handler */
  onClick?: () => void;
  /** Additional class names */
  className?: string;
  /** ARIA label */
  ariaLabel?: string;
}

Breadcrumbs

Breadcrumb navigation component showing the current page's location within the site hierarchy.

/**
 * Breadcrumb navigation showing page hierarchy
 * @param breadcrumbs - Array of breadcrumb items
 * @returns JSX element with breadcrumb navigation
 */
function Breadcrumbs(props: BreadcrumbsProps): JSX.Element;

interface BreadcrumbsProps {
  /** Array of breadcrumb items */
  breadcrumbs: Breadcrumb[];
}

interface Breadcrumb {
  /** Breadcrumb content/label */
  content: string;
  /** Breadcrumb URL */
  url?: string;
  /** Click handler */
  onAction?: () => void;
  /** Target for link */
  target?: Target;
  /** Accessibility label */
  accessibilityLabel?: string;
}

/** Link target values */
type Target = '_blank' | '_self' | '_parent' | '_top';

Usage Example:

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

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

  return (
    <Page
      title="Vintage T-Shirt"
      breadcrumbs={breadcrumbs}
    >
      <Card>
        {/* Product details */}
      </Card>
    </Page>
  );
}

Pagination

Page navigation component with previous/next controls and page information display.

/**
 * Page navigation with previous/next controls
 * @param hasPrevious - Has previous page
 * @param onPrevious - Previous page handler
 * @param hasNext - Has next page
 * @param onNext - Next page handler
 * @param label - Pagination accessibility label
 * @returns JSX element with pagination controls
 */
function Pagination(props: PaginationProps): JSX.Element;

interface PaginationProps {
  /** Has previous page */
  hasPrevious?: boolean;
  /** Previous page click handler */
  onPrevious?: () => void;
  /** Has next page */
  hasNext?: boolean;
  /** Next page click handler */
  onNext?: () => void;
  /** Accessibility label */
  label: string;
  /** Next button tooltip */
  nextTooltip?: string;
  /** Previous button tooltip */
  previousTooltip?: string;
  /** Next button accessibility label */
  nextLabel?: string;
  /** Previous button accessibility label */
  previousLabel?: string;
  /** Previous button keys for keyboard navigation */
  previousKeys?: Key[];
  /** Next button keys for keyboard navigation */
  nextKeys?: Key[];
  /** Page information display */
  type?: 'page' | 'table';
}

Usage Example:

import React, { useState } from 'react';
import { Pagination, Card, DataTable } from '@shopify/polaris';

function PaginatedTable() {
  const [currentPage, setCurrentPage] = useState(1);
  const totalPages = 10;

  const handlePrevious = () => {
    if (currentPage > 1) {
      setCurrentPage(currentPage - 1);
    }
  };

  const handleNext = () => {
    if (currentPage < totalPages) {
      setCurrentPage(currentPage + 1);
    }
  };

  return (
    <Card>
      <DataTable
        // ... table props
      />
      <Pagination
        hasPrevious={currentPage > 1}
        onPrevious={handlePrevious}
        hasNext={currentPage < totalPages}
        onNext={handleNext}
        label={`Page ${currentPage} of ${totalPages}`}
      />
    </Card>
  );
}

Navigation Types

/** Keyboard key enum for navigation shortcuts */
enum Key {
  Backspace = 'Backspace',
  Tab = 'Tab',
  Enter = 'Enter',
  Shift = 'Shift',
  Control = 'Control',
  Alt = 'Alt',
  Escape = 'Escape',
  Space = ' ',
  PageUp = 'PageUp',
  PageDown = 'PageDown',
  End = 'End',
  Home = 'Home',
  LeftArrow = 'ArrowLeft',
  UpArrow = 'ArrowUp',
  RightArrow = 'ArrowRight',
  DownArrow = 'ArrowDown',
  Delete = 'Delete',
}

/** Icon source type for navigation items */
type IconSource = React.ComponentType<any> | 'placeholder' | string;

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

FooterHelp

Footer help component for providing contextual assistance and links to additional resources at the bottom of pages.

/**
 * Footer help component for contextual assistance
 * @param children - Help content and links
 * @returns JSX element with footer help information
 */
function FooterHelp(props: FooterHelpProps): JSX.Element;

interface FooterHelpProps {
  /** The content to display inside the footer help */
  children?: React.ReactNode;
}

TopBar

Top navigation bar component that provides global navigation, search, user menu, and notification access across the application.

/**
 * Global top navigation bar
 * @param showNavigationToggle - Whether to show navigation toggle
 * @param userMenu - User account menu
 * @param searchField - Global search field
 * @returns JSX element with top navigation bar
 */
function TopBar(props: TopBarProps): JSX.Element;

interface TopBarProps {
  /** Whether to show the navigation toggle button */
  showNavigationToggle?: boolean;
  /** User menu for the top bar */
  userMenu?: React.ReactNode;
  /** A search field for the top bar */
  searchField?: React.ReactNode;
  /** A global search field for the top bar */
  searchResults?: React.ReactNode;
  /** A slot for search result popup */
  searchResultsVisible?: boolean;
  /** Callback when the search results are dismissed */
  onSearchResultsDismiss?(): void;
  /** Whether the search results overlay is visible */
  searchResultsOverlayVisible?: boolean;
  /** A contextual save bar for the top bar */
  contextualSaveBar?: React.ReactNode;
  /** Secondary menu for the top bar */
  secondaryMenu?: React.ReactNode;
  /** Callback when the navigation toggle is clicked */
  onNavigationToggle?(): void;
}

FullscreenBar

Fullscreen mode navigation bar that replaces the normal top bar when content is displayed in fullscreen view.

/**
 * Navigation bar for fullscreen mode
 * @param onAction - Back/exit action handler
 * @param children - Content to display in the bar
 * @returns JSX element with fullscreen navigation bar
 */
function FullscreenBar(props: FullscreenBarProps): JSX.Element;

interface FullscreenBarProps {
  /** Callback when the back button is clicked */
  onAction(): void;
  /** The content to display inside the fullscreen bar */
  children?: React.ReactNode;
}

Install with Tessl CLI