@shopify/shop-minis-react 0.4.16 → 0.4.17

package/dist/utils/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sources":["../../src/utils/image.ts"],"sourcesContent":["import {toUint8Array} from 'js-base64'\nimport {thumbHashToDataURL} from 'thumbhash'\n\n/**\n * Converts a thumbhash string to a data URL for use as an image placeholder\n * @param thumbhash Base64 encoded thumbhash string\n * @returns Data URL that can be used as image source or undefined if conversion fails\n */\nexport function getThumbhashDataURL(thumbhash?: string): string | undefined {\n  if (!thumbhash) return\n\n  try {\n    const thumbhashArray = toUint8Array(thumbhash)\n    return thumbHashToDataURL(thumbhashArray)\n  } catch (error) {\n    console.warn('Failed to decode thumbhash to data URL', error)\n    return undefined\n  }\n}\n\n/** Converts a file to a data URI\n * @param file The file to convert\n * @returns A promise that resolves to the data URI string\n */\nexport function fileToDataUri(file: File): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const reader = new FileReader()\n    reader.onloadend = () => resolve(reader.result as string)\n    reader.onerror = reject\n    reader.readAsDataURL(file)\n  })\n}\n\nconst ImageSizes = {\n  xxsUrl: 32,\n  xsUrl: 64,\n  sUrl: 128,\n  xxsmUrl: 256,\n  xsmUrl: 384,\n  smUrl: 512,\n  mUrl: 640,\n  lUrl: 1080,\n  xlUrl: 2048,\n} as const\n\ntype Key = keyof typeof ImageSizes\n\n/**\n * Acceptable offset for image sizes. An image could use the size that is within this offset.\n */\nconst offsetPercentage = 0.05\n\nconst sortedImageSizes = Object.entries(ImageSizes).sort(\n  ([, firstSize], [, secondSize]) => firstSize - secondSize\n)\n\nconst getImageSizeKeyWithSize = (size: number): Key => {\n  for (const [key, imgSize] of sortedImageSizes) {\n    const upperBoundSize = imgSize + imgSize * offsetPercentage\n    if (size <= upperBoundSize) return key as Key\n  }\n\n  return 'xlUrl'\n}\n\nconst resizeImage = (imageUrl: string, width: number) => {\n  const pattern = new RegExp(/\\?+/g)\n  const delimiter = pattern.test(imageUrl) ? '&' : '?'\n  return `${imageUrl}${delimiter}width=${width}`\n}\n\n/**\n * Optimizes Shopify CDN image URLs by adding a width parameter based on screen size\n * @param url The image URL to optimize\n * @returns The optimized URL with width parameter if it's a Shopify CDN image, otherwise returns the original URL\n */\n\nexport const getResizedImageUrl = (url?: string): string => {\n  if (!url) return ''\n\n  // Only process Shopify CDN images\n  if (!url.startsWith('https://cdn.shopify.com')) {\n    return url\n  }\n\n  const width = window.innerWidth ?? screen.width\n\n  const key = getImageSizeKeyWithSize(width)\n\n  return resizeImage(url, ImageSizes[key])\n}\n"],"names":["getThumbhashDataURL","thumbhash","thumbhashArray","toUint8Array","thumbHashToDataURL","error","fileToDataUri","file","resolve","reject","reader","ImageSizes","offsetPercentage","sortedImageSizes","firstSize","secondSize","getImageSizeKeyWithSize","size","key","imgSize","upperBoundSize","resizeImage","imageUrl","width","delimiter","getResizedImageUrl","url"],"mappings":";;AAQO,SAASA,EAAoBC,GAAwC;AAC1E,MAAKA;AAED,QAAA;AACI,YAAAC,IAAiBC,EAAaF,CAAS;AAC7C,aAAOG,EAAmBF,CAAc;AAAA,aACjCG,GAAO;AACN,cAAA,KAAK,0CAA0CA,CAAK;AACrD;AAAA,IAAA;AAEX;AAMO,SAASC,EAAcC,GAA6B;AACzD,SAAO,IAAI,QAAQ,CAACC,GAASC,MAAW;AAChC,UAAAC,IAAS,IAAI,WAAW;AAC9B,IAAAA,EAAO,YAAY,MAAMF,EAAQE,EAAO,MAAgB,GACxDA,EAAO,UAAUD,GACjBC,EAAO,cAAcH,CAAI;AAAA,EAAA,CAC1B;AACH;AAEA,MAAMI,IAAa;AAAA,EACjB,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AACT,GAOMC,IAAmB,MAEnBC,IAAmB,OAAO,QAAQF,CAAU,EAAE;AAAA,EAClD,CAAC,CAAG,EAAAG,CAAS,GAAG,GAAGC,CAAU,MAAMD,IAAYC;AACjD,GAEMC,IAA0B,CAACC,MAAsB;AACrD,aAAW,CAACC,GAAKC,CAAO,KAAKN,GAAkB;AACvC,UAAAO,IAAiBD,IAAUA,IAAUP;AACvC,QAAAK,KAAQG,EAAuB,QAAAF;AAAA,EAAA;AAG9B,SAAA;AACT,GAEMG,IAAc,CAACC,GAAkBC,MAAkB;AAEvD,QAAMC,IADU,IAAI,OAAO,MAAM,EACP,KAAKF,CAAQ,IAAI,MAAM;AACjD,SAAO,GAAGA,CAAQ,GAAGE,CAAS,SAASD,CAAK;AAC9C,GAQaE,IAAqB,CAACC,MAAyB;AACtD,MAAA,CAACA,EAAY,QAAA;AAGjB,MAAI,CAACA,EAAI,WAAW,yBAAyB;AACpC,WAAAA;AAGH,QAAAH,IAAQ,OAAO,cAAc,OAAO,OAEpCL,IAAMF,EAAwBO,CAAK;AAEzC,SAAOF,EAAYK,GAAKf,EAAWO,CAAG,CAAC;AACzC;"}
+{"version":3,"file":"image.js","sources":["../../src/utils/image.ts"],"sourcesContent":["import {toUint8Array} from 'js-base64'\nimport {thumbHashToDataURL} from 'thumbhash'\n\n/**\n * Converts a thumbhash string to a data URL for use as an image placeholder\n * @param thumbhash Base64 encoded thumbhash string\n * @returns Data URL that can be used as image source or undefined if conversion fails\n */\nexport function getThumbhashDataURL(thumbhash?: string): string | undefined {\n  if (!thumbhash) return\n\n  try {\n    const thumbhashArray = toUint8Array(thumbhash)\n    return thumbHashToDataURL(thumbhashArray)\n  } catch (error) {\n    console.warn('Failed to decode thumbhash to data URL', error)\n    return undefined\n  }\n}\n\n/**\n * Converts a data URL to a Blob\n * @param dataURL The data URL to convert\n * @returns A Blob object\n */\nexport function dataURLToBlob(dataURL: string): Blob {\n  const [header, base64Data] = dataURL.split(',')\n  const mimeMatch = header.match(/:(.*?);/)\n  const mime = mimeMatch ? mimeMatch[1] : 'image/png'\n  const binary = atob(base64Data)\n  const array = new Uint8Array(binary.length)\n  for (let i = 0; i < binary.length; i++) {\n    array[i] = binary.charCodeAt(i)\n  }\n  return new Blob([array], {type: mime})\n}\n\n/**\n * Converts a thumbhash string to a blob URL for use as an image placeholder\n * This is useful when CSP restrictions prevent data URLs\n * @param thumbhash Base64 encoded thumbhash string\n * @returns Blob URL that can be used as image source or undefined if conversion fails\n */\nexport function getThumbhashBlobURL(thumbhash?: string): string | undefined {\n  if (!thumbhash) return\n\n  try {\n    const dataURL = getThumbhashDataURL(thumbhash)\n    if (!dataURL) return\n\n    const blob = dataURLToBlob(dataURL)\n    return URL.createObjectURL(blob)\n  } catch (error) {\n    console.warn('Failed to create thumbhash blob URL', error)\n    return undefined\n  }\n}\n\n/** Converts a file to a data URI\n * @param file The file to convert\n * @returns A promise that resolves to the data URI string\n */\nexport function fileToDataUri(file: File): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const reader = new FileReader()\n    reader.onloadend = () => resolve(reader.result as string)\n    reader.onerror = reject\n    reader.readAsDataURL(file)\n  })\n}\n\nconst ImageSizes = {\n  xxsUrl: 32,\n  xsUrl: 64,\n  sUrl: 128,\n  xxsmUrl: 256,\n  xsmUrl: 384,\n  smUrl: 512,\n  mUrl: 640,\n  lUrl: 1080,\n  xlUrl: 2048,\n} as const\n\ntype Key = keyof typeof ImageSizes\n\n/**\n * Acceptable offset for image sizes. An image could use the size that is within this offset.\n */\nconst offsetPercentage = 0.05\n\nconst sortedImageSizes = Object.entries(ImageSizes).sort(\n  ([, firstSize], [, secondSize]) => firstSize - secondSize\n)\n\nconst getImageSizeKeyWithSize = (size: number): Key => {\n  for (const [key, imgSize] of sortedImageSizes) {\n    const upperBoundSize = imgSize + imgSize * offsetPercentage\n    if (size <= upperBoundSize) return key as Key\n  }\n\n  return 'xlUrl'\n}\n\nconst resizeImage = (imageUrl: string, width: number) => {\n  const pattern = new RegExp(/\\?+/g)\n  const delimiter = pattern.test(imageUrl) ? '&' : '?'\n  return `${imageUrl}${delimiter}width=${width}`\n}\n\n/**\n * Optimizes Shopify CDN image URLs by adding a width parameter based on screen size\n * @param url The image URL to optimize\n * @returns The optimized URL with width parameter if it's a Shopify CDN image, otherwise returns the original URL\n */\n\nexport const getResizedImageUrl = (url?: string): string => {\n  if (!url) return ''\n\n  // Only process Shopify CDN images\n  if (!url.startsWith('https://cdn.shopify.com')) {\n    return url\n  }\n\n  const width = window.innerWidth ?? screen.width\n\n  const key = getImageSizeKeyWithSize(width)\n\n  return resizeImage(url, ImageSizes[key])\n}\n"],"names":["getThumbhashDataURL","thumbhash","thumbhashArray","toUint8Array","thumbHashToDataURL","error","dataURLToBlob","dataURL","header","base64Data","mimeMatch","mime","binary","array","i","getThumbhashBlobURL","blob","fileToDataUri","file","resolve","reject","reader","ImageSizes","offsetPercentage","sortedImageSizes","firstSize","secondSize","getImageSizeKeyWithSize","size","key","imgSize","upperBoundSize","resizeImage","imageUrl","width","delimiter","getResizedImageUrl","url"],"mappings":";;AAQO,SAASA,EAAoBC,GAAwC;AAC1E,MAAKA;AAED,QAAA;AACI,YAAAC,IAAiBC,EAAaF,CAAS;AAC7C,aAAOG,EAAmBF,CAAc;AAAA,aACjCG,GAAO;AACN,cAAA,KAAK,0CAA0CA,CAAK;AACrD;AAAA,IAAA;AAEX;AAOO,SAASC,EAAcC,GAAuB;AACnD,QAAM,CAACC,GAAQC,CAAU,IAAIF,EAAQ,MAAM,GAAG,GACxCG,IAAYF,EAAO,MAAM,SAAS,GAClCG,IAAOD,IAAYA,EAAU,CAAC,IAAI,aAClCE,IAAS,KAAKH,CAAU,GACxBI,IAAQ,IAAI,WAAWD,EAAO,MAAM;AAC1C,WAASE,IAAI,GAAGA,IAAIF,EAAO,QAAQE;AACjC,IAAAD,EAAMC,CAAC,IAAIF,EAAO,WAAWE,CAAC;AAEzB,SAAA,IAAI,KAAK,CAACD,CAAK,GAAG,EAAC,MAAMF,GAAK;AACvC;AAQO,SAASI,EAAoBd,GAAwC;AAC1E,MAAKA;AAED,QAAA;AACI,YAAAM,IAAUP,EAAoBC,CAAS;AAC7C,UAAI,CAACM,EAAS;AAER,YAAAS,IAAOV,EAAcC,CAAO;AAC3B,aAAA,IAAI,gBAAgBS,CAAI;AAAA,aACxBX,GAAO;AACN,cAAA,KAAK,uCAAuCA,CAAK;AAClD;AAAA,IAAA;AAEX;AAMO,SAASY,EAAcC,GAA6B;AACzD,SAAO,IAAI,QAAQ,CAACC,GAASC,MAAW;AAChC,UAAAC,IAAS,IAAI,WAAW;AAC9B,IAAAA,EAAO,YAAY,MAAMF,EAAQE,EAAO,MAAgB,GACxDA,EAAO,UAAUD,GACjBC,EAAO,cAAcH,CAAI;AAAA,EAAA,CAC1B;AACH;AAEA,MAAMI,IAAa;AAAA,EACjB,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AACT,GAOMC,IAAmB,MAEnBC,IAAmB,OAAO,QAAQF,CAAU,EAAE;AAAA,EAClD,CAAC,CAAG,EAAAG,CAAS,GAAG,GAAGC,CAAU,MAAMD,IAAYC;AACjD,GAEMC,IAA0B,CAACC,MAAsB;AACrD,aAAW,CAACC,GAAKC,CAAO,KAAKN,GAAkB;AACvC,UAAAO,IAAiBD,IAAUA,IAAUP;AACvC,QAAAK,KAAQG,EAAuB,QAAAF;AAAA,EAAA;AAG9B,SAAA;AACT,GAEMG,IAAc,CAACC,GAAkBC,MAAkB;AAEvD,QAAMC,IADU,IAAI,OAAO,MAAM,EACP,KAAKF,CAAQ,IAAI,MAAM;AACjD,SAAO,GAAGA,CAAQ,GAAGE,CAAS,SAASD,CAAK;AAC9C,GAQaE,IAAqB,CAACC,MAAyB;AACtD,MAAA,CAACA,EAAY,QAAA;AAGjB,MAAI,CAACA,EAAI,WAAW,yBAAyB;AACpC,WAAAA;AAGH,QAAAH,IAAQ,OAAO,cAAc,OAAO,OAEpCL,IAAMF,EAAwBO,CAAK;AAEzC,SAAOF,EAAYK,GAAKf,EAAWO,CAAG,CAAC;AACzC;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shopify/shop-minis-react",
   "license": "SEE LICENSE IN LICENSE.txt",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "sideEffects": false,
   "type": "module",
   "engines": {

package/src/components/atoms/alert-dialog.tsx

@@ -20,11 +20,11 @@ export interface AlertDialogAtomProps {
   /** The description text shown in the alert dialog body */
   description: string
   /** The text shown in the cancel button */
-  cancelButtonText: string
+  cancelButtonText?: string
   /** The text shown in the confirmation button */
-  confirmationButtonText: string
+  confirmationButtonText?: string
   /** Whether the alert dialog is open */
-  open: boolean
+  open?: boolean
   /** Callback fired when the alert dialog open state changes */
   onOpenChange: (open: boolean) => void
   /** Callback fired when the confirmation button is clicked */

package/src/components/atoms/button.tsx

@@ -7,6 +7,28 @@ import {BaseButton, buttonVariants} from '../ui/button'
 
 import {Touchable} from './touchable'
 
+export interface ButtonDocProps {
+  /** Visual style variant */
+  variant?:
+    | 'default'
+    | 'secondary'
+    | 'destructive'
+    | 'outline'
+    | 'ghost'
+    | 'link'
+    | 'icon'
+  /** Button size */
+  size?: 'default' | 'sm' | 'lg' | 'icon'
+  /** Click handler */
+  onClick?: React.MouseEventHandler<HTMLButtonElement>
+  /** Prevent click from bubbling to parent elements */
+  stopPropagation?: boolean
+  /** Whether the button is disabled */
+  disabled?: boolean
+  /** Button content */
+  children?: React.ReactNode
+}
+
 export function Button({
   className,
   variant,

package/src/components/atoms/icon-button.tsx

@@ -4,6 +4,21 @@ import {cn} from '../../lib/utils'
 
 import {Button} from './button'
 
+export interface IconButtonProps {
+  /** Click handler */
+  onClick?: () => void
+  /** Whether the button is in a filled/active state */
+  filled?: boolean
+  /** Button size variant */
+  size?: 'default' | 'sm' | 'lg'
+  /** Lucide icon component to render */
+  Icon: LucideIcon
+  /** Custom CSS classes for the button container */
+  buttonStyles?: string
+  /** Custom CSS classes for the icon */
+  iconStyles?: string
+}
+
 export function IconButton({
   onClick,
   filled = false,
@@ -11,14 +26,7 @@ export function IconButton({
   Icon,
   buttonStyles,
   iconStyles,
-}: {
-  onClick?: () => void
-  filled?: boolean
-  size?: 'default' | 'sm' | 'lg'
-  Icon: LucideIcon
-  buttonStyles?: string
-  iconStyles?: string
-}) {
+}: IconButtonProps) {
   const sizeMap = {
     sm: 'size-3',
     default: 'size-4',

package/src/components/atoms/image.test.tsx

@@ -1,13 +1,18 @@
-import {describe, expect, it, vi} from 'vitest'
+import {describe, expect, it, vi, beforeAll} from 'vitest'
 
 import {render, screen, waitFor} from '../../test-utils'
 
 import {Image} from './image'
 
+// Mock URL.revokeObjectURL for jsdom
+beforeAll(() => {
+  URL.revokeObjectURL = vi.fn()
+})
+
 // Mock the util functions
 vi.mock('../../utils', () => ({
-  getThumbhashDataURL: vi.fn((thumbhash?: string) =>
-    thumbhash ? `data:image/png;base64,${thumbhash}` : null
+  getThumbhashBlobURL: vi.fn((thumbhash?: string) =>
+    thumbhash ? `blob:http://localhost/${thumbhash}` : undefined
   ),
   getResizedImageUrl: vi.fn((url?: string) => url),
 }))
@@ -76,7 +81,7 @@ describe('Image', () => {
     expect(wrapper.style.aspectRatio).toBe('16/9')
   })
 
-  it('uses thumbhash as background when provided with fixed aspect ratio', () => {
+  it('uses thumbhash as placeholder when provided with fixed aspect ratio', () => {
     const {container} = render(
       <Image
         src="https://example.com/image.jpg"
@@ -86,10 +91,15 @@ describe('Image', () => {
       />
     )
 
-    const wrapper = container.firstChild as HTMLElement
-    expect(wrapper.style.backgroundImage).toContain(
-      'data:image/png;base64,testThumbhash'
+    // Thumbhash is now rendered as a separate img element (placeholder)
+    const images = container.querySelectorAll('img')
+    expect(images).toHaveLength(2) // placeholder + main image
+    const placeholderImg = images[0]
+    expect(placeholderImg).toHaveAttribute(
+      'src',
+      'blob:http://localhost/testThumbhash'
     )
+    expect(placeholderImg).toHaveAttribute('aria-hidden', 'true')
   })
 
   it('renders with natural sizing when aspectRatio is auto', () => {
@@ -122,13 +132,17 @@ describe('Image', () => {
       />
     )
 
-    const wrapper = container.firstChild as HTMLElement
-    const img = screen.getByRole('img')
-
-    expect(wrapper.style.backgroundImage).toContain(
-      'data:image/png;base64,testThumbhash'
+    // Thumbhash is now rendered as a separate img element (placeholder)
+    const images = container.querySelectorAll('img')
+    expect(images).toHaveLength(2) // placeholder + main image
+    const placeholderImg = images[0]
+    expect(placeholderImg).toHaveAttribute(
+      'src',
+      'blob:http://localhost/testThumbhash'
     )
-    expect(img).toHaveClass('w-full', 'h-auto')
+
+    const mainImg = images[1]
+    expect(mainImg).toHaveClass('w-full', 'h-auto')
   })
 
   it('passes additional props to img element', () => {

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/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-link.tsx

@@ -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.