StatefulIntentCreator

Read more about the differences between Stateful and Stateless APIs in the UI2 API Overview.

Recall that the StatefulIntentCreator is not meant to be used directly, but is actually wrapped by the React useUI2 hook. Thus, this reference is for people wishing to build other React integrations, to use as inspiration for other UI2 extensions, or to better understand how UI2 works.

What's different from the Stateless API?

The StatefulIntentCreator has a few critical differences from the standard stateless IntentCreator that you should know about:

• Storing State: Obviously, the Stateful API stores state about certain things:
  • The content of the UI2 input
  • What intents are "active" or currently identified
  • The loading state of the AI
  • All the promises and async processing
• Submission: With State, UI2 can also handle Submitting, or "Confirming" intents, adding a whole new step to the lifecycle: onSubmit
• Input Debouncing: Finally, the other main difference is input debouncing, which allows UI2 to automatically identifyIntent as you are entering input

This Stateful API is mainly used to be mounted on React, but it also serves as an example for other extensions of UI2 (i.e. built for other frameworks, or other types of UIs).

The following documentation will only go over the differences from the initial API. It will not cover all properties available on the StatefulIntentCreator. Read documentation for the IntentCreator for more information.

What is the UI2 Input?

The UI2 input is the main way that a user is meant to communicate with the UI2 application. This currently is through text input.

This text input is able to trigger intent identification, submission, and more.

Constructor

The constructor similarly takes a Configuration object with the following information:

However, it also takes a few extra properties in this order after the configuration:

• inputValue and setInputValue: Setter and getter for the state of the UI2 input (string)
• isLoading and setIsLoading: Setter and getter for the state of the loading indicator (boolean)

The React hook takes care of creating and providing these states.

debounceDelay

This is how long, in milliseconds, the app should wait before identifying intent on the user's text. The timeout is reset when the user starts typing again.

This number should be carefully tailored to ensure balance:

• If it's too short, you could use too many tokens and requests to the AI server
• If it's too long, UI2 will feel less natural

Note that this is slightly different from standard debounce timings, because the debounce delay does not take into account the processing time of the AI. In other words, the "preceived" debounce delay can be longer than the actual debounce delay.

Because of this, if you use a faster model, even a longer debounce delay could feel natural.

onSubmitStart and onSubmitEnd

These event listeners help manage submission.

Note that submission is not instantaneous, and thus two event listeners are needed.

The delay in submission is due to the fact that there is a period of time where possibly, your intent is still being detected or a completely new intent detection is started.

• onSubmitStart is called immediately when submission begins
• onSubmitEnd is called when all processing has been finished

Furthermore, the input box content is stored, so you do not have to worry about data loss when clearing the input.

Methods

There are a few new methods on StatefulIntentCreator and also a few methods with updates.

handleInputChange

This event listener of course updates the input value.

However, it also does a few other things in the Stateful API to manage asynchronous handling including cache validation and more for submitting.

handleSubmit

The issue with intent detection is that both detecting and submitting your intents should feel fast and snappy.

This is why handleSubmit has a few features to ensure that experience:

• When there is no identification going on (i.e. during debounce), a completely new request is triggered and then submit
• When there is identification going on already, St atefulIntentCreator will wait for that to complete and then submit
• Finally, and possibly most commonly, if an identification has already completed, no new identification will start, and it will directly submit.

Note that handleSubmit uses various checks to ensure the cache is up-to-date and it is submitting the right thing. In the case that it is unsure, a new identification is always started to be safe.

addIntent

The only thing new in addIntent is the addition of a onSubmit event handler, which you can pass in alongside onIntent and onCleanup.

onSubmit is called whenever an intent is currently identified, and it is submitted.

There are a few important things about submission:

1. There is no cleanup: Cleanup is not called when submitting
2. Operate on your preview: Due to that, you should use a simple operation to "confirm" your preview instead of adding new elements to state or otherwise.