@asteby/storefront-react 0.1.2 → 0.3.0

package/dist/index.d.cts

@@ -1,6 +1,8 @@
 import * as react from 'react';
-import { ReactNode, ComponentPropsWithoutRef, ElementType, ComponentType } from 'react';
-import { StorefrontClient, Shop, StorefrontClientOptions, Cart, CartLineInput, CartLineMerchandise, CartLineUpdateInput, CartBuyerInput, AddressInput, DeliveryInput, DeliveryOptions, Image as Image$1, FormatMoneyOptions, Money as Money$1, Product, ProductVariant, Collection, Section, Theme } from '@asteby/storefront';
+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';
+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';
 
 type StorefrontContextValue = {
     /** Client for browser-side calls (use a public `pk_` token). */
@@ -123,55 +125,6 @@ declare function useCart(): CartContextValue;
 /** Cart context or `null` outside a provider. */
 declare function useOptionalCart(): CartContextValue | null;
 
-type MoneyProps<As extends ElementType = 'span'> = FormatMoneyOptions & {
-    data: Money$1;
-    /** Element to render (default `span`). */
-    as?: As;
-    /** Overrides the provider locale. */
-    locale?: string;
-} & Omit<ComponentPropsWithoutRef<As>, 'children' | 'as'>;
-/** Formats `Money` with the provider locale (or `locale`). */
-declare function Money<As extends ElementType = 'span'>({ data, as, locale, withoutTrailingZeros, withoutCurrency, currencyDisplay, ...rest }: MoneyProps<As>): react.ReactElement<any, string | react.JSXElementConstructor<any>>;
-declare const DEFAULT_IMAGE_WIDTHS: readonly [320, 480, 640, 768, 1024, 1280, 1600];
-/** Builds the URL for one srcset width. */
-type ImageLoader = (src: string, width: number, height?: number) => string;
-/**
- * Default loader: adds `?width=<w>` (the convention of most image CDNs and of
- * the OPS image proxy). URLs that cannot be parsed are returned unchanged.
- */
-declare const defaultImageLoader: ImageLoader;
-type ImageProps = Omit<ComponentPropsWithoutRef<'img'>, 'src' | 'srcSet' | 'width' | 'height'> & {
-    data: Image$1;
-    /** `sizes` attribute (default `100vw`). */
-    sizes?: string;
-    /** Candidate widths for `srcset` (capped at the intrinsic width when known). */
-    widths?: readonly number[];
-    /** URL builder per width (default adds `?width=`). Pass `null` to disable srcset. */
-    loader?: ImageLoader | null;
-    /** Above-the-fold image: eager loading and `fetchpriority="high"`. */
-    priority?: boolean;
-    /** Forces an aspect ratio, e.g. `1/1` or `4/3`, used for width/height and srcset heights. */
-    aspectRatio?: string;
-};
-/** Responsive `<img>` with `srcset`, lazy by default, intrinsic size to avoid layout shift. */
-declare function Image({ data, sizes, widths, loader, priority, aspectRatio, alt, loading, decoding, ...rest }: ImageProps): react.JSX.Element;
-type ProductPriceProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
-    product?: Pick<Product, 'price_range' | 'compare_at_price_range'> | null;
-    variant?: Pick<ProductVariant, 'price' | 'compare_at_price'> | null;
-    /** Prefix shown when the product has a price range and no variant is selected (default `Desde`). */
-    fromLabel?: ReactNode;
-    /** Accessible label for the compare-at price (default `Precio anterior`). */
-    compareAtLabel?: string;
-    locale?: string;
-    withoutTrailingZeros?: boolean;
-};
-/**
- * Price with optional compare-at (strikethrough). With a `variant` it shows
- * that variant; otherwise the product's minimum price (prefixed with
- * `fromLabel` when prices vary).
- */
-declare function ProductPrice({ product, variant, fromLabel, compareAtLabel, locale, withoutTrailingZeros, ...rest }: ProductPriceProps): react.JSX.Element | null;
-
 type ProductOptionValueState = {
     value: string;
     /** Part of the current selection. */
@@ -284,7 +237,7 @@ type SeoMetaInput = {
     description?: string | null;
     /** Canonical absolute URL. */
     url?: string | null;
-    image?: Image$1 | string | null;
+    image?: Image | string | null;
     /** `og:type` (default `website`). */
     type?: string;
     siteName?: string | null;
@@ -310,7 +263,17 @@ type LocalBusinessOptions = {
     url?: string;
     priceRange?: string;
 };
-/** One schema.org `LocalBusiness` (default `Store`) per shop branch. */
+/**
+ * schema.org `openingHours` values from structured hours or a legacy string.
+ * A string is accepted only if EVERY comma-separated token is strict schema.org
+ * syntax (`Mo-Fr 09:00-19:00`); free text such as `Lun-Sáb 8:00 a 18:00` yields
+ * `undefined` so no invalid markup is ever emitted.
+ */
+declare function openingHoursJsonLd(hours: OpeningHours | string | null | undefined): string[] | undefined;
+/**
+ * One schema.org `LocalBusiness` (default `Store`) per shop branch. Hours come
+ * from `opening_hours` when present, else from the legacy `hours` string.
+ */
 declare function localBusinessJsonLd(shop: Shop, options?: LocalBusinessOptions): JsonLdObject[];
 type BreadcrumbItem = {
     name: string;
@@ -481,4 +444,215 @@ type ThemeStyleProps = ThemeCssOptions & {
 /** Emits the theme variables as a `<style>` (render it in `<head>` from the root route). */
 declare function ThemeStyle({ theme, nonce, id, ...options }: ThemeStyleProps): react.JSX.Element | null;
 
-export { AddToCartButton, type AddToCartButtonProps, type BreadcrumbItem, CART_COOKIE_NAME, type CartContextValue, type CartCookieOptions, type CartLineAddInput, CartProvider, type CartProviderProps, type CartStatus, DEFAULT_IMAGE_WIDTHS, type FaqItem, Image, type ImageLoader, type ImageProps, type InferSectionProps, JsonLd, type JsonLdObject, type JsonLdProps, type LocalBusinessOptions, type MetaDescriptor, Money, type MoneyProps, type ProductOptionState, type ProductOptionValueState, type ProductOptionsState, ProductPrice, type ProductPriceProps, 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 UseProductOptionsConfig, VariantSelector, type VariantSelectorProps, type VariantSelectorRenderProps, breadcrumbJsonLd, collectionJsonLd, collectionMeta, createSectionRegistry, defaultImageLoader, defineSection, faqJsonLd, getCartIdFromCookie, isSafeCssValue, localBusinessJsonLd, optimisticCart, organizationJsonLd, productJsonLd, productMeta, readCartCookie, resolveSectionProps, sectionJsonSchema, seoMeta, serializeCartCookie, serializeJsonLd, themeFontsHref, themeToCss, themeToCssVariables, toMerchandise, tokenName, useCart, useOptionalCart, useOptionalStorefront, useProductOptions, useStorefront, useStorefrontClient, writeCartCookie };
+type GeolocationErrorCode = 'unsupported' | 'insecure' | 'denied' | 'unavailable' | 'timeout';
+/** Typed failure of `request()`. `message` is a ready-to-show es-MX text. */
+type GeolocationFailure = {
+    code: GeolocationErrorCode;
+    message: string;
+};
+/** State of the browser permission. `unknown` when the Permissions API is missing. */
+type GeolocationPermission = 'granted' | 'denied' | 'prompt' | 'unknown';
+type UseGeolocationOptions = {
+    enableHighAccuracy?: boolean;
+    /** Give up after this long (default 10 s). */
+    timeoutMs?: number;
+    /** Accept a cached position up to this old (default 5 min). */
+    maximumAge?: number;
+};
+type UseGeolocationResult = {
+    /** `false` on the server and until mounted, so SSR and hydration agree. */
+    supported: boolean;
+    permission: GeolocationPermission;
+    status: 'idle' | 'locating' | 'success' | 'error';
+    position: GeoPoint | null;
+    error: GeolocationFailure | null;
+    /**
+     * Asks the browser for the position. Call it ONLY from a user gesture (a button's onClick): the hook never
+     * asks by itself. Resolves to the point, or `null` on failure (see `error`).
+     */
+    request: () => Promise<GeoPoint | null>;
+    reset: () => void;
+};
+/**
+ * Browser geolocation that only runs under a user action. Reading the permission state (when the Permissions
+ * API exists) does not prompt. The point stays in React state: it is never stored or sent anywhere here.
+ */
+declare function useGeolocation(options?: UseGeolocationOptions): UseGeolocationResult;
+
+type NearbyLocation<L extends ShopBranch = ShopBranch> = L & {
+    distance_km: number | null;
+};
+type UseNearestLocationsOptions<L extends ShopBranch = ShopBranch> = {
+    /** The buyer's point (from `useGeolocation().request()`). */
+    origin?: GeoPoint$1 | null;
+    /** Postal code typed by the buyer (5 digits). The server resolves it to coordinates, so this always asks the server. */
+    postalCode?: string | null;
+    /** Branches to rank. Defaults to `shop.branches` from the provider. */
+    locations?: readonly L[];
+    /** Keep the closest N. */
+    limit?: number;
+    /** Keep those within this many km. */
+    radiusKm?: number;
+    /** Force the server (`locations.nearest`) for `origin` instead of ranking `locations` in the browser. */
+    remote?: boolean;
+    /** Defaults to the provider's client. */
+    client?: StorefrontClient;
+};
+type UseNearestLocationsResult<L extends ShopBranch = ShopBranch> = {
+    locations: NearbyLocation<L>[];
+    status: 'idle' | 'loading' | 'success' | 'error';
+    error: Error | null;
+    /** `local`: ranked in the browser, the point never leaves it. `remote`: answered by the server. */
+    source: 'local' | 'remote' | null;
+};
+/**
+ * Branches ordered by distance. With an `origin` and branches at hand (explicit or `shop.branches`) the ranking
+ * runs in the browser with haversine and the coordinates are sent nowhere. `postalCode` (or `remote`) asks the
+ * server, which rounds and never stores the point. With zero branches, or neither origin nor postal code, the
+ * result is empty and `idle`.
+ */
+declare function useNearestLocations<L extends ShopBranch = ShopBranch>(options?: UseNearestLocationsOptions<L>): UseNearestLocationsResult<L>;
+
+/** Query param that carries the chosen branch (also the default `name` of `<LocationPicker>`). */
+declare const SELECTED_LOCATION_PARAM = "sucursal";
+/** localStorage key of "Mi sucursal". Never a cookie: the choice is per browser and is not sent to the server. */
+declare const SELECTED_LOCATION_STORAGE_KEY = "sf_sucursal";
+/**
+ * The saved branch id: `?sucursal=` wins over localStorage. Pure helper for loaders and tests; on the server
+ * pass the request's search string (`new URL(request.url).search`) and no storage.
+ */
+declare function readSelectedLocationId({ search, store, param, storageKey }?: {
+    search?: string;
+    store?: Pick<Storage, 'getItem'> | null;
+    param?: string;
+    storageKey?: string;
+}): string | null;
+type UseSelectedLocationOptions = {
+    /** Branches to validate against. Defaults to `shop.branches` from `<StorefrontProvider>`. */
+    locations?: readonly ShopBranch[];
+    /** Id already known on the server (from `?sucursal=`), so SSR and hydration render the same. */
+    initialId?: string | null;
+    param?: string;
+    storageKey?: string;
+    /** Mirror the choice in the address bar with `history.replaceState` (default true). */
+    syncUrl?: boolean;
+};
+type UseSelectedLocationResult<L extends ShopBranch = ShopBranch> = {
+    id: string | null;
+    location: L | null;
+    /** `false` until the saved choice has been read on the client. */
+    ready: boolean;
+    select: (id: string) => void;
+    clear: () => void;
+};
+/**
+ * "Mi sucursal": the chosen branch lives in the URL (`?sucursal=<id>`, shareable) and in localStorage. It is
+ * never written to a cookie, so it does not travel with every request. An id that is not among `locations`
+ * is ignored and forgotten; with zero branches nothing is ever selected.
+ */
+declare function useSelectedLocation<L extends ShopBranch = ShopBranch>(options?: UseSelectedLocationOptions & {
+    locations?: readonly L[];
+}): UseSelectedLocationResult<L>;
+
+type LocationItemState = {
+    index: number;
+    selected: boolean;
+};
+type LocationListProps<L extends ShopBranch = ShopBranch> = {
+    locations?: readonly L[];
+    /** Marks one item with `data-selected` / `aria-current`. */
+    selectedId?: string | null;
+    /** Renders each item's content. Defaults to name and address. */
+    children?: (location: L, state: LocationItemState) => ReactNode;
+} & Omit<ComponentPropsWithoutRef<'ul'>, 'children'>;
+/** `<ul>` of branches; the content of every `<li>` is yours (render prop). */
+declare function LocationList<L extends ShopBranch = ShopBranch>({ locations, selectedId, children, ...rest }: LocationListProps<L>): react.JSX.Element | null;
+type LocationPickerProps<L extends ShopBranch = ShopBranch> = {
+    /** Accessible name of the group (rendered as `<legend>`). */
+    legend: ReactNode;
+    locations?: readonly L[];
+    /** Controlled value (branch id). */
+    value?: string | null;
+    defaultValue?: string | null;
+    onChange?: (id: string, location: L) => void;
+    /** Radio `name` (default `sucursal`, the same param `useSelectedLocation` reads). */
+    name?: string;
+    /** Content of each option next to its radio. Defaults to name and address. */
+    children?: (location: L, state: {
+        checked: boolean;
+    }) => ReactNode;
+} & Omit<ComponentPropsWithoutRef<'fieldset'>, 'children' | 'onChange' | 'defaultValue'>;
+/**
+ * `<fieldset>` of native radio buttons: keyboard and screen-reader behaviour comes from the browser, and inside
+ * a GET `<form>` it submits `?sucursal=<id>` without JavaScript.
+ */
+declare function LocationPicker<L extends ShopBranch = ShopBranch>({ legend, locations, value, defaultValue, onChange, name, children, ...rest }: LocationPickerProps<L>): react.JSX.Element | null;
+type OpenStatusLabels = {
+    open: string;
+    closed: string;
+};
+type OpenStatusProps = {
+    /** Reads `opening_hours` and `timezone` from it. */
+    location?: Pick<ShopBranch, 'opening_hours' | 'timezone'>;
+    hours?: OpeningHours;
+    /** IANA zone (default: the branch's, else `America/Mexico_City`). */
+    timezone?: string;
+    /** Fixed instant, for tests and SSR snapshots. Without it the status is computed after mount and refreshed every minute. */
+    now?: Date;
+    labels?: Partial<OpenStatusLabels>;
+    children?: (status: OpenStatus$1) => ReactNode;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/**
+ * "Abierto" / "Cerrado" from `openStatus`. The clock makes server and client disagree, so without `now` it
+ * renders nothing until mounted. Renders `null` without hours or with an unknown time zone.
+ */
+declare function OpenStatus({ location, hours, timezone, now, labels, children, ...rest }: OpenStatusProps): react.JSX.Element | null;
+type DirectionsLinkProps = {
+    location: Pick<ShopBranch, 'lat' | 'lng' | 'address' | 'city'>;
+    provider?: 'google' | 'apple' | 'geo';
+    children?: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'a'>, 'href' | 'children'>;
+/** Link to directions in the maps app. `null` when the branch has neither coordinates nor address. */
+declare function DirectionsLink({ location, provider, children, ...rest }: DirectionsLinkProps): react.JSX.Element | null;
+type PickupInfo<L extends ShopBranch = ShopBranch> = {
+    location: L;
+    /** `null` = free. Amount as sent by OPS; nothing is calculated here. */
+    fee: Money | null;
+    free: boolean;
+    /** Formatted `fee` (`null` when free). */
+    feeText: string | null;
+    prepDays: number;
+};
+type PickupOptionProps<L extends ShopBranch = ShopBranch> = {
+    location: L;
+    locale?: string;
+    children?: (info: PickupInfo<L>) => ReactNode;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/** "Recoge en sucursal" terms: fee and preparation time. `null` when the branch does not offer pickup. */
+declare function PickupOption<L extends ShopBranch = ShopBranch>({ location, locale, children, ...rest }: PickupOptionProps<L>): react.JSX.Element | null;
+type NearestLocationFormLabels = {
+    postalCode: string;
+    submit: string;
+    locate: string;
+    locating: string;
+};
+type NearestLocationFormProps<L extends ShopBranch = ShopBranch> = {
+    locations?: readonly L[];
+    /** Destination of the GET (default: the current page). */
+    action?: string;
+    /** Query param and input name (default `cp`). */
+    name?: string;
+    defaultValue?: string;
+    /** With JavaScript: intercept the submit and receive the postal code. Without it the browser navigates to `?cp=`. */
+    onSubmitPostalCode?: (postalCode: string, event: FormEvent<HTMLFormElement>) => void;
+    /** Shows a "use my location" button (only when the browser supports it); it asks permission on click. */
+    onLocate?: (point: GeoPoint$1) => void;
+    labels?: Partial<NearestLocationFormLabels>;
+} & Omit<ComponentPropsWithoutRef<'form'>, 'action' | 'method' | 'onSubmit' | 'defaultValue'>;
+/**
+ * `<form method="get">` with a postal-code field: works without JavaScript (navigates to `?cp=06000`). Add
+ * `onSubmitPostalCode` / `onLocate` to enhance it. Renders `null` when there are no branches.
+ */
+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 };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import * as react from 'react';
-import { ReactNode, ComponentPropsWithoutRef, ElementType, ComponentType } from 'react';
-import { StorefrontClient, Shop, StorefrontClientOptions, Cart, CartLineInput, CartLineMerchandise, CartLineUpdateInput, CartBuyerInput, AddressInput, DeliveryInput, DeliveryOptions, Image as Image$1, FormatMoneyOptions, Money as Money$1, Product, ProductVariant, Collection, Section, Theme } from '@asteby/storefront';
+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';
+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';
 
 type StorefrontContextValue = {
     /** Client for browser-side calls (use a public `pk_` token). */
@@ -123,55 +125,6 @@ declare function useCart(): CartContextValue;
 /** Cart context or `null` outside a provider. */
 declare function useOptionalCart(): CartContextValue | null;
 
-type MoneyProps<As extends ElementType = 'span'> = FormatMoneyOptions & {
-    data: Money$1;
-    /** Element to render (default `span`). */
-    as?: As;
-    /** Overrides the provider locale. */
-    locale?: string;
-} & Omit<ComponentPropsWithoutRef<As>, 'children' | 'as'>;
-/** Formats `Money` with the provider locale (or `locale`). */
-declare function Money<As extends ElementType = 'span'>({ data, as, locale, withoutTrailingZeros, withoutCurrency, currencyDisplay, ...rest }: MoneyProps<As>): react.ReactElement<any, string | react.JSXElementConstructor<any>>;
-declare const DEFAULT_IMAGE_WIDTHS: readonly [320, 480, 640, 768, 1024, 1280, 1600];
-/** Builds the URL for one srcset width. */
-type ImageLoader = (src: string, width: number, height?: number) => string;
-/**
- * Default loader: adds `?width=<w>` (the convention of most image CDNs and of
- * the OPS image proxy). URLs that cannot be parsed are returned unchanged.
- */
-declare const defaultImageLoader: ImageLoader;
-type ImageProps = Omit<ComponentPropsWithoutRef<'img'>, 'src' | 'srcSet' | 'width' | 'height'> & {
-    data: Image$1;
-    /** `sizes` attribute (default `100vw`). */
-    sizes?: string;
-    /** Candidate widths for `srcset` (capped at the intrinsic width when known). */
-    widths?: readonly number[];
-    /** URL builder per width (default adds `?width=`). Pass `null` to disable srcset. */
-    loader?: ImageLoader | null;
-    /** Above-the-fold image: eager loading and `fetchpriority="high"`. */
-    priority?: boolean;
-    /** Forces an aspect ratio, e.g. `1/1` or `4/3`, used for width/height and srcset heights. */
-    aspectRatio?: string;
-};
-/** Responsive `<img>` with `srcset`, lazy by default, intrinsic size to avoid layout shift. */
-declare function Image({ data, sizes, widths, loader, priority, aspectRatio, alt, loading, decoding, ...rest }: ImageProps): react.JSX.Element;
-type ProductPriceProps = Omit<ComponentPropsWithoutRef<'div'>, 'children'> & {
-    product?: Pick<Product, 'price_range' | 'compare_at_price_range'> | null;
-    variant?: Pick<ProductVariant, 'price' | 'compare_at_price'> | null;
-    /** Prefix shown when the product has a price range and no variant is selected (default `Desde`). */
-    fromLabel?: ReactNode;
-    /** Accessible label for the compare-at price (default `Precio anterior`). */
-    compareAtLabel?: string;
-    locale?: string;
-    withoutTrailingZeros?: boolean;
-};
-/**
- * Price with optional compare-at (strikethrough). With a `variant` it shows
- * that variant; otherwise the product's minimum price (prefixed with
- * `fromLabel` when prices vary).
- */
-declare function ProductPrice({ product, variant, fromLabel, compareAtLabel, locale, withoutTrailingZeros, ...rest }: ProductPriceProps): react.JSX.Element | null;
-
 type ProductOptionValueState = {
     value: string;
     /** Part of the current selection. */
@@ -284,7 +237,7 @@ type SeoMetaInput = {
     description?: string | null;
     /** Canonical absolute URL. */
     url?: string | null;
-    image?: Image$1 | string | null;
+    image?: Image | string | null;
     /** `og:type` (default `website`). */
     type?: string;
     siteName?: string | null;
@@ -310,7 +263,17 @@ type LocalBusinessOptions = {
     url?: string;
     priceRange?: string;
 };
-/** One schema.org `LocalBusiness` (default `Store`) per shop branch. */
+/**
+ * schema.org `openingHours` values from structured hours or a legacy string.
+ * A string is accepted only if EVERY comma-separated token is strict schema.org
+ * syntax (`Mo-Fr 09:00-19:00`); free text such as `Lun-Sáb 8:00 a 18:00` yields
+ * `undefined` so no invalid markup is ever emitted.
+ */
+declare function openingHoursJsonLd(hours: OpeningHours | string | null | undefined): string[] | undefined;
+/**
+ * One schema.org `LocalBusiness` (default `Store`) per shop branch. Hours come
+ * from `opening_hours` when present, else from the legacy `hours` string.
+ */
 declare function localBusinessJsonLd(shop: Shop, options?: LocalBusinessOptions): JsonLdObject[];
 type BreadcrumbItem = {
     name: string;
@@ -481,4 +444,215 @@ type ThemeStyleProps = ThemeCssOptions & {
 /** Emits the theme variables as a `<style>` (render it in `<head>` from the root route). */
 declare function ThemeStyle({ theme, nonce, id, ...options }: ThemeStyleProps): react.JSX.Element | null;
 
-export { AddToCartButton, type AddToCartButtonProps, type BreadcrumbItem, CART_COOKIE_NAME, type CartContextValue, type CartCookieOptions, type CartLineAddInput, CartProvider, type CartProviderProps, type CartStatus, DEFAULT_IMAGE_WIDTHS, type FaqItem, Image, type ImageLoader, type ImageProps, type InferSectionProps, JsonLd, type JsonLdObject, type JsonLdProps, type LocalBusinessOptions, type MetaDescriptor, Money, type MoneyProps, type ProductOptionState, type ProductOptionValueState, type ProductOptionsState, ProductPrice, type ProductPriceProps, 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 UseProductOptionsConfig, VariantSelector, type VariantSelectorProps, type VariantSelectorRenderProps, breadcrumbJsonLd, collectionJsonLd, collectionMeta, createSectionRegistry, defaultImageLoader, defineSection, faqJsonLd, getCartIdFromCookie, isSafeCssValue, localBusinessJsonLd, optimisticCart, organizationJsonLd, productJsonLd, productMeta, readCartCookie, resolveSectionProps, sectionJsonSchema, seoMeta, serializeCartCookie, serializeJsonLd, themeFontsHref, themeToCss, themeToCssVariables, toMerchandise, tokenName, useCart, useOptionalCart, useOptionalStorefront, useProductOptions, useStorefront, useStorefrontClient, writeCartCookie };
+type GeolocationErrorCode = 'unsupported' | 'insecure' | 'denied' | 'unavailable' | 'timeout';
+/** Typed failure of `request()`. `message` is a ready-to-show es-MX text. */
+type GeolocationFailure = {
+    code: GeolocationErrorCode;
+    message: string;
+};
+/** State of the browser permission. `unknown` when the Permissions API is missing. */
+type GeolocationPermission = 'granted' | 'denied' | 'prompt' | 'unknown';
+type UseGeolocationOptions = {
+    enableHighAccuracy?: boolean;
+    /** Give up after this long (default 10 s). */
+    timeoutMs?: number;
+    /** Accept a cached position up to this old (default 5 min). */
+    maximumAge?: number;
+};
+type UseGeolocationResult = {
+    /** `false` on the server and until mounted, so SSR and hydration agree. */
+    supported: boolean;
+    permission: GeolocationPermission;
+    status: 'idle' | 'locating' | 'success' | 'error';
+    position: GeoPoint | null;
+    error: GeolocationFailure | null;
+    /**
+     * Asks the browser for the position. Call it ONLY from a user gesture (a button's onClick): the hook never
+     * asks by itself. Resolves to the point, or `null` on failure (see `error`).
+     */
+    request: () => Promise<GeoPoint | null>;
+    reset: () => void;
+};
+/**
+ * Browser geolocation that only runs under a user action. Reading the permission state (when the Permissions
+ * API exists) does not prompt. The point stays in React state: it is never stored or sent anywhere here.
+ */
+declare function useGeolocation(options?: UseGeolocationOptions): UseGeolocationResult;
+
+type NearbyLocation<L extends ShopBranch = ShopBranch> = L & {
+    distance_km: number | null;
+};
+type UseNearestLocationsOptions<L extends ShopBranch = ShopBranch> = {
+    /** The buyer's point (from `useGeolocation().request()`). */
+    origin?: GeoPoint$1 | null;
+    /** Postal code typed by the buyer (5 digits). The server resolves it to coordinates, so this always asks the server. */
+    postalCode?: string | null;
+    /** Branches to rank. Defaults to `shop.branches` from the provider. */
+    locations?: readonly L[];
+    /** Keep the closest N. */
+    limit?: number;
+    /** Keep those within this many km. */
+    radiusKm?: number;
+    /** Force the server (`locations.nearest`) for `origin` instead of ranking `locations` in the browser. */
+    remote?: boolean;
+    /** Defaults to the provider's client. */
+    client?: StorefrontClient;
+};
+type UseNearestLocationsResult<L extends ShopBranch = ShopBranch> = {
+    locations: NearbyLocation<L>[];
+    status: 'idle' | 'loading' | 'success' | 'error';
+    error: Error | null;
+    /** `local`: ranked in the browser, the point never leaves it. `remote`: answered by the server. */
+    source: 'local' | 'remote' | null;
+};
+/**
+ * Branches ordered by distance. With an `origin` and branches at hand (explicit or `shop.branches`) the ranking
+ * runs in the browser with haversine and the coordinates are sent nowhere. `postalCode` (or `remote`) asks the
+ * server, which rounds and never stores the point. With zero branches, or neither origin nor postal code, the
+ * result is empty and `idle`.
+ */
+declare function useNearestLocations<L extends ShopBranch = ShopBranch>(options?: UseNearestLocationsOptions<L>): UseNearestLocationsResult<L>;
+
+/** Query param that carries the chosen branch (also the default `name` of `<LocationPicker>`). */
+declare const SELECTED_LOCATION_PARAM = "sucursal";
+/** localStorage key of "Mi sucursal". Never a cookie: the choice is per browser and is not sent to the server. */
+declare const SELECTED_LOCATION_STORAGE_KEY = "sf_sucursal";
+/**
+ * The saved branch id: `?sucursal=` wins over localStorage. Pure helper for loaders and tests; on the server
+ * pass the request's search string (`new URL(request.url).search`) and no storage.
+ */
+declare function readSelectedLocationId({ search, store, param, storageKey }?: {
+    search?: string;
+    store?: Pick<Storage, 'getItem'> | null;
+    param?: string;
+    storageKey?: string;
+}): string | null;
+type UseSelectedLocationOptions = {
+    /** Branches to validate against. Defaults to `shop.branches` from `<StorefrontProvider>`. */
+    locations?: readonly ShopBranch[];
+    /** Id already known on the server (from `?sucursal=`), so SSR and hydration render the same. */
+    initialId?: string | null;
+    param?: string;
+    storageKey?: string;
+    /** Mirror the choice in the address bar with `history.replaceState` (default true). */
+    syncUrl?: boolean;
+};
+type UseSelectedLocationResult<L extends ShopBranch = ShopBranch> = {
+    id: string | null;
+    location: L | null;
+    /** `false` until the saved choice has been read on the client. */
+    ready: boolean;
+    select: (id: string) => void;
+    clear: () => void;
+};
+/**
+ * "Mi sucursal": the chosen branch lives in the URL (`?sucursal=<id>`, shareable) and in localStorage. It is
+ * never written to a cookie, so it does not travel with every request. An id that is not among `locations`
+ * is ignored and forgotten; with zero branches nothing is ever selected.
+ */
+declare function useSelectedLocation<L extends ShopBranch = ShopBranch>(options?: UseSelectedLocationOptions & {
+    locations?: readonly L[];
+}): UseSelectedLocationResult<L>;
+
+type LocationItemState = {
+    index: number;
+    selected: boolean;
+};
+type LocationListProps<L extends ShopBranch = ShopBranch> = {
+    locations?: readonly L[];
+    /** Marks one item with `data-selected` / `aria-current`. */
+    selectedId?: string | null;
+    /** Renders each item's content. Defaults to name and address. */
+    children?: (location: L, state: LocationItemState) => ReactNode;
+} & Omit<ComponentPropsWithoutRef<'ul'>, 'children'>;
+/** `<ul>` of branches; the content of every `<li>` is yours (render prop). */
+declare function LocationList<L extends ShopBranch = ShopBranch>({ locations, selectedId, children, ...rest }: LocationListProps<L>): react.JSX.Element | null;
+type LocationPickerProps<L extends ShopBranch = ShopBranch> = {
+    /** Accessible name of the group (rendered as `<legend>`). */
+    legend: ReactNode;
+    locations?: readonly L[];
+    /** Controlled value (branch id). */
+    value?: string | null;
+    defaultValue?: string | null;
+    onChange?: (id: string, location: L) => void;
+    /** Radio `name` (default `sucursal`, the same param `useSelectedLocation` reads). */
+    name?: string;
+    /** Content of each option next to its radio. Defaults to name and address. */
+    children?: (location: L, state: {
+        checked: boolean;
+    }) => ReactNode;
+} & Omit<ComponentPropsWithoutRef<'fieldset'>, 'children' | 'onChange' | 'defaultValue'>;
+/**
+ * `<fieldset>` of native radio buttons: keyboard and screen-reader behaviour comes from the browser, and inside
+ * a GET `<form>` it submits `?sucursal=<id>` without JavaScript.
+ */
+declare function LocationPicker<L extends ShopBranch = ShopBranch>({ legend, locations, value, defaultValue, onChange, name, children, ...rest }: LocationPickerProps<L>): react.JSX.Element | null;
+type OpenStatusLabels = {
+    open: string;
+    closed: string;
+};
+type OpenStatusProps = {
+    /** Reads `opening_hours` and `timezone` from it. */
+    location?: Pick<ShopBranch, 'opening_hours' | 'timezone'>;
+    hours?: OpeningHours;
+    /** IANA zone (default: the branch's, else `America/Mexico_City`). */
+    timezone?: string;
+    /** Fixed instant, for tests and SSR snapshots. Without it the status is computed after mount and refreshed every minute. */
+    now?: Date;
+    labels?: Partial<OpenStatusLabels>;
+    children?: (status: OpenStatus$1) => ReactNode;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/**
+ * "Abierto" / "Cerrado" from `openStatus`. The clock makes server and client disagree, so without `now` it
+ * renders nothing until mounted. Renders `null` without hours or with an unknown time zone.
+ */
+declare function OpenStatus({ location, hours, timezone, now, labels, children, ...rest }: OpenStatusProps): react.JSX.Element | null;
+type DirectionsLinkProps = {
+    location: Pick<ShopBranch, 'lat' | 'lng' | 'address' | 'city'>;
+    provider?: 'google' | 'apple' | 'geo';
+    children?: ReactNode;
+} & Omit<ComponentPropsWithoutRef<'a'>, 'href' | 'children'>;
+/** Link to directions in the maps app. `null` when the branch has neither coordinates nor address. */
+declare function DirectionsLink({ location, provider, children, ...rest }: DirectionsLinkProps): react.JSX.Element | null;
+type PickupInfo<L extends ShopBranch = ShopBranch> = {
+    location: L;
+    /** `null` = free. Amount as sent by OPS; nothing is calculated here. */
+    fee: Money | null;
+    free: boolean;
+    /** Formatted `fee` (`null` when free). */
+    feeText: string | null;
+    prepDays: number;
+};
+type PickupOptionProps<L extends ShopBranch = ShopBranch> = {
+    location: L;
+    locale?: string;
+    children?: (info: PickupInfo<L>) => ReactNode;
+} & Omit<ComponentPropsWithoutRef<'span'>, 'children'>;
+/** "Recoge en sucursal" terms: fee and preparation time. `null` when the branch does not offer pickup. */
+declare function PickupOption<L extends ShopBranch = ShopBranch>({ location, locale, children, ...rest }: PickupOptionProps<L>): react.JSX.Element | null;
+type NearestLocationFormLabels = {
+    postalCode: string;
+    submit: string;
+    locate: string;
+    locating: string;
+};
+type NearestLocationFormProps<L extends ShopBranch = ShopBranch> = {
+    locations?: readonly L[];
+    /** Destination of the GET (default: the current page). */
+    action?: string;
+    /** Query param and input name (default `cp`). */
+    name?: string;
+    defaultValue?: string;
+    /** With JavaScript: intercept the submit and receive the postal code. Without it the browser navigates to `?cp=`. */
+    onSubmitPostalCode?: (postalCode: string, event: FormEvent<HTMLFormElement>) => void;
+    /** Shows a "use my location" button (only when the browser supports it); it asks permission on click. */
+    onLocate?: (point: GeoPoint$1) => void;
+    labels?: Partial<NearestLocationFormLabels>;
+} & Omit<ComponentPropsWithoutRef<'form'>, 'action' | 'method' | 'onSubmit' | 'defaultValue'>;
+/**
+ * `<form method="get">` with a postal-code field: works without JavaScript (navigates to `?cp=06000`). Add
+ * `onSubmitPostalCode` / `onLocate` to enhance it. Renders `null` when there are no branches.
+ */
+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 };