@cartbase/storefront 0.1.0

package/src/store/search-params.ts

@@ -0,0 +1,256 @@
+/**
+ * Search-template URL-state helpers — NEW in barter (no @1click source;
+ * pure module so the round-trip is unit-testable —
+ * tests/unit/storefront-catalog.test.ts).
+ *
+ * The search page keeps its whole filter state in the URL query string,
+ * using the SAME param names as the search endpoint's wire format
+ * (docs/storefront/search.md): `q`, CSV id filters (`collection_id`,
+ * `category_id`, `tag_id`, `type_id`), `price_min`/`price_max`,
+ * `availability`, dynamic `option.<Title>` CSV params — plus `page` (UI
+ * pagination, converted to `offset` when calling the SDK). Facet buckets
+ * toggle by rewriting these params (and resetting `page`).
+ */
+import type { SearchProductsQuery } from "../api/search"
+
+/** Parsed URL state of the search page. */
+export interface SearchPageState {
+  q: string
+  /** 1-based UI page (only serialized when > 1). */
+  page: number
+  collection_id: string[]
+  category_id: string[]
+  tag_id: string[]
+  type_id: string[]
+  price_min?: number
+  price_max?: number
+  availability?: "in_stock" | "out_of_stock"
+  /** Option title → selected values (`option.<Title>` params). */
+  options: Record<string, string[]>
+}
+
+/** Raw `searchParams` shape a Next.js page receives. */
+export type RawSearchParams = Record<string, string | string[] | undefined>
+
+const CSV_KEYS = ["collection_id", "category_id", "tag_id", "type_id"] as const
+
+function first(v: string | string[] | undefined): string | undefined {
+  if (Array.isArray(v)) return v[0]
+  return v
+}
+
+function parseCsv(v: string | string[] | undefined): string[] {
+  const raw = Array.isArray(v) ? v.join(",") : v
+  if (!raw) return []
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+}
+
+function parseNumber(v: string | string[] | undefined): number | undefined {
+  const s = first(v)
+  if (s === undefined || s === "") return undefined
+  const n = Number(s)
+  return Number.isFinite(n) ? n : undefined
+}
+
+/** Parse a Next.js `searchParams` record into the canonical page state. */
+export function parseSearchParams(params: RawSearchParams): SearchPageState {
+  const state: SearchPageState = {
+    q: first(params.q)?.trim() ?? "",
+    page: Math.max(1, Math.trunc(parseNumber(params.page) ?? 1)),
+    collection_id: parseCsv(params.collection_id),
+    category_id: parseCsv(params.category_id),
+    tag_id: parseCsv(params.tag_id),
+    type_id: parseCsv(params.type_id),
+    price_min: parseNumber(params.price_min),
+    price_max: parseNumber(params.price_max),
+    options: {},
+  }
+
+  const availability = first(params.availability)
+  if (availability === "in_stock" || availability === "out_of_stock") {
+    state.availability = availability
+  }
+
+  for (const [key, value] of Object.entries(params)) {
+    if (!key.startsWith("option.")) continue
+    const title = key.slice("option.".length)
+    if (!title) continue
+    const values = parseCsv(value)
+    if (values.length) state.options[title] = values
+  }
+
+  return state
+}
+
+/**
+ * Serialize the page state back to a query string (no leading `?`).
+ * Round-trip law: `parseSearchParams(fromQueryString(buildSearchQueryString(s)))`
+ * equals `s` for any normalized state. Empty/default fields are omitted so
+ * URLs stay canonical (page 1 has no `page` param).
+ */
+export function buildSearchQueryString(state: SearchPageState): string {
+  const sp = new URLSearchParams()
+  if (state.q) sp.set("q", state.q)
+  for (const key of CSV_KEYS) {
+    const values = state[key]
+    if (values.length) sp.set(key, values.join(","))
+  }
+  if (state.price_min !== undefined) sp.set("price_min", String(state.price_min))
+  if (state.price_max !== undefined) sp.set("price_max", String(state.price_max))
+  if (state.availability) sp.set("availability", state.availability)
+  for (const [title, values] of Object.entries(state.options)) {
+    if (values.length) sp.set(`option.${title}`, values.join(","))
+  }
+  if (state.page > 1) sp.set("page", String(state.page))
+  return sp.toString()
+}
+
+/** Convenience for tests + client code: query string → raw params record. */
+export function fromQueryString(qs: string): RawSearchParams {
+  const out: RawSearchParams = {}
+  for (const [key, value] of new URLSearchParams(qs)) {
+    out[key] = value
+  }
+  return out
+}
+
+/** The facet-bucket identity needed to toggle it (api/search shapes). */
+export interface FacetBucketRef {
+  /** Facet key: "price" | "availability" | "type" | "tags" | "collection" | "options.<Title>" */
+  facetKey: string
+  /** Bucket `value` (id, option value, availability enum, or "min-max"). */
+  value: string
+  /** Range (price) buckets only. */
+  min?: number
+  max?: number | null
+}
+
+/** True when the bucket is currently active in the state. */
+export function isFacetSelected(
+  state: SearchPageState,
+  bucket: FacetBucketRef
+): boolean {
+  const { facetKey, value } = bucket
+  switch (facetKey) {
+    case "collection":
+      return state.collection_id.includes(value)
+    case "type":
+      return state.type_id.includes(value)
+    case "tags":
+      return state.tag_id.includes(value)
+    case "availability":
+      return state.availability === value
+    case "price":
+      return (
+        state.price_min === (bucket.min ?? undefined) &&
+        state.price_max === (bucket.max ?? undefined)
+      )
+    default:
+      if (facetKey.startsWith("options.")) {
+        const title = facetKey.slice("options.".length)
+        return state.options[title]?.includes(value) ?? false
+      }
+      return false
+  }
+}
+
+function toggleInList(list: string[], value: string): string[] {
+  return list.includes(value)
+    ? list.filter((v) => v !== value)
+    : [...list, value]
+}
+
+/**
+ * Toggle a facet bucket on/off, returning the NEXT state (input untouched).
+ * Multi-value facets (collection/type/tags/options) toggle membership;
+ * single-value facets (availability, price range) select-or-clear. Every
+ * toggle resets `page` to 1 (the result set changed).
+ */
+export function toggleFacetSelection(
+  state: SearchPageState,
+  bucket: FacetBucketRef
+): SearchPageState {
+  const next: SearchPageState = {
+    ...state,
+    collection_id: [...state.collection_id],
+    category_id: [...state.category_id],
+    tag_id: [...state.tag_id],
+    type_id: [...state.type_id],
+    options: Object.fromEntries(
+      Object.entries(state.options).map(([k, v]) => [k, [...v]])
+    ),
+    page: 1,
+  }
+
+  const { facetKey, value } = bucket
+  if (facetKey === "collection") {
+    next.collection_id = toggleInList(next.collection_id, value)
+  } else if (facetKey === "type") {
+    next.type_id = toggleInList(next.type_id, value)
+  } else if (facetKey === "tags") {
+    next.tag_id = toggleInList(next.tag_id, value)
+  } else if (facetKey === "availability") {
+    next.availability =
+      state.availability === value
+        ? undefined
+        : (value as SearchPageState["availability"])
+  } else if (facetKey === "price") {
+    if (isFacetSelected(state, bucket)) {
+      next.price_min = undefined
+      next.price_max = undefined
+    } else {
+      next.price_min = bucket.min ?? undefined
+      next.price_max = bucket.max ?? undefined
+    }
+  } else if (facetKey.startsWith("options.")) {
+    const title = facetKey.slice("options.".length)
+    const values = toggleInList(next.options[title] ?? [], value)
+    if (values.length) {
+      next.options[title] = values
+    } else {
+      delete next.options[title]
+    }
+  }
+
+  return next
+}
+
+/** State with every filter cleared (query + page reset kept minimal). */
+export function clearFilters(state: SearchPageState): SearchPageState {
+  return {
+    q: state.q,
+    page: 1,
+    collection_id: [],
+    category_id: [],
+    tag_id: [],
+    type_id: [],
+    options: {},
+  }
+}
+
+/**
+ * Map the page state to the SDK query (`api/search` `searchProducts`).
+ * `page` becomes `offset`; empty filters are omitted.
+ */
+export function toSearchQuery(
+  state: SearchPageState,
+  limit: number
+): SearchProductsQuery {
+  const query: SearchProductsQuery = {
+    q: state.q,
+    limit,
+    offset: (state.page - 1) * limit,
+  }
+  if (state.collection_id.length) query.collection_id = state.collection_id
+  if (state.category_id.length) query.category_id = state.category_id
+  if (state.tag_id.length) query.tag_id = state.tag_id
+  if (state.type_id.length) query.type_id = state.type_id
+  if (state.price_min !== undefined) query.price_min = state.price_min
+  if (state.price_max !== undefined) query.price_max = state.price_max
+  if (state.availability) query.availability = state.availability
+  if (Object.keys(state.options).length) query.options = state.options
+  return query
+}

package/src/store/search-template.tsx

@@ -0,0 +1,249 @@
+/**
+ * Search results page — NEW in barter (no @1click source; the Medusa stores
+ * had no search endpoint). Built in the store-template idiom: filter
+ * sidebar, heading, product grid, pagination — over `api/search`
+ * `searchProducts` (docs/storefront/search.md).
+ *
+ * Everything is URL state (see ./search-params): the query box is a plain
+ * GET form and every facet bucket is a link that toggles its param — the
+ * whole page works server-rendered with zero client JS of its own (only
+ * `Pagination` is a client component). Facets arrive from the response
+ * (`facets[]` per the tenant's Settings → Search & discovery config):
+ * value buckets carry ids/option values, the price facet carries range
+ * buckets applied as `price_min`/`price_max`. Bucket counts follow the
+ * standard faceting rule (own dimension excluded), so selecting a value
+ * never zeroes its siblings.
+ *
+ * Async server component — give it the page's raw `searchParams`.
+ */
+import Link from "next/link"
+import type { StorefrontClient } from "../api/http"
+import type { PricingContextQuery } from "../api/types"
+import type { SearchFacet, SearchProductsResponse } from "../api/search"
+import { searchProducts } from "../api/search"
+import { cn } from "../lib/utils"
+import { Button } from "../primitives/ui/button"
+import { ProductPreview } from "../products/product-preview"
+import { defaultStoreLabels, type StoreLabels } from "./labels"
+import type { ProductCardComponent } from "./paginated-products"
+import { Pagination } from "./pagination"
+import {
+  buildSearchQueryString,
+  clearFilters,
+  isFacetSelected,
+  parseSearchParams,
+  toggleFacetSelection,
+  toSearchQuery,
+  type RawSearchParams,
+  type SearchPageState,
+} from "./search-params"
+
+const DEFAULT_LIMIT = 20
+
+type SearchTemplateProps = {
+  client: StorefrontClient
+  /** The page's raw `searchParams` (q, filters, page — see search-params). */
+  searchParams: RawSearchParams
+  /** Route the form + facet links target. Default `/search`. */
+  basePath?: string
+  /** Pricing context so result cards carry `calculated_price`. */
+  pricingContext?: PricingContextQuery
+  /** Page size, 1–100 (server default 20). */
+  limit?: number
+  labels?: Partial<StoreLabels>
+  /** Override the default ProductPreview with a store-specific card. */
+  renderProduct?: ProductCardComponent
+}
+
+export async function SearchTemplate({
+  client,
+  searchParams,
+  basePath = "/search",
+  pricingContext,
+  limit = DEFAULT_LIMIT,
+  labels,
+  renderProduct: Card = ProductPreview,
+}: SearchTemplateProps) {
+  const l = { ...defaultStoreLabels, ...labels }
+  const state = parseSearchParams(searchParams)
+
+  let response: SearchProductsResponse | null = null
+  if (state.q) {
+    response = await searchProducts(client, {
+      ...toSearchQuery(state, limit),
+      ...pricingContext,
+    })
+  }
+
+  const hasFilters =
+    state.collection_id.length > 0 ||
+    state.category_id.length > 0 ||
+    state.tag_id.length > 0 ||
+    state.type_id.length > 0 ||
+    state.price_min !== undefined ||
+    state.price_max !== undefined ||
+    state.availability !== undefined ||
+    Object.keys(state.options).length > 0
+
+  const totalPages = response ? Math.ceil(response.total / limit) : 0
+
+  return (
+    <div
+      className="flex flex-col sm:flex-row sm:items-start py-6 max-w-7xl mx-auto px-4"
+      data-testid="search-container"
+    >
+      <div className="flex flex-col gap-8 py-4 mb-8 sm:px-0 pl-6 sm:min-w-[250px] sm:max-w-[250px]">
+        <form method="get" action={basePath} className="flex flex-col gap-y-2">
+          <label
+            htmlFor="search-q"
+            className="text-sm font-medium text-muted-foreground"
+          >
+            {l.searchTitle}
+          </label>
+          <input
+            id="search-q"
+            type="search"
+            name="q"
+            defaultValue={state.q}
+            placeholder={l.searchPlaceholder}
+            className="h-10 rounded-lg border border-border bg-card px-3 text-sm text-foreground placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-primary"
+            data-testid="search-input"
+          />
+          <Button type="submit" className="h-10" data-testid="search-button">
+            {l.searchAction}
+          </Button>
+        </form>
+
+        {response && response.facets.length > 0 && (
+          <div className="flex flex-col gap-y-6" data-testid="search-facets">
+            <div className="flex items-center justify-between">
+              <span className="text-sm font-medium text-muted-foreground">
+                {l.filters}
+              </span>
+              {hasFilters && (
+                <Link
+                  href={`${basePath}?${buildSearchQueryString(clearFilters(state))}`}
+                  className="text-sm text-primary hover:underline"
+                  data-testid="clear-filters"
+                >
+                  {l.clearFilters}
+                </Link>
+              )}
+            </div>
+            {response.facets.map((facet) => (
+              <FacetGroup
+                key={facet.key}
+                facet={facet}
+                state={state}
+                basePath={basePath}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+
+      <div className="w-full">
+        <div className="mb-8">
+          {state.q ? (
+            <>
+              <h1
+                className="text-2xl font-semibold text-foreground"
+                data-testid="search-page-title"
+              >
+                {l.resultsFor} “{state.q}”
+              </h1>
+              {response && (
+                <p className="text-sm text-muted-foreground mt-1">
+                  {response.total} {l.resultsCount}
+                </p>
+              )}
+            </>
+          ) : (
+            <h1 className="text-2xl font-semibold text-foreground">
+              {l.searchTitle}
+            </h1>
+          )}
+        </div>
+
+        {response && response.results.length === 0 && (
+          <p className="text-muted-foreground" data-testid="no-results">
+            {l.noResults}
+          </p>
+        )}
+
+        {response && response.results.length > 0 && (
+          <>
+            <ul
+              className="grid grid-cols-2 w-full sm:grid-cols-3 md:grid-cols-4 gap-x-6 gap-y-8"
+              data-testid="search-results"
+            >
+              {response.results.map((p) => (
+                <li key={p.id}>
+                  <Card product={p} />
+                </li>
+              ))}
+            </ul>
+            {totalPages > 1 && (
+              <Pagination
+                data-testid="search-pagination"
+                page={state.page}
+                totalPages={totalPages}
+              />
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function FacetGroup({
+  facet,
+  state,
+  basePath,
+}: {
+  facet: SearchFacet
+  state: SearchPageState
+  basePath: string
+}) {
+  return (
+    <div className="flex flex-col gap-y-2">
+      <span className="text-sm font-medium text-muted-foreground">
+        {facet.label}
+      </span>
+      <ul className="flex flex-col gap-y-1">
+        {facet.buckets.map((bucket) => {
+          const ref = {
+            facetKey: facet.key,
+            value: bucket.value,
+            min: bucket.min,
+            max: bucket.max,
+          }
+          const selected = isFacetSelected(state, ref)
+          const href = `${basePath}?${buildSearchQueryString(
+            toggleFacetSelection(state, ref)
+          )}`
+          return (
+            <li key={bucket.value}>
+              <Link
+                href={href}
+                className={cn(
+                  "flex items-center justify-between text-sm px-2 py-1.5 rounded-md transition-colors",
+                  selected
+                    ? "text-foreground font-medium bg-muted"
+                    : "text-muted-foreground hover:text-foreground hover:bg-muted"
+                )}
+                data-testid="facet-bucket"
+              >
+                <span>{bucket.label}</span>
+                <span className="text-muted-foreground">{bucket.count}</span>
+              </Link>
+            </li>
+          )
+        })}
+      </ul>
+    </div>
+  )
+}
+
+export { type SearchTemplateProps }

package/src/store/skeleton-product-grid.tsx

@@ -0,0 +1,26 @@
+/**
+ * Loading skeleton for product grids — ported from
+ * `@1click/ui/src/store/skeleton-product-grid.tsx` (v2.3.1) unchanged.
+ * Server-safe; use as the `<Suspense>` fallback for the async listings.
+ */
+export function SkeletonProductGrid({
+  numberOfProducts = 8,
+}: {
+  numberOfProducts?: number
+}) {
+  return (
+    <ul className="grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 gap-x-6 gap-y-8">
+      {Array.from({ length: numberOfProducts }).map((_, i) => (
+        <li key={i}>
+          <div className="animate-pulse">
+            <div className="aspect-[9/16] w-full bg-muted rounded-lg" />
+            <div className="flex justify-between mt-4">
+              <div className="h-4 w-24 bg-muted rounded" />
+              <div className="h-4 w-16 bg-muted rounded" />
+            </div>
+          </div>
+        </li>
+      ))}
+    </ul>
+  )
+}

package/src/store/sort-select.tsx

@@ -0,0 +1,81 @@
+"use client"
+
+/**
+ * Listing sort selector — ported from
+ * `@1click/ui/src/store/sort-select.tsx` (v2.3.1). Writes the `sortBy`
+ * query param; the server templates map it to the API's `order` param
+ * (server truth for pagination — see paginated-products.tsx).
+ *
+ * Port adaptations: `sortBy` is now OPTIONAL — on collection pages no
+ * selection means "the collection's admin `default_sort`", so nothing is
+ * highlighted until the shopper picks an override. The option list renders
+ * from `sortOptionLabelKeys` (labels.ts, pure) so map completeness against
+ * `SortOptions` is unit-tested.
+ */
+import { usePathname, useRouter, useSearchParams } from "next/navigation"
+import { useCallback } from "react"
+import { cn } from "../lib/utils"
+import type { SortOptions } from "../lib/sort-products"
+import { defaultStoreLabels, sortOptionLabelKeys, type StoreLabels } from "./labels"
+
+type SortSelectProps = {
+  /** Current selection; undefined = server default (no highlight). */
+  sortBy?: SortOptions
+  labels?: Partial<
+    Pick<StoreLabels, "sortBy" | "latestArrivals" | "priceLowToHigh" | "priceHighToLow">
+  >
+  "data-testid"?: string
+}
+
+export function SortSelect({
+  sortBy,
+  labels,
+  "data-testid": dataTestId,
+}: SortSelectProps) {
+  const l = { ...defaultStoreLabels, ...labels }
+  const router = useRouter()
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+
+  const sortOptions = (
+    Object.keys(sortOptionLabelKeys) as SortOptions[]
+  ).map((value) => ({ value, label: l[sortOptionLabelKeys[value]] }))
+
+  const createQueryString = useCallback(
+    (name: string, value: string) => {
+      const params = new URLSearchParams(searchParams)
+      params.set(name, value)
+      return params.toString()
+    },
+    [searchParams]
+  )
+
+  const handleChange = (value: SortOptions) => {
+    const query = createQueryString("sortBy", value)
+    router.push(`${pathname}?${query}`)
+  }
+
+  return (
+    <div className="flex flex-col gap-y-3" data-testid={dataTestId}>
+      <span className="text-sm font-medium text-muted-foreground">{l.sortBy}</span>
+      <div className="flex flex-col gap-y-1">
+        {sortOptions.map((option) => (
+          <button
+            key={option.value}
+            onClick={() => handleChange(option.value)}
+            className={cn(
+              "text-sm text-left px-2 py-1.5 rounded-md transition-colors",
+              option.value === sortBy
+                ? "text-foreground font-medium bg-muted"
+                : "text-muted-foreground hover:text-foreground hover:bg-muted"
+            )}
+          >
+            {option.label}
+          </button>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export { type SortSelectProps }

package/src/store/store-template.tsx

@@ -0,0 +1,65 @@
+/**
+ * "/store" all-products page — ported from
+ * `@1click/ui/src/store/store-template.tsx` (v2.3.1). Data seam:
+ * `countryCode` → `client` + `pricingContext` (see paginated-products.tsx).
+ * Layout — sort sidebar, heading, suspended grid — unchanged.
+ */
+import { Suspense } from "react"
+import type { StorefrontClient } from "../api/http"
+import type { PricingContextQuery } from "../api/types"
+import type { SortOptions } from "../lib/sort-products"
+import { defaultStoreLabels, type StoreLabels } from "./labels"
+import { SortSelect } from "./sort-select"
+import { PaginatedProducts, type ProductCardComponent } from "./paginated-products"
+import { SkeletonProductGrid } from "./skeleton-product-grid"
+
+type StoreTemplateProps = {
+  client: StorefrontClient
+  /** From the `sortBy` query param. */
+  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 StoreTemplate({
+  client,
+  sortBy,
+  page,
+  pricingContext,
+  labels,
+  renderProduct,
+}: StoreTemplateProps) {
+  const l = { ...defaultStoreLabels, ...labels }
+  const pageNumber = page ? parseInt(page) : 1
+  const sort = sortBy || "created_at"
+
+  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={sort} labels={l} />
+      </div>
+      <div className="w-full">
+        <div className="mb-8">
+          <h1 className="text-2xl font-semibold text-foreground">
+            {l.allProducts}
+          </h1>
+        </div>
+        <Suspense fallback={<SkeletonProductGrid />}>
+          <PaginatedProducts
+            client={client}
+            sortBy={sort}
+            page={pageNumber}
+            pricingContext={pricingContext}
+            renderProduct={renderProduct}
+          />
+        </Suspense>
+      </div>
+    </div>
+  )
+}
+
+export { type StoreTemplateProps }