@shopify/shop-minis-react 0.0.0-snapshot.20251216112959 → 0.0.0-snapshot.20251216185714

package/src/components/atoms/image.tsx

@@ -10,7 +10,24 @@ import {
 } from 'react'
 
 import {cn} from '../../lib/utils'
-import {getThumbhashDataURL, getResizedImageUrl} from '../../utils'
+import {getThumbhashBlobURL, getResizedImageUrl} from '../../utils'
+
+export interface ImageDocProps {
+  /** Remote image URL */
+  src?: string
+  /** File object from useImagePicker (auto-manages blob URL lifecycle) */
+  file?: File
+  /** Thumbhash string for progressive loading placeholder */
+  thumbhash?: string | null
+  /** Aspect ratio (e.g., 16/9, "4/3", or "auto") */
+  aspectRatio?: number | string
+  /** How the image should fit within its container */
+  objectFit?: 'cover' | 'contain' | 'fill' | 'scale-down' | 'none'
+  /** Alt text for accessibility */
+  alt?: string
+  /** Callback when image finishes loading */
+  onLoad?: () => void
+}
 
 type ImageProps = ImgHTMLAttributes<HTMLImageElement> & {
   src?: string
@@ -52,11 +69,20 @@ export const Image = memo(function Image(props: ImageProps) {
     }
   }, [file])
 
-  const thumbhashDataURL = useMemo(
-    () => getThumbhashDataURL(thumbhash ?? undefined),
+  const thumbhashBlobUrl = useMemo(
+    () => getThumbhashBlobURL(thumbhash ?? undefined),
     [thumbhash]
   )
 
+  // Cleanup blob URL when it changes or component unmounts
+  useEffect(() => {
+    return () => {
+      if (thumbhashBlobUrl) {
+        URL.revokeObjectURL(thumbhashBlobUrl)
+      }
+    }
+  }, [thumbhashBlobUrl])
+
   const handleLoad = useCallback(
     (event: React.SyntheticEvent<HTMLImageElement, Event>) => {
       setIsLoaded(true)
@@ -77,13 +103,20 @@ export const Image = memo(function Image(props: ImageProps) {
       style={{
         ...style,
         ...(aspectRatio !== 'auto' && {aspectRatio}),
-        backgroundImage: thumbhashDataURL
-          ? `url(${thumbhashDataURL})`
-          : undefined,
-        backgroundSize: 'cover',
-        backgroundPosition: 'center',
       }}
     >
+      {thumbhashBlobUrl && !isLoaded && (
+        <img
+          className={cn(
+            aspectRatio === 'auto'
+              ? 'w-full h-auto'
+              : 'absolute inset-0 size-full',
+            'object-cover'
+          )}
+          src={thumbhashBlobUrl}
+          aria-hidden="true"
+        />
+      )}
       <img
         className={cn(
           aspectRatio === 'auto'

package/src/components/atoms/list.tsx

@@ -12,7 +12,30 @@ import {Skeleton} from '../ui/skeleton'
 const DEFAULT_REFRESH_PULL_THRESHOLD = 200
 const ELEMENT_BIND_DELAY = 100
 
-interface Props<T = any>
+export interface ListDocProps<T = any> {
+  /** Array of items to render */
+  items: T[]
+  /** Function to render each item */
+  renderItem: (item: T, index: number) => React.ReactNode
+  /** Height of the list container */
+  height?: string | number
+  /** Show scrollbar (default: false) */
+  showScrollbar?: boolean
+  /** Header element rendered at the top of the list */
+  header?: React.ReactNode
+  /** Callback to fetch more items when scrolled to bottom */
+  fetchMore?: () => Promise<void>
+  /** Custom loading component shown while fetching more */
+  loadingComponent?: React.ReactNode
+  /** Callback for pull-to-refresh */
+  onRefresh?: () => Promise<void>
+  /** Whether the list is currently refreshing */
+  refreshing?: boolean
+  /** Enable pull-to-refresh gesture (default: true) */
+  enablePullToRefresh?: boolean
+}
+
+export interface ListProps<T = any>
   extends Omit<
     VirtuosoProps<T, unknown>,
     'data' | 'itemContent' | 'endReached'
@@ -41,7 +64,7 @@ export function List<T = any>({
   refreshing,
   enablePullToRefresh = true,
   ...virtuosoProps
-}: Props<T>) {
+}: ListProps<T>) {
   const inFlightFetchMoreRef = useRef<Promise<void> | null>(null)
   const virtuosoRef = useRef<any>(null)
   const containerRef = useRef<HTMLDivElement>(null)

package/src/components/atoms/product-variant-price.test.tsx

@@ -5,7 +5,7 @@ import {render, screen} from '../../test-utils'
 import {ProductVariantPrice} from './product-variant-price'
 
 // Mock formatMoney function
-vi.mock('../../lib/formatMoney', () => ({
+vi.mock('../../utils/formatMoney', () => ({
   formatMoney: vi.fn((amount: string, currencyCode: string) => {
     const numAmount = parseFloat(amount)
     return currencyCode === 'USD'

package/src/components/atoms/product-variant-price.tsx

@@ -1,5 +1,5 @@
-import {formatMoney} from '../../lib/formatMoney'
 import {cn} from '../../lib/utils'
+import {formatMoney} from '../../utils/formatMoney'
 
 export interface ProductVariantPriceProps {
   amount: number | string

package/src/components/atoms/text-input.tsx

@@ -3,7 +3,9 @@ import * as React from 'react'
 import {useKeyboardAvoidingView} from '../../hooks'
 import {Input} from '../ui/input'
 
-function TextInput({...props}: React.ComponentProps<'input'>) {
+export type TextInputProps = React.ComponentProps<'input'>
+
+function TextInput({...props}: TextInputProps) {
   const inputRef = React.useRef<HTMLInputElement>(null)
   const {onBlur, onFocus} = useKeyboardAvoidingView()
 

package/src/components/atoms/touchable.tsx

@@ -2,15 +2,26 @@ import * as React from 'react'
 
 import {motion, HTMLMotionProps, useAnimationControls} from 'motion/react'
 
+export interface TouchableDocProps {
+  /** Click handler */
+  onClick?: React.MouseEventHandler<HTMLDivElement>
+  /** Prevent click event from bubbling to parent elements */
+  stopPropagation?: boolean
+  /** Content to render inside the touchable area */
+  children?: React.ReactNode
+}
+
+export interface TouchableProps extends HTMLMotionProps<'div'> {
+  onClick?: React.MouseEventHandler<HTMLDivElement>
+  stopPropagation?: boolean
+}
+
 export const Touchable = ({
   children,
   onClick,
   stopPropagation = false,
   ...props
-}: HTMLMotionProps<'div'> & {
-  onClick?: React.MouseEventHandler<HTMLDivElement>
-  stopPropagation?: boolean
-}) => {
+}: TouchableProps) => {
   const ref = React.useRef<HTMLDivElement>(null)
   const controls = useAnimationControls()
 

package/src/components/atoms/video-player.tsx

@@ -17,24 +17,34 @@ export interface VideoPlayerRef {
   pause: () => void
 }
 
-interface VideoPlayerProps {
+export interface VideoPlayerProps {
+  /** The video source URL */
   src: string
-  /**
-   * The format/MIME type of the video.
-   * @default 'video/mp4'
-   */
+  /** The format/MIME type of the video (default: 'video/mp4') */
   format?: string
+  /** Whether the video should be muted */
   muted?: boolean
+  /** URL for the poster image shown before playback */
   poster?: string
+  /** Whether the video should autoplay */
   autoplay?: boolean
+  /** Preload behavior: 'none', 'metadata', or 'auto' */
   preload?: 'none' | 'metadata' | 'auto'
+  /** Whether the video should loop */
   loop?: boolean
+  /** Video width in pixels */
   width?: number
+  /** Video height in pixels */
   height?: number
+  /** Custom play button component */
   playButtonComponent?: React.ReactNode
+  /** Callback when video starts playing */
   onPlay?: () => void
+  /** Callback when video is paused */
   onPause?: () => void
+  /** Callback when video ends */
   onEnded?: () => void
+  /** Callback when video player is ready */
   onReady?: () => void
 }
 
@@ -49,7 +59,7 @@ export const VideoPlayer: React.ForwardRefExoticComponent<
       muted,
       autoplay,
       preload = 'auto',
-      loop = 'false',
+      loop = false,
       width,
       height,
       playButtonComponent,

package/src/components/commerce/add-to-cart.tsx

@@ -10,22 +10,18 @@ import {useShopCartActions} from '../../internal/useShopCartActions'
 import {cn} from '../../lib/utils'
 import {Button} from '../atoms/button'
 
-interface AddToCartButtonProps {
+export interface AddToCartButtonProps {
+  /** Whether the button is disabled */
   disabled?: boolean
+  /** CSS class name */
   className?: string
+  /** Button size variant */
   size?: 'default' | 'sm' | 'lg'
-  /**
-   * The discount codes to apply to the cart.
-   */
+  /** The discount codes to apply to the cart */
   discountCodes?: string[]
-  /**
-   * The GID of the product variant. E.g. `gid://shopify/ProductVariant/456`.
-   */
+  /** The GID of the product variant. E.g. `gid://shopify/ProductVariant/456` */
   productVariantId: string
-
-  /**
-   * The product to add to the cart.
-   */
+  /** The product to add to the cart */
   product?: Product
 }
 

package/src/components/commerce/buy-now.tsx

@@ -8,21 +8,18 @@ import {useShopCartActions} from '../../internal/useShopCartActions'
 import {cn} from '../../lib/utils'
 import {Button} from '../atoms/button'
 
-interface BuyNowButtonProps {
+export interface BuyNowButtonProps {
+  /** Whether the button is disabled */
   disabled?: boolean
+  /** CSS class name */
   className?: string
+  /** Button size variant */
   size?: 'default' | 'sm' | 'lg'
-  /**
-   * The discount code to apply to the purchase.
-   */
+  /** The discount code to apply to the purchase */
   discountCode?: string
-  /**
-   * The GID of the product variant. E.g. `gid://shopify/ProductVariant/456`.
-   */
+  /** The GID of the product variant. E.g. `gid://shopify/ProductVariant/456` */
   productVariantId: string
-  /**
-   * The product to buy now.
-   */
+  /** The product to buy now */
   product?: Product
 }
 

package/src/components/commerce/favorite-button.tsx

@@ -2,13 +2,14 @@ import {Heart} from 'lucide-react'
 
 import {IconButton} from '../atoms/icon-button'
 
-export function FavoriteButton({
-  onClick,
-  filled = false,
-}: {
+export interface FavoriteButtonProps {
+  /** Click handler for toggling favorite state */
   onClick?: () => void
+  /** Whether the product is currently favorited */
   filled?: boolean
-}) {
+}
+
+export function FavoriteButton({onClick, filled = false}: FavoriteButtonProps) {
   return (
     <IconButton
       Icon={Heart}

package/src/components/commerce/merchant-card.tsx

@@ -365,9 +365,13 @@ function MerchantCardHeader({
 }
 
 export interface MerchantCardProps {
+  /** The shop/merchant to display */
   shop: Shop
+  /** Whether the card is tappable to navigate to shop (default: true) */
   touchable?: boolean
+  /** Maximum number of featured product images to show (default: 4) */
   featuredImagesLimit?: number
+  /** Custom content to render inside the card */
   children?: React.ReactNode
 }
 

package/src/components/commerce/product-card.test.tsx

@@ -40,7 +40,7 @@ vi.mock('../../hooks/user/useSavedProductsActions', () => ({
 }))
 
 // Mock formatMoney
-vi.mock('../../lib/formatMoney', () => ({
+vi.mock('../../utils/formatMoney', () => ({
   formatMoney: vi.fn((amount: string, currencyCode: string) => {
     const numAmount = parseFloat(amount)
     return currencyCode === 'USD'

package/src/components/commerce/product-card.tsx

@@ -6,8 +6,8 @@ import {type Product, type ProductVariant} from '@shopify/shop-minis-platform'
 import {useShopNavigation} from '../../hooks/navigation/useShopNavigation'
 import {useSavedProductsActions} from '../../hooks/user/useSavedProductsActions'
 import {ProductReviewStars} from '../../internal/components/product-review-stars'
-import {formatMoney} from '../../lib/formatMoney'
 import {cn} from '../../lib/utils'
+import {formatMoney} from '../../utils/formatMoney'
 import {Image} from '../atoms/image'
 import {ProductVariantPrice} from '../atoms/product-variant-price'
 import {Touchable} from '../atoms/touchable'

package/src/components/commerce/product-link.test.tsx

@@ -28,7 +28,7 @@ vi.mock('../../hooks/user/useSavedProductsActions', () => ({
 }))
 
 // Mock formatMoney
-vi.mock('../../lib/formatMoney', () => ({
+vi.mock('../../utils/formatMoney', () => ({
   formatMoney: vi.fn((amount: string, currencyCode: string) => {
     const numAmount = parseFloat(amount)
     return currencyCode === 'USD'

package/src/components/commerce/product-link.tsx

@@ -7,8 +7,8 @@ import {Slot as SlotPrimitive} from 'radix-ui'
 import {useShopNavigation} from '../../hooks/navigation/useShopNavigation'
 import {useSavedProductsActions} from '../../hooks/user/useSavedProductsActions'
 import {ProductReviewStars} from '../../internal/components/product-review-stars'
-import {formatMoney} from '../../lib/formatMoney'
 import {cn} from '../../lib/utils'
+import {formatMoney} from '../../utils/formatMoney'
 import {Touchable} from '../atoms/touchable'
 import {Card, CardContent, CardAction} from '../ui/card'
 
@@ -226,6 +226,21 @@ function ProductLinkActions({
   )
 }
 
+export interface ProductLinkDocProps {
+  /** The product to display */
+  product: Product
+  /** Hide the favorite/save button */
+  hideFavoriteAction?: boolean
+  /** Callback when the product link is clicked */
+  onClick?: (product: Product) => void
+  /** Hide the review stars */
+  reviewsDisabled?: boolean
+  /** Custom action element to replace the favorite button. Must be provided with `onCustomActionClick`. */
+  customAction?: React.ReactNode
+  /** Callback when the custom action is clicked. Must be provided with `customAction`. */
+  onCustomActionClick?: () => void
+}
+
 export type ProductLinkProps = {
   product: Product
   hideFavoriteAction?: boolean

package/src/components/commerce/quantity-selector.tsx

@@ -5,11 +5,16 @@ import {Minus, Plus} from 'lucide-react'
 import {cn} from '../../lib/utils'
 import {IconButton} from '../atoms/icon-button'
 
-interface QuantitySelectorProps {
+export interface QuantitySelectorProps {
+  /** Current quantity value */
   quantity: number
+  /** Callback when quantity changes */
   onQuantityChange: (quantity: number) => void
+  /** Maximum allowed quantity */
   maxQuantity: number
+  /** Minimum allowed quantity (default: 1) */
   minQuantity?: number
+  /** Whether the selector is disabled */
   disabled?: boolean
 }
 

package/src/components/content/image-content-wrapper.tsx

@@ -1,7 +1,22 @@
 import {ContentWrapper} from '../atoms/content-wrapper'
 import {Image} from '../atoms/image'
 
-type ImageContentWrapperProps = (
+export interface ImageContentWrapperDocProps {
+  /** The public ID of the uploaded image (use this OR externalId) */
+  publicId?: string
+  /** The external ID of the uploaded image (use this OR publicId) */
+  externalId?: string
+  /** Callback when the image loads */
+  onLoad?: () => void
+  /** Image width */
+  width?: number
+  /** Image height */
+  height?: number
+  /** Loading placeholder */
+  Loader?: React.ReactNode | string
+}
+
+export type ImageContentWrapperProps = (
   | {publicId: string; externalId?: never}
   | {externalId: string; publicId?: never}
 ) & {

package/src/components/navigation/minis-router.tsx

@@ -2,7 +2,7 @@ import {BrowserRouter, BrowserRouterProps} from 'react-router'
 
 import {TransitionContainer} from './transition-container'
 
-type ShopMinisRouterProps = BrowserRouterProps & {
+export interface MinisRouterProps extends BrowserRouterProps {
   viewTransitions?: boolean
 }
 
@@ -10,7 +10,7 @@ export function MinisRouter({
   children,
   viewTransitions = false,
   ...props
-}: ShopMinisRouterProps) {
+}: MinisRouterProps) {
   if (viewTransitions) {
     return (
       <BrowserRouter {...props}>

package/src/components/navigation/transition-link.tsx

@@ -4,7 +4,17 @@ import {useHref} from 'react-router'
 
 import {useNavigateWithTransition} from '../../hooks/navigation/useNavigateWithTransition'
 
-type TransitionLinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & {
+export interface TransitionLinkDocProps {
+  /** The target path to navigate to */
+  to: string
+  /** Click handler called before navigation */
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>
+  /** Content to render inside the link */
+  children?: React.ReactNode
+}
+
+export interface TransitionLinkProps
+  extends AnchorHTMLAttributes<HTMLAnchorElement> {
   to: string
 }
 

package/src/components/ui/alert.tsx

@@ -4,6 +4,13 @@ import {cva, type VariantProps} from 'class-variance-authority'
 
 import {cn} from '../../lib/utils'
 
+export interface AlertDocProps {
+  /** Visual style variant */
+  variant?: 'default' | 'destructive'
+  /** Content to render inside */
+  children?: React.ReactNode
+}
+
 const alertVariants = cva(
   'relative w-full rounded-lg border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
   {

package/src/components/ui/badge.tsx

@@ -5,6 +5,15 @@ import {Slot as SlotPrimitive} from 'radix-ui'
 
 import {cn} from '../../lib/utils'
 
+export interface BadgeDocProps {
+  /** Visual style variant */
+  variant?: 'primary' | 'secondary' | 'destructive' | 'outline' | 'none'
+  /** Render as child element instead of span */
+  asChild?: boolean
+  /** Content to render inside */
+  children?: React.ReactNode
+}
+
 const badgeVariants = cva(
   'inline-flex items-center justify-center rounded-md border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none transition-[color,box-shadow] overflow-hidden',
   {

package/src/components/ui/input.tsx

@@ -2,6 +2,21 @@ import * as React from 'react'
 
 import {cn} from '../../lib/utils'
 
+export interface InputDocProps {
+  /** Ref to the input element (use instead of ref) */
+  innerRef?: React.Ref<HTMLInputElement>
+  /** Input type (text, email, password, etc.) */
+  type?: string
+  /** Placeholder text */
+  placeholder?: string
+  /** Current value */
+  value?: string
+  /** Change handler */
+  onChange?: React.ChangeEventHandler<HTMLInputElement>
+  /** Whether the input is disabled */
+  disabled?: boolean
+}
+
 // using the default ref doesn't seem to set the parent's ref object when mounted
 // Since this is a shadCN component, we need to make sure to add back the innerRef prop,
 // whenever the component is updated.

package/src/hooks/storage/useImageUpload.ts

@@ -107,6 +107,19 @@ export const useImageUpload = (): UseImageUploadReturns => {
         throw new Error(links.error.message)
       }
 
+      if (links.mocked) {
+        // Skip upload and return mock data
+        return [
+          {
+            id: 'uploaded-image-id',
+            imageUrl:
+              'https://cdn.shopify.com/s/files/1/0621/0463/3599/files/Mr._Bean_2007_800x800.jpg?v=1763126175',
+            resourceUrl:
+              'https://cdn.shopify.com/s/files/1/0621/0463/3599/files/Mr._Bean_2007_800x800.jpg?v=1763126175',
+          },
+        ]
+      }
+
       // Upload single file to GCS
       const {error: uploadError} = await uploadFileToGCS(
         processedImageParams,

package/src/mocks.ts

@@ -6,28 +6,50 @@ import {
 } from '@shopify/shop-minis-platform'
 import {ShopActions} from '@shopify/shop-minis-platform/actions'
 
+const SAMPLE_IMAGE_NAMES = [
+  'garnished.jpeg',
+  'bath.jpeg',
+  'teapot.jpg',
+  'shoes.jpeg',
+]
+
+// Simple hash function to get a deterministic index from a string
+const hashString = (str: string): number => {
+  let hash = 0
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash << 5) - hash + str.charCodeAt(i)
+    hash |= 0
+  }
+  return Math.abs(hash)
+}
+
 // Helper functions for common data structures
 export const createProduct = (
   id: string,
   title: string,
   price = '99.99',
   compareAtPrice?: string
-): Product => ({
-  id,
-  title,
-  price: {amount: price, currencyCode: 'USD'},
-  ...(compareAtPrice && {
-    compareAtPrice: {amount: compareAtPrice, currencyCode: 'USD'},
-  }),
-  reviewAnalytics: {averageRating: 4.5, reviewCount: 10},
-  shop: createShop('shop1', 'Mock Shop'),
-  defaultVariantId: `variant-${id}`,
-  isFavorited: false,
-  featuredImage: {
-    url: `https://cdn.shopify.com/static/sample-images/teapot.jpg`,
-    altText: title,
-  },
-})
+): Product => {
+  const imageIndex = hashString(id) % SAMPLE_IMAGE_NAMES.length
+  const imageName = SAMPLE_IMAGE_NAMES[imageIndex]
+
+  return {
+    id,
+    title,
+    price: {amount: price, currencyCode: 'USD'},
+    ...(compareAtPrice && {
+      compareAtPrice: {amount: compareAtPrice, currencyCode: 'USD'},
+    }),
+    reviewAnalytics: {averageRating: 4.5, reviewCount: 10},
+    shop: createShop('shop1', 'Mock Shop'),
+    defaultVariantId: `variant-${id}`,
+    isFavorited: false,
+    featuredImage: {
+      url: `https://cdn.shopify.com/static/sample-images/${imageName}`,
+      altText: title,
+    },
+  }
+}
 
 export const createShop = (
   id: string,
@@ -202,7 +224,11 @@ function makeMockMethod<K extends keyof ShopActions>(
 ): ShopActions[K] {
   return ((params: Parameters<ShopActions[K]>[0]) => {
     logMockAction(String(key), params)
-    return Promise.resolve({ok: true as const, data: result})
+    return Promise.resolve({
+      ok: true as const,
+      data: result,
+      mocked: true,
+    })
   }) as ShopActions[K]
 }
 
@@ -249,6 +275,7 @@ export function makeMockActions(): ShopActions {
     navigateToOrder: undefined,
     navigateToCheckout: undefined,
     createImageUploadLink: {
+      // This action is mocked in the actual hook. See `useImageUpload` for more details.
       targets: [
         {
           url: 'https://example.com/upload',
@@ -262,7 +289,9 @@ export function makeMockActions(): ShopActions {
         {
           id: 'file-123',
           fileStatus: 'READY',
-          image: {url: 'https://example.com/image.jpg'},
+          image: {
+            url: 'https://example.com/image.jpg',
+          },
         },
       ],
     },
@@ -556,7 +585,7 @@ export const injectMocks = ({force}: {force?: boolean} = {}) => {
     window.minisSDK = makeMockActions()
     window.minisParams = {
       handle: 'mock-handle',
-      initialUrl: '/mock-initial-url',
+      initialUrl: '/',
       platform: 'web',
     }
   }