@zalify/storefront-kit 0.1.0

package/src/react/components/ProductCard.tsx

@@ -0,0 +1,417 @@
+/**
+ * Port of snippets/product-card.liquid — a product card for grids:
+ * square media (second image on hover), title, price, and badges
+ * (sold-out/sale/best-seller, plus merchant chips from "badge:<Label>"
+ * product tags), variant swatches / image thumbs, and quick add.
+ *
+ * The Liquid theme's <product-card> island (src/entries/cards.ts)
+ * drives swatch-hover previews and the quick-add dialog; here the same
+ * behavior lives in React state. CSS: app/styles/components/snippets-product-card.css
+ */
+import {useState} from 'react';
+import type {CardProduct} from '../../commerce/index.ts';
+import {
+  emit,
+  hasOnlyDefaultVariant,
+  numericId,
+  productUrl,
+  resolvePickerOption,
+  targetVariantFor,
+} from '../../commerce/index.ts';
+import {useAdapter} from '../adapter';
+import {Price} from './Price';
+import {Rating} from './Rating';
+import {ProductBadges, hasProductBadges} from './ProductBadges';
+import {swatchStyle} from './SwatchStyle';
+import {imageUrl, PlaceholderSvg} from '../engine/images';
+import {themeSettings} from '../engine/settings';
+import {t} from '../engine/translate';
+
+export interface ProductCardProps {
+  product: CardProduct;
+  loading?: 'eager' | 'lazy';
+}
+
+const CARD_SIZES = '(min-width: 64rem) 25vw, (min-width: 48rem) 33vw, 50vw';
+const CARD_WIDTHS = [360, 540, 720, 800];
+
+function cardSrcSet(url: string): string {
+  return CARD_WIDTHS.map((w) => `${imageUrl(url, w)} ${w}w`).join(', ');
+}
+
+/** Localized option names that mark an option as a color, for the
+ * picker resolution shared via commerce-core. */
+function colorOptionNames(): string[] {
+  return t('products.color_option_match')
+    .toLowerCase()
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
+
+export function ProductCard({product, loading = 'lazy'}: ProductCardProps) {
+  const {Link, CartAddForm} = useAdapter();
+  const url = productUrl(product);
+  const badgePosition =
+    (themeSettings.card_badge_position as string) ?? 'corner';
+  const showBadges = hasProductBadges(product);
+  const available = product.availableForSale !== false;
+  const showQuickAdd =
+    available && (themeSettings.card_show_quick_add ?? true);
+
+  const featuredImage = product.featuredImage ?? null;
+  // Mirror of `product.images[1]` — the second product image.
+  const secondaryImage =
+    (themeSettings.card_show_secondary_image ?? true)
+      ? (product.images?.nodes?.[1] ?? null)
+      : null;
+
+  // Swatch-hover preview, crossfading over the base image. The Liquid
+  // island creates the <img> on first hover; React renders it once a
+  // swatch has actually been hovered.
+  const [preview, setPreview] = useState<{src: string; visible: boolean} | null>(
+    null,
+  );
+
+  const onSwatchEnter = (mediaUrl: string | undefined) => () => {
+    // Touch devices simulate mouseover on tap; mutating the media then
+    // makes iOS treat the tap as hover and swallow the navigation
+    if (!mediaUrl) return;
+    if (
+      typeof window !== 'undefined' &&
+      window.matchMedia('(hover: none)').matches
+    ) {
+      return;
+    }
+    setPreview((previous) =>
+      previous?.src === mediaUrl
+        ? {src: mediaUrl, visible: true}
+        : {src: mediaUrl, visible: false},
+    );
+  };
+
+  const onSwatchLeave = (event: React.MouseEvent<HTMLDivElement>) => {
+    if (
+      event.relatedTarget instanceof Node &&
+      event.currentTarget.contains(event.relatedTarget)
+    ) {
+      return;
+    }
+    setPreview((previous) =>
+      previous ? {...previous, visible: false} : previous,
+    );
+  };
+
+  const onQuickAdd = (event: React.MouseEvent) => {
+    // Shell missing (customized layout): let the link navigate to the PDP
+    if (
+      typeof document === 'undefined' ||
+      !document.getElementById('QuickAddDialog')
+    ) {
+      return;
+    }
+    event.preventDefault();
+    emit('quick-add:open', {product});
+  };
+
+  // Rendered twice: hover overlay on the media (desktop) and inline
+  // under the variant picker (mobile, Glossier-style)
+  const quickAdd = hasOnlyDefaultVariant(product) ? (
+    <CartAddForm
+      lines={[
+        {
+          merchandiseId: product.selectedOrFirstAvailableVariant?.id ?? '',
+          quantity: 1,
+        },
+      ]}
+    >
+      {({submitting}) => (
+        <button
+          type="submit"
+          className="button button--secondary product-card__quick-button"
+          disabled={submitting}
+        >
+          {t('products.add_to_bag')}
+        </button>
+      )}
+    </CartAddForm>
+  ) : (
+    <Link
+      to={url}
+      className="button button--secondary product-card__quick-button"
+      onClick={onQuickAdd}
+    >
+      {t('products.add_to_bag')}
+    </Link>
+  );
+
+  // Variant display per theme settings: color swatches, variant image
+  // thumbs, or nothing.
+  const swatchStyleSetting =
+    (themeSettings.card_swatch_style as string) ?? 'variant_image';
+  const pickerOption = resolvePickerOption(
+    product,
+    swatchStyleSetting,
+    colorOptionNames(),
+  );
+  // Image thumbs: 3 + the +N tile fit a narrow mobile column
+  const valueLimit = swatchStyleSetting === 'variant_image' ? 3 : 4;
+  const extraCount = pickerOption
+    ? pickerOption.optionValues.length - valueLimit
+    : 0;
+
+  return (
+    <div className="product-card">
+      <div className="product-card__frame">
+        <Link
+          to={url}
+          className="product-card__media"
+          aria-label={product.title}
+        >
+          {featuredImage ? (
+            <>
+              <img
+                className="product-card__image"
+                src={imageUrl(featuredImage.url, 800)}
+                srcSet={cardSrcSet(featuredImage.url)}
+                sizes={CARD_SIZES}
+                loading={loading}
+                alt={featuredImage.altText ?? ''}
+                width={featuredImage.width ?? undefined}
+                height={featuredImage.height ?? undefined}
+              />
+              {secondaryImage ? (
+                <img
+                  className="product-card__image product-card__image--hover"
+                  src={imageUrl(secondaryImage.url, 800)}
+                  srcSet={cardSrcSet(secondaryImage.url)}
+                  sizes={CARD_SIZES}
+                  loading="lazy"
+                  alt=""
+                  aria-hidden="true"
+                  width={secondaryImage.width ?? undefined}
+                  height={secondaryImage.height ?? undefined}
+                />
+              ) : null}
+            </>
+          ) : (
+            <PlaceholderSvg className="product-card__placeholder" />
+          )}
+
+          {preview ? (
+            <img
+              className={`product-card__image product-card__image--preview${
+                preview.visible ? ' is-visible' : ''
+              }`}
+              src={preview.src}
+              alt=""
+              aria-hidden="true"
+              onLoad={() =>
+                setPreview((previous) =>
+                  previous ? {...previous, visible: true} : previous,
+                )
+              }
+            />
+          ) : null}
+
+          {badgePosition === 'corner' && showBadges ? (
+            <div className="product-card__badges">
+              <ProductBadges product={product} />
+            </div>
+          ) : null}
+        </Link>
+
+        {showQuickAdd ? (
+          <div className="product-card__quick product-card__quick--overlay">
+            {quickAdd}
+          </div>
+        ) : null}
+      </div>
+
+      <div
+        className="product-card__info stack"
+        style={{'--stack-gap': 'var(--space-2xs)'} as React.CSSProperties}
+      >
+        {badgePosition === 'below' && showBadges ? (
+          <div className="product-card__badges">
+            <ProductBadges product={product} />
+          </div>
+        ) : null}
+        <h3 className="product-card__title">
+          <Link to={url}>{product.title}</Link>
+        </h3>
+        <Price
+          price={product.priceRange?.minVariantPrice}
+          compareAt={product.compareAtPriceRange?.minVariantPrice}
+          unitPrice={product.selectedOrFirstAvailableVariant?.unitPrice}
+          unitPriceMeasurement={
+            product.selectedOrFirstAvailableVariant?.unitPriceMeasurement
+          }
+        />
+        {themeSettings.card_show_rating ? <Rating product={product} /> : null}
+
+        {pickerOption ? (
+          <div className="product-card__swatches" onMouseOut={onSwatchLeave}>
+            {pickerOption.optionValues.slice(0, valueLimit).map((value) => {
+              const targetVariant = targetVariantFor(
+                product,
+                pickerOption,
+                value.name,
+              );
+              const valueUrl = targetVariant
+                ? `${url}?variant=${numericId(targetVariant.id)}`
+                : url;
+              const cardMediaUrl = targetVariant?.image
+                ? imageUrl(targetVariant.image.url, 800)
+                : undefined;
+
+              if (swatchStyleSetting === 'variant_image') {
+                if (!targetVariant?.image) return null;
+                return (
+                  <Link
+                    key={value.name}
+                    className="product-card__variant-thumb"
+                    to={valueUrl}
+                    data-card-media={cardMediaUrl}
+                    onMouseOver={onSwatchEnter(cardMediaUrl)}
+                    aria-label={`${product.title} – ${value.name}`}
+                  >
+                    <img
+                      src={imageUrl(targetVariant.image.url, 80)}
+                      loading="lazy"
+                      alt={targetVariant.image.altText ?? ''}
+                    />
+                  </Link>
+                );
+              }
+              return (
+                <Link
+                  key={value.name}
+                  className="swatch swatch--sm"
+                  to={valueUrl}
+                  data-card-media={cardMediaUrl}
+                  onMouseOver={
+                    cardMediaUrl ? onSwatchEnter(cardMediaUrl) : undefined
+                  }
+                  style={swatchStyle(value.name, value.swatch)}
+                  aria-label={`${product.title} – ${value.name}`}
+                ></Link>
+              );
+            })}
+            {extraCount > 0 ? (
+              swatchStyleSetting === 'variant_image' ? (
+                <Link
+                  className="product-card__swatch-count product-card__swatch-count--tile"
+                  to={url}
+                  aria-label={t('products.choose_options')}
+                >
+                  +{extraCount}
+                </Link>
+              ) : (
+                <span className="product-card__swatch-count" aria-hidden="true">
+                  +{extraCount}
+                </span>
+              )
+            ) : null}
+          </div>
+        ) : null}
+
+        {showQuickAdd ? (
+          <div className="product-card__quick product-card__quick--inline">
+            {quickAdd}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Storefront API fragment every section loader uses for product cards.
+ * Spread into queries as `...ProductCard` and interpolate the constant
+ * (it carries its own nested ProductCardVariant fragment).
+ *
+ * Mirrors what snippets/product-card.liquid + sections/quick-add.liquid
+ * read from the Liquid product drop: images, price/compare/unit price,
+ * the full variant list (option probing + quick-add variant
+ * resolution), option swatches, and the standardized review metafields.
+ */
+export const PRODUCT_CARD_FRAGMENT = `#graphql
+  fragment ProductCardVariant on ProductVariant {
+    id
+    availableForSale
+    image {
+      id
+      url
+      altText
+      width
+      height
+    }
+    price { amount currencyCode }
+    compareAtPrice { amount currencyCode }
+    unitPrice { amount currencyCode }
+    unitPriceMeasurement { referenceValue referenceUnit }
+    selectedOptions { name value }
+  }
+  fragment ProductCard on Product {
+    id
+    handle
+    title
+    vendor
+    tags
+    availableForSale
+    featuredImage {
+      id
+      url
+      altText
+      width
+      height
+    }
+    images(first: 2) {
+      nodes {
+        id
+        url
+        altText
+        width
+        height
+      }
+    }
+    priceRange {
+      minVariantPrice { amount currencyCode }
+      maxVariantPrice { amount currencyCode }
+    }
+    compareAtPriceRange {
+      minVariantPrice { amount currencyCode }
+      maxVariantPrice { amount currencyCode }
+    }
+    options {
+      name
+      optionValues {
+        name
+        swatch {
+          color
+          image {
+            previewImage { url }
+          }
+        }
+        firstSelectableVariant {
+          ...ProductCardVariant
+        }
+      }
+    }
+    selectedOrFirstAvailableVariant {
+      ...ProductCardVariant
+    }
+    variants(first: 50) {
+      nodes {
+        ...ProductCardVariant
+      }
+    }
+    rating: metafield(namespace: "reviews", key: "rating") {
+      value
+    }
+    ratingCount: metafield(namespace: "reviews", key: "rating_count") {
+      value
+    }
+  }
+` as const;

package/src/react/components/Rating.tsx

@@ -0,0 +1,59 @@
+/**
+ * Port of snippets/rating.liquid — compact review score (star, average,
+ * review count) from the standardized review metafields reviews.rating
+ * and reviews.rating_count (aliased `rating` / `ratingCount` in
+ * PRODUCT_CARD_FRAGMENT). Renders nothing for products without reviews.
+ * CSS: app/styles/components/snippets-rating.css
+ */
+import type {CardProduct} from '../../commerce/index.ts';
+import {Icon} from './Icon';
+import {t} from '../engine/translate';
+
+interface RatingValue {
+  rating: number;
+  scaleMax: number;
+}
+
+/**
+ * `reviews.rating` is a `rating` type metafield; the Storefront API
+ * returns its value as JSON: {"value":"4.5","scale_min":"1.0","scale_max":"5.0"}.
+ */
+function parseRating(raw: string | null | undefined): RatingValue | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const rating = Number(parsed.value ?? parsed.rating);
+    if (!Number.isFinite(rating)) return null;
+    const scaleMax = Number(parsed.scale_max);
+    return {rating, scaleMax: Number.isFinite(scaleMax) ? scaleMax : 5};
+  } catch {
+    // Plain number value (some apps write a number_decimal metafield)
+    const rating = Number(raw);
+    return Number.isFinite(rating) ? {rating, scaleMax: 5} : null;
+  }
+}
+
+export function Rating({product}: {product: CardProduct}) {
+  const rating = parseRating(product.rating?.value);
+  const ratingCount = Number(product.ratingCount?.value ?? 0);
+  if (!rating || !(ratingCount > 0)) return null;
+
+  return (
+    <div
+      className="rating"
+      aria-label={t('products.rating_label', {
+        rating: rating.rating,
+        max: rating.scaleMax,
+        count: ratingCount,
+      })}
+    >
+      <span className="rating__star" aria-hidden="true">
+        <Icon name="icon-star" />
+      </span>
+      <span aria-hidden="true">{Math.round(rating.rating * 10) / 10}</span>
+      <span className="rating__count" aria-hidden="true">
+        ({ratingCount})
+      </span>
+    </div>
+  );
+}

package/src/react/components/SwatchStyle.tsx

@@ -0,0 +1,50 @@
+/**
+ * Port of snippets/swatch-style.liquid — resolves the fill for a color
+ * swatch. The Liquid snippet emits a `--swatch: …` inline style
+ * declaration (not a stylesheet), so the mirror is a helper returning
+ * a React style object — or undefined when the value can't be
+ * resolved, in which case the .swatch CSS paints a neutral chip.
+ *
+ * Resolution order:
+ * 1. The value's native swatch (admin-managed taxonomy colors)
+ * 2. The value's own name read as a CSS color keyword
+ *    ("Light Blue" -> lightblue)
+ *
+ * The Liquid snippet's step 2 (the "swatch_color" metaobject matched
+ * by label) needs shop.metaobjects, which isn't part of the card
+ * data — intentionally skipped in the mirror.
+ */
+import type {CSSProperties} from 'react';
+import type {CardSwatch} from '../../commerce/index.ts';
+import {imageUrl} from '../engine/images';
+
+// Only vetted CSS keywords may pass through — an arbitrary name would
+// invalidate the whole background declaration
+const CSS_COLORS = new Set(
+  'aliceblue,antiquewhite,aqua,aquamarine,azure,beige,bisque,black,blanchedalmond,blue,blueviolet,brown,burlywood,cadetblue,chartreuse,chocolate,coral,cornflowerblue,cornsilk,crimson,cyan,darkblue,darkcyan,darkgoldenrod,darkgray,darkgreen,darkgrey,darkkhaki,darkmagenta,darkolivegreen,darkorange,darkorchid,darkred,darksalmon,darkseagreen,darkslateblue,darkslategray,darkslategrey,darkturquoise,darkviolet,deeppink,deepskyblue,dimgray,dimgrey,dodgerblue,firebrick,floralwhite,forestgreen,fuchsia,gainsboro,ghostwhite,gold,goldenrod,gray,green,greenyellow,grey,honeydew,hotpink,indianred,indigo,ivory,khaki,lavender,lavenderblush,lawngreen,lemonchiffon,lightblue,lightcoral,lightcyan,lightgoldenrodyellow,lightgray,lightgreen,lightgrey,lightpink,lightsalmon,lightseagreen,lightskyblue,lightslategray,lightslategrey,lightsteelblue,lightyellow,lime,limegreen,linen,magenta,maroon,mediumaquamarine,mediumblue,mediumorchid,mediumpurple,mediumseagreen,mediumslateblue,mediumspringgreen,mediumturquoise,mediumvioletred,midnightblue,mintcream,mistyrose,moccasin,navajowhite,navy,oldlace,olive,olivedrab,orange,orangered,orchid,palegoldenrod,palegreen,paleturquoise,palevioletred,papayawhip,peachpuff,peru,pink,plum,powderblue,purple,rebeccapurple,red,rosybrown,royalblue,saddlebrown,salmon,sandybrown,seagreen,seashell,sienna,silver,skyblue,slateblue,slategray,slategrey,snow,springgreen,steelblue,tan,teal,thistle,tomato,turquoise,violet,wheat,white,whitesmoke,yellow,yellowgreen'.split(
+    ',',
+  ),
+);
+
+/**
+ * `style={swatchStyle(value.name, value.swatch)}` ≙
+ * `style='{% render 'swatch-style', swatch: value.swatch, name: value.name %}'`
+ */
+export function swatchStyle(
+  name: string,
+  swatch?: CardSwatch | null,
+): CSSProperties | undefined {
+  const imageSrc = swatch?.image?.previewImage?.url;
+  if (imageSrc) {
+    return {'--swatch': `url(${imageUrl(imageSrc, 100)})`} as CSSProperties;
+  }
+  if (swatch?.color) {
+    return {'--swatch': swatch.color} as CSSProperties;
+  }
+
+  const probe = name.toLowerCase().trim().replace(/ /g, '').replace(/-/g, '');
+  if (CSS_COLORS.has(probe)) {
+    return {'--swatch': probe} as CSSProperties;
+  }
+  return undefined;
+}