# Smart Lookup Picker User Guide

## A. Template name

Smart Lookup Picker

## B. Short description

Smart Lookup Picker is a reusable Yeeflow custom code control that lets users search a Yeeflow data list, select one or more matching records, optionally add manual entries, and save the result back into configured form fields.

## C. Purpose / what this is for

Many business forms need users to choose an existing supplier, customer, product, employee, department, contract, asset, or partner from a master list. A normal text field is too loose, and a static dropdown can become hard to use when the list is large.

Smart Lookup Picker solves this by giving users a search-based picker that queries a configured Yeeflow data list as they type. Users can select matched records, see selected values as chips, remove mistakes, and optionally enter a new/manual value when the right record does not exist yet.

Customers use this template when they want cleaner structured input, fewer spelling mistakes, better master-data consistency, and a faster form experience.

## D. Supported placement

This template is optimized for:

- Approval form
- Data list form
- Dashboard page, when output values are written to dashboard temp variables

It is a data-entry/search control, not a dashboard analytics component.

## E. When to use this template

Use Smart Lookup Picker when users need to search and select records from a Yeeflow data list inside a form.

Best-fit scenarios include:

- selecting a supplier in a purchase request
- selecting a customer in a service case
- selecting one or more products in a request form
- selecting a department, employee, asset, contract, or partner from a master list
- allowing users to enter a new supplier/customer name when it is not yet in the master data

Do not use this template when the option list is very small and a normal dropdown is enough.

## F. Input parameters overview table

| Parameter name | Type | Required | Purpose | Example value |
| --- | --- | --- | --- | --- |
| `dataListId` | Expression / variable | Required | Target Yeeflow data list to search. | Supplier Master list ID |
| `displayField` | Expression / variable | Required | Field used for display text and search matching. | `Title` |
| `valueField` | Expression / variable | Required | Field value saved for selected matched records. | `ListDataID` |
| `saveToField` | Expression / variable selector | Optional, recommended | Current form field or dashboard temp variable that stores the full combined JSON output. | `SupplierLookupJson` |
| `selectedItemsField` | Expression / variable selector | Optional | Current form field or dashboard temp variable that stores matched selected values only. | `SelectedSupplierIds` |
| `newItemsField` | Expression / variable selector | Optional | Current form field or dashboard temp variable that stores manual/free-text entries only. | `NewSupplierNames` |
| `multiSelect` | Expression / variable | Optional | Enables selecting more than one matched or manual item. | `true` |
| `allowManualEntry` | Expression / variable | Optional | Allows users to add typed text as a manual item. | `true` |
| `maxResults` | String | Optional | Maximum number of suggestions shown. | `8` |
| `placeholderText` | String | Optional | Placeholder shown in the search input. | `Search supplier` |
| `labelText` | String | Optional | Label shown above the control. | `Supplier` |
| `noResultText` | String | Optional | Message shown when no records match. | `No suppliers found` |
| `manualTagText` | String | Optional | Badge text shown on manual-entry chips. | `New` |
| `minSearchChars` | String | Optional | Minimum typed characters before search runs. | `2` |
| `debounceMs` | String | Optional | Delay before querying after the user types. | `300` |

## G. Detailed parameter explanation

### `dataListId`

The Yeeflow data list ID that the control searches.

Configure this with the source list that contains the selectable records, such as Supplier Master, Customer Master, Product Master, Employee List, or Asset Register.

This parameter uses the expression editor type, so it can come from a fixed value, form field, temp variable, complex variable, or expression. The final resolved value should be the target data list ID.

### `displayField`

The field shown to users in the suggestion list and selected chips. It is also the field used for keyword matching.

For many Yeeflow lists, `Title` is a valid display field. You can also use a business field such as Supplier Name, Customer Name, Product Name, Employee Name, or Asset Name.

This parameter supports expression-editor values. If an expression returns an object, the template attempts to use common keys such as `value`, `key`, `fieldId`, `name`, or `label`.

### `valueField`

The field saved as the selected value for matched records.

Use a stable identifier whenever possible. Common choices are:

- `ListDataID`
- supplier code
- customer code
- product ID
- employee ID
- asset number

Do not use display text here unless the display text is also the intended saved value. The matched-only output saves this value, not the display text.

### `saveToField`

The current form field used to store the full combined JSON result.

This output includes all selected matched records and manual entries. It is useful when later steps need both display text and structured source information.

Recommended field type: multiline text, JSON/text, or another text field that can store JSON.

Configure this by selecting the target field or dashboard temp variable from the selector. The template captures the selected writable target during `requiredFields(params)`, because Yeeflow may later pass only the variable's current value into `context.params` during Preview/runtime.

Example saved value:

```json
[
  {
    "display": "Partner A",
    "value": "2041029741761015809",
    "isManual": false,
    "source": "selected"
  },
  {
    "display": "custom supplier x",
    "value": "custom supplier x",
    "isManual": true,
    "source": "manual"
  }
]
```

### `selectedItemsField`

The current form field used to store matched selected values only.

Manual entries are not saved here. This field is useful for workflow logic, integration, reporting, or downstream automation that only needs selected source-list IDs/codes.

Example saved value:

```json
["2041029741761015809", "2041029741761015810"]
```

Configure this by selecting the target field or dashboard temp variable from the selector. Manual entries are never saved into this field.

### `newItemsField`

The current form field used to store manual/free-text entries only.

Matched selected records are not saved here. This is useful when the process needs to review or create new master-data records later.

Example saved value:

```json
["abc", "custom supplier x"]
```

Configure this by selecting the target field or dashboard temp variable from the selector. Matched selected records are never saved into this field.

### `multiSelect`

Controls whether users can select multiple items.

Accepted values include:

- `true`
- `false`
- expression returning a boolean
- expression returning an object with a boolean-like `value`, `key`, `checked`, `selected`, or `label`

Use `true` for product lists, email-style selections, multiple assets, or multiple departments. Use `false` when the form should only have one selected supplier, customer, contract, or employee.

### `allowManualEntry`

Controls whether users can add typed text as a manual item.

When enabled, users can type a value and press Enter or click the manual-entry row. Manual entries are visually marked with the configured `manualTagText`.

Use `true` when users may request a new supplier, customer, product, or partner. Use `false` when users must select an existing approved record.

### `maxResults`

Maximum number of matching suggestions shown in the dropdown.

Recommended values:

- `5` for compact forms
- `8` for most forms
- `10` or `15` for broader lookup scenarios

### `placeholderText`

Placeholder text shown in the input before the user types.

Use clear business wording, such as:

- `Search supplier`
- `Search customer`
- `Search product or SKU`
- `Search employee`

### `labelText`

Optional label shown above the control.

Use this when the custom code control itself needs a visible title. Leave it blank if the Yeeflow form already provides a field label near the control.

### `noResultText`

Message shown when no records match the typed keyword.

Examples:

- `No suppliers found`
- `No matching customers`
- `No products found`

### `manualTagText`

Small badge text shown on manual-entry chips.

Examples:

- `Manual`
- `New`
- `Custom`

### `minSearchChars`

Minimum number of characters the user must type before the control queries the data list.

Recommended values:

- `1` for small lists
- `2` for most master-data lists
- `3` for very large lists

### `debounceMs`

Delay in milliseconds before the search query runs after typing.

Recommended values:

- `260` for normal use
- `300` to `500` for slower or larger lists

Higher values reduce query frequency but make the search feel slightly slower.

## H. Step-by-step setup guide

1. Add a custom code control to the approval form or data list form.
2. Paste or upload the `smart-lookup-picker.tsx` code.
3. Open the input parameter settings.
4. Set `dataListId` to the Yeeflow data list you want to search.
5. Set `displayField` to the field users should see and search, such as `Title`.
6. Set `valueField` to the stable value to save, such as `ListDataID`.
7. Create or choose output fields on the current form, or temp variables on a dashboard page, for `saveToField`, `selectedItemsField`, and/or `newItemsField`.
8. Use the selector on those three output parameters to choose the writable field or temp variable.
9. Configure `multiSelect` as `true` or `false`.
10. Configure `allowManualEntry` as `true` or `false`.
11. Set user-facing text such as `placeholderText`, `labelText`, `noResultText`, and `manualTagText`.
12. Save the form or dashboard page.
13. Test search, select, remove, manual entry, and saved output fields.

## I. Result / expected output

After setup, users will see a clean lookup input with optional label text. As they type, the control searches the configured Yeeflow data list and shows matching records in a dropdown panel.

When users select records, selected values appear as chips. In multi-select mode, multiple chips can be added. In single-select mode, selecting a new item replaces the previous selected item.

If manual entry is enabled, users can add typed text as a manual chip. Manual chips look slightly different from matched data-list chips.

The control can save three outputs:

- full combined JSON result into `saveToField`
- matched selected values only into `selectedItemsField`
- manual/free-text values only into `newItemsField`

The saved values update immediately when users select or remove items.

## J. Real business examples

### Supplier picker for purchase requests

Users search the Supplier Master list and select the supplier for a purchase request. If the supplier is not found, manual entry can be enabled so users can enter a proposed new supplier name.

### Customer picker for service cases

Users search the Customer Master list and select the customer linked to a support case. Manual entry can be disabled to ensure only approved customer records are used.

### Product picker for internal requests

Users search a Product Master list and select one or more products. Multi-select can be enabled so several products can be attached to one request.

### Asset picker for maintenance forms

Users search an Asset Register and select the asset being repaired or inspected. The saved value can use `ListDataID` or a business asset number field.

## K. Notes / assumptions / limitations

- `dataListId`, `displayField`, and `valueField` must resolve to usable values at runtime.
- `displayField` can be `Title` if that is the correct display field in the source list.
- `valueField` should normally be `ListDataID` or a stable business ID/code field.
- The template first attempts a filtered data-list query. If that returns no usable rows, it attempts a limited broader query and performs local matching on the display field.
- Search behavior depends on Yeeflow list query permissions and the fields exposed by the selected data list.
- The control is optimized for approval forms and data list forms, and can also be used on dashboard pages with temp variables.
- On dashboard pages, use temp variables as output targets and select them directly in `saveToField`, `selectedItemsField`, and `newItemsField`. The template also falls back to the ordered `requiredFields` / `fieldsValues` keys when Yeeflow evaluates a selected variable into its current value.
- The output fields should be able to store JSON strings.
- Very large lists should use a higher `minSearchChars` value to reduce unnecessary queries.

## L. Testing checklist

- Search by a known display value.
- Select one matched item.
- If `multiSelect` is enabled, select multiple matched items.
- If `allowManualEntry` is enabled, type a new value and press Enter.
- Remove a selected chip.
- Confirm the input clears after selection.
- Confirm `saveToField` stores the combined JSON result.
- Confirm `selectedItemsField` stores only matched selected values.
- Confirm `newItemsField` stores only manual entries.
- Test a no-result search.
- Test readonly mode.
- Test an existing saved JSON value if editing an existing record.

## M. Troubleshooting

### No results appear when typing

Check that `dataListId` points to the correct data list and that the user has permission to read it. Also confirm `displayField` is the correct field ID/name, such as `Title`.

### Results appear but selected output is wrong

Check `valueField`. If you want to save the Yeeflow record ID, use `ListDataID`. If you want a business code, use the correct code field.

### Selected values do not save

Check that `saveToField`, `selectedItemsField`, and/or `newItemsField` point to valid current form fields. The fields should support text/JSON-style values.

On dashboard pages, choose the target temp variables directly in `saveToField`, `selectedItemsField`, and `newItemsField`. The template uses `requiredFields(params)` and the ordered `fieldsValues` keys to preserve those selected target names before Yeeflow evaluates them into current values during Preview/runtime.

### Manual entry does not work

Confirm `allowManualEntry` resolves to `true`. If it is coming from an expression, verify the expression returns a boolean or a clear true-like value.

### Only one item can be selected

Confirm `multiSelect` resolves to `true`. If it is `false` or blank, the control behaves as single-select.

### The control says lookup configuration is incomplete

At least `dataListId`, `displayField`, and `valueField` must be configured and resolve to non-empty values.

### Search feels slow

Increase `debounceMs` only if the source list is slow or large. For better perceived speed, keep `debounceMs` around `260` to `300` and set `minSearchChars` to `2` or `3`.
