httk.serve.web.widgets
======================

.. py:module:: httk.serve.web.widgets

.. autoapi-nested-parse::

   Static, safe widget authoring contracts and discovery helpers.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /reference/autoapi/httk/serve/web/widgets/assets/index
   /reference/autoapi/httk/serve/web/widgets/core/index
   /reference/autoapi/httk/serve/web/widgets/extraction/index
   /reference/autoapi/httk/serve/web/widgets/loader/index
   /reference/autoapi/httk/serve/web/widgets/optimade_table/index
   /reference/autoapi/httk/serve/web/widgets/table/index


Attributes
----------

.. autoapisummary::

   httk.serve.web.widgets.MAX_WIDGET_ASSET_BYTES
   httk.serve.web.widgets.SUPPORTED_WIDGET_ASSET_CONTENT_TYPES


Exceptions
----------

.. autoapisummary::

   httk.serve.web.widgets.OptimadeTableProtocolError


Classes
-------

.. autoapisummary::

   httk.serve.web.widgets.FunctionWidget
   httk.serve.web.widgets.Widget
   httk.serve.web.widgets.WidgetAsset
   httk.serve.web.widgets.WidgetContext
   httk.serve.web.widgets.WidgetRegistry
   httk.serve.web.widgets.WidgetRenderResult
   httk.serve.web.widgets.SiteWidgetLoader


Functions
---------

.. autoapisummary::

   httk.serve.web.widgets.function_widget
   httk.serve.web.widgets.trusted_html


Package Contents
----------------

.. py:data:: MAX_WIDGET_ASSET_BYTES
   :value: 1000000


   Largest individual trusted widget asset accepted by :class:`WidgetAsset`.

.. py:data:: SUPPORTED_WIDGET_ASSET_CONTENT_TYPES

   The deliberately small content-type vocabulary for internal widget assets.

.. py:class:: FunctionWidget

   An immutable adapter for the common module-level ``render`` facade.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: render_function
      :type:  WidgetRenderer


   .. py:attribute:: source
      :type:  str


   .. py:method:: render(context: WidgetContext, **props: object) -> str | WidgetRenderResult


.. py:class:: Widget

   Bases: :py:obj:`Protocol`


   Advanced immutable widget definition protocol.


   .. py:property:: name
      :type: str



   .. py:property:: source
      :type: str



   .. py:method:: render(context: WidgetContext, **props: object) -> str | WidgetRenderResult


.. py:class:: WidgetAsset

   An immutable, deployment-relative asset declared by trusted widget code.

   ``path`` is relative to ``/_httk/serve/assets/`` and is never interpreted as a
   filesystem path.  The engine serves only assets it has registered while
   rendering this site instance.


   .. py:attribute:: path
      :type:  str


   .. py:attribute:: content
      :type:  bytes


   .. py:attribute:: content_type
      :type:  str


.. py:class:: WidgetContext

   Immutable request and page information made available to widgets.


   .. py:attribute:: route
      :type:  str


   .. py:attribute:: render_mode
      :type:  str


   .. py:attribute:: widget_id
      :type:  str


   .. py:attribute:: query
      :type:  collections.abc.Mapping[str, str]


   .. py:attribute:: postvars
      :type:  collections.abc.Mapping[str, str]


   .. py:attribute:: page
      :type:  collections.abc.Mapping[str, object]


   .. py:attribute:: source_path
      :type:  pathlib.Path


   .. py:attribute:: url_for
      :type:  collections.abc.Callable[[str], str]


   .. py:attribute:: absolute_url_for
      :type:  collections.abc.Callable[[str], str]


   .. py:attribute:: table_runtime
      :type:  object | None
      :value: None



.. py:class:: WidgetRegistry

   Registry for built-ins; aliases never participate in site resolution.


   .. py:method:: register(widget: Widget, *, alias: str | None = None) -> None


   .. py:method:: resolve(name: str) -> Widget | None


   .. py:method:: available() -> list[tuple[str, str]]


.. py:class:: WidgetRenderResult

   An explicitly trusted HTML result returned by a widget.


   .. py:attribute:: html
      :type:  str


   .. py:attribute:: assets
      :type:  tuple[WidgetAsset, Ellipsis]
      :value: ()



.. py:function:: function_widget(render: WidgetRenderer, *, name: str = '', source: str = '') -> FunctionWidget

   Wrap a callable as a :class:`FunctionWidget`.

   Site-local modules normally need no wrapper: a module-level ``render`` is
   discovered automatically.  The helper is useful for explicit definitions.


.. py:function:: trusted_html(value: str) -> WidgetRenderResult

   Mark a widget's reviewed HTML output as trusted.


.. py:class:: SiteWidgetLoader(widgets_dir: pathlib.Path)

   Load ``src/widgets/<name>.py`` without allowing paths to escape it.


   .. py:attribute:: widgets_dir


   .. py:method:: available() -> list[tuple[str, str]]


   .. py:method:: resolve(name: str) -> httk.serve.web.widgets.core.Widget | None


.. py:exception:: OptimadeTableProtocolError

   Bases: :py:obj:`ValueError`


   A declared OPTIMADE table shell cannot meet the browser protocol.