@cartbase/storefront 0.1.0

package/src/reviews-ui/wizard-state.ts

@@ -0,0 +1,81 @@
+/**
+ * Wizard step resolution — the pure state machine behind the review token
+ * wizard. Ported from the Alenika /review/[token] server page's branching
+ * (page.tsx) so the SAME rules hold wherever the wizard mounts.
+ * Unit-tested in tests/unit/storefront-order-reviews.test.ts.
+ */
+import type { TokenValidation } from "../api/reviews"
+
+export type WizardStep = "rate" | "photo" | "done"
+
+export type WizardEntry =
+  /** Token bad — show the invalid/expired panel. */
+  | { kind: "invalid"; reason: "not_found" | "expired" | "invalid" }
+  /**
+   * Consumed token with NO review row (deleted / never created) — the
+   * terminal "thanks, already done" panel. NOT resumable.
+   */
+  | { kind: "already-submitted" }
+  /** Render the form at `step`. */
+  | {
+      kind: "form"
+      step: WizardStep
+      reviewId: string | null
+      rewardCode: string | null
+    }
+
+/**
+ * THE resume rule (production behavior, verified against barter's token
+ * endpoint in batch 9): a consumed token does NOT mean "done".
+ *
+ *  - `valid: false`                                  → invalid panel
+ *  - consumed + review row + `reward_code` set       → "done" (show code)
+ *  - consumed + review row + `reward_code` null      → resume at "photo"
+ *  - consumed + NO review row                        → terminal thanks panel
+ *  - not consumed                                    → fresh "rate"
+ */
+export function resolveWizardEntry(validation: TokenValidation): WizardEntry {
+  if (!validation.valid) {
+    return { kind: "invalid", reason: validation.reason }
+  }
+  const review = validation.already_submitted ? validation.review : null
+  if (validation.already_submitted && !review) {
+    return { kind: "already-submitted" }
+  }
+  const step: WizardStep = review?.reward_code
+    ? "done"
+    : review
+      ? "photo"
+      : "rate"
+  return {
+    kind: "form",
+    step,
+    reviewId: review?.id ?? null,
+    rewardCode: review?.reward_code ?? null,
+  }
+}
+
+/** Labels keys usable as submit-error copy. */
+export type SubmitErrorKey =
+  | "errRateLimited"
+  | "errAlreadySubmitted"
+  | "errExpired"
+  | "errGeneric"
+
+/**
+ * HTTP status → labels key for the submit step (POST /api/store/reviews
+ * error contract: 429 rate_limited · 409 conflict (token replay) · 410
+ * gone (expired) · anything else generic). Port of Alenika's
+ * `submitErrorMessage`.
+ */
+export function submitErrorKeyFor(status: number): SubmitErrorKey {
+  if (status === 429) return "errRateLimited"
+  if (status === 409) return "errAlreadySubmitted"
+  if (status === 410) return "errExpired"
+  return "errGeneric"
+}
+
+/** Step-1 gate: a rating AND a non-blank body are both required. */
+export function canSubmitRating(rating: number, body: string): boolean {
+  return rating >= 1 && rating <= 5 && body.trim().length > 0
+}

package/src/store/category-template.tsx

@@ -0,0 +1,129 @@
+/**
+ * Category page — ported from
+ * `@1click/ui/src/store/category-template.tsx` (v2.3.1). Data seam:
+ * `HttpTypes.StoreProductCategory` → barter `StoreProductCategory`
+ * (`@cartbase/storefront/api/categories`); products come from the plain
+ * listing filtered by `category_id` (membership), via `PaginatedProducts`.
+ *
+ * Breadcrumbs need `parent_category` chains and the child list needs
+ * `category_children` — fetch the category with `include_ancestors_tree` +
+ * `include_descendants_tree` (`retrieveCategory` query flags), otherwise
+ * those sections simply don't render. Skeleton count is the fixed default
+ * (barter categories don't embed a products array).
+ */
+import { Suspense } from "react"
+import { notFound } from "next/navigation"
+import Link from "next/link"
+import type { StorefrontClient } from "../api/http"
+import type { PricingContextQuery } from "../api/types"
+import type { StoreProductCategory } from "../api/categories"
+import type { SortOptions } from "../lib/sort-products"
+import type { StoreLabels } from "./labels"
+import { SortSelect } from "./sort-select"
+import { PaginatedProducts, type ProductCardComponent } from "./paginated-products"
+import { SkeletonProductGrid } from "./skeleton-product-grid"
+
+type CategoryTemplateProps = {
+  client: StorefrontClient
+  category: StoreProductCategory
+  sortBy?: SortOptions
+  /** From the `page` query param. */
+  page?: string
+  pricingContext?: PricingContextQuery
+  labels?: Partial<StoreLabels>
+  /** Override the default ProductPreview with a store-specific card. */
+  renderProduct?: ProductCardComponent
+}
+
+export function CategoryTemplate({
+  client,
+  category,
+  sortBy,
+  page,
+  pricingContext,
+  labels,
+  renderProduct,
+}: CategoryTemplateProps) {
+  const pageNumber = page ? parseInt(page) : 1
+  const sort = sortBy || "created_at"
+
+  if (!category) notFound()
+
+  const parents: StoreProductCategory[] = []
+  const getParents = (cat: StoreProductCategory) => {
+    if (cat.parent_category) {
+      parents.push(cat.parent_category)
+      getParents(cat.parent_category)
+    }
+  }
+  getParents(category)
+
+  return (
+    <div
+      className="flex flex-col sm:flex-row sm:items-start py-6 max-w-7xl mx-auto px-4"
+      data-testid="category-container"
+    >
+      <div className="flex sm:flex-col gap-12 py-4 mb-8 sm:px-0 pl-6 sm:min-w-[250px]">
+        <SortSelect
+          sortBy={sort}
+          labels={labels}
+          data-testid="sort-by-container"
+        />
+      </div>
+      <div className="w-full">
+        <div className="flex flex-row mb-8 gap-4">
+          {parents.map((parent) => (
+            <span key={parent.id} className="text-muted-foreground text-2xl">
+              <Link
+                className="mr-4 hover:text-foreground"
+                href={`/categories/${parent.handle}`}
+              >
+                {parent.name}
+              </Link>
+              /
+            </span>
+          ))}
+          <h1
+            className="text-2xl font-semibold text-foreground"
+            data-testid="category-page-title"
+          >
+            {category.name}
+          </h1>
+        </div>
+        {category.description && (
+          <div className="mb-8 text-sm text-muted-foreground">
+            <p>{category.description}</p>
+          </div>
+        )}
+        {category.category_children && (
+          <div className="mb-8">
+            <ul className="grid grid-cols-1 gap-2">
+              {category.category_children.map((c) => (
+                <li key={c.id}>
+                  <Link
+                    href={`/categories/${c.handle}`}
+                    className="text-primary hover:underline"
+                  >
+                    {c.name}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          </div>
+        )}
+        <Suspense fallback={<SkeletonProductGrid />}>
+          <PaginatedProducts
+            client={client}
+            sortBy={sort}
+            page={pageNumber}
+            categoryId={category.id}
+            pricingContext={pricingContext}
+            renderProduct={renderProduct}
+          />
+        </Suspense>
+      </div>
+    </div>
+  )
+}
+
+export { type CategoryTemplateProps }

package/src/store/collection-template.tsx

@@ -0,0 +1,139 @@
+/**
+ * Collection page — ported from
+ * `@1click/ui/src/store/collection-template.tsx` (v2.3.1), REWIRED to the
+ * barter collection MEMBERSHIP listing (docs/storefront/collections.md).
+ *
+ * The original filtered the plain products listing by `collection_id`
+ * (Medusa primary collection). barter collections are curated groupings
+ * (manual or smart) with an admin-set `default_sort` — the membership
+ * endpoint `api/collections` `listCollectionProducts` honors it SERVER-side
+ * (manual position, title, EUR price asc/desc, newest/oldest, best_selling).
+ * So: when the shopper has NOT picked a sort, send NO `order` — the admin's
+ * `default_sort` applies, and nothing is re-sorted client-side. A shopper
+ * override maps to the `order` param (still server-side, incl. price).
+ *
+ * `SortSelect` therefore receives `sortBy` unset until the shopper picks
+ * (no highlight = admin default).
+ */
+import { Suspense } from "react"
+import type { StorefrontClient } from "../api/http"
+import type { PricingContextQuery } from "../api/types"
+import type { StoreProduct } from "../api/products"
+import type { CollectionSortMode, StoreCollection } from "../api/collections"
+import { listCollectionProducts } from "../api/collections"
+import type { SortOptions } from "../lib/sort-products"
+import type { StoreLabels } from "./labels"
+import { SortSelect } from "./sort-select"
+import type { ProductCardComponent } from "./paginated-products"
+import { ProductPreview } from "../products/product-preview"
+import { Pagination } from "./pagination"
+import { SkeletonProductGrid } from "./skeleton-product-grid"
+
+const PRODUCT_LIMIT = 12
+
+/** Shopper sort override → membership-listing `order` param. */
+const ORDER_BY_SORT: Record<SortOptions, CollectionSortMode> = {
+  created_at: "newest",
+  price_asc: "price_asc",
+  price_desc: "price_desc",
+}
+
+type CollectionTemplateProps = {
+  client: StorefrontClient
+  collection: StoreCollection
+  /** Shopper override from the `sortBy` query param; unset = admin default_sort. */
+  sortBy?: SortOptions
+  /** From the `page` query param. */
+  page?: string
+  pricingContext?: PricingContextQuery
+  labels?: Partial<StoreLabels>
+  /** Override the default ProductPreview with a store-specific card. */
+  renderProduct?: ProductCardComponent
+}
+
+async function CollectionProducts({
+  client,
+  collectionId,
+  sortBy,
+  page,
+  pricingContext,
+  renderProduct: Card = ProductPreview,
+}: {
+  client: StorefrontClient
+  collectionId: string
+  sortBy?: SortOptions
+  page: number
+  pricingContext?: PricingContextQuery
+  renderProduct?: ProductCardComponent
+}) {
+  const res = await listCollectionProducts(client, collectionId, {
+    limit: PRODUCT_LIMIT,
+    offset: (page - 1) * PRODUCT_LIMIT,
+    ...(sortBy ? { order: ORDER_BY_SORT[sortBy] } : {}),
+    ...pricingContext,
+  })
+
+  const products: StoreProduct[] = res.products
+  const totalPages = Math.ceil(res.count / PRODUCT_LIMIT)
+
+  return (
+    <>
+      <ul
+        className="grid grid-cols-2 w-full sm:grid-cols-3 md:grid-cols-4 gap-x-6 gap-y-8"
+        data-testid="products-list"
+      >
+        {products.map((p) => (
+          <li key={p.id}>
+            <Card product={p} />
+          </li>
+        ))}
+      </ul>
+      {totalPages > 1 && (
+        <Pagination
+          data-testid="product-pagination"
+          page={page}
+          totalPages={totalPages}
+        />
+      )}
+    </>
+  )
+}
+
+export function CollectionTemplate({
+  client,
+  collection,
+  sortBy,
+  page,
+  pricingContext,
+  labels,
+  renderProduct,
+}: CollectionTemplateProps) {
+  const pageNumber = page ? parseInt(page) : 1
+
+  return (
+    <div className="flex flex-col sm:flex-row sm:items-start py-6 max-w-7xl mx-auto px-4">
+      <div className="flex sm:flex-col gap-12 py-4 mb-8 sm:px-0 pl-6 sm:min-w-[250px]">
+        <SortSelect sortBy={sortBy} labels={labels} />
+      </div>
+      <div className="w-full">
+        <div className="mb-8">
+          <h1 className="text-2xl font-semibold text-foreground">
+            {collection.title}
+          </h1>
+        </div>
+        <Suspense fallback={<SkeletonProductGrid />}>
+          <CollectionProducts
+            client={client}
+            collectionId={collection.id}
+            sortBy={sortBy}
+            page={pageNumber}
+            pricingContext={pricingContext}
+            renderProduct={renderProduct}
+          />
+        </Suspense>
+      </div>
+    </div>
+  )
+}
+
+export { type CollectionTemplateProps }

package/src/store/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @cartbase/storefront — store (listing) family barrel. Prefer subpath
+ * imports in apps; the barrel exists for convenience and for the extra pure
+ * module (search-params).
+ */
+export {
+  defaultStoreLabels,
+  sortOptionLabelKeys,
+  type StoreLabels,
+} from "./labels"
+export { bulgarianStoreLabels } from "./labels-bg"
+
+export { Pagination } from "./pagination"
+export { SortSelect, type SortSelectProps } from "./sort-select"
+export { PaginatedProducts, type ProductCardComponent } from "./paginated-products"
+export { SkeletonProductGrid } from "./skeleton-product-grid"
+export { StoreTemplate, type StoreTemplateProps } from "./store-template"
+export {
+  CollectionTemplate,
+  type CollectionTemplateProps,
+} from "./collection-template"
+export {
+  CategoryTemplate,
+  type CategoryTemplateProps,
+} from "./category-template"
+export { SearchTemplate, type SearchTemplateProps } from "./search-template"
+
+export {
+  parseSearchParams,
+  buildSearchQueryString,
+  fromQueryString,
+  toggleFacetSelection,
+  isFacetSelected,
+  clearFilters,
+  toSearchQuery,
+  type SearchPageState,
+  type RawSearchParams,
+  type FacetBucketRef,
+} from "./search-params"
+
+export { type SortOptions } from "../lib/sort-products"

package/src/store/labels-bg.ts

@@ -0,0 +1,22 @@
+/**
+ * Bulgarian store labels — ported from `@1click/ui/src/store/labels-bg.ts`
+ * (v2.3.1), extended with the search-template keys. Typed against the full
+ * `StoreLabels` shape so a missing translation is a compile error.
+ */
+import type { StoreLabels } from "./labels"
+
+export const bulgarianStoreLabels: StoreLabels = {
+  allProducts: "Всички продукти",
+  sortBy: "Сортирай по",
+  latestArrivals: "Най-нови",
+  priceLowToHigh: "Цена: ниска → висока",
+  priceHighToLow: "Цена: висока → ниска",
+  searchTitle: "Търсене",
+  searchPlaceholder: "Търсете продукти…",
+  searchAction: "Търси",
+  resultsFor: "Резултати за",
+  resultsCount: "резултата",
+  noResults: "Няма намерени продукти",
+  filters: "Филтри",
+  clearFilters: "Изчисти филтрите",
+}

package/src/store/labels.ts

@@ -0,0 +1,52 @@
+/**
+ * Store-family label map — ported from `@1click/ui/src/store/labels.ts`
+ * (v2.3.1), EXTENDED with the search-template keys (search-template is new
+ * in barter — no @1click source). i18n discipline: components merge
+ * `labels` props over these defaults; `labels-bg.ts` must cover every key
+ * (typed against the full shape — completeness is unit-tested).
+ */
+import type { SortOptions } from "../lib/sort-products"
+
+export type StoreLabels = {
+  allProducts: string
+  sortBy: string
+  latestArrivals: string
+  priceLowToHigh: string
+  priceHighToLow: string
+  // search-template (barter addition)
+  searchTitle: string
+  searchPlaceholder: string
+  searchAction: string
+  resultsFor: string
+  resultsCount: string
+  noResults: string
+  filters: string
+  clearFilters: string
+}
+
+export const defaultStoreLabels: StoreLabels = {
+  allProducts: "All products",
+  sortBy: "Sort by",
+  latestArrivals: "Latest Arrivals",
+  priceLowToHigh: "Price: Low → High",
+  priceHighToLow: "Price: High → Low",
+  searchTitle: "Search",
+  searchPlaceholder: "Search products…",
+  searchAction: "Search",
+  resultsFor: "Results for",
+  resultsCount: "results",
+  noResults: "No products found",
+  filters: "Filters",
+  clearFilters: "Clear filters",
+}
+
+/**
+ * Sort mode → label key. THE map `SortSelect` renders from — kept here
+ * (pure module) so completeness against `SortOptions` is unit-testable
+ * without importing React components.
+ */
+export const sortOptionLabelKeys: Record<SortOptions, keyof StoreLabels> = {
+  created_at: "latestArrivals",
+  price_asc: "priceLowToHigh",
+  price_desc: "priceHighToLow",
+}

package/src/store/paginated-products.tsx

@@ -0,0 +1,116 @@
+/**
+ * Paginated product grid — ported from
+ * `@1click/ui/src/store/paginated-products.tsx` (v2.3.1). Data seam: the
+ * Medusa `listProductsWithSort` server action (region-resolved via
+ * `countryCode`) becomes `api/products` `listProducts` with the barter
+ * pricing context (`currency_code`/`region_id`).
+ *
+ * Sorting (server truth first):
+ * - `created_at` (default) → server `order: "-created_at"` with real
+ *   limit/offset pagination.
+ * - `price_asc`/`price_desc` → price is NOT a products-table column, so the
+ *   @1click production approach is preserved: fetch the sort window
+ *   (100 items, the `listProductsWithSort` cap), re-sort client-side on the
+ *   server-computed `calculated_price` (`lib/sort-products`), slice the
+ *   page. Catalogs past 100 items should sort via the collection membership
+ *   listing (collection-template), where price sorting IS server-side.
+ *
+ * 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 { ListProductsQuery, StoreProduct } from "../api/products"
+import { listProducts } from "../api/products"
+import { sortProducts, type SortOptions } from "../lib/sort-products"
+import { ProductPreview } from "../products/product-preview"
+import { Pagination } from "./pagination"
+
+/** A component that renders a single product card. */
+export type ProductCardComponent = ComponentType<{
+  product: StoreProduct
+}>
+
+const PRODUCT_LIMIT = 12
+/** The @1click client-sort window (listProductsWithSort cap). */
+const SORT_WINDOW = 100
+
+export async function PaginatedProducts({
+  client,
+  sortBy,
+  page,
+  collectionId,
+  categoryId,
+  productsIds,
+  pricingContext,
+  renderProduct: Card = ProductPreview,
+}: {
+  client: StorefrontClient
+  sortBy?: SortOptions
+  page: number
+  /** Filters by PRIMARY collection (`products.collection_id`) — for the
+   *  membership join use collection-template / `listCollectionProducts`. */
+  collectionId?: string
+  categoryId?: string
+  productsIds?: string[]
+  /** Pricing context so cards carry `calculated_price`. */
+  pricingContext?: PricingContextQuery
+  /** Override the default ProductPreview with a store-specific card. */
+  renderProduct?: ProductCardComponent
+}) {
+  const queryParams: ListProductsQuery = {
+    limit: PRODUCT_LIMIT,
+    ...pricingContext,
+  }
+
+  if (collectionId) queryParams.collection_id = [collectionId]
+  if (categoryId) queryParams.category_id = [categoryId]
+  if (productsIds) queryParams.id = productsIds
+
+  let products: StoreProduct[]
+  let count: number
+
+  if (sortBy === "price_asc" || sortBy === "price_desc") {
+    const res = await listProducts(client, {
+      ...queryParams,
+      limit: SORT_WINDOW,
+      offset: 0,
+    })
+    const sorted = sortProducts(res.products, sortBy)
+    const offset = (page - 1) * PRODUCT_LIMIT
+    products = sorted.slice(offset, offset + PRODUCT_LIMIT)
+    count = res.count
+  } else {
+    const res = await listProducts(client, {
+      ...queryParams,
+      order: "-created_at",
+      offset: (page - 1) * PRODUCT_LIMIT,
+    })
+    products = res.products
+    count = res.count
+  }
+
+  const totalPages = Math.ceil(count / PRODUCT_LIMIT)
+
+  return (
+    <>
+      <ul
+        className="grid grid-cols-2 w-full sm:grid-cols-3 md:grid-cols-4 gap-x-6 gap-y-8"
+        data-testid="products-list"
+      >
+        {products.map((p) => (
+          <li key={p.id}>
+            <Card product={p} />
+          </li>
+        ))}
+      </ul>
+      {totalPages > 1 && (
+        <Pagination
+          data-testid="product-pagination"
+          page={page}
+          totalPages={totalPages}
+        />
+      )}
+    </>
+  )
+}

package/src/store/pagination.tsx

@@ -0,0 +1,103 @@
+"use client"
+
+/**
+ * Page-number pagination — ported from `@1click/ui/src/store/pagination.tsx`
+ * (v2.3.1) unchanged. Writes the `page` query param and pushes the route;
+ * the server templates read it back and convert to `offset`. Windowed
+ * layout: ≤7 pages inline, otherwise ellipsis around the current window.
+ */
+import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { cn } from "../lib/utils"
+
+export function Pagination({
+  page,
+  totalPages,
+  "data-testid": dataTestid,
+}: {
+  page: number
+  totalPages: number
+  "data-testid"?: string
+}) {
+  const router = useRouter()
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+
+  const arrayRange = (start: number, stop: number) =>
+    Array.from({ length: stop - start + 1 }, (_, index) => start + index)
+
+  const handlePageChange = (newPage: number) => {
+    const params = new URLSearchParams(searchParams)
+    params.set("page", newPage.toString())
+    router.push(`${pathname}?${params.toString()}`)
+  }
+
+  const renderPageButton = (
+    p: number,
+    label: string | number,
+    isCurrent: boolean
+  ) => (
+    <button
+      key={p}
+      className={cn("text-xl text-muted-foreground", {
+        "text-foreground font-semibold": isCurrent,
+        "hover:text-muted-foreground": !isCurrent,
+      })}
+      disabled={isCurrent}
+      onClick={() => handlePageChange(p)}
+    >
+      {label}
+    </button>
+  )
+
+  const renderEllipsis = (key: string) => (
+    <span key={key} className="text-xl text-muted-foreground cursor-default">
+      ...
+    </span>
+  )
+
+  const renderPageButtons = () => {
+    const buttons: React.ReactNode[] = []
+
+    if (totalPages <= 7) {
+      buttons.push(
+        ...arrayRange(1, totalPages).map((p) =>
+          renderPageButton(p, p, p === page)
+        )
+      )
+    } else if (page <= 4) {
+      buttons.push(
+        ...arrayRange(1, 5).map((p) => renderPageButton(p, p, p === page))
+      )
+      buttons.push(renderEllipsis("e1"))
+      buttons.push(renderPageButton(totalPages, totalPages, false))
+    } else if (page >= totalPages - 3) {
+      buttons.push(renderPageButton(1, 1, false))
+      buttons.push(renderEllipsis("e2"))
+      buttons.push(
+        ...arrayRange(totalPages - 4, totalPages).map((p) =>
+          renderPageButton(p, p, p === page)
+        )
+      )
+    } else {
+      buttons.push(renderPageButton(1, 1, false))
+      buttons.push(renderEllipsis("e3"))
+      buttons.push(
+        ...arrayRange(page - 1, page + 1).map((p) =>
+          renderPageButton(p, p, p === page)
+        )
+      )
+      buttons.push(renderEllipsis("e4"))
+      buttons.push(renderPageButton(totalPages, totalPages, false))
+    }
+
+    return buttons
+  }
+
+  return (
+    <div className="flex justify-center w-full mt-12">
+      <div className="flex gap-3 items-end" data-testid={dataTestid}>
+        {renderPageButtons()}
+      </div>
+    </div>
+  )
+}