Bitys React Components

Componentes React reutilizáveis dos projetos Bitys, feitos para Bootstrap 5, reactstrap e styled-components.

Instalação

npm install bitys-react-components

Peer dependencies (precisam existir no projeto que consome):

| Pacote | Versão | |---|---| | react, react-dom | 17 ou 18 | | bootstrap | 5 | | reactstrap | 9 | | react-icons | 5 | | styled-components | 5 ou 6 | | xlsx-js-style | 1.2 (exportação Excel do DataGridView) |

import { CardFilter, InputCheck, DataGridView } from 'bitys-react-components'

DataGridView

Tabela com ordenação, paginação, pesquisa, seleção por checkbox, estados vazios e exportação para Excel e PDF. Os textos já vêm em português.

Uso mínimo

const columns = [
  { key: 'id', text: 'Id', sortable: true, width: 60 },
  { key: 'nome', text: 'Nome', sortable: true },
  { key: 'vlTotal', text: 'Total', align: 'right', cell: (d) => d.vlTotal.toFixed(2) },
]

<DataGridView config={{ key_column: 'id' }} records={dados} columns={columns} />

Props

| Prop | Tipo | Padrão | Descrição | |---|---|---|---| | records | array \| undefined | | Registros a exibir. undefined ou null significa "ainda não buscou" e mostra init_text. Array vazio mostra no_data_text. | | columns | array | [] | Definição das colunas, ver abaixo. | | config | object | {} | Configuração, ver abaixo. É relida a cada render, então pode ser montada inline e mudar com o estado da tela. | | loading | bool | | Mostra o estado "carregando" no lugar das linhas. | | checkSelectedIds | array | [] | Ids selecionados quando existe coluna de checkbox. A tela é dona da lista. | | onCheckChange | (ids) => void | | Recebe a lista completa de ids já calculada pelo grid. Normalmente é o próprio setter do estado. | | onRowClicked | (event, record, index) => void | | Clique na linha. | | onSort | (column, records, order) => array | | Substitui a ordenação padrão. | | onChange | ({ filter_value, page_number, page_size, sort_order }) => void | | Disparado ao pesquisar, paginar ou ordenar. | | extraButtons | array | | Botões extras na barra de ferramentas, exige config.button.extra = true. Cada item: { className, title, onClick, children }. | | id | string | as-react-datatable | Id do elemento table. | | className | string | table table-bordered table-striped | Classes da table. | | tHeadClassName | string | | Classes do thead. |

Modo servidor (paginação feita pela API): dynamic={true}, total_record={n} e onPageChange. Nesse modo o grid não filtra nem pagina localmente. Nenhuma tela dos projetos usa hoje.

Colunas

| Campo | Descrição | |---|---| | key | Nome do campo no registro. Usado para ordenar, pesquisar e exportar. | | text | Título da coluna. | | sortable | Habilita ordenação ao clicar no cabeçalho. | | cell | (record, index) => ReactNode. Renderização customizada. Na exportação, o resultado vira texto. | | width | Largura do th. | | align | left, center ou right. | | className | Classes do td. | | TrOnlyClassName | Classes só do th. | | type: 'checkBox' ou key: 'checkBox' | Coluna de seleção, ver abaixo. |

Config

| Chave | Padrão | Descrição | |---|---|---| | key_column | 'id' | Campo que identifica o registro. Usado na seleção e na key das linhas. | | page_size | 10 | Registros por página. | | length_menu | [10, 25, 50, 75, 100] | Opções de registros por página. | | show_filter | true | Exibe a barra superior (pesquisa, quantidade por página e botões). | | show_length_menu | true | Exibe o seletor de quantidade por página. | | show_pagination | true | Exibe a paginação. | | show_info | true | Exibe "Exibindo X até Y de Z registros". | | show_first, show_last | true | Exibe os botões de primeira e última página. | | pagination | 'basic' | 'basic' ou 'advance'. | | button.excel | false | Botão de exportação para Excel. | | button.print | false | Botão de impressão / PDF. | | button.extra | false | Renderiza extraButtons. | | filename | 'table' | Nome do arquivo exportado, sem extensão. | | sort | | Ordenação inicial: { column: 'nome', order: 'asc' }. | | language | | Textos, ver abaixo. |

Textos em config.language. Só informe o que quiser trocar:

| Chave | Padrão | |---|---| | init_text | Informe os filtros e clique em Buscar para exibir o resultado | | no_data_text | Nenhum registro encontrado | | no_match_text | Nenhum registro corresponde à pesquisa | | loading_text | Aguarde, carregando... | | filter | Pesquisar... | | length_menu | Exibir MENU registros | | info | Exibindo START até END de TOTAL registros | | pagination | { first: '<<', previous: '<', next: '>', last: '>>' } |

Estados

O grid resolve sozinho o que mostrar. A tela não precisa testar length antes de renderizar.

| Situação | O que aparece | |---|---| | records undefined ou null | Bloco centralizado com init_text, sem cabeçalho nem rodapé. | | records vazio | Bloco centralizado com no_data_text, sem cabeçalho nem rodapé. | | Pesquisa sem correspondência | Cabeçalho mantido, para o usuário limpar a pesquisa, e no_match_text no corpo. | | loading | Spinner com loading_text no corpo. |

Mensagem por tela:

<DataGridView config={{ key_column: 'pedidoId', language: { no_data_text: 'Nenhum pedido aguardando conferência' } }} records={pendentes} columns={columns} />

Como o config é relido a cada render, a mensagem pode depender do estado:

config={{ ...conf, language: { no_data_text: gerar ? 'Serão gerados ao liberar' : 'Liberação sem geração' } }}

Seleção por checkbox

Inclua uma coluna { key: 'checkBox', text: '' } e controle a lista de ids na tela:

const [sel, setSel] = useState([])

<DataGridView config={{ key_column: 'enderecoId' }} records={dados} columns={columns} checkSelectedIds={sel} onCheckChange={setSel} />

Regras aplicadas pelo grid:

| Ação | Resultado em onCheckChange | |---|---| | Marcar o checkbox do cabeçalho | Substitui a lista pelos ids que passam pela pesquisa, em todas as páginas. | | Desmarcar o cabeçalho | Lista vazia. | | Clicar em uma linha | Adiciona ou remove só aquele id, preserva o restante. | | Shift + clique | Adiciona ou remove o intervalo desde o último clique, calculado sobre a lista pesquisada, preserva o restante. |

O checkbox do cabeçalho aparece marcado quando todos os registros pesquisados estão na lista.

Paginação

Volta para a página 1 ao receber uma lista nova em records, ao pesquisar e ao trocar a quantidade por página. Por isso, não recrie o array de records a cada render. Se precisar transformar os dados, use useMemo:

const linhas = useMemo(() => itens.map((d, i) => ({ ...d, nrItem: i + 1 })), [itens])

Exportação

button.excel gera um .xlsx com xlsx-js-style: cabeçalho em negrito, largura de coluna automática, todos os registros pesquisados e ordenados, sem a coluna de checkbox. Colunas com cell exportam o texto renderizado. button.print abre a tabela em uma janela para impressão ou PDF.

CardFilter

Card "Filtros" recolhível com botão Buscar. Os campos de filtro vão como children.

<CardFilter onChange={buscar}>
  <Row>...campos...</Row>
</CardFilter>

| Prop | Descrição | |---|---| | children | Conteúdo do card quando expandido. | | onChange | Chamado ao clicar em Buscar. O card recolhe em seguida. |

InputCheck

Checkbox estilizado, compatível com handlers onChange que leem ev.target.name e ev.target.value.

<InputCheck name="ativo" label="Ativo" value={values.ativo} onChange={(ev) => setValues({ ...values, [ev.target.name]: ev.target.value })} />

| Prop | Descrição | |---|---| | value | Booleano controlado. | | label | Texto ao lado do checkbox. | | onChange | Recebe { target: { name, value: boolean, ...props }, event }. | | disabled | Desabilita e muda a cor quando marcado. | | styleContainer, styleLabel | Estilos inline do container e do label. |

Demais props vão para o input.

Desenvolvimento

npm run build     # babel src -> dist

O dist é versionado e é o que vai no pacote (files: ["dist", "README.md"]). O babel não limpa o destino, então apague dist antes do build quando remover ou renomear arquivos em src, senão sobra arquivo morto dentro do pacote.

Nos projetos que consomem, o DataGridView costuma existir também como cópia local em src/Components/DataGridView. O barrel src/Components/index.js decide qual entra em uso. Mantenha as duas cópias iguais e aponte o barrel para o pacote após publicar.

Publicação

O pacote é público no registro padrão (registry.npmjs.org), publicado pela conta bitys ([email protected]). Só quem é maintainer dessa conta publica.

Passo a passo:

npm whoami                 # precisa responder "bitys"; se der 401, faça login
npm login                  # abre o navegador para autenticar a conta bitys
npm run build              # regera o dist a partir do src
npm version patch          # 0.1.14 -> 0.1.15 (use minor/major conforme o caso)
npm publish

Depois de publicar, no projeto que consome:

npm install bitys-react-components@latest

Confira o conteúdo do pacote antes de publicar com npm publish --dry-run. Ele lista os arquivos do tarball sem enviar nada.

Erros comuns

| Sintoma | Causa | Solução | |---|---|---| | 404 Not Found - PUT .../bitys-react-components | Não autenticado. O npm responde 404 em vez de 401 no publish para não revelar se o pacote existe. | npm whoami. Se der 401, o token expirou: rode npm login. | | 403 Forbidden | Autenticado com uma conta que não é maintainer. | Entrar com a conta bitys ou pedir para ser adicionado como maintainer. | | 403 cannot publish over previously published version | A versão do package.json já existe no registro. | npm version patch antes de publicar. | | Arquivo antigo aparece no tarball | dist com sobra de build anterior. | Apagar dist e rodar npm run build. |

Changelog

0.1.14

Quebras:

• onCheckRowChange(id, checked) foi substituído por onCheckChange(ids). O grid calcula a lista final, a tela só guarda.
• records undefined deixou de ser tratado como lista vazia. Passe [] quando quiser a mensagem "Nenhum registro encontrado" sem buscar.
• Exportação CSV removida. Use button.excel.
• config.button.csv é ignorado.

Novidades:

• Seleção respeita a pesquisa: marcar todos seleciona só o que está visível pela pesquisa, em todas as páginas. Shift funciona sobre a lista pesquisada e entre páginas.
• Estados vazio, inicial, sem correspondência e carregando renderizados pelo próprio grid, com ícone.
• Exportação Excel gera .xlsx de verdade, com xlsx-js-style.
• Textos padrão em português. O bloco language nas telas passou a ser opcional.
• config é relido a cada render.
• Volta para a página 1 ao recarregar, pesquisar ou trocar a quantidade por página.
• Ícones dos botões de exportação com react-icons. Os anteriores dependiam de Font Awesome, que não é carregado.

Licença

MIT