@salesforce/templates 66.4.0 → 66.4.2

package/lib/templates/project/reactb2x/_r_/skills/webapp-ui-ux/SKILL.md

@@ -1,11 +1,13 @@
 ---
-name: ui-ux
-description: Comprehensive design guide for React + Tailwind + shadcn/ui applications. Searchable database with priority-based recommendations for styles, color palettes, font pairings, UX guidelines, and chart types.
+name: webapp-ui-ux
+description: Use when editing any UI code in the web application — styling, layout, design, appearance, Tailwind, shadcn, colors, typography, icons, or visual/UX changes. Comprehensive design guide and searchable database for React + Tailwind + shadcn/ui (styles, color palettes, font pairings, UX guidelines, chart types).
 ---
 
-# ui-ux
+# Web App UI/UX
 
-Comprehensive design guide for React + Tailwind + shadcn/ui applications. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types. Searchable database with priority-based recommendations.
+Use this skill whenever you are editing UI code in the web application — styling, layout, design, appearance, Tailwind, shadcn, colors, typography, icons, or any visual/UX change.
+
+Comprehensive design guide for React + Tailwind + shadcn/ui. Contains 67 styles, 96 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types. Searchable database with priority-based recommendations.
 
 ## Prerequisites
 
@@ -200,9 +202,10 @@ These are frequently overlooked issues that make UI look unprofessional:
 
 | Rule | Do | Don't |
 |------|----|----- |
-| **No emoji icons** | Use SVG icons (Heroicons, Lucide, Simple Icons) | Use emojis like 🎨 🚀 ⚙️ as UI icons |
+| **Icons: Lucide only** | Use **lucide-react** for all UI icons: `import { IconName } from 'lucide-react'` | Use Heroicons, react-icons, or other icon libraries; use emojis as icons |
+| **No emojis ever** | Use words + Lucide icons for labels, empty states, tooltips, headings | Use emojis anywhere in UI or user-facing text (e.g. 🎨 🚀 ⚙️) |
 | **Stable hover states** | Use color/opacity transitions on hover | Use scale transforms that shift layout |
-| **Correct brand logos** | Research official SVG from Simple Icons | Guess or use incorrect logo paths |
+| **Correct brand logos** | Research official SVG from Simple Icons (when needed outside Lucide) | Guess or use incorrect logo paths |
 | **Consistent icon sizing** | Use fixed viewBox (24x24) with w-6 h-6 | Mix different icon sizes randomly |
 
 ### Interaction & Cursor
@@ -237,8 +240,8 @@ These are frequently overlooked issues that make UI look unprofessional:
 Before delivering UI code, verify these items:
 
 ### Visual Quality
-- [ ] No emojis used as icons (use SVG instead)
-- [ ] All icons from consistent icon set (Heroicons/Lucide)
+- [ ] No emojis anywhere (UI, labels, empty states, tooltips—use words + Lucide icons only)
+- [ ] All icons from **lucide-react** only (no Heroicons, react-icons, or emojis)
 - [ ] Brand logos are correct (verified from Simple Icons)
 - [ ] Hover states don't cause layout shift
 - [ ] Use theme colors directly (bg-primary) not var() wrapper

package/lib/templates/project/reactb2x/_r_/webapp-cli-commands.md

@@ -0,0 +1,88 @@
+---
+description: CLI command generation rules — no node -e one-liners; safe quoting and scripts
+paths:
+  - "**/webapplications/**/*"
+---
+
+# A4D Enforcement: CLI Command Generation & No `node -e` One-Liners
+
+When **generating any CLI/shell commands** (for the user or for automation), follow the rules below. Default shell is **Zsh** (macOS); commands must work there without Bash-only syntax.
+
+---
+
+## 1. Never Use Complex `node -e` One-Liners
+
+**Forbidden:** `node -e` (or `node -p`, `node --eval`) for file manipulation, string replacement, reading/writing configs, or multi-line logic.
+
+**Why:** In Zsh, `node -e '...'` **silently breaks** due to:
+- **`!` (history expansion):** Zsh expands `!` in double-quoted strings → `event not found` or wrong output.
+- **Backticks:** `` ` `` is command substitution; the shell runs it before Node sees the string.
+- **Nested quoting:** Escaping differs between Bash and Zsh; multi-line JS in one string is fragile.
+
+**Allowed:** Trivial one-line only if it has **no** backticks, no `!`, no nested quotes, no multi-line, no `fs` usage. Example: `node -e "console.log(1+1)"`. If in doubt, **use a script file**.
+
+---
+
+## 2. How To Generate CLI Commands Correctly
+
+### Run Node scripts by path, not inline code
+
+- **Do:** `node scripts/setup-cli.mjs --target-org myorg`
+- **Do:** `node path/to/script.mjs arg1 arg2`
+- **Do not:** `node -e "require('fs').writeFileSync(...)"` or any non-trivial inline JS.
+
+### For file edits or transforms
+
+1. **Prefer IDE/agent file tools** (StrReplace, Write, etc.) — they avoid the shell.
+2. **Otherwise:** write a **temporary `.js` or `.mjs` file**, run it, then remove it. Use a **heredoc with quoted delimiter** so the shell does not interpret `$`, `` ` ``, or `!`:
+
+```bash
+cat > /tmp/_transform.js << 'SCRIPT'
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+data.name = 'my-app';
+fs.writeFileSync('package.json', JSON.stringify(data, null, 2) + '\n');
+SCRIPT
+node /tmp/_transform.js && rm /tmp/_transform.js
+```
+
+3. **Simple replacements:** `sed -i '' 's/old/new/g' path/to/file` (macOS: `-i ''`).
+4. **JSON:** `jq '.name = "my-app"' package.json > tmp.json && mv tmp.json package.json`.
+
+### Quoting and shell safety
+
+- Use **single quotes** around the outer shell string when the inner content has `$`, `` ` ``, or `!`.
+- For heredocs that must be literal, use **`<< 'END'`** (quoted delimiter) so the body is not expanded.
+- **Do not** generate commands that rely on Bash-only features (e.g. `[[ ]]` is fine in Zsh; avoid `source` vs `.` if you need POSIX).
+
+### Paths and working directory
+
+- **State where to run from** when it matters, e.g. "From project root" or "From `force-app/main/default/webapplications/<appName>`".
+- Prefer **explicit paths** or `cd <dir> && ...` so the command is copy-paste safe.
+- This project: setup is `node scripts/setup-cli.mjs --target-org <alias>` from **project root**. Web app commands (`npm run dev`, `npm run build`, `npm run lint`) run from the **web app directory** (e.g. `force-app/main/default/webapplications/<appName>` or `**/webapplications/<appName>`).
+
+### npm / npx
+
+- Use **exact package names** (e.g. `npx @salesforce/webapps-features-experimental list`).
+- For app-specific scripts, **cd to the web app directory first**, then run `npm run <script>` or `npm install ...`.
+- Chain steps with `&&`; one logical command per line is clearer than one giant line.
+
+### Summary checklist when generating a command
+
+- [ ] No `node -e` / `node -p` / `node --eval` with complex or multi-line code.
+- [ ] If Node logic is needed, use `node path/to/script.mjs` or a temp script with heredoc `<< 'SCRIPT'`.
+- [ ] No unescaped `!`, `` ` ``, or `$` in double-quoted strings in Zsh.
+- [ ] Working directory and required args (e.g. `--target-org`) are clear.
+- [ ] Prefer file-editing tools over shell one-liners when editing project files.
+
+---
+
+## 3. Violation Handling
+
+- If a generated command used a complex `node -e` one-liner, **revert and redo** using a script file, `sed`/`jq`, or IDE file tools.
+- If the user sees `event not found`, `unexpected token`, or garbled output, **check for**:
+  - `node -e` with special characters,
+  - Double-quoted strings containing `!` or backticks,
+  - Wrong working directory or missing args.
+
+**Cross-reference:** **webapp.md** (MUST FOLLOW #1) summarizes the no–`node -e` rule; this file is the full reference for CLI command generation and alternatives.

package/lib/templates/project/reactb2x/_r_/webapp-react-code-quality.md

@@ -1,7 +1,7 @@
 ---
 description: Code quality and build validation standards
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # Code Quality & Build Validation

package/lib/templates/project/reactb2x/_r_/webapp-react-typescript.md

@@ -1,7 +1,7 @@
 ---
 description: Strict TypeScript standards for type-safe React applications
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # TypeScript Standards

package/lib/templates/project/reactb2x/_r_/webapp-react.md

@@ -1,7 +1,7 @@
 ---
 description: React-specific patterns and Salesforce data access for SFDX web apps
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # React Web App (SFDX)
@@ -18,6 +18,15 @@ For layout, navigation, and generation rules, see **webapp.md**.
 - Dev server: `npm run dev`
 - Build: `npm run build`
 
+## Routing (React Router)
+
+Use a **single** router package for the app. When using `createBrowserRouter` and `RouterProvider` from `react-router`, all routing imports must come from **`react-router`** — not from `react-router-dom`.
+
+- ✅ `import { createBrowserRouter, RouterProvider, Link, useNavigate, useLocation, Outlet } from 'react-router';`
+- ❌ `import { Link } from 'react-router-dom';` when the app uses `RouterProvider` from `react-router`
+
+Mixing packages causes "Cannot destructure property 'basename' of ... as it is null" because `Link`/hooks from `react-router-dom` read a different context than the one provided by `RouterProvider` from `react-router`.
+
 ## Component Library (MANDATORY)
 
 Use **shadcn/ui** for UI components:
@@ -28,6 +37,42 @@ import { Card, CardHeader, CardContent } from '@/components/ui/card';
 import { Input } from '@/components/ui/input';
 ```
 
+## Icons & No Emojis (MANDATORY)
+
+- **Icons:** Use **lucide-react** only. Do not use Heroicons, Simple Icons, or other icon libraries in the web app.
+  - ✅ `import { Menu, Settings, Bell } from 'lucide-react';` then `<Menu className="w-5 h-5" />`
+  - ❌ Any emoji character as an icon or visual element (e.g. 🎨 🚀 ⚙️ 🔔)
+  - ❌ Other icon libraries (e.g. `@heroicons/react`, `react-icons`, custom SVG icon sets)
+- **No emojis ever:** Do not use emojis anywhere in the app: no emojis in UI labels, buttons, headings, empty states, tooltips, or any user-facing text. Use words and lucide-react icons instead.
+  - ✅ "Settings" with `<Settings />` icon
+  - ❌ "⚙️ Settings" or "Settings 🔧"
+- For icon usage patterns and naming, see the **webapp-ui-ux** skill (`.a4drules/skills/webapp-ui-ux/`, especially `data/icons.csv`).
+
+## Editing UI — Source Files Only (CRITICAL)
+
+When asked to edit the home page, a section, or any on-screen UI:
+
+- **Always edit the actual React/TSX source files.** Never output, paste, or generate raw HTML. The UI is built from components; the agent must locate the component file(s) that render the target area and change **JSX in those files**.
+- **Do not** replace JSX with HTML strings, and do not copy browser-rendered DOM (e.g. expanded `<div>`, `data-slot`, long class strings) into the codebase. That is the output of React + shadcn; the source is `.tsx` with `<Card>`, `<Input>`, etc.
+- **Edit inside the component that owns the UI.** If the element to change is rendered by a **child component** (e.g. `<GlobalSearchInput />` in `Home.tsx`), make the edit **inside that component's file** (e.g. `GlobalSearchInput.tsx`). Do **not** only wrap the component with extra elements in the parent (e.g. adding a `<section>` or `<div>` around `<GlobalSearchInput />`). The parent composes components; the visual/content change belongs in the component that actually renders that part of the UI.
+- **Where to edit:**
+  - **Home page content:** `src/pages/Home.tsx` — but if the target is inside a child (e.g. `<GlobalSearchInput />`), edit the child's file, not the parent.
+  - **Layout, header, nav:** `src/appLayout.tsx`.
+  - **Feature-specific UI (e.g. search, list):** open the **specific component file** that renders the target (e.g. `GlobalSearchInput.tsx` for the search input UI).
+- **Steps:** (1) Identify which **component** owns the section (follow the import: e.g. `GlobalSearchInput` → its file). (2) Open that component's file and modify the JSX there. (3) Only change the parent (e.g. `Home.tsx`) if the change is layout/ordering of components, not the internals of a child. Do not emit a standalone HTML snippet as the “edit.”
+
+## Mobile Nav / Hamburger — Must Be Functional
+
+When adding a navigation menu that includes a hamburger (or Menu icon) for mobile:
+
+- **Do not** add a hamburger/Menu icon that does nothing. The icon must **toggle a visible mobile menu**.
+- **Required implementation:**
+  1. **State:** e.g. `const [isOpen, setIsOpen] = useState(false);`
+  2. **Toggle button:** The hamburger/Menu button must have `onClick={() => setIsOpen(!isOpen)}` and `aria-label="Toggle menu"` (or equivalent).
+  3. **Conditional panel:** A mobile-only menu panel that renders when `isOpen` is true, e.g. `{isOpen && ( <div className="..."> ... nav links ... </div> )}`. Use responsive classes (e.g. `md:hidden`) so the panel is shown only on small screens if the desktop nav is separate.
+  4. **Close on navigation:** Each nav link in the mobile panel should call `onClick={() => setIsOpen(false)}` (or similar) so the menu closes when the user navigates.
+- Implement this in `appLayout.tsx` (or the component that owns the header/nav). See existing apps for the full pattern (state + button + conditional panel + link onClick).
+
 ## Styling
 
 - Use **Tailwind CSS** utility classes
@@ -137,11 +182,20 @@ window.location.reload();
 - ❌ Using LWC patterns (`@wire`, LDS) in React
 - ❌ Hardcoded Salesforce IDs or URLs
 - ❌ Missing error handling for async operations
+- ❌ Mixing `react-router` and `react-router-dom` (e.g. `RouterProvider` from `react-router` but `Link` from `react-router-dom`) — use one package for all routing imports
+- ❌ Using emojis anywhere in the app (labels, icons, empty states, headings, tooltips)
+- ❌ Using any icon library other than **lucide-react** (no Heroicons, react-icons, or emoji-as-icon)
+- ❌ Outputting or pasting raw HTML when editing UI — always edit the React/TSX source files (e.g. `Home.tsx`, `appLayout.tsx`, feature components)
+- ❌ Adding a hamburger or Menu icon for mobile nav without implementing toggle state, conditional menu panel, and close-on-navigate
 
 ## Quality Checklist
 
 - [ ] Entry point maintained (`app.tsx`)
 - [ ] Uses shadcn/ui and Tailwind
+- [ ] Icons from **lucide-react** only; no emojis anywhere in UI or user-facing text
+- [ ] UI changes made by editing .tsx source files (never by pasting raw HTML)
+- [ ] If mobile hamburger exists: it has toggle state, conditional menu panel, and close on link click
+- [ ] All routing imports from same package as router (e.g. `react-router` only)
 - [ ] DataSDK used for all Salesforce API calls
 - [ ] Proper error handling with try/catch
 - [ ] Loading and error states implemented

package/lib/templates/project/reactb2x/_r_/webapp-skills-first.md

@@ -1,7 +1,7 @@
 ---
 description: Always search for and read relevant skills before starting any task
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # Skills-First Protocol (MUST FOLLOW)

package/lib/templates/project/reactb2x/_r_/webapp-webapplication.md

@@ -0,0 +1,159 @@
+
+---
+paths:
+  - "**/webapplications/**/*"
+---
+
+# WebApplication Requirements
+
+## Bundle Rules
+- A WebApplication bundle must live under `webapplications/<AppName>/`
+- The bundle must contain `<AppName>.webapplication-meta.xml`
+- The metadata filename must exactly match the folder name
+- A build output directory must exist and contain at least one file
+- Default build output directory: `dist/`
+- If `webapplication.json.outputDir` is set, it overrides `dist/`
+
+Valid example:
+```text
+webapplications/
+  MyApp/
+    MyApp.webapplication-meta.xml
+    webapplication.json
+    dist/
+      index.html
+```
+
+## Metadata XML
+Required fields:
+- `masterLabel`
+- `version` (max 20 chars)
+- `isActive` (boolean)
+
+Optional fields:
+- `description` (max 255 chars)
+
+## webapplication.json
+`webapplication.json` is optional.
+
+Allowed top-level keys only:
+- `outputDir`
+- `routing`
+- `headers`
+
+### File Constraints
+- Must be valid UTF-8 JSON
+- Max size: 100 KB
+- Root must be a non-empty object
+- Never allow `{}`, arrays, or primitives as the root
+
+### Path Safety
+Applies to:
+- `outputDir`
+- `routing.fallback`
+
+Reject:
+- backslashes
+- leading `/` or `\`
+- `..` segments
+- null or control characters
+- globs: `*`, `?`, `**`
+- `%`
+
+All resolved paths must stay within the application bundle.
+
+### outputDir
+- Must be a non-empty string
+- Must reference a subdirectory only
+- Reject `.` and `./`
+- The directory must exist in the bundle
+- The directory must contain at least one file
+
+### routing
+- If present, must be a non-empty object
+- Allowed keys only:
+  - `rewrites`
+  - `redirects`
+  - `fallback`
+  - `trailingSlash`
+  - `fileBasedRouting`
+
+#### routing.trailingSlash
+- Must be one of: `"always"`, `"never"`, `"auto"`
+
+#### routing.fileBasedRouting
+- Must be a boolean
+
+#### routing.fallback
+- Must be a non-empty string
+- Must satisfy Path Safety rules
+- Target file must exist
+
+#### routing.rewrites
+- Must be a non-empty array
+- Each item must be a non-empty object
+- Allowed keys: `route`, `rewrite`
+- `rewrite` must be a non-empty string
+- `route`, if present, must be a non-empty string
+
+Example:
+```json
+{
+  "routing": {
+    "rewrites": [
+      { "route": "/app/:path*", "rewrite": "/index.html" }
+    ]
+  }
+}
+```
+
+#### routing.redirects
+- Must be a non-empty array
+- Each item must be a non-empty object
+- Allowed keys: `route`, `redirect`, `statusCode`
+- `redirect` must be a non-empty string
+- `route`, if present, must be a non-empty string
+- `statusCode`, if present, must be one of: `301`, `302`, `307`, `308`
+
+Example:
+```json
+{
+  "routing": {
+    "redirects": [
+      { "route": "/old-page", "redirect": "/new-page", "statusCode": 301 }
+    ]
+  }
+}
+```
+
+### headers
+- If present, must be a non-empty array
+- Each item must be a non-empty object
+- Allowed keys: `source`, `headers`
+- `headers` must be a non-empty array
+
+Each header entry must contain:
+- `key`: non-empty string
+- `value`: non-empty string
+
+Example:
+```json
+{
+  "headers": [
+    {
+      "source": "/assets/**",
+      "headers": [
+        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
+      ]
+    }
+  ]
+}
+```
+
+## Never Suggest
+- `{}` as the JSON root
+- `"routing": {}`
+- empty arrays
+- empty array items such as `[{}]`
+- `"outputDir": "."`
+- `"outputDir": "./"`

package/lib/templates/project/reactb2x/_r_/webapp.md

@@ -1,7 +1,7 @@
 ---
 description: Core web application rules for SFDX React apps
 paths:
-  - "force-app/main/default/webapplications/**/*"
+  - "**/webapplications/**/*"
 ---
 
 # Skills-First (MUST FOLLOW)
@@ -81,7 +81,7 @@ Agents consistently miss these. **You must not leave them default.**
 
 # Shell Command Safety (MUST FOLLOW)
 
-**Never use complex `node -e` one-liners** for file edits or multi-line transforms. They break in Zsh due to `!` history expansion and backtick interpolation. Use a temporary `.js` file, `sed`/`awk`, `jq`, or IDE file-editing tools instead. See **webapp-no-node-e.md** for full details and approved alternatives.
+**Never use complex `node -e` one-liners** for file edits or multi-line transforms. They break in Zsh due to `!` history expansion and backtick interpolation. Use a temporary `.js` file, `sed`/`awk`, `jq`, or IDE file-editing tools instead. See **webapp-cli-commands.md** for full details and approved alternatives.
 
 # Development Cycle
 

package/lib/templates/project/reactb2x/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.84.0",
+  "version": "1.101.3",
   "description": "Base SFDX project template",
   "private": true,
   "files": [

package/lib/templates/project/reactb2x/scripts/prepare-import-unique-fields.js

@@ -5,7 +5,7 @@
  *
  * Usage:
  *   node scripts/prepare-import-unique-fields.js
- *   node scripts/prepare-import-unique-fields.js --data-dir /path/to/force-app/main/default/data
+ *   node scripts/prepare-import-unique-fields.js --data-dir /path/to/<sfdx-source>/data
  *
  * Expects data dir to contain (optional) JSON files:
  *   Contact.json (Email with unique domain per run, LastName, FirstName, Phone — standard Contact)
@@ -18,8 +18,22 @@
 const fs = require('fs');
 const path = require('path');
 
-// When run from project root: scripts/prepare-import-unique-fields.js → data dir under force-app
-const DEFAULT_DATA_DIR = path.resolve(__dirname, '..', 'force-app/main/default/data');
+function resolveSfdxSource() {
+  const sfdxPath = path.resolve(__dirname, '..', 'sfdx-project.json');
+  if (!fs.existsSync(sfdxPath)) {
+    console.error('Error: sfdx-project.json not found at project root.');
+    process.exit(1);
+  }
+  const sfdxProject = JSON.parse(fs.readFileSync(sfdxPath, 'utf8'));
+  const pkgDir = sfdxProject?.packageDirectories?.[0]?.path;
+  if (!pkgDir) {
+    console.error('Error: No packageDirectories[].path found in sfdx-project.json.');
+    process.exit(1);
+  }
+  return path.resolve(__dirname, '..', pkgDir, 'main', 'default');
+}
+
+const DEFAULT_DATA_DIR = path.resolve(resolveSfdxSource(), 'data');
 
 function parseArgs() {
   const args = process.argv.slice(2);