docs(widget): add new parameters of widget in docs (#3292)

* feat(widget): flat widget settings config * docs(widget): add new parameters of widget in docs * chore: app key docs * chore: fix configurator styles * chore: exclude configurator from service-worker * chore: revert * chore: rename const
cowprotocol · Oct 31, 2023 · 0bc7d99 · 0bc7d99
1 parent 4cd3b9c
commit 0bc7d99
Show file tree

Hide file tree

Showing 7 changed files with 60 additions and 59 deletions.
diff --git a/apps/cowswap-frontend/src/legacy/theme/mapWidgetTheme.ts b/apps/cowswap-frontend/src/legacy/theme/mapWidgetTheme.ts
@@ -1,10 +1,10 @@
-import type { InjectedWidgetPalette } from '@cowprotocol/widget-lib'
+import type { CowSwapWidgetPalette } from '@cowprotocol/widget-lib'
 
 import { css, DefaultTheme } from 'styled-components/macro'
 
 // Map the provided data from consumer to styled-components theme
 export function mapWidgetTheme(
-  widgetTheme: InjectedWidgetPalette | undefined,
+  widgetTheme: CowSwapWidgetPalette | undefined,
   defaultTheme: DefaultTheme
 ): DefaultTheme {
   if (!widgetTheme) return defaultTheme

diff --git a/apps/cowswap-frontend/src/modules/injectedWidget/hooks/useInjectedWidgetPalette.ts b/apps/cowswap-frontend/src/modules/injectedWidget/hooks/useInjectedWidgetPalette.ts
@@ -1,9 +1,9 @@
-import type { InjectedWidgetPalette } from '@cowprotocol/widget-lib'
+import type { CowSwapWidgetPalette } from '@cowprotocol/widget-lib'
 
 import { useInjectedWidgetParams } from './useInjectedWidgetParams'
 
 // The theme palette provided by a consumer
-export function useInjectedWidgetPalette(): InjectedWidgetPalette | undefined {
+export function useInjectedWidgetPalette(): CowSwapWidgetPalette | undefined {
   const state = useInjectedWidgetParams()
 
   return state.palette

diff --git a/apps/widget-configurator/src/app/configurator/controls/CurrentTradeTypeControl.tsx b/apps/widget-configurator/src/app/configurator/controls/CurrentTradeTypeControl.tsx
@@ -9,19 +9,20 @@ import Select from '@mui/material/Select'
 
 import { TRADE_MODES } from '../consts'
 
+const LABEL = 'Current trade type'
+
 export function CurrentTradeTypeControl({ state }: { state: [TradeType, Dispatch<SetStateAction<TradeType>>] }) {
   const [tradeType, setTradeType] = state
 
   return (
     <FormControl sx={{ width: '100%' }}>
-      <InputLabel id="select-trade-type">Current trade type</InputLabel>
+      <InputLabel>{LABEL}</InputLabel>
       <Select
-        labelId="select-trade-type-label"
         id="select-trade-type"
         value={tradeType}
         onChange={(event) => setTradeType(event.target.value as TradeType)}
         autoWidth
-        label="Trade type"
+        label={LABEL}
         size="small"
       >
         {TRADE_MODES.map((option) => (

diff --git a/apps/widget-configurator/src/app/configurator/controls/TradeModesControl.tsx b/apps/widget-configurator/src/app/configurator/controls/TradeModesControl.tsx
@@ -10,6 +10,7 @@ import MenuItem from '@mui/material/MenuItem'
 import OutlinedInput from '@mui/material/OutlinedInput'
 import Select, { SelectChangeEvent } from '@mui/material/Select'
 
+const LABEL = 'Trade Modes'
 export function TradeModesControl({ state }: { state: [TradeType[], Dispatch<SetStateAction<TradeType[]>>] }) {
   const [tradeModes, setTradeModes] = state
   const handleTradeModeChange = (event: SelectChangeEvent<TradeType[]>) => {
@@ -20,15 +21,14 @@ export function TradeModesControl({ state }: { state: [TradeType[], Dispatch<Set
 
   return (
     <FormControl sx={{ width: '100%' }}>
-      <InputLabel id="trade-mode-label">Trade Modes</InputLabel>
+      <InputLabel>{LABEL}</InputLabel>
       <Select
-        labelId="trade-mode-label"
         id="trade-mode-select"
         multiple
         size="small"
         value={tradeModes}
         onChange={handleTradeModeChange}
-        input={<OutlinedInput id="trade-mode-select-outlined" label="Available trade modes" />}
+        input={<OutlinedInput id="trade-mode-select-outlined" label={LABEL} />}
         renderValue={(selected) => selected.join(', ')}
       >
         {Object.values(TradeType).map((option) => (

diff --git a/libs/widget-lib/docs/README.md b/libs/widget-lib/docs/README.md
@@ -4,9 +4,9 @@ Integrate the power of `CowSwap` into your product!
 With the widget, you can create an incredible trading interface. Specify the required pair of currencies, customize the
 look and much more!
 
-[![Demo](./demo-preview.png)](https://www.youtube.com/watch?v=gxRRH9Rumx4&ab_channel=CoWSwap)
+Create your own widget using the configurator https://swap.cow.fi/widget-configurator/
 
-> [Watch the demo](https://www.youtube.com/watch?v=gxRRH9Rumx4&ab_channel=CoWSwap)
+![Demo](./demo-preview.png)
 
 ## Install
 
@@ -21,28 +21,31 @@ npm install @cowprotocol/widget-lib
 ## Quick start
 
 ```typescript
-import { cowSwapWidget, CowSwapWidgetParams, CowSwapWidgetSettings } from '@cowprotocol/widget-lib'
+import {cowSwapWidget, CowSwapWidgetParams, CowSwapWidgetSettings} from '@cowprotocol/widget-lib'
 
 // Initialise the widget
 const widgetContainer = document.getElementById('cowswap-widget')
 
 const params: CowSwapWidgetParams = {
   container: widgetContainer,
-  metaData: { appKey: 'YOUR_APP_ID', url: 'https://YOUR_APP_URL' },
+  metaData: {appKey: 'YOUR_APP_ID', url: 'https://YOUR_APP_URL'},
   width: 600,
   height: 640,
 }
 
 const settings: CowSwapWidgetSettings = {
-  urlParams: {
-    sell: { asset: 'DAI' },
-    buy: { asset: 'USDC', amount: '0.1' }
-  }
+  sell: {asset: 'DAI'},
+  buy: {asset: 'USDC', amount: '0.1'}
 }
 
 cowSwapWidget(params, settings)
 ```
 
+## App key
+You must specify the `appKey` parameter when initializing the widget. This parameter is used to identify the source of orders.  
+The key must be a UTF8 string of up to 50 chars.  
+It will be a part of orders meta-data, see more in the [CoW Protocol Docs](https://docs.cow.fi/front-end/creating-app-ids/create-the-order-meta-data-file/appcode).
+
 ## Wallet provider
 
 You can pass the wallet provider from your application to seamlessly use the widget as part of your application.
@@ -70,11 +73,11 @@ interface JsonRpcRequest {
 An example of connecting a widget to Metamask:
 
 ```typescript
-import { cowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-lib'
+import {cowSwapWidget, CowSwapWidgetParams} from '@cowprotocol/widget-lib'
 
 const params: CowSwapWidgetParams = {
   container: document.getElementById('cowswap-widget'),
-  metaData: { appKey: 'YOUR_APP_ID', url: 'https://YOUR_APP_URL' },
+  metaData: {appKey: 'YOUR_APP_ID', url: 'https://YOUR_APP_URL'},
   width: 600,
   height: 640,
   provider: window.ethereum // <-------
@@ -97,22 +100,26 @@ cowSwapWidget(params, {})
 
 ### `CowSwapWidgetSettings`
 
-| Parameter   | Type                     | Description                                                                                                                     |
-|-------------|--------------------------|---------------------------------------------------------------------------------------------------------------------------------|
-| `urlParams` | `CowSwapWidgetUrlParams` | The URL parameters of the widget, including chain information, trade type, environment, assets, and theme.                      |
-| `appParams` | `CowSwapWidgetAppParams` | (Optional) The application parameters of the widget, including the logo URL and flags for hiding the logo and network selector. |
-
-### `CowSwapWidgetUrlParams`
-
-| Parameter     | Type               | Description                                                                                |
-|---------------|--------------------|--------------------------------------------------------------------------------------------|
-| `chainId`     | `number`           | The blockchain ID on which the trade will take place.                                      |
-| `tradeType`   | `string`           | The type of trade. Can be `swap` or `limit-orders`.                                        |
-| `env`         | `CowSwapWidgetEnv` | The environment of the widget (`'local'` or `'prod'`).                                     |
-| `theme`       | `CowSwapTheme`     | (Optional) The theme of the widget (`'dark'` for dark theme or `'light'` for light theme). |
-| `tradeAssets` | `TradeAssets`      | (Optional) An object containing information about the selling and buying assets.           |
+| Parameter              | Type                   | Description                                                                                                                                                  |
+|------------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `chainId`              | `number`               | The blockchain ID on which the trade will take place.                                                                                                        |
+| `tradeType`            | `string`               | The type of trade. Can be `swap` or `limit-orders`.                                                                                                          |
+| `env`                  | `CowSwapWidgetEnv`     | The environment of the widget (`'local'` or `'prod'`).                                                                                                       |
+| `tradeAssets`          | `TradeAssets`          | (Optional) An object containing information about the selling and buying assets.                                                                             |
+| `theme`                | `CowSwapTheme`         | (Optional) The theme of the widget (`'dark'` for dark theme or `'light'` for light theme).                                                                   |
+| `logoUrl`              | `boolean`              | (Optional) The width of the widget in pixels.                                                                                                                |
+| `hideLogo`             | `boolean`              | (Optional) The height of the widget in pixels.                                                                                                               |
+| `hideNetworkSelector`  | `boolean`              | (Optional) Disables an opportunity to change the network from the widget UI.                                                                                 |
+| `dynamicHeightEnabled` | `boolean`              | (Optional) Dynamically changes the height of the iframe depending on the content.                                                                            |
+| `enabledTradeTypes`    | `Array<TradeType>`     | (Optional) CowSwap provides three trading widgets: swap, limit and twap orders. Using this option you can narrow down the list of available trading widgets. |
+| `palette`              | `CowSwapWidgetPalette` | (Optional) Using the palette you can customize the appearance of the widget. For example, you can change the main color of the background and text.          |
 
 ```typescript
+export interface CowSwapWidgetMetaData {
+  appKey: string
+  url: string
+}
+
 interface TradeAsset {
   asset: string
   amount?: string
@@ -122,15 +129,20 @@ export interface TradeAssets {
   sell: TradeAsset
   buy: TradeAsset
 }
-```
 
-### `CowSwapWidgetAppParams`
+export enum TradeType {
+  SWAP = 'swap',
+  LIMIT = 'limit',
+  ADVANCED = 'advanced',
+}
 
-| Parameter             | Type      | Description                                          |
-|-----------------------|-----------|------------------------------------------------------|
-| `logoUrl`             | `boolean` | The width of the widget in pixels.                   |
-| `hideLogo`            | `boolean` | The height of the widget in pixels.                  |
-| `hideNetworkSelector` | `boolean` | The container in which the widget will be displayed. |
+export interface CowSwapWidgetPalette {
+  primaryColor: string
+  screenBackground: string
+  widgetBackground: string
+  textColor: string
+}
+```
 
 ## Widget updating
 
@@ -148,22 +160,16 @@ const params: CowSwapWidgetParams = {
 
 
 const settings: CowSwapWidgetSettings = {
-  appParams: {
-    logoUrl: 'YOUR_LOGO_URL'
-  }
+  logoUrl: 'YOUR_LOGO_URL'
 }
 
 const updateWidget = cowSwapWidget(params, settings)
 
 // Update the widget
 updateWidget({
-  urlParams: {
-    theme: 'dark', // <- Change theme to dark
-  },
-  appParams: {
-    ...settings.appParams,
-    hideNetworkSelector: true // <- Hide the network selector
-  },
+  ...settings,
+  theme: 'dark', // <- Change theme to dark
+  hideNetworkSelector: true // <- Hide the network selector
 })
 ```
 
@@ -176,9 +182,3 @@ An example of URL:
 ```
 https://swap.cow.fi/#/100/swap/WXDAI/GNO?sellAmount=200&theme=dark
 ```
-
-## Backlog
-
-1. [ ] Customizing the theme palette
-2. [ ] Set custom tokens list from URL or JSON
-3. [ ] Forward integrator meta-data to Appzi
diff --git a/libs/widget-lib/docs/demo-preview.png b/libs/widget-lib/docs/demo-preview.png
diff --git a/libs/widget-lib/src/types.ts b/libs/widget-lib/src/types.ts
@@ -39,7 +39,7 @@ export interface CowSwapWidgetUrlParams {
   theme?: CowSwapTheme
 }
 
-export interface InjectedWidgetPalette {
+export interface CowSwapWidgetPalette {
   primaryColor: string
   screenBackground: string
   widgetBackground: string
@@ -52,7 +52,7 @@ export interface CowSwapWidgetAppParams {
   hideNetworkSelector?: boolean
   dynamicHeightEnabled?: boolean
   enabledTradeTypes?: TradeType[]
-  palette?: InjectedWidgetPalette
+  palette?: CowSwapWidgetPalette
 }
 
 export type CowSwapWidgetSettings = CowSwapWidgetUrlParams & CowSwapWidgetAppParams