[feat] Add contributing guidelines for the directory

.gitignore

@@ -67,5 +67,6 @@ template-reactless/**/package-lock.json
 ########################################################################
 # VSCode
 ########################################################################
-.vscode/
-buildcontext/
+.vscode/*
+!.vscode/settings.json
+buildcontext/

.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["directory/components/*.json"],
+      "url": "./directory/schemas/component.schema.json"
+    }
+  ]
+}

CONTRIBUTING.md

@@ -2,11 +2,18 @@
 
 Welcome to Streamlit component template! We appreciate your interest in contributing to our project.
 
+## Adding a component to the directory
+
+If your goal is to add a new JSON entry under `directory/components/` (the community component registry), you **do not** need to follow the development setup below.
+
+Start here instead: [`directory/README.md`](directory/README.md)
+
 ## Setting up pyenv and Intellij IDEA
 
 ### 1. Install pyenv
 
 Run command:
+
 ```shell
 $ curl https://pyenv.run | bash
 ```
@@ -16,12 +23,13 @@ $ curl https://pyenv.run | bash
 ```shell
 $ pyenv install <python_version>
 ```
+
 - python_version - version of python. To check all available versions (recommended 3.11.4) use:
+
 ```shell
 $ pyenv install --list
 ```
 
-
 ### 3. Creating virtual environment
 
 ```shell
@@ -66,15 +74,16 @@ $ ./dev.py all-npm-build
 $ ./dev.py all-python-build-package
 ```
 
-### 3. Set _RELEASE flag
+### 3. Set `_RELEASE` flag
 
-For development we need to set _RELEASE flag. Open __init__.py file for any example or template and set _RELEASE flag to true. 
-Remember to set this flag back to false if you want to create PR.
+For development we need to set the `_RELEASE` flag. Open the `__init__.py` file for any example or template and set `_RELEASE = True`.
+Remember to set this flag back to `False` if you want to create PR.
 
 ### 4. Install template as editable package
 
 Go to directory of example or template and run `pip install -e .`.
 Example:
+
 ```shell
 $ cd examples/CustomDataframe
 $ pip install -e .
@@ -85,11 +94,13 @@ $ pip install -e .
 **Example for CustomDataframe**
 
 Run python script:
+
 ```shell
 $ streamlit run examples/CustomDataframe/custom_dataframe/example.py
 ```
 
 Run frontend:
+
 ```shell
 $ cd examples/CustomDataframe/custom_dataframe/frontend
 $ npm run start
@@ -128,23 +139,29 @@ Template and template-reactless share the same component name. We can only have
 To switch between them, we need to uninstall one and install another. To do that:
 
 ### 1. Check installed template
+
 Run:
+
 ```shell
 $ pip freeze
 ```
 
 and find installed package. Copy egg name of this component.
 
 ### 2. Uninstall template
+
 ```shell
 $ pip uninstall <egg_name>
 ```
 
 - egg_name - name of package name, by default it is: `streamlit_custom_component`
 
 ### 3. Install another template
+
 Run:
+
 ```shell
 $ pip install -e .
 ```
+
 inside template directory.

README.md

@@ -116,6 +116,12 @@ These templates are provided by the community. If you run into any issues, pleas
 - [streamlit-component-template-vue](https://github.com/andfanilo/streamlit-component-template-vue) - [@andfanilo](https://github.com/andfanilo)
 - [streamlit-component-template-react-hooks](https://github.com/whitphx/streamlit-component-template-react-hooks) - [@whitphx](https://github.com/whitphx)
 
+## Component directory
+
+This repo also includes a community directory of Streamlit components under `directory/components/`.
+
+To add your component to the directory, see [`directory/README.md`](directory/README.md).
+
 ## Contributing
 
 If you want to contribute to this project, `./dev.py` script will be helpful for you. For details, run `./dev.py --help`.

directory/README.md

@@ -0,0 +1,120 @@
+# Component Directory
+
+This repo includes a **community-maintained directory** of Streamlit components under [`directory/components/`](components/). Each file is a small JSON document describing a single component found on the internet.
+
+If you maintain a Streamlit Component, we’d love for you to add it here via a pull request!
+
+## Quick submit (GitHub web editor)
+
+1. **Fork** this repository.
+2. In your fork, open [`directory/components/`](components/) and click **Add file → Create new file**.
+3. Name your file: `directory/components/<slug>.json`
+   - Use a short, URL-safe slug like `streamlit-my-component.json` (lowercase + hyphens is best).
+4. Copy/paste the **Starter template** below, fill in your values.
+5. Commit to a new branch in your fork.
+6. Open a **Pull Request** back to this repo.
+
+When you open the PR, CI will automatically validate your JSON.
+
+## Starter template (minimal valid)
+
+> Tip: If you’re editing in VS Code / GitHub’s web editor, you should get live validation + autocomplete from the schema once `.vscode/settings.json` is present in the repo.
+
+```json
+{
+  "schemaVersion": 1,
+  "title": "My Component",
+  "author": {
+    "github": "your-github-username",
+    "displayName": "Your Name (optional)"
+  },
+  "description": "One sentence describing what the component does (recommended).",
+  "links": {
+    "github": "https://github.com/OWNER/REPO",
+    "pypi": null,
+    "demo": null,
+    "docs": null
+  },
+  "media": {
+    "image": null
+  },
+  "install": {
+    "pip": "pip install your-package-name"
+  },
+  "governance": {
+    "enabled": true,
+    "notes": null
+  },
+  "categories": ["Widgets"]
+}
+```
+
+## Requirements (what CI checks)
+
+CI runs [`directory/scripts/validate.py`](scripts/validate.py) on every PR that touches `directory/components/**`.
+
+### Schema requirements
+
+Your JSON must conform to [`directory/schemas/component.schema.json`](schemas/component.schema.json). Key points:
+
+- **`schemaVersion`**: must be `1`.
+- **`title`**: 1–80 characters.
+- **`author.github`**: GitHub username _without_ `@`.
+- **`links.github`**: must be a repo URL like `https://github.com/<owner>/<repo>` (no extra path segments).
+- **`links.pypi`**: PyPI project name (not a URL), or `null`.
+- **`description`** (recommended): if present, must be 1–280 characters.
+- **No extra keys**: the schema uses `additionalProperties: false`, so don’t add custom fields.
+
+### Policy checks beyond schema (common CI failures)
+
+The validator enforces a few “lint” rules to keep the registry stable:
+
+- **Unique repo**: `links.github` must be unique across all submissions. If the same repo was already submitted, CI will fail.
+- **HTTPS only**: all URLs must be `https://` and must not use `javascript:`, `data:`, or `file:` schemes.
+- **Stable images** (`media.image`): must be a stable `https://` URL.
+  - Signed/expiring URLs (S3/GCS/CloudFront-style query params like `X-Amz-Signature`, `Expires`, etc.) are rejected.
+  - Proxy hosts like `camo.githubusercontent.com` are rejected.
+- **File size**: each `directory/components/*.json` must be ≤ 50 KB.
+
+## Categories
+
+Pick **at least one** category (you can pick multiple). Allowed values are:
+
+- `LLMs`
+- `Widgets`
+- `Charts`
+- `Authentication`
+- `Connections`
+- `Images & video`
+- `Audio`
+- `Text`
+- `Maps`
+- `Dataframes`
+- `Graphs`
+- `Molecules & genes`
+- `Code editors`
+- `Page navigation`
+- `Developer tools`
+- `Integrations`
+
+## Self-check your submission (optional, but recommended)
+
+### Option A: No local setup
+
+Open a **draft PR** and let CI validate it automatically.
+
+### Option B: Run the validator locally
+
+From the repo root:
+
+```bash
+uv venv .venv
+uv pip install -r requirements.txt
+.venv/bin/python ./directory/scripts/validate.py
+```
+
+If it prints `OK: all validated files passed.`, your submission is valid.
+
+## What not to edit
+
+- Don’t edit `directory/compiled/components.json` directly — it’s a generated artifact.

work-tmp/pr-139-review-threads.json

@@ -0,0 +1 @@
+{"data":{"repository":{"pullRequest":{"reviewThreads":{"nodes":[{"isResolved":false,"comments":{"nodes":[{"databaseId":2699324915,"author":{"login":"copilot-pull-request-reviewer"},"body":"The filename should be `__init__.py` (double underscores), not `**init**.py` (which renders as bold 'init' in Markdown). Use backticks for code formatting: `` `__init__.py` ``\n```suggestion\nFor development we need to set \\_RELEASE flag. Open `__init__.py` file for any example or template and set \\_RELEASE flag to true.\n```","path":"CONTRIBUTING.md","diffHunk":"@@ -66,15 +74,16 @@ $ ./dev.py all-npm-build\n $ ./dev.py all-python-build-package\n ```\n \n-### 3. Set _RELEASE flag\n+### 3. Set \\_RELEASE flag\n \n-For development we need to set _RELEASE flag. Open __init__.py file for any example or template and set _RELEASE flag to true. \n+For development we need to set \\_RELEASE flag. Open **init**.py file for any example or template and set \\_RELEASE flag to true.","url":"https://github.com/streamlit/component-template/pull/139#discussion_r2699324915"}]}}]}}}}}