Repository navigation
feat(ember-form): add Ember adapter (@tanstack/ember-form) #2156
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
NullVoxPopuli-ai-agent
wants to merge
23
commits into
TanStack:main
Choose a base branch
from
NullVoxPopuli-ai-agent:ember-form-adapter
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+9,903
−194
Draft
Changes from all commits
Commits
Show all changes
23 commits
Select commit
Hold shift + click to select a range
e99a7d3
feat(ember-form): add Ember adapter
NullVoxPopuli 56454b8
feat(ember-form): closure-bound this.form.Field
NullVoxPopuli 5816eb1
feat(ember-form): address review — trackedObject, reactive args, docs
NullVoxPopuli fbfd92f
feat(ember-form): bump ember-source to 7.1.0-alpha.5, strip `on`/`fn`…
NullVoxPopuli 290b230
chore(ember-form): address review notes + self-cleanup pass
NullVoxPopuli c7b14f3
feat(ember-form)!: refactor createForm into a component factory
NullVoxPopuli 5894482
docs(ember-form): adopt tanstackForm / f block-param convention
NullVoxPopuli 905b525
chore(ember-form): align with NullVoxPopuli/ember-primitives conventions
NullVoxPopuli 381e565
style(ember-form): apply the repo prettier config
NullVoxPopuli 85f19f9
refactor(ember-form): typed Field, useSelector, one subscription per …
NullVoxPopuli c4f631a
docs(ember-form): show the quick start in a class-based component
NullVoxPopuli d645fe9
docs(ember-form): explain why the examples do not use the name `form`
NullVoxPopuli 9cde168
test(ember-form): cover the behaviors that the other adapters test
NullVoxPopuli 84b3803
ci(ember-form): run the browser tests on the GitHub runner
NullVoxPopuli 51f6d2b
perf(ember-form): de-dupe store tracking per key
NullVoxPopuli ce9fce2
feat(ember-form): support ember-source 6.8
NullVoxPopuli 1a23626
refactor(ember-form): plain getters instead of a Proxy in trackStore
NullVoxPopuli 2bce6e2
revert(ember-form): the minimum is ember-source 7.1, not 6.8
NullVoxPopuli 4dbba13
perf(ember-form): one render pass, and no option updates on a keystroke
NullVoxPopuli 2655f59
docs(ember-form): keyed array rows, tracked form state, fixed examples
NullVoxPopuli a3a10bd
ci(ember-form): install ember-source 7.1 for the oldest-version job
NullVoxPopuli 1ed4884
docs(ember-form): list the open work in TODO.md
NullVoxPopuli 045e352
refactor(ember-form): give Field live options, and document the updat…
NullVoxPopuli File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,116 @@ | ||
| --- | ||
| id: arrays | ||
| title: Arrays | ||
| --- | ||
|
|
||
| TanStack Form supports arrays as values in a form, including sub-object values inside of an array. | ||
|
|
||
| ## Basic Usage | ||
|
|
||
| > The examples name the form component `PeopleForm` and the yielded form `tanstackForm`. [Why not `form`?](./basic-concepts.md#why-not-form) explains the names. | ||
|
|
||
| To use an array, you can iterate over `field.state.value` with [`{{#each}}`](https://api.emberjs.com/ember/release/classes/Ember.Templates.helpers/methods/each): | ||
|
|
||
| ```gjs | ||
| import { createForm } from '@tanstack/ember-form'; | ||
|
|
||
| const PeopleForm = createForm({ | ||
|
NullVoxPopuli-ai-agent marked this conversation as resolved.
Resolved
|
||
| defaultValues: { | ||
| people: [], | ||
| }, | ||
| }); | ||
|
|
||
| <template> | ||
| <PeopleForm as |tanstackForm|> | ||
| <tanstackForm.Field @name="people" @mode="array" as |field|> | ||
| {{#each field.state.value key="@index" as |person|}} | ||
| {{!-- ... --}} | ||
| {{/each}} | ||
| </tanstackForm.Field> | ||
| </PeopleForm> | ||
| </template> | ||
| ``` | ||
|
|
||
| Always pass `key="@index"`. Without it, `{{#each}}` identifies a row by its value. form-core replaces the value of a row on each change, so the row renders from the start and its input loses the focus. | ||
|
|
||
| This will regenerate the list every time you run `pushValue` on `field`: | ||
|
|
||
| ```gjs | ||
| const addPerson = (field) => field.pushValue({ name: '', age: 0 }); | ||
|
|
||
| {{!-- inside a template --}} | ||
| <button {{on "click" (fn addPerson field)}} type="button"> | ||
| Add person | ||
| </button> | ||
| ``` | ||
|
|
||
| Finally, you can use a subfield like so: | ||
|
|
||
| ```gjs | ||
| const handleInput = (field, event) => field.handleChange(event.target.value); | ||
| const nameAt = (i) => `people[${i}].name`; | ||
|
|
||
| {{!-- inside a template --}} | ||
| <tanstackForm.Field @name={{nameAt i}} as |subField|> | ||
| <input | ||
| value={{subField.state.value}} | ||
| {{on "input" (fn handleInput subField)}} | ||
| /> | ||
| </tanstackForm.Field> | ||
| ``` | ||
|
|
||
| ## Full Example | ||
|
|
||
| ```gjs | ||
| import { createForm } from '@tanstack/ember-form'; | ||
|
|
||
| const handleInput = (field, event) => field.handleChange(event.target.value); | ||
| const nameAt = (i) => `people[${i}].name`; | ||
| const addPerson = (field) => field.pushValue({ name: '', age: 0 }); | ||
|
|
||
| const onSubmitFor = (form) => (event) => { | ||
| event.preventDefault(); | ||
| event.stopPropagation(); | ||
| form.handleSubmit(); | ||
| }; | ||
|
|
||
| const handleSubmit = ({ value }) => alert(JSON.stringify(value)); | ||
|
|
||
| const PeopleForm = createForm({ | ||
| defaultValues: { | ||
| people: [], | ||
| }, | ||
| }); | ||
|
|
||
| <template> | ||
| <PeopleForm @onSubmit={{handleSubmit}} as |f|> | ||
| <form id="form" {{on "submit" (onSubmitFor f)}}> | ||
| <f.Field @name="people" @mode="array" as |field|> | ||
| <div> | ||
| {{#each field.state.value key="@index" as |_person i|}} | ||
| <f.Field @name={{nameAt i}} as |subField|> | ||
| <div> | ||
| <label> | ||
| <div>Name for person {{i}}</div> | ||
| <input | ||
| value={{subField.state.value}} | ||
| {{on "input" (fn handleInput subField)}} | ||
| /> | ||
| </label> | ||
| </div> | ||
| </f.Field> | ||
| {{/each}} | ||
|
|
||
| <button {{on "click" (fn addPerson field)}} type="button"> | ||
| Add person | ||
| </button> | ||
| </div> | ||
| </f.Field> | ||
|
|
||
| <button type="submit">Submit</button> | ||
| </form> | ||
| </PeopleForm> | ||
| </template> | ||
| ``` | ||
|
|
||
| > Note: in strict-mode templates you can't put complex expressions like `` `people[${i}].name` `` directly into an attribute or argument value. The `nameAt` helper above is a small module-level function that does the templating in JavaScript and is then invoked as `{{nameAt i}}`. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| --- | ||
| id: async-initial-values | ||
| title: Async Initial Values | ||
| --- | ||
|
|
||
| Let's say that you want to fetch some data from an API and use it as the initial value of a form. | ||
|
|
||
| While this problem sounds simple on the surface, there are hidden complexities you might not have thought of thus far. | ||
|
|
||
| For example, you might want to show a loading spinner while the data is being fetched, or you might want to handle errors gracefully. Likewise, you could also find yourself looking for a way to cache the data so that you don't have to fetch it every time the form is rendered. | ||
|
|
||
| While we could implement many of these features from scratch, it would end up looking a lot like another project we maintain: [TanStack Query](https://tanstack.com/query). | ||
|
|
||
| As such, this guide shows you how you can mix-n-match TanStack Form with a data-loading utility (such as [`ember-resources`](https://github.com/NullVoxPopuli/ember-resources), [warp-drive](https://github.com/emberjs/data), or your own routing layer) to achieve the desired behavior. | ||
|
|
||
| ## Basic Usage | ||
|
|
||
| The general shape of the solution is: | ||
|
|
||
| 1. Load the data outside of the form (in a route, a resource, or a parent component). | ||
| 2. Render the form only once the data is available, passing the resolved values into the invocation as `@defaultValues`. | ||
|
|
||
| Because `createForm` is called at module scope, the component it returns is constructed every time it's invoked in a template. The simplest pattern is to render the form invocation inside an `{{#if}}` that gates on the loading state and pass the resolved data as `@defaultValues`. An arg on the invocation replaces the same key in the options of `createForm`, so `@defaultValues` replaces the fallback values. | ||
|
|
||
| ```gjs | ||
| // person-form.gts | ||
| import { createForm } from '@tanstack/ember-form'; | ||
|
|
||
| const handleInput = (field, event) => field.handleChange(event.target.value); | ||
|
|
||
| const onSubmitFor = (form) => (event) => { | ||
| event.preventDefault(); | ||
| event.stopPropagation(); | ||
| form.handleSubmit(); | ||
| }; | ||
|
|
||
| const handleSubmit = async ({ value }) => { | ||
| // Do something with form data | ||
| console.log(value); | ||
| }; | ||
|
|
||
| const PersonForm = createForm({ | ||
| // Fallback values. `@defaultValues` replaces them. | ||
| defaultValues: { | ||
| firstName: '', | ||
| lastName: '', | ||
| }, | ||
| }); | ||
|
|
||
| <template> | ||
| <PersonForm | ||
| @defaultValues={{@initial}} | ||
| @onSubmit={{handleSubmit}} | ||
| as |f| | ||
| > | ||
| <form {{on "submit" (onSubmitFor f)}}> | ||
| <f.Field @name="firstName" as |field|> | ||
| <input | ||
| name={{field.name}} | ||
| value={{field.state.value}} | ||
| {{on "blur" field.handleBlur}} | ||
| {{on "input" (fn handleInput field)}} | ||
| /> | ||
| </f.Field> | ||
| <f.Field @name="lastName" as |field|> | ||
| <input | ||
| name={{field.name}} | ||
| value={{field.state.value}} | ||
| {{on "blur" field.handleBlur}} | ||
| {{on "input" (fn handleInput field)}} | ||
| /> | ||
| </f.Field> | ||
| <button type="submit">Submit</button> | ||
| </form> | ||
| </PersonForm> | ||
| </template> | ||
| ``` | ||
|
|
||
| ```gjs | ||
| // page.gts | ||
| import Component from '@glimmer/component'; | ||
| import { getPromiseState } from 'reactiveweb/get-promise-state'; | ||
| import PersonForm from './person-form.gts'; | ||
|
|
||
| async function loadPerson() { | ||
| await new Promise((resolve) => setTimeout(resolve, 1000)); | ||
|
|
||
| return { firstName: 'FirstName', lastName: 'LastName' }; | ||
| } | ||
|
|
||
| export default class PersonPage extends Component { | ||
| request = loadPerson(); | ||
|
|
||
| get person() { | ||
| return getPromiseState(this.request); | ||
| } | ||
|
|
||
| <template> | ||
| {{#if this.person.isLoading}} | ||
| <p>Loading...</p> | ||
| {{else if this.person.error}} | ||
| <p>The person did not load.</p> | ||
| {{else}} | ||
| <PersonForm @initial={{this.person.resolved}} /> | ||
| {{/if}} | ||
| </template> | ||
| } | ||
| ``` | ||
|
|
||
| The page shows the loading text until the promise resolves. `<PersonForm>` renders only after that, so the form starts with the fetched values. | ||
|
|
||
| > The example uses `getPromiseState` from [`reactiveweb`](https://github.com/universal-ember/reactiveweb). It derives `isLoading`, `error`, and `resolved` from a promise, so the component has no loading flags of its own. Any other source of data works the same way: a route model, ember-resources, or warp-drive. Do not render the form until the data is ready. | ||
|
|
||
| ## Updating defaults after the form is mounted | ||
|
|
||
| To render the form immediately, pass the loaded values when they arrive. The form applies changed args by itself. | ||
|
|
||
| ```gjs | ||
| <PersonForm @initial={{this.person.resolved}} /> | ||
| ``` | ||
|
|
||
| New default values do not replace the input of a user. A field that the user touched keeps its value. |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
we test in the browser, becaues thats where our users are
(the typical (end-)user is not running jsdom in node)