@salesforce/b2c-dx-mcp 0.4.4 → 0.4.6

package/content/pwav3/data-fetching.md

@@ -0,0 +1,213 @@
+# Data Fetching and Commerce API Integration
+
+## Overview
+
+PWA Kit applications fetch data from Salesforce Commerce Cloud APIs using the `@salesforce/commerce-sdk-react` library. This library provides React hooks built on top of React Query for data fetching, caching, and state management.
+
+## Commerce SDK React Hooks
+
+### Standard Commerce API Hooks
+
+The commerce-sdk-react library provides hooks for all standard Commerce APIs:
+
+```jsx
+import {
+    useProduct,
+    useProducts,
+    useCategory,
+    useCustomer,
+    useBasket,
+    useCustomerBaskets,
+    useProductSearch,
+    useShopperBasketsMutation
+} from '@salesforce/commerce-sdk-react';
+```
+
+### Basic Usage Pattern
+
+**Reference:** See `app/pages/product-detail/index.jsx` for useProduct with useParams, loading/error states. Pattern: `const {data, isLoading, error, refetch} = useProduct({parameters: {id, allImages, perPricebook}})`.
+
+## Custom API Implementation
+
+For custom Commerce Cloud APIs (OCAPI Data API or SCAPI custom endpoints), use `useCustomQuery` and `useCustomMutation`.
+
+### useCustomQuery for GET Requests
+
+```jsx
+import {useCustomQuery} from '@salesforce/commerce-sdk-react';
+
+const MyComponent = () => {
+    const {data, isLoading, error} = useCustomQuery({
+        options: {
+            method: 'GET',
+            customApiPathParameters: {
+                apiName: 'store-locations',
+                apiVersion: 'v1',
+                endpointPath: 'locations'
+            },
+            parameters: {
+                c_latitude: 37.7749,
+                c_longitude: -122.4194,
+                c_radius: 50
+            }
+        }
+    });
+
+    if (isLoading) return <Spinner />;
+    if (error) return <ErrorMessage error={error} />;
+
+    return <StoreList stores={data?.stores} />;
+};
+```
+
+### Critical Rules for customApiPathParameters
+
+**DO NOT include extra '/' before or after path parameters:**
+
+```javascript
+// ✅ CORRECT
+customApiPathParameters: {
+    apiName: 'store-locations',
+    apiVersion: 'v1',
+    endpointPath: 'locations'
+}
+
+// ❌ WRONG - Extra slashes
+customApiPathParameters: {
+    apiName: '/store-locations/',
+    apiVersion: '/v1/',
+    endpointPath: '/locations'
+}
+```
+
+### useCustomMutation for POST/PUT/PATCH/DELETE
+
+```jsx
+import {useCustomMutation} from '@salesforce/commerce-sdk-react';
+
+const StoreLocator = () => {
+    const mutation = useCustomMutation({
+        options: {
+            method: 'POST',
+            customApiPathParameters: {
+                apiName: 'store-locator',
+                apiVersion: 'v1',
+                endpointPath: 'find-nearest'
+            }
+        }
+    });
+
+    const findNearestStore = () => {
+        mutation.mutate({
+            body: {
+                latitude: 37.7749,
+                longitude: -122.4194
+            },
+            parameters: {
+                c_maxResults: 5
+            },
+            headers: {
+                'X-Custom-Header': 'value'
+            }
+        });
+    };
+
+    return (
+        <div>
+            <Button onClick={findNearestStore} isLoading={mutation.isLoading}>
+                Find Nearest Store
+            </Button>
+            {mutation.isSuccess && <StoreList stores={mutation.data.stores} />}
+            {mutation.isError && <ErrorMessage error={mutation.error} />}
+        </div>
+    );
+};
+```
+
+### mutation.mutate() Arguments
+
+The `mutation.mutate(args)` function accepts:
+- **body** (Object): Request payload for POST/PUT/PATCH methods
+- **parameters** (Object): Optional query parameters
+- **headers** (Object): Optional custom headers
+
+## Custom Hooks Pattern
+
+Create custom hooks to encapsulate data fetching logic. **Reference:** See `app/hooks/use-current-customer.js` in the template.
+
+## React Query Integration
+
+PWA Kit uses React Query under the hood. Access the query client for advanced operations:
+
+```jsx
+import {useQueryClient} from '@tanstack/react-query';
+import {useParams} from 'react-router-dom';
+
+const ProductDetail = () => {
+    const {productId} = useParams();
+    const queryClient = useQueryClient();
+
+    const handleUpdate = async () => {
+        // Invalidate and refetch
+        await queryClient.invalidateQueries(['product', productId]);
+
+        // Or manually update cache
+        queryClient.setQueryData(['product', productId], (old) => ({
+            ...old,
+            viewed: true
+        }));
+    };
+
+    return <div>...</div>;
+};
+```
+
+## Caching Strategies
+
+### Default Cache Behavior (Template Override)
+
+The Retail React App _app-config overrides React Query defaults:
+- **staleTime**: 10 seconds
+- **retry**: false
+- **refetchOnWindowFocus**: false
+
+### Custom Cache Configuration
+
+```jsx
+const {data} = useProduct({
+    parameters: {id: productId},
+    staleTime: 10 * 60 * 1000, // 10 minutes
+    cacheTime: 30 * 60 * 1000, // 30 minutes (React Query v4; gcTime in v5)
+    refetchOnWindowFocus: false
+});
+```
+
+## Error Handling
+
+```jsx
+import {useProduct} from '@salesforce/commerce-sdk-react';
+import {useParams} from 'react-router-dom';
+import {Box, Alert, AlertIcon, AlertTitle, AlertDescription, Button} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const ProductDetail = () => {
+    const {productId} = useParams();
+    const {data, error, isError, refetch} = useProduct({
+        parameters: {id: productId}
+    });
+
+    if (isError) {
+        return (
+            <Alert status="error">
+                <AlertIcon />
+                <Box flex="1">
+                    <AlertTitle>Failed to load product</AlertTitle>
+                    <AlertDescription>{error.message}</AlertDescription>
+                </Box>
+                <Button size="sm" onClick={() => refetch()}>Retry</Button>
+            </Alert>
+        );
+    }
+
+    return <ProductView product={data} />;
+};
+```

package/content/pwav3/extensibility.md

@@ -0,0 +1,167 @@
+# PWA Kit Extensibility
+
+## Overview
+
+PWA Kit v3 provides an extensibility system to extend a base template (like @salesforce/retail-react-app) and override specific files while inheriting the rest.
+
+## Configuration
+
+Configure extensibility in `package.json`:
+
+```json
+{
+  "ccExtensibility": {
+    "extends": "@salesforce/retail-react-app",
+    "overridesDir": "overrides"
+  },
+  "dependencies": {
+    "@salesforce/retail-react-app": "^3.0.0"
+  }
+}
+```
+
+### Configuration Properties
+
+- **extends**: The npm package name of the base template
+- **overridesDir**: Directory containing override files (default: "overrides")
+
+## Overriding Files
+
+To override a file, recreate its exact path in your overrides directory:
+
+```
+Base template:
+@salesforce/retail-react-app/app/components/header/index.jsx
+
+Your override:
+overrides/app/components/header/index.jsx
+```
+
+### Example Override Structure
+
+```
+my-custom-storefront/
+├── overrides/
+│   ├── app/
+│   │   ├── components/
+│   │   │   ├── header/
+│   │   │   │   └── index.jsx   # Overrides base header
+│   │   │   └── footer/
+│   │   │       └── index.jsx   # Overrides base footer
+│   │   └── theme/
+│   │       └── index.js        # Overrides base theme
+│   └── config/
+│       └── default.js          # Overrides base config
+├── package.json
+└── README.md
+```
+
+## Overriding Components
+
+### Simple Component Override
+
+```jsx
+// overrides/app/components/header/index.jsx
+import {Box, Heading} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const Header = () => {
+    return (
+        <Box bg="brand.500" p={4}>
+            <Heading color="white">My Custom Store</Heading>
+        </Box>
+    );
+};
+
+export default Header;
+```
+
+### Importing from Base Template
+
+```jsx
+// overrides/app/components/header/index.jsx
+import {Box} from '@salesforce/retail-react-app/app/components/shared/ui';
+import Navigation from '@salesforce/retail-react-app/app/components/list-menu';
+import SearchBar from '@salesforce/retail-react-app/app/components/search';
+
+const Header = () => {
+    return (
+        <Box>
+            <SearchBar />
+            <Navigation />
+        </Box>
+    );
+};
+
+export default Header;
+```
+
+### Extending Base Component
+
+```jsx
+// overrides/app/components/product-tile/index.jsx
+import BaseProductTile from '@salesforce/retail-react-app/app/components/product-tile';
+import {Badge, Box} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const ProductTile = (props) => {
+    return (
+        <Box position="relative">
+            {props.product.isNew && (
+                <Badge position="absolute" top={2} right={2} colorScheme="green">
+                    New
+                </Badge>
+            )}
+            <BaseProductTile {...props} />
+        </Box>
+    );
+};
+
+export default ProductTile;
+```
+
+## Overriding Configuration
+
+### Custom Theme
+
+```javascript
+// 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 customTheme = extendTheme(baseTheme, {
+    colors: {
+        brand: {
+            50: '#e6f2ff',
+            500: '#0066cc',
+            900: '#003366'
+        }
+    }
+});
+
+export default customTheme;
+```
+
+### Custom Configuration
+
+```javascript
+// overrides/config/default.js
+const baseConfig = require('@salesforce/retail-react-app/config/default');
+
+module.exports = {
+    ...baseConfig,
+    app: {
+        ...baseConfig.app,
+        defaultSite: 'MyCustomSite',
+        storeLocatorEnabled: true,
+        customFeatureEnabled: true
+    }
+};
+```
+
+## Best Practices
+
+1. **Minimize Overrides** - Only override what you need
+2. **Import from Base** - Reuse components from base template
+3. **Extend, Don't Replace** - Wrap or extend base components
+4. **Document Overrides** - Keep clear records of changes
+5. **Test Thoroughly** - Ensure overrides work correctly
+6. **Keep Up to Date** - Review base template updates

package/content/pwav3/i18n.md

@@ -0,0 +1,214 @@
+# Internationalization (i18n)
+
+## Overview
+
+PWA Kit applications use React Intl for internationalization and localization. The system supports multiple locales, currency formats, date formats, and translated messages.
+
+## React Intl Integration
+
+```jsx
+import {IntlProvider, FormattedMessage, FormattedNumber, FormattedDate} from 'react-intl';
+```
+
+## Translation Files
+
+Translations live at project root; compiled output goes to `app/static/translations/compiled/`:
+
+```
+project-root/
+├── translations/
+│   ├── en-US.json
+│   ├── en-GB.json
+│   └── fr-FR.json
+└── app/
+    └── static/
+        └── translations/
+            └── compiled/
+                ├── en-US.json
+                ├── en-GB.json
+                └── en-XA.json   # pseudo-locale for testing
+```
+
+### Message Format
+
+```json
+{
+    "product.add_to_cart": "Add to Cart",
+    "product.price": "Price: {price}",
+    "cart.item_count": "{count, plural, =0 {No items} one {1 item} other {# items}}"
+}
+```
+
+## Defining Messages
+
+### Using defineMessage
+
+```jsx
+import {defineMessage, useIntl} from 'react-intl';
+import {Button} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const messages = {
+    addToCart: defineMessage({
+        id: 'product.add_to_cart',
+        defaultMessage: 'Add to Cart'
+    })
+};
+
+const ProductTile = ({product}) => {
+    const intl = useIntl();
+    return (
+        <Button>{intl.formatMessage(messages.addToCart)}</Button>
+    );
+};
+```
+
+### Using FormattedMessage
+
+```jsx
+import {FormattedMessage} from 'react-intl';
+
+<FormattedMessage
+    id="product.add_to_cart"
+    defaultMessage="Add to Cart"
+/>
+```
+
+## Message Formatting
+
+### With Variables
+
+```jsx
+<FormattedMessage
+    id="product.price"
+    defaultMessage="Price: {price}"
+    values={{price: product.price}}
+/>
+```
+
+### Pluralization
+
+```jsx
+<FormattedMessage
+    id="cart.item_count"
+    defaultMessage="{count, plural, =0 {No items} one {1 item} other {# items}}"
+    values={{count: itemCount}}
+/>
+```
+
+### Date and Number Formatting
+
+```jsx
+import {FormattedDate, FormattedNumber} from 'react-intl';
+
+<FormattedDate
+    value={new Date()}
+    year="numeric"
+    month="long"
+    day="numeric"
+/>
+
+<FormattedNumber
+    value={product.price}
+    style="currency"
+    currency="USD"
+/>
+```
+
+## useIntl Hook
+
+```jsx
+import {useIntl} from 'react-intl';
+import {Text} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const ProductDetail = ({product}) => {
+    const intl = useIntl();
+
+    const formattedPrice = intl.formatNumber(product.price, {
+        style: 'currency',
+        currency: 'USD'
+    });
+
+    return <Text>{formattedPrice}</Text>;
+};
+```
+
+## Translation Extraction
+
+```bash
+# Extract default messages (en-US, en-GB)
+npm run extract-default-translations
+
+# Compile translations
+npm run compile-translations
+
+# Compile pseudo-locale for testing
+npm run compile-translations:pseudo
+```
+
+## Multi-Locale Configuration
+
+Sites and locales are defined in `config/sites.js`:
+
+```javascript
+// config/sites.js
+module.exports = [
+    {
+        id: 'RefArch',
+        l10n: {
+            supportedCurrencies: ['USD'],
+            defaultCurrency: 'USD',
+            defaultLocale: 'en-US',
+            supportedLocales: [
+                { id: 'en-US', preferredCurrency: 'USD' },
+                { id: 'en-CA', preferredCurrency: 'USD' }
+            ]
+        }
+    }
+];
+```
+
+## Locale Switcher
+
+```jsx
+import {useIntl} from 'react-intl';
+import {useHistory, useLocation} from 'react-router-dom';
+import {Select} from '@salesforce/retail-react-app/app/components/shared/ui';
+
+const LocaleSwitcher = ({supportedLocales}) => {
+    const intl = useIntl();
+    const history = useHistory();
+    const location = useLocation();
+
+    const handleChange = (e) => {
+        const newLocale = e.target.value;
+        const newPath = location.pathname.replace(
+            `/${intl.locale}/`,
+            `/${newLocale}/`
+        );
+        history.push(newPath);
+    };
+
+    return (
+        <Select value={intl.locale} onChange={handleChange}>
+            {supportedLocales.map((locale) => (
+                <option key={locale.id} value={locale.id}>
+                    {locale.id}
+                </option>
+            ))}
+        </Select>
+    );
+};
+```
+
+## Best Practices
+
+1. Always use translation keys
+2. Provide defaultMessage
+3. Use semantic key names
+4. Extract regularly
+5. Compile for production
+6. Test with pseudo-locale
+7. Consider text expansion
+8. Format dates and numbers
+9. Handle pluralization
+10. Document context