Form Field Component

Purpose

Form Field is a component that wraps a form field and provides a label, description, and error message.

Field Component

Field Component is using Formik for form management. It is a wrapper for Formik's field component. More information about Formik's field component can be found here.

Field Definition

Field definition is used to define the field component. It is used to define the field component in the form.

component: field
name: firstName # component / field name is required
props:
  label: First Name # label of the field
  type: text # type of the field

Props

• label (string): The label of the field. (localized)
• description (string): The description of the field. (localized)
• error (string): The error message of the field. (localized)
• type (string): The type of the field. It accepts text, number, password, email, checkbox, radio, select, select-async, textarea, date, time, datetime, url, tel, file, hidden, image, range.
• placeholder (string): The placeholder of the field.
• defaultValue (string): The default value of the field.
• items (array): The items of the field. It is used for radio and select types.
• options (object): The options of the field. Options for Formik field component.

Yaml Example

component: field
name: firstName
props:
  label: First Name
  type: text
  placeholder: Enter your first name
  defaultValue: John

Field Types

The following types are supported:

• text
• number
• password
• email
• checkbox
• radio
• select
• select-async
• textarea
• date
• time
• datetime
• url
• tel
• hidden
• file
• image
• range

Text

The text type is used for single-line text input.

component: field
name: firstName
props:
  label: First Name
  type: text
  placeholder: Enter your first name

Number

The number type is used for input fields that should contain a numeric value.

Options: https://s-yadav.github.io/react-number-format/docs/numeric_format for more details.

component: field
name: age
props:
  label: Age
  type: number
  placeholder: Enter your age
  options:
    decimalScale: 3

Password

The password type is used for password input fields.

component: field
name: password
props:
  label: Password
  type: password
  placeholder: Enter your password

Email

The email type is used for email input fields.

component: field
name: email
props:
  label: Email
  type: email
  placeholder: Enter your email

Checkbox

The checkbox type is used for checkboxes.

component: field
name: terms
props:
  label: Terms
  type: checkbox
  onChange:
    - if: "{{ value }}"
      then: # if checked
        - setStore:
            terms: "T"
      else: # if unchecked
        - setStore:
            terms: "N"
  onKeyPress: # on key press event for the field
    - if: "{{ eval keyCode === 13 }}"
      then: # if enter key is pressed
        - consoleLog: "Enter key pressed"

Radio

The radio type is used for radio buttons.

component: field
name: PaymentMethod
props:
  label: Payment Method
  type: radio
  items:
    - label: Credit Card
      value: creditCard
    - label: PayPal
      value: payPal

Select

The select type is used for select dropdowns.

component: field
name: country
props:
  label: Country
  type: select
  options:
    allowSearch: true
    allowClear: true
    allowMultiple: true
    allowCreate: true
  items:
    - label: United States
      value: us
    - label: Canada
      value: ca

Select Async

Select with query is used to load options from a GraphQL query.

component: field
name: country
props:
  label: Country
  type: select-async
  options:
    valueFieldName: "countryCode" # if name is different than value field
    itemLabelTemplate: "{{value}}"
    itemValueTemplate: "{{id}}"
    searchQuery:
      name: getCountries
      path: countries
      totalCountPath: totalCount
    valueQuery:
      name: getCountry
      path: country
    allowSearch: true
    allowClear: true
    allowMultiple: false
    allowCreate: true
    queries:
      - name: getCountries
        query:
          command: "query { countries { id name } }"
          variables: { search: "{{search}}" }
      - name: getCountry
        query:
          command: "query { country(id: {{id}}) { id name } }"
        variables: { id: "{{id}}" }
    dropDownToolbar:
      - component: button
        name: createCountryBtn
        props:
          label:
            en-US: Create Country
          icon: plus
          options:
            variant: primary
          onClick:
            - dialog:
                component: Countries/CreateCountry
                onClose:
                  - selectValue: "{{ result.countryCode }}"
    onSelectValue:
      - setStore:
          selectedCountry: "{{ selectedItem }}"
    onCreateValue:
      - mutation:
          command: "mutation { createCountry(input: { countryCode: '{{ value }}' }) { countryCode } }"
          variables: { value: "{{ value }}" }

Select Async Options

• itemLabelTemplate (string): The template for the label of the item.
• itemValueTemplate (string): The template for the value of the item.
• searchQuery (object): The search query for the select dropdown.
• valueQuery (object): The value query for the select dropdown.
• allowSearch (boolean): Allow search in the select dropdown.
• allowClear (boolean): Allow clear in the select dropdown.
• allowMultiple (boolean): Allow multiple selection in the select dropdown.
• allowCreate (boolean): Allow create in the select dropdown.
• queries (array): The queries for the select dropdown.
• dropDownToolbar (components): The toolbar component to be displayed in the dropdown.
• onSelectValue (array): The actions to be executed when a value is selected.
• onCreateValue (array): The actions to be executed when a value is created.

Select Async Additional Actions

• 'refreshSelect': Reload the selected value from the server.

Textarea

The textarea type is used for multi-line text input.

component: field
name: description
props:
  label: Description
  type: textarea
  placeholder: Enter your description
  options:
    rows: 3

Date

The date type is used for date input fields.

component: field
name: date
props:
  label: Date
  type: date
  options:
    format: "MM/dd/yyyy"

Time

The time type is used for time input fields.

component: field
name: time
props:
  label: Time
  type: time
  options:
    format: "hh:mm a"

Datetime

The datetime type is used for date and time input fields.

component: field
name: datetime
props:
  label: Date and Time
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    useTimezone: false # default: false - displays the same time for all users
    timezone: "UTC" # specify a fixed timezone (e.g., "UTC", "America/New_York")
    storeAsUTC: false # default: false - stores exactly as entered
    showTimeSelect: false # default: false - whether to show time selection

Datetime Options

All datetime configuration should be placed inside the options object. Direct props attributes are obsolete and should not be used.

Core Options:

• format (string): The display format for the datetime (uses moment.js format strings). Default: "MM/dd/yyyy hh:mm a"
• useTimezone (boolean): Whether to convert datetime to user's local timezone. Default: false - displays the same time for all users
• timezone (string): Fixed timezone to use for display (e.g., "UTC", "America/New_York", "Europe/London"). Overrides user timezone
• storeAsUTC (boolean): Whether to store the value as UTC in the database. Default: false

Time Selection Options:

• showTimeSelect (boolean): Whether to show time selection in the datetime picker. Default: true
• showTimeSelectOnly (boolean): Show only time selection without date picker. Default: false
• timeIntervals (number): The interval between time options in minutes. Default: 10
• timeCaption (string): The label for the time dropdown. Default: "Time"

Obsolete Configuration: ⚠️ The following direct props attributes are obsolete and should be migrated to the options object:

• dateFormat → Use options.format
• showTimeSelect → Use options.showTimeSelect
• showTimeSelectOnly → Use options.showTimeSelectOnly
• timeIntervals → Use options.timeIntervals
• timeCaption → Use options.timeCaption
• useTimezone → Use options.useTimezone

Datetime Configuration Quick Reference

Configuration	Use Case	Example	Result
useTimezone: false storeAsUTC: false	Location-specific times (port schedules)	Vessel departs Shanghai 14:00	All users see 14:00
useTimezone: true storeAsUTC: true	User-relative times (meetings, deadlines)	Virtual meeting at 2 PM UTC	NY user sees 10 AM London user sees 3 PM
timezone: "America/New_York" storeAsUTC: true	Fixed timezone display (business hours)	NY office hours	All users see EST/EDT times

Non-Timezone Specific Datetime

To ensure all users see the same date and time regardless of their location, configure the datetime field with timezone conversion disabled:

component: field
name: eventDateTime
props:
  label: Event Date and Time
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    useTimezone: false # Disable timezone conversion
    storeAsUTC: false # Store exactly as entered

Use Cases for Non-Timezone Specific Datetime

1. Logistics Cut-off Times

component: field
name: bookingCutoffTime
props:
  label: Booking Cut-off Time
  type: datetime
  options:
    format: "MM/dd/yyyy HH:mm"
    useTimezone: false
    storeAsUTC: false
  description: "Cut-off time at origin port (local time)"

2. Vessel/Flight Departure Times

component: field
name: vesselDepartureTime
props:
  label: Vessel Departure Time
  type: datetime
  options:
    format: "MM/dd/yyyy HH:mm"
    useTimezone: false
    storeAsUTC: false
  description: "Actual departure time at port of loading"

3. Document Submission Deadlines

component: field
name: documentDeadline
props:
  label: Document Submission Deadline
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    useTimezone: false
    storeAsUTC: false
  description: "Deadline based on destination country requirements"

4. Warehouse Operating Hours

component: field
name: warehouseOpenTime
props:
  label: Warehouse Opening Time
  type: datetime
  options:
    format: "MM/dd/yyyy HH:mm"
    useTimezone: false
    storeAsUTC: false
  description: "Local warehouse operating hours"

When to Use Non-Timezone Specific Datetime

Use useTimezone: false and storeAsUTC: false when:

• Location-based times: The time is specific to a physical location (port, warehouse, airport)
• Regulatory deadlines: Government or customs deadlines that apply regardless of user location
• Operational schedules: Fixed schedules like vessel departures, flight times, or facility hours
• Historical records: Recording when something actually happened at a specific location
• Cross-border coordination: When multiple parties need to see the same absolute time

Important Considerations

1. Display clarity: Always include location context in the field label or description
2. User training: Ensure users understand they're entering/viewing location-specific times
3. Validation: Consider adding validation to prevent confusion (e.g., business hours validation)
4. Reporting: Reports should clearly indicate that times are location-specific, not user-adjusted

Timezone-Aware Datetime (Default Behavior)

When timezone conversion is needed to show times relative to each user's location:

component: field
name: meetingTime
props:
  label: Meeting Time
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    useTimezone: true # Explicitly enable - default is false
    storeAsUTC: true # Explicitly enable - default is false

Use Cases for Timezone-Aware Datetime

1. Virtual Meetings/Conference Calls

component: field
name: webinarStartTime
props:
  label: Webinar Start Time
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    useTimezone: true
    storeAsUTC: true
  description: "Time will be displayed in your local timezone"

2. System Notifications/Alerts

component: field
name: notificationTime
props:
  label: Send Notification At
  type: datetime
  options:
    format: "MM/dd/yyyy HH:mm"
    useTimezone: true
    storeAsUTC: true
  description: "Notification will be sent at this time in your timezone"

3. Task Deadlines for Remote Teams

component: field
name: taskDeadline
props:
  label: Task Deadline
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    useTimezone: true
    storeAsUTC: true
  description: "Deadline adjusted to your local time"

4. Shipment Tracking Updates

component: field
name: lastUpdateTime
props:
  label: Last Status Update
  type: datetime
  options:
    format: "MM/dd/yyyy HH:mm:ss"
    useTimezone: true
    storeAsUTC: true
  description: "Timestamp shown in your local time"

When to Use Timezone-Aware Datetime

Use useTimezone: true (default) when:

• User-relative activities: Meetings, calls, or events where each user needs to see their local time
• System timestamps: Created/modified times, audit logs, tracking updates
• Personal deadlines: Task due dates that should be relative to the user's working hours
• Notifications: Scheduled alerts that should trigger based on user's local time
• Global coordination: When teams across timezones need to coordinate but see their own local times

Timezone Conversion Examples

Created/Modified Timestamps

component: field
name: createdAt
props:
  label: Created At
  type: datetime
  options:
    format: "MM/dd/yyyy HH:mm:ss"
    useTimezone: true # User in NY sees 3:00 PM, user in London sees 8:00 PM
    storeAsUTC: true
  readOnly: true

Email Send Time

component: field
name: scheduledSendTime
props:
  label: Schedule Email Send
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    useTimezone: true # Each user schedules based on their local time
    storeAsUTC: true
  description: "Email will be sent at this time in your timezone"

Fixed Timezone Datetime

To display datetime in a specific timezone for all users:

component: field
name: appointmentTime
props:
  label: Appointment Time (EST)
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    timezone: "America/New_York" # Always display in EST
    storeAsUTC: true # Still store as UTC in database

Comprehensive Datetime Examples

1. Time Selection Only

component: field
name: appointmentTime
props:
  label: Appointment Time
  type: datetime
  options:
    showTimeSelectOnly: true # Only show time picker
    showTimeSelect: true
    timeIntervals: 15 # 15-minute intervals
    timeCaption: "Select Time"
    format: "hh:mm a"

2. Date Only (No Time Selection)

component: field
name: birthDate
props:
  label: Date of Birth
  type: datetime
  options:
    showTimeSelect: false # Disable time selection
    format: "MM/dd/yyyy"

3. Custom Time Intervals

component: field
name: meetingTime
props:
  label: Meeting Time
  type: datetime
  options:
    showTimeSelect: true
    timeIntervals: 30 # 30-minute intervals
    timeCaption: "Meeting Time"
    format: "MM/dd/yyyy hh:mm a"

4. Port Operations Schedule (No Timezone Conversion)

component: field
name: vesselArrival
props:
  label: Vessel Arrival (Port Local Time)
  type: datetime
  options:
    format: "MM/dd/yyyy HH:mm"
    showTimeSelect: true
    timeIntervals: 60 # Hourly intervals
    useTimezone: false # No timezone conversion
    storeAsUTC: false # Store as entered
  description: "Enter the actual arrival time at the port"

5. Global Team Meeting (With Timezone)

component: field
name: globalMeeting
props:
  label: Global Team Meeting
  type: datetime
  options:
    format: "MM/dd/yyyy hh:mm a"
    showTimeSelect: true
    timeIntervals: 15
    useTimezone: true # Convert to user's timezone
    storeAsUTC: true # Store as UTC
  description: "Time will be shown in your local timezone"

6. Warehouse Shift Schedule

component: field
name: shiftStart
props:
  label: Shift Start Time
  type: datetime
  options:
    showTimeSelectOnly: true
    showTimeSelect: true
    timeIntervals: 30
    timeCaption: "Shift Start"
    format: "HH:mm"
    useTimezone: false # Fixed time for warehouse location
    storeAsUTC: false

URL

The url type is used for URL input fields.

component: field
name: url
props:
  label: URL
  type: url
  placeholder: Enter your URL

Tel

The tel type is used for telephone input fields.

component: field
name: phone
props:
  label: Phone
  type: tel
  placeholder: Enter your phone number

Attachment

Attachment type is used for attachment input fields. It will create a new attachment record in the database and return the attachment id.

component: field
name: attachment
props:
  label: Attachment
  type: attachment
  options:
    allowMultiple: false
    allowClear: true
    displayAs: "image" # image, file
    previewWidth: 100 # optional
    previewHeight: 100 # optional
    maxSize: 10485760 # 10MB
    allowedExtensions:
      - "image/*"
      - "application/pdf"
    onUploaded:
      - consoleLog: "{{ result.attachmentId }}"

File

The file type is used for file input fields. File type will upload the file to the temp storage and return the file ur

component: field
name: file
props:
  label: File
  type: file

Hidden

The hidden type is used for hidden input fields.

component: field
name: id
props:
  label: ID
  type: hidden
  defaultValue: 1

Image

The image type is used for image input fields.

component: field
name: image
props:
  label: Image
  type: image

Range

The range type is used for range input fields.

component: field
name: range
props:
  label: Range
  type: range
  options:
    min: 0
    max: 100
    step: 1

Field Actions

The following actions are supported:

• setValue - Set value for a field. Available for form fields only.

Autocomplete

The autocomplete type is used for autocomplete input fields.

component: field
name: country
props:
  label: Country
  type: autocomplete
  options:
    allowSearch: true
    allowClear: true
    allowMultiple: true
    allowCreate: true
  items:
    - label: United States
      value: us
    - label: Canada
      value: ca

Autocomplete (Draft)

Autocomplete with query is used to load options from a GraphQL query.

component: field
name: country
props:
  label: Country
  type: autocomplete
  options:
    searchQuery:
      name: getCountries
      path: countries
    queries:
      - name: getCountries
        query:
          command: "query { countries { id name } }"
          variables: { search: "{{search}}" }
    onSelectValue:
      - setStore:
          selectedCountry: "{{ selectedItem }}"

Autocomplete Async With Google Places (Draft)

Autocomplete with Google Places is used to load options from Google Places API.

component: field
name: location
props:
  label: Location
  type: autocomplete
  options:
    searchQuery:
      type: googlePlaces
      options:
        apiKey: '{{ YOUR_GOOGLE_PLACES_API_KEY }}'
        locationRestriction: { country: 'us' }
        origin: { lat: 37.7749, lng: -122.4194 }
        includedPrimaryTypes: ['locality', 'administrative_area_level_1', 'country']
        language: "en-US",
        region: "us",
        fields: ['address_components', 'geometry', 'icon', 'name', 'place_id', 'types']
    onSelectValue:
      - setStore:
          selectedLocation: '{{ selectedItem }}'