@cartbase/storefront 0.1.0

package/src/products/purchase-options.tsx

@@ -0,0 +1,130 @@
+"use client"
+
+/**
+ * PDP purchase options — one-time vs subscription plans (subscriptions-core
+ * card, step 4; barter-native, no @1click/ui ancestor). Presentational and
+ * controlled: the host owns the selection and passes the chosen plan id
+ * into its add-to-cart seam (`carts.addLineItem` `selling_plan_id`). The
+ * SERVER prices the line — the preview here is display-only and computed
+ * from the same plan fields the server applies.
+ *
+ * Consent note (docs/storefront/checkout.md): a plan selection later
+ * requires a logged-in customer at payment (`save_payment_method` →
+ * 400 `customer_required` for guests) — surface login before checkout when
+ * a plan line is in the cart.
+ */
+import React from "react"
+import type { StoreSellingPlan } from "../api/products"
+import { cn } from "../lib/utils"
+
+export type PurchaseOptionsLabels = {
+  title: string
+  oneTime: string
+  /** Interval nouns, singular/plural: {day: ["day","days"], …} */
+  every: string
+}
+
+const DEFAULT_LABELS: PurchaseOptionsLabels = {
+  title: "Purchase options",
+  oneTime: "One-time purchase",
+  every: "Every",
+}
+
+/** Display-only mirror of the server's plan pricing (the server is truth). */
+export function previewPlanPrice(plan: StoreSellingPlan, basePrice: number): number {
+  if (plan.pricing_type === "percent" && plan.pricing_value != null) {
+    return Math.max(0, Math.round(basePrice * (1 - plan.pricing_value / 100) * 100) / 100)
+  }
+  if (plan.pricing_type === "fixed" && plan.pricing_value != null) {
+    return plan.pricing_value
+  }
+  return basePrice
+}
+
+export function cadenceLabel(plan: StoreSellingPlan, everyWord = "Every"): string {
+  const unit =
+    plan.interval_count === 1 ? plan.interval : `${plan.interval_count} ${plan.interval}s`
+  return `${everyWord} ${unit}`
+}
+
+type PurchaseOptionsProps = {
+  plans: StoreSellingPlan[]
+  /** Selected plan id; null = one-time. */
+  value: string | null
+  onChange: (sellingPlanId: string | null) => void
+  /** The one-time unit price (from the product's calculated price). */
+  basePrice: number
+  /** Format an amount for display (host's currency formatting). */
+  formatPrice: (amount: number) => string
+  disabled?: boolean
+  labels?: Partial<PurchaseOptionsLabels>
+  "data-testid"?: string
+}
+
+export function PurchaseOptions({
+  plans,
+  value,
+  onChange,
+  basePrice,
+  formatPrice,
+  disabled,
+  labels: labelOverrides,
+  "data-testid": dataTestId,
+}: PurchaseOptionsProps) {
+  const labels = { ...DEFAULT_LABELS, ...labelOverrides }
+  if (plans.length === 0) return null
+
+  const options: Array<{
+    id: string | null
+    title: string
+    subtitle: string | null
+    price: number
+  }> = [
+    { id: null, title: labels.oneTime, subtitle: null, price: basePrice },
+    ...plans.map((plan) => ({
+      id: plan.id,
+      title: plan.name,
+      subtitle: cadenceLabel(plan, labels.every),
+      price: previewPlanPrice(plan, basePrice),
+    })),
+  ]
+
+  return (
+    <div className="flex flex-col gap-y-3" data-testid={dataTestId}>
+      <span className="text-sm text-foreground">{labels.title}</span>
+      <div role="radiogroup" aria-label={labels.title} className="flex flex-col gap-2">
+        {options.map((opt) => {
+          const selected = value === opt.id
+          return (
+            <button
+              key={opt.id ?? "one-time"}
+              type="button"
+              role="radio"
+              aria-checked={selected}
+              onClick={() => onChange(opt.id)}
+              disabled={disabled}
+              className={cn(
+                "border border-border bg-muted rounded-lg p-3 flex items-center justify-between gap-3 text-left",
+                {
+                  "border-primary": selected,
+                  "hover:shadow-sm transition-shadow ease-in-out duration-150": !selected,
+                }
+              )}
+              data-testid="purchase-option"
+            >
+              <span className="flex flex-col">
+                <span className="text-sm text-foreground">{opt.title}</span>
+                {opt.subtitle && (
+                  <span className="text-xs text-muted-foreground">{opt.subtitle}</span>
+                )}
+              </span>
+              <span className="text-sm text-foreground whitespace-nowrap">
+                {formatPrice(opt.price)}
+              </span>
+            </button>
+          )
+        })}
+      </div>
+    </div>
+  )
+}

package/src/products/related-products.tsx

@@ -0,0 +1,86 @@
+/**
+ * Related-products strip — ported from
+ * `@1click/ui/src/products/related-products.tsx` (v2.3.1), REWIRED to the
+ * barter related-products endpoint (docs/storefront/search.md).
+ *
+ * The original hand-rolled relatedness client-side (same collection + shared
+ * tags via a products listing). barter owns that server-side:
+ * `api/search` `listRelatedProducts` returns manual admin picks first
+ * (Admin → Product → Related, position order), then a deterministic fallback
+ * fills to `limit` — same primary collection (newest first), then
+ * most-shared-tags (`auto_filled: true` when any fallback item is present).
+ * The anchor product is never in the results, so the source's self-filter is
+ * gone. Region resolution via `countryCode` is replaced by the barter
+ * pricing context (`currency_code`/`region_id`).
+ *
+ * Async server component — render inside `<Suspense>`.
+ */
+import type { ComponentType } from "react"
+import type { StorefrontClient } from "../api/http"
+import type { PricingContextQuery } from "../api/types"
+import type { StoreProduct } from "../api/products"
+import { listRelatedProducts } from "../api/search"
+import { StoreApiError } from "../api/types"
+import { ProductPreview } from "./product-preview"
+import { defaultProductLabels, type ProductLabels } from "./labels"
+
+type RelatedProductsProps = {
+  client: StorefrontClient
+  product: StoreProduct
+  /** Pricing context for `calculated_price` on the related cards. */
+  pricingContext?: PricingContextQuery
+  /** 1–24, server default 12. */
+  limit?: number
+  labels?: Pick<ProductLabels, "relatedProducts" | "relatedProductsDescription">
+  /** Override the default ProductPreview with a store-specific card. */
+  renderProduct?: ComponentType<{ product: StoreProduct }>
+}
+
+export async function RelatedProducts({
+  client,
+  product,
+  pricingContext,
+  limit,
+  labels,
+  renderProduct: Card = ProductPreview,
+}: RelatedProductsProps) {
+  const l = { ...defaultProductLabels, ...labels }
+
+  let products: StoreProduct[]
+  try {
+    const res = await listRelatedProducts(client, product.id, {
+      ...(limit !== undefined ? { limit } : {}),
+      ...pricingContext,
+    })
+    products = res.products
+  } catch (e) {
+    // Anchor invisible to this key/tenant (404) → render nothing, matching
+    // the source's null-region behavior. Everything else propagates.
+    if (e instanceof StoreApiError && e.status === 404) return null
+    throw e
+  }
+
+  if (!products.length) return null
+
+  return (
+    <div>
+      <div className="flex flex-col items-center text-center mb-16">
+        <span className="text-sm text-muted-foreground mb-6">
+          {l.relatedProducts}
+        </span>
+        <p className="text-2xl text-foreground max-w-lg">
+          {l.relatedProductsDescription}
+        </p>
+      </div>
+      <ul className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 gap-x-6 gap-y-8">
+        {products.map((p) => (
+          <li key={p.id}>
+            <Card product={p} />
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+
+export { type RelatedProductsProps }

package/src/products/thumbnail.tsx

@@ -0,0 +1,71 @@
+/**
+ * Product thumbnail — ported from `@1click/ui/src/products/thumbnail.tsx`
+ * (v2.3.1) unchanged (structural props: works with `StoreProduct.thumbnail`
+ * + `StoreProduct.images`). Server-safe (no "use client"): renders inside
+ * RSC product grids.
+ */
+import Image from "next/image"
+import React from "react"
+import { ImageOff } from "lucide-react"
+
+import { cn } from "../lib/utils"
+
+type ThumbnailProps = {
+  thumbnail?: string | null
+  images?: { url: string }[] | null
+  size?: "small" | "medium" | "large" | "full" | "square"
+  isFeatured?: boolean
+  className?: string
+  "data-testid"?: string
+}
+
+const Thumbnail: React.FC<ThumbnailProps> = ({
+  thumbnail,
+  images,
+  size = "small",
+  isFeatured,
+  className,
+  "data-testid": dataTestid,
+}) => {
+  const initialImage = thumbnail || images?.[0]?.url
+
+  return (
+    <div
+      className={cn(
+        "relative w-full overflow-hidden p-4 bg-muted rounded-lg group-hover:shadow-md transition-shadow ease-in-out duration-150",
+        {
+          "aspect-[11/14]": isFeatured,
+          "aspect-[9/16]": !isFeatured && size !== "square",
+          "aspect-[1/1]": size === "square",
+          "w-[180px]": size === "small",
+          "w-[290px]": size === "medium",
+          "w-[440px]": size === "large",
+          "w-full": size === "full",
+        },
+        className
+      )}
+      data-testid={dataTestid}
+    >
+      {initialImage ? (
+        <Image
+          src={initialImage}
+          alt="Thumbnail"
+          className="absolute inset-0 object-cover object-center"
+          draggable={false}
+          quality={50}
+          sizes="(max-width: 576px) 280px, (max-width: 768px) 360px, (max-width: 992px) 480px, 800px"
+          fill
+        />
+      ) : (
+        <div className="w-full h-full absolute inset-0 flex items-center justify-center">
+          <ImageOff
+            className="text-muted-foreground"
+            size={size === "small" ? 16 : 24}
+          />
+        </div>
+      )}
+    </div>
+  )
+}
+
+export { Thumbnail, type ThumbnailProps }

package/src/products/variant-matching.ts

@@ -0,0 +1,71 @@
+/**
+ * Pure variant-matching logic — extracted from
+ * `@1click/ui/src/products/product-actions.tsx` (v2.3.1) so the
+ * option-choice → variant resolution is testable without React
+ * (tests/unit/storefront-catalog.test.ts).
+ *
+ * Data-seam translation: Medusa served `variant.options[]` as flat
+ * `{option_id, value}` rows; barter serves option-value LINKS
+ * (`{value: {option_id, value, option}}` — see
+ * `@cartbase/storefront/api/products` `StoreVariantOptionValueLink`).
+ * `optionsAsKeymap` reads the barter link shape (null-safe) and falls back
+ * to the flat Medusa row shape so both wire formats resolve identically.
+ */
+
+/** Either barter's option-value link or Medusa's flat option-value row. */
+export type VariantOptionLike =
+  | {
+      option_id?: string
+      value?: string | { option_id: string; value: string } | null
+    }
+  | null
+
+/** Chosen options on a PDP: option_id → chosen value (undefined = not chosen). */
+export type OptionChoices = Record<string, string | undefined>
+
+/**
+ * Flatten a variant's option values into `{[option_id]: value}` for
+ * comparison against the user's current choices.
+ */
+export function optionsAsKeymap(
+  variantOptions: VariantOptionLike[] | null | undefined
+): Record<string, string> | undefined {
+  return variantOptions?.reduce((acc: Record<string, string>, varopt) => {
+    if (!varopt) return acc
+    const v = varopt.value
+    if (v && typeof v === "object") {
+      // barter link shape: { value: { option_id, value } }
+      if (v.option_id) acc[v.option_id] = v.value
+    } else if (varopt.option_id && typeof v === "string") {
+      // Medusa flat row shape: { option_id, value }
+      acc[varopt.option_id] = v
+    }
+    return acc
+  }, {})
+}
+
+/**
+ * True when the chosen options exactly cover the variant's keymap — same
+ * key count, same values. Partial choices never match (the add-to-cart
+ * button stays disabled until every option is picked).
+ */
+export function optionsMatch(
+  a: OptionChoices,
+  b: Record<string, string> | undefined
+): boolean {
+  if (!b) return false
+  const keys = Object.keys(a)
+  if (keys.length !== Object.keys(b).length) return false
+  return keys.every((k) => a[k] === b[k])
+}
+
+/** Resolve the variant whose options exactly match the current choices. */
+export function findMatchingVariant<
+  V extends { options?: VariantOptionLike[] | null }
+>(
+  variants: V[] | null | undefined,
+  options: OptionChoices
+): V | undefined {
+  if (!variants || variants.length === 0) return undefined
+  return variants.find((v) => optionsMatch(options, optionsAsKeymap(v.options)))
+}

package/src/reviews-ui/helpers.ts

@@ -0,0 +1,174 @@
+/**
+ * Pure helpers for the reviews-UI family — no React, no fetches. Ported
+ * from the Alenika production storefront (src/lib/reviews-api.ts +
+ * src/components/product/reviews-list.tsx + review-form.tsx) with the
+ * hardcoded Bulgarian copy replaced by the labels pack. Unit-tested in
+ * tests/unit/storefront-order-reviews.test.ts.
+ */
+import type { ReviewsUiLabels } from "./labels"
+
+/** Replace `{key}` slots in a label template. Unknown slots are left as-is. */
+export function formatLabel(
+  template: string,
+  vars: Record<string, string | number> = {}
+): string {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) =>
+    key in vars ? String(vars[key]) : match
+  )
+}
+
+/**
+ * Public display name: first name + last-word initial ("Мария Петрова" →
+ * "Мария П."). The full surname is NEVER shown publicly. Shared by the
+ * visible reviews list AND any JSON-LD the app renders, so the two can't
+ * drift (production fix — the JSON-LD once leaked the full name to Google
+ * while the UI abbreviated). `fallback` covers empty names ("Клиент" on
+ * Alenika).
+ */
+export function reviewDisplayName(full: string, fallback = "Customer"): string {
+  const parts = (full || "").trim().split(/\s+/).filter(Boolean)
+  if (parts.length === 0) return fallback
+  const last = parts[parts.length - 1] as string
+  if (parts.length === 1) return last
+  return `${parts.slice(0, -1).join(" ")} ${last.charAt(0).toUpperCase()}.`
+}
+
+/** First word of a full name — the wizard greeting ("Здравей, Мария"). */
+export function firstNameOf(fullName: string): string {
+  return (fullName || "").trim().split(/\s+/)[0] || ""
+}
+
+/**
+ * Relative-or-absolute review date: today / yesterday / "{n} days ago"
+ * under 30 days, then DD.MM.YYYY. Port of the Alenika
+ * `fmtRelativeOrAbsolute`; `now` is injectable for tests.
+ */
+export function formatReviewDate(
+  iso: string,
+  labels: Pick<ReviewsUiLabels, "dateToday" | "dateYesterday" | "dateDaysAgo">,
+  now: number = Date.now()
+): string {
+  const d = new Date(iso)
+  if (isNaN(d.getTime())) return ""
+  const ageMs = now - d.getTime()
+  const ageDays = ageMs / (24 * 60 * 60 * 1000)
+  if (ageDays < 1) return labels.dateToday
+  if (ageDays < 2) return labels.dateYesterday
+  if (ageDays < 30)
+    return formatLabel(labels.dateDaysAgo, { n: Math.floor(ageDays) })
+  return `${String(d.getDate()).padStart(2, "0")}.${String(
+    d.getMonth() + 1
+  ).padStart(2, "0")}.${d.getFullYear()}`
+}
+
+/** UI sort keys (the select) — richer than the API's 3-value `sort`. */
+export type ReviewSortKey = "default" | "rating-desc" | "rating-asc" | "date"
+
+/**
+ * Translate the UI sort key into the API's `(sort, order)` tuple
+ * (`api/reviews.ListReviewsQuery`). Port of the Alenika `sortParams`.
+ */
+export function sortParamsFor(s: ReviewSortKey): {
+  sort: "default" | "rating" | "date"
+  order?: "asc" | "desc"
+} {
+  if (s === "rating-desc") return { sort: "rating", order: "desc" }
+  if (s === "rating-asc") return { sort: "rating", order: "asc" }
+  if (s === "date") return { sort: "date" }
+  return { sort: "default" }
+}
+
+/** "1 review" / "N reviews" — singular/plural noun pick. */
+export function reviewCountLabel(
+  count: number,
+  labels: Pick<ReviewsUiLabels, "reviewSingular" | "reviewPlural">
+): string {
+  return `${count} ${count === 1 ? labels.reviewSingular : labels.reviewPlural}`
+}
+
+// ---------------------------------------------------------------------------
+// Upload constraints — MUST mirror the server rules (docs/storefront/
+// reviews.md: image ≤ 8MB, video ≤ 50MB; ≤ 6 images + ≤ 1 video; MIME
+// image/jpeg|jpg|png|webp, video/mp4|quicktime; 60s video cap is a
+// client-side production rule from Alenika).
+// ---------------------------------------------------------------------------
+
+export const MAX_IMAGES = 6
+export const MAX_VIDEOS = 1
+export const MAX_BODY = 2000
+export const MAX_IMAGE_BYTES = 8 * 1024 * 1024
+export const MAX_VIDEO_BYTES = 50 * 1024 * 1024
+export const MAX_VIDEO_SECONDS = 60
+export const IMAGE_MIME = new Set([
+  "image/jpeg",
+  "image/jpg",
+  "image/png",
+  "image/webp",
+])
+export const VIDEO_MIME = new Set(["video/mp4", "video/quicktime"])
+export const UPLOAD_ACCEPT =
+  "image/jpeg,image/jpg,image/png,image/webp,video/mp4,video/quicktime"
+
+export interface FileCheckInput {
+  name: string
+  type: string
+  size: number
+}
+
+export type FileCheckResult =
+  | { ok: true; kind: "image" | "video" }
+  | {
+      ok: false
+      /** Labels key for the error copy. */
+      errorKey:
+        | "errUnsupported"
+        | "errMaxImages"
+        | "errImageTooLarge"
+        | "errMaxVideos"
+        | "errVideoTooLarge"
+      /** `formatLabel` vars for the error template. */
+      vars: Record<string, string | number>
+    }
+
+/**
+ * Pure per-file admission check for a multi-select batch. Production fix
+ * preserved from Alenika: the caller decrements LOCAL slot counters as
+ * files are accepted (`imgSlots`/`vidSlots` start at max − current), so a
+ * multi-select of N files can't all pass the cap against stale render
+ * state in one pass. Video DURATION is checked separately (async metadata
+ * read) in the uploader component.
+ */
+export function checkFileForUpload(
+  file: FileCheckInput,
+  slots: { imgSlots: number; vidSlots: number }
+): FileCheckResult {
+  const isImage = IMAGE_MIME.has(file.type)
+  const isVideo = VIDEO_MIME.has(file.type)
+  if (!isImage && !isVideo) {
+    return { ok: false, errorKey: "errUnsupported", vars: { name: file.name } }
+  }
+  if (isImage) {
+    if (slots.imgSlots <= 0) {
+      return { ok: false, errorKey: "errMaxImages", vars: { n: MAX_IMAGES } }
+    }
+    if (file.size > MAX_IMAGE_BYTES) {
+      return {
+        ok: false,
+        errorKey: "errImageTooLarge",
+        vars: { name: file.name, mb: MAX_IMAGE_BYTES / 1024 / 1024 },
+      }
+    }
+    return { ok: true, kind: "image" }
+  }
+  if (slots.vidSlots <= 0) {
+    return { ok: false, errorKey: "errMaxVideos", vars: { n: MAX_VIDEOS } }
+  }
+  if (file.size > MAX_VIDEO_BYTES) {
+    return {
+      ok: false,
+      errorKey: "errVideoTooLarge",
+      vars: { mb: MAX_VIDEO_BYTES / 1024 / 1024 },
+    }
+  }
+  return { ok: true, kind: "video" }
+}

package/src/reviews-ui/index.ts

@@ -0,0 +1,74 @@
+/**
+ * @cartbase/storefront/reviews-ui — verified-purchase review components.
+ * NEW family (no @1click/ui counterpart): ported/adapted from the Alenika
+ * production storefront (src/components/product/reviews-list.tsx + the
+ * /review/[token] page + review-form.tsx) over the batch-9 SDK
+ * (`api/reviews` — DTOs mirror alenika/src/lib/reviews-api.ts verbatim).
+ * Contracts: docs/storefront/components.md + docs/storefront/reviews.md.
+ */
+export {
+  defaultReviewsUiLabels,
+  type ReviewsUiLabels,
+} from "./labels"
+export { bulgarianReviewsUiLabels } from "./labels-bg"
+
+export {
+  formatLabel,
+  reviewDisplayName,
+  firstNameOf,
+  formatReviewDate,
+  sortParamsFor,
+  reviewCountLabel,
+  checkFileForUpload,
+  MAX_IMAGES,
+  MAX_VIDEOS,
+  MAX_BODY,
+  MAX_IMAGE_BYTES,
+  MAX_VIDEO_BYTES,
+  MAX_VIDEO_SECONDS,
+  IMAGE_MIME,
+  VIDEO_MIME,
+  UPLOAD_ACCEPT,
+  type ReviewSortKey,
+  type FileCheckInput,
+  type FileCheckResult,
+} from "./helpers"
+
+export {
+  resolveWizardEntry,
+  submitErrorKeyFor,
+  canSubmitRating,
+  type WizardEntry,
+  type WizardStep,
+  type SubmitErrorKey,
+} from "./wizard-state"
+
+export {
+  StarRow,
+  StarBadge,
+  RatingDistribution,
+  type StarBadgeProps,
+  type RatingDistributionProps,
+} from "./star-badge"
+
+export {
+  ReviewList,
+  ReviewLightbox,
+  type ReviewListProps,
+} from "./review-list"
+
+export { ReviewWidget, type ReviewWidgetProps } from "./review-widget"
+
+export {
+  ReviewWizard,
+  ReviewWizardForm,
+  type ReviewWizardProps,
+} from "./review-wizard"
+
+export {
+  ReviewPhotoUpload,
+  readyMedia,
+  putToSignedUrl,
+  type LocalMedia,
+  type ReviewPhotoUploadProps,
+} from "./photo-upload"