@jigx/core-sdk 1.1.0 → 1.2.0-rc

package/docs/pattern-navigation.md

@@ -0,0 +1,304 @@
+# Pattern: Navigation
+
+## Screen lifecycle — `onFocus` vs `onLoad`
+
+- **`onFocus`** fires when the user navigates *to* a screen (via `goto`, a tab switch,
+  or a list-item onPress). It does **not** fire when the user returns to the screen
+  via `goBack` from another screen. This is what you want for "run something each
+  time I arrive fresh", e.g., pushing input values into solution state, or triggering
+  an auto-generate action.
+- **`onLoad`** fires once when the screen is first instantiated and never again.
+
+Practical implication: if you use `screen.onFocus.setApplicationState({...})` to
+push jig.inputs into solution state, the state is set on each navigation-in. But
+if the user is already on the screen and navigates back to it, onFocus does not
+re-fire — existing solution state from the previous visit is preserved.
+
+For a "generate if missing" pattern (e.g., PDF auto-generation on screen focus),
+always pair `onFocus` with a `when` guard so re-focusing a screen that already has
+the result doesn't re-run the work:
+
+```typescript
+screen.onFocus.executeAction({
+  action: 'act-generate-quote-pdf',
+  when: '=$exists(@ctx.datasources.salesInfoAnswers.data.pdfFilePath) = false',
+  parameters: { opportunityID: '=@ctx.jig.inputs.opportunityID' },
+})
+```
+
+## Navigation with fresh instances
+
+When navigating to a create form from a list, use `behaviour: 'new'` and a UUID instance:
+
+```typescript
+screen.bottomPanel().add.goto({
+  title: 'New Customer',
+  linkTo: SCREEN.CUSTOMER_CREATE,
+  isPrimary: true,
+  behaviour: 'new',
+  instanceId: '=$uuid()',
+})
+```
+
+For standalone create screens, the generated UUID can be used as `@ctx.jig.instanceId` on the target screen and then saved as the new record `id`.
+
+For child-create screens inside a parent aggregate, do not rely on the child screen `@ctx.jig.instanceId` as the row id. Generate the child row id at the `go-to` call and pass it in explicitly:
+
+```typescript
+buttons.add.goto({
+  title: 'Add Detail',
+  linkTo: SCREEN.DETAIL_CREATE,
+  behaviour: 'new',
+  parameters: {
+    serviceOrderId: '=@ctx.jig.inputs.serviceOrderId',
+    detailId: '=$uuid()',
+  },
+})
+```
+
+Then save the child row with the passed `detailId`.
+
+## Bottom panel action order
+
+The first action in `bottomPanel()` is the visible button. Additional actions go into the overflow menu (accessed via `...`).
+
+```typescript
+const buttons = tabs.bottomPanel()
+buttons.add.executeAction({ title: 'Save', isPrimary: true, ... })  // Visible
+buttons.add.goBack({ title: 'Cancel' })                              // Overflow
+```
+
+## Navigation flow: List → Detail → Child form
+
+```
+jig-customer-list (jig.list)
+  ├── onPress → jig-customer-view (parameters: { customerId })
+  │     └── Add Contact → jig-contact-create (parameters: { customerId })
+  └── New Customer → jig-customer-create (tabs, behaviour: 'new', instanceId: $uuid())
+```
+
+### List item to detail
+
+```typescript
+listItem.onPress.goto({
+  linkTo: SCREEN.CUSTOMER_VIEW,
+  parameters: { customerId: '=@ctx.current.item.id' },
+})
+```
+
+### Detail to child form (forwarding parent ID)
+
+```typescript
+buttons.add.goto({
+  title: 'Add Contact',
+  linkTo: SCREEN.CONTACT_CREATE,
+  parameters: { customerId: '=@ctx.jig.inputs.customerId' },
+})
+```
+
+### Child form save with foreign key
+
+For child entities (e.g., Contact belongs to Customer), use the parent's local ID as the relationship key. Before the parent syncs with the remote system, this is the jig `instanceId` (UUID). After sync, the REST function's find-replace operation updates this value to the remote system's business key.
+
+```typescript
+// Contact save expression — foreign key links to parent
+"BusinessAccount": {"value": @ctx.jig.inputs.customerId},
+"CompanyName": {"value": @ctx.jig.inputs.customerName},
+```
+
+**Acumatica-specific**: `BusinessAccount.value` is Acumatica's field linking a Contact to a Customer. The `{ "value": ... }` wrapper is Acumatica's field format. For other systems, use the appropriate foreign key field name and format.
+
+The parent's REST function includes a find-replace on the child table to update the local UUID to the remote key after sync. See [pattern-rest-acumatica.md](pattern-rest-acumatica.md) for details.
+
+### Adding child records from a tab
+
+When a tabs screen embeds a child list tab, pass the parent ID and name via tab inputs:
+
+```typescript
+const contactsTab = tabs.addInstance.tab(SCREEN.CUSTOMER_CONTACTS, TAB_INSTANCE.CONTACTS)
+contactsTab.input('customerId', '=@ctx.jig.instanceId')
+contactsTab.input('customerName', '=@ctx.jigs.general-instance.components.CustomerName.state.value')
+```
+
+The child list tab opens a modal form to create new records:
+
+```typescript
+screen.bottomPanel().add.goto({
+  title: 'Add Contact',
+  linkTo: SCREEN.CONTACT_CREATE,
+  isPrimary: true,
+  isModal: true,
+  parameters: {
+    customerId: '=@ctx.jig.inputs.customerId',
+    customerName: '=@ctx.jig.inputs.customerName',
+  },
+})
+```
+
+If the child row needs its own stable local id before save, generate that id in the `go-to` parameters as well instead of trying to derive it from the child screen instance.
+
+## Sync status tags on list items
+
+Show the sync state of each record using colored tags:
+
+```typescript
+const listItem = screen.addControl
+  .listItem({ instanceId: 'customer-item' })
+  .title('=@ctx.current.item.data.CustomerName.value')   // Acumatica field path
+  .subtitle('=@ctx.current.item.data.MainContact.Email.value')
+
+listItem.addTag({
+  text: '=@ctx.current.item.data.Remote = "remote" ? "Synced" : @ctx.current.item.data.Remote = "dirty" ? "Edited" : "New"',
+  color: '=@ctx.current.item.data.Remote = "remote" ? "positive" : @ctx.current.item.data.Remote = "dirty" ? "warning" : "primary"',
+})
+```
+
+The `Remote` field and tag logic is generic — works with any system. The field paths in `title`/`subtitle` are **Acumatica-specific** (`.value` wrappers). Adapt to match your system's data structure.
+
+| Remote value | Tag text | Color |
+| --- | --- | --- |
+| `"remote"` | Synced | `positive` (green) |
+| `"dirty"` | Edited | `warning` (orange) |
+| `"new"` | New | `primary` (blue) |
+
+Apply to both Customer and Contact list items.
+
+## Detail screen with screen-scoped datasources
+
+For detail/view screens, use screen-scoped datasources (declared on the screen, not at app level). These stay inline in the jig's YAML output. Follow the standard datasource pattern (`SELECT id, data` + `jsonProperties`).
+
+```typescript
+const screen = app.addScreen.default({ screenId: 'jig-customer-view', title: 'Customer Detail' })
+screen.addInput({ name: 'customerId', type: 'string', isRequired: true })
+
+// Single document datasource
+screen.addDatasource
+  .sqlite({ datasourceId: 'data-select-customer', provider: 'dynamic' })
+  .entity('default/customers')
+  .query('SELECT id, data FROM [default/customers] WHERE id = @customerId')
+  .queryParameter('customerId', '=@ctx.jig.inputs.customerId')
+  .jsonProperties('data')
+  .isDocument(true)
+
+// Related records (json_extract only in WHERE)
+screen.addDatasource
+  .sqlite({ datasourceId: 'data-select-contacts', provider: 'dynamic' })
+  .entity('default/contacts')
+  .query(`SELECT id, data FROM [default/contacts] WHERE json_extract(data, '$.customerId') = @customerId`)
+  .queryParameter('customerId', '=@ctx.jig.inputs.customerId')
+  .jsonProperties('data')
+```
+
+Use `.isDocument(true)` for single-record lookups — returns an object instead of an array, so `=@ctx.datasources.data-select-customer.data.CustomerName.value` works directly (no `[0]` needed).
+
+## Swipe actions with confirmation + global action
+
+List items support `swipeLeft()` and `swipeRight()`. Each returns a `SwipeableActionBuilder` whose `.onPress` is a full action builder — you can chain `confirm` (for destructive ops) then `executeAction` (for the actual work) via `onConfirmed`.
+
+```typescript
+item
+  .swipeRight()
+  .label('Delete')
+  .icon('delete-1')
+  .color('negative')
+  .onPress.confirm({
+    modal: {
+      title: 'Delete Quote?',
+      description: '=@ctx.current.item.quoteName & " will be permanently deleted."',
+      confirm: 'Delete',
+      cancel: 'Cancel',
+    },
+  })
+  .onConfirmed.executeAction({
+    action: ACTION.DELETE_QUOTE,
+    parameters: {
+      opportunityID: '=@ctx.current.item.opportunityID',
+    },
+  })
+```
+
+`@ctx.current.item.*` is available inside the swipe action (same scope as the list item itself), but **not** inside the global action it calls — the global action only sees the parameters you pass in. Pass anything the action needs (ids, names, etc.) explicitly.
+
+### Copying list rows locally
+
+For local child rows, copy by saving a merged data object with a fresh row id and
+fresh parent/line metadata. Keep the copied row tied to the same parent key unless
+the copy is intentionally moving between parents.
+
+```typescript
+item
+  .swipeLeft()
+  .label('Copy')
+  .icon('copy-1')
+  .color('positive')
+  .onPress.confirm({
+    modal: { title: 'Copy Item?', confirm: 'Copy', cancel: 'Cancel' },
+  })
+  .onConfirmed.executeEntity({ instanceId: 'copy-item' })
+  .dynamicData('default/childRows', 'save')
+.data(
+  '=$merge([@ctx.current.item.data, {"id": $uuid(), "parentId": @ctx.jig.inputs.parentId, "lineNumber": @ctx.datasources.nextLineNumber.lineNumber}])',
+)
+```
+
+### Add-next-item chooser
+
+When a parent can contain multiple similar configured items (doors, openers, contacts,
+etc.), the add action should branch:
+
+- If no prior child rows exist, navigate directly to a clean create screen with a new
+  child id generated in the `go-to` parameters.
+- If at least one child row exists, navigate to a small chooser screen that offers
+  "Copy previous" and "Start clean".
+- "Copy previous" should save a merged local row with the new id/line metadata before
+  navigating to edit that copied row.
+- "Start clean" should navigate with the same generated child id but no copied data.
+
+This pattern keeps repeated configuration fast without reusing the previous row's id.
+
+When adding a new child row and an existing row can act as a template, navigate to
+a small chooser screen rather than overloading a confirm dialog. `action.confirm`
+only has an `onConfirmed` branch, so it cannot implement both "copy previous" and
+"start clean" from the cancel button. Use two explicit actions/list items instead.
+
+## Conditional tag on list item
+
+`addTag({text, color, when})` supports a `when` expression — the tag is only rendered
+when the expression evaluates truthy. This is the preferred pattern for conditional
+badges on list items:
+
+```typescript
+// Good — tag only shown when the condition is true
+item.addTag({
+  text: 'PDF',
+  color: 'positive',
+  when: '=$exists(@ctx.current.item.pdfFilePath)',
+})
+```
+
+Note: at one point the SDK's `TagBadge` type definition was missing the `when` field,
+which led to a workaround using the expression-based `.tags(expr)` method. That
+workaround still works but is unnecessary — `addTag` with `when` is simpler and more
+readable. If the TS type complains about `when`, update `packages/core-sdk/src/component/jc.list-item.ts`
+to include `when?: BooleanOrExpression` on the `TagBadge` interface.
+
+### Row-specific tags driven by external datasources
+
+When a static menu/list row shows status derived from separate datasources
+(`formProgress`, checklist answers, child counts, etc.), prefer `.tags(expr)` and
+return an array for the current row. This keeps the row identity and status logic
+in one expression and avoids accidental repeated badges when several row types
+share one compound condition.
+
+```typescript
+item.tags(
+  '=(' +
+    '(@ctx.current.item.id = "details" and $count(@ctx.datasources.formProgress[itemSection="details" and $string(isCompleted)="1"]) > 0) or ' +
+    '(@ctx.current.item.id = "checklist" and $count(@ctx.datasources.requiredItems) > 0 and $count(@ctx.datasources.requiredItems) = $count(@ctx.datasources.answers))' +
+    ') ? [{"text":"Complete","color":"positive"}] : []',
+)
+```
+
+Use a stable row key such as `@ctx.current.item.id` rather than comparing display
+labels. Coerce saved flag values with `$string(...)` or `$number(...)` when the
+local table stores boolean-like values as strings.