dash-startup-loading-plugin 1.0.2__tar.gz → 1.0.4__tar.gz

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/MANIFEST.in

@@ -1 +1,2 @@
 include README.zh-CN.md
+include README.md

{dash_startup_loading_plugin-1.0.2/src/dash_startup_loading_plugin.egg-info → dash_startup_loading_plugin-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dash-startup-loading-plugin
-Version: 1.0.2
+Version: 1.0.4
 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
@@ -34,7 +34,7 @@ document.
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.2"
+pip install "dash-startup-loading-plugin>=1.0.4"
 ```
 
 Dash discovers the plugin through its `dash_hooks` entry point. Installing the
@@ -62,6 +62,10 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+By default, the overlay only replaces Dash's built-in `._dash-loading`
+animation and closes once Dash has rendered the application layout. Waiting
+for lazy or asynchronous component placeholders is opt-in.
+
 Call `configure()` before creating `Dash` when custom behavior is needed:
 
 ```python
@@ -85,6 +89,30 @@ app.layout = html.Main(
 )
 ```
 
+### Theme behavior
+
+With the default `theme_mode="auto"`, the startup overlay follows an explicit
+application theme from, in order, the root HTML element (including Tailwind's
+`dark`/`light` classes and common theme data attributes), a persisted Dash
+theme component, or conventional theme keys in local storage. If the
+application has not declared a theme preference, the overlay uses the light
+theme; it does not infer a preference from the operating system.
+
+Set the mode explicitly when the application does not expose its preference,
+or when the loading screen should always use one theme:
+
+```python
+configure(theme_mode="light")  # or "dark"
+```
+
+An application preference explicitly set to `"system"` or `"auto"` still
+uses `prefers-color-scheme`. Use `dash_theme_component_id` to prefer one Dash
+component when multiple persisted theme values exist:
+
+```python
+configure(theme_mode="auto", dash_theme_component_id="theme-provider")
+```
+
 ## Component-library integrations
 
 Component libraries are not dependencies of this package. Install only the
@@ -180,16 +208,16 @@ The overlay closes when:
 1. `root_selector` exists and no longer contains `._dash-loading`.
 2. The root contains rendered content.
 3. Every `required_selectors` entry exists.
-4. No `pending_selector` node remains under the root.
+4. If `pending_selector` is configured, no matching node remains under the root.
 5. The conditions remain true for two animation frames.
 
 `timeout_ms` is a forced-dismiss fallback. `minimum_display_ms` applies to
 ready and manual dismissal, but does not delay a timeout.
 
-`pending_selector` delays dismissal while any matching element remains inside
-`root_selector`. It is useful for lazy or asynchronous placeholders that are
-mounted before the real content. Set it to an application-specific CSS
-selector, or use `None` when no pending-node check is needed:
+`pending_selector` optionally delays dismissal while any matching element
+remains inside `root_selector`. It is useful for lazy or asynchronous
+placeholders that are mounted before the real content. The check is disabled
+by default; opt in with an application-specific CSS selector:
 
 ```python
 configure(pending_selector="[data-async-placeholder]")
@@ -208,7 +236,7 @@ configure(pending_selector=None)
 | `aria_label` | `"Loading"` | Accessible status label. |
 | `root_selector` | `"#react-entry-point"` | Root observed for rendered content. |
 | `required_selectors` | `("#react-entry-point",)` | Selectors that must exist before dismissal. |
-| `pending_selector` | `"[data-dac-async-placeholder]"` | Selector checked under `root_selector`; dismissal waits until all matches disappear. Use `None` to disable. |
+| `pending_selector` | `None` | Optional selector checked under `root_selector`; when configured, dismissal waits until all matches disappear. |
 | `timeout_ms` | `6000` | Forced-dismiss timeout; use `None` to disable. |
 | `minimum_display_ms` | `0` | Minimum display time. |
 | `fade_duration_ms` | `160` | Fade-out duration. |
@@ -217,7 +245,7 @@ configure(pending_selector=None)
 | `dark_background` | `"#0f0f0f"` | Dark background. |
 | `color` | `"#1677ff"` | Light spinner color. |
 | `dark_color` | `"#4096ff"` | Dark spinner color. |
-| `theme_mode` | `"auto"` | `"auto"`, `"light"`, or `"dark"`. |
+| `theme_mode` | `"auto"` | `"auto"` detects application theme signals and otherwise uses light; `"light"` and `"dark"` force a mode. |
 | `dash_theme_component_id` | `None` | Preferred persisted Dash theme component. |
 | `spinner_size_px` | `28` | Spinner width and height. |
 | `spinner_stroke_px` | `3` | Spinner stroke width. |

{dash_startup_loading_plugin-1.0.2/src/dash_startup_loading_plugin → dash_startup_loading_plugin-1.0.4}/README.md

@@ -20,7 +20,7 @@ document.
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.2"
+pip install "dash-startup-loading-plugin>=1.0.4"
 ```
 
 Dash discovers the plugin through its `dash_hooks` entry point. Installing the
@@ -48,6 +48,10 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+By default, the overlay only replaces Dash's built-in `._dash-loading`
+animation and closes once Dash has rendered the application layout. Waiting
+for lazy or asynchronous component placeholders is opt-in.
+
 Call `configure()` before creating `Dash` when custom behavior is needed:
 
 ```python
@@ -71,6 +75,30 @@ app.layout = html.Main(
 )
 ```
 
+### Theme behavior
+
+With the default `theme_mode="auto"`, the startup overlay follows an explicit
+application theme from, in order, the root HTML element (including Tailwind's
+`dark`/`light` classes and common theme data attributes), a persisted Dash
+theme component, or conventional theme keys in local storage. If the
+application has not declared a theme preference, the overlay uses the light
+theme; it does not infer a preference from the operating system.
+
+Set the mode explicitly when the application does not expose its preference,
+or when the loading screen should always use one theme:
+
+```python
+configure(theme_mode="light")  # or "dark"
+```
+
+An application preference explicitly set to `"system"` or `"auto"` still
+uses `prefers-color-scheme`. Use `dash_theme_component_id` to prefer one Dash
+component when multiple persisted theme values exist:
+
+```python
+configure(theme_mode="auto", dash_theme_component_id="theme-provider")
+```
+
 ## Component-library integrations
 
 Component libraries are not dependencies of this package. Install only the
@@ -166,16 +194,16 @@ The overlay closes when:
 1. `root_selector` exists and no longer contains `._dash-loading`.
 2. The root contains rendered content.
 3. Every `required_selectors` entry exists.
-4. No `pending_selector` node remains under the root.
+4. If `pending_selector` is configured, no matching node remains under the root.
 5. The conditions remain true for two animation frames.
 
 `timeout_ms` is a forced-dismiss fallback. `minimum_display_ms` applies to
 ready and manual dismissal, but does not delay a timeout.
 
-`pending_selector` delays dismissal while any matching element remains inside
-`root_selector`. It is useful for lazy or asynchronous placeholders that are
-mounted before the real content. Set it to an application-specific CSS
-selector, or use `None` when no pending-node check is needed:
+`pending_selector` optionally delays dismissal while any matching element
+remains inside `root_selector`. It is useful for lazy or asynchronous
+placeholders that are mounted before the real content. The check is disabled
+by default; opt in with an application-specific CSS selector:
 
 ```python
 configure(pending_selector="[data-async-placeholder]")
@@ -194,7 +222,7 @@ configure(pending_selector=None)
 | `aria_label` | `"Loading"` | Accessible status label. |
 | `root_selector` | `"#react-entry-point"` | Root observed for rendered content. |
 | `required_selectors` | `("#react-entry-point",)` | Selectors that must exist before dismissal. |
-| `pending_selector` | `"[data-dac-async-placeholder]"` | Selector checked under `root_selector`; dismissal waits until all matches disappear. Use `None` to disable. |
+| `pending_selector` | `None` | Optional selector checked under `root_selector`; when configured, dismissal waits until all matches disappear. |
 | `timeout_ms` | `6000` | Forced-dismiss timeout; use `None` to disable. |
 | `minimum_display_ms` | `0` | Minimum display time. |
 | `fade_duration_ms` | `160` | Fade-out duration. |
@@ -203,7 +231,7 @@ configure(pending_selector=None)
 | `dark_background` | `"#0f0f0f"` | Dark background. |
 | `color` | `"#1677ff"` | Light spinner color. |
 | `dark_color` | `"#4096ff"` | Dark spinner color. |
-| `theme_mode` | `"auto"` | `"auto"`, `"light"`, or `"dark"`. |
+| `theme_mode` | `"auto"` | `"auto"` detects application theme signals and otherwise uses light; `"light"` and `"dark"` force a mode. |
 | `dash_theme_component_id` | `None` | Preferred persisted Dash theme component. |
 | `spinner_size_px` | `28` | Spinner width and height. |
 | `spinner_stroke_px` | `3` | Spinner stroke width. |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/README.zh-CN.md

@@ -18,7 +18,7 @@
 ## 安装
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.2"
+pip install "dash-startup-loading-plugin>=1.0.4"
 ```
 
 Dash 会通过 `dash_hooks` entry point 自动发现插件。安装后，默认 loading
@@ -46,6 +46,9 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+默认情况下，遮罩只替换 Dash 自带的 `._dash-loading` 动画，并在 Dash
+渲染出应用布局后关闭。等待懒加载或异步组件的占位节点消失属于可选行为。
+
 如需自定义行为，请在创建 `Dash` 实例前调用 `configure()`：
 
 ```python
@@ -69,6 +72,27 @@ app.layout = html.Main(
 )
 ```
 
+### 主题行为
+
+默认的 `theme_mode="auto"` 会按顺序读取应用显式提供的主题：HTML 根节点
+（包括 Tailwind 的 `dark`/`light` 类及常见主题 data 属性）、Dash 组件的
+持久化主题值，以及 local storage 中的常见主题键。如果应用没有声明主题
+偏好，loading 遮罩会使用亮色主题，不会根据操作系统配色自动推断。
+
+当应用没有暴露主题偏好，或 loading 页面需要固定主题时，可手动配置：
+
+```python
+configure(theme_mode="light")  # 或 "dark"
+```
+
+如果应用主题偏好明确设置为 `"system"` 或 `"auto"`，插件仍会读取
+`prefers-color-scheme`。当页面中存在多个持久化主题值时，可用
+`dash_theme_component_id` 指定优先读取的 Dash 组件：
+
+```python
+configure(theme_mode="auto", dash_theme_component_id="theme-provider")
+```
+
 ## 组件库集成
 
 各组件库不是本插件的依赖。应用只需单独安装实际使用的组件库。
@@ -160,15 +184,15 @@ dash-startup-loading-plugin examples.dash \
 1. `root_selector` 已存在，且内部不再包含 `._dash-loading`。
 2. 根节点中已有实际渲染内容。
 3. `required_selectors` 中的所有选择器都已匹配到节点。
-4. 根节点中已不存在匹配 `pending_selector` 的节点。
+4. 如果配置了 `pending_selector`，根节点中已不存在匹配它的节点。
 5. 上述状态连续保持两个动画帧。
 
 `timeout_ms` 是强制关闭的安全兜底。`minimum_display_ms` 适用于正常就绪和
 手动关闭，但不会延迟 timeout。
 
-`pending_selector` 用于在异步或懒加载占位节点仍存在时延迟关闭遮罩。它只会
-在 `root_selector` 内查找匹配节点。可以设置为应用自己的 CSS 选择器；如果
-不需要检查占位节点，请设置为 `None`：
+`pending_selector` 可用于在异步或懒加载占位节点仍存在时延迟关闭遮罩。它只会
+在 `root_selector` 内查找匹配节点。该检查默认关闭；如需等待异步组件加载完成，
+请显式设置为应用自己的 CSS 选择器：
 
 ```python
 configure(pending_selector="[data-async-placeholder]")
@@ -186,7 +210,7 @@ configure(pending_selector=None)
 | `aria_label` | `"Loading"` | 无障碍状态标签。 |
 | `root_selector` | `"#react-entry-point"` | 用于观察渲染内容的根节点。 |
 | `required_selectors` | `("#react-entry-point",)` | 关闭遮罩前必须存在的节点选择器。 |
-| `pending_selector` | `"[data-dac-async-placeholder]"` | 在 `root_selector` 内检查；所有匹配节点消失后才允许关闭。设置为 `None` 可禁用。 |
+| `pending_selector` | `None` | 可选的根节点内选择器；配置后，所有匹配节点消失才允许关闭。 |
 | `timeout_ms` | `6000` | 强制关闭超时；设置为 `None` 可禁用。 |
 | `minimum_display_ms` | `0` | 最短显示时间。 |
 | `fade_duration_ms` | `160` | 淡出时长。 |
@@ -195,7 +219,7 @@ configure(pending_selector=None)
 | `dark_background` | `"#0f0f0f"` | 暗色背景。 |
 | `color` | `"#1677ff"` | 亮色 spinner 颜色。 |
 | `dark_color` | `"#4096ff"` | 暗色 spinner 颜色。 |
-| `theme_mode` | `"auto"` | 可选 `"auto"`、`"light"` 或 `"dark"`。 |
+| `theme_mode` | `"auto"` | `"auto"` 自动检测应用主题，未检测到时使用亮色；`"light"` 和 `"dark"` 用于强制指定主题。 |
 | `dash_theme_component_id` | `None` | 优先读取主题状态的 Dash 持久化组件 ID。 |
 | `spinner_size_px` | `28` | Spinner 宽度和高度。 |
 | `spinner_stroke_px` | `3` | Spinner 描边宽度。 |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dash-startup-loading-plugin"
-version = "1.0.2"
+version = "1.0.4"
 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-1.0.2 → dash_startup_loading_plugin-1.0.4/src/dash_startup_loading_plugin}/README.md

@@ -20,7 +20,7 @@ document.
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.2"
+pip install "dash-startup-loading-plugin>=1.0.4"
 ```
 
 Dash discovers the plugin through its `dash_hooks` entry point. Installing the
@@ -48,6 +48,10 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+By default, the overlay only replaces Dash's built-in `._dash-loading`
+animation and closes once Dash has rendered the application layout. Waiting
+for lazy or asynchronous component placeholders is opt-in.
+
 Call `configure()` before creating `Dash` when custom behavior is needed:
 
 ```python
@@ -71,6 +75,30 @@ app.layout = html.Main(
 )
 ```
 
+### Theme behavior
+
+With the default `theme_mode="auto"`, the startup overlay follows an explicit
+application theme from, in order, the root HTML element (including Tailwind's
+`dark`/`light` classes and common theme data attributes), a persisted Dash
+theme component, or conventional theme keys in local storage. If the
+application has not declared a theme preference, the overlay uses the light
+theme; it does not infer a preference from the operating system.
+
+Set the mode explicitly when the application does not expose its preference,
+or when the loading screen should always use one theme:
+
+```python
+configure(theme_mode="light")  # or "dark"
+```
+
+An application preference explicitly set to `"system"` or `"auto"` still
+uses `prefers-color-scheme`. Use `dash_theme_component_id` to prefer one Dash
+component when multiple persisted theme values exist:
+
+```python
+configure(theme_mode="auto", dash_theme_component_id="theme-provider")
+```
+
 ## Component-library integrations
 
 Component libraries are not dependencies of this package. Install only the
@@ -166,16 +194,16 @@ The overlay closes when:
 1. `root_selector` exists and no longer contains `._dash-loading`.
 2. The root contains rendered content.
 3. Every `required_selectors` entry exists.
-4. No `pending_selector` node remains under the root.
+4. If `pending_selector` is configured, no matching node remains under the root.
 5. The conditions remain true for two animation frames.
 
 `timeout_ms` is a forced-dismiss fallback. `minimum_display_ms` applies to
 ready and manual dismissal, but does not delay a timeout.
 
-`pending_selector` delays dismissal while any matching element remains inside
-`root_selector`. It is useful for lazy or asynchronous placeholders that are
-mounted before the real content. Set it to an application-specific CSS
-selector, or use `None` when no pending-node check is needed:
+`pending_selector` optionally delays dismissal while any matching element
+remains inside `root_selector`. It is useful for lazy or asynchronous
+placeholders that are mounted before the real content. The check is disabled
+by default; opt in with an application-specific CSS selector:
 
 ```python
 configure(pending_selector="[data-async-placeholder]")
@@ -194,7 +222,7 @@ configure(pending_selector=None)
 | `aria_label` | `"Loading"` | Accessible status label. |
 | `root_selector` | `"#react-entry-point"` | Root observed for rendered content. |
 | `required_selectors` | `("#react-entry-point",)` | Selectors that must exist before dismissal. |
-| `pending_selector` | `"[data-dac-async-placeholder]"` | Selector checked under `root_selector`; dismissal waits until all matches disappear. Use `None` to disable. |
+| `pending_selector` | `None` | Optional selector checked under `root_selector`; when configured, dismissal waits until all matches disappear. |
 | `timeout_ms` | `6000` | Forced-dismiss timeout; use `None` to disable. |
 | `minimum_display_ms` | `0` | Minimum display time. |
 | `fade_duration_ms` | `160` | Fade-out duration. |
@@ -203,7 +231,7 @@ configure(pending_selector=None)
 | `dark_background` | `"#0f0f0f"` | Dark background. |
 | `color` | `"#1677ff"` | Light spinner color. |
 | `dark_color` | `"#4096ff"` | Dark spinner color. |
-| `theme_mode` | `"auto"` | `"auto"`, `"light"`, or `"dark"`. |
+| `theme_mode` | `"auto"` | `"auto"` detects application theme signals and otherwise uses light; `"light"` and `"dark"` force a mode. |
 | `dash_theme_component_id` | `None` | Preferred persisted Dash theme component. |
 | `spinner_size_px` | `28` | Spinner width and height. |
 | `spinner_stroke_px` | `3` | Spinner stroke width. |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/src/dash_startup_loading_plugin/README.zh-CN.md

@@ -18,7 +18,7 @@
 ## 安装
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.2"
+pip install "dash-startup-loading-plugin>=1.0.4"
 ```
 
 Dash 会通过 `dash_hooks` entry point 自动发现插件。安装后，默认 loading
@@ -46,6 +46,9 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+默认情况下，遮罩只替换 Dash 自带的 `._dash-loading` 动画，并在 Dash
+渲染出应用布局后关闭。等待懒加载或异步组件的占位节点消失属于可选行为。
+
 如需自定义行为，请在创建 `Dash` 实例前调用 `configure()`：
 
 ```python
@@ -69,6 +72,27 @@ app.layout = html.Main(
 )
 ```
 
+### 主题行为
+
+默认的 `theme_mode="auto"` 会按顺序读取应用显式提供的主题：HTML 根节点
+（包括 Tailwind 的 `dark`/`light` 类及常见主题 data 属性）、Dash 组件的
+持久化主题值，以及 local storage 中的常见主题键。如果应用没有声明主题
+偏好，loading 遮罩会使用亮色主题，不会根据操作系统配色自动推断。
+
+当应用没有暴露主题偏好，或 loading 页面需要固定主题时，可手动配置：
+
+```python
+configure(theme_mode="light")  # 或 "dark"
+```
+
+如果应用主题偏好明确设置为 `"system"` 或 `"auto"`，插件仍会读取
+`prefers-color-scheme`。当页面中存在多个持久化主题值时，可用
+`dash_theme_component_id` 指定优先读取的 Dash 组件：
+
+```python
+configure(theme_mode="auto", dash_theme_component_id="theme-provider")
+```
+
 ## 组件库集成
 
 各组件库不是本插件的依赖。应用只需单独安装实际使用的组件库。
@@ -160,15 +184,15 @@ dash-startup-loading-plugin examples.dash \
 1. `root_selector` 已存在，且内部不再包含 `._dash-loading`。
 2. 根节点中已有实际渲染内容。
 3. `required_selectors` 中的所有选择器都已匹配到节点。
-4. 根节点中已不存在匹配 `pending_selector` 的节点。
+4. 如果配置了 `pending_selector`，根节点中已不存在匹配它的节点。
 5. 上述状态连续保持两个动画帧。
 
 `timeout_ms` 是强制关闭的安全兜底。`minimum_display_ms` 适用于正常就绪和
 手动关闭，但不会延迟 timeout。
 
-`pending_selector` 用于在异步或懒加载占位节点仍存在时延迟关闭遮罩。它只会
-在 `root_selector` 内查找匹配节点。可以设置为应用自己的 CSS 选择器；如果
-不需要检查占位节点，请设置为 `None`：
+`pending_selector` 可用于在异步或懒加载占位节点仍存在时延迟关闭遮罩。它只会
+在 `root_selector` 内查找匹配节点。该检查默认关闭；如需等待异步组件加载完成，
+请显式设置为应用自己的 CSS 选择器：
 
 ```python
 configure(pending_selector="[data-async-placeholder]")
@@ -186,7 +210,7 @@ configure(pending_selector=None)
 | `aria_label` | `"Loading"` | 无障碍状态标签。 |
 | `root_selector` | `"#react-entry-point"` | 用于观察渲染内容的根节点。 |
 | `required_selectors` | `("#react-entry-point",)` | 关闭遮罩前必须存在的节点选择器。 |
-| `pending_selector` | `"[data-dac-async-placeholder]"` | 在 `root_selector` 内检查；所有匹配节点消失后才允许关闭。设置为 `None` 可禁用。 |
+| `pending_selector` | `None` | 可选的根节点内选择器；配置后，所有匹配节点消失才允许关闭。 |
 | `timeout_ms` | `6000` | 强制关闭超时；设置为 `None` 可禁用。 |
 | `minimum_display_ms` | `0` | 最短显示时间。 |
 | `fade_duration_ms` | `160` | 淡出时长。 |
@@ -195,7 +219,7 @@ configure(pending_selector=None)
 | `dark_background` | `"#0f0f0f"` | 暗色背景。 |
 | `color` | `"#1677ff"` | 亮色 spinner 颜色。 |
 | `dark_color` | `"#4096ff"` | 暗色 spinner 颜色。 |
-| `theme_mode` | `"auto"` | 可选 `"auto"`、`"light"` 或 `"dark"`。 |
+| `theme_mode` | `"auto"` | `"auto"` 自动检测应用主题，未检测到时使用亮色；`"light"` 和 `"dark"` 用于强制指定主题。 |
 | `dash_theme_component_id` | `None` | 优先读取主题状态的 Dash 持久化组件 ID。 |
 | `spinner_size_px` | `28` | Spinner 宽度和高度。 |
 | `spinner_stroke_px` | `3` | Spinner 描边宽度。 |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/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__ = "1.0.2"
+    __version__ = "1.0.4"
 
 from .plugin import (
     StartupLoadingConfig,

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/src/dash_startup_loading_plugin/plugin.py

@@ -37,7 +37,7 @@ class StartupLoadingConfig:
     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]"
+    pending_selector: str | None = None
     timeout_ms: int | None = 6000
     minimum_display_ms: int = 0
     fade_duration_ms: int = 160

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/src/dash_startup_loading_plugin/resources/theme.js

@@ -92,7 +92,7 @@
         theme = dashPersistenceTheme();
     }
     if (!theme) {
-        theme = rootTheme() || dashPersistenceTheme() || conventionalStoredTheme() || "system";
+        theme = rootTheme() || dashPersistenceTheme() || conventionalStoredTheme() || "light";
     }
     if (theme === "system") {
         theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4/src/dash_startup_loading_plugin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dash-startup-loading-plugin
-Version: 1.0.2
+Version: 1.0.4
 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
@@ -34,7 +34,7 @@ document.
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.2"
+pip install "dash-startup-loading-plugin>=1.0.4"
 ```
 
 Dash discovers the plugin through its `dash_hooks` entry point. Installing the
@@ -62,6 +62,10 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+By default, the overlay only replaces Dash's built-in `._dash-loading`
+animation and closes once Dash has rendered the application layout. Waiting
+for lazy or asynchronous component placeholders is opt-in.
+
 Call `configure()` before creating `Dash` when custom behavior is needed:
 
 ```python
@@ -85,6 +89,30 @@ app.layout = html.Main(
 )
 ```
 
+### Theme behavior
+
+With the default `theme_mode="auto"`, the startup overlay follows an explicit
+application theme from, in order, the root HTML element (including Tailwind's
+`dark`/`light` classes and common theme data attributes), a persisted Dash
+theme component, or conventional theme keys in local storage. If the
+application has not declared a theme preference, the overlay uses the light
+theme; it does not infer a preference from the operating system.
+
+Set the mode explicitly when the application does not expose its preference,
+or when the loading screen should always use one theme:
+
+```python
+configure(theme_mode="light")  # or "dark"
+```
+
+An application preference explicitly set to `"system"` or `"auto"` still
+uses `prefers-color-scheme`. Use `dash_theme_component_id` to prefer one Dash
+component when multiple persisted theme values exist:
+
+```python
+configure(theme_mode="auto", dash_theme_component_id="theme-provider")
+```
+
 ## Component-library integrations
 
 Component libraries are not dependencies of this package. Install only the
@@ -180,16 +208,16 @@ The overlay closes when:
 1. `root_selector` exists and no longer contains `._dash-loading`.
 2. The root contains rendered content.
 3. Every `required_selectors` entry exists.
-4. No `pending_selector` node remains under the root.
+4. If `pending_selector` is configured, no matching node remains under the root.
 5. The conditions remain true for two animation frames.
 
 `timeout_ms` is a forced-dismiss fallback. `minimum_display_ms` applies to
 ready and manual dismissal, but does not delay a timeout.
 
-`pending_selector` delays dismissal while any matching element remains inside
-`root_selector`. It is useful for lazy or asynchronous placeholders that are
-mounted before the real content. Set it to an application-specific CSS
-selector, or use `None` when no pending-node check is needed:
+`pending_selector` optionally delays dismissal while any matching element
+remains inside `root_selector`. It is useful for lazy or asynchronous
+placeholders that are mounted before the real content. The check is disabled
+by default; opt in with an application-specific CSS selector:
 
 ```python
 configure(pending_selector="[data-async-placeholder]")
@@ -208,7 +236,7 @@ configure(pending_selector=None)
 | `aria_label` | `"Loading"` | Accessible status label. |
 | `root_selector` | `"#react-entry-point"` | Root observed for rendered content. |
 | `required_selectors` | `("#react-entry-point",)` | Selectors that must exist before dismissal. |
-| `pending_selector` | `"[data-dac-async-placeholder]"` | Selector checked under `root_selector`; dismissal waits until all matches disappear. Use `None` to disable. |
+| `pending_selector` | `None` | Optional selector checked under `root_selector`; when configured, dismissal waits until all matches disappear. |
 | `timeout_ms` | `6000` | Forced-dismiss timeout; use `None` to disable. |
 | `minimum_display_ms` | `0` | Minimum display time. |
 | `fade_duration_ms` | `160` | Fade-out duration. |
@@ -217,7 +245,7 @@ configure(pending_selector=None)
 | `dark_background` | `"#0f0f0f"` | Dark background. |
 | `color` | `"#1677ff"` | Light spinner color. |
 | `dark_color` | `"#4096ff"` | Dark spinner color. |
-| `theme_mode` | `"auto"` | `"auto"`, `"light"`, or `"dark"`. |
+| `theme_mode` | `"auto"` | `"auto"` detects application theme signals and otherwise uses light; `"light"` and `"dark"` force a mode. |
 | `dash_theme_component_id` | `None` | Preferred persisted Dash theme component. |
 | `spinner_size_px` | `28` | Spinner width and height. |
 | `spinner_stroke_px` | `3` | Spinner stroke width. |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/tests/test_documentation.py

@@ -28,6 +28,9 @@ def test_readmes_use_current_selector_and_installation_examples():
         assert "usage-sidebar-menu" not in readme
         assert "dash-ant-design  # Python 3.10+" not in readme
         assert "feffery-antd-components>=0.4.0" not in readme
+        assert 'theme_mode="auto"' in readme
+        assert 'theme_mode="light"' in readme
+        assert "dash_theme_component_id" in readme
 
 
 def test_readmes_link_to_each_other():

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.4}/tests/test_plugin.py

@@ -61,6 +61,15 @@ def test_injects_overlay_after_body_with_custom_attributes():
     assert result.count(" data-dash-loading ") == 1
     assert '<span class="dash-loading__spinner"' in result
     assert _data_config(result)["requiredSelectors"] == ["#react-entry-point"]
+    assert _data_config(result)["pendingSelector"] is None
+
+
+def test_waiting_for_async_components_is_opt_in():
+    configure(pending_selector="[data-async-placeholder]")
+
+    result = _inject_overlay("<html><body><main></main></body></html>")
+
+    assert _data_config(result)["pendingSelector"] == "[data-async-placeholder]"
 
 
 def test_injection_is_idempotent_and_can_be_disabled():
@@ -202,6 +211,22 @@ def test_theme_bootstrap_supports_dash_tailwind_and_mantine_conventions():
     assert 'name === "system" || name === "auto"' in script
 
 
+def test_theme_bootstrap_defaults_to_light_without_an_app_preference():
+    script = (
+        files("dash_startup_loading_plugin")
+        .joinpath("resources/theme.js")
+        .read_text(encoding="utf-8")
+    )
+
+    assert (
+        'rootTheme() || dashPersistenceTheme() || conventionalStoredTheme() || "light"'
+        in script
+    )
+    assert 'conventionalStoredTheme() || "system"' not in script
+    assert 'theme === "system"' in script
+    assert 'matchMedia("(prefers-color-scheme: dark)")' in script
+
+
 def test_theme_bootstrap_serializes_component_id_and_explicit_mode():
     configure(theme_mode="dark", dash_theme_component_id="theme-provider")