@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

package/content/pwav3/data-fetching.md

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

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

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