Tutorial de utilização Storybook

Este é um tutorial de utilização. Para o tutorial de instalação, veja: https://dev.to/gustavoacaetano/tutorial-de-instalacao-do-storybook-com-tailwind-324l

Iniciar Storybook

Para iniciar o Storybook, execute o comando:

npm run storybook

Estrutura de arquivos

Após a instalação, os arquivos ficarão dentro da pasta src/stories:

Junto com os arquivos, terá uma pasta assets com todas as imagens utilizadas no arquivo Configure.mdx.

Para melhor organização, recomendo uma estrutura de:

stories/
├─ Bases/
|  ├─ ComponenteBase/
│  |  ├─ ComponenteBase.vue
│  |  ├─ ComponenteBase.stories.ts
│  |  ├─ ComponenteBase.css
├─ Complexos/
|  ├─ ComponenteComplexo/
│  |  ├─ ComponenteComplexo.vue
│  |  ├─ ComponenteComplexo.stories.ts
│  |  ├─ ComponenteComplexo.css

Porém, sinta-se livre para utilizar da forma que melhor se encaixa no seu projeto.

Arquivo de documentação (.mdx)

O arquivo Configure.mdx contém informações sobre o Storybook. Se deseja criar um arquivo semelhante para documentação, substitua o arquivo Configure.mdx por um arquivo NomeDoArquivo.mdx:

import { Meta } from "@storybook/blocks";

<Meta title="Título na sidebar" />

<div className="sb-container">
  <div className='sb-section-title'>
    # Titulo da página

    Esse Storybook contém os componentes utilizados no projeto NomeDoProjeto.
  </div>
</div>

<style>
  {`
  .sb-container {
    margin-bottom: 48px;
  }

  .sb-section-title {
    margin-bottom: 32px;
  }
  `}
</style>

Após, personalize o arquivo da forma que preferir.

Se estiver vendo este erro:

Clique na opção com o novo título na sidebar.

Sidebar do Storybook

A estrutura dos arquivos, por enquanto, impactará somente na forma de trabalhar na IDE. Para modificar a sidebar do Storybook existem diferentes formas.

Inicialmente, sua sidebar estará parecida com esta imagem:

Dentro do arquivo Componente.storie.ts, pode-se alterar a estrutura da sidebar através do title:

...
const meta = {
  title: 'Pasta1/Pasta2/Componente',
...

Exemplo:

const meta = {
  title: 'Componentes/Complexos/Header',

Para diferentes formas de alteração, veja o vídeo do canal da Chromatic:
https://www.youtube.com/watch?v=zrdcCSTGo4A

Desenvolvimento com Storybook

O objetivo do desenvolvimento com o Storybook é isolar componentes e trabalhar de forma individualizada para reuso.

Quando estiver desenvolvendo, o arquivo Componente.vue deve ser o componente do seu trabalho. O Storybook servirá para testar seu componente através do Componente.stories.ts.

Esse arquivo será composto da seguinte forma:

// IMPORTACOES
import type { Meta, StoryObj } from '@storybook/vue3';
import { fn } from '@storybook/test';
import Componente from './Componente.vue';

// METADATA PARA CONSTRUCAO DO COMPONENTE
const meta = {
  title: 'Componentes/Bases/Componente',
  component: Componente,
  tags: ['autodocs'],
  argTypes: {
    argumento: tipo,
    ...
  },
  args: {
    argumento: valor,
    ...
    // Para os eventos, adicione o fn() para monitorar
    // e apresentar o evento na aba 'Actions'
    onEventoComponente: fn()
  },
} satisfies Meta<typeof Componente>;
export default meta;

E no final do arquivo, ficarão os Stories, que são casos de uso do componente.
Utilize os argumentos do componente para criar os diferentes casos.

// CASOS DE USO
type Story = StoryObj<typeof meta>;
export const FirstStory: Story = {
  args: {
    argumento: valor,
    ...
  },
};

export const SecondStory: Story = {
  args: {
    argumento: valor,
    ...
  },
};

Para cada Story, pode-se acompanhar no Storybook o visual e relacionados de cada componente.

Os controles ajudam a realizar ajustes nos casos de uso por meio da interface. Essas mudanças podem ser salvas no código posteriormente:

Utilize o fn() no código dos eventos do componente para acompanhar se os eventos estão sendo disparados na aba Actions:

Expanda a Action para visualizar os parâmetros, isso será útil para ações específicas que podem aparecer em certos componentes:

Documentação de componentes

A documentação dos componentes também é feita por arquivos .mdx.

Arquivo Componente.mdx:

import { Meta, Story, Canvas } from '@storybook/blocks';
import * as ComponenteStories from './Componente.stories';

<Meta title="Componente" of={ComponenteStories} />

# Componente
Teste `MDX` para documentar o componente `Componente`. Para mais sobre a documentação de componentes: <br/>
https://storybook.js.org/addons/@storybook/addon-docs

<Canvas>
  <Story of={ComponenteStories} />
</Canvas>

Mais informações

Para mais informações e detalhes gerais, consulte a documentação oficial do Storybook:
https://storybook.js.org/docs

Veja também o canal da Chromatic no YouTube:
https://www.youtube.com/@chromaticui