@jigx/core-sdk 1.0.0 → 1.2.0-rc

package/docs/pattern-pdf-generation.md

@@ -0,0 +1,391 @@
+# Pattern: PDF Generation and Preview
+
+Generate a PDF from form data, persist the file URI on the source record, preview in a native document viewer, share via the OS share sheet.
+
+## The trio
+
+1. **`app.script('html.js', ...)`** — JS helper that builds the HTML string (see [pattern-javascript-functions.md](pattern-javascript-functions.md))
+2. **`action.generate-pdf`** — renders the HTML to a PDF file, outputs a local URI
+3. **`jig.document` screen** — native PDF viewer that binds to the file URI
+
+This pattern is **generic Jigx** — nothing Acumatica-specific.
+
+## Global action — generate, save, push to state
+
+```typescript
+export function actGenerateQuotePdf(app: ApplicationBuilder): void {
+  const action = app.addAction({ actionId: 'act-generate-quote-pdf' })
+  action.addParameter('opportunityID', { type: 'string', required: true })
+  action.addParameter('quoteName', { type: 'string', required: false })
+
+  const workflow = action.action.list({ concurrency: 'sequential' })
+
+  // 1. Generate the PDF
+  workflow.actions.generatePdf({
+    instanceId: 'generate-pdf',
+    fileName: '=@ctx.action.parameters.quoteName & "-" & @ctx.action.parameters.opportunityID & ".pdf"',
+    html: '=$html.salesFormGenerateHTML(@ctx.datasources.salesInfoAnswers, ...)',
+  })
+
+  // 2. Persist URI on the quote record (merge over existing fields).
+  //
+  // Two critical details:
+  //   a. `when` guard — only save if the row actually exists. Otherwise a missing
+  //      datasource or empty filter would cause $merge to produce an object with
+  //      only {pdfFilePath, pdfGeneratedAt} and no id, triggering a *duplicate row*
+  //      on every PDF generation.
+  //   b. Explicitly override `id` with the row's top-level `.id` column (not
+  //      `.data.id`). Jigx may strip `id` from the JSON blob on save and keep it
+  //      only as the row's primary key column. Reading `.data.id` can return
+  //      undefined, leaving the merged object with no id → new UUID → duplicate row.
+  workflow.actions
+    .executeEntity({
+      instanceId: 'save-pdf-path',
+      when: '=$exists(@ctx.datasources.salesInfoAnswers.id)',
+    })
+    .dynamicData('default/salesInfoAnswers', 'save')
+    .data(
+      '=$merge([@ctx.datasources.salesInfoAnswers.data, {"id": @ctx.datasources.salesInfoAnswers.id, "pdfFilePath": @ctx.actions.generate-pdf.outputs.uri, "pdfGeneratedAt": $now()}])',
+    )
+
+  // 3. Push URI to screen state for immediate viewer refresh
+  workflow.actions.setScreenState({
+    instanceId: 'set-pdf-path',
+    keys: { pdfFilePath: '=@ctx.actions.generate-pdf.outputs.uri' },
+  })
+}
+```
+
+### Why the three steps matter
+
+- **Step 1** produces the URI but nothing else is aware of it yet.
+- **Step 2** writes it to the database. This triggers a datasource cache invalidation, so lists showing quotes will eventually refresh. But the current screen's datasources may not have re-queried yet by the time step 3 runs.
+- **Step 3** puts the URI directly into screen state, which the viewer binds to first (before falling back to the datasource value). The viewer updates on the next render tick, no race.
+
+### `$merge` over field-by-field enumeration
+
+For upsert-style saves where most fields should be preserved and only a few updated, `$merge([existing, patch])` is much cleaner than listing every field:
+
+```typescript
+// Verbose (don't do this)
+.data({
+  id: '=@ctx.datasources.X.data.id',
+  field1: '=@ctx.datasources.X.data.field1',
+  field2: '=@ctx.datasources.X.data.field2',
+  // ... 20 more fields
+  pdfFilePath: '=@ctx.actions.generate-pdf.outputs.uri',
+})
+
+// Clean
+.data('=$merge([@ctx.datasources.X.data, {"id": @ctx.datasources.X.id, "pdfFilePath": @ctx.actions.generate-pdf.outputs.uri}])')
+```
+
+**Always include `.id` explicitly in the merge patch.** Jigx's `save` method may strip
+`id` from the JSON blob on write, keeping it only as the row primary key column.
+Reading back via `.data.id` can return undefined, which breaks the upsert key and
+creates a duplicate row. Override explicitly with the row's top-level `.id`.
+
+## Passing datasource arrays to JavaScript functions
+
+Single-row array datasources (non-`isDocument`) have a trap. JSONata's "singleton
+sequence" behavior unwraps a 1-element sequence to a scalar when passed to a function:
+
+```text
+@ctx.datasources.doors          = [{id, data: {...}}]              // 1-row array
+@ctx.datasources.doors.data     = {...}   ← scalar, not [{...}]!
+```
+
+The JS function expecting an array will see a single object and `Array.isArray()`
+returns false. Fix by forcing array shape with `[...]` wrapping:
+
+```text
+[@ctx.datasources.doors.data]   = [{...}]   // always an array
+```
+
+For datasources where you need the row's top-level `id` preserved inside each item
+(e.g., to match foreign keys like `answer.itemID === item.id`), use `$map` with
+`$merge` to lift the id into the data object:
+
+```text
+$map(@ctx.datasources.salesChecklist, function($r) { $merge([{"id": $r.id}, $r.data]) })
+```
+
+Each resulting item is `{id, title, description, ...}` — id promoted from the row
+column into the data shape the JS helper expects.
+
+`isDocument: true` datasources don't have this trap — they always return a single
+object, so `@ctx.datasources.X.data` is reliably the data object.
+
+## Redesigning an existing PDF safely
+
+When replacing a production PDF layout, do not overwrite the existing HTML helper
+until the new layout has been reviewed in the app. Add a second script file and
+register it with its own namespace:
+
+```typescript
+app.script('quotehtml.js', readScriptFile('quotehtml.js')) // existing fallback
+app.script('quotepresentation.js', readScriptFile('quotepresentation.js')) // new layout
+```
+
+Then change only the `action.generate-pdf.html` expression to call the new
+namespace, keeping the argument order and datasource wrapping identical:
+
+```text
+=$quotepresentation.salesPresentationGenerateHTML(
+  @ctx.datasources.salesInfoAnswers.data,
+  [@ctx.datasources.doorDetails.data],
+  @ctx.datasources.salesSelectionAnswers.data,
+  $map(@ctx.datasources.salesChecklist, function($r) { $merge([{"id": $r.id}, $r.data]) }),
+  [@ctx.datasources.salesChecklistAnswers.data],
+  [@ctx.datasources.openerDetails.data],
+  @ctx.datasources.salesOpenersAnswers.data,
+  [@ctx.datasources.salesFormSignatures.data]
+)
+```
+
+This keeps rollback cheap and avoids reintroducing array/singleton shape bugs
+while changing only the presentation layer.
+
+### Use line records as the pricing source of truth
+
+For quote PDFs with doors, openers, products, services, or other repeatable line
+items, keep `price`, `tax`, and `totalWithTax` on each line record. The quote
+screen and PDF should aggregate those child records for running totals instead of
+duplicating an editable quote-level total on the disclosure or signature screen.
+
+This prevents stale totals when a line is copied, deleted, repriced, or edited
+after quote acceptance is captured. The final PDF page can still show a quote
+summary, but it should be derived from the saved line rows:
+
+```text
+door total = SUM(COALESCE(totalWithTax, price + tax, 0))
+opener total = SUM(COALESCE(totalWithTax, price + tax, 0))
+quote total = door total + opener total
+```
+
+If a line-level code is internal only, do not render it in customer-facing PDF
+HTML. Save it locally and pass it to integration/sync actions as needed.
+
+### Paginate repeatable quote lines deliberately
+
+For presentation-style PDFs, do not assume all repeatable line items fit on one
+slide/page. Chunk child records into a conservative fixed count and render more
+slides as needed:
+
+- Door configuration cards: 2 per slide.
+- Opener configuration cards: 2 per slide.
+- Included services / scope: separate slide from repeatable products.
+
+This keeps the layout stable when a quote has 3, 5, or more line items and avoids
+one overflowing mixed slide that combines repeatable products with scope text.
+
+## Signature images in generated PDFs
+
+Do not rely on persisted local signature paths for PDF HTML unless the PDF is being
+generated on the same device that captured the signature. Paths like
+`file:///data/...` or `/var/mobile/...` are sandbox-local and can point to nothing
+after the quote syncs to a different device. Missing images can also make the native
+PDF renderer wait until timeout.
+
+For signatures that must appear in generated PDFs:
+
+- Keep `signatureImage` as the local URI for `signatureField.initialValue`.
+- Save a separate `signatureImagePortable` field with `conversions:
+  [{ property: 'signatureImagePortable', from: 'local-uri', to: 'data-uri' }]`.
+- Re-run the save/conversion when `signatureImagePortable` is missing, even if
+  `signatureImage` did not change. Older rows or rows captured on another device
+  can have only the non-portable local URI.
+- In the PDF HTML helper, use `signatureImagePortable` first, then only fall back to
+  current-device local paths if needed.
+- If no portable image is available, render a text fallback such as "Signature on
+  file" instead of emitting a stale local `<img>` path or leaving an unexplained
+  blank area.
+
+## Product and logo images in generated PDFs
+
+Do not embed large static product images as base64/data-URI constants in a solution.
+It inflates the solution payload, slows script parsing, makes YAML diffs unreadable,
+and can force heavy memory usage during PDF generation. Prefer normal hosted image
+URLs for static manufacturer/product examples when the app is online and the image
+host is reliable.
+
+Use portable `data:` images only for small or user-generated values that cannot be
+fetched by URL, such as `signatureImagePortable`. If a remote product image fails
+to load, the PDF should still be recoverable by regenerating after connectivity is
+restored. Do not use stale device-local `file://` paths for images captured on a
+different device.
+
+## Saving generated HTML for renderer debugging
+
+When native PDF output does not match the browser-rendered HTML, save the exact
+HTML string to a dedicated dynamic debug table immediately before
+`action.generate-pdf`. This separates template bugs from native renderer bugs.
+
+Use a first-class table name like `default/htmldebug`, not a generic scratch table,
+so it is easy to inspect in the device database or management tools:
+
+```typescript
+app.addDatabase.default.table('htmldebug')
+
+const htmlExpr = '$quote.salesPresentationGenerateHTML(...)'
+
+workflow.actions
+  .executeEntity({ instanceId: 'debug-html' })
+  .dynamicData('default/htmldebug', 'save')
+  .data(
+    `={"id": @ctx.action.parameters.opportunityID, "opportunityID": @ctx.action.parameters.opportunityID, "html": ${htmlExpr}, "generatedAt": $now(), "templateVersion": "presentation-v1"}`,
+  )
+
+workflow.actions.generatePdf({
+  instanceId: 'generate-pdf',
+  fileName: '=@ctx.action.parameters.opportunityID & "-" & $millis() & ".pdf"',
+  html: `=${htmlExpr}`,
+})
+```
+
+Keep the debug row keyed by the parent record id (`opportunityID`, service order
+id, etc.) so regeneration replaces the previous debug HTML for that record.
+
+## Document screen — native PDF viewer
+
+```typescript
+const screen = app.addScreen.document({
+  screenId: 'jig-quote-pdf-preview',
+  title: 'Quote PDF',
+})
+
+screen.addInput({ name: 'opportunityID', type: 'string' })
+screen.with({ state: { pdfFilePath: { initialValue: null } } })
+
+const hasPdfStateExpr =
+  '@ctx.jig.state.pdfFilePath != null and @ctx.jig.state.pdfFilePath != ""'
+
+// All datasources the PDF generator needs — scoped to this quote
+screen.addDatasource.sqlite({ datasourceId: 'salesInfoAnswers', provider: 'dynamic' })
+  .entity('default/salesInfoAnswers')
+  .query(`SELECT id, data FROM [default/salesInfoAnswers] WHERE json_extract(data, '$.opportunityID') = @opportunityID`)
+  .queryParameter('opportunityID', '=@ctx.jig.inputs.opportunityID')
+  .jsonProperties('data')
+  .isDocument(true)
+// ... more datasources
+
+// Generate on first visit in this screen/device session if no local state URI exists yet.
+// Persisted file:// URIs are device-local and must not be trusted across phones,
+// app reinstalls, or sandbox changes.
+screen.onFocus.executeAction({
+  action: 'act-generate-quote-pdf',
+  when: `=(${hasPdfStateExpr}) = false`,
+  parameters: {
+    opportunityID: '=@ctx.jig.inputs.opportunityID',
+  },
+})
+
+// Bind the PDF source only to the current screen/device URI. Do not fall back to
+// persisted pdfFilePath here; it may point to another device's sandbox.
+screen.source.pdf({
+  uri: '=@ctx.jig.state.pdfFilePath',
+})
+
+// Header actions — regenerate and share
+const header = screen.header()
+
+header.actions.executeAction({
+  title: 'Regenerate',
+  icon: 'synchronize-arrows-1',
+  action: 'act-generate-quote-pdf',
+  parameters: { opportunityID: '=@ctx.jig.inputs.opportunityID' },
+})
+
+header.actions.share({
+  title: 'Share',
+  icon: 'share',
+  fileUri: '=@ctx.jig.state.pdfFilePath',
+  when: '=$exists(@ctx.jig.state.pdfFilePath)',
+})
+```
+
+### Placeholder PDFs for incomplete flows
+
+`jig.document` has one source type for the screen. If the screen is a PDF viewer,
+do not navigate away just because the real PDF cannot be generated yet. Generate a
+small temporary placeholder PDF on focus, set its URI into screen state, and keep
+the real persisted `pdfFilePath` untouched.
+
+Use this when a tab should remain open but the quote/report is not ready:
+
+```typescript
+focusActions.infoModal({
+  instanceId: 'incomplete-alert',
+  when: '=@ctx.expressions.allSectionsComplete = false',
+  modal: { title: 'Quote Not Complete', buttonText: 'OK' },
+})
+
+focusActions.generatePdf({
+  instanceId: 'generate-placeholder-pdf',
+  when: '=@ctx.expressions.allSectionsComplete = false',
+  fileName: '="Quote-Not-Generated-" & @ctx.jig.inputs.opportunityID & ".pdf"',
+  html: '<html><body><h1>Not generated yet</h1></body></html>',
+})
+
+focusActions.setScreenState({
+  instanceId: 'set-placeholder-pdf',
+  when: '=@ctx.expressions.allSectionsComplete = false',
+  keys: { pdfFilePath: '=@ctx.actions.generate-placeholder-pdf.outputs.uri' },
+})
+```
+
+Hide `Share` and `Clear` while showing a placeholder. Those actions should apply
+only to a real generated PDF, not the temporary screen-state PDF.
+
+### Key behaviors to remember
+
+- **`DocumentScreenBuilder extends ScreenBaseBuilderNew`** — so it has `addInput`, `addDatasource`, `with({state})`, `onFocus`, `header`, etc. Same building blocks as a default screen.
+- **`source.pdf({uri})` accepts an expression** — reactive binding. When the expression changes (state, datasource), the viewer updates.
+- **`onFocus` fires on navigation *to* the screen, not on `goBack`**. Safe to use for "generate if missing" without re-triggering every time the user leaves and comes back via back navigation.
+- **`share` action requires a local `file://` URI** — base64 and data URIs don't work.
+- **Generated PDF `file://` URIs are device-local.** A URI persisted on a dynamic-data row can point to another device's app sandbox, or to a previous install's sandbox. The preview screen should generate a fresh local PDF into screen state when `@ctx.jig.state.pdfFilePath` is missing, bind `source.pdf` to state only, and share state only. Persist `pdfFilePath` for audit/status/sync metadata, not as a guaranteed reusable viewer source.
+- **Do not use `$exists` alone on initialized state.** If `pdfFilePath` is declared with `initialValue: null`, `$exists(@ctx.jig.state.pdfFilePath)` can be true even though there is no usable URI. Use an explicit non-null/non-empty check like `@ctx.jig.state.pdfFilePath != null and @ctx.jig.state.pdfFilePath != ""` for on-focus generation and share enablement.
+- **Images inside generated HTML must not use stale device-local paths.** Device-local image/signature paths from another device can leave the PDF renderer waiting for images until `RENDER_TIMEOUT`. For signatures, store a portable `data:` representation or omit the image and show the signature/name/date fields instead.
+- **External HTTP images can still fail if connectivity or the image host is bad.** Keep product imagery hosted at stable URLs and avoid very large images, but do not base64-embed large static brand/product photos into the solution.
+- **Guard post-generation saves.** If `action.generate-pdf` fails, later sequential actions may still run. Save `pdfFilePath` and update screen state only when `$exists(@ctx.actions.generate-pdf.outputs.uri)` is true.
+- **Give regenerate actions explicit feedback.** A `generate-pdf` failure can leave
+  `outputs.uri` empty while later guarded steps are skipped. For user-triggered
+  regeneration, add success and failure `infoModal` actions gated by
+  `$exists(@ctx.actions.<instanceId>.outputs.uri)` so the user knows whether a new
+  file was created.
+- **Do not rely on print-only CSS for production appearance.** The current iOS
+  `action.generate-pdf` path renders HTML through the native Jigx PDF generator
+  using a WebView PDF export, not a full browser print flow. `@page`,
+  `page-break-after`, and `@media print` are useful hints, but normal screen CSS
+  must already look acceptable because iOS can export the scrollable WebView as a
+  single tall page. Avoid dark-only presentation slides, oversized decorative
+  absolute shapes, and backgrounds that only get corrected inside `@media print`.
+- **Prefer flat, explicit PDF styling.** Native and desktop PDF viewers can render
+  transparency, gradients, and CSS shadows differently. For customer-facing PDFs,
+  prefer `background: #ffffff`, solid borders, and simple accent colors over
+  `rgba()`, `linear-gradient()`, and `box-shadow`. This keeps Android preview,
+  shared PDFs, macOS Preview, and browser print output closer to each other.
+
+## Global action caller context
+
+A key thing to understand: when `executeAction` calls a global action, expressions inside the global action's steps resolve in the **caller's screen context**. That means `@ctx.datasources.X` refers to the caller's screen-level datasources, not anything defined on the action itself (global actions don't have datasources).
+
+So the PDF generation action above works because the PDF preview screen defines all the required datasources in its own scope. If you called the same action from a screen without those datasources loaded, the expressions would resolve to null.
+
+## `file://` URIs flow end-to-end
+
+For this pattern we deliberately store signature and media images as **local URIs** (not base64), then let the generator embed them directly as `<img src="file://...">`. The Jigx `generate-pdf` action renders these correctly. This avoids the cost of base64 encoding on every save and keeps the rows small. See "Signature and media storage" in [pattern-datasources.md](pattern-datasources.md) for the trade-off.
+
+## Filename — namespace by script file name
+
+Calling `app.script('html.js', ...)` registers the functions under the `$html` JSONata namespace (filename minus `.js`). Call as `$html.salesFormGenerateHTML(...)`. If you name the file `pdf.js`, call as `$pdf.create(...)`.
+
+## Real-world reference
+
+`workspace/acumatica-apps/doorpro-door-quote/` — the full trio:
+
+- `src/scripts/html.js` — HTML helper
+- `src/actions/act-generate-quote-pdf.ts` — global action
+- `src/screens/jig-quote-pdf-preview.ts` — document screen
+- `src/app.ts` — `readScriptFile` + `app.script('html.js', ...)`
+- `src/screens/jig-quote-list.ts:93` — swipe-left that navigates to the PDF screen