nicegui-bootstrap-components 0.1.0__py3-none-any.whl

nicegui_bootstrap_components/theme.py

@@ -0,0 +1,238 @@
+"""Per-client color mode and stylesheet selection."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from . import themes as _themes
+from ._host import add_head_html, client_store, get_client, run_javascript
+from .assets import _validate_stylesheet_url, _validated_theme_cdn, get_asset_manager
+
+__all__ = ["ThemeController"]
+
+THEME_STYLE_ID = "ngbs-theme-client"
+
+_MODE_VALUES = {"light", "dark", "auto"}
+
+_RUNTIME_JS = r"""
+(() => {
+  if (window.ngbsSetColorMode) return;
+  const themeStyleId = __NGBS_THEME_STYLE_ID__;
+  const styleMode = __NGBS_STYLE_MODE__;
+  let observer = null;
+  let media = null;
+  let domReadyHandler = null;
+  let lastResolved = 'light';
+  const targets = () => {
+    if (styleMode === 'unscoped') {
+      return document.documentElement ? [document.documentElement] : [];
+    }
+    return document.querySelectorAll('.ngbs, .ngbs-overlay');
+  };
+  const apply = (value) => {
+    lastResolved = value;
+    targets().forEach((el) => el.setAttribute('data-bs-theme', value));
+  };
+  const clearNiceguiObserver = () => {
+    if (observer) { observer.disconnect(); observer = null; }
+    if (domReadyHandler) {
+      document.removeEventListener('DOMContentLoaded', domReadyHandler);
+      domReadyHandler = null;
+    }
+  };
+  const armNiceguiObserver = (read) => {
+    const body = document.body;
+    if (!body) {
+      domReadyHandler = () => {
+        domReadyHandler = null;
+        armNiceguiObserver(read);
+      };
+      document.addEventListener('DOMContentLoaded', domReadyHandler, { once: true });
+      return;
+    }
+    observer = new MutationObserver(() => apply(read() ? 'dark' : 'light'));
+    observer.observe(body, { attributes: true, attributeFilter: ['class'] });
+    apply(read() ? 'dark' : 'light');
+  };
+  window.ngbsApplyCurrentTheme = () => apply(lastResolved);
+  window.ngbsSetColorMode = (mode, followNiceguiDark) => {
+    clearNiceguiObserver();
+    if (media) { media.removeEventListener('change', media._ngbsRun); media = null; }
+    if (mode === 'light' || mode === 'dark') { apply(mode); return; }
+    if (followNiceguiDark) {
+      const read = () => document.body ? document.body.classList.contains('body--dark') : false;
+      armNiceguiObserver(read);
+      return;
+    }
+    media = window.matchMedia('(prefers-color-scheme: dark)');
+    media._ngbsRun = () => apply(media.matches ? 'dark' : 'light');
+    media.addEventListener('change', media._ngbsRun);
+    media._ngbsRun();
+  };
+  const escapeCssString = (value) => value
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r/g, '\\D ')
+    .replace(/\n/g, '\\A ');
+  window.ngbsSetThemeSheet = (href) => {
+    let tag = document.getElementById(themeStyleId);
+    if (!tag) {
+      tag = document.createElement('style');
+      tag.id = themeStyleId;
+      document.head.appendChild(tag);
+    }
+    tag.textContent = '@import url("' + escapeCssString(href) + '") layer(overrides);';
+  };
+})();
+"""
+
+
+def _runtime_js(style_mode: str) -> str:
+    return _RUNTIME_JS.replace("__NGBS_THEME_STYLE_ID__", json.dumps(THEME_STYLE_ID)).replace(
+        "__NGBS_STYLE_MODE__", json.dumps(style_mode)
+    )
+
+
+def _normalize_mode(mode: str | None) -> str:
+    value = str(mode).lower()
+    if value not in _MODE_VALUES:
+        raise ValueError(f"color_mode must be light|dark|auto, got {mode!r}")
+    return value
+
+
+class ThemeController:
+    """Page-lifetime theme state for one NiceGUI client.
+
+    Obtained through :meth:`for_client`; never constructed directly.
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        color_mode: str,
+        follow_nicegui_dark: bool,
+        theme: _themes.Theme,
+    ) -> None:
+        self._client = client
+        self._color_mode = color_mode
+        self._follow_nicegui_dark = follow_nicegui_dark
+        self._theme = theme
+
+    @classmethod
+    def for_client(cls, client: Any | None = None) -> ThemeController:
+        """Bind or return the controller for ``client`` (defaults to the current one)."""
+        target = client if client is not None else get_client()
+        if target is None:
+            raise RuntimeError("ThemeController requires an active client")
+        store = client_store(target)
+        existing = store.get("theme_controller")
+        if isinstance(existing, cls):
+            return existing
+        manager = get_asset_manager()
+        raw_mode = manager.color_mode if manager is not None else "auto"
+        color_mode = _normalize_mode(raw_mode)
+        style_mode = manager.mode.value if manager is not None else "mixed"
+        controller = cls(
+            target,
+            color_mode=color_mode,
+            follow_nicegui_dark=manager.follow_nicegui_dark if manager is not None else True,
+            theme=manager.theme if manager is not None else _themes.BOOTSTRAP,
+        )
+        add_head_html(f"<script>{_runtime_js(style_mode)}</script>", shared=False, client=target)
+        controller._apply()
+        store["theme_controller"] = controller
+        return controller
+
+    # -- state ---------------------------------------------------------
+
+    @property
+    def color_mode(self) -> str:
+        return self._color_mode
+
+    @property
+    def theme(self) -> _themes.Theme:
+        return self._theme
+
+    def set_color_mode(self, mode: str) -> None:
+        """Switch this client to ``light``, ``dark``, or ``auto``."""
+        self._color_mode = _normalize_mode(mode)
+        self._apply()
+
+    def set_theme(self, theme: _themes.Theme | str) -> None:
+        """Swap this client's stylesheet without touching other clients."""
+        resolved = _resolve_theme(theme)
+        manager = get_asset_manager()
+        href = _stylesheet_url(resolved, manager)
+        if href is None:
+            raise RuntimeError("bundled theme selection requires setup() to serve its stylesheet")
+        run_javascript(
+            f"window.ngbsSetThemeSheet && window.ngbsSetThemeSheet({json.dumps(href)});",
+            client=self._client,
+        )
+        self._theme = resolved
+
+    def bind_to_nicegui_dark(self, enabled: bool = True) -> None:
+        """Choose whether ``auto`` follows the host dark state or the OS preference."""
+        self._follow_nicegui_dark = bool(enabled)
+        if self._color_mode == "auto":
+            self._apply()
+
+    # -- internals -----------------------------------------------------
+
+    def _apply(self) -> None:
+        mode = self._color_mode
+        follow = "true" if self._follow_nicegui_dark else "false"
+        run_javascript(
+            f"window.ngbsSetColorMode && window.ngbsSetColorMode({json.dumps(mode)}, {follow});",
+            client=self._client,
+        )
+        # Live anchors are updated by the runtime; the stored value seeds any
+        # scope or overlay root created later in this client.
+        store = client_store(self._client)
+        store["overlay_theme"] = None if mode == "auto" else mode
+
+
+def _resolve_theme(theme: _themes.Theme | str) -> _themes.Theme:
+    if isinstance(theme, _themes.Theme):
+        for candidate in _themes._CATALOGUE:
+            if theme is candidate or theme == candidate:
+                return candidate
+        if theme.cdn:
+            _validate_stylesheet_url(theme.cdn)
+        elif not theme.bundled:
+            raise ValueError("theme must provide a bundled name or a plain http(s) URL")
+        return theme
+    if isinstance(theme, str):
+        for candidate in _themes._CATALOGUE:
+            if theme in {candidate.name, candidate.bundled}:
+                return candidate
+        if theme.lower().startswith(("http://", "https://")):
+            _validate_stylesheet_url(theme)
+            return _themes.Theme(name=theme, cdn=theme, bundled="")
+        valid_names = ", ".join(candidate.name for candidate in _themes._CATALOGUE)
+        raise ValueError(f"unknown theme {theme!r}; valid names: {valid_names}")
+    raise TypeError(f"theme must be a Theme or a name/url string, got {type(theme)!r}")
+
+
+def _stylesheet_url(theme: _themes.Theme, manager: Any) -> str | None:
+    if manager is not None and manager.cdn:
+        return _validated_theme_cdn(theme)
+    if not theme.bundled:
+        return _validate_stylesheet_url(theme.cdn)
+    return manager.bundled_url(theme) if manager is not None else None
+
+
+def ensure_theme_bound() -> None:
+    """Lazy-bind the controller on first library use inside a page."""
+    try:
+        store = client_store()
+    except Exception:
+        return
+    if "theme_controller" in store:
+        return
+    try:
+        ThemeController.for_client()
+    except Exception:
+        return

nicegui_bootstrap_components/themes.py

@@ -0,0 +1,131 @@
+"""Selectable stylesheet constants and their pinned CDN twins."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = [
+    "BOOTSTRAP",
+    "GRID",
+    "CERULEAN",
+    "COSMO",
+    "CYBORG",
+    "DARKLY",
+    "FLATLY",
+    "JOURNAL",
+    "LITERA",
+    "LUMEN",
+    "LUX",
+    "MATERIA",
+    "MINTY",
+    "MORPH",
+    "PULSE",
+    "QUARTZ",
+    "SANDSTONE",
+    "SIMPLEX",
+    "SKETCHY",
+    "SLATE",
+    "SOLAR",
+    "SPACELAB",
+    "SUPERHERO",
+    "UNITED",
+    "VAPOR",
+    "YETI",
+    "ZEPHYR",
+    "Theme",
+]
+
+_CDN_ROOT = "https://cdn.jsdelivr.net/npm"
+_BOOTSTRAP_VERSION = "5.3.8"
+
+
+@dataclass(frozen=True)
+class Theme:
+    """One selectable stylesheet: a bundled build plus its pinned CDN twin.
+
+    ``bundled`` names the package stylesheet pair: ``<bundled>.css`` is the
+    scoped build and ``<bundled>-unscoped.css`` applies document-wide.
+    """
+
+    name: str
+    cdn: str
+    bundled: str
+
+
+BOOTSTRAP = Theme(
+    name="bootstrap",
+    cdn=f"{_CDN_ROOT}/bootstrap@{_BOOTSTRAP_VERSION}/dist/css/bootstrap.min.css",
+    bundled="ngbs-bootstrap",
+)
+
+GRID = Theme(
+    name="grid",
+    cdn=f"{_CDN_ROOT}/bootstrap@{_BOOTSTRAP_VERSION}/dist/css/bootstrap-grid.min.css",
+    bundled="ngbs-grid",
+)
+
+
+def _bootswatch(name: str) -> Theme:
+    return Theme(
+        name=name,
+        cdn=f"{_CDN_ROOT}/bootswatch@{_BOOTSTRAP_VERSION}/dist/{name}/bootstrap.min.css",
+        bundled=f"ngbs-{name}",
+    )
+
+
+CERULEAN = _bootswatch("cerulean")
+COSMO = _bootswatch("cosmo")
+CYBORG = _bootswatch("cyborg")
+DARKLY = _bootswatch("darkly")
+FLATLY = _bootswatch("flatly")
+JOURNAL = _bootswatch("journal")
+LITERA = _bootswatch("litera")
+LUMEN = _bootswatch("lumen")
+LUX = _bootswatch("lux")
+MATERIA = _bootswatch("materia")
+MINTY = _bootswatch("minty")
+MORPH = _bootswatch("morph")
+PULSE = _bootswatch("pulse")
+QUARTZ = _bootswatch("quartz")
+SANDSTONE = _bootswatch("sandstone")
+SIMPLEX = _bootswatch("simplex")
+SKETCHY = _bootswatch("sketchy")
+SLATE = _bootswatch("slate")
+SOLAR = _bootswatch("solar")
+SPACELAB = _bootswatch("spacelab")
+SUPERHERO = _bootswatch("superhero")
+UNITED = _bootswatch("united")
+VAPOR = _bootswatch("vapor")
+YETI = _bootswatch("yeti")
+ZEPHYR = _bootswatch("zephyr")
+
+
+_CATALOGUE = (
+    BOOTSTRAP,
+    GRID,
+    CERULEAN,
+    COSMO,
+    CYBORG,
+    DARKLY,
+    FLATLY,
+    JOURNAL,
+    LITERA,
+    LUMEN,
+    LUX,
+    MATERIA,
+    MINTY,
+    MORPH,
+    PULSE,
+    QUARTZ,
+    SANDSTONE,
+    SIMPLEX,
+    SKETCHY,
+    SLATE,
+    SOLAR,
+    SPACELAB,
+    SUPERHERO,
+    UNITED,
+    VAPOR,
+    YETI,
+    ZEPHYR,
+)

nicegui_bootstrap_components-0.1.0.dist-info/METADATA

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: nicegui-bootstrap-components
+Version: 0.1.0
+Summary: Bootstrap 5 components for NiceGUI, matching the dash-bootstrap-components API, docs, and examples
+Project-URL: Homepage, https://github.com/raffieeey/nicegui-bootstrap-components
+Project-URL: Documentation, https://raffieeey.github.io/nicegui-bootstrap-components/
+Author: raffieeey
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bootstrap,components,dashboard,nicegui,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Requires-Dist: nicegui<4,>=3.17.1
+Provides-Extra: dbc-ref
+Requires-Dist: dash-bootstrap-components==2.0.4; extra == 'dbc-ref'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pandas-stubs; extra == 'dev'
+Requires-Dist: pillow>=10; extra == 'dev'
+Requires-Dist: playwright>=1.47; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: selenium>=4.20; extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: pandas; extra == 'examples'
+Description-Content-Type: text/markdown
+
+# nicegui-bootstrap-components
+
+Bootstrap 5 components for [NiceGUI](https://nicegui.io). The public API matches
+the [dash-bootstrap-components](https://github.com/facultyai/dash-bootstrap-components)
+2.0.4 API for the component set listed below.
+
+[![CI](https://github.com/raffieeey/nicegui-bootstrap-components/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/raffieeey/nicegui-bootstrap-components/actions/workflows/ci.yml)
+[![Python >=3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Install
+
+The package requires Python 3.10 or later and NiceGUI >=3.17.1,<4; it has been
+tested against NiceGUI 3.17.1. It bundles Bootstrap 5.3.8. CI checks the oldest
+supported NiceGUI release and the newest available 3.x release.
+
+```bash
+pip install nicegui-bootstrap-components
+```
+
+`Table.from_dataframe` needs pandas, installed by the optional extra:
+
+```bash
+pip install "nicegui-bootstrap-components[examples]"
+```
+
+## Quickstart
+
+Save this as `app.py` and run `python app.py`. Open the local URL printed in the
+terminal.
+
+```python
+from nicegui import ui
+from nicegui_bootstrap_components import bs
+
+with bs.scope(), bs.container():
+    with bs.row():
+        with bs.col(width=12, md=6):
+            bs.input(placeholder="Name")
+            bs.button("Save", color="primary", on_click=lambda: ui.notify("Saved"))
+
+ui.run()
+```
+
+## Two API surfaces
+
+`nicegui_bootstrap_components.bs` is the native surface: 67 PascalCase classes
+and 67 snake_case aliases (134 exports). Use it for new NiceGUI code.
+
+`nicegui_bootstrap_components.dbc` is the compatibility surface (66 exports)
+with dash-bootstrap-components 2.0.4 prop names. Use it when porting Dash layouts.
+
+```python
+from nicegui import ui
+from nicegui_bootstrap_components import dbc
+
+dbc.Container(
+    dbc.Row(dbc.Col(dbc.Button("Save", color="primary"), md=6)),
+    fluid=True,
+)
+```
+
+Top-level exports: `StyleMode`, `ThemeController`, `bs`, `dbc`, `icons`, `setup`,
+`themes`, `__version__`.
+
+## Style modes
+
+`setup()` registers library CSS once, process-wide, and is idempotent for the same
+arguments. A conflicting mode, or scoped mode with `cdn=True`, raises `ValueError`.
+
+- `StyleMode.UNSCOPED` (`"unscoped"`): Bootstrap-first page.
+- `StyleMode.MIXED` (`"mixed"`): scoped Bootstrap islands inside an existing
+  NiceGUI/Quasar page. Mark islands with `bs.scope()` (`bs.Scope` is the class form).
+
+```python
+from nicegui_bootstrap_components import StyleMode, setup, themes
+
+setup(mode=StyleMode.MIXED, theme=themes.FLATLY, color_mode="auto")
+```
+
+## Themes and dark mode
+
+27 constants on `themes`: Bootstrap itself, the grid-only build, and 25 Bootswatch
+themes. `color_mode="auto"` follows the host app. Pass `icons.BOOTSTRAP` or
+`icons.FONT_AWESOME` to `setup(icons=...)`.
+
+`BOOTSTRAP`, `CERULEAN`, `COSMO`, `CYBORG`, `DARKLY`, `FLATLY`, `GRID`, `JOURNAL`,
+`LITERA`, `LUMEN`, `LUX`, `MATERIA`, `MINTY`, `MORPH`, `PULSE`, `QUARTZ`, `SANDSTONE`,
+`SIMPLEX`, `SKETCHY`, `SLATE`, `SOLAR`, `SPACELAB`, `SUPERHERO`, `UNITED`, `VAPOR`,
+`YETI`, `ZEPHYR`.
+
+## Components
+
+67 native names (each has a snake_case alias on `bs`):
+
+Accordion, AccordionItem, Alert, Badge, Breadcrumb, Button, ButtonGroup, Card, CardBody,
+CardFooter, CardGroup, CardHeader, CardImg, CardImgOverlay, CardLink, Carousel, Checkbox,
+Checklist, Col, Collapse, Container, DropdownMenu, DropdownMenuItem, Fade, Form,
+FormFeedback, FormFloating, FormText, Input, InputGroup, InputGroupText, Label, ListGroup,
+ListGroupItem, Modal, ModalBody, ModalFooter, ModalHeader, ModalTitle, Nav, NavItem,
+NavLink, Navbar, NavbarBrand, NavbarSimple, NavbarToggler, Offcanvas, Pagination,
+Placeholder, Popover, PopoverBody, PopoverHeader, Progress, RadioButton, RadioItems, Row,
+Scope, Select, Spinner, Stack, Switch, Tab, Table, Tabs, Textarea, Toast, Tooltip.
+
+## Layout
+
+```python
+from nicegui_bootstrap_components import bs
+
+with bs.scope(), bs.container():
+    with bs.row():
+        with bs.col(width=12, md=4):
+            bs.label("Full width on phones, one third from md")
+        with bs.col(width=12, md=4):
+            bs.label("Middle")
+        with bs.col(width=12, md=4):
+            bs.label("Right")
+```
+
+## Forms
+
+```python
+from nicegui_bootstrap_components import bs
+
+with bs.scope():
+    bs.input(placeholder="Your name", on_change=lambda: None)
+    bs.select(options={"my": "Malaysia", "sg": "Singapore"}, value="my")
+    bs.checkbox(label="Remember me")
+    bs.switch(label="Enable alerts")
+```
+
+## Cards, alerts, and badges
+
+```python
+from nicegui_bootstrap_components import bs
+
+with bs.scope(), bs.card():
+    bs.card_header("Header")
+    with bs.card_body():
+        bs.alert("Something happened.", color="info", dismissable=True)
+        bs.badge("New", color="success")
+```
+
+## Modal
+
+```python
+from nicegui_bootstrap_components import bs
+
+with bs.scope():
+    with bs.modal() as modal:
+        bs.modal_header("Title")
+        bs.modal_body("Content")
+        bs.modal_footer(bs.button("Close", on_click=modal.close))
+```
+
+## Table
+
+```python
+import pandas as pd
+from nicegui_bootstrap_components import bs
+
+df = pd.DataFrame({"city": ["Kuala Lumpur"], "country": ["Malaysia"]})
+
+with bs.scope():
+    bs.Table.from_dataframe(df, striped=True, bordered=False, hover=True)
+```
+
+## Examples
+
+The gallery mirrors dash-bootstrap-components: Layer 1 component examples, Layer 2
+composite apps (Iris, Graphs in Tabs, Simple Sidebar), and Layer 3 templates.
+
+## Documentation
+
+[https://raffieeey.github.io/nicegui-bootstrap-components/](https://raffieeey.github.io/nicegui-bootstrap-components/)
+
+## Development
+
+```bash
+git clone https://github.com/raffieeey/nicegui-bootstrap-components.git
+cd nicegui-bootstrap-components
+pip install -e ".[dev]"
+pytest
+```
+
+`python -m playwright install chromium`. At 0.1.0, the default run carries
+545 tests plus the Playwright browser suite and the visual matrix; mypy and
+ruff are clean. CI runs three GitHub Actions jobs (checks, docs, browser). The
+browser suite uses real Chromium. Every Python block in the docs and every
+example is executed by tests, so a snippet that cannot run fails CI.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Status
+
+0.1.0, first public release. Matches the dash-bootstrap-components 2.0.4 API for the
+component set listed above.