@salesforce/webapp-template-feature-react-global-search-experimental 1.75.1 → 1.76.1

package/README.md

@@ -1,403 +1,250 @@
-# Feature: Global Search
+# Feature: React Global Search (Single Object)
 
-This feature provides API services and utilities for implementing global search functionality in Salesforce Web Applications. It includes:
+This package is a **reference implementation** for adding global search (keyword search, filters, results list, and record detail) to a Salesforce web app. It provides **API services, hooks, types/schemas, and utilities** so you can **build your own UI** and import the data layer from the package—or optionally **copy** the reference UI from the package and adapt it.
 
-## Consuming as a dependency
+**Intended use (vibing model):**
 
-Apps (e.g. `appreactsampleb2e`) can depend on this package and import **API, hooks, types, and utilities** (no UI). The package exposes a built ESM bundle.
+- **Do not copy the feature source** (api, hooks, types, utils).
+- **Build your own UI** (recommended), or **copy** the reference pages/components from the package and adapt.
+- **Import** data-layer pieces from the package: services, hooks, types, utilities.
 
-1. Add the dependency: `"@salesforce/webapp-template-feature-react-global-search-experimental": "^1.71.3"`.
-2. **Before building or running the app**, build the library bundle from this package:
-   ```bash
-   cd packages/template/feature/feature-react-global-search && npm run build:lib
-   ```
-   This produces `dist/index.js`, which is the package entry point.
-3. Import what you need (e.g. `useObjectListMetadata`, `parseFilterValue`, `sanitizeFilterValue`, `FilterCriteria`, `objectInfoService`). Use your own UI for filters and list pages.
+UI components and feature constants are deliberately **not exported** from the public API.
 
-- **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
-
-### Data Layer (GraphQL vs REST)
-
-- **GraphQL (uiapi)**
-  - **Object metadata** – `getObjectInfoBatch` and `getPicklistValues` are implemented via `getObjectInfosGraphQL` (uiapi.objectInfos). Responses are adapted to the existing REST-shaped types.
-  - **Records** – A single query path is used for both list and detail: `getRecordsGraphQL` with optional `recordId` for single-record fetch. `getRecordByIdGraphQL` is a thin wrapper that calls `getRecordsGraphQL` with `recordId` and `first: 1`.
-
-- **REST (uiApiClient)**
-  - **Layout** – Detail view layout comes from `GET /layout/{object}` (used by `objectDetailService.getRecordDetail`).
-  - **List/search** – Columns are derived from `getObjectListFilters` (e.g. `filters.map(f => ({ fieldApiName: f.targetFieldPath, label: f.label }))`); filters and results from `getObjectListFilters` / `searchResults` (keyword search) or from `getRecordsGraphQL` for list views.
-
-The detail page uses `useRecordDetailLayout` → `objectDetailService.getRecordDetail` (layout + object metadata + single record by Id). List/search uses `useRecordListGraphQL` (columns derived from Filters API, records from GraphQL) or `useObjectSearchData` (REST search).
-
-### API Service Layer
-
-The feature includes a state-agnostic service layer (`objectInfoService`, `objectDetailService`, record GraphQL helpers) 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}
+## What you get (public API)
+
+Import from the package root:
+
+```ts
+import {
+  objectInfoService,
+  objectDetailService,
+  useObjectListMetadata,
+  useRecordListGraphQL,
+  useRecordDetailLayout,
+  useObjectColumns,
+  useObjectFilters,
+  useObjectInfoBatch,
+  type FilterCriteria,
+  parseFilterValue,
+  sanitizeFilterValue,
+} from "@salesforce/webapp-template-feature-react-global-search-experimental";
+```
 
-    %% Filters API (columns derived from filters via targetFieldPath)
-    ParallelAPIs --> FiltersAPI[getObjectListFilters API]
-    FiltersAPI -->|Object Name| Filters[Filter Definitions]
-    Filters --> Columns[Column Definitions]
+### API services
 
-    %% Search Results API
-    ParallelAPIs --> SearchAPI[searchResults API]
-    SearchAPI -->|Query + Object Name + Pagination| SearchRecords[Search Records]
+- **`objectInfoService`**
+  - `getObjectInfoBatch(objectApiNames)` (GraphQL uiapi.objectInfos)
+  - `getPicklistValues(objectApiName, fieldName, recordTypeId?)` (GraphQL uiapi.objectInfos)
+  - `getObjectListFilters(objectApiName)` (REST search-info filters)
+- **`objectDetailService`**
+  - `getLayout(objectApiName, recordTypeId?)` (REST layout)
+  - `getRecordDetail(objectApiName, recordId, recordTypeId?)` (layout + object info + record)
+- **GraphQL record helpers**
+  - `getRecordsGraphQL(...)` (list query, `first + after`)
+  - `getRecordByIdGraphQL(...)` (single record by Id)
+  - `buildWhereFromCriteria(...)`, `buildOrderByFromSort(...)`, `buildGetRecordsQuery(...)`
 
-    %% 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]
+### Hooks
 
-    %% User Interactions - API Calls
-    UserQuery([User Search Query]) --> Debounce[Debounce 500ms]
-    Debounce --> SearchAPI
+- **List metadata**: `useObjectListMetadata(objectApiName)` — filters, columns (derived from filters), picklistValues.
+- **List columns (legacy)**: `useObjectColumns(objectApiName)` — columns, columnsLoading, columnsError.
+- **List filters**: `useObjectFilters(objectApiName)` — filtersData (filters + picklist values per object).
+- **List records**: `useRecordListGraphQL({ objectApiName, first, after, filters, sortBy, searchQuery, columns? })` — GraphQL list with cursor pagination.
+- **Detail**: `useRecordDetailLayout({ objectApiName, recordId, recordTypeId?, initialData? })` — layout (REST) + object metadata + record (GraphQL).
+- **Batch object info**: `useObjectInfoBatch(objectApiNames)` — objectInfos, loading, error.
 
-    FilterChange([Filter Change]) --> SearchAPI
-    PageChange([Pagination Change]) --> SearchAPI
-    PageSizeChange([Page Size Change]) --> SearchAPI
+### Types, schemas, utils
 
-    %% Error Handling
-    BatchAPI -.->|Error| ErrorHandler[Error Handler]
-    FiltersAPI -.->|Error| ErrorHandler
-    SearchAPI -.->|Error| ErrorHandler
-    PicklistAPI -.->|Error| ErrorHandler
-    ErrorHandler --> HandleError[Handle Error Gracefully]
+- **Types**: `Filter`, `FilterCriteria`, `Column`, `SearchResultRecord`, `LayoutResponse`, `ObjectInfoResult`, …
+- **Zod schemas**: `LayoutResponseSchema`, `ObjectInfoResultSchema`, `SearchResultsResponseSchema`, …
+- **Utilities**: `parseFilterValue`, `sanitizeFilterValue`, `createFiltersKey`, `getGraphQLNodeValue`, `graphQLNodeToSearchResultRecordData`, `fetchAndValidate`, `safeEncodePath`, `getNestedFieldValue`, `getRecordDisplayName`, layout transform and form helpers, etc.
 
-    %% Race Condition Protection
-    SearchAPI -.->|AbortSignal| CancelOld[Cancel Old Request]
-    CancelOld --> PreventStale[Prevent Stale Data]
+The definitive type surface is in `index.d.ts` in this package.
 
-    style BatchAPI fill:#e1f5ff
-    style FiltersAPI fill:#e1f5ff
-    style SearchAPI fill:#e1f5ff
-    style PicklistAPI fill:#e1f5ff
-    style ErrorHandler fill:#ffe1e1
-    style CancelOld fill:#fff4e1
-```
+---
 
-## API Reference
+## Features
 
-### 1. `getObjectInfoBatch(objectApiNames, signal?)`
+- **Single object browse & search**: keyword search and “browse all” mode (`browse__all`).
+- **Filterable list**: filter definitions + picklist values, criteria → GraphQL where clause.
+- **Sortable list**: build orderBy from sort selection.
+- **Cursor pagination (forward-only)** with **previous-page simulation via cursor stack**.
+- **Record detail**: layout-driven field selection (layout REST + record GraphQL).
+- **Type safety**: Zod validation + exported TypeScript types.
 
-**Purpose**: Fetches object metadata for multiple Salesforce objects in a single request.
+---
 
-**When to Use**:
+## Architecture
 
-- 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
+### Data layer (GraphQL vs REST)
 
-**Parameters**:
+- **GraphQL (uiapi)**  
+  Object metadata via `getObjectInfoBatch` and `getPicklistValues`. Records via `getRecordsGraphQL` and `getRecordByIdGraphQL`.
+- **REST (uiApiClient)**  
+  Layout from `GET /layout/{object}`. Search filters from `GET /search-info/{object}/filters`. List/search results are **GraphQL-only** via `useRecordListGraphQL` (no REST keyword search in the public API).
 
-- `objectApiNames`: Comma-separated list (e.g., `"Account,Property__c"`)
-- `signal?`: Optional AbortSignal for cancellation
+In the reference implementation:
 
-**Returns**: `ObjectInfoBatchResponse` containing metadata for all requested objects
+- **Detail page**: `useRecordDetailLayout` → `objectDetailService.getRecordDetail` (layout REST + record GraphQL).
+- **List page**: `useObjectListMetadata` (filters + columns + picklists) + `useRecordListGraphQL` (records).
 
-**Example**:
+### API flow (conceptual)
 
-```typescript
-const objectInfo = await getObjectInfoBatch("Account,Property__c");
-// Returns: { objects: [{ apiName: 'Account', label: 'Accounts', ... }, ...] }
-```
+- **Initialization**: `getObjectInfoBatch` for object metadata; per object: `getObjectListFilters` (columns derived from filters), then `getPicklistValues` for picklist filters.
+- **List/search**: `useRecordListGraphQL` (GraphQL UI API with cursor pagination; use a cursor stack for “Previous”).
+- **Detail**: `useRecordDetailLayout` / `objectDetailService.getRecordDetail`.
 
-**API Endpoint**: `GET /object-info/batch/{objectApiNames}`
+All API calls use `fetchAndValidate` and validate with Zod.
 
 ---
 
-### 2. `getObjectListFilters(objectApiName, signal?)`
+## Install
 
-**Purpose**: Fetches filter definitions for a specific object.
-
-**When to Use**:
+```bash
+npm install @salesforce/webapp-template-feature-react-global-search-experimental
+```
 
-- 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
+### Required peer environment
 
-**Parameters**:
+- `@salesforce/webapp-experimental` (API proxy, auth, etc.)
+- React and React Router
 
-- `objectApiName`: The object API name (e.g., `"Account"`)
-- `signal?`: Optional AbortSignal for cancellation
+If you are not using that stack, you can still reuse **pure** utilities and types; the API services and hooks need an equivalent UI API transport.
 
-**Returns**: Array of `Filter` objects with filter definitions
+---
 
-**Example**:
+## Configuration (constants)
 
-```typescript
-const filters = await getObjectListFilters("Account");
-// Returns: [{ targetFieldPath: 'Name', operator: 'contains', ... }, ...]
-```
+Constants are **not exported**. When you build your app (or copy reference UI), define them in the app:
 
-**API Endpoint**: `GET /search-info/{objectApiName}/filters`
+- **OBJECT_API_NAMES** – Array of object API names to search. First element is the primary object (e.g. `OBJECT_API_NAMES[0]`). Default to `["Account"]` if no object is specified.
+- **DEFAULT_PAGE_SIZE** – e.g. `20`.
+- **DEFAULT_DETAIL_PAGE_TITLE** – e.g. `"Untitled"`.
 
-Column definitions for list/result UI are derived from the filters response: `filters.map(f => ({ fieldApiName: f.targetFieldPath, label: f.label, searchable: true, sortable: true }))`. The `useObjectColumns` hook calls `getObjectListFilters` and derives columns internally.
+**Determining the search object:** Decide from the user’s request or app context. If the user does not specify an object, use **Account**. If your repo provides a script (e.g. `scripts/parse-feature-install-context.cjs`), you can use it to parse the user prompt and get an object API name or label hint; otherwise set OBJECT_API_NAMES in the app’s constants accordingly.
 
 ---
 
-### 3. `getPicklistValues(objectApiName, fieldName, recordTypeId?, signal?)`
-
-**Purpose**: Fetches available picklist values for a specific field.
-
-**When to Use**:
+## Vibing integration (recommended: build your own UI)
 
-- 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`
+1. **Routes**  
+   Search results: e.g. `/global-search/:query` (use `browse__all` for “show all”). Record detail: e.g. `/object/:objectApiName/:recordId`.
 
-**Parameters**:
+2. **Search entry**  
+   On submit, navigate to `/global-search/${encodeURIComponent(query)}` or `/global-search/browse__all`.
 
-- `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
+3. **Results page (list)**  
+   Use `useObjectListMetadata(objectApiName)` for filters/columns/picklists and `useRecordListGraphQL({ objectApiName, first, after, filters, sortBy, searchQuery, columns })` for records. Implement a **cursor stack** for “Previous” (see reference `GlobalSearch` page).
 
-**Returns**: Array of `PicklistValue` objects with label and value
+4. **Detail page**  
+   Use `useRecordDetailLayout({ objectApiName, recordId })` for `layout`, `record`, `objectMetadata`; render with `layoutTransformUtils` and `graphQLNodeFieldUtils` (or equivalent).
 
-**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. **Search input placement**  
+   Put the search entry on the **Home page** (e.g. as a card) or in the app **Header**—**not** in a root layout that wraps every page.
 
 ---
 
-### 4. `searchResults(query, objectApiName, params?, signal?)`
+## Optional: copy reference UI from the package
 
-**Purpose**: Performs keyword search on a specific object and returns matching records.
+The package **does not export** UI components. If you prefer to copy the reference UI instead of building your own:
 
-**When to Use**:
+- **What to import (do not copy):** API (`objectInfoService`, `objectDetailService`, …), hooks (`useObjectListMetadata`, `useRecordListGraphQL`, `useRecordDetailLayout`, …), types, Zod schemas, utilities.
+- **What to copy into the app:** A single **constants** file (set `OBJECT_API_NAMES` to your chosen object(s)) and the **pages** and **components** from the package’s reference implementation.
 
-- 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
+**Path convention (reference implementation in this repo):**
 
-**Parameters**:
+All paths below are relative to the **package root** of this feature. The reference implementation lives under:
 
-- `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)
+`src/force-app/main/default/webapplications/feature-react-global-search/src/features/global-search/`
 
-**Returns**: Array of `SearchResultRecord` objects with field values
+Example paths:
 
-**Example**:
+- Constants: `src/force-app/main/default/webapplications/feature-react-global-search/src/features/global-search/constants.ts`
+- Search page: `src/force-app/main/default/webapplications/feature-react-global-search/src/features/global-search/pages/GlobalSearch.tsx`
+- Components: `src/force-app/main/default/webapplications/feature-react-global-search/src/features/global-search/components/`
 
-```typescript
-const results = await searchResults("Acme", "Account", { pageSize: 25, pageToken: "0" });
-// Returns: [{ id: '001...', fields: { Name: 'Acme Corp', ... }, ... }, ...]
-```
+After copying **pages/** and **components/** into your app:
 
-**API Endpoint**: `POST /search/results/keyword?q={query}&objectApiName={objectApiName}`
+1. In the **copied files only**, replace imports from `@/api`, `@/hooks`, `@/types`, `@/utils`, `@/lib`, `@/features` with imports from **`@salesforce/webapp-template-feature-react-global-search-experimental`**.
+2. Keep constants and component-to-component imports pointing at your app’s copied constants and components.
+3. Adapt markup and styles to your app’s UI library (the reference uses shadcn and Tailwind).
 
-**Request Body**:
+---
 
-```json
-{
-  "pageSize": 25,
-  "pageToken": "0"
+## Example: build filters → FilterCriteria[]
+
+```ts
+import {
+  parseFilterValue,
+  sanitizeFilterValue,
+  type FilterCriteria,
+} from "@salesforce/webapp-template-feature-react-global-search-experimental";
+
+function toCriteria(
+  objectApiName: string,
+  fieldPath: string,
+  operator: "eq" | "like",
+  rawValues: string[],
+): FilterCriteria {
+  return {
+    objectApiName,
+    fieldPath,
+    operator,
+    values: rawValues
+      .map((v) => sanitizeFilterValue(v))
+      .filter(Boolean)
+      .map((v) => parseFilterValue(v)),
+  };
 }
 ```
 
 ---
 
-## 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):
-   - **`getObjectListFilters`** - Gets filter definitions; column definitions for list/result UI are derived from filters (e.g. `filters.map(f => f.targetFieldPath)` for field names)
-   - **`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
+## Implementation steps (for an agent)
 
-1. **Initial Search**:
-   - Call **`searchResults`** with the search query and object API name
-   - Include pagination parameters (`pageSize`, `pageToken`)
+1. **Install**  
+   From the consumer app root: `npm install @salesforce/webapp-template-feature-react-global-search-experimental`.
 
-2. **Filter Application**:
-   - Apply filters to the search query
-   - Call **`searchResults`** with updated query/filters
-   - Reset pagination to page 1 (use `pageToken: '0'`)
+2. **Determine search object(s)**  
+   From user prompt or app context. Default to **Account** if none specified. Set `OBJECT_API_NAMES` in the app’s constants to this value.
 
-3. **Pagination**:
-   - Use `pageToken` from previous response for next page
-   - Call **`searchResults`** with new `pageToken`
+3. **Constants**  
+   In the app, create a constants file (or copy from the package reference path above) and set `OBJECT_API_NAMES`, `DEFAULT_PAGE_SIZE`, `DEFAULT_DETAIL_PAGE_TITLE`.
 
-4. **Page Size Change**:
-   - Call **`searchResults`** with new `pageSize`
-   - Reset to page 1 (use `pageToken: '0'`)
+4. **API / types / utils / hooks**  
+   **Import** only from the package. Do **not** create or copy `api/`, `hooks/`, `types/`, or `utils/` in the app.
 
-### Race Condition Prevention
+5. **UI**  
+   Either **(a)** build your own UI using the package’s hooks and types, or **(b)** copy the full **pages/** and **components/** from the package reference path into the app, then batch-replace imports in the copied files to use the package (see “Optional: copy reference UI” above).
 
-All API calls support `AbortSignal` to prevent stale data:
+6. **Routes and search input**  
+   Add routes for search (e.g. `/global-search/:query`) and record detail (e.g. `/object/:objectApiName/:recordId`). Place the search input on the **Home page** or in the **Header** only—not in a root layout.
 
-- 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
+### Checklist
 
-This ensures applications always work with the most recent data and avoid race conditions.
+- [ ] Package installed.
+- [ ] Search object(s) determined; `OBJECT_API_NAMES` set in app constants.
+- [ ] API, types, utils, hooks **imported** from package only (no api/hooks/types/utils folders in app).
+- [ ] UI: own implementation **or** full copy of reference pages/components with imports updated to the package.
+- [ ] Routes and search entry placement done; GlobalSearchInput not in root layout.
 
-## 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)
+## Notes / constraints
 
-### Linking @salesforce/webapps (Required until packages are published)
+- **Single-object scope**: The package’s APIs and hooks are designed for one CRM object at a time (one `objectApiName` per call). There is no built-in multi-object search or tabbed results. You can still implement **multi-object CRM search** by calling the same services and hooks once per object (e.g. in parallel or per tab), then combining the results and building your own UI (tabs, merged lists, or separate sections).
+- **Layout is REST**: record layout from UI API REST; record and object metadata are GraphQL-backed.
+- **No UI exports**: build or copy UI in the app; import only the data layer from the package.
 
-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
-```
+## Local development (this repo)
 
-### Building and Running
+When developing this feature inside the webapps repo:
 
 ```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;
+nx run @salesforce/webapp-template-feature-react-global-search-experimental:build:dist-app
+nx run @salesforce/webapp-template-feature-react-global-search-experimental:dev
 ```
-
-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 filter definitions (columns for list UI are derived from filters via targetFieldPath + label)
-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/skills/webapp-add-react-component/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: webapp-add-react-component
+description: Creates React components, pages, headers, and footers using shadcn UI and Tailwind CSS. Use when the user asks to create a component, add a widget, build a UI element, add a page, create a new page, add a section (e.g. "add a contacts page"), add a header, add a footer, add a navigation bar, or add anything to the web application.
+---
+
+# Add React Component
+
+## Step 1 — Identify the type of component
+
+Determine which of these three categories the request falls into, then follow the corresponding section below:
+
+- **Page** — user wants a new routed page (e.g. "add a contacts page", "create a dashboard page", "add a settings section")
+- **Header / Footer** — user wants a site-wide header, footer, nav bar, or page footer that appears on every page
+- **Component** — everything else: a widget, card, table, form, dialog, or other UI element placed within an existing page
+
+If it is not immediately clear from the user's message, ask:
+
+> "Are you looking to add a new page, a site-wide header or footer, or a component within an existing page?"
+
+Then follow the matching section.
+
+---
+
+## Clarifying Questions
+
+Ask **one question at a time** and wait for the response before asking the next. Stop when you have enough to build accurately — do not guess or assume.
+
+### For a Page
+
+1. **What is the name and purpose of the page?** (e.g., Contacts, Dashboard, Settings)
+2. **What URL path should it use?** (e.g., `/contacts`, `/dashboard`) — or derive from the page name?
+3. **Should the page appear in the navigation menu?**
+4. **Who can access it?** Public, authenticated users only (`PrivateRoute`), or unauthenticated only (e.g., login — `AuthenticationRoute`)?
+5. **What content or sections should the page include?** (list, form, table, detail view, etc.)
+6. **Does it need to fetch any data?** If so, from where?
+
+### For a Header / Footer
+
+1. **Header, footer, or both?**
+2. **What should the header contain?** (logo/app name, nav links, user avatar, CTA button, etc.)
+3. **What should the footer contain?** (copyright text, links, social icons, etc.)
+4. **Should the header be sticky (fixed to top while scrolling)?**
+5. **Is there a logo or brand name to display?** (or placeholder?)
+6. **Any specific color scheme or style direction?** (dark background, branded primary color, minimal, etc.)
+7. **Should navigation links appear in the header?** If so, which pages?
+
+### For a Component
+
+1. **What should the component do?** (display data, accept input, trigger an action, etc.)
+2. **What page or location should it appear on?**
+3. **Is this shared/reusable across pages, or specific to one feature?** (determines file location)
+4. **What data or props does it need?** (static content, props, fetched data)
+5. **Does it need internal state?** (loading, toggle, form state, etc.)
+6. **Are there any specific shadcn components to use?** (Card, Table, Dialog, Form, etc.)
+7. **Should it appear in a specific layout position?** (full-width, sidebar, inline, etc.)
+
+---
+
+## Implementation
+
+Once you have identified the type and gathered answers to the clarifying questions, read and follow the corresponding implementation guide:
+
+- **Page** — read `implementation/page.md` and follow the instructions there.
+- **Header / Footer** — read `implementation/header-footer.md` and follow the instructions there.
+- **Component** — read `implementation/component.md` and follow the instructions there.
+
+---
+
+## Verification
+
+Before completing, run from the web app directory `force-app/main/default/webapplications/<appName>/` (use the actual app folder name):
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors. Fix any ESLint or TypeScript issues.
+- **Build:** MUST succeed. Resolve any compilation or Vite build failures before finishing.