# Hierarchical Selector

## Short Description

Hierarchical Selector - reusable Yeeflow tree selector for organization, category, geography, or location structures.

## Purpose / What This Is For

Lets users pick values from a tree built from a Yeeflow data list with ID, parent, and label fields.

## Supported Placement

Approval form; Data list form

## When To Use

Use this template when teams need a reusable Yeeflow control for org units, category trees, location structures, and product families.

## Recommended Defaults

Start with the required source/save parameters, keep labels concise, and test with a small data set before publishing.

## Input Parameters Overview

| Parameter | Type | Purpose |
| --- | --- | --- |
| `dataListId` | `variable` | Hierarchy source list. |
| `idField` | `variable` | Unique ID field. |
| `parentField` | `variable` | Parent ID field. |
| `labelField` | `variable` | Display label field. |
| `valueField` | `variable` | Saved value field. |
| `saveToField` | `variable` | Writable output field. |
| `multiSelect` | `variable` | Allow multiple selections. |
| `titleText` | `string` | Panel title. |
| `subtitleText` | `string` | Panel subtitle. |
| `maxItems` | `string` | Max loaded records. |
| `emptyText` | `string` | Empty text. |
| `filterExpression` | `variable` | Optional filter. |

## Detailed Parameter Explanation

Configure expression-editor parameters with Yeeflow fields, variables, temp variables, or static values as appropriate. Writable target parameters save output values and are resolved defensively at runtime. Plain text parameters control display labels and helper text.

## Step-By-Step Setup

1. Add a Custom Code control to the supported Yeeflow placement.
2. Paste the `hierarchical-selector.tsx` code file.
3. Configure required data source, field, and save-target parameters.
4. Configure labels, limits, and display options.
5. Preview with realistic records.
6. Confirm readonly, empty, and validation states.
7. Publish when behavior is correct.

## Result / Expected Output

A compact selectable hierarchy that saves selected IDs as JSON.

## Real Business Examples

- Procurement approval and vendor review.
- Case, request, or task management.
- Policy, compliance, and operational control checks.
- Department, location, product, or category-driven workflows.

## Notes / Assumptions / Limitations

- Runtime query behavior uses `yeeSDKClient.lists.queryItems(...)` where list data is needed.
- Expression-editor values are normalized from strings, booleans, objects, arrays, and variable selector values.
- Writable targets use defensive setter paths and a local `fieldsValues` fallback.
- Tenant-specific query filter shapes may require adjustment in `filterExpression`.

## Testing Checklist

- Required parameters configured.
- Empty state displays safely.
- Existing saved values initialize correctly when applicable.
- Save targets update as expected when applicable.
- Readonly mode prevents editing.
- Narrow layout remains readable.

## Troubleshooting

If data does not appear, verify list ID, field IDs, filter expression, and permissions. If saving does not work, confirm the target parameter was selected as a writable form field or variable and that the field exists on the form.
