labforge 0.2.0__tar.gz → 0.3.0__tar.gz

{labforge-0.2.0 → labforge-0.3.0}/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 Notable changes to labforge. Versions follow [semantic versioning](https://semver.org).
 
+## 0.3.0 — 2026-07-22
+
+- **Wordmark animation** — hovering the app title blows its letters apart and
+  keeps them floating until the pointer leaves; they spring back into the
+  wordmark on exit.
+- **Motion** — rail navigation cross-fades between pages; a re-rendered figure
+  or recomputed result fades over its predecessor instead of flashing; the run
+  gate dissolves into the first output; the scan toggle fades between slider
+  and comma field; and the RUNNING status pulses gently while a run is in
+  flight.
+- **Reading measure** — every page constrains its content to a 720 px column,
+  so prose keeps a comfortable line length and control rows stay compact
+  instead of stretching across the window. Displayed equations sit centered in
+  the measure, and figures scale down to fit it (staying crisp on high-dpi
+  screens) instead of clipping at the pane edge.
+- **Uniform control rows** — text fields share the sliders' fixed label column
+  and the house field styling (hairline outline, square corners), and a new
+  `help` string on `Param` surfaces as a tooltip on the row label.
+- **Parse feedback** — an unreadable text or comma-list entry now flags the
+  field ("invalid, kept ...") while the last good value stays live, instead of
+  falling back silently.
+- **Error tone** — a worker, viz or analysis exception shows its status line in
+  the theme's error colour rather than the muted telemetry tone.
+- **Scan progress** — a running scan reports `RUNNING · k/N` as the grid fills
+  in; `run_worker` and `LabState.run` accept an optional `progress(done, total)`
+  callback.
+- **Explorable pre-run pages** — the Visualization and Analysis tabs, their
+  descriptions and controls now show before the first Run; the NO DATA card
+  sits only in the output slot. Tab labels speak the app's monospace voice.
+- **Enter to run** — pressing Enter in any text field fires its section's
+  Run/Render/Compute action.
+
 ## 0.2.0 — 2026-07-22
 
 - **`choice` param** — `Param(kind="choice", options=[...])` renders a Dropdown

{labforge-0.2.0 → labforge-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labforge
-Version: 0.2.0
+Version: 0.3.0
 Summary: Wrap plain Python functions into a small scientific Flet desktop app: theory, simulation, visualization, analysis.
 Project-URL: Homepage, https://github.com/laroccod/labforge
 Project-URL: Repository, https://github.com/laroccod/labforge
@@ -69,7 +69,7 @@ def sample(mu=0.0, sigma=1.0, n=2000, seed=42):
 
 
 lab.add_worker(sample, {
-    "mu": Param(default=0.0, bounds=(-5, 5), scan=True),
+    "mu": Param(default=0.0, bounds=(-5, 5), scan=True, help="Mean of the distribution"),
     "sigma": Param(default=1.0, bounds=(0.1, 4), scan=True),
     "n": Param(kind="int", default=2000, bounds=(10, 100_000)),
     "seed": "int",
@@ -108,7 +108,9 @@ lab.open()
 That is the whole app. `lab.open()` opens a native window with four pages —
 Theory, Simulation, Visualization, Analysis — a slider for every bounded
 parameter, a Run button, and tabs for each registered visualization and
-analysis.
+analysis. Content keeps a book-like reading measure, navigation and result
+updates cross-fade rather than cut, and every page is explorable before the
+first Run.
 
 An extended version of this example — same lab plus a fitted-density overlay
 and a Q-Q plot tab — lives at [`examples/demo_lab.py`](examples/demo_lab.py):
@@ -133,6 +135,12 @@ spec nothing:
 | `Param(default=1.0)` / `"scalar"` / `"int"` | validated text field |
 | `Param(..., scan=True)` / `"scalar or array"` / `"int or array"` | scannable (see below) |
 | `"N-tuple"` (e.g. `"2-tuple"`) | one field per element |
+| `Param(kind="choice", options=["a", "b"])` | dropdown |
+
+Every `Param` also takes `label=` to rename its control and `help=` for a
+tooltip on the control's label. Pressing Enter in any text field runs the
+section it belongs to, and an entry that fails to parse flags the field while
+the last good value stays live.
 
 Validation happens at registration: unknown spec keys, defaults outside
 bounds, or a scan spec on a non-worker function raise `ValueError` when the
@@ -141,7 +149,8 @@ app is assembled, never mid-use.
 **Parameter scans.** A kwarg declared `scan=True` gets a scan toggle (bounded)
 or a comma-separated field (unbounded). Enter `0, 1, 2` and `labforge` calls the
 worker once per point of the cartesian grid across all scanned parameters —
-the worker itself always receives scalars. Downstream functions then receive a
+the worker itself always receives scalars. A long scan reports its progress in
+the status line as the grid fills in. Downstream functions then receive a
 `ScanResult`: a list of `(params, result)` records with `keys`, `values()` and
 `axis(name)` helpers, distinguished with `isinstance(data, ScanResult)`.
 

{labforge-0.2.0 → labforge-0.3.0}/README.md

@@ -36,7 +36,7 @@ def sample(mu=0.0, sigma=1.0, n=2000, seed=42):
 
 
 lab.add_worker(sample, {
-    "mu": Param(default=0.0, bounds=(-5, 5), scan=True),
+    "mu": Param(default=0.0, bounds=(-5, 5), scan=True, help="Mean of the distribution"),
     "sigma": Param(default=1.0, bounds=(0.1, 4), scan=True),
     "n": Param(kind="int", default=2000, bounds=(10, 100_000)),
     "seed": "int",
@@ -75,7 +75,9 @@ lab.open()
 That is the whole app. `lab.open()` opens a native window with four pages —
 Theory, Simulation, Visualization, Analysis — a slider for every bounded
 parameter, a Run button, and tabs for each registered visualization and
-analysis.
+analysis. Content keeps a book-like reading measure, navigation and result
+updates cross-fade rather than cut, and every page is explorable before the
+first Run.
 
 An extended version of this example — same lab plus a fitted-density overlay
 and a Q-Q plot tab — lives at [`examples/demo_lab.py`](examples/demo_lab.py):
@@ -100,6 +102,12 @@ spec nothing:
 | `Param(default=1.0)` / `"scalar"` / `"int"` | validated text field |
 | `Param(..., scan=True)` / `"scalar or array"` / `"int or array"` | scannable (see below) |
 | `"N-tuple"` (e.g. `"2-tuple"`) | one field per element |
+| `Param(kind="choice", options=["a", "b"])` | dropdown |
+
+Every `Param` also takes `label=` to rename its control and `help=` for a
+tooltip on the control's label. Pressing Enter in any text field runs the
+section it belongs to, and an entry that fails to parse flags the field while
+the last good value stays live.
 
 Validation happens at registration: unknown spec keys, defaults outside
 bounds, or a scan spec on a non-worker function raise `ValueError` when the
@@ -108,7 +116,8 @@ app is assembled, never mid-use.
 **Parameter scans.** A kwarg declared `scan=True` gets a scan toggle (bounded)
 or a comma-separated field (unbounded). Enter `0, 1, 2` and `labforge` calls the
 worker once per point of the cartesian grid across all scanned parameters —
-the worker itself always receives scalars. Downstream functions then receive a
+the worker itself always receives scalars. A long scan reports its progress in
+the status line as the grid fills in. Downstream functions then receive a
 `ScanResult`: a list of `(params, result)` records with `keys`, `values()` and
 `axis(name)` helpers, distinguished with `isinstance(data, ScanResult)`.
 

{labforge-0.2.0 → labforge-0.3.0}/examples/demo_lab.py

@@ -58,10 +58,12 @@ def sample(mu=0.0, sigma=1.0, n=2000, seed=42):
 lab.add_worker(
     sample,
     {
-        "mu": Param(default=0.0, bounds=(-5, 5), scan=True),
-        "sigma": Param(default=1.0, bounds=(0.1, 4), scan=True),
-        "n": Param(kind="int", default=2000, bounds=(10, 100_000)),
-        "seed": "int",
+        "mu": Param(default=0.0, bounds=(-5, 5), scan=True, help="Mean of the distribution"),
+        "sigma": Param(
+            default=1.0, bounds=(0.1, 4), scan=True, help="Standard deviation of the distribution"
+        ),
+        "n": Param(kind="int", default=2000, bounds=(10, 100_000), help="Sample size of the draw"),
+        "seed": Param(kind="int", help="Seed of the random generator"),
     },
     name="Normal",
 )
@@ -169,10 +171,10 @@ def sample_gamma(shape=2.0, scale=1.0, n=2000, seed=42):
 lab.add_worker(
     sample_gamma,
     {
-        "shape": Param(default=2.0, bounds=(0.5, 10), scan=True),
-        "scale": Param(default=1.0, bounds=(0.1, 4), scan=True),
-        "n": Param(kind="int", default=2000, bounds=(10, 100_000)),
-        "seed": "int",
+        "shape": Param(default=2.0, bounds=(0.5, 10), scan=True, help="Shape parameter k"),
+        "scale": Param(default=1.0, bounds=(0.1, 4), scan=True, help="Scale parameter θ"),
+        "n": Param(kind="int", default=2000, bounds=(10, 100_000), help="Sample size of the draw"),
+        "seed": Param(kind="int", help="Seed of the random generator"),
     },
     name="Gamma",
 )

{labforge-0.2.0 → labforge-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "labforge"
-version = "0.2.0"
+version = "0.3.0"
 description = "Wrap plain Python functions into a small scientific Flet desktop app: theory, simulation, visualization, analysis."
 readme = "README.md"
 license = "MIT"

{labforge-0.2.0 → labforge-0.3.0}/src/labforge/controls.py

@@ -6,13 +6,17 @@ from dataclasses import dataclass
 
 import flet as ft
 
-from .ui import FONT_MONO
+from .ui import FONT_MONO, fading_pane
 
 # Parameter names and values are data, so every label, readout and field in a
 # control row speaks the app's monospace voice.
 MONO = ft.TextStyle(size=13, font_family=FONT_MONO)
 MONO_LABEL = ft.TextStyle(size=12, font_family=FONT_MONO)
 
+# Shared width of the leading label cell, so the control rows of a card align
+# into a clean two-column grid.
+LABEL_WIDTH = 120
+
 
 @dataclass
 class ControlBinding:
@@ -32,7 +36,7 @@ class ControlBinding:
     read: callable
 
 
-def build_control(name, param, values, page, on_change=None):
+def build_control(name, param, values, page, on_change=None, on_submit=None):
     """
     Build the control row for one Param.
 
@@ -49,11 +53,15 @@ def build_control(name, param, values, page, on_change=None):
         The live values dict (state.worker_values or a per-tab kwargs dict);
         read at build time and committed to on every change.
     page: ft.Page
-        Needed to flush live readout updates during a slider drag.
+        Needed to flush live readout and parse-error updates.
     on_change: callable
         Optional callback(value) fired after a choice commits — the Theory-page
         selector uses it to rebuild the markdown its selection drives. Ignored
         by every other kind.
+    on_submit: callable
+        Optional zero-arg callback fired when Enter is pressed in a text
+        field; the section builders pass their Run/Render/Compute action so a
+        keyboard edit can commit and run in one stroke.
 
     Returns
     -------
@@ -64,17 +72,45 @@ def build_control(name, param, values, page, on_change=None):
     if param.kind == "choice":
         return choice_control(name, label, param, value, values, on_change)
     if param.kind == "tuple":
-        return tuple_control(name, label, param, value, values)
+        return tuple_control(name, label, param, value, values, page, on_submit)
     if param.bounds is None and not param.scan:
-        return text_control(name, label, param, value, values)
+        return text_control(name, label, param, value, values, page, on_submit)
     if param.bounds is None:
-        return scan_control(name, label, param, value, values)
+        return scan_control(name, label, param, value, values, page, on_submit)
     if not param.scan:
         return slider_control(name, label, param, value, values, page)
-    return toggled_control(name, label, param, value, values, page)
+    return toggled_control(name, label, param, value, values, page, on_submit)
+
+
+def label_cell(label, param):
+    """The fixed-width row label; carries the param's help as a tooltip."""
+    return ft.Text(label, width=LABEL_WIDTH, style=MONO, tooltip=param.help)
 
 
-def slider_control(name, label, param, value, values, page):
+def label_row(label, param, body):
+    """The uniform control row: a label cell, then the control body."""
+    return ft.Row(
+        vertical_alignment=ft.CrossAxisAlignment.CENTER,
+        controls=[label_cell(label, param), body],
+    )
+
+
+def text_field(value, width, on_submit=None, hint=None):
+    """A text field in the house style: hairline outline, near-square corners."""
+    field = ft.TextField(
+        value=value,
+        width=width,
+        text_style=MONO,
+        border_color=ft.Colors.OUTLINE_VARIANT,
+        border_radius=2,
+        hint_text=hint,
+    )
+    if on_submit is not None:
+        field.on_submit = lambda e: on_submit()
+    return field
+
+
+def slider_control(name, label, param, value, values, page, labelled=True):
     """A bounded param: a slider with a live readout."""
     lo, hi = param.bounds
     if isinstance(value, list):  # scan values left over from a stale spec edit
@@ -104,73 +140,80 @@ def slider_control(name, label, param, value, values, page):
     def read():
         return cast(param, slider.value)
 
-    return ControlBinding(row=slider_row(label, slider, readout), read=read)
+    # The bare body is what toggled_control swaps in and out of its holder,
+    # which keeps the label cell fixed while the control behind it changes.
+    body = ft.Row(
+        expand=True,
+        vertical_alignment=ft.CrossAxisAlignment.CENTER,
+        controls=[ft.Container(slider, expand=True), readout],
+    )
+    row = label_row(label, param, body) if labelled else body
+    return ControlBinding(row=row, read=read)
 
 
-def text_control(name, label, param, value, values):
+def text_control(name, label, param, value, values, page, on_submit):
     """An unbounded scalar or int: a validated text field."""
-    field = ft.TextField(
-        label=label,
-        value=format_scalar(param, value),
-        width=160,
-        text_style=MONO,
-        label_style=MONO_LABEL,
-    )
+    field = text_field(format_scalar(param, value), 160, on_submit)
 
     def read():
-        parsed = parse_scalar(param, field.value, fallback=values.get(name, param.default))
+        fallback = values.get(name, param.default)
+        parsed, ok = parse_scalar(param, field.value, fallback)
+        field.error = None if ok else f"invalid, kept {format_scalar(param, fallback)}"
         values[name] = parsed
         return parsed
 
-    field.on_change = lambda e: read()
-    return ControlBinding(row=field, read=read)
+    def on_change(e):
+        read()
+        page.update()  # paint or clear the parse-error flag as the user types
+
+    field.on_change = on_change
+    return ControlBinding(row=label_row(label, param, field), read=read)
 
 
-def scan_control(name, label, param, value, values):
+def scan_control(name, label, param, value, values, page, on_submit):
     """An unbounded scan param: always a comma-separated values field."""
-    field = ft.TextField(
-        label=f"{label} (comma-separated to scan)",
-        value=format_values(param, value),
-        width=260,
-        text_style=MONO,
-        label_style=MONO_LABEL,
-    )
+    field = text_field(format_values(param, value), 260, on_submit, hint="comma-separated to scan")
 
     def read():
-        parsed = parse_values(param, field.value, fallback=values.get(name, param.default))
+        fallback = values.get(name, param.default)
+        parsed, ok = parse_values(param, field.value, fallback)
+        field.error = None if ok else f"invalid, kept {format_values(param, fallback)}"
         values[name] = parsed
         return parsed
 
-    field.on_change = lambda e: read()
-    return ControlBinding(row=field, read=read)
+    def on_change(e):
+        read()
+        page.update()
 
+    field.on_change = on_change
+    return ControlBinding(row=label_row(label, param, field), read=read)
 
-def toggled_control(name, label, param, value, values, page):
+
+def toggled_control(name, label, param, value, values, page, on_submit):
     """
     A bounded scan param: a slider row with a scan Switch.
 
-    The switch swaps the content of a mounted Container between the slider and a
-    comma-list field — the same mutate-in-place pattern the pages use for their
-    result panes. Starting from a list value (a scan committed earlier) restores
-    scan mode.
+    The switch swaps the content of a mounted fading pane between the slider
+    and a comma-list field — the same mutate-in-place pattern the pages use for
+    their result panes, so the mode change fades instead of cutting. Starting
+    from a list value (a scan committed earlier) restores scan mode.
     """
     scanning = isinstance(value, list)
     slider_binding = slider_control(
-        name, label, param, value if not scanning else param.default, values, page
-    )
-    field = ft.TextField(
-        label=f"{label} values",
-        value=format_values(param, value),
-        width=220,
-        text_style=MONO,
-        label_style=MONO_LABEL,
+        name, label, param, value if not scanning else param.default, values, page, labelled=False
     )
-    holder = ft.Container(content=field if scanning else slider_binding.row, expand=True)
+    field = text_field(format_values(param, value), 220, on_submit, hint="comma-separated to scan")
+    # The switcher centers a lone child, so the field rides in a left-aligning
+    # box to line up with the other rows' controls.
+    field_box = ft.Container(content=field, alignment=ft.Alignment.CENTER_LEFT)
+    holder = fading_pane(field_box if scanning else slider_binding.row, duration=200, expand=True)
     switch = ft.Switch(label="SCAN", value=scanning, label_position=ft.LabelPosition.RIGHT)
 
     def read():
         if switch.value:
-            parsed = parse_values(param, field.value, fallback=values.get(name, param.default))
+            fallback = values.get(name, param.default)
+            parsed, ok = parse_values(param, field.value, fallback)
+            field.error = None if ok else f"invalid, kept {format_values(param, fallback)}"
         else:
             parsed = slider_binding.read()
         values[name] = parsed
@@ -180,41 +223,49 @@ def toggled_control(name, label, param, value, values, page):
         if switch.value:
             # Carry the slider's value across, so switching to scan starts there.
             field.value = format_values(param, slider_binding.read())
-            holder.content = field
+            holder.content = field_box
         else:
             holder.content = slider_binding.row
         read()
         page.update()
 
+    def on_field_change(e):
+        read()
+        page.update()
+
     switch.on_change = on_toggle
-    field.on_change = lambda e: read()
-    row = ft.Row(vertical_alignment=ft.CrossAxisAlignment.CENTER, controls=[holder, switch])
+    field.on_change = on_field_change
+    row = ft.Row(
+        vertical_alignment=ft.CrossAxisAlignment.CENTER,
+        controls=[label_cell(label, param), holder, switch],
+    )
     return ControlBinding(row=row, read=read)
 
 
-def tuple_control(name, label, param, value, values):
+def tuple_control(name, label, param, value, values, page, on_submit):
     """A fixed-size tuple: one small text field per element."""
-    fields = [
-        ft.TextField(value=f"{element:g}", width=90, text_align=ft.TextAlign.RIGHT, text_style=MONO)
-        for element in tuple(value)
-    ]
+    fields = [text_field(f"{element:g}", 90, on_submit) for element in tuple(value)]
+    for field in fields:
+        field.text_align = ft.TextAlign.RIGHT
 
     def read():
         previous = tuple(values.get(name, param.default))
-        parsed = tuple(
-            parse_scalar(param, field.value, fallback=element)
-            for field, element in zip(fields, previous)
-        )
-        values[name] = parsed
-        return parsed
+        parsed = []
+        for field, element in zip(fields, previous):
+            element_value, ok = parse_scalar(param, field.value, element)
+            field.error = None if ok else f"kept {element:g}"
+            parsed.append(element_value)
+        values[name] = tuple(parsed)
+        return values[name]
+
+    def on_change(e):
+        read()
+        page.update()
 
     for field in fields:
-        field.on_change = lambda e: read()
-    row = ft.Row(
-        vertical_alignment=ft.CrossAxisAlignment.CENTER,
-        controls=[ft.Text(label, width=120, style=MONO), *fields],
-    )
-    return ControlBinding(row=row, read=read)
+        field.on_change = on_change
+    body = ft.Row(vertical_alignment=ft.CrossAxisAlignment.CENTER, controls=fields)
+    return ControlBinding(row=label_row(label, param, body), read=read)
 
 
 def choice_control(name, label, param, value, values, on_change):
@@ -237,6 +288,7 @@ def choice_control(name, label, param, value, values, on_change):
         border_color=ft.Colors.OUTLINE_VARIANT,
         border_radius=2,
         width=260,
+        tooltip=param.help,
     )
 
     def read():
@@ -252,18 +304,6 @@ def choice_control(name, label, param, value, values, on_change):
     return ControlBinding(row=dropdown, read=read)
 
 
-def slider_row(label, slider, readout):
-    """A labelled slider with its live readout to the right."""
-    return ft.Row(
-        vertical_alignment=ft.CrossAxisAlignment.CENTER,
-        controls=[
-            ft.Text(label, width=120, style=MONO),
-            ft.Container(slider, expand=True),
-            readout,
-        ],
-    )
-
-
 def cast(param, value):
     """
     Cast a slider value or one token of user text to the param's kind, rounding
@@ -291,19 +331,25 @@ def format_values(param, value):
 
 
 def parse_scalar(param, text, fallback):
-    """Parse one value of the param's kind, keeping fallback on bad input."""
+    """
+    Parse one value of the param's kind into (value, ok).
+
+    Bad input keeps the fallback with ok False, so the caller can hold the last
+    good value live while flagging the field.
+    """
     try:
-        return cast(param, text)
+        return cast(param, text), True
     except (TypeError, ValueError):
-        return fallback
+        return fallback, False
 
 
 def parse_values(param, text, fallback):
     """
-    Parse a comma-separated scan entry.
+    Parse a comma-separated scan entry into (value, ok).
 
-    A single valid value returns a scalar (a one-point scan is just a run);
-    several return a list; no valid values return the fallback.
+    A single valid value parses to a scalar (a one-point scan is just a run)
+    and several to a list; any bad token, or no token at all, keeps the
+    fallback with ok False.
     """
     parsed = []
     for token in str(text).split(","):
@@ -313,7 +359,7 @@ def parse_values(param, text, fallback):
         try:
             parsed.append(cast(param, token))
         except ValueError:
-            return fallback
+            return fallback, False
     if not parsed:
-        return fallback
-    return parsed[0] if len(parsed) == 1 else parsed
+        return fallback, False
+    return (parsed[0] if len(parsed) == 1 else parsed), True

{labforge-0.2.0 → labforge-0.3.0}/src/labforge/pages/analysis.py

@@ -16,10 +16,11 @@ def section_controls(entry, state, page):
     One analysis's description, kwarg controls, Compute action and result pane,
     as a list of controls. Shared by the tabbed page and the scroll layout.
     """
-    pane = ft.Container()
+    pane = ui.fading_pane()
 
     def show(value):
-        # Swap only the content: the mounted Container stays, so the tab survives.
+        # Swap only the content: the mounted pane stays, so the tab survives,
+        # and each Compute cross-fades the new result over the old.
         pane.content = render_result(value)
 
     return panel.section_controls(
@@ -60,7 +61,7 @@ def render_result(value):
     if isinstance(value, str):
         return ui.body(value)
     if is_figure(value):
-        return ui.image(figure_to_base64(unpack_figure(value)))
+        return ui.fitted_image(figure_to_base64(unpack_figure(value)))
     return ui.body(f"`{value!r}`")