streamlit-vanilla-components 0.1.0__tar.gz

streamlit_vanilla_components-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Horton
+
+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_vanilla_components-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: streamlit-vanilla-components
+Version: 0.1.0
+Summary: Vanilla HTML/CSS/JS Streamlit components with no npm dependencies.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/lukehorton1/streamlit-vanilla-components
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: streamlit>=1.57
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Streamlit vanilla components
+
+Lightweight [Streamlit components v2](https://docs.streamlit.io/develop/api-reference/custom-components) in plain HTML, CSS and JavaScript. No npm packages, no build step. Each component copies its native Streamlit look and follows the active theme.
+
+Built using GitHub Copilot as an AI coding agent, with manual oversight, design and testing throughout.
+
+```python
+from streamlit_vanilla_components import st_live_searchbox, stateful_button
+```
+
+Run the demo with `streamlit run example.py`.
+
+## Installation
+
+```bash
+pip install streamlit-vanilla-components
+```
+
+Or install straight from GitHub:
+
+```bash
+pip install "git+https://github.com/lukehorton1/streamlit-vanilla-components.git"
+```
+
+Requires Python 3.10+ and Streamlit 1.57+.
+
+## Components
+
+- [`st_live_searchbox`](#st_live_searchbox)
+- [`stateful_button`](#stateful_button)
+
+---
+
+## `st_live_searchbox`
+
+A search box whose dropdown is filled by your Python function as the user types. Returns the picked option as a string.
+
+```python
+def search_places(term: str) -> list[str]:
+    return db.query("SELECT label FROM places WHERE label ILIKE %s LIMIT 300", f"%{term}%")
+
+choice = st_live_searchbox(search_places, placeholder="Search a place...", rank=True, max_results=50)
+```
+
+### Parameters
+
+| Parameter | Description |
+|---|---|
+| `search_fn` *(callable)* | Receives the typed text and returns a list of options. Required. |
+| `placeholder` *(str)* | Placeholder text. Default `"Type to search..."`. |
+| `key` *(str)* | Widget key. Default `"live_search"`. |
+| `on_change` *(callable or None)* | Runs when the typed text changes. |
+| `on_submit` *(callable or None)* | Runs when an option is picked. |
+| `args` *(tuple or None)* | Passed to `on_change` and `on_submit`. |
+| `kwargs` *(dict or None)* | Passed to `on_change` and `on_submit`. |
+| `debounce` *(int)* | Milliseconds to wait after typing stops before searching. Default `250`. |
+| `default` *(str or None)* | Returned until something is picked. Default `None`. |
+| `label` *(str or None)* | Label above the box. |
+| `label_visibility` *(str)* | `"visible"`, `"hidden"` or `"collapsed"`. Default `"visible"`. |
+| `help` *(str or None)* | Tooltip next to the label. |
+| `disabled` *(bool)* | Disables the box. Default `False`. |
+| `min_chars` *(int)* | Characters typed before `search_fn` runs. Default `1`. |
+| `max_results` *(int or None)* | Maximum options shown, applied after ranking. Default `None`. |
+| `rank` *(bool)* | Sorts options by match quality (exact, starts with, word starts with, contains). Default `False`. |
+| `clear_on_submit` *(bool)* | Empties the box after a pick. Default `False`. |
+| `width` *(str or int)* | `"stretch"` or a pixel width. Default `"stretch"`. |
+
+**Returns** *(str or None)*: the picked option, or `default`.
+
+### See also
+
+- Typing again after a pick replaces it with the new text.
+- Ranking only sees what `search_fn` returns, so return more candidates than `max_results`.
+
+---
+
+## `stateful_button`
+
+A `st.button` look-alike that disables itself on click, shows a spinner in place of its icon while your code runs, then a tick on success.
+
+```python
+with stateful_button("Submit", type="primary") as clicked:
+    if clicked:
+        save_records()
+        st.success("Saved!")
+
+# or, for a single function call
+stateful_button("Run job", on_click=run_job, args=("Job 1",))
+```
+
+### Parameters
+
+Same as `st.button`, plus `icon_position` and `wrap`.
+
+| Parameter | Description |
+|---|---|
+| `label` *(str)* | Button text. Plain text, no Markdown. Required. |
+| `key` *(str or None)* | Widget key. Derived from the other arguments if omitted. |
+| `help` *(str or None)* | Tooltip. |
+| `on_click` *(callable or None)* | Work to run. The button stays busy until it finishes. |
+| `args` *(tuple or None)* | Passed to `on_click`. |
+| `kwargs` *(dict or None)* | Passed to `on_click`. |
+| `type` *(str)* | `"primary"`, `"secondary"` or `"tertiary"`. Default `"secondary"`. |
+| `icon` *(str or None)* | Emoji or `:material/name:`. |
+| `icon_position` *(str)* | `"left"` or `"right"`. Default `"left"`. |
+| `disabled` *(bool)* | Disables the button. Default `False`. |
+| `width` *(str or int)* | `"content"`, `"stretch"` or a pixel width. Default `"content"`. |
+| `shortcut` *(str or None)* | Keyboard shortcut. |
+| `wrap` *(bool or None)* | Whether the label may wrap. |
+
+**Returns** *(StatefulButton)*: truthy on the run it was clicked. Works as a context manager, and `.release(success=True)` ends the busy state early.
+
+### See also
+
+- Use either the `with` form or `on_click`. Without either, the spinner never stops.
+- Errors in the `with` block or in `on_click` re-enable the button, then raise.

streamlit_vanilla_components-0.1.0/README.md

@@ -0,0 +1,116 @@
+# Streamlit vanilla components
+
+Lightweight [Streamlit components v2](https://docs.streamlit.io/develop/api-reference/custom-components) in plain HTML, CSS and JavaScript. No npm packages, no build step. Each component copies its native Streamlit look and follows the active theme.
+
+Built using GitHub Copilot as an AI coding agent, with manual oversight, design and testing throughout.
+
+```python
+from streamlit_vanilla_components import st_live_searchbox, stateful_button
+```
+
+Run the demo with `streamlit run example.py`.
+
+## Installation
+
+```bash
+pip install streamlit-vanilla-components
+```
+
+Or install straight from GitHub:
+
+```bash
+pip install "git+https://github.com/lukehorton1/streamlit-vanilla-components.git"
+```
+
+Requires Python 3.10+ and Streamlit 1.57+.
+
+## Components
+
+- [`st_live_searchbox`](#st_live_searchbox)
+- [`stateful_button`](#stateful_button)
+
+---
+
+## `st_live_searchbox`
+
+A search box whose dropdown is filled by your Python function as the user types. Returns the picked option as a string.
+
+```python
+def search_places(term: str) -> list[str]:
+    return db.query("SELECT label FROM places WHERE label ILIKE %s LIMIT 300", f"%{term}%")
+
+choice = st_live_searchbox(search_places, placeholder="Search a place...", rank=True, max_results=50)
+```
+
+### Parameters
+
+| Parameter | Description |
+|---|---|
+| `search_fn` *(callable)* | Receives the typed text and returns a list of options. Required. |
+| `placeholder` *(str)* | Placeholder text. Default `"Type to search..."`. |
+| `key` *(str)* | Widget key. Default `"live_search"`. |
+| `on_change` *(callable or None)* | Runs when the typed text changes. |
+| `on_submit` *(callable or None)* | Runs when an option is picked. |
+| `args` *(tuple or None)* | Passed to `on_change` and `on_submit`. |
+| `kwargs` *(dict or None)* | Passed to `on_change` and `on_submit`. |
+| `debounce` *(int)* | Milliseconds to wait after typing stops before searching. Default `250`. |
+| `default` *(str or None)* | Returned until something is picked. Default `None`. |
+| `label` *(str or None)* | Label above the box. |
+| `label_visibility` *(str)* | `"visible"`, `"hidden"` or `"collapsed"`. Default `"visible"`. |
+| `help` *(str or None)* | Tooltip next to the label. |
+| `disabled` *(bool)* | Disables the box. Default `False`. |
+| `min_chars` *(int)* | Characters typed before `search_fn` runs. Default `1`. |
+| `max_results` *(int or None)* | Maximum options shown, applied after ranking. Default `None`. |
+| `rank` *(bool)* | Sorts options by match quality (exact, starts with, word starts with, contains). Default `False`. |
+| `clear_on_submit` *(bool)* | Empties the box after a pick. Default `False`. |
+| `width` *(str or int)* | `"stretch"` or a pixel width. Default `"stretch"`. |
+
+**Returns** *(str or None)*: the picked option, or `default`.
+
+### See also
+
+- Typing again after a pick replaces it with the new text.
+- Ranking only sees what `search_fn` returns, so return more candidates than `max_results`.
+
+---
+
+## `stateful_button`
+
+A `st.button` look-alike that disables itself on click, shows a spinner in place of its icon while your code runs, then a tick on success.
+
+```python
+with stateful_button("Submit", type="primary") as clicked:
+    if clicked:
+        save_records()
+        st.success("Saved!")
+
+# or, for a single function call
+stateful_button("Run job", on_click=run_job, args=("Job 1",))
+```
+
+### Parameters
+
+Same as `st.button`, plus `icon_position` and `wrap`.
+
+| Parameter | Description |
+|---|---|
+| `label` *(str)* | Button text. Plain text, no Markdown. Required. |
+| `key` *(str or None)* | Widget key. Derived from the other arguments if omitted. |
+| `help` *(str or None)* | Tooltip. |
+| `on_click` *(callable or None)* | Work to run. The button stays busy until it finishes. |
+| `args` *(tuple or None)* | Passed to `on_click`. |
+| `kwargs` *(dict or None)* | Passed to `on_click`. |
+| `type` *(str)* | `"primary"`, `"secondary"` or `"tertiary"`. Default `"secondary"`. |
+| `icon` *(str or None)* | Emoji or `:material/name:`. |
+| `icon_position` *(str)* | `"left"` or `"right"`. Default `"left"`. |
+| `disabled` *(bool)* | Disables the button. Default `False`. |
+| `width` *(str or int)* | `"content"`, `"stretch"` or a pixel width. Default `"content"`. |
+| `shortcut` *(str or None)* | Keyboard shortcut. |
+| `wrap` *(bool or None)* | Whether the label may wrap. |
+
+**Returns** *(StatefulButton)*: truthy on the run it was clicked. Works as a context manager, and `.release(success=True)` ends the busy state early.
+
+### See also
+
+- Use either the `with` form or `on_click`. Without either, the spinner never stops.
+- Errors in the `with` block or in `on_click` re-enable the button, then raise.

streamlit_vanilla_components-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "streamlit-vanilla-components"
+version = "0.1.0"
+description = "Vanilla HTML/CSS/JS Streamlit components with no npm dependencies."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["streamlit>=1.57"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.urls]
+Repository = "https://github.com/lukehorton1/streamlit-vanilla-components"
+
+[tool.setuptools.packages.find]
+include = ["streamlit_vanilla_components*"]
+
+[tool.setuptools.package-data]
+"streamlit_vanilla_components.searchbox" = ["frontend/*"]
+"streamlit_vanilla_components.stateful_button" = ["frontend/*"]

streamlit_vanilla_components-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/__init__.py

@@ -0,0 +1,6 @@
+"""Vanilla HTML/JS/CSS components for Streamlit."""
+
+from .searchbox import st_live_searchbox
+from .stateful_button import stateful_button
+
+__all__ = ["st_live_searchbox", "stateful_button"]

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/searchbox/__init__.py

@@ -0,0 +1,130 @@
+"""A live search box: typing runs your Python search function."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+import re
+
+import streamlit as st
+
+_FRONTEND = Path(__file__).parent / "frontend"
+
+
+def _read(name: str) -> str:
+    return (_FRONTEND / name).read_text(encoding="utf-8")
+
+
+_COMPONENT = st.components.v2.component(
+    "live_searchbox",
+    html=_read("index.html"),
+    css=_read("style.css"),
+    js=_read("index.js"),
+)
+
+
+def _rank(options: list[str], term: str) -> list[str]:
+    """Stable sort by match quality, judged on the text before the first comma."""
+    t = term.strip().lower()
+    if not t:
+        return options
+    word_start = re.compile(r"\b" + re.escape(t))
+
+    def tier(option: str) -> int:
+        text = option.split(",")[0].strip().lower()
+        if text == t:
+            return 0
+        if text.startswith(t):
+            return 1
+        if word_start.search(text):
+            return 2
+        if t in text:
+            return 3
+        return 4
+
+    return sorted(options, key=tier)  # sorted() is stable: incoming order breaks ties
+
+
+def st_live_searchbox(
+    search_fn: Callable[[str], list[str]],
+    placeholder: str = "Type to search...",
+    key: str = "live_search",
+    *,
+    on_change: Callable | None = None,
+    on_submit: Callable | None = None,
+    args: tuple | None = None,
+    kwargs: dict | None = None,
+    debounce: int = 250,
+    default: str | None = None,
+    label: str | None = None,
+    label_visibility: str = "visible",
+    help: str | None = None,
+    disabled: bool = False,
+    min_chars: int = 1,
+    max_results: int | None = None,
+    rank: bool = False,
+    clear_on_submit: bool = False,
+    width: str | int = "stretch",
+) -> str | None:
+    """Show a text box whose dropdown is filled by `search_fn(search_term)`.
+
+    `search_fn` returns a list of strings (e.g. from a SQL query) and runs after the
+    user pauses typing for `debounce` milliseconds. Returns the last option the user
+    picked (or `default`).
+
+    `on_change` runs when the typed text changes, `on_submit` when an option is picked.
+    Both run before the script reruns, like native widgets, and can read
+    `st.session_state[key].query` and `st.session_state[key].selected`.
+
+    `rank=True` re-orders the results by match quality: exact match, starts with the
+    term, a word starts with the term, contains the term. Results in the same tier keep
+    the order `search_fn` returned them in, so sort by e.g. population there. Because
+    ranking only sees what `search_fn` returns, return more candidates than
+    `max_results` or the best match may already have been cut off.
+
+    `min_chars` holds back searching until enough text is typed, `max_results` caps the
+    list (applied after ranking), and `clear_on_submit` empties the box after a pick.
+    """
+
+    def wrap(fn):
+        if fn is None:
+            return lambda: None
+        return lambda: fn(*(args or ()), **(kwargs or {}))
+
+    state = st.session_state.get(key)
+    query = getattr(state, "query", None) or ""
+    selected = getattr(state, "selected", None)
+    if selected is None:
+        selected = default
+    selected = selected or None  # "" means the user cleared it
+
+    options: list[str] = []
+    if len(query) >= min_chars:
+        options = [str(o) for o in (search_fn(query) or [])]
+        if rank:
+            options = _rank(options, query)
+        if max_results is not None:
+            options = options[:max_results]
+
+    result = _COMPONENT(
+        key=key,
+        data={
+            "options": options,
+            "placeholder": placeholder,
+            "initial": "" if clear_on_submit else (selected or ""),
+            "debounce": max(0, int(debounce)),
+            "label": label,
+            "labelVisibility": label_visibility,
+            "help": help,
+            "disabled": disabled,
+            "clearOnSubmit": clear_on_submit,
+        },
+        width=width,
+        on_query_change=wrap(on_change),
+        on_selected_change=lambda: None,
+        on_submitted_change=wrap(on_submit),
+    )
+    if result.selected is None:
+        return default
+    return result.selected or None

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/searchbox/frontend/index.html

@@ -0,0 +1,10 @@
+<div id="wrap">
+  <label id="label" for="input" hidden></label>
+  <div id="field">
+    <div id="box">
+      <input id="input" type="text" autocomplete="off" spellcheck="false" role="combobox" aria-expanded="false" aria-controls="list" />
+      <button id="clear" type="button" aria-label="Clear" title="Clear" hidden><svg viewBox="0 0 24 24" height="1rem" width="1rem" aria-hidden="true" focusable="false" fill="currentColor" xmlns="http://www.w3.org/2000/svg"><path fill="none" d="M0 0h24v24H0V0z"></path><path d="M12 2C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2zm4.29 12.89a.996.996 0 11-1.41 1.41L12 13.41 9.11 16.3a.996.996 0 11-1.41-1.41L10.59 12 7.71 9.11A.996.996 0 119.12 7.7L12 10.59l2.89-2.89a.996.996 0 111.41 1.41L13.41 12l2.88 2.89z"></path></svg></button>
+    </div>
+    <ul id="list" role="listbox" hidden></ul>
+  </div>
+</div>

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/searchbox/frontend/index.js

@@ -0,0 +1,155 @@
+export default function (component) {
+  const { data, parentElement, setStateValue, setTriggerValue } = component
+
+  const input = parentElement.querySelector("#input")
+  const list = parentElement.querySelector("#list")
+  const label = parentElement.querySelector("#label")
+  const clear = parentElement.querySelector("#clear")
+
+  // The script reruns after each query and this function runs again every time, so
+  // what the user is doing (open/closed, pending debounce) lives on the element.
+  const ui = (parentElement._searchbox ??= { open: false, index: 0, timer: null, picked: null })
+  const options = data.options ?? []
+
+  input.placeholder = data.placeholder ?? ""
+  input.title = data.help ?? ""
+  input.disabled = !!data.disabled
+  parentElement.querySelector("#box").classList.toggle("disabled", input.disabled)
+  label.hidden = !data.label
+  label.textContent = data.label ?? ""
+  label.className = data.labelVisibility === "visible" ? "" : "collapsed"
+  if (!ui.initialized) {
+    input.value = data.initial ?? ""
+    ui.initialized = true
+  }
+
+  // Fresh options from Python: highlight the first. Open state is left alone, so a
+  // rerun after a selection never pops the list back open.
+  ui.index = 0
+
+  function render() {
+    clear.hidden = !input.value || input.disabled
+    const show = ui.open && options.length > 0
+    list.hidden = !show
+    input.setAttribute("aria-expanded", String(show))
+    list.textContent = ""
+    options.forEach((text, i) => {
+      const li = document.createElement("li")
+      const span = document.createElement("span")
+      span.title = text
+      const term = input.value.trim()
+      const at = term ? text.toLowerCase().indexOf(term.toLowerCase()) : -1
+      if (at < 0) {
+        span.textContent = text
+      } else {
+        const strong = document.createElement("strong")
+        strong.textContent = text.slice(at, at + term.length)
+        span.append(text.slice(0, at), strong, text.slice(at + term.length))
+      }
+      li.appendChild(span)
+      li.role = "option"
+      li.className = i === ui.index ? "active" : ""
+      li.onmouseenter = () => highlight(i, false)
+      // mousedown fires before the input loses focus, so the click can't be lost
+      li.onmousedown = (e) => {
+        e.preventDefault()
+        select(i)
+      }
+      list.appendChild(li)
+    })
+    if (show) list.children[ui.index]?.scrollIntoView({ block: "nearest" })
+  }
+
+  function highlight(i, scroll = true) {
+    ui.index = i
+    ;[...list.children].forEach((li, n) => li.classList.toggle("active", n === i))
+    if (scroll) list.children[i]?.scrollIntoView({ block: "nearest" })
+  }
+
+  function close() {
+    ui.open = false
+    render()
+    input.blur()
+  }
+
+  function select(i) {
+    const value = options[i]
+    if (value === undefined) return
+    clearTimeout(ui.timer)
+    setStateValue("selected", value)
+    setTriggerValue("submitted", value)
+    if (data.clearOnSubmit) {
+      input.value = ""
+      setStateValue("query", "")
+    } else {
+      input.value = value
+      ui.picked = value
+    }
+    close()
+  }
+
+  // mousedown keeps focus in the input; the click clears text and the picked result
+  clear.onmousedown = (e) => e.preventDefault()
+  clear.onclick = () => {
+    clearTimeout(ui.timer)
+    ui.picked = null
+    input.value = ""
+    setStateValue("selected", "")
+    setStateValue("query", "")
+    input.focus()
+    render()
+  }
+
+  function changed() {
+    ui.open = true
+    clearTimeout(ui.timer)
+    const text = input.value
+    ui.timer = setTimeout(() => setStateValue("query", text), data.debounce ?? 250)
+    render()
+  }
+
+  // Typing over a picked result replaces it instead of appending to it. Changing the
+  // value inside beforeinput drops the pending keystroke, so apply the edit ourselves.
+  input.onbeforeinput = (e) => {
+    if (ui.picked === null || input.value !== ui.picked) return
+    ui.picked = null
+    e.preventDefault()
+    input.value = e.inputType.startsWith("insert") ? (e.data ?? e.dataTransfer?.getData("text") ?? "") : ""
+    changed()
+  }
+  input.oninput = changed
+  input.onfocus = () => {
+    ui.open = true
+    render()
+  }
+  input.onblur = () => {
+    ui.open = false
+    render()
+  }
+  input.onkeydown = (e) => {
+    if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+      e.preventDefault()
+      if (!options.length) return
+      if (!ui.open) {
+        ui.open = true
+        render()
+        return
+      }
+      const step = e.key === "ArrowDown" ? 1 : -1
+      highlight((ui.index + step + options.length) % options.length)
+    } else if (e.key === "Enter") {
+      e.preventDefault()
+      if (ui.open && options.length) select(ui.index)
+      else input.blur()
+    } else if (e.key === "Escape") {
+      e.preventDefault()
+      close()
+    }
+  }
+
+  render()
+
+  return () => {
+    clear.onclick = clear.onmousedown = input.onbeforeinput = input.oninput = input.onfocus = input.onblur = input.onkeydown = null
+  }
+}

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/searchbox/frontend/style.css

@@ -0,0 +1,130 @@
+:host {
+  display: block;
+}
+
+#wrap {
+  --primary: var(--st-primary-color, #ff4b4b);
+  --bg: var(--st-background-color, #fff);
+  --sec-bg: var(--st-secondary-background-color, #f0f2f6);
+  --text: var(--st-text-color, #31333f);
+  --font: var(--st-font, sans-serif);
+  --border: var(--st-border-color, rgba(128, 128, 128, 0.4));
+
+  font-family: var(--font);
+  color: var(--text);
+}
+
+#label {
+  display: block;
+  margin-bottom: 0.25rem;
+  min-height: 1.5rem;
+  font-size: 0.875rem;
+  line-height: 1.6;
+}
+#label[hidden] { display: none; }
+#label.collapsed {
+  display: block;
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+}
+
+#field { position: relative; }
+
+/* Measured against st.selectbox: 40px box, 1px border in the secondary background
+   colour (primary when focused), 14px text, 8px padding. */
+#box {
+  display: flex;
+  box-sizing: border-box;
+  width: 100%;
+  height: 2.5rem;
+  border: 1px solid var(--sec-bg);
+  border-radius: var(--st-button-radius, 0.5rem);
+  background: var(--sec-bg);
+}
+#box:focus-within { border-color: var(--primary); }
+#box.disabled { opacity: 0.4; cursor: not-allowed; }
+
+input {
+  flex: 1 1 0%;
+  min-width: 0.125rem;
+  padding: 0.5rem;
+  border: none;
+  outline: none;
+  background: none;
+  font: inherit;
+  font-size: 0.875rem;
+  line-height: 1.4;
+  font-weight: 400;
+  color: var(--text);
+  caret-color: var(--text);
+  box-sizing: border-box;
+}
+input:disabled { cursor: not-allowed; }
+input::placeholder { color: color-mix(in srgb, var(--text) 60%, transparent); opacity: 1; }
+
+ul {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  right: 0;
+  z-index: 1000;
+  box-sizing: border-box;
+  max-height: calc(300px + 2px);
+  margin: 0;
+  padding: 0;
+  overflow-y: auto;
+  list-style: none;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--st-button-radius, 0.5rem);
+}
+ul[hidden] { display: none; }
+
+/* 40px rows with a 28px rounded highlight inset 5px/6px, like the native options */
+li {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  height: 40px;
+  padding: 0 5px;
+  cursor: pointer;
+  font-size: 0.875rem;
+  line-height: 1.6;
+}
+li > span {
+  flex: 1;
+  min-width: 0;
+  padding: 0 8px;
+  line-height: 28px;
+  border-radius: 6px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+li > span strong { font-weight: 600; }
+li.active > span { background: rgba(172, 177, 195, 0.15); }
+
+#clear {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  align-self: center;
+  flex-shrink: 0;
+  font-size: 1rem;
+  margin-right: 0.25rem;: 0.5rem;
+  padding: 0.125rem;
+  width: 1.5em;
+  height: 1.5em;
+  border: none;
+  outline: none;
+  border-radius: 0.5rem;
+  background: none;
+  cursor: pointer;
+  color: color-mix(in srgb, var(--text) 60%, transparent);
+}
+#clear:hover { color: var(--text); }
+#clear:focus-visible { box-shadow: color-mix(in srgb, var(--primary) 50%, transparent) 0 0 0 0.2rem; }
+#clear[hidden] { display: none; }

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/stateful_button/__init__.py

@@ -0,0 +1,150 @@
+"""A st.button look-alike that disables itself while your script is busy."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import streamlit as st
+
+_FRONTEND = Path(__file__).parent / "frontend"
+
+
+def _read(name: str) -> str:
+    return (_FRONTEND / name).read_text(encoding="utf-8")
+
+
+# Registered once at import time (re-registering the same name causes warnings)
+_COMPONENT = st.components.v2.component(
+    "stateful_button",
+    html=_read("index.html"),
+    css=_read("style.css"),
+    js=_read("index.js"),
+)
+
+
+class StatefulButton:
+    """Returned by `stateful_button`. Use it as a bool, a context manager, or both."""
+
+    def __init__(self, clicked: bool, release):
+        self.clicked = clicked
+        self._release = release
+        self._released = False
+
+    def release(self, success: bool = True) -> None:
+        # Only ever re-render once per run, or Streamlit complains about a duplicate key
+        if self.clicked and not self._released:
+            self._released = True
+            self._release(success)
+
+    def __bool__(self) -> bool:
+        return self.clicked
+
+    def __enter__(self) -> StatefulButton:
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        # Runs on success and on errors, so the button never gets stuck
+        self.release(exc_type is None)
+        return False
+
+
+def stateful_button(
+    label: str,
+    key: str | None = None,
+    help: str | None = None,
+    on_click=None,
+    args=None,
+    kwargs=None,
+    *,
+    type: str = "secondary",
+    icon: str | None = None,
+    icon_position: str = "left",
+    disabled: bool = False,
+    width: str | int = "content",
+    shortcut: str | None = None,
+    wrap: bool | None = None,
+) -> StatefulButton:
+    """Same parameters as `st.button`. Labels are plain text (no Markdown).
+
+    The button disables itself the moment it's clicked and shows a spinner in place
+    of its icon, then a tick when the work succeeds. Pick one way to do the work:
+
+        # Several lines, or you want to show results afterwards
+        with stateful_button("Submit") as clicked:
+            if clicked:
+                save_records()
+
+        # A single function call
+        stateful_button("Submit", on_click=save_records)
+
+    Without either, nothing tells the button when the work is done, so it keeps
+    spinning until the next rerun.
+    """
+    # Without a key, the same arguments give the same identity on every rerun
+    ident = key or hashlib.md5(
+        repr((label, type, icon, icon_position, width, shortcut)).encode()
+    ).hexdigest()[:10]
+    nonce_name = f"_stateful_button_nonce_{ident}"
+    done_name = f"_stateful_button_done_{ident}"
+    failed_name = f"_stateful_button_failed_{ident}"
+    nonce = st.session_state.get(nonce_name, 0)
+    # Must match what the browser is already showing, or the data changes and the
+    # button resets itself mid-click (losing its spinner and disabled state)
+    was_done = st.session_state.pop(done_name, False)
+
+    data = {
+        "label": label,
+        "help": help,
+        "type": type,
+        "icon": icon,
+        "iconPosition": icon_position,
+        "disabled": disabled,
+        "width": width,
+        "shortcut": shortcut,
+        "wrap": wrap,
+    }
+
+    def callback():
+        if on_click:
+            try:
+                on_click(*(args or ()), **(kwargs or {}))
+            except Exception as e:
+                # Raising here would abort the whole run before the button is drawn,
+                # so keep the error and raise it later in the script instead
+                st.session_state[failed_name] = e
+
+    def mount(n: int, done: bool = False):
+        # A new nonce means a new component identity, which gives a fresh idle button
+        return _COMPONENT(
+            key=f"{ident}-{n}",
+            data={**data, "done": done},
+            width=width,
+            on_clicked_change=callback,
+        )
+
+    slot = st.empty()
+    with slot:
+        result = mount(nonce, done=was_done)
+
+    if not result.clicked:
+        return StatefulButton(False, lambda ok: None)
+
+    # The browser keeps the old button disabled. Bump the nonce so the next run
+    # (or the end of the `with` block) mounts a fresh, enabled one.
+    st.session_state[nonce_name] = nonce + 1
+
+    def release(success: bool):
+        # On success the fresh button briefly shows a tick before going back to normal
+        st.session_state[done_name] = success
+        with slot:
+            mount(nonce + 1, done=success)
+
+    button = StatefulButton(True, release)
+    if on_click:
+        # The callback already ran before this script started, so the work is finished
+        error = st.session_state.pop(failed_name, None)
+        button.release(error is None)
+        if error is not None:
+            raise error
+    return button

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/stateful_button/frontend/index.html

@@ -0,0 +1,4 @@
+<button id="btn" type="button">
+  <span id="icon" class="icon"></span>
+  <span id="label"></span>
+</button>

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/stateful_button/frontend/index.js

@@ -0,0 +1,93 @@
+const MATERIAL = /^:material\/([a-z0-9_]+):$/
+
+// Maps the key names Streamlit documents for `shortcut` to KeyboardEvent.key values
+const KEY_NAMES = {
+  esc: "Escape", space: " ", up: "ArrowUp", down: "ArrowDown", left: "ArrowLeft", right: "ArrowRight",
+  pageup: "PageUp", pagedown: "PageDown", enter: "Enter", tab: "Tab",
+  backspace: "Backspace", delete: "Delete", home: "Home", end: "End",
+}
+
+// "Cmd+Shift+O" -> a function that tests a KeyboardEvent
+function parseShortcut(text) {
+  const parts = text.split("+").map((p) => p.trim().toLowerCase())
+  const key = parts.pop()
+  const want = {
+    mod: parts.some((p) => ["ctrl", "cmd", "meta", "mod"].includes(p)),
+    alt: parts.some((p) => ["alt", "option"].includes(p)),
+    shift: parts.includes("shift"),
+  }
+  const expected = KEY_NAMES[key] ?? key
+  return (e) =>
+    e.key.toLowerCase() === expected.toLowerCase() &&
+    (e.ctrlKey || e.metaKey) === want.mod &&
+    e.altKey === want.alt &&
+    e.shiftKey === want.shift
+}
+
+function renderIcon(el, icon, busy, done) {
+  el.className = "icon"
+  el.textContent = ""
+  if (busy) {
+    el.className = "icon spinner"
+  } else if (done) {
+    el.className = "icon material-symbols"
+    el.textContent = "check"
+  } else if (icon) {
+    const match = MATERIAL.exec(icon)
+    el.textContent = match ? match[1] : icon
+    if (match) el.className = "icon material-symbols"
+  }
+}
+
+export default function (component) {
+  const { data, parentElement, setTriggerValue } = component
+
+  const btn = parentElement.querySelector("#btn")
+  const icon = parentElement.querySelector("#icon")
+  const label = parentElement.querySelector("#label")
+
+  btn.dataset.type = data.type
+  btn.dataset.width = data.width === "stretch" ? "stretch" : "content"
+  btn.dataset.iconPosition = data.iconPosition
+  btn.dataset.wrap = String(data.wrap !== false)
+  btn.style.width = typeof data.width === "number" ? `${data.width}px` : ""
+  btn.title = [data.help, data.shortcut && `(${data.shortcut})`].filter(Boolean).join(" ")
+  label.textContent = data.label
+  renderIcon(icon, data.icon, false, data.done)
+  btn.disabled = data.disabled || data.done
+
+  // After a successful run, show a tick for a moment, then restore the original icon
+  const timer = data.done
+    ? setTimeout(() => {
+        renderIcon(icon, data.icon, false, false)
+        btn.disabled = data.disabled
+      }, 1500)
+    : null
+
+  // Disable straight away in the browser, so a second click can't happen
+  // while Python is still working. Python re-renders the button when it's done.
+  function click() {
+    if (btn.disabled) return
+    btn.disabled = true
+    renderIcon(icon, data.icon, true)
+    setTriggerValue("clicked", true)
+  }
+  btn.onclick = click
+
+  let onKey = null
+  if (data.shortcut) {
+    const matches = parseShortcut(data.shortcut)
+    onKey = (e) => {
+      if (matches(e)) {
+        e.preventDefault()
+        click()
+      }
+    }
+    document.addEventListener("keydown", onKey)
+  }
+
+  return () => {
+    clearTimeout(timer)
+    onKey && document.removeEventListener("keydown", onKey)
+  }
+}

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components/stateful_button/frontend/style.css

@@ -0,0 +1,103 @@
+/* Approximation of the native st.button, driven by Streamlit's theme variables. */
+:host {
+  display: block;
+}
+
+button {
+  --primary: var(--st-primary-color, #ff4b4b);
+  --on-primary: #fff;
+  --hover-overlay: rgba(172, 177, 195, 0.15);
+  --active-overlay: rgba(172, 177, 195, 0.25);
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  box-sizing: border-box;
+  min-height: 2.5rem;
+  max-width: 100%;
+  padding: 0.25rem 0.75rem;
+  border: 1px solid var(--st-border-color);
+  border-radius: var(--st-button-radius, 0.5rem);
+  background: color-mix(in srgb, var(--st-secondary-background-color) 30%, var(--st-background-color));
+  color: var(--st-text-color);
+  font-family: var(--st-font, sans-serif);
+  font-size: 1rem;
+  font-weight: var(--st-base-font-weight, 400);
+  line-height: 1.6;
+  cursor: pointer;
+  transition: color 0.15s, background-color 0.15s, border-color 0.15s;
+}
+
+/* Layout options: width and icon side */
+button[data-width="stretch"] { width: 100%; }
+button[data-icon-position="right"] { flex-direction: row-reverse; }
+
+/* Label: wrap onto extra lines, or stay on one row with an ellipsis */
+#label { min-width: 0; font-size: 0.875rem; line-height: 1.6; }
+button[data-wrap="true"] #label { white-space: normal; overflow-wrap: anywhere; }
+button[data-wrap="false"] #label { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+
+/* Icons */
+.icon:empty:not(.spinner) { display: none; }
+/* Every icon (emoji, Material, spinner, tick) gets the same box so the button never resizes */
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 1rem;
+  height: 1rem;
+}
+.material-symbols {
+  font-family: "Material Symbols Rounded";
+  font-size: 1rem;
+  line-height: 1;
+  font-weight: normal;
+  font-feature-settings: "liga";
+  -webkit-font-feature-settings: "liga";
+}
+
+/* Spinner shown while the script is working. The ring spins inside the standard icon box. */
+.spinner::before {
+  content: "";
+  box-sizing: border-box;
+  width: 0.875rem;
+  height: 0.875rem;
+  border: 2px solid currentColor;
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+
+/* Secondary (default): hover and active only tint the background */
+button:hover:not(:disabled) { background-image: linear-gradient(var(--hover-overlay), var(--hover-overlay)); }
+button:active:not(:disabled) { background-image: linear-gradient(var(--active-overlay), var(--active-overlay)); }
+
+/* Primary (darker shades are the primary colour with lightness reduced) */
+button[data-type="primary"] { background: var(--primary); border-color: var(--primary); color: var(--on-primary); }
+button[data-type="primary"]:hover:not(:disabled) {
+  background: hsl(from var(--primary) h s calc(l - 15));
+  border-color: hsl(from var(--primary) h s calc(l - 15));
+  background-image: none;
+}
+button[data-type="primary"]:active:not(:disabled) {
+  background: var(--primary);
+  border-color: hsl(from var(--primary) h s calc(l - 15));
+  background-image: none;
+}
+
+/* Tertiary: no border, no padding, text changes colour */
+button[data-type="tertiary"] { background: transparent; border: 0; padding: 0; }
+button[data-type="tertiary"]:hover:not(:disabled) { color: var(--primary); background-image: none; }
+button[data-type="tertiary"]:active:not(:disabled) { color: hsl(from var(--primary) h s calc(l - 25)); background-image: none; }
+
+button:focus-visible { outline: none; box-shadow: 0 0 0 0.2rem color-mix(in srgb, var(--primary) 50%, transparent); }
+button:focus-visible:not(:disabled):not([data-type="primary"]):not([data-type="tertiary"]) { background-image: linear-gradient(var(--hover-overlay), var(--hover-overlay)); }
+
+button:disabled {
+  background: transparent;
+  color: color-mix(in srgb, var(--st-text-color) 40%, transparent);
+  cursor: not-allowed;
+}

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: streamlit-vanilla-components
+Version: 0.1.0
+Summary: Vanilla HTML/CSS/JS Streamlit components with no npm dependencies.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/lukehorton1/streamlit-vanilla-components
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: streamlit>=1.57
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# Streamlit vanilla components
+
+Lightweight [Streamlit components v2](https://docs.streamlit.io/develop/api-reference/custom-components) in plain HTML, CSS and JavaScript. No npm packages, no build step. Each component copies its native Streamlit look and follows the active theme.
+
+Built using GitHub Copilot as an AI coding agent, with manual oversight, design and testing throughout.
+
+```python
+from streamlit_vanilla_components import st_live_searchbox, stateful_button
+```
+
+Run the demo with `streamlit run example.py`.
+
+## Installation
+
+```bash
+pip install streamlit-vanilla-components
+```
+
+Or install straight from GitHub:
+
+```bash
+pip install "git+https://github.com/lukehorton1/streamlit-vanilla-components.git"
+```
+
+Requires Python 3.10+ and Streamlit 1.57+.
+
+## Components
+
+- [`st_live_searchbox`](#st_live_searchbox)
+- [`stateful_button`](#stateful_button)
+
+---
+
+## `st_live_searchbox`
+
+A search box whose dropdown is filled by your Python function as the user types. Returns the picked option as a string.
+
+```python
+def search_places(term: str) -> list[str]:
+    return db.query("SELECT label FROM places WHERE label ILIKE %s LIMIT 300", f"%{term}%")
+
+choice = st_live_searchbox(search_places, placeholder="Search a place...", rank=True, max_results=50)
+```
+
+### Parameters
+
+| Parameter | Description |
+|---|---|
+| `search_fn` *(callable)* | Receives the typed text and returns a list of options. Required. |
+| `placeholder` *(str)* | Placeholder text. Default `"Type to search..."`. |
+| `key` *(str)* | Widget key. Default `"live_search"`. |
+| `on_change` *(callable or None)* | Runs when the typed text changes. |
+| `on_submit` *(callable or None)* | Runs when an option is picked. |
+| `args` *(tuple or None)* | Passed to `on_change` and `on_submit`. |
+| `kwargs` *(dict or None)* | Passed to `on_change` and `on_submit`. |
+| `debounce` *(int)* | Milliseconds to wait after typing stops before searching. Default `250`. |
+| `default` *(str or None)* | Returned until something is picked. Default `None`. |
+| `label` *(str or None)* | Label above the box. |
+| `label_visibility` *(str)* | `"visible"`, `"hidden"` or `"collapsed"`. Default `"visible"`. |
+| `help` *(str or None)* | Tooltip next to the label. |
+| `disabled` *(bool)* | Disables the box. Default `False`. |
+| `min_chars` *(int)* | Characters typed before `search_fn` runs. Default `1`. |
+| `max_results` *(int or None)* | Maximum options shown, applied after ranking. Default `None`. |
+| `rank` *(bool)* | Sorts options by match quality (exact, starts with, word starts with, contains). Default `False`. |
+| `clear_on_submit` *(bool)* | Empties the box after a pick. Default `False`. |
+| `width` *(str or int)* | `"stretch"` or a pixel width. Default `"stretch"`. |
+
+**Returns** *(str or None)*: the picked option, or `default`.
+
+### See also
+
+- Typing again after a pick replaces it with the new text.
+- Ranking only sees what `search_fn` returns, so return more candidates than `max_results`.
+
+---
+
+## `stateful_button`
+
+A `st.button` look-alike that disables itself on click, shows a spinner in place of its icon while your code runs, then a tick on success.
+
+```python
+with stateful_button("Submit", type="primary") as clicked:
+    if clicked:
+        save_records()
+        st.success("Saved!")
+
+# or, for a single function call
+stateful_button("Run job", on_click=run_job, args=("Job 1",))
+```
+
+### Parameters
+
+Same as `st.button`, plus `icon_position` and `wrap`.
+
+| Parameter | Description |
+|---|---|
+| `label` *(str)* | Button text. Plain text, no Markdown. Required. |
+| `key` *(str or None)* | Widget key. Derived from the other arguments if omitted. |
+| `help` *(str or None)* | Tooltip. |
+| `on_click` *(callable or None)* | Work to run. The button stays busy until it finishes. |
+| `args` *(tuple or None)* | Passed to `on_click`. |
+| `kwargs` *(dict or None)* | Passed to `on_click`. |
+| `type` *(str)* | `"primary"`, `"secondary"` or `"tertiary"`. Default `"secondary"`. |
+| `icon` *(str or None)* | Emoji or `:material/name:`. |
+| `icon_position` *(str)* | `"left"` or `"right"`. Default `"left"`. |
+| `disabled` *(bool)* | Disables the button. Default `False`. |
+| `width` *(str or int)* | `"content"`, `"stretch"` or a pixel width. Default `"content"`. |
+| `shortcut` *(str or None)* | Keyboard shortcut. |
+| `wrap` *(bool or None)* | Whether the label may wrap. |
+
+**Returns** *(StatefulButton)*: truthy on the run it was clicked. Works as a context manager, and `.release(success=True)` ends the busy state early.
+
+### See also
+
+- Use either the `with` form or `on_click`. Without either, the spinner never stops.
+- Errors in the `with` block or in `on_click` re-enable the button, then raise.

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+streamlit_vanilla_components/__init__.py
+streamlit_vanilla_components.egg-info/PKG-INFO
+streamlit_vanilla_components.egg-info/SOURCES.txt
+streamlit_vanilla_components.egg-info/dependency_links.txt
+streamlit_vanilla_components.egg-info/requires.txt
+streamlit_vanilla_components.egg-info/top_level.txt
+streamlit_vanilla_components/searchbox/__init__.py
+streamlit_vanilla_components/searchbox/frontend/index.html
+streamlit_vanilla_components/searchbox/frontend/index.js
+streamlit_vanilla_components/searchbox/frontend/style.css
+streamlit_vanilla_components/stateful_button/__init__.py
+streamlit_vanilla_components/stateful_button/frontend/index.html
+streamlit_vanilla_components/stateful_button/frontend/index.js
+streamlit_vanilla_components/stateful_button/frontend/style.css
+tests/test_smoke.py

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components.egg-info/requires.txt

@@ -0,0 +1,4 @@
+streamlit>=1.57
+
+[dev]
+pytest>=8

streamlit_vanilla_components-0.1.0/streamlit_vanilla_components.egg-info/top_level.txt

@@ -0,0 +1 @@
+streamlit_vanilla_components

streamlit_vanilla_components-0.1.0/tests/test_smoke.py

@@ -0,0 +1,54 @@
+"""Smoke tests: the package imports, ships its frontend assets, and renders in a Streamlit app."""
+
+from pathlib import Path
+
+import pytest
+from streamlit.testing.v1 import AppTest
+
+import streamlit_vanilla_components as svc
+from streamlit_vanilla_components.searchbox import _rank
+
+PACKAGE_DIR = Path(svc.__file__).parent
+FRONTEND_DIRS = [PACKAGE_DIR / "searchbox" / "frontend", PACKAGE_DIR / "stateful_button" / "frontend"]
+
+
+def test_public_api_exports():
+    assert callable(svc.st_live_searchbox)
+    assert callable(svc.stateful_button)
+    assert set(svc.__all__) == {"st_live_searchbox", "stateful_button"}
+
+
+@pytest.mark.parametrize("folder", FRONTEND_DIRS, ids=lambda p: p.parent.name)
+@pytest.mark.parametrize("name", ["index.html", "index.js", "style.css"])
+def test_frontend_assets_present(folder, name):
+    path = folder / name
+    assert path.is_file(), f"missing {path}"
+    assert path.read_text(encoding="utf-8").strip(), f"empty {path}"
+
+
+def test_rank_puts_exact_matches_before_partial_matches():
+    options = ["Old Liverpool", "Liverpool, United Kingdom", "Liverpool"]
+    ranked = _rank(options, "liverpool")
+    assert ranked[-1] == "Old Liverpool"
+    assert set(ranked[:2]) == {"Liverpool, United Kingdom", "Liverpool"}
+
+
+def test_rank_blank_term_keeps_order():
+    options = ["b", "a"]
+    assert _rank(options, "  ") == options
+
+
+def test_stateful_button_renders_in_app():
+    # AppTest uses a fresh component registry per run; the module-level
+    # registration only happens on import, so reload it inside the script.
+    script = """
+import importlib
+import streamlit as st
+
+sb = importlib.import_module("streamlit_vanilla_components.stateful_button")
+importlib.reload(sb)
+if sb.stateful_button("Go", key="go"):
+    st.write("clicked")
+"""
+    at = AppTest.from_string(script).run()
+    assert not at.exception