# Solid signals

> Keep a form's value in step with a Solid signal.

Source: https://forms.lunarhue.dev/solid/integrations/solid-signals

`signal()` binds a form to a Solid 2 signal. The form doesn't move into the
signal. It keeps its own store with the values, errors, touched flags and the
rest. The binding copies the value both ways: a form write sets the signal,
and a change to the signal comes into the form. Remove the binding and the
form works the same.

```bash
npm install @lunarhue/forms-bind
```

```tsx title="settings.tsx"
import { signal } from "@lunarhue/forms-bind/solid";
import { createForm, createForms } from "@lunarhue/forms-solid";
import { createSignal } from "solid-js";
import { TextField } from "./TextField";

const forms = createForms({ fields: { TextField } });

interface Settings {
  displayName: string;
  timezone: string;
}

// State the app already keeps in a signal.
const [settings, setSettings] = createSignal<Settings>({
  displayName: "Ada",
  timezone: "Europe/London",
});

const settingsForm = forms.define({
  defaultValues: { displayName: "", timezone: "" },
  onSubmit: (value) => value,
});

// Reads the signal as usual. It sees each keystroke, since the
// binding copies every form write out.
function Greeting() {
  return <p>Hello, {settings().displayName}.</p>;
}

// A change made outside the form comes in too.
function loadSaved() {
  setSettings({ displayName: "Grace", timezone: "America/New_York" });
}

export default function SettingsForm() {
  // The form starts from the signal's value. Errors, touched and the
  // rest stay in the form. Only the value is copied.
  const form = createForm(settingsForm, {
    id: "settings",
    plugins: [signal(settings, setSettings)],
  });
  return (
    <form.Form>
      {(formProps) => (
        <form {...formProps}>
          <Greeting />
          <form.TextField name="displayName" label="Display name" />
          <form.TextField name="timezone" label="Time zone" />
          <button type="button" onClick={loadSaved}>
            Load saved
          </button>
          <button type="submit">Save</button>
        </form>
      )}
    </form.Form>
  );
}
```

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

interface TextFieldProps {
  readonly field: FieldApi<string>;
  readonly label: string;
}

export function TextField(props: TextFieldProps) {
  return (
    <label>
      {props.label}
      <input {...inputProps(props.field)} />
    </label>
  );
}
```

Type in a field and the greeting, which reads the signal, follows. Load saved
sets the signal, and the form takes the new value.

## Bind a signal

Pass the getter and setter that `createSignal` returns:

```tsx
import { signal } from "@lunarhue/forms-bind/solid";
import { createForm } from "@lunarhue/forms-solid";
import { createSignal } from "solid-js";

const [settings, setSettings] = createSignal({
  displayName: "Ada",
  timezone: "Europe/London",
});

const form = createForm(settingsForm, {
  plugins: [signal(settings, setSettings)],
});
```

The binding can also go in the definition's `plugins` when the signal lives at
module scope. Passed to `createForm`, it runs after the shared plugins and the
definition's.

The compiler checks that the form's value type is the signal's type, and that
the getter and setter share it.

## Timing

A form write sets the signal right away. A signal change reaches the form when
Solid runs its effects, not in the same line of code.

The binding watches the signal with an effect in a root of its own. It makes
the root when the form gets its first listener, which is when its fields
mount, and disposes it when the last one goes. Listening again catches up with
the signal. The setter runs outside any owner, so a form write made inside a
component or a memo sets the signal where Solid would otherwise throw.

A form has one binding.

## Options

| Option | Default | What it does |
| --- | --- | --- |
| `initial` | `"outside"` | Where the starting value comes from. `"outside"` starts the form from the signal, server render included. `"form"` keeps the form's defaults and sets the signal to them when the form is first listened to. |
| `incoming` | `"replace"` | What a signal change does to the form. `"replace"` writes the signal's value over the form's. `"rebase"` moves the form's baseline to it and keeps the fields the user edited. A function picks per field, as [rebase](https://forms.lunarhue.dev/solid/plugins/rebase.md) does. |

```tsx
signal(settings, setSettings, { initial: "form", incoming: "rebase" });
```

For anything other than a signal, such as a Solid store, `bind()`
from `@lunarhue/forms-solid/plugins` takes `get`, `set` and `subscribe`
functions and the same two options.
