@nebulasistemas/ui-kit

Kit de componentes de interface (UI Kit) em React e TypeScript para aplicações da Nebula: componentes reutilizáveis, formulários declarativos com SchemaForm (MobX) e estilos em SCSS.

Página npm: npmjs.com/package/@nebulasistemas/ui-kit

Nome do pacote: o scope publicado no npm é @nebulasistemas. No código antigo ou exemplos pode aparecer @nebula/ui-kit; o nome canónico para instalar é @nebulasistemas/ui-kit.

Repositório: o texto canónico deste README para o npm vive em docs/README-npm-package.md. Junto a package.json em src-components/, o ficheiro README.md é uma cópia gerada no prepublishOnly (não é a fonte; pode estar no .gitignore).

Requisitos

• Node.js >=14.21.3 (baseline alinhada aos projetos Nebula; o ficheiro .nvmrc na raiz do repositório fixa 14.21.3 para desenvolvimento do kit). Versões mais novas de Node costumam funcionar, mas validem em CI.
• npm >=6.14.0
• Na aplicação consumidora: React 16.8+, MobX 5, mobx-react 5, react-transition-group 2 (ver peerDependencies abaixo)

Instalação

npm install @nebulasistemas/ui-kit

Instale também as peer dependencies que o seu projeto ainda não tiver:

npm install react react-dom mobx mobx-react react-transition-group
npm install -D @types/react @types/react-dom @types/react-transition-group

Visão geral da API

O pacote expõe um único módulo ESM (lib/index.js) com tipos (lib/index.d.ts). Exemplo:

import {
  Button,
  Input,
  Form,
  SchemaForm,
} from '@nebulasistemas/ui-kit';

Principais famílias de componentes:

| Área | Exemplos | |------|----------| | Formulário | Form, Field, Label, Message, Input, Checkbox, PasswordInput, Autocomplete, ImageInput, FieldCalendar | | Layout | Card, Collapsible, List, ListBasic, Tabs, Tab, TabPanels, TabPanel, DraggableTabs | | Feedback | Spinner, Notification + NotificationManager + NotificationContainer, ModalHelper, Popup, Tooltip | | Avançado | SchemaForm (schema + UI schema + dados MobX) |

Documentação detalhada por componente (props e exemplos) no repositório Git do kit: docs/componentes.md.

Exemplos rápidos (API real)

Button

<Button className="primary" onClick={() => {}}>
  Guardar
</Button>

<Button.Group className="actions">
  <Button className="secondary" onClick={() => {}}>Cancelar</Button>
  <Button className="primary" onClick={() => {}}>OK</Button>
</Button.Group>

Input

<Input
  name="email"
  type="email"
  value={email}
  onChange={(name, value) => setEmail(value)}
  label="E-mail"
/>

Checkbox

O estado é value: boolean e onChange(name, value) (não há prop checked).

<Checkbox
  name="aceito"
  value={accepted}
  onChange={(name, v) => setAccepted(v)}
/>

Toggle

<Toggle value={on} onChange={(v) => setOn(v)} />

Form + Message

import { Form, Field, Label, Message, MessageType } from '@nebulasistemas/ui-kit';

<Form onSubmit={(e) => { e.preventDefault(); }}>
  <Field>
    <Form.Label id="nome" required isValid={!erro}>
      Nome
    </Form.Label>
    <Input name="nome" value={nome} onChange={(n, v) => setNome(v)} readOnly={false} disabled={false} />
    <Form.Message type={MessageType.Error}>Mensagem de erro</Form.Message>
  </Field>
</Form>

Tooltip

A prop de texto é tooltip (não content).

<Tooltip tooltip="Texto de ajuda" position="bottom center">
  <span>Hover</span>
</Tooltip>

Portal

A prop é mountNode (predefinição document.body).

<Portal mountNode={document.body}>
  <div>Conteúdo portaled</div>
</Portal>

ModalHelper

Exige um elemento #modal no HTML da aplicação.

<ModalHelper isOpen={open} onCloseModal={() => setOpen(false)} className="">
  <p>Conteúdo</p>
</ModalHelper>

Notificações

Monte NotificationContainer uma vez; use o singleton NotificationManager.

<NotificationContainer />

NotificationManager.success({
  title: 'Gravado',
  message: 'Operação concluída.',
  timeOut: 4000,
});

Tabs

Cada Tab deve ter um único filho (ex.: button). Use value + onChangeTab em Tabs e o mesmo value em TabPanels.

<Tabs value={tab} onChangeTab={setTab}>
  <Tab name="a"><button type="button">A</button></Tab>
  <Tab name="b"><button type="button">B</button></Tab>
</Tabs>
<TabPanels value={tab}>
  <TabPanel name="a"><p>A</p></TabPanel>
  <TabPanel name="b"><p>B</p></TabPanel>
</TabPanels>

SchemaForm (resumo)

Requer dados tipicamente MobX (observable), schema, uiSchema, name, namespace, onSubmit, etc. Ver docs/componentes.md e o código em schema-form/.

Desenvolvimento e build (clonando o repositório)

O package.json do pacote vive em src-components/:

cd src-components
npm install
npm run build
npm run watch

• npm run build — bundle Rollup sem minificar (desenvolvimento).
• npm run test — Jest + Testing Library (ver src/**/__tests__/**).
• npm run build:prod — bundle minificado (Terser), o que entra no pacote npm.

Antes de npm publish, o script prepublishOnly corre: test → sync-readme → build:prod. Detalhes: docs/qa-e-publish.md no repositório.

Publicação no npm

1. Login (uma vez): npm login com a conta do scope @nebulasistemas.
2. Na raiz do repositório:

./scripts/publish.sh patch    # ou minor | major
# simulação, sem enviar:
./scripts/publish.sh --dry-run

O script corre npm run build em src-components/, opcionalmente npm version, e npm publish --access public. O prepublishOnly copia o README a partir de docs/README-npm-package.md e volta a correr o build antes do publish.

Nunca coloque tokens npm em README, scripts versionados ou issues. Se um token foi exposto, revogue-o em npmjs.com → Access Tokens.

Stack técnica

| Tecnologia | Uso | |------------|-----| | React 16.8 | UI | | TypeScript 3.x | Tipagem; decorators para MobX | | MobX + mobx-react | Estado reativo (@observer na maior parte dos componentes) | | SCSS | Estilos; node-sass no build | | Rollup | Bundle ESM lib/index.js + .d.ts | | react-text-mask / addons | Máscaras no Input | | @ionic/react | DraggableTabs (reordenar abas) | | react-transition-group | Animações nas notificações |

Licença

UNLICENSED — uso interno / conforme política da Nebula.

Histórico / notas

• tslib: dependência explícita para compatibilidade com helpers gerados pelo TypeScript e resolução no Rollup.
• Sass: o build usa node-sass (conforme package.json atual). Migração para sass (Dart Sass) seria um passo futuro coordenado com o pipeline Rollup/PostCSS.

Para alterações detalhadas, consulte o repositório Git e docs/ no monorepo.