Referência da API

Os símbolos públicos do tempest_core, gerados a partir das docstrings.

tempest-core — the renderer-agnostic core shared across the tempest stack.

The engine behind both tempestroid (native renderers) and tempestweb (DOM): the IR, reconciler, state model, style model, widgets, components and the cross-cutting helpers (animation, i18n, navigation, theme, validators). It carries no platform-coupled code (no Qt, no JNI, no Android, no DOM) so it imports cleanly under CPython, Pyodide and a headless server.

This is the single source of truth — consumers depend on the published package and import from here (from tempest_core import App, Column, build, diff) rather than vendoring a copy.

Everything a submodule declares public is re-exported here. That is the whole policy, and it exists because the alternative was measured: with only part of the surface re-exported, from tempest_core import Input raised ImportError and a consumer had no choice but to reach into tempest_core.widgets.inputs — 50 files in tempestweb did exactly that, against their own house rule of importing from the package root. A partial root is a root that teaches people to bypass it.

Each name is re-exported in both forms — from x import Y as Y and an entry in :data:__all__. The redundancy is not style: without the as form, basedpyright and Pylance in strict mode report "private import usage" at every consumer call site, and __all__ alone does not silence it.

tests/test_public_surface.py fails if a submodule ever gains a public name this module does not re-export, so the two can no longer drift.

AnimationController

Drives a normalized value on the app's frame clock.

A controller is renderer-agnostic: it owns only its progress (value, 0.0..1.0), the direction it is moving (forward toward 1.0, reverse toward 0.0), and how to advance — either an eased ramp over duration_s or a :class:Spring integration. The app's clock calls :meth:_advance once per frame with the elapsed dt and removes the controller when it reports completion.

The controller binds to an app lazily: it stores no App reference until :meth:forward/:meth:reverse is called after the app has registered it (via :meth:bind), so a controller can be constructed in a view without a circular import.

Attributes:

Name	Type	Description
value	float	The current progress, 0.0..1.0 — read by the view.

Methods:

Name	Description
bind	Attach the controller to an app's frame clock.
forward	Animate value toward 1.0 and (re)register on the app clock.
reverse	Animate value toward 0.0 and (re)register on the app clock.
stop	Halt the animation and unregister from the app clock.

__init__(duration_s, curve=Curve.EASE_IN_OUT, spring=None, *, time_source=None)

Initialize the controller.

Parameters:

Name	Type	Description	Default
duration_s	float	The ramp duration in seconds (ignored when spring is given). Must be positive for a fixed-duration ramp.	required
curve	Curve	The easing curve applied to the linear ramp.	EASE_IN_OUT
spring	Spring | None	Optional spring parameters; when set, the controller integrates a damped oscillator instead of easing over a fixed duration.	None
time_source	Callable[[], float] | None	Optional injectable monotonic clock (seconds). Tests pass a deterministic source; in production the app supplies its own loop clock, so this is normally left unset.	None

bind(app)

Attach the controller to an app's frame clock.

Called by :meth:~tempestroid.core.state.App.register_animation so a later :meth:stop can unregister, and so :meth:forward/:meth:reverse can (re)register even if invoked after construction.

Parameters:

Name	Type	Description	Default
app	_AppClock	The app driving this controller's frames.	required

forward()

Animate value toward 1.0 and (re)register on the app clock.

reverse()

Animate value toward 0.0 and (re)register on the app clock.

stop()

Halt the animation and unregister from the app clock.

Spring

Bases: BaseModel

A spring's physical parameters, used instead of a fixed duration.

When a :class:AnimationController is given a :class:Spring, it advances its value by integrating a damped harmonic oscillator toward the target (1.0 on forward, 0.0 on reverse) rather than easing over a fixed duration_s. Frozen so it can be compared/diffed by value.

Attributes:

Name	Type	Description
stiffness	float	The spring constant k (higher snaps faster).
damping	float	The damping coefficient c (higher settles with less bounce).
mass	float	The attached mass m (higher is more sluggish).

Tween

Bases: BaseModel, Generic[T]

A linear interpolator between two typed endpoints.

Supports float, :class:~tempestroid.style.Color (per-channel), :class:~tempestroid.style.Edge (per-side) and numeric tuple endpoints. The view reads :meth:at with an :class:AnimationController's value to get the per-frame interpolated value, which it then feeds into a :class:~tempestroid.style.Style — so the interpolation stays in the core.

T is the endpoint type being interpolated. It is described here rather than in a section of its own: a type parameter is not an argument, and griffe reports a "Type Args" entry that does not appear in the signature — which mkdocs build --strict turns into a failed docs build.

Attributes:

Name	Type	Description
begin	T	The value at t == 0.0.
end	T	The value at t == 1.0.

Methods:

Name	Description
at	Interpolate between begin and end at fraction t.

at(t)

Interpolate between :attr:begin and :attr:end at fraction t.

Parameters:

Name	Type	Description	Default
t	float	The interpolation fraction, typically an :class:AnimationController's value (0.0..1.0). Values outside [0, 1] extrapolate linearly.	required

Returns:

Type	Description
T	The interpolated value, of the same type as the endpoints.

Raises:

Type	Description
TypeError	If the endpoint type is not a supported interpolatable type.

Accordion

Bases: Component

A titled section whose body shows only when open.

Themed (Trilho H3): the header is styled through :func:~tempest_core.variants.resolve_surface_variant (a filled or outlined Material 3 surface) and the gaps/padding come from the theme's spacing scale. The open flag is controlled (lives in app state), toggled from the header on_toggle.

Attributes:

Name	Type	Description
title	str	The header text.
open	bool	Whether the body is expanded.
children	list[Widget]	The widgets revealed when open.
on_toggle	Callable[[], Any]	Called when the header is tapped (flip open in state).
variant	CardVariant	The surface treatment for the header (filled / outlined / elevated).
color_scheme	str	The Material 3 role family to tint the header with.
theme	Theme	The design-system theme whose tokens resolve the header surface.

render()

Lower the accordion into a primitive column.

Returns:

Type	Description
Widget	A Column of the header button and, when open, the body widgets.

AddressInput

Bases: _BRField

A grouped Brazilian address block of labelled fields.

Renders a labelled Column of CEP (masked 99999-999), street, number, complement, neighborhood, city and UF inputs. A single on_change handler is called as on_change(field_name, new_value) for whichever field changed, where field_name is one of "cep", "street", "number", "complement", "neighborhood", "city" or "state".

Attributes:

Name	Type	Description
cep	str	The current postal code (CEP) value.
street	str	The current street value.
number	str	The current house/building number value.
complement	str	The current address complement value.
neighborhood	str	The current neighborhood value.
city	str	The current city value.
state	str	The current state (UF) value.
label	str	The block heading (omitted when empty).
on_change	Callable[[str, str], Any]	Called as on_change(field_name, new_value) on each edit.

render()

Lower the address block into a labelled column of inputs.

Returns:

Name	Type	Description
A	Widget	class:~tempestroid.widgets.Column of the heading and the
	Widget	address inputs.

Alert

Bases: Component

A block-level status callout: optional icon glyph, title, body and dismiss.

The richer sibling of :class:Banner, lowered through the same :func:~tempest_core.variants.resolve_alert_variant resolver: a row with an optional leading glyph and an optional trailing dismiss widget around a column that stacks the title (bold) over the body text. Use variant=LEFT_ACCENT for the classic accented-edge callout.

Attributes:

Name	Type	Description
title	str	The alert's headline (bold).
body	str | None	An optional secondary line of detail.
glyph	str | None	An optional leading text glyph (no icon font needed).
color_scheme	str	The Material 3 status family to tint with (default "info").
variant	AlertVariant	The alert treatment (subtle / solid / left_accent / top_accent).
dismiss	Widget | None	An optional trailing dismiss widget (e.g. a close Button).
theme	Theme	The design-system theme whose tokens resolve the treatment.

render()

Lower the alert into a themed primitive row.

Returns:

Type	Description
Widget	A themed Row of an optional glyph, the title/body column and an
Widget	optional dismiss widget.

AppBar

Bases: Component

A top application bar: optional leading widget, title and trailing actions.

Themed (Trilho H5): the bar surface is resolved from variant / color_scheme / elevation via :func:~tempest_core.variants.resolve_surface_variant (a Material 3 elevated / filled / outlined bar), and the title color is the resolved surface content color. An explicit style is merged on top of the resolved surface (its set fields win). Backward-compatible: AppBar(title=…) is an elevated neutral bar matching the previous dark-surface look.

Attributes:

Name	Type	Description
title	str	The bar's title text.
leading	Widget | None	An optional widget shown before the title (e.g. a menu or back button); omitted when None.
actions	list[Widget]	Trailing action widgets laid out at the end of the bar.
variant	CardVariant	The surface treatment (elevated / filled / outlined).
color_scheme	str	The Material 3 role family to tint with.
elevation	int | None	An explicit M3 elevation level (0-5) overriding the default.
theme	Theme	The design-system theme whose tokens resolve the bar surface.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; forwarded).

render()

Lower the app bar into a horizontal primitive row.

Returns:

Type	Description
Widget	A Row with the leading widget, a growing title and the actions,
Widget	carrying the resolved surface style.

Avatar

Bases: Component

A round badge showing short initials, themed via the container roles.

Themed (Trilho H4): the circle fills with the color_scheme's tonal *_container role and the initials use its legible on_*_container role (WCAG-AA safe by construction), resolved from the theme rather than a fixed hex. Backward-compatible: Avatar(initials="MB") is a primary-container circle.

Attributes:

Name	Type	Description
initials	str	The short text shown inside the circle (e.g. "MB").
size	float	The circle's diameter in logical pixels.
color_scheme	str	The Material 3 role family the circle tints with.
theme	Theme	The design-system theme resolving the circle colors.

render()

Lower the avatar into a circular container with centered initials.

Returns:

Type	Description
Widget	A Container sized to size wrapping a centered Text.

Badge

Bases: Component

A small inline status pill (count or short label).

Themed (Trilho H4): the pill treatment comes from :func:~tempest_core.variants.resolve_badge_variant against the theme (a Material 3 solid/subtle/outline badge) rather than a hard-coded hex. The legacy tone prop is mapped onto a color_scheme, so Badge(tone="error") keeps working; pass color_scheme / variant / size for the full API.

Attributes:

Name	Type	Description
label	str	The badge text (e.g. a count like "3" or "NEW").
tone	str	The legacy status tone, mapped onto color_scheme when unset.
color_scheme	str | None	The Material 3 status family to tint with; derived from tone when None.
variant	BadgeVariant	The badge treatment (solid / subtle / outline).
size	ResponsiveSize	The density size of the pill.
theme	Theme	The design-system theme whose tokens resolve the treatment.
media	MediaQueryData | None	Optional viewport snapshot for a responsive size.

render()

Lower the badge into a primitive pill.

Returns:

Type	Description
Widget	A small rounded Text pill in the resolved badge style.

Banner

Bases: Component

An inline status bar with a message and an optional trailing action.

Themed (Trilho H4): the background/content come from the :func:~tempest_core.variants.resolve_alert_variant resolver against the theme (a Material 3 subtle alert by default) rather than a hard-coded hex. The legacy tone prop is mapped onto a color_scheme, so Banner(tone="success") keeps working; pass color_scheme / variant directly for the full H4 API.

Attributes:

Name	Type	Description
message	str	The banner text.
tone	str	The legacy status tone ("info" / "success" / "warning" / "error"); mapped onto color_scheme when the latter is unset.
color_scheme	str | None	The Material 3 status family to tint with; None derives it from tone.
variant	AlertVariant	The alert treatment (subtle / solid / left_accent / top_accent).
action	Widget | None	An optional trailing widget (e.g. a dismiss Button).
theme	Theme	The design-system theme whose tokens resolve the treatment.

render()

Lower the banner into a primitive row.

Returns:

Type	Description
Widget	A themed Row with the growing message and the optional action.

BarChart

Bases: _ChartBase

A bar chart drawn over a :class:~tempest_core.widgets.Canvas.

Accepts either a list of :class:ChartSeries (the first series' points become the bars) or, for the trivial single-series case, a plain values list (+ optional labels). Each bar is a :class:~tempest_core.widgets.DrawRect + a :class:~tempest_core.widgets.FillCmd over the shared framed plot rect; the command list is deterministic, so the conformance suite pins it. No new draw command is introduced.

Attributes:

Name	Type	Description
series	list[ChartSeries]	The data series (the first series is plotted as bars). Optional when values is given.
values	list[float]	A convenience single-series value list (used when series is empty).
labels	list[str]	Optional x-axis labels for the bars.

render()

Lower the bar chart into a Canvas of axis + bar commands.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.widgets.Canvas carrying the deterministic
	Widget	draw-command list.

Breadcrumb

Bases: Component

A path trail of crumbs joined by a separator.

Themed (Trilho H5, tokens-only): the separators use the theme's ON_SURFACE_VARIANT role, the current (last) crumb uses ON_SURFACE and a non-current crumb uses ON_SURFACE_VARIANT; a tappable link crumb resolves its style via :func:~tempest_core.variants.resolve_variant (LINK, color_scheme). Backward-compatible: Breadcrumb(items=…) is a neutral trail.

Attributes:

Name	Type	Description
items	list[str]	The crumb labels from root to current, in order.
separator	str	The text drawn between crumbs.
on_select	Callable[[int], Any] | None	Optional handler called with a crumb's index when tapped; when None the crumbs are presentational. The last crumb (current) is never tappable.
color_scheme	str	The Material 3 role family the link crumb paints with.
theme	Theme	The design-system theme whose tokens supply colors and the link.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; forwarded).

render()

Lower the breadcrumb into a primitive row of crumbs and separators.

Returns:

Type	Description
Widget	A Row interleaving crumbs with separator labels.

Burger

Bases: Component

A hamburger menu button.

Themed (Trilho H5): lowers to an :class:~tempest_core.widgets.IconButton showing the curated :data:~tempest_core.icons.Icons.MENU glyph in the GHOST variant, so it reuses the H1 variant resolver and the icon system (a real line icon, not a literal glyph). The legacy glyph prop is a deprecated backward-compatibility fallback: when set to a non-default value it is carried as the accessible label, but the icon is always the Material menu glyph.

Attributes:

Name	Type	Description
on_click	Callable[[], Any]	Invoked when the button is tapped (e.g. to toggle a Drawer).
variant	Variant	The visual treatment (solid/outline/ghost/link); defaults to GHOST.
color_scheme	str	The Material 3 role family to paint with.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
glyph	str	Deprecated. The icon character that previous versions rendered; kept only for backward-compatibility. The button now always shows the Material menu icon — set style to customise.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

render()

Lower the burger into a primitive icon button.

Returns:

Name	Type	Description
An	Widget	class:~tempest_core.widgets.IconButton showing the menu glyph.

Calendar

Bases: Component

A month grid of selectable day cells.

Themed (Trilho H6): the title/day text reads the theme's ON_SURFACE role, the weekday header and unselected days the muted ON_SURFACE_VARIANT / SURFACE_VARIANT roles, and the selected day fills with the color_scheme role (default primary) on its legible on_* content — all resolved from the theme rather than hard-coded hexes. Backward-compatible: Calendar(on_select=…) renders against the default M3 light theme (a visual shift from the previous dark palette).

Attributes:

Name	Type	Description
month	str	The displayed month as "YYYY-MM"; empty means the current month.
selected	str	The selected day as "YYYY-MM-DD" (highlighted when it falls in the displayed month); empty means no selection.
on_select	Callable[[str], Any]	Called with the tapped day's ISO "YYYY-MM-DD" string.
color_scheme	str	The Material 3 role family the selected day fills with.
theme	Theme	The design-system theme whose tokens supply the colors.

render()

Lower the calendar into a primitive month grid.

Returns:

Type	Description
Widget	A Column of a title, a weekday header row and one row per week.

Card

Bases: Component

A themed surface grouping a stack of children (Material 3 card).

Builds on :class:~tempest_core.components.Surface: it resolves the surface treatment from variant / color_scheme / elevation against the theme (via :func:~tempest_core.variants.resolve_surface_variant), adds its own padding, and stacks the children in a Column. Card is exactly Surface + padding + Column. Backward-compatible: a no-arg Card(children=…) produces an elevated, neutral card; an explicit style is merged on top of the resolved surface (its set fields win).

Attributes:

Name	Type	Description
children	list[Widget]	The widgets stacked vertically inside the card.
variant	CardVariant	The surface treatment (elevated / filled / outlined).
color_scheme	str	The Material 3 role family to tint with.
elevation	int | None	An explicit M3 elevation level (0-5) overriding the default.
padding_step	str	The spacing-scale step name for the inner padding.
radius_step	str	The shape-scale step name for the corner radius.
gap_step	str	The spacing-scale step name for the gap between children.
theme	Theme	The design-system theme whose tokens resolve the surface.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; unused).

render()

Lower the card into a themed, padded surface wrapping a column.

Returns:

Type	Description
Widget	A Surface (the resolved variant style) wrapping a padded
Widget	Column of the children.

ChartSeries

Bases: BaseModel

A single named, optionally-colored data series for a chart.

A chart takes a list of these rather than bare list[float] so it can plot several series at once, each with its own label and (optionally) its own color_scheme; an unset color_scheme lets the chart pick from its rotating themed palette by series index.

Attributes:

Name	Type	Description
points	list[float]	The series' y-values, in plot order (one per x position).
label	str	An optional series label (e.g. for a legend; not drawn by the minimal v1 charts but carried for the renderers/legend to read).
color_scheme	str | None	An optional Material 3 role family to color this series with; None falls back to the chart's rotating palette.

Chip

Bases: Component

A small rounded label, optionally selectable, themed via the badge resolver.

Themed (Trilho H4): the pill treatment comes from :func:~tempest_core.variants.resolve_badge_variant against the theme — a solid badge when selected, a subtle badge otherwise. A tappable chip (on_click set) lowers to a Button carrying the resolved badge style; a presentational chip lowers to a Text pill.

Attributes:

Name	Type	Description
label	str	The chip text.
selected	bool	Whether the chip reads as active (a solid badge vs a subtle one).
on_click	Callable[[], Any] | None	Optional tap handler; when None the chip is presentational.
color_scheme	str	The Material 3 role family the chip tints with.
size	ResponsiveSize	The density size of the pill.
theme	Theme	The design-system theme resolving the chip treatment.
media	MediaQueryData | None	Optional viewport snapshot for a responsive size.

render()

Lower the chip into a primitive button or a static pill.

Returns:

Type	Description
Widget	A Button when on_click is set, otherwise a Text pill.

Clock

Bases: Component

A digital clock face rendering a preformatted time string.

Themed (Trilho H6): the time reads the theme's ON_SURFACE role (or an optional color_scheme role), the caption the muted ON_SURFACE_VARIANT role, and the background the SURFACE role — resolved from the theme rather than hard-coded hexes. Backward-compatible: Clock(time=…) renders against the default M3 light theme (a visual shift from the previous dark palette).

Attributes:

Name	Type	Description
time	str	The time text to display (e.g. "12:34:56"); the app formats and ticks it from state.
label	str | None	An optional caption shown muted under the time.
color_scheme	str | None	Optional Material 3 role family tinting the time; None keeps the neutral ON_SURFACE time.
theme	Theme	The design-system theme whose tokens supply the colors.

render()

Lower the clock into a centered primitive column.

Returns:

Type	Description
Widget	A Column with the time and, when set, the label.

CNPJInput

Bases: _BRField

A labelled CNPJ field, masked 99.999.999/9999-99.

Validate with :func:tempestroid.validators.validate_cnpj.

Attributes:

Name	Type	Description
value	str	The current text value (controlled).
label	str	The label shown above the field (omitted when empty).
placeholder	str	The empty-field hint.
error	str	The validation message; shown in the theme's error color.
on_change	Callable[[str], Any]	Called with the new string value on each edit.

render()

Lower the CNPJ input into a labelled column.

Returns:

Type	Description
Widget	A labelled :class:~tempestroid.widgets.Column wrapping a masked
Widget	class:~tempestroid.widgets.MaskedInput.

CollapsingAppBar

Bases: Component

A sliver-style app bar that shrinks as the user scrolls the content down.

Coordinates with a scrollable container's on_scroll handler entirely through state: the application reads the current scroll offset from the list's :class:~tempestroid.ScrollEvent, stores it, and passes it back as :attr:scroll_offset. The component derives a height that eases from :attr:expanded_height (offset 0) down to :attr:collapsed_height (once the offset exceeds the collapse distance) and renders accordingly — so the reconciler simply diffs the derived Style.height as an ordinary prop, needing no new IR, no new event and no renderer change. The title's font shrinks in step with the bar.

Themed (Trilho H5): the bar surface is resolved from variant / color_scheme / elevation via :func:~tempest_core.variants.resolve_surface_variant exactly like :class:AppBar; the height/font collapse derivation is unchanged pure Python. The legacy background prop still wins when set (backward-compatible).

Attributes:

Name	Type	Description
title	str	The bar's title text.
expanded_height	float	The bar height at the top of the scroll (offset 0).
collapsed_height	float	The minimum bar height once fully collapsed.
scroll_offset	float	The current scroll offset (logical pixels) driven by the application from the scrollable's on_scroll handler.
background	Color | None	An optional background color overriding the resolved surface fill (legacy escape hatch).
variant	CardVariant	The surface treatment (elevated / filled / outlined).
color_scheme	str	The Material 3 role family to tint with.
elevation	int | None	An explicit M3 elevation level (0-5) overriding the default.
theme	Theme	The design-system theme whose tokens resolve the bar surface.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; forwarded).
style	Style | None	An optional style overlaid on the bar's derived default.

render()

Lower the collapsing app bar into a primitive container with a title.

Returns:

Type	Description
Widget	A bottom-aligned Container whose height tracks the scroll offset,
Widget	wrapping the title (whose size eases between expanded and collapsed).

ConfidenceBadge

Bases: Component

A status pill showing a model's confidence, colored by threshold.

Composes the H4 :class:~tempest_core.components.Badge, picking its color_scheme from :func:confidence_scheme (success / warning / error) and labelling it as a rounded percentage ("92%"). Optionally prefixes a class name ("cat 92%").

Attributes:

Name	Type	Description
confidence	float	The model confidence in [0, 1].
label	str	An optional prefix (e.g. the predicted class) shown before the percentage.
high	float	The success threshold passed to :func:confidence_scheme.
mid	float	The warning threshold passed to :func:confidence_scheme.
theme	Theme	The design-system theme whose tokens resolve the pill.

render()

Lower the confidence badge into a themed status pill.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.components.Badge whose color_scheme and
	Widget	label encode the confidence.

Note

SUBTLE uses the tonal container pair (WCAG-AA safe), unlike SOLID, which paints white on the saturated status role (success ~3.02, warning ~4.0 — both fail AA). Consistent with the H4 A1 decision.

CPFInput

Bases: _BRField

A labelled CPF field, masked 999.999.999-99.

Validate with :func:tempestroid.validators.validate_cpf.

Attributes:

Name	Type	Description
value	str	The current text value (controlled).
label	str	The label shown above the field (omitted when empty).
placeholder	str	The empty-field hint.
error	str	The validation message; shown in the theme's error color.
on_change	Callable[[str], Any]	Called with the new string value on each edit.

render()

Lower the CPF input into a labelled column.

Returns:

Type	Description
Widget	A labelled :class:~tempestroid.widgets.Column wrapping a masked
Widget	class:~tempestroid.widgets.MaskedInput.

DataTable

Bases: Component

A themed string-matrix table with app-driven sort and pagination.

A styled convenience over the common header-plus-string-matrix case. With Trilho H6 it reads its colors from the :class:~tempest_core.theme.Theme tokens (header fill SURFACE_VARIANT / ON_SURFACE, body SURFACE / ON_SURFACE with a subtle zebra stripe derived from SURFACE_VARIANT, row divider OUTLINE_VARIANT) and offers sortable, tappable headers and an optional pager.

The component owns no state (mirroring the E1 virtualized-list pattern):

• Sort — the application holds sort_column / sort_ascending, passes the rows already sorted, and the table only draws the directional ▲/▼ arrow on the active header and emits on_sort(col) when a header is tapped.
• Paginate — the application holds the current page; when page_size is set the table slices rows[page*page_size : …] for display, renders a pager row (prev / next + "page X/Y"), and emits on_page(page) for prev/next.

Backward-compatible: DataTable(columns=…, rows=…) is a plain themed table; DataTable(sortable=True) keeps the legacy "annotate every header with a sort glyph" behavior when no on_sort is wired.

Attributes:

Name	Type	Description
columns	list[str]	The column header labels.
rows	list[list[str]]	The body rows as a matrix of string cells (the app pre-sorts them).
sortable	bool	Whether headers carry a sort affordance (legacy glyph when no on_sort is wired).
sort_column	int | None	The index of the column the rows are currently sorted by, or None for no active sort.
sort_ascending	bool	Whether the active sort is ascending (▲) or descending (▼).
on_sort	Callable[[int], Any] | None	Called with the tapped column index to request a sort change.
page	int	The current zero-based page index (used when page_size is set).
page_size	int | None	The number of rows shown per page; None shows every row (no pager).
on_page	Callable[[int], Any] | None	Called with the requested zero-based page index on prev/next.
theme	Theme	The design-system theme whose tokens supply the colors.
style	Style | None	An optional style overlaid on the table's default surface.

render()

Lower the data table into a themed column of header + body rows.

Returns:

Type	Description
Widget	A Column of a header row, the current page's body rows (with a
Widget	zebra stripe and a bottom divider each) and, when paginated, a pager
Widget	row.

Note

The zebra stripe is SURFACE_VARIANT mixed halfway toward SURFACE, since the token model has no dedicated SURFACE_CONTAINER role and H6 adds no new token — deterministic, so the conformance suite pins it. Its parity follows the absolute row index, so stripes stay continuous across pages instead of restarting on each page slice.

DetectionBox

Bases: BaseModel

A normalized object-detection bounding box (xyxy in [0, 1]).

Coordinates are fractions of the canvas width/height (0 = left/top, 1 = right/bottom), so a box is resolution-independent and multiplied by the canvas pixel size at draw time. This mirrors the common normalized-xyxy convention without depending on ort-vision-sdk — an adapter from a Detection result lives on the tempestroid side.

Attributes:

Name	Type	Description
x1	float	The left edge as a fraction of the canvas width ([0, 1]).
y1	float	The top edge as a fraction of the canvas height ([0, 1]).
x2	float	The right edge as a fraction of the canvas width ([0, 1]).
y2	float	The bottom edge as a fraction of the canvas height ([0, 1]).
name	str	An optional class label drawn beside the box.
conf	float	The detection confidence in [0, 1] (drives the box color and the label percentage).

DetectionOverlay

Bases: Component

An image with object-detection boxes drawn on top of it.

Lowers to a :class:~tempest_core.widgets.Stack of a base :class:~tempest_core.widgets.Image (fit=COVER) and a :class:~tempest_core.widgets.Canvas overlay. Each :class:DetectionBox (normalized xyxy) is multiplied by the canvas size and drawn as a stroked rectangle (:class:~tempest_core.widgets.DrawRect + :class:~tempest_core.widgets.StrokeCmd) colored by :func:confidence_scheme, with a small filled label background (:class:~tempest_core.widgets.DrawRect + :class:~tempest_core.widgets.FillCmd) and a "{name} {conf:.0%}" caption (:class:~tempest_core.widgets.DrawText). No new draw command is introduced.

Attributes:

Name	Type	Description
image_src	str	The image source (URL or asset path) to box over.
boxes	list[DetectionBox]	The normalized detection boxes to draw.
width	float	The canvas/image width, in logical pixels.
height	float	The canvas/image height, in logical pixels.
high	float	The success threshold passed to :func:confidence_scheme.
mid	float	The warning threshold passed to :func:confidence_scheme.
theme	Theme	The design-system theme whose tokens supply the label color.

render()

Lower the overlay into a stack of an image and a box canvas.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.widgets.Stack of the base image and the
	Widget	detection-box canvas, sized to width × height.

Divider

Bases: Component

A thin horizontal rule, themed with the Material 3 outline-variant color.

Themed (Trilho H3): the line color comes from the theme's OUTLINE_VARIANT role (or an optional color_scheme role) rather than a fixed hex, and the thickness accepts a token-step name (resolved against the shape scale) or a raw float. Backward-compatible: Divider() is a 1px outline-variant rule.

Attributes:

Name	Type	Description
thickness	float | str	The line's height — a token-step name ("xs") or a float in logical pixels.
color_scheme	str | None	Optional Material 3 role family to color the rule; None uses the neutral OUTLINE_VARIANT.
theme	Theme	The design-system theme whose tokens supply the color and step.

render()

Lower the divider into a thin, full-width container.

Returns:

Type	Description
Widget	An empty Container styled as a line in the resolved color.

DocumentPicker

Bases: Component

A labelled document picker.

Attributes:

Name	Type	Description
value	str	The picked document URI ("" until one is chosen).
label	str	An optional heading shown above the picker (omitted when empty).
on_pick	Callable[[str], Any]	Called with the picked document URI on selection.

render()

Lower the document picker into a labelled column.

Returns:

Name	Type	Description
A	Widget	class:~tempestroid.widgets.Column of the optional label and a
	Widget	class:~tempestroid.widgets.FilePicker.

Drawer

Bases: Component

A controlled lateral panel that shows its children when open.

Themed (Trilho H5): when open, the panel surface is resolved from variant / color_scheme / elevation via :func:~tempest_core.variants.resolve_surface_variant, mirroring a card; the width and the open/closed behavior are unchanged. Backward-compatible: Drawer(open=…, children=…) is an elevated neutral panel.

Attributes:

Name	Type	Description
open	bool	Whether the drawer is expanded; when False it collapses to an empty box.
children	list[Widget]	The widgets stacked inside the open drawer.
width	float	The panel width in logical pixels when open.
variant	CardVariant	The surface treatment (elevated / filled / outlined).
color_scheme	str	The Material 3 role family to tint with.
elevation	int | None	An explicit M3 elevation level (0-5) overriding the default.
theme	Theme	The design-system theme whose tokens resolve the panel surface.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; forwarded).

render()

Lower the drawer into a primitive panel or an empty box.

Returns:

Type	Description
Widget	A styled Column panel when open, otherwise an empty Container.

EmailInput

Bases: _BRField

A labelled e-mail field with the e-mail keyboard and a mail icon.

Validate with :func:tempestroid.validators.validate_email.

Attributes:

Name	Type	Description
value	str	The current text value (controlled).
label	str	The label shown above the field (omitted when empty).
placeholder	str	The empty-field hint.
error	str	The validation message; shown in the theme's error color.
on_change	Callable[[str], Any]	Called with the new string value on each edit.

render()

Lower the e-mail input into a labelled column.

Returns:

Type	Description
Widget	A labelled :class:~tempestroid.widgets.Column wrapping an
Widget	e-mail-keyboard :class:~tempestroid.widgets.Input.

EmptyState

Bases: Component

A centered placeholder for empty screens: glyph, title, subtitle, action.

Themed (Trilho H4): the glyph/subtitle read the muted ON_SURFACE_VARIANT role, the title reads ON_SURFACE, and the gaps/padding come from the theme's spacing scale rather than fixed pixels.

Attributes:

Name	Type	Description
title	str	The primary message.
subtitle	str | None	An optional secondary line.
glyph	str	A large text glyph shown above the title (no icon font needed).
action	Widget | None	An optional call-to-action widget (e.g. a Button).
theme	Theme	The design-system theme whose tokens supply colors and spacing.

render()

Lower the empty state into a centered primitive column.

Returns:

Type	Description
Widget	A Column stacking the glyph, title, optional subtitle and action.

Footer

Bases: Component

A bottom bar holding arbitrary, centered content.

Themed (Trilho H5): the footer surface is resolved from variant / color_scheme / elevation via :func:~tempest_core.variants.resolve_surface_variant, mirroring :class:AppBar. Backward-compatible: Footer(children=…) is an elevated neutral bar.

Attributes:

Name	Type	Description
children	list[Widget]	The widgets laid out in the footer (e.g. links or labels).
variant	CardVariant	The surface treatment (elevated / filled / outlined).
color_scheme	str	The Material 3 role family to tint with.
elevation	int | None	An explicit M3 elevation level (0-5) overriding the default.
theme	Theme	The design-system theme whose tokens resolve the bar surface.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; forwarded).

render()

Lower the footer into a centered primitive row.

Returns:

Type	Description
Widget	A Row containing the footer's children, carrying the resolved
Widget	surface style.

Grid

Bases: Component

A fixed-column grid laying children out in equal-width cells.

Attributes:

Name	Type	Description
children	list[Widget]	The cell widgets, filled left-to-right then top-to-bottom.
columns	int	The number of columns per row (clamped to at least 1).
gap	float | str	The spacing between cells, both horizontally and vertically.

render()

Lower the grid into a primitive column of rows.

Returns:

Type	Description
Widget	A Column of Rows; each child is wrapped in a growing
Widget	Container so columns share width, and short final rows are padded
Widget	with empty cells to keep alignment.

Header

Bases: Component

A page header band: a title with an optional subtitle.

Themed (Trilho H5, tokens-only): the band fills with the theme's SURFACE_VARIANT role, the title uses ON_SURFACE and the subtitle uses ON_SURFACE_VARIANT, with spacing/typography read from the theme tokens. An optional color_scheme tints the title with the role color (e.g. a section header). There is no surface variant — a header is a flat band, not an elevated surface. Backward-compatible: Header(title=…) is a neutral band.

Attributes:

Name	Type	Description
title	str	The header's primary line.
subtitle	str | None	An optional secondary line shown muted under the title.
color_scheme	str | None	Optional Material 3 role family tinting the title; None keeps the neutral ON_SURFACE title.
theme	Theme	The design-system theme whose tokens supply colors and spacing.

render()

Lower the header into a stacked primitive column.

Returns:

Type	Description
Widget	A Column with the title and, when set, the subtitle.

HStack

Bases: Component

A horizontal stack: children laid left-to-right with a token-step gap.

A thin, SwiftUI-style ergonomic wrapper over the primitive :class:~tempest_core.widgets.Row. The gap is a token-step name ("md" / "lg") resolved against the theme's spacing scale, or a raw float for backward-compatibility; align (cross-axis) and justify (main-axis) are surfaced directly so the common layout is one call. An explicit style is merged on top of the resolved defaults.

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets, laid left-to-right.
gap	float | str	The spacing between children — a token-step name ("md") or a float in logical pixels.
align	AlignItems | None	The cross-axis (vertical) alignment of the children.
justify	JustifyContent | None	The main-axis (horizontal) distribution of the children.
theme	Theme	The design-system theme whose spacing scale resolves the gap.

render()

Lower the horizontal stack into a primitive Row.

Returns:

Type	Description
Widget	A Row carrying the resolved gap/align/justify, with any explicit
Widget	style merged on top.

ImagePicker

Bases: Component

A labelled image picker with an inline preview of the chosen image.

Attributes:

Name	Type	Description
value	str	The picked image URI ("" until one is chosen).
label	str	An optional heading shown above the picker (omitted when empty).
on_pick	Callable[[str], Any]	Called with the picked image URI on selection.

render()

Lower the image picker into a labelled column.

Returns:

Name	Type	Description
A	Widget	class:~tempestroid.widgets.Column of the optional label, an
	Widget	class:~tempestroid.widgets.Image preview (when a URI is set) and a
	Widget	class:~tempestroid.widgets.FilePicker.

ImagePicture

Bases: Component

A circular profile-photo picker: a round photo over a change affordance.

Distinct from :class:~tempestroid.components.Avatar (which shows initials): this clips a chosen :class:~tempestroid.widgets.Image to a circle, falling back to a user :class:~tempestroid.widgets.Icon placeholder when no photo is set, and offers a :class:~tempestroid.widgets.FilePicker to change it.

Attributes:

Name	Type	Description
src	str	The current photo URI ("" shows the placeholder).
size	float	The circle's diameter in logical pixels.
on_pick	Callable[[str], Any]	Called with the picked photo URI on selection.

render()

Lower the profile-photo picker into a column.

Returns:

Type	Description
Widget	A centered :class:~tempestroid.widgets.Column of the circular photo
Widget	and a "change" :class:~tempestroid.widgets.FilePicker.

LineChart

Bases: _ChartBase

A multi-series line chart drawn over a :class:~tempest_core.widgets.Canvas.

Each :class:ChartSeries becomes a connected polyline (:class:~tempest_core.widgets.MoveTo + a run of :class:~tempest_core.widgets.LineTo + one :class:~tempest_core.widgets.StrokeCmd) over a shared, framed plot rect with y-axis gridlines and right-aligned tick labels. The command list is deterministic for fixed input, so the conformance suite pins it. No new draw command is introduced.

Attributes:

Name	Type	Description
series	list[ChartSeries]	The data series to plot (each its own polyline + color).

render()

Lower the line chart into a Canvas of axis + polyline commands.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.widgets.Canvas carrying the deterministic
	Widget	draw-command list.

ListTile

Bases: Component

A single list row: optional leading/trailing widgets around a title block.

Themed (Trilho H3): the title uses ON_SURFACE, the subtitle uses ON_SURFACE_VARIANT, and the gaps/padding come from the theme's spacing scale rather than fixed pixels. An optional color_scheme tints the title with the role color (e.g. a highlighted/active row).

Attributes:

Name	Type	Description
title	str	The row's primary text.
subtitle	str | None	An optional secondary line shown muted under the title.
leading	Widget | None	An optional widget shown before the text (e.g. an Avatar).
trailing	Widget | None	An optional widget shown after the text (e.g. a Button).
color_scheme	str | None	Optional Material 3 role family tinting the title; None keeps the neutral ON_SURFACE title.
theme	Theme	The design-system theme whose tokens supply colors and spacing.

render()

Lower the list tile into a primitive row.

Returns:

Type	Description
Widget	A Row of the leading widget, the growing title block and the
Widget	trailing widget.

MetricCard

Bases: Component

A dashboard metric inside a themed card: label, value and optional trend.

Composes the H3 :class:~tempest_core.components.Card (the surface) around the H4 :class:~tempest_core.components.Stat (the label/value/delta block), with an optional trailing slot (e.g. a sparkline :class:LineChart or an icon). No new primitive is introduced — it is Card + Stat.

Attributes:

Name	Type	Description
label	str	The metric's caption (muted).
value	str	The metric's value (large, prominent).
delta	str | None	An optional trend line (e.g. "+12%"); None hides it.
delta_up	bool	Whether the delta is positive (success-tinted) or negative (error-tinted).
color_scheme	str	The Material 3 role family the card surface tints with.
variant	CardVariant	The card surface treatment (elevated / filled / outlined).
trailing	Widget | None	An optional widget shown to the right of the stat block.
theme	Theme	The design-system theme whose tokens resolve the surface and stat.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; unused).

render()

Lower the metric card into a themed card wrapping a stat.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.components.Card containing the stat block and,
	Widget	when set, a trailing widget laid out in a centered Row-like column.

NavBar

Bases: Component

A horizontal navigation/tab bar with a highlighted active item.

Themed (Trilho H5): the bar surface is resolved from :func:~tempest_core.variants.resolve_surface_variant; the active item is an accent pill from :func:~tempest_core.variants.resolve_badge_variant (SOLID, color_scheme); inactive items are a low-emphasis GHOST treatment from :func:~tempest_core.variants.resolve_variant (neutral). Backward-compatible: NavBar(items=…, active=…, on_select=…) is a primary-accented bar over a neutral surface.

Attributes:

Name	Type	Description
items	list[str]	The visible item labels, in order.
active	int	The index of the currently selected item.
on_select	Callable[[int], Any]	Called with the tapped item's index when an item is pressed.
color_scheme	str	The Material 3 role family the active pill paints with.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
theme	Theme	The design-system theme whose tokens resolve the bar and items.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

render()

Lower the navigation bar into a primitive row of buttons.

Returns:

Type	Description
Widget	A Row of item buttons with the active one highlighted as an accent
Widget	pill, carrying the resolved surface style.

PasswordInput

Bases: _BRField

A labelled password field (secure, with the built-in eye toggle).

Attributes:

Name	Type	Description
value	str	The current text value (controlled).
label	str	The label shown above the field (omitted when empty).
placeholder	str	The empty-field hint.
error	str	The validation message; shown in the theme's error color.
on_change	Callable[[str], Any]	Called with the new string value on each edit.

render()

Lower the password input into a labelled column.

Returns:

Type	Description
Widget	A labelled :class:~tempestroid.widgets.Column wrapping a secure
Widget	class:~tempestroid.widgets.Input.

PhoneInput

Bases: _BRField

A labelled Brazilian phone field, masked (99) 99999-9999.

Validate with :func:tempestroid.validators.validate_phone.

Attributes:

Name	Type	Description
value	str	The current text value (controlled).
label	str	The label shown above the field (omitted when empty).
placeholder	str	The empty-field hint.
error	str	The validation message; shown in the theme's error color.
on_change	Callable[[str], Any]	Called with the new string value on each edit.

render()

Lower the phone input into a labelled column.

Returns:

Type	Description
Widget	A labelled :class:~tempestroid.widgets.Column wrapping a masked
Widget	class:~tempestroid.widgets.MaskedInput.

ProgressStepper

Bases: Component

A horizontal wizard / progress stepper showing labelled, numbered steps.

Lays out the steps in a row: each step is a small numbered circle (a filled accent disc for done/active steps, a muted outline for pending ones) above its label, joined by connector rules. The colors are theme-driven: done/active steps read the color_scheme role; pending steps read the muted ON_SURFACE_VARIANT role. Named ProgressStepper to avoid colliding with the numeric :class:~tempest_core.components.Stepper (a +/- number spinner).

Attributes:

Name	Type	Description
steps	list[str]	The step labels, in order.
current	int	The index of the active step (steps before it read as done).
color_scheme	str	The Material 3 role family the done/active steps paint with.
theme	Theme	The design-system theme resolving the step colors and spacing.

render()

Lower the stepper into a primitive row of step cells.

Returns:

Type	Description
Widget	A Row of step cells joined by flexible connector spaces.

Note

Each gap between two cells carries a growing connector rule, tinted by whether the step it leads into is already done.

RadioGroup

Bases: Component

A vertical single-choice list with radio markers, theme-driven colors.

Each row's marker/text color is resolved from the H2 selection variant (:func:~tempest_core.variants.resolve_selection_variant) against the theme — the chosen row reads the color_scheme accent, the rest read a muted on-surface tone — so dark mode and brand color work for free. The ◉/○ glyphs are unchanged; only the colors become theme-driven.

Attributes:

Name	Type	Description
options	list[str]	The choice labels, in order.
selected	int	The index of the chosen option.
on_select	Callable[[int], Any]	Called with the tapped option's index.
size	ResponsiveSize	The density size of each row's marker.
color_scheme	str	The Material 3 role family the chosen row's accent paints with.
theme	Theme	The design-system theme resolving the row colors.
media	MediaQueryData | None	Optional viewport snapshot for a responsive size.

render()

Lower the group into a primitive column of radio buttons.

Returns:

Type	Description
Widget	A Column of one button per option, the chosen one marked.

Rating

Bases: Component

A row of stars showing (and optionally setting) a 1-based rating.

Themed (Trilho H4): the star color reads the color_scheme role from the theme rather than a hard-coded accent, so dark mode and brand color apply.

Attributes:

Name	Type	Description
value	int	The number of filled stars.
max_stars	int	The total number of stars shown.
on_rate	Callable[[int], Any] | None	Optional handler called with the tapped star's 1-based value; when None the rating is presentational.
color_scheme	str	The Material 3 role family the filled stars paint with.
theme	Theme	The design-system theme resolving the star color.

render()

Lower the rating into a primitive row of stars.

Returns:

Type	Description
Widget	A Row of star cells.

ResultView

Bases: Component

The image-picker → result flow: pick an image, then show its result.

Stacks an :class:~tempest_core.components.ImagePicker over an optional result slot — the widget the app builds from the model output (e.g. a :class:DetectionOverlay, a :class:MetricCard, a :class:ConfidenceBadge or a chart). The app owns the inference + builds the result; this component only arranges the picker and the result.

Attributes:

Name	Type	Description
value	str	The picked image URI (forwarded to the picker; "" until one is chosen).
label	str	An optional heading shown above the picker.
on_pick	Callable[[str], Any]	Called with the picked image URI on selection.
result	Widget | None	The optional result widget shown below the picker; None shows only the picker.
theme	Theme	The design-system theme whose tokens supply the spacing.

render()

Lower the result view into a column of the picker and the result.

Returns:

Name	Type	Description
A	Widget	class:~tempest_core.widgets.Column of the
	Widget	class:~tempest_core.components.ImagePicker and, when set, the result
	Widget	widget.

Scaffold

Bases: Component

A page frame: app bar on top, growing body, optional bottom bar.

Attributes:

Name	Type	Description
app_bar	Widget | None	The top bar widget (commonly an :class:AppBar); omitted when None.
body	Widget | None	The main content; defaults to an empty column when None.
bottom_bar	Widget | None	A bottom bar widget (e.g. a :class:NavBar or Footer); omitted when None.
scroll	bool	When True, the body is wrapped in a ScrollView (a Qt convenience; the Compose renderer scrolls natively post-Trilho-B).
theme	Theme	The design-system theme whose BACKGROUND role fills the frame.

render()

Lower the scaffold into a stacked primitive column.

Returns:

Type	Description
Widget	A Column stacking the app bar, the (growing) body and the bottom
Widget	bar in order.

SearchBar

Bases: Component

A search field: a controlled text Input with an optional clear button.

Themed (Trilho H5): the inner Input style is resolved from the Chakra-style field_variant / color_scheme / size props via :func:~tempest_core.variants.resolve_field_variant; the outer pill carries a surface treatment from :func:~tempest_core.variants.resolve_surface_variant; and the clear button lowers to an :class:~tempest_core.widgets.IconButton (the curated :data:~tempest_core.icons.Icons.X glyph, GHOST variant). Backward-compatible: SearchBar(value=…, on_change=…) is a filled neutral search pill.

Attributes:

Name	Type	Description
value	str	The current query text (controlled).
placeholder	str	The empty-field hint.
on_change	Callable[[TextChangeEvent], Any]	Called with the validated TextChangeEvent on each edit.
on_clear	Callable[[], Any] | None	Optional handler for the clear button; the button shows only when set and the field is non-empty.
field_variant	FieldVariant	The inner input's field treatment (outline / filled / flushed).
color_scheme	str	The Material 3 role family the focus tint paints with.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
theme	Theme	The design-system theme whose tokens resolve the field and pill.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

render()

Lower the search bar into a primitive row.

Returns:

Type	Description
Widget	A Row of the input and, when applicable, a clear icon button,
Widget	carrying the resolved surface pill style.

SegmentedControl

Bases: Component

A compact single-choice pill group, themed via the H1 variant resolver.

Themed (Trilho H4): the active segment resolves to a Material 3 solid treatment and the inactive ones to ghost via :func:~tempest_core.variants.resolve_variant against the theme — so dark mode and brand color work for free instead of hard-coded hexes.

Attributes:

Name	Type	Description
options	list[str]	The visible segment labels, in order.
selected	int	The index of the active segment.
on_select	Callable[[int], Any]	Called with the tapped segment's index.
color_scheme	str	The Material 3 role family the active segment paints with.
size	ResponsiveSize	The density size of each segment.
theme	Theme	The design-system theme resolving the segments.
media	MediaQueryData | None	Optional viewport snapshot for a responsive size.

render()

Lower the control into a primitive row of segment buttons.

Returns:

Type	Description
Widget	A Row of segment buttons with the active one highlighted.

Sidebar

Bases: Component

A fixed-width lateral column of navigation/content widgets.

Themed (Trilho H5): the panel surface is resolved from variant / color_scheme / elevation via :func:~tempest_core.variants.resolve_surface_variant, mirroring a card; the fixed width and padding are unchanged. Backward-compatible: Sidebar(children=…) is an elevated neutral panel.

Attributes:

Name	Type	Description
children	list[Widget]	The widgets stacked top-to-bottom in the sidebar.
width	float	The sidebar's fixed width in logical pixels.
variant	CardVariant	The surface treatment (elevated / filled / outlined).
color_scheme	str	The Material 3 role family to tint with.
elevation	int | None	An explicit M3 elevation level (0-5) overriding the default.
theme	Theme	The design-system theme whose tokens resolve the panel surface.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; forwarded).

render()

Lower the sidebar into a fixed-width primitive column.

Returns:

Type	Description
Widget	A Column carrying the sidebar's children, with the resolved
Widget	surface style.

Stat

Bases: Component

A labelled metric with a value and an optional trend delta.

A compact dashboard stat: a muted label over a large value, with an optional delta line tinted by the H4 success (up) or error (down) status role depending on delta_up — the canonical "▲ +12%" / "▼ -3%" trend cue.

Attributes:

Name	Type	Description
label	str	The metric's caption (muted).
value	str	The metric's value (large, prominent).
delta	str | None	An optional trend line (e.g. "+12%"); None hides it.
delta_up	bool	Whether the delta is positive (success-tinted) or negative (error-tinted).
theme	Theme	The design-system theme whose tokens supply colors and spacing.

render()

Lower the stat into a primitive column.

Returns:

Type	Description
Widget	A Column of the muted label, the prominent value and an optional
Widget	status-tinted delta.

StatCard

Bases: MetricCard

A compact preset of :class:MetricCard (a filled, tighter card).

Exactly a :class:MetricCard with a denser default surface (filled, smaller padding) — handy for a tight grid of stats. Every MetricCard prop still applies; override variant / padding via style to retune.

Attributes:

Name	Type	Description
variant	CardVariant	Defaults to filled for the compact look (overridable).

Stepper

Bases: Component

A numeric stepper: - decrement, current value, + increment.

Themed: the two buttons resolve from the Chakra-style variant / color_scheme / size props via :func:~tempest_core.variants.resolve_variant, and the value reads the theme's ON_SURFACE role. Before this, both carried the fixed MUTED / ON_SURFACE constants of the dark palette — a stepper on a light surface painted a dark-grey button whatever the app's theme said, and no prop could move it.

Attributes:

Name	Type	Description
value	int	The current value.
step	int	The amount added/removed per tap.
min_value	int | None	The lower bound, or None for unbounded.
max_value	int | None	The upper bound, or None for unbounded.
on_change	Callable[[int], Any]	Called with the new (clamped) value when a button is tapped.
variant	Variant	The visual treatment of the two buttons.
color_scheme	str	The Material 3 role family the buttons paint with.
size	ResponsiveSize	The density size of each button.
theme	Theme	The design-system theme resolving the buttons and the value.
media	MediaQueryData | None	Optional viewport snapshot for a responsive size.

render()

Lower the stepper into a primitive row.

Returns:

Type	Description
Widget	A Row of the decrement button, the value and the increment button.

StyledContainer

Bases: Component

A themed single-child box with token-step padding over the IR Container.

The thin, additive wrapper that gives the primitive :class:~tempest_core.widgets.Container design-system ergonomics — a token-step padding ("md" / "lg" / a raw float) resolved against the theme's spacing scale — without mutating the IR primitive, which stays pure. A bare padding float keeps backward-compatibility; a step name resolves via :meth:~tempest_core.theme.Theme.space. An explicit style is merged on top.

Attributes:

Name	Type	Description
child	Widget | None	The optional wrapped widget.
padding	float | str	The inner padding — a token-step name ("md") or a raw float in logical pixels.
theme	Theme	The design-system theme whose spacing scale resolves a step name.

render()

Lower the styled container into a primitive padded container.

Returns:

Type	Description
Widget	A Container whose style.padding is the resolved token-step (or
Widget	float) padding, with any explicit style merged on top.

Surface

Bases: Component

A themed, un-padded single-child box — the surface primitive cards build on.

Resolves its :class:~tempest_core.style.Style from variant / color_scheme / elevation against the design-system theme via :func:~tempest_core.variants.resolve_surface_variant, then merges the caller's explicit style on top (its set fields win, so hand-styling still works and stays backward-compatible). Unlike :class:~tempest_core.components.Card it adds no inner padding or gap — it is the bare surface, leaving content layout to whatever it wraps. Card is exactly Surface + padding + a Column.

Attributes:

Name	Type	Description
child	Widget | None	The optional wrapped widget.
variant	CardVariant	The surface treatment (elevated / filled / outlined).
color_scheme	str	The Material 3 role family to tint with ("neutral" uses the plain surface roles; a role family uses the tonal container roles).
elevation	int | None	An explicit Material 3 elevation level (0-5) overriding the variant default; None uses the per-variant default.
radius_step	str	The shape-scale step name for the corner radius.
theme	Theme	The design-system theme whose tokens resolve the surface.
media	MediaQueryData | None	Optional viewport snapshot (accepted for parity; unused here).

render()

Lower the surface into a themed single-child container.

Returns:

Type	Description
Widget	A Container carrying the resolved surface style (no inner padding
Widget	of its own beyond the resolver's), wrapping the child.

Note

padding_step="none": a bare surface owns no inner padding, since cards add their own.

Table

Bases: Component

A static data table laid out as rows of equal-width cells.

Attributes:

Name	Type	Description
rows	list[TableRow]	The body rows, each a :class:TableRow of :class:TableCell\s.
headers	list[str]	Optional header labels rendered as an emphasised first row.
style	Style | None	An optional style overlaid on the table's default surface.

render()

Lower the table into a primitive column of rows.

Returns:

Type	Description
Widget	A Column of Rows; each row carries a bottom divider and each
Widget	cell grows to share the row width evenly.

TableCell

Bases: BaseModel

A single cell of a :class:Table.

Attributes:

Name	Type	Description
content	str	The cell's text content.
colspan	int	How many columns the cell spans (currently informational; the primitive lowering renders one cell per entry).
rowspan	int	How many rows the cell spans (currently informational).
style	Style | None	An optional style overlaid on the cell's default padding/text.

TableRow

Bases: BaseModel

A single row of a :class:Table.

Attributes:

Name	Type	Description
cells	list[TableCell]	The ordered cells of the row.
style	Style | None	An optional style overlaid on the row's default layout.

Tabs

Bases: Component

A tab strip whose active tab carries an underline indicator.

Themed (Trilho H5): the strip is a :func:~tempest_core.variants.resolve_surface_variant surface; each tab is a :func:~tempest_core.variants.resolve_variant (GHOST, neutral) text; the active tab takes the color_scheme role color plus a thin underline indicator — a one-pixel-tall bottom :class:~tempest_core.style.SideBorder in the accent role (existing Border / SideBorder fields, no new style field). Mirrors :class:NavBar's lowering and the same zero-argument select handler. Tabs is presentational selection: the active index lives in app state, toggled from on_select.

Attributes:

Name	Type	Description
tabs	list[str]	The visible tab labels, in order.
active	int	The index of the currently selected tab.
on_select	Callable[[int], Any]	Called with the tapped tab's index when a tab is pressed.
color_scheme	str	The Material 3 role family the active tab + underline use.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
theme	Theme	The design-system theme whose tokens resolve the strip and tabs.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

render()

Lower the tab strip into a primitive row of tab buttons.

Returns:

Type	Description
Widget	A Row of GHOST tab buttons with the active one underlined,
Widget	carrying the resolved surface strip style.

Tag

Bases: Chip

A closed, non-selectable label — a thin preset of :class:Chip.

A Tag is exactly a :class:Chip fixed to its presentational, low-emphasis form: never selectable and never tappable (selected and on_click are not exposed), so it always lowers to a static subtle badge Text pill. It carries the same theming props (color_scheme / size / theme) as Chip and reuses :func:~tempest_core.variants.resolve_badge_variant. Use it for read-only category/status labels where a Chip's interactivity is wrong.

VStack

Bases: Component

A vertical stack: children laid top-to-bottom with a token-step gap.

The vertical sibling of :class:HStack over the primitive :class:~tempest_core.widgets.Column. The gap is a token-step name resolved against the theme's spacing scale (or a raw float); align (cross-axis, horizontal) and justify (main-axis, vertical) are surfaced directly. An explicit style is merged on top.

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets, laid top-to-bottom.
gap	float | str	The spacing between children — a token-step name ("md") or a float in logical pixels.
align	AlignItems | None	The cross-axis (horizontal) alignment of the children.
justify	JustifyContent | None	The main-axis (vertical) distribution of the children.
theme	Theme	The design-system theme whose spacing scale resolves the gap.

render()

Lower the vertical stack into a primitive Column.

Returns:

Type	Description
Widget	A Column carrying the resolved gap/align/justify, with any
Widget	explicit style merged on top.

App

Bases: Generic[S]

Owns app state and drives coalesced rebuilds.

The view receives the app itself, so it can read app.state and wire handlers that call :meth:set_state (sync or from inside an async handler). This avoids any circular dependency between the view and the app.

The app also owns a :class:~tempestroid.navigation.NavStack (self.nav), independent of the generic state S. The view reads app.nav.top to decide which screen to build; :meth:push/:meth:pop/:meth:replace/ :meth:reset mutate the stack and schedule the same coalesced rebuild as a state change, so navigation flows through the existing diff with no new patch kind.

The type parameter S is the application state type.

Methods:

Name	Description
start	Build the initial scene and record it as the current tree.
set_state	Mutate state (optionally) and request a coalesced rebuild.
swap_view	Swap the view function and rebuild against live state.
request_rebuild	Schedule a single coalesced rebuild on the event loop.
push / pop / replace / reset	Navigation-stack mutations (each rebuilds).
show_dialog / show_sheet / show_menu / toast	Push an overlay layer entry.
dismiss	Remove an overlay by id and request a rebuild.
set_theme / set_locale	Swap the active theme/locale and rebuild.
slide_window / slide_section_window	Set a virtualized list's visible window.
register_animation / unregister_animation	Manage the frame-clock controllers.

Properties

current_tree: The most recently built scene (None before start). has_animations: Whether any animation controller is active on the clock.

has_animations property

Whether at least one animation controller is active on the frame clock.

The device bridge reads this when serializing a mount/patch so the Compose host knows whether to run its withFrameNanos loop (and emit the reserved __frame__ token). It flips True as soon as a controller is registered (:meth:register_animation) and back to False once the last controller settles and is dropped by :meth:_tick/:meth:_tick_from_device.

Returns:

Type	Description
bool	True when one or more controllers are active, False otherwise.

current_tree property

The most recently built scene (None before :meth:start).

Returns:

Type	Description
Scene | None	The current scene, or None.

__init__(state, view, apply_patches, nav=None, *, time_source=None, theme=None, media=None, locale=None)

Initialize the app.

Parameters:

Name	Type	Description	Default
state	S	The initial application state.	required
view	Callable[[App[S]], Widget]	Builds the widget tree from the app (reads app.state and app.nav.top).	required
apply_patches	Callable[[list[Patch]], None]	Renderer callback that applies a patch list.	required
nav	NavStack | None	The initial navigation stack. Defaults to a fresh :class:~tempestroid.navigation.NavStack with the root route.	None
time_source	Callable[[], float] | None	Optional monotonic clock (seconds) used by the animation frame loop to compute the per-frame dt. Tests inject a deterministic source; the Qt runner passes loop.time. Defaults to the event loop's clock.	None
theme	Theme | None	The initial theme context the view reads. Defaults to a fresh :class:~tempestroid.theme.Theme (SYSTEM mode).	None
media	MediaQueryData | None	The initial media-query context the view reads. Defaults to a fresh :class:~tempestroid.theme.MediaQueryData.	None
locale	Locale | None	The initial locale context the view reads. Defaults to a fresh :class:~tempestroid.i18n.Locale (pt, LTR).	None

start()

Build the initial scene and record it as the current tree.

Returns:

Name	Type	Description
The	Scene	class:Scene (root tree + overlay layer), ready to hand to a
	Scene	renderer's mount.

swap_view(view)

Swap the view function and rebuild against the live state.

This is stateful hot reload: unlike a hot restart (which throws the state away and remounts), it keeps the current state object and diffs the tree built by the new view against the current tree, so on-screen state survives a code edit. The new tree is built eagerly (synchronously) so an incompatible view — e.g. one reading a state attribute the preserved state lacks — raises here and the old view stays installed, letting the caller fall back to a clean restart.

Parameters:

Name	Type	Description	Default
view	Callable[[App[S]], Widget]	The new view function (typically from a reloaded module).	required

Returns:

Type	Description
list[Patch]	The patches applied to reconcile the new tree ([] if unchanged).

Raises:

Type	Description
RuntimeError	If called before :meth:start.
Exception	Whatever the new view/build raises — the swap is rolled back (the old view stays installed) before re-raising.

set_state(mutate=None)

Mutate state (optionally) and request a coalesced rebuild.

Parameters:

Name	Type	Description	Default
mutate	Callable[[S], None] | None	Optional callback that mutates self.state in place.	None

set_theme(theme)

Swap the active theme and request a coalesced rebuild.

The view reads app.theme on the next build, so toggling dark/light (or a palette) flows through the existing diff with no new patch kind.

Parameters:

Name	Type	Description	Default
theme	Theme	The new theme context.	required

set_locale(locale)

Swap the active locale and request a coalesced rebuild.

The view reads app.locale (language for string lookup, locale.rtl for layout direction) on the next build.

Parameters:

Name	Type	Description	Default
locale	Locale	The new locale context.	required

slide_window(key, start, end)

Set the visible window of a virtualized list and request a rebuild.

A renderer (or the device bridge) calls this from a list's scroll handler: the new [start, end) window is recorded by the list's key and injected into the next build, so :class:LazyColumn/:class:LazyRow/ :class:LazyGrid materialize the slid window. Through the keyed diff this becomes a minimal remove/reorder/insert patch sequence.

Parameters:

Name	Type	Description	Default
key	str	The key of the target list widget.	required
start	int	The first visible index (inclusive).	required
end	int	The one-past-last visible index (exclusive).	required

slide_section_window(key, section_title, start, end)

Set the visible window of one section of a :class:SectionList.

Parameters:

Name	Type	Description	Default
key	str	The key of the target :class:SectionList widget.	required
section_title	str	The title of the section to slide.	required
start	int	The first visible index (inclusive) within that section.	required
end	int	The one-past-last visible index (exclusive) within that section.	required

push(route)

Push a route onto the navigation stack and request a rebuild.

Parameters:

Name	Type	Description	Default
route	Route	The destination route to navigate to.	required

pop()

Pop the top route, returning to the previous screen.

At the root (a single route on the stack) this is a no-op: the stack is left untouched so the host can take its default back action (e.g. close the app on Android).

Returns:

Type	Description
bool	True if a route was popped, False if already at the root.

replace(route)

Replace the top route in place (no stack-depth change).

Parameters:

Name	Type	Description	Default
route	Route	The route to put on top, replacing the current screen.	required

reset(stack)

Replace the entire navigation stack and request a rebuild.

Parameters:

Name	Type	Description	Default
stack	list[Route]	The new, non-empty route stack (e.g. for a deep link).	required

Raises:

Type	Description
ValueError	If stack is empty — an app must always have a screen.

show_dialog(widget, *, barrier=True)

Push a modal dialog onto the overlay layer.

Parameters:

Name	Type	Description	Default
widget	Widget	The dialog widget (typically a :class:~tempestroid.Dialog).	required
barrier	bool	Whether a touch-blocking scrim sits behind the dialog.	True

Returns:

Type	Description
str	The stable overlay id, for a later :meth:dismiss.

show_sheet(widget, *, barrier=True)

Push a bottom sheet onto the overlay layer.

Parameters:

Name	Type	Description	Default
widget	Widget	The sheet widget (typically a :class:~tempestroid.BottomSheet).	required
barrier	bool	Whether a touch-blocking scrim sits behind the sheet.	True

Returns:

Type	Description
str	The stable overlay id, for a later :meth:dismiss.

show_menu(widget, *, anchor=None, barrier=False)

Push a menu or popover onto the overlay layer.

Parameters:

Name	Type	Description	Default
widget	Widget	The menu widget (typically a :class:~tempestroid.Menu or :class:~tempestroid.Popover). When it exposes an anchor field and anchor is given, the anchor is applied to the widget so the renderer can position the menu.	required
anchor	str | None	Optional key of the widget to anchor the menu to.	None
barrier	bool	Whether a touch-blocking scrim sits behind the menu (menus are usually anchored and barrier-free).	False

Returns:

Type	Description
str	The stable overlay id, for a later :meth:dismiss.

toast(widget, *, duration_s=2.5)

Push a transient toast that auto-dismisses after duration_s.

The auto-dismiss is scheduled on the event loop via call_later; the app remains authoritative over the toast's lifetime even if a renderer also runs its own visual timer.

Parameters:

Name	Type	Description	Default
widget	Widget	The toast widget (typically a :class:~tempestroid.Toast).	required
duration_s	float	How long the toast stays visible, in seconds.	2.5

Returns:

Type	Description
str	The stable overlay id (also dismissable early via :meth:dismiss).

dismiss(overlay_id)

Remove an overlay by id and request a rebuild.

A no-op when the id is unknown (e.g. a toast already auto-dismissed, or a double dismiss), so renderer-driven and timer-driven dismissals are safe to race.

Parameters:

Name	Type	Description	Default
overlay_id	str	The id returned by a show_*/toast call.	required

register_animation(ctrl)

Register an active animation controller on the frame clock.

Binds the controller to this app (so it can later unregister itself) and starts the frame clock if it was idle. Registering an already-tracked controller is a no-op beyond (re)binding, so repeated :meth:~tempestroid.animation.AnimationController.forward calls are safe.

Parameters:

Name	Type	Description	Default
ctrl	AnimationController	The controller to drive on each frame.	required

unregister_animation(ctrl)

Remove a controller from the frame clock.

A no-op when the controller is not tracked (e.g. a double :meth:~tempestroid.animation.AnimationController.stop). The clock stops re-arming once the set drains.

Parameters:

Name	Type	Description	Default
ctrl	AnimationController	The controller to remove.	required

request_rebuild()

Schedule a single rebuild on the event loop.

Repeated calls before the loop next runs are coalesced into one rebuild.

Insert

Bases: _IRModel

Insert node as a new child at index under path.

Attributes:

Name	Type	Description
path	Path	Address of the parent node.
index	int	Position among the parent's children for the new node.
node	Node	The subtree to insert.

Node

Bases: _IRModel

A normalized, renderer-agnostic UI node.

Attributes:

Name	Type	Description
type	str	The widget type tag (e.g. "Text", "Column").
key	str | None	Optional stable identity used to match nodes across rebuilds.
props	dict[str, Any]	Renderable properties (style, text, label, handlers, ...), excluding children. Values are compared by equality during diffing.
children	list[Node]	Ordered child nodes.

OverlayEntry dataclass

One slot in the app's floating overlay layer.

Attributes:

Name	Type	Description
id	str	Stable overlay id (a UUID), used as the overlay node's key.
widget	Widget	The overlay's widget tree.
barrier	bool	Whether a touch-blocking scrim sits behind the overlay.
is_toast	bool	Whether this overlay auto-dismisses on a timer (a toast).

Remove

Bases: _IRModel

Remove the child at index under path.

Attributes:

Name	Type	Description
path	Path	Address of the parent node.
index	int	Position of the child to remove.

Reorder

Bases: _IRModel

Reorder the children under path according to order.

Attributes:

Name	Type	Description
path	Path	Address of the parent node.
order	list[int]	A permutation where order[i] is the old index of the child that must end up at new index i. The renderer rebuilds the child list as [old_children[order[i]] for i in ...].

Replace

Bases: _IRModel

Replace the whole subtree at path with node.

Emitted when the node type or key changes — the old subtree cannot be updated in place, so the renderer rebuilds it from scratch.

Attributes:

Name	Type	Description
path	Path	Address of the node to replace.
node	Node	The new subtree.

Scene

Bases: _IRModel

A full UI document: the root tree plus a z-ordered overlay layer.

A scene is the unit the runtime builds and diffs once overlays exist. The root is the ordinary screen tree; overlays is the floating layer (dialogs, sheets, toasts, menus) rendered above it in ascending z-order. Each overlay node carries its stable overlay id as its key so the keyed diff can match overlays across rebuilds. An empty overlays list reduces a scene to its root tree, so the no-overlay path is unchanged.

Attributes:

Name	Type	Description
root	Node	The root screen node.
overlays	list[Node]	The floating overlay nodes, in ascending z-order. Each node's key is its stable overlay id.

Update

Bases: _IRModel

Update the props of the node at path in place.

Attributes:

Name	Type	Description
path	Path	Address of the node to update.
set_props	dict[str, Any]	Props to add or overwrite.
unset_props	list[str]	Prop names to remove (reset to the renderer default).

Device

Bases: Enum

A named Android device screen preset, sized in logical dp.

Each member's value is its unique label; the viewport lives in the width / height attributes (and .size). Sizes are physical_px / density — what Compose lays out against — sourced from each vendor's published spec / the standard device-metrics tables. The enum value is the label, not the size, because many phones share the same viewport and equal enum values would silently collapse into aliases.

Attributes:

Name	Type	Description
width	int	Logical viewport width in density-independent pixels (dp).
height	int	Logical viewport height in density-independent pixels (dp).
label	str	Human-readable device name (the member's value).

size property

The viewport as a (width, height) tuple.

Returns:

Type	Description
int	The (width, height) pair in dp, ready for
int	host.resize(*device.size).

__new__(width, height, label)

Build a member keyed by its unique label.

Parameters:

Name	Type	Description	Default
width	int	Logical viewport width in dp.	required
height	int	Logical viewport height in dp.	required
label	str	Human-readable device name (also the member's value).	required

Returns:

Type	Description
Device	The constructed enum member.

Locale

Bases: BaseModel

An immutable locale: language, optional region, and layout direction.

Attributes:

Name	Type	Description
language	str	The BCP-47 language tag (e.g. "pt", "en", "ar").
region	str | None	The optional region/country subtag (e.g. "BR", "US").
rtl	bool	Whether the locale lays out right-to-left (e.g. Arabic, Hebrew).

Properties

tag: The locale as a BCP-47 tag (language or language-REGION).

tag property

Render the locale as a BCP-47 tag (language or language-REGION).

Returns:

Type	Description
str	The composed tag, e.g. "pt-BR" or "pt".

Icons

Bases: StrEnum

The names of the curated built-in icons.

A :class:~enum.StrEnum so each member doubles as its kebab-case string — Icons.EYE == "eye" — giving editor autocomplete while still being a plain str anywhere a name is accepted (e.g. Icon(name=Icons.SEARCH) or Input(leading_icon=Icons.MAIL)).

Attributes:

Name	Type	Description
EYE		An open eye; toggle to reveal hidden content (e.g. a password).
EYE_OFF		An eye with a slash; toggle to hide content (e.g. a password).
LOCK		A closed padlock, denoting secured or locked state.
UNLOCK		An open padlock, denoting unsecured or unlocked state.
SEARCH		A magnifying glass, for search inputs and actions.
X		A close cross, for dismissing dialogs, chips, or clearing input.
CHECK		A checkmark, indicating success, confirmation, or selection.
CHEVRON_DOWN		A downward chevron, for expanding or opening dropdowns.
CHEVRON_UP		An upward chevron, for collapsing or closing dropdowns.
CHEVRON_LEFT		A left-pointing chevron, for back or previous navigation.
CHEVRON_RIGHT		A right-pointing chevron, for forward or next navigation.
ARROW_LEFT		A left arrow, for back navigation or moving content left.
ARROW_RIGHT		A right arrow, for forward navigation or moving content right.
PLUS		A plus sign, for add, create, or increment actions.
MINUS		A minus sign, for remove or decrement actions.
USER		A person silhouette, for accounts, profiles, or authors.
MAIL		An envelope, for email addresses, messages, or contact actions.
PHONE		A telephone handset, for phone numbers or call actions.
CALENDAR		A calendar grid, for dates, schedules, or date pickers.
CLOCK		A clock face, for times, durations, or recent activity.
TRASH		A trash can, for delete or discard actions.
MENU		A three-line "hamburger", for opening a navigation menu.
HOME		A house, for the home screen or landing page.
SETTINGS		A gear, for settings, preferences, or configuration.
STAR		A five-point star, for favorites, ratings, or bookmarks.
HEART		A heart, for likes, favorites, or wishlist actions.
BELL		A bell, for notifications or alerts.
INFO		An "i" in a circle, for informational hints or details.

NavStack

Bases: BaseModel

The ordered stack of routes, from root to the visible screen.

Unlike :class:Route, the stack is mutable: :class:~tempestroid.App pushes, pops, replaces and resets it in place and schedules a rebuild. The bottom of the stack is the root route; the top is the screen currently shown.

Attributes:

Name	Type	Description
stack	list[Route]	The route stack. Defaults to a single root route "/" so an app always has a screen to render.

Properties

top: The route on top of the stack (the visible screen). can_pop: Whether the stack can be popped without emptying it.

top property

The route on top of the stack (the visible screen).

Returns:

Type	Description
Route	The top-most route.

can_pop property

Whether the stack can be popped without emptying it.

Returns:

Type	Description
bool	True when more than one route is on the stack (a back navigation
bool	is possible), False at the root.

Route

Bases: BaseModel

A single navigation destination.

A route is an immutable value (frozen, like :class:~tempestroid.style.Style and :class:~tempestroid.widgets.Event) so the navigation stack can be compared and diffed by value.

Attributes:

Name	Type	Description
name	str	The route name (a path-like identifier, e.g. "/" or "/details").
params	dict[str, Any]	Typed parameters passed to the destination screen.

AlertVariant

Bases: StrEnum

The visual variant of an alert / banner (Chakra-style variant).

Picks the treatment a block-level status surface (alert, banner) renders with, mapped to a Material 3 treatment by the H4 alert resolver (:func:~tempest_core.variants.resolve_alert_variant). The color_scheme then chooses which status family the alert tints with. An alert is non-interactive (no state layer), like a surface.

Attributes:

Name	Type	Description
SUBTLE		A low-emphasis tonal fill — the *_container role as the background with its on_*_container content (WCAG-AA safe, the default alert).
SOLID		A filled treatment — the role color as the background with its legible on_* content (a high-emphasis alert).
LEFT_ACCENT		A subtle tonal fill with a thick directional border on the leading (start) edge in the saturated role color.
TOP_ACCENT		A subtle tonal fill with a thick directional border on the top edge in the saturated role color.

AlignItems

Bases: StrEnum

Alignment of children along the cross axis (align-items).

Positions children on the axis perpendicular to :class:FlexDirection's main axis. Also used per-child via :attr:Style.align_self to override the container's choice.

Attributes:

Name	Type	Description
START		Align children to the start edge of the cross axis (top in a row, left in a column).
END		Align children to the end edge of the cross axis (bottom in a row, right in a column).
CENTER		Center each child on the cross axis.
STRETCH		Grow children to fill the container's cross-axis extent when they have no fixed cross-axis size.

BadgeVariant

Bases: StrEnum

The visual variant of a badge / tag / chip (Chakra-style variant).

Picks the treatment a small inline status pill (badge, tag, chip) renders with, mapped to a Material 3 treatment by the H4 badge resolver (:func:~tempest_core.variants.resolve_badge_variant). The color_scheme then chooses which color family the badge tints with. Distinct from :class:Variant (the button treatment): a badge is a compact, pill-shaped label, not a tappable action surface.

Attributes:

Name	Type	Description
SOLID		A filled treatment — the role color as the background with its legible on_* content (a high-emphasis status pill).
SUBTLE		A low-emphasis tonal fill — the *_container role as the background with its on_*_container content (WCAG-AA safe, the default subtle badge).
OUTLINE		A transparent background with the role color as both the content and a same-color border (the lowest-emphasis badge).

Border

Bases: BaseModel

A uniform border (border-width + border-color).

Applies the same width and color to all four sides. Use it in :attr:Style.border; reach for :class:SideBorder when sides differ. Frozen so the reconciler can diff it by value.

Attributes:

Name	Type	Description
width	float	Border thickness in logical pixels (0.0 draws no border).
color	Color | None	The border color, or None to defer to the renderer's default border color.

CardVariant

Bases: StrEnum

The visual variant of a surface/card (Chakra-style variant).

Picks the treatment a non-interactive surface (card, panel, container) renders with, mapped to a Material 3 surface appearance by the H3 surface resolver (:func:~tempest_core.variants.resolve_surface_variant). Distinct from :class:Variant (the button treatment) and :class:FieldVariant (the text-field treatment): a surface is non-interactive, so it has no state layer — it simply chooses how the box is filled and whether it casts an elevation shadow or carries an outline. The color_scheme then chooses which color family the surface tints with ("neutral" uses the plain surface roles; a role family uses the tonal *_container roles).

Attributes:

Name	Type	Description
ELEVATED		A surface background that casts a Material 3 elevation shadow and carries no border — the default raised card.
FILLED		A low-emphasis surface_variant tonal fill with no shadow and no border (the M3 filled card).
OUTLINED		A surface background with a hairline outline border and no shadow (the M3 outlined card).

Color

Bases: BaseModel

An RGBA color.

Construct it directly, from a hex string via :meth:from_hex, or by passing a hex string anywhere a Color is expected (a before validator coerces str into a Color).

Attributes:

Name	Type	Description
r	int	Red channel, 0-255.
g	int	Green channel, 0-255.
b	int	Blue channel, 0-255.
a	float	Alpha channel, 0.0 (transparent) to 1.0 (opaque).

Methods:

Name	Description
from_hex	Build a color from a hex string (classmethod).
rgba	Build a color from explicit channel values (classmethod).
to_hex	Render the color as #RRGGBB (or #RRGGBBAA when translucent).
to_rgba_string	Render the color as a CSS-style rgba(...) string.
with_alpha	Return a copy with a replaced alpha channel.
blend	Linearly interpolate toward another color by a factor.
overlay	Composite a translucent color on top of this one (M3 state layers).

from_hex(value) classmethod

Build a color from a hex string.

Parameters:

Name	Type	Description	Default
value	str	A #RGB, #RRGGBB or #RRGGBBAA string.	required

Returns:

Type	Description
Color	The parsed color.

Raises:

Type	Description
ValueError	If the string is not a valid hex color.

rgba(r, g, b, a=1.0) classmethod

Build a color from explicit channel values.

Parameters:

Name	Type	Description	Default
r	int	Red channel, 0-255.	required
g	int	Green channel, 0-255.	required
b	int	Blue channel, 0-255.	required
a	float	Alpha channel, 0.0-1.0.	1.0

Returns:

Type	Description
Color	The constructed color.

to_hex()

Render the color as #RRGGBB (or #RRGGBBAA when translucent).

Returns:

Type	Description
str	The hex representation.

to_rgba_string()

Render the color as a CSS-style rgba(...) string.

Returns:

Type	Description
str	The rgba(r, g, b, a) representation.

with_alpha(alpha)

Return a copy of this color with a replaced alpha channel.

Parameters:

Name	Type	Description	Default
alpha	float	The new alpha, 0.0 (transparent) to 1.0 (opaque). Clamped into range.	required

Returns:

Type	Description
Color	A new color with the same RGB channels and the given alpha.

blend(other, t)

Linearly interpolate from this color toward other by t.

Interpolates every channel — RGB and alpha — by the factor t: at t=0.0 the result equals self, at t=1.0 it equals other, and intermediate values mix the two proportionally. t is clamped into [0.0, 1.0].

Parameters:

Name	Type	Description	Default
other	Color	The color to interpolate toward.	required
t	float	The interpolation factor, 0.0 (this color) to 1.0 (other).	required

Returns:

Type	Description
Color	The interpolated color.

overlay(on, opacity)

Alpha-composite this color over on at a given opacity.

Computes the source-over compositing of self (taken at opacity) on top of the opaque on color — the operation a Material 3 state layer uses: a hover layer is the content color overlaid on the background at ~8% opacity, pressed at ~12%, etc. The result is opaque (the backdrop on is treated as fully opaque).

Parameters:

Name	Type	Description	Default
on	Color	The backdrop color the state layer sits on (treated as opaque).	required
opacity	float	The state-layer opacity, 0.0 (no change) to 1.0 (fully self). Clamped into range.	required

Returns:

Type	Description
Color	The composited, opaque color.

ComponentState

Bases: StrEnum

The interaction state a component is resolved for (M3 state layers).

The H1 variant resolver (:func:~tempest_core.variants.resolve_variant) layers a Material 3 state layer over the base style for the non-default states: HOVER and PRESSED overlay the content color at the M3 state opacities, FOCUS adds a focus indicator, and DISABLED drops content to the M3 disabled opacity. The renderers apply the per-state styles in response to real pointer/focus events.

Attributes:

Name	Type	Description
DEFAULT		The resting state, with no state layer applied.
HOVER		The pointer-hover state (M3 hover state layer, ~8% overlay).
PRESSED		The pressed/active state (M3 pressed state layer, ~12% overlay).
DISABLED		The disabled state (M3 disabled content/container opacities).
FOCUS		The keyboard/accessibility focus state (focus indicator + the M3 focus state layer).

Corners

Bases: BaseModel

Per-corner border radii in logical pixels (border-*-radius).

Use it in :attr:Style.radius instead of a single float when corners differ (e.g. a sheet rounded only on top).

Curve

Bases: StrEnum

Easing curve for an animated transition (CSS transition-timing-function).

Mirrors the common CSS/Flutter easing presets; the leaf renderer maps each onto its native curve (Compose Easing; Qt QEasingCurve). The core's own :func:~tempestroid.animation._apply_curve also approximates each so the simulator/test clock can interpolate without a renderer.

Attributes:

Name	Type	Description
LINEAR		Constant speed from start to end, with no acceleration.
EASE_IN		Start slow and accelerate toward the end.
EASE_OUT		Start fast and decelerate toward the end.
EASE_IN_OUT		Accelerate at the start and decelerate at the end (symmetric ease).
EASE		The CSS default — a gentle ease that starts quickly then slows, biased differently from EASE_IN_OUT.
BOUNCE		Overshoot and settle with a bouncing motion near the end, like an object dropping onto a surface.
ELASTIC		Overshoot and oscillate around the target before settling, like a spring.

Edge

Bases: BaseModel

Per-side spacing in logical pixels (used for padding and margin).

Attributes:

Name	Type	Description
top	float	Spacing on the top side.
right	float	Spacing on the right side.
bottom	float	Spacing on the bottom side.
left	float	Spacing on the left side.

Methods:

Name	Description
all	Build an edge with the same spacing on every side (classmethod).
symmetric	Build an edge with mirrored vertical/horizontal spacing (classmethod).

all(value) classmethod

Build an edge with the same spacing on every side.

Parameters:

Name	Type	Description	Default
value	float	Spacing applied to all four sides.	required

Returns:

Type	Description
Edge	The constructed edge.

symmetric(*, vertical=0.0, horizontal=0.0) classmethod

Build an edge with mirrored vertical and horizontal spacing.

Parameters:

Name	Type	Description	Default
vertical	float	Spacing for the top and bottom sides.	0.0
horizontal	float	Spacing for the left and right sides.	0.0

Returns:

Type	Description
Edge	The constructed edge.

FieldVariant

Bases: StrEnum

The visual variant of a text-input field (Chakra-style field_variant).

Picks the treatment a value-bearing field (text input, select, masked input, autocomplete, …) renders with, mapped to a Material 3 text-field appearance by the H2 field resolver (:func:~tempest_core.variants.resolve_field_variant). Distinct from :class:Variant (which is the button treatment) because fields have their own affordances: a field is never "solid" or "link", and the color_scheme only tints the focus/caret/label, never the resting fill.

Attributes:

Name	Type	Description
OUTLINE		A transparent fill with a full same-color outline border and a small radius — the M3 outlined text field (the default).
FILLED		A low-emphasis tonal fill (surface_variant) with no resting border and a small radius — the M3 filled text field.
FLUSHED		A transparent fill with only a bottom border and no radius — a minimal, underline-only field (Chakra flushed).

FlexDirection

Bases: StrEnum

Main-axis direction of a flex container (flex-direction).

Picks which axis is the main axis along which children are laid out; the perpendicular axis becomes the cross axis used by :class:AlignItems.

Attributes:

Name	Type	Description
ROW		Lay children out horizontally, left to right; the main axis is horizontal and the cross axis vertical.
COLUMN		Lay children out vertically, top to bottom; the main axis is vertical and the cross axis horizontal.

FlexWrap

Bases: StrEnum

Whether a flex container wraps its children onto new lines (flex-wrap).

NOWRAP keeps every child on a single line (the flex default), while WRAP lets children flow onto subsequent lines once the current one fills and WRAP_REVERSE does the same with the cross-axis order reversed. Only flow-capable containers (a :class:~tempestroid.widgets.Wrap) react to it; the Compose translator lowers it into the spec, while the Qt translator realizes wrapping imperatively in its flow-layout widget (see the conformance suite).

Attributes:

Name	Type	Description
NOWRAP		Keep every child on a single main-axis line, shrinking or overflowing rather than wrapping (the flex default).
WRAP		Allow children to flow onto additional lines once the current line is full, stacking lines in the cross-axis direction.
WRAP_REVERSE		Wrap like :attr:WRAP, but stack the new lines in the reverse cross-axis order (new lines appear before earlier ones).

FontStyle

Bases: StrEnum

Font slant (font-style).

Attributes:

Name	Type	Description
NORMAL		Upright glyphs with no slant (roman).
ITALIC		Slanted glyphs, using the font's italic/oblique variant.

FontWeight

Bases: IntEnum

Common font weights, matching the CSS numeric scale.

Each member is the CSS/OpenType numeric weight; higher values render thicker glyph strokes.

Attributes:

Name	Type	Description
THIN		Weight 100 — the thinnest strokes (hairline).
LIGHT		Weight 300 — lighter than the regular text weight.
NORMAL		Weight 400 — the default body-text weight (regular).
MEDIUM		Weight 500 — slightly heavier than regular.
SEMIBOLD		Weight 600 — between medium and bold.
BOLD		Weight 700 — the standard bold weight for emphasis.
BLACK		Weight 900 — the heaviest strokes (extra bold).

Gradient

Bases: BaseModel

A linear color gradient usable wherever a background color is.

Attributes:

Name	Type	Description
stops	list[GradientStop]	The ordered color stops (at least two for a visible gradient).
direction	GradientDirection	The direction the colors progress in.

GradientDirection

Bases: StrEnum

Direction of a linear gradient's color progression.

Names the axis and orientation along which the gradient's stops are interpolated, from the first stop to the last.

Attributes:

Name	Type	Description
TOP_BOTTOM		Progress vertically downward — first stop at the top, last at the bottom.
BOTTOM_TOP		Progress vertically upward — first stop at the bottom, last at the top.
LEFT_RIGHT		Progress horizontally rightward — first stop on the left, last on the right.
RIGHT_LEFT		Progress horizontally leftward — first stop on the right, last on the left.

GradientStop

Bases: BaseModel

One color stop of a :class:Gradient.

Attributes:

Name	Type	Description
color	Color	The stop's color.
position	float	The stop's position along the gradient, 0.0-1.0.

JustifyContent

Bases: StrEnum

Distribution of children along the main axis (justify-content).

Controls how any free space on the main axis is allocated before, between and after the children.

Attributes:

Name	Type	Description
START		Pack children at the start of the main axis; free space sits after the last child.
END		Pack children at the end of the main axis; free space sits before the first child.
CENTER		Pack children together and center them on the main axis; equal free space at both ends.
SPACE_BETWEEN		Spread children apart with equal space between them and none at the edges; the first and last touch the edges.
SPACE_AROUND		Give each child equal space on both sides, so edge gaps are half the size of the gaps between children.
SPACE_EVENLY		Distribute children with equal space everywhere, including the two edges (all gaps identical).

Position

Bases: StrEnum

Stacking-flow positioning of a child inside a Stack (position).

STATIC (the default) lets the child participate in the stack's normal overlap flow, aligned by the stack's :attr:Style.stack_align. ABSOLUTE pulls the child out of that flow and anchors it by its insets (:attr:Style.top/:attr:Style.right/:attr:Style.bottom/:attr:Style.left), modelled on Flutter's Positioned / CSS position: absolute.

Attributes:

Name	Type	Description
STATIC		The default — the child stays in the stack's normal overlap flow and is aligned by :attr:Style.stack_align.
ABSOLUTE		Remove the child from the flow and anchor it by its insets (:attr:Style.top/:attr:Style.right/:attr:Style.bottom/ :attr:Style.left), overlaid on top of the stack.

Shadow

Bases: BaseModel

A drop shadow (box-shadow) / Material elevation.

Compose maps it to elevation; Qt approximates it with a QGraphicsDropShadowEffect. Frozen so the reconciler can diff it by value.

Attributes:

Name	Type	Description
color	Color | None	The shadow color (renderer default when None).
blur	float	The blur radius in logical pixels.
offset_x	float	Horizontal offset in logical pixels.
offset_y	float	Vertical offset in logical pixels.

SideBorder

Bases: BaseModel

A per-side border (border-top/border-right/…).

Each side is an independent :class:Border, or None to leave that side unset. Use it in :attr:Style.border instead of a uniform :class:Border when sides differ (e.g. only a bottom divider).

Size

Bases: StrEnum

The density size of a styled component (Chakra-style size).

Picks the padding/typography density the H1 variant resolver (:func:~tempest_core.variants.resolve_variant) applies. The hit target is always kept at or above the Material 3 minimum (48dp) regardless of size — a smaller size reduces visual density (padding, font) but never the accessible touch area.

Attributes:

Name	Type	Description
XS		The most compact density.
SM		A compact density.
MD		The default, comfortable density.
LG		A spacious, high-emphasis density.

StackAlign

Bases: StrEnum

Two-axis alignment of a Stack's non-positioned children.

Mirrors Compose Alignment / Flutter AlignmentDirectional constants: a vertical band (top/center/bottom) crossed with a horizontal band (start/center/end). Used only by Stack containers; ordinary flex containers keep using single-axis :class:JustifyContent/:class:AlignItems.

Each member pairs a vertical band (top/center/bottom) with a horizontal band (start/center/end), where start is the leading edge (left in left-to-right layouts) and end the trailing edge.

Attributes:

Name	Type	Description
TOP_START		Pin children to the top edge and the leading side.
TOP_CENTER		Pin children to the top edge, centered horizontally.
TOP_END		Pin children to the top edge and the trailing side.
CENTER_START		Center children vertically, on the leading side.
CENTER		Center children on both axes.
CENTER_END		Center children vertically, on the trailing side.
BOTTOM_START		Pin children to the bottom edge and the leading side.
BOTTOM_CENTER		Pin children to the bottom edge, centered horizontally.
BOTTOM_END		Pin children to the bottom edge and the trailing side.

Style

Bases: BaseModel

An inline, typed style object.

Every field is optional: None means "unset", letting the leaf renderer fall back to its own default. Styles are frozen; combine them with :meth:merge to layer overrides without mutation.

Methods:

Name	Description
merge	Layer another style on top of this one (returns a new Style).

merge(other)

Layer another style on top of this one.

Fields explicitly set on other (i.e. not None) win; everything else is inherited from self.

Parameters:

Name	Type	Description	Default
other	Style	The overriding style.	required

Returns:

Type	Description
Style	A new, merged style.

TextAlign

Bases: StrEnum

Horizontal text alignment (text-align).

Attributes:

Name	Type	Description
LEFT		Align each line to the left edge of the text box.
CENTER		Center each line within the text box.
RIGHT		Align each line to the right edge of the text box.
JUSTIFY		Stretch inter-word spacing so each line (except the last) fills the full width, flush on both edges.

TextDecoration

Bases: StrEnum

Text line decoration (text-decoration).

Attributes:

Name	Type	Description
NONE		No decorative line on the text.
UNDERLINE		Draw a line beneath the text.
LINE_THROUGH		Draw a line through the middle of the text (strikethrough).

TextOverflow

Bases: StrEnum

How clipped text terminates (text-overflow / Compose TextOverflow).

Applies when text exceeds its allotted space (e.g. past :attr:Style.max_lines).

Attributes:

Name	Type	Description
CLIP		Cut the overflowing text off sharply at the box edge, with no marker.
ELLIPSIS		Truncate the text and append an ellipsis (…) to signal that content was cut.

Transition

Bases: BaseModel

An implicit animation applied when a style's properties change.

Modelled on CSS transition / Flutter's implicitly-animated widgets: when a node is rebuilt with a different Style, the renderer tweens the changed visual properties over duration_ms using curve rather than snapping. Frozen so the reconciler can diff it by value.

Attributes:

Name	Type	Description
duration_ms	int	Animation duration in milliseconds (must be positive).
curve	Curve	The easing curve to apply.
delay_ms	int	Delay before the animation starts, in milliseconds.

Variant

Bases: StrEnum

The visual variant of a styled component (Chakra-style variant).

Picks the emphasis/treatment a component renders with, mapped to a Material 3 container/outline/text treatment by the H1 variant resolver (:func:~tempest_core.variants.resolve_variant). The color_scheme then chooses which color family the treatment paints with.

Attributes:

Name	Type	Description
SOLID		A filled treatment — the role color as the background with its legible on_* content (M3 filled button).
OUTLINE		A transparent background with the role color as both the content and a same-color border (M3 outlined button).
GHOST		A transparent background with the role color as the content and no border — the lowest-emphasis tappable treatment (M3 text button without underline).
LINK		A transparent, inline text treatment — the role color as the content with an underline, no padding-heavy hit area styling beyond the enforced touch target.

MediaQueryData

Bases: BaseModel

An immutable snapshot of the viewport / environment context.

Read by the view to build responsively (e.g. switch a column to a row above a width breakpoint, scale text by the user's accessibility setting). The renderer keeps it current via App._update_media on resize / config change; it is never serialized as tree data — it is context, not a node.

Attributes:

Name	Type	Description
width	float	The viewport width in logical pixels.
height	float	The viewport height in logical pixels.
device_pixel_ratio	float	The display density (physical / logical pixels).
text_scale_factor	float	The user's font-scale accessibility multiplier.
platform_dark_mode	bool	Whether the OS is currently in dark mode.
orientation	str	"portrait" or "landscape".

Theme

Bases: BaseModel

An immutable theme: the active mode plus a small color palette.

The palette mirrors a subset of Material's color roles. Every legacy color is optional: None lets the renderer fall back to its own default scheme. The view reads :attr:mode (resolving SYSTEM against the media query) to decide which colors to apply to the tree it builds.

Beyond the legacy flat colors, a theme carries a full Material 3 :class:~tempest_core.tokens.TokenSet (color schemes + spacing/shape/ typography/elevation/motion scales). A researcher seeds a brand color with :meth:from_seed to get a complete M3 palette, then components (or the view) read tokens via :meth:color/:meth:space/:meth:radius/… or resolve a :class:~tempest_core.tokens.TokenRef carried in a Style via :meth:resolve_ref. The legacy flat colors remain so existing apps keep working unchanged — tokens are additive.

Attributes:

Name	Type	Description
mode	ThemeMode	The active color-scheme mode.
tokens	TokenSet	The Material 3 token set (color schemes + scales). Defaults to the baseline M3 token set.
primary	Color | None	The legacy primary brand color (optional override).
secondary	Color | None	The legacy secondary brand color (optional override).
background	Color | None	The legacy screen background color (optional override).
surface	Color | None	The legacy raised-surface color (optional override).
on_primary	Color | None	The legacy color of content drawn on primary.
on_background	Color | None	The legacy color of content drawn on background.
error	Color | None	The legacy error color (optional override).

Methods:

Name	Description
from_seed	Build a theme from a brand seed color (classmethod).
is_dark	Resolve whether the theme renders dark, given the platform setting (resolves SYSTEM against the media query).
scheme	Resolve the active :class:~tempest_core.tokens.ColorScheme.
color	Resolve a color role to a concrete color.
space	Resolve a spacing step to its pixel value.
radius	Resolve a radius step to its pixel value.
typography	Resolve a typography role to its token.
elevation	Resolve an elevation level to its dp value.
resolve_ref	Resolve a :class:~tempest_core.tokens.TokenRef to a concrete value.

from_seed(seed, *, mode=ThemeMode.SYSTEM, secondary_seed=None, tertiary_seed=None, error_seed=None, success_seed=None, warning_seed=None, info_seed=None) classmethod

Build a theme whose tokens are derived from a brand seed color.

This is the researcher-facing entry point: seed a single brand color and get a complete Material 3 token set (light + dark schemes + the default scales). Override the secondary/tertiary/error key colors to hand-pick brand accents, or the H4 success/warning/info status seeds to retune the semantic status colors.

Parameters:

Name	Type	Description	Default
seed	Color	The primary brand/key color.	required
mode	ThemeMode	The initial color-scheme mode.	SYSTEM
secondary_seed	Color | None	Override key color for the secondary palette.	None
tertiary_seed	Color | None	Override key color for the tertiary palette.	None
error_seed	Color | None	Override key color for the error palette.	None
success_seed	Color | None	Override key color for the success status palette (H4).	None
warning_seed	Color | None	Override key color for the warning status palette (H4).	None
info_seed	Color | None	Override key color for the info status palette (H4).	None

Returns:

Type	Description
Theme	A theme carrying the seeded token set.

is_dark(*, platform_dark_mode=False)

Resolve whether the theme renders dark, given the platform setting.

LIGHT / DARK are absolute; SYSTEM defers to the platform.

Parameters:

Name	Type	Description	Default
platform_dark_mode	bool	The OS dark-mode flag (typically :attr:MediaQueryData.platform_dark_mode).	False

Returns:

Type	Description
bool	True when the resolved scheme is dark.

scheme(*, platform_dark_mode=False)

Resolve the active color scheme for the current mode.

Parameters:

Name	Type	Description	Default
platform_dark_mode	bool	The OS dark-mode flag, used to resolve SYSTEM mode.	False

Returns:

Type	Description
ColorScheme	The light or dark color scheme matching the resolved mode.

color(role, *, platform_dark_mode=False)

Resolve a Material 3 color role to a concrete color.

Parameters:

Name	Type	Description	Default
role	ColorRole | str	The color role (a :class:~tempest_core.tokens.ColorRole or its string value).	required
platform_dark_mode	bool	The OS dark-mode flag, used to resolve SYSTEM mode.	False

Returns:

Type	Description
Color	The concrete color for that role in the active scheme.

space(name)

Resolve a named spacing step to its pixel value.

Parameters:

Name	Type	Description	Default
name	str	The spacing step name ("md", …).	required

Returns:

Type	Description
float	The spacing in logical pixels.

radius(name)

Resolve a named radius step to its pixel value.

Parameters:

Name	Type	Description	Default
name	str	The radius step name ("lg", …).	required

Returns:

Type	Description
float	The radius in logical pixels.

typography(name)

Resolve a typography role to its token.

Parameters:

Name	Type	Description	Default
name	str	The type role name ("body_medium", …).	required

Returns:

Type	Description
TypographyToken	The typography token for that role.

elevation(level)

Resolve an elevation level to its dp value.

Parameters:

Name	Type	Description	Default
level	int	The elevation level, 0-5.	required

Returns:

Type	Description
float	The elevation in dp.

resolve_ref(ref, *, platform_dark_mode=False)

Resolve a token reference to its concrete value.

This is the seam that lets a Style field carry a :class:~tempest_core.tokens.TokenRef instead of a raw value: the renderer (or the variant resolver in H1) calls this to turn the reference into the concrete color/spacing/radius/type/elevation/motion value before the diff.

Parameters:

Name	Type	Description	Default
ref	TokenRef	The token reference to resolve.	required
platform_dark_mode	bool	The OS dark-mode flag, used to resolve a color reference against the active scheme.	False

Returns:

Type	Description
Color | float | TypographyToken | Curve | int	The concrete value: a :class:~tempest_core.style.Color for
Color | float | TypographyToken | Curve | int	"color"; a float for "space"/"radius"/
Color | float | TypographyToken | Curve | int	"elevation"; a :class:~tempest_core.tokens.TypographyToken for
Color | float | TypographyToken | Curve | int	"type"; a :class:~tempest_core.style.Curve or int for
Color | float | TypographyToken | Curve | int	"motion" (easing curve vs. duration in ms).

Raises:

Type	Description
ValueError	If ref.category is not a known token category.
KeyError	If ref.name is not a defined token in its category.

resolve_style(refs, *, base=None, platform_dark_mode=False)

Build a concrete Style by resolving token references per field.

This is the Style ⟷ token seam: a component (or the H1 variant resolver) maps style fields to token references — e.g. {"background": TokenRef.color("primary"), "radius": TokenRef.radius("lg")} — and the theme resolves them against its tokens, producing a plain frozen Style the renderers consume unchanged. A "type" reference expands into the matching font_size/line_height/font_weight/letter_spacing fields. Raw Style values keep working — this is purely an additive way to source values from the theme.

Parameters:

Name	Type	Description	Default
refs	dict[str, TokenRef]	Mapping of Style field name to the token reference that supplies its value.	required
base	Style | None	An optional base style the resolved fields are layered on top of (via :meth:Style.merge); None starts from an empty style.	None
platform_dark_mode	bool	The OS dark-mode flag, used to resolve color references against the active scheme.	False

Returns:

Type	Description
Style	A concrete, frozen Style with every referenced field resolved.

Raises:

Type	Description
ValueError	If a reference category is unknown.
KeyError	If a referenced token name is not defined.

ThemeMode

Bases: StrEnum

The active color-scheme mode of the application.

SYSTEM defers to the platform's current setting (read from :attr:MediaQueryData.platform_dark_mode); LIGHT / DARK force the respective scheme regardless of the OS.

Attributes:

Name	Type	Description
LIGHT		Force the light color scheme always, ignoring the OS setting.
DARK		Force the dark color scheme always, ignoring the OS setting.
SYSTEM		Follow the platform's current scheme, resolving against :attr:MediaQueryData.platform_dark_mode at build time.

Breakpoints

Bases: BaseModel

Responsive width breakpoints in logical pixels (Chakra-style).

Used by H1's responsive token resolution against the E9 :class:~tempest_core.theme.MediaQueryData (e.g. size={"base": "sm", "md": "lg"}). Frozen so it diffs by value.

Attributes:

Name	Type	Description
sm	float	The small breakpoint (compact phones).
md	float	The medium breakpoint (large phones / small tablets).
lg	float	The large breakpoint (tablets).
xl	float	The extra-large breakpoint (desktop).

ColorRole

Bases: StrEnum

The Material 3 color roles a :class:ColorScheme exposes.

These are the semantic slots components paint against — never raw tones. Each on_* role is the legible foreground for its base role and is generated to meet WCAG-AA contrast against it.

Attributes:

Name	Type	Description
PRIMARY		The highest-emphasis brand color (key actions, active state).
ON_PRIMARY		Legible content drawn on top of PRIMARY.
PRIMARY_CONTAINER		A tonal, lower-emphasis fill derived from primary.
ON_PRIMARY_CONTAINER		Content drawn on PRIMARY_CONTAINER.
SECONDARY		A complementary, lower-emphasis accent.
ON_SECONDARY		Content drawn on SECONDARY.
SECONDARY_CONTAINER		A tonal fill derived from secondary.
ON_SECONDARY_CONTAINER		Content drawn on SECONDARY_CONTAINER.
TERTIARY		A contrasting accent used to balance primary/secondary.
ON_TERTIARY		Content drawn on TERTIARY.
TERTIARY_CONTAINER		A tonal fill derived from tertiary.
ON_TERTIARY_CONTAINER		Content drawn on TERTIARY_CONTAINER.
ERROR		The role signalling errors and destructive actions.
ON_ERROR		Content drawn on ERROR.
ERROR_CONTAINER		A tonal error fill.
ON_ERROR_CONTAINER		Content drawn on ERROR_CONTAINER.
SUCCESS		The role signalling success / positive confirmation (H4).
ON_SUCCESS		Content drawn on SUCCESS.
SUCCESS_CONTAINER		A tonal success fill.
ON_SUCCESS_CONTAINER		Content drawn on SUCCESS_CONTAINER.
WARNING		The role signalling caution / a non-blocking problem (H4).
ON_WARNING		Content drawn on WARNING.
WARNING_CONTAINER		A tonal warning fill.
ON_WARNING_CONTAINER		Content drawn on WARNING_CONTAINER.
INFO		The role signalling neutral information (H4).
ON_INFO		Content drawn on INFO.
INFO_CONTAINER		A tonal info fill.
ON_INFO_CONTAINER		Content drawn on INFO_CONTAINER.
BACKGROUND		The screen background.
ON_BACKGROUND		Content drawn on BACKGROUND.
SURFACE		The base surface of cards, sheets and menus.
ON_SURFACE		Content drawn on SURFACE.
SURFACE_VARIANT		A subtly differentiated surface for dividers/fills.
ON_SURFACE_VARIANT		Lower-emphasis content on a surface.
OUTLINE		The color of borders and dividers.
OUTLINE_VARIANT		A lower-emphasis outline.
INVERSE_SURFACE		A surface inverted relative to the scheme (snackbars).
INVERSE_ON_SURFACE		Content drawn on INVERSE_SURFACE.
INVERSE_PRIMARY		The primary color as it appears on an inverse surface.

ColorScheme

Bases: BaseModel

A resolved Material 3 color scheme — every role as a concrete color.

One scheme is the full set of M3 roles for a single mode (light or dark). Built from tonal palettes via :func:color_schemes_from_seed, or supplied directly to fully hand-author a brand scheme. Frozen so it diffs by value.

Attributes:

Name	Type	Description
primary	Color	The PRIMARY role color.
on_primary	Color	The ON_PRIMARY role color.
primary_container	Color	The PRIMARY_CONTAINER role color.
on_primary_container	Color	The ON_PRIMARY_CONTAINER role color.
secondary	Color	The SECONDARY role color.
on_secondary	Color	The ON_SECONDARY role color.
secondary_container	Color	The SECONDARY_CONTAINER role color.
on_secondary_container	Color	The ON_SECONDARY_CONTAINER role color.
tertiary	Color	The TERTIARY role color.
on_tertiary	Color	The ON_TERTIARY role color.
tertiary_container	Color	The TERTIARY_CONTAINER role color.
on_tertiary_container	Color	The ON_TERTIARY_CONTAINER role color.
error	Color	The ERROR role color.
on_error	Color	The ON_ERROR role color.
error_container	Color	The ERROR_CONTAINER role color.
on_error_container	Color	The ON_ERROR_CONTAINER role color.
success	Color | None	The SUCCESS role color (H4 status family).
on_success	Color | None	The ON_SUCCESS role color.
success_container	Color | None	The SUCCESS_CONTAINER role color.
on_success_container	Color | None	The ON_SUCCESS_CONTAINER role color.
warning	Color | None	The WARNING role color (H4 status family).
on_warning	Color | None	The ON_WARNING role color.
warning_container	Color | None	The WARNING_CONTAINER role color.
on_warning_container	Color | None	The ON_WARNING_CONTAINER role color.
info	Color | None	The INFO role color (H4 status family).
on_info	Color | None	The ON_INFO role color.
info_container	Color | None	The INFO_CONTAINER role color.
on_info_container	Color | None	The ON_INFO_CONTAINER role color.
background	Color	The BACKGROUND role color.
on_background	Color	The ON_BACKGROUND role color.
surface	Color	The SURFACE role color.
on_surface	Color	The ON_SURFACE role color.
surface_variant	Color	The SURFACE_VARIANT role color.
on_surface_variant	Color	The ON_SURFACE_VARIANT role color.
outline	Color	The OUTLINE role color.
outline_variant	Color	The OUTLINE_VARIANT role color.
inverse_surface	Color	The INVERSE_SURFACE role color.
inverse_on_surface	Color	The INVERSE_ON_SURFACE role color.
inverse_primary	Color	The INVERSE_PRIMARY role color.

Methods:

Name	Description
role	Read the color for a :class:ColorRole.

role(role)

Read the color for a given Material 3 color role.

Parameters:

Name	Type	Description	Default
role	ColorRole	The semantic role to resolve.	required

Returns:

Type	Description
Color	The concrete color for that role in this scheme.

ColorSchemes

Bases: BaseModel

The light and dark :class:ColorScheme pair of a theme.

Attributes:

Name	Type	Description
light	ColorScheme	The color scheme used when the theme renders light.
dark	ColorScheme	The color scheme used when the theme renders dark.

Methods:

Name	Description
for_mode	Pick the scheme for a resolved dark/light flag.

for_mode(*, is_dark)

Pick the scheme matching a resolved dark/light flag.

Parameters:

Name	Type	Description	Default
is_dark	bool	True to select the dark scheme, False for light.	required

Returns:

Type	Description
ColorScheme	The matching color scheme.

ElevationScale

Bases: BaseModel

The Material 3 elevation scale (levels 0-5 → dp).

Maps the six M3 elevation levels to their dp values; renderers turn the dp into a tonal-surface tint (Compose) or a drop shadow (Qt). Frozen so it diffs by value.

Attributes:

Name	Type	Description
level0	float	0 dp — flush with the background.
level1	float	1 dp.
level2	float	3 dp.
level3	float	6 dp.
level4	float	8 dp.
level5	float	12 dp.

Methods:

Name	Description
get	Resolve an elevation level (0-5) to its dp value.

get(level)

Resolve an elevation level to its dp value.

Parameters:

Name	Type	Description	Default
level	int	The elevation level, 0-5.	required

Returns:

Type	Description
float	The elevation in dp.

Raises:

Type	Description
KeyError	If level is outside 0-5.

MotionScale

Bases: BaseModel

The Material 3 motion scale (standard durations + easing curves).

Durations are in milliseconds (M3's short/medium/long buckets); easing reuses the framework's :class:~tempest_core.style.Curve. Frozen so it diffs by value.

Attributes:

Name	Type	Description
duration_short	int	A short transition (150 ms) — small UI changes.
duration_medium	int	A medium transition (300 ms) — the default.
duration_long	int	A long transition (500 ms) — large/expressive motion.
easing_standard	Curve	The default easing for most transitions.
easing_emphasized	Curve	A more expressive easing for prominent motion.

ShapeScale

Bases: BaseModel

The Material 3 shape (corner-radius) scale in logical pixels.

full uses the framework's pill sentinel (999) so the renderer clamps it to a fully-rounded shape. Frozen so it diffs by value.

Attributes:

Name	Type	Description
none	float	0 dp — square corners.
xs	float	4 dp.
sm	float	8 dp.
md	float	12 dp (the M3 default for cards/buttons).
lg	float	16 dp.
xl	float	28 dp (large containers, sheets).
full	float	999 dp — the pill/circle sentinel.

Methods:

Name	Description
get	Resolve a named radius step to its pixel value.

get(name)

Resolve a named radius step to its pixel value.

Parameters:

Name	Type	Description	Default
name	str	The step name ("none", "xs", …, "full").	required

Returns:

Type	Description
float	The radius in logical pixels.

Raises:

Type	Description
KeyError	If name is not a defined radius step.

SpacingScale

Bases: BaseModel

The 4dp-grid spacing scale (named steps → logical pixels).

Named t-shirt steps mapping to a 4dp grid, matching Chakra's spacing ergonomics over Material's raw dp. Components ask for space("md") rather than a literal 16.0. Frozen so it diffs by value.

Attributes:

Name	Type	Description
none	float	0 dp.
xs	float	4 dp (one grid unit).
sm	float	8 dp.
md	float	16 dp (the default content gutter).
lg	float	24 dp.
xl	float	32 dp.
xxl	float	48 dp.

Methods:

Name	Description
get	Resolve a named step to its pixel value.

get(name)

Resolve a named spacing step to its pixel value.

Parameters:

Name	Type	Description	Default
name	str	The step name ("none", "xs", …, "xxl").	required

Returns:

Type	Description
float	The spacing in logical pixels.

Raises:

Type	Description
KeyError	If name is not a defined spacing step.

TokenRef

Bases: BaseModel

A reference to a design token, resolved by the theme at build time.

This is the seam that lets a :class:~tempest_core.style.Style field carry a token reference instead of a raw value: a component (or app) writes Style(background=TokenRef.color("primary")) and the theme resolves it to a concrete value before the diff. Raw values keep working unchanged — a TokenRef is purely an additional, opt-in source.

The reference names a category and a token name; the theme's :meth:~tempest_core.theme.Theme.resolve_ref reads the right scale. Frozen so it diffs by value and can sit inside a frozen Style.

Attributes:

Name	Type	Description
category	str	Which token scale to read — "color", "space", "radius", "type", "elevation" or "motion".
name	str	The token name within the category (e.g. "primary", "md", "body_medium", "level2", "duration_short").

Methods:

Name	Description
color	Build a color-role reference (classmethod).
space	Build a spacing-step reference (classmethod).
radius	Build a radius-step reference (classmethod).
type_	Build a typography-role reference (classmethod).
elevation	Build an elevation-level reference (classmethod).
motion	Build a motion-token reference (classmethod).

color(role) classmethod

Build a reference to a color role.

Parameters:

Name	Type	Description	Default
role	ColorRole | str	The color role (a :class:ColorRole or its string value).	required

Returns:

Type	Description
TokenRef	The token reference.

space(name) classmethod

Build a reference to a spacing step.

Parameters:

Name	Type	Description	Default
name	str	The spacing step name ("md", …).	required

Returns:

Type	Description
TokenRef	The token reference.

radius(name) classmethod

Build a reference to a radius step.

Parameters:

Name	Type	Description	Default
name	str	The radius step name ("lg", …).	required

Returns:

Type	Description
TokenRef	The token reference.

type_(name) classmethod

Build a reference to a typography role.

Parameters:

Name	Type	Description	Default
name	str	The type role name ("body_medium", …).	required

Returns:

Type	Description
TokenRef	The token reference.

elevation(level) classmethod

Build a reference to an elevation level.

Parameters:

Name	Type	Description	Default
level	int	The elevation level, 0-5.	required

Returns:

Type	Description
TokenRef	The token reference.

motion(name) classmethod

Build a reference to a motion token.

Parameters:

Name	Type	Description	Default
name	str	The motion token name ("duration_short", "easing_standard", …).	required

Returns:

Type	Description
TokenRef	The token reference.

TokenSet

Bases: BaseModel

The full set of design tokens a theme resolves against.

Bundles the color schemes with every systematic scale (spacing, shape, typography, elevation, motion, breakpoints). Build one from a seed via :meth:from_seed, or hand-author any scale. Frozen so the runtime can hold it as an immutable snapshot and swap it wholesale.

Attributes:

Name	Type	Description
schemes	ColorSchemes	The light/dark color schemes.
spacing	SpacingScale	The 4dp spacing scale.
shape	ShapeScale	The corner-radius scale.
typography	TypographyScale	The type scale.
elevation	ElevationScale	The elevation scale.
motion	MotionScale	The motion (duration/easing) scale.
breakpoints	Breakpoints	The responsive width breakpoints.

Methods:

Name	Description
from_seed	Build a token set from a brand seed color (classmethod).
scheme	Resolve the color scheme for a dark/light flag.

from_seed(seed, *, secondary_seed=None, tertiary_seed=None, error_seed=None, success_seed=None, warning_seed=None, info_seed=None) classmethod

Build a token set from a brand seed color with M3 default scales.

Parameters:

Name	Type	Description	Default
seed	Color	The primary brand/key color.	required
secondary_seed	Color | None	Override key color for the secondary palette.	None
tertiary_seed	Color | None	Override key color for the tertiary palette.	None
error_seed	Color | None	Override key color for the error palette.	None
success_seed	Color | None	Override key color for the success status palette (H4).	None
warning_seed	Color | None	Override key color for the warning status palette (H4).	None
info_seed	Color | None	Override key color for the info status palette (H4).	None

Returns:

Type	Description
TokenSet	A token set with schemes derived from the seed and default M3
TokenSet	spacing/shape/typography/elevation/motion scales.

scheme(*, is_dark)

Resolve the color scheme for a dark/light flag.

Parameters:

Name	Type	Description	Default
is_dark	bool	True for the dark scheme, False for light.	required

Returns:

Type	Description
ColorScheme	The matching color scheme.

TonalPalette

Bases: BaseModel

A Material 3 tonal palette: one hue sampled at the standard tones.

Generated from a single key color via :func:tonal_palette_from_seed; the color schemes read specific tones from it (light primary = tone 40, dark primary = tone 80, etc.). Frozen so it diffs by value.

Attributes:

Name	Type	Description
tones	dict[int, Color]	Mapping of each standard M3 tone (0-100) to its color.

Methods:

Name	Description
tone	Read the color at a given tone (nearest standard tone).

tone(value)

Read the palette color at a tone, snapping to the nearest standard tone.

Parameters:

Name	Type	Description	Default
value	int	The desired tone, 0-100.	required

Returns:

Type	Description
Color	The color at the nearest available standard tone.

TypographyScale

Bases: BaseModel

The Material 3 type scale (display/headline/title/body/label × sizes).

Each role is a :class:TypographyToken carrying size, line-height and weight, matching the M3 baseline values. Frozen so it diffs by value.

Attributes:

Name	Type	Description
display_large	TypographyToken	Largest display role (57/64).
display_medium	TypographyToken	Medium display role (45/52).
display_small	TypographyToken	Small display role (36/44).
headline_large	TypographyToken	Large headline (32/40).
headline_medium	TypographyToken	Medium headline (28/36).
headline_small	TypographyToken	Small headline (24/32).
title_large	TypographyToken	Large title (22/28).
title_medium	TypographyToken	Medium title (16/24, medium weight).
title_small	TypographyToken	Small title (14/20, medium weight).
body_large	TypographyToken	Large body (16/24).
body_medium	TypographyToken	Medium body (14/20).
body_small	TypographyToken	Small body (12/16).
label_large	TypographyToken	Large label (14/20, medium weight).
label_medium	TypographyToken	Medium label (12/16, medium weight).
label_small	TypographyToken	Small label (11/16, medium weight).

Methods:

Name	Description
get	Resolve a named type role to its :class:TypographyToken.

get(name)

Resolve a named type role to its token.

Parameters:

Name	Type	Description	Default
name	str	The role name ("body_medium", "title_large", …).	required

Returns:

Type	Description
TypographyToken	The typography token for that role.

Raises:

Type	Description
KeyError	If name is not a defined type role.

TypographyToken

Bases: BaseModel

One role of the Material 3 type scale (size + line-height + weight).

Attributes:

Name	Type	Description
font_size	float	The font size in logical pixels.
line_height	float	The line height in logical pixels.
font_weight	FontWeight	The font weight.
letter_spacing	float	The tracking in logical pixels (M3 uses small values).

ActionSheet

Bases: Widget

A bottom-anchored list of actions, optionally titled.

It is presented modally — with a scrim behind it — so it needs the same dismissal contract as a :class:Dialog or a :class:BottomSheet: a renderer reports the scrim tap or the Escape key, and the app decides whether to close. Without :attr:on_dismiss that gesture had nowhere to go, so a sheet whose actions did not close it trapped the reader — worse once a renderer traps focus inside modal overlays, as the web client now does.

Attributes:

Name	Type	Description
title	str | None	Optional sheet title.
items	list[MenuItem]	The selectable actions.
on_select	MenuSelectHandler | None	Handler invoked on action selection, validated against :class:MenuSelectEvent.
on_dismiss	DismissHandler | None	Handler invoked when the user dismisses the sheet (barrier tap or system back), validated against :class:DismissEvent.

Animated

Bases: Widget

A wrapper whose child is rebuilt with interpolated style each frame.

The interpolation happens in the core: the view reads the value of its :attr:controller (driven by the app frame clock), interpolates a :class:~tempestroid.animation.Tween with it, and folds the result into the child :class:~tempestroid.style.Style. So the renderer receives a child that is already at this frame target — it just mounts it normally. The :attr:controller, :attr:style_begin and :attr:style_end fields are kept on the node for introspection/device parity; they are not consumed by the Qt renderer's mount path (a documented Qt-vs-Compose divergence).

Attributes:

Name	Type	Description
child	Widget	The wrapped widget (mounted with its per-frame interpolated style).
controller	Any	The :class:~tempestroid.animation.AnimationController driving the interpolation (typed Any to avoid an import cycle through the core animation module).
style_begin	Any	The style at value == 0.0 (or None to use the child's own style as the start).
style_end	Any	The style at value == 1.0 (or None).

child_nodes()

Return the single wrapped child.

Returns:

Type	Description
list[Widget]	A one-element list holding the child.

AnimatedList

Bases: Widget

A flex container that animates items as they enter and leave.

Lays its children along :attr:direction like a Column/Row, but on a structural change (an Insert/Remove patch) the affected child is animated in/out rather than appearing/disappearing instantly. The Qt renderer realizes this with a QPropertyAnimation on the child's opacity and maximum height; the device renderer wraps each child in AnimatedVisibility (a documented divergence).

Attributes:

Name	Type	Description
direction	FlexDirection	The main-axis direction (column or row).
children	list[Widget]	The ordered child widgets.
enter_duration_ms	int	Enter-animation duration in milliseconds.
exit_duration_ms	int	Exit-animation duration in milliseconds.
enter_curve	Curve	The easing curve applied to the enter animation.
exit_curve	Curve	The easing curve applied to the exit animation.

child_nodes()

Return the list's children in order.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

AppState

Bases: StrEnum

The lifecycle state of the application process.

Attributes:

Name	Type	Description
FOREGROUND		The app is visible and receiving user input — it is the active task in front of the user and may run UI work freely.
BACKGROUND		The app is no longer visible (the user switched away or the screen is off); it should pause UI work and release scarce resources, as the OS may suspend or reclaim it.
INACTIVE		The app is in a transitional, partially-obscured state where it is visible but not receiving input — e.g. during an incoming call, the app switcher, a system permission prompt, or a split-screen transition.

ArcTo

Bases: BaseModel

Add an elliptical arc within the bounding box (x, y, width, height).

Attributes:

Name	Type	Description
kind	Literal['arc_to']	The command discriminator ("arc_to").
x	float	Bounding box left, in logical pixels.
y	float	Bounding box top, in logical pixels.
width	float	Bounding box width, in logical pixels.
height	float	Bounding box height, in logical pixels.
start_angle	float	Start angle, in degrees.
sweep_angle	float	Sweep angle, in degrees.

AspectRatio

Bases: Widget

A single-child box that constrains its child to a fixed width/height ratio.

The ratio is width / height: a value of 1.0 is square, 16/9 is widescreen. The renderer derives the missing dimension from whichever one is bounded by the parent. This is the explicit-widget counterpart to :attr:~tempestroid.style.Style.aspect_ratio — use the widget when fixing the ratio is the box's only purpose; the two coexist. The Compose renderer lowers it to Modifier.aspectRatio and the Qt renderer derives the fixed dimension imperatively.

Attributes:

Name	Type	Description
ratio	float	The width / height ratio to enforce (must be positive).
child	Widget | None	The optional wrapped widget.

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

Autocomplete

Bases: _FieldWidget

A text field that suggests and selects from a list of options (H2 field API).

Emits a :class:TextChangeEvent as the user types and a :class:SelectEvent when a suggestion is chosen. Both handlers serialize as distinct tokens on the node (the multi-handler pattern shared with LazyColumn).

Attributes:

Name	Type	Description
options	list[str]	The candidate suggestions, filtered against the typed text.
value	str	The current text value.
placeholder	str	The hint shown when the field is empty.
leading_icon	Icons | str | None	An optional icon name shown inside the field on the start (leading) edge — a curated :class:~tempestroid.icons.Icons value (or its string) or an arbitrary platform icon name.
trailing_icon	Icons | str | None	An optional icon name shown inside the field on the end (trailing) edge, resolved like :attr:leading_icon.
field_variant	FieldVariant	The field treatment (outline/filled/flushed).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	TextChangeHandler | None	Handler invoked with a :class:TextChangeEvent on each edit.
on_select	SelectHandler | None	Handler invoked with a :class:SelectEvent when a suggestion is selected.

BackdropFilter

Bases: Widget

A wrapper that blurs the layers behind its child (semantic alias of Blur).

Attributes:

Name	Type	Description
radius	float	The blur radius, in logical pixels.
child	Widget | None	The optional wrapped widget.

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

Blur

Bases: Widget

A wrapper that blurs its child.

Attributes:

Name	Type	Description
radius	float	The blur radius, in logical pixels.
child	Widget | None	The optional wrapped widget.

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

BottomSheet

Bases: Widget

A sheet that slides up from the bottom edge of the screen.

Attributes:

Name	Type	Description
children	list[Widget]	The sheet body widgets.
on_dismiss	DismissHandler | None	Handler invoked when the user dismisses the sheet (barrier tap or swipe-down), validated against :class:DismissEvent.

child_nodes()

Return the sheet's body widgets.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

Button

Bases: Widget

A tappable button, styled via the Chakra-ergonomics variant API.

The button resolves its base :class:~tempest_core.style.Style from its variant / size / color_scheme against the design-system theme (Material 3 tokens), via :func:~tempest_core.variants.resolve_variant. An explicit style is merged on top of the resolved base (its set fields win), so hand-styling still works and stays backward-compatible: Button(label=...) with no variant produces a solid/primary/md button, and Button(label=..., style=…) layers the override over it. The resolved style is baked into :attr:~tempest_core.widgets.base.Widget.style so the renderers consume a plain Style unchanged.

The per-state styles (default/hover/pressed/disabled/focus) are exposed via :meth:state_styles so a renderer can apply the matching Material 3 state layer on real pointer/focus events — the resolution stays pure and in the engine; only the event→state mapping lives in the renderers.

The accessibility surface (semantics / focusable / focus_order) is preserved unchanged from :class:~tempest_core.widgets.base.Widget.

Attributes:

Name	Type	Description
label	str	The text shown on the button.
on_click	EventHandler | None	Optional handler invoked on tap. May be sync or async; the runtime schedules awaitables on the event loop.
variant	Variant	The visual treatment (solid/outline/ghost/link).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map ({"base": Size.SM, "md": Size.LG}).
color_scheme	str	The Material 3 role family to paint with ("primary", "secondary", "tertiary", "error" or "neutral").
theme	Theme	The design-system theme whose tokens resolve the variant; defaults to the baseline Material 3 theme.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

Methods:

Name	Description
state_styles	Resolve the per-interaction-state style table for the renderers (default/hover/pressed/disabled/focus).

state_styles()

Resolve the per-interaction-state style table for the renderers.

Returns the resolved :class:~tempest_core.style.Style for every :class:~tempest_core.style.ComponentState (default/hover/pressed/ disabled/focus), each with any explicit style override merged on top — the same merge applied to the baked default style. A renderer applies the matching style on the corresponding pointer/focus event.

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of each ComponentState to its resolved, override-merged
dict[ComponentState, Style]	Style.

CameraFrameEvent

Bases: Event

One decoded RGB frame from a live camera preview.

Emitted by CameraPreview (when on_frame is wired) at most every frame_interval_ms, so an app can run on-device inference on the live feed. The frame crosses the boundary as base64 of the raw width × height × 3 row-major RGB bytes; rotation is the clockwise degrees the sensor reports (apply it before display). Rebuild the array with tempestroid.vision.frame_array(event).

Attributes:

Name	Type	Description
width	int	Frame width in pixels.
height	int	Frame height in pixels.
data	str	Base64 of the raw H × W × 3 uint8 RGB buffer.
rotation	int	Clockwise rotation the sensor reports, in degrees (0/90/180/270).

CameraPreview

Bases: Widget

A live camera preview surface, optionally streaming frames to the app.

Wire on_frame to run on-device inference on the live feed: the device attaches a CameraX ImageAnalysis stage (keeping only the latest frame) and invokes the handler with a :class:CameraFrameEvent at most every frame_interval_ms — throttled because inference is far slower than the camera's frame rate. With no on_frame it is a plain preview.

Attributes:

Name	Type	Description
facing	str	Which camera to use ("front" or "back").
on_frame	EventHandler | None	Handler invoked with a :class:CameraFrameEvent per (throttled) frame; rebuild the array with tempestroid.vision.frame_array.
frame_interval_ms	int	Minimum gap between emitted frames, in milliseconds (ignored when on_frame is unset).

Canvas

Bases: Widget

A retained-mode drawing surface interpreting a list of draw commands.

The command list is the IR: a serializable, value-diffable sequence of :data:DrawCommand that both leaf renderers replay (Qt via QPainter in a paintEvent; Compose via drawIntoCanvas). The reconciler diffs the list by value, so changing a command emits a single Update carrying the new list.

Attributes:

Name	Type	Description
commands	list[DrawCommand]	The ordered draw commands to replay each paint.
width	float | None	Optional fixed canvas width, in logical pixels.
height	float | None	Optional fixed canvas height, in logical pixels.

Checkbox

Bases: _SelectionWidget

A labelled boolean checkbox, styled via the H2 selection-variant API.

Resolves its accent/ring :class:~tempest_core.style.Style from its size / color_scheme against the theme (passing checked); an explicit style is merged on top.

Attributes:

Name	Type	Description
label	str	The text shown beside the control.
checked	bool	Whether the box is currently checked.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the accent paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	ToggleHandler | None	Handler invoked with a :class:ToggleEvent on toggle.

ClipPath

Bases: Widget

A wrapper that clips its child to a predefined shape.

Attributes:

Name	Type	Description
shape	ClipShape	The clipping shape.
radius	float	The corner radius for ROUNDED_RECT, in logical pixels.
child	Widget | None	The optional wrapped widget.

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

ClipShape

Bases: StrEnum

The predefined shapes a :class:ClipPath can clip its child to.

Attributes:

Name	Type	Description
CIRCLE		Clip the child to a circle inscribed in its box — anything outside the largest centered circle that fits the box is hidden. Useful for circular avatars; on a non-square box the circle uses the shorter side as its diameter.
ROUNDED_RECT		Clip the child to a rectangle with rounded corners, using :attr:ClipPath.radius as the corner radius. With a radius of 0 this is effectively a plain rectangle (no clipping effect).
OVAL		Clip the child to an ellipse that fills the box's full width and height — it stretches to the box bounds rather than staying circular, so a non-square box yields a non-circular oval.

Close

Bases: BaseModel

Close the active subpath back to its start point.

Attributes:

Name	Type	Description
kind	Literal['close']	The command discriminator ("close").

Column

Bases: Widget

A vertical flex container (main axis = top-to-bottom).

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets.

child_nodes()

Return the column's children.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

Component

Bases: Widget

A composite widget that lowers to a primitive widget tree.

A component is not part of the serialized IR. The reconciler expands it via :meth:render into primitive widgets (Text / Row / Column / Container / inputs / …) before diffing, so neither leaf renderer (Qt or Compose) ever sees a component — only the tree it produces. This keeps higher-level, reusable building blocks (app bars, scaffolds, navigation bars) fully renderer-agnostic and device-ready: they work anywhere a primitive works, with zero renderer changes.

Subclasses declare their inputs as Pydantic fields and implement :meth:render; they may read self.style / self.key and fold them into the returned tree. render runs on the same thread as build (desktop and device), so it may close over plain Python callables (e.g. a navigation item's on_select) and wire them into the primitives it emits.

Every key a component emits is namespaced under :attr:base_key — its own root through :attr:base_key, each inner node through :meth:child_key. A fixed child key (key="seg-0") collides the moment a screen holds two instances of the same component, and since events route by key the handler that answers belongs to the wrong instance. Subclasses that emit inner nodes override :attr:default_key so an unkeyed instance still namespaces predictably.

base_key property

The key this component's root node and inner keys namespace under.

Returns:

Type	Description
str	The caller-supplied key, or :attr:default_key when unkeyed.

child_key(suffix)

Namespace one inner node's key under this component's key.

Parameters:

Name	Type	Description	Default
suffix	str	The node's role inside this component ("seg-0", "card-body"), unique among the component's own nodes.	required

Returns:

Type	Description
str	The suffix prefixed with :attr:base_key, so two instances of the
str	component on one screen never emit the same key.

render()

Lower this component into a primitive widget tree.

Returns:

Type	Description
Widget	The widget tree this component expands to (may itself contain further
Widget	components, which are expanded recursively).

Raises:

Type	Description
NotImplementedError	If a subclass does not implement it.

ConnectivityEvent

Bases: Event

The device's network connectivity changed.

Emitted by the host's connectivity callback and routed over the reserved connectivity token ("__connectivity__:<state>"), so application code can react to the device going online/offline or switching transports.

Attributes:

Name	Type	Description
state	ConnectivityState	The new connectivity state.

ConnectivityState

Bases: StrEnum

The device's current network connectivity state.

Attributes:

Name	Type	Description
CONNECTED		The device has an active network link of an unspecified or generic transport — reachability is available but the kind of link is not distinguished.
DISCONNECTED		The device has no active network link; requests will fail until connectivity is restored (airplane mode, no signal, Wi-Fi off).
WIFI		The device is connected over a Wi-Fi network — typically unmetered, so larger transfers are acceptable.
MOBILE		The device is connected over a cellular (mobile data) network — typically metered, so handlers may choose to defer heavy transfers.

Container

Bases: Widget

A single-child box used for padding, background, borders and sizing.

Attributes:

Name	Type	Description
child	Widget | None	The optional wrapped widget.

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

DateChangeEvent

Bases: Event

A date picker's value changed.

Attributes:

Name	Type	Description
value	str	The new date as an ISO yyyy-mm-dd string (empty when cleared).

DatePicker

Bases: _FieldWidget

A date selection field, styled via the H2 field-variant API (field trigger).

Attributes:

Name	Type	Description
value	str	The selected date as an ISO yyyy-mm-dd string ("" if unset).
label	str	An optional label shown with the field.
field_variant	FieldVariant	The field treatment (outline/filled/flushed).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	DateChangeHandler | None	Handler invoked with a :class:DateChangeEvent on selection.

DeepLinkEvent

Bases: Event

The app was opened (or resumed) via a deep link.

Carries the link target and its parsed query parameters as a flat dict[str, str] so the payload stays JSON-serializable.

Attributes:

Name	Type	Description
url	str	The full deep-link URL.
params	dict[str, str]	The parsed query parameters (empty when the link carries none).

Dialog

Bases: Widget

A modal dialog floated above the screen, optionally with a title.

Attributes:

Name	Type	Description
title	str | None	Optional dialog title.
children	list[Widget]	The dialog body widgets.
on_dismiss	DismissHandler | None	Handler invoked when the user dismisses the dialog (barrier tap or system back), validated against :class:DismissEvent.

child_nodes()

Return the dialog's body widgets.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

DismissEvent

Bases: Event

An overlay was dismissed (barrier tap, swipe-down, or system back).

The renderer emits this when the user dismisses an overlay through a gesture the host owns (tapping the scrim behind a dialog, dragging a sheet down). The bridge routes it to App.dismiss; the optional overlay_id lets the host name the overlay, while None lets a renderer fire it without one (the bridge then falls back to the token-encoded id).

Attributes:

Name	Type	Description
overlay_id	str | None	The dismissed overlay's stable id, or None when the renderer dispatches without one.

Dismissible

Bases: Widget

A child that can be swiped away to dismiss it (swipe-to-delete).

Attributes:

Name	Type	Description
child	Widget | None	The wrapped widget the dismiss gesture is detected over.
direction	SwipeDirection	The swipe direction that triggers the dismiss (defaults to :attr:~tempestroid.widgets.events.SwipeDirection.LEFT).
on_dismiss	DismissHandler | None	Optional handler fired once the swipe passes the dismiss threshold (receives a DismissEvent; reuses the overlay-dismiss event type).

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

DoubleTapHandler

Bases: Widget

A single-child container that reports a double tap.

Attributes:

Name	Type	Description
child	Widget | None	The wrapped widget the double tap is detected over.
on_double_tap	TapHandler | None	Optional handler for a double tap (receives a TapEvent).

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

DragEvent

Bases: Event

A drag-and-drop interaction: an item picked up and (maybe) dropped.

Emitted by Draggable (on release) and DragTarget (on drop). The data field is the opaque label declared by the Draggable so the drop target can identify what landed on it; x/y report the drop position when the renderer can measure it.

Attributes:

Name	Type	Description
data	str	The opaque payload carried from Draggable.drag_data.
x	float | None	Optional x position of the drop, in logical pixels.
y	float | None	Optional y position of the drop, in logical pixels.

Draggable

Bases: Widget

A child that can be picked up and dragged onto a :class:DragTarget.

Attributes:

Name	Type	Description
child	Widget | None	The wrapped widget the user drags.
drag_data	str	An opaque label carried to the drop target via the DragEvent.data field, so the target can identify what landed on it.
on_drag	DragHandler | None	Optional handler fired when the drag finishes (receives a DragEvent with the carried data and the release position).

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

DragTarget

Bases: Widget

A child that accepts a dropped :class:Draggable.

Attributes:

Name	Type	Description
child	Widget | None	The wrapped widget that acts as the drop region.
on_drop	DragHandler | None	Optional handler fired when a draggable is released over this target (receives a DragEvent carrying the dropped item's data).

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

DrawOval

Bases: BaseModel

Add an ellipse (oval) to the active path.

Attributes:

Name	Type	Description
kind	Literal['draw_oval']	The command discriminator ("draw_oval").
x	float	Bounding box left, in logical pixels.
y	float	Bounding box top, in logical pixels.
width	float	Bounding box width, in logical pixels.
height	float	Bounding box height, in logical pixels.

DrawRect

Bases: BaseModel

Add a rectangle to the active path.

Attributes:

Name	Type	Description
kind	Literal['draw_rect']	The command discriminator ("draw_rect").
x	float	Rectangle left, in logical pixels.
y	float	Rectangle top, in logical pixels.
width	float	Rectangle width, in logical pixels.
height	float	Rectangle height, in logical pixels.

DrawText

Bases: BaseModel

Draw a run of text at a baseline anchor.

Attributes:

Name	Type	Description
kind	Literal['draw_text']	The command discriminator ("draw_text").
text	str	The text to draw.
x	float	Baseline x coordinate, in logical pixels.
y	float	Baseline y coordinate, in logical pixels.
size	float	The font size, in logical pixels.
color	list[float]	The text color as an [r, g, b, a] list of floats in [0, 1] (a list, never a tuple).

Dropdown

Bases: _FieldWidget

A single-choice dropdown / select control, styled via the H2 field API.

Attributes:

Name	Type	Description
options	list[str]	The selectable option strings, in display order.
value	str | None	The currently selected option, or None when nothing is chosen.
placeholder	str	The hint shown while no option is selected.
leading_icon	Icons | str | None	An optional icon name shown inside the control on the start (leading) edge — a curated :class:~tempestroid.icons.Icons value (or its string) or an arbitrary platform icon name.
trailing_icon	Icons | str | None	An optional icon name shown inside the control on the end (trailing) edge, resolved like :attr:leading_icon.
field_variant	FieldVariant	The field treatment (outline/filled/flushed).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_select	SelectHandler | None	Handler invoked with a :class:SelectEvent (carrying the option value and its 0-based index) on selection.

EndReachedEvent

Bases: Event

The list scrolled past its end-reached threshold.

Carries no payload. The handler typically paginates — loading the next page of items and growing the list's item_count.

Event

Bases: BaseModel

Base class for all events crossing the native boundary.

EventValidationError

Bases: Exception

Raised when a raw event payload fails validation at the boundary.

Attributes:

Name	Type	Description
event_type	type[Event]	The expected event type.
errors	list[dict[str, Any]]	The structured Pydantic error list (JSON-serializable).

__init__(event_type, errors)

Initialize the error.

Parameters:

Name	Type	Description	Default
event_type	type[Event]	The expected event type.	required
errors	list[dict[str, Any]]	The structured validation errors.	required

FilePicker

Bases: _FieldWidget

A field-shaped trigger that opens the platform file picker (H2 field API).

Attributes:

Name	Type	Description
label	str	The button text.
value	str	The selected file's display name/URI ("" until one is chosen).
field_variant	FieldVariant	The field treatment (outline/filled/flushed).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_select	FileSelectHandler | None	Handler invoked with a :class:FileSelectEvent on selection.

FileSelectEvent

Bases: Event

A file was selected from a file picker.

Attributes:

Name	Type	Description
uri	str	The selected file's URI (Android content://) or path.
name	str | None	The display name, if the platform reports one.

FillCmd

Bases: BaseModel

Fill the active path with a solid color and reset the path.

Attributes:

Name	Type	Description
kind	Literal['fill']	The command discriminator ("fill").
color	list[float]	The fill color as an [r, g, b, a] list of floats in [0, 1] (a list, never a tuple, so the command is JSON-serializable directly).

Form

Bases: Widget

A container that aggregates fields, validates them, and gates submit.

The fields are exposed as child nodes (each a :class:FormField), so the serialized tree carries them as children — never as a prop holding nested models. :meth:validate runs every field's validators purely in Python and returns a :class:FormState; the application uses it to decide whether to dispatch the form's :class:~tempestroid.widgets.events.SubmitEvent.

Attributes:

Name	Type	Description
fields	list[FormField]	The form's fields, in display order.
on_submit	SubmitHandler | None	Handler invoked with a :class:SubmitEvent when the form is submitted with valid values.

Methods:

Name	Description
validate	Validate every field against values and build the :class:FormState (used to gate submit).

validate(values)

Validate every field against values and build the form state.

Pure: runs each field's validators against the matching value (an absent value validates as the empty string), collects the failures into a flat dict[str, str], and reports overall validity. Performs no side effects — the caller decides what to do with the result (e.g. mirror each error back onto its field and gate SubmitEvent).

Parameters:

Name	Type	Description	Default
values	dict[str, Any]	A mapping of field name to its raw value at validation time.	required

Returns:

Name	Type	Description
A	FormState	class:FormState whose errors holds only the failing fields and
	FormState	whose valid is True when no field failed.

child_nodes()

Return the form's fields in order.

Returns:

Type	Description
list[Widget]	The ordered :class:FormField children (empty when the form has no
list[Widget]	fields).

FormField

Bases: Widget

A labelled wrapper around a single input, carrying validation metadata.

The wrapped input is exposed as a child node (so renderers render it recursively and it crosses the boundary as a normal child, never as a prop). The error prop mirrors :attr:FormState.errors for this field; the enclosing :class:Form fills it after running validators.

Attributes:

Name	Type	Description
name	str	The field's name (the key used in :attr:FormState.errors and :attr:~tempestroid.widgets.events.SubmitEvent.values).
validators	list[_AnnotatedValidator]	The typed validation rules run against this field's value. Pure Python — never serialized over the boundary.
label	str	An optional label shown above the input.
error	str	The current validation message ("" when valid). Mirrored from the owning form's :class:FormState.
child	Widget | None	The wrapped input widget rendered inside the field.
on_validate	ValidationHandler | None	Optional handler invoked with a :class:ValidationEvent when this field is validated.

run_validators(value)

Run this field's validators against value.

Named run_validators rather than validate to avoid shadowing Pydantic's deprecated BaseModel.validate classmethod.

Parameters:

Name	Type	Description	Default
value	Any	The field's raw value.	required

Returns:

Type	Description
str | None	The first validator's error message, or None when every validator
str | None	passes.

child_nodes()

Return the wrapped input, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child input, or an empty list.

FormState

Bases: BaseModel

The structured result of validating a form.

Frozen so it can be diffed by value and dropped straight into the app state. Serializes to plain JSON — {"errors": {...}, "valid": bool} — with no nested models.

Attributes:

Name	Type	Description
errors	dict[str, str]	A mapping of field name to its error message. Only failing fields appear; an empty mapping means every field passed.
valid	bool	True when no field has an error.

GestureDetector

Bases: Widget

A single-child container that reports touch gestures over its child.

Attributes:

Name	Type	Description
child	Widget | None	The wrapped widget the gestures are detected over.
on_tap	TapHandler | None	Optional handler for a single tap (receives a TapEvent).
on_double_tap	TapHandler | None	Optional handler for a double tap (receives a TapEvent).
on_long_press	LongPressHandler | None	Optional handler for a held press past the long-press threshold (receives a LongPressEvent).
on_swipe	SwipeHandler | None	Optional handler for a directional swipe (receives a SwipeEvent).

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

Hero

Bases: Widget

A shared-element transition tag wrapping a single child.

When two screens of a :class:~tempestroid.widgets.Navigator each contain a Hero with the same :attr:hero_tag, the renderer interpolates the tagged subtree's geometry across the route transition (Qt: a QPropertyAnimation on geometry; Compose: SharedTransitionLayout + Modifier.sharedElement). The tag must be unique within each screen.

Attributes:

Name	Type	Description
hero_tag	str	The shared-element identity (must match across screens).
child	Widget	The wrapped widget that participates in the transition.

child_nodes()

Return the single wrapped child.

Returns:

Type	Description
list[Widget]	A one-element list holding the child.

Icon

Bases: Widget

A vector icon, drawn from the built-in curated set or a platform set.

The name may be one of the framework's curated icon names — see :class:tempestroid.icons.Icons and :data:tempestroid.icons.ICON_PATHS (e.g. Icons.SEARCH / "search") — in which case the renderer strokes the built-in single-path geometry resolved via :func:tempestroid.icons.icon_path. Otherwise name is treated as an arbitrary platform icon identifier (e.g. a Material Icons name like "home"); when neither resolves, the renderer falls back to showing the name. This keeps the field contract unchanged.

Attributes:

Name	Type	Description
name	str	The icon identifier — a curated :class:~tempestroid.icons.Icons value (or its string) or an arbitrary platform icon name.
size	float | None	The icon's edge length in logical pixels, or None for the renderer default.

IconButton

Bases: Widget

A square/circular icon-only button, styled via the Chakra-style variant API.

An icon button is button-shaped, so it reuses :func:~tempest_core.variants.resolve_variant exactly like :class:Button — then pins its width and height to the resolved min_height (a square hit area at least the 48dp touch target) and sets a circular radius, using only existing :class:~tempest_core.style.Style fields (no new field). It defaults to the GHOST variant (the lowest-emphasis, icon-forward treatment). An explicit style is merged on top of the resolved base.

The label carries the accessible name (contentDescription / accessible label) since the button has no visible text; renderers route it into the node's accessibility surface.

Attributes:

Name	Type	Description
icon	Icons | str	The icon to show — a curated :class:~tempest_core.icons.Icons value (or its string) or an arbitrary platform icon name.
on_click	EventHandler | None	Optional handler invoked on tap. May be sync or async.
variant	Variant	The visual treatment (solid/outline/ghost/link); defaults to GHOST.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family to paint with.
label	str	The accessible label for the icon-only button (a11y / Semantics).
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.

Methods:

Name	Description
state_styles	Resolve the per-interaction-state style table for the renderers (default/hover/pressed/disabled/focus), each pinned to the square/circular icon-button geometry.

state_styles()

Resolve the per-interaction-state style table for the renderers.

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of each :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved, squared, override-merged Style.

Image

Bases: Widget

A bitmap image loaded from a URL or asset path.

Attributes:

Name	Type	Description
src	str	The image source — an http(s) URL or a bundled asset path.
fit	ImageFit	How the image scales within its box.
alt	str	Alternative text shown if the image cannot be loaded.

ImageFit

Bases: StrEnum

How an image scales to fill its box (CSS object-fit vocabulary).

Attributes:

Name	Type	Description
CONTAIN		Scale the image up or down, preserving its aspect ratio, until it fits entirely inside the box. The whole image is visible and may leave empty space (letterboxing) on the unfilled axis.
COVER		Scale the image, preserving its aspect ratio, until it fully covers the box. The image fills the box with no empty space, and whatever overflows the box on the longer axis is cropped.
FILL		Stretch the image to the box's exact width and height, ignoring its aspect ratio. Nothing is cropped, but the image may appear distorted (squashed or stretched).
NONE		Do not scale the image at all; render it at its intrinsic pixel size. If larger than the box it is clipped; if smaller it is centered with surrounding empty space.

Input

Bases: _FieldWidget

A single-line editable text field, styled via the H2 field-variant API.

The field resolves its base :class:~tempest_core.style.Style from its field_variant / size / color_scheme against the design-system theme, via :func:~tempest_core.variants.resolve_field_variant, passing invalid=bool(self.error) so a field carrying an error message also paints its border/label the error role. An explicit style is merged on top of the resolved base (its set fields win), so hand-styling still works and existing Input(...) calls keep working with sensible defaults.

Attributes:

Name	Type	Description
value	str	The current text value.
placeholder	str	The hint shown when the field is empty.
secure	bool	Whether the text is masked (password field). When set, the renderer also offers a visibility toggle ("eye") that reveals the text locally without a round-trip to Python.
pattern	str | None	An optional regular expression the value must fully match to be considered valid. The renderer evaluates it and reports the result via :attr:TextChangeEvent.valid.
error	str	An optional validation message shown when the value is invalid. A non-empty error also forces the resolved border/label to the error role.
keyboard	KeyboardType	The soft-keyboard variant the field requests.
max_length	int | None	An optional cap on the number of characters.
leading_icon	Icons | str | None	An optional icon name shown inside the field on the start (leading) edge — a curated :class:~tempestroid.icons.Icons value (or its string) or an arbitrary platform icon name. The renderer resolves and places it; None shows no leading icon.
trailing_icon	Icons | str | None	An optional icon name shown inside the field on the end (trailing) edge, resolved like :attr:leading_icon. None shows no trailing icon.
field_variant	FieldVariant	The field treatment (outline/filled/flushed).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	TextChangeHandler | None	Handler invoked with a :class:TextChangeEvent on each edit.

InteractiveViewer

Bases: Widget

A single-child container the user can pan and zoom (pinch + drag).

Attributes:

Name	Type	Description
child	Widget | None	The wrapped widget that is panned and zoomed.
min_scale	float	The minimum allowed zoom factor.
max_scale	float	The maximum allowed zoom factor.
on_interaction	ScaleHandler | None	Optional handler fired as the view transforms (receives a ScaleEvent with the current scale, focal point and rotation).

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

KeyboardAvoidingView

Bases: Widget

A vertical container that recedes its content when the keyboard appears.

Wraps its children and, while the on-screen keyboard is open, insets them so the focused input stays visible above it. On the device the Compose renderer lowers it to a Column with Modifier.imePadding() (driven by WindowInsets.ime); the Qt simulator listens on QApplication.inputMethod().keyboardRectangleChanged and adjusts its content margins, behaving like a plain Column on desktop (no virtual keyboard). It declares no event contract — the keyboard inset is handled by the renderer, not surfaced to application handlers.

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets the view insets.

child_nodes()

Return the view's children.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

KeyboardType

Bases: StrEnum

The soft-keyboard variant a text field requests on the device.

Maps to Android inputType on the device renderer and to Qt input-method hints in the simulator.

Attributes:

Name	Type	Description
TEXT		The default full alphanumeric keyboard for free-form text, with no specialization.
NUMBER		A numeric keypad optimized for entering numbers (digits, and typically a decimal/sign key).
EMAIL		A text keyboard tuned for email addresses, surfacing the @ and . keys for quicker entry.
PHONE		A telephone dial pad for phone numbers (digits plus +, * and #).
URL		A text keyboard tuned for web addresses, surfacing / and . and omitting the space bar in favor of URL-friendly keys.
PASSWORD		A keyboard for secret entry; the field masks its characters and the platform disables suggestions/auto-correct so the value is not cached or learned.

LazyColumn

Bases: Widget

A vertically virtualized list (Compose LazyColumn).

Declares an item_count and an item_builder instead of materialized children. Only the visible window is built into the IR. Emits :class:~tempestroid.widgets.events.ScrollEvent as it scrolls, :class:~tempestroid.widgets.events.RefreshEvent on pull-to-refresh, and :class:~tempestroid.widgets.events.EndReachedEvent when scrolling past end_reached_threshold.

Attributes:

Name	Type	Description
item_count	int	The total number of items in the list.
item_builder	ItemBuilder	Factory building the item widget at a given index. Lives only on the Python side; never serialized over the boundary.
window_size	int	The number of items materialized into the initial window when :attr:window is unset (so the first mount has content).
window	tuple[int, int] | None	The current visible [start, end) window, or None to use the initial default. The application slides this on a scroll event.
end_reached_threshold	float	The fraction 0..1 of total scroll at which :attr:on_end_reached fires.
refreshing	bool	Whether the pull-to-refresh spinner is active.
on_scroll	ScrollHandler | None	Optional handler for scroll events.
on_refresh	RefreshHandler | None	Optional handler for pull-to-refresh.
on_end_reached	EndReachedHandler | None	Optional handler fired near the end of the list.

child_nodes()

Materialize the current visible window into keyed item widgets.

Returns:

Type	Description
list[Widget]	The items in the resolved window, each keyed by absolute index.

LazyGrid

Bases: Widget

A virtualized grid (Compose LazyVerticalGrid).

Lays virtualized items out in a fixed number of columns, scrolling vertically. Has no pull-to-refresh (use a wrapping :class:RefreshControl).

Attributes:

Name	Type	Description
item_count	int	The total number of items in the grid.
item_builder	ItemBuilder	Factory building the item widget at a given index. Lives only on the Python side; never serialized over the boundary.
columns	int	The number of grid columns.
window_size	int	The number of items materialized into the initial window when :attr:window is unset (so the first mount has content).
window	tuple[int, int] | None	The current visible [start, end) window, or None to use the initial default. The application slides this on a scroll event.
end_reached_threshold	float	The fraction 0..1 of total scroll at which :attr:on_end_reached fires.
on_scroll	ScrollHandler | None	Optional handler for scroll events.
on_end_reached	EndReachedHandler | None	Optional handler fired near the end of the grid.

child_nodes()

Materialize the current visible window into keyed item widgets.

Returns:

Type	Description
list[Widget]	The items in the resolved window, each keyed by absolute index.

LazyRow

Bases: Widget

A horizontally virtualized list (Compose LazyRow).

The horizontal analogue of :class:LazyColumn: identical contract, items laid out and scrolled left-to-right.

Attributes:

Name	Type	Description
item_count	int	The total number of items in the list.
item_builder	ItemBuilder	Factory building the item widget at a given index. Lives only on the Python side; never serialized over the boundary.
window_size	int	The number of items materialized into the initial window when :attr:window is unset (so the first mount has content).
window	tuple[int, int] | None	The current visible [start, end) window, or None to use the initial default. The application slides this on a scroll event.
end_reached_threshold	float	The fraction 0..1 of total scroll at which :attr:on_end_reached fires.
refreshing	bool	Whether the pull-to-refresh spinner is active.
on_scroll	ScrollHandler | None	Optional handler for scroll events.
on_refresh	RefreshHandler | None	Optional handler for pull-to-refresh.
on_end_reached	EndReachedHandler | None	Optional handler fired near the end of the list.

child_nodes()

Materialize the current visible window into keyed item widgets.

Returns:

Type	Description
list[Widget]	The items in the resolved window, each keyed by absolute index.

LifecycleEvent

Bases: Event

The application moved between lifecycle states.

Emitted by the host's lifecycle observer (Android ProcessLifecycleOwner, or the Qt simulator's QApplication.applicationStateChanged) and routed over the reserved lifecycle token, so application code can react to the app entering the foreground or background.

Attributes:

Name	Type	Description
state	AppState	The new lifecycle state.

LineTo

Bases: BaseModel

Add a straight line from the current point to (x, y).

Attributes:

Name	Type	Description
kind	Literal['line_to']	The command discriminator ("line_to").
x	float	Target x coordinate, in logical pixels.
y	float	Target y coordinate, in logical pixels.

LocaleChangeEvent

Bases: Event

The active locale / layout direction changed.

Not emitted by a widget handler: the host fires it when the device locale changes (or app code requests a switch), and the bridge routes it over the reserved locale token ("__locale__") to App.set_locale.

Attributes:

Name	Type	Description
language	str	The new BCP-47 language tag.
region	str | None	The optional region/country subtag.
rtl	bool	Whether the new locale lays out right-to-left.

LongPressEvent

Bases: Event

A press held past the long-press threshold.

Attributes:

Name	Type	Description
x	float | None	Optional x position of the press, in logical pixels.
y	float | None	Optional y position of the press, in logical pixels.

MapView

Bases: Widget

An embedded map centered on a coordinate, with optional markers.

Attributes:

Name	Type	Description
latitude	float	The map center latitude, in degrees.
longitude	float	The map center longitude, in degrees.
zoom	float	The map zoom level.
markers	list[dict[str, Any]]	Plain JSON-serializable marker descriptors (each a dict, e.g. {"lat": ..., "lng": ..., "title": ...}); the list crosses the boundary as-is.

MaskedInput

Bases: _FieldWidget

A text field that enforces an input mask while typing (H2 field API).

The mask uses 9 for a required digit and A for a required letter; any other character is a fixed literal (e.g. "999.999.999-99" for a CPF). The renderer translates the mask to its native notation.

Attributes:

Name	Type	Description
mask	str	The input mask pattern (9 digit, A letter, else literal).
value	str	The current text value.
placeholder	str	The hint shown when the field is empty.
keyboard	KeyboardType	The soft-keyboard variant the field requests.
field_variant	FieldVariant	The field treatment (outline/filled/flushed).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	TextChangeHandler | None	Handler invoked with a :class:TextChangeEvent on each edit.

Menu

Bases: Widget

A list of selectable items anchored to a widget.

Attributes:

Name	Type	Description
items	list[MenuItem]	The selectable entries.
anchor	str | None	Optional key of the widget the menu anchors to.
on_select	MenuSelectHandler | None	Handler invoked on item selection, validated against :class:MenuSelectEvent.

MenuItem

Bases: BaseModel

A single selectable entry in a :class:Menu or :class:ActionSheet.

A frozen value model (not a widget): it carries only JSON-serializable data so it crosses the device bridge as a plain dict.

Attributes:

Name	Type	Description
label	str	The display label.
value	str	The stable value reported by :class:MenuSelectEvent on select.
icon	str | None	Optional icon name to render alongside the label.

MenuSelectEvent

Bases: Event

The user selected an item from a menu or action sheet.

Attributes:

Name	Type	Description
value	str	The selected item's stable value.
label	str	The selected item's display label.

MoveTo

Bases: BaseModel

Move the current point of the active path without drawing.

Attributes:

Name	Type	Description
kind	Literal['move_to']	The command discriminator ("move_to").
x	float	Target x coordinate, in logical pixels.
y	float	Target y coordinate, in logical pixels.

Navigator

Bases: Widget

A navigation-stack host that renders the screen on top of the stack.

The view builds child from app.nav.top and wraps it in a Navigator; pushing/popping a route rebuilds with a different child, which the reconciler diffs (an Update when the screen's subtree is compatible, a Replace otherwise). The transition prop is a renderer hint for how to animate the swap, and depth (the stack length) lets the renderer tell a push (deeper) from a pop (shallower) to pick the slide direction.

Attributes:

Name	Type	Description
child	Widget	The screen currently on top of the stack.
transition	str	Animation hint for a screen swap ("slide", "fade" or "none"). Defaults to "slide".
depth	int	The current navigation stack depth. The renderer compares it against the previous depth to slide forward (push) or back (pop).

child_nodes()

Return the top screen as this navigator's single child.

Returns:

Type	Description
list[Widget]	A one-element list with the top screen.

PageChangeEvent

Bases: Event

The active page of a PageView carousel changed.

Emitted when the user swipes to a new page (or a renderer's prev/next control settles on one). The application keeps the active page in its own state and reacts by storing the new index; a handler should guard against re-emitting the same index to avoid a feedback loop.

Attributes:

Name	Type	Description
page	int	The new active page index (0-based).
previous	int	The page index that was active before the change.

PageView

Bases: Widget

A paginated horizontal carousel: one full-width page visible at a time.

Each child is a page; the user swipes (device) or uses prev/next controls (simulator) to move between them. The active page index lives in the application's own state — the app passes the current :attr:page and updates it from the :attr:on_page_change handler. To avoid a feedback loop, a handler should ignore a :class:PageChangeEvent whose page already matches the state. The Compose renderer lowers it to a HorizontalPager; the Qt renderer uses a QStackedWidget with prev/next navigation.

Attributes:

Name	Type	Description
children	list[Widget]	The ordered page widgets.
page	int	The active page index (0-based), driven by the application state.
on_page_change	PageChangeHandler | None	Handler invoked with a :class:PageChangeEvent when the active page changes.

child_nodes()

Return the carousel's pages in order.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

PanEvent

Bases: Event

A pan/drag gesture reported continuously and on release.

Emitted by PanHandler as the pointer drags over its child, carrying the per-frame delta and — at release — the fling velocity, so handlers can drive momentum scrolling or kinetic movement.

Attributes:

Name	Type	Description
dx	float	Horizontal travel since the previous report, in logical pixels.
dy	float	Vertical travel since the previous report, in logical pixels.
vx	float	Horizontal velocity at release, in logical pixels per second.
vy	float	Vertical velocity at release, in logical pixels per second.

PinInput

Bases: _FieldWidget

A segmented PIN / OTP entry of single-character cells (H2 field API).

Forces the OUTLINE field variant (the segmented cells read as outlined boxes). Emits a :class:TextChangeEvent (the concatenated value) on each edit and a :class:SubmitEvent once every cell is filled.

Attributes:

Name	Type	Description
length	int	The number of single-character cells.
value	str	The current concatenated value.
secure	bool	Whether each cell masks its character (PIN rather than OTP).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	TextChangeHandler | None	Handler invoked with a :class:TextChangeEvent on each edit.
on_complete	SubmitHandler | None	Handler invoked with a :class:SubmitEvent when all cells are filled.

Popover

Bases: Widget

A floating panel anchored near a widget, dismissible by tapping away.

Attributes:

Name	Type	Description
child	Widget | None	Optional widget shown inside the popover.
anchor	str | None	Optional key of the widget the popover anchors to.
on_dismiss	DismissHandler | None	Handler invoked on dismiss, validated against :class:DismissEvent.

child_nodes()

Return the popover's child, if any.

Returns:

Type	Description
list[Widget]	A single-element list with the child, or an empty list.

ProgressBar

Bases: Widget

A horizontal progress bar.

Attributes:

Name	Type	Description
value	float	The completed fraction in [0.0, 1.0] (ignored when indeterminate is set).
indeterminate	bool	When True, render a looping bar with no fixed value (work of unknown duration).
color_scheme	str	The Material 3 role family the renderer paints the bar's accent (the filled track) with — one of the design-system color schemes. The engine carries the prop; the renderer resolves the accent against the active theme (H4).

QrScanEvent

Bases: Event

A QR/barcode scan result.

Emitted by QrScanner for each decoded code. The decoded payload and its symbology cross the boundary as plain strings.

Attributes:

Name	Type	Description
data	str	The decoded code contents.
format	str	The barcode symbology (e.g. "QR_CODE").

QrScanner

Bases: Widget

A live camera surface that scans QR/barcodes and reports each result.

Attributes:

Name	Type	Description
on_scan	EventHandler | None	Handler invoked with a :class:QrScanEvent for each decoded code (the typed event is the widget's contract; the device wires the scanner directly to this handler's token).

RangeChangeEvent

Bases: Event

A range slider's bounds changed.

The two bounds cross the boundary as separate top-level floats (never a raw tuple) so the payload stays JSON-serializable.

Attributes:

Name	Type	Description
low	float	The lower bound of the selected range.
high	float	The upper bound of the selected range.

RangeSlider

Bases: _SliderWidget

A dual-handle slider selecting a [low, high] sub-range (H2 slider API).

Attributes:

Name	Type	Description
low	float	The current lower bound, clamped to [min_value, high].
high	float	The current upper bound, clamped to [low, max_value].
min_value	float	The lowest selectable value.
max_value	float	The highest selectable value.
step	float	The increment between selectable values.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the active track paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	RangeChangeHandler | None	Handler invoked with a :class:RangeChangeEvent carrying both bounds as the range moves.

RefreshControl

Bases: Widget

A standalone pull-to-refresh wrapper (Compose PullToRefreshBox).

Wraps content with a pull-to-refresh gesture, decoupled from a virtualized list — use it around any scrollable content. The content is supplied by the renderer (the widget itself carries only the refresh contract); see the renderer's RefreshControl case for how content is wired.

Attributes:

Name	Type	Description
refreshing	bool	Whether the pull-to-refresh spinner is active.
on_refresh	RefreshHandler | None	Optional handler for pull-to-refresh.

RefreshEvent

Bases: Event

A pull-to-refresh gesture completed.

Carries no payload: the gesture itself is the signal. The handler typically reloads the list's data and clears the widget's refreshing flag.

ReorderableList

Bases: Widget

A vertical list whose items can be dragged into a new order.

The handler typically mutates its backing list (items.insert(to_index, items.pop(from_index))) and re-renders; a keyed child list then diffs to a Reorder patch (the A2 mechanism), so no new patch kind is needed.

Attributes:

Name	Type	Description
children	list[Widget]	The ordered list items. Prefer stable keys so the keyed diff emits a Reorder rather than positional updates.
on_reorder	ReorderHandler | None	Optional handler fired when an item is dragged to a new slot (receives a ReorderEvent with the source and destination index).

child_nodes()

Return the list items in order.

Returns:

Type	Description
list[Widget]	The ordered child widgets (empty when the list has no items).

ReorderEvent

Bases: Event

A list item dragged from one position to another.

Emitted by ReorderableList when the user drags an item to a new slot. The handler typically mutates its backing list (items.insert(to_index, items.pop(from_index))); a keyed child list then diffs to a Reorder patch (the A2 mechanism), so no new patch kind is needed.

Attributes:

Name	Type	Description
from_index	int	The item's original index.
to_index	int	The item's destination index.

RouteChangeEvent

Bases: Event

The active route changed (a push/pop/replace happened).

This is the typed payload a navigation host emits when it settles on a new screen, so handlers (analytics, focus management) can react to navigation across the native boundary.

Attributes:

Name	Type	Description
name	str	The destination route name.
params	dict[str, Any]	The destination route's typed parameters.

RouteDrawer

Bases: Widget

A drawer-as-route host: main content with a slide-over side panel.

When open is True the renderer slides the drawer panel over the child content; toggling it fires on_change so a handler can flip the open flag and rebuild. Modelling the drawer as a widget (rather than a transient overlay) keeps its open/closed state in the declarative tree, so it survives rebuilds and diffs like any other prop.

Attributes:

Name	Type	Description
child	Widget	The main content shown under the drawer.
drawer	Widget	The panel that slides over the content when open.
open	bool	Whether the drawer panel is currently shown.
on_change	RouteChangeHandler | None	Optional handler invoked with a RouteChangeEvent when the drawer toggles.

child_nodes()

Return the content and the drawer panel, in that order.

Returns:

Type	Description
list[Widget]	A two-element list: [child, drawer].

Row

Bases: Widget

A horizontal flex container (main axis = left-to-right).

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets.

child_nodes()

Return the row's children.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

SafeArea

Bases: Widget

A single-child box that insets its child away from system intrusions.

Mirrors React Native's SafeAreaView: it pads the content so it does not sit under the status bar, the navigation bar, or a display cutout/notch. On the device renderer the inset is the real WindowInsets.safeDrawing reported by the platform; the desktop simulator has no system bars, so it stands in with fixed approximate insets. The edges set selects which edges are protected — pass a subset (e.g. only SafeAreaEdge.TOP) to leave the others flush.

Attributes:

Name	Type	Description
child	Widget | None	The optional wrapped widget.
edges	list[SafeAreaEdge]	The edges to inset against (defaults to all four).

child_nodes()

Return the wrapped child, if any.

Returns:

Type	Description
list[Widget]	A one-element list with the child, or an empty list.

SafeAreaEdge

Bases: StrEnum

A screen edge a :class:SafeArea can inset against system intrusions.

Attributes:

Name	Type	Description
TOP		The top edge. Insetting it pushes content below the status bar or a top display cutout/notch so it is not drawn underneath them.
RIGHT		The right edge. Insetting it keeps content clear of right-side intrusions such as a rounded corner or a landscape-orientation notch.
BOTTOM		The bottom edge. Insetting it lifts content above the system navigation bar or the home-indicator gesture area.
LEFT		The left edge. Insetting it keeps content clear of left-side intrusions such as a rounded corner or a landscape-orientation notch.

ScaleEvent

Bases: Event

A pinch (scale + rotation) gesture, anchored at a focal point.

Emitted by ScaleHandler and InteractiveViewer as the user pinches or rotates two pointers over the child. The focal point is reported as two top-level floats (never a raw tuple) so the payload stays JSON-serializable across the bridge.

Attributes:

Name	Type	Description
scale	float	The cumulative scale factor (1.0 is no change).
focus_x	float	The x coordinate of the pinch focal point, in logical pixels.
focus_y	float	The y coordinate of the pinch focal point, in logical pixels.
rotation	float	The cumulative rotation, in degrees.

ScrollEvent

Bases: Event

A scrollable container scrolled.

Emitted by virtualized lists as the user scrolls, so the application can recompute the visible window and request new items.

Attributes:

Name	Type	Description
offset	float	The current scroll position, in logical pixels.
direction	str	The scroll axis ("vertical" or "horizontal").

ScrollView

Bases: Widget

A scrollable container holding an overflowing list of children.

Attributes:

Name	Type	Description
horizontal	bool	When True, children lay out and scroll left-to-right; otherwise they stack and scroll top-to-bottom.
children	list[Widget]	The ordered child widgets.

child_nodes()

Return the scroll view's children.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

SectionHeader

Bases: BaseModel

One section of a :class:SectionList: a header plus virtualized items.

A section is not a widget — it is a frozen value object describing how to build a section's sticky header and its items. The header_builder and item_builder callables are Python factories that live only on the Python side; they never cross the native boundary (the serializer drops them).

Attributes:

Name	Type	Description
title	str	A stable label for the section (used as a key and for the header).
item_count	int	The number of items in this section.
item_builder	ItemBuilder	Factory building the item widget at a section-local index.
header_builder	HeaderBuilder	Factory building this section's sticky header widget.
window_size	int	The number of items materialized into this section's initial window when :attr:window is unset.
window	tuple[int, int] | None	The current visible [start, end) window for this section, or None to use the initial default. The application slides it on a scroll event by replacing the (frozen) section via model_copy.

materialize()

Materialize this section's header plus its visible item window.

The header is keyed "sec:<title>:header" and each item "sec:<title>:<index>" so every materialized child of a :class:SectionList carries a globally unique key for the keyed diff.

Returns:

Type	Description
list[Widget]	The header widget followed by the section's windowed items.

SectionList

Bases: Widget

A sectioned virtualized list with sticky section headers.

Each :class:SectionHeader declares a header plus its own virtualized items. The renderer renders the headers sticky (Compose stickyHeader; the Qt simulator pins a label above the scroll area).

Attributes:

Name	Type	Description
sections	list[SectionHeader]	The ordered sections to render.
end_reached_threshold	float	The fraction 0..1 of total scroll at which :attr:on_end_reached fires.
on_scroll	ScrollHandler | None	Optional handler for scroll events.
on_end_reached	EndReachedHandler | None	Optional handler fired near the end of the list.

child_nodes()

Materialize each section's header and visible item window in order.

Returns:

Type	Description
list[Widget]	The flattened header + windowed items of every section, keyed for the
list[Widget]	reconciler's keyed diff.

SelectEvent

Bases: Event

An option was selected from a dropdown / select control.

Attributes:

Name	Type	Description
value	str	The selected option string.
index	int	The 0-based index of the option in the control's options list.

Semantics

Bases: BaseModel

Accessibility metadata propagated to both renderers.

Attached to any :class:Widget via :attr:Widget.semantics; the leaf renderers map it to the platform's accessibility surface (Qt QAccessible name/description; Compose Modifier.semantics { contentDescription; role }) so screen readers (TalkBack, Qt AT) can describe the node. Frozen so the reconciler diffs it by value.

Attributes:

Name	Type	Description
label	str | None	The accessible label (contentDescription / accessible name).
role	str | None	The accessible role hint (e.g. "button", "image", "heading"); the renderer maps it to its native role enum.
hint	str | None	An accessibility hint / tooltip describing what the node does.

SensorEvent

Bases: Event

A single sample from a device sensor stream.

Emitted continuously by the host while a sensor stream is open and routed over the reserved sensor token ("__sensor__:<type>"). The sample values cross the boundary as a flat list of floats (never a tuple) so the payload stays JSON-serializable.

Attributes:

Name	Type	Description
sensor	SensorType	Which sensor produced the sample.
values	list[float]	The sample values (e.g. [x, y, z] for the accelerometer).
timestamp_ms	int	The sample timestamp in milliseconds since boot, or 0 when the host does not report one.

SensorType

Bases: StrEnum

A device hardware sensor a continuous stream can be opened on.

Attributes:

Name	Type	Description
ACCELEROMETER		Reports linear acceleration along the device's x/y/z axes (including gravity), in metres per second squared.
GYROSCOPE		Reports the device's angular velocity (rate of rotation) about its x/y/z axes, in radians per second.
MAGNETOMETER		Reports the ambient geomagnetic field strength along the device's x/y/z axes, in microtesla — the basis for a compass.
PRESSURE		Reports ambient atmospheric (barometric) pressure, in hectopascals, used for altitude estimation and weather sensing.
LIGHT		Reports ambient illuminance at the screen, in lux — used to drive automatic screen-brightness adjustment.
PROXIMITY		Reports nearness of an object to the front of the device (e.g. an ear during a call); typically a near/far distance in centimetres.
STEP_COUNTER		Reports the cumulative number of steps the user has taken since the device last booted, as counted by the hardware pedometer.

Shimmer

Bases: Widget

A loading placeholder that sweeps a gradient highlight over a child.

Wraps a child (usually a skeleton layout) and animates a diagonal gradient band from :attr:base_color toward :attr:highlight_color and back in a loop, the classic "content is loading" shimmer. Qt drives the gradient with an internal QTimer repaint loop; the device renderer uses an InfiniteTransition + Brush.linearGradient (a documented divergence).

Attributes:

Name	Type	Description
child	Widget	The wrapped widget the shimmer paints over.
base_color	Color	The resting tone of the gradient.
highlight_color	Color	The moving highlight tone.
duration_ms	int	The duration of one full sweep, in milliseconds.

child_nodes()

Return the single wrapped child.

Returns:

Type	Description
list[Widget]	A one-element list holding the child.

Skeleton

Bases: Widget

A childless rectangular shimmer placeholder.

The leaf variant of :class:Shimmer: a single rounded rectangle that sweeps a gradient highlight, used to stand in for a line of text or an avatar while the real content loads. Qt realizes it as a rounded QLabel with the same gradient repaint loop as :class:Shimmer.

Attributes:

Name	Type	Description
width	float | None	The fixed width in logical pixels, or None to flex.
height	float | None	The fixed height in logical pixels, or None to flex.
radius	float	The corner radius in logical pixels.
base_color	Color	The resting tone of the gradient.
highlight_color	Color	The moving highlight tone.
duration_ms	int	The duration of one full sweep, in milliseconds.
color_scheme	str	The Material 3 role family the renderer may tint the shimmer tones with — one of the design-system color schemes. The engine carries the prop; the renderer resolves it against the active theme (H4). Defaults to "neutral" (the classic grey shimmer).

SlideEvent

Bases: Event

A slider's value changed.

Attributes:

Name	Type	Description
value	float	The new slider value, in the widget's [min, max] range.

Slider

Bases: _SliderWidget

A draggable value slider over a numeric range (H2 slider-variant API).

Resolves its active/inactive track + thumb :class:~tempest_core.style.Style from its size / color_scheme against the theme; an explicit style is merged on top.

Attributes:

Name	Type	Description
value	float	The current value, clamped to [min_value, max_value].
min_value	float	The lowest selectable value.
max_value	float	The highest selectable value.
step	float	The increment between selectable values.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the active track paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	SlideHandler | None	Handler invoked with a :class:SlideEvent as the value moves.

Spacer

Bases: Widget

A flexible empty box that consumes free space along its parent's main axis.

The layout primitive for pushing siblings apart: dropped between two children of a :class:Row/:class:Column (or an :class:HStack/:class:VStack), it expands to fill the remaining space so the children are pushed to the ends. It is a leaf with no children and renders nothing visible — only its :attr:~tempest_core.widgets.base.Widget.style grow matters. When the caller leaves grow unset, the spacer defaults to grow == 1.0 (its whole purpose); an explicit style with a different grow wins, so a weighted spacer (Style(grow=2.0)) still works. The renderers realize it as a stretchable empty box (Qt addStretch / a growing QWidget; Compose Modifier.weight), using only the existing grow style field — no new field is added.

Attributes:

Name	Type	Description
flex	float	The flex weight the spacer grows by (defaults to 1.0); baked into the node's style.grow unless an explicit style.grow is already set.

Spinner

Bases: Widget

A circular activity indicator (always indeterminate).

Attributes:

Name	Type	Description
size	float | None	The indicator's diameter in logical pixels, or None for the renderer default.
color_scheme	str	The Material 3 role family the renderer paints the spinner's accent with — one of the design-system color schemes. The engine carries the prop; the renderer resolves the accent against the active theme (H4).

Stack

Bases: Widget

An overlapping container: children share one box, layered by z-order.

Unlike Column/Row (which lay children out along an axis), a Stack paints its children on top of one another in declaration order — the first child is the bottom layer, the last is on top. This is the framework's overlay primitive: a scrim, a modal card, a toast or a floating action button is just a later child of a Stack wrapping the page content.

Non-positioned children are aligned within the box by the stack's :attr:~tempestroid.style.Style.stack_align. A child whose style sets position = ABSOLUTE is anchored instead by its top/right/bottom/left insets (Flutter Positioned / CSS position: absolute); set both left and right (or top and bottom) to stretch it across that axis — a full-bleed scrim is position = ABSOLUTE with all four insets at 0.

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets, bottom layer first.

child_nodes()

Return the stack's children in z-order (bottom layer first).

Returns:

Type	Description
list[Widget]	The ordered child widgets.

StrokeCmd

Bases: BaseModel

Stroke the active path with a solid color and reset the path.

Attributes:

Name	Type	Description
kind	Literal['stroke']	The command discriminator ("stroke").
color	list[float]	The stroke color as an [r, g, b, a] list of floats in [0, 1] (a list, never a tuple).
width	float	The stroke width, in logical pixels.

SubmitEvent

Bases: Event

A form (or completable input) was submitted.

Carries the raw field values captured at submit time as a flat dict[str, str] — no nested models — so the payload is JSON-serializable.

Attributes:

Name	Type	Description
values	dict[str, str]	A mapping of field name to its raw string value at submit time.

Svg

Bases: Widget

A scalable vector graphic loaded from a URL or asset path.

Attributes:

Name	Type	Description
src	str	The SVG source — an http(s) URL or a bundled asset path.
fit	ImageFit	How the vector scales within its box.

SwipeDirection

Bases: StrEnum

The cardinal direction of a swipe gesture.

Attributes:

Name	Type	Description
LEFT		The pointer travelled predominantly toward the left edge of the screen (decreasing x).
RIGHT		The pointer travelled predominantly toward the right edge of the screen (increasing x).
UP		The pointer travelled predominantly toward the top of the screen (decreasing y).
DOWN		The pointer travelled predominantly toward the bottom of the screen (increasing y).

SwipeEvent

Bases: Event

A directional swipe (a press-drag-release past the distance threshold).

Attributes:

Name	Type	Description
direction	SwipeDirection	The dominant cardinal direction of the swipe.
dx	float	Total horizontal travel from press to release, in logical pixels.
dy	float	Total vertical travel from press to release, in logical pixels.

Switch

Bases: _SelectionWidget

A labelled on/off switch (toggle), styled via the H2 selection-variant API.

Distinct from :class:Checkbox only in its rendered affordance — both carry the same boolean semantics and the same accent resolution.

Attributes:

Name	Type	Description
label	str	The text shown beside the control.
checked	bool	Whether the switch is currently on.
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the accent paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	ToggleHandler | None	Handler invoked with a :class:ToggleEvent on toggle.

TabBar

Bases: Widget

A standalone tab strip: one selectable label per tab.

Emits a typed :class:~tempestroid.widgets.RouteChangeEvent when a tab is tapped, with the tapped index in params["index"]. Use it on its own to drive navigation, or let :class:TabView own one implicitly.

Attributes:

Name	Type	Description
tabs	list[str]	The ordered tab labels (paired by index across Qt/Compose).
active	int	The index of the currently selected tab.
on_change	RouteChangeHandler | None	Optional handler invoked with a RouteChangeEvent on a tap.

TabView

Bases: Widget

A tabbed host: a tab strip plus the active tab's content.

The view builds child for the active tab (typically from app.nav/active); tapping a tab fires on_change with a RouteChangeEvent carrying params["index"] so the handler can switch the active tab and rebuild a new child.

Attributes:

Name	Type	Description
tabs	list[str]	The ordered tab labels.
active	int	The index of the currently selected tab.
child	Widget	The content widget for the active tab.
on_change	RouteChangeHandler | None	Optional handler invoked with a RouteChangeEvent on a tap.

child_nodes()

Return the active tab's content as the single child.

Returns:

Type	Description
list[Widget]	A one-element list with the active tab's content.

TapEvent

Bases: Event

A tap/click on a widget.

Attributes:

Name	Type	Description
x	float | None	Optional x position of the tap, in logical pixels.
y	float | None	Optional y position of the tap, in logical pixels.

Text

Bases: Widget

A run of text.

Attributes:

Name	Type	Description
content	str	The string to display.

TextArea

Bases: _FieldWidget

A multi-line editable text field, styled via the H2 field-variant API.

Resolves its base :class:~tempest_core.style.Style from its field_variant / size / color_scheme against the theme like :class:Input; an explicit style is merged on top.

Attributes:

Name	Type	Description
value	str	The current text value.
placeholder	str	The hint shown when the field is empty.
rows	int	The number of visible text rows (initial height hint).
max_length	int | None	An optional cap on the number of characters.
field_variant	FieldVariant	The field treatment (outline/filled/flushed).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	TextChangeHandler | None	Handler invoked with a :class:TextChangeEvent on each edit.

TextChangeEvent

Bases: Event

A text input's value changed.

Attributes:

Name	Type	Description
value	str	The new text value.
valid	bool | None	Whether the value satisfies the input's pattern (regex), or None when the input declares no pattern. The renderer computes this against the widget's pattern before dispatch.

ThemeChangeEvent

Bases: Event

The active theme mode changed (e.g. the user toggled dark/light).

Not emitted by a widget handler: the host fires it when the OS color scheme changes (or app code requests a switch), and the bridge routes it over the reserved theme token ("__theme__") to App.set_theme.

Attributes:

Name	Type	Description
mode	ThemeMode	The new theme mode.

TimeChangeEvent

Bases: Event

A time picker's value changed.

Attributes:

Name	Type	Description
value	str	The new time as a 24-hour "HH:MM" string ("" when cleared).

TimePicker

Bases: _FieldWidget

A time selection field, styled via the H2 field-variant API (field trigger).

Attributes:

Name	Type	Description
value	str	The selected time as a 24-hour "HH:MM" string ("" if unset).
label	str	An optional label shown with the field.
field_variant	FieldVariant	The field treatment (outline/filled/flushed).
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map.
color_scheme	str	The Material 3 role family the focus tint paints with.
theme	Theme	The design-system theme whose tokens resolve the variant.
media	MediaQueryData | None	Optional viewport snapshot used to resolve a responsive size.
on_change	TimeChangeHandler | None	Handler invoked with a :class:TimeChangeEvent on selection.

Toast

Bases: Widget

A transient message that appears briefly then auto-dismisses.

The app's :meth:~tempestroid.core.state.App.toast schedules the auto-dismiss on the loop; duration_s is also carried to the renderer so a device can mirror the timing for snappy visual feedback.

Attributes:

Name	Type	Description
message	str	The text to display.
duration_s	float	How long the toast stays visible, in seconds.

ToggleEvent

Bases: Event

A checkbox/switch toggled.

Attributes:

Name	Type	Description
checked	bool	The new checked state.

Tooltip

Bases: Widget

A small hint label shown next to an anchored child.

Attributes:

Name	Type	Description
message	str	The hint text.
child	Widget | None	Optional widget the tooltip annotates.
color_scheme	str	The Material 3 role family the renderer paints the tooltip surface with — one of the design-system color schemes. The engine carries the prop; the renderer resolves the accent against the active theme (H4).

child_nodes()

Return the annotated child, if any.

Returns:

Type	Description
list[Widget]	A single-element list with the child, or an empty list.

ValidationEvent

Bases: Event

A single form field was validated.

Emitted by FormField when its validators run, so a handler can react to a per-field validation result without re-running the rules.

Attributes:

Name	Type	Description
field	str	The field's name.
value	str	The field's raw string value at validation time.
error	str | None	The validation message, or None when the field is valid.

VideoPlayer

Bases: Widget

An embedded video player.

Attributes:

Name	Type	Description
src	str	The video source — an http(s) URL or a bundled asset path.
autoplay	bool	Whether playback starts automatically when mounted.
loop	bool	Whether playback restarts when it reaches the end.
controls	bool	Whether the platform transport controls are shown.
muted	bool	Whether the audio track starts muted.

WebView

Bases: Widget

An embedded web view rendering a remote page.

Attributes:

Name	Type	Description
url	str	The page URL to load.
javascript_enabled	bool	Whether JavaScript execution is allowed.

Widget

Bases: BaseModel

Base class for every node in the declarative UI tree.

Attributes:

Name	Type	Description
key	str | None	Optional stable identity used by the reconciler to match nodes across rebuilds (analogous to a React key).
style	Style | None	Optional inline style for this node.
semantics	Semantics | None	Optional accessibility metadata for this node, propagated to both renderers and to :func:~tempestroid.introspect.
focusable	bool | None	Whether this node accepts focus. None keeps the widget's natural focusability (e.g. a button is focusable, a label is not).
focus_order	int | None	The node's explicit focus/tab order; None uses the natural traversal order.
tag	str | None	Semantic HTML tag override honored by the HTML/SSR renderer (e.g. "nav", "section", "article", "h1"); None lets the renderer pick its default element, and non-web renderers ignore it.
attrs	dict[str, str]	Arbitrary HTML attributes (hx-*, id, class, data-*, aria-*) honored by the HTML/SSR renderer; empty by default and ignored by non-web renderers.

widget_type property

The node's type tag, used by renderers and diffing.

Returns:

Type	Description
str	The concrete class name (e.g. "Text", "Column").

child_nodes()

Return this node's children in order.

Leaf widgets return an empty list. Container/layout widgets override this to expose their children, giving the reconciler a uniform way to walk any tree regardless of how children are stored.

Returns:

Type	Description
list[Widget]	The ordered child widgets (empty for leaf nodes).

Wrap

Bases: Widget

A flow-layout container: children wrap to the next line when a row fills.

Unlike Row (which keeps every child on a single line), a Wrap flows its children left-to-right and breaks onto a new line once the current line is full — the natural primitive for chips, tags or any free-flowing set of pills. Wrapping is controlled by :attr:~tempestroid.style.Style.flex_wrap; a Wrap wraps by default even when the caller leaves the field unset, since wrapping is the widget's whole purpose. The Compose renderer lowers it to FlowRow/FlowColumn and the Qt renderer realizes the flow imperatively (see the conformance suite).

Attributes:

Name	Type	Description
children	list[Widget]	The ordered child widgets, flowed and wrapped in order.

child_nodes()

Return the wrap's children in flow order.

Returns:

Type	Description
list[Widget]	The ordered child widgets.

confidence_scheme(conf, *, high=0.8, mid=0.5)

Map a confidence score to a status color_scheme.

The canonical traffic-light cue for a model's confidence: at or above high is "success" (green), at or above mid is "warning" (amber), and below mid is "error" (red). Pure and deterministic, so every confidence-driven component (badge, detection box) colors consistently.

Parameters:

Name	Type	Description	Default
conf	float	The confidence score, typically in [0, 1].	required
high	float	The inclusive threshold at or above which the score reads as high confidence ("success").	0.8
mid	float	The inclusive threshold at or above which the score reads as medium confidence ("warning"); below it reads as low ("error").	0.5

Returns:

Type	Description
str	One of "success" / "warning" / "error".

merge_style(base, override)

Overlay the set fields of override onto base.

Only fields explicitly set to a non-None value on override win; every other field keeps the component's default. Style is frozen, so this returns a fresh merged copy.

Parameters:

Name	Type	Description	Default
base	Style	The component's default style.	required
override	Style | None	The caller-supplied style, or None to keep the default.	required

Returns:

Type	Description
Style	The merged style (base unchanged when override is None).

build(widget)

Normalize a widget tree into an IR node tree.

A :class:Component is expanded first — replaced by the primitive tree its :meth:Component.render returns — so the IR (and therefore both renderers) only ever contains primitive widgets. Children come from :meth:Widget.child_nodes; everything else on the widget (except key and the declared child slots) becomes a prop.

Expanding a component would drop what the caller set on the component: the props in :data:CARRIED_PROPS describe the node, and the component is not a node. They are carried onto the root the component rendered — see :func:_carry_base_props — so Card(semantics=Semantics(label="Total")) names something instead of nothing.

Parameters:

Name	Type	Description	Default
widget	Widget	The root widget to normalize.	required

Returns:

Type	Description
Node	The root IR node.

build_scene(widget, overlays)

Build a full :class:Scene from a root widget plus an overlay layer.

Each overlay is given as a (id, widget, barrier) tuple: the id becomes the overlay node's stable key (so the keyed diff matches it across rebuilds), and barrier is recorded as a barrier prop on the overlay node so a renderer knows whether to draw a touch-blocking scrim.

Parameters:

Name	Type	Description	Default
widget	Widget	The root screen widget.	required
overlays	list[tuple[str, Widget, bool]]	The overlay layer, in ascending z-order, as (overlay_id, widget, barrier) tuples.	required

Returns:

Type	Description
Scene	The built scene (root node + overlay nodes).

diff(old, new)

Diff two IR node trees into an ordered list of patches.

Patches are ordered so a renderer can apply them sequentially: a node's own update/reorder precedes its descendants' patches, and within a child list removals run tail-first before insertions.

Parameters:

Name	Type	Description	Default
old	Node	The previously rendered tree.	required
new	Node	The freshly built tree.	required

Returns:

Type	Description
list[Patch]	The patches that transform old into new (empty if identical).

diff_scene(old, new)

Diff two scenes into an ordered patch list.

The root tree is diffed exactly as :func:diff does (paths unchanged, so every existing renderer consumer is unaffected). The overlay layer is diffed as a fully-keyed child list (each overlay's key is its stable id) under the reserved ("overlay",) path prefix, so overlay add/remove/reorder reuse the existing :class:Insert/:class:Remove/:class:Reorder/ :class:Update/:class:Replace patch kinds — no new patch kind is needed.

Parameters:

Name	Type	Description	Default
old	Scene	The previously rendered scene.	required
new	Scene	The freshly built scene.	required

Returns:

Type	Description
list[Patch]	The patches transforming old into new (empty if identical).

event_catalog()

Describe every event payload schema.

Returns:

Type	Description
dict[str, Any]	A mapping of event name to its JSON schema.

introspect()

Produce the full, JSON-serializable framework contract.

Returns:

Type	Description
dict[str, Any]	{"widgets": <widget catalog>, "events": <event catalog>}.

widget_catalog()

Describe every widget: its prop schema and the events it emits.

Returns:

Type	Description
dict[str, Any]	A mapping of widget name to ``{"schema": , "events":
dict[str, Any]	{handler_prop: event_type_name}}``.

resolve_device(name)

Resolve a user-supplied device name to a :class:Device preset.

Matching is forgiving: the enum member name or its human label, compared case-insensitively with -/_/spaces normalized away. So "pixel-7", "PIXEL_7", "pixel 7" and "Google Pixel 7" all resolve to :attr:Device.PIXEL_7.

Parameters:

Name	Type	Description	Default
name	str	The device identifier to resolve.	required

Returns:

Type	Description
Device | None	The matching :class:Device, or None when no preset matches.

translate(key, locale, translations, **kwargs)

Look up and interpolate a localized string.

Resolution order, by the locale's language: a translation table keyed by language ({"pt": {"hello": "Olá, {name}"}, "en": {...}}) is searched for locale.language; the matched string is then interpolated with kwargs via :meth:str.format. When the language or key is missing, key itself is returned (still interpolated when possible) so a missing translation degrades to the developer-facing key rather than raising.

Parameters:

Name	Type	Description	Default
key	str	The translation key to resolve.	required
locale	Locale	The active locale (its :attr:Locale.language selects the table).	required
translations	dict[str, dict[str, str]]	A {language: {key: template}} mapping.	required
**kwargs	str	Interpolation values applied to the resolved template.	{}

Returns:

Type	Description
str	The interpolated, localized string (or the interpolated key on miss).

icon_names()

Return the names of every available icon, sorted alphabetically.

Includes both the curated set and any custom icons registered via :func:register_icon.

Returns:

Type	Description
list[str]	A sorted list of available icon names (always a list, never raises).

icon_path(name)

Resolve an icon name to its single-path d string.

Parameters:

Name	Type	Description	Default
name	str	An :class:Icons member or a raw icon name string. As :class:Icons is a :class:~enum.StrEnum, both forms are accepted transparently.	required

Returns:

Type	Description
str | None	The icon's d string — from the curated set, then a custom icon
str | None	registered via :func:register_icon, then a Material-name alias in
str | None	data:MATERIAL_ALIASES resolved to its curated glyph — or None when
str | None	the name is unknown (the renderer then falls back to a platform icon /
str | None	the name).

register_icon(name, source=None, *, path=None)

Register a custom icon so it resolves like a curated one.

Provide either a raw path d string (path=) or an source SVG (file path or markup) that is converted via :func:svg_to_path. After registering, Icon(name=…) / an input's leading_icon/trailing_icon / :func:icon_path all resolve the name to this glyph. Re-registering the same name overwrites it.

Parameters:

Name	Type	Description	Default
name	str	The icon name to register (used as Icon(name=…)).	required
source	str | Path | None	An SVG file path or markup to convert. Mutually exclusive with path.	None
path	str | None	A ready normalized d string to register verbatim.	None

Returns:

Type	Description
str	The registered d string.

Raises:

Type	Description
ValueError	If neither or both of source/path are given, if the name collides with a curated icon, or the SVG has no shapes.

svg_to_path(source)

Convert an SVG image (file path or raw markup) into one d string.

Extracts every drawable shape (path/circle/ellipse/line/ rect/polyline/polygon) and flattens them into a single space-joined d string in the same shape the renderers stroke — so a project SVG becomes a tempestroid icon. The SVG should already be on a 24x24 viewBox (or a similar small grid) for the stroke width to look right.

Parameters:

Name	Type	Description	Default
source	str | Path	A path to an .svg file, or a raw SVG markup string.	required

Returns:

Type	Description
str	The combined path d string.

Raises:

Type	Description
ValueError	When the source has no usable shapes, or the markup / file cannot be parsed as XML.

routes_from_path(path)

Resolve a deep-link path into an initial navigation stack.

A deep link arrives as an intent extra on the device (or a launch argument in the simulator) and is resolved to the stack the app should open on. This is the device-independent half of the deep-link path: the entry point passes the resulting stack to :meth:~tempestroid.App.reset so the app opens directly on the linked screen with its back stack already built.

The path is split on "/" into cumulative segments, so "/a/b" opens the stack ["/", "/a", "/a/b"] — the user can pop back through the intermediate screens. The root "/" (or an empty path) yields the single root route, matching :class:NavStack's default.

Parameters:

Name	Type	Description	Default
path	str	The deep-link path (e.g. "/details" or "/shop/item").	required

Returns:

Type	Description
list[Route]	A non-empty list of routes from the root to the linked screen.

current_theme()

Return the theme of the view currently building.

Every themed component declares theme with this as its default factory, which is what makes an app's palette reach the tree without a single call site passing it down. The factory runs while the widget is constructed — that is, while the view runs — so :meth:use_theme only has to be installed around the view call.

Outside a build there is no app to ask, so this answers the Material baseline. That keeps a widget constructed in a test, a script or a REPL working exactly as before.

Returns:

Name	Type	Description
Theme	Theme	The active theme, or a baseline one outside a build.

use_theme(theme)

Run a block with theme as the one components default to.

Installed by :meth:~tempest_core.App._build around the view call. The variable is a :class:~contextvars.ContextVar, so concurrent apps — two server sessions building at the same time — never see each other's palette, and the token is reset on the way out even if the view raises.

Parameters:

Name	Type	Description	Default
theme	Theme	The palette for the tree about to be built.	required

Yields:

Name	Type	Description
None	None	Control, with the theme installed.

color_schemes_from_seed(seed, *, secondary_seed=None, tertiary_seed=None, error_seed=None, success_seed=None, warning_seed=None, info_seed=None)

Generate the light + dark Material 3 schemes from a brand seed color.

By default the secondary and tertiary key colors are derived by rotating the seed hue (M3 derives related palettes from one seed); a researcher can override any of them to hand-pick a brand accent. The neutral palette is the desaturated seed so surfaces carry a hint of the brand tint, as M3 does. The H4 status families (success / warning / info) use fixed semantic seeds (green / amber / blue) so a "success" surface reads green regardless of the brand hue, and are overridable like the error seed.

Parameters:

Name	Type	Description	Default
seed	Color	The primary brand/key color.	required
secondary_seed	Color | None	Override key color for the secondary palette; defaults to the seed hue rotated -60°.	None
tertiary_seed	Color | None	Override key color for the tertiary palette; defaults to the seed hue rotated +60°.	None
error_seed	Color | None	Override key color for the error palette; defaults to the Material 3 baseline red.	None
success_seed	Color | None	Override key color for the success palette (H4); defaults to :data:_DEFAULT_SUCCESS_SEED (green).	None
warning_seed	Color | None	Override key color for the warning palette (H4); defaults to :data:_DEFAULT_WARNING_SEED (amber).	None
info_seed	Color | None	Override key color for the info palette (H4); defaults to :data:_DEFAULT_INFO_SEED (blue).	None

Returns:

Type	Description
ColorSchemes	The light/dark scheme pair derived from the seed.

default_tokens()

Build the default Material 3 token set (the baseline M3 theme).

Seeded with the Material 3 reference purple so an app that sets no brand color still gets a complete, M3-faithful token set.

Returns:

Type	Description
TokenSet	The default token set.

tonal_palette_from_seed(seed)

Generate a Material 3 tonal palette from a seed/brand color.

The seed's hue and saturation are preserved while lightness is swept across the thirteen standard M3 tones; chroma is attenuated at the extremes. The result is deterministic for a given seed.

Parameters:

Name	Type	Description	Default
seed	Color	The key/brand color to derive the palette from.	required

Returns:

Type	Description
TonalPalette	The tonal palette sampling the seed's hue at every standard tone.

validate_cnpj(value)

Validate a Brazilian CNPJ number.

Strips mask characters, then checks for exactly 14 digits, rejects all-same-digit sequences, and verifies the two check digits using the standard CNPJ weights (5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2).

Pairs with :class:~tempestroid.components.CNPJInput.

Parameters:

Name	Type	Description	Default
value	Any	The raw CNPJ (e.g. "11.222.333/0001-81" or "11222333000181").	required

Returns:

Type	Description
str | None	A PT-BR error message when the CNPJ is invalid, or None when valid.

validate_cpf(value)

Validate a Brazilian CPF number.

Strips mask characters, then checks for exactly 11 digits, rejects all-same-digit sequences, and verifies the two mod-11 check digits.

Pairs with :class:~tempestroid.components.CPFInput.

Parameters:

Name	Type	Description	Default
value	Any	The raw CPF (e.g. "529.982.247-25" or "52998224725").	required

Returns:

Type	Description
str | None	A PT-BR error message when the CPF is invalid, or None when valid.

validate_email(value)

Validate an email address with a pragmatic regular expression.

Pairs with :class:~tempestroid.components.EmailInput.

Parameters:

Name	Type	Description	Default
value	Any	The raw email address.	required

Returns:

Type	Description
str | None	A PT-BR error message when the address is invalid, or None when
str | None	valid.

validate_phone(value)

Validate a Brazilian phone number.

Strips non-digits, then requires 10 digits (landline: DDD + 8-digit number) or 11 digits (mobile: DDD + leading 9 + 8-digit number).

Pairs with :class:~tempestroid.components.PhoneInput.

Parameters:

Name	Type	Description	Default
value	Any	The raw phone (e.g. "(11) 98765-4321" or "11987654321").	required

Returns:

Type	Description
str | None	A PT-BR error message when the number is invalid, or None when valid.

merge_styles(base, override)

Layer override over base and re-validate nested value objects.

Unlike :meth:~tempest_core.style.Style.merge (which updates via model_copy without re-validation, leaving a nested Color as a raw dict), this dumps both styles, overlays the override's set fields and validates once — so the resulting Style keeps properly-typed Color / Border / Edge values. Mirrors Theme.resolve_style's approach.

Parameters:

Name	Type	Description	Default
base	Style	The base style.	required
override	Style	The style whose set (non-None) fields win.	required

Returns:

Type	Description
Style	A new, fully-validated merged Style.

resolve_alert_variant(*, variant, color_scheme='info', theme, padding_step='md', radius_step='sm', platform_dark_mode=False, media=None)

Resolve an alert / banner's props into a Material 3 Style.

The H4 sibling of :func:resolve_surface_variant for the alert family (alert, banner). An alert is a non-interactive block-level status surface — there is no state parameter and no per-state table (like a surface):

• subtle fills with the tonal *_container role and its on_*_container content — the WCAG-AA-safe default;
• solid fills with the saturated role color and its on_* content;
• left_accent / top_accent are a subtle fill plus a thick directional :class:~tempest_core.style.SideBorder (4px) in the saturated role on the leading / top edge respectively. The renderers mirror the start/end side under RTL via their existing rtl flag (the same idiom as the field flushed bottom border).

Padding and radius come from the spacing / shape scales via the padding_step / radius_step token-step names. Pure and deterministic.

Parameters:

Name	Type	Description	Default
variant	AlertVariant	The alert treatment (subtle / solid / left_accent / top_accent).	required
color_scheme	str	The Material 3 role family to tint with — one of :data:VALID_COLOR_SCHEMES (default "info"; the H4 status families "success" / "warning" / "info" are the typical choices).	'info'
theme	Theme	The theme whose tokens supply colors, spacing and shape.	required
padding_step	str	The spacing-scale step name for the alert padding (default "md").	'md'
radius_step	str	The shape-scale step name for the corner radius (default "sm").	'sm'
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot (accepted for signature parity; an alert has no responsive size).	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested alert combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown.

resolve_badge_variant(*, variant, size, color_scheme, theme, state=ComponentState.DEFAULT, platform_dark_mode=False, media=None)

Resolve a badge / tag / chip's props into a Material 3 Style.

The H4 sibling of :func:resolve_variant for the badge family (badge, tag, chip). A badge is a compact, pill-shaped status label:

• solid fills with the role color and its legible on_* content;
• subtle fills with the tonal *_container role and its on_*_container content — the WCAG-AA-safe subtle look (a saturated status role on white can fail AA, see :func:_status_container_pair);
• outline is a transparent background with the role color as both content and a same-color border.

Padding is compact (:data:BADGE_DENSITY), the radius is the M3 full pill sentinel, and the font comes from a label-scale typography role. An optional interaction state layers a Material 3 state layer (for a tappable chip); a presentational badge resolves at DEFAULT. Pure and deterministic, like every resolver.

Parameters:

Name	Type	Description	Default
variant	BadgeVariant	The badge treatment (solid / subtle / outline).	required
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family to paint with — one of :data:VALID_COLOR_SCHEMES (incl. the H4 status families "success" / "warning" / "info").	required
theme	Theme	The theme whose tokens supply colors, spacing, shape and type.	required
state	ComponentState	The interaction state to resolve for (default :attr:~tempest_core.style.ComponentState.DEFAULT).	DEFAULT
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested badge combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_badge_variant_states(*, variant, size, color_scheme, theme, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a badge variant + size + scheme.

The H4 badge-family counterpart of :func:resolve_variant_states — the seam a tappable chip's renderer consumes to apply the matching state layer on real pointer/focus events.

Parameters:

Name	Type	Description	Default
variant	BadgeVariant	The badge treatment (solid / subtle / outline).	required
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_field_variant(*, variant, size, color_scheme, theme, state=ComponentState.DEFAULT, invalid=False, platform_dark_mode=False, media=None)

Resolve a text-field's Chakra-style props into a Material 3 Style.

The H2 sibling of :func:resolve_variant for the field family (text input, text area, select/dropdown, masked input, autocomplete, pin). A field is focus-led: the resting treatment is low-emphasis (outline / filled / flushed) and the color_scheme role only tints the focus border/caret/label. An invalid field forces the border + label to the error role in every state (it coexists with the field's separate error-message text, which the field widget renders elsewhere). Pure and deterministic, like every resolver.

Parameters:

Name	Type	Description	Default
variant	FieldVariant	The field treatment (outline / filled / flushed).	required
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family the focus tint paints with — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply colors, spacing, shape and type.	required
state	ComponentState	The interaction state to resolve for (default :attr:~tempest_core.style.ComponentState.DEFAULT).	DEFAULT
invalid	bool	Whether the field is in an invalid (error) state — forces the border/label to the error role.	False
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested field combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_field_variant_states(*, variant, size, color_scheme, theme, invalid=False, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a field variant + size + scheme.

The H2 field-family counterpart of :func:resolve_variant_states — the seam the renderers consume to apply the matching style on real focus/hover events.

Parameters:

Name	Type	Description	Default
variant	FieldVariant	The field treatment (outline / filled / flushed).	required
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
invalid	bool	Whether the field is in an invalid (error) state.	False
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_selection_variant(*, size, color_scheme, theme, state=ComponentState.DEFAULT, checked=False, platform_dark_mode=False, media=None)

Resolve a selection control's props into a Material 3 Style.

The H2 sibling of :func:resolve_variant for the selection family (checkbox, switch, radio row). Material 3 gives selection controls a single affordance each, so there is no variant param. The resolved style carries: the accent (color_scheme role) as color (the tick / on-track); background = the accent when checked else transparent (no fill); the outline role as the empty-ring border when unchecked; and the control box dimension (width == height) from :data:SELECTION_SIZE. The 48dp touch target is the parent row's job, never the box.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family the accent paints with — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply colors and the dimension.	required
state	ComponentState	The interaction state to resolve for.	DEFAULT
checked	bool	Whether the control is currently selected/on.	False
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested selection combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_selection_variant_states(*, size, color_scheme, theme, checked=False, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a selection control.

The H2 selection-family counterpart of :func:resolve_variant_states.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
checked	bool	Whether the control is currently selected/on.	False
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_size(size, theme, *, media=None)

Resolve a (possibly responsive) size prop to a concrete Size.

A bare :class:~tempest_core.style.Size resolves to itself. A per-breakpoint map is resolved mobile-first against the theme's :class:~tempest_core.tokens.Breakpoints and the optional viewport width from media: the entry for the widest breakpoint whose min-width the viewport meets wins, falling back to "base" (or the smallest provided entry) when no width context is available.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The size prop — a single Size or a {"base": …, "md": …} map.	required
theme	Theme	The theme whose breakpoints resolve the map.	required
media	MediaQueryData | None	The current viewport snapshot; when None (or width 0) the "base" entry is used.	None

Returns:

Type	Description
Size	The concrete Size for the current viewport.

Raises:

Type	Description
ValueError	If size is an empty map or names an unknown breakpoint.

resolve_slider_variant(*, size, color_scheme, theme, state=ComponentState.DEFAULT, platform_dark_mode=False, media=None)

Resolve a slider's props into a Material 3 Style.

The H2 sibling of :func:resolve_variant for the slider family (slider, range slider). Material 3 gives a slider a single affordance, so there is no variant param. The resolved style carries: the accent (color_scheme role) as color (the active track + thumb); the surface_variant role as background (the inactive track); the track thickness as height from :data:SLIDER_SIZE; and a thumb radius hint as radius (the M3 full pill). The thumb halo + 48dp touch target are the renderer's job, never the track height.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family the accent paints with — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply colors and the track thickness.	required
state	ComponentState	The interaction state to resolve for.	DEFAULT
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested slider combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_slider_variant_states(*, size, color_scheme, theme, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a slider.

The H2 slider-family counterpart of :func:resolve_variant_states.

Parameters:

Name	Type	Description	Default
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

resolve_surface_variant(*, variant, color_scheme='neutral', theme, elevation=None, padding_step='md', radius_step='md', platform_dark_mode=False, media=None)

Resolve a surface/card's Chakra-style props into a Material 3 Style.

The H3 sibling of :func:resolve_variant for the surface family (card, surface, panel, accordion header). A surface is non-interactive — there is no state parameter and no per-state table (D5): it simply chooses how the box is filled and whether it carries an elevation shadow (elevated), a tonal fill (filled) or a hairline outline (outlined). Every treatment paints onto existing :class:~tempest_core.style.Style fields, so no new field is introduced (D1): elevation is realized as a :class:~tempest_core.style.Shadow mapped from the M3 level, never an elevation style field.

The color_scheme tints the surface (D2): "neutral" uses the plain SURFACE / ON_SURFACE roles; a role family ("primary", …) uses the tonal *_container role as the background and its on_*_container role as the content. Padding and radius come from the spacing/shape scales via the padding_step / radius_step token-step names (D6). Pure and deterministic, like every resolver.

Parameters:

Name	Type	Description	Default
variant	CardVariant	The surface treatment (elevated / filled / outlined).	required
color_scheme	str	The Material 3 role family to tint with — one of :data:VALID_COLOR_SCHEMES (default "neutral").	'neutral'
theme	Theme	The theme whose tokens supply colors, spacing, shape and elevation.	required
elevation	int | None	An explicit Material 3 elevation level (0-5) overriding the variant default; None uses the per-variant default (elevated → level 1, filled/outlined → level 0).	None
padding_step	str	The spacing-scale step name for the surface padding (default "md").	'md'
radius_step	str	The shape-scale step name for the surface corner radius (default "md").	'md'
platform_dark_mode	bool	The OS dark-mode flag, used to resolve the scheme.	False
media	MediaQueryData | None	The current viewport snapshot (accepted for signature parity with the other resolvers; unused here as a surface has no responsive size).	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested surface combination.

Raises:

Type	Description
ValueError	If color_scheme is unknown or elevation is outside the 0-5 range.

resolve_variant(*, variant, size, color_scheme, theme, state=ComponentState.DEFAULT, platform_dark_mode=False, media=None)

Resolve Chakra-style variant props into a concrete Material 3 Style.

This is the heart of H1: a pure function that maps variant / size / color_scheme (+ an interaction state) onto a frozen :class:~tempest_core.style.Style, resolved against the theme's M3 tokens. It is renderer-agnostic and deterministic, so it is unit-tested exhaustively and pinned by the conformance suite. See the module docstring for the full variant→treatment, size→density and state→state-layer mapping.

Parameters:

Name	Type	Description	Default
variant	Variant	The visual treatment (solid/outline/ghost/link).	required
size	ResponsiveSize	The density size — a single :class:~tempest_core.style.Size or a per-breakpoint map resolved against the theme + media.	required
color_scheme	str	The Material 3 role family to paint with — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply colors, spacing, shape and type.	required
state	ComponentState	The interaction state to resolve for (default :attr:~tempest_core.style.ComponentState.DEFAULT).	DEFAULT
platform_dark_mode	bool	The OS dark-mode flag, used to resolve SYSTEM theme mode to the right color scheme.	False
media	MediaQueryData | None	The current viewport snapshot, used to resolve a responsive size map; None resolves to the "base" entry.	None

Returns:

Type	Description
Style	The resolved, frozen Style for the requested combination.

Raises:

Type	Description
ValueError	If color_scheme is not one of :data:VALID_COLOR_SCHEMES, or the responsive size map is malformed.

resolve_variant_states(*, variant, size, color_scheme, theme, platform_dark_mode=False, media=None)

Resolve the full per-state style table for a variant + size + scheme.

This is the seam the renderers consume: a styled component asks for every interaction state up front (default/hover/pressed/disabled/ focus) and hands the table to the renderer, which applies the matching style on real pointer/focus events (Qt QSS pseudo-states; Compose InteractionSource / Material3 state layers). The resolution stays pure and in the engine; only the event→state mapping lives in the renderers.

Parameters:

Name	Type	Description	Default
variant	Variant	The visual treatment.	required
size	ResponsiveSize	The density size (single or responsive map).	required
color_scheme	str	The Material 3 role family — one of :data:VALID_COLOR_SCHEMES.	required
theme	Theme	The theme whose tokens supply the values.	required
platform_dark_mode	bool	The OS dark-mode flag.	False
media	MediaQueryData | None	The current viewport snapshot for a responsive size.	None

Returns:

Type	Description
dict[ComponentState, Style]	A mapping of every :class:~tempest_core.style.ComponentState to its
dict[ComponentState, Style]	resolved Style.

Raises:

Type	Description
ValueError	If color_scheme is unknown or the size map is malformed.

handler_accepts_event(handler)

Whether handler accepts a positional event argument.

Value-bearing widgets pass the validated typed event to their handler, but only when the handler is declared to accept one — a zero-argument handler is called bare. Both the device bridge registry and the Qt renderer use this to agree on the calling convention.

Parameters:

Name	Type	Description	Default
handler	Callable[..., Any]	The handler callable to inspect.	required

Returns:

Type	Description
bool	True if the handler can take one positional argument, False if it
bool	must be called with none (or its signature cannot be inspected).

parse_event(event_type, raw)

Validate a raw payload into a typed event.

This is the boundary gate: native code sends an untyped mapping, and only a valid payload becomes a typed event the handler can trust.

Parameters:

Name	Type	Description	Default
event_type	type[E]	The expected event type.	required
raw	Mapping[str, Any]	The raw payload from the native boundary.	required

Returns:

Type	Description
E	The validated, typed event.

Raises:

Type	Description
EventValidationError	If the payload does not match event_type, with the structured field errors attached.