@salesforce/b2c-dx-mcp 2.0.0 → 2.1.0

package/content/sfnext/quick-reference.md

@@ -1,226 +0,0 @@
-# Storefront Next - Development Guidelines (Quick Reference)
-
-⚠️ **READ THESE CRITICAL RULES BEFORE WRITING ANY CODE** ⚠️
-
-## 🏗️ Architecture Overview
-
-**Server-rendered SPA** built on React Server Components:
-- **React Router 7** in framework mode
-- **Managed Runtime (MRT)** as data orchestration layer
-- **All SCAPI requests execute on MRT server** (both SSR and client-side navigation)
-
-**Key Point**: Client-side routing does NOT mean client-side data fetching. Loaders always run on the server.
-
----
-
-## 🚨 Non-Negotiable Rules
-
-### 1. Server-Only Data Loading
-
-✅ **REQUIRED**: Use server `loader` for all SCAPI data fetching
-
-```typescript
-export function loader({ context }: LoaderFunctionArgs): PageData {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),  // Promise - streams
-        reviews: clients.shopperProducts.getReviews({...}),  // Promise - streams
-    };
-}
-```
-
-**Why?** Keeps SCAPI requests on MRT server for security, performance, and bundle size.
-
-### 2. Synchronous Loaders (Not Async)
-
-✅ **CRITICAL**: Loaders must be **synchronous functions that return promises**, NOT async functions.
-
-```typescript
-// ✅ CORRECT - Enables streaming
-export function loader({ context }: LoaderFunctionArgs): PageData {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),  // Promise - streams
-    };
-}
-
-// ❌ AVOID - Blocks page transitions
-export async function loader({ context }: LoaderFunctionArgs) {
-    const product = await clients.shopperProducts.getProduct({...}); // Blocks!
-    return { product };
-}
-```
-
-**Why?** Async loaders block page transitions. Synchronous loaders enable progressive streaming.
-
-### 3. TypeScript-Only
-
-✅ **REQUIRED**: Use `.ts` and `.tsx` file extensions  
-❌ **BLOCKED**: `.js`, `.jsx`, `.mjs`, `.cjs` files are forbidden by ESLint
-
-### 4. Use createPage() HOC
-
-✅ **RECOMMENDED**: Use `createPage()` for standardized page patterns
-
-```typescript
-import { createPage } from '@/components/create-page';
-
-const ProductPage = createPage({
-    component: ProductView,
-    fallback: <ProductSkeleton />
-});
-
-export default ProductPage;
-```
-
-### 5. Tailwind CSS 4 Only
-
-✅ **REQUIRED**: Use Tailwind utility classes only  
-❌ **BLOCKED**: No inline styles (`style={{...}}`), no CSS modules, no separate CSS files
-
-```typescript
-// ✅ CORRECT - Tailwind utilities
-<div className="rounded-lg border border-border bg-card p-4">
-    <h2 className="text-lg font-semibold text-card-foreground">
-        {product.name}
-    </h2>
-</div>
-
-// ❌ AVOID - Inline styles
-<div style={{ padding: '1rem' }}>
-
-// ❌ AVOID - CSS modules
-import styles from './product-card.module.css';
-```
-
-**Why?** Consistent styling approach, better performance, automatic dark mode support via theme variables.
-
----
-
-## 📋 Quick Patterns
-
-### Data Fetching
-
-```typescript
-import { createApiClients } from '@/lib/api-clients';
-
-export function loader({ context }: LoaderFunctionArgs): PageData {
-    const clients = createApiClients(context);
-    return {
-        product: clients.shopperProducts.getProduct({...}),
-        reviews: clients.shopperProducts.getReviews({...}),
-    };
-}
-```
-
-**See `data-fetching` section for:** loaders, actions, useScapiFetcher, parallel requests, data flow
-
-### Authentication
-
-```typescript
-import { getAuth } from '@/middlewares/auth.server';
-
-export function loader({ context }: LoaderFunctionArgs) {
-    const auth = getAuth(context);
-    return { 
-        isGuest: auth.userType === 'guest',
-        customerId: auth.customer_id 
-    };
-}
-```
-
-**See `auth` section for:** cookie architecture, client usage, token management
-
-### Configuration
-
-```typescript
-// Components
-import { useConfig } from '@/config';
-const config = useConfig();
-
-// Loaders/Actions
-import { getConfig } from '@/config';
-const config = getConfig(context);
-```
-
-**See `config` section for:** adding config, environment variables, security
-
-### Internationalization
-
-```typescript
-// Components
-import { useTranslation } from 'react-i18next';
-const { t } = useTranslation('product');
-
-// Loaders/Actions
-import { getTranslation } from '@/lib/i18next';
-const { t } = getTranslation(context);
-```
-
-**See `i18n` section for:** validation schemas (factory pattern), language switching, extensions
-
-### Components
-
-```typescript
-// Suspense boundaries
-import { Suspense } from 'react';
-import { Await } from 'react-router';
-
-<Suspense fallback={<ProductSkeleton />}>
-    <Await resolve={product}>
-        {(data) => <ProductHeader product={data} />}
-    </Await>
-</Suspense>
-```
-
-**See `components` section for:** createPage HOC, file organization, best practices
-
-### Styling
-
-```typescript
-// Tailwind utility classes
-<div className="bg-background text-foreground border-border">
-    <button className="bg-primary text-primary-foreground rounded-md px-4 py-2">
-        Click me
-    </button>
-</div>
-
-// shadcn/ui: Add via npx shadcn@latest add <component-name>
-import { Button } from '@/components/ui/button';
-import { Card } from '@/components/ui/card';
-```
-
-**See `styling` section for:** Tailwind CSS 4 rules, Shadcn/ui components, dark mode, responsive design
-
----
-
-## 🔍 Get Detailed Guidelines
-
-Use the `sfnext_get_guidelines` MCP tool with specific sections:
-
-```json
-{
-  "sections": ["data-fetching", "components", "testing"]
-}
-```
-
-**Available sections:**
-- `data-fetching` - Loaders, actions, useScapiFetcher, data flow
-- `components` - createPage HOC, Suspense, file organization
-- `styling` - Tailwind CSS 4, Shadcn/ui, styling guidelines
-- `testing` - Vitest, Storybook, coverage requirements
-- `auth` - Authentication and session management
-- `config` - Configuration system
-- `i18n` - Internationalization patterns
-- `state-management` - Client-side state with Zustand
-- `page-designer` - Page Designer integration
-- `performance` - Optimization techniques
-- `extensions` - Extension development
-- `pitfalls` - Common mistakes to avoid
-
----
-
-**When in doubt:**
-1. Check existing code for similar examples
-2. Use the MCP tool to get detailed section guidance
-3. Follow architectural principles: server-only, streaming, TypeScript

package/content/sfnext/state-management.md

@@ -1,75 +0,0 @@
-# Client-Side State Management
-
-## Zustand Store Pattern
-
-Storefront Next uses Zustand for client-side state (basket, wishlist):
-
-```typescript
-// src/middlewares/basket.client.ts
-import {create} from 'zustand';
-
-interface BasketStore {
-  basket: Basket | null;
-  setBasket: (basket: Basket | null) => void;
-  clearBasket: () => void;
-}
-
-export const useBasketStore = create<BasketStore>((set) => ({
-  basket: null,
-  setBasket: (basket) => set({basket}),
-  clearBasket: () => set({basket: null}),
-}));
-```
-
-## Context Integration
-
-Access Zustand state via context helpers:
-
-```typescript
-import { getBasket, updateBasket } from '@/middlewares/basket.client';
-
-// In clientLoader
-export const clientLoader: ClientLoaderFunction = ({ context }) => {
-    const basket = getBasket(context);
-    return { basket, itemCount: basket?.productItems?.length ?? 0 };
-};
-
-// In components
-function CartIcon() {
-    const basket = getBasket(context);
-    return <Badge count={basket?.productItems?.length ?? 0} />;
-}
-```
-
-## Update Pattern
-
-After mutations, update the store:
-
-```typescript
-export async function clientAction({request, context}: ActionFunctionArgs) {
-  const formData = await request.formData();
-  const productId = formData.get('productId') as string;
-
-  const basket = getBasket(context);
-  const clients = createApiClients(context);
-
-  const {data: updatedBasket} = await clients.shopperBasketsV2.addItemToBasket({
-    params: {path: {basketId: basket.basketId}},
-    body: [{productId, quantity: 1}],
-  });
-
-  // Update Zustand store
-  updateBasket(context, updatedBasket);
-
-  return Response.json({success: true, basket: updatedBasket});
-}
-```
-
-## Best Practices
-
-1. **Use for ephemeral client state**: Shopping cart, UI state, temporary selections
-2. **Don't duplicate server state**: Prefer React Router loaders for server data
-3. **Keep stores focused**: Separate stores for basket, wishlist, etc.
-4. **Sync with server**: Update store after successful mutations
-
-For full documentation on client-side state management patterns, see the Zustand documentation and React Router state management patterns.

package/content/sfnext/styling.md

@@ -1,51 +0,0 @@
-# Styling Guidelines
-
-## Rules
-
-- ✅ **Use Tailwind utility classes** in component JSX
-- ✅ **Use `cn()` utility** for conditional classes (`import { cn } from '@/lib/utils'`)
-- ✅ **Follow mobile-first** responsive patterns (`md:`, `lg:` breakpoints)
-- ❌ **NO inline styles** (`style={{...}}`)
-- ❌ **NO CSS modules** (`.module.css` files)
-- ❌ **NO separate CSS files** for component styles
-- ✅ **Custom CSS** only in `src/app.css` for global styles and theme configuration
-
-## Shadcn/ui Components
-
-**Adding components:**
-
-```bash
-npx shadcn@latest add <component-name>
-```
-
-**Rules:**
-
-- ✅ **DO** customize components by editing files in `src/components/ui/`
-- ❌ **DON'T** create custom components inside `src/components/ui/`
-- ❌ **DON'T** manually copy components (use CLI instead)
-
-## Dark Mode
-
-Dark mode is supported via CSS variables and the `.dark` class. Theme variables automatically adapt:
-
-```typescript
-<div className="bg-background text-foreground border-border">
-    <button className="bg-primary text-primary-foreground">
-        Click me
-    </button>
-</div>
-```
-
-## Responsive Design
-
-Follow mobile-first responsive design:
-
-```typescript
-<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
-    {/* Content */}
-</div>
-```
-
----
-
-**Reference:** See [README-UI-STYLING.md](docs/README-UI-STYLING.md) in your project for complete UI and styling documentation.

package/content/sfnext/testing.md

@@ -1,232 +0,0 @@
-# Testing Strategy
-
-## Unit Tests (Vitest)
-
-This project uses **Vitest** for unit tests, running under Vite with jsdom as the default test environment.
-
-### Test File Organization
-
-Tests live alongside source files with `.test.ts` or `.test.tsx` extension:
-
-```typescript
-// src/components/product-card/product-card.test.tsx
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import { ProductCard } from './product-card';
-import { mockProduct } from '@/test-utils/mocks';
-
-describe('ProductCard', () => {
-    it('renders product name', () => {
-        render(<ProductCard product={mockProduct} />);
-        expect(screen.getByText(mockProduct.productName)).toBeInTheDocument();
-    });
-});
-```
-
-### Test Utilities
-
-Test utilities are available in `src/test-utils/`:
-- `config.ts` - Mock configuration objects and ConfigProvider wrappers
-- `context-provider-utils.ts` - Context provider helpers for testing
-- `context-provider.tsx` - Test context providers
-
-### Running Tests
-
-```bash
-# Run all tests with coverage
-pnpm test
-
-# Open Vitest UI (interactive test runner)
-pnpm test:ui
-
-# Watch mode (re-run on file changes)
-pnpm test:watch
-
-# Generate coverage report
-pnpm test
-# Coverage report outputs to console and coverage/ directory
-```
-
-### Coverage Requirements
-
-Coverage thresholds are enforced in `vitest.thresholds.ts`:
-- Lines: 73%
-- Statements: 73%
-- Functions: 86%
-- Branches: 87%
-
-These thresholds represent minimum values that must not be undershot. They should be raised regularly to reflect current status.
-
-### Testing Libraries
-
-- **@testing-library/react** - React component testing
-- **@testing-library/jest-dom** - Custom Jest DOM matchers
-- **@testing-library/user-event** - User interaction simulation
-- **@vitest/coverage-v8** - Code coverage
-- **@vitest/ui** - Interactive test UI
-
-## Storybook Testing
-
-Every reusable component should have a Storybook story file (`.stories.tsx`).
-
-### Story Structure
-
-```typescript
-// src/components/product-card/product-card.stories.tsx
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { within, expect } from 'storybook/test';
-import { waitForStorybookReady } from '@storybook/test-utils';
-import { ProductCard } from './product-card';
-import { ConfigProvider } from '@/config/context';
-import { mockConfig } from '@/test-utils/config';
-import { mockProduct } from '@/test-utils/mocks';
-
-const meta: Meta<typeof ProductCard> = {
-    title: 'Components/ProductCard',
-    component: ProductCard,
-    tags: ['autodocs', 'interaction'],
-    decorators: [
-        (Story) => (
-            <ConfigProvider config={mockConfig}>
-                <Story />
-            </ConfigProvider>
-        ),
-    ],
-};
-
-export default meta;
-type Story = StoryObj<typeof ProductCard>;
-
-export const Default: Story = {
-    args: {
-        product: mockProduct,
-    },
-    play: async ({ canvasElement }) => {
-        await waitForStorybookReady(canvasElement);
-        const canvas = within(canvasElement);
-        await expect(canvas.getByText(mockProduct.productName)).toBeInTheDocument();
-    },
-};
-```
-
-### Storybook Commands
-
-```bash
-# Development server (port 6006)
-pnpm storybook
-
-# Build static Storybook
-pnpm build-storybook
-
-# Snapshot tests (visual regression)
-pnpm test-storybook:snapshot
-pnpm test-storybook:snapshot:update  # Update snapshots
-
-# Interaction tests (play functions)
-pnpm test-storybook:interaction
-pnpm test-storybook:static:interaction  # Against static build
-
-# Accessibility tests
-pnpm test-storybook:a11y
-pnpm test-storybook:static:a11y  # Against static build
-
-# Generate story tests with coverage
-pnpm generate:story-tests:coverage
-```
-
-### Storybook Features
-
-- **@storybook/addon-docs** - Automatic documentation generation
-- **@storybook/addon-a11y** - Accessibility testing and validation
-- **@storybook/addon-vitest** - Integration with Vitest
-- **@storybook/test-runner** - Automated testing (interaction, a11y)
-- **Viewport Toolbar** - Built-in toolbar for testing different screen sizes
-
-> **Important**: Use Storybook's built-in viewport toolbar instead of creating separate Mobile/Tablet/Desktop stories. Use the viewport selector in the Storybook toolbar to test components at different screen sizes.
-
-### Story Tags
-
-- `autodocs` - Enable automatic documentation
-- `interaction` - Include in interaction test runs
-- `skip-a11y` - Exclude from a11y tests (use sparingly)
-
-## Testing Best Practices
-
-### Component Testing
-
-1. **Colocate tests** - Keep test files next to source files
-2. **Use test utilities** - Leverage `@/test-utils` for mocks and providers
-3. **Mock external dependencies** - Use `vi.mock()` for API clients, context providers, etc.
-4. **Test user interactions** - Use `@testing-library/user-event` for realistic interactions
-5. **Test accessibility** - Use Storybook a11y addon and test-runner
-
-### Storybook Stories
-
-1. **Multiple variants** - Create stories for different states (Default, Loading, Error, etc.)
-2. **Play functions** - Use `play` functions for interaction testing
-3. **Decorators** - Wrap stories with necessary providers (ConfigProvider, etc.)
-4. **Documentation** - Include component descriptions and prop documentation
-5. **Viewport testing** - Use built-in viewport toolbar, not separate stories
-
-### Route Testing
-
-Route tests should mock:
-- Loader functions and their return values
-- Action functions
-- React Router context
-- API clients
-
-Example:
-
-```typescript
-// src/routes/_app.product.$productId.test.tsx
-import { describe, test, expect, vi } from 'vitest';
-import { render } from '@testing-library/react';
-
-vi.mock('@/components/product-view', () => ({
-    default: ({ product }: any) => (
-        <div data-testid="product-view">
-            <div data-testid="product-name">{product?.name}</div>
-        </div>
-    ),
-}));
-
-// Test route component...
-```
-
-## Testing Recommendations
-
-### SEO Crawler Emulation
-
-- Use **Googlebot user agent** in network conditions to emulate SEO crawler behavior
-- This changes React Router's streaming strategy and shows what crawlers see for SSR
-- Helps verify server-side rendering works correctly for search engines
-
-### Coverage Goals
-
-- Maintain coverage above thresholds defined in `vitest.thresholds.ts`
-- Raise thresholds regularly as coverage improves
-- Focus on testing critical paths and user-facing functionality
-
-### Test Organization
-
-```
-src/
-├── components/
-│   ├── product-card/
-│   │   ├── index.tsx              # Component
-│   │   ├── index.test.tsx          # Unit tests
-│   │   └── index.stories.tsx       # Storybook stories
-├── routes/
-│   ├── _app.product.$productId.tsx
-│   └── _app.product.$productId.test.tsx
-└── test-utils/                     # Shared test utilities
-    ├── config.ts
-    └── context-provider-utils.ts
-```
-
-## References
-
-- **README-TESTS.md** - Complete testing documentation
-- **.storybook/README-STORYBOOK.md** - Storybook setup and usage guide
-- **vitest.thresholds.ts** - Coverage threshold definitions

package/dist/tools/storefrontnext/figma/figma-to-component/figma-url-parser.d.ts

@@ -1,24 +0,0 @@
-/**
- * Extracted parameters from a Figma design URL.
- *
- * @property {string} fileKey - Figma file identifier from URL path
- * @property {string} nodeId - Node identifier (colon format for Figma MCP)
- */
-export interface FigmaParams {
-    fileKey: string;
-    nodeId: string;
-}
-/**
- * Parses a Figma URL to extract fileKey and nodeId.
- *
- * Supported URL formats:
- * - https://figma.com/design/:fileKey/:fileName?node-id=1-2
- * - https://www.figma.com/design/:fileKey/:fileName?node-id=1-2
- * - https://figma.com/file/:fileKey/:fileName?node-id=1-2
- *
- * @param figmaUrl - The Figma URL to parse
- * @returns Object with fileKey and nodeId
- * @throws {Error} When URL is not from figma.com, fileKey cannot be extracted, or node-id is missing
- * @throws {TypeError} When URL format is invalid
- */
-export declare function parseFigmaUrl(figmaUrl: string): FigmaParams;

package/dist/tools/storefrontnext/figma/figma-to-component/figma-url-parser.js

@@ -1,53 +0,0 @@
-/*
- * Copyright (c) 2025, Salesforce, Inc.
- * SPDX-License-Identifier: Apache-2
- * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
- */
-/**
- * Parses a Figma URL to extract fileKey and nodeId.
- *
- * Supported URL formats:
- * - https://figma.com/design/:fileKey/:fileName?node-id=1-2
- * - https://www.figma.com/design/:fileKey/:fileName?node-id=1-2
- * - https://figma.com/file/:fileKey/:fileName?node-id=1-2
- *
- * @param figmaUrl - The Figma URL to parse
- * @returns Object with fileKey and nodeId
- * @throws {Error} When URL is not from figma.com, fileKey cannot be extracted, or node-id is missing
- * @throws {TypeError} When URL format is invalid
- */
-export function parseFigmaUrl(figmaUrl) {
-    try {
-        const url = new URL(figmaUrl);
-        // Validate it's a Figma URL
-        if (!url.hostname.includes('figma.com')) {
-            throw new Error('URL must be from figma.com');
-        }
-        // Extract fileKey from pathname
-        // Pattern: /design/:fileKey/:fileName or /file/:fileKey/:fileName
-        const pathMatch = url.pathname.match(/\/(design|file)\/([^/]+)/);
-        if (!pathMatch || !pathMatch[2]) {
-            throw new Error('Could not extract fileKey from URL. Expected format: https://figma.com/design/:fileKey/:fileName');
-        }
-        const fileKey = pathMatch[2];
-        // Extract nodeId from query params
-        // Pattern: ?node-id=1-2 or ?node-id=1:2
-        const nodeIdParam = url.searchParams.get('node-id');
-        if (!nodeIdParam) {
-            throw new Error('Could not extract node-id from URL. Expected query parameter: ?node-id=1-2');
-        }
-        // Convert node-id format from "1-2" to "1:2" (Figma MCP expects colon format)
-        const nodeId = nodeIdParam.replaceAll('-', ':');
-        return {
-            fileKey,
-            nodeId,
-        };
-    }
-    catch (error) {
-        if (error instanceof TypeError) {
-            throw new TypeError(`Invalid URL format: ${figmaUrl}`);
-        }
-        throw error;
-    }
-}
-//# sourceMappingURL=figma-url-parser.js.map