dash-startup-loading-plugin 0.2.0__tar.gz → 0.4.0__tar.gz

{dash_startup_loading_plugin-0.2.0/src/dash_startup_loading_plugin.egg-info → dash_startup_loading_plugin-0.4.0}/PKG-INFO

@@ -1,17 +1,15 @@
 Metadata-Version: 2.4
 Name: dash-startup-loading-plugin
-Version: 0.2.0
+Version: 0.4.0
 Summary: A configurable full-screen startup loading overlay for Dash apps, packaged as a Dash Hooks plugin.
 Author-email: Ethan Zhang <ethan.zhang2016@gmail.com>
 License-Expression: MIT
-Keywords: dash,plotly,loading,plugin,hooks
+Keywords: dash,plotly,loading,plugin
 Classifier: Framework :: Dash
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: dash>=3.0.3
-Provides-Extra: test
-Requires-Dist: pytest>=8; extra == "test"
 Dynamic: license-file
 
 # dash-startup-loading-plugin
@@ -51,7 +49,7 @@ discovery, resource hooks, and the index hook described in the official
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=0.2.0"
+pip install "dash-startup-loading-plugin>=0.4.0"
 ```
 
 The package declares the following entry point:
@@ -66,6 +64,25 @@ package therefore enables the default startup overlay for Dash applications in
 that Python environment; an explicit import is only needed when changing its
 configuration or using its Python API.
 
+When `dash_antd_components` from Dash Ant Design is installed in the same
+environment, the plugin detects it during automatic hook discovery and applies
+the matching `#ffffff` and `#121212` loading backgrounds. Dash Ant Design
+applications therefore only need to install this plugin; calling
+`configure_antd()` is optional and is reserved for explicit overrides.
+
+## What's new in 0.4.0
+
+- Adds `configure_antd()` with matching `#ffffff` and `#121212` loading
+  backgrounds plus explicit light/dark overrides.
+- Adds `configure_mantine()` with theme defaults sourced from Dash Mantine
+  Components and its pre-render color-scheme hook.
+- Updates the Dash Ant Design example for the structured
+  `ConfigProvider.theme.algorithm` API.
+- Adds a Dash Mantine Components example with persisted theme switching.
+- Adds `configure_fac()` and a feffery-antd-components example.
+- Uses one shared set of display copy across all packaged examples.
+- Supports Dash versions from 3.0.3 onward.
+
 ## What's new in 0.2.0
 
 - Resolves the loading background before first paint from a persisted
@@ -104,25 +121,73 @@ from dash import Dash, html
 from dash_startup_loading_plugin import configure
 
 configure(
-    required_selectors=["#page-header", "#sidebar-menu"],
+    required_selectors=["#usage-header", "#usage-sidebar-menu"],
     pending_selector="[data-dac-async-placeholder]",
     timeout_ms=6000,
-    minimum_display_ms=200,
     fade_duration_ms=160,
-    color="#1677ff",
-    dark_color="#4096ff",
 )
 
 app = Dash(__name__)
 app.layout = html.Div(
     [
-        html.Header("Dashboard", id="page-header"),
-        html.Nav("Navigation", id="sidebar-menu"),
+        html.Header("Dashboard", id="usage-header"),
+        html.Nav("Navigation", id="usage-sidebar-menu"),
     ]
 )
 ```
 
-See [`examples/basic.py`](examples/basic.py) for a runnable example.
+## Installed demos
+
+The example applications are included in the installed Python package. Select a
+packaged example with the `dash-startup-loading-plugin` command:
+
+Component libraries are not dependencies of this plugin. Install the library
+used by the selected example separately:
+
+```bash
+pip install dash-mantine-components
+pip install dash-ant-design
+pip install "feffery-antd-components>=0.4.0"
+```
+
+If the selected component library cannot be imported, the command exits with
+an error naming the failed import and the package to install.
+
+```bash
+# Framework-neutral Dash
+dash-startup-loading-plugin examples.dash
+
+# Dash Mantine Components
+dash-startup-loading-plugin examples.dash-mantine-components
+
+# Dash Ant Design
+dash-startup-loading-plugin examples.dash-ant-design
+
+# feffery-antd-components
+dash-startup-loading-plugin examples.feffery-antd-components
+```
+
+Server options can be supplied directly:
+
+```bash
+dash-startup-loading-plugin examples.dash-mantine-components \
+    --host 0.0.0.0 --port 8050 --debug
+```
+
+The same launcher is available through Python when a console-script path is not
+available:
+
+```bash
+python -m dash_startup_loading_plugin.examples examples.dash-mantine-components
+```
+
+Application code can create a selected demo without starting its server:
+
+```python
+from dash_startup_loading_plugin.examples import create_demo_app
+
+app = create_demo_app("dash-mantine-components")
+```
 
 ## Readiness behavior
 
@@ -152,7 +217,7 @@ immutable `StartupLoadingConfig` instance.
 | Option | Default | Description |
 |---|---:|---|
 | `enabled` | `True` | Inject the startup overlay. Set to `False` to disable it. |
-| `overlay_id` | `"dash-startup-loading"` | HTML `id` of the injected overlay; also used by the browser API. |
+| `overlay_id` | `"dash-loading"` | HTML `id` of the injected overlay; also used by the browser API. |
 | `aria_label` | `"Loading"` | Accessible label on the overlay's `role="status"` element. |
 | `root_selector` | `"#react-entry-point"` | Dash renderer root observed for mounted content. |
 | `required_selectors` | `("#react-entry-point",)` | Iterable of document-level CSS selectors that must all exist. A single string is not accepted. |
@@ -187,35 +252,136 @@ in this order:
    followed by the common `theme`, `color-theme`, and `color-scheme` keys.
 6. `prefers-color-scheme`.
 
-The result is written to `data-dash-startup-loading-theme` before the body is
+The result is written to `data-dash-loading-theme` before the body is
 parsed. This isolates the overlay styling without changing classes or data
 attributes owned by Tailwind, Dash Mantine Components, or the application.
 The stylesheet also adjusts its animation for `prefers-reduced-motion`.
 
+### Dash Mantine Components
+
+Dash Mantine Components 2.6 and later includes `ColorSchemeToggle`, which
+switches the active color scheme without a callback and persists it in
+`mantine-color-scheme-value`. The startup plugin reads that value before Dash
+and React mount. To make the loading transition seamless, use Mantine's current
+default dark body color for the overlay:
+
+```python
+import dash_mantine_components as dmc
+from dash_startup_loading_plugin import configure_mantine
+
+configure_mantine()
+
+app.layout = dmc.MantineProvider(
+    [
+        dmc.ColorSchemeToggle(
+            lightIcon=dmc.Text("☀"),
+            darkIcon=dmc.Text("☾"),
+        ),
+        dmc.Text("Application content", id="app-ready"),
+    ],
+    defaultColorScheme="auto",
+)
+```
+
+Run `dash-startup-loading-plugin examples.dash-mantine-components` for the
+complete example.
+
+`configure_mantine()` keeps DMC optional. When used, it registers DMC's
+pre-render color-scheme hook, disables the Dash Ant Design placeholder check,
+and derives the light and dark loading backgrounds from DMC's active default
+theme. Any explicit configuration still takes precedence:
+
+```python
+configure_mantine(dark_background="#202020")
+```
+
 ### Dash Ant Design persistence
 
-`dash_antd_components.ConfigProvider` can persist its `theme` prop. The startup
-plugin reads that same Dash persistence record on the next page load:
+Current `dash_antd_components.ConfigProvider.theme` accepts a structured theme
+configuration whose `algorithm` is `"default"`, `"dark"`, `"compact"`, or an
+array of those values. Persist a user-facing system/light/dark selector, resolve
+the system preference in a clientside callback, and store the semantic choice
+in the small conventional `localStorage["theme"]` value that the startup plugin
+reads before Dash mounts:
 
 ```python
 import dash_antd_components as dac
-from dash_startup_loading_plugin import configure
+from dash import Input, Output, clientside_callback
+from dash_startup_loading_plugin import configure_antd
 
-configure(dash_theme_component_id="theme-provider")
+configure_antd()
 
 provider = dac.ConfigProvider(
-    app_content,
+    [
+        app_content,
+        dac.Segmented(
+            id="theme-mode",
+            options=["system", "light", "dark"],
+            value="system",
+            persistence=True,
+            persisted_props=["value"],
+            persistence_type="local",
+        ),
+    ],
     id="theme-provider",
-    persistence=True,
-    persisted_props=["theme"],
-    persistence_type="local",
+    theme={"algorithm": "default"},
+)
+
+clientside_callback(
+    """function(mode) {
+        localStorage.setItem("theme", JSON.stringify(mode));
+        const dark = mode === "dark" || (
+            mode === "system"
+            && window.matchMedia("(prefers-color-scheme: dark)").matches
+        );
+        return {algorithm: dark ? "dark" : "default"};
+    }""",
+    Output("theme-provider", "theme"),
+    Input("theme-mode", "value"),
+)
+```
+
+The selector owns the semantic `"system"` state; `ConfigProvider` receives only
+the algorithms allowed by its current API. `configure_antd()` uses `#ffffff`
+and `#121212`, matching the component library's default light and dark
+backgrounds. If the application customizes either background, pass the same
+values explicitly:
+
+```python
+configure_antd(
+    background="#f5f5f5",
+    dark_background="#202020",
+)
+```
+
+Run `dash-startup-loading-plugin examples.dash-ant-design` for the complete
+switcher.
+
+### feffery-antd-components persistence
+
+FAC 0.4 and later supports Dash 3 and exposes Ant Design's theme algorithm
+through `AntdConfigProvider.algorithm`. Use `configure_fac()` before creating
+the app, persist a semantic system/light/dark selection, and return either
+`"default"` or `"dark"` to the provider:
+
+```python
+import feffery_antd_components as fac
+from dash import Dash
+from dash_startup_loading_plugin import configure_fac
+
+configure_fac(required_selectors=["#fac-app-ready"])
+
+app = Dash(__name__)
+app.layout = fac.AntdConfigProvider(
+    fac.AntdButton("Example component", id="fac-app-ready"),
+    id="fac-theme-provider",
+    algorithm="default",
 )
 ```
 
-Update `theme-provider.theme` from a regular or clientside callback. Dash stores
-the UI edit, `ConfigProvider` restores it after mount, and the startup plugin
-uses it for the loading background before mount. See
-[`examples/basic.py`](examples/basic.py) for the complete switcher.
+Run `dash-startup-loading-plugin examples.feffery-antd-components` for the
+complete persisted-theme example. FAC remains an external dependency and is
+imported only when that example is selected.
 
 ### Custom loader markup
 
@@ -242,12 +408,22 @@ configuration. Never populate it with user input.
 from dash_startup_loading_plugin import (
     StartupLoadingConfig,
     configure,
+    configure_antd,
+    configure_fac,
+    configure_mantine,
     get_config,
     reset_config,
 )
 ```
 
 - `configure(**changes)` validates and applies a partial configuration update.
+- `configure_antd(**changes)` matches the loading backgrounds to Dash Ant
+  Design's light and dark themes. Installed Dash Ant Design is detected
+  automatically, so this helper is only needed for explicit overrides.
+- `configure_fac(**changes)` applies the equivalent light and dark loading
+  backgrounds for feffery-antd-components.
+- `configure_mantine(**changes)` applies DMC theme defaults and registers DMC's
+  pre-render color-scheme hook.
 - `get_config()` returns the current immutable configuration.
 - `reset_config()` restores all defaults. It is primarily useful in tests.
 - `StartupLoadingConfig` is the frozen dataclass containing all options.
@@ -261,21 +437,21 @@ The plugin exposes two methods for integrations that need explicit control:
 
 ```javascript
 // Recheck the configured readiness conditions.
-window.dashStartupLoading.check();
+window.dashLoading.check();
 
 // Begin a manual dismissal.
-window.dashStartupLoading.finish();
+window.dashLoading.finish();
 
 // A custom overlay_id can be supplied to either method.
-window.dashStartupLoading.finish("my-loading-overlay");
+window.dashLoading.finish("my-loading-overlay");
 ```
 
 Before fading out, the overlay dispatches a bubbling
-`dash-startup-loading:ready` event. Its `detail.reason` is `"ready"`,
+`dash-loading:ready` event. Its `detail.reason` is `"ready"`,
 `"timeout"`, or `"manual"`:
 
 ```javascript
-document.addEventListener("dash-startup-loading:ready", function (event) {
+document.addEventListener("dash-loading:ready", function (event) {
     console.log("Startup overlay finished:", event.detail.reason);
 });
 ```
@@ -345,120 +521,6 @@ This is expected with automatic `dash_hooks` discovery. Use a dedicated virtual
 environment, uninstall the package where it is not wanted, or call
 `configure(enabled=False)` before constructing those Dash apps.
 
-## Development
-
-Clone the repository, then install the project and test dependencies:
-
-```bash
-uv sync --extra test
-```
-
-Run the tests and example:
-
-```bash
-uv run pytest
-uv run --with dash-ant-design python examples/basic.py
-```
-
-The example uses `dash_antd_components.ConfigProvider` to demonstrate native
-theme persistence, so `dash-ant-design` is an example-only dependency rather
-than a runtime dependency of the plugin.
-
-Build the source distribution and wheel:
-
-```bash
-uv build
-```
-
-## Publishing to PyPI
-
-PyPI does not allow replacing an existing distribution file. Confirm that the
-version in `pyproject.toml` is new before building, then create the artifacts
-from a clean `dist/` directory:
-
-```bash
-rm -rf build dist src/*.egg-info
-uv lock
-uv run --extra test pytest
-uvx ruff check src tests examples
-uv build
-uvx twine check dist/*
-```
-
-Inspect the resulting files before upload:
-
-```bash
-ls -lh dist/
-unzip -l dist/dash_startup_loading_plugin-0.2.0-py3-none-any.whl
-tar -tzf dist/dash_startup_loading_plugin-0.2.0.tar.gz
-uv publish --dry-run dist/*
-```
-
-### TestPyPI
-
-Create a TestPyPI API token, then upload to its legacy upload endpoint:
-
-```bash
-export UV_PUBLISH_TOKEN="pypi-your-test-token"
-uv publish \
-  --publish-url https://test.pypi.org/legacy/ \
-  --check-url https://test.pypi.org/simple/ \
-  dist/*
-unset UV_PUBLISH_TOKEN
-```
-
-Test installation in an isolated environment:
-
-```bash
-uv run --isolated \
-  --index-url https://test.pypi.org/simple/ \
-  --extra-index-url https://pypi.org/simple/ \
-  --with dash-startup-loading-plugin==0.2.0 \
-  python -c "import dash_startup_loading_plugin; print('import ok')"
-```
-
-The extra PyPI index is needed because TestPyPI may not contain the plugin's
-runtime dependencies.
-
-### PyPI with an API token
-
-Create a project-scoped PyPI token and publish the checked artifacts:
-
-```bash
-export UV_PUBLISH_TOKEN="pypi-your-project-token"
-uv publish dist/*
-unset UV_PUBLISH_TOKEN
-```
-
-Do not place tokens in `pyproject.toml`, shell history, source control, or CI
-logs.
-
-### PyPI Trusted Publishing
-
-For CI releases, configure the repository and workflow as a Trusted Publisher
-in the PyPI project settings. The publishing job needs the
-`id-token: write` permission and can upload without a long-lived token:
-
-```yaml
-permissions:
-  contents: read
-  id-token: write
-
-steps:
-  - uses: actions/checkout@v4
-  - uses: astral-sh/setup-uv@v8
-  - run: uv build
-  - run: uv publish --trusted-publishing always
-```
-
-After publishing, verify the release:
-
-```bash
-uv run --isolated \
-  --with dash-startup-loading-plugin==0.2.0 \
-  python -c "import dash_startup_loading_plugin; print('import ok')"
-```
-
 ## License
 
 MIT. See [`LICENSE`](LICENSE).