@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/pattern-javascript-functions.md

@@ -0,0 +1,452 @@
+# Pattern: Extending JSONata with JavaScript Functions
+
+Register a JavaScript file whose exported functions become callable from any JSONata expression in the app. This is **the** way to extend JSONata in a Jigx project — anything JSONata can't express cleanly can drop into JS.
+
+## When to use
+
+Reach for this whenever JSONata becomes awkward or unreadable. Typical categories:
+
+| Category | Example |
+| --- | --- |
+| **HTML/text template building** | PDF generation, email body composition, report rendering |
+| **Non-trivial math** | Pricing tiers, tax/discount rules, amortization, unit conversions |
+| **Date/time beyond `$fromMillis`** | Business-day arithmetic, timezone conversions, date-range diffs |
+| **Data shaping** | Group-by, pivot, multi-level aggregation, CSV/TSV export |
+| **Validation logic** | Complex multi-field checks, regex-heavy rules, checksum/Luhn |
+| **String parsing and formatting** | Phone normalization, address parsing, slugify, abbreviation |
+| **Lookups and decoding** | State code → full name, SKU → category tree, barcode parsing |
+| **JSON manipulation** | Deep merge with rules, remove-nulls, diffing, schema validation |
+
+Keep as pure JSONata:
+
+- Simple field reads, string concatenation, null-coalescing
+- Per-component reactive bindings (JSONata is the native reactive layer)
+- One-off conditionals and ternaries
+- Anything where a single expression stays readable
+
+## API — `ApplicationBuilder.script(name, script)`
+
+Source: `packages/core-sdk/src/application/application.sdk.ts:360`
+
+```typescript
+script(name: string, script: unknown): this
+```
+
+The JSDoc reads "reserved for future use", but it is in active use by the Expert SDK for PDF generation (`packages/expert-sdk/src/expert-form/utils/attach-pdf-action.ts:34`). Treat it as a real but semi-internal feature — no public docs, no validation of the JS body, no TypeScript checking.
+
+On `build()`, scripts are transformed into `{ scripts: { expressions: { <name>: <body> } } }` in the output config.
+
+## Call syntax from JSONata
+
+The **filename without `.js`** becomes a namespace prefix. Exported functions on that module are callable via:
+
+```text
+$<namespace>.<exportedFn>(args)
+```
+
+Example — file `pdf.js` registered as `app.script('pdf.js', ...)`, with `export function create(data) { ... }`:
+
+```text
+=$pdf.create(@ctx.inputs.data)
+```
+
+## Step-by-step
+
+### 1. Write the JS file
+
+Use ES module exports. Place under `src/scripts/` (convention — anywhere works).
+
+```javascript
+// src/scripts/quote-math.js
+
+/**
+ * Calculate total including tax on a quote.
+ * @param {number} subtotal
+ * @param {number} taxRate - e.g. 0.0725 for 7.25%
+ * @returns {number}
+ */
+export function totalWithTax(subtotal, taxRate) {
+  if (!subtotal || subtotal < 0) return 0
+  const tax = Math.round(subtotal * taxRate * 100) / 100
+  return subtotal + tax
+}
+
+export function formatCurrency(amount) {
+  return new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount || 0)
+}
+```
+
+### 2. Read and register in `app.ts`
+
+Use Node's `fs` + `path` to read the file at build time:
+
+```typescript
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+function readScriptFile(scriptName: string): string {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url))
+  const scriptPath = path.resolve(__dirname, 'scripts', scriptName)
+  return fs.readFileSync(scriptPath, 'utf-8')
+}
+
+// In buildApp():
+app.script('quote-math.js', readScriptFile('quote-math.js'))
+```
+
+### 3. Call from any expression
+
+```typescript
+contactSection.addControl.numberField({
+  instanceId: 'total',
+  label: 'Total',
+  value: '=$quote-math.totalWithTax(@ctx.components.subtotal.state.value, 0.0725)',
+})
+
+contactSection.addControl.textField({
+  instanceId: 'totalFormatted',
+  label: 'Total (formatted)',
+  value: '=$quote-math.formatCurrency(@ctx.components.total.state.value)',
+})
+```
+
+Note: if the filename contains a hyphen, the JSONata reference uses the raw filename segment as the namespace. Prefer short, hyphen-free filenames (`quote.js`, `pdf.js`) if you want cleaner call sites (`$quote.totalWithTax(...)`).
+
+## Scenario gallery
+
+Short snippets showing the kind of code that belongs in a script file vs. what you'd struggle to write in pure JSONata.
+
+### 1. Pricing math with tiered discounts
+
+```javascript
+// src/scripts/pricing.js
+
+/**
+ * Apply tiered volume discount then tax.
+ * @param {number} unitPrice
+ * @param {number} quantity
+ * @param {number} taxRate - 0.0725 = 7.25%
+ * @returns {{subtotal: number, discount: number, tax: number, total: number}}
+ */
+export function calculate(unitPrice, quantity, taxRate) {
+  const gross = (unitPrice || 0) * (quantity || 0)
+  let discountRate = 0
+  if (quantity >= 100) discountRate = 0.15
+  else if (quantity >= 50) discountRate = 0.10
+  else if (quantity >= 20) discountRate = 0.05
+
+  const discount = Math.round(gross * discountRate * 100) / 100
+  const subtotal = gross - discount
+  const tax = Math.round(subtotal * (taxRate || 0) * 100) / 100
+  return { subtotal, discount, tax, total: subtotal + tax }
+}
+```
+
+```typescript
+// Usage — call and destructure in separate components
+screen.addExpression(
+  'pricing',
+  '=$pricing.calculate(@ctx.components.unitPrice.state.value, @ctx.components.qty.state.value, 0.0725)',
+)
+
+section.addControl.numberField({ instanceId: 'subtotal', value: '=@ctx.expressions.pricing.subtotal' })
+section.addControl.numberField({ instanceId: 'discount', value: '=@ctx.expressions.pricing.discount' })
+section.addControl.numberField({ instanceId: 'tax', value: '=@ctx.expressions.pricing.tax' })
+section.addControl.numberField({ instanceId: 'total', value: '=@ctx.expressions.pricing.total' })
+```
+
+The JS returns an object; the single expression caches the result; individual fields read members. Cleaner than four nested JSONata ternaries.
+
+### 2. Date formatting beyond `$fromMillis`
+
+```javascript
+// src/scripts/dates.js
+
+const MONTHS = ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
+
+/** Format ISO date as "Mar 5, 2026" */
+export function friendly(iso) {
+  if (!iso) return ''
+  const d = new Date(iso)
+  if (isNaN(d.getTime())) return iso
+  return `${MONTHS[d.getMonth()]} ${d.getDate()}, ${d.getFullYear()}`
+}
+
+/** Days between two ISO dates (positive if b > a) */
+export function daysBetween(a, b) {
+  if (!a || !b) return null
+  const da = new Date(a), db = new Date(b)
+  return Math.round((db - da) / (1000 * 60 * 60 * 24))
+}
+
+/** Add business days (skipping Sat/Sun) */
+export function addBusinessDays(iso, days) {
+  const d = new Date(iso)
+  let added = 0
+  while (added < days) {
+    d.setDate(d.getDate() + 1)
+    if (d.getDay() !== 0 && d.getDay() !== 6) added++
+  }
+  return d.toISOString()
+}
+```
+
+```typescript
+// Usage
+field.value('=$dates.friendly(@ctx.datasources.order.data.orderDate)')
+field.value('="Due in " & $string($dates.daysBetween($now(), @ctx.datasources.order.data.dueDate)) & " days"')
+field.value('=$dates.addBusinessDays(@ctx.datasources.order.data.orderDate, 5)')
+```
+
+### 3. Multi-field validation
+
+```javascript
+// src/scripts/validate.js
+
+/**
+ * Validate a US address and return first problem, or null if OK.
+ * Useful for showing a single error message when multiple fields interact.
+ */
+export function address({ line1, city, state, postalCode }) {
+  if (!line1 || line1.length < 3) return 'Street address is too short'
+  if (!city) return 'City is required'
+  if (!/^[A-Z]{2}$/.test(state || '')) return 'State must be a 2-letter code'
+  if (!/^\d{5}(-\d{4})?$/.test(postalCode || '')) return 'ZIP must be 5 or 9 digits'
+  return null
+}
+
+/** Luhn checksum for credit card numbers */
+export function luhn(num) {
+  const digits = String(num || '').replace(/\D/g, '').split('').map(Number)
+  if (digits.length < 13) return false
+  let sum = 0
+  for (let i = 0; i < digits.length; i++) {
+    let d = digits[digits.length - 1 - i]
+    if (i % 2 === 1) { d *= 2; if (d > 9) d -= 9 }
+    sum += d
+  }
+  return sum % 10 === 0
+}
+```
+
+```typescript
+// Usage — show error text beneath a form section
+section.addControl.textField({
+  instanceId: 'addressError',
+  value: '=$validate.address({"line1": @ctx.components.line1.state.value, "city": @ctx.components.city.state.value, "state": @ctx.components.state.state.value, "postalCode": @ctx.components.zip.state.value})',
+  isHidden: '=$validate.address({...}) = null',
+})
+```
+
+### 4. Data shaping — group by + aggregate
+
+```javascript
+// src/scripts/agg.js
+
+/** Group records by a key and sum a field per group */
+export function sumBy(records, groupKey, sumKey) {
+  const out = {}
+  for (const r of records || []) {
+    const k = r[groupKey] ?? 'unknown'
+    out[k] = (out[k] || 0) + (Number(r[sumKey]) || 0)
+  }
+  return Object.entries(out).map(([key, total]) => ({ key, total }))
+}
+
+/** Pivot: records × rowKey × colKey → matrix */
+export function pivot(records, rowKey, colKey, valueKey) {
+  const rows = {}
+  for (const r of records || []) {
+    const row = r[rowKey], col = r[colKey]
+    if (!rows[row]) rows[row] = { [rowKey]: row }
+    rows[row][col] = (rows[row][col] || 0) + (Number(r[valueKey]) || 0)
+  }
+  return Object.values(rows)
+}
+```
+
+```typescript
+// Feed a list with grouped data — no SQL GROUP BY needed
+list.data('=$agg.sumBy(@ctx.datasources.orders, "category", "amount")')
+```
+
+JSONata's `$sum`/`$reduce` can do single-group aggregation but chokes on multi-key grouping. JS is much clearer here.
+
+### 5. Parsing and normalization
+
+```javascript
+// src/scripts/format.js
+
+/** Normalize US phone to (555) 123-4567 */
+export function phone(s) {
+  const d = String(s || '').replace(/\D/g, '')
+  if (d.length === 10) return `(${d.slice(0,3)}) ${d.slice(3,6)}-${d.slice(6)}`
+  if (d.length === 11 && d[0] === '1') return `+1 (${d.slice(1,4)}) ${d.slice(4,7)}-${d.slice(7)}`
+  return s
+}
+
+/** URL-safe slug from any string */
+export function slug(s) {
+  return String(s || '')
+    .toLowerCase()
+    .normalize('NFKD').replace(/[\u0300-\u036f]/g, '') // strip accents
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/** Compact address as single display line */
+export function address({ line1, line2, city, state, zip }) {
+  return [line1, line2, [city, state].filter(Boolean).join(', '), zip]
+    .filter(Boolean).join(' · ')
+}
+```
+
+### 6. Text export (CSV)
+
+```javascript
+// src/scripts/csv.js
+
+const escape = (v) => {
+  const s = v == null ? '' : String(v)
+  return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s
+}
+
+/** Build CSV from an array of row objects and an ordered column list */
+export function build(rows, columns) {
+  const header = columns.map(escape).join(',')
+  const body = (rows || [])
+    .map((r) => columns.map((c) => escape(r[c])).join(','))
+    .join('\n')
+  return header + '\n' + body
+}
+```
+
+```typescript
+// Use with generateFile action to produce a downloadable CSV
+actions.generateFile({
+  fileName: 'orders.csv',
+  content: '=$csv.build(@ctx.datasources.orders, ["id","customer","total","date"])',
+  encoding: 'utf8',
+})
+```
+
+### 7. Deep merge with null-strip (save/sync hygiene)
+
+```javascript
+// src/scripts/obj.js
+
+/** Merge patch over base, treating null/undefined as "don't touch" */
+export function softMerge(base, patch) {
+  const out = { ...(base || {}) }
+  for (const [k, v] of Object.entries(patch || {})) {
+    if (v !== null && v !== undefined) out[k] = v
+  }
+  return out
+}
+
+/** Remove keys with null/undefined/empty-string values */
+export function compact(obj) {
+  const out = {}
+  for (const [k, v] of Object.entries(obj || {})) {
+    if (v !== null && v !== undefined && v !== '') out[k] = v
+  }
+  return out
+}
+```
+
+```typescript
+// Useful for executeEntity saves where you want to preserve unchanged fields
+.data('=$obj.softMerge(@ctx.datasources.customer.data, {"email": @ctx.components.email.state.value})')
+```
+
+JSONata's built-in `$merge` does a full overwrite — if the patch has `null`, it nulls the field. Sometimes that's not what you want.
+
+## Real-world references
+
+### Expert SDK — PDF generation helper
+
+`packages/expert-sdk/src/expert-form/utils/attach-pdf-action.ts:34`
+
+```typescript
+app.script('pdf.js', readScriptFile('pdf.js'))
+
+actions.generatePdf({
+  instanceId: 'pdf-file',
+  fileName: SUBMISSION_PDF_FILE_NAME,
+  html: `=$pdf.create(@ctx.inputs.data)`,
+})
+```
+
+`pdf.js` exports `create(data)` which returns an HTML string for the PDF generator to render. That's a great canonical use case: a 200-line HTML template would be unreadable as a JSONata string.
+
+### doorpro-door-quote — Sales form HTML helper
+
+`workspace/acumatica-apps/doorpro-door-quote/src/scripts/html.js` — ~1950 lines exporting multiple `*GenerateHTML(...)` functions for different form types. Registered in `src/app.ts` via:
+
+```typescript
+app.script('html.js', readScriptFile('html.js'))
+```
+
+Called from `src/actions/act-generate-quote-pdf.ts` as part of a sequential action list:
+
+```typescript
+workflow.actions.generatePdf({
+  instanceId: 'generate-pdf',
+  fileName: '=... & ".pdf"',
+  html: '=$html.salesFormGenerateHTML(@ctx.datasources.salesInfoAnswers, @ctx.datasources.doorDetails, ...)',
+})
+```
+
+The JS function receives 8 datasources positionally (not wrapped in a single object) — that works fine. Callers with different datasource shapes can still call it as long as they pass the same positional types.
+
+**Signature handling note**: this helper supports both legacy base64 signatures and new local-uri signatures by checking the `file://` / `http://` / `https://` prefix before building an `<img src>`. Lets us migrate storage format without rewriting the helper:
+
+```javascript
+const img = sig.signatureImage
+if (img.startsWith('file://') || img.startsWith('http://') || img.startsWith('https://')) {
+  return img
+}
+return `data:image/png;base64,${img}` // legacy fallback
+```
+
+## Design tips
+
+- **One file per concern.** `pricing.js`, `dates.js`, `validate.js`, `csv.js`. Namespacing by filename keeps call sites self-documenting (`$pricing.calculate(...)` reads better than `$util.calculatePrice(...)`).
+- **Prefer pure functions.** Same inputs → same outputs, no side effects. JSONata reactivity works best when the function is referentially transparent.
+- **Return objects for multi-value results.** Let the caller destructure via JSONata member access: `@ctx.expressions.pricing.tax`. Beats returning a tuple and indexing.
+- **Accept either positional or single-object arguments.** For 1–3 arguments, positional is natural. For more, accept a single object so callers don't have to remember order.
+- **Defensive null handling.** JSONata can pass `null` for missing fields. Use `v ?? default` or `v || default` guards at the top of functions.
+- **Avoid `console.log`**. There's no reliable place to read it at runtime. If you need debugging, return diagnostic info in the result object.
+- **No imports.** The JS file stands alone — no `require`, no `import` from other files. Everything you need must be in-lined or written inside the same file.
+- **Keep state-free.** Don't rely on module-level variables holding state between calls. Treat each call as independent.
+
+## Testing a script in isolation
+
+Because it's just a `.js` file with ES module exports, you can run it through Node directly for quick unit tests:
+
+```bash
+node --input-type=module -e "
+  import('./src/scripts/pricing.js').then(m => {
+    console.log(m.calculate(100, 25, 0.0725))
+  })
+"
+```
+
+Or write a proper test file and run it with `node --test`. The JS file isn't tied to Jigx at runtime, so anything that runs outside Jigx will behave the same inside.
+
+## Caveats
+
+1. **No TypeScript.** The body is a `.js` file. You can use JSDoc for light type hints but there's no compile-time check.
+2. **Semi-internal.** The `script()` method's JSDoc says "reserved for future use". Stable enough that the expert-sdk ships with it, but don't be surprised if the transformation shape (`scripts.expressions`) changes.
+3. **File-based only.** No inline closure form — must be a separate `.js` file read as a string.
+4. **Runtime-only.** Evaluated on device at expression time. No SDK validation of the JS body or its arguments.
+5. **Namespacing by filename.** Registering two scripts with the same filename overwrites.
+6. **No access to `@ctx`.** The function receives only the arguments passed in the JSONata call. Thread context values in explicitly: `$pdf.create({data: @ctx.inputs.data, user: @ctx.user.displayName})`.
+7. **No browser/Node APIs.** No `fetch`, no `fs`, no `document`. The runtime is a JavaScript sandbox — pure computation only. For I/O, use Jigx actions (`executeEntity`, REST functions, `generatePdf`, etc.).
+8. **No ES module imports between script files.** Each registered script is standalone. If two scripts share helpers, copy the helpers into both.
+9. **Argument types are whatever JSONata evaluates.** Arrays from datasources come through as JS arrays, objects as plain objects, numbers as numbers, `null` as `null`. Dates arrive as ISO strings — `new Date(iso)` to convert.
+
+## Generic vs Acumatica-specific
+
+This pattern is **generic Jigx** — nothing Acumatica about it. Applies to any Core SDK app.