From 68178585693f961c4a19ab99c8b6e2d0ef106cf1 Mon Sep 17 00:00:00 2001
From: Andrew Baldwin <andrew.baldwin44@gmail.com>
Date: Thu, 18 Jul 2024 14:34:10 -0400
Subject: [PATCH] Update README

---
 locust/webui/README.md | 147 +++++++++++++++++++++++++++++------------
 1 file changed, 103 insertions(+), 44 deletions(-)

diff --git a/locust/webui/README.md b/locust/webui/README.md
index 185e1610f4..95876f0864 100644
--- a/locust/webui/README.md
+++ b/locust/webui/README.md
@@ -20,35 +20,39 @@ yarn add locust-ui
 ```js
 import LocustUi from "locust-ui";
 
-<LocustUi<"content-length", "content_length">
-    extendedTabs={[
-        {
-            title: "Content Length",
-            key: "content-length",
-        },
-    ]}
-    extendedTables={[
-        {
-        key: "content-length",
-        structure: [
-            { key: "name", title: "Name" },
-            { key: "content_length", title: "Total content length" },
-        ],
-        },
-    ]}
-    extendedReports={[
-        {
-            href: "/content-length/csv",
-            title: "Download content length statistics CSV",
-        },
-    ]}
-    extendedStats={[
-        {
-            key: "content-length",
-            data: [{ name: "/", safeName: "/", content_length: "123" }],
-        },
-    ]}
-/>
+function App() {
+    return (
+        <LocustUi<"content-length", "content_length">
+            extendedTabs={[
+                {
+                    title: "Content Length",
+                    key: "content-length",
+                },
+            ]}
+            extendedTables={[
+                {
+                    key: "content-length",
+                    structure: [
+                        { key: "name", title: "Name" },
+                        { key: "content_length", title: "Total content length" },
+                    ],
+                },
+            ]}
+            extendedReports={[
+                {
+                    href: "/content-length/csv",
+                    title: "Download content length statistics CSV",
+                },
+            ]}
+            extendedStats={[
+                {
+                    key: "content-length",
+                    data: [{ name: "/", safeName: "/", content_length: "123" }],
+                },
+            ]}
+        />
+    )
+}
 ```
 
 For Locust to be able to pass data to your React frontend, place the following script tag in your html template file:
@@ -58,25 +62,15 @@ For Locust to be able to pass data to your React frontend, place the following s
 </script>
 ```
 
-The Locust UI package exports a Redux store. By wrapping your App in a Redux provider, you may be able to read Locust data from state:
-```js
-import { locustStore } from "locust-webui";
-import { Provider } from "react-redux";
-
-ReactDOM.createRoot(document.getElementById("root")!).render(
-    <React.StrictMode>
-        <Provider store={locustStore}>
-            <App />
-        </Provider>
-    </React.StrictMode>
-);
-```
-
 Lastly, you must configure Locust to point to your own React build output. To achieve this, you can use the flag `--build-path` and provide the **absolute** path to your build directory.
 
+```sh
+locust -f locust.py --build-path /home/user/custom-webui/dist
+```
+
 For more on configuring Locust see [the Locust docs](https://docs.locust.io/en/stable/configuration.html).
 
-### Options
+### Customizing Tabs
 By default, the extended tabs will display the provided data in a table. However you may choose to render any React component in the tab:
 ```js
 import { IRootState } from "locust-webui";
@@ -97,6 +91,71 @@ const extendedTabs = {[
         component: MyCustomTab
     },
 ]};
+
+function App() {
+    return (
+        <LocustUi extendedTabs={extendedTabs} />
+    )
+}
+```
+
+The `tabs` prop allows for complete control of which tabs are rendered. You can then customize which base tabs are shown or where your new tab should be placed:
+```js
+import LocustUi, { baseTabs } from "locust-ui";
+
+const tabs = [...baseTabs];
+tabs.splice(2, 0, {
+  title: "Custom Tab",
+  key: "custom-tab",
+  component: MyCustomTab,
+});
+
+function App() {
+    return (
+        <LocustUi tabs={tabs} />
+    )
+}
+```
+
+### API
+**Tab**
+```js
+{
+    title: string; // **Required** Any string for display purposes
+    key: string; // **Required** Programatic key used in extendedTabs to find corresponding stats and tables
+    component: // **Optional** React component to render
+    shouldDisplayTab: // **Optional** Function provided with Locust redux state to output boolean
+}
+```
+**Extended Stat**
+```js
+{
+    key: string; // **Required** Programatic key that must correspond to a tab key
+    data: {
+        [key: string]: string; // The key must have a corresponding entry in the extended table structure. The value corresponds to the data to be displayed
+    }[];
+}
+```
+**Extended Table**
+```js
+{
+    key: string; // **Required** Programatic key that must correspond to a tab key
+    structure: {
+        key: string; // **Required** key that must correspond to a key in the extended stat data object
+        title: string; // **Required** Corresponds to the title of the column in the table
+    }[]
+}
+```
+**Locust UI**
+```js
+// Provide the types for your extended tab and stat keys to get helpful type hints
+<LocustUI<ExtendedTabType, StatKey>
+    extendedTabs={/* Optional array of extended tabs */}
+    extendedTables={/* Optional array of extended tables */}
+    extendedReports={/* Optional array of extended reports */}
+    extendedStats={/* Optional array of extended stats */}
+    tabs={/* Optional array of tabs that will take precedence over extendedTabs */}
+/>
 ```