@cw-parcelpanel/headless-react/index.d.ts

ParcelPanel Headless React Component - EDD & Tracking widgets for Shopify stores with TypeScript support

/**
 * Type definitions for ParcelPanel EDD React components
 */

import * as React from 'react';

/**
 * Customer location information interface
 * Only contains the essential location data needed for delivery calculations
 */
export interface Customer {
  /** Country code (ISO 3166-1 alpha-2), e.g., "US", "CN" */
  country_code: string;
  /** Province/state code, e.g., "CA", "NY" */
  province_code: string;
}

/**
 * Widget styling configuration interface
 */
export interface WidgetSettings {
  /** Border radius in pixels */
  corner_radius?: number;
  /** Top margin in pixels */
  margin_top?: number;
  /** Bottom margin in pixels */
  margin_bottom?: number;
  /** Horizontal padding in pixels */
  padding_x?: number;
  /** Vertical padding in pixels */
  padding_y?: number;
}

/**
 * Product information interface for SDK
 */
export interface SDKProductInfo {
  /** Product ID */
  id: number;
  /** Product handle/slug (optional) */
  handle?: string;
  /** Whether the product is available for purchase */
  available: boolean;
  /** Array of product variants (optional) */
  variants?: Array<{
    /** Variant ID */
    id: string;
    /** Whether the variant is available */
    available: boolean;
    /** Whether the variant requires shipping */
    requires_shipping: boolean;
  }>;
}

/**
 * SDK configuration interface
 */
export interface SDKConfig {
  /** Shopify shop domain (e.g., "example.myshopify.com") */
  shopDomain: string;
  /** Product ID (optional) */
  productId?: number | string;
  /** Locale code (e.g., "en", "zh-CN") (optional) */
  locale?: string;
  /** Whether in preview mode (optional) */
  isPreview?: boolean;
  /** API endpoint configuration (optional) */
  apiEndpoint?: 'test' | 'prod' | string;
  /** Customer location information (optional) */
  customer?: Customer;
  /** Widget styling settings (optional) */
  settings?: WidgetSettings;
}

/**
 * ParcelPanel EDD SDK interface
 */
export interface ParcelPanelEDDSDK {
  /** Get current SDK configuration */
  getConfig(): SDKConfig;
  /** Update SDK configuration */
  updateConfig(config: Partial<SDKConfig>): void;
  /** Set product information */
  setProduct(productInfo: SDKProductInfo): void;
  /** Set customer location information */
  setCustomer(customer: Customer): void;
  /** Set widget styling settings */
  setSettings(settings: WidgetSettings): void;
  /** Destroy the SDK instance */
  destroy(): void;
  /** Refresh all widgets (optional method) */
  refreshAllWidgets?(): void;
  /** Create a widget in the specified container */
  createWidget(container: HTMLElement, options?: any): HTMLElement | null;
}

/**
 * Address selector configuration options
 */
export interface SelectorOptions {
  /** Default country code */
  country?: string;
  /** Default province/state code */
  province?: string;
  /** JSON string of additional settings */
  settings?: string;
}

/**
 * Location change event data
 */
export interface LocationChangeData {
  /** Selected country code */
  country: string;
  /** Selected province/state code */
  province: string;
}

/**
 * Props interface for ParcelPanel EDD React component
 */
export interface ParcelPanelEDDProps extends Omit<SDKConfig, 'shopDomain'> {
  /** Shopify shop domain (required), e.g., "example.myshopify.com" */
  shopDomain: string;
  /** CSS class name for the component */
  className?: string;
  /** Inline styles for the component */
  style?: React.CSSProperties;
  /** Address selector configuration options */
  selectorOptions?: SelectorOptions;
  /** Callback fired when the component is successfully loaded */
  onLoaded?: (sdk: ParcelPanelEDDSDK) => void;
  /** Callback fired when an error occurs */
  onError?: (error: Error) => void;
  /** Callback fired when the address/location changes */
  onLocationChange?: (location: LocationChangeData) => void;
}

/**
 * Ref interface for ParcelPanel EDD React component methods
 */
export interface ParcelPanelEDDRef {
  /** Get the SDK instance */
  getSDK: () => ParcelPanelEDDSDK | null;
  /** Set product information */
  setProduct: (productInfo: SDKProductInfo) => void;
  /** Update customer location information */
  setCustomer: (customer: SDKConfig['customer']) => void;
  /** Update styling settings */
  setSettings: (settings: SDKConfig['settings']) => void;
  /** Update SDK configuration */
  updateConfig: (config: Partial<SDKConfig>) => void;
  /** Destroy the component and clean up resources */
  destroy: () => void;
}

/**
 * ParcelPanel EDD React component
 * 
 * A React wrapper component for ParcelPanel's Estimated Delivery Date (EDD) widget,
 * providing seamless integration with Shopify stores.
 * 
 * @example
 * ```tsx
 * import { ParcelPanelEDD } from '@cw-parcelpanel/headless-react';
 * 
 * function ProductPage() {
 *   return (
 *     <ParcelPanelEDD
 *       shopDomain="your-shop.myshopify.com"
 *       productId={123456}
 *       locale="en"
 *       customer={{ country_code: "US", province_code: "CA" }}
 *       onLoaded={(sdk) => console.log('EDD widget loaded:', sdk)}
 *       onError={(error) => console.error('EDD error:', error)}
 *     />
 *   );
 * }
 * ```
 */
export const ParcelPanelEDD: React.ForwardRefExoticComponent<
  ParcelPanelEDDProps & React.RefAttributes<ParcelPanelEDDRef>
>;

/**
 * Tracking widget props interface
 */
export interface TrackingWidgetProps {
  /** Shopify shop domain (required), e.g., "your-shop.myshopify.com" */
  shopDomain: string;
  /** Locale code (optional), e.g., "en", "zh-CN", "ja". Defaults to "en" */
  locale?: string;
  /** CSS class name for the component */
  className?: string;
  /** Inline styles for the component */
  style?: React.CSSProperties;
  /** Callback fired when the tracking widget is loaded */
  onLoaded?: () => void;
  /** Callback fired when an error occurs */
  onError?: (error: Error) => void;
}

/**
 * Tracking widget component for order tracking functionality
 * 
 * A React component that embeds ParcelPanel's tracking page widget,
 * allowing customers to track their orders directly within your app.
 * 
 * @example
 * ```tsx
 * import { TrackingWidget } from '@cw-parcelpanel/headless-react';
 * 
 * function TrackingPage() {
 *   return (
 *     <TrackingWidget
 *       shopDomain="your-shop.myshopify.com"
 *       locale="en"
 *       onLoaded={() => console.log('Tracking widget loaded')}
 *       onError={(error) => console.error('Tracking error:', error)}
 *     />
 *   );
 * }
 * ```
 */
export const TrackingWidget: React.FC<TrackingWidgetProps>;

// Export additional types for convenience
export type {
  Customer as CustomerLocationInfo,
  WidgetSettings as StyleSettings,
  SDKProductInfo as ProductInfo,
  SDKConfig as Config,
  SelectorOptions as AddressSelectorOptions,
  LocationChangeData as LocationData
};

// Default export
declare const _default: {
  ParcelPanelEDD: typeof ParcelPanelEDD;
  TrackingWidget: typeof TrackingWidget;
};

export default _default;