# Rebase

> Take a fresh server copy without losing what the user typed.

Source: https://forms.lunarhue.dev/solid/plugins/rebase

The user is editing a record when a fresher copy arrives from the server.
Taking it whole loses their typing, and ignoring it leaves stale values in
the fields they didn't touch. `rebase` merges the two, field by field.

```tsx title="profile.tsx"
import { createForm, createForms } from "@lunarhue/forms-solid";
import { dirty, rebase } from "@lunarhue/forms-solid/plugins";
import { TextField } from "./TextField";

const forms = createForms({ plugins: [dirty(), rebase()], fields: { TextField } });

const profile = forms.define({
  defaultValues: { name: "Ada Lovelace", email: "ada@example.com" },
  onSubmit: (value) => value,
});

// Stands in for `fetch("/api/profile")`. Someone changed both fields
// on the server since this form loaded.
const fetchProfile = () =>
  Promise.resolve({ name: "Ada King", email: "ada@lovelace.dev" });

export default function ProfileForm() {
  const form = createForm(profile, { id: "profile" });

  // Fields the user edited keep their text. The rest take the server's.
  const refresh = async () => {
    const fresh = await fetchProfile();
    form.plugins.rebase(form.root, fresh, (leaf) => (leaf.edited ? "keep" : "take"));
  };

  return (
    <form.Form>
      {(formProps) => (
        <form {...formProps}>
          <form.TextField name="name" label="Name" />
          <form.TextField name="email" label="Email" />
          <button type="button" onClick={() => void refresh()}>
            Refresh
          </button>
        </form>
      )}
    </form.Form>
  );
}
```

```tsx title="TextField.tsx"
import { type FieldApi, type FormError, inputProps } from "@lunarhue/forms-solid";

interface TextFieldProps {
  readonly field: FieldApi<string, FormError, "dirty">;
  readonly label: string;
}

// `field.dirty` is true while the value differs from its baseline. The
// "dirty" in the type says the form must have `dirty()`.
export function TextField(props: TextFieldProps) {
  return (
    <label>
      <span>
        {props.label}
        {props.field.dirty ? " (changed)" : null}
      </span>
      <input {...inputProps(props.field)} />
    </label>
  );
}
```

Edit the name, then press Refresh. The name keeps your text and the email
takes the server's.

`form.plugins.rebase(handle, incoming, resolve)` moves the baseline of the
subtree at `handle` to `incoming`, such as a fresh copy from the server. A
leaf whose current value already equals the incoming one only moves its
baseline. For every other leaf, `resolve` picks what it becomes:

```ts
const fresh = await fetchProfile();
form.plugins.rebase(form.root, fresh, (leaf) => (leaf.edited ? "keep" : "take"));
```

- `"keep"` keeps the current value. The field stays dirty against the new
  baseline.
- `"take"` writes the incoming value.
- `{ value }` writes a value of your own, such as a merge of the two.

Each leaf comes with its `path`, the current `value`, the old `baseline`, the
`incoming` value and `edited`, true when the user has edited it.

## What it returns

`rebase` returns `{ taken }`, the paths it wrote with `"take"` or `{ value }`.
Validators that already ran on those fields run again. Listeners run
once, after the whole rebase.

Pass any handle of the form, such as `form.root.at("address")`, to rebase one
part of it. A handle from another form throws
[`rebase:store`](https://forms.lunarhue.dev/errors.md#core:rebase:store).

## Comparing values

With [`dirty()`](https://forms.lunarhue.dev/solid/plugins/dirty.md) installed, rebase compares values with the form's
dirty comparison, including any `equals` you gave. Without it, values compare
by `Object.is`, so a date with the same time counts as changed and goes to
`resolve`.

Objects are walked key by key. An array is walked item by item when its items
still have the keys and order of its baseline and the incoming array is as
long. Otherwise the whole array is one leaf.

## Other plugins

Rebase writes aren't user edits. `history` records no step for them, and
`mask` doesn't clean them, since the incoming value is the server's copy.
