@cartbase/storefront 0.20.1 → 0.22.0

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,372 @@
+"use client"
+
+import { useCallback, useEffect, useMemo, useState } from "react"
+
+import type { StorefrontClient } from "../api/http"
+import {
+  listPickupPoints,
+  type PickupPointKeys,
+  type StorePickupPoint,
+} from "../api/integrations"
+import { cn } from "../lib/utils"
+import { distanceMeters, formatDistance, geocodeAddress } from "./geocode"
+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.
+ *
+ * WHERE THE SEARCH HAPPENS is the platform's business, not this component's.
+ * Carriers that search (Speedy, Pigeon) are asked; carriers that publish a
+ * whole catalogue (Econt, BoxNow) are held per store and ranked there. This
+ * component types into one query parameter either way, which is why it can
+ * afford to be one component.
+ *
+ * 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 NEAREST_COUNT = 3
+const SEARCH_RESULTS = 8
+const MIN_SEARCH_CHARS = 2
+
+export function PickupPointSelector({
+  client,
+  provider,
+  mode,
+  userCity,
+  userAddress,
+  selectedPoint,
+  onSelect,
+}: PickupPointSelectorProps) {
+  const labels = useCheckoutLabels()
+  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 [searchResults, setSearchResults] = useState<PickupPoint[]>([])
+  const [showSearch, setShowSearch] = useState(false)
+  const [loading, setLoading] = useState(true)
+  const [failed, setFailed] = useState(false)
+
+  // The nearby set: the carrier's own answer for the typed town, plus the
+  // shopper's coordinates, asked for together. The town is the query because
+  // a catalogue of every office in the country ranked by distance to Sofia is
+  // a slower way to reach the same three rows.
+  useEffect(() => {
+    let alive = true
+    setLoading(true)
+    setFailed(false)
+    Promise.all([
+      listPickupPoints(client, provider, { mode, q: userCity, limit: 50 }).catch(
+        () => null
+      ),
+      userCity && userAddress
+        ? geocodeAddress(userCity, userAddress).catch(() => null)
+        : Promise.resolve(null),
+    ]).then(([answer, position]) => {
+      if (!alive) return
+      if (!answer) {
+        setFailed(true)
+        setPoints([])
+      } else {
+        setPoints(answer.points)
+        setKeys(answer.keys)
+      }
+      setCoords(position)
+      setLoading(false)
+    })
+    return () => {
+      alive = false
+    }
+  }, [client, provider, mode, userCity, userAddress])
+
+  const nearest = useMemo(() => {
+    if (!points.length) return []
+    if (coords) {
+      const withCoords = points.filter(
+        (p) => p.latitude !== null && p.longitude !== null
+      )
+      if (withCoords.length) {
+        return withCoords
+          .map((point) => ({
+            point,
+            distance: distanceMeters(
+              coords.lat,
+              coords.lng,
+              point.latitude!,
+              point.longitude!
+            ),
+          }))
+          .sort((a, b) => a.distance - b.distance)
+          .slice(0, NEAREST_COUNT)
+      }
+    }
+    // No position, or a carrier whose rows carry none: the first answers for
+    // the typed town, which the platform already ranked town-first.
+    return points.slice(0, NEAREST_COUNT).map((point) => ({ point, distance: 0 }))
+  }, [points, coords])
+
+  // Searching asks the store, because the carrier may be the one searching.
+  // Debounced, so a typed word is one call and not one per letter.
+  useEffect(() => {
+    const q = search.trim()
+    if (q.length < MIN_SEARCH_CHARS) {
+      setSearchResults([])
+      return
+    }
+    let alive = true
+    const timer = setTimeout(() => {
+      listPickupPoints(client, provider, { mode, q, limit: SEARCH_RESULTS })
+        .then((answer) => {
+          if (!alive) return
+          setSearchResults(answer.points)
+          setKeys(answer.keys)
+        })
+        .catch(() => {
+          if (alive) setSearchResults([])
+        })
+    }, 250)
+    return () => {
+      alive = false
+      clearTimeout(timer)
+    }
+  }, [search, client, provider, mode])
+
+  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, coords ? distance : null)
+            )}
+          </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>
+  )
+}