Skip to content

Package

wybthon (package)

Top-level Wybthon package API and browser/runtime detection.

This module exposes the public surface area for both browser (Pyodide) and non-browser environments, importing DOM/VDOM features only when available.

BaseComponent

Bases: ABC

Async component base that renders to a concrete DOM Element.

render() abstractmethod async

Render this component and return its root Element.

render_children(parent) async

Render and append all child components to the given parent element.

Component

Class component base for the VDOM renderer.

Subclasses should implement render(self) -> VNode. Lifecycle hooks: - on_mount(self) - on_update(self, prev_props: dict) - on_unmount(self)

add_cleanup(fn)

Register a cleanup callback to run on unmount.

on_mount()

Called after the component is first mounted.

on_unmount()

Called before the component is removed from the DOM.

on_update(prev_props)

Called after props update and render diff applied.

Context dataclass

Opaque context identifier and default value container.

DomEvent

Thin wrapper around a JS event with convenience helpers.

prevent_default()

Prevent the default browser action for this event, if possible.

stop_propagation()

Stop propagation through the delegated listener chain.

Element

Thin wrapper around a DOM node with convenience methods.

add_class(*class_names)

Add one or more CSS classes to this element.

append(child)

Append a child Element or a text node to this element.

append_to(parent)

Append this element to the given parent element.

attach_ref(ref)

Attach this element to a mutable Ref container.

cleanup()

Remove all tracked event listeners from this element.

find(selector)

Find the first matching descendant by CSS selector.

find_all(selector)

Find all matching descendants by CSS selector.

get_attr(name)

Return attribute value or None when missing.

has_class(class_name)

Return True if the element currently has the given class.

load_html(url) async

Fetch HTML from url and set as innerHTML of this element.

off(event_type=None, handler=None)

Remove matching event listeners previously attached via on().

on(event_type, handler, *, options=None)

Add an event listener and track it for cleanup.

query(selector, within=None) classmethod

Query a single element by CSS selector, optionally within a parent.

query_all(selector, within=None) classmethod

Query all matching elements by CSS selector, optionally within a parent.

remove()

Remove this element from its parent if attached.

remove_attr(name)

Remove an attribute from this element.

remove_class(*class_names)

Remove one or more CSS classes from this element.

set_attr(name, value)

Set an attribute on this element, with text-node fallbacks.

set_html(html)

Set the innerHTML of this element to the provided HTML string.

set_style(styles=None, **style_kwargs)

Set CSS properties using a dict and/or keyword arguments.

set_text(text)

Set text content for this element.

toggle_class(class_name, force=None)

Toggle a CSS class, optionally forcing on/off.

ErrorBoundary

Bases: Component

Component that catches errors in its subtree and renders a fallback.

reset()

Clear the current error and re-render children.

FieldState dataclass

Signals representing a field's value, error message, and touched state.

Provider

Bases: Component if Component is not None else object

Context provider component.

Props
  • context: Context
  • value: Any
  • children: VNode or list of VNodes

render()

Render passthrough children; VDOM manages push/pop of context value.

Ref

Mutable container holding a reference to an Element.

Resource

Bases: Generic[R]

Async resource wrapper with Signals for data, error, and loading.

Use reload() to (re)fetch, cancel() to cancel the in-flight request.

Route dataclass

Declarative route definition mapping a path to a component.

Router

Bases: Component

render()

Render the matched route's component or a not-found view.

Suspense

Bases: Component

Render a fallback while one or more resources are loading.

Props
  • resources | resource: Resource or list of Resources (objects exposing .loading.get())
  • fallback: VNode | str | callable returning VNode/str
  • keep_previous: bool (default False) – when True, keep children visible after first successful load even if a subsequent reload is in-flight.

VNode dataclass

Virtual node representing an element, text, or component subtree.

Anchor element component that navigates via history API without reloads.

a11y_control_attrs(field, *, described_by_id=None)

Return ARIA attributes for an input/select control bound to the field.

  • aria-invalid is set to "true" when there's an error, else "false".
  • aria-describedby includes the provided error element id when an error exists.

batch()

Batch signal updates within the returned context manager.

bind_checkbox(field)

Bind a checkbox input to a boolean field.

bind_select(field)

Bind a select element to a field, updating value on change.

bind_text(field, *, validators=None)

Bind a text input to a field with validation on input events.

computed(fn)

Create a computed value that derives from other signals.

create_context(default)

Create a new Context with a unique identifier and default value.

effect(fn)

Run a reactive effect and return its computation handle.

email(message='Invalid email address')

Validate a basic email address format (lightweight regex).

error_message_attrs(*, id)

Return attributes for an error message container.

Use with a live region to announce validation errors to assistive tech.

form_state(initial)

Create a form state map from initial values using Signals.

h(tag, props=None, *children)

Create a VNode from a tag, props, and children (component-aware).

load_component(module_path, attr=None)

Dynamically import a module (optionally attribute) and return a function component factory.

The returned function component will render a small loader until the module is imported. On success it will render the loaded component with the same props. On error, it renders a minimal error text.

This utility is Pyodide-friendly: it uses Python's import system, which is compatible with packages pre-bundled or fetched via micropip. Use preload_component to warm the cache.

max_length(n, message=None)

Validate that stringified value length is at most n.

min_length(n, message=None)

Validate that stringified value length is at least n.

navigate(path, *, replace=False)

Programmatically change the current path and update current_path.

on_effect_cleanup(comp, fn)

Register a cleanup callback to run when a computation is disposed.

on_submit(handler, form)

Create a submit handler that prevents default and calls the handler.

on_submit_validated(rules, handler, form)

Submit handler that validates the whole form before invoking handler.

Prevents the default submit, validates via validate_form, and calls handler(form) only when the form is valid.

preload_component(module_path, attr=None)

Eagerly import a component to warm caches before navigation.

render(vnode, container)

Render a VNode tree into a container Element or CSS selector.

required(message='This field is required')

Validate that a value is present and non-empty.

rules_from_schema(schema)

Build a validators map from a simple, lightweight schema.

Supported keys per field: - required: bool or str (if str, used as custom message) - min_length: int (optional custom message via min_length_message) - max_length: int (optional custom message via max_length_message) - email: bool or str (if str, used as custom message)

Example

{ "name": {"required": True, "min_length": 2}, "email": {"email": True}, }

signal(value)

Create a new Signal with the given initial value.

use_context(ctx)

Read the current value for ctx, or its default if not provided.

use_resource(fetcher)

Create an async Resource with loading/error states and cancellation.

The provided fetcher should be an async function returning the data value. If it accepts a signal keyword argument, an AbortSignal will be passed for cancellation support when available.

validate(value, validators)

Return first validation error or None when all validators pass.

validate_field(field, validators=None)

Validate a single field and update its error/touched signals.

Returns the error message if any, else None.

validate_form(form, rules)

Validate all fields in a form against a rules map.

Mutates each field's touched and error signals. Returns (is_valid, errors_map).

Public API (top-level imports)

  • Core rendering
  • Element, Ref
  • VNode, h, render
  • Components
  • Component, ErrorBoundary, Suspense
  • Reactivity
  • signal, computed, effect, batch, on_effect_cleanup
  • Resource, use_resource
  • Context
  • Context, create_context, use_context, Provider
  • Router
  • Route, Router, Link, navigate, current_path
  • Forms
  • State and validation: FieldState, form_state, validate, validate_field, validate_form
  • Validators: required, min_length, max_length, email
  • Bindings and submit helpers: bind_text, bind_checkbox, bind_select, on_submit, on_submit_validated
  • A11y helpers: a11y_control_attrs, error_message_attrs
  • Events
  • DomEvent
  • Lazy loading
  • lazy, load_component, preload_component

Note: DOM/VDOM-related symbols (e.g., Element, h, render, Component, router) require a Pyodide/browser environment. In non-browser contexts, only reactivity, forms, and lazy utilities are available.