@asteby/storefront-react 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ComponentPropsWithoutRef, ComponentType, FormEvent } from 'react';
-import { StorefrontClient, Shop, StorefrontClientOptions, Cart, CartLineInput, CartLineMerchandise, CartLineUpdateInput, CartBuyerInput, AddressInput, DeliveryInput, DeliveryOptions, ProductVariant, Product, Image, Collection, Section, Theme, GeoPoint, ShopBranch, Money } from '@asteby/storefront';
+import { StorefrontClient, Shop, StorefrontClientOptions, Cart, CartLineInput, CartLineMerchandise, CartLineUpdateInput, CartBuyerInput, AddressInput, DeliveryInput, DeliveryOptions, Availability, ProductVariant, Product, resolveAvailability, AvailabilityMessages, CartLine, CartLineProblem as CartLineProblem$1, AvailabilityView, Image, Collection, ResolveAvailabilityOptions, Section, Theme, GeoPoint, ShopBranch, Money } from '@asteby/storefront';
 export { D as DEFAULT_IMAGE_WIDTHS, I as Image, a as ImageLoader, b as ImageProps, M as Money, c as MoneyProps, P as ProductPrice, d as ProductPriceProps, e as defaultImageLoader } from './components-B5XhSH-m.cjs';
 import { OpeningHours, GeoPoint as GeoPoint$1, OpenStatus as OpenStatus$1 } from '@asteby/storefront/geo';
 
@@ -135,6 +135,8 @@ type ProductOptionValueState = {
     available: boolean;
     /** The variant this value would select, if it exists. */
     variant: ProductVariant | null;
+    /** Availability of that variant (polyfilled for servers older than contract 1.1); with the other options not chosen yet, the best among matching variants. `null` when no variant matches. Feed it to `<VariantOptionState availability>`. */
+    availability: Availability | null;
     /** Query string (`?Talla=M&Color=Rojo`) selecting this value, preserving other params. */
     search: string;
 };
@@ -196,13 +198,130 @@ declare function toMerchandise(product: Pick<Product, 'handle' | 'title' | 'feat
 type AddToCartButtonProps = Omit<ComponentPropsWithoutRef<'button'>, 'onClick'> & {
     variantId: string | null | undefined;
     quantity?: number;
+    /**
+     * Availability of the variant (server `availability`, or the variant itself to polyfill). When given: the label
+     * comes from the server state ("Agotado", "Pedir bajo pedido"...) unless `children` is set, the button is
+     * disabled when it cannot be bought, and the quantity is capped at `max_per_order`.
+     */
+    availability?: Availability | null;
+    /** Variant to derive the availability from when the server did not send it. */
+    availabilitySource?: ProductVariant | null;
+    /** Polyfill only: shop-level low-stock threshold. */
+    lowStockThreshold?: number | null;
+    /** BCP 47; defaults to the provider locale. */
+    locale?: string;
     /** Variant data for an instant optimistic cart line. */
     merchandise?: CartLineMerchandise;
     onAdded?: () => void;
     onClick?: ComponentPropsWithoutRef<'button'>['onClick'];
 };
 /** Adds a variant to the cart via `useCart().addLines`. Disabled without a variant or while adding. */
-declare function AddToCartButton({ variantId, quantity, merchandise, onAdded, onClick, disabled, children, type, ...rest }: AddToCartButtonProps): react.JSX.Element;
+declare function AddToCartButton({ variantId, quantity, availability, availabilitySource, lowStockThreshold, locale, merchandise, onAdded, onClick, disabled, children, type, ...rest }: AddToCartButtonProps): react.JSX.Element;
+
+/** Visually hidden text for screen readers. */
+declare function SrOnly({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+type AvailabilitySource = Parameters<typeof resolveAvailability>[0];
+type AvailabilityInput = {
+    /** Availability sent by the server. */
+    availability?: Availability | null;
+    /** Variant or product: used when `availability` is absent (polyfill for servers older than contract 1.1). */
+    source?: AvailabilitySource | null;
+    /** Polyfill only: shop-level low-stock threshold (never hard-coded here). */
+    lowStockThreshold?: number | null;
+    /** BCP 47; defaults to the provider locale, then `es-MX`. */
+    locale?: string;
+    /** Per-key text overrides. */
+    messages?: Partial<AvailabilityMessages>;
+};
+/** `AvailabilityView` for a server `availability` or a variant/product (polyfilled). `null` when nothing is given. */
+declare function useAvailability(input: AvailabilityInput): AvailabilityView | null;
+type AvailabilityBadgeProps = AvailabilityInput & {
+    /**
+     * `card` (listing): renders `null` for plain `in_stock` so cards are not saturated.
+     * `detail` (product page): always renders, with the ETA and the order cap.
+     */
+    placement?: 'card' | 'detail';
+    /** Announce changes (e.g. after the client refreshes the stock): `role="status"`. */
+    live?: boolean;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/**
+ * Availability label. `data-availability` is the status and `data-tone` the tone, so a
+ * card can dim its image with CSS (`[data-availability=out_of_stock]`).
+ */
+declare function AvailabilityBadge({ availability, source, lowStockThreshold, locale, messages, placement, live, ...rest }: AvailabilityBadgeProps): react.JSX.Element | null;
+type VariantOptionStateProps = AvailabilityInput & {
+    /** The option text (e.g. the flavor). */
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/**
+ * Content for one option of a flavor/variant selector. A sold-out option is struck through
+ * (`<s>`) and announced as "agotado" to screen readers; it stays selectable so the buyer can
+ * see it and subscribe. Backorder / preorder options get a visible tag. Plain in-stock: just the text.
+ * Without any availability it renders `children` untouched.
+ */
+declare function VariantOptionState({ children, availability, source, lowStockThreshold, locale, messages, ...rest }: VariantOptionStateProps): react.JSX.Element;
+type RestockNotifyFormProps = AvailabilityInput & {
+    sku: string;
+    /** Market (country) of the buyer, if the shop has several. */
+    market?: string;
+    /** Offer a phone / WhatsApp field next to the email. Default false (email only). */
+    allowPhone?: boolean;
+    /**
+     * Destination of the native POST. Without JavaScript the browser posts `sku`, `email`, `phone`, `locale`,
+     * `market` and `consent` there, so the shop's own route can call `client.restock.subscribe`. Default: the current page.
+     */
+    action?: string;
+    /** Client override (defaults to the `StorefrontProvider` client). */
+    client?: StorefrontClient;
+    /** With JavaScript the form submits through the SDK; set `false` to always post natively. */
+    enhance?: boolean;
+    onSubscribed?: () => void;
+    onError?: (error: unknown) => void;
+} & Omit<ComponentPropsWithoutRef<'form'>, 'action' | 'method' | 'onSubmit' | 'children'>;
+/**
+ * Subscription form. Renders `null` unless the server says `notify_available` and the state is
+ * `out_of_stock`. Works without JavaScript (native POST); with it, submits via the SDK and shows
+ * the result in place (`role="status"` / `role="alert"`).
+ */
+declare function RestockNotifyForm({ sku, market, allowPhone, action, client: clientProp, enhance, onSubscribed, onError, availability, source, lowStockThreshold, locale, messages, ...rest }: RestockNotifyFormProps): react.JSX.Element | null;
+type CartLineProblemProps = {
+    /** The cart line; its `problem` is shown. Renders `null` when there is none. */
+    line: Pick<CartLine, 'id' | 'quantity'> & {
+        problem?: CartLineProblem$1 | null;
+    };
+    locale?: string;
+    messages?: Partial<AvailabilityMessages>;
+    /** Defaults to `useCart().updateLines` when inside a `CartProvider`. */
+    onAdjust?: (lineId: string, quantity: number) => void | Promise<unknown>;
+    /** Defaults to `useCart().removeLines` when inside a `CartProvider`. */
+    onRemove?: (lineId: string) => void | Promise<unknown>;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
+/**
+ * Problem of one cart line, shown as soon as the cart loads (before checkout): "Ya no hay existencias" or
+ * "Solo puedes llevar N", with "Ajustar a N" (only when the server lets the number be seen) and "Quitar".
+ */
+declare function CartLineProblem({ line, locale, messages, onAdjust, onRemove, ...rest }: CartLineProblemProps): react.JSX.Element | null;
+type StockConflictAlertProps = {
+    /** Error to inspect. Defaults to `useCart().error`. Renders `null` unless it is a `409 insufficient_stock`. */
+    error?: unknown;
+    /** Cart used to name the affected lines. Defaults to `useCart().cart`. */
+    cart?: Cart | null;
+    locale?: string;
+    messages?: Partial<AvailabilityMessages>;
+    onAdjust?: (lineId: string, quantity: number) => void | Promise<unknown>;
+    onRemove?: (lineId: string) => void | Promise<unknown>;
+    onDismiss?: () => void;
+    /** Move focus to the alert when it appears (default true). */
+    autoFocus?: boolean;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'role' | 'tabIndex'>;
+/**
+ * Recoverable stock conflict. The cart and the form data are NOT touched: it shows our own text (never the raw
+ * `error.message`), the affected lines with "Ajustar a N" / "Quitar", and takes focus (`role="alert"`) without
+ * moving the page. Drop it above the checkout form: `<StockConflictAlert />` reads the error from the cart.
+ */
+declare function StockConflictAlert({ error: errorProp, cart: cartProp, locale, messages, onAdjust, onRemove, onDismiss, autoFocus, ...rest }: StockConflictAlertProps): react.JSX.Element | null;
 
 /**
  * SEO helpers: pure functions returning meta descriptors (React Router v7
@@ -248,12 +367,11 @@ type SeoMetaInput = {
 };
 /** Generic title/description/canonical/Open Graph/Twitter descriptors. */
 declare function seoMeta(input: SeoMetaInput): MetaDescriptor[];
-/** Product page descriptors (`og:type=product` and price tags). */
-declare function productMeta(product: Product, shop: Pick<Shop, 'name' | 'locale'> | null, url: string): MetaDescriptor[];
+declare function productMeta(product: Product, shop: Pick<Shop, 'name' | 'locale'> | null, url: string, options?: ResolveAvailabilityOptions): MetaDescriptor[];
 /** Collection page descriptors. */
 declare function collectionMeta(collection: Collection, shop: Pick<Shop, 'name' | 'locale'> | null, url: string): MetaDescriptor[];
 /** schema.org `Product` with one `Offer` per variant. */
-declare function productJsonLd(product: Product, shop: Pick<Shop, 'name' | 'domain'> | null, url: string): JsonLdObject;
+declare function productJsonLd(product: Product, shop: Pick<Shop, 'name' | 'domain'> | null, url: string, options?: ResolveAvailabilityOptions): JsonLdObject;
 /** schema.org `Organization` for the shop (logo, contact, url). */
 declare function organizationJsonLd(shop: Shop, url?: string): JsonLdObject;
 type LocalBusinessOptions = {
@@ -302,6 +420,97 @@ type JsonLdProps = {
 /** Renders `<script type="application/ld+json">` safely (works in SSR). */
 declare function JsonLd({ data, nonce }: JsonLdProps): react.JSX.Element | null;
 
+/** Types OPS ships built in; they cannot be redefined through the API. */
+declare const OPS_BUILTIN_SECTION_TYPES: readonly ["hero", "product_grid", "collection_list", "rich_text", "faq", "image_with_text"];
+declare const OPS_PROP_KINDS: readonly ["text", "textarea", "richtext", "image", "link", "number", "select", "boolean", "collection", "collection_list", "product", "product_list", "list"];
+type OpsPropKind = (typeof OPS_PROP_KINDS)[number];
+type OpsSectionProp = {
+    key: string;
+    kind: OpsPropKind;
+    label: string;
+    required?: boolean;
+    default?: unknown;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    min?: number;
+    max?: number;
+    fields?: OpsSectionProp[];
+};
+type OpsSectionType = {
+    type: string;
+    label: string;
+    description?: string;
+    category?: string;
+    schema: {
+        props: OpsSectionProp[];
+    };
+    max_per_page?: number;
+};
+type SectionTypeIssue = {
+    /** Dotted path, e.g. `promo.schema.props[1].fields[0].key`. */
+    path: string;
+    message: string;
+};
+type SectionTypeWarning = {
+    type: string;
+    /** Prop key when the warning is about a single prop. */
+    prop?: string;
+    message: string;
+};
+declare class SectionTypesValidationError extends Error {
+    readonly issues: SectionTypeIssue[];
+    constructor(issues: SectionTypeIssue[]);
+}
+type ToOpsOptions = {
+    /** Skip OPS built-in types (default true). */
+    excludeBuiltin?: boolean;
+    /**
+     * Prop keys OPS already knows for each built-in type (e.g. `{ hero: ['title','subtitle'] }`).
+     * With it, only the extra local props are warned about; without it, every
+     * locally-defined built-in type gets one generic warning.
+     */
+    builtinProps?: Record<string, readonly string[]>;
+};
+type ToOpsResult = {
+    types: OpsSectionType[];
+    warnings: SectionTypeWarning[];
+};
+/** Local mirror of the OPS validation, so mistakes surface before the request. */
+declare function validateOpsSectionTypes(types: readonly OpsSectionType[]): SectionTypeIssue[];
+type DefinitionsSource = {
+    definitions(): SectionDefinition<any, any>[];
+} | readonly SectionDefinition<any, any>[];
+/**
+ * Converts the registry (or a list of definitions) to OPS section types.
+ * Throws `SectionTypesValidationError` (with `issues`) when something would
+ * be rejected by OPS.
+ */
+declare function sectionTypesToOps(source: DefinitionsSource, options?: ToOpsOptions): ToOpsResult;
+type SectionTypesTarget = {
+    request<T>(spec: {
+        method: 'PUT';
+        path: string;
+        body?: unknown;
+    }): Promise<T>;
+} | {
+    baseUrl: string;
+    token: string;
+    fetch?: typeof fetch;
+};
+type SyncResult = {
+    created: number;
+    updated: number;
+    warnings: SectionTypeWarning[];
+};
+/**
+ * Validates locally and then `PUT`s the section types to OPS. Needs an `sk_`
+ * token with `content:write`. `target` is a `createStorefrontClient()` client or
+ * `{ baseUrl, token, fetch? }`. Returns `{ created, updated, warnings }`.
+ */
+declare function syncSectionTypes(target: SectionTypesTarget, source: DefinitionsSource, options?: ToOpsOptions): Promise<SyncResult>;
+
 type SectionPropKind = 'text' | 'textarea' | 'richtext' | 'number' | 'boolean' | 'url' | 'image' | 'color' | 'select' | 'collection' | 'product' | 'products' | 'list';
 type SectionPropSchema = {
     label: string;
@@ -347,6 +556,10 @@ type SectionDefinition<P = Record<string, unknown>, C = any> = {
     type: string;
     label?: string;
     description?: string;
+    /** OPS editor grouping (only used when exporting to OPS). */
+    category?: string;
+    /** Max instances per page (only used when exporting to OPS). */
+    maxPerPage?: number;
     schema: SectionSchema;
     component: ComponentType<SectionComponentProps<P, C>>;
 };
@@ -367,6 +580,8 @@ declare function defineSection<const S extends SectionSchema, C = any>(definitio
     type: string;
     label?: string;
     description?: string;
+    category?: string;
+    maxPerPage?: number;
     schema: S;
     component: ComponentType<SectionComponentProps<InferSectionProps<S>, C>>;
 }): SectionDefinition<InferSectionProps<S>, C>;
@@ -395,6 +610,12 @@ declare class SectionRegistry {
     definitions(): SectionDefinition<any, any>[];
     /** JSON Schemas of every registered section, keyed by type. */
     toJSONSchema(): Record<string, Record<string, unknown>>;
+    /**
+     * Section types in the OPS `storefront_content` format, ready for
+     * `PUT /storefront/content/section-types`. Throws `SectionTypesValidationError`
+     * on anything OPS would reject; `warnings` flags built-in types.
+     */
+    toOpsSectionTypes(options?: ToOpsOptions): ToOpsResult;
 }
 declare function createSectionRegistry(definitions?: readonly SectionDefinition<any, any>[]): SectionRegistry;
 type SectionsProps<C = unknown> = {
@@ -655,4 +876,4 @@ type NearestLocationFormProps<L extends ShopBranch = ShopBranch> = {
  */
 declare function NearestLocationForm<L extends ShopBranch = ShopBranch>({ locations, action, name, defaultValue, onSubmitPostalCode, onLocate, labels, children, ...rest }: NearestLocationFormProps<L>): react.JSX.Element | null;
 
-export { AddToCartButton, type AddToCartButtonProps, type BreadcrumbItem, CART_COOKIE_NAME, type CartContextValue, type CartCookieOptions, type CartLineAddInput, CartProvider, type CartProviderProps, type CartStatus, DirectionsLink, type DirectionsLinkProps, type FaqItem, type GeolocationErrorCode, type GeolocationFailure, type GeolocationPermission, type InferSectionProps, JsonLd, type JsonLdObject, type JsonLdProps, type LocalBusinessOptions, type LocationItemState, LocationList, type LocationListProps, LocationPicker, type LocationPickerProps, type MetaDescriptor, type NearbyLocation, NearestLocationForm, type NearestLocationFormLabels, type NearestLocationFormProps, OpenStatus, type OpenStatusLabels, type OpenStatusProps, type PickupInfo, PickupOption, type PickupOptionProps, type ProductOptionState, type ProductOptionValueState, type ProductOptionsState, SELECTED_LOCATION_PARAM, SELECTED_LOCATION_STORAGE_KEY, type SectionComponentProps, type SectionDefinition, type SectionPropError, type SectionPropKind, type SectionPropSchema, SectionRegistry, type SectionSchema, Sections, type SectionsProps, type SeoMetaInput, type StorefrontContextValue, StorefrontProvider, type StorefrontProviderProps, type ThemeCssOptions, ThemeStyle, type ThemeStyleProps, type UseGeolocationOptions, type UseGeolocationResult, type UseNearestLocationsOptions, type UseNearestLocationsResult, type UseProductOptionsConfig, type UseSelectedLocationOptions, type UseSelectedLocationResult, VariantSelector, type VariantSelectorProps, type VariantSelectorRenderProps, breadcrumbJsonLd, collectionJsonLd, collectionMeta, createSectionRegistry, defineSection, faqJsonLd, getCartIdFromCookie, isSafeCssValue, localBusinessJsonLd, openingHoursJsonLd, optimisticCart, organizationJsonLd, productJsonLd, productMeta, readCartCookie, readSelectedLocationId, resolveSectionProps, sectionJsonSchema, seoMeta, serializeCartCookie, serializeJsonLd, themeFontsHref, themeToCss, themeToCssVariables, toMerchandise, tokenName, useCart, useGeolocation, useNearestLocations, useOptionalCart, useOptionalStorefront, useProductOptions, useSelectedLocation, useStorefront, useStorefrontClient, writeCartCookie };
+export { AddToCartButton, type AddToCartButtonProps, AvailabilityBadge, type AvailabilityBadgeProps, type AvailabilityInput, type BreadcrumbItem, CART_COOKIE_NAME, type CartContextValue, type CartCookieOptions, type CartLineAddInput, CartLineProblem, type CartLineProblemProps, CartProvider, type CartProviderProps, type CartStatus, DirectionsLink, type DirectionsLinkProps, type FaqItem, type GeolocationErrorCode, type GeolocationFailure, type GeolocationPermission, type InferSectionProps, JsonLd, type JsonLdObject, type JsonLdProps, type LocalBusinessOptions, type LocationItemState, LocationList, type LocationListProps, LocationPicker, type LocationPickerProps, type MetaDescriptor, type NearbyLocation, NearestLocationForm, type NearestLocationFormLabels, type NearestLocationFormProps, OPS_BUILTIN_SECTION_TYPES, OPS_PROP_KINDS, OpenStatus, type OpenStatusLabels, type OpenStatusProps, type OpsPropKind, type OpsSectionProp, type OpsSectionType, type PickupInfo, PickupOption, type PickupOptionProps, type ProductOptionState, type ProductOptionValueState, type ProductOptionsState, RestockNotifyForm, type RestockNotifyFormProps, SELECTED_LOCATION_PARAM, SELECTED_LOCATION_STORAGE_KEY, type SectionComponentProps, type SectionDefinition, type SectionPropError, type SectionPropKind, type SectionPropSchema, SectionRegistry, type SectionSchema, type SectionTypeIssue, type SectionTypeWarning, type SectionTypesTarget, SectionTypesValidationError, Sections, type SectionsProps, type SeoMetaInput, SrOnly, StockConflictAlert, type StockConflictAlertProps, type StorefrontContextValue, StorefrontProvider, type StorefrontProviderProps, type SyncResult, type ThemeCssOptions, ThemeStyle, type ThemeStyleProps, type ToOpsOptions, type ToOpsResult, type UseGeolocationOptions, type UseGeolocationResult, type UseNearestLocationsOptions, type UseNearestLocationsResult, type UseProductOptionsConfig, type UseSelectedLocationOptions, type UseSelectedLocationResult, VariantOptionState, type VariantOptionStateProps, VariantSelector, type VariantSelectorProps, type VariantSelectorRenderProps, breadcrumbJsonLd, collectionJsonLd, collectionMeta, createSectionRegistry, defineSection, faqJsonLd, getCartIdFromCookie, isSafeCssValue, localBusinessJsonLd, openingHoursJsonLd, optimisticCart, organizationJsonLd, productJsonLd, productMeta, readCartCookie, readSelectedLocationId, resolveSectionProps, sectionJsonSchema, sectionTypesToOps, seoMeta, serializeCartCookie, serializeJsonLd, syncSectionTypes, themeFontsHref, themeToCss, themeToCssVariables, toMerchandise, tokenName, useAvailability, useCart, useGeolocation, useNearestLocations, useOptionalCart, useOptionalStorefront, useProductOptions, useSelectedLocation, useStorefront, useStorefrontClient, validateOpsSectionTypes, writeCartCookie };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, ComponentPropsWithoutRef, ComponentType, FormEvent } from 'react';
-import { StorefrontClient, Shop, StorefrontClientOptions, Cart, CartLineInput, CartLineMerchandise, CartLineUpdateInput, CartBuyerInput, AddressInput, DeliveryInput, DeliveryOptions, ProductVariant, Product, Image, Collection, Section, Theme, GeoPoint, ShopBranch, Money } from '@asteby/storefront';
+import { StorefrontClient, Shop, StorefrontClientOptions, Cart, CartLineInput, CartLineMerchandise, CartLineUpdateInput, CartBuyerInput, AddressInput, DeliveryInput, DeliveryOptions, Availability, ProductVariant, Product, resolveAvailability, AvailabilityMessages, CartLine, CartLineProblem as CartLineProblem$1, AvailabilityView, Image, Collection, ResolveAvailabilityOptions, Section, Theme, GeoPoint, ShopBranch, Money } from '@asteby/storefront';
 export { D as DEFAULT_IMAGE_WIDTHS, I as Image, a as ImageLoader, b as ImageProps, M as Money, c as MoneyProps, P as ProductPrice, d as ProductPriceProps, e as defaultImageLoader } from './components-B5XhSH-m.js';
 import { OpeningHours, GeoPoint as GeoPoint$1, OpenStatus as OpenStatus$1 } from '@asteby/storefront/geo';
 
@@ -135,6 +135,8 @@ type ProductOptionValueState = {
     available: boolean;
     /** The variant this value would select, if it exists. */
     variant: ProductVariant | null;
+    /** Availability of that variant (polyfilled for servers older than contract 1.1); with the other options not chosen yet, the best among matching variants. `null` when no variant matches. Feed it to `<VariantOptionState availability>`. */
+    availability: Availability | null;
     /** Query string (`?Talla=M&Color=Rojo`) selecting this value, preserving other params. */
     search: string;
 };
@@ -196,13 +198,130 @@ declare function toMerchandise(product: Pick<Product, 'handle' | 'title' | 'feat
 type AddToCartButtonProps = Omit<ComponentPropsWithoutRef<'button'>, 'onClick'> & {
     variantId: string | null | undefined;
     quantity?: number;
+    /**
+     * Availability of the variant (server `availability`, or the variant itself to polyfill). When given: the label
+     * comes from the server state ("Agotado", "Pedir bajo pedido"...) unless `children` is set, the button is
+     * disabled when it cannot be bought, and the quantity is capped at `max_per_order`.
+     */
+    availability?: Availability | null;
+    /** Variant to derive the availability from when the server did not send it. */
+    availabilitySource?: ProductVariant | null;
+    /** Polyfill only: shop-level low-stock threshold. */
+    lowStockThreshold?: number | null;
+    /** BCP 47; defaults to the provider locale. */
+    locale?: string;
     /** Variant data for an instant optimistic cart line. */
     merchandise?: CartLineMerchandise;
     onAdded?: () => void;
     onClick?: ComponentPropsWithoutRef<'button'>['onClick'];
 };
 /** Adds a variant to the cart via `useCart().addLines`. Disabled without a variant or while adding. */
-declare function AddToCartButton({ variantId, quantity, merchandise, onAdded, onClick, disabled, children, type, ...rest }: AddToCartButtonProps): react.JSX.Element;
+declare function AddToCartButton({ variantId, quantity, availability, availabilitySource, lowStockThreshold, locale, merchandise, onAdded, onClick, disabled, children, type, ...rest }: AddToCartButtonProps): react.JSX.Element;
+
+/** Visually hidden text for screen readers. */
+declare function SrOnly({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+type AvailabilitySource = Parameters<typeof resolveAvailability>[0];
+type AvailabilityInput = {
+    /** Availability sent by the server. */
+    availability?: Availability | null;
+    /** Variant or product: used when `availability` is absent (polyfill for servers older than contract 1.1). */
+    source?: AvailabilitySource | null;
+    /** Polyfill only: shop-level low-stock threshold (never hard-coded here). */
+    lowStockThreshold?: number | null;
+    /** BCP 47; defaults to the provider locale, then `es-MX`. */
+    locale?: string;
+    /** Per-key text overrides. */
+    messages?: Partial<AvailabilityMessages>;
+};
+/** `AvailabilityView` for a server `availability` or a variant/product (polyfilled). `null` when nothing is given. */
+declare function useAvailability(input: AvailabilityInput): AvailabilityView | null;
+type AvailabilityBadgeProps = AvailabilityInput & {
+    /**
+     * `card` (listing): renders `null` for plain `in_stock` so cards are not saturated.
+     * `detail` (product page): always renders, with the ETA and the order cap.
+     */
+    placement?: 'card' | 'detail';
+    /** Announce changes (e.g. after the client refreshes the stock): `role="status"`. */
+    live?: boolean;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/**
+ * Availability label. `data-availability` is the status and `data-tone` the tone, so a
+ * card can dim its image with CSS (`[data-availability=out_of_stock]`).
+ */
+declare function AvailabilityBadge({ availability, source, lowStockThreshold, locale, messages, placement, live, ...rest }: AvailabilityBadgeProps): react.JSX.Element | null;
+type VariantOptionStateProps = AvailabilityInput & {
+    /** The option text (e.g. the flavor). */
+    children: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/**
+ * Content for one option of a flavor/variant selector. A sold-out option is struck through
+ * (`<s>`) and announced as "agotado" to screen readers; it stays selectable so the buyer can
+ * see it and subscribe. Backorder / preorder options get a visible tag. Plain in-stock: just the text.
+ * Without any availability it renders `children` untouched.
+ */
+declare function VariantOptionState({ children, availability, source, lowStockThreshold, locale, messages, ...rest }: VariantOptionStateProps): react.JSX.Element;
+type RestockNotifyFormProps = AvailabilityInput & {
+    sku: string;
+    /** Market (country) of the buyer, if the shop has several. */
+    market?: string;
+    /** Offer a phone / WhatsApp field next to the email. Default false (email only). */
+    allowPhone?: boolean;
+    /**
+     * Destination of the native POST. Without JavaScript the browser posts `sku`, `email`, `phone`, `locale`,
+     * `market` and `consent` there, so the shop's own route can call `client.restock.subscribe`. Default: the current page.
+     */
+    action?: string;
+    /** Client override (defaults to the `StorefrontProvider` client). */
+    client?: StorefrontClient;
+    /** With JavaScript the form submits through the SDK; set `false` to always post natively. */
+    enhance?: boolean;
+    onSubscribed?: () => void;
+    onError?: (error: unknown) => void;
+} & Omit<ComponentPropsWithoutRef<'form'>, 'action' | 'method' | 'onSubmit' | 'children'>;
+/**
+ * Subscription form. Renders `null` unless the server says `notify_available` and the state is
+ * `out_of_stock`. Works without JavaScript (native POST); with it, submits via the SDK and shows
+ * the result in place (`role="status"` / `role="alert"`).
+ */
+declare function RestockNotifyForm({ sku, market, allowPhone, action, client: clientProp, enhance, onSubscribed, onError, availability, source, lowStockThreshold, locale, messages, ...rest }: RestockNotifyFormProps): react.JSX.Element | null;
+type CartLineProblemProps = {
+    /** The cart line; its `problem` is shown. Renders `null` when there is none. */
+    line: Pick<CartLine, 'id' | 'quantity'> & {
+        problem?: CartLineProblem$1 | null;
+    };
+    locale?: string;
+    messages?: Partial<AvailabilityMessages>;
+    /** Defaults to `useCart().updateLines` when inside a `CartProvider`. */
+    onAdjust?: (lineId: string, quantity: number) => void | Promise<unknown>;
+    /** Defaults to `useCart().removeLines` when inside a `CartProvider`. */
+    onRemove?: (lineId: string) => void | Promise<unknown>;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
+/**
+ * Problem of one cart line, shown as soon as the cart loads (before checkout): "Ya no hay existencias" or
+ * "Solo puedes llevar N", with "Ajustar a N" (only when the server lets the number be seen) and "Quitar".
+ */
+declare function CartLineProblem({ line, locale, messages, onAdjust, onRemove, ...rest }: CartLineProblemProps): react.JSX.Element | null;
+type StockConflictAlertProps = {
+    /** Error to inspect. Defaults to `useCart().error`. Renders `null` unless it is a `409 insufficient_stock`. */
+    error?: unknown;
+    /** Cart used to name the affected lines. Defaults to `useCart().cart`. */
+    cart?: Cart | null;
+    locale?: string;
+    messages?: Partial<AvailabilityMessages>;
+    onAdjust?: (lineId: string, quantity: number) => void | Promise<unknown>;
+    onRemove?: (lineId: string) => void | Promise<unknown>;
+    onDismiss?: () => void;
+    /** Move focus to the alert when it appears (default true). */
+    autoFocus?: boolean;
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'role' | 'tabIndex'>;
+/**
+ * Recoverable stock conflict. The cart and the form data are NOT touched: it shows our own text (never the raw
+ * `error.message`), the affected lines with "Ajustar a N" / "Quitar", and takes focus (`role="alert"`) without
+ * moving the page. Drop it above the checkout form: `<StockConflictAlert />` reads the error from the cart.
+ */
+declare function StockConflictAlert({ error: errorProp, cart: cartProp, locale, messages, onAdjust, onRemove, onDismiss, autoFocus, ...rest }: StockConflictAlertProps): react.JSX.Element | null;
 
 /**
  * SEO helpers: pure functions returning meta descriptors (React Router v7
@@ -248,12 +367,11 @@ type SeoMetaInput = {
 };
 /** Generic title/description/canonical/Open Graph/Twitter descriptors. */
 declare function seoMeta(input: SeoMetaInput): MetaDescriptor[];
-/** Product page descriptors (`og:type=product` and price tags). */
-declare function productMeta(product: Product, shop: Pick<Shop, 'name' | 'locale'> | null, url: string): MetaDescriptor[];
+declare function productMeta(product: Product, shop: Pick<Shop, 'name' | 'locale'> | null, url: string, options?: ResolveAvailabilityOptions): MetaDescriptor[];
 /** Collection page descriptors. */
 declare function collectionMeta(collection: Collection, shop: Pick<Shop, 'name' | 'locale'> | null, url: string): MetaDescriptor[];
 /** schema.org `Product` with one `Offer` per variant. */
-declare function productJsonLd(product: Product, shop: Pick<Shop, 'name' | 'domain'> | null, url: string): JsonLdObject;
+declare function productJsonLd(product: Product, shop: Pick<Shop, 'name' | 'domain'> | null, url: string, options?: ResolveAvailabilityOptions): JsonLdObject;
 /** schema.org `Organization` for the shop (logo, contact, url). */
 declare function organizationJsonLd(shop: Shop, url?: string): JsonLdObject;
 type LocalBusinessOptions = {
@@ -302,6 +420,97 @@ type JsonLdProps = {
 /** Renders `<script type="application/ld+json">` safely (works in SSR). */
 declare function JsonLd({ data, nonce }: JsonLdProps): react.JSX.Element | null;
 
+/** Types OPS ships built in; they cannot be redefined through the API. */
+declare const OPS_BUILTIN_SECTION_TYPES: readonly ["hero", "product_grid", "collection_list", "rich_text", "faq", "image_with_text"];
+declare const OPS_PROP_KINDS: readonly ["text", "textarea", "richtext", "image", "link", "number", "select", "boolean", "collection", "collection_list", "product", "product_list", "list"];
+type OpsPropKind = (typeof OPS_PROP_KINDS)[number];
+type OpsSectionProp = {
+    key: string;
+    kind: OpsPropKind;
+    label: string;
+    required?: boolean;
+    default?: unknown;
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    min?: number;
+    max?: number;
+    fields?: OpsSectionProp[];
+};
+type OpsSectionType = {
+    type: string;
+    label: string;
+    description?: string;
+    category?: string;
+    schema: {
+        props: OpsSectionProp[];
+    };
+    max_per_page?: number;
+};
+type SectionTypeIssue = {
+    /** Dotted path, e.g. `promo.schema.props[1].fields[0].key`. */
+    path: string;
+    message: string;
+};
+type SectionTypeWarning = {
+    type: string;
+    /** Prop key when the warning is about a single prop. */
+    prop?: string;
+    message: string;
+};
+declare class SectionTypesValidationError extends Error {
+    readonly issues: SectionTypeIssue[];
+    constructor(issues: SectionTypeIssue[]);
+}
+type ToOpsOptions = {
+    /** Skip OPS built-in types (default true). */
+    excludeBuiltin?: boolean;
+    /**
+     * Prop keys OPS already knows for each built-in type (e.g. `{ hero: ['title','subtitle'] }`).
+     * With it, only the extra local props are warned about; without it, every
+     * locally-defined built-in type gets one generic warning.
+     */
+    builtinProps?: Record<string, readonly string[]>;
+};
+type ToOpsResult = {
+    types: OpsSectionType[];
+    warnings: SectionTypeWarning[];
+};
+/** Local mirror of the OPS validation, so mistakes surface before the request. */
+declare function validateOpsSectionTypes(types: readonly OpsSectionType[]): SectionTypeIssue[];
+type DefinitionsSource = {
+    definitions(): SectionDefinition<any, any>[];
+} | readonly SectionDefinition<any, any>[];
+/**
+ * Converts the registry (or a list of definitions) to OPS section types.
+ * Throws `SectionTypesValidationError` (with `issues`) when something would
+ * be rejected by OPS.
+ */
+declare function sectionTypesToOps(source: DefinitionsSource, options?: ToOpsOptions): ToOpsResult;
+type SectionTypesTarget = {
+    request<T>(spec: {
+        method: 'PUT';
+        path: string;
+        body?: unknown;
+    }): Promise<T>;
+} | {
+    baseUrl: string;
+    token: string;
+    fetch?: typeof fetch;
+};
+type SyncResult = {
+    created: number;
+    updated: number;
+    warnings: SectionTypeWarning[];
+};
+/**
+ * Validates locally and then `PUT`s the section types to OPS. Needs an `sk_`
+ * token with `content:write`. `target` is a `createStorefrontClient()` client or
+ * `{ baseUrl, token, fetch? }`. Returns `{ created, updated, warnings }`.
+ */
+declare function syncSectionTypes(target: SectionTypesTarget, source: DefinitionsSource, options?: ToOpsOptions): Promise<SyncResult>;
+
 type SectionPropKind = 'text' | 'textarea' | 'richtext' | 'number' | 'boolean' | 'url' | 'image' | 'color' | 'select' | 'collection' | 'product' | 'products' | 'list';
 type SectionPropSchema = {
     label: string;
@@ -347,6 +556,10 @@ type SectionDefinition<P = Record<string, unknown>, C = any> = {
     type: string;
     label?: string;
     description?: string;
+    /** OPS editor grouping (only used when exporting to OPS). */
+    category?: string;
+    /** Max instances per page (only used when exporting to OPS). */
+    maxPerPage?: number;
     schema: SectionSchema;
     component: ComponentType<SectionComponentProps<P, C>>;
 };
@@ -367,6 +580,8 @@ declare function defineSection<const S extends SectionSchema, C = any>(definitio
     type: string;
     label?: string;
     description?: string;
+    category?: string;
+    maxPerPage?: number;
     schema: S;
     component: ComponentType<SectionComponentProps<InferSectionProps<S>, C>>;
 }): SectionDefinition<InferSectionProps<S>, C>;
@@ -395,6 +610,12 @@ declare class SectionRegistry {
     definitions(): SectionDefinition<any, any>[];
     /** JSON Schemas of every registered section, keyed by type. */
     toJSONSchema(): Record<string, Record<string, unknown>>;
+    /**
+     * Section types in the OPS `storefront_content` format, ready for
+     * `PUT /storefront/content/section-types`. Throws `SectionTypesValidationError`
+     * on anything OPS would reject; `warnings` flags built-in types.
+     */
+    toOpsSectionTypes(options?: ToOpsOptions): ToOpsResult;
 }
 declare function createSectionRegistry(definitions?: readonly SectionDefinition<any, any>[]): SectionRegistry;
 type SectionsProps<C = unknown> = {
@@ -655,4 +876,4 @@ type NearestLocationFormProps<L extends ShopBranch = ShopBranch> = {
  */
 declare function NearestLocationForm<L extends ShopBranch = ShopBranch>({ locations, action, name, defaultValue, onSubmitPostalCode, onLocate, labels, children, ...rest }: NearestLocationFormProps<L>): react.JSX.Element | null;
 
-export { AddToCartButton, type AddToCartButtonProps, type BreadcrumbItem, CART_COOKIE_NAME, type CartContextValue, type CartCookieOptions, type CartLineAddInput, CartProvider, type CartProviderProps, type CartStatus, DirectionsLink, type DirectionsLinkProps, type FaqItem, type GeolocationErrorCode, type GeolocationFailure, type GeolocationPermission, type InferSectionProps, JsonLd, type JsonLdObject, type JsonLdProps, type LocalBusinessOptions, type LocationItemState, LocationList, type LocationListProps, LocationPicker, type LocationPickerProps, type MetaDescriptor, type NearbyLocation, NearestLocationForm, type NearestLocationFormLabels, type NearestLocationFormProps, OpenStatus, type OpenStatusLabels, type OpenStatusProps, type PickupInfo, PickupOption, type PickupOptionProps, type ProductOptionState, type ProductOptionValueState, type ProductOptionsState, SELECTED_LOCATION_PARAM, SELECTED_LOCATION_STORAGE_KEY, type SectionComponentProps, type SectionDefinition, type SectionPropError, type SectionPropKind, type SectionPropSchema, SectionRegistry, type SectionSchema, Sections, type SectionsProps, type SeoMetaInput, type StorefrontContextValue, StorefrontProvider, type StorefrontProviderProps, type ThemeCssOptions, ThemeStyle, type ThemeStyleProps, type UseGeolocationOptions, type UseGeolocationResult, type UseNearestLocationsOptions, type UseNearestLocationsResult, type UseProductOptionsConfig, type UseSelectedLocationOptions, type UseSelectedLocationResult, VariantSelector, type VariantSelectorProps, type VariantSelectorRenderProps, breadcrumbJsonLd, collectionJsonLd, collectionMeta, createSectionRegistry, defineSection, faqJsonLd, getCartIdFromCookie, isSafeCssValue, localBusinessJsonLd, openingHoursJsonLd, optimisticCart, organizationJsonLd, productJsonLd, productMeta, readCartCookie, readSelectedLocationId, resolveSectionProps, sectionJsonSchema, seoMeta, serializeCartCookie, serializeJsonLd, themeFontsHref, themeToCss, themeToCssVariables, toMerchandise, tokenName, useCart, useGeolocation, useNearestLocations, useOptionalCart, useOptionalStorefront, useProductOptions, useSelectedLocation, useStorefront, useStorefrontClient, writeCartCookie };
+export { AddToCartButton, type AddToCartButtonProps, AvailabilityBadge, type AvailabilityBadgeProps, type AvailabilityInput, type BreadcrumbItem, CART_COOKIE_NAME, type CartContextValue, type CartCookieOptions, type CartLineAddInput, CartLineProblem, type CartLineProblemProps, CartProvider, type CartProviderProps, type CartStatus, DirectionsLink, type DirectionsLinkProps, type FaqItem, type GeolocationErrorCode, type GeolocationFailure, type GeolocationPermission, type InferSectionProps, JsonLd, type JsonLdObject, type JsonLdProps, type LocalBusinessOptions, type LocationItemState, LocationList, type LocationListProps, LocationPicker, type LocationPickerProps, type MetaDescriptor, type NearbyLocation, NearestLocationForm, type NearestLocationFormLabels, type NearestLocationFormProps, OPS_BUILTIN_SECTION_TYPES, OPS_PROP_KINDS, OpenStatus, type OpenStatusLabels, type OpenStatusProps, type OpsPropKind, type OpsSectionProp, type OpsSectionType, type PickupInfo, PickupOption, type PickupOptionProps, type ProductOptionState, type ProductOptionValueState, type ProductOptionsState, RestockNotifyForm, type RestockNotifyFormProps, SELECTED_LOCATION_PARAM, SELECTED_LOCATION_STORAGE_KEY, type SectionComponentProps, type SectionDefinition, type SectionPropError, type SectionPropKind, type SectionPropSchema, SectionRegistry, type SectionSchema, type SectionTypeIssue, type SectionTypeWarning, type SectionTypesTarget, SectionTypesValidationError, Sections, type SectionsProps, type SeoMetaInput, SrOnly, StockConflictAlert, type StockConflictAlertProps, type StorefrontContextValue, StorefrontProvider, type StorefrontProviderProps, type SyncResult, type ThemeCssOptions, ThemeStyle, type ThemeStyleProps, type ToOpsOptions, type ToOpsResult, type UseGeolocationOptions, type UseGeolocationResult, type UseNearestLocationsOptions, type UseNearestLocationsResult, type UseProductOptionsConfig, type UseSelectedLocationOptions, type UseSelectedLocationResult, VariantOptionState, type VariantOptionStateProps, VariantSelector, type VariantSelectorProps, type VariantSelectorRenderProps, breadcrumbJsonLd, collectionJsonLd, collectionMeta, createSectionRegistry, defineSection, faqJsonLd, getCartIdFromCookie, isSafeCssValue, localBusinessJsonLd, openingHoursJsonLd, optimisticCart, organizationJsonLd, productJsonLd, productMeta, readCartCookie, readSelectedLocationId, resolveSectionProps, sectionJsonSchema, sectionTypesToOps, seoMeta, serializeCartCookie, serializeJsonLd, syncSectionTypes, themeFontsHref, themeToCss, themeToCssVariables, toMerchandise, tokenName, useAvailability, useCart, useGeolocation, useNearestLocations, useOptionalCart, useOptionalStorefront, useProductOptions, useSelectedLocation, useStorefront, useStorefrontClient, validateOpsSectionTypes, writeCartCookie };