rok-ui 0.9.2

shadcn/ui-style component system for GPUI desktop apps, with a React-like developer experience.
Documentation
# Forms

`rok_ui::form` (feature `form`, part of the `forms` group and of `full`) is a headless,
type-safe form library modeled on TanStack Form: the form owns typed values, fields read their
slice through typed paths, validators run on the events you choose, and bound controls render
the state.

| TanStack Form | rok-ui |
|---|---|
| `useForm({ defaultValues, validators, onSubmit })` | `form::use_form(cx, FormOptions::new(defaults).validators(..).on_submit(..))` |
| `<form.Field name="email" validators={..}>` | `form.field(cx, SignUp::EMAIL)` / `form.field_with(cx, path, validators)` |
| `field.state.value`, `field.state.meta.errors` | `field.value()`, `field.meta().errors()` |
| `field.handleChange`, `field.handleBlur` | `field.handle_change(cx, value)`, `field.handle_blur(cx)` |
| `onChange`, `onBlur`, `onSubmit`, `onChangeAsyncDebounceMs` | `on_change`, `on_blur`, `on_submit`, `on_change_async_debounce` |
| `onChangeListenTo` | `.listen_to(&SignUp::PASSWORD)` |
| `form.Field mode="array"` + `pushValue`, `removeValue`, .. | `form.array_field(cx, path)` + `push_value`, `remove_value`, .. |
| `form.state.canSubmit`, `isSubmitting` | `form.state().can_submit`, `.is_submitting` |
| Standard Schema adapters | `FormValidators::schema(..)`, `GardeSchema` (feature `form-garde`) |

## Defining a form

`#[derive(FormValues)]` adds a typed field constant per struct field: `email: String` becomes
`SignUp::EMAIL`, a `Field<SignUp, String>`. Options are a value built by a function:

```
use rok_ui::{
    form::{FormError, FormOptions, FormValidators, FormValues, Validators},
    gpui::Task,
};

#[derive(FormValues, Clone, Debug, Default)]
pub struct SignUp {
    pub email: String,
    pub password: String,
    pub confirm: String,
    pub accept_terms: bool,
}

pub fn sign_up_form() -> FormOptions<SignUp> {
    FormOptions::new(SignUp::default())
        .field(
            SignUp::EMAIL,
            Validators::new()
                .on_change(|email: &String| email.is_empty().then_some("Required"))
                .on_blur(|email: &String| (!email.contains('@')).then_some("Enter a valid email")),
        )
        .field(
            SignUp::CONFIRM,
            // Re-checked when the password changes too.
            Validators::new().listen_to(&SignUp::PASSWORD),
        )
        .validators(FormValidators::new().on_submit(|values: &SignUp| {
            (values.password != values.confirm)
                .then(|| FormError::field(&SignUp::CONFIRM, "Passwords do not match"))
        }))
        .on_submit(|values, _cx| {
            // Call a procedure or save the values; errors map back onto fields.
            let _ = values;
            Task::ready(Ok(()))
        })
}
# let _ = sign_up_form();
```

## Rendering fields

```no_run
# use rok_ui::{prelude::*, form::{self, CheckboxField, FormOptions, FormValues, SubmitButton, TextField}};
# #[derive(FormValues, Clone, Default)]
# pub struct SignUp { email: String, password: String, accept_terms: bool }
#[component]
fn SignUpForm(cx: &mut Cx) -> impl IntoElement {
    let form = form::use_form(cx, FormOptions::new(SignUp::default()));
    let email = form.field(cx, SignUp::EMAIL);
    let password = form.field(cx, SignUp::PASSWORD);
    let terms = form.field(cx, SignUp::ACCEPT_TERMS);
    FieldGroup::new()
        .child(TextField::new(&email, "Email").leading_icon(IconName::Mail))
        .child(TextField::new(&password, "Password").password())
        .child(CheckboxField::new(&terms, "I accept the terms"))
        .child(SubmitButton::new(&form, "Create account"))
}
```

- `TextField` (and the bare `BoundInput`) binds an `Input` to a `String` field: typing
  changes the value, leaving the field runs blur validators, and Enter submits the form.
- `TextareaField` binds a multi-line text area: Enter adds a line and Ctrl/Cmd-Enter submits.
- `CheckboxField` and `SwitchField` bind `bool` fields. `SelectField` and `RadioGroupField`
  (with the `select` and `radio-group` features) bind `String` fields to the chosen option's
  value, as does `ComboboxField` (`combobox`); `SliderField` (`slider`) binds an `f32` and
  `DatePickerField` (`date-picker`) an `Option<CalendarDate>`. Picking a value counts as
  leaving the field, so blur validators run.
- `InputOtpField` (`input-otp`) binds a one-time code to a `String`: every edit changes the
  value, and filling the last box counts as leaving the field. Any other control with an `on_change` that passes the new
  value binds with `.on_change(field.change_handler())`.
- Errors show once the field is touched or a submit was attempted
  (`field.should_show_errors()`); custom layouts read `field.meta()` directly.
- `SubmitButton` spins while the form submits and is disabled while it cannot.
  `FormErrors::new(&form)` lists errors that are not tied to a field.

## Field and form state

| Field | Meaning |
|---|---|
| `value()` | The typed value at the field's path |
| `meta().errors()`, `meta().error_map`, `meta().form_error_map` | Errors, by the event that produced them |
| `meta().is_touched`, `is_blurred`, `is_dirty`, `is_pristine()` | Interaction state |
| `meta().is_validating` | An async validator is running |
| `handle_change(cx, value)`, `handle_blur(cx)`, `change_handler()` | What bound controls call |

| Form | Meaning |
|---|---|
| `values()` | Every value |
| `state().can_submit`, `is_submitting`, `is_submitted`, `submission_attempts` | Submit lifecycle |
| `state().is_valid`, `is_dirty`, `is_touched`, `is_validating`, `errors` | Aggregates |
| `submit(window, cx)`, `submit_handler()`, `reset(cx)`, `reset_field(cx, path)`, `set_value(cx, path, value)`, `validate(cx, event)` | Imperative API |

## Validation

- **Events.** `on_mount`, `on_change`, `on_blur` and `on_submit`. Errors are kept per event
  (`error_map`), so a blur error does not hide a submit error. Changing a field clears its
  submit and server errors; each event's errors last until that event runs again.
- **Async.** `on_change_async_debounce(duration, |value| async { .. })` runs once the value
  has been still for `duration`, only after the synchronous `on_change` passes, and only the
  latest run's result counts. `on_blur_async` and `on_submit_async` run without a debounce.
- **Form validators** (`FormValidators`) see all values and return a `FormError` with errors
  for any field (`FormError::field(&SignUp::CONFIRM, ..)`) or the whole form.
- **Linked fields.** `.listen_to(&OTHER)` re-runs a field's change validators when `OTHER`
  changes.
- **Schemas.** `FormValidators::schema(..)` validates with anything implementing `Schema`.
  With the `form-garde` feature, `GardeSchema` uses the values' `garde::Validate` derive, so
  one set of rules covers the form and the procedure that receives it.
- **Submit.** Submitting runs every validator and waits for the async ones (the form is
  `is_submitting` meanwhile). If anything is invalid, the first invalid bound field gets
  focus; otherwise the submit handler runs, and the `FormError` it returns shows on its fields
  as `ValidationEvent::Server` errors.
- **Long forms.** Give the form the handle of the scroll area it sits in, and a failed submit
  also scrolls the first invalid field to the top: keep a `ScrollHandle` in your view, pass it
  to `ScrollArea::track_scroll(&handle)` and to `FormOptions::scroll_handle(handle.clone())`.
  The bound field controls are found this way; a bare `BoundInput` is not.

## Nested and list fields

Paths compose: `SignUp::TEAM.at(0).then(Invite::EMAIL)` is the first invite's email, keyed
`team.0.email`. List fields keep each row's state with its row when rows move:

```no_run
# use rok_ui::{prelude::*, form::{self, FormOptions, FormValues, TextField}};
# #[derive(FormValues, Clone, Default)] pub struct Invite { email: String }
# #[derive(FormValues, Clone, Default)] pub struct SignUp { team: Vec<Invite> }
#[component]
fn Team(cx: &mut Cx) -> impl IntoElement {
    let form = form::use_form(cx, FormOptions::new(SignUp::default()));
    let team = form.array_field(cx, SignUp::TEAM);
    let rows: Vec<AnyElement> = (0..team.len())
        .map(|index| {
            let email = form.field(cx, team.at(index).then(Invite::EMAIL));
            div()
                .flex()
                .gap_2()
                .child(TextField::new(&email, "Email"))
                .child(
                    Button::new(("remove", index))
                        .ghost()
                        .icon(IconName::Trash)
                        .on_click(team.remove_handler(index)),
                )
                .into_any_element()
        })
        .collect();
    div()
        .children(rows)
        .child(
            Button::new("add")
                .outline()
                .label("Add teammate")
                .on_click(team.push_handler(Invite::default())),
        )
}
```

`push_value`, `insert_value`, `remove_value`, `swap_values`, `move_value` and `replace_value`
move the rows' touched, dirty and error state (and their inputs) along with them.

## Unsaved changes

`form.is_dirty()` plugs into the router's blocker: `router::use_blocker(cx, form.is_dirty())`
asks before navigating away from a changed form.

### Drafts

With the `persist` feature, `FormOptions::persist_draft(PersistOptions::new("new-note"))` saves
the values while the user edits, so a form closed half-filled (or an app that quit) opens where
it was left. The values type derives `Serialize` and `Deserialize`:

```rust,no_run
# use rok_ui::{prelude::*, form::{self, FormOptions, FormValues, TextField}, persist::PersistOptions};
#[derive(FormValues, Clone, Default, serde::Serialize, serde::Deserialize)]
struct NewNote { title: String, body: String }

#[component]
fn NewNoteForm(cx: &mut Cx) -> impl IntoElement {
    let form = form::use_form(
        cx,
        FormOptions::new(NewNote::default()).persist_draft(PersistOptions::new("new-note")),
    );
    let title = form.field(cx, NewNote::TITLE);
    TextField::new(&title, "Title")
}
```

The form starts from the saved draft when there is one. Edits are written after the options'
debounce (300 ms by default) to `<config dir>/<app name>/new-note.json`, and a successful
submit or `form.reset(cx)` deletes the file. A restored draft does not mark fields as changed,
so `is_dirty()` starts false. Bump `PersistOptions::version` and add a `migrate` when the
values type changes shape, as with persisted stores.