@lime-bundles/react 6.1.0 → 7.0.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { CartLineInput, BuyerResolver, ProductVariant, ParsedBundle, OutOfStockBehavior, WidgetConfig } from '@lime-bundles/core';
-export { BUNDLES_FOR_PRODUCT_QUERY, BUNDLE_METAOBJECT_QUERY, BogoBundleData, BundleParseError, BundleType, CartLineInput, CountdownConfig, CtaConfig, DEFAULT_OUT_OF_STOCK_BEHAVIOR, DiscountConfig, FixedBundleData, FixedBundlePricing, HeaderConfig, ImageTransform, LayoutConfig, MixMatchBundleData, MultiStepBundleData, OutOfStockBehavior, ParsedBundle, ParsedMultiStep, PopularBadgeConfig, PricingConfig, PricingRow, Product, ProductListConfig, ProductVariant, SHOP_SETTINGS_QUERY, SavingsBarConfig, StorefrontApiError, ThumbnailRatio, VolumeBundleData, VolumeTier, WIDGET_CONFIG_DEFAULTS, WidgetConfig, applyWidgetConfigVars, calculateDiscount, calculateTierSavings, computeBundleSaleCents, computeFixedPricing, createStorefrontClient, fetchBundlesForProduct, formatCents, formatCountdown, formatMoney, formatUnitPrice, getActiveTier, injectCustomCss, mergeWidgetConfig, observeImpression, parseCents, parseMetaobjectBundle, parseMetaobjectBundleStrict, parseOutOfStockBehavior, percentageDiscountUnit, productsForStep, reportAddToCart, reportImpression, sanitizeCustomCss, stepHeadroom, thumbnailRatioVars, transformImageUrl, validateQuantity } from '@lime-bundles/core';
+import { CartLineInput, BuyerResolver, WidgetConfig, ProductVariant, ParsedBundle } from '@lime-bundles/core';
+export { BUNDLES_FOR_PRODUCT_QUERY, BUNDLE_METAOBJECT_QUERY, BogoBundleData, BundleParseError, BundleType, CartLineInput, CountdownConfig, CtaConfig, DiscountConfig, FixedBundleData, FixedBundlePricing, HeaderConfig, ImageTransform, LayoutConfig, MixMatchBundleData, MultiStepBundleData, ParsedBundle, ParsedMultiStep, PopularBadgeConfig, PricingConfig, PricingRow, Product, ProductListConfig, ProductVariant, SHOP_SETTINGS_QUERY, SavingsBarConfig, StorefrontApiError, ThumbnailRatio, VolumeBundleData, VolumeTier, WIDGET_CONFIG_DEFAULTS, WidgetConfig, applyWidgetConfigVars, calculateDiscount, calculateTierSavings, computeBundleSaleCents, computeFixedPricing, createStorefrontClient, fetchBundlesForProduct, formatCents, formatCountdown, formatMoney, formatUnitPrice, getActiveTier, injectCustomCss, mergeWidgetConfig, observeImpression, parseCents, parseMetaobjectBundle, parseMetaobjectBundleStrict, percentageDiscountUnit, productsForStep, reportAddToCart, reportImpression, sanitizeCustomCss, stepHeadroom, thumbnailRatioVars, transformImageUrl, validateQuantity } from '@lime-bundles/core';
 
 /**
  * Shared props for bundle components.
@@ -55,7 +55,26 @@ interface BundleComponentProps {
 
 declare function FixedBundle(props: BundleComponentProps): react_jsx_runtime.JSX.Element | null;
 
-declare function MixMatchBundle(props: BundleComponentProps): react_jsx_runtime.JSX.Element | null;
+interface MixMatchBundleProps extends BundleComponentProps {
+    /**
+     * Handle of the product page this component is rendered on, when there is
+     * one. Enables the theme widget's courtesy seed: with no required products,
+     * the bundle starts with this product (or the first that qualifies)
+     * pre-added at its rule minimum. Omit on non-product pages to start empty.
+     */
+    productHandle?: string | null;
+}
+declare function MixMatchBundle(props: MixMatchBundleProps): react_jsx_runtime.JSX.Element | null;
+
+interface BundleCountdownProps {
+    /** The bundle's ISO end date; renders nothing when null. */
+    endsAt: string | null | undefined;
+    /** The bundle's widget config — gates on `countdown.showCountdown`. */
+    widgetConfig: WidgetConfig | undefined;
+    /** Label text; defaults to the theme's translation default. */
+    label?: string;
+}
+declare function BundleCountdown({ endsAt, widgetConfig, label, }: BundleCountdownProps): react_jsx_runtime.JSX.Element | null;
 
 declare function VolumeBundle(props: BundleComponentProps): react_jsx_runtime.JSX.Element | null;
 
@@ -84,8 +103,9 @@ interface UseVariantSelectionOptions {
     /** Positional option names for the product, e.g. `['Size', 'Color']`. */
     optionNames: ReadonlyArray<string>;
     /**
-     * Optional initial variant. Defaults to the first available variant, or
-     * the first variant if none are available.
+     * Optional initial variant. Defaults to the first variant that can cover
+     * the slot (per `requiredQtyFor` when supplied), then the first available
+     * variant, then the first variant.
      */
     initialVariant?: ProductVariant | null;
     /**
@@ -95,6 +115,12 @@ interface UseVariantSelectionOptions {
      * order is variant-discovery order (which may not match Shopify admin).
      */
     optionValuesByPosition?: ReadonlyArray<ReadonlyArray<string>>;
+    /**
+     * Per-variant required quantity for the bundle slot this picker fills.
+     * When provided, dropdown availability is quantity-aware (a variant short
+     * of the bundle's needs greys out) instead of plain `availableForSale`.
+     */
+    requiredQtyFor?: (variantId: string) => number;
 }
 interface UseVariantSelectionResult {
     /** Positional option values matching `optionNames`. */
@@ -109,7 +135,7 @@ interface UseVariantSelectionResult {
         disabled: boolean;
     }>;
 }
-declare function useVariantSelection({ variants, optionNames, initialVariant, optionValuesByPosition, }: UseVariantSelectionOptions): UseVariantSelectionResult;
+declare function useVariantSelection({ variants, optionNames, initialVariant, optionValuesByPosition, requiredQtyFor, }: UseVariantSelectionOptions): UseVariantSelectionResult;
 
 /**
  * Framework-agnostic async fetcher for bundle data.
@@ -162,27 +188,6 @@ interface FetchBundleDataOptions {
 }
 declare function fetchBundleData(options: FetchBundleDataOptions): Promise<ParsedBundle>;
 
-/**
- * Best-effort fetch for the shop's `$app` settings metafields.
- *
- * Returns the raw custom CSS (still needs sanitization before injection — see
- * `injectCustomCss` from core) and the shop-wide out-of-stock behaviour.
- *
- * **Per-shop in-memory cache.** Multiple `<FixedBundle>` / `<VolumeBundle>` /
- * `<MixMatchBundle>` components on the same page share one network request —
- * the first caller fetches, concurrent callers await the same promise, and
- * resolved values are cached so subsequent mounts return instantly. Failures
- * are NOT cached so the next caller retries.
- *
- * The cache lives for the life of the JS module (typically one page load).
- * Merchants updating settings see changes on the next page load. The cache is
- * exposed as `__clearShopSettingsCache` for test use only.
- *
- * Both metafields ride in one query. The out-of-stock behaviour must be in hand
- * *before* a bundle renders — a component can't retroactively un-render itself —
- * so components await this alongside their bundle data rather than after it.
- */
-
 interface FetchShopSettingsOptions {
     shopDomain: string;
     storefrontAccessToken: string;
@@ -192,26 +197,14 @@ interface FetchShopSettingsOptions {
 interface ShopSettings {
     /** Raw, unsanitized merchant CSS. Null when unset. */
     customCss: string | null;
-    /** Shop-wide handling of products the store can't sell. */
-    outOfStockBehavior: OutOfStockBehavior;
 }
 declare function fetchShopSettings(options: FetchShopSettingsOptions): Promise<ShopSettings>;
 /**
- * Same fetch, never rejects. Components that need the out-of-stock behaviour
- * to render at all use this — a failed settings request must not stop a bundle
- * from appearing.
+ * Same fetch, never rejects — a failed settings request must not stop a
+ * bundle from appearing.
  */
 declare function fetchShopSettingsOrDefault(options: FetchShopSettingsOptions): Promise<ShopSettings>;
 
-interface UseShopSettingsOptions {
-    shopDomain: string;
-    storefrontAccessToken: string;
-}
-interface UseShopSettingsResult {
-    outOfStockBehavior: OutOfStockBehavior;
-}
-declare function useShopSettings(options: UseShopSettingsOptions): UseShopSettingsResult;
-
 type FetchShopCustomCssOptions = FetchShopSettingsOptions;
 /** @deprecated Use `fetchShopSettings().customCss`. */
 declare function fetchShopCustomCss(options: FetchShopCustomCssOptions): Promise<string | null>;
@@ -285,4 +278,4 @@ declare function useAnalytics(options: UseAnalyticsOptions): {
 
 declare function useWidgetConfigVars(config: WidgetConfig | null | undefined): (el: HTMLElement | null) => void;
 
-export { BogoBundle, type BundleComponentProps, type FetchBundleDataOptions, type FetchShopCustomCssOptions, type FetchShopSettingsOptions, FixedBundle, MixMatchBundle, MultiStepBundle, type ShopSettings, type UseBundleDataOptions, type UseBundleDataResult, type UseBundlesForProductOptions, type UseBundlesForProductResult, type UseShopSettingsOptions, type UseShopSettingsResult, type UseVariantSelectionOptions, type UseVariantSelectionResult, VariantDropdown, type VariantDropdownOption, type VariantDropdownProps, VolumeBundle, fetchBundleData, fetchShopCustomCss, fetchShopSettings, fetchShopSettingsOrDefault, useAnalytics, useBundleData, useBundlesForProduct, useShopSettings, useVariantSelection, useWidgetConfigVars };
+export { BogoBundle, type BundleComponentProps, BundleCountdown, type BundleCountdownProps, type FetchBundleDataOptions, type FetchShopCustomCssOptions, type FetchShopSettingsOptions, FixedBundle, MixMatchBundle, type MixMatchBundleProps, MultiStepBundle, type ShopSettings, type UseBundleDataOptions, type UseBundleDataResult, type UseBundlesForProductOptions, type UseBundlesForProductResult, type UseVariantSelectionOptions, type UseVariantSelectionResult, VariantDropdown, type VariantDropdownOption, type VariantDropdownProps, VolumeBundle, fetchBundleData, fetchShopCustomCss, fetchShopSettings, fetchShopSettingsOrDefault, useAnalytics, useBundleData, useBundlesForProduct, useVariantSelection, useWidgetConfigVars };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { CartLineInput, BuyerResolver, ProductVariant, ParsedBundle, OutOfStockBehavior, WidgetConfig } from '@lime-bundles/core';
-export { BUNDLES_FOR_PRODUCT_QUERY, BUNDLE_METAOBJECT_QUERY, BogoBundleData, BundleParseError, BundleType, CartLineInput, CountdownConfig, CtaConfig, DEFAULT_OUT_OF_STOCK_BEHAVIOR, DiscountConfig, FixedBundleData, FixedBundlePricing, HeaderConfig, ImageTransform, LayoutConfig, MixMatchBundleData, MultiStepBundleData, OutOfStockBehavior, ParsedBundle, ParsedMultiStep, PopularBadgeConfig, PricingConfig, PricingRow, Product, ProductListConfig, ProductVariant, SHOP_SETTINGS_QUERY, SavingsBarConfig, StorefrontApiError, ThumbnailRatio, VolumeBundleData, VolumeTier, WIDGET_CONFIG_DEFAULTS, WidgetConfig, applyWidgetConfigVars, calculateDiscount, calculateTierSavings, computeBundleSaleCents, computeFixedPricing, createStorefrontClient, fetchBundlesForProduct, formatCents, formatCountdown, formatMoney, formatUnitPrice, getActiveTier, injectCustomCss, mergeWidgetConfig, observeImpression, parseCents, parseMetaobjectBundle, parseMetaobjectBundleStrict, parseOutOfStockBehavior, percentageDiscountUnit, productsForStep, reportAddToCart, reportImpression, sanitizeCustomCss, stepHeadroom, thumbnailRatioVars, transformImageUrl, validateQuantity } from '@lime-bundles/core';
+import { CartLineInput, BuyerResolver, WidgetConfig, ProductVariant, ParsedBundle } from '@lime-bundles/core';
+export { BUNDLES_FOR_PRODUCT_QUERY, BUNDLE_METAOBJECT_QUERY, BogoBundleData, BundleParseError, BundleType, CartLineInput, CountdownConfig, CtaConfig, DiscountConfig, FixedBundleData, FixedBundlePricing, HeaderConfig, ImageTransform, LayoutConfig, MixMatchBundleData, MultiStepBundleData, ParsedBundle, ParsedMultiStep, PopularBadgeConfig, PricingConfig, PricingRow, Product, ProductListConfig, ProductVariant, SHOP_SETTINGS_QUERY, SavingsBarConfig, StorefrontApiError, ThumbnailRatio, VolumeBundleData, VolumeTier, WIDGET_CONFIG_DEFAULTS, WidgetConfig, applyWidgetConfigVars, calculateDiscount, calculateTierSavings, computeBundleSaleCents, computeFixedPricing, createStorefrontClient, fetchBundlesForProduct, formatCents, formatCountdown, formatMoney, formatUnitPrice, getActiveTier, injectCustomCss, mergeWidgetConfig, observeImpression, parseCents, parseMetaobjectBundle, parseMetaobjectBundleStrict, percentageDiscountUnit, productsForStep, reportAddToCart, reportImpression, sanitizeCustomCss, stepHeadroom, thumbnailRatioVars, transformImageUrl, validateQuantity } from '@lime-bundles/core';
 
 /**
  * Shared props for bundle components.
@@ -55,7 +55,26 @@ interface BundleComponentProps {
 
 declare function FixedBundle(props: BundleComponentProps): react_jsx_runtime.JSX.Element | null;
 
-declare function MixMatchBundle(props: BundleComponentProps): react_jsx_runtime.JSX.Element | null;
+interface MixMatchBundleProps extends BundleComponentProps {
+    /**
+     * Handle of the product page this component is rendered on, when there is
+     * one. Enables the theme widget's courtesy seed: with no required products,
+     * the bundle starts with this product (or the first that qualifies)
+     * pre-added at its rule minimum. Omit on non-product pages to start empty.
+     */
+    productHandle?: string | null;
+}
+declare function MixMatchBundle(props: MixMatchBundleProps): react_jsx_runtime.JSX.Element | null;
+
+interface BundleCountdownProps {
+    /** The bundle's ISO end date; renders nothing when null. */
+    endsAt: string | null | undefined;
+    /** The bundle's widget config — gates on `countdown.showCountdown`. */
+    widgetConfig: WidgetConfig | undefined;
+    /** Label text; defaults to the theme's translation default. */
+    label?: string;
+}
+declare function BundleCountdown({ endsAt, widgetConfig, label, }: BundleCountdownProps): react_jsx_runtime.JSX.Element | null;
 
 declare function VolumeBundle(props: BundleComponentProps): react_jsx_runtime.JSX.Element | null;
 
@@ -84,8 +103,9 @@ interface UseVariantSelectionOptions {
     /** Positional option names for the product, e.g. `['Size', 'Color']`. */
     optionNames: ReadonlyArray<string>;
     /**
-     * Optional initial variant. Defaults to the first available variant, or
-     * the first variant if none are available.
+     * Optional initial variant. Defaults to the first variant that can cover
+     * the slot (per `requiredQtyFor` when supplied), then the first available
+     * variant, then the first variant.
      */
     initialVariant?: ProductVariant | null;
     /**
@@ -95,6 +115,12 @@ interface UseVariantSelectionOptions {
      * order is variant-discovery order (which may not match Shopify admin).
      */
     optionValuesByPosition?: ReadonlyArray<ReadonlyArray<string>>;
+    /**
+     * Per-variant required quantity for the bundle slot this picker fills.
+     * When provided, dropdown availability is quantity-aware (a variant short
+     * of the bundle's needs greys out) instead of plain `availableForSale`.
+     */
+    requiredQtyFor?: (variantId: string) => number;
 }
 interface UseVariantSelectionResult {
     /** Positional option values matching `optionNames`. */
@@ -109,7 +135,7 @@ interface UseVariantSelectionResult {
         disabled: boolean;
     }>;
 }
-declare function useVariantSelection({ variants, optionNames, initialVariant, optionValuesByPosition, }: UseVariantSelectionOptions): UseVariantSelectionResult;
+declare function useVariantSelection({ variants, optionNames, initialVariant, optionValuesByPosition, requiredQtyFor, }: UseVariantSelectionOptions): UseVariantSelectionResult;
 
 /**
  * Framework-agnostic async fetcher for bundle data.
@@ -162,27 +188,6 @@ interface FetchBundleDataOptions {
 }
 declare function fetchBundleData(options: FetchBundleDataOptions): Promise<ParsedBundle>;
 
-/**
- * Best-effort fetch for the shop's `$app` settings metafields.
- *
- * Returns the raw custom CSS (still needs sanitization before injection — see
- * `injectCustomCss` from core) and the shop-wide out-of-stock behaviour.
- *
- * **Per-shop in-memory cache.** Multiple `<FixedBundle>` / `<VolumeBundle>` /
- * `<MixMatchBundle>` components on the same page share one network request —
- * the first caller fetches, concurrent callers await the same promise, and
- * resolved values are cached so subsequent mounts return instantly. Failures
- * are NOT cached so the next caller retries.
- *
- * The cache lives for the life of the JS module (typically one page load).
- * Merchants updating settings see changes on the next page load. The cache is
- * exposed as `__clearShopSettingsCache` for test use only.
- *
- * Both metafields ride in one query. The out-of-stock behaviour must be in hand
- * *before* a bundle renders — a component can't retroactively un-render itself —
- * so components await this alongside their bundle data rather than after it.
- */
-
 interface FetchShopSettingsOptions {
     shopDomain: string;
     storefrontAccessToken: string;
@@ -192,26 +197,14 @@ interface FetchShopSettingsOptions {
 interface ShopSettings {
     /** Raw, unsanitized merchant CSS. Null when unset. */
     customCss: string | null;
-    /** Shop-wide handling of products the store can't sell. */
-    outOfStockBehavior: OutOfStockBehavior;
 }
 declare function fetchShopSettings(options: FetchShopSettingsOptions): Promise<ShopSettings>;
 /**
- * Same fetch, never rejects. Components that need the out-of-stock behaviour
- * to render at all use this — a failed settings request must not stop a bundle
- * from appearing.
+ * Same fetch, never rejects — a failed settings request must not stop a
+ * bundle from appearing.
  */
 declare function fetchShopSettingsOrDefault(options: FetchShopSettingsOptions): Promise<ShopSettings>;
 
-interface UseShopSettingsOptions {
-    shopDomain: string;
-    storefrontAccessToken: string;
-}
-interface UseShopSettingsResult {
-    outOfStockBehavior: OutOfStockBehavior;
-}
-declare function useShopSettings(options: UseShopSettingsOptions): UseShopSettingsResult;
-
 type FetchShopCustomCssOptions = FetchShopSettingsOptions;
 /** @deprecated Use `fetchShopSettings().customCss`. */
 declare function fetchShopCustomCss(options: FetchShopCustomCssOptions): Promise<string | null>;
@@ -285,4 +278,4 @@ declare function useAnalytics(options: UseAnalyticsOptions): {
 
 declare function useWidgetConfigVars(config: WidgetConfig | null | undefined): (el: HTMLElement | null) => void;
 
-export { BogoBundle, type BundleComponentProps, type FetchBundleDataOptions, type FetchShopCustomCssOptions, type FetchShopSettingsOptions, FixedBundle, MixMatchBundle, MultiStepBundle, type ShopSettings, type UseBundleDataOptions, type UseBundleDataResult, type UseBundlesForProductOptions, type UseBundlesForProductResult, type UseShopSettingsOptions, type UseShopSettingsResult, type UseVariantSelectionOptions, type UseVariantSelectionResult, VariantDropdown, type VariantDropdownOption, type VariantDropdownProps, VolumeBundle, fetchBundleData, fetchShopCustomCss, fetchShopSettings, fetchShopSettingsOrDefault, useAnalytics, useBundleData, useBundlesForProduct, useShopSettings, useVariantSelection, useWidgetConfigVars };
+export { BogoBundle, type BundleComponentProps, BundleCountdown, type BundleCountdownProps, type FetchBundleDataOptions, type FetchShopCustomCssOptions, type FetchShopSettingsOptions, FixedBundle, MixMatchBundle, type MixMatchBundleProps, MultiStepBundle, type ShopSettings, type UseBundleDataOptions, type UseBundleDataResult, type UseBundlesForProductOptions, type UseBundlesForProductResult, type UseVariantSelectionOptions, type UseVariantSelectionResult, VariantDropdown, type VariantDropdownOption, type VariantDropdownProps, VolumeBundle, fetchBundleData, fetchShopCustomCss, fetchShopSettings, fetchShopSettingsOrDefault, useAnalytics, useBundleData, useBundlesForProduct, useVariantSelection, useWidgetConfigVars };