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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dash-startup-loading-plugin
-Version: 0.3.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
@@ -9,11 +9,7 @@ Classifier: Framework :: Dash
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: dash==4.4.1
-Provides-Extra: test
-Requires-Dist: pytest>=8; extra == "test"
-Provides-Extra: mantine
-Requires-Dist: dash-mantine-components>=2.6.0; extra == "mantine"
+Requires-Dist: dash>=3.0.3
 Dynamic: license-file
 
 # dash-startup-loading-plugin
@@ -53,7 +49,7 @@ discovery, resource hooks, and the index hook described in the official
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=0.3.0"
+pip install "dash-startup-loading-plugin>=0.4.0"
 ```
 
 The package declares the following entry point:
@@ -68,7 +64,13 @@ 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.
 
-## What's new in 0.3.0
+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.
@@ -77,6 +79,9 @@ configuration or using its Python API.
 - 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
 
@@ -131,17 +136,57 @@ app.layout = html.Div(
 )
 ```
 
-Runnable examples:
+## 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:
 
-- [`examples/basic.py`](examples/basic.py): Dash Ant Design theme persistence.
-- [`examples/mantine_theme.py`](examples/mantine_theme.py):
-  Dash Mantine Components with a persisted light/dark theme switch.
+```bash
+dash-startup-loading-plugin examples.dash-mantine-components \
+    --host 0.0.0.0 --port 8050 --debug
+```
 
-Run the Mantine example with:
+The same launcher is available through Python when a console-script path is not
+available:
 
 ```bash
-pip install -e ".[mantine]"
-python examples/mantine_theme.py
+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
@@ -172,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. |
@@ -207,7 +252,7 @@ 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`.
@@ -238,9 +283,8 @@ app.layout = dmc.MantineProvider(
 )
 ```
 
-See
-[`examples/mantine_theme.py`](examples/mantine_theme.py)
-for the complete runnable example.
+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,
@@ -310,8 +354,34 @@ configure_antd(
 )
 ```
 
-See
-[`examples/basic.py`](examples/basic.py) for the complete switcher.
+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",
+)
+```
+
+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
 
@@ -339,6 +409,7 @@ from dash_startup_loading_plugin import (
     StartupLoadingConfig,
     configure,
     configure_antd,
+    configure_fac,
     configure_mantine,
     get_config,
     reset_config,
@@ -347,7 +418,10 @@ from dash_startup_loading_plugin import (
 
 - `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 and accepts explicit overrides.
+  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.
@@ -363,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);
 });
 ```

{dash_startup_loading_plugin-0.3.0 → dash_startup_loading_plugin-0.4.0}/README.md

@@ -35,7 +35,7 @@ discovery, resource hooks, and the index hook described in the official
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=0.3.0"
+pip install "dash-startup-loading-plugin>=0.4.0"
 ```
 
 The package declares the following entry point:
@@ -50,7 +50,13 @@ 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.
 
-## What's new in 0.3.0
+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.
@@ -59,6 +65,9 @@ configuration or using its Python API.
 - 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
 
@@ -113,17 +122,57 @@ app.layout = html.Div(
 )
 ```
 
-Runnable examples:
+## 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:
 
-- [`examples/basic.py`](examples/basic.py): Dash Ant Design theme persistence.
-- [`examples/mantine_theme.py`](examples/mantine_theme.py):
-  Dash Mantine Components with a persisted light/dark theme switch.
+```bash
+dash-startup-loading-plugin examples.dash-mantine-components \
+    --host 0.0.0.0 --port 8050 --debug
+```
 
-Run the Mantine example with:
+The same launcher is available through Python when a console-script path is not
+available:
 
 ```bash
-pip install -e ".[mantine]"
-python examples/mantine_theme.py
+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
@@ -154,7 +203,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. |
@@ -189,7 +238,7 @@ 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`.
@@ -220,9 +269,8 @@ app.layout = dmc.MantineProvider(
 )
 ```
 
-See
-[`examples/mantine_theme.py`](examples/mantine_theme.py)
-for the complete runnable example.
+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,
@@ -292,8 +340,34 @@ configure_antd(
 )
 ```
 
-See
-[`examples/basic.py`](examples/basic.py) for the complete switcher.
+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",
+)
+```
+
+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
 
@@ -321,6 +395,7 @@ from dash_startup_loading_plugin import (
     StartupLoadingConfig,
     configure,
     configure_antd,
+    configure_fac,
     configure_mantine,
     get_config,
     reset_config,
@@ -329,7 +404,10 @@ from dash_startup_loading_plugin import (
 
 - `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 and accepts explicit overrides.
+  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.
@@ -345,21 +423,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);
 });
 ```

{dash_startup_loading_plugin-0.3.0 → dash_startup_loading_plugin-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dash-startup-loading-plugin"
-version = "0.3.0"
+version = "0.4.0"
 description = "A configurable full-screen startup loading overlay for Dash apps, packaged as a Dash Hooks plugin."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -16,16 +16,16 @@ classifiers = ["Framework :: Dash"]
 license = "MIT"
 license-files = ["LICENSE"]
 dependencies = [
-    "dash==4.4.1",
+    "dash>=3.0.3",
 ]
 
-[project.optional-dependencies]
+[dependency-groups]
 test = [
     "pytest>=8",
 ]
-mantine = [
-    "dash-mantine-components>=2.6.0",
-]
+
+[project.scripts]
+dash-startup-loading-plugin = "dash_startup_loading_plugin.examples:main"
 
 [project.entry-points."dash_hooks"]
 dash_startup_loading_plugin = "dash_startup_loading_plugin"

{dash_startup_loading_plugin-0.3.0 → dash_startup_loading_plugin-0.4.0}/src/dash_startup_loading_plugin/__init__.py

@@ -5,12 +5,13 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("dash-startup-loading-plugin")
 except PackageNotFoundError:  # pragma: no cover - source tree fallback
-    __version__ = "0.3.0"
+    __version__ = "0.4.0"
 
 from .plugin import (
     StartupLoadingConfig,
     configure,
     configure_antd,
+    configure_fac,
     configure_mantine,
     get_config,
     reset_config,
@@ -21,6 +22,7 @@ __all__ = [
     "__version__",
     "configure",
     "configure_antd",
+    "configure_fac",
     "configure_mantine",
     "get_config",
     "reset_config",

dash_startup_loading_plugin-0.4.0/src/dash_startup_loading_plugin/examples/__init__.py

@@ -0,0 +1,5 @@
+"""Bundled runnable examples for the startup loading plugin."""
+
+from .cli import DemoDependencyError, create_demo_app, main
+
+__all__ = ["DemoDependencyError", "create_demo_app", "main"]

dash_startup_loading_plugin-0.4.0/src/dash_startup_loading_plugin/examples/__main__.py

@@ -0,0 +1,5 @@
+"""Run the bundled examples with ``python -m dash_startup_loading_plugin.examples``."""
+
+from .cli import main
+
+raise SystemExit(main())

dash_startup_loading_plugin-0.4.0/src/dash_startup_loading_plugin/examples/antd.py

@@ -0,0 +1,109 @@
+"""Dash Ant Design theme persistence demonstration."""
+
+from dash import Dash, Input, Output, clientside_callback, html
+
+from ..plugin import configure_antd
+from .cli import DemoDependencyError
+from .shared import (
+    DEMO_ACTION_TEXT,
+    DEMO_DESCRIPTION,
+    DEMO_READY_TEXT,
+    DEMO_READY_TITLE,
+    DEMO_TITLE,
+    MAIN_STYLE,
+    PANEL_STYLE,
+    THEME_OPTIONS,
+)
+
+
+def create_app() -> Dash:
+    """Create the Dash Ant Design example application."""
+
+    try:
+        import dash_antd_components as dac
+    except ModuleNotFoundError as error:
+        if error.name != "dash_antd_components":
+            raise
+        raise DemoDependencyError(
+            "Failed to import dash_antd_components. "
+            "Install it with: pip install dash-ant-design"
+        ) from error
+
+    configure_antd(
+        required_selectors=["#antd-app-ready"],
+        minimum_display_ms=250,
+        fade_duration_ms=180,
+    )
+
+    app = Dash(__name__)
+    app.layout = dac.ConfigProvider(
+        html.Main(
+            [
+                html.H1(DEMO_TITLE),
+                html.P(DEMO_DESCRIPTION),
+                dac.Segmented(
+                    id="theme-mode",
+                    options=THEME_OPTIONS,
+                    value="system",
+                    block=True,
+                    persistence=True,
+                    persisted_props=["value"],
+                    persistence_type="local",
+                ),
+                html.Section(
+                    [
+                        html.H2(DEMO_READY_TITLE),
+                        html.P(DEMO_READY_TEXT),
+                        html.Button(DEMO_ACTION_TEXT),
+                    ],
+                    style=PANEL_STYLE,
+                ),
+            ],
+            id="antd-app-ready",
+            style=MAIN_STYLE,
+        ),
+        id="theme-provider",
+        theme={"algorithm": "default"},
+    )
+
+    clientside_callback(
+        """function(mode) {
+            const selected = mode || "system";
+            const media = window.matchMedia("(prefers-color-scheme: dark)");
+
+            try {
+                localStorage.setItem("theme", JSON.stringify(selected));
+            } catch (_) {}
+
+            function applyDocumentScheme(dark) {
+                document.documentElement.style.colorScheme = dark ? "dark" : "light";
+            }
+
+            const dark = selected === "dark"
+                || (selected === "system" && media.matches);
+            applyDocumentScheme(dark);
+
+            if (!window.__dashLoadingAntdThemeListener) {
+                window.__dashLoadingAntdThemeListener = function(event) {
+                    let current = "system";
+                    try {
+                        current = JSON.parse(localStorage.getItem("theme")) || "system";
+                    } catch (_) {}
+                    if (current !== "system") return;
+                    applyDocumentScheme(event.matches);
+                    dash_clientside.set_props("theme-provider", {
+                        theme: {algorithm: event.matches ? "dark" : "default"}
+                    });
+                };
+                media.addEventListener(
+                    "change",
+                    window.__dashLoadingAntdThemeListener
+                );
+            }
+
+            return {algorithm: dark ? "dark" : "default"};
+        }""",
+        Output("theme-provider", "theme"),
+        Input("theme-mode", "value"),
+    )
+    return app

dash_startup_loading_plugin-0.4.0/src/dash_startup_loading_plugin/examples/basic.py

@@ -0,0 +1,49 @@
+"""Framework-neutral Dash demonstration."""
+
+from dash import Dash, html
+
+from ..plugin import configure
+from .shared import (
+    DEMO_ACTION_TEXT,
+    DEMO_DESCRIPTION,
+    DEMO_READY_TEXT,
+    DEMO_READY_TITLE,
+    DEMO_TITLE,
+    MAIN_STYLE,
+    PANEL_STYLE,
+)
+
+
+def create_app() -> Dash:
+    """Create the framework-neutral example application."""
+
+    configure(
+        required_selectors=["#dash-app-ready"],
+        minimum_display_ms=250,
+        fade_duration_ms=180,
+        theme_mode="light",
+    )
+
+    app = Dash(__name__)
+    app.layout = html.Main(
+        [
+            html.H1(DEMO_TITLE),
+            html.P(DEMO_DESCRIPTION),
+            html.Section(
+                [
+                    html.H2(DEMO_READY_TITLE),
+                    html.P(DEMO_READY_TEXT),
+                    html.Button(DEMO_ACTION_TEXT),
+                ],
+                style=PANEL_STYLE,
+            ),
+        ],
+        id="dash-app-ready",
+        style=MAIN_STYLE
+        | {
+            "color": "#212529",
+            "background": "#ffffff",
+            "colorScheme": "light",
+        },
+    )
+    return app