@jigx/core-sdk 1.1.0 → 1.2.0-rc

package/dist/assets/extracted-core-sdk-types.yaml

@@ -2617,6 +2617,8 @@ types:
         fileName: Expression|string
         /** HTML content to convert to PDF */
         html: Expression|string
+        /** Optional page size, orientation, and margins. Defaults to letter portrait with no margins. */
+        page?: PdfPageOptions
       }
   GoBackActionInput:
     domain: action
@@ -3707,11 +3709,13 @@ types:
          * @param options.fileName - PDF file name
          * @param options.html - HTML content
          * @param options.instanceId - Instance ID for tracking
+         * @param options.page - Optional page size, orientation, and margins
          */
         generatePdf(options: {
         fileName: Expression|string
         html: Expression|string
         instanceId?: KegInstanceId|string
+        page?: PdfPageOptions
         }): JaGeneratePdfBuilder
         /**
          * Create an open-app-settings action builder
@@ -9529,6 +9533,60 @@ types:
       type PathsData = Expression|string | {
         data: Expression|string
       }
+  PdfPageMargin:
+    domain: action
+    code: |-
+      /**
+       * PDF page margin specification.
+       *
+       * - `'none'` — zero margins on all sides (default).
+       * - `number` — uniform margin in PDF points on all sides (72pt = 1in).
+       * - object — independent per-side margins in PDF points; omitted sides default to 0.
+       */
+      type PdfPageMargin = 'none' | number | {
+        top?: number
+        right?: number
+        bottom?: number
+        left?: number
+      }
+  PdfPageOptions:
+    domain: action
+    code: |-
+      /**
+       * PDF page configuration.
+       *
+       * The runtime constructs the physical page bounds from these values before the
+       * HTML is rendered. CSS `@page` rules do not control the PDF page size — to
+       * avoid overflow, match the body dimensions to the configured size in points.
+       *
+       * When `width` and `height` are both provided they override `size`/`orientation`.
+       *
+       * @see PdfPageSize
+       * @see PdfPageOrientation
+       * @see PdfPageMargin
+       */
+      interface PdfPageOptions {
+        /** Named paper size. Default: `'letter'`. */
+        size?: PdfPageSize
+        /** Page orientation. Default: `'portrait'`. */
+        orientation?: PdfPageOrientation
+        /** Custom page width in PDF points (72pt = 1in). When set with `height`, overrides `size`/`orientation`. */
+        width?: number
+        /** Custom page height in PDF points (72pt = 1in). When set with `width`, overrides `size`/`orientation`. */
+        height?: number
+        /** Page margins. Default: `'none'`. */
+        margin?: PdfPageMargin
+      }
+  PdfPageOrientation:
+    domain: action
+    code: |-
+      /** PDF page orientation. */
+      type PdfPageOrientation = 'portrait' | 'landscape'
+  PdfPageSize:
+    domain: action
+    code: |-
+      /** Named PDF paper sizes. */
+      type PdfPageSize = 'letter' | 'legal' | 'tabloid' | 'a4' | 'a3'
   PieChartLayout:
     domain: component
     code: type PieChartLayout = 'pie' | 'arch'

package/dist/assets/type-extraction-cache.json

@@ -1,9 +1,9 @@
 {
   "version": "1.0.0",
-  "sourceHash": "8b7a1f45e39c7460275edc85ed96a0ef",
-  "timestamp": 1778660398642,
+  "sourceHash": "4054b27eb8116771508a3e3fbe66d3cf",
+  "timestamp": 1778854916954,
   "stats": {
     "inputFiles": 300,
-    "extractionTimeMs": 10955
+    "extractionTimeMs": 11351
   }
 }

package/docs/array-fields.md

@@ -0,0 +1,371 @@
+## Basic Setup
+
+Create an array field and set its required title:
+
+```typescript
+const members = step.addArrayField({ name: 'members', label: 'Team Members' })
+// Title is required - identifies items in list
+members.with({
+ title: new JsonataBuilder('$name', { name: members.getCurrentItemRef('name') }),
+})
+// Add fields to each item
+members.addText({ name: 'name', label: 'Name' })
+members.addEmail({ name: 'email', label: 'Email' })
+```
+
+## getCurrentItemRef() - Item Field References
+
+Reference fields within the current array item using `getCurrentItemRef()`:
+
+```typescript
+const members = step.addArrayField({ name: 'members', label: 'Members' })
+// Single field reference
+members.with({
+ title: new JsonataBuilder('$n', { n: members.getCurrentItemRef('name') }),
+})
+// Combine multiple fields
+members.with({
+ subtitle: new JsonataBuilder('$first & " " & $last', {
+  first: members.getCurrentItemRef('firstName'),
+  last: members.getCurrentItemRef('lastName'),
+ }),
+})
+members.addText({ name: 'name', label: 'Name' })
+members.addText({ name: 'firstName', label: 'First Name' })
+members.addText({ name: 'lastName', label: 'Last Name' })
+```
+
+## getCurrentItemLabelRef() - Dropdown Labels
+
+For dropdown fields inside arrayField, use `getCurrentItemLabelRef()` to display the human-readable label instead of the value id:
+
+```typescript
+const items = step.addArrayField({
+ name: 'orderItems',
+ label: 'Order Items',
+})
+// Display dropdown LABEL (e.g., "Electronics") in item title
+// instead of dropdown VALUE (e.g., "electronics")
+items.with({
+ title: new JsonataBuilder('$product & " - " & $categoryLabel', {
+  product: items.getCurrentItemRef('productName'),
+  categoryLabel: items.getCurrentItemLabelRef('category'),
+ }),
+})
+items.addText({ name: 'productName', label: 'Product Name' })
+items.addDropdown({
+ name: 'category',
+ label: 'Category',
+ data: [
+  { label: 'Electronics', value: 'electronics' },
+  { label: 'Clothing', value: 'clothing' },
+  { label: 'Home & Garden', value: 'home' },
+ ],
+})
+items.addNumber({ name: 'quantity', label: 'Quantity' })
+```
+
+| Method | Returns | Use Case |
+| --- | --- | --- |
+| `arrayField.getCurrentItemRef('dropdown')` | Value (id) | Business logic |
+| `arrayField.getCurrentItemLabelRef('dropdown')` | Label (text) | Display in title/subtitle |
+
+## Item Display
+
+Customize how items appear in the list:
+
+```typescript
+const items = step.addArrayField({ name: 'items', label: 'Order Items' })
+// Required title
+items.with({
+ title: new JsonataBuilder('$name', { name: items.getCurrentItemRef('productName') }),
+})
+// Optional subtitle with formatted currency
+items.with({
+ subtitle: new I18nBuilder('item.subtitle', 'Qty: {qty} × {price}', {
+  qty: new JsonataBuilder('$qty', {
+   qty: items.getCurrentItemRef('quantity'),
+  }),
+  price: new FormatBuilder(
+   new JsonataBuilder('$price', {
+    price: items.getCurrentItemRef('unitPrice'),
+   }),
+   { numberStyle: 'currency', currency: 'USD' },
+  ),
+ }),
+})
+// Optional description
+items.with({
+ description: new JsonataBuilder('$notes', { notes: items.getCurrentItemRef('notes') }),
+})
+items.addText({ name: 'productName', label: 'Product Name' })
+items.addNumber({ name: 'quantity', label: 'Quantity' })
+items.addNumber({ name: 'unitPrice', label: 'Unit Price' })
+items.addText({ name: 'notes', label: 'Notes' })
+```
+
+## Nested Fields
+
+Array fields support all standard field types:
+
+```typescript
+const items = step.addArrayField({ name: 'items', label: 'Line Items' })
+items.with({
+ title: new JsonataBuilder('$p', { p: items.getCurrentItemRef('product') }),
+})
+items.addText({ name: 'product', label: 'Product Name' })
+items.addNumber({ name: 'quantity', label: 'Quantity' })
+items.addNumber({ name: 'unitPrice', label: 'Unit Price' })
+items.addDropdown({
+ name: 'category',
+ label: 'Category',
+ data: [
+  { label: 'Electronics', value: 'electronics' },
+  { label: 'Clothing', value: 'clothing' },
+ ],
+})
+```
+
+## Sections Within Array Fields
+
+Group related fields within array items:
+
+```typescript
+const items = step.addArrayField({
+ name: 'items',
+ label: 'Order Items',
+ addButtonLabel: 'Add Item',
+})
+// Set title for array items - need to use .with() since we need the variable declared first
+items.with({
+ title: new JsonataBuilder('$productName', {
+  productName: items.getCurrentItemRef('product-name'),
+ }),
+})
+const section = items.addSection()
+section.with({ title: 'Product Details' })
+section.addText({ name: 'product-name', label: 'Product' })
+section.addNumber({ name: 'quantity', label: 'Quantity' })
+```
+
+## Configuration Options
+
+Customize array behavior:
+
+```typescript
+const tasks = step.addArrayField({
+ name: 'tasks',
+ label: 'Tasks',
+ addButtonLabel: 'Add Task', // Custom button text
+})
+tasks.with({
+ title: new JsonataBuilder('$t', { t: tasks.getCurrentItemRef('taskName') }),
+})
+tasks.addText({ name: 'taskName', label: 'Task Name' })
+```
+
+## Conditional Visibility
+
+Show/hide array field based on conditions:
+
+```typescript
+const hasTeam = step.addCheckbox({
+ name: 'has-team',
+ label: 'This project has a team',
+})
+const teamMembers = step.addArrayField({
+ name: 'team-members',
+ label: 'Team Members',
+ addButtonLabel: 'Add Team Member',
+ // Option 1: Set title in constructor
+ title: 'Team Member',
+})
+// Option 2: Set title via .with()
+teamMembers.with({
+ // Can't use in constructor because the variable doesn't exist yet
+ title: new JsonataBuilder('$name', { name: teamMembers.getCurrentItemRef('member-name') }),
+ // Use Jsonata expression to show array field only when checkbox is checked
+ isVisible: new JsonataBuilder('$hasTeam = true', { hasTeam: hasTeam.state.value }),
+})
+teamMembers.addText({
+ name: 'member-name',
+ label: 'Name',
+})
+teamMembers.addEmail({
+ name: 'member-email',
+ label: 'Email',
+})
+```
+
+## Formatting in Array Item title / subtitle / description
+
+**Date fields MUST use `FormatBuilder`** in arrayField `title`, `subtitle`, and `description`. Without it, unreadable ISO 8601 strings like `"2024-01-15T14:30:00Z"` display instead of human-readable dates.
+
+**Number/currency fields** should also use `FormatBuilder` for locale-aware display instead of JSONata string concatenation.
+
+**Ref:** `./formatting.md` for `FormatBuilder` usage, date format codes, and common mistakes
+
+## Retrieving Array Data
+
+Access array items from other steps using `getArrayFieldData()`:
+
+```typescript
+// Step 1: Collect team members
+const step1 = form.addStep({ instanceId: 'team' }, (step) => {
+ const members = step.addArrayField({
+  name: 'members',
+  label: 'Team Members',
+ })
+ members.with({
+  title: new JsonataBuilder('$name', { name: members.getCurrentItemRef('name') }),
+ })
+ members.addText({ name: 'name', label: 'Name' })
+ members.addText({ name: 'role', label: 'Role' })
+})
+step1.with({ icon: 'multiple-users-3', title: 'Team Members' })
+// Step 2: Select team lead from collected members
+const step2 = form.addStep({ instanceId: 'lead' }, (step) => {
+ step.addDropdown({
+  name: 'teamLead',
+  label: 'Select Team Lead',
+  // IMPORTANT: Use getArrayFieldData to map arrayField items to dropdown options
+  data: step1.data.getArrayFieldData('members'),
+ })
+})
+step2.with({ icon: 'messages-people-user-check', title: 'Select Lead' })
+```
+
+**Custom mapping:**
+
+```typescript
+const step1 = form.addStep({ instanceId: 'step1' }, (step) => {
+ const items = step.addArrayField({ name: 'items', label: 'Items', title: 'Item' })
+ items.addText({ name: 'code', label: 'Code' })
+ items.addText({ name: 'description', label: 'Description' })
+})
+step1.with({ icon: 'list', title: 'Items' })
+const step2 = form.addStep({ instanceId: 'step2' }, (step) => {
+ step.addDropdown({
+  name: 'selectedItem',
+  label: 'Select Item',
+  // IMPORTANT: Use getArrayFieldData to map arrayField items to dropdown options
+  data: step1.data.getArrayFieldData('items', {
+   valueKey: 'code',
+   labelKey: 'description',
+  }),
+ })
+})
+step2.with({ icon: 'check', title: 'Select' })
+```
+
+## Data Structure
+
+Each array item has this structure:
+
+| Property | Description |
+| --- | --- |
+| `id` | Auto-generated UUID (used as default dropdown value) |
+| `item_title` | Captured from title expression (used as default dropdown label) |
+| `<fieldName>` | Values from each nested field |
+
+**item_title mechanism:** A hidden field automatically captures the evaluated title expression when saving. This enables dropdown compatibility - when you use `getArrayFieldData()`, the `item_title` is available as the default label without re-evaluating the expression.
+
+```typescript
+// Example data structure after user adds items:
+[
+  { id: "uuid-1", item_title: "John Doe", name: "John Doe", email: "john@example.com" },
+  { id: "uuid-2", item_title: "Jane Smith", name: "Jane Smith", email: "jane@example.com" }
+]
+```
+
+## Use Case: Team Members
+
+Classic pattern for collecting people with name/email:
+
+```typescript
+const members = step.addArrayField({
+ name: 'teamMembers',
+ label: 'Team Members',
+ addButtonLabel: 'Add Member',
+})
+members.with({
+ title: new JsonataBuilder('$name', { name: members.getCurrentItemRef('fullName') }),
+})
+members.with({
+ subtitle: new JsonataBuilder('$role', { role: members.getCurrentItemRef('role') }),
+})
+members.addText({ name: 'fullName', label: 'Full Name' })
+members.addEmail({ name: 'email', label: 'Email' })
+members.addDropdown({
+ name: 'role',
+ label: 'Role',
+ data: [
+  { label: 'Developer', value: 'developer' },
+  { label: 'Designer', value: 'designer' },
+  { label: 'Manager', value: 'manager' },
+ ],
+})
+```
+
+## Use Case: Line Items
+
+Invoice or order items with quantities:
+
+```typescript
+const items = step.addArrayField({
+ name: 'lineItems',
+ label: 'Order Items',
+})
+items.with({
+ title: new JsonataBuilder('$product', {
+  product: items.getCurrentItemRef('productName'),
+ }),
+})
+items.with({
+ subtitle: new I18nBuilder('line-item.subtitle', 'Qty: {qty} × {price}', {
+  qty: new JsonataBuilder('$qty', {
+   qty: items.getCurrentItemRef('quantity'),
+  }),
+  price: new FormatBuilder(
+   new JsonataBuilder('$price', {
+    price: items.getCurrentItemRef('unitPrice'),
+   }),
+   { numberStyle: 'currency', currency: 'USD' },
+  ),
+ }),
+})
+items.addText({ name: 'productName', label: 'Product' })
+items.addNumber({ name: 'quantity', label: 'Quantity' })
+items.addNumber({ name: 'unitPrice', label: 'Unit Price' })
+```
+
+## Use Case: Inspection Checklist
+
+Status tracking with notes:
+
+```typescript
+const checks = step.addArrayField({
+ name: 'inspectionItems',
+ label: 'Inspection Checklist',
+})
+checks.with({
+ title: new JsonataBuilder('$item', { item: checks.getCurrentItemRef('checkItem') }),
+})
+checks.with({
+ subtitle: new JsonataBuilder('$uppercase($status)', {
+  status: checks.getCurrentItemRef('status'),
+ }),
+})
+checks.addText({ name: 'checkItem', label: 'Item to Check' })
+checks.addDropdown({
+ name: 'status',
+ label: 'Status',
+ data: [
+  { label: 'Pass', value: 'pass', icon: 'check-circle-1' },
+  { label: 'Fail', value: 'fail', icon: 'remove-circle' },
+  { label: 'N/A', value: 'na', icon: 'remove-circle-1' },
+ ],
+})
+checks.addText({ name: 'notes', label: 'Notes', isMultiline: true })
+checks.addMedia({ name: 'photo', label: 'Photo Evidence' })
+```

package/docs/conditional-logic.md

@@ -0,0 +1,178 @@
+## Basic Conditional Visibility
+
+```typescript
+const attendanceType = step.addDropdown({
+ name: 'attendance',
+ label: 'Attendance Type',
+ data: [
+  { label: 'In Person', value: 'in-person' },
+  { label: 'Virtual', value: 'virtual' },
+ ],
+})
+// Show only for in-person attendance
+step.addText({
+ name: 'hotel-preferences',
+ label: 'Hotel Preferences',
+ isVisible: new JsonataBuilder('$attendance = "in-person"', {
+  attendance: attendanceType.state.value,
+ }),
+})
+```
+
+## Conditional Required
+
+Often combine with visibility - if a field is shown, it should be required:
+
+```typescript
+const attendanceType = step.addDropdown({
+ name: 'attendance',
+ label: 'Attendance Type',
+ data: [
+  { label: 'In Person', value: 'in-person' },
+  { label: 'Virtual', value: 'virtual' },
+ ],
+})
+const visibilityCondition = new JsonataBuilder('$attendance = "in-person"', {
+ attendance: attendanceType.state.value,
+})
+// Show and require together using same condition
+step.addText({
+ name: 'hotel-preferences',
+ label: 'Hotel Preferences',
+ isVisible: visibilityCondition,
+ isRequired: new JsonataBuilder('$attendance = "in-person"', {
+  attendance: attendanceType.state.value,
+ }),
+})
+```
+
+**Best practice:** Apply same condition to both `isVisible` and `isRequired`.
+
+## Multiple Conditions
+
+Combine conditions with `and`/`or`:
+
+```typescript
+const attendance = step.addDropdown({
+ name: 'attendance',
+ label: 'Attendance',
+ data: [
+  { label: 'In Person', value: 'in-person' },
+  { label: 'Virtual', value: 'virtual' },
+ ],
+})
+const needsAccommodation = step.addCheckbox({
+ name: 'needs-accommodation',
+ label: 'I need accommodation',
+})
+// Show when BOTH conditions are true
+step.addText({
+ name: 'hotel-preferences',
+ label: 'Hotel Preferences',
+ isVisible: new JsonataBuilder('$attendance = "in-person" and $needsAccommodation = true', {
+  attendance: attendance.state.value,
+  needsAccommodation: needsAccommodation.state.value,
+ }),
+})
+```
+
+## Either/Or Conditions
+
+```typescript
+const email = step.addEmail({
+ name: 'email',
+ label: 'Email',
+})
+const phone = step.addPhone({
+ name: 'phone',
+ label: 'Phone',
+ isRequired: new JsonataBuilder('$email = null or $email = ""', {
+  email: email.state.value,
+ }),
+})
+email.with({
+ isRequired: new JsonataBuilder('$phone = null or $phone = ""', {
+  phone: phone.state.value,
+ }),
+})
+```
+
+## Cross-Step Conditions
+
+For conditions based on other steps, use `step.data.getFieldData()`:
+
+```typescript
+const step1 = form.addStep({ instanceId: 'type' }, (step) => {
+ step.addDropdown({
+  name: 'account-type',
+  label: 'Account Type',
+  data: [
+   { label: 'Personal', value: 'personal' },
+   { label: 'Business', value: 'business' },
+  ],
+ })
+})
+step1.with({ icon: 'monitor-user', title: 'Account Type' })
+form.addStep({ instanceId: 'business', icon: 'small-office-building' }, (step) => {
+ // Required only for business accounts
+ step.addText({
+  name: 'tax-id',
+  label: 'Tax ID',
+  isRequired: new JsonataBuilder('$type = "business"', {
+   type: step1.data.getFieldData('account-type'),
+  }),
+ })
+})
+```
+
+**Ref:** `./cross-step-data.md` for more on `getFieldData()`
+
+## Conditional Disabled
+
+Make fields read-only based on conditions:
+
+```typescript
+const status = step.addDropdown({
+ name: 'status',
+ label: 'Status',
+ data: [
+  { label: 'Draft', value: 'draft' },
+  { label: 'Submitted', value: 'submitted' },
+ ],
+})
+// Can't edit title after submission
+step.addText({
+ name: 'title',
+ label: 'Title',
+ isDisabled: new JsonataBuilder('$status = "submitted"', {
+  status: status.state.value,
+ }),
+})
+```
+
+## Updating Conditions with .with()
+
+```typescript
+const toggleField = step.addCheckbox({
+ name: 'show-notes',
+ label: 'Add Notes',
+})
+const field = step.addText({ name: 'notes', label: 'Notes' })
+// Add conditions after construction
+field.with({
+ isVisible: new JsonataBuilder('$show = true', { show: toggleField.state.value }),
+ isRequired: new JsonataBuilder('$show = true', { show: toggleField.state.value }),
+})
+```
+
+## JSONata Operators
+
+| Operator | Meaning | Example |
+| --- | --- | --- |
+| `=` | Equals | `$status = "active"` |
+| `!=` | Not equals | `$status != "inactive"` |
+| `and` | Both true | `$a = 1 and $b = 2` |
+| `or` | Either true | `$a = 1 or $b = 2` |
+| `>`, `<`, `>=`, `<=` | Comparison | `$age >= 18` |
+
+**Note:** Use single `=` for equality (not `==`).