@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/pattern-forms.md

@@ -0,0 +1,528 @@
+# Pattern: Forms (generic)
+
+Applies to **any** form — single-screen, tabbed, modal, wizard, detail-from-list.
+Tab-specific extras (cross-jig validation, propagating state via inputs) live in
+[pattern-tabs-form.md](pattern-tabs-form.md).
+
+## Required fields
+
+Always set `isRequired` explicitly on every field — `true` or `false`. Omitting it
+may render fields as required by default depending on type, which surprises users.
+
+```typescript
+form.addControl.textField({
+  instanceId: 'customerName',
+  label: 'Customer Name',
+  isRequired: true,
+})
+form.addControl.textField({
+  instanceId: 'addressLine2',
+  label: 'Address Line 2',
+  isRequired: false,
+})
+```
+
+## Form container
+
+Wrap fields in a form so `@ctx.components.<formId>.state.isValid` and `state.isDirty`
+are available for validation and discard-alert logic:
+
+```typescript
+const form = screen.addControl.form({
+  instanceId: 'contactInfo',
+  isDiscardChangesAlertEnabled: '=@ctx.jig.state.upload = true ? false:true',
+})
+```
+
+The `isDiscardChangesAlertEnabled` expression is the hook for suppressing the
+"Discard changes?" dialog during a save — see below.
+
+## Save button — `isDisabled`, never `when`
+
+**Rule:** Use `isDisabled` on the save button, not `when`.
+
+- `when` means "don't run the action if the condition is false". The button still
+  *looks* enabled, but tapping it does nothing. Users interpret this as a bug.
+- `isDisabled` makes the button visibly greyed out when the form is invalid —
+  users instantly see why they can't proceed.
+
+```typescript
+// WRONG — button looks enabled but silently unresponsive when invalid
+buttons.add.list({
+  title: 'Save',
+  when: '=@ctx.components.form.state.isValid',
+}).actions
+
+// RIGHT — button visibly disabled until form is valid
+buttons.add.list({
+  title: 'Save',
+  isDisabled: '=@ctx.components.form.state.isValid = true ? false:true',
+}).actions
+```
+
+`isDisabled` is a top-level property on any action builder (`ActionBaseInput`). The
+SDK transforms it to `style.isDisabled` in the output YAML — you don't write the
+nested `style` wrapper in TypeScript.
+
+Applies to `buttons.add.list({...})`, `buttons.add.executeEntity({...})`,
+`buttons.add.executeAction({...})`, `.swipeLeft()`, `.swipeRight()` — anywhere you
+have an action button.
+
+## Save action list — correct ordering
+
+For any form using the upload-state discard-alert pattern, the sequential save action
+list **must** be ordered:
+
+1. **`setScreenState({ upload: true })`** — suppress discard alert FIRST
+2. **Saves** (`executeEntity`, `executeEntities`) — do the work. Conditional `when`
+   on individual steps is fine (e.g., "only save signature if changed")
+3. **`resetScreenState({ keys: ['upload'] })`** — reset state BEFORE navigating
+4. **`goBack`** — LAST, standalone, never chained
+
+```typescript
+screen.with({ state: { upload: { initialValue: null } } })
+
+const form = screen.addControl.form({
+  instanceId: 'contactInfo',
+  isDiscardChangesAlertEnabled: '=@ctx.jig.state.upload = true ? false:true',
+})
+
+const saveActions = screen.bottomPanel().add.list({
+  concurrency: 'sequential',
+  title: 'Save Information',
+  isDisabled: '=@ctx.components.contactInfo.state.isValid = true ? false:true',
+}).actions
+
+// 1. Disable alert
+saveActions.setScreenState({ instanceId: 'set-upload', keys: { upload: true } })
+
+// 2. Saves (conditional `when` on individual steps is fine)
+saveActions
+  .executeEntity({ instanceId: 'save-info' })
+  .dynamicData('default/salesInfoAnswers', 'save')
+  .data({ /* ... */ })
+
+saveActions
+  .executeEntity({
+    instanceId: 'save-signature',
+    when: '=$exists(@ctx.datasources.signatures.data.signatureImage) = false or @ctx.datasources.signatures.data.signatureImage != @ctx.components.signature.state.value',
+    conversions: [{ property: 'signatureImage', from: 'local-uri', to: 'base64' }],
+  })
+  .dynamicData('default/formSignatures', 'save')
+  .data({ /* ... */ })
+
+// 3. Reset BEFORE goBack — jig state is unreachable after goBack
+saveActions.resetScreenState({ instanceId: 'reset-upload', keys: ['upload'] })
+
+// 4. goBack LAST, standalone
+saveActions.goBack({ instanceId: 'go-back' })
+```
+
+If the save keeps the user on the same screen instead of navigating away, keep the
+same first and third steps:
+
+1. `setScreenState({ upload: true })`
+2. saves
+3. `resetScreenState({ keys: ['upload'] })`
+
+In that variant there is no `goBack`, but you should still use the same `upload`
+state contract so discard warnings behave consistently.
+
+### Why the ordering matters
+
+**Rule 1 — `resetScreenState` before `goBack`:** Once `goBack` fires, the jig is gone
+from context. Any subsequent `setScreenState` / `resetScreenState` targeting that jig's
+state silently fails because the state object no longer exists. Always reset state
+*before* navigating away.
+
+**Rule 2 — `goBack` is standalone and last:** Never chain `.onSuccess.goBack()` to an
+earlier step, especially one with a `when` guard (e.g., a conditional signature save).
+If the guard is false the step is skipped entirely and its `onSuccess` never fires —
+the user gets stuck on the form with no feedback. This exact bug shipped in
+doorpro-door-quote on 2026-04-09 and confused us for a full session.
+
+**Rule 3 — Why the discard alert still works:** You might wonder: if `resetScreenState`
+fires before `goBack`, isn't the alert re-enabled at goBack time? It is — but the form
+is no longer "dirty" because component values match the just-saved datasource data. The
+form's dirty check compares current values against freshly saved values, not the
+original initial-render values. So the alert doesn't fire even though it's "enabled".
+The `upload=true` flag only needs to cover the window *during* the saves, not after.
+
+## Conditional signature / media save
+
+For image fields that are expensive to re-upload, guard the save with a `when` that
+only runs the write if the value actually changed:
+
+```typescript
+saveActions
+  .executeEntity({
+    instanceId: 'save-signature',
+    when: '=$exists(@ctx.datasources.signatures.data.signatureImage) = false or @ctx.datasources.signatures.data.signatureImage != @ctx.components.signature.state.value',
+    conversions: [{ property: 'signatureImage', from: 'local-uri', to: 'base64' }],
+  })
+  .dynamicData('default/formSignatures', 'save')
+  .data({ /* ... */ })
+```
+
+- `when` on the *step* is fine — it skips cleanly.
+- `when` on the *button* is bad — it hides the disabled state from the user.
+- `conversions` converts the field at save time. `local-uri` → `base64` produces a
+  base64 string suitable for embedding in `<img src="data:image/png;base64,...">` in
+  a PDF template. See [pattern-datasources.md](pattern-datasources.md#signature-and-media-storage--uri-vs-base64)
+  for the URI vs base64 trade-off.
+
+## Derived defaults must be visible before save
+
+If a lookup selection derives editable field values such as price, tax category, UOM,
+account, or address defaults, populate those values into visible field state when the
+selection changes. Do not only calculate them inside the final `.data(...)` save
+expression.
+
+If the user cannot see the derived values before tapping save, the UI and the saved
+record drift apart and debugging becomes harder. Preferred pattern:
+
+1. Use the lookup field's `onChange` to `setScreenState(...)` with the derived values.
+2. Bind the affected controls to those screen-state keys (with fallback to existing
+   datasource values when editing).
+3. Save from the same derived state so the visible form and persisted payload match.
+
+## Attribute-derived item codes
+
+When an external system constructs an item/inventory code from ordered attribute
+segments, do not build the code from display descriptions. Store both the
+human-readable field value and the segment/value ID needed by the external system.
+
+Use the specification-defined segment order, not the order fields happen to appear
+in the saved JSON. For Acumatica door item numbers, this means joining the selected
+attribute `valueID` fields with the documented separator, then showing the computed
+code in a read-only field before save:
+
+```typescript
+const doorCodeExpression =
+  '=($segments := [' +
+  [
+    '(@ctx.components.size.state.selected.valueID ? @ctx.components.size.state.selected.valueID : @ctx.datasources.doorDetails.data.sizeValueID)',
+    '(@ctx.components.modser.state.selected.valueID ? @ctx.components.modser.state.selected.valueID : @ctx.datasources.doorDetails.data.modserValueID)',
+    '(@ctx.components.coloram.state.selected.valueID ? @ctx.components.coloram.state.selected.valueID : @ctx.datasources.doorDetails.data.coloramValueID)',
+  ].join(', ') +
+  ']; $join($filter($segments, function($v) { $exists($v) and $string($v) != "" }), "-"))'
+
+section.addControl.textField({
+  instanceId: 'doorCode',
+  label: 'Door Code',
+  isRequired: false,
+  isDisabled: true,
+  value: doorCodeExpression,
+})
+```
+
+Save the same expression into the local row (for list/PDF display) and save each
+segment `valueID` separately so copies and edits do not depend on re-looking up the
+description later. Use the customer's required separator exactly. If the customer
+requires a compact code, join segments with `""` and do not pad spaces, even when an
+older draft specification mentioned separators or fixed-width padding.
+
+### Manufacturer-specific attribute chains
+
+When the attribute sequence changes by manufacturer or product family, do not force
+one generic form to handle all variants. Use a lightweight chooser/list screen first,
+then navigate to the manufacturer-specific builder for the selected chain. This keeps
+the save action, form validity, discard-warning state, and item-code construction in
+the same jig context.
+
+Preferred pattern:
+
+1. Create a chooser jig backed by a static or local datasource with `manufacturer`,
+   `title`, `description`, and `target` jig fields.
+2. Filter out gateway values whose downstream sequence is not yet specified.
+3. On manufacturer press, `go-to` the target manufacturer jig with the stable local
+   row id and line number as inputs/parameters.
+4. In each manufacturer jig, declare fields in the exact specification order.
+5. Put the save button on the same manufacturer jig as the form and use that form's
+   `state.isValid` for `isDisabled`.
+6. Store both display text and `valueID` for every attribute segment.
+7. Build the final item code from the specification order, not from object key order.
+8. If the customer temporarily removes a segment such as Template ID, remove it from
+   the visible form, required validation, saved payload, and code expression together.
+
+Avoid putting a parent save button above `component.jig`-hosted manufacturer forms.
+In runtime testing, embedded jig outputs were `null` in the wrapper action context,
+which caused valid forms to be treated as incomplete. Keeping the save action on the
+actual manufacturer jig avoids cross-jig validity and state propagation failures.
+
+For optional or conditional segments, keep the segment expression in the documented
+position and return an empty string only when the specification says the segment is
+not applicable. The join/filter step can then omit the blank segment without moving
+later segments out of order.
+
+### Copying quote/detail records
+
+When copying a quote or parent record, copy business fields and repeatable child
+details, but reset workflow/integration state:
+
+- Set a new parent id/opportunity id.
+- Set the copied quote date to `$now()` so it reflects the copy date.
+- Reset an order quote back to a non-order quote when only one order is allowed.
+- Clear generated artifacts such as `pdfFilePath`, `pdfGeneratedAt`, and `pdfStale`.
+- Do not copy signatures, form progress, or Acumatica submission/status rows.
+- Copy child line fields that define the quote, including attributes, generated
+  internal codes, line pricing, tax, and totals.
+- When copying a child line inside the same quote, assign a new child id, new line
+  number, and new display label, then mark the quote PDF stale.
+
+### Temporary local seeding for pending attributes
+
+If a customer has documented an attribute chain but has not yet loaded the future
+attributes into Acumatica, seed temporary local `Attributes` and `AttributeDetails`
+rows with `action.execute-sql` using `INSERT OR IGNORE`. Keep this seed isolated to
+the app lifecycle, mark it as temporary in code, and use the documented future
+attribute IDs so the UI and save payloads do not need to be renamed later.
+
+Do not seed over real customer data. Use stable ids such as `ATTRIBUTEID_VALUEID`,
+write JSON into the `data` column, and list the affected local entities in the
+`execute-sql` action so datasources refresh.
+
+### Add Spaces / padded segments
+
+When an attribute specification marks `Add Spaces = true`, pad that segment to the
+specified max character length before joining it into the item code. Apply padding to
+the segment value itself, not to the separator. A safe JSONata pattern is:
+
+```typescript
+const padded = '$substring($string($segment) & "                         ", 0, 11)'
+```
+
+Use the per-manufacturer max length from the specification. Shared attributes can
+have different max lengths in different chains, so do not centralize a single global
+length per attribute ID.
+
+## Global action for save logic
+
+Inline save action lists work, but they duplicate 40+ lines across every form that
+follows the same pattern. Extract to a global action when:
+
+- Multiple form screens share the same save flow (progress + data + signature)
+- You want to test the save logic in isolation
+- You want the save to complete reliably even if the user navigates mid-save
+
+### Why global actions are more robust
+
+Global actions run in **their own action context**. Parameters are **snapshotted at
+call time** and held for the duration of the action. In contrast, an inline action
+list on a screen button references the screen's context directly — if the user starts
+navigating while the action is mid-flight, subsequent steps may see stale or missing
+context.
+
+The form's role shrinks to: "collect inputs, call global action with snapshot". Cleaner.
+
+### Shape of a form-save global action
+
+```typescript
+// src/actions/act-quote-save-customer-info.ts
+export function actQuoteSaveCustomerInfo(app: ApplicationBuilder): void {
+  const action = app.addAction({ actionId: 'act-quote-save-customer-info' })
+
+  // Every field the save needs — snapshotted at call time
+  action.addParameter('data', { type: 'object', required: true })
+  action.addParameter('signatureImage', { type: 'string', required: false })
+  action.addParameter('formName', { type: 'string', required: true })
+  action.addParameter('itemSection', { type: 'string', required: true })
+
+  const workflow = action.action.list({ concurrency: 'sequential' })
+
+  // 1. Disable discard alert on the calling screen
+  workflow.actions.setScreenState({
+    instanceId: 'set-upload',
+    keys: { upload: true },
+  })
+
+  // 2. Save progress row (upserts)
+  workflow.actions
+    .executeEntity({ instanceId: 'save-progress' })
+    .dynamicData('default/formProgress', 'save')
+    .data({
+      id: '=@ctx.solution.state.opportunityid & "-" & @ctx.action.parameters.itemSection',
+      opportunityID: '=@ctx.solution.state.opportunityid',
+      appNbr: '=@ctx.solution.state.appnbr',
+      itemSection: '=@ctx.action.parameters.itemSection',
+      formName: '=@ctx.action.parameters.formName',
+      isCompleted: '1',
+    })
+
+  // 3. Save the actual form data (parameter snapshot)
+  workflow.actions
+    .executeEntity({ instanceId: 'save-info' })
+    .dynamicData('default/salesInfoAnswers', 'save')
+    .data('=@ctx.action.parameters.data')
+
+  // 4. Reset state FIRST
+  workflow.actions.resetScreenState({
+    instanceId: 'reset-upload',
+    keys: ['upload'],
+  })
+
+  // 5. goBack LAST
+  workflow.actions.goBack({ instanceId: 'go-back' })
+}
+```
+
+### Calling from the form screen
+
+```typescript
+const saveActions = screen.bottomPanel().add.list({
+  concurrency: 'sequential',
+  title: 'Save',
+  isDisabled: '=@ctx.components.contactInfo.state.isValid = true ? false:true',
+}).actions
+
+saveActions.executeAction({
+  instanceId: 'save-customer-info',
+  action: 'act-quote-save-customer-info',
+  parameters: {
+    formName: '=@ctx.jig.inputs.formName',
+    itemSection: '=@ctx.jig.inputs.itemSection',
+    signatureImage: '=@ctx.components.salesRepSignature.state.value',
+    data: `={
+      "id": @ctx.datasources.salesInfoAnswers.data.id ? @ctx.datasources.salesInfoAnswers.data.id : $uuid(),
+      "opportunityID": @ctx.solution.state.opportunityid,
+      "appNbr": @ctx.solution.state.appnbr,
+      "customer": @ctx.components.customer.state.value,
+      "addressLine1": @ctx.components.addressLine1.state.value
+    }`,
+  },
+})
+```
+
+The form screen has almost zero inline save logic. Two references: the button config
+and the data JSONata expression. Everything else lives in the action file.
+
+### Caveats for global actions
+
+- **Parameter declaration**: `action.addParameter('name', {...})` — plain name, no `$`.
+- **Parameter access inside the action body**: `@ctx.action.parameters.<name>`.
+- **Parameter values in the caller's `parameters: {}` block**: plain name again, no `$`.
+- **Global actions can access `@ctx.datasources.X` from the caller's screen scope** —
+  useful for reading existing record IDs for upserts without passing them as params.
+- **`setScreenState` inside the global action targets the *calling* screen's state**,
+  so the upload-discard-alert pattern works across the boundary.
+
+## Navigating TO a form — only pass declared inputs
+
+When navigating to a form screen via `goto` or `executeAction`, only pass parameters
+that the target screen has declared via `addInput(...)`. Passing undeclared parameters
+can cause the navigation to fail silently — the target screen never loads or loads
+with partial state.
+
+If the form needs data from the caller that isn't a declared input, either:
+
+- Declare it as an input on the form
+- Or put it in solution state (`setApplicationState`) from the caller's `onFocus` and
+  read it via `@ctx.solution.state.<key>` in the form
+
+## Editing an existing record
+
+Form screens typically filter a datasource by some ID (e.g., `opportunityID` from
+solution state) to load existing data, then use `initialValue` on each field to
+populate from that datasource. A new record has no matching row → filter returns empty
+→ `initialValue` resolves to null/fallback → user sees a blank form.
+
+```typescript
+screen.addDatasource
+  .sqlite({ datasourceId: 'salesInfoAnswers', provider: 'dynamic' })
+  .entity('default/salesInfoAnswers')
+  .query(
+    `SELECT id, data FROM [default/salesInfoAnswers]
+     WHERE json_extract(data, '$.opportunityID') = @opportunityID`,
+  )
+  .queryParameter('opportunityID', '=@ctx.solution.state.opportunityid')
+  .jsonProperties('data')
+  .isDocument(true)  // single-row lookup → returns object, not array
+
+form.addControl.textField({
+  instanceId: 'customerName',
+  label: 'Customer Name',
+  isRequired: true,
+  initialValue: '=@ctx.datasources.salesInfoAnswers.data.customerName',
+})
+```
+
+On save, use the same datasource to detect whether this is a create or update:
+
+```typescript
+.data({
+  id: '=@ctx.datasources.salesInfoAnswers.data.id ? @ctx.datasources.salesInfoAnswers.data.id : $uuid()',
+  // ... rest of fields
+})
+```
+
+`method: 'save'` is an upsert — it creates if `id` is new, updates if `id` exists.
+No need to branch between create/update methods.
+
+### Filter by the unique record key only
+
+**Critical:** filter the edit-existing-record datasource by the **unique** record key
+only — typically `opportunityID` or whatever uniquely identifies the thing being
+edited. Do **not** add `OR <other-key>` clauses like `OR appNbr = @appNbr`.
+
+The legacy sales-form-triplicate pattern used `WHERE opportunityID = @opportunityID
+OR appNbr = @appNbr` to support both "existing opportunity" and "new appointment
+without opportunity yet" lookups. This breaks as soon as you support **multiple
+records per appointment** (e.g., multiple quotes under the same appointment number):
+
+- The `OR appNbr` clause matches every record under the appointment
+- `isDocument: true` picks one — often the wrong one
+- On save, `data.id` points to a different record's UUID → either silently updates
+  the wrong record, or returns null and `$uuid()` generates a fresh UUID → new row
+- Symptoms: save button label stays "Save Information" after saving (because the
+  expression reads `data.id != null` which resolved to false), and each subsequent
+  save creates a duplicate
+
+**Rule:** one row, one unique key, one filter condition. If you need "lookup by
+appointment OR by opportunity" logic, that belongs in a quote *list* screen, not
+in an individual record's edit screen.
+
+### Dynamic button label based on existing row
+
+```typescript
+title: '=@ctx.datasources.salesInfoAnswers.data.id != null ? "Update Information" : "Save Information"'
+```
+
+This works correctly when the datasource filter is precise. If the label stays on
+"Save Information" after a successful save, double-check the datasource filter —
+it's usually because the filter isn't finding the just-saved row.
+
+### JSONata comparisons are strict on type
+
+JSONata's `=` operator does **strict equality** — `"1" = 1` evaluates to **false**
+because one is a string and the other is a number. This trap hits boolean-like flags
+stored as strings:
+
+```typescript
+// Save: stored as string "1"
+.data({ isCompleted: '1' })
+
+// Read (BROKEN — always false)
+'=...isCompleted = 1 ? "check" : "cross"'
+
+// Read (CORRECT)
+'=...isCompleted = "1" ? "check" : "cross"'
+```
+
+Match the literal type in the comparison to what the save writes. If you want a
+type-agnostic compare, use `$number(value) = 1` or `$string(value) = "1"` to coerce.
+
+The `isCompleted` field in `formProgress` is stored as string `"1"` in the parent
+AcumaticaBase project — we keep that convention for merge compat. When you see a
+completion indicator or status icon stuck on the "not done" state, check for a
+string-vs-number mismatch before assuming the save didn't run.
+
+## Checklist when building a new form
+
+- [ ] Every field has `isRequired` explicitly set
+- [ ] Fields wrapped in `form.addControl.form({ instanceId: ..., isDiscardChangesAlertEnabled: ... })`
+- [ ] Save button uses `isDisabled`, not `when`
+- [ ] Save action list order: `setScreenState(upload: true)` → saves → `resetScreenState` → `goBack`
+- [ ] `goBack` is standalone and last
+- [ ] Conditional saves (`when` on a step) are only used for expensive operations like signatures
+- [ ] Only declared inputs are passed when navigating to the form
+- [ ] Datasource filter + `initialValue` pattern for edit-existing-record support

package/docs/pattern-global-actions.md

@@ -0,0 +1,92 @@
+# Pattern: Global Actions
+
+## Why global actions
+
+When an action list uses `@ctx` values, those values can change between steps (e.g., a datasource updates after a previous step writes to the table). Global actions with parameters solve this — parameters are snapshot at call time and stay consistent throughout execution.
+
+## Defining a global action (local save)
+
+```typescript
+const action = app.addAction({ actionId: 'act-customer-save' })
+action.addParameter('data', { type: 'object', required: true })
+
+const workflow = action.action.list({ concurrency: 'sequential' })
+
+workflow.actions.setScreenState({
+  instanceId: 'disable-discard-alert',
+  keys: { showDiscardAlert: false },
+})
+
+workflow.actions
+  .executeEntity({ instanceId: 'save-entity' })
+  .dynamicData('default/customers', 'create')
+  .data('=@ctx.action.parameters.data')
+  .onSuccess.goBack()
+```
+
+## Calling from a jig
+
+Build the data via JSONata in the jig, pass as parameter:
+
+```typescript
+buttons.add.executeAction({
+  title: 'Save',
+  isPrimary: true,
+  action: 'act-customer-save',
+  when: IS_VALID,
+  parameters: {
+    data: buildSaveExpression(),  // JSONata evaluated at call time
+  },
+})
+```
+
+## TypeScript helper functions
+
+Use helpers to reduce repetition when building cross-jig references and JSONata expressions.
+
+**Note on JSONata variable bindings**: `$var := <expr>` *is* supported in Jigx expressions, but only when the right-hand side is a value that resolves from the `@ctx` tree — e.g., `$customers := @ctx.datasources.customers` binds the datasource's array result to a variable for later reference in the same expression. What is **not** supported is using variable bindings as a shortcut for component state paths across separate action/component configs — each config is its own JSONata expression, so a binding in one config doesn't carry into another. For DRY across configs, use TypeScript constants that get compiled into the expression strings.
+
+```typescript
+// Full paths to cross-jig component state (TypeScript constants for DRY, not JSONata variables)
+const G = '@ctx.jigs.general-instance.components'
+const B = '@ctx.jigs.billing-instance.components'
+const S = '@ctx.jigs.shipping-instance.components'
+
+/** Build a JSONata {"value": <full-path>} expression for a field. */
+// NOTE: The {"value": ...} wrapper is Acumatica-specific. For other systems,
+// adapt the helper to match their field format (e.g., flat values, different wrappers).
+function v(scope: string, componentId: string): string {
+  return `{"value": ${scope}.${componentId}.state.value}`
+}
+```
+
+Usage: `"CustomerName": ${v(G, 'CustomerName')}` produces `"CustomerName": {"value": @ctx.jigs.general-instance.components.CustomerName.state.value}`.
+
+The `v()` helper builds nested `{ "value": ... }` objects. **Acumatica-specific**: Acumatica wraps all field values in `{ "value": ... }` objects. For other systems, adjust or remove the wrapper to match the expected API format.
+
+## JSONata save expression
+
+Build nested JSON matching the external API schema using a single JSONata expression with variable bindings:
+
+```typescript
+function buildSaveExpression(): `=${string}` {
+  return `={
+  "id": @ctx.jig.instanceId,
+  "Remote": "new",
+  "CustomerName": ${v(G, 'CustomerName')},
+  "BillingContact": {
+    "Email": ${v(B, 'Email')}
+  }
+}`
+}
+```
+
+Key points:
+
+- The `.data()` method on `executeEntity` accepts either `Record<string, Primitive>` or a single `Expression` string
+- Use the expression form to build arbitrarily nested JSON
+- Use TypeScript constants (`G`, `B`, `S`) for DRY across configs — these are compile-time substitutions that get baked into each expression string. JSONata `$var :=` bindings work within a single expression but don't carry between separate configs
+- Return type must be `` `=${string}` `` for TypeScript
+- **Acumatica-specific**: The `{ "value": ... }` wrapper matches Acumatica's API field convention. Other systems may use flat values or different structures — adapt the save expression accordingly
+- Include `"Remote": "new"` to flag new records as unsynced (see [pattern-rest-acumatica.md](pattern-rest-acumatica.md#record-sync-state-remote-field) for all states)
+- Include `"LastModifiedDateTime": {"value": $now()}` so new records sort to the top of time-ordered lists