@nlxai/touchpoint-ui 1.2.4-alpha.1 → 1.2.4-alpha.5

package/docs/README.md

@@ -1,44 +1,682 @@
-# @nlxai/touchpoint-ui
+## Basics
 
-## Namespaces
+### create()
 
-- [Icons](modules/Icons.md)
+```ts
+function create(props): Promise<TouchpointInstance>;
+```
 
-## Interfaces
+Creates a new Touchpoint UI instance and appends it to the document body
+
+#### Parameters
+
+##### props
+
+[`TouchpointConfiguration`](#touchpointconfiguration)
+
+Configuration props for Touchpoint
+
+#### Returns
+
+`Promise`\<[`TouchpointInstance`](#touchpointinstance)\>
+
+A promise that resolves to a TouchpointInstance
+
+---
+
+### TouchpointConfiguration
+
+Main Touchpoint creation properties object
+
+#### Properties
+
+##### config
+
+```ts
+config: Config;
+```
+
+Connection information for the @nlxai/core conversation handler
+
+##### windowSize?
+
+```ts
+optional windowSize: "full" | "half";
+```
+
+Optional window size for the chat window, defaults to `half`
+
+##### colorMode?
+
+```ts
+optional colorMode: "dark" | "light" | "light dark";
+```
+
+Optional color mode for the chat window, defaults to `dark`. Setting `light dark` enables automatic switching based on system settings.
+
+##### brandIcon?
+
+```ts
+optional brandIcon: string;
+```
+
+URL of icon used to display the brand in the chat header
+
+##### animate?
+
+```ts
+optional animate: boolean;
+```
+
+Include border animation. Currently only supported in Voice Mini.
+
+##### launchIcon?
+
+```ts
+optional launchIcon:
+  | string
+  | boolean
+  |
+  | ComponentClass<{
+  className?: string;
+  onClick?: () => void;
+}, any>
+  | FunctionComponent<{
+  className?: string;
+  onClick?: () => void;
+}>;
+```
+
+URL of icon used on the launch icon in the bottom right when the experience is collapsed.
+
+When set to `false`, no launch button is shown at all. When not set or set to `true`, the default launch icon is rendered.
+
+##### userMessageBubble?
+
+```ts
+optional userMessageBubble: boolean;
+```
+
+Specifies whether the user message has bubbles or not
+
+##### agentMessageBubble?
+
+```ts
+optional agentMessageBubble: boolean;
+```
+
+Specifies whether the agent message has bubbles or not
+
+##### chatMode?
+
+```ts
+optional chatMode: boolean;
+```
+
+Enables chat mode, a classic chat experience with inline loaders and the chat history visible at all times.
+
+##### theme?
+
+```ts
+optional theme: Partial<Theme>;
+```
+
+Optional theme object to override default theme values
+
+##### modalityComponents?
+
+```ts
+optional modalityComponents: Record<string, CustomModalityComponent<unknown>>;
+```
+
+Optional [custom modality components](#custommodalitycomponent) to render in Touchpoint
+
+##### initializeConversation()?
+
+```ts
+optional initializeConversation: (handler, context?) => void;
+```
+
+Custom conversation init method. Defaults to sending the welcome flow.
+
+###### Parameters
+
+###### handler
+
+`ConversationHandler`
+
+the conversation handler.
+
+###### context?
+
+`Context`
+
+the context object
+
+###### Returns
+
+`void`
+
+##### input?
+
+```ts
+optional input: "text" | "voice" | "voiceMini";
+```
+
+Controls the ways in which the user can communicate with the application. Defaults to `"text"`
+
+##### initialContext?
+
+```ts
+optional initialContext: Context;
+```
+
+Context sent with the initial request.
+
+##### bidirectional?
+
+```ts
+optional bidirectional: BidirectionalConfig;
+```
+
+Enables bidirectional mode of voice+. Will automatically set the bidirectional flag in the config.
+
+---
+
+### TouchpointInstance
+
+Instance of a Touchpoint UI component
+
+#### Properties
+
+##### expanded
+
+```ts
+expanded: boolean;
+```
+
+Controls whether the Touchpoint UI is expanded or collapsed
+
+##### conversationHandler
+
+```ts
+conversationHandler: ConversationHandler;
+```
+
+The conversation handler instance for interacting with the application
+
+##### teardown()
+
+```ts
+teardown: () => void;
+```
+
+Method to remove the Touchpoint UI from the DOM
+
+###### Returns
+
+`void`
+
+##### setCustomBidirectionalCommands()
+
+```ts
+setCustomBidirectionalCommands: (commands) => void;
+```
+
+Sets currently available custom bidirectional commands.
+This allows you to define custom commands that can be used in the voice bot.
+The commands will be available in the voice bot and can be used to trigger actions.
+
+Example:
+
+```javascript
+client.setCustomBidirectionalCommands([
+  {
+    action: "Meal",
+    description: "add a meal to your flight",
+    schema: {
+      enum: ["standard", "vegetarian", "vegan", "gluten-free"],
+    },
+    handler: (value) => {
+      console.log("Meal option:", value);
+    },
+  },
+]);
+```
+
+This will allow the voice bot to use the command `Meal` with the value `standard`, `vegetarian`, `vegan`, or `gluten-free`.
+
+When using more complex arguments, a library such as [Zod](https://zod.dev) can be useful:
+
+```javascript
+import * as z from "zod/v4";
+
+const schema = z.object({
+  name: z.string().describe("The customer's name, such as John Doe"),
+  email: z.string().email().describe("The customer's email address"),
+});
+
+client.setCustomBidirectionalCommands([
+  {
+    action: "Meal",
+    description: "add a meal to your flight",
+    schema: z.toJSONSchema(schema, { io: "input" }),
+    handler: (value) => {
+      const result = z.safeParse(schema, value);
+      if (result.success) {
+        // result.data is now type safe and TypeScript can reason about it
+        console.log("Meal option:", result.data);
+      } else {
+        console.error("Failed to parse Meal option:", result.error);
+      }
+    },
+  },
+]);
+```
+
+###### Parameters
+
+###### commands
+
+[`BidirectionalCustomCommand`](#bidirectionalcustomcommand)[]
+
+A list containing the custom commands to set.
+
+###### Returns
+
+`void`
+
+## Theming
+
+### Theme
+
+The full theme expressed as CSS custom properties.
+This means that for instance colors can be made to switch automatically based on the system color mode by using the `light-dark()` CSS function.
+Note also that not all colors need to be provided manually. For instance if only `primary80` is provided, the rest of the primary colors will be computed automatically based on it.
+Therefore, for a fully custom but minimal theme, you only need to provide `accent`, `primary80`, `secondary80`, `background`, `overlay`, and potentially the warning and error colors.
+
+#### Example
+
+```typescript
+const theme: Partial<Theme> = {
+  primary80: "light-dark(rgba(0, 2, 9, 0.8), rgba(255, 255, 255, 0.8))",
+  secondary80: "light-dark(rgba(255, 255, 255, 0.8), rgba(0, 2, 9, 0.8))",
+  accent: "light-dark(rgb(28, 99, 218), rgb(174, 202, 255))",
+  background: "light-dark(rgba(220, 220, 220, 0.9), rgba(0, 2, 9, 0.9))",
+};
+```
+
+#### Properties
+
+##### fontFamily
+
+```ts
+fontFamily: string;
+```
+
+Font family
+
+##### primary80
+
+```ts
+primary80: string;
+```
+
+Primary color with 80% opacity
+
+##### primary60
+
+```ts
+primary60: string;
+```
+
+Primary color with 60% opacity
+
+##### primary40
+
+```ts
+primary40: string;
+```
+
+Primary color with 40% opacity
+
+##### primary20
+
+```ts
+primary20: string;
+```
+
+Primary color with 20% opacity
+
+##### primary10
+
+```ts
+primary10: string;
+```
+
+Primary color with 10% opacity
+
+##### primary5
+
+```ts
+primary5: string;
+```
+
+Primary color with 5% opacity
+
+##### primary1
+
+```ts
+primary1: string;
+```
+
+Primary color with 1% opacity
+
+##### secondary80
+
+```ts
+secondary80: string;
+```
+
+Secondary color with 80% opacity
+
+##### secondary60
+
+```ts
+secondary60: string;
+```
+
+Secondary color with 60% opacity
+
+##### secondary40
+
+```ts
+secondary40: string;
+```
+
+Secondary color with 40% opacity
+
+##### secondary20
+
+```ts
+secondary20: string;
+```
+
+Secondary color with 20% opacity
+
+##### secondary10
+
+```ts
+secondary10: string;
+```
+
+Secondary color with 10% opacity
+
+##### secondary5
+
+```ts
+secondary5: string;
+```
+
+Secondary color with 5% opacity
+
+##### secondary1
+
+```ts
+secondary1: string;
+```
+
+Secondary color with 1% opacity
+
+##### accent
+
+```ts
+accent: string;
+```
+
+Accent color used e.g. for prominent buttons, the loader animation as well as selected card outlines
+
+##### accent20
+
+```ts
+accent20: string;
+```
+
+Accent color with 20% opacity
+
+##### background
+
+```ts
+background: string;
+```
+
+The background color of the main Touchpoint interface
+
+##### overlay
+
+```ts
+overlay: string;
+```
+
+The color of the overlay covering the visible portion of the website when the Touchpoint interface does not cover the full screen
+
+##### warningPrimary
+
+```ts
+warningPrimary: string;
+```
+
+Primary warning color
+
+##### warningSecondary
+
+```ts
+warningSecondary: string;
+```
+
+Secondary warning color
+
+##### errorPrimary
 
-- [InteractiveElementInfo](interfaces/InteractiveElementInfo.md)
-- [PageForms](interfaces/PageForms.md)
-- [CustomCardProps](interfaces/CustomCardProps.md)
-- [CustomCardRowProps](interfaces/CustomCardRowProps.md)
-- [DateInputProps](interfaces/DateInputProps.md)
-- [IconButtonProps](interfaces/IconButtonProps.md)
-- [TextButtonProps](interfaces/TextButtonProps.md)
-- [ChoiceMessage](interfaces/ChoiceMessage.md)
-- [Theme](interfaces/Theme.md)
-- [InputField](interfaces/InputField.md)
-- [PageState](interfaces/PageState.md)
-- [BidirectionalContext](interfaces/BidirectionalContext.md)
-- [TouchpointConfiguration](interfaces/TouchpointConfiguration.md)
-- [BidirectionalCustomCommand](interfaces/BidirectionalCustomCommand.md)
-- [TouchpointInstance](interfaces/TouchpointInstance.md)
+```ts
+errorPrimary: string;
+```
 
-## Type Aliases
+Primary error color
 
-### AccessibilityInformation
+##### errorSecondary
 
-Ƭ **AccessibilityInformation**: `Record`\<`string`, `any`\>
+```ts
+errorSecondary: string;
+```
 
-Accessibility information
+Secondary error color
 
-#### Defined in
+##### innerBorderRadius
 
-[packages/touchpoint-ui/src/bidirectional/analyzePageForms.ts:9](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/bidirectional/analyzePageForms.ts#L9)
+```ts
+innerBorderRadius: string;
+```
 
-___
+Inner border radius: used for most buttons
+
+##### outerBorderRadius
+
+```ts
+outerBorderRadius: string;
+```
+
+Outer border radius: generally used for elements that contain buttons that have inner border radius. Also used by the launch button.
+
+## Modality components
+
+### Ripple
+
+```ts
+const Ripple: FC<{
+  className?: string;
+  style?: CSSProperties;
+}>;
+```
+
+A ripple effect composed of expanding circles.
+
+---
+
+### Carousel
+
+```ts
+const Carousel: FC<{
+  className?: string;
+  children?: ReactNode;
+}>;
+```
+
+Renders a carousel of cards.
+
+#### Example
+
+```tsx
+import {
+  Carousel,
+  CustomCard,
+  CustomCardImageRow,
+  React,
+} from "@nlx/touchpoint-ui";
+
+const MyCarousel = ({ data }) => (
+  <Carousel>
+    {data.map((item) => (
+      <CustomCard key={item.id}>
+        <CustomCardImageRow src={item.image} alt={item.description} />
+      </CustomCard>
+    ))}
+  </Carousel>
+);
+```
+
+---
+
+### CustomCard
+
+```ts
+const CustomCard: FC<{
+  className?: string;
+  children: ReactNode;
+  selected?: boolean;
+  onClick?: () => void;
+  href?: string;
+  newTab?: boolean;
+}>;
+```
+
+A customizable card component that can function as a button or link.
+
+#### Example
+
+```tsx
+import {
+  CustomCard,
+  CustomCardImageRow,
+  CustomCardRow,
+  React,
+} from "@nlx/touchpoint-ui";
+
+const MyCard = ({ data }) => (
+  <CustomCard selected={data.active} onClick={() => alert("Card clicked!")}>
+    <CustomCardImageRow
+      src="https://example.com/image.jpg"
+      alt="Example Image"
+    />
+    <CustomCardRow
+      left={<div>Left Content</div>}
+      right={<div>Right Content</div>}
+      icon={MyIcon}
+    />
+  </CustomCard>
+);
+```
+
+---
+
+### CustomCardImageRow
+
+```ts
+const CustomCardImageRow: FC<{
+  src: string;
+  alt?: string;
+}>;
+```
+
+A row within a CustomCard that displays an image.
+
+---
+
+### CustomCardRow
+
+```ts
+const CustomCardRow: FC<{
+  left: ReactNode;
+  right: ReactNode;
+  icon?: Icon;
+  className?: string;
+}>;
+```
+
+A row within a CustomCard that displays left and right content, with an optional centered icon.
+
+#### Example
+
+```tsx
+import { CustomCardRow, Icons, BaseText, React } from "@nlx/touchpoint-ui";
+
+const MyCardRow = () => (
+  <CustomCardRow
+    left={<BaseText>Left Content</BaseText>}
+    right={<BaseText>Right Content</BaseText>}
+    icon={Icons.ArrowRight}
+  />
+);
+```
+
+---
+
+### DateInput
+
+```ts
+const DateInput: FC<{
+  onSubmit?: (date) => void;
+  className?: string;
+}>;
+```
+
+A date input
+
+#### Example
+
+```tsx
+import { DateInput, React } from "@nlx/touchpoint-ui";
+
+const MyDateInput = ({ conversationHandler }) => (
+  <DateInput
+    onSubmit={(date) => conversationHandler.sendContext({ myDate: date })}
+  />
+);
+```
+
+---
 
 ### IconButtonType
 
-Ƭ **IconButtonType**: ``"main"`` \| ``"ghost"`` \| ``"activated"`` \| ``"coverup"`` \| ``"error"`` \| ``"overlay"``
+```ts
+type IconButtonType =
+  | "main"
+  | "ghost"
+  | "activated"
+  | "coverup"
+  | "error"
+  | "overlay";
+```
 
 Represents the different types of icon buttons available in the application.
 
@@ -48,432 +686,669 @@ Represents the different types of icon buttons available in the application.
 - `coverup`: An icon button used to cover up or mask something.
 - `overlay`: An icon button that appears over other content.
 
-#### Defined in
+---
 
-[packages/touchpoint-ui/src/components/ui/IconButton.tsx:16](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/IconButton.tsx#L16)
+### IconButton
 
-___
+```ts
+const IconButton: FC<{
+  onClick?: MouseEventHandler<HTMLButtonElement>;
+  label: string;
+  className?: string;
+  type: IconButtonType;
+  Icon: FC<IconProps>;
+}>;
+```
 
-### WindowSize
+A button showing only an icon (textual label is provided for accessibility)
 
-Ƭ **WindowSize**: ``"half"`` \| ``"full"``
+#### Example
 
-Window size configuration
+```tsx
+import { IconButton, Icons, React } from "@nlx/touchpoint-ui";
 
-#### Defined in
+const MyIconButton = () => (
+  <IconButton
+    label="Send message"
+    onClick={() => alert("Icon button clicked!")}
+    type="main"
+    Icon={Icons.ArrowForward}
+  />
+);
+```
 
-[packages/touchpoint-ui/src/interface.ts:13](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/interface.ts#L13)
+---
 
-___
+### TextButton
 
-### ColorMode
+```ts
+const TextButton: FC<{
+  onClick?: () => void;
+  label: string;
+  className?: string;
+  type?: "main" | "ghost";
+  Icon: FC<IconProps>;
+}>;
+```
 
-Ƭ **ColorMode**: ``"light"`` \| ``"dark"``
+A button with a visible textual label
 
-Color mode configuration (light/dark modes)
+#### Example
 
-#### Defined in
+```tsx
+import { TextButton, ArrowForward, React } from "@nlx/touchpoint-ui";
 
-[packages/touchpoint-ui/src/interface.ts:18](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/interface.ts#L18)
+const MyTextButton = ({ onClickHandler }) => (
+  <TextButton onClick={onClickHandler} label="Continue" />
+);
+```
 
-___
+---
 
-### CustomModalityComponent
+### BaseText
 
-Ƭ **CustomModalityComponent**\<`Data`\>: `ComponentType`\<\{ `data`: `Data` ; `conversationHandler`: `ConversationHandler` ; `enabled`: `boolean` ; `className?`: `string`  }\>
+```ts
+const BaseText: FC<{
+  children: ReactNode;
+  faded?: boolean;
+  className?: string;
+}>;
+```
 
-Custom Modalities allow rendering of rich components from nodes.
-See: https://docs.studio.nlx.ai/build/resources/modalities
+Standard text component with base typography styles applied.
 
-#### Type parameters
+#### Example
 
-| Name |
-| :------ |
-| `Data` |
+```tsx
+import { BaseText, React } from "@nlx/touchpoint-ui";
 
-#### Defined in
+const MyText = () => <BaseText faded>This is some standard text.</BaseText>;
+```
 
-[packages/touchpoint-ui/src/interface.ts:42](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/interface.ts#L42)
+---
 
-___
+### SmallText
 
-### InitializeConversation
+```ts
+const SmallText: FC<{
+  children: ReactNode;
+  className?: string;
+}>;
+```
 
-Ƭ **InitializeConversation**: (`handler`: `ConversationHandler`, `context?`: `Context`) => `void`
+Small text component with smaller typography styles applied.
 
-Custom conversation init method. Defaults to sending the welcome intent
+---
 
-#### Type declaration
+### html()
 
-▸ (`handler`, `context?`): `void`
+```ts
+const html: (strings, ...values) => unknown;
+```
 
-##### Parameters
+A tagged literal for creating reactive elements for custom modalities.
+It already knows about all Touchpoint UI components, so you can use them directly without the need to import them.
+Also very useful when using Touchpoint directly from CDN or in projects without a build step.
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `handler` | `ConversationHandler` | the conversation handler. |
-| `context?` | `Context` | context set via TouchpointConfiguration.initialContext |
+#### Parameters
 
-##### Returns
+##### strings
 
-`void`
+`TemplateStringsArray`
 
-#### Defined in
+##### values
 
-[packages/touchpoint-ui/src/interface.ts:180](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/interface.ts#L180)
+...`any`[]
 
-___
+#### Returns
 
-### CustomLaunchButton
+`unknown`
 
-Ƭ **CustomLaunchButton**: `ComponentType`\<\{ `className?`: `string` ; `onClick?`: () => `void`  }\>
+#### Example
+
+```ts
+import { html, Icons } from "@nlx/touchpoint-ui";
+
+const MyCustomModality = ({ data, conversationHandler }) =>
+  html`<div style="display: flex; gap: 8px;">
+    <IconButton
+      label="Cancel"
+      Icon=${Icons.Close}
+      type="ghost"
+      onClick=${cancel()}
+    />
+    <TextButton
+      label="Submit"
+      Icon=${Icons.ArrowForward}
+      type="main"
+      onClick=${() => conversationHandler.sendText("Button clicked!")}
+    />
+  </div>`;
+```
+
+---
 
-Fully custom launch icon
+### CustomModalityComponent
 
-#### Defined in
+```ts
+type CustomModalityComponent<Data> = ComponentType<{
+  data: Data;
+  conversationHandler: ConversationHandler;
+  className?: string;
+  renderedAsOverlay?: boolean;
+}>;
+```
 
-[packages/touchpoint-ui/src/interface.ts:188](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/interface.ts#L188)
+Custom Modalities allow rendering of rich user interfaces directly inside a conversation.
+A custom modality component is a React component. It will receive the modality data as a
+`data` prop, along with the conversation handler instance to interact with the conversation as
+`conversationHandler` prop.
 
-___
+#### Type Parameters
 
-### Input
+##### Data
 
-Ƭ **Input**: ``"text"`` \| ``"voice"`` \| ``"voiceMini"``
+`Data`
 
-Input type for the experience
+The type of the modality being rendered by this component.
 
-#### Defined in
+## Bidirectional Voice+
 
-[packages/touchpoint-ui/src/interface.ts:202](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/interface.ts#L202)
+### InteractiveElementInfo
 
-___
+Accessibility information with ID
 
-### BidirectionalConfig
+#### Indexable
 
-Ƭ **BidirectionalConfig**: \{ `automaticContext?`: ``true`` ; `navigation?`: (`action`: ``"page_next"`` \| ``"page_previous"`` \| ``"page_custom"`` \| ``"page_unknown"``, `destination`: `string` \| `undefined`, `destinations`: `Record`\<`string`, `string`\>) => `void` ; `input?`: (`fields`: [`InputField`](interfaces/InputField.md)[], `pageFields`: `Record`\<`string`, `Element`\>) => `void` ; `custom?`: (`action`: `string`, `payload`: `unknown`) => `void` ; `customizeAutomaticContext?`: (`arg`: \{ `context`: [`BidirectionalContext`](interfaces/BidirectionalContext.md) ; `state`: [`PageState`](interfaces/PageState.md)  }) => \{ `context`: [`BidirectionalContext`](interfaces/BidirectionalContext.md) ; `state`: [`PageState`](interfaces/PageState.md)  }  } \| \{ `automaticContext`: ``false`` ; `navigation?`: (`action`: ``"page_next"`` \| ``"page_previous"`` \| ``"page_custom"`` \| ``"page_unknown"``, `destination?`: `string`) => `void` ; `input?`: (`fields`: [`InputField`](interfaces/InputField.md)[]) => `void` ; `custom?`: (`action`: `string`, `payload`: `unknown`) => `void`  }
+```ts
+[key: string]: any
+```
 
-Configuration for bidirectional mode of voice+.
+#### Properties
 
-#### Defined in
+##### id
 
-[packages/touchpoint-ui/src/interface.ts:256](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/interface.ts#L256)
+```ts
+id: string;
+```
 
-## Variables
+Form element ID (assigned by the analysis logic, not necessarily equal to the DOM ID)
 
-### version
+---
 
-• `Const` **version**: `string` = `packageJson.version`
+### PageForms
 
-Package version
+Page forms with elements
 
-#### Defined in
+#### Properties
 
-[packages/touchpoint-ui/src/index.tsx:52](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/index.tsx#L52)
+##### context
 
-## Functions
+```ts
+context: InteractiveElementInfo[];
+```
 
-### analyzePageForms
+Page context
 
-▸ **analyzePageForms**(): [`PageForms`](interfaces/PageForms.md)
+##### formElements
+
+```ts
+formElements: Record<string, Element>;
+```
+
+Form element references
+
+---
+
+### analyzePageForms()
+
+```ts
+function analyzePageForms(): PageForms;
+```
 
 Analyze page forms
 
 #### Returns
 
-[`PageForms`](interfaces/PageForms.md)
+[`PageForms`](#pageforms)
 
-pageForms
+Context and state about all the form elements detected on the page using accessibility APIs.
 
-#### Defined in
+---
 
-[packages/touchpoint-ui/src/bidirectional/analyzePageForms.ts:89](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/bidirectional/analyzePageForms.ts#L89)
+### PageState
 
-___
+Internal state that the automatic context maintains.
 
-### Ripple
+#### Properties
 
-▸ **Ripple**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+##### formElements
 
-#### Parameters
+```ts
+formElements: Record<string, Element>;
+```
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | `Object` | - |
-| `props.className?` | `string` | - |
-| `props.style?` | `CSSProperties` | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+Mapping from form element IDs to their DOM elements
 
-#### Returns
+##### links
 
-`ReactNode`
+```ts
+links: Record<string, string>;
+```
 
-#### Defined in
+Mapping from link element names to their URLs
 
-[packages/touchpoint-ui/src/components/Ripple.tsx:24](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/Ripple.tsx#L24)
+##### customCommands
 
-___
+```ts
+customCommands: Map<string, (arg) => void>;
+```
 
-### Carousel
+Mapping from custom commands to their handlers
 
-▸ **Carousel**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+---
 
-#### Parameters
+### BidirectionalContext
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | `Object` | - |
-| `props.className?` | `string` | - |
-| `props.children?` | `ReactNode` | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+Bidirectional context information that is sent to the LLM.
 
-#### Returns
+#### Properties
 
-`ReactNode`
+##### uri?
 
-#### Defined in
+```ts
+optional uri: string;
+```
 
-[packages/touchpoint-ui/src/components/ui/Carousel.tsx:17](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/Carousel.tsx#L17)
+Identifier for which page you are currently on. This can be used to filter the relevant KB pages.
 
-___
+##### fields?
 
-### CustomCard
+```ts
+optional fields: InteractiveElementInfo[];
+```
 
-▸ **CustomCard**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+The active form fields that can be filled in.
 
-#### Parameters
+##### destinations?
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | [`CustomCardProps`](interfaces/CustomCardProps.md) | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+```ts
+optional destinations: string[];
+```
 
-#### Returns
+Human readable location names that can be navigated to.
 
-`ReactNode`
+##### actions?
 
-#### Defined in
+```ts
+optional actions: object[];
+```
 
-[packages/touchpoint-ui/src/components/ui/CustomCard.tsx:38](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/CustomCard.tsx#L38)
+Custom actions that can be performed.
 
-___
+###### action
 
-### CustomCardImageRow
+```ts
+action: string;
+```
 
-▸ **CustomCardImageRow**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+The name of the command, used to invoke it.
 
-#### Parameters
+###### description?
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | `Object` | - |
-| `props.src` | `string` | - |
-| `props.alt?` | `string` | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+```ts
+optional description: string;
+```
 
-#### Returns
+A short description of the command
 
-`ReactNode`
+###### schema?
 
-#### Defined in
+```ts
+optional schema: any;
+```
 
-[packages/touchpoint-ui/src/components/ui/CustomCard.tsx:96](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/CustomCard.tsx#L96)
+A schema for validating the command's input. Should follow the JSON Schema specification.
 
-___
+---
 
-### CustomCardRow
+### BidirectionalConfig
 
-▸ **CustomCardRow**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+```ts
+type BidirectionalConfig =
+  | {
+      automaticContext?: true;
+      navigation?: (action, destination, destinations) => void;
+      input?: (fields, pageFields) => void;
+      custom?: (action, payload) => void;
+      customizeAutomaticContext?: (arg) => object;
+    }
+  | {
+      automaticContext: false;
+      navigation?: (action, destination?) => void;
+      input?: (fields) => void;
+      custom?: (action, payload) => void;
+    };
+```
 
-#### Parameters
+Configuration for bidirectional mode of voice+.
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | [`CustomCardRowProps`](interfaces/CustomCardRowProps.md) | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+#### Type Declaration
 
-#### Returns
+```ts
+{
+  automaticContext?: true;
+  navigation?: (action, destination, destinations) => void;
+  input?: (fields, pageFields) => void;
+  custom?: (action, payload) => void;
+  customizeAutomaticContext?: (arg) => object;
+}
+```
 
-`ReactNode`
+##### automaticContext?
 
-#### Defined in
+```ts
+optional automaticContext: true;
+```
 
-[packages/touchpoint-ui/src/components/ui/CustomCard.tsx:121](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/CustomCard.tsx#L121)
+Attempt to gather and send page context automatically. This will work well on semantically coded pages without too many custom form controls.
+This enables a number of automatic features.
 
-___
+Defaults to `true`.
 
-### DateInput
+##### navigation()?
 
-▸ **DateInput**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+```ts
+optional navigation: (action, destination, destinations) => void;
+```
 
-#### Parameters
+Navigation handler for bidirectional mode.
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | [`DateInputProps`](interfaces/DateInputProps.md) | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+The default implementation will navigate to those pages using standard `window.location` APIs.
 
-#### Returns
+###### Parameters
 
-`ReactNode`
+###### action
 
-#### Defined in
+The navigation action to perform.
 
-[packages/touchpoint-ui/src/components/ui/DateInput.tsx:29](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/DateInput.tsx#L29)
+`"page_next"` | `"page_previous"` | `"page_custom"` | `"page_unknown"`
 
-___
+###### destination
 
-### IconButton
+The name of the destination to navigate to if `action` is `"page_custom"`.
 
-▸ **IconButton**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+`string` | `undefined`
 
-#### Parameters
+###### destinations
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | [`IconButtonProps`](interfaces/IconButtonProps.md) | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+`Record`\<`string`, `string`\>
 
-#### Returns
+A map of destination names to URLs for custom navigation.
 
-`ReactNode`
+###### Returns
 
-#### Defined in
+`void`
 
-[packages/touchpoint-ui/src/components/ui/IconButton.tsx:94](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/IconButton.tsx#L94)
+##### input()?
 
-___
+```ts
+optional input: (fields, pageFields) => void;
+```
 
-### TextButton
+A callback for filling out form fields in bidirectional mode.
 
-▸ **TextButton**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+The default implementation will fill out the form fields using standard DOM APIs.
 
-#### Parameters
+###### Parameters
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | [`TextButtonProps`](interfaces/TextButtonProps.md) | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+###### fields
 
-#### Returns
+`object`[]
 
-`ReactNode`
+An array of field objects with `id` and `value` properties.
 
-#### Defined in
+###### pageFields
 
-[packages/touchpoint-ui/src/components/ui/TextButton.tsx:33](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/TextButton.tsx#L33)
+`Record`\<`string`, `Element`\>
 
-___
+A map of field IDs to DOM elements for custom form filling.
 
-### BaseText
+###### Returns
 
-▸ **BaseText**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+`void`
 
-#### Parameters
+##### ~~custom()?~~
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | `Object` | - |
-| `props.children` | `ReactNode` | - |
-| `props.faded?` | `boolean` | - |
-| `props.className?` | `string` | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+```ts
+optional custom: (action, payload) => void;
+```
 
-#### Returns
+A callback for custom actions in bidirectional mode.
 
-`ReactNode`
+###### Parameters
 
-#### Defined in
+###### action
 
-[packages/touchpoint-ui/src/components/ui/Typography.tsx:5](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/Typography.tsx#L5)
+`string`
 
-___
+The custom name of your action.
 
-### SmallText
+###### payload
 
-▸ **SmallText**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+`unknown`
 
-#### Parameters
+The payload defined for the custom action.
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | `Object` | - |
-| `props.children` | `ReactNode` | - |
-| `props.className?` | `string` | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+###### Returns
 
-#### Returns
+`void`
 
-`ReactNode`
+###### Deprecated
 
-#### Defined in
+Use [TouchpointInstance.setCustomBidirectionalCommands](#setcustombidirectionalcommands) instead.
 
-[packages/touchpoint-ui/src/components/ui/Typography.tsx:21](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/components/ui/Typography.tsx#L21)
+##### customizeAutomaticContext()?
 
-___
+```ts
+optional customizeAutomaticContext: (arg) => object;
+```
 
-### html
+A callback for customizing the automatic context gathering.
 
-▸ **html**(`strings`, `...values`): `unknown`
+This allows you to modify the context and state before they are sent to the LLM.
 
-#### Parameters
+###### Parameters
 
-| Name | Type |
-| :------ | :------ |
-| `strings` | `TemplateStringsArray` |
-| `...values` | `any`[] |
+###### arg
 
-#### Returns
+###### context
+
+[`BidirectionalContext`](#bidirectionalcontext)
+
+###### state
+
+[`PageState`](#pagestate)
+
+###### Returns
+
+The modified context and state. If the state is identical to the previous state, the call to the server will be skipped.
+
+###### context
+
+```ts
+context: BidirectionalContext;
+```
+
+The current context being sent to the LLM
+
+###### state
+
+```ts
+state: PageState;
+```
+
+The current state of the page - this is stuff not sent to the LLM, but needed to connect the results back to actions to take on the page.
+
+```ts
+{
+  automaticContext: false;
+  navigation?: (action, destination?) => void;
+  input?: (fields) => void;
+  custom?: (action, payload) => void;
+}
+```
+
+##### automaticContext
+
+```ts
+automaticContext: false;
+```
+
+Disable gathering page context automatically.
+
+##### navigation()?
+
+```ts
+optional navigation: (action, destination?) => void;
+```
+
+Navigation handler for bidirectional mode. Without automatic context there is no default implementation.
+
+###### Parameters
+
+###### action
+
+The navigation action to perform.
+
+`"page_next"` | `"page_previous"` | `"page_custom"` | `"page_unknown"`
+
+###### destination?
+
+`string`
+
+The name of the destination to navigate to if `action` is `"page_custom"`.
+
+###### Returns
+
+`void`
+
+##### input()?
+
+```ts
+optional input: (fields) => void;
+```
+
+A callback for filling out form fields in bidirectional mode. Without automatic context there is no default implementation.
+
+###### Parameters
+
+###### fields
+
+`object`[]
+
+An array of field objects with `id` and `value` properties.
+
+###### Returns
+
+`void`
+
+##### custom()?
+
+```ts
+optional custom: (action, payload) => void;
+```
+
+A callback for custom actions in bidirectional mode.
+
+###### Parameters
+
+###### action
+
+`string`
+
+The custom name of your action.
+
+###### payload
 
 `unknown`
 
-#### Defined in
+The payload defined for the custom action.
+
+###### Returns
 
-[packages/touchpoint-ui/src/index.tsx:61](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/index.tsx#L61)
+`void`
 
-___
+---
 
-### create
+### BidirectionalCustomCommand
 
-▸ **create**(`props`): `Promise`\<[`TouchpointInstance`](interfaces/TouchpointInstance.md)\>
+During a Voice+ bidirectional conversation, you can indicate to the application the availability of
+custom commands that the user can invoke.
 
-Creates a new Touchpoint UI instance and appends it to the document body
+#### Properties
 
-#### Parameters
+##### action
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | [`TouchpointConfiguration`](interfaces/TouchpointConfiguration.md) | Configuration props for Touchpoint |
+```ts
+action: string;
+```
 
-#### Returns
+The name of the command, used to invoke it. Should be unique and descriptive in the context of the LLM.
 
-`Promise`\<[`TouchpointInstance`](interfaces/TouchpointInstance.md)\>
+##### description?
 
-A promise that resolves to a TouchpointInstance
+```ts
+optional description: string;
+```
 
-#### Defined in
+A short description of the command, used to help the LLM understand its purpose.
 
-[packages/touchpoint-ui/src/index.tsx:342](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/index.tsx#L342)
+If omitted, then the command will not be sent to the application and must be triggered
+from the application side.
 
-___
+##### schema?
 
-### PreviewContainer
+```ts
+optional schema: any;
+```
 
-▸ **PreviewContainer**(`props`, `deprecatedLegacyContext?`): `ReactNode`
+A JSON Schema that defines the structure of the command's input.
 
-#### Parameters
+Use descriptive names and `description` fields to give the underlying LLM plenty of context for
+it to generate reasonable parameters. Note that the LLM output will be validated (and transformed)
+with this schema, so you are guaranteed type safe inputs to your handler.
 
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `props` | `Object` | - |
-| `props.children` | `ReactNode` | - |
-| `props.mode` | [`ColorMode`](README.md#colormode) | - |
-| `props.theme` | `Partial`\<[`Theme`](interfaces/Theme.md)\> | - |
-| `deprecatedLegacyContext?` | `any` | **`Deprecated`** **`See`** [React Docs](https://legacy.reactjs.org/docs/legacy-context.html#referencing-context-in-lifecycle-methods) |
+Should follow the JSONSchema specification.
 
-#### Returns
+##### handler()
+
+```ts
+handler: (value) => void;
+```
+
+A handler that will be called with an argument matching the schema when the command is invoked.
+
+###### Parameters
 
-`ReactNode`
+###### value
 
-#### Defined in
+`any`
 
-[packages/touchpoint-ui/src/preview.tsx:10](https://github.com/nlxai/sdk/blob/e13e2baae9abf0ee3add35f3a4b4c3fe47e8f43d/packages/touchpoint-ui/src/preview.tsx#L10)
+###### Returns
+
+`void`
+
+## Other
+
+- [Icons](@nlxai/namespaces/Icons.md)
+
+## Utilities
+
+### version
+
+```ts
+const version: string = packageJson.version;
+```
+
+Package version