Add forms, fields, and operation-backed actions

[czpython]

ENG-905

An operator writes into an app through blocks the app declared in Python. No
app JavaScript.

ui.Form(
    title="New note",
    fields=[ui.TextAreaField(name="body", label="Note", is_required=True, rows=3)],
    action=ui.Action(label="Save", operation="write_note", tone="primary",
                     link=ui.Link("Notes", page="notes")),
)

Fields

TextField, TextAreaField, NumberField, SelectField, MultiSelectField,
RadioField, and CheckboxField, each with name, label, help_text, and
is_required. name is the key the shell sends. Option(label) takes its
label positionally, like every type whose one required value is the thing it
shows.

Actions and operations

An Action names one of the app's own routes by its operation_id — the id
FastAPI already has — and the shell resolves it to a method and URL, so an
author never writes one. The app roster carries that table as
{id, method, path}, non-GET only.

Two boot errors: two routes sharing one operation_id, and one route
answering two methods. Two page-read errors, found the moment a page is
built: an action naming an operation no route declares, and an action naming
a GET. The route takes its values the way the shell sends them — path
parameters and a flat JSON body, Body(embed=True) or a model — and a route
shaped otherwise answers 422 when the action runs. Deeper request
introspection was deliberately left out: actions are headed for a declared
surface like pages, which removes those route shapes entirely.

What pressing a button does

The shell merges the action's arguments with the field values, fills the
route's path parameters, and posts the rest as the body. Then, by the
action's refresh: nothing, the region it sits in, or the whole page. A
link navigates after success. confirm asks first. A 422 lands on the
field it names; anything else shows on the action. A double press sends once.

Form names every argument — its required value is the action that sends it,
not something it shows — and a field validator refuses a field named like an
argument the action already carries, so every value is sent exactly once.

How it is verified

backend/tests/test_ui_actions.py pins the wire shapes, the boot errors, the
page-read refusals, and that every action on a page is checked wherever it
nests. backend/tests/test_ui_page_api.py reads the proof app's form page and
gist card through HTTP.

frontend/src/druksui/Form.test.tsx and Fields.tsx tests cover every field
input, the merged payload, path filling, each refresh mode, the confirm, the
double-press guard, field-level 422s, and the success link.
AppPage.test.tsx covers region refresh finding its section.

Gates run: uv run ruff check backend, uv run ruff format --check backend,
npm --prefix frontend run lint, npm --prefix frontend test (203 tests
pass), npm --prefix frontend run build. uv run pytest backend/ runs in CI;
the fixture-free suites were run directly and pass.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
druks	🟢 Ready	View Preview	Aug 30, 2026, 10:44 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.