dash-startup-loading-plugin 0.1.0__py3-none-any.whl

dash_startup_loading_plugin/__init__.py

@@ -0,0 +1,23 @@
+"""Full-screen startup loading overlay for Dash applications."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dash-startup-loading-plugin")
+except PackageNotFoundError:  # pragma: no cover - source tree fallback
+    __version__ = "0.1.0"
+
+from .plugin import (  # noqa: E402
+    StartupLoadingConfig,
+    configure,
+    get_config,
+    reset_config,
+)
+
+__all__ = [
+    "StartupLoadingConfig",
+    "__version__",
+    "configure",
+    "get_config",
+    "reset_config",
+]

dash_startup_loading_plugin/plugin.py

@@ -0,0 +1,198 @@
+"""Dash Hooks registration and startup-overlay configuration."""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import asdict, dataclass, fields, replace
+from html import escape
+from threading import RLock
+from typing import Any, Iterable
+
+from dash import hooks
+
+_OVERLAY_MARKER = "data-dash-startup-loading"
+_BODY_PATTERN = re.compile(r"<body(?:\s[^>]*)?>", flags=re.IGNORECASE)
+_CONFIG_LOCK = RLock()
+
+
+@dataclass(frozen=True)
+class StartupLoadingConfig:
+    """Configuration serialized into the startup overlay.
+
+    ``custom_loader_html`` is inserted verbatim and must only contain trusted
+    HTML supplied by the application author.
+    """
+
+    enabled: bool = True
+    overlay_id: str = "dash-startup-loading"
+    aria_label: str = "Loading"
+    root_selector: str = "#react-entry-point"
+    required_selectors: tuple[str, ...] = ("#react-entry-point",)
+    pending_selector: str | None = "[data-dac-async-placeholder]"
+    timeout_ms: int | None = 6000
+    minimum_display_ms: int = 0
+    fade_duration_ms: int = 160
+    z_index: int = 9999
+    background: str = "#ffffff"
+    dark_background: str = "#0f0f0f"
+    color: str = "#1677ff"
+    dark_color: str = "#4096ff"
+    spinner_size_px: int = 28
+    spinner_stroke_px: int = 3
+    hide_default_loading: bool = True
+    custom_loader_html: str | None = None
+
+
+_DEFAULT_CONFIG = StartupLoadingConfig()
+_config = _DEFAULT_CONFIG
+
+
+def _selector_tuple(value: Iterable[str] | str) -> tuple[str, ...]:
+    if isinstance(value, str):
+        raise TypeError("required_selectors must be an iterable of CSS selector strings")
+    selectors = tuple(value)
+    if not all(isinstance(selector, str) and selector.strip() for selector in selectors):
+        raise ValueError("required_selectors must contain non-empty CSS selector strings")
+    return selectors
+
+
+def _validate(config: StartupLoadingConfig) -> StartupLoadingConfig:
+    if not isinstance(config.enabled, bool):
+        raise TypeError("enabled must be a boolean")
+    if not isinstance(config.overlay_id, str) or not config.overlay_id.strip():
+        raise ValueError("overlay_id must be a non-empty string")
+    if not isinstance(config.root_selector, str) or not config.root_selector.strip():
+        raise ValueError("root_selector must be a non-empty CSS selector")
+    if config.pending_selector is not None and (
+        not isinstance(config.pending_selector, str) or not config.pending_selector.strip()
+    ):
+        raise ValueError("pending_selector must be None or a non-empty CSS selector")
+    if config.timeout_ms is not None and config.timeout_ms < 0:
+        raise ValueError("timeout_ms must be None or greater than or equal to zero")
+    for name in ("minimum_display_ms", "fade_duration_ms", "spinner_size_px", "spinner_stroke_px"):
+        if getattr(config, name) < 0:
+            raise ValueError(f"{name} must be greater than or equal to zero")
+    return config
+
+
+def configure(**changes: Any) -> StartupLoadingConfig:
+    """Update the process-wide plugin configuration.
+
+    Call this before creating ``dash.Dash``. The Dash hooks registry is
+    process-wide, so one configuration is shared by all apps in the process.
+    """
+
+    valid_names = {field.name for field in fields(StartupLoadingConfig)}
+    unknown = set(changes).difference(valid_names)
+    if unknown:
+        names = ", ".join(sorted(unknown))
+        raise TypeError(f"Unknown startup loading option(s): {names}")
+    if "required_selectors" in changes:
+        changes["required_selectors"] = _selector_tuple(changes["required_selectors"])
+
+    global _config
+    with _CONFIG_LOCK:
+        _config = _validate(replace(_config, **changes))
+        return _config
+
+
+def get_config() -> StartupLoadingConfig:
+    """Return the active immutable configuration."""
+
+    with _CONFIG_LOCK:
+        return _config
+
+
+def reset_config() -> StartupLoadingConfig:
+    """Restore the default configuration, primarily for tests."""
+
+    global _config
+    with _CONFIG_LOCK:
+        _config = _DEFAULT_CONFIG
+        return _config
+
+
+def _client_config(config: StartupLoadingConfig) -> dict[str, Any]:
+    values = asdict(config)
+    return {
+        "rootSelector": values["root_selector"],
+        "requiredSelectors": list(values["required_selectors"]),
+        "pendingSelector": values["pending_selector"],
+        "timeoutMs": values["timeout_ms"],
+        "minimumDisplayMs": values["minimum_display_ms"],
+        "fadeDurationMs": values["fade_duration_ms"],
+    }
+
+
+def _overlay_html(config: StartupLoadingConfig) -> str:
+    client_config = escape(
+        json.dumps(_client_config(config), ensure_ascii=False, separators=(",", ":")),
+        quote=True,
+    )
+    overlay_id = escape(config.overlay_id, quote=True)
+    aria_label = escape(config.aria_label, quote=True)
+    classes = ["dash-startup-loading"]
+    if config.hide_default_loading:
+        classes.append("dash-startup-loading--hide-default")
+    class_name = " ".join(classes)
+    styles = {
+        "--dash-startup-loading-background": config.background,
+        "--dash-startup-loading-dark-background": config.dark_background,
+        "--dash-startup-loading-color": config.color,
+        "--dash-startup-loading-dark-color": config.dark_color,
+        "--dash-startup-loading-size": f"{config.spinner_size_px}px",
+        "--dash-startup-loading-stroke": f"{config.spinner_stroke_px}px",
+        "--dash-startup-loading-fade-duration": f"{config.fade_duration_ms}ms",
+        "--dash-startup-loading-z-index": str(config.z_index),
+    }
+    style = escape(";".join(f"{name}:{value}" for name, value in styles.items()), quote=True)
+    loader = config.custom_loader_html
+    if loader is None:
+        loader = '<span class="dash-startup-loading__spinner" aria-hidden="true"></span>'
+
+    return (
+        f'<div id="{overlay_id}" class="{class_name}" {_OVERLAY_MARKER} '
+        f'data-config="{client_config}" role="status" aria-live="polite" '
+        f'aria-label="{aria_label}" aria-busy="true" style="{style}">'
+        f'<div class="dash-startup-loading__content">{loader}</div>'
+        "</div>"
+    )
+
+
+def _inject_overlay(app_index: str) -> str:
+    config = get_config()
+    if not config.enabled or _OVERLAY_MARKER in app_index:
+        return app_index
+
+    body_match = _BODY_PATTERN.search(app_index)
+    if body_match is None:
+        return app_index
+    position = body_match.end()
+    return app_index[:position] + _overlay_html(config) + app_index[position:]
+
+
+hooks.stylesheet(
+    [
+        {
+            "relative_package_path": "resources/startup-loading.css",
+            "namespace": "dash_startup_loading_plugin",
+        }
+    ]
+)
+
+hooks.script(
+    [
+        {
+            "relative_package_path": "resources/startup-loading.js",
+            "namespace": "dash_startup_loading_plugin",
+        }
+    ]
+)
+
+
+@hooks.index(priority=100)
+def inject_startup_loading(app_index: str) -> str:
+    """Inject the pre-React overlay into the final HTML document."""
+
+    return _inject_overlay(app_index)

dash_startup_loading_plugin/resources/startup-loading.css

@@ -0,0 +1,66 @@
+.dash-startup-loading {
+    position: fixed;
+    inset: 0;
+    z-index: var(--dash-startup-loading-z-index, 9999);
+    display: grid;
+    place-items: center;
+    overflow: hidden;
+    opacity: 1;
+    color: var(--dash-startup-loading-color, #1677ff);
+    background: var(--dash-startup-loading-background, #fff);
+    transition: opacity var(--dash-startup-loading-fade-duration, 160ms) ease;
+}
+
+.dash-startup-loading.is-ready {
+    pointer-events: none;
+    opacity: 0;
+}
+
+.dash-startup-loading__content {
+    display: grid;
+    place-items: center;
+}
+
+.dash-startup-loading__spinner {
+    box-sizing: border-box;
+    display: block;
+    width: var(--dash-startup-loading-size, 28px);
+    height: var(--dash-startup-loading-size, 28px);
+    border: var(--dash-startup-loading-stroke, 3px) solid transparent;
+    border-top-color: currentcolor;
+    border-radius: 50%;
+    animation: dash-startup-loading-spin 0.8s linear infinite;
+}
+
+.dash-startup-loading--hide-default ~ #react-entry-point ._dash-loading,
+.dash-startup-loading--hide-default ~ * ._dash-loading {
+    display: none;
+}
+
+html.dark .dash-startup-loading {
+    color: var(--dash-startup-loading-dark-color, #4096ff);
+    background: var(--dash-startup-loading-dark-background, #0f0f0f);
+}
+
+@media (prefers-color-scheme: dark) {
+    html:not(.light) .dash-startup-loading {
+        color: var(--dash-startup-loading-dark-color, #4096ff);
+        background: var(--dash-startup-loading-dark-background, #0f0f0f);
+    }
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .dash-startup-loading {
+        transition: none;
+    }
+
+    .dash-startup-loading__spinner {
+        animation-duration: 1.6s;
+    }
+}
+
+@keyframes dash-startup-loading-spin {
+    to {
+        transform: rotate(360deg);
+    }
+}

dash_startup_loading_plugin/resources/startup-loading.js

@@ -0,0 +1,177 @@
+(function () {
+    "use strict";
+
+    var overlays = new Map();
+
+    function warn(message, error) {
+        if (window.console && typeof window.console.warn === "function") {
+            window.console.warn("[dash-startup-loading] " + message, error || "");
+        }
+    }
+
+    function parseConfig(overlay) {
+        try {
+            return JSON.parse(overlay.getAttribute("data-config") || "{}");
+        } catch (error) {
+            warn("Invalid overlay configuration.", error);
+            return {};
+        }
+    }
+
+    function query(selector, root) {
+        if (!selector) {
+            return null;
+        }
+        try {
+            return (root || document).querySelector(selector);
+        } catch (error) {
+            warn("Invalid CSS selector: " + selector, error);
+            return null;
+        }
+    }
+
+    function hasRenderedContent(root) {
+        if (!root || query("._dash-loading", root)) {
+            return false;
+        }
+        return Array.prototype.some.call(root.childNodes, function (node) {
+            return node.nodeType === 1 || (node.nodeType === 3 && node.textContent.trim());
+        });
+    }
+
+    function createController(overlay) {
+        var config = parseConfig(overlay);
+        var startedAt = window.performance && performance.now ? performance.now() : Date.now();
+        var observer = null;
+        var timeoutId = null;
+        var minimumTimerId = null;
+        var removalTimerId = null;
+        var scheduled = false;
+        var finished = false;
+
+        function now() {
+            return window.performance && performance.now ? performance.now() : Date.now();
+        }
+
+        function isReady() {
+            var root = query(config.rootSelector || "#react-entry-point");
+            if (!hasRenderedContent(root)) {
+                return false;
+            }
+
+            var required = Array.isArray(config.requiredSelectors) ? config.requiredSelectors : [];
+            if (!required.every(function (selector) { return Boolean(query(selector)); })) {
+                return false;
+            }
+
+            return !config.pendingSelector || !query(config.pendingSelector, root);
+        }
+
+        function cleanup() {
+            if (observer) {
+                observer.disconnect();
+            }
+            window.removeEventListener("load", check);
+            if (timeoutId !== null) {
+                window.clearTimeout(timeoutId);
+            }
+            if (minimumTimerId !== null) {
+                window.clearTimeout(minimumTimerId);
+            }
+        }
+
+        function finish(reason) {
+            if (finished) {
+                return;
+            }
+
+            var minimumDisplayMs = Math.max(Number(config.minimumDisplayMs) || 0, 0);
+            var remaining = minimumDisplayMs - (now() - startedAt);
+            if (remaining > 0 && reason !== "timeout") {
+                if (minimumTimerId === null) {
+                    minimumTimerId = window.setTimeout(function () {
+                        minimumTimerId = null;
+                        finish(reason);
+                    }, remaining);
+                }
+                return;
+            }
+
+            finished = true;
+            cleanup();
+            overlay.classList.add("is-ready");
+            overlay.setAttribute("aria-busy", "false");
+            overlay.dispatchEvent(new CustomEvent("dash-startup-loading:ready", {
+                bubbles: true,
+                detail: { reason: reason || "manual" }
+            }));
+
+            var fadeDurationMs = Math.max(Number(config.fadeDurationMs) || 0, 0);
+            removalTimerId = window.setTimeout(function () {
+                overlays.delete(overlay.id);
+                if (overlay.isConnected) {
+                    overlay.remove();
+                }
+            }, fadeDurationMs + 20);
+        }
+
+        function check() {
+            if (finished || scheduled || !isReady()) {
+                return;
+            }
+            scheduled = true;
+            window.requestAnimationFrame(function () {
+                window.requestAnimationFrame(function () {
+                    scheduled = false;
+                    if (isReady()) {
+                        finish("ready");
+                    }
+                });
+            });
+        }
+
+        observer = new MutationObserver(check);
+        observer.observe(document.documentElement, { childList: true, subtree: true });
+        window.addEventListener("load", check);
+        if (config.timeoutMs !== null && config.timeoutMs !== undefined) {
+            timeoutId = window.setTimeout(function () { finish("timeout"); }, Math.max(Number(config.timeoutMs) || 0, 0));
+        }
+        check();
+
+        return {
+            check: check,
+            finish: finish,
+            destroy: function () {
+                cleanup();
+                if (removalTimerId !== null) {
+                    window.clearTimeout(removalTimerId);
+                }
+            }
+        };
+    }
+
+    function boot() {
+        document.querySelectorAll("[data-dash-startup-loading]").forEach(function (overlay) {
+            if (!overlays.has(overlay.id)) {
+                overlays.set(overlay.id, createController(overlay));
+            }
+        });
+    }
+
+    window.dashStartupLoading = {
+        check: function (overlayId) {
+            var controller = overlays.get(overlayId || "dash-startup-loading");
+            if (controller) {
+                controller.check();
+            }
+        },
+        finish: function (overlayId) {
+            var controller = overlays.get(overlayId || "dash-startup-loading");
+            if (controller) {
+                controller.finish("manual");
+            }
+        }
+    };
+
+    boot();
+}());

dash_startup_loading_plugin-0.1.0.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: dash-startup-loading-plugin
+Version: 0.1.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
+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
+
+`dash-startup-loading-plugin` is an installable [Dash Hooks plugin](https://dash.plotly.com/dash-plugins-using-hooks)
+that displays a full-screen loading overlay while a Dash application performs
+its initial browser-side startup.
+
+The overlay is injected into the final HTML document with `hooks.index`, so it
+is visible before Dash and React mount the application layout. The packaged CSS
+and JavaScript are registered with `hooks.stylesheet` and `hooks.script`; an app
+does not need to copy assets or replace Dash's `index_string`.
+
+## Features
+
+- Appears before the Dash renderer starts, avoiding a blank startup page.
+- Is discovered automatically through Dash's `dash_hooks` entry point.
+- Waits for real rendered content and optional app-specific readiness selectors.
+- Can wait for lazy-loading placeholders to disappear.
+- Includes a timeout fallback, minimum display time, and fade-out transition.
+- Supports light and dark themes, reduced-motion preferences, custom colors,
+  custom spinner geometry, and trusted custom loader markup.
+- Exposes a small browser API and emits a completion event.
+- Requires no changes to the app layout or callbacks.
+
+## Requirements
+
+- Python 3.9 or later
+- Dash 3.0.3 or later
+
+Dash Hooks were introduced in Dash 3.0. The plugin uses automatic hook
+discovery, resource hooks, and the index hook described in the official
+[Dash plugin documentation](https://dash.plotly.com/dash-plugins-using-hooks).
+
+## Installation
+
+```bash
+pip install dash-startup-loading-plugin
+```
+
+The package declares the following entry point:
+
+```toml
+[project.entry-points."dash_hooks"]
+dash_startup_loading_plugin = "dash_startup_loading_plugin"
+```
+
+Dash imports registered `dash_hooks` packages automatically. Installing the
+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.
+
+## Quick start
+
+The defaults work without any plugin-specific code:
+
+```python
+from dash import Dash, html
+
+app = Dash(__name__)
+app.layout = html.Main(
+    [
+        html.H1("My Dash app"),
+        html.P("The overlay disappears after this layout is mounted."),
+    ]
+)
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+To customize the readiness conditions or appearance, call `configure()` before
+creating the `Dash` instance:
+
+```python
+from dash import Dash, html
+from dash_startup_loading_plugin import configure
+
+configure(
+    required_selectors=["#page-header", "#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"),
+    ]
+)
+```
+
+See [`examples/basic.py`](examples/basic.py) for a runnable example.
+
+## Readiness behavior
+
+The overlay closes with the `ready` reason after all of these conditions are
+true:
+
+1. `root_selector` exists.
+2. The root no longer contains Dash's initial `._dash-loading` element.
+3. The root contains an element or non-empty text node.
+4. Every CSS selector in `required_selectors` exists in the document.
+5. No node matching `pending_selector` remains under the root.
+6. The conditions stay true for two consecutive animation frames.
+
+A `MutationObserver` rechecks these conditions as the page changes. The
+two-frame confirmation prevents the overlay from disappearing during an
+intermediate render.
+
+`timeout_ms` is a safety fallback and dismisses the overlay even when the
+readiness contract is not satisfied. Set it to `None` to disable forced
+dismissal. A timeout is not delayed by `minimum_display_ms`.
+
+## Configuration reference
+
+`configure(**changes)` updates only the supplied values and returns the active,
+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. |
+| `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. |
+| `pending_selector` | `"[data-dac-async-placeholder]"` | Selector for placeholders under the root that delay dismissal. Use `None` to disable this check. |
+| `timeout_ms` | `6000` | Forced-dismiss timeout in milliseconds. Use `None` to disable it. |
+| `minimum_display_ms` | `0` | Minimum display time for ready or manual dismissal. |
+| `fade_duration_ms` | `160` | Opacity transition duration before the overlay is removed. |
+| `z_index` | `9999` | Overlay stacking order. |
+| `background` | `"#ffffff"` | Light-theme background color. |
+| `dark_background` | `"#0f0f0f"` | Dark-theme background color. |
+| `color` | `"#1677ff"` | Light-theme spinner/current color. |
+| `dark_color` | `"#4096ff"` | Dark-theme spinner/current color. |
+| `spinner_size_px` | `28` | Default spinner width and height in pixels. |
+| `spinner_stroke_px` | `3` | Default spinner stroke width in pixels. |
+| `hide_default_loading` | `True` | Hide Dash's built-in initial `._dash-loading` indicator while the overlay is present. |
+| `custom_loader_html` | `None` | Trusted HTML that replaces the default spinner. |
+
+The default stylesheet recognizes `html.dark` and `html.light`. When neither
+class forces a theme, it follows `prefers-color-scheme`. It also adjusts its
+animation when the user enables `prefers-reduced-motion`.
+
+### Custom loader markup
+
+```python
+from dash_startup_loading_plugin import configure
+
+configure(
+    aria_label="Loading dashboard",
+    custom_loader_html="""
+    <div class="brand-loader" aria-hidden="true">
+      <span></span><span></span><span></span>
+    </div>
+    """,
+)
+```
+
+Add the matching `.brand-loader` rules to the app's normal `assets` directory.
+`custom_loader_html` is inserted verbatim and must be trusted application
+configuration. Never populate it with user input.
+
+## Python API
+
+```python
+from dash_startup_loading_plugin import (
+    StartupLoadingConfig,
+    configure,
+    get_config,
+    reset_config,
+)
+```
+
+- `configure(**changes)` validates and applies a partial configuration update.
+- `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.
+
+Unknown option names raise `TypeError`. Invalid selector collections and
+negative timing or spinner values are rejected rather than silently ignored.
+
+## Browser API and events
+
+The plugin exposes two methods for integrations that need explicit control:
+
+```javascript
+// Recheck the configured readiness conditions.
+window.dashStartupLoading.check();
+
+// Begin a manual dismissal.
+window.dashStartupLoading.finish();
+
+// A custom overlay_id can be supplied to either method.
+window.dashStartupLoading.finish("my-loading-overlay");
+```
+
+Before fading out, the overlay dispatches a bubbling
+`dash-startup-loading:ready` event. Its `detail.reason` is `"ready"`,
+`"timeout"`, or `"manual"`:
+
+```javascript
+document.addEventListener("dash-startup-loading:ready", function (event) {
+    console.log("Startup overlay finished:", event.detail.reason);
+});
+```
+
+## Migrating from a custom `index_string`
+
+If an app previously injected a loader into a hand-written `index_string`, move
+its readiness contract into the plugin and remove the `app.index_string = ...`
+assignment:
+
+```python
+from dash_startup_loading_plugin import configure
+
+configure(
+    required_selectors=["#usage-header", "#usage-sidebar-menu"],
+    pending_selector="[data-dac-async-placeholder]",
+    timeout_ms=6000,
+    fade_duration_ms=160,
+)
+```
+
+The plugin preserves Dash's normal index template, injects the overlay directly
+after the opening `<body>` tag, and registers its versioned package assets via
+Dash Hooks. The index hook uses priority `100`, so it runs before lower-priority
+index hooks. If multiple hooks share the same priority, Dash does not guarantee
+their relative order.
+
+## Scope and process model
+
+Dash's hook registry is process-wide. `configure()` therefore affects every
+Dash app created in the same Python process. Use one shared configuration per
+process, or set `enabled=False` when the overlay should not be injected.
+
+This plugin handles initial application startup only. It does not show a
+full-screen overlay for later callback execution; use `dcc.Loading` or another
+callback-specific loading pattern for that use case.
+
+## Troubleshooting
+
+### The overlay only disappears after the timeout
+
+One of the configured selectors is probably never becoming ready. Check that:
+
+- `root_selector` matches the actual Dash renderer root.
+- Every `required_selectors` entry exists in the final document.
+- `pending_selector` does not match a placeholder that remains permanently.
+- Custom selectors are valid CSS selectors.
+
+Temporarily keep the fallback enabled and listen for the completion event. A
+`"timeout"` reason confirms that the readiness contract was not met.
+
+### The overlay disappears too quickly
+
+Set `minimum_display_ms` to keep it visible for a predictable minimum duration,
+or add stable application elements to `required_selectors`.
+
+### The overlay appears in every app in the environment
+
+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 python examples/basic.py
+```
+
+Build the source distribution and wheel:
+
+```bash
+uv build
+```
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

dash_startup_loading_plugin-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+dash_startup_loading_plugin/__init__.py,sha256=mhRGKUhJY9UjP1zUJGwPxWGDBokyjp3YfQzccsm6WNg,519
+dash_startup_loading_plugin/plugin.py,sha256=YIMv4xmDgWvDxEcLR3LEvWLkd6TUS3d1fuKstALPaXs,7030
+dash_startup_loading_plugin/resources/startup-loading.css,sha256=rAJSLe9YQjVEfLA3QGFsulqVhajMu6Z7jMfzFGUm5fg,1758
+dash_startup_loading_plugin/resources/startup-loading.js,sha256=okhYdwYlzDrcUp8Sd1HI91b1iXnlXEEmkzfUsT06J8g,5739
+dash_startup_loading_plugin-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+dash_startup_loading_plugin-0.1.0.dist-info/METADATA,sha256=4YxAoc8XPumzQ0VdZgB8ouRPowG-jYFNWy51U2woyjM,10740
+dash_startup_loading_plugin-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+dash_startup_loading_plugin-0.1.0.dist-info/entry_points.txt,sha256=TLRonncU9df9fZjsZzCSicZ0XToewEf1zrihk0dUzHQ,71
+dash_startup_loading_plugin-0.1.0.dist-info/top_level.txt,sha256=bF7ddV1nLIby8uvgcLlytofPH5ci8GqOX0uvaNTUEXc,28
+dash_startup_loading_plugin-0.1.0.dist-info/RECORD,,

dash_startup_loading_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dash_startup_loading_plugin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[dash_hooks]
+dash_startup_loading_plugin = dash_startup_loading_plugin

dash_startup_loading_plugin-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

dash_startup_loading_plugin-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dash_startup_loading_plugin