@doswiftly/cli 0.1.1

package/templates/storefront-nextjs/components/auth/auth-guard.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { useEffect, ReactNode } from "react";
+import { useRouter } from "next/navigation";
+import { useAuth } from "@doswiftly/commerce-sdk/graphql/react";
+import { redirects } from "@/lib/auth/routes";
+
+interface AuthGuardProps {
+  children: ReactNode;
+  /** URL to redirect to (default: from lib/auth/routes.ts) */
+  redirectTo?: string;
+  /** Custom loading component */
+  fallback?: ReactNode;
+  /** If true, only guests can access (redirects authenticated users) */
+  requireGuest?: boolean;
+}
+
+/**
+ * AuthGuard - Client-side route protection based on authentication status
+ *
+ * Security Model (Layer 2 of 3):
+ * 1. Middleware - Fast redirect based on cookie (runs first)
+ * 2. AuthGuard (this) - Client-side validation via useAuth hook
+ * 3. GraphQL Backend - Ultimate security (validates token)
+ *
+ * Why use AuthGuard if middleware exists?
+ * - Middleware only checks cookie existence (fast but not validation)
+ * - AuthGuard validates token via useAuth (catches expired/invalid tokens)
+ * - Provides loading states during redirect
+ * - Works for client-side navigation (middleware only runs on initial load)
+ *
+ * @example
+ * ```tsx
+ * // Protected route (requires login)
+ * export default function AccountPage() {
+ *   return (
+ *     <AuthGuard>
+ *       <AccountContent />
+ *     </AuthGuard>
+ *   );
+ * }
+ *
+ * // Guest-only route (login/register pages)
+ * export default function LoginPage() {
+ *   return (
+ *     <AuthGuard requireGuest>
+ *       <LoginForm />
+ *     </AuthGuard>
+ *   );
+ * }
+ *
+ * // Custom redirect (e.g., preserve checkout URL)
+ * export default function CheckoutPage() {
+ *   return (
+ *     <AuthGuard redirectTo="/auth/login?redirect=/checkout">
+ *       <CheckoutContent />
+ *     </AuthGuard>
+ *   );
+ * }
+ * ```
+ *
+ * @see lib/auth/routes.ts - SSOT for route configuration
+ * @see middleware.ts - Server-side route protection
+ */
+export function AuthGuard({
+  children,
+  redirectTo,
+  fallback,
+  requireGuest = false,
+}: AuthGuardProps) {
+  const router = useRouter();
+  const { isAuthenticated } = useAuth();
+
+  // Use SSOT defaults from routes.ts
+  const defaultRedirect = requireGuest
+    ? redirects.authenticated
+    : redirects.unauthenticated;
+  const targetRedirect = redirectTo ?? defaultRedirect;
+
+  // Determine if we should redirect
+  const shouldRedirect = requireGuest ? isAuthenticated : !isAuthenticated;
+
+  useEffect(() => {
+    if (shouldRedirect) {
+      // Use replace instead of push to prevent back button issues
+      router.replace(targetRedirect);
+    }
+  }, [shouldRedirect, targetRedirect, router]);
+
+  // Always render children immediately (non-blocking)
+  // Redirect happens async in useEffect
+  // This prevents blocking router.replace() execution
+  return <>{children}</>;
+}

package/templates/storefront-nextjs/components/commerce/add-to-cart-button.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { useState } from "react";
+import { ShoppingCart, Loader2, Check } from "lucide-react";
+import { useCartManager } from "@doswiftly/commerce-sdk/graphql/react";
+
+interface AddToCartButtonProps {
+  variantId: string;
+  quantity?: number;
+  disabled?: boolean;
+}
+
+/**
+ * AddToCartButton - Developer-friendly add to cart button
+ *
+ * Uses useCartManager hook - all loading/error states come from the hook.
+ * No manual state management needed!
+ *
+ * @example
+ * ```tsx
+ * <AddToCartButton variantId="variant-123" />
+ * <AddToCartButton variantId="variant-123" quantity={2} />
+ * <AddToCartButton variantId="variant-123" disabled={!inStock} />
+ * ```
+ */
+export function AddToCartButton({
+  variantId,
+  quantity = 1,
+  disabled = false,
+}: AddToCartButtonProps) {
+  // Success state (only local state needed - for brief "Added!" feedback)
+  const [justAdded, setJustAdded] = useState(false);
+
+  // All cart logic from hook - no manual state management!
+  const { addItem, addItemLoading } = useCartManager();
+
+  const handleAddToCart = async () => {
+    if (disabled || addItemLoading) return;
+
+    try {
+      await addItem(variantId, quantity);
+      setJustAdded(true);
+      setTimeout(() => setJustAdded(false), 2000);
+    } catch (err) {
+      console.error("Failed to add to cart:", err);
+    }
+  };
+
+  return (
+    <button
+      onClick={handleAddToCart}
+      disabled={disabled || addItemLoading}
+      className={`btn w-full ${
+        justAdded
+          ? "bg-green-500 text-white hover:bg-green-600"
+          : "bg-gray-900 text-white hover:bg-gray-800"
+      }`}
+    >
+      {addItemLoading ? (
+        <>
+          <Loader2 className="mr-2 h-5 w-5 animate-spin" />
+          Adding...
+        </>
+      ) : justAdded ? (
+        <>
+          <Check className="mr-2 h-5 w-5" />
+          Added to Cart!
+        </>
+      ) : (
+        <>
+          <ShoppingCart className="mr-2 h-5 w-5" />
+          Add to Cart
+        </>
+      )}
+    </button>
+  );
+}

package/templates/storefront-nextjs/components/commerce/cart-icon.tsx

@@ -0,0 +1,29 @@
+"use client";
+
+import Link from "next/link";
+import { ShoppingCart } from "lucide-react";
+import { useCartManager } from "@doswiftly/commerce-sdk/graphql/react";
+
+/**
+ * CartIcon - Cart icon with dynamic item count
+ *
+ * Shows total quantity from useCartManager.
+ * Updates automatically when cart changes.
+ */
+export function CartIcon() {
+  const { totalQuantity } = useCartManager();
+
+  return (
+    <Link
+      href="/cart"
+      className="relative p-2 text-gray-600 hover:text-primary"
+    >
+      <ShoppingCart className="h-5 w-5" />
+      {totalQuantity > 0 && (
+        <span className="absolute -right-1 -top-1 flex h-5 w-5 items-center justify-center rounded-full bg-primary text-xs text-white">
+          {totalQuantity > 99 ? "99+" : totalQuantity}
+        </span>
+      )}
+    </Link>
+  );
+}

package/templates/storefront-nextjs/components/commerce/currency-selector.tsx

@@ -0,0 +1,217 @@
+"use client";
+
+import { useState, useRef, useEffect } from "react";
+import { ChevronDown, Check, Globe } from "lucide-react";
+import { useCurrency } from "@doswiftly/commerce-sdk/graphql/react";
+import {
+  useCurrencyStore,
+  selectIsHydrated,
+} from "@doswiftly/commerce-sdk/graphql/react/stores";
+
+// ============================================================================
+// CURRENCY DATA
+// ============================================================================
+
+const CURRENCY_SYMBOLS: Record<string, string> = {
+  PLN: "zł",
+  EUR: "€",
+  USD: "$",
+  GBP: "£",
+  CHF: "CHF",
+  CZK: "Kč",
+  SEK: "kr",
+  NOK: "kr",
+  DKK: "kr",
+  JPY: "¥",
+  CNY: "¥",
+  AUD: "A$",
+  CAD: "C$",
+};
+
+const CURRENCY_NAMES: Record<string, string> = {
+  PLN: "Polski złoty",
+  EUR: "Euro",
+  USD: "US Dollar",
+  GBP: "British Pound",
+  CHF: "Swiss Franc",
+  CZK: "Czech Koruna",
+  SEK: "Swedish Krona",
+  NOK: "Norwegian Krone",
+  DKK: "Danish Krone",
+  JPY: "Japanese Yen",
+  CNY: "Chinese Yuan",
+  AUD: "Australian Dollar",
+  CAD: "Canadian Dollar",
+};
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+interface CurrencySelectorProps {
+  className?: string;
+  showSymbol?: boolean;
+  showIcon?: boolean;
+  variant?: "default" | "compact" | "minimal";
+}
+
+// ============================================================================
+// COMPONENT
+// ============================================================================
+
+export function CurrencySelector({
+  className = "",
+  showSymbol = false,
+  showIcon = true,
+  variant = "default",
+}: CurrencySelectorProps) {
+  // useCurrency from SDK context - setCurrency includes QueryClient invalidation
+  const { currency, supportedCurrencies, setCurrency, isAutoDetected } = useCurrency();
+
+  // Hydration state from Zustand (prevents SSR mismatch flash)
+  const isHydrated = useCurrencyStore(selectIsHydrated);
+
+  const [isOpen, setIsOpen] = useState(false);
+  const dropdownRef = useRef<HTMLDivElement>(null);
+
+  // Close dropdown on outside click
+  useEffect(() => {
+    function handleClickOutside(event: MouseEvent) {
+      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    }
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
+
+  // Close on escape
+  useEffect(() => {
+    function handleEscape(event: KeyboardEvent) {
+      if (event.key === "Escape") setIsOpen(false);
+    }
+    document.addEventListener("keydown", handleEscape);
+    return () => document.removeEventListener("keydown", handleEscape);
+  }, []);
+
+  // Prevent SSR mismatch - skeleton until hydrated
+  if (!isHydrated) {
+    return (
+      <div className={`inline-block ${className}`}>
+        <div className="px-3 py-2 bg-gray-100 rounded-lg animate-pulse w-16 h-9" />
+      </div>
+    );
+  }
+
+  const handleSelect = (newCurrency: string) => {
+    if (newCurrency !== currency) {
+      setCurrency(newCurrency); // Includes QueryClient invalidation
+    }
+    setIsOpen(false);
+  };
+
+  const displayValue = showSymbol ? (CURRENCY_SYMBOLS[currency] || currency) : currency;
+
+  const buttonStyles = {
+    default: "px-3 py-2 text-sm",
+    compact: "px-2 py-1.5 text-xs",
+    minimal: "px-2 py-1 text-xs",
+  };
+
+  const dropdownStyles = {
+    default: "w-48",
+    compact: "w-40",
+    minimal: "w-36",
+  };
+
+  return (
+    <div ref={dropdownRef} className={`relative inline-block ${className}`}>
+      <button
+        type="button"
+        onClick={() => setIsOpen(!isOpen)}
+        className={`
+          inline-flex items-center justify-between gap-2
+          bg-white dark:bg-gray-800
+          border border-gray-200 dark:border-gray-700
+          rounded-lg
+          text-gray-700 dark:text-gray-200
+          hover:bg-gray-50 dark:hover:bg-gray-700
+          focus:outline-none focus:ring-2 focus:ring-blue-500
+          transition-colors
+          ${buttonStyles[variant]}
+        `}
+        aria-expanded={isOpen}
+        aria-haspopup="listbox"
+      >
+        {showIcon && variant !== "minimal" && (
+          <Globe className="w-4 h-4 text-gray-400" />
+        )}
+        <span className="font-medium">{displayValue}</span>
+        {isAutoDetected && variant === "default" && (
+          <span className="text-xs text-gray-400">(auto)</span>
+        )}
+        <ChevronDown
+          className={`w-4 h-4 text-gray-400 transition-transform ${isOpen ? "rotate-180" : ""}`}
+        />
+      </button>
+
+      {isOpen && (
+        <div
+          className={`
+            absolute right-0 mt-2 z-50
+            bg-white dark:bg-gray-800
+            border border-gray-200 dark:border-gray-700
+            rounded-lg shadow-lg
+            overflow-hidden
+            ${dropdownStyles[variant]}
+          `}
+          role="listbox"
+        >
+          <div className="py-1 max-h-64 overflow-y-auto">
+            {supportedCurrencies.map((code) => {
+              const isSelected = code === currency;
+              const symbol = CURRENCY_SYMBOLS[code] || code;
+              const name = CURRENCY_NAMES[code] || code;
+
+              return (
+                <button
+                  key={code}
+                  type="button"
+                  onClick={() => handleSelect(code)}
+                  className={`
+                    w-full px-3 py-2 text-left
+                    flex items-center justify-between gap-2
+                    hover:bg-gray-100 dark:hover:bg-gray-700
+                    transition-colors
+                    ${isSelected ? "bg-blue-50 dark:bg-blue-900/20" : ""}
+                  `}
+                  role="option"
+                  aria-selected={isSelected}
+                >
+                  <div className="flex items-center gap-2">
+                    <span className="w-6 text-center text-gray-400 font-mono text-sm">
+                      {symbol}
+                    </span>
+                    <div>
+                      <span className="font-medium text-gray-900 dark:text-gray-100">
+                        {code}
+                      </span>
+                      {variant === "default" && (
+                        <span className="ml-2 text-xs text-gray-500 dark:text-gray-400">
+                          {name}
+                        </span>
+                      )}
+                    </div>
+                  </div>
+                  {isSelected && <Check className="w-4 h-4 text-blue-500" />}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default CurrencySelector;

package/templates/storefront-nextjs/components/commerce/pagination.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { useSearchParams, usePathname } from "next/navigation";
+import Link from "next/link";
+
+interface PaginationProps {
+  hasMore: boolean;
+  endCursor?: string | null;
+  currentCursor?: string;
+  totalShown: number;
+}
+
+/**
+ * Pagination - URL-based pagination that preserves filters
+ */
+export function Pagination({
+  hasMore,
+  endCursor,
+  currentCursor,
+  totalShown,
+}: PaginationProps) {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  // Build URL preserving current filters
+  const buildUrl = (cursor?: string | null) => {
+    const params = new URLSearchParams(searchParams.toString());
+
+    if (cursor) {
+      params.set("after", cursor);
+    } else {
+      params.delete("after");
+    }
+
+    const queryString = params.toString();
+    return queryString ? `${pathname}?${queryString}` : pathname;
+  };
+
+  return (
+    <div className="mt-12 flex justify-center gap-2">
+      <Link
+        href={buildUrl()}
+        className={`btn btn-outline ${
+          !currentCursor ? "pointer-events-none opacity-50" : ""
+        }`}
+      >
+        First Page
+      </Link>
+      <span className="flex items-center px-4 text-gray-600">
+        Showing {totalShown} products
+      </span>
+      <Link
+        href={hasMore && endCursor ? buildUrl(endCursor) : "#"}
+        className={`btn btn-outline ${
+          !hasMore ? "pointer-events-none opacity-50" : ""
+        }`}
+      >
+        Next
+      </Link>
+    </div>
+  );
+}

package/templates/storefront-nextjs/components/commerce/product-actions.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import { useState, useMemo } from "react";
+import { VariantSelector } from "@/components/commerce/variant-selector";
+import { AddToCartButton } from "@/components/commerce/add-to-cart-button";
+import { formatPrice } from "@/lib/currency";
+
+interface ProductVariant {
+  id: string;
+  title: string;
+  available: boolean;
+  selectedOptions: Array<{ name: string; value: string }>;
+  price: {
+    amount: string;
+    currencyCode: string;
+  };
+  compareAtPrice?: {
+    amount: string;
+    currencyCode: string;
+  } | null;
+}
+
+interface ProductActionsProps {
+  variants: ProductVariant[];
+  productId: string;
+}
+
+/**
+ * ProductActions - Client-side product interactions
+ *
+ * Handles variant selection, quantity, and add to cart.
+ * Server Component renders the rest of the page.
+ */
+export function ProductActions({ variants, productId }: ProductActionsProps) {
+  // Store only variant ID - derive variant object from props (SSOT)
+  const [selectedVariantId, setSelectedVariantId] = useState<string | null>(
+    () => variants[0]?.id ?? null
+  );
+  const [quantity, setQuantity] = useState(1);
+
+  // Derived state: automatically updates when variants prop changes (e.g., after currency change)
+  const selectedVariant = useMemo(() => {
+    if (!variants || variants.length === 0) return null;
+    const found = variants.find((v) => v.id === selectedVariantId);
+    // Fallback to first variant if selected ID not found in new variants
+    return found ?? variants[0];
+  }, [variants, selectedVariantId]);
+
+  // Handler for VariantSelector - extracts ID from variant object
+  const handleVariantChange = (variant: ProductVariant) => {
+    setSelectedVariantId(variant.id);
+  };
+
+  const inStock = selectedVariant?.available ?? true;
+  const price = selectedVariant?.price;
+  const compareAtPrice = selectedVariant?.compareAtPrice;
+
+  return (
+    <div className="space-y-6">
+      {/* Price */}
+      <div className="flex items-baseline gap-4">
+        <span className="text-2xl font-bold text-primary">
+          {formatPrice(price)}
+        </span>
+        {compareAtPrice && (
+          <span className="text-lg text-gray-400 line-through">
+            {formatPrice(compareAtPrice)}
+          </span>
+        )}
+      </div>
+
+      {/* Variant Selector */}
+      {variants.length > 1 && (
+        <VariantSelector
+          variants={variants}
+          selectedVariantId={selectedVariant?.id}
+          onVariantChange={handleVariantChange}
+        />
+      )}
+
+      {/* Stock Status */}
+      <div>
+        {inStock ? (
+          <span className="inline-flex items-center gap-2 text-green-600">
+            <span className="h-2 w-2 rounded-full bg-green-600" />
+            In Stock
+          </span>
+        ) : (
+          <span className="inline-flex items-center gap-2 text-red-600">
+            <span className="h-2 w-2 rounded-full bg-red-600" />
+            Out of Stock
+          </span>
+        )}
+      </div>
+
+      {/* Quantity & Add to Cart */}
+      <div className="space-y-4">
+        <div className="flex items-center gap-4">
+          <label className="text-sm font-medium text-gray-700">Quantity:</label>
+          <div className="flex items-center rounded-lg border border-gray-300">
+            <button
+              type="button"
+              onClick={() => setQuantity((q) => Math.max(1, q - 1))}
+              className="px-3 py-2 text-gray-600 hover:text-primary"
+            >
+              -
+            </button>
+            <input
+              type="number"
+              min="1"
+              value={quantity}
+              onChange={(e) =>
+                setQuantity(Math.max(1, parseInt(e.target.value) || 1))
+              }
+              className="w-16 border-x border-gray-300 py-2 text-center"
+            />
+            <button
+              type="button"
+              onClick={() => setQuantity((q) => q + 1)}
+              className="px-3 py-2 text-gray-600 hover:text-primary"
+            >
+              +
+            </button>
+          </div>
+        </div>
+
+        <AddToCartButton
+          variantId={selectedVariant?.id || productId}
+          quantity={quantity}
+          disabled={!inStock}
+        />
+      </div>
+    </div>
+  );
+}