tempestweb 0.5.2__tar.gz → 0.6.0__tar.gz

{tempestweb-0.5.2 → tempestweb-0.6.0}/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to **tempestweb** are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/); this project adheres to semantic
 versioning.
 
+## [0.6.0] — 2026-06-13
+
+### Added
+
+- **Always-on Material 3 base stylesheet.** The web client now ships a small
+  always-on MD3 base theme (`client/theme.js`), keyed off `data-tw-type`, so
+  apps get sensible typography, spacing and accented controls out of the box —
+  no per-widget styling required. Inline widget `Style` still overrides it.
+- **`Style.shadow` renders as `box-shadow` on the web.** Elevation set on a
+  widget's `Style` now emits a real CSS `box-shadow`, matching the native
+  renderers.
+- **MD3 field and button variants.** The pre-built components (`fields`,
+  `buttons`) gained light Material 3 variants (filled/outlined/text buttons,
+  themed text fields) so forms look finished without hand-styling.
+
+### Fixed
+
+- **Checkbox MD3 theming targets the nested input.** Following the Checkbox
+  `<label><input>` structure (0.5.3), the base theme sizes/accents the nested
+  `[data-tw-type="Checkbox"] > input` rather than the keyed `<label>` wrapper,
+  so the box is styled without shrinking the whole caption row.
+
+## [0.5.3] — 2026-06-13
+
+### Fixed
+
+- **`Checkbox` now renders its label as visible text on the web.** The DOM
+  renderer mapped `Checkbox` to a bare `<input type=checkbox>` and put its
+  `label` on `aria-label` only, so labelled checkboxes (todo items, settings
+  toggles) showed as empty boxes. A `Checkbox` now renders as a `<label>`
+  wrapping the real `<input>` plus a caption text node: the box and its caption
+  lay out as one tidy row (the wrapper also gives the input its accessible name
+  natively). The `<label>` is the keyed, path-addressed element; the nested
+  input carries `checked` and fires `change`, which bubbles to the label for
+  event delegation. An explicit widget `Style` still wins.
+
+### Examples
+
+- **Fixed three examples that passed `children=` to `Container`.** `Container`
+  holds a single `child`, not a `children` list (that is `Column`/`Row`/`Stack`).
+  Pydantic silently dropped the unknown kwarg, so the container rendered empty:
+  `list_demo` lost its row text (1000-item list showed blank rows), `gesture_demo`
+  lost its "swipe or tap me" hint, and `anim_demo` carried a no-op `children=[]`.
+
 ## [0.5.2] — 2026-06-13
 
 ### Changed

{tempestweb-0.5.2 → tempestweb-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempestweb
-Version: 0.5.2
+Version: 0.6.0
 Summary: Build web apps in typed Python — one tree, a DOM renderer, two execution modes (WASM + server).
 Author-email: Mauricio Benjamin <mauricio.benjamin@reloverelations.com>
 License: MIT
@@ -60,6 +60,12 @@ demos (stopwatch, forms, data table, kanban, chat, theming, i18n, canvas, native
 capabilities, observability, PWA/WebPush, and a server-mode walkthrough), each
 running unchanged in both modes.
 
+Building something real? Read the **[App architecture & best practices](https://mauriciobenjamin700.github.io/tempestweb/best-practices/)**
+guide ([EN](https://mauriciobenjamin700.github.io/tempestweb/en/best-practices/)) —
+the ideal layered structure (routes · pages · components · styles · controllers ·
+services · storages · schemas · utils · core), mirroring `tempest-fastapi-sdk`, so
+your app doesn't rot into garbage code.
+
 ## How it works
 
 ```text

{tempestweb-0.5.2 → tempestweb-0.6.0}/README.md

@@ -32,6 +32,12 @@ demos (stopwatch, forms, data table, kanban, chat, theming, i18n, canvas, native
 capabilities, observability, PWA/WebPush, and a server-mode walkthrough), each
 running unchanged in both modes.
 
+Building something real? Read the **[App architecture & best practices](https://mauriciobenjamin700.github.io/tempestweb/best-practices/)**
+guide ([EN](https://mauriciobenjamin700.github.io/tempestweb/en/best-practices/)) —
+the ideal layered structure (routes · pages · components · styles · controllers ·
+services · storages · schemas · utils · core), mirroring `tempest-fastapi-sdk`, so
+your app doesn't rot into garbage code.
+
 ## How it works
 
 ```text

{tempestweb-0.5.2 → tempestweb-0.6.0}/client/constants.js

@@ -15,3 +15,6 @@ export const GESTURE_TYPE = "GestureDetector";
 
 /** Id of the injected stylesheet that carries virtualized-list spacer heights. */
 export const VIRT_STYLE_ID = "tw-virt-styles";
+
+/** Id of the injected stylesheet that carries the always-on MD3 base theme. */
+export const BASE_THEME_STYLE_ID = "tw-base-theme";

{tempestweb-0.5.2 → tempestweb-0.6.0}/client/dom.js

@@ -32,7 +32,12 @@ const TAG_BY_TYPE = Object.freeze({
   Text: "span",
   Button: "button",
   Input: "input",
-  Checkbox: "input",
+  // A Checkbox renders as a <label> wrapping a real <input type=checkbox> plus
+  // its caption text, so the box and its label show side by side and the input
+  // gets its accessible name natively. The <label> is the keyed, path-addressed
+  // element; the input it wraps is renderer-internal (Checkbox is an IR leaf, so
+  // no patch path ever descends into it).
+  Checkbox: "label",
   Image: "img",
 });
 
@@ -89,14 +94,15 @@ function applyProps(el, props) {
       el.removeAttribute("style");
     }
   }
-  // Text-bearing props. A Checkbox is an <input> and cannot hold text, so its
-  // label rides as an accessible name instead of textContent.
+  // Text-bearing props. A Checkbox is a <label> wrapping an <input>, so its
+  // caption is set as a trailing text node (see setCheckboxLabel) rather than
+  // overwriting textContent, which would drop the nested input.
   if ("content" in props) {
     el.textContent = props.content == null ? "" : String(props.content);
   }
   if ("label" in props) {
     if (type === "Checkbox") {
-      el.setAttribute("aria-label", props.label == null ? "" : String(props.label));
+      setCheckboxLabel(el, props.label == null ? "" : String(props.label));
     } else {
       el.textContent = props.label == null ? "" : String(props.label);
     }
@@ -188,6 +194,46 @@ function applyLazyProps(el, type, props) {
   el.setAttribute("data-tw-window-start", String(start ?? 0));
 }
 
+/**
+ * Get (or lazily create) the real ``<input type=checkbox>`` nested inside a
+ * Checkbox's ``<label>`` wrapper. The label is the keyed, path-addressed
+ * element; this nested input carries the actual ``checked`` state and fires the
+ * native ``change`` event (which bubbles up to the keyed label for delegation).
+ *
+ * @param {HTMLElement} el  The Checkbox ``<label>`` element.
+ * @returns {HTMLInputElement}  The nested checkbox input.
+ */
+function ensureCheckboxInput(el) {
+  let input = /** @type {HTMLInputElement|null} */ (el.querySelector("input"));
+  if (input == null) {
+    input = /** @type {HTMLInputElement} */ (document.createElement("input"));
+    input.setAttribute("type", "checkbox");
+    el.insertBefore(input, el.firstChild);
+  }
+  return input;
+}
+
+/**
+ * Set a Checkbox's visible caption, kept as a single text node after the nested
+ * input so the box and its label render side by side. Wrapping the input in the
+ * ``<label>`` also gives it its accessible name natively (no ``aria-label``).
+ *
+ * @param {HTMLElement} el    The Checkbox ``<label>`` element.
+ * @param {string} text       The caption text (``""`` clears it).
+ * @returns {void}
+ */
+function setCheckboxLabel(el, text) {
+  const input = ensureCheckboxInput(el);
+  for (const node of Array.from(el.childNodes)) {
+    if (node !== input) {
+      el.removeChild(node);
+    }
+  }
+  if (text) {
+    el.appendChild(document.createTextNode(text));
+  }
+}
+
 function applyControlProps(el, type, props) {
   if (type === "Input") {
     el.setAttribute("type", props.secure ? "password" : "text");
@@ -201,9 +247,29 @@ function applyControlProps(el, type, props) {
       el.setAttribute("maxlength", String(props.max_length));
     }
   } else if (type === "Checkbox") {
-    el.setAttribute("type", "checkbox");
+    const input = ensureCheckboxInput(el);
     if ("checked" in props) {
-      el.checked = Boolean(props.checked);
+      input.checked = Boolean(props.checked);
+    }
+    // Lay the box and caption out on one line, as a block-level row so stacked
+    // checkboxes each get their own line (an inline default would let adjacent
+    // labels flow together in a non-flex parent). Defaults only — an explicit
+    // Style on the widget (applied just before this) wins. Re-applied here on
+    // every update because a `style` patch resets the element's inline cssText.
+    if (!el.style.display) {
+      el.style.display = "flex";
+    }
+    if (!el.style.alignItems) {
+      el.style.alignItems = "center";
+    }
+    if (!el.style.gap) {
+      el.style.gap = "0.4em";
+    }
+    // Size to the box + caption. Without this the <label>, as a flex item of a
+    // column, collapses to the input's width and the caption overflows onto the
+    // next row; fit-content keeps it a tidy one-line row instead of stretching.
+    if (!el.style.width) {
+      el.style.width = "fit-content";
     }
   } else if (type === "Image") {
     if ("src" in props && props.src != null) {
@@ -263,6 +329,8 @@ function applyUpdate(root, patch) {
   for (const key of patch.unset_props ?? []) {
     if (key === "style") {
       el.removeAttribute("style");
+    } else if (key === "label" && el.getAttribute(TYPE_ATTR) === "Checkbox") {
+      setCheckboxLabel(el, "");
     } else if (key === "content" || key === "label") {
       el.textContent = "";
     }

{tempestweb-0.5.2 → tempestweb-0.6.0}/client/style.js

@@ -48,6 +48,14 @@
  * @property {number} bottom_left   Bottom-left radius, px.
  */
 
+/**
+ * @typedef {Object} ShadowDump
+ * @property {?ColorDump} color  The shadow color, or null for a default tint.
+ * @property {number} blur       The blur radius, px.
+ * @property {number} offset_x   The horizontal offset, px.
+ * @property {number} offset_y   The vertical offset, px.
+ */
+
 /**
  * @typedef {Object} GradientStopDump
  * @property {ColorDump} color  The stop color.
@@ -230,6 +238,20 @@ const CURVE_CSS = Object.freeze({
   elastic: "cubic-bezier(0.68, -0.6, 0.32, 1.6)",
 });
 
+/**
+ * Render a serialized Shadow as a CSS `box-shadow` value.
+ *
+ * `offset_x offset_y blur color`. A null shadow color falls back to a neutral
+ * translucent black so an elevation set without an explicit tint still reads.
+ *
+ * @param {ShadowDump} shadow  The shadow dump.
+ * @returns {string}           The CSS `box-shadow` value.
+ */
+function shadowToCss(shadow) {
+  const color = shadow.color ? colorToRgba(shadow.color) : "rgba(0, 0, 0, 0.3)";
+  return `${shadow.offset_x}px ${shadow.offset_y}px ${shadow.blur}px ${color}`;
+}
+
 /**
  * Translate a serialized Transition into a CSS `transition` shorthand.
  * @param {{duration_ms:number, curve:string, delay_ms:number}} transition
@@ -317,6 +339,9 @@ export function styleToCss(style, type) {
   if (style.opacity != null) {
     rules.push(`opacity: ${style.opacity}`);
   }
+  if (style.shadow != null) {
+    rules.push(`box-shadow: ${shadowToCss(style.shadow)}`);
+  }
 
   // Typography.
   if (style.font_family != null) {

{tempestweb-0.5.2 → tempestweb-0.6.0}/client/tempestweb.js

@@ -9,6 +9,7 @@
 import { applyPatches, buildElement } from "./dom.js";
 import { bindEvents } from "./events.js";
 import { installRouter } from "./router.js";
+import { installBaseTheme } from "./theme.js";
 import { installVirtualization } from "./virtualize.js";
 
 /**
@@ -48,6 +49,11 @@ import { installVirtualization } from "./virtualize.js";
  * @returns {MountHandle}     A handle to unmount the app.
  */
 export function mount(root, transport, initialNode = null) {
+  // Modern look for every app: inject the MD3 base stylesheet once. It styles
+  // bare widgets (Button/Input/Checkbox) and their interaction states; an app's
+  // inline Style still overrides it (see theme.js).
+  installBaseTheme();
+
   /** @type {HTMLElement | null} */
   let tree = null;
   if (initialNode != null) {

tempestweb-0.6.0/client/theme.js

@@ -0,0 +1,190 @@
+// theme.js — the always-on Material 3 base stylesheet.  UI MODERNIZATION.
+//
+// Core widgets render with no intrinsic visual style (a Button is a bare
+// <button>), so unstyled apps fall back to the browser's ugly chrome defaults.
+// This module injects ONE base stylesheet — once, at mount — that gives every
+// widget a modern Material 3 look: filled buttons with state layers + elevation,
+// outlined text fields, themed checkboxes, smooth focus rings.
+//
+// Why a stylesheet and not inline Style: inline CSS cannot express :hover,
+// :focus-visible, :active or :disabled — the very states that make a control feel
+// modern. Those live here, keyed off the `data-tw-type` attribute dom.js stamps on
+// every element.
+//
+// Override order: an app's inline Style (emitted by style.js onto the element's
+// `style` attribute) ALWAYS wins over this sheet — inline declarations beat a
+// stylesheet rule of equal-or-lower specificity, and nothing here uses
+// `!important`. So the base is a floor, not a cage: set `background`/`radius`/etc.
+// on a widget's Style and your value takes over while the interaction states stay.
+//
+// Tokens are CSS custom properties on :root, so an app can rebrand the whole UI by
+// overriding e.g. `--tw-primary` from its own <style> without touching this file.
+
+import { BASE_THEME_STYLE_ID as STYLE_ID } from "./constants.js";
+
+/**
+ * The Material 3 base theme CSS, exported so tests can assert its content
+ * without a live DOM. Tokens (`--tw-*`) are overridable by the app.
+ * @type {string}
+ */
+export const BASE_THEME_CSS = `
+:root {
+  /* Material 3 baseline palette (light scheme). Override any of these from the
+     app to rebrand: e.g. \`:root { --tw-primary: #0b57d0; }\`. */
+  --tw-primary: #6750a4;
+  --tw-on-primary: #ffffff;
+  --tw-primary-container: #eaddff;
+  --tw-on-primary-container: #21005d;
+  --tw-secondary-container: #e8def8;
+  --tw-on-secondary-container: #1d192b;
+  --tw-surface: #fef7ff;
+  --tw-on-surface: #1d1b20;
+  --tw-on-surface-variant: #49454f;
+  --tw-outline: #79747e;
+  --tw-error: #b3261e;
+
+  /* MD3 elevation levels (umbra + penumbra). */
+  --tw-elevation-1: 0 1px 2px rgba(0,0,0,0.30), 0 1px 3px 1px rgba(0,0,0,0.15);
+  --tw-elevation-2: 0 1px 2px rgba(0,0,0,0.30), 0 2px 6px 2px rgba(0,0,0,0.15);
+
+  --tw-radius-full: 9999px;
+  --tw-font: "Roboto", "Segoe UI", system-ui, -apple-system, sans-serif;
+  --tw-motion: 180ms cubic-bezier(0.2, 0, 0, 1);
+}
+
+/* Sensible page baseline so apps don't sit on Times New Roman. */
+[data-tw-type] { box-sizing: border-box; }
+
+/* ── Button: MD3 filled button ─────────────────────────────────────────────
+   A pill-shaped filled button with an interaction state layer (::before) and
+   elevation on hover. The state layer is the MD3 way to show hover/focus/press:
+   a translucent overlay of the on-color tinting the surface. */
+[data-tw-type="Button"] {
+  position: relative;
+  overflow: hidden;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  min-height: 40px;
+  padding: 10px 24px;
+  border: none;
+  border-radius: var(--tw-radius-full);
+  background: var(--tw-primary);
+  color: var(--tw-on-primary);
+  font-family: var(--tw-font);
+  font-size: 14px;
+  font-weight: 500;
+  letter-spacing: 0.1px;
+  line-height: 20px;
+  cursor: pointer;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+  transition: box-shadow var(--tw-motion), background var(--tw-motion);
+}
+/* The state layer: an overlay tinted with the foreground color, invisible at
+   rest and fading in for hover (8%) / focus & press (12%) per MD3 specs. */
+[data-tw-type="Button"]::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: currentColor;
+  opacity: 0;
+  transition: opacity var(--tw-motion);
+  pointer-events: none;
+}
+/* State-layer overlay — universal, correct for every button variant. */
+[data-tw-type="Button"]:hover::before { opacity: 0.08; }
+[data-tw-type="Button"]:focus-visible { outline: none; }
+[data-tw-type="Button"]:focus-visible::before { opacity: 0.12; }
+[data-tw-type="Button"]:active::before { opacity: 0.12; }
+/* Elevation — only the default filled button (no app-set inline background).
+   A variant that sets its own \`background\` (tonal/outlined/text/elevated) opts
+   out of this and controls its own shadow via inline Style. */
+[data-tw-type="Button"]:not([style*="background"]):hover { box-shadow: var(--tw-elevation-1); }
+[data-tw-type="Button"]:not([style*="background"]):active { box-shadow: var(--tw-elevation-2); }
+[data-tw-type="Button"]:not([style*="background"]):focus-visible { box-shadow: var(--tw-elevation-1); }
+[data-tw-type="Button"]:disabled,
+[data-tw-type="Button"][aria-disabled="true"] {
+  background: rgba(29,27,32,0.12);
+  color: rgba(29,27,32,0.38);
+  box-shadow: none;
+  cursor: default;
+}
+[data-tw-type="Button"]:disabled::before { opacity: 0; }
+
+/* ── Input: MD3 outlined text field ────────────────────────────────────────
+   A rounded, outlined field whose border thickens and recolors to the primary
+   tone on focus. */
+[data-tw-type="Input"] {
+  min-height: 40px;
+  padding: 9px 16px;
+  border: 1px solid var(--tw-outline);
+  border-radius: 8px;
+  background: var(--tw-surface);
+  color: var(--tw-on-surface);
+  font-family: var(--tw-font);
+  font-size: 16px;
+  line-height: 22px;
+  transition: border-color var(--tw-motion), box-shadow var(--tw-motion);
+}
+[data-tw-type="Input"]::placeholder { color: var(--tw-on-surface-variant); }
+[data-tw-type="Input"]:hover { border-color: var(--tw-on-surface); }
+[data-tw-type="Input"]:focus,
+[data-tw-type="Input"]:focus-visible {
+  outline: none;
+  border-color: var(--tw-primary);
+  box-shadow: inset 0 0 0 1px var(--tw-primary);
+}
+[data-tw-type="Input"]:disabled {
+  border-color: rgba(29,27,32,0.12);
+  color: rgba(29,27,32,0.38);
+}
+
+/* ── Checkbox: a <label> wrapping the real <input type=checkbox> ─────────────
+   dom.js renders a Checkbox as a keyed <label> with the caption text and lays
+   the row out inline (display/gap/align/width), so the base only sets the
+   caption type ramp + cursor on the label and themes the nested box itself. */
+[data-tw-type="Checkbox"] {
+  cursor: pointer;
+  font-family: var(--tw-font);
+  font-size: 14px;
+  color: var(--tw-on-surface);
+}
+[data-tw-type="Checkbox"] > input {
+  width: 18px;
+  height: 18px;
+  margin: 0;
+  accent-color: var(--tw-primary);
+  cursor: pointer;
+}
+
+/* ── Text: inherit the modern font instead of the UA serif default ─────────── */
+[data-tw-type="Text"] { font-family: var(--tw-font); }
+`;
+
+/**
+ * Inject the Material 3 base stylesheet into the document head, once.
+ *
+ * Idempotent: if a sheet with {@link BASE_THEME_STYLE_ID} already exists (a
+ * previous mount, or the page provided its own) it is left untouched. A no-op
+ * when there is no `document` (e.g. a non-DOM test harness).
+ *
+ * @returns {?HTMLStyleElement}  The injected (or pre-existing) style element, or
+ *                               `null` when no document is available.
+ */
+export function installBaseTheme() {
+  if (typeof document === "undefined") {
+    return null;
+  }
+  const existing = document.getElementById(STYLE_ID);
+  if (existing != null) {
+    return /** @type {HTMLStyleElement} */ (existing);
+  }
+  const el = document.createElement("style");
+  el.id = STYLE_ID;
+  el.textContent = BASE_THEME_CSS;
+  // Prepend so app- and inline-styles declared later still win the cascade.
+  document.head.insertBefore(el, document.head.firstChild);
+  return el;
+}

{tempestweb-0.5.2 → tempestweb-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempestweb"
-version = "0.5.2"
+version = "0.6.0"
 description = "Build web apps in typed Python — one tree, a DOM renderer, two execution modes (WASM + server)."
 readme = "README.md"
 requires-python = ">=3.11"

{tempestweb-0.5.2 → tempestweb-0.6.0}/tempestweb/cli/commands/build.py

@@ -58,6 +58,7 @@ _CLIENT_ASSETS: tuple[str, ...] = (
     "tempestweb.js",
     "dom.js",
     "style.js",
+    "theme.js",
     "events.js",
     "transport.js",
     "virtualize.js",

tempestweb-0.6.0/tempestweb/components/__init__.py

@@ -0,0 +1,60 @@
+"""tempestweb.components — ready-to-use fields, forms and Material 3 buttons.
+
+Pre-built, validated building blocks so an app declares a field, a button or a
+whole form in one line instead of wiring inputs, labels, errors and validators
+by hand:
+
+    from tempestweb.components import EmailField, PasswordField, LoginForm
+    from tempestweb.components import filled_button, text_button
+
+``EmailField``/``PasswordField`` and ``TextField`` are tempestweb-native, styled
+for the Material 3 light surface the base stylesheet renders; the BR fields
+(:class:`PhoneField`/:class:`CPFField`/:class:`CNPJField`/:class:`AddressField`)
+wrap the core's masked inputs. The ``*_button`` helpers build the MD3 button
+variants. Everything renders identically in Mode A (WASM) and Mode B (server).
+"""
+
+from __future__ import annotations
+
+from tempestweb.components.buttons import (
+    elevated_button,
+    filled_button,
+    outlined_button,
+    text_button,
+    tonal_button,
+)
+from tempestweb.components.fields import (
+    AddressField,
+    CNPJField,
+    CPFField,
+    EmailField,
+    PasswordField,
+    PhoneField,
+    TextField,
+    validate_cnpj,
+    validate_cpf,
+    validate_email,
+    validate_phone,
+)
+from tempestweb.components.forms import LoginForm, SignupForm
+
+__all__ = [
+    "AddressField",
+    "CNPJField",
+    "CPFField",
+    "EmailField",
+    "LoginForm",
+    "PasswordField",
+    "SignupForm",
+    "TextField",
+    "PhoneField",
+    "elevated_button",
+    "filled_button",
+    "outlined_button",
+    "text_button",
+    "tonal_button",
+    "validate_cnpj",
+    "validate_cpf",
+    "validate_email",
+    "validate_phone",
+]