plesty.lib.ui.theme
===================

.. py:module:: plesty.lib.ui.theme

.. autoapi-nested-parse::

   Design tokens and stylesheet of the PLESTY shell.

   Colours are data, not code: they live in ``assets/palette.json`` and the
   widget chrome lives in ``assets/shell.qss``, whose ``{{token}}`` placeholders
   this module substitutes at load time. The tokens mirror the plesty.net theme
   (``theme/static/css/plesty.css``) and the canonical module/type colours, so
   the website, the generated reports, and the lab GUI stay one visual system —
   and a palette change never means editing Python.

   .. code-block:: python

       theme = Theme.load()
       app.setStyleSheet(theme.stylesheet())
       pen_color = theme.color("cyan")          # trace colour by token
       pen_color = theme.series_color(2)        # nth trace of a view



Attributes
----------

.. autoapisummary::

   plesty.lib.ui.theme.ASSETS
   plesty.lib.ui.theme._UNKNOWN


Classes
-------

.. autoapisummary::

   plesty.lib.ui.theme.Theme


Functions
---------

.. autoapisummary::

   plesty.lib.ui.theme._read_asset


Module Contents
---------------

.. py:data:: ASSETS
   :value: 'plesty.lib.ui.assets'


.. py:data:: _UNKNOWN
   :value: '#ff00ff'


.. py:function:: _read_asset(name: str) -> str

   Return the text of a packaged asset.

   :param name: File name inside the assets directory.

   :returns: The file contents.


.. py:class:: Theme

   Resolved design tokens plus the stylesheet built from them.

   :ivar name: Theme identifier, e.g. ``"plesty-dark"``.
   :ivar tokens: Token name → hex colour.
   :ivar series: Token names cycled for successive traces of a view.
   :ivar colormap: Hex stops of the image/heatmap colour map, dark to bright.
   :ivar state: Semantic state name → token name (running, idle, error, …).



   .. py:attribute:: name
      :type:  str
      :value: 'plesty-dark'



   .. py:attribute:: tokens
      :type:  dict[str, str]


   .. py:attribute:: series
      :type:  list[str]
      :value: []



   .. py:attribute:: colormap
      :type:  list[str]
      :value: []



   .. py:attribute:: state
      :type:  dict[str, str]


   .. py:method:: load(palette: Optional[str | pathlib.Path] = None) -> Theme
      :classmethod:


      Load the packaged palette, or a custom one from disk.

      :param palette: Path to a JSON palette with the same keys as the
                      packaged ``palette.json``; ``None`` loads the packaged one.

      :returns: The resolved theme.



   .. py:method:: color(token: str, default: Optional[str] = None) -> str

      Return the hex colour of a design token.

      :param token: Token name (``"cyan"``, ``"violet"``, ``"muted"``, …) or
                    a literal ``#rrggbb`` value, which is passed through.
      :param default: Returned when the token is unknown; without it an unknown
                      token resolves to a glaring magenta rather than failing
                      silently mid-experiment.

      :returns: The hex colour.



   .. py:method:: series_color(index: int) -> str

      Return the colour of the *index*-th trace of a view.

      :param index: Zero-based trace index; wraps around the series list.

      :returns: The hex colour.



   .. py:method:: state_color(state: str) -> str

      Return the colour marking a run or device state.

      :param state: State name, e.g. ``"running"``, ``"error"``, ``"idle"``.

      :returns: The hex colour; unknown states fall back to the muted text colour.



   .. py:method:: stylesheet(source: Optional[str | pathlib.Path] = None) -> str

      Return the Qt stylesheet with every ``{{token}}`` substituted.

      :param source: Path to a custom ``.qss`` template; ``None`` uses the
                     packaged ``shell.qss``.

      :returns: The rendered stylesheet.