Resolves #159, #158: add custom renderers config for images and texts

.eslintrc.js

@@ -21,6 +21,14 @@ module.exports = {
 
   rules: {
     '@emotion/pkg-renaming': 'error',
+    '@emotion/no-vanilla': 'error',
+    '@emotion/import-from-emotion': 'error',
+    '@emotion/styled-import': 'error',
+    // Modern JSX transform does not require explicit React import
+    'react/jsx-uses-react': 'off',
+    'react/react-in-jsx-scope': 'off',
+    // Ignore the css property added to React components by Emotion
+    'react/no-unknown-property': ['error', { ignore: ['css'] }],
     '@typescript-eslint/ban-types': [
       'error',
       {

.storybook/main.ts

@@ -11,7 +11,13 @@ const config: StorybookConfig = {
 
   framework: {
     name: '@storybook/react-webpack5',
-    options: {},
+    options: {
+      strictMode: true,
+      fastRefresh: true,
+      builder: {
+        useSWC: true,
+      },
+    },
   },
 
   docs: {

.swcrc

@@ -0,0 +1,10 @@
+{
+  "jsc": {
+    "transform": {
+      "react": {
+        "runtime": "automatic",
+        "importSource": "@emotion/react"
+      }
+    }
+  }
+}

README.md

@@ -162,7 +162,25 @@ renderChat(document.getElementById('chat'), '<TOCK_BOT_API_URL>', 'referralParam
 
 ## Customize interface
 
-If the chat does not suit your needs you can also use the components separately.
+If the chat does not suit your needs, there are two main ways to customize the interface rendering.
+
+### Configure custom renderers
+
+Custom rendering can currently be defined for text and images. Here are some examples of what this enables:
+
+- processing custom markup in the text of any component
+- stripping harmful HTML tags and attributes when the backend is untrustworthy
+- dynamically decorating text messages
+- automatically embedding SVG images into the DOM
+- implementing fallback behavior when an image fails to load
+- using [metadata](#message-metadata) sent by the server to set image properties like width and height
+
+See the [`TockSettings`](#renderersettings) API reference for the details of available renderers.
+
+### Use the chat components separately
+
+The `tock-react-kit` exports its main components, so you can re-use them to build your own chat interface.
+This approach can be used alongside custom renderers to control more granular aspects of rendering.
 
 ## Message Metadata
 
@@ -180,44 +198,45 @@ ensure data stays available if required.
 
 The metadata from each response is also attached to the corresponding messages.
 This metadata is persisted with the messages, including through page reloads if [local storage history](#local-storage-history) is enabled.
-At the current time, it is only available to custom React-based frontends that handle message rendering themselves.
+It is available to [custom renderers](#configure-custom-renderers) through the use of the `useMessageMetadata` hook,
+as well as to custom React-based frontends that handle message rendering themselves.
 
 ## API Reference
 
 ### `renderChat(element, tockBotApiUrl, referralParameter, theme, options)`
 
 Renders an entire chat in a target element.
 
-| Argument name                  | Type                                                                  | Description                                    |
-| ------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------- |
-| `element`                      | [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) | Target element where the chat will be rendered |
-| `tockBotApiUrl`                | `string`                                                              | URL to the Tock Bot REST API                   |
-| `referralParameter`            | `string`                                                              | Optional referal parameter                     |
-| `theme`                        | `TockTheme`                                                           | Optional theme object                          |
-| `options`                      | `TockOptions`                                                         | Optional options object                        |
+| Argument name       | Type                                                                  | Description                                    |
+|---------------------|-----------------------------------------------------------------------|------------------------------------------------|
+| `element`           | [`Element`](https://developer.mozilla.org/en-US/docs/Web/API/Element) | Target element where the chat will be rendered |
+| `tockBotApiUrl`     | `string`                                                              | URL to the Tock Bot REST API                   |
+| `referralParameter` | `string`                                                              | Optional referal parameter                     |
+| `theme`             | `TockTheme`                                                           | Optional theme object                          |
+| `options`           | `TockOptions`                                                         | Optional options object                        |
 
 ### `useTock(tockBotApiUrl, extraHeadersProvider, disableSse, localStorageHistory)`
 
 Hook that provides chat history and methods to communicate with the Tock Bot. It must be used alongside with `TockContext`. Returns a useTock interface.
 
 | Argument name          | Type                                    | Description                                                   |
-| ---------------------- | --------------------------------------- | ------------------------------------------------------------- |
+|------------------------|-----------------------------------------|---------------------------------------------------------------|
 | `tockBotApiUrl`        | `string`                                | URL to the Tock Bot REST API                                  |
 | `extraHeadersProvider` | `() => Promise<Record<string, string>>` | Optional Provider of extra HTTP headers for outgoing requests |
-| `disableSse`           | `boolean`                               | Optional Force-disabling of SSE mode                      |
-| `localStorageHistory`  | `TockLocalStorage`                      | Optional Configuration for LocalStorage history   |
+| `disableSse`           | `boolean`                               | Optional Force-disabling of SSE mode                          |
+| `localStorageHistory`  | `TockLocalStorage`                      | Optional Configuration for LocalStorage history               |
 
 ### `TockTheme`
 
 A `TockTheme` can be used as a value of a `ThemeProvider` of [`emotion-theming`](https://emotion.sh/docs/theming) (bundled with the library) or as a third argument of `renderChat`.
 
-| Property name       | Type              | Description                                               |
-|---------------------|-------------------|-----------------------------------------------------------|
-| `palette`           | `Palette`         | Object for customising colors (see below)                 |
-| `sizing`            | `Sizing`          | Object for customising elements sizing (see below)        |
-| `typography`        | `Typography`      | Object for customising typographies (see below)           |
-| `overrides`         | `Overrides?`      | Object allowing further styling (see below)               |
-| `inlineQuickReplies`| `boolean?`        | Displaying quick replies inline (by default false)        |
+| Property name        | Type         | Description                                        |
+|----------------------|--------------|----------------------------------------------------|
+| `palette`            | `Palette`    | Object for customising colors (see below)          |
+| `sizing`             | `Sizing`     | Object for customising elements sizing (see below) |
+| `typography`         | `Typography` | Object for customising typographies (see below)    |
+| `overrides`          | `Overrides?` | Object allowing further styling (see below)        |
+| `inlineQuickReplies` | `boolean?`   | Displaying quick replies inline (by default false) |
 
 #### `Palette`
 
@@ -317,13 +336,54 @@ A `TockTheme` can be used as a value of a `ThemeProvider` of [`emotion-theming`]
 |----------------|-------------------------|------------------------------------------------------|
 | `locale`       | `string?`               | Optional user language, as an *RFC 5646* code        |
 | `localStorage` | `LocalStorageSettings?` | Configuration for use of localStorage by the library |
+| `renderers`    | `RendererSettings?`     | Configuration for custom image and text renderers    |
 
 #### `LocalStorageSettings`
 
 | Property name   | Type      | Description                                                                                   |
 |-----------------|-----------|-----------------------------------------------------------------------------------------------|
 | `storagePrefix` | `string?` | Prefix for local storage keys allowing communication with different bots from the same domain |
 
+#### `RendererSettings`
+
+| Property name    | Type                     | Description                                                                   |
+|------------------|--------------------------|-------------------------------------------------------------------------------|
+| `imageRenderers` | `ImageRendererSettings?` | Configuration of renderers for dynamic images displayed in the chat interface |
+| `textRenderers`  | `TextRendererSettings?`  | Configuration of renderers for dynamic text displayed in the chat interface   |
+
+#### `ImageRendererSettings`
+
+Image renderers all implement the `ImageRenderer` interface.
+They are tasked with rendering a graphical component using a source URL, a description, a class name, and other generic HTML attributes.
+The passed in class name provides the default style for the rendered component, as well as applicable [overrides](#overrides).
+
+| Property name | Description                                                                                       |
+|---------------|---------------------------------------------------------------------------------------------------|
+| `default`     | The fallback renderer. By default, renders a single `img` component using the provided properties |
+| `standalone`  | Renders images in the dedicated image component, including the zoomed-in view                     |
+| `card`        | Renders images in the card component (including in carousels)                                     |
+| `buttonIcon`  | Renders icons in quick replies, URL buttons, and postback buttons                                 |
+
+#### `TextRendererSettings`
+
+Text renderers all implement the `TextRenderer` interface.
+They are tasked with rendering a string into a text component.
+
+A renderer can be restricted in the kind of HTML nodes it emits depending on the context in which it is invoked.
+Most text renderers should only emit [phrasing content](https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories#phrasing_content)
+that is also [non-interactive](https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories#interactive_content).
+However, some contexts allow interactive phrasing content, or even any [flow content](https://developer.mozilla.org/en-US/docs/Web/HTML/Content_categories#flow_content).
+
+Some renderers are expected to handle rich text, that is text that already contains HTML formatting.
+Such rich text renderers may strip HTML tags or attributes that are deemed dangerous to add to the DOM.
+
+| Property name | Type of content          | Description                                                                                               |
+|---------------|--------------------------|-----------------------------------------------------------------------------------------------------------|
+| `default`     | non-interactive phrasing | The fallback renderer. By default, renders the whole string as a single text node                         |
+| `html`        | flow                     | The fallback renderer for rich text. By default, renders the string into a `div` with `innerHTML`         |
+| `htmlPhrase`  | phrasing                 | The fallback renderer for inline rich text. By default, renders the string into a `span` with `innerHTML` |
+| `userContent` | phrasing                 | Renders text in user messages. If unspecified, falls back to `default`                                    |
+
 ### `TockOptions`
 
 Contains all the properties from [`TockSettings`](#tocksettings) as well as the following:

package.json

@@ -15,7 +15,6 @@
     "build/tock-react-kit.d.ts",
     "build/tock-react-kit.esm.js",
     "build/tock-react-kit.esm.js.map",
-    "build/tock-react-kit.umd.js",
     "build/tock-react-kit-standalone.umd.js",
     "build/tock-react-kit-standalone.esm.js"
   ],
@@ -33,16 +32,13 @@
   },
   "dependencies": {
     "deepmerge": "^4.2.2",
-    "linkifyjs": "^2.1.9",
+    "linkify-html": "^3.0.5",
+    "linkifyjs": "^3.0.5",
     "polished": "^3.6.5",
     "react-feather": "^2.0.8",
     "styled-tools": "^1.7.2"
   },
   "devDependencies": {
-    "@babel/core": "^7.22.15",
-    "@babel/preset-env": "^7.22.15",
-    "@babel/preset-react": "^7.22.15",
-    "@babel/preset-typescript": "^7.22.15",
     "@emotion/eslint-plugin": "^11.11.0",
     "@emotion/react": "^11.11.3",
     "@emotion/styled": "^11.11.0",
@@ -65,7 +61,6 @@
     "@typescript-eslint/eslint-plugin": "^7.0.2",
     "@typescript-eslint/parser": "^7.0.2",
     "auto-changelog": "^2.4.0",
-    "babel-loader": "^9.1.3",
     "eslint": "^8.56.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.1.3",

rollup.config.mjs

@@ -8,20 +8,15 @@ import typescript from '@rollup/plugin-typescript';
 export default [
   {
     input: 'src/index.ts',
-    external: ['react', 'react-dom', '@emotion/react', '@emotion/styled'],
+    external: [
+      'react',
+      'react/jsx-runtime',
+      'react-dom',
+      '@emotion/react',
+      '@emotion/react/jsx-runtime',
+      '@emotion/styled',
+    ],
     output: [
-      {
-        // TODO deprecated build output, remove in 24.x
-        file: 'build/tock-react-kit.umd.js',
-        format: 'umd',
-        name: 'TockReact',
-        globals: {
-          react: 'React',
-          'react-dom': 'ReactDOM',
-          '@emotion/styled': 'emotionStyled',
-          '@emotion/react': 'emotionReact',
-        },
-      },
       {
         file: 'build/tock-react-kit.esm.js',
         format: 'esm',

src/MessageMetadata.tsx

@@ -0,0 +1,12 @@
+import { Context, createContext, useContext } from 'react';
+
+const MessageMetadataCtx: Context<Record<string, string>> = createContext({});
+
+export const MessageMetadataContext = MessageMetadataCtx.Provider;
+
+/**
+ * Returns the metadata associated with the surrounding message
+ */
+export const useMessageMetadata = (): Record<string, string> => {
+  return useContext(MessageMetadataCtx);
+};

src/PostInitContext.ts

@@ -7,7 +7,7 @@ export interface TockHistoryData {
   readonly quickReplies: QuickReply[];
 }
 
-export interface PostInitContext extends UseLocalTools {
+export default interface PostInitContext extends UseLocalTools {
   /**
    * The full chat history at the time the Chat component is initialized, which includes messages from local storage
    * and/or from TockContext, or null if there is no chat history at all.

src/TockContext.tsx

@@ -1,4 +1,4 @@
-import React, {
+import {
   Context,
   createContext,
   Dispatch,
@@ -12,6 +12,7 @@ import { PartialDeep } from 'type-fest';
 import { retrieveUserId } from './utils';
 import { QuickReply } from './model/buttons';
 import { Message } from './model/messages';
+import TockSettings, { defaultSettings } from './settings/TockSettings';
 
 export const TockSettingsContext: Context<TockSettings | undefined> =
   createContext<TockSettings | undefined>(undefined);
@@ -47,15 +48,6 @@ export const useTockDispatch: () => Dispatch<TockAction> = () => {
   return dispatch;
 };
 
-export interface LocalStorageSettings {
-  prefix?: string;
-}
-
-export interface TockSettings {
-  localStorage: LocalStorageSettings;
-  locale?: string;
-}
-
 export interface TockState {
   quickReplies: QuickReply[];
   messages: Message[];
@@ -139,10 +131,6 @@ const tockReducer: Reducer<TockState, TockAction> = (
   return state;
 };
 
-const defaultSettings: TockSettings = {
-  localStorage: {},
-};
-
 const TockContext: (props: {
   children?: ReactNode;
   settings?: PartialDeep<TockSettings>;
@@ -153,18 +141,15 @@ const TockContext: (props: {
   children?: ReactNode;
   settings: PartialDeep<TockSettings>;
 }) => {
-  const mergedSettings = deepmerge(defaultSettings, settings);
-  const [state, dispatch]: [TockState, Dispatch<TockAction>] = useReducer(
-    tockReducer,
-    {
-      quickReplies: [],
-      messages: [],
-      userId: retrieveUserId(mergedSettings.localStorage.prefix),
-      loading: false,
-      sseInitializing: false,
-      metadata: {},
-    },
-  );
+  const mergedSettings = deepmerge(defaultSettings, settings) as TockSettings;
+  const [state, dispatch] = useReducer(tockReducer, {
+    quickReplies: [],
+    messages: [],
+    userId: retrieveUserId(mergedSettings.localStorage.prefix),
+    loading: false,
+    sseInitializing: false,
+    metadata: {},
+  });
   return (
     <TockSettingsContext.Provider value={mergedSettings}>
       <TockStateContext.Provider value={state}>

src/TockOptions.ts

@@ -1,8 +1,8 @@
 import { PartialDeep } from 'type-fest';
 import TockAccessibility from './TockAccessibility';
 import TockLocalStorage from './TockLocalStorage';
-import { TockSettings } from './TockContext';
-import { PostInitContext } from './PostInitContext';
+import TockSettings from './settings/TockSettings';
+import PostInitContext from './PostInitContext';
 
 export interface TockOptions extends PartialDeep<TockSettings> {
   // a callback that will be executed once the chat is able to send and receive messages