@salesforce/retail-react-app 7.0.0 → 7.1.0-nightly-20250724080225
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.cursor/rules/accessibility-rule.mdc +8 -0
- package/.cursor/rules/component-generation-requirements.mdc +29 -0
- package/.cursor/rules/cursor-accessibility-mdc/accessibility-button-name.mdc +26 -0
- package/.cursor/rules/cursor-accessibility-mdc/accessibility-heading-order.mdc +26 -0
- package/.cursor/rules/cursor-accessibility-mdc/accessibility-image-alt.mdc +24 -0
- package/.cursor/rules/cursor-accessibility-mdc/accessibility-input-label.mdc +27 -0
- package/.cursor/rules/cursor-accessibility-mdc/accessibility-link-name.mdc +26 -0
- package/.cursor/rules/cursor-rule.mdc +66 -0
- package/.cursor/rules/development-guidelines.mdc +103 -0
- package/.cursor/rules/page-creation.mdc +16 -0
- package/CHANGELOG.md +5 -0
- package/package.json +6 -6
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Check and verify accessibility on local project
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
To check accessibility of a project, use the accessibility rules defined in ./cursor-accessibility-mdc/ directory.
|
|
7
|
+
Run an automated scan for the entire codebase within the project and check for any violations.
|
|
8
|
+
Show the scanned results in summary and detailed violations if any.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: USE when creating new components
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
# Component Generation Requirements
|
|
7
|
+
|
|
8
|
+
## Process
|
|
9
|
+
1. **Preferred**
|
|
10
|
+
- Ask user to provide the component name, purpose and requirements.
|
|
11
|
+
- Determine the appropriate component type (presentational, container, form, etc.).
|
|
12
|
+
- Collected component information must be displayed and asked for confirmation.
|
|
13
|
+
2. **Default to Simple** - Start with minimal implementation
|
|
14
|
+
3. DO NOT add extra features unless asked
|
|
15
|
+
|
|
16
|
+
## General Rules
|
|
17
|
+
Create components at the components directory: `**/components/[component-name]/index.jsx`
|
|
18
|
+
|
|
19
|
+
## Guidelines
|
|
20
|
+
**IMPORTANT**
|
|
21
|
+
- Use functional components with hooks
|
|
22
|
+
- Use PascalCase for component names
|
|
23
|
+
- Use kebab-case for directories
|
|
24
|
+
- Start simple, expand only if requested
|
|
25
|
+
- One main purpose per component
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: When accessibility is checked. Check if Buttons must have a discernible name using text or aria attributes
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Rule: accessibility-button-name
|
|
8
|
+
|
|
9
|
+
Buttons must have a discernible name using text or aria attributes
|
|
10
|
+
|
|
11
|
+
## 🔍 Pattern
|
|
12
|
+
|
|
13
|
+
```regex
|
|
14
|
+
<button(?![^>]*\b(aria-label|aria-labelledby|title|name)=)
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## 📍 Examples
|
|
18
|
+
|
|
19
|
+
```tsx
|
|
20
|
+
// ❌ Bad
|
|
21
|
+
<button></button>
|
|
22
|
+
// ✅ Good
|
|
23
|
+
<button>Submit</button>
|
|
24
|
+
// ✅ Good
|
|
25
|
+
<button aria-label="Close dialog"><XIcon /></button>
|
|
26
|
+
```
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: When accessibility is checked. Check if heading levels should increase sequentially for semantic structure
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Rule: accessibility-heading-order
|
|
8
|
+
|
|
9
|
+
Heading levels should increase sequentially for semantic structure
|
|
10
|
+
|
|
11
|
+
## 🔍 Pattern
|
|
12
|
+
|
|
13
|
+
```regex
|
|
14
|
+
<h([3-6])>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## 📍 Examples
|
|
18
|
+
|
|
19
|
+
```tsx
|
|
20
|
+
// ❌ Bad
|
|
21
|
+
<h1>Main Title</h1>
|
|
22
|
+
<h4>Subsection</h4>
|
|
23
|
+
// ✅ Good
|
|
24
|
+
<h1>Main Title</h1>
|
|
25
|
+
<h2>Subsection</h2>
|
|
26
|
+
```
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: When accessibility is checked. Ensure all <img> tags include descriptive alt attributes
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Rule: accessibility-image-alt
|
|
8
|
+
|
|
9
|
+
Ensure all <img> tags include descriptive alt attributes
|
|
10
|
+
|
|
11
|
+
## 🔍 Pattern
|
|
12
|
+
|
|
13
|
+
```regex
|
|
14
|
+
<img(?![^>]*\balt=)
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## 📍 Examples
|
|
18
|
+
|
|
19
|
+
```tsx
|
|
20
|
+
// ❌ Bad
|
|
21
|
+
<img src="photo.jpg" />
|
|
22
|
+
// ✅ Good
|
|
23
|
+
<img src="photo.jpg" alt="Company logo" />
|
|
24
|
+
```
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: When accessibility is checked. Check if Input fields must have a label or aria-label for screen readers
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Rule: accessibility-input-label
|
|
8
|
+
|
|
9
|
+
Input fields must have a label or aria-label for screen readers
|
|
10
|
+
|
|
11
|
+
## 🔍 Pattern
|
|
12
|
+
|
|
13
|
+
```regex
|
|
14
|
+
<input(?![^>]*(aria-label|aria-labelledby|id=))
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## 📍 Examples
|
|
18
|
+
|
|
19
|
+
```tsx
|
|
20
|
+
// ❌ Bad
|
|
21
|
+
<input type="text" />
|
|
22
|
+
// ✅ Good
|
|
23
|
+
<input aria-label="Search" />
|
|
24
|
+
// ✅ Good with label
|
|
25
|
+
<label htmlFor="email">Email</label>
|
|
26
|
+
<input id="email" type="text" />
|
|
27
|
+
```
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: When accessibility is checked. Check if Anchor tags must have accessible names
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Rule: accessibility-link-name
|
|
8
|
+
|
|
9
|
+
Anchor tags must have accessible names
|
|
10
|
+
|
|
11
|
+
## 🔍 Pattern
|
|
12
|
+
|
|
13
|
+
```regex
|
|
14
|
+
<a(?![^>]*\b(aria-label|aria-labelledby|title)=)(?![^>]*>\s*\w+\s*</a>)
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## 📍 Examples
|
|
18
|
+
|
|
19
|
+
```tsx
|
|
20
|
+
// ❌ Bad
|
|
21
|
+
<a href="/profile"></a>
|
|
22
|
+
// ✅ Good
|
|
23
|
+
<a href="/profile">Your Profile</a>
|
|
24
|
+
// ✅ Good
|
|
25
|
+
<a href="/profile" aria-label="Profile page"><UserIcon /></a>
|
|
26
|
+
```
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: How to add or edit Cursor rules in our project
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
# Cursor Rules Location
|
|
7
|
+
|
|
8
|
+
How to add new cursor rules to the project
|
|
9
|
+
|
|
10
|
+
1. Always place rule files in PROJECT_ROOT/.cursor/rules/:
|
|
11
|
+
```
|
|
12
|
+
.cursor/rules/
|
|
13
|
+
├── your-rule-name.mdc
|
|
14
|
+
├── another-rule.mdc
|
|
15
|
+
└── ...
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
2. Follow the naming convention:
|
|
19
|
+
- Use kebab-case for filenames
|
|
20
|
+
- Always use .mdc extension
|
|
21
|
+
- Make names descriptive of the rule's purpose
|
|
22
|
+
|
|
23
|
+
3. Directory structure:
|
|
24
|
+
```
|
|
25
|
+
PROJECT_ROOT/
|
|
26
|
+
├── .cursor/
|
|
27
|
+
│ └── rules/
|
|
28
|
+
│ ├── your-rule-name.mdc
|
|
29
|
+
│ └── ...
|
|
30
|
+
└── ...
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
4. Never place rule files:
|
|
34
|
+
- In the project root
|
|
35
|
+
- In subdirectories outside .cursor/rules
|
|
36
|
+
- In any other location
|
|
37
|
+
|
|
38
|
+
5. Cursor rules have the following structure:
|
|
39
|
+
|
|
40
|
+
````
|
|
41
|
+
---
|
|
42
|
+
description: Short description of the rule's purpose
|
|
43
|
+
globs: optional/path/pattern/**/*
|
|
44
|
+
alwaysApply: false
|
|
45
|
+
---
|
|
46
|
+
# Rule Title
|
|
47
|
+
|
|
48
|
+
Main content explaining the rule with markdown formatting.
|
|
49
|
+
|
|
50
|
+
1. Step-by-step instructions
|
|
51
|
+
2. Code examples
|
|
52
|
+
3. Guidelines
|
|
53
|
+
|
|
54
|
+
Example:
|
|
55
|
+
```typescript
|
|
56
|
+
// Good example
|
|
57
|
+
function goodExample() {
|
|
58
|
+
// Implementation following guidelines
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// Bad example
|
|
62
|
+
function badExample() {
|
|
63
|
+
// Implementation not following guidelines
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
````
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Salesforce Commerce Composable Storefront Development Guidelines
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Salesforce Commerce Composable Storefront Development Guidelines
|
|
8
|
+
|
|
9
|
+
## Overview
|
|
10
|
+
This document offers guidelines in the development of Salesforce Commerce Composable Storefront applications using PWA Kit. The AI should possess a comprehensive understanding of the PWA Kit architecture, sample Retail React App, Chakra UI, and standard React application practices.
|
|
11
|
+
|
|
12
|
+
## Core Principles
|
|
13
|
+
|
|
14
|
+
### Project Understanding
|
|
15
|
+
- Thoroughly analyze requests and the existing project for successful implementation.
|
|
16
|
+
- Promptly clarify ambiguous requirements.
|
|
17
|
+
|
|
18
|
+
### Development Workflow
|
|
19
|
+
- **Analyze Requirements** - Clearly define the objectives and functionalities required.
|
|
20
|
+
- **Review Existing Code** - Examine the current codebase to identify similar solutions and potentially reusable components.
|
|
21
|
+
- **Understand Existing Hooks and Utilities** - Familiarize with hooks and utility functions available within the project, including those from commerce-sdk-react and template-retail-react-app modules.
|
|
22
|
+
- **Plan Implementation** - Design component structure before coding.
|
|
23
|
+
- **Implement Incrementally** - Develop and test the service in small, manageable steps.
|
|
24
|
+
- **Test Thoroughly** - Ensure comprehensive testing, including the use of Jest.
|
|
25
|
+
|
|
26
|
+
## Technical Stack
|
|
27
|
+
|
|
28
|
+
### Core Technologies
|
|
29
|
+
- **React** - UI components and SPA architecture
|
|
30
|
+
- **Express** - Server-side rendering and backend
|
|
31
|
+
- **@salesforce/commerce-sdk-react** - Commerce Cloud API integration (hooks)
|
|
32
|
+
- **PWA Kit** - SSR, routing, config, Salesforce integration
|
|
33
|
+
- **Chakra UI V2** - UI components and theming
|
|
34
|
+
- **Emotion** - CSS-in-JS styling
|
|
35
|
+
- **React Router** - Routing
|
|
36
|
+
- **React Intl** - Localization
|
|
37
|
+
- **React Query** - Data fetching/caching
|
|
38
|
+
- **Webpack** - Bundling
|
|
39
|
+
- **React Testing Library, Jest** - Testing libraries
|
|
40
|
+
- **react-helmet, framer-motion, etc.** - Utilities, animation, head management
|
|
41
|
+
- **ESLint/Prettier** - Code formatting and linting
|
|
42
|
+
|
|
43
|
+
## PWK Kit Architecture
|
|
44
|
+
|
|
45
|
+
### Configuration Files
|
|
46
|
+
- PWA Kit apps are customized using configuration files for API access, URL formatting, and server-side rendering.
|
|
47
|
+
- These files support JavaScript, YAML, and JSON formats, with default.js being the standard.
|
|
48
|
+
- Configuration values are serialized for isomorphic rendering, so secrets must not be included.
|
|
49
|
+
- Environment-specific configuration files can replace or complement default.js.
|
|
50
|
+
- File precedence is .js > .yml > .yaml > .json if base names are the same.
|
|
51
|
+
|
|
52
|
+
### Proxy Requests
|
|
53
|
+
- Managed Runtime's proxy feature routes API requests through the storefront domain to avoid CORS issues and improve performance.
|
|
54
|
+
- Local proxy configurations are set in config/default.js, while Managed Runtime deployments use Runtime Admin or the Managed Runtime API.
|
|
55
|
+
- Requests use the /mobify/proxy/<PROXY_PATH> pattern.
|
|
56
|
+
- Proxied requests and responses are modified for transparent operation.
|
|
57
|
+
- Proxied requests are uncached by default but can be cached using a caching path prefix.
|
|
58
|
+
|
|
59
|
+
### Rendering
|
|
60
|
+
- PWA Kit uses server-side rendering (SSR) for fast initial page loads, leveraging CDN caching.
|
|
61
|
+
- After the first load, client-side rendering (CSR) takes over for fluid user interactions.
|
|
62
|
+
- Application code must be isomorphic, functioning in both server and client environments, often with conditional logic.
|
|
63
|
+
- Props from API requests are serialized into the page source during SSR for client-side hydration.
|
|
64
|
+
- A correlation ID is provided on each page for tracking requests across PWA Kit and other systems.
|
|
65
|
+
|
|
66
|
+
### Routing
|
|
67
|
+
- PWA Kit uses Express.js and React Router for handling requests and rendering components.
|
|
68
|
+
- Routes are defined in app/routes.jsx as an array of objects with 'path' and 'component' properties.
|
|
69
|
+
- You can use both withReactQuery and withLegacyGetProps at the same time.
|
|
70
|
+
- getProps and shouldGetProps were removed from the default template of pages of the Retail React App, but aren't deprecated. Long-term support for these methods remains.
|
|
71
|
+
|
|
72
|
+
### PWA Kit Special Components
|
|
73
|
+
- Customize your storefront by overriding default special components that start with an underscore (_), such as app/components/_app-config/index.jsx.
|
|
74
|
+
- app/components/_app-config: The top-level component for app-wide configurations like theme providers and state management.
|
|
75
|
+
- app/components/_app: The child of _app-config. Use it for layout and UI that persist throughout your React app, such as the header, footer, and sidebar.
|
|
76
|
+
- app/components/_error: Renders when a page or its data isn't found, or when an error occurs, returning a 404 status.
|
|
77
|
+
|
|
78
|
+
### State Management
|
|
79
|
+
- PWA Kit applications support various state management approaches, including simple prop-passing or React's Context API.
|
|
80
|
+
- The React Context API can be used with useReducer and useContext for shared global state.
|
|
81
|
+
- The AppConfig special component is the primary place to initialize a state management system.
|
|
82
|
+
- When integrating libraries like Redux, AppConfig methods such as restore, freeze, extraGetPropsArgs, and render are utilized.
|
|
83
|
+
|
|
84
|
+
### PWA Kit Extensibility
|
|
85
|
+
- In PWA Kit v3, you can extend a base template (@salesforce/retail-react-app) by replacing specific files using a local "overrides directory."
|
|
86
|
+
- Extensibility is configured in package.json with the base template (ccExtensibility.extends) and your overrides directory (ccExtensibility.overridesDir).
|
|
87
|
+
- To override a file, recreate its exact path and filename in your overrides directory.
|
|
88
|
+
|
|
89
|
+
### PWA Kit Storefront Development
|
|
90
|
+
- Start development with Retail React App sample codebase and tooling.
|
|
91
|
+
- Use included npm scripts for automating development tasks like build, test, and lint.
|
|
92
|
+
- Access Shopper data through the commerce-sdk-react hooks to fetch, cache, and mutate utilizing Salesforce Commerce API (SLAS) and OCAPI.
|
|
93
|
+
- Use Chakra UI and existing components when available.
|
|
94
|
+
- Create simple, functional, modular, reusable components.
|
|
95
|
+
- Use the React Helmet library to modify the HTML tags in Document, such as <head>.
|
|
96
|
+
- Use kebab-case for file names. Only start with an underscore (_) if they are special components.
|
|
97
|
+
- Use React Hooks (e.g., useState, useEffect, useContext, useMemo, useCallback) for state management and side effects.
|
|
98
|
+
|
|
99
|
+
## Quality Standards
|
|
100
|
+
- Maintain consistent code formatting using project standards.
|
|
101
|
+
- Write comprehensive test coverage.
|
|
102
|
+
- Ensure components are accessible and mobile-friendly.
|
|
103
|
+
- Follow security best practices for all code.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Page Creation Rule - automatically apply when user asks to create new page, add page, make page, build page, generate page
|
|
3
|
+
globs:
|
|
4
|
+
alwaysApply: false
|
|
5
|
+
---
|
|
6
|
+
USE WHEN create a new page, add a new page, make a new page, build a new page, generate a new page, create page, add page, make page, build page, generate page
|
|
7
|
+
|
|
8
|
+
**Mandatory**
|
|
9
|
+
- DO ask user to clarify page name and page route before proceed
|
|
10
|
+
- ONLY Create a bare minimum page component
|
|
11
|
+
- Do NOT include other project components or hooks unless specifically requested
|
|
12
|
+
- Do NOT add extra styling, layout, or features unless explicitly asked
|
|
13
|
+
|
|
14
|
+
## Implementation Steps
|
|
15
|
+
1. Create simple component in `app/pages/[page-name]/index.jsx`
|
|
16
|
+
2. Add route to `app/routes.jsx`
|
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,6 @@
|
|
|
1
|
+
## v7.1.0-dev (July 22, 2025)
|
|
2
|
+
|
|
3
|
+
|
|
1
4
|
## v7.0.0 (July 22, 2025)
|
|
2
5
|
|
|
3
6
|
- Improved the layout of product tiles in product scroll and product list [#2446](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2446)
|
|
@@ -20,6 +23,8 @@
|
|
|
20
23
|
- Fix passwordless race conditions in form submission [#2758](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2758)
|
|
21
24
|
- Use `<picture>` element for responsive images [#2724](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2724)
|
|
22
25
|
- Add Data Cloud partyIdentification events and improve error handling [#2811](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2811)
|
|
26
|
+
- Introduce the cursor rules to assist project developers [#2820](https://github.com/SalesforceCommerceCloud/pwa-kit/pull/2820)
|
|
27
|
+
|
|
23
28
|
|
|
24
29
|
## v6.1.0 (May 22, 2025)
|
|
25
30
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@salesforce/retail-react-app",
|
|
3
|
-
"version": "7.
|
|
3
|
+
"version": "7.1.0-nightly-20250724080225",
|
|
4
4
|
"license": "See license in LICENSE",
|
|
5
5
|
"author": "cc-pwa-kit@salesforce.com",
|
|
6
6
|
"ccExtensibility": {
|
|
@@ -46,10 +46,10 @@
|
|
|
46
46
|
"@loadable/component": "^5.15.3",
|
|
47
47
|
"@peculiar/webcrypto": "^1.4.2",
|
|
48
48
|
"@salesforce/cc-datacloud-typescript": "1.1.2",
|
|
49
|
-
"@salesforce/commerce-sdk-react": "3.
|
|
50
|
-
"@salesforce/pwa-kit-dev": "3.
|
|
51
|
-
"@salesforce/pwa-kit-react-sdk": "3.
|
|
52
|
-
"@salesforce/pwa-kit-runtime": "3.
|
|
49
|
+
"@salesforce/commerce-sdk-react": "3.5.0-nightly-20250724080225",
|
|
50
|
+
"@salesforce/pwa-kit-dev": "3.12.0-nightly-20250724080225",
|
|
51
|
+
"@salesforce/pwa-kit-react-sdk": "3.12.0-nightly-20250724080225",
|
|
52
|
+
"@salesforce/pwa-kit-runtime": "3.12.0-nightly-20250724080225",
|
|
53
53
|
"@tanstack/react-query": "^4.28.0",
|
|
54
54
|
"@tanstack/react-query-devtools": "^4.29.1",
|
|
55
55
|
"@testing-library/dom": "^9.0.1",
|
|
@@ -107,5 +107,5 @@
|
|
|
107
107
|
"maxSize": "328 kB"
|
|
108
108
|
}
|
|
109
109
|
],
|
|
110
|
-
"gitHead": "
|
|
110
|
+
"gitHead": "5ee8b1378edaa5edcdfa185a94590d2a1c0f7264"
|
|
111
111
|
}
|