@processhub-lib/react

Biblioteca de componentes e utilitários React para o ecossistema ProcessHub. Construída com Tailwind CSS e Phosphor Icons.

Instalação

npm install @processhub-lib/react

Peer dependencies obrigatórias

npm install react react-dom @phosphor-icons/react uuid

CSS

Importe o stylesheet da lib no entry point da sua aplicação:

import "@processhub-lib/react/style.css";

A lib usa variáveis CSS do Tailwind (--color-primary, --color-card, --color-border, etc.). Garanta que seu tema Tailwind define essas variáveis para que os estilos funcionem corretamente.

Componentes

Button

import { Button } from "@processhub-lib/react";

<Button
  title="Salvar"
  color="green"
  variant="solid"
  onClick={() => {}}
/>

| Prop | Tipo | Padrão | Descrição | | -------------- | ----------------------------------------------------------------------------------------- | ---------- | ------------------------------------ | | title | string | — | Texto do botão | | color | "green" "blue" "red" "yellow" "primary" "secondary" "destructive" "card" | — | Cor do botão | | variant | "solid" "outline" "ghost" | "solid" | Estilo visual | | icon | JSX.Element | — | Ícone opcional | | positionIcon | "left" "right" | — | Posição do ícone | | type | "button" "submit" "reset" | "button" | Tipo HTML do botão | | disable | boolean | false | Desabilita o botão | | className | string | — | Classes extras | | onClick | (e?) => void | — | Callback de clique |

Exemplo com ícone:

import { PlusIcon } from "@phosphor-icons/react";

<Button
  title="Novo"
  color="primary"
  variant="outline"
  icon={<PlusIcon size={16} />}
  positionIcon="left"
/>

Input

import { Input } from "@processhub-lib/react";

<Input
  field="nome"
  title="Nome"
  id="nome"
  placeholder="Digite seu nome"
  value={value}
  onChange={(e) => setValue(e.target.value)}
/>

| Prop | Tipo | Padrão | Descrição | | -------------- | ------------------------- | ------- | ---------------------------------------- | | field | keyof T | — | Chave do campo no objeto de dados | | title | string | — | Label exibida acima do input | | error | string | — | Mensagem de erro (ativa estilo vermelho) | | icon | React.JSX.Element | — | Ícone dentro do input | | iconPosition | "left" "right" | — | Posição do ícone | | mask | string | — | Máscara de formatação |

Aceita todos os atributos nativos de <input> (type, placeholder, disabled, required, onChange, etc.).

Select

Dropdown acessível com suporte a busca, limpeza e navegação por teclado.

import { Select } from "@processhub-lib/react";

type Fruta = { id: number; nome: string };

const frutas: Fruta[] = [
  { id: 1, nome: "Maçã" },
  { id: 2, nome: "Banana" },
];

<Select<Fruta>
  field="nome"
  title="Fruta"
  value={selecionada?.nome}
  options={frutas}
  onChange={(item) => setSelecionada(item)}
  searchable
  isClearable
  size="md"
/>

| Prop | Tipo | Padrão | Descrição | | ---------------- | -------------------------------- | ---------------- | ----------------------------------------- | | field | string | — | Chave do objeto usada como label | | options | T[] | — | Lista de opções | | value | string | — | Valor exibido no trigger (label) | | onChange | (value: T) => void | — | Callback ao selecionar | | title | string | — | Label acima do select | | placeholder | string | "Selecione..." | Texto quando vazio | | size | "sm" "md" "lg" | "md" | Tamanho do componente | | searchable | boolean | false | Habilita campo de busca no dropdown | | isClearable | boolean | false | Exibe botão para limpar seleção | | disabled | boolean | false | Desabilita o componente | | optionPosition | "left" "right" | "left" | Alinhamento do dropdown | | icon | React.ReactNode | — | Ícone no trigger | | iconPosition | "left" "right" | "right" | Posição do ícone no trigger | | error | string | — | Mensagem de erro | | required | boolean | — | Marca o campo como obrigatório | | renderOption | (option: T) => React.ReactNode | — | Renderizador customizado por opção |

Navegação por teclado: ↑ ↓ para navegar, Enter/Espaço para selecionar, Escape/Tab para fechar.

Dropdown

Menu dropdown com trigger customizável, busca e descrição por item.

import { Dropdown } from "@processhub-lib/react";

type Tema = "light" | "dark" | "system";

const opcoes = [
  { value: "light"  as Tema, label: "Claro" },
  { value: "dark"   as Tema, label: "Escuro" },
  { value: "system" as Tema, label: "Sistema" },
];

<Dropdown<Tema>
  options={opcoes}
  value={tema}
  onChange={(v) => setTema(v)}
/>

| Prop | Tipo | Padrão | Descrição | | ------------------- | --------------------------------- | ------------- | ------------------------------------ | | options | DropdownOption<T>[] | — | Lista de opções | | value | T | — | Valor atualmente selecionado | | onChange | (value: T) => void | — | Callback ao selecionar | | label | string | — | Aria-label do trigger padrão | | align | "left" "right" | "right" | Alinhamento do menu | | searchable | boolean | false | Habilita busca no menu | | searchPlaceholder | string | "Buscar..." | Placeholder do campo de busca | | iconPosition | "left" "right" | "left" | Posição do ícone nas opções | | renderTrigger | (selected, isOpen) => ReactNode | — | Trigger totalmente customizado | | className | string | — | Classe no container | | triggerClassName | string | — | Classe no trigger padrão | | menuClassName | string | — | Classe no menu |

Tipo DropdownOption<T>:

interface DropdownOption<T> {
  value: T;
  label: string;
  icon?: ReactNode;
  description?: string;
}

Trigger customizado:

<Dropdown
  options={opcoes}
  value={valor}
  onChange={setValor}
  renderTrigger={(selected, isOpen) => (
    <Avatar name={selected.label} isOpen={isOpen} />
  )}
/>

Utilitários

import { classnames, applyMask, isDocumento } from "@processhub-lib/react";
// ou via subpath:
import { classnames } from "@processhub-lib/react/utils";

classnames

Constrói strings de classes CSS dinamicamente — equivalente ao clsx.

classnames("btn", { active: true, disabled: false }, ["px-2", null]);
// "btn active px-2"

applyMask

Aplica máscara de formatação a uma string de dígitos.

applyMask("12345678901", "cpf");
// "123.456.789-01"

applyMask("12345678000195", "cnpj");
// "12.345.678/0001-95"

applyMask("11999998888", "outro", "(xx) xxxxx-xxxx");
// "(11) 99999-8888"

| Parâmetro | Tipo | Descrição | | --------- | --------------------------- | ----------------------------------------------- | | value | string | String com dígitos | | tipo | "cpf" "cnpj" "outro" | Tipo de máscara pré-definida | | mask | string | Máscara customizada usando x para cada dígito |

isDocumento

Valida CPF (11 dígitos) ou CNPJ (14 dígitos) com ou sem formatação.

isDocumento("123.456.789-09"); // true | false
isDocumento("12345678000195"); // true | false

Release

npm version patch   # 1.0.0 → 1.0.1  (bug fix)
npm version minor   # 1.0.0 → 1.1.0  (nova feature)
npm version major   # 1.0.0 → 2.0.0  (breaking change)

O pipeline executa automaticamente: type check → build → bump de versão → git tag → publish no npm → git push --follow-tags.

Desenvolvimento

npm install
npm run build       # gera /dist
npm run typecheck   # verifica tipos sem build