streamlit-command-palette 0.1.0__tar.gz

streamlit_command_palette-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 streamlit-command-palette contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

streamlit_command_palette-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include LICENSE
+include src/streamlit_command_palette/frontend/package.json
+include src/streamlit_command_palette/frontend/tsconfig.json
+include src/streamlit_command_palette/frontend/vite.config.ts
+recursive-include src/streamlit_command_palette/frontend/src *.ts
+recursive-include src/streamlit_command_palette/frontend/build *.js
+prune src/streamlit_command_palette/frontend/node_modules
+recursive-include examples *.py
+recursive-include tests *.py
+global-exclude __pycache__ *.py[cod] .DS_Store

streamlit_command_palette-0.1.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: streamlit-command-palette
+Version: 0.1.0
+Summary: A Cmd/Ctrl-K command palette and global search overlay for Streamlit apps.
+Author: streamlit-command-palette contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/huss22/streamlit-command-palette
+Project-URL: Repository, https://github.com/huss22/streamlit-command-palette
+Project-URL: Issues, https://github.com/huss22/streamlit-command-palette/issues
+Keywords: streamlit,streamlit-component,command-palette,search,custom-component
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: streamlit>=1.54.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: trove-classifiers>=2026.5.7.17; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# streamlit-command-palette
+
+`streamlit-command-palette` adds a polished Cmd/Ctrl-K command palette and
+global search overlay to Streamlit apps.
+
+It is intentionally small for v1: local client-side fuzzy search, grouped
+results, keyboard and mouse selection, and a simple Python API. It does not add
+AI search, database search, auth, or server-side search.
+
+## Installation
+
+```bash
+pip install streamlit-command-palette
+```
+
+Streamlit Custom Components v2 is required, so the package depends on
+`streamlit>=1.54.0` and Python `>=3.10`.
+
+## Quickstart
+
+```python
+import streamlit as st
+from streamlit_command_palette import action_item, command_palette, page_item
+
+items = [
+    page_item("home", "Home", subtitle="Overview", target="Home.py"),
+    page_item("reports", "Reports", subtitle="Saved reporting views"),
+    action_item("refresh", "Refresh data", subtitle="Run the latest query"),
+    {
+        "id": "docs",
+        "title": "Open documentation",
+        "subtitle": "Project README and runbook",
+        "type": "link",
+        "group": "Resources",
+        "url": "https://example.com/docs",
+        "keywords": ["help", "manual", "reference"],
+    },
+]
+
+selected = command_palette(items, key="global_palette")
+
+if selected:
+    st.write("Selected:", selected)
+    if selected["id"] == "refresh":
+        st.cache_data.clear()
+        st.rerun()
+```
+
+The component opens with `Cmd+K` on macOS and `Ctrl+K` elsewhere when using the
+default `shortcut="mod+k"`.
+
+## API
+
+```python
+from streamlit_command_palette import (
+    action_item,
+    command_palette,
+    command_search,
+    dataframe_items,
+    page_item,
+)
+```
+
+```python
+command_palette(
+    items,
+    placeholder="Search...",
+    shortcut="mod+k",
+    open=False,
+    groups=None,
+    max_results=10,
+    min_query_length=0,
+    search_fields=None,
+    show_shortcut_hint=True,
+    empty_state="No results found",
+    key=None,
+    height=None,
+    theme=None,
+)
+```
+
+`command_palette` returns the selected item dictionary on the Streamlit rerun
+caused by selection, or `None` when nothing was selected.
+
+`command_search` remains available as an alias for compatibility.
+
+## Item schema
+
+Each item supports these fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `id` | yes | Stable unique item id. |
+| `title` | yes | Primary result label. |
+| `subtitle` | no | Secondary text below the title. |
+| `type` | no | Item type such as `page`, `action`, `dataframe`, or `link`. |
+| `group` | no | Group heading for grouped results. |
+| `target` | no | JSON-safe value returned to Python for your app logic. |
+| `url` | no | URL metadata returned to Python. |
+| `icon` | no | Short label or icon text. Built-ins: `page`, `action`, `dataframe`, `link`. |
+| `keywords` | no | Extra searchable terms. |
+| `metadata` | no | JSON-safe metadata, also searchable by default. |
+| `disabled` | no | Disabled items are shown but cannot be selected. |
+
+## Helpers
+
+```python
+page_item("analytics", "Analytics", target="pages/1_Analytics.py")
+action_item("clear-cache", "Clear cache", target="clear-cache")
+
+items = dataframe_items(
+    df,
+    id_field="customer_id",
+    title_field="customer_name",
+    subtitle_fields=["segment", "region"],
+    group="Customers",
+)
+```
+
+## Group ordering and labels
+
+Pass `groups` to control display order and labels:
+
+```python
+selected = command_palette(
+    items,
+    groups={
+        "Pages": "Pages",
+        "Actions": "Actions",
+        "Customers": {"title": "Customers"},
+    },
+)
+```
+
+## Search fields
+
+By default, the frontend searches `title`, `subtitle`, `keywords`, and
+`metadata`. You can override the fields:
+
+```python
+command_palette(
+    items,
+    search_fields=["title", "keywords", "metadata.owner"],
+    min_query_length=1,
+)
+```
+
+## Theming
+
+The component uses Streamlit theme CSS variables automatically. You can pass a
+small override mapping when needed:
+
+```python
+command_palette(
+    items,
+    theme={
+        "primaryColor": "#0f766e",
+        "borderColor": "rgba(148, 163, 184, 0.35)",
+    },
+)
+```
+
+## Keyboard support
+
+The overlay supports:
+
+- `Cmd+K` on macOS and `Ctrl+K` elsewhere by default
+- `Escape` to close
+- `Enter` to select
+- `ArrowUp` and `ArrowDown` to move
+- `Home` and `End` to jump
+
+## Examples
+
+Run any example with Streamlit:
+
+```bash
+streamlit run examples/basic.py
+streamlit run examples/actions.py
+streamlit run examples/dataframe.py
+streamlit run examples/multipage/Home.py
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+cd src/streamlit_command_palette/frontend
+npm install
+npm run build
+
+cd ../../../..
+pytest
+python -m build
+```
+
+The package includes a prebuilt `frontend/build/index.js` asset so users do not
+need Node.js to install or run the component.
+
+## Release checklist
+
+1. Update the version in the root `pyproject.toml`, package
+   `__init__.py`, and component-level `pyproject.toml`.
+2. Build the frontend from `src/streamlit_command_palette/frontend`.
+3. Run `pytest`.
+4. Run `python -m build`.
+5. Run `python -m twine check dist/*`.
+6. Publish from GitHub Actions using the included TestPyPI and PyPI workflows.
+
+GitHub Actions workflows are included for pull request CI, manual TestPyPI
+publishing, and PyPI publishing from GitHub releases.
+
+## Contributing and security
+
+See `CONTRIBUTING.md` for development setup and pull request expectations.
+See `SECURITY.md` for vulnerability reporting.
+See `CODE_OF_CONDUCT.md` for community expectations.
+
+## License
+
+MIT

streamlit_command_palette-0.1.0/README.md

@@ -0,0 +1,224 @@
+# streamlit-command-palette
+
+`streamlit-command-palette` adds a polished Cmd/Ctrl-K command palette and
+global search overlay to Streamlit apps.
+
+It is intentionally small for v1: local client-side fuzzy search, grouped
+results, keyboard and mouse selection, and a simple Python API. It does not add
+AI search, database search, auth, or server-side search.
+
+## Installation
+
+```bash
+pip install streamlit-command-palette
+```
+
+Streamlit Custom Components v2 is required, so the package depends on
+`streamlit>=1.54.0` and Python `>=3.10`.
+
+## Quickstart
+
+```python
+import streamlit as st
+from streamlit_command_palette import action_item, command_palette, page_item
+
+items = [
+    page_item("home", "Home", subtitle="Overview", target="Home.py"),
+    page_item("reports", "Reports", subtitle="Saved reporting views"),
+    action_item("refresh", "Refresh data", subtitle="Run the latest query"),
+    {
+        "id": "docs",
+        "title": "Open documentation",
+        "subtitle": "Project README and runbook",
+        "type": "link",
+        "group": "Resources",
+        "url": "https://example.com/docs",
+        "keywords": ["help", "manual", "reference"],
+    },
+]
+
+selected = command_palette(items, key="global_palette")
+
+if selected:
+    st.write("Selected:", selected)
+    if selected["id"] == "refresh":
+        st.cache_data.clear()
+        st.rerun()
+```
+
+The component opens with `Cmd+K` on macOS and `Ctrl+K` elsewhere when using the
+default `shortcut="mod+k"`.
+
+## API
+
+```python
+from streamlit_command_palette import (
+    action_item,
+    command_palette,
+    command_search,
+    dataframe_items,
+    page_item,
+)
+```
+
+```python
+command_palette(
+    items,
+    placeholder="Search...",
+    shortcut="mod+k",
+    open=False,
+    groups=None,
+    max_results=10,
+    min_query_length=0,
+    search_fields=None,
+    show_shortcut_hint=True,
+    empty_state="No results found",
+    key=None,
+    height=None,
+    theme=None,
+)
+```
+
+`command_palette` returns the selected item dictionary on the Streamlit rerun
+caused by selection, or `None` when nothing was selected.
+
+`command_search` remains available as an alias for compatibility.
+
+## Item schema
+
+Each item supports these fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `id` | yes | Stable unique item id. |
+| `title` | yes | Primary result label. |
+| `subtitle` | no | Secondary text below the title. |
+| `type` | no | Item type such as `page`, `action`, `dataframe`, or `link`. |
+| `group` | no | Group heading for grouped results. |
+| `target` | no | JSON-safe value returned to Python for your app logic. |
+| `url` | no | URL metadata returned to Python. |
+| `icon` | no | Short label or icon text. Built-ins: `page`, `action`, `dataframe`, `link`. |
+| `keywords` | no | Extra searchable terms. |
+| `metadata` | no | JSON-safe metadata, also searchable by default. |
+| `disabled` | no | Disabled items are shown but cannot be selected. |
+
+## Helpers
+
+```python
+page_item("analytics", "Analytics", target="pages/1_Analytics.py")
+action_item("clear-cache", "Clear cache", target="clear-cache")
+
+items = dataframe_items(
+    df,
+    id_field="customer_id",
+    title_field="customer_name",
+    subtitle_fields=["segment", "region"],
+    group="Customers",
+)
+```
+
+## Group ordering and labels
+
+Pass `groups` to control display order and labels:
+
+```python
+selected = command_palette(
+    items,
+    groups={
+        "Pages": "Pages",
+        "Actions": "Actions",
+        "Customers": {"title": "Customers"},
+    },
+)
+```
+
+## Search fields
+
+By default, the frontend searches `title`, `subtitle`, `keywords`, and
+`metadata`. You can override the fields:
+
+```python
+command_palette(
+    items,
+    search_fields=["title", "keywords", "metadata.owner"],
+    min_query_length=1,
+)
+```
+
+## Theming
+
+The component uses Streamlit theme CSS variables automatically. You can pass a
+small override mapping when needed:
+
+```python
+command_palette(
+    items,
+    theme={
+        "primaryColor": "#0f766e",
+        "borderColor": "rgba(148, 163, 184, 0.35)",
+    },
+)
+```
+
+## Keyboard support
+
+The overlay supports:
+
+- `Cmd+K` on macOS and `Ctrl+K` elsewhere by default
+- `Escape` to close
+- `Enter` to select
+- `ArrowUp` and `ArrowDown` to move
+- `Home` and `End` to jump
+
+## Examples
+
+Run any example with Streamlit:
+
+```bash
+streamlit run examples/basic.py
+streamlit run examples/actions.py
+streamlit run examples/dataframe.py
+streamlit run examples/multipage/Home.py
+```
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+cd src/streamlit_command_palette/frontend
+npm install
+npm run build
+
+cd ../../../..
+pytest
+python -m build
+```
+
+The package includes a prebuilt `frontend/build/index.js` asset so users do not
+need Node.js to install or run the component.
+
+## Release checklist
+
+1. Update the version in the root `pyproject.toml`, package
+   `__init__.py`, and component-level `pyproject.toml`.
+2. Build the frontend from `src/streamlit_command_palette/frontend`.
+3. Run `pytest`.
+4. Run `python -m build`.
+5. Run `python -m twine check dist/*`.
+6. Publish from GitHub Actions using the included TestPyPI and PyPI workflows.
+
+GitHub Actions workflows are included for pull request CI, manual TestPyPI
+publishing, and PyPI publishing from GitHub releases.
+
+## Contributing and security
+
+See `CONTRIBUTING.md` for development setup and pull request expectations.
+See `SECURITY.md` for vulnerability reporting.
+See `CODE_OF_CONDUCT.md` for community expectations.
+
+## License
+
+MIT

streamlit_command_palette-0.1.0/examples/actions.py

@@ -0,0 +1,43 @@
+import streamlit as st
+
+from streamlit_command_palette import action_item, command_palette
+
+st.set_page_config(page_title="Command Palette Actions", page_icon="K")
+
+if "counter" not in st.session_state:
+    st.session_state.counter = 0
+if "status" not in st.session_state:
+    st.session_state.status = "Ready"
+
+items = [
+    action_item("increment", "Increment counter", subtitle="Add one to the demo value"),
+    action_item("reset", "Reset counter", subtitle="Set the demo value back to zero"),
+    action_item(
+        "clear-cache",
+        "Clear Streamlit cache",
+        subtitle="Call st.cache_data.clear",
+    ),
+    action_item(
+        "disabled",
+        "Disabled action",
+        subtitle="This item is visible but cannot be selected",
+        disabled=True,
+    ),
+]
+
+selected = command_palette(items, placeholder="Run an action...", key="actions_search")
+
+if selected:
+    if selected["id"] == "increment":
+        st.session_state.counter += 1
+        st.session_state.status = "Counter incremented"
+    elif selected["id"] == "reset":
+        st.session_state.counter = 0
+        st.session_state.status = "Counter reset"
+    elif selected["id"] == "clear-cache":
+        st.cache_data.clear()
+        st.session_state.status = "Cache cleared"
+
+st.title("Command actions")
+st.metric("Counter", st.session_state.counter)
+st.caption(st.session_state.status)

streamlit_command_palette-0.1.0/examples/basic.py

@@ -0,0 +1,43 @@
+import streamlit as st
+
+from streamlit_command_palette import action_item, command_palette, page_item
+
+st.set_page_config(page_title="Command Palette Basic", page_icon="K", layout="wide")
+
+st.title("Command palette basic example")
+
+items = [
+    page_item("home", "Home", subtitle="Dashboard overview", target="home"),
+    page_item("reports", "Reports", subtitle="Saved report views", target="reports"),
+    page_item(
+        "settings",
+        "Settings",
+        subtitle="Workspace preferences",
+        target="settings",
+    ),
+    action_item("refresh", "Refresh data", subtitle="Clear cache and rerun"),
+    action_item("download", "Download report", subtitle="Prepare latest CSV export"),
+    {
+        "id": "docs",
+        "title": "Open documentation",
+        "subtitle": "README and usage guide",
+        "type": "link",
+        "group": "Resources",
+        "url": "https://example.com/docs",
+        "icon": "link",
+        "keywords": ["help", "manual", "reference"],
+    },
+]
+
+selected = command_palette(
+    items,
+    placeholder="Search pages, actions, and resources...",
+    groups=["Pages", "Actions", "Resources"],
+    key="basic_command_search",
+)
+
+if selected:
+    st.success(f"Selected {selected['title']} ({selected['id']})")
+    st.json(selected)
+
+st.info("Use Cmd+K on macOS or Ctrl+K elsewhere.")

streamlit_command_palette-0.1.0/examples/dataframe.py

@@ -0,0 +1,53 @@
+import streamlit as st
+
+from streamlit_command_palette import command_palette, dataframe_items
+
+st.set_page_config(page_title="Command Palette DataFrame", page_icon="K", layout="wide")
+
+rows = [
+    {
+        "customer_id": "C-1001",
+        "customer_name": "Northstar Labs",
+        "segment": "Enterprise",
+        "region": "North America",
+        "owner": "Priya",
+    },
+    {
+        "customer_id": "C-1002",
+        "customer_name": "Lumen Works",
+        "segment": "Mid-market",
+        "region": "Europe",
+        "owner": "Mateo",
+    },
+    {
+        "customer_id": "C-1003",
+        "customer_name": "Harbor Analytics",
+        "segment": "Startup",
+        "region": "Australia",
+        "owner": "Ava",
+    },
+]
+
+items = dataframe_items(
+    rows,
+    id_field="customer_id",
+    title_field="customer_name",
+    subtitle_fields=["segment", "region"],
+    group="Customers",
+    keywords_fields=["customer_name", "segment", "region", "owner"],
+)
+
+selected = command_palette(
+    items,
+    placeholder="Search customers...",
+    groups={"Customers": "Customers"},
+    search_fields=["title", "subtitle", "keywords", "metadata.owner"],
+    key="customer_search",
+)
+
+st.title("DataFrame search")
+st.dataframe(rows, use_container_width=True)
+
+if selected:
+    st.subheader("Selected customer")
+    st.json(selected)

streamlit_command_palette-0.1.0/examples/multipage/Home.py

@@ -0,0 +1,8 @@
+import streamlit as st
+from palette import render_palette
+
+st.set_page_config(page_title="Multipage Command Palette", page_icon="K")
+render_palette()
+
+st.title("Home")
+st.write("Use Cmd+K on macOS or Ctrl+K elsewhere to navigate this multipage app.")

streamlit_command_palette-0.1.0/examples/multipage/pages/1_Analytics.py

@@ -0,0 +1,8 @@
+import streamlit as st
+from palette import render_palette
+
+st.set_page_config(page_title="Analytics", page_icon="K")
+render_palette()
+
+st.title("Analytics")
+st.line_chart({"Revenue": [120, 132, 141, 156], "Pipeline": [80, 96, 122, 138]})

streamlit_command_palette-0.1.0/examples/multipage/pages/2_Settings.py

@@ -0,0 +1,9 @@
+import streamlit as st
+from palette import render_palette
+
+st.set_page_config(page_title="Settings", page_icon="K")
+render_palette()
+
+st.title("Settings")
+st.toggle("Enable compact results", value=True)
+st.selectbox("Default group", ["Pages", "Actions", "Customers"])