> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personal

> The Personal Screen component enables end-users to enter their details securely for verification against government data sources. This guide covers implementation, customization, and event handling.

## Quick Start

<Steps>
  <Step title="Add HTML Container">
    ```html theme={null}
    <div id="form"></div>
    ```
  </Step>

  <Step title="Initialize Component">
    ```javascript theme={null}
    const personal = oneSdk.component("form", {
      name: "PERSONAL",
      type: "manual",
    });

    // Mount to your container
    personal.mount("#form");
    ```
  </Step>
</Steps>

## Configuration Guide

<AccordionGroup>
  <Accordion title="Basic Configuration">
    ### General Settings

    ```javascript theme={null}
    const personal = oneSdk.component('form', {
      name: "PERSONAL",
      type: "manual",
      title: {
        label: "Your Personal Details",
        style: { 'ff-title': {} }
      },
      descriptions: [
        {label: 'We need to collect your data'}
      ],
      logo: {
        src: './assets/logo.png' // path to your logo
      },
      style: {
        'ff-logo': {
          'width': '50px'
        }
      }
    });
    ```

    For more detailed configuration options, please refer to the <a href="#field-configuration">Field Configuration</a> section below
  </Accordion>

  <Accordion title="Country-Specific Configuration">
    You can customize fields based on country (using ISO 3166-1 alpha-3 codes) and state:

    ```javascript theme={null}
    const personal = oneSdk.component('form', {
      name: "PERSONAL",
      type: "manual",
      personal: {
        countries: {
          AUS: {
            NSW: { /* NSW specific config */ },
            default: { /* Other AU states */ }
          },
          NZL: {
            default: { /* NZ config */ }
          },
          default: {
            default: { /* Default config */ }
          }
        }
      }
    });
    ```
  </Accordion>
</AccordionGroup>

## Field Configuration

<Tabs>
  <Tab title="Name">
    ### Name

    <CardGroup cols={2}>
      <Card title="Available Fields">
        * givenName
        * middleName
        * familyName
      </Card>

      <Card title="Common Properties">
        * fieldType: 'input'
        * dataType: 'text'
        * label: Custom label
        * hide: true/false
        * rules:
          * required: \{ value: 'boolean', message: 'string' }
          * pattern: \{ value: 'regex string', message: 'string' }
      </Card>
    </CardGroup>

    ```javascript theme={null}
    fields: [
      {
        fieldType: "input",
        name: "givenName",
        label: "Given Name:",
        dataType: 'text',
        hide: false,
        helperText: "As shown on your ID",
        rules: {
          required: {
            value: true,
            message: "Please enter your given name"
          },
          pattern: {
            value: "^[a-zA-Z]+(\\s+[a-zA-Z]+)*$",
            message: "Please use alphabetic characters only"
          }
        }
      }
    ]
    ```
  </Tab>

  <Tab title="Date of Birth">
    ### Date of Birth

    <CardGroup cols={2}>
      <Card title="Calendar Types">
        * gregorian
        * buddhist
        * chinese
        * islamic
        * persian
      </Card>

      <Card title="Locales">
        * en (English)
        * zh (Chinese)
        * ja (Japanese)
        * ko (Korean)
      </Card>
    </CardGroup>

    ```javascript theme={null}
    {
      fieldType: "date",
      name: "dateOfBirth",
      label: "Date of Birth",
      calendarConfig: {
        type: 'gregorian',
        locale: 'en',
        age: {
          min: 18,
          max: 85,
          message: "Age must be between 18 and 85"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Address">
    ### Address

    <Callout icon="bell" color="#FFCA16" iconType="regular">
      To enable address auto-complete, you must provide a Google Maps API key during SDK initialization.
    </Callout>

    <Callout icon="bell" color="#FFCA16" iconType="regular">
      As of March 1st, 2025, google deprecate `AutocompleteService` to new
      customers and replace it with `AutocompleteSuggestion`
      [source <Icon icon="arrow-up-right-from-square" size={12} />](https://developers.google.com/maps/documentation/javascript/reference/places-autocomplete-service).
      To enable new `AutocompleteSuggestion` by google, you can set
      `useGoogleAutoCompleteSuggestion` to `true`.
    </Callout>

    ```javascript theme={null}
    const oneSdk = await OneSdk({
      session: sessionObjectFromBackend,
      mode: "production",
      recipe: {
        form: {
          provider: {
            name: 'react',
            googleApiKey: "YOUR_API_KEY",

            // Optional. Default: false
            // This is to opt-in the new `AutocompleteSuggestion` by google
            useGoogleAutoCompleteSuggestion: true
          }
        }
      }
    });
    ```

    <CardGroup cols={2}>
      <Card title="Available Fields">
        * address.fullAddress
        * address.country
        * address.unitNumber
        * address.streetAddress
        * address.town
        * address.state
        * address.postalCode
      </Card>

      <Card title="Common Properties">
        * fieldType: 'input' | 'select' | 'text'
        * name: 'field name' (see Available Fields)
        * dataType: 'text'
        * label: Custom label
        * hide: true/false
        * rules:
          * required: \{ value: 'boolean', message: 'string' }
          * pattern: \{ value: 'regex string', message: 'string' }
      </Card>
    </CardGroup>

    ```javascript theme={null}
    {
      // Main address field configuration
      fieldType: 'address',
      dataType: 'current_addr',
      name: 'address.fullAddress',
      // Restrict address lookup to Australia and New Zealand only
      acceptedCountries: ["AUS", "NZL"],

      // Configuration for manual address entry fields
      manualFieldConfig: [
        {
          // Country dropdown field
          fieldType: 'select',
          dataType: 'text',
          hide: false,
          label: 'Country',
          name: 'address.country',
          rules: {
            required: {
              value: true,
              message: `Please select your country`,
            },
          },
        },
        {
          // Optional unit/apartment number field
          fieldType: 'input',
          dataType: 'text',
          hide: false,
          label: 'Unit Number (optional)',
          name: 'address.unitNumber',
        },
        {
          // Street address field with required validation
          fieldType: 'input',
          dataType: 'text',
          hide: false,
          label: 'Street Address',
          name: 'address.streetAddress',
          rules: {
            required: {
              value: true,
              message: 'Please enter your street address',
            },
          },
        },
        {
          // Suburb/Town field with required validation
          fieldType: 'input',
          dataType: 'text',
          hide: false,
          label: 'Suburb / Town',
          name: 'address.town',
          rules: {
            required: {
              value: true,
              message: 'Please enter your suburb/town.',
            },
          },
        },
        {
          // State dropdown field with required validation
          fieldType: 'select',
          dataType: 'text',
          hide: false,
          label: "State",
          name: 'address.state',
          placeholder: 'Select Your State',
          rules: {
            required: {
              value: true,
              message: 'Please enter your state',
            },
          },
        },
        {
          // Postal code field with length and required validation
          dataType: 'text',
          hide: false,
          label: "Postal Code",
          name: 'address.postalCode',
          rules: {
            required: {
              value: true,
              message: 'Please enter your postal code',
            },
            minLength: {
              value: 4,
              message: "should be 4 characters",
            },
            maxLength: {
              value: 4,
              message: "Should be 4 characters",
            },
          },
        },
      ],
    }
    ```

    <Callout icon="bell" color="#FFCA16" iconType="regular">
      ##### Caution

      When customizing the `manualFieldConfig` field, you must override all fields
      in `manualFieldConfig` as shown in the example above. Additionally, if you
      have specified `acceptedCountries`, you will need to redefine the configuration
      for each country in the `personal` field. Currently, this is the only available
      approach.
    </Callout>

    <Callout icon="star" color="#3DD892" iconType="regular">
      ##### Best Practice

      Create reusable units to define the `manualFieldConfig` for each supported
      country. This is useful when you need different validation rules for different
      countries (e.g., postal code lengths vary between Australia and the UK).
    </Callout>
  </Tab>

  <Tab title="Custom">
    ### Custom

    Other than the default fields, you can also add custom fields to the
    form and manage the order of the fields.

    <Card title="Properties">
      * name: 'extraData.yourDesiredFieldName'
      * fieldType: 'input'
      * dataType: 'text'
      * label: Custom label
      * hide: true/false
      * rules:
        * required: \{ value: 'boolean', message: 'string' }
        * pattern: \{ value: 'regex string', message: 'string' }
    </Card>

    <Callout icon="bell" color="#FFCA16" iconType="regular">
      You must define the fields to all your supported countries
      and ensure the field name has prefix `extraData.` followed by the field name
    </Callout>

    <Tabs>
      <Tab title="Add new fields">
        In this example, the field will be appear at the top of the default form.

        ```javascript theme={null}
        {
          countries: {
            default: {
              default: {
                fields: [
                  {
                    name: "extraData.personTitle",
                    fieldType: "input",
                    dataType: "text",
                    label: "Title",
                    rules: {
                      required: {
                        value: true,
                        message: "Please enter your title",
                      },
                    },
                  },
                ],
              },
            },
          },
        }
        ```
      </Tab>

      <Tab title="Fields Ordering">
        If you want to change the order of the fields, simply add them
        to the `fields` array in the desired order.
        For example, if you want a field to appear below the `givenName` field,
        redefine the existing `givenName` field and add the new field below it in the array.

        ```javascript theme={null}
        {
          countries: {
            default: {
              default: {
                fields: [
                  {
                    name: "givenName",
                  },
                  {
                    name: "extraData.personTitle",
                    fieldType: "input",
                    dataType: "text",
                    label: "Title",
                    rules: {
                      required: {
                        value: true,
                        message: "Please enter your title",
                      },
                    },
                  },
                ],
              },
            },
          },
        }
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Event Handling

<CardGroup cols={3}>
  <Card title="form:personal:loaded">
    Emitted when the screen is successfully mounted
  </Card>

  <Card title="form:personal:ready">
    Emitted when form submission is complete and ready for next step
  </Card>

  <Card title="form:personal:failed">
    Emitted when an error occurs during form operation
  </Card>
</CardGroup>

### Event Listener Example

```javascript theme={null}
personal.on("form:personal:ready", (data) => {
  // Handle successful form completion
  console.log("Form completed:", data);
});
```

<Callout icon="star" color="#3DD892" iconType="regular">
  ##### Best Practice

  Always implement error handling and loading states when working with Personal
  Screen events to provide a smooth user experience.
</Callout>