@ploomescrm/ui
v1.2.0
Published
Biblioteca de componentes React do Design System da Ploomes: componentes acessíveis, tematizáveis e prontos para produção, com tokens de design embutidos e suporte a dark mode e whitelabel em tempo de execução.
Keywords
Readme
@ploomescrm/ui
Biblioteca de componentes React do Design System da Ploomes: componentes acessíveis, tematizáveis e prontos para produção, com tokens de design embutidos e suporte a dark mode e whitelabel em tempo de execução.
Pacote proprietário da Ploomes. Publicado publicamente apenas para distribuição — o uso é destinado a aplicações da Ploomes e parceiros autorizados.
Pré-requisitos
- React
18.2+ou19(peer dependency, junto comreact-dom). - Tailwind CSS v4 com
@tailwindcss/postcss— os componentes são estilizados com utilities do Tailwind. Existe um caminho sem Tailwind (veja abaixo), mas o Tailwind é fortemente recomendado para fidelidade visual completa.
Instalação
npm install @ploomescrm/ui
# ou: pnpm add @ploomescrm/ui / yarn add @ploomescrm/uiVocê instala apenas este pacote — os tokens de design (@ploomescrm/ui/theme)
já vêm embutidos.
Se for passar ícones aos componentes, instale também o lucide-react (a lib usa
ele para renderizar ícones).
Configuração do CSS (passo essencial)
Os componentes usam classes utilitárias do Tailwind. Por padrão, o Tailwind v4
ignora node_modules, então sem um @source apontando para o bundle da lib as
classes são removidas no tree-shaking e os componentes renderizam sem estilo.
No seu CSS de entrada:
@import 'tailwindcss';
@import '@ploomescrm/ui/theme'; /* tokens → utilities (bg-brand, text-foreground, ...) */
@source '../node_modules/@ploomescrm/ui/dist'; /* preserva as classes usadas pela lib */O caminho do
@sourceé relativo ao arquivo CSS — ajuste conforme a estrutura do seu projeto.
E adicione o plugin ao seu postcss.config.js:
export default {
plugins: { '@tailwindcss/postcss': {} },
};Sem Tailwind: importe @ploomescrm/ui/tokens.css em vez do theme — ele expõe
as custom properties --color-* em :root para você estilizar sua aplicação. Os
componentes da lib, porém, ainda dependem das utilities do Tailwind para a aparência
correta.
Providers
Envolva a raiz da sua aplicação. Ambos são exportados de @ploomescrm/ui:
ToasterProvider— obrigatório se você usar toasts/notificações. O hook éuseToaster()(retorna{ toast }).WhitelabelProvider— opcional, para recolorir por cliente (veja abaixo).
import { ToasterProvider } from '@ploomescrm/ui';
import { createRoot } from 'react-dom/client';
createRoot(document.getElementById('root')!).render(
<ToasterProvider>
<App />
</ToasterProvider>,
);Uso
import { Badge, Table, useToaster, cn } from '@ploomescrm/ui';
function Example() {
const { toast } = useToaster();
return (
<div className={cn('flex items-center gap-2', 'text-foreground-muted')}>
<Badge color="brand" size="md">
Novo
</Badge>
<button
onClick={() => toast({ type: 'info', title: 'Pronto!', body: 'Olá!' })}
>
Notificar
</button>
</div>
);
}Ao montar sua própria marcação, estilize sempre com as utilities semânticas de
token (bg-brand, text-foreground-muted, border-neutral-subtle) — nunca cores
cruas (#fff, bg-red-500). É isso que mantém dark mode e whitelabel funcionando.
Dark mode
Adicione a classe dark a um elemento ancestral (ex.: <html class="dark">). As
variáveis --color-* cascateiam e todos os componentes se adaptam automaticamente —
sem configuração por componente. Alterne a classe para trocar de tema.
Whitelabel (cores por cliente)
WhitelabelProvider recolore todo o Design System em tempo de execução a partir de
duas cores hex, derivando os overrides --color-* para os modos claro e escuro e
injetando-os — sem mudanças nos componentes, e o .dark continua alternando os modos
normalmente.
import { WhitelabelProvider } from '@ploomescrm/ui';
<WhitelabelProvider brandColor="#E6334A" actionColor="#1A94FF">
{children}
</WhitelabelProvider>;brandColor→ famíliabrand(+hover/active/muted) e gradientes da marca.actionColor→ famíliainfo(papel de ação/confirmação).tintSurfaces={false}→ recolore apenas os acentos, preservando os tokens de superfície (útil quando a cor da marca prejudicaria o contraste do texto).- Omitir ambas as cores mantém o tema padrão (nada é injetado).
- Cores semânticas fixas (
warning,success,danger,overlay) não mudam. nonceé repassado ao<style>injetado, para apps com CSP estrito.useWhitelabel()expõe a configuração ativa.
O que está incluído
Cerca de 70 componentes, organizados por área:
- Botões e ações —
ButtonAction,ButtonCheck,ButtonFavorite,ButtonSoft,CardButton,NestedButton,SpeechToTextButton,ActionDock. - Campos de formulário — sistema completo de
Field*(texto, número, data, hora, opções, anexo, imagem, cor, CPF/CNPJ, telefone, endereço, editor de texto, etc.), além deFieldSelector,DeepSelector,SearchInputeCodeInput. - Navegação e layout —
Breadcrumbs,HorizontalMenu,VerticalMenu,SubMenuHorizontal,HorizontalTabs,Stepper,Pagination. - Overlays —
ModalCenter,ModalFloating,ModalSide,AlertModal,ResizableDrawer,Dropdown,Tooltip,HeaderModal,FooterModal. - Exibição de dados —
Table,DataView,GridView,ImageGallery,Card,Badge,NotifyBadge,ProgressBar,ProfileImage,ProfileGroup,Collapse,EmptyLabel,AlertMessage. - Listas —
DraggableList,SearchableList,InfiniteScroll,FilterGroup. - Feedback —
Toaster/ToasterProvider,Loader,Spinner. - Outros —
Icon,RenameableText.
Hooks e utilitários públicos:
useIsTruncated— detecta se um elemento está com texto truncado.cn(...)— composição de classes (twMerge(clsx(...))).- Helpers de whitelabel:
deriveWhitelabelTheme,whitelabelThemeToCss,changeColorLuminous,blendColors,isValidHex.
Cada componente exporta seus próprios tipos de props. Importe-os normalmente:
import { Badge, type BadgeProps } from '@ploomescrm/ui';TypeScript
O pacote distribui tipos .d.ts para ESM e CJS. Garanta que seu tsconfig.json use
moduleResolution em bundler (ou node16+) para a resolução de tipos funcionar.
Formatos e exports
| Export | Conteúdo |
| --------------------------- | ---------------------------------------------------- |
| @ploomescrm/ui | Componentes, hooks e utilitários (ESM + CJS + tipos) |
| @ploomescrm/ui/theme | Tema Tailwind v4 (tokens → utilities) |
| @ploomescrm/ui/tokens.css | Custom properties --color-* (uso sem Tailwind) |
Solução de problemas
| Sintoma | Causa / correção |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Componentes renderizam sem estilo | Falta o @source '.../@ploomescrm/ui/dist' — o Tailwind removeu as classes. Ajuste o caminho relativo. |
| Utilities como bg-brand não existem | Falta o @import '@ploomescrm/ui/theme'. |
| Dark mode não faz nada | Falta a classe dark em um ancestral. |
| useToaster must be used within <ToasterProvider> | Falta o ToasterProvider na raiz. |
| Cores de whitelabel ignoradas | brandColor/actionColor omitidos, ou o provider não envolve a subárvore. |
| Tipos não encontrados | Ajuste moduleResolution para bundler/node16+. |
© Ploomes. Todos os direitos reservados.