future/report: Updating a subset of fields

[transparent-citizen]

If you have a form with a lot of fields, updating just one of them is possible using client-side JavaScript via intent.update.

However, if you're trying to update a single field through the server, you will find that the report API uses a different update mechanism.

Going through report, you must either update every field (via reset: true, constructing a complete targetValue if desired) or none of them (by using report only to pass validation errors to the UI).

It would be useful if the intent and report APIs were more similar to one another. This might also help get around some data races like #1095. The reason for that is that the point of onInput={submitForm} is not primarily to update the field you're typing into, but usually to update dependent fields.

Currently, the smallest API change enabling such behavior would be something like:

report(submission, {
    partial: true, // <--- this means set "foo", but don't touch other fields
    reset: true,
    targetValue: {
        foo: "bar"
    },
})

[edmundhung]

report API uses a different update mechanism.

I am curious why you think this way. To me they are exactly the same. intent.reset and reset: true uses the same reset mechanism. While intent.update and other intents uses the same update mechanism as you do report(submission, { targetValue: { ... } }).

In fact, targetValue was purely designed for handling intent in the server. The API is not finalized yet but here is the idea:

export async function action (request: Request) {
  const formData = await request.formData();
  const submission = parseSubmission(formData);

  // This will deserialize the intent and update submission.value based on the intent
  // e.g. intent.update('name', 'test') will result in `{ ...submission.value, name: 'test' }`
  const [value, intent] = applyIntent(submission.value, submission.intent);
 
  // Parse the updated value instead of submission.value
  // as the error should always refers to the updated version
  const result = schema.safeParse(value);
  
  if (!result.success || intent) {
    return report(submission, {
      error: result.error,
      // Send the updated value back to client so it is reflected there
      targetValue: value,
    });
  }
  
  // ...
}

[transparent-citizen]

Referring to it as different update mechanism was imprecise, my bad. 😅 What I meant was that the useIntent and report APIs don't seem to implement the same set of operations:

Operation 1: Reset all fields to current defaultValue

API	Supported?	How to do it
useIntent	✅	intent.reset()
report	✅	report(submission, { reset: true })

Operation 2: Reset all fields to a new defaultValue

API	Supported?	How to do it
useIntent	✅	intent.reset({ foo: "bar", baz: "quux" })
report	✅	report(submission, { reset: true, targetValue: { foo: "bar", baz: "quux" })

Operation 3: Update single field, leaving others untouched

API	Supported?	How to do it
useIntent	✅	intent.update({ name: "foo", value: "update!" })
report	❌	🧪 could be done via partial as noted in previous post

Operation 4: Update multiple fields, leaving others untouched

API	Supported?	How to do it
useIntent	⚠️	Multiple invocations of intent.update
report	❌	🧪 could be done via partial as noted in previous post

[transparent-citizen]

The following could create the illusion that it's possible to perform operations 3 and 4 with report:

const searchParams = new URL(request.url).searchParams;
const submission = parseSubmission(searchParams);
const result = schema.safeParse(submission.payload);

report(submission, {
    targetValue: {
        ...result.data, // <-- spread the submitted data
        foo: "bar"
    }
})

The code makes it look like the field named "foo" changes its value to "bar" while all the other fields will keep their values, but they might have changed their values by the time targetValue is applied (see #1095). The goal would be for these fields to keep their future values, not their current values.

When the browser receives targetValue and applies it to the form, all fields are overwritten, not just "foo". And if you don't spread the submitted data like above, all the other fields will be set to an empty string.

With intent.update, the user can specify a partial state that only overwrites a single field and leaves other fields untouched.

But with report, the user has to provide a full state that replaces the form state at the time of the update.

[transparent-citizen]

updateValue as opposed to targetValue could be a more natural way to cover the ❌ operations:

report(submission, {
    // update foo to "1"
    //    and bar to "2", leave rest unchanged
    updateValue: {
        foo: "1",
        bar: "2"
    }
})

[edmundhung]

I am curious what real-world scenarios you are hoping to support with targetValue here. The current behaviour is closer to an initialValue: it defines what the form starts with rather than updating an existing value. This is also why I liked your original idea of adding intendedValue support with reset: true.

A couple of details that might help frame things:

• Intents are handled on the client by default. The only time they reach the server is during a full document reload, and in that case the value becomes the form's initial state again.
• When the server resets the form, the returned value is also treated as the new initial value.

I am sure there are scenarios you have in mind that I have missed. Would you mind starting with those? It would help me understand how these APIs could support your use case.

[transparent-citizen]

The scenario I'm hoping to support is something like this. Say we have a site that offers shoes. The search page has a GET form with two fields:

• an <input name="query"> for a shoe-related search query, and
• a <select name="brand"> to choose a certain brand.

As the user submits "query=air", this information would be enough for the server to narrow down the search results to Nike-branded shoes. It would be helpful to the user if the form could reflect the narrowing as well, by updating the value of the <select> to "nike". By doing this, the form can be used to inform the user that the only available shoes matching "air" are Nike-branded.

But note that there is a chance that the user is still typing into <input name="query"> by the time we attempt to update the form. If conform were to overwrite the query value while typing, it would lead to staleness bugs. So replacing the entire form state would be error-prone:

report(submission, {
    targetValue: {
        query: "air",
        brand: "nike"
    }
})

Instead, report could have the ability to update just the <select> while <input> remains untouched, basically an equivalent to intent.update for the server:

report(submission, {
    updateValue: {
        brand: "nike"
    }
})

This would enable the user to freely type into the <input> without its value ever being replaced by the server, while dependent fields like <select> could be updated.