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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dash-startup-loading-plugin
-Version: 0.1.0
+Version: 0.2.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
@@ -20,10 +20,10 @@ Dynamic: license-file
 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`.
+The overlay, CSS, and JavaScript are injected into the final HTML document with
+`hooks.index`, so they are available before Dash and React mount the application
+layout without additional startup resource requests. An app does not need to
+copy assets or replace Dash's `index_string`.
 
 ## Features
 
@@ -32,8 +32,10 @@ does not need to copy assets or replace Dash's `index_string`.
 - 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.
+- Inlines its small startup CSS and JavaScript, avoiding two additional requests.
+- Resolves light and dark themes before first paint from Dash component
+  persistence, Tailwind root classes, Mantine color-scheme state, or the
+  operating-system preference.
 - Exposes a small browser API and emits a completion event.
 - Requires no changes to the app layout or callbacks.
 
@@ -49,7 +51,7 @@ discovery, resource hooks, and the index hook described in the official
 ## Installation
 
 ```bash
-pip install dash-startup-loading-plugin
+pip install "dash-startup-loading-plugin>=0.2.0"
 ```
 
 The package declares the following entry point:
@@ -64,6 +66,17 @@ 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.2.0
+
+- Resolves the loading background before first paint from a persisted
+  `dash_antd_components.ConfigProvider.theme`.
+- Supports Tailwind's `html.dark` and `html.light` classes.
+- Supports Dash Mantine Components' `data-mantine-color-scheme` attribute and
+  `mantine-color-scheme-value` localStorage entry.
+- Adds `theme_mode` and `dash_theme_component_id` configuration.
+- Keeps the startup CSS and JavaScript inline, so theme detection does not add
+  network requests before Dash mounts.
+
 ## Quick start
 
 The defaults work without any plugin-specific code:
@@ -152,14 +165,57 @@ immutable `StartupLoadingConfig` instance.
 | `dark_background` | `"#0f0f0f"` | Dark-theme background color. |
 | `color` | `"#1677ff"` | Light-theme spinner/current color. |
 | `dark_color` | `"#4096ff"` | Dark-theme spinner/current color. |
+| `theme_mode` | `"auto"` | Startup theme policy: `"auto"`, `"light"`, or `"dark"`. Auto follows persisted or active app state, then the operating-system preference. |
+| `dash_theme_component_id` | `None` | Preferred Dash component ID when reading a persisted `theme` prop. When omitted, the first compatible persisted theme is used. |
 | `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`.
+With `theme_mode="auto"`, the inline head bootstrap resolves the startup theme
+in this order:
+
+1. The persisted Dash `theme` for `dash_theme_component_id`, when configured.
+2. An existing `html.dark` or `html.light` class, including Tailwind's manual
+   dark-mode convention.
+3. `data-theme`, `data-color-scheme`, or `data-mantine-color-scheme` on
+   `<html>`.
+4. Other Dash local persistence entries for a component's `theme` prop. Set
+   `dash_theme_component_id` when an app contains more than one persisted
+   theme-capable component.
+5. Dash Mantine Components' `mantine-color-scheme-value` localStorage entry,
+   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
+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 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:
+
+```python
+import dash_antd_components as dac
+from dash_startup_loading_plugin import configure
+
+configure(dash_theme_component_id="theme-provider")
+
+provider = dac.ConfigProvider(
+    app_content,
+    id="theme-provider",
+    persistence=True,
+    persisted_props=["theme"],
+    persistence_type="local",
+)
+```
+
+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.
 
 ### Custom loader markup
 
@@ -241,11 +297,18 @@ configure(
 )
 ```
 
-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.
+The plugin preserves Dash's normal index template, injects its stylesheet before
+`</head>`, and inserts the overlay followed by its startup script directly after
+the opening `<body>` tag. The source CSS and JavaScript remain package resources
+for maintainability, but the browser receives them inline and makes no separate
+request for either file. 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.
+
+Because the resources are inline, applications with a strict Content Security
+Policy must permit the injected style and script, or add nonce support in a
+customized deployment. The previous external-resource form is more suitable
+when a policy forbids all inline code.
 
 ## Scope and process model
 
@@ -294,15 +357,108 @@ Run the tests and example:
 
 ```bash
 uv run pytest
-uv run python examples/basic.py
+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).

{dash_startup_loading_plugin-0.1.0 → dash_startup_loading_plugin-0.2.0}/README.md

@@ -4,10 +4,10 @@
 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`.
+The overlay, CSS, and JavaScript are injected into the final HTML document with
+`hooks.index`, so they are available before Dash and React mount the application
+layout without additional startup resource requests. An app does not need to
+copy assets or replace Dash's `index_string`.
 
 ## Features
 
@@ -16,8 +16,10 @@ does not need to copy assets or replace Dash's `index_string`.
 - 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.
+- Inlines its small startup CSS and JavaScript, avoiding two additional requests.
+- Resolves light and dark themes before first paint from Dash component
+  persistence, Tailwind root classes, Mantine color-scheme state, or the
+  operating-system preference.
 - Exposes a small browser API and emits a completion event.
 - Requires no changes to the app layout or callbacks.
 
@@ -33,7 +35,7 @@ discovery, resource hooks, and the index hook described in the official
 ## Installation
 
 ```bash
-pip install dash-startup-loading-plugin
+pip install "dash-startup-loading-plugin>=0.2.0"
 ```
 
 The package declares the following entry point:
@@ -48,6 +50,17 @@ 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.2.0
+
+- Resolves the loading background before first paint from a persisted
+  `dash_antd_components.ConfigProvider.theme`.
+- Supports Tailwind's `html.dark` and `html.light` classes.
+- Supports Dash Mantine Components' `data-mantine-color-scheme` attribute and
+  `mantine-color-scheme-value` localStorage entry.
+- Adds `theme_mode` and `dash_theme_component_id` configuration.
+- Keeps the startup CSS and JavaScript inline, so theme detection does not add
+  network requests before Dash mounts.
+
 ## Quick start
 
 The defaults work without any plugin-specific code:
@@ -136,14 +149,57 @@ immutable `StartupLoadingConfig` instance.
 | `dark_background` | `"#0f0f0f"` | Dark-theme background color. |
 | `color` | `"#1677ff"` | Light-theme spinner/current color. |
 | `dark_color` | `"#4096ff"` | Dark-theme spinner/current color. |
+| `theme_mode` | `"auto"` | Startup theme policy: `"auto"`, `"light"`, or `"dark"`. Auto follows persisted or active app state, then the operating-system preference. |
+| `dash_theme_component_id` | `None` | Preferred Dash component ID when reading a persisted `theme` prop. When omitted, the first compatible persisted theme is used. |
 | `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`.
+With `theme_mode="auto"`, the inline head bootstrap resolves the startup theme
+in this order:
+
+1. The persisted Dash `theme` for `dash_theme_component_id`, when configured.
+2. An existing `html.dark` or `html.light` class, including Tailwind's manual
+   dark-mode convention.
+3. `data-theme`, `data-color-scheme`, or `data-mantine-color-scheme` on
+   `<html>`.
+4. Other Dash local persistence entries for a component's `theme` prop. Set
+   `dash_theme_component_id` when an app contains more than one persisted
+   theme-capable component.
+5. Dash Mantine Components' `mantine-color-scheme-value` localStorage entry,
+   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
+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 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:
+
+```python
+import dash_antd_components as dac
+from dash_startup_loading_plugin import configure
+
+configure(dash_theme_component_id="theme-provider")
+
+provider = dac.ConfigProvider(
+    app_content,
+    id="theme-provider",
+    persistence=True,
+    persisted_props=["theme"],
+    persistence_type="local",
+)
+```
+
+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.
 
 ### Custom loader markup
 
@@ -225,11 +281,18 @@ configure(
 )
 ```
 
-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.
+The plugin preserves Dash's normal index template, injects its stylesheet before
+`</head>`, and inserts the overlay followed by its startup script directly after
+the opening `<body>` tag. The source CSS and JavaScript remain package resources
+for maintainability, but the browser receives them inline and makes no separate
+request for either file. 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.
+
+Because the resources are inline, applications with a strict Content Security
+Policy must permit the injected style and script, or add nonce support in a
+customized deployment. The previous external-resource form is more suitable
+when a policy forbids all inline code.
 
 ## Scope and process model
 
@@ -278,15 +341,108 @@ Run the tests and example:
 
 ```bash
 uv run pytest
-uv run python examples/basic.py
+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).

{dash_startup_loading_plugin-0.1.0 → dash_startup_loading_plugin-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dash-startup-loading-plugin"
-version = "0.1.0"
+version = "0.2.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"

{dash_startup_loading_plugin-0.1.0 → dash_startup_loading_plugin-0.2.0}/src/dash_startup_loading_plugin/__init__.py

@@ -5,7 +5,7 @@ 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"
+    __version__ = "0.2.0"
 
 from .plugin import (  # noqa: E402
     StartupLoadingConfig,

{dash_startup_loading_plugin-0.1.0 → dash_startup_loading_plugin-0.2.0}/src/dash_startup_loading_plugin/plugin.py

@@ -5,7 +5,9 @@ from __future__ import annotations
 import json
 import re
 from dataclasses import asdict, dataclass, fields, replace
+from functools import lru_cache
 from html import escape
+from importlib.resources import files
 from threading import RLock
 from typing import Any, Iterable
 
@@ -13,6 +15,7 @@ from dash import hooks
 
 _OVERLAY_MARKER = "data-dash-startup-loading"
 _BODY_PATTERN = re.compile(r"<body(?:\s[^>]*)?>", flags=re.IGNORECASE)
+_HEAD_END_PATTERN = re.compile(r"</head\s*>", flags=re.IGNORECASE)
 _CONFIG_LOCK = RLock()
 
 
@@ -38,6 +41,8 @@ class StartupLoadingConfig:
     dark_background: str = "#0f0f0f"
     color: str = "#1677ff"
     dark_color: str = "#4096ff"
+    theme_mode: str = "auto"
+    dash_theme_component_id: str | None = None
     spinner_size_px: int = 28
     spinner_stroke_px: int = 3
     hide_default_loading: bool = True
@@ -70,6 +75,13 @@ def _validate(config: StartupLoadingConfig) -> StartupLoadingConfig:
         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")
+    if config.theme_mode not in {"auto", "light", "dark"}:
+        raise ValueError("theme_mode must be 'auto', 'light', or 'dark'")
+    if config.dash_theme_component_id is not None and (
+        not isinstance(config.dash_theme_component_id, str)
+        or not config.dash_theme_component_id.strip()
+    ):
+        raise ValueError("dash_theme_component_id must be None or a non-empty string")
     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")
@@ -125,6 +137,13 @@ def _client_config(config: StartupLoadingConfig) -> dict[str, Any]:
     }
 
 
+def _theme_config(config: StartupLoadingConfig) -> dict[str, Any]:
+    return {
+        "themeMode": config.theme_mode,
+        "dashThemeComponentId": config.dash_theme_component_id,
+    }
+
+
 def _overlay_html(config: StartupLoadingConfig) -> str:
     client_config = escape(
         json.dumps(_client_config(config), ensure_ascii=False, separators=(",", ":")),
@@ -160,6 +179,33 @@ def _overlay_html(config: StartupLoadingConfig) -> str:
     )
 
 
+@lru_cache(maxsize=2)
+def _resource_text(name: str) -> str:
+    return (
+        files("dash_startup_loading_plugin")
+        .joinpath("resources", name)
+        .read_text(encoding="utf-8")
+        .strip()
+    )
+
+
+def _inline_head_resources(app_index: str, config: StartupLoadingConfig) -> str:
+    theme_config = json.dumps(_theme_config(config), ensure_ascii=False, separators=(",", ":"))
+    resources = (
+        '<style data-dash-startup-loading-resource="style">'
+        f"{_resource_text('startup-loading.css')}"
+        "</style>"
+        '<script data-dash-startup-loading-resource="theme">'
+        f"window.__dashStartupLoadingThemeConfig={theme_config};"
+        f"{_resource_text('startup-theme.js')}"
+        "</script>"
+    )
+    head_end = _HEAD_END_PATTERN.search(app_index)
+    if head_end is not None:
+        return app_index[: head_end.start()] + resources + app_index[head_end.start() :]
+    return resources + app_index
+
+
 def _inject_overlay(app_index: str) -> str:
     config = get_config()
     if not config.enabled or _OVERLAY_MARKER in app_index:
@@ -168,27 +214,16 @@ def _inject_overlay(app_index: str) -> str:
     body_match = _BODY_PATTERN.search(app_index)
     if body_match is None:
         return app_index
+    app_index = _inline_head_resources(app_index, config)
+    body_match = _BODY_PATTERN.search(app_index)
+    assert body_match is not None
     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",
-        }
-    ]
-)
+    script = (
+        '<script data-dash-startup-loading-resource="script">'
+        f"{_resource_text('startup-loading.js')}"
+        "</script>"
+    )
+    return app_index[:position] + _overlay_html(config) + script + app_index[position:]
 
 
 @hooks.index(priority=100)

{dash_startup_loading_plugin-0.1.0 → dash_startup_loading_plugin-0.2.0}/src/dash_startup_loading_plugin/resources/startup-loading.css

@@ -37,16 +37,14 @@
     display: none;
 }
 
-html.dark .dash-startup-loading {
-    color: var(--dash-startup-loading-dark-color, #4096ff);
-    background: var(--dash-startup-loading-dark-background, #0f0f0f);
+html[data-dash-startup-loading-theme="light"] .dash-startup-loading {
+    color: var(--dash-startup-loading-color, #1677ff);
+    background: var(--dash-startup-loading-background, #fff);
 }
 
-@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);
-    }
+html[data-dash-startup-loading-theme="dark"] .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_plugin-0.2.0/src/dash_startup_loading_plugin/resources/startup-theme.js

@@ -0,0 +1,102 @@
+(function () {
+    "use strict";
+
+    var root = document.documentElement;
+    var config = window.__dashStartupLoadingThemeConfig || {};
+    var persistencePrefix = "_dash_persistence.";
+
+    function parseStored(value) {
+        if (value === null || value === undefined) {
+            return null;
+        }
+        try {
+            return JSON.parse(value);
+        } catch (_) {
+            return value;
+        }
+    }
+
+    function normalize(value) {
+        if (Array.isArray(value)) {
+            value = value[0];
+        }
+        if (typeof value === "string") {
+            var name = value.toLowerCase();
+            if (name === "dark") return "dark";
+            if (name === "light" || name === "default") return "light";
+            if (name === "system" || name === "auto") return "system";
+            return null;
+        }
+        if (!value || typeof value !== "object") {
+            return null;
+        }
+
+        var explicit = value.mode || value.colorScheme || value.color_scheme;
+        var normalized = normalize(explicit);
+        if (normalized) return normalized;
+
+        var algorithms = Array.isArray(value.algorithm) ? value.algorithm : [value.algorithm];
+        if (algorithms.some(function (algorithm) { return algorithm === "dark"; })) return "dark";
+        if (algorithms.some(function (algorithm) { return algorithm === "default"; })) return "light";
+
+        return Object.keys(value).length ? "light" : null;
+    }
+
+    function rootTheme() {
+        if (root.classList.contains("dark")) return "dark";
+        if (root.classList.contains("light")) return "light";
+        return normalize(
+            root.getAttribute("data-theme")
+            || root.getAttribute("data-color-scheme")
+            || root.getAttribute("data-mantine-color-scheme")
+        );
+    }
+
+    function dashPersistenceTheme() {
+        var id = config.dashThemeComponentId;
+        var exactPrefix = id ? persistencePrefix + id + ".theme." : null;
+        var fallback = null;
+        try {
+            for (var index = 0; index < localStorage.length; index += 1) {
+                var key = localStorage.key(index);
+                if (!key || key.indexOf(persistencePrefix) !== 0 || key.indexOf(".theme.") < 0) {
+                    continue;
+                }
+                var theme = normalize(parseStored(localStorage.getItem(key)));
+                if (!theme) continue;
+                if (exactPrefix && key.indexOf(exactPrefix) === 0) return theme;
+                if (!fallback) fallback = theme;
+            }
+        } catch (_) {
+            return null;
+        }
+        return fallback;
+    }
+
+    function conventionalStoredTheme() {
+        var keys = ["mantine-color-scheme-value", "theme", "color-theme", "color-scheme"];
+        try {
+            for (var index = 0; index < keys.length; index += 1) {
+                var theme = normalize(parseStored(localStorage.getItem(keys[index])));
+                if (theme) return theme;
+            }
+        } catch (_) {
+            return null;
+        }
+        return null;
+    }
+
+    var configuredTheme = normalize(config.themeMode);
+    var theme = configuredTheme === "light" || configuredTheme === "dark" ? configuredTheme : null;
+    if (!theme && config.dashThemeComponentId) {
+        theme = dashPersistenceTheme();
+    }
+    if (!theme) {
+        theme = rootTheme() || dashPersistenceTheme() || conventionalStoredTheme() || "system";
+    }
+    if (theme === "system") {
+        theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    }
+
+    root.setAttribute("data-dash-startup-loading-theme", theme);
+}());

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dash-startup-loading-plugin
-Version: 0.1.0
+Version: 0.2.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
@@ -20,10 +20,10 @@ Dynamic: license-file
 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`.
+The overlay, CSS, and JavaScript are injected into the final HTML document with
+`hooks.index`, so they are available before Dash and React mount the application
+layout without additional startup resource requests. An app does not need to
+copy assets or replace Dash's `index_string`.
 
 ## Features
 
@@ -32,8 +32,10 @@ does not need to copy assets or replace Dash's `index_string`.
 - 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.
+- Inlines its small startup CSS and JavaScript, avoiding two additional requests.
+- Resolves light and dark themes before first paint from Dash component
+  persistence, Tailwind root classes, Mantine color-scheme state, or the
+  operating-system preference.
 - Exposes a small browser API and emits a completion event.
 - Requires no changes to the app layout or callbacks.
 
@@ -49,7 +51,7 @@ discovery, resource hooks, and the index hook described in the official
 ## Installation
 
 ```bash
-pip install dash-startup-loading-plugin
+pip install "dash-startup-loading-plugin>=0.2.0"
 ```
 
 The package declares the following entry point:
@@ -64,6 +66,17 @@ 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.2.0
+
+- Resolves the loading background before first paint from a persisted
+  `dash_antd_components.ConfigProvider.theme`.
+- Supports Tailwind's `html.dark` and `html.light` classes.
+- Supports Dash Mantine Components' `data-mantine-color-scheme` attribute and
+  `mantine-color-scheme-value` localStorage entry.
+- Adds `theme_mode` and `dash_theme_component_id` configuration.
+- Keeps the startup CSS and JavaScript inline, so theme detection does not add
+  network requests before Dash mounts.
+
 ## Quick start
 
 The defaults work without any plugin-specific code:
@@ -152,14 +165,57 @@ immutable `StartupLoadingConfig` instance.
 | `dark_background` | `"#0f0f0f"` | Dark-theme background color. |
 | `color` | `"#1677ff"` | Light-theme spinner/current color. |
 | `dark_color` | `"#4096ff"` | Dark-theme spinner/current color. |
+| `theme_mode` | `"auto"` | Startup theme policy: `"auto"`, `"light"`, or `"dark"`. Auto follows persisted or active app state, then the operating-system preference. |
+| `dash_theme_component_id` | `None` | Preferred Dash component ID when reading a persisted `theme` prop. When omitted, the first compatible persisted theme is used. |
 | `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`.
+With `theme_mode="auto"`, the inline head bootstrap resolves the startup theme
+in this order:
+
+1. The persisted Dash `theme` for `dash_theme_component_id`, when configured.
+2. An existing `html.dark` or `html.light` class, including Tailwind's manual
+   dark-mode convention.
+3. `data-theme`, `data-color-scheme`, or `data-mantine-color-scheme` on
+   `<html>`.
+4. Other Dash local persistence entries for a component's `theme` prop. Set
+   `dash_theme_component_id` when an app contains more than one persisted
+   theme-capable component.
+5. Dash Mantine Components' `mantine-color-scheme-value` localStorage entry,
+   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
+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 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:
+
+```python
+import dash_antd_components as dac
+from dash_startup_loading_plugin import configure
+
+configure(dash_theme_component_id="theme-provider")
+
+provider = dac.ConfigProvider(
+    app_content,
+    id="theme-provider",
+    persistence=True,
+    persisted_props=["theme"],
+    persistence_type="local",
+)
+```
+
+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.
 
 ### Custom loader markup
 
@@ -241,11 +297,18 @@ configure(
 )
 ```
 
-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.
+The plugin preserves Dash's normal index template, injects its stylesheet before
+`</head>`, and inserts the overlay followed by its startup script directly after
+the opening `<body>` tag. The source CSS and JavaScript remain package resources
+for maintainability, but the browser receives them inline and makes no separate
+request for either file. 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.
+
+Because the resources are inline, applications with a strict Content Security
+Policy must permit the injected style and script, or add nonce support in a
+customized deployment. The previous external-resource form is more suitable
+when a policy forbids all inline code.
 
 ## Scope and process model
 
@@ -294,15 +357,108 @@ Run the tests and example:
 
 ```bash
 uv run pytest
-uv run python examples/basic.py
+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).

{dash_startup_loading_plugin-0.1.0 → dash_startup_loading_plugin-0.2.0}/src/dash_startup_loading_plugin.egg-info/SOURCES.txt

@@ -11,4 +11,5 @@ src/dash_startup_loading_plugin.egg-info/requires.txt
 src/dash_startup_loading_plugin.egg-info/top_level.txt
 src/dash_startup_loading_plugin/resources/startup-loading.css
 src/dash_startup_loading_plugin/resources/startup-loading.js
+src/dash_startup_loading_plugin/resources/startup-theme.js
 tests/test_plugin.py

{dash_startup_loading_plugin-0.1.0 → dash_startup_loading_plugin-0.2.0}/tests/test_plugin.py

@@ -1,6 +1,7 @@
 import html
 import json
 import re
+from importlib.resources import files
 
 import pytest
 from dash import Dash
@@ -27,8 +28,16 @@ def test_injects_overlay_after_body_with_custom_attributes():
 
     result = _inject_overlay(index)
 
+    assert '<style data-dash-startup-loading-resource="style">' in result
+    assert result.index("<style") < result.index("</head>")
+    assert '<script data-dash-startup-loading-resource="theme">' in result
+    assert result.index('data-dash-startup-loading-resource="theme"') < result.index("</head>")
     assert '<body class="app"><div id="dash-startup-loading"' in result
-    assert result.count("data-dash-startup-loading") == 1
+    assert '<script data-dash-startup-loading-resource="script">' in result
+    assert result.index('id="dash-startup-loading"') < result.index(
+        '<script data-dash-startup-loading-resource="script">'
+    )
+    assert result.count(" data-dash-startup-loading ") == 1
     assert '<span class="dash-startup-loading__spinner"' in result
     assert _data_config(result)["requiredSelectors"] == ["#react-entry-point"]
 
@@ -81,12 +90,53 @@ def test_configuration_validation():
         configure(required_selectors="#header")
     with pytest.raises(ValueError, match="timeout_ms"):
         configure(timeout_ms=-1)
+    with pytest.raises(ValueError, match="theme_mode"):
+        configure(theme_mode="sepia")
+    with pytest.raises(ValueError, match="dash_theme_component_id"):
+        configure(dash_theme_component_id="")
     with pytest.raises(TypeError, match="Unknown"):
         configure(unknown=True)
     assert get_config().required_selectors == ("#react-entry-point",)
 
 
-def test_dash_index_contains_overlay_and_packaged_resources():
+def test_resolved_startup_theme_controls_overlay_colors():
+    css = (
+        files("dash_startup_loading_plugin")
+        .joinpath("resources/startup-loading.css")
+        .read_text(encoding="utf-8")
+    )
+
+    assert 'html[data-dash-startup-loading-theme="light"] .dash-startup-loading' in css
+    assert 'html[data-dash-startup-loading-theme="dark"] .dash-startup-loading' in css
+
+
+def test_theme_bootstrap_supports_dash_tailwind_and_mantine_conventions():
+    script = (
+        files("dash_startup_loading_plugin")
+        .joinpath("resources/startup-theme.js")
+        .read_text(encoding="utf-8")
+    )
+
+    assert "_dash_persistence." in script
+    assert 'classList.contains("dark")' in script
+    assert 'data-mantine-color-scheme' in script
+    assert 'mantine-color-scheme-value' in script
+    assert 'data-dash-startup-loading-theme' in script
+    assert 'name === "system" || name === "auto"' in script
+
+
+def test_theme_bootstrap_serializes_component_id_and_explicit_mode():
+    configure(theme_mode="dark", dash_theme_component_id="theme-provider")
+
+    result = _inject_overlay("<html><head></head><body></body></html>")
+
+    assert (
+        'window.__dashStartupLoadingThemeConfig={"themeMode":"dark",'
+        '"dashThemeComponentId":"theme-provider"};'
+    ) in result
+
+
+def test_dash_index_contains_overlay_and_inline_resources():
     app = Dash(__name__)
     app.layout = dash_html.Div("Ready", id="ready")
 
@@ -96,9 +146,8 @@ def test_dash_index_contains_overlay_and_packaged_resources():
 
     assert response.status_code == 200
     assert "data-dash-startup-loading" in index
-    css_url = re.search(r'href="([^"]*dash_startup_loading_plugin/[^"]*startup-loading[^\"]+\.css)"', index)
-    js_url = re.search(r'src="([^"]*dash_startup_loading_plugin/[^"]*startup-loading[^\"]+\.js)"', index)
-    assert css_url is not None
-    assert js_url is not None
-    assert client.get(css_url.group(1)).status_code == 200
-    assert client.get(js_url.group(1)).status_code == 200
+    assert '<style data-dash-startup-loading-resource="style">' in index
+    assert '<script data-dash-startup-loading-resource="theme">' in index
+    assert '<script data-dash-startup-loading-resource="script">' in index
+    assert "resources/startup-loading.css" not in index
+    assert "resources/startup-loading.js" not in index