@cartbase/storefront 0.19.0 → 0.20.1

package/src/common/index.ts

@@ -1,20 +1,20 @@
-/**
- * @cartbase/storefront/common — shared storefront chrome. Ported from
- * `@1click/ui/src/common` (v2.3.1) + `LocalizedLink` (from the
- * mindpages-storefront production component); Cartbase data seams per
- * module JSDoc.
- */
-export { LocalizedLink, type LocalizedLinkProps } from "./localized-link"
-export { CartButton } from "./cart-button"
-export { CartButtonClient } from "./cart-button-client"
-export { DeleteButton, type DeleteButtonProps } from "./delete-button"
-export { CountryFlag } from "./country-flag"
-export { MarketSelect, type MarketSelectProps } from "./market-select"
-/** @deprecated the old name of `MarketSelect`, kept for one release (2026-09-14). */
-export { CountrySelect, type CountrySelectProps } from "./country-select"
-export {
-  LanguageSelect,
-  localeDisplayName,
-  type LanguageSelectProps,
-} from "./language-select"
-export { Skeleton, SkeletonProductPreview } from "./skeleton"
+/**
+ * @cartbase/storefront/common — shared storefront chrome. Ported from
+ * `@1click/ui/src/common` (v2.3.1) + `LocalizedLink` (from the
+ * mindpages-storefront production component); Cartbase data seams per
+ * module JSDoc.
+ */
+export { LocalizedLink, type LocalizedLinkProps } from "./localized-link"
+export { CartButton } from "./cart-button"
+export { CartButtonClient } from "./cart-button-client"
+export { DeleteButton, type DeleteButtonProps } from "./delete-button"
+export { CountryFlag } from "./country-flag"
+export { MarketSelect, type MarketSelectProps } from "./market-select"
+/** @deprecated the old name of `MarketSelect`, kept for one release (2026-09-14). */
+export { CountrySelect, type CountrySelectProps } from "./country-select"
+export {
+  LanguageSelect,
+  localeDisplayName,
+  type LanguageSelectProps,
+} from "./language-select"
+export { Skeleton, SkeletonProductPreview } from "./skeleton"

package/src/common/market-select.tsx

@@ -1,57 +1,57 @@
-"use client"
-
-import { useMemo } from "react"
-import type { StoreRegion } from "../api/regions"
-
-/**
- * THE MARKET PICKER for a header or footer: the store's regions, by name.
- *
- * Ported from `@1click/ui/src/common/country-select.tsx` (v2.3.1) and
- * renamed on 2026-09-14 (store-package card, finding 6). The port carried the
- * name of a component that listed a region's countries; Cartbase regions
- * carry no countries on the store surface, so it listed the REGIONS
- * themselves and was named for something it did not do. A market is what a
- * shopper picks here; a country is picked in the checkout, from
- * `listCountries`, with `CountryFlag` beside it.
- *
- * Persistence is the app's: `onChange` hands over the chosen region and the
- * app writes it where it keeps it (usually `carts.updateCart(client, cartId,
- * { region_id })` plus a cookie).
- */
-export type MarketSelectProps = {
-  regions: StoreRegion[]
-  /** The active region's id. */
-  value?: string | null
-  /** Fired with the chosen region; persist it app-side. */
-  onChange: (region: StoreRegion) => void
-  className?: string
-}
-
-export function MarketSelect({ regions, value, onChange, className }: MarketSelectProps) {
-  const options = useMemo(
-    () => [...regions].sort((a, b) => (a.name ?? "").localeCompare(b.name ?? "")),
-    [regions]
-  )
-
-  const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
-    const selected = options.find((r) => r.id === e.target.value)
-    if (selected) onChange(selected)
-  }
-
-  return (
-    <select
-      value={value || ""}
-      onChange={handleChange}
-      className={
-        className ??
-        "text-sm text-foreground bg-card border border-border rounded-lg px-3 py-2"
-      }
-    >
-      {options.map((r) => (
-        <option key={r.id} value={r.id}>
-          {r.name}
-        </option>
-      ))}
-    </select>
-  )
-}
+"use client"
+
+import { useMemo } from "react"
+import type { StoreRegion } from "../api/regions"
+
+/**
+ * THE MARKET PICKER for a header or footer: the store's regions, by name.
+ *
+ * Ported from `@1click/ui/src/common/country-select.tsx` (v2.3.1) and
+ * renamed on 2026-09-14 (store-package card, finding 6). The port carried the
+ * name of a component that listed a region's countries; Cartbase regions
+ * carry no countries on the store surface, so it listed the REGIONS
+ * themselves and was named for something it did not do. A market is what a
+ * shopper picks here; a country is picked in the checkout, from
+ * `listCountries`, with `CountryFlag` beside it.
+ *
+ * Persistence is the app's: `onChange` hands over the chosen region and the
+ * app writes it where it keeps it (usually `carts.updateCart(client, cartId,
+ * { region_id })` plus a cookie).
+ */
+export type MarketSelectProps = {
+  regions: StoreRegion[]
+  /** The active region's id. */
+  value?: string | null
+  /** Fired with the chosen region; persist it app-side. */
+  onChange: (region: StoreRegion) => void
+  className?: string
+}
+
+export function MarketSelect({ regions, value, onChange, className }: MarketSelectProps) {
+  const options = useMemo(
+    () => [...regions].sort((a, b) => (a.name ?? "").localeCompare(b.name ?? "")),
+    [regions]
+  )
+
+  const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
+    const selected = options.find((r) => r.id === e.target.value)
+    if (selected) onChange(selected)
+  }
+
+  return (
+    <select
+      value={value || ""}
+      onChange={handleChange}
+      className={
+        className ??
+        "text-sm text-foreground bg-card border border-border rounded-lg px-3 py-2"
+      }
+    >
+      {options.map((r) => (
+        <option key={r.id} value={r.id}>
+          {r.name}
+        </option>
+      ))}
+    </select>
+  )
+}

package/src/index.ts

@@ -1,12 +1,12 @@
-/**
- * @cartbase/storefront — root barrel.
- *
- * `@cartbase/storefront/api` is the SDK layer (typed store-API client).
- * Component families ship under their own subpath exports (stage 3) and are
- * NOT re-exported here — UI imports stay per-module so tree-shaking and
- * client/server boundaries stay explicit, same discipline as @1click/ui.
- */
-
-export * from "./api/types"
-export { StorefrontClient } from "./api/http"
-export type { StorefrontClientConfig } from "./api/http"
+/**
+ * @cartbase/storefront — root barrel.
+ *
+ * `@cartbase/storefront/api` is the SDK layer (typed store-API client).
+ * Component families ship under their own subpath exports (stage 3) and are
+ * NOT re-exported here — UI imports stay per-module so tree-shaking and
+ * client/server boundaries stay explicit, same discipline as @1click/ui.
+ */
+
+export * from "./api/types"
+export { StorefrontClient } from "./api/http"
+export type { StorefrontClientConfig } from "./api/http"

package/src/lib/country-name.ts

@@ -1,59 +1,59 @@
-/**
- * The name of a country, from its ISO-3166 alpha-2 code.
- *
- * A code is a machine string: "bg" is how a cart address stores a country,
- * never how a shopper reads it. The catalogue from
- * `GET /api/store/countries` carries real names, so this is for the one case
- * where a code arrives WITHOUT one: the checkout hook's fallback when the
- * country list cannot be loaded. It used to hand the address form
- * `{iso_2: "bg", display_name: ""}`, and the form rendered an EMPTY country
- * field (found on evoo, 2026-09-13).
- *
- * `Intl.DisplayNames` is in the runtime, so this needs no bundled table and
- * knows every country in every language the browser does.
- *
- * THE LOCALE IS EXPLICIT AND DEFAULTS TO ENGLISH ON PURPOSE. Letting Intl
- * pick the runtime default would name the country in the SERVER's language
- * during a server render and in the BROWSER's language after hydration,
- * which is a hydration mismatch on any store whose visitors are not in the
- * server's locale. Pass the store's own language to translate it:
- *
- *   const locale = useStorefrontLocale()
- *   countryName("bg", locale.code)   // "България"
- *
- * Three behaviours verified against the runtime rather than assumed
- * (2026-09-13): a LOWERCASE code returns itself unchanged, so the code is
- * uppercased here; a malformed code throws `RangeError`, so it is shape
- * checked and wrapped; and an unknown-but-well-formed code resolves to
- * "Unknown Region" unless `fallback: "none"` is set, which is why it is set
- * and why the uppercase code is the last resort.
- */
-
-const cache = new Map<string, Intl.DisplayNames>()
-
-function namer(locale: string): Intl.DisplayNames | null {
-  const hit = cache.get(locale)
-  if (hit) return hit
-  try {
-    const made = new Intl.DisplayNames([locale], { type: "region", fallback: "none" })
-    cache.set(locale, made)
-    return made
-  } catch {
-    return null
-  }
-}
-
-export function countryName(
-  code: string | null | undefined,
-  locale: string = "en"
-): string {
-  const iso2 = code?.trim()
-  if (!iso2 || !/^[a-z]{2}$/i.test(iso2)) return ""
-
-  const upper = iso2.toUpperCase()
-  try {
-    return namer(locale)?.of(upper) || upper
-  } catch {
-    return upper
-  }
-}
+/**
+ * The name of a country, from its ISO-3166 alpha-2 code.
+ *
+ * A code is a machine string: "bg" is how a cart address stores a country,
+ * never how a shopper reads it. The catalogue from
+ * `GET /api/store/countries` carries real names, so this is for the one case
+ * where a code arrives WITHOUT one: the checkout hook's fallback when the
+ * country list cannot be loaded. It used to hand the address form
+ * `{iso_2: "bg", display_name: ""}`, and the form rendered an EMPTY country
+ * field (found on evoo, 2026-09-13).
+ *
+ * `Intl.DisplayNames` is in the runtime, so this needs no bundled table and
+ * knows every country in every language the browser does.
+ *
+ * THE LOCALE IS EXPLICIT AND DEFAULTS TO ENGLISH ON PURPOSE. Letting Intl
+ * pick the runtime default would name the country in the SERVER's language
+ * during a server render and in the BROWSER's language after hydration,
+ * which is a hydration mismatch on any store whose visitors are not in the
+ * server's locale. Pass the store's own language to translate it:
+ *
+ *   const locale = useStorefrontLocale()
+ *   countryName("bg", locale.code)   // "България"
+ *
+ * Three behaviours verified against the runtime rather than assumed
+ * (2026-09-13): a LOWERCASE code returns itself unchanged, so the code is
+ * uppercased here; a malformed code throws `RangeError`, so it is shape
+ * checked and wrapped; and an unknown-but-well-formed code resolves to
+ * "Unknown Region" unless `fallback: "none"` is set, which is why it is set
+ * and why the uppercase code is the last resort.
+ */
+
+const cache = new Map<string, Intl.DisplayNames>()
+
+function namer(locale: string): Intl.DisplayNames | null {
+  const hit = cache.get(locale)
+  if (hit) return hit
+  try {
+    const made = new Intl.DisplayNames([locale], { type: "region", fallback: "none" })
+    cache.set(locale, made)
+    return made
+  } catch {
+    return null
+  }
+}
+
+export function countryName(
+  code: string | null | undefined,
+  locale: string = "en"
+): string {
+  const iso2 = code?.trim()
+  if (!iso2 || !/^[a-z]{2}$/i.test(iso2)) return ""
+
+  const upper = iso2.toUpperCase()
+  try {
+    return namer(locale)?.of(upper) || upper
+  } catch {
+    return upper
+  }
+}

package/src/lib/get-product-price.ts

@@ -1,133 +1,133 @@
-import { getPercentageDiff } from "./get-percentage-diff"
-import { convertToLocale } from "./money"
-
-/**
- * Product price extraction — ported from
- * `@1click/ui/src/lib/get-product-price.ts` (v2.3.1). The
- * `@medusajs/types` `HttpTypes.StoreProduct` parameter is replaced by the
- * structural shapes below so this module stays decoupled from the SDK
- * domain modules (Cartbase's `variant.calculated_price` is the b2b-v1
- * pricing context documented in `@cartbase/storefront/api/types`
- * `CalculatedPrice`, decimal EUR major units).
- *
- * Wire-shape note (code truth, `src/lib/products/pricing.ts`): Cartbase serves
- * `calculated_price.price_list_type` FLAT on the calculated_price object.
- * The Medusa wire shape ALSO nests a `calculated_price.calculated_price`
- * detail object carrying `price_list_type` — the original library read the
- * nested path. `getPricesForVariant` reads the flat key first and falls
- * back to the nested path so both shapes produce the same result.
- */
-
-/** Structural `variant.calculated_price` shape (see api/types CalculatedPrice). */
-export type CalculatedPriceLike = {
-  calculated_amount: number
-  original_amount: number
-  currency_code: string
-  price_list_type?: string | null
-  /** Medusa-wire nested detail object (fallback path). */
-  calculated_price?: { price_list_type?: string | null } | null
-}
-
-/** Structural variant shape — any richer product-variant DTO satisfies it. */
-export type VariantWithPrice = {
-  id?: string
-  sku?: string | null
-  calculated_price?: CalculatedPriceLike | null
-}
-
-/** Structural product shape — any richer product DTO satisfies it. */
-export type ProductWithVariants = {
-  id?: string
-  variants?: VariantWithPrice[] | null
-}
-
-export type VariantPrice = {
-  calculated_price_number: number
-  calculated_price: string
-  original_price_number: number
-  original_price: string
-  currency_code: string
-  price_type: string | null | undefined
-  percentage_diff: string
-}
-
-export const getPricesForVariant = (
-  variant: VariantWithPrice | null | undefined
-): VariantPrice | null => {
-  if (!variant?.calculated_price?.calculated_amount) {
-    return null
-  }
-
-  const cp = variant.calculated_price
-  return {
-    calculated_price_number: cp.calculated_amount,
-    calculated_price: convertToLocale({
-      amount: cp.calculated_amount,
-      currency_code: cp.currency_code,
-    }),
-    original_price_number: cp.original_amount,
-    original_price: convertToLocale({
-      amount: cp.original_amount,
-      currency_code: cp.currency_code,
-    }),
-    currency_code: cp.currency_code,
-    // Flat key (Cartbase wire shape) first — an explicit null stays null;
-    // the nested Medusa detail is the fallback only when the flat key is
-    // absent entirely (the original @1click read path).
-    price_type:
-      cp.price_list_type !== undefined
-        ? cp.price_list_type
-        : cp.calculated_price?.price_list_type,
-    percentage_diff: getPercentageDiff(cp.original_amount, cp.calculated_amount),
-  }
-}
-
-export function getProductPrice({
-  product,
-  variantId,
-}: {
-  product: ProductWithVariants
-  variantId?: string
-}) {
-  if (!product || !product.id) {
-    throw new Error("No product provided")
-  }
-
-  const cheapestPrice = (): VariantPrice | null => {
-    if (!product || !product.variants?.length) {
-      return null
-    }
-
-    const cheapestVariant = product.variants
-      .filter((v) => !!v.calculated_price)
-      .sort(
-        (a, b) =>
-          (a.calculated_price?.calculated_amount ?? 0) -
-          (b.calculated_price?.calculated_amount ?? 0)
-      )[0]
-
-    return getPricesForVariant(cheapestVariant)
-  }
-
-  const variantPrice = (): VariantPrice | null => {
-    if (!product || !variantId) {
-      return null
-    }
-
-    const variant = product.variants?.find(
-      (v) => v.id === variantId || v.sku === variantId
-    )
-
-    if (!variant) {
-      return null
-    }
-
-    return getPricesForVariant(variant)
-  }
-
-  return {
-    product,
-    cheapestPrice: cheapestPrice(),
-    variantPrice: variantPrice(),
-  }
-}
+import { getPercentageDiff } from "./get-percentage-diff"
+import { convertToLocale } from "./money"
+
+/**
+ * Product price extraction — ported from
+ * `@1click/ui/src/lib/get-product-price.ts` (v2.3.1). The
+ * `@medusajs/types` `HttpTypes.StoreProduct` parameter is replaced by the
+ * structural shapes below so this module stays decoupled from the SDK
+ * domain modules (Cartbase's `variant.calculated_price` is the b2b-v1
+ * pricing context documented in `@cartbase/storefront/api/types`
+ * `CalculatedPrice`, decimal EUR major units).
+ *
+ * Wire-shape note (code truth, `src/lib/products/pricing.ts`): Cartbase serves
+ * `calculated_price.price_list_type` FLAT on the calculated_price object.
+ * The Medusa wire shape ALSO nests a `calculated_price.calculated_price`
+ * detail object carrying `price_list_type` — the original library read the
+ * nested path. `getPricesForVariant` reads the flat key first and falls
+ * back to the nested path so both shapes produce the same result.
+ */
+
+/** Structural `variant.calculated_price` shape (see api/types CalculatedPrice). */
+export type CalculatedPriceLike = {
+  calculated_amount: number
+  original_amount: number
+  currency_code: string
+  price_list_type?: string | null
+  /** Medusa-wire nested detail object (fallback path). */
+  calculated_price?: { price_list_type?: string | null } | null
+}
+
+/** Structural variant shape — any richer product-variant DTO satisfies it. */
+export type VariantWithPrice = {
+  id?: string
+  sku?: string | null
+  calculated_price?: CalculatedPriceLike | null
+}
+
+/** Structural product shape — any richer product DTO satisfies it. */
+export type ProductWithVariants = {
+  id?: string
+  variants?: VariantWithPrice[] | null
+}
+
+export type VariantPrice = {
+  calculated_price_number: number
+  calculated_price: string
+  original_price_number: number
+  original_price: string
+  currency_code: string
+  price_type: string | null | undefined
+  percentage_diff: string
+}
+
+export const getPricesForVariant = (
+  variant: VariantWithPrice | null | undefined
+): VariantPrice | null => {
+  if (!variant?.calculated_price?.calculated_amount) {
+    return null
+  }
+
+  const cp = variant.calculated_price
+  return {
+    calculated_price_number: cp.calculated_amount,
+    calculated_price: convertToLocale({
+      amount: cp.calculated_amount,
+      currency_code: cp.currency_code,
+    }),
+    original_price_number: cp.original_amount,
+    original_price: convertToLocale({
+      amount: cp.original_amount,
+      currency_code: cp.currency_code,
+    }),
+    currency_code: cp.currency_code,
+    // Flat key (Cartbase wire shape) first — an explicit null stays null;
+    // the nested Medusa detail is the fallback only when the flat key is
+    // absent entirely (the original @1click read path).
+    price_type:
+      cp.price_list_type !== undefined
+        ? cp.price_list_type
+        : cp.calculated_price?.price_list_type,
+    percentage_diff: getPercentageDiff(cp.original_amount, cp.calculated_amount),
+  }
+}
+
+export function getProductPrice({
+  product,
+  variantId,
+}: {
+  product: ProductWithVariants
+  variantId?: string
+}) {
+  if (!product || !product.id) {
+    throw new Error("No product provided")
+  }
+
+  const cheapestPrice = (): VariantPrice | null => {
+    if (!product || !product.variants?.length) {
+      return null
+    }
+
+    const cheapestVariant = product.variants
+      .filter((v) => !!v.calculated_price)
+      .sort(
+        (a, b) =>
+          (a.calculated_price?.calculated_amount ?? 0) -
+          (b.calculated_price?.calculated_amount ?? 0)
+      )[0]
+
+    return getPricesForVariant(cheapestVariant)
+  }
+
+  const variantPrice = (): VariantPrice | null => {
+    if (!product || !variantId) {
+      return null
+    }
+
+    const variant = product.variants?.find(
+      (v) => v.id === variantId || v.sku === variantId
+    )
+
+    if (!variant) {
+      return null
+    }
+
+    return getPricesForVariant(variant)
+  }
+
+  return {
+    product,
+    cheapestPrice: cheapestPrice(),
+    variantPrice: variantPrice(),
+  }
+}

package/src/lib/media-image.tsx

@@ -1,39 +1,39 @@
-import NextImage, { type ImageProps } from "next/image"
-
-/**
- * The store's picture element (store-speed-law card, step 3, 2026-09-15).
- *
- * Product pictures live on the Cartbase media CDN, and Next resizes them on
- * the store's own project, per device and in the modern formats, which the
- * scaffold allows through `images.remotePatterns` (next.config.ts). The
- * scaffold used to ship `images.unoptimized: true` instead, so no picture
- * was ever resized: a phone downloaded the merchant's full upload.
- *
- * A picture from any other host (a catalogue not yet rehosted, a demo
- * placeholder, a merchant's own asset host) renders as it is instead of
- * failing the page: Next refuses to resize a host the config does not
- * list, so this element switches resizing off for those. A merchant who
- * adds their host to `remotePatterns` gets resizing there too by passing
- * `unoptimized={false}` where they render it, or by using `next/image`
- * directly.
- */
-
-/** The public base of the media CDN (REGISTRY.md, CDN domain). */
-export const MEDIA_HOST = "cartbase.cloud"
-
-/** Is this picture served by the media CDN (or by the app itself)? */
-export function isResizableSrc(src: ImageProps["src"]): boolean {
-  if (typeof src !== "string") return true
-  if (src.startsWith("/")) return true
-  try {
-    const host = new URL(src).hostname
-    return host === MEDIA_HOST || host.endsWith(`.${MEDIA_HOST}`)
-  } catch {
-    return false
-  }
-}
-
-export function StoreImage(props: ImageProps) {
-  const unoptimized = props.unoptimized ?? !isResizableSrc(props.src)
-  return <NextImage {...props} unoptimized={unoptimized} />
-}
+import NextImage, { type ImageProps } from "next/image"
+
+/**
+ * The store's picture element (store-speed-law card, step 3, 2026-09-15).
+ *
+ * Product pictures live on the Cartbase media CDN, and Next resizes them on
+ * the store's own project, per device and in the modern formats, which the
+ * scaffold allows through `images.remotePatterns` (next.config.ts). The
+ * scaffold used to ship `images.unoptimized: true` instead, so no picture
+ * was ever resized: a phone downloaded the merchant's full upload.
+ *
+ * A picture from any other host (a catalogue not yet rehosted, a demo
+ * placeholder, a merchant's own asset host) renders as it is instead of
+ * failing the page: Next refuses to resize a host the config does not
+ * list, so this element switches resizing off for those. A merchant who
+ * adds their host to `remotePatterns` gets resizing there too by passing
+ * `unoptimized={false}` where they render it, or by using `next/image`
+ * directly.
+ */
+
+/** The public base of the media CDN (REGISTRY.md, CDN domain). */
+export const MEDIA_HOST = "cartbase.cloud"
+
+/** Is this picture served by the media CDN (or by the app itself)? */
+export function isResizableSrc(src: ImageProps["src"]): boolean {
+  if (typeof src !== "string") return true
+  if (src.startsWith("/")) return true
+  try {
+    const host = new URL(src).hostname
+    return host === MEDIA_HOST || host.endsWith(`.${MEDIA_HOST}`)
+  } catch {
+    return false
+  }
+}
+
+export function StoreImage(props: ImageProps) {
+  const unoptimized = props.unoptimized ?? !isResizableSrc(props.src)
+  return <NextImage {...props} unoptimized={unoptimized} />
+}