@salesforce/b2c-dx-mcp 0.4.4 → 0.4.6

package/content/pwav3/quick-reference.md

@@ -0,0 +1,169 @@
+# PWA Kit Development Quick Reference
+
+## Overview
+
+PWA Kit (Progressive Web App Kit) is Salesforce's solution for building high-performance, React-based e-commerce storefronts for Commerce Cloud. It provides server-side rendering (SSR), React Router integration, and seamless Commerce API integration through the commerce-sdk-react library.
+
+The Retail React App template serves as the foundation, demonstrating best practices for component architecture, data fetching, and state management using modern React patterns.
+
+## Core Architecture
+
+### Hybrid Rendering Model
+- **Server-Side Rendering (SSR)**: Initial page loads render on the server for fast First Contentful Paint and SEO
+- **Client-Side Rendering (CSR)**: After hydration, navigation happens client-side for fluid user interactions
+- **Isomorphic Code**: All application code must work in both Node.js (server) and browser (client) environments
+- **CDN Caching**: Server-rendered pages are cached at the edge for optimal performance
+
+### Express.js + React Stack
+- **Express.js**: Handles server-side routing and rendering
+- **React Router**: Manages client-side navigation and route definitions
+- **React 18**: UI library with Hooks, Suspense, and Concurrent Features
+- **Managed Runtime**: Salesforce's hosting platform for PWA Kit applications
+
+## Core Principles
+
+### Project Understanding
+- Thoroughly analyze requests and the existing project before implementation
+- Examine the current codebase to identify similar solutions and reusable components
+- Promptly clarify ambiguous requirements
+
+### Development Workflow
+Follow this workflow for all development tasks:
+
+1. **Analyze Requirements** - Clearly define objectives and functionalities
+2. **Review Existing Code** - Identify patterns and reusable components
+3. **Understand Available Tools** - Familiarize with hooks and utilities from commerce-sdk-react and template-retail-react-app
+4. **Plan Implementation** - Design component structure before coding
+5. **Implement Incrementally** - Develop and test in small, manageable steps
+6. **Test Thoroughly** - Ensure comprehensive testing with Jest and React Testing Library
+
+## Technical Stack
+
+### Core Technologies
+- **React** - UI components and single-page application architecture
+- **Express** - Server-side rendering and backend routing
+- **@salesforce/commerce-sdk-react** - Commerce Cloud API integration with React hooks
+- **PWA Kit** - SSR framework, routing, configuration, and Salesforce integration
+- **Chakra UI V2** - UI component library and theming system
+- **Emotion** - CSS-in-JS styling solution
+- **React Router** - Client-side routing
+- **React Intl** - Internationalization and localization
+- **React Query** - Data fetching, caching, and state synchronization
+- **Webpack** - Module bundling and code splitting
+- **React Testing Library & Jest** - Testing frameworks
+- **react-helmet** - HTML head tag management
+- **framer-motion** - Animation library
+- **ESLint & Prettier** - Code formatting and linting
+
+## Critical Non-Negotiable Rules
+
+### 1. Isomorphic Code Requirements
+```javascript
+import {useState, useEffect} from 'react';
+
+// ✅ CORRECT: Isomorphic code that works in both environments
+export const MyComponent = () => {
+    const [mounted, setMounted] = useState(false);
+
+    useEffect(() => {
+        // Client-only logic safely in useEffect
+        setMounted(true);
+        if (window.analytics) {
+            window.analytics.track('page_view');
+        }
+    }, []);
+
+    return <div>Component</div>;
+};
+
+// ❌ WRONG: Direct window access at module level
+const userAgent = window.navigator.userAgent; // Crashes on server!
+```
+
+### 2. No Secrets in Configuration
+```javascript
+// ❌ WRONG: Secrets in config files (serialized to client!)
+export default {
+    apiKey: 'sk_live_abc123', // EXPOSED TO BROWSER!
+    secretToken: process.env.SECRET // Still serialized!
+};
+
+// ✅ CORRECT: Use proxy requests for sensitive operations
+// Keep secrets in environment variables on the server only
+```
+
+### 3. Proxy Pattern for API Requests
+Always use the proxy pattern for external APIs to avoid CORS and improve performance:
+
+```javascript
+// Proxy configuration in config/default.js (merge into module.exports)
+module.exports = {
+    // ...other config
+    proxy: {
+        'external-api': {
+            host: 'https://api.example.com',
+            path: '/api'
+        }
+    }
+};
+
+// Request through proxy
+fetch('/mobify/proxy/external-api/endpoint')
+```
+
+### 4. Component File Naming
+- Use kebab-case for all file names: `product-tile.jsx`, `use-basket.js`
+- Only prefix with underscore for special components: `_app.jsx`, `_app-config.jsx`, `_error.jsx`
+
+## Quick Code Patterns
+
+**Reference the template for these patterns:**
+- **Fetch Commerce Data:** `app/pages/product-detail/index.jsx` (useProduct, useParams)
+- **Custom Hook:** `app/hooks/use-current-customer.js` (useCustomer, useCustomerId, useCustomerType)
+- **Routes:** `app/routes.jsx` (loadable, configureRoutes)
+- **Chakra UI:** `app/components/product-tile`, `app/components/shared/ui`
+
+## Quality Standards
+
+- **Code Formatting**: Maintain consistent formatting using Prettier and ESLint
+- **Test Coverage**: Write comprehensive tests for all business logic
+- **Accessibility**: Ensure components are keyboard navigable and screen reader friendly
+- **Mobile-First**: Design responsive layouts that work on all device sizes
+- **Security**: Follow OWASP best practices, never expose secrets
+- **Performance**: Monitor bundle sizes, use code splitting, optimize images
+
+## Common Commands
+
+```bash
+# Start development server
+npm start
+
+# Run tests
+npm test
+
+# Build for production
+npm run build
+
+# Lint code
+npm run lint
+
+# Extract and compile translations
+npm run build-translations
+# Or individually: extract-default-translations, compile-translations, compile-translations:pseudo
+
+# Run Lighthouse CI performance tests
+npm run test:lighthouse
+```
+
+## Documentation References
+
+For detailed information on specific topics, refer to the dedicated sections:
+- **Components**: Component patterns, Chakra UI, special components, React Hooks
+- **Data Fetching**: commerce-sdk-react hooks, custom APIs, React Query patterns
+- **Routing**: Express.js integration, React Router, SSR/CSR navigation
+- **Configuration**: Config files, environment variables, proxy setup, multi-site
+- **State Management**: Context API, useReducer, Redux integration patterns
+- **Extensibility**: Template extension, overrides directory, ccExtensibility configuration
+- **Testing**: Jest, React Testing Library, MSW, test organization
+- **Internationalization**: React Intl, translation workflows, multi-locale support
+- **Styling**: Chakra UI theming, Emotion CSS-in-JS, responsive design

package/content/pwav3/routing.md

@@ -0,0 +1,107 @@
+# Routing in PWA Kit
+
+## Overview
+
+PWA Kit uses Express.js (server-side) and React Router (client-side) for routing. Routes are defined in `app/routes.jsx` and support both SSR and client-side navigation. The template uses `loadable` for code-splitting and `configureRoutes` to add site/locale path segments.
+
+## Route Definition
+
+**Reference:** See `app/routes.jsx` in the template for the full setup (loadable, configureRoutes, dynamic routes, catch-all).
+
+To add a route: add to the `routes` array and ensure the default export passes them through `configureRoutes` with `fuzzyPathMatching: true`, then appends the catch-all `{ path: '*', component: PageNotFound }`.
+
+## Route Parameters
+
+```jsx
+import {useParams} from 'react-router-dom';
+
+const ProductDetail = () => {
+    const {productId} = useParams();
+
+    const {data: product} = useProduct({
+        parameters: {id: productId}
+    });
+
+    return <ProductView product={product} />;
+};
+```
+
+## Data Loading with React Query
+
+`withReactQuery` is applied at the **AppConfig** level (in `_app-config/index.jsx`), not per route. Route components use commerce-sdk-react hooks (e.g., `useProduct`) which integrate with React Query automatically. No need to wrap individual route components with `withReactQuery`.
+
+## Legacy getProps Pattern
+
+PWA Kit still supports `getProps` and `shouldGetProps` methods with long-term support. The template prefers commerce-sdk-react hooks for data fetching; use getProps when you need server-side prefetching.
+
+```jsx
+const ProductDetail = ({product}) => {
+    return <ProductView product={product} />;
+};
+
+// getProps receives {req, res, params, location} plus extraGetPropsArgs (buildUrl, site, locale)
+ProductDetail.getProps = async ({params}) => {
+    const {productId} = params;
+    // Use Commerce SDK client or fetch via proxy to prefetch product data
+    const product = await fetchProduct(productId);
+    return {product};
+};
+
+ProductDetail.shouldGetProps = ({previousParams, params}) => {
+    return previousParams?.productId !== params?.productId;
+};
+
+export default ProductDetail;
+```
+
+## Navigation
+
+### Programmatic Navigation
+
+```jsx
+import {useHistory} from 'react-router-dom';
+
+const ProductTile = ({product}) => {
+    const history = useHistory();
+
+    const navigateToProduct = () => {
+        history.push(`/product/${product.id}`);
+    };
+
+    return <Button onClick={navigateToProduct}>View Details</Button>;
+};
+```
+
+### Link Component
+
+```jsx
+import {Link} from 'react-router-dom';
+import {Button} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const ProductTile = ({product}) => {
+    return (
+        <Button as={Link} to={`/product/${product.id}`}>
+            View Details
+        </Button>
+    );
+};
+```
+
+## SSR vs CSR Navigation
+
+### Server-Side Rendering (First Load)
+- Initial page request goes to Express.js
+- Server renders React components to HTML
+- Data fetched on server
+- HTML sent to browser
+- Client-side JavaScript hydrates
+
+### Client-Side Rendering (Subsequent)
+- React Router handles routing
+- No full page reload
+- Data fetched via React Query
+- Smooth transitions
+
+## Lazy Loading Routes
+
+Use `@loadable/component` with a Skeleton fallback. See `app/routes.jsx` for the pattern.

package/content/pwav3/state-management.md

@@ -0,0 +1,193 @@
+# State Management
+
+## Overview
+
+PWA Kit applications support various state management approaches, from prop passing to global state using React Context API or Redux. The _app-config special component initializes state management systems.
+
+## React Context API (Recommended)
+
+The React Context API combined with useReducer provides simple, effective state management:
+
+```jsx
+import {createContext, useContext, useReducer} from 'react';
+
+// Create context
+const CartContext = createContext();
+
+// Define reducer
+const cartReducer = (state, action) => {
+    switch (action.type) {
+        case 'ADD_ITEM':
+            return {...state, items: [...state.items, action.payload]};
+        case 'REMOVE_ITEM':
+            return {...state, items: state.items.filter(item => item.id !== action.payload)};
+        case 'CLEAR_CART':
+            return {...state, items: []};
+        default:
+            return state;
+    }
+};
+
+// Provider component
+export const CartProvider = ({children}) => {
+    const [state, dispatch] = useReducer(cartReducer, {
+        items: [],
+        total: 0
+    });
+
+    return (
+        <CartContext.Provider value={{state, dispatch}}>
+            {children}
+        </CartContext.Provider>
+    );
+};
+
+// Custom hook
+export const useCart = () => {
+    const context = useContext(CartContext);
+    if (!context) {
+        throw new Error('useCart must be used within CartProvider');
+    }
+    return context;
+};
+```
+
+### Using Context in Components
+
+```jsx
+import {useCart} from '../contexts/cart-context';
+
+const ProductDetail = ({product}) => {
+    const {state, dispatch} = useCart();
+
+    const addToCart = () => {
+        dispatch({type: 'ADD_ITEM', payload: product});
+    };
+
+    return (
+        <Button onClick={addToCart}>
+            Add to Cart ({state.items.length} items)
+        </Button>
+    );
+};
+```
+
+### Integrating Context in _app-config
+
+```jsx
+// app/components/_app-config/index.jsx
+import {CartProvider} from '../../contexts/cart-context';
+import {MultiSiteProvider} from '../../contexts/multi-site-context';
+
+const AppConfig = ({children}) => {
+    return (
+        <CommerceApiProvider>
+            <ChakraProvider>
+                <MultiSiteProvider>
+                    <CartProvider>
+                        {children}
+                    </CartProvider>
+                </MultiSiteProvider>
+            </ChakraProvider>
+        </CommerceApiProvider>
+    );
+};
+
+export default AppConfig;
+```
+
+## Redux Integration
+
+PWA Kit supports Redux through AppConfig special methods:
+
+```jsx
+// app/components/_app-config/index.jsx
+import {Provider} from 'react-redux';
+import {createStore} from '../../store';
+
+const AppConfig = ({children, locals = {}}) => {
+    const store = createStore(locals.initialState);
+
+    return (
+        <Provider store={store}>
+            {children}
+        </Provider>
+    );
+};
+
+// Restore state from server
+AppConfig.restore = (locals = {}) => {
+    const store = createStore(locals.initialState);
+    return {initialState: store.getState()};
+};
+
+// Serialize state for SSR
+AppConfig.freeze = () => {
+    const store = window.__STORE__;
+    return {initialState: store.getState()};
+};
+
+// Provide extra arguments to getProps
+AppConfig.extraGetPropsArgs = () => {
+    return {store: window.__STORE__};
+};
+
+export default AppConfig;
+```
+
+## Local Component State
+
+For simple, component-specific state:
+
+```jsx
+import {useState} from 'react';
+
+const ProductImages = ({images}) => {
+    const [selectedIndex, setSelectedIndex] = useState(0);
+
+    return (
+        <Box>
+            <Image src={images[selectedIndex]} />
+            <Thumbnails
+                images={images}
+                onSelect={setSelectedIndex}
+            />
+        </Box>
+    );
+};
+```
+
+## Derived State with useMemo
+
+```jsx
+import {useMemo} from 'react';
+
+const Cart = ({items}) => {
+    const subtotal = useMemo(() => {
+        return items.reduce((sum, item) => sum + (item.price * item.quantity), 0);
+    }, [items]);
+
+    const tax = useMemo(() => subtotal * 0.08, [subtotal]);
+    const total = useMemo(() => subtotal + tax, [subtotal, tax]);
+
+    return (
+        <Box>
+            <Text>Subtotal: ${subtotal.toFixed(2)}</Text>
+            <Text>Tax: ${tax.toFixed(2)}</Text>
+            <Text>Total: ${total.toFixed(2)}</Text>
+        </Box>
+    );
+};
+```
+
+## Best Practices
+
+1. Keep state as local as possible
+2. Use Context for global UI state
+3. Use React Query for server state
+4. Avoid prop drilling
+5. Memoize expensive computations
+6. Keep reducer logic pure
+7. Type your state
+8. Normalize complex state
+9. Test reducers independently

package/content/pwav3/styling.md

@@ -0,0 +1,248 @@
+# Styling with Chakra UI and Emotion
+
+## Overview
+
+PWA Kit applications use Chakra UI V2 for component styling and theming, with Emotion as the underlying CSS-in-JS engine.
+
+## Chakra UI Components
+
+Import from the Retail React App shared/ui barrel for consistency with the template:
+
+```jsx
+import {
+    Box,
+    Flex,
+    Stack,
+    Button,
+    Heading,
+    Text,
+    Image
+} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const ProductCard = ({product}) => {
+    return (
+        <Box borderWidth="1px" borderRadius="lg" p={4}>
+            <Image src={product.image} alt={product.name} />
+            <Heading size="md" mt={2}>{product.name}</Heading>
+            <Text color="gray.600">${product.price}</Text>
+            <Button colorScheme="blue" mt={4} width="full">
+                Add to Cart
+            </Button>
+        </Box>
+    );
+};
+```
+
+## Style Props
+
+```jsx
+<Box
+    // Layout
+    display="flex"
+    flexDirection="column"
+    w="100%"
+    maxW="container.lg"
+
+    // Colors
+    bg="gray.50"
+    color="gray.800"
+
+    // Spacing
+    p={8}
+    px={4}
+    m={4}
+
+    // Typography
+    fontSize="lg"
+    fontWeight="bold"
+
+    // Borders
+    borderWidth="1px"
+    borderRadius="md"
+
+    // Effects
+    shadow="lg"
+
+    // Pseudo selectors
+    _hover={{bg: 'gray.100'}}
+/>
+```
+
+## Responsive Design
+
+```jsx
+<Box
+    // Array syntax: [base, sm, md, lg]
+    fontSize={['sm', 'md', 'lg', 'xl']}
+
+    // Object syntax
+    display={{base: 'block', md: 'flex'}}
+    width={{base: '100%', md: '50%'}}
+>
+    Content
+</Box>
+
+<SimpleGrid columns={{base: 1, sm: 2, md: 3, lg: 4}} spacing={6}>
+    {products.map(product => (
+        <ProductCard key={product.id} product={product} />
+    ))}
+</SimpleGrid>
+```
+
+## Theme Customization
+
+```javascript
+// app/theme/index.js (or overrides/app/theme/index.js)
+import baseTheme from '@salesforce/retail-react-app/app/theme';
+import {extendTheme} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const theme = extendTheme(baseTheme, {
+    colors: {
+        brand: {
+            50: '#e6f2ff',
+            500: '#0073e6',
+            900: '#00111a'
+        }
+    },
+    fonts: {
+        heading: 'Montserrat, sans-serif',
+        body: 'Open Sans, sans-serif'
+    },
+    components: {
+        Button: {
+            baseStyle: {
+                fontWeight: 'bold'
+            },
+            variants: {
+                solid: {
+                    bg: 'brand.500',
+                    color: 'white',
+                    _hover: {bg: 'brand.600'}
+                }
+            }
+        }
+    }
+});
+
+export default theme;
+```
+
+### Applying Theme
+
+```jsx
+// app/components/_app-config/index.jsx
+import {ChakraProvider} from '@salesforce/retail-react-app/app/components/shared/ui';
+import theme from '@salesforce/retail-react-app/app/theme';
+
+const AppConfig = ({children}) => {
+    return (
+        <ChakraProvider theme={theme}>
+            {children}
+        </ChakraProvider>
+    );
+};
+```
+
+## Emotion CSS-in-JS
+
+```jsx
+import {css} from '@emotion/react';
+
+const customStyles = css`
+    background: linear-gradient(90deg, #667eea 0%, #764ba2 100%);
+    border-radius: 8px;
+    transition: transform 0.2s;
+
+    &:hover {
+        transform: scale(1.05);
+    }
+`;
+
+const GradientBox = ({children}) => {
+    return <Box css={customStyles}>{children}</Box>;
+};
+```
+
+## Layout Components
+
+### Flex Layout
+
+```jsx
+<Flex direction="row" justify="space-between" align="center" gap={4}>
+    <Box>Item 1</Box>
+    <Box>Item 2</Box>
+</Flex>
+```
+
+### Grid Layout
+
+```jsx
+<Grid templateColumns="repeat(auto-fit, minmax(250px, 1fr))" gap={6}>
+    {products.map(product => (
+        <ProductCard key={product.id} product={product} />
+    ))}
+</Grid>
+```
+
+### Stack Layout
+
+```jsx
+<Stack direction="column" spacing={4}>
+    <Heading>Title</Heading>
+    <Text>Description</Text>
+    <Button>Action</Button>
+</Stack>
+```
+
+## Pseudo Selectors
+
+```jsx
+<Button
+    _hover={{
+        bg: 'brand.600',
+        transform: 'translateY(-2px)'
+    }}
+    _active={{
+        transform: 'translateY(0)'
+    }}
+    _focus={{
+        outline: '2px solid',
+        outlineColor: 'brand.500'
+    }}
+>
+    Click me
+</Button>
+```
+
+## Color Mode (Dark Mode)
+
+```jsx
+import {useColorMode, useColorModeValue} from '@chakra-ui/react';
+
+const ThemedComponent = () => {
+    const {colorMode, toggleColorMode} = useColorMode();
+    const bg = useColorModeValue('white', 'gray.800');
+    const color = useColorModeValue('gray.800', 'white');
+
+    return (
+        <Box bg={bg} color={color}>
+            <Button onClick={toggleColorMode}>
+                Toggle {colorMode === 'light' ? 'Dark' : 'Light'}
+            </Button>
+        </Box>
+    );
+};
+```
+
+## Best Practices
+
+1. Use Chakra UI components
+2. Leverage style props
+3. Make designs responsive
+4. Follow theme structure
+5. Use semantic HTML with `as` prop
+6. Ensure accessibility
+7. Optimize images
+8. Test in multiple browsers
+9. Use theme tokens
+10. Consider performance