@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/content/pwav3/quick-reference.md

@@ -1,169 +0,0 @@
-# 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

@@ -1,107 +0,0 @@
-# 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

@@ -1,193 +0,0 @@
-# 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

@@ -1,248 +0,0 @@
-# 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