[docs] Toolpad docs part 1

docs/README.md

@@ -12,9 +12,11 @@ If you do not have yarn installed, select your OS and follow the instructions on
 
 _DO NOT USE NPM, use Yarn to install the dependencies._
 
+Visit the [MUI Toolpad documentation](https://mui.com/toolpad/getting-started/overview/).
+
 ## How can I add a new demo to the documentation?
 
-[You can follow this guide](https://github.com/mui/material-ui/blob/HEAD/CONTRIBUTING.md)
+Please follow the [contributing guidelines](https://github.com/mui/material-ui/blob/HEAD/CONTRIBUTING.md).
 on how to get started contributing to MUI.
 
 ## How do I help to improve the translations?

docs/data/pages.ts

@@ -3,23 +3,69 @@ import type { MuiPage } from '@mui/monorepo/docs/src/MuiPage';
 const pages: MuiPage[] = [
   {
     pathname: '/toolpad/getting-started',
-    title: 'Getting started',
-    icon: 'CreateIcon',
+    icon: 'DescriptionIcon',
     children: [
-      { pathname: '/toolpad/getting-started/setup' },
-      { pathname: '/toolpad/getting-started/tutorial', title: 'Tutorial' },
+      { pathname: '/toolpad/getting-started/overview' },
+      { pathname: '/toolpad/getting-started/quickstart' },
     ],
   },
   {
-    pathname: '/toolpad/data-fetching',
+    pathname: '/toolpad/connecting-to-datasources',
     icon: 'TableViewIcon',
     children: [
-      { pathname: '/toolpad/data-fetching', title: 'Overview' },
-      { pathname: '/toolpad/data-fetching/rest', title: 'REST API' },
-      { pathname: '/toolpad/data-fetching/google-sheets', title: 'Google Sheets' },
-      { pathname: '/toolpad/data-fetching/queries' },
+      {
+        pathname: '/toolpad/connecting-to-datasources/queries',
+      },
+      {
+        pathname: '/toolpad/connecting-to-datasources/connections',
+      },
+      {
+        pathname: '/toolpad/connecting-to-datasources/fetch',
+        title: 'Fetch datasource',
+      },
+      {
+        pathname: '/toolpad/connecting-to-datasources/function',
+        title: 'Function datasource',
+      },
+      {
+        pathname: '/toolpad/connecting-to-datasources/google-sheets',
+        title: 'Google Sheets datasource',
+      },
+      {
+        pathname: '/toolpad/connecting-to-datasources/postgre-sql',
+        title: 'PostgreSQL datasource',
+      },
     ],
   },
+  {
+    pathname: '/toolpad/building-ui',
+    title: 'Building UI [TODO]',
+    icon: 'VisibilityIcon',
+    children: [
+      {
+        pathname: '/toolpad/building-ui/build-in-components',
+      },
+    ],
+  },
+  {
+    pathname: '/toolpad/data-binding',
+    icon: 'CodeIcon',
+  },
+  {
+    pathname: '/toolpad/versioning-and-deploying',
+    title: 'Versioning & deploying [TODO]',
+    icon: 'ToggleOnIcon',
+    children: [
+      {
+        pathname: '/toolpad/versioning-and-deploying/releases',
+      },
+    ],
+  },
+  {
+    pathname: '/toolpad/faq',
+    title: 'FAQ [TODO]',
+    icon: 'ReaderIcon',
+  },
 ];
 
 export default pages;

docs/data/toolpad/connecting-to-datasources/connections.md

@@ -0,0 +1,86 @@
+# Connections
+
+<p class="description">A connection instance lets you reuse certain configuration details to create queries faster.</p>
+
+To create a new connection instance, press the **+** button in the Explorer menu on the left side of the interface:
+
+<img src="/static/toolpad/docs/connection.png" alt="Add connection" width="196px" />
+
+## Connection types
+
+There are 2 kinds of data sources that do not require a connection instance:
+
+### Function
+
+<img src="/static/toolpad/docs/connection-function-1.png" alt="Connection function" width="730px" />
+
+You can define secrets (key/value) that can later be accessed in the function datasource query:
+
+<img src="/static/toolpad/docs/connection-function-2.png" alt="Connection function" width="748px" />
+
+### Fetch
+
+<img src="/static/toolpad/docs/connection-fetch-1.png" alt="Connection fetch" width="723px" />
+
+You can configure:
+
+- **base url** - url that can be shared between different queries.
+- **Headers** - pass custom headers with each request.
+- **Authentication** type - if your API is protected choose the authentication method that fits your needs:
+  - **Basic** - adds authorization header and generates base64 encoded value for a given user credentials.
+  - **Bearer token** - adds authorization header generates value for provided token.
+  - **API key** - adds key/value header.
+
+There are 2 datasources that require a connection instance:
+
+### Google Sheets
+
+**Obtain credentials**
+
+Before you create a Google Sheets connection you must first configure Toolpad app by providing Google Sheets **client ID** and **client secret**:
+
+1. Create a new Google Cloud project - [instructions](https://cloud.google.com/resource-manager/docs/creating-managing-projects#creating_a_project).
+
+2. Generate Oauth 2.0 credentials - [instructions](https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred).
+
+3. Start Toolpad with following environment variables:
+
+   ```sh
+   TOOLPAD_EXTERNAL_URL=<YOUR_APP_URL>
+   TOOLPAD_DATASOURCE_GOOGLESHEETS_CLIENT_ID=
+   TOOLPAD_DATASOURCE_GOOGLESHEETS_CLIENT_SECRET=
+   ```
+
+   where YOUR_APP_URL is the URL Toolpad is hosted on.
+
+4. Add the following URIs under Authorized Redirect URIs:
+   ```sh
+   https://<YOUR_APP_URL>/api/dataSources/googleSheets/auth/callback</YOUR_APP_URL>
+   ```
+5. Enable the Google Sheets and Google Drive APIs for the project - [instructions](https://developers.google.com/identity/protocols/oauth2/web-server#enable-apis).
+
+**Connect your google account**
+
+1. Once you create Google Sheets type connection click **CONNECT** button:
+
+<img src="/static/toolpad/docs/connection-sheets-1.png" alt="Connection Google Sheets" width="724px" />
+
+1. Choose the Google account that you want to authorize.
+
+1. Grant access to your Google Drive files by clicking **Allow**.
+
+1. Once you successfully connect your account you should see a button stating the account that was connected.
+
+<img src="/static/toolpad/docs/connection-sheets-2.png" alt="Google Sheets connected" width="721px" />
+
+### PostgreSQL
+
+To query data from a PostgreSQL database, you must configure the connection:
+
+<img src="/static/toolpad/docs/connection-postgres-1.png" alt="Connection postgres" width="726px" />
+
+Provide the database credentials and click **TEST CONNECTION** to verify that you're able to connect.
+
+If everything is correct, click **SAVE** to complete the connection.
+
+Learn more in the [PostgreSQL documentation](/toolpad/connecting-to-datasources/postgre-sql/).

docs/data/toolpad/connecting-to-datasources/fetch.md

@@ -0,0 +1,35 @@
+# Fetch datasource
+
+<p class="description">Fetch datasource is the easiest and fastest way to load external data within Toolpad app.</p>
+
+## Working with fetch
+
+As explained in the [connections](/toolpad/connecting-to-datasources/connections/) section you can either create a reusable connection or simply create a new query and put all connection details inline:
+
+1. Choose **ADD QUERY** in the **Inspector** on the right.
+
+1. Select fetch datasource and click **CREATE QUERY**:
+
+   <img src="/static/toolpad/docs/fetch-query-1.png" alt="Fetch datasource" width="478px" />
+
+1. You can modify all the basic configuration settings as described in [queries](/toolpad/connecting-to-datasources/queries/) section.
+
+1. In addition you can configuration following properties inline:
+
+   <img src="/static/toolpad/docs/fetch-query-2.png" alt="Fetch configuration" width="886px" />
+   <br />
+
+   - **HTTP method** - by default GET is used, but we also support POST, PUT, DELETE, PATCH and HEAD methods.
+   - **url** - is an endpoint to which requests will be made. We also have an option to dynamically generate url by using [data binding](/toolpad/data-binding/). **Parameters** can be accessed by using **query** object inside url data binding editor.
+   - **parameters** - allows us to use [data bound](/toolpad/data-binding/) properties which can then be used construct dynamic **url** value.
+
+   <img src="/static/toolpad/docs/fetch-query-3.png" alt="Dynamic url" width="702px" />
+
+1. Knowing that data comes in a different shapes we provide an easy way to **transform response**:
+
+   - Simply enable option by checking **Transform response**.
+   - Then modify which properties of data object should be returned as a final response.
+
+   <img src="/static/toolpad/docs/fetch-query-4.png" alt="Transform response" width="431px" />
+
+1. Once finished with configuration click **SAVE** to commit your changes and return to the canvas.

docs/data/toolpad/connecting-to-datasources/function.md

@@ -0,0 +1,65 @@
+# Function datasource
+
+<p class="description">Function datasource is an advanced way to make request from Toolpad app.</p>
+
+## Working with functions
+
+As explained in the [connections](/toolpad/connecting-to-datasources/connections/) section you can either create a reusable connection or simply create a new query and put all connection details inline:
+
+1. Choose **ADD QUERY** in the **Inspector** on the right.
+
+1. Select function datasource and click **CREATE QUERY**:
+
+   <img src="/static/toolpad/docs/function-query-1.png" alt="Function datasource" width="476px" />
+
+1. You can modify all the basic configuration settings as described in [queries](/toolpad/connecting-to-datasources/queries/) section.
+
+1. In addition you are now presented with a **code editor** where you can write a custom code for data fetching:
+
+   <img src="/static/toolpad/docs/function-query-2.png" alt="Function configuration" width="888px" />
+
+   Supported features:
+
+   - Subset of webplatform APIs:
+
+     - fetch (Request, Response)
+     - AbortController
+     - console (.log, .debug, .info, .warn, .error)
+     - setTimeout, clearTimeout
+     - TextEncoder, TextDecoder
+     - ReadableStream
+
+   - Access outside variables by binding parameters fields.
+   - Console and Network tabs for an easier debugging.
+
+   Current limitations:
+
+   - You can not import modules.
+
+1. Once finished with configuration click **SAVE** to commit your changes and return to the canvas.
+
+## Use cases
+
+While [function](/toolpad/connecting-to-datasources/function/) datasource can suffice for many different setups we found some advances use cases where limitations of function datasource starts surfacing and prevents us from building more complex data access queries.
+
+1. **Pre-processing** request:
+
+   You can execute extra steps before doing an actual request in case you need to do some pre-processing. I.e. sending parameters as a BASE64 encoded data:
+
+   <img src="/static/toolpad/docs/function-query-3.png" alt="Function pre-processing" width="790px" style="margin-bottom: 16px;" />
+
+1. **Fetching** data from **multiple data sources** and **combining** the result:
+
+   <img src="/static/toolpad/docs/function-query-4.png" alt="Function combined result" width="814px" />
+
+1. **Chaining** multiple request:
+
+   In this example you might want to fetch name of the top contributor of **mui/materual-ui** repository, in order to do that you first need to fetch a list of contributors for a given repo. Once you have a response and link to a top contributor you can do a follow up request to fetch details about specific user:
+
+   <img src="/static/toolpad/docs/function-query-5.png" alt="Function chained" width="944px" />
+
+1. **Custom error handling**:
+
+   You can handle different error scenarios. I.e. if 404 error is returned you can still pass empty array so that UI does not break:
+
+   <img src="/static/toolpad/docs/function-query-6.png" alt="Function error handling" width="706px" />

docs/data/toolpad/connecting-to-datasources/google-sheets.md

@@ -0,0 +1,29 @@
+# Google Sheets datasource
+
+<p class="description">Google Sheets datasource allows fetching data from Google Sheets living in your Google Drive.</p>
+
+## Working with Google Sheets
+
+1. Create a new Google Sheets connection as explained in the [instructions](/toolpad/connecting-to-datasources/connections/#google-sheets).
+
+1. Once your connection is ready click on **ADD QUERY** in the **Inspector** on the right.
+
+1. Select Google Sheets datasource and click **CREATE QUERY**:
+
+   <img src="/static/toolpad/docs/google-sheets-query-1.png" alt="Google Sheets type" width="595px" style="margin-bottom: 16px;" />
+
+1. You can modify all the basic configuration settings as described in [queries](/toolpad/connecting-to-datasources/queries/) section.
+
+1. In addition you can configure following properties inline:
+
+   <img src="/static/toolpad/docs/google-sheets-query-2.png" alt="Google Sheets configuration" width="1108px" />
+
+   - **Select spreadsheet** - browse for a spreadsheet that you own or that is shared with you.
+
+   - **Select sheet** - choose a spreadsheet's sheet from which you want to pull the data.
+
+   - **Range** - select a range of cells from which the data should be pulled.
+
+   - **First row contains column headers** - enable this setting if you would like to use names defined in a header row as the name for object keys in a response.
+
+1. Once finished with configuration click **SAVE** to commit your changes and return to the canvas.

docs/data/toolpad/connecting-to-datasources/postgre-sql.md

@@ -0,0 +1,31 @@
+# PostgreSQL datasource
+
+<p class="description">PostgreSQL datasource allows fetching data straight from PostgreSQL database.</p>
+
+## Working with PostgreSQL
+
+1. Create a new PostgreSQL connection as explained in the [instructions](/toolpad/connecting-to-datasources/connections/#postgresql).
+
+1. Once your connection is ready click on **ADD QUERY** in the **Inspector** on the right.
+
+1. Select PostgreSQL datasource and click **CREATE QUERY**:
+
+   <img src="/static/toolpad/docs/postgres-query-1.png" alt="Postgres type" width="593px" style="margin-bottom: 16px;" />
+
+1. You can modify all the basic configuration settings as described in [queries](/toolpad/connecting-to-datasources/queries/) section.
+
+1. In addition you can configure following properties inline:
+
+   <img src="/static/toolpad/docs/postgres-query-2.png" alt="Postgres configuration" width="1120px" />
+
+   - On the left is a SQL query editor.
+
+   - On the right is a table for previewing results.
+
+   - Below the query editor you can configure parameters which can be used to bind page state to your SQL query. Toolpad uses [prepared statements](https://www.postgresql.org/docs/current/sql-prepare.html) under the hood to prevent SQL injection. You can use the positional parameter syntax (`$1`, `$2`, `$3`) of postgres prepared statements. Additionally it will also accept named parameters of the form `$myParameter`.
+
+      <img src="/static/toolpad/docs/postgres-query-3.png" alt="Parameters configuration" width="553px" />
+
+     Like so: `SELECT * FROM "db" WHERE name = $name`.
+
+1. Once finished with configuration click **SAVE** to commit your changes and return to the canvas.

docs/data/toolpad/connecting-to-datasources/queries.md

@@ -0,0 +1,28 @@
+# Queries
+
+<p class="description">Toolpad allows you to easily connect to external datasources and render dynamic data. The easiest way to do so is to create a new query which can be used to fetch data.</p>
+
+1. Locate **ADD QUERY** button in the **Inspector** on the right:
+
+   <img src="/static/toolpad/docs/query-1.png" alt="Query" width="239px" />
+
+2. There are currently 4 different datasources\* that can be used to fetch data:
+
+   <img src="/static/toolpad/docs/query-2.png" alt="Datasources" width="476px" />
+
+   - [Function](/toolpad/connecting-to-datasources/function/) - advanced fetching methods which gives a lot of freedom by allowing to write custom fetching code.
+   - [Fetch](/toolpad/connecting-to-datasources/fetch/) - basic, but very powerful. Just pass URL of an API endpoint and you are ready to query your data.
+   - [Google Sheets](/toolpad/connecting-to-datasources/google-sheets/) - allows accessing data from your Google sheet document.
+   - [PostgreSQL](/toolpad/connecting-to-datasources/postgre-sql/) - ability to hook directly into your own DB without the need to use API.
+
+   \* - by default you will see only **Function** and **Fetch** datasources, for **Google Sheets** and **PostgreSQL** you will first need to create a [CONNECTION instance](/toolpad/connecting-to-datasources/connections/).
+
+3. After choosing the **QUERY** datasource and clicking **CREATE QUERY** you will be presented with a query configuration dialog (configuration settings for each individual type are documented on their respective pages).
+
+   There are a few configuration options that are applicable to every query type:
+
+   <img src="/static/toolpad/docs/query-3.png" alt="Query configuration" width="726px" />
+
+   - **Refetch on window focus** - execute the query every time the window is focused to make sure you always have the latest data visible.
+   - **Refetch on network reconnect** - execute the query every time the network status changes.
+   - **Refetch interval** - you can configure the query to run on an interval, e.g. **every 30s**. To disable this option, keep the field empty.