@doswiftly/cli 0.2.0 → 0.2.5

package/templates/storefront-nextjs-shadcn/components/product/product-configurator.tsx

@@ -0,0 +1,282 @@
+"use client";
+
+/**
+ * ProductConfigurator
+ *
+ * Renderuje pola konfiguratora produktu dla klienta końcowego — Product.attributes
+ * z fillingMode CUSTOMER lub BOTH. Każdy atrybut obsługuje:
+ *
+ *   - SELECT / RADIO  — lista opcji (1 wybór), opcje z dopłatą pokazują kwotę obok
+ *   - CHECKBOX        — lista opcji (wielokrotny wybór; Faza 2 stosuje MULTI_SELECT)
+ *   - TEXT / TEXTAREA — wolny tekst (z walidacją minValue/maxValue jako min/max długości)
+ *   - NUMBER          — pole liczbowe z zakresem
+ *   - DATE            — date picker (natywny input type=date)
+ *
+ * Komponent jest kontrolowany: rodzic (product-client.tsx) trzyma mapę
+ * `Record<attributeDefinitionId, AttributeSelectionInput>` i mutacje koszyka
+ * przesyłają ją jako `cartLinesAdd.lines[i].attributeSelections`.
+ *
+ * Wymagane pola (`isRequired`) blokują AddToCart jeśli użytkownik nie wypełnił —
+ * walidacja odbywa się także po stronie serwera, ale local gate poprawia UX.
+ */
+
+import { useMemo } from "react";
+import { Label } from "@/components/ui/label";
+import { Input } from "@/components/ui/input";
+import { Textarea } from "@/components/ui/textarea";
+import { Badge } from "@/components/ui/badge";
+import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
+import { formatAmount } from "@doswiftly/storefront-sdk";
+import type { ProductConfiguratorFieldsFragment } from "@/generated/graphql";
+import { cn } from "@/lib/utils";
+
+/**
+ * Single attribute selection (matches AttributeSelectionInput schema shape).
+ * Rodzic przekazuje Record<definitionId, ProductConfiguratorSelection>.
+ */
+export interface ProductConfiguratorSelection {
+  attributeDefinitionId: string;
+  optionId?: string | null;
+  optionIds?: string[] | null;
+  textValue?: string | null;
+}
+
+export interface ProductConfiguratorProps {
+  attributes: readonly ProductConfiguratorFieldsFragment[];
+  selections: Record<string, ProductConfiguratorSelection>;
+  onChange: (definitionId: string, selection: ProductConfiguratorSelection) => void;
+  currency: string;
+  /** Podświetla pola wymagane bez wartości — przełączane przez rodzica po kliku AddToCart. */
+  showValidation?: boolean;
+}
+
+/**
+ * Compute total surcharge from current selections (for live price preview in parent).
+ * Zwraca tylko FIXED surcharge (PERCENT jest placeholderem Fazy 2 i nie jest pokazywany).
+ */
+export function computeConfiguratorSurcharge(
+  attributes: readonly ProductConfiguratorFieldsFragment[],
+  selections: Record<string, ProductConfiguratorSelection>,
+): number {
+  let total = 0;
+  for (const def of attributes) {
+    const selection = selections[def.id];
+    if (!selection?.optionId) continue;
+    const option = def.options.find((opt) => opt.id === selection.optionId);
+    if (!option?.surchargeAmount || option.surchargeType !== "FIXED") continue;
+    total += option.surchargeAmount;
+  }
+  return total;
+}
+
+/**
+ * Detect unfilled required fields — rodzic używa przed wysłaniem cartLinesAdd.
+ * Zwraca tablicę nazw (dla toast/highlight), pustą gdy wszystko poprawnie wypełnione.
+ */
+export function findMissingRequiredFields(
+  attributes: readonly ProductConfiguratorFieldsFragment[],
+  selections: Record<string, ProductConfiguratorSelection>,
+): string[] {
+  const missing: string[] = [];
+  for (const def of attributes) {
+    if (!def.isRequired) continue;
+    const selection = selections[def.id];
+    const isOptionType = def.type === "SELECT" || def.type === "RADIO" || def.type === "CHECKBOX";
+    const isTextType =
+      def.type === "TEXT" || def.type === "TEXTAREA" || def.type === "NUMBER" || def.type === "DATE";
+    if (isOptionType && !selection?.optionId && !selection?.optionIds?.length) {
+      missing.push(def.name);
+    } else if (isTextType && !selection?.textValue?.trim()) {
+      missing.push(def.name);
+    }
+  }
+  return missing;
+}
+
+export function ProductConfigurator({
+  attributes,
+  selections,
+  onChange,
+  currency,
+  showValidation = false,
+}: ProductConfiguratorProps) {
+  const sortedAttributes = useMemo(
+    () => [...attributes].sort((a, b) => a.displayOrder - b.displayOrder),
+    [attributes],
+  );
+
+  if (sortedAttributes.length === 0) return null;
+
+  return (
+    <div className="space-y-5 rounded-lg border bg-muted/30 p-4">
+      <div>
+        <h3 className="text-sm font-semibold">Konfiguracja</h3>
+        <p className="text-xs text-muted-foreground">
+          Wybierz opcje zanim dodasz do koszyka. Dopłaty doliczymy do ceny lub wyszczególnimy
+          na fakturze zgodnie z ustawieniami sprzedawcy.
+        </p>
+      </div>
+
+      {sortedAttributes.map((def) => {
+        const selection = selections[def.id];
+        const isMissing =
+          showValidation && def.isRequired && isSelectionEmpty(def, selection);
+
+        return (
+          <div key={def.id} className={cn("space-y-2", isMissing && "rounded-md border border-destructive/40 p-2")}>
+            <div className="flex items-start justify-between gap-2">
+              <Label className="text-sm font-medium">
+                {def.name}
+                {def.isRequired && <span className="ml-1 text-destructive">*</span>}
+              </Label>
+              {def.billingMode === "SEPARATE_LINE" && (
+                <Badge variant="secondary" className="text-[10px]">
+                  osobna pozycja faktury
+                </Badge>
+              )}
+            </div>
+            {def.description && (
+              <p className="text-xs text-muted-foreground">{def.description}</p>
+            )}
+
+            <ConfiguratorField
+              definition={def}
+              selection={selection}
+              currency={currency}
+              onChange={onChange}
+            />
+
+            {isMissing && (
+              <p className="text-xs text-destructive">Pole wymagane — wypełnij, żeby dodać do koszyka.</p>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * Per-type rendering delegate. Trzyma logikę switch w jednym miejscu żeby
+ * `ProductConfigurator` nie rozrastał się ponad wzorzec "list + row".
+ */
+function ConfiguratorField({
+  definition,
+  selection,
+  currency,
+  onChange,
+}: {
+  definition: ProductConfiguratorFieldsFragment;
+  selection?: ProductConfiguratorSelection;
+  currency: string;
+  onChange: ProductConfiguratorProps["onChange"];
+}) {
+  const updateOption = (optionId: string) => {
+    onChange(definition.id, {
+      attributeDefinitionId: definition.id,
+      optionId,
+    });
+  };
+
+  const updateText = (textValue: string) => {
+    onChange(definition.id, {
+      attributeDefinitionId: definition.id,
+      textValue,
+    });
+  };
+
+  switch (definition.type) {
+    case "SELECT":
+    case "RADIO":
+      return (
+        <RadioGroup
+          value={selection?.optionId ?? ""}
+          onValueChange={updateOption}
+          className="space-y-1"
+        >
+          {definition.options.map((opt) => (
+            <label
+              key={opt.id}
+              className="flex cursor-pointer items-center justify-between gap-3 rounded-md border bg-background px-3 py-2 text-sm hover:bg-muted/50"
+            >
+              <span className="flex items-center gap-2">
+                <RadioGroupItem value={opt.id} id={`${definition.id}-${opt.id}`} />
+                <span>{opt.label}</span>
+              </span>
+              {typeof opt.surchargeAmount === "number" && opt.surchargeAmount > 0 && (
+                <span className="text-xs font-medium text-muted-foreground">
+                  +{formatAmount(opt.surchargeAmount / 100, currency)}
+                </span>
+              )}
+            </label>
+          ))}
+        </RadioGroup>
+      );
+
+    case "CHECKBOX":
+      // Faza 1 obsługuje CHECKBOX jako pojedynczy wybór (backend przyjmuje optionId).
+      // MULTI_SELECT z optionIds[] jest w Fazie 2.
+      return (
+        <RadioGroup
+          value={selection?.optionId ?? ""}
+          onValueChange={updateOption}
+          className="space-y-1"
+        >
+          {definition.options.map((opt) => (
+            <label
+              key={opt.id}
+              className="flex cursor-pointer items-center justify-between gap-3 rounded-md border bg-background px-3 py-2 text-sm hover:bg-muted/50"
+            >
+              <span className="flex items-center gap-2">
+                <RadioGroupItem value={opt.id} id={`${definition.id}-${opt.id}`} />
+                <span>{opt.label}</span>
+              </span>
+              {typeof opt.surchargeAmount === "number" && opt.surchargeAmount > 0 && (
+                <span className="text-xs font-medium text-muted-foreground">
+                  +{formatAmount(opt.surchargeAmount / 100, currency)}
+                </span>
+              )}
+            </label>
+          ))}
+        </RadioGroup>
+      );
+
+    case "TEXT":
+    case "NUMBER":
+    case "DATE":
+      return (
+        <Input
+          type={definition.type === "NUMBER" ? "number" : definition.type === "DATE" ? "date" : "text"}
+          value={selection?.textValue ?? ""}
+          onChange={(e) => updateText(e.target.value)}
+          min={definition.type === "NUMBER" ? definition.minValue ?? undefined : undefined}
+          max={definition.type === "NUMBER" ? definition.maxValue ?? undefined : undefined}
+          placeholder={definition.description ?? ""}
+        />
+      );
+
+    case "TEXTAREA":
+      return (
+        <Textarea
+          value={selection?.textValue ?? ""}
+          onChange={(e) => updateText(e.target.value)}
+          rows={3}
+          placeholder={definition.description ?? ""}
+        />
+      );
+
+    default:
+      // COLOR / IMAGE / FILE / BOOLEAN / CURRENCY — Faza 2+ / admin-only; nie renderujemy.
+      return null;
+  }
+}
+
+function isSelectionEmpty(
+  definition: ProductConfiguratorFieldsFragment,
+  selection: ProductConfiguratorSelection | undefined,
+): boolean {
+  if (!selection) return true;
+  const optionType = definition.type === "SELECT" || definition.type === "RADIO" || definition.type === "CHECKBOX";
+  if (optionType) return !selection.optionId;
+  return !selection.textValue?.trim();
+}

package/templates/storefront-nextjs-shadcn/components/product/product-detail.fragment.graphql

@@ -28,10 +28,11 @@ fragment ProductDetailFields on Product {
     description
   }
   images(first: 20) {
-    url
+    url(transform: { maxWidth: 1600 })
     altText
     width
     height
+    thumbhash
   }
   variants(first: 100) {
     ...ProductVariantFields
@@ -49,4 +50,10 @@ fragment ProductDetailFields on Product {
       currencyCode
     }
   }
+  # Customer-facing configurator fields (CUSTOMER + BOTH filling modes).
+  # Rendered by components/product/product-configurator.tsx on the product page.
+  # MERCHANT-filled fields (product metadata) are intentionally excluded.
+  attributes(filter: { fillingMode: "CUSTOMER" }) {
+    ...ProductConfiguratorFields
+  }
 }

package/templates/storefront-nextjs-shadcn/components/product/product-image.tsx

@@ -1,9 +1,9 @@
 "use client";
 
-import { useState } from "react";
+import { useState, useMemo } from "react";
 import Image from "next/image";
 import { cn } from "@/lib/utils";
-import type { ImageData } from "@doswiftly/storefront-sdk";
+import { type ImageData, thumbHashToDataURL } from "@doswiftly/storefront-sdk";
 
 export type ProductImageData = ImageData;
 
@@ -111,7 +111,10 @@ export function ProductImage({
 
   const imageAlt = alt || image.altText || "Product image";
 
-  // Global loaderFile (next.config.ts) handles imgproxy resize — no per-component loader needed
+  // Decode ThumbHash to data URL for instant blur placeholder (memoized — decode once per image)
+  const blurDataURL = useMemo(() => thumbHashToDataURL(image.thumbhash), [image.thumbhash]);
+
+  // CDN URL already has correct transform params from GraphQL — passthrough loader skips /_next/image
   const commonProps = {
     src: image.url,
     alt: imageAlt,
@@ -121,6 +124,7 @@ export function ProductImage({
       className
     ),
     onError: () => setHasError(true),
+    ...(blurDataURL ? { placeholder: "blur" as const, blurDataURL } : {}),
   };
 
   if (fill) {

package/templates/storefront-nextjs-shadcn/components/product/product-variant.fragment.graphql

@@ -39,10 +39,11 @@ fragment ProductVariantFields on ProductVariant {
     currencyCode
   }
   image {
-    url
+    url(transform: { maxWidth: 300 })
     altText
     width
     height
+    thumbhash
   }
   selectedOptions {
     name

package/templates/storefront-nextjs-shadcn/graphql/custom.example.graphql

@@ -101,6 +101,106 @@ query SearchProductsWithFilters(
   }
 }
 
+# ============================================================================
+# BOPIS (Buy Online, Pick Up In Store) — per-location stock availability
+# ============================================================================
+#
+# For shops with multiple active locations (warehouses, physical stores, fulfillment
+# centers) the `ProductVariant.storeAvailability` field exposes per-location stock
+# with `near` proximity sort, `locationType` filter, and the
+# `@inContext(preferredLocationId)` operation directive.
+#
+# Returns `null` for single-location shops (backward-compat shortcut — the storefront
+# can skip rendering the store picker UI entirely without an extra round-trip).
+#
+# Token gating:
+# - `available: Boolean!` and `pickUpTime: String` are public.
+# - `quantityAvailable: Int` is null for anonymous requests, Int for authenticated
+#   customers (send the `x-customer-access-token` header).
+#
+# Built-in query: `ProductStoreAvailability($handle, $id)` from
+# @doswiftly/storefront-operations also works — this example shows how to write a
+# BOPIS-focused variant with proximity + preferred-location pinning.
+
+# Example: proximity-sorted pickup points near the customer, with a preferred location
+# pinned to the top via the @inContext directive.
+query GetProductStoreAvailability(
+  $handle: String!
+  $near: GeoCoordinateInput
+  $preferredLocationId: ID
+) @inContext(preferredLocationId: $preferredLocationId) {
+  product(handle: $handle) {
+    id
+    handle
+    title
+    variants {
+      id
+      title
+      sku
+      available
+      quantityAvailable
+      storeAvailability(first: 10, near: $near, locationType: STORE) {
+        totalCount
+        pageInfo { hasNextPage endCursor }
+        edges {
+          cursor
+          node {
+            available
+            quantityAvailable # null for anonymous, Int for authenticated
+            pickUpTime        # localized, e.g. "Usually ready in 2 hours"
+            location {
+              id
+              name
+              pickupEnabled
+              timezone
+              pickupInstructions
+              address { city country latitude longitude formatted }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+# Example: store picker — list pickup-enabled locations sorted by distance.
+query GetPickupLocations($near: GeoCoordinateInput) {
+  locations(first: 20, hasPickupEnabled: true, near: $near) {
+    totalCount
+    pageInfo { hasNextPage endCursor }
+    edges {
+      cursor
+      node {
+        id
+        name
+        pickupEnabled
+        address { city formatted }
+      }
+    }
+  }
+}
+
+# Example usage in component:
+#
+#   'use client';
+#   import { useGraphQLQuery } from '@/lib/graphql/hooks';
+#   import { GetProductStoreAvailabilityDocument } from '@/generated/graphql';
+#
+#   function StorePickup({ handle, userCoords, preferredLocationId }: Props) {
+#     const { data } = useGraphQLQuery(GetProductStoreAvailabilityDocument, {
+#       handle,
+#       near: userCoords, // { latitude, longitude } or undefined
+#       preferredLocationId,
+#     });
+#     const conn = data?.product?.variants?.[0]?.storeAvailability;
+#     if (!conn) return <p>Online only</p>;
+#     return conn.edges.map(({ node }) => (
+#       <div key={node.location.id}>
+#         {node.location.name}: {node.available ? (node.pickUpTime ?? 'Available') : 'Out of stock'}
+#       </div>
+#     ));
+#   }
+
 # Get collection with products (inline — useful when collection page needs custom fields)
 query GetCollectionWithProducts(
   $handle: String!

package/templates/storefront-nextjs-shadcn/hooks/use-cart-actions.ts

@@ -1,6 +1,7 @@
 'use client';
 
 import { useCallback, useEffect, useRef } from 'react';
+import type { CartAttributeSelectionInput } from '@doswiftly/storefront-sdk';
 import { useCartStore, useCartStoreApi } from '@/stores/cart-store';
 
 // Debounce delay for quantity updates (prevents rate limiting)
@@ -26,12 +27,32 @@ export function useCartActions() {
   const updateTimeoutRef = useRef<Map<string, NodeJS.Timeout>>(new Map());
 
   /**
-   * Add item to cart by variant ID, delegates to SDK store.
+   * Add item to cart by variant ID.
+   *
+   * Optional `attributeSelections` przekazywane do backendu jako konfigurator
+   * (Faza 1) — np. wybór Finiszera w drukarce. Backend waliduje + snapshotuje
+   * surcharge/taxRate; server odpowiada userErrors jeśli brak wymaganego pola
+   * (catch błędu w UI obsługuje `onMutationError` w CartProvider).
    */
-  const addToCart = useCallback(async (variantId: string, quantity = 1) => {
-    await api.getState().addToCart([{ merchandiseId: variantId, quantity }]);
-    api.getState().openCart();
-  }, [api]);
+  const addToCart = useCallback(
+    async (
+      variantId: string,
+      quantity = 1,
+      attributeSelections?: CartAttributeSelectionInput[],
+    ) => {
+      await api.getState().addToCart([
+        {
+          merchandiseId: variantId,
+          quantity,
+          ...(attributeSelections && attributeSelections.length > 0
+            ? { attributeSelections }
+            : {}),
+        },
+      ]);
+      api.getState().openCart();
+    },
+    [api],
+  );
 
   /**
    * Execute the actual quantity update via SDK store.

package/templates/storefront-nextjs-shadcn/hooks/use-cart-sync.ts

@@ -6,6 +6,21 @@ import { useCartStore } from "@/stores/cart-store";
 import { useHydrated } from "@doswiftly/storefront-sdk/react";
 import type { CartLineFields } from "@/lib/graphql/fragments";
 
+/**
+ * Per-line attribute selection surfaced to cart UI (configurator choices).
+ * Mirroruje CartLine.attributeSelections z GraphQL, ale ograniczony do pól
+ * potrzebnych do wyświetlania — surchargeAmount kumulowany w cost.totalAmount
+ * (BUNDLED) lub emitowany jako child OrderItem po checkout (SEPARATE_LINE).
+ */
+export interface CartItemAttributeSelection {
+  attributeDefinitionId: string;
+  attributeName: string;
+  optionLabel?: string | null;
+  textValue?: string | null;
+  billingMode?: string | null;
+  surchargeAmount: number;
+}
+
 /**
  * Mapped cart item for display components.
  * Server is the single source of truth — no client-side items[].
@@ -22,6 +37,8 @@ export interface CartItemData {
   price: { amount: string; currencyCode: string };
   image?: { url: string; altText?: string | null } | null;
   available: boolean;
+  /** Faza 1 — customer configurator selections snapshot (empty when no configurator). */
+  attributeSelections: CartItemAttributeSelection[];
 }
 
 /**
@@ -78,6 +95,15 @@ export function useCartSync() {
       },
       image: line.merchandise.image || null,
       available: line.merchandise.available,
+      // Faza 1 — configurator selections (backend snapshot).
+      attributeSelections: (line.attributeSelections ?? []).map((sel) => ({
+        attributeDefinitionId: sel.attributeDefinitionId,
+        attributeName: sel.attributeName,
+        optionLabel: sel.optionLabel ?? null,
+        textValue: sel.textValue ?? null,
+        billingMode: sel.billingMode ?? null,
+        surchargeAmount: sel.surchargeAmount,
+      })),
     };
   });
 

package/templates/storefront-nextjs-shadcn/lib/image-loader.ts

@@ -0,0 +1,12 @@
+/**
+ * Passthrough image loader for Next.js.
+ *
+ * GraphQL API returns ready-to-use CDN URLs with transform query params
+ * (e.g., ?width=300). imgproxy auto-negotiates AVIF/WEBP from Accept header.
+ *
+ * No re-optimization needed — skips /_next/image proxy entirely.
+ * Browser loads directly from CDN (one hop, zero double-compression).
+ */
+export default function doswiftlyLoader({ src }: { src: string }): string {
+  return src;
+}

package/templates/storefront-nextjs-shadcn/next.config.ts

@@ -7,24 +7,13 @@ const nextConfig: NextConfig = {
   // Enable React strict mode for better development experience
   reactStrictMode: true,
 
-  // Image optimization — GraphQL API returns ready-to-use CDN URLs.
-  // Use url(transform: { maxWidth: 800 }) in queries. No client-side loader needed.
+  // Image optimization — GraphQL API returns ready-to-use CDN URLs with transform params.
+  // url(transform: { maxWidth: 800 }) in queries → imgproxy serves correct size.
+  // imgproxy auto-negotiates AVIF/WEBP from Accept header (IMGPROXY_AUTO_AVIF=true).
+  // Passthrough loader skips /_next/image proxy — browser loads directly from CDN.
   images: {
-    remotePatterns: [
-      {
-        protocol: 'https',
-        hostname: '**.doswiftly.pl',
-      },
-      {
-        protocol: 'https',
-        hostname: 'images.unsplash.com',
-      },
-      {
-        protocol: 'http',
-        hostname: 'app.localhost',
-        port: '8000',
-      },
-    ],
+    loader: 'custom',
+    loaderFile: './lib/image-loader.ts',
     dangerouslyAllowSVG: true,
     contentDispositionType: 'attachment',
   },

package/templates/storefront-nextjs-shadcn/package.json

@@ -15,7 +15,7 @@
     "@doswiftly/storefront-operations": "{{STOREFRONT_OPS_VERSION}}",
     "@doswiftly/storefront-sdk": "^4.0.0",
     "@tanstack/react-query": "^5.62.0",
-    "next": "^16.1.7",
+    "next": "^16.2.3",
     "react": "^19",
     "react-dom": "^19",
     "lucide-react": "latest",
@@ -34,7 +34,7 @@
     "zustand": "^5.0.2",
     "zod": "^3.23.8",
     "sonner": "^1.7.1",
-    "next-intl": "^4.1.0",
+    "next-intl": "^4.9.1",
     "next-themes": "^0.4.4",
     "react-hook-form": "^7.55.0",
     "@hookform/resolvers": "^5.2.0"