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

package/LICENSE.txt

@@ -0,0 +1,82 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this
+software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were
+last updated on April 15, 2025, and constitute a legally binding
+agreement between you and Salesforce. If you do not agree to these Terms of
+Use, do not install or use the Software.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free
+copyright license to reproduce, prepare derivative works of, publicly
+display, publicly perform, sublicense, and distribute the Software and
+derivative works subject to these Terms. These Terms shall be included in
+all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce
+reserves all rights, title, and interest in and to all intellectual
+property subsisting in the Software. No rights are granted to you hereunder
+other than as expressly set forth herein. Users residing in countries on
+the United States Office of Foreign Assets Control sanction list, or which
+are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you
+are responsible. The Software may contain bugs, errors and
+incompatibilities and is made available on an AS IS basis without support,
+updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or
+discontinue, the Software (or any part thereof) with or without notice. You
+agree that Salesforce shall not be liable to you or to any third party for
+any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or
+proceeding made or brought against Salesforce by a third party arising out
+of or accruing from (a) your use of the Software, and (b) any application
+you develop with the Software that infringes any copyright, trademark,
+trade secret, trade dress, patent, or other intellectual property right of
+any person or defames any person or violates their rights of publicity or
+privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce
+from any damages, attorney fees, and costs finally awarded against
+Salesforce as a result of, or for any amounts paid by Salesforce under a
+settlement approved by you in writing of, a Claim Against Salesforce,
+provided Salesforce (x) promptly gives you written notice of the Claim
+Against Salesforce, (y) gives you sole control of the defense and
+settlement of the Claim Against Salesforce (except that you may not settle
+any Claim Against Salesforce unless it unconditionally releases Salesforce
+of all liability), and (z) gives you all reasonable assistance, at your
+expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT
+SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES,
+INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL,
+PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA,
+OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN
+CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU
+HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of
+the State of California, without regard to its conflicts of laws
+rules. Each party hereby consents to the exclusive jurisdiction of the
+state and federal courts located in San Francisco County, California to
+adjudicate any dispute arising out of or relating to these Terms of Use and
+the download, installation, and/or use of the Software. Except as expressly
+stated herein, these Terms of Use constitute the entire agreement between
+the parties, and supersede all prior and contemporaneous agreements,
+proposals, or representations, written or oral, concerning their subject
+matter. No modification, amendment, or waiver of any provision of these
+Terms of Use shall be effective unless it is by an update to these Terms of
+Use that Salesforce makes available, or is in writing and signed by the
+party against whom the modification, amendment, or waiver is to be
+asserted.
+
+Data Privacy: Salesforce may collect, process, and store device,
+system, and other information related to your use of the Software. This
+information includes, but is not limited to, IP address, user metrics, and
+other data ("Usage Data"). Salesforce may use Usage Data for analytics,
+product development, and marketing purposes. You acknowledge that files
+generated in conjunction with the Software may contain sensitive or
+confidential data, and you are solely responsible for anonymizing and
+protecting such data.

package/README.md

@@ -0,0 +1,415 @@
+# Feature: Global Search
+
+This feature provides API services and utilities for implementing global search functionality in Salesforce Web Applications. It includes:
+
+- **API Service Layer** - Type-safe API client for Salesforce search endpoints
+- **Type Definitions** - Complete TypeScript types with Zod schema validation
+- **Utility Functions** - Helper functions for debouncing and data extraction
+- **Custom Hooks** - React hooks for managing search data and API calls
+
+## Features
+
+- **Multi-Object Search API** - Search across multiple Salesforce objects simultaneously
+- **Object Metadata API** - Fetch object information, column definitions, and filter definitions
+- **Picklist Values API** - Retrieve picklist values for dynamic filter options
+- **Type Safety** - Full TypeScript support with Zod schema validation
+- **Race Condition Protection** - AbortSignal support to cancel stale requests
+- **Error Handling** - Consistent error handling across all API calls
+
+## Architecture
+
+### API Service Layer
+
+The feature includes a state-agnostic service layer (`objectInfoService`) that provides pure functions for API interactions. All API calls:
+
+- Use `fetchAndValidate` utility for consistent error handling
+- Support `AbortSignal` for request cancellation
+- Validate responses with Zod schemas
+- Provide type-safe return values
+
+### API Flow Diagram
+
+The following flowchart explains the API architecture and how each API is consumed:
+
+```mermaid
+flowchart TD
+    Start([Application Initialization]) --> BatchAPI[getObjectInfoBatch API]
+    BatchAPI -->|Comma-separated Object Names| ObjectMetadata[Object Metadata]
+    ObjectMetadata --> LoadObjectData[Load Data for Each Object]
+
+    %% Parallel API Calls for Each Object
+    LoadObjectData --> ParallelAPIs{Parallel API Calls per Object}
+
+    %% List Info API
+    ParallelAPIs --> ListInfoAPI[getObjectListInfo API]
+    ListInfoAPI -->|Object Name + __SearchResult| Columns[Column Definitions]
+
+    %% Filters API
+    ParallelAPIs --> FiltersAPI[getObjectListFilters API]
+    FiltersAPI -->|Object Name| Filters[Filter Definitions]
+
+    %% Search Results API
+    ParallelAPIs --> SearchAPI[searchResults API]
+    SearchAPI -->|Query + Object Name + Pagination| SearchRecords[Search Records]
+
+    %% Picklist Values Flow
+    Filters --> PicklistCheck{Has Picklist Fields?}
+    PicklistCheck -->|Yes| PicklistAPI[getPicklistValues API]
+    PicklistAPI -->|Object Name + Field Name| PicklistValues[Picklist Options]
+    PicklistCheck -->|No| SkipPicklist[Skip Picklist Fetch]
+
+    %% User Interactions - API Calls
+    UserQuery([User Search Query]) --> Debounce[Debounce 500ms]
+    Debounce --> SearchAPI
+
+    FilterChange([Filter Change]) --> SearchAPI
+    PageChange([Pagination Change]) --> SearchAPI
+    PageSizeChange([Page Size Change]) --> SearchAPI
+
+    %% Error Handling
+    BatchAPI -.->|Error| ErrorHandler[Error Handler]
+    ListInfoAPI -.->|Error| ErrorHandler
+    FiltersAPI -.->|Error| ErrorHandler
+    SearchAPI -.->|Error| ErrorHandler
+    PicklistAPI -.->|Error| ErrorHandler
+    ErrorHandler --> HandleError[Handle Error Gracefully]
+
+    %% Race Condition Protection
+    SearchAPI -.->|AbortSignal| CancelOld[Cancel Old Request]
+    CancelOld --> PreventStale[Prevent Stale Data]
+
+    style BatchAPI fill:#e1f5ff
+    style ListInfoAPI fill:#e1f5ff
+    style FiltersAPI fill:#e1f5ff
+    style SearchAPI fill:#e1f5ff
+    style PicklistAPI fill:#e1f5ff
+    style ErrorHandler fill:#ffe1e1
+    style CancelOld fill:#fff4e1
+```
+
+## API Reference
+
+### 1. `getObjectInfoBatch(objectApiNames, signal?)`
+
+**Purpose**: Fetches object metadata for multiple Salesforce objects in a single request.
+
+**When to Use**:
+
+- Initial page load to get object labels and basic metadata
+- Needed to create tabs for each object type
+- Provides object plural labels for tab display
+
+**Parameters**:
+
+- `objectApiNames`: Comma-separated list (e.g., `"Account,Property__c"`)
+- `signal?`: Optional AbortSignal for cancellation
+
+**Returns**: `ObjectInfoBatchResponse` containing metadata for all requested objects
+
+**Example**:
+
+```typescript
+const objectInfo = await getObjectInfoBatch("Account,Property__c");
+// Returns: { objects: [{ apiName: 'Account', label: 'Accounts', ... }, ...] }
+```
+
+**API Endpoint**: `GET /object-info/batch/{objectApiNames}`
+
+---
+
+### 2. `getObjectListInfo(objectApiName, listViewApiName, signal?)`
+
+**Purpose**: Fetches column definitions for search results.
+
+**When to Use**:
+
+- When loading data for an object to determine which columns are available
+- Provides column metadata (field API names, labels, sortability)
+- Used to understand the structure of search results
+
+**Parameters**:
+
+- `objectApiName`: The object API name (e.g., `"Account"`)
+- `listViewApiName`: Always `"__SearchResult"` for search results
+- `signal?`: Optional AbortSignal for cancellation
+
+**Returns**: Array of `Column` objects with field information
+
+**Example**:
+
+```typescript
+const columns = await getObjectListInfo("Account", "__SearchResult");
+// Returns: [{ fieldApiName: 'Name', label: 'Account Name', sortable: true, ... }, ...]
+```
+
+**API Endpoint**: `GET /list-info/{objectApiName}/{listViewApiName}`
+
+---
+
+### 3. `getObjectListFilters(objectApiName, signal?)`
+
+**Purpose**: Fetches filter definitions for a specific object.
+
+**When to Use**:
+
+- When loading data for an object to determine available filters
+- Provides filter metadata (field types, operators, default values, affordances)
+- Used to understand what filters can be applied to search results
+
+**Parameters**:
+
+- `objectApiName`: The object API name (e.g., `"Account"`)
+- `signal?`: Optional AbortSignal for cancellation
+
+**Returns**: Array of `Filter` objects with filter definitions
+
+**Example**:
+
+```typescript
+const filters = await getObjectListFilters("Account");
+// Returns: [{ targetFieldPath: 'Name', operator: 'contains', ... }, ...]
+```
+
+**API Endpoint**: `GET /search-info/{objectApiName}/filters`
+
+---
+
+### 4. `getPicklistValues(objectApiName, fieldName, recordTypeId?, signal?)`
+
+**Purpose**: Fetches available picklist values for a specific field.
+
+**When to Use**:
+
+- When a filter has `affordance: 'select'` (indicating a picklist field)
+- Needed to get the list of valid values for a picklist filter
+- Called for each picklist field in the filters array returned by `getObjectListFilters`
+
+**Parameters**:
+
+- `objectApiName`: The object API name (e.g., `"Account"`)
+- `fieldName`: The field API name (e.g., `"Type"`)
+- `recordTypeId?`: Optional record type ID (defaults to master record type)
+- `signal?`: Optional AbortSignal for cancellation
+
+**Returns**: Array of `PicklistValue` objects with label and value
+
+**Example**:
+
+```typescript
+const picklistValues = await getPicklistValues("Account", "Type");
+// Returns: [{ label: 'Customer', value: 'Customer' }, { label: 'Partner', value: 'Partner' }, ...]
+```
+
+**API Endpoint**: `GET /object-info/{objectApiName}/picklist-values/{recordTypeId}/{fieldName}`
+
+---
+
+### 5. `searchResults(query, objectApiName, params?, signal?)`
+
+**Purpose**: Performs keyword search on a specific object and returns matching records.
+
+**When to Use**:
+
+- When executing a search query for a specific object
+- When filters are applied (query should include filter criteria)
+- When pagination changes (use `pageToken` parameter)
+- When page size changes (use `pageSize` parameter)
+- Returns the actual search results with field values
+
+**Parameters**:
+
+- `query`: The search query string
+- `objectApiName`: The object API name to search (e.g., `"Account"`)
+- `params?`: Optional pagination parameters (`pageSize`, `pageToken`)
+- `signal?`: Optional AbortSignal for cancellation (critical for race condition prevention)
+
+**Returns**: Array of `SearchResultRecord` objects with field values
+
+**Example**:
+
+```typescript
+const results = await searchResults("Acme", "Account", { pageSize: 25, pageToken: "0" });
+// Returns: [{ id: '001...', fields: { Name: 'Acme Corp', ... }, ... }, ...]
+```
+
+**API Endpoint**: `POST /search/results/keyword?q={query}&objectApiName={objectApiName}`
+
+**Request Body**:
+
+```json
+{
+  "pageSize": 25,
+  "pageToken": "0"
+}
+```
+
+---
+
+## API Consumption Flow
+
+### Initialization
+
+1. **`getObjectInfoBatch`** is called with all object names from `OBJECT_API_NAMES`
+   - Returns object metadata (labels, plural labels, etc.)
+   - Use this to understand which objects are available for search
+
+2. **For each object** (can be done in parallel):
+   - **`getObjectListInfo`** - Gets column definitions for search results
+   - **`getObjectListFilters`** - Gets filter definitions
+   - **`searchResults`** - Gets initial search results (if query is provided)
+
+3. **For each picklist filter** (can be done in parallel):
+   - **`getPicklistValues`** - Gets available values for picklist fields
+
+### Search Execution
+
+1. **Initial Search**:
+   - Call **`searchResults`** with the search query and object API name
+   - Include pagination parameters (`pageSize`, `pageToken`)
+
+2. **Filter Application**:
+   - Apply filters to the search query
+   - Call **`searchResults`** with updated query/filters
+   - Reset pagination to page 1 (use `pageToken: '0'`)
+
+3. **Pagination**:
+   - Use `pageToken` from previous response for next page
+   - Call **`searchResults`** with new `pageToken`
+
+4. **Page Size Change**:
+   - Call **`searchResults`** with new `pageSize`
+   - Reset to page 1 (use `pageToken: '0'`)
+
+### Race Condition Prevention
+
+All API calls support `AbortSignal` to prevent stale data:
+
+- When a new search is triggered, cancel the previous request using `AbortSignal`
+- When switching between objects, cancel previous object requests
+- When component unmounts, cancel all pending requests
+
+This ensures applications always work with the most recent data and avoid race conditions.
+
+## Setup
+
+### Prerequisites
+
+1. **Salesforce CLI (`sf`)** - Must be installed and authenticated to a Salesforce org
+2. **@salesforce/webapps packages** - Required for API proxy functionality (see linking instructions below)
+
+### Linking @salesforce/webapps (Required until packages are published)
+
+Since `@salesforce/webapps` and `@salesforce/vite-plugin-webapps` are not yet published to npm, you need to link them locally:
+
+```bash
+# Step 1: In the webapps repo - register packages with npm's link registry
+cd /path/to/webapps/packages/webapps && npm link
+cd /path/to/webapps/packages/vite-plugin-webapps && npm link
+
+# Step 2: In this repo - link the packages
+cd /path/to/webapps-templates/packages/feature/feature-react-global-search
+npm link @salesforce/webapps
+npm link @salesforce/vite-plugin-webapps
+```
+
+### Building and Running
+
+```bash
+# Build the feature (applies patches from template to dist)
+npm run build
+
+# Start the development server
+npm run dev
+```
+
+The `npm run build` command will:
+
+1. Apply feature patches to create the dist directory
+2. Remove the package-lock.json (to avoid resolution conflicts)
+3. Re-link the @salesforce/webapps packages
+
+## Configuration
+
+### Setting Searchable Objects
+
+Configure which Salesforce objects to search by editing `src/constants.ts`:
+
+```typescript
+export const OBJECT_API_NAMES = ["Account", "Property__c"] as const;
+```
+
+This configuration determines which objects will be included when calling `getObjectInfoBatch` and when executing searches.
+
+## Usage
+
+### Using the API Service
+
+Import the service and use the available methods:
+
+```typescript
+import { objectInfoService } from "@/api/objectInfoService";
+
+// Get object metadata
+const objectInfo = await objectInfoService.getObjectInfoBatch("Account,Property__c");
+
+// Get column definitions
+const columns = await objectInfoService.getObjectListInfo("Account", "__SearchResult");
+
+// Get filter definitions
+const filters = await objectInfoService.getObjectListFilters("Account");
+
+// Get picklist values
+const picklistValues = await objectInfoService.getPicklistValues("Account", "Type");
+
+// Execute search
+const results = await objectInfoService.searchResults("Acme", "Account", {
+  pageSize: 25,
+  pageToken: "0",
+});
+```
+
+### Using the Custom Hook
+
+The `useObjectSearchData` hook manages API calls and data fetching:
+
+```typescript
+import { useObjectSearchData } from "@/hooks/useObjectSearchData";
+
+const { tabs, loading, error, tabData, filtersData } = useObjectSearchData({
+  filteredObjectApiNames: ["Account", "Property__c"],
+  activeTab: "Account",
+  searchQuery: "Acme",
+  searchPageSize: 25,
+  searchPageToken: "0",
+});
+```
+
+## Type Safety
+
+All API responses are validated using Zod schemas, ensuring:
+
+- Type safety at compile time
+- Runtime validation of API responses
+- Better error messages when API contracts change
+- Protection against malformed data
+
+Type definitions are derived from Zod schemas using `z.infer`, ensuring consistency between validation and TypeScript types.
+
+## Error Handling
+
+The `fetchAndValidate` utility provides consistent error handling:
+
+- Network errors are caught and re-thrown with context
+- HTTP errors (non-200 status) are caught and reported
+- Zod validation errors are caught and reported (without logging sensitive details)
+- AbortErrors are properly propagated (not treated as regular errors)
+
+All errors are handled gracefully in the UI, preventing page refreshes and providing user-friendly error messages.
+
+## Dependencies
+
+This feature depends on:
+
+- **feature-shadcn** - For all UI components (Button, Input, Select, Table, Pagination, etc.)
+- **@salesforce/webapps** - For API client and Salesforce integration
+- **zod** - For runtime validation and type inference

package/dist/.a4drules/build-validation.md

@@ -0,0 +1,81 @@
+# AI Rule: Build Validation
+
+Build validation for successful deployments with minimal friction.
+
+## Targets
+- `force-app/main/default/webapplications/*/**/*`
+- `**/*.{js,ts,jsx,tsx}`
+
+## MANDATORY: Build Success
+
+**Before completing any coding session:**
+```bash
+npm run build  # MUST succeed with no errors
+```
+
+## Quick Quality Checks
+```bash
+npm run format:check  # Auto-fixable
+npm run lint          # Most issues auto-fixable
+tsc -b               # Catches major issues
+```
+
+## Requirements
+
+**Must Pass:**
+- `npm run build` completes successfully
+- No TypeScript compilation errors
+- No critical ESLint errors
+
+**Can Be Warnings:**
+- ESLint warnings
+- Prettier formatting issues
+- Minor TypeScript warnings
+
+## Auto-Fix Commands
+```bash
+npm run fix-all      # Fix formatting + linting
+npm run format       # Fix Prettier issues
+npm run lint:fix     # Fix ESLint issues
+```
+
+## Workflow
+
+**During Development:**
+1. Write code with AI assistance
+2. Save frequently (auto-format on save)
+3. Check periodically: `npm run lint` (optional)
+
+**Before Completion:**
+1. Run `npm run build`
+2. If fails: Run `npm run fix-all`, fix TypeScript errors, retry build
+
+## Error Priority
+
+**Fix Immediately:**
+- TypeScript compilation errors
+- Import/export errors
+- Syntax errors
+
+**Fix When Convenient:**
+- ESLint warnings
+- Prettier formatting
+- Unused variables
+
+## Hard Requirements
+- Build must complete without errors
+- No broken imports
+- Basic TypeScript type safety
+
+## Key Commands
+```bash
+npm run dev          # Start development
+npm run build        # Check deployment readiness
+npm run fix-all      # Fix common issues
+```
+
+## Troubleshooting Import Errors
+```bash
+npm install          # Check missing dependencies
+# Verify file exists, case sensitivity, export/import match
+```