Vamos abordar os conceitos que envolvem doc blocks, parameters e argTypes com exemplos de suas utilizações.

Recentemente me deparei com a necessidade de documentar uma biblioteca de componentes pela primeira vez. Resolvi aproveitar um pouco do conhecimento adquirido nessa jornada para compartilhar aqui com vocês.

Por que documentar seus componentes?
Ao documentar os seus componentes, você além de facilitar o entendimento da utilização deles para o coleguinha que for pegar pela primeira vez. Também facilita para o seu eu do futuro que desenvolveu aquele componente já tem alguns meses. Além disso, podemos adicionar as alterações dinâmicas para quem gostaria de por exemplo ver outro tema do seu componente de botão apenas clicando no nome do tema.

Como documentar o seu componente
A documentação ocorre dentro do arquivo stories.jsx do seu componente. É lá que a magia acontece e você determina como será a apresentação dele para quem estiver acessando a página do seu storybook. Para isso precisamos entender o conceito de alguns aliados que o storybook nos disponibiliza:

Parameters — é esse carinha que vai nos permitir codificar e controlar tudo que envolve o ambiente do nosso componente. É dentro dele que vamos trabalhar hoje. Vamos passar o doc blocks para trazer as informações do nosso componente de uma forma mais bonita para todos que acessam o storybook.

Essa é a estrutura padrão que fica dentro do arquivo stories.tsx do seu componente.

doc blocks — é utilizado para documentar e compartilhar componentes UI através de uma interface bonitinha. Possui features que nos permitem interagir diretamente com o componente através dessa interface, e adicionar blocos de código para copiar e colar.

Exemplo da estrutura mostrada anteriormente, mas agora com seus blocos de documentação adicionadas:

Vamos dar uma olhadinha tag por tag para maior compreensão.

<Title /> Renderiza uma tag de estilo H1
<Subtitle /> Renderiza uma tag de estilo H2
<Description /> Renderiza uma tag de estilo P
<Stories /> Quando não recebe uma prop indicando qual renderizar, ele pode renderizar todos os exemplos de componentes que existe dentro do arquivo
<Source /> É aqui que adicionamos um trecho de código com a funcionalidade de copiar e colar junto. Note também que no meu exemplo eu adicionei a tag dark para que o bloco de código fique escuro.
<Primary /> Mostra o primeiro componente do arquivo stories. Geralmente é utilizado após o título e descrição do componente.
<Controls /> É a interface dinâmica que além de documentar o componente, também permite uma interação com ele. O que alimenta esse carinha é o argTypes que vamos ver a seguir.

Exemplo de como isso irá renderizar no Storybook (sem a chamada do <Controls /> junto):

argTypes — Especifica e documenta o comportamento dos argumentos esperados pelo componente, e também os tipos de valores que são aceitos por cada um deles. Quando utilizado sem ser em conjunto do Controls(doc blocks, citado anteriormente), mostra essa lista estática em uma tabela:

Quando utilizado em conjunto do Controls mostra esses argTypes um por um em cada linha da tabela. A diferença é que agora mostra de forma dinâmica para que possa haver interações diretas com o componente.

No exemplo utilizando o Controls, nós temos uma coluna a mais que permite essa interação direta com o componente.

Exemplo completo de como ficaria um arquivo stories com tudo que aprendemos:

Espero que esse artigo tenha ajudado você a desmistificar um pouco a parte da documentação dos componentes, ou pelo menos tenha despertado a curiosidade de tentar por aí também.

Para entender mais sobre argTypes e seu funcionamento acesse a documentação do Storybook

Até a próxima!