@jigx/core-sdk 1.1.0 → 1.2.0-rc

package/docs/field-state.md

@@ -0,0 +1,131 @@
+## Basic Usage
+
+```typescript
+form.addStep({ instanceId: 'details', icon: 'pencil-edit-info' }, (step) => {
+ const emailField = step.addEmail({ name: 'email', label: 'Email' })
+ // Phone required only if email is empty
+ step.addText({
+  name: 'phone',
+  label: 'Phone',
+  isRequired: new JsonataBuilder('$email = null or $email = ""', {
+   email: emailField.state.value,
+  }),
+ })
+})
+```
+
+## How It Works
+
+`field.state.value` is a template variable replaced with actual state reference at runtime:
+
+```typescript
+step.addDropdown({
+ name: 'status',
+ label: 'Status',
+ data: [
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' },
+ ],
+})
+// When user selects "active":
+// status.state.value → "active" (immediately)
+```
+
+## Characteristics
+
+| Property | Behavior |
+| --- | --- |
+| Updates | Immediate on user input |
+| Scope | Current step only |
+| Persistence | Not persisted until step saved |
+| Use case | Local validation, conditional fields |
+
+## Important Limitations
+
+**Self-reference in `value` creates a cycle (not allowed):**
+
+A field's `value` cannot reference its own `.state.value`
+
+
+**ArrayField does not expose `.state`:**
+
+```typescript
+const step1 = form.addStep({ instanceId: 'collect-items' }, (step) => {
+ // Wrong - arrayField has no .state
+ const items = step.addArrayField({ name: 'items', label: 'Items', title: 'Item' })
+ items.addText({ name: 'name', label: 'Name' })
+ // items.state.value  // Error - doesn't exist
+})
+step1.with({ icon: 'list', title: 'Items' })
+// Correct - use step.data.getArrayFieldData()
+form.addStep({ instanceId: 'select-item', icon: 'cursor-select-1' }, (otherStep) => {
+ otherStep.addDropdown({
+  name: 'selected',
+  label: 'Select Item',
+  data: step1.data.getArrayFieldData('items'),
+ })
+})
+```
+
+**Cross-step access not available:**
+
+```typescript
+const step1 = form.addStep({ instanceId: 'type' }, (step) => {
+ step.addDropdown({
+  name: 'status',
+  label: 'Status',
+  data: [
+   { label: 'Active', value: 'active' },
+   { label: 'Inactive', value: 'inactive' },
+  ],
+ })
+})
+step1.with({ icon: 'settings', title: 'Type' })
+// Wrong - field.state.value only works within same step
+// step1Field.state.value  // Won't work cross-step
+// Correct - use step.data.getFieldData() for cross-step
+form.addStep({ instanceId: 'details', icon: 'pencil-edit-info' }, (step2) => {
+ step2.addText({
+  name: 'field',
+  label: 'Field',
+  isVisible: new JsonataBuilder('$status = "active"', {
+   status: step1.data.getFieldData('status'),
+  }),
+ })
+})
+```
+
+## Dropdown state.selected
+
+Dropdowns expose an additional `state.selected` property for accessing the full selected object in the same step:
+
+```typescript
+const productField = step.addDropdown({
+ name: 'product',
+ label: 'Product',
+ data: [
+  { label: 'Widget A', value: 'widget-a', icon: 'cube-shape' },
+  { label: 'Widget B', value: 'widget-b', icon: 'cube-shape' },
+ ],
+})
+// state.value → "widget-a" (just the value)
+// state.selected → { label: "Widget A", value: "widget-a", icon: "cube" }
+// Access full object to show selected label in read-only field
+step.addText({
+ name: 'selectedLabel',
+ label: 'Selected Product Name',
+ value: new JsonataBuilder('$product.label', {
+  product: productField.state.selected,
+ }),
+ isDisabled: true,
+})
+```
+
+| Property | Returns | Use Case |
+| --- | --- | --- |
+| `state.value` | `string \| number` | Selected value for conditions |
+| `state.selected` | Full object | Access label, icon, or nested properties |
+
+**Ref:** `./dropdown-fields.md` for more on dropdown state
+
+**Ref:** `./cross-step-data.md` for cross-step data access

package/docs/field-types-overview.md

@@ -0,0 +1,132 @@
+## Adding Fields
+
+Fields are added to steps or sections:
+
+```typescript
+// Add to step
+step.addText({ name: 'username', label: 'Username' })
+// Add to section
+const section = step.addSection({ title: 'Contact Info' })
+section.addEmail({ name: 'email', label: 'Email' })
+```
+
+**Important:** Call field methods on step or section only - NOT on field references.
+
+## Common Properties
+
+All fields support these via constructor or `.with()`:
+
+```typescript
+const otherField = step.addCheckbox({ name: 'showNotes', label: 'Show Notes' })
+// Pass all properties in constructor
+step.addText({
+ name: 'notes',
+ label: 'Notes',
+ icon: 'common-file-text',
+ helperText: 'Enter additional details',
+ isRequired: false, // Make optional
+ isDisabled: true, // Read-only
+ isVisible: new JsonataBuilder('$showNotes = true', { showNotes: otherField.state.value }),
+})
+```
+
+Or use `.with()` to update after construction:
+
+```typescript
+const field = step.addText({ name: 'notes', label: 'Notes' })
+field.with({
+ icon: 'common-file-text',
+ helperText: 'Enter additional details',
+ isRequired: false,
+})
+```
+
+## Required vs Optional
+
+- **Most fields required by default** - no need to set `isRequired: true`
+- **Checkbox is optional by default** - set `isRequired: true` if needed
+- To make any field optional: `isRequired: false`
+
+## Text Fields
+
+```typescript
+// Single-line
+step.addText({ name: 'title', label: 'Title' })
+// Multi-line textarea
+step.addText({
+ name: 'notes',
+ label: 'Notes',
+ isMultiline: true,
+})
+```
+
+## Validated Input Fields
+
+```typescript
+// Email - built-in format validation
+step.addEmail({ name: 'email', label: 'Email' })
+// Phone - phone-pad keyboard
+step.addPhone({ name: 'phone', label: 'Phone' })
+// Number - numeric input
+step.addNumber({ name: 'quantity', label: 'Quantity' })
+```
+
+## Date/Time Fields
+
+```typescript
+step.addDate({
+ mode: 'datetime',
+ name: 'eventDateTime',
+ label: 'Event Date & Time',
+})
+```
+
+## Checkbox Fields
+
+```typescript
+step.addCheckbox({
+ name: 'consent',
+ label: 'I agree to terms',
+ isRequired: true, // Checkbox optional by default, set true to require
+})
+```
+
+**Choice vs Checkbox for yes/no:**
+
+- Required yes/no question: Use choice field (checkbox fails validation when unchecked)
+- Optional toggle: Use checkbox
+
+## Rating Fields
+
+```typescript
+step.addRating({ name: 'satisfaction', label: 'Satisfaction Rating' })
+```
+
+**Rating vs Number:**
+
+- Rating: Subjective feedback on fixed scale (1-5 stars, quality)
+- Number: Objective/precise values (counts, measurements)
+
+## Slider Fields
+
+```typescript
+step.addSlider({ name: 'price', label: 'Price', minimum: 0, maximum: 1000, step: 50 })
+```
+
+**Slider vs Number:**
+
+- Slider: Bounded range with known min/max, coarse precision
+- Number: High precision, large ranges, exact values
+
+## Helper Text Guidelines
+
+- Use only when providing NEW information (formatting hints, constraints, examples)
+- Never repeat the label
+- Omit entirely if label is self-explanatory
+
+```typescript
+// Good - adds information
+step.addEmail({ name: 'email', label: 'Email', helperText: 'We will never share your email' })
+// Bad - repeats label
+step.addEmail({ name: 'email2', label: 'Email', helperText: 'Enter your email address' }) // Don't do this
+```

package/docs/formatting.md

@@ -0,0 +1,421 @@
+Field `format` and `FormatBuilder` use [ECMA-402](https://tc39.es/ecma402/) `Intl.NumberFormat` for numbers (currency, percent, units) and [Moment.js](https://momentjs.com/docs/#/displaying/) `dateFormat` presets/patterns for dates (`LL`, `fromNow`, etc.). Both are locale-aware — numbers adapt decimal separators, thousands grouping, and currency symbols; dates adapt month names, orderings, and relative-time wording automatically.
+
+**Important:** Field `format` only applies when field is disabled. When editable, raw value displays.
+
+
+### Where FormatBuilder applies
+
+Use `FormatBuilder` to format values in these specific properties:
+
+- `submissionItemTitle` — form-level submission title
+- `submissionItemSubtitle` — form-level submission subtitle
+- ArrayField `title` — item title in the array list
+- ArrayField `subtitle` — item subtitle in the array list
+- ArrayField `description` — item description in the array list
+- Step `title` — step header text
+
+Wrap `FormatBuilder` around a `JsonataBuilder` expression, then pass to `I18nBuilder` if combining with text.
+
+## ECMA-402 Standard
+
+Format options follow two systems:
+
+- **Number formatting**: [ECMA-402](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) `Intl.NumberFormat` — currency, percent, units, scientific notation. Locale-aware, adapts to user's device locale automatically.
+- **Date formatting**: [Moment.js](https://momentjs.com/docs/#/displaying/) `dateFormat` presets (`LL`, `fromNow`, etc.). See [Date Format Codes](#date-format-codes) below.
+
+No manual locale configuration needed - the SDK handles it.
+
+## Field Format Property
+
+### When Format Applies
+
+- **Disabled/read-only fields**: Format is applied, formatted value displays
+- **Editable fields**: Raw value from `value` property displays, format ignored
+
+```typescript
+// Format applied - field is disabled
+step.addNumber({
+  name: 'total',
+  label: 'Total',
+  value: 1234.56,
+  isDisabled: true,
+  format: { numberStyle: 'currency', currency: 'USD' },
+})
+// Displays: $1,234.56
+
+// Format NOT applied - field is editable
+step.addNumber({
+  name: 'amount',
+  label: 'Amount',
+  value: 1234.56,
+  format: { numberStyle: 'currency', currency: 'USD' },
+})
+// Displays: 1234.56 (raw value)
+```
+
+## Currency Formatting
+
+```typescript
+step.addNumber({
+ name: 'price',
+ label: 'Price',
+ format: { currency: 'USD', numberStyle: 'currency' },
+})
+```
+
+### Currency Options
+
+```typescript
+step.addNumber({
+ name: 'price',
+ label: 'Price',
+ format: {
+  numberStyle: 'currency',
+  currency: 'EUR',
+  currencyDisplay: 'symbol', // €, $, £ (options: 'symbol', 'code', 'name', 'narrowSymbol')
+  currencySign: 'accounting', // (100) for negative (options: 'standard', 'accounting')
+ },
+})
+```
+
+## Percentage Formatting
+
+```typescript
+// Format as percentage
+step.addNumber({
+ name: 'completion-rate',
+ label: 'Completion Rate',
+ format: { numberStyle: 'percent' },
+})
+```
+
+## Decimal Formatting
+
+```typescript
+// Fixed decimal places (123.45, 0.50)
+step.addNumber({
+ name: 'average-score',
+ label: 'Average Score',
+ format: { numberStyle: 'decimal', minimumFractionDigits: 2, maximumFractionDigits: 2 },
+})
+// Significant digits (123.4, 0.5, 0.001234)
+step.addNumber({
+ name: 'precision-value',
+ label: 'Precision Value',
+ format: { minimumSignificantDigits: 3, maximumSignificantDigits: 4 },
+})
+// Combining both: min/max fraction digits
+step.addNumber({
+ name: 'detailed-score',
+ label: 'Detailed Score',
+ format: { minimumFractionDigits: 1, maximumFractionDigits: 3 },
+})
+```
+
+### Decimal Options
+
+```typescript
+format: {
+  minimumFractionDigits: 2,       // Min decimal places
+  maximumFractionDigits: 4,       // Max decimal places
+  minimumSignificantDigits: 3,    // Min significant digits
+  maximumSignificantDigits: 5     // Max significant digits
+}
+```
+
+## Unit Formatting
+
+```typescript
+// Distance in kilometers with 2 decimal precision
+step.addNumber({
+ name: 'distance-km',
+ label: 'Distance (km)',
+ format: {
+  numberStyle: 'unit',
+  unit: 'kilometer',
+  unitDisplay: 'long',
+  minimumFractionDigits: 2,
+  maximumFractionDigits: 2,
+ },
+})
+// Height in meters with 1 decimal place
+step.addNumber({
+ name: 'height-m',
+ label: 'Height (m)',
+ format: {
+  numberStyle: 'unit',
+  unit: 'meter',
+  unitDisplay: 'short',
+  minimumFractionDigits: 1,
+  maximumFractionDigits: 1,
+ },
+})
+// Width in millimeters (no decimals for precision)
+step.addNumber({
+ name: 'width-mm',
+ label: 'Width (mm)',
+ format: {
+  numberStyle: 'unit',
+  unit: 'millimeter',
+  unitDisplay: 'narrow',
+  minimumFractionDigits: 0,
+  maximumFractionDigits: 0,
+ },
+})
+// Weight in kilograms with sign display
+step.addNumber({
+ name: 'weight-kg',
+ label: 'Weight Change (kg)',
+ format: {
+  numberStyle: 'unit',
+  unit: 'kilogram',
+  unitDisplay: 'short',
+  signDisplay: 'always',
+  minimumFractionDigits: 1,
+ },
+})
+// Temperature in celsius with minimum integer digits
+step.addNumber({
+ name: 'temperature',
+ label: 'Temperature',
+ format: {
+  numberStyle: 'unit',
+  unit: 'celsius',
+  minimumIntegerDigits: 2,
+ },
+})
+```
+
+### Unit Display Options
+
+| Display | Example |
+| --- | --- |
+| `'short'` | 150 lb |
+| `'long'` | 150 pounds |
+| `'narrow'` | 150# |
+
+### Common Units
+
+- Length: `meter`, `kilometer`, `mile`, `foot`, `inch`
+- Weight: `kilogram`, `pound`, `ounce`
+- Temperature: `celsius`, `fahrenheit`
+- Volume: `liter`, `gallon`
+- Time: `hour`, `minute`, `second`
+
+## Scientific Notation
+
+```typescript
+// Set multiple format properties
+step.addNumber({
+ name: 'result',
+ label: 'Result',
+ format: {
+  notation: 'scientific',
+  minimumSignificantDigits: 3,
+  maximumSignificantDigits: 5,
+ },
+})
+```
+
+## Dynamic Formatting
+
+Format properties support `JsonataBuilder` for dynamic values:
+
+```typescript
+// Let user select currency
+const currencyField = step.addDropdown({
+ name: 'currency',
+ label: 'Currency',
+ data: [
+  { label: 'USD', value: 'USD' },
+  { label: 'EUR', value: 'EUR' },
+  { label: 'GBP', value: 'GBP' },
+ ],
+})
+// Set currency dynamically based on selection
+step.addNumber({
+ name: 'amount',
+ label: 'Amount',
+ format: {
+  currency: new JsonataBuilder('$selectedCurrency', {
+   selectedCurrency: currencyField.state.value,
+  }),
+  numberStyle: 'currency',
+ },
+})
+```
+
+## Updating Format with .with()
+
+```typescript
+const price = step.addNumber({ name: 'price', label: 'Price' })
+// Update format after construction
+price.with({
+ format: { numberStyle: 'currency', currency: 'USD', minimumFractionDigits: 2 },
+})
+```
+
+## FormatBuilder Class
+
+Use `FormatBuilder` to format values for text display in `submissionItemTitle`, `submissionItemSubtitle`, arrayField item `title`/`subtitle`/`description`, and step `title`. Supports same number options as field format, plus date formatting.
+
+### Number Formatting with FormatBuilder
+
+```typescript
+// Step 1: Collect balance
+const step1 = form.addStep(
+ { instanceId: 'input', title: 'Enter Balance', icon: 'accounting-calculator' },
+ (step) => {
+  step.addNumber({ name: 'balance', label: 'Balance' })
+ },
+)
+// Step 2: Display formatted balance in title
+form.addStep(
+ {
+  instanceId: 'summary',
+  title: new I18nBuilder('balance.display', 'Balance: {amount}', {
+   amount: new FormatBuilder(
+    new JsonataBuilder('$balance', { balance: step1.data.getFieldData('balance') }),
+    { numberStyle: 'currency', currency: 'USD' },
+   ),
+  }),
+  icon: 'cash-payment-wallet',
+ },
+ (step) => {
+  step.addText({ name: 'note', label: 'Note' })
+ },
+)
+```
+
+### Date Formatting with FormatBuilder
+
+```typescript
+// Step 1: Collect date
+const step1 = form.addStep(
+ { instanceId: 'input', title: 'Enter Date', icon: 'calendar-date' },
+ (step) => {
+  step.addDate({ name: 'updatedAt', label: 'Last Updated' })
+ },
+)
+// Step 2: Display formatted date in title
+form.addStep(
+ {
+  instanceId: 'activity',
+  title: new I18nBuilder('activity.updated', 'Updated {when}', {
+   when: new FormatBuilder(
+    new JsonataBuilder('$date', { date: step1.data.getFieldData('updatedAt') }),
+    { dateFormat: 'fromNow' },
+   ),
+  }),
+  icon: 'stopwatch',
+ },
+ (step) => {
+  step.addText({ name: 'note', label: 'Note' })
+ },
+)
+```
+
+## Date Format Codes
+
+Use these format codes with `FormatBuilder` for date display:
+
+| Format | Example Output | Description |
+| --- | --- | --- |
+| `'fromNow'` | "2 hours ago", "3 days ago" | Relative time (past) |
+| `'toNow'` | "in 23 hours" | Relative time (future) |
+| `'LT'` | "3:28 PM" | Time only |
+| `'LTS'` | "3:28:57 PM" | Time with seconds |
+| `'L'` | "03/03/2022" | Short date |
+| `'l'` | "3/3/2022" | Short date (no padding) |
+| `'LL'` | "March 3, 2022" | Long date (default) |
+| `'ll'` | "Mar 3, 2022" | Abbreviated date |
+| `'LLL'` | "March 3, 2022 3:28 PM" | Long date + time |
+| `'lll'` | "Mar 3, 2022 3:28 PM" | Abbreviated date + time |
+| `'LLLL'` | "Thursday, March 3, 2022 3:28 PM" | Full date + time |
+| `'llll'` | "Thu, Mar 3, 2022 3:28 PM" | Abbreviated full |
+| `'HH:mm'` | "15:28" | 24-hour format |
+
+## Common Mistakes
+
+### Don't use date fields without FormatBuilder
+
+Date fields store ISO 8601 strings. Using a raw date reference displays unformatted text like `"2024-01-15T14:30:00Z"`. This applies to `submissionItemTitle`, `submissionItemSubtitle`, arrayField `title`/`subtitle`/`description`, and step `title`. Always wrap in `FormatBuilder` with a `dateFormat` option.
+
+**In submission title/subtitle:**
+
+```typescript
+const step1 = form.addStep({ instanceId: 'booking', icon: 'calendar' }, (step) => {
+ step.addDate({ name: 'appointment', label: 'Appointment Date' })
+})
+// WRONG: using JsonataBuilder alone displays raw ISO string like "2024-01-15T14:30:00Z"
+// submissionItemTitle: new JsonataBuilder('$date', { date: step1.data.getFieldData('appointment') })
+// CORRECT: always wrap date fields in FormatBuilder
+// Displays: "January 15, 2024"
+form.with({
+ submissionItemTitle: new FormatBuilder(
+  new JsonataBuilder('$date', { date: step1.data.getFieldData('appointment') }),
+  { dateFormat: 'LL' },
+ ),
+ submissionItemSubtitle: 'Booking',
+})
+```
+
+**In arrayField item title/subtitle:**
+
+```typescript
+const events = step.addArrayField({ name: 'events', label: 'Events' })
+// WRONG: raw ISO string in title
+// events.with({
+//  title: new JsonataBuilder('$date', { date: events.getCurrentItemRef('eventDate') }),
+// })
+// CORRECT: wrap in FormatBuilder
+events.with({
+ title: new FormatBuilder(
+  new JsonataBuilder('$date', { date: events.getCurrentItemRef('eventDate') }),
+  { dateFormat: 'LL' },
+ ),
+})
+events.addText({ name: 'eventName', label: 'Event Name' })
+events.addDate({ name: 'eventDate', label: 'Event Date' })
+```
+
+### Don't use JSONata formatting functions
+
+**Wrong:**
+
+```typescript
+// DON'T DO THIS - use format property instead of JSONata functions
+value: new JsonataBuilder('$formatNumber($price, "#,##0.00")', {
+  price: step1.data.getFieldData('price')
+})  // JSONata formatting is not locale-aware
+```
+
+**Correct:**
+
+```typescript
+step.addNumber({
+ name: 'price',
+ label: 'Price',
+ format: { numberStyle: 'currency', currency: 'USD' },
+})
+```
+
+**Benefits of format property / FormatBuilder:**
+
+- Validates options at build time
+- Type-safe configuration
+- Integrates with field rendering
+- Handles locale automatically
+
+## Best Practices
+
+| Scenario | Approach |
+| --- | --- |
+| Disabled number field | Field `format` property |
+| `submissionItemTitle` / `submissionItemSubtitle` with formatting | `I18nBuilder` + `FormatBuilder` |
+| ArrayField `title` / `subtitle` / `description` with formatting | `I18nBuilder` + `FormatBuilder` |
+| Step `title` with formatting | `I18nBuilder` + `FormatBuilder` |
+| Date values in any display property | Always `FormatBuilder` (even without `I18nBuilder`) |
+| Never | JSONata `$formatNumber()` / `$formatBase()` functions |
+
+**Ref:** `./i18n.md` for internationalization patterns