@nlxai/touchpoint-ui 1.2.3-alpha.2 → 1.2.4-alpha.1

package/lib/interface.d.ts

@@ -3,14 +3,17 @@ import { ComponentType } from 'react';
 import { InteractiveElementInfo } from './bidirectional/analyzePageForms';
 /**
  * Window size configuration
+ * @inline @hidden
  */
 export type WindowSize = "half" | "full";
 /**
  * Color mode configuration (light/dark modes)
+ * @inline @hidden
  */
-export type ColorMode = "light" | "dark";
+export type ColorMode = "light" | "dark" | "light dark";
 /**
  * Choice message with metadata
+ * @internal
  */
 export interface ChoiceMessage {
     /**
@@ -27,8 +30,12 @@ export interface ChoiceMessage {
     messageIndex: number;
 }
 /**
- * Custom Modalities allow rendering of rich components from nodes.
- * See: https://docs.studio.nlx.ai/build/resources/modalities
+ * 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.
+ * @category Modality components
+ * @typeParam Data - The type of the modality being rendered by this component.
  */
 export type CustomModalityComponent<Data> = ComponentType<{
     /**
@@ -49,120 +56,22 @@ export type CustomModalityComponent<Data> = ComponentType<{
      * Class name to propagate to the container
      */
     className?: string;
-}>;
-/**
- * The full theme expressed as CSS custom properties
- */
-export interface Theme {
-    /**
-     * Font family
-     */
-    fontFamily: string;
-    /**
-     * Primary color with 80% opacity
-     */
-    primary80: string;
-    /**
-     * Primary color with 60% opacity
-     */
-    primary60: string;
-    /**
-     * Primary color with 40% opacity
-     */
-    primary40: string;
-    /**
-     * Primary color with 20% opacity
-     */
-    primary20: string;
     /**
-     * Primary color with 10% opacity
+     * Tells the component whether it is rendered as an overlay over other elements. In this case, the class `backdrop-blur-overlay` is required
+     * on transparent elements in order to make sure its contents remain visible.
      */
-    primary10: string;
-    /**
-     * Primary color with 5% opacity
-     */
-    primary5: string;
-    /**
-     * Primary color with 1% opacity
-     */
-    primary1: string;
-    /**
-     * Secondary color with 80% opacity
-     */
-    secondary80: string;
-    /**
-     * Secondary color with 60% opacity
-     */
-    secondary60: string;
-    /**
-     * Secondary color with 40% opacity
-     */
-    secondary40: string;
-    /**
-     * Secondary color with 20% opacity
-     */
-    secondary20: string;
-    /**
-     * Secondary color with 10% opacity
-     */
-    secondary10: string;
-    /**
-     * Secondary color with 5% opacity
-     */
-    secondary5: string;
-    /**
-     * Secondary color with 1% opacity
-     */
-    secondary1: string;
-    /**
-     * Accent color used e.g. for prominent buttons, the loader animation as well as selected card outlines
-     */
-    accent: string;
-    /**
-     * Accent color with 20% opacity
-     */
-    accent20: string;
-    /**
-     * The background color of the main Touchpoint interface
-     */
-    background: string;
-    /**
-     * The color of the overlay covering the visible portion of the website when the Touchpoint interface does not cover the full screen
-     */
-    overlay: string;
-    /**
-     * Primary warning color
-     */
-    warningPrimary: string;
-    /**
-     * Secondary warning color
-     */
-    warningSecondary: string;
-    /**
-     * Primary error color
-     */
-    errorPrimary: string;
-    /**
-     * Secondary error color
-     */
-    errorSecondary: string;
-    /**
-     * Inner border radius: used for most buttons
-     */
-    innerBorderRadius: string;
-    /**
-     * Outer border radius: generally used for elements that contain buttons that have inner border radius. Also used by the launch button.
-     */
-    outerBorderRadius: string;
-}
+    renderedAsOverlay?: boolean;
+}>;
 /**
  * Custom conversation init method. Defaults to sending the welcome intent
  * @param handler - the conversation handler.
  * @param context - context set via TouchpointConfiguration.initialContext
+ * @inline @hidden
  */
 export type InitializeConversation = (handler: ConversationHandler, context?: Context) => void;
 /**
  * Fully custom launch icon
+ * @inline @hidden
  */
 export type CustomLaunchButton = ComponentType<{
     /**
@@ -176,10 +85,12 @@ export type CustomLaunchButton = ComponentType<{
 }>;
 /**
  * Input type for the experience
+ * @inline @hidden
  */
 export type Input = "text" | "voice" | "voiceMini";
 /**
  * Input field value
+ * @inline @hidden
  */
 export interface InputField {
     /**
@@ -193,6 +104,7 @@ export interface InputField {
 }
 /**
  * Internal state that the automatic context maintains.
+ * @category Bidirectional Voice+
  */
 export interface PageState {
     /** Mapping from form element IDs to their DOM elements */
@@ -204,6 +116,7 @@ export interface PageState {
 }
 /**
  * Bidirectional context information that is sent to the LLM.
+ * @category Bidirectional Voice+
  */
 export interface BidirectionalContext {
     /** Identifier for which page you are currently on. This can be used to filter the relevant KB pages. */
@@ -226,6 +139,7 @@ export interface BidirectionalContext {
 }
 /**
  * Configuration for bidirectional mode of voice+.
+ * @category Bidirectional Voice+
  */
 export type BidirectionalConfig = {
     /**
@@ -238,18 +152,18 @@ export type BidirectionalConfig = {
     /**
      * Navigation handler for bidirectional mode.
      *
-     * If automatic context gathering is enabled, the default implementation will navigate to those pages using standard `window.location` APIs.
+     * The default implementation will navigate to those pages using standard `window.location` APIs.
      * @param action - The navigation action to perform.
      * @param destination - The name of the destination to navigate to if `action` is `"page_custom"`.
-     * @param destinations - A map of destination names to URLs for custom navigation. Only present if `automaticContext` is enabled.
+     * @param destinations - A map of destination names to URLs for custom navigation.
      */
     navigation?: (action: "page_next" | "page_previous" | "page_custom" | "page_unknown", destination: string | undefined, destinations: Record<string, string>) => void;
     /**
      * A callback for filling out form fields in bidirectional mode.
      *
-     * If automatic context gathering is enabled, the default implementation will fill out the form fields using standard DOM APIs.
+     * The default implementation will fill out the form fields using standard DOM APIs.
      * @param fields - An array of field objects with `id` and `value` properties.
-     * @param pageFields - A map of field IDs to DOM elements for custom form filling. Only present if `automaticContext` is enabled.
+     * @param pageFields - A map of field IDs to DOM elements for custom form filling.
      */
     input?: (fields: InputField[], pageFields: Record<string, Element>) => void;
     /**
@@ -264,7 +178,6 @@ export type BidirectionalConfig = {
      * A callback for customizing the automatic context gathering.
      *
      * This allows you to modify the context and state before they are sent to the LLM.
-     * @param arg - An object containing the current context and state.
      * @returns The modified context and state. If the state is identical to the previous state, the call to the server will be skipped.
      */
     customizeAutomaticContext?: (arg: {
@@ -282,24 +195,17 @@ export type BidirectionalConfig = {
     };
 } | {
     /**
-     * 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`.
+     * Disable gathering page context automatically.
      */
     automaticContext: false;
     /**
-     * Navigation handler for bidirectional mode.
-     *
-     * If automatic context gathering is enabled, the default implementation will navigate to those pages using standard `window.location` APIs.
+     * Navigation handler for bidirectional mode. Without automatic context there is no default implementation.
      * @param action - The navigation action to perform.
      * @param destination - The name of the destination to navigate to if `action` is `"page_custom"`.
      */
     navigation?: (action: "page_next" | "page_previous" | "page_custom" | "page_unknown", destination?: string) => void;
     /**
-     * A callback for filling out form fields in bidirectional mode.
-     *
-     * If automatic context gathering is enabled, the default implementation will fill out the form fields using standard DOM APIs.
+     * A callback for filling out form fields in bidirectional mode.  Without automatic context there is no default implementation.
      * @param fields - An array of field objects with `id` and `value` properties.
      */
     input?: (fields: InputField[]) => void;
@@ -307,12 +213,12 @@ export type BidirectionalConfig = {
      * A callback for custom actions in bidirectional mode.
      * @param action - The custom name of your action.
      * @param payload - The payload defined for the custom action.
-     * @returns
      */
     custom?: (action: string, payload: unknown) => void;
 };
 /**
  * Main Touchpoint creation properties object
+ * @category Basics
  */
 export interface TouchpointConfiguration {
     /**
@@ -324,7 +230,7 @@ export interface TouchpointConfiguration {
      */
     windowSize?: WindowSize;
     /**
-     * Optional color mode for the chat window, defaults to `dark`
+     * Optional color mode for the chat window, defaults to `dark`. Setting `light dark` enables automatic switching based on system settings.
      */
     colorMode?: ColorMode;
     /**
@@ -358,16 +264,17 @@ export interface TouchpointConfiguration {
      */
     theme?: Partial<Theme>;
     /**
-     * Optional custom modality components to render in Touchpoint
+     * Optional {@link CustomModalityComponent | custom modality components} to render in Touchpoint
      */
     modalityComponents?: Record<string, CustomModalityComponent<unknown>>;
     /**
      * Optional custom modality components to render in Touchpoint
      * @deprecated use {@link TouchpointConfiguration.modalityComponents} instead.
+     * @hidden
      */
     customModalities?: Record<string, CustomModalityComponent<unknown>>;
     /**
-     * Custom conversation init method. Defaults to sending the welcome intent
+     * Custom conversation init method. Defaults to sending the welcome flow.
      * @param handler - the conversation handler.
      * @param context - the context object
      */
@@ -386,10 +293,128 @@ export interface TouchpointConfiguration {
      */
     bidirectional?: BidirectionalConfig;
 }
+/**
+ * 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))",
+ * }
+ * ```
+ * @category Theming
+ */
+export interface Theme {
+    /**
+     * Font family
+     */
+    fontFamily: string;
+    /**
+     * Primary color with 80% opacity
+     */
+    primary80: string;
+    /**
+     * Primary color with 60% opacity
+     */
+    primary60: string;
+    /**
+     * Primary color with 40% opacity
+     */
+    primary40: string;
+    /**
+     * Primary color with 20% opacity
+     */
+    primary20: string;
+    /**
+     * Primary color with 10% opacity
+     */
+    primary10: string;
+    /**
+     * Primary color with 5% opacity
+     */
+    primary5: string;
+    /**
+     * Primary color with 1% opacity
+     */
+    primary1: string;
+    /**
+     * Secondary color with 80% opacity
+     */
+    secondary80: string;
+    /**
+     * Secondary color with 60% opacity
+     */
+    secondary60: string;
+    /**
+     * Secondary color with 40% opacity
+     */
+    secondary40: string;
+    /**
+     * Secondary color with 20% opacity
+     */
+    secondary20: string;
+    /**
+     * Secondary color with 10% opacity
+     */
+    secondary10: string;
+    /**
+     * Secondary color with 5% opacity
+     */
+    secondary5: string;
+    /**
+     * Secondary color with 1% opacity
+     */
+    secondary1: string;
+    /**
+     * Accent color used e.g. for prominent buttons, the loader animation as well as selected card outlines
+     */
+    accent: string;
+    /**
+     * Accent color with 20% opacity
+     */
+    accent20: string;
+    /**
+     * The background color of the main Touchpoint interface
+     */
+    background: string;
+    /**
+     * The color of the overlay covering the visible portion of the website when the Touchpoint interface does not cover the full screen
+     */
+    overlay: string;
+    /**
+     * Primary warning color
+     */
+    warningPrimary: string;
+    /**
+     * Secondary warning color
+     */
+    warningSecondary: string;
+    /**
+     * Primary error color
+     */
+    errorPrimary: string;
+    /**
+     * Secondary error color
+     */
+    errorSecondary: string;
+    /**
+     * Inner border radius: used for most buttons
+     */
+    innerBorderRadius: string;
+    /**
+     * Outer border radius: generally used for elements that contain buttons that have inner border radius. Also used by the launch button.
+     */
+    outerBorderRadius: string;
+}
 /**
  * During a Voice+ bidirectional conversation, you can indicate to the application the availability of
  * custom commands that the user can invoke.
- * @typeParam T - Commands can take a single parameter which will be generated from this schema.
+ * @category Bidirectional Voice+
  */
 export interface BidirectionalCustomCommand {
     /**
@@ -420,6 +445,7 @@ export interface BidirectionalCustomCommand {
 }
 /**
  * Instance of a Touchpoint UI component
+ * @category Basics
  */
 export interface TouchpointInstance {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlxai/touchpoint-ui",
-  "version": "1.2.3-alpha.2",
+  "version": "1.2.4-alpha.1",
   "description": "Web UI for Touchpoint",
   "type": "module",
   "main": "lib/index.js",
@@ -21,10 +21,13 @@
     "preview-docs": "npm run docs && comrak --unsafe --gfm -o docs/index.html docs/index.md && open docs/index.html",
     "publish-docs": "npm run docs && mv docs/index.md ../website/src/content/touchpoint-ui-api-reference.md",
     "test": "typedoc --emit none",
-    "tsc": "tsc"
+    "tsc": "tsc",
+    "update-readme:docs": "rm -rf docs/ && typedoc",
+    "update-readme:merge": "../../scripts/transclude-markdown.js",
+    "update-readme": "npm run update-readme:docs && npm run update-readme:merge"
   },
   "dependencies": {
-    "@nlxai/core": "^1.2.3-alpha.2",
+    "@nlxai/core": "^1.2.4-alpha.1",
     "@react-hookz/web": "^25.0.1",
     "@react-input/mask": "^2.0.4",
     "@rive-app/webgl2": "^2.31.5",
@@ -33,7 +36,7 @@
     "htm": "^3.1.1",
     "livekit-client": "^2.15.14",
     "marked": "^15.0.4",
-    "ramda": "^0.30.1",
+    "ramda": "^0.32.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-error-boundary": "^6.0.0",
@@ -44,7 +47,7 @@
     "@rollup/plugin-replace": "^6.0.2",
     "@tailwindcss/vite": "^4.1.16",
     "@types/node": "^20.12.8",
-    "@types/ramda": "^0.30.2",
+    "@types/ramda": "^0.31.1",
     "@types/react": "^18.3.1",
     "@types/react-dom": "^18.3.0",
     "@typescript-eslint/eslint-plugin": "^7.8.0",
@@ -53,6 +56,8 @@
     "dom-accessibility-api": "^0.7.0",
     "eslint-config-nlx": "*",
     "tailwindcss": "^4.1.16",
+    "typedoc": "^0.28.14",
+    "typedoc-plugin-markdown": "^4.9.0",
     "typescript": "^5.4.5",
     "vite": "^6.0",
     "vite-plugin-dts": "^4.5.0",
@@ -61,5 +66,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7b3f2bffccf925bf674d8fef42af177dc17c367c"
+  "gitHead": "366aa0de51688c11109364d16fbd27783bf4486a"
 }

package/typedoc.cjs

@@ -1,14 +1,27 @@
 /** @type { import('typedoc').TypeDocOptions & { hideInPageTOC?: boolean, hideBreadcrumbs?: boolean} } */
 module.exports = {
-  excludeExternals: true,
   entryPoints: ["./src/index.tsx"],
+  hidePageHeader: true,
+  hidePageTitle: true,
   hideBreadcrumbs: true,
-  hideInPageTOC: true,
+  formatWithPrettier: true,
+  readme: "none",
   out: "docs",
+  useCodeBlocks: true,
   plugin: ["typedoc-plugin-markdown"],
-  readme: "none",
+  router: "module",
+  excludeInternal: true,
+  disableSources: true,
+  groupOrder: ["Functions", "Variables", "Interfaces", "*"],
   sort: ["source-order", "kind", "instance-first", "alphabetical"],
-  treatValidationWarningsAsErrors: true,
-  treatWarningsAsErrors: true,
+  categoryOrder: [
+    "Basics",
+    "Theming",
+    "Modality components",
+    "Bidirectional Voice+",
+    "*",
+  ],
+  treatValidationWarningsAsErrors: false,
+  treatWarningsAsErrors: false,
   validation: { notExported: true, invalidLink: true, notDocumented: true },
-};
+};