Lexigram UI

Overview

Lexigram-ui (experimental, at experimental/apps/lexigram-ui) provides htpy-backed component rendering, HTMX integration, layouts, atoms/molecules/organisms, and theming. Components subclass Component and implement render(); elements are built with el().

Component Pattern

from lexigram.ui import component
from lexigram.ui.core.base import Component, el, render_to_string

class StatCard(Component):
    def __init__(self, label: str, value: str):
        super().__init__()
        self.label = label
        self.value = value

    def render(self):
        return el("div", {"class": "stat-card"},
            el("span", {"class": "stat-label"}, self.label),
            el("span", {"class": "stat-value"}, self.value),
        )

html = render_to_string(StatCard("Users", "1,204"))

el(tag, *children, **attrs) builds an element (htpy when installed, local Element fallback); plain-string children are auto-escaped, wrap trusted HTML in raw(...). Component supports Streamlit-style with blocks, as_child delegation, an on_mount hook, and fluent .add(...).

The @component(name=None, *, cacheable=False) decorator only attaches __component_name__ metadata for DI discovery by UIProvider — it does not register anything itself.

Module Registration

from lexigram.di.module import Module, module
from lexigram.ui import UIModule
from lexigram.ui.config import UIConfig

@module(imports=[UIModule.configure(UIConfig(default_theme="default"))])
class AppModule(Module): ...

UIModule.configure(config) exports RenderableProtocol; the provider binds UIConfig, MetricsCollector, ResponseOptimizer, and RenderCache singletons. UIModule.stub() gives a no-op for tests.

Config ([ui] section)

ui:
  default_theme: default     # CSS theme name
  theme: light               # active theme
  auto_escape: true
  htmx_version: 2.0.4        # HTMX CDN version
  debug_components: false    # data-component markers (warns in production)
  enable_sse: false

Env prefix LEX_UI__.

Static Files

Static serving comes from lexigram-web's middleware (constructor takes ASGI app first — use partial/wrapper when adding via middleware list):

from lexigram.web.middleware.static import StaticFilesMiddleware

StaticFilesMiddleware(app, directory="static", prefix="/static")
# html=True enables index.html resolution; cache_max_age sets Cache-Control

Common Mistakes

• Expecting @component(...) to register globally — registration happens through UIProvider discovery
• Building HTML with f-strings — use el(); plain strings are escaped, raw() is the explicit opt-out
• Forgetting to call super().__init__() in Component.__init__ — breaks context-stack and on_mount
• Enabling debug_components in production — emits debug comments on every fragment