diff --git a/public/robots.txt b/public/robots.txt index e3d26cc48..4857501a1 100644 --- a/public/robots.txt +++ b/public/robots.txt @@ -1,9 +1,14 @@ # * User-agent: * Allow: / +Disallow: /*.json$ +Disallow: /*_buildManifest.js$ +Disallow: /*_middlewareManifest.js$ +Disallow: /*_ssgManifest.js$ +Disallow: /*.js$ # Host -Host: https://platform.text.com/docs/ +Host: https://platform.text.com/docs # Sitemaps Sitemap: https://platform.text.com/docs/sitemap.xml diff --git a/src/components/extensions/Placeholder.js b/src/components/extensions/Placeholder.js index dbd91c1eb..0bd070011 100644 --- a/src/components/extensions/Placeholder.js +++ b/src/components/extensions/Placeholder.js @@ -20,6 +20,11 @@ const placeholders = { label: "LiveChat Marketplace", url: "https://www.livechat.com/marketplace/", }, + DESIGN_SYSTEM_URL: { + type: "link", + label: "Design System", + url: "https://design.livechat.com/", + }, }; const Placeholder = ({ id }) => { diff --git a/src/configs/containers.json b/src/configs/containers.json index 064fcd0f9..5285d1a06 100644 --- a/src/configs/containers.json +++ b/src/configs/containers.json @@ -96,6 +96,10 @@ { "slug": "/extending-agent-app/product-cards/", "title": "Product Cards" + }, + { + "slug": "/extending-agent-app/developer-ui-toolkit/", + "title": "Developer UI Toolkit" } ] }, diff --git a/src/constants/index.js b/src/constants/index.js index e8a703186..77a4b2614 100644 --- a/src/constants/index.js +++ b/src/constants/index.js @@ -690,6 +690,7 @@ const EXCLUDED_SEARCH_RESULTS = [ "/messaging/apple-messages-for-business", "/management/configuration-api/v2.0", "/management/limits", + "/extending-agent-app/product-cards/" ]; // Some search results are unclear. Sometimes there's missing information diff --git a/src/pages/extending-agent-app/developer-ui-toolkit/index.mdx b/src/pages/extending-agent-app/developer-ui-toolkit/index.mdx new file mode 100644 index 000000000..94c48d6e4 --- /dev/null +++ b/src/pages/extending-agent-app/developer-ui-toolkit/index.mdx @@ -0,0 +1,603 @@ +--- +weight: 14 +category: "extending-agent-app" +title: "Developer UI Toolkit" +tagline: "Developer UI Toolkit with React components and views for Text Marketplace applications." +desc: "Build beatufiul and responsie applications with ready-to-use components and views that follow Text's design rules." +--- + +# Introduction + +Developer UI Toolkit is a TypeScript library with React components and views that should be used in applications built for Text Marketplace. It is available in the npm registry. + +The library is designed to help developers build beautiful and responsive applications that follow Text's design rules. All the views were built based on the components from the offical Text Design System. The Developer UI Toolkit extends the , providing new components that were designed specifically for 3rd party application use cases. + +# Components + +## LiveChat Details + +This module provides a context implementation for managing a LiveChat Details Widget using the LiveChat Agent App SDK in a React application. It includes tools for initializing and accessing the details widget and associated customer profile information, ensuring seamless integration within React components. + +### LiveChatDetailsProvider + +Type: `React.FC<{ children: React.ReactNode | ((context: LiveChatDetailsContext) => React.ReactNode), onSectionLoad?: () => ISection }>` + +A provider component that initializes the LiveChat Details Widget and supplies its context to child components. + +| Prop | Required | Type | Description | +| ---- | ---- | ---- | ----------- | +| `children` | Yes | React.ReactNode | ((context: LiveChatDetailsContext) => React.ReactNode) | Child components or a render function to access context values.| +| `onSectionLoad` | No | `() => ISection` | Callback function invoked when a section loads. | + + + +```js +import { LiveChatDetailsProvider } from './LiveChatDetailsContext'; + +const App = () => { + return ( + + + + ); +}; +``` + + +### useLiveChatDetails + +Type: `() => LiveChatDetailsContext` + +A custom hook to access the LiveChatDetailsContext. Ensures that the context is properly provided before usage. + + + +```js +import { useLiveChatDetails } from './LiveChatDetailsContext'; + +const CustomerDetails = () => { + const { widget, customerProfile } = useLiveChatDetails(); + + return ( +
+

Widget Name: {widget.name}

+ {customerProfile &&

Customer: {customerProfile.name}

} +
+ ); +}; +``` +
+ +### withLiveChatDetails + +Type: `(Component: React.ComponentType) => React.ComponentType` + +A higher-order component (HOC) that injects the `LiveChatDetailsContext` values (`widget` and `customerProfile`) into the wrapped component. + + + +```js +import { withLiveChatDetails } from './LiveChatDetailsContext'; + +const CustomerDetails = ({ widget, customerProfile }: LiveChatDetailsContext) => { + return ( +
+

Widget Name: {widget.name}

+ {customerProfile &&

Customer: {customerProfile.name}

} +
+ ); +}; + +export default withLiveChatDetails(CustomerDetails); +``` +
+ +### Context + +`LiveChatDetailsContext` + +Type: `React.Context` + +A React context that holds the details of the LiveChat Details Widget and the customer profile. + +| Prop | Type | Description | +| ---- | ---- | ----------- | +| `widget` | `IDetailsWidget` | The LiveChat Details Widget instance. | +| `customerProfile` | ICustomerProfile | null | The customer profile data, if available. | + +## LiveChat Fullscreen + +This module provides a context implementation for managing a LiveChat Fullscreen Widget using the LiveChat Agent App SDK in a React application. It includes tools for initializing and accessing the fullscreen widget, ensuring seamless integration within React components. + +### LiveChatFullscreenProvider + +Type: `React.FC<{ children: React.ReactNode | ((context: LiveChatFullscreenContext) => React.ReactNode) }>` + +A provider component that initializes the LiveChat Fullscreen Widget and supplies its context to child components. + +| Prop | Required | Type | Description | +| ---- | ---- | ---- | ----------- | +| `children` | Yes | React.ReactNode | ((context: LiveChatFullscreenContext) => React.ReactNode) | Child components or a render function to access context values.| + + + +```js +import { LiveChatFullscreenProvider } from './LiveChatFullscreenContext'; + +const App = () => { + return ( + + + + ); +}; +``` + + +### useLiveChatFullscreen + +Type: `() => LiveChatFullscreenContext` + +A custom hook to access the LiveChatFullscreenContext. Ensures that the context is properly provided before usage. + + + +```js +import { useLiveChatFullscreen } from './LiveChatFullscreenContext'; + +const FullscreenWidget = () => { + const { widget } = useLiveChatFullscreen(); + + return
Widget Name: {widget.name}
; +}; +``` +
+ +### withLiveChatFullscreen + +Type: `(Component: React.ComponentType) => React.ComponentType` + +A higher-order component (HOC) that injects the `LiveChatFullscreenContext` values (`widget`) into the wrapped component. + + + +```js +import { withLiveChatFullscreen } from './LiveChatFullscreenContext'; + +const FullscreenWidget = ({ widget }: LiveChatFullscreenContext) => { + return
Widget Name: {widget.name}
; +}; +``` +
+ +### Context + +`LiveChatFullscreenContext` + +Type: `React.Context` + +A React context that holds the details of the LiveChat Fullscreen Widget. + +| Prop | Type | Description | +| ---- | ---- | ----------- | +| `widget` | `IFullscreenWidget` | The LiveChat Fullscreen Widget instance. | + +## LiveChat Message Box + +This module provides a context implementation for managing a LiveChat MessageBox Widget using the LiveChat Agent App SDK in a React application. It includes tools for initializing and accessing the MessageBox widget and associated customer profile information, ensuring seamless integration within React components. + +### LiveChatMessageBoxProvider + +Type: `React.FC<{ children: React.ReactNode | ((context: LiveChatMessageBoxContext) => React.ReactNode) }>` + +A provider component that initializes the LiveChat MessageBox Widget and supplies its context to child components. + +| Prop | Required | Type | Description | +| ---- | ---- | ---- | ----------- | +| `children` | Yes | React.ReactNode | ((context: LiveChatMessageBoxContext) => React.ReactNode) | Child components or a render function to access context values.| + + + +```js +import { LiveChatMessageBoxProvider } from './LiveChatMessageBoxContext'; + +const App = () => { + return ( + + + + ); +}; +``` + + +### useLiveChatMessageBox + +Type: `() => LiveChatMessageBoxContext` + +A custom hook to access the LiveChatMessageBoxContext. Ensures that the context is properly provided before usage. + + + +```js +import { useLiveChatMessageBox } from './LiveChatMessageBoxContext'; + +const MessageBoxWidget = () => { + const { widget, customerProfile } = useLiveChatMessageBox(); + + return ( +
+

Widget Name: {widget.name}

+ {customerProfile &&

Customer: {customerProfile.name}

} +
+ ); +}; +``` +
+ +### withLiveChatMessageBox + +Type: `(Component: React.ComponentType) => React.ComponentType` + +A higher-order component (HOC) that injects the `LiveChatMessageBoxContext` values (`widget` and `customerProfile`) into the wrapped component. + + + +```js +import { withLiveChatMessageBox } from './LiveChatMessageBoxContext'; + +const MessageBoxWidget = ({ widget, customerProfile }: LiveChatMessageBoxContext) => { + return ( +
+

Widget Name: {widget.name}

+ {customerProfile &&

Customer: {customerProfile.name}

} +
+ ); +}; + +export default withLiveChatMessageBox(MessageBoxWidget); +``` +
+ +### Context + +`LiveChatMessageBoxContext` + +Type: `React.Context` + +A React context that holds the details of the LiveChat MessageBox Widget and the customer profile. + +| Prop | Type | Description | +| ---- | ---- | ----------- | +| `widget` | `IDetailsWidget` | The LiveChat MessageBox Widget instance. | +| `customerProfile` | ICustomerProfile | null | The customer profile data, if available. | + +## HelpDesk Details + +### HelpDeskDetailsProvider + +A provider component that initializes the HelpDesk widget and supplies its context to child components. + +| Prop | Required | Type | Description | +| ---- | ---- | ---- | ----------- | +| `children` | Yes | React.ReactNode | ((context: HelpDeskDetailsContext) => React.ReactNode) | Child components or a render function to access context values.| +| `onSectionLoad` | No | `() => ISection` | Callback function invoked when a section loads. | + + + +```js +import { HelpDeskDetailsProvider } from './HelpDeskDetailsContext'; + +const App = () => { + return ( + + + + ); +}; +``` + + +### withHelpDeskDetails + +A higher-order component (HOC) that injects the `HelpDeskDetailsContext` values (`widget` and `ticketInfo`) into the wrapped component. + + + +```js +import { withHelpDeskDetails } from './HelpDeskDetailsContext'; + +const TicketDetails = ({ widget, ticketInfo }: HelpDeskDetailsContext) => { + return ( +
+

Widget: {widget.name}

+ {ticketInfo &&

Ticket ID: {ticketInfo.id}

} +
+ ); +}; + +export default withHelpDeskDetails(TicketDetails); +``` +
+ +### useHelpDeskDetails + +A custom hook to access the `HelpDeskDetailsContext`. Ensures that the context is properly provided before usage. + + + +```js +import { useHelpDeskDetails } from './HelpDeskDetailsContext'; + +const TicketDetails = () => { + const { widget, ticketInfo } = useHelpDeskDetails(); + + return ( +
+

Widget: {widget.name}

+ {ticketInfo &&

Ticket ID: {ticketInfo.id}

} +
+ ); +}; +``` +
+ +### Context + +`HelpDeskDetailsContext` + +Type: `React.Context` + +A React context that holds the details of the HelpDesk widget and ticket information. + +| Prop | Type | Description | +| ---- | ---- | ----------- | +| `widget` | `IDetailsWidget` | Child components or a render function to access context values.| +| `ticketInfo` | ITicketInfo | null | Callback function invoked when a section loads. | + +## HelpDesk Fullscreen + +### HelpDeskFullscreenProvider + +A provider component that initializes the fullscreen widget and supplies its context to child components. + +| Prop | Required | Type | Description | +| ---- | ---- | ---- | ----------- | +| `children` | Yes | React.ReactNode | ((context: HelpDeskFullscreenContext) => React.ReactNode) | Child components or a render function to access context values.| + + + +```js +import { HelpDeskFullscreenProvider } from './HelpDeskFullscreenContext'; + +const App = () => { + return ( + + + + ); +}; +``` + + +### useHelpDeskFullscreen + +A custom hook to access the `HelpDeskFullscreenContext`. Ensures that the context is properly provided before usage. + + + +```js +import { useHelpDeskFullscreen } from './HelpDeskFullscreenContext'; + +const FullscreenWidget = () => { + const { widget } = useHelpDeskFullscreen(); + + return
Widget Name: {widget.name}
; +}; +``` +
+ +### withHelpDeskFullscreen + +A higher-order component (HOC) that injects the `HelpDeskFullscreenContext` values (`widget`) into the wrapped component. + + + +```js +import { withHelpDeskFullscreen } from './HelpDeskFullscreenContext'; + +const FullscreenWidget = ({ widget }: HelpDeskFullscreenContext) => { + return
Widget Name: {widget.name}
; +}; + +export default withHelpDeskFullscreen(FullscreenWidget); +``` +
+ +### Context + +`HelpDeskFullscreenContext` + +Type: `React.Context` + +A React context that holds the details of the HelpDesk fullscreen widget. + +| Prop | Type | Description | +| ---- | ---- | ----------- | +| `widget` | `IFullscreenWidget` | Child components or a render function to access context values.| + + +## Best practices + +
    +
  • Always wrap components needing access to ...Context with ...Provider.
  • +
  • Use the use... hook for function components to simplify accessing context values.
  • +
  • Utilize the with... HOC for class components or components that prefer HOC patterns.
  • +
+ +## Error handling +
    +
  • Missing Context: The use... hook and the with... HOC throw an error if the ...Context is not wrapping the component tree.
  • +
  • Initialization Errors: If the widget initialization fails, the ...Provider renders an AppError component with an error message.
  • +
  • Loading State: During widget initialization, an AppLoader component is displayed.
  • +
+ +# Views + +## Loading view + +Loading view was created to unify the loading state among applications, therefore it doesn't leave much room for customization. It's a simple view with a loading spinner and a message that says `Loading an external application...`. + +| Prop | Required | Type | Description | +| ---- | ---- | ---- | ----------- | +| `label` | No | `string` | A message that will be displayed below the loading spinner.
Default: `Loading application...`
In general, the default copy shouldn't be changed unless you're using this component to load some part of your application.| + + + +```js +import { AppLoader } from '@livechat/developer-ui-react'; + +const Loader = () => ( +
+ +
+); +``` + +
+ + +# Errors + +The Details Error View is a standardized error component designed to display errors in applications. This component ensures consistency in error handling and provides users with a clear and professional experience when issues arise. + +The error message displayed by the Details Error View is a default copy meant to communicate a failure in loading the details view. It helps users understand that something went wrong without overwhelming them with technical details. + +## Details error view + + + +```js +import { AppDetailsError } from '@livechat/developer-ui-react'; + +const DetailsError = () => ( + +); +``` + + + +## Fullscreen error view + + + +```js +import { AppFullscreenError } from '@livechat/developer-ui-react'; + +const FullscreenError = () => ( + +); +``` + + + +## Message Box error view + + + +```js +import { AppMessageBoxError } from '@livechat/developer-ui-react'; + +const MessageBoxError = () => ( + +); +``` + + + + +## Settings error view + + + +```js +import { AppSettingsError } from '@livechat/developer-ui-react'; + +const SettingsError = () => ( + +); +``` + + + + +# Success + +## Success view + +The Success view component is used to display a success message to the user after the successful installation of the application. It shows the application logo and relevant details to inform the user that the process was completed successfully. + +| Prop | Required | Type | Description | +| ---- | ---- | ---- | ----------- | +| `appId` | yes | `string` | The ID of your application. | +| `icon` | yes | `React.ReactNode` | The icon that will be displayed in the success view. | +| `product` | no |'livechat' | 'helpdesk'| The product that the application is integrated with.
Default: 'livechat' | + +React component: + + +```js +import { AppSuccessPage } from '@livechat/developer-ui-react'; +import { ReactComponent as AppLogo } from './app-logo.svg'; + +const SuccessView = () => ( + } product="livechat" /> +); +``` + + +Next component: + + +```js +import { AppSuccessPage } from '@livechat/developer-ui-react'; +import AppLogo from './app-logo.svg'; +import Image from 'next/image'; + +const SuccessView = () => ( + } product="livechat" /> +); +``` + + + diff --git a/src/pages/extending-agent-app/product-cards/index.mdx b/src/pages/extending-agent-app/product-cards/index.mdx index e41d2afaa..3feebe432 100644 --- a/src/pages/extending-agent-app/product-cards/index.mdx +++ b/src/pages/extending-agent-app/product-cards/index.mdx @@ -4,6 +4,7 @@ category: "extending-agent-app" title: "Product Cards" tagline: "Create a backend service to connect your store with the Product Cards app." desc: "Connect your store with the Product Cards app, and send product recommendations without leaving LiveChat." +hidden: true --- # Introduction