@schandlergarcia/sf-web-components 1.0.0

package/.a4drules/skills/implementing-file-upload/SKILL.md

@@ -0,0 +1,396 @@
+---
+name: implementing-file-upload
+description: Add file upload functionality to React webapps with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR.
+---
+
+# File Upload API (workflow)
+
+When the user wants file upload functionality in a React webapp, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
+
+## CRITICAL: This is an API-only package
+
+The package exports **programmatic APIs**, not React components or hooks. You will:
+
+- Use the `upload()` function to handle file uploads with progress tracking
+- Build your own custom UI (file input, dropzone, progress bars, etc.)
+- Track upload progress through the `onProgress` callback
+
+**Do NOT:**
+
+- Expect pre-built components like `<FileUpload />` — they are not exported
+- Try to import React hooks like `useFileUpload` — they are not exported
+- Look for dropzone components — they are not exported
+
+The source code contains reference components for demonstration, but they are **not available** as imports. Use them as examples to build your own UI.
+
+## 1. Install the package
+
+```bash
+npm install @salesforce/webapp-template-feature-react-file-upload-experimental
+```
+
+Dependencies are automatically installed:
+
+- `@salesforce/webapp-experimental` (API client)
+- `@salesforce/sdk-data` (data SDK)
+
+## 2. Understand the three upload patterns
+
+### Pattern A: Basic upload (no record linking)
+
+Upload files to Salesforce and get back `contentBodyId` for each file. No ContentVersion record is created.
+
+**When to use:**
+
+- User wants to upload files first, then create/link them to a record later
+- Building a multi-step form where the record doesn't exist yet
+- Deferred record linking scenarios
+
+```tsx
+import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+const results = await upload({
+  files: [file1, file2],
+  onProgress: (progress) => {
+    console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
+  },
+});
+
+// results[0].contentBodyId: "069..." (always available)
+// results[0].contentVersionId: undefined (no record linked)
+```
+
+### Pattern B: Upload with immediate record linking
+
+Upload files and immediately link them to an existing Salesforce record by creating ContentVersion records.
+
+**When to use:**
+
+- Record already exists (Account, Opportunity, Case, etc.)
+- User wants files immediately attached to the record
+- Direct upload-and-attach scenarios
+
+```tsx
+import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+const results = await upload({
+  files: [file1, file2],
+  recordId: "001xx000000yyyy", // Existing record ID
+  onProgress: (progress) => {
+    console.log(`${progress.fileName}: ${progress.status} - ${progress.progress}%`);
+  },
+});
+
+// results[0].contentBodyId: "069..." (always available)
+// results[0].contentVersionId: "068..." (linked to record)
+```
+
+### Pattern C: Deferred record linking (record creation flow)
+
+Upload files without a record, then link them after the record is created.
+
+**When to use:**
+
+- Building a "create record with attachments" form
+- Record doesn't exist until form submission
+- Need to upload files before knowing the final record ID
+
+```tsx
+import {
+  upload,
+  createContentVersion,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+// Step 1: Upload files (no recordId)
+const uploadResults = await upload({
+  files: [file1, file2],
+  onProgress: (progress) => console.log(progress),
+});
+
+// Step 2: Create the record
+const newRecordId = await createRecord(formData);
+
+// Step 3: Link uploaded files to the new record
+for (const file of uploadResults) {
+  const contentVersionId = await createContentVersion(
+    new File([""], file.fileName),
+    file.contentBodyId,
+    newRecordId,
+  );
+}
+```
+
+## 3. Build your custom UI
+
+The package provides the backend — you build the frontend. Here's a minimal example:
+
+```tsx
+import {
+  upload,
+  type FileUploadProgress,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+import { useState } from "react";
+
+function CustomFileUpload({ recordId }: { recordId?: string }) {
+  const [progress, setProgress] = useState<Map<string, FileUploadProgress>>(new Map());
+
+  const handleFileSelect = async (event: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(event.target.files || []);
+
+    await upload({
+      files,
+      recordId,
+      onProgress: (fileProgress) => {
+        setProgress((prev) => new Map(prev).set(fileProgress.fileName, fileProgress));
+      },
+    });
+  };
+
+  return (
+    <div>
+      <input type="file" multiple onChange={handleFileSelect} />
+
+      {Array.from(progress.entries()).map(([fileName, fileProgress]) => (
+        <div key={fileName}>
+          {fileName}: {fileProgress.status} - {fileProgress.progress}%
+          {fileProgress.error && <span>Error: {fileProgress.error}</span>}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## 4. Track upload progress
+
+The `onProgress` callback fires multiple times for each file as it moves through stages:
+
+| Status         | When                                           | Progress Value       |
+| -------------- | ---------------------------------------------- | -------------------- |
+| `"pending"`    | File queued for upload                         | `0`                  |
+| `"uploading"`  | Upload in progress (XHR)                       | `0-100` (percentage) |
+| `"processing"` | Creating ContentVersion (if recordId provided) | `0`                  |
+| `"success"`    | Upload complete                                | `100`                |
+| `"error"`      | Upload failed                                  | `0`                  |
+
+**Always provide visual feedback:**
+
+- Show file name
+- Display current status
+- Render progress bar for "uploading" status
+- Show error message if status is "error"
+
+## 5. Cancel uploads (optional)
+
+Use an `AbortController` to allow users to cancel uploads:
+
+```tsx
+const abortController = new AbortController();
+
+const handleUpload = async (files: File[]) => {
+  try {
+    await upload({
+      files,
+      signal: abortController.signal,
+      onProgress: (progress) => console.log(progress),
+    });
+  } catch (error) {
+    console.error("Upload cancelled or failed:", error);
+  }
+};
+
+const cancelUpload = () => {
+  abortController.abort();
+};
+```
+
+## 6. Link to current user (special case)
+
+If the user wants to upload files to their own profile or personal library:
+
+```tsx
+import {
+  upload,
+  getCurrentUserId,
+} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+
+const userId = await getCurrentUserId();
+await upload({ files, recordId: userId });
+```
+
+## API Reference
+
+### upload(options)
+
+Main upload API that handles complete flow with progress tracking.
+
+```typescript
+interface UploadOptions {
+  files: File[];
+  recordId?: string | null; // If provided, creates ContentVersion
+  onProgress?: (progress: FileUploadProgress) => void;
+  signal?: AbortSignal; // Optional cancellation
+}
+
+interface FileUploadProgress {
+  fileName: string;
+  status: "pending" | "uploading" | "processing" | "success" | "error";
+  progress: number; // 0-100 for uploading, 0 for other states
+  error?: string;
+}
+
+interface FileUploadResult {
+  fileName: string;
+  size: number;
+  contentBodyId: string; // Always available
+  contentVersionId?: string; // Only if recordId was provided
+}
+```
+
+**Returns:** `Promise<FileUploadResult[]>`
+
+### createContentVersion(file, contentBodyId, recordId)
+
+Manually create a ContentVersion record from a previously uploaded file.
+
+```typescript
+async function createContentVersion(
+  file: File,
+  contentBodyId: string,
+  recordId: string,
+): Promise<string | undefined>;
+```
+
+**Parameters:**
+
+- `file` — File object (used for metadata like name)
+- `contentBodyId` — ContentBody ID from previous upload
+- `recordId` — Record ID for FirstPublishLocationId
+
+**Returns:** ContentVersion ID if successful
+
+### getCurrentUserId()
+
+Get the current user's Salesforce ID.
+
+```typescript
+async function getCurrentUserId(): Promise<string>;
+```
+
+**Returns:** Current user ID
+
+## Common UI patterns
+
+### File input with button
+
+```tsx
+<input type="file" multiple accept=".pdf,.doc,.docx,.jpg,.png" onChange={handleFileSelect} />
+```
+
+### Drag-and-drop zone
+
+Build your own dropzone using native events:
+
+```tsx
+function DropZone({ onDrop }: { onDrop: (files: File[]) => void }) {
+  const handleDrop = (e: React.DragEvent) => {
+    e.preventDefault();
+    const files = Array.from(e.dataTransfer.files);
+    onDrop(files);
+  };
+
+  return (
+    <div
+      onDrop={handleDrop}
+      onDragOver={(e) => e.preventDefault()}
+      style={{ border: "2px dashed #ccc", padding: "2rem" }}
+    >
+      Drop files here
+    </div>
+  );
+}
+```
+
+### Progress bar
+
+```tsx
+{
+  progress.status === "uploading" && (
+    <div style={{ width: "100%", background: "#eee" }}>
+      <div
+        style={{
+          width: `${progress.progress}%`,
+          background: "#0176d3",
+          height: "8px",
+        }}
+      />
+    </div>
+  );
+}
+```
+
+## Decision tree for agents
+
+**User asks for file upload functionality:**
+
+1. **Ask about record context:**
+   - "Do you want to link uploaded files to a specific record, or upload them first and link later?"
+
+2. **Based on response:**
+   - **Link to existing record** → Use Pattern B with `recordId`
+   - **Upload first, link later** → Use Pattern A (no recordId), then Pattern C for linking
+   - **Link to current user** → Use Pattern B with `getCurrentUserId()`
+
+3. **Build the UI:**
+   - Create file input or dropzone (not provided by package)
+   - Add progress display for each file (status + progress bar)
+   - Handle errors in the UI
+
+4. **Test the implementation:**
+   - Verify progress callbacks fire correctly
+   - Check that `contentBodyId` is returned
+   - If `recordId` was provided, verify `contentVersionId` is returned
+
+## Reference implementation
+
+The package includes a reference implementation in `src/features/fileupload/` with:
+
+- `FileUpload.tsx` — Complete component with dropzone and dialog
+- `FileUploadDialog.tsx` — Progress tracking dialog
+- `FileUploadDropZone.tsx` — Drag-and-drop zone
+- `useFileUpload.ts` — React hook for state management
+
+**These are NOT exported** but can be viewed as examples. Read the source files to understand patterns for building your own UI.
+
+## Troubleshooting
+
+**Upload fails with CORS error:**
+
+- Ensure the webapp is properly deployed to Salesforce or running on `localhost`
+- Check that the org allows the origin in CORS settings
+
+**No progress updates:**
+
+- Verify `onProgress` callback is provided
+- Check that the callback function updates React state correctly
+
+**ContentVersion not created:**
+
+- Verify `recordId` is provided to `upload()` function
+- Check that the record ID is valid and exists in the org
+- Ensure user has permissions to create ContentVersion records
+
+**Files upload but don't appear in record:**
+
+- Verify `recordId` is correct
+- Check that ContentVersion was created (look for `contentVersionId` in results)
+- Confirm user has access to view files on the record
+
+## DO NOT do these things
+
+- ❌ Build XHR/fetch upload logic from scratch — use the `upload()` API
+- ❌ Try to import `<FileUpload />` component — it's not exported
+- ❌ Try to import `useFileUpload` hook — it's not exported
+- ❌ Use third-party file upload libraries when this feature exists
+- ❌ Skip progress tracking — always provide user feedback
+- ❌ Ignore errors — always handle and display error messages

package/.a4drules/skills/installing-webapp-features/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: installing-webapp-features
+description: Search, describe, and install pre-built UI features (authentication, shadcn components, navigation, search, GraphQL, Agentforce AI) into Salesforce webapps. Use this when the user wants to add functionality to a webapp, or when determining what salesforce-provided features are available — whether prompted by the user or on your own initiative. Always check for an existing feature before building from scratch.
+---
+
+# webapps-features-experimental CLI — Agent Reference
+
+**Always check for an existing feature before building something yourself.** This CLI installs pre-built, tested feature packages into Salesforce webapps. Features range from foundational UI component libraries (shadcn/ui with Button, Card, Input, Table, etc.) to full-stack application capabilities like authentication (login, registration, password flows, session management, and Apex backend classes), global search, navigation menus, GraphQL integrations, and Agentforce AI conversation UIs. Each feature ships as a complete implementation — including React components, context providers, route guards, and any required Salesforce server-side code — that already handles platform-specific concerns like Salesforce API integration, session management, and SFDX metadata structure. Building these from scratch is error-prone and unnecessary when a feature exists. **If no existing feature is found, ask the user before proceeding with a custom implementation — a relevant feature may exist under a different name or keyword.**
+
+```
+npx @salesforce/webapps-features-experimental <command> [options]
+```
+
+## Workflow: Search Project → Search Features → Describe → Install
+
+**MANDATORY**: When the user asks to add ANY webapp functionality, follow this entire workflow. Do not skip steps.
+
+### 1. Search existing project code
+
+Before installing anything, check whether the functionality already exists in the **project source code** (not dependencies).
+
+- **Always scope searches to `src/`** to avoid matching files in `node_modules/`, `dist/`, or `build/` output
+- Use Glob with a scoped path: e.g., `src/**/Button.tsx`, `src/**/*auth*.tsx`
+- Use Grep with the `path` parameter set to the `src/` directory, or use `glob: "*.{ts,tsx}"` to restrict file types
+- Check common directories: `src/components/`, `src/lib/`, `src/pages/`, `src/hooks/`
+- **Never** search from the project root without a path or glob filter — this will crawl `node_modules` and produce massive, unhelpful output
+
+**If existing code is found** — read the files, present them to the user, and ask if they want to reuse or extend what's there. If yes, use the existing code and stop. If no, proceed to step 2.
+
+**If nothing is found** — proceed to step 2.
+
+### 2. Search available features
+
+```bash
+npx @salesforce/webapps-features-experimental list [options]
+```
+
+Options:
+
+- `-v, --verbose` — Show full descriptions, packages, and dependencies
+- `--search <query>` — Filter features by keyword (ranked by relevance)
+
+```bash
+npx @salesforce/webapps-features-experimental list
+npx @salesforce/webapps-features-experimental list --search "auth"
+npx @salesforce/webapps-features-experimental list --search "button"
+```
+
+**If no matching feature is found** — ask the user before proceeding with a custom implementation. A relevant feature may exist under a different name or keyword.
+
+### 3. Describe a feature
+
+```bash
+npx @salesforce/webapps-features-experimental describe <feature>
+```
+
+Shows description, package name, dependencies, components, copy operations, and example files.
+
+```bash
+npx @salesforce/webapps-features-experimental describe authentication
+npx @salesforce/webapps-features-experimental describe shadcn
+```
+
+### 4. Install a feature
+
+```bash
+npx @salesforce/webapps-features-experimental install <feature> --webapp-dir <path> [options]
+```
+
+Resolves the feature name to an npm package, installs it and its dependencies (including transitive feature dependencies like `shadcn`), copies source files into your project, and reports any `__example__` files that require manual integration.
+
+Options:
+
+- `--webapp-dir <name>` (required) — Webapp name, resolves to `<sfdx-source>/webapplications/<name>`
+- `--sfdx-source <path>` (default: `force-app/main/default`) — SFDX source directory
+- `--dry-run` (default: `false`) — Preview changes without writing files
+- `-v, --verbose` (default: `false`) — Enable verbose logging
+- `-y, --yes` (default: `false`) — Skip all prompts (auto-skip conflicts)
+- `--on-conflict <mode>` (default: `prompt`) — `prompt`, `error`, `skip`, or `overwrite`
+- `--conflict-resolution <file>` — Path to JSON file with per-file resolutions
+
+```bash
+# Install authentication (also installs shadcn dependency)
+npx @salesforce/webapps-features-experimental install authentication \
+  --webapp-dir mywebapp
+
+# Dry run to preview changes
+npx @salesforce/webapps-features-experimental install shadcn \
+  --webapp-dir mywebapp \
+  --dry-run
+
+# Non-interactive install (skip all file conflicts)
+npx @salesforce/webapps-features-experimental install authentication \
+  --webapp-dir mywebapp \
+  --yes
+```
+
+## Conflict Handling
+
+Since you are running in a non-interactive environment, you cannot use `--on-conflict prompt` directly. When conflicts are likely (e.g. installing into an existing project), you have two options:
+
+**Option A — Let the user resolve conflicts interactively.** Suggest the user run the install command themselves with `--on-conflict prompt` so they can decide per-file.
+
+**Option B — Two-pass automated resolution:**
+
+```bash
+# Pass 1: detect conflicts
+npx @salesforce/webapps-features-experimental install authentication \
+  --webapp-dir mywebapp \
+  --on-conflict error
+
+# The CLI will exit with an error listing every conflicting file path.
+
+# Pass 2: create a resolution file and re-run
+echo '{ "src/styles/global.css": "overwrite", "src/lib/utils.ts": "skip" }' > resolutions.json
+
+npx @salesforce/webapps-features-experimental install authentication \
+  --webapp-dir mywebapp \
+  --conflict-resolution resolutions.json
+```
+
+Resolution values per file: `"skip"` (keep existing) or `"overwrite"` (replace). When unsure how to resolve a conflict, ask the user rather than guessing.
+
+## Hint Placeholders in Copy Paths
+
+Some copy operations use **hint placeholders** in the `"to"` path — descriptive segments like `<desired-page-with-search-input>` that are NOT resolved by the CLI. These are guidance for the user or LLM to choose an appropriate destination.
+
+**How they work:** The file is copied with the literal placeholder name (e.g., `src/pages/<desired-page-with-search-input>.tsx`). After installation, you should:
+
+1. Read the copied file to understand its purpose
+2. Rename or relocate it to the intended target (e.g., `src/pages/Home.tsx`)
+3. Or integrate its patterns into an existing file, then delete it
+
+**How to identify them:** Hint placeholders use `<descriptive-name>` syntax but are NOT one of the system placeholders (`<sfdxSource>`, `<webappDir>`, `<webapp>`). They always appear in the middle or end of a path, never as the leading segment.
+
+**Example from features.json:**
+
+```json
+{
+  "to": "<webappDir>/src/pages/<desired-page-with-search-input>.tsx",
+  "description": "Example home page showing GlobalSearchInput integration",
+  "integrationTarget": "src/pages/Home.tsx"
+}
+```
+
+The `integrationTarget` field tells you the suggested destination. Use your judgment — if the user already has a different page where search should go, integrate there instead.
+
+**When `integrationTarget` itself is a placeholder:** Some features use a hint placeholder in the `integrationTarget` value (e.g., `"integrationTarget": "src/<path-to-desired-page-with-search-input>.tsx"`). This means there is no single default target — the user must decide which existing file to integrate into. When you encounter this:
+
+1. Ask the user which page or file they want to integrate the feature into
+2. Read the `__example__` file to understand the integration pattern
+3. Read the user's chosen target file
+4. Apply the pattern from the example into the target file
+
+## Post Installation: Integrating **example** Files
+
+Features may include `__example__` files (e.g., `__example__auth-app.tsx`) showing integration patterns.
+
+**The describe command shows**:
+
+- Which **example** files will be copied
+- Target file to integrate into (e.g., `src/app.tsx`)
+- What the example demonstrates
+
+### How to Integrate Example Files (CRITICAL FOR LLMs)
+
+⚠️ **ONLY USE Read AND Edit TOOLS - NO BASH COMMANDS** ⚠️
+
+**DO NOT DO THIS**:
+
+- ❌ `git status` or any git commands
+- ❌ `ls`, `cat`, `sed`, `awk`, or ANY bash file commands
+- ❌ Chaining bash commands to read multiple files
+- ❌ Using bash to check directories or file existence
+
+**DO THIS INSTEAD**:
+
+- ✅ Use Read tool with `file_path` parameter to read each file
+- ✅ Use Edit tool with `file_path`, `old_string`, `new_string` to modify files
+- ✅ That's it! Just Read and Edit tools.
+
+**Integration steps**:
+
+1. **Read each example file** (use Read tool)
+   - Example: Read tool with `file_path: "force-app/main/default/webapplications/mywebapp/src/__example__auth-app.tsx"`
+   - Note the imports and patterns to integrate
+
+2. **Read each target file** (use Read tool)
+   - Example: Read tool with `file_path: "force-app/main/default/webapplications/mywebapp/src/app.tsx"`
+   - Understand where the new code should go
+
+3. **Edit each target file** (use Edit tool)
+   - Add imports from the example
+   - Add or modify code following the example's patterns
+   - Preserve existing functionality
+
+4. **Delete the example file after successful integration** (use Bash tool)
+   - Example: `rm force-app/main/default/webapplications/mywebapp/src/__example__authentication-routes.tsx`
+   - Only delete after you have successfully integrated the pattern
+   - This keeps the codebase clean and removes temporary example files
+
+## Troubleshooting
+
+**Directory not found**: Check paths are correct, use absolute or correct relative paths
+
+**Feature not found**: Use `npx @salesforce/webapps-features-experimental list` to see available feature names
+
+**Conflicts in error mode**: Follow CLI instructions to create resolution file
+
+**Need help?**: Run `npx @salesforce/webapps-features-experimental --help` to see all commands and options