mst-form-type documentation in markdown as we talked in email

[sherlockwang]

What does this PR do and why?

If this pull request is approved, it will add a document for a library built on mobx-state-tree.

As Tyler and me discussed via email, I wrote a brief doc for mst-form-type library. Please have a look and feel free to ask any questions.

Thanks.

Steps to validate locally

No code change has been made. So there is no need to validate the code.

[coolsoftwaretyler]

Thanks @sherlockwang! I will take a look now.

I'll probably make some suggestions, and once we get to a good place, I'll move things around for the actual website. I've got a plan for where to put this.

[coolsoftwaretyler]

Hey @sherlockwang - this is a great start! Thanks so much for building your library and for writing these docs.

I've made a few suggestions. Some of them are intended to fix spelling and grammar issues. Others are based on my own preferences for writing style.

In addition to those suggestions, I've asked some questions where I think this document could add more detail.

Most importantly, I'd love to get a more detailed problem statement (perhaps an example of how using Ant Design with MST has been challenging in the past), and a more thorough example (you could use the same Ant Design/MST challenge and solve it with your library).

Thanks again for all your time on this. Looking forward to the next draft!

[sherlockwang]

Hi Tyler, Thanks for all your suggestions and hard work. From my understanding, I need to improve the doc in two aspects. One is making a more detailed example especially showing the hardness using libraries like Ant Design and MST. I think that is very useful and will give users a better vision of why I made mst-form-type. The other is pulling as much content as possible from the npm doc, right? At first, I'm actually trying to avoid copying content from that, because I think people can just go to the npm page for the library documentation. But as you suggested, I will create a more realistic example to include as many features as I can. I already have a good scenario. Please wait for a few days for me to finish it. Finally, sorry for the grammar and spell issues. It has been quite a long time for me to write a long English doc like this. But I will try to improve myself next time. Thanks. Best regards, Jinghan Wang

…

On Fri, Mar 15, 2024 at 10:33 PM Tyler Scott Williams < ***@***.***> wrote: ***@***.**** requested changes on this pull request. Hey @sherlockwang <https://github.com/sherlockwang> - this is a great start! Thanks so much for building your library and for writing these docs. I've made a few suggestions. Some of them are intended to fix spelling and grammar issues. Others are based on my own preferences for writing style. In addition to those suggestions, I've asked some questions where I think this document could add more detail. Most importantly, I'd love to get a more detailed problem statement (perhaps an example of how using Ant Design with MST has been challenging in the past), and a more thorough example (you could use the same Ant Design/MST challenge and solve it with your library). Thanks again for all your time on this. Looking forward to the next draft! ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > @@ -0,0 +1,95 @@ +# MST Form Type + +npm: https://www.npmjs.com/package/mst-form-type ⬇️ Suggested change -npm: https://www.npmjs.com/package/mst-form-type +Find the `mst-form-type` library on npm: https://www.npmjs.com/package/mst-form-type. *suggestion:* I'd prefer to lead with a full sentence if you don't mind. ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > @@ -0,0 +1,95 @@ +# MST Form Type + +npm: https://www.npmjs.com/package/mst-form-type + +## Introduction + +Librarys like Ant Design has a build-in Form component that can hold fields status and validation rules. This component houses its own store to sustain internally related field statuses and can be conveniently used independently. integrating Form component with MobX State Tree models can pose significant challenges as business logic grows intricately complex. ⬇️ Suggested change -Librarys like Ant Design has a build-in Form component that can hold fields status and validation rules. This component houses its own store to sustain internally related field statuses and can be conveniently used independently. integrating Form component with MobX State Tree models can pose significant challenges as business logic grows intricately complex. +Libraries like [Ant Design](https://ant.design/) have a built-in `Form` component that holds field status and validation rules. Integrating a `Form` component with MobX State Tree models can pose significant challenges as business logic become more complex. *suggestion:* I'd like to fix some spelling and grammar errors here, and also clarify some of the sentences. ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > @@ -0,0 +1,95 @@ +# MST Form Type + +npm: https://www.npmjs.com/package/mst-form-type + +## Introduction + +Librarys like Ant Design has a build-in Form component that can hold fields status and validation rules. This component houses its own store to sustain internally related field statuses and can be conveniently used independently. integrating Form component with MobX State Tree models can pose significant challenges as business logic grows intricately complex. *question:* can you please list a few examples of those challenges? It would be great to articulate more about why the Form component is hard to use with MST models. ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > @@ -0,0 +1,95 @@ +# MST Form Type + +npm: https://www.npmjs.com/package/mst-form-type + +## Introduction + +Librarys like Ant Design has a build-in Form component that can hold fields status and validation rules. This component houses its own store to sustain internally related field statuses and can be conveniently used independently. integrating Form component with MobX State Tree models can pose significant challenges as business logic grows intricately complex. + +The `mst-form-type` library comes into play. It provides the field management feature of Ant Design Form component in Mobx State Tree model way. Users can only use the UI of a component library, but keep logic inside your Mobx State Tree model context, instead of syncing status changes between Form component and model. ⬇️ Suggested change -The `mst-form-type` library comes into play. It provides the field management feature of Ant Design Form component in Mobx State Tree model way. Users can only use the UI of a component library, but keep logic inside your Mobx State Tree model context, instead of syncing status changes between Form component and model. +That's where a solution like `mst-form-type` library comes into play. It models the Ant design field management like a conventional MobX-State-Tree type definition. Users can still use the UI of a component library and keep logic inside MobX-State-Tree, instead of syncing status changes between `Form` component and model. *suggestion:* I reworded a few things and fixed spelling/grammar errors here. ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > + +1. Install the `mst-form-type` library via npm: + +```sh +npm install mst-form-type +``` + +2. Ensure you have `mobx-state-tree ^5.0.0` installed: + +```sh +npm install mobx-state-tree@^5.0.0 +``` + +3. Declare a form schema and create the form model, subsequently, all the relevant field models would then be created in a form model. An example schema look like this: + +```typescript *suggestion:* can you show a full example, including all the imports, this schema definition, and then how the library would use it? I see something like that on npm: // render dynamic fieldsmodel.dynamicForm['price'].fields.map(fields => ({ ... })) // field actionmodel.dynamicForm.onAdd('price') // this will use field default value in schemamodel.dynamicForm.onRemove('price', fields.id) // form actionmodel.dynamicForm.submit()model.dynamicForm.reset()model.dynamicForm.clear('price') // this will clear all dynamic fields, including default ones ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > + itemPrice: 20, + }, + ], + onAdd: i => { + console.log('add', i) + }, + onRemove: i => { + console.log('remove', i) + }, + onEdit: key => { + console.log('edit', key) + }, + }, + ], +} +``` *suggestion:* can you go over the different types of fields? I'd love to pull more of the docs from npm <https://www.npmjs.com/package/mst-form-type> into this if possible. Maybe create an example of a form you've used in the past, and explain the use cases for different syntax. It's OK if you want to just cover the basic fields, as well. One way or another, it would be awesome to get a more realistic example here. ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > + console.log('add', i) + }, + onRemove: i => { + console.log('remove', i) + }, + onEdit: key => { + console.log('edit', key) + }, + }, + ], +} +``` + +## How It Works + +The `mst-form-type` library exports a function, which creates a form model based on the base form model underhood using a form schema and an optional name. Each form type model implements its own type, and every attribute and method is independent. The user can conveniently interact with the form field via form props, or apply the form model action to directly get or set field values. ⬇️ Suggested change -The `mst-form-type` library exports a function, which creates a form model based on the base form model underhood using a form schema and an optional name. Each form type model implements its own type, and every attribute and method is independent. The user can conveniently interact with the form field via form props, or apply the form model action to directly get or set field values. +The `mst-form-type` library exports a function which creates a form model (based on the base form model under the hood) using the provided schema and an optional name. Each form type model implements its own type, and every attribute and method is independent. The user can conveniently interact with the form field via form props, or apply the form model actions to directly get or set field values. *suggestion:* fixed some spelling and grammar errors. ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > + console.log('add', i) + }, + onRemove: i => { + console.log('remove', i) + }, + onEdit: key => { + console.log('edit', key) + }, + }, + ], +} +``` + +## How It Works + +The `mst-form-type` library exports a function, which creates a form model based on the base form model underhood using a form schema and an optional name. Each form type model implements its own type, and every attribute and method is independent. The user can conveniently interact with the form field via form props, or apply the form model action to directly get or set field values. *question:* what does it mean when you say "every attribute and method is independent"? ------------------------------ In docs/libraries/mst-form-type.md <#2168 (comment)> : > + onRemove: i => { + console.log('remove', i) + }, + onEdit: key => { + console.log('edit', key) + }, + }, + ], +} +``` + +## How It Works + +The `mst-form-type` library exports a function, which creates a form model based on the base form model underhood using a form schema and an optional name. Each form type model implements its own type, and every attribute and method is independent. The user can conveniently interact with the form field via form props, or apply the form model action to directly get or set field values. + +## Architecture *suggestion:* can you add more detail to this section about how these three entities work together with the schema to become what the user will end up working with? — Reply to this email directly, view it on GitHub <#2168 (review)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJ23EOQPBPOCPEONGW32XDYYMBBXAVCNFSM6AAAAABEXIVI76VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMYTSMZZGA3DQMJZGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[coolsoftwaretyler]

Hey @sherlockwang - yup, that's exactly what I'm looking for here, for the most part. Don't feel pressure to include more details from npm than feels natural, but I think if you start with a clear example, more of the API will make sense to discuss in detail.

Thanks for all your effort on this, don't worry about the grammar and spelling. I'm always happy to fix that on my end. We are really excited to include your work in the docs!

[sherlockwang]

Hi @coolsoftwaretyler ,

Sorry for the delay, this work suppose to be done last week.

I have updated the doc with an comparative example and documetation of all APIs. Please have a look. Let me know if you have any questions.

Thanks and have a nice day!

[coolsoftwaretyler]

Thanks @sherlockwang! I'll take a look in the coming days.

[coolsoftwaretyler]

Hey @sherlockwang - this is amazing! The edits are phenomenal.

I went through and:

1. Relocated the docs to our "recipes" section
2. Fixed some syntax highlighting in the code fences by changing the typescript designation to tsx
3. Reworded just a couple of small things (removed a header, removed some asides, fixed on grammar issue I saw)

I'm going to merge this in, then I'll publish to the site. Later today, it should be available at https://mobx-state-tree.js.org/recipes/pre-built-form-types-with-mst-form-type

Thanks so much for your contribution! Please feel free to submit changes, or any other cool stuff you're doing around MST. Really appreciate it.

[sherlockwang]

Hi Tyler, Thanks for all your help. Feel free to make any changes if you need it. I really appreciate that I have a chance to contribute to MST project. I will definitely let you know if I come up with some new ideas. And please let me know when you need any help from. Have a great weekend! Best regards, Jinghan Wang

…

On Thu, Apr 4, 2024 at 10:26 PM Tyler Scott Williams < ***@***.***> wrote: Merged #2168 <#2168> into master. — Reply to this email directly, view it on GitHub <#2168 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACJ23EJPO37BFNBETKIC37DY3VPKNAVCNFSM6AAAAABEXIVI76VHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJSGM2TSMRZG4ZDMMI> . You are receiving this because you were mentioned.Message ID: ***@***.***>