@reblu/site-next 1.13.0 → 1.15.0

package/dist/cart.d.cts

@@ -0,0 +1,169 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as zustand_middleware from 'zustand/middleware';
+import * as zustand from 'zustand';
+
+/**
+ * `CartProvider` — mount this once near the root layout (inside a Client
+ * Component boundary). It owns the ONE explicit-hydration call
+ * `useCartStore.persist.rehydrate()` requires (`store.ts`'s `skipHydration`
+ * doc) — a SITE that forgets to mount it gets an always-empty cart that never
+ * reads back whatever a previous visit (or page reload) persisted.
+ */
+declare function CartProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * `useCartStore` — the SDK's cart state (REB-829). Ported verbatim (same
+ * shape, same quantity-clamping rules) from demo-site's local
+ * `lib/store/cart-store.ts`, which every SITE was otherwise expected to
+ * hand-copy. `CART_STORAGE_KEY` stays exactly `'shop-cart'` on purpose: a
+ * SITE migrating from the local copy keeps its visitors' existing carts.
+ *
+ * `skipHydration: true` (zustand persist) is load-bearing for SSR: without
+ * it, zustand's persist middleware reads `localStorage` synchronously during
+ * module evaluation, which throws (or silently desyncs) on the server. The
+ * `CartProvider` (`./provider`) calls `useCartStore.persist.rehydrate()`
+ * inside a `useEffect`, so hydration only ever happens client-side, after
+ * mount — the same explicit-hydration contract the SITE README documents.
+ */
+declare const CART_STORAGE_KEY = "shop-cart";
+/**
+ * The zustand `persist` schema version for the cart's PERSISTED shape (the
+ * `CartItem[]` written to `localStorage` under `CART_STORAGE_KEY`) — bump
+ * this (with a `migrate` option) if that shape ever changes incompatibly.
+ * Also folded into {@link CART_STORE_GLOBAL_KEY} (REB-837 review fix): a
+ * future incompatible shape change should mint a NEW global singleton
+ * rather than let a stale, already-evaluated old-shape instance (e.g. kept
+ * alive across an HMR reload in dev) silently satisfy the new one.
+ */
+declare const CART_STORE_PERSIST_VERSION = 0;
+interface CartItem {
+    productId: string;
+    variantId?: string | null;
+    name: string;
+    variantName?: string;
+    /** Integer cents — every Reblu shop price travels as cents, never a float. */
+    unitPrice: number;
+    quantity: number;
+    imageUrl?: string;
+    /** `null` means untracked/unlimited stock — never clamp against it. */
+    maxStock: number | null;
+    /** Basis points, e.g. `2100` = 21%. `null`/`undefined` = unknown or exempt. */
+    taxRateBps?: number | null;
+    taxRateName?: string | null;
+}
+/**
+ * Outcome of `addItem` (REB-837): a SITE's add-to-cart feedback (toast,
+ * `AddToCartButton`'s built-in confirmed/error state) needs to know what
+ * actually happened, not just fire-and-forget — `'clamped'` only differs
+ * from `'added'` in the RESULTING quantity reaching less than what was
+ * requested (capped by `maxStock`); `'refused'` means nothing changed
+ * (invalid quantity, or the product is out of stock).
+ */
+type AddItemStatus = 'added' | 'clamped' | 'refused';
+interface AddItemOutcome {
+    status: AddItemStatus;
+    /** The resulting line quantity after the call (`0` when refused and no line exists). */
+    quantity: number;
+}
+interface CartStore {
+    items: CartItem[];
+    addItem: (item: CartItem) => AddItemOutcome;
+    removeItem: (productId: string, variantId?: string | null) => void;
+    updateQuantity: (productId: string, variantId: string | null | undefined, quantity: number) => void;
+    clearCart: () => void;
+    getTotal: () => number;
+    getItemCount: () => number;
+}
+/**
+ * REB-837 cross-entry singleton guard — the mutation that caught it: a
+ * single test rendering `useShopOrderStatus` (the `./shop` tsup entry) and
+ * asserting on `useCartStore` (the `./cart` entry) saw the order resolve to
+ * `paid` but the cart stay non-empty. Root cause: `splitting: false` (R4,
+ * `tsup.config.ts`) bundles each entry standalone, so a plain relative
+ * import of this file from `./shop` INLINES a SEPARATE copy of this
+ * `create(...)` call — a second, disconnected store instance with its own
+ * state, not the one `@reblu/site-next/cart` consumers read. `clearCart()`
+ * from inside the hook silently cleared the WRONG store.
+ *
+ * `globalThis` keyed by a `Symbol.for(...)` (same registry entry regardless
+ * of which bundle's copy of this module evaluates it first) makes every
+ * entry that imports this file — however many times esbuild inlines it —
+ * resolve to the SAME store. Verified by mutation: removing this guard
+ * (reverting to a bare `export const useCartStore = create(...)`) turns
+ * `use-shop-order-status.test.ts`'s cart-clearing assertions red again once
+ * the hook is exercised through its OWN entry rather than imported directly
+ * within `cart`'s own test file (which never saw the bug, since it only
+ * ever touches ONE copy of this module).
+ */
+declare function createCartStore(): zustand.UseBoundStore<Omit<zustand.StoreApi<CartStore>, "setState" | "persist"> & {
+    setState(partial: CartStore | Partial<CartStore> | ((state: CartStore) => CartStore | Partial<CartStore>), replace?: false | undefined): unknown;
+    setState(state: CartStore | ((state: CartStore) => CartStore), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<zustand_middleware.PersistOptions<CartStore, CartStore, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: CartStore) => void) => () => void;
+        onFinishHydration: (fn: (state: CartStore) => void) => () => void;
+        getOptions: () => Partial<zustand_middleware.PersistOptions<CartStore, CartStore, unknown>>;
+    };
+}>;
+type CartStoreApi = ReturnType<typeof createCartStore>;
+declare const useCartStore: CartStoreApi;
+/**
+ * TEST-ONLY (REB-837 review fix). Clears the `globalThis`-keyed slot so the
+ * NEXT access to `useCartStore` — in THIS module instance — creates a fresh
+ * store. The singleton is intentionally shared process-wide; most tests
+ * should keep resetting STATE via `useCartStore.setState(...)` in
+ * `beforeEach`, not the instance itself. Reach for this only to prove
+ * something about the singleton mechanism (e.g. the cross-entry test in
+ * `tests/cart-store-cross-entry-singleton.test.ts`) — it does not and
+ * cannot affect an ALREADY-evaluated copy of this module inlined into a
+ * different tsup entry's bundle (each such copy owns its own `const
+ * globalForCartStore`/`CART_STORE_GLOBAL_KEY` closed over at that copy's
+ * own module-evaluation time, same as any other ES module binding).
+ */
+declare function __resetCartStoreForTests(): void;
+
+interface UseCartResult {
+    items: CartItem[];
+    /** Sum of every line's `unitPrice * quantity`, in integer cents. */
+    total: number;
+    /** Sum of every line's `quantity`. */
+    itemCount: number;
+    /**
+     * Whether `CartProvider`'s `persist.rehydrate()` has finished (REB-837).
+     * `false` on the server and on the very first client render — `items`
+     * (and therefore `itemCount`) jumps from `0` to whatever was persisted the
+     * instant hydration finishes, which is NOT a real "item added" event. A
+     * consumer driving `CartIcon`'s `bumpOnAdd` MUST gate the bump on this
+     * flag (see `CartIcon`'s own guard) or every page load with a non-empty
+     * cart bumps the badge once for free.
+     */
+    hydrated: boolean;
+    addItem: (item: CartItem) => AddItemOutcome;
+    removeItem: (productId: string, variantId?: string | null) => void;
+    updateQuantity: (productId: string, variantId: string | null | undefined, quantity: number) => void;
+    clearCart: () => void;
+}
+/**
+ * `useCartHydrated` — standalone so a SITE that only needs the flag (e.g. to
+ * gate its own effects) doesn't have to subscribe to the whole cart via
+ * `useCart()`.
+ */
+declare function useCartHydrated(): boolean;
+/**
+ * `useCart` — the ergonomic entry point for a SITE's cart UI: a single
+ * selector call that re-renders only on `items` changes, with `total`/
+ * `itemCount` derived inline (cheap — a plain `reduce` over a typically-small
+ * array) rather than via `useCartStore`'s own `getTotal`/`getItemCount`
+ * selectors, which are stable function references and would NOT trigger a
+ * re-render on their own. A SITE that wants raw store access (existing
+ * per-field selectors, e.g. `useCartStore((s) => s.addItem)`) can still
+ * import `useCartStore` directly — this hook doesn't replace it.
+ */
+declare function useCart(): UseCartResult;
+
+export { type AddItemOutcome, type AddItemStatus, CART_STORAGE_KEY, CART_STORE_PERSIST_VERSION, type CartItem, CartProvider, type CartStore, type UseCartResult, __resetCartStoreForTests, useCart, useCartHydrated, useCartStore };

package/dist/cart.d.ts

@@ -0,0 +1,169 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as zustand_middleware from 'zustand/middleware';
+import * as zustand from 'zustand';
+
+/**
+ * `CartProvider` — mount this once near the root layout (inside a Client
+ * Component boundary). It owns the ONE explicit-hydration call
+ * `useCartStore.persist.rehydrate()` requires (`store.ts`'s `skipHydration`
+ * doc) — a SITE that forgets to mount it gets an always-empty cart that never
+ * reads back whatever a previous visit (or page reload) persisted.
+ */
+declare function CartProvider({ children }: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+/**
+ * `useCartStore` — the SDK's cart state (REB-829). Ported verbatim (same
+ * shape, same quantity-clamping rules) from demo-site's local
+ * `lib/store/cart-store.ts`, which every SITE was otherwise expected to
+ * hand-copy. `CART_STORAGE_KEY` stays exactly `'shop-cart'` on purpose: a
+ * SITE migrating from the local copy keeps its visitors' existing carts.
+ *
+ * `skipHydration: true` (zustand persist) is load-bearing for SSR: without
+ * it, zustand's persist middleware reads `localStorage` synchronously during
+ * module evaluation, which throws (or silently desyncs) on the server. The
+ * `CartProvider` (`./provider`) calls `useCartStore.persist.rehydrate()`
+ * inside a `useEffect`, so hydration only ever happens client-side, after
+ * mount — the same explicit-hydration contract the SITE README documents.
+ */
+declare const CART_STORAGE_KEY = "shop-cart";
+/**
+ * The zustand `persist` schema version for the cart's PERSISTED shape (the
+ * `CartItem[]` written to `localStorage` under `CART_STORAGE_KEY`) — bump
+ * this (with a `migrate` option) if that shape ever changes incompatibly.
+ * Also folded into {@link CART_STORE_GLOBAL_KEY} (REB-837 review fix): a
+ * future incompatible shape change should mint a NEW global singleton
+ * rather than let a stale, already-evaluated old-shape instance (e.g. kept
+ * alive across an HMR reload in dev) silently satisfy the new one.
+ */
+declare const CART_STORE_PERSIST_VERSION = 0;
+interface CartItem {
+    productId: string;
+    variantId?: string | null;
+    name: string;
+    variantName?: string;
+    /** Integer cents — every Reblu shop price travels as cents, never a float. */
+    unitPrice: number;
+    quantity: number;
+    imageUrl?: string;
+    /** `null` means untracked/unlimited stock — never clamp against it. */
+    maxStock: number | null;
+    /** Basis points, e.g. `2100` = 21%. `null`/`undefined` = unknown or exempt. */
+    taxRateBps?: number | null;
+    taxRateName?: string | null;
+}
+/**
+ * Outcome of `addItem` (REB-837): a SITE's add-to-cart feedback (toast,
+ * `AddToCartButton`'s built-in confirmed/error state) needs to know what
+ * actually happened, not just fire-and-forget — `'clamped'` only differs
+ * from `'added'` in the RESULTING quantity reaching less than what was
+ * requested (capped by `maxStock`); `'refused'` means nothing changed
+ * (invalid quantity, or the product is out of stock).
+ */
+type AddItemStatus = 'added' | 'clamped' | 'refused';
+interface AddItemOutcome {
+    status: AddItemStatus;
+    /** The resulting line quantity after the call (`0` when refused and no line exists). */
+    quantity: number;
+}
+interface CartStore {
+    items: CartItem[];
+    addItem: (item: CartItem) => AddItemOutcome;
+    removeItem: (productId: string, variantId?: string | null) => void;
+    updateQuantity: (productId: string, variantId: string | null | undefined, quantity: number) => void;
+    clearCart: () => void;
+    getTotal: () => number;
+    getItemCount: () => number;
+}
+/**
+ * REB-837 cross-entry singleton guard — the mutation that caught it: a
+ * single test rendering `useShopOrderStatus` (the `./shop` tsup entry) and
+ * asserting on `useCartStore` (the `./cart` entry) saw the order resolve to
+ * `paid` but the cart stay non-empty. Root cause: `splitting: false` (R4,
+ * `tsup.config.ts`) bundles each entry standalone, so a plain relative
+ * import of this file from `./shop` INLINES a SEPARATE copy of this
+ * `create(...)` call — a second, disconnected store instance with its own
+ * state, not the one `@reblu/site-next/cart` consumers read. `clearCart()`
+ * from inside the hook silently cleared the WRONG store.
+ *
+ * `globalThis` keyed by a `Symbol.for(...)` (same registry entry regardless
+ * of which bundle's copy of this module evaluates it first) makes every
+ * entry that imports this file — however many times esbuild inlines it —
+ * resolve to the SAME store. Verified by mutation: removing this guard
+ * (reverting to a bare `export const useCartStore = create(...)`) turns
+ * `use-shop-order-status.test.ts`'s cart-clearing assertions red again once
+ * the hook is exercised through its OWN entry rather than imported directly
+ * within `cart`'s own test file (which never saw the bug, since it only
+ * ever touches ONE copy of this module).
+ */
+declare function createCartStore(): zustand.UseBoundStore<Omit<zustand.StoreApi<CartStore>, "setState" | "persist"> & {
+    setState(partial: CartStore | Partial<CartStore> | ((state: CartStore) => CartStore | Partial<CartStore>), replace?: false | undefined): unknown;
+    setState(state: CartStore | ((state: CartStore) => CartStore), replace: true): unknown;
+    persist: {
+        setOptions: (options: Partial<zustand_middleware.PersistOptions<CartStore, CartStore, unknown>>) => void;
+        clearStorage: () => void;
+        rehydrate: () => Promise<void> | void;
+        hasHydrated: () => boolean;
+        onHydrate: (fn: (state: CartStore) => void) => () => void;
+        onFinishHydration: (fn: (state: CartStore) => void) => () => void;
+        getOptions: () => Partial<zustand_middleware.PersistOptions<CartStore, CartStore, unknown>>;
+    };
+}>;
+type CartStoreApi = ReturnType<typeof createCartStore>;
+declare const useCartStore: CartStoreApi;
+/**
+ * TEST-ONLY (REB-837 review fix). Clears the `globalThis`-keyed slot so the
+ * NEXT access to `useCartStore` — in THIS module instance — creates a fresh
+ * store. The singleton is intentionally shared process-wide; most tests
+ * should keep resetting STATE via `useCartStore.setState(...)` in
+ * `beforeEach`, not the instance itself. Reach for this only to prove
+ * something about the singleton mechanism (e.g. the cross-entry test in
+ * `tests/cart-store-cross-entry-singleton.test.ts`) — it does not and
+ * cannot affect an ALREADY-evaluated copy of this module inlined into a
+ * different tsup entry's bundle (each such copy owns its own `const
+ * globalForCartStore`/`CART_STORE_GLOBAL_KEY` closed over at that copy's
+ * own module-evaluation time, same as any other ES module binding).
+ */
+declare function __resetCartStoreForTests(): void;
+
+interface UseCartResult {
+    items: CartItem[];
+    /** Sum of every line's `unitPrice * quantity`, in integer cents. */
+    total: number;
+    /** Sum of every line's `quantity`. */
+    itemCount: number;
+    /**
+     * Whether `CartProvider`'s `persist.rehydrate()` has finished (REB-837).
+     * `false` on the server and on the very first client render — `items`
+     * (and therefore `itemCount`) jumps from `0` to whatever was persisted the
+     * instant hydration finishes, which is NOT a real "item added" event. A
+     * consumer driving `CartIcon`'s `bumpOnAdd` MUST gate the bump on this
+     * flag (see `CartIcon`'s own guard) or every page load with a non-empty
+     * cart bumps the badge once for free.
+     */
+    hydrated: boolean;
+    addItem: (item: CartItem) => AddItemOutcome;
+    removeItem: (productId: string, variantId?: string | null) => void;
+    updateQuantity: (productId: string, variantId: string | null | undefined, quantity: number) => void;
+    clearCart: () => void;
+}
+/**
+ * `useCartHydrated` — standalone so a SITE that only needs the flag (e.g. to
+ * gate its own effects) doesn't have to subscribe to the whole cart via
+ * `useCart()`.
+ */
+declare function useCartHydrated(): boolean;
+/**
+ * `useCart` — the ergonomic entry point for a SITE's cart UI: a single
+ * selector call that re-renders only on `items` changes, with `total`/
+ * `itemCount` derived inline (cheap — a plain `reduce` over a typically-small
+ * array) rather than via `useCartStore`'s own `getTotal`/`getItemCount`
+ * selectors, which are stable function references and would NOT trigger a
+ * re-render on their own. A SITE that wants raw store access (existing
+ * per-field selectors, e.g. `useCartStore((s) => s.addItem)`) can still
+ * import `useCartStore` directly — this hook doesn't replace it.
+ */
+declare function useCart(): UseCartResult;
+
+export { type AddItemOutcome, type AddItemStatus, CART_STORAGE_KEY, CART_STORE_PERSIST_VERSION, type CartItem, CartProvider, type CartStore, type UseCartResult, __resetCartStoreForTests, useCart, useCartHydrated, useCartStore };

package/dist/cart.js

@@ -0,0 +1,148 @@
+"use client";
+
+// src/cart/provider.tsx
+import { useEffect } from "react";
+
+// src/cart/store.ts
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+var CART_STORAGE_KEY = "shop-cart";
+var CART_STORE_PERSIST_VERSION = 0;
+function isSameItem(a, productId, variantId) {
+  return a.productId === productId && (a.variantId ?? null) === (variantId ?? null);
+}
+function normalizeQuantity(quantity, maxStock) {
+  if (!Number.isFinite(quantity)) return 0;
+  const truncated = Math.trunc(quantity);
+  if (truncated < 1) return 0;
+  if (maxStock === null) return truncated;
+  const maxTruncated = Math.trunc(maxStock);
+  if (maxTruncated < 1) return 0;
+  return Math.min(truncated, maxTruncated);
+}
+function createCartStore() {
+  return create()(
+    persist(
+      (set, get) => ({
+        items: [],
+        addItem: (item) => {
+          let outcome = { status: "refused", quantity: 0 };
+          set((state) => {
+            const existing = state.items.find((i) => isSameItem(i, item.productId, item.variantId));
+            if (existing) {
+              if (item.maxStock !== null && Math.trunc(item.maxStock) < 1) {
+                outcome = { status: "refused", quantity: 0 };
+                return {
+                  items: state.items.filter((i) => !isSameItem(i, item.productId, item.variantId))
+                };
+              }
+              const requestedQty = existing.quantity + item.quantity;
+              const newQty = normalizeQuantity(requestedQty, item.maxStock);
+              if (newQty < 1) {
+                outcome = { status: "refused", quantity: existing.quantity };
+                return {};
+              }
+              outcome = {
+                status: newQty < requestedQty ? "clamped" : "added",
+                quantity: newQty
+              };
+              return {
+                items: state.items.map(
+                  (i) => isSameItem(i, item.productId, item.variantId) ? { ...i, quantity: newQty, maxStock: item.maxStock } : i
+                )
+              };
+            }
+            const qty = normalizeQuantity(item.quantity, item.maxStock);
+            if (qty < 1) {
+              outcome = { status: "refused", quantity: 0 };
+              return {};
+            }
+            outcome = { status: qty < item.quantity ? "clamped" : "added", quantity: qty };
+            return { items: [...state.items, { ...item, quantity: qty }] };
+          });
+          return outcome;
+        },
+        removeItem: (productId, variantId) => {
+          set((state) => ({
+            items: state.items.filter((i) => !isSameItem(i, productId, variantId))
+          }));
+        },
+        updateQuantity: (productId, variantId, quantity) => {
+          const existing = get().items.find((i) => isSameItem(i, productId, variantId));
+          if (!existing) return;
+          const newQty = normalizeQuantity(quantity, existing.maxStock);
+          if (newQty < 1) {
+            get().removeItem(productId, variantId);
+            return;
+          }
+          set((state) => ({
+            items: state.items.map(
+              (i) => isSameItem(i, productId, variantId) ? { ...i, quantity: newQty } : i
+            )
+          }));
+        },
+        clearCart: () => set({ items: [] }),
+        getTotal: () => get().items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0),
+        getItemCount: () => get().items.reduce((sum, item) => sum + item.quantity, 0)
+      }),
+      {
+        name: CART_STORAGE_KEY,
+        version: CART_STORE_PERSIST_VERSION,
+        skipHydration: true
+      }
+    )
+  );
+}
+var CART_STORE_GLOBAL_KEY = /* @__PURE__ */ Symbol.for(
+  `@reblu/site-next/cart-store@v${CART_STORE_PERSIST_VERSION}`
+);
+var globalForCartStore = globalThis;
+var useCartStore = globalForCartStore[CART_STORE_GLOBAL_KEY] ?? (globalForCartStore[CART_STORE_GLOBAL_KEY] = createCartStore());
+function __resetCartStoreForTests() {
+  delete globalForCartStore[CART_STORE_GLOBAL_KEY];
+}
+
+// src/cart/provider.tsx
+import { Fragment, jsx } from "react/jsx-runtime";
+function CartProvider({ children }) {
+  useEffect(() => {
+    useCartStore.persist.rehydrate();
+  }, []);
+  return /* @__PURE__ */ jsx(Fragment, { children });
+}
+
+// src/cart/use-cart.ts
+import { useSyncExternalStore } from "react";
+function subscribeHydration(onStoreChange) {
+  return useCartStore.persist.onFinishHydration(onStoreChange);
+}
+function getHydratedSnapshot() {
+  return useCartStore.persist.hasHydrated();
+}
+function getServerHydratedSnapshot() {
+  return false;
+}
+function useCartHydrated() {
+  return useSyncExternalStore(subscribeHydration, getHydratedSnapshot, getServerHydratedSnapshot);
+}
+function useCart() {
+  const items = useCartStore((s) => s.items);
+  const addItem = useCartStore((s) => s.addItem);
+  const removeItem = useCartStore((s) => s.removeItem);
+  const updateQuantity = useCartStore((s) => s.updateQuantity);
+  const clearCart = useCartStore((s) => s.clearCart);
+  const hydrated = useCartHydrated();
+  const total = items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0);
+  const itemCount = items.reduce((sum, item) => sum + item.quantity, 0);
+  return { items, total, itemCount, hydrated, addItem, removeItem, updateQuantity, clearCart };
+}
+export {
+  CART_STORAGE_KEY,
+  CART_STORE_PERSIST_VERSION,
+  CartProvider,
+  __resetCartStoreForTests,
+  useCart,
+  useCartHydrated,
+  useCartStore
+};
+//# sourceMappingURL=cart.js.map

package/dist/cart.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cart/provider.tsx","../src/cart/store.ts","../src/cart/use-cart.ts"],"sourcesContent":["'use client'\n\nimport { useEffect } from 'react'\nimport { useCartStore } from './store'\n\n/**\n * `CartProvider` — mount this once near the root layout (inside a Client\n * Component boundary). It owns the ONE explicit-hydration call\n * `useCartStore.persist.rehydrate()` requires (`store.ts`'s `skipHydration`\n * doc) — a SITE that forgets to mount it gets an always-empty cart that never\n * reads back whatever a previous visit (or page reload) persisted.\n */\nexport function CartProvider({ children }: { children: React.ReactNode }) {\n  useEffect(() => {\n    useCartStore.persist.rehydrate()\n  }, [])\n\n  return <>{children}</>\n}\n","import { create } from 'zustand'\nimport { persist } from 'zustand/middleware'\n\n/**\n * `useCartStore` — the SDK's cart state (REB-829). Ported verbatim (same\n * shape, same quantity-clamping rules) from demo-site's local\n * `lib/store/cart-store.ts`, which every SITE was otherwise expected to\n * hand-copy. `CART_STORAGE_KEY` stays exactly `'shop-cart'` on purpose: a\n * SITE migrating from the local copy keeps its visitors' existing carts.\n *\n * `skipHydration: true` (zustand persist) is load-bearing for SSR: without\n * it, zustand's persist middleware reads `localStorage` synchronously during\n * module evaluation, which throws (or silently desyncs) on the server. The\n * `CartProvider` (`./provider`) calls `useCartStore.persist.rehydrate()`\n * inside a `useEffect`, so hydration only ever happens client-side, after\n * mount — the same explicit-hydration contract the SITE README documents.\n */\nexport const CART_STORAGE_KEY = 'shop-cart'\n\n/**\n * The zustand `persist` schema version for the cart's PERSISTED shape (the\n * `CartItem[]` written to `localStorage` under `CART_STORAGE_KEY`) — bump\n * this (with a `migrate` option) if that shape ever changes incompatibly.\n * Also folded into {@link CART_STORE_GLOBAL_KEY} (REB-837 review fix): a\n * future incompatible shape change should mint a NEW global singleton\n * rather than let a stale, already-evaluated old-shape instance (e.g. kept\n * alive across an HMR reload in dev) silently satisfy the new one.\n */\nexport const CART_STORE_PERSIST_VERSION = 0\n\nexport interface CartItem {\n  productId: string\n  variantId?: string | null\n  name: string\n  variantName?: string\n  /** Integer cents — every Reblu shop price travels as cents, never a float. */\n  unitPrice: number\n  quantity: number\n  imageUrl?: string\n  /** `null` means untracked/unlimited stock — never clamp against it. */\n  maxStock: number | null\n  /** Basis points, e.g. `2100` = 21%. `null`/`undefined` = unknown or exempt. */\n  taxRateBps?: number | null\n  taxRateName?: string | null\n}\n\n/**\n * Outcome of `addItem` (REB-837): a SITE's add-to-cart feedback (toast,\n * `AddToCartButton`'s built-in confirmed/error state) needs to know what\n * actually happened, not just fire-and-forget — `'clamped'` only differs\n * from `'added'` in the RESULTING quantity reaching less than what was\n * requested (capped by `maxStock`); `'refused'` means nothing changed\n * (invalid quantity, or the product is out of stock).\n */\nexport type AddItemStatus = 'added' | 'clamped' | 'refused'\n\nexport interface AddItemOutcome {\n  status: AddItemStatus\n  /** The resulting line quantity after the call (`0` when refused and no line exists). */\n  quantity: number\n}\n\nexport interface CartStore {\n  items: CartItem[]\n  addItem: (item: CartItem) => AddItemOutcome\n  removeItem: (productId: string, variantId?: string | null) => void\n  updateQuantity: (\n    productId: string,\n    variantId: string | null | undefined,\n    quantity: number,\n  ) => void\n  clearCart: () => void\n  getTotal: () => number\n  getItemCount: () => number\n}\n\nfunction isSameItem(a: CartItem, productId: string, variantId?: string | null): boolean {\n  return a.productId === productId && (a.variantId ?? null) === (variantId ?? null)\n}\n\n/**\n * REB-829 review finding: neither `addItem` nor `updateQuantity` validated\n * `quantity` — `0`, a negative number, `NaN` (e.g. a stray `parseInt('')`\n * upstream), a non-integer, or `maxStock` itself being `0` (out of stock)\n * all used to leave an invalid line sitting in the cart, silently reaching\n * checkout.\n *\n * Normalizes to a safe POSITIVE INTEGER clamped to `maxStock`. Returns `0`\n * to signal \"not a valid positive quantity\" — callers decide what that\n * means for them: `addItem` ignores the call (never creates/corrupts a\n * line), `updateQuantity` removes the line (same as its pre-existing\n * `quantity <= 0` → remove contract, just now reached by more inputs).\n *\n * `Math.trunc` rounds toward zero (not `Math.floor`, which would round a\n * negative input further negative before the `< 1` check below ever saw it\n * — not a behavioural difference here since any negative result is\n * rejected either way, but `trunc` is the operation that actually means\n * \"drop the fractional part\").\n */\nfunction normalizeQuantity(quantity: number, maxStock: number | null): number {\n  if (!Number.isFinite(quantity)) return 0\n  const truncated = Math.trunc(quantity)\n  if (truncated < 1) return 0\n  if (maxStock === null) return truncated\n  const maxTruncated = Math.trunc(maxStock)\n  if (maxTruncated < 1) return 0\n  return Math.min(truncated, maxTruncated)\n}\n\n/**\n * REB-837 cross-entry singleton guard — the mutation that caught it: a\n * single test rendering `useShopOrderStatus` (the `./shop` tsup entry) and\n * asserting on `useCartStore` (the `./cart` entry) saw the order resolve to\n * `paid` but the cart stay non-empty. Root cause: `splitting: false` (R4,\n * `tsup.config.ts`) bundles each entry standalone, so a plain relative\n * import of this file from `./shop` INLINES a SEPARATE copy of this\n * `create(...)` call — a second, disconnected store instance with its own\n * state, not the one `@reblu/site-next/cart` consumers read. `clearCart()`\n * from inside the hook silently cleared the WRONG store.\n *\n * `globalThis` keyed by a `Symbol.for(...)` (same registry entry regardless\n * of which bundle's copy of this module evaluates it first) makes every\n * entry that imports this file — however many times esbuild inlines it —\n * resolve to the SAME store. Verified by mutation: removing this guard\n * (reverting to a bare `export const useCartStore = create(...)`) turns\n * `use-shop-order-status.test.ts`'s cart-clearing assertions red again once\n * the hook is exercised through its OWN entry rather than imported directly\n * within `cart`'s own test file (which never saw the bug, since it only\n * ever touches ONE copy of this module).\n */\nfunction createCartStore() {\n  return create<CartStore>()(\n    persist(\n      (set, get) => ({\n        items: [],\n\n        addItem: (item) => {\n          // REB-837: `set`'s updater can't return a value to the caller, so the\n          // outcome is captured in this closure variable and returned after.\n          let outcome: AddItemOutcome = { status: 'refused', quantity: 0 }\n\n          set((state) => {\n            const existing = state.items.find((i) => isSameItem(i, item.productId, item.variantId))\n\n            if (existing) {\n              // REB-829 review follow-up (a): incoming maxStock is the\n              // FRESHEST stock signal available — if it says 0, the product is\n              // confirmed out of stock right now, so the existing line is\n              // removed outright (same contract as updateQuantity's own\n              // \"quantity resolves to <1 → remove\"), not merely left alone.\n              if (item.maxStock !== null && Math.trunc(item.maxStock) < 1) {\n                outcome = { status: 'refused', quantity: 0 }\n                return {\n                  items: state.items.filter((i) => !isSameItem(i, item.productId, item.variantId)),\n                }\n              }\n\n              const requestedQty = existing.quantity + item.quantity\n              const newQty = normalizeQuantity(requestedQty, item.maxStock)\n              if (newQty < 1) {\n                // Invalid delta (NaN/non-positive quantity) — leave the\n                // existing, previously-valid line untouched rather than\n                // destroying good data because of one bad call.\n                outcome = { status: 'refused', quantity: existing.quantity }\n                return {}\n              }\n\n              outcome = {\n                status: newQty < requestedQty ? 'clamped' : 'added',\n                quantity: newQty,\n              }\n\n              // Refresh maxStock with the incoming value on every successful\n              // merge — the stale-maxStock finding: a stored line used to keep\n              // its ORIGINAL maxStock forever, so a later updateQuantity call\n              // clamped against stock data that could be long out of date.\n              return {\n                items: state.items.map((i) =>\n                  isSameItem(i, item.productId, item.variantId)\n                    ? { ...i, quantity: newQty, maxStock: item.maxStock }\n                    : i,\n                ),\n              }\n            }\n\n            const qty = normalizeQuantity(item.quantity, item.maxStock)\n            if (qty < 1) {\n              // Invalid quantity, or maxStock 0 (out of stock) — never create\n              // a line nobody could actually buy.\n              outcome = { status: 'refused', quantity: 0 }\n              return {}\n            }\n\n            outcome = { status: qty < item.quantity ? 'clamped' : 'added', quantity: qty }\n            return { items: [...state.items, { ...item, quantity: qty }] }\n          })\n\n          return outcome\n        },\n\n        removeItem: (productId, variantId) => {\n          set((state) => ({\n            items: state.items.filter((i) => !isSameItem(i, productId, variantId)),\n          }))\n        },\n\n        updateQuantity: (productId, variantId, quantity) => {\n          const existing = get().items.find((i) => isSameItem(i, productId, variantId))\n          if (!existing) return\n\n          const newQty = normalizeQuantity(quantity, existing.maxStock)\n          if (newQty < 1) {\n            get().removeItem(productId, variantId)\n            return\n          }\n\n          set((state) => ({\n            items: state.items.map((i) =>\n              isSameItem(i, productId, variantId) ? { ...i, quantity: newQty } : i,\n            ),\n          }))\n        },\n\n        clearCart: () => set({ items: [] }),\n\n        getTotal: () => get().items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0),\n\n        getItemCount: () => get().items.reduce((sum, item) => sum + item.quantity, 0),\n      }),\n      {\n        name: CART_STORAGE_KEY,\n        version: CART_STORE_PERSIST_VERSION,\n        skipHydration: true,\n      },\n    ),\n  )\n}\n\ntype CartStoreApi = ReturnType<typeof createCartStore>\n\n/**\n * Versioned (REB-837 review fix) with {@link CART_STORE_PERSIST_VERSION} —\n * an incompatible shape change bumps that version, which mints a NEW\n * `Symbol.for(...)` registry key, so a stale old-shape singleton (e.g. kept\n * alive across an HMR reload in dev before a code change takes effect)\n * never satisfies the new one.\n */\nconst CART_STORE_GLOBAL_KEY = Symbol.for(\n  `@reblu/site-next/cart-store@v${CART_STORE_PERSIST_VERSION}`,\n)\n\ninterface GlobalWithCartStore {\n  [CART_STORE_GLOBAL_KEY]?: CartStoreApi\n}\n\nconst globalForCartStore = globalThis as typeof globalThis & GlobalWithCartStore\n\nexport const useCartStore: CartStoreApi =\n  globalForCartStore[CART_STORE_GLOBAL_KEY] ??\n  (globalForCartStore[CART_STORE_GLOBAL_KEY] = createCartStore())\n\n/**\n * TEST-ONLY (REB-837 review fix). Clears the `globalThis`-keyed slot so the\n * NEXT access to `useCartStore` — in THIS module instance — creates a fresh\n * store. The singleton is intentionally shared process-wide; most tests\n * should keep resetting STATE via `useCartStore.setState(...)` in\n * `beforeEach`, not the instance itself. Reach for this only to prove\n * something about the singleton mechanism (e.g. the cross-entry test in\n * `tests/cart-store-cross-entry-singleton.test.ts`) — it does not and\n * cannot affect an ALREADY-evaluated copy of this module inlined into a\n * different tsup entry's bundle (each such copy owns its own `const\n * globalForCartStore`/`CART_STORE_GLOBAL_KEY` closed over at that copy's\n * own module-evaluation time, same as any other ES module binding).\n */\nexport function __resetCartStoreForTests(): void {\n  delete globalForCartStore[CART_STORE_GLOBAL_KEY]\n}\n","'use client'\n\nimport { useSyncExternalStore } from 'react'\n\nimport { useCartStore, type AddItemOutcome, type CartItem } from './store'\n\nexport interface UseCartResult {\n  items: CartItem[]\n  /** Sum of every line's `unitPrice * quantity`, in integer cents. */\n  total: number\n  /** Sum of every line's `quantity`. */\n  itemCount: number\n  /**\n   * Whether `CartProvider`'s `persist.rehydrate()` has finished (REB-837).\n   * `false` on the server and on the very first client render — `items`\n   * (and therefore `itemCount`) jumps from `0` to whatever was persisted the\n   * instant hydration finishes, which is NOT a real \"item added\" event. A\n   * consumer driving `CartIcon`'s `bumpOnAdd` MUST gate the bump on this\n   * flag (see `CartIcon`'s own guard) or every page load with a non-empty\n   * cart bumps the badge once for free.\n   */\n  hydrated: boolean\n  addItem: (item: CartItem) => AddItemOutcome\n  removeItem: (productId: string, variantId?: string | null) => void\n  updateQuantity: (\n    productId: string,\n    variantId: string | null | undefined,\n    quantity: number,\n  ) => void\n  clearCart: () => void\n}\n\nfunction subscribeHydration(onStoreChange: () => void): () => void {\n  return useCartStore.persist.onFinishHydration(onStoreChange)\n}\n\nfunction getHydratedSnapshot(): boolean {\n  return useCartStore.persist.hasHydrated()\n}\n\n/** Server snapshot is always `false` — the server never reads `localStorage`. */\nfunction getServerHydratedSnapshot(): boolean {\n  return false\n}\n\n/**\n * `useCartHydrated` — standalone so a SITE that only needs the flag (e.g. to\n * gate its own effects) doesn't have to subscribe to the whole cart via\n * `useCart()`.\n */\nexport function useCartHydrated(): boolean {\n  return useSyncExternalStore(subscribeHydration, getHydratedSnapshot, getServerHydratedSnapshot)\n}\n\n/**\n * `useCart` — the ergonomic entry point for a SITE's cart UI: a single\n * selector call that re-renders only on `items` changes, with `total`/\n * `itemCount` derived inline (cheap — a plain `reduce` over a typically-small\n * array) rather than via `useCartStore`'s own `getTotal`/`getItemCount`\n * selectors, which are stable function references and would NOT trigger a\n * re-render on their own. A SITE that wants raw store access (existing\n * per-field selectors, e.g. `useCartStore((s) => s.addItem)`) can still\n * import `useCartStore` directly — this hook doesn't replace it.\n */\nexport function useCart(): UseCartResult {\n  const items = useCartStore((s) => s.items)\n  const addItem = useCartStore((s) => s.addItem)\n  const removeItem = useCartStore((s) => s.removeItem)\n  const updateQuantity = useCartStore((s) => s.updateQuantity)\n  const clearCart = useCartStore((s) => s.clearCart)\n  const hydrated = useCartHydrated()\n\n  const total = items.reduce((sum, item) => sum + item.unitPrice * item.quantity, 0)\n  const itemCount = items.reduce((sum, item) => sum + item.quantity, 0)\n\n  return { items, total, itemCount, hydrated, addItem, removeItem, updateQuantity, clearCart }\n}\n"],"mappings":"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","names":[]}

package/dist/collection-gAD_g03I.d.cts

@@ -0,0 +1,106 @@
+import { ShopProductsParams, ListResult, RebluClient } from '@reblu/site-client';
+import { ShopProductListItem, ShopFacets } from '@reblu/site-contracts';
+
+/**
+ * Parse a `URLSearchParams` (or anything with that shape — `ReadonlyURLSearchParams`
+ * from `next/navigation`, or a plain `new URLSearchParams(record)`) into
+ * `ShopProductsParams`. Hostile/unknown params are dropped: only the known
+ * scalar keys and the two bracket groups are ever read.
+ */
+declare function parseShopSearchParams(searchParams: URLSearchParams): ShopProductsParams;
+/**
+ * Serialize `ShopProductsParams` into a `URLSearchParams` — the inverse of
+ * {@link parseShopSearchParams}. Falsy/empty/undefined fields are omitted, so
+ * `parseShopSearchParams(serializeShopParams(params))` round-trips to `params`
+ * for any already-canonical (non-empty-string, in-range) input — that is the
+ * property the round-trip tests pin.
+ */
+declare function serializeShopParams(params: ShopProductsParams): URLSearchParams;
+/**
+ * Convert Next's `searchParams` route prop —
+ * `Record<string, string | string[] | undefined>`, already URL-decoded, with
+ * a repeated query key grouped into an array — into a `URLSearchParams` for
+ * {@link parseShopSearchParams}.
+ *
+ * NOT the same as `new URLSearchParams(searchParams)`: the native
+ * `URLSearchParams` constructor only accepts `Record<string, string>` —
+ * handed an array value (`{ 'attr[color]': ['red', 'blue'] }`), it calls
+ * `String()` on it, producing ONE entry `attr[color]=red,blue` instead of two
+ * repeated `attr[color]=red` / `attr[color]=blue` entries. That silently
+ * breaks `parseShopSearchParams`'s repeat-count-based array/scalar
+ * distinction (see its own module doc) for every multi-value `attr[<key>]`
+ * filter — this helper is what actually preserves the repeat.
+ */
+declare function toURLSearchParams(searchParams: Record<string, string | string[] | undefined>): URLSearchParams;
+/**
+ * The navigation seam `@reblu/site-blocks`'s `ShopFilters` calls `hrefs` — kept
+ * structurally identical to its `ShopFiltersHrefs` type WITHOUT a package
+ * dependency on `@reblu/site-blocks` (this package has none today, and this
+ * one shape does not warrant adding one). Any object matching this shape is
+ * assignable to `ShopFiltersHrefs` by structural typing.
+ */
+interface ShopFilterHrefs {
+    taxonomy: (axisKey: string, value: string | undefined) => string;
+    attr: (fieldKey: string, value: string) => string;
+    price: (min: number | undefined, max: number | undefined) => string;
+    onSale: (nextActive: boolean) => string;
+    clearAll: () => string;
+}
+/**
+ * Build `ShopFilters`' href set from the CURRENT params and pathname. Every
+ * href preserves every OTHER current param (category, q, sort, every other
+ * taxonomy/attr filter) and resets pagination (`page`) — a filter change is
+ * never silently stuck on page 4 of a now-smaller result set.
+ *
+ * Pure and framework-agnostic (no `next/navigation`): a Server Component calls
+ * it directly with its own `searchParams` prop and route pathname — no
+ * `'use client'` boundary required. See `./use-shop-filter-links` for the
+ * client-side hook that wraps this with `usePathname`/`useSearchParams`.
+ */
+declare function buildShopFilterHrefs(current: ShopProductsParams, pathname: string): ShopFilterHrefs;
+
+/**
+ * `getShopCollection` (REB-809) — fetches the product list AND its facets with
+ * the EXACT SAME params in one call. This is the seam that keeps a shop
+ * collection page correct: facet counts must reflect the same filter context
+ * the product list is showing, and a hand-rolled page that calls
+ * `client.shop.products(params)` and `client.shop.facets(someOtherParams)`
+ * separately is exactly how they drift apart.
+ *
+ * Server-safe (no `'use client'`, no React) — call it directly from an async
+ * Server Component (route `page.tsx`) with the params parsed via
+ * {@link parseShopSearchParams} from that page's `searchParams` prop.
+ */
+interface ShopCollection {
+    products: ListResult<ShopProductListItem>;
+    facets: ShopFacets;
+    /**
+     * R3-002: `'ok'` when `client.shop.facets(...)` actually succeeded;
+     * `'unavailable'` when it failed and `facets` above is the degraded
+     * {@link EMPTY_FACETS} fallback. NOT silent — check this before treating an
+     * empty `facets` as "this tenant configured no filterable axes" when it may
+     * really mean "the facets endpoint is down right now". A logged
+     * `console.warn` (see below) covers the case nobody checks this field.
+     */
+    facetsStatus: 'ok' | 'unavailable';
+}
+/**
+ * R4-facets-failure-takes-down-listing: `products` and `facets` are NOT
+ * equally critical. A product listing with no products is not a listing —
+ * that failure must propagate so the caller's own error handling (or a
+ * thrown-away `try/catch` degrading the whole page) sees it. A product
+ * listing with no FACETS is still a perfectly good listing, just without
+ * filter UI — degrading `facets` to {@link EMPTY_FACETS} on failure, instead
+ * of letting one upstream endpoint's outage take the other down too, is what
+ * `Promise.allSettled` (rather than `Promise.all`) buys here.
+ *
+ * R3-002: that degradation must not be SILENT. `console.warn`, bracket-tagged
+ * `[getShopCollection]` — the same convention `@reblu/site-next` already uses
+ * elsewhere (`route-handlers.ts`'s `[createProxyRoute]`,
+ * `set-password.tsx`'s `[SetPassword]`) — fires once per failed call, and the
+ * returned `facetsStatus: 'unavailable'` lets a caller that wants to act on
+ * it (retry, surface a banner, alert) do so without parsing a log line.
+ */
+declare function getShopCollection(client: RebluClient, params?: ShopProductsParams): Promise<ShopCollection>;
+
+export { type ShopCollection as S, type ShopFilterHrefs as a, buildShopFilterHrefs as b, getShopCollection as g, parseShopSearchParams as p, serializeShopParams as s, toURLSearchParams as t };