@zydon/common

Design system da Zydon

Instalação no seu projeto

• instalação pacote: yarn add @zydon/common
• instalação dependências necessárias: yarn add @emotion/react @emotion/styled @mui/lab @mui/material @mui/x-data-grid-premium @mui/x-date-pickers-pro @mui/x-license-pro react-hook-form

Configuração @zydon/common

Basta fazer a seguinte configuração no arquivo main.ts:

import React from 'react';
import { LicenseInfo } from '@mui/x-license-pro';
import { Common } from '@zydon/common';
import ReactDOM from 'react-dom/client';

import '@zydon/common/styles.css';

import App from './App';

LicenseInfo.setLicenseKey(import.meta.env.VITE_MUI_PREMIUM_KEY);

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <Common themeColor="cor_hexadecimal_aqui">
      <App />
    </Common>
  </React.StrictMode>,
);

Recursos disponíveis

Esse pacote tem os seguintes recursos disponiveis (components, hooks, utils e types):

Componentes

• animate: recursos construídos utilizando framer-motion
• Autocomplete: componente dropdown de seleção única/múltipla
• ColorPickerInput: componente de seleção de cor
• Common: componente wrapper/provider que faz esse pacote funcionar
• CommonSSR: componente wrapper/provider que faz esse pacote funcionar em aplicações NextJS (SSR)
• ConfirmDelete: mensagem de confirmação de exclusão
• CustomAvatar e CustomAvatarGroup: avatares customizados
• DataGrid: componente de tabela construido em cima do MUI-Datagrid
• Delayed: componente que renderiza um children com um delay
• Drawer: componente Drawer construido em cima do MUI-Drawer
• FixedProgressBar: barra de progresso de loading que é apresentado fixo no topo da tela
• Iconify: componente de ícones SVG construido em cima do @iconify/react
• Incrementer: input numérico com botões laterais para incrementar/decrementar o valor
• ImageCrop: componente para cortar imagens
• Label: componente que renderiza uma tag bonitinha
• MaskedInput: input com máscara. Util para campos como CPF, CNPJ, Telefone
• MenuPopover: menu flutuante com setinha apontado para um ponto escolhido
• Modal: componente de modal
• NumberInput: input que aceita somente números
• Portal: componente que renderiza o children em outro local desejado React Portals
• Scrollbar: Scrollbar bonitinha construido em cima do simplebar-react
• SearchInput: componente para busca/filtros. Funciona com onChange e como click na tecla enter
• snackbar: componente para mostrar mensagens [sucesso | alerta | informação | erro] para o usuário

const { enqueueSnackbar } = useSnackbar();
enqueueSnackbar('Mensagem', { variant: 'error' });

• Steps: componente que indica etapas e o progresso. Construido em cima do MUI-Stepper
• TabPanel: componente para renderizar o conteúdos de uma Tab. Todas as tabs são rendreziadas, mas somente o conteúdo da Tab ativa será exibido
• ThemeProvider: wrapper/provider para configuração do tema. (Provavelmente vc nunca vai precisar usá-lo, já que ele já está includo no component <Common />)
• upload (Upload, UploadAvatar, UplaodBox e UploadWithCrop): componentes para uploads de arquivos

Componentes de formulário (react-hook-form)

• Form: componente de formulário construido em cima do react-hook-form. (Todos os componentes abaixo funcionam somente dentro desse componente:) <Form />
• Autocomplete: componente dropdown de seleção única/múltipla
• Checkbox / MultiCheckbox: caixa seleção
• Codes: campos para inserção de código. Ex: código recebido por e-email
• ColorPicker: componente de seleção de cor
• DatePicker: componente de seleção de data. Construido em cima do MUI-DatePicker
• DateRangePicker: componente de seleção de intervalo de data. Construido em cima do MUI-DateRangePicker
• DateTimePicker: componente de seleção de data e hora. Construido em cima do MUI-DateTimePicker
• Field: componente de inserção de texto. Construido em cima do MUI-TextField
• MaskedInput: componente de input com máscara. Util para campos como CPF, CNPJ, Telefone
• Password: componente para inserção de senha com um olhinho para visualização da senha no canto direito.
• RadioGroup: componente de seleção única. Construido em cima do MUI-RadioGroup
• Switch: componente de ativação/desativação. Construido em cima do MUI-Switch
• TimePicker: componente de seleção hora. Construido em cima do MUI-TimePicker
• UploadWithCrop: componente para upload/crop de imagem
• UploadAvatarWithCrop: componente para upload/crop de avatar
• Webhook: componente criação e edição de um webhook, necessário estar envolvido de um form
• MultipleChip: componente de texto que permite adicionar multiplas opçoes em formato de chip

Utils

• file: utils para lidar com arquivos (downloadFile)
• formatNumber: utils para formatar números (fNumber, fCurrency, fPercent, fShortenNumber, fData result, fWithDecimalPlacesOrNot)
• formatTime: utils para lidar com datas (fDate, fDateTime format, fTimestamp, fToNow) (Construido utilizando date-fns)
• cssStyles: utils para lidar com estilos CSS (bgBlur, bgGradient, textGradient, filterStyles, hideScrollbarY, hideScrollbarX)
• routes: utils para lidar com rotas (getRoot)
• sort: utils para lidar com ordenação de arrys de objetos (sort, updatePosition)
• validators: utils para validação de dados (cpfIsValid, cnpjIsValid)
• number: utils para lidar com números (isMultiple, roundIfNecessary)
• uuidv4: utils para gerar um UUID v4
• loadable: util para utilizar com code split. Ele irá carregar o compomente e exibirá um loading fixo no topo da tela
• mask: utils para aplicação de máscaras em strings (applyMask, cpfMask, cnpjMask, cepMask, phoneMask)

Hooks

• useActiveElement: hook que indicar qual compnente (input, button, etc.) está com foco ativo
• useCopyToClipboard: hook para copiar algum texto para a área de transferência. Equivalente a ctrl+c
• useDatagrid: hook com recursos utéis para serem usados por um <Datagrid />
• useDeepCompareEffect: hook semelhante ao useEffect do React, mas que lida melhor com objetos complexos
• useEventListener: hook para lidar com eventos JavaScript
• useIsMounting: hook que retorna um booleano indicando se é a primeira renderezição do componente
• useResponsive: hook que retorna qual a media-query está ativa (xs, sm, md, lg, xl)
• useTabs: hook com recursos utéis para lidar com tabs (currentTab, onChangeTab, setCurrentTab)
• useToggle: hook que alterna o estado que uma variável boolean. Ex:

const [detailsOpen, toggleDetailsOpen] = useToggle(true);

• usePagination: hook para paginar dados de um array (currentPage, totalPages, currentItems, goToPage, nextPage, prevPage,): Ex:

const { currentItems, totalPages, goToPage } = usePagination({
    items,
    itemsPerPage: 5,
  });

Types

• PagedRequest interface para tipar requisições paginadas. Ex: PagedRequest<{userId: string}> (agora o userId também vai estar disponivel no objeto)

export type PagedRequest<T = unknown> = T & {
  search?: string;
  page?: number;
  perPage?: number;
  sort?: string;
  dir?: 'asc' | 'desc';
};

• PagedResponse interface para tipar respostas paginadas. Ex: PagedResponse<User[]> (agora sabemos que no 'items' temos um array de usuários)

export interface PagedResponse<T> {
  currentPage: number;
  perPage: number;
  total: number;
  items: T;
}

• ListResponse interface para tipar listas com uma prop contendo o total de itens da lista. Ex: ListResponse<User[]> (agora sabemos que no 'items' temos um array de usuários)

export interface ListResponse<T> {
  total: number;
  items: T;
}

Como fazer implementações/correções nesse pacote?

Para realizar implementações ou correções neste pacote, siga os passos abaixo:

• Clone o repositório: Faça um clone do repositório do projeto na sua máquina local.
• Crie uma branch: Crie uma nova branch para suas alterações. Isso mantém o trabalho organizado e facilita a revisão do código.
• Realize as implementações/correções: Faça as modificações necessárias no código. Certifique-se de seguir as práticas de codificação estabelecidas no projeto.
• Teste localmente: Para testar suas alterações, execute os seguintes comandos no diretório do projeto: yarn build para construir o pacote. npm link para criar um link simbólico do pacote na sua máquina.
• Teste em um projeto separado: Em outro projeto local, use o comando npm link @zydon/common-csr para conectar o pacote localmente e verificar se as alterações funcionam conforme o esperado.

Dica: Você pode utilizar o componente App.tsx para testar suas implementações/correções de forma prática

• Suba suas alterações: Após testar e validar as mudanças, faça o push da sua branch para o repositório remoto.
• Solicite um merge: Abra um pull request para a branch main. Após a revisão e aprovação, as mudanças serão mescladas.
• Publicação automática: As alterações aprovadas serão publicadas automaticamente no npm após alguns minutos.