create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/src/components/commerce/ProductCard.tsx

@@ -0,0 +1,117 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import { useState } from 'react'
+import type { Product } from '@tanqory/theme-kit'
+import { Badge, pickBadge } from '../base/Badge'
+import { IconButton } from '../base/IconButton'
+import { Icon } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import { Price } from './Price'
+import { discountPercent, hasOptions, hasPriceRange } from './money'
+import { isColorOption, swatchColor } from './swatch'
+import './ProductCard.css'
+
+/**
+ * 12C · 00 the ONE product card every product row uses — image-first, no
+ * container, title then price.
+ *
+ *   media     the global product ratio (1:1 default) or the row's; radius 8;
+ *             a second image on hover (desktop pointers only)
+ *   badge     top-start, one max: sale −% · New · Sold out · a merchant badge
+ *   vendor    optional, 12 muted · title 14 / 500, two-line clamp (the link
+ *             keeps the full title) · price (From for ranges)
+ *   swatches  up to 4 colour dots + "+n" (colours inferred from names)
+ *   quick add product-grid only: adds a single-variant product, opens the
+ *             variant sheet otherwise (the owner decides — onQuickAdd)
+ * Rating stars are not shown anywhere until reviews data exists.
+ */
+export type CardRatio = 'square' | 'portrait' | 'landscape' | 'adapt'
+
+export interface ProductCardProps {
+  product: Product
+  /** Absent = the global product media ratio (--ratio-product). */
+  ratio?: CardRatio
+  showVendor?: boolean
+  showSwatches?: boolean
+  /** Recently viewed: 1:1, one-line title, price only. */
+  compact?: boolean
+  /** Above the fold: load the image eagerly. */
+  priority?: boolean
+  /** The title element; the row decides the outline (h3 under a section h2). */
+  titleAs?: 'h2' | 'h3' | 'h4' | 'p'
+  /** Presence turns quick add on. */
+  onQuickAdd?: (product: Product) => void
+}
+
+export function ProductCard({ product: p, ratio, showVendor, showSwatches = true, compact, priority, titleAs: T = 'h3', onQuickAdd }: ProductCardProps): JSX.Element {
+  const { strings } = useNova()
+  const [hover, setHover] = useState(false)
+  const image = p.featuredImage ?? p.images[0] ?? null
+  const second = p.images.find((i) => i !== image && i.src !== image?.src) ?? null
+  const price = p.priceRange.min
+  const compareAt = p.compareAtPriceRange?.min ?? null
+  const soldOut = !p.available
+  const percent = discountPercent(price, compareAt)
+  const tone = compact ? null : pickBadge({ soldOut, sale: percent != null, custom: p.badge, isNew: p.tags?.includes('new') })
+  const badgeText = tone === 'sale' ? fmt(strings.discountBadge, { percent: percent! }) : tone === 'sold-out' ? strings.soldOut : tone === 'new' ? strings.newBadge : tone === 'custom' ? p.badge : null
+  const colours = !compact && showSwatches ? (p.options.find(isColorOption)?.values ?? []) : []
+  const aspect = ratio === 'adapt' && image ? `${image.width} / ${image.height}` : undefined
+
+  return (
+    <div className="nv-card" data-compact={compact ? '' : undefined} data-ratio={compact ? 'square' : ratio} data-sold-out={soldOut ? '' : undefined} onPointerEnter={(e) => e.pointerType === 'mouse' && setHover(true)} onPointerLeave={() => setHover(false)}>
+      <div className={sxJoin("nv-card__media", sx(aspect ? { aspectRatio: aspect } : undefined))}>
+        {image ? (
+          <>
+            <img className="nv-card__img" src={image.src} srcSet={image.srcSet} sizes="(min-width: 1024px) 25vw, 50vw" alt="" width={image.width} height={image.height} loading={priority ? 'eager' : 'lazy'} decoding="async" />
+            {second && !compact && <img className="nv-card__img nv-card__img--alt" data-shown={hover ? '' : undefined} src={second.src} alt="" width={second.width} height={second.height} loading="lazy" decoding="async" />}
+          </>
+        ) : (
+          <span className="nv-card__missing">
+            <Icon name="image" size="md" />
+            <span>{strings.noImage}</span>
+          </span>
+        )}
+        {badgeText && (
+          <span className="nv-card__badge">
+            <Badge tone={tone!}>{badgeText}</Badge>
+          </span>
+        )}
+        {onQuickAdd && !soldOut && (
+          <IconButton
+            className="nv-card__quick"
+            variant="on-media"
+            icon="plus"
+            label={fmt(hasOptions(p) ? strings.chooseOptions : strings.quickAdd, { title: p.title })}
+            onClick={() => onQuickAdd(p)}
+          />
+        )}
+      </div>
+      <div className="nv-card__info">
+        {showVendor && p.vendor && !compact && <p className="nv-card__vendor"><bdi>{p.vendor}</bdi></p>}
+        <T className="nv-card__title">
+          <a href={p.url} className="nv-card__link">
+            <bdi>{p.title}</bdi>
+          </a>
+        </T>
+        <Price price={price} compareAt={compareAt} from={hasPriceRange(p)} soldOut={soldOut} />
+        {colours.length > 1 && (
+          <p className="nv-card__swatches">
+            {colours.slice(0, 4).map((c) => (
+              <span key={c} className={sxJoin("nv-card__dot", sx({ background: swatchColor(c) ?? undefined }))} title={c} aria-hidden />
+            ))}
+            <span className="nv-card__swatch-label">
+              {colours.length > 4 ? (
+                <>
+                  <span aria-hidden>+{colours.length - 4}</span>
+                  <span className="nv-visually-hidden">{fmt(strings.colourCount, { count: colours.length })}</span>
+                </>
+              ) : (
+                fmt(strings.colourCount, { count: colours.length })
+              )}
+            </span>
+          </p>
+        )}
+      </div>
+    </div>
+  )
+}

package/templates/nova/src/components/commerce/ProductGallery.css

@@ -0,0 +1,72 @@
+/* 12C · product gallery. */
+.nv-gallery { --nv-gallery-ratio: 4 / 5; display: grid; gap: var(--space-3); min-width: 0; }
+.nv-gallery[data-ratio='square'] { --nv-gallery-ratio: 1; }
+.nv-gallery[data-layout='thumbnails-left'] { grid-template-columns: var(--pdp-thumb) minmax(0, 1fr); gap: var(--space-4); align-items: start; }
+.nv-gallery[data-layout='thumbnails-left'][data-single] { grid-template-columns: minmax(0, 1fr); }
+.nv-gallery[data-layout='thumbnails-below'] .nv-gallery__thumbs { order: 2; flex-direction: row; }
+.nv-gallery__thumbs { display: flex; flex-direction: column; gap: var(--space-2); min-width: 0; }
+.nv-gallery__thumb {
+  flex: none;
+  width: var(--pdp-thumb);
+  aspect-ratio: var(--nv-gallery-ratio);
+  padding: 0;
+  border-radius: var(--radius-sm);
+  overflow: hidden;
+  background: var(--color-media-bg);
+  box-shadow: inset 0 0 0 var(--border-width) transparent;
+  cursor: pointer;
+}
+.nv-gallery__thumb img { width: 100%; height: 100%; object-fit: cover; }
+.nv-gallery__thumb[aria-current='true'] { outline: 1.5px solid var(--color-fg); outline-offset: 2px; }
+.nv-gallery__stage { position: relative; min-width: 0; }
+.nv-gallery__strip { display: grid; }
+.nv-gallery__slide { position: relative; grid-area: 1 / 1; margin: 0; aspect-ratio: var(--nv-gallery-ratio); border-radius: var(--radius-media); overflow: hidden; background: var(--color-media-bg); visibility: hidden; }
+.nv-gallery__slide[data-active] { visibility: visible; }
+.nv-gallery__slide img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+.nv-gallery__zoom.nv-icon-btn { position: absolute; inset-block-end: var(--space-4); inset-inline-end: var(--space-4); }
+.nv-gallery__badge { position: absolute; z-index: var(--z-raised); inset-block-start: var(--space-4); inset-inline-start: var(--space-4); }
+.nv-gallery__counter { display: none; }
+.nv-gallery__empty {
+  display: grid;
+  place-items: center;
+  aspect-ratio: var(--nv-gallery-ratio);
+  padding: var(--space-6);
+  border-radius: var(--radius-media);
+  background: var(--color-bg-muted);
+  color: var(--color-fg-muted);
+  font-weight: var(--weight-medium);
+  text-align: center;
+}
+
+/* stacked: 1 large + a 2-up grid, all visible. */
+.nv-gallery[data-layout='stacked'] .nv-gallery__strip { grid-template-columns: 1fr 1fr; gap: var(--space-3); }
+.nv-gallery[data-layout='stacked'] .nv-gallery__slide { grid-area: auto; visibility: visible; }
+.nv-gallery[data-layout='stacked'] .nv-gallery__slide:first-child { grid-column: 1 / -1; }
+
+/* < 1024: every layout is a swipe strip with a counter; no thumbnails. */
+@media (max-width: 1023.98px) {
+  .nv-gallery, .nv-gallery[data-layout] { grid-template-columns: minmax(0, 1fr); }
+  .nv-gallery__thumbs { display: none; }
+  .nv-gallery .nv-gallery__strip, .nv-gallery[data-layout='stacked'] .nv-gallery__strip {
+    display: flex;
+    gap: 0;
+    overflow-x: auto;
+    scroll-snap-type: x mandatory;
+    scrollbar-width: none;
+    border-radius: var(--radius-media);
+  }
+  .nv-gallery__strip::-webkit-scrollbar { display: none; }
+  .nv-gallery .nv-gallery__slide { flex: 0 0 100%; visibility: visible; scroll-snap-align: start; border-radius: 0; }
+  .nv-gallery__counter {
+    display: block;
+    position: absolute;
+    inset-block-end: var(--space-3);
+    inset-inline-end: var(--space-3);
+    padding: var(--space-1) var(--space-2);
+    border-radius: var(--radius-pill);
+    background: var(--color-bg);
+    font-size: var(--type-label);
+    font-weight: var(--weight-medium);
+  }
+  .nv-gallery__zoom.nv-icon-btn { display: none; }
+}

package/templates/nova/src/components/commerce/ProductGallery.tsx

@@ -0,0 +1,98 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import { useEffect, useRef, type CSSProperties, type ReactNode } from 'react'
+import { useScrollRegion } from '../../styles/scroll'
+import type { NovaImage } from '@tanqory/theme-kit'
+import { IconButton } from '../base/IconButton'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import './ProductGallery.css'
+
+/**
+ * 12C · product-details gallery.
+ *
+ *   thumbnails-left   a 64 thumbnail column beside the main image (default)
+ *   thumbnails-below  a thumbnail row under it (best for 2–5 images)
+ *   stacked           1 large + a 2-up grid, scrolling beside the sticky buy box
+ *   < 1024 every layout is a swipe strip with a "1 / 6" counter
+ *   one image → no thumbnails, counter or dots · none → a neutral tile with
+ *   the product name, no zoom (the editor asks for images)
+ * Zoom opens the owner's lightbox (onZoom). Controlled: the owner keeps index.
+ */
+export interface ProductGalleryProps {
+  images: NovaImage[]
+  /** The product name, for the no-image tile and image labels. */
+  title: string
+  layout?: 'thumbnails-left' | 'thumbnails-below' | 'stacked'
+  ratio?: 'adapt' | 'portrait' | 'square'
+  index: number
+  onIndex: (index: number) => void
+  /** Presence turns zoom on. */
+  onZoom?: (index: number) => void
+  /** Overlay top-start (the sale badge). */
+  badge?: ReactNode
+}
+
+export function ProductGallery({ images, title, layout = 'thumbnails-left', ratio = 'portrait', index, onIndex, onZoom, badge }: ProductGalleryProps): JSX.Element {
+  const { strings } = useNova()
+  const strip = useRef<HTMLDivElement>(null)
+  const count = images.length
+  // The swipe strip (< 1024) is a keyboard-scrollable region only while it scrolls.
+  const region = useScrollRegion(strip, strings.productImages, [count])
+  const aspect = ratio === 'adapt' && images[0] ? `${images[0].width} / ${images[0].height}` : undefined
+
+  // Keep the swipe strip on the chosen image (thumbnail click, variant change).
+  useEffect(() => {
+    const el = strip.current
+    const slide = el?.children[index] as HTMLElement | undefined
+    if (el && slide && Math.abs(el.scrollLeft - slide.offsetLeft) > 2 && getComputedStyle(el).overflowX !== 'visible') el.scrollTo({ left: slide.offsetLeft, behavior: 'smooth' })
+  }, [index])
+
+  if (!count) {
+    return (
+      <div className="nv-gallery" data-layout="empty" data-ratio={ratio}>
+        <div className="nv-gallery__empty">
+          <span><bdi>{title}</bdi></span>
+        </div>
+      </div>
+    )
+  }
+
+  const onScroll = () => {
+    const el = strip.current
+    if (!el || getComputedStyle(el).overflowX === 'visible') return
+    const i = Math.round(Math.abs(el.scrollLeft) / el.clientWidth)
+    if (i !== index && i < count) onIndex(i)
+  }
+
+  return (
+    <div className={sxJoin("nv-gallery", sx(aspect ? ({ '--nv-gallery-ratio': aspect } as CSSProperties) : undefined))} data-layout={layout} data-ratio={ratio} data-single={count === 1 ? '' : undefined}>
+      {count > 1 && layout !== 'stacked' && (
+        <div className="nv-gallery__thumbs" role="group" aria-label={strings.productImages}>
+          {images.map((img, i) => (
+            <button key={img.src + i} type="button" className="nv-gallery__thumb" aria-current={i === index ? 'true' : undefined} aria-label={fmt(strings.imageOf, { index: i + 1, count })} onClick={() => onIndex(i)}>
+              <img src={img.src} alt="" width={img.width} height={img.height} loading="lazy" decoding="async" />
+            </button>
+          ))}
+        </div>
+      )}
+      <div className="nv-gallery__stage">
+        {badge && <span className="nv-gallery__badge">{badge}</span>}
+        <div ref={strip} className="nv-gallery__strip" onScroll={onScroll} {...region}>
+          {images.map((img, i) => (
+            <figure key={img.src + i} className="nv-gallery__slide" data-active={i === index ? '' : undefined} aria-hidden={layout !== 'stacked' && i !== index ? true : undefined}>
+              <img src={img.src} srcSet={img.srcSet} sizes="(min-width: 1024px) 50vw, 100vw" alt={img.alt ?? ''} width={img.width} height={img.height} loading={i === 0 ? 'eager' : 'lazy'} decoding="async" />
+              {onZoom && (layout === 'stacked' || i === index) && (
+                <IconButton className="nv-gallery__zoom" variant="on-media" icon="zoom" label={strings.zoomImage} onClick={() => onZoom(i)} />
+              )}
+            </figure>
+          ))}
+        </div>
+        {count > 1 && (
+          <span className="nv-gallery__counter nv-tabular" aria-hidden>
+            {index + 1} / {count}
+          </span>
+        )}
+      </div>
+    </div>
+  )
+}

package/templates/nova/src/components/commerce/QuantitySelector.css

@@ -0,0 +1,23 @@
+.nv-qty {
+  display: inline-flex;
+  align-items: center;
+  min-height: var(--btn-height-lg);
+  padding-inline: var(--space-1);
+  border-radius: var(--btn-radius);
+  box-shadow: inset 0 0 0 var(--border-width) var(--color-border-input);
+}
+.nv-qty__input {
+  /* The number is its own 44×44 target: as tall as the stepper, at least 44 wide (WCAG 2.5.5). */
+  align-self: stretch;
+  width: 2.5ch;
+  min-width: 44px;
+  border: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-size: var(--type-body);
+  text-align: center;
+  -moz-appearance: textfield;
+}
+.nv-qty__input::-webkit-inner-spin-button, .nv-qty__input::-webkit-outer-spin-button { -webkit-appearance: none; margin: 0; }
+@media (max-width: 639.98px) { .nv-qty { min-height: var(--space-7); } }

package/templates/nova/src/components/commerce/QuantitySelector.tsx

@@ -0,0 +1,45 @@
+import { IconButton } from '../base/IconButton'
+import { useNova } from '../../styles/NovaProvider'
+import './QuantitySelector.css'
+
+/**
+ * 12C · quantity stepper — 52 tall beside the add button (48 at 390); − and +
+ * are 44 targets; the number is a real input (type a quantity). Controlled.
+ */
+export interface QuantitySelectorProps {
+  value: number
+  onChange: (value: number) => void
+  min?: number
+  /** Stock limit, when known. */
+  max?: number
+  disabled?: boolean
+  id?: string
+  /** Group name — per line in a cart ("Quantity of Mug"); defaults to "Quantity". */
+  label?: string
+}
+
+export function QuantitySelector({ value, onChange, min = 1, max, disabled, id, label }: QuantitySelectorProps): JSX.Element {
+  const { strings } = useNova()
+  const clamp = (n: number) => Math.max(min, max ? Math.min(max, n) : n)
+  return (
+    <div className="nv-qty" role="group" aria-label={label ?? strings.quantity} data-disabled={disabled ? '' : undefined}>
+      <IconButton icon="minus" label={strings.decreaseQuantity} disabled={disabled || value <= min} onClick={() => onChange(clamp(value - 1))} />
+      <input
+        id={id}
+        className="nv-qty__input nv-tabular"
+        type="number"
+        inputMode="numeric"
+        min={min}
+        max={max}
+        value={value}
+        disabled={disabled}
+        aria-label={strings.quantity}
+        onChange={(e) => {
+          const n = Number.parseInt(e.target.value, 10)
+          if (Number.isFinite(n)) onChange(clamp(n))
+        }}
+      />
+      <IconButton icon="plus" label={strings.increaseQuantity} disabled={disabled || (max != null && value >= max)} onClick={() => onChange(clamp(value + 1))} />
+    </div>
+  )
+}

package/templates/nova/src/components/commerce/Reviews.css

@@ -0,0 +1,34 @@
+/* 12F · product reviews. Summary 56 / 1 score; bars 4px ink on muted; review rows hairline-separated. */
+.nv-rating-summary { display: grid; gap: var(--space-3); }
+.nv-rating-summary__score { display: flex; align-items: baseline; flex-wrap: wrap; gap: var(--space-2); margin: 0; }
+.nv-rating-summary__value { font-size: 3.5rem; line-height: 1; letter-spacing: var(--tracking-display); font-weight: var(--weight-heading); }
+.nv-rating-summary__of { font-size: var(--type-body-sm); color: var(--color-fg-muted); }
+
+.nv-rating-bars { display: grid; gap: 2px; }
+.nv-rating-bars__row { display: grid; grid-template-columns: 2.25rem minmax(0, 1fr) 3rem; align-items: center; gap: var(--space-3); width: 100%; min-height: 32px; padding: 0; border: 0; border-radius: var(--radius-sm); background: none; color: var(--color-fg); font: inherit; font-size: var(--type-body-sm); text-align: start; cursor: pointer; }
+.nv-rating-bars__row:disabled { cursor: default; }
+.nv-rating-bars__row:focus-visible { outline: var(--focus-ring-width) solid var(--color-focus); outline-offset: 2px; }
+.nv-rating-bars__track { height: 4px; border-radius: 2px; background: var(--color-bg-muted); overflow: hidden; }
+.nv-rating-bars__track span { display: block; height: 100%; min-width: 2px; background: var(--color-fg); }
+.nv-rating-bars__count { text-align: end; color: var(--color-fg-muted); }
+.nv-rating-bars__row[aria-pressed='true'] .nv-rating-bars__stars { font-weight: var(--weight-medium); text-decoration: underline; text-underline-offset: var(--underline-offset); }
+.nv-rating-bars__row:hover:not(:disabled) .nv-rating-bars__track { background: var(--color-bg-muted-hover); }
+
+.nv-review { display: grid; gap: var(--space-3); padding-block: var(--space-5); border-block-end: 1px solid var(--color-border); }
+.nv-review__top { display: flex; align-items: center; justify-content: space-between; gap: var(--space-3); }
+.nv-review__date { font-size: var(--type-body-sm); color: var(--color-fg-muted); }
+.nv-review__title { font-size: 1rem; line-height: 1.35; font-weight: var(--weight-medium); letter-spacing: 0; }
+.nv-review__body { max-width: 68ch; font-size: 0.9375rem; line-height: 1.65; }
+.nv-review__photos { display: flex; flex-wrap: wrap; gap: var(--space-2); }
+.nv-review__photo { display: block; width: 72px; height: 72px; padding: 0; border: 0; border-radius: var(--radius-sm); overflow: hidden; background: var(--color-media-bg); cursor: zoom-in; }
+.nv-review__photo img { width: 100%; height: 100%; object-fit: cover; }
+.nv-review__photo:focus-visible { outline: var(--focus-ring-width) solid var(--color-focus); outline-offset: 2px; }
+.nv-review__meta { font-size: var(--type-body-sm); color: var(--color-fg-muted); }
+.nv-review__author { font-weight: var(--weight-medium); color: var(--color-fg); }
+.nv-review__verified { color: var(--color-success); }
+.nv-review__verified-short, .nv-review__meta-date { display: none; }
+@media (max-width: 639.98px) {
+  .nv-review__date, .nv-review__verified-long, .nv-review__variant { display: none; }
+  .nv-review__verified-short, .nv-review__meta-date { display: inline; }
+  .nv-review__body { font-size: 0.875rem; }
+}

package/templates/nova/src/components/commerce/Reviews.tsx

@@ -0,0 +1,112 @@
+import { sx } from '@tanqory/theme-kit'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import type { NovaImage, Review } from '@tanqory/theme-kit'
+import { Stars } from './Stars'
+import { formatDate } from '../content/ArticleCard'
+import './Reviews.css'
+
+/**
+ * 12F · product reviews, the pieces a reviews source feeds (DATA REQUIREMENT).
+ * Real data only: no placeholder stars, no "0 reviews" before a source exists.
+ */
+
+export function RatingSummary({ average, count }: { average: number; count: number }): JSX.Element {
+  const { strings, locale } = useNova()
+  const avg = new Intl.NumberFormat(locale, { minimumFractionDigits: 1, maximumFractionDigits: 1 }).format(average)
+  return (
+    <div className="nv-rating-summary">
+      <p className="nv-rating-summary__score">
+        <span className="nv-rating-summary__value nv-tabular">{avg}</span>
+        <span className="nv-rating-summary__of">
+          {strings.outOfFive} · {fmt(strings.reviewsCount, { count: new Intl.NumberFormat(locale).format(count) })}
+        </span>
+      </p>
+      <Stars value={average} size="lg" />
+    </div>
+  )
+}
+
+export interface RatingBreakdownProps {
+  /** Counts for 5 · 4 · 3 · 2 · 1 stars. */
+  distribution: readonly number[]
+  /** The star filter in force (null = all). */
+  active?: number | null
+  onSelect?: (stars: number | null) => void
+}
+
+/** Distribution bars are buttons that filter the list (12F rules); pressing the active bar clears it. */
+export function RatingBreakdown({ distribution, active = null, onSelect }: RatingBreakdownProps): JSX.Element {
+  const { strings, locale } = useNova()
+  const total = distribution.reduce((a, b) => a + b, 0) || 1
+  const nf = new Intl.NumberFormat(locale)
+  return (
+    <ul className="nv-rating-bars" aria-label={strings.filterReviews}>
+      {distribution.map((n, i) => {
+        const stars = 5 - i
+        return (
+          <li key={stars}>
+            <button
+              type="button"
+              className="nv-rating-bars__row"
+              aria-pressed={active === stars}
+              aria-label={fmt(strings.starsFilter, { n: stars, count: nf.format(n) })}
+              disabled={n === 0}
+              onClick={() => onSelect?.(active === stars ? null : stars)}
+            >
+              <span className="nv-rating-bars__stars nv-tabular" aria-hidden>{fmt(strings.starsShort, { n: stars })}</span>
+              <span className="nv-rating-bars__track" aria-hidden>
+                <span className={sx({ width: `${(n / total) * 100}%` })} />
+              </span>
+              <span className="nv-rating-bars__count nv-tabular" aria-hidden>{nf.format(n)}</span>
+            </button>
+          </li>
+        )
+      })}
+    </ul>
+  )
+}
+
+export interface ReviewItemProps {
+  review: Review
+  showPhotos?: boolean
+  onOpenPhoto?: (photos: NovaImage[], index: number) => void
+}
+
+export function ReviewItem({ review: r, showPhotos = true, onOpenPhoto }: ReviewItemProps): JSX.Element {
+  const { strings, locale } = useNova()
+  const date = formatDate(r.createdAt, locale)
+  const photos = showPhotos ? (r.photos ?? []) : []
+  return (
+    <article className="nv-review">
+      <div className="nv-review__top">
+        <Stars value={r.rating} />
+        <time className="nv-review__date" dateTime={r.createdAt}>{date}</time>
+      </div>
+      {r.title && <h3 className="nv-review__title"><bdi>{r.title}</bdi></h3>}
+      <p className="nv-review__body"><bdi>{r.body}</bdi></p>
+      {photos.length > 0 && (
+        <ul className="nv-review__photos" aria-label={fmt(strings.reviewPhotos, { name: r.author })}>
+          {photos.map((p, i) => (
+            <li key={i}>
+              <button type="button" className="nv-review__photo" onClick={() => onOpenPhoto?.(photos, i)} aria-label={p.alt || fmt(strings.imageOf, { index: i + 1, count: photos.length })}>
+                <img src={p.src} alt="" width={p.width} height={p.height} loading="lazy" decoding="async" />
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+      <p className="nv-review__meta">
+        <span className="nv-review__author"><bdi>{r.author}</bdi></span>
+        {r.verified && (
+          <span className="nv-review__verified">
+            {' · '}✓ <span className="nv-review__verified-long">{strings.verifiedBuyer}</span>
+            <span className="nv-review__verified-short">{strings.verified}</span>
+          </span>
+        )}
+        {r.variant && <span className="nv-review__variant"> · {r.variant}</span>}
+        <span className="nv-review__meta-date"> · {date}</span>
+      </p>
+    </article>
+  )
+}

package/templates/nova/src/components/commerce/Stars.css

@@ -0,0 +1,7 @@
+.nv-stars { display: inline-flex; align-items: center; gap: var(--space-2); color: var(--color-fg); }
+.nv-stars__row { display: inline-flex; gap: 2px; }
+.nv-stars svg { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linejoin: round; }
+.nv-stars svg[data-filled] { fill: currentColor; }
+.nv-stars[data-size='sm'] svg { width: 13px; height: 13px; }
+.nv-stars[data-size='lg'] svg { width: 20px; height: 20px; }
+.nv-stars__label { font-size: var(--type-caption); color: var(--color-fg-muted); }

package/templates/nova/src/components/commerce/Stars.tsx

@@ -0,0 +1,38 @@
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import './Stars.css'
+
+export interface StarsProps {
+  /** 0–5. Whole stars fill (4.8 → five); the exact number is in the label. */
+  value: number
+  size?: 'sm' | 'md' | 'lg'
+  /** Show "4.8 out of 5" beside the stars instead of only to screen readers. */
+  showLabel?: boolean
+  className?: string
+}
+
+const STAR = 'M12 3.5 14.6 9l6 .6-4.5 4 1.4 5.9L12 16.4 6.5 19.5 7.9 13.6 3.4 9.6l6-.6z'
+
+/**
+ * Stars always paired with the number ("4.8 out of 5") — never shape alone
+ * (12F rules). Ink outline / fill, 16 px by default. Rendering 0 is the
+ * caller's decision: a 0 rating hides the stars, it is not "no stars".
+ */
+export function Stars({ value, size = 'md', showLabel, className }: StarsProps): JSX.Element {
+  const { strings, locale } = useNova()
+  const v = Math.max(0, Math.min(5, value))
+  const filled = Math.round(v)
+  const label = fmt(strings.ratingOutOf, { value: new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(v), max: 5 })
+  return (
+    <span className={['nv-stars', className].filter(Boolean).join(' ')} data-size={size}>
+      <span className="nv-stars__row" aria-hidden>
+        {[0, 1, 2, 3, 4].map((i) => (
+          <svg key={i} viewBox="0 0 24 24" data-filled={i < filled ? '' : undefined}>
+            <path d={STAR} />
+          </svg>
+        ))}
+      </span>
+      <span className={showLabel ? 'nv-stars__label' : 'nv-visually-hidden'}>{label}</span>
+    </span>
+  )
+}

package/templates/nova/src/components/commerce/VariantPicker.css

@@ -0,0 +1,31 @@
+/* 12C · option picker — each option its own row. */
+.nv-variants { display: grid; gap: var(--space-5); }
+.nv-variants__option { display: grid; gap: var(--space-3); min-width: 0; margin: 0; padding: 0; border: 0; }
+.nv-variants__legend { padding: 0; font-size: var(--type-body-sm); font-weight: var(--weight-medium); width: 100%; }
+.nv-variants__legend-row { display: flex; justify-content: space-between; align-items: baseline; gap: var(--space-3); }
+.nv-variants__current { color: var(--color-fg-muted); font-weight: var(--weight-body); }
+.nv-variants__values { display: flex; flex-wrap: wrap; gap: var(--space-2); }
+.nv-variants__value { position: relative; display: inline-grid; place-items: center; cursor: pointer; }
+.nv-variants__input { position: absolute; inset: 0; margin: 0; opacity: 0; cursor: pointer; }
+
+/* buttons — 44 tall, equal widths that share the row (4 sizes fit at 390), ink ring when chosen. */
+[data-kind='buttons'] .nv-variants__values { display: grid; grid-template-columns: repeat(auto-fill, minmax(4.25rem, 1fr)); }
+[data-kind='buttons'] .nv-variants__value {
+  min-height: var(--touch-target);
+  padding-inline: var(--space-2);
+  border-radius: var(--btn-radius);
+  box-shadow: inset 0 0 0 var(--border-width) var(--color-border-input);
+  font-size: var(--type-body);
+}
+[data-kind='buttons'] .nv-variants__value:has(:checked) { box-shadow: inset 0 0 0 1.5px var(--color-fg); }
+[data-kind='buttons'] .nv-variants__value[data-unavailable] { color: var(--color-fg-subtle); box-shadow: inset 0 0 0 var(--border-width) var(--color-border); background: linear-gradient(to top right, transparent calc(50% - 0.5px), var(--color-border) 50%, transparent calc(50% + 0.5px)); }
+[data-kind='buttons'] .nv-variants__value[data-unavailable]:has(:checked) { box-shadow: inset 0 0 0 1.5px var(--color-fg-muted); }
+
+/* swatches — a 32 dot in a 44 target, ring when chosen. */
+[data-kind='swatches'] .nv-variants__value { width: var(--touch-target); height: var(--touch-target); border-radius: var(--radius-circle); }
+.nv-variants__dot { width: var(--swatch-size); height: var(--swatch-size); border-radius: var(--radius-circle); background: var(--color-bg-muted); box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-fg) 12%, transparent); }
+[data-kind='swatches'] .nv-variants__value:has(:checked) { box-shadow: 0 0 0 1.5px var(--color-fg); }
+[data-kind='swatches'] .nv-variants__value[data-unavailable] .nv-variants__dot { opacity: 0.45; }
+[data-kind='swatches'] .nv-variants__value[data-unavailable]::after { content: ''; position: absolute; width: var(--swatch-size); height: 1.5px; background: var(--color-fg-muted); transform: rotate(-45deg); }
+
+.nv-variants__value:has(:focus-visible) { outline: var(--focus-ring-width) solid var(--color-focus); outline-offset: var(--focus-ring-offset); }