@asteby/storefront-react 0.10.0 → 0.11.0

package/dist/checkout.d.cts

@@ -5,9 +5,9 @@ import { ShippingRate, PickupOption, Money } from '@asteby/storefront';
 type BrandMarkProps = {
     /** Provider identifier (`fedex`, `oxxo`, `mercadopago`, `7eleven`…). Unknown keys get a neutral monogram. */
     brand: string | null | undefined;
-    /** Licensed logo sent by the provider (`PaymentPoint.logo_url`…). Only `https:`; it wins over the badge. */
+    /** Licensed logo sent by the provider (`PaymentPoint.logo_url`…). Only `https:`; it wins over the bundled logo and the badge. */
     logoUrl?: string | null;
-    /** Height in px. The badge is 3:2 (width = 1.5 × height). Default 24. */
+    /** Height in px of the box. Badges are 3:2 (width = 1.5 × height); real logos get a width that follows their shape. Default 24. */
     size?: number;
     /**
      * Accessible name. Omit it when the brand name is already written next to the mark (the usual case): the mark is then
@@ -16,16 +16,25 @@ type BrandMarkProps = {
     title?: string;
     className?: string;
 };
+/** What the mark ended up drawing: the provider's logo, the bundled real logo, or the typographic fallback. */
+type BrandMarkSource = 'provider' | 'logo' | 'badge';
 /**
- * The mark of a carrier, card network, wallet or cash point: an inline SVG badge in the brand color with its short
- * wordmark (no network request, same size on the server and in the browser, so no layout shift). With `logoUrl` it
- * draws the provider's licensed logo instead, lazily, with fixed dimensions.
+ * The mark of a carrier, card network, wallet or cash point. Precedence: the provider's `logoUrl` (https, lazy) > the
+ * real logo bundled with the package (inline data URI: no network request, same size on the server and in the browser)
+ * > a typographic badge in the brand color for the brands without an available logo.
  *
- * The badge carries its own background, so it keeps its contrast on light and dark themes; a hairline
- * (`--sf-brand-mark-ring`) separates it from the page.
+ * Logos are never recolored; they sit on a white plate with a hairline (`--sf-brand-mark-ring`, plate color
+ * `--sf-brand-mark-plate`) so they keep their contrast on light and dark themes. The element carries
+ * `data-sf-brand-mark="<key>"` and `data-sf-brand-source="provider|logo|badge"`.
  */
 declare function BrandMark({ brand, logoUrl, size, title, className }: BrandMarkProps): react.JSX.Element;
 
+type LogoAsset = {
+    src: string;
+    ar: number;
+    mono: boolean;
+};
+
 /**
  * Shared catalog of the brands a checkout names: parcel carriers, card networks, wallets and cash payment points.
  *
@@ -33,10 +42,12 @@ declare function BrandMark({ brand, logoUrl, size, title, className }: BrandMark
  * `PaymentPoint.payment_point` or `id` of the payment addon, a `PaymentMethod.key`). Nothing here decides what a shop
  * offers: the server lists the rates and methods; this only gives each one its commercial name and a mark.
  *
- * Marks are typographic badges drawn by `<BrandMark>` (brand color + short wordmark): no third-party logo files are
- * bundled, so there is no licensing question and no extra request. A provider that holds a licensed logo sends it as
- * `logo_url` and it wins over the badge. Colors are close approximations of each brand's public color.
+ * Marks are drawn by `<BrandMark>` with this precedence: the provider's `logo_url` > the real logo bundled in
+ * `brands/assets` (inline data URI, no request; provenance in `brands/LOGOS.md`) > a typographic badge (brand color +
+ * short wordmark) for the brands without an available logo. The `bg`/`fg` colors here are close approximations of each
+ * brand's public color and only paint that fallback badge.
  */
+
 type BrandKind = 'carrier' | 'card' | 'wallet' | 'cash' | 'bank';
 type Brand = {
     key: string;
@@ -63,6 +74,10 @@ declare function findBrand(raw: string | null | undefined): Brand | null;
 declare function brandName(raw: string | null | undefined): string | null;
 /** Every brand of the catalog (for docs, previews and tests). */
 declare function listBrands(kind?: BrandKind): Brand[];
+/** Real logo bundled for a provider identifier (inline data URI), or `null` when the brand only has the fallback badge. */
+declare function brandLogo(raw: string | null | undefined): (LogoAsset & {
+    key: string;
+}) | null;
 
 /**
  * Pure helpers for the "Delivery" step: how to name a carrier rate, its arrival time, which rate is the cheapest or the
@@ -194,4 +209,4 @@ type DeliveryOptionsProps = {
  */
 declare function DeliveryOptions(props: DeliveryOptionsProps): react.JSX.Element;
 
-export { type Brand, type BrandKind, BrandMark, type BrandMarkProps, type DeliveryMessages, DeliveryOptions, type DeliveryOptionsClassNames, type DeliveryOptionsProps, type QuoteNote, type RateBadge, brandKey, brandName, deliveryMessages, findBrand, isQuoteChange, listBrands, matchRate, quoteDeadline, quoteNote, rateBadges, rateCarrier, rateEta, rateService };
+export { type Brand, type BrandKind, BrandMark, type BrandMarkProps, type BrandMarkSource, type DeliveryMessages, DeliveryOptions, type DeliveryOptionsClassNames, type DeliveryOptionsProps, type QuoteNote, type RateBadge, brandKey, brandLogo, brandName, deliveryMessages, findBrand, isQuoteChange, listBrands, matchRate, quoteDeadline, quoteNote, rateBadges, rateCarrier, rateEta, rateService };

package/dist/checkout.d.ts

@@ -5,9 +5,9 @@ import { ShippingRate, PickupOption, Money } from '@asteby/storefront';
 type BrandMarkProps = {
     /** Provider identifier (`fedex`, `oxxo`, `mercadopago`, `7eleven`…). Unknown keys get a neutral monogram. */
     brand: string | null | undefined;
-    /** Licensed logo sent by the provider (`PaymentPoint.logo_url`…). Only `https:`; it wins over the badge. */
+    /** Licensed logo sent by the provider (`PaymentPoint.logo_url`…). Only `https:`; it wins over the bundled logo and the badge. */
     logoUrl?: string | null;
-    /** Height in px. The badge is 3:2 (width = 1.5 × height). Default 24. */
+    /** Height in px of the box. Badges are 3:2 (width = 1.5 × height); real logos get a width that follows their shape. Default 24. */
     size?: number;
     /**
      * Accessible name. Omit it when the brand name is already written next to the mark (the usual case): the mark is then
@@ -16,16 +16,25 @@ type BrandMarkProps = {
     title?: string;
     className?: string;
 };
+/** What the mark ended up drawing: the provider's logo, the bundled real logo, or the typographic fallback. */
+type BrandMarkSource = 'provider' | 'logo' | 'badge';
 /**
- * The mark of a carrier, card network, wallet or cash point: an inline SVG badge in the brand color with its short
- * wordmark (no network request, same size on the server and in the browser, so no layout shift). With `logoUrl` it
- * draws the provider's licensed logo instead, lazily, with fixed dimensions.
+ * The mark of a carrier, card network, wallet or cash point. Precedence: the provider's `logoUrl` (https, lazy) > the
+ * real logo bundled with the package (inline data URI: no network request, same size on the server and in the browser)
+ * > a typographic badge in the brand color for the brands without an available logo.
  *
- * The badge carries its own background, so it keeps its contrast on light and dark themes; a hairline
- * (`--sf-brand-mark-ring`) separates it from the page.
+ * Logos are never recolored; they sit on a white plate with a hairline (`--sf-brand-mark-ring`, plate color
+ * `--sf-brand-mark-plate`) so they keep their contrast on light and dark themes. The element carries
+ * `data-sf-brand-mark="<key>"` and `data-sf-brand-source="provider|logo|badge"`.
  */
 declare function BrandMark({ brand, logoUrl, size, title, className }: BrandMarkProps): react.JSX.Element;
 
+type LogoAsset = {
+    src: string;
+    ar: number;
+    mono: boolean;
+};
+
 /**
  * Shared catalog of the brands a checkout names: parcel carriers, card networks, wallets and cash payment points.
  *
@@ -33,10 +42,12 @@ declare function BrandMark({ brand, logoUrl, size, title, className }: BrandMark
  * `PaymentPoint.payment_point` or `id` of the payment addon, a `PaymentMethod.key`). Nothing here decides what a shop
  * offers: the server lists the rates and methods; this only gives each one its commercial name and a mark.
  *
- * Marks are typographic badges drawn by `<BrandMark>` (brand color + short wordmark): no third-party logo files are
- * bundled, so there is no licensing question and no extra request. A provider that holds a licensed logo sends it as
- * `logo_url` and it wins over the badge. Colors are close approximations of each brand's public color.
+ * Marks are drawn by `<BrandMark>` with this precedence: the provider's `logo_url` > the real logo bundled in
+ * `brands/assets` (inline data URI, no request; provenance in `brands/LOGOS.md`) > a typographic badge (brand color +
+ * short wordmark) for the brands without an available logo. The `bg`/`fg` colors here are close approximations of each
+ * brand's public color and only paint that fallback badge.
  */
+
 type BrandKind = 'carrier' | 'card' | 'wallet' | 'cash' | 'bank';
 type Brand = {
     key: string;
@@ -63,6 +74,10 @@ declare function findBrand(raw: string | null | undefined): Brand | null;
 declare function brandName(raw: string | null | undefined): string | null;
 /** Every brand of the catalog (for docs, previews and tests). */
 declare function listBrands(kind?: BrandKind): Brand[];
+/** Real logo bundled for a provider identifier (inline data URI), or `null` when the brand only has the fallback badge. */
+declare function brandLogo(raw: string | null | undefined): (LogoAsset & {
+    key: string;
+}) | null;
 
 /**
  * Pure helpers for the "Delivery" step: how to name a carrier rate, its arrival time, which rate is the cheapest or the
@@ -194,4 +209,4 @@ type DeliveryOptionsProps = {
  */
 declare function DeliveryOptions(props: DeliveryOptionsProps): react.JSX.Element;
 
-export { type Brand, type BrandKind, BrandMark, type BrandMarkProps, type DeliveryMessages, DeliveryOptions, type DeliveryOptionsClassNames, type DeliveryOptionsProps, type QuoteNote, type RateBadge, brandKey, brandName, deliveryMessages, findBrand, isQuoteChange, listBrands, matchRate, quoteDeadline, quoteNote, rateBadges, rateCarrier, rateEta, rateService };
+export { type Brand, type BrandKind, BrandMark, type BrandMarkProps, type BrandMarkSource, type DeliveryMessages, DeliveryOptions, type DeliveryOptionsClassNames, type DeliveryOptionsProps, type QuoteNote, type RateBadge, brandKey, brandLogo, brandName, deliveryMessages, findBrand, isQuoteChange, listBrands, matchRate, quoteDeadline, quoteNote, rateBadges, rateCarrier, rateEta, rateService };

package/dist/checkout.js

@@ -1,5 +1,5 @@
-import { brandName, BrandMark } from './chunk-DSZVJ2PW.js';
-export { BrandMark, brandKey, brandName, findBrand, listBrands } from './chunk-DSZVJ2PW.js';
+import { brandName, BrandMark } from './chunk-3ZJTDFHE.js';
+export { BrandMark, brandKey, brandLogo, brandName, findBrand, listBrands } from './chunk-3ZJTDFHE.js';
 import { useResolvedLocale } from './chunk-T52H5HL3.js';
 import './chunk-DQBL2DFJ.js';
 import { useMemo, useSyncExternalStore } from 'react';