@cartbase/storefront 0.21.0 → 0.22.1

package/src/checkout/pickup-option.ts

@@ -0,0 +1,35 @@
+/**
+ * Does this shipping option deliver to a POINT, and to whose?
+ *
+ * Every carrier names its fulfillment options `<carrier>-<mode>`, because the
+ * platform's registry declares them that way and the same ids key the carrier
+ * marks and the order's own destination editor. So one reader answers for all
+ * of them, and a carrier connected tomorrow opens its picker with no line
+ * added anywhere.
+ *
+ * `address` is the door: there is no point to choose, so it answers null.
+ *
+ * This is the whole reason Speedy had no office picker until 2026-09-18. The
+ * checkout asked the question three times, once per carrier, as
+ * `id === "econt-office"`, `id === "boxnow-locker"`, `id === "pigeon-office"`,
+ * so a fourth carrier was invisible to it however well the platform served
+ * that carrier's catalogue.
+ */
+
+export type PickupOption = {
+  /** `econt`, `speedy`, `boxnow`, `pigeon`. */
+  provider: string
+  mode: "office" | "locker"
+}
+
+export function pickupOptionOf(
+  fulfillmentOptionId: string | null | undefined
+): PickupOption | null {
+  if (!fulfillmentOptionId) return null
+  const dash = fulfillmentOptionId.lastIndexOf("-")
+  if (dash <= 0) return null
+  const mode = fulfillmentOptionId.slice(dash + 1)
+  if (mode !== "office" && mode !== "locker") return null
+  const provider = fulfillmentOptionId.slice(0, dash)
+  return provider ? { provider, mode } : null
+}

package/src/checkout/pickup-point-selector.tsx

@@ -0,0 +1,328 @@
+"use client"
+
+import { useCallback, useContext, useEffect, useMemo, useState } from "react"
+
+import type { StorefrontClient } from "../api/http"
+import {
+  type PickupPointKeys,
+  type StorePickupPoint,
+} from "../api/integrations"
+import { cn } from "../lib/utils"
+import { formatDistance, geocodeAddress } from "./geocode"
+import { StorefrontLocaleContext } from "../locales/context"
+import { loadPickupPoints, nearestPickupPoints, pickupPointsInCity, searchPickupPoints } from "./pickup-points"
+import { useCheckoutLabels } from "./context"
+
+/**
+ * PickupPointSelector — ONE picker, every carrier.
+ *
+ * The shopper chose "to an office" or "to a locker"; this is where they say
+ * WHICH one. The shape is the one Alenika's checkout has carried since it was
+ * built, and the one this kit ported for Econt alone: the three nearest
+ * points to the address just typed, each with its distance, and a door to
+ * search the whole catalogue when none of them is the right one.
+ *
+ * WHY IT REPLACED THREE COMPONENTS (2026-09-18). The kit had a picker per
+ * carrier: Econt's fetched the carrier's own public catalogue straight from
+ * the browser, BoxNow's and Pigeon's each called a hand-written store route
+ * of their own, and Speedy had none at all, because Speedy's catalogue is
+ * credentialed and a browser can never ask for it. So a store could offer
+ * delivery to a Speedy office
+ * and give the shopper no way to name one. Every carrier is the same
+ * problem, so it is one component against one door
+ * (`GET /api/store/integrations/:provider/pickup-points`), and a carrier the
+ * platform connects tomorrow arrives with a working picker and no new code
+ * here.
+ *
+ * Like the Mindpages and Alenika pickers, load the COMPLETE eligible
+ * catalogue once, then rank and search locally. The platform adapter owns
+ * credentials, language and office/locker filtering. Never rank a capped
+ * town-search response: an omitted office can never become the nearest.
+ *
+ * NEAREST needs coordinates, and all four carriers publish them. The
+ * shopper's own position is geocoded from the city and street they typed
+ * (OpenStreetMap, `./geocode`), never from the device: a checkout that asks
+ * for location permission to show three addresses is a checkout people
+ * abandon. No address yet, or no geocode hit, and the list falls back to the
+ * points in the typed city, which is what a shopper would have scrolled to
+ * anyway.
+ */
+
+export type PickupPoint = StorePickupPoint
+
+type PickupPointSelectorProps = {
+  /** The SDK transport — the points come from the store, never the carrier. */
+  client: StorefrontClient
+  /** `econt`, `speedy`, `boxnow`, `pigeon`, from the shipping option. */
+  provider: string
+  /** Which kind of point this option delivers to. */
+  mode: "office" | "locker"
+  /** The address the shopper has typed so far, for "nearest to me". */
+  userCity: string
+  userAddress: string
+  selectedPoint: PickupPoint | null
+  /** Reports the choice, and the carrier's own key names beside it, so the
+   * checkout writes the point under the names this carrier's booking reads. */
+  onSelect: (point: PickupPoint | null, keys: PickupPointKeys | null) => void
+}
+
+const MIN_SEARCH_CHARS = 2
+
+export function PickupPointSelector({
+  client,
+  provider,
+  mode,
+  userCity,
+  userAddress,
+  selectedPoint,
+  onSelect,
+}: PickupPointSelectorProps) {
+  const labels = useCheckoutLabels()
+  const locale = useContext(StorefrontLocaleContext)?.code ?? "en"
+  const [points, setPoints] = useState<PickupPoint[]>([])
+  const [keys, setKeys] = useState<PickupPointKeys | null>(null)
+  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null)
+  const [search, setSearch] = useState("")
+  const [showSearch, setShowSearch] = useState(false)
+  const [loading, setLoading] = useState(true)
+  const [failed, setFailed] = useState(false)
+
+  // One complete catalogue per store/carrier/mode/language, shared across
+  // mounts. Address edits only geocode; they never reload the carrier list.
+  useEffect(() => {
+    let alive = true
+    setLoading(true)
+    setFailed(false)
+    setPoints([])
+    setKeys(null)
+    loadPickupPoints(client, provider, mode, locale).then((answer) => {
+      if (!alive) return
+      setPoints(answer.points.filter((point) => point.mode === mode))
+      setKeys(answer.keys)
+    }).catch(() => {
+      if (alive) setFailed(true)
+    }).finally(() => {
+      if (alive) setLoading(false)
+    })
+    return () => { alive = false }
+  }, [client, provider, mode, locale])
+
+  useEffect(() => {
+    let alive = true
+    setCoords(null)
+    const timer = setTimeout(() => {
+      if (userCity && userAddress) {
+        geocodeAddress(userCity, userAddress).then((position) => {
+          if (alive) setCoords(position)
+        }).catch(() => {})
+      }
+    }, 350)
+    return () => { alive = false; clearTimeout(timer) }
+  }, [userCity, userAddress])
+
+  // Alenika's BoxNow picker locks both nearest and search to the town.
+  // Econt (and the shared office pattern used for Speedy) searches all offices.
+  const eligiblePoints = useMemo(() => provider === "boxnow"
+    ? pickupPointsInCity(points, userCity) : points, [points, provider, userCity])
+  const nearest = useMemo(() => nearestPickupPoints(eligiblePoints, coords, userCity),
+    [eligiblePoints, coords, userCity])
+  const searchResults = useMemo(() => searchPickupPoints(eligiblePoints, search),
+    [eligiblePoints, search])
+
+  const choose = useCallback(
+    (point: PickupPoint | null) => {
+      onSelect(point, point ? keys : null)
+      setShowSearch(false)
+      setSearch("")
+    },
+    [onSelect, keys]
+  )
+
+  const renderPoint = useCallback(
+    (point: PickupPoint, distance: number | null) => (
+      <button
+        key={`${point.provider}-${point.id}`}
+        type="button"
+        onClick={() => choose(point)}
+        className={cn(
+          "flex items-start gap-3 w-full px-3.5 py-3 text-left transition-all duration-150 rounded-lg",
+          "bg-card hover:bg-muted"
+        )}
+      >
+        <div className="w-8 h-8 rounded-full bg-muted flex items-center justify-center flex-shrink-0 mt-0.5">
+          <svg
+            className="w-4 h-4 text-muted-foreground"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2}
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M15 10.5a3 3 0 11-6 0 3 3 0 016 0z"
+            />
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M19.5 10.5c0 7.142-7.5 11.25-7.5 11.25S4.5 17.642 4.5 10.5a7.5 7.5 0 1115 0z"
+            />
+          </svg>
+        </div>
+
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium text-foreground leading-tight">
+            {point.name}
+          </p>
+          <p className="text-xs text-muted-foreground mt-0.5">
+            {[point.address, point.city].filter(Boolean).join(", ")}
+          </p>
+        </div>
+
+        {distance !== null && distance > 0 && (
+          <span className="text-xs font-medium text-muted-foreground flex-shrink-0 mt-1">
+            {formatDistance(distance)}
+          </span>
+        )}
+      </button>
+    ),
+    [choose]
+  )
+
+  if (loading) {
+    return (
+      <div className="px-4 py-6 flex items-center justify-center">
+        <div className="w-5 h-5 border-2 border-border border-t-muted-foreground rounded-full animate-spin" />
+        <span className="ml-2 text-sm text-muted-foreground">
+          {labels.pickupLoading}
+        </span>
+      </div>
+    )
+  }
+
+  return (
+    <div className="px-4 pb-4 pt-2 space-y-3">
+      {selectedPoint && (
+        <div className="flex items-center gap-2 px-3 py-2 bg-primary/10 border border-primary/30 rounded-lg">
+          <svg
+            className="w-4 h-4 text-primary flex-shrink-0"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2}
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+            />
+          </svg>
+          <p className="text-sm font-medium text-primary">{selectedPoint.name}</p>
+          <button
+            type="button"
+            onClick={() => choose(null)}
+            className="ml-auto text-xs text-primary hover:underline"
+          >
+            {labels.pickupChange}
+          </button>
+        </div>
+      )}
+
+      {/* The carrier answered nothing: said plainly, with the search still
+          open, because a shopper who knows their office by name can find it
+          even when the town query came back empty. */}
+      {!selectedPoint && failed && (
+        <p className="text-sm text-muted-foreground">{labels.pickupUnavailable}</p>
+      )}
+
+      {!selectedPoint && !failed && nearest.length > 0 && (
+        <div>
+          <p className="text-xs font-medium text-muted-foreground uppercase tracking-wide mb-2">
+            {mode === "locker" ? labels.pickupNearestLockers : labels.pickupNearestOffices}
+          </p>
+          <div className="space-y-1.5">
+            {nearest.map(({ point, distance }) =>
+              renderPoint(point, distance)
+            )}
+          </div>
+        </div>
+      )}
+
+      {!selectedPoint && (
+        <div>
+          {!showSearch ? (
+            <button
+              type="button"
+              onClick={() => setShowSearch(true)}
+              className="flex items-center gap-2 text-sm text-muted-foreground hover:text-foreground transition-colors"
+            >
+              <svg
+                className="w-4 h-4"
+                fill="none"
+                viewBox="0 0 24 24"
+                stroke="currentColor"
+                strokeWidth={2}
+                aria-hidden="true"
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M21 21l-5.197-5.197m0 0A7.5 7.5 0 105.196 5.196a7.5 7.5 0 0010.607 10.607z"
+                />
+              </svg>
+              {mode === "locker"
+                ? labels.pickupSearchLocker
+                : labels.pickupSearchOffice}
+            </button>
+          ) : (
+            <div>
+              <div className="relative">
+                <svg
+                  className="absolute left-3 top-1/2 -translate-y-1/2 w-4 h-4 text-muted-foreground"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke="currentColor"
+                  strokeWidth={2}
+                  aria-hidden="true"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    d="M21 21l-5.197-5.197m0 0A7.5 7.5 0 105.196 5.196a7.5 7.5 0 0010.607 10.607z"
+                  />
+                </svg>
+                <input
+                  type="text"
+                  value={search}
+                  onChange={(e) => setSearch(e.target.value)}
+                  placeholder={
+                    mode === "locker"
+                      ? labels.pickupSearchLockerPlaceholder
+                      : labels.pickupSearchOfficePlaceholder
+                  }
+                  className="w-full h-10 pl-9 pr-3 text-sm rounded-lg border border-border bg-card focus:outline-none focus:ring-2 focus:ring-primary/20 focus:border-primary transition-all"
+                  autoFocus
+                />
+              </div>
+
+              {searchResults.length > 0 && (
+                <div className="mt-2 space-y-1 max-h-[240px] overflow-y-auto">
+                  {searchResults.map((point) => renderPoint(point, null))}
+                </div>
+              )}
+
+              {search.trim().length >= MIN_SEARCH_CHARS &&
+                searchResults.length === 0 && (
+                  <p className="mt-2 text-xs text-muted-foreground text-center py-3">
+                    {labels.pickupNoResults} &quot;{search}&quot;
+                  </p>
+                )}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/checkout/pickup-points.ts

@@ -0,0 +1,65 @@
+import type { StorefrontClient } from "../api/http"
+import { listPickupPoints, type PickupPointsResponse, type StorePickupPoint } from "../api/integrations"
+import { distanceMeters, normalizeForMatch } from "./geocode"
+
+// The reference pickers cache the full catalogue. Scope it to the SDK client
+// (the store), carrier, mode and language instead of sharing one global list.
+const catalogues = new WeakMap<StorefrontClient, Map<string, {
+  expires: number
+  promise: Promise<PickupPointsResponse>
+}>>()
+
+export function loadPickupPoints(
+  client: StorefrontClient,
+  provider: string,
+  mode: "office" | "locker",
+  locale: string
+): Promise<PickupPointsResponse> {
+  let cache = catalogues.get(client)
+  if (!cache) catalogues.set(client, cache = new Map())
+  const key = JSON.stringify([provider, mode, locale])
+  const hit = cache.get(key)
+  if (hit && hit.expires > Date.now()) return hit.promise
+  const promise = listPickupPoints(client, provider, { mode, catalogue: true, locale })
+    .catch((error) => {
+      if (cache.get(key)?.promise === promise) cache.delete(key)
+      throw error
+    })
+  cache.set(key, { expires: Date.now() + 10 * 60 * 1000, promise })
+  return promise
+}
+
+/** BoxNow's reference picker city-locks both lists, comparing both scripts. */
+export function pickupPointsInCity(points: StorePickupPoint[], city: string): StorePickupPoint[] {
+  const needle = normalizeForMatch(city.trim())
+  if (!needle) return points
+  return points.filter((point) => normalizeForMatch(point.city).includes(needle) ||
+    (point.provider === "boxnow" && normalizeForMatch(point.address).includes(needle)))
+}
+
+/** The reference's full catalogue → distance sort → nearest three, in that order. */
+export function nearestPickupPoints(
+  points: StorePickupPoint[],
+  position: { lat: number; lng: number } | null,
+  city: string
+): Array<{ point: StorePickupPoint; distance: number | null }> {
+  if (position && Number.isFinite(position.lat) && Number.isFinite(position.lng)) {
+    const located = points.filter((p) =>
+      p.latitude !== null && p.longitude !== null &&
+      Number.isFinite(p.latitude) && Number.isFinite(p.longitude)
+    )
+    if (located.length) return located.map((point) => ({ point,
+      distance: distanceMeters(position.lat, position.lng, point.latitude!, point.longitude!),
+    })).sort((a, b) => a.distance - b.distance).slice(0, 3)
+  }
+  return pickupPointsInCity(points, city).slice(0, 3).map((point) => ({ point, distance: null }))
+}
+
+/** The same catalogue powers search, including streets and either script. */
+export function searchPickupPoints(points: StorePickupPoint[], search: string): StorePickupPoint[] {
+  const needle = normalizeForMatch(search.trim())
+  if (needle.length < 2) return []
+  return points.filter((point) => normalizeForMatch(
+    [point.name, point.city, point.address, point.postal_code].join(" ")
+  ).includes(needle)).slice(0, 8)
+}