@salesforce/webapp-template-feature-react-global-search-experimental 1.3.3

package/dist/.a4drules/code-quality.md

@@ -0,0 +1,150 @@
+# AI Rule: Code Quality Standards
+
+Enforces ESLint, Prettier, and coding best practices for consistent, maintainable code.
+
+## Targets
+- `force-app/main/default/webapplications/*/**/*`
+- `**/*.{js,ts,jsx,tsx,json,md}`
+
+## MANDATORY Checks
+
+**Before writing code:**
+```bash
+npm run lint         # MUST result in: 0 problems (0 errors, 0 warnings)
+npm run format:check # MUST result in: All matched files use Prettier code style!
+```
+
+## Prettier Config (.prettierrc)
+```json
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "bracketSpacing": true,
+  "arrowParens": "avoid",
+  "endOfLine": "lf"
+}
+```
+
+## Auto-Fix Commands
+```bash
+npm run fix-all      # Fix formatting + linting (recommended)
+npm run format       # Fix Prettier issues
+npm run lint:fix     # Fix ESLint issues
+```
+
+## Import Order (MANDATORY)
+```typescript
+// 1. React ecosystem
+import { useState, useEffect } from 'react';
+
+// 2. External libraries (alphabetical)
+import axios from 'axios';
+import clsx from 'clsx';
+
+// 3. UI components (alphabetical)
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+
+// 4. Internal utilities (alphabetical)
+import { useAuth } from '../hooks/useAuth';
+import { formatDate } from '../utils/dateUtils';
+
+// 5. Relative imports
+import { ComponentA } from './ComponentA';
+
+// 6. Type imports (separate, at end)
+import type { User, ApiResponse } from '../types';
+```
+
+## Naming Conventions
+```typescript
+// PascalCase: Components, classes
+const UserProfile = () => {};
+const ApiClient = class {};
+
+// camelCase: Variables, functions, properties
+const userName = 'john';
+const fetchUserData = async () => {};
+
+// SCREAMING_SNAKE_CASE: Constants
+const API_BASE_URL = 'https://api.example.com';
+
+// kebab-case: Files
+// user-profile.tsx, api-client.ts
+```
+
+## React Component Structure
+```typescript
+interface ComponentProps {
+  // Props interface first
+}
+
+const Component: React.FC<ComponentProps> = ({ prop1, prop2 }) => {
+  // 1. Hooks
+  // 2. Computed values
+  // 3. Event handlers
+  // 4. JSX return
+
+  return <div />;
+};
+
+export default Component;
+```
+
+## JSX Standards
+```typescript
+// Self-closing tags
+<Button onClick={handleClick} />
+
+// Conditional rendering
+{isLoading && <Spinner />}
+{error ? <ErrorMessage error={error} /> : <Content />}
+
+// Lists with keys
+{items.map(item => <Item key={item.id} data={item} />)}
+```
+
+## Error Handling
+```typescript
+// Async functions with try-catch
+const fetchData = async (id: string): Promise<Data> => {
+  try {
+    const response = await api.get(`/data/${id}`);
+    return response.data;
+  } catch (error) {
+    console.error('Failed to fetch data:', error);
+    throw error;
+  }
+};
+```
+
+## Anti-Patterns (FORBIDDEN)
+```typescript
+// NEVER disable ESLint without justification
+// eslint-disable-next-line
+
+// NEVER mutate state directly
+state.items.push(newItem); // Wrong
+setItems(prev => [...prev, newItem]); // Correct
+
+// NEVER use magic numbers/strings
+setTimeout(() => {}, 5000); // Wrong
+const DEBOUNCE_DELAY = 5000; // Correct
+```
+
+## Quality Workflow
+
+**Before Committing:**
+1. `npm run check-all` - All checks must pass
+2. `npm run fix-all` - Auto-fix issues if needed
+3. `npm run build` - Build must succeed
+
+## Zero Tolerance Policy
+- ESLint errors: MUST be 0
+- ESLint warnings: MUST be 0
+- Prettier violations: MUST be 0
+- TypeScript errors: MUST be 0

package/dist/.a4drules/graphql/tools/knowledge/lds-explore-graphql-schema.md

@@ -0,0 +1,227 @@
+# GraphQL Schema Reference
+
+This document provides guidance for AI agents working with the Salesforce GraphQL API schema in this project.
+
+## Schema File Location
+
+**The complete GraphQL schema is located at: `@schema.graphql`** (in the project root)
+
+> ⚠️ **Important**: The schema file is very large (~265,000+ lines). Do NOT read it entirely. Instead, use targeted searches to find specific types, fields, or operations.
+
+If the file is not present, generate it by running:
+```bash
+npm run graphql:get-schema
+```
+
+## Required Pre-Flight Check
+
+**BEFORE generating any GraphQL query, you MUST:**
+
+1. **Check if schema exists**: Look for `schema.graphql` in the project root
+2. **If schema is missing**: 
+   - Run `npm run graphql:get-schema` to download it
+   - Wait for the command to complete successfully
+   - Then proceed with schema exploration
+3. **If schema exists**: Proceed with targeted searches as described below
+
+> ⚠️ **DO NOT** generate GraphQL queries without first having access to the schema. Standard field assumptions may not match the target org's configuration.
+
+## Schema Structure Overview
+
+The schema follows the Salesforce GraphQL Wire Adapter pattern with these main entry points:
+
+### Query Entry Point
+```graphql
+type Query {
+  uiapi: UIAPI!
+}
+```
+
+### UIAPI Structure
+```graphql
+type UIAPI {
+  query: RecordQuery!           # For querying records
+  aggregate: RecordQueryAggregate!  # For aggregate queries
+  objectInfos: [ObjectInfo]     # For metadata
+  relatedListByName: RelatedListInfo
+}
+```
+
+### Mutation Entry Point
+```graphql
+type Mutation {
+  uiapi(input: UIAPIMutationsInput): UIAPIMutations!
+}
+```
+
+## How to Explore the Schema
+
+When you need to build a GraphQL query, use these search patterns:
+
+### 1. Find Available Fields for a Record Type
+Search for `type <ObjectName> implements Record` to find all queryable fields:
+```bash
+# Example: Find Account fields
+grep "^type Account implements Record" schema.graphql -A 50
+```
+
+### 2. Find Filter Options for a Record Type
+Search for `input <ObjectName>_Filter` to find filterable fields and operators:
+```bash
+# Example: Find Account filter options
+grep "^input Account_Filter" schema.graphql -A 30
+```
+
+### 3. Find OrderBy Options
+Search for `input <ObjectName>_OrderBy` for sorting options:
+```bash
+# Example: Find Account ordering options
+grep "^input Account_OrderBy" schema.graphql -A 20
+```
+
+### 4. Find Mutation Operations
+Search for operations in `UIAPIMutations`:
+```bash
+# Example: Find Account mutations
+grep "Account.*Create\|Account.*Update\|Account.*Delete" schema.graphql
+```
+
+### 5. Find Input Types for Mutations
+Search for `input <ObjectName>CreateInput` or `input <ObjectName>UpdateInput`:
+```bash
+# Example: Find Account create input
+grep "^input AccountCreateInput" schema.graphql -A 30
+```
+
+## Common Operator Types
+
+### StringOperators (for text fields)
+```graphql
+input StringOperators {
+  eq: String      # equals
+  ne: String      # not equals
+  like: String    # pattern matching (use % as wildcard)
+  lt: String      # less than
+  gt: String      # greater than
+  lte: String     # less than or equal
+  gte: String     # greater than or equal
+  in: [String]    # in list
+  nin: [String]   # not in list
+}
+```
+
+### OrderByClause
+```graphql
+input OrderByClause {
+  order: ResultOrder   # ASC or DESC
+  nulls: NullOrder     # FIRST or LAST
+}
+```
+
+## Query Pattern Examples
+
+### Basic Query Structure
+All record queries follow this pattern:
+```graphql
+query {
+  uiapi {
+    query {
+      <ObjectName>(
+        first: Int           # pagination limit
+        after: String        # pagination cursor
+        where: <Object>_Filter
+        orderBy: <Object>_OrderBy
+      ) {
+        edges {
+          node {
+            Id
+            <Field> { value }
+            # ... more fields
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Example: Query Accounts with Filter
+```graphql
+query GetHighRevenueAccounts($minRevenue: Currency) {
+  uiapi {
+    query {
+      Account(
+        where: { AnnualRevenue: { gt: $minRevenue } }
+        orderBy: { AnnualRevenue: { order: DESC } }
+        first: 50
+      ) {
+        edges {
+          node {
+            Id
+            Name { value }
+            AnnualRevenue { value }
+            Industry { value }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Mutation Pattern
+```graphql
+mutation CreateAccount($input: AccountCreateInput!) {
+  uiapi(input: { AccountCreate: { input: $input } }) {
+    AccountCreate {
+      Record {
+        Id
+        Name { value }
+      }
+    }
+  }
+}
+```
+
+## Field Value Wrappers
+
+Salesforce GraphQL returns field values wrapped in typed objects:
+
+| Wrapper Type | Access Pattern |
+|-------------|----------------|
+| `StringValue` | `FieldName { value }` |
+| `IntValue` | `FieldName { value }` |
+| `BooleanValue` | `FieldName { value }` |
+| `DateTimeValue` | `FieldName { value displayValue }` |
+| `PicklistValue` | `FieldName { value displayValue }` |
+| `CurrencyValue` | `FieldName { value displayValue }` |
+
+## Agent Workflow for Building Queries
+
+**Pre-requisites (MANDATORY):**
+- [ ] Verified `schema.graphql` exists in project root
+- [ ] If missing, ran `npm run graphql:get-schema` and waited for completion
+- [ ] Confirmed connection to correct Salesforce org (if downloading fresh schema)
+
+**Workflow Steps:**
+
+1. **Identify the target object** (e.g., Account, Contact, Opportunity)
+2. **Search the schema** for the object type to discover available fields
+3. **Search for filter input** (`<Object>_Filter`) to understand filtering options
+4. **Search for orderBy input** (`<Object>_OrderBy`) for sorting capabilities
+5. **Build the query** following the patterns above
+6. **Validate field names** match exactly as defined in the schema (case-sensitive)
+
+## Tips for Agents
+
+- **Always verify field names** by searching the schema before generating queries
+- **Use grep/search** to explore the schema efficiently—never read the entire file
+- **Check relationships** by looking for `parentRelationship` and `childRelationship` comments in type definitions
+- **Look for Connection types** (e.g., `AccountConnection`) to understand pagination structure
+- **Custom objects** end with `__c` (e.g., `CustomObject__c`)
+- **Custom fields** also end with `__c` (e.g., `Custom_Field__c`)
+
+## Related Documentation
+
+- For generating mutations and queries, see `lds-generate-graphql-mutationquery.md`
+- For GraphQL best practices, see `lds-guide-graphql.md`

package/dist/.a4drules/graphql/tools/knowledge/lds-generate-graphql-mutationquery.md

@@ -0,0 +1,211 @@
+# GraphQL Mutation Query Generation
+
+**Triggering conditions**
+1. Only if the `LDS_Guide_GraphQL` rule completed successfully
+2. Only if the query to generate is a mutation query
+
+## Your Role
+
+You are a GraphQL expert and your role is to help generate Salesforce compatible GraphQL mutation queries once the exploration phase has completed.
+
+You will leverage the context provided by the requesting user as well as the validation phase provided by the `LDS_Guide_GraphQL` rule. This tool will also provide you with a method to dynamically query the target org instance that you will use to test the generated query.
+
+If the `LDS_Guide_GraphQL` rule has not been executed yet, you **MUST** run it first, and then get back to mutation query generation.
+
+## Mutation Queries General Information
+
+**IMPORTANT**:
+1. **Mutation Types**: The GraphQL engine supports `Create`, `Update` and `Delete` operations
+2. **Id Based Mutations**: `Update` and `Delete` operations operate on Id-based entity identification
+3. **Mutation Schema**: Defined in the [mutation query schema](#mutation-query-schema) section
+
+## Mutation Query Generation Workflow
+
+Strictly follow the rules below when generating the GraphQL mutation query:
+1. **Input Fields Validation** - Validate that the set of fields validate [input field constraints](#mutation-queries-input-field-constraints)
+2. **Output Fields Validation** - Validate that the set of fields used in the select part of the query validate the [output fields constraints](#mutation-queries-output-field-constraints)
+3. **Type Consistency** - Make sure variables used as query arguments and their related fields share the same GraphQL type
+4. **Report Phase** - Use the [Mutation Query Report Template](#mutation-query-report-template) below to report on the previous validation phases
+5. **Input Arguments** - `input` is the default name for the argument, unless otherwise specified
+6. **Output Field** - For `Create` and `Update` operations, the output field is always named `Record`, and is of type EntityName
+7. **Query Generation** - Use the [mutation query](#mutation-query-templates) template and adjust it based on the selected operation
+8. **Output Format** - Use the [standalone](#mutation-standalone-default-output-format---clean-code-only)
+9. **Test the Query** - Use the [Generated Mutation Query Testing](#generated-mutation-query-testing) workflow to test the generated query
+    1. **Report First** - Always report first, using the proper output format, before testing
+
+## Mutation Query Schema
+
+**Important**: In the schema fragments below, replace **EntityName** occurrences by the real entity name (i.e. Account, Case...).
+**Important**: `Delete` operations all share the same generic `Record` entity name for both input and payload, only exposing the standard `Id` field.
+
+```graphql
+input EntityNameCreateRepresentation {
+  # Subset of EntityName fields here
+}
+input EntityNameCreateInput { EntityName: EntityNameCreateRepresentation! }
+type EntityNameCreatePayload { Record: EntityName! }
+
+input EntityNameUpdateRepresentation {
+  # Subset of EntityName fields here
+}
+input EntityNameUpdateInput { Id: IdOrRef! EntityName: EntityNameUpdateRepresentation! }
+type EntityNameUpdatePayload { Record: EntityName! }
+
+input RecordDeleteInput { Id: IdOrRef! }
+type RecordDeletePayload { Id: ID }
+
+type UIAPIMutations {
+  EntityNameCreate(input: EntityNameCreateInput!): EntityNameCreatePayload
+  EntityNameDelete(input: RecordDeleteInput!): RecordDeletePayload
+  EntityNameUpdate(input: EntityNameUpdateInput!): EntityNameUpdatePayload
+}
+```
+
+## Mutation Queries Input Field Constraints
+
+1. **`Create` Mutation Queries**:
+    1. **MUST** include all required fields
+    2. **MUST** only include createable fields
+    3. Child relationships can't be set and **MUST** be excluded
+    4. Fields with type `REFERENCE` can only be assigned IDs through their `ApiName` name
+2. **`Update` Mutation Queries**:
+    1. **MUST** include the id of the entity to update
+    2. **MUST** only include updateable fields
+    3. Child relationships can't be set and **MUST** be excluded
+    4. Fields with type `REFERENCE` can only be assigned IDs through their `ApiName` name
+3. **`Delete` Mutation Queries**:
+    1. **MUST** include the id of the entity to delete
+
+## Mutation Queries Output Field Constraints
+
+1. **`Create` and `Update` Mutation Queries**:
+    1. **MUST** exclude all child relationships
+    2. **MUST** exclude all `REFERENCE` fields, unless accessed through their `ApiName` member (no navigation to referenced entity)
+    3. Inaccessible fields will be reported as part of the `errors` attribute in the returned payload
+    4. Child relationships **CAN'T** be queried as part of a mutation
+    5. Fields with type `REFERENCE` can only be queried through their `ApiName` (no referenced entities navigation, no sub fields)
+2. **`Delete` Mutation Queries**:
+    1. **MUST** only include the `Id` field
+
+## Mutation Query Report Template
+
+Input arguments:
+- Required fields: FieldName1 (Type1), FieldName2 (Type2)...
+- Other fields: FieldName3 (Type3)...
+  Output fields: FieldNameA (TypeA), FieldNameB (TypeB)...
+
+## Mutation Query Templates
+
+```graphql
+mutation mutateEntityName(
+  # arguments
+) {
+  uiapi {
+    EntityNameOperation(input: {
+      # the following is for `Create` and `Update` operations only
+      EntityName: {
+        # Input fields
+      }
+      # the following is for `Update` and `Delete` operations only
+      Id: ... # id here
+    }) {
+      # the following is for `Create` and `Update` operations only
+      Record {
+        # Output fields
+      }
+      # the following is for `Delete` operations only
+      Id: ... # id here
+    }
+  }
+}
+```
+
+## Mutation Standalone (Default) Output Format - CLEAN CODE ONLY
+
+```javascript
+const QUERY_NAME = `
+  mutation mutateEntity($input: EntityNameOperationInput!) {
+    uiapi {
+      EntityNameOperation(input: $input) {
+        # select output fields here depending on operation type
+      }
+    }
+  }
+`;
+
+const QUERY_VARIABLES = {
+  input: {
+    // The following is for `Create` and `Update` operations only
+    EntityName: {
+      // variables here
+    },
+    // The following is for `Update` and `Delete` operations only
+    Id: ... // id here
+  }
+};
+```
+
+**❌ DO NOT INCLUDE:**
+- Explanatory comments about the query
+- Field descriptions
+- Additional text about what the query does
+- Workflow step descriptions
+
+**✅ ONLY INCLUDE:**
+- Raw query string
+- Variables object
+- Nothing else
+
+## Generated Mutation Query Testing
+
+**Triggering conditions** - **ALL CONDITIONS MUST VALIDATE***
+1. Only if the [Mutation Query Generation Workflow](#mutation-query-generation-workflow) step global status is `SUCCESS` and you have a generated query
+2. Only if the query to generate is a mutation query
+3. Only if non manual method was used during `LDS_Guide_GraphQL` rule execution to retrieve introspection data
+
+**Workflow**
+1. **Report Step** - Explain that you are able to test the query using the same method used during introspection
+    1. You **MUST** report the method you will use, based on the one you used during `LDS_Guide_GraphQL` rule execution
+2. **Interactive Step** - Ask the user whether they want you to test the query using the proposed method
+    1. **WAIT** for the user's answer.
+3. **Input Arguments** - You **MUST** ask the user for the input arguments to use
+    1. **WAIT** for the user's answer.
+4. **Test Query** - If the user are OK with you testing the query:
+    1. Use the selected method to test the query
+    2. **IMPORTANT** - If you use the Salesforce CLI `sf api request graphql` command, you will need to inject the variable values directly into the query, as this command doesn't accept variables as a parameter
+5. **Result Analysis** - Retrieve the `data` and `errors` attributes from the returned payload, and report the result of the test as one of the following options:
+    1. `PARTIAL` if `data` is not an empty object, but `errors` is not an empty list - Explanation: some of the queried fields are not accessible on mutations
+    2. `FAILED` if `data` is an empty object - Explanation: the query is not valid
+    3. `SUCCESS` if `errors` is an empty list
+6. **Remediation Step** - If status is not `SUCCESS`, use the [`FAILED`](#failed-status-handling-workflow) or [`PARTIAL`](#partial-status-handling-workflow) status handling workflows
+
+### `FAILED` Status Handling Workflow
+
+The query is invalid:
+1. **Error Analysis** - Parse and categorize the specific error messages
+2. **Root Cause Identification** - Use error message to identify the root cause:
+    - **Execution** - Error contains `invalid cross reference id` or `entity is deleted`
+    - **Syntax** - Error contains `invalid syntax`
+    - **Validation** - Error contains `validation error`
+    - **Type** - Error contains `VariableTypeMismatch` or `UnknownType`
+    - **Navigation** - Error contains `is not currently available in mutation results`
+    - **API Version** - Query deals with updates, you're testing with Connect API and error contains `Cannot invoke JsonElement.isJsonObject()`
+3. **Targeted Resolution** - Depending on the root cause categorization
+    - **Execution** - You're trying to update or delete an unknown/no longer available entity: either create an entity first, if you have generated the related query, or ask for a valid entity id to use
+    - **Syntax** - Update the query using the error message information to fix the syntax errors
+    - **Validation** - This field's name is most probably invalid, ask user for clarification and **WAIT** for the user's answer
+    - **Type** - Use the error details and GraphQL schema to correct argument's type, and adjust variables accordingly
+    - **Navigation** - Use the [`PARTIAL` status handling workflow](#partial-status-handling-workflow) below
+    - **API Version** - `Record` selection is only available with API version 64 and higher, **report** the issue, and try again with API version 64
+4. **Test Again** - Resume the [query testing workflow](#generated-mutation-query-testing) with the updated query (increment and track attempt counter)
+5. **Escalation Path** - If targeted resolution fails after 2 attempts, ask for additional details and restart the entire GraphQL workflow, going again through the introspection phase
+
+### `PARTIAL` Status Handling Workflow
+
+The query can be improved:
+1. Report the fields mentioned in the `errors` list
+2. Explain that these fields can't be queried as part of a mutation query
+3. Explain that the query might be considered as failing, as it will report errors
+4. Offer to remove the offending fields
+5. **WAIT** for the user's answer
+6. If they are OK with removing the fields restart the [generation workflow](#mutation-query-generation-workflow) with the new field list