Resolves #163: add custom renderers config for images and texts (#164)

* closes #163: add custom button renderer setting * move endPoint from Chat props to TockSettings
theopenconversationkit · Oct 4, 2024 · f5c99a2 · f5c99a2
1 parent 1487322
commit f5c99a2
Show file tree

Hide file tree

Showing 19 changed files with 236 additions and 89 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -38,8 +38,10 @@ module.exports = {
         },
       },
     ],
-    // Place to specify ESLint rules. Can be used to overwrite rules specified from the extended configs
-    // e.g. "@typescript-eslint/explicit-function-return-type": "off",
+    '@typescript-eslint/no-unused-vars': [
+      'error',
+      { ignoreRestSiblings: true },
+    ],
   },
   plugins: ['@emotion'],
 };
diff --git a/README.md b/README.md
@@ -80,10 +80,11 @@ Your bundler must support ESM modules, which is the case for Webpack, Rollup and
 import { ThemeProvider } from "@emotion/react";
 import { TockContext, Chat, createTheme } from 'tock-react-kit';
 
-<TockContext settings={ /* ... */ }>
+<TockContext settings={{
+    endPoint: "<TOCK_BOT_API_URL>",
+}}>
     <ThemeProvider theme={createTheme({ /* ... */})}>
         <Chat
-            endPoint="<TOCK_BOT_API_URL>"
             /* The following parameters are optional */
             referralParameter="referralParameter"
             // also accepts all properties from TockOptions, like:
@@ -166,14 +167,15 @@ If the chat does not suit your needs, there are two main ways to customize the i
 
 ### Configure custom renderers
 
-Custom rendering can currently be defined for text and images. Here are some examples of what this enables:
+Custom rendering can currently be defined for text, images, and buttons. 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
+- dynamically decorating text messages and buttons
 - 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
+- setting up redirects for links
 
 See the [`TockSettings`](#renderersettings) API reference for the details of available renderers.
 
@@ -334,6 +336,7 @@ A `TockTheme` can be used as a value of a `ThemeProvider` of [`emotion-theming`]
 
 | Property name  | Type                    | Description                                          |
 |----------------|-------------------------|------------------------------------------------------|
+| `endPoint`     | `string`                | URL for the bot's web connector endpoint             |
 | `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    |
@@ -346,10 +349,24 @@ A `TockTheme` can be used as a value of a `ThemeProvider` of [`emotion-theming`]
 
 #### `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   |
+| Property name     | Type               | Description                                                                   |
+|-------------------|--------------------|-------------------------------------------------------------------------------|
+| `buttonRenderers` | `ButtonRenderers?` | Configuration of renderers for buttons displayed in the chat interface        |
+| `imageRenderers`  | `ImageRenderers?`  | Configuration of renderers for dynamic images displayed in the chat interface |
+| `textRenderers`   | `TextRenderers?`   | Configuration of renderers for dynamic text displayed in the chat interface   |
+
+#### `ButtonRendererSettings`
+
+Button renderers all implement some specialization of the `ButtonRenderer` interface.
+They are tasked with rendering a graphical component using button-specific data, 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 | Type                        | Description                                                                                          |
+|---------------|-----------------------------|------------------------------------------------------------------------------------------------------|
+| `default`     | `ButtonRenderer`            | The fallback renderer. By default, renders a single `button` component using the provided properties |
+| `url`         | `UrlButtonRenderer`         | Renders an `UrlButton`. By default, renders a single `a` component using the provided properties     |
+| `postback`    | `PostBackButtonRenderer?`   | Renders a `PostBackButton`                                                                           |
+| `quickReply`  | `QuickReplyButtonRenderer?` | Renders a `QuickReply`                                                                               |
 
 #### `ImageRendererSettings`
 

diff --git a/src/components/Card/Card.tsx b/src/components/Card/Card.tsx
@@ -147,13 +147,17 @@ const Card = forwardRef<HTMLLIElement, CardProps>(function cardRender(
     // having the default index-based key is fine since we do not reorder buttons
     <li key={index}>
       {'url' in button ? (
-        <UrlButton customStyle={urlButtonStyle} {...button} />
+        <UrlButton
+          buttonData={button}
+          customStyle={urlButtonStyle}
+          {...(isHidden && { tabIndex: -1 })}
+        />
       ) : (
         <PostBackButton
+          buttonData={button}
           customStyle={postBackButtonStyle}
           onClick={onAction.bind(null, button)}
           onKeyPress={onAction.bind(null, button)}
-          {...button}
           {...(isHidden && { tabIndex: -1 })}
         />
       )}

diff --git a/src/components/Chat/Chat.tsx b/src/components/Chat/Chat.tsx
@@ -8,7 +8,7 @@ import TockLocalStorage from 'TockLocalStorage';
 import PostInitContext from '../../PostInitContext';
 
 export interface ChatProps {
-  endPoint: string;
+  endPoint?: string;
   referralParameter?: string;
   timeoutBetweenMessage?: number;
   /** A callback that will be executed once the chat is able to send and receive messages */

diff --git a/src/components/InlineQuickReplyList/InlineQuickReplyList.tsx b/src/components/InlineQuickReplyList/InlineQuickReplyList.tsx
@@ -156,8 +156,8 @@ const InlineQuickReplyList = ({
         {items.map((child, index) => (
           <QuickReply
             key={`${child.label}-${index}`}
+            buttonData={child}
             onClick={onItemClick.bind(null, child)}
-            {...child}
             ref={ref.items[index]}
           />
         ))}

diff --git a/src/components/QuickReply/QuickReply.tsx b/src/components/QuickReply/QuickReply.tsx
@@ -5,7 +5,10 @@ import React, { DetailedHTMLProps, HTMLAttributes, RefObject } from 'react';
 import { QuickReply as QuickReplyData } from '../../model/buttons';
 
 import QuickReplyImage from './QuickReplyImage';
-import { useTextRenderer } from '../../settings/RendererSettings';
+import {
+  useButtonRenderer,
+  useTextRenderer,
+} from '../../settings/RendererSettings';
 
 const QuickReplyButtonContainer = styled.li`
   list-style: none;
@@ -46,25 +49,29 @@ const qrButtonCss: Interpolation<Theme> = [
   (theme) => theme.overrides?.quickReply,
 ];
 
-type Props = DetailedHTMLProps<
-  HTMLAttributes<HTMLButtonElement>,
-  HTMLButtonElement
-> &
-  QuickReplyData;
+interface Props
+  extends DetailedHTMLProps<
+    HTMLAttributes<HTMLButtonElement>,
+    HTMLButtonElement
+  > {
+  buttonData: QuickReplyData;
+}
 
 const QuickReply = React.forwardRef<HTMLButtonElement, Props>(
-  (
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    { imageUrl, label, payload, nlpText, ...rest }: Props,
-    ref: RefObject<HTMLButtonElement>,
-  ) => {
+  ({ buttonData, ...rest }: Props, ref: RefObject<HTMLButtonElement>) => {
     const TextRenderer = useTextRenderer('default');
+    const ButtonRenderer = useButtonRenderer('quickReply');
     return (
       <QuickReplyButtonContainer>
-        <button ref={ref} css={qrButtonCss} {...rest}>
-          {imageUrl && <QuickReplyImage src={imageUrl} />}
-          <TextRenderer text={label} />
-        </button>
+        <ButtonRenderer
+          buttonData={buttonData}
+          ref={ref}
+          css={qrButtonCss}
+          {...rest}
+        >
+          {buttonData.imageUrl && <QuickReplyImage src={buttonData.imageUrl} />}
+          <TextRenderer text={buttonData.label} />
+        </ButtonRenderer>
       </QuickReplyButtonContainer>
     );
   },

diff --git a/src/components/QuickReplyList/QuickReplyList.tsx b/src/components/QuickReplyList/QuickReplyList.tsx
@@ -50,8 +50,8 @@ const QuickReplyList: (props: Props) => JSX.Element = ({
     (item: Button, index: number) => (
       <QuickReply
         key={`${item.label}-${index}`}
+        buttonData={item}
         onClick={onItemClick.bind(null, item)}
-        {...item}
       />
     ),
     [onItemClick],

diff --git a/src/components/buttons/ButtonList/ButtonList.tsx b/src/components/buttons/ButtonList/ButtonList.tsx
@@ -38,9 +38,12 @@ export const ButtonList: (props: Props) => JSX.Element = ({
     // having the default index-based key is fine since we do not reorder buttons
     <li key={index}>
       {'url' in item ? (
-        <UrlButton {...item}></UrlButton>
+        <UrlButton buttonData={item} />
       ) : (
-        <PostBackButton onClick={onItemClick.bind(null, item)} {...item} />
+        <PostBackButton
+          buttonData={item}
+          onClick={onItemClick.bind(null, item)}
+        />
       )}
     </li>
   );

diff --git a/src/components/buttons/PostBackButton/PostBackButton.stories.tsx b/src/components/buttons/PostBackButton/PostBackButton.stories.tsx
@@ -12,14 +12,18 @@ type Story = StoryObj<typeof PostBackButton>;
 export const SimplePostback: Story = {
   name: 'PostBack Button',
   args: {
-    label: 'Help',
+    buttonData: {
+      label: 'Help',
+    },
   },
 };
 
 export const WithImage: Story = {
   name: 'PostBack Button with image',
   args: {
-    label: 'Help',
-    imageUrl: 'https://doc.tock.ai/tock/assets/images/logo.svg',
+    buttonData: {
+      label: 'Help',
+      imageUrl: 'https://doc.tock.ai/tock/assets/images/logo.svg',
+    },
   },
 };
diff --git a/src/components/buttons/PostBackButton/PostBackButton.tsx b/src/components/buttons/PostBackButton/PostBackButton.tsx
@@ -1,9 +1,13 @@
 import { quickReplyStyle } from '../../QuickReply/QuickReply';
 import { Interpolation, Theme } from '@emotion/react';
 import { baseButtonStyle } from '../../QuickReply';
-import { DetailedHTMLProps, HTMLAttributes } from 'react';
+import { DetailedHTMLProps, HTMLAttributes, JSX } from 'react';
 import QuickReplyImage from '../../QuickReply/QuickReplyImage';
-import { useTextRenderer } from '../../../settings/RendererSettings';
+import {
+  useButtonRenderer,
+  useTextRenderer,
+} from '../../../settings/RendererSettings';
+import { PostBackButtonData } from '../../../index';
 
 const postBackButtonCss: Interpolation<Theme> = [
   baseButtonStyle,
@@ -15,29 +19,29 @@ const postBackButtonCss: Interpolation<Theme> = [
   ],
 ];
 
-type Props = DetailedHTMLProps<
-  HTMLAttributes<HTMLButtonElement>,
-  HTMLButtonElement
-> & {
+interface Props
+  extends DetailedHTMLProps<
+    HTMLAttributes<HTMLButtonElement>,
+    HTMLButtonElement
+  > {
+  buttonData: PostBackButtonData;
   customStyle?: Interpolation<unknown>;
-  imageUrl?: string;
-  label: string;
   tabIndex?: 0 | -1;
-};
+}
 
 export const PostBackButton = ({
-  imageUrl,
-  label,
+  buttonData,
   customStyle,
   ...rest
 }: Props): JSX.Element => {
   // Allow custom override for the Card's button styling
   const css = customStyle ? [baseButtonStyle, customStyle] : postBackButtonCss;
   const TextRenderer = useTextRenderer('default');
+  const ButtonRenderer = useButtonRenderer('postback');
   return (
-    <button css={css} {...rest}>
-      {imageUrl && <QuickReplyImage src={imageUrl} />}
-      <TextRenderer text={label} />
-    </button>
+    <ButtonRenderer buttonData={buttonData} css={css} {...rest}>
+      {buttonData.imageUrl && <QuickReplyImage src={buttonData.imageUrl} />}
+      <TextRenderer text={buttonData.label} />
+    </ButtonRenderer>
   );
 };
diff --git a/src/components/buttons/UrlButton/UrlButton.stories.tsx b/src/components/buttons/UrlButton/UrlButton.stories.tsx
@@ -12,25 +12,31 @@ type Story = StoryObj<typeof UrlButton>;
 export const SimpleUrl: Story = {
   name: 'URL Button',
   args: {
-    label: 'TOCK',
-    url: 'https://doc.tock.ai',
+    buttonData: {
+      label: 'TOCK',
+      url: 'https://doc.tock.ai',
+    },
   },
 };
 
 export const WithImage: Story = {
   name: 'URL Button with image',
   args: {
-    label: 'TOCK',
-    url: 'https://doc.tock.ai',
-    imageUrl: 'https://doc.tock.ai/tock/assets/images/logo.svg',
+    buttonData: {
+      label: 'TOCK',
+      url: 'https://doc.tock.ai',
+      imageUrl: 'https://doc.tock.ai/tock/assets/images/logo.svg',
+    },
   },
 };
 
 export const WithTarget: Story = {
   name: 'URL Button with _self target',
   args: {
-    label: 'TOCK',
-    url: 'https://doc.tock.ai',
-    target: '_self',
+    buttonData: {
+      label: 'TOCK',
+      url: 'https://doc.tock.ai',
+      target: '_self',
+    },
   },
 };
diff --git a/src/components/buttons/UrlButton/UrlButton.tsx b/src/components/buttons/UrlButton/UrlButton.tsx
@@ -2,14 +2,15 @@ import { quickReplyStyle } from '../../QuickReply/QuickReply';
 import { css, Interpolation, Theme } from '@emotion/react';
 import { baseButtonStyle } from '../../QuickReply';
 import QuickReplyImage from '../../QuickReply/QuickReplyImage';
-import { useTextRenderer } from '../../../settings/RendererSettings';
+import {
+  useButtonRenderer,
+  useTextRenderer,
+} from '../../../settings/RendererSettings';
+import { UrlButton as UrlButtonData } from '../../../model/buttons';
 
 type Props = {
   customStyle?: Interpolation<unknown>;
-  imageUrl?: string;
-  label: string;
-  target?: string;
-  url: string;
+  buttonData: UrlButtonData;
   tabIndex?: 0 | -1;
 };
 
@@ -29,21 +30,25 @@ const defaultUrlButtonCss: Interpolation<Theme> = [
 ];
 
 export const UrlButton: (props: Props) => JSX.Element = ({
-  url,
-  imageUrl,
-  label,
-  target = '_blank',
+  buttonData,
   customStyle,
   tabIndex,
 }: Props) => {
   const css = customStyle
     ? [baseUrlButtonCss, customStyle]
     : defaultUrlButtonCss;
   const TextRenderer = useTextRenderer('default');
+  const ButtonRenderer = useButtonRenderer('url');
   return (
-    <a href={url} target={target} css={css} tabIndex={tabIndex}>
-      {imageUrl && <QuickReplyImage src={imageUrl} />}
-      <TextRenderer text={label} />
-    </a>
+    <ButtonRenderer
+      buttonData={buttonData}
+      href={buttonData.url}
+      target={buttonData.target ?? '_blank'}
+      css={css}
+      tabIndex={tabIndex}
+    >
+      {buttonData.imageUrl && <QuickReplyImage src={buttonData.imageUrl} />}
+      <TextRenderer text={buttonData.label} />
+    </ButtonRenderer>
   );
 };