@davi-ai/retorik-framework 1.0.7

package/README.md

@@ -0,0 +1,508 @@
+# retorik-framework
+
+> Retorik Framework package
+
+[![NPM](https://img.shields.io/npm/v/retorik-framework.svg)](https://www.npmjs.com/package/retorik-framework) [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
+
+## Usage with React
+
+### Install
+
+Create a .npmrc file at project root (where your package.json file is located) :
+
+```
+@davi:registry=https://pkgs.dev.azure.com/mydavi/_packaging/Retorik/npm/registry/
+
+always-auth=true
+```
+
+Then [connect to feed](https://dev.azure.com/mydavi/BU%20Logiciel/_artifacts/feed/Retorik/connect/npm) and install package :
+
+```bash
+npm install --save @davi/retorik-framework
+```
+
+### Retorik Agent (full screen)
+
+Minimal configuration :
+
+```tsx
+import { RetorikAgent, characters } from '@davi/retorik-framework'
+import {
+  Configuration,
+  ViewsConfiguration,
+  ChatbotData,
+  PonyfillFactoryCredentials,
+  AddressData,
+  UserData,
+  CustomVoice,
+  characters
+} from '@davi/retorik-framework/dist/src'
+
+const defaultConfig: Configuration = {
+  subtitles: {
+    activated: true,
+    maxLength: 50,
+    showAttachmentsAsSubtitle: false
+  }
+}
+
+const defaultViewsConfig: ViewsConfiguration = {
+  homeRoute: 'home',
+  views: {
+    home: {
+      background: {
+        image: 'images/background_MTC.jpg',
+        style: 'image'
+      }
+    }
+  }
+}
+
+const chatbotData: ChatbotData = {
+  size: undefined,
+  height: undefined
+}
+
+// NB : prefix can be 'dev', 'staging', or 'experimental' 
+const addressData: AddressData = {
+  baseURI: ''
+  tenant: 'name_of_the_tenant',
+  prefix: 'prefix_if_not_using_production_studio.retorik'
+}
+
+const userData: UserData = {
+  name: '',
+  id: '',
+  username: '',
+  nom: '',
+  prenom: '',
+  email: '',
+  token: '',
+  referrer: '',
+  ipaddress: ''
+}
+
+const ponyfillFactoryCredentials: PonyfillFactoryCredentials = {
+  region: 'your_region',
+  subscriptionKey: 'subscription_key'
+}
+
+class Example extends Component {
+  render() {
+    return (
+      <RetorikAgent
+        config={defaultConfig}
+        viewsConfig={defaultViewsConfig}
+        chatbotData={chatbotData}
+        agentData={characters.lea}
+        ponyfillFactoryCredentials={ponyfillFactoryCredentials}
+        addressData={addressData}
+        userData={userData}
+      />
+  }
+}
+```
+
+### Retorik Widget
+
+You can use Retorik Widget just like Retorik Agent, with the same props.
+The default button supplied with Retorik Widget can be customized or deleted as you wish (`#retorik-widget-button`)
+You can create your own buttons and use several global helper functions to open and close the widget.
+These functions can be either imported from the package (React mode) or used through the DOM window element :
+- React : 
+  ```ts
+    import {
+      openWidget,
+      closeWidget,
+      toggleWidget,
+      toggleDisplay
+    } from '@davi/retorik-framework'
+
+    openWidget()        // open the widget
+    closeWidget()       // close the widget
+    toggleWidget()      // toggle to open if the widget is closed, and to close if the widget is opened
+    toggleDisplay()     // toggle from large display to thumbnail, or from thumbnail to large (experimental)
+  ```
+- commonJs :
+  ```ts
+    window.Retorik.toggleWidget()
+    window.Retorik.openWidget()
+    window.Retorik.closeWidget()
+    window.Retorik.toggleDisplay()
+  ````
+A configuration file is also available, allowing you to customize some parts of the widget. If this configuration is used, it has to be added in the props as `{ widgetConfig: <configuration> }` This configuration's type is :
+
+```ts
+  type WidgetConfiguration = {
+    button?: WidgetButton       // button options
+    large?: WidgetFrame         // main frame options
+    thumbnail?: WidgetFrame     // thumbnail mode options (experimental)
+  }
+
+  type WidgetButton = {
+    display?: boolean           // set this to false to prevent the button from being displayed
+    text?: {
+      content?: string          // string that will be displayed in the button, if not set a default translation of 'Need help ?' based on the browser's default language is displayed
+      color?: string            // text color, default = rgb(112, 112, 112)
+      bold?: boolean            // text is bold by default, set to false to use a normal weight
+    }
+    image?: {
+      url?: string
+      position?: 'left' | 'right'   // default = left
+      height?: string               // default = 2rem
+      marginY?: boolean             // default = 0.25rem, set to false to remove this margin
+    }
+    border?: {
+      color?: string            // default = rgb(112, 112, 112)
+      thickness?: number        // border width in pixels, default = 1px
+      rounded?: boolean         // rounded corners by default, set to false to remove rounding 
+    }
+    background?: {
+      color?: string            // default = transparent
+    }
+    position?: Position         // default = right lower corner (right = 1rem, bottom = 1rem)
+  }
+
+  type WidgetFrame = {
+    height?: string             // default = full height
+    width?: string              // max-width = 600px, default = 600px
+    position?: Position         // default = on the right of the screen with margins (right = 1rem, bottom = 1rem, top = 2rem)
+    border?: {
+      color?: string            // default = rgb(112, 112, 112)
+      thickness?: number        // border width in pixels, default = 1px
+      rounded?: boolean         // rounded corners by default, set to false to remove rounding
+    }
+  }
+
+  type Position = {
+    top?: string
+    bottom?: string
+    left?: string
+    right?: string
+  }
+```
+
+## Locales
+
+If you followed the minimal configuration `addressData` field, the available languages will be automatically retrieved from studio.retorik  
+depending on the chosen tenant, and the default language will be set from this data.  
+If graphql is not allowed for this tenant or if no locale is set, `fr-FR` is the default one, without any other language allowed.  
+
+### Default Locale
+
+You can override the default locale with the `locales` objet in the `config`. There are two mechanisms, and of course each one functions only if the  
+chosen language is available in studio.retorik. You can either :
+- choose the default language to use with the field `default`
+- choose to use the browser's language as default with putting the `getDefaultFromBrowser` field to `true`
+
+The chosen locale will be compared with the array of those retrieved from studio.retorik, and set as default if present in this array.  
+
+### Dynamically set the locale
+
+You can dynamically set the current locale by using the CustomEvent `changeRetorikLocale`, giving the wanted locale in the detail in the `locale` field.
+```
+const changeLocaleEvent = new CustomEvent('changeRetorikLocale', {
+  detail: {
+    locale: 'en-US'
+  }
+})
+
+document.dispatchEvent(changeLocaleEvent)
+```
+The locale sent inside the event will also be compared with the array of those retrieved from studio.retorik, and set if present in this array.
+
+## Development
+
+Navigate to the root of the folder 'retorik-framework'.
+Install the packages with npm
+
+```bash
+npm install
+```
+
+Launch the auto-package tool and let it run
+
+```bash
+npm start
+```
+
+Navigate to the folder 'example'.
+Same steps as before :
+
+```bash
+npm install
+npm start
+```
+
+Npm start launches a local server on localhost:3000 which renders the app, as if used as a React app importing the packages.
+Modifying the code inside the 'example' or 'src' folders auto-updates the display on localhost:3000
+
+## About the animation
+
+Your animations MUST follow the following rules
+
+### Folder architecture
+
+The parameter 'agentData' in the props of the component 'retorikAgent' is an URL so that the framework is able to load the animations.
+This URL must lead to a folder with the following architecture :
+
+```
+└── <folder_name>
+          ├── webm
+          │    ├── small
+          │    │    ├── Move
+          │    │    │     ├── ns
+          │    │    │     │   ├── Explain1_ns.webm
+          │    │    │     │   ├── ...
+          │    │    │     │   ├── Explain<x>_ns.webm
+          │    │    │     │   ├── Idle1_ns.webm
+          │    │    │     │   ├── ...
+          │    │    │     │   └── Idle<x>_ns.webm
+          │    │    │     └── sp
+          │    │    │         ├── Explain1_sp.webm
+          │    │    │         ├── ...
+          │    │    │         ├── Explain<x>_sp.webm
+          │    │    │         ├── Idle1_sp.webm
+          │    │    │         ├── ...
+          │    │    │         └── Idle<x>_sp.webm
+          │    │    ├── Still
+          │    │    │     ├── ns
+          │    │    │     │   ├── Still1_ns.webm
+          │    │    │     │   ├── ...
+          │    │    │     │   └── Still<x>_ns.webm
+          │    │    │     └── sp
+          │    │    │         ├── Still1_sp.webm
+          │    │    │         ├── ...
+          │    │    │         └── Still<x>_sp.webm
+          │    │    ├── <custom>
+          │    │    │     ├── ns
+          │    │    │     │   ├── <custom>1_ns.webm
+          │    │    │     │   ├── ...
+          │    │    │     │   └── <custom><x>_ns.webm
+          │    │    │     └── sp
+          │    │    │         ├── <custom>1_sp.webm
+          │    │    │         ├── ...
+          │    │    │         └── <custom><x>_sp.webm
+          │    │    └── ...
+          │    ├── medium
+          │    │    └── <same as small>
+          │    └── large
+          │         └── <same as small>
+          ├── mp4
+          │    ├── small
+          │    │    └── <same as webm with mp4 files>
+          │    ├── medium
+          │    │    └── <same as webm with mp4 files>
+          │    └── large
+          │         └── <same as webm with mp4 files>
+          └── manifest.json
+```
+
+Webm / mp4 are used in different browsers (mostly mp4 for Safari, webm for the others).
+The 3 sub-folders small, medium and large contain the animations which are scaled for different screen sizes. The sizes below are thoses used basicaly :
+
+- small : 480x480 pixels (mobiles)
+- medium : 1200x1200 px (laptops / desktops)
+- large : 2000x2000 px (very large screens)
+
+'ns' and 'sp' sub-folders mean 'no-speak' and 'speak'. In the 'ns' folders are the animations where the character's lips aren't moving and the 'sp' folder contains the same animations, in which the lips are moving to simulate a speech.
+
+### Naming convention
+
+Only the folders 'Move' and 'Still' are necessary. The folder 'Move' contains the basic animation that are displayed when the character is performing an action, and is divided in 2 main categories :
+
+- Idle : animation where the character moves while there is no text to speak
+- Explain : animation where the character makes movements to explain something while speaking.
+
+The folder 'Still' contains the animations where the character stays still. These are used for transition between each loading of an Idle or Explain animation.
+
+The other folders contain the animations only usable in a custom queue where the given animations will be played one after another, with a fallback to the normal behavior when every animation has been played.
+
+Each animation file MUST follow this pattern :
+
+```
+  'Move' folder :
+  <Explain|Idle><index>_<ns|sp>.<webm|mp4>
+
+  'Still' folder :
+  <Still><index>_<ns|sp>.<webm|mp4>
+
+  <other_folder> folder :
+  <other_folder><index>_<ns|sp>.<webm|mp4>
+```
+
+The index begins at 1 and goes one by one up to 99. There MUST be an index even if there is only 1 animation in the folder.
+
+For example :
+
+```
+└── <folder_name>
+          ├── webm
+          │    ├── small
+          │    │    ├── Chatting
+          │    │    │     ├── ns
+          │    │    │     │   ├── Chatting1_ns.webm
+          │    │    │     │   └── Chatting2_ns.webm
+          │    │    │     └── sp
+          │    │    │         ├── Chatting1_sp.webm
+          │    │    │         └── Chatting2_sp.webm
+```
+
+### Manifest.json
+
+At the root of the main folder reached when using the URL, there has to be a 'manifest.json' file containing some data related to the animations :
+
+- gender : 'male' | 'female' | 'other' : the gender of the character, used to choose a correct voice inside the framework
+- name : the name of the agent displayed in the framework
+- portrait : link to the portrait image displayed in the widget or mobile in text conversation mode
+- data : contains the number of animations related to each folder. The mandatoty keys are "idle", "explain" and "still". For every other animation folder, there must be a pair "key" : value with the name of the folder (lowercase) as key and the number of animations available as value.
+
+For example if you have :
+
+- a male character
+- 5 Explain animations
+- 3 Idle animations
+- 1 Still animation
+- taking the example above, 2 Chatting animations
+  the manifest.json file will be as follows :
+
+```tsx
+{
+	"gender": "male",
+  "name": "Léa",
+  "portrait": "portrait_cropped.png",
+	"data": {
+		"idle": 3,
+		"explain": 5,
+		"still": 1,
+		"chatting": 2
+	}
+}
+```
+
+With these data, the chatbot inside the framework will be able to use the animations and switch from one to another depending on the situation.
+
+## Actions and events
+
+### Keep the animations playing no-speak even while a speech is played
+
+Two customEvents allow you to prevent or allow the animations from playing the speak ones.
+These events are linked to the document, and can be called anywhere as follows :
+
+```tsx
+/* Allow speak animations : */
+document.dispatchEvent(new CustomEvent('allowChatbotSpeakAnimationsEvent'))
+/* Prevent speak animations : */
+document.dispatchEvent(new CustomEvent('preventChatbotSpeakAnimationsEvent'))
+```
+
+### Change the voice used for speak without changing the complete agent
+
+When you change the agentData in the props of the RetorikAgent component, its gender is taken in account to get a correct voice each time a text is spoken. If you want
+to use different voice from the basic one or want to use a voice from the other gender, you can use the prop 'customVoice'. The custom voice is taken in account before the gender of the agent, so you can use a male voice even with a female agent, and inversely. See the type of customVoice below :
+
+```tsx
+type CustomVoice = {
+  voice?: string
+  gender?: 'male' | 'female' | 'other'
+}
+```
+
+You can either use :
+
+- a special voice if you know its name among the set of Azure neural voices, for example the default English voices are 'AriaNeural' (female) and 'GuyNeural' (male). Be aware that using this forces the language to the one linked to the chosen voice.
+- the default voice using only the gender. As the voice is selected depending the locale in the activity, the first voice within the set of Azure neural voices matching both gender and locale is chosen.
+
+
+### Menus and extensions
+
+Menu entries are customizable and expandable
+## Menu types
+You can use 3 types of menu :
+- BaseMenu using the views available inside Retorik Framework :
+```tsx
+type BaseMenu = {
+  view: AvailableViews
+  indice: number
+}
+```
+
+- CustomMenu using the custom data from your side :
+```tsx
+type CustomMenu = {
+    icon: JSX.Element;
+    clickHandler?: () => void;
+    label: LocalizedStrings | string;
+    customDisplay?: string;
+    indice: number
+};
+```
+
+- BaseSubMenu with smaller cards for sub-functionalities
+```tsx
+type BaseSubMenu = {
+  view: AvailableSubViews
+  indice: number
+}
+```
+## Menu disposition in desktop mode
+![](./example/public/images/readme/menus.PNG)
+
+You can have several custom menus. They will stack one under another.
+
+## Base menu
+In the configuration object, `baseMenu` property is available to add or remove base menu entries
+
+`baseMenu` is an array of type `BaseMenu` | `CustomMenu`.
+
+Here is the default value :
+
+```js
+baseMenu:[
+    { view: AvailableViews.home, indice: 1 }
+  ]
+```
+
+## Additionnal menu & page
+You can add additionnal entry that redirect to an external component with the property `customMenu` in the configuration object.
+
+`customMenu` is an array of type `CustomMenu`.
+
+External components can be passed to the `RetorikMainComponentProps` when creating the `RetorikAgent` or the `RetorikWidget` component :
+
+```tsx
+externalComponents: Array<{ name: string; component: JSX.Element }>
+```
+
+- `customDisplay` and `externalComponents` properties need to match and make the connection between menu entry and external component. They allow to inject an external component which will be displayed in full screen in the framework
+- The complete menu is ordered by the `indice` property present in the basic and custom menus
+
+You can also trigger the opening of the custom screen externaly using the `setCurrentCustomView` function that takes as parameter a `CustomMenu` object
+
+## Submenu
+Basically contains history and tutorial functionnalities. You can add custom items inside, with the same behaviour as in base or custom menus. 
+
+`subMemu` is an array of type `BaseSubMenu | CustomMenu`:
+
+### Events sent and received
+Most of the time, these events are used in a commonJs way, as we provide functions carrying the same task that you can import from the package.
+You can find all the events in the 2 next sections.
+
+## Events sent by Retorik Framework
+- `retorikChangeLocale` : CustomEvent, detail: { locale: string } -> event sent when  the locale is changed inside the retorik framework. The detail is an object which key 'locale' contains the new locale as string
+- `retorikSpeakStart` : Event -> sent on speech start
+- `retorikSpeakStop` : Event -> sent on speech end / error
+- `newsEnded` : Event -> sent when all news have been read in news view
+- `retorikSpeechRecognitionEnded` : CustomEvent, detail : string | undefined -> event sent at the end of a speech recognition. The detail field contains the text spoken as a string | undefined
+
+## Events with listeners in Retorik Framework
+- `cancelSpeech` : Event linked to document -> cancels current speech if there is one
+- `retorikSendActivity` : CustomEvent linked to document, detail : Object of type WebchatActivity -> uses the internal process to send an activity to the bot
+- `retorikStartListening` : Event linked to the document -> begins speech recognition in Retorik Framework
+- `retorikDisplaySubtitles` : CustomEvent linked to document, detail : boolean -> sets displaySubtitles state to the content of detail (true / false)
+- `sendPlayAnimationEvent` : CustomEvent linked to the document, detail : { queue : Array<string> } -> sets a queue of animations to be played by the Body Engine Sprite
+
+## License
+
+MIT © [DAVI](https://github.com/DAVI)