@salesforce/webapp-template-feature-react-global-search-experimental 1.110.1 → 1.112.0

package/dist/.a4drules/skills/creating-webapp/SKILL.md

@@ -111,7 +111,7 @@ Apps run behind dynamic base paths. Router navigation (`<Link to>`, `navigate()`
 
 ## Module Restrictions
 
-React apps must NOT import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, invoke the **accessing-data** skill.
+React apps must NOT import Salesforce platform modules like `lightning/*` or `@wire` (LWC-only). For data access, invoke the **using-salesforce-data** skill.
 
 # Frontend Aesthetics
 
@@ -138,4 +138,3 @@ 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/.a4drules/skills/deploying-to-salesforce/SKILL.md

@@ -225,5 +225,4 @@ The project includes `scripts/setup-cli.mjs` which runs this sequence in batch.
 
 ## Related Skills
 
-- **exploring-graphql-schema** — Schema exploration (grep-only) after schema exists
-- **using-graphql** — Full GraphQL workflow (explore, query, codegen, lint)
+- **using-salesforce-data** — Full data access workflow (GraphQL queries/mutations, REST APIs, schema exploration, webapp integration)

package/dist/.a4drules/skills/using-salesforce-data/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: using-salesforce-data
+description: Salesforce data access for reads, mutations, and REST APIs. Use when the user wants to fetch, display, create, update, or delete Salesforce records; add data fetching to a component; query Accounts, Contacts, Opportunities, or custom objects; call Chatter, Connect, or Apex REST APIs; or integrate Salesforce data into a webapp.
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.graphql"
+---
+
+# Salesforce Data Access
+
+## When to Use
+
+Use this skill when the user wants to:
+
+- **Fetch or display Salesforce data** — Query records (Account, Contact, Opportunity, custom objects) to show in a component
+- **Create, update, or delete records** — Perform mutations on Salesforce data
+- **Add data fetching to a component** — Wire up a React component to Salesforce data
+- **Call REST APIs** — Use Chatter, Connect, Apex REST, or UI API endpoints
+- **Explore the org schema** — Discover available objects, fields, or relationships
+
+## Data SDK Requirement
+
+> **All Salesforce data access MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK handles authentication, CSRF, and base URL resolution. Never use `fetch()` or `axios` directly.
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+
+const sdk = await createDataSDK();
+
+// GraphQL for record queries/mutations (PREFERRED)
+const response = await sdk.graphql?.<ResponseType>(query, variables);
+
+// REST for Chatter, Connect, Apex REST (when GraphQL insufficient)
+const res = await sdk.fetch?.("/services/data/v65.0/chatter/users/me");
+```
+
+**Always use optional chaining** (`sdk.graphql?.()`, `sdk.fetch?.()`) — these methods may be undefined in some surfaces.
+
+## Decision: GraphQL vs REST
+
+| Need | Method | Example |
+|------|--------|---------|
+| Query/mutate records | `sdk.graphql` | Account, Contact, custom objects |
+| Chatter API | `sdk.fetch` | `/chatter/users/me` |
+| Connect REST | `sdk.fetch` | `/connect/file/upload/config` |
+| Apex REST | `sdk.fetch` | `/services/apexrest/auth/login` |
+| Einstein LLM | `sdk.fetch` | `/einstein/llm/prompt/generations` |
+
+**GraphQL is preferred** for record operations. Use REST only when GraphQL doesn't cover the use case.
+
+---
+
+## GraphQL Workflow
+
+### Step 1: Acquire Schema
+
+The `schema.graphql` file (265K+ lines) is the source of truth. **Use grep only** — never open or parse the file directly.
+
+1. Check if `schema.graphql` exists at the SFDX project root
+2. If missing, run from the **webapp dir**: `npm run graphql:schema`
+3. Custom objects appear only after metadata is deployed
+
+### Step 2: Identify & Introspect Entities
+
+Map user intent to PascalCase names ("accounts" → `Account`). Validate via grep:
+
+```bash
+# From project root — find entity fields
+grep -nE '^type Account implements Record' ./schema.graphql -A 100
+
+# Find filter options
+grep -nE '^input Account_Filter' ./schema.graphql -A 50
+
+# Find mutation input
+grep -nE '^input AccountCreateInput' ./schema.graphql -A 50
+```
+
+**Maximum 3 introspection cycles.** If entities remain unknown, ask the user.
+
+### Step 3: Generate Query
+
+Use the templates below. Every field name **must** be verified via grep.
+
+#### Read Query Template
+
+```graphql
+query GetAccounts {
+  uiapi {
+    query {
+      Account(where: { Industry: { eq: "Technology" } }, first: 10) {
+        edges {
+          node {
+            Id
+            Name @optional { value }
+            Industry @optional { value }
+            # Parent relationship
+            Owner @optional { Name { value } }
+            # Child relationship
+            Contacts @optional {
+              edges { node { Name @optional { value } } }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**FLS Resilience**: Apply `@optional` to all record fields. The server omits inaccessible fields instead of failing. Consuming code must use optional chaining:
+
+```typescript
+const name = node.Name?.value ?? "";
+```
+
+#### Mutation Template
+
+```graphql
+mutation CreateAccount($input: AccountCreateInput!) {
+  uiapi {
+    AccountCreate(input: $input) {
+      Record { Id Name { value } }
+    }
+  }
+}
+```
+
+**Mutation constraints:**
+- Create: Include required fields, only `createable` fields, no child relationships
+- Update: Include `Id`, only `updateable` fields
+- Delete: Include `Id` only
+
+### Step 4: Validate & Test
+
+1. **Lint**: `npx eslint <file>` from webapp dir
+2. **Test**: Ask user before testing. For mutations, request input values — never fabricate data.
+
+```bash
+# From project root
+sf api request rest /services/data/v65.0/graphql \
+  --method POST \
+  --body '{"query":"..."}'
+```
+
+---
+
+## Webapp Integration (React)
+
+### Pattern 1: External .graphql File (Recommended)
+
+```typescript
+import { createDataSDK, type NodeOfConnection } from "@salesforce/sdk-data";
+import GET_ACCOUNTS from "./query/getAccounts.graphql?raw";
+import type { GetAccountsQuery } from "../graphql-operations-types";
+
+const sdk = await createDataSDK();
+const response = await sdk.graphql?.<GetAccountsQuery>(GET_ACCOUNTS);
+
+if (response?.errors?.length) {
+  throw new Error(response.errors.map(e => e.message).join("; "));
+}
+
+const accounts = response?.data?.uiapi?.query?.Account?.edges?.map(e => e.node) ?? [];
+```
+
+After creating/modifying `.graphql` files, run: `npm run graphql:codegen`
+
+### Pattern 2: Inline gql Tag
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+
+const GET_CURRENT_USER = gql`
+  query CurrentUser {
+    uiapi { currentUser { Id Name { value } } }
+  }
+`;
+
+const response = await sdk.graphql?.<CurrentUserQuery>(GET_CURRENT_USER);
+```
+
+**Must use `gql` tag** — plain template strings bypass ESLint validation.
+
+---
+
+## REST API Patterns
+
+Use `sdk.fetch` when GraphQL is insufficient:
+
+```typescript
+declare const __SF_API_VERSION__: string;
+const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
+
+// Chatter — current user
+const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/chatter/users/me`);
+
+// Connect — file upload config
+const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/connect/file/upload/config`);
+
+// Apex REST (no version in path)
+const res = await sdk.fetch?.("/services/apexrest/auth/login", {
+  method: "POST",
+  body: JSON.stringify({ email, password }),
+  headers: { "Content-Type": "application/json" },
+});
+
+// Einstein LLM
+const res = await sdk.fetch?.(`/services/data/v${API_VERSION}/einstein/llm/prompt/generations`, {
+  method: "POST",
+  body: JSON.stringify({ promptTextorId: prompt }),
+});
+```
+
+---
+
+## Directory Structure
+
+```
+<project-root>/                              ← SFDX project root
+├── schema.graphql                           ← grep target (lives here)
+├── sfdx-project.json
+└── force-app/main/default/webapplications/<app-name>/  ← webapp dir
+    ├── package.json                         ← npm scripts
+    ├── codegen.yml
+    └── src/
+        └── api/graphql-operations-types.ts  ← generated types
+```
+
+| Command | Run From | Why |
+|---------|----------|-----|
+| `npm run graphql:schema` | webapp dir | Script in webapp's package.json |
+| `npm run graphql:codegen` | webapp dir | Reads codegen.yml |
+| `npx eslint <file>` | webapp dir | Reads eslint.config.js |
+| `grep ... schema.graphql` | project root | Schema lives at root |
+| `sf api request rest` | project root | Needs sfdx-project.json |
+
+---
+
+## Quick Reference
+
+### Grep Patterns (from project root)
+
+| Pattern | Context | Purpose |
+|---------|---------|---------|
+| `^type <Entity> implements Record` | `-A 100` | Entity fields |
+| `^input <Entity>_Filter` | `-A 50` | Filter options |
+| `^input <Entity>_OrderBy` | `-A 30` | Sort options |
+| `^input <Entity>CreateInput` | `-A 50` | Create mutation input |
+| `^input <Entity>UpdateInput` | `-A 50` | Update mutation input |
+
+### Error Categories
+
+| Error Contains | Resolution |
+|----------------|------------|
+| `invalid syntax` | Fix syntax per error message |
+| `validation error` | Re-grep to verify field name |
+| `VariableTypeMismatch` | Correct argument type from schema |
+| `invalid cross reference id` | Entity deleted — ask for valid Id |
+
+### Checklist
+
+- [ ] All field names verified via grep
+- [ ] `@optional` applied to record fields (reads)
+- [ ] Optional chaining in consuming code
+- [ ] `gql` tag used (not plain strings)
+- [ ] Lint passes: `npx eslint <file>`
+- [ ] Types generated: `npm run graphql:codegen`

package/dist/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.112.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.111.0...v1.112.0) (2026-03-20)
+
+
+### Features
+
+* unify 4 GraphQL skills into single using-graphql skill ([#325](https://github.com/salesforce-experience-platform-emu/webapps/issues/325)) ([3935407](https://github.com/salesforce-experience-platform-emu/webapps/commit/393540779c2da76d7f181f62738aa3d4613a2805))
+
+
+
+
+
+# [1.111.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.110.1...v1.111.0) (2026-03-19)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 ## [1.110.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.110.0...v1.110.1) (2026-03-19)
 
 

package/dist/force-app/main/default/webapplications/feature-react-global-search/package.json

@@ -15,8 +15,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/sdk-data": "^1.110.1",
-    "@salesforce/webapp-experimental": "^1.110.1",
+    "@salesforce/sdk-data": "^1.112.0",
+    "@salesforce/webapp-experimental": "^1.112.0",
     "@tailwindcss/vite": "^4.1.17",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -43,7 +43,7 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/vite-plugin-webapp-experimental": "^1.110.1",
+    "@salesforce/vite-plugin-webapp-experimental": "^1.112.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.110.1",
+  "version": "1.112.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-      "version": "1.110.1",
+      "version": "1.112.0",
       "license": "SEE LICENSE IN LICENSE.txt",
       "devDependencies": {
         "@lwc/eslint-plugin-lwc": "^3.3.0",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.110.1",
+  "version": "1.112.0",
   "description": "Base SFDX project template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "publishConfig": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-feature-react-global-search-experimental",
-  "version": "1.110.1",
+  "version": "1.112.0",
   "description": "Global search feature for Salesforce objects with filtering and pagination",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",

package/dist/.a4drules/skills/accessing-data/SKILL.md

@@ -1,178 +0,0 @@
----
-name: accessing-data
-description: Salesforce data access patterns. Use when adding or modifying any code that fetches data from Salesforce (records, Chatter, Connect API, etc.).
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "**/*.graphql"
----
-
-# Salesforce Data Access
-
-Guidance for accessing Salesforce data from web apps. **All Salesforce data fetches MUST use the Data SDK** (`@salesforce/sdk-data`). The SDK provides authentication, CSRF handling, and correct base URL resolution — direct `fetch` or `axios` calls bypass these and are not allowed.
-
-## Mandatory: Use the Data SDK
-
-> **Every Salesforce data fetch must go through the Data SDK.** Obtain it via `createDataSDK()`, then use `sdk.graphql?.()` or `sdk.fetch?.()`. Never call `fetch()` or `axios` directly for Salesforce endpoints.
-
-## Optional Chaining and Graceful Handling
-
-**Always use optional chaining** when calling `sdk.graphql` or `sdk.fetch` — these methods may be undefined in some surfaces (e.g., Salesforce ACC, MCP Apps). Handle the case where they are not available gracefully:
-
-```typescript
-const sdk = await createDataSDK();
-
-// ✅ Use optional chaining
-const response = await sdk.graphql?.(query);
-
-// ✅ Check before using fetch
-if (!sdk.fetch) {
-  throw new Error("Data SDK fetch is not available in this context");
-}
-const res = await sdk.fetch(url);
-```
-
-For GraphQL, if `sdk.graphql` is undefined, the call returns `undefined` — handle that in your logic (e.g., throw a clear error or return a fallback). For `sdk.fetch`, check availability before calling when the operation is required.
-
-## Preference: GraphQL First
-
-**GraphQL is the preferred method** for querying and mutating Salesforce records. Use it when:
-
-- Querying records (Account, Contact, Opportunity, custom objects)
-- Creating, updating, or deleting records (when GraphQL supports the operation)
-- Fetching related data, filters, sorting, pagination
-
-**Use `sdk.fetch` only when GraphQL is not sufficient.** For REST API usage, invoke the `fetching-rest-api` skill, which documents:
-
-- Chatter API (e.g., `/services/data/v65.0/chatter/users/me`)
-- Connect REST API (e.g., `/services/data/v65.0/connect/file/upload/config`)
-- Apex REST (e.g., `/services/apexrest/auth/login`)
-- UI API REST (e.g., `/services/data/v65.0/ui-api/records/{recordId}`)
-- Einstein LLM Gateway
-
----
-
-## Getting the SDK
-
-```typescript
-import { createDataSDK } from "@salesforce/sdk-data";
-
-const sdk = await createDataSDK();
-```
-
----
-
-## Example 1: GraphQL (Preferred)
-
-For record queries and mutations, use GraphQL via the Data SDK. Invoke the `using-graphql` skill for the full workflow (schema exploration, query authoring, codegen, lint validate).
-
-```typescript
-import { createDataSDK, gql } from "@salesforce/sdk-data";
-import type { GetAccountsQuery } from "../graphql-operations-types";
-
-const GET_ACCOUNTS = gql`
-  query GetAccounts {
-    uiapi {
-      query {
-        Account(first: 10) {
-          edges {
-            node {
-              Id
-              Name { value }
-            }
-          }
-        }
-      }
-    }
-  }
-`;
-
-export async function getAccounts() {
-  const sdk = await createDataSDK();
-  const response = await sdk.graphql?.<GetAccountsQuery>(GET_ACCOUNTS);
-
-  if (response?.errors?.length) {
-    throw new Error(response.errors.map((e) => e.message).join("; "));
-  }
-
-  return response?.data?.uiapi?.query?.Account?.edges?.map((e) => e?.node) ?? [];
-}
-```
-
----
-
-## Example 2: Fetch (When GraphQL Is Not Sufficient)
-
-For REST endpoints that have no GraphQL equivalent, use `sdk.fetch`. **Invoke the `fetching-rest-api` skill** for full documentation of Chatter, Connect REST, Apex REST, UI API REST, and Einstein LLM endpoints.
-
-```typescript
-import { createDataSDK } from "@salesforce/sdk-data";
-
-declare const __SF_API_VERSION__: string;
-const API_VERSION = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
-
-export async function getCurrentUser() {
-  const sdk = await createDataSDK();
-  const response = await sdk.fetch?.(`/services/data/v${API_VERSION}/chatter/users/me`);
-
-  if (!response?.ok) throw new Error(`HTTP ${response?.status}`);
-  const data = await response.json();
-  return { id: data.id, name: data.name };
-}
-```
-
----
-
-## Anti-Patterns (Forbidden)
-
-### Direct fetch to Salesforce
-
-```typescript
-// ❌ FORBIDDEN — bypasses Data SDK auth and CSRF
-const res = await fetch("/services/data/v65.0/chatter/users/me");
-```
-
-### Direct axios to Salesforce
-
-```typescript
-// ❌ FORBIDDEN — bypasses Data SDK
-const res = await axios.get("/services/data/v65.0/chatter/users/me");
-```
-
-### Correct approach
-
-```typescript
-// ✅ CORRECT — use Data SDK
-const sdk = await createDataSDK();
-const res = await sdk.fetch?.("/services/data/v65.0/chatter/users/me");
-```
-
----
-
-## Clarifying Vague Data Requests
-
-When a user asks about data and the request is vague, **clarify before implementing**. Ask which of the following they want:
-
-- **Application code** — Add or modify code in a specific web app so the app performs the data interaction at runtime (e.g., GraphQL query in the React app)
-- **Local SF CLI** — Run Salesforce CLI commands locally (e.g., `sf data query`, `sf data import tree`) to interact with the org from the terminal
-- **Local example data** — Update or add local fixture/example data files (e.g., JSON in `data/`) for development or testing
-- **Other** — Data export, report generation, setup script, etc.
-
-Do not assume. A request like "fetch accounts" could mean: (1) add a GraphQL query to the app, (2) run `sf data query` in the terminal, or (3) update sample data files. Confirm the intent before proceeding.
-
----
-
-## Decision Flow
-
-1. **Need to query or mutate Salesforce records?** → Use GraphQL via the Data SDK. Invoke the `using-graphql` skill.
-2. **Need Chatter, Connect REST, Apex REST, UI API REST, or Einstein LLM?** → Use `sdk.fetch`. Invoke the `fetching-rest-api` skill.
-3. **Never** use `fetch`, `axios`, or similar directly for Salesforce API calls.
-
----
-
-## Reference
-
-- GraphQL workflow: invoke the `using-graphql` skill (`.a4drules/skills/using-graphql/`)
-- REST API via fetch: invoke the `fetching-rest-api` skill (`.a4drules/skills/fetching-rest-api/`)
-- Data SDK package: `@salesforce/sdk-data` (`createDataSDK`, `gql`, `NodeOfConnection`)
-- `createRecord` for UI API record creation: `@salesforce/webapp-experimental/api` (uses Data SDK internally)