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

{dash_startup_loading_plugin-1.0.1 → 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.1/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.1
+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
@@ -14,7 +14,8 @@ Dynamic: license-file
 
 # dash-startup-loading-plugin
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+[English](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.md) |
+[简体中文](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.zh-CN.md)
 
 An installable [Dash Hooks plugin](https://dash.plotly.com/dash-plugins-using-hooks)
 that replaces Dash's initial loading presentation with a configurable
@@ -33,7 +34,7 @@ document.
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.1"
+pip install "dash-startup-loading-plugin>=1.0.3"
 ```
 
 Dash discovers the plugin through its `dash_hooks` entry point. Installing the
@@ -61,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
@@ -179,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]")
@@ -207,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.1 → dash_startup_loading_plugin-1.0.3}/README.md

@@ -1,6 +1,7 @@
 # dash-startup-loading-plugin
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+[English](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.md) |
+[简体中文](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.zh-CN.md)
 
 An installable [Dash Hooks plugin](https://dash.plotly.com/dash-plugins-using-hooks)
 that replaces Dash's initial loading presentation with a configurable
@@ -19,7 +20,7 @@ document.
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.1"
+pip install "dash-startup-loading-plugin>=1.0.3"
 ```
 
 Dash discovers the plugin through its `dash_hooks` entry point. Installing the
@@ -47,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
@@ -165,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]")
@@ -193,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.1 → dash_startup_loading_plugin-1.0.3}/README.zh-CN.md

@@ -1,6 +1,7 @@
 # dash-startup-loading-plugin
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+[English](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.md) |
+[简体中文](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.zh-CN.md)
 
 一个基于 [Dash Hooks 插件规范](https://dash.plotly.com/dash-plugins-using-hooks)
 的可安装插件，用于将 Dash 初始加载提示替换为可配置的全屏 loading 遮罩。
@@ -17,7 +18,7 @@
 ## 安装
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.1"
+pip install "dash-startup-loading-plugin>=1.0.3"
 ```
 
 Dash 会通过 `dash_hooks` entry point 自动发现插件。安装后，默认 loading
@@ -45,6 +46,9 @@ if __name__ == "__main__":
     app.run(debug=True)
 ```
 
+默认情况下，遮罩只替换 Dash 自带的 `._dash-loading` 动画，并在 Dash
+渲染出应用布局后关闭。等待懒加载或异步组件的占位节点消失属于可选行为。
+
 如需自定义行为，请在创建 `Dash` 实例前调用 `configure()`：
 
 ```python
@@ -159,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]")
@@ -185,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.1 → 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.1"
+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"
@@ -38,7 +38,12 @@ include-package-data = true
 where = ["src"]
 
 [tool.setuptools.package-data]
-dash_startup_loading_plugin = ["resources/*.css", "resources/*.js"]
+dash_startup_loading_plugin = [
+    "README.md",
+    "README.zh-CN.md",
+    "resources/*.css",
+    "resources/*.js",
+]
 
 [tool.pytest.ini_options]
 addopts = "-q -p no:cacheprovider"

dash_startup_loading_plugin-1.0.3/src/dash_startup_loading_plugin/README.md

@@ -0,0 +1,265 @@
+# dash-startup-loading-plugin
+
+[English](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.md) |
+[简体中文](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.zh-CN.md)
+
+An installable [Dash Hooks plugin](https://dash.plotly.com/dash-plugins-using-hooks)
+that replaces Dash's initial loading presentation with a configurable
+full-screen overlay.
+
+The plugin injects its CSS and JavaScript into Dash's normal index document
+before React mounts. Applications do not need to copy assets or replace
+`index_string`, and Dash's built-in `<div class="_dash-loading">` remains in the
+document.
+
+## Requirements
+
+- Python 3.9 or later
+- Dash 3.0.3 or later
+
+## Installation
+
+```bash
+pip install "dash-startup-loading-plugin>=1.0.3"
+```
+
+Dash discovers the plugin through its `dash_hooks` entry point. Installing the
+package enables the default loading overlay without an explicit import.
+
+When Dash Ant Design (`dash_antd_components`) is installed, the plugin detects
+it automatically and applies matching light and dark loading backgrounds.
+
+## Quick start
+
+The default configuration requires no 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 closes after this layout is ready."),
+    ]
+)
+
+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
+from dash import Dash, html
+from dash_startup_loading_plugin import configure
+
+configure(
+    required_selectors=["#header", "#sidebar-menu"],
+    pending_selector="[data-async-placeholder]",
+    timeout_ms=6000,
+    minimum_display_ms=250,
+    fade_duration_ms=180,
+)
+
+app = Dash(__name__)
+app.layout = html.Main(
+    [
+        html.Header("Header", id="header"),
+        html.Nav("Sidebar", id="sidebar-menu"),
+    ]
+)
+```
+
+## Component-library integrations
+
+Component libraries are not dependencies of this package. Install only the
+libraries used by the application.
+
+### Dash Ant Design
+
+Dash Ant Design is detected automatically. `configure_dac()` is only required
+to override its defaults:
+
+```bash
+pip install dash-ant-design
+```
+
+The plugin does not impose a Dash Ant Design version constraint. Use the
+version compatible with the application's Python and Dash versions.
+
+```python
+from dash_startup_loading_plugin import configure_dac
+
+configure_dac(
+    background="#f5f5f5",
+    dark_background="#202020",
+)
+```
+
+### Dash Mantine Components
+
+`configure_dmc()` uses Mantine's active default theme and registers its
+pre-render color-scheme hook:
+
+```bash
+pip install dash-mantine-components
+```
+
+```python
+from dash_startup_loading_plugin import configure_dmc
+
+configure_dmc()
+```
+
+### feffery-antd-components
+
+Use `configure_fac()` to match the loading overlay to
+`AntdConfigProvider`:
+
+```bash
+pip install feffery-antd-components
+```
+
+The plugin does not pin a feffery-antd-components version. Compatibility is
+determined by the installed component library.
+
+```python
+from dash_startup_loading_plugin import configure_fac
+
+configure_fac(required_selectors=["#fac-app-ready"])
+```
+
+## Installed examples
+
+The package includes four runnable examples:
+
+```bash
+# Dash
+dash-startup-loading-plugin examples.dash
+
+# Dash Mantine Components
+dash-startup-loading-plugin examples.dash-mantine-components
+
+# Dash Ant Design
+dash-startup-loading-plugin examples.dash-ant-design
+
+# feffery-antd-components
+dash-startup-loading-plugin examples.feffery-antd-components
+```
+
+Install the selected example's component library separately. If it cannot be
+imported, the command reports the failed module and the corresponding
+installation command.
+
+Server options are available on every example:
+
+```bash
+dash-startup-loading-plugin examples.dash \
+    --host 127.0.0.1 --port 8050 --debug
+```
+
+## Readiness behavior
+
+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. 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` 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]")
+configure(pending_selector=None)
+```
+
+## Configuration
+
+`configure(**changes)` updates the process-wide immutable
+`StartupLoadingConfig`.
+
+| Option | Default | Description |
+|---|---:|---|
+| `enabled` | `True` | Enable index injection. |
+| `overlay_id` | `"dash-loading"` | Injected overlay ID. |
+| `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` | `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. |
+| `z_index` | `9999` | Overlay stacking order. |
+| `background` | `"#ffffff"` | Light background. |
+| `dark_background` | `"#0f0f0f"` | Dark background. |
+| `color` | `"#1677ff"` | Light spinner color. |
+| `dark_color` | `"#4096ff"` | Dark spinner color. |
+| `theme_mode` | `"auto"` | `"auto"`, `"light"`, or `"dark"`. |
+| `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. |
+| `hide_default_loading` | `True` | Hide the visual `._dash-loading` indicator while the overlay exists. |
+| `custom_loader_html` | `None` | Trusted HTML replacing the default spinner. |
+
+`custom_loader_html` is inserted verbatim and must never contain untrusted
+user input.
+
+## Python API
+
+```python
+from dash_startup_loading_plugin import (
+    StartupLoadingConfig,
+    configure,
+    configure_dac,
+    configure_fac,
+    configure_dmc,
+    get_config,
+    reset_config,
+)
+```
+
+## Browser API
+
+```javascript
+// Recheck readiness.
+window.dashLoading.check();
+
+// Dismiss the default or a custom overlay.
+window.dashLoading.finish();
+window.dashLoading.finish("my-loading-overlay");
+```
+
+Before fading out, the overlay emits a bubbling `dash-loading:ready` event.
+`event.detail.reason` is `"ready"`, `"timeout"`, or `"manual"`.
+
+```javascript
+document.addEventListener("dash-loading:ready", function (event) {
+    console.log(event.detail.reason);
+});
+```
+
+## Notes
+
+- Dash's hook and plugin configuration is process-wide. Use one configuration
+  per process.
+- Resources are inlined, so strict Content Security Policy deployments must
+  allow the injected style and script.
+- The overlay is only for initial application startup. Use `dcc.Loading` or
+  another callback-specific pattern for later callback execution.
+
+## License
+
+MIT

dash_startup_loading_plugin-1.0.3/src/dash_startup_loading_plugin/README.zh-CN.md

@@ -0,0 +1,253 @@
+# dash-startup-loading-plugin
+
+[English](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.md) |
+[简体中文](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.zh-CN.md)
+
+一个基于 [Dash Hooks 插件规范](https://dash.plotly.com/dash-plugins-using-hooks)
+的可安装插件，用于将 Dash 初始加载提示替换为可配置的全屏 loading 遮罩。
+
+插件会在 React 挂载前，将 CSS 和 JavaScript 注入 Dash 的标准 index
+文档。应用无需复制 assets，也无需替换 `index_string`。Dash 自带的
+`<div class="_dash-loading">` 节点仍会保留。
+
+## 环境要求
+
+- Python 3.9 或更高版本
+- Dash 3.0.3 或更高版本
+
+## 安装
+
+```bash
+pip install "dash-startup-loading-plugin>=1.0.3"
+```
+
+Dash 会通过 `dash_hooks` entry point 自动发现插件。安装后，默认 loading
+效果会自动启用，无需在应用中显式导入。
+
+如果环境中安装了 Dash Ant Design（`dash_antd_components`），插件会自动
+识别并应用与其亮色、暗色主题匹配的 loading 背景。
+
+## 快速开始
+
+默认配置无需编写插件相关代码：
+
+```python
+from dash import Dash, html
+
+app = Dash(__name__)
+app.layout = html.Main(
+    [
+        html.H1("My Dash app"),
+        html.P("The overlay closes after this layout is ready."),
+    ]
+)
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+默认情况下，遮罩只替换 Dash 自带的 `._dash-loading` 动画，并在 Dash
+渲染出应用布局后关闭。等待懒加载或异步组件的占位节点消失属于可选行为。
+
+如需自定义行为，请在创建 `Dash` 实例前调用 `configure()`：
+
+```python
+from dash import Dash, html
+from dash_startup_loading_plugin import configure
+
+configure(
+    required_selectors=["#header", "#sidebar-menu"],
+    pending_selector="[data-async-placeholder]",
+    timeout_ms=6000,
+    minimum_display_ms=250,
+    fade_duration_ms=180,
+)
+
+app = Dash(__name__)
+app.layout = html.Main(
+    [
+        html.Header("Header", id="header"),
+        html.Nav("Sidebar", id="sidebar-menu"),
+    ]
+)
+```
+
+## 组件库集成
+
+各组件库不是本插件的依赖。应用只需单独安装实际使用的组件库。
+
+### Dash Ant Design
+
+插件会自动识别 Dash Ant Design。只有需要覆盖默认配置时，才需要调用
+`configure_dac()`：
+
+```bash
+pip install dash-ant-design
+```
+
+本插件不限制 Dash Ant Design 的版本。请安装与应用所用 Python 和 Dash
+版本兼容的版本。
+
+```python
+from dash_startup_loading_plugin import configure_dac
+
+configure_dac(
+    background="#f5f5f5",
+    dark_background="#202020",
+)
+```
+
+### Dash Mantine Components
+
+`configure_dmc()` 会读取 Mantine 的当前默认主题，并注册其预渲染配色
+hook：
+
+```bash
+pip install dash-mantine-components
+```
+
+```python
+from dash_startup_loading_plugin import configure_dmc
+
+configure_dmc()
+```
+
+### feffery-antd-components
+
+使用 `configure_fac()` 使 loading 遮罩与 `AntdConfigProvider` 匹配：
+
+```bash
+pip install feffery-antd-components
+```
+
+本插件不固定 feffery-antd-components 的版本，兼容性由已安装的组件库决定。
+
+```python
+from dash_startup_loading_plugin import configure_fac
+
+configure_fac(required_selectors=["#fac-app-ready"])
+```
+
+## 内置示例
+
+安装包中包含四个可直接运行的示例：
+
+```bash
+# Dash
+dash-startup-loading-plugin examples.dash
+
+# Dash Mantine Components
+dash-startup-loading-plugin examples.dash-mantine-components
+
+# Dash Ant Design
+dash-startup-loading-plugin examples.dash-ant-design
+
+# feffery-antd-components
+dash-startup-loading-plugin examples.feffery-antd-components
+```
+
+组件库需要单独安装。如果所选示例无法导入对应组件库，命令会显示导入失败的
+模块和安装命令。
+
+所有示例都支持服务器参数：
+
+```bash
+dash-startup-loading-plugin examples.dash \
+    --host 127.0.0.1 --port 8050 --debug
+```
+
+## 就绪判断
+
+满足以下条件后，遮罩会关闭：
+
+1. `root_selector` 已存在，且内部不再包含 `._dash-loading`。
+2. 根节点中已有实际渲染内容。
+3. `required_selectors` 中的所有选择器都已匹配到节点。
+4. 如果配置了 `pending_selector`，根节点中已不存在匹配它的节点。
+5. 上述状态连续保持两个动画帧。
+
+`timeout_ms` 是强制关闭的安全兜底。`minimum_display_ms` 适用于正常就绪和
+手动关闭，但不会延迟 timeout。
+
+`pending_selector` 可用于在异步或懒加载占位节点仍存在时延迟关闭遮罩。它只会
+在 `root_selector` 内查找匹配节点。该检查默认关闭；如需等待异步组件加载完成，
+请显式设置为应用自己的 CSS 选择器：
+
+```python
+configure(pending_selector="[data-async-placeholder]")
+configure(pending_selector=None)
+```
+
+## 配置项
+
+`configure(**changes)` 会更新进程级、不可变的 `StartupLoadingConfig`。
+
+| 参数 | 默认值 | 说明 |
+|---|---:|---|
+| `enabled` | `True` | 是否启用 index 注入。 |
+| `overlay_id` | `"dash-loading"` | 注入遮罩的 ID。 |
+| `aria_label` | `"Loading"` | 无障碍状态标签。 |
+| `root_selector` | `"#react-entry-point"` | 用于观察渲染内容的根节点。 |
+| `required_selectors` | `("#react-entry-point",)` | 关闭遮罩前必须存在的节点选择器。 |
+| `pending_selector` | `None` | 可选的根节点内选择器；配置后，所有匹配节点消失才允许关闭。 |
+| `timeout_ms` | `6000` | 强制关闭超时；设置为 `None` 可禁用。 |
+| `minimum_display_ms` | `0` | 最短显示时间。 |
+| `fade_duration_ms` | `160` | 淡出时长。 |
+| `z_index` | `9999` | 遮罩层级。 |
+| `background` | `"#ffffff"` | 亮色背景。 |
+| `dark_background` | `"#0f0f0f"` | 暗色背景。 |
+| `color` | `"#1677ff"` | 亮色 spinner 颜色。 |
+| `dark_color` | `"#4096ff"` | 暗色 spinner 颜色。 |
+| `theme_mode` | `"auto"` | 可选 `"auto"`、`"light"` 或 `"dark"`。 |
+| `dash_theme_component_id` | `None` | 优先读取主题状态的 Dash 持久化组件 ID。 |
+| `spinner_size_px` | `28` | Spinner 宽度和高度。 |
+| `spinner_stroke_px` | `3` | Spinner 描边宽度。 |
+| `hide_default_loading` | `True` | 遮罩存在时隐藏 `._dash-loading` 的视觉效果。 |
+| `custom_loader_html` | `None` | 替换默认 spinner 的可信 HTML。 |
+
+`custom_loader_html` 会原样插入页面，禁止传入任何不可信的用户输入。
+
+## Python API
+
+```python
+from dash_startup_loading_plugin import (
+    StartupLoadingConfig,
+    configure,
+    configure_dac,
+    configure_fac,
+    configure_dmc,
+    get_config,
+    reset_config,
+)
+```
+
+## 浏览器 API
+
+```javascript
+// 重新检查就绪条件。
+window.dashLoading.check();
+
+// 关闭默认或指定遮罩。
+window.dashLoading.finish();
+window.dashLoading.finish("my-loading-overlay");
+```
+
+淡出前，遮罩会触发可冒泡的 `dash-loading:ready` 事件。
+`event.detail.reason` 为 `"ready"`、`"timeout"` 或 `"manual"`。
+
+```javascript
+document.addEventListener("dash-loading:ready", function (event) {
+    console.log(event.detail.reason);
+});
+```
+
+## 注意事项
+
+- Dash hooks 和插件配置是进程级的，同一进程应共用一套配置。
+- 资源以内联方式注入；严格 CSP 部署需要允许相应的 style 和 script。
+- 本插件只处理应用初始启动。后续 callback loading 请使用 `dcc.Loading`
+  或其他针对 callback 的方案。
+
+## License
+
+MIT

{dash_startup_loading_plugin-1.0.1 → 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.1"
+    __version__ = "1.0.3"
 
 from .plugin import (
     StartupLoadingConfig,

{dash_startup_loading_plugin-1.0.1 → 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.1 → 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.1
+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
@@ -14,7 +14,8 @@ Dynamic: license-file
 
 # dash-startup-loading-plugin
 
-[English](README.md) | [简体中文](README.zh-CN.md)
+[English](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.md) |
+[简体中文](https://github.com/C0deBeez/dash-startup-loading-plugin/blob/master/README.zh-CN.md)
 
 An installable [Dash Hooks plugin](https://dash.plotly.com/dash-plugins-using-hooks)
 that replaces Dash's initial loading presentation with a configurable
@@ -33,7 +34,7 @@ document.
 ## Installation
 
 ```bash
-pip install "dash-startup-loading-plugin>=1.0.1"
+pip install "dash-startup-loading-plugin>=1.0.3"
 ```
 
 Dash discovers the plugin through its `dash_hooks` entry point. Installing the
@@ -61,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
@@ -179,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]")
@@ -207,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.1 → dash_startup_loading_plugin-1.0.3}/src/dash_startup_loading_plugin.egg-info/SOURCES.txt

@@ -3,6 +3,8 @@ MANIFEST.in
 README.md
 README.zh-CN.md
 pyproject.toml
+src/dash_startup_loading_plugin/README.md
+src/dash_startup_loading_plugin/README.zh-CN.md
 src/dash_startup_loading_plugin/__init__.py
 src/dash_startup_loading_plugin/plugin.py
 src/dash_startup_loading_plugin.egg-info/PKG-INFO

dash_startup_loading_plugin-1.0.3/tests/test_documentation.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+import tomllib
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+def test_pypi_description_uses_english_readme():
+    pyproject = tomllib.loads(
+        (PROJECT_ROOT / "pyproject.toml").read_text(encoding="utf-8")
+    )
+
+    assert pyproject["project"]["readme"] == "README.md"
+    assert "An installable" in (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
+
+
+def test_readmes_use_current_selector_and_installation_examples():
+    english = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
+    chinese = (PROJECT_ROOT / "README.zh-CN.md").read_text(encoding="utf-8")
+
+    for readme in (english, chinese):
+        assert "#header" in readme
+        assert "#sidebar-menu" in readme
+        assert "pending_selector" in readme
+        assert "pip install dash-ant-design" in readme
+        assert "pip install feffery-antd-components" in readme
+        assert "usage-header" not in readme
+        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
+
+
+def test_readmes_link_to_each_other():
+    english = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
+    chinese = (PROJECT_ROOT / "README.zh-CN.md").read_text(encoding="utf-8")
+
+    chinese_link = (
+        "[简体中文](https://github.com/C0deBeez/"
+        "dash-startup-loading-plugin/blob/master/README.zh-CN.md)"
+    )
+    english_link = (
+        "[English](https://github.com/C0deBeez/"
+        "dash-startup-loading-plugin/blob/master/README.md)"
+    )
+
+    for readme in (english, chinese):
+        assert chinese_link in readme
+        assert english_link in readme
+
+
+def test_packaged_chinese_readme_matches_project_readme():
+    project_readme = (PROJECT_ROOT / "README.zh-CN.md").read_text(encoding="utf-8")
+    packaged_readme = (
+        PROJECT_ROOT
+        / "src"
+        / "dash_startup_loading_plugin"
+        / "README.zh-CN.md"
+    ).read_text(encoding="utf-8")
+
+    assert packaged_readme == project_readme
+
+
+def test_packaged_english_readme_matches_project_readme():
+    project_readme = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
+    packaged_readme = (
+        PROJECT_ROOT
+        / "src"
+        / "dash_startup_loading_plugin"
+        / "README.md"
+    ).read_text(encoding="utf-8")
+
+    assert packaged_readme == project_readme

{dash_startup_loading_plugin-1.0.1 → 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():

dash_startup_loading_plugin-1.0.1/tests/test_documentation.py

@@ -1,28 +0,0 @@
-from pathlib import Path
-
-
-PROJECT_ROOT = Path(__file__).resolve().parents[1]
-
-
-def test_readmes_use_current_selector_and_installation_examples():
-    english = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
-    chinese = (PROJECT_ROOT / "README.zh-CN.md").read_text(encoding="utf-8")
-
-    for readme in (english, chinese):
-        assert "#header" in readme
-        assert "#sidebar-menu" in readme
-        assert "pending_selector" in readme
-        assert "pip install dash-ant-design" in readme
-        assert "pip install feffery-antd-components" in readme
-        assert "usage-header" not in readme
-        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
-
-
-def test_readmes_link_to_each_other():
-    english = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
-    chinese = (PROJECT_ROOT / "README.zh-CN.md").read_text(encoding="utf-8")
-
-    assert "[简体中文](README.zh-CN.md)" in english
-    assert "[English](README.md)" in chinese