create-tanqory-theme 0.0.0-stage → 0.2.3

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

@@ -0,0 +1,120 @@
+import { useEffect, useRef, useState } from 'react'
+import type { Money, PaymentMethod } from '@tanqory/theme-kit'
+import { Button } from '../base/Button'
+import { Icon } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import { EarnHint } from './EarnHint'
+import { PaymentMark } from './PaymentMark'
+import { formatMoney } from './money'
+import './CartSummary.css'
+
+export interface CartSummaryProps {
+  subtotal: Money
+  /** Compare-at savings across the lines; null or 0 hides the row. */
+  savings?: Money | null
+  /** Merchant copy under the total ("Taxes included. Discount codes at checkout."). */
+  note?: string
+  /** The store's prices include tax (Settings › Taxes): the platform-driven line under the total. */
+  taxNote?: string
+  checkoutLabel: string
+  /** The checkout app. Checkout never goes anywhere else (12G conflict 1). */
+  checkoutUrl: string
+  /** Checkout failed to start: an inline error above the button. */
+  checkoutError?: boolean
+  paymentMethods?: readonly PaymentMethod[]
+  /** Trust lines under the button ("✓ 30-day returns"). */
+  badges?: readonly { label: string; link?: string }[]
+  /** At 390 pin total + Checkout to the bottom while the summary's own button is still below the fold. */
+  pinOnPhone?: boolean
+}
+
+const PHONE = '(max-width: 639.98px)'
+
+/**
+ * 12G · the cart summary: subtotal, "You save", shipping at checkout,
+ * estimated total, the merchant's note, the one primary action, payment
+ * chips (as in the footer) and trust lines. No free-shipping bar — there is
+ * no threshold data (Nova 10 · D8).
+ */
+export function CartSummary({ subtotal, savings, note, taxNote, checkoutLabel, checkoutUrl, checkoutError, paymentMethods = [], badges = [], pinOnPhone }: CartSummaryProps): JSX.Element {
+  const { strings, locale } = useNova()
+  const action = useRef<HTMLDivElement>(null)
+  const [pinned, setPinned] = useState(false)
+  useEffect(() => {
+    const el = action.current
+    if (!pinOnPhone || !el || typeof IntersectionObserver === 'undefined' || !window.matchMedia?.(PHONE).matches) return
+    // Below the fold → pin; once it scrolls into view (or above) → the summary's own button is enough.
+    const io = new IntersectionObserver(([e]) => setPinned(!e.isIntersecting && e.boundingClientRect.top > 0))
+    io.observe(el)
+    return () => io.disconnect()
+  }, [pinOnPhone])
+  return (
+    <div className="nv-cart-summary">
+      <h2 className="nv-cart-summary__title">{strings.summary}</h2>
+      <dl className="nv-cart-summary__rows nv-tabular">
+        <div>
+          <dt>{strings.subtotal}</dt>
+          <dd>{formatMoney(subtotal, locale)}</dd>
+        </div>
+        {savings && savings.amount > 0 && (
+          <div data-kind="save">
+            <dt>{strings.youSave}</dt>
+            <dd>{formatMoney(savings, locale)}</dd>
+          </div>
+        )}
+        <div>
+          <dt>{strings.shipping}</dt>
+          <dd>{strings.atCheckout}</dd>
+        </div>
+        <div data-kind="total">
+          <dt>{strings.estimatedTotal}</dt>
+          <dd>{formatMoney(subtotal, locale)}</dd>
+        </div>
+      </dl>
+      <EarnHint amount={subtotal} scope="order" />
+      {taxNote && <p className="nv-cart-summary__note" data-kind="tax">{taxNote}</p>}
+      {note?.trim() && <p className="nv-cart-summary__note">{note}</p>}
+      <div ref={action} className="nv-cart-summary__action">
+        {checkoutError && (
+          <p className="nv-cart-summary__error" role="alert">
+            <Icon name="alert" size="sm" />
+            {strings.checkoutFailed}
+          </p>
+        )}
+        <Button href={checkoutUrl} size="lg" block>
+          {checkoutLabel}
+        </Button>
+      </div>
+      {paymentMethods.length > 0 && (
+        <ul className="nv-cart-summary__pay" aria-label={strings.paymentMethods}>
+          {paymentMethods.map((m) => (
+            <li key={m}>
+              <PaymentMark method={m} />
+            </li>
+          ))}
+        </ul>
+      )}
+      {pinned && (
+        <div className="nv-cart-summary__pinned">
+          <span className="nv-cart-summary__pinned-total nv-tabular">
+            <span>{strings.estimatedTotal}</span>
+            <strong>{formatMoney(subtotal, locale)}</strong>
+          </span>
+          <Button href={checkoutUrl} size="lg">
+            {checkoutLabel}
+          </Button>
+        </div>
+      )}
+      {badges.length > 0 && (
+        <ul className="nv-cart-summary__badges">
+          {badges.map((b, i) => (
+            <li key={i}>
+              <Icon name="check" size="sm" />
+              {b.link ? <a href={b.link}><bdi>{b.label}</bdi></a> : <bdi>{b.label}</bdi>}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,66 @@
+/* 12C · collection tile. */
+.nv-collection-card { position: relative; display: flex; flex-direction: column; gap: var(--space-3); min-width: 0; height: 100%; color: var(--color-fg); }
+.nv-collection-card__media { position: relative; isolation: isolate; display: grid; flex: 1; aspect-ratio: 4 / 5; border-radius: var(--radius-media); overflow: hidden; background: var(--color-media-bg); }
+.nv-collection-card[data-ratio='square'] .nv-collection-card__media { aspect-ratio: 1; }
+.nv-collection-card[data-ratio='landscape'] .nv-collection-card__media { aspect-ratio: 4 / 3; }
+.nv-collection-card[data-lead] .nv-collection-card__media { aspect-ratio: auto; min-height: 100%; }
+.nv-collection-card__media img { position: absolute; z-index: -1; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+.nv-collection-card__name-tile {
+  position: absolute;
+  z-index: -1;
+  inset: 0;
+  display: grid;
+  place-items: center;
+  padding: var(--space-4);
+  background: var(--color-bg-muted);
+  color: var(--color-fg-muted);
+  font-size: var(--type-h4);
+  font-weight: var(--weight-medium);
+  text-align: center;
+}
+.nv-collection-card__title {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: var(--space-2);
+  font-size: var(--type-body);
+  font-weight: var(--weight-medium);
+  line-height: var(--leading-snug);
+  letter-spacing: 0;
+}
+.nv-collection-card__link { color: inherit; text-decoration: none; display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden; }
+.nv-collection-card__link::after { content: ''; position: absolute; inset: 0; border-radius: var(--radius-media); }
+.nv-collection-card__link:focus-visible { outline: none; }
+/* The hit area reaches a little past the tile — below it, and into the gap at its inline start — so a short title
+   at the tile's edge still has a 44×44 target (WCAG 2.5.5). Transparent; the focus ring stays on the tile (::after).
+   Never past the inline end: in a carousel that would widen the strip's scroll width (styles/scroll.ts). The 12px
+   below stays inside a strip of tiles through the padding below (cancelled by a margin: nothing moves). */
+.nv-collection-card__link::before { content: ''; position: absolute; inset-block: 0 calc(-1 * var(--space-3)); inset-inline: calc(-1 * var(--space-2)) 0; }
+.nv-row__list:has(.nv-collection-card) { padding-block-end: var(--space-3); margin-block-end: calc(-1 * var(--space-3)); }
+.nv-collection-card__link:focus-visible::after { outline: var(--focus-ring-width) solid var(--color-focus); outline-offset: var(--focus-ring-offset); }
+.nv-collection-card:hover .nv-collection-card__link { text-decoration: underline; text-underline-offset: var(--underline-offset); }
+.nv-collection-card__count { font-weight: var(--weight-body); color: var(--color-fg-muted); font-size: var(--type-body-sm); }
+.nv-collection-card__desc { font-size: var(--type-body-sm); color: var(--color-fg-muted); display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden; }
+
+/* overlay: a white label chip, bottom-start — no image overlay needed. */
+.nv-collection-card__chip {
+  /* In flow (not absolute), so the link's target covers the whole tile. */
+  align-self: end;
+  justify-self: start;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  max-width: calc(100% - 2 * var(--space-3));
+  margin: var(--space-3);
+  padding: var(--space-2) var(--space-3);
+  border-radius: var(--radius-sm);
+  background: var(--color-bg);
+  color: var(--color-fg);
+  font-size: var(--type-body-sm);
+  font-weight: var(--weight-medium);
+  letter-spacing: 0;
+  line-height: var(--leading-tight);
+}
+.nv-collection-card__chip-text { max-width: 24ch; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+/* The chip is the link; its target still covers the whole tile. */
+.nv-collection-card__chip .nv-collection-card__link { display: block; -webkit-line-clamp: unset; }

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

@@ -0,0 +1,57 @@
+import type { Collection } from '@tanqory/theme-kit'
+import { Icon } from '../../styles/Icon'
+import './CollectionCard.css'
+
+/**
+ * 12C · collection tile (collection-list). Name + count under the image by
+ * default; `overlay` puts a white label chip on the image (readable on any
+ * image without an overlay; chips truncate at 24ch). A collection without an
+ * image uses its first product's image, else a neutral tile with the name.
+ */
+export interface CollectionCardProps {
+  collection: Collection
+  /** Blank = the collection title (collection-item block title). */
+  title?: string
+  ratio?: 'square' | 'portrait' | 'landscape'
+  textStyle?: 'below' | 'overlay'
+  showCount?: boolean
+  showDescription?: boolean
+  /** editorial lead tile (spans 2 × 2). */
+  lead?: boolean
+  priority?: boolean
+  titleAs?: 'h2' | 'h3' | 'h4' | 'p'
+}
+
+export function CollectionCard({ collection: c, title, ratio = 'portrait', textStyle = 'below', showCount = true, showDescription, lead, priority, titleAs: T = 'h3' }: CollectionCardProps): JSX.Element {
+  const name = title?.trim() || c.title
+  const image = c.image ?? c.products?.find((p) => p.featuredImage)?.featuredImage ?? null
+  const overlay = textStyle === 'overlay'
+  // Count shows product count from collection data; hidden if unknown.
+  const count = showCount && !overlay && Number.isFinite(c.productsCount) && c.productsCount > 0 ? c.productsCount : null
+  return (
+    <div className="nv-collection-card" data-ratio={ratio} data-text={textStyle} data-lead={lead ? '' : undefined} data-no-image={image ? undefined : ''}>
+      <div className="nv-collection-card__media">
+        {image ? <img src={image.src} srcSet={image.srcSet} sizes="(min-width: 1024px) 25vw, 45vw" alt="" width={image.width} height={image.height} loading={priority ? 'eager' : 'lazy'} decoding="async" /> : <span className="nv-collection-card__name-tile" aria-hidden><bdi>{name}</bdi></span>}
+        {overlay && (
+          <T className="nv-collection-card__chip">
+            <a href={c.url} className="nv-collection-card__link nv-collection-card__chip-text">
+              <bdi>{name}</bdi>
+            </a>
+            <Icon name="arrow-right" size="sm" className="nv-dir" />
+          </T>
+        )}
+      </div>
+      {!overlay && (
+        <div className="nv-collection-card__info">
+          <T className="nv-collection-card__title">
+            <a href={c.url} className="nv-collection-card__link">
+              <bdi>{name}</bdi>
+            </a>
+            {count != null && <span className="nv-collection-card__count nv-tabular">{count}</span>}
+          </T>
+          {showDescription && c.description && <p className="nv-collection-card__desc"><bdi>{c.description}</bdi></p>}
+        </div>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,33 @@
+/* 12F · comparison table. Feature column ~ 23%; items share the rest; recommended = muted column + pill. */
+.nv-compare { display: grid; gap: var(--space-4); justify-items: start; }
+.nv-compare__scroll { position: relative; justify-self: stretch; min-width: 0; overflow-x: auto; }
+.nv-compare__table { width: 100%; border-collapse: separate; border-spacing: 0; table-layout: fixed; font-size: 0.9375rem; }
+.nv-compare__table :is(th, td) { padding: var(--space-3) var(--space-4); text-align: start; vertical-align: middle; border-block-end: 1px solid var(--color-border); font-weight: 400; }
+.nv-compare__table thead :is(th, td) { vertical-align: bottom; padding-block: var(--space-4); border-block-end-color: var(--color-border-emphasis); }
+.nv-compare__corner { width: 23%; padding-inline-start: 0 !important; font-size: var(--type-body-sm); color: var(--color-fg-muted); }
+.nv-compare__table tbody th { padding-inline-start: 0; font-weight: var(--weight-medium); }
+.nv-compare__table [data-rec] { background: var(--color-bg-muted); }
+.nv-compare__item[data-rec] { border-start-start-radius: var(--radius-lg); border-start-end-radius: var(--radius-lg); }
+.nv-compare__table tbody tr:last-child :is(th, td) { border-block-end: 0; }
+.nv-compare__head { display: grid; gap: var(--space-2); justify-items: start; }
+.nv-compare__pill { display: inline-flex; align-items: center; min-height: 20px; padding-inline: var(--space-2); border-radius: 999px; background: var(--color-fg); color: var(--color-bg); font-size: 0.6875rem; font-weight: var(--weight-medium); }
+.nv-compare__media { display: block; width: 100%; aspect-ratio: 4 / 3; margin-block-end: var(--space-2); border-radius: var(--radius-sm); overflow: hidden; background: var(--color-media-bg); }
+.nv-compare__media img { width: 100%; height: 100%; object-fit: cover; }
+.nv-compare__title { font-size: 1.0625rem; font-weight: var(--weight-medium); color: var(--color-fg); text-decoration: none; }
+a.nv-compare__title:hover { text-decoration: underline; text-underline-offset: var(--underline-offset); }
+.nv-compare__add { margin-block-start: var(--space-2); }
+.nv-compare__none { color: var(--color-fg-muted); }
+.nv-compare__table tr[data-missing] th { box-shadow: inset 3px 0 0 var(--color-warning); padding-inline-start: var(--space-3); }
+.nv-compare__swipe { display: none; font-size: var(--type-caption); color: var(--color-fg-muted); }
+
+@media (max-width: 639.98px) {
+  .nv-compare__table { width: calc(6.5rem + var(--nv-compare-cols) * 10rem); font-size: 0.8125rem; }
+  .nv-compare__corner { width: 6.5rem; }
+  .nv-compare__table :is(th, td) { padding: var(--space-3); }
+  .nv-compare__table :is(thead td, tbody th) { position: sticky; inset-inline-start: 0; z-index: 1; background: var(--color-bg); padding-inline-start: var(--space-3) !important; }
+  .nv-compare__table thead :is(th, td) { padding-block: var(--space-3); }
+  .nv-compare__media, .nv-compare__head .nv-price, .nv-compare__add { display: none; }
+  .nv-compare__title { font-size: 0.8125rem; }
+  .nv-compare__item[data-rec] { border-radius: 0; }
+  .nv-compare__swipe { display: block; }
+}

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

@@ -0,0 +1,113 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import { useRef, useState, type CSSProperties } from 'react'
+import { Button } from '../base/Button'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import { useScrollRegion } from '../../styles/scroll'
+import type { NovaImage, Product } from '@tanqory/theme-kit'
+import { Price } from './Price'
+import { hasPriceRange } from './money'
+import './ComparisonTable.css'
+
+export interface ComparisonColumn {
+  title: string
+  image?: NovaImage | null
+  /** Supplies price and Add to cart; sold out → disabled. */
+  product?: Product | null
+  /** One value per feature row; missing values render —. */
+  values: readonly string[]
+}
+
+export interface ComparisonTableProps {
+  features: readonly string[]
+  columns: readonly ComparisonColumn[]
+  /** 1-based recommended column; 0 = none. */
+  highlight?: number
+  showProductRow?: boolean
+  /** Hide rows whose values are all the same. */
+  differencesOnly?: boolean
+  /** Rows shown before "Show all features". */
+  collapseAfter?: number
+  onAdd?: (product: Product) => void
+  /** Accessible name of the table (the section heading). */
+  caption?: string
+}
+
+/** The contract's words for yes / no — rendered as ✓ / — with a text alternative. */
+const YES = /^(yes|y|true|✓|✔)$/i
+const NO = /^(no|n|false|—|-|–)$/i
+
+export function sameRow(values: readonly (string | undefined)[]): boolean {
+  const norm = values.map((v) => (v ?? '').trim().toLowerCase())
+  return norm.every((v) => v === norm[0])
+}
+
+/**
+ * 12F · comparison table. Real table markup — items are column headers,
+ * features are row headers. One recommended column: muted fill down the
+ * whole column and a "Recommended" pill. At 390 the feature column sticks
+ * and 1.6 items show so it is clear there is more.
+ */
+export function ComparisonTable({ features, columns, highlight = 0, showProductRow = true, differencesOnly, collapseAfter = 10, onAdd, caption }: ComparisonTableProps): JSX.Element {
+  const { strings, mode } = useNova()
+  const [all, setAll] = useState(false)
+  const wrap = useRef<HTMLDivElement>(null)
+  const region = useScrollRegion(wrap, caption ?? strings.feature, [columns.length, features.length])
+  const rows = features.map((f, i) => ({ feature: f, values: columns.map((c) => c.values[i]) })).filter((r) => !differencesOnly || !sameRow(r.values))
+  const shown = all ? rows : rows.slice(0, collapseAfter)
+  const rec = highlight >= 1 && highlight <= columns.length ? highlight - 1 : -1
+
+  const cell = (v: string | undefined) => {
+    const t = (v ?? '').trim()
+    if (!t) return <span className="nv-compare__none">—</span>
+    if (YES.test(t)) return <><span aria-hidden>✓</span><span className="nv-visually-hidden">{strings.yes}</span></>
+    if (NO.test(t)) return <><span className="nv-compare__none" aria-hidden>—</span><span className="nv-visually-hidden">{strings.no}</span></>
+    return t
+  }
+
+  return (
+    <div className={sxJoin("nv-compare", sx({ '--nv-compare-cols': columns.length } as CSSProperties))}>
+      <div ref={wrap} className="nv-compare__scroll" {...region}>
+        <table className="nv-compare__table">
+          {caption && <caption className="nv-visually-hidden"><bdi>{caption}</bdi></caption>}
+          <thead>
+            <tr>
+              <td className="nv-compare__corner">{strings.feature}</td>
+              {columns.map((c, i) => (
+                <th key={i} scope="col" className="nv-compare__item" data-rec={i === rec ? '' : undefined}>
+                  <span className="nv-compare__head">
+                    {i === rec && <span className="nv-compare__pill">{strings.recommended}</span>}
+                    {showProductRow && <span className="nv-compare__media">{c.image && <img src={c.image.src} alt="" width={c.image.width} height={c.image.height} loading="lazy" decoding="async" />}</span>}
+                    {c.product ? <a className="nv-compare__title" href={c.product.url}><bdi>{c.title}</bdi></a> : <span className="nv-compare__title"><bdi>{c.title}</bdi></span>}
+                    {showProductRow && c.product && <Price price={c.product.priceRange.min} from={hasPriceRange(c.product)} soldOut={!c.product.available} />}
+                    {showProductRow && c.product && onAdd && (
+                      <Button className="nv-compare__add" size="sm" block variant={i === rec ? 'primary' : 'secondary'} disabled={!c.product.available} onClick={() => onAdd(c.product!)}>
+                        {c.product.available ? strings.addToCart : strings.soldOut}
+                      </Button>
+                    )}
+                  </span>
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {shown.map((r) => (
+              <tr key={r.feature} data-missing={mode === 'editor' && r.values.some((v) => !(v ?? '').trim()) ? '' : undefined}>
+                <th scope="row"><bdi>{r.feature}</bdi></th>
+                {r.values.map((v, i) => (
+                  <td key={i} data-rec={i === rec ? '' : undefined}>{cell(v)}</td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      <p className="nv-compare__swipe" aria-hidden>{fmt(strings.swipeCompare, { count: columns.length })} </p>
+      {rows.length > collapseAfter && !all && (
+        <Button className="nv-compare__all" variant="secondary" size="sm" onClick={() => setAll(true)}>
+          {strings.showAllFeatures}
+        </Button>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,3 @@
+.nv-earn-hint { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-1) var(--space-3); margin: 0; color: var(--color-fg-muted); font-size: var(--type-caption); }
+.nv-earn-hint:empty { display: none; }
+.nv-earn-hint__signin { display: inline-flex; align-items: center; min-height: var(--touch-target); color: var(--color-fg); text-decoration: underline; text-underline-offset: var(--underline-offset); }

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

@@ -0,0 +1,31 @@
+import type { Money } from '@tanqory/theme-kit'
+import { earnPoints, useRewards } from '@tanqory/theme-kit'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import './EarnHint.css'
+
+/**
+ * "Earn 120 points with this item" (product page) / "... with this order" (cart), from the
+ * store's earn rate, the member's tier multiplier and the price shown. A guest is also told to
+ * sign in to collect them. Browser-only (the loyalty state is), so it is a client slot that
+ * stays empty on the server, in the editor and for a store with loyalty off.
+ */
+export function EarnHint({ amount, scope }: { amount: Money | null | undefined; scope: 'item' | 'order' }): JSX.Element {
+  const { state } = useRewards()
+  const { strings, locale } = useNova()
+  const points = amount ? earnPoints(amount.amount, amount.currencyCode, state) : null
+  return (
+    <p className="nv-earn-hint" data-tq-client-slot="earn-hint">
+      {points ? (
+        <>
+          <span>{fmt(scope === 'item' ? strings.earnWithItem : strings.earnWithOrder, { points: new Intl.NumberFormat(locale).format(points) })}</span>
+          {!state?.signedIn && (
+            <a className="nv-earn-hint__signin" href="/account/login">
+              {strings.earnSignIn}
+            </a>
+          )}
+        </>
+      ) : null}
+    </p>
+  )
+}

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

@@ -0,0 +1,16 @@
+.nv-hotspot { position: absolute; z-index: 1; width: 0; height: 0; }
+.nv-hotspot[data-active] { z-index: 2; }
+.nv-hotspot__dot { position: absolute; inset-block-start: -22px; inset-inline-start: -22px; display: grid; place-items: center; width: 44px; height: 44px; padding: 0; border: 0; background: none; cursor: pointer; }
+.nv-hotspot__dot span { display: grid; place-items: center; width: 28px; height: 28px; border-radius: 50%; background: var(--color-on-media); color: var(--color-on-media-ink); box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.55), var(--shadow-floating); font-size: 0.75rem; font-weight: var(--weight-medium); font-variant-numeric: tabular-nums; transition: transform var(--duration-fast, 120ms) var(--ease-standard, ease); }
+.nv-hotspot[data-active] .nv-hotspot__dot span { width: 32px; height: 32px; background: var(--color-on-media-ink); color: var(--color-on-media); box-shadow: 0 0 0 2px var(--color-on-media), var(--shadow-floating); }
+.nv-hotspot__dot:hover span { transform: scale(1.08); }
+.nv-hotspot__dot:focus-visible { outline: none; }
+.nv-hotspot__dot:focus-visible span { outline: var(--focus-ring-width) solid var(--color-focus); outline-offset: 3px; }
+.nv-hotspot__card { position: absolute; inset-block-start: -32px; inset-inline-start: 22px; display: flex; gap: var(--space-3); align-items: center; width: 13.25rem; padding: var(--space-2); border-radius: var(--radius-md); background: var(--color-bg); color: var(--color-fg); box-shadow: var(--shadow-popover); text-decoration: none; }
+.nv-hotspot[data-flip] .nv-hotspot__card { inset-inline-start: auto; inset-inline-end: 22px; }
+.nv-hotspot__card img { flex: none; width: 46px; height: 46px; border-radius: var(--radius-sm); object-fit: cover; background: var(--color-media-bg); }
+.nv-hotspot__text { display: grid; gap: 2px; min-width: 0; font-size: var(--type-body-sm); line-height: 1.3; }
+.nv-hotspot__title { font-weight: var(--weight-medium); }
+.nv-hotspot__card:hover .nv-hotspot__title { text-decoration: underline; text-underline-offset: var(--underline-offset); }
+.nv-hotspot__card:focus-visible { outline: var(--focus-ring-width) solid var(--color-focus); outline-offset: 2px; }
+@media (prefers-reduced-motion: reduce) { .nv-hotspot__dot span { transition: none; } }

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

@@ -0,0 +1,64 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import { useEffect, useId } from 'react'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import type { Product } from '@tanqory/theme-kit'
+import { formatMoney, hasPriceRange } from './money'
+import './Hotspot.css'
+
+export interface HotspotProps {
+  /** 1-based, matching the product list. */
+  index: number
+  product: Product
+  /** Percent from the start / top edge of the image. */
+  x: number
+  y: number
+  active?: boolean
+  /** Show the popover card when active (off at 390: the list scrolls instead). */
+  card?: boolean
+  onActivate?: () => void
+  onClose?: () => void
+}
+
+/**
+ * 12F · a numbered point on a look image: 44 target, 28 dot (32 active),
+ * white ring + shadow. Active shows a card — image, name, price; the card
+ * opens the product; Esc closes. The product list is the accessible
+ * alternative, so the dots follow list order.
+ */
+export function Hotspot({ index, product: p, x, y, active, card = true, onActivate, onClose }: HotspotProps): JSX.Element {
+  const { strings, locale } = useNova()
+  const id = useId()
+  const open = Boolean(active && card)
+  useEffect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent) => e.key === 'Escape' && onClose?.()
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [open, onClose])
+  const price = formatMoney(p.priceRange.min, locale)
+  const img = p.featuredImage
+  return (
+    <div className={sxJoin("nv-hotspot", sx({ insetInlineStart: `${x}%`, insetBlockStart: `${y}%` }))} data-active={active ? '' : undefined} data-flip={x > 58 ? '' : undefined}>
+      <button
+        type="button"
+        className="nv-hotspot__dot"
+        aria-label={fmt(strings.hotspot, { index, title: p.title })}
+        aria-expanded={card ? open : undefined}
+        aria-controls={card ? id : undefined}
+        onClick={() => (active ? onClose?.() : onActivate?.())}
+      >
+        <span aria-hidden>{index}</span>
+      </button>
+      {open && (
+        <a id={id} className="nv-hotspot__card" href={p.url}>
+          {img && <img src={img.src} alt="" width={img.width} height={img.height} loading="lazy" decoding="async" />}
+          <span className="nv-hotspot__text">
+            <span className="nv-hotspot__title"><bdi>{p.title}</bdi></span>
+            <span className="nv-hotspot__price nv-tabular">{hasPriceRange(p) ? fmt(strings.priceFrom, { price }) : price}</span>
+          </span>
+        </a>
+      )}
+    </div>
+  )
+}

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

@@ -0,0 +1,79 @@
+/* 12C · listing parts. */
+.nv-facets { border-block-start: var(--border-subtle); }
+.nv-facet__values { list-style: none; margin: 0; padding: 0; display: grid; gap: var(--space-1); }
+.nv-facet__value { display: flex; align-items: center; justify-content: space-between; gap: var(--space-3); }
+.nv-facet__count { font-size: var(--type-label); color: var(--color-fg-muted); }
+.nv-facet__price { display: grid; grid-template-columns: 1fr auto 1fr; align-items: center; gap: var(--space-2); }
+
+.nv-disclosure { position: relative; }
+.nv-disclosure__button {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-height: var(--touch-target);
+  padding-inline: var(--space-3);
+  border-radius: var(--btn-radius);
+  box-shadow: inset 0 0 0 var(--border-width) var(--color-border-input);
+  background: var(--color-bg);
+  color: var(--color-fg);
+  font-size: var(--type-body-sm);
+  cursor: pointer;
+}
+.nv-disclosure[data-open] .nv-disclosure__button { box-shadow: inset 0 0 0 1.5px var(--color-fg); }
+.nv-disclosure__panel {
+  position: absolute;
+  z-index: var(--z-dropdown);
+  inset-block-start: calc(100% + var(--space-2));
+  inset-inline-start: 0;
+  min-width: 14rem;
+  padding: var(--space-3);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-elevated);
+  box-shadow: var(--shadow-floating);
+}
+.nv-disclosure[data-align='end'] .nv-disclosure__panel { inset-inline: auto 0; }
+.nv-sort__list { list-style: none; margin: 0; padding: 0; }
+.nv-sort__option {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  min-height: var(--touch-target);
+  padding-inline: var(--space-2);
+  border-radius: var(--radius-sm);
+  color: var(--color-fg);
+  font-size: var(--type-body-sm);
+  text-align: start;
+  cursor: pointer;
+}
+.nv-sort__option:hover { background: var(--color-bg-muted); }
+.nv-sort__option[aria-current='true'] { font-weight: var(--weight-medium); }
+
+.nv-active-filters { list-style: none; margin: 0; padding: 0; display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-2); }
+.nv-chip-filter {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-height: var(--space-6);
+  padding-inline: var(--space-3) var(--space-2);
+  border-radius: var(--radius-sm);
+  background: var(--color-bg-muted);
+  color: var(--color-fg);
+  font-size: var(--type-body-sm);
+  cursor: pointer;
+}
+.nv-chip-filter::after { content: ''; position: absolute; inset: calc((var(--space-6) - var(--touch-target)) / 2) 0; }
+.nv-active-filters__clear { min-height: var(--touch-target); padding-inline: var(--space-2); color: var(--color-fg); font-size: var(--type-body-sm); text-decoration: underline; text-underline-offset: var(--underline-offset); cursor: pointer; }
+
+.nv-load-more { display: grid; justify-items: center; gap: var(--space-3); margin-block-start: var(--space-7); }
+.nv-load-more__count { font-size: var(--type-body-sm); color: var(--color-fg-muted); }
+.nv-load-more__bar { width: min(12rem, 60%); height: 2px; background: var(--color-border); border-radius: var(--radius-pill); overflow: hidden; }
+.nv-load-more__bar span { display: block; height: 100%; background: var(--color-fg); }
+
+.nv-card-skeleton { display: grid; gap: var(--space-2); }
+
+.nv-listing-message { display: grid; justify-items: center; gap: var(--space-3); padding: var(--space-9) var(--space-5); text-align: center; }
+.nv-listing-message__title { font-size: var(--type-h4); font-weight: var(--weight-medium); }
+.nv-listing-message__hint { max-width: 40ch; color: var(--color-fg-muted); }
+.nv-listing-message__actions { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--space-2); margin-block-start: var(--space-2); }