Forem: Matheo Daninos

How to transform Component Development with Storybook and Symfony UX ?

Matheo Daninos — Mon, 17 Jun 2024 14:17:39 +0000

Hey everyone! I am so excited about this article because what I'm going to show you here has been my dream since I first heard about Symfony UX! I will demonstrate a setup that makes me incredibly productive, but most importantly, brings me a lot of joy.

As you know, I love working with components (TwigComponent/LiveComponent), and I also adore Storybook! In my last article, I showed you how to use Storybook to share your components with your team. Today, we're going to dive even deeper. Storybook has been a game changer for me primarily because it provides the best environment to work with components. Components are visual and interactive, and Storybook offers a fantastic playground to view, interact with, and test your components. It helps you create beautiful, interactive, fun, and robust components. So, let’s see how this works!

Working in isolation

If you remember from my first article, we discussed the four main rules of component architecture. One of these rules is independence. Your components should not depend on the context of the page; you should be able to move your component from one page to another without any issues.

The great thing about using Storybook is that it enforces this rule. Storybook operates by isolating each component, allowing you to test them one by one in complete isolation. This ensures that if your component works in Storybook, it will work seamlessly on all your pages.

Hot Reload

So when I am working on a new component, the first thing I do is create a story. A really basic one that just gives me the environment to start building.



import Alert from '../templates/components/Alert.html.twig';
import { twig } from '@sensiolabs/storybook-symfony-webpack5';

export default {
  component: (args) => ({
    components: {Alert},
    template: twig`
      <twig:Alert>
        {{ message }}
      </twig:Alert>
  `
  }),
}

export const Default = {}

Then I can just focus on creating my component. With hot reload, I get quick feedback, which makes things really comfortable for a visual component like an alert.

No need to press F5 anymore or try your component on random pages. Just write a story for your Storybook, and you will have a nice development environment.

Interactions

When working on a new feature, one of the most frustrating aspects can be having to interact with your component to access the part you want to test. For example, I have a small form here, and I want to see how it looks when the entered email is invalid.

Doing this manually can be a huge waste of time, especially for larger components. That's why I don’t do that anymore! With Storybook, you can automate your interactions to reach the exact state you want to test

How can I do that ?

First, I set up my Default story:



import Email from '../templates/components/Email.html.twig';
import { twig } from '@sensiolabs/storybook-symfony-webpack5';

export default {
  component: (args) => ({
    component: {Email},
    template: twig`
        <twig:Email/>
    `,
  })
}


export const Default = {}

Then, I add a new story called ‘WrongEmail’:



import Email from '../templates/components/Email.html.twig';
import { twig } from '@sensiolabs/storybook-symfony-webpack5';
import {userEvent, waitFor, within, expect, fn} from "@storybook/test";

...

export const Default = {}

export const WrongEmail = {
  play: async () => {
      ...
  }
}

In this story, I define a play function. This function contains snippets of code executed after the story renders, allowing you to interact with your components and test scenarios that would otherwise require manual intervention.

The play function looks like this:



import {userEvent, waitFor, within, expect, fn} from "@storybook/test";

play: async ({canvasElement}) => {
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByLabelText('Email'), 'wrongemail');
    await userEvent.type(canvas.getByLabelText('FirstName'), 'Kobe');
    await userEvent.type(canvas.getByLabelText('LastName'), 'Bryant');

    await userEvent.click(canvas.getByRole('button'));
  }

Storybook provides a wrapper around https://testing-library.com/.

If you are not familiar with this library, it is widely used in the JS community, very robust, and has a strong community around it, making it easy to find good resources.

So, if we get back to our play function, we see that we define an argument canvasElement. This canvasElement represents the canvas where our story is rendered.

Then we do the following:



const canvas = within(canvasElement);

Here, we wrap our canvas in an object to enable better assertions later.



await userEvent.type(canvas.getByLabelText('Email'), 'wrongemail');

This line simulates the user typing ‘wrongemail’ in the input with the label Email.

We do the same thing for the first name and last name:



await userEvent.type(canvas.getByLabelText('FirstName'), 'Kobe');
await userEvent.type(canvas.getByLabelText('LastName'), 'Bryant');

Then we click on the submit button:



await userEvent.click(canvas.getByRole('button'));

And just like this, Storybook will perform the interactions for me, so I no longer need to do all these steps by hand.

You can also easily debug what happens using the interaction panel and go back to previous steps.

I just love this feature—it saves me so much time. Components are visual and interactive, and having an environment that lets me see and interact with my components easily is a real game changer.

And you know what? We can do even more! We can use Storybook to test our components!

Testing

I have a component, RadioList, that displays a list of radios and a search bar. When the user types into the search bar, the component updates the list of radios accordingly.

I know the content of my database, so I want to ensure that when I type "90," four radios are displayed.

We already know how to do this by writing a play function and adding an assertion at the end.



import {twig} from "@sensiolabs/storybook-symfony-webpack5";
import {userEvent, waitFor, within, expect} from "@storybook/test";

export default {
  component: (args) => ({
    template: twig`
      <twig:RadioList />
    `
  }),
}

export const Default = {
};

export const Play = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByRole('searchbox'), '90');

    await waitFor(() => {
      expect(canvas.queryAllByRole('listbox')).toHaveLength(4)
    });
  },
}

And just like that, I have a real test that fully tests my LiveComponent from PHP to JavaScript!

I can see that my test is working by checking the interaction panel. I now have a green "Pass" indicator.

We can go even further and run all our tests at once by running:



npm run test-storybook

What's interesting is that even simple stories with no interaction are tests. Storybook checks that all your components are rendered correctly. This is just a test runner, so you can completely run all your tests in your CI.

By leveraging Storybook for testing, you ensure a seamless and efficient development process, catching issues early and maintaining high-quality components.

Leveraging Storybook has transformed the way I develop and test components. From working in isolation to hot reloading, automating interactions, and writing comprehensive tests, Storybook provides a development environment that boosts productivity and fun. Although we still rely on Node.js, it’s not a big deal since Storybook is only used in your development environment and not deployed to production.

Components are often visual elements of your application, and maintaining a visual development approach greatly enhances the process. Storybook ensures that your components are robust, interactive, and beautifully designed. I hope you enjoyed this article and found it helpful. See you soon!

How to share your TwigComponent with your team ?

Matheo Daninos — Wed, 15 May 2024 20:40:21 +0000

Quick Reminders

This article follows my previous one. If you haven't read it yet, you can do so here: Symfony Can Help You Fall in Love with Your Front-End Team.

To give you context, we are developing a small application that lets you listen to various live radio stations.

We've adopted the principles from Component Architecture and, naturally, after designing various components of differing sizes and complexity, we are beginning to establish what is known as a design system.

Overwhelmed by All These Components?

It's common to feel overwhelmed as the number of components grows. In a team setting, or when developing new features, it's crucial to know what components are already available. When we create a new component, we want to share it immediately with our teammates.

So, how do we manage this?

Documenting everything? Yes, but it's time-consuming, and let's face it, we're developers—we tend to be a bit lazy.

But here’s some good news: there’s already a solution in the JavaScript world called Storybook!

What is Storybook?

Storybook is an exceptional tool for documenting components. It's specifically designed for this purpose, but it offers much more. It allows us to build components in isolation, test them, and mock them to see how they appear in different states or create specific end-to-end scenarios for each component, among many other features! And if you're still not convinced, just look at how beautiful your documentation can look with Storybook:

Here you can see an example of how I documented our Alert component. This documentation helps my teammates understand how to use the component and the different variations available.

Integrating Storybook with Symfony

Thanks to contributions from the community, you can now use the StorybookBundle for Symfony, developed by my friend Nicolas (not Grekas). I’m very excited about this release—not only because it involved a lot of work, but also because this bundle demonstrates that Symfony can match any front-end framework in capabilities.

To get started, install the bundle with Composer:



**composer require sensiolabs/storybook-bundle**

Then you can use the init command to configure everything for you.



bin/console storybook:init

Don’t run away! We gonna use npm but just to run the storybook. This will not have any impact to your project. And the bundle have an integration with AssetMapper, npm is just to start the storybook.



npm install

And to finish



npm run storybook

And just like that you are fully set up! You can go to: http://localhost:6006/ (it can be something else if your port is not available) to admire your storybook.

Write your first story

Let's get started! The first thing we want to do is show our Alert component in our Storybook.



import Alert from '../templates/components/Alert.html.twig';
import { twig } from '@sensiolabs/storybook-symfony-webpack5';

export default {
  component: (args) => ({
    components: {Alert},
    template: twig`
      <twig:Alert color="{{ color }}" size="{{ size }}" position="{{ position }}">
        {{ message }}
      </twig:Alert>
  `
  }),
  argTypes: {
    color: {
      options: ['blue', 'red', 'green'],
      control: {type: 'radio'},
    },
    size: {
      options: ['lg', 'md', 'sm'],
      control: {type: 'radio'},
    },
    position: {
      options: ['top-left', 'top-right', 'bottom-left', 'bottom-right'],
      control: {type: 'radio'},
    }
  }
}

export const Default = {
  args: {
    color: 'blue',
    size: 'sm',
    position: 'top-left',
    message: 'Hello world!'
  },
}

Let me explain what we have here:



import Alert from '../templates/components/Alert.html.twig';

We import our component template. Yes, this is Twig code, but thanks to the bundle, it works!



import { twig } from '@sensiolabs/storybook-symfony-webpack5';

Then we import a twig function that allows us to write Twig code directly in our JavaScript.



export default {
  component: (args) => ({
    components: {Alert},
    template: twig`
      <twig:Alert color="{{ color }}" size="{{ size }}" position="{{ position }}">
        {{ message }}
      </twig:Alert>
  `
  }),
  argTypes: {
    color: {
      options: ['blue', 'red', 'green'],
      control: {type: 'radio'},
    },
    size: {
      options: ['lg', 'md', 'sm'],
      control: {type: 'radio'},
    },
    position: {
      options: ['top-left', 'top-right', 'bottom-left', 'bottom-right'],
      control: {type: 'radio'},
    }
  }
}

Here is everything that is common to all stories related to our Alert component.

We have the component key that allows us to define our component, the Alert, and a template. We use the twig function, and everything inside can be any valid Twig code we want. Here, we simply render the Alert component and give this component props: color, size, and position.

Then we define some argTypes that allow us to describe the controls we want under the story.

Then we define our first story:



export const Default = {
  args: {
    color: 'blue',
    size: 'sm',
    position: 'top-left',
    message: 'Hello world!'
  },
}

And just like that, we have the following result!

You can play with the controls to test your component with different variations.

Then we can add more stories:



export const Large = {
  args: {
    color: 'blue',
    size: 'lg',
    position: 'top-left',
    message: 'Hello world!'
  },
}

export const Error = {
  args: {
    color: 'red',
    size: 'lg',
    position: 'top-left',
    message: 'Hello world!'
  },
}

export const Success = {
  args: {
    color: 'green',
    size: 'lg',
    position: 'top-right',
    message: 'Good job!'
  },
}

So now, if we look at the menu of our Storybook, we have three stories:

This is great, but we can go a bit further. Add the tags: ['autodocs'] to your export default:



export default {
  component: (args) => ({
    components: {Alert},
    template: twig`
      <twig:Alert color="{{ color }}" size="{{ size }}" position="{{ position }}">
        {{ message }}
      </twig:Alert>
  `
  }),
  ...
  tags: ['autodocs']

And just by adding this tag, Storybook creates a documentation page for us:

And if that's not crazy enough, you can create a .mdx file:



import {Canvas, Controls, Meta, Story} from "@storybook/blocks";
import * as AlertStories from "./Alert.stories";

<Meta of={AlertStories} />

# Alert

An Alert display information to the user.

<Story of={AlertStories.Default} />

Here are the properties you can use on the alert component:

<Controls of={AlertStories.Default} />

## Error

For error message you can use:

<Canvas of={AlertStories.Error} />

## Success

For success message you can use

<Story of={AlertStories.Success} />

As you can see in this .mdx file, we were able to import our stories into our documentation to make everything playable.

This is really cool! But you know what? This is only the beginning! We used Storybook to document a simple component, but Storybook can do much more. It can help with developing complex components or testing your components. We still have a lot to learn with Storybook, so stay tuned for the next article!

Thanks for reading. See you soon!

Symfony can help you fall in love with your front-end team!

Matheo Daninos — Thu, 11 Apr 2024 16:44:55 +0000

A little context

I'll place myself in the context of a Symfony application. We are a team of 8 developers: 6 dedicated backend Symfony developers and 2 frontend developers, including one who is a junior.
This shows that our team has a strong inclination towards backend development. The first thing not to do is to underestimate the frontend. Don't think that frontend development is easy; on the contrary, it requires expertise - an expertise that our backend developers lack.
Our goal, therefore, will be to take as much weight off the shoulders of our frontend developers as possible, without forcing backend developers to step out of their comfort zone.

The application I'll use for this example is as follows:

We have a set of radios, multiple pages with different radios, and if you click on any of them, then you can listen to a live stream of that radio.

Let's start working!

So, we start by making the first page and everything goes well. But as we proceed to the next one, we encounter our first problem. Our frontend developers simply reused the code from the first page on the next. They immediately encounter this error:

This is an error we're well acquainted with. We forgot to pass a variable to our Controller. Solving it is simple, but this error illustrates a deeper problem. Our frontend developer is dependent on our backend developers. Each time they make a new page, they have to ask the other developers to prepare a controller with the variables they need. We want to make our frontend independent. We aim to advance the project with as little friction between our backend and frontend devs as possible.

Component Architecture

For that, I propose that we cater to the frontend developers by using the component architecture. I won't go back over what component architecture is, but I invite you to read my article on this topic if you haven't already (https://dev.to/webmamba/how-to-integrate-component-architecture-into-symfony-4bjb).

So, we start by breaking down our page into many small components. Our list of radios will be a RadioList component composed of several Radio components. These Radio components are themselves made up of smaller components. To do all this, the frontend developer does not need us at all. They write anonymous component, component only made off a template:

RadioCard

<div
        class="
        transition ease-in-out delay-150 hover:-translate-y-1
        hover:scale-110 duration-300 aspect-square relative overflow-hidden
        rounded-lg bg-white/50 shadow-lg transition duration-300
        ease-in-out hover:shadow-2xl p-4"
>
    {% block content %}
    {% endblock %}
</div>

RadioCardImage

{% props logo, name %}

<div class="relative overflow-hidden border-slate-500/50 border rounded aspect-square">
    <div>
        <img
                class="w-full h-full object-cover self-center"
                src="{{ logo }}" alt="{{ name }}"
        />
    </div>
</div>

Radio

{% props radio %}

<twig:RadioCard>
        <twig:RadioCardBackground logo="{{ radio.logo }}" radio="{{ radio.name }}" color="{{ radio.color }}"/>
        <twig:RadioCardImage logo="{{ radio.logo }}" name="{{ radio.name }}" />
        <div class="absolute bottom-2 right-2">
                <twig:PlayerButton/>
        </div>
</twig:RadioCard>

I repeat, to make this list of components, the frontend did not need to write any PHP. They do all this work with complete autonomy.

Backend dev it's your time!

Once all these components are made to integrate our list of radios, the backend developers now only have to make a RadioList component, which has the following class:

<?php

namespace App\Twig\Components;

use App\Repository\RadioRepository;
use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;

#[AsTwigComponent]
final class RadioList
{
    public ?string $filter = null;

    public function __construct(
        private readonly RadioRepository $radioRepository
    ) {}

    public function getRadios(): array
    {
        if ($this->filter === null) {
            return $this->radioRepository->findAll();
        }

        return $this->radioRepository->findByGenre($this->filter);
    }
}

But where it becomes really interesting is for the template, which will now only be this. All the work will have been pre-done by our frontend developers.

{% for radio in this.getRadios %}
    <twig:Radio :radio="radio"/>
{% endfor %}

This is great, we now have a working component able to communicate with our database, that anyone can reuse on every page. And all that while sticking to what we are good at, PHP code.

CVA

But we need to go a bit further. For example, for this site, we will need to set up an alert system. The informational alerts will be at the top left in blue, errors at the bottom in bold red, etc. We don't want a component for each variation; we want modular components.

For this in Symfony, we can use CVAs (Component Variant Attributes). Here's how it works:

{% props color, size, position %}

{% set alert = cva({
    base: 'min-w-96 absolute rounded-lg shadow-md bg-slate-200 text-white z-50',
    variants: {
        color: {
            'blue': 'bg-blue-800 shadow-blue-800',
            'red': 'bg-red-800 shadow-red-800',
            'green': 'bg-green-800 shadow-green-800',
        },
        size: {
            'sm': 'p-2 mb-2 text-sm',
            'lg': 'p-4 mb-4text-lg',
        },
        position: {
            'top-left': 'top-4 left-4',
            'top-right': 'top-4 right-4',
            'bottom-left': 'bottom-4 left-4',
            'bottom-right': 'bottom-4 right-4',
        }
    }
}) %}

<div class="{{ alert.apply({color, size, position})|tailwind_merge }}" role="alert">
    {% block content %}
    {% endblock %}
</div>

We create our Alert component. At the start of this file, we'll use the cva function. To this function, we'll pass a key array, the first key of which will be 'base' and will take as its value all the CSS classes that will be present in all variations of our components. Next, we'll define our variants. So here, variants on color, size, or position. Then, we'll apply our cva to the div of our alert.

And just like that, we've created a component with a multitude of possible variations.

So, quite naturally, we've been able to create a set of components of different sizes, with different variations, from which our developers can draw to implement new features. We have the beginnings of a design system. Working in this way allows our front-end and back-end developers to work without stepping on each other's toes, all while staying on a common codebase. Implementing a new feature is now picking between few components from our design system, we are dangerous!

Thank you for reading, see you soon for an article on how to document this design system!

How to integrate Component Architecture into Symfony?

Matheo Daninos — Fri, 15 Mar 2024 09:40:02 +0000

Miscommunication in our projects is costly. A single misunderstood User Story can result in 3 days of wasted development time. Additionally, when developers do not use the same programming language, it may be necessary to construct APIs to facilitate communication, which can also be expensive. It is important to consider why front-end developers may be hesitant to work with Twig and how this can lead to a disconnect between front-end and back-end development.

Front-end developers, like back-end developers, have their own set of habits, principles, and rules that make them feel safe, efficient, and at home.

One of the most important principles is Component Architecture, which serves as the foundation for major JavaScript frameworks such as Svelte, React, and Vue.

What is Component Architecture?

4 main rules define Component Architecture.

Composition

A page is no longer just a page, but rather a collection of small, reusable components. These components can be assembled to form a page. For example, there could be a component for the title and another for the training list. The training list component could even be composed of smaller components, such as a training card component. The goal is to create the most atomic components possible.

Independence

For a component to be infinitely reusable, it should not be aware of its context. It should function identically when placed on another page.

Properties

Our component must remain independent, but we can customize it based on the context. For instance, we can change the label of a button while keeping its appearance the same by assigning it properties. Properties are attributes that the component will adopt at creation and maintain throughout its life.

States

A component can have multiple states. For instance, a button can transition from an active state to a loading state and then to a disabled state. Typically, a state principle is used to achieve this. The difference between a state and a property is that a property remains constant throughout the lifespan of the component, while a state changes.

Does it work with Symfony?

The answer is yes!

Start by installing

composer require ux-twig-component

Then in your template folder, create a component folder. Inside the component folder, add a file named Button.html.twig.

<button class="btn btn-primary">Click me</button>

And just like that… you have created your first component! Congrats

Now, how will you use it? Let's assume you want to use it on your homepage. Open your home.html.twig template.

// the content of your template
<twig:Button/>

This way, you have successfully imported a component for the first time.

Can I include properties for this component?

Sure, you can! Simply go back to your button template and add a label property like this:

{% props label = 'Click me' %}

<button class="btn btn-primary">{{ label }}</button>

Now, our component has a label property, with a default value 'Click me'. Without this property, using the component would result in an error.

To assign a property to a component, follow these steps:

<twig:Button label="Submit"/>

How do we do composition?

If we want our component to contain an icon before our label, let's modify the template of our button.

{% props label = 'Click me' %}

<button class="btn btn-primary">
        {% block content %}
        {% endblock %}
        {{ label }}
</button>

So, I have added a block that I have named content. The term "content" is important because it corresponds to the default block.

You can now use your button in this way:

<twig:Button label="Submit">
    <twig:Icon/>
</twig:Button>

We added an Icon component to the Button component by placing it between the tags. This transfers the Icon component to the content block.

This block is a powerful tool for for precise composition. You can even create your own blocks.

{% props label = 'Click me' %}

<button class="btn btn-primary">
        {% block content %}
        {% endblock %}
        {{ label }}
        {% block after_label %}
        {% endblock %}
</button>

<twig:Button label="Submit">
    <twig:Icon/>
    <twig:block name="after_label">
            +
    </twig:block>
</twig:Button>

Note that we use the <twig:block tag to easily refer to the block of our component.

And what about the states of our component?

You have two options to manage the states of your component:

For the first option, if you want your component's CSS classes to change based on user actions, you can use Stimulus, a small JavaScript library that integrates perfectly with Symfony through the StimulusBundle. With just a few lines of JavaScript code, you can achieve your goal.
But imagine having a component with complex states that depend on the back-end. In this case, you have the option of using LiveComponents. I won't go into details, but here is what you need to remember: with very little code, you can perform complex actions on your back-end without reloading the page.

The present article is meant to give you an overview of how to use Component Architecture with Symfony. I know this article will be read mainly by back-end developers, but spread the word. It is suitable for both back-end and front-end developers. Even front-end developers can feel at home with Symfony. And you, back-end developers, you can continue to have fun while developing a quality front-end.

Thank you for reading!