Access plugin state from script block

[logaretm]

What

Following the release of slotBinds (#194), It provided a way for plugins to expose state to the SchemaForm slots.

However it doesn't cover most of the needs, some plugins would probably need to also expose a way to mutate their state. This is hard to do in the template, consider the following example where the user would like to reset the form after the submission is processed.

That means in order to do that with the template the user needs to pass the plugins API function as a callback to their own function, resulting in something like this:

<!-- user would like to submit then reset the form -->
<SchemaFormWithValidation>
  <template #afterForm="{ resetForm }">
    <button type="button" @click="submit(resetForm)">Submit</button>
  </template>
</SchemaFormWithValidation>

async function submit(resetCb) {
  // do async/await stuff...
  resetCb(); // reset the form
}

This can be fine for some cases but I think it's a little bit unhandy to most. So we need to figure a way for plugins to expose their APIs in the parent's setup function with the composition API.

How

I tried to think of this in a non-breaking manner, and I got a working PoC, but it has some caveats.

The main challenge here is plugins now to somehow inject their state upwards (towards the parent). Which is the opposite direction of provide/inject, this makes it a little bit hard to reason about.

Initially, we can re-use useSchemaForm and have it return a plugins reactive object alongside the formModel.

export default function useSchemaForm (initialFormValue = {}) {
  // ....
  provide(FORM_PLUGIN_STATE, plugins)

  return {
    formModel,
    plugins
  }
}

That plugins object will be provided to all plugin functions via provide/inject and they can add stuff to it:

function VeeValidatePlugin (opts) {
  // Maps the validation state exposed by vee-validate to components
  var mapProps = (opts && opts.mapProps) || defaultMapProps;

  return function veeValidatePlugin (baseReturns) {
    var plugins = inject('fvl_pluginState');

   // utilizes the auto-unwrapping behavior of objects created with `reactive()`:
    plugins.validation = computed(() => {
      return {
       // expose some stuff
        errors: formContext.errors.value,
        values: formContext.values,
        setFieldTouched: formContext.setFieldTouched,
        resetForm: formContext.resetForm,
      }
    })
    // rest of plugin code...
  }
}

Eventually it can be used like this:

const formData = ref({});
const { plugins } = useSchemaForm(formData);

const schema = [
  // some schema...
]

function onSubmit() {
  // uses the plugin's API
  plugins.validation.setErrors({
    field: "Already exists"
  });
}

This is as far as I got the PoC to work.

The caveat here is that the plugins are not immediately available within the parent's setup. This is because the plugin function will execute once the SchemaForm is setup.

const { plugins } = useSchemaForm(formData);

plugins.validation; // undefined

I can see this being a foot gun even if properly documented. A simple workaround to make it clear to the users is to make it lazily evaluated via a function.

const { getPlugins } = useSchemaForm(formData);

getPlugins('validation'); // undefined, maybe log a warning.

function onSubmit() {
  getPlugins('validation').resetForm();
}

This is just a slight API change that could force users to be more carful around this. I think its hacky tho.

An actual possible workaround is to use something different than useSchemaForm, perhaps a similarly named function created by SchemaFormFactory.

This would allow plugins to "prepare" dummy values initially that can be used until the form is setup. Sounds hacky but it move this responsibility to plugin authors which I would agree are more likely to be advanced users than the average and so could take on this caveat.

The usage for the end user looks something like this:

const SchemaFormWithValidation = SchemaFormFactory([
  VeeValidatePlugin({
    // plugin configuration here
  })
])

const { useFormSchema } = SchemaFormWithValidation;

The way this would work, is that the SchemaFormFactory will prepare a reactive object for plugins to dump stuff in. Plugins could expose beforeSetup method on their return value to allow them to "attach" their state before the user calls useSchemaForm.

So a plugin fn may look like this:

function somePlugin () {
   // same code
}

somePlugin.beforeSetup = (plugins) => {
  // add dummy object, will be overwritten later by the same plugin's setup code.
  plugins.validation = computed(() => { ... });
}

I probably haven't thought about this enough, LMK what you think!

[marina-mosti]

Hey @logaretm thanks for the detailed idea.

I think the lib is young enough where we can still somewhat liberally release a breaking change with minimal impact.
I am not a huge fan of approach #1, I had thought of something similar and could never get past the problem of what you called the "foot gun". This approach will eventually and definitely bite us in the ass.

I think the second approach is better suited, but I'm not afraid to make a breaking change (?) here where we could potentially do something in the lines of:

const { SchemaForm, Plugins } = SchemaFormFactory([])

This will also open up the road for being able to add more stuff to the return of SchemaFormFactory if/when needed.
This feels like a good moment to do it, as libs like vuex and router and taking similar approaches so users should be fairly comfortable with such an API.

Thoughts?

[logaretm]

I don't mind introducing breaking changes, was just trying to avoid them if possible. Anyway, I assume it would look like this?

const { SchemaForm, useSchemaForm } = SchemaFormFactory([])

// in setup
const { plugins, formModel } = useSchemaForm();

[marina-mosti]

I feel like I'm missing something, why do you want to return a useSchemaForm function from here instead of the one that is imported from the lib itself? That seems very confusing to me. Can you clarify why this would be needed?

From my point of view:
SchemaFormFactory is injecting and receiving all the elements from plugins around ln 16-20.
Here is where I was thinking we can pass in a new param to the plugin function with the shared plugin configuration object, and then return it directly from the factory.

Unless I'm envisioning things wildly different from you. But I think we will need to maybe wait and see on actual development how it works best :)

[logaretm]

Why do you want to return a useSchemaForm function from here instead of the one that is imported from the lib itself?

Oh, I skimmed on that part. It's tied to where the users will get the plugins object from, so if it is from the original useSchemaForm then we won't be able to type it properly with TypeScript. So returning another differently typed version from useSchemaForm is one way to go about it.

But if we were to use some other thing to provide the same functionality, like:

const { SchemaForm, Plugins } = SchemaFormFactory([])


// in setup
export default {
  setup() {
    // same thing
    const validationApi = Plugins.validation;
  }
}

Maybe that's for the better so as not to confuse anybody with multiple functions of the same name. I will try to take a jab at this and see how it looks since I'm not sure yet how it will all work.

[marina-mosti]

Sounds good, thanks!
Wonder if we should push the monorepo first so that's its easier to test/develop this. Wdyt?

[logaretm]

Definitely 👍