@cartbase/storefront 0.17.0 → 0.18.0

package/src/cart-drawer/labels.ts

@@ -1,123 +1,123 @@
-/**
- * Cart drawer labels — default English copy.
- *
- * Every user-facing string in the cart drawer comes from a `CartDrawerLabels`
- * object. Stores override strings by passing a partial labels object to
- * `CartDrawerProvider`. English is the baseline; stores wanting Bulgarian,
- * German, etc. pass their own translations.
- *
- * Ported from `@1click/ui/src/cart-drawer/labels.ts` (v2.3.1). Cartbase
- * additions: the summary-breakdown row labels (`discount`, `tax`, `paymentMethodFee`,
- * `giftCard`, `remainingToPay`) — the decorated cart carries
- * discount/tax/COD-fee/gift-card tender fields that the breakdown renders,
- * so the copy for those rows lives here too.
- */
-
-export type CartDrawerLabels = {
-  // Header
-  yourCart: string
-  item: string
-  items: string
-  closeCart: string
-
-  // Empty state
-  emptyCartTitle: string
-  emptyCartMessage: string
-  browseProducts: string
-
-  // Tiered progress
-  awayFromFreeShipping: string
-  allRewardsUnlocked: string
-
-  // Gift wrap / notes
-  addGiftWrap: string
-  giftNote: string
-  orderNote: string
-  giftNotePlaceholder: string
-  orderNotePlaceholder: string
-
-  // Rewards
-  estimatedRewardPoints: string
-
-  // Cross-sell
-  pairsWellWith: string
-  youllLoveThis: string
-  youMightAlsoLike: string
-  addToCart: string
-
-  // Summary / footer
-  subtotal: string
-  taxAndShipping: string
-  shipping: string
-  free: string
-  calculatedAtCheckout: string
-  total: string
-  secureCheckout: string
-  shippingAndTaxCalculatedAtCheckout: string
-
-  // Summary breakdown rows (Cartbase decorated-cart fields)
-  discount: string
-  tax: string
-  /** Fallback only — the server's `payment_method_fee_label` wins when present. */
-  paymentMethodFee: string
-  /** Prefix for an applied gift-card row; rendered as `<giftCard> ••1234`. */
-  giftCard: string
-  /** Label for `gift_card_remainder` — what the remainder provider charges. */
-  remainingToPay: string
-
-  // Continue shopping
-  continueShopping: string
-
-  // A11y / buttons
-  remove: string
-}
-
-export const defaultCartDrawerLabels: CartDrawerLabels = {
-  yourCart: "Your cart",
-  item: "item",
-  items: "items",
-  closeCart: "Close cart",
-
-  emptyCartTitle: "Your cart is empty",
-  emptyCartMessage: "You haven't added any products yet.",
-  browseProducts: "Browse products",
-
-  awayFromFreeShipping: "away from free shipping",
-  allRewardsUnlocked: "All rewards unlocked",
-
-  addGiftWrap: "Add gift wrapping",
-  giftNote: "Gift note",
-  orderNote: "Order note",
-  giftNotePlaceholder: "Add a personal message...",
-  orderNotePlaceholder: "Special instructions for this order...",
-
-  estimatedRewardPoints: "Estimated reward points",
-
-  pairsWellWith: "Pairs well with",
-  youllLoveThis: "You'll love this",
-  youMightAlsoLike: "You might also like",
-  addToCart: "Add",
-
-  subtotal: "Subtotal",
-  // Neutral and true on every store: it states WHEN the numbers are worked
-  // out, not which tax regime applies. It read "VAT included. Shipping
-  // calculated at checkout." until 2026-09-13, and the first half is false
-  // wherever tax is added at checkout instead of sitting in the price.
-  taxAndShipping: "Taxes and shipping calculated at checkout.",
-  shipping: "Shipping",
-  free: "FREE",
-  calculatedAtCheckout: "Calculated at checkout",
-  total: "Total",
-  secureCheckout: "Checkout",
-  shippingAndTaxCalculatedAtCheckout: "Shipping and tax calculated at checkout",
-
-  discount: "Discount",
-  tax: "VAT",
-  paymentMethodFee: "Payment method fee",
-  giftCard: "Gift card",
-  remainingToPay: "Remaining to pay",
-
-  continueShopping: "Continue shopping",
-
-  remove: "Remove",
-}
+/**
+ * Cart drawer labels — default English copy.
+ *
+ * Every user-facing string in the cart drawer comes from a `CartDrawerLabels`
+ * object. Stores override strings by passing a partial labels object to
+ * `CartDrawerProvider`. English is the baseline; stores wanting Bulgarian,
+ * German, etc. pass their own translations.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/labels.ts` (v2.3.1). Cartbase
+ * additions: the summary-breakdown row labels (`discount`, `tax`, `paymentMethodFee`,
+ * `giftCard`, `remainingToPay`) — the decorated cart carries
+ * discount/tax/COD-fee/gift-card tender fields that the breakdown renders,
+ * so the copy for those rows lives here too.
+ */
+
+export type CartDrawerLabels = {
+  // Header
+  yourCart: string
+  item: string
+  items: string
+  closeCart: string
+
+  // Empty state
+  emptyCartTitle: string
+  emptyCartMessage: string
+  browseProducts: string
+
+  // Tiered progress
+  awayFromFreeShipping: string
+  allRewardsUnlocked: string
+
+  // Gift wrap / notes
+  addGiftWrap: string
+  giftNote: string
+  orderNote: string
+  giftNotePlaceholder: string
+  orderNotePlaceholder: string
+
+  // Rewards
+  estimatedRewardPoints: string
+
+  // Cross-sell
+  pairsWellWith: string
+  youllLoveThis: string
+  youMightAlsoLike: string
+  addToCart: string
+
+  // Summary / footer
+  subtotal: string
+  taxAndShipping: string
+  shipping: string
+  free: string
+  calculatedAtCheckout: string
+  total: string
+  secureCheckout: string
+  shippingAndTaxCalculatedAtCheckout: string
+
+  // Summary breakdown rows (Cartbase decorated-cart fields)
+  discount: string
+  tax: string
+  /** Fallback only — the server's `payment_method_fee_label` wins when present. */
+  paymentMethodFee: string
+  /** Prefix for an applied gift-card row; rendered as `<giftCard> ••1234`. */
+  giftCard: string
+  /** Label for `gift_card_remainder` — what the remainder provider charges. */
+  remainingToPay: string
+
+  // Continue shopping
+  continueShopping: string
+
+  // A11y / buttons
+  remove: string
+}
+
+export const defaultCartDrawerLabels: CartDrawerLabels = {
+  yourCart: "Your cart",
+  item: "item",
+  items: "items",
+  closeCart: "Close cart",
+
+  emptyCartTitle: "Your cart is empty",
+  emptyCartMessage: "You haven't added any products yet.",
+  browseProducts: "Browse products",
+
+  awayFromFreeShipping: "away from free shipping",
+  allRewardsUnlocked: "All rewards unlocked",
+
+  addGiftWrap: "Add gift wrapping",
+  giftNote: "Gift note",
+  orderNote: "Order note",
+  giftNotePlaceholder: "Add a personal message...",
+  orderNotePlaceholder: "Special instructions for this order...",
+
+  estimatedRewardPoints: "Estimated reward points",
+
+  pairsWellWith: "Pairs well with",
+  youllLoveThis: "You'll love this",
+  youMightAlsoLike: "You might also like",
+  addToCart: "Add",
+
+  subtotal: "Subtotal",
+  // Neutral and true on every store: it states WHEN the numbers are worked
+  // out, not which tax regime applies. It read "VAT included. Shipping
+  // calculated at checkout." until 2026-09-13, and the first half is false
+  // wherever tax is added at checkout instead of sitting in the price.
+  taxAndShipping: "Taxes and shipping calculated at checkout.",
+  shipping: "Shipping",
+  free: "FREE",
+  calculatedAtCheckout: "Calculated at checkout",
+  total: "Total",
+  secureCheckout: "Checkout",
+  shippingAndTaxCalculatedAtCheckout: "Shipping and tax calculated at checkout",
+
+  discount: "Discount",
+  tax: "VAT",
+  paymentMethodFee: "Payment method fee",
+  giftCard: "Gift card",
+  remainingToPay: "Remaining to pay",
+
+  continueShopping: "Continue shopping",
+
+  remove: "Remove",
+}

package/src/cart-drawer/mutation-queue.ts

@@ -0,0 +1,78 @@
+/**
+ * THE CART'S CHANGES, ONE AT A TIME (the instant cart, 2026-09-16).
+ *
+ * The drawer shows every change at once and the platform confirms behind
+ * it. The platform's answers are whole carts, so two changes in flight
+ * together can answer out of order and the older cart would overwrite the
+ * newer one; and a second add before the first has created the cart would
+ * create a second cart. So the provider sends its changes through this
+ * queue: one call at a time, each starting after the one before has
+ * answered, each reading the cart as the answers left it.
+ *
+ * Quantity clicks on one line are combined: while a change for a line waits
+ * its turn, a new click only moves the number it will send, so ten fast
+ * clicks send at most two calls (the one already in flight and the last
+ * number). Pure module, no React.
+ */
+
+export interface CartMutationQueue {
+  /** Run a change after every change before it has answered. A failure never blocks the next. */
+  run<T>(job: () => Promise<T>): Promise<T>
+  /**
+   * A quantity change for one line. While an earlier change for the same
+   * line still waits its turn, only its number moves and its promise is
+   * returned; otherwise `send` is queued and called with the latest number
+   * when its turn comes.
+   */
+  quantity<T>(lineKey: string, quantity: number, send: (quantity: number) => Promise<T>): Promise<T>
+  /** A waiting quantity change for this line is dropped (the line is being removed). */
+  forget(lineKey: string): void
+  /** True while any change is queued or in flight. */
+  busy(): boolean
+}
+
+export function createCartMutationQueue(): CartMutationQueue {
+  let tail: Promise<unknown> = Promise.resolve()
+  let pending = 0
+  const waiting = new Map<string, { quantity: number; dropped: boolean; job: Promise<unknown> }>()
+
+  function run<T>(job: () => Promise<T>): Promise<T> {
+    pending++
+    const result = tail.then(job, job)
+    const settled = result.then(
+      () => undefined,
+      () => undefined
+    )
+    tail = settled
+    void settled.then(() => {
+      pending--
+    })
+    return result
+  }
+
+  function quantity<T>(lineKey: string, quantity: number, send: (quantity: number) => Promise<T>): Promise<T> {
+    const queued = waiting.get(lineKey)
+    if (queued && !queued.dropped) {
+      queued.quantity = quantity
+      return queued.job as Promise<T>
+    }
+    const entry = { quantity, dropped: false, job: Promise.resolve() as Promise<unknown> }
+    entry.job = run(async () => {
+      // The turn has come: later clicks start a new change from here on.
+      if (waiting.get(lineKey) === entry) waiting.delete(lineKey)
+      if (entry.dropped) return undefined as T
+      return send(entry.quantity)
+    })
+    waiting.set(lineKey, entry)
+    return entry.job as Promise<T>
+  }
+
+  function forget(lineKey: string): void {
+    const queued = waiting.get(lineKey)
+    if (!queued) return
+    queued.dropped = true
+    waiting.delete(lineKey)
+  }
+
+  return { run, quantity, forget, busy: () => pending > 0 }
+}

package/src/cart-drawer/notes.tsx

@@ -1,131 +1,131 @@
-"use client"
-
-import { useState } from "react"
-
-import { cn } from "../lib/utils"
-import { useCartDrawer } from "./context"
-
-/**
- * CartNotes — pill buttons to open gift/order note textareas.
- *
- * Ported from `@1click/ui/src/cart-drawer/notes.tsx` (v2.3.1);
- * originally extracted from mindpages-storefront
- * src/modules/cart-drawer/cart-notes.tsx. Tokens applied. Icons +
- * placeholders pulled from `labels` context. Persist notes via `onSave`
- * — e.g. `updateCart(client, cartId, { metadata: { ...cart.metadata,
- * gift_note: value } })` (`@cartbase/storefront/api/carts`). NOTE: the update
- * route REPLACES the metadata object wholesale (no server-side merge) —
- * always spread the current `cart.metadata` or you clobber other keys
- * (UTM attribution, gift-wrap flags…). Cart metadata is copied onto the
- * order at complete.
- */
-
-type NoteType = "gift" | "order"
-
-type CartNotesProps = {
-  types?: NoteType[]
-  onSave?: (type: NoteType, value: string) => void
-}
-
-const iconGift = (
-  <svg
-    width="14"
-    height="14"
-    viewBox="0 0 14 14"
-    fill="none"
-    stroke="currentColor"
-    strokeWidth="1.3"
-    strokeLinecap="round"
-    strokeLinejoin="round"
-  >
-    <rect x="1.5" y="5" width="11" height="7.5" rx="1" />
-    <rect x="0.5" y="3" width="13" height="2.5" rx="0.5" />
-    <path d="M7 3v9.5" />
-  </svg>
-)
-
-const iconOrder = (
-  <svg
-    width="14"
-    height="14"
-    viewBox="0 0 14 14"
-    fill="none"
-    stroke="currentColor"
-    strokeWidth="1.3"
-    strokeLinecap="round"
-    strokeLinejoin="round"
-  >
-    <path d="M8.5 1.5H4a1 1 0 00-1 1v9a1 1 0 001 1h6a1 1 0 001-1V4L8.5 1.5z" />
-    <path d="M8.5 1.5V4H11M5.5 7h3M5.5 9.5h3" />
-  </svg>
-)
-
-export function CartNotes({
-  types = ["gift", "order"],
-  onSave,
-}: CartNotesProps) {
-  const { labels } = useCartDrawer()
-  const [activeNote, setActiveNote] = useState<NoteType | null>(null)
-  const [values, setValues] = useState<Record<NoteType, string>>({
-    gift: "",
-    order: "",
-  })
-
-  const noteConfig: Record<
-    NoteType,
-    { label: string; placeholder: string; icon: React.ReactNode }
-  > = {
-    gift: {
-      label: labels.giftNote,
-      placeholder: labels.giftNotePlaceholder,
-      icon: iconGift,
-    },
-    order: {
-      label: labels.orderNote,
-      placeholder: labels.orderNotePlaceholder,
-      icon: iconOrder,
-    },
-  }
-
-  return (
-    <div className="px-5 sm:px-6 py-3">
-      <div className="flex gap-2">
-        {types.map((type) => {
-          const config = noteConfig[type]
-          const active = activeNote === type
-          return (
-            <button
-              key={type}
-              type="button"
-              onClick={() => setActiveNote(active ? null : type)}
-              className={cn(
-                "flex items-center gap-1.5 text-xs font-medium px-4 py-2.5 min-h-[44px] rounded-xl border transition-colors active:scale-[0.97]",
-                active
-                  ? "border-text-base bg-foreground text-card"
-                  : "border-border text-muted-foreground hover:border-text-muted active:bg-muted"
-              )}
-            >
-              {config.icon}
-              {config.label}
-            </button>
-          )
-        })}
-      </div>
-
-      {activeNote && (
-        <div className="mt-3">
-          <textarea
-            value={values[activeNote]}
-            onChange={(e) =>
-              setValues({ ...values, [activeNote]: e.target.value })
-            }
-            onBlur={() => onSave?.(activeNote, values[activeNote])}
-            placeholder={noteConfig[activeNote].placeholder}
-            rows={3}
-            className="w-full text-[14px] sm:text-sm border border-border rounded-xl px-4 py-3 resize-none focus:outline-none focus:ring-2 focus:ring-primary/20 focus:border-primary placeholder:text-muted-foreground text-foreground bg-card"
-          />
-        </div>
-      )}
-    </div>
-  )
-}
+"use client"
+
+import { useState } from "react"
+
+import { cn } from "../lib/utils"
+import { useCartDrawer } from "./context"
+
+/**
+ * CartNotes — pill buttons to open gift/order note textareas.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/notes.tsx` (v2.3.1);
+ * originally extracted from mindpages-storefront
+ * src/modules/cart-drawer/cart-notes.tsx. Tokens applied. Icons +
+ * placeholders pulled from `labels` context. Persist notes via `onSave`
+ * — e.g. `updateCart(client, cartId, { metadata: { ...cart.metadata,
+ * gift_note: value } })` (`@cartbase/storefront/api/carts`). NOTE: the update
+ * route REPLACES the metadata object wholesale (no server-side merge) —
+ * always spread the current `cart.metadata` or you clobber other keys
+ * (UTM attribution, gift-wrap flags…). Cart metadata is copied onto the
+ * order at complete.
+ */
+
+type NoteType = "gift" | "order"
+
+type CartNotesProps = {
+  types?: NoteType[]
+  onSave?: (type: NoteType, value: string) => void
+}
+
+const iconGift = (
+  <svg
+    width="14"
+    height="14"
+    viewBox="0 0 14 14"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.3"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <rect x="1.5" y="5" width="11" height="7.5" rx="1" />
+    <rect x="0.5" y="3" width="13" height="2.5" rx="0.5" />
+    <path d="M7 3v9.5" />
+  </svg>
+)
+
+const iconOrder = (
+  <svg
+    width="14"
+    height="14"
+    viewBox="0 0 14 14"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.3"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M8.5 1.5H4a1 1 0 00-1 1v9a1 1 0 001 1h6a1 1 0 001-1V4L8.5 1.5z" />
+    <path d="M8.5 1.5V4H11M5.5 7h3M5.5 9.5h3" />
+  </svg>
+)
+
+export function CartNotes({
+  types = ["gift", "order"],
+  onSave,
+}: CartNotesProps) {
+  const { labels } = useCartDrawer()
+  const [activeNote, setActiveNote] = useState<NoteType | null>(null)
+  const [values, setValues] = useState<Record<NoteType, string>>({
+    gift: "",
+    order: "",
+  })
+
+  const noteConfig: Record<
+    NoteType,
+    { label: string; placeholder: string; icon: React.ReactNode }
+  > = {
+    gift: {
+      label: labels.giftNote,
+      placeholder: labels.giftNotePlaceholder,
+      icon: iconGift,
+    },
+    order: {
+      label: labels.orderNote,
+      placeholder: labels.orderNotePlaceholder,
+      icon: iconOrder,
+    },
+  }
+
+  return (
+    <div className="px-5 sm:px-6 py-3">
+      <div className="flex gap-2">
+        {types.map((type) => {
+          const config = noteConfig[type]
+          const active = activeNote === type
+          return (
+            <button
+              key={type}
+              type="button"
+              onClick={() => setActiveNote(active ? null : type)}
+              className={cn(
+                "flex items-center gap-1.5 text-xs font-medium px-4 py-2.5 min-h-[44px] rounded-xl border transition-colors active:scale-[0.97]",
+                active
+                  ? "border-text-base bg-foreground text-card"
+                  : "border-border text-muted-foreground hover:border-text-muted active:bg-muted"
+              )}
+            >
+              {config.icon}
+              {config.label}
+            </button>
+          )
+        })}
+      </div>
+
+      {activeNote && (
+        <div className="mt-3">
+          <textarea
+            value={values[activeNote]}
+            onChange={(e) =>
+              setValues({ ...values, [activeNote]: e.target.value })
+            }
+            onBlur={() => onSave?.(activeNote, values[activeNote])}
+            placeholder={noteConfig[activeNote].placeholder}
+            rows={3}
+            className="w-full text-[14px] sm:text-sm border border-border rounded-xl px-4 py-3 resize-none focus:outline-none focus:ring-2 focus:ring-primary/20 focus:border-primary placeholder:text-muted-foreground text-foreground bg-card"
+          />
+        </div>
+      )}
+    </div>
+  )
+}