@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/icons.md

@@ -0,0 +1,142 @@
+## Searching Icons
+
+Use MCP to find valid icon names:
+
+```typescript
+mcp__jigx_common__search_sdk_icons({
+  queries: [{ query: "money dollar payment", category: "business-products" }]
+})
+```
+
+### Search Tips
+
+- Use 3-5 descriptive keywords
+- Include category for better results
+- Bad: "vintage" → vintage-tv
+- Good: "vintage car classic" → vintage-car
+
+### Common Categories
+
+| Category | Contains |
+| --- | --- |
+| `interface-essential` | UI elements, controls |
+| `users` | People, profiles, teams |
+| `business-products` | Commerce, finance, products |
+| `technology` | Devices, tech symbols |
+| `logos` | Brand logos |
+| `flags` | Country flags |
+| `transportation` | Vehicles, travel |
+| `maps-navigation` | Location, directions |
+
+## Using Icons
+
+### Field Icons
+
+Pass `icon` in constructor or use `.with()`:
+
+```typescript
+step.addEmail({
+ name: 'email',
+ label: 'Email',
+ icon: 'send-email-envelope',
+})
+step.addPhone({
+ name: 'phone',
+ label: 'Phone',
+ icon: 'phone',
+})
+```
+
+### Step Icons
+
+```typescript
+form.addStep(
+ {
+  instanceId: 'contact',
+  title: 'Contact',
+  icon: 'single-neutral',
+ },
+ (step) => {
+  step.addText({ name: 'name', label: 'Name' })
+ },
+)
+```
+
+### Icons in Dropdown/Choice Options
+
+```typescript
+step.addDropdown({
+ name: 'priority',
+ label: 'Priority',
+ data: [
+  { label: 'High', value: 'high', icon: 'alert-triangle' },
+  { label: 'Medium', value: 'medium', icon: 'alert-circle' },
+  { label: 'Low', value: 'low', icon: 'information-circle' },
+ ],
+})
+```
+
+## Updating Icons with .with()
+
+```typescript
+const field = step.addText({ name: 'status', label: 'Status' })
+// Update icon after construction
+field.with({ icon: 'check-circle-1' })
+```
+
+## Validation
+
+Icons are validated at build time:
+
+```typescript
+// Valid - builds successfully
+const step = form.addStep({ instanceId: 'billing', icon: 'currency-dollar' })
+
+// Invalid - build fails
+const step = form.addStep({ instanceId: 'billing', icon: 'made-up-icon-123' })  // Error: Invalid icon name
+```
+
+## Common Icons by Use Case
+
+| Use Case | Search Query | Example Icons |
+| --- | --- | --- |
+| Contact | "user person profile" | `user`, `user-profile-stacking` |
+| Email | "mail envelope" | `mail`, `envelope` |
+| Phone | "phone call" | `phone`, `phone-call` |
+| Money | "money dollar currency" | `currency-dollar`, `money-bag` |
+| Location | "location pin map" | `location`, `pin`, `map-marker` |
+| Calendar | "calendar date schedule" | `calendar`, `calendar-check` |
+| Settings | "settings gear cog" | `settings`, `cog`, `gear` |
+| Search | "search magnify" | `search`, `magnifying-glass` |
+| Add | "add plus create" | `add`, `plus`, `plus-circle` |
+| Delete | "delete trash remove" | `trash`, `delete`, `x-circle` |
+| Edit | "edit pencil write" | `pencil`, `edit`, `pen` |
+| Save | "save disk check" | `save`, `floppy-disk`, `check` |
+| Warning | "warning alert triangle" | `alert-triangle`, `warning` |
+| Info | "info information circle" | `information-circle`, `info` |
+| Success | "success check complete" | `check-circle`, `check` |
+| Error | "error x close" | `x-circle`, `x`, `close` |
+
+## Dynamic Icons
+
+Icons support `JsonataBuilder` for conditional values:
+
+```typescript
+const statusField = step.addDropdown({
+ name: 'status',
+ label: 'Status',
+ data: [
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' },
+ ],
+})
+step.addText({
+ name: 'statusDisplay',
+ label: 'Status Display',
+ icon: new IconBuilder(
+  new JsonataBuilder('$status = "active" ? "check-circle-1" : "x-circle"', {
+   status: statusField.state.value,
+  }),
+ ),
+})
+```

package/docs/index.md

@@ -0,0 +1,23 @@
+# Expert SDK Documentation
+
+Available documentation resources for Expert SDK forms and wizards.
+
+| Resource | Description |
+| --- | --- |
+expressions |
+| [JSONata Expressions](./jsonata-expressions.md) | JSONata expression language for dynamic values |
+| [Conditional Logic](./conditional-logic.md) | Show/hide and require fields based on other field values using JsonataBuilder |
+| [Validation Patterns](./validation-patterns.md) | Custom field validation using errorText with JsonataBuilder expressions |
+| [Sections](./sections.md) | Group related fields visually within steps using addSection() |
+| [Dropdown Fields](./dropdown-fields.md) | Single/multi-select dropdowns with static, dynamic, and arrayField data sources |
+| [Choice Fields](./choice-fields.md) | Radio buttons and chips with grid layout for small option sets |
+| [Array Fields](./array-fields.md) | Nested repeating forms for collecting multiple items (invoice line items, team members, checklist tasks) |
+| [Array Initialization](./predefined-array-items.md) | Static arrays (subforms, fixed lists) and dynamic arrays from related fields using ArrayField value property |
+| [Date Field](./date-field.md) | Date, time, and datetime picker fields with mode, minimum, and maximum constraints |
+| [Formatting](./formatting.md) | Number, currency, date, and unit formatting via format property and FormatBuilder class (ECMA-402 standard) |
+| [Media Fields](./media-fields.md) | File upload, signature capture, and avatar selection fields |
+| [Location Field](./location-field.md) | GPS coordinate capture with auto-fill and editable modes |
+| [Icons](./icons.md) | Search and use SDK icons in constructors with validation at build time |
+| [Runtime Variables](./runtime-variables.md) | System and Auth.user variables for device info and authenticated user data in JsonataBuilder |
+| [Internationalization](./i18n.md) | Multi-language support with I18nBuilder class, JsonataBuilder interpolation, and FormatBuilder for currency/date/number display |
+| [Submission Display](./submission-display.md) | Configure submission title and subtitle with JsonataBuilder or I18nBuilder using step.data.getFieldData() |

package/docs/jsonata-expressions.md

@@ -0,0 +1,200 @@
+## Static Values
+
+Pass values directly in constructor or via `.with()`:
+
+```typescript
+step.addEmail({
+ name: 'email',
+ label: 'Email',
+ helperText: 'We will never share your email',
+ isRequired: true,
+ icon: 'send-email-envelope',
+})
+```
+
+**When to use:**
+
+- Fixed labels, titles, descriptions
+- Boolean flags (true/false)
+- No dependencies on other data
+
+## Dynamic Expressions with JsonataBuilder
+
+Use `new JsonataBuilder()` when value depends on other fields or data:
+
+```typescript
+const age = step.addNumber({ name: 'age', label: 'Age' })
+step.addCheckbox({
+ name: 'consent',
+ label: 'I agree to terms',
+ isVisible: new JsonataBuilder('$age >= 18', { age: age.state.value }),
+})
+```
+
+## JsonataBuilder Pattern
+
+Constructor: `new JsonataBuilder(body, variables)`
+- **body**: JSONata expression using `$` prefix for variables
+- **variables**: Object mapping variable names to references
+
+```typescript
+const statusField = step.addDropdown({
+ name: 'status',
+ label: 'Status',
+ data: [
+  { label: 'Employed', value: 'employed' },
+  { label: 'Unemployed', value: 'unemployed' },
+ ],
+})
+step.addText({
+ name: 'company',
+ label: 'Company',
+ isRequired: new JsonataBuilder('$status = "employed"', { status: statusField.state.value }),
+})
+```
+
+## Multiple Variables
+
+```typescript
+const age = step.addNumber({ name: 'age', label: 'Age' })
+const country = step.addDropdown({
+ name: 'country',
+ label: 'Country',
+ data: [
+  { label: 'USA', value: 'usa' },
+  { label: 'Canada', value: 'canada' },
+ ],
+})
+step.addCheckbox({
+ name: 'consent',
+ label: 'I agree',
+ isRequired: new JsonataBuilder('$age >= 18 and $country = "usa"', {
+  age: age.state.value,
+  country: country.state.value,
+ }),
+})
+```
+
+## Variable Sources
+
+| Source | Use Case | Example |
+| --- | --- | --- |
+| `field.state.value` | Same-step field value | `age.state.value` |
+| `step.data.getFieldData()` | Cross-step field value | `step1.data.getFieldData('status')` |
+| `Auth.user.*` | Authenticated user data | `Auth.user.displayName` |
+| `System.*` | Device/environment data | `System.isOnline` |
+
+```typescript
+// User data pre-fill
+step.addText({
+ name: 'name',
+ label: 'Name',
+ value: new JsonataBuilder('$userName', { userName: Auth.user.displayName }),
+})
+// System data in helper text
+step.addText({
+ name: 'status',
+ label: 'Status',
+ helperText: new JsonataBuilder('$online ? "Connected" : "Offline mode"', {
+  online: System.isOnline,
+ }),
+})
+```
+
+## String Concatenation
+
+Use `&` (not `+`) for string concatenation:
+
+```typescript
+const step1 = form.addStep({ instanceId: 'name' }, (step) => {
+ step.addText({ name: 'firstName', label: 'First Name' })
+ step.addText({ name: 'lastName', label: 'Last Name' })
+})
+step1.with({ icon: 'monitor-user', title: 'Name' })
+form.with({
+ submissionItemTitle: new JsonataBuilder('$firstName & " " & $lastName', {
+  firstName: step1.data.getFieldData('firstName'),
+  lastName: step1.data.getFieldData('lastName'),
+ }),
+})
+```
+
+## Ternary Conditionals
+
+```typescript
+const statusField = step.addDropdown({
+ name: 'status',
+ label: 'Status',
+ data: [
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' },
+ ],
+})
+step.addText({
+ name: 'message',
+ label: 'Message',
+ helperText: new JsonataBuilder(
+  '$status = "active" ? "Account is active" : "Account is inactive"',
+  { status: statusField.state.value },
+ ),
+})
+```
+
+## Multi-Line Expressions
+
+For complex calculations:
+
+```typescript
+const step1 = form.addStep({ instanceId: 'products' }, (step) => {
+ step.addNumber({ name: 'quantity', label: 'Quantity' })
+ step.addNumber({ name: 'price', label: 'Price' })
+})
+step1.with({ icon: 'shopping-cart', title: 'Products' })
+form.addStep({ instanceId: 'summary', icon: 'summary-organize' }, (step) => {
+ step.addText({
+  name: 'total',
+  label: 'Total',
+  value: new JsonataBuilder(
+   `
+   $subtotal := $qty * $price;
+   $tax := $subtotal * 0.1;
+   $total := $subtotal + $tax;
+   "$" & $formatNumber($total, "#,##0.00")
+  `,
+   {
+    qty: step1.data.getFieldData('quantity'),
+    price: step1.data.getFieldData('price'),
+   },
+  ),
+  isDisabled: true,
+ })
+})
+```
+
+## Updating Properties with .with()
+
+Use `.with()` to change properties after construction:
+
+```typescript
+const toggleField = step.addCheckbox({ name: 'showNotes', label: 'Show Notes' })
+const field = step.addText({ name: 'notes', label: 'Notes' })
+// Update multiple properties
+field.with({
+ helperText: 'Additional details',
+ isVisible: new JsonataBuilder('$show = true', { show: toggleField.state.value }),
+})
+```
+
+## Common Mistakes
+
+**Wrong - == for equality:**
+
+```typescript
+new JsonataBuilder('$status == "active"', ...)  // Wrong
+```
+
+**Correct - single =:**
+
+```typescript
+new JsonataBuilder('$status = "active"', ...)  // Correct
+```

package/docs/media-fields.md

@@ -0,0 +1,107 @@
+## Media Upload
+
+```typescript
+step.addMedia({
+ name: 'documents',
+ label: 'Upload Documents',
+ isMultiple: true, // Enable multi-select
+})
+// Single file media field for comparison (default behavior)
+step.addMedia({
+ name: 'profile-photo',
+ label: 'Profile Photo',
+})
+```
+
+**Properties:**
+
+- `isMultiple: true` - Enable multiple file selection
+- Default: Single file upload
+
+## Local photos for offline sync
+
+For local-first Acumatica apps, media fields and picked files should usually be stored in a
+separate local child table rather than embedded directly into the parent record.
+
+Recommended shape per file row:
+
+- `id`
+- `parentId` — stable local parent row id
+- `recordId` — remote parent id / NoteID target used by the upload URL
+- `fileUrl` — local device URI
+- `filename`
+- `contentType`
+- `Remote`
+
+Identity rule:
+
+- keep `parentId` as the stable local parent row id
+- keep any remote upload target in a separate field such as `recordId`
+- generate each media child row id locally at creation time with `$uuid()`
+- do not repurpose a child screen `@ctx.jig.instanceId` as the media row id if the media flow is part of a parent aggregate
+
+Use `openMediaPicker` when you need direct camera/photo-library capture:
+
+```typescript
+const actions = screen.bottomPanel().add.list({
+  title: 'Add Photos',
+  icon: 'camera',
+  concurrency: 'sequential',
+})
+
+actions.actions.openMediaPicker({
+  instanceId: 'photo-picker',
+  mediaType: 'image',
+  isMultiple: true,
+  imageQuality: 50,
+})
+
+actions.actions
+  .executeEntities({ instanceId: 'save-photos' })
+  .local('ServiceOrderPhotos', 'save')
+  .data(`=$map(@ctx.actions.photo-picker.outputs.newItems, function($f){
+    {
+      "id": $uuid(),
+      "parentId": @ctx.jig.inputs.serviceOrderId,
+      "fileUrl": $f.uri,
+      "filename": $f.fileName,
+      "Remote": "new"
+    }
+  })`)
+```
+
+Notes:
+
+- `mediaType: 'image'` gives the native image flow, including camera/photo-library options
+- omit `imageCropping` when cropping should be disabled
+- use `imageQuality` deliberately for mobile upload size control
+- keep remote upload logic separate; picker/save is local only
+
+## Signature Capture
+
+```typescript
+step.addSignature({
+ name: 'agreementSignature',
+ label: 'Your Signature',
+ helperText: 'Please sign using your finger or stylus',
+})
+```
+
+## Avatar Field
+
+For profile picture selection:
+
+```typescript
+step.addAvatar({ name: 'avatar', label: 'Profile Picture' })
+```
+
+## Duration Picker
+
+For time duration input:
+
+```typescript
+step.addDurationPicker({
+ name: 'workDuration',
+ label: 'Work Duration',
+})
+```