@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/overview.md

@@ -0,0 +1,467 @@
+# Expert SDK Overview
+
+Available documentation resources for Core SDK forms and wizards.
+
+## Field Types
+
+Expert SDK provides these field types:
+
+| Type | Purpose | Default Required |
+| --- | --- | --- |
+| `text` | Single/multi-line text input | Yes |
+| `email` | Email with format validation | Yes |
+| `phone` | Phone with phone-pad keyboard | Yes |
+| `number` | Numeric input | Yes |
+| `checkbox` | Boolean toggle | **No** |
+| `date` | Date/time picker (mode: date/time/datetime) | Yes |
+| `dropdown` | Single/multi selection from list | Yes |
+| `choice-field` | Radio buttons or chips | Yes |
+| `media` | File/image upload | Yes |
+| `signature` | Signature capture pad | Yes |
+| `duration-picker` | Time duration selector | Yes |
+| `avatar-field` | Profile picture selector | Yes |
+| `location` | GPS coordinate capture | Yes |
+| `rating` | Star rating scale | Yes |
+| `slider` | Range selection with min/max | Yes |
+
+**Common properties** (all fields): `icon`, `helperText`, `errorText`, `value`, `isDisabled`, `isRequired`, `isVisible`
+
+**Ref:** `./dropdown-fields.md` for dropdown patterns
+**Ref:** `./choice-fields.md` for choice vs dropdown decision
+
+**Details:** [Field Types Overview](./field-types-overview.md)
+
+---
+
+## Field State
+
+Every field has `.state.value` that provides live access to the current field value. Updates immediately as user types.
+
+**Scope:** Current step only - not accessible from other steps.
+
+**Use for:**
+
+- Same-step conditional visibility
+- Same-step validation
+- Real-time field dependencies within one step
+
+**For cross-step data:** Use `step.data.getFieldData()` instead.
+
+**Dropdown special case:** Dropdowns also expose `dropdownField.state.selected` for full object access in the same step.
+
+**Details:** [Field State](./field-state.md)
+
+---
+
+## About JSONata
+
+The Expert SDK uses [JSONata](https://jsonata.org/) (v1.8) as its expression language. JSONata is a lightweight query and transformation language for JSON data, similar to XPath for XML.
+
+**Key characteristics and rules:**
+
+- Functional expression language (no side effects)
+- Path navigation with dot notation
+- Built-in functions for string, array, date manipulation
+- Single `=` for equality (not `==`)
+- `&` for string concatenation (not `+`)
+- `$now()` returns ISO string — use `$millis()` for date comparisons/diffs
+- `null` can't be used in math, string concat, comparisons, or array operations — always check first: `$x ? $x > 0 : false`
+
+Official docs: [jsonata.org](https://jsonata.org/)
+
+## Value Types
+
+Field properties support two modes:
+
+| Mode | API | Use When |
+| --- | --- | --- |
+| **Static** | Constructor arg or `.with()` | Constant values that never change |
+| **Dynamic** | `new JsonataBuilder(body, variables)` | Values dependent on other data |
+
+## JSONata Reference
+
+| Operator | Example | ⚠️ Never Use |
+| --- | --- | --- |
+| `=` | `$x = "value"` | `==` |
+| `!=` | `$x != "value"` | `!==`, `<>` |
+| `and` | `$a and $b` | `&&` |
+| `or` | `$a or $b` | `\|\|` |
+| `$not()` | `$not($a)` | `!`, `not` |
+| `&` | `$a & " " & $b` | `+` (except math) |
+| `? :` | `$x ? "yes" : "no"` | (ternary conditional) |
+| `:=` | `$temp := $x * 2` | (assignment) |
+| `..` | `1..10` | (range → array) |
+| `~>` | `$x ~> $uppercase` | (pipe/transform) |
+
+**Fallback pattern** (use ternary instead of elvis/null coalesce):
+
+```text
+$x ? $x : "default"
+```
+
+**Functions:**
+
+| Category | Functions |
+| --- | --- |
+| String | `$uppercase` `$lowercase` `$substring` `$length` `$trim` `$contains` `$split` `$join` |
+| Array | `$count` `$sum` `$max` `$min` `$distinct` `$sort` `$reverse` `$filter` `$map` `$in` |
+| Date | `$now` `$millis` `$toMillis` `$fromMillis` |
+| Type | `$string` `$number` `$boolean` `$type` |
+
+**Details:** [JSONata Expressions](./jsonata-expressions.md)
+
+---
+
+## Conditional Logic
+
+Make fields conditionally visible or required based on other field values using `JsonataBuilder`.
+
+**Common patterns:**
+
+- Show field when another has specific value
+- Require field only when relevant
+- Combine multiple conditions
+
+**Details:** [Conditional Logic](./conditional-logic.md)
+
+---
+
+## Field Validation
+
+Use `errorText` with `JsonataBuilder` to show validation messages based on field values. Messages appear when expression returns non-null string.
+
+**Pattern:** Expression returns error message string when invalid, `null` when valid.
+
+**Details:** [Validation Patterns](./validation-patterns.md)
+
+---
+
+## Sections
+
+Use `addSection()` to group related fields visually within a step. Improves form organization and user experience.
+
+**When to use:**
+
+- Group 3+ related fields together
+- Separate different types of information (personal vs professional)
+- Create visual hierarchy in longer forms
+- Improve scannability
+
+**Details:** [Sections](./sections.md)
+
+---
+
+## Dropdown Fields
+
+Four data source patterns for dropdown options:
+
+| Source | Use When | Data Type |
+| --- | --- | --- |
+| **Static** | Fixed list <20 items (priorities, statuses) | `{label, value, icon?}[]` |
+| **Dynamic** | Database-backed data (products, customers) | `DatasourceBuilder` |
+| **ArrayField** | Cross-step data from arrayField | `step.data.getArrayFieldData()` |
+| **Package** | ERP/CRM data via data packages (Acumatica, etc.) | `PackageDataBuilder` |
+
+**Dropdown vs Choice:**
+
+- Dropdown: >6 options OR long option labels
+- Choice: ≤6 options AND short labels
+
+**Multi-selection:** Set `isMultiple: true` for multiple selections.
+
+---
+
+## Static vs Dynamic Decision
+
+**Use static options when:**
+
+- Small fixed sets unlikely to change (Yes/No, gender, true/false)
+- Values tied to app logic (status enums where code branches on specific values)
+- Fewer than ~8 items that are universal across deployments
+
+**Use dynamic (lookup table) when:**
+
+- User says "managed", "from database", "editable", "configurable"
+- Domain/reference data that may grow (countries, products, customers, categories)
+- User provides a large list (>10 items)
+- Values that different orgs/deployments would customize
+- Data that non-developers should be able to edit in management portal
+
+**If uncertain**, ask the user whether the options are fixed or may change over time.
+
+---
+
+### Value Collection
+
+If values are clear from context, suggest initial values and ask for confirmation. If unclear, ask the user what values to populate.
+
+When ambiguous (e.g., "add a status field" without specifying values), ask the user whether the values should be static or managed dynamically.
+
+---
+
+### Displaying Lookup Data
+
+When showing lookup table contents to the user, format as a markdown table:
+
+| Value | Label | Sort |
+| --- | --- | ---: |
+| high | High | 1 |
+| medium | Medium | 2 |
+| low | Low | 3 |
+
+---
+
+## Choice Fields
+
+Use choice fields for small, fixed option sets displayed as radio buttons or chips.
+
+**When to use:**
+
+- ≤6 options with short labels
+- Visual selection (user sees all options at once)
+- Grid layout desired
+
+**Choice vs Dropdown:**
+
+| Criteria | Choice | Dropdown |
+| --- | --- | --- |
+| Options count | ≤6 | >6 |
+| Label length | Short | Any |
+| Display | All visible | Collapsed list |
+
+**Choice vs Checkbox for yes/no:**
+
+- Required yes/no: Use choice (checkbox fails validation when unchecked)
+- 3-state logic: Use choice (Yes/No/NA, True/False/Unknown)
+- Optional toggle: Use checkbox
+
+**Details:** [Choice Fields](./choice-fields.md)
+
+---
+
+## Array Fields
+
+**Use ArrayField when you need a "form within a form"** - a repeatable group of fields where users can add/remove multiple entries of the same structure.
+
+**When to use:**
+
+- Invoice/order with multiple line items (product, quantity, price per item)
+- Team registration with multiple members (name, email, role per person)
+- Inspection checklist with multiple items (item name, status, notes per check)
+- Any scenario requiring "Add another [X]" functionality
+
+**How it works:** ArrayField creates a nested, repeatable form section. Each item contains the same field structure. Users tap "Add" to create new items and can remove existing ones.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | string | Field identifier (required) |
+| `label` | string | Display label (required) |
+| `title` | TextValueBuilder | Item title in the array list (required) |
+| `subtitle` | TextValueBuilder | Item subtitle in the array list |
+| `description` | TextValueBuilder | Item description in the array list |
+| `addButtonLabel` | string | Custom "Add" button text |
+| `value` | ArrayFieldValue[] \| JsonataBuilder | Initial data for fixed-size arrays (hides add/delete) |
+| `keyField` | string | Field to match init items with saved data (required with `value`) |
+
+**Three ways to use ArrayField:**
+
+| Mode | `value` | Behavior |
+| --- | --- | --- |
+| **User-managed** | (not set) | Users add/remove items freely |
+| **Static** | Array literal | Fixed items (subform, checklist) |
+| **Dynamic** | Expression/field ref | Items regenerate from source |
+
+**Ref:** `./predefined-array-items.md` for static and dynamic initialization
+
+**Title is required** - identifies items in the list and delete confirmation.
+
+**Ref:** `./cross-step-data.md` for accessing array data in other steps
+
+**Recognize repeated data patterns:**
+
+| User describes... | Use |
+| --- | --- |
+| "3 passengers on booking" | ArrayField + 3 predefined items |
+| "5 emergency contacts" | ArrayField + 5 predefined items |
+| "Add ingredients to recipe" | ArrayField (user-managed) |
+| "Track project milestones" | ArrayField (user-managed) |
+
+**Anti-pattern:** Creating multiple sections with duplicated fields (e.g., "Contact 1 Name", "Contact 1 Phone", "Contact 2 Name"...). This creates longer forms and inconsistent data structure.
+
+**Default rule:** Same data type captured multiple times → ArrayField, not duplicated sections.
+
+**Details:** [Array Fields](./array-fields.md)
+
+---
+
+## Array Initialization
+
+Use ArrayField with `value` to initialize items. Add/delete buttons hidden automatically.
+
+| Mode | `value` | Regenerates | Use Case |
+| --- | --- | --- | --- |
+| **Subform** | 1 static item | No | Nested details (vehicle, address) |
+| **Fixed list** | N static items | No | Scorecards, checklists |
+| **Dynamic** | Expression/field ref | Yes | Date ranges, count from field |
+
+**Key properties:**
+
+| Property | Description |
+| --- | --- |
+| `value` | Initial items (static array or JsonataBuilder expression) |
+| `keyField` | Field to match items with saved data (required for dynamic, optional for static) |
+
+**Ref:** `./array-fields.md` for full ArrayField API
+
+**Details:** [Array Initialization](./predefined-array-items.md)
+
+---
+
+## Date Field
+
+Use `addDate()` to capture dates, times, or both with a native picker.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `mode` | `'date'` \| `'time'` \| `'datetime'` | Picker type (default: 'date') |
+| `minimum` | `string` \| `number` \| `JsonataBuilder` | Earliest selectable date |
+| `maximum` | `string` \| `number` \| `JsonataBuilder` | Latest selectable date |
+
+| Mode | Picker | Use Case |
+| --- | --- | --- |
+| `'date'` | Date only | Birthdays, deadlines |
+| `'time'` | Time only | Meeting times, schedules |
+| `'datetime'` | Both | Appointments, events |
+
+**Details:** [Date Field](./date-field.md)
+
+---
+
+## Formatting
+
+Two ways to format values:
+
+| Approach | Use Case |
+| --- | --- |
+| **Field `format` property** | Format numbers in disabled (read-only) fields |
+| **`FormatBuilder` class** | Format any value for text display: `submissionItemTitle`, `submissionItemSubtitle`, arrayField `title`/`subtitle`/`description`, step `title` |
+
+**Details:** [Formatting](./formatting.md)
+
+---
+
+**Read the YAML schemas before writing any SQL query.** They document available tables, fields, nullable columns, relationships, and common query patterns.
+
+### When to Use Custom Sync Parameters
+
+| Use Case | Parameters |
+| --- | --- |
+| Fetch all records | None (uses package defaults) |
+| Only sync active records | Custom filter to limit fetched records |
+| Reduce sync volume | Filter expression |
+| Different expand per screen | Expand override |
+
+### Handling Null Values (COALESCE)
+
+External data fields can be null. **Use COALESCE** for display fields to prevent empty UI labels. Check the package's schema files for which fields are nullable and their recommended fallbacks.
+
+### JOIN Queries (Multiple Tables)
+
+**Always wrap `json_extract()` in `TRIM()` for JOIN conditions.** External data often contains leading/trailing whitespace that breaks equality comparisons.
+
+---
+
+## Media & Specialized Fields
+
+Core SDK provides these media capture fields:
+
+| Type | Purpose |
+| --- | --- |
+| `media` | File/image upload (single or multiple) |
+| `signature` | Signature capture pad |
+| `avatar-field` | Profile picture selector |
+| `duration-picker` | Time duration selector |
+
+**Details:** [Media Fields](./media-fields.md)
+
+---
+
+## Location Field
+
+The `addLocation()` method creates a field that auto-captures GPS coordinates as "lat,lng" format.
+
+**Two patterns:**
+
+| Pattern | Use Case | isDisabled |
+| --- | --- | --- |
+| Current location (readonly) | Check-ins, service visits, asset tagging | `true` |
+| Generic location (editable) | Delivery addresses, event venues | `false` (default) |
+
+**Details:** [Location Field](./location-field.md)
+
+---
+
+## Icons
+
+Expert SDK includes 18,000+ icons. Icon names are validated at build time - invalid names cause build failures.
+
+**Never guess icon names** - always search via MCP.
+
+**Details:** [Icons](./icons.md)
+
+---
+
+## Runtime Variables
+
+Access runtime context using `System` and `Auth.user` from Expert SDK:
+
+```typescript
+import { Auth, System, JsonataBuilder } from '@jigx/expert-sdk'
+```
+
+| Namespace | Purpose |
+| --- | --- |
+| `System.*` | Device info, network status, location |
+| `Auth.user.*` | Authenticated user data |
+
+**Details:** [Runtime Variables](./runtime-variables.md)
+
+---
+
+## Internationalization (i18n)
+
+Build multi-language forms using the `I18nBuilder` class. Supports:
+
+- Translation keys with fallback messages
+- Placeholder interpolation with `JsonataBuilder`
+- Formatted values with `FormatBuilder` class
+- Formatted strings combining multiple values
+
+**Priority:** `I18nBuilder` > `format property` > `direct value`
+
+
+**When to use I18nBuilder:**
+- Combining multiple field values with text
+- Formatting dates, currencies, numbers, or percentages
+- Multi-language support needed
+- Complex string interpolation
+
+**Details:** [Internationalization](./i18n.md)
+
+---
+
+## Submission Display
+
+Use `step.data.getFieldData()` to configure what information appears in the submission list. Shows meaningful data instead of generic IDs.
+
+**Properties (both required):**
+- `submissionItemTitle` — primary text shown for each submission
+- `submissionItemSubtitle` — secondary text shown below the title
+
+**Important:** Both `submissionItemTitle` and `submissionItemSubtitle` must be defined. Form validation will fail if either is missing.
+
+**Date/number formatting:** Use `FormatBuilder` when displaying date, currency, or number values in `submissionItemTitle` or `submissionItemSubtitle`. See `./formatting.md` for details.
+
+**Details:** [Submission Display](./submission-display.md)
+
+---

package/docs/pattern-build-deploy.md

@@ -0,0 +1,91 @@
+# Pattern: Build and Deploy
+
+## Build order matters
+
+Register in this order in `app.ts`:
+
+1. Database tables
+2. App-scoped datasources
+3. Functions (before actions that reference them)
+4. Global actions (before screens that reference them)
+5. Tab content screens (before the tabs screen that embeds them)
+6. Tabs screen
+7. Other screens
+
+## Prerequisites
+
+Core SDK must be compiled before workspace projects can build (tsx imports compiled output):
+
+```bash
+yarn workspace @jigx/core-sdk build
+```
+
+## Commands
+
+```bash
+# Typecheck
+npx tsc --noEmit --strict --target es2022 --module esnext \
+  --moduleResolution bundler --customConditions source \
+  --esModuleInterop --skipLibCheck workspace/acumatica-apps/create-customer/src/app.ts
+
+# Build JSON + YAML
+npx tsx workspace/build.ts workspace/acumatica-apps/create-customer
+npx tsx workspace/build-yaml.ts workspace/acumatica-apps/create-customer
+
+# Deploy (env vars or .env)
+STAMP=PROD ORGANIZATION_ID="..." JIGX_API_KEY="..." \
+  ./workspace/acumatica-apps/create-customer/build-publish.sh
+```
+
+## Build scripts
+
+| Script | Output | Location |
+| ---: | --- | --- |
+| `workspace/build.ts` | `build/output.json` + `build/output.yaml` | Single merged file |
+| `workspace/build-yaml.ts` | `build/jigx-project/` | Individual `.jigx` files matching standard Jigx YAML project structure |
+| `build-publish.sh` | Builds + publishes to Jigx API | Per-project script |
+
+## YAML project output
+
+The `build-yaml.ts` script decomposes the single JSON output into individual files:
+
+| JSON key | Output |
+| ---: | --- |
+| `name`, `title`, `category`, `tabs` | `index.jigx` |
+| `databases["default"]` | `databases/default.jigx` |
+| `datasources["<id>"]` | `datasources/<id>.jigx` |
+| `jigs["<id>"]` | `jigs/<id>.jigx` (screen-scoped datasources stay inline) |
+| `actions["<id>"]` | `actions/<id>.jigx` |
+| `functions["<id>"]` | `functions/<id>.jigx` |
+
+Internal IDs (`jigId`, `datasourceId`, `instanceId`, `databaseId`) are stripped — they're implied by the filename.
+
+## Deploy script (`build-publish.sh`)
+
+Each project has a `build-publish.sh` that builds and publishes to the Jigx API. Required env vars (from `.env` or inline):
+
+| Variable | Description |
+| ---: | --- |
+| `ORGANIZATION_ID` | Jigx organization UUID |
+| `JIGX_API_KEY` | PAT for Jigx API (store in `.env`, never commit) |
+| `STAMP` | `DEV` (default) or `PROD` |
+
+API base URLs:
+
+- DEV: `https://us-west-2.dev-api.jigx.com/v2.0`
+- PROD: `https://us-east-1.api.jigx.com/v2.0`
+
+Deploy flow:
+
+1. Build `output.json` via `workspace/build.ts`
+2. `GET /strata/organizations/{orgId}/solutions/{appName}` — look up existing solution
+3. If 404: `POST /strata/organizations/{orgId}/solutions/` — create new solution
+4. `PUT /strata/organizations/{orgId}/solutions/{solutionId}/content` — publish full `output.json` as body
+
+All calls use `Authorization: Bearer {JIGX_API_KEY}`.
+
+Inline env vars override `.env` defaults — pass credentials on the command line to avoid storing prod keys:
+
+```bash
+STAMP=PROD ORGANIZATION_ID="..." JIGX_API_KEY="..." ./workspace/acumatica-apps/create-customer/build-publish.sh
+```