@doswiftly/cli 0.1.18 → 0.1.19

package/templates/storefront-nextjs-shadcn/PRODUCT_DETAIL_PAGE_IMPLEMENTATION.md

@@ -1,307 +0,0 @@
-# Product Detail Page Implementation
-
-## Overview
-
-This document describes the implementation of the product detail page (Task 21) following the Next.js 15+ App Router architecture with Server Components and Client Components.
-
-## Implementation Summary
-
-### Files Created/Modified
-
-1. **`app/products/[slug]/page.tsx`** - Server Component (MODIFIED)
-   - Converted from Client Component to Server Component
-   - Added metadata generation for SEO
-   - Added structured data (JSON-LD) for search engines
-   - Added static params generation for top 100 products
-   - Implemented ISR with 60-second revalidation
-
-2. **`app/products/[slug]/product-client.tsx`** - Client Component (MODIFIED)
-   - Enhanced to handle SSR hydration with currency switching
-   - Added logic to refetch product data when user's preferred currency differs from SSR currency
-   - Added `suppressHydrationWarning` to prevent hydration mismatches
-   - Maintains selected variant across currency changes
-
-3. **`app/not-found.tsx`** - 404 Page (CREATED)
-   - Created custom 404 page for better error handling
-   - Provides helpful navigation back to the site
-
-## Architecture
-
-### Server Component Flow
-
-```
-1. Build Time (SSG)
-   ├─ generateStaticParams() fetches top 100 products
-   ├─ Pre-renders pages for each product handle
-   └─ Uses base currency (no X-Preferred-Currency header)
-
-2. Request Time
-   ├─ Server Component fetches product data (base currency)
-   ├─ Generates metadata (title, description, Open Graph)
-   ├─ Generates JSON-LD structured data
-   └─ Passes initial data to Client Component
-
-3. ISR Revalidation
-   └─ Pages revalidate every 60 seconds
-```
-
-### Client Component Flow
-
-```
-1. Initial Render
-   ├─ Receives product data from Server Component (base currency)
-   ├─ Displays product with SSR data
-   └─ suppressHydrationWarning prevents mismatch
-
-2. Currency Store Initialization
-   ├─ CurrencyProvider initializes from Shop data
-   ├─ Checks localStorage for saved currency
-   ├─ Detects browser locale
-   └─ Sets preferred currency
-
-3. Currency-Aware Refetch
-   ├─ Compares preferred currency vs SSR currency
-   ├─ If different, refetches product with new currency
-   ├─ Updates prices dynamically
-   └─ Maintains selected variant
-```
-
-## Key Features
-
-### 1. Metadata Generation (Requirement 13.1, 13.3)
-
-```typescript
-export async function generateMetadata({ params }): Promise<Metadata> {
-  const data = await fetchProduct(params.slug);
-  const product = data?.product;
-  
-  return {
-    title: product.title,
-    description: product.description,
-    openGraph: {
-      title: product.title,
-      description: product.description,
-      images: [product.images[0]],
-    },
-    twitter: {
-      card: "summary_large_image",
-      // ...
-    },
-  };
-}
-```
-
-**Benefits:**
-- Improved SEO with proper meta tags
-- Better social media sharing with Open Graph
-- Twitter Card support for rich previews
-
-### 2. Structured Data (JSON-LD) (Requirement 13.3)
-
-```typescript
-const jsonLd = {
-  "@context": "https://schema.org",
-  "@type": "Product",
-  name: product.title,
-  description: product.description,
-  image: product.images[0].url,
-  brand: { "@type": "Brand", name: product.vendor },
-  offers: {
-    "@type": "Offer",
-    price: product.priceRange.minVariantPrice.amount,
-    priceCurrency: product.priceRange.minVariantPrice.currencyCode,
-    availability: "https://schema.org/InStock",
-  },
-};
-```
-
-**Benefits:**
-- Rich snippets in search results
-- Better product visibility in Google Shopping
-- Improved search engine understanding
-
-### 3. Static Params Generation (Requirement 2.2, 6.4)
-
-```typescript
-export async function generateStaticParams() {
-  const { products } = await fetchProducts({
-    first: 100,
-    sortKey: "BEST_SELLING",
-  });
-  
-  return products.map((product) => ({
-    slug: product.handle,
-  }));
-}
-```
-
-**Benefits:**
-- Pre-renders top 100 products at build time
-- Instant page loads for popular products
-- Reduced server load
-- Better Core Web Vitals scores
-
-### 4. SSR with Client Hydration (Requirement 2.2, 3.2, 6.4)
-
-**Server Component:**
-```typescript
-export default async function ProductPage({ params }) {
-  const data = await fetchProduct(params.slug);
-  return <ProductClient product={data.product} />;
-}
-```
-
-**Client Component:**
-```typescript
-export function ProductClient({ product: initialProduct }) {
-  const currency = useCurrencyStore((s) => s.currency);
-  const needsRefetch = currency !== initialProduct.priceRange.minVariantPrice.currencyCode;
-  
-  const { data } = useProduct(initialProduct.handle, {
-    initialData: { product: initialProduct },
-    enabled: needsRefetch,
-  });
-  
-  const product = data?.product || initialProduct;
-  
-  return (
-    <div suppressHydrationWarning>
-      <ProductPrice price={product.priceRange.minVariantPrice} />
-    </div>
-  );
-}
-```
-
-**Benefits:**
-- Fast initial render with SSR
-- Dynamic currency switching without page reload
-- No hydration mismatches
-- Optimal user experience
-
-### 5. ISR Configuration
-
-```typescript
-export const revalidate = 60;
-```
-
-**Benefits:**
-- Pages stay fresh with 60-second revalidation
-- Maintains static generation benefits
-- Automatic updates when products change
-- No manual cache invalidation needed
-
-## Requirements Validation
-
-✅ **Requirement 2.2**: Server Component renders prices in base currency for SSG  
-✅ **Requirement 3.2**: Client Component renders prices in preferred currency  
-✅ **Requirement 6.4**: Clear separation between server and client data fetching  
-✅ **Requirement 13.1**: Metadata generation with title, description, Open Graph  
-✅ **Requirement 13.3**: Structured data (JSON-LD) with Product schema  
-
-## Testing Recommendations
-
-### Manual Testing
-
-1. **SSG Verification**
-   - Build the project: `npm run build`
-   - Check `.next/server/app/products/[slug]` for pre-rendered pages
-   - Verify top 100 products are statically generated
-
-2. **Metadata Verification**
-   - View page source in browser
-   - Check `<head>` for meta tags
-   - Verify Open Graph tags
-   - Test social media sharing
-
-3. **Structured Data Verification**
-   - View page source
-   - Find `<script type="application/ld+json">`
-   - Validate with Google's Rich Results Test
-   - Check schema.org compliance
-
-4. **Currency Switching**
-   - Load product page (should show base currency)
-   - Change currency in selector
-   - Verify prices update without page reload
-   - Check no hydration warnings in console
-
-5. **ISR Verification**
-   - Update product in backend
-   - Wait 60 seconds
-   - Refresh page
-   - Verify changes appear
-
-### Automated Testing
-
-```typescript
-// Example test for metadata generation
-describe('Product Page Metadata', () => {
-  it('should generate correct metadata', async () => {
-    const metadata = await generateMetadata({ params: { slug: 'test-product' } });
-    expect(metadata.title).toBeDefined();
-    expect(metadata.description).toBeDefined();
-    expect(metadata.openGraph).toBeDefined();
-  });
-});
-
-// Example test for static params
-describe('Static Params Generation', () => {
-  it('should generate params for top products', async () => {
-    const params = await generateStaticParams();
-    expect(params.length).toBeGreaterThan(0);
-    expect(params[0]).toHaveProperty('slug');
-  });
-});
-```
-
-## Performance Considerations
-
-1. **Static Generation**: Top 100 products are pre-rendered at build time
-2. **ISR**: Pages revalidate every 60 seconds for fresh data
-3. **React Cache**: Server-side requests are deduplicated within a render
-4. **Client-side Caching**: React Query caches product data with currency in key
-5. **Image Optimization**: Next.js Image component handles optimization
-
-## Future Enhancements
-
-1. **Related Products**: Add similar products section based on tags/category
-2. **Product Reviews**: Integrate review system with structured data
-3. **Variant Images**: Show variant-specific images when variant changes
-4. **Breadcrumbs**: Add dynamic breadcrumbs based on product category
-5. **Share Buttons**: Add social media share buttons
-6. **Recently Viewed**: Track and display recently viewed products
-
-## Troubleshooting
-
-### Hydration Mismatch Errors
-
-**Problem**: Console shows hydration mismatch warnings  
-**Solution**: Ensure `suppressHydrationWarning` is on price elements
-
-### Currency Not Switching
-
-**Problem**: Prices don't update when currency changes  
-**Solution**: Check currency store initialization and query key includes currency
-
-### 404 Errors
-
-**Problem**: Product pages return 404  
-**Solution**: Verify product handle matches exactly, check generateStaticParams
-
-### Metadata Not Showing
-
-**Problem**: Meta tags not appearing in page source  
-**Solution**: Ensure generateMetadata is async and returns Metadata object
-
-## Conclusion
-
-The product detail page implementation follows Next.js 15+ best practices with:
-- Server Components for optimal performance
-- Client Components for interactivity
-- Proper metadata for SEO
-- Structured data for search engines
-- Static generation for popular products
-- ISR for fresh data
-- Currency-aware price display
-
-This implementation satisfies all requirements (2.2, 3.2, 6.4, 13.1, 13.3) and provides a solid foundation for a production-ready e-commerce storefront.

package/templates/storefront-nextjs-shadcn/THEME_CUSTOMIZATION.md

@@ -1,245 +0,0 @@
-# Theme Customization Guide
-
-This guide explains how to customize the theme colors and appearance of your storefront.
-
-## Overview
-
-The storefront uses a theme system based on CSS variables and Tailwind CSS v4. The theme supports:
-- Light mode
-- Dark mode
-- System preference detection
-- Smooth transitions between themes
-- Persistent theme selection (localStorage)
-
-## Theme Configuration
-
-The main theme configuration is located in `lib/theme/theme-config.ts`:
-
-```typescript
-export const themeConfig = {
-  defaultTheme: "system",
-  themes: ["light", "dark", "system"],
-  enableSystem: true,
-  disableTransitionOnChange: false,
-  storageKey: "doswiftly-theme",
-  attribute: "class",
-  colors: {
-    light: { /* ... */ },
-    dark: { /* ... */ }
-  }
-}
-```
-
-## Customizing Colors
-
-### Method 1: Update CSS Variables (Recommended)
-
-Edit `app/globals.css` to change theme colors:
-
-```css
-@theme {
-  /* Light mode colors */
-  --color-primary: rgb(59 130 246); /* Change this */
-  --color-primary-foreground: rgb(255 255 255);
-  /* ... other colors */
-}
-
-.dark {
-  /* Dark mode colors */
-  --color-primary: rgb(96 165 250); /* Change this */
-  --color-primary-foreground: rgb(15 23 42);
-  /* ... other colors */
-}
-```
-
-### Method 2: Update Theme Config
-
-Edit `lib/theme/theme-config.ts`:
-
-```typescript
-export const themeConfig = {
-  // ...
-  colors: {
-    light: {
-      primary: "220 90% 56%", // HSL format
-      // ...
-    },
-    dark: {
-      primary: "220 90% 70%",
-      // ...
-    }
-  }
-}
-```
-
-## Available Color Variables
-
-The following CSS variables are available for customization:
-
-### Core Colors
-- `--color-background` - Main background color
-- `--color-foreground` - Main text color
-- `--color-primary` - Primary brand color
-- `--color-primary-foreground` - Text on primary color
-- `--color-secondary` - Secondary brand color
-- `--color-secondary-foreground` - Text on secondary color
-
-### UI Colors
-- `--color-muted` - Muted background (for disabled states, etc.)
-- `--color-muted-foreground` - Muted text color
-- `--color-accent` - Accent color (for highlights)
-- `--color-accent-foreground` - Text on accent color
-- `--color-border` - Border color
-- `--color-ring` - Focus ring color
-
-### Component Colors
-- `--color-card` - Card background
-- `--color-card-foreground` - Card text
-- `--color-destructive` - Error/danger color
-- `--color-destructive-foreground` - Text on destructive color
-
-## Brand Color Examples
-
-### Blue Theme (Default)
-```css
---color-primary: rgb(59 130 246); /* blue-500 */
-```
-
-### Green Theme
-```css
---color-primary: rgb(34 197 94); /* green-500 */
---color-accent: rgb(74 222 128); /* green-400 */
-```
-
-### Purple Theme
-```css
---color-primary: rgb(168 85 247); /* purple-500 */
---color-accent: rgb(192 132 252); /* purple-400 */
-```
-
-### Orange Theme
-```css
---color-primary: rgb(249 115 22); /* orange-500 */
---color-accent: rgb(251 146 60); /* orange-400 */
-```
-
-## Theme Switcher Components
-
-Three theme switcher variants are available:
-
-### 1. Simple Toggle (Default)
-```tsx
-import { ThemeSwitcher } from "@/components/layout/theme-switcher";
-
-<ThemeSwitcher />
-```
-
-### 2. Dropdown Menu
-```tsx
-import { ThemeSwitcherDropdown } from "@/components/layout/theme-switcher";
-
-<ThemeSwitcherDropdown />
-```
-
-### 3. Compact Buttons
-```tsx
-import { ThemeSwitcherCompact } from "@/components/layout/theme-switcher";
-
-<ThemeSwitcherCompact showLabel />
-```
-
-## Programmatic Theme Control
-
-Use the `useTheme` hook from `next-themes`:
-
-```tsx
-"use client";
-
-import { useTheme } from "next-themes";
-
-export function MyComponent() {
-  const { theme, setTheme, systemTheme } = useTheme();
-  
-  return (
-    <button onClick={() => setTheme("dark")}>
-      Switch to Dark Mode
-    </button>
-  );
-}
-```
-
-## Disable Theme Transitions
-
-To disable transitions when theme changes (prevents flash):
-
-```typescript
-// lib/theme/theme-config.ts
-export const themeConfig = {
-  // ...
-  disableTransitionOnChange: true, // Set to true
-}
-```
-
-## Custom Theme Storage
-
-To use a different storage key:
-
-```typescript
-// lib/theme/theme-config.ts
-export const themeConfig = {
-  // ...
-  storageKey: "my-custom-theme-key",
-}
-```
-
-## Force a Specific Theme
-
-To force light or dark mode without system detection:
-
-```typescript
-// lib/theme/theme-config.ts
-export const themeConfig = {
-  defaultTheme: "light", // or "dark"
-  enableSystem: false, // Disable system detection
-}
-```
-
-## Testing Themes
-
-1. **Manual Testing**: Use the theme switcher in the header
-2. **Browser DevTools**: Toggle dark mode in DevTools
-3. **System Preference**: Change your OS theme settings
-
-## Troubleshooting
-
-### Theme Flashing on Page Load
-
-Add `suppressHydrationWarning` to the `<html>` tag (already done in `app/layout.tsx`):
-
-```tsx
-<html lang="en" suppressHydrationWarning>
-```
-
-### Theme Not Persisting
-
-Check that localStorage is enabled and the storage key is correct in `theme-config.ts`.
-
-### Colors Not Updating
-
-1. Clear browser cache
-2. Restart dev server
-3. Check CSS variable names match in both `globals.css` and components
-
-## Best Practices
-
-1. **Use CSS Variables**: Always use CSS variables instead of hardcoded colors
-2. **Test Both Themes**: Ensure your custom colors work in both light and dark mode
-3. **Maintain Contrast**: Ensure sufficient contrast for accessibility (WCAG AA)
-4. **Consistent Naming**: Keep color variable names consistent across themes
-5. **Document Changes**: Document any custom color choices for your team
-
-## Resources
-
-- [next-themes Documentation](https://github.com/pacocoursey/next-themes)
-- [Tailwind CSS v4 Documentation](https://tailwindcss.com/docs)
-- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/)

package/templates/storefront-nextjs-shadcn/components/providers/currency-provider.tsx

@@ -1,103 +0,0 @@
-'use client';
-
-/**
- * CurrencyProvider - Initializes currency store with Shop data
- *
- * This provider:
- * 1. Receives Shop data from server (via root layout)
- * 2. Initializes currency store on mount
- * 3. Handles currency detection from:
- *    - localStorage (saved preference)
- *    - Browser locale (auto-detection)
- *    - Shop base currency (fallback)
- *
- * The currency store manages:
- * - User's preferred currency
- * - Supported currencies list
- * - Base currency for the shop
- * - Persistence to localStorage
- *
- * @module storefront-nextjs/components/providers/currency-provider
- */
-
-import { useEffect, type ReactNode } from 'react';
-import { useCurrencyStore, type ShopCurrencyData } from '@/stores/currency-store';
-
-// ============================================================================
-// TYPES
-// ============================================================================
-
-interface CurrencyProviderProps {
-  /**
-   * Shop data containing currency configuration
-   * Fetched from GraphQL Shop query in root layout
-   */
-  shopData: ShopCurrencyData;
-  
-  /**
-   * Child components
-   */
-  children: ReactNode;
-}
-
-// ============================================================================
-// COMPONENT
-// ============================================================================
-
-/**
- * CurrencyProvider - Initializes currency store with Shop data
- *
- * This component should be placed in the root layout after fetching Shop data.
- * It initializes the currency store once on mount, which triggers:
- * 1. Loading saved currency from localStorage (if valid)
- * 2. Auto-detecting currency from browser locale (if no saved preference)
- * 3. Falling back to shop's base currency
- *
- * The initialization only happens once per session. Subsequent currency changes
- * are handled by the currency store's setCurrency action.
- *
- * @example
- * ```tsx
- * // app/layout.tsx
- * import { fetchShop } from '@/lib/graphql/server';
- * import { CurrencyProvider } from '@/components/providers/currency-provider';
- *
- * export default async function RootLayout({ children }) {
- *   const { shop } = await fetchShop();
- *
- *   return (
- *     <html lang="en">
- *       <body>
- *         <QueryProvider>
- *           <CurrencyProvider shopData={shop}>
- *             <Header />
- *             <main>{children}</main>
- *             <Footer />
- *           </CurrencyProvider>
- *         </QueryProvider>
- *       </body>
- *     </html>
- *   );
- * }
- * ```
- *
- * @param props - Component props
- * @param props.shopData - Shop currency configuration
- * @param props.children - Child components to render
- */
-export function CurrencyProvider({ shopData, children }: CurrencyProviderProps) {
-  const initialize = useCurrencyStore((state: any) => state.initialize);
-  
-  useEffect(() => {
-    // Initialize currency store with Shop data
-    // This will:
-    // 1. Set base currency and supported currencies
-    // 2. Restore saved currency from localStorage (if valid)
-    // 3. Auto-detect from browser locale (if no saved preference)
-    // 4. Fall back to base currency
-    initialize(shopData);
-  }, [shopData, initialize]);
-  
-  // Simply render children - the store initialization happens in the background
-  return <>{children}</>;
-}