@salesforce/webapp-template-app-react-sample-b2e-experimental 1.61.3 → 1.61.4

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.
Files changed (35) hide show
  1. package/dist/.a4drules/{graphql.md → features/feature-graphql-graphql-data-access-rule.md} +127 -117
  2. package/dist/.a4drules/features/feature-react-agentforce-conversation-client-embedded-agent-rule.md +32 -0
  3. package/dist/.a4drules/features/feature-react-chart-analytics-charts-rule.md +27 -0
  4. package/dist/.a4drules/skills/feature-graphql-graphql-data-access/SKILL.md +155 -0
  5. package/dist/.a4drules/{graphql/tools/knowledge/lds-explore-graphql-schema.md → skills/feature-graphql-graphql-data-access/docs/explore-schema.md} +58 -29
  6. package/dist/.a4drules/{graphql/tools/knowledge/lds-generate-graphql-mutationquery.md → skills/feature-graphql-graphql-data-access/docs/generate-mutation-query.md} +52 -42
  7. package/dist/.a4drules/{graphql/tools/knowledge/lds-generate-graphql-readquery.md → skills/feature-graphql-graphql-data-access/docs/generate-read-query.md} +32 -22
  8. package/dist/.a4drules/{graphql/tools/schemas/shared.graphqls → skills/feature-graphql-graphql-data-access/docs/shared-schema.graphqls} +1 -1
  9. package/dist/.a4drules/skills/feature-micro-frontend-micro-frontend/SKILL.md +137 -0
  10. package/dist/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent/SKILL.md +108 -0
  11. package/dist/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent/docs/embed-examples.md +182 -0
  12. package/dist/.a4drules/skills/feature-react-chart-analytics-charts/SKILL.md +41 -0
  13. package/dist/.a4drules/skills/feature-react-chart-analytics-charts/docs/schema-mapping.md +4 -0
  14. package/dist/.a4drules/webapp-code-quality.md +136 -0
  15. package/dist/.a4drules/{images.md → webapp-images.md} +6 -4
  16. package/dist/.a4drules/webapp-no-node-e.md +3 -2
  17. package/dist/.a4drules/webapp-react.md +149 -0
  18. package/dist/.a4drules/{typescript.md → webapp-typescript.md} +9 -17
  19. package/dist/.a4drules/webapp.md +62 -45
  20. package/dist/CHANGELOG.md +8 -0
  21. package/dist/force-app/main/default/webapplications/appreactsampleb2e/vite.config.ts +2 -2
  22. package/dist/package.json +1 -1
  23. package/package.json +2 -2
  24. package/dist/.a4drules/README.md +0 -35
  25. package/dist/.a4drules/a4d-webapp-generate.md +0 -27
  26. package/dist/.a4drules/build-validation.md +0 -78
  27. package/dist/.a4drules/code-quality.md +0 -136
  28. package/dist/.a4drules/graphql/tools/knowledge/lds-guide-graphql.md +0 -205
  29. package/dist/.a4drules/react.md +0 -388
  30. package/dist/.a4drules/react_image_processing.md +0 -45
  31. package/dist/.a4drules/ui-layout.md +0 -23
  32. package/dist/.a4drules/webapp-nav-and-placeholders.md +0 -33
  33. package/dist/.a4drules/webapp-ui-first.md +0 -32
  34. package/dist/force-app/main/default/webapplications/appreactsampleb2e/build/vite.config.d.ts +0 -2
  35. package/dist/force-app/main/default/webapplications/appreactsampleb2e/build/vite.config.js +0 -93
@@ -1,388 +0,0 @@
1
- # AI Customization Rule: React Web App (SFDX)
2
-
3
- This rule consolidates React web application guidelines, data access rules, security standards, anti-patterns, and project integration requirements for consistent AI-generated code.
4
-
5
- ## Targets (File Pattern Matching)
6
-
7
- Apply these rules to the React web app files under the SFDX package directory:
8
-
9
- - `force-app/main/default/webapplications/*/**/*.js`
10
- - `force-app/main/default/webapplications/*/**/*.jsx`
11
- - `force-app/main/default/webapplications/*/**/*.ts`
12
- - `force-app/main/default/webapplications/*/**/*.tsx`
13
-
14
- ## Rule Objectives
15
-
16
- - Enforce secure, performant, and maintainable patterns for Salesforce data access.
17
- - Standardize UI with shadcn/ui and Tailwind.
18
- - Prevent prohibited patterns that break React or Salesforce constraints.
19
-
20
- ## UI / layout edits (MANDATORY — read before any UI change)
21
-
22
- **When the user asks for UI changes** (new components, pages, navigation, header, footer, sidebar, theme, or “layout”):
23
- **You MUST open and update `src/appLayout.tsx`** (the theme layout) whenever the change affects how the app shell looks or behaves.
24
- Do not only edit pages or components and leave `appLayout.tsx` unchanged.
25
- If in doubt, **edit appLayout.tsx as well**.
26
- The layout file is: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` (or the app’s `appLayout.tsx` used by `routes.tsx`).
27
-
28
- **Navigation menu and placeholder name/design:** In `appLayout.tsx`, always replace the **default navigation menu** (items and labels) with app-specific links and names, and replace the **placeholder app name** (header, nav brand, footer) and **placeholder design** with the actual app name and intentional styling. Do not leave template nav or "React App"–style branding. See **webapp-nav-and-placeholders.md**.
29
-
30
- ## Project & Entry Points
31
-
32
- - React web app root: `force-app/main/default/webapplications/<appName>/`
33
- - Main entry component: `force-app/main/default/webapplications/<appName>/src/App.tsx`
34
- - **Theme/layout shell**: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` — wraps all routed content (navigation, header, sidebar, outlet). Routes use `<AppLayout />` as the layout element; page content renders inside it via `<Outlet />`. When making UI edits that affect global layout, navigation, header, footer, sidebar, or theme, **you must consider and edit appLayout.tsx** in addition to page or component files; do not only edit individual pages and omit the layout.
35
- - Running Development Server (from the web app directory):
36
- - `npm run dev` — starts the Vite dev server
37
- - You can generally assume the dev server is already running and don't need to start it.
38
- - Build (from the web app directory):
39
- - `npm run build` — TypeScript check + Vite build
40
- - Deploy and open in Salesforce are done from the **SFDX project root** (e.g. via Salesforce CLI or the IDE), not via the web app's package.json. Keep the app buildable so deploy workflows continue to work.
41
-
42
- ## Component Library (MANDATORY)
43
-
44
- - Use shadcn/ui for UI components (Buttons, Cards, Inputs, Dialogs, etc.).
45
- - Import patterns:
46
-
47
- ```javascript
48
- import { Button } from '@/components/ui/button';
49
- import { Card, CardHeader, CardContent } from '@/components/ui/card';
50
- import { Input } from '@/components/ui/input';
51
- ```
52
-
53
- ## Styling Standards
54
-
55
- - Use Tailwind CSS utility classes.
56
- - Follow consistent spacing, color, and typography conventions.
57
-
58
- ## React & TypeScript Standards
59
-
60
- - Component Architecture: Prefer functional components with hooks.
61
- - File Naming: Use PascalCase for components (e.g., `Button.tsx`) and camelCase for hooks (e.g., `useAuth.ts`).
62
- - Imports: Use absolute paths (e.g., `@/components/...`) if the `tsconfig.json` or `vite.config.ts` supports it.
63
- - State: Default to `useState` for local state; avoid adding global state libraries unless requested.
64
-
65
- ## Layout and theme (appLayout.tsx) — CRITICAL for UI edits
66
-
67
- - **appLayout.tsx** is the application shell: it wraps every page and typically contains the main navigation (e.g. `NavigationMenu`), header, sidebar, and `<Outlet />` for child routes. It defines the global look and structure of the app.
68
- - **MANDATORY:** When asked to change the UI in ways that affect the **overall layout**, **navigation**, **header**, **footer**, **sidebar**, or **theme** (e.g. add a top bar, change nav items, add a sidebar, apply a theme wrapper), you **MUST** edit `appLayout.tsx` (or the app’s layout file) as part of the same change. Do not only edit individual pages or components and leave the layout unchanged.
69
- - **Before finishing any UI edit:** Ask yourself: “Does this touch layout, nav, header, footer, sidebar, or theme?” If yes, **you must have modified appLayout.tsx** (or the layout file used by routes). If you did not, add that edit before considering the task done.
70
- - If the project uses feature inheritance (e.g. `__inherit__appLayout`), the editable layout may live in the app or feature at `src/appLayout.tsx`; ensure you modify the correct file that is actually used by `routes.tsx`.
71
-
72
- ## Module & Platform Restrictions
73
-
74
- - React apps must NOT import or rely on Salesforce platform modules; do not use:
75
- - `@salesforce/*`
76
- - `lightning/*`
77
- - `@wire` (LWC-only)
78
- - Use standard web APIs and npm packages only.
79
-
80
- ## LWC MCP Server Integration (Data Access Guidance)
81
-
82
- The LWC MCP server (via Agentforce Vibes extension) provides framework-agnostic data access guidance for UI API and GraphQL patterns.
83
-
84
- ### Primary Tool: `orchestrate_lds_data_requirements`
85
-
86
- The `orchestrate_lds_data_requirements` tool analyzes data requirements and routes to appropriate guidance tools (UI API or GraphQL). **Note:** Tool names may change, but the purpose remains orchestrating LDS data requirements.
87
-
88
- **Important for React Applications:** If the MCP tool recommends Apex REST, React applications should ignore this recommendation. Apex REST is not available in React applications. Follow the [Apex REST Strategy](#data-access-priority-order) section above to evaluate whether GraphQL can handle the requirement, or inform the user that the feature is not currently supported in React.
89
-
90
- ### Tool Availability Check (MANDATORY)
91
-
92
- Before implementing data access, **MUST** verify `orchestrate_lds_data_requirements` is available. If unavailable:
93
-
94
- 1. Notify user: "LWC MCP data access tools not enabled. Add 'lwc-experts' to --toolsets in a4d_mcp_settings.json"
95
- 2. Offer to update the file if you have write access
96
- 3. Otherwise, provide manual instructions
97
-
98
- **Configuration:** Add `"lwc-experts"` to `--toolsets` in `a4d_mcp_settings.json` (typically at `{VSCode/Cursor globalStorage}/salesforce.salesforcedx-einstein-gpt/settings/a4d_mcp_settings.json`). Example: `"metadata,lwc-experts"` in the args array.
99
-
100
- ### LWC MCP Server Tool Usage Restrictions (CRITICAL)
101
-
102
- **This rule applies when building React applications. Do NOT create LWC components or use LWC-specific development tools.**
103
-
104
- **Allowed MCP Tools (Data Access Only):**
105
-
106
- - `orchestrate_lds_data_requirements` - Primary tool for data access guidance
107
- - Any data access guidance tools referenced by `orchestrate_lds_data_requirements` (e.g., UI API or GraphQL guidance tools)
108
-
109
- **Note:** If the MCP tool recommends Apex REST guidance tools, React applications should ignore these recommendations as Apex REST is not available in React.
110
-
111
- **Prohibited MCP Tools (LWC Component Development):**
112
-
113
- - `guide_lwc_development` - LWC component development guidance
114
- - `orchestrate_lwc_component_creation` - LWC component creation orchestration
115
- - `create_lwc_component_from_prd` - LWC component creation from PRD
116
- - Any other LWC component creation, development, or framework-specific tools
117
-
118
- **Enforcement:**
119
-
120
- - **NEVER** call LWC component creation or development tools from the LWC MCP server
121
- - **ONLY** use data access related tools that provide framework-agnostic guidance
122
- - If you encounter a request to create LWC components, remind the user that you are building a React app and redirect them to use React patterns instead
123
-
124
- ## Data Access Rules (CRITICAL)
125
-
126
- - MANDATORY: Use the DataSDK (`getDataSDK()` from `@salesforce/sdk-data`) for all API calls from React. The SDK handles authentication and CSRF token management. Do NOT use `axios` or raw `fetch` for Salesforce API calls.
127
-
128
- ### Data Access Workflow (MANDATORY)
129
-
130
- **Before implementing any data access functionality:**
131
-
132
- 1. **Proactively check** for LWC MCP server tool availability (see [LWC MCP Server Integration](#lwc-mcp-server-integration-data-access-guidance) section above)
133
- 2. **Use the LWC MCP server's `orchestrate_lds_data_requirements` tool** to get guidance on the appropriate data access pattern
134
- 3. The MCP tool will analyze your requirements and guide you to the appropriate Salesforce data access pattern (GraphQL or UI API)
135
- 4. **Follow the MCP tool's recommendations** when implementing data access code, prioritizing GraphQL for all operations
136
- 5. **If the tool recommends Apex REST**, ignore this recommendation and follow the [Apex REST Strategy](#data-access-priority-order) to evaluate if GraphQL can handle the requirement
137
-
138
- **Note:** The code examples below serve as reference patterns, but your implementation should be informed by the MCP tool's guidance, which provides the most up-to-date best practices and framework-agnostic patterns.
139
-
140
- ### Data Access Priority Order
141
-
142
- The LWC MCP server's `orchestrate_lds_data_requirements` tool follows this priority order when recommending data access patterns:
143
-
144
- 1. **GraphQL** (queries & mutations) - Preferred for all data operations including reads, writes, complex queries, relationships, and multi-entity operations
145
- 2. **Salesforce UI API** - For standard CRUD operations when GraphQL is not suitable
146
-
147
- **Apex REST Strategy (CRITICAL):**
148
-
149
- - **Apex REST is NOT available in React applications.** If the MCP tool recommends Apex REST, or if you believe Apex is needed:
150
- 1. **Reflect** on why Apex seems necessary
151
- 2. **Evaluate** whether GraphQL queries or mutations can accomplish the task
152
- 3. **If GraphQL cannot handle the requirement**, inform the user that the feature is not currently supported in React applications
153
- 4. **Do NOT** implement Apex REST endpoints or attempt to call them from React
154
-
155
- **Note:** For AI/generative features, see the [Einstein LLM Gateway](#einstein-llm-gateway-aigenerative-features) section below.
156
-
157
- ### Reference Code Examples
158
-
159
- The following code examples serve as reference patterns for React applications. **Always consult the LWC MCP server's `orchestrate_lds_data_requirements` tool first** to ensure you're using the most appropriate pattern and latest best practices for your specific use case.
160
-
161
- GraphQL query example:
162
-
163
- ```typescript
164
- import { getDataSDK, gql } from '@salesforce/sdk-data';
165
-
166
- const GET_ACCOUNT = gql`
167
- query GetAccount($id: ID!) {
168
- uiapi {
169
- query {
170
- Account(where: { Id: { eq: $id } }) {
171
- edges {
172
- node {
173
- Id
174
- Name {
175
- value
176
- }
177
- }
178
- }
179
- }
180
- }
181
- }
182
- }
183
- `;
184
-
185
- const data = await getDataSDK();
186
- const response = await data.graphql?.<GetAccountQuery>(GET_ACCOUNT, { id: '001...' });
187
-
188
- if (response?.errors?.length) {
189
- throw new Error(response.errors.map(e => e.message).join('; '));
190
- }
191
-
192
- const account = response?.data;
193
- ```
194
-
195
- GraphQL mutation example:
196
-
197
- ```typescript
198
- import { getDataSDK, gql } from '@salesforce/sdk-data';
199
-
200
- const UPDATE_ACCOUNT = gql`
201
- mutation UpdateAccount($id: ID!, $name: String!) {
202
- uiapi {
203
- AccountUpdate(input: {
204
- Id: $id
205
- Account: {
206
- Name: { value: $name }
207
- }
208
- }) {
209
- Record {
210
- Id
211
- Name {
212
- value
213
- }
214
- }
215
- }
216
- }
217
- }
218
- `;
219
-
220
- const data = await getDataSDK();
221
- const result = await data.graphql?.<UpdateAccountMutation>(UPDATE_ACCOUNT, {
222
- id: '001...',
223
- name: 'New Name',
224
- });
225
-
226
- if (result?.errors?.length) {
227
- throw new Error(result.errors.map(e => e.message).join('; '));
228
- }
229
- ```
230
-
231
- UI API example (using the SDK's fetch):
232
-
233
- ```typescript
234
- import { getDataSDK } from '@salesforce/sdk-data';
235
-
236
- async function fetchRecord(recordId: string) {
237
- const data = await getDataSDK();
238
- const response = await data.fetch!(`/services/data/v62.0/ui-api/records/${recordId}`);
239
-
240
- if (!response.ok) {
241
- throw new Error(`UI API failed: ${response.status}`);
242
- }
243
-
244
- return response.json();
245
- }
246
- ```
247
-
248
- ## Einstein LLM Gateway (AI/Generative Features)
249
-
250
- Einstein LLM Gateway provides AI and generative capabilities for your React application. Use this service when you want to add features such as:
251
-
252
- - Text generation
253
- - Prompt-based AI responses
254
- - LLM-powered content creation
255
- - AI-assisted workflows
256
-
257
- ### Einstein LLM Gateway Pattern
258
-
259
- ```typescript
260
- import { getDataSDK } from '@salesforce/sdk-data';
261
-
262
- async function callEinsteinGenerations({ prompt, model = 'gpt-4', signal }: {
263
- prompt: string;
264
- model?: string;
265
- signal?: AbortSignal;
266
- }): Promise<string> {
267
- const url = '/services/data/v62.0/einstein/llm/prompt/generations';
268
- const sdk = await getDataSDK();
269
- const resp = await sdk.fetch!(url, {
270
- method: 'POST',
271
- headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
272
- body: JSON.stringify({
273
- additionalConfig: {
274
- applicationName: 'PromptTemplateGenerationsInvocable',
275
- model,
276
- },
277
- promptTextorId: prompt,
278
- }),
279
- signal,
280
- });
281
-
282
- if (!resp.ok) {
283
- throw new Error(`Einstein LLM request failed (${resp.status})`);
284
- }
285
-
286
- const data = await resp.json();
287
- return data?.generations?.[0]?.text || '';
288
- }
289
- ```
290
-
291
- ## Error Handling Pattern
292
-
293
- - Always implement robust try/catch for async operations.
294
- - Provide useful but safe error messages (no sensitive data leakage).
295
-
296
- ```javascript
297
- async function safeFetch(recordId) {
298
- try {
299
- const data = await fetchRecord(recordId);
300
- return data;
301
- } catch (err) {
302
- console.error('Salesforce UI API Error:', err);
303
- throw err;
304
- }
305
- }
306
- ```
307
-
308
- ## Anti-Patterns (Do NOT do these)
309
-
310
- - **Do NOT make UI/layout/theme/nav changes without updating appLayout.tsx** — If you add or change navigation, header, footer, sidebar, or overall layout, you must also edit the layout shell (`src/appLayout.tsx`). Leaving appLayout.tsx untouched while editing only pages or components is an error.
311
- - **Apex REST is not available in React applications** - Do NOT attempt to use or call Apex REST endpoints from React code
312
- - Unnecessary Apex controllers for simple UI API/GraphQL operations
313
- - Missing error handling for async operations
314
- - Hardcoded Salesforce URLs, IDs, or sensitive data
315
- - Ignoring field-level security and permission checks
316
- - Direct DOM manipulation in React components
317
- - Using LWC-specific patterns (`@wire`, LDS) or `@salesforce/*` modules in React
318
-
319
- ## Security Standards (CRITICAL)
320
-
321
- - Validate user permissions before data operations.
322
- - Respect record sharing rules and field-level security.
323
- - Never hardcode credentials or secrets in client code.
324
- - Sanitize all user inputs.
325
- - Use HTTPS for all API calls.
326
-
327
- ### Authentication Error Handling (MANDATORY)
328
-
329
- - The Data SDK handles 401/403 errors.
330
- - When a 401 (Unauthorized) or 403 (Forbidden) response is received, trigger a page refresh with `window.location.reload()` to redirect to login.
331
-
332
- ### Notes
333
-
334
- - avoid swallowing errors.
335
-
336
- Input sanitization example:
337
-
338
- ```javascript
339
- function sanitizeInput(input) {
340
- if (typeof input !== 'string') return '';
341
- return input
342
- .trim()
343
- .replace(/<script[^>]*>.*?<\/script>/gi, '')
344
- .replace(/javascript:/gi, '')
345
- .slice(0, 255);
346
- }
347
- ```
348
-
349
- ## Performance Standards
350
-
351
- - Implement client-side caching (e.g., RTK Query or React Query) for API data.
352
- - Use `React.memo`, `useMemo`, and `useCallback` where appropriate.
353
- - Implement proper loading and error states.
354
-
355
- ## TypeScript Standards
356
-
357
- - Prefer TypeScript for React components and utilities.
358
- - Define clear and explicit interfaces for props and API data.
359
-
360
- ## Testing Requirements
361
-
362
- - Use Jest + React Testing Library for UI tests.
363
- - Test loading, success, and error states for data-fetching components.
364
-
365
- ## Application Generation Rules
366
-
367
- - When requested to generate a new application:
368
- - Replace existing template content; do not append to the starter.
369
- - Preserve the entry point and routes under `force-app/main/default/webapplications/<appName>/src/`.
370
- - Keep existing build and deploy commands working.
371
- - Follow the Data Access and Security standards above.
372
-
373
- ## Debugging Guidance
374
-
375
- - Use React DevTools for component inspection.
376
- - Monitor the browser Network tab for REST/GraphQL calls and auth headers.
377
- - Implement Error Boundaries for unhandled exceptions.
378
-
379
- ## Quality Checklist (for generated code)
380
-
381
- - Entry point maintained (`App.tsx` or `App.js` present and wired in routes/pages).
382
- - **Layout maintained (MANDATORY for UI work):** For any change that affects global layout, nav, header, footer, sidebar, or theme, you **must** have edited `appLayout.tsx`. If you did not open or modify appLayout.tsx, the change is incomplete — go back and update the layout file.
383
- - Uses shadcn/ui and Tailwind for UI.
384
- - Follows Data Access rules with proper auth and error handling.
385
- - Enforces Security standards and input sanitization.
386
- - Includes loading and error states.
387
- - Performance optimizations present where reasonable.
388
- - Tests cover core UI and data interactions.
@@ -1,45 +0,0 @@
1
- #Goal
2
-
3
- - You are configuring image usage for React applications generated through Vibe Coding.
4
- - Your goal is to ensure Unsplash is used as the default image source unless the developer provides their own images.
5
-
6
- # AI Customization Rule: React Image Processing
7
-
8
- Image handling standards for React web apps (SFDX): CSP compliance, accessibility, and proper image sources.
9
-
10
- ## Targets (File Pattern Matching)
11
-
12
- - `force-app/main/default/webapplications/*/**/*.tsx`
13
- - `force-app/main/default/webapplications/*/**/*.ts`
14
- - `force-app/main/default/webapplications/*/**/*.jsx`
15
- - `force-app/main/default/webapplications/*/**/*.js`
16
- - `force-app/main/default/webapplications/*/**/*.html`
17
-
18
- ## Core Rules
19
-
20
- ### Default Image Source: Unsplash
21
-
22
- Use Unsplash by default (pre-configured in CSP):
23
-
24
- ```
25
- https://images.unsplash.com/photo-{PHOTO_ID}?w={WIDTH}&h={HEIGHT}&fit=crop&q=80
26
- ```
27
-
28
- Sample Photo IDs: `1557683316-973673baf926` (tech), `1506905925346-21bda4d32df4` (nature)
29
-
30
- ### Alternative Sources
31
-
32
- If user requests another source (Pexels, custom):
33
-
34
- - Use requested source
35
- - Inform user: "Add CSP Trusted Site in Setup → Security → CSP Trusted Sites"
36
-
37
- ### Accessibility (MANDATORY)
38
-
39
- - Always include descriptive `alt` text
40
- - Use `alt=""` for decorative images only
41
-
42
- ### Avoid (CSP Violations)
43
-
44
- - Avoid until requested `placeholder.com`, `picsum.photos`, `via.placeholder.com`
45
- - Pre-configured: `images.unsplash.com`, `source.unsplash.com`, `images.pexels.com`
@@ -1,23 +0,0 @@
1
- # UI layout: always update appLayout.tsx (MANDATORY)
2
-
3
- **Build navigation into the app layout:** The app layout (e.g. `appLayout.tsx`) must **include** the navigation—header nav, sidebar, or both—so that every routed page is wrapped by the same shell and nav. Do not omit nav from the layout or rely on per-page nav only.
4
-
5
- ## Targets (File Pattern Matching)
6
-
7
- Apply this rule when editing React UI or layout:
8
-
9
- - `force-app/main/default/webapplications/*/src/appLayout.tsx`
10
- - `force-app/main/default/webapplications/*/src/**/*.tsx`
11
- - `force-app/main/default/webapplications/*/src/**/*.jsx`
12
-
13
- ## Rule (CRITICAL)
14
-
15
- **When making any UI change** that affects navigation, header, footer, sidebar, theme, or overall layout:
16
-
17
- 1. **You MUST also edit `src/appLayout.tsx`** (the theme layout used by `routes.tsx`).
18
- 2. Do not only edit pages or components and leave `appLayout.tsx` unchanged.
19
- 3. Before finishing: confirm you opened and modified `appLayout.tsx` if the change touches layout/nav/theme. If you did not, the task is incomplete — update the layout file.
20
-
21
- **Navigation menu and placeholder name/design (often missed):** When editing the layout, **always** update (1) the **navigation menu**—replace default nav items and labels with app-specific links and names; do not leave template "Home"/"About" or placeholder links; (2) the **app name** in header/nav brand/footer and in `index.html` `<title>`—use the actual app name, not the template placeholder; (3) any **placeholder design** in the shell so it matches the app. See **webapp-nav-and-placeholders.md**.
22
-
23
- Path: `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` (or the app's layout file that `routes.tsx` imports). (or the app’s layout file that `routes.tsx` imports).
@@ -1,33 +0,0 @@
1
- ---
2
- description: A4D rule — always update navigation menu and placeholder name/design; never leave default
3
- alwaysApply: true
4
- ---
5
-
6
- # Navigation Menu & Placeholder Name/Design (MANDATORY)
7
-
8
- Agents consistently miss these. **You must not leave them default.**
9
-
10
- **Navigation belongs in the app layout:** Build the navigation **into** the app layout (e.g. `appLayout.tsx`). The layout component must include the nav—header nav, sidebar, or both—so every page is wrapped by the same shell and nav. Do not omit navigation from the layout or put it only on individual pages.
11
-
12
- ## 1. Navigation menu
13
-
14
- - **Always edit the navigation menu** in the layout file (typically `src/appLayout.tsx`). Replace default/placeholder nav items and labels with **app-specific** links and names.
15
- - Do **not** leave template items (e.g. "Home", "About", generic links or placeholder labels). Use real routes and labels that match the app (e.g. "Dashboard", "Products", "Orders" for an e‑commerce app).
16
- - The navigation is part of the app shell; it lives in **appLayout.tsx** (or the file that `routes.tsx` uses as the layout). Open that file and update every nav link and label.
17
-
18
- **Check before finishing:** Did I change the nav items and labels in the layout file to match this app? If not, the task is incomplete.
19
-
20
- ## 2. Placeholder name and design
21
-
22
- - **Replace the placeholder app name** everywhere it appears: header, nav brand/logo area, footer, document `<title>`, and any "Welcome to…" or generic title text. Use the **actual app name** (e.g. the name used in `sf webapp generate -n <AppName>` or the user's requested name).
23
- - **Replace placeholder design** in the shell: default header/footer styling, generic logo area, and any template branding must be updated to match the app's aesthetic (or at least use the real app name and intentional styling).
24
-
25
- **Check before finishing:** Is the app name and shell design still the template default anywhere? If yes, update it.
26
-
27
- ## Where to edit
28
-
29
- - **Layout/nav/branding:** `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` — the app layout must contain the navigation (build it in here).
30
- - **Document title:** `force-app/main/default/webapplications/<appName>/index.html`
31
- - **Root page content:** The component rendered at the root route (often `Home` or similar in `routes.tsx`)
32
-
33
- Completing a web app task includes updating **navigation menu**, **app name in header/nav/footer/title**, and **placeholder design** in the shell—not only the main page content.
@@ -1,32 +0,0 @@
1
- ---
2
- description: A4D rule — build UI first, then business logic for web apps
3
- alwaysApply: true
4
- ---
5
-
6
- # A4D Rule: UI First, Then Business Logic (Proceed Immediately After UI)
7
-
8
- When building or modifying a web application (or any feature within it):
9
-
10
- 1. **Build the UI first**
11
- - Implement layout, structure, and components (pages, forms, lists, navigation).
12
- - Apply styling, theming, and design-system usage so the interface is visually complete and navigable.
13
- - Use placeholder or mock data only where needed to render the UI; do not wire real APIs yet.
14
-
15
- 2. **Proceed to API and business logic immediately after UI completion (same iteration)**
16
- - As soon as the UI for a feature is visually complete and routable, begin wiring the data layer for that same feature in the same iteration.
17
- - Add data fetching (GraphQL preferred per LDS rules, then UI API; avoid Apex REST for React), state management, and event handlers.
18
- - Connect forms and actions to real APIs and backend behavior.
19
- - Add validation, loading, and user-friendly error states.
20
- - Keep the build green; fix TypeScript and ESLint issues as you wire logic.
21
-
22
- 3. **Quality gates before marking the feature complete**
23
- - Run `npm run lint` and ensure 0 errors (warnings acceptable if minor).
24
- - Run `npm run build` and ensure it passes.
25
- - Replace any remaining mock data relevant to the feature with real data paths or clearly marked TODOs if blocked.
26
-
27
- **Rationale:** A visible, stable UI gives a clear target, and immediately wiring the API and business logic in the same iteration ensures end‑to‑end functionality and avoids stale mock UIs. This also aligns with design-system guidance (invoke **webapplications-design-system**) and LDS data access rules.
28
-
29
- Notes:
30
- - Within LDS, prefer GraphQL for complex reads and mutations; fall back to standard UI API adapters when appropriate.
31
- - For React apps, do not implement or call Apex REST. If server-side logic is truly required and cannot be achieved via GraphQL/UI API, surface a limitation explicitly.
32
- - If a feature's UI spans multiple pages, wire business logic page-by-page as each page's UI stabilizes, rather than deferring all logic to the end.
@@ -1,2 +0,0 @@
1
- declare const _default: import("vite").UserConfigFnObject;
2
- export default _default;
@@ -1,93 +0,0 @@
1
- import { defineConfig } from 'vite';
2
- import react from '@vitejs/plugin-react';
3
- import path from 'path';
4
- import { resolve } from 'path';
5
- import tailwindcss from '@tailwindcss/vite';
6
- import salesforce from '@salesforce/vite-plugin-webapp-experimental';
7
- import codegen from 'vite-plugin-graphql-codegen';
8
- export default defineConfig(function (_a) {
9
- var mode = _a.mode;
10
- return {
11
- // Ensure root base for e2e/static serve; plugin may override when deployed under a path
12
- base: '/',
13
- plugins: [
14
- tailwindcss(),
15
- react(),
16
- salesforce(),
17
- codegen({
18
- // Path to the codegen config file
19
- configFilePathOverride: resolve(__dirname, 'codegen.yml'),
20
- // Run codegen on dev server start
21
- runOnStart: true,
22
- // Don't run codegen on build for now
23
- runOnBuild: false,
24
- // Enable file watcher during development
25
- enableWatcher: true,
26
- // Fail build if codegen errors
27
- throwOnBuild: true,
28
- }),
29
- ],
30
- // Build configuration for MPA
31
- build: {
32
- outDir: resolve(__dirname, 'dist'),
33
- assetsDir: 'assets',
34
- sourcemap: false,
35
- },
36
- // Resolve aliases (shared between build and test)
37
- resolve: {
38
- dedupe: ['react', 'react-dom'],
39
- alias: {
40
- '@': path.resolve(__dirname, './src'),
41
- '@api': path.resolve(__dirname, './src/api'),
42
- '@components': path.resolve(__dirname, './src/components'),
43
- '@utils': path.resolve(__dirname, './src/utils'),
44
- '@styles': path.resolve(__dirname, './src/styles'),
45
- '@assets': path.resolve(__dirname, './src/assets'),
46
- },
47
- },
48
- // Vitest configuration
49
- test: {
50
- // Override root for tests (build uses src/pages as root)
51
- root: resolve(__dirname),
52
- // Use jsdom environment for React component testing
53
- environment: 'jsdom',
54
- // Setup files to run before each test
55
- setupFiles: ['./src/test/setup.ts'],
56
- // Global test patterns
57
- include: [
58
- 'src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}',
59
- 'src/**/__tests__/**/*.{js,mjs,cjs,ts,mts,cts,jsx,tsx}',
60
- ],
61
- // Coverage configuration
62
- coverage: {
63
- provider: 'v8',
64
- reporter: ['text', 'html', 'clover', 'json'],
65
- exclude: [
66
- 'node_modules/',
67
- 'src/test/',
68
- 'src/**/*.d.ts',
69
- 'src/main.tsx',
70
- 'src/vite-env.d.ts',
71
- 'src/components/**/index.ts',
72
- '**/*.config.ts',
73
- 'build/',
74
- 'dist/',
75
- 'coverage/',
76
- 'eslint.config.js',
77
- ],
78
- thresholds: {
79
- global: {
80
- branches: 85,
81
- functions: 85,
82
- lines: 85,
83
- statements: 85,
84
- },
85
- },
86
- },
87
- // Test timeout
88
- testTimeout: 10000,
89
- // Globals for easier testing
90
- globals: true,
91
- },
92
- };
93
- });