DEV Community: Abdelrahman Awad

Generically Typed Vue.js Components

Abdelrahman Awad — Thu, 12 Aug 2021 17:00:00 +0000

One of the most productive features of TypeScript is Generics.

Generics allow you to create reusable bits of code, be it classes or functions and once you learn and understand them, you won't stop using them.

But it has always eluded me how to make Vue components with them, Let's explore our options.

Prerequisites

This article...

assumes you are using volar for Vue.js TypeScript tooling.
is a Vue.js 3 article
focuses on the composition API

The problem

Let's sketch an example of a component that will benefit from using generics, the simplest best example I can think of is a "select" or a "multi-select" component.

Such components always have an ecosystem of features operating on a specific type.

For example, if you are passing a string option to the component, It only makes sense it will only provide string for the model value and will operate on strings in general.

That's also true for complex values, a list of users will have a value of a user object and will perform operations and emits events with the user type.

The easy way out is to use any or better yet unknown, so this component is often implemented like this:

<template>
  <div>
    <!-- Template is irrelevant -->
  </div>
</template>

<script lang="ts">
import { defineComponent, PropType } from 'vue';

export default defineComponent({
  name: 'InputSelect',
  props: {
    options: {
      type: Array as PropType<unknown[]>,
      required: true,
    },
    value: {
      type: null as unknown as PropType<unknown | undefined>,
      default: undefined as unknown,
    },
  },
  emits: {
    change: (payload: unknown) => true,
  },
});
</script>

The problem with this component now is when you use it, you can never ensure type safety when passing values or receiving them.

Usually you will use the InputSelect like this:

<template>
  <InputSelect
    :options="options"
    :value="selectedOption"
    @change="handleChange"
  />
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';
import InputSelect from './InputSelect.vue';

export default defineComponent({
  components: {
    InputSelect,
  },
  setup() {
    const options = ref(['1', '2', '3']);
    const selectedOption = ref('');

    function handleChange(option: string) {
      console.log(option);
    }

    return {
      options,
      selectedOption,
      handleChange,
    };
  },
});
</script>

Notice that you will get an error with @change being assigned to handleChange.

This is because handleChange expects a string type while the InputSelect may pass anything to the @change handler. After all, it is typed as unknown so anything goes. This forces you to cast the value sent from the component before you can use it:

function handleChange(option: unknown) {
  const str = option as string;
  // do stuff...
}

This is unfortunate because you know for a fact that option value will always be a string.

If only there was a way to make your editor (vscode + volar) understand that 🤔.

The struggle

Wrapper Function

One idea that you will find after a quick search is to use a wrapper generic function:

import { defineComponent, PropType } from 'vue';

function defineGenericComponent<T = unknown>() {
  return defineComponent({
    props: {
      options: {
        type: Array as PropType<T[]>,
        required: true,
      },
      value: {
        type: null as unknown as PropType<T | undefined>,
        default: undefined as unknown,
      },
    },
    emits: {
      change: (payload: T) => true,
    },
  });
}

This looks promising, but you cannot use it inside an SFC because of how the compiler works and how it assigns the render function to the default export. Also even if it worked, there is no good way to use it:

import { defineComponent } from 'vue';
import InputSelect from './InputSelect.vue';

export default defineComponent({
  components: {
    InputSelect, // You cannot easily cast this
  },
});

Now you are stuck, because InputSelect is in TypeScript's value-space. Meaning you cannot really cast it because you need something for it to be cast to, consider this:

const arr: Array<unknown> = ['1', '2', '3'];

// ✅ Works
const strArr = arr as Array<string>

const InputSelect = defineComponent(...);

const StrInputSelect = InputSelect as // ???

You can probably get something working with the exported DefineComponent type from vue but it is complicated.

Named Exports

A feature that's often ignored or not used often is to use named exports with SFC modules. After all, they are perfectly valid ESM modules and you can have named exports and import them individually without importing the component itself.

Here is how it works:

const Ctor = defineComponent({
  // ...
});

export function logAnything() {
  console.log('Anything!');
}

export default Ctor;

// You can import the named exports
import { logAnything } from './SomeComponent.vue';

This is not used often because there is little use to it in production apps, at least from my experience. However, if you do have neat use-cases feel free to write about them!

Now, how can we use this to get a step closer to our generic component?

We can instead of exposing a generic component as the default, we could expose the generic wrapper function as a named export.

So we could do something like this:

import { defineComponent, PropType } from 'vue';

function defineGenericComponent<T = unknown>() {
  return defineComponent({
    name: 'InputSelect',
    props: {
      options: {
        type: Array as PropType<T[]>,
        required: true,
      },
      value: {
        type: null as unknown as PropType<T | undefined>,
        default: undefined as unknown,
      },
    },
    emits: {
      change: (payload: T) => true,
    },
  });
}

export const GenericInputSelect = <T>() => {
  return defineGenericComponent<T>();
};

export default defineGenericComponent();

Then we can try to use it like this:

import { defineComponent } from 'vue';
import { GenericInputSelect } from './InputSelect.vue';

export default defineComponent({
  components: {
    InputSelect: GenericInputSelect<string>(),
  },
});

Ha! because functions can take generic parameters we can finally tell TypeScript and volar about the component generic type!

One problem though, the component won't render anything. Actually, you will get this warning:

[Vue warn]: Component is missing template or render function.

The reason for this is the same one that prevented us from exporting the custom defineGenericComponent. To give you more insight, this is how the default export is compiled:

{
  name: "InputSelect"
  props: {options: {…}, value: {…}, ... }
  render: (_ctx, _cache, $props, $setup, $data, $options)
  __file: "src/components/InputSelect.vue"
}

Looks alright, lets see how the named export is compiled:

{ name: 'InputSelect', props: {…} }

So, where the heck is our render function?

We lost the template render information here, which is even more important than the type information we've set out to improve. We can't blame the compiler here as we are trying some really weird stuff.

The rule as I understand it is: The render function is added to the default export.

Mirroring the default export

So all we have to do to make the previous example work is to mirror the default export as the generic type we want. In other words, return it after casting it.

This could be your very first attempt:

import { defineComponent, PropType } from 'vue';

function defineGenericComponent<T = unknown>() {
  return defineComponent({
    // ...
  });
}

const main = defineGenericComponent();

export const GenericInputSelect = <T>() => {
  return main as ReturnType<typeof defineGenericComponent>;
};

export default main;

The component will render correctly again, but the type information still doesn't work because typeof doesn't allow us to pass generics.

The casting we did just gave us our component back with unknown as the generic type which means we have done zero progress.

Let's analyze this on a deeper level, so typeof accepts a value-space identifier to infer its type. The keyword here is "value-space identifier", as we cannot use generics on function identifier names. We can only use them when we call the functions.

We can try doing some voodoo magic with infer keyword, but you will need someone better than me at TypeScript to figure out a way to do that and explain it properly.

Instead, I have a little trick up my sleeve.

So the only reason typeof doesn't work, is because of its limitations on value-space identifiers. But if only we could have some construct that can wrap the function while being generic, Actually, classes does that very well!

Classes can be generic, and double as a value-space identifier and a type-space identifier:

class SomeClass<T> {}

const item = new SomeClass(); // used as a value!

// used as a type!
function doOp(param: SomeClass) {
  // ...
}

By re-writing the generic wrapper using a class instead while mirroring the default export as we've tried before, we should get what we need:

import { defineComponent, PropType } from 'vue';

class InputSelectFactory<T = unknown> {
  define() {
    return defineComponent({
      name: 'InputSelect',
      props: {
        options: {
          type: Array as PropType<T[]>,
          required: true,
        },
        value: {
          type: null as unknown as PropType<T | undefined>,
          default: undefined as unknown,
        },
      },
      emits: {
        change: (payload: T) => true,
      },
    });
  }
}

const main = new InputSelectFactory().define();

export function GenericInputSelect<T>() {
  // This now will be casted correctly!
  return main as ReturnType<InputSelectFactory<T>['define']>;
}

export default main;

And finally, you can use it like this:

<template>
  <InputSelect
    :options="options"
    :value="selectedOption"
    @change="handleSelectionChange"
  />
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';
import { GenericInputSelect } from './InputSelect.vue';

export default defineComponent({
  components: {
    InputSelect: GenericInputSelect<string>(),
  },
  setup() {
    const options = ref(['1', '2', '3']);
    const selectedOption = ref<string>('');

    function handleSelectionChange(option: string) {
      console.log(option);
    }

    return {
      options,
      selectedOption,
      handleSelectionChange,
    };
  },
});
</script>

And you can use more complex types with it:

import { defineComponent, ref } from 'vue';
import { GenericInputSelect } from './SelectInput.vue';

interface Tag {
  id: number;
  label: string;
}

export default defineComponent({
  components: {
    InputSelect: GenericInputSelect<Tag>(),
  },
});

I'm not a fan of the casting done here:

const main = new InputSelectFactory().define();

export function GenericInputSelect<T>() {
  return main as ReturnType<InputSelectFactory<T>['define']>;
}

export default main;

Casting is usually seen as an "escape hatch" and its usage should be kept to a minimum, but there are situations where it is very safe. I argue this is one of those situations as there is no way the main component isn't the component we just defined.

And that's it, we managed to finally create a truly generic component with SFC support.

Note that you cannot use this technique with <script setup> in vue >= 3.2+, because you need control over what is exported, this is a hack after all.

If you want to see this in action, download this sandbox project

Additional Reading

You can check out the original issue answered in the Vue next repo here.

There is an RFC proposal for something similar.

Conclusion

While it doesn't seem that we have an easy and official way to support generic components, it is relatively straightforward if you learn how to navigate the pitfalls we just did.

When should you use generic components? The answer is the same as when you should be using generics! But to cut the list down, I see them mostly used in form field components and UI builders.

I don't use this pattern a lot, and using unknown works fine for 90% of my cases, but for those who want the extra edge and getting fully type-safe this might be the way for you.

Thanks for reading 👋 if you liked this article you can check my other articles over at my blog.

VeeValidate 2.1: Validation Providers

Abdelrahman Awad — Sun, 28 Oct 2018 18:36:40 +0000

A retake on Vue.js form validation

This article marks the release of vee-validate 2.1.0, a template-based validation framework for Vue.js which mainly uses directives.

Directives in Vue.js offer somewhat low-level access that allows us to manipulate the element bound to the directive.

While very handy to use, directives have limits because they don’t have an instance, or rather a state. Back in Vue 1.x they had state and allowed much more to be done. This was one of the reasons that influenced vee-validate design to be template-based.

Recently I introduced the Verify API which validates values without declaring a field. You can even use the verify method on the server-side. 🤨

import express from 'express';
import bodyParser from 'body-parser';
import { Validator } from 'vee-validate';

const app = express();
app.use(bodyParser.json());
const v = new Validator();

// validate the subscribe request.
function validateReq (req) {
  return v.verify(req.body.email, 'required|email');
}

app.post('/subscribe', async (_req_, _res_) => {
  const { errors, valid } = await validateReq(req);
  if (!valid) {
    return res.status(422).json({
      errors
    });
  }

// ...
});

app.listen(3000);

This new API has sparked a new idea for me a few weeks ago:

Can I use components to validate? 🤔

Vue has a component API called scoped slots which allows a component to pass data to its slot in an isolated manner. I used that feature for various purposes in our clients’ works.

VueApollouses them as data providers, which in some cases reduces the JavaScript considerably. Scoped slots offer the ability to create behaviors encapsulated in components and a way to communicate the results.

I began experimenting with render functions, diving into the VNode API. I managed to create a reliable alternative to the directive, I would even say, a better approach.

Validation Provider

This is a component that leverages scoped slots to provide validation for your inputs like Vuetify’s VTextField component. It looks like this:

<ValidationProvider rules="required">
  <template slot-scope="{ errors }">
    <VTextField v-model="value" :error-messages="errors" />      
  </template>
</ValidationProvider>

Aside from errors, the slot-scope also contains classes, flags, and aria attributes. Opting in for any of those useful properties is better than implicitly injecting them into your components. It also does not force your template to be structured in a certain way. This API is explicit , clean and flexible.

<ValidationProvider rules="required">
  <template slot-scope="{ errors }">
    <VTextField v-model="foo" :error-messages="errors" />      
  </template>
</ValidationProvider>

<ValidationProvider rules="required">
  <template slot-scope="{ errors }">
    <VTextField v-model="bar" :error-messages="errors" />   
  </template>
</ValidationProvider>

This can grow to become quite verbose, definitely not pretty in a very large form.

A simple refactoring will make it more attractive. Creating another component wrapped by this one is trivial.

<template>
  <ValidationProvider _:rules_="rules">
  <template _slot-scope_="{ errors }">
     <VTextField _v-model_="innerValue" _:error-messages_="errors" />   
   </template>
 </ValidationProvider>
</template>

<script>
import { ValidationProvider } from 'vee-validate';

export default {
  name: 'InputWithValidation',
  props: {
    rules: [_String_],
    value: null
  },
  components: {
_ValidationProvider_
},
  data: () => ({
    innerValue: null
  }),
  watch: {
    innerValue (_val_) {
_this_.$emit('input', _val_);
    }
  }
};
</script>

Refactoring the previous example would make it look like this:

<InputWithValidation _v-model_="foo" _rules_="required" />

<InputWithValidation _v-model_="bar" _rules_="required" />

This is a self-validating component but done right. We can also refactor it in another way using higher-order components.

Higher-Order Components

A High-order function is a function that takes a function and returns a new function, an enhanced one.

Likewise, a higher-order component takes a component and returns a new enhanced component. In our case, we want to add validation to our components. This is where withValidation comes in.

import { VTextField } from 'vuetify/lib';
import { withValidation } from 'vee-validate';

const VInput = withValidation(VTextField, ({ _errors_ }) => ({
  'error-messages': errors
}));

You can use the new component in place of your input components. The withValidation function uses the ValidationProvider to “enhance” your component.

The second argument transforms the slot-scope data into props which are passed to the original component.

But, there are some cons to using HoC which I will not touch on in this article. Using either approach is fine.

Using components for validation introduces new problems. Like tracking the current validation state without injections/shared state 🤔.

Here is a concrete example:

disable a button as long as inputs are invalid.

We want to be able to observe our inputs and have something present their state to us. At this point, I thought why not double down on the scoped-slots components thing and add another one_ _🤪.

Validation Observer

This component presents the current state of child providers and their HoC variants.

It looks like this:

<ValidationObserver>
  <template _slot-scope_="{ valid }">
    <InputWithValidation _v-model_="foo" _rules_="required" />

    <InputWithValidation _v-model_="bar" _rules_="required" />

    <VBtn _:disabled_="!valid" _@click_="submit">Submit</VBtn>   
  </template>
</ValidationObserver>

You can also control them by validating them on demand or resetting them using the public methods on the observer instance.

Here is everything in action 🎉

https://medium.com/media/545facb2525dd99dcc8dd888c2121e72/href

You can find more detailed description over in the docs which cover scopes, manual validation, and form resets_._

Perf Matters

By taking advantage of Vue’s virtual DOM and render functions vee-validate is now able to work with ridiculously large forms. larger than before for sure.

A long-standing issue with 800 radio input in the same page would have poor performance, Another that was using 120+ text inputs would cause memory leaks in Edge. Using validation providers had a negligible effect on performance in both cases.

Strictly using these components would eliminate the small overhead of having the global mixin that injects state for the directive.

The Future of VeeValidate

We have experimented with those components in Baianat and so far it is easier to use than the directive, less confusing and everyone seems to love it.

For me, this API lights a bright future for vee-validate. It’s API is smaller than the directive, more reliable, SSR friendly, and efficient 💨.

Currently, I’m working on an experimental branch v3 which removes the old API which reduces the bundle size considerably.

Full-bundle went down to 34kb gzipped (32% smaller).
Minimal bundle went down to 11kb (57% smaller 😲).

More improvements can be squeezed out once vee-validate begins shifting towards a more modular approach, providing only what you need/use in your apps, not everything.

As for 2.x versions, they will have both approaches available and will continue improving upon the existing API. It will have feature parity with the 3.x versions.

I would love 😍 to get feedback from the community. What do these changes mean to you?

Authoring Validatable Vue Input Components

Abdelrahman Awad — Thu, 29 Mar 2018 18:24:15 +0000

Building Vue.js components is very fun and straightforward, you can build almost anything and it will work most of the time. But when it comes to components that serve as inputs there are few things to cover.

We will start with covering the basics using Vue.js guide then build our way up to integrate the component to work seamlessly with vee-validate.

Implement the v-model interface

As mentioned in the official Vue guide, your component should be able to work with the v-model directive, which boils down to emitting an input event whenever the value changes and it should accept a value input, which of course can be customized to cover other events and props.

As a start, our custom text component would look like this:

<template>
  <input type="text" :value="value" @input="onInput" />
</template>

<script>
export default {
  props: {
    value: String
  },
  methods: {
    onInput (e) {
      this.$emit('input', $event.target.value);
    }
  }
};
</script>

It doesn’t do much yet, it just accepts a value prop and emits an event whenever the user manipulates the input via the native input event, so in a way, it translates the interaction from native HTML input to a Vue component.

This way, using v-model is the only way this component mutates the state, which is simple and manageable. And above all else is re-usable.

Add events as needed

Native HTML inputs have a plethora of events that you can listen to, but most of the time you are only interested in a few of them, in our case we have been only interested in the input event, we should add some useful events as well, like focus, blur, and change.

<template>
  <input
    type="text"
    :value="value"
    @input="updateValue"
    @change="updateValue"
    @blur="$emit('blur')"
    @focus="$emit('focus')"/>
</template>

<script>
export default {
  props: {
    value: String
  },
  methods: {
    updateValue (e) {
      this.$emit('input', $event.target.value);
    }
  }
};
</script>

This might not be necessary when working with your own components in your own projects but if you are planning to publish your components to the masses then you might need to cover a few events that the users might be interested in listing to, for example, blur could be used to trigger UI change or trigger validation on that input.

Add props

Like events, some users may be interested in setting some props on your component like they would on a native HTML input, for example, the disabled attribute is extremely valuable, maybe a label and name props as well.

Also having the input type always set to text isn’t very accessible on mobile devices since the keyboards can be context-aware to display relevant characters to the input type, like @ for emails and .com for URLs.

Let us add our props and bind it to the inner input attributes:

<template>
  <div class="form__input">
    <label v-if="label" class="form__label">{{ label }}</label>
    <input
      class="input"
      :type="type" 
      :value="value" 
      :disabled="disabled" 
      @input="updateValue" 
      @change="updateValue" 
      @blur="$emit('blur')" 
      @focus="$emit('focus')"
    />
  </div>
</template>

<script>
export default {
  props: {
    name: {
      type: String
    },
    label: {
      type: String
    },
    disabled: {
      type: Boolean,
      default: false
    },
    value: String,
    type: {
      type: String,
      default: 'text',
      validate: (val) => {
        // we only cover these types in our input components.
        return ['text', 'url', 'email', 'password', 'search'].indexOf(val) !== -1;
      }
    }
  },
  methods: {
    updateValue (e) {
      this.$emit('input', $event.target.value);
    }
  }
};
</script>

We can go a long way with this, for example: autocomplete , placeholder and plenty more .

Enable Validation

Most likely you want to validate this little component of ours, we have two approaches:

Validate it from the parent as a response to the input event (reactive).
Have it validate itself whenever the value changes (passive).

Now while the second option makes it sound more contained and useful, you should realize that it forces validation on the component, It is opt-out instead of opt-in.

Furthermore in the lines of the single responsibility pattern: Should the component be concerned if its value is valid? or is it the concern of the consumer of said value, the consumer being the parent component or the form component.

The first approach simplifies our component implementation and makes it lighter, the component should only report its value, not its validness.

Vee-validate supports both approaches, but depending on your implementation, the second approach could be more difficult to maintain since it requires communicating the errors to the parent component to prevent form submission for example until everything is valid.

For now, let us go with the first approach, we don’t have to add anything to our component, it will just work:


<template>
  <div>
    <text-input 
      name="email" 
      label="Email Address" 
      v-validate="'required|email'"
      v-model="email"
      type="email"
    ></text-input>
  </div>
</template>

<script>
import TextInput from '@components/inputs/Text';
export default {
  components: {
    TextInput
  },
  data: () => ({
    email: null
  })
};
</script>

Here comes the issue, our parent component can tell if the component is valid or not using the validator API, but not our user. Going back to our question if the component should be concerned if its value is valid or not, maybe it should since we need to display some red flags to the user as well.

But instead of it saying “my value is valid” maybe it should instead ask: “is my value valid?” which can be done using props easily.

Let us add error prop to our component and bind it to its view:

<template>
  <div class="form__input">
    <label v-if="label" class="form__label">{{ label }}</label>
    <input
      class="input"
      :type="type" 
      :value="value" 
      :disabled="disabled" 
      @input="updateValue" 
      @change="updateValue" 
      @blur="$emit('blur')" 
      @focus="$emit('focus')"
    />
    <p v-if="error" class="form__error">{{ error }}</p>
  </div>
</template>

<script>
export default {
  props: {
    error: {
      type: String
    },
    // ...
  },
  methods: {
    // ...
  }
};
</script>

<template>
  <div>
    <text-input 
      name="email" 
      label="Email Address" 
      v-validate="'required|email'"
      v-model="email"
      type="email"
      :error="errors.first('email')"
    ></text-input>
  </div>
</template>

<script>
import TextInput from '@components/inputs/Text';
export default {
  // ...
};
</script>

Well, now we got a clean component that can be validated with a few nice features. The only thing remaining is to fix some issue with vee-validate.

Vee-validate validates components the same way it validates HTML inputs, mainly using events but what happens when you call validateAll to validate manually before form submission. vee-validate doesn’t know the current value of the input since it doesn’t track them, also what if you want to validate on blur instead? Our component does not emit the value with the blur event, so the validator wouldn’t know what to do.

VeeValidate Component Options

There is a newly added feature called component options, which is a contract between the component and VeeValidate. It allows your component to tell vee-validate some stuff, like how to fetch the current value, the component name and which events should be used to validate the component.

<script>
export default {
  $_veeValidate: {
    // must not be arrow functions.
    // the name getter
    name () {
      return this.label;
    },
    // the value getter
    value () {
      return this.value; // `this` is the component instance, `value` is the prop we added.
    }
  },
  props: {
    // ...
  },
  methods: {
    // ...
  }
};
</script>

And that is it, we got ourselves a nice custom input component that plays well with vee-validate. Of course, there is room for improvements and there are already plenty of Vue.js component frameworks that do this very well like Vuetify.

What about other input types?

Text inputs while versatile, are lacking in many ways for some input value types. Like dates, choices, files and whatever you can think of.

I have included in this sandbox other types of inputs that you might find useful for your next component implementation. They share the same principle of what we did here: Passing values to the model and telling the validator how to fetch it.

We covered a lot here! Now go on and give your input components a nice touch. thanks for reading!