@salesforce/webapp-template-feature-react-file-upload-experimental 1.55.0

package/dist/.a4drules/webapp-nav-and-placeholders.md

@@ -0,0 +1,33 @@
+---
+description: A4D rule — always update navigation menu and placeholder name/design; never leave default
+alwaysApply: true
+---
+
+# Navigation Menu & Placeholder Name/Design (MANDATORY)
+
+Agents consistently miss these. **You must not leave them default.**
+
+**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.
+
+## 1. Navigation menu
+
+- **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.
+- 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).
+- 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.
+
+**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.
+
+## 2. Placeholder name and design
+
+- **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).
+- **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).
+
+**Check before finishing:** Is the app name and shell design still the template default anywhere? If yes, update it.
+
+## Where to edit
+
+- **Layout/nav/branding:** `force-app/main/default/webapplications/<appName>/src/appLayout.tsx` — the app layout must contain the navigation (build it in here).
+- **Document title:** `force-app/main/default/webapplications/<appName>/index.html`
+- **Root page content:** The component rendered at the root route (often `Home` or similar in `routes.tsx`)
+
+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.

package/dist/.a4drules/webapp-no-node-e.md

@@ -0,0 +1,25 @@
+---
+description: A4D rule — no node -e; use replace_in_file / write_to_file only
+alwaysApply: true
+---
+
+# A4D Enforcement: No node -e
+
+This project forbids using "node -e" for any operation (file manipulation, string replacement, reading/writing configs, shell automation).
+
+Policy:
+- Never use "node -e" one-liners.
+- Use replace_in_file or write_to_file for code/config edits.
+- Use jq/sed/awk cautiously when needed; prefer replace_in_file for deterministic edits.
+- For JSON edits: prefer write_to_file after reading, or replace_in_file with precise diffs.
+- For ESLint/TS config changes: edit files directly via write_to_file or replace_in_file.
+
+Rationale:
+- Ensures reproducibility and auditability.
+- Avoids shell escaping bugs and cross-platform inconsistencies.
+- Aligns with project reliability protocol.
+
+Violation handling:
+- If any prior step used "node -e", revert and redo using write_to_file or replace_in_file.
+
+**Cross-reference:** This rule is also summarized in **webapp.md** (MUST FOLLOW #1). Both apply.

package/dist/.a4drules/webapp-ui-first.md

@@ -0,0 +1,32 @@
+---
+description: A4D rule — build UI first, then business logic for web apps
+alwaysApply: true
+---
+
+# A4D Rule: UI First, Then Business Logic (Proceed Immediately After UI)
+
+When building or modifying a web application (or any feature within it):
+
+1. **Build the UI first**
+   - Implement layout, structure, and components (pages, forms, lists, navigation).
+   - Apply styling, theming, and design-system usage so the interface is visually complete and navigable.
+   - Use placeholder or mock data only where needed to render the UI; do not wire real APIs yet.
+
+2. **Proceed to API and business logic immediately after UI completion (same iteration)**
+   - 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.
+   - Add data fetching (GraphQL preferred per LDS rules, then UI API; avoid Apex REST for React), state management, and event handlers.
+   - Connect forms and actions to real APIs and backend behavior.
+   - Add validation, loading, and user-friendly error states.
+   - Keep the build green; fix TypeScript and ESLint issues as you wire logic.
+
+3. **Quality gates before marking the feature complete**
+   - Run `npm run lint` and ensure 0 errors (warnings acceptable if minor).
+   - Run `npm run build` and ensure it passes.
+   - Replace any remaining mock data relevant to the feature with real data paths or clearly marked TODOs if blocked.
+
+**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.
+
+Notes:
+- Within LDS, prefer GraphQL for complex reads and mutations; fall back to standard UI API adapters when appropriate.
+- 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.
+- 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.

package/dist/.a4drules/webapp.md

@@ -0,0 +1,75 @@
+# MUST FOLLOW
+
+0. **Always invoke the `local-expert` MCP** when dealing with web applications: call **`get_expert_knowledge`** with topic **`webapplications-design-system`** (for UI/design), and with **`webapplications`** when generating or structuring the app. Do not skip the design-system expert for any web app UI work.
+1. **No `node -e`.** This project forbids `node -e` for any operation (file edits, config, shell automation). Use `replace_in_file` or `write_to_file` only. See **webapp-no-node-e.md**.
+
+# React Development & Stability Rules
+
+## Terminal & Execution Strategy
+- **NEVER use `node -e`** for file manipulation, string replacement, or reading files. Forbidden. Use `replace_in_file` or `write_to_file` only. 
+- ALWAYS use `replace_in_file` or `write_to_file` for code changes.
+- IF you must parse JSON (like package.json), use `jq` if available. Otherwise, read the file and process it internally.
+- ALWAYS use `npm` or `yarn` commands directly rather than writing custom Node scripts to trigger them.
+
+## React & TypeScript Standards
+- Component Architecture: Prefer functional components with hooks.
+- File Naming: Use PascalCase for components (e.g., `Button.tsx`) and camelCase for hooks (e.g., `useAuth.ts`).
+- Imports: Use absolute paths (e.g., `@/components/...`) if the `tsconfig.json` or `vite.config.ts` supports it.
+- State: Default to `useState` for local state; avoid adding global state libraries unless requested.
+
+## Reliability Protocol
+- Before running any build or test command, check for the existence of `node_modules`. If missing, prompt to run `npm install`.
+- When searching for code, use `search_files` with regex rather than trying to `grep` or `awk` through the terminal.
+- If a command fails twice, STOP and report the exact error to the user rather than attempting a third "creative" bash one-liner.
+
+# General app generation guidance
+
+Your goal is to create a functioning app on Salesforce platform. Do not mock UIs, but use tools at your disposal, such as custom objects, graphql API, Apex controllers in order to achieve your goal.
+
+**Home page must be populated:** The home page (root route) must never be left as the default template. Always populate it with real content—e.g. landing content, banners, tiles, hero, navigation to main features—tailored to the app or use case. Make it visually pleasing and purposeful. Do not leave placeholder or "Welcome to..." default content.
+
+**Replace default boilerplate:** Always replace default scaffold content (e.g. "React App", "Vite + React", default page titles, placeholder headings in index.html or App.tsx) with **project- or app-specific** names and copy. Do not leave generic "React App" or template placeholders in the UI or document title.
+
+**Navigation menu and placeholder name/design (critical — often missed):** **Build the navigation into the app layout** (`appLayout.tsx`) so every page shares the same nav. Always edit the **navigation menu** in that layout file: replace default nav items and labels with app-specific links and names; do not leave template "Home"/"About" or placeholder links. Always replace the **placeholder app name** in header, nav brand, footer, and `<title>` with the actual app name, and update **placeholder design** (header/footer/shell) so it's not the template default. See **webapp-nav-and-placeholders.md**.
+
+**Frontend aesthetics (avoid AI slop):** Make creative, distinctive frontends that surprise and delight. Use distinctive typography (avoid Inter, Roboto, Arial, Space Grotesk as defaults), cohesive color with sharp accents (use CSS variables; avoid purple-on-white clichés), high-impact motion (e.g. staggered reveals), and atmosphere/depth in backgrounds. Do not converge on generic, cookie-cutter layouts. Follow **webapplications-design-system** expert knowledge for full guidance.
+
+# SFDX React Web Application Creation
+
+When the user asks to **create a React app** (or a web app, webpplication, etc) in this SFDX project:
+
+1. **Generate the app** using the Salesforce CLI:
+   \`\`\`bash
+   sf webapp generate -n MyWebApp -t reactbasic
+   \`\`\`
+   Use the app name the user requested instead of \`MyWebApp\` if they specify one.
+
+Do not use \`create-react-app\`, Vite, or other generic React scaffolds for this scenario; use \`sf webapp generate\` so the app is SFDX-aware.
+
+2. **For B2B/B2C or authenticated/guest apps:** Also create site container metadata and create and configure Digital Experience Sites to host the React web application.
+
+When modifying webapp in an SFDX project, use the experts MCP to obtain the latest guidance and design before starting implementation. Never assume or create tools that are not explicitly available
+
+3. Repeat iterations until the there are no pending actions left.
+
+
+# Software development cycle (modified for continuous execution)
+
+- Execute tasks continuously until all planned items are complete in the current iteration, without pausing after intermediate checkpoints.
+- Maintain a running checklist and proceed through it sequentially.
+- Quality gates (lint/build) remain required, but failures should be remediated inline and the workflow should continue through all feature tasks in this iteration unless the user directs otherwise.
+
+## Attempt Completion Enforcement (Local Project Rule)
+
+- Do NOT invoke attempt_completion until ALL checklist items for the current iteration are complete and quality gates pass.
+- Intermediate status updates must use task_progress on tool calls (never attempt_completion) until completion criteria are met.
+- The only exceptions that allow early attempt_completion are:
+  - A blocking error that cannot be resolved after reasonable remediation and requires user input
+  - The user explicitly instructs to pause or complete early
+
+## Stop Conditions
+
+Only stop when:
+- All checklist items are completed and quality gates pass, or
+- A blocking error cannot be resolved after reasonable remediation, or
+- The user explicitly asks to pause.

package/dist/.forceignore

@@ -0,0 +1,15 @@
+# List files or directories below to ignore them when running force:source:push, force:source:pull, and force:source:status
+# More information: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_exclude_source.htm
+#
+
+package.xml
+
+# LWC configuration files
+**/jsconfig.json
+**/.eslintrc.json
+
+# LWC Jest
+**/__tests__/**
+
+node_modules/
+.DS_Store

package/dist/.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+npm run precommit

package/dist/.prettierignore

@@ -0,0 +1,11 @@
+# List files or directories below to ignore them when running prettier
+# More information: https://prettier.io/docs/en/ignore.html
+#
+
+**/staticresources/**
+.localdevserver
+.sfdx
+.sf
+.vscode
+
+coverage/

package/dist/.prettierrc

@@ -0,0 +1,17 @@
+{
+  "trailingComma": "none",
+  "plugins": [
+    "prettier-plugin-apex",
+    "@prettier/plugin-xml"
+  ],
+  "overrides": [
+    {
+      "files": "**/lwc/**/*.html",
+      "options": { "parser": "lwc" }
+    },
+    {
+      "files": "*.{cmp,page,component}",
+      "options": { "parser": "html" }
+    }
+  ]
+}

package/dist/AGENT.md

@@ -0,0 +1,75 @@
+# Agent guide: SFDX project with React web app
+
+This project is a **Salesforce DX (SFDX) project** containing a **React web application**. The structure is generated; the app lives under `force-app/main/default/webapplications/<appName>/`. Use this file when working in this directory.
+
+## Project layout
+
+- **Project root**: this directory — SFDX project root. Contains `sfdx-project.json`, `force-app/`, and (optionally) LWC/Aura.
+- **React web app**: `force-app/main/default/webapplications/<appName>/`  
+  - Replace `<appName>` with the actual app folder name (e.g. `base-react-app`, or the name chosen when the app was generated).
+  - Entry: `src/App.tsx`  
+  - Routes: `src/routes.tsx`  
+  - API/GraphQL: `src/api/` (e.g. `graphql.ts`, `graphql-operations-types.ts`, `utils/`)
+
+Path convention: **webapplications** (lowercase).
+
+## Two package.json contexts
+
+### 1. Project root (this directory)
+
+Used for SFDX metadata (LWC, Aura, etc.). Scripts here are for the base SFDX template:
+
+| Command | Purpose |
+|---------|---------|
+| `npm run lint` | ESLint for `aura/` and `lwc/` |
+| `npm run test` | LWC Jest (passWithNoTests) |
+| `npm run prettier` | Format supported metadata files |
+| `npm run prettier:verify` | Check Prettier |
+
+Root **does not** run the React app. The root `npm run build` is a no-op for the base SFDX project.
+
+### 2. React web app (where you do most work)
+
+**Always `cd` into the web app directory for dev/build/lint/test:**
+
+```bash
+cd force-app/main/default/webapplications/<appName>
+```
+
+| Command | Purpose |
+|---------|---------|
+| `npm run dev` | Start Vite dev server |
+| `npm run build` | TypeScript (`tsc -b`) + Vite build |
+| `npm run lint` | ESLint for the React app |
+| `npm run test` | Vitest |
+| `npm run preview` | Preview production build |
+| `npm run graphql:codegen` | Generate GraphQL types |
+| `npm run graphql:schema` | Fetch GraphQL schema |
+
+**Before finishing changes:** run `npm run build` and `npm run lint` from the web app directory; both must succeed.
+
+## Agent rules (.a4drules)
+
+This project includes **.a4drules/** at the project root. Follow them when generating or editing code.
+
+When rules refer to “web app directory” or `force-app/main/default/webapplications/<appName>/`, use the **actual app folder name** for this project.
+
+## Deploying
+
+From **this project root**:
+
+```bash
+# Build the React app first (replace <appName> with the app folder name)
+cd force-app/main/default/webapplications/<appName> && npm i && npm run build && cd -
+
+# Deploy web app only
+sf project deploy start --source-dir force-app/main/default/webapplications --target-org <alias>
+
+# Deploy all metadata
+sf project deploy start --source-dir force-app --target-org <alias>
+```
+
+## Conventions (quick reference)
+
+- **UI**: shadcn/ui + Tailwind. Import from `@/components/ui/...`.
+- **Entry**: Keep `App.tsx` and routes in `src/`; add features as new routes or sections, don’t replace the app shell but you may modify it to match the requested design.