Release 1.51.0 (#1365)

* Feature/custom components v2 (#1364)

* Fix Tailwind example CSS

* Custom components with Typescript

* Custom component API reference

* st.space

* streamlit run

* Configuration options

* LIght and dark theming

* Release notes

* Smart quotes

* What's new

* Cheat sheet

* Bump apps to latest

* Add cleanup function and npm refcards

* Review edits

Author: sfc-gh-dmatthews

components/blocks/autofunction.js

@@ -159,15 +159,19 @@ const Autofunction = ({
   let headerTitle;
   let body;
   let isClass;
+  let isInterface;
   let isAttributeDict;
+  let isTypeAlias;
   let methods = [];
   let properties = [];
 
   if (streamlitFunction in docstrings || oldStreamlitFunction in docstrings) {
     functionObject =
       docstrings[streamlitFunction] ?? docstrings[oldStreamlitFunction];
-    isClass = functionObject.is_class;
+    isClass = functionObject.is_class ?? false;
+    isInterface = functionObject.is_interface ?? false;
     isAttributeDict = functionObject.is_attribute_dict ?? false;
+    isTypeAlias = functionObject.type === "type_alias";
     if (
       functionObject.description !== undefined &&
       functionObject.description
@@ -222,9 +226,12 @@ const Autofunction = ({
   if (hideHeader !== undefined && hideHeader) {
     header = "";
   } else {
-    const name = functionObject.signature
-      ? `${functionObject.signature}`.split("(")[0].replace("streamlit", "st")
-      : "";
+    let name = "";
+    if (isInterface || isTypeAlias) {
+      name = functionObject.name;
+    } else if (functionObject.signature) {
+      name = functionObject.signature.split("(")[0].replace("streamlit", "st");
+    }
     headerTitle = isAttributeDict ? (
       <H3 className={styles.Title}>
         <a
@@ -351,10 +358,10 @@ const Autofunction = ({
     // When "Parameters" are included in a class docstring, they are actually
     // "Properties." Using "Properties" in the docstring does not result in
     // individually parsed properties; using "Parameters" is a workaround.
-    if (isClass) {
-      propertiesRows.push(row);
-    } else {
+    if (!isClass || isInterface) {
       args.push(row);
+    } else {
+      propertiesRows.push(row);
     }
   }
 
@@ -364,7 +371,9 @@ const Autofunction = ({
     const row = {};
     const method = methods[index];
     const slicedSlug = slug.slice().join("/");
-    const hrefName = `${functionObject.name}.${method.name}`
+    const hrefName = (
+      isTypeAlias ? method.name : `${functionObject.name}.${method.name}`
+    )
       .toLowerCase()
       .replace("streamlit", "st")
       .replace(/[.,\/#!$%\^&\*;:{}=\-`~()]/g, "");
@@ -454,6 +463,16 @@ const Autofunction = ({
     returns.push(row);
   }
 
+  const getArgsTitle = () => {
+    if (isTypeAlias && !isInterface) {
+      return "Properties"; // For TypeScript type aliases that aren't function interfaces
+    }
+    if (isTypeAlias) {
+      return "Arguments"; // For TypeScript function interfaces
+    }
+    return "Parameters"; // For Python functions
+  };
+
   body = (
     <Table
       head={
@@ -462,7 +481,11 @@ const Autofunction = ({
           : {
               title: (
                 <>
-                  {isClass ? "Class description" : "Function signature"}
+                  {isTypeAlias
+                    ? "(TypeScript) Type alias description"
+                    : isClass
+                      ? "Class description"
+                      : "Function signature"}
                   <a
                     className={styles.Title.a}
                     href={functionObject.source}
@@ -481,12 +504,22 @@ const Autofunction = ({
               content: `<p class='code'> ${functionObject.signature}</p> `,
             }
       }
-      body={args.length ? { title: "Parameters" } : null}
+      body={
+        args.length
+          ? {
+              title: getArgsTitle(),
+            }
+          : null
+      }
       bodyRows={args.length ? args : null}
       foot={[
-        methods.length ? { title: "Methods" } : null,
+        methods.length
+          ? { title: isTypeAlias ? "Functions" : "Methods" }
+          : null,
         returns.length ? { title: "Returns" } : null,
-        propertiesRows.length ? { title: "Attributes" } : null,
+        propertiesRows.length
+          ? { title: isTypeAlias ? "Properties" : "Attributes" }
+          : null,
       ].filter((section) => section !== null)}
       footRows={[
         methods.length ? methodRows : null,

content/develop/api-reference/_index.md

@@ -1582,6 +1582,19 @@ st.sidebar.write("This lives in the sidebar")
 st.sidebar.button("Click me!")
 ```
 
+</RefCard>
+<RefCard href="/develop/api-reference/layout/st.space">
+
+<Image pure alt="screenshot" src="/images/api/space.jpg" />
+
+<h4>Space</h4>
+
+Add vertical or horizontal space.
+
+```python
+st.space("small")
+```
+
 </RefCard>
 <RefCard href="/develop/api-reference/layout/st.tabs">
 
@@ -2424,6 +2437,106 @@ st.write(user_info)
 
 <br />
 
+#### V2 custom components
+
+<TileContainer>
+
+<RefCard href="/develop/api-reference/custom-components/st.components.v2.component">
+
+<h4>Register</h4>
+
+Register a custom component.
+
+```python
+my_component = st.components.v2.component(
+    html=HTML,
+    js=JS
+)
+my_component()
+```
+
+</RefCard>
+
+<RefCard href="/develop/api-reference/custom-components/st.components.v2.types.bidicomponentcallable">
+
+<h4>Mount</h4>
+
+Mount a custom component.
+
+```python
+my_component = st.components.v2.component(
+    html=HTML,
+    js=JS
+)
+my_component()
+```
+
+</RefCard>
+
+<RefCard href="/develop/api-reference/custom-components/component-v2-lib">
+
+<h4>npm support code</h4>
+
+Support code published through npm.
+
+```bash
+npm i @streamlit/component-v2-lib
+```
+
+</RefCard>
+
+<RefCard href="/develop/api-reference/custom-components/component-v2-lib-component">
+
+<h4>Component</h4>
+
+Type alias for the component function.
+
+```typescript
+import { Component } from "@streamlit/component-v2-lib";
+```
+
+</RefCard>
+
+<RefCard href="/develop/api-reference/custom-components/component-v2-lib-componentargs">
+
+<h4>ComponentArgs</h4>
+
+Type alias for the component arguments.
+
+```typescript
+import { ComponentArgs } from "@streamlit/component-v2-lib";
+```
+
+</RefCard>
+
+<RefCard href="/develop/api-reference/custom-components/component-v2-lib-componentstate">
+
+<h4>ComponentState</h4>
+
+Type alias for the component state.
+
+```typescript
+import { ComponentState } from "@streamlit/component-v2-lib";
+```
+
+</RefCard>
+
+<RefCard href="/develop/api-reference/custom-components/component-v2-lib-optionalcomponentcleanupfunction" size="two-third">
+
+<h4>OptionalComponentCleanupFunction</h4>
+
+Type alias for the component cleanup function.
+
+```typescript
+import { OptionalComponentCleanupFunction } from "@streamlit/component-v2-lib";
+```
+
+</RefCard>
+
+</TileContainer>
+
+#### V1 custom components
+
 <TileContainer>
 
 <RefCard href="/develop/api-reference/custom-components/st.components.v1.declare_component">

content/develop/api-reference/command-line/run.md

@@ -12,12 +12,18 @@ This command starts your Streamlit app.
 ### Syntax
 
 ```
-streamlit run <entrypoint file> [-- config options] [script args]
+streamlit run [<entrypoint file or directory>] [-- config options] [script args]
 ```
 
 ### Arguments
 
-`<entrypoint file>`: The path to your entrypoint file for your Streamlit app. In a multipage app with `st.navigation`, your entrypoint file acts as a router between your pages. Otherwise, your entrypoint file is your app's homepage.
+`<entrypoint file or directory>` (optional): The path to your entrypoint file or directory for your Streamlit app.
+
+- **If not provided**: Streamlit will try to run `streamlit_app.py` from the current working directory.
+- **If a directory path is provided**: Streamlit will try to run `streamlit_app.py` in the specified directory.
+- **If a file path is provided**: Streamlit will run the specified file.
+
+In a multipage app with `st.navigation`, your entrypoint file acts as a router between your pages. Otherwise, your entrypoint file is your app's homepage.
 
 ### Options
 
@@ -31,44 +37,62 @@ For a complete list of configuration options, see [`config.toml`](/develop/api-r
 
 ### Script arguments
 
-If you need to pass arguments directly to your script, you can pass them as positional arguments. If you use `sys.argv` to read your arguments, `sys.arfgv` returns a list of all arugments and does _not_ include any configuration options. Python interprets all arguments as strings.
+If you need to pass arguments directly to your script, you can pass them as positional arguments. If you use `sys.argv` to read your arguments, `sys.argv` returns a list of all arguments and does _not_ include any configuration options. Python interprets all arguments as strings.
 
-- `sys.argv[0]` returns the provided path to your entrypoint file (`<entrypoint file>`).
+- `sys.argv[0]` returns the the path to your entrypoint file, even if you did not explicitly provide it.
 - `sys.argv[1:]` returns a list of arguments in order and does not include any configuration options.
 
 ### Examples
 
-- If your app is in your working directory, run it as follows:
+- If your app is named `streamlit_app.py` in your working directory, you can run it with the following command:
+
+  ```
+  streamlit run
+  ```
+
+- If your app has a different name and is in your working directory, run it like the following command:
 
   ```
   streamlit run your_app.py
   ```
 
-- If your app is in a subdirectory, run it as follows:
+- If your app is named `streamlit_app.py` in a subdirectory, you can run it like the following command:
+
+  ```
+  streamlit run your_subdirectory
+  ```
+
+- If your app has a different name and is in a subdirectory, run it like the following command:
 
   ```
   streamlit run your_subdirectory/your_app.py
   ```
 
-- If your app is saved in a public GitHub repo or gist, run it as follows:
+- If your app is saved in a public GitHub repo or gist, run it like the following command:
 
   ```
   streamlit run https://raw.githubusercontent.com/streamlit/demo-uber-nyc-pickups/master/streamlit_app.py
   ```
 
-- If you need to set one or more configuration options, run it as follows:
+- If you need to set one or more configuration options, run it like the following command:
 
   ```
   streamlit run your_app.py --client.showErrorDetails=False --theme.primaryColor=blue
   ```
 
-- If you need to pass an argument to your script, run it as follows:
+  Or if using the default `streamlit_app.py`:
+
+  ```
+  streamlit run --client.showErrorDetails=False --theme.primaryColor=blue
+  ```
+
+- If you need to pass an argument to your script, run it like the following command:
 
   ```
   streamlit run your_app.py "my list" of arguments
   ```
 
-  Within your script, the following statement will be true:
+  Within your script, the following statements will be true:
 
   ```
   sys.argv[0] == "your_app.py"