streamlit-sortable-multiselect 0.7.3__tar.gz → 0.7.5__tar.gz

{streamlit_sortable_multiselect-0.7.3/streamlit_sortable_multiselect.egg-info → streamlit_sortable_multiselect-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: streamlit-sortable-multiselect
-Version: 0.7.3
+Version: 0.7.5
 Summary: A Streamlit custom component for selecting and reordering multiple string values.
 Author: Kentaro Aoki
 License-Expression: MIT
@@ -36,6 +36,12 @@ A Streamlit custom component for searching, selecting, and reordering multiple s
 python -m pip install streamlit-sortable-multiselect
 ```
 
+Upgrade an existing installation:
+
+```bash
+python -m pip install --upgrade streamlit-sortable-multiselect
+```
+
 For local development:
 
 ```bash
@@ -104,6 +110,17 @@ st.write(selected)
 | `selected_position` | `str` | `"bottom"` | Position of the selected item list relative to the search/add input. Use `"bottom"` or `"top"`. |
 | `icon_size` | `int` | `20` | Icon display size in pixels for `icon_url` images. Images are displayed inside a square area while preserving their aspect ratio. |
 | `options_max_height` | `int` | `190` | Maximum height in pixels for the available options dropdown. |
+| `suggestions_api_url` | `str \| None` | `None` | Absolute HTTP(S) endpoint used to fetch suggestions in the browser. `None` disables API suggestions. |
+| `suggestions_query_param` | `str` | `"q"` | Query parameter name used to send the current search text. |
+| `suggestions_response_path` | `str` | `""` | Dot-separated path to the suggestions array in the JSON response. Empty means the response root. |
+| `suggestions_label_path` | `str` | `"label"` | Dot-separated path to each suggestion's display label. |
+| `suggestions_value_path` | `str` | `"value"` | Dot-separated path to each suggestion's returned value. |
+| `suggestions_icon_url_path` | `str \| None` | `"icon_url"` | Optional dot-separated path to each suggestion's icon URL. `None` disables API icons. |
+| `suggestions_headers` | `Mapping[str, str] \| None` | `None` | HTTP headers sent with suggestions requests. Header values are visible to browser users and must not contain secrets. |
+| `suggestions_min_chars` | `int` | `1` | Minimum trimmed query length before requesting suggestions. Use `0` to allow an empty query. |
+| `suggestions_debounce_ms` | `int` | `300` | Delay in milliseconds between the latest input and the API request. |
+| `suggestions_loading_message` | `str` | `"Loading suggestions..."` | Message shown while an API request is in progress. |
+| `suggestions_error_message` | `str` | `"Failed to load suggestions"` | Message shown when the request or response cannot be processed. |
 | `key` | `str \| None` | `None` | Optional Streamlit component key. Use this when rendering multiple sortable multiselects. |
 
 Option dictionaries use this shape:
@@ -114,6 +131,54 @@ Option dictionaries use this shape:
 
 `icon_url` may be omitted. The returned value is always the `value`, not the display `label`.
 
+## API Suggestions
+
+Set `suggestions_api_url` to request suggestions as the user types. Static `options` that match the query are shown first, followed by API results. Duplicate `value` entries prefer the static option.
+
+```python
+selected = sortable_multiselect(
+    "Repositories",
+    options=[{"label": "Streamlit", "value": "streamlit/streamlit"}],
+    suggestions_api_url="https://api.example.com/repositories",
+    suggestions_query_param="query",
+    suggestions_response_path="data.items",
+    suggestions_label_path="name",
+    suggestions_value_path="full_name",
+    suggestions_icon_url_path="owner.avatar_url",
+    suggestions_headers={"X-Public-Client": "streamlit-app"},
+    suggestions_min_chars=2,
+    suggestions_debounce_ms=300,
+    suggestions_loading_message="Searching repositories...",
+    suggestions_error_message="Repository search is unavailable",
+)
+```
+
+The example above accepts a response such as:
+
+```json
+{
+  "data": {
+    "items": [
+      {
+        "name": "streamlit-sortable-multiselect",
+        "full_name": "example/streamlit-sortable-multiselect",
+        "owner": {
+          "avatar_url": "https://example.com/avatar.png"
+        }
+      }
+    ]
+  }
+}
+```
+
+Requests are made directly from the component iframe, so the endpoint must allow browser requests with CORS. Values in `suggestions_headers` are exposed to browser users. Do not pass API secrets, private bearer tokens, or other credentials. Use a server-side proxy when authentication must remain private.
+
+The component sends a `GET` request after the trimmed input reaches
+`suggestions_min_chars` and remains unchanged for `suggestions_debounce_ms`.
+Changing the input cancels the previous in-flight request. Set `options=[]` to
+use only API results. Selected API values remain selected when a later query
+returns different suggestions.
+
 Build the frontend before packaging or using release mode:
 
 ```bash
@@ -125,8 +190,30 @@ Run the example app:
 
 ```bash
 streamlit run examples/basic.py
+streamlit run examples/api_suggestions.py
+```
+
+`api_suggestions.py` starts a CORS-enabled sample API on a local random port, so
+it can be tried without a separate API process. This embedded server is intended
+for local development; use a separately deployed HTTPS API in remote deployments.
+The Streamlit page displays the address and port selected for the API. Test the
+endpoint from the same machine with:
+
+```bash
+curl "http://127.0.0.1:<displayed-port>/suggest?q=py"
+```
+
+Pass a fixed API port after `--` when needed:
+
+```bash
+streamlit run examples/api_suggestions.py -- --api-port 8765
 ```
 
+The embedded API binds to `127.0.0.1`. Because suggestions are fetched by the
+browser, it works only when the browser and Streamlit run on the same machine.
+For Docker, another computer, or a hosted Streamlit app, configure
+`suggestions_api_url` with a browser-accessible HTTPS endpoint instead.
+
 ## Release
 
 Build and check the distribution files:

{streamlit_sortable_multiselect-0.7.3 → streamlit_sortable_multiselect-0.7.5}/README.md

@@ -8,6 +8,12 @@ A Streamlit custom component for searching, selecting, and reordering multiple s
 python -m pip install streamlit-sortable-multiselect
 ```
 
+Upgrade an existing installation:
+
+```bash
+python -m pip install --upgrade streamlit-sortable-multiselect
+```
+
 For local development:
 
 ```bash
@@ -76,6 +82,17 @@ st.write(selected)
 | `selected_position` | `str` | `"bottom"` | Position of the selected item list relative to the search/add input. Use `"bottom"` or `"top"`. |
 | `icon_size` | `int` | `20` | Icon display size in pixels for `icon_url` images. Images are displayed inside a square area while preserving their aspect ratio. |
 | `options_max_height` | `int` | `190` | Maximum height in pixels for the available options dropdown. |
+| `suggestions_api_url` | `str \| None` | `None` | Absolute HTTP(S) endpoint used to fetch suggestions in the browser. `None` disables API suggestions. |
+| `suggestions_query_param` | `str` | `"q"` | Query parameter name used to send the current search text. |
+| `suggestions_response_path` | `str` | `""` | Dot-separated path to the suggestions array in the JSON response. Empty means the response root. |
+| `suggestions_label_path` | `str` | `"label"` | Dot-separated path to each suggestion's display label. |
+| `suggestions_value_path` | `str` | `"value"` | Dot-separated path to each suggestion's returned value. |
+| `suggestions_icon_url_path` | `str \| None` | `"icon_url"` | Optional dot-separated path to each suggestion's icon URL. `None` disables API icons. |
+| `suggestions_headers` | `Mapping[str, str] \| None` | `None` | HTTP headers sent with suggestions requests. Header values are visible to browser users and must not contain secrets. |
+| `suggestions_min_chars` | `int` | `1` | Minimum trimmed query length before requesting suggestions. Use `0` to allow an empty query. |
+| `suggestions_debounce_ms` | `int` | `300` | Delay in milliseconds between the latest input and the API request. |
+| `suggestions_loading_message` | `str` | `"Loading suggestions..."` | Message shown while an API request is in progress. |
+| `suggestions_error_message` | `str` | `"Failed to load suggestions"` | Message shown when the request or response cannot be processed. |
 | `key` | `str \| None` | `None` | Optional Streamlit component key. Use this when rendering multiple sortable multiselects. |
 
 Option dictionaries use this shape:
@@ -86,6 +103,54 @@ Option dictionaries use this shape:
 
 `icon_url` may be omitted. The returned value is always the `value`, not the display `label`.
 
+## API Suggestions
+
+Set `suggestions_api_url` to request suggestions as the user types. Static `options` that match the query are shown first, followed by API results. Duplicate `value` entries prefer the static option.
+
+```python
+selected = sortable_multiselect(
+    "Repositories",
+    options=[{"label": "Streamlit", "value": "streamlit/streamlit"}],
+    suggestions_api_url="https://api.example.com/repositories",
+    suggestions_query_param="query",
+    suggestions_response_path="data.items",
+    suggestions_label_path="name",
+    suggestions_value_path="full_name",
+    suggestions_icon_url_path="owner.avatar_url",
+    suggestions_headers={"X-Public-Client": "streamlit-app"},
+    suggestions_min_chars=2,
+    suggestions_debounce_ms=300,
+    suggestions_loading_message="Searching repositories...",
+    suggestions_error_message="Repository search is unavailable",
+)
+```
+
+The example above accepts a response such as:
+
+```json
+{
+  "data": {
+    "items": [
+      {
+        "name": "streamlit-sortable-multiselect",
+        "full_name": "example/streamlit-sortable-multiselect",
+        "owner": {
+          "avatar_url": "https://example.com/avatar.png"
+        }
+      }
+    ]
+  }
+}
+```
+
+Requests are made directly from the component iframe, so the endpoint must allow browser requests with CORS. Values in `suggestions_headers` are exposed to browser users. Do not pass API secrets, private bearer tokens, or other credentials. Use a server-side proxy when authentication must remain private.
+
+The component sends a `GET` request after the trimmed input reaches
+`suggestions_min_chars` and remains unchanged for `suggestions_debounce_ms`.
+Changing the input cancels the previous in-flight request. Set `options=[]` to
+use only API results. Selected API values remain selected when a later query
+returns different suggestions.
+
 Build the frontend before packaging or using release mode:
 
 ```bash
@@ -97,8 +162,30 @@ Run the example app:
 
 ```bash
 streamlit run examples/basic.py
+streamlit run examples/api_suggestions.py
+```
+
+`api_suggestions.py` starts a CORS-enabled sample API on a local random port, so
+it can be tried without a separate API process. This embedded server is intended
+for local development; use a separately deployed HTTPS API in remote deployments.
+The Streamlit page displays the address and port selected for the API. Test the
+endpoint from the same machine with:
+
+```bash
+curl "http://127.0.0.1:<displayed-port>/suggest?q=py"
+```
+
+Pass a fixed API port after `--` when needed:
+
+```bash
+streamlit run examples/api_suggestions.py -- --api-port 8765
 ```
 
+The embedded API binds to `127.0.0.1`. Because suggestions are fetched by the
+browser, it works only when the browser and Streamlit run on the same machine.
+For Docker, another computer, or a hosted Streamlit app, configure
+`suggestions_api_url` with a browser-accessible HTTPS endpoint instead.
+
 ## Release
 
 Build and check the distribution files:

{streamlit_sortable_multiselect-0.7.3 → streamlit_sortable_multiselect-0.7.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "streamlit-sortable-multiselect"
-version = "0.7.3"
+version = "0.7.5"
 description = "A Streamlit custom component for selecting and reordering multiple string values."
 readme = "README.md"
 requires-python = ">=3.9"

{streamlit_sortable_multiselect-0.7.3 → streamlit_sortable_multiselect-0.7.5}/streamlit_sortable_multiselect/__init__.py

@@ -5,10 +5,11 @@ from __future__ import annotations
 import os
 from pathlib import Path
 from typing import Any, Iterable, Mapping, Sequence, cast
+from urllib.parse import urlparse
 
 import streamlit.components.v1 as components
 
-__version__ = "0.7.3"
+__version__ = "0.7.5"
 __all__ = ["sortable_multiselect"]
 
 _COMPONENT_NAME = "streamlit_sortable_multiselect"
@@ -111,6 +112,59 @@ def _validate_options_max_height(options_max_height: int) -> int:
     return options_max_height
 
 
+def _validate_non_negative_int(name: str, value: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"{name} must be an integer.")
+    if value < 0:
+        raise ValueError(f"{name} must be 0 or greater.")
+    return value
+
+
+def _validate_optional_non_empty_string(name: str, value: str | None) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string or None.")
+    if not value:
+        raise ValueError(f"{name} must not be empty.")
+    return value
+
+
+def _validate_non_empty_string(name: str, value: str) -> str:
+    if not isinstance(value, str):
+        raise TypeError(f"{name} must be a string.")
+    if not value:
+        raise ValueError(f"{name} must not be empty.")
+    return value
+
+
+def _validate_suggestions_api_url(value: str | None) -> str | None:
+    validated = _validate_optional_non_empty_string("suggestions_api_url", value)
+    if validated is None:
+        return None
+
+    parsed = urlparse(validated)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ValueError("suggestions_api_url must be an absolute HTTP(S) URL.")
+    return validated
+
+
+def _normalize_suggestions_headers(
+    headers: Mapping[str, str] | None,
+) -> dict[str, str]:
+    if headers is None:
+        return {}
+    if not isinstance(headers, Mapping):
+        raise TypeError("suggestions_headers must be a mapping of strings to strings.")
+
+    result: dict[str, str] = {}
+    for name, value in headers.items():
+        if not isinstance(name, str) or not isinstance(value, str):
+            raise TypeError("suggestions_headers must contain only string keys and values.")
+        result[name] = value
+    return result
+
+
 def sortable_multiselect(
     label: str,
     options: Sequence[str | Mapping[str, Any]],
@@ -128,6 +182,17 @@ def sortable_multiselect(
     selected_position: str = "bottom",
     icon_size: int = 20,
     options_max_height: int = 190,
+    suggestions_api_url: str | None = None,
+    suggestions_query_param: str = "q",
+    suggestions_response_path: str = "",
+    suggestions_label_path: str = "label",
+    suggestions_value_path: str = "value",
+    suggestions_icon_url_path: str | None = "icon_url",
+    suggestions_headers: Mapping[str, str] | None = None,
+    suggestions_min_chars: int = 1,
+    suggestions_debounce_ms: int = 300,
+    suggestions_loading_message: str = "Loading suggestions...",
+    suggestions_error_message: str = "Failed to load suggestions",
     key: str | None = None,
 ) -> list[str]:
     """Select multiple string values and return them in user-defined order.
@@ -166,6 +231,28 @@ def sortable_multiselect(
         Icon display size in pixels. Images keep their aspect ratio within this square size.
     options_max_height:
         Maximum height in pixels for the available options dropdown.
+    suggestions_api_url:
+        Absolute HTTP(S) endpoint used to fetch suggestions. None disables API suggestions.
+    suggestions_query_param:
+        Query parameter name used to send the current search text.
+    suggestions_response_path:
+        Dot-separated path to the options array in the JSON response. Empty means the root.
+    suggestions_label_path:
+        Dot-separated path to each suggestion's display label.
+    suggestions_value_path:
+        Dot-separated path to each suggestion's returned value.
+    suggestions_icon_url_path:
+        Optional dot-separated path to each suggestion's icon URL.
+    suggestions_headers:
+        HTTP headers sent by the browser. Do not include secret credentials.
+    suggestions_min_chars:
+        Minimum query length before requesting suggestions.
+    suggestions_debounce_ms:
+        Delay in milliseconds between input and the suggestions request.
+    suggestions_loading_message:
+        Text shown while suggestions are loading.
+    suggestions_error_message:
+        Text shown when suggestions cannot be loaded.
     key:
         Optional Streamlit component key.
     """
@@ -199,18 +286,58 @@ def sortable_multiselect(
     max_selection_count = _validate_max_selections(max_selections)
     icon_size_value = _validate_icon_size(icon_size)
     options_max_height_value = _validate_options_max_height(options_max_height)
-
-    duplicate_options = sorted({value for value in option_values if option_values.count(value) > 1})
-    if duplicate_options:
+    suggestions_api_url_value = _validate_suggestions_api_url(suggestions_api_url)
+    suggestions_query_param_value = _validate_non_empty_string(
+        "suggestions_query_param", suggestions_query_param
+    )
+    if not isinstance(suggestions_response_path, str):
+        raise TypeError("suggestions_response_path must be a string.")
+    suggestions_label_path_value = _validate_non_empty_string(
+        "suggestions_label_path", suggestions_label_path
+    )
+    suggestions_value_path_value = _validate_non_empty_string(
+        "suggestions_value_path", suggestions_value_path
+    )
+    suggestions_icon_url_path_value = _validate_optional_non_empty_string(
+        "suggestions_icon_url_path", suggestions_icon_url_path
+    )
+    suggestions_headers_value = _normalize_suggestions_headers(suggestions_headers)
+    suggestions_min_chars_value = _validate_non_negative_int(
+        "suggestions_min_chars", suggestions_min_chars
+    )
+    suggestions_debounce_ms_value = _validate_non_negative_int(
+        "suggestions_debounce_ms", suggestions_debounce_ms
+    )
+    if not isinstance(suggestions_loading_message, str):
+        raise TypeError("suggestions_loading_message must be a string.")
+    if not isinstance(suggestions_error_message, str):
+        raise TypeError("suggestions_error_message must be a string.")
+
+    # Set membership keeps these checks O(n); list.count / `in list` here are
+    # O(n**2) and hang the rerun once options reaches tens of thousands.
+    seen_option_values: set[str] = set()
+    has_duplicate_options = False
+    for value in option_values:
+        if value in seen_option_values:
+            has_duplicate_options = True
+            break
+        seen_option_values.add(value)
+    if has_duplicate_options:
         raise ValueError("options must not contain duplicate values.")
 
-    missing_defaults = [value for value in default_values if value not in option_values]
+    missing_defaults = [value for value in default_values if value not in seen_option_values]
     if missing_defaults:
         missing = ", ".join(repr(value) for value in missing_defaults)
         raise ValueError(f"default contains values not present in options: {missing}.")
 
-    duplicate_defaults = sorted({value for value in default_values if default_values.count(value) > 1})
-    if duplicate_defaults:
+    seen_default_values: set[str] = set()
+    has_duplicate_defaults = False
+    for value in default_values:
+        if value in seen_default_values:
+            has_duplicate_defaults = True
+            break
+        seen_default_values.add(value)
+    if has_duplicate_defaults:
         raise ValueError("default must not contain duplicate values.")
 
     if max_selection_count is not None and len(default_values) > max_selection_count:
@@ -233,6 +360,17 @@ def sortable_multiselect(
         selected_position=selected_position,
         icon_size=icon_size_value,
         options_max_height=options_max_height_value,
+        suggestions_api_url=suggestions_api_url_value,
+        suggestions_query_param=suggestions_query_param_value,
+        suggestions_response_path=suggestions_response_path,
+        suggestions_label_path=suggestions_label_path_value,
+        suggestions_value_path=suggestions_value_path_value,
+        suggestions_icon_url_path=suggestions_icon_url_path_value,
+        suggestions_headers=suggestions_headers_value,
+        suggestions_min_chars=suggestions_min_chars_value,
+        suggestions_debounce_ms=suggestions_debounce_ms_value,
+        suggestions_loading_message=suggestions_loading_message,
+        suggestions_error_message=suggestions_error_message,
         key=key,
         default=default_values,
     )

streamlit_sortable_multiselect-0.7.5/streamlit_sortable_multiselect/frontend/build/assets/index-DGpJ50qI.css

@@ -0,0 +1 @@
+:root{font-family:system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;color:#111827}body{margin:0}button,input{font:inherit}.sortable-multiselect{box-sizing:border-box;width:100%;padding:2px 0 6px}.component-label{display:block;margin:0 0 6px;color:#31333f;font-size:14px;font-weight:400}.search-combobox{position:relative}.search-input{box-sizing:border-box;width:100%;min-height:38px;border:1px solid #d1d5db;border-radius:6px;background:#fff;color:#111827;padding:6px 10px}.search-input:focus{border-color:#ff4b4b;box-shadow:0 0 0 1px #ff4b4b;outline:none}.search-input:disabled{background:#f9fafb;color:#6b7280}.options-popover{background:#fff;border:1px solid #d1d5db;border-radius:6px;box-shadow:0 6px 18px #31333f24;box-sizing:border-box;left:0;margin:4px 0 0;padding:4px;position:absolute;right:0;top:100%;z-index:10}.options-scroll{box-sizing:border-box;list-style:none;margin:0;max-height:var(--options-max-height, 190px);overflow-y:auto;padding:0}.options-inner{list-style:none;margin:0;padding:0}.option-item,.option-empty{align-items:center;border-radius:4px;box-sizing:border-box;color:#111827;display:flex;gap:8px;min-height:32px;padding:7px 9px}.option-item{cursor:pointer;overflow:hidden}.option-label{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.option-item.highlighted,.option-item:hover{background:#f3f4f6}.option-empty{color:#6b7280}.option-status{border-bottom:1px solid #e5e7eb;color:#6b7280;font-size:13px;padding:7px 9px}.option-error{color:#b91c1c}.selected-list{display:flex;flex-direction:column;gap:6px;list-style:none;margin:8px 0 0;padding:0}.sortable-item{align-items:center;background:var(--item-bg, #ffffff);border:1px solid #d1d5db;border-radius:6px;box-sizing:border-box;color:var(--item-fg, #111827);display:grid;gap:8px;grid-template-columns:34px minmax(0,1fr) auto;min-height:40px;padding:4px}.sortable-item.with-number{grid-template-columns:34px 30px minmax(0,1fr) auto}.sortable-item.dragging{border-color:#ff4b4b;box-shadow:0 4px 12px #31333f24}.drag-handle,.item-actions button{align-items:center;background:transparent;border:1px solid transparent;border-radius:4px;color:var(--item-muted-fg, #374151);cursor:pointer;display:inline-flex;height:30px;justify-content:center;min-width:30px;padding:0 7px}.drag-handle:hover,.item-actions button:hover{background:#f3f4f6}.drag-handle:focus,.item-actions button:focus{border-color:#ff4b4b;outline:none}.drag-handle:disabled,.item-actions button:disabled{color:color-mix(in srgb,var(--item-muted-fg, #374151) 45%,transparent);cursor:not-allowed}.item-content{align-items:center;display:inline-flex;gap:8px;min-width:0}.item-label{min-width:0;overflow-wrap:anywhere}.item-icon,.option-icon{border-radius:4px;flex:0 0 auto;height:var(--icon-size, 20px);object-fit:contain;width:var(--icon-size, 20px)}.item-number{align-items:center;background:color-mix(in srgb,var(--item-bg, #f3f4f6) 72%,#ffffff);border-radius:999px;color:var(--item-fg, #4b5563);display:inline-flex;font-size:12px;font-weight:600;height:24px;justify-content:center;line-height:1;min-width:24px;padding:0 6px}.item-actions{display:inline-flex;gap:2px}.empty-state{border:1px dashed #d1d5db;border-radius:6px;color:#6b7280;margin-top:8px;padding:10px;text-align:center}.selected-position-top .selected-list,.selected-position-top .empty-state{margin:0 0 8px}