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

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.3}/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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dash-startup-loading-plugin
-Version: 1.0.2
+Version: 1.0.3
 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.3"
 ```
 
 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
@@ -180,16 +184,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 +212,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. |

{dash_startup_loading_plugin-1.0.2/src/dash_startup_loading_plugin → dash_startup_loading_plugin-1.0.3}/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.3"
 ```
 
 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
@@ -166,16 +170,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 +198,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. |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.3}/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.3"
 ```
 
 Dash 会通过 `dash_hooks` entry point 自动发现插件。安装后，默认 loading
@@ -46,6 +46,9 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+默认情况下，遮罩只替换 Dash 自带的 `._dash-loading` 动画，并在 Dash
+渲染出应用布局后关闭。等待懒加载或异步组件的占位节点消失属于可选行为。
+
 如需自定义行为，请在创建 `Dash` 实例前调用 `configure()`：
 
 ```python
@@ -160,15 +163,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 +189,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` | 淡出时长。 |

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dash-startup-loading-plugin"
-version = "1.0.2"
+version = "1.0.3"
 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.3/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.3"
 ```
 
 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
@@ -166,16 +170,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 +198,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. |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.3}/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.3"
 ```
 
 Dash 会通过 `dash_hooks` entry point 自动发现插件。安装后，默认 loading
@@ -46,6 +46,9 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+默认情况下，遮罩只替换 Dash 自带的 `._dash-loading` 动画，并在 Dash
+渲染出应用布局后关闭。等待懒加载或异步组件的占位节点消失属于可选行为。
+
 如需自定义行为，请在创建 `Dash` 实例前调用 `configure()`：
 
 ```python
@@ -160,15 +163,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 +189,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` | 淡出时长。 |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.3}/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.3"
 
 from .plugin import (
     StartupLoadingConfig,

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.3}/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.3/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.3
 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.3"
 ```
 
 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
@@ -180,16 +184,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 +212,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. |

{dash_startup_loading_plugin-1.0.2 → dash_startup_loading_plugin-1.0.3}/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():