@shopify/shop-minis-react 0.3.2 → 0.4.0

package/src/internal/components/product-review-stars.tsx

@@ -0,0 +1,113 @@
+import * as React from 'react'
+
+import {Star, StarHalf} from 'lucide-react'
+
+import {cn} from '../../lib/utils'
+import {formatReviewCount, normalizeRating} from '../../utils/merchant-card'
+
+const starSizeClasses = {
+  sm: 'h-3 w-3',
+  md: 'h-4 w-4',
+  lg: 'h-5 w-5',
+} as const
+
+const textSizeClasses = {
+  sm: 'text-xs',
+  md: 'text-sm',
+  lg: 'text-base',
+} as const
+
+export interface ProductReviewStarsProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Average rating value (0-5)
+   */
+  averageRating: number
+  /**
+   * Total number of reviews
+   */
+  reviewCount?: number | null
+  /**
+   * Custom color for filled star
+   * @default 'var(--grayscale-d100)' (black)
+   */
+  filledStarColor?: string
+  /**
+   * Custom color for empty star
+   * @default 'var(--grayscale-l20)' (light gray)
+   */
+  emptyStarColor?: string
+  /**
+   * Size of the stars
+   * @default 'sm'
+   */
+  size?: 'sm' | 'md' | 'lg'
+}
+
+export const ProductReviewStars = React.forwardRef<
+  HTMLDivElement,
+  ProductReviewStarsProps
+>(
+  (
+    {
+      averageRating,
+      reviewCount,
+      size = 'sm',
+      filledStarColor = 'var(--grayscale-d100)',
+      emptyStarColor = 'var(--grayscale-l20)',
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    const normalizedRating = Math.min(5, normalizeRating(averageRating))
+    const filledStars = Math.floor(normalizedRating)
+    const remainder = normalizedRating % 1
+
+    return (
+      <div
+        ref={ref}
+        className={cn('flex items-center', className)}
+        data-slot="product-review-stars"
+        {...props}
+      >
+        <div className="relative">
+          <div className="flex">
+            {Array.from({length: 5}, (_, i) => (
+              <Star
+                key={i}
+                className={cn(starSizeClasses[size])}
+                style={{fill: emptyStarColor}}
+                strokeWidth={0}
+              />
+            ))}
+          </div>
+          <div className="flex absolute top-0 left-0">
+            {Array.from({length: filledStars}, (_, i) => (
+              <Star
+                key={i}
+                className={cn(starSizeClasses[size])}
+                style={{fill: filledStarColor}}
+                strokeWidth={0}
+              />
+            ))}
+            {remainder >= 0.5 && (
+              <StarHalf
+                className={cn(starSizeClasses[size])}
+                style={{fill: filledStarColor}}
+                strokeWidth={0}
+              />
+            )}
+          </div>
+        </div>
+        {reviewCount && (
+          <span className={cn(textSizeClasses[size], 'ml-1')}>
+            ({formatReviewCount(reviewCount)})
+          </span>
+        )}
+      </div>
+    )
+  }
+)
+
+ProductReviewStars.displayName = 'ProductReviewStars'

package/src/internal/reactQuery/MinisQueryProvider.test.tsx

@@ -0,0 +1,38 @@
+import {QueryClient} from '@tanstack/react-query'
+import {renderHook} from '@testing-library/react'
+import {describe, expect, it} from 'vitest'
+
+import {MinisQueryProvider} from './MinisQueryProvider'
+import {useShopMinisQueryClient} from './queryClient'
+
+describe('MinisQueryProvider', () => {
+  it('provides QueryClient to children', () => {
+    const {result} = renderHook(() => useShopMinisQueryClient(), {
+      wrapper: MinisQueryProvider,
+    })
+
+    expect(result.current).toBeInstanceOf(QueryClient)
+  })
+
+  it('allows hooks to work within provider', () => {
+    const {result} = renderHook(() => useShopMinisQueryClient(), {
+      wrapper: MinisQueryProvider,
+    })
+
+    // Should not throw
+    expect(() => result.current).not.toThrow()
+  })
+
+  it('provides consistent QueryClient across renders', () => {
+    const {result, rerender} = renderHook(() => useShopMinisQueryClient(), {
+      wrapper: MinisQueryProvider,
+    })
+
+    const firstClient = result.current
+    rerender()
+    const secondClient = result.current
+
+    // Same instance across re-renders
+    expect(firstClient).toBe(secondClient)
+  })
+})

package/src/internal/reactQuery/MinisQueryProvider.tsx

@@ -0,0 +1,16 @@
+import React, {useMemo} from 'react'
+
+import {
+  createShopMinisQueryClient,
+  ShopMinisQueryClientContext,
+} from './queryClient'
+
+export function MinisQueryProvider({children}: {children: React.ReactNode}) {
+  const queryClient = useMemo(() => createShopMinisQueryClient(), [])
+
+  return (
+    <ShopMinisQueryClientContext.Provider value={queryClient}>
+      {children}
+    </ShopMinisQueryClientContext.Provider>
+  )
+}

package/src/internal/reactQuery/index.ts

@@ -0,0 +1,8 @@
+export {
+  ShopMinisQueryClientContext,
+  useShopMinisQueryClient,
+  createShopMinisQueryClient,
+} from './queryClient'
+export {MinisQueryProvider} from './MinisQueryProvider'
+export {useShopActionQuery} from './useShopActionQuery'
+export {useShopActionInfiniteQuery} from './useShopActionInfiniteQuery'

package/src/internal/reactQuery/queryClient.test.tsx

@@ -0,0 +1,91 @@
+import React from 'react'
+
+import {QueryClient} from '@tanstack/react-query'
+import {renderHook} from '@testing-library/react'
+import {describe, expect, it} from 'vitest'
+
+import {
+  createShopMinisQueryClient,
+  ShopMinisQueryClientContext,
+  useShopMinisQueryClient,
+} from './queryClient'
+
+describe('queryClient', () => {
+  describe('createShopMinisQueryClient', () => {
+    it('creates a QueryClient instance', () => {
+      const client = createShopMinisQueryClient()
+
+      expect(client).toBeInstanceOf(QueryClient)
+    })
+
+    it('creates isolated QueryClient instances', () => {
+      const client1 = createShopMinisQueryClient()
+      const client2 = createShopMinisQueryClient()
+
+      // Each call creates a new instance
+      expect(client1).not.toBe(client2)
+    })
+
+    it('has caching disabled by default', () => {
+      const client = createShopMinisQueryClient()
+
+      const defaults = client.getDefaultOptions()
+
+      expect(defaults.queries?.staleTime).toBe(0)
+      expect(defaults.queries?.gcTime).toBe(0)
+    })
+
+    it('has retry and refetchOnWindowFocus configured', () => {
+      const client = createShopMinisQueryClient()
+
+      const defaults = client.getDefaultOptions()
+
+      expect(defaults.queries?.retry).toBe(1)
+      expect(defaults.queries?.refetchOnWindowFocus).toBe(false)
+    })
+  })
+
+  describe('useShopMinisQueryClient', () => {
+    it('throws error when used outside provider', () => {
+      expect(() => {
+        renderHook(() => useShopMinisQueryClient())
+      }).toThrow(
+        'Shop Minis hooks must be used within <MinisContainer> or <MinisQueryProvider>. ' +
+          'Wrap your component tree with one of these providers.'
+      )
+    })
+
+    it('returns QueryClient when used within provider', () => {
+      const client = createShopMinisQueryClient()
+      const wrapper = ({children}: {children: React.ReactNode}) => (
+        <ShopMinisQueryClientContext.Provider value={client}>
+          {children}
+        </ShopMinisQueryClientContext.Provider>
+      )
+
+      const {result} = renderHook(() => useShopMinisQueryClient(), {wrapper})
+
+      expect(result.current).toBe(client)
+      expect(result.current).toBeInstanceOf(QueryClient)
+    })
+
+    it('returns the same client instance across re-renders', () => {
+      const client = createShopMinisQueryClient()
+      const wrapper = ({children}: {children: React.ReactNode}) => (
+        <ShopMinisQueryClientContext.Provider value={client}>
+          {children}
+        </ShopMinisQueryClientContext.Provider>
+      )
+
+      const {result, rerender} = renderHook(() => useShopMinisQueryClient(), {
+        wrapper,
+      })
+
+      const firstClient = result.current
+      rerender()
+      const secondClient = result.current
+
+      expect(firstClient).toBe(secondClient)
+    })
+  })
+})

package/src/internal/reactQuery/queryClient.ts

@@ -0,0 +1,43 @@
+import {createContext, useContext} from 'react'
+
+import {QueryClient} from '@tanstack/react-query'
+
+/**
+ * Custom QueryClient context for Shop Minis SDK
+ * This ensures our SDK always uses its own QueryClient,
+ * even if the parent app has their own QueryClientProvider
+ */
+export const ShopMinisQueryClientContext = createContext<QueryClient | null>(
+  null
+)
+
+export function useShopMinisQueryClient(): QueryClient {
+  const client = useContext(ShopMinisQueryClientContext)
+  if (!client) {
+    throw new Error(
+      'Shop Minis hooks must be used within <MinisContainer> or <MinisQueryProvider>. ' +
+        'Wrap your component tree with one of these providers.'
+    )
+  }
+  return client
+}
+
+/**
+ * Create a QueryClient instance for Shop Minis SDK
+ * Isolated from any parent app's QueryClient
+ *
+ * Caching is disabled by default since Apollo provides the cache layer.
+ * React Query only provides request deduplication and state management.
+ */
+export function createShopMinisQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 0, // Data is immediately stale
+        gcTime: 0, // Don't keep in cache after component unmounts
+        retry: 1,
+        refetchOnWindowFocus: false,
+      },
+    },
+  })
+}

package/src/internal/reactQuery/useShopActionInfiniteQuery.test.tsx

@@ -0,0 +1,357 @@
+import React from 'react'
+
+import {renderHook, waitFor, act} from '@testing-library/react'
+import {describe, expect, it, vi} from 'vitest'
+
+import {MinisQueryProvider} from './MinisQueryProvider'
+import {useShopActionInfiniteQuery} from './useShopActionInfiniteQuery'
+
+describe('useShopActionInfiniteQuery', () => {
+  const wrapper = ({children}: {children: React.ReactNode}) => (
+    <MinisQueryProvider>{children}</MinisQueryProvider>
+  )
+
+  describe('Data Fetching', () => {
+    it('fetches and returns flattened array data', async () => {
+      const mockAction = vi.fn().mockResolvedValue({
+        ok: true,
+        data: {
+          data: [{id: '1'}, {id: '2'}],
+          pageInfo: {hasNextPage: false, endCursor: null},
+        },
+      })
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-array'], mockAction, {}),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false)
+      })
+
+      expect(result.current.data).toEqual([{id: '1'}, {id: '2'}])
+      expect(result.current.hasNextPage).toBe(false)
+      expect(mockAction).toHaveBeenCalledWith({})
+    })
+
+    it('handles non-array data by returning it directly', async () => {
+      const mockAction = vi.fn().mockResolvedValue({
+        ok: true,
+        data: {
+          data: {items: [{id: '1'}]},
+          pageInfo: {hasNextPage: false, endCursor: null},
+        },
+      })
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-nonarray'], mockAction, {}),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false)
+      })
+
+      // Non-array data is returned as-is from the first page
+      expect(result.current.data).toEqual({items: [{id: '1'}]})
+    })
+
+    it('returns null when data is null', async () => {
+      const mockAction = vi.fn().mockResolvedValue({
+        ok: true,
+        data: {
+          data: null,
+          pageInfo: {hasNextPage: false, endCursor: null},
+        },
+      })
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-null-data'], mockAction, {}),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false)
+      })
+
+      expect(result.current.data).toBeNull()
+    })
+  })
+
+  describe('Pagination Logic', () => {
+    it('appends data when fetching more pages', async () => {
+      const page1 = [{id: '1'}]
+      const page2 = [{id: '2'}]
+
+      const mockAction = vi
+        .fn()
+        .mockResolvedValueOnce({
+          ok: true,
+          data: {
+            data: page1,
+            pageInfo: {hasNextPage: true, endCursor: 'cursor1'},
+          },
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          data: {
+            data: page2,
+            pageInfo: {hasNextPage: false, endCursor: null},
+          },
+        })
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-pagination'], mockAction, {}),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual(page1)
+        expect(result.current.hasNextPage).toBe(true)
+      })
+
+      // Fetch more
+      await act(async () => {
+        await result.current.fetchMore()
+      })
+
+      // Data should be flattened and appended
+      await waitFor(() => {
+        expect(result.current.data).toEqual([...page1, ...page2])
+      })
+
+      expect(result.current.hasNextPage).toBe(false)
+      expect(mockAction).toHaveBeenCalledTimes(2)
+    })
+
+    it('passes cursor to subsequent pages', async () => {
+      const mockAction = vi
+        .fn()
+        .mockResolvedValueOnce({
+          ok: true,
+          data: {
+            data: [{id: '1'}],
+            pageInfo: {hasNextPage: true, endCursor: 'cursor1'},
+          },
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          data: {
+            data: [{id: '2'}],
+            pageInfo: {hasNextPage: false, endCursor: null},
+          },
+        })
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-cursor'], mockAction, {}),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual([{id: '1'}])
+        expect(result.current.hasNextPage).toBe(true)
+      })
+
+      await act(async () => {
+        await result.current.fetchMore()
+      })
+
+      // Second call should include the cursor
+      expect(mockAction).toHaveBeenNthCalledWith(2, {after: 'cursor1'})
+    })
+
+    it('preserves other params when fetching more', async () => {
+      const mockAction = vi
+        .fn()
+        .mockResolvedValueOnce({
+          ok: true,
+          data: {
+            data: [{id: '1'}],
+            pageInfo: {hasNextPage: true, endCursor: 'cursor1'},
+          },
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          data: {
+            data: [{id: '2'}],
+            pageInfo: {hasNextPage: false, endCursor: null},
+          },
+        })
+
+      const {result} = renderHook(
+        () =>
+          useShopActionInfiniteQuery(['test-params'], mockAction, {
+            query: 'shoes',
+            fetchPolicy: 'cache-first',
+          }),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual([{id: '1'}])
+        expect(result.current.hasNextPage).toBe(true)
+      })
+
+      await act(async () => {
+        await result.current.fetchMore()
+      })
+
+      // Should preserve original params and add cursor
+      expect(mockAction).toHaveBeenNthCalledWith(2, {
+        query: 'shoes',
+        fetchPolicy: 'cache-first',
+        after: 'cursor1',
+      })
+    })
+  })
+
+  describe('Error Handling', () => {
+    it('handles action errors', async () => {
+      const mockAction = vi.fn().mockRejectedValue(new Error('API Error'))
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-api-error'], mockAction, {}),
+        {wrapper}
+      )
+
+      // Wait for loading to complete (after retries)
+      await waitFor(
+        () => {
+          expect(result.current.loading).toBe(false)
+        },
+        {timeout: 3000}
+      )
+
+      expect(result.current.data).toBeNull()
+      expect(result.current.error).toBeInstanceOf(Error)
+      expect(result.current.error?.message).toBe('API Error')
+    })
+  })
+
+  describe('Skip Parameter', () => {
+    it('does not fetch when skip is true', async () => {
+      const mockAction = vi.fn()
+
+      renderHook(
+        () =>
+          useShopActionInfiniteQuery(
+            ['test-skip-inf'],
+            mockAction,
+            {},
+            {skip: true}
+          ),
+        {wrapper}
+      )
+
+      await new Promise(resolve => setTimeout(resolve, 100))
+
+      expect(mockAction).not.toHaveBeenCalled()
+    })
+
+    it('fetches when skip is false', async () => {
+      const mockAction = vi.fn().mockResolvedValue({
+        ok: true,
+        data: {
+          data: [{id: 'noskip'}],
+          pageInfo: {hasNextPage: false, endCursor: null},
+        },
+      })
+
+      const {result} = renderHook(
+        () =>
+          useShopActionInfiniteQuery(
+            ['test-noskip-fetch'],
+            mockAction,
+            {},
+            {skip: false}
+          ),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual([{id: 'noskip'}])
+      })
+
+      expect(mockAction).toHaveBeenCalled()
+    })
+  })
+
+  describe('API Contract', () => {
+    it('returns expected shape', async () => {
+      const mockAction = vi.fn().mockResolvedValue({
+        ok: true,
+        data: {
+          data: [{id: 'contract'}],
+          pageInfo: {hasNextPage: false, endCursor: null},
+        },
+      })
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-contract-inf'], mockAction, {}),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false)
+      })
+
+      // Verify all expected properties exist
+      expect(result.current).toHaveProperty('data')
+      expect(result.current).toHaveProperty('loading')
+      expect(result.current).toHaveProperty('error')
+      expect(result.current).toHaveProperty('hasNextPage')
+      expect(result.current).toHaveProperty('fetchMore')
+      expect(result.current).toHaveProperty('refetch')
+
+      // Verify types
+      expect(typeof result.current.loading).toBe('boolean')
+      expect(typeof result.current.hasNextPage).toBe('boolean')
+      expect(typeof result.current.fetchMore).toBe('function')
+      expect(typeof result.current.refetch).toBe('function')
+    })
+  })
+
+  describe('hasNextPage Logic', () => {
+    it('sets hasNextPage based on pageInfo', async () => {
+      const mockAction = vi.fn().mockResolvedValue({
+        ok: true,
+        data: {
+          data: [{id: '1'}],
+          pageInfo: {hasNextPage: true, endCursor: 'cursor1'},
+        },
+      })
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-hasnext'], mockAction, {}),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.data).toEqual([{id: '1'}])
+        expect(result.current.hasNextPage).toBe(true)
+      })
+    })
+
+    it('returns false when no more pages', async () => {
+      const mockAction = vi.fn().mockResolvedValue({
+        ok: true,
+        data: {
+          data: [{id: '1'}],
+          pageInfo: {hasNextPage: false, endCursor: null},
+        },
+      })
+
+      const {result} = renderHook(
+        () => useShopActionInfiniteQuery(['test-nonext'], mockAction, {}),
+        {wrapper}
+      )
+
+      await waitFor(() => {
+        expect(result.current.loading).toBe(false)
+      })
+
+      expect(result.current.hasNextPage).toBe(false)
+    })
+  })
+})