@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/pattern-tabs-form.md

@@ -0,0 +1,293 @@
+# Pattern: Tabbed Forms
+
+**Tab-specific nuances only.** For generic form patterns (required fields, `isDisabled`,
+save action ordering, global actions, edit-existing-record), see
+[pattern-forms.md](pattern-forms.md).
+
+## Tabs screen with header
+
+```typescript
+const tabs = app.addScreen.tabs({
+  screenId: SCREEN.CUSTOMER_CREATE,
+  title: 'New Customer',
+})
+
+tabs.with({ state: { showDiscardAlert: { initialValue: true } } })
+
+const header = tabs.header()
+header.with({ height: 'tiny' })
+header.addControl.image({
+  instanceId: 'header-image',
+  source: { uri: 'https://images.jigx.com/customers/sales/sales_header.png' },
+})
+```
+
+## Registering tabs with inputs
+
+Use `.input()` to pass state from the tabs screen to child screens:
+
+```typescript
+const generalTab = tabs.addInstance.tab(SCREEN.CUSTOMER_GENERAL, TAB_INSTANCE.GENERAL)
+generalTab.button({ instanceId: 'general-btn', title: 'General', icon: 'contact' })
+generalTab.input('showDiscardAlert', '=@ctx.jig.state.showDiscardAlert')
+```
+
+## Conditional embedded jigs
+
+When one tab or detail screen needs to host a variant-specific sub-flow, use
+`component.jig` inside a `jig.default` screen. Render one embedded jig per variant and
+guard each with `when` rather than trying to make `jigId` dynamic.
+
+```typescript
+screen.addControl.jig({
+  instanceId: 'amarr-builder',
+  jigId: SCREEN.DOOR_AMARR,
+  when: '=@ctx.components.manufacturer.state.value = "AMARR"',
+  inputs: {
+    doorId: '=@ctx.jig.inputs.doorId',
+    lineNumber: '=@ctx.jig.inputs.lineNumber',
+  },
+})
+```
+
+The wrapper owns variant selection. The embedded jig owns its form, validation, save
+action, and item-code construction. Pass stable ids as inputs; do not rely on the
+embedded jig instance id as a local row id.
+
+For manufacturer-specific attribute builders, prefer not to use `component.jig` at
+all. Navigate from a chooser/list screen to the concrete manufacturer jig and put the
+save action on that concrete jig. Use wrapper-owned saves only when the embedded
+content is simple enough that cross-jig validation has been proven in the target
+runtime.
+
+If the UX requires one parent-level save button, keep the wrapper as the save owner
+instead. In that variant:
+
+1. The wrapper owns the bottom-panel action list.
+2. Each embedded jig is field-only. The wrapper reads the active embedded jig's
+   component state in the save action, e.g.
+   `@ctx.jigs.amarr-builder.components.size.state.selected.valueID`.
+3. The wrapper save action has one conditional `executeEntity` branch per embedded
+   variant, guarded by the wrapper selection (`when: =@ctx.components.manufacturer.state.value = "AMARR"`).
+4. Each branch also checks the active embedded jig's form validity before saving,
+   e.g. `@ctx.jigs.amarr-builder.components.door-details-form.state.isValid`.
+5. The wrapper save button's disabled expression should depend only on wrapper-owned
+   state, such as the selected manufacturer. Do not depend on embedded jig outputs
+   for the button style, because parent bottom-panel `isDisabled` can remain stale
+   after fields change inside the embedded jig.
+6. Shared wrapper datasources needed by the save, such as the existing local row and
+   PDF stale marker row, must live on the wrapper screen because the parent action
+   executes in wrapper context.
+
+```typescript
+const amarr = app.addScreen.default({
+  screenId: SCREEN.DOOR_AMARR,
+  title: 'Amarr Door Builder',
+})
+
+const form = amarr.addControl.form({ instanceId: 'door-details-form' })
+
+screen.addControl.jig({
+  instanceId: 'amarr-builder',
+  jigId: SCREEN.DOOR_AMARR,
+  when: '=@ctx.components.manufacturer.state.value = "AMARR"',
+})
+
+screen.bottomPanel().add.list({
+  title: 'Save Door',
+  isDisabled: '=@ctx.components.manufacturer.state.value ? false:true',
+})
+```
+
+Use the embedded component state inside the action list at tap time. Add an invalid
+alert before the save branches, guard the state changes and saves with the embedded
+form validity, and read field values from the embedded component state.
+
+Do not rely on `@ctx.jigs.<embedded>.outputs` for wrapper-owned save actions unless
+you have verified the current runtime exposes those outputs in the action context.
+In the DoorPro flow, debug logs showed `@ctx.jigs.amarr-builder.outputs` as `null`
+inside the wrapper action, while direct embedded component state remained the safer
+pattern for wrapper-owned saves.
+
+If the product requirement is a visually disabled button until every embedded field
+is valid, put the save button inside the same jig as the form state instead of on
+the wrapper.
+
+When the parent owns the save button, read embedded component state in the save
+action itself:
+
+```typescript
+saveActions.showAlert({
+  instanceId: 'missing-required-fields',
+  when: '=@ctx.components.manufacturer.state.value = "AMARR" ? (@ctx.jigs.amarr-builder.components.door-details-form.state.isValid = true ? false:true) : true',
+  title: 'Door Not Complete',
+})
+
+saveActions
+  .executeEntity({
+    when: '=@ctx.components.manufacturer.state.value = "AMARR" and @ctx.jigs.amarr-builder.components.door-details-form.state.isValid = true',
+  })
+  .dynamicData('default/doorDetails', 'save')
+  .data({
+    sizeValueID: '=@ctx.jigs.amarr-builder.components.size.state.selected.valueID',
+  })
+```
+
+For wrapper-owned saves, propagate the wrapper upload/discard state into the embedded
+jigs as an input and bind each embedded form's `isDiscardChangesAlertEnabled` to that
+input. The save action still follows the generic ordering: set wrapper `upload`,
+save, reset wrapper `upload`, then navigate.
+
+Do not put critical save actions on a section only to work around embedded jig bottom
+panels not rendering. Use either embedded-owned saves when each embedded jig is a
+standalone interaction, or wrapper-owned saves when the parent screen should expose a
+single consistent save action.
+
+## Local correlation id for new tabbed aggregates
+
+When a tabs flow creates a new local aggregate, the preferred pattern is:
+
+1. Navigate to the new parent screen with a generated jig `instanceId`
+2. Generate one local correlation id and use it for both:
+   - the parent screen `instanceId`
+   - the parent input that child tabs read as the aggregate key
+3. Pass that same id down to child tabs and child create screens as the parent key
+4. Save the parent row with that id in the local table
+5. Save child rows with `parentId` set to that same local correlation id
+
+This is the stable local key for the whole aggregate until remote sync happens.
+
+Example:
+
+```typescript
+const createActions = list.bottomPanel().add.list({
+  title: 'New Service Order',
+  isPrimary: true,
+  concurrency: 'sequential',
+}).actions
+
+createActions.setScreenState({
+  instanceId: 'set-new-id',
+  keys: { newParentId: '=$uuid()' },
+})
+
+createActions.goto({
+  linkTo: SCREEN.SERVICE_ORDER_CREATE,
+  behaviour: 'new',
+  instanceId: '=@ctx.jig.state.newParentId',
+  parameters: {
+    serviceOrderId: '=@ctx.jig.state.newParentId',
+  },
+})
+```
+
+Then inside the tabs flow:
+
+```typescript
+detailsTab.input('serviceOrderId', '=@ctx.jig.inputs.serviceOrderId')
+```
+
+And child rows:
+
+```typescript
+.data({
+  id: '=@ctx.jig.inputs.detailId',
+  parentId: '=@ctx.jig.inputs.serviceOrderId',
+})
+```
+
+For child create screens, generate the new child id at the `go-to` call and pass it in as an input or parameter. Do not rely on the child jig `instanceId` as the row id.
+
+```typescript
+addDetail.goto({
+  linkTo: SCREEN.SERVICE_ORDER_DETAIL_CREATE,
+  behaviour: 'new',
+  parameters: {
+    serviceOrderId: '=@ctx.jig.inputs.serviceOrderId',
+    detailId: '=$uuid()',
+  },
+})
+```
+
+Then the child save can always use the passed `detailId` directly.
+
+Important distinction:
+
+- the parent input is the authoritative local correlator child tabs should use
+- the parent screen `instanceId` should match that correlator for new flows
+- existing records opened from a list should pass their persisted row id in inputs
+- child tables should keep `parentId` pointing at the stable local parent id
+- if a remote API later needs a different id (for example Acumatica `id` / `NoteID` for file uploads),
+  store that in a separate remote-target field and update it during sync operations
+
+Do not mix "input id" and fallback `@ctx.jig.instanceId` logic in the same tabbed aggregate flow.
+Use one stable local correlation id end to end.
+
+Do not introduce refresh-token workarounds when the real issue is parent-child key consistency.
+If details, photos, or contacts are not showing after save, check the local correlation id flow first.
+
+## Tab content screen with form
+
+Each tab screen declares the input and wraps fields in a form. See
+[pattern-forms.md](pattern-forms.md) for the generic form rules (required fields,
+button validation, etc.).
+
+```typescript
+const screen = app.addScreen.default({ screenId: SCREEN.CUSTOMER_GENERAL, title: 'General' })
+screen.addInput({ name: 'showDiscardAlert', type: 'boolean' })
+
+const form = screen.addControl.form({
+  instanceId: 'general-form',
+  isDiscardChangesAlertEnabled: '=@ctx.jig.inputs.showDiscardAlert',
+})
+
+form.addControl.textField({ instanceId: 'CustomerName', label: 'Customer Name', isRequired: true })
+```
+
+## Cross-jig form validation
+
+The one thing unique to tabs: combine `isValid` across all child forms from the
+parent tabs screen:
+
+```typescript
+const IS_VALID = [
+  '=@ctx.jigs.general-instance.components.general-form.state.isValid',
+  'and @ctx.jigs.billing-instance.components.billing-form.state.isValid',
+  'and @ctx.jigs.shipping-instance.components.shipping-form.state.isValid',
+].join(' ')
+```
+
+Use as `isDisabled` (inverted) on the save button — see
+[pattern-forms.md](pattern-forms.md#save-button--isdisabled-never-when) for why
+`isDisabled` not `when`.
+
+```typescript
+tabs.bottomPanel().add.executeAction({
+  title: 'Save',
+  action: 'act-customer-save',
+  isDisabled: `=(${IS_VALID}) = true ? false:true`,
+})
+```
+
+## Discard alert across tabs
+
+The discard alert pattern in [pattern-forms.md](pattern-forms.md#save-action-list--correct-ordering)
+uses a single-screen local state key (`upload`). For tabs, the state lives on the
+parent tabs screen and propagates to child tabs via inputs:
+
+1. **Tabs screen state**: `upload: { initialValue: null }`
+2. **Pass to child tabs** via `.input('upload', '=@ctx.jig.state.upload')`
+3. **Child screens declare** `addInput({ name: 'upload', type: 'boolean' })`
+4. **Form binds**: `isDiscardChangesAlertEnabled: '=@ctx.jig.inputs.upload = true ? false:true'`
+5. **Global action's first step**: `setScreenState({ keys: { upload: true } })` —
+   this targets the tabs screen's state (the *calling* screen), which propagates to
+   child forms via the input binding
+6. **Global action's last steps**:
+   - save-and-close flows: `resetScreenState` → `goBack`
+   - save-in-place flows: `resetScreenState`
+   See [pattern-forms.md](pattern-forms.md#save-action-list--correct-ordering).
+
+**The nuance vs single-screen**: in the tabs pattern, the state lives on the PARENT
+tabs screen, not the child form screens. `setScreenState` targets the calling jig,
+which in this flow is the tabs screen (where the save button lives). Because child
+tabs read the state via `.input()`, they pick up the change on the next render.

package/docs/recipe-index.md

@@ -0,0 +1,64 @@
+# Recipe: Core SDK App with Acumatica Integration
+
+Build a multi-screen Jigx app using Core SDK with local data, tabbed forms, REST integration, and Acumatica-compatible nested JSON.
+
+Reference implementation: `workspace/acumatica-apps/create-customer/`
+
+## Pattern files
+
+| Pattern | Description |
+| --- | --- |
+| [convention-naming.md](convention-naming.md) | File, component, field, and constant naming conventions |
+| [pattern-datasources.md](pattern-datasources.md) | SELECT id/data, jsonProperties, isDocument, config table, schemas folder |
+| [pattern-forms.md](pattern-forms.md) | **Generic form patterns** — required fields, save button isDisabled, save action ordering, global action extraction, edit-existing-record |
+| [pattern-tabs-form.md](pattern-tabs-form.md) | Tab-specific additions — cross-jig validation, tab inputs for discard-alert propagation |
+| [pattern-global-actions.md](pattern-global-actions.md) | Parameter snapshotting, local save action, JSONata save expression, TypeScript helpers |
+| [pattern-rest-acumatica.md](pattern-rest-acumatica.md) | REST functions, Acumatica conventions, functionCall, accessToken, remote sync flag |
+| [pattern-navigation.md](pattern-navigation.md) | behaviour: 'new', $uuid(), bottom panel order, list-detail-child flow, screen-scoped datasources |
+| [pattern-sync.md](pattern-sync.md) | Initial sync, continuation, diff sync, sync scopes, OData vs REST |
+| [pattern-sync-progress.md](pattern-sync-progress.md) | Sync progress bar UI ideas — weights, step text, show/hide, cards |
+| [pattern-javascript-functions.md](pattern-javascript-functions.md) | `app.script()` — extend JSONata with custom JS functions (math, formatting, HTML templates, validation, transformation) |
+| [pattern-pdf-generation.md](pattern-pdf-generation.md) | `generate-pdf` action + `app.script()` + `jig.document` screen — generate, persist, preview, share PDFs |
+| [pattern-build-deploy.md](pattern-build-deploy.md) | Build order, typecheck, JSON/YAML generation, deploy script, Jigx API |
+
+## Project structure
+
+```
+src/
+├── app.ts                            # Assembly + build order
+├── common.ts                         # Screen/action/function/datasource/entity constants
+├── database.ts                       # Table definitions (config, customers, contacts)
+├── datasources.ts                    # App-scoped datasources
+├── schemas/
+│   ├── customers.yaml                # Schema for default/customers table
+│   └── contacts.yaml                 # Schema for default/contacts table
+├── functions/
+│   └── rest-put-customer.ts          # REST PUT function for Acumatica
+├── actions/
+│   ├── act-customer-save.ts          # Save customer locally
+│   └── act-customer-save-remote.ts   # Save customer to Acumatica via REST
+└── screens/
+    ├── jig-customer-list.ts          # List screen with header sync action
+    ├── jig-customer-general.ts       # Tab 1 content (default screen with form)
+    ├── jig-customer-billing.ts       # Tab 2 content
+    ├── jig-customer-shipping.ts      # Tab 3 content
+    ├── jig-customer-create.ts        # Tabs screen (orchestrator)
+    ├── jig-customer-view.ts          # Detail view
+    └── jig-contact-create.ts         # Child entity form
+```
+
+## Schema-driven field design
+
+Start with the external API schema (e.g., `acumatica schemas/Customers.yaml`) to drive field creation. The schema documents:
+
+- Field paths (`data.CustomerName.value`, `data.MainContact.Email.value`)
+- Nested objects (`MainContact`, `BillingContact`, `ShippingContact`, `PrimaryContact`)
+- Field types and enumerations
+- Relationships to other entities
+
+Use the schema to:
+
+1. Name form field `instanceId` values to match schema field names
+2. Structure the save JSONata expression to match the schema's nesting
+3. Identify required fields from the UI design (orange-highlighted labels in mockups)
+4. Map sections to schema objects (Account Address → top-level, Primary Contact → `PrimaryContact`, etc.)

package/docs/runtime-variables.md

@@ -0,0 +1,127 @@
+## Import Statement
+
+```typescript
+import { Auth, System, JsonataBuilder } from '@jigx/expert-sdk'
+```
+
+## System Variables
+
+### Device & Environment
+
+| Variable | Type | Description |
+| --- | --- | --- |
+| `System.deviceType` | string | Device type ('ios', 'android') |
+| `System.isOnline` | boolean | Network connected |
+| `System.isOffline` | boolean | Network disconnected |
+| `System.isPortrait` | boolean | Portrait orientation |
+| `System.locale` | string | User's locale setting |
+| `System.appVersion` | string | Current app version |
+
+### Location
+
+| Variable | Type | Description |
+| --- | --- | --- |
+| `System.isLocationSharingEnabled` | boolean | Location permission granted |
+| `System.geolocation.coords.latitude` | number | GPS latitude |
+| `System.geolocation.coords.longitude` | number | GPS longitude |
+| `System.geolocation.coords.accuracy` | number | GPS accuracy (meters) |
+| `System.geolocation.coords.altitude` | number | GPS altitude |
+| `System.geolocation.coords.speed` | number | Movement speed |
+| `System.geolocation.coords.heading` | number | Movement direction |
+| `System.geolocation.timestamp` | number | Location timestamp |
+
+### Timezone
+
+| Variable | Type | Description |
+| --- | --- | --- |
+| `System.timezone.name` | string | Timezone name (e.g., 'America/New_York') |
+| `System.timezone.offset` | number | UTC offset in minutes |
+
+## User Variables (Auth.user)
+
+| Variable | Type | Description |
+| --- | --- | --- |
+| `Auth.user.id` | string | User's unique identifier |
+| `Auth.user.displayName` | string | User's display name |
+| `Auth.user.email` | string | User's email address |
+| `Auth.user.phone` | string | User's phone number |
+| `Auth.user.avatarUrl` | string | User's avatar image URL |
+| `Auth.user.isVerified` | boolean | Account verification status |
+
+## Usage Examples
+
+### Pre-fill with User Data
+
+```typescript
+step.addText({
+ name: 'name',
+ label: 'Name',
+ value: new JsonataBuilder('$userName', { userName: Auth.user.displayName }),
+})
+step.addEmail({
+ name: 'email',
+ label: 'Email',
+ value: new JsonataBuilder('$userEmail', { userEmail: Auth.user.email }),
+})
+```
+
+### Conditional Based on Network
+
+```typescript
+step.addText({
+ name: 'status',
+ label: 'Status',
+ value: new JsonataBuilder('$online ? "Connected" : "Offline"', { online: System.isOnline }),
+})
+```
+
+### Device-Specific Logic
+
+```typescript
+step.addDropdown({
+ name: 'selection',
+ label: 'Selection',
+ data: [
+  { label: 'Option A', value: 'a' },
+  { label: 'Option B', value: 'b' },
+ ],
+ helperText: new JsonataBuilder('$device = "ios" ? "Tap to select" : "Touch to select"', {
+  device: System.deviceType,
+ }),
+})
+```
+
+### Location-Based Features
+
+```typescript
+step.addLocation({ name: 'location', label: 'Current Location' })
+// Location field auto-configures with System.geolocation
+// Or manual access:
+step.addText({
+ name: 'coords',
+ label: 'Coordinates',
+ value: new JsonataBuilder('$lat & "," & $lng', {
+  lat: System.geolocation.coords.latitude,
+  lng: System.geolocation.coords.longitude,
+ }),
+})
+```
+
+### Timezone Display
+
+```typescript
+step.addText({
+ name: 'timezone',
+ label: 'Timezone',
+ helperText: new JsonataBuilder('"Your timezone: " & $tz', { tz: System.timezone.name }),
+})
+```
+
+## Availability
+
+System and Auth variables are accessible in all `JsonataBuilder` contexts:
+
+- Field properties (value, helperText, isVisible, etc.)
+- Step properties (title, description, isVisible)
+- Submission item (submissionItemTitle, submissionItemSubtitle)
+- Form metadata (description)

package/docs/sections.md

@@ -0,0 +1,81 @@
+## Creating Sections
+
+```typescript
+// Section for contact info
+const contactSection = step.addSection({ title: 'Contact Information' })
+contactSection.addEmail({ name: 'email', label: 'Email' })
+contactSection.addPhone({ name: 'phone', label: 'Phone' })
+// Section for address
+const addressSection = step.addSection({ title: 'Address' })
+addressSection.addText({ name: 'street', label: 'Street' })
+addressSection.addText({ name: 'city', label: 'City' })
+```
+
+**Important:** Add fields to the section, not the step directly:
+
+```typescript
+// Correct
+section.addText({ name: 'field', label: 'Field' })
+
+// Wrong - adds to step, not section
+step.addText({ name: 'field', label: 'Field' })
+```
+
+## Section Properties
+
+Pass in constructor or use `.with()`:
+
+```typescript
+const toggleField = step.addCheckbox({ name: 'show-section', label: 'Show Issues' })
+const section = step.addSection({
+ title: 'Issues & Evidence',
+ subtitle: 'Describe any problems encountered',
+})
+// Or update later
+section.with({
+ title: 'Updated Title',
+ isVisible: new JsonataBuilder('$show = true', { show: toggleField.state.value }),
+})
+section.addText({ name: 'description', label: 'Description' })
+```
+
+## Best Practices
+
+**Section titles:**
+
+- Keep concise (under 20 characters)
+- Use clear, descriptive names
+- Examples: "Contact Info", "Preferences", "Billing Details"
+
+**Grouping logic:**
+
+- Contact info: email, phone, address
+- Personal: name, date of birth, gender
+- Professional: company, title, department
+- Preferences: notification settings, language
+
+## Example: Multi-Section Step
+
+```typescript
+form.addStep({ instanceId: 'profile', icon: 'single-neutral' }, (step) => {
+ // Personal section
+ const personal = step.addSection({ title: 'Personal' })
+ personal.addText({ name: 'full-name', label: 'Full Name' })
+ personal.addDate({ name: 'dob', label: 'Date of Birth' })
+ // Contact section
+ const contact = step.addSection({ title: 'Contact' })
+ contact.addEmail({ name: 'email', label: 'Email' })
+ contact.addPhone({ name: 'phone', label: 'Phone' })
+ // Preferences section
+ const prefs = step.addSection({ title: 'Preferences' })
+ prefs.addCheckbox({ name: 'newsletter', label: 'Subscribe to newsletter' })
+ prefs.addDropdown({
+  name: 'language',
+  label: 'Language',
+  data: [
+   { label: 'English', value: 'en' },
+   { label: 'Spanish', value: 'es' },
+  ],
+ })
+})
+```