@snowcone-app/ui 0.8.2 → 0.9.0

package/dist/index.d.cts

@@ -1623,13 +1623,21 @@ interface AddToCartProps {
     text?: string;
     loadingText?: string;
     successText?: string;
+    /** Button text after a failed add; the error's message is announced in a
+     *  `role="alert"` below the button and the button stays enabled to retry. */
+    errorText?: string;
     disabled?: boolean;
     className?: string;
     quantity?: number;
-    onClick?: (cartDetail: any) => void;
+    /** Performs the add. Return a Promise and the button waits for it: "Added!"
+     *  only after it resolves; a rejection shows the error state. */
+    onClick?: (cartDetail: any) => void | Promise<unknown>;
     onError?: (error: Error) => void;
+    /** Fake delay used only when there is no `onClick` (demos). */
     simulateDelay?: number;
 }
+/** `data-add-to-cart` on the button — assert on this, not the label text. */
+type AddToCartStatus = "idle" | "adding" | "added" | "error";
 /**
  * AddToCart - Add to cart button with validation and loading states
  *
@@ -1639,8 +1647,11 @@ interface AddToCartProps {
  *
  * Features:
  * - Automatic selection validation before allowing add
- * - Loading state with customizable text
- * - Success state with visual feedback (green background)
+ * - Loading state with customizable text; waits for an async `onClick`
+ * - Success only after `onClick` resolves; a rejection shows `errorText`
+ *   plus the error message in a `role="alert"`, and the button stays
+ *   enabled to retry (never a silent "Added!")
+ * - `data-add-to-cart="idle|adding|added|error"` for tests and agents
  * - Automatic cart detail generation with variant info
  * - Simulated delay for cart operations
  * - Screen reader announcements for state changes
@@ -1665,9 +1676,10 @@ interface AddToCartProps {
  * <Product productId="shirt-123">
  *   <ProductOptions />
  *   <AddToCart
- *     onClick={(cartDetail) => {
- *       console.log('Added to cart:', cartDetail);
- *       // Add to your cart state/API
+ *     onClick={async (cartDetail) => {
+ *       // Throw (or reject) if the add fails — the button shows the error.
+ *       const res = await fetch('/api/cart', { method: 'POST', body: JSON.stringify(cartDetail) });
+ *       if (!res.ok) throw new Error('Could not add to cart');
  *     }}
  *   />
  * </Product>
@@ -1697,24 +1709,22 @@ interface AddToCartProps {
  *
  * @example
  * ```tsx
- * // Faster simulation for testing
- * <AddToCart
- *   simulateDelay={500}
- *   onClick={(detail) => console.log(detail)}
- * />
+ * // Demo without a real cart: a simulated delay, then "Added!"
+ * <AddToCart simulateDelay={500} />
  * ```
  *
  * @param text - Button text in default state (default: "Add to Bag")
  * @param loadingText - Button text while adding (default: "Adding...")
  * @param successText - Button text after successful add (default: "Added!")
+ * @param errorText - Button text after a failed add (default: "Couldn't add — try again")
  * @param disabled - Force button to disabled state
  * @param className - Additional CSS classes for button
  * @param quantity - Number of items to add (default: 1)
- * @param onClick - Callback with cart detail after successful add
+ * @param onClick - Performs the add with the cart detail; may return a Promise, which the button awaits
  * @param onError - Callback when add fails with error
- * @param simulateDelay - Delay in ms to simulate cart operation (default: 1000)
+ * @param simulateDelay - Delay in ms to simulate a cart operation when there is no `onClick` (default: 1000)
  */
-declare function AddToCart({ text, loadingText, successText, disabled, className, quantity, onClick, onError, simulateDelay, }: AddToCartProps): react_jsx_runtime.JSX.Element;
+declare function AddToCart({ text, loadingText, successText, errorText, disabled, className, quantity, onClick, onError, simulateDelay, }: AddToCartProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Artwork shape types. Kept here for backwards-compatible imports
@@ -2306,7 +2316,31 @@ interface PlacementTabsProps {
     toolbarSize?: number;
     /** Additional className for the container */
     className?: string;
-}
+    /**
+     * Linked placements (ADR-0101): one design on every print area.
+     *
+     * - `true` — LINKED. Renders one non-interactive pill naming the set
+     *   ("Both sides" for two placements, "All N areas" otherwise; the labels
+     *   in its `title`) plus a single **Customize separately** action
+     *   (`onSplitAll`). No per-placement tabs: there is one design to edit.
+     * - `false` — SPLIT. Renders the per-placement tabs plus one
+     *   **Use one design for all** action (`onLinkAll`).
+     * - `undefined` (default) — no link model: plain tabs, exactly as before.
+     */
+    linked?: boolean;
+    /** Linked → split: every placement gets its own copy of the design. */
+    onSplitAll?: () => void;
+    /** Split → linked: drop the per-placement copies, back to one design. */
+    onLinkAll?: () => void;
+    /** Override the linked pill's copy (localisation). */
+    linkedLabel?: string;
+    /** Override the "Customize separately" action copy. */
+    splitAllLabel?: string;
+    /** Override the "Use one design for all" action copy. */
+    linkAllLabel?: string;
+}
+/** Default pill copy for a linked set of `count` placements. */
+declare function linkedPlacementsLabel(count: number): string;
 /**
  * PlacementTabs - Renders placement tabs with optional floating toolbar placeholder.
  *
@@ -2314,6 +2348,11 @@ interface PlacementTabsProps {
  * to flow around the toolbar placeholder. On desktop, renders simple tabs
  * without the toolbar placeholder (toolbar is typically in header).
  *
+ * The container carries `data-placement-tabs` and, when the link model is in
+ * play, `data-linked="true" | "false"`; the pill is `data-placement-pill`
+ * and the actions are `data-action="split-all" | "link-all"` so hosts and
+ * agents can assert the state instead of reading pixels.
+ *
  * @example
  * ```tsx
  * // Basic usage
@@ -2333,9 +2372,19 @@ interface PlacementTabsProps {
  *   onPlacementChange={setSelected}
  *   isDesktop
  * />
+ *
+ * // Linked by default (ADR-0101): one design on every area
+ * <PlacementTabs
+ *   placements={placements}
+ *   selectedPlacement={selected}
+ *   onPlacementChange={setSelected}
+ *   linked={linked}
+ *   onSplitAll={splitAll}
+ *   onLinkAll={linkAll}
+ * />
  * ```
  */
-declare function PlacementTabs({ placements, selectedPlacement, onPlacementChange, isDesktop, toolbarPlaceholderId, toolbarSize, className, }: PlacementTabsProps): react_jsx_runtime.JSX.Element | null;
+declare function PlacementTabs({ placements, selectedPlacement, onPlacementChange, isDesktop, toolbarPlaceholderId, toolbarSize, className, linked, onSplitAll, onLinkAll, linkedLabel, splitAllLabel, linkAllLabel, }: PlacementTabsProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * usePlacementsProcessor - Process placement prop to separate colors from images
@@ -2952,6 +3001,10 @@ interface RealtimeContextValue {
             y: number;
             width: number;
             height: number;
+            part?: {
+                index: number;
+                count: number;
+            };
         }>;
     }> | undefined) => void;
     getMockupResultsImmediate: () => MockupResult[];
@@ -5595,4 +5648,4 @@ declare function normalizeHex(color: string): string;
  */
 declare function scrollInputAboveKeyboard(input: HTMLElement): void;
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, AddToCart, type AddToCartProps, ArtAlignment, type ArtAlignmentProps, ArtSelector, type ArtSelectorProps, type Artwork, ArtworkCustomizer, type ArtworkCustomizerProps, Badge, type BadgeProps, BrandLogo, type BrandLogoProps, BrandName, type BrandNameProps, Button, type ButtonProps, CanvasEditor, type CanvasExportServiceConfig, CanvasIsolationBoundary, CanvasIsolationConfigurator, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CarouselImage, type CarouselRenderProps, Checkbox, Chip, type ClipShape, Collapsible, CollapsibleContent, CollapsibleRoot, CollapsibleTrigger, ColorPalette, ColorPicker, type ColorPickerProps, ColorRow, ColorSwatch, type ColorSwatchChoice, type ColorSwatchProps, ColorTokenSwatch, type ContentRenderProps, CurrentRefinements, CurrentSelectionDisplay, type CurrentSelectionDisplayProps, DEFAULT_HERO_ZOOM_CONFIG, DEFAULT_IMAGE_CONFIG, DEFAULT_VISIBILITY_OPTIONS, DesignSystemPage, type DeviceDetectionResult, Disclosure, DisclosureContent, DisclosureTrigger, DragHintAnimation, type DragHintAnimationProps, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EdgeBlurBox, type EdgeBlurBoxProps, EdgeSwipeGuards, type EdgeSwipeGuardsProps, EnhancedImageViewer, FACET_SECTIONS, type FacetSection, type FacetType, Fieldset, type FieldsetProps, Filters, FiltersButton, type FiltersButtonProps, FiltersDrawer, type FiltersProps, FloatingActionGroup, type FloatingActionGroupProps, type FloatingActionItem, type FormatCurrencyOptions, HeroCarousel, type HeroCarouselProps, type HeroImage, type HeroImageRenderProps, HeroProductImage, type HeroProductImageProps, type HeroShrinkConfig, HeroShrinkLayout, type HeroShrinkLayoutProps, type HeroZoomConfig, HeroZoomLayout, type HeroZoomLayoutProps, type HeroZoomScales, HorizontalProgressiveBlur, type HorizontalProgressiveBlurProps, Drawer as IOSDrawer, DrawerClose as IOSDrawerClose, DrawerContent as IOSDrawerContent, DrawerDescription as IOSDrawerDescription, DrawerFooter as IOSDrawerFooter, DrawerHeader as IOSDrawerHeader, DrawerTitle as IOSDrawerTitle, DrawerTrigger as IOSDrawerTrigger, ImageBlurExtension, type ImageBlurExtensionProps, ImageEdgeBlur, type ImageEdgeBlurProps, type ImageLayer, type ImageUpdateRequest, Input, type InputProps, Kbd, type KbdProps, Label, Legend, type LegendProps, Lightbox, type LightboxProps, Link, LinkIcon, type LinkProps, LoadingOverlayPrism, LoadingOverlayPrismCandy, LoadingOverlayPrismCandyInline, type LoadingOverlayPrismCandyProps, type LoadingOverlayPrismProps, MasonryGrid, type MasonryGridProps, MobileProductCarousel, type MobileProductCarouselProps, MockupBackground, type MockupBackgroundProps, type MockupPriorityContextValue, MockupPriorityProvider, type MockupPriorityProviderProps, type MockupResult, PDPLayout, type PDPLayoutProps, PersonalizationField, PersonalizationInputs, PersonalizationProvider, PersonalizationValues, PlacementClipShapeSelector, type PlacementConfig, type PlacementDesign, PlacementTabs, type PlacementTabsProps, Popover, PopoverAnchor, PopoverContent, PopoverRoot, PopoverTrigger, type PriorityLevel, Product, ProductCard, type ProductCardProps, ProductContext, type ProductDataMode, ProductGallery, type ProductGalleryProps, ProductGrid, type ProductGridProps, type ProductHit, ProductHitComponent, ProductImage, type Artwork$1 as ProductImageArtwork, type ProductImageProps, ProductList, type ProductListProps, ProductOptions, type ProductPageContext, ProductPageProvider, ProductPageProviderMinimal, type ProductPageProviderMinimalProps, type ProductPageProviderProps, ProductPrice, type ProductPriceProps, type ProductProviderProps, ProgressiveBlur, type ProgressiveBlurProps, type ProviderStatus, Radio, RadioGroup, RadioGroupItem, RadiusScale, type ReactProductContext, type RealtimeContextValue, RealtimeMockup, type RealtimeMockupProps, RealtimeProvider, type RealtimeProviderProps, type RealtimeState, type RegularArtwork$1 as RegularArtwork, type ResponsiveColumns, type ResponsiveImageCapInfo, type ResponsiveImageCapOptions, ResponsiveZoom, RightToLeftProgressiveBlur, type RightToLeftProgressiveBlurProps, SafeImg, type SafeImgProps, type ScrollDirection, ScrollFade, type ScrollFadeProps, type ScrollState, type SeamlessPattern$1 as SeamlessPattern, SearchBox, SearchProvider, type SearchProviderProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Shop, ShopContext, type ShopContextValue, type ShopProps, SimpleImageBlur, type SimpleImageBlurProps, Slider, SliderFill, SliderOutput, SliderThumb, SliderTrack, Spinner, type SpinnerProps, Surface, SurfaceContext, type SurfaceProps, Switch, Tabs, TabsContent, TabsList, TabsRoot, TabsTrigger, TextArea, TextField, type TextFieldProps, Textarea, type TextareaProps, ThemeSwitcher, ThemeToggle, type ThemeToggleProps, TileCount, Tooltip, TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger, TypographyScale, type UiRouter, UiRouterProvider, type UseBrandResult, type UseImagePreloaderOptions, type UseImagePreloaderReturn, type UseImageTransitionOptions, type UseImageTransitionReturn, type UsePersonalizationShimmerReturn, type UseProductGalleryOptions, type UseProductGalleryReturn, VISIBILITY_THRESHOLDS, type ViewportDimensions, type ZoomImage, ZoomOverlay, badgeVariants, brandAssets, buttonVariants, canvasExportService, checkComponentStyles, checkTailwindConfig, checkThemeTokens, createScrollDirectionTracker, formatCurrency, formatDate, formatDateTime, getBrand, getObservedElementCount, getObserverCount, hasEdgeBlur, isObserved, isWideMonitor, kbdVariants, linkVariants, normalizeHex, observe, runConfigChecks, scrollInputAboveKeyboard, searchClient, spinnerVariants, surfaceVariants, useArtworkAlignment, useBrand, useCanvasContext, useCanvasContextStatic, useCurrentPlacements, useDesign, useDesignOptional, useDeviceDetection, useFocusTrap, useHeroZoomScales, useImagePreloader, useImageTransition, useIsolatedCanvas, useLoadingOverlay, useMediaQuery, useMockupBackgroundOptional, useMockupPriority, useMockupPriorityOptional, usePersonalization, usePersonalizationOptional, usePersonalizationShimmer, usePlacementClipShape, usePlacementsProcessor, useProduct, useProductGallery, useProductOptional, useProductPage, useProductPageOptional, useProductSelection, useProviderStatus, useRealtime, useRealtimeOptional, useRenderCount, useRenderGuard, useResponsiveImageCap, useScrollDirection, useSelectedArtwork, useSetArtworkAlignment, useShop, useShopOptional, useSurface, useViewportDimensions, useWideMonitorMode };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, AddToCart, type AddToCartProps, type AddToCartStatus, ArtAlignment, type ArtAlignmentProps, ArtSelector, type ArtSelectorProps, type Artwork, ArtworkCustomizer, type ArtworkCustomizerProps, Badge, type BadgeProps, BrandLogo, type BrandLogoProps, BrandName, type BrandNameProps, Button, type ButtonProps, CanvasEditor, type CanvasExportServiceConfig, CanvasIsolationBoundary, CanvasIsolationConfigurator, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CarouselImage, type CarouselRenderProps, Checkbox, Chip, type ClipShape, Collapsible, CollapsibleContent, CollapsibleRoot, CollapsibleTrigger, ColorPalette, ColorPicker, type ColorPickerProps, ColorRow, ColorSwatch, type ColorSwatchChoice, type ColorSwatchProps, ColorTokenSwatch, type ContentRenderProps, CurrentRefinements, CurrentSelectionDisplay, type CurrentSelectionDisplayProps, DEFAULT_HERO_ZOOM_CONFIG, DEFAULT_IMAGE_CONFIG, DEFAULT_VISIBILITY_OPTIONS, DesignSystemPage, type DeviceDetectionResult, Disclosure, DisclosureContent, DisclosureTrigger, DragHintAnimation, type DragHintAnimationProps, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EdgeBlurBox, type EdgeBlurBoxProps, EdgeSwipeGuards, type EdgeSwipeGuardsProps, EnhancedImageViewer, FACET_SECTIONS, type FacetSection, type FacetType, Fieldset, type FieldsetProps, Filters, FiltersButton, type FiltersButtonProps, FiltersDrawer, type FiltersProps, FloatingActionGroup, type FloatingActionGroupProps, type FloatingActionItem, type FormatCurrencyOptions, HeroCarousel, type HeroCarouselProps, type HeroImage, type HeroImageRenderProps, HeroProductImage, type HeroProductImageProps, type HeroShrinkConfig, HeroShrinkLayout, type HeroShrinkLayoutProps, type HeroZoomConfig, HeroZoomLayout, type HeroZoomLayoutProps, type HeroZoomScales, HorizontalProgressiveBlur, type HorizontalProgressiveBlurProps, Drawer as IOSDrawer, DrawerClose as IOSDrawerClose, DrawerContent as IOSDrawerContent, DrawerDescription as IOSDrawerDescription, DrawerFooter as IOSDrawerFooter, DrawerHeader as IOSDrawerHeader, DrawerTitle as IOSDrawerTitle, DrawerTrigger as IOSDrawerTrigger, ImageBlurExtension, type ImageBlurExtensionProps, ImageEdgeBlur, type ImageEdgeBlurProps, type ImageLayer, type ImageUpdateRequest, Input, type InputProps, Kbd, type KbdProps, Label, Legend, type LegendProps, Lightbox, type LightboxProps, Link, LinkIcon, type LinkProps, LoadingOverlayPrism, LoadingOverlayPrismCandy, LoadingOverlayPrismCandyInline, type LoadingOverlayPrismCandyProps, type LoadingOverlayPrismProps, MasonryGrid, type MasonryGridProps, MobileProductCarousel, type MobileProductCarouselProps, MockupBackground, type MockupBackgroundProps, type MockupPriorityContextValue, MockupPriorityProvider, type MockupPriorityProviderProps, type MockupResult, PDPLayout, type PDPLayoutProps, PersonalizationField, PersonalizationInputs, PersonalizationProvider, PersonalizationValues, PlacementClipShapeSelector, type PlacementConfig, type PlacementDesign, PlacementTabs, type PlacementTabsProps, Popover, PopoverAnchor, PopoverContent, PopoverRoot, PopoverTrigger, type PriorityLevel, Product, ProductCard, type ProductCardProps, ProductContext, type ProductDataMode, ProductGallery, type ProductGalleryProps, ProductGrid, type ProductGridProps, type ProductHit, ProductHitComponent, ProductImage, type Artwork$1 as ProductImageArtwork, type ProductImageProps, ProductList, type ProductListProps, ProductOptions, type ProductPageContext, ProductPageProvider, ProductPageProviderMinimal, type ProductPageProviderMinimalProps, type ProductPageProviderProps, ProductPrice, type ProductPriceProps, type ProductProviderProps, ProgressiveBlur, type ProgressiveBlurProps, type ProviderStatus, Radio, RadioGroup, RadioGroupItem, RadiusScale, type ReactProductContext, type RealtimeContextValue, RealtimeMockup, type RealtimeMockupProps, RealtimeProvider, type RealtimeProviderProps, type RealtimeState, type RegularArtwork$1 as RegularArtwork, type ResponsiveColumns, type ResponsiveImageCapInfo, type ResponsiveImageCapOptions, ResponsiveZoom, RightToLeftProgressiveBlur, type RightToLeftProgressiveBlurProps, SafeImg, type SafeImgProps, type ScrollDirection, ScrollFade, type ScrollFadeProps, type ScrollState, type SeamlessPattern$1 as SeamlessPattern, SearchBox, SearchProvider, type SearchProviderProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Shop, ShopContext, type ShopContextValue, type ShopProps, SimpleImageBlur, type SimpleImageBlurProps, Slider, SliderFill, SliderOutput, SliderThumb, SliderTrack, Spinner, type SpinnerProps, Surface, SurfaceContext, type SurfaceProps, Switch, Tabs, TabsContent, TabsList, TabsRoot, TabsTrigger, TextArea, TextField, type TextFieldProps, Textarea, type TextareaProps, ThemeSwitcher, ThemeToggle, type ThemeToggleProps, TileCount, Tooltip, TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger, TypographyScale, type UiRouter, UiRouterProvider, type UseBrandResult, type UseImagePreloaderOptions, type UseImagePreloaderReturn, type UseImageTransitionOptions, type UseImageTransitionReturn, type UsePersonalizationShimmerReturn, type UseProductGalleryOptions, type UseProductGalleryReturn, VISIBILITY_THRESHOLDS, type ViewportDimensions, type ZoomImage, ZoomOverlay, badgeVariants, brandAssets, buttonVariants, canvasExportService, checkComponentStyles, checkTailwindConfig, checkThemeTokens, createScrollDirectionTracker, formatCurrency, formatDate, formatDateTime, getBrand, getObservedElementCount, getObserverCount, hasEdgeBlur, isObserved, isWideMonitor, kbdVariants, linkVariants, linkedPlacementsLabel, normalizeHex, observe, runConfigChecks, scrollInputAboveKeyboard, searchClient, spinnerVariants, surfaceVariants, useArtworkAlignment, useBrand, useCanvasContext, useCanvasContextStatic, useCurrentPlacements, useDesign, useDesignOptional, useDeviceDetection, useFocusTrap, useHeroZoomScales, useImagePreloader, useImageTransition, useIsolatedCanvas, useLoadingOverlay, useMediaQuery, useMockupBackgroundOptional, useMockupPriority, useMockupPriorityOptional, usePersonalization, usePersonalizationOptional, usePersonalizationShimmer, usePlacementClipShape, usePlacementsProcessor, useProduct, useProductGallery, useProductOptional, useProductPage, useProductPageOptional, useProductSelection, useProviderStatus, useRealtime, useRealtimeOptional, useRenderCount, useRenderGuard, useResponsiveImageCap, useScrollDirection, useSelectedArtwork, useSetArtworkAlignment, useShop, useShopOptional, useSurface, useViewportDimensions, useWideMonitorMode };

package/dist/index.d.ts

@@ -1623,13 +1623,21 @@ interface AddToCartProps {
     text?: string;
     loadingText?: string;
     successText?: string;
+    /** Button text after a failed add; the error's message is announced in a
+     *  `role="alert"` below the button and the button stays enabled to retry. */
+    errorText?: string;
     disabled?: boolean;
     className?: string;
     quantity?: number;
-    onClick?: (cartDetail: any) => void;
+    /** Performs the add. Return a Promise and the button waits for it: "Added!"
+     *  only after it resolves; a rejection shows the error state. */
+    onClick?: (cartDetail: any) => void | Promise<unknown>;
     onError?: (error: Error) => void;
+    /** Fake delay used only when there is no `onClick` (demos). */
     simulateDelay?: number;
 }
+/** `data-add-to-cart` on the button — assert on this, not the label text. */
+type AddToCartStatus = "idle" | "adding" | "added" | "error";
 /**
  * AddToCart - Add to cart button with validation and loading states
  *
@@ -1639,8 +1647,11 @@ interface AddToCartProps {
  *
  * Features:
  * - Automatic selection validation before allowing add
- * - Loading state with customizable text
- * - Success state with visual feedback (green background)
+ * - Loading state with customizable text; waits for an async `onClick`
+ * - Success only after `onClick` resolves; a rejection shows `errorText`
+ *   plus the error message in a `role="alert"`, and the button stays
+ *   enabled to retry (never a silent "Added!")
+ * - `data-add-to-cart="idle|adding|added|error"` for tests and agents
  * - Automatic cart detail generation with variant info
  * - Simulated delay for cart operations
  * - Screen reader announcements for state changes
@@ -1665,9 +1676,10 @@ interface AddToCartProps {
  * <Product productId="shirt-123">
  *   <ProductOptions />
  *   <AddToCart
- *     onClick={(cartDetail) => {
- *       console.log('Added to cart:', cartDetail);
- *       // Add to your cart state/API
+ *     onClick={async (cartDetail) => {
+ *       // Throw (or reject) if the add fails — the button shows the error.
+ *       const res = await fetch('/api/cart', { method: 'POST', body: JSON.stringify(cartDetail) });
+ *       if (!res.ok) throw new Error('Could not add to cart');
  *     }}
  *   />
  * </Product>
@@ -1697,24 +1709,22 @@ interface AddToCartProps {
  *
  * @example
  * ```tsx
- * // Faster simulation for testing
- * <AddToCart
- *   simulateDelay={500}
- *   onClick={(detail) => console.log(detail)}
- * />
+ * // Demo without a real cart: a simulated delay, then "Added!"
+ * <AddToCart simulateDelay={500} />
  * ```
  *
  * @param text - Button text in default state (default: "Add to Bag")
  * @param loadingText - Button text while adding (default: "Adding...")
  * @param successText - Button text after successful add (default: "Added!")
+ * @param errorText - Button text after a failed add (default: "Couldn't add — try again")
  * @param disabled - Force button to disabled state
  * @param className - Additional CSS classes for button
  * @param quantity - Number of items to add (default: 1)
- * @param onClick - Callback with cart detail after successful add
+ * @param onClick - Performs the add with the cart detail; may return a Promise, which the button awaits
  * @param onError - Callback when add fails with error
- * @param simulateDelay - Delay in ms to simulate cart operation (default: 1000)
+ * @param simulateDelay - Delay in ms to simulate a cart operation when there is no `onClick` (default: 1000)
  */
-declare function AddToCart({ text, loadingText, successText, disabled, className, quantity, onClick, onError, simulateDelay, }: AddToCartProps): react_jsx_runtime.JSX.Element;
+declare function AddToCart({ text, loadingText, successText, errorText, disabled, className, quantity, onClick, onError, simulateDelay, }: AddToCartProps): react_jsx_runtime.JSX.Element;
 
 /**
  * Artwork shape types. Kept here for backwards-compatible imports
@@ -2306,7 +2316,31 @@ interface PlacementTabsProps {
     toolbarSize?: number;
     /** Additional className for the container */
     className?: string;
-}
+    /**
+     * Linked placements (ADR-0101): one design on every print area.
+     *
+     * - `true` — LINKED. Renders one non-interactive pill naming the set
+     *   ("Both sides" for two placements, "All N areas" otherwise; the labels
+     *   in its `title`) plus a single **Customize separately** action
+     *   (`onSplitAll`). No per-placement tabs: there is one design to edit.
+     * - `false` — SPLIT. Renders the per-placement tabs plus one
+     *   **Use one design for all** action (`onLinkAll`).
+     * - `undefined` (default) — no link model: plain tabs, exactly as before.
+     */
+    linked?: boolean;
+    /** Linked → split: every placement gets its own copy of the design. */
+    onSplitAll?: () => void;
+    /** Split → linked: drop the per-placement copies, back to one design. */
+    onLinkAll?: () => void;
+    /** Override the linked pill's copy (localisation). */
+    linkedLabel?: string;
+    /** Override the "Customize separately" action copy. */
+    splitAllLabel?: string;
+    /** Override the "Use one design for all" action copy. */
+    linkAllLabel?: string;
+}
+/** Default pill copy for a linked set of `count` placements. */
+declare function linkedPlacementsLabel(count: number): string;
 /**
  * PlacementTabs - Renders placement tabs with optional floating toolbar placeholder.
  *
@@ -2314,6 +2348,11 @@ interface PlacementTabsProps {
  * to flow around the toolbar placeholder. On desktop, renders simple tabs
  * without the toolbar placeholder (toolbar is typically in header).
  *
+ * The container carries `data-placement-tabs` and, when the link model is in
+ * play, `data-linked="true" | "false"`; the pill is `data-placement-pill`
+ * and the actions are `data-action="split-all" | "link-all"` so hosts and
+ * agents can assert the state instead of reading pixels.
+ *
  * @example
  * ```tsx
  * // Basic usage
@@ -2333,9 +2372,19 @@ interface PlacementTabsProps {
  *   onPlacementChange={setSelected}
  *   isDesktop
  * />
+ *
+ * // Linked by default (ADR-0101): one design on every area
+ * <PlacementTabs
+ *   placements={placements}
+ *   selectedPlacement={selected}
+ *   onPlacementChange={setSelected}
+ *   linked={linked}
+ *   onSplitAll={splitAll}
+ *   onLinkAll={linkAll}
+ * />
  * ```
  */
-declare function PlacementTabs({ placements, selectedPlacement, onPlacementChange, isDesktop, toolbarPlaceholderId, toolbarSize, className, }: PlacementTabsProps): react_jsx_runtime.JSX.Element | null;
+declare function PlacementTabs({ placements, selectedPlacement, onPlacementChange, isDesktop, toolbarPlaceholderId, toolbarSize, className, linked, onSplitAll, onLinkAll, linkedLabel, splitAllLabel, linkAllLabel, }: PlacementTabsProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * usePlacementsProcessor - Process placement prop to separate colors from images
@@ -2952,6 +3001,10 @@ interface RealtimeContextValue {
             y: number;
             width: number;
             height: number;
+            part?: {
+                index: number;
+                count: number;
+            };
         }>;
     }> | undefined) => void;
     getMockupResultsImmediate: () => MockupResult[];
@@ -5595,4 +5648,4 @@ declare function normalizeHex(color: string): string;
  */
 declare function scrollInputAboveKeyboard(input: HTMLElement): void;
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, AddToCart, type AddToCartProps, ArtAlignment, type ArtAlignmentProps, ArtSelector, type ArtSelectorProps, type Artwork, ArtworkCustomizer, type ArtworkCustomizerProps, Badge, type BadgeProps, BrandLogo, type BrandLogoProps, BrandName, type BrandNameProps, Button, type ButtonProps, CanvasEditor, type CanvasExportServiceConfig, CanvasIsolationBoundary, CanvasIsolationConfigurator, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CarouselImage, type CarouselRenderProps, Checkbox, Chip, type ClipShape, Collapsible, CollapsibleContent, CollapsibleRoot, CollapsibleTrigger, ColorPalette, ColorPicker, type ColorPickerProps, ColorRow, ColorSwatch, type ColorSwatchChoice, type ColorSwatchProps, ColorTokenSwatch, type ContentRenderProps, CurrentRefinements, CurrentSelectionDisplay, type CurrentSelectionDisplayProps, DEFAULT_HERO_ZOOM_CONFIG, DEFAULT_IMAGE_CONFIG, DEFAULT_VISIBILITY_OPTIONS, DesignSystemPage, type DeviceDetectionResult, Disclosure, DisclosureContent, DisclosureTrigger, DragHintAnimation, type DragHintAnimationProps, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EdgeBlurBox, type EdgeBlurBoxProps, EdgeSwipeGuards, type EdgeSwipeGuardsProps, EnhancedImageViewer, FACET_SECTIONS, type FacetSection, type FacetType, Fieldset, type FieldsetProps, Filters, FiltersButton, type FiltersButtonProps, FiltersDrawer, type FiltersProps, FloatingActionGroup, type FloatingActionGroupProps, type FloatingActionItem, type FormatCurrencyOptions, HeroCarousel, type HeroCarouselProps, type HeroImage, type HeroImageRenderProps, HeroProductImage, type HeroProductImageProps, type HeroShrinkConfig, HeroShrinkLayout, type HeroShrinkLayoutProps, type HeroZoomConfig, HeroZoomLayout, type HeroZoomLayoutProps, type HeroZoomScales, HorizontalProgressiveBlur, type HorizontalProgressiveBlurProps, Drawer as IOSDrawer, DrawerClose as IOSDrawerClose, DrawerContent as IOSDrawerContent, DrawerDescription as IOSDrawerDescription, DrawerFooter as IOSDrawerFooter, DrawerHeader as IOSDrawerHeader, DrawerTitle as IOSDrawerTitle, DrawerTrigger as IOSDrawerTrigger, ImageBlurExtension, type ImageBlurExtensionProps, ImageEdgeBlur, type ImageEdgeBlurProps, type ImageLayer, type ImageUpdateRequest, Input, type InputProps, Kbd, type KbdProps, Label, Legend, type LegendProps, Lightbox, type LightboxProps, Link, LinkIcon, type LinkProps, LoadingOverlayPrism, LoadingOverlayPrismCandy, LoadingOverlayPrismCandyInline, type LoadingOverlayPrismCandyProps, type LoadingOverlayPrismProps, MasonryGrid, type MasonryGridProps, MobileProductCarousel, type MobileProductCarouselProps, MockupBackground, type MockupBackgroundProps, type MockupPriorityContextValue, MockupPriorityProvider, type MockupPriorityProviderProps, type MockupResult, PDPLayout, type PDPLayoutProps, PersonalizationField, PersonalizationInputs, PersonalizationProvider, PersonalizationValues, PlacementClipShapeSelector, type PlacementConfig, type PlacementDesign, PlacementTabs, type PlacementTabsProps, Popover, PopoverAnchor, PopoverContent, PopoverRoot, PopoverTrigger, type PriorityLevel, Product, ProductCard, type ProductCardProps, ProductContext, type ProductDataMode, ProductGallery, type ProductGalleryProps, ProductGrid, type ProductGridProps, type ProductHit, ProductHitComponent, ProductImage, type Artwork$1 as ProductImageArtwork, type ProductImageProps, ProductList, type ProductListProps, ProductOptions, type ProductPageContext, ProductPageProvider, ProductPageProviderMinimal, type ProductPageProviderMinimalProps, type ProductPageProviderProps, ProductPrice, type ProductPriceProps, type ProductProviderProps, ProgressiveBlur, type ProgressiveBlurProps, type ProviderStatus, Radio, RadioGroup, RadioGroupItem, RadiusScale, type ReactProductContext, type RealtimeContextValue, RealtimeMockup, type RealtimeMockupProps, RealtimeProvider, type RealtimeProviderProps, type RealtimeState, type RegularArtwork$1 as RegularArtwork, type ResponsiveColumns, type ResponsiveImageCapInfo, type ResponsiveImageCapOptions, ResponsiveZoom, RightToLeftProgressiveBlur, type RightToLeftProgressiveBlurProps, SafeImg, type SafeImgProps, type ScrollDirection, ScrollFade, type ScrollFadeProps, type ScrollState, type SeamlessPattern$1 as SeamlessPattern, SearchBox, SearchProvider, type SearchProviderProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Shop, ShopContext, type ShopContextValue, type ShopProps, SimpleImageBlur, type SimpleImageBlurProps, Slider, SliderFill, SliderOutput, SliderThumb, SliderTrack, Spinner, type SpinnerProps, Surface, SurfaceContext, type SurfaceProps, Switch, Tabs, TabsContent, TabsList, TabsRoot, TabsTrigger, TextArea, TextField, type TextFieldProps, Textarea, type TextareaProps, ThemeSwitcher, ThemeToggle, type ThemeToggleProps, TileCount, Tooltip, TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger, TypographyScale, type UiRouter, UiRouterProvider, type UseBrandResult, type UseImagePreloaderOptions, type UseImagePreloaderReturn, type UseImageTransitionOptions, type UseImageTransitionReturn, type UsePersonalizationShimmerReturn, type UseProductGalleryOptions, type UseProductGalleryReturn, VISIBILITY_THRESHOLDS, type ViewportDimensions, type ZoomImage, ZoomOverlay, badgeVariants, brandAssets, buttonVariants, canvasExportService, checkComponentStyles, checkTailwindConfig, checkThemeTokens, createScrollDirectionTracker, formatCurrency, formatDate, formatDateTime, getBrand, getObservedElementCount, getObserverCount, hasEdgeBlur, isObserved, isWideMonitor, kbdVariants, linkVariants, normalizeHex, observe, runConfigChecks, scrollInputAboveKeyboard, searchClient, spinnerVariants, surfaceVariants, useArtworkAlignment, useBrand, useCanvasContext, useCanvasContextStatic, useCurrentPlacements, useDesign, useDesignOptional, useDeviceDetection, useFocusTrap, useHeroZoomScales, useImagePreloader, useImageTransition, useIsolatedCanvas, useLoadingOverlay, useMediaQuery, useMockupBackgroundOptional, useMockupPriority, useMockupPriorityOptional, usePersonalization, usePersonalizationOptional, usePersonalizationShimmer, usePlacementClipShape, usePlacementsProcessor, useProduct, useProductGallery, useProductOptional, useProductPage, useProductPageOptional, useProductSelection, useProviderStatus, useRealtime, useRealtimeOptional, useRenderCount, useRenderGuard, useResponsiveImageCap, useScrollDirection, useSelectedArtwork, useSetArtworkAlignment, useShop, useShopOptional, useSurface, useViewportDimensions, useWideMonitorMode };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, AddToCart, type AddToCartProps, type AddToCartStatus, ArtAlignment, type ArtAlignmentProps, ArtSelector, type ArtSelectorProps, type Artwork, ArtworkCustomizer, type ArtworkCustomizerProps, Badge, type BadgeProps, BrandLogo, type BrandLogoProps, BrandName, type BrandNameProps, Button, type ButtonProps, CanvasEditor, type CanvasExportServiceConfig, CanvasIsolationBoundary, CanvasIsolationConfigurator, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, type CarouselImage, type CarouselRenderProps, Checkbox, Chip, type ClipShape, Collapsible, CollapsibleContent, CollapsibleRoot, CollapsibleTrigger, ColorPalette, ColorPicker, type ColorPickerProps, ColorRow, ColorSwatch, type ColorSwatchChoice, type ColorSwatchProps, ColorTokenSwatch, type ContentRenderProps, CurrentRefinements, CurrentSelectionDisplay, type CurrentSelectionDisplayProps, DEFAULT_HERO_ZOOM_CONFIG, DEFAULT_IMAGE_CONFIG, DEFAULT_VISIBILITY_OPTIONS, DesignSystemPage, type DeviceDetectionResult, Disclosure, DisclosureContent, DisclosureTrigger, DragHintAnimation, type DragHintAnimationProps, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EdgeBlurBox, type EdgeBlurBoxProps, EdgeSwipeGuards, type EdgeSwipeGuardsProps, EnhancedImageViewer, FACET_SECTIONS, type FacetSection, type FacetType, Fieldset, type FieldsetProps, Filters, FiltersButton, type FiltersButtonProps, FiltersDrawer, type FiltersProps, FloatingActionGroup, type FloatingActionGroupProps, type FloatingActionItem, type FormatCurrencyOptions, HeroCarousel, type HeroCarouselProps, type HeroImage, type HeroImageRenderProps, HeroProductImage, type HeroProductImageProps, type HeroShrinkConfig, HeroShrinkLayout, type HeroShrinkLayoutProps, type HeroZoomConfig, HeroZoomLayout, type HeroZoomLayoutProps, type HeroZoomScales, HorizontalProgressiveBlur, type HorizontalProgressiveBlurProps, Drawer as IOSDrawer, DrawerClose as IOSDrawerClose, DrawerContent as IOSDrawerContent, DrawerDescription as IOSDrawerDescription, DrawerFooter as IOSDrawerFooter, DrawerHeader as IOSDrawerHeader, DrawerTitle as IOSDrawerTitle, DrawerTrigger as IOSDrawerTrigger, ImageBlurExtension, type ImageBlurExtensionProps, ImageEdgeBlur, type ImageEdgeBlurProps, type ImageLayer, type ImageUpdateRequest, Input, type InputProps, Kbd, type KbdProps, Label, Legend, type LegendProps, Lightbox, type LightboxProps, Link, LinkIcon, type LinkProps, LoadingOverlayPrism, LoadingOverlayPrismCandy, LoadingOverlayPrismCandyInline, type LoadingOverlayPrismCandyProps, type LoadingOverlayPrismProps, MasonryGrid, type MasonryGridProps, MobileProductCarousel, type MobileProductCarouselProps, MockupBackground, type MockupBackgroundProps, type MockupPriorityContextValue, MockupPriorityProvider, type MockupPriorityProviderProps, type MockupResult, PDPLayout, type PDPLayoutProps, PersonalizationField, PersonalizationInputs, PersonalizationProvider, PersonalizationValues, PlacementClipShapeSelector, type PlacementConfig, type PlacementDesign, PlacementTabs, type PlacementTabsProps, Popover, PopoverAnchor, PopoverContent, PopoverRoot, PopoverTrigger, type PriorityLevel, Product, ProductCard, type ProductCardProps, ProductContext, type ProductDataMode, ProductGallery, type ProductGalleryProps, ProductGrid, type ProductGridProps, type ProductHit, ProductHitComponent, ProductImage, type Artwork$1 as ProductImageArtwork, type ProductImageProps, ProductList, type ProductListProps, ProductOptions, type ProductPageContext, ProductPageProvider, ProductPageProviderMinimal, type ProductPageProviderMinimalProps, type ProductPageProviderProps, ProductPrice, type ProductPriceProps, type ProductProviderProps, ProgressiveBlur, type ProgressiveBlurProps, type ProviderStatus, Radio, RadioGroup, RadioGroupItem, RadiusScale, type ReactProductContext, type RealtimeContextValue, RealtimeMockup, type RealtimeMockupProps, RealtimeProvider, type RealtimeProviderProps, type RealtimeState, type RegularArtwork$1 as RegularArtwork, type ResponsiveColumns, type ResponsiveImageCapInfo, type ResponsiveImageCapOptions, ResponsiveZoom, RightToLeftProgressiveBlur, type RightToLeftProgressiveBlurProps, SafeImg, type SafeImgProps, type ScrollDirection, ScrollFade, type ScrollFadeProps, type ScrollState, type SeamlessPattern$1 as SeamlessPattern, SearchBox, SearchProvider, type SearchProviderProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Shop, ShopContext, type ShopContextValue, type ShopProps, SimpleImageBlur, type SimpleImageBlurProps, Slider, SliderFill, SliderOutput, SliderThumb, SliderTrack, Spinner, type SpinnerProps, Surface, SurfaceContext, type SurfaceProps, Switch, Tabs, TabsContent, TabsList, TabsRoot, TabsTrigger, TextArea, TextField, type TextFieldProps, Textarea, type TextareaProps, ThemeSwitcher, ThemeToggle, type ThemeToggleProps, TileCount, Tooltip, TooltipContent, TooltipProvider, TooltipRoot, TooltipTrigger, TypographyScale, type UiRouter, UiRouterProvider, type UseBrandResult, type UseImagePreloaderOptions, type UseImagePreloaderReturn, type UseImageTransitionOptions, type UseImageTransitionReturn, type UsePersonalizationShimmerReturn, type UseProductGalleryOptions, type UseProductGalleryReturn, VISIBILITY_THRESHOLDS, type ViewportDimensions, type ZoomImage, ZoomOverlay, badgeVariants, brandAssets, buttonVariants, canvasExportService, checkComponentStyles, checkTailwindConfig, checkThemeTokens, createScrollDirectionTracker, formatCurrency, formatDate, formatDateTime, getBrand, getObservedElementCount, getObserverCount, hasEdgeBlur, isObserved, isWideMonitor, kbdVariants, linkVariants, linkedPlacementsLabel, normalizeHex, observe, runConfigChecks, scrollInputAboveKeyboard, searchClient, spinnerVariants, surfaceVariants, useArtworkAlignment, useBrand, useCanvasContext, useCanvasContextStatic, useCurrentPlacements, useDesign, useDesignOptional, useDeviceDetection, useFocusTrap, useHeroZoomScales, useImagePreloader, useImageTransition, useIsolatedCanvas, useLoadingOverlay, useMediaQuery, useMockupBackgroundOptional, useMockupPriority, useMockupPriorityOptional, usePersonalization, usePersonalizationOptional, usePersonalizationShimmer, usePlacementClipShape, usePlacementsProcessor, useProduct, useProductGallery, useProductOptional, useProductPage, useProductPageOptional, useProductSelection, useProviderStatus, useRealtime, useRealtimeOptional, useRenderCount, useRenderGuard, useResponsiveImageCap, useScrollDirection, useSelectedArtwork, useSetArtworkAlignment, useShop, useShopOptional, useSurface, useViewportDimensions, useWideMonitorMode };