DEV Community: Pablo Berganza

Shadow DOM, Firefox and contenteditable

Pablo Berganza — Wed, 16 Mar 2022 15:56:29 +0000

This is more of a short note about some experiments when working with web components that I’m publishing as a reference for future me (or other people that experience the same issue).

I’ve been experimenting with web components in order to build a wrapper for Felte that can easily be used with vanilla JS. One of Felte’s features is the ability to use custom field components that are not based on the browser’s native inputs (input, textarea, select). The example I show is a div with an attribute [contenteditable=“true”]. While testing this experiment I found some weird behaviour coming from Firefox: while I could perfectly click each field and type of it, if I tried to use the form only using the keyboard (tabbing to each field) the focus moved but trying to type would always result in the text being added to the first field I focused.

Another confusing behaviour is that, even if you can type on the element when clicking on the element itself, the care is not displayed at all. So there’s no visual cue indicating the user that the element itself is editable. Currently, there’s an open issue on bugzilla that seems to be exactly this.

This behaviour is, of course, unacceptable. Specially since forms (and web applications in general) should be accessible to keyboard users. In order for the demo I was working on to function correctly I went to look for an immediate solution. After some research I found that the solution that works more consistently for me is to not add [contenteditable] to the fields on render and, instead, add event listeners that dynamically add the attribute on focus and remove it on blur:

function handleFocus(e) {
  e.target.setAttribute('contenteditable', '');
}

function handleBlur(e) {
  e.target.removeAttribute('contenteditable');
}

// We query the shadowRoot of the element that contains
// our `contenteditable` fields
element.shadowRoot
  .querySelectorAll('div[role="textbox"]')
  .forEach((el) => {
    el.addEventListener('focusin', handleFocus);
    el.addEventListener('focusout', handleBlur);
  });

Or better yet, in order to make it more easy to reuse, make a custom element that behaves like this:

function handleFocus(e) {
  e.target.setAttribute('contenteditable', '');
}

function handleBlur(e) {
  e.target.removeAttribute('contenteditable');
}

export class MyField extends HTMLElement {
  constructor() {
    super();
    // Make the element focusable
    this.setAttribute('tabindex', '0');
    // Assign a role for assistive technologies
    this.setAttribute('role', 'textbox');
    // Some default styles
    this.style.display = 'block';
    this.style.cursor = 'text';
  }

  connectedCallback() {
    this.addEventListener('focusin', handleFocus);
    this.addEventListener('focusout', handleBlur);
  }

  disconnectedCallback() {
    this.removeEventListener('focusin', handleFocus);
    this.removeEventListener('focusout', handleBlur);
  }
}

customElements.define('my-field', MyField);

This way you can use <my-field></my-field> as a [contenteditable] “div”!

Keep in mind that this article only worries about making focus work correctly on a [contenteditable] element. There's more things that you should consider when doing something like this which would depend on your use-case.

Creating a Chai like assertion library using proxies

Pablo Berganza — Sat, 19 Feb 2022 22:34:34 +0000

For the past few weeks I’ve taken the (arguably pointless) work of migrating Felte from using Jest to uvu. This is a really tedious work by itself, but one of details that would have made this work even more tedious is that Jest prefers assertions to the style of expect(…).toBe* while uvu gives you freedom to choose any assertion library, although there’s an official uvu/assert module that comes with assertions to the style of assert.is(value, expected).

While this is fine and I could have perfectly moved all my tests to use said assertion style, I like the descriptive way Jest tests look like. As a quick way to maintain certain similarity I reached for ChaiJS, an assertion library that is mainly used with mocha. Chai offers expect like assertions that can arguably be more descriptive than Jest’s. Instead of writing expect(…).toBe(true), you’d write expect(…).to.be.true. For the most part I managed to do a search and replace for this.

This setup works really good! But there’s some minor details: The assertion errors thrown by Chai are slightly different than those expected by uvu., so sometimes I’d get messages or extra details that are not so relevant to the test itself. Another issue is that I’d receive diffs comparing undefined to undefined when an assertion failed. As a proper developer with too much free time, I went ahead and decided to experiment with writing my own assertion library built on top of uvu’s assertions that I called uvu-expect. Here’s more or less how I did it.

The “expect” function

The main thing our assertion library needs is an expect function that should receive the value you’re planning to validate.

export function expect(value) {
  // run your validations here
}

If we wanted to keep a similar API to Jest, this could return an object with functions.

export function expect(value) {
  return {
    toBe(expected) {
      if (expected !== value) {
        throw new Error('Expected values to be strictly equal');
      }
    },
  };
}

But I actually really enjoyed Chai’s syntax. So I decided to use proxies to achieve something similar. We could start by allowing to chain arbitrary words after our expect call. I decided not to restrict the possible “chain” words to simplify development.

Proxy is a JavaScript feature that allows you to "wrap" an object in order to intercept and modify its functionality. In our case we will use it to modify the behaviour when accessing our object's properties.

export function expect(value) {
  const proxy = new Proxy(
    // The target we are adding the proxy on. For now it's empty.
    {},
    {
      get() {
        // Any property access returns the proxy once again.
        return proxy;
      },
    }
  );
  return proxy;
}

expect().this.does.nothing.but.also.does.not.crash;

Next we will allow for any of these chain words to be functions.

export function expect(value) {
  const proxy = new Proxy(
    {},
    {
      get(_, outerProp) {
        // Instead of returning the initial proxy, we return
        // a new proxy that wraps a function.
        return new Proxy(() => proxy, {
          get(_, innerProp) {
            // If the function does not get called, and a property gets
            // accessed directly, we access the same property
            // from our original proxy.
            return proxy[innerProp];
          },
        });
      },
    }
  );
  return proxy;
}

expect().this.does.nothing().but.also.does.not.crash();

With this we already got the base for our syntax. We now need to be able to add some meaning to certain properties. For example, we might want to make expect(…).to.be.null to check whether a value is null or not.

Adding meaning to our properties

We could perfectly check the name of the property being accessed and use that to run validations. For example, if we wanted to add a validation for checking if a value is null:

// For brevity, we're not going to use the code that handles functions.
// Only property access
export function expect(value) {
  const proxy = new Proxy(
    {},
    {
      get(_, prop) {
        // `prop` is the name of the propery being
        // accessed.
        switch (prop) {
          case 'null':
            if (value !== null) {
              throw new Error('Expected value to be null');
            }
            break;
        }
        return proxy;
      },
    }
  );
  return proxy;
}

expect(null).to.be.null;
try {
  expect('not null').to.be.null;
} catch (err) {
  console.log(err.message); // => "Expected value to be null"
}

This can make our expect function hard to maintain, and adding more properties would not be so trivial. In order to make this more maintainable (and extensible) we’re going to handle this a bit differently.

Defining properties

Instead of proxying an empty object, we will proxy an object that contains the properties we want to have meaning.

const properties = {
  // ...
};

export function expect(value) {
  const proxy = new Proxy(properties, {
    get(target, outerProp) {
      // `target` is our `properties` object
      console.log(target);
      return new Proxy(() => proxy, {
        get(_, innerProp) {
          return proxy[innerProp];
        },
      });
    },
  });
  return proxy;
}

I decided to define each property as an object that contains two functions: onAccess to be executed on property access, and onCall to be executed when calling the property as a function. For example, our property for null could look like:

const isNull = {
  onAccess(actual) {
    if (actual !== null) {
      throw new Error('Expected value to be null');
    }
  },
};

We can also define a property to check if two values are strictly equal:

const isEqual = {
  onCall(actual, expected) {
    if (actual !== expected) {
      throw new Error('Expected values to be strictly equal');
    }
  },
};

Then we can modify our expect function to call them when they’re accessed:

// We add the previously defined properties to
// our `properties` object
const properties = {
  null: isNull,
  equal: isEqual,
};

export function expect(value) {
  const proxy = new Proxy(properties, {
    get(target, outerProp) {
      const property = target[outerProp];
        // We execute the `onAccess` handler when one is found
      property?.onAccess?.(value);
      return new Proxy(
        (...args) => {
            // We execute the `onCall` handler when one is found
          property?.onCall?.(value, ...args);
          return proxy;
        },
        {
          get(_, innerProp) {
            return proxy[innerProp];
          },
        }
      );
    },
  });
  return proxy;
}

expect(null).to.be.null;
expect('a').to.equal('a');

We suddenly have a really basic assertion library! And it can be easily extended by adding properties to our properties object!

There’s one thing we’re still not able to do with our current implementation: negate assertions. We need a way to modify the behaviour of future assertions.

Negating assertions

In order to be able to achieve this, we need a way to communicate to our properties that the current assertions is being negated. For this we’re going to change a bit how we define our properties. Instead of expecting the actual value being validated as first argument, we’re going to receive a context object that will contain our actual value and a new negated property that will be a boolean indicating if the assertion is being negated. Our new properties for equal and null will then look like this:

const isNull = {
  onAccess(context) {
    if (!context.negated && context.actual !== null) {
      throw new Error('Expected value to be null');
    }
    if (context.negated && context.actual === null) {
      throw new Error('Expected value not to be null');
    }
  },
};

const isEqual = {
  onCall(context, expected) {
    if (!context.negated && context.actual !== expected) {
      throw new Error('Expected values to be strictly equal');
    }
    if (context.negated && context.actual === expected) {
      throw new Error('Expected values not to be strictly equal');
    }
  },
};

And we can add a new property to negate our assertions:

const isNot = {
  onAccess(context) {
    // We set `negated` to true so future assertions
    // will have knowledge of it.
    context.negated = true;
  },
};

Then our expect function will call each handler with a context object instead of the actual value:

const properties = {
  null: isNull,
  equal: isEqual,
  not: isNot,
};

export function expect(value) {
  // Our context object
  const context = {
    actual: value,
    negated: false,
  };
  const proxy = new Proxy(properties, {
    get(target, outerProp) {
      const property = target[outerProp];
      property?.onAccess?.(context);
      return new Proxy(
        (...args) => {
          property?.onCall?.(context, ...args);
          return proxy;
        },
        {
          get(_, innerProp) {
            return proxy[innerProp];
          },
        }
      );
    },
  });
  return proxy;
}

expect('a').to.not.equal('b');

This technique can be used to communicate more details about our assertions to future assertions.

Do not throw normal Errors

To make examples simpler, we throw normal errors (throw new Error(…)). Since this is to be used with a test runner, it’d be better to throw something like Node’s built-in AssertionError or, in the case of uvu, its own Assertion error. These would give way more information when assertions fail. And it can be picked by Node or test runners to show prettier messages and diffs!

Conclusion

This is a simplified explanation of how I made uvu-expect. uvu-expect has way more features and validations such as:

.resolves and .rejects to assert on promises
Possibility to create plugins for it using an extend function. This is how I also created a plugin for it called uvu-expect-dom which offers similar validations to @testing-library/jest-dom.
Assertions on mock functions (compatible with sinonjs and tinyspy).

I aimed for it to have at least the features I used of Jest’s expect. You can read more about its features on its README! I documented everything about it there. Even how to create your own plugins for it.

It was a really fun side-project to build and explain. And it’s been working really well with our tests on Felte.

Announcing Felte 1.0: A form library for Svelte, Solid and React

Pablo Berganza — Mon, 14 Feb 2022 14:25:23 +0000

After more than a year of work, I am proud to announce the release of version 1.0.0 of Felte!

Felte is an extensible form management library for Svelte, Solid and (as of today) React. The main characteristic of it is that it does not require any sort of Field or Form components to work. In its most basic form it only requires you to provide it your HTML form element so it can subscribe to your user’s interaction with your form.

I originally started working on Felte wanting a form library for Svelte that would not make it complex to style my input components. As I worked more on it, it began growing into a much more flexible package that allowed you to validate your form using your preferred validation library and display your validation messages as you preferred. After the release of version 1.0.0 of SolidJS, I released a version for it as well that shares most of its internals with the original Felte package. And now, more than a year after the first commit, version 1.0.0 has been released alongside a new version for React! This includes many improvements in the core API, new features and a more consistent API between all three versions.

Usage

All three versions of Felte have a very similar API, and a similar concept: you call a function to set up your form. Then you give Felte a reference to your HTML form element. The variations in its API come mostly from how each framework handles reactivity. For example, with Svelte, Felte returns stores that contain your data which you can access by prefixing the stores with $. With Solid and React it returns functions that will let you subscribe to all of your form’s data or specific values of it.

On its most basic form, you only need to use form, a property returned from Felte that will let it subscribe to all interactions that happen in your form.

Here’s a basic example of how each version looks like:

Svelte

The package for Svelte is available on npm as felte.

<script>
  import { createForm } from 'felte'

  const { form } = createForm({
    onSubmit: async (values) => {
      /* call to an api */
    },
  })
</script>

<!-- `form` is an action -->
<form use:form>
  <input type=text name=email>
  <input type=password name=password>
  <button type=submit>Sign In</button>
</form>

Solid

The package for Solid is available on npm as @felte/solid.

import { createForm } from '@felte/solid';

function Form() {
  const { form } = createForm({
    onSubmit: async (values) => {
      /* call to an api */
    },
  })

    // `form` is an action
  return (
    <form use:form>
      <input type="text" name="email" />
      <input type="password" name="password" />
      <button type="submit">Sign In</button>
    </form>
  );
}

React

The package for React is available on npm as @felte/react.

import { useForm } from '@felte/react';

function Form() {
  const { form } = useForm({
    onSubmit: async (values) => {
      /* call to an api */
    },
  })

    // `form` is a ref
  return (
    <form ref={form}>
      <input type="text" name="email" />
      <input type="password" name="password" />
      <button type="submit">Sign In</button>
    </form>
  );
}

New features

Version 1 comes with a lot of improvements and features:

Debounced validation is now supported. Previously we only supported asynchronous validation, but offered no way to debounce them. This meant using Felte’s validation for calls to an API would not be recommended unless you debounced it yourself, or did them only on submission.
Asynchronous and debounced validations might apply to only a few fields. Showing loaders for the field’s that are validating is a nice feature to have for your users. This is why Felte now offer’s a way to check if validations are currently running via the new isValidating store. And a way to check which is the last field your users interact with using the new interacted store.
Using custom form controls was not so straightforward. Requiring to use helper functions to update your stores. Felte now exports a new function: createField (useField for React) to be used with custom fields where you can’t directly provide a name, or with fields that don’t use native HTML controls at all (such as a contenteditable elements). It helps you make your custom fields “discoverable” to Felte.
Better support for field arrays with new helper functions to handle them: addField, unsetField, moveField and swapFields.
You no longer always need to have an onSubmit handler. If no onSubmit is declared, Felte will submit your values as either application/x-www-form-urlencoded or multipart/form-data using the action, method and enctype attributes of your <form> element.

Breaking changes

This being a major version release, there are some breaking changes. If you were previously using Felte v0.x, you can check the migration guide for Svelte, or the migration guide for Solid.

I’ve gone back to update my original introductory posts about Felte, as well as added a new one about React to the series. You can check them out here:

Final words

I’ve put a lot of work on this project, and I’m really grateful to the contributors that helped Felte grow as much as it did! I hope that this release can be useful to all of you!

Felte: An extensible form library for React

Pablo Berganza — Mon, 14 Feb 2022 14:10:28 +0000

NOTE: The previous articles in the series have been updated for v1!

Arguably one of the most common problems front-end developers need to solve is form handling. Specially in modern web applications that require instant validation and other real-time interactions with the user. To provide the best user experience as possible, you’ll probably grab a third party form management library to help you.

In this post I am going to write about Felte, a form management library for React I have been working on for the past year that aims to make the basics of form handling on the front-end as simple as possible, while still allowing for it to grow more complex as your requirements grow.

This is one of three blog posts related to Felte. This one is oriented towards Felte’s integration with React. The other two are oriented towards Felte’s integration with Svelte and Solid.

Features

As mentioned above, Felte aims to make the basics of form reactivity as easy to handle as possible, while still allowing for more complex behaviours via configuration and extensibility. Its main features are:

Single action to make your form reactive.
Use HTML5 native elements to create your form. (Only the name attribute is necessary).
Minimal re-renders. None if you don't need your form's data in your component.
Provides stores and helper functions to handle more complex use cases.
No assumptions on your validation strategy. Use any validation library you want or write your own strategy.
Handles addition and removal of form controls during runtime.
Official solutions for error reporting using reporter packages.
Supports validation with yup, zod, superstruct and vest.
Easily extend its functionality.

How does it look like?

In its most basic form, Felte only requires a single function to be imported:

import { useForm } from '@felte/react';

export function Form() {
  const { form } = useForm({
    onSubmit: (values) => {
      // ...
    },
  });

  return (
    <form ref={form}>
      <input type="text" name="email" />
      <input type="password" name="password" />
      <input type="submit" value="Sign in" />
    </form>
  );
}

We set up the form by calling useForm with our submit handler. This function returns, among other utilities, an action that can be used on your form element. Now Felte will track all inputs with a name attribute. When submitting your form, the latest values in your inputs will be passed to your onSubmit function as an object. For our previous example, the shape of values will be:

{
  email: '',
  password: '',
}

Where can I see my data?

As you type, Felte will keep track of your user’s input in an observable that contains your form data in the same shape as the values you'd receive on your onSubmit. This observable is handled by Felte and its value can be obtained by calling the function data returned from useForm; no need to handle observables by yourself! We'll refer to these functions as accessors from now on. When this accessor is called without any arguments (data()), it returns all of the form's data as an object. This also "subscribes" your component to every change on your form, triggering a re-render everytime a value changes. An argument can be passed as first argument to select a specific field, either a selector function or a string path. By using an argument, your component will only "subscribe" to changes made to the specific value you've selected.

For example, this would log your user’s email to the console as they type it:

// Within a component
const { form, data } = useForm({ /* ... */ });

// Passing a function as first argument
console.log(data(($data) => $data.email));

// Passing a string as first argument
console.log(data('email'));

Accessors are NOT hooks, this means they can be called from wherever you need them in your code.

I might need some validation here

Of course, another common requirement of forms is validation. If we want our app to feel snappy to the user, we will want some client side validation. useForm’s configuration object accepts a validate function (which can be asynchronous). It will receive the current value of your data as it changes, and it expects you to return an object with the same shape, containing your validation messages if the form is not valid, or nothing if your form is valid. Felte will keep track of these validation messages on an accessor that is returned from useForm as errors:

const { form, errors } = useForm({
  validate(values) {
    const currentErrors = {};
    if (!values.email) currentErrors.email = 'Must not be empty';
    if (!values.password) currentErrors.password = 'Must not be empty';
    return currentErrors;
  },
});

console.log(errors(($errors) => $errors.email));

More complex validation requirements might require third party validation libraries. Felte offers first party integrations with some popular validation libraries through its extensibility features. These integrations are offered as separate packages. I will write write more about this in the next section regarding extensibility, but you can read more about these packages in our official documentation.

Handling complex scenarios via extensibility

Felte does not attempt to have the perfect solution on how to handle all scenarios regarding form management. This is why Felte offers an API to extend its functionality as your requirements grow more complex. You may have a preferred library you like to use, such as the really popular yup, or Vest (which was recently talked about during Svelte Summit). Modifying Felte’s behaviour to handle these scenarios can be done via the extend option on useForm’s configuration object. More about this can be read in the official documentation. To keep things simple for the purposes of this blog post, I am only going to write about some of the existing packages we maintain to handle some common use cases:

Validators: Integrations with popular validation libraries

We are currently maintaining four packages to integrate Felte with some popular validation libraries: yup, zod, superstruct and most recently vest. Here we will use yup as an example, but you can read more about the rest here.

The package to use yup is on npm under the name @felte/validator-yup. You will need to install it alongside yup:

npm install --save @felte/validator-yup yup

# Or, if you use yarn

yarn add @felte/validator-yup yup

This validator package exports a function called validator which you can call with your validation schema and pass its result to the extend option of useForm:

import { validator } from '@felte/validator-yup';
import * as yup from 'yup';

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().required(),
});

const { form } = useForm({
  // ...
  extend: validator({ schema }), // OR `extend: [validator({ schema })],`
  // ...
});

Reporters: Displaying validation messages

Displaying your validation messages can be done by directly using the errors accessor returned by useForm. Messages won’t be available on this accessor until the related field is interacted with.

import { useForm } from '@felte/react';

function Form() {
  const { form, errors } = useForm({ /* ... */ });

  return (
    <form ref={form}>
      <label htmlFor="email">Email:</label>
      <input name="email" type="email" id="email" />
      {!!errors('email') && (
        <span>{errors('email')}</span>
      )}
      <button>Submit</button>
    </form>
  );
}

If a specific field has an error, Felte assigns an aria-invalid=true attribute to the appropriate input.

But you might not like that specific syntax to handle your validation messages. Felte currently also has four accompanying packages that offer different alternatives on how to display your validation messages:

Using a React component, which gives the most flexibility and would allow you to have access to your validation messages deep within the component tree without needing to pass the errors accessor around.
Modifying the DOM directly by adding and removing DOM elements.
Using Tippy.js to display your messages in a tooltip.
Using the browser’s built-in constraint validation API, which can be less friendly to mobile users.

For brevity, I am only going to cover the first package. But you can read more about the rest in the documentation.

Using a React component to get your validation messages can be done with the package @felte/reporter-react. You’ll need to add it to your project using your favourite package manager:

# npm
npm i -S @felte/reporter-react

# yarn
yarn add @felte/reporter-react

Then you’ll need to import both the reporter function to add to the extend property, and the ValidationMessage component which you will use to receive your validation messages:

import { reporter, ValidationMessage } from '@felte/reporter-react';
import { useForm } from '@felte/react';

function Form() {
  const { form } = useForm({
      // ...
      extend: reporter, // or [reporter]
      // ...
    },
  })

 // We assume a single string will be passed as a validation message
 // This can be an array of strings depending on your validation strategy
  return (
    <form ref={form}>
      <input id="email" type="text" name="email" />
      <ValidationMessage for="email">
        {(message) => <span>{message}</span>}
      </ValidationMessage>
      <input type="password" name="password" />
      <ValidationMessage for="password">
        {(message) => <span>{message}</span>}
      </ValidationMessage>
      <input type="submit" value="Sign in" />
    </form>
  );
}

Next steps

You can check more about Felte in its official website with some functional examples. There’s also a more complex example showcasing its usage with Tippy.js and Yup available on CodeSandbox.

Finishing thoughts

I hope this served as a good introduction to Felte, and that it is interesting enough for you to give it a try. Felte is already on a stable state and used by some people. I am also open to help and suggestions so feel free to open an issue or make a pull request on GitHub.

Felte: An extensible form library for Solid

Pablo Berganza — Wed, 08 Dec 2021 19:51:11 +0000

This article has been updated to showcase Felte 1.0

In this post I am going to write about Felte, a form management library for Solid I have been working on for the past year that aims to make the basics of form handling on the front-end as simple as possible, while still allowing for it to grow more complex as your requirements grow.

This is one of three blog posts related to Felte. This one is oriented towards Felte’s integration with Solid. The other two are oriented towards Felte’s integration with Svelte and React.

Features

Single action to make your form reactive.
Use HTML5 native elements to create your form. (Only the name attribute is necessary).
Provides stores and helper functions to handle more complex use cases.
No assumptions on your validation strategy. Use any validation library you want or write your own strategy.
Handles addition and removal of form controls during runtime.
Official solutions for error reporting using reporter packages.
Supports validation with yup, zod, superstruct and vest.
Easily extend its functionality.

How does it look like?

In its most basic form, Felte only requires a single function to be imported:

import { createForm } from '@felte/solid';

export function Form() {
  const { form } = createForm({
    onSubmit: (values) => {
      // ...
    },
  });

  return (
    <form use:form>
      <input type="text" name="email" />
      <input type="password" name="password" />
      <input type="submit" value="Sign in" />
    </form>
  );
}

We set up the form by calling createForm with our submit handler. This function returns, among other utilities, an action that can be used on your form element. Now Felte will track all inputs with a name attribute. When submitting your form, the latest values in your inputs will be passed to your onSubmit function as an object. For our previous example, the shape of values will be:

{
  email: '',
  password: '',
}

Where can I see my data?

As you type, Felte will keep track of your user’s input in a signal that contains your form data in the same shape as the values you'd receive on your onSubmit. This signal is wrapped, allowing some extra functionality, and is returned by createForm as function called data. We'll refer to these functions as accessors from now on. When this accessor is called without any arguments (data()), it behaves like a regular signal that returns all of the form's data as an object. An argument can be passed as first argument to select a specific field, either a selector function or a string path.

For example, this would log your user’s email to the console as they type it:

// Within a component
const { form, data } = createForm({ /* ... */ });

createEffect(() => {
  // Passing a function as first argument
  console.log(data(($data) => $data.email));

  // Passing a string as first argument
  console.log(data('email'));
});

I might need some validation here

Of course, another common requirement of forms is validation. If we want our app to feel snappy to the user, we will want some client side validation. createForm’s configuration object accepts a validate function (which can be asynchronous). It will receive the current value of your data as it changes, and it expects you to return an object with the same shape, containing your validation messages if the form is not valid, or nothing if your form is valid. Felte will keep track of these validation messages on an accessor that is returned from createForm as errors:

const { form, errors } = createForm({
  validate(values) {
    const currentErrors = {};
    if (!values.email) currentErrors.email = 'Must not be empty';
    if (!values.password) currentErrors.password = 'Must not be empty';
    return currentErrors;
  },
});

createEffect(() => {
  console.log(errors(($errors) => $errors.email));
});

Handling complex scenarios via extensibility

Felte does not attempt to have the perfect solution on how to handle all scenarios regarding form management. This is why Felte offers an API to extend its functionality as your requirements grow more complex. You may have a preferred library you like to use, such as the really popular yup, or Vest (which was recently talked about during Svelte Summit). Modifying Felte’s behaviour to handle these scenarios can be done via the extend option on createForm’s configuration object. More about this can be read in the official documentation. To keep things simple for the purposes of this blog post, I am only going to write about some of the existing packages we maintain to handle some common use cases:

Validators: Integrations with popular validation libraries

The package to use yup is on npm under the name @felte/validator-yup. You will need to install it alongside yup:

npm install --save @felte/validator-yup yup

# Or, if you use yarn

yarn add @felte/validator-yup yup

This validator package exports a function called validator which you can call with your validation schema and pass its result to the extend option of createForm:

import { validator } from '@felte/validator-yup';
import * as yup from 'yup';

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().required(),
});

const { form } = createForm({
  // ...
  extend: validator({ schema }), // OR `extend: [validator({ schema })],`
  // ...
});

Reporters: Displaying validation messages

Displaying your validation messages can be done by directly using the errors accessor returned by createForm. Messages won’t be available on this accessor until the related field is interacted with.

import { Show } from 'solid-js';
import { createForm } from '@felte/solid';

function Form() {
  const { form, errors } = createForm({ /* ... */ });

  return (
    <form use:form>
      <label for="email">Email:</label>
      <input name="email" type="email" id="email" />
      <Show when={errors('email')}>
        <span>{errors('email')}</span>
      </Show>
      <button>Submit</button>
    </form>
  );
}

If a specific field has an error, Felte assigns an aria-invalid=true attribute to the appropriate input.

Using a Solid component, which gives the most flexibility and would allow you to have access to your validation messages deep within the component tree without needing to pass the errors accessor around.
Modifying the DOM directly by adding and removing DOM elements.
Using Tippy.js to display your messages in a tooltip.
Using the browser’s built-in constraint validation API, which can be less friendly to mobile users.

For brevity, I am only going to cover the first package. But you can read more about the rest in the documentation.

Using a Solid component to get your validation messages can be done with the package @felte/reporter-solid. You’ll need to add it to your project using your favourite package manager:

# npm
npm i -S @felte/reporter-solid

# yarn
yarn add @felte/reporter-solid

Then you’ll need to import both the reporter function to add to the extend property, and the ValidationMessage component which you will use to receive your validation messages:

import { reporter, ValidationMessage } from '@felte/reporter-solid';
import { createForm } from '@felte/solid';

function Form() {
  const { form } = createForm({
      // ...
      extend: reporter, // or [reporter]
      // ...
    },
  })

 // We assume a single string will be passed as a validation message
 // This can be an array of strings depending on your validation strategy
  return (
    <form use:form>
      <input id="email" type="text" name="email" />
      <ValidationMessage for="email">
        {(message) => <span>{message}</span>}
      </ValidationMessage>
      <input type="password" name="password" />
      <ValidationMessage for="password">
        {(message) => <span>{message}</span>}
      </ValidationMessage>
      <input type="submit" value="Sign in" />
    </form>
  );
}

Next steps

You can check more about Felte in its official website with some functional examples. There’s also a more complex example showcasing its usage with Tippy.js and Yup available on CodeSandbox.

Finishing thoughts

Felte: An extensible form library for Svelte

Pablo Berganza — Wed, 08 Dec 2021 19:51:05 +0000

This article has been updated to showcase Felte 1.0

In this post I am going to write about Felte, a form management library for Svelte I have been working on for the past year that aims to make the basics of form handling on the front-end as simple as possible, while still allowing for it to grow more complex as your requirements grow.

This is one of three blog posts related to Felte. This one is oriented towards Felte’s integration with Svelte. The other two are oriented towards Felte’s integration with Solid and React.

Features

Single action to make your form reactive.
Use HTML5 native elements to create your form. (Only the name attribute is necessary).
Provides stores and helper functions to handle more complex use cases.
No assumptions on your validation strategy. Use any validation library you want or write your own strategy.
Handles addition and removal of form controls during runtime.
Official solutions for error reporting using reporter packages.
Supports validation with yup, zod, superstruct and vest.
Easily extend its functionality.

How does it look like?

In its most basic form, Felte only requires a single function to be imported:

<script>
  import { createForm } from 'felte'

  const { form } = createForm({
    onSubmit: async (values) => {
      /* call to an api */
    },
  })
</script>

<form use:form>
  <input type=text name=email>
  <input type=password name=password>
  <input type=submit value="Sign in">
</form>

{
  email: '',
  password: '',
}

Where can I see my data?

As you type, Felte will keep track of your user’s input in a regular writable Svelte store. This store is returned by createForm as data, following the same shape as the values you’d receive on your onSubmit function.

For example, this would log your user’s email to the console as they type it:

const { form, data } = createForm({ /* ... */ });

// We use a reactive statement to log everytime our data store changes.
// We access the value of our store by prefixing it with `$`.
$: console.log($data.email);

I might need some validation here

Of course, another common requirement of forms is validation. If we want our app to feel snappy to the user, we will want some client side validation. createForm’s configuration object accepts a validate function (which can be asynchronous). It will receive the current value of your data store as it changes, and it expects you to return an object with the same shape as your data store containing your validation messages if the form is not valid, or nothing if your form is valid. Felte will keep track of these validation messages on a writable store that is returned from createForm as errors:

const { form, errors } = createForm({
  validate(values) {
    const currentErrors = {};
    if (!values.email) currentErrors.email = 'Must not be empty';
    if (!values.password) currentErrors.password = 'Must not be empty';
    return currentErrors;
  },
});

$: console.log($errors);

Handling complex scenarios via extensibility

Felte does not attempt to have the perfect solution on how to handle all scenarios regarding form management. This is why Felte offers an API to extend its functionality as your requirements grow more complex. You may have a preferred library you like to use, such as the really popular yup, or Vest (which was recently talked about during Svelte Summit). Or you might find it tedious to display your validation messages using if statements. Modifying Felte’s behaviour to handle these scenarios can be done via the extend option on createForm’s configuration object. More about this can be read in the official documentation. To keep things simple for the purposes of this blog post, I am only going to write about the existing packages we maintain to handle some common use cases:

Validators: Integrations with popular validation libraries

We are currently maintaining four packages to integrate Felte with some popular validation libraries: yup, zod, superstruct and most recently vest. Here I will use yup as an example, but you can read more about the rest here.

The package to use yup is on npm under the name @felte/validator-yup. You will need to install it alongside yup:

npm install --save @felte/validator-yup yup

# Or, if you use yarn

yarn add @felte/validator-yup yup

This validator package exports a function called validator which you can call with your validation schema and pass its result to the extend option of createForm:

import { validator } from '@felte/validator-yup';
import * as yup from 'yup';

const schema = yup.object({
  email: yup.string().email().required(),
  password: yup.string().required(),
});

const { form } = createForm({
  // ...
  extend: validator({ schema }), // OR `extend: [validator({ schema })],`
  // ...
});

Reporters: Displaying validation messages

Displaying your validation messages can be done by directly accessing the errors store returned by createForm. Messages won’t be available on this store until the related field is interacted with.

<script>
  const { form, errors } = createForm({ /* ... */ });
</script>

<form use:form>
  <label for=email>Email:</label>
  <input name=email id=email type=email>
  {#if $errors.email}
    <span>{$errors.email}</span>
  {/if}
  <button>Submit</button>
</form>

If a specific field has an error, Felte assigns an aria-invalid=true attribute to the appropriate input.

Using a Svelte component, which gives the most flexibility and would allow you to have access to your validation messages deep within the component tree without needing to pass the errors store around.
Modifying the DOM directly by adding and removing DOM elements.
Using Tippy.js to display your messages in a tooltip.
Using the browser’s built-in constraint validation API, which can be less friendly to mobile users.

For brevity, I am only going to write about the first package. But you can read more about the rest in the documentation.

Using a Svelte component to get your validation messages can be done with the package @felte/reporter-svelte. You’ll need to add it to your project using your favourite package manager:

# npm
npm i -S @felte/reporter-svelte

# yarn
yarn add @felte/reporter-svelte

Then you’ll need to import both the svelteReporter function to add to the extend property, and the ValidationMessage component which you will use to receive your validation messages:

<script>
  import { svelteReporter, ValidationMessage } from '@felte/reporter-svelte';
  import { createForm } from 'felte';

  const { form } = createForm({
      // ...
      extend: svelteReporter,
      // ...
    },
  })
</script>

<form use:form>
  <input id="email" type="text" name="email">
  <ValidationMessage for="email" let:messages={message}>
    <!-- We assume a single string will be passed as a validation message -->
    <!-- This can be an array of strings depending on your validation strategy -->
    <span>{message}</span>
    <!-- Shown when there's no validation messages -->
    <span slot="placeholder">Please type a valid email.</span>
  </ValidationMessage>
  <input type="password" name="password">
  <ValidationMessage for="password" let:messages={message}>
    <!-- If not slot is used, you'll need to handle empty messages -->
    <span>{message || ''}</span>
  </ValidationMessage>
  <input type="submit" value="Sign in">
</form>

Next steps

You can check more about Felte in its official website with some functional examples. There’s also a more complex example showcasing its usage with Tippy.js and Yup available on CodeSandbox.

Finishing thoughts

You don't really need Apollo

Pablo Berganza — Wed, 10 Jun 2020 22:21:13 +0000

The first time I tried GraphQL was when I would still have considered myself as just a back-end developer. About two years ago I gave myself the opportunity to learn it thanks to NestJS's support for it and I totally felt in love with it. The fact that it's basically self-documenting and the fact that you can ask for exactly the data you want with just one request made me feel that working with a GraphQL API as a front-end developer would feel really enjoyable.

Road to front-end GraphQL

I wanted to try to make something on the front-end side with this new knowledge, to get a better feel of it. By that time I was still learning the ropes on front-end with React (last time I did front-end, jQuery was the thing to use). So, naturally, I duckduckgo'ed graphql react and the first thing I found was Apollo. Apollo is a great tool that offers many features; you can even manage your whole application's state with it. But it did feel a bit heavy for someone who's just trying to learn how to use GraphQL, or for any small project in that sense. I will admit that it was really naive of me, but at the time I really thought: woah, so GraphQL is really only suitable for pretty big apps. Regardless, I kept on doing my experiments with Apollo. As I suspected I spent a lot of my time learning how to use Apollo, which is not bad per se, but of course it would feel daunting for anyone learning.

Sometime about last year I found urql which aims to be a lighter alternative to Apollo. I found this really appealing. And it was great. A simpler API and fewer features meant less time spent on the documentation and more time to actually build something with it. But it still felt pretty heavy for my use cases. Although right now I would probably choose urql over Apollo for a serious project, since I do feel Apollo tries to do too much for my taste.

Even though I haven't worked professionally with GraphQL yet, I've kept on using it for my personal projects. Still, I kept on feeling that the entry point for any front-end developer learning it was quite high. If you duckduckgo (or google) react graphql your top results will be Apollo and howtographql.com. If you go to the latter, you'll see that both Apollo and urql are listed as the beginner's choice. This I feel is an artificially high entry point for a beginner.

What's the alternative?

What are the minimum requirements for making a request to a GraphQL API from the browser? Well... just the fetch API. After all, you only need to make an HTTP POST request to the GraphQL endpoint. It only needs to contain a query/mutation in the body as a string and, optionally, the variables if they're needed for the query. It doesn't need to be a POST request, and it can have an application/graphql MIME type; but, to keep things simple, a POST request with an application/json MIME type should always work.

fetch(`${API}/graphql`, {
  method: 'post',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    query: `...`,
    variables: {
      ...
    },
  })
}).then(r => r.json())

You can turn this into a more reusable function with something like this:

async function gqlFetcher(query, variables) {
  const { data, errors } = await fetch(`${API}/graphql`, {
    method: 'post',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ query, variables }),
  }).then(r => r.json())
  if (errors) throw errors
  return data
}

A GraphQL server returns a 200 response even if it contains errors, so you generally only need to check if the response contains an errors property. This is still an optimistic way of handling it, since you're not accounting for other kinds of errors such as network errors that can return 4xx or 5xx responses. For the purposes of this post we'll leave it like this.

Some nicer ergonomics

This approach does make you lose the nice interface that Apollo and urql provide you. You can, of course, create your own hooks that provide a friendlier interface; however, I prefer to use Vercel's swr hook. This hook works for any kind of remote data fetching; it works by first returning data from the cache, then sending the fetch request, and finally returning the newly received data. It provides a nice interface for handling your data inside your component while keeping your UI, as they describe it, fast and reactive. The gqlFetcher function we made earlier is already compatible with the useSWR hook, so no additional work is required.

import useSWR from 'swr'

const gqlQuery = `...`

function Component() {
  // gqlFetcher is the same function we defined earlier
  const { data, error } = useSWR(gqlQuery, gqlFetcher)

  if (error) return <div>{/*...*/}</div> // JSX with error data
  if (!data) return <div>Loading...</div> // Loading component
  return <div>{/*...*/}</div> // JSX with returned data
}

In order to pass multiple arguments to the fetcher function, the swr hook allows you to pass an array as the first argument.

const gqlQuery = `...`
const gqlVariables = {
  // ...
}

function Component() {
  const { data, error } = useSWR([gqlQuery, gqlVariables], gqlFetcher)
  // ...
}

useSWR uses the first argument as a key that serves to uniquely identify the request. If an array is passed, swr shallowly compares each element and, if any of them has changed, it revalidates the request.

Existing tooling

If you don't feel like creating your own wrapper over fetch, you can use graphql-request. This is also a wrapper over the fetch API for making GraphQL requests that doesn't need much work to start using it. It already handles errors nicely and is isomorphic by default (which some people might not like). The swr GitHub page already provides an example using this.

import { request } from 'graphql-request'

const API = 'https://api.graph.cool/simple/v1/movies'
const fetcher = query => request(API, query)

function App () {
  const { data, error } = useSWR(
    `{
      Movie(title: "Inception") {
        releaseDate
        actors {
          name
        }
      }
    }`,
    fetcher
  )
  // ...
}

Conclusion

It feels there's an artificially high entry level for front-end developers who want to get into the GraphQL world. The fact that Apollo and urql are shown as beginner choices for learning GraphQL can make developers feel like these kinds of tools are actually required to work with a GraphQL API. This is, in fact, not the case; you can build a fully capable web application with just the fetch API and some other small libraries for extra features. I can't think of any small project that would actually require all the features that these big libraries have to offer. To clarify: I'm not saying you shouldn't use these tools if you want to; I'm saying you don't need to feel they're required to build what you want.

Svelte: my new obsession

Pablo Berganza — Sun, 19 Apr 2020 22:22:55 +0000

I admit I am the kind of person who gets immediately obsessed with something if it is new and interesting. That's how I got into Clojure, how I got into Rust, and how I got into the topic I'm writing about today: Svelte.

Svelte is not a new language I am learning, as it was with Rust and Clojure. It's a JavaScript framework for building single page applications (SPA). Like React, Vue or Angular. Its syntax may remind some people of Vue; but it has a major difference with the typical framework. Svelte does not have a runtime and, unlike the rest, it's not bundled with the rest of your code. Svelte is a compiler. It compiles your components into reactive JavaScript code that modifies the DOM directly. It will produce a small and more performant bundle.

How does it look?

Svelte tries to stay as close as possible to semantically correct HTML. This means that a simple HTML editor would do the trick for editing a Svelte component.

For example, the most minimalist component may look like this:

<p>Hello world!</p>

That's it! That's a valid Svelte component that the compiler will understand.

How to make it reactive?

Of course if you were going to write components like that, you would be better off writing plain HTML. The reason you're using a JavaScript framework is because you need a way to handle reactivity in your web application. So we need a way to add JavaScript to our component. As you would do with plain HTML, JavaScript can be added inside a script tag like this:

<script>
  console.log('Hello world!')
</script>

In order to add “state” to our component we just need to declare JavaScript variables:

<script>
  let message = 'Hello world!'
</script>

These variables can be accessed in the template by using curly braces. This is similar to how Vue does it.

<script>
  let messsage = 'Hello world!'
</script>

<p>{message}</p>

The message variable is reactive. If it were to change for some reason (e.g. an event), the contents of the p tag would be immediately updated. For example, we can create an input that updates the content of message.

The template of a Svelte component does not need to be a single element, so we can just add an input element right after the p element.

<script>
  let message = 'Hello world!'

  function onInput(event) {
    message = event.target.value
  }
</script>

<p>{message}</p>

<input value={message} on:input={onInput}>

But this is still too complicated. Svelte provides some “magic” directives in order to make certain operations easier. The bind directive helps with two-way data binding.

<script>
  let message = 'Hello world!'
</script>

<p>{message}</p>

<input bind:value={message}>

Svelte only handles reactivity on assignments. This means that array methods like push and pop won't trigger updates on the components.

Svelte also provides Handlebars like blocks to handle conditional rendering, asynchronicity and loops inside the templates.

What about styling?

Svelte provides a way to provide scoped styles to your components. As expected, this is done via the style HTML tag. Svelte will assign unique classes to each of your component's elements during compilation. You can use any valid CSS inside the tag, but a rollup/webpack plugin may be used to accept your favorite variant (e.g. SASS).

<h1>Hello world!</h1>

<style>
  h1 {
    color: purple;
  }
</style>

On compile time, the h1 tag will be assigned a class generated by Svelte and a CSS selector for this class will be added to the h1 on the style tag.

If you need to make the selector global you can wrap it in :global(...). For the example above, if we replaced h1 for :global(h1) it would apply the style globally to all h1 elements of the project. This can be really useful if your project contains dynamically generated HTML not controlled by Svelte, since Svelte wouldn't be able to assign unique classes to the elements inside it. Something like div :global(h1) would select all h1 elements inside all div elements of the component. This can be used to guarantee that the style remains scoped to the component.

Of course, you can always have a global CSS file to handle common styling for all components.

A more complete example

Here's how a simple to-do app would look like in Svelte:

<script>
  let todos = [], value = '';
  let filter = 'all';
  // The $: tells Svelte to make the statement reactive.
  // In this case, the assignment statement to "filtered" will be run
  // everytime "todos" changes.
  $: filtered = todos.filter(todo => {
    if (filter === 'checked') return todo.checked
    if (filter === 'unchecked') return !todo.checked
    return todo
  })
  function addTodo() {
    todos = [...todos, { value, id: Date.now(), checked: false }];
    value = '';
  }
  function toggleTodo(event) {
    const i = todos.findIndex(todo => todo.id === +event.target.id)
    todos[i].checked = event.target.checked
  }
</script>

<form>
  <label for=all>
    <input type=radio id=all value=all bind:group={filter}>
    All
  </label>
  <label for=checked>
    <input type=radio id=checked value=checked bind:group={filter}>
    Checked
  </label>
  <label for=unchecked>
    <input type=radio id=unchecked value=unchecked bind:group={filter}>
    Unchecked
  </label>
</form>
<form on:submit|preventDefault={addTodo}>
  <input bind:value>
  <button type=submit>Add Todo</button>
</form>
<ul>
  {#each filtered as todo, i (todo.id)}
    <li>
      <input
        id={todo.id}
        checked={todo.checked}
        type="checkbox"
        on:change={toggleTodo}
        >
      {todo.value}
    </li>
  {/each}
</ul>

<style>
  label {
      display: inline-block;
      margin: 0 10px;
  }
  li {
      list-style: none;
  }
</style>

This example uses some features I didn't talk about, but the official tutorial is great if you're interested in learning more.

Other features

Svelte also provides some other nice features, such as:

Built-in transitions and animations.
Easily access the document's head, window and body.
Lifecycles for the components.
Global stores.
Compatibility with server side rendering.
Components can be exported as web components.

Why rewrite the whole site?

Previously my site was written using Perun. It is a nice static site generator for Clojure that has tons of flexibility, since each step of the generation can be intercepted. But there were certain aspects of the generation that were hard to change or had little documentation. (I am not bashing on Perun, it is a perfectly great tool. I just wanted more freedom).

Perun generates a plain HTML output with no JavaScript. JavaScript needs to be injected manually. Each page is rendered by renderer functions written in Clojure which output HTML. Unless you installed extra packages, there is no built-in support for scoped styling. And, since the generator runs on top of the JVM, the generation of the site was quite slow.

This site is not written with plain Svelte. It is using Sapper. Sapper is a framework for Svelte inspired in Next.JS that allows to build server side rendered web applications. It can also export a static site like Next.JS does. This gives you much more freedom on how the site is generated at the cost of a bit more coding. For example, just as I did with Perun, each post's content source is a markdown file. But for Sapper I manually had to write the process the reads the markdown files and generates the HTML. This allowed me to use libraries I am much more familiar with, such as Marked for markdown parsing and Highlight.js for code highlighting.

The resulting site works as an SPA and has some features that I couldn't do previously, some of them:

Highlighting for GraphQL code.
Add working examples of code (such as the ones above).
Navigate the whole site without having to do a page reload.
Lazy loading of images.
Embedding external elements to blog posts, like YouTube videos.

It also brought some DX improvements such as:

Reusable components.
Scoped CSS styling, which helped with some headaches I had previously due to my lack of CSS knowledge.
Much faster generation of the static files.
Easily add more interactive elements to the site. (I might add a search bar for my blog posts at a later time).
It's easier to follow a more maintainable code structure.

One downside to using Svelte is its lack of TypeScript support (although this is being worked on).
Another downside is that Sapper is still in early development, so I would not recommend it for serious projects. Svelte itself is ready for production, though.
It also has a much smaller ecosystem than other mainstream frameworks.

Conclusion

Even taking into account the downsides mentioned before, Svelte/Sapper has been a joy to work with. In under 20 hours of combined work I managed to rewrite my whole site. Svelte should be an excellent choice for performance critical web applications, and it's syntax is easier to grasp compared to other frameworks. It should definitely not be considered a “toy” framework and I encourage you to add it to your tool set.

As a little extra, here's the talk that got me excited about Svelte. I recommend everyone with a slight interest on Svelte to watch it.

DEV Community: Pablo Berganza

Shadow DOM, Firefox and contenteditable

Creating a Chai like assertion library using proxies

The “expect” function

Adding meaning to our properties

Defining properties

Negating assertions

Do not throw normal Errors

Conclusion

Announcing Felte 1.0: A form library for Svelte, Solid and React

Usage

Svelte

Solid

React

New features

Breaking changes

Read more

Final words

Felte: An extensible form library for React

Features

How does it look like?

Where can I see my data?

I might need some validation here

Handling complex scenarios via extensibility

Validators: Integrations with popular validation libraries

Reporters: Displaying validation messages

Next steps

Finishing thoughts

Felte: An extensible form library for Solid

Features

How does it look like?

Where can I see my data?

I might need some validation here

Handling complex scenarios via extensibility

Validators: Integrations with popular validation libraries

Reporters: Displaying validation messages

Next steps

Finishing thoughts

Felte: An extensible form library for Svelte

Features

How does it look like?

Where can I see my data?

I might need some validation here

Handling complex scenarios via extensibility

Validators: Integrations with popular validation libraries

Reporters: Displaying validation messages

Next steps

Finishing thoughts

You don't really need Apollo

Road to front-end GraphQL

What's the alternative?

Some nicer ergonomics

Existing tooling

Conclusion

Svelte: my new obsession

How does it look?

How to make it reactive?

What about styling?

A more complete example

Other features

Why rewrite the whole site?

Conclusion