shinyhub-bookmarks 0.2.0__tar.gz

shinyhub_bookmarks-0.2.0/.gitignore

@@ -0,0 +1,61 @@
+.superpowers/
+docs/superpowers/
+# Raw HTML under docs is an internal design/review artifact, not product
+# documentation. Keep reports and their assets out of Git and deployments.
+/docs/**/*.html
+/docs/reports/
+/scripts/docs-smoke.py
+.claire/
+.codex/
+.impeccable/
+go.work
+go.work.sum
+bin/
+tmp/
+.worktrees/
+.claude/investigations/
+CLAUDE.md
+CLAUDE.local.md
+
+# Product positioning and brand direction, maintained by local tooling rather
+# than as a repo artifact. Nothing in the build or the docs site reads it.
+PRODUCT.md
+
+# JS toolchain (only used for JSDOM tests of UI assets)
+node_modules/
+
+# Compiled server binary from `go build` at the repo root.
+/shinyhub
+
+# Runtime artifacts created when running the server from a checkout
+# (default config writes the SQLite DB and per-app data under ./data).
+/shinyhub.yaml
+/data/
+/site/
+/deploy/demo/.env
+*.db
+*.db-shm
+*.db-wal
+
+# PyPI wheel build artifacts
+/packaging/python/src/shinyhub/_binary/shinyhub
+/packaging/python/dist/
+/packaging/python/build/
+/packaging/python/src/shinyhub.egg-info/
+/packaging/python/__pycache__/
+
+# Python bytecode (repo-wide; the render-rig test suites generate it)
+__pycache__/
+
+# npm install artifact from the render-rig driver, not a deliverable
+loadtest/render/driver/package-lock.json
+
+# Local investigation scratch. Not shipped, and it carries customer names
+# that must never reach a committed file.
+research/
+
+# Local prototypes kept beside the repo, never part of a build.
+experiments/
+
+# macOS Finder metadata.
+.DS_Store

shinyhub_bookmarks-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: shinyhub-bookmarks
+Version: 0.2.0
+Summary: Let ShinyHub visitors create selective URL bookmarks for Python Shiny apps.
+Project-URL: Homepage, https://github.com/rvben/shinyhub
+Project-URL: Repository, https://github.com/rvben/shinyhub
+Project-URL: Issues, https://github.com/rvben/shinyhub/issues
+Author-email: "Ruben J. Jongejan" <ruben.jongejan@gmail.com>
+License-Expression: MIT
+Keywords: bookmark,shiny,shinyhub,state
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: shiny<2,>=1.6.4
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=1.2; extra == 'test'
+Requires-Dist: pytest>=9; extra == 'test'
+Description-Content-Type: text/markdown
+
+# shinyhub-bookmarks
+
+Selective URL bookmarks for Python Shiny apps running in ShinyHub.
+
+The package registers the filters an app author considers meaningful. ShinyHub
+then adds a **Bookmark this view** control to its app switcher. Visitors see a
+plain-language receipt, can copy the exact view immediately, or customise which
+registered filters follow the link. Unselected filters return to the app's
+defaults when the bookmark opens.
+
+```python
+from shiny import App, render, ui
+from shinyhub_bookmarks import ChoiceRestore, Field, bookmarking_dependency, register
+
+
+def app_ui(request):
+    return ui.page_fluid(
+        bookmarking_dependency(),
+        ui.input_select("region", "Region", ["Europe", "Americas", "Asia"]),
+        ui.input_slider("year", "Year", 2020, 2026, 2026),
+        ui.output_text_verbatim("summary"),
+    )
+
+
+def server(input, output, session):
+    register(
+        session=session,
+        input=input,
+        fields={
+            "region": Field("Region"),
+            "year": Field("Year"),
+        },
+    )
+
+    @render.text
+    def summary():
+        return f"{input.region()} · {input.year()}"
+
+
+app = App(app_ui, server, bookmark_store="url")
+```
+
+Both pieces are required: `bookmarking_dependency()` installs the tiny browser
+bridge, and `register()` publishes the allow-list and creates links through
+Shiny's native bookmarking API. The UI must be a function accepting `request`
+so Shiny can restore URL state before rendering it.
+
+## Bookmarks that outlive the app
+
+Native Shiny restoration ignores a removed input, but a retired choice can
+otherwise become empty or fall back differently across widgets. Declare current
+choices when a bookmark should remain dependable across app releases:
+
+```python
+register(
+    session=session,
+    input=input,
+    schema_version=3,
+    legacy_fields={"segment": "Market segment"},
+    fields={
+        "region": Field(
+            "Region",
+            restore=ChoiceRestore(choices=REGIONS, default="Europe"),
+            renamed_from={"territory": "Territory"},
+        ),
+        "product": Field(
+            "Product",
+            restore=ChoiceRestore(
+                choices=lambda: PRODUCTS,
+                default="All products",
+                aliases={"Legacy planning": "Planning"},
+                control="select",
+            ),
+        ),
+    },
+)
+```
+
+`ChoiceRestore` validates the saved value, applies aliases, and updates the
+current Shiny choice input. Supported controls are `select`, `selectize`, and
+`radio`. Multiple selections retain every choice that still exists. A missing
+declared default falls back to the valid value Shiny already selected.
+
+`renamed_from` maps an old input ID to its former label. `legacy_fields` names
+removed inputs that should be reported as ignored. Every new link records the
+app's `schema_version`; older links without metadata remain supported.
+
+When anything changes, the switcher marks the bookmark action and presents a
+plain-language **View adjusted** receipt. It names migrated, unavailable,
+renamed, and removed filters and offers **Copy updated link**. The app still
+opens; stale state is never promoted into a blocking error.
+
+An input that is neither registered nor declared as renamed or removed is shown
+with its URL-provided ID and saved value, labelled **Unknown**. Both are rendered
+as bounded plain text. At most three unknown inputs are listed before a compact
+overflow summary. Copying the updated link drops every unknown setting, so the
+warning clears on the next visit.
+
+## Privacy and behaviour
+
+- The browser-local ShinyHub switcher receives the registered display values and
+  generated URL so it can show the receipt and copy the link. The ShinyHub
+  server neither receives nor persists bookmark state; selected values stay in
+  Shiny's URL.
+- Every registered field is selected by default, including values equal to the
+  app's current defaults. The receipt makes that scope explicit before copying.
+- App inputs not registered here are always excluded.
+- A custom bookmark with no selected fields cannot be created.
+- URLs over 8 KiB are rejected by default. Raise `max_url_length` only when the
+  complete delivery path is known to accept longer URLs.
+- The control stays absent when the bridge is not installed, so unsupported apps
+  never show a dead action.

shinyhub_bookmarks-0.2.0/README.md

@@ -0,0 +1,112 @@
+# shinyhub-bookmarks
+
+Selective URL bookmarks for Python Shiny apps running in ShinyHub.
+
+The package registers the filters an app author considers meaningful. ShinyHub
+then adds a **Bookmark this view** control to its app switcher. Visitors see a
+plain-language receipt, can copy the exact view immediately, or customise which
+registered filters follow the link. Unselected filters return to the app's
+defaults when the bookmark opens.
+
+```python
+from shiny import App, render, ui
+from shinyhub_bookmarks import ChoiceRestore, Field, bookmarking_dependency, register
+
+
+def app_ui(request):
+    return ui.page_fluid(
+        bookmarking_dependency(),
+        ui.input_select("region", "Region", ["Europe", "Americas", "Asia"]),
+        ui.input_slider("year", "Year", 2020, 2026, 2026),
+        ui.output_text_verbatim("summary"),
+    )
+
+
+def server(input, output, session):
+    register(
+        session=session,
+        input=input,
+        fields={
+            "region": Field("Region"),
+            "year": Field("Year"),
+        },
+    )
+
+    @render.text
+    def summary():
+        return f"{input.region()} · {input.year()}"
+
+
+app = App(app_ui, server, bookmark_store="url")
+```
+
+Both pieces are required: `bookmarking_dependency()` installs the tiny browser
+bridge, and `register()` publishes the allow-list and creates links through
+Shiny's native bookmarking API. The UI must be a function accepting `request`
+so Shiny can restore URL state before rendering it.
+
+## Bookmarks that outlive the app
+
+Native Shiny restoration ignores a removed input, but a retired choice can
+otherwise become empty or fall back differently across widgets. Declare current
+choices when a bookmark should remain dependable across app releases:
+
+```python
+register(
+    session=session,
+    input=input,
+    schema_version=3,
+    legacy_fields={"segment": "Market segment"},
+    fields={
+        "region": Field(
+            "Region",
+            restore=ChoiceRestore(choices=REGIONS, default="Europe"),
+            renamed_from={"territory": "Territory"},
+        ),
+        "product": Field(
+            "Product",
+            restore=ChoiceRestore(
+                choices=lambda: PRODUCTS,
+                default="All products",
+                aliases={"Legacy planning": "Planning"},
+                control="select",
+            ),
+        ),
+    },
+)
+```
+
+`ChoiceRestore` validates the saved value, applies aliases, and updates the
+current Shiny choice input. Supported controls are `select`, `selectize`, and
+`radio`. Multiple selections retain every choice that still exists. A missing
+declared default falls back to the valid value Shiny already selected.
+
+`renamed_from` maps an old input ID to its former label. `legacy_fields` names
+removed inputs that should be reported as ignored. Every new link records the
+app's `schema_version`; older links without metadata remain supported.
+
+When anything changes, the switcher marks the bookmark action and presents a
+plain-language **View adjusted** receipt. It names migrated, unavailable,
+renamed, and removed filters and offers **Copy updated link**. The app still
+opens; stale state is never promoted into a blocking error.
+
+An input that is neither registered nor declared as renamed or removed is shown
+with its URL-provided ID and saved value, labelled **Unknown**. Both are rendered
+as bounded plain text. At most three unknown inputs are listed before a compact
+overflow summary. Copying the updated link drops every unknown setting, so the
+warning clears on the next visit.
+
+## Privacy and behaviour
+
+- The browser-local ShinyHub switcher receives the registered display values and
+  generated URL so it can show the receipt and copy the link. The ShinyHub
+  server neither receives nor persists bookmark state; selected values stay in
+  Shiny's URL.
+- Every registered field is selected by default, including values equal to the
+  app's current defaults. The receipt makes that scope explicit before copying.
+- App inputs not registered here are always excluded.
+- A custom bookmark with no selected fields cannot be created.
+- URLs over 8 KiB are rejected by default. Raise `max_url_length` only when the
+  complete delivery path is known to accept longer URLs.
+- The control stays absent when the bridge is not installed, so unsupported apps
+  never show a dead action.

shinyhub_bookmarks-0.2.0/RELEASING.md

@@ -0,0 +1,36 @@
+# Releasing shinyhub-bookmarks
+
+`shinyhub-bookmarks` is versioned independently from the ShinyHub server. A
+release is built from an immutable package-specific tag and published through
+PyPI Trusted Publishing with `uv publish`; no long-lived API token is used.
+
+## First release only
+
+Before pushing the first tag, add a pending GitHub publisher under the PyPI
+account's **Publishing** settings:
+
+- PyPI project name: `shinyhub-bookmarks`
+- GitHub owner: `rvben`
+- Repository: `shinyhub`
+- Workflow: `publish-bookmarks.yml`
+- Environment: `pypi`
+
+The pending publisher creates the project on its first successful upload. It
+does not reserve the name before then.
+
+## Release checklist
+
+1. Update `project.version` in `pyproject.toml` and `__version__` in
+   `src/shinyhub_bookmarks/__init__.py` in the same commit.
+2. Run `make test-py-bookmarks` and the repository's JavaScript test suite.
+3. Build both distributions with `uv build --no-sources` and validate their
+   metadata with a current Twine release.
+4. Merge the release commit to `main`.
+5. Tag that exact commit as `shinyhub-bookmarks-v<version>` and push the tag.
+6. Wait for the **publish shinyhub-bookmarks** workflow to finish.
+7. Verify the version, files, project links, and Trusted Publisher attestation
+   on PyPI.
+
+The workflow rejects a tag whose version does not exactly match the package
+metadata. PyPI also rejects re-uploading an existing filename, so published
+versions are immutable; issue a patch release for any correction.

shinyhub_bookmarks-0.2.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shinyhub-bookmarks"
+version = "0.2.0"
+description = "Let ShinyHub visitors create selective URL bookmarks for Python Shiny apps."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Ruben J. Jongejan", email = "ruben.jongejan@gmail.com" },
+]
+keywords = ["shinyhub", "shiny", "bookmark", "state"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+  "shiny>=1.6.4,<2",
+]
+
+[project.urls]
+Homepage   = "https://github.com/rvben/shinyhub"
+Repository = "https://github.com/rvben/shinyhub"
+Issues     = "https://github.com/rvben/shinyhub/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=9", "pytest-asyncio>=1.2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shinyhub_bookmarks"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

shinyhub_bookmarks-0.2.0/src/shinyhub_bookmarks/__init__.py

@@ -0,0 +1,16 @@
+"""Selective URL bookmarking for Python Shiny apps hosted by ShinyHub."""
+
+__version__ = "0.2.0"
+
+from ._adapter import Field, Registration, register
+from ._dependency import bookmarking_dependency
+from ._restore import Adjustment, ChoiceRestore
+
+__all__ = [
+    "Adjustment",
+    "ChoiceRestore",
+    "Field",
+    "Registration",
+    "bookmarking_dependency",
+    "register",
+]