@humu-tech/ui 0.1.26 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -4,177 +4,402 @@
4
4
  [![Storybook](https://img.shields.io/badge/Storybook-online-FF4785?logo=storybook&logoColor=white)](https://inovanti-bank.github.io/humu-ui/)
5
5
  [![types](https://img.shields.io/npm/types/@humu-tech/ui)](https://www.npmjs.com/package/@humu-tech/ui)
6
6
 
7
- **Design System V2 da Humu.** 51 primitives · 32 patterns · tema claro/escuro · React 18 · preset Tailwind · TypeScript.
7
+ **Design System Humu.** Primitives e patterns em React, com tema claro/escuro, preset para Tailwind CSS 3, ícones lucide e tipos TypeScript.
8
8
 
9
- Extraído dos apps de crédito (admin + portal do cliente) para ser consumido por todos os projetos da empresa.
9
+ - **[Storybook](https://inovanti-bank.github.io/humu-ui/)**: catálogo interativo. Cada componente tem a aba **Docs**, com a tabela de props gerada a partir dos tipos, e uma story para cada variação.
10
+ - **[CHANGELOG](https://github.com/Inovanti-Bank/humu-ui/blob/main/packages/react/CHANGELOG.md)**: o que mudou em cada versão.
11
+ - Vindo da 0.1.x? Veja [Migrando da 0.1.x](#migrando-da-01x).
10
12
 
11
- 📖 **[Catálogo interativo no Storybook](https://inovanti-bank.github.io/humu-ui/)** — 83 componentes, 398 stories, e a aba **Docs** de cada um com a tabela de props gerada a partir dos tipos.
13
+ ## Requisitos
12
14
 
13
- > **Nome do pacote:** publica como `@humu-tech/ui` e coexiste com o legado `@inovanti/react@3`. O rebrand do escopo para `@humu/*` fica para quando o registry `@humu` estiver provisionado.
15
+ | O quê | Versão |
16
+ | --- | --- |
17
+ | `react` e `react-dom` | 18 ou 19 (`peerDependencies`: `^18 \|\| ^19`) |
18
+ | `tailwindcss` | 3 (o preset é um `Config` do Tailwind 3; o Tailwind 4 não é suportado) |
19
+ | Bundler | um que resolva `import` de CSS vindo de `node_modules`, como Vite ou Next.js |
20
+
21
+ Radix, gráficos, ícones (`lucide-react`) e as fontes já vêm como dependências da lib.
14
22
 
15
23
  ## Instalação
16
24
 
17
25
  ```bash
18
- npm install @humu-tech/ui
26
+ npm install @humu-tech/ui --save-exact
19
27
  ```
20
28
 
21
- Pacote **público no npm** — não precisa de registry privado nem de token.
29
+ Se o app ainda não usa Tailwind:
22
30
 
23
- `react` e `react-dom` (^18) são **peerDependencies**.
31
+ ```bash
32
+ npm install -D tailwindcss@3 postcss autoprefixer
33
+ ```
24
34
 
25
- ## Setup
35
+ Use versão exata (`--save-exact`). O visual muda entre versões menores enquanto a lib está em `0.x`, então subir de versão deve ser uma decisão, conferida nas telas.
26
36
 
27
- ### 1. Tokens
37
+ ## Configuração
28
38
 
29
- Importe o CSS de tokens uma vez na raiz do app:
39
+ São quatro passos, uma vez por app.
30
40
 
31
- ```ts
32
- // Vite: src/main.tsx
33
- import '@humu-tech/ui/tokens.css'
34
- ```
41
+ ### 1. CSS global: tokens e Tailwind
42
+
43
+ Importe `@humu-tech/ui/tokens.css` no CSS global, **antes** das diretivas do Tailwind:
35
44
 
36
45
  ```css
37
- /* Next.js App Router: app/globals.css */
38
46
  @import '@humu-tech/ui/tokens.css';
47
+ @tailwind base;
48
+ @tailwind components;
49
+ @tailwind utilities;
50
+
51
+ body {
52
+ background-color: var(--humu-background-base);
53
+ color: var(--humu-content-title);
54
+ font-family: var(--humu-font-family-ibm-plex-sans);
55
+ }
39
56
  ```
40
57
 
41
- ### 2. Tailwind
58
+ O `tokens.css` traz as variáveis `--humu-*` dos dois temas (cor, tipografia, raio, sombra, movimento) e carrega as fontes IBM Plex Sans, Inter e JetBrains Mono. Não é preciso importar fonte à parte. Ele não estiliza o `body`: a regra acima é o que faz o fundo, o texto e a fonte do app acompanharem o tema.
42
59
 
43
- O preset traz os utilitários v2 (`bg-v2-action-primary`, `text-v2-fg-default`, `rounded-v2-md`, …).
60
+ Também dá para importar pelo JavaScript, no ponto de entrada do app: `import '@humu-tech/ui/tokens.css'`.
44
61
 
45
- > ⚠️ **O `content` precisa incluir o `dist` da lib.** Os componentes trazem as classes deles no bundle; sem essa linha, o Tailwind não gera essas classes e os estilos somem em silêncio — sem erro de build.
62
+ ### 2. Tailwind: preset e `content`
46
63
 
47
64
  ```ts
48
- // tailwind.config.ts
49
- export default {
50
- presets: [require('@humu-tech/ui/tailwind-preset').default],
65
+ import type { Config } from 'tailwindcss'
66
+ import humuPreset from '@humu-tech/ui/tailwind-preset'
67
+
68
+ const config: Config = {
69
+ presets: [humuPreset],
51
70
  content: [
71
+ './index.html',
52
72
  './src/**/*.{ts,tsx}',
53
73
  './node_modules/@humu-tech/ui/dist/**/*.{js,mjs}',
54
74
  ],
55
75
  }
76
+
77
+ export default config
56
78
  ```
57
79
 
58
- <details>
59
- <summary><strong>Se o app já usa <code>@inovanti/react/tailwind.config</code> como preset</strong></summary>
80
+ Em `tailwind.config.js` CommonJS: `presets: [require('@humu-tech/ui/tailwind-preset').default]`.
60
81
 
61
- Não empilhe dois presets — o do `@inovanti/react` perde as próprias cores quando combinado com qualquer outro. Puxe os tokens por `theme.extend`:
82
+ > **A linha do `node_modules/@humu-tech/ui/dist` no `content` não é opcional.** Os componentes trazem as classes Tailwind no bundle. Sem ela, o Tailwind do app não gera essas classes e os estilos somem, sem erro de build.
62
83
 
63
- ```ts
64
- export default {
65
- presets: [require('@inovanti/react/tailwind.config')],
66
- content: [
67
- './src/**/*.{ts,tsx}',
68
- './node_modules/@humu-tech/ui/dist/**/*.{js,mjs}',
69
- ],
70
- theme: {
71
- extend: {
72
- ...require('@humu-tech/ui/tailwind-preset').default.theme.extend,
73
- },
74
- },
84
+ O preset liga `darkMode: ['class']` e acrescenta as classes `humu-*` (veja [Classes dos tokens](#classes-dos-tokens)).
85
+
86
+ ### 3. Tema: `ThemeProvider`
87
+
88
+ Envolva o app no `ThemeProvider`. Ele aplica o tema no `<html>`, guarda a escolha da pessoa e acompanha o tema do sistema.
89
+
90
+ ```tsx
91
+ import { ThemeProvider, Toaster } from '@humu-tech/ui'
92
+
93
+ export function Root({ children }: { children: React.ReactNode }) {
94
+ return (
95
+ <ThemeProvider>
96
+ {children}
97
+ <Toaster />
98
+ </ThemeProvider>
99
+ )
75
100
  }
76
101
  ```
77
102
 
78
- </details>
103
+ O `<Toaster />`, montado uma vez, é o que faz os avisos de `toast()` aparecerem.
104
+
105
+ ### 4. Tema sem piscar: script no `<head>`
106
+
107
+ O `ThemeProvider` só roda depois que o JavaScript carrega. Para a página já abrir no tema certo, coloque no `<head>` o script devolvido por `getThemeBootstrapScript()`. Ele lê a mesma preferência que o provider e aplica `data-theme`, a classe e o `color-scheme` antes do primeiro desenho.
108
+
109
+ A função devolve uma string. Como o bundle da lib importa CSS e é marcado `"use client"`, ela não roda em `vite.config.ts` nem em Server Component do Next.js: gere a string uma vez e cole no HTML.
110
+
111
+ ```html
112
+ <head>
113
+ <script data-theme-bootstrap>COLE AQUI A SAÍDA DE getThemeBootstrapScript()</script>
114
+ </head>
115
+ ```
116
+
117
+ Um teste no app garante que o HTML acompanha a lib quando ela muda o script:
118
+
119
+ ```ts
120
+ import { readFileSync } from 'node:fs'
121
+ import { getThemeBootstrapScript } from '@humu-tech/ui'
122
+ import { expect, it } from 'vitest'
123
+
124
+ it('index.html traz o script de tema da versão instalada', () => {
125
+ const html = readFileSync('index.html', 'utf8')
126
+ expect(html).toContain(getThemeBootstrapScript())
127
+ })
128
+ ```
129
+
130
+ Se o `ThemeProvider` usa `storageKey` ou `defaultPreference`, passe as mesmas opções para `getThemeBootstrapScript({ storageKey, defaultPreference })`. Em Next.js, o script entra no `<head>` do layout raiz com `dangerouslySetInnerHTML`, e o `<html>` precisa de `suppressHydrationWarning`, porque o script muda os atributos dele antes da hidratação. Com Content-Security-Policy, o script inline precisa de `nonce` ou hash.
79
131
 
80
132
  ## Uso
81
133
 
134
+ Tudo é importado da raiz do pacote.
135
+
82
136
  ```tsx
83
- import { Button, Input, DataTable, cn } from '@humu-tech/ui'
137
+ import { Button, Input, toast } from '@humu-tech/ui'
138
+ import { Save } from 'lucide-react'
84
139
 
85
- export function Example() {
140
+ export function ClienteForm() {
86
141
  return (
87
- <div className={cn('flex flex-col gap-4')}>
88
- <Input label="Nome" />
89
- <Button variant="primary">Salvar</Button>
90
- </div>
142
+ <form
143
+ className="flex flex-col gap-4"
144
+ onSubmit={(event) => {
145
+ event.preventDefault()
146
+ toast.success('Cliente salvo')
147
+ }}
148
+ >
149
+ <Input label="Nome" name="nome" />
150
+ <Button type="submit" variant="primary" leftIcon={<Save />}>
151
+ Salvar
152
+ </Button>
153
+ </form>
91
154
  )
92
155
  }
93
156
  ```
94
157
 
95
- ### Navegação desacoplada
158
+ ### Campos em grade
159
+
160
+ Os campos (`Input`, `MaskedInput` e os derivados, como `CepInput`, `MoneyInput`, `PhoneInput`, `DocumentInput`, `PasswordInput` e `PercentInput`) têm duas props de classe:
96
161
 
97
- Os componentes de navegação (`AppShell`, `Sidebar`, `Breadcrumb`, `KpiHero`) não embutem roteador: recebem `linkComponent` e `currentPath` por prop.
162
+ | Prop | Onde aplica | Use para |
163
+ | --- | --- | --- |
164
+ | `containerClassName` | Bloco externo do campo (rótulo, caixa e mensagens), que é o item da grade | `col-span-*`, `row-span-*`, largura na grade |
165
+ | `className` | Caixa do campo | Ajustes visuais da caixa |
98
166
 
99
167
  ```tsx
100
- import { AppShell, type DsLinkComponent } from '@humu-tech/ui'
101
- import { Link, useLocation } from 'react-router-dom'
168
+ <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
169
+ <CepInput label="CEP" />
170
+ <Input label="Logradouro" containerClassName="sm:col-span-2" />
171
+ <Input label="Número" />
172
+ <Input label="Complemento" />
173
+ </div>
174
+ ```
102
175
 
103
- const RouterLink: DsLinkComponent = ({ to, className, children }) => (
104
- <Link to={to} className={className}>{children}</Link>
105
- )
176
+ ### Ícones
177
+
178
+ A lib usa [`lucide-react`](https://lucide.dev/icons/). Os componentes recebem o ícone como `ReactNode` (`leftIcon`, `rightIcon` e `icon` do `Button`, por exemplo). Para usar ícones no app, instale o pacote:
179
+
180
+ ```bash
181
+ npm install lucide-react
182
+ ```
183
+
184
+ Usar a mesma versão da lib evita duas cópias no bundle; `npm ls lucide-react` mostra qual é.
106
185
 
107
- <AppShell
108
- linkComponent={RouterLink}
109
- currentPath={useLocation().pathname}
110
- sidebarGroups={groups}
111
- >
112
- {children}
113
- </AppShell>
186
+ ### Classes dos tokens
187
+
188
+ O preset gera classes Tailwind a partir dos tokens, com o prefixo `humu-`. Use essas classes no app em vez de cores fixas, para acompanhar o tema:
189
+
190
+ ```tsx
191
+ <div className="rounded-humu-md border border-humu-background-border bg-humu-background-surface p-4 shadow-humu-card">
192
+ <h2 className="text-humu-heading-xm font-bold text-humu-content-title">Título</h2>
193
+ <p className="text-humu-body-xs text-humu-content-body-text">Texto de apoio</p>
194
+ </div>
114
195
  ```
115
196
 
116
- Sem `linkComponent`, o default renderiza um `<a href>`.
197
+ | Grupo | Exemplos |
198
+ | --- | --- |
199
+ | Fundo | `bg-humu-background-base`, `bg-humu-background-surface`, `bg-humu-background-brand-brand` |
200
+ | Texto | `text-humu-content-title`, `text-humu-content-subtitle`, `text-humu-content-body-text`, `text-humu-content-brand`, `text-humu-content-brand-strong` (texto de destaque da marca: Carvão no claro, verde da marca no escuro) |
201
+ | Borda | `border-humu-background-border`, `border-humu-border-default`, `border-humu-border-brand` |
202
+ | Foco | `ring-humu-focus`, `outline-humu-focus` (indicador de foco com 3:1 sobre os fundos nos dois temas; use sólido, sem opacidade) |
203
+ | Status | `bg-humu-status-background-success-subtle`, `text-humu-status-content-error` |
204
+ | Paleta | `bg-humu-brand-500`, `text-humu-grey-700` (escalas `grey`, `brand`, `turtle`, `purple`, `green`, `yellow`, `red`, `blue`, de 50 a 950) |
205
+ | Gráfico | `fill-humu-chart-1` a `fill-humu-chart-8` |
206
+ | Tipografia | `text-humu-heading-{x,l,xm}`, `text-humu-body-{m,s,xs,xxs}` (tamanho, altura de linha e espaçamento) e `text-humu-size-{xs…6xl}` (só tamanho) |
207
+ | Fonte | `font-humu-ibm-plex-sans`, `font-humu-inter` |
208
+ | Raio | `rounded-humu-{none,sm,md,lg,xl,pill}` |
209
+ | Sombra | `shadow-humu-card`, `shadow-humu-dialog`, `shadow-humu-raised` |
210
+ | Movimento | `duration-humu-{instant,fast,normal,slow,slower}`, `ease-humu-{out,in-out,spring}` |
211
+
212
+ As cores aceitam opacidade do Tailwind (`bg-humu-brand-500/20`). O `cn` conhece esses grupos: `cn('text-humu-body-xs', 'text-humu-body-s')` fica só com o último tamanho e mantém a cor.
117
213
 
118
- ### Tema claro/escuro
214
+ ### Tema claro e escuro
119
215
 
120
- O estado do tema vive no DOM (`data-theme` na raiz), então **não existe `ThemeProvider`** — qualquer parte da árvore, inclusive CSS puro, reage sozinha.
216
+ O tema vale para a página inteira e é aplicado no `<html>`: `data-theme="light"` ou `data-theme="dark"`, a classe `light`/`dark` e o `color-scheme`. Os tokens reagem ao atributo, então CSS fora do React também troca de tema.
121
217
 
122
218
  ```tsx
123
- import { ThemeToggle, useDsV2Theme } from '@humu-tech/ui'
219
+ import { ThemeToggle, useTheme } from '@humu-tech/ui'
124
220
 
125
- function Topbar() {
126
- const theme = useDsV2Theme() // 'light' | 'dark'
221
+ export function Topbar() {
222
+ const { theme, preference, setPreference } = useTheme()
127
223
  return (
128
- <header>
129
- <span>Tema atual: {theme}</span>
224
+ <header className="flex items-center gap-2">
225
+ <span>
226
+ Tema: {theme} (preferência: {preference})
227
+ </span>
228
+ <button type="button" onClick={() => setPreference('dark')}>
229
+ Escuro
230
+ </button>
130
231
  <ThemeToggle size="md" />
131
232
  </header>
132
233
  )
133
234
  }
134
235
  ```
135
236
 
136
- - **`ThemeToggle`** — cicla `light → dark → system`, persiste em `localStorage` (`storageKey`, default `"ds-v2-theme-preference"`), escuta `prefers-color-scheme` quando a preferência é `system`, e escreve `data-theme` em `document.documentElement`.
137
- - **`useDsV2Theme()`** — hook somente-leitura que observa esse atributo (`MutationObserver`) e devolve `'light' | 'dark'`. Útil para adaptar o que não é do DS, como a cor de um gráfico de terceiros.
237
+ - **`ThemeProvider`**: guarda a preferência (`light`, `dark` ou `system`) no `localStorage`, acompanha `prefers-color-scheme` quando a preferência é `system` e sincroniza entre abas. Props: `storageKey` (padrão `"theme-preference"`, exportado como `THEME_STORAGE_KEY`) e `defaultPreference` (padrão `"system"`).
238
+ - **`useTheme()`**: devolve `preference` (`ThemePreference`), `theme` (`ResolvedTheme`, `'light' | 'dark'`, já resolvido), `setPreference` e `cyclePreference`. Fora do `ThemeProvider`, lança erro.
239
+ - **`ThemeToggle`**: botão que cicla claro, escuro e sistema, com o título do próximo passo ("Mudar para tema escuro" etc.). Prop `size`: `sm`, `md` (padrão) ou `lg`. Precisa estar dentro do `ThemeProvider`.
240
+
241
+ **Tema escuro num trecho.** `data-theme="dark"` em qualquer elemento aplica os tokens do tema escuro só àquele trecho, com o resto da página no claro:
242
+
243
+ ```tsx
244
+ <section data-theme="dark" className="bg-humu-background-base p-6 text-humu-content-title">
245
+ <Button variant="primary">Ação</Button>
246
+ </section>
247
+ ```
248
+
249
+ O contrário (trecho claro numa página escura) não existe: só o tema escuro tem seletor por elemento.
250
+
251
+ ### Navegação sem acoplar roteador
252
+
253
+ `AppShell`, `Sidebar`, `Breadcrumb` e `KpiHero` não embutem roteador: recebem `linkComponent` (tipo `DsLinkComponent`). `AppShell` e `Sidebar` recebem também `currentPath`, para marcar o item ativo.
254
+
255
+ ```tsx
256
+ import { AppShell, type DsLinkComponent, type SidebarGroup } from '@humu-tech/ui'
257
+ import { Link, useLocation } from 'react-router-dom'
258
+
259
+ const RouterLink: DsLinkComponent = ({ to, className, children }) => (
260
+ <Link to={to} className={className}>
261
+ {children}
262
+ </Link>
263
+ )
264
+
265
+ export function Layout({ groups, children }: { groups: SidebarGroup[]; children: React.ReactNode }) {
266
+ const { pathname } = useLocation()
267
+ return (
268
+ <AppShell linkComponent={RouterLink} currentPath={pathname} sidebarGroups={groups}>
269
+ {children}
270
+ </AppShell>
271
+ )
272
+ }
273
+ ```
274
+
275
+ Sem `linkComponent`, o padrão é o `DefaultLink`, que renderiza um `<a href>`.
138
276
 
139
277
  ## O que o pacote entrega
140
278
 
141
279
  | Entrada | O quê |
142
280
  | --- | --- |
143
- | `@humu-tech/ui` | 51 primitives + 32 patterns + `cn` + hooks |
144
- | `@humu-tech/ui/tokens.css` | CSS custom properties em oklch, com variantes claro/escuro |
145
- | `@humu-tech/ui/tailwind-preset` | `theme.extend` com os utilitários v2 |
281
+ | `@humu-tech/ui` | Componentes, tema, `cn` e utilitários (ESM e CommonJS, com tipos para os dois) |
282
+ | `@humu-tech/ui/tokens.css` | Variáveis CSS dos dois temas e as fontes |
283
+ | `@humu-tech/ui/tailwind-preset` | Preset do Tailwind 3 com as classes `humu-*` (ESM e CommonJS) |
146
284
 
147
- Mais: **`cn`** (`tailwind-merge` estendido com os grupos de classe v2), bundles com `"use client"` (compatível com App Router/RSC, inerte em Vite) e tipos TypeScript inclusos.
285
+ Os bundles trazem `"use client"` (compatível com o App Router do Next.js, sem efeito no Vite). O pacote declara `sideEffects` só para `*.css`, o que deixa o bundler descartar o JavaScript dos componentes que o app não usa.
148
286
 
149
287
  ## Catálogo
150
288
 
151
- Tudo é exportado da raiz: `import { X } from '@humu-tech/ui'`.
289
+ Tudo é exportado da raiz: `import { X } from '@humu-tech/ui'`. Exemplos e props de cada um no [Storybook](https://inovanti-bank.github.io/humu-ui/).
152
290
 
153
- ### Primitives (51)
291
+ ### Primitives
154
292
 
155
293
  | Grupo | Componentes |
156
294
  | --- | --- |
157
- | **Formulário** | `Button` `Checkbox` `CepInput` `ColorPicker` `Combobox` `DateInput` `DateRangeInput` `DocumentInput` `FileUpload` `ImageUpload` `Input` `Label` `MaskedInput` `MoneyInput` `MultiCombobox` `OtpInput` `PasswordInput` `PercentInput` `PhoneInput` `RadioGroup` `Switch` `TextArea` |
158
- | **Overlays / menus** | `ConfirmDialog` `ContextMenu` `Dialog` `Drawer` `Dropdown` `Popover` `Tooltip` |
159
- | **Exibição de dados** | `Avatar` `Badge` `Box` `Card` `CopyButton` `FilePreview` `FileThumbnail` `Heading` `Skeleton` `Sparkline` `SparklineBadge` `Text` |
160
- | **Navegação / layout** | `Breadcrumb` `Separator` `Stepper` `Tabs` |
161
- | **Feedback** | `FormAlert` `FullScreenLoading` `HelpHint` `Spinner` `Toast` |
162
- | **Tema** | `ThemeToggle` |
295
+ | **Formulário** | `Button` `Checkbox` `CepInput` `ColorPicker` `Combobox` `DateInput` `DateRangeInput` `DocumentInput` `DocumentUploadCard` `FileUpload` `FileViewCard` `ImageUpload` `Input` `Label` `MaskedInput` `MoneyInput` `MultiCombobox` `OtpInput` `PasswordInput` `PercentInput` `PhoneInput` `RadioGroup` `SelectableCard` `Switch` `TextArea` `TitleSelect` `ToggleChip` |
296
+ | **Overlays e menus** | `ConfirmDialog` `ContextMenu` `Dialog` `Drawer` `Dropdown` `FilePreviewDialog` `Popover` `Tooltip` |
297
+ | **Exibição de dados** | `Avatar` `Badge` `Box` `Card` `ContentCard` `CopyButton` `FieldsCard` `FileInfoCard` `FilePreviewContent` `FileThumbnail` `Heading` `Logo` `Skeleton` `Sparkline` `SparklineBadge` `Text` |
298
+ | **Navegação e layout** | `Breadcrumb` `Separator` `Stepper` `Tabs` |
299
+ | **Feedback** | `Checklist` `FormAlert` `FullScreenLoading` `HelpHint` `InfoBox` `Progress` `ProgressTitle` `Spinner` `Toaster` (com `toast`, `useToast` e `dismissToast`) |
300
+ | **Tema** | `ThemeProvider` `ThemeToggle` `useTheme` `getThemeBootstrapScript` `THEME_STORAGE_KEY` |
163
301
 
164
- ### Patterns (32)
302
+ ### Patterns
165
303
 
166
304
  | Grupo | Componentes |
167
305
  | --- | --- |
168
- | **Formulário** | `FormSection` `FormWithAside` `WizardShell` |
169
- | **Exibição de dados** | `DataField` `DataTable` `DataTablePagination` `EmptyState` `LegalDocumentRenderer` `PanelCard` `ReadOnlyDataView` `SectionCard` `SortableColumnHeader` `TutorialCard` |
170
- | **Navegação / layout** | `AppShell` `ErrorPageLayout` `NavigatorTile` `PublicPageLayout` `Sidebar` `Topbar` |
171
- | **Gráficos** | `ChartTimeSeries` `DonutChart` `HorizontalBarChart` `KpiCard` `KpiHero` `LineChart` `StackedBarChart` |
172
- | **Diversos** | `CommandPalette` `DashboardBlock` `DSAccordion` `FilterBarV2` `NotificationCenter` `WorkflowDesigner` |
306
+ | **Formulário** | `FilterBar` `FilterToolbar` `FormSection` `FormWithAside` `WizardShell` |
307
+ | **Exibição de dados** | `DataField` `DataTable` (com `DataTableTextCell`, `DataTableLinkCell`, `DataTableDocumentCell` e `DataTableActionButton`) `DataTablePagination` `EmptyState` `LegalDocumentRenderer` `PanelCard` `ReadOnlyDataView` `SectionCard` `SortableColumnHeader` `Timeline` (com `TimelineItem`, `TimelineDaySeparator` e `TimelineSection`) `TutorialCard` |
308
+ | **Navegação e layout** | `AppShell` `ErrorPageLayout` `NavigatorTile` `NavigatorTileGrid` `PageTitle` `PublicPageLayout` `Sidebar` `Topbar` (com `TopbarIconButton` e `TopbarSearchButton`) |
309
+ | **Gráficos e indicadores** | `ChartTimeSeries` `DonutChart` `HorizontalBarChart` `KpiCard` `KpiHero` `LineChart` `StackedBarChart` |
310
+ | **Diversos** | `CommandPalette` `DashboardBlock` `DSAccordion` `NotificationCenter` `WorkflowDesigner` |
311
+
312
+ ### Utilitários
313
+
314
+ `cn` (junta classes e resolve conflitos do Tailwind, incluindo as `humu-*`), `DefaultLink`, `SuspenseSkeleton`, `isMacOS`, `getShortcutLabel`, `getShortcutKeys`, `isImageFile` e `isPdfFile`. Os componentes exportam também o tipo das props (`ButtonProps`, `DataTableProps` etc.).
315
+
316
+ ## Migrando da 0.2.x
317
+
318
+ A 0.3.0 alinha a lib com a revisão do Figma de 04/11, corrige contraste e padroniza movimento, foco e estados. O detalhe está no [CHANGELOG](https://github.com/Inovanti-Bank/humu-ui/blob/main/packages/react/CHANGELOG.md#030). O que pede ação de quem consome:
319
+
320
+ 1. **Suba com versão exata e confira as telas.**
321
+
322
+ ```bash
323
+ npm install @humu-tech/ui@0.3.0 --save-exact
324
+ ```
325
+
326
+ 2. **`Combobox` e `MultiCombobox` foram refeitos.** A busca acontece no próprio campo, que agora é um `input` com `role="combobox"`:
327
+ - a `ref` aponta para o `input` (antes era um `button`); `focus()` continua funcionando;
328
+ - em testes, o valor escolhido é lido com `toHaveValue(...)` ou `getByDisplayValue(...)`, não mais com `toHaveTextContent(...)`; o placeholder com `getByPlaceholderText(...)`;
329
+ - o botão "Limpar seleção" fica ao lado do `input`, não dentro dele;
330
+ - o texto padrão de `emptyMessage` passou a ser "Nenhum resultado encontrado";
331
+ - no `MultiCombobox`, o indicador padrão da lista é o check à direita; para caixas de seleção, use `selectionIndicator="checkbox"`.
332
+
333
+ 3. **`Drawer.Footer` e `Dialog.Footer`**: como no Figma, as ações ficam todas à direita, com 16px entre elas (Cancelar e depois a ação principal). O `Drawer.Footer` tem a prop `status` para um texto acima delas. Quem forçava `sm:!justify-between` ou separava as ações pode tirar a classe.
334
+
335
+ 4. **Tamanhos do Figma**: campos com 52px no tamanho padrão (`md` igual a `lg`), bordas de 1.5px em campos, `Checkbox` e `Radio`, botões do `ConfirmDialog` com 44px e área do `FileUpload` com 152px. Revise layouts com altura fixa.
336
+
337
+ 5. **`Badge` abraça o conteúdo** (`w-fit`). Quem passava `w-fit` pode tirar a classe.
338
+
339
+ 6. **Filtros**: o gatilho do `FilterBar` passa a ser o chip "Filtros avançados", com a contagem ao lado. O novo `FilterToolbar` monta a barra das listagens com o `FilterBar` e os `ToggleChip` de filtros rápidos como filhos. Quem usa `hideTrigger` não é afetado.
340
+
341
+ 7. **Arquivo enviado**: `FileUpload` (com `label` e um arquivo) e `DocumentUploadCard` (tamanho padrão) mostram o arquivo na variante View do Figma, com "Trocar arquivo" e "Excluir arquivo". O nome acessível do botão de excluir passa a conter o texto visível ("Excluir arquivo (rótulo)"). A versão `compact` não muda.
342
+
343
+ 8. **Animações no preset**: o `tailwindcss-animate` passou a ser dependência da lib e está no preset, então o app pode tirá-lo do próprio `tailwind.config`. Os keyframes `slideDownAndFade`, `slideLeftAndFade`, `slideUpAndFade`, `slideRightAndFade`, `slideIn` e `slideOut` saíram do preset; quem os usa precisa declará-los no próprio config.
344
+
345
+ 9. **Visual que pode mudar seletores ou capturas**: `Checkbox` desabilitado com 50% de opacidade, `Toast` sem sombra, foco com contorno único (`outline-humu-focus`) e um só hover neutro em listas, linhas de tabela e botões de ícone. No `CommandPalette`, o item realçado continua na cor da marca e o ícone à direita (`meta`) passa a ter 18px.
346
+
347
+ 10. **Campos em grade**: `col-span-*` passado em `className` de um campo nunca chegou à grade, porque o `className` estiliza a caixa. Use a nova prop `containerClassName` (veja [Campos em grade](#campos-em-grade)).
348
+
349
+ 11. **Arquivos como no Figma**: o novo `FileViewCard` é o componente **View files** (`size="sm"` em linha, `size="lg"` em cartão), com "Ver arquivo", selo de status e campos extras. O `DocumentUploadCard` mostra o arquivo já enviado com ele (Large no tamanho padrão, Small no `compact`, só com o ícone de arquivo no lugar da miniatura) e aceita `sent.status`, `sent.fields` e `viewText`. O `FileUpload` ganha a variante **View no name** (`showFileInfo={false}`), e o `ImageUpload` passa a usar o mesmo cartão: área de envio do Figma vazia e, com imagem, miniatura de 100px com "Trocar arquivo" e "Excluir arquivo" empilhados.
350
+
351
+ 12. **Títulos de cartão em 20px negrito**: `Card.Title` passa de 16px seminegrito para 20px negrito, como o "Card title" do Figma, igual a `SectionCard`, `PanelCard` e `FormSection`.
352
+
353
+ ## Migrando da 0.1.x
354
+
355
+ A 0.2.0 traz o novo layout do Figma. Os nomes exportados continuam os mesmos, exceto os do tema. O resumo abaixo é o que pede ação de quem consome; o detalhe está no [CHANGELOG](https://github.com/Inovanti-Bank/humu-ui/blob/main/packages/react/CHANGELOG.md#020).
356
+
357
+ 1. **Suba com versão exata e confira as telas.** O visual muda em quase todos os componentes.
358
+
359
+ ```bash
360
+ npm install @humu-tech/ui@0.2.0 --save-exact
361
+ ```
362
+
363
+ 2. **Tema.** Saem `useDsV2Theme`, os tipos `DsV2Theme` e `ThemeMode` e as props `storageKey`, `ariaLabelLight` e `ariaLabelDark` do `ThemeToggle`.
364
+
365
+ | Antes | Depois |
366
+ | --- | --- |
367
+ | `useDsV2Theme()` | `useTheme().theme` |
368
+ | `DsV2Theme`, `ThemeMode` | `ResolvedTheme` (`'light' \| 'dark'`) ou `ThemePreference` (`'light' \| 'dark' \| 'system'`) |
369
+ | `<ThemeToggle storageKey="..." />` | `<ThemeProvider storageKey="...">` envolvendo o app, com `<ThemeToggle />` dentro dele |
370
+
371
+ O `ThemeToggle` e o `useTheme` passam a exigir o `ThemeProvider`. Adicione também o script do [passo 4](#4-tema-sem-piscar-script-no-head). A preferência salva nas chaves antigas (`ds-v2-theme-preference` e `theme`) é migrada para a chave do provider na primeira leitura.
372
+
373
+ 3. **Classes `v2-*` viram legado.** A lib passa a usar só tokens `humu-*`. As classes `v2-*` do preset e as variáveis `--v2-*` usadas por elas continuam funcionando, agora como apelidos, e **serão removidas numa versão futura**. Migre:
374
+
375
+ | Antes | Depois |
376
+ | --- | --- |
377
+ | `rounded-v2-*` | `rounded-humu-*` |
378
+ | `text-v2-{xs…6xl}` | `text-humu-size-{xs…6xl}` |
379
+ | `*-v2-auth-*` | `*-humu-auth-*` |
380
+ | `shadow-v2-2` | `shadow-humu-raised` |
381
+ | `duration-v2-*` / `ease-v2-*` | `duration-humu-*` / `ease-humu-*` |
382
+
383
+ Foram removidas as variáveis `--v2-spacing-*`, `--v2-font-weight-*`, `--v2-line-height-*`, `--v2-letter-spacing-*`, `--v2-font-family-sans`, `--v2-font-family-mono` (use `--humu-font-family-ibm-plex-sans`) e `--v2-elevation-0`.
384
+
385
+ 4. **`FilterBarV2` agora é `FilterBar`** (props em `FilterBarProps`). `FilterBarV2` e `FilterBarV2Props` seguem exportados como apelidos.
386
+
387
+ 5. **Ícones.** A lib trocou `@phosphor-icons/react` por `lucide-react`. Se o app importava Phosphor contando com a dependência da lib, instale-o por conta própria ou migre para lucide.
388
+
389
+ 6. **Nomes internos que mudaram**, só relevantes se o app os usava:
390
+ - camada CSS `@layer ds-v2` → `@layer humu`;
391
+ - classes do calendário `rdp-v2`, `rdp-v2-range`, `rdp-v2-single` → `rdp-humu`, `rdp-humu-range`, `rdp-humu-single`;
392
+ - rolagem da `Sidebar` `.ds-v2-sidebar-nav` → `.humu-sidebar-nav`;
393
+ - estado recolhido da `Sidebar` salvo em `humu-sidebar-collapsed` (o valor de `ds-v2-sidebar-collapsed` ainda é lido se a chave nova não existir).
173
394
 
174
- ## Changelog
395
+ 7. **Pode exigir ajuste em tela ou teste:**
396
+ - `FormAlert` passa a ser um `InfoBox` com `role="alert"` (mesmas variantes e props);
397
+ - `KpiCard` com `variant="danger"` é desenhado como `error`;
398
+ - `Dialog.Footer` e `Drawer.Footer` põem a primeira ação à esquerda e a última à direita; quem forçava `sm:!justify-between` pode tirar a classe;
399
+ - correções de acessibilidade (rótulos, papéis, contraste) podem mudar seletores de teste por `role` ou nome acessível.
175
400
 
176
- Versionado com [changesets](https://github.com/changesets/changesets). O histórico completo está no [`CHANGELOG.md`](https://github.com/Inovanti-Bank/humu-ui/blob/main/packages/react/CHANGELOG.md) do repositório.
401
+ 8. **React 19** passa a ser aceito, além do 18.
177
402
 
178
403
  ## Repositório
179
404
 
180
- [github.com/Inovanti-Bank/humu-ui](https://github.com/Inovanti-Bank/humu-ui) — monorepo com o DS, o Storybook e as configs compartilhadas.
405
+ [github.com/Inovanti-Bank/humu-ui](https://github.com/Inovanti-Bank/humu-ui): monorepo com o pacote, o Storybook e as configs compartilhadas. Licença MIT.
@@ -0,0 +1,112 @@
1
+ .rdp-root.rdp-humu {
2
+ --rdp-day-width: 36px;
3
+ --rdp-day-height: 36px;
4
+ --rdp-day_button-width: 36px;
5
+ --rdp-day_button-height: 36px;
6
+ --rdp-nav-height: 2rem;
7
+ --rdp-nav_button-width: 2rem;
8
+ --rdp-nav_button-height: 2rem;
9
+ --rdp-accent-color: var(--humu-background-brand-brand);
10
+ --rdp-accent-background-color: var(--humu-background-brand-brand);
11
+ --rdp-today-color: var(--humu-background-brand-brand);
12
+ --rdp-selected-border: 2px solid var(--humu-background-brand-brand);
13
+ --rdp-outside-opacity: 0.5;
14
+ --rdp-disabled-opacity: 0.4;
15
+ --rdp-weekday-text-transform: uppercase;
16
+ --rdp-weekday-opacity: 1;
17
+ margin: 0;
18
+ color: var(--humu-content-title);
19
+ }
20
+
21
+ .rdp-humu .rdp-day_button {
22
+ border-radius: var(--radius-md);
23
+ color: var(--humu-content-title);
24
+ }
25
+
26
+ .rdp-humu .rdp-day:not(.rdp-selected) .rdp-day_button:hover:not([disabled]) {
27
+ background-color: var(--humu-background-surface);
28
+ }
29
+
30
+ .rdp-humu .rdp-selected {
31
+ font-size: inherit;
32
+ }
33
+
34
+ .rdp-humu .rdp-day_button:focus-visible {
35
+ outline: 2px solid var(--humu-focus-ring);
36
+ outline-offset: 1px;
37
+ }
38
+
39
+ .rdp-humu .rdp-today .rdp-day_button {
40
+ color: var(--humu-background-brand-brand);
41
+ font-weight: 600;
42
+ }
43
+
44
+ .rdp-humu .rdp-outside .rdp-day_button {
45
+ color: var(--humu-content-body-text);
46
+ }
47
+
48
+ .rdp-humu .rdp-weekday {
49
+ color: var(--humu-content-subtitle);
50
+ font-weight: 500;
51
+ }
52
+
53
+ .rdp-humu .rdp-caption_label {
54
+ color: var(--humu-content-title);
55
+ font-weight: 600;
56
+ }
57
+
58
+ .rdp-humu .rdp-button_previous,
59
+ .rdp-humu .rdp-button_next {
60
+ display: inline-flex;
61
+ align-items: center;
62
+ justify-content: center;
63
+ border: 1px solid var(--humu-border-default);
64
+ border-radius: 9999px;
65
+ background-color: transparent;
66
+ color: var(--humu-content-title);
67
+ transition: background-color var(--humu-duration-fast) var(--humu-easing-in-out);
68
+ }
69
+
70
+ .rdp-humu .rdp-button_previous:not([aria-disabled='true']):hover,
71
+ .rdp-humu .rdp-button_next:not([aria-disabled='true']):hover {
72
+ background-color: var(--humu-background-surface);
73
+ }
74
+
75
+ .rdp-humu .rdp-button_previous:focus-visible,
76
+ .rdp-humu .rdp-button_next:focus-visible {
77
+ outline: 2px solid var(--humu-focus-ring);
78
+ outline-offset: 1px;
79
+ }
80
+
81
+ .rdp-humu .rdp-button_previous[aria-disabled='true'],
82
+ .rdp-humu .rdp-button_next[aria-disabled='true'] {
83
+ opacity: 0.4;
84
+ }
85
+
86
+ .rdp-humu .rdp-chevron {
87
+ width: 1rem;
88
+ height: 1rem;
89
+ fill: currentColor;
90
+ }
91
+
92
+ .rdp-humu-single .rdp-day_button {
93
+ border-radius: 9999px;
94
+ }
95
+
96
+ .rdp-humu-single .rdp-today:not(.rdp-selected) .rdp-day_button {
97
+ box-shadow: inset 0 0 0 1.5px var(--humu-background-brand-brand);
98
+ }
99
+
100
+ .rdp-humu-single .rdp-selected .rdp-day_button {
101
+ background-color: var(--humu-background-brand-brand);
102
+ color: var(--humu-content-on-brand);
103
+ border: none;
104
+ font-weight: 600;
105
+ }
106
+
107
+ @media (prefers-reduced-motion: reduce) {
108
+ .rdp-humu .rdp-button_previous,
109
+ .rdp-humu .rdp-button_next {
110
+ transition: none;
111
+ }
112
+ }