@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/content/guidance/storefront-next/sfnext-i18n/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: sfnext-i18n
+description: Implement internationalization in Storefront Next using i18next with useTranslation for components and getTranslation for server-side code. Use when adding translations, configuring locales, handling pluralization, using the Zod schema factory pattern, or managing extension translations. Covers namespaces, interpolation, and language switching.
+---
+
+# Internationalization (i18n) Skill
+
+This skill covers internationalization in Storefront Next using i18next with a dual-instance architecture (server + client).
+
+## Overview
+
+- **Server instance** — Has access to all translations for all languages
+- **Client instance** — Dynamically imports translations as JavaScript chunks
+- **Dual API** — `useTranslation()` for components, `getTranslation()` for non-component code
+
+## Translation File Structure
+
+Translations are organized as namespace files per locale, compiled into a TypeScript index:
+
+```
+src/locales/en-US/
+├── index.ts              # Merges all namespace files + extensions
+├── translations.json     # Default namespace (top-level keys become namespaces)
+└── product.json          # "product" namespace (separate file)
+
+src/locales/en-GB/
+├── index.ts
+├── translations.json
+└── product.json
+```
+
+The `index.ts` imports all namespace files and extension translations:
+
+```typescript
+import translations from '@/locales/en-US/translations.json';
+import product from '@/locales/en-US/product.json';
+import extensionTranslations from '@/extensions/locales/en-US/';
+
+const allTranslations = { ...translations, product, ...extensionTranslations };
+export default allTranslations satisfies ResourceLanguage;
+```
+
+### Namespace structure in `translations.json`
+
+Each top-level key is a namespace:
+
+```json
+{
+    "header": {
+        "search": "Search",
+        "account": "Account"
+    },
+    "footer": {
+        "copyright": "© {{year}} Company"
+    }
+}
+```
+
+### Separate namespace file (`product.json`)
+
+```json
+{
+    "title": "Product Details",
+    "addToCart": "Add to Cart",
+    "greeting": "Hello, {{name}}!",
+    "itemCount_one": "{{count}} item",
+    "itemCount_other": "{{count}} items"
+}
+```
+
+## Usage in Components
+
+```typescript
+import { useTranslation } from 'react-i18next';
+
+export function ProductCard() {
+    const { t } = useTranslation('product');
+
+    return (
+        <div>
+            <h1>{t('title')}</h1>
+            <button>{t('addToCart')}</button>
+            <p>{t('greeting', { name: 'John' })}</p>
+            <p>{t('itemCount', { count: 5 })}</p>
+        </div>
+    );
+}
+```
+
+**Critical:** Always pass a namespace to `useTranslation()`:
+
+```typescript
+// WRONG — missing namespace
+const { t } = useTranslation();
+t('title');  // Will not find the key
+
+// CORRECT — with namespace
+const { t } = useTranslation('product');
+t('title');  // Works
+```
+
+## Usage in Server Code
+
+```typescript
+import { getTranslation } from '@/lib/i18next';
+
+// In loaders/actions (pass context)
+export function loader(args: LoaderFunctionArgs) {
+    const { t } = getTranslation(args.context);
+    return { title: t('product:title') };
+}
+
+// Client-side utilities (no context)
+const { t } = getTranslation();
+const message = t('product:addToCart');
+```
+
+## Validation Schemas — Factory Pattern
+
+**Critical:** Use a factory function for Zod schemas with translated messages to avoid race conditions:
+
+```typescript
+// WRONG — Module-level schema (race condition: t() may not be initialized)
+export const schema = z.object({
+    email: z.string().email(t('validation:emailInvalid'))
+});
+
+// CORRECT — Factory function
+import type { TFunction } from 'i18next';
+
+export const createSchema = (t: TFunction) => {
+    return z.object({
+        email: z.string().email(t('validation:emailInvalid'))
+    });
+};
+
+// Usage in component
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+function MyForm() {
+    const { t } = useTranslation();
+    const schema = useMemo(() => createSchema(t), [t]);
+
+    const form = useForm({ resolver: zodResolver(schema) });
+}
+```
+
+## Language Switching
+
+```typescript
+import LocaleSwitcher from '@/components/locale-switcher';
+
+export function Footer() {
+    return <footer><LocaleSwitcher /></footer>;
+}
+```
+
+## Extension Translations
+
+Extensions use `extPascalCase` namespace auto-derived from the extension directory name:
+
+```
+src/extensions/my-extension/locales/
+├── en-US/translations.json
+└── it-IT/translations.json
+```
+
+```typescript
+const { t } = useTranslation('extMyExtension');
+t('welcome');
+```
+
+## Common Pitfalls
+
+| Pitfall | Problem | Solution |
+|---------|---------|----------|
+| Missing namespace | Keys not found | Always pass namespace: `useTranslation('product')` |
+| Module-level `t()` in schemas | Race condition on initialization | Use factory pattern: `createSchema(t)` |
+| Forgetting context on server | Translations not found | Use `getTranslation(args.context)` in loaders |
+| Duplicate keys across namespaces | Wrong translation shown | Prefix with namespace: `t('product:title')` |
+
+## Related Skills
+
+- `storefront-next:sfnext-components` - Using translations in UI components
+- `storefront-next:sfnext-extensions` - Extension translation namespacing
+- `storefront-next:sfnext-configuration` - Locale and site configuration

package/content/guidance/storefront-next/sfnext-page-designer/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: sfnext-page-designer
+description: Integrate Page Designer with Storefront Next using React decorators, component registry, and Region rendering. Use when creating merchant-editable pages, adding Page Designer components with @Component/@AttributeDefinition decorators, using fetchPageFromLoader, or rendering Regions. This is for the React/Storefront Next implementation — for classic ISML Page Designer, see b2c:b2c-page-designer.
+---
+
+# Page Designer Skill
+
+This skill covers Page Designer integration in Storefront Next — building merchant-editable pages with React components, decorators, and the Shopper Experience API.
+
+## Overview
+
+Page Designer is Commerce Cloud's visual editor for merchants. In Storefront Next, page structure (regions, components, attributes) is fetched from the Shopper Experience API and rendered via a component registry and `<Region>` component.
+
+| Concept | Role |
+|---------|------|
+| **Page** | Fetched in route loaders via `fetchPageFromLoader(args, { pageId })` |
+| **Region** | Named area rendered with `<Region page={...} regionId="..." />` |
+| **Component** | Content block with a `typeId` and attributes; registered in `@/lib/registry` |
+| **Registry** | Static registry auto-generated by Vite plugin — do not edit by hand |
+
+## Which Pages Use Page Designer
+
+| Uses Page Designer | Does Not |
+|--------------------|----------|
+| Home (`homepage`), Category/PLP, Search, Product/PDP | Cart, Checkout, Account, Auth |
+
+## Route Setup
+
+### In the Loader
+
+```typescript
+import { fetchPageFromLoader, collectComponentDataPromises } from '@/lib/page-designer';
+
+export function loader(args: LoaderFunctionArgs) {
+    const pagePromise = fetchPageFromLoader(args, { pageId: 'homepage' });
+    const componentData = collectComponentDataPromises(args, pagePromise);
+
+    return {
+        page: pagePromise,
+        componentData,
+    };
+}
+```
+
+### In the Layout
+
+```typescript
+import { Region } from '@/components/region';
+
+export default function HomePage({ loaderData: { page, componentData } }) {
+    return (
+        <div>
+            <Region page={page} regionId="hero" componentData={componentData}
+                fallbackElement={<HeroSkeleton />}
+                errorElement={<RegionError />} />
+
+            <Region page={page} regionId="content" componentData={componentData}
+                fallbackElement={<ContentSkeleton />} />
+        </div>
+    );
+}
+```
+
+## Component Setup
+
+### Metadata Class with Decorators
+
+```typescript
+import { Component, AttributeDefinition, RegionDefinition } from '@salesforce/storefront-next-runtime/design';
+
+@Component('hero-banner', {
+    name: 'Hero Banner',
+    description: 'Full-width banner with image and CTA'
+})
+class HeroBannerMeta {
+    @AttributeDefinition({ type: 'image' })
+    image: string;
+
+    @AttributeDefinition()
+    headline: string;
+
+    @AttributeDefinition({ type: 'url' })
+    ctaUrl: string;
+
+    @AttributeDefinition()
+    ctaText: string;
+
+    @AttributeDefinition({ type: 'boolean' })
+    fullWidth: boolean;
+}
+```
+
+### React Component
+
+```typescript
+export default function HeroBanner({ image, headline, ctaUrl, ctaText, fullWidth }) {
+    return (
+        <div className={cn('relative', fullWidth && 'w-full')}>
+            <DynamicImage src={image} alt={headline} />
+            <h1>{headline}</h1>
+            {ctaUrl && <a href={ctaUrl}>{ctaText}</a>}
+        </div>
+    );
+}
+```
+
+See [Decorator Patterns Reference](references/DECORATOR-PATTERNS.md) for all decorator options.
+
+### Components with Server Data
+
+If a component needs server data (e.g., product carousel):
+
+```typescript
+// Export a loader for the component
+export function loader({ componentData, context }) {
+    const clients = createApiClients(context);
+    return clients.shopperProducts.getProducts({
+        params: { query: { ids: componentData.productIds } }
+    }).then(({ data }) => data);
+}
+
+// Optional fallback during loading
+export function fallback() {
+    return <CarouselSkeleton />;
+}
+
+// Component receives data as prop
+export default function ProductCarousel({ data, ...props }) {
+    return <Carousel products={data.products} />;
+}
+```
+
+See [Component Registry Reference](references/COMPONENT-REGISTRY.md) for registry details.
+
+## Design Mode
+
+Detect when running inside Page Designer:
+
+```typescript
+import { isDesignModeActive, isPreviewModeActive } from '@salesforce/storefront-next-runtime/design/mode';
+
+// In loaders
+const isDesignMode = isDesignModeActive(request);
+const isPreview = isPreviewModeActive(request);
+
+// Root layout exposes pageDesignerMode in loader data
+// 'EDIT' | 'PREVIEW' | undefined
+```
+
+## MCP Tools
+
+Use the B2C DX MCP server tools for Page Designer development:
+
+1. **`storefront_next_page_designer_decorator`** — Adds decorators to components (auto mode or interactive)
+2. **`storefront_next_generate_page_designer_metadata`** — Generates metadata JSON for Business Manager
+3. **`cartridge_deploy`** — Deploys cartridge to Commerce Cloud
+
+### Typical Workflow
+
+1. Add decorators to component (use `storefront_next_page_designer_decorator` with autoMode)
+2. Generate metadata JSON (`storefront_next_generate_page_designer_metadata`)
+3. Deploy cartridge (`cartridge_deploy`)
+
+## Best Practices
+
+1. **Keep loaders synchronous** — Return promises for streaming
+2. **Use registry** — Register components with proper `typeId`
+3. **Handle design mode** — Adapt UI when `pageDesignerMode` is `'EDIT'` or `'PREVIEW'`
+4. **Rebuild after changes** — Static registry regenerates at build time
+5. **Use MCP tools** — Faster than hand-writing decorators and metadata
+
+## Related Skills
+
+- `storefront-next:sfnext-data-fetching` - Loader patterns for Page Designer routes
+- `storefront-next:sfnext-components` - Component development patterns
+- `b2c:b2c-page-designer` - Classic ISML Page Designer (NOT Storefront Next)
+
+## Reference Documentation
+
+- [Decorator Patterns Reference](references/DECORATOR-PATTERNS.md) - All decorator types and options
+- [Component Registry Reference](references/COMPONENT-REGISTRY.md) - Registry setup and component loaders

package/content/guidance/storefront-next/sfnext-page-designer/references/COMPONENT-REGISTRY.md

@@ -0,0 +1,78 @@
+# Component Registry Reference
+
+## Overview
+
+The component registry maps Page Designer `typeId` values to React components. The registry is **auto-generated** at build time by the staticRegistry Vite plugin.
+
+## Static Registry
+
+The file `src/lib/static-registry.ts` is generated automatically. **Do not edit it by hand.** The Vite plugin scans for components with `@Component` decorators and builds the registry.
+
+After adding or modifying decorators, rebuild the app to regenerate the registry:
+
+```bash
+pnpm build
+# or during development
+pnpm dev   # Hot reload regenerates automatically
+```
+
+## Component Registration
+
+Components are registered by their `@Component` decorator `typeId`:
+
+```typescript
+// The registry maps typeId -> component module
+// Example auto-generated entry:
+{
+    'hero-banner': () => import('@/components/hero-banner'),
+    'product-carousel': () => import('@/components/product-carousel'),
+    'content-card': () => import('@/components/content-card'),
+}
+```
+
+## Component Loaders
+
+Components that need server data export a `loader` function. The registry calls these loaders during `collectComponentDataPromises()` in the route loader:
+
+```typescript
+// In the component file:
+export function loader({ componentData, context }) {
+    const clients = createApiClients(context);
+    const productIds = componentData.productIds;
+
+    return clients.shopperProducts.getProducts({
+        params: { query: { ids: productIds.join(',') } }
+    }).then(({ data }) => data);
+}
+
+export function fallback() {
+    return <ProductCarouselSkeleton />;
+}
+
+export default function ProductCarousel({ data, ...props }) {
+    // data = resolved result from loader
+    return <div>{data.products.map(p => <ProductTile key={p.id} product={p} />)}</div>;
+}
+```
+
+### Data Flow
+
+```
+Route loader
+  |-- fetchPageFromLoader(args, { pageId })     -> page promise
+  +-- collectComponentDataPromises(args, page)  -> componentData map
+        |
+  For each component with a loader:
+    component.loader({ componentData, context }) -> data promise
+        |
+  <Region> renders components with resolved data
+```
+
+## Adding a New Page Designer Component
+
+1. Create the React component with decorator metadata class
+2. Implement the component's render function
+3. (Optional) Export `loader` and `fallback` if server data is needed
+4. Rebuild to regenerate static registry
+5. Generate metadata JSON via MCP tool (`storefront_next_generate_page_designer_metadata`)
+6. Deploy cartridge via MCP tool (`cartridge_deploy`)

package/content/guidance/storefront-next/sfnext-page-designer/references/DECORATOR-PATTERNS.md

@@ -0,0 +1,180 @@
+# Decorator Patterns Reference
+
+## @Component Decorator
+
+Marks a class as a Page Designer component:
+
+```typescript
+@Component('typeId', {
+    name: 'Display Name',
+    description: 'Component description for merchants'
+})
+class MyComponentMeta {
+    // attribute definitions...
+}
+```
+
+- `typeId` — Unique identifier (lowercase, hyphens); used in registry and Business Manager
+- `name` — Display name in Page Designer sidebar
+- `description` — Merchant-facing description
+
+## @AttributeDefinition Decorator
+
+Defines a merchant-editable attribute:
+
+```typescript
+@AttributeDefinition()              // Default: string type
+headline: string;
+
+@AttributeDefinition({ type: 'image' })
+heroImage: string;
+
+@AttributeDefinition({ type: 'url' })
+ctaLink: string;
+
+@AttributeDefinition({ type: 'boolean' })
+showBadge: boolean;
+
+@AttributeDefinition({ type: 'enum', values: ['left', 'center', 'right'] })
+alignment: string;
+
+@AttributeDefinition({ type: 'product' })
+featuredProduct: string;
+
+@AttributeDefinition({ type: 'category' })
+category: string;
+
+@AttributeDefinition({ type: 'markup' })
+richText: string;
+
+@AttributeDefinition({ type: 'integer' })
+maxItems: number;
+```
+
+### Attribute Types
+
+| Type | Input in Business Manager | Returns |
+|------|--------------------------|---------|
+| `string` | Text input | String |
+| `text` | Multi-line text | String |
+| `markup` | Rich text editor | Markup string |
+| `boolean` | Checkbox | Boolean |
+| `integer` | Number input | Integer |
+| `enum` | Dropdown select | String |
+| `image` | Image picker | Image URL |
+| `file` | File picker | File URL |
+| `url` | URL input | URL string |
+| `category` | Category selector | Category ID |
+| `product` | Product selector | Product ID |
+
+### Type Inference by MCP Tool
+
+The `storefront_next_page_designer_decorator` MCP tool infers types from prop names:
+
+| Prop Name Pattern | Inferred Type |
+|------------------|---------------|
+| `*Url`, `*Link`, `*Href` | `url` |
+| `*Image`, `*Img`, `*Src` | `image` |
+| `is*`, `show*`, `has*`, `enable*` | `boolean` |
+| `*Count`, `*Num`, `max*`, `min*` | `integer` |
+| Other | `string` |
+
+## @RegionDefinition Decorator
+
+Defines nested regions within a component (e.g., a grid with slots):
+
+```typescript
+@Component('content-grid', { name: 'Content Grid', description: '2-column grid' })
+@RegionDefinition([
+    {
+        id: 'left',
+        name: 'Left Column',
+        description: 'Left content area',
+        maxComponents: 3,
+    },
+    {
+        id: 'right',
+        name: 'Right Column',
+        description: 'Right content area',
+        maxComponents: 3,
+    },
+])
+class ContentGridMeta {
+    @AttributeDefinition({ type: 'boolean' })
+    equalWidth: boolean;
+}
+```
+
+## @PageType Decorator
+
+Used on route modules to define page types in Business Manager:
+
+```typescript
+@PageType({
+    name: 'Home Page',
+    description: 'Main landing page',
+    supportedAspectTypes: ['default']
+})
+@RegionDefinition([
+    { id: 'hero', name: 'Hero Section', maxComponents: 1 },
+    { id: 'content', name: 'Main Content' },
+])
+```
+
+## Complete Component Example
+
+```typescript
+import { Component, AttributeDefinition, RegionDefinition } from '@salesforce/storefront-next-runtime/design';
+
+@Component('promo-banner', {
+    name: 'Promotional Banner',
+    description: 'Banner with background image, text overlay, and CTA'
+})
+class PromoBannerMeta {
+    @AttributeDefinition({ type: 'image' })
+    backgroundImage: string;
+
+    @AttributeDefinition()
+    headline: string;
+
+    @AttributeDefinition({ type: 'text' })
+    subheadline: string;
+
+    @AttributeDefinition({ type: 'url' })
+    ctaUrl: string;
+
+    @AttributeDefinition()
+    ctaLabel: string;
+
+    @AttributeDefinition({ type: 'enum', values: ['light', 'dark'] })
+    theme: string;
+
+    @AttributeDefinition({ type: 'boolean' })
+    fullWidth: boolean;
+}
+
+export default function PromoBanner({
+    backgroundImage,
+    headline,
+    subheadline,
+    ctaUrl,
+    ctaLabel,
+    theme = 'light',
+    fullWidth,
+}: PromoBannerProps) {
+    return (
+        <div className={cn(
+            'relative overflow-hidden',
+            fullWidth ? 'w-full' : 'max-w-7xl mx-auto',
+            theme === 'dark' ? 'text-white' : 'text-gray-900'
+        )}>
+            <DynamicImage src={backgroundImage} alt="" className="absolute inset-0" />
+            <div className="relative z-10 p-8">
+                <h2 className="text-3xl font-bold">{headline}</h2>
+                {subheadline && <p className="mt-2">{subheadline}</p>}
+                {ctaUrl && <a href={ctaUrl} className="mt-4 inline-block">{ctaLabel}</a>}
+            </div>
+        </div>
+    );
+}
+```