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' });

• StepNavigator: navegação de formulário em etapas. O StepNavigatorProvider recebe as definições de etapa e passa a responder pela etapa atual, pelo status de cada uma e pela conclusão (isComplete); o StepNavigatorLayout exibe a barra lateral a partir do md e, abaixo disso, um card com a etapa atual que abre a lista completa
• 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
• Analytics/OrderProjection: calendário da Projeção de pedidos, compartilhado entre o admin e o portal. Ver a seção abaixo
• ColumnResizeHandle: divisa arrastável para redimensionar coluna de tabela, usada junto do useResizableColumns
• Accordion: accordion sem sombra e sem gutters, com ícone de expandir à esquerda

Analytics/OrderProjection

O calendário da Projeção de pedidos inteiro: cabeçalho, linhas, células, toolbar, filtros, tooltips e drawers de detalhe. O pacote não faz chamada de serviço — quem consome injeta o transporte e as próprias regras, o que permite admin e portal compartilharem a tela mantendo comportamentos diferentes.

<OrderProjectionProvider adapters={adapters} slots={slots}>
  <Calendar
    partners={partners}
    summary={summary}
    isFetching={isFetching}
    isFetchingSummary={isFetchingSummary}
    onRowsScrollEnd={handleRowsScrollEnd}
    isFetchingNextPage={isFetchingNextPage}
  />
</OrderProjectionProvider>

adapters — os hooks de dados do consumidor, um por consulta que a tela precisa:

| Adapter | Alimenta | |---|---| | usePartnerOptions | filtro de clientes | | useProfileOptions | filtro de segmentos | | useEventDetails | drawer de detalhe do evento | | usePartnerDetails | dados do cliente no drawer | | usePartnerOrders | últimas vendas | | usePartnerSaleSummary | resumo de vendas |

Cada app implementa com o próprio serviço. É assim que o portal escopa os clientes pelo vendedor logado sem que o pacote saiba disso.

slots — o que varia de um produto para o outro:

| Slot | Para que serve | |---|---| | getEventCode | qual identificador do pedido é exibido | | formatAddress | como o endereço é montado | | renderEventStatus | bloco de status do pedido no detalhe | | renderEventActions | botões de ação do detalhe do evento | | renderSaleLink | link para o pedido a partir do id | | renderPartnerLink | link para a ficha do cliente | | renderPhoneEditor | edição de telefone do cliente |

Só getEventCode e formatAddress são obrigatórios. O slot que não for passado não é renderizado, e é isso que mantém uma capacidade existindo em um consumidor e não no outro.

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 (today, fDate, fDateTime, fTime, fTimestamp, fToNow, fTimeAgo, fExpiration, fIsBetween, fIsAfter, fIsSame, fDateRangeShortLabel, fAdd, fSub, getDifferenceInDays, formatStr) (Construido utilizando dayjs)
• 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, cpfCnpjIsValid, sanitizeDocument) e validadores prontos para rules do react-hook-form (validateCpf, validateCnpj, validateCpfCnpj, validateOptionalCpf, validateOptionalCnpj, validateOptionalCpfCnpj). O CNPJ segue o padrão alfanumérico da Receita Federal: os 12 primeiros caracteres aceitam letras e números, e os 2 dígitos verificadores continuam numéricos
• 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, cpfMaskOrCnpjMask) e máscaras prontas para o MaskedInput (CPF_INPUT_MASK, CNPJ_INPUT_MASK, CPF_CNPJ_INPUT_MASK)

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
• useOrderProjectionFilters: hook com o estado de filtros, período e visualização da Projeção de pedidos
• useResizableColumns: hook que controla a largura das colunas de uma tabela, com mínimo por coluna e a última coluna ocupando a folga
• 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,
  });

• useReconciliation: hook que mantém a fonte da verdade em dia como rede de segurança do push (entrega at-most-once). Recebe um reconcile (ex.: o trigger de um lazy query do RTK), um isActive e um intervalMs (padrão 10s): dispara reconcile no intervalo enquanto ativo, e o consumidor chama notifyActivity() a cada push recebido para resetar o timer (só relê o domínio quando o push fica em silêncio).

Contexts

• PushNotificationsV2 (@zydon/common/contexts/PushNotificationsV2): provider de push de tempo real. Canais webpush (Service Worker, com permissão) ou stream (SSE, sem permissão) — não há mais polling. Um único sink faz dedup + ack DELIVERED, e a entrega é roteada por tópico via on(topic, handler); o consumidor usa usePushTopic(topic, handler), que registra o roteamento local uma vez por tópico e entrega sempre ao handler do render mais recente, sem useRef nem cleanup no consumidor — a inscrição do client no tópico (subscribeToTopic/subscribeTopicsBatch) continua sendo responsabilidade do consumidor, mas o provider lembra o que já inscreveu para o clientId atual e não repete a chamada ao adapter para tópico já inscrito (dois consumidores no mesmo tópico, ou o mesmo efeito rodando duas vezes, geram uma única request); unsubscribeFromTopic sempre chega ao adapter e libera o tópico para nova inscrição, e o conjunto zera quando o client muda. O transporte (auth/URL/reconexão) é responsabilidade do adapter injetado (apiAdapters, incluindo o subscribeToStream). Não recebe bearerToken. Um provider montado dentro de outro cede ao externo: não registra client nem abre stream, e os hooks abaixo dele leem o contexto do provider mais externo (é o que permite ao host e a um remote federado montarem cada um o seu provider com um único client por aba). A prop opcional contextKey habilita a transferência de organização (só admin): quando muda, o provider re-registra o client sob o contexto (token) atual e remove o client antigo. Os tópicos são org-scoped, então as inscrições não são carregadas da org antiga; inscrever nos tópicos da org nova é responsabilidade do consumidor. A contextKey deve ser derivada do token/sessão (ex.: organization id do token), nunca de um valor que possa estar adiantado em relação ao token, senão o re-registro cai na org errada. Consumidores de org única por sessão (ex.: portal storefront) não passam contextKey.

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.