@jigx/core-sdk 1.1.0 → 1.2.0-rc

package/docs/convention-naming.md

@@ -0,0 +1,102 @@
+# Convention: Naming
+
+## File and component naming
+
+All files and components that map to output files follow this pattern:
+
+```
+{type}-{entity}-{action}
+```
+
+Keep names short. The type prefix indicates what the component is.
+
+| Type | Prefix | Examples |
+| --- | --- | --- |
+| Jig (screen) | `jig-` | `jig-customer-create`, `jig-customer-list`, `jig-customer-view` |
+| Action | `act-` | `act-customer-save`, `act-customers-sync` |
+| Datasource | `data-` | `data-select-customers`, `data-select-customer` |
+| Function (REST) | `rest-` | `rest-get-customers`, `rest-put-customer` |
+
+Functions are the exception — prefix with the call type and HTTP method: `rest-get-`, `rest-put-`, `rest-post-`, `rest-delete-`.
+
+## TypeScript file names match the component ID
+
+```
+src/
+├── screens/
+│   ├── jig-customer-list.ts       # screenId: 'jig-customer-list'
+│   ├── jig-customer-create.ts     # screenId: 'jig-customer-create'
+│   └── jig-customer-view.ts       # screenId: 'jig-customer-view'
+├── functions/
+│   └── rest-put-customer.ts       # functionId: 'rest-put-customer'
+├── actions/
+│   └── act-customer-save.ts       # actionId: 'act-customer-save'
+```
+
+## Function export names
+
+Use camelCase matching the file name:
+
+```typescript
+// jig-customer-list.ts
+export function jigCustomerList(app: ApplicationBuilder): void { ... }
+
+// act-customer-save.ts
+export function actCustomerSave(app: ApplicationBuilder): void { ... }
+
+// rest-put-customer.ts
+export function restPutCustomer(app: ApplicationBuilder): void { ... }
+```
+
+## Constants use the component IDs
+
+```typescript
+export const SCREEN = {
+  CUSTOMER_LIST: 'jig-customer-list',
+  CUSTOMER_CREATE: 'jig-customer-create',
+  CUSTOMER_VIEW: 'jig-customer-view',
+} as const
+
+export const ACTION = {
+  CUSTOMER_SAVE: 'act-customer-save',
+  CUSTOMER_SAVE_REMOTE: 'act-customer-save-remote',
+} as const
+
+export const FUNCTION = {
+  REST_PUT_CUSTOMER: 'rest-put-customer',
+} as const
+
+export const GLOBAL_DATASOURCE = {
+  CONFIG: 'data-select-config',
+  CUSTOMERS: 'data-select-customers',
+  CUSTOMER_TO_SAVE: 'data-select-customer-to-save',
+} as const
+
+export const ENTITY = {
+  CONFIG: { TABLE: 'config', FQN: 'default/config' },
+  CUSTOMERS: { TABLE: 'customers', FQN: 'default/customers' },
+  CONTACTS: { TABLE: 'contacts', FQN: 'default/contacts' },
+} as const
+```
+
+## Field naming convention
+
+Name `instanceId` values to match the external schema field names. This makes the form component state (`@ctx.components.<instanceId>.state.value`) naturally map to the expected data shape.
+
+For fields in nested schema objects that collide (e.g., `Phone1` exists on both `PrimaryContact` and `MainContact`), prefix with the parent: `PrimaryContact-Phone1`, `MainContact-Phone1`.
+
+Fields on separate tab screens don't collide — each screen has its own component namespace.
+
+## Config naming convention
+
+Config field names are case-sensitive. Keep the Acumatica URL fields identical everywhere:
+
+- REST: `acumaticaURL`
+- OData: `acumaticaOdataURL`
+
+Use the same casing in:
+
+- `default/config` data
+- datasource expressions such as `@ctx.datasources.data-select-config.data.acumaticaURL`
+- function path parameters
+- action `parameters`

package/docs/date-field.md

@@ -0,0 +1,92 @@
+## Display in Titles
+
+Date fields store ISO 8601 strings. When referencing in `submissionItemTitle`, `submissionItemSubtitle`, arrayField `title`/`subtitle`/`description`, or step `title`, **always wrap in `FormatBuilder`** with a `dateFormat` option — otherwise unreadable ISO strings like `"2024-01-15T14:30:00Z"` display.
+
+Recommended `dateFormat` by mode:
+
+| Mode | Format | Example |
+| --- | --- | --- |
+| `'date'` | `'LL'` | January 15, 2024 |
+| `'time'` | `'LT'` | 3:28 PM |
+| `'datetime'` | `'LLL'` | January 15, 2024 3:28 PM |
+
+**Ref:** `./formatting.md` for `FormatBuilder` usage, date format codes, and examples
+
+## Date Field Modes
+
+```typescript
+// Date only (default)
+step.addDate({
+ name: 'birthday',
+ label: 'Date of Birth',
+})
+// Time only
+step.addDate({
+ name: 'meeting-time',
+ label: 'Meeting Time',
+ mode: 'time',
+})
+// Date and time
+step.addDate({
+ name: 'appointment',
+ label: 'Appointment',
+ mode: 'datetime',
+})
+```
+
+## Date Constraints (min/max)
+
+Restrict selectable dates with `minimum` and `maximum`:
+
+```typescript
+// Future dates only (min = today)
+step.addDate({
+ name: 'booking-date',
+ label: 'Booking Date',
+ minimum: '2024-01-01',
+})
+// Date range constraint
+step.addDate({
+ name: 'event-date',
+ label: 'Event Date',
+ minimum: '2024-01-01',
+ maximum: '2024-12-31',
+})
+```
+
+## Dynamic Constraints
+
+Use JsonataBuilder for dynamic min/max values:
+
+```typescript
+// Minimum from current date
+step.addDate({
+ name: 'future-date',
+ label: 'Select Future Date',
+ minimum: new JsonataBuilder('$now()'),
+})
+// Maximum 6 months from now
+step.addDate({
+ name: 'deadline',
+ label: 'Deadline',
+ maximum: new JsonataBuilder('$fromMillis($millis() + 180*24*60*60*1000)'),
+})
+```
+
+## Date Range (Two Fields)
+
+Link start and end dates so end is always after start:
+
+```typescript
+const startDate = step.addDate({
+ name: 'start-date',
+ label: 'Start Date',
+ minimum: '=$now()',
+})
+// End date must be after start date
+step.addDate({
+ name: 'end-date',
+ label: 'End Date',
+ minimum: startDate.state.value,
+})
+```