dash-splash-plugin 0.1.0__tar.gz

dash_splash_plugin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dash_splash_plugin-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+prune tests
+prune scripts
+prune docs
+exclude package.json package-lock.json tsconfig.json usage.py
+include README.md README.zh-CN.md

dash_splash_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,513 @@
+Metadata-Version: 2.4
+Name: dash-splash-plugin
+Version: 0.1.0
+Summary: A configurable full-screen startup loading overlay for Dash apps, packaged as a Dash Hooks plugin.
+Author-email: Ethan Zhang <ethan.zhang2016@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/c0debeez/dash-splash-plugin
+Project-URL: Bug Reports, https://github.com/c0debeez/dash-splash-plugin/issues
+Project-URL: Source, https://github.com/c0debeez/dash-splash-plugin
+Keywords: dash,plotly,loading,plugin
+Classifier: Framework :: Dash
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: src/dash_splash_plugin/resources/licenses/SOURCES.json
+License-File: src/dash_splash_plugin/resources/licenses/UPSTREAM-INVENTORY.md
+License-File: src/dash_splash_plugin/resources/licenses/dash-loading-components-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/dash-loading-components-NOTICE.txt
+License-File: src/dash_splash_plugin/resources/licenses/loading-ui-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__alerix_m3-loading-indicator-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__alerix_m3-loading-indicator-NOTICE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__ant-design_colors-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__ant-design_cssinjs-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__ant-design_cssinjs-utils-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__ant-design_fast-color-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__ant-design_icons-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__ant-design_react-slick-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__babel_runtime-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__emotion_hash-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__emotion_is-prop-valid-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__emotion_memoize-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__emotion_unitless-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_async-validator-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_cascader-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_cascader-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_checkbox-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_collapse-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_color-picker-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_context-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_dialog-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_drawer-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_dropdown-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_form-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_image-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_image-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_input-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_input-number-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_listy-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_mentions-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_mentions-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_menu-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_menu-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_mini-decimal-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_motion-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_mutate-observer-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_notification-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_notification-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_overflow-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_pagination-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_picker-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_picker-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_portal-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_progress-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_progress-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_qrcode-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_rate-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_resize-observer-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_segmented-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_segmented-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_segmented_node_modules__babel_runtime-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_select-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_select-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_slider-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_steps-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_steps-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_switch-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_table-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_table-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_tabs-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_tabs-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_tooltip-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_tour-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_tree-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_tree-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_tree-select-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_tree-select-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_trigger-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_upload-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_util-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_util_node_modules_react-is-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_virtual-list-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__rc-component_virtual-list_node_modules__babel_runtime-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__types_prop-types-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__types_react-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules__types_react-dom-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_antd-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_camelize-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_clsx-license.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_compute-scroll-into-view-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_css-color-keywords-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_css-to-react-native-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_csstype-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_dayjs-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_flicker-dot-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_framer-motion-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_gridora-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_js-tokens-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_json2mq-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_ldrs-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_loadersz-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_loose-envify-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_motion-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_motion-dom-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_motion-utils-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_object-assign-license.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_postcss-value-parser-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_premium-react-loaders-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_prop-types-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_react-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_react-dom-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_react-epic-spinners-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_react-is-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_react-loader-spinner-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_react-loading-indicators-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_react-spinners-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_scheduler-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_scroll-into-view-if-needed-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_spinners-react-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_string-convert-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_styled-components-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_stylis-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_thinking-orbs-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_throttle-debounce-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_tinycolor2-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/node_modules_tslib-LICENSE.txt.txt
+License-File: src/dash_splash_plugin/resources/licenses/scripts_react19_node_modules_loading-dev-LICENSE.md.txt
+License-File: src/dash_splash_plugin/resources/licenses/scripts_react19_node_modules_react-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/scripts_react19_node_modules_react-dom-LICENSE.txt
+License-File: src/dash_splash_plugin/resources/licenses/scripts_react19_node_modules_scheduler-LICENSE.txt
+Requires-Dist: dash>=4.5.0rc0
+Requires-Dist: typing-extensions>=4.11
+Dynamic: license-file
+
+# dash-splash-plugin
+
+[English](https://github.com/C0deBeez/dash-splash-plugin/blob/master/README.md) |
+[简体中文](https://github.com/C0deBeez/dash-splash-plugin/blob/master/README.zh-CN.md)
+
+A configurable full-screen startup loading overlay for Dash, packaged as a
+[Dash Hooks plugin](https://dash.plotly.com/dash-plugins-using-hooks).
+Install it to enable the default `loading-ui:fade-arc` loader automatically, or choose from 530 generated loader
+identifiers and presets with shared color, size and playback controls. Native Dash and Dash Ant
+Design applications use the same configuration.
+
+## Installation
+
+Requires **Python 3.9+** and **Dash >=4.5.0rc0**.
+
+Host applications can use **React 18.3.1 or React 19**. The plugin bundles a
+private React 19 runtime for native animations and never reads or replaces the
+host's React/ReactDOM. Animations start before Dash's React finishes loading;
+even `loading-dev` does not require changing the application's React version.
+
+Until the first PyPI release, install from a checkout of this repository:
+
+```bash
+pip install -e .
+```
+
+Once published, install the pinned release with:
+
+```bash
+pip install "dash-splash-plugin==0.1.0"
+```
+
+Dash discovers the plugin through its `dash_hooks` entry point. No explicit
+registration, asset copying or `index_string` replacement is needed to enable
+the overlay. Native Ant Design loaders are bundled as separate resources, with no
+additional Python component-library dependency.
+
+## Quick start
+
+Installing the package is enough for a standard Dash app:
+
+```python
+from dash import Dash, html
+
+app = Dash(__name__)
+app.layout = html.Main([
+    html.H1("My Dash app"),
+    html.P("The startup overlay closes after the initial layout mounts."),
+])
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+To customize the overlay, call `setup()` before creating the app:
+
+```python
+from dash import Dash, html
+from dash_splash_plugin import setup
+
+setup(loader="loading-ui:ring", color="#1677ff", size=32, stroke=3, rate=1.0)
+
+app = Dash(__name__)
+app.layout = html.H1("My dashboard")
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+The default loader is `loading-ui:fade-arc`; select it explicitly with `setup(loader="loading-ui:fade-arc")`. Use `setup(loader="antd:spin")` to select the four-dot spinner,
+`setup(loader="loading-ui:text-shimmer", text="Preparing dashboard", font_size=20)` for a
+text animation, or `setup(enabled=False)` to disable the plugin.
+
+### Dash Ant Design
+
+Dash Ant Design is optional. Install it with `pip install dash-ant-design`, then
+use the Python module `dash_antd_components` in your layout. The overlay works
+with these components automatically; configure it with the same `setup()` call.
+
+## Run the interactive demo
+
+From a checkout of this repository:
+
+```bash
+uv sync --group dev
+uv run python usage.py
+```
+
+Open [http://127.0.0.1:5001](http://127.0.0.1:5001). Select **Library**, then search
+**Animation** to preview [Loading UI](https://loading-ui.com/) or a public component
+or preset from dash-loading-components. Use **Preview color** to compare five
+foreground colors. The Python example below updates with syntax highlighting.
+
+Previews use a white background matching the page and an explicit `size=64`.
+They use the isolated animation runtime and the configured `rate` and `playing`
+settings. The selectors update only the preview, not the process-wide configuration.
+
+## Configuration
+
+`setup(**changes)` updates an immutable, process-wide `SplashConfig`.
+Use one configuration per Python process; apps in the same process share it.
+
+Select an animation with a single qualified `library:name` identifier:
+
+```python
+setup()  # Initially uses loading-ui:fade-arc.
+setup(loader="loading-ui:fade-arc")
+setup(loader="flicker:mail")
+setup(loader="spinners:bar")  # No trailing -loader.
+```
+
+`loader` always includes its namespace; short names and a separate `library`
+argument are not accepted. Omitted settings retain their values. Switching the loader
+clears previous `loader_options` unless new options are supplied in the same call.
+Unknown identifiers raise `ValueError` with nearby suggestions and leave the
+current configuration unchanged. The generated `LoaderId` literal provides IDE completion:
+
+```python
+from dash_splash_plugin import LoaderId, setup
+
+loader: LoaderId = "flicker:helix"
+setup(loader=loader)
+```
+
+Calling `setup()` without changes does not reset an existing configuration.
+Use `reset_config()` to restore the defaults. `get_config().loader` always holds
+the complete identifier; there is no separate `library` configuration field.
+
+| Option | Default | Description |
+| --- | ---: | --- |
+| `enabled` | `True` | Enable index injection. |
+| `theme` | `"auto"` | Splash theme policy: `"light"`, `"dark"`, `"auto"` or `"system"`. |
+| `aria_label` | `"Loading"` | Accessible status label. |
+| `z_index` | `9999` | Overlay stacking order. |
+| `background` | `#f5f5f5` | Overlay background in light mode. |
+| `dark_background` | `#000` | Overlay background when the splash resolves to dark mode. |
+| `color` | `"#1890ff"` | Default loader foreground in both themes; set a CSS color to override it. |
+| `dark_color` | `None` | Dark-mode override; falls back to `color`, then inherited foreground. |
+| `text_color` | `None` | Optional text color; falls back to `color`, then inherited foreground. |
+| `dark_text_color` | `None` | Falls back to `text_color`, `dark_color`, `color`, then inherited foreground. |
+| `loader` | `"loading-ui:fade-arc"` | Qualified animation identifier, for example `"flicker:helix"`. |
+| `text` | `"Loading"` | Text rendered by `loading-ui:text*` Loading UI loaders. |
+| `size` | `None` | Loaders retain their native geometry (`antd:spin`: 20px, matching Ant Design Spin medium) unless `size` is specified. Set a CSS pixel size to override; `0` hides the loader. Text loaders use `font_size`. |
+| `stroke` | `None` | Preserve original borders and SVG strokes. A number overrides supported borders and strokes in CSS pixels; dot, text and filled-shape loaders may have no adjustable stroke. |
+| `rate` | `1.0` | Positive relative animation tempo. `2.0` is twice as fast; `0.5` is half speed. |
+| `playing` | `True` | `False` pauses CSS and SVG animations without hiding the loader. |
+| `font_size` | `None` | Font size in CSS pixels for `loading-ui:text*` loaders; independent of container sizing. |
+| `custom_loader_html` | `None` | Trusted HTML replacing the selected loader. |
+| `loader_options` | `None` | JSON-safe native wrapper options; explicit options override common settings. |
+
+`custom_loader_html` is inserted verbatim and must only contain trusted HTML.
+
+### Size and animation
+
+Graphical loaders fit their container's longest side to an explicit `size`, preserving their
+aspect ratio. `size=None` retains each loader's original geometry; `size=0` hides the
+loader. Text loaders retain their original font size unless `font_size` is set.
+`stroke=None` preserves the artwork's original borders and strokes.
+
+`rate` must be a finite positive number. Use `playing=False` to pause animations
+while keeping the loader visible. The `size`, `color`, `rate` and `playing`
+parameter names match `dash-loading-components`. Its pinned React wrappers,
+including their native speed mappings, are reused at build time. Installing its
+Python package is not necessary. Native options use its snake_case names.
+
+```python
+from dash_splash_plugin import list_libraries, list_loaders, setup
+
+print(list_loaders("loading-dev"))
+print(list_libraries())
+setup(loader="loading-dev:arc", size=48, loader_options={"easing": "linear"})
+setup(loader="gridora:orbit", size=48, loader_options={"grid_size": 5})
+setup(loader="flicker:mycelium", size=48)
+setup(loader="loadersz:heatmapping", size=96)
+```
+
+The generated registry covers 47 Loading UI components, four `antd` loaders, and all public
+wrappers/presets from 14 dash-loading-components families: loading-dev, ldrs,
+spinners, spinners-react, loader-spinner, premium, indicators, m3, epic, flicker,
+gridora, loadersz, thinking-orbs and lab. Presets share their component chunk.
+`list_loaders()` and the generated `LoaderId` literal are the source of truth.
+
+Library and loader names use kebab-case. Trailing `-loader` is omitted:
+for example, use `setup(loader="spinners:bar")` or `setup(loader="flicker:mail")`.
+`list_libraries()` lists available namespaces. `list_loaders()` returns qualified
+identifiers; `list_loaders("flicker")` filters them without stripping the namespace.
+Every returned identifier can be passed directly to `setup(loader=...)`.
+Select the four-dot spinner with `setup(loader="antd:spin")`.
+The `antd` library provides these native React presets:
+
+| Loader | Component |
+| --- | --- |
+| `antd:spin` | Default Spin four-dot indicator. |
+| `antd:loading` | Spin with the rotating LoadingOutlined icon. |
+| `antd:progress` | Active Progress bar, 160px wide, with a fixed 70% animated track. This is a loading illustration, not measured startup progress. |
+| `antd:skeleton` | Active Skeleton with a title and two paragraph rows, 160px wide. |
+
+Choose, for example, `setup(loader="antd:skeleton")`. All four are
+pre-rendered from the native React components at build time into HTML and CSS.
+They animate immediately without loading React or a component module at runtime,
+follow the splash color, and support `size`, `rate`, `playing`, and reduced motion.
+Styles are scoped to each loader's shadow root.
+Epic names also omit `-spinner`: use `setup(loader="epic:atom")`
+or `loader="epic:hollow-dots"`. Suffixed Epic names are not accepted.
+All eight Epic presets, 64 Flicker presets (including `helix`), and the
+`spinners`/`spinners-react` libraries also use build-time HTML/CSS and animate
+without downloading a React runtime. The generated registry determines first-paint support.
+When `loader_options` is supplied, the pre-rendered preview appears immediately,
+then the native component mounts with the private runtime to apply those advanced options.
+
+### Theme behavior
+
+Choose the splash theme independently of its color values:
+
+| `theme` | Behavior |
+| --- | --- |
+| `"auto"` (default) | Follow the application's root theme; fall back to light when none is declared. Ignores the system preference. |
+| `"light"` | Always use light colors, regardless of root markers or system preference. |
+| `"dark"` | Always use dark colors. |
+| `"system"` | Follow `prefers-color-scheme`, regardless of root markers. |
+
+In `"auto"` mode, a valid `html[data-theme="light"]` or `html[data-theme="dark"]`
+takes priority over `html.dark` / `html.light`. Unrecognized attribute values
+fall back to the classes; without a dark marker, the splash is light. Changes
+to root markers or the system preference update the appropriate theme mode.
+The plugin only styles its overlay and does not change the application's root markers.
+
+For a light-only application, including when the operating system is dark:
+
+```python
+setup(theme="light", background="#f3f5f4")
+```
+
+For an application with its own theme switch:
+
+```python
+setup(theme="auto", background="#f7f9fc", dark_background="#0b1018")
+```
+
+Initialize root theme markers before Dash mounts, for example with a script in
+`index_string`, so the first paint matches the app. The pre-React splash cannot
+infer a theme declared inside a React `ConfigProvider`. Set `theme="system"`
+explicitly to use the operating system's preference; unlike previous behavior,
+`"auto"` no longer falls back to it.
+
+`background` / `dark_background` choose the overlay colors. `color` / `dark_color`
+choose the loader colors; text loaders support separate `text_color` /
+`dark_text_color` overrides. All loaders use `#1890ff` blue by default in both
+modes. Pre-rendered markup and styles are embedded in the initial response;
+other libraries load their native components from cacheable modules without
+waiting for the host React.
+
+### Configuration validation
+
+`setup()` accepts only the current configuration fields listed above. Unknown
+options raise `TypeError` without changing the active configuration. No aliases
+or deprecated parameter conversions are provided.
+
+```python
+setup(loader="loading-ui:ring", color="#1677ff", size=32, stroke=2)
+setup(loader="loading-ui:text-shimmer", text="Loading", font_size=20)
+```
+
+## Startup lifecycle
+
+The overlay is injected before React mounts and observes Dash's
+`#react-entry-point ._dash-loading` element. When that element disappears, the
+overlay is removed. It does not wait for application-specific background work
+or reappear during later callbacks. Use `dcc.Loading` for callback loading states.
+
+The overlay strictly follows Dash's initial layout mounting. Elapsed time and
+script loading errors do not dismiss it. Its observer is released when the
+overlay is removed.
+
+### First-paint rendering
+
+With default native options, 97 loaders render directly from HTML/CSS embedded
+in the response, without downloading animation modules or React:
+
+| Namespace | Pre-rendered identifiers |
+| --- | ---: |
+| `antd` | 4 |
+| `epic` | 8 |
+| `flicker` | 64 |
+| `spinners` | 12 |
+| `spinners-react` | 9 |
+
+Pre-rendered loaders display their build-time HTML/CSS immediately and do not mount
+a React tree or request animation modules with default options. Other libraries use an inline HTML/CSS
+fallback only while their selected module loads. Their original React animation mounts immediately
+in an independent root with Shadow DOM style isolation. Motion components use the
+real Motion runtime. The main Dash root is never replaced. A failed import or
+render keeps the fallback. There is no forced minimum display time.
+
+Only the selected module, its stylesheet and shared dependencies are requested.
+Assets have content-hashed names and immutable caching. Removing the overlay first
+unmounts its React tree and disconnects observers. Delayed imports
+cannot remount a dismissed overlay. Reduced-motion preferences pause animations.
+Strict Content Security Policy must allow the inline startup script/style and
+same-origin module/style resources under `_dash-splash-plugin/react/`.
+
+### Troubleshooting
+
+- After rebuilding or upgrading the plugin, restart the Dash process. A running
+  process caches the resource manifest; old hashed asset URLs may no longer exist.
+- For non-pre-rendered loaders, a brief generic spinner while the selected module
+  downloads is expected. It does not wait for Dash's React. A persistent fallback
+  indicates an asset or rendering failure; inspect browser errors and requests
+  under `_dash-splash-plugin/react/`.
+- Invalid loader identifiers fail during `setup()` instead of silently selecting
+  another animation. Use `list_loaders()` to inspect supported identifiers.
+
+## Python API
+
+```python
+from dash_splash_plugin import (
+    LoaderId,
+    LoaderLibrary,
+    SplashConfig,
+    setup,
+    get_config,
+    list_loaders,
+    list_libraries,
+    reset_config,
+)
+```
+
+`setup()` returns the updated configuration, `get_config()` reads it, and
+`reset_config()` restores the defaults.
+
+## Development
+
+```bash
+uv sync --group test
+uv run pytest -q
+```
+
+To rebuild, run `npm ci` then `uv run python scripts/build_loaders.py`.
+Frontend rebuilding requires a Git checkout. Python wheels and source
+distributions include the Python runtime, prebuilt assets, typing files and
+licenses, but exclude `scripts/`, npm configuration, tests and demo files.
+The build fetches exact upstream commits, generates the registry and Python
+literal, and bundles native React modules with one shared, private React 19 runtime.
+The `scripts/react19` workspace isolates these browser runtime dependencies from
+the React 18 server-rendering/type baseline. The manifest records upstream React
+requirements; the bundled runtime satisfies them without changing the host.
+`--upstream PATH --loading-ui PATH` accepts existing checkouts at those commits.
+Run `npm run typecheck` and `npm run test:browser`; use `ALL_LOADERS=1 npm run test:browser` for all 530 choices.
+Repeat with `REACT_VERSION=19.2.4` to verify isolation from a React 19 host.
+Use `ALL_LOADERS=1 NO_HOST_REACT=1 npm run test:browser` to block the host React
+scripts and check that all animations still render.
+The browser tests need Playwright Chromium (`npx playwright install chromium`)
+and a Python interpreter with Dash 4.5.0rc2 (set `PYTHON` to its executable).
+Node, npm and the source checkouts are not required by wheel/sdist users.
+Development uses Dash 4.5.0rc2. The gallery uses only Dash's built-in controls;
+no additional Python component library is needed.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Bundled third-party licenses, upstream NOTICE and
+source revisions ship in `dash_splash_plugin/resources/licenses/`. The M3 library
+retains Apache-2.0 attribution. Excluded upstream libraries and non-open gallery
+patterns are not imported.