@jigx/core-sdk 1.1.0 → 1.2.0-rc

package/docs/dropdown-fields.md

@@ -0,0 +1,879 @@
+## Static Options
+
+Hardcode options directly:
+
+```typescript
+step.addDropdown({
+ name: 'priority',
+ label: 'Priority Level',
+ data: [
+  { label: 'High', value: 'high', icon: 'alert-triangle' },
+  { label: 'Medium', value: 'medium', icon: 'alert-circle' },
+  { label: 'Low', value: 'low', icon: 'information-circle' },
+ ],
+})
+```
+
+Static options support one visual element: `icon`, `image`, or `avatar`.
+
+## Icons in Options
+
+Both dropdown and choice-field support icons using icon name strings:
+
+```typescript
+const options = [
+  { label: 'High', value: 'high', icon: 'alert-triangle' },
+  { label: 'Low', value: 'low', icon: 'information-circle' }
+]
+```
+
+Icon names are validated at build time. Use `mcp__jigx_common__search_sdk_icons` to find valid names.
+
+## Dynamic Datasource
+
+For database-backed data, create a datasource then reference it:
+
+```typescript
+// Create datasource
+const categoriesData = step
+ .addDatasource({ provider: 'dynamic', datasourceId: 'categories-ds' })
+ .table('default/categories')
+ .query(
+  "SELECT id AS value, json_extract(data, '$.label') AS label FROM [default/categories]",
+ )
+// Reference in dropdown
+step.addDropdown({
+ name: 'category',
+ label: 'Category',
+ data: categoriesData,
+})
+```
+
+**Provider options:**
+
+- `'dynamic'` - Cloud-synced, offline-first, auto-registered (recommended)
+- `'local'` - Device-only storage
+
+**Required columns:**
+
+- `id AS value` - identifier
+- `json_extract(data, '$.label') AS label` - display text
+- Optional: `json_extract(data, '$.icon') AS icon`
+
+**Document schema:** Tables have `id` and `data` columns. Use `json_extract(data, '$.field')` to access fields.
+
+### Value matching rule
+
+For datasource-backed dropdowns, the dropdown `value` must come from a concrete top-level field on the datasource row so Jigx can match the selected value back to the datasource item.
+
+Preferred pattern:
+
+```typescript
+screen.addDatasource
+  .sqlite({ datasourceId: 'customers', provider: 'local' })
+  .entity('Customers')
+  .query(`
+    SELECT id,
+           data,
+           json_extract(data, '$.CustomerID.value') as CustomerID,
+           json_extract(data, '$.CustomerName.value') as CustomerName
+    FROM [Customers]
+  `)
+  .jsonProperties('data')
+
+const customerDropdown = form.addControl.dropdown({
+  instanceId: 'Customer',
+  label: 'Customer',
+  data: '=@ctx.datasources.customers',
+})
+
+customerDropdown.addControl
+  .item()
+  .title('=@ctx.current.item.CustomerID')
+  .description('=@ctx.current.item.CustomerName')
+  .value('=@ctx.current.item.CustomerID')
+```
+
+Do not rely on nested `data.*` fields alone for dropdown matching when a stable selected value is required.
+
+### Sort by key, describe with name
+
+For Acumatica lookup dropdowns, sort by the business key users actually recognize first:
+
+- `CustomerID`
+- `LocationID`
+- `ProjectID`
+- `InventoryID`
+- `WarehouseID`
+- similar code/key fields
+
+Then show the human-readable label in `description(...)` when it exists.
+
+Preferred pattern:
+
+```typescript
+.query(`
+  SELECT id,
+         data,
+         json_extract(data, '$.LocationID.value') as LocationID,
+         json_extract(data, '$.LocationName.value') as LocationName
+  FROM [CustomerLocations]
+  ORDER BY json_extract(data, '$.LocationID.value')
+`)
+
+locationDropdown.addControl
+  .item()
+  .title('=@ctx.current.item.LocationID')
+  .description('=@ctx.current.item.LocationName')
+  .value('=@ctx.current.item.LocationID')
+```
+
+### Valid-combination matrix dropdowns
+
+When dropdown choices must be constrained by earlier selections, use a compact support table with one row per valid terminal item/configuration. Store stable top-level fields for every selectable attribute and the final external key.
+
+For small or manually maintained matrices, Dynamic Data is fine. For large matrices, prefer a REST-backed initial sync into a local SQLite table. Keep the row shape identical between the REST response and the Dynamic Data shape so the app can switch sources without rewriting dropdown queries.
+
+Recommended support-table shape:
+
+- `id`: deterministic row id, short enough for Dynamic Data.
+- `chainId`: manufacturer/configuration chain, for example `AMARR`, `CHI`, `CLOPAY`, `WAYNEDALTON`.
+- Optional external key fields such as `InventoryID`, if the app needs the exact external record id at runtime. If the app can construct the output code from validated selections, omit external keys to keep the support table smaller.
+- Attribute columns using the exact Acumatica attribute IDs and case, for example `SIZE`, `MODSER`, `COLORAM`, `PANELDES`, `GLASSTYPE`, `WNDOWOPTAM`, `TRACK`, `SPR`.
+- Optional metadata such as `Description`, `ItemClass`, `ItemStatus`, `selectionKey`.
+
+For a Dynamic Data matrix, register the support table in `database.ts` and add an app-scoped dynamic datasource so local SQL datasources can join/query it offline:
+
+```typescript
+// common.ts
+DOOR_MATRIX_ITEMS: { TABLE: 'doorMatrixItems', FQN: 'default/doorMatrixItems' }
+
+// database.ts
+app.addDatabase.default.table(ENTITY.DOOR_MATRIX_ITEMS.TABLE)
+
+// datasources.ts
+app.addDatasource
+  .sqlite({ datasourceId: 'data-register-door-matrix-items', provider: 'dynamic' })
+  .entity(ENTITY.DOOR_MATRIX_ITEMS.FQN)
+  .query(`SELECT id, data FROM [${ENTITY.DOOR_MATRIX_ITEMS.FQN}]`)
+  .jsonProperties('data')
+```
+
+For large support tables, seed Dynamic Data through the Data API bulk merge endpoint instead of one row at a time. The accepted request is `PATCH /v2.0/data/organizations/{organizationId}/solutions/{solutionId}/databases/default/tables/{tableId}/rows` with a body keyed by row id, where each value wraps the row content:
+
+```json
+{
+  "1": {
+    "content": {
+      "chainId": "AMARR",
+      "v1": "10X10",
+      "v2": "HE3000"
+    }
+  }
+}
+```
+
+Keep batches under the API validation limit. In practice, batches of 250 rows are a safe default for large matrix imports. The row id should stay outside `content`; duplicate imports are safe because the endpoint merges by row id.
+
+For a REST-backed matrix, define the matrix entity as a local table, expose an endpoint with `$top` and `$skip`, and use a REST function with continuation:
+
+```yaml
+provider: DATA_PROVIDER_REST
+method: GET
+url: https://{matrixApiURL}/matrix/doorMatrixItems
+useLocalCall: true
+
+parameters:
+  accessToken:
+    location: header
+    type: jigx
+    value: jigx
+    required: true
+  matrixApiURL:
+    location: path
+    type: string
+    required: true
+  $top:
+    location: query
+    type: number
+    value: 5000
+    required: true
+  $skip:
+    location: query
+    type: number
+    value: 0
+    required: true
+```
+
+The backend should validate the Jigx token before returning data, then return rows in the same shape the app expects locally:
+
+```json
+{
+  "top": 5000,
+  "skip": 0,
+  "value": [
+    {
+      "id": "1",
+      "chainId": "AMARR",
+      "v1": "10X10",
+      "v2": "HE3000",
+      "createdDateAndTime": "2026-05-09T12:00:00.000Z"
+    }
+  ]
+}
+```
+
+Use a `syncEntities().rest().entityWithFunction(...)` action during initial sync to save those records into the local table. Do not prefix the local table with `default/`; query it as `[doorMatrixItems]`.
+
+For each dependent dropdown, return normal attribute values when strict validation is off and matrix-filtered values when strict validation is on. The selected value still needs to be a concrete top-level field returned by the datasource, usually `valueID`.
+
+If source attribute values are temporarily wrong but the generated code must use corrected values, do not hard-code corrections into every dropdown or save action. Add a small Dynamic Data override table, for example `default/attributeValueOverrides`, with `attributeID`, `sourceValueID`, and `outputValueID`. If an attribute is shared by multiple manufacturers or chains, add a scope field such as `chainId` and apply overrides only for that chain; otherwise a correction for one manufacturer can silently change another manufacturer's generated code. Join or scalar-lookup that table inside the dropdown datasource so both unrestricted AttributeDetails rows and strict matrix rows expose the same corrected `valueID`. Apply the same corrected expression in every matrix filter and final matrix validation query, otherwise downstream dropdowns will compare corrected saved values to uncorrected matrix rows and return no results.
+
+```sql
+SELECT id, valueID, description, sortOrder
+FROM (
+  SELECT id,
+         json_extract(data, '$.valueID') as valueID,
+         json_extract(data, '$.description') as description,
+         json_extract(data, '$.sortOrder') as sortOrder
+  FROM [AttributeDetails]
+  WHERE @strict != '1'
+    AND json_extract(data, '$.attributeID') = 'MODSER'
+
+  UNION ALL
+
+  SELECT 'MODSER:' || option.valueID as id,
+         option.valueID as valueID,
+         COALESCE(NULLIF(json_extract(ad.data, '$.description'), ''), option.valueID) as description,
+         json_extract(ad.data, '$.sortOrder') as sortOrder
+  FROM (
+    SELECT DISTINCT json_extract(m.data, '$.MODSER') as valueID
+    FROM [doorMatrixItems] m
+    WHERE @strict = '1'
+      AND json_extract(m.data, '$.chainId') = @chainId
+      AND json_extract(m.data, '$.SIZE') = @size
+      AND COALESCE(NULLIF(json_extract(m.data, '$.MODSER'), ''), '') != ''
+  ) option
+  LEFT JOIN [AttributeDetails] ad
+    ON json_extract(ad.data, '$.attributeID') = 'MODSER'
+   AND json_extract(ad.data, '$.valueID') = option.valueID
+)
+ORDER BY LOWER(COALESCE(NULLIF(description, ''), valueID)), LOWER(valueID)
+```
+
+When strict validation is enabled, each dropdown should filter its datasource by the earlier selected fields. Disable the save action unless a terminal matrix datasource confirms that the completed selection has at least one valid match. If the output code is truly deterministic from the exact selected code segments, construct it from the selected values instead of storing every external id in the support table.
+
+If the external identifier can include fixed manufacturer prefixes, omitted segments, legacy aliases, corrected segment values, or any other value that is not exactly represented by the visible dropdown selections, include the resolved external identifier on the terminal matrix row and use that value for strict-mode save. Dropdown overrides can make display and filtering values consistent, but the final strict-mode payload should still use the matrix-resolved identifier to avoid drifting from the authoritative external system.
+
+Fields that are optional in unrestricted mode may still be required in strict mode when the matrix needs them to identify a valid combination. In that case, drive `isRequired` and downstream disable rules from the strict-mode flag, not from a hard-coded required setting.
+
+Large valid-combination tables should create SQLite expression indexes after the initial data sync. Use an `action.execute-sql` step at the end of the global initial-sync action and index the JSON fields used by matrix dropdown filters, for example `(json_extract(data, '$.chainId'), json_extract(data, '$.v1'), json_extract(data, '$.v2'))`. Also index lookup tables by `(attributeID, valueID)` and any override table by `(attributeID, sourceValueID)`. Keep the index action idempotent with `CREATE INDEX IF NOT EXISTS`.
+
+### Datasource Reference Methods
+
+Use `ds.ref` and `ds.getFieldRef()` to generate runtime references for datasource fields. Works for any field that needs datasource values - not just dropdowns:
+
+```typescript
+const employeesDs = step
+ .addDatasource({ provider: 'dynamic', datasourceId: 'employees-ds' })
+ .table('default/employees')
+ .query(
+  "SELECT id AS value, json_extract(data, '$.name') AS label, json_extract(data, '$.email') AS email FROM [default/employees]",
+ )
+// ds.ref returns base datasource reference: '@ctx.datasources.employees-ds'
+// ds.getFieldRef('email') returns field reference: '@ctx.datasources.employees-ds.email'
+capturedRef = employeesDs.ref
+capturedFieldRef = employeesDs.getFieldRef('email')
+step.addDropdown({
+ name: 'employee',
+ label: 'Employee',
+ data: employeesDs,
+})
+// Use getFieldRef to reference datasource fields in expressions
+step.addText({
+ name: 'emailDisplay',
+ label: 'Selected Email',
+ value: new JsonataBuilder('$email', {
+  email: employeesDs.getFieldRef('email'),
+ }),
+ isDisabled: true,
+})
+```
+
+| Method | Use Case | Returns |
+| --- | --- | --- |
+| `ds.ref` | Reference entire datasource row | `@ctx.datasources.my-ds` |
+| `ds.getFieldRef('field')` | Reference specific field | `@ctx.datasources.my-ds.field` |
+| `ds.getFieldRef('a.b')` | Nested field paths | `@ctx.datasources.my-ds.a.b` |
+
+**Prefilling multiple fields from datasource:**
+
+```typescript
+// CORRECT: Use ds.ref for entire row, access fields in Jsonata
+step.addText({
+  name: 'firstName',
+  label: 'First Name',
+  value: new JsonataBuilder('$data.firstName', { data: contactDs.ref }),
+})
+
+// WRONG: Do NOT use getFieldRef with empty string
+// value: new JsonataBuilder('$data.firstName', { data: contactDs.getFieldRef('') })
+```
+
+**Ref:** `./external-data-packages.md` for full employee contact prefill example
+
+## Searchable Dropdowns
+
+Enable real-time filtering as users type. **Searchable dropdowns require 3 steps** — setting `isSearchable: true` alone only shows a search bar UI, it does NOT filter. You MUST also: (1) add `@searchText IS NULL OR @searchText = '' OR ... LIKE '%' || @searchText || '%'` to the SQL WHERE clause, and (2) call `datasource.addQueryParameter('searchText', new JsonataBuilder('$s', { s: dropdown.state.searchText }))` after creating the dropdown.
+
+**When to use:**
+
+- Large datasets (100+ items)
+- User needs to find specific items quickly
+- Remote/synced data where client-side filtering is insufficient
+
+### Basic Pattern
+
+```typescript
+const vendorData = step
+ .addDatasource({ provider: 'dynamic', datasourceId: 'vendor-datasource' })
+ .table('default/vendors').query(`
+  SELECT
+   id AS value,
+   json_extract(data, '$.VendorName') AS label
+  FROM [default/vendors]
+  WHERE @searchText IS NULL OR @searchText = ''
+   OR json_extract(data, '$.VendorName') LIKE '%' || @searchText || '%'
+   OR json_extract(data, '$.VendorCode') LIKE '%' || @searchText || '%'
+ `)
+// Create dropdown with isSearchable, then bind its searchText state to query parameter
+const vendor = step.addDropdown({
+ name: 'vendor',
+ label: 'Select Vendor',
+ data: vendorData,
+ isSearchable: true,
+})
+// Use dropdown.state.searchText to get the expression
+vendorData.addQueryParameter(
+ 'searchText',
+ new JsonataBuilder('$s', { s: vendor.state.searchText }),
+)
+```
+
+**Key points:**
+
+- Set `isSearchable: true` on the dropdown
+- SQL query uses `@searchText` parameter with NULL/empty check
+- Create dropdown first, then bind `dropdown.state.searchText` to query parameter
+- Use `LIKE '%' || @searchText || '%'` for partial matching
+- Search multiple fields with `OR` conditions
+
+### Choosing Search Fields
+
+Search across 4-5 fields for best user experience. Always include basic identifiers (id, name/label), then add fields users might search by — email, phone, city, code, etc.
+
+Pick fields based on the datasource schema. For example, a Customers table might search:
+
+```sql
+WHERE @searchText IS NULL OR @searchText = ''
+  OR json_extract(data, '$.CustomerName.value') LIKE '%' || @searchText || '%'
+  OR json_extract(data, '$.CustomerID.value') LIKE '%' || @searchText || '%'
+  OR json_extract(data, '$.Email.value') LIKE '%' || @searchText || '%'
+  OR json_extract(data, '$.City.value') LIKE '%' || @searchText || '%'
+```
+
+**Guidelines:**
+
+- Default: always search `id` / `name` (or equivalent label field)
+- Ask the user which additional fields to include if not specified in prompt
+- Verify field paths exist in the datasource schema before adding to WHERE clause
+- More search fields = better discoverability, minimal performance impact on SQLite
+
+### Multiple Filters with searchText
+
+Combine searchText with additional filter parameters:
+
+```typescript
+// Category filter (static dropdown)
+const category = step.addDropdown({
+ name: 'category',
+ label: 'Category',
+ data: [
+  { label: 'Electronics', value: 'electronics' },
+  { label: 'Clothing', value: 'clothing' },
+  { label: 'All', value: '' },
+ ],
+})
+const productData = step
+ .addDatasource({ provider: 'dynamic', datasourceId: 'product-datasource' })
+ .table('default/products').query(`
+  SELECT
+   id AS value,
+   json_extract(data, '$.name') AS label
+  FROM [default/products]
+  WHERE (@searchText IS NULL OR @searchText = ''
+     OR json_extract(data, '$.name') LIKE '%' || @searchText || '%')
+   AND (@category IS NULL OR @category = ''
+     OR json_extract(data, '$.category') = @category)
+ `)
+// Create dropdown with isSearchable, then bind parameters
+const product = step.addDropdown({
+ name: 'product',
+ label: 'Search Products',
+ data: productData,
+ isSearchable: true,
+})
+// Bind searchText using dropdown.state.searchText
+productData.addQueryParameter(
+ 'searchText',
+ new JsonataBuilder('$s', { s: product.state.searchText }),
+)
+// Bind category filter parameter using JsonataBuilder
+productData.addQueryParameter(
+ 'category',
+ new JsonataBuilder('$cat', { cat: category.state.value }),
+)
+```
+
+**Filter parameter patterns:**
+
+- searchText: Use `dropdown.state.searchText` property
+- Other filters: Use `JsonataBuilder` for field references
+
+### SQL Query Pattern
+
+Always include NULL/empty checks to show all results when search is empty:
+
+```sql
+WHERE (@searchText IS NULL OR @searchText = ''
+       OR json_extract(data, '$.name') LIKE '%' || @searchText || '%')
+  AND (@category IS NULL OR @category = ''
+       OR json_extract(data, '$.category') = @category)
+```
+
+**Pattern elements:**
+
+| Element | Purpose |
+| --- | --- |
+| `@searchText IS NULL` | Handle null parameter |
+| `@searchText = ''` | Handle empty string |
+| `LIKE '%' \|\| @searchText \|\| '%'` | Partial match |
+| `json_extract(data, '$.field')` | Access JSON fields |
+
+### With External Package Data
+
+Searchable dropdown with Acumatica or other package data:
+
+```typescript
+// Create package data for Acumatica customers with search filter
+const packageData = step.addPackageData({ package: 'my-data-package' })
+packageData.addExecuteAction({ action: 'act-sync-customers' })
+const customers = packageData.addDatasource({
+ datasourceId: 'customers-ds',
+ provider: 'local',
+})
+customers.table('Customers')
+// Query with searchText filter for customer name and ID
+customers.query(`
+ SELECT
+  json_extract(data, '$.CustomerID.value') AS value,
+  json_extract(data, '$.CustomerName.value') AS label,
+  json_extract(data, '$.Email.value') AS email
+ FROM ${customers.fullTableName}
+ WHERE @searchText IS NULL OR @searchText = ''
+  OR json_extract(data, '$.CustomerName.value') LIKE '%' || @searchText || '%'
+  OR json_extract(data, '$.CustomerID.value') LIKE '%' || @searchText || '%'
+`)
+// Create searchable dropdown, then bind searchText
+const customerField = step.addDropdown({
+ name: 'customer',
+ label: 'Search Customer',
+ data: packageData,
+ isSearchable: true,
+})
+// Bind dropdown's searchText state to query parameter
+customers.addQueryParameter(
+ 'searchText',
+ new JsonataBuilder('$s', { s: customerField.state.searchText }),
+)
+```
+
+## Lookup Tables
+
+Dynamic enum tables use the naming pattern `lookups-{name}`. Examples: `lookups-priorities`, `lookups-categories`, `lookups-departments`. The `lookups-` prefix distinguishes enum tables from app data tables. In SDK code, the table reference is `default/lookups-{name}`.
+
+Tables are created automatically on first deploy — no manual setup required.
+
+### Row Structure
+
+Each row uses a human-readable slug as `rid` (not a GUID), with `label`, `sort`, and optional visual fields in content:
+
+```json
+{ "rid": "high", "content": { "label": "High", "sort": 1, "icon": "arrow-up" } }
+```
+
+- `rid`: slugified label — lowercase letters, numbers, and hyphens only (regex `^[a-z0-9-]+$`); use hyphens for spaces. `"High Priority"` → `high-priority`, `"In Progress"` → `in-progress`
+- `label` (required): display text
+- `sort` (required): sequential integer (1, 2, 3...) controlling display order
+- `icon`, `image`, `avatar` (optional): visual metadata
+
+### SQL Query for Lookups
+
+```sql
+SELECT id AS value, json_extract(data, '$.label') AS label FROM [default/lookups-{name}] ORDER BY json_extract(data, '$.sort')
+```
+
+### Seed Data Manifest
+
+Initial lookup data is defined in `seed-data.json`, written alongside `app.ts`. After first deploy, the seed step populates tables automatically. Subsequent deploys skip seeding if the table already has rows.
+
+```json
+{
+  "tables": [
+    {
+      "tableId": "lookups-categories",
+      "rows": [
+        { "rid": "electronics", "content": { "label": "Electronics", "sort": 1, "icon": "shopping-cart" } },
+        { "rid": "clothing", "content": { "label": "Clothing", "sort": 2, "icon": "shirt" } },
+        { "rid": "home-garden", "content": { "label": "Home & Garden", "sort": 3, "icon": "house" } }
+      ]
+    }
+  ]
+}
+```
+
+Each entry in `tables` has a `tableId` (e.g., `lookups-categories` — without the `default/` prefix) and an array of `rows` with `rid` and `content`.
+
+If multiple dynamic enums exist, include all tables in a single `seed-data.json`. On resume/rebuild, overwrite the manifest entirely — it always reflects the current build intent.
+
+## ArrayField Data Source
+
+Populate dropdown from arrayField items collected in another step:
+
+```typescript
+// Step 1: Collect team members
+const step1 = form.addStep({ instanceId: 'team' }, (step) => {
+ const members = step.addArrayField({
+  name: 'members',
+  label: 'Team Members',
+ })
+ members.with({
+  title: new JsonataBuilder('$n', { n: members.getCurrentItemRef('name') }),
+ })
+ members.addText({ name: 'name', label: 'Name' })
+ members.addEmail({ name: 'email', label: 'Email' })
+})
+step1.with({ icon: 'multiple-neutral-2', title: 'Team Members' })
+// Step 2: Select from collected members
+form.addStep({ instanceId: 'lead', icon: 'single-neutral' }, (step) => {
+ step.addDropdown({
+  name: 'teamLead',
+  label: 'Select Team Lead',
+  data: step1.data.getArrayFieldData('members'),
+ })
+})
+```
+
+**Default mapping:**
+
+| ArrayField Property | Dropdown Property |
+| --- | --- |
+| `id` (auto-generated UUID) | `value` |
+| `item_title` (from arrayField.title) | `label` |
+
+**Custom mapping:**
+
+```typescript
+const step1 = form.addStep({ instanceId: 'team' }, (step) => {
+ const members = step.addArrayField({
+  name: 'members',
+  label: 'Team Members',
+  title: 'Member',
+ })
+ members.addText({ name: 'name', label: 'Name' })
+ members.addEmail({ name: 'email', label: 'Email' })
+})
+step1.with({ icon: 'multiple-neutral-2', title: 'Team Members' })
+form.addStep({ instanceId: 'lead', icon: 'single-neutral' }, (step) => {
+ step.addDropdown({
+  name: 'teamLead',
+  label: 'Select Team Lead',
+  data: step1.data.getArrayFieldData('members', {
+   valueKey: 'email', // Use email as value
+   labelKey: 'name', // Use name as label
+  }),
+ })
+})
+```
+
+**Ref:** `./cross-step-data.md` for more on `getArrayFieldData()`
+
+## Package Datasource
+
+For data from external systems (ERP, CRM), use `addPackageData()` to sync and query package tables:
+
+```typescript
+const packageData = step.addPackageData({ package: 'my-data-package' })
+packageData.addExecuteAction({ action: 'act-sync-customers' })
+const ds = packageData.addDatasource({
+ datasourceId: 'customers-ds',
+ provider: 'local',
+})
+ds.table('Customers')
+ds.query(`
+ SELECT id AS value,
+  COALESCE(json_extract(data, '$.CustomerName.value'), json_extract(data, '$.CustomerID.value')) AS label
+ FROM ${ds.fullTableName}
+`)
+step.addDropdown({ name: 'customer', label: 'Customer', data: packageData })
+```
+
+**Ref:** `./external-data-packages.md` for available tables, schemas, and sync actions
+
+## Data Paths (labelDataPath / valueDataPath)
+
+Specify JSON paths to label and value fields in datasource data.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `labelDataPath` | `'label'` | Path to display text |
+| `valueDataPath` | `'value'` | Path to identifier |
+
+```typescript
+// Default behavior - uses 'label' and 'value' paths
+step.addDropdown({
+  name: 'category',
+  label: 'Category',
+  data: categoriesData  // labelDataPath: 'label', valueDataPath: 'value'
+})
+
+// Custom paths for external datasources with different schema
+step.addDropdown({
+  name: 'customer',
+  label: 'Customer',
+  data: customers,
+  labelDataPath: 'data.CustomerName.value',
+  valueDataPath: 'id'
+})
+```
+
+**When to use:**
+- Package data with custom schemas (check schema files in `external-data-packages`)
+- Any datasource where fields aren't named `label` / `value`
+
+## Multiple Selection
+
+Enable multi-select with `isMultiple: true`:
+
+```typescript
+step.addDropdown({
+ name: 'skills',
+ label: 'Technical Skills',
+ isMultiple: true,
+ data: [
+  { label: 'JavaScript', value: 'javascript', icon: 'java-script-logo' },
+  { label: 'TypeScript', value: 'typescript', icon: 'type-script-logo' },
+  { label: 'React', value: 'react', icon: 'react-native-logo' },
+  { label: 'Node.js', value: 'nodejs', icon: 'server' },
+ ],
+})
+```
+
+## Accessing Selected Dropdown Data
+
+Dropdown fields expose two state properties:
+
+| Property | Returns | Use Case |
+| --- | --- | --- |
+| `state.value` | `string \| number` | Selected value/id for conditions, business logic |
+| `state.selected` | Full object | Access label, icon, or nested properties |
+
+### state.value vs state.selected
+
+```typescript
+const statusField = step.addDropdown({
+ name: 'status',
+ label: 'Status',
+ data: [
+  { label: 'Active', value: 'active', icon: 'check-2' },
+  { label: 'Inactive', value: 'inactive', icon: 'close' },
+ ],
+})
+// state.value → "active" (just the value)
+// Use for conditional logic based on selected value
+step.addText({
+ name: 'statusNote',
+ label: 'Status Note',
+ isVisible: new JsonataBuilder('$status = "active"', {
+  status: statusField.state.value,
+ }),
+})
+// state.selected → { label: "Active", value: "active", icon: "check-2" }
+// Use to access other properties like label or icon
+step.addText({
+ name: 'statusLabel',
+ label: 'Selected Status Label',
+ value: new JsonataBuilder('$selected.label', {
+  selected: statusField.state.selected,
+ }),
+ isDisabled: true,
+})
+```
+
+### Accessing External Package Data
+
+With external datasources, use `state.selected` to access nested properties:
+
+```typescript
+// Create package data for external package (e.g., Acumatica ERP customers)
+const packageData = step.addPackageData({ package: 'my-data-package' })
+packageData.addExecuteAction({ action: 'act-sync-customers' })
+const customers = packageData.addDatasource({
+ datasourceId: 'customers-ds',
+ provider: 'local',
+})
+customers.table('Customers')
+// Query selects value, label, and extra fields for state.selected access
+customers.query(`
+ SELECT
+  json_extract(data, '$.CustomerID.value') AS value,
+  json_extract(data, '$.CustomerName.value') AS label,
+  json_extract(data, '$.Email.value') AS email
+ FROM ${customers.fullTableName}
+`)
+// Customer dropdown
+const customerField = step.addDropdown({
+ name: 'customer',
+ label: 'Customer',
+ data: packageData,
+})
+// Derived read-only field showing customer email
+// Uses state.selected to access the full selected object
+step.addText({
+ name: 'customerEmail',
+ label: 'Customer Email',
+ value: new JsonataBuilder('$customer.email', {
+  customer: customerField.state.selected,
+ }),
+ isDisabled: true,
+})
+```
+
+For derived fields in forms, prefer binding the target field directly to the dropdown's `state.selected.<Field>` instead of copying values through jig state with `action.set-jig-state`.
+
+Example:
+
+```typescript
+form.addControl.textField({
+  instanceId: 'UnitPrice',
+  label: 'Unit Price',
+  value: '=@ctx.components.InventoryID.state.selected.UnitPrice',
+})
+```
+
+This keeps the form reactive to the currently selected dropdown row and avoids extra state propagation layers.
+
+## Displaying Dropdown Labels
+
+Dropdown fields store `value` (id) but often need to display `label` (human-readable text).
+
+### getDropdownLabel() - Cross-Step Label Access
+
+Access the persisted label for submission titles or cross-step display:
+
+```typescript
+const step1 = form.addStep({ instanceId: 'priority-step' }, (step) => {
+ step.addDropdown({
+  name: 'priority',
+  label: 'Priority',
+  data: [
+   { label: 'High', value: 'high' },
+   { label: 'Medium', value: 'medium' },
+   { label: 'Low', value: 'low' },
+  ],
+ })
+})
+step1.with({ title: 'Set Priority', icon: 'alert-triangle' })
+// Use getDropdownLabel() to show "High" instead of "high" in submissions
+form.with({
+ submissionItemTitle: new JsonataBuilder('$priority', {
+  priority: step1.data.getDropdownLabel('priority'),
+ }),
+})
+```
+
+| Method | Returns | Use Case |
+| --- | --- | --- |
+| `step.data.getFieldData('dropdown')` | `string \| number` (value) | Business logic, conditions |
+| `step.data.getDropdownLabel('dropdown')` | `string` or `string[]` | Display text, titles |
+
+### Multi-Select Labels with $join()
+
+For multi-select dropdowns, `getDropdownLabel()` returns an array of strings:
+
+```typescript
+const step1 = form.addStep({ instanceId: 'tags-step' }, (step) => {
+ step.addDropdown({
+  name: 'tags',
+  label: 'Tags',
+  isMultiple: true,
+  data: [
+   { label: 'Urgent', value: 'urgent' },
+   { label: 'Bug', value: 'bug' },
+   { label: 'Feature', value: 'feature' },
+  ],
+ })
+})
+step1.with({ title: 'Select Tags', icon: 'tags' })
+// Multi-select: getDropdownLabel returns array of strings ["Urgent", "Bug"]
+// Use $join() to display as "Urgent, Bug"
+form.with({
+ submissionItemTitle: new JsonataBuilder('$join($tags?$tags:[], ", ")', {
+  tags: step1.data.getDropdownLabel('tags'),
+ }),
+})
+```
+
+### getCurrentItemLabelRef() - ArrayField Context
+
+Inside arrayField, use `getCurrentItemLabelRef()` for dropdown labels:
+
+```typescript
+const items = step.addArrayField({
+ name: 'orderItems',
+ label: 'Order Items',
+})
+// Display dropdown LABEL (e.g., "Electronics") in item title
+// instead of dropdown VALUE (e.g., "electronics")
+items.with({
+ title: new JsonataBuilder('$product & " - " & $categoryLabel', {
+  product: items.getCurrentItemRef('productName'),
+  categoryLabel: items.getCurrentItemLabelRef('category'),
+ }),
+})
+items.addText({ name: 'productName', label: 'Product Name' })
+items.addDropdown({
+ name: 'category',
+ label: 'Category',
+ data: [
+  { label: 'Electronics', value: 'electronics' },
+  { label: 'Clothing', value: 'clothing' },
+  { label: 'Home & Garden', value: 'home' },
+ ],
+})
+items.addNumber({ name: 'quantity', label: 'Quantity' })
+```
+
+**Ref:** `./cross-step-data.md` for more on data access patterns
+
+## Finding Examples
+
+Use MCP to search for patterns:
+
+```typescript
+// Search examples
+mcp__jigx_expert_sdk__search_expert_sdk_examples({ search: "dropdown datasource" })
+
+// Get specific example
+mcp__jigx_expert_sdk__get_expert_sdk_example({ id: "..." })
+```